feat: eventless (Always) transitions, Raise internal events, state Tags (#57)

Adds three XState-class primitives to the core engine:

- Always(): eventless transitions evaluated on entry and after every
  transition; first enabled (guard-passing) wins, target required.
- Raise(): enqueue internal events processed in the same macrostep,
  before control returns and before any external event.
- Tags()/HasTag(): lightweight state categorization queryable across
  the active leaf, ancestors, and parallel-region leaves.

A bounded macrostep settles eventless transitions and drains the raised
event queue after Start()/Send(). All three round-trip through the
Native JSON and XState v5 exporters (always, tags, xstate.raise), closing
the previously-missing pieces of the Stately Studio export story.

Builder, IR, validation, interpreter, and exporters wired; 10 new tests
plus export round-trip coverage. Coverage gates pass.

Author: felixgeelhaar

README.md

@@ -62,6 +62,7 @@ Step-by-step migration guides:
 - Hierarchical states with event bubbling
 - History states (shallow and deep)
 - Delayed transitions and parallel/orthogonal regions
+- Eventless (`Always`) transitions, `Raise` internal events, and state `Tags`
 - Guards, actions, entry/exit hooks
 - Reflection DSL — define machines with struct tags
 - Build-time validation
@@ -217,6 +218,46 @@ interp.Send(statekit.Event{Type: "TOGGLE_BOLD"})
 // bold: on, italic: off (independent regions)
 ```
 
+## Eventless Transitions, Raise & Tags
+
+**`Always`** transitions fire automatically on state entry (and after every
+transition), choosing the first whose guard passes — ideal for conditional
+routing without an explicit event. **`Raise`** enqueues an internal event that
+is processed in the same step, before control returns and before any external
+event. **`Tags`** categorize states for lightweight querying via `HasTag`.
+
+```go
+machine, _ := statekit.NewMachine[Ctx]("checkout").
+    WithInitial("validating").
+    WithGuard("ok", func(c Ctx, e statekit.Event) bool { return c.Valid }).
+    State("validating").
+        Tags("busy").
+        Always().Target("approved").Guard("ok").End().
+        Always().Target("rejected").End().            // guardless fallback
+        Done().
+    State("approved").
+        On("SHIP").Target("shipping").Raise("NOTIFY").End().  // raise internal event
+        Done().
+    State("shipping").
+        On("NOTIFY").Target("done").End().            // handled in the same step
+        Done().
+    State("rejected").Final().Done().
+    State("done").Final().Done().
+    Build()
+
+interp := statekit.NewInterpreter(machine)
+interp.Start()
+// validating → approved|rejected resolved automatically via Always
+
+fmt.Println(interp.HasTag("busy"))  // true while in a tagged active state
+```
+
+Key behaviors:
+- `Always` transitions are evaluated in declaration order; the first enabled wins. A target is required (build-time validated) to prevent infinite loops.
+- A macrostep settles all eventless transitions and drains raised events before `Start()`/`Send()` returns (bounded to guard against always-true cycles).
+- `HasTag` matches the active leaf, its ancestors, and active parallel-region leaves.
+- All three round-trip through the Native JSON and XState v5 exporters (`always`, `tags`, and `xstate.raise` action descriptors).
+
 ## Reflection DSL
 
 Define machines using struct tags:

builder.go

@@ -30,6 +30,8 @@ type StateBuilder[C any] struct {
 	entry       []ActionType
 	exit        []ActionType
 	transitions []*TransitionBuilder[C]
+	always      []*TransitionBuilder[C] // eventless transitions (v1.x)
+	tags        []string                // state tags (v1.x)
 
 	// History state fields (v2.0)
 	historyType    HistoryType
@@ -109,6 +111,12 @@ type TransitionBuilder[C any] struct {
 
 	// Delayed transition fields (v2.0)
 	delay time.Duration
+
+	// Eventless ("always") transition flag (v1.x)
+	eventless bool
+
+	// Raised internal events (v1.x)
+	raise []EventType
 }
 
 // NewMachine creates a new MachineBuilder with the given ID
@@ -233,15 +241,28 @@ func buildStateRecursive[C any](sb *StateBuilder[C], parentID ir.StateID, machin
 	state.Entry = append(state.Entry, sb.entry...)
 	state.Exit = append(state.Exit, sb.exit...)
 
+	// Copy state tags (v1.x)
+	state.Tags = append(state.Tags, sb.tags...)
+
 	// Build transitions
 	for _, tb := range sb.transitions {
 		trans := ir.NewTransitionConfig(tb.event, tb.target)
 		trans.Guard = tb.guard
 		trans.Actions = append(trans.Actions, tb.actions...)
 		trans.Delay = tb.delay // Delayed transitions (v2.0)
+		trans.Raise = append(trans.Raise, tb.raise...)
 		state.Transitions = append(state.Transitions, trans)
 	}
 
+	// Build eventless ("always") transitions (v1.x)
+	for _, tb := range sb.always {
+		trans := ir.NewTransitionConfig("", tb.target)
+		trans.Guard = tb.guard
+		trans.Actions = append(trans.Actions, tb.actions...)
+		trans.Raise = append(trans.Raise, tb.raise...)
+		state.Always = append(state.Always, trans)
+	}
+
 	// Build invocations (v3.0)
 	for _, ib := range sb.invocations {
 		invoke := &ir.InvokeConfig{
@@ -341,6 +362,27 @@ func (b *StateBuilder[C]) On(event EventType) *TransitionBuilder[C] {
 	return tb
 }
 
+// Always starts building an eventless ("always") transition (v1.x). It is
+// evaluated when the state is entered and after every transition, in
+// declaration order; the first whose guard passes is taken. A target is
+// required. Use multiple Always() calls to express guarded routing with a
+// final guardless fallback.
+func (b *StateBuilder[C]) Always() *TransitionBuilder[C] {
+	tb := &TransitionBuilder[C]{
+		state:     b,
+		eventless: true,
+	}
+	b.always = append(b.always, tb)
+	return tb
+}
+
+// Tags attaches one or more tags to the state for lightweight querying via
+// Interpreter.HasTag (v1.x).
+func (b *StateBuilder[C]) Tags(tags ...string) *StateBuilder[C] {
+	b.tags = append(b.tags, tags...)
+	return b
+}
+
 // Done completes the state definition and returns the root MachineBuilder.
 //
 // Watch out: when called from a nested StateBuilder, Done() teleports the
@@ -623,6 +665,14 @@ func (b *TransitionBuilder[C]) Do(action ActionType) *TransitionBuilder[C] {
 	return b
 }
 
+// Raise enqueues internal events emitted when this transition is taken (v1.x).
+// Raised events are processed in the same macrostep — before control returns
+// to the caller and before any externally sent event.
+func (b *TransitionBuilder[C]) Raise(events ...EventType) *TransitionBuilder[C] {
+	b.raise = append(b.raise, events...)
+	return b
+}
+
 // On starts a new transition on the same state (chainable)
 func (b *TransitionBuilder[C]) On(event EventType) *TransitionBuilder[C] {
 	return b.state.On(event)

eventless_raise_tags_test.go

@@ -0,0 +1,184 @@
+package statekit
+
+import "testing"
+
+// --- Tags ---
+
+func TestTags_HasTagForActiveAndAncestors(t *testing.T) {
+	m, err := NewMachine[struct{}]("tags").
+		WithInitial("active").
+		State("active").
+		Tags("running").
+		WithInitial("loading").
+		State("loading").Tags("busy", "io").End().
+		State("ready").Tags("idle").End().
+		Done().
+		Build()
+	if err != nil {
+		t.Fatalf("build: %v", err)
+	}
+
+	i := NewInterpreter(m)
+	i.Start()
+
+	// Leaf "loading" tags
+	if !i.HasTag("busy") {
+		t.Errorf("expected HasTag(busy) on leaf")
+	}
+	if !i.HasTag("io") {
+		t.Errorf("expected HasTag(io) on leaf")
+	}
+	// Ancestor "active" tag visible from leaf
+	if !i.HasTag("running") {
+		t.Errorf("expected HasTag(running) from ancestor")
+	}
+	// Tag of a sibling (not active) must not match
+	if i.HasTag("idle") {
+		t.Errorf("did not expect HasTag(idle) — sibling not active")
+	}
+	// Unknown tag
+	if i.HasTag("nope") {
+		t.Errorf("did not expect HasTag(nope)")
+	}
+}
+
+// --- Always (eventless transitions) ---
+
+func TestAlways_FiresOnEntryWhenGuardPasses(t *testing.T) {
+	m, err := NewMachine[struct{ Ok bool }]("always").
+		WithInitial("check").
+		WithGuard("ok", func(c struct{ Ok bool }, e Event) bool { return c.Ok }).
+		WithContext(struct{ Ok bool }{Ok: true}).
+		State("check").
+		Always().Target("approved").Guard("ok").End().
+		Always().Target("rejected").End(). // fallback (guardless)
+		Done().
+		State("approved").Final().Done().
+		State("rejected").Final().Done().
+		Build()
+	if err != nil {
+		t.Fatalf("build: %v", err)
+	}
+
+	i := NewInterpreter(m)
+	i.Start()
+	if got := i.State().Value; got != "approved" {
+		t.Errorf("state = %q, want approved", got)
+	}
+}
+
+func TestAlways_FallbackWhenGuardFails(t *testing.T) {
+	m, err := NewMachine[struct{ Ok bool }]("always").
+		WithInitial("check").
+		WithGuard("ok", func(c struct{ Ok bool }, e Event) bool { return c.Ok }).
+		WithContext(struct{ Ok bool }{Ok: false}).
+		State("check").
+		Always().Target("approved").Guard("ok").End().
+		Always().Target("rejected").End().
+		Done().
+		State("approved").Final().Done().
+		State("rejected").Final().Done().
+		Build()
+	if err != nil {
+		t.Fatalf("build: %v", err)
+	}
+
+	i := NewInterpreter(m)
+	i.Start()
+	if got := i.State().Value; got != "rejected" {
+		t.Errorf("state = %q, want rejected", got)
+	}
+}
+
+func TestAlways_ChainsThroughMultipleStates(t *testing.T) {
+	// a -> b -> c all via eventless transitions in a single macrostep
+	m, err := NewMachine[struct{}]("chain").
+		WithInitial("a").
+		State("a").Always().Target("b").End().Done().
+		State("b").Always().Target("c").End().Done().
+		State("c").Final().Done().
+		Build()
+	if err != nil {
+		t.Fatalf("build: %v", err)
+	}
+
+	i := NewInterpreter(m)
+	i.Start()
+	if got := i.State().Value; got != "c" {
+		t.Errorf("state = %q, want c", got)
+	}
+}
+
+func TestAlways_FiresAfterEventTransition(t *testing.T) {
+	m, err := NewMachine[struct{}]("evt").
+		WithInitial("idle").
+		State("idle").On("GO").Target("transient").End().Done().
+		State("transient").Always().Target("done").End().Done().
+		State("done").Final().Done().
+		Build()
+	if err != nil {
+		t.Fatalf("build: %v", err)
+	}
+
+	i := NewInterpreter(m)
+	i.Start()
+	if got := i.State().Value; got != "idle" {
+		t.Fatalf("state = %q, want idle", got)
+	}
+	i.Send(Event{Type: "GO"})
+	if got := i.State().Value; got != "done" {
+		t.Errorf("state = %q, want done (transient should auto-advance)", got)
+	}
+}
+
+// --- Raise (internal self-event) ---
+
+func TestRaise_ProcessedInSameMacrostep(t *testing.T) {
+	m, err := NewMachine[struct{}]("raise").
+		WithInitial("idle").
+		State("idle").On("START").Target("middle").Raise("NEXT").End().Done().
+		State("middle").On("NEXT").Target("done").End().Done().
+		State("done").Final().Done().
+		Build()
+	if err != nil {
+		t.Fatalf("build: %v", err)
+	}
+
+	i := NewInterpreter(m)
+	i.Start()
+	i.Send(Event{Type: "START"})
+	if got := i.State().Value; got != "done" {
+		t.Errorf("state = %q, want done (raised NEXT should be processed)", got)
+	}
+}
+
+func TestRaise_FromAlwaysTransition(t *testing.T) {
+	m, err := NewMachine[struct{}]("raise2").
+		WithInitial("start").
+		State("start").Always().Target("waiting").Raise("PING").End().Done().
+		State("waiting").On("PING").Target("done").End().Done().
+		State("done").Final().Done().
+		Build()
+	if err != nil {
+		t.Fatalf("build: %v", err)
+	}
+
+	i := NewInterpreter(m)
+	i.Start()
+	if got := i.State().Value; got != "done" {
+		t.Errorf("state = %q, want done (always→raise→PING)", got)
+	}
+}
+
+// --- Validation ---
+
+func TestAlways_RequiresTarget(t *testing.T) {
+	_, err := NewMachine[struct{}]("bad").
+		WithInitial("a").
+		State("a").Always().End().Done().
+		State("b").Final().Done().
+		Build()
+	if err == nil {
+		t.Errorf("expected validation error for always transition without target")
+	}
+}