// Package semantic defines the coarse-route contract for the learned-router
// experiment. The existing seven-intent router remains authoritative; this
// package provides a six-class semantic layer that runs only in eval/shadow
// mode until it earns promotion.
//
// The six coarse routes are:
//
//   - conversation — social turns, greetings, mood, jokes, open-ended chat
//   - knowledge    — questions seeking an answer (world, recall, calendar)
//   - action       — executable commands and reminders (act, reminder)
//   - memory_write — structured or unstructured writes (fact, note)
//   - system       — time, date, quiet mode, self-management
//   - uncertain    — too little signal to decide; the authoritative router clarifies
//
// No capability, function, slot, or source information lives in this artifact.
// That is a later stage. The contract here is purely coarse-route + confidence.
package semantic

// SemanticRoute — one of six coarse semantic classes.
type SemanticRoute string

const (
	RouteConversation SemanticRoute = "conversation"
	RouteKnowledge    SemanticRoute = "knowledge"
	RouteAction       SemanticRoute = "action"
	RouteMemoryWrite  SemanticRoute = "memory_write"
	RouteSystem       SemanticRoute = "system"
	RouteUncertain    SemanticRoute = "uncertain"
)

// AllRoutes is the ordered set of valid routes, for iteration and confusion
// matrix layout.
var AllRoutes = []SemanticRoute{
	RouteConversation,
	RouteKnowledge,
	RouteAction,
	RouteMemoryWrite,
	RouteSystem,
	RouteUncertain,
}

// SemanticRouteDecision — the output of a coarse router. No slots, no
// capability, no source — just the route, confidence, and whether the model
// chose to abstain.
type SemanticRouteDecision struct {
	Route      SemanticRoute
	Confidence float64
	Abstain    bool
	ModelID    string
}

// ValidRoute reports whether r is one of the six defined routes.
func ValidRoute(r SemanticRoute) bool {
	switch r {
	case RouteConversation, RouteKnowledge, RouteAction,
		RouteMemoryWrite, RouteSystem, RouteUncertain:
		return true
	}
	return false
}