chore: establish local platform baseline

internal/conversation/state.go

@@ -0,0 +1,52 @@
+package conversation
+
+import (
+	"errors"
+	"fmt"
+)
+
+type Status string
+
+const (
+	StatusPreparing     Status = "PREPARING"
+	StatusRoomIssued    Status = "ROOM_ISSUED"
+	StatusStartingAgent Status = "STARTING_AGENT"
+	StatusActive        Status = "ACTIVE"
+	StatusStopping      Status = "STOPPING"
+	StatusCompleted     Status = "COMPLETED"
+	StatusFailed        Status = "FAILED"
+	StatusExpired       Status = "EXPIRED"
+)
+
+var ErrInvalidTransition = errors.New("invalid conversation state transition")
+
+var transitions = map[Status]map[Status]struct{}{
+	StatusPreparing:     {StatusRoomIssued: {}, StatusFailed: {}},
+	StatusRoomIssued:    {StatusStartingAgent: {}, StatusExpired: {}},
+	StatusStartingAgent: {StatusActive: {}, StatusStopping: {}, StatusFailed: {}},
+	StatusActive:        {StatusStopping: {}},
+	StatusStopping:      {StatusCompleted: {}},
+}
+
+func ValidateTransition(from, to Status) error {
+	if from == to && IsKnown(from) {
+		return nil
+	}
+	if _, allowed := transitions[from][to]; !allowed {
+		return fmt.Errorf("%w: %s -> %s", ErrInvalidTransition, from, to)
+	}
+	return nil
+}
+
+func IsTerminal(status Status) bool {
+	return status == StatusCompleted || status == StatusFailed || status == StatusExpired
+}
+
+func IsKnown(status Status) bool {
+	switch status {
+	case StatusPreparing, StatusRoomIssued, StatusStartingAgent, StatusActive, StatusStopping, StatusCompleted, StatusFailed, StatusExpired:
+		return true
+	default:
+		return false
+	}
+}