Traits

States and transitions

lolo

trait Approval -> Expense [interaction, instance] {
  initial: draft

  state draft {
    SUBMIT -> submitted when (> @entity.amount 0)
      (render-ui main { type: typography, content: "Submitted", variant: h4 })
  }

  state submitted {
    APPROVE -> approved when (<= @entity.amount 500)
      (set @entity.note "Approved")
    REJECT -> rejected
      (set @entity.note "Rejected")
  }
}

EVENT -> target is a transition. Effects follow on their own lines and run in order.
when (…) is a guard: if it is false, the event is refused and nothing changes.
The first state is initial unless initial: names another.
Each transition stands alone. Two transitions that differ only in their source state are written twice; nothing is shared implicitly.
A state with no way out is an error unless the program means it to end there.

The header's bracket holds a category (interaction, lifecycle, integration, …) and instance (one state machine per entity row, the default) or collection (one for the whole entity).

Here is the full approval flow running. Try submitting a claim over 500 EUR and approving it; the guard refuses:

State machine

Approval

on Expense · states: 4 · transitions: 7

emitsMOVED

INIT

RAISE

SUBMIT

(> @entity.amount 0)

APPROVE

(<= @entity.amount 500)

REJECT

NEW_CLAIM

REVISE

nowdraft

submitted

approved

rejected

Running live

Draft claim: EUR

The same trait as a state machine: each box is a state, each arrow an event that moves it, and the icons on an arrow are the effects that event runs. Hover a symbol to see what it does. How to read AVL

std-orb-docex-expense.lolololo

app std-orb-docex-expense "1.0.0"
"std-orb-docex-expense — an approval flow: four states, a guard on the amount, and a rule the shape of the program enforces."
orbital ExpenseOrbital {
  entity Expense [runtime] {
    id : string!
    amount : number = 120
    note : string = ""
  }

  trait Approval -> Expense [interaction, instance] {
    initial: draft

    state draft {
      INIT -> draft
        (render-ui main { type: stack, direction: vertical, gap: sm, children: [
          { type: typography, content: (str/concat "Draft claim: " @entity.amount " EUR"), variant: h4 },
          { type: stack, direction: horizontal, gap: sm, children: [
            { type: button, label: "Add 50 EUR", action: RAISE, variant: ghost },
            { type: button, label: "Submit", action: SUBMIT, variant: primary }
          ] }
        ] })
      RAISE -> draft
        (emit MOVED { event: "RAISE" })
        (set @entity.amount (+ @entity.amount 50))
      SUBMIT -> submitted when (> @entity.amount 0)
        (emit MOVED { event: "SUBMIT" })
        (render-ui main { type: stack, direction: vertical, gap: sm, children: [
          { type: typography, content: (str/concat "Submitted: " @entity.amount " EUR"), variant: h4 },
          { type: typography, content: "Claims over 500 EUR cannot be approved here.", variant: small, color: muted },
          { type: stack, direction: horizontal, gap: sm, children: [
            { type: button, label: "Approve", action: APPROVE, variant: primary },
            { type: button, label: "Reject", action: REJECT, variant: secondary }
          ] }
        ] })
    }

    state submitted {
      APPROVE -> approved when (<= @entity.amount 500)
        (emit MOVED { event: "APPROVE" })
        (set @entity.note "Approved")
        (render-ui main { type: stack, direction: vertical, gap: sm, children: [
          { type: badge, label: "Approved", variant: success },
          { type: button, label: "New claim", action: NEW_CLAIM, variant: ghost }
        ] })
      REJECT -> rejected
        (emit MOVED { event: "REJECT" })
        (set @entity.note "Rejected")
        (render-ui main { type: stack, direction: vertical, gap: sm, children: [
          { type: badge, label: "Rejected", variant: error },
          { type: button, label: "Revise", action: REVISE, variant: primary }
        ] })
    }

    state approved {
      NEW_CLAIM -> draft
        (emit MOVED { event: "NEW_CLAIM" })
        (set @entity.amount 120)
        (render-ui main { type: stack, direction: vertical, gap: sm, children: [
          { type: typography, content: (str/concat "Draft claim: " @entity.amount " EUR"), variant: h4 },
          { type: stack, direction: horizontal, gap: sm, children: [
            { type: button, label: "Add 50 EUR", action: RAISE, variant: ghost },
            { type: button, label: "Submit", action: SUBMIT, variant: primary }
          ] }
        ] })
    }

    state rejected {
      REVISE -> draft
        (emit MOVED { event: "REVISE" })
        (render-ui main { type: stack, direction: vertical, gap: sm, children: [
          { type: typography, content: (str/concat "Draft claim: " @entity.amount " EUR"), variant: h4 },
          { type: stack, direction: horizontal, gap: sm, children: [
            { type: button, label: "Add 50 EUR", action: RAISE, variant: ghost },
            { type: button, label: "Submit", action: SUBMIT, variant: primary }
          ] }
        ] })
    }

    emits {
      MOVED -> external {
        event : string!
      }
        @description "Each move names the event it took, so the diagram beside the demo can follow it."
    }
  }

  page "/expenses" -> Approval
}

What happens when APPROVE fires:

submittedAPPROVE

→

approved

GuardThe transition only fires when this check is true.

(<= @entity.amount 500)

Effects (2)What runs, in order, when the transition fires.

(set @entity.note "Approved")

Effects

Effect	What it does
`(set @entity.f v)`	Assign a field. The only assignment form.
`(fetch E { … })` / `(persist create\|update\|delete E data)`	Read and write stored rows.
`(emit EVENT { … })`	Broadcast a declared event.
`(render-ui slot { … })`	Draw a pattern tree into a slot (`main`, `modal`, `drawer`, `toast`, …); `null` clears it.
`(navigate "/path")` / `(navigate-back)`	Move to another page.
`(notify info "Saved")`	Show a toast.
`(call-service provider action { … })`	Call an integration (LLM, email, payments, …).

Operators compute values: (+ a b), (str/concat …), (array/map xs (fn x …)). They are all prefix; there is no infix. The operator reference lists every one.

Sigil	Meaning
`@entity.field`	A field of the bound entity
`?field`	A field of the incoming event's payload
`@config.key`	A value from the trait's `config`
`@user.field`	The signed-in viewer
`now` / `state`	This dispatch's timestamp / the current state

Sigil

Meaning

@entity.field

A field of the bound entity

?field

A field of the incoming event's payload

@config.key

A value from the trait's config

@user.field

The signed-in viewer

now / state

This dispatch's timestamp / the current state

Emits and listens

A trait declares what it broadcasts, and another trait declares what it reacts to. Here the dial emits TARGET_CHANGED, and the status listens for it and maps it to its own SHOW event:

State machine

Dial

on Thermostat · states: 1 · transitions: 3

emitsTARGET_CHANGEDemitsMOVED

INIT

UP

(< @entity.target 28)

DOWN

(> @entity.target 16)

nowidle

Status

on Thermostat · states: 1 · transitions: 2

listensTARGET_CHANGEDemitsMOVED

INIT

SHOW

nowwatching

Running live

21 °C

Set a temperature between 16 and 28 °C.

std-orb-docex-thermostat.lolololo

app std-orb-docex-thermostat "1.0.0"
"std-orb-docex-thermostat — two traits in one orbital: one guards and emits, the other listens and reacts."
orbital ThermostatOrbital {
  entity Thermostat [runtime, shared] {
    id : string!
    target : number = 21
  }

  trait Dial -> Thermostat [interaction, instance] {
    initial: idle

    state idle {
      INIT -> idle
        (render-ui main { type: stack, direction: horizontal, gap: md, align: center, children: [
          { type: button, label: "Colder", action: DOWN, variant: secondary },
          { type: typography, content: (str/concat @entity.target " °C"), variant: h2 },
          { type: button, label: "Warmer", action: UP, variant: secondary }
        ] })
      UP -> idle when (< @entity.target 28)
        (emit MOVED { event: "UP" })
        (set @entity.target (+ @entity.target 1))
        (emit TARGET_CHANGED { target: @entity.target })
      DOWN -> idle when (> @entity.target 16)
        (emit MOVED { event: "DOWN" })
        (set @entity.target (- @entity.target 1))
        (emit TARGET_CHANGED { target: @entity.target })
    }

    emits {
      TARGET_CHANGED {
        target : number!
      }
        @description "The target temperature moved."
      MOVED -> external {
        event : string!
      }
        @description "Each move names the event it took, so the diagram beside the demo can follow it."
    }
  }

  trait Status -> Thermostat [interaction, instance] {
    initial: watching

    state watching {
      INIT -> watching
        (render-ui main { type: typography, content: "Set a temperature between 16 and 28 °C.", variant: body, color: muted })
      SHOW -> watching
        (emit MOVED { event: "SHOW" })
        (render-ui main { type: badge, label: (if (> ?target 23) "Heating up" (if (< ?target 19) "Cooling down" "Comfortable")), variant: (if (> ?target 23) warning (if (< ?target 19) info success)) })
    }

    emits {
      MOVED -> external {
        event : string!
      }
        @description "Each move names the event it took, so the diagram beside the demo can follow it."
    }

    listens {
      Dial.TARGET_CHANGED -> SHOW
      SHOW {
        target : number!
      }
    }
  }

  page "/thermostat" -> Dial, Status
}

What happens when UP fires:

idleUP

→

idle

GuardThe transition only fires when this check is true.

(< @entity.target 28)

Effects (2)What runs, in order, when the transition fires.

(set @entity.target (+ @entity.target 1))

(emit "TARGET_CHANGED" { target: @entity.target })

lolo

emits {
  TARGET_CHANGED {
    target : number!
  }
}

listens {
  Dial.TARGET_CHANGED -> SHOW
  SHOW {
    target : number!
  }
}

internal events (the default) stay within the orbital; external events cross to other orbitals and must declare their payload. Trait.EVENT resolves within the listener's own orbital; across orbitals, write Orbital.Trait.EVENT. Cross-orbital events shows both.

Ticks

A tick is a periodic effect. It runs only while its when holds, so a tick bound to a state stops the moment the trait leaves it:

State machine

Timing

on Stopwatch · states: 2 · transitions: 4

emitsMOVED

INIT

START

RESET

STOP

nowstopped

running

Running live

s

std-orb-docex-stopwatch.lolololo

app std-orb-docex-stopwatch "1.0.0"
"std-orb-docex-stopwatch — a tick: a periodic effect that runs only while the trait is in the running state."
orbital StopwatchOrbital {
  entity Stopwatch [runtime] {
    id : string!
    seconds : number = 0
  }

  trait Timing -> Stopwatch [interaction, instance] {
    initial: stopped

    state stopped {
      INIT -> stopped
        (render-ui main { type: stack, direction: horizontal, gap: md, align: center, children: [
          { type: typography, content: (str/concat @entity.seconds " s"), variant: h2 },
          { type: button, label: "Start", action: START, variant: primary },
          { type: button, label: "Reset", action: RESET, variant: ghost }
        ] })
      START -> running
        (emit MOVED { event: "START" })
        (render-ui main { type: stack, direction: horizontal, gap: md, align: center, children: [
          { type: typography, content: (str/concat @entity.seconds " s"), variant: h2 },
          { type: button, label: "Stop", action: STOP, variant: secondary }
        ] })
      RESET -> stopped
        (emit MOVED { event: "RESET" })
        (set @entity.seconds 0)
    }

    state running {
      STOP -> stopped
        (emit MOVED { event: "STOP" })
        (render-ui main { type: stack, direction: horizontal, gap: md, align: center, children: [
          { type: typography, content: (str/concat @entity.seconds " s"), variant: h2 },
          { type: button, label: "Start", action: START, variant: primary },
          { type: button, label: "Reset", action: RESET, variant: ghost }
        ] })
    }

    emits {
      MOVED -> external {
        event : string!
      }
        @description "Each move names the event it took, so the diagram beside the demo can follow it."
    }

    ticks {
      second every 1s when (= state "running")
        (set @entity.seconds (+ @entity.seconds 1))
    }
  }

  page "/stopwatch" -> Timing
}

What happens when START fires:

stoppedSTART

→

running

Effects (1)What runs, in order, when the transition fires.

lolo

▼ticks {
  second every 1s when (= state "running")
    (set @entity.seconds (+ @entity.seconds 1))
}

Intervals are milliseconds, a duration (5s, 1m, 1h, 1d) or a cron string. A tick on a stored entity runs on the server while a page holds the trait; tag it [background] to run with nobody watching.

Orb

Orb

Traits

States and transitions

Draft claim: EUR

→

Effects

Bindings

Emits and listens

21 °C

→

Ticks

s

→

Config

Next

Orb