storage

type AnalysisRecord struct {
	ID string `json:"id"`
	// OrgID scopes the analysis to one organization. Defaults to
	// storage.DefaultOrgID ("default"); see IncidentRecord.OrgID.
	OrgID       string    `json:"org_id,omitempty"`
	IncidentID  string    `json:"incident_id"`
	RequestedAt time.Time `json:"requested_at"`
	RequestedBy string    `json:"requested_by,omitempty"`
	DurationMs  int64     `json:"duration_ms,omitempty"`
	Model       string    `json:"model,omitempty"`

	// ToolCalls is the full audit trail of read-only tool invocations
	// the agent issued during the run, in execution order.
	ToolCalls []AnalysisToolCall `json:"tool_calls,omitempty"`

	// Finding is the parsed structured output from the model. Nil when
	// the run failed before the model produced JSON.
	Finding *core.AIFinding `json:"finding,omitempty"`

	// RawResponse is the model's final assistant message. Kept for
	// audit / debugging when ParseFinding fails.
	RawResponse string `json:"raw_response,omitempty"`

	// Status is one of: "ok", "error", "rate_limited".
	Status string `json:"status"`
	Error  string `json:"error,omitempty"`
}

type AnalysisToolCall struct {
	Name       string          `json:"name"`
	Args       json.RawMessage `json:"args,omitempty"`
	Output     json.RawMessage `json:"output,omitempty"`
	DurationMs int64           `json:"duration_ms,omitempty"`
	Error      string          `json:"error,omitempty"`
}

type Blob struct {
	Name string
	Data []byte
}

type BlobCreator interface {
	// CreateBlobIfAbsent atomically writes data under key only if key does
	// not already exist. It returns written==true when THIS call created the
	// blob, and written==false when the key already existed — because a
	// concurrent or prior writer won the race, OR because the key was set by
	// an earlier WriteBlob. On written==false the stored bytes are left
	// untouched: the caller re-reads them via ReadBlob(key) to adopt the
	// surviving value. After a nil-error return the blob is durably present,
	// so ReadBlob(key) observes the one surviving set of bytes regardless of
	// which caller won.
	CreateBlobIfAbsent(key string, data []byte) (written bool, err error)
}

type Config struct {
	Type     string // file | redis | database | postgres (default: file)
	File     FileOptions
	Redis    RedisOptions
	Database DatabaseOptions
	Postgres PostgresOptions
}

type DatabaseOptions struct {
	Driver string // postgres | mysql | sqlite
	DSN    string
}

type FileOptions struct {
	DataDir      string // default DefaultDataDir
	MaxIncidents int    // default MaxIncidentsDefault
}

type IncidentRecord struct {
	ID string `json:"id"`
	// OrgID scopes the record to one organization. Defaults to
	// storage.DefaultOrgID ("default") so single-tenant OSS users never
	// see or set it; enterprise multi-tenant routing reads it to isolate
	// orgs.
	OrgID   string `json:"org_id,omitempty"`
	TeamID  string `json:"team_id,omitempty"`
	Title   string `json:"title,omitempty"`
	Source  string `json:"source,omitempty"`  // "webhook" | "sns" | "sqs" | ...
	Service string `json:"service,omitempty"` // best-effort from payload
	// Origin is the coarse classifier for how the incident entered the
	// system: OriginAIDetect (agent detect emit) or OriginWebhook
	// (inbound alert ingestion). Stamped at creation on both paths. Legacy
	// records persisted before this field default to empty on disk;
	// EffectiveOrigin derives a value from Source so they are never
	// miscounted.
	Origin   string `json:"origin,omitempty"`
	Resolved bool   `json:"resolved"`
	// ChannelsEnabled is the snapshot of channels that were configured
	// when the alert fired. ChannelsNotified is the subset that
	// actually succeeded. The two diverge whenever a channel fails:
	// keep both so the UI can show "Slack failed" without losing the
	// fact that Slack was supposed to be tried.
	ChannelsEnabled  []string `json:"channels_enabled,omitempty"`
	ChannelsNotified []string `json:"channels_notified,omitempty"`
	OnCallTriggered  bool     `json:"oncall_triggered,omitempty"`
	OnCallError      string   `json:"oncall_error,omitempty"`
	// NotifyStatus reflects the outcome of the alert fan-out:
	// "pending" — record persisted, fan-out not yet attempted
	// "sent"    — every enabled channel returned success
	// "partial" — at least one channel succeeded, at least one failed
	// "failed"  — no channel succeeded
	NotifyStatus string                 `json:"notify_status,omitempty"`
	NotifyError  string                 `json:"notify_error,omitempty"`
	CreatedAt    time.Time              `json:"created_at"`
	AckedAt      *time.Time             `json:"acked_at,omitempty"`
	ResolvedAt   *time.Time             `json:"resolved_at,omitempty"`
	Content      map[string]interface{} `json:"content,omitempty"`

	// AssignedTeamID and AssignedMemberIDs record an operator's
	// assignment for this incident. Routing logic will read
	// these to pick channels per assignee; the storage layer only
	// holds the references. Empty means unassigned.
	AssignedTeamID    string   `json:"assigned_team_id,omitempty"`
	AssignedMemberIDs []string `json:"assigned_member_ids,omitempty"`
}

type Lifecycle interface {
	// PurgeOlderThan deletes every record in domain whose natural age
	// column is strictly older than cutoff, returning the number deleted.
	// The compared column is fixed per domain (see DomainIncidents /
	// DomainAnalyses / DomainBlobs). An unknown domain returns
	// ErrUnknownDomain and deletes nothing.
	PurgeOlderThan(domain string, cutoff time.Time) (int, error)
	// DeleteByID deletes one record from domain by its primary key — an
	// incident/analysis id, or a blob name. Returns ErrNotFound when the
	// id is unknown and ErrUnknownDomain for a domain outside the fixed
	// set.
	DeleteByID(domain, id string) error
}

type ModelState struct {
	OrgID     string    `json:"org_id"`
	Agent     string    `json:"agent"`
	Key       string    `json:"key"`
	Version   int       `json:"version"`
	UpdatedAt time.Time `json:"updated_at"`
	// Data is the opaque, consumer-defined payload, stored verbatim.
	Data []byte `json:"data"`
}

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

type PostgresOptions struct {
	DSN string // postgres connection string or DSN URL
}

type Provider interface {
	// ReadBlob returns the contents previously written under name.
	// Missing blobs MUST return (nil, nil) — not ErrNotFound — so the
	// agent's "fresh start" path stays a single line.
	ReadBlob(name string) ([]byte, error)
	// WriteBlob atomically replaces the blob stored under name.
	WriteBlob(name string, data []byte) error
	// ListBlobs returns every blob whose name begins with prefix, as
	// (name, data) pairs in no guaranteed order. It is the enumeration
	// primitive the model-state seam (ModelStore.List) rides to list all
	// learned artifacts under a namespace (models/<org>/<agent>/…). A
	// prefix that matches nothing returns an empty result, never
	// ErrNotFound, mirroring the ReadBlob "fresh start" contract. The
	// returned Data slices are copies the caller owns. The list is
	// unbounded — a namespace is naturally bounded per org × agent (one
	// artifact per learned key), so callers that need a cap apply it.
	ListBlobs(prefix string) ([]Blob, error)

	// SaveIncident appends a new incident to the store. Subsequent
	// SaveIncident calls with the same ID overwrite the existing record
	// (used by the ack path). The file backend caps its single-file
	// history at MaxIncidents (dropping the oldest on save); database
	// backends keep history unbounded and rely on storage.Lifecycle for
	// retention instead.
	SaveIncident(rec *IncidentRecord) error
	// UpdateIncidentAck stamps an existing incident as acknowledged.
	// Returns ErrNotFound when the id is unknown.
	UpdateIncidentAck(id string, ackedAt time.Time) error
	// GetIncident returns one incident or ErrNotFound.
	GetIncident(id string) (*IncidentRecord, error)
	// ListIncidents returns the most recent incidents, newest first.
	// limit <= 0 returns the full window.
	ListIncidents(limit int) ([]*IncidentRecord, error)

	// SaveAnalysis stores (or replaces by ID) one analyze-mode run.
	SaveAnalysis(rec *AnalysisRecord) error
	// GetAnalysis returns one analysis or ErrNotFound.
	GetAnalysis(id string) (*AnalysisRecord, error)
	// ListAnalysesByIncident returns all analyses for one incident,
	// newest first. limit <= 0 returns the full window.
	ListAnalysesByIncident(incidentID string, limit int) ([]*AnalysisRecord, error)
	// ListAnalyses returns analyses across all incidents, newest first.
	// limit <= 0 returns the full window.
	ListAnalyses(limit int) ([]*AnalysisRecord, error)
	// DeleteAnalysis removes one analysis. Returns ErrNotFound when the
	// id is unknown.
	DeleteAnalysis(id string) error

	// Close releases any underlying resources (file handles, redis
	// connections, db pools). Calling Close on a closed provider is a
	// no-op.
	Close() error
}

type RangeLister interface {
	// ListIncidentsInRange returns incidents with start <= CreatedAt < end,
	// newest first. limit <= 0 returns the full window. A zero end is
	// treated as an open upper bound (all incidents at or after start).
	ListIncidentsInRange(start, end time.Time, limit int) ([]*IncidentRecord, error)
}

type RedisOptions struct {
	Host               string
	Port               int
	Password           string
	DB                 int
	InsecureSkipVerify bool
	KeyPrefix          string
	MaxIncidents       int
}

type SQLAccessor interface {
	// DB returns the live *sql.DB backing this Provider. Never nil for a
	// backend that implements SQLAccessor.
	DB() *sql.DB
}

type Searcher interface {
	// SearchIncidents returns incidents whose title, service, source,
	// or JSON body match the case-insensitive query, newest first.
	// An empty query returns the most recent incidents (same as
	// ListIncidents). limit <= 0 returns the full window.
	SearchIncidents(query string, limit int) ([]*IncidentRecord, error)
	// SearchAnalyses returns analyses whose JSON body matches the
	// case-insensitive query, newest first. limit <= 0 returns the
	// full window.
	SearchAnalyses(query string, limit int) ([]*AnalysisRecord, error)
}