gate

type Clock interface {
	Now() time.Time
	After(d time.Duration) <-chan time.Time
}

type Config struct {
	// URL and Token are the connection details, read from the environment by
	// the CLI and never registered as flags. Token never enters the pure layer,
	// an error string, or a Result.
	URL, Token string

	// Alerts is REQUIRED in single-step mode and must be EMPTY in log mode:
	// with a log, the header IS the alert set, and there is nothing to compare
	// a second list against.
	Alerts []string
	Folder string

	// IncludeLabels selects by labels instead of names; ExcludeLabels drops
	// matching rules. Both are refused in log mode. ExcludeAlerts is an
	// enumerated list subtracted from either selection.
	IncludeLabels, ExcludeLabels []LabelMatcher
	ExcludeAlerts                []string

	States               []State
	Preexisting          PreexistingPolicy
	MinObserved          int
	AllowPaused          bool
	NodataIsUnobservable bool

	// NoFailFast disables early exit, so the loop always runs to
	// to+transitionGrace for a full-window coverage proof. The CLI sets it
	// with --fail-fast=false; the gate never exits 0 early either way.
	NoFailFast bool

	// From is the moment the deploy finished and To is the end of the work.
	// In recorder mode an absent From is a hard error; in single-step mode it
	// falls back to the start of this step, and a From before the
	// first-observation pass completes is a declared blind interval.
	From, To time.Time

	// Log is the path of a recording made by watch; "" selects single-step
	// mode. PidFile defaults to <Log>.pid, the convention watch's parent
	// writes and the only way check can reach the recorder it must stop before
	// it may read the log.
	Log     string
	PidFile string

	// There is deliberately NO cadence override anywhere. In log mode the
	// cadence comes from the header — the cadence the recording actually used
	// — and in single-step mode the same process records and classifies, so
	// half the evaluation interval is the only cadence there is.
	Concurrency int
	Clock       Clock

	// Notes is where the shell prints what an operator has to see while the
	// run is in progress: the planned run time, the grace and its source, the
	// countdown, the blind-interval warning. nil discards them. The library
	// renders no table — the CLI owns presentation.
	Notes io.Writer
}

type CoverageResult struct {
	Proved       bool
	LargestGap   time.Duration
	LargestGapAt time.Time
	Unobservable bool
	Reason       UnobservableReason
	Notes        []string
	// BlindFor is the worst staleness (GrafanaNow - LastEvaluation) that
	// tripped check 6; zero when check 6 never fired.
	BlindFor time.Duration
}

type DaemonChildConfig struct {
	URL, Token  string // from the inherited environment, never from argv
	Out         string
	Until       time.Time
	Concurrency int
	Clock       Clock
	// ReadyFD is the inherited descriptor to report readiness on (ReadyFDFlag).
	// Zero means nobody is waiting — a hand-started child — and the report is
	// then skipped rather than written to stdin.
	ReadyFD int
}

type Definition struct {
	// Key is the map key across both source kinds (identity.go). UID stays the
	// API-given uid and is empty for datasource-managed rules.
	Key                                  string
	UID, Title, Folder, FolderUID, Group string
	// DatasourceUID, DatasourceName and File are populated for
	// KindDatasourceManaged only; File is the Prometheus rule group's file.
	DatasourceUID, DatasourceName, File string
	For                                 time.Duration
	IntervalSeconds                     int
	NoDataState                         string
	ExecErrState                        string
	IsPaused                            bool
	Kind                                RuleKind
	// PauseObservable is true only for Grafana-managed rules, whose state
	// endpoint reports isPaused. A datasource-managed rule has no pause signal.
	PauseObservable bool
	Labels          map[string]string
}

type GlobalThresholds struct {
	TransitionGrace time.Duration
	// GraceSource names, and already carries the `for` value of, the rule that
	// set TransitionGrace — an operator has to see both. "none" when no rule
	// contributed (TransitionGrace is then 0).
	GraceSource  string
	DrainTimeout time.Duration
}

type GlobalTimings struct {
	// contains filtered or unexported fields
}

type Header struct {
	SchemaVersion  int       `json:"schema_version"`
	URL            string    `json:"url"` // the log's identity
	GrafanaVersion string    `json:"grafana_version"`
	StartedAt      time.Time `json:"started_at"` // the record start
	// ReadyAt is when the first-observation pass completed — the earliest
	// instant a `from` can honestly name, since before it some rules were
	// never observed. Zero on older logs and single-step synthesis; readyAt()
	// then falls back to StartedAt.
	ReadyAt time.Time    `json:"ready_at,omitzero"`
	Rules   []LoggedRule `json:"rules"` // THE alert set
}

type Instance struct {
	Labels   map[string]string `json:"labels"`
	State    State             `json:"state"`
	Reason   string            `json:"reason,omitempty"`
	ActiveAt time.Time         `json:"active_at"`
	Value    string            `json:"value,omitempty"`
}

type LabelMatcher struct {
	Key, Value string
}

type LoggedRule struct {
	// Key is the rule's identity across both source kinds; uid stays empty for
	// datasource-managed rules. SourceKind, DatasourceUID/Name and File are
	// additive (schema 1) and let a later check re-resolve a ds rule without
	// discovery.
	Key            string `json:"key,omitempty"`
	UID            string `json:"uid"`
	Title          string `json:"title"`
	Folder         string `json:"folder"`
	Group          string `json:"group"`
	SourceKind     string `json:"source_kind,omitempty"`
	DatasourceUID  string `json:"datasource_uid,omitempty"`
	DatasourceName string `json:"datasource_name,omitempty"`
	File           string `json:"file,omitempty"`
	// ForSeconds, IntervalSeconds, NoDataState and ExecErrState are purely
	// forensic: a resolve-time snapshot that makes the uploaded artifact
	// self-describing to a human reading it after the runner is gone. check
	// never converts them back into a Definition — it always re-resolves
	// definitions from the ruler API.
	ForSeconds      float64 `json:"for_seconds"`
	IntervalSeconds int     `json:"interval_seconds"`
	// IsPaused is load-bearing (beside PollEverySeconds): the pause state at
	// record start, the only moment `skipped` can honestly mean. decide reads
	// it via Header.pausedAtStart, never a ruler read taken after the window.
	IsPaused     bool   `json:"is_paused"`
	NoDataState  string `json:"no_data_state"`
	ExecErrState string `json:"exec_err_state"`
	// PollEverySeconds is the cadence this recording ACTUALLY used. Load-bearing:
	// check derives maxGap from it, never from the definitions — the two must
	// not be allowed to diverge.
	PollEverySeconds float64 `json:"poll_every_seconds"`
}

type Observation struct {
	Rules      []StateRule   // may be empty — an authoritative 2xx saying the rule is absent
	GrafanaNow time.Time     // the response's Date header
	Skew       time.Duration // serverDate - (t_send+t_headers)/2, signed
	SkewBound  time.Duration // (t_headers-t_send)/2 — RTT/2 to the response headers
	Latency    time.Duration // t_send through the full body read — see requestResult.Latency
}

type Outcome string

type Policy struct {
	States                            []State
	Preexisting                       PreexistingPolicy
	MinObserved                       int
	AllowPaused, NodataIsUnobservable bool
	From, To                          time.Time
}

type Poll struct {
	// RuleKey is the map key across both source kinds; RuleUID is kept for
	// compatibility and is empty for datasource-managed rules. pollKey reads
	// RuleKey when present, else RuleUID, so a v1 log written before rule_key
	// stays readable.
	RuleKey    string    `json:"rule_key,omitempty"`
	RuleUID    string    `json:"rule_uid,omitempty"`
	GrafanaNow time.Time `json:"grafana_now"` // the response's Date header
	// SkewMS, SkewBoundMS and LatencyMS are milliseconds for JSONL
	// compactness ONLY. The pure layer never touches raw ms: it reads
	// Skew(), SkewBound() and Latency() below, which convert at the
	// (de)serialization boundary.
	SkewMS      int64 `json:"skew_ms"`
	SkewBoundMS int64 `json:"skew_bound_ms"`
	LatencyMS   int64 `json:"latency_ms"`
	// KeepFiringForMS is the rule's recovery period as reported by this
	// response; 0/absent means no instance can be Recovering.
	KeepFiringForMS int64 `json:"keep_firing_for_ms,omitempty"`
	// Found false means an authoritative 2xx in which this rule was absent —
	// never a transport failure, which the transport retries and never turns
	// into a Poll. The coverage proof turns it into unobservable.
	Found bool `json:"found"`
	// State, Health and LastError are the raw rule-level strings, reporting
	// only and never classified.
	State     string `json:"state,omitempty"`
	Health    string `json:"health,omitempty"`
	LastError string `json:"last_error,omitempty"`
	// omitzero, not omitempty: a not-found poll (and a paused rule) has no
	// evaluation time, and writing "0001-01-01T00:00:00Z" into an artifact
	// humans and jq read invites reading it as a real timestamp.
	LastEvaluation time.Time      `json:"last_evaluation,omitzero"`
	IsPaused       bool           `json:"is_paused"`
	Histogram      map[string]int `json:"histogram,omitempty"` // written, never analysed
	// Reasons counts this poll's non-empty instance reasons, e.g.
	// {"NoData":1091,"Error":14}; nil when none. Reporting-only, and the only
	// place composite states stay visible (they are canonical normal, dropped
	// from Abnormal). Keys are raw reason strings and can be comma-joined
	// composites ("KeepLast, MissingSeries"), so consumers must test membership
	// via reasonNames and never index a literal key.
	Reasons map[string]int `json:"reasons,omitempty"`
	// Abnormal holds the instances whose CANONICAL state is not normal.
	// "Normal (NoData)" and "Normal (Error)" are canonical normal and are
	// deliberately not retained here.
	Abnormal []Instance `json:"abnormal,omitempty"`
	// Cleared and Vanished are instance keys that left the abnormal set,
	// resolved against the SAME response — a clear and a discontinuity are not
	// the same fact.
	Cleared  []string `json:"cleared,omitempty"`
	Vanished []string `json:"vanished,omitempty"`
}

type PreexistingPolicy string

type RecordType string

type Reducer struct {
	// contains filtered or unexported fields
}

type Result struct {
	From, To       time.Time
	GrafanaVersion string
	ClockSkew      time.Duration // the largest |skew| across every poll decide was given, not only the ones a rule's window actually used
	// ClockSkewBound is the skew BOUND (RTT/2) of that SAME poll — not
	// the largest bound seen overall, which would pair a wide bound from an
	// unrelated slow request with the worst skew and misstate how tightly
	// that skew is actually known. SkewHardLimit is a separate, fixed input
	// validation threshold (source.go) and is not an error bound on this
	// value; the CLI prints both, but must not conflate them.
	ClockSkewBound time.Duration
	Coverage       map[string]CoverageResult
	// Thresholds carries one RuleThresholds per rule Coverage also covers —
	// every non-skipped rule, keyed by UID. A skipped rule has neither: it was
	// never scheduled, so it has no maxGap/healthGrace/evalStaleAfter to
	// report.
	Thresholds map[string]RuleThresholds
	Global     GlobalThresholds
	Verdicts   []RuleVerdict
	Violations []Violation
	// Caveats are run-level, kind-level policy notes (e.g. datasource-managed
	// pause is unobservable). They are not per-rule details; the CLI prints them
	// once so they never bloat the table.
	Caveats []string `json:"caveats,omitempty"`
	// TerminatedEarly is set only when fail-fast stopped before the window
	// closed; the coverage proof is then over [from, At]. To and Global below
	// still report the requested values. Published JSON output.
	TerminatedEarly *Termination `json:"terminated_early,omitempty"`
}

type RetryExhaustedError struct {
	Failures int
	Cause    error
}

type RuleKind int

type RuleRef struct {
	Key                      string
	Kind                     RuleKind
	DatasourceUID            string // "" = Grafana-managed
	UID                      string // Grafana-managed only
	Group, Name, File, Title string
}

type RuleSource struct{ UID, Name string }

type RuleThresholds struct {
	MaxGap         time.Duration
	HealthGrace    time.Duration
	EvalStaleAfter time.Duration
}

type RuleTimings struct {
	// contains filtered or unexported fields
}

type RuleVerdict struct {
	Alert, RuleUID string
	RuleKey        string `json:"rule_key,omitempty"`
	// SourceKind is "grafana" or "datasource" (sourceKind), so a reader can see
	// which classification semantics apply without prose.
	SourceKind string `json:"source_kind,omitempty"`
	Outcome    Outcome
	BadFor     time.Duration // total wall-clock time any instance was bad inside the window, overlaps merged
	PollEvery  time.Duration
	Note       string
}

type Scheduler struct {
	// contains filtered or unexported fields
}

type Source interface {
	Version(ctx context.Context) (string, error)
	GrafanaDefinitions(ctx context.Context) ([]Definition, error)
	DiscoverRuleSources(ctx context.Context) ([]RuleSource, error)
	// DatasourceDefinitions names empty = fetch every rule; names non-empty =
	// one request with repeated rule_name[] params.
	DatasourceDefinitions(ctx context.Context, src RuleSource, names []string) ([]Definition, error)
	RuleState(ctx context.Context, ref RuleRef) (Observation, error)
}

type State string

type StateRule struct {
	// Key is the map key across both source kinds (identity.go); UID is empty
	// for datasource-managed rules.
	Key                       string
	UID, Title, Folder, Group string
	// DatasourceUID and File are set for datasource-managed rules only; Type is
	// the Prometheus rule type ("alerting"/"recording"); Query and For carry the
	// Prometheus definition.
	DatasourceUID string
	File          string
	Type, Query   string
	For           time.Duration
	Labels        map[string]string
	Interval      time.Duration
	// KeepFiringFor is the rule's recovery period in seconds; 0/absent means
	// no instance can be Recovering. Carried onto the Poll.
	KeepFiringFor time.Duration
	// State and Health are raw, lowercase, and reporting-only — never
	// classified. State in particular is never normalized.
	State, Health  string
	LastError      string
	LastEvaluation time.Time
	IsPaused       bool
	Instances      []Instance
	Totals         map[string]int
}

type StopConfig struct {
	// Log is the JSONL path whose flock proves a writer exists right now.
	// PidFile defaults to <Log>.pid.
	Log     string
	PidFile string

	Clock Clock
	Notes io.Writer

	// Timeout bounds each wait (SIGTERM, then SIGKILL when Cleanup is set).
	// Zero means recorderStopTimeout; a test overrides it to drive the SIGKILL
	// path quickly.
	Timeout time.Duration

	// Cleanup is the `stop` command's semantics rather than check's: SIGKILL a
	// recorder that ignores SIGTERM, and remove the pidfile once no writer
	// holds the log. check leaves it false — a writer that will not exit means
	// the log cannot be trusted, which is a could-not-check, never a silent
	// kill.
	Cleanup bool
}

type SystemClock struct{}

type Termination struct {
	Kind    TerminationKind    `json:"kind"`
	Alert   string             `json:"alert,omitempty"`
	RuleKey string             `json:"rule_key,omitempty"`
	RuleUID string             `json:"rule_uid,omitempty"`
	Outcome Outcome            `json:"outcome,omitempty"`
	Reason  UnobservableReason `json:"reason,omitempty"`
	At      time.Time          `json:"at"`
}

type TerminationKind string

type TransportError struct {
	Err    error
	Status int // 0 when the failure never got a status (network/transport failure)
}

type UnobservableReason string

type Violation struct {
	Alert, RuleUID string
	// RuleKey is the identity across both source kinds; RuleUID is empty for a
	// datasource-managed rule.
	RuleKey   string `json:"rule_key,omitempty"`
	Outcome   Outcome
	State     State
	Health    string // raw, reporting-only, like Poll.Health
	LastError string
	// FirstSeen is the episode's onset in the runner domain (translated by the
	// poll's own skew), or `from` when preexisting — never a raw Grafana time.
	FirstSeen time.Time
	// ClearedAt is zero unless the episode closed via a genuine Cleared event.
	ClearedAt      time.Time
	InstanceLabels map[string]string
	// Note explains a Violation with no instance behind it — decide's synthetic
	// MinObserved shortfall — and must not double as LastError (reporting-only
	// rule state from a real poll).
	Note string
}

type WatchConfig struct {
	// URL and Token are the connection details. The CLI reads both from the
	// environment and never from a flag; Token is never logged and never
	// enters an error string.
	URL, Token string

	// Alerts are the operator-supplied names, one per line, in any of the forms
	// Resolve accepts. Empty lines are discarded by Resolve.
	Alerts []string
	Folder string

	// IncludeLabels selects by labels instead of names; ExcludeLabels drops
	// matching rules. The two modes cannot be combined. ExcludeAlerts is an
	// enumerated list subtracted from either selection.
	IncludeLabels, ExcludeLabels []LabelMatcher
	ExcludeAlerts                []string

	// Out is the JSONL log path. PidFile and DaemonLog default to
	// <Out>.pid and <Out>.daemon.log — the same convention check uses to find
	// the recorder it must stop, so nothing has to be wired by hand.
	Out       string
	PidFile   string
	DaemonLog string

	// Until is an optional hard stop for the child. Zero means "record until
	// signalled", which is the normal case: check sends SIGTERM when its
	// collection loop ends.
	Until time.Time

	Concurrency int
	Clock       Clock

	// Notes is where the parent prints what an operator has to see before the
	// deploy step runs: resolve notes, the cadence per rule, the rules it will
	// not wait for. nil discards them. The library prints nothing else — the
	// CLI owns presentation.
	Notes io.Writer
}

type Writer struct {
	// contains filtered or unexported fields
}