caching

type BackendDB interface {
	Get(key []byte) ([]byte, error)
	GetUnsafe(key []byte) ([]byte, error)
	GetAppend(key, dst []byte) ([]byte, error)
	Has(key []byte) (bool, error)
	Iterator(start, end []byte) (iterator.UnsafeIterator, error)
	ReverseIterator(start, end []byte) (iterator.UnsafeIterator, error)
	NewBatch() batch.Interface
	Close() error
	Print() error
	Stats() map[string]string
}

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

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

type DictStore interface {
	GetCurrent(ctx context.Context) (uint64, error)
	GetDictBytes(ctx context.Context, dictID uint64) ([]byte, error)
}

type Options struct {
	FlushThreshold int64

	// MemtableMode selects the in-memory write buffer implementation.
	// Supported: "skiplist", "hash_sorted", "btree", "adaptive".
	// Use "adaptive" or "adaptive:<mode>" to switch per-rotation based on workload.
	MemtableMode string

	// MemtableShards controls the number of mutable memtable shards. Values <= 0
	// use a default derived from GOMAXPROCS. The count is rounded down to a power
	// of two.
	MemtableShards int

	// Legacy backpressure knob: queue length limit.
	// 0 uses the default (4). <0 disables writer backpressure entirely.
	MaxQueuedMemtables int

	// Adaptive backpressure knobs (seconds/bytes). If any of these are non-zero,
	// the caching layer uses backlog-bytes thresholds instead of queue length.
	SlowdownBacklogSeconds float64
	StopBacklogSeconds     float64
	MaxBacklogBytes        int64

	// Writer flush assist limits when backpressure triggers.
	WriterFlushMaxMemtables int
	WriterFlushMaxDuration  time.Duration

	// FlushBuildConcurrency controls how many goroutines may be used to build a
	// combined flush batch from multiple immutable memtables. Values <= 1 disable
	// parallelism.
	FlushBuildConcurrency int

	// DisableWAL disables the Write-Ahead Log entirely (legacy alias for disabling
	// both the journal/redo log and value-log pointers).
	DisableWAL bool
	// DisableJournal disables the redo/journal records while still allowing
	// value-log pointers/value storage. A crash may lose writes since the last
	// checkpoint because there is no redo log to replay.
	DisableJournal bool
	// DisableValueLog forces the cached WAL to remain in legacy mode (no value-log pointers).
	DisableValueLog bool
	// SplitValueLog stores WAL records in wal/ while large values go to vlog/
	// segments, and WAL entries reference them via pointers.
	SplitValueLog bool
	// JournalLanes controls the number of active commit/value log lanes (0=default).
	// Max supported lanes is 255; value-log segment sequence per lane is capped at 8,388,607.
	JournalLanes int
	// WALMaxSegmentBytes caps the size of a single WAL segment payload.
	// 0 uses the default limit.
	WALMaxSegmentBytes int64
	// JournalCompression enables best-effort zstd compression for journal/commitlog
	// segments (metadata only). The writer only keeps compressed bytes when they
	// are smaller than the raw payload, so compression never causes size
	// amplification.
	JournalCompression bool
	// RelaxedSync disables fsync on Sync operations.
	RelaxedSync bool
	// MemtableValueLogPointers avoids storing large values in the memtable and
	// serves them by pointer from the value log (WAL/vlog). Requires WAL/value-log.
	MemtableValueLogPointers bool
	// ValueLogPointerThreshold controls when WAL/vlog pointers are used.
	// Values <= 0 use the default inline threshold (256 bytes).
	ValueLogPointerThreshold int
	// DisableReadChecksum skips CRC verification on value-log reads.
	DisableReadChecksum bool
	// AllowUnsafe acknowledges unsafe durability options.
	// When false, Open will reject DisableWAL or RelaxedSync.
	AllowUnsafe bool
	// MaxValueLogRetainedBytes emits a warning when retained value-log bytes exceed
	// this threshold (0 disables warnings).
	MaxValueLogRetainedBytes int64
	// MaxValueLogRetainedBytesHard disables value-log pointers for new large
	// values once retained bytes exceed this threshold (0 disables the cap).
	MaxValueLogRetainedBytesHard int64

	// ValueLogDictTrain configures background dictionary training for value-log frame compression.
	// TrainBytes <= 0 disables training.
	ValueLogDictTrain compression.TrainConfig
	// ValueLogDictAdaptiveRatio enables adaptive pause of dict compression when payload ratios degrade.
	// 0 disables.
	ValueLogDictAdaptiveRatio float64
	// ValueLogDictMetricsWindowBytes controls the metrics window size (0=default).
	ValueLogDictMetricsWindowBytes int
	// ValueLogDictMetricsMinRecords is a minimum record count before pausing (0=default).
	ValueLogDictMetricsMinRecords int
	// ValueLogDictMetricsPauseBytes controls pause duration in bytes (0=default).
	ValueLogDictMetricsPauseBytes int
	// ValueLogDictMinPayloadSavingsRatio rejects newly trained dictionaries whose payload ratio
	// does not improve by at least this fraction (0 uses default).
	ValueLogDictMinPayloadSavingsRatio float64

	// ValueLogCompressionAutotune configures the wall-time value-log compression autotuner.
	// Cached mode only (SplitValueLog must be enabled).
	ValueLogCompressionAutotune valuelog.AutotuneOptions

	// NotifyError is an optional hook for background maintenance failures.
	NotifyError func(error)
}

type VlogAutotuneBenchMode string

type VlogAutotuneBenchRequest struct {
	Mode     VlogAutotuneBenchMode
	FixedK   int
	Segments []VlogAutotuneBenchSegment
}

type VlogAutotuneBenchResult struct {
	Mode         VlogAutotuneBenchMode
	Segments     []VlogAutotuneBenchSegmentResult
	RawBytes     uint64
	StoredBytes  uint64
	WallTimeNs   int64
	ThroughputMB float64
	TrainerStats compression.TrainerStats
}

type VlogAutotuneBenchSegment struct {
	Name               string
	Workload           valuelog.AutotuneWorkload
	ValueSize          int
	Records            int
	EncodeNsPerRawByte float64
	IoNsPerStoredByte  float64
}

type VlogAutotuneBenchSegmentResult struct {
	Name               string
	RawBytes           uint64
	StoredBytes        uint64
	WallTimeNs         int64
	ThroughputRawMBps  float64
	AttemptedFrac      float64
	KeptFrac           float64
	ObservedRatio      float64
	FramesTotal        uint64
	FramesAttempted    uint64
	FramesKept         uint64
	EncodeNsTotal      int64
	IoNsTotal          int64
	State              string
	DictID             uint64
	DictHash           uint64
	HistoryBytes       int
	K                  int
	PublishOrderingOK  bool
	TrainerProfileOK   bool
	TrainerProfileK    int
	TrainerProfileHash uint64
}