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 MaintenancePhase uint8

type Options struct {
	FlushThreshold int64

	// MemtableMode selects the in-memory write buffer implementation.
	// Supported: "skiplist", "hash_sorted", "btree", "append_only", "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
	// DomainIngressWorkers enables experimental domain-local write ingress queues.
	// Values <= 0 keep the legacy direct caller write path.
	DomainIngressWorkers int
	// DomainIngressQueueSize configures the per-worker ingress queue length.
	// Values <= 0 use a default.
	DomainIngressQueueSize 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
	// FlushBuildMinEntries gates the parallel build path by total entries.
	// Values <= 0 use a default of 16k.
	FlushBuildMinEntries int
	// FlushBuildMinUnits gates the parallel build path by number of queued units.
	// Values <= 0 use a default of 2.
	FlushBuildMinUnits int
	// FlushBuildChunkCap controls the maximum entries per build chunk.
	// Values < 0 use the fixed default of 8192, 0 enables adaptive chunk sizing,
	// and values > 0 set a fixed cap.
	FlushBuildChunkCap int
	// FlushBuildChunkTargetBytes controls adaptive chunk sizing (bytes per chunk).
	// Values <= 0 use a default of 2MiB.
	FlushBuildChunkTargetBytes int
	// FlushBuildChunkMinBytes clamps adaptive chunk sizes (minimum bytes).
	// Values <= 0 use a default of 1MiB.
	FlushBuildChunkMinBytes int
	// FlushBuildChunkMaxBytes clamps adaptive chunk sizes (maximum bytes).
	// Values <= 0 use a default of 4MiB.
	FlushBuildChunkMaxBytes int
	// FlushBuildPrefetchUnits controls how many memtables to start building ahead
	// of the consumer. Values <= 0 use FlushBuildConcurrency.
	FlushBuildPrefetchUnits int

	// FlushApplyConcurrency enables backend M2 opt-in COW apply workers. The
	// backend owns execution; cached mode carries this knob for config/reporting
	// symmetry with FlushBuildConcurrency. Values <=1 keep the M2 path off.
	FlushApplyConcurrency int
	// FlushApplyMinEntries gates backend opt-in parallel apply by planned ops.
	FlushApplyMinEntries int
	// FlushApplyMinSpans gates backend opt-in parallel apply by planned leaf spans.
	FlushApplyMinSpans int
	// FlushApplyMinBytes gates backend opt-in parallel apply by planned bytes.
	FlushApplyMinBytes int
	// FlushApplySpanNative enables backend M10 opt-in span-native apply. The
	// backend owns execution; cached mode carries this knob for config/reporting
	// symmetry and keeps the path default-off.
	FlushApplySpanNative bool

	// FlushBackendMaxEntries caps how many operations are buffered into a single
	// backend batch before committing it and continuing with a fresh batch.
	//
	// This increases backend commit cadence during very large flushes, which can
	// reduce index.db high-watermark growth under small KeepRecent windows by
	// making retired pages eligible for reuse sooner.
	//
	// 0 uses the internal default. Negative disables chunking (single backend
	// commit per flush).
	FlushBackendMaxEntries int
	// FlushBackendMaxBatches caps how many intermediate backend commits a single
	// flush may emit. This bounds zipper/apply overhead when FlushBackendMaxEntries
	// is very small relative to the flush size.
	//
	// 0 uses the internal default. Negative disables the cap.
	FlushBackendMaxBatches int

	// FlushSpanRunTargetPlanning enables diagnostic read-only target-leaf planning
	// for canonical flush runs. It is default-off because the extra root traversal
	// is not part of the M9 default write path; M10+ can use the same backend
	// planner when span-native execution consumes target spans.
	FlushSpanRunTargetPlanning bool

	// FlushBacklogCoalescing enables the M11 bounded adaptive cached-flush
	// coalescing controller. It is default-off; when enabled the coordinator may
	// include additional already-sealed eligible memtables before canonical run
	// planning under observed cumulative single-op-span pressure and explicit
	// budgets.
	FlushBacklogCoalescing bool
	// FlushBacklogCoalescingMaxMemtables bounds memtables per coalesced point run
	// after preserving the pre-existing base collector minimum (0=default, capped
	// internally).
	FlushBacklogCoalescingMaxMemtables int
	// FlushBacklogCoalescingMaxBytes is a soft queued-byte budget per coalesced
	// point run. It is checked before adding the next memtable after at least one
	// unit, so a selected run can exceed this value by one whole memtable and the
	// budget never tightens the pre-existing base collector (0=default).
	FlushBacklogCoalescingMaxBytes int64
	// FlushBacklogCoalescingMaxOps is a soft queued point-op budget per coalesced
	// point run. It is checked before adding the next memtable after at least one
	// unit, so a selected run can exceed this value by one whole memtable and the
	// budget never tightens the pre-existing base collector (0=default).
	FlushBacklogCoalescingMaxOps int
	// FlushBacklogCoalescingMinAge requires the oldest queued memtable to be at
	// least this old before adaptive coalescing admits extra work (0=no age floor).
	FlushBacklogCoalescingMinAge time.Duration
	// FlushBacklogCoalescingSingleOpSpanRatio is the observed single-op span ratio
	// that triggers coalescing (0=default). Pressure gates use cumulative apply/span
	// counters; after workload-shape changes, eligibility may decay only as
	// cumulative ratios change, while each admitted run remains bounded by the
	// explicit budgets above.
	FlushBacklogCoalescingSingleOpSpanRatio float64
	// FlushBacklogCoalescingMaxOpsPerSpan is the observed ops/span ceiling that
	// still counts as single-op pressure (0=default).
	FlushBacklogCoalescingMaxOpsPerSpan float64
	// FlushBacklogCoalescingMinOldLeafBytesPerOp optionally requires observed
	// old-leaf decode bytes/op before coalescing (0=disabled).
	FlushBacklogCoalescingMinOldLeafBytesPerOp float64

	// DisableWAL disables the redo/journal log while keeping the value log enabled.
	DisableWAL bool
	// JournalLanes controls the number of active commit/value log lanes
	// (0=GOMAXPROCS-aware 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
	// ValueLogPointerThreshold controls when WAL/vlog pointers are used.
	// Values <= 0 use a default threshold. In relaxed durability modes, the
	// default is smaller to avoid catastrophic update-heavy cliffs at large key
	// counts by pushing moderate values into the value log.
	ValueLogPointerThreshold int
	// IndexOuterLeavesInValueLog stores B+Tree leaf pages (the pages containing
	// key/value entries) in the persistent value log instead of index.db.
	IndexOuterLeavesInValueLog bool
	// ValueLogDomainInlineThresholds configures optional per-domain overrides
	// for inline-vs-pointer placement. Longest-prefix match wins.
	ValueLogDomainInlineThresholds []backenddb.ValueLogDomainThreshold
	// ValueLogRawWritevMinAvgBytes controls raw grouped-frame writev usage for
	// the value log.
	//
	// 0 uses adaptive mode (no average-bytes floor); values >0 require average
	// payload bytes/record to meet this floor before raw writev is considered.
	ValueLogRawWritevMinAvgBytes int
	// ValueLogRawWritevMinBatchRecords controls the minimum grouped records before
	// raw writev is considered for value-log appends.
	//
	// Values <=0 use a default of 8.
	ValueLogRawWritevMinBatchRecords int
	// ValueLogCompression selects value-log compression behavior:
	// 0=default(unset; normalized to auto by TreeDB Open), 1=off, 2=block,
	// 3=dict, 4=auto.
	ValueLogCompression uint8
	// ValueLogBlockCodec selects block codec when block compression is enabled:
	// 0=snappy, 1=lz4.
	ValueLogBlockCodec uint8
	// ValueLogBlockTargetCompressedBytes controls block-mode grouped frame K
	// adaptation target (0=default).
	ValueLogBlockTargetCompressedBytes int
	// ValueLogIncompressibleHoldBytes configures auto-mode incompressible hold
	// window bytes (0=default).
	ValueLogIncompressibleHoldBytes int
	// ValueLogIncompressibleProbeBytes configures auto-mode hold probe interval
	// bytes (0=default).
	ValueLogIncompressibleProbeBytes int
	// ValueLogAutoPolicy controls auto-mode dict-vs-block bias:
	// 0=balanced, 1=throughput, 2=size.
	ValueLogAutoPolicy uint8
	// ValueLogMaxSegmentBytes caps the size of a single value-log segment file.
	// 0 disables the cap.
	//
	// This is an internal safety knob used by experimental index encodings
	// (e.g. packed on-disk ValuePtr) that require value-log offsets stay within a
	// smaller representable range.
	ValueLogMaxSegmentBytes int64
	// ValueLogGenerationPolicy selects generational mode:
	// 0=default(unset; normalized to hot_warm_cold by Open),
	// 1=off, 2=hot_warm_cold.
	ValueLogGenerationPolicy uint8
	// ValueLogGenerationLeafSegmentTargetBytes configures leaf_vlog segment target size.
	ValueLogGenerationLeafSegmentTargetBytes int64
	// ValueLogGenerationHotSegmentTargetBytes configures hot segment target size.
	ValueLogGenerationHotSegmentTargetBytes int64
	// ValueLogGenerationWarmSegmentTargetBytes configures warm segment target size.
	ValueLogGenerationWarmSegmentTargetBytes int64
	// ValueLogGenerationColdSegmentTargetBytes configures cold segment target size.
	ValueLogGenerationColdSegmentTargetBytes int64
	// ValueLogRewriteBudgetBytesPerSec configures incremental rewrite byte budget.
	ValueLogRewriteBudgetBytesPerSec int64
	// ValueLogRewriteBudgetRecordsPerSec configures incremental rewrite record budget.
	ValueLogRewriteBudgetRecordsPerSec int
	// ValueLogRewriteTriggerStaleRatioPPM triggers rewrite by stale/live ratio.
	ValueLogRewriteTriggerStaleRatioPPM uint32
	// ValueLogRewriteTriggerTotalBytes triggers rewrite by retained bytes.
	ValueLogRewriteTriggerTotalBytes int64
	// ValueLogRewriteTriggerChurnPerSec triggers rewrite by churn rate.
	ValueLogRewriteTriggerChurnPerSec int64
	// ValueLogRewriteMinSegmentAge gates online rewrite to source segments that
	// are at least this old.
	//
	// 0 uses the implementation default.
	ValueLogRewriteMinSegmentAge time.Duration
	// ForceValueLogPointers stores all values out-of-line in the value log.
	ForceValueLogPointers bool
	// DisableReadChecksum skips CRC verification on value-log reads.
	DisableReadChecksum bool
	// ValueLogCurrentWritableMmap enables mmap-backed reads for current writable
	// value-log segments.
	ValueLogCurrentWritableMmap bool
	// AllowUnsafe acknowledges unsafe durability options.
	// When false, Open will reject DisableWAL or RelaxedSync.
	AllowUnsafe bool
	// MaxValueLogRetainedBytes emits a warning once retained value-log bytes
	// reach or exceed this threshold and also acts as the soft retained-byte
	// trigger for background prune scheduling (0 disables both).
	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
	// ValueLogDictMaxK clamps the maximum group size (K) used for dict-compressed
	// value-log frames. Values <= 0 use the default (32).
	ValueLogDictMaxK int
	// ValueLogDictClassMode controls dictionary-state partitioning:
	// 0=single shared dict stream, 1=split outer-leaf vs single-value streams.
	ValueLogDictClassMode uint8
	// ValueLogDictFrameEncodeLevel controls the zstd encoder level used for
	// dict-compressed value-log frames. Values <= 0 use SpeedFastest.
	ValueLogDictFrameEncodeLevel zstd.EncoderLevel
	// ValueLogDictFrameEnableEntropy enables entropy coding for dict-compressed
	// frames (higher ratio, lower throughput).
	ValueLogDictFrameEnableEntropy bool
	// 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
	// ValueLogDictIncompressibleHoldBytes enables classifier-driven hold mode for
	// high-entropy streams. While hold mode is active, dict compression attempts
	// and trainer collection are bypassed until hold bytes are consumed.
	//
	// 0 uses profile/default hold configuration; <0 explicitly disables hold
	// mode and opts out of profile defaults.
	ValueLogDictIncompressibleHoldBytes int
	// ValueLogDictProbeIntervalBytes controls periodic probe attempts while
	// incompressible hold mode is active.
	//
	// Values <=0 use a default derived from hold bytes.
	ValueLogDictProbeIntervalBytes int
	// ValueLogDictMinPayloadSavingsRatio rejects newly trained dictionaries whose
	// payload ratio does not improve by at least this fraction (0 uses a
	// throughput-oriented default: 0.02 normally, 0.05 with force pointers or
	// WAL disabled).
	ValueLogDictMinPayloadSavingsRatio float64

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

	// ValueLogTemplateMode controls template-based compression for value-log values.
	ValueLogTemplateMode template.Mode
	// ValueLogTemplateConfig controls template creation and encoding behavior.
	ValueLogTemplateConfig template.Config
	// ValueLogTemplateReadStrict controls strict template decode behavior.
	ValueLogTemplateReadStrict bool

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

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

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
}