package semantic

// SemanticSeed is an intermediate specification whose label is known before
// any surface text is generated. The important invariant is:
//
//	semantic identity → deterministic surface generation
//
// NOT:
//
//	sentence → model guesses label
type SemanticSeed struct {
	// ID uniquely identifies this seed within the corpus factory.
	ID string `json:"id"`

	// Route is the coarse semantic route this seed maps to.
	Route SemanticRoute `json:"route"`

	// Family groups seeds that share the same semantic operation.
	// All surfaces derived from one seed share a SplitGroup.
	Family string `json:"family"`

	// OperationID identifies the concrete operation (tool, capability, etc.)
	// that this seed represents. Empty for seeds without a concrete operation.
	OperationID string `json:"operation_id,omitempty"`

	// SplitGroup is the group ID for train/eval splitting.
	// All surfaces from one seed must share this.
	SplitGroup string `json:"split_group"`

	// VerbForms are the imperative/stative verbs that express this seed's
	// action or query. For action seeds, these are the command verbs.
	// For knowledge seeds, these are the query-opening words.
	VerbForms []string `json:"verb_forms,omitempty"`

	// Subjects are the targets/objects of the action or query.
	// For HA actions: entity names. For tools: service names.
	Subjects []string `json:"subjects,omitempty"`

	// Objects are additional objects or arguments.
	Objects []string `json:"objects,omitempty"`

	// Values are quantified values (durations, amounts, etc.)
	Values []string `json:"values,omitempty"`

	// Tags are metadata tags applied to all generated surfaces from this seed.
	Tags []string `json:"tags,omitempty"`
}

// SurfaceGenerator generates surface forms from a seed. Each generator
// produces meaning-preserving forms that are less tied to the deterministic
// command grammar, tagged by template category.
type SurfaceGenerator struct {
	// Name identifies this generator for provenance tracking.
	Name string

	// Fn generates surface forms from a seed.
	Fn func(seed SemanticSeed) []GeneratedSurface
}

// GeneratedSurface is one surface form derived from a seed.
type GeneratedSurface struct {
	Text   string `json:"text"`
	// TemplateCategory identifies which template produced this surface.
	TemplateCategory string `json:"template_category"`
	// FastPathMatched is set after fast-path classification.
	FastPathMatched bool `json:"-"`
	// ExpectedRoute is the route this surface should map to.
	ExpectedRoute SemanticRoute `json:"-"`
}