aggregate

type AccuracyMetadata struct {
	// Approximate is true whenever a percentile came from a sketch.
	Approximate bool `json:"approximate"`
	// SketchScale is the mapping scale of the merged sketch.
	SketchScale uint8 `json:"sketch_scale"`
	// RelativeErrorBound is the worst-case relative error of a quantile
	// estimate at SketchScale, as a fraction (0.0217 = 2.17%).
	RelativeErrorBound float64 `json:"relative_error_bound"`
	// Degraded reports that the merged sketch collapsed or saturated, which
	// puts estimates in the affected range OUTSIDE RelativeErrorBound.
	Degraded bool `json:"degraded,omitempty"`

	// SourceBucketError is the worst-case relative error imported from the
	// SOURCE histogram's bucket widths, as a fraction. Zero for a native
	// sketch and for exponential histograms, whose index transfer is exact.
	// When non-zero it, not RelativeErrorBound, is the number that dominates.
	SourceBucketError float64 `json:"source_bucket_error,omitempty"`
	// UnboundedTail reports that observations landed in the source
	// histogram's +Inf bucket. A quantile that falls there is a LOWER BOUND
	// (>= UnboundedTailBound), never an estimate.
	UnboundedTail      bool    `json:"unbounded_tail,omitempty"`
	UnboundedTailBound float64 `json:"unbounded_tail_bound,omitempty"`
	// PercentilesUnavailable suppresses every quantile: the sketch does not
	// describe the whole distribution. PercentilesUnavailableReason names why
	// (negative_observations, scale_out_of_range, no_finite_boundaries).
	PercentilesUnavailable       bool   `json:"percentiles_unavailable,omitempty"`
	PercentilesUnavailableReason string `json:"percentiles_unavailable_reason,omitempty"`
}

type Admission struct {
	// Key is the series to record under. It differs from the requested key
	// when a cap forced overflow routing.
	Key SeriesKey
	// Overflowed reports that a cap was hit and Key is an __other__ series.
	Overflowed bool
	// Reason names the cap that triggered overflow.
	Reason OverflowReason
	// Reserved reports that THIS call created (Key, window) presence, and so
	// that a matching Release is the exact undo. It is false when the pair was
	// already present, which is what lets a rolled-back group commit release
	// only the occupancy it charged and never occupancy an earlier committed
	// batch is still using (#194 blocker 3).
	Reserved bool
}

type AdmissionPlan struct {
	// Resolved is the batch keyed by the identity to record under.
	Resolved DeltaMap
	// contains filtered or unexported fields
}

type AggregateDelta struct {
	// Count is the number of accepted points that contributed to this series:
	// spans for traces, log records for logs, data points for metrics. It is
	// accepted telemetry, never sampled telemetry (#153 §8).
	Count uint64
	// ErrorCount is the subset of Count classified as an error: span status
	// ERROR for traces, severity ERROR/FATAL for logs. Metrics never set it.
	ErrorCount uint64

	// RequestCount is the subset of Count that qualifies as a REQUEST: a span
	// that is a trace root (no parent span) or a SERVER-kind span. Either
	// qualifies and a span is counted at most once (#197 Q2).
	//
	// It exists because Count is per SPAN, and a dashboard that labels a span
	// total "traces" is lying by a factor of the average trace size. A
	// distributed trace with several entry points counts once per entry point:
	// a documented approximation, not a unique-trace-ID count, because trace
	// IDs are on the permanent banned list (#153, #159) and cannot be counted
	// without carrying them into aggregate identity.
	//
	// Only trace-shaped signals set it; logs and metrics leave it zero.
	RequestCount uint64
	// ErrorRequestCount is the error subset of RequestCount. It is the
	// numerator of the headline dashboard error rate (#197 Q3); per-operation
	// error rates stay span-based on ErrorCount/Count.
	ErrorRequestCount uint64

	// DurationCount is the number of duration observations. It tracks Count
	// for trace series and stays zero elsewhere, so a merged delta can still
	// tell "no spans" from "spans with zero duration".
	DurationCount uint64
	// DurationSum is the sum of observed durations, in microseconds.
	DurationSum float64
	// DurationMin and DurationMax are the extremes of the observed durations
	// in microseconds. They are only meaningful when DurationCount > 0.
	DurationMin float64
	DurationMax float64
	// Sketch holds the quantile contribution of the observed durations. It is
	// allocated on the first duration observation and stays nil for series
	// that carry no latency (logs, metrics), which keeps the common delta
	// small — a Sketch is ~2 KiB of dense bins.
	Sketch *Sketch

	GaugeCount uint64
	GaugeSum   float64
	GaugeMin   float64
	GaugeMax   float64
	// GaugeLast is the sample with the highest GaugeLastTime seen so far.
	// Merging picks the later timestamp so the result does not depend on the
	// order in which deltas were merged. Two samples of one series carrying
	// the IDENTICAL timestamp are ambiguous about which is last, and that tie
	// resolves by arrival order — no merge rule can fix a producer that
	// timestamps two values the same.
	GaugeLast     float64
	GaugeLastTime time.Time

	// CounterDelta is the increase attributed to this window: the sum of
	// per-point deltas computed by the baseline tracker for cumulative sums,
	// or the raw values of delta-temporality points.
	CounterDelta float64
	// ResetCount is the number of counter resets observed in this window
	// (start-time change or value regression, per #166).
	ResetCount uint64

	// HistogramCount is the population count reported by the folded points.
	// It counts OBSERVATIONS, unlike Count which counts data points.
	HistogramCount uint64
	// HistogramSum is the authoritative sum reported by the producer. It is
	// never derived from the sketch: bucket folding only knows bucket
	// midpoints, and a sum of midpoints is an estimate.
	HistogramSum float64
	// HistogramMin and HistogramMax are the producer-reported extremes, valid
	// only when HistHasMin / HistHasMax are set in HistogramFlags.
	HistogramMin float64
	HistogramMax float64
	// HistogramFlags is the bit set defined in histogram.go:
	// HistPercentilesUnavailable, HistUnboundedTail, HistHasMin, HistHasMax,
	// plus a SketchDropReason in its high byte.
	HistogramFlags uint32
	// HistogramSourceError is the worst-case relative error imported from the
	// SOURCE histogram's bucket widths, as a fraction. Zero for exponential
	// histograms; an explicit-bounds histogram with decade-wide buckets can
	// put this an order of magnitude above the sketch's own bound.
	HistogramSourceError float64
	// HistogramTailBound is the last finite boundary below the +Inf bucket,
	// and HistogramTailCount how many observations landed above it. They are
	// NOT in the sketch: a quantile that falls in the tail is answerable only
	// as "at least HistogramTailBound".
	HistogramTailBound float64
	HistogramTailCount uint64

	// LogCount is the number of log records in this series. It is redundant
	// with Count for log series and zero everywhere else; it exists so a
	// merged multi-signal view can still answer "how many logs" without
	// carrying the SeriesKey alongside.
	LogCount uint64
	// FirstTimestamp and LastTimestamp bound the log records that contributed.
	// Zero when LogCount is zero.
	FirstTimestamp time.Time
	LastTimestamp  time.Time
}

type Applier interface {
	Apply(DeltaMap) uint64
}

type BacklogStats struct {
	// Rows is the number of delta-log rows currently awaiting finalization.
	Rows int64
	// OldestWindow is the oldest un-finalized window start, 0 when empty.
	OldestWindow int64
	// Bytes is the approximate delta-log payload size.
	Bytes int64
}

type Barrier interface {
	// RunBarrier executes fn with no group commit in flight and no commit
	// able to start until it returns. fn must be bounded — it is on the ACK
	// path of every Export parked behind the writer.
	RunBarrier(fn func()) error
}

type Baseline struct {
	// StartTime is the point's start_time_unix_nano. A change means the
	// producer restarted its counter.
	StartTime time.Time
	// LastTimestamp is the timestamp of the last accepted point. Points at or
	// before it are stale or duplicate.
	LastTimestamp time.Time
	// Value is the last accepted cumulative value.
	Value float64
}

type BaselineRow struct {
	SeriesID SeriesID
	Producer ProducerID
	Baseline Baseline
}

type BaselineStats struct {
	// Entries is the number of live baseline records.
	Entries int
	// Series is the number of series holding at least one baseline.
	Series int
	// Stale counts points ignored as stale or duplicate.
	Stale uint64
	// Seeded counts baselines created.
	Seeded uint64
	// Gaps counts baselines re-seeded after a downtime gap.
	Gaps uint64
	// ResetsStartTime and ResetsRegression count resets by reason.
	ResetsStartTime  uint64
	ResetsRegression uint64
	// ProducerOverflow counts points routed to a degraded shared baseline
	// because the per-series producer bound was exhausted.
	ProducerOverflow uint64
	// GlobalOverflow counts points that could not take a dedicated baseline
	// because the global baseline budget was exhausted.
	GlobalOverflow uint64
	// Owed is the number of records currently carrying an increase whose
	// group commit failed. A number that does not return to zero means the
	// store is refusing writes, not that accounting is drifting.
	Owed int
	// Recovered counts points that re-attributed a stranded increase.
	Recovered uint64
	// Stranded counts stranded increases dropped by a downtime re-seed,
	// which is the one place the owed ledger is deliberately not honoured.
	Stranded uint64
}

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

type BaselineTrackerConfig struct {
	// MaxProducersPerSeries is the per-series producer-baseline bound
	// (AGGREGATE_MAX_PRODUCER_BASELINES_PER_SERIES, default 8). Excess
	// producers share one degraded baseline and never evict the first N.
	MaxProducersPerSeries int
	// MaxBaselines is the global baseline-entry budget
	// (the resolved AGGREGATE_MAX_BASELINES). Past it, only the per-series
	// degraded slot may still be created — it is reserved capacity, exactly
	// like the __other__ series, because refusing it would strand the series.
	MaxBaselines int
	// GapThreshold is the downtime bound: a point more than this after the
	// baseline's last timestamp re-seeds instead of crediting the increase.
	// Defaults to AllowedLateness.
	GapThreshold time.Duration
}

type Bounds struct {
	// MaxValueBytes caps the encoded length of a non-tenant dictionary value.
	MaxValueBytes int
	// MaxTenantBytes caps the encoded length of a tenant name.
	MaxTenantBytes int
	// MaxTenants is the instance-wide tenant-identity cap.
	MaxTenants int
	// PerTenantKind caps entries per (tenant, kind). A missing or zero entry
	// means unlimited. __other__ entries are exempt.
	PerTenantKind map[Kind]int
	// InstanceKind caps entries per kind across every tenant — the backstop
	// behind PerTenantKind. A missing or zero entry means unlimited.
	InstanceKind map[Kind]int
}

type Bucket struct {
	WindowStart int64
	SeriesID    SeriesID
	Delta       *AggregateDelta
	// Source says which table the row came from. A window may hold a
	// materialized bucket and a not-yet-finalized delta row for one series;
	// both are real contributions and both must be counted.
	Source BucketSource
}

type BucketCursor struct {
	WindowStart int64
	SeriesID    SeriesID
	Source      BucketSource
}

type BucketPage struct {
	// Buckets are the rows of this page, ordered by (window, series, source).
	Buckets []Bucket
	// Limit is the row limit that was applied.
	Limit int
	// Truncated reports that more rows matched than this page returned. It is
	// result-completeness metadata and is INDEPENDENT of Coverage: a result
	// can be full-coverage and truncated at the same time (#197 Q4).
	Truncated bool
	// Next resumes the read immediately past the last returned row. Only
	// meaningful when Truncated.
	Next BucketCursor
}

type BucketSource uint8

type BucketsResult struct {
	Points   []TrafficPoint
	Coverage Coverage
	Epoch    string
	Revision uint64
}

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

type CacheStats struct {
	// Hits counts lookups served from the in-memory map.
	Hits uint64
	// Misses counts lookups that reached the Registrar.
	Misses uint64
	// Overflows counts misses the Registrar rejected as ErrDictFull, which
	// were routed to the __other__ entry.
	Overflows uint64
	// Errors counts misses the Registrar failed for any other reason. These
	// were also routed to __other__; Phase 2 must surface this as a metric.
	Errors uint64
	// OverLength counts values refused for exceeding the encoded-length cap
	// and routed to __other__ (#200 Q3). Never truncated.
	OverLength uint64
	// TenantsRejected counts tenant identities refused outright — over-length,
	// empty, or past the instance-wide tenant cap. These points are DROPPED,
	// not collapsed.
	TenantsRejected uint64
	// Fenced counts lookups that hit a dictionary ID the identity-maintenance
	// barrier had fenced, and were therefore served from __other__ (#200 Q2).
	Fenced uint64
}

type Coverage string

type CumulativeOutcome struct {
	// Delta is the increase attributable to this point. Zero for ignored,
	// seeded and gap outcomes.
	Delta float64
	// Ignored is true for a stale or duplicate point: it did not move the
	// baseline and produced no delta (case 1).
	Ignored bool
	// Seeded is true when this point created a baseline. No delta is
	// attributed: the accumulation predates our observation window and
	// crediting it to one 5-minute window would fabricate a rate spike.
	Seeded bool
	// Gap is true when the point arrived more than the allowed-lateness
	// window after the baseline's last timestamp. The computed delta is
	// discarded and the baseline re-seeded (#166 downtime handling): totals
	// under-count across long outages, rates never lie.
	Gap bool
	// Reset is true when a counter reset was detected; Reason says which.
	Reset  bool
	Reason ResetReason
	// Degraded is true when the point was attributed to the per-series shared
	// baseline because the producer bound was exhausted.
	Degraded bool
	// Recovered is true when Delta also carries an increase whose group commit
	// failed earlier and which this point re-attributes (#194 blocker 2). It is
	// informational: the stranded amount is already folded into Delta.
	Recovered bool
}

type DashboardResult struct {
	// RequestCount is accepted request entry points over the range;
	// ErrorRequestCount is its error subset and RequestErrorRate is the
	// headline dashboard error rate, as a PERCENT.
	RequestCount      int64
	ErrorRequestCount int64
	RequestErrorRate  float64
	// SpanCount is accepted spans; SpanErrorCount is its error subset and
	// SpanErrorRate the corresponding PERCENT.
	SpanCount      int64
	SpanErrorCount int64
	SpanErrorRate  float64

	TotalLogs         int64
	AvgLatencyMs      float64
	ActiveServices    int64
	P99LatencyMicros  float64
	LatencyProvenance latency.Provenance
	TopFailing        []ServiceStat
	Accuracy          AccuracyMetadata
	Coverage          Coverage
	Epoch             string
	Revision          uint64
}

type DeltaMap map[SeriesWindowKey]*AggregateDelta

type DeltaRow struct {
	// SeriesID and WindowStart identify the bucket the row contributes to.
	SeriesID    SeriesID
	WindowStart int64
	// Delta is the aggregate contribution. Its sketch is encoded with the
	// versioned codec from #157 on write and decoded on read.
	Delta *AggregateDelta
}

type DictEntry struct {
	ID       uint32
	TenantID uint32
	Kind     Kind
	Value    []byte
}

type DictRow struct {
	ID       uint32
	TenantID uint32
	Kind     Kind
	Value    []byte
}

type DimPair struct {
	KeyID   uint32
	ValueID uint32
}

type DimsConfig map[string][]string

type DirtyBaseline struct {
	Key      SeriesKey
	Producer ProducerID
	Baseline Baseline
	// Inflight is the increase this record emitted as deltas since its last
	// drain. It rides the drain so a failed commit can hand the amount back
	// as owed instead of stranding it (#194 blocker 2). It is not part of the
	// durable BaselineRow — the store never sees it.
	Inflight float64
}

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

type EdgeInput struct {
	Tenant string
	// Caller is the service that owns the parent span.
	Caller string
	// Callee is the service that owns this span.
	Callee string
	// HTTPRoute, URLPath and SpanName resolve the callee's operation for
	// route normalization; only the callee service name enters edge identity.
	HTTPRoute string
	URLPath   string
	SpanName  string

	Method         string
	HTTPStatusCode int
	SpanKind       int32
	StatusCode     int32
	// Root mirrors SpanInput.Root for the callee's span.
	Root bool

	Timestamp      time.Time
	DurationMicros float64
}

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

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

type EngineConfig struct {
	// Mode is the aggregate mode (AGGREGATE_MODE). An Engine is only
	// constructed for a non-legacy mode.
	Mode string

	// Limiter holds the cardinality budget.
	Limiter LimiterConfig

	// MaxProducerBaselinesPerSeries and MaxBaselines bound the cumulative
	// baseline tracker.
	MaxProducerBaselinesPerSeries int
	MaxBaselines                  int

	// Registrar mints dictionary IDs. Defaults to an in-memory registrar
	// whose IDs are provisional and vanish on restart (#173 replaces it).
	Registrar Registrar

	// Bounds are the identity bounds of #200 Q3: encoded-value length caps,
	// per-(tenant, kind) and instance-wide dictionary counts, and the tenant
	// cap. The zero value takes every default.
	Bounds Bounds

	// Miner is the ingest-owned template miner (#163). Defaults to one built
	// from the log-template cap.
	Miner *TemplateMiner

	// Metrics is the Prometheus recorder. nil disables metric recording.
	Metrics MetricsRecorder

	// MetricDims maps metric names to their configured aggregation dimension keys.
	// Nil or empty means no metrics are configured for custom dimensions.
	MetricDims DimsConfig

	// Topology bounds the per-tenant topology projection GraphRAG consumes in
	// aggregate mode (#174). Zero values take the package defaults.
	Topology TopologyConfig

	// EdgeResolverSpans bounds the span-ID memory used to recover a call
	// edge's caller service. Zero takes DefaultEdgeResolverSpans.
	EdgeResolverSpans int

	// MaxClosedWindows bounds the closed-but-unfinalized windows held in
	// memory. Zero takes DefaultMaxClosedWindows; negative is unbounded and
	// is for tests only.
	MaxClosedWindows int

	// Epoch identifies this engine instance. A consumer that sees a new epoch
	// knows the revision counter restarted and must replace its state rather
	// than reconcile against it. Zero derives one from the clock.
	Epoch uint64

	// Now is the clock, injectable for tests. Defaults to time.Now.
	Now func() time.Time
}

type ExpBuckets struct {
	Offset int32
	Counts []uint64
}

type ExponentialHistogramInput struct {
	HistogramCommon
	Scale     int32
	ZeroCount uint64
	Positive  ExpBuckets
	Negative  ExpBuckets
}

type FailableApplier interface {
	Applier
	// ApplyErr applies the deltas, returning the revision and any refusal.
	ApplyErr(DeltaMap) (uint64, error)
}

type FieldError struct {
	Field  string
	Value  uint8
	Signal Signal
}

type FinalizeStats struct {
	// WindowStart is the finalized window.
	WindowStart int64
	// Buckets is the number of bucket rows written or merged.
	Buckets int
	// DeltaRows is the number of delta-log rows incorporated and deleted.
	DeltaRows int
	// Duration is the wall time of the transaction.
	Duration time.Duration
}

type FinalizedPage struct {
	// Buckets are the rows, ordered by (window DESC, series). Newest first, so
	// a cap drops the OLDEST part of the horizon rather than the freshest.
	Buckets []Bucket
	// Truncated reports that more rows matched than the cap allowed.
	Truncated bool
}

type GCConfig struct {
	// Store is the durable aggregate store. Must satisfy GCStore.
	Store Store
	// Registrar owns the dictionary identity maps.
	Registrar *DurableRegistrar
	// Cache is the hot-path intern cache in front of Registrar.
	Cache *Cache
	// Miner is the log-template miner whose templates are GC roots.
	Miner *TemplateMiner
	// Engine supplies the live shard keys.
	Engine *Engine
	// Series is the writer's series registry.
	Series *seriesRegistry
	// Barrier serializes the sweep with the commit path.
	Barrier Barrier
	// Metrics records the pass. nil disables recording.
	Metrics StoreMetrics
}

type GCSnapshot struct {
	// Referenced is every series ID named by aggregate_buckets,
	// aggregate_delta_log or aggregate_baseline.
	Referenced map[SeriesID]struct{}
	// Series, Dict and Templates are the identity tables themselves.
	Series    []SeriesRow
	Dict      []DictRow
	Templates []TemplateRow
}

type GCStats struct {
	// SeriesScanned, DictScanned and TemplatesScanned are the row counts the
	// mark phase examined.
	SeriesScanned, DictScanned, TemplatesScanned int
	// SeriesSwept, DictSwept and TemplatesSwept are the rows actually deleted.
	SeriesSwept, DictSwept, TemplatesSwept int64
	// SeriesRetained and DictRetained are the rows the mark phase kept.
	SeriesRetained, DictRetained int
	// Revalidated counts candidates the barrier rescued after the lock-free
	// scan — a non-zero value is normal under load, a large one means the scan
	// is running too long.
	Revalidated int
	// MarkDuration is the lock-free scan; BarrierDuration is the part that
	// serializes with the writer. Only the second belongs in an ACK-latency
	// budget.
	MarkDuration, BarrierDuration time.Duration
	// Duration is the wall time of the whole pass.
	Duration time.Duration
}

type GCStore interface {
	// GCSnapshot reads the reference set and all three identity tables inside
	// ONE read transaction. It runs on the READ pool, without the writer
	// lock: the full scan is the part of GC that must never become an
	// ACK-latency incident.
	GCSnapshot() (*GCSnapshot, error)

	// LoadTemplates returns every durable log-template row, capped at max.
	LoadTemplates(max int) ([]TemplateRow, error)

	// SweepIdentities deletes the given series, dictionary and template rows
	// in ONE transaction, series first. It runs under the writer lock. A
	// partial sweep is never observable: either every row named here is gone
	// or none of them are.
	SweepIdentities(series []SeriesID, dict []uint32, templates []uint32) (SweepStats, error)

	// SaveTemplateStats refreshes the non-identity template counters. Rows
	// whose template no longer exists are ignored, not created.
	SaveTemplateStats(rows []TemplateStatRow) error
}

type GroupBatch struct {
	Dicts     []DictRow
	Series    []SeriesRow
	Deltas    []DeltaRow
	Baselines []BaselineRow
	// Templates are identity-critical log-template mutations: a new template,
	// a pattern generalization, or an alias change (#200 Q4). They ride the
	// same transaction as the delta that used the resulting identity, because
	// a 15-minute snapshot alone lets acknowledged identity state vanish in a
	// crash — the bucket would survive naming a template ID that the reloaded
	// miner has never heard of.
	Templates []TemplateRow
}

type GroupBy uint8

type HTTPClass uint8

type HistogramCommon struct {
	Tenant   string
	Service  string
	Name     string
	Resource ResourceIdentity

	Timestamp time.Time
	StartTime time.Time

	Temporality Temporality
	Attributes  []*commonpb.KeyValue
	// ResourceAttributes are the RAW OTLP resource attributes; a configured
	// dimension key the point lacks falls back to them (#279).
	ResourceAttributes []*commonpb.KeyValue

	Count  uint64
	Sum    float64
	HasSum bool
	Min    float64
	HasMin bool
	Max    float64
	HasMax bool
}

type HistogramFold struct {
	Sketch *Sketch
	Count  uint64
	Sum    float64
	HasSum bool
	Min    float64
	HasMin bool
	Max    float64
	HasMax bool

	// PercentilesUnavailable suppresses every quantile derived from this
	// point, and DropReason says why.
	PercentilesUnavailable bool
	DropReason             SketchDropReason

	// SourceBucketError is the worst-case relative error contributed by the
	// SOURCE histogram's own bucket widths, as a fraction. It is 0 for an
	// exponential histogram (index transfer is exact) and can dwarf the
	// scale-4 sketch's 2.17% for a coarse explicit-bounds histogram.
	SourceBucketError float64

	// UnboundedTail reports that observations landed in the +Inf bucket.
	// Those observations are deliberately NOT folded into the sketch: their
	// only known property is "greater than UnboundedTailBound", and placing
	// them at any finite value would turn a lower bound into a fabricated
	// estimate. UnboundedTailCount is how many.
	UnboundedTail      bool
	UnboundedTailBound float64
	UnboundedTailCount uint64
}

type HistogramInput struct {
	HistogramCommon
	Bounds       []float64
	BucketCounts []uint64
}

type Kind uint8

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

type LimiterConfig struct {
	MaxSeries        int
	MaxSeriesMetrics int
	MaxSeriesTraces  int
	MaxSeriesEdges   int
	MaxSeriesLogs    int
	MaxSeriesSystem  int

	MaxOperationsPerService   int
	MaxLogTemplatesPerService int
	MaxTraceSeriesPerService  int
	MaxMetricSeriesPerService int

	// SeriesPerTenantFraction is the fraction of MaxSeries one tenant may
	// hold. 0 disables the tenant cap (the single-tenant default).
	SeriesPerTenantFraction float64

	// OtherNameID resolves the dictionary __other__ ID for the name kind of a
	// signal, which is what an overflow series uses as its NameID. Required.
	OtherNameID func(tenantID uint32, signal Signal) uint32
}

type LimiterStats struct {
	// Active is the number of distinct budgeted series present in a mutable
	// window. __other__ series are excluded: they are the reserve the caps
	// spend, not occupancy the caps admit, and counting them here is what let
	// the observed census exceed its own sub-cap (#173).
	Active int
	// ActiveBySignal breaks Active down per signal. Each entry is bounded by
	// that signal's sub-cap.
	ActiveBySignal map[Signal]int
	// Overflow counts admissions routed to an __other__ series, per reason.
	Overflow map[OverflowReason]uint64
	// OverflowSeries is the number of live __other__ series.
	OverflowSeries int
	// OverflowSeriesBySignal breaks OverflowSeries down per signal. This is
	// the reserve's real occupancy — unbudgeted, bounded by
	// (services x signals x status classes).
	OverflowSeriesBySignal map[Signal]int
}

type LogInput struct {
	Tenant  string
	Service string
	// Severity is the severity text; SeverityNumber is the OTLP number and
	// wins when non-zero.
	Severity       string
	SeverityNumber int32
	// Body is mined into a template. It never enters series identity itself.
	Body      string
	Timestamp time.Time
}

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

type MemRegistrarOptions struct {
	// Limits caps the number of entries per (tenant, kind). A missing or
	// zero entry means unlimited. __other__ entries are exempt.
	Limits map[Kind]int
}

type Method uint8

type MetricInput struct {
	Tenant  string
	Service string
	Name    string
	Value   float64
	// Timestamp selects the window; StartTime is the cumulative start time
	// used for reset detection.
	Timestamp time.Time
	StartTime time.Time
	// Temporality and Monotonic select the aggregation model (#166).
	Temporality Temporality
	Monotonic   bool
	// Resource carries the stable identity used to derive the ProducerID.
	Resource ResourceIdentity
	// Attributes are the RAW OTLP point attributes. The configured dimension
	// tuple is extracted from them here, against a request-local scratch, so
	// the hot path never allocates a per-point map (#199 Q4).
	Attributes []*commonpb.KeyValue
	// ResourceAttributes are the RAW OTLP resource attributes; a configured
	// dimension key the point lacks falls back to them (#279).
	ResourceAttributes []*commonpb.KeyValue
}

type MetricPointOutcome uint8

type MetricPointResult struct {
	Outcome MetricPointOutcome
	// Reason is the metric label for a rejection, "" when accepted.
	Reason string
	// Err carries the validation failure behind PointRejectedMalformed.
	Err error
	// SketchDropped reports that the point's scalars were accepted but its
	// percentiles suppressed, and DropReason says why. This is NOT a
	// rejection: the point still contributes count, sum, min and max.
	SketchDropped bool
	DropReason    SketchDropReason
}

type MetricsRecorder interface {
	// RecordReduction publishes one Export request's reduction accounting:
	// input points, emitted deltas, the reduction ratio, late/future
	// exclusions, and the shadow-comparison counters.
	RecordReduction(stats ReducerStats, deltas map[Signal]uint64)
	// RecordOverflow counts one admission rerouted to an __other__ series.
	RecordOverflow(signal Signal, reason OverflowReason)
	// SetActiveSeries publishes the budgeted active-series census and the
	// __other__ reserve occupancy, both per signal. They are separate numbers
	// because only the first is bounded by the AGGREGATE_MAX_SERIES* caps.
	SetActiveSeries(active, overflow map[Signal]int)
	// SetClosedWindows publishes how many closed-but-unfinalized windows the
	// engine is holding. It is the finalizer-backlog signal: a value that does
	// not return to zero means finalization is failing.
	SetClosedWindows(held int)
	// RecordClosedWindowEvicted counts one closed window the cap forced out of
	// memory before it was finalized. Every one is lost data.
	RecordClosedWindowEvicted()
	// RecordTenantRejected counts one point dropped because its tenant
	// identity was refused (#200 Q3). Unlike every other identity cap this is
	// a DROP, so it deserves its own counter rather than a reason label on
	// the overflow one.
	RecordTenantRejected(signal Signal)
	// RecordIdentityOverflow counts one identity routed to __other__ by a
	// #200 Q3 bound, labeled by dictionary kind and the bound that tripped
	// ("length" or "count").
	RecordIdentityOverflow(kind Kind, bound string)
}

type OverflowReason uint8

type Ownership struct {
	// Epoch is the process generation.
	Epoch string
	// Revision is the engine revision at capture time.
	Revision uint64
	// Mutable is the memory-owned window starts, oldest first.
	Mutable []int64
	// FinalizedWatermark is the newest store-owned window start. Zero means
	// nothing has been handed over yet.
	FinalizedWatermark int64
}

type PointDisposition uint8

type PreloadError struct {
	Table string
	Rows  int
	Max   int
}

type ProducerID uint64

type PurgeStats struct {
	// Buckets and Deltas count deleted rows.
	Buckets int64
	Deltas  int64
	// Baselines counts baselines dropped because their series has no
	// remaining data.
	Baselines int64
	// Duration is the wall time of the whole purge.
	Duration time.Duration
}

type Query struct {
	// Tenant is the tenant name. Required.
	Tenant string
	// Start and End bound the read. Required, Start before End.
	Start, End time.Time
	// Services, when non-empty, restricts the read to these service names.
	Services []string
	// Signal, when non-zero, restricts the read to one signal.
	Signal Signal
}

type RecoverOptions struct {
	// TopologyHorizon is how much FINALIZED history is rebuilt into the
	// engine's topology projection. Zero disables the restore; anything past
	// the projection's own horizon is clamped down to it, because a window the
	// projection would prune on arrival is not worth reading.
	TopologyHorizon time.Duration
	// TopologyMaxRows caps the finalized rows one restore may read. Zero takes
	// DefaultTopologyRestoreMaxRows. It is the second bound on startup cost:
	// the horizon says how far back, this says how much.
	TopologyMaxRows int
}

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

type RecoveryStats struct {
	// FinalizedWindows counts windows finalized because their lateness
	// horizon expired during downtime.
	FinalizedWindows int
	// ReplayedRows and ReplayedSeries count delta-log rows read back and the
	// distinct (series, window) pairs they folded into.
	ReplayedRows   int
	ReplayedSeries int
	// SeededBaselines counts cumulative baselines restored.
	SeededBaselines int
	// RestoredTopologyRows counts the durable rows the topology restore read:
	// finalized bucket rows inside the horizon plus the replayed mutable rows,
	// which are in the shards but not in the projection.
	RestoredTopologyRows int
	// RestoredTopologyWindows counts the (series, window) pairs that actually
	// LANDED in the projection. It is lower than RestoredTopologyRows whenever
	// the projection's cutoff or one of its caps refused a row.
	RestoredTopologyWindows int
	// RestoredTopologyTruncated reports that the row cap cut the horizon
	// short. The restored topology is real but incomplete at its oldest end.
	RestoredTopologyTruncated bool
	// SkippedSeries counts delta rows whose series id no longer resolves —
	// structurally impossible while registration and first delta share a
	// transaction, so a non-zero value here is a corruption signal.
	SkippedSeries int
	// Duration is the wall time of the whole recovery.
	Duration time.Duration
}

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

type ReducerStats struct {
	// InputPoints counts points offered to the reducer, per signal, including
	// the ones excluded as late or future.
	InputPoints [signalCount]uint64
	// LatePoints counts points older than the lateness horizon. They are
	// excluded from aggregates and counted here — never dropped silently
	// (#160). The raw/exemplar path still sees them.
	LatePoints [signalCount]uint64
	// FuturePoints counts points timestamped beyond the tolerated skew.
	FuturePoints [signalCount]uint64
	// Accepted counts points that contributed to a delta. This is the
	// shadow-comparison numerator: it must be identical for the same input
	// stream at any sampling rate.
	Accepted [signalCount]uint64
	// StaleCumulative counts cumulative points ignored as stale or duplicate
	// against their baseline (#166 case 1).
	StaleCumulative uint64
	// DimsRejected counts metric points whose configured dimension tuple was
	// refused from series identity because an attribute value had no scalar
	// rendering (#199 Q4). The point is still aggregated, under DimsID 0.
	DimsRejected uint64
	// TenantsRejected counts points DROPPED because their tenant identity was
	// refused — over-length, empty, or past the instance-wide tenant cap
	// (#200 Q3). Every other namespace degrades into __other__; the tenant
	// namespace refuses instead, because a shared overflow tenant is exactly
	// the cross-tenant merge the cap exists to prevent.
	TenantsRejected uint64
	// ErrorsByService counts errors per service — the cheap invariant #165
	// asks for on the aggregate side, and nothing more expensive.
	ErrorsByService map[string]uint64
}

type Registrar interface {
	// Register returns the ID for (tenantID, kind, value), minting one if the
	// value is new. It returns ErrDictFull when the namespace is at capacity.
	Register(tenantID uint32, kind Kind, value []byte) (uint32, error)

	// OtherID returns the pre-created overflow ID for (tenantID, kind). It
	// never fails: the entry is created outside the capacity cap.
	OtherID(tenantID uint32, kind Kind) uint32
}

type ResetReason uint8

type Resolver interface {
	// Lookup returns the entry for id. ok is false when the ID is unknown.
	Lookup(id uint32) (DictEntry, bool)
}

type ResourceIdentity struct {
	// ServiceInstanceID is service.instance.id. When present it IS the
	// producer identity — the semantic convention exists for exactly this.
	ServiceInstanceID string
	// ServiceNamespace is service.namespace.
	ServiceNamespace string
	// ServiceName is service.name.
	ServiceName string
	// Host is host.id, else host.name.
	Host string
	// Workload is k8s.pod.uid, else container.id, else process.pid.
	Workload string
}

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

type SaturationError struct {
	// Bound is "bytes", "waiters" or "deltas".
	Bound string
	// Current is the value at the moment of refusal; Limit is the cap.
	Current, Limit int64
}

type SchemaError struct {
	// Reason is a short machine-ish description ("missing_meta",
	// "partial_schema", "version_mismatch").
	Reason string
	// Key names the meta key when Reason is "version_mismatch".
	Key string
	// Got and Want are the mismatched values.
	Got, Want string
	// Detail carries anything else worth printing.
	Detail string
}

type Selector struct {
	// TenantID scopes the read. Required.
	TenantID uint32
	// Start and End bound the window range, inclusive of Start and exclusive
	// of End, in UTC-aligned Unix seconds. Required, Start < End.
	Start, End int64
	// Signal, when non-zero, restricts the read to one signal.
	Signal Signal
	// Signals, when non-empty, restricts the read to this set of signals. It
	// is the multi-signal form of Signal for a query that folds several
	// signals in one scan (the dashboard reads trace ops and logs); the two
	// are mutually exclusive.
	Signals []Signal
	// SeriesIDs, when non-empty, restricts the read to these series.
	SeriesIDs []SeriesID
	// Limit caps returned rows. Zero takes MaxReadRows; anything above it is
	// clamped down, never up.
	Limit int
	// After resumes a paged read immediately past this cursor. The zero value
	// starts at the beginning of the range.
	After BucketCursor
	// SketchOnly restricts the read to rows that carry a sketch. It is the
	// percentile path's filter: a row with no sketch cannot move a quantile,
	// so paging past it is wasted work.
	SketchOnly bool
}

type SeriesID int64

type SeriesInfo struct {
	ID  SeriesID
	Key SeriesKey
}

type SeriesKey struct {
	TenantID    uint32
	ServiceID   uint32
	NameID      uint32
	DimsID      uint32
	Signal      Signal
	StatusClass StatusClass
	HTTPClass   HTTPClass
	Method      Method
	Variant     Variant
}

type SeriesRow struct {
	ID  SeriesID
	Key SeriesKey
}

type SeriesWindowKey struct {
	Key         SeriesKey
	WindowStart int64
}

type ServiceStat struct {
	Service           string
	Count             int64
	ErrorCount        int64
	ErrorRate         float64
	AvgLatencyMs      float64
	P99LatencyMicros  float64
	LatencyProvenance latency.Provenance
	RequestCount      int64
	ErrorRequestCount int64
}

type Signal uint8

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

type SketchDropReason uint8

type Snapshot struct {
	// Revision is the revision at the end of the walk.
	Revision uint64
	// Windows are the mutable windows, oldest first.
	Windows []WindowSnapshot
	// ActiveSeries and ActiveBySignal mirror the limiter's census.
	ActiveSeries   int
	ActiveBySignal map[Signal]int
	// Overflow counts admissions rerouted to an __other__ series, per reason.
	Overflow map[OverflowReason]uint64
	// WindowsDiscarded and SeriesDiscarded count rollover loss.
	WindowsDiscarded uint64
	SeriesDiscarded  uint64
	// ClosedWindowsForced counts closed-but-unfinalized windows the cap
	// forced out of memory. Every one is data the finalizer never
	// materialized, so a non-zero value means the finalizer is behind.
	ClosedWindowsForced uint64
	// ClosedWindows is how many closed-but-unfinalized windows memory holds.
	ClosedWindows int
}

type SnapshotEdge struct {
	Caller    string           `json:"caller"`
	Callee    string           `json:"callee"`
	FirstSeen time.Time        `json:"first_seen"`
	LastSeen  time.Time        `json:"last_seen"`
	Windows   []TopologyWindow `json:"windows"`
}

type SpanInput struct {
	Tenant  string
	Service string
	// SpanName is the raw span name, used for operation naming when no route
	// attribute is present.
	SpanName string
	// HTTPRoute is http.route, URLPath is url.path or http.target. Route
	// normalization precedence is fixed in #159.
	HTTPRoute string
	URLPath   string
	// Method is the raw HTTP method string; it collapses onto the bounded
	// Method enum.
	Method string
	// HTTPStatusCode is http.response.status_code, 0 when absent.
	HTTPStatusCode int
	// SpanKind and StatusCode are the OTLP numeric values.
	SpanKind   int32
	StatusCode int32
	// Root reports that the span has no parent span, i.e. it starts a trace.
	// The parent span ID itself is NOT carried: it is on the permanent banned
	// list (#153, #159) and only its emptiness affects an aggregate.
	Root bool
	// Timestamp is the span start time; it selects the window.
	Timestamp      time.Time
	DurationMicros float64
}

type StatusClass uint8

type Store interface {
	// CommitGroup writes one group batch inside exactly one transaction.
	// Either everything in the batch is durable when it returns nil, or
	// nothing in it is.
	CommitGroup(b *GroupBatch) error

	// FinalizeWindow materializes the window's buckets from the delta log and
	// deletes exactly the delta rows it incorporated, in one transaction.
	FinalizeWindow(windowStart int64) (FinalizeStats, error)

	// FinalizableWindows returns the un-finalized window starts at or below
	// cutoff, oldest first, capped at limit.
	FinalizableWindows(cutoff int64, limit int) ([]int64, error)

	// PurgeBefore deletes finalized history older than cutoff.
	PurgeBefore(cutoff int64) (PurgeStats, error)

	// ReadBuckets returns the store-owned rows matching sel: materialized
	// buckets AND any not-yet-finalized delta rows for the same range. Both
	// are store-owned data once the engine has handed the window over, and
	// omitting either is exactly the silent omission #194 blocker 4 is about.
	//
	// The selector's bounds are mandatory and the row cap is enforced
	// store-side. The read asks the database for limit+1 rows and reports
	// Truncated rather than trimming in silence; a caller that needs every row
	// pages with Selector.After until Truncated is false.
	ReadBuckets(ctx context.Context, sel Selector) (BucketPage, error)

	// SumBuckets aggregates the same row set as ReadBuckets in SQL, grouped by
	// by. NO row cap applies: the result is bounded by the grouping — windows,
	// services, signals — not by the number of rows scanned, which is what
	// makes a scalar dashboard total structurally impossible to truncate.
	SumBuckets(ctx context.Context, sel Selector, by GroupBy) ([]SumRow, error)

	// VisitSketches streams every sketch-bearing row matching sel — from
	// BOTH durable tables, like ReadBuckets — to visit, in no particular
	// order. It is the percentile path of the #197 read contract: a quantile
	// sketch cannot be SUMmed in SQL, but its merge is commutative and
	// associative, so no total order and no pagination are needed — one
	// unordered pass replaces the sorted, keyset-paged drain that made a
	// wide dashboard range cost O(pages) sorted re-scans (#219).
	//
	// The selector's bounds are mandatory (Selector.Validate applies) and
	// SketchOnly is implied. The row cap is NOT applied: it bounds RESULT
	// sizes, and this read's result is whatever the caller folds the
	// visited sketches into; the scan itself is bounded by the validated
	// window span, the same bound SumBuckets relies on.
	//
	// The visited sketch is valid only for the duration of the call: the
	// store decodes every row into one scratch value, so a visitor must
	// merge or copy it, never retain the pointer.
	VisitSketches(ctx context.Context, sel Selector, visit func(serviceID uint32, sk *Sketch) error) error

	// ReplayMutable returns the delta-log rows for windows at or after since —
	// the mutable set only. Finalized history never hydrates into RAM (#160).
	ReplayMutable(since int64) ([]DeltaRow, error)

	// ReadFinalizedSince returns MATERIALIZED bucket rows at or after since
	// for the given signals, across every tenant, NEWEST window first, capped
	// at limit rows.
	//
	// It is the one bounded exception to "finalized history never hydrates"
	// (#194 finding 15): the topology projection is rebuilt from it at
	// startup so a restart does not erase the recent service map. It feeds
	// the projection ONLY — never the mutable shards — and the two bounds
	// that keep it a startup cost rather than a startup stall are the caller's
	// horizon (since) and the row cap. Truncated reports that the cap cut the
	// answer, so a restored topology is never presented as complete when it
	// is not.
	ReadFinalizedSince(since int64, signals []Signal, limit int) (FinalizedPage, error)

	// LoadBaselines returns every durable cumulative baseline, capped at max.
	LoadBaselines(max int) ([]BaselineRow, error)

	// ResolveSeries resolves series IDs back to their identity. The input
	// count is capped at MaxReadRows.
	ResolveSeries(ids []SeriesID) ([]SeriesInfo, error)

	// LoadDict returns every dictionary row, capped at max. It is how the
	// durable registrar warms its cache at startup so IDs stay stable.
	LoadDict(max int) ([]DictRow, error)

	// LoadSeries returns every series row, capped at max.
	LoadSeries(max int) ([]SeriesRow, error)

	// Backlog reports the delta-log backlog health bounds.
	Backlog() (BacklogStats, error)

	// Close releases the store's connections.
	Close() error
}

type StoreConfig struct {
	// Path is the database file (AGGREGATE_DB_PATH). Empty takes
	// DefaultAggregateDBPath. ":memory:" and file: URIs are honoured for
	// tests.
	Path string
	// AllowRebuild permits DESTROYING and recreating the aggregate tables
	// when the on-disk schema is partial or version-mismatched
	// (AGGREGATE_ALLOW_REBUILD). Off by default: silent data loss is worse
	// than a refused startup.
	AllowRebuild bool
	// Synchronous is the SQLite synchronous mode ("NORMAL" or "FULL").
	// Empty takes NORMAL. See the stanza comment in open() for the durability
	// argument.
	Synchronous string
	// ReadPoolSize is the read-connection count. Zero takes the default.
	ReadPoolSize int
	// CacheSizeKB is the per-connection page cache in KB, applied as a
	// negative cache_size. Zero takes 32 MB — the aggregate working set is
	// the mutable delta log, not seven days of buckets.
	CacheSizeKB int
	// Metrics is the durable path's metric surface. nil disables recording.
	Metrics StoreMetrics
}

type StoreInspection struct {
	State                 string
	ExpectedSchemaVersion int
	ActualSchemaVersion   int
	ExpectedSeriesVersion int
	ActualSeriesVersion   int
	ExpectedSketchVersion int
	ActualSketchVersion   int
	StoreUUID             string
	MigrationResult       string
	Detail                string
}

type StoreMetrics interface {
	// RecordCommit publishes one group commit: its wall time, how many
	// deltas it carried and how many bytes it wrote.
	RecordCommit(d time.Duration, deltas int, bytes int64, err error)
	// RecordAdmissionRejected counts one ErrSaturated refusal by bound.
	RecordAdmissionRejected(bound string)
	// RecordFinalize publishes one window finalization.
	RecordFinalize(stats FinalizeStats, err error)
	// RecordPurge publishes one retention purge.
	RecordPurge(stats PurgeStats, err error)
	// SetBacklog publishes the delta-log backlog health bounds.
	SetBacklog(rows int64, ageSeconds float64)
	// RecordRecovery publishes one startup recovery: its duration and every
	// row class it moved.
	RecordRecovery(stats RecoveryStats)
	// RecordGC publishes one identity garbage-collection pass.
	RecordGC(stats GCStats, err error)
}

type SumRow struct {
	WindowStart int64
	ServiceID   uint32
	// NameID is set only when GroupByName was requested. It resolves through
	// NameKind(Signal), never through the service namespace.
	NameID uint32
	Signal Signal

	Count             uint64
	ErrorCount        uint64
	RequestCount      uint64
	ErrorRequestCount uint64
	DurationCount     uint64
	DurationSum       float64
	LogCount          uint64
}

type SweepStats struct {
	// Series, Dict and Templates count deleted rows per table.
	Series, Dict, Templates int64
	// Duration is the wall time of the delete transaction.
	Duration time.Duration
}

type TemplateFact struct {
	Tenant     string
	Service    string
	Severity   string
	TemplateID uint32
	Template   string
	Timestamp  time.Time
	IsOther    bool
}

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

type TemplateMinerConfig struct {
	// MaxTemplatesPerService caps distinct mined templates per
	// (tenant, service). The overflow template is reserved capacity and does
	// not count against it. Default DefaultMaxLogTemplatesPerService.
	MaxTemplatesPerService int

	// Depth is the prefix-tree depth below the token-length layer.
	// Default 4, minimum 1.
	Depth int

	// SimilarityThreshold is Drain's simSeq threshold in (0, 1]. Default 0.4.
	SimilarityThreshold float64

	// MaxChildren caps distinct children per tree node; overflow tokens route
	// through the wildcard child. Default 100.
	MaxChildren int

	// MaxTokens bounds tokens taken from one log body, keeping Mine() latency
	// independent of body size. Default 128.
	MaxTokens int

	// Registrar allocates template IDs. Default NewInMemoryTemplateRegistrar().
	Registrar TemplateRegistrar

	// OnFact, when set, is called synchronously for every mined line —
	// including overflow lines — outside the partition lock. Keep it cheap.
	OnFact func(TemplateFact)
}

type TemplatePartitionStats struct {
	Tenant            string
	Service           string
	Templates         int    // live mined templates (excludes __other__)
	OtherID           uint32 // 0 when the overflow identity is not allocated
	Overflow          uint64 // lines absorbed by __other__
	Converged         uint64 // templates retired into a surviving twin
	RegistrarFailures uint64
}

type TemplateRegistrar interface {
	RegisterTemplate(TemplateRegistration) (uint32, error)
}

type TemplateRegistrarFunc func(TemplateRegistration) (uint32, error)

type TemplateRegistration struct {
	Tenant   string
	Service  string
	Template string // rendered template text at registration time
	IsOther  bool   // true for a partition's pre-created __other__ identity
}

type TemplateRow struct {
	// ID is the immutable surrogate template identity — the same uint32 the
	// log_template dictionary minted, and the NameID of every log series that
	// used it.
	ID uint32
	// Tenant and Service name the partition. They are the strings, not
	// dictionary IDs: the miner is keyed by them and a reload must rebuild
	// its partitions before any dictionary lookup is warm.
	Tenant, Service string
	// PatternVersion increments on every generalization of Tokens. It makes a
	// stale periodic stats write unable to overwrite a newer pattern.
	PatternVersion uint32
	// Tokens is the token pattern, NUL-joined. Tokens never contain
	// whitespace (the tokenizer splits on it) and never contain NUL.
	Tokens string
	// Seq is the partition-local creation ordinal. Convergence keeps the
	// lower one, so it has to survive a restart or two restarts could pick
	// different survivors for the same pair.
	Seq uint64
	// IsOther marks the partition's pre-created overflow identity.
	IsOther bool
	// AliasOf is the surviving template this ID forwards to, or 0.
	AliasOf uint32
	// Count, FirstSeen and LastSeen are the non-identity statistics. They are
	// refreshed by the periodic dirty-partition write, not by the identity
	// commit path.
	Count               uint64
	FirstSeen, LastSeen int64
}

type TemplateStatRow struct {
	ID                  uint32
	Count               uint64
	FirstSeen, LastSeen int64
}

type Temporality uint8

type TopologyConfig struct {
	MaxServices             int
	MaxOperationsPerService int
	MaxEdges                int
	MaxMetrics              int
	// Horizon is the finalized history retained behind the mutable windows.
	Horizon time.Duration
}

type TopologyEdge struct {
	Source, Target string
	CallCount      int64
	AvgLatencyMs   float64
	ErrorRate      float64
}

type TopologyMetric struct {
	Service   string           `json:"service"`
	Metric    string           `json:"metric"`
	FirstSeen time.Time        `json:"first_seen"`
	LastSeen  time.Time        `json:"last_seen"`
	Windows   []TopologyWindow `json:"windows"`
}

type TopologyOperation struct {
	Service   string           `json:"service"`
	Operation string           `json:"operation"`
	FirstSeen time.Time        `json:"first_seen"`
	LastSeen  time.Time        `json:"last_seen"`
	Windows   []TopologyWindow `json:"windows"`
}

type TopologyResult struct {
	Nodes    []ServiceStat
	Edges    []TopologyEdge
	Coverage Coverage
	Epoch    string
	Revision uint64
}

type TopologyService struct {
	Name      string           `json:"name"`
	FirstSeen time.Time        `json:"first_seen"`
	LastSeen  time.Time        `json:"last_seen"`
	Windows   []TopologyWindow `json:"windows"`
}

type TopologySnapshot struct {
	Tenant   string    `json:"tenant"`
	Epoch    uint64    `json:"epoch"`
	Revision uint64    `json:"revision"`
	Now      time.Time `json:"now"`

	Horizon time.Duration `json:"horizon"`

	Services   []TopologyService   `json:"services"`
	Operations []TopologyOperation `json:"operations"`
	Edges      []SnapshotEdge      `json:"edges"`
	Metrics    []TopologyMetric    `json:"metrics"`

	// Dropped* count facts refused by the projection caps since startup.
	// Non-zero means the topology is truncated and must be presented as such.
	DroppedServices   uint64 `json:"dropped_services,omitempty"`
	DroppedOperations uint64 `json:"dropped_operations,omitempty"`
	DroppedEdges      uint64 `json:"dropped_edges,omitempty"`
	DroppedMetrics    uint64 `json:"dropped_metrics,omitempty"`
}

type TopologyWindow struct {
	Start   time.Time     `json:"start"`
	End     time.Time     `json:"end"`
	Closed  bool          `json:"closed"`
	Final   bool          `json:"final"`
	Elapsed time.Duration `json:"elapsed"`

	Count      uint64 `json:"count"`
	ErrorCount uint64 `json:"error_count"`

	DurationCount     uint64  `json:"duration_count,omitempty"`
	DurationSumMicros float64 `json:"duration_sum_micros,omitempty"`
	DurationMinMicros float64 `json:"duration_min_micros,omitempty"`
	DurationMaxMicros float64 `json:"duration_max_micros,omitempty"`
	// P95Micros and P99Micros come from the merged latency sketch. They are
	// zero when the entity carries no sketch (operations, edges and metrics
	// deliberately do not, so a 2 KiB sketch is not multiplied by every
	// operation of every service of every window).
	P95Micros         float64             `json:"p95_micros,omitempty"`
	P99Micros         float64             `json:"p99_micros,omitempty"`
	LatencyProvenance *latency.Provenance `json:"latency_provenance,omitempty"`

	// Value* carry metric samples: gauge samples plus counter deltas, which
	// is what a rolling mean/variance baseline is computed over.
	ValueCount uint64  `json:"value_count,omitempty"`
	ValueSum   float64 `json:"value_sum,omitempty"`
	ValueMin   float64 `json:"value_min,omitempty"`
	ValueMax   float64 `json:"value_max,omitempty"`
}

type TrafficPoint struct {
	// WindowStart is the UTC start of the five-minute window.
	WindowStart time.Time
	// RequestCount is accepted request entry points — root or SERVER spans.
	// ErrorRequestCount is its error subset.
	RequestCount, ErrorRequestCount int64
	// SpanCount is accepted spans; SpanErrorCount is its error subset.
	SpanCount, SpanErrorCount int64
}

type Variant uint8

type VersionError struct {
	Got  uint8
	Want uint8
}

type WatermarkStore interface {
	// Watermarks returns the persisted dictionary and series high-watermarks:
	// the next ID each allocator may mint. Zero means "not yet stamped".
	Watermarks() (uint32, SeriesID, error)
}

type WindowSnapshot struct {
	// Start is the window's UTC start.
	Start time.Time
	// Series maps each active series in the window to a copy of its delta.
	Series map[SeriesKey]*AggregateDelta
}

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

type WriterConfig struct {
	// Store is the durable store. Required.
	Store Store
	// Engine is the engine whose shards receive committed deltas. Required.
	Engine *Engine
	// Registrar is the durable dictionary registrar whose staged rows ride
	// each commit. Required when the engine was built with one.
	Registrar *DurableRegistrar

	// CoalesceWindow, MaxBatchDeltas and MaxBatchBytes set the commit cadence.
	CoalesceWindow time.Duration
	MaxBatchDeltas int
	MaxBatchBytes  int64

	// MaxPendingBytes, MaxWaiters and MaxPendingDeltas are the triple
	// admission bound.
	MaxPendingBytes  int64
	MaxWaiters       int
	MaxPendingDeltas int

	// FinalizeInterval is the window-finalization tick. Zero takes the
	// default; negative disables the loop (tests drive it by hand).
	FinalizeInterval time.Duration

	// Metrics is the durable path's metric surface.
	Metrics StoreMetrics

	// Now is the clock, injectable for tests.
	Now func() time.Time
}

type WriterStats struct {
	// Commits and CommitErrors count group commits attempted and failed.
	Commits, CommitErrors uint64
	// Deltas counts delta rows written.
	Deltas uint64
	// Rejections counts ErrSaturated refusals.
	Rejections uint64
	// PendingBytes, PendingDeltas and Waiters are the live admission
	// occupancy.
	PendingBytes  int64
	PendingDeltas int
	Waiters       int
	// Finalized counts windows finalized by the writer's state machine.
	Finalized uint64

	// The runtime-readiness surface (#194 finding 18). Cumulative counters
	// say what happened since boot; a readiness probe needs to know what is
	// happening NOW, which is what the streaks and the cached backlog sample
	// carry.
	//
	// CommitFailureStreak and FinalizeFailureStreak count CONSECUTIVE
	// failures: any success resets them to zero. A handful of failures spread
	// over a week is a log line; three in a row is a store that has stopped
	// accepting writes.
	CommitFailureStreak   uint64
	FinalizeFailureStreak uint64
	// FinalizeErrors counts finalization failures since boot.
	FinalizeErrors uint64

	// MaxPendingBytes, MaxPendingDeltas and MaxWaiters are the configured
	// admission bounds the live occupancy above is measured against.
	MaxPendingBytes  int64
	MaxPendingDeltas int
	MaxWaiters       int

	// DeltaLogRows, DeltaLogAgeSeconds and BacklogSampledAt are the last
	// delta-log backlog sample the finalize loop published. Cached rather
	// than queried on demand so a readiness probe never stacks behind the
	// single SQLite writer. BacklogSampledAt is zero before the first sample.
	DeltaLogRows       int64
	DeltaLogAgeSeconds float64
	BacklogSampledAt   time.Time
}