rbi

type BatchStats struct {
	// Enabled reports whether write combining is enabled.
	Enabled bool
	// Window is current coalescing window duration.
	Window time.Duration
	// MaxBatch is configured maximum combined batch size.
	MaxBatch int
	// MaxQueue is configured maximum queue size (0 means unbounded).
	MaxQueue int
	// AllowCallbacks reports whether callback-bearing writes can be combined.
	AllowCallbacks bool

	// QueueLen is current pending requests in queue.
	QueueLen int
	// QueueCap is current allocated queue capacity.
	QueueCap int
	// WorkerRunning reports whether combiner worker goroutine is active.
	WorkerRunning bool
	// HotWindowActive reports whether adaptive hot coalescing window is active.
	HotWindowActive bool

	// Submitted is number of submit attempts from eligible write calls.
	Submitted uint64
	// Enqueued is number of requests accepted into combiner queue.
	Enqueued uint64
	// Dequeued is number of requests popped from queue for execution.
	Dequeued uint64
	// QueueHighWater is maximum observed queue length.
	QueueHighWater uint64

	// Batches is total executed combined-transaction batches.
	Batches uint64
	// CombinedBatches is number of batches containing more than one request.
	CombinedBatches uint64
	// CombinedOps is total requests executed inside multi-request batches.
	CombinedOps uint64
	// AvgBatchSize is average requests per executed batch.
	AvgBatchSize float64
	// MaxBatchSeen is maximum observed executed batch size.
	MaxBatchSeen uint64

	// CallbackOps is number of requests with PreCommit callbacks executed by combiner.
	CallbackOps uint64
	// CoalescedSetDelete is number of Set/Delete requests collapsed into later Set/Delete of same ID.
	CoalescedSetDelete uint64

	// CoalesceWaits is number of coalescing sleeps performed by worker.
	CoalesceWaits uint64
	// CoalesceWaitTime is total time spent sleeping for coalescing.
	CoalesceWaitTime time.Duration

	// FallbackDisabled is number of write calls not queued because combiner is disabled.
	FallbackDisabled uint64
	// FallbackQueueFull is number of write calls not queued because queue is full.
	FallbackQueueFull uint64
	// FallbackCallbacks is number of write calls not queued because callbacks
	// are present and callback batching is disabled.
	FallbackCallbacks uint64
	// FallbackPatchUnique is a legacy counter of patch calls not queued due to
	// potential unique-field touch (kept for compatibility; expected to stay 0).
	FallbackPatchUnique uint64
	// FallbackClosed is number of write calls rejected by combiner because DB is closed.
	FallbackClosed uint64

	// UniqueRejected is number of queued requests rejected by unique checks before commit.
	UniqueRejected uint64
	// TxBeginErrors is number of write tx begin failures inside combiner.
	TxBeginErrors uint64
	// TxOpErrors is number of write tx operation failures before commit.
	TxOpErrors uint64
	// TxCommitErrors is number of write tx commit failures.
	TxCommitErrors uint64
	// CallbackErrors is number of callback failures returned by PreCommit funcs.
	CallbackErrors uint64
}

type CalibrationSnapshot struct {
	UpdatedAt   time.Time          `json:"updated_at"`
	Multipliers map[string]float64 `json:"multipliers"`
	Samples     map[string]uint64  `json:"samples"`
}

type CalibrationStats struct {
	// Enabled reports whether online calibration is enabled.
	Enabled bool
	// SampleEvery controls calibration sampling frequency (every Nth query).
	SampleEvery uint64

	// UpdatedAt is the timestamp of the last calibration state update.
	UpdatedAt time.Time
	// SamplesTotal is the total number of accumulated calibration samples.
	SamplesTotal uint64

	// Multipliers stores per-plan calibration multipliers.
	Multipliers map[string]float64
	// Samples stores per-plan calibration sample counters.
	Samples map[string]uint64
}

type DB[K ~string | ~uint64, V any] struct {
	// contains filtered or unexported fields
}

type Field struct {
	// Name is the logical name of the field to patch.
	// It can be a struct field name, a "db" tag value, or a "json" tag value.
	Name string
	// Value is the new value to assign to the field.
	// Patch* methods will attempt to convert Value to the field's concrete type,
	// including numeric widening and some int/float conversions.
	Value any
}

type IndexStats[K ~uint64 | ~string] struct {
	// IndexBuildTime is the duration of the last index rebuild.
	BuildTime time.Duration
	// IndexBuildRPS is an approximate throughput (records per second) of the last index rebuild.
	BuildRPS int
	// IndexLoadTime is the time spent loading a persisted index from disk on the last successful load.
	LoadTime time.Duration

	// LastKey is the largest key present in the database according to the
	// current universe bitmap. For string keys this is derived from the
	// internal string mapping.
	LastKey K
	// KeyCount is the total number of keys currently present in the database.
	KeyCount uint64

	// UniqueFieldKeys contains the number of unique index keys per indexed field name.
	UniqueFieldKeys map[string]uint64
	// IndexSize contains the total size of the index, in bytes.
	Size uint64
	// IndexFieldSize contains the size of the index for each indexed field.
	FieldSize map[string]uint64
	// IndexFieldKeyBytes contains total bytes occupied by index keys per field.
	FieldKeyBytes map[string]uint64
	// IndexFieldTotalCardinality contains sum of posting-list cardinalities per field.
	FieldTotalCardinality map[string]uint64

	// FieldCount is the number of indexed fields in the current snapshot.
	FieldCount int

	// EntryCount is the total number of non-empty index entries across fields.
	EntryCount uint64
	// KeyBytes is the total byte length of index keys across entries.
	KeyBytes uint64
	// BitmapCardinality is the sum of posting bitmap cardinalities across entries.
	BitmapCardinality uint64

	// ApproxStructBytes is approximate memory used by index entry structs.
	ApproxStructBytes uint64
	// ApproxHeapBytes is rough index heap estimate from bitmaps, keys and structs.
	ApproxHeapBytes uint64
}

type Options struct {

	// DisableIndexLoad prevents indexer from loading previously persisted index
	// data from the .rbi file on startup. If set, indexer will either rebuild
	// the index from the underlying bucket (unless DisableIndexRebuild is
	// also set) or operate with an empty index until rebuilt.
	DisableIndexLoad bool

	// DisableIndexStore prevents indexer from saving the in-memory index state
	// to the .rbi file on Close.
	DisableIndexStore bool

	// DisableIndexRebuild skips automatic index rebuilding when the index
	// cannot be loaded or is incomplete. When this is true and the index
	// cannot be reused, queries will fail until the caller explicitly
	// rebuilds the index using RebuildIndex.
	DisableIndexRebuild bool

	// BucketName overrides the default bucket name.
	// By default, bucket name is derived from the name of the value type V.
	BucketName string

	// AnalyzeInterval configures how often planner statistics should be
	// refreshed in the background.
	//
	// Default: 1 hour
	//
	// Negative value disables periodic refresh.
	AnalyzeInterval time.Duration

	// TraceSink receives optional per-query planner tracing events.
	// If nil, planner tracing is disabled.
	//
	// Synchronous or heavy sinks can significantly increase query latency.
	TraceSink func(TraceEvent)

	// TraceSampleEvery controls trace sampling:
	//   - 0: when sink is set, sample every query (equivalent to 1)
	//   - 1: sample every query
	//   - N: sample every Nth query
	TraceSampleEvery uint64

	// SnapshotPinWaitTimeout controls how long Query waits for a snapshot
	// with matching Bolt txID to appear after opening a read transaction.
	// Non-positive values use the default timeout.
	//
	// Default: 1s
	//
	// Query retry budget is bounded by 10x this value.
	// Too low can increase "snapshot is not available" errors under write bursts.
	// Too high can increase tail latency when snapshot publication is delayed.
	SnapshotPinWaitTimeout time.Duration

	// CalibrationEnabled enables online self-calibration of planner
	// cost coefficients using sampled query traces.
	//
	// Enable for workloads with evolving predicate selectivity/cost profile.
	// Keep disabled when strict latency determinism is preferred.
	CalibrationEnabled bool

	// CalibrationSampleEvery controls calibration sampling:
	//   - 0: use default sampling interval
	//   - 1: calibrate every query
	//   - N: calibrate every Nth query
	// The value is ignored when CalibrationEnabled is false.
	//
	// Default: 16
	//
	// Lower values adapt faster but add overhead and sensitivity to noise.
	// Higher values reduce overhead but adapt slower to workload shifts.
	CalibrationSampleEvery uint64

	// CalibrationPersistPath enables optional auto load/save of planner
	// calibration state from/to this JSON file.
	//
	// Default: empty (disabled).
	CalibrationPersistPath string

	// BucketFillPercent controls bbolt bucket fill factor for write operations.
	//
	// Default: 0.8
	//
	// Valid range: (0, 1]
	//
	// Lower values leave more free space on pages (usually larger file and
	// lower split cost on random updates). Higher values pack pages denser
	// (usually smaller file, potentially higher split/relocation cost).
	//
	// Values too low can cause excessive file growth and write amplification.
	// Values too high on churn-heavy workloads can sharply increase write latency.
	BucketFillPercent float64

	// SnapshotMaterializedPredCacheMaxEntries controls max number of cached
	// materialized predicate bitmaps for stable snapshots (without deltas).
	//
	// Default: 16
	//
	// Typical range: 16..256
	//
	// Negative value disables cache for stable snapshots.
	//
	// High values on diverse workloads can cause sharp memory growth.
	SnapshotMaterializedPredCacheMaxEntries int

	// SnapshotMaterializedPredCacheMaxEntriesWithDelta controls max cached
	// materialized predicate bitmaps for snapshots with active deltas.
	//
	// Default: 2
	//
	// Typical range: 2..64
	//
	// Negative value disables cache for delta snapshots.
	//
	// High values can increase GC pressure under write-heavy workloads.
	SnapshotMaterializedPredCacheMaxEntriesWithDelta int

	// SnapshotMaterializedPredCacheMaxBitmapCardinality skips caching very large
	// bitmaps to reduce retained heap and GC pressure.
	//
	// Default: 32K
	//
	// Negative value disables the guard.
	//
	// Negative (disabled) or very large values can significantly increase memory
	// usage for broad predicates.
	SnapshotMaterializedPredCacheMaxBitmapCardinality int

	// SnapshotRegistryMax limits amount of snapshots tracked for txID pinning/floor fallback.
	//
	// Default: 16
	//
	// Typical range: 32..512
	//
	// Higher values retain more snapshots (higher memory).
	// Too low values can increase snapshot misses for long readers.
	SnapshotRegistryMax uint

	// SnapshotDeltaCompactFieldKeys is a per-field threshold for accumulated
	// delta keys; above it field delta is compacted into base index.
	//
	// Default: 256
	//
	// Typical range: 128..2048
	//
	// Negative value disables key-count trigger.
	//
	// Too high can increase delta memory/read CPU.
	// Too low can increase compaction frequency and hurt write latency.
	SnapshotDeltaCompactFieldKeys int

	// SnapshotDeltaCompactFieldOps is a per-field threshold for accumulated
	// add/del cardinality across delta entries.
	//
	// Default: 4096
	//
	// Typical range: 2K..64K
	//
	// Negative value disables ops-count trigger.
	//
	// Too high delays compaction (delta growth, read overhead).
	// Too low can force frequent compaction and hurt write throughput.
	SnapshotDeltaCompactFieldOps int

	// SnapshotDeltaCompactMaxFieldsPerPublish limits how many fields can be
	// compacted from delta into base in one publish pass.
	//
	// Default: 3
	//
	// Negative value disables field compaction in publish path.
	//
	// High values can create severe write-latency spikes.
	SnapshotDeltaCompactMaxFieldsPerPublish int

	// SnapshotDeltaCompactUniverseOps is a threshold for universe add/drop
	// cardinality sum; above it universe delta is compacted into base.
	//
	// Default: 4096
	//
	// Typical values: 2K..64K
	//
	// Negative value disables universe compaction trigger.
	//
	// Too high values can increase overlay growth/read cost.
	// Too low values can increase write-path compaction work.
	SnapshotDeltaCompactUniverseOps int

	// SnapshotDeltaLayerMaxDepth limits per-field delta layer depth.
	// Once exceeded, layered delta is flattened into one layer.
	//
	// Default: 6
	//
	// Typical range: 4..64
	//
	// Negative value disables depth-based flattening.
	//
	// Very high/disabled values can increase read-path CPU and memory.
	// Very low values can increase flattening overhead on writes.
	SnapshotDeltaLayerMaxDepth int

	// SnapshotCompactorMaxIterationsPerRun limits background compaction work per wake-up.
	//
	// Default: 3
	//
	// Typical range: 1..8
	//
	// Zero disables compaction passes.
	//
	// High values increase contention with writers and can degrade throughput.
	SnapshotCompactorMaxIterationsPerRun uint

	// SnapshotCompactorRequestEveryNWrites controls best-effort compactor
	// wakeups under steady write load.
	//
	// Default: 4
	//
	// Typical range: 4..64
	//
	// Lower values improve delta control but increase write contention.
	// Higher values reduce contention but can increase delta memory/read cost.
	//
	// Zero disables periodic write-triggered compactor requests.
	//
	// Value 1 can cause sustained compactor/writer contention and write
	// throughput degradation on heavy write workloads.
	SnapshotCompactorRequestEveryNWrites uint

	// SnapshotCompactorIdleInterval configures one-shot idle debounce for
	// force-drain compaction when snapshot activity stops.
	// After this pause without new snapshot publication, compactor performs a
	// bounded force pass to collapse remaining deltas and aggressively prune
	// snapshot registry for best read-path locality.
	//
	// Default: 2s
	//
	// Typical range: 500ms..10s
	//
	// Non-positive value disables idle force-drain mode.
	//
	// Lower values converge faster after write bursts but can increase
	// compactor/writer contention on bursty workloads.
	// Higher values reduce background churn but keep layered state longer.
	SnapshotCompactorIdleInterval time.Duration

	// BatchWindow enables lightweight write micro-batching window for
	// single-record Set/Patch/Delete operations.
	//
	// Default: 200us
	//
	// Typical range: 10us..500us
	//
	// Non-positive value disables write combining.
	//
	// Higher values can reduce write-path overhead under contention but may
	// increase single-write latency at low load.
	BatchWindow time.Duration

	// BatchMax limits max operations merged into one combined write tx.
	//
	// Default: 16
	//
	// Typical range: 4..64
	//
	// Values <=1 disable effective batching.
	//
	// Very high values can create commit-size spikes and tail-latency variance.
	BatchMax int

	// BatchMaxQueue limits pending combined write requests.
	//
	// Default: 512
	//
	// Typical range: 128..8192
	//
	// Non-positive value disables queue cap.
	//
	// Larger values can increase memory usage under sustained overload.
	BatchMaxQueue int

	// BatchAllowCallbacks allows combiner batching for requests with one or more
	// PreCommit callbacks.
	//
	// Default: false
	//
	// When false, any Set/Patch/Delete call with callbacks bypasses combiner queue
	// and is executed via direct single-write path.
	//
	// When true, callback-bearing requests may be combined with other writes and
	// callbacks run inside the same shared write transaction.
	//
	// Limitations:
	// - A callback error aborts the current combined-transaction attempt. The
	//   failed request is isolated and remaining requests are retried without it.
	// - On such abort, the whole current write transaction is rolled back.
	//   Stored records and in-memory index state remain consistent; no partial
	//   data/index changes from the failed attempt are published.
	// - Non-callback transaction errors (put/delete/commit) still fail all
	//   requests from the current combined batch.
	// - Callback execution order follows operation order inside combined batch.
	// - Because surviving requests can be retried after isolating a failed one,
	//   their callbacks may run more than once. Callback logic with side effects
	//   outside this DB write transaction should be idempotent.
	BatchAllowCallbacks bool

	// NumericRangeBucketSize controls amount of sorted numeric keys grouped into one
	// pre-aggregated bucket for range predicate acceleration.
	//
	// Default: 512
	//
	// Non-positive value disables numeric bucket acceleration.
	NumericRangeBucketSize int

	// NumericRangeBucketMinFieldKeys is the minimum amount of unique keys in a
	// numeric field required to build range buckets.
	//
	// Default: 8192
	//
	// Non-positive value disables numeric bucket acceleration.
	NumericRangeBucketMinFieldKeys int

	// NumericRangeBucketMinSpanKeys is the minimum range span (in keys) required to
	// route GT/GTE/LT/LTE through bucket acceleration path.
	//
	// Default: 2048
	//
	// Non-positive value disables numeric bucket acceleration.
	NumericRangeBucketMinSpanKeys int
}

type PlanName string

type PlannerFieldStats struct {
	// DistinctKeys is number of distinct keys in field index.
	DistinctKeys uint64
	// NonEmptyKeys is number of keys with non-empty posting bitmap.
	NonEmptyKeys uint64
	// TotalBucketCard is total cardinality summed across all field buckets.
	TotalBucketCard uint64
	// AvgBucketCard is average bucket cardinality.
	AvgBucketCard float64
	// MaxBucketCard is maximum bucket cardinality.
	MaxBucketCard uint64
	// P50BucketCard is median bucket cardinality.
	P50BucketCard uint64
	// P95BucketCard is 95th percentile bucket cardinality.
	P95BucketCard uint64
}

type PlannerStats struct {
	// Version is the current planner statistics version.
	Version uint64
	// GeneratedAt is the timestamp when planner stats were generated.
	GeneratedAt time.Time
	// UniverseCardinality is the universe cardinality used by planner stats.
	UniverseCardinality uint64
	// FieldCount is the number of fields represented in planner stats.
	FieldCount int
	// Fields contains per-field planner cardinality distribution metrics.
	// The map is deep-copied and safe for caller mutation.
	Fields map[string]PlannerFieldStats

	// AnalyzeInterval is the configured periodic planner analyze interval.
	AnalyzeInterval time.Duration
	// TraceSampleEvery controls trace sampling frequency (every Nth query).
	TraceSampleEvery uint64
}

type PreCommitFunc[K ~string | ~uint64, V any] = func(tx *bbolt.Tx, key K, oldValue, newValue *V) error

type RuntimeStats struct {
	// Goroutines is the current number of goroutines.
	Goroutines int

	// HeapAlloc is bytes of allocated heap objects.
	HeapAlloc uint64
	// HeapInuse is bytes in in-use heap spans.
	HeapInuse uint64
	// HeapIdle is bytes in idle heap spans.
	HeapIdle uint64
	// HeapReleased is bytes returned from heap to OS.
	HeapReleased uint64
	// HeapObjects is the number of allocated heap objects.
	HeapObjects uint64

	// StackInuse is bytes in stack spans.
	StackInuse uint64
	// MSpanInuse is bytes in mspan allocator metadata.
	MSpanInuse uint64
	// MCacheInuse is bytes in mcache allocator metadata.
	MCacheInuse uint64

	// NextGC is the target heap size for the next GC cycle.
	NextGC uint64
	// LastGC is the timestamp of the last completed GC cycle.
	LastGC time.Time
	// NumGC is the total number of completed GC cycles.
	NumGC uint32
	// GCCPUFraction is the fraction of available CPU used by GC since start.
	GCCPUFraction float64
}

type SnapshotStats struct {
	// TxID is the transaction ID of the published snapshot.
	TxID uint64

	// HasDelta reports whether snapshot contains any delta state.
	HasDelta bool
	// UniverseBaseCard is cardinality of the base universe bitmap.
	UniverseBaseCard uint64
	// IndexLayerDepth is depth of index delta layer chain.
	IndexLayerDepth int
	// LenLayerDepth is depth of length-index delta layer chain.
	LenLayerDepth int

	// IndexDeltaFields is number of fields with effective index delta.
	IndexDeltaFields int
	// LenDeltaFields is number of fields with effective length delta.
	LenDeltaFields int
	// IndexDeltaKeys is total effective keys in index delta layers.
	IndexDeltaKeys int
	// LenDeltaKeys is total effective keys in length delta layers.
	LenDeltaKeys int
	// IndexDeltaOps is total effective operations in index delta layers.
	IndexDeltaOps uint64
	// LenDeltaOps is total effective operations in length delta layers.
	LenDeltaOps uint64

	// UniverseAddCard is cardinality of pending universe additions.
	UniverseAddCard uint64
	// UniverseRemCard is cardinality of pending universe removals.
	UniverseRemCard uint64

	// RegistrySize is number of snapshot entries tracked in registry map.
	RegistrySize int
	// RegistryOrderLen is length of registry order buffer.
	RegistryOrderLen int
	// RegistryHead is current head offset inside registry order buffer.
	RegistryHead int
	// PinnedRefs is number of registry snapshots with active pins.
	PinnedRefs int
	// PendingRefs is number of registry snapshots marked pending.
	PendingRefs int

	// CompactorQueueLen is current compactor request queue length.
	CompactorQueueLen int
	// CompactorRequested is total number of compaction requests.
	CompactorRequested uint64
	// CompactorRuns is total number of compactor loop runs.
	CompactorRuns uint64
	// CompactorAttempts is total latest-snapshot compaction attempts.
	CompactorAttempts uint64
	// CompactorSucceeded is total successful compactions applied.
	CompactorSucceeded uint64
	// CompactorLockMiss is total attempts skipped due to DB lock contention.
	CompactorLockMiss uint64
	// CompactorNoChange is total attempts that produced no effective changes.
	CompactorNoChange uint64
}

type Stats[K ~uint64 | ~string] struct {
	// Index contains additional index shape diagnostics useful for memory analysis.
	Index IndexStats[K]
	// Runtime contains process-level memory counters sampled during Stats().
	Runtime RuntimeStats
	// Snapshot contains copy-on-write snapshot/compactor diagnostics.
	Snapshot SnapshotStats
	// Planner contains current planner statistics snapshot and settings.
	Planner PlannerStats
	// Calibration contains current online planner calibration state.
	Calibration CalibrationStats
	// Batch contains write-combiner queue/batch/fallback diagnostics.
	Batch BatchStats
}

type TraceEvent struct {
	Timestamp time.Time
	Duration  time.Duration

	Plan string

	HasOrder   bool
	OrderField string
	OrderDesc  bool
	Offset     uint64
	Limit      uint64

	LeafCount int
	HasNeg    bool
	HasPrefix bool

	EstimatedRows uint64
	EstimatedCost float64
	FallbackCost  float64

	RowsExamined uint64
	RowsReturned uint64

	// ORBranches contains per-branch runtime metrics for OR plans.
	ORBranches []TraceORBranch
	// ORRoute contains route/cost diagnostics for ordered OR merge path.
	ORRoute TraceORRoute

	// OrderIndexScanWidth is the number of non-empty order-index buckets
	// traversed while producing query output.
	OrderIndexScanWidth uint64

	// DedupeCount is the number of duplicate candidates dropped globally.
	DedupeCount uint64

	// EarlyStopReason explains why execution stopped early.
	// Examples: "limit_reached", "input_exhausted", "candidates_exhausted".
	EarlyStopReason string

	Error string
}

type TraceORBranch struct {
	Index int

	RowsExamined uint64
	RowsEmitted  uint64

	Skipped    bool
	SkipReason string
}

type TraceORRoute struct {
	Route  string
	Reason string

	KWayCost     float64
	FallbackCost float64
	Overlap      float64
	AvgChecks    float64

	HasPrefixNonOrder   bool
	HasSelectiveLead    bool
	FallbackCollectFast bool

	RuntimeGuardEnabled bool
	RuntimeGuardReason  string

	RuntimeFallbackTriggered    bool
	RuntimeFallbackReason       string
	RuntimeExaminedPerUnique    float64
	RuntimeProjectedExamined    float64
	RuntimeProjectedExaminedMax float64
}

type ValueIndexer interface {
	IndexingValue() string
}