obsbackend

type AddIssueCommentRequest struct {
	ID   string
	Body string
}

type AddIssueCommentResult struct {
	Comment IssueComment
}

type Alert struct {
	Rule        string            `json:"rule"`
	State       string            `json:"state"`
	Fingerprint string            `json:"fingerprint,omitempty"`
	Labels      map[string]string `json:"labels,omitempty"`
	// Summary is the rule's summary annotation, when it has one.
	Summary string `json:"summary,omitempty"`
	// Why is the alert's why-fired payload (alerting.Why), as the control
	// plane carries it in the `why` annotation. Nil for an alert whose rule
	// attaches none.
	Why      json.RawMessage `json:"why,omitempty"`
	ActiveAt time.Time       `json:"active_at,omitzero"`
	FiringAt time.Time       `json:"firing_at,omitzero"`
	Value    float64         `json:"value"`
}

type AlertReader interface {
	Alerts(ctx context.Context) ([]Alert, error)
}

type AssignIssueRequest struct {
	ID       string
	Assignee string
}

type AssignIssueResult struct {
	Issue Issue
}

type AssignmentChange struct {
	From, To *IssueUser
}

type Backend interface {
	Info() Info
	Logs(ctx context.Context, req LogsRequest) (LogsResult, error)
	Traces(ctx context.Context, req TracesRequest) (TracesResult, error)
	Trace(ctx context.Context, req TraceRequest) (TraceResult, error)
	Endpoints(ctx context.Context, req EndpointsRequest) (EndpointsResult, error)
	MetricsList(ctx context.Context, req MetricsListRequest) (MetricsListResult, error)
	MetricsQuery(ctx context.Context, req MetricsQueryRequest) (MetricsQueryResult, error)
	MetricsDescribe(ctx context.Context, req MetricsDescribeRequest) (MetricsDescribeResult, error)
	MetricsExemplars(ctx context.Context, req MetricsExemplarsRequest) (MetricsExemplarsResult, error)
	Query(ctx context.Context, req QueryRequest) (QueryResult, error)
}

type Caller interface {
	Call(ctx context.Context, procedure string, req, out any) error
}

type Change struct {
	Kind        string    `json:"kind"`
	At          time.Time `json:"at"`
	Summary     string    `json:"summary"`
	Version     string    `json:"version,omitempty"`
	PromotionID string    `json:"promotion_id,omitempty"`
	Direction   string    `json:"direction,omitempty"`
	Verb        string    `json:"verb,omitempty"`
	Target      string    `json:"target,omitempty"`
	Actor       string    `json:"actor,omitempty"`
	Via         string    `json:"via,omitempty"`
}

type ChangesReader interface {
	Changes(ctx context.Context, req ChangesRequest) (ChangesResult, error)
}

type ChangesRequest struct {
	Env string
	// Range bounds the rows, newest first.
	Range Range
	Limit int
	// Project is the forge project whose promotions are listed (cloud).
	Project string
}

type ChangesResult struct {
	Changes []Change
	// Omitted counts rows the Limit cut.
	Omitted int
	// Current is the promotion in force at the end of the range, whether or
	// not it falls inside it; nil when the env has none on record.
	Current *Change
	// CurrentUnsettled says Current's rollout had not been reported finished:
	// a promotion is intent, and the env may still be serving the one before.
	CurrentUnsettled bool
	Warnings         []string
}

type ChatLink struct {
	ChatID    string
	ChatTitle string
	LinkedBy  *IssueUser
	LinkedAt  time.Time
}

type Cloud struct {
	Env   string
	EnvID string
	OrgID string
	// ProjectID is the control plane's own id for the project, when the
	// checkout is bound to it; "" leaves ResolveProjectID to ask.
	ProjectID string
	Caller    Caller
}

type Column struct {
	Name string `json:"name"`
	Type string `json:"type"`
}

type ComposeFunc func(ctx context.Context, projectDir string, args ...string) ([]byte, error)

type DashboardDocument struct {
	Info    DashboardInfo
	Spec    json.RawMessage
	Version int
}

type DashboardInfo struct {
	Ref DashboardRef
	// Title is the dashboard's title.
	Title string
	// Source is "generated", "repo", "workspace", "template" or "builtin".
	Source     string
	PanelCount int
	// ReleaseVersion is the release that shipped a release dashboard.
	ReleaseVersion string
	// Typed marks a server-owned view (organization costs) that has no panel
	// spec to run.
	Typed bool
}

type DashboardReader interface {
	ListDashboards(ctx context.Context, project string) ([]DashboardInfo, error)
	GetDashboard(ctx context.Context, ref DashboardRef) (DashboardDocument, error)
	QueryPanelReadout(ctx context.Context, req PanelReadoutRequest) (PanelReadout, error)
}

type DashboardRef struct {
	Source    string
	ProjectID string
	Key       string
}

type Decision struct {
	Backend string
	// Reason is one line a human header can show: "no destination: host
	// processes feed the local ClickStack".
	Reason string
}

type DeliveriesResult struct {
	// Enabled says the control plane's delivery reconciler is on; when it is
	// off nothing keeps any token valid.
	Enabled    bool
	Deliveries []TelemetryDelivery
}

type DeliveryReader interface {
	TelemetryDeliveries(ctx context.Context) (DeliveriesResult, error)
}

type Destination struct {
	Endpoint string
	// TokenFromControlPlane marks the destination as the Reliant control
	// plane's own telemetry intake.
	TokenFromControlPlane bool
}

type DockerRunner struct {
	Exec ExecFunc
	// Env names the env in the remedy commands of a "not running" error.
	Env string
}

type Endpoint struct {
	Service       string
	Name          string
	Requests      float64
	Errors        float64
	ErrorRatio    float64
	RatePerSecond float64
	P50Ms         float64
	P95Ms         float64
	P99Ms         float64
}

type EndpointsRequest struct {
	Narrow
	// Sort is "requests" (default), "p95", "errors" or "rate".
	Sort string
	Top  int
}

type EndpointsResult struct {
	Endpoints []Endpoint
	// Omitted counts endpoints the Top cap cut.
	Omitted    int
	Statements []Statement
}

type Error struct {
	Code int
	Msg  string
	// Suggested are complete, runnable commands that remedy the failure.
	Suggested []string
	Err       error
}

type ExecFunc func(ctx context.Context, script string, args []string) ([]byte, error)

type Facts struct {
	Env string
	// Declared is false when the env has no observability block at all;
	// Enabled is the block's own switch.
	Declared, Enabled bool
	// Destination is the env's declared telemetry destination; nil sends
	// host processes to the local ClickStack.
	Destination *Destination
	// HasHosted is true when anything in the env is bound to forge.OnHosted.
	HasHosted bool
	// HasLocal is true when a workload of the env runs on this machine (host
	// process or docker compose): only then can the local ClickStack hold its
	// telemetry. An env whose workloads all deploy to a cluster has none.
	HasLocal bool
	// HasCluster is true when a workload deploys to a declared cluster.
	// Without local workloads, its services are reached through ControlPlane,
	// not through this machine's ClickStack. It does not imply hosted runtime.
	HasCluster bool
	// LocalLifecycle is the env's explicit local/ephemeral lifecycle. Local
	// host processes may share that scratch env with a developer's cluster.
	LocalLifecycle bool
	// ControlPlane is the env's control_plane endpoint; "" when it declares none.
	ControlPlane string
	// ReleaseHealth is the env's recorded release-health policy; nil means
	// every default.
	ReleaseHealth *release.ShapeReleaseHealth
}

type Failure struct {
	Class FailureClass
	// Code is the Connect code's wire name; Reason the control plane's
	// domain reason. Either may be empty.
	Code   string
	Reason string
	// HTTPStatus is the response status (0: none came back).
	HTTPStatus int
	// Message is the control plane's own text.
	Message string
	// MissingScope names the scope a 403 says the credential lacks.
	MissingScope string
	// RetryAfter is how long the control plane asked to wait; ResetsAt when a
	// spent quota refills. Zero when it said neither.
	RetryAfter time.Duration
	ResetsAt   time.Time
}

type FailureClass string

type Filter struct {
	Key   string
	Value string
	Not   bool
}

type GetIssueRequest struct {
	Narrow
	ID string
}

type GetIssueResult struct {
	Issue       Issue
	LatestEvent *IssueEvent
	Frames      []IssueFrame
	ByVersion   []IssueVersion
	// CoOccurring are the ids of issues that fired in the same traces.
	CoOccurring []string
	// Incident are the ids of the other issues of this issue's incident (the
	// same cause, first fired close in time), when it is part of one.
	Incident     []string
	FirstRelease *IssueRelease
	Statements   []Statement
}

type GetSessionRequest struct {
	Narrow
	ID string
	// Limit is the timeline page size; PageToken resumes it.
	Limit     int
	PageToken string
}

type GetSessionResult struct {
	Session       SessionSummary
	Timeline      []SessionEntry
	NextPageToken string
	Statements    []Statement
}

type HealthReader interface {
	ReleaseHealth(ctx context.Context, req HealthRequest) (HealthResult, error)
}

type HealthRequest struct {
	// Cloud: the promotion to judge, by id or by release version. Both empty
	// means the env's current promotion.
	PromotionID string
	Release     string
	// Local: the instant to judge from. There are no promotions locally, so
	// the caller names one (`--since`, or the start of the last `forge env up`).
	PromotedAt time.Time
	// Now is the clock.
	Now time.Time
	// Options pick the thresholds. Local applies them all; cloud sends the
	// window and the named overrides and leaves fail_on to the caller
	// (releasehealth.Rejudge).
	Options releasehealth.Options
}

type HealthResult struct {
	Report releasehealth.Report
	// Statements are what a local judgement ran.
	Statements []Statement
}

type Info struct {
	Env     string
	Backend string
	// EnvID is the control plane's id for the env, on the cloud backend.
	EnvID string
}

type Issue struct {
	// ID is what `forge obs issue <id>` takes: "sfp1-<fingerprint>" locally,
	// the control plane's id in the cloud.
	ID       string
	Platform string
	// Source is the issue source (obsquery.LogKeyIssueSource) its events
	// carry; "" for an error.
	Source string
	// EnvID is the control plane's id for the issue's environment (cloud only).
	EnvID         string
	Service       string
	Fingerprint   string
	Title         string
	Culprit       string
	ExceptionType string
	Status        string
	FirstSeen     time.Time
	LastSeen      time.Time
	FirstVersion  string
	LastVersion   string
	// Events and Affected are over the queried range. Affected counts
	// AffectedUnit: users when the issue's events name them, else the chats,
	// threads or workflows they ran for, else traces (server) or sessions
	// (browser). Never a bare number: an unknown unit is "".
	Events       int64
	Affected     int64
	AffectedUnit string

	ResolvedAt      time.Time
	ResolvedVersion string
	RegressedAt     time.Time
	IgnoredUntil    time.Time
	// Version is the row version a triage write must echo; 0 locally.
	Version int32
	// LatestTraceID is the trace of the newest event, when the list knows it
	// (the local grouping does; the control plane answers it in GetIssue).
	LatestTraceID string
	// Assignee is who the issue is assigned to; nil when unassigned (always
	// nil locally).
	Assignee *IssueUser
	// IncidentKey is shared by the issues of one incident: issues with the
	// same cause (obsquery.ServerCause) that first fired within a window of
	// one another. Empty for an issue that is not part of one. RelatedCount
	// is how many OTHER issues carry the same key. Issues are never merged.
	IncidentKey  string
	RelatedCount int
}

type IssueActor struct {
	Kind string
	ID   string
	Name string
}

type IssueComment struct {
	ID        string
	IssueID   string
	Author    *IssueUser
	Body      string
	CreatedAt time.Time
	UpdatedAt time.Time
}

type IssueEvent struct {
	Time       time.Time
	TraceID    string
	SpanID     string
	Version    string
	Message    string
	Attributes map[string]string
	SessionID  string
	URLPath    string
}

type IssueFrame struct {
	Function string
	File     string
	Line     int
	InApp    bool
}

type IssueReader interface {
	ListIssues(ctx context.Context, req ListIssuesRequest) (ListIssuesResult, error)
	GetIssue(ctx context.Context, req GetIssueRequest) (GetIssueResult, error)
	ListIssueEvents(ctx context.Context, req ListIssueEventsRequest) (ListIssueEventsResult, error)
	UpdateIssueStatus(ctx context.Context, req UpdateIssueStatusRequest) (UpdateIssueStatusResult, error)
	ListIssueTimeline(ctx context.Context, req ListIssueTimelineRequest) (ListIssueTimelineResult, error)
	AddIssueComment(ctx context.Context, req AddIssueCommentRequest) (AddIssueCommentResult, error)
	AssignIssue(ctx context.Context, req AssignIssueRequest) (AssignIssueResult, error)
}

type IssueRelease struct {
	Version     string
	GitCommit   string
	CommitRange string
	PromotedAt  time.Time
}

type IssueUser struct {
	ID   string
	Name string
}

type IssueVersion struct {
	Version      string
	Events       int64
	Affected     int64
	AffectedUnit string
	FirstSeen    time.Time
	LastSeen     time.Time
}

type Job struct {
	EnvName    string    `json:"env_name,omitempty"`
	Name       string    `json:"name"`
	Workload   string    `json:"workload,omitempty"`
	Result     string    `json:"result"`
	Reason     string    `json:"reason,omitempty"`
	Release    string    `json:"release,omitempty"`
	StartedAt  time.Time `json:"started_at,omitzero"`
	FinishedAt time.Time `json:"finished_at,omitzero"`
	Seconds    int64     `json:"duration_seconds,omitempty"`
}

type KV struct{ Key, Value string }

type LedgerReader interface {
	releasetimeline.LedgerReader
	SessionsFor(env string) ([]release.LocalSession, error)
}

type Limits struct {
	Timeout time.Duration
	// MaxRows is the result row cap; 0 = none.
	MaxRows int
	// Break ends the result at MaxRows (a partial result) instead of failing
	// the statement. Raw SQL uses it so a wide SELECT returns its first rows.
	Break bool
}

type ListIssueEventsRequest struct {
	Narrow
	ID    string
	Limit int
}

type ListIssueEventsResult struct {
	Events        []IssueEvent
	NextPageToken string
	Truncated     bool
	Statements    []Statement
}

type ListIssueTimelineRequest struct {
	ID    string
	Limit int
}

type ListIssueTimelineResult struct {
	Entries []TimelineEntry
	// IssueID is the issue the timeline is of: the requested one, or the one
	// it was merged into.
	IssueID string
	// Omitted counts older entries the Limit cut.
	Omitted int
}

type ListIssuesRequest struct {
	Narrow
	// Statuses filters on these (IssueStatuses); empty is the open ones.
	Statuses []string
	// Platform is "", PlatformServer or PlatformBrowser.
	Platform string
	// Source lists the issues of this issue source; "" lists errors.
	Source string
	// Assignee keeps issues assigned to this user id, or "me" (the verified
	// credential's acting user). Empty keeps every issue unless Unassigned.
	Assignee string
	// Unassigned keeps issues with no assignee; exclusive with Assignee.
	Unassigned bool
	// SinceRelease keeps issues first seen in this release version.
	SinceRelease string
	// SincePromotion keeps issues first seen at or after this promotion.
	SincePromotion string
	Sort           string
	Limit          int
	PageToken      string
	// IncidentWindow is how close in first-seen time issues of one cause must
	// be to share an incident; zero is obsquery.DefaultIncidentWindow.
	IncidentWindow time.Duration
}

type ListIssuesResult struct {
	Issues []Issue
	// NextPageToken resumes the cloud list. A local list has no pages:
	// Truncated says the Limit cut it.
	NextPageToken string
	Truncated     bool
	Statements    []Statement
}

type ListSessionsRequest struct {
	Narrow
	HasError  bool
	HasReplay bool
	// UserID keeps one user's sessions; PathContains those whose entry path
	// contains it, case-insensitively.
	UserID       string
	PathContains string
	Limit        int
	PageToken    string
}

type ListSessionsResult struct {
	Sessions      []SessionSummary
	NextPageToken string
	Statements    []Statement
}

type Local struct {
	Env    string
	Runner Runner
	// Ledger opens this machine's release ledger, for `forge obs changes`.
	// Nil when the caller has none; a read that needs it then fails with a
	// remedy rather than a panic.
	Ledger func() (LedgerReader, error)
	// Declared reads the metrics schemas this project declares
	// (bin/observability/metrics-schema.json), for `forge obs metrics list`
	// and `describe`. Nil when the caller has none.
	Declared func() []metrics.Schema
}

type LogRecord struct {
	Time           time.Time
	Severity       string
	SeverityNumber int
	Service        string
	Body           string
	TraceID        string
	SpanID         string
	Attributes     map[string]string
	// Hash is the keyset hash of the row (follow mode resumes from it).
	Hash uint64
}

type LogsRequest struct {
	Narrow
	Query      string
	Severities []string
	TraceID    string
	Oldest     bool
	Limit      int
	PageToken  string
}

type LogsResult struct {
	Logs          []LogRecord
	NextPageToken string
	Statements    []Statement
}

type MetricAttribute struct {
	Key      string
	Resource bool
	// DistinctEstimate is the estimated number of values over the range.
	DistinctEstimate int64
	// Enumerated is the declared closed value set; empty when open.
	Enumerated []string
	// HighCardinality: grouping by the key could exceed the series cap.
	HighCardinality bool
}

type MetricAttributeSpec struct {
	Key    string
	Values []string
}

type MetricExemplar struct {
	Time       time.Time
	Value      float64
	TraceID    string
	SpanID     string
	Attributes map[string]string
	// TraceStored: the trace is in the trace store. false means it was sampled
	// out and the trace view would be empty.
	TraceStored bool
}

type MetricInfo struct {
	Name        string
	Unit        string
	Description string
	// Type is "gauge", "sum", "histogram", "exp_histogram" or "summary".
	Type string
	// Monotonic is a sum that is a counter, not an up-down counter.
	Monotonic bool
	// Temporality is "delta", "cumulative", or "" (a gauge, or not known).
	Temporality string
	// Services are up to 10 service.name values that emit it; ServiceCount is
	// how many do.
	Services     []string
	ServiceCount int
	// LastSeen is the newest data point in the catalog range; zero for a
	// declared metric never seen.
	LastSeen       time.Time
	SeriesEstimate int64
	// Queryable is false for a kind the evaluator cannot run yet.
	Queryable bool
	Builtin   bool
	// Declared: the release's metrics schema lists it. Seen: it has data in
	// the range.
	Declared, Seen bool
	// Stability is "stable", "experimental" or "deprecated"; empty when not
	// declared.
	Stability          string
	DeclaredAttributes []MetricAttributeSpec
}

type MetricMeta struct {
	Label  string
	Metric string
	// Type is "gauge", "sum" or "histogram".
	Type        string
	Monotonic   bool
	Temporality string
	// Agg is the dashspec aggregation after defaulting: rate, increase, sum,
	// avg, min, max, last, count or quantile.
	Agg       string
	Quantile  float64
	ValueUnit string
}

type MetricPoint struct {
	Time          time.Time
	Value         float64
	Null, Partial bool
}

type MetricSeries struct {
	Label   string
	Labels  map[string]string
	Points  []MetricPoint
	Reduced *float64
}

type MetricsCompare struct {
	Offset      time.Duration
	From, To    time.Time
	Series      []MetricSeries
	SeriesTotal int
}

type MetricsDescribeRequest struct {
	Narrow
	Name string
}

type MetricsDescribeResult struct {
	Info MetricInfo
	// IntervalSeconds estimates the export interval: the floor of a useful
	// step. 0 when it cannot be estimated.
	IntervalSeconds  int64
	MixedTemporality bool
	Attributes       []MetricAttribute
	// SuggestedBreakdowns are the attribute keys worth grouping by, best first.
	SuggestedBreakdowns []string
	Statements          []Statement
}

type MetricsExemplarsRequest struct {
	Narrow
	Name     string
	From, To time.Time
	// Where narrows to series matching the predicates (panel vocabulary).
	Where []obsquery.PanelPredicate
	// Group narrows to one series group: group-by key to value.
	Group    map[string]string
	MinValue *float64
	Limit    int
}

type MetricsExemplarsResult struct {
	Exemplars  []MetricExemplar
	Statements []Statement
}

type MetricsListRequest struct {
	Narrow
	NameContains string
	Limit        int
}

type MetricsListResult struct {
	Metrics    []MetricInfo
	Truncated  bool
	Statements []Statement
}

type MetricsQueryRequest struct {
	Narrow
	Panel       obsquery.Panel
	StepSeconds int64
	// MaxSeries lowers the series cap (the most groups per series label).
	MaxSeries int
	// Compare, when positive, runs the panel a second time over the range
	// shifted back by this much; Result.Compare carries it.
	Compare time.Duration
}

type MetricsQueryResult struct {
	Meta   []MetricMeta
	Series []MetricSeries
	// SeriesTotal is how many groups matched before the series cap.
	SeriesTotal int
	Truncated   bool
	StepSeconds int64
	// Warnings are stable codes: mixed_bounds, mixed_temporality,
	// step_raised, metric_stored_as_n_kinds, metric_absent,
	// metric_kind_mismatch.
	Warnings   []string
	Compare    *MetricsCompare
	Statements []Statement
}

type MockAlertReader struct {
	contractkit.Recorder
	AlertsFunc func(context.Context) ([]Alert, error)
}

type MockBackend struct {
	contractkit.Recorder
	InfoFunc             func() Info
	LogsFunc             func(context.Context, LogsRequest) (LogsResult, error)
	TracesFunc           func(context.Context, TracesRequest) (TracesResult, error)
	TraceFunc            func(context.Context, TraceRequest) (TraceResult, error)
	EndpointsFunc        func(context.Context, EndpointsRequest) (EndpointsResult, error)
	MetricsListFunc      func(context.Context, MetricsListRequest) (MetricsListResult, error)
	MetricsQueryFunc     func(context.Context, MetricsQueryRequest) (MetricsQueryResult, error)
	MetricsDescribeFunc  func(context.Context, MetricsDescribeRequest) (MetricsDescribeResult, error)
	MetricsExemplarsFunc func(context.Context, MetricsExemplarsRequest) (MetricsExemplarsResult, error)
	QueryFunc            func(context.Context, QueryRequest) (QueryResult, error)
}

type MockChangesReader struct {
	contractkit.Recorder
	ChangesFunc func(context.Context, ChangesRequest) (ChangesResult, error)
}

type MockDashboardReader struct {
	contractkit.Recorder
	ListDashboardsFunc    func(context.Context, string) ([]DashboardInfo, error)
	GetDashboardFunc      func(context.Context, DashboardRef) (DashboardDocument, error)
	QueryPanelReadoutFunc func(context.Context, PanelReadoutRequest) (PanelReadout, error)
}

type MockDeliveryReader struct {
	contractkit.Recorder
	TelemetryDeliveriesFunc func(context.Context) (DeliveriesResult, error)
}

type MockHealthReader struct {
	contractkit.Recorder
	ReleaseHealthFunc func(context.Context, HealthRequest) (HealthResult, error)
}

type MockIssueReader struct {
	contractkit.Recorder
	ListIssuesFunc        func(context.Context, ListIssuesRequest) (ListIssuesResult, error)
	GetIssueFunc          func(context.Context, GetIssueRequest) (GetIssueResult, error)
	ListIssueEventsFunc   func(context.Context, ListIssueEventsRequest) (ListIssueEventsResult, error)
	UpdateIssueStatusFunc func(context.Context, UpdateIssueStatusRequest) (UpdateIssueStatusResult, error)
	ListIssueTimelineFunc func(context.Context, ListIssueTimelineRequest) (ListIssueTimelineResult, error)
	AddIssueCommentFunc   func(context.Context, AddIssueCommentRequest) (AddIssueCommentResult, error)
	AssignIssueFunc       func(context.Context, AssignIssueRequest) (AssignIssueResult, error)
}

type MockOverviewReader struct {
	contractkit.Recorder
	OverviewFunc func(context.Context, OverviewRequest) (OverviewResult, error)
}

type MockSessionReader struct {
	contractkit.Recorder
	ListSessionsFunc func(context.Context, ListSessionsRequest) (ListSessionsResult, error)
	GetSessionFunc   func(context.Context, GetSessionRequest) (GetSessionResult, error)
}

type Narrow struct {
	Range    Range
	Services []string
	Filters  []Filter
	// Explain compiles the final statements without running them; the result
	// carries them in Statements.
	Explain bool
	// Now is the clock a metrics read marks partial buckets against; zero is
	// time.Now(). The CLI sets it so a golden is deterministic.
	Now time.Time
}

type OverviewReader interface {
	Overview(ctx context.Context, req OverviewRequest) (OverviewResult, error)
}

type OverviewRequest struct {
	Narrow
}

type OverviewResult struct {
	Services   []ServiceOverview
	Statements []Statement
}

type PanelReadout struct {
	// Kind echoes the panel kind the control plane ran.
	Kind string
	// StepSeconds is the bucket width the control plane used (0: the kind has
	// no time axis).
	StepSeconds int64
	// Series and Rows are how many entries the answer carries; Points is the
	// points across all series, NonNull those that hold a value, NonZero those
	// (and table cells, and number figures) that are not zero.
	Series, Rows, Points, NonNull, NonZero int
	// Buckets is how many distinct bucket times hold a drawable (non-null)
	// point: null formula results and gaps draw nothing, so a line of one
	// valued point among nulls is one bucket.
	Buckets int
	// SeriesBuckets is, per series that holds a drawable point, how many
	// distinct bucket times it holds: a line is drawn per series, so a series
	// of one bucket draws nothing whatever the others hold.
	SeriesBuckets []int
	// LastDataAt is the newest bucket holding a non-zero value; zero when the
	// answer has no time axis or nothing non-zero.
	LastDataAt time.Time
	// Items counts funnel steps entered, issues, sessions or heatmap cells.
	Items int
	// HasData is true when the console would draw something rather than its
	// empty state.
	HasData bool
	// BucketSeconds and BucketTimezone are the bucket width and zone a sql
	// time series reports; zero and empty when the control plane sends none
	// (older ones do not, and nothing here depends on them).
	BucketSeconds  int64
	BucketTimezone string
	// Truncated says a cap cut the answer; SeriesTotal is how many series
	// matched before the cap (0: unknown).
	Truncated   bool
	SeriesTotal int
	// Warnings are the control plane's non-fatal notes, verbatim
	// ("metric_absent: rpc.server.calls").
	Warnings []string
	// SQLColumns are a sql panel's result columns, in order.
	SQLColumns []Column
}

type PanelReadoutRequest struct {
	// Narrow carries the range and services; its filters and Explain are the
	// audit's to leave empty (the console sends none for a dashboard panel).
	Narrow
	Panel obsquery.Panel
	// ProjectID is the forge project, sent beside the env as the console does
	// (empty: no project narrowing).
	ProjectID string
	// AllEnvs lifts the env bound: the same panel over every environment of
	// ProjectID, the question "does this data exist in another env?".
	AllEnvs bool
	// NoEnv drops the env predicate as a platform-scoped dashboard does: its
	// telemetry belongs to no environment and carries no env id. Unlike
	// AllEnvs it is the dashboard's own read, not a widening, so it needs no
	// project to bound it (who may read which org's data is unchanged).
	NoEnv bool
}

type QueryRequest struct {
	Narrow
	SQL    string
	Panel  *obsquery.Panel
	Params map[string]string
	// StepSeconds is the {step} parameter and a panel's bucket width; 0 picks
	// one for the range.
	StepSeconds int64
	// Limit is the most rows returned; the statement is cut one past it to
	// detect truncation.
	Limit int
}

type QueryResult struct {
	Columns    []Column
	Rows       [][]any
	Truncated  bool
	Statements []Statement
}

type REDSummary struct {
	Traces      uint64
	ErrorTraces uint64
	P50Ms       float64
	P95Ms       float64
	P99Ms       float64
}

type Range struct{ From, To time.Time }

type Result struct {
	Columns []Column
	Rows    [][]any
}

type Runner interface {
	Run(ctx context.Context, st obsquery.Stmt, lim Limits) (Result, error)
}

type ServiceOverview struct {
	Service       string  `json:"service"`
	Requests      int64   `json:"requests"`
	RatePerSecond float64 `json:"rate_per_second"`
	Errors        int64   `json:"errors"`
	// ErrorRate is a fraction, 0..1.
	ErrorRate float64 `json:"error_rate"`
	P50Ms     float64 `json:"p50_ms"`
	P95Ms     float64 `json:"p95_ms"`
	P99Ms     float64 `json:"p99_ms"`
	// ErrorLogs counts the error-level log records in the range.
	ErrorLogs int64 `json:"error_logs"`
}

type SessionEntry struct {
	Time time.Time
	// Kind is an obsquery.TimelineKind: navigation, click, request_failed,
	// error or event.
	Kind string
	// Name is a navigation's span name, "click", a failed request's method, an
	// error's span name or a custom event's name.
	Name string
	// Path is the page, or a failed request's path.
	Path   string
	Method string
	// Status is a failed request's HTTP status; 0 for a network failure.
	Status   int
	Selector string
	Element  string
	// ErrorType is an error's exception type, or a failed request's SDK error
	// type. Message is the error's masked message.
	ErrorType string
	Message   string
	// Fingerprint is the issue fingerprint of an error; IssueID the issue it
	// belongs to, which only the control plane assigns.
	Fingerprint string
	IssueID     string
	TraceID     string
	SpanID      string
	DurationMs  float64
	Props       map[string]string
	Service     string
}

type SessionReader interface {
	ListSessions(ctx context.Context, req ListSessionsRequest) (ListSessionsResult, error)
	GetSession(ctx context.Context, req GetSessionRequest) (GetSessionResult, error)
}

type SessionSummary struct {
	ID      string
	Service string
	// Version is the service.version of the frontend build the session ran.
	Version string
	// UserID is the userId the app identified the session with; "" when it
	// never did.
	UserID string
	// EntryPath is the path of the first page, with no query or fragment.
	EntryPath    string
	Started      time.Time
	Ended        time.Time
	PageViews    int64
	Interactions int64
	Errors       int64
	HasReplay    bool
}

type Span struct {
	SpanID        string
	ParentID      string
	Name          string
	Kind          string
	Service       string
	Start         time.Time
	DurationNs    int64
	StatusCode    string
	StatusMessage string
	Attributes    map[string]string
	Events        []SpanEvent
}

type SpanEvent struct {
	Name       string
	Time       time.Time
	Attributes map[string]string
}

type Statement struct {
	Purpose string            `json:"purpose"`
	SQL     string            `json:"sql"`
	Params  map[string]string `json:"params,omitempty"`
}

type StatusChange struct {
	From, To     string
	Version      string
	IgnoredUntil time.Time
}

type TelemetryDelivery struct {
	Cluster   string `json:"cluster"`
	Namespace string `json:"namespace"`
	Name      string `json:"name"`
	State     string `json:"state"`
	// ExpiresAt is when the delivered token stops working.
	ExpiresAt           time.Time `json:"expires_at,omitzero"`
	LastVerifiedAt      time.Time `json:"last_verified_at,omitzero"`
	LastError           string    `json:"last_error,omitempty"`
	ConsecutiveFailures int       `json:"consecutive_failures,omitempty"`
}

type TimelineEntry struct {
	ID    string
	Time  time.Time
	Kind  string
	Actor IssueActor
	// IssueID is the issue it happened on: the requested one, or one merged
	// into it.
	IssueID    string
	Status     *StatusChange
	Comment    *IssueComment
	Assignment *AssignmentChange
	Chat       *ChatLink
}

type TraceRequest struct {
	Narrow
	TraceID string
	// LogLimit bounds the correlated logs returned.
	LogLimit int
}

type TraceResult struct {
	TraceID string
	Spans   []Span
	// SpansTruncated says the trace has more spans than the compiler returns.
	SpansTruncated bool
	Logs           []LogRecord
	LogsTruncated  bool
	Statements     []Statement
}

type TraceSummary struct {
	TraceID        string
	Start          time.Time
	DurationMs     float64
	RootService    string
	RootName       string
	RootDurationMs float64
	Spans          int
	Errors         int
	// Weight is how many real traces this stored one stands for (tail
	// sampling); 1 locally.
	Weight   float64
	Services []string
}

type TracesRequest struct {
	Narrow
	ErrorsOnly    bool
	MinDurationMs float64
	// Route narrows to traces whose root span name contains it.
	Route string
	// Slow orders by duration, slowest first. The compiler pages newest-first
	// only, so the slowest are taken from the newest SlowWindow traces.
	Slow      bool
	Limit     int
	PageToken string
}

type TracesResult struct {
	Traces        []TraceSummary
	Summary       *REDSummary
	NextPageToken string
	// SortedFrom is how many traces a Slow request sorted (SlowWindow at most).
	SortedFrom int
	Statements []Statement
}

type Tree struct {
	Roots []*TreeNode
	// Spans is every span of the trace; Shown how many are rendered (a
	// collapsed run counts once).
	Spans, Shown int
	// Duration is first start to last end.
	Duration time.Duration
	// Orphans counts spans whose parent is not in the trace (a dropped or
	// not-yet-exported parent); they are rendered as extra roots.
	Orphans int
	// Capped reports that a cap hid something.
	Capped bool
}

type TreeNode struct {
	Span Span
	// Count > 1 marks a collapsed run: Count identical sibling spans (same
	// service, name and status) shown once, with Min/P50/P95/Max over their
	// durations.
	Count    int
	Min, Max time.Duration
	P50, P95 time.Duration
	// Error is true when this span (or, for a run, any span in it) failed.
	Error bool
	// Critical marks the spans on the critical path: from the root, the child
	// that ends last at each level.
	Critical bool
	// Offset is the span's start relative to the trace's first span.
	Offset   time.Duration
	Children []*TreeNode
	// Hidden counts descendants not rendered because of a cap, so the output
	// can say "… 12 more spans" instead of dropping them silently.
	Hidden int
	// Uninstrumented is how much of the span no child span covers, when that
	// is enough to be where the time went (see [IsGap]); zero otherwise. A
	// handler that took 10s with 15ms of children spent the rest in code that
	// emitted no span, and the reader should look there, not at the children.
	// Gap is the largest such stretch, as offsets from the span's start.
	Uninstrumented time.Duration
	Gap            [2]time.Duration
}

type UpdateIssueStatusRequest struct {
	ID string
	// Status is IssueResolved, IssueIgnored or IssueUnresolved.
	Status string
	// ResolveIn is ResolveNow (default), ResolveNextRelease or ResolveVersion;
	// Version names it for ResolveVersion.
	ResolveIn string
	Version   string
	// IgnoredUntil un-ignores at this time; zero ignores until unignored.
	IgnoredUntil time.Time
}

type UpdateIssueStatusResult struct {
	Issue Issue
}

type Workload struct {
	EnvID     string `json:"env_id,omitempty"`
	EnvName   string `json:"env_name,omitempty"`
	Workload  string `json:"workload"`
	Namespace string `json:"namespace,omitempty"`
	Kind      string `json:"kind,omitempty"`
	Health    string `json:"health"`
	// Cause says whose side a fault is on: workload, platform, undetermined.
	Cause         string              `json:"cause,omitempty"`
	Reason        string              `json:"reason,omitempty"`
	Detail        string              `json:"detail,omitempty"`
	Since         time.Time           `json:"since,omitzero"`
	SinceKnown    bool                `json:"since_known,omitempty"`
	Ready         *int32              `json:"ready,omitempty"`
	Desired       *int32              `json:"desired,omitempty"`
	Restarts      int64               `json:"restarts"`
	LastExit      string              `json:"last_exit_reason,omitempty"`
	LastExitAt    time.Time           `json:"last_exit_at,omitzero"`
	Release       string              `json:"release,omitempty"`
	Version       string              `json:"service_version,omitempty"`
	Containers    []WorkloadContainer `json:"containers,omitempty"`
	LatestWarning *WorkloadEvent      `json:"latest_warning,omitempty"`
}

type WorkloadContainer struct {
	Container        string    `json:"container"`
	Image            string    `json:"image,omitempty"`
	Restarts         int64     `json:"restarts"`
	LastExitReason   string    `json:"last_exit_reason,omitempty"`
	LastExitAt       time.Time `json:"last_exit_at,omitzero"`
	MemoryLimitRatio *float64  `json:"memory_limit_ratio,omitempty"`
}

type WorkloadEvent struct {
	At         time.Time `json:"at,omitzero"`
	Type       string    `json:"type,omitempty"`
	Reason     string    `json:"reason,omitempty"`
	Plain      string    `json:"plain_reason,omitempty"`
	Message    string    `json:"message,omitempty"`
	Count      int64     `json:"count,omitempty"`
	ObjectKind string    `json:"object_kind,omitempty"`
	ObjectName string    `json:"object_name,omitempty"`
}

type WorkloadsResult struct {
	Workloads     []Workload
	Truncated     bool
	Jobs          []Job
	JobsTruncated bool
}