usage

type Closer interface {
	Close() error
}

type DurationStats struct {
	Avg int64 `json:"avg"`
	P50 int64 `json:"p50"`
	P95 int64 `json:"p95"`
	P99 int64 `json:"p99"`
	Max int64 `json:"max"`
}

type Event struct {
	// Identity / trace
	RequestID string    `json:"request_id"`
	Source    string    `json:"source"` // "pipeline" | "proxy" | "ws" | "batch"
	Timestamp time.Time `json:"ts"`

	// Outcome
	Status       int    `json:"status"`
	DurationMs   int64  `json:"duration_ms"` // total: start → response closed
	Streamed     bool   `json:"streamed,omitempty"`
	FinishReason string `json:"finish_reason,omitempty"` // "stop"|"length"|"tool_calls"|"content_filter"|"refusal"
	Attempts     int    `json:"attempts,omitempty"`      // upstream tries (pipeline failover); 0 = not tracked
	ErrorKind    string `json:"error_kind,omitempty"`
	ErrorMessage string `json:"error_message,omitempty"`

	// Upstream is the upstream-leg timing breakdown. Nil when the request
	// never reached upstream (routing/pre-flight failure). The total
	// (start → close) is DurationMs; this adds the finer marks DurationMs
	// can't express. See UpstreamTiming for unit + how to derive TTFT.
	Upstream *sdkusage.UpstreamTiming `json:"upstream,omitempty"`

	// Reasoning is the reasoning span (when the model emitted reasoning
	// content). Nil unless the response was a canonical-observed stream
	// that carried reasoning. Microseconds from start, like Upstream.
	Reasoning *sdkusage.ReasoningTiming `json:"reasoning,omitempty"`

	// Attribution — UUIDs (stable, snapshot-resolvable to slugs at
	// query time). Hash of the inbound bearer is included so the
	// plaintext is never logged.
	RelayKeyHash   string `json:"relay_key_hash,omitempty"`
	PolicyID       string `json:"policy_id,omitempty"`
	ModelID        string `json:"model_id,omitempty"`
	RequestedModel string `json:"requested_model,omitempty"` // model string as the caller sent it
	HostID         string `json:"host_id,omitempty"`
	HostKeyID      string `json:"host_key_id,omitempty"`

	// Token usage as reported by the upstream. Empty on error or when
	// the adapter could not extract.
	Tokens sdkusage.Tokens `json:"tokens,omitempty"`

	// Free-form per-runner tags (client_ip for anonymous proxy, etc.)
	Extras map[string]string `json:"extras,omitempty"`

	// Tags are caller-owned (X-WR-Request-Tags, validated post-flight);
	// Extras stays relay-stamped — the provenance split queries rely on.
	Tags map[string]string `json:"tags,omitempty"`

	// Model, Host, Policy are the entities' slugs (metadata.name) at
	// event time, denormalized so events stay self-describing when the
	// catalog entity is gone (deleted, renamed, re-seeded). The *_id
	// fields above remain the precise keys.
	Model  string `json:"model,omitempty"`
	Host   string `json:"host,omitempty"`
	Policy string `json:"policy,omitempty"`

	// Provider is the model's owning provider slug at event time — same
	// denormalization rationale as Model/Host/Policy above.
	Provider string `json:"provider,omitempty"`

	// Cost, stamped once at emit time from the pricing then in effect.
	// CostNanos is integer nano-USD (1 USD = 1e9) — integer so sums never
	// drift; USD-only by decision, so no currency field. nil = unpriced
	// (no pricing resolved, or no priceable tokens — error/LogOnly rows),
	// which MUST stay distinguishable from a true $0: never collapse nil
	// to 0. CostBreakdown is per-meter nanos (keys like "tokens.input");
	// Pricing is the rate sheet's slug, stamped whenever one resolved
	// (even if the row ended up unpriced) for audit.
	CostNanos     *int64           `json:"cost_nanos,omitempty"`
	CostBreakdown map[string]int64 `json:"cost_breakdown,omitempty"`
	Pricing       string           `json:"pricing,omitempty"`
}

type EventQuery struct {
	// Time bounds. Lower bound resolution: From if set, else now()-Since,
	// else unbounded. Upper bound: To if set, else unbounded. From/To are
	// absolute and take precedence over the relative Since.
	Since time.Duration
	From  time.Time
	To    time.Time

	// RequestID is an exact single-value lookup (deep-link one event).
	RequestID string

	// Categorical filters — match any value in the slice (SQL IN / set
	// membership). Empty slice means no filter on that dimension.
	RelayKeyHash []string
	PolicyID     []string
	ModelID      []string
	HostID       []string
	Source       []string // "pipeline" | "proxy" | "ws" | "batch"
	FinishReason []string
	ErrorKind    []string

	// StatusMin / StatusMax restrict by HTTP status. Zero values mean
	// unbounded on that side. StatusMin=400 picks errors only;
	// StatusMin=200, StatusMax=299 picks successes only.
	StatusMin int
	StatusMax int
	// Status matches exact HTTP status codes (IN). Empty = no filter.
	// Composes with StatusMin/Max (AND).
	Status []int

	// More categorical filters (set membership; empty = no filter).
	HostKeyID      []string
	RequestedModel []string

	// Slug filters — match the denormalized entity names (Event.Model /
	// Host / Policy / Provider) recorded at event time.
	Model    []string
	Host     []string
	Policy   []string
	Provider []string

	// Tags filters on caller-supplied event tags: key → accepted values.
	// AND across keys, OR within a key's values. An event with the key
	// missing matches only an explicit "" value. Nil/empty = no filter.
	Tags map[string][]string

	// Streamed / ErrorsOnly are tri-state: nil = no filter, else match the
	// bool. ErrorsOnly true matches status>=400 OR error_kind!="" (false
	// matches the complement — "successes only").
	Streamed   *bool
	ErrorsOnly *bool

	// AttemptsMin filters by upstream try count (failover). 0 = no filter.
	AttemptsMin int

	// DurationMsMin / DurationMsMax bound total request duration (ms).
	DurationMsMin int64
	DurationMsMax int64

	// TTFTMsMin / TTFTMsMax bound upstream time-to-first-byte (ms), derived
	// from Upstream.ResponseStart (µs from start). Events with no upstream
	// timing are excluded when either bound is set.
	TTFTMsMin int64
	TTFTMsMax int64

	// Q is a free-text needle matched (case-insensitive substring) against
	// request_id, model_id, requested_model, and source.
	Q string

	// Limit caps the number of events returned. <=0 → DefaultEventLimit.
	Limit int

	// CursorTS / CursorID implement keyset pagination for Events. When
	// CursorTS is non-zero, only events strictly older than the cursor are
	// returned — i.e. (ts, request_id) < (CursorTS, CursorID) under the
	// (ts DESC, request_id DESC) ordering. Set only on the Events path;
	// ignored by Summary / TimeSeries.
	CursorTS time.Time
	CursorID string
}

type Reader interface {
	// Events returns raw events matching q, in reverse-chronological
	// order (newest first), capped at q.Limit.
	Events(ctx context.Context, q EventQuery) ([]Event, error)

	// Summary returns aggregated rows grouped by q.GroupBy. Each row
	// carries totals + latency percentiles over the events matching
	// the filter. Rows are sorted by Requests descending. LogOnly
	// events (pre-upstream rejections) are excluded from aggregation —
	// every backend must apply the Event.LogOnly predicate. The same
	// exclusion applies to TimeSeries; Events listings keep them.
	Summary(ctx context.Context, q SummaryQuery) (SummaryResult, error)

	// TimeSeries returns one or more series of time-bucketed aggregates
	// over the filtered set. With an empty GroupBy a single series is
	// returned; with a GroupBy dimension, one series per distinct value.
	// Buckets are aligned to the Unix epoch by q.Interval and ordered
	// oldest-first within each series.
	TimeSeries(ctx context.Context, q TimeSeriesQuery) (TimeSeriesResult, error)
}

type Sink interface {
	// Write delivers one event. The error is logged by the Emitter;
	// returning non-nil does not stop subsequent events.
	Write(ev Event) error
}

type SummaryQuery struct {
	EventQuery

	// GroupBy is the dimension to group on. Valid values:
	// "relay_key_hash", "policy_id", "model_id", "host_id",
	// "host_key_id", "source", "finish_reason", "error_kind",
	// "model", "host", "policy", "provider" (event-time slugs),
	// or "tags.<key>" (dynamic, groups on a caller tag's value).
	// Empty → "source".
	GroupBy string
}

type SummaryResult struct {
	Rows []SummaryRow `json:"rows"`
	From time.Time    `json:"from"`
	To   time.Time    `json:"to"`
}

type SummaryRow struct {
	Group      map[string]string `json:"group"`
	Requests   int64             `json:"requests"`
	ErrorCount int64             `json:"error_count"`
	Tokens     map[string]int64  `json:"tokens"`
	DurationMs DurationStats     `json:"duration_ms"`
	// TTFTMs aggregates upstream time-to-first-byte (ms, derived from
	// Upstream.ResponseStart) over the subset of events that carry upstream
	// timing. Nil when no event in the group has it — a pointer so "no
	// samples" is distinguishable from "all-zero latency".
	TTFTMs    *DurationStats `json:"ttft_ms,omitempty"`
	FirstSeen time.Time      `json:"first_seen"`
	LastSeen  time.Time      `json:"last_seen"`
	// CostNanos sums Event.CostNanos over the group's priced events
	// (nano-USD). Unpriced counts the events that carried no cost stamp —
	// reported instead of folding them into the sum as silent zeros, so a
	// cost total always says how complete it is.
	CostNanos int64 `json:"cost_nanos"`
	Unpriced  int64 `json:"unpriced"`
}

type TimeSeriesPoint struct {
	Bucket     time.Time `json:"bucket"`
	Requests   int64     `json:"requests"`
	ErrorCount int64     `json:"error_count"`
	// Errors4xx/Errors5xx split ErrorCount by status class for triage
	// charts. They may sum below ErrorCount only if an out-of-band status
	// >= 600 ever appears; in practice ErrorCount = Errors4xx + Errors5xx.
	Errors4xx  int64            `json:"errors_4xx"`
	Errors5xx  int64            `json:"errors_5xx"`
	Tokens     map[string]int64 `json:"tokens"`
	DurationMs DurationStats    `json:"duration_ms"`
	// TTFTMs — see SummaryRow.TTFTMs; nil when no event in the bucket
	// carries upstream timing.
	TTFTMs *DurationStats `json:"ttft_ms,omitempty"`
	// CostNanos / Unpriced — see SummaryRow.
	CostNanos int64 `json:"cost_nanos"`
	Unpriced  int64 `json:"unpriced"`
}

type TimeSeriesQuery struct {
	EventQuery

	// Interval is the bucket width. Must be > 0.
	Interval time.Duration

	// GroupBy splits the result into one series per dimension value.
	// Empty means a single series. Valid values match ValidGroupBy.
	GroupBy string
}

type TimeSeriesResult struct {
	Rows     []TimeSeriesRow `json:"rows"`
	Interval string          `json:"interval"`
	From     time.Time       `json:"from"`
	To       time.Time       `json:"to"`
}

type TimeSeriesRow struct {
	Group  map[string]string `json:"group,omitempty"`
	Points []TimeSeriesPoint `json:"points"`
}