observe

type AggOp uint8

type Aggregation struct {
	// Op is the range-vector function.
	Op AggOp

	// Step is the histogram bucket width (the `[5m]` range / resolution).
	Step time.Duration

	// GroupBy is the `by (...)` grouping dimensions. Grouping by a
	// high-cardinality field is Advanced tier on Loki.
	GroupBy []string

	// Field is the extracted numeric field for AggQuantileOverTime
	// (e.g. "dur"). Ignored by the count/rate/bytes ops.
	Field string

	// Quantile in [0,1] for AggQuantileOverTime (e.g. 0.99). Advanced tier.
	Quantile float64
}

type Capabilities struct {
	// Backend is the store identity ("embedded", "loki", or "clickhouse"),
	// surfaced in the dashboard and in operational logs.
	Backend string

	// MaxTier is the highest tier the store supports. The embedded store and
	// Loki report TierCore; ClickHouse reports TierAdvanced (which implies
	// Core).
	MaxTier Tier

	// RawSQL is true when the store accepts Query.RawSQL (ClickHouse only).
	RawSQL bool

	// Percentiles is true when AggQuantileOverTime is supported.
	Percentiles bool

	// HighCardinalityFilters is true when filtering/grouping on arbitrary
	// high-cardinality label keys (e.g. order_id, trace_id) is cheap enough to
	// expose in the dashboard.
	HighCardinalityFilters bool

	// Parsers is true when the store evaluates field-extraction pipeline
	// stages (`| logfmt`, `| json`) and post-parse label filters. The
	// embedded store evaluates them in-process and Loki natively; the
	// ClickHouse adapter rejects them for now (RawSQL is its escape hatch).
	Parsers bool
}

type CompiledLabelFilters []compiledLabelFilter

type Direction uint8

type LabelFilter struct {
	Label string
	Op    LabelFilterOp
	Value string
}

type LabelFilterOp string

type LabelValue struct {
	Name  string
	Value string
	Count int64
}

type LineFilter struct {
	Op    LineFilterOp
	Value string
}

type LineFilterOp uint8

type LogRecord struct {
	// Timestamp is the event time of the line (not ingest time).
	Timestamp time.Time

	// Line is the raw log content (the "message").
	Line string

	// Stream is the source stream: "stdout" or "stderr". For Outbox-sourced
	// agent/subsystem events this is "event".
	Stream string

	// Level is the parsed severity if known ("info", "warn", "error", ...).
	// Empty when the line was not classified.
	Level string

	// Namespace the producing instance lives in (default: "default").
	Namespace string

	// Service is the parent service name.
	Service string

	// Instance is the instance ID the line came from.
	Instance string

	// Node is the Rune node ID (agent identity) that captured the line.
	Node string

	// Labels are arbitrary key/value stream selectors carried from the
	// instance (pkg/types). High-cardinality labels are only safely
	// queryable on the ClickHouse backend (Advanced tier).
	Labels map[string]string
}

type LogRow struct {
	Timestamp time.Time
	Line      string
	Stream    string
	Level     string
	Labels    map[string]string
}

type LogStore interface {
	// Write persists a batch of enriched records (the ingest path). Stores
	// translate to the backend's native write. Must be safe for concurrent
	// callers.
	Write(ctx context.Context, batch []LogRecord) error

	// Execute runs a parsed Query and streams results. It receives an AST,
	// never raw LogQL text. Stores reject queries that exceed their
	// Capabilities with ErrCapabilityUnsupported.
	Execute(ctx context.Context, q *Query) (ResultStream, error)

	// Capabilities reports the store's capability handshake for dashboard
	// feature-flagging. Cheap and side-effect free.
	Capabilities() Capabilities

	// Labels returns known values for the dimensions named by sel — used to
	// populate label chips and autocomplete in the dashboard.
	Labels(ctx context.Context, sel Selector) ([]LabelValue, error)

	// Health is a liveness/readiness probe against the backend.
	Health(ctx context.Context) error
}

type MatchOp uint8

type Matcher struct {
	Label string
	Op    MatchOp
	Value string
}

type MetricSample struct {
	// Timestamp is the left edge of the histogram bucket.
	Timestamp time.Time

	// Value is the aggregated value (count, rate, percentile, ...).
	Value float64

	// GroupLabels are the resolved by(...) dimensions for this series
	// (e.g. {"level":"error"} for a level breakdown). nil for ungrouped.
	GroupLabels map[string]string
}

type ParserStage string

type Query struct {
	// Selectors are the stream matchers (the `{service="api"}` part of LogQL).
	// ANDed together. Required — a query must select at least one stream.
	Selectors []Matcher

	// LineFilters are post-selection grep stages (`|= "boom"`, `!= "noise"`).
	// Applied in order; ANDed together.
	LineFilters []LineFilter

	// Parsers are field-extraction stages (`| logfmt`, `| json`) applied
	// after the line filters. Extracted fields become labels on the row —
	// visible in results, filterable via LabelFilters, and groupable in
	// aggregations. Our subset fixes the pipeline order as
	// selectors → line filters → parsers → label filters.
	Parsers []ParserStage

	// LabelFilters are post-parse predicates (`| status = "500"`,
	// `| dur > 250`) over intrinsic and extracted labels. ANDed together.
	LabelFilters []LabelFilter

	// Aggregation, when non-nil, turns the query from a log query into a
	// metric query (e.g. count_over_time → a histogram). When nil the query
	// returns raw log lines.
	Aggregation *Aggregation

	// Start and End bound the query window (event time). End is exclusive.
	Start time.Time
	End   time.Time

	// Limit caps the number of returned log lines (ignored for aggregations).
	// Zero means "store default".
	Limit int

	// Direction controls ordering of returned lines.
	Direction Direction

	// RawSQL, when non-empty, is an Advanced-tier escape hatch: the operator
	// asked for raw SQL mode. Only the ClickHouse store honours it; the Loki
	// and embedded stores must reject a Query with RawSQL set (CapabilityAdvanced
	// absent). When set, the other fields are advisory (time bounds may still be
	// injected as query parameters).
	RawSQL string
}

type ResultStream interface {
	// IsMetric reports whether Next yields MetricSample (true) or LogRow.
	IsMetric() bool

	// Next advances to the next result. It returns false at end of stream or
	// on error; check Err after Next returns false.
	Next(ctx context.Context) bool

	// Row returns the current log line. Valid only when IsMetric is false and
	// the last Next returned true.
	Row() LogRow

	// Sample returns the current metric sample. Valid only when IsMetric is
	// true and the last Next returned true.
	Sample() MetricSample

	// Err returns the first error encountered, if any.
	Err() error

	// Close releases backend resources. Safe to call multiple times.
	Close() error
}

type Selector struct {
	// Name is the dimension whose values to enumerate (e.g. "service"). Empty
	// means "enumerate the available label names rather than values".
	Name string

	// Match optionally constrains which streams contribute values (e.g. only
	// services within a namespace). Empty means all streams.
	Match []Matcher

	// Start and End bound the time window considered. Zero values mean the
	// store's default lookback.
	Start time.Time
	End   time.Time

	// Limit caps the number of returned values. Zero means store default.
	Limit int
}

type StatsProvider interface {
	Stats() StoreStats
}

type StoreStats struct {
	// Records currently held.
	Records int64

	// DiskUsedBytes is the on-disk footprint (0 for a purely in-memory store).
	DiskUsedBytes int64

	// DiskCapBytes is the hard disk bound (drop-oldest), 0 if unbounded.
	DiskCapBytes int64

	// Retention is the store's age bound (0 = store default semantics,
	// negative = age-based eviction disabled).
	Retention time.Duration

	// OldestRecord is the timestamp of the oldest held record (zero when
	// empty) — i.e. how far back queries can actually see.
	OldestRecord time.Time
}

type Tier uint8