feat(lang): 27.1 - a state machine as data: @Machine(Record.field) on a registry of transitions

A registry marked `@Machine(Deer.mood)` is the transitions of a machine over that enum field of the
records a state's Table<Deer> holds. Its record has from and to (the enum's variants), on: string (an
action's name, "" for a transition the tick asks), guard: fn(Row<Deer>, reads...) -> bool and
enter: fn(Row<Deer>, reads...) -> void; the states are the enum's variants and the start is the
field's default. The rows are data (an .lres or defs), the names the studio already edits.

Written by the compiler (machines.ludic, machines_write.ludic): for each action an `on` names, a row
reducer in the registry's file (named ..__machine__DeerSteps, so it sits beside the program's own
row reducer on the same action, after it): the row's state, the first transition from it on that
action whose guard passes, the field set, enter run - guards and enters called by name. When a row
leaves a state on a guard alone, `state DeerStepsMachine` (the kept row view) and
deer_steps_tick(m: mut DeerStepsMachine, s: mut Herd, reads...), one transition a row a tick.
Nothing allocates.

The table is the whole machine: the field written anywhere else - an assignment, or a `machine`
block's become over it - is a type error (check_stmt.ludic, ck_machine_write). Guards and enters take
the row first, are the record's module's, keep a row reducer's rules (and may be handed the row);
a guard writes nothing through it. The graph is checked, each error at its row (in the .lres when
the rows are there): a state never reached from the start, a state with no way out, an `on` naming
no action or an action with no @Target, a self-transition with no guard, two ways out of a state on
one trigger behind an unguarded first. Also refused: @Machine off a registry, a field that is not a
plain enum with a default, a @Column field, no table (or two) of the record, a transitions record of
another shape, a machine outside its table's state's module.

ludic schema's code section gains `machines` (registry, record, field, enum, table, start, states,
actions, tick, module, at); ludic deps names a machine's reducer `reducer Deer in Herd.deer on Spook
(machine DeerSteps)`. vocab @Machine; docs annot-machine, kw-machine; LANGUAGE.md "A machine as
data"; examples actions/machine (+ deer_steps.lres) and ten rejects; test.ludic feat, reject and
schema cases (not run); changes/machines.md. Reseeded; bootstrap-cfree fixpoint holds (317642
lines); Maroon Lake's `ludic build --check` is clean against this tree.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

examples/actions/deer_steps.lres

@@ -0,0 +1,6 @@
+# deer_steps.lres - Machines' DeerSteps: how a deer's mood changes (examples/actions/machine.ludic)
+startled { from: Mood.Calm, to: Mood.Wary, on: "Spook", enter: fn deer_startle }
+bolts { from: Mood.Wary, to: Mood.Fled, on: "Spook", guard: fn deer_afraid, enter: fn deer_bolt }
+uneasy { from: Mood.Wary, to: Mood.Wary, on: "Spook", guard: fn deer_calm_enough, enter: fn deer_startle }
+settles { from: Mood.Wary, to: Mood.Calm, guard: fn deer_settled }
+home { from: Mood.Fled, to: Mood.Calm, guard: fn deer_away, enter: fn deer_rest }

examples/actions/machine.ludic

@@ -0,0 +1,53 @@
+# machine.ludic - 27.1: a state machine as data. Deer.mood is the state, and the registry marked
+# @Machine(Deer.mood) is its transitions, one row each in deer_steps.lres: from, to, the action it
+# is `on` ("" for one the tick asks), a guard and an enter. The compiler writes a row reducer for
+# each action a row names and deer_steps_tick for the rest; nothing else writes Deer.mood.
+#
+# Running it prints:  0 0 1 1
+import "ludic.base"
+program Machines {
+  numbers float
+  enum Mood { Calm, Wary, Fled }
+  property Deer {
+    mood: Mood = Mood.Calm           # the start
+    fear: int = 0
+    x: float = 0.0
+  }
+  state Herd {
+    deer: Table<Deer> = null
+    far: float = 10.0
+  }
+  action Spook { @Target who: int = -1 }
+  property DeerStep {
+    from: Mood = Mood.Calm
+    to: Mood = Mood.Calm
+    on: string = ""
+    guard: fn(Row<Deer>, Herd) -> bool = null
+    enter: fn(Row<Deer>, Herd) -> void = null
+  }
+  @Machine(Deer.mood) registry DeerSteps of DeerStep as DS from "deer_steps.lres"
+
+  function deer_afraid(r: Row<Deer>, h: Herd) -> bool { return r.rec.fear >= 2 }
+  function deer_calm_enough(r: Row<Deer>, h: Herd) -> bool { return r.rec.fear < 2 }
+  function deer_settled(r: Row<Deer>, h: Herd) -> bool { return r.rec.fear == 0 }
+  function deer_away(r: Row<Deer>, h: Herd) -> bool { return r.rec.x > h.far }
+  function deer_startle(r: mut Row<Deer>, h: Herd) -> void { r.rec.fear += 1 }
+  function deer_bolt(r: mut Row<Deer>, h: Herd) -> void { r.rec.x += 20.0 }
+  function deer_rest(r: mut Row<Deer>, h: Herd) -> void { r.rec.fear = 0 }
+
+  entry (h: mut Herd, m: mut DeerStepsMachine) {
+    let tb: Table<Deer> = table_new(0, 0)
+    h.deer = tb
+    let a = tb_add(tb, new Deer)
+    let b = tb_add(tb, new Deer)
+    dispatch Spook { who: a }        # Calm -> Wary, fear 1
+    dispatch Spook { who: a }        # Wary, not afraid yet: stays, fear 2
+    dispatch Spook { who: a }        # afraid: Wary -> Fled, 20 m off
+    dispatch Spook { who: b }        # Calm -> Wary, fear 1
+    drain_actions()
+    deer_steps_tick(m, h)            # a is far enough: Fled -> Calm, fear 0; b is still uneasy
+    let ra = tb_rec(tb, tb_row(tb, a))
+    let rb = tb_rec(tb, tb_row(tb, b))
+    print(`{int(ra.mood)} {ra.fear} {int(rb.mood)} {rb.fear}`)
+  }
+}

examples/rejected/machine_ambiguous.ludic

@@ -0,0 +1,22 @@
+# 27.1: two ways out of a state on one trigger: the first has a guard
+import "ludic.base"
+program MachineAmbiguous {
+  enum Mood { Calm, Wary }
+  property Deer { mood: Mood = Mood.Calm, fear: int = 0 }
+  state Herd { deer: Table<Deer> = null }
+  action Spook { @Target who: int = -1 }
+  action Shout { loud: int = 1 }
+  property DeerStep {
+    from: Mood = Mood.Calm
+    to: Mood = Mood.Calm
+    on: string = ""
+    guard: fn(Row<Deer>, Herd) -> bool = null
+    enter: fn(Row<Deer>, Herd) -> void = null
+  }
+  @Machine(Deer.mood) registry DeerSteps of DeerStep
+  function deer_afraid(r: Row<Deer>, h: Herd) -> bool { return r.rec.fear > 1 }
+  def DeerSteps startled { from: Mood.Calm, to: Mood.Wary, on: "Spook" }
+  def DeerSteps settles { from: Mood.Wary, to: Mood.Calm, on: "Spook" }
+  def DeerSteps stays { from: Mood.Wary, to: Mood.Calm, on: "Spook", guard: fn deer_afraid }
+  entry { print(1) }
+}

examples/rejected/machine_field_written.ludic

@@ -0,0 +1,25 @@
+# 27.1: a machine's field changes only by a transition in its table
+import "ludic.base"
+program MachineFieldWritten {
+  enum Mood { Calm, Wary }
+  property Deer { mood: Mood = Mood.Calm, fear: int = 0 }
+  state Herd { deer: Table<Deer> = null }
+  action Spook { @Target who: int = -1 }
+  action Shout { loud: int = 1 }
+  property DeerStep {
+    from: Mood = Mood.Calm
+    to: Mood = Mood.Calm
+    on: string = ""
+    guard: fn(Row<Deer>, Herd) -> bool = null
+    enter: fn(Row<Deer>, Herd) -> void = null
+  }
+  @Machine(Deer.mood) registry DeerSteps of DeerStep
+  function deer_afraid(r: Row<Deer>, h: Herd) -> bool { return r.rec.fear > 1 }
+  def DeerSteps startled { from: Mood.Calm, to: Mood.Wary, on: "Spook" }
+  def DeerSteps settles { from: Mood.Wary, to: Mood.Calm, guard: fn deer_afraid }
+  function calm_all(h: mut Herd) -> void {
+    let d = tb_rec(h.deer, 0)
+    d.mood = Mood.Calm
+  }
+  entry { print(1) }
+}

examples/rejected/machine_guard_writes.ludic

@@ -0,0 +1,25 @@
+# 27.1: a guard asks and changes nothing
+import "ludic.base"
+program MachineGuardWrites {
+  enum Mood { Calm, Wary }
+  property Deer { mood: Mood = Mood.Calm, fear: int = 0 }
+  state Herd { deer: Table<Deer> = null }
+  action Spook { @Target who: int = -1 }
+  action Shout { loud: int = 1 }
+  property DeerStep {
+    from: Mood = Mood.Calm
+    to: Mood = Mood.Calm
+    on: string = ""
+    guard: fn(Row<Deer>, Herd) -> bool = null
+    enter: fn(Row<Deer>, Herd) -> void = null
+  }
+  @Machine(Deer.mood) registry DeerSteps of DeerStep
+  function deer_afraid(r: Row<Deer>, h: Herd) -> bool { return r.rec.fear > 1 }
+  def DeerSteps startled { from: Mood.Calm, to: Mood.Wary, on: "Spook", guard: fn deer_nervous }
+  def DeerSteps settles { from: Mood.Wary, to: Mood.Calm, guard: fn deer_afraid }
+  function deer_nervous(r: Row<Deer>, h: Herd) -> bool {
+    r.rec.fear += 1
+    return true
+  }
+  entry { print(1) }
+}

examples/rejected/machine_no_way_out.ludic

@@ -0,0 +1,22 @@
+# 27.1: every state of a machine has a way out
+import "ludic.base"
+program MachineNoWayOut {
+  enum Mood { Calm, Wary, Fled }
+  property Deer { mood: Mood = Mood.Calm, fear: int = 0 }
+  state Herd { deer: Table<Deer> = null }
+  action Spook { @Target who: int = -1 }
+  action Shout { loud: int = 1 }
+  property DeerStep {
+    from: Mood = Mood.Calm
+    to: Mood = Mood.Calm
+    on: string = ""
+    guard: fn(Row<Deer>, Herd) -> bool = null
+    enter: fn(Row<Deer>, Herd) -> void = null
+  }
+  @Machine(Deer.mood) registry DeerSteps of DeerStep
+  function deer_afraid(r: Row<Deer>, h: Herd) -> bool { return r.rec.fear > 1 }
+  def DeerSteps startled { from: Mood.Calm, to: Mood.Wary, on: "Spook" }
+  def DeerSteps settles { from: Mood.Wary, to: Mood.Calm, guard: fn deer_afraid }
+  def DeerSteps bolts { from: Mood.Wary, to: Mood.Fled, on: "Spook", guard: fn deer_afraid }
+  entry { print(1) }
+}

examples/rejected/machine_not_enum.ludic

@@ -0,0 +1,10 @@
+# 27.1: a machine's state is a plain enum field with a start
+import "ludic.base"
+program MachineNotEnum {
+  property Deer { mood: int = 0 }
+  state Herd { deer: Table<Deer> = null }
+  property DeerStep { from: int = 0, to: int = 0, on: string = "" }
+  @Machine(Deer.mood) registry DeerSteps of DeerStep
+  def DeerSteps a { from: 0, to: 1 }
+  entry { print(1) }
+}

examples/rejected/machine_not_registry.ludic

@@ -0,0 +1,8 @@
+# 27.1: @Machine marks a registry of transitions
+import "ludic.base"
+program MachineNotRegistry {
+  enum Mood { Calm, Wary }
+  property Deer { mood: Mood = Mood.Calm }
+  @Machine(Deer.mood) property DeerStep { from: Mood = Mood.Calm }
+  entry { print(1) }
+}

examples/rejected/machine_on_no_target.ludic

@@ -0,0 +1,21 @@
+# 27.1: a transition's action names the row it moves (@Target)
+import "ludic.base"
+program MachineOnNoTarget {
+  enum Mood { Calm, Wary }
+  property Deer { mood: Mood = Mood.Calm, fear: int = 0 }
+  state Herd { deer: Table<Deer> = null }
+  action Spook { @Target who: int = -1 }
+  action Shout { loud: int = 1 }
+  property DeerStep {
+    from: Mood = Mood.Calm
+    to: Mood = Mood.Calm
+    on: string = ""
+    guard: fn(Row<Deer>, Herd) -> bool = null
+    enter: fn(Row<Deer>, Herd) -> void = null
+  }
+  @Machine(Deer.mood) registry DeerSteps of DeerStep
+  function deer_afraid(r: Row<Deer>, h: Herd) -> bool { return r.rec.fear > 1 }
+  def DeerSteps startled { from: Mood.Calm, to: Mood.Wary, on: "Shout" }
+  def DeerSteps settles { from: Mood.Wary, to: Mood.Calm, guard: fn deer_afraid }
+  entry { print(1) }
+}

examples/rejected/machine_on_unknown.ludic

@@ -0,0 +1,21 @@
+# 27.1: a transition's `on` names an action
+import "ludic.base"
+program MachineOnUnknown {
+  enum Mood { Calm, Wary }
+  property Deer { mood: Mood = Mood.Calm, fear: int = 0 }
+  state Herd { deer: Table<Deer> = null }
+  action Spook { @Target who: int = -1 }
+  action Shout { loud: int = 1 }
+  property DeerStep {
+    from: Mood = Mood.Calm
+    to: Mood = Mood.Calm
+    on: string = ""
+    guard: fn(Row<Deer>, Herd) -> bool = null
+    enter: fn(Row<Deer>, Herd) -> void = null
+  }
+  @Machine(Deer.mood) registry DeerSteps of DeerStep
+  function deer_afraid(r: Row<Deer>, h: Herd) -> bool { return r.rec.fear > 1 }
+  def DeerSteps startled { from: Mood.Calm, to: Mood.Wary, on: "Spok" }
+  def DeerSteps settles { from: Mood.Wary, to: Mood.Calm, guard: fn deer_afraid }
+  entry { print(1) }
+}

examples/rejected/machine_self_no_guard.ludic

@@ -0,0 +1,22 @@
+# 27.1: a transition from a state to itself has a guard
+import "ludic.base"
+program MachineSelfNoGuard {
+  enum Mood { Calm, Wary }
+  property Deer { mood: Mood = Mood.Calm, fear: int = 0 }
+  state Herd { deer: Table<Deer> = null }
+  action Spook { @Target who: int = -1 }
+  action Shout { loud: int = 1 }
+  property DeerStep {
+    from: Mood = Mood.Calm
+    to: Mood = Mood.Calm
+    on: string = ""
+    guard: fn(Row<Deer>, Herd) -> bool = null
+    enter: fn(Row<Deer>, Herd) -> void = null
+  }
+  @Machine(Deer.mood) registry DeerSteps of DeerStep
+  function deer_afraid(r: Row<Deer>, h: Herd) -> bool { return r.rec.fear > 1 }
+  def DeerSteps startled { from: Mood.Calm, to: Mood.Wary, on: "Spook" }
+  def DeerSteps settles { from: Mood.Wary, to: Mood.Calm, guard: fn deer_afraid }
+  def DeerSteps again { from: Mood.Wary, to: Mood.Wary, on: "Spook" }
+  entry { print(1) }
+}

examples/rejected/machine_unreachable.ludic

@@ -0,0 +1,22 @@
+# 27.1: every state of a machine is reached from its start
+import "ludic.base"
+program MachineUnreachable {
+  enum Mood { Calm, Wary, Fled }
+  property Deer { mood: Mood = Mood.Calm, fear: int = 0 }
+  state Herd { deer: Table<Deer> = null }
+  action Spook { @Target who: int = -1 }
+  action Shout { loud: int = 1 }
+  property DeerStep {
+    from: Mood = Mood.Calm
+    to: Mood = Mood.Calm
+    on: string = ""
+    guard: fn(Row<Deer>, Herd) -> bool = null
+    enter: fn(Row<Deer>, Herd) -> void = null
+  }
+  @Machine(Deer.mood) registry DeerSteps of DeerStep
+  function deer_afraid(r: Row<Deer>, h: Herd) -> bool { return r.rec.fear > 1 }
+  def DeerSteps startled { from: Mood.Calm, to: Mood.Wary, on: "Spook" }
+  def DeerSteps settles { from: Mood.Wary, to: Mood.Calm, guard: fn deer_afraid }
+  def DeerSteps home { from: Mood.Fled, to: Mood.Calm, guard: fn deer_afraid }
+  entry { print(1) }
+}