// Package intelligence is the Phase 7 derived-metrics layer. Each module
// (ratio_velocity, hr_risk, dead_swarms, disk_forecast) computes one
// metric from `torrent_snapshots` and `ratio_snapshots`; the recommendations
// module orchestrates them and emits structured recommendations with
// provenance.
package intelligence

import "time"

// Provenance is the typed causal chain attached to every recommendation.
// Subscribers (the UI, the audit log, the simulation-engine comparison view)
// rely on this shape; new fields can be appended without breaking readers,
// but renames are breaking and need a coordinated change.
type Provenance struct {
	// GeneratedAt is when the recommendation was produced.
	GeneratedAt time.Time `json:"generated_at"`

	// Inputs lists the table+filter pairs the engine consulted. Operators
	// expanding a recommendation's tree see one entry per data source.
	Inputs []Input `json:"inputs"`

	// Rules names the metric thresholds or formulas that fired. Each rule
	// has a human-readable description AND the concrete value(s) that
	// caused the firing.
	Rules []FiredRule `json:"rules"`

	// Alternatives are actions the engine considered before settling on
	// the recommended one. Each carries the reason it was NOT picked.
	Alternatives []Alternative `json:"alternatives,omitempty"`

	// Assumptions are the baked-in defaults the engine used (e.g. "dead
	// swarm threshold = 72h", "HR safety margin = 12h"). The operator can
	// override these in YAML; the provenance trail records what was in
	// effect at generation time.
	Assumptions map[string]any `json:"assumptions,omitempty"`
}

// Input documents one data source the engine consulted.
type Input struct {
	Source    string         `json:"source"` // "ratio_snapshots" | "torrent_snapshots" | "filter_performance" | ...
	Filter    string         `json:"filter,omitempty"`
	RowCount  int            `json:"row_count"`
	WindowEnd time.Time      `json:"window_end,omitempty"`
	WindowDur time.Duration  `json:"window_duration,omitempty"`
	Extra     map[string]any `json:"extra,omitempty"`
}

// FiredRule is one metric-threshold-or-formula that contributed.
type FiredRule struct {
	Name        string         `json:"name"`
	Description string         `json:"description"`
	Values      map[string]any `json:"values,omitempty"`
}

// Alternative is one rejected action.
type Alternative struct {
	Action string `json:"action"`
	Reason string `json:"reason"`
}