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 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
}

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
}

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 Engine string

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

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
	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)
	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 (alert fingerprint, or failing resource+condition) set at trigger time; curator.DupFingerprint prefers it so reworded re-investigations of one incident still dedupe (#137)
	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
}

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)
}

type KubeEvent struct {
	Type    string // Normal | Warning
	Reason  string
	Object  string // Kind/Name
	Message string
	Count   int32
}

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 LogLine struct {
	Time    time.Time
	Message string
	Fields  map[string]string
}

type LogReader interface {
	// PodLogs returns recent log lines from pods matching labelSelector in
	// namespace, bounded to the last sinceMinutes (0 = no lower bound).
	PodLogs(ctx context.Context, namespace, labelSelector string, sinceMinutes int) (LogResult, error)
}

type LogResult []LogLine

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

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
}

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)
}

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

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 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 …"
}

type Point struct {
	Time  time.Time
	Value float64
}

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 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 // prompt/input tokens billed for the request
	OutputTokens int // generated/output tokens in the reply
}

type Workload struct {
	Kind      string
	Name      string
	Namespace string
}