recordengine

type AppendLimits struct {
	// MaxSeries caps the number of distinct streams buffered in the head. A record that would
	// register a new stream once the head already holds MaxSeries is rejected (the whole batch,
	// since a batch is one stream); known streams are unaffected. 0 ⇒ unlimited.
	MaxSeries int64
	// MaxInFlightBytes caps the head's buffered record bytes. A record arriving while the head is
	// at or over the cap is rejected (memory backpressure) until a flush drains it. 0 ⇒ unlimited.
	MaxInFlightBytes int64
}

type AppendResult struct {
	Accepted            int
	RejectedOOO         int // older than the out-of-order window
	RejectedCardinality int // would exceed AppendLimits.MaxSeries (a new stream)
	RejectedBytes       int // head at or over AppendLimits.MaxInFlightBytes
}

type Batch struct {
	Stream   signal.SeriesID
	Identity func() signal.Series // materialized only when the stream is newly seen
	Ts       []int64
	Ints     [][]int64  // len == schema int count; Ints[k][row]
	Bytes    [][][]byte // len == schema byte count; Bytes[k][row]
	// Side is an optional encoded side-store delta (the content-addressed symbols this batch's
	// records reference) absorbed by [Config.SideStore]. nil when the engine has no side store.
	Side []byte
}

type BloomMode uint8

type CardinalityStat struct {
	TotalSeries        int64 // distinct streams
	DistinctLabelNames int
	SymbolCount        int
	Top                []LabelCard // sorted by Series desc, then Name; truncated to the requested top-N
}

type Column struct {
	Name  string
	Kind  Kind
	Codec chunk.Codec
	Bloom BloomMode
}

type ColumnStat struct {
	Name     string
	Kind     string // physical type: int64 / float64 / bytes / int128
	Codec    string // value codec
	Compress string // block-compression algorithm
}

type Config struct {
	// Schema is the per-record column set this engine stores (required; the signal supplies it).
	Schema *Schema
	// OOOWindow rejects records older than newest-OOOWindow (nanoseconds). 0 disables.
	OOOWindow int64
	// WAL, when non-nil, durably logs streams and records for crash recovery. nil ⇒ ephemeral.
	WAL *wal.SegmentWriter
	// Backend stores flushed parts. Required for [Engine.Flush]; nil ⇒ head-only.
	Backend backend.Backend
	// Prefix is the backend key prefix under which this engine's parts are written.
	Prefix string
	// SideStore, when non-nil, is a signal-supplied content-addressed auxiliary store (e.g. the
	// profiles symbol store) that the engine persists as part sidecars on flush and unions on merge.
	// nil ⇒ no side data (logs, traces).
	SideStore SideStore
	// Obs is the observability handle (spans + metrics). nil ⇒ a no-op handle.
	Obs *obs.Obs
	// Signal is the signal label for this engine's metrics ("log"/"trace"/"profile"); the facade
	// sets it per signal. Empty ⇒ "record".
	Signal string
}

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

type KeyInfo struct {
	Key   []byte
	Scope KeyScope
}

type KeyScope uint8

type Kind uint8

type LabelCard struct {
	Name           string
	Series         int64
	DistinctValues int
}

type PartDetailStat struct {
	PartStat

	Bytes   int64        // sum of the part's backend object sizes
	Chunks  int          // sparse-index granules: ceil(RowCount / GranuleSize)
	Columns []ColumnStat // per-column physical layout
}

type PartStat struct {
	ID      string // the part's backend key prefix
	MinTime int64  // inclusive unix-ns bounds of the part's records
	MaxTime int64
	Series  int   // distinct streams in the part (len of its row-range index)
	Rows    int64 // total records (sum of the per-stream row spans)
}

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

type SideStore interface {
	// Absorb merges one batch's encoded side delta ([Batch.Side]) into the live accumulator.
	Absorb(delta []byte) error
	// Encode serializes the accumulated side data into named sidecar payloads (name → bytes),
	// written as {prefix}/sym-{name}.bin at flush.
	Encode() map[string][]byte
	// Reset clears the live accumulator (after a flush drains the head).
	Reset()
	// Names returns the sidecar names to read back for a part on merge (the keys [SideStore.Encode]
	// may produce). A part missing a named sidecar is skipped.
	Names() []string
	// Union merges the loaded sidecars of the compacted parts (one map per part) and returns the
	// merged named payloads to write under the new part. Pure; ignores the live accumulator.
	Union(parts []map[string][]byte) (map[string][]byte, error)
}

type Stats struct {
	Streams     int64 // distinct streams ever seen (index span: head ∪ flushed)
	HeadRecords int64 // records currently buffered in the head (unflushed)
	HeadBytes   int64 // head's buffered record bytes (the in-flight memory measure)
	Parts       int   // flushed immutable parts
	MinTime     int64 // oldest flushed record time (unix ns); 0 when no parts
	MaxTime     int64 // newest record time across parts and the head (unix ns); 0 when empty
}