fetch

type Batch struct {
	ID         signal.SeriesID
	Series     signal.Series
	Timestamps []int64
	Values     []float64

	// ScaleFactors carries each sample's lossy-sampling weight (metrics only): a kept sample
	// with ScaleFactors[i] = N "represents" N original samples that budgeted sampling dropped
	// (DESIGN §8a). It is nil when no sampling occurred (every weight is 1), so the common path
	// is unaffected; when non-nil its length matches Values. The storage layer only *carries* the
	// weight — an embedder's aggregation multiplies it back into count/sum/rate to stay unbiased
	// (a gauge read ignores it). Use [Batch.ScaleFactor] to read it with the nil default.
	ScaleFactors []float64

	// Columns are the materialized per-record columns (logs); nil for metrics. Each column's
	// length matches Timestamps. The named layout is the engine's (e.g. severity, body, attrs).
	Columns []NamedColumn
	// contains filtered or unexported fields
}

type Condition struct {
	Column string
	Match  func(value signal.Value) bool
	Tokens [][]byte
	Equal  *EqualMatcher
}

type EqualMatcher struct {
	Name  string
	Value string
}

type Fetcher interface {
	Fetch(ctx context.Context, r Request) (Iterator, error)
}

type Iterator interface {
	Next(ctx context.Context) (*Batch, error)
	Close() error
}

type Matcher struct {
	Name  []byte
	Match func(value signal.Value) bool

	// Spec is an optional **serializable** form of an equality predicate, set by the language
	// layer when Match is an exact compare. It lets the cluster fan-out push a selective
	// matcher (e.g. `__name__="metric"`) to a peer node — the Match closure cannot cross the
	// wire. It is metadata only: a [Fetcher] always matches via Match; a peer reconstructs an
	// equivalent closure from Spec. Only equality is carried (it is exact, so a peer's pushdown
	// never drops a matching series); other predicates fall back to the requester's re-check.
	Spec *EqualMatcher
}

type NamedColumn struct {
	Name    string
	Int64   []int64
	Float64 []float64
	Bytes   [][]byte
}

type Request struct {
	Tenant     signal.TenantID
	Signal     signal.Signal // 0 ⇒ metric (the default vertical); Log for the logs read path
	Start, End int64         // unix nanos, inclusive
	Matchers   []Matcher

	// Conditions are columnar predicates applied per record (logs). Each names a column and
	// carries an operator-free Match callback over the row's typed value (mirroring Matcher).
	Conditions []Condition
	// AllConditions, when true, ANDs the conditions; a fetcher may still return a superset (an
	// approximate index like a bloom is re-checked by the requester). False ⇒ the fetcher need
	// not apply them at all (pure fetch-all; the caller filters).
	AllConditions bool
	// Projection names the columns to materialize for surviving rows (the second pass). Empty ⇒
	// the fetcher's default column set. Filter columns are decoded regardless of Projection.
	Projection []string
	// SecondPass, when set, is an engine-side row filter applied after the column Conditions —
	// for predicates not expressible as a single-column Match (e.g. a per-record attribute
	// decoded from the serialized attrs column). It sees the candidate row's materialized Batch.
	SecondPass func(*Batch) bool

	// Limit, when > 0, bounds the records returned to the most recent (Reverse) or oldest by
	// timestamp across all matched streams — the ordered top-N pushdown for limited log queries.
	// The result is a SUPERSET: the fetcher returns the Limit rows beyond the boundary timestamp
	// plus any rows that tie at that boundary, so a caller applying its own exact ordering+limit
	// never loses a boundary row (the fetch contract already permits a superset). It composes with
	// Matchers/Conditions/SecondPass — filtering happens first, the limit selects over survivors.
	// 0 ⇒ unlimited (every matching record). Honored by the record engine (logs/traces/profiles);
	// the metric engine ignores it (PromQL needs every sample).
	Limit int
	// Reverse selects the Limit direction: true keeps the newest records (largest timestamps, the
	// usual log-query default); false keeps the oldest. Ignored when Limit == 0.
	Reverse bool

	// Recycle opts the fetch into buffer pooling: the caller promises to call [Batch.Release] on
	// each returned batch once done with it, so the engine may hand out (and later reuse) pooled
	// result buffers. Default false — the engine allocates fresh buffers and the caller need not
	// release (so the non-recycling path takes no pool overhead at all). Misuse (reading a batch
	// after Release, or not releasing while Recycle is set) only forfeits the reuse, except that
	// reading after Release is undefined — never do it.
	Recycle bool
}

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