internal/shared/domain/statemachine/
  machine.go      → StateMachine[TState, TEvent comparable]
  transition.go   → Transition[TState, TEvent]{ From, Event, To, Guard, Action }
  errors.go       → ErrInvalidTransition{ From, Event string }

internal/modules/fieldforce/domain/statemachine/
  task_machine.go → NewTaskStateMachine() — registers all 9 transitions

Trigger(ctx, currentState, event, tctx)
  1. Find Transition where From == currentState AND Event == event
  2. Run Guard(tctx) — returns ErrInvalidTransition if role or state invalid
  3. Run Action(tctx) — optional side-effect (e.g. append ReviewNote to tctx)
  4. Return (To, nil) — caller is responsible for persisting the new state

// Module-local state machine — requires migration when next module needs it
package fieldforce

type TaskStateMachine struct{} // wrong — put in internal/shared/domain/statemachine

// Persisting inside an Action — breaks pure-function contract
statemachine.Transition[TaskStatus, TaskEvent]{
    Action: func(tctx statemachine.TransitionContext) error {
        repo.Update(ctx, task) // wrong — Action must not do I/O
        return nil
    },
}

// Shared kernel type imported by fieldforce
import "github.com/waynecheah/go-core/internal/shared/domain/statemachine"

func NewTaskStateMachine() *statemachine.StateMachine[TaskStatus, TaskEvent] {
    return statemachine.New([]statemachine.Transition[TaskStatus, TaskEvent]{
        {
            From:  TaskStatusPending,
            Event: EventStart,
            To:    TaskStatusInProgress,
            Guard: requireRole("field_team", "supervisor", "manager"),
        },
        // ... 8 more transitions
    })
}

// Service calls Trigger, then persists the result
newStatus, err := taskMachine.Trigger(ctx, task.Status, event, tctx)
if err != nil { return nil, err }
task.Status = newStatus
return repo.Update(ctx, task) // persistence is the caller's responsibility