db

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

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

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

type DBState struct {
	CommitSeq                  uint64
	RootPageID                 uint64
	SystemRootPageID           uint64
	ValueLogSet                *valuelog.Set
	LeafGenerations            *leafGenerationView
	LeafGenerationStateVersion uint64
}

type DurabilityMode uint8

type FormatConfig struct {
	Version int `json:"version"`

	IndexOuterLeavesInValueLog bool `json:"index_outer_leaves_in_vlog"`

	LeafPrefixCompression     bool `json:"leaf_prefix_compression"`
	IndexColumnarLeaves       bool `json:"index_columnar_leaves"`
	IndexPackedValuePtr       bool `json:"index_packed_valueptr"`
	IndexInternalBaseDelta    bool `json:"index_internal_base_delta"`
	IndexAdaptiveLeafEncoding bool `json:"index_adaptive_leaf_encoding"`

	ValueLogCompression string `json:"vlog_compression"`
	ValueLogBlockCodec  string `json:"vlog_block_codec"`
	ValueLogAutoPolicy  string `json:"vlog_auto_policy"`
}

type IntegrityMode uint8

type Iterator interface {
	Valid() bool
	Next()
	Key() []byte
	Value() []byte
	KeyCopy(dst []byte) []byte
	ValueCopy(dst []byte) []byte
	Close() error
	Error() error
	// Reset resets the iterator for reuse.
	Reset(start, end []byte)
}

type IteratorMode = tree.IteratorMode

type IteratorOptions = tree.IteratorOptions

type LeafGenerationGCOptions struct {
	DryRun bool
}

type LeafGenerationGCStats struct {
	GenerationsTotal    int
	GenerationsWritable int
	GenerationsLive     int
	GenerationsRetiring int
	GenerationsEligible int
	GenerationsDeleted  int
	FilesDeleted        int
	BytesEligible       int64
	BytesDeleted        int64
}

type LeafGenerationPackFromPlanOptions struct {
	Sync                       bool
	Force                      bool
	MinPublishedAgeCommits     uint64
	MinCandidateGenerations    int
	MinExpectedReclaimBytes    int64
	MinExpectedReclaimRatioPPM int
	MinReclaimPerByteCopiedPPM int
	MaxGenerations             int
	MaxBytesToCopy             int64
	ReserveRIDs                func(count int) (start uint64, err error)
}

type LeafGenerationPackOptions struct {
	GenerationIDs              []uint64
	Sync                       bool
	MinPublishedAgeCommits     uint64
	MinExpectedReclaimBytes    int64
	MinExpectedReclaimRatioPPM int
	MinReclaimPerByteCopiedPPM int
	ReserveRIDs                func(count int) (start uint64, err error)
	Force                      bool
}

type LeafGenerationPackRunOnceStats struct {
	Plan       LeafGenerationPlan
	Selection  LeafGenerationPackSelection
	Pack       LeafGenerationPackStats
	Ran        bool
	SkipReason string
}

type LeafGenerationPackSelectOptions struct {
	Force                      bool
	MinExpectedReclaimBytes    int64
	MinExpectedReclaimRatioPPM int
	MaxGenerations             int
	MaxBytesToCopy             int64
	MinReclaimPerByteCopiedPPM int
}

type LeafGenerationPackSelection struct {
	GenerationIDs                   []uint64
	Generations                     []LeafGenerationPlanGeneration
	BytesTotal                      int64
	BytesLive                       int64
	BytesDead                       int64
	BytesToCopy                     int64
	LivePages                       int
	ExpectedReclaimBytes            int64
	ExpectedReclaimRatioPPM         int
	ExpectedReclaimPerByteCopiedPPM int
}

type LeafGenerationPackStats struct {
	GenerationsRequested            int
	GenerationsMatched              int
	SourceGenerationIDs             []uint64
	SourceFilesRequested            int
	SourceFileIDs                   []uint32
	SourceBytesTotal                int64
	SourceBytesLive                 int64
	SourceBytesDead                 int64
	SourceBytesToCopy               int64
	ExpectedReclaimBytes            int64
	ExpectedReclaimRatioPPM         int
	ExpectedReclaimPerByteCopiedPPM int
	LeafPagesCopied                 int
	BytesCopied                     int64
	InternalPagesVisited            int
	SubtreesPruned                  int
	CreatedFileIDs                  []uint32
	WallTimeNanos                   int64
}

type LeafGenerationPlan struct {
	CurrentCommitSeq       uint64
	CurrentGenerationID    uint64
	Generations            []LeafGenerationPlanGeneration
	Candidates             []LeafGenerationPlanGeneration
	CandidateGenerationIDs []uint64

	CandidateBytesTotal  int64
	CandidateBytesLive   int64
	CandidateBytesDead   int64
	CandidateBytesToCopy int64
	CandidateLivePages   int

	ExpectedReclaimBytes            int64
	ExpectedReclaimRatioPPM         int
	ExpectedReclaimPerByteCopiedPPM int
	Admission                       string
}

type LeafGenerationPlanGeneration struct {
	GenerationID uint64
	State        string
	FileIDs      []uint32
	FileCount    int

	BytesTotal  int64
	BytesLive   int64
	BytesDead   int64
	BytesToCopy int64
	LivePages   int

	AgeCommits                uint64
	PinnedCount               uint64
	DeadRatioPPM              int
	LiveRatioPPM              int
	WholeGenerationGCEligible bool
	Eligible                  bool
	SkipReason                string
}

type LeafGenerationPlanOptions struct {
	MinPublishedAgeCommits     uint64
	MinCandidateGenerations    int
	MinExpectedReclaimBytes    int64
	MinExpectedReclaimRatioPPM int
	MinReclaimPerByteCopiedPPM int
	Force                      bool
}

type LeafPageLog interface {
	AppendLeafPage(leafPage []byte) (page.LeafLogPtr, error)
	Flush() error
	Sync() error
}

type Options struct {
	Dir string
	// IgnoreFormatConfig disables best-effort persisted format.json loading in
	// TreeDB open paths that auto-apply index-format knobs from disk (e.g.
	// treedb.Open, treedb.OpenBackend) and in offline maintenance helpers
	// (VacuumIndexOffline, ValueLogRewriteOffline, treemap vacuum/rewrite/vlog-gc).
	IgnoreFormatConfig bool
	// ReadOnly opens the database without acquiring an exclusive lock and without
	// modifying on-disk state (no recovery truncation, no WAL replay, no background
	// maintenance). Only read operations are supported.
	ReadOnly  bool
	ChunkSize int64 // Default 256KiB
	// DictDBChunkSize controls the mmap chunk size used for the `dictdb/` side
	// store when TreeDB is opened via the public `treedb.Open` wrapper.
	//
	// It is intentionally independent of ChunkSize so benchmarks and callers can
	// tune the main index pager without inflating dictdb disk usage.
	//
	// Values <= 0 use a default of 64KiB.
	DictDBChunkSize int64
	// TemplateDBChunkSize controls the mmap chunk size used for the `templatedb/`
	// side store when template compression is enabled.
	//
	// Values <= 0 use a default of 64KiB.
	TemplateDBChunkSize int64
	KeepRecent          uint64 // Default 10000
	// PagerSyncConcurrency controls how many goroutines may msync dirty chunks
	// in parallel during Sync. Values <= 0 use the default (1).
	PagerSyncConcurrency int
	// PagerMmapPopulate enables MAP_POPULATE on Linux when mmapping index.db
	// chunks. This can reduce minor-fault overhead under random access patterns
	// at the cost of increased work at map/grow time.
	PagerMmapPopulate bool
	// PagerPrefetchOnRead enables best-effort prefetch hints (madvise WILLNEED)
	// for mmapped index chunks (Linux only). When enabled, TreeDB may issue
	// prefetch requests opportunistically (e.g. before rewriting child pages
	// during checkpoint/merge). It is a no-op on unsupported platforms.
	PagerPrefetchOnRead bool

	// Durability configures cached-mode durability semantics.
	//
	// The default (zero) is DurabilityDurable.
	Durability DurabilityMode
	// DisableBackgroundPrune keeps pruning on the commit critical path (legacy
	// behavior). When false (default), a bounded background pruner frees pages
	// asynchronously to reduce commit latency under churn.
	DisableBackgroundPrune bool
	// PruneInterval controls how often the background pruner wakes up (0 uses a
	// default).
	PruneInterval time.Duration
	// PruneMaxPages bounds how many pages are freed per pruner tick (0 uses a
	// default; <0 means unlimited).
	PruneMaxPages int
	// PruneMaxDuration bounds how long a pruner tick may run (0 uses a default;
	// <0 means unlimited).
	PruneMaxDuration time.Duration

	FlushThreshold int64
	// MemtableMode selects the cached-mode memtable implementation.
	// Supported values: "skiplist", "hash_sorted", "btree", "append_only", "adaptive".
	MemtableMode string
	// MemtableShards controls the number of mutable memtable shards in cached
	// mode. Values <= 0 use a runtime-dependent default.
	MemtableShards int
	// DomainIngressWorkers enables experimental domain-local ingress workers in
	// cached mode. Values <= 0 keep the legacy direct write path.
	DomainIngressWorkers int
	// DomainIngressQueueSize configures the per-worker ingress queue length when
	// DomainIngressWorkers is enabled. Values <= 0 use a default.
	DomainIngressQueueSize int
	// PreferAppendAlloc makes the page allocator ignore the freelist and append
	// new pages instead. This can improve scan locality under churn at the cost
	// of file growth (space is reclaimed later via vacuum).
	PreferAppendAlloc bool
	// FreelistRegionPages and FreelistRegionRadius bias freelist reuse toward
	// nearby page regions to improve locality. Leave both at 0 to disable the
	// bias (default). If either is set, missing values will use defaults.
	// Set FreelistRegionRadius < 0 to force-disable the bias.
	FreelistRegionPages  uint64
	FreelistRegionRadius int

	// LeafFillTargetPPM and InternalFillTargetPPM control how full newly-written
	// B+Tree pages are allowed to become before forcing a split (soft-full).
	// Lower values reduce split churn and slow re-fragmentation under updates, at
	// the cost of higher page count (more index bytes).
	//
	// Values are in parts-per-million where 1_000_000 means "allow full pages"
	// (current behavior). Zero uses the default (1_000_000).
	LeafFillTargetPPM     uint32
	InternalFillTargetPPM uint32
	// MaintenanceOpsPerCoalesce controls the maintenance budget during zipper
	// merge. It bounds coalesce work to roughly len(ops)/K operations per batch.
	// 0 uses the default; negative disables the budget (full maintenance).
	MaintenanceOpsPerCoalesce int
	// LeafPrefixCompression enables prefix-compressed leaf nodes for new pages.
	LeafPrefixCompression bool
	// IndexColumnarLeaves enables the experimental columnar leaf encoding for new pages.
	IndexColumnarLeaves bool
	// IndexPackedValuePtr enables the experimental packed 12-byte ValuePtr encoding
	// for pointer entries in new leaf pages.
	//
	// Packed pointers store ValuePtr.Offset as u32 on disk. Callers must ensure
	// value-log segments are rotated such that offsets remain representable.
	IndexPackedValuePtr bool
	// IndexInternalBaseDelta enables the experimental internal-node base-delta encoding.
	IndexInternalBaseDelta bool
	// IndexOuterLeavesInValueLog stores B+Tree leaf pages (the pages containing
	// key/value entries) in the persistent value log instead of index.db.
	//
	// When enabled, internal nodes store encoded value-log pointers for leaf
	// children. This is pre-alpha and changes on-disk format/assumptions.
	IndexOuterLeavesInValueLog bool
	// IndexAdaptiveLeafEncoding enables per-page adaptive selection of leaf
	// encoding flags using deterministic heuristics from key/value shape.
	//
	// This option only affects newly-written leaf pages.
	IndexAdaptiveLeafEncoding bool
	// MaxQueuedMemtables controls how much immutable-memtable backlog the cached
	// layer will allow before applying backpressure (i.e. forcing flush work on
	// writers). A negative value disables backpressure entirely (higher short-term
	// ingest, but potentially unbounded flush debt). Zero uses the default.
	MaxQueuedMemtables int

	// SlowdownBacklogSeconds begins applying writer backpressure when queued flush
	// backlog exceeds this many seconds of estimated flush work (0 disables).
	SlowdownBacklogSeconds float64
	// StopBacklogSeconds blocks writers when queued flush backlog exceeds this many
	// seconds of estimated flush work (0 disables).
	StopBacklogSeconds float64
	// MaxBacklogBytes is an absolute cap on queued flush backlog bytes (0 disables).
	MaxBacklogBytes int64

	// WriterFlushMaxMemtables bounds how much queued work a writer will help flush
	// per write when backpressure is active (0 uses a default).
	WriterFlushMaxMemtables int
	// WriterFlushMaxDuration bounds how long a writer will spend helping flush per
	// write when backpressure is active (0 disables the time bound).
	WriterFlushMaxDuration time.Duration
	// FlushBuildConcurrency controls how many goroutines may be used to build a
	// combined flush batch from multiple immutable memtables in cached mode.
	// 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.
	// A value of 0 enables adaptive chunk sizing, values < 0 use the fixed default of 8192,
	// and values > 0 set an explicit 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

	// 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 (0=default, <0=disable cap).
	FlushBackendMaxBatches int

	// 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 cached-mode
	// journal/commitlog segments (metadata only).
	//
	// The redo log will only keep compressed bytes when they are smaller than the
	// raw payload, so compression never causes size amplification.
	JournalCompression bool

	// ValueLog configures value-log pointer behavior and read integrity.
	ValueLog ValueLogOptions

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

	// VerifyOnRead forces checksum verification on every index page read,
	// bypassing the verified-page cache.
	VerifyOnRead bool
	// DisableSideStores skips opening dictdb/templatedb side stores.
	// This is intended for internal side-store usage (e.g. templatedb itself).
	DisableSideStores bool

	// DisablePiggybackCompaction disables opportunistic defragmentation during writes.
	// When false (default), nodes are rewritten if their siblings are physically
	// distant, keeping the tree clustered. Set to true to maximize write speed.
	DisablePiggybackCompaction bool

	// BackgroundCheckpointInterval enables periodic durable checkpoints in cached
	// mode. A checkpoint creates a backend sync boundary and trims
	// cached-mode WAL segments to keep `wal/` growth bounded.
	//
	// Semantics:
	// - `0` uses a default.
	// - `<0` disables the periodic interval trigger.
	BackgroundCheckpointInterval time.Duration
	// BackgroundCheckpointIdleDuration triggers an opportunistic checkpoint after
	// a period of write-idleness in cached mode.
	//
	// Semantics:
	// - `0` uses a default.
	// - `<0` disables the idle trigger.
	BackgroundCheckpointIdleDuration time.Duration
	// BackgroundIndexVacuumInterval enables periodic online index vacuum passes.
	// `0` uses a default; `<0` disables.
	BackgroundIndexVacuumInterval time.Duration
	// BackgroundIndexVacuumSpanRatioPPM sets the span ratio threshold that
	// triggers a vacuum pass (0 uses a default).
	BackgroundIndexVacuumSpanRatioPPM uint32
	// MaxWALBytes triggers an immediate checkpoint in cached mode when the sum of
	// WAL segment sizes exceeds this many bytes (0 uses a default; <0 disables the
	// size trigger). This is an operational safety cap; it does not make each
	// individual write durable (use *Sync APIs for that).
	MaxWALBytes int64
}

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

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

type ValueLogAutoPolicy uint8

type ValueLogBlockCodec uint8

type ValueLogCompressionMode uint8

type ValueLogDictClassMode uint8

type ValueLogDomainThreshold struct {
	// Prefix selects the key domain this override applies to.
	Prefix []byte
	// InlineThreshold is the maximum inline value size for keys in Prefix.
	// Values larger than this threshold are eligible for value-log pointers.
	// Zero forces all non-empty values in this domain to pointer placement.
	InlineThreshold int
}

type ValueLogGCOptions struct {
	DryRun bool
	// ProtectedPaths preserves legacy callers that provide a single merged set
	// of protected paths. Prefer the specific ProtectedInUsePaths and
	// ProtectedRetainedPaths fields for blocker classification.
	ProtectedPaths []string
	// ProtectedInUsePaths are paths that may still be referenced by mutable
	// in-memory state during online maintenance.
	ProtectedInUsePaths []string
	// ProtectedRetainedPaths are paths pinned by pointer lifecycle retention.
	ProtectedRetainedPaths []string
	// ObservedSourceFileIDs enables per-classification probe counters for a
	// caller-provided subset of segment IDs (for example, rewrite-selected
	// source segments). IDs not present in the current set are ignored.
	ObservedSourceFileIDs []uint32
	// ObservedSourceAssumeUnreferenced indicates ObservedSourceFileIDs are
	// already known to be unreferenced. When true, ValueLogGC skips the
	// reachability scan and only classifies (and, if !DryRun, zombifies) the
	// observed IDs; it does not attempt to reclaim other segments.
	ObservedSourceAssumeUnreferenced bool
}

type ValueLogGCStats struct {
	SegmentsTotal                           int
	SegmentsReferenced                      int
	SegmentsActive                          int
	SegmentsProtected                       int
	SegmentsProtectedInUse                  int
	SegmentsProtectedRetained               int
	SegmentsProtectedOverlap                int
	SegmentsProtectedOther                  int
	SegmentsEligible                        int
	SegmentsDeleted                         int
	SegmentsPending                         int
	BytesTotal                              int64
	BytesReferenced                         int64
	BytesActive                             int64
	BytesProtected                          int64
	BytesProtectedInUse                     int64
	BytesProtectedRetained                  int64
	BytesProtectedOverlap                   int64
	BytesProtectedOther                     int64
	BytesEligible                           int64
	BytesDeleted                            int64
	BytesPending                            int64
	ObservedSourceSegments                  int
	ObservedSourceSegmentsReferenced        int
	ObservedSourceSegmentsActive            int
	ObservedSourceSegmentsProtected         int
	ObservedSourceSegmentsProtectedInUse    int
	ObservedSourceSegmentsProtectedRetained int
	ObservedSourceSegmentsProtectedOverlap  int
	ObservedSourceSegmentsProtectedOther    int
	ObservedSourceSegmentsEligible          int
	ObservedSourceSegmentsDeleted           int
	ObservedSourceSegmentsPending           int
	ObservedSourceBytes                     int64
	ObservedSourceBytesReferenced           int64
	ObservedSourceBytesActive               int64
	ObservedSourceBytesProtected            int64
	ObservedSourceBytesProtectedInUse       int64
	ObservedSourceBytesProtectedRetained    int64
	ObservedSourceBytesProtectedOverlap     int64
	ObservedSourceBytesProtectedOther       int64
	ObservedSourceBytesEligible             int64
	ObservedSourceBytesDeleted              int64
	ObservedSourceBytesPending              int64
}

type ValueLogGenerationConfig struct {
	// Policy selects generation behavior. Off preserves current behavior.
	Policy ValueLogGenerationPolicy
	// LeafSegmentTargetBytes configures target segment size for leaf_vlog
	// generations when outer leaves are stored out-of-line.
	//
	// 0 uses the implementation default leaf-generation target.
	LeafSegmentTargetBytes int64
	// HotSegmentTargetBytes configures target segment size for hot generation.
	// 0 uses implementation default.
	HotSegmentTargetBytes int64
	// WarmSegmentTargetBytes configures target segment size for warm generation.
	// 0 uses implementation default.
	WarmSegmentTargetBytes int64
	// ColdSegmentTargetBytes configures target segment size for cold generation.
	// 0 uses implementation default.
	ColdSegmentTargetBytes int64
	// RewriteBudgetBytesPerSec bounds background incremental rewrite bandwidth.
	// 0 disables byte-budget trigger.
	RewriteBudgetBytesPerSec int64
	// RewriteBudgetRecordsPerSec bounds background incremental rewrite records/s.
	// 0 disables record-budget trigger.
	RewriteBudgetRecordsPerSec int
	// RewriteTriggerStaleRatioPPM triggers rewrite when stale/live ratio exceeds
	// threshold (parts-per-million, 0 disables).
	RewriteTriggerStaleRatioPPM uint32
	// RewriteTriggerTotalBytes triggers rewrite when total retained bytes exceeds
	// threshold (0 disables).
	RewriteTriggerTotalBytes int64
	// RewriteTriggerChurnPerSec triggers rewrite when churn rate exceeds
	// threshold (0 disables).
	RewriteTriggerChurnPerSec int64
	// RewriteMinSegmentAge gates online rewrite to source segments that are at
	// least this old.
	//
	// 0 uses the implementation default.
	RewriteMinSegmentAge time.Duration
}

type ValueLogGenerationPolicy uint8

type ValueLogOptions struct {
	// Compression selects value-log compression behavior.
	Compression ValueLogCompressionMode
	// BlockCodec selects the block codec for block compression.
	BlockCodec ValueLogBlockCodec
	// BlockTargetCompressedBytes guides grouped block size adaptation.
	//
	// 0 uses a default.
	BlockTargetCompressedBytes int
	// IncompressibleHoldBytes configures auto-mode suppression duration after
	// repeated incompressible probes.
	//
	// 0 uses a default.
	IncompressibleHoldBytes int
	// IncompressibleProbeIntervalBytes controls probe cadence while
	// incompressible hold is active.
	//
	// 0 uses a default.
	IncompressibleProbeIntervalBytes int
	// AutoPolicy controls auto-mode bias (throughput, balanced, size).
	AutoPolicy ValueLogAutoPolicy
	// DictClassMode controls dictionary-state partitioning:
	// 0=single (default shared dict stream), 1=split_outer_leaf.
	DictClassMode ValueLogDictClassMode

	// PointerThreshold controls when value-log pointers are used.
	// Values <= 0 use a default threshold. In cached mode, relaxed durability
	// settings may choose a smaller default to avoid large-scale update cliffs by
	// pushing moderate values into the value log.
	PointerThreshold int
	// Generational configures generation-aware value-log placement and rewrite
	// scheduling. PR1 wires config and stats only; behavior remains legacy until
	// follow-on phases land.
	Generational ValueLogGenerationConfig
	// ForcePointers stores all values out-of-line in the value log (no inline values).
	ForcePointers bool
	// DomainInlineThresholds provides optional per-domain overrides for
	// inline-vs-pointer placement. These overrides are evaluated by
	// longest-prefix match and fall back to PointerThreshold/default behavior
	// when no domain matches.
	DomainInlineThresholds []ValueLogDomainThreshold
	// RawWritevMinAvgBytes controls raw grouped-frame writev usage.
	//
	// 0 enables adaptive mode (no average-bytes floor).
	RawWritevMinAvgBytes int
	// RawWritevMinBatchRecords controls minimum grouped records before raw writev
	// is considered.
	//
	// <=0 uses the default.
	RawWritevMinBatchRecords int

	// ReadIntegrity configures checksum verification on value-log reads.
	ReadIntegrity IntegrityMode

	// MaxRetainedBytes emits a warning when retained value-log bytes exceed this
	// threshold (0 disables warnings). Cached mode only.
	MaxRetainedBytes int64
	// MaxRetainedBytesHard disables value-log pointers for new large values once
	// retained bytes exceed this threshold (0 disables the cap).
	MaxRetainedBytesHard int64

	// DictLookup provides dictionary bytes for value-log decoding.
	DictLookup valuelog.DictLookup
	// DictCurrentForClass resolves the current dictionary ID for a payload class.
	// Offline/maintenance rewrite uses this to seed class-specific rewrite codecs.
	DictCurrentForClass func(context.Context, string) (uint64, error)
	// DictLeafPayloadMode reports whether a published leaf dictionary expects raw
	// 4KiB leaf pages (useRawPages=true) or compact split-leaf payloads
	// (useRawPages=false). The returned ok flag is false when no explicit mode is
	// recorded and callers should fall back to legacy defaults.
	DictLeafPayloadMode func(context.Context, uint64) (useRawPages bool, ok bool, err error)
	// DictPut persists dictionary bytes and returns the stable dictionary ID.
	// Offline/maintenance rewrite may use this to bootstrap a class-specific dict
	// before rewriting into dict-compressed frames.
	DictPut func(context.Context, []byte) (uint64, error)
	// DictSetCurrentForClass marks a dictionary ID as the current dict for the
	// provided payload class. Rewrite bootstrap uses this after publishing a new
	// class-specific dict.
	DictSetCurrentForClass func(context.Context, string, uint64) error
	// DictSetLeafPayloadMode records whether a published leaf dictionary expects
	// raw 4KiB leaf pages or compact split-leaf payloads.
	DictSetLeafPayloadMode func(context.Context, uint64, bool) error

	// DictTrain configures background dictionary training for value-log frame
	// compression in cached mode.
	DictTrain compression.TrainConfig
	// DictAdaptiveRatio enables best-effort adaptive disable/pause of value-log
	// dictionary compression when payload compression ratios degrade (0 disables).
	DictAdaptiveRatio float64
	// DictMetricsWindowBytes controls the rolling window size for ratio tracking (0=default).
	DictMetricsWindowBytes int
	// DictMetricsMinRecords controls how many records must be observed in a window
	// before adaptive pause triggers (0=default).
	DictMetricsMinRecords int
	// DictMetricsPauseBytes controls how long to pause dict compression after a degraded
	// window is detected (0=default).
	DictMetricsPauseBytes int
	// DictIncompressibleHoldBytes enables classifier-driven hold mode for
	// high-entropy streams. While hold mode is active, dict 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.
	DictIncompressibleHoldBytes int
	// DictProbeIntervalBytes controls periodic probe attempts while
	// incompressible hold mode is active.
	//
	// <=0 uses a default derived from hold bytes.
	DictProbeIntervalBytes int
	// DictMinPayloadSavingsRatio rejects newly trained dictionaries whose payload
	// ratio does not improve by at least this fraction (0 uses a cached-mode
	// throughput-oriented default: 0.02 normally, 0.05 with ForcePointers or
	// WAL disabled).
	DictMinPayloadSavingsRatio float64
	// DictMaxK clamps the maximum group size (K) used for value-log dict-compressed
	// frames.
	//
	// Larger K can improve compression ratio (more cross-record matches) and can
	// reduce framing overhead, but may increase CPU and tail latency due to larger
	// encode/decode units.
	//
	// Values <= 0 use the default (32). Values above the engine maximum are clamped.
	DictMaxK int
	// DictFrameEncodeLevel controls the zstd encoder level used for dict-compressed
	// value-log frames.
	//
	// Values <= 0 use the default (SpeedFastest).
	DictFrameEncodeLevel zstd.EncoderLevel
	// DictFrameEnableEntropy enables entropy coding for dict-compressed value-log
	// frames (higher ratio, lower throughput).
	//
	// Default is false (throughput-focused: no-entropy compression).
	DictFrameEnableEntropy bool

	// CompressionAutotune configures the wall-time value-log compression autotuner.
	CompressionAutotune valuelog.AutotuneOptions

	// TemplateMode controls template-based compression for value-log values.
	TemplateMode template.Mode
	// TemplateConfig controls template creation and encoding behavior.
	TemplateConfig template.Config
	// TemplateReadStrict controls strict template decode behavior.
	TemplateReadStrict bool
	// TemplateStore provides template routing/definition lookups for template
	// encoding (for example in offline rewrite prepass experiments).
	TemplateStore template.Store
	// TemplateLookup provides template definition bytes for value-log decoding.
	TemplateLookup valuelog.TemplateLookup
	// TemplateDecodeOptions controls decode caps for template payloads.
	TemplateDecodeOptions template.DecodeOptions
}

type ValueLogRewriteChunkPlan struct {
	ChunkBytes int64

	SourceChunks []ValueLogRewritePlanChunk

	ChunksTotal    int
	ChunksSelected int

	BytesTotal int64
	BytesLive  int64
	BytesStale int64

	SelectedBytesTotal int64
	SelectedBytesLive  int64
	SelectedBytesStale int64

	AgeBlockedChunks          int
	AgeBlockedBytesTotal      int64
	AgeBlockedBytesLive       int64
	AgeBlockedBytesStale      int64
	AgeBlockedMinRemainingAge time.Duration
}

type ValueLogRewriteLocalityPolicy string

type ValueLogRewriteOnlineOptions struct {
	// BatchSize bounds pointer swaps per commit.
	BatchSize int
	// SyncEachBatch forces fsync durability boundaries for each rewritten batch.
	SyncEachBatch bool
	// MaxSegmentBytes bounds new value-log segment size during rewrite.
	// <=0 uses a default.
	MaxSegmentBytes int64
	// LocalityPolicy controls ordering of rewritten pointer candidates within
	// each batch.
	LocalityPolicy ValueLogRewriteLocalityPolicy
	// SourceFileIDs restricts rewrite to pointers currently referencing these
	// value-log segment IDs. Missing IDs are ignored.
	SourceFileIDs []uint32
	// SourceChunks restrict rewrite to explicit value-log chunks. When non-empty,
	// they take precedence over SourceFileIDs and sparse segment selection.
	SourceChunks []ValueLogRewritePlanChunk
	// SourceChunkBytes is the chunk width used to interpret SourceChunks.
	SourceChunkBytes int64
	// ProtectedPaths are value-log segment paths that must not be marked zombie
	// during rewrite cleanup.
	//
	// When non-empty, cleanup also avoids zombifying currently-active pre-existing
	// segments (cached-mode maintenance), since concurrent writers may still be
	// appending records whose pointers are not yet visible in the backend index.
	ProtectedPaths []string
	// MaxSourceSegments bounds the number of source segments selected by sparse
	// segment selection. Applies only when SourceFileIDs is empty.
	MaxSourceSegments int
	// MaxSourceBytes bounds estimated live bytes selected by sparse segment
	// selection. Applies only when SourceFileIDs is empty.
	MaxSourceBytes int64
	// MaxCopiedBytes bounds the selected source bytes actually rewritten in this
	// pass. <=0 disables the bound.
	MaxCopiedBytes int64
	// MinSegmentStaleRatio requires stale_bytes/segment_size to be at least this
	// value (0..1) when sparse segment selection is used.
	MinSegmentStaleRatio float64
	// MinSegmentStaleBytes requires estimated stale bytes to be at least this
	// threshold when sparse segment selection is used.
	MinSegmentStaleBytes int64
	// MinSegmentAge excludes very recent source segments from sparse selection.
	// This is useful for cached maintenance so freshly-written segments are not
	// immediately churned by rewrite during sustained ingest.
	MinSegmentAge time.Duration
	// ReserveRIDs allocates a contiguous RID range for rewrite-created records.
	// Cached-mode callers should provide the live runtime allocator here so
	// online rewrite and foreground writes share one RID namespace.
	ReserveRIDs func(count int) (start uint64, err error)
}

type ValueLogRewritePlan struct {
	// SourceFileIDs are the selected value-log segment IDs. The slice is sorted.
	SourceFileIDs []uint32
	// SelectedSegments summarizes per-segment live/stale estimates for the
	// selected SourceFileIDs when live-byte estimation was performed.
	//
	// When present, it is ordered by FileID ascending.
	SelectedSegments []ValueLogRewritePlanSegment

	SegmentsTotal    int
	SegmentsSelected int

	BytesTotal int64
	BytesLive  int64
	BytesStale int64

	SelectedBytesTotal int64
	SelectedBytesLive  int64
	SelectedBytesStale int64

	// AgeBlocked* summarizes candidate segments excluded by MinSegmentAge while
	// evaluating sparse rewrite candidates. These counters are age-filter
	// diagnostics, not a guarantee that every counted segment would otherwise
	// satisfy stale/live rewrite thresholds.
	AgeBlockedSegments        int
	AgeBlockedBytesTotal      int64
	AgeBlockedBytesLive       int64
	AgeBlockedBytesStale      int64
	AgeBlockedMinRemainingAge time.Duration
}

type ValueLogRewritePlanChunk struct {
	FileID      uint32
	ChunkOffset int64
	BytesTotal  int64
	BytesLive   int64
	BytesStale  int64
	StaleRatio  float64
}

type ValueLogRewritePlanSegment struct {
	FileID     uint32
	BytesTotal int64
	BytesLive  int64
	BytesStale int64
	StaleRatio float64
}

type ValueLogRewriteStats struct {
	SegmentsBefore int
	SegmentsAfter  int
	BytesBefore    int64
	BytesAfter     int64
	RecordsCopied  int
	// Value* counters track key/value-pointer payload copied by the main rewrite
	// pointer swap path.
	ValueRecordsCopied int
	ValueBytesCopied   int64
	// SourceSegmentsRequested is the number of source segments selected for this
	// rewrite run after applying selection filters.
	SourceSegmentsRequested int
	// SourceChunksRequested is the number of explicit source chunks selected for
	// this rewrite run when chunk-restricted execution is used.
	SourceChunksRequested int
	// SourceSegmentsStillReferenced is the subset of selected source segments
	// that remained referenced after rewrite pointer swaps and cleanup.
	SourceSegmentsStillReferenced int
	// SourceSegmentsUnreferenced is the subset of selected source segments that
	// became unreferenced after rewrite pointer swaps and cleanup.
	SourceSegmentsUnreferenced int
	// SourceBytesRequested is the total bytes across selected source segments.
	SourceBytesRequested int64
	// SourceBytesStillReferenced is the bytes of selected source segments that
	// remained referenced after rewrite pointer swaps and cleanup.
	SourceBytesStillReferenced int64
	// SourceBytesUnreferenced is the bytes of selected source segments that
	// became unreferenced after rewrite pointer swaps and cleanup.
	SourceBytesUnreferenced int64
	// SourceBytesProcessed is the bounded subset of selected source bytes
	// actually rewritten in this pass. When zero, the rewrite either copied
	// nothing or ran without a per-pass source-byte bound.
	SourceBytesProcessed int64
	// SourceFileIDsStillReferenced records which selected source segments
	// remained referenced after cleanup.
	SourceFileIDsStillReferenced []uint32
	// SourceFileIDsUnreferenced records which selected source segments became
	// fully unreferenced after cleanup.
	SourceFileIDsUnreferenced []uint32

	TemplateRecordsAttempted int
	TemplateRecordsKept      int
	TemplateInputBytes       int64
	TemplateOutputBytes      int64

	TemplatePointerRecordsAttempted int
	TemplatePointerRecordsKept      int
	TemplatePointerInputBytes       int64
	TemplatePointerOutputBytes      int64
	TemplatePointerReasons          map[string]uint64

	TemplateOuterLeafRecordsAttempted int
	TemplateOuterLeafRecordsKept      int
	TemplateOuterLeafInputBytes       int64
	TemplateOuterLeafOutputBytes      int64
	TemplateOuterLeafReasons          map[string]uint64
}

type WritePolicy struct {
	FlushThreshold  int64 // Size of memtable before flush
	InlineThreshold int   // Max size of value to store inline
}