report

type Brief struct {
	// Headline is the one-line status.
	Headline string `json:"headline"`
	// Lines are the supporting summary points, most important first.
	Lines []string `json:"lines,omitempty"`
}

type BuildOptions struct {
	// OutlierThreshold controls outlier sensitivity (standard deviations).
	// Lower values flag more outliers. Default is 3.5.
	OutlierThreshold float64
	// Groups maps group name to cluster names for group-aware analysis.
	Groups map[string][]string
	// ClusterTags maps cluster name to a cohort tag value. When non-empty,
	// tagged clusters land in tagged cohorts instead of being auto-grouped.
	// Untagged clusters still get auto-cohorted.
	ClusterTags map[string]string
	// Timestamp is when the scan behind the report ran. A report rebuilt from a stored scan
	// passes that scan's time, so rebuilding it later yields the same report. Zero means now.
	Timestamp time.Time
}

type CapacityAnalysis struct {
	// Cluster is the cluster name.
	Cluster string `json:"cluster"`
	// CPUUtilization is the average CPU percentage.
	CPUUtilization float64 `json:"cpu_utilization"`
	// MemoryUtilization is the average memory percentage.
	MemoryUtilization float64 `json:"memory_utilization"`
	// HasMemoryPressure is true when any node reports MemoryPressure=True.
	HasMemoryPressure bool `json:"has_memory_pressure"`
	// HasDiskPressure is true when any node reports DiskPressure=True.
	HasDiskPressure bool `json:"has_disk_pressure"`
	// HasOOMEvents is true when OOMKilling events were detected.
	HasOOMEvents bool `json:"has_oom_events"`
	// HasSchedulingFailures is true when FailedScheduling events were detected.
	HasSchedulingFailures bool `json:"has_scheduling_failures"`
	// NodeCount is the total number of nodes.
	NodeCount int `json:"node_count"`
	// HealthyNodes is the number of healthy nodes.
	HealthyNodes int `json:"healthy_nodes"`
	// HeadroomCPU is the percentage of CPU capacity still available.
	HeadroomCPU float64 `json:"headroom_cpu"`
	// HeadroomMemory is the percentage of memory capacity still available.
	HeadroomMemory float64 `json:"headroom_memory"`
	// Status is the assessed state: healthy, busy, strained, critical.
	Status string `json:"status"`
	// Recommendation is a plain English capacity recommendation.
	Recommendation string `json:"recommendation,omitempty"`
	// NodesNeededForTarget is how many additional nodes would bring memory below 70%.
	NodesNeededForTarget int `json:"nodes_needed_for_target,omitempty"`
	// GroupDeviation describes how this cluster compares to its group peers.
	GroupDeviation string `json:"group_deviation,omitempty"`
}

type Category struct {
	// Name is the category display name.
	Name string `json:"name"`
	// Scanners lists the scanner names in this category.
	Scanners []string `json:"scanners"`
}

type CategoryReport struct {
	// Name is the category display name.
	Name string `json:"name"`
	// Scanners lists scanner names in this category.
	Scanners []string `json:"scanners"`
}

type ClusterDrift struct {
	// Cluster is the cluster name.
	Cluster string `json:"cluster"`
	// Mass is the cluster's deviation mass in each scan, oldest first, zero
	// where the cluster was absent.
	Mass []float64 `json:"mass"`
	// MassBefore is the deviation mass in the first scan.
	MassBefore float64 `json:"mass_before"`
	// MassAfter is the deviation mass in the last scan.
	MassAfter float64 `json:"mass_after"`
	// MassDelta is MassAfter - MassBefore.
	MassDelta float64 `json:"mass_delta"`
	// Fields lists up to five fields whose value changed between the first
	// and last scan, the largest move in |z| first.
	Fields []FieldDrift `json:"fields,omitempty"`
	// Gained lists outlier flags set in the last scan and not in the first.
	Gained []FlagChange `json:"gained,omitempty"`
	// Lost lists outlier flags set in the first scan and not in the last.
	Lost []FlagChange `json:"lost,omitempty"`
}

type ClusterHealth struct {
	// Name is the cluster context name.
	Name string `json:"name"`
	// Status is "healthy", "busy", "degraded", or "critical".
	Status string `json:"status"`
	// FindingCounts maps severity to count for this cluster.
	FindingCounts map[string]int `json:"finding_counts"`
	// KubernetesVersion is the cluster's k8s version.
	KubernetesVersion string `json:"kubernetes_version"`
	// NodeCount is the number of nodes.
	NodeCount int `json:"node_count"`
	// HealthyNodes is the number of healthy nodes.
	HealthyNodes int `json:"healthy_nodes"`
	// AvgCPU is the average CPU utilization percentage.
	AvgCPU float64 `json:"avg_cpu"`
	// AvgMemory is the average memory utilization percentage.
	AvgMemory float64 `json:"avg_memory"`
	// WarningEvents is the number of warning events.
	WarningEvents int `json:"warning_events"`
	// NamespaceCount is the number of namespaces.
	NamespaceCount int `json:"namespace_count"`
	// DegradedScanners is how many scanner runs did not return complete,
	// trustworthy data for this cluster (errored, degraded, or unavailable).
	// Nonzero means this cluster's report rests on partial coverage.
	DegradedScanners int `json:"degraded_scanners,omitempty"`
}

type ClusterMark struct {
	// Cluster is the implicated cluster.
	Cluster string `json:"cluster"`
	// Severity is the severity the finding sets on this cluster's status.
	Severity string `json:"severity"`
}

type ClusterScore struct {
	// Cluster is the kubeconfig context name the score applies to.
	Cluster string `json:"cluster"`
	// Score is the 0-100 health score.
	Score int `json:"score"`
	// Grade is the letter grade rollup.
	Grade string `json:"grade"`
	// Headline is a one-line plain-English summary.
	Headline string `json:"headline"`
}

type ClusterTrend struct {
	// Cluster is the cluster name.
	Cluster string `json:"cluster"`
	// Scanner is the scanner that produces the metric.
	Scanner string `json:"scanner"`
	// Field is the metric field name.
	Field string `json:"field"`
	// Points are the historical data points, oldest first.
	Points []TrendPoint `json:"points"`
	// Direction indicates the overall trend.
	Direction TrendDirection `json:"direction"`
	// Confidence describes how trustworthy this direction is: "high", "low",
	// or empty when no direction was computed.
	Confidence string `json:"confidence,omitempty"`
	// RSquared is the coefficient of determination for the fitted slope.
	RSquared float64 `json:"r_squared,omitempty"`
}

type ClusterValue struct {
	// Cluster is the cluster name.
	Cluster string `json:"cluster"`
	// Number is the value of a numeric field.
	Number *float64 `json:"number,omitempty"`
	// Text is the value of a string field.
	Text string `json:"text,omitempty"`
	// Size is how many members a set field has on this cluster.
	Size int `json:"size,omitempty"`
	// Missing lists the consensus members a set field lacks on this cluster,
	// sorted. Every other consensus member is present.
	Missing []string `json:"missing,omitempty"`
	// Z is the signed modified z-score of a numeric value, zero when MAD is
	// zero. In a limited sample a flagged cluster's Z is measured against the
	// other clusters, as its finding quotes.
	Z float64 `json:"z,omitempty"`
	// Outlier is true when the detector flagged this cluster.
	Outlier bool `json:"outlier,omitempty"`
	// Explained names the operator-tagged cohort whose own norm holds this
	// fleet outlier, empty otherwise. An explained outlier raises no finding.
	Explained string `json:"explained,omitempty"`
}

type CohortSummary struct {
	// Name is the cohort label (tag value for tagged cohorts, "auto-N" for
	// auto-detected cohorts, or "fleet" for too-small fleets).
	Name string `json:"name"`
	// Source identifies how the cohort was produced.
	Source string `json:"source"`
	// Clusters lists the member cluster names, sorted.
	Clusters []string `json:"clusters"`
	// Outliers are clusters that deviate from this cohort's baseline.
	Outliers []OutlierResult `json:"outliers,omitempty"`
}

type Distribution struct {
	// Scope is "fleet" or the name of the cohort the population was drawn from.
	Scope string `json:"scope"`
	// Scanner is the scanner that reported the field.
	Scanner string `json:"scanner"`
	// Field is the field within the scanner's data.
	Field string `json:"field"`
	// Kind is "numeric", "string", or "set".
	Kind string `json:"kind"`
	// Values holds one entry per cluster in the population, in report cluster
	// order.
	Values []ClusterValue `json:"values"`
	// Median is the population median of a numeric field.
	Median float64 `json:"median"`
	// MAD is the median absolute deviation of a numeric field from Median.
	MAD float64 `json:"mad"`
	// Band is how far from Median a numeric value may sit before it is
	// flagged: Threshold * MAD / 0.6745. Zero when MAD is zero.
	Band float64 `json:"band"`
	// Threshold is the cutoff the detector applied: the modified z-score for
	// numeric, the minimum mode share for string, and the minimum presence
	// share for set membership.
	Threshold float64 `json:"threshold"`
	// Mode is the most common value of a string field.
	Mode string `json:"mode,omitempty"`
	// ModeShare is the fraction of the population holding Mode.
	ModeShare float64 `json:"mode_share,omitempty"`
	// Consensus lists the members of a set field present in at least
	// Threshold of the population, sorted.
	Consensus []string `json:"consensus,omitempty"`
	// SampleSize is the number of clusters in the population.
	SampleSize int `json:"sample_size"`
	// LimitedSample marks a population too small for MAD, judged by the
	// leave-one-out majority diff.
	LimitedSample bool `json:"limited_sample,omitempty"`
	// Mass is the sum over Values of |Z| capped at 10.
	Mass float64 `json:"mass"`
}

type Divergence struct {
	// Field identifies what differs (e.g. "git_version").
	Field string `json:"field"`
	// Severity indicates how important this divergence is.
	Severity string `json:"severity"`
	// Values maps cluster name to the value it reported for this field.
	Values map[string]string `json:"values"`
}

type FieldDrift struct {
	// Scanner is the scanner that reported the field.
	Scanner string `json:"scanner"`
	// Field is the field name.
	Field string `json:"field"`
	// ZBefore is the cluster's z in the first scan, zero when absent.
	ZBefore float64 `json:"z_before"`
	// ZAfter is the cluster's z in the last scan, zero when absent.
	ZAfter float64 `json:"z_after"`
	// Before is the cluster's value in the first scan, empty when absent.
	Before string `json:"before,omitempty"`
	// After is the cluster's value in the last scan, empty when absent.
	After string `json:"after,omitempty"`
}

type Finding struct {
	// Title is a short description of the finding.
	Title string `json:"title"`
	// Description is a detailed explanation.
	Description string `json:"description"`
	// Severity is critical, warning, or info.
	Severity string `json:"severity"`
	// Cluster is the cluster this finding applies to, or "fleet" for cross-cluster.
	Cluster string `json:"cluster"`
	// Scanner is the scanner that produced this finding.
	Scanner string `json:"scanner"`
	// Rule names the check that produced this finding as scanner/slug, e.g.
	// "workload-security/privileged". It never carries a cluster name or a
	// count, so the same check on two clusters shares a rule.
	Rule string `json:"rule"`
	// Fingerprint is the stable identifier of this finding, a hash of its
	// cluster, scanner, and rule. Acknowledgements and persistence key on it.
	Fingerprint string `json:"fingerprint"`
	// Acked reports whether an active acknowledgement covers this finding.
	// Only the server, which holds the acknowledgements, sets it.
	Acked bool `json:"acked"`
	// Affected lists the offending resources (nodes, pods, bindings, images)
	// scoped to this finding. Empty when the finding has no specific noun.
	Affected []string `json:"affected,omitempty"`
	// Remediation is the suggested fix. Empty when no automated suggestion fits.
	Remediation *Remediation `json:"remediation,omitempty"`
	// Norm is the fleet or cohort norm a fleet-relative finding was measured
	// against. It is nil on absolute-rule findings, which is how a reader
	// tells the two classes apart.
	Norm *NormBasis `json:"norm,omitempty"`
	// Marks names the clusters a fleet-scoped finding holds responsible, each
	// with the severity it sets on that cluster's status. Empty on cluster
	// findings and on fleet findings no single cluster is behind.
	Marks []ClusterMark `json:"marks,omitempty"`
}

type FindingPersistence struct {
	// Fingerprint is the stable finding identifier, matching its ack key.
	Fingerprint string `json:"fingerprint"`
	// Cluster is the finding's cluster scope, or "fleet".
	Cluster string `json:"cluster"`
	// Scanner is the scanner that produced the finding.
	Scanner string `json:"scanner"`
	// Rule is the check that produced the finding.
	Rule string `json:"rule"`
	// Title is the finding title as last observed.
	Title string `json:"title"`
	// Severity is the finding's severity as last observed.
	Severity string `json:"severity"`
	// Present is the number of scans in the window that contained the finding.
	Present int `json:"present"`
	// Total is the number of scans in the window.
	Total int `json:"total"`
	// Fraction is Present divided by Total, in the range zero to one.
	Fraction float64 `json:"fraction"`
	// Streak is the number of consecutive most-recent scans containing it.
	Streak int `json:"streak"`
	// Class is chronic, intermittent, or transient.
	Class string `json:"class"`
	// Acked reports whether the finding has an active acknowledgement.
	Acked bool `json:"acked"`
}

type Fix struct {
	// Cluster is the cluster to change.
	Cluster string `json:"cluster"`
	// Scanner is the scanner whose field changes.
	Scanner string `json:"scanner"`
	// Field is the field to change, as distributions name it.
	Field string `json:"field"`
	// Kind is one of the Fix constants. Empty picks the one that matches the
	// field: median for numeric, mode for string, consensus for set.
	Kind string `json:"kind,omitempty"`
	// Scope is "fleet" or a cohort name, the norm to fix toward. Empty means
	// the cluster's tagged cohort when that cohort has a norm for the field,
	// since that is the norm the cluster answers to, and the fleet otherwise.
	Scope string `json:"scope,omitempty"`
}

type FlagChange struct {
	// Scanner is the scanner that reported the field.
	Scanner string `json:"scanner"`
	// Field is the field name.
	Field string `json:"field"`
	// Scan is the ID of the scan where the flag last changed to its final
	// state.
	Scan string `json:"scan"`
}

type FleetScore struct {
	// Score is the rounded 0-100 health score.
	Score int `json:"score"`
	// Grade is a single-letter rollup of Score: A 90+, B 80+, C 70+, D 60+, F under 60.
	Grade string `json:"grade"`
	// Headline is a one-line plain-English summary suitable for a hero card.
	Headline string `json:"headline"`
	// Drivers names the top three factors pulling the score below 100, in
	// descending order of impact. Empty when the fleet is at 100.
	Drivers []FleetScoreDriver `json:"drivers,omitempty"`
	// SampleSize is the number of clusters that contributed scanner data to
	// this score. A score from six clusters and one from sixty are different
	// claims, so the sample travels with the number.
	SampleSize int `json:"sample_size"`
	// Dimensions is the number of scan dimensions that contributed data from
	// at least one cluster.
	Dimensions int `json:"dimensions"`
	// ExcludedClusters is how many scanned clusters contributed no usable data
	// and were left out of the statistical population.
	ExcludedClusters int `json:"excluded_clusters"`
}

type FleetScoreDriver struct {
	// Reason is a short human-readable label.
	Reason string `json:"reason"`
	// Impact is the number of points (whole or fractional, rounded) this
	// driver removed from the score.
	Impact int `json:"impact"`
}

type FleetScoreForecast struct {
	// Predicted is the projected Fleet Score at PredictedFor.
	Predicted int `json:"predicted"`
	// Lower is the lower bound of a 95% prediction interval, clamped to 0-100.
	Lower int `json:"lower"`
	// Upper is the upper bound of the 95% prediction interval, clamped to 0-100.
	Upper int `json:"upper"`
	// PredictedFor is the wall-clock time the forecast targets. The handler
	// chooses this (typically "now + median inter-scan gap"); the math is
	// time-aware so a quoted ETA reflects the actual extrapolation.
	PredictedFor time.Time `json:"predicted_for"`
	// Slope is the slope of the fitted line in points per hour. Negative means
	// the fleet is degrading.
	Slope float64 `json:"slope_per_hour"`
	// RSquared is the coefficient of determination for the fit.
	RSquared float64 `json:"r_squared"`
	// Basis is the number of historical points used in the fit.
	Basis int `json:"basis"`
	// Sufficient is true when the fit cleared the minimum sample and noise
	// thresholds and the forecast is worth showing.
	Sufficient bool `json:"sufficient"`
	// Headline is a one-line plain-English summary suitable for the dashboard.
	Headline string `json:"headline"`
}

type FleetScoreHistoryPoint struct {
	// ScanID is the scan that produced the score.
	ScanID string `json:"scan_id"`
	// Timestamp is when the scan executed.
	Timestamp time.Time `json:"timestamp"`
	// Score is the Fleet Score for that scan.
	Score int `json:"score"`
}

type FleetTrend struct {
	// Scanner is the scanner name.
	Scanner string `json:"scanner"`
	// Field is the metric field name.
	Field string `json:"field"`
	// Direction indicates the overall trend.
	Direction TrendDirection `json:"direction"`
	// Points are fleet-aggregated values over time (e.g. count of unique versions).
	Points []TrendPoint `json:"points"`
	// Confidence describes how trustworthy this direction is.
	Confidence string `json:"confidence,omitempty"`
	// RSquared is the coefficient of determination for the fitted slope.
	RSquared float64 `json:"r_squared,omitempty"`
}

type Incident struct {
	// Cluster is the cluster the incident is on.
	Cluster string `json:"cluster"`
	// Title is a synthesized one-line summary.
	Title string `json:"title"`
	// Theme is the root-cause family the fused findings belong to.
	Theme string `json:"theme"`
	// Severity is the highest severity among the member findings.
	Severity string `json:"severity"`
	// Summary is a deterministic, templated root-cause hypothesis.
	Summary string `json:"summary"`
	// Findings lists the titles of the fused member findings, sorted.
	Findings []string `json:"findings"`
}

type Ledger struct {
	// Scans lists the scan IDs the ledger spans, oldest first.
	Scans []string `json:"scans"`
	// Clusters lists the clusters that drifted, largest change in deviation
	// mass first.
	Clusters []ClusterDrift `json:"clusters"`
}

type MisCohortFinding struct {
	// Cluster is the cluster whose tag disagrees with its profile.
	Cluster string `json:"cluster"`
	// TaggedAs is the user-applied cohort tag the cluster carries.
	TaggedAs string `json:"tagged_as"`
	// ProfileMatches is the cohort tag a majority of similar clusters carry.
	ProfileMatches string `json:"profile_matches"`
}

type NormBasis struct {
	// Scope is "fleet" or the name of the cohort the norm was computed over.
	Scope string `json:"scope"`
	// Kind is "numeric", "string", or "set".
	Kind string `json:"kind"`
	// Median is the population median of a numeric field.
	Median float64 `json:"median"`
	// MAD is the median absolute deviation of a numeric field from Median.
	MAD float64 `json:"mad"`
	// Mode is the most common value of a string field.
	Mode string `json:"mode,omitempty"`
	// ModeShare is the fraction of the population holding Mode.
	ModeShare float64 `json:"mode_share,omitempty"`
	// Consensus lists the members of a set field present in at least
	// Threshold of the population, sorted.
	Consensus []string `json:"consensus,omitempty"`
	// Missing lists the consensus members this cluster lacks, sorted.
	Missing []string `json:"missing,omitempty"`
	// SampleSize is the number of clusters in the population.
	SampleSize int `json:"sample_size"`
	// Threshold is the cutoff the detector applied: the modified z-score for
	// numeric, the minimum mode share for string, and the minimum presence
	// share for set membership.
	Threshold float64 `json:"threshold"`
	// Value is this cluster's value for the field.
	Value string `json:"value"`
	// Z is this cluster's signed modified z-score for a numeric field.
	Z float64 `json:"z"`
	// LimitedSample marks a norm drawn from a population too small for MAD.
	LimitedSample bool `json:"limited_sample"`
	// NoWhatIf explains why no what-if can project a fix toward this norm.
	// Empty when one can.
	NoWhatIf string `json:"no_what_if,omitempty"`
}

type Outcome struct {
	// Fix is the change, with Kind and Scope resolved.
	Fix Fix `json:"fix"`
	// ScoreBefore is the fleet score as scanned.
	ScoreBefore int `json:"score_before"`
	// ScoreAfter is the fleet score after the fix.
	ScoreAfter int `json:"score_after"`
	// Before is the field's distribution as scanned.
	Before *Distribution `json:"before"`
	// After is the field's distribution after the fix, nil when every
	// cluster now agrees or the population no longer qualifies for one.
	After *Distribution `json:"after,omitempty"`
	// MedianShift is the change in the numeric median.
	MedianShift float64 `json:"median_shift"`
	// MADShift is the change in the numeric MAD.
	MADShift float64 `json:"mad_shift"`
	// NewOutliers lists clusters flagged on the field after the fix that were
	// not flagged before, sorted.
	NewOutliers []string `json:"new_outliers,omitempty"`
	// ClearedOutliers lists clusters flagged before that are not flagged
	// after, sorted.
	ClearedOutliers []string `json:"cleared_outliers,omitempty"`
}

type OutlierResult struct {
	// Cluster is the cluster that deviates.
	Cluster string `json:"cluster"`
	// Field is the data field that deviates.
	Field string `json:"field"`
	// Value is the cluster's value for the field.
	Value string `json:"value"`
	// FleetNorm is the typical fleet value (median for numeric, mode for string).
	FleetNorm string `json:"fleet_norm"`
	// Deviation is the modified z-score for numeric fields.
	Deviation float64 `json:"deviation,omitempty"`
	// Scanner is the scanner that produced this data.
	Scanner string `json:"scanner"`
	// Severity is critical, warning, or info.
	Severity string `json:"severity"`
	// Scope is "fleet" or the name of the cohort the norm was computed over.
	Scope string `json:"scope"`
	// Kind is "numeric", "string", or "set".
	Kind string `json:"kind"`
	// Median is the population median of a numeric field.
	Median float64 `json:"median"`
	// MAD is the median absolute deviation of a numeric field from Median.
	MAD float64 `json:"mad"`
	// Mode is the most common value of a string field.
	Mode string `json:"mode,omitempty"`
	// ModeShare is the fraction of the population holding Mode.
	ModeShare float64 `json:"mode_share,omitempty"`
	// Consensus lists the consensus members of a set field, sorted.
	Consensus []string `json:"consensus,omitempty"`
	// Missing lists the consensus members this cluster lacks, sorted.
	Missing []string `json:"missing,omitempty"`
	// SampleSize is the number of clusters in the population.
	SampleSize int `json:"sample_size"`
	// Threshold is the cutoff the detector applied (see NormBasis.Threshold).
	Threshold float64 `json:"threshold"`
	// Z is the signed modified z-score for a numeric field.
	Z float64 `json:"z"`
	// ExplainedBy names the operator-tagged cohort whose own norm holds this
	// fleet outlier, empty otherwise. An explained outlier raises no finding.
	ExplainedBy string `json:"explained_by,omitempty"`
	// LimitedSample marks a norm drawn from a population too small for MAD.
	LimitedSample bool `json:"limited_sample"`
}

type Remediation struct {
	// Command is a kubectl or related command that addresses the finding.
	Command string `json:"command,omitempty"`
	// YAML is a manifest snippet the operator can apply directly.
	YAML string `json:"yaml,omitempty"`
	// RunbookURL is an optional runbook link.
	RunbookURL string `json:"runbook_url,omitempty"`
}

type Report struct {
	// Timestamp is when the scan was executed.
	Timestamp string `json:"timestamp"`
	// Clusters lists the kubeconfig contexts that were scanned.
	Clusters []string `json:"clusters"`
	// Categories groups sections by functional area.
	Categories []CategoryReport `json:"categories"`
	// Sections holds per-scanner comparison results keyed by scanner name.
	Sections map[string]*SectionReport `json:"sections"`
	// Summary holds fleet-wide summary statistics.
	Summary Summary `json:"summary"`
	// Findings lists human-readable issues discovered across the fleet.
	Findings []Finding `json:"findings"`
	// ClusterHealths holds per-cluster health summaries.
	ClusterHealths []ClusterHealth `json:"cluster_healths"`
	// Outliers lists clusters that deviate from fleet norms. Fleets of
	// minMADSample clusters or more use MAD. Fleets of minMajoritySample to
	// minMADSample-1 use the leave-one-out majority diff, whose results are
	// marked LimitedSample. Smaller fleets get none and a line in Notes.
	Outliers []OutlierResult `json:"outliers,omitempty"`
	// Distributions holds the population behind every field the fleet and
	// cohort detectors evaluated, fleet scope first, most deviant first.
	Distributions []Distribution `json:"distributions,omitempty"`
	// DeviationMass sums, per cluster, the capped |z| of its numeric values
	// across the fleet-scope distributions. Clusters at zero are left out.
	DeviationMass map[string]float64 `json:"deviation_mass,omitempty"`
	// ScoreAttribution is the full cost ledger behind FleetScore.
	ScoreAttribution *ScoreAttribution `json:"score_attribution,omitempty"`
	// Capacity holds smart capacity analysis per cluster, correlating
	// utilization, pressure, events, and headroom.
	Capacity []CapacityAnalysis `json:"capacity,omitempty"`
	// FleetScore is the single 0-100 indicator of overall fleet health,
	// suitable as a hero number on a status TV. Populated by Build.
	FleetScore FleetScore `json:"fleet_score"`
	// Cohorts partitions the fleet into groups of similar clusters and
	// reports within-cohort outliers. Cohorts come from user-supplied
	// cluster tags when present, otherwise from agglomerative clustering
	// on scanner-derived features.
	Cohorts []CohortSummary `json:"cohorts,omitempty"`
	// Degraded lists scanner runs that did not return complete, trustworthy
	// data for a cluster, so the report surfaces reduced coverage instead of
	// reading a failed or forbidden scan as a clean, zero-resource result.
	Degraded []ScannerStatus `json:"degraded,omitempty"`
	// Incidents groups related findings by shared root cause so operators read
	// one incident instead of a flat list of correlated symptoms.
	Incidents []Incident `json:"incidents,omitempty"`
	// Brief is a short, deterministic executive summary of this report.
	Brief Brief `json:"brief"`
	// Notes explain analysis the report could not run, such as outlier
	// detection on a fleet too small to have a norm.
	Notes []string `json:"notes,omitempty"`
}

type ScanMeta struct {
	// ID is the scan identifier.
	ID string
	// Timestamp is when the scan ran.
	Timestamp time.Time
}

type ScanReport struct {
	// ID is the scan ID. It may be empty when the report was not stored.
	ID string
	// Report is the report built from the scan.
	Report *Report
}

type ScannerInfo struct {
	// ID is the scanner key used in reports and findings.
	ID string `json:"id"`
	// Label is the human-readable name.
	Label string `json:"label"`
	// Description says in one line what the scanner checks.
	Description string `json:"description"`
	// Category is the report category the scanner belongs to.
	Category string `json:"category"`
}

type ScannerStatus struct {
	// Cluster is the cluster the scanner ran against.
	Cluster string `json:"cluster"`
	// Scanner is the scanner name.
	Scanner string `json:"scanner"`
	// State is "degraded", "errored", or "unavailable".
	State string `json:"state"`
	// Reason is a short explanation of why the data is not fully trustworthy.
	Reason string `json:"reason,omitempty"`
}

type ScoreAttribution struct {
	// Terms lists every term that cost points, in a fixed order.
	Terms []ScoreTerm `json:"terms"`
	// Entries lists every contribution to a term, grouped by term, rule, and
	// cluster.
	Entries []ScoreEntry `json:"entries"`
	// Total is the sum of every term's applied cost.
	Total float64 `json:"total"`
	// ByCluster sums applied cost per cluster. Fleet-wide costs are left out.
	ByCluster map[string]float64 `json:"by_cluster,omitempty"`
	// ByRule sums applied cost per finding rule. Costs not tied to a rule are
	// left out.
	ByRule map[string]float64 `json:"by_rule,omitempty"`
}

type ScoreEntry struct {
	// Term is the category the entry belongs to.
	Term string `json:"term"`
	// Rule is the finding rule charged, empty for costs not tied to a rule.
	Rule string `json:"rule,omitempty"`
	// Cluster is the cluster charged, empty for fleet-wide costs.
	Cluster string `json:"cluster,omitempty"`
	// Raw is the cost before the term's cap.
	Raw float64 `json:"raw"`
	// Cost is the cost after the term's cap.
	Cost float64 `json:"cost"`
}

type ScoreTerm struct {
	// Term is the category, one of the Term constants.
	Term string `json:"term"`
	// Reason is the driver label for this term.
	Reason string `json:"reason"`
	// Count is how many findings or clusters the term charged.
	Count int `json:"count"`
	// Raw is the cost before the cap.
	Raw float64 `json:"raw"`
	// Cap is the most the term may cost, zero when uncapped.
	Cap float64 `json:"cap,omitempty"`
	// Cost is the points the term removed from the score.
	Cost float64 `json:"cost"`
}

type SectionReport struct {
	// Uniform is true when all clusters produced identical data for this scanner.
	Uniform bool `json:"uniform"`
	// PerCluster holds the raw scanner data from each cluster.
	PerCluster map[string]any `json:"per_cluster"`
	// Divergences describes specific differences found between clusters.
	Divergences []Divergence `json:"divergences,omitempty"`
}

type SelfDrift struct {
	// Cluster is the cluster that drifted from its own past.
	Cluster string `json:"cluster"`
	// Scanner is the scanner that produces the metric.
	Scanner string `json:"scanner"`
	// Field is the metric field name.
	Field string `json:"field"`
	// Baseline is the median of the cluster's history before the change point.
	Baseline float64 `json:"baseline"`
	// Latest is the mean of the cluster's values after the change point.
	Latest float64 `json:"latest"`
	// Deviation is the modified z-score of Latest against the baseline, or the
	// fractional step when the baseline was flat.
	Deviation float64 `json:"deviation"`
	// ChangedAt is when the shift began, taken from the change-point scan.
	ChangedAt time.Time `json:"changed_at"`
	// Direction is worsening or improving, calibrated per metric.
	Direction TrendDirection `json:"direction"`
	// Severity is warning for a worsening shift, info for an improving one.
	Severity string `json:"severity"`
}

type Summary struct {
	// ClusterCount is the number of clusters scanned.
	ClusterCount int `json:"cluster_count"`
	// ScannerCount is the number of scanners executed.
	ScannerCount int `json:"scanner_count"`
	// UniformCount is how many scanners found identical data across all clusters.
	UniformCount int `json:"uniform_count"`
	// DivergentCount is how many scanners found differences.
	DivergentCount int `json:"divergent_count"`
	// TotalDivergences is the total number of individual divergence points.
	TotalDivergences int `json:"total_divergences"`
	// CriticalCount is the number of critical-severity divergences.
	CriticalCount int `json:"critical_count"`
	// WarningCount is the number of warning-severity divergences.
	WarningCount int `json:"warning_count"`
}

type TrendDirection string

type TrendPoint struct {
	// Timestamp is when this value was observed.
	Timestamp time.Time `json:"timestamp"`
	// ScanID is the scan that produced this value.
	ScanID string `json:"scan_id"`
	// Value is the metric value.
	Value float64 `json:"value"`
}