providers

type Action struct {
	Name        string
	Description string
	Op          string // executable operation: suspend | resume | reconcile (empty = suggestion only)
	Target      Workload
	Mutating    bool   // true for any cluster write
	Reversible  bool   // a rollback/suspend is reversible; a delete may not be
	BlastRadius int    // number of workloads affected
	ApprovalID  string // runtime: set when registered for approval; drives Slack approve/reject buttons
}

type Bucket struct {
	Time  time.Time
	Level string
	Count int64
}

type Change struct {
	Workload    Workload
	Engine      Engine
	Type        ChangeType
	When        time.Time
	FromRev     string
	ToRev       string
	Source      SourceRef
	ManagedBy   string     // the Kustomization/Application/ResourceSet that owns it
	BlastRadius []Workload // resources affected by the change
	DiffRef     string     // opaque handle resolvable via GitOpsProvider.Diff
}

type ChangeType string

type CloudProvider interface {
	// CloudChanges returns recent mutating cloud control-plane events (AWS:
	// CloudTrail) in the window, normalized to the engine-agnostic Change model so
	// they join the same "what changed" timeline as GitOps diffs.
	CloudChanges(ctx context.Context, sel Selector, w TimeWindow) ([]Change, error)
	// ResourceHealth returns cloud-side state/health for resources backing the
	// selector (EC2 instance status, ASG capacity/activities, EKS nodegroup), as
	// normalized lines for the model.
	ResourceHealth(ctx context.Context, sel Selector, w TimeWindow) (LogResult, error)
}

type CompletionRequest struct {
	System   string
	Messages []Message
	Tools    []ToolSpec
	// ToolChoice optionally names one tool from Tools that the model MUST call on
	// this turn ("" = provider default: the model chooses freely between prose and
	// any tool). Set it on structured-output turns — submit_verdicts, submit_review,
	// submit_grade, and the post-budget-nudge submit_findings — where a prose reply
	// is never acceptable; leave it empty on normal investigation steps so the model
	// keeps the freedom to pick tools or answer.
	ToolChoice string
}

type CompletionResponse struct {
	Text      string
	ToolCalls []ToolCall
	// Usage is the provider-reported token count for this completion. Zero when
	// the provider omits it (older endpoints, or a provider that does not report
	// it) — callers treat the zero value as "unknown", not "zero tokens".
	Usage Usage
	// Truncated is true when the provider stopped because it hit the output-token
	// ceiling (Anthropic stop_reason "max_tokens", OpenAI finish_reason "length",
	// Gemini finishReason "MAX_TOKENS"). It distinguishes a cut-off answer from a
	// complete one, so the loop need not treat a truncated reply as final.
	Truncated bool
	// StopReason is the provider's raw turn-termination reason, normalized to the
	// provider's own vocabulary (Anthropic stop_reason, OpenAI finish_reason, Gemini
	// finishReason). It is empty when the provider omits it. Refused() interprets it;
	// the loop uses Refused() rather than matching strings itself.
	StopReason string
	// Opaque is provider-specific content the client must replay verbatim; produced
	// and consumed only by the same provider, empty otherwise. The loop copies it onto
	// the assistant Message it appends to history so the same provider can replay it on
	// the next request. The Anthropic client serializes completed adaptive-thinking
	// (and redacted_thinking) blocks — in order, with their signatures — into it;
	// OpenAI/Gemini leave it empty and ignore it.
	Opaque json.RawMessage
}

type CuratedIssue struct {
	Number    int
	Title     string
	Body      string
	Labels    []string
	UpdatedAt time.Time // forge last-update time; used by the curate lifecycle sweep
}

type CurationForge interface {
	OpenPR(ctx context.Context, entry KBEntry) (Ref, error)
	ListPRsByLabel(ctx context.Context, label string) ([]CuratedIssue, error)
	Comment(ctx context.Context, number int, body string) error
}

type DepNode struct {
	Workload Workload
	NotFound bool
	Ready    string // Ready condition status
	Reason   string
	Children []DepNode
}

type Diff struct {
	Files []FileDiff
}

type DriftVerdict struct {
	Drifted bool
	Signal  string
	Detail  string
}

type Engine string

type EventWindower interface {
	// EventsSince behaves like KubeReader.Events but drops events older than
	// sinceMinutes (0 = no lower bound, equivalent to Events).
	EventsSince(ctx context.Context, namespace, objectName string, warnOnly bool, sinceMinutes int) ([]KubeEvent, error)
}

type FailureEvent struct {
	Workload Workload
	Engine   Engine
	Reason   string
	Message  string
	When     time.Time
}

type FieldCount struct {
	Name string
	Hits int64
}

type FileDiff struct {
	Path  string
	Patch string
}

type GitOpsInspector interface {
	// ResourceStatus returns conditions, key refs, and recent Events for one object.
	ResourceStatus(ctx context.Context, w Workload) (ResourceStatus, error)
	// DependencyTree walks dependsOn/sourceRef edges to surface the root failure.
	DependencyTree(ctx context.Context, w Workload) (DepNode, error)
}

type GitOpsProvider interface {
	// Changes returns the ranked change timeline in a window (the spine).
	Changes(ctx context.Context, w TimeWindow, sel Selector) ([]Change, error)
	// Diff returns the actual Git diff for a change, scoped to its source path.
	Diff(ctx context.Context, c Change) (Diff, error)
	// WatchFailures emits normalized GitOps failure events as a React trigger.
	WatchFailures(ctx context.Context) (<-chan FailureEvent, error)
}

type Hypothesis struct {
	Summary         string
	Confidence      float64
	ChangeRef       string
	Evidence        []string
	SuggestedAction string // reversible-first
	Reversible      bool
}

type Investigation struct {
	Title      string
	RootCauses []Hypothesis
	Changes    []Change
	Unresolved []string // honest: what the agent could not determine
	Verdict    Verdict  // model-classified actionability; "" when the model omitted it (rendered nowhere)
	RuledOut   []string // hypotheses considered and rejected, one line each with the disproving evidence
	DataGaps   []string // signals that could not be obtained (tool errors, missing metrics, truncation) — a data limitation, not a question for a human
	Confidence float64
	Recalled   bool     // true when produced by instant recall (a KB cache hit); the curator skips re-curating it
	Resource   Workload // the workload the investigation identified as affected; defaults to the originating alert workload when none was named (stored on curated entries for structural recall)
	// Trigger-time facts stamped verbatim from the Request for the notification's
	// metadata block. The model never sees or sets them; empty for sources that lack them.
	Severity      string      // alert severity label at trigger time
	Environment   string      // deployment environment (prod/staging/…)
	Cluster       string      // alert "cluster" label
	Tenant        string      // alert "tenant" label
	AlertName     string      // triggering alert name (labels["alertname"]); "" for non-alert sources
	StartedAt     time.Time   // incident start (alert startsAt / failure time)
	Actions       []Action    // proposed remediations (autonomy ladder; never executed at rung "suggest")
	CuratedURL    string      // runtime: KB issue/PR the curator opened, linked in delivery (set after curation)
	Fingerprint   string      // originating alert fingerprint; for outcome-ledger attribution
	Fingerprints  []string    // coalesced batch fingerprints; one outcome open is recorded per entry
	TriggerKey    string      // deterministic incident identity set at trigger time (alerts: host-invariant per-class key from curator.IncidentKey; GitOps: failing resource+condition). curator.DupFingerprint prefers it so reworded re-investigations (#137) AND the same alert on a different pod/node (CORE-681) still dedupe
	RecalledEntry string      // when Recalled: the catalog entry Path that was matched
	Verified      bool        // true when the adversarial verify pass ran and a root cause survived it
	Usage         UsageTotals // per-investigation model token/cost accounting (loop + verify); surfaced to humans + metrics, never written to the curated KB body
	// Recurrence facts stamped at completion from the outcome ledger's per-TriggerKey
	// index (never seen by the model). They describe PRIOR investigations of the same
	// TriggerKey; this run's own open is recorded after they are read.
	Occurrences    int             // Nth recorded investigation of this TriggerKey (1 = first); 0 = unknown/ledger disabled
	LastOccurrence time.Time       // when the previous occurrence was investigated
	PrevCuratedURL string          // the previous occurrence's KB link, for the "same conclusion as before" pointer
	Prior          *PriorKnowledge // what the merged KB entry already says about this recurring incident; nil when unknown (see PriorKnowledge)
	// MatchedKnowledge is the single strongest PRE-EXISTING knowledge-base entry that
	// this investigation's kb_search calls matched at clear-match strength — the visible
	// proof that RunLore already had documented knowledge for the incident. It is stamped
	// by the ReAct loop (never by the model) and is DISTINCT from Prior: Prior reports
	// RECURRENCE ("this exact incident, investigated N times before", from the outcome
	// ledger), whereas MatchedKnowledge reports that a FULL investigation reused a known
	// runbook/entry even on a first sighting. nil when no kb_search hit cleared the bar.
	// Notifiers render it only when Prior == nil (the recurrence block already covers the
	// "seen before" case — don't double-render).
	MatchedKnowledge *MatchedEntry
}

type KBEntry struct {
	Type        string // OKF type, one of the validator vocabulary: Incident | Playbook | Concept
	Title       string
	Description string
	Resource    string
	Tags        []string
	Body        string   // markdown
	Fingerprint string   // deterministic dedup fingerprint (see curator.DupFingerprint)
	Confidence  float64  // overall investigation confidence; queryable extension frontmatter (0 = unset)
	Provenance  []string // distinct causing-change refs; queryable extension frontmatter
	// Reviewer context, rendered in the PR BODY only — never in the committed
	// entry file (renderEntry ignores these), so the catalog and validator are
	// untouched. Related is the draft-time BM25 neighborhood; the recurrence
	// facts mirror Investigation.Occurrences/PrevCuratedURL.
	Related        []RelatedEntry
	Occurrences    int
	PrevCuratedURL string
}

type KubeEvent struct {
	Type     string // Normal | Warning
	Reason   string
	Object   string // Kind/Name
	Message  string
	Count    int32
	LastSeen time.Time // when the event last fired; zero when the API omitted it
}

type KubeReader interface {
	// PodStatuses returns pod health in a namespace, optionally narrowed by a label
	// selector (empty = all pods).
	PodStatuses(ctx context.Context, namespace, labelSelector string) ([]PodStatus, error)
	// Events returns recent Events in a namespace; objectName "" = all objects;
	// warnOnly restricts to Warning events.
	Events(ctx context.Context, namespace, objectName string, warnOnly bool) ([]KubeEvent, error)
}

type LogFields interface {
	// FieldNames returns the field names present in the logs matching query over
	// the window, each with its occurrence count, most-frequent first.
	FieldNames(ctx context.Context, query string, w TimeWindow) ([]FieldCount, error)
}

type LogLine struct {
	Time    time.Time
	Message string
	Fields  map[string]string
}

type LogReader interface {
	// PodLogs returns recent log lines from the pods selected by q, each line
	// prefixed with its pod name.
	PodLogs(ctx context.Context, q PodLogQuery) (LogResult, error)
}

type LogResult []LogLine

type LogStats interface {
	// Hits returns the match count per step-sized bucket over the window; the
	// backend may split into per-level series (Bucket.Level set) or return a
	// single unsplit series.
	Hits(ctx context.Context, query string, w TimeWindow, step time.Duration) ([]Bucket, error)
	// TopMessages returns up to k dominant messages (numeric tokens collapsed so
	// near-identical lines group), each with its count and first→last span.
	TopMessages(ctx context.Context, query string, w TimeWindow, k int) ([]MsgCount, error)
}

type LogsProvider interface {
	Query(ctx context.Context, query string, w TimeWindow) (LogResult, error)
}

type MatchedEntry struct {
	Path  string  // catalog path of the matched entry (bundle-relative)
	Title string  // entry title, for the human-facing line
	URL   string  // web link to the entry when cheaply derivable; "" ⇒ notifier shows Path
	Score float64 // BM25 relevance score of the matching kb_search hit
}

type Matrix []Series

type Message struct {
	Role       string // system | user | assistant | tool
	Content    string
	ToolCalls  []ToolCall // assistant turn requesting tools
	ToolCallID string     // tool turn: the call this answers
	// Opaque is provider-specific content the client must replay verbatim; produced
	// and consumed only by the same provider, empty otherwise. The loop carries it
	// from a completion's CompletionResponse.Opaque onto the assistant turn it stores
	// in history, so the same provider can prepend it on the next request. Currently
	// the Anthropic client uses it to replay signed adaptive-thinking blocks; other
	// providers ignore it.
	Opaque json.RawMessage
}

type MetricsProvider interface {
	Query(ctx context.Context, promql string, at time.Time) (Samples, error)
	QueryRange(ctx context.Context, promql string, w TimeWindow, step time.Duration) (Matrix, error)
	// LabelValues lists the values a label takes across the series that match the
	// given matchers (PromQL selectors, e.g. `{namespace="apps"}`), within the
	// window. label "__name__" enumerates metric names. matchers may be empty
	// (whole-TSDB), though callers should scope it so it stays cheap.
	LabelValues(ctx context.Context, label string, matchers []string, w TimeWindow) ([]string, error)
}

type ModelProvider interface {
	Complete(ctx context.Context, req CompletionRequest) (CompletionResponse, error)
}

type MsgCount struct {
	Message string
	Count   int64
	First   time.Time
	Last    time.Time
}

type NetworkProvider interface {
	Drops(ctx context.Context, sel Selector, w TimeWindow) (LogResult, error)
}

type Notifier interface {
	Deliver(ctx context.Context, inv Investigation) error
}

type OpSafety struct {
	Reversible bool
	Blast      int
}

type OwnerChain struct {
	// Chain is the ownerReferences hops, start (the pod) FIRST, top controller LAST.
	Chain []OwnerLink
	// Top is the top controller (Deployment/StatefulSet/DaemonSet/Job); zero-valued
	// Kind when the start object had no controller owner (a bare pod).
	Top OwnerLink
	// Engine is the GitOps engine whose tracking labels named the owner ("flux"/
	// "argocd"), or "" when no tracking label was found on the top controller.
	Engine Engine
	// ManagedByKind/ManagedByName name the owning GitOps object (e.g. Kustomization
	// "harbor", Application "harbor"); "" when no tracking label was found.
	ManagedByKind      string
	ManagedByNamespace string
	ManagedByName      string
	// Drift is the generic last-applied-configuration drift signal computed while
	// walking (a manual `kubectl edit` on the top controller). nil when the signal
	// was absent (no last-applied annotation) or the live spec matched it. The
	// authoritative GitOps-engine verdict (Argo OutOfSync / Flux not-Ready) is layered
	// on separately by the caller via GitOpsInspector — this is the cheap fallback.
	Drift *DriftVerdict
}

type OwnerLink struct {
	Kind      string
	Name      string
	Namespace string
}

type OwnerWalker interface {
	// WorkloadOwnership resolves the owner chain for the pods selected by (namespace,
	// labelSelector). It picks the first matching pod (or an explicit podName when
	// set), walks Pod → ReplicaSet → Deployment (or StatefulSet/DaemonSet/Job), reads
	// the top controller's tracking labels to name the owning GitOps object, and
	// computes the last-applied-configuration drift signal on the top controller.
	WorkloadOwnership(ctx context.Context, namespace, labelSelector, podName string) (OwnerChain, error)
}

type PermanentError struct{ Err error }

type PodLogQuery struct {
	Namespace     string // required
	LabelSelector string // empty = all pods in the namespace
	SinceMinutes  int    // 0 = no lower bound
	Previous      bool   // read the last-terminated container (crash output) instead of the running one
	Container     string // empty = all of the pod's containers (the reader iterates them); set to scope to one
}

type PodStatus struct {
	Name    string
	Phase   string
	Ready   string   // "1/2"
	Healthy bool     // Running/Succeeded with all containers ready and no waiting reasons
	Reasons []string // e.g. "registry: CreateContainerConfigError: couldn't find key username in Secret …"
	// PodIP/NodeName/HostIP bridge a network_drops IP back to a pod: a VPC/Hubble
	// drop names an IP, and only pod_status can tie that IP to a workload. All three
	// are already on the corev1.Pod object, so surfacing them costs no extra API call
	// (B8, CORE-707). Empty when the pod hasn't been scheduled/assigned an IP yet.
	PodIP    string
	NodeName string
	HostIP   string
	// Time anchors (K1): pod_status was the only cluster tool with no notion of
	// WHEN. Restarts is the summed container RestartCount (how many times the pod
	// has looped); CreatedAt is the pod's creation time (its age); the
	// LastTerminated* pair is the last-terminated container's start/finish, so a
	// crash loop can be tied to a change/deploy time. All zero-valued when the
	// signal is absent (a fresh, never-restarted pod), and rendered only then.
	Restarts               int
	CreatedAt              time.Time
	LastTerminatedStarted  time.Time
	LastTerminatedFinished time.Time
}

type Point struct {
	Time  time.Time
	Value float64
}

type PriorKnowledge struct {
	Cause      string // excerpt of the merged entry's "## Cause" section
	Resolution string // excerpt of "## Resolution" — carries the human's review edits, the payoff of curation
	EntryPath  string // catalog path of the merged entry
	Recalls    int    // times the entry answered an incident via instant recall
	Resolved   int    // recalls followed by an incident-resolved signal
}

type ProgressNotifier interface {
	DeliverProgress(ctx context.Context, up ProgressUpdate) error
}

type ProgressUpdate struct {
	Title     string         // incident title (untrusted alert text)
	Step      int            // current step (1-based)
	MaxSteps  int            // step ceiling
	ToolsUsed map[string]int // investigation tool name → call count so far
	Interim   string         // model's latest interim assistant text (already secret-redacted), if any
}

type Ref struct{ URL string }

type ReinvestForge interface {
	// ListIssuesByLabel returns open issues carrying the given label.
	ListIssuesByLabel(ctx context.Context, label string) ([]CuratedIssue, error)
	// Comment posts a comment on an issue.
	Comment(ctx context.Context, number int, body string) error
	// ReplaceLabel removes one label and adds another (lifecycle transition);
	// either side may be empty to only add or only remove.
	ReplaceLabel(ctx context.Context, number int, remove, add string) error
}

type RelatedEntry struct {
	Path     string // bundle-relative entry path (the forge renders the web link)
	Title    string
	Resource string  // affected resource, when the entry names one
	Score    float64 // BM25 score at draft time (corpus-relative — a hint, not a ranking guarantee)
}

type ResourceStatus struct {
	Workload Workload
	NotFound bool              // the object does not exist (often the cascade root)
	Ready    string            // Ready condition status: "True"/"False"/"Unknown"/""
	Reason   string            // Ready condition reason
	Message  string            // Ready condition message
	Refs     map[string]string // key spec references (e.g. sourceRef, dependsOn)
	Events   []string          // recent Event lines (type/reason/message)
}

type Sample struct {
	Metric map[string]string
	Value  float64
	Time   time.Time
}

type Samples []Sample

type Selector struct {
	Namespace string
	Kind      string
	Name      string
}

type Series struct {
	Metric map[string]string
	Points []Point
}

type SourceRef struct {
	RepoURL string
	Path    string
}

type TimeWindow struct {
	Start time.Time
	End   time.Time
}

type ToolCall struct {
	ID   string
	Name string
	Args string // JSON
}

type ToolSpec struct {
	Name        string
	Description string
	Schema      string // JSON Schema
}

type Usage struct {
	InputTokens  int // total prompt/input tokens billed, INCLUDING any served from cache (normalized across providers)
	OutputTokens int // generated/output tokens in the reply
	// CachedInputTokens is the subset of InputTokens that was a cache READ (Anthropic
	// cache_read_input_tokens, OpenAI prompt_tokens_details.cached_tokens, Gemini
	// cachedContentTokenCount) — the saving. 0 when the provider reports none.
	CachedInputTokens int
	// CacheWriteTokens is input tokens WRITTEN to the cache this request (Anthropic
	// cache_creation_input_tokens, billed ~1.25x). 0 for providers that don't report it.
	CacheWriteTokens int
}

type UsageTotals struct {
	ModelCalls        int     // number of model completions made
	InputTokens       int     // total input/prompt tokens, INCLUDING any served from cache (mirrors Usage.InputTokens)
	OutputTokens      int     // total generated/output tokens
	CachedInputTokens int     // subset of InputTokens that was a cache read (the saving)
	CostUSD           float64 // estimated cost; meaningful only when Priced (model.pricing configured)
	Priced            bool    // pricing was configured, so CostUSD is populated (may legitimately be 0)
}

type Verdict string

type Workload struct {
	Kind      string
	Name      string
	Namespace string
}