Skip to content

Relay Language

Håkon Olav Torvik edited this page Oct 24, 2026 · 1 revision

Relay Language

Part of the Relay design spec. See the contents.

06 · Relay language

The hard part

Carried over from chainlang, with one extension: a named block can be used as a number in duration arithmetic.

relay      = "(" element (sep element)* ")"
sep        = "," | NEWLINE                // # starts a comment, to the end of the line
element    = ref | dur_expr [STRING] | call | relay   // STRING: optional label, e.g. 5m "stretch"
ref        = IDENT                      // bare name: a reference step, keeps its identity and sound
call       = "repeat" "(" int_expr "," element ")"
           | "range" "(" num_expr "," num_expr ["," num_expr] ")"  // fractional allowed
dur_expr   = dur_term (("+" | "-") dur_term)*
dur_term   = literal | int_expr | ref_value
ref_value  = IDENT                      // inside arithmetic: that block's total duration  NEW
literal    = (NUMBER "h")? (NUMBER "m")? (NUMBER "s")?
int_expr   = int_term (("+" | "-") int_term)*    // bare number = minutes
int_term   = NUMBER | "RANDOM" "(" int_expr "," int_expr ")"
           | ("MINUTE" | "HOUR" | "SECOND") "(" "NOW" (("+"|"-") literal)? ")"
           | "(" int_expr ")"
num_expr   = int_expr with decimal NUMBERs allowed  // minutes, rounded to whole seconds

Rules

  • A bare name is a reference: (Test2) runs Test2 as a step, with its own sound. References are resolved when a run starts, so retuning Test2 updates every relay that uses it. Once started, a run is a frozen snapshot.
  • A name inside arithmetic is a value new: with Test2 = 10m, (Test2 - 2) is a relay of one anonymous 8m step. Test2 + 30s also works. A relay name used this way contributes its total duration. A result ≤ 0 is an error. Sound: with exactly one name in the expression, the step inherits that block's sound. Otherwise it uses the relay default.
  • range(a, b, step) expands to anonymous steps of a, a+step, … minutes, including b when it lands on a step (range(1, 3) is 1, 2, 3; range(1, 4, 2) is 1, 3), which reads naturally to non-programmers. Direction-aware; fractional values allowed: range(1, 3, 0.5) gives 1m, 1m30s, 2m, 2m30s, 3m. arange is dropped changed.
  • An anonymous step can carry a display-only label, written 5m "stretch", which is shown at ring time. new
  • NOW is evaluated once, when the run starts.
  • # starts a comment that runs to the end of the line (except inside a quoted label). new

Worked examples

Block Definition Total
Work Timer · 25m · sound: sadsong 25m
Break Timer · 5m · sound: happysong 5m
Session Relay · repeat(4, (Work, Break)) · seamless 2h
Workday Relay · (Session, 30, Session, 60, Work) 5h 55m
Wake Relay · (Nudge, Nudge, Louder, Loud, Siren), five 5m timers with escalating sounds · interaction required · scheduled Mon–Fri 06:30 25m

Wake is the snooze-less wake-up call. Each boundary rings with the ending step's sound until you tap Continue, which starts the next five minutes. It's snooze with character, and Stop relay ends it when you're actually up.

Safety limits keep

Limit Default Configurable
Reference graph is a DAG (no self-containment) always No
Max reference depth 20 No
Max resolved plan size, counted across all references 300 steps Yes, hard ceiling 1000
Max repeat/range multiplier 200 No
Max expression length 2000 chars No
Long-relay warning above 24 h Yes

What each check guards against

Check When Catches
Cycle check over the whole reference graph Every save and rename of a relay or timer Self-containment, direct (R1 → R1) or indirect (R1 → R2 → R1), with the path in the error
Shape check on one script's AST Every keystroke and save, before expansion Nesting bombs inside one script (repeat(200, repeat(200, …))). It treats each reference as one opaque step, so on its own it does not catch cycles or big referenced blocks
Plan check on the fully expanded plan Run start, and in the editor preview Totals across references (repeat(200, BigRelay)) and max depth. It also stops expanding if the depth limit is hit, so a cycle that slips past save (a bad import, say) fails safely instead of overflowing the stack new

v0.5 gap: only the first two existed. The run engine expanded referenced relays recursively without re-checking the combined size or depth, so a relay made of big referenced relays could exceed the plan cap.


Relay · spec v1.0 · clean-restart baseline, update as screens get built

Clone this wiki locally