timeseries

type AggregateQuery struct {
	Timeline      TimelineID
	Dims          []uint64
	From          time.Time
	To            time.Time
	NumField      uint8         // index into Nums (0-based, max 6)
	Function      string        // "avg", "min", "max", "sum", "count"
	Interval      time.Duration // 0 = scalar result; > 0 = time-bucketed
	MaxScanEvents int           // 0 = no scan limit
	MaxBuckets    int           // 0 = no bucket limit; > 0 aborts when exceeded (XOLU-TS019)
}

type Bucket struct {
	Time  time.Time
	Value float64
	Count uint64
}

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

type Event struct {
	Timeline TimelineID
	Dims     []uint64 // len must equal timeline's Dims
	Time     time.Time
	Nums     []float64 // optional, up to 7; nil means no numeric fields
	Payload  []byte    // optional, caller-defined opaque bytes
}

type LatestQuery struct {
	Timeline TimelineID
	Dims     []uint64
	N        int       // default 10, max 10000
	From     time.Time // optional lower bound (zero = unbounded)
	To       time.Time // optional upper bound (zero = unbounded)
}

type Manager interface {
	// Provision creates a timeseries store for a tenant.
	// tenantName is used to scope dynconfig lookups.
	Provision(ctx context.Context, tenantID uint16, tenantName string) error

	// StoreFor returns the Store for a tenant, or an error if not provisioned.
	StoreFor(tenantID uint16) (Store, error)

	// IsProvisioned reports whether a tenant has timeseries storage.
	IsProvisioned(tenantID uint16) bool

	// Close shuts down all stores.
	Close() error
}

type PebbleConfig struct {
	MemtableSize          int    // bytes; default 67108864 (64 MB)
	BlockSize             int    // bytes; default 32768 (32 KB)
	Compression           string // "snappy", "zstd", or "none"; default "zstd"
	L0CompactionThreshold int    // L0 files before compaction; default 4
	MaxOpenFiles          int    // per-store file descriptor limit; default 500

	// Write coalescer tuning. Zero values fall back to package-level defaults
	// (10ms flush interval, 2000 max events). Only relevant when the coalescer
	// is enabled via dynconfig key ts.writecoal for the tenant or globally.
	CoalFlushIntervalMs int // flush window in milliseconds; default 10
	CoalMaxEvents       int // early-flush threshold in events; default 2000
}

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

type RangeAggregateResult struct {
	Count  uint64
	Sums   [7]float64
	Avgs   [7]float64 // populated after scan: Sums[i]/Count; NaN if Count==0
	Mins   [7]float64
	Maxs   [7]float64
	Fields [7]bool // true if field i appeared in at least one event
}

type RangeAllQuery struct {
	Timeline      TimelineID
	Dims          []uint64
	From          time.Time
	To            time.Time
	MaxScanEvents int // 0 = no limit
}

type RangeFullQuery struct {
	RangeAllQuery
	Quantiles      []float64 // quantile values to estimate, e.g. [0.5, 0.9, 0.99]
	QuantileFields []uint8   // num fields to estimate quantiles for (0–6); nil = all fields
}

type RangeFullResult struct {
	Aggregate RangeAggregateResult
	Quantiles [7][]float64
}

type RangeNumQuery struct {
	Timeline      TimelineID
	Dims          []uint64
	From          time.Time
	To            time.Time
	NumField      uint8 // 0–6
	MaxScanEvents int   // 0 = no limit
}

type RangeQuery struct {
	Timeline      TimelineID
	Dims          []uint64
	From          time.Time
	To            time.Time
	Limit         int    // default 1000, max 10000
	Order         string // "asc" (default) or "desc"
	MaxScanEvents int    // 0 = use store/server default; aborts scan if exceeded
}

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

type RollupDef struct {
	ID             RollupID      `json:"id"`
	SourceTID      TimelineID    `json:"source_tid"`
	DestTID        TimelineID    `json:"dest_tid"`
	BucketDuration time.Duration `json:"bucket_duration"`
	// LateWindow is how long after a bucket closes to wait before computing
	// the rollup, to absorb late-arriving events. Default 0.
	LateWindow time.Duration `json:"late_window,omitempty"`
	// Running records whether the worker was active when last persisted.
	// Workers are not started automatically at DefineRollup time; they are
	// started explicitly via RunRollup (which starts the worker and cascades
	// to all descendants). On store reopen, only definitions with Running=true
	// restart their workers.
	Running   bool      `json:"running"`
	CreatedAt time.Time `json:"created_at"`
}

type RollupID string

type RollupStatusReport struct {
	ID            RollupID   `json:"id"`
	SourceTID     TimelineID `json:"source_tid"`
	DestTID       TimelineID `json:"dest_tid"`
	LastRunAt     time.Time  `json:"last_run_at,omitempty"`
	LastBucketEnd time.Time  `json:"last_bucket_end,omitempty"`
	EventsWritten int64      `json:"events_written"`
	LastError     string     `json:"last_error,omitempty"`
	Running       bool       `json:"running"`
}

type RollupTreeNode struct {
	TID      TimelineID        `json:"tid"`
	Def      *RollupDef        `json:"def,omitempty"` // nil for the root (tid=0) and raw timelines
	Children []*RollupTreeNode `json:"children,omitempty"`
}

type Store interface {
	// Timeline management
	DefineTimeline(id TimelineID, cfg TimelineConfig) error
	UpdateTimeline(id TimelineID, cfg TimelineConfig) error // name + RetentionDays only
	Timeline(id TimelineID) (TimelineConfig, bool)
	Timelines() []TimelineID

	// Write
	Append(ctx context.Context, e Event) error
	AppendBatch(ctx context.Context, events []Event, maxBatch int) (int, error)

	// Delete removes the event identified by e from the store by computing its
	// encoded key from (Timeline, Dims, Time) and issuing a hard delete.
	// The event counter for the timeline is decremented on success.
	//
	// Implementors: returning nil from a backend that does not actually delete
	// the event is a silent correctness bug. The /commit endpoint calls Delete
	// and DeleteKeys as a rollback mechanism; a no-op implementation means
	// orphaned timeseries events will silently survive a SQLite failure and
	// become permanently inconsistent with entity state. Always return
	// ErrDeleteNotSupported if your backend cannot honour the deletion.
	Delete(ctx context.Context, e Event) error

	// DeleteKeys removes events by their pre-encoded keys. Keys must be produced
	// by EncodeKey; passing arbitrary byte slices produces undefined behaviour.
	// This is the preferred path when the caller already holds encoded keys
	// (e.g. during /commit rollback) and wants to avoid re-encoding overhead.
	// Because raw keys carry no Go-level timeline identity, implementations that
	// successfully delete via this method do NOT adjust event counters — the
	// counter is already documented as approximate (see storeMeta). Callers that
	// require an exact counter decrement should use Delete instead.
	//
	// Implementors: the same obligation as Delete applies. A silent no-op here
	// is not safe — it will cause /commit to silently succeed the rollback path
	// while leaving orphaned Pebble entries in place. Return ErrDeleteNotSupported
	// if your backend cannot delete by raw key; the /commit handler will log
	// XOLU-CM016 and alert operators rather than silently corrupting the store.
	DeleteKeys(ctx context.Context, keys [][]byte) error

	// Read
	QueryRange(ctx context.Context, q RangeQuery) ([]Event, error)
	Latest(ctx context.Context, q LatestQuery) ([]Event, error)

	// Aggregate — bucketed or scalar, single numeric field
	Aggregate(ctx context.Context, q AggregateQuery) ([]Bucket, error)

	// Single-field scalar range functions. Each performs one scan pass
	// over [From, To] for the given NumField. Kept alongside RangeAggregate
	// to allow direct performance comparison via benchmarks.
	RangeSum(ctx context.Context, q RangeNumQuery) (float64, error)
	RangeAvg(ctx context.Context, q RangeNumQuery) (float64, error)
	RangeMin(ctx context.Context, q RangeNumQuery) (float64, error)
	RangeMax(ctx context.Context, q RangeNumQuery) (float64, error)
	RangeCount(ctx context.Context, q RangeNumQuery) (uint64, error)

	// RangeAggregate computes Count, Sum, Avg, Min, Max for all seven
	// numeric fields simultaneously in a single scan pass.
	RangeAggregate(ctx context.Context, q RangeAllQuery) (*RangeAggregateResult, error)

	// RangeQuantile returns an approximate quantile estimate for a single
	// numeric field over [From, To] using a t-digest (compression=100).
	//
	// q must be in [0, 1]. Returns (0, nil) when no events carry NumField.
	//
	// Performance note: RangeQuantile performs its own full scan pass and
	// cannot be combined with RangeAggregate in a single pass. A caller
	// needing both sum/avg/min/max AND a quantile estimate for the same
	// range must issue two separate queries and pay for two scans.
	//
	// Future optimisation: if a single-pass combined result becomes
	// necessary, introduce a separate RangeFullQuery / RangeFullResult pair
	// rather than embedding *tdigest.TDigest into RangeAggregateResult.
	// Keeping the types separate preserves RangeAggregateResult as a plain
	// value type (no heap pointers, trivially copyable and serialisable) and
	// avoids surfacing the quantile estimator implementation as part of the
	// Store contract.
	RangeQuantile(ctx context.Context, q RangeNumQuery, quantile float64) (float64, error)

	// RangeMedian returns the approximate P50 for a single numeric field
	// over [From, To]. Syntax sugar over RangeQuantile(ctx, q, 0.5).
	// Carries the same two-scan limitation; see RangeQuantile.
	RangeMedian(ctx context.Context, q RangeNumQuery) (float64, error)

	// RangeFullAggregate computes exact sum/avg/min/max/count for all seven
	// numeric fields AND approximate quantiles for selected fields in a single
	// Pebble scan pass.
	//
	// This is the efficient alternative to calling RangeAggregate and
	// RangeQuantile separately when both are needed. RangeAggregateResult
	// is kept as a plain value type; digests are allocated during the scan
	// and discarded after quantile extraction, never stored in the result.
	//
	// If RangeFullQuery.Quantiles is empty the call is equivalent to
	// RangeAggregate with no additional cost.
	RangeFullAggregate(ctx context.Context, q RangeFullQuery) (*RangeFullResult, error)

	// Retention
	Purge(ctx context.Context) error

	// Retention configuration
	DefaultRetentionDays() int
	SetDefaultRetentionDays(days int) error

	// WriteConfig returns the write performance configuration for a timeline.
	// Returns the zero value (both flags false) if the timeline has no explicit
	// config set or if id is not defined.
	WriteConfig(id TimelineID) TimelineWriteConfig

	// SetWriteConfig updates the write performance configuration for a timeline.
	// The timeline must already exist. The config is persisted to disk so it
	// survives store restarts.
	SetWriteConfig(id TimelineID, cfg TimelineWriteConfig) error

	// Diagnostics
	Stats(ctx context.Context) (*StoreStats, error)
	TimelineStats(ctx context.Context, id TimelineID) (*TimelineStats, error)

	// Rollup management
	//
	// DefineRollup creates or updates a rollup definition on sourceTID.
	// Timeline 0 is rejected (XOLU-TS022). The destination must not already
	// be the target of another definition (XOLU-TS026). Adding a definition
	// that would create a cycle (XOLU-TS023) or exceed the depth limit
	// (XOLU-TS024) is rejected. Returns the assigned RollupID.
	DefineRollup(sourceTID TimelineID, def RollupDef) (RollupID, error)

	// GetRollup returns a specific rollup definition by its ID on sourceTID.
	GetRollup(sourceTID TimelineID, id RollupID) (RollupDef, error)

	// ListRollups returns all rollup definitions where sourceTID is the source.
	ListRollups(sourceTID TimelineID) ([]RollupDef, error)

	// DeleteRollup removes a rollup definition and stops its worker.
	// Data already written to the destination timeline is not affected.
	DeleteRollup(sourceTID TimelineID, id RollupID) error

	// RollupParent returns the rollup definition for which sourceTID is the
	// destination — i.e. the definition that feeds into this timeline.
	// Returns (RollupDef{}, false) if this timeline has no parent rollup.
	RollupParent(sourceTID TimelineID) (RollupDef, bool)

	// RollupTree returns the full rollup tree for this store, rooted at
	// timeline 0. Each node carries its definition and its children.
	RollupTree() *RollupTreeNode

	// RunRollup executes a rollup definition immediately for the given time
	// range, writing the results into the destination timeline. If from and
	// to are both zero, runs for the most recently closed bucket.
	// If cascade is true, after completing the specified bucket RunRollup
	// also runs all descendant definitions for the corresponding time windows,
	// walking down the tree in source→destination order. The worker goroutine
	// is started for this definition and all cascaded descendants if not
	// already running.
	RunRollup(ctx context.Context, sourceTID TimelineID, id RollupID, from, to time.Time, cascade bool) error

	// RollupStatus returns the operational status of a rollup definition.
	RollupStatus(sourceTID TimelineID, id RollupID) (RollupStatusReport, error)

	// Data deletion
	//
	// DeleteTimelineData removes all events from a timeline's Pebble key
	// range. The timeline definition is preserved. Timeline 0 is rejected.
	DeleteTimelineData(ctx context.Context, id TimelineID) error

	// DeleteTimeline removes a timeline's definition together with its event
	// data and its rollups. It is the inverse of DefineTimeline and is distinct
	// from DeleteTimelineData (which keeps the definition). Rollup cascade
	// follows RollupCascadeDelete: when off and the timeline still has rollups,
	// the call returns an error and changes nothing. Timeline 0 is rejected.
	DeleteTimeline(ctx context.Context, id TimelineID) error

	// PurgeTimelineRange removes events in [from, to] from a timeline.
	// Timeline 0 is rejected.
	PurgeTimelineRange(ctx context.Context, id TimelineID, from, to time.Time) error

	// Lifecycle
	Close() error
}

type StoreConfig struct {
	DefaultRetentionDays int // store-level fallback; 0 = no expiry

	// RollupCascadeDelete controls whether DeleteRollup automatically removes
	// all descendant definitions. When true (default), deleting a parent
	// removes its entire subtree. When false, deleting a definition that has
	// descendants returns an error; the caller must delete bottom-up.
	RollupCascadeDelete bool
}

type StoreFactory func(dir string, cfg StoreConfig, tenantName string) (Store, error)

type StoreStats struct {
	Timelines int
	DiskBytes int64
}

type TimelineConfig struct {
	Name          string // optional, human-readable label
	Dims          uint8  // 1–5, immutable after FirstWriteAt is set
	RetentionDays int    // 0 = use store-level default
	CreatedAt     time.Time
	FirstWriteAt  time.Time // zero until first event written; Dims locks here
}

type TimelineID uint16

type TimelineStats struct {
	TotalEvents            int64
	TotalEventsApproximate bool // always true; counter is eventually consistent
	OldestEvent            time.Time
	NewestEvent            time.Time
}

type TimelineWriteConfig struct {
	// NoSync — when true, AppendBatch commits this timeline's events with
	// pebble.NoSync instead of pebble.Sync. The OS page cache is not flushed
	// to durable storage before the call returns. Data loss is possible if
	// the process crashes before the OS writes the WAL to disk.
	NoSync bool `json:"nosync"`
}