store

type AttrKeyDelta struct {
	SignalType  string // 'span' | 'log' | 'metric' | 'resource' | 'scope' | 'event' | 'link'
	ServiceName string // "" for cross-service keys
	Key         string
	ValueType   string // 'str' | 'int' | 'flt' | 'bool' | 'arr' | 'kv' | 'bytes'
	Count       int64
	LastSeenNS  int64
}

type AttrValueDelta struct {
	SignalType  string
	ServiceName string
	Key         string
	Value       string
	Count       int64
	LastSeenNS  int64
}

type Batch struct {
	Resources    []Resource
	Scopes       []Scope
	Events       []Event
	MetricEvents []MetricEvent
	AttrKeys     []AttrKeyDelta
	AttrValues   []AttrValueDelta
	EnqueuedAt   time.Time

	// MetaOverwrites counts ingest events whose attributes collided with a
	// reserved meta.* key and got overwritten. Surfaced in logs for SDK
	// debugging.
	MetaOverwrites int64
}

type Event struct {
	TimeNS      int64
	EndTimeNS   *int64 // spans only
	ResourceID  uint64
	ScopeID     uint64
	ServiceName string
	Name        string

	TraceID      []byte
	SpanID       []byte
	ParentSpanID []byte

	// Span-only scalars (nil when not a span)
	StatusCode    *int32
	StatusMessage string
	TraceState    string
	Flags         *uint32

	// Log-only scalars
	SeverityNumber *int32
	SeverityText   string
	Body           string
	ObservedTimeNS *int64

	AttributesJSON string

	// Span events + links ride alongside when this event is a span. Writer
	// inserts them into span_events / span_links after the parent Event.
	SpanEvents []SpanEvent
	SpanLinks  []SpanLink
}

type FieldFilter struct {
	SignalType string // "span" | "log" | "metric"
	Service    string
	Prefix     string
	Limit      int
}

type FieldInfo struct {
	Key       string `json:"key"`
	ValueType string `json:"type"`
	Count     int64  `json:"count"`
}

type LogFilter struct {
	Query   string // FTS5 expression; empty means no text filter
	Service string
	FromNS  int64
	ToNS    int64
	Limit   int
	Cursor  string
}

type LogOut struct {
	LogID          int64  `json:"log_id"`
	TimeNS         int64  `json:"time_ns"`
	ServiceName    string `json:"service"`
	SeverityText   string `json:"severity"`
	SeverityNumber int32  `json:"severity_number"`
	Body           string `json:"body"`
	TraceID        string `json:"trace_id,omitempty"`
	SpanID         string `json:"span_id,omitempty"`
	AttributesJSON string `json:"attributes"`
}

type MetricEvent struct {
	TimeNS         int64
	ResourceID     uint64
	ScopeID        uint64
	ServiceName    string
	AttributesJSON string
}

type QueryColumn = query.Column

type QueryHistoryEntry struct {
	ID          int64  `json:"id"`
	Dataset     string `json:"dataset"`
	QueryJSON   string `json:"query_json"`
	DisplayText string `json:"display_text"`
	RunCount    int64  `json:"run_count"`
	FirstRunNS  int64  `json:"first_run_ns"`
	LastRunNS   int64  `json:"last_run_ns"`
}

type QueryRateSpec = query.RateSpec

type QueryResult struct {
	Columns   []QueryColumn `json:"columns"`
	Rows      [][]any       `json:"rows"`
	HasBucket bool          `json:"has_bucket"`
	GroupKeys []string      `json:"group_keys,omitempty"`
}

type Resource struct {
	ID                uint64
	ServiceName       string
	ServiceNamespace  string
	ServiceVersion    string
	ServiceInstanceID string
	SDKName           string
	SDKLanguage       string
	SDKVersion        string
	AttributesJSON    string
	FirstSeenNS       int64
	LastSeenNS        int64
}

type Scope struct {
	ID             uint64
	Name           string
	Version        string
	AttributesJSON string
}

type ServiceSummary struct {
	ServiceName string  `json:"service"`
	SpanCount   int64   `json:"span_count"`
	ErrorCount  int64   `json:"error_count"`
	ErrorRate   float64 `json:"error_rate"`
}

type SpanEvent struct {
	TraceID           []byte
	SpanID            []byte
	Seq               int
	TimeNS            int64
	Name              string
	AttributesJSON    string
	DroppedAttrsCount uint32
}

type SpanEventOut struct {
	TimeNS         int64  `json:"time_ns"`
	Name           string `json:"name"`
	AttributesJSON string `json:"attributes"`
}

type SpanLink struct {
	TraceID           []byte
	SpanID            []byte
	Seq               int
	LinkedTraceID     []byte
	LinkedSpanID      []byte
	TraceState        string
	Flags             uint32
	AttributesJSON    string
	DroppedAttrsCount uint32
}

type SpanLinkOut struct {
	LinkedTraceID  string `json:"linked_trace_id"`
	LinkedSpanID   string `json:"linked_span_id"`
	AttributesJSON string `json:"attributes,omitempty"`
}

type SpanOut struct {
	TraceID        string         `json:"trace_id"`
	SpanID         string         `json:"span_id"`
	ParentSpanID   string         `json:"parent_span_id,omitempty"`
	ResourceID     uint64         `json:"resource_id"`
	ServiceName    string         `json:"service_name"`
	Name           string         `json:"name"`
	Kind           string         `json:"kind"` // OTel enum name: SERVER|CLIENT|INTERNAL|PRODUCER|CONSUMER|UNSPECIFIED
	StartTimeNS    int64          `json:"start_ns"`
	EndTimeNS      int64          `json:"end_ns"`
	DurationNS     int64          `json:"duration_ns"`
	StatusCode     int32          `json:"status_code"`
	StatusMessage  string         `json:"status_message,omitempty"`
	AttributesJSON string         `json:"attributes"`
	Events         []SpanEventOut `json:"events,omitempty"`
	Links          []SpanLinkOut  `json:"links,omitempty"`
}

type Store interface {
	WriteBatch(ctx context.Context, b Batch) error

	ListServices(ctx context.Context) ([]ServiceSummary, error)
	ListTraces(ctx context.Context, f TraceFilter) ([]TraceSummary, string, error)
	GetTrace(ctx context.Context, traceID string) (TraceDetail, error)

	ListFields(ctx context.Context, f FieldFilter) ([]FieldInfo, error)
	ListFieldValues(ctx context.Context, f ValueFilter) ([]string, error)
	ListSpanNames(ctx context.Context, service, prefix string, limit int) ([]string, error)

	SearchLogs(ctx context.Context, f LogFilter) ([]LogOut, string, error)

	// RunQuery executes a pre-compiled structured query (SQL + args + column
	// schema) against the read pool. All user-provided inputs have been
	// whitelisted by the query package before we get here; sqlite parameter
	// binding handles the values. Rates, when non-empty, are applied as a
	// post-scan transform.
	RunQuery(ctx context.Context, sql string, args []any, columns []QueryColumn, hasBucket bool, groupKeys []string, rates []QueryRateSpec) (QueryResult, error)

	// RecordQueryRun upserts a row in query_history keyed by the AST's
	// content hash: first insert stamps first_run_ns/last_run_ns = now and
	// run_count = 1; subsequent runs of the same AST update last_run_ns
	// and increment run_count. DisplayText is the pre-rendered list-view
	// summary ("SELECT COUNT WHERE … GROUP BY …"). Errors are fatal to the
	// caller only if it wants them to be — the query itself has already
	// succeeded by the time this fires.
	RecordQueryRun(ctx context.Context, dataset, queryJSON, displayText string, hash []byte) error
	// ListQueryHistory returns rows ordered by last_run_ns DESC, capped at
	// `limit`. No cursor pagination yet — the set is bounded by the prune
	// cap in RecordQueryRun.
	ListQueryHistory(ctx context.Context, limit int) ([]QueryHistoryEntry, error)

	Retain(ctx context.Context, olderThanNS int64) error
	Clear(ctx context.Context) error

	Close() error
}

type TraceDetail struct {
	TraceID   string              `json:"trace_id"`
	Spans     []SpanOut           `json:"spans"`
	Resources map[uint64]Resource `json:"resources"`
}

type TraceFilter struct {
	Service  string
	FromNS   int64
	ToNS     int64
	HasError *bool
	Limit    int
	Cursor   string
}

type TraceSummary struct {
	TraceID     string `json:"trace_id"`
	RootService string `json:"root_service"`
	RootName    string `json:"root_name"`
	StartTimeNS int64  `json:"start_ns"`
	DurationNS  int64  `json:"duration_ns"`
	SpanCount   int64  `json:"span_count"`
	HasError    bool   `json:"has_error"`
}

type ValueFilter struct {
	SignalType string
	Service    string
	Key        string
	Prefix     string
	Limit      int
}