db

package
v0.6.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 1, 2026 License: MIT Imports: 47 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	IteratorModeFull              = tree.IteratorModeFull
	IteratorModeKeysOnly          = tree.IteratorModeKeysOnly
	IteratorModePointerProjection = tree.IteratorModePointerProjection
)
View Source 
const (
	MetaPage0ID = 0
	MetaPage1ID = 1
	KeepRecent  = 1
)
View Source 
const (
	FlushAdmissionReasonNoExplicitOptIn           = "no_explicit_opt_in"
	FlushAdmissionReasonExplicitOptIn             = "explicit_opt_in"
	FlushAdmissionReasonPolicyOff                 = "policy_off"
	FlushAdmissionReasonAutoAdmitted              = "auto_admitted"
	FlushAdmissionReasonAutoAdmittedCappedAdapt   = "auto_admitted_capped_adaptive"
	FlushAdmissionReasonAutoAdmittedHardwareAware = "auto_admitted_hardware_aware"
	FlushAdmissionReasonLowConcurrency            = "low_concurrency"
	FlushAdmissionReasonUnsafeDurability          = "unsafe_durability"
	FlushAdmissionReasonCheckpointDebt            = "checkpoint_debt_unresolved"
	FlushAdmissionReasonInvalidPolicy             = "invalid_policy"
)
View Source 
const (
	FlushAdmissionConcurrencyCapDisabled             = "disabled"
	FlushAdmissionConcurrencyCapConfigured           = "configured"
	FlushAdmissionConcurrencyCapConfiguredGOMAXPROCS = "configured_gomaxprocs_cap"
	FlushAdmissionConcurrencyCapDefaultPhysicalCores = "default_physical_cores"
	FlushAdmissionConcurrencyCapDefaultAutoCap       = "default_auto_cap"
	FlushAdmissionConcurrencyCapDefaultGOMAXPROCS    = "default_gomaxprocs_cap"
)
View Source 
const FlushSpanRunFallbackReasonCount = int(flushSpanRunFallbackReasonCount)

FlushSpanRunFallbackReasonCount is the size of the append-only fallback reason enum. It is exported for stats arrays; callers should iterate with FlushSpanRunFallbackReasons when they need the concrete stable reasons.

View Source 
const (
	// LeafPageReadCacheEntriesEnvKey names the environment variable that
	// overrides the process default when Options.LeafPageReadCacheEntries is 0.
	LeafPageReadCacheEntriesEnvKey = "TREEDB_LEAF_PAGE_CACHE_ENTRIES"
)
View Source 
const RequiredFeatureCommandWALV1 = "command_wal_v1"

Variables

View Source 
var (
	ErrCommandWALSplitPublish         = errors.New("treedb: command wal roots changed without advancing applied lsn")
	ErrCommandWALAppliedLSNRegression = errors.New("treedb: command wal applied lsn regression")
	ErrCommandWALAppliedLSNNonContig  = errors.New("treedb: command wal applied lsn non-contiguous")
)
View Source 
var (
	// ErrLocked indicates the database directory is already opened by another process.
	ErrLocked = lockfile.ErrLocked
	// ErrReadOnly indicates a write was attempted on a read-only DB handle.
	ErrReadOnly = errors.New("treedb: read-only")
	// ErrClosed indicates the DB handle is closed or closing for reads.
	ErrClosed = errors.New("treedb: db is closed")
	// ErrConcurrentModification indicates a publish or maintenance operation
	// observed that a root changed after its validation point.
	ErrConcurrentModification = errors.New("treedb: concurrent modification")
	// ErrRecoveryRequired indicates the DB must be opened read-write for recovery
	// before the requested read-only or offline-maintenance operation can run.
	ErrRecoveryRequired = collectionwal.ErrCollectionWALRecoveryRequired
	// ErrUnsupportedRequiredFeature indicates format.json requires a storage
	// feature this binary does not understand.
	ErrUnsupportedRequiredFeature = errors.New("treedb: unsupported required storage feature")
	// ErrCommandWALUnsupported is returned while command_wal_v1 durable
	// execution is still gated behind later implementation PRs.
	ErrCommandWALUnsupported = errors.New("treedb: command_wal_v1 execution is not enabled")
	// ErrCommandWALRejected is the stable public sentinel for commands that are
	// intentionally rejected while command_wal_v1 is active.
	ErrCommandWALRejected = errors.New("treedb: command_wal_v1 command rejected")
	// ErrCommandWALSegmentSeqExhausted indicates the command WAL segment sequence
	// number space has no strictly higher segment available.
	ErrCommandWALSegmentSeqExhausted = errors.New("treedb: command wal segment sequence exhausted")
)
View Source 
var ErrCommandWALContextMissingFrame = errors.New("treedb: command WAL context publish requires a command frame")

ErrCommandWALContextMissingFrame reports a command-WAL context publish that was called without the command frame that defines the publish LSN.

View Source 
var ErrCommandWALDirtyActivation = errors.New("treedb: command_wal_v1 requires clean legacy WAL before activation")
View Source 
var ErrCommandWALMissingValueLogRID = errors.New("treedb: command wal missing value-log rid")
View Source 
var ErrCompactStorageLeafPageLogHandoffCleanup = errors.New("treedb: compact storage leaf page log handoff cleanup failed")

ErrCompactStorageLeafPageLogHandoffCleanup is returned when CompactStorage cannot safely restore the previous leaf-page-log owner after installing its temporary compact writer.

View Source 
var ErrCompactStorageLeafPageLogOwnerUnsupported = errors.New("treedb: compact storage leaf page log owner unsupported")

ErrCompactStorageLeafPageLogOwnerUnsupported is returned when exhaustive compact reaches an installed leaf-page-log owner it cannot safely replace.

View Source 
var ErrNilUpdateFunc = errors.New("treedb: nil update function")

ErrNilUpdateFunc indicates a nil callback was passed to Update.

View Source 
var ErrOrderedRootDeltaBatchGroupCommandWALContextNilSystemBuilder = errors.New("treedb: PublishOrderedRootDeltaBatchGroupWithCommandWALContextAndSystemDeltaBuilder: nil system builder")

ErrOrderedRootDeltaBatchGroupCommandWALContextNilSystemBuilder reports a nil system delta builder passed to the batch ordered-root command-WAL context publish API.

View Source 
var ErrOrderedRootGroupCommandWALContextNilSystemBuilder = errors.New("treedb: PublishOrderedRootDeltaGroupWithCommandWALContextAndSystemDeltaBuilder: nil system builder")

ErrOrderedRootGroupCommandWALContextNilSystemBuilder reports a nil system delta builder passed to an ordered-root command-WAL context publish API.

View Source 
var ErrStorageMaintenancePlanMissing = errors.New("treedb: storage-maintenance publish requires a recognized maintenance plan")

ErrStorageMaintenancePlanMissing reports a maintenance ordered-root publish that was called without a recognized storage-maintenance plan token.

View Source 
var ErrStorageMaintenancePublishPreApplyFailed = errors.New("treedb: storage-maintenance publish failed before root apply")

ErrStorageMaintenancePublishPreApplyFailed marks a storage-maintenance publish failure that happened before any root or system-root delta was applied. Maintenance callers may use this to clean newly copied physical assets without risking removal of data that a partially-applied root can reach.

View Source 
var ErrStorageMaintenanceRootDeltaEmpty = errors.New("treedb: storage-maintenance publish requires every maintenance root delta to rewrite its root")

ErrStorageMaintenanceRootDeltaEmpty reports a maintenance publish whose marked root delta did not actually rewrite its root.

View Source 
var ErrStorageMaintenanceRootDeltaIteratorMissing = errors.New("treedb: storage-maintenance publish requires every maintenance root delta to include an iterator")

ErrStorageMaintenanceRootDeltaIteratorMissing reports a maintenance publish whose marked root delta has no iterator to apply.

View Source 
var ErrStorageMaintenanceRootDeltaMissing = errors.New("treedb: storage-maintenance publish requires at least one maintenance root delta")

ErrStorageMaintenanceRootDeltaMissing reports a maintenance publish with no root delta to rewrite. System-only logical changes must use command-WAL covered publish APIs.

View Source 
var ErrStorageMaintenanceSystemBuilderMissing = errors.New("treedb: storage-maintenance publish requires a system-delta builder")

ErrStorageMaintenanceSystemBuilderMissing reports a maintenance publish with no system-root delta builder to atomically publish rewritten root IDs.

View Source 
var ErrUpdateValueNil = errors.New("value cannot be nil")

ErrUpdateValueNil is retained for callers that handled the former nil-value Update error. Raw KV Update now canonicalizes nil SetUpdate values to zero-length values.

View Source 
var ErrVacuumInProgress = errors.New("online vacuum already in progress")
View Source 
var ErrVacuumUnsupported = errors.New("online vacuum unsupported on this platform")
View Source 
var ErrValueLogAppenderUnavailable = errors.New("value-log appender unavailable")
View Source 
var LeafPageReadCacheEntries = defaultLeafPageReadCacheEntries

Functions

func CollectMaintenanceRootIDs added in v0.6.0 

func CollectMaintenanceRootIDs(p *pager.Pager, reader tree.SlabReader, state *DBState) ([]uint64, error)

CollectMaintenanceRootIDs returns the deduplicated root IDs that storage maintenance must preserve for the supplied state: the active user and system roots plus collection roots referenced by system descriptors.

func CollectMaintenanceRootIDsForSystemRoot added in v0.6.0 

func CollectMaintenanceRootIDsForSystemRoot(p *pager.Pager, reader tree.SlabReader, systemRootID uint64) ([]uint64, error)

CollectMaintenanceRootIDsForSystemRoot returns the deduplicated root IDs for a system root plus collection roots referenced by that system root's descriptors.

func CollectMaintenanceRootIDsForSystemRootWithContext added in v0.6.0 

func CollectMaintenanceRootIDsForSystemRootWithContext(ctx context.Context, p *pager.Pager, reader tree.SlabReader, systemRootID uint64) ([]uint64, error)

CollectMaintenanceRootIDsForSystemRootWithContext is the context-aware form of CollectMaintenanceRootIDsForSystemRoot.

func CollectMaintenanceRootIDsWithContext added in v0.6.0 

func CollectMaintenanceRootIDsWithContext(ctx context.Context, p *pager.Pager, reader tree.SlabReader, state *DBState) ([]uint64, error)

CollectMaintenanceRootIDsWithContext is the context-aware form of CollectMaintenanceRootIDs.

func ColumnAssetRootDirPath added in v0.6.0 

func ColumnAssetRootDirPath(dir string) string

func CommandWALRequiredFeatureEnabled added in v0.6.0 

func CommandWALRequiredFeatureEnabled(dir string) (bool, error)

func DetectPhysicalCores added in v0.6.0 

func DetectPhysicalCores() int

DetectPhysicalCores returns the best-effort number of physical CPU cores for the current host. A return value <=0 means the platform did not expose a reliable physical-core count. Runtime defaults must then fall back to a safe logical-CPU policy.

func LeafLogDirPath added in v0.5.0 

func LeafLogDirPath(dir string) string

func NormalizePublicBatchReserveHint added in v0.4.0 

func NormalizePublicBatchReserveHint(size int) int

NormalizePublicBatchReserveHint keeps small public hints behaving like entry reserves, but treats larger hints as approximate byte budgets so callers do not accidentally preallocate one entry per byte. This is intentionally discontinuous at the cutover for compatibility with small entry-count hints.

For internal use; behavior may change without notice and is not part of the supported external API surface of the db package.

func OrderedRootDeltaBatchFromIterator added in v0.6.0 

func OrderedRootDeltaBatchFromIterator(iter iterator.UnsafeIterator) (*batch.Batch, error)

OrderedRootDeltaBatchFromIterator materializes a root-local mutation iterator into the same transient batch shape used by ordered-root delta publishing. It does not close iter.

func RegisterCommandWALReplayHandler added in v0.6.0 

func RegisterCommandWALReplayHandler(kind commitlog.CommandKind, handler CommandWALReplayHandler)

RegisterCommandWALReplayHandler installs a replay handler for a command kind. It is intended for package init registration by higher-level executors.

func RegisterCommandWALReplayHandlerWithOptions added in v0.6.0 

func RegisterCommandWALReplayHandlerWithOptions(kind commitlog.CommandKind, handler CommandWALReplayHandler, opts CommandWALReplayHandlerOptions)

RegisterCommandWALReplayHandlerWithOptions installs a replay handler with explicit recovery support requirements. Handlers that replay only in-memory metadata can opt out of value-log/leaf-log replay setup.

func ResolveInlineThresholdForKey added in v0.4.0 

func ResolveInlineThresholdForKey(baseThreshold int, key []byte, domains []ValueLogDomainThreshold) int

ResolveInlineThresholdForKey chooses an inline threshold for key using longest-prefix domain overrides and a global fallback.

Callers should pass NormalizeValueLogDomainThresholds output so that the first match is the intended longest-prefix override.

func ResolveLeafPageReadCacheEntries added in v0.6.0 

func ResolveLeafPageReadCacheEntries(optionEntries int) (int, error)

ResolveLeafPageReadCacheEntries returns the effective cache size for an Options.LeafPageReadCacheEntries value after applying process/env defaults. It returns an error when the explicit option, environment override, or process default resolves outside the supported cache-size range.

func SaveFormatConfig added in v0.4.0 

func SaveFormatConfig(dir string, cfg FormatConfig) error

SaveFormatConfig writes cfg to dir/format.json atomically. A transition into command_wal_v1 validates that legacy WAL state is clean; re-saving a config that already requires command_wal_v1 does not re-run activation validation because command-WAL segments are expected after activation.

func VacuumIndexOffline 

func VacuumIndexOffline(opts Options) error

VacuumIndexOffline rewrites index.db into a fresh file and swaps it in.

This is intended to reclaim space (reduce `index.db` chunk count) and restore locality after long churn. It is an offline operation (requires exclusive open lock).

func ValidateCommandWALActivationClean added in v0.6.0 

func ValidateCommandWALActivationClean(dir string) error

ValidateCommandWALActivationClean enforces the PR1 activation precondition: command_wal_v1 can only be advertised after legacy commit-log debt has been drained by checkpoint/rebuild. Later PRs will add the activator; this guard is production code now so tests and tooling cannot silently enable mixed modes.

func ValidateFlushSpanRunMetadata added in v0.6.0 

func ValidateFlushSpanRunMetadata(meta FlushSpanRunMetadata) error

ValidateFlushSpanRunMetadata checks only the ordering/ownership invariants needed by the M8 contract. It intentionally does not execute or publish the run; M9+ remains responsible for constructing the metadata from sealed memtables and base-root snapshots.

func ValidateFormatRequiredFeatureGate added in v0.6.0 

func ValidateFormatRequiredFeatureGate(dir string) error

ValidateFormatRequiredFeatureGate checks only the required-feature gate in format.json. It is intentionally narrower than LoadFormatConfig so IgnoreFormatConfig remains an escape hatch for malformed or future ordinary format configs, while still failing closed for explicitly required features.

func ValidateFragmentationReport 

func ValidateFragmentationReport(rep map[string]string) error

ValidateFragmentationReport validates basic invariants on a FragmentationReport output map. It is intended for tests and operational "health" tooling.

func ValueLogDirPath added in v0.5.0 

func ValueLogDirPath(dir string) string

func ValueReaderForState 

func ValueReaderForState(state *DBState) tree.SlabReader

ValueReaderForState returns a reader that resolves value-log pointers.

func WALDirPath added in v0.5.0 

func WALDirPath(dir string) string

Types

type Batch 

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

Batch implements the cosmos-db Batch interface.

func (*Batch) Close 

func (b *Batch) Close() error

func (*Batch) Delete 

func (b *Batch) Delete(key []byte) error

func (*Batch) DeleteRange added in v0.6.0 

func (b *Batch) DeleteRange(start, end []byte) error

func (*Batch) DeleteView 

func (b *Batch) DeleteView(key []byte) error

DeleteView records a Delete without copying the key bytes. Callers must treat key as immutable until the batch is written or closed.

func (*Batch) DeleteViewWithRevision added in v0.6.1 

func (b *Batch) DeleteViewWithRevision(key []byte, revision page.EntryRevision) error

func (*Batch) DeleteWithRevision added in v0.6.1 

func (b *Batch) DeleteWithRevision(key []byte, revision page.EntryRevision) error

func (*Batch) GetByteSize 

func (b *Batch) GetByteSize() (int, error)

func (*Batch) Replay 

func (b *Batch) Replay(fn func(batch.Entry) error) error

func (*Batch) Reserve added in v0.4.0 

func (b *Batch) Reserve(n int)

Reserve forwards best-effort preallocation hints to the internal batch.

func (*Batch) Reset 

func (b *Batch) Reset()

Reset clears the batch for reuse.

func (*Batch) Set 

func (b *Batch) Set(key, value []byte) error

func (*Batch) SetCommandWALPublish added in v0.6.0 

func (b *Batch) SetCommandWALPublish(appliedLSN uint64, covered []CommandWALLSNRange) error

SetCommandWALPublish records an already-appended command-WAL LSN range to publish atomically with this physical batch's root commit.

func (*Batch) SetFlushApplySpanNativeFallback added in v0.6.0 

func (b *Batch) SetFlushApplySpanNativeFallback(reason FlushSpanRunFallbackReason)

SetFlushApplySpanNativeFallback forces this internal batch's span-native candidate path to use fallback accounting with reason. It is used by cached checkpoint/close drains and tests; callers outside TreeDB internals should not rely on it as a stable public API.

func (*Batch) SetOps 

func (b *Batch) SetOps(ops []batch.Entry) error

func (*Batch) SetPointer 

func (b *Batch) SetPointer(key []byte, ptr page.ValuePtr) error

SetPointer records a pointer without copying the value bytes.

func (*Batch) SetPointerView added in v0.2.0 

func (b *Batch) SetPointerView(key []byte, ptr page.ValuePtr) error

SetPointerView records a pointer without copying the key bytes.

func (*Batch) SetPointerViewWithRevision added in v0.6.1 

func (b *Batch) SetPointerViewWithRevision(key []byte, ptr page.ValuePtr, revision page.EntryRevision) error

func (*Batch) SetPointerWithRevision added in v0.6.1 

func (b *Batch) SetPointerWithRevision(key []byte, ptr page.ValuePtr, revision page.EntryRevision) error

func (*Batch) SetView 

func (b *Batch) SetView(key, value []byte) error

SetView records a Put without copying key/value bytes. Callers must treat key/value as immutable until the batch is written or closed.

This is intentionally not part of the public batch.Interface; it is a best-effort optimization used by higher-level layers (e.g. cached streaming).

func (*Batch) SetViewWithRevision added in v0.6.1 

func (b *Batch) SetViewWithRevision(key, value []byte, revision page.EntryRevision) error

func (*Batch) SetWithRevision added in v0.6.1 

func (b *Batch) SetWithRevision(key, value []byte, revision page.EntryRevision) error

func (*Batch) Write 

func (b *Batch) Write() error

func (*Batch) WriteSync 

func (b *Batch) WriteSync() error

type CommandWALIntent added in v0.6.0 

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

CommandWALIntent is an opaque command-WAL append/finalize token used by higher-level deterministic command executors such as collections.

func NewCommandWALCoverageIntent added in v0.6.0 

func NewCommandWALCoverageIntent(appliedLSN uint64, covered CommandWALLSNRange) (*CommandWALIntent, error)

NewCommandWALCoverageIntent returns an intent for publishing roots that already reflect an appended contiguous command-WAL range. It does not append a new command frame when used with the ordered-root command-WAL publish APIs.

func (*CommandWALIntent) AssignedLSN added in v0.6.0 

func (intent *CommandWALIntent) AssignedLSN() uint64

AssignedLSN returns the command LSN already assigned to this intent. Replay intents use this to finalize durable command coverage without appending a duplicate foreground command frame.

func (*CommandWALIntent) ReplayAssignedLSN added in v0.6.0 

func (intent *CommandWALIntent) ReplayAssignedLSN() (uint64, bool)

ReplayAssignedLSN returns the assigned non-zero LSN and true only for replay-originated intents. The boolean keeps callers from treating LSN 0 as a replay sentinel.

func (*CommandWALIntent) StagedForPublish added in v0.6.0 

func (intent *CommandWALIntent) StagedForPublish() bool

StagedForPublish reports whether the intent was appended by AppendStagedCommandWALIntent and still expects its caller to hold the command-WAL staging lock through root publication.

type CommandWALLSNRange added in v0.6.0 

type CommandWALLSNRange struct {
	First uint64
	Last  uint64
}

type CommandWALPublishContext added in v0.6.0 

type CommandWALPublishContext struct {
	AppliedCommandLSN uint64
}

CommandWALPublishContext carries the command-WAL LSN assigned to a grouped root publish. Builders that need the LSN in durable metadata should use the context-aware grouped publish APIs so command append and root publication remain one fail-closed boundary.

type CommandWALReplayHandler added in v0.6.0 

type CommandWALReplayHandler func(db *DB, env commitlog.CommandEnvelope) error

CommandWALReplayHandler applies one deterministic command-WAL frame through its normal high-level executor and must publish the supplied frame LSN.

type CommandWALReplayHandlerOptions added in v0.6.0 

type CommandWALReplayHandlerOptions struct {
	NeedsReplayLogSupport bool
}

type CompactStorageDebt added in v0.6.0 

type CompactStorageDebt struct {
	ValueLogRewriteSegments int   `json:"value_log_rewrite_segments"`
	ValueLogRewriteBytes    int64 `json:"value_log_rewrite_bytes"`
	ValueLogGCSegments      int   `json:"value_log_gc_segments"`
	ValueLogGCBytes         int64 `json:"value_log_gc_bytes"`
	LeafPackGenerations     int   `json:"leaf_pack_generations"`
	LeafPackBytes           int64 `json:"leaf_pack_bytes"`
	LeafGCGenerations       int   `json:"leaf_gc_generations"`
	LeafGCBytes             int64 `json:"leaf_gc_bytes"`
	ZeroByteValueLogFiles   int   `json:"zero_byte_value_log_files"`
}

CompactStorageDebt summarizes remaining work after planning or compaction.

func (CompactStorageDebt) Empty added in v0.6.0 

func (d CompactStorageDebt) Empty() bool

Empty reports whether the storage audit found no meaningful compaction debt.

type CompactStorageLeafPageLogHandoffError added in v0.6.0 

type CompactStorageLeafPageLogHandoffError struct {
	Stage    string
	Recovery string
	Err      error
}

CompactStorageLeafPageLogHandoffError reports the restore stage that failed after CompactStorage installed its temporary leaf-page-log writer. When restoration cannot be proven safe, CompactStorage fails closed by clearing the active leaf-page-log writer; close and reopen the database before resuming writes.

func (*CompactStorageLeafPageLogHandoffError) Error added in v0.6.0 

func (e *CompactStorageLeafPageLogHandoffError) Error() string

func (*CompactStorageLeafPageLogHandoffError) Unwrap added in v0.6.0 

func (e *CompactStorageLeafPageLogHandoffError) Unwrap() []error

type CompactStorageLeafPageLogOwnerClass added in v0.6.0 

type CompactStorageLeafPageLogOwnerClass string

CompactStorageLeafPageLogOwnerClass identifies who owns the currently installed leaf-page-log writer from CompactStorage's point of view. 

const (
	CompactStorageLeafPageLogOwnerNone                     CompactStorageLeafPageLogOwnerClass = "no installed leaf log"
	CompactStorageLeafPageLogOwnerCommandWALReplayInline   CompactStorageLeafPageLogOwnerClass = "command-WAL/replay-inline internal owner"
	CompactStorageLeafPageLogOwnerInternalHiddenByWrapper  CompactStorageLeafPageLogOwnerClass = "internal owner hidden by wrapper"
	CompactStorageLeafPageLogOwnerCachedWrapper            CompactStorageLeafPageLogOwnerClass = "cached/wrapper owner"
	CompactStorageLeafPageLogOwnerStandaloneCallerExternal CompactStorageLeafPageLogOwnerClass = "standalone/caller external owner"
)

type CompactStorageLeafPageLogOwnerClassification added in v0.6.0 

type CompactStorageLeafPageLogOwnerClassification struct {
	OwnerClass CompactStorageLeafPageLogOwnerClass
	Status     CompactStorageOwnerStatus
	// Lifecycle is a caller-supplied modeled state, not runtime proof. The
	// current CompactStorage refusal path classifies after taking the exclusive
	// maintenance lock and therefore passes CompactStorageLifecycleExclusiveMaintenance.
	Lifecycle          CompactStorageLifecycleState
	Replaceable        bool
	RequiresQuiescence bool
	Detail             string
}

CompactStorageLeafPageLogOwnerClassification is the compact-owner production support contract attached to fail-closed exhaustive compact errors.

type CompactStorageLeafPageLogOwnerError added in v0.6.0 

type CompactStorageLeafPageLogOwnerError struct {
	Classification CompactStorageLeafPageLogOwnerClassification
}

CompactStorageLeafPageLogOwnerError carries the owner classification that caused exhaustive compact to fail closed.

func (*CompactStorageLeafPageLogOwnerError) Error added in v0.6.0 

func (e *CompactStorageLeafPageLogOwnerError) Error() string

func (*CompactStorageLeafPageLogOwnerError) Unwrap added in v0.6.0 

func (e *CompactStorageLeafPageLogOwnerError) Unwrap() error

type CompactStorageLifecycleState added in v0.6.0 

type CompactStorageLifecycleState string

CompactStorageLifecycleState records the writer lifecycle assumption used by the owner classifier. 

const (
	CompactStorageLifecycleExclusiveMaintenance CompactStorageLifecycleState = "exclusive maintenance"
	CompactStorageLifecycleQuiescedMaintenance  CompactStorageLifecycleState = "quiesced maintenance"
	CompactStorageLifecycleActiveWriter         CompactStorageLifecycleState = "active writer"
)

type CompactStorageMode added in v0.6.0 

type CompactStorageMode string

CompactStorageMode selects how aggressively CompactStorage should reclaim storage. Empty/default currently maps to full storage compaction. 

const (
	CompactStorageDefault    CompactStorageMode = ""
	CompactStorageFull       CompactStorageMode = "full"
	CompactStorageQuick      CompactStorageMode = "quick"
	CompactStorageExhaustive CompactStorageMode = "exhaustive"
)

type CompactStorageOptions added in v0.6.0 

type CompactStorageOptions struct {
	Mode CompactStorageMode

	// DryRun reports the current compaction plan without mutating storage.
	DryRun bool

	// SyncEachPhase asks rewrite/pack phases to fsync each durable batch.
	SyncEachPhase bool

	// Value-log rewrite knobs.
	ValueLogRewriteBatchSize       int
	ValueLogRewriteMaxSegmentBytes int64
	ValueLogProtectedPaths         []string
	// ValueLogProtectedPathsFunc refreshes online protected paths before each
	// value-log rewrite/GC audit or applied phase. Live cached-mode callers use
	// this so foreground writer rotations that happen during a multi-phase
	// compaction cannot leave newly queued value-log segments unprotected.
	ValueLogProtectedPathsFunc func() []string
	// ValueLogFencedProtectedPathsFunc refreshes paths that remain unsafe for
	// fenced observed-only reclaim after the caller has performed its write
	// fence. Cached callers use this to protect in-use writer paths without
	// preserving retained paths that are independently proven unreachable.
	ValueLogFencedProtectedPathsFunc func() []string

	// Leaf-generation pack knobs. Non-exhaustive defaults keep copy bytes per
	// pass finite while still draining ordinary debt.
	LeafGenerationProtectedRootIDs []uint64
	// LeafGenerationProtectedSystemRootIDs are system roots whose collection
	// descriptors should be expanded into additional protected leaf-generation
	// roots during compaction.
	LeafGenerationProtectedSystemRootIDs []uint64
	// LeafGenerationProtectedRootIDsFunc refreshes additional leaf-generation
	// roots before each leaf plan/pack/GC phase. Cached/native interop callers
	// use this so roots published outside backend meta roots keep their leaf-log
	// children live during compaction.
	LeafGenerationProtectedRootIDsFunc func() []uint64
	// LeafGenerationProtectedSystemRootIDsFunc refreshes additional system roots
	// whose collection root descriptors should be expanded during compaction.
	LeafGenerationProtectedSystemRootIDsFunc func() []uint64
	// LeafGenerationProtectedRootIDPairFunc refreshes ordinary and system roots
	// from one caller snapshot when both lists come from the same source.
	LeafGenerationProtectedRootIDPairFunc func() (rootIDs []uint64, systemRootIDs []uint64)
	LeafPackMaxPasses                     int
	LeafPackMaxGenerationsPerPass         int
	LeafPackMaxBytesToCopyPerPass         int64
	LeafPackMinExpectedReclaimBytes       int64
	LeafPackMinExpectedReclaimRatioPPM    int
	LeafPackMinReclaimPerCopyPPM          int
	// LeafPackForce bypasses leaf-pack admission thresholds. It is enabled by
	// CompactStorageExhaustive so benchmark/VACUUM-equivalent compaction can
	// drain low-yield physical debt instead of stopping at production policy
	// thresholds.
	LeafPackForce      bool
	LeafPackLeafFrameK int

	// ReserveRIDs lets cached-mode callers share the live RID allocator with
	// foreground writers.
	ReserveRIDs func(count int) (start uint64, err error)

	// UnsafeValueLogReclaimFencedUnreferenced permits CompactStorage to reclaim
	// unreferenced value-log segments that cached retained/current-writer
	// protection would otherwise hide. Callers must first checkpoint, fence
	// writers, rotate away from any candidate writer segment, and refresh the
	// value-log set. Backend-only callers should leave it disabled.
	UnsafeValueLogReclaimFencedUnreferenced bool

	// DisableZeroByteValueLogCleanup leaves zero-byte value_vlog segment files in
	// place. This is intended for specialty diagnostics that need to inspect
	// empty segment files after compaction.
	DisableZeroByteValueLogCleanup bool
}

CompactStorageOptions controls full storage compaction across TreeDB storage domains. Prefer this high-level API over manually sequencing value-log rewrite, value-log GC, leaf-generation pack/GC, and index vacuum.

type CompactStorageOwnerStatus added in v0.6.0 

type CompactStorageOwnerStatus string

CompactStorageOwnerStatus is the production support category for an exhaustive compact leaf-page-log owner. 

const (
	CompactStorageOwnerStatusSupportedTarget      CompactStorageOwnerStatus = "supported-target"
	CompactStorageOwnerStatusLiveWriterFailClosed CompactStorageOwnerStatus = "live-writer fail-closed"
	CompactStorageOwnerStatusExternalUnsupported  CompactStorageOwnerStatus = "external-owner unsupported"
	CompactStorageOwnerStatusBlockingBug          CompactStorageOwnerStatus = "blocking-bug"
)

type CompactStoragePhaseStats added in v0.6.0 

type CompactStoragePhaseStats struct {
	Name          string `json:"name"`
	Skipped       bool   `json:"skipped,omitempty"`
	SkipReason    string `json:"skip_reason,omitempty"`
	WallTimeNanos int64  `json:"wall_time_nanos"`
}

CompactStoragePhaseStats records one phase in a full compaction run.

type CompactStorageStats added in v0.6.0 

type CompactStorageStats struct {
	Mode   CompactStorageMode `json:"mode"`
	DryRun bool               `json:"dry_run"`

	Before []CompactStorageUsage `json:"before"`
	After  []CompactStorageUsage `json:"after"`

	Phases []CompactStoragePhaseStats `json:"phases,omitempty"`

	ValueLogRewritePlan ValueLogRewritePlan              `json:"value_log_rewrite_plan"`
	ValueLogRewrite     ValueLogRewriteStats             `json:"value_log_rewrite,omitempty"`
	ValueLogGC          ValueLogGCStats                  `json:"value_log_gc"`
	LeafGenerationPlan  LeafGenerationPlan               `json:"leaf_generation_plan"`
	LeafGenerationPacks []LeafGenerationPackRunOnceStats `json:"leaf_generation_packs,omitempty"`
	LeafGenerationGC    LeafGenerationGCStats            `json:"leaf_generation_gc"`

	ZeroByteValueLogFilesDeleted int `json:"zero_byte_value_log_files_deleted,omitempty"`

	RemainingDebt CompactStorageDebt `json:"remaining_debt"`

	// FullyCompacted is the legacy policy-oriented compacted flag. For
	// exhaustive mode, ByteMinimized reports the stricter benchmark contract.
	FullyCompacted       bool `json:"fully_compacted"`
	PolicyFullyCompacted bool `json:"policy_fully_compacted"`
	ByteMinimized        bool `json:"byte_minimized"`
}

CompactStorageStats is the single high-level report for TreeDB storage compaction and planning.

type CompactStorageUsage added in v0.6.0 

type CompactStorageUsage struct {
	Name          string `json:"name"`
	Path          string `json:"path"`
	Bytes         int64  `json:"bytes"`
	Files         int    `json:"files"`
	ZeroByteFiles int    `json:"zero_byte_files"`
}

CompactStorageUsage summarizes file usage for a storage domain.

type DB 

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

func Open 

func Open(opts Options) (*DB, error)

Open opens the database.

func (*DB) AcquireSnapshot 

func (db *DB) AcquireSnapshot() *Snapshot

AcquireSnapshot returns a new snapshot.

func (*DB) AppendCommandWALIntent added in v0.6.0 

func (db *DB) AppendCommandWALIntent(intent *CommandWALIntent, sync bool) (uint64, error)

AppendCommandWALIntent appends a deterministic command frame without publishing roots. It is used by cached public command-WAL writers that must make a typed frame replay-visible before inserting the mutation into memory. If the append succeeds but the post-append flush fails, the returned LSN is still the allocated LSN and the open handle is poisoned for recovery.

func (*DB) AppendCommandWALPayload added in v0.6.0 

func (db *DB) AppendCommandWALPayload(kind commitlog.CommandKind, scope commitlog.CommandScope, payloadFormat commitlog.PayloadFormat, payload []byte, sync bool) (uint64, error)

AppendCommandWALPayload appends a command-WAL frame without allocating a reusable intent token. It is for public cached write paths that only need the assigned LSN after the append succeeds.

func (*DB) AppendRawKVBatchPayloadCommandWAL added in v0.6.0 

func (db *DB) AppendRawKVBatchPayloadCommandWAL(payload []byte, sync bool) (uint64, error)

AppendRawKVBatchPayloadCommandWAL appends a prebuilt RawKVBatch payload as a command frame. It delegates post-append flushing to FlushCommandWAL(sync); relaxed durability flushes without fsync rather than forcing strict-sync semantics. If that post-append flush fails, the returned LSN is still the allocated LSN; callers must record the command as pending and treat subsequent command-WAL appends as recovery-required until the DB is reopened.

func (*DB) AppendRawKVBatchPayloadCommandWALTrusted added in v0.6.0 

func (db *DB) AppendRawKVBatchPayloadCommandWALTrusted(payload []byte, sync bool) (uint64, error)

AppendRawKVBatchPayloadCommandWALTrusted appends a prebuilt RawKVBatch payload that was constructed through a trusted canonical encoder/builder. It has the same post-append flush-failure contract as AppendRawKVBatchPayloadCommandWAL.

func (*DB) AppendRawKVCommandWALOrderedEntries added in v0.6.0 

func (db *DB) AppendRawKVCommandWALOrderedEntries(entries []batchpkg.Entry, sync bool) (uint64, error)

AppendRawKVCommandWALOrderedEntries appends a raw-KV command frame directly from entries that are already in the caller's required application order. The caller must keep entries and their key/value buffers immutable until this method returns.

func (*DB) AppendRawKVCommandWALOrderedEntryScan added in v0.6.0 

func (db *DB) AppendRawKVCommandWALOrderedEntryScan(scanEntries func(func(batchpkg.Entry) error) error, sync bool) (uint64, error)

AppendRawKVCommandWALOrderedEntryScan appends a raw-KV command frame by replaying already-ordered entries directly into the command encoder. The replay source must be deterministic and replayable because planning and writing scan it separately. Callers must keep replayed entry buffers immutable until this method returns.

func (*DB) AppendRawKVPointCommandWALTrusted added in v0.6.0 

func (db *DB) AppendRawKVPointCommandWALTrusted(op commitlog.RawKVOp, key, value []byte, sync bool) (uint64, error)

AppendRawKVPointCommandWALTrusted appends a caller-validated public raw KV point Set/Delete command. It is intended for public cached command-WAL writes after cached preflight has validated the user input and before visibility. It flushes while holding the command-journal lock; relaxed durability flushes without fsync rather than forcing strict-sync semantics. If that post-append flush fails, the returned LSN is still the allocated LSN; callers must record the command as pending and treat subsequent command-WAL appends as recovery-required until the DB is reopened.

func (*DB) AppendRawKVPointCommandWALTrustedWithRevision added in v0.6.1 

func (db *DB) AppendRawKVPointCommandWALTrustedWithRevision(op commitlog.RawKVOp, key, value []byte, revision page.EntryRevision, sync bool) (uint64, error)

AppendRawKVPointCommandWALTrustedWithRevision appends a caller-validated public raw-KV point command with native entry revision metadata.

func (*DB) AppendRawKVSingleCommandWAL added in v0.6.0 

func (db *DB) AppendRawKVSingleCommandWAL(op commitlog.RawKVOperation, sync bool) (uint64, error)

AppendRawKVSingleCommandWAL appends a one-operation RawKVBatch command frame. It flushes while holding the command-journal lock; relaxed durability flushes without fsync rather than forcing strict-sync semantics. If that post-append flush fails, the returned LSN is still the allocated LSN; callers must record the command as pending and treat subsequent command-WAL appends as recovery-required until the DB is reopened.

func (*DB) AppendStagedCommandWALIntent added in v0.6.0 

func (db *DB) AppendStagedCommandWALIntent(intent *CommandWALIntent, sync bool) (uint64, error)

AppendStagedCommandWALIntent appends an intent while the caller holds a higher-level staging guard observed by public command-WAL barriers.

func (*DB) AppendValueLogValues added in v0.6.0 

func (db *DB) AppendValueLogValues(values [][]byte) ([]page.ValuePtr, error)

AppendValueLogValues appends values through the configured persistent value log appender.

func (*DB) CheckCommandWALPublishReady added in v0.6.0 

func (db *DB) CheckCommandWALPublishReady() error

CheckCommandWALPublishReady verifies that this open handle can publish command-WAL coverage without forcing another writer flush. Public cached command-WAL writes already flush their command frame before visibility; the checkpoint publish path uses this for relaxed AppliedCommandLSN publication.

func (*DB) CheckStorageMaintenanceReady added in v0.6.0 

func (db *DB) CheckStorageMaintenanceReady() error

CheckStorageMaintenanceReady verifies this handle may run destructive storage maintenance such as GC, rewrite cleanup, or typed column asset reclamation. It returns ErrClosed for nil or closing handles, ErrReadOnly for read-only handles, and otherwise returns any command-WAL poison error that would make storage maintenance unsafe.

func (*DB) Checkpoint added in v0.6.0 

func (db *DB) Checkpoint() error

Checkpoint forces a durable boundary for previously-published backend state.

Unlike Commit, this does not publish a new root or advance CommitSeq. It is intended for callers that already made writes visible with relaxed durability and now need those writes durable on disk.

func (*DB) CleanupCommandWALCoveredSegments added in v0.6.0 

func (db *DB) CleanupCommandWALCoveredSegments(sync bool) error

CleanupCommandWALCoveredSegments removes command-WAL segments whose max LSN is covered by the current durable AppliedCommandLSN and that are not active.

func (*DB) Close 

func (db *DB) Close() error

func (*DB) ColumnAssetRootDir added in v0.6.0 

func (db *DB) ColumnAssetRootDir() string

ColumnAssetRootDir returns the isolated physical root for typed column asset manager payloads. It is separate from ordinary value_vlog and leaf_vlog.

func (*DB) CommandWALActiveBytes added in v0.6.0 

func (db *DB) CommandWALActiveBytes() int64

CommandWALActiveBytes reports the active command-WAL segment bytes accepted by the open writer, including command frames buffered for batch flush.

func (*DB) CommandWALBytes added in v0.6.0 

func (db *DB) CommandWALBytes() int64

CommandWALBytes reports command-WAL bytes currently present on disk, plus any active command frames buffered by the open writer. It intentionally counts covered non-active segments until cleanup removes them so byte-pressure checkpointing can bound total command-WAL growth rather than only the active file.

func (*DB) CommandWALEnabled added in v0.6.0 

func (db *DB) CommandWALEnabled() bool

func (*DB) CommandWALNextLSN added in v0.6.0 

func (db *DB) CommandWALNextLSN() uint64

CommandWALNextLSN reports the next LSN this handle would reserve.

func (*DB) Commit 

func (db *DB) Commit(newRootID uint64) error

Commit persists the new root (Sync=true by default). Note: This is usually called internally by Batch.Write or externally if manual root management. If manual, retired pages are unknown? `Commit` signature assumes manual root. If external user calls Commit, they might not know retired pages. We'll accept nil for retired if manual.

func (*DB) CompactIndex 

func (db *DB) CompactIndex() error

CompactIndex rewrites the entire B-Tree sequentially to the end of the file. This improves Full Scan performance by restoring physical locality. Note: This operation causes file growth as old pages are not immediately reclaimed (they are leaked to the freelist but not reused during this append-only build).

func (*DB) CompactStorage added in v0.6.0 

func (db *DB) CompactStorage(ctx context.Context, opts CompactStorageOptions) (CompactStorageStats, error)

CompactStorage runs the recommended full storage compaction sequence: value-log rewrite, value-log GC, leaf-generation pack, leaf-generation GC, index vacuum, final GC settle passes, empty value-log file cleanup, and a final audit.

func (*DB) CompactStorageLeafPageLogOwnerClassification added in v0.6.0 

func (db *DB) CompactStorageLeafPageLogOwnerClassification(lifecycle CompactStorageLifecycleState) CompactStorageLeafPageLogOwnerClassification

CompactStorageLeafPageLogOwnerClassification reports the compact-owner support category for the currently installed leaf-page log. The lifecycle argument is a modeled assumption used by the contract matrix; it does not prove the database is actually in that lifecycle state.

func (*DB) CompactStoragePlan added in v0.6.0 

func (db *DB) CompactStoragePlan(ctx context.Context, opts CompactStorageOptions) (CompactStorageStats, error)

CompactStoragePlan reports full storage compaction debt without mutating the database. It is safe for read-only opens.

func (*DB) Delete 

func (db *DB) Delete(key []byte) error

Delete removes a key.

func (*DB) DeleteSync 

func (db *DB) DeleteSync(key []byte) error

DeleteSync removes a key and syncs.

func (*DB) Dir added in v0.3.0 

func (db *DB) Dir() string

Dir returns the on-disk directory backing the DB.

func (*DB) DurabilityMode added in v0.6.0 

func (db *DB) DurabilityMode() DurabilityMode

DurabilityMode reports the backend durability mode configured at open.

func (*DB) FlushApplyPressureSnapshot added in v0.6.0 

func (db *DB) FlushApplyPressureSnapshot() FlushApplyPressureSnapshot

FlushApplyPressureSnapshot returns cumulative span/old-leaf pressure counters without constructing the full Stats map.

func (*DB) FlushApplyReducerPublishNs added in v0.6.0 

func (db *DB) FlushApplyReducerPublishNs() uint64

FlushApplyReducerPublishNs returns the cumulative root-reduce plus guarded publish time without constructing the full Stats map.

func (*DB) FlushCommandWAL added in v0.6.0 

func (db *DB) FlushCommandWAL(sync bool) error

FlushCommandWAL flushes the command WAL writer. When sync is true, durable modes fsync the command WAL; DurabilityWALOnRelaxed intentionally downgrades this to a flush-to-kernel boundary to preserve relaxed-sync semantics.

func (*DB) FragmentationReport 

func (db *DB) FragmentationReport() (map[string]string, error)

FragmentationReport returns best-effort structural stats about the user index that help diagnose scan regressions after churn.

func (*DB) Get 

func (db *DB) Get(key []byte) ([]byte, error)

Get returns the value for a key.

Semantics: Returns a safe copy of the value.

func (*DB) GetAppend 

func (db *DB) GetAppend(key, dst []byte) ([]byte, error)

GetAppend appends the value for the key to dst and returns the new slice. If the key is not found, it returns dst and ErrKeyNotFound.

func (*DB) GetMany added in v0.4.0 

func (db *DB) GetMany(keys [][]byte) ([][]byte, error)

GetMany returns values for keys.

Semantics: Returns safe copies of values. Missing keys are returned as nil entries with no error.

func (*DB) GetManyParallelPlan added in v0.4.0 

func (db *DB) GetManyParallelPlan(keyCount int) (workers int, parallel bool)

GetManyParallelPlan reports how this backend would schedule GetMany for the provided key count.

func (*DB) GetManyView added in v0.6.0 

func (db *DB) GetManyView(keys [][]byte, fn GetManyViewFunc) error

GetManyView calls fn once for each key with a read-only value view. Missing keys are reported with found=false and value=nil. Callback values are valid only until fn returns and must be copied before retaining. Large batches may invoke callbacks concurrently; callers that mutate shared state must synchronize it. If fn returns an error, iteration stops best-effort and that error is returned; callbacks already invoked are not retried.

func (*DB) GetUnsafe 

func (db *DB) GetUnsafe(key []byte) ([]byte, error)

GetUnsafe returns the value for a key.

Semantics: Returns a safe copy of the value. For zero-copy views tied to a snapshot lifetime, use Snapshot.GetUnsafe.

func (*DB) GetVersioned added in v0.6.1 

func (db *DB) GetVersioned(key []byte) ([]byte, page.EntryRevision, error)

GetVersioned returns the value for key plus the native entry revision stored beside that value. Missing keys return a nil value, LegacyEntryRevision, and nil error; tombstones return a nil value with their tombstone revision.

func (*DB) GetVersionedAppend added in v0.6.1 

func (db *DB) GetVersionedAppend(key, dst []byte) ([]byte, page.EntryRevision, error)

GetVersionedAppend appends the value for key to dst and returns the native entry revision stored with the visible entry. Missing/tombstoned keys return dst and tree.ErrKeyNotFound; tombstones preserve their stored revision.

func (*DB) Has 

func (db *DB) Has(key []byte) (bool, error)

Has checks if a key exists.

func (*DB) HasValueLogAppender added in v0.6.0 

func (db *DB) HasValueLogAppender() bool

HasValueLogAppender reports whether native-root callers can append user values to the persistent value log.

func (*DB) InlineThreshold 

func (db *DB) InlineThreshold() int

func (*DB) InlineThresholdForKey added in v0.4.0 

func (db *DB) InlineThresholdForKey(key []byte) int

func (*DB) IsClosing added in v0.6.0 

func (db *DB) IsClosing() bool

IsClosing reports whether the database is closing. It returns true if db is nil.

func (*DB) Iterator 

func (db *DB) Iterator(start, end []byte) (iterator.UnsafeIterator, error)

Iterator returns an iterator.

func (*DB) IteratorWithOptions added in v0.4.0 

func (db *DB) IteratorWithOptions(start, end []byte, opts IteratorOptions) (iterator.UnsafeIterator, error)

IteratorWithOptions returns an iterator with explicit value materialization controls.

func (*DB) LeafGenerationGC added in v0.5.0 

func (db *DB) LeafGenerationGC(ctx context.Context, opts LeafGenerationGCOptions) (LeafGenerationGCStats, error)

func (*DB) LeafGenerationPack added in v0.5.0 

func (db *DB) LeafGenerationPack(ctx context.Context, opts LeafGenerationPackOptions) (stats LeafGenerationPackStats, err error)

LeafGenerationPack rewrites live leaf-log pages from sealed source generations into a fresh leaf-log output so the old generations can later be reclaimed by ordinary generation GC.

func (*DB) LeafGenerationPackFromPlan added in v0.5.0 

func (db *DB) LeafGenerationPackFromPlan(ctx context.Context, opts LeafGenerationPackFromPlanOptions) (LeafGenerationPackStats, error)

LeafGenerationPackFromPlan computes the current plan, selects a bounded candidate prefix, then packs those sealed generations.

func (*DB) LeafGenerationPackRunOnce added in v0.5.0 

func (db *DB) LeafGenerationPackRunOnce(ctx context.Context, opts LeafGenerationPackFromPlanOptions) (LeafGenerationPackRunOnceStats, error)

LeafGenerationPackRunOnce computes the current plan, applies bounded selection, and either runs one pack pass or reports why it skipped.

func (*DB) LeafGenerationPlan added in v0.5.0 

func (db *DB) LeafGenerationPlan(ctx context.Context, opts LeafGenerationPlanOptions) (LeafGenerationPlan, error)

LeafGenerationPlan estimates reclaim opportunities for sealed leaf generations by scanning the current live tree once and attributing reachable leaf-log pages back to manifest generations.

func (*DB) LockCommandWALPublish added in v0.6.0 

func (db *DB) LockCommandWALPublish() func()

LockCommandWALPublish serializes a higher-level command-WAL publish without running raw-publish barriers. Callers must arrange any higher-level draining required before appending or publishing under the returned lock.

func (*DB) LockCommandWALPublishWithBarriers added in v0.6.0 

func (db *DB) LockCommandWALPublishWithBarriers() (func(), error)

LockCommandWALPublishWithBarriers serializes a public command-WAL append and drains registered staged-command barriers before the caller appends a frame.

func (*DB) LockCommandWALStaging added in v0.6.0 

func (db *DB) LockCommandWALStaging() func()

LockCommandWALStaging prevents any command-WAL append/publish path from starting while a higher-level command has appended a frame but not yet made it publishable.

func (*DB) MarkCommandWALIntentRecoveryRequired added in v0.6.0 

func (db *DB) MarkCommandWALIntentRecoveryRequired(intent *CommandWALIntent)

MarkCommandWALIntentRecoveryRequired marks this open handle as requiring recovery after a command frame was appended but the caller could not make the corresponding mutation visible in memory or durable roots. Reopen recovery may apply the frame, so retrying on the same handle can create command-WAL gaps.

func (*DB) MarkCommandWALRecoveryRequired added in v0.6.0 

func (db *DB) MarkCommandWALRecoveryRequired()

MarkCommandWALRecoveryRequired marks this open handle as requiring recovery after a public command-WAL frame was appended but the caller could not prove that the matching physical mutation became visible/publishable on this handle. Reopen recovery may apply the frame, so further command appends and AppliedCommandLSN publishes must fail closed.

func (*DB) MarkValueLogZombie 

func (db *DB) MarkValueLogZombie(id uint32) error

MarkValueLogZombie marks a value-log segment as zombie so it can be removed once all snapshots release it.

func (*DB) MinPinnedSnapshotCommitSeq added in v0.6.0 

func (db *DB) MinPinnedSnapshotCommitSeq() uint64

MinPinnedSnapshotCommitSeq returns the oldest commit sequence currently held by any active snapshot reader across the current and still-tracked retired index generations. In-flight snapshot acquisitions conservatively return 0 because they may have loaded a view that is not registered yet. math.MaxUint64 means no snapshot reader is pinned.

func (*DB) NewBatch 

func (db *DB) NewBatch() batch.Interface

func (*DB) NewBatchWithSize 

func (db *DB) NewBatchWithSize(size int) batch.Interface

NewBatchWithSize accepts the public cosmos-db style size hint. Small values are treated like exact entry reserves; larger values are normalized as approximate byte budgets and capped to avoid preallocating one entry per byte. The normalization is intentionally discontinuous at the cutover: `publicBatchHintExactEntryReserveMax` still means "reserve that many entries", while the next value is treated as a byte budget and normalized downward.

func (*DB) NewCommandWALIntent added in v0.6.0 

func (db *DB) NewCommandWALIntent(kind commitlog.CommandKind, scope commitlog.CommandScope, payloadFormat commitlog.PayloadFormat, payload []byte) (*CommandWALIntent, error)

func (*DB) NewCommandWALReplayIntent added in v0.6.0 

func (db *DB) NewCommandWALReplayIntent(env commitlog.CommandEnvelope) (*CommandWALIntent, error)

func (*DB) NewPhysicalBatch added in v0.6.0 

func (db *DB) NewPhysicalBatch() batch.Interface

NewPhysicalBatch creates a backend batch that mutates the physical index without appending a RawKVBatch command frame. It is for higher-level command WAL executors that have already appended their logical command frames before making writes visible through the cached layer.

func (*DB) NewPhysicalBatchWithSize added in v0.6.0 

func (db *DB) NewPhysicalBatchWithSize(size int) batch.Interface

NewPhysicalBatchWithSize is NewPhysicalBatch with the public size hint.

func (*DB) NewRawKVCommandWALIntentFromOrderedEntries added in v0.6.0 

func (db *DB) NewRawKVCommandWALIntentFromOrderedEntries(entries []batchpkg.Entry) (*CommandWALIntent, error)

NewRawKVCommandWALIntentFromOrderedEntries builds a public raw-KV command intent from entries that are already in the caller's required application order. Unlike prepareRawKVCommandWALIntent, this does not sort or compact point ops; public cached batches rely on replay order to preserve mixed set/delete/range-delete semantics.

func (*DB) NewTrustedCommandWALIntent added in v0.6.0 

func (db *DB) NewTrustedCommandWALIntent(kind commitlog.CommandKind, scope commitlog.CommandScope, payloadFormat commitlog.PayloadFormat, payload []byte) (*CommandWALIntent, error)

NewTrustedCommandWALIntent creates a command-WAL intent for payload bytes constructed through a canonical commitlog encoder. The append path still validates command identity and size, but it skips payload decoding because the caller owns that construction boundary.

func (*DB) NoteLeafGenerationRecordLength added in v0.5.0 

func (db *DB) NoteLeafGenerationRecordLength(ptr page.ValuePtr)

func (*DB) OrderedRootSpanNativeTriageSnapshot added in v0.6.0 

func (db *DB) OrderedRootSpanNativeTriageSnapshot() []OrderedRootSpanNativeTriageRow

OrderedRootSpanNativeTriageSnapshot returns the ordered-root-specific route support matrix for the current DB admission decision. It is a support surface: benchmark/report plumbing should consume these rows instead of inferring ordered-root proof from raw flush_apply span-native counters.

func (*DB) Pager 

func (db *DB) Pager() *pager.Pager

Getters

func (*DB) PlanFlushSpanRun added in v0.6.0 

func (db *DB) PlanFlushSpanRun(req FlushSpanRunPlanRequest) (FlushSpanRunMetadata, error)

PlanFlushSpanRun plans exact target-leaf spans for an already-canonical flush run. It is side-effect-free: it captures the current root, runs the read-only prepare pass against the supplied point/range operations, and returns M8/M9 span-run metadata for cache-layer chunk planning and future span-native jobs.

func (*DB) PlanFlushSpanRunChunks added in v0.6.0 

func (db *DB) PlanFlushSpanRunChunks(req FlushSpanRunPlanRequest, maxPointOpsPerChunk int) (FlushSpanRunChunkPlan, error)

PlanFlushSpanRunChunks plans target-leaf-aware backend chunks for an already-canonical flush run without copying every read-only span into the M8 exported span struct. This is the cache flush hot-path form: it still runs the same side-effect-free read-only prepare pass and emits aggregate target-span counters plus split evidence.

func (*DB) PrepareReadOnlyApplyPlan added in v0.6.0 

func (db *DB) PrepareReadOnlyApplyPlan(b *Batch, opts ReadOnlyApplyPlanOptions) (ReadOnlyApplyPlan, error)

PrepareReadOnlyApplyPlan runs the reusable read-only prepare/leaf-span planning contract against the current user root. It is default-off and is intended for tests, benchmark evidence, and future cached flush/ordered-root apply integrations.

func (*DB) Print 

func (db *DB) Print() error

Print debugs the tree (simple dump).

func (*DB) Prune 

func (db *DB) Prune()

Prune reclaims pages from the graveyard.

func (*DB) PublishCommandWALAppliedLSN added in v0.6.0 

func (db *DB) PublishCommandWALAppliedLSN(appliedLSN uint64, covered []CommandWALLSNRange, sync bool) error

PublishCommandWALAppliedLSN publishes the current roots with an advanced AppliedCommandLSN. Callers must only pass ranges for command frames already reflected in the current roots.

func (*DB) PublishCommandWALNoop added in v0.6.0 

func (db *DB) PublishCommandWALNoop(intent *CommandWALIntent, sync bool) error

func (*DB) PublishOrderedRootDeltaBatchGroupWithCommandWALAndSystemDeltaBuilder added in v0.6.0 

func (db *DB) PublishOrderedRootDeltaBatchGroupWithCommandWALAndSystemDeltaBuilder(ordered []OrderedRootDeltaBatchPublishInput, intent *CommandWALIntent, buildSystemDeltaIter OrderedRootGroupSystemBuilder) (uint64, []uint64, error)

PublishOrderedRootDeltaBatchGroupWithCommandWALAndSystemDeltaBuilder is like PublishOrderedRootDeltaBatchGroupWithSystemDeltaBuilder, but the root publish is covered by the supplied command-WAL intent.

func (*DB) PublishOrderedRootDeltaBatchGroupWithCommandWALContextAndSystemDeltaBuilder added in v0.6.0 

func (db *DB) PublishOrderedRootDeltaBatchGroupWithCommandWALContextAndSystemDeltaBuilder(ordered []OrderedRootDeltaBatchPublishInput, intent *CommandWALIntent, buildSystemDeltaIter OrderedRootGroupCommandWALSystemBuilder) (uint64, []uint64, error)

PublishOrderedRootDeltaBatchGroupWithCommandWALContextAndSystemDeltaBuilder is like PublishOrderedRootDeltaBatchGroupWithCommandWALAndSystemDeltaBuilder, but the system-delta builder receives the command-WAL LSN assigned to this publish.

func (*DB) PublishOrderedRootDeltaBatchGroupWithCommandWALContextRootBuilderAndSystemDeltaBuilder added in v0.6.0 

func (db *DB) PublishOrderedRootDeltaBatchGroupWithCommandWALContextRootBuilderAndSystemDeltaBuilder(ordered []OrderedRootDeltaBatchPublishInput, intent *CommandWALIntent, buildContextDeltas OrderedRootDeltaBatchGroupCommandWALDeltaBuilder, buildSystemDeltaIter OrderedRootGroupCommandWALSystemBuilder) (uint64, []uint64, error)

PublishOrderedRootDeltaBatchGroupWithCommandWALContextRootBuilderAndSystemDeltaBuilder is like PublishOrderedRootDeltaBatchGroupWithCommandWALContextAndSystemDeltaBuilder, but may append additional batch-materialized root deltas after the command-WAL LSN is assigned. The returned rootIDs slice contains the original ordered inputs first, then any context-built roots in returned order, so it may be longer than len(ordered).

func (*DB) PublishOrderedRootDeltaBatchGroupWithPreflightAndSystemDeltaBuilder added in v0.6.0 

func (db *DB) PublishOrderedRootDeltaBatchGroupWithPreflightAndSystemDeltaBuilder(ordered []OrderedRootDeltaBatchPublishInput, preflight OrderedRootGroupPreflight, buildSystemDeltaIter OrderedRootGroupSystemBuilder) (uint64, []uint64, error)

PublishOrderedRootDeltaBatchGroupWithPreflightAndSystemDeltaBuilder is like PublishOrderedRootDeltaBatchGroupWithSystemDeltaBuilder, but runs preflight under the DB write lock before applying root-local deltas.

func (*DB) PublishOrderedRootDeltaBatchGroupWithPreflightCommandWALAndSystemDeltaBuilder added in v0.6.0 

func (db *DB) PublishOrderedRootDeltaBatchGroupWithPreflightCommandWALAndSystemDeltaBuilder(ordered []OrderedRootDeltaBatchPublishInput, preflight OrderedRootGroupPreflight, intent *CommandWALIntent, buildSystemDeltaIter OrderedRootGroupSystemBuilder) (uint64, []uint64, error)

PublishOrderedRootDeltaBatchGroupWithPreflightCommandWALAndSystemDeltaBuilder is like PublishOrderedRootDeltaBatchGroupWithCommandWALAndSystemDeltaBuilder, but runs preflight under the DB write lock before appending the command-WAL frame or applying root-local deltas.

func (*DB) PublishOrderedRootDeltaBatchGroupWithPreflightCommandWALContextAndSystemDeltaBuilder added in v0.6.0 

func (db *DB) PublishOrderedRootDeltaBatchGroupWithPreflightCommandWALContextAndSystemDeltaBuilder(ordered []OrderedRootDeltaBatchPublishInput, preflight OrderedRootGroupPreflight, intent *CommandWALIntent, buildSystemDeltaIter OrderedRootGroupCommandWALSystemBuilder) (uint64, []uint64, error)

PublishOrderedRootDeltaBatchGroupWithPreflightCommandWALContextAndSystemDeltaBuilder is like PublishOrderedRootDeltaBatchGroupWithCommandWALContextAndSystemDeltaBuilder, but runs preflight before the command frame is appended.

func (*DB) PublishOrderedRootDeltaBatchGroupWithPreflightCommandWALContextRootBuilderAndSystemDeltaBuilder added in v0.6.0 

func (db *DB) PublishOrderedRootDeltaBatchGroupWithPreflightCommandWALContextRootBuilderAndSystemDeltaBuilder(ordered []OrderedRootDeltaBatchPublishInput, preflight OrderedRootGroupPreflight, intent *CommandWALIntent, buildContextDeltas OrderedRootDeltaBatchGroupCommandWALDeltaBuilder, buildSystemDeltaIter OrderedRootGroupCommandWALSystemBuilder) (uint64, []uint64, error)

PublishOrderedRootDeltaBatchGroupWithPreflightCommandWALContextRootBuilderAndSystemDeltaBuilder is like PublishOrderedRootDeltaBatchGroupWithCommandWALContextRootBuilderAndSystemDeltaBuilder, but runs preflight before the command frame is appended. The returned rootIDs slice contains the original ordered inputs first, then any context-built roots in returned order, so it may be longer than len(ordered).

func (*DB) PublishOrderedRootDeltaBatchGroupWithSystemDeltaBuilder added in v0.6.0 

func (db *DB) PublishOrderedRootDeltaBatchGroupWithSystemDeltaBuilder(ordered []OrderedRootDeltaBatchPublishInput, buildSystemDeltaIter OrderedRootGroupSystemBuilder) (uint64, []uint64, error)

PublishOrderedRootDeltaBatchGroupWithSystemDeltaBuilder is like PublishOrderedRootDeltaGroupWithSystemDeltaBuilder, but the root-local mutation batches have already been materialized by the caller. This lets collection flush paths do iterator-to-batch work before entering the DB write critical section.

func (*DB) PublishOrderedRootDeltaGroupWithCommandWALAndSystemDeltaBuilder added in v0.6.0 

func (db *DB) PublishOrderedRootDeltaGroupWithCommandWALAndSystemDeltaBuilder(ordered []OrderedRootDeltaPublishInput, intent *CommandWALIntent, buildSystemDeltaIter OrderedRootGroupSystemBuilder) (uint64, []uint64, error)

PublishOrderedRootDeltaGroupWithCommandWALAndSystemDeltaBuilder applies the grouped root delta under one command-WAL LSN. The command frame is appended while commit serialization is held and before publishing the metadata root tuple that advances AppliedCommandLSN.

func (*DB) PublishOrderedRootDeltaGroupWithCommandWALContextAndSystemDeltaBuilder added in v0.6.0 

func (db *DB) PublishOrderedRootDeltaGroupWithCommandWALContextAndSystemDeltaBuilder(ordered []OrderedRootDeltaPublishInput, intent *CommandWALIntent, buildSystemDeltaIter OrderedRootGroupCommandWALSystemBuilder) (uint64, []uint64, error)

PublishOrderedRootDeltaGroupWithCommandWALContextAndSystemDeltaBuilder is like PublishOrderedRootDeltaGroupWithCommandWALAndSystemDeltaBuilder, but the system-delta builder receives the command-WAL LSN assigned to this publish. The command frame is appended before any roots are published; if later root or system publication fails, the open handle is poisoned and must be reopened for recovery before more command-WAL publishes can proceed.

func (*DB) PublishOrderedRootDeltaGroupWithCommandWALContextRootBuilderAndSystemDeltaBuilder added in v0.6.0 

func (db *DB) PublishOrderedRootDeltaGroupWithCommandWALContextRootBuilderAndSystemDeltaBuilder(ordered []OrderedRootDeltaPublishInput, intent *CommandWALIntent, buildContextDeltas OrderedRootGroupCommandWALDeltaBuilder, buildSystemDeltaIter OrderedRootGroupCommandWALSystemBuilder) (uint64, []uint64, error)

PublishOrderedRootDeltaGroupWithCommandWALContextRootBuilderAndSystemDeltaBuilder is like PublishOrderedRootDeltaGroupWithCommandWALContextAndSystemDeltaBuilder, but may append additional root-local mutation streams after the command-WAL LSN is assigned. The returned rootIDs slice contains the original ordered inputs first, then any context-built roots in returned order, so it may be longer than len(ordered).

func (*DB) PublishOrderedRootDeltaGroupWithPreflightAndSystemDeltaBuilder added in v0.6.0 

func (db *DB) PublishOrderedRootDeltaGroupWithPreflightAndSystemDeltaBuilder(ordered []OrderedRootDeltaPublishInput, preflight OrderedRootGroupPreflight, buildSystemDeltaIter OrderedRootGroupSystemBuilder) (uint64, []uint64, error)

PublishOrderedRootDeltaGroupWithPreflightAndSystemDeltaBuilder is like PublishOrderedRootDeltaGroupWithSystemDeltaBuilder, but runs preflight under the DB write lock before applying root-local deltas.

func (*DB) PublishOrderedRootDeltaGroupWithPreflightCommandWALContextAndSystemDeltaBuilder added in v0.6.0 

func (db *DB) PublishOrderedRootDeltaGroupWithPreflightCommandWALContextAndSystemDeltaBuilder(ordered []OrderedRootDeltaPublishInput, preflight OrderedRootGroupPreflight, intent *CommandWALIntent, buildSystemDeltaIter OrderedRootGroupCommandWALSystemBuilder) (uint64, []uint64, error)

PublishOrderedRootDeltaGroupWithPreflightCommandWALContextAndSystemDeltaBuilder is like PublishOrderedRootDeltaGroupWithCommandWALContextAndSystemDeltaBuilder, but runs preflight before the command frame is appended.

func (*DB) PublishOrderedRootDeltaGroupWithPreflightCommandWALContextRootBuilderAndSystemDeltaBuilder added in v0.6.0 

func (db *DB) PublishOrderedRootDeltaGroupWithPreflightCommandWALContextRootBuilderAndSystemDeltaBuilder(ordered []OrderedRootDeltaPublishInput, preflight OrderedRootGroupPreflight, intent *CommandWALIntent, buildContextDeltas OrderedRootGroupCommandWALDeltaBuilder, buildSystemDeltaIter OrderedRootGroupCommandWALSystemBuilder) (uint64, []uint64, error)

PublishOrderedRootDeltaGroupWithPreflightCommandWALContextRootBuilderAndSystemDeltaBuilder is like PublishOrderedRootDeltaGroupWithCommandWALContextRootBuilderAndSystemDeltaBuilder, but runs preflight before the command frame is appended. The returned rootIDs slice contains the original ordered inputs first, then any context-built roots in returned order, so it may be longer than len(ordered).

func (*DB) PublishOrderedRootDeltaGroupWithPreflightMaintenanceSystemDeltaBuilder added in v0.6.0 

func (db *DB) PublishOrderedRootDeltaGroupWithPreflightMaintenanceSystemDeltaBuilder(plan StorageMaintenancePlan, ordered []StorageMaintenanceRootDeltaPublishInput, preflight OrderedRootGroupPreflight, buildSystemDeltaIter OrderedRootGroupSystemBuilder) (uint64, []uint64, error)

PublishOrderedRootDeltaGroupWithPreflightMaintenanceSystemDeltaBuilder is like PublishOrderedRootDeltaGroupWithPreflightAndSystemDeltaBuilder, but permits TreeDB-internal storage-maintenance root rewrites while command-WAL mode is enabled. Callers must provide an internal maintenance plan and at least one maintenance root-delta input. System-only logical changes must use command-WAL-covered publish APIs. This path does not append or advance a command-WAL frame.

func (*DB) PublishOrderedRootDeltaGroupWithSystemBuilder added in v0.6.0 

func (db *DB) PublishOrderedRootDeltaGroupWithSystemBuilder(ordered []OrderedRootDeltaPublishInput, buildSystemIter OrderedRootGroupSystemBuilder) (newSystemRoot uint64, rootIDs []uint64, err error)

PublishOrderedRootDeltaGroupWithSystemBuilder applies root-local mutation streams to non-system roots, then builds and commits a system-root iterator that can persist the produced root IDs in the same backend commit.

func (*DB) PublishOrderedRootDeltaGroupWithSystemDeltaBuilder added in v0.6.0 

func (db *DB) PublishOrderedRootDeltaGroupWithSystemDeltaBuilder(ordered []OrderedRootDeltaPublishInput, buildSystemDeltaIter OrderedRootGroupSystemBuilder) (uint64, []uint64, error)

PublishOrderedRootDeltaGroupWithSystemDeltaBuilder applies root-local mutation streams to non-system roots, then applies a root-local mutation stream to the system root. The system delta should contain only changed system-root entries; omitted system entries are preserved.

func (*DB) PublishOrderedRootGroup added in v0.6.0 

func (db *DB) PublishOrderedRootGroup(systemIter iterator.UnsafeIterator, ordered []OrderedRootPublishInput) (uint64, []uint64, error)

PublishOrderedRootGroup builds and commits a mixed system/non-system root group in one backend commit. Non-system roots are built from ordered iterators and become durable when the grouped commit finalizes.

func (*DB) PublishOrderedRootGroupWithSystemBuilder added in v0.6.0 

func (db *DB) PublishOrderedRootGroupWithSystemBuilder(ordered []OrderedRootPublishInput, buildSystemIter OrderedRootGroupSystemBuilder) (uint64, []uint64, error)

PublishOrderedRootGroupWithSystemBuilder builds non-system roots first, then calls buildSystemIter with the produced root IDs and commits the system root plus all non-system roots in one backend commit. This is intended for callers whose system descriptors must store the new root IDs produced by the group.

func (*DB) PublishOrderedRootIterator added in v0.6.0 

func (db *DB) PublishOrderedRootIterator(baseRoot uint64, iter iterator.UnsafeIterator) (uint64, error)

PublishOrderedRootIterator builds and commits a non-meta root from an ordered iterator while preserving the current user and system roots in the commit.

func (*DB) PublishStagedCommandWALNoop added in v0.6.0 

func (db *DB) PublishStagedCommandWALNoop(intent *CommandWALIntent, sync bool) error

PublishStagedCommandWALNoop publishes an already-staged command-WAL no-op. Callers must hold a higher-level raw publish or staging guard from the frame append through this publish call.

func (*DB) PublishStagedOrderedRootDeltaBatchGroupWithCommandWALAndSystemDeltaBuilder added in v0.6.0 

func (db *DB) PublishStagedOrderedRootDeltaBatchGroupWithCommandWALAndSystemDeltaBuilder(ordered []OrderedRootDeltaBatchPublishInput, intent *CommandWALIntent, buildSystemDeltaIter OrderedRootGroupSystemBuilder) (uint64, []uint64, error)

PublishStagedOrderedRootDeltaBatchGroupWithCommandWALAndSystemDeltaBuilder is like PublishOrderedRootDeltaBatchGroupWithCommandWALAndSystemDeltaBuilder, but assumes the caller already holds the command-WAL raw publish lock.

func (*DB) PublishStagedOrderedRootDeltaBatchGroupWithCommandWALContextRootBuilderAndSystemDeltaBuilder added in v0.6.0 

func (db *DB) PublishStagedOrderedRootDeltaBatchGroupWithCommandWALContextRootBuilderAndSystemDeltaBuilder(ordered []OrderedRootDeltaBatchPublishInput, intent *CommandWALIntent, buildContextDeltas OrderedRootDeltaBatchGroupCommandWALDeltaBuilder, buildSystemDeltaIter OrderedRootGroupCommandWALSystemBuilder) (uint64, []uint64, error)

PublishStagedOrderedRootDeltaBatchGroupWithCommandWALContextRootBuilderAndSystemDeltaBuilder is like PublishOrderedRootDeltaBatchGroupWithCommandWALContextRootBuilderAndSystemDeltaBuilder, but assumes the caller already holds the command-WAL raw publish lock.

func (*DB) PublishStagedOrderedRootDeltaBatchGroupWithPreflightCommandWALAndSystemDeltaBuilder added in v0.6.0 

func (db *DB) PublishStagedOrderedRootDeltaBatchGroupWithPreflightCommandWALAndSystemDeltaBuilder(ordered []OrderedRootDeltaBatchPublishInput, preflight OrderedRootGroupPreflight, intent *CommandWALIntent, buildSystemDeltaIter OrderedRootGroupSystemBuilder) (uint64, []uint64, error)

PublishStagedOrderedRootDeltaBatchGroupWithPreflightCommandWALAndSystemDeltaBuilder is like PublishOrderedRootDeltaBatchGroupWithPreflightCommandWALAndSystemDeltaBuilder, but assumes the caller already holds the command-WAL raw publish lock.

func (*DB) PublishStagedOrderedRootDeltaBatchGroupWithPreflightCommandWALContextRootBuilderAndSystemDeltaBuilder added in v0.6.0 

func (db *DB) PublishStagedOrderedRootDeltaBatchGroupWithPreflightCommandWALContextRootBuilderAndSystemDeltaBuilder(ordered []OrderedRootDeltaBatchPublishInput, preflight OrderedRootGroupPreflight, intent *CommandWALIntent, buildContextDeltas OrderedRootDeltaBatchGroupCommandWALDeltaBuilder, buildSystemDeltaIter OrderedRootGroupCommandWALSystemBuilder) (uint64, []uint64, error)

PublishStagedOrderedRootDeltaBatchGroupWithPreflightCommandWALContextRootBuilderAndSystemDeltaBuilder is like PublishOrderedRootDeltaBatchGroupWithPreflightCommandWALContextRootBuilderAndSystemDeltaBuilder, but assumes the caller already holds the command-WAL raw publish lock.

func (*DB) PublishStagedOrderedRootDeltaGroupWithCommandWALAndSystemDeltaBuilder added in v0.6.0 

func (db *DB) PublishStagedOrderedRootDeltaGroupWithCommandWALAndSystemDeltaBuilder(ordered []OrderedRootDeltaPublishInput, intent *CommandWALIntent, buildSystemDeltaIter OrderedRootGroupSystemBuilder) (uint64, []uint64, error)

PublishStagedOrderedRootDeltaGroupWithCommandWALAndSystemDeltaBuilder is like PublishOrderedRootDeltaGroupWithCommandWALAndSystemDeltaBuilder, but assumes the caller already holds the command-WAL raw publish lock.

func (*DB) PublishStagedOrderedRootDeltaGroupWithCommandWALContextRootBuilderAndSystemDeltaBuilder added in v0.6.0 

func (db *DB) PublishStagedOrderedRootDeltaGroupWithCommandWALContextRootBuilderAndSystemDeltaBuilder(ordered []OrderedRootDeltaPublishInput, intent *CommandWALIntent, buildContextDeltas OrderedRootGroupCommandWALDeltaBuilder, buildSystemDeltaIter OrderedRootGroupCommandWALSystemBuilder) (uint64, []uint64, error)

PublishStagedOrderedRootDeltaGroupWithCommandWALContextRootBuilderAndSystemDeltaBuilder is like PublishOrderedRootDeltaGroupWithCommandWALContextRootBuilderAndSystemDeltaBuilder, but assumes the caller already holds the command-WAL raw publish lock.

func (*DB) PublishStagedOrderedRootDeltaGroupWithPreflightCommandWALContextAndSystemDeltaBuilder added in v0.6.0 

func (db *DB) PublishStagedOrderedRootDeltaGroupWithPreflightCommandWALContextAndSystemDeltaBuilder(ordered []OrderedRootDeltaPublishInput, preflight OrderedRootGroupPreflight, intent *CommandWALIntent, buildSystemDeltaIter OrderedRootGroupCommandWALSystemBuilder) (uint64, []uint64, error)

PublishStagedOrderedRootDeltaGroupWithPreflightCommandWALContextAndSystemDeltaBuilder is like PublishOrderedRootDeltaGroupWithPreflightCommandWALContextAndSystemDeltaBuilder, but assumes the caller already holds the command-WAL raw publish lock.

func (*DB) PublishStagedOrderedRootDeltaGroupWithPreflightCommandWALContextRootBuilderAndSystemDeltaBuilder added in v0.6.0 

func (db *DB) PublishStagedOrderedRootDeltaGroupWithPreflightCommandWALContextRootBuilderAndSystemDeltaBuilder(ordered []OrderedRootDeltaPublishInput, preflight OrderedRootGroupPreflight, intent *CommandWALIntent, buildContextDeltas OrderedRootGroupCommandWALDeltaBuilder, buildSystemDeltaIter OrderedRootGroupCommandWALSystemBuilder) (uint64, []uint64, error)

PublishStagedOrderedRootDeltaGroupWithPreflightCommandWALContextRootBuilderAndSystemDeltaBuilder is like PublishOrderedRootDeltaGroupWithPreflightCommandWALContextRootBuilderAndSystemDeltaBuilder, but assumes the caller already holds the command-WAL raw publish lock.

func (*DB) PublishSystemRootIterator added in v0.6.0 

func (db *DB) PublishSystemRootIterator(iter iterator.UnsafeIterator) (uint64, error)

PublishSystemRootIterator builds and commits a new system root from an ordered iterator without detached-batch replay. The current user root is preserved across the commit.

func (*DB) RefreshValueLogSet added in v0.3.0 

func (db *DB) RefreshValueLogSet() error

RefreshValueLogSet publishes a new DBState with the current value-log set (excluding zombies) without creating a new commit.

func (*DB) RegisterCloseHook added in v0.6.0 

func (db *DB) RegisterCloseHook(hook func() error) func()

RegisterCloseHook registers a callback that runs before Close marks the DB as closing, while normal write/publish APIs are still available.

func (*DB) RegisterCloseHookBefore added in v0.6.0 

func (db *DB) RegisterCloseHookBefore(hook func() error) func()

RegisterCloseHookBefore registers a callback that runs before ordinary close hooks. It is intended for high-level owners that must flush buffered state while lower-level resources registered during DB open are still available.

func (*DB) RegisterCloseHookIfOpen added in v0.6.0 

func (db *DB) RegisterCloseHookIfOpen(hook func() error) (func(), bool)

RegisterCloseHookIfOpen is like RegisterCloseHook, but also reports whether the hook was retained. Callers that attach external state to the hook can use this to avoid leaks when registration races DB close.

func (*DB) RegisterCloseHookIfOpenAfter added in v0.6.0 

func (db *DB) RegisterCloseHookIfOpenAfter(setup func() bool, hook func() error) (func(), bool)

RegisterCloseHookIfOpenAfter runs setup while close-hook registration is serialized with RunCloseHooks, then registers hook if setup returns true. The returned bool reports that the DB was still accepting close-hook registration and setup, if any, ran inside that accepted registration window. If setup returns false, no hook is retained even though the registration window was accepted.

func (*DB) RegisterCommandWALRawPublishBarrier added in v0.6.0 

func (db *DB) RegisterCommandWALRawPublishBarrier(hook func() error) func()

RegisterCommandWALRawPublishBarrier registers a callback that raw command-WAL writers must run before appending a new raw KV command frame. Higher-level command executors use this to drain already-appended staged command frames so raw KV publishes cannot create AppliedCommandLSN gaps. Hooks run while the command-WAL publish mutex is held, so they must not append command-WAL frames, take a staging lock, or call paths that may do either. The returned unregister function waits for in-flight hooks and must not be called from the hook itself.

func (*DB) RegisterValueLogSegment added in v0.4.0 

func (db *DB) RegisterValueLogSegment(path string, fileID uint32) error

RegisterValueLogSegment registers a newly created value-log segment with the backend read manager without scanning the filesystem. Cached mode uses this when it rotates the shared value log so outer-leaf commits can publish a current ValueLogSet via CurrentSetNoRefresh.

func (*DB) RegisterValueLogSegmentReplacing added in v0.6.0 

func (db *DB) RegisterValueLogSegmentReplacing(path string, fileID, previousFileID uint32) error

RegisterValueLogSegmentReplacing registers a newly created value-log segment and marks it as current writable, sealing previousFileID when it is the prior segment for the same physical writer. Cached leaf-log lanes use this because multiple physical writers share the reserved encoded leaf-log lane id.

func (*DB) ReleaseValueLogValues added in v0.6.0 

func (db *DB) ReleaseValueLogValues(ptrs []page.ValuePtr)

ReleaseValueLogValues releases pending GC pins for previously appended value-log pointers. Native-root callers should call this when pointers are abandoned before publication or after a detached root containing those pointers has been made reachable by a later catalog/system-root publish.

func (*DB) ReverseIterator 

func (db *DB) ReverseIterator(start, end []byte) (iterator.UnsafeIterator, error)

ReverseIterator returns a reverse iterator.

func (*DB) ReverseIteratorWithOptions added in v0.4.0 

func (db *DB) ReverseIteratorWithOptions(start, end []byte, opts IteratorOptions) (iterator.UnsafeIterator, error)

ReverseIteratorWithOptions returns a reverse iterator with explicit value materialization controls.

func (*DB) RotateCommandWALActiveSegment added in v0.6.0 

func (db *DB) RotateCommandWALActiveSegment(sync bool) error

RotateCommandWALActiveSegment rotates the active command-WAL segment to a fresh file. Checkpoint cutovers use this to make covered frames non-active so cleanup can reclaim them.

func (*DB) RunCloseHooks added in v0.6.0 

func (db *DB) RunCloseHooks() error

RunCloseHooks runs and clears registered close hooks. Wrappers that own a backend DB should call this before they start closing resources required by backend publish APIs.

func (*DB) Set 

func (db *DB) Set(key, value []byte) error

Set sets the value for a key.

func (*DB) SetCurrentValueLogReadBarrier added in v0.4.0 

func (db *DB) SetCurrentValueLogReadBarrier(fn func(fileID uint32) error)

SetCurrentValueLogReadBarrier installs a callback that will be invoked before backend-internal reads of segments still marked currentWritable.

func (*DB) SetCurrentValueLogReadBarrierWithSize added in v0.6.0 

func (db *DB) SetCurrentValueLogReadBarrierWithSize(fn func(fileID uint32) (int64, error))

SetCurrentValueLogReadBarrierWithSize is like SetCurrentValueLogReadBarrier, but the callback can return the flushed file size. Current-writable mmap reads use that size hint to avoid a per-read file Stat on freshly flushed segments.

func (*DB) SetLeafPageLog added in v0.4.0 

func (db *DB) SetLeafPageLog(log LeafPageLog)

SetLeafPageLog installs the value-log appender used for value-log-backed leaf pages. It is typically wired by the cached layer after opening the backend.

func (*DB) SetSync 

func (db *DB) SetSync(key, value []byte) error

SetSync sets the value and syncs to disk.

func (*DB) SetValueLogAppender added in v0.6.0 

func (db *DB) SetValueLogAppender(appender ValueLogAppender)

SetValueLogAppender installs the appender used by native-root APIs that need to create persistent value-log pointers. Cached mode wires this to its normal value-log writer.

func (*DB) SetZipperParallelMergePressureSource added in v0.4.0 

func (db *DB) SetZipperParallelMergePressureSource(src zipper.ParallelMergePressureSource)

SetZipperParallelMergePressureSource installs an optional pressure signal for future zipper generations and the current live zipper.

func (*DB) State 

func (db *DB) State() *DBState

func (*DB) Stats 

func (db *DB) Stats() map[string]string

Stats returns database statistics.

func (*DB) Update added in v0.6.0 

func (db *DB) Update(key []byte, fn UpdateFunc) error

Update applies fn to the current value for key and writes the returned mutation without forcing an fsync boundary.

func (*DB) UpdateSync added in v0.6.0 

func (db *DB) UpdateSync(key []byte, fn UpdateFunc) error

UpdateSync applies fn to the current value for key and writes the returned mutation with a sync durability boundary.

func (*DB) VacuumIndexOnline 

func (db *DB) VacuumIndexOnline(ctx context.Context) error

VacuumIndexOnline rebuilds the index into a new file and swaps it in with a short writer pause. Old snapshots remain valid by pinning the previous index generation until readers drain; disk space is reclaimed once the old mmap is closed.

func (*DB) ValueLogGC added in v0.3.0 

func (db *DB) ValueLogGC(ctx context.Context, opts ValueLogGCOptions) (ValueLogGCStats, error)

ValueLogGC deletes fully-unreferenced value-log segments from value_vlog.

It scans the user + system trees for value-log pointers, computes referenced value_vlog segments, and removes segments that are:

  • not referenced,
  • not the currently-active segment per lane,
  • and not pinned by active snapshots.

func (*DB) ValueLogRewriteChunkPlan added in v0.4.0 

func (db *DB) ValueLogRewriteChunkPlan(ctx context.Context, opts ValueLogRewriteOnlineOptions, chunkBytes int64) (ValueLogRewriteChunkPlan, error)

func (*DB) ValueLogRewriteOnline added in v0.4.0 

func (db *DB) ValueLogRewriteOnline(ctx context.Context, opts ValueLogRewriteOnlineOptions) (stats ValueLogRewriteStats, err error)

ValueLogRewriteOnline rewrites pointer-backed values in bounded commit batches, then atomically swaps keys to rewritten pointers.

func (*DB) ValueLogRewritePlan added in v0.4.0 

func (db *DB) ValueLogRewritePlan(ctx context.Context, opts ValueLogRewriteOnlineOptions) (ValueLogRewritePlan, error)

ValueLogRewritePlan returns the segments that would be selected for sparse online rewrite given opts. It performs the same live-byte estimation work as ValueLogRewriteOnline sparse selection, but does not modify the DB.

func (*DB) Zipper 

func (db *DB) Zipper() *zipper.Zipper

type DBIterator 

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

DBIterator wraps tree.Iterator and holds a Snapshot.

func (*DBIterator) Close 

func (it *DBIterator) Close() error

func (*DBIterator) DebugStats 

func (it *DBIterator) DebugStats() (queueLen int, sourcesUsed int)

func (*DBIterator) Domain 

func (it *DBIterator) Domain() (start, end []byte)

func (*DBIterator) Error 

func (it *DBIterator) Error() error

func (*DBIterator) IsDeleted 

func (it *DBIterator) IsDeleted() bool

func (*DBIterator) Key 

func (it *DBIterator) Key() []byte

Key returns a read-only view of the current key. The view is valid only until the next Next()/Seek()/Close() on this iterator; use KeyCopy for stable bytes.

func (*DBIterator) KeyCopy 

func (it *DBIterator) KeyCopy(dst []byte) []byte

func (*DBIterator) Next 

func (it *DBIterator) Next()

func (*DBIterator) Seek 

func (it *DBIterator) Seek(key []byte)

UnsafeIterator methods

func (*DBIterator) UnsafeEntry 

func (it *DBIterator) UnsafeEntry() ([]byte, page.ValuePtr, byte)

func (*DBIterator) UnsafeEntryWithRevision added in v0.6.1 

func (it *DBIterator) UnsafeEntryWithRevision() ([]byte, page.ValuePtr, byte, page.EntryRevision)

func (*DBIterator) UnsafeKey 

func (it *DBIterator) UnsafeKey() []byte

func (*DBIterator) UnsafeValue 

func (it *DBIterator) UnsafeValue() []byte

func (*DBIterator) Valid 

func (it *DBIterator) Valid() bool

func (*DBIterator) Value 

func (it *DBIterator) Value() []byte

Value returns a read-only view of the current value. The view is valid only until the next Next()/Seek()/Close() on this iterator; use ValueCopy for stable bytes.

func (*DBIterator) ValueCopy 

func (it *DBIterator) ValueCopy(dst []byte) []byte

type DBState 

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

type DurabilityMode added in v0.3.0 

type DurabilityMode uint8

DurabilityMode configures cached-mode durability semantics.

These modes are explicit and intentionally replace the previous boolean combination of DisableWAL + RelaxedSync + AllowUnsafe. 

const (
	// DurabilityDurable enables WAL (journal) and uses fsync for sync operations.
	DurabilityDurable DurabilityMode = iota
	// DurabilityWALOnRelaxed keeps WAL enabled but disables fsync (crash-consistent).
	DurabilityWALOnRelaxed
	// DurabilityWALOffRelaxed disables WAL and fsync (unsafe; recent writes
	// may be lost and sync calls may defer backend publication until a later
	// checkpoint/flush boundary).
	DurabilityWALOffRelaxed
)

type FlushAdmissionDecision added in v0.6.0 

type FlushAdmissionDecision struct {
	Policy                          FlushAdmissionPolicy
	Admitted                        bool
	Reason                          string
	FlushApplyConcurrencyConfigured int
	FlushApplyConcurrency           int
	FlushApplyConcurrencyCapReason  string
	FlushApplyConcurrencyDefaulted  bool
	RuntimeGOMAXPROCS               int
	PhysicalCores                   int
	FlushApplySpanNative            bool
	FlushBacklogCoalescing          bool
	LeafPageReadCacheWriteAdmission LeafPageReadCacheWriteAdmissionPolicy
}

FlushAdmissionDecision is the normalized admission result reported through DB.Stats and benchmark option reports.

func FlushAdmissionDecisionForOptions added in v0.6.0 

func FlushAdmissionDecisionForOptions(opts Options) FlushAdmissionDecision

FlushAdmissionDecisionForOptions returns the decision already stored in opts, or computes the decision for a copy without mutating the caller's options.

func NormalizeFlushAdmissionOptions added in v0.6.0 

func NormalizeFlushAdmissionOptions(opts *Options) FlushAdmissionDecision

NormalizeFlushAdmissionOptions applies the fail-closed admission seam to opts and stores the decision in the options for Open/Stats. It is idempotent so public wrappers can normalize before passing options to the backend without losing the original decline reason.

type FlushAdmissionPolicy added in v0.6.0 

type FlushAdmissionPolicy uint8

FlushAdmissionPolicy controls how TreeDB admits the span-native/backlog flush/apply candidate path. The zero value is the default auto selector: it admits the measured hardware-aware span-native/backlog/adaptive candidate on sufficiently parallel hosts, declines low-concurrency shapes, and leaves rollback and explicit opt-in policies available. 

const (
	// FlushAdmissionPolicyAuto is the default selector. It admits the measured
	// span-native/backlog/adaptive-cache candidate at the detected physical core
	// count, capped by GOMAXPROCS and a conservative upper bound, only when the
	// low-concurrency guardrail passes; otherwise it fails closed to the serial
	// path. If physical-core detection is unavailable, auto falls back to the
	// existing GOMAXPROCS-capped bound.
	FlushAdmissionPolicyAuto FlushAdmissionPolicy = iota
	// FlushAdmissionPolicyExplicit preserves existing explicit knobs. Use this to
	// opt in to a non-default span-native/backlog/concurrency/cache shape.
	FlushAdmissionPolicyExplicit
	// FlushAdmissionPolicyOff force-disables span-native, backlog coalescing, and
	// flush-apply worker-pool concurrency as a rollback/fail-closed policy.
	FlushAdmissionPolicyOff
)

func ParseFlushAdmissionPolicy added in v0.6.0 

func ParseFlushAdmissionPolicy(raw string) (FlushAdmissionPolicy, error)

ParseFlushAdmissionPolicy parses off|explicit|auto policy values. Empty and "default" use the current default auto selector.

func (FlushAdmissionPolicy) String added in v0.6.0 

func (p FlushAdmissionPolicy) String() string

func (FlushAdmissionPolicy) Valid added in v0.6.0 

func (p FlushAdmissionPolicy) Valid() bool

type FlushApplyPressureSnapshot added in v0.6.0 

type FlushApplyPressureSnapshot struct {
	ApplyOps                     uint64
	ReadOnlyPrepareSpans         uint64
	ReadOnlyPrepareSingleOpSpans uint64
	ReadOnlyPrepareSpanOps       uint64
	ReadOnlyPrepareSpanBytes     uint64
	OldLeafReadDecodeBytes       uint64
}

FlushApplyPressureSnapshot is a cheap cumulative snapshot of the M8/M10 apply pressure counters used by the cached flush backlog coalescing policy. It intentionally mirrors existing Stats() counters without requiring a map allocation on the flush hot path.

type FlushSpanRunBackendChunk added in v0.6.0 

type FlushSpanRunBackendChunk struct {
	ChunkIndex   int
	PointOpStart int
	PointOpEnd   int
	ByteCount    int
}

FlushSpanRunBackendChunk describes an existing entry-count backend batch chunk. M8 keeps this metadata explicit so later milestones can prove whether entry-count chunking splits target leaves and whether leaf-aware chunking fixes that split.

type FlushSpanRunBaseRootValidation added in v0.6.0 

type FlushSpanRunBaseRootValidation struct {
	CapturedRootID uint64
	CurrentRootID  uint64
	Matched        bool
}

FlushSpanRunBaseRootValidation records the root identity captured before span planning and the root identity observed at guarded publish. Future span-native reducers must publish only when Matched is true; mismatches retry or fall back and any already prepared output is durable-but-unreachable.

type FlushSpanRunChunkPlan added in v0.6.0 

type FlushSpanRunChunkPlan struct {
	Metadata FlushSpanRunMetadata

	TargetLeafSpans int
	SingleOpSpans   int
	SpanOps         int
	SpanBytes       int

	BackendChunks []FlushSpanRunBackendChunk
	SplitSummary  FlushSpanRunChunkSplitSummary
}

FlushSpanRunChunkPlan is the cache-layer M9 planning result used to pack a canonical point run into backend chunks without materializing a second copy of every target leaf span. Full TargetLeafSpans remain available through PlanFlushSpanRun for tests and future span-native consumers; this compact result is the hot-path chunking/observability form.

type FlushSpanRunChunkSplitSummary added in v0.6.0 

type FlushSpanRunChunkSplitSummary struct {
	BackendChunks                 int
	TargetLeafSpans               int
	TargetLeavesSplitAcrossChunks int
	MaxChunksPerTargetLeaf        int
}

FlushSpanRunChunkSplitSummary summarizes whether existing entry-count backend chunks split target leaf spans.

func SummarizeFlushSpanRunChunkSplits added in v0.6.0 

func SummarizeFlushSpanRunChunkSplits(spans []FlushSpanRunTargetLeafSpan, chunks []FlushSpanRunBackendChunk) FlushSpanRunChunkSplitSummary

SummarizeFlushSpanRunChunkSplits returns how many target leaves are crossed by more than one backend chunk. A later leaf-aware chunker should drive TargetLeavesSplitAcrossChunks to zero for point-write spans.

type FlushSpanRunFallbackReason added in v0.6.0 

type FlushSpanRunFallbackReason uint8

FlushSpanRunFallbackReason is the stable M8 fallback matrix for future span-native flush/apply. The string values are exported through stats, bench artifacts, and docs; add new reasons append-only so existing dashboards and downstream milestones keep their meaning. 

const (
	FlushSpanRunFallbackUnknown FlushSpanRunFallbackReason = iota
	FlushSpanRunFallbackDisabled
	FlushSpanRunFallbackBelowThreshold
	FlushSpanRunFallbackSpanNativeNotImplemented
	FlushSpanRunFallbackPrepareError
	FlushSpanRunFallbackValidationFailed
	FlushSpanRunFallbackRootMismatch
	FlushSpanRunFallbackRangeDeleteBarrier
	FlushSpanRunFallbackLaneBarrier
	FlushSpanRunFallbackCommandWALBarrier
	FlushSpanRunFallbackInexactLeafSpans
	FlushSpanRunFallbackColdBuild
	FlushSpanRunFallbackMaintenance
	FlushSpanRunFallbackBackendChunkSplit
	FlushSpanRunFallbackCloseOrCheckpoint
	FlushSpanRunFallbackMemoryEmergencyCap
	FlushSpanRunFallbackOutputOwnershipFailure
	FlushSpanRunFallbackReducerValidationFailed
	FlushSpanRunFallbackRouteIneligible
	FlushSpanRunFallbackAdmissionPolicyDecline
	FlushSpanRunFallbackReducerValidationGuard
)

func FlushSpanRunFallbackReasons added in v0.6.0 

func FlushSpanRunFallbackReasons() []FlushSpanRunFallbackReason

FlushSpanRunFallbackReasons returns the stable fallback reason list in enum order. Unknown is included so stats can fail closed instead of silently dropping an unclassified fallback.

func ParseFlushSpanRunFallbackReason added in v0.6.0 

func ParseFlushSpanRunFallbackReason(s string) (FlushSpanRunFallbackReason, bool)

ParseFlushSpanRunFallbackReason parses a stable fallback reason stat value.

func (FlushSpanRunFallbackReason) String added in v0.6.0 

func (r FlushSpanRunFallbackReason) String() string

func (FlushSpanRunFallbackReason) Valid added in v0.6.0 

func (r FlushSpanRunFallbackReason) Valid() bool

Valid reports whether r is a known append-only fallback reason.

type FlushSpanRunMetadata added in v0.6.0 

type FlushSpanRunMetadata struct {
	RunID uint64

	BaseRoot FlushSpanRunBaseRootValidation

	SourceMemtables  int
	SourcePointOps   int
	PlannedPointOps  int
	ShadowedPointOps int
	RangeBarriers    int
	LaneBarriers     int

	TargetLeafSpans []FlushSpanRunTargetLeafSpan
	BackendChunks   []FlushSpanRunBackendChunk
}

FlushSpanRunMetadata is the canonical run-level metadata contract. M8 does not build the production multi-memtable run yet; the structure documents the fields M9+ must provide before span planning and reducer execution.

type FlushSpanRunPlanRequest added in v0.6.0 

type FlushSpanRunPlanRequest struct {
	RunID uint64

	SourceMemtables  int
	SourcePointOps   int
	PlannedPointOps  int
	ShadowedPointOps int
	RangeBarriers    int
	LaneBarriers     int

	PointOps     []batch.Entry
	DeleteRanges []batch.DeleteRange
}

FlushSpanRunPlanRequest asks a backend to plan exact target leaf spans for a canonical point-op run. PointOps must already be globally sorted and shadowed; DeleteRanges are explicit range barriers/ranges that the caller did not cross while selecting source memtables.

The request owns no durable output. Slices only need to remain stable for the duration of the call.

type FlushSpanRunPreparedOutputOwnership added in v0.6.0 

type FlushSpanRunPreparedOutputOwnership struct {
	LeafLogPages int
	LeafLogBytes int64
	RetiredRefs  []page.ChildRef

	Installed               bool
	DurableButUnreachable   bool
	AbandonedFallbackReason FlushSpanRunFallbackReason
}

FlushSpanRunPreparedOutputOwnership describes prepared durable output owned by a span job. Prepared leaf/value-log output is persistent storage: on retry or root mismatch it becomes durable-but-unreachable and is accounted as abandoned; it is never rolled back by truncating durable pointer targets.

type FlushSpanRunReducerInput added in v0.6.0 

type FlushSpanRunReducerInput struct {
	RunID      uint64
	BaseRoot   FlushSpanRunBaseRootValidation
	SpanOutput []FlushSpanRunSpanJobOutput
}

FlushSpanRunReducerInput is the deterministic reducer contract. Outputs must be sorted by SpanIndex, and the reducer must validate BaseRoot before publish.

type FlushSpanRunSpanJobInput added in v0.6.0 

type FlushSpanRunSpanJobInput struct {
	RunID      uint64
	BaseRootID uint64
	Span       FlushSpanRunTargetLeafSpan
	PointOps   []batch.Entry
	Ranges     []batch.DeleteRange
}

FlushSpanRunSpanJobInput is the future span-native worker input contract. The op slices are canonical slices from FlushSpanRunMetadata and must already have same-key shadowing applied globally across source memtables.

type FlushSpanRunSpanJobOutput added in v0.6.0 

type FlushSpanRunSpanJobOutput struct {
	SpanIndex       int
	ReplacementRefs []page.ChildRef
	SplitBoundaries [][]byte
	PreparedOutput  FlushSpanRunPreparedOutputOwnership
}

FlushSpanRunSpanJobOutput is the deterministic worker output contract fed to the reducer. SplitBoundaries are ordered high-key boundaries for ReplacementRefs.

type FlushSpanRunTargetLeafSpan added in v0.6.0 

type FlushSpanRunTargetLeafSpan struct {
	SpanIndex int
	Ref       page.ChildRef

	LowKey     []byte
	HighKey    []byte
	FirstOpKey []byte
	LastOpKey  []byte

	PointOpStart     int
	PointOpEnd       int
	DeleteRangeStart int
	DeleteRangeEnd   int
	OpCount          int
	ByteCount        int
}

FlushSpanRunTargetLeafSpan is the M8 target-leaf span contract consumed by future span-native jobs. PointOpStart/PointOpEnd index the canonical run's globally shadowed point-op slice; DeleteRangeStart/DeleteRangeEnd index the canonical range-barrier slice. It owns no durable output.

type FormatConfig added in v0.4.0 

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

	RequiredFeatures []string `json:"required_features,omitempty"`

	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"`
}

FormatConfig captures the format-affecting knobs that maintenance tooling should preserve when rewriting index/value-log state.

This file is best-effort and pre-alpha; callers should tolerate it being absent. Versioned files written by SaveFormatConfig are expected to be fully populated; if new fields are added in the future, the version should be bumped so older binaries do not accidentally apply zero-values.

func LoadFormatConfig added in v0.4.0 

func LoadFormatConfig(dir string) (FormatConfig, bool, error)

LoadFormatConfig loads the best-effort persisted format config for dir. The returned bool reports whether the file was found.

func (FormatConfig) ApplyIndexFormatToOptions added in v0.4.0 

func (cfg FormatConfig) ApplyIndexFormatToOptions(opts *Options)

ApplyIndexFormatToOptions overwrites index-format-affecting knobs in opts from cfg.

This is intentionally narrower than ApplyToOptions: it is safe for normal DB opens where callers may want to tune runtime policies (e.g. value-log compression) via env vars or flags, while still ensuring the index encoding matches on-disk state.

func (FormatConfig) ApplyToOptions added in v0.4.0 

func (cfg FormatConfig) ApplyToOptions(opts *Options)

ApplyToOptions overwrites format-affecting knobs in opts from cfg.

Callers should treat cfg as best-effort (it may be absent) and may apply explicit overrides after this call.

func (FormatConfig) RequiresCommandWALV1 added in v0.6.0 

func (cfg FormatConfig) RequiresCommandWALV1() bool

type GetManyViewFunc added in v0.6.0 

type GetManyViewFunc = tree.GetManyViewFunc

GetManyViewFunc receives one GetManyView result. The value slice is a read-only view that is valid only until the callback returns; callers must copy it before retaining it. Missing/tombstoned keys are reported with found=false and value=nil.

type IntegrityMode added in v0.3.0 

type IntegrityMode uint8

IntegrityMode configures value-log read integrity checks.

It intentionally replaces the previous DisableReadChecksum boolean. 

const (
	// IntegrityVerify enables checksum verification on value-log reads.
	IntegrityVerify IntegrityMode = iota
	// IntegritySkipChecksums disables checksum verification on value-log reads (unsafe).
	IntegritySkipChecksums
)

type Iterator 

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)
}

Iterator is the internal interface for iteration.

type IteratorMode added in v0.4.0 

type IteratorMode = tree.IteratorMode

type IteratorOptions added in v0.4.0 

type IteratorOptions = tree.IteratorOptions

type JournalLaneDefaultDecision added in v0.6.0 

type JournalLaneDefaultDecision struct {
	Configured       int
	Effective        int
	Defaulted        bool
	GOMAXPROCS       int
	PhysicalCores    int
	GenerationPolicy ValueLogGenerationPolicy
	HotLanes         int
	WarmLanes        int
	ColdLanes        int
}

JournalLaneDefaultDecision describes the lane topology selected for a new cached-mode open before recovery may widen it to include already-existing lane files.

func ResolveJournalLaneDefaults added in v0.6.0 

func ResolveJournalLaneDefaults(configured, gomax, physicalCores int, generationPolicy ValueLogGenerationPolicy) JournalLaneDefaultDecision

ResolveJournalLaneDefaults resolves the default journal/value-log lane count for cached mode. The default is intentionally coalescing-safe: hot/warm/cold generation uses three total lanes (one hot, one warm, one cold), while generation-off cached mode uses one hot lane. Explicit JournalLanes values are authoritative and are only classified for reporting.

type LeafGenerationGCOptions added in v0.5.0 

type LeafGenerationGCOptions struct {
	DryRun bool

	// ProtectedRootIDs are additional ordinary root page IDs whose leaf-log
	// children must be treated as live even when they are not reachable from the
	// backend meta roots. Cached named roots use this during online maintenance.
	ProtectedRootIDs []uint64
	// ProtectedSystemRootIDs are system-root page IDs whose collection root
	// descriptors should be expanded into additional protected roots.
	ProtectedSystemRootIDs []uint64
}

type LeafGenerationGCStats added in v0.5.0 

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

type LeafGenerationPackFromPlanOptions added in v0.5.0 

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)
	LeafFrameK                 int
	ProtectedRootIDs           []uint64
	ProtectedSystemRootIDs     []uint64
}

LeafGenerationPackFromPlanOptions combines planner thresholds, bounded selection limits, and pack execution settings for the manual from-plan path.

type LeafGenerationPackOptions added in v0.5.0 

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
	LeafFrameK                 int
	ProtectedRootIDs           []uint64
	ProtectedSystemRootIDs     []uint64
}

type LeafGenerationPackRunOnceStats added in v0.5.0 

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

LeafGenerationPackRunOnceStats describes one bounded admission/evaluation pass for leaf-generation packing.

type LeafGenerationPackSelectOptions added in v0.5.0 

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

LeafGenerationPackSelectOptions bounds a selected ranked subset of plan candidates.

type LeafGenerationPackSelection added in v0.5.0 

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

LeafGenerationPackSelection summarizes a bounded subset of pack candidates.

func SelectLeafGenerationPackCandidates added in v0.5.0 

func SelectLeafGenerationPackCandidates(plan LeafGenerationPlan, opts LeafGenerationPackSelectOptions) (LeafGenerationPackSelection, error)

SelectLeafGenerationPackCandidates selects a bounded subset from an eligible leaf-generation plan. For bounded windows it maximizes reclaimable bytes within the requested generation/copy limits, then emits the chosen generations in their original plan order.

type LeafGenerationPackStats added in v0.5.0 

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
	LeafFramesWritten               int
	MaxLeafFrameK                   int
	InternalPagesVisited            int
	SubtreesPruned                  int
	CreatedFileIDs                  []uint32
	WallTimeNanos                   int64
}

type LeafGenerationPlan added in v0.5.0 

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 added in v0.5.0 

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 added in v0.5.0 

type LeafGenerationPlanOptions struct {
	MinPublishedAgeCommits     uint64
	MinCandidateGenerations    int
	MinExpectedReclaimBytes    int64
	MinExpectedReclaimRatioPPM int
	MinReclaimPerByteCopiedPPM int
	Force                      bool
	// ProtectedRootIDs are additional ordinary root page IDs whose leaf-log
	// children must be treated as live while planning maintenance. Empty uses the
	// existing cached live-scan path when no protected system roots are present.
	ProtectedRootIDs []uint64
	// ProtectedSystemRootIDs are system-root page IDs whose collection root
	// descriptors should be expanded into additional protected roots.
	ProtectedSystemRootIDs []uint64
}

type LeafPageBatchLog added in v0.6.0 

type LeafPageBatchLog interface {
	// AppendLeafPages appends every leaf page and returns one pointer per input
	// page in the same order. Callers use that positional relationship for
	// cache population and per-page record-length metadata.
	AppendLeafPages(leafPages [][]byte) ([]page.LeafLogPtr, error)
}

type LeafPageConcurrentAppendLog added in v0.6.0 

type LeafPageConcurrentAppendLog interface {
	ConcurrentLeafPageAppends() bool
}

type LeafPageLog added in v0.4.0 

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

LeafPageLog appends and flushes B+Tree leaf pages stored in the value log.

This is used when Options.IndexOuterLeavesInValueLog is enabled. Implementations are expected to reuse the existing value-log record encoding and compression semantics (i.e. they should append normal value-log records and return LeafLogPtr references).

type LeafPageLogCachedWrapperOwner added in v0.6.0 

type LeafPageLogCachedWrapperOwner interface {
	CompactStorageCachedWrapperOwner() bool
}

LeafPageLogCachedWrapperOwner marks leaf-page logs installed by the public cached TreeDB wrapper. Exhaustive compact treats these separately from caller-owned logs with similar concurrency or segment-reporting capabilities because cached owners also need background-flush and backlog quiescence.

type LeafPageLogCloser added in v0.6.0 

type LeafPageLogCloser interface {
	LeafPageLog
	Close() error
}

LeafPageLogCloser is a standalone leaf-page log that should be closed by the owner after the DB is closed.

func NewStandaloneLeafPageLog added in v0.6.0 

func NewStandaloneLeafPageLog(dir string, opts StandaloneLeafPageLogOptions) (LeafPageLogCloser, error)

NewStandaloneLeafPageLog creates a persistent leaf-page log for direct DB users. Cached TreeDB opens install their own leaf log; this helper is for direct backend adapters and tests that intentionally bypass cached mode.

type LeafPageLogCompactStorageHandoff added in v0.6.0 

type LeafPageLogCompactStorageHandoff interface {
	AdvanceCompactStorageLeafPageLogSeqAtLeast(seq uint32) error
}

LeafPageLogCompactStorageHandoff is implemented by internally owned leaf-page-log writers that can be safely restored after CompactStorage temporarily replaces them with its compact writer.

type LeafPageLogCreatedSegmentProvider added in v0.6.0 

type LeafPageLogCreatedSegmentProvider interface {
	CreatedLeafPageLogSegmentsSnapshot() ([]LeafPageLogSegment, error)
}

type LeafPageLogCurrentSegmentProvider added in v0.6.0 

type LeafPageLogCurrentSegmentProvider interface {
	CurrentLeafPageLogSegmentsSnapshot() ([]LeafPageLogSegment, error)
}

LeafPageLogCurrentSegmentProvider optionally reports every currently tracked leaf-log segment. Implementations may return multiple current segments while keeping the singular CurrentValueLogSegment compatibility path available.

type LeafPageLogLaneProvider added in v0.6.0 

type LeafPageLogLaneProvider interface {
	LeafPageLogLane(workerIndex int) (LeafPageLog, bool)
}

LeafPageLogLaneProvider optionally exposes additional lane-specific leaf-page log appenders for concurrent writers.

type LeafPageLogSegment added in v0.6.0 

type LeafPageLogSegment struct {
	Path   string
	FileID uint32
}

type LeafPageLogSegmentRegistrationObserver added in v0.6.0 

type LeafPageLogSegmentRegistrationObserver interface {
	MarkLeafPageLogSegmentsRegistered([]LeafPageLogSegment)
}

type LeafPagePreparedAppendLog added in v0.6.0 

type LeafPagePreparedAppendLog interface {
	PreparedLeafPageAppends() bool
}

type LeafPagePreparedBatchAppendLog added in v0.6.0 

type LeafPagePreparedBatchAppendLog interface {
	PreparedLeafPageBatchAppends() bool
}

type LeafPagePreparedBatchLog added in v0.6.0 

type LeafPagePreparedBatchLog interface {
	// AppendPreparedLeafPages appends caller-prepared leaf-log payloads while
	// preserving the positional relationship to the original leaf pages. The
	// original leafPages are used for read-cache population and integrity checks;
	// preparedPayloads contain the already-compacted value-log record payloads.
	AppendPreparedLeafPages(leafPages [][]byte, preparedPayloads [][]byte) ([]page.LeafLogPtr, error)
}

type LeafPagePreparedChildRefBatchLog added in v0.6.0 

type LeafPagePreparedChildRefBatchLog interface {
	// AppendPreparedLeafPageChildRefs is the ChildRef-returning counterpart to
	// AppendPreparedLeafPages. It lets hot paths avoid allocating an intermediate
	// []LeafLogPtr when the caller ultimately needs ChildRefs.
	AppendPreparedLeafPageChildRefs(leafPages [][]byte, preparedPayloads [][]byte, refs []page.ChildRef) ([]page.ChildRef, error)
}

type LeafPagePreparedLog added in v0.6.0 

type LeafPagePreparedLog interface {
	// AppendPreparedLeafPage appends one caller-prepared leaf-log payload. The
	// original leafPage is used for read-cache population and integrity checks;
	// preparedPayload contains the already-compacted value-log record payload.
	AppendPreparedLeafPage(leafPage []byte, preparedPayload []byte) (page.LeafLogPtr, error)
}

type LeafPageReadCacheWriteAdmissionPolicy added in v0.6.0 

type LeafPageReadCacheWriteAdmissionPolicy uint8

LeafPageReadCacheWriteAdmissionPolicy controls whether write-side outer-leaf appends immediately populate the in-memory read cache or use an opt-in, best-effort admission policy. It affects only cache population; leaf-log and value-log records remain persistent regardless of cache admission. 

const (
	// LeafPageReadCacheWriteAdmissionImmediate preserves the historical behavior:
	// every valid write-side outer-leaf append is copied into the read cache.
	LeafPageReadCacheWriteAdmissionImmediate LeafPageReadCacheWriteAdmissionPolicy = iota
	// LeafPageReadCacheWriteAdmissionAdaptive is an opt-in write-heavy policy that
	// warms the cache, samples cold write streams, re-admits when reads prove the
	// cache is hot, and skips rather than blocking on cache locks.
	LeafPageReadCacheWriteAdmissionAdaptive
)

func ParseLeafPageReadCacheWriteAdmissionPolicy added in v0.6.0 

func ParseLeafPageReadCacheWriteAdmissionPolicy(raw string) (LeafPageReadCacheWriteAdmissionPolicy, error)

ParseLeafPageReadCacheWriteAdmissionPolicy parses public/user-facing policy strings. Empty/default keep the historical immediate behavior.

func (LeafPageReadCacheWriteAdmissionPolicy) String added in v0.6.0 

func (p LeafPageReadCacheWriteAdmissionPolicy) String() string

type Options 

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
	// CommandWAL enables the compatibility-breaking command-WAL mode for direct
	// backend raw KV writes. It is also enabled automatically when format.json
	// advertises the command_wal_v1 required feature.
	//
	// Public treedb.Open write handles route raw KV writes through the direct
	// backend command-WAL path while command_wal_v1 is active, avoiding the
	// legacy cached redo journal until cached writes are converted to typed
	// command frames.
	CommandWAL bool
	// CommandWALStatsScan enables expensive diagnostic Stats() counters that scan
	// command-WAL segment files for frame counts and max LSN. Keep this disabled
	// for normal telemetry; benchmark proof paths can opt in explicitly.
	CommandWALStatsScan 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. Under the collection WAL
	// target contract, read-only open must fail with a recovery-required error if
	// committed unapplied collection WAL needs mutating recovery.
	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 1
	// 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
	// LeafPageReadCacheEntries controls the bounded process-local cache used for
	// B-tree leaf pages stored in the value log. The cache stores decoded 4KiB
	// leaf pages and is most useful for sparse update/publish/read workloads that
	// revisit recently-written outer leaves.
	//
	// Semantics:
	//   - 0 uses the process default/env override.
	//   - <0 disables the cache for this DB.
	//   - >0 sets the exact number of set-associative cache entries.
	LeafPageReadCacheEntries int
	// LeafPageReadCacheWriteAdmission controls write-side cache population for
	// outer-leaf pages stored in the value log. The field's zero value is the
	// historical immediate admission behavior for explicit/off policies; the
	// default auto flush-admission policy upgrades it to the measured adaptive
	// write-admission candidate. Adaptive admission only changes in-memory cache
	// population, not persistent leaf-log/value-log writes or pointer validity.
	LeafPageReadCacheWriteAdmission LeafPageReadCacheWriteAdmissionPolicy

	// 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

	// FlushAdmissionPolicy selects how TreeDB admits the span-native/backlog
	// flush/apply candidate path. The zero value (auto) admits the measured
	// hardware-aware adaptive candidate, selecting up to the detected physical
	// core count capped by GOMAXPROCS and a conservative upper bound on
	// sufficiently parallel hosts. If physical-core detection is unavailable, auto
	// falls back to the existing GOMAXPROCS-capped bound. Explicit preserves
	// caller-supplied knobs; Off force-disables span-native/backlog/concurrency as
	// a rollback policy.
	FlushAdmissionPolicy FlushAdmissionPolicy

	// FlushApplyConcurrency enables M2 parallel COW apply for backend flush/write
	// batches using a bounded reusable worker pool. It is separate from
	// FlushBuildConcurrency. Values <=1 keep the worker-pool path off for
	// explicit policy; the default auto admission policy chooses a hardware-aware
	// candidate capped by GOMAXPROCS when the low-concurrency guardrail passes.
	FlushApplyConcurrency int
	// FlushApplyMinEntries gates opt-in parallel apply by planned span-local ops.
	// Values <=0 use the internal default.
	FlushApplyMinEntries int
	// FlushApplyMinSpans gates opt-in parallel apply by planned leaf span count.
	// Values <=0 use the internal default.
	FlushApplyMinSpans int
	// FlushApplyMinBytes gates opt-in parallel apply by planned span bytes.
	// Values <=0 use the internal default.
	FlushApplyMinBytes int
	// FlushApplySpanNative enables the M10 span-native apply candidate path. The
	// default auto admission policy enables it only for the measured capped
	// adaptive candidate; explicit policy preserves caller-provided values.
	// Unsupported runs fall back to recursive apply.
	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 (0=default, <0=disable cap).
	FlushBackendMaxBatches int

	// FlushSpanRunTargetPlanning enables diagnostic read-only target-leaf planning
	// for canonical cached flush runs. It is default-off; M9's default write path
	// builds canonical multi-memtable runs but does not pay the extra target-span
	// traversal unless this diagnostic knob is explicitly enabled.
	FlushSpanRunTargetPlanning bool

	// FlushBacklogCoalescing enables the M11 bounded adaptive cached-flush
	// coalescing controller. The default auto admission policy enables it for the
	// measured capped adaptive candidate; when enabled the cache layer may
	// include additional already-sealed eligible memtables in one canonical flush
	// run 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

	// 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
	// CommandWALSegmentTargetBytes bounds command-WAL active segment growth by
	// rotating to a fresh command-WAL segment before an append would make a
	// non-empty active segment exceed the target. It is separate from
	// WALMaxSegmentBytes, which remains a per-frame payload cap. 0 disables
	// runtime command-WAL rotation.
	CommandWALSegmentTargetBytes 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
	// contains filtered or unexported fields
}

type OrderedRootDeltaBatchGroupCommandWALDeltaBuilder added in v0.6.0 

type OrderedRootDeltaBatchGroupCommandWALDeltaBuilder func(CommandWALPublishContext) ([]OrderedRootDeltaBatchPublishInput, error)

OrderedRootDeltaBatchGroupCommandWALDeltaBuilder is the batch-materialized counterpart to OrderedRootGroupCommandWALDeltaBuilder. On success, returned batch deltas keep the normal OrderedRootDeltaBatchPublishInput ownership contract: the DB publish path does not close them, so builders that allocate batches must arrange cleanup after the enclosing publish call returns. If a builder returns deltas with a non-nil error, the DB publish path closes those deltas before returning the error. If context build succeeds but a later publish step fails, the DB closes the context-built batch deltas before returning the publish error.

type OrderedRootDeltaBatchPublishInput added in v0.6.0 

type OrderedRootDeltaBatchPublishInput struct {
	BaseRoot      uint64
	Delta         *batch.Batch
	StoragePolicy OrderedRootStoragePolicy
	// IncludeDeletedOnColdBuild preserves tombstones when BaseRoot is zero.
	// Most cold root builds can omit deletes because there is no base tree to
	// hide, but collection overlay roots need tombstones to mask older overlay
	// or base-root entries during reads.
	IncludeDeletedOnColdBuild bool
	// ParallelApply allows this root-local batch apply to run concurrently with
	// other opted-in roots in the same group before the final commit validation.
	// Callers should opt in only when root deltas are already materialized and
	// benchmarked as large enough to amortize goroutine and shared backend costs.
	ParallelApply bool
	// PrepareReadOnly runs the side-effect-free leaf-span planning pass before
	// warm root apply and records planning stats. It is observability/planning
	// only; it does not change publish output or enable parallel leaf execution.
	PrepareReadOnly bool
	// ReadOnlyPrepareWorkers is the requested future worker count used to build
	// deterministic contiguous leaf-span ranges when PrepareReadOnly is true.
	// Values <=0 skip worker-range construction while still validating spans.
	ReadOnlyPrepareWorkers int
	// SpanNativeRoute tags runtime ordered-root span-native observations for this
	// root-local batch. Empty uses the publish helper's default route.
	SpanNativeRoute OrderedRootSpanNativeRoute
	// SpanNativeContext is optional human-readable route context for diagnostics.
	// Empty uses the route's default context.
	SpanNativeContext string
}

OrderedRootDeltaBatchPublishInput describes a sorted root-local mutation batch whose iterator materialization has already been done by the caller. Callers retain ownership of Delta and must keep any borrowed key/value views immutable until the publish call returns.

type OrderedRootDeltaPublishInput added in v0.6.0 

type OrderedRootDeltaPublishInput struct {
	BaseRoot      uint64
	Iter          iterator.UnsafeIterator
	StoragePolicy OrderedRootStoragePolicy
}

OrderedRootDeltaPublishInput describes a sorted root-local mutation stream. Unlike OrderedRootPublishInput, Iter contains only keys changed by this publish; omitted base-root keys are preserved.

type OrderedRootGroupCommandWALDeltaBuilder added in v0.6.0 

type OrderedRootGroupCommandWALDeltaBuilder func(CommandWALPublishContext) ([]OrderedRootDeltaPublishInput, error)

OrderedRootGroupCommandWALDeltaBuilder builds additional root-local mutation streams after the command-WAL LSN has been assigned. It is for roots whose durable contents include the assigned AppliedCommandLSN. On a nil error, the DB publish path takes ownership of returned iterators and closes every unconsumed iterator. If a builder returns iterators with a non-nil error, the DB publish path closes those iterators before returning the error.

type OrderedRootGroupCommandWALSystemBuilder added in v0.6.0 

type OrderedRootGroupCommandWALSystemBuilder func(CommandWALPublishContext, []uint64) (iterator.UnsafeIterator, error)

OrderedRootGroupCommandWALSystemBuilder builds a target system-root iterator after the command-WAL frame has been appended and the non-system roots have been built. For context-root publish APIs, rootIDs contains the original ordered inputs first, followed by any context-built roots in returned order, so it may be longer than the original ordered input slice. The rootIDs slice is borrowed for the duration of the call and must be treated as read-only. APIs without context-built roots receive only the original ordered root IDs.

type OrderedRootGroupPreflight added in v0.6.0 

type OrderedRootGroupPreflight func() error

OrderedRootGroupPreflight validates that a root group can still be applied. It runs while the DB write lock is held and before root-local deltas are applied, so callers can reject stale base roots before old pages are read.

type OrderedRootGroupSystemBuilder added in v0.6.0 

type OrderedRootGroupSystemBuilder func(rootIDs []uint64) (iterator.UnsafeIterator, error)

OrderedRootGroupSystemBuilder builds a target system-root iterator after the non-system roots in a group have been built. The rootIDs slice is ordered to match the OrderedRootPublishInput slice passed to PublishOrderedRootGroupWithSystemBuilder.

type OrderedRootPublishInput added in v0.6.0 

type OrderedRootPublishInput struct {
	BaseRoot      uint64
	Iter          iterator.UnsafeIterator
	StoragePolicy OrderedRootStoragePolicy
}

type OrderedRootSpanNativeFallbackClass added in v0.6.0 

type OrderedRootSpanNativeFallbackClass string

OrderedRootSpanNativeFallbackClass groups stable fallback reasons into the support buckets operators need during triage. 

const (
	OrderedRootSpanNativeFallbackClassNone           OrderedRootSpanNativeFallbackClass = "none"
	OrderedRootSpanNativeFallbackClassPolicy         OrderedRootSpanNativeFallbackClass = "policy"
	OrderedRootSpanNativeFallbackClassRoute          OrderedRootSpanNativeFallbackClass = "route"
	OrderedRootSpanNativeFallbackClassValidation     OrderedRootSpanNativeFallbackClass = "validation"
	OrderedRootSpanNativeFallbackClassReducerStorage OrderedRootSpanNativeFallbackClass = "reducer_storage"
	OrderedRootSpanNativeFallbackClassUnknown        OrderedRootSpanNativeFallbackClass = "unknown"
)

type OrderedRootSpanNativeRoute added in v0.6.0 

type OrderedRootSpanNativeRoute string

OrderedRootSpanNativeRoute is the stable support route label for ordered-root span-native eligibility. These labels are emitted through Stats and should be changed only at an explicit translation boundary. 

const (
	OrderedRootSpanNativeRouteDirectPublish             OrderedRootSpanNativeRoute = "direct_publish"
	OrderedRootSpanNativeRouteGroupedPublish            OrderedRootSpanNativeRoute = "grouped_publish"
	OrderedRootSpanNativeRouteSystemDeltaBuilderPublish OrderedRootSpanNativeRoute = "system_delta_builder_publish"
	OrderedRootSpanNativeRouteCommandWALPublish         OrderedRootSpanNativeRoute = "command_wal_publish"
	OrderedRootSpanNativeRouteCollectionBufferedRoots   OrderedRootSpanNativeRoute = "collection_buffered_roots"
	OrderedRootSpanNativeRouteOverlayColdBuild          OrderedRootSpanNativeRoute = "overlay_cold_build"
	OrderedRootSpanNativeRouteMultiIndexGroupPublish    OrderedRootSpanNativeRoute = "multi_index_group_publish"
	OrderedRootSpanNativeRouteDeltaBatchPublish         OrderedRootSpanNativeRoute = "delta_batch_publish"
	OrderedRootSpanNativeRouteReadOnlyPrepare           OrderedRootSpanNativeRoute = "read_only_prepare"
)

type OrderedRootSpanNativeStatus added in v0.6.0 

type OrderedRootSpanNativeStatus string

OrderedRootSpanNativeStatus is the terminal support status for a route or observed publish attempt. 

const (
	OrderedRootSpanNativeStatusIneligible OrderedRootSpanNativeStatus = "ineligible"
	OrderedRootSpanNativeStatusCandidate  OrderedRootSpanNativeStatus = "candidate"
	OrderedRootSpanNativeStatusEligible   OrderedRootSpanNativeStatus = "eligible"
	OrderedRootSpanNativeStatusUsed       OrderedRootSpanNativeStatus = "used"
	OrderedRootSpanNativeStatusFallback   OrderedRootSpanNativeStatus = "fallback"
)

type OrderedRootSpanNativeTriageRow added in v0.6.0 

type OrderedRootSpanNativeTriageRow struct {
	Route              OrderedRootSpanNativeRoute
	Context            string
	Status             OrderedRootSpanNativeStatus
	Candidate          bool
	Eligible           bool
	Used               bool
	Ops                uint64
	Spans              uint64
	FallbackReason     string
	FallbackClass      OrderedRootSpanNativeFallbackClass
	AdmissionPolicy    string
	AdmissionAdmitted  bool
	AdmissionReason    string
	SelectedWorkers    int
	RouteSupportDetail string
}

OrderedRootSpanNativeTriageRow is a route-level support snapshot. It is intentionally independent of raw flush-apply counters.

type OrderedRootStoragePolicy added in v0.6.0 

type OrderedRootStoragePolicy uint8

OrderedRootStoragePolicy selects the physical storage policy for a published ordered root. The zero value keeps the DB-level default. 

const (
	OrderedRootStorageDefault OrderedRootStoragePolicy = iota
	// OrderedRootStoragePagerLeaves stores root leaves in index.db pages. It is
	// the fast index policy and can use internal base-delta child encodings.
	OrderedRootStoragePagerLeaves
	// OrderedRootStorageValueLogLeaves stores root leaves as leaf-log records.
	// It is the compressed policy; leaf-log child pages use explicit LogRecordRef
	// entries instead of base-delta page-child encoding.
	OrderedRootStorageValueLogLeaves
)

type RawSpanNativeRoute added in v0.6.0 

type RawSpanNativeRoute string

RawSpanNativeRoute is the stable support route label for raw TreeDB write batches reaching the backend apply boundary. 

const (
	RawSpanNativeRoutePointPut               RawSpanNativeRoute = "point_put"
	RawSpanNativeRoutePointDelete            RawSpanNativeRoute = "point_delete"
	RawSpanNativeRouteMixedPoint             RawSpanNativeRoute = "mixed_point"
	RawSpanNativeRouteRangeDelete            RawSpanNativeRoute = "range_delete"
	RawSpanNativeRouteMixedRangeDelete       RawSpanNativeRoute = "mixed_range_delete"
	RawSpanNativeRouteEmptyBatch             RawSpanNativeRoute = "empty_batch"
	RawSpanNativeRouteCloseOrCheckpointDrain RawSpanNativeRoute = "close_or_checkpoint_drain"
)

type ReadOnlyApplyPlan added in v0.6.0 

type ReadOnlyApplyPlan struct {
	Prepare      zipper.ReadOnlyPrepareResult
	WorkerRanges []zipper.ReadOnlyLeafSpanWorkerRange
	PrepareNs    uint64
}

ReadOnlyApplyPlan is the validated, side-effect-free planning output for the captured root. WorkerRanges is empty when ReadOnlyApplyPlanOptions.Workers <=0 or when the prepare result has no spans.

type ReadOnlyApplyPlanOptions added in v0.6.0 

type ReadOnlyApplyPlanOptions struct {
	// Workers is the requested future worker count for deterministic span range
	// construction. Values <=0 skip worker-range construction while still
	// validating the leaf-span plan.
	Workers int

	// Zipper reuses buffers for the zipper read-only prepare pass.
	Zipper zipper.ReadOnlyPrepareOptions
}

ReadOnlyApplyPlanOptions configures an opt-in read-only flush/apply planning pass. The pass captures the current root through a DB snapshot, traverses the tree without allocating durable output, validates the resulting leaf-span plan, and optionally constructs deterministic worker span ranges. It does not publish roots, retire pages, append value-log/leaf-log output, or transfer ownership of prepared output.

type Snapshot 

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

func (*Snapshot) Close 

func (s *Snapshot) Close() error

Close releases the snapshot.

func (*Snapshot) Get 

func (s *Snapshot) Get(key []byte) ([]byte, error)

Get returns value from snapshot.

func (*Snapshot) GetAppend added in v0.4.0 

func (s *Snapshot) GetAppend(key, dst []byte) ([]byte, error)

GetAppend appends the value for key to dst and returns the grown slice. If key is not found, it returns dst and tree.ErrKeyNotFound.

func (*Snapshot) GetAppendAtRoot added in v0.6.0 

func (s *Snapshot) GetAppendAtRoot(rootID uint64, key, dst []byte) ([]byte, error)

func (*Snapshot) GetAtRoot added in v0.6.0 

func (s *Snapshot) GetAtRoot(rootID uint64, key []byte) ([]byte, error)

func (*Snapshot) GetEntry 

func (s *Snapshot) GetEntry(key []byte) (node.LeafEntry, error)

GetEntry returns the persisted leaf entry for key.

func (*Snapshot) GetEntryAtRoot added in v0.6.0 

func (s *Snapshot) GetEntryAtRoot(rootID uint64, key []byte) (node.LeafEntry, error)

func (*Snapshot) GetEntryExact added in v0.4.0 

func (s *Snapshot) GetEntryExact(key []byte) (node.LeafEntry, error)

GetEntryExact is an alias for GetEntry.

func (*Snapshot) GetManyView added in v0.6.0 

func (s *Snapshot) GetManyView(keys [][]byte, fn GetManyViewFunc) error

GetManyView calls fn once for each key with a read-only value view. Values are valid until fn returns and must be copied before retaining.

func (*Snapshot) GetManyViewAtRoot added in v0.6.0 

func (s *Snapshot) GetManyViewAtRoot(rootID uint64, keys [][]byte, fn GetManyViewFunc) error

func (*Snapshot) GetUnsafe 

func (s *Snapshot) GetUnsafe(key []byte) ([]byte, error)

GetUnsafe returns a zero-copy view of the value from the snapshot. The slice is valid until the snapshot is closed.

func (*Snapshot) GetUnsafeAtRoot added in v0.6.0 

func (s *Snapshot) GetUnsafeAtRoot(rootID uint64, key []byte) ([]byte, error)

func (*Snapshot) GetVersioned added in v0.6.1 

func (s *Snapshot) GetVersioned(key []byte) ([]byte, page.EntryRevision, error)

GetVersioned returns a safe value copy plus the native entry revision stored with the visible leaf entry.

func (*Snapshot) GetVersionedAppend added in v0.6.1 

func (s *Snapshot) GetVersionedAppend(key, dst []byte) ([]byte, page.EntryRevision, error)

GetVersionedAppend appends the value for key to dst and returns the native entry revision stored with the visible leaf entry.

func (*Snapshot) Has 

func (s *Snapshot) Has(key []byte) (bool, error)

func (*Snapshot) HasAnySortedAtRoot added in v0.6.0 

func (s *Snapshot) HasAnySortedAtRoot(rootID uint64, keys [][]byte) (bool, error)

func (*Snapshot) HasMany added in v0.6.0 

func (s *Snapshot) HasMany(keys [][]byte) ([]bool, error)

func (*Snapshot) HasManyAtRoot added in v0.6.0 

func (s *Snapshot) HasManyAtRoot(rootID uint64, keys [][]byte) ([]bool, error)

func (*Snapshot) HasPrefixes added in v0.6.0 

func (s *Snapshot) HasPrefixes(prefixes [][]byte) ([]bool, error)

func (*Snapshot) HasPrefixesAtRoot added in v0.6.0 

func (s *Snapshot) HasPrefixesAtRoot(rootID uint64, prefixes [][]byte) ([]bool, error)

func (*Snapshot) Iterator added in v0.6.0 

func (s *Snapshot) Iterator(start, end []byte) (iterator.UnsafeIterator, error)

Iterator returns an iterator bound to an existing snapshot.

func (*Snapshot) IteratorAtRoot added in v0.6.0 

func (s *Snapshot) IteratorAtRoot(rootID uint64, start, end []byte) (iterator.UnsafeIterator, error)

func (*Snapshot) IteratorAtRootWithOptions added in v0.6.0 

func (s *Snapshot) IteratorAtRootWithOptions(rootID uint64, start, end []byte, opts IteratorOptions) (iterator.UnsafeIterator, error)

func (*Snapshot) IteratorWithOptions added in v0.6.0 

func (s *Snapshot) IteratorWithOptions(start, end []byte, opts IteratorOptions) (iterator.UnsafeIterator, error)

IteratorWithOptions returns an iterator bound to an existing snapshot with explicit value materialization controls.

func (*Snapshot) Pager 

func (s *Snapshot) Pager() *pager.Pager

func (*Snapshot) ReaderAtRoot added in v0.6.0 

func (s *Snapshot) ReaderAtRoot(rootID uint64) (SnapshotRootReader, error)

func (*Snapshot) ReverseIterator added in v0.6.0 

func (s *Snapshot) ReverseIterator(start, end []byte) (iterator.UnsafeIterator, error)

ReverseIterator returns a reverse iterator bound to an existing snapshot.

func (*Snapshot) ReverseIteratorAtRoot added in v0.6.0 

func (s *Snapshot) ReverseIteratorAtRoot(rootID uint64, start, end []byte) (iterator.UnsafeIterator, error)

func (*Snapshot) ReverseIteratorAtRootWithOptions added in v0.6.0 

func (s *Snapshot) ReverseIteratorAtRootWithOptions(rootID uint64, start, end []byte, opts IteratorOptions) (iterator.UnsafeIterator, error)

func (*Snapshot) ReverseIteratorWithOptions added in v0.6.0 

func (s *Snapshot) ReverseIteratorWithOptions(start, end []byte, opts IteratorOptions) (iterator.UnsafeIterator, error)

ReverseIteratorWithOptions returns a reverse iterator bound to an existing snapshot with explicit value materialization controls.

func (*Snapshot) State 

func (s *Snapshot) State() *DBState

type SnapshotPool 

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

SnapshotPool manages a pool of Snapshot objects to reduce allocation overhead.

func NewSnapshotPool 

func NewSnapshotPool() *SnapshotPool

func (*SnapshotPool) Get 

func (p *SnapshotPool) Get() *Snapshot

func (*SnapshotPool) Put 

func (p *SnapshotPool) Put(s *Snapshot)

type SnapshotRootReader added in v0.6.0 

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

SnapshotRootReader is a root-bound read view owned by a Snapshot. It is valid only while the parent Snapshot remains open.

func (*SnapshotRootReader) GetAppend added in v0.6.0 

func (r *SnapshotRootReader) GetAppend(key, dst []byte) ([]byte, error)

func (*SnapshotRootReader) GetManyView added in v0.6.0 

func (r *SnapshotRootReader) GetManyView(keys [][]byte, fn GetManyViewFunc) error

type StandaloneLeafPageLogOptions added in v0.6.0 

type StandaloneLeafPageLogOptions struct {
	MaxSegmentBytes int64
	Compression     ValueLogCompressionMode
	AutoPolicy      ValueLogAutoPolicy
	BlockCodec      ValueLogBlockCodec
}

StandaloneLeafPageLogOptions configures a leaf-page log for direct backend users that enable IndexOuterLeavesInValueLog without the cached layer.

type StorageMaintenancePlan added in v0.6.0 

type StorageMaintenancePlan interface {
	StorageMaintenancePlanToken() storagemaintenance.Plan
}

StorageMaintenancePlan authorizes a physical storage-maintenance publish. It is intentionally opaque at the DB package boundary; recognized values are minted only by TreeDB-internal packages and external callers cannot create a value that validates the command-WAL maintenance bypass.

type StorageMaintenanceRootDeltaPublishInput added in v0.6.0 

type StorageMaintenanceRootDeltaPublishInput struct {
	BaseRoot      uint64
	Iter          iterator.UnsafeIterator
	StoragePolicy OrderedRootStoragePolicy
}

StorageMaintenanceRootDeltaPublishInput describes a root-local physical storage-maintenance rewrite. It is intentionally separate from OrderedRootDeltaPublishInput so ordinary logical root-delta callers do not inherit maintenance-only fields or semantics.

type UpdateFunc added in v0.6.0 

type UpdateFunc func(old []byte) (UpdateResult, error)

UpdateFunc transforms the current value for a key into a mutation. The old value is nil when the key is absent and is a safe copy when present. The callback may be retried if the key changes before the mutation commits.

type UpdateOp added in v0.6.0 

type UpdateOp uint8

UpdateOp describes the write produced by an Update callback. 

const (
	// UpdateNoop leaves the key unchanged.
	UpdateNoop UpdateOp = iota
	// UpdateSet replaces the key with Value.
	UpdateSet
	// UpdateDelete removes the key.
	UpdateDelete
)

type UpdateResult added in v0.6.0 

type UpdateResult struct {
	Op    UpdateOp
	Value []byte
}

UpdateResult is returned by an Update callback.

func DeleteUpdate added in v0.6.0 

func DeleteUpdate() UpdateResult

DeleteUpdate returns an Update result that removes the key.

func NoopUpdate added in v0.6.0 

func NoopUpdate() UpdateResult

NoopUpdate returns an Update result that leaves the key unchanged.

func SetUpdate added in v0.6.0 

func SetUpdate(value []byte) UpdateResult

SetUpdate returns an Update result that replaces the key with value.

type ValueLogAppender added in v0.6.0 

type ValueLogAppender interface {
	AppendValues(values [][]byte) ([]page.ValuePtr, error)
	Flush() error
	Sync() error
	CurrentValueLogSegment() (path string, fileID uint32, ok bool)
}

ValueLogAppender appends user values to the persistent value log and returns stable ValuePtr references that may be stored by native-root callers.

AppendValues must finish reading each values element before returning; callers may reuse or release the backing buffers once the call completes.

type ValueLogAutoPolicy added in v0.3.0 

type ValueLogAutoPolicy uint8

ValueLogAutoPolicy controls auto-mode dict vs block selection bias. 

const (
	ValueLogAutoBalanced ValueLogAutoPolicy = iota
	ValueLogAutoThroughput
	ValueLogAutoSize
)

type ValueLogBlockCodec added in v0.3.0 

type ValueLogBlockCodec uint8

ValueLogBlockCodec selects the block codec used for block compression modes. 

const (
	ValueLogBlockSnappy ValueLogBlockCodec = iota
	ValueLogBlockLZ4
	ValueLogBlockZSTD
)

type ValueLogCompressionMode added in v0.3.0 

type ValueLogCompressionMode uint8

ValueLogCompressionMode selects value-log compression behavior in cached mode. 

const (
	// ValueLogCompressionOff stores value-log grouped frames uncompressed.
	//
	// Zero is intentionally reserved as "unset/default".
	// db.Open normalizes zero to ValueLogCompressionAuto.
	ValueLogCompressionOff ValueLogCompressionMode = iota + 1
	// ValueLogCompressionBlock uses block compression without dictionaries.
	ValueLogCompressionBlock
	// ValueLogCompressionDict uses dictionary compression when available.
	ValueLogCompressionDict
	// ValueLogCompressionAuto adaptively chooses off/block/dict.
	ValueLogCompressionAuto
)

type ValueLogDictClassMode added in v0.4.0 

type ValueLogDictClassMode uint8

ValueLogDictClassMode controls whether dictionary state is shared across all value-log payloads or split by payload class. 

const (
	// ValueLogDictClassSingle keeps one shared dictionary stream for all
	// value-log payloads.
	ValueLogDictClassSingle ValueLogDictClassMode = iota
	// ValueLogDictClassSplitOuterLeaf keeps separate dictionary streams for
	// outer-leaf payloads and single-value payloads.
	ValueLogDictClassSplitOuterLeaf
)

type ValueLogDomainThreshold added in v0.4.0 

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
}

ValueLogDomainThreshold overrides inline-vs-pointer placement policy for keys under a domain prefix.

A key belongs to the first matching prefix after normalization (longest-prefix wins).

func NormalizeValueLogDomainThresholds added in v0.4.0 

func NormalizeValueLogDomainThresholds(in []ValueLogDomainThreshold) []ValueLogDomainThreshold

NormalizeValueLogDomainThresholds returns a deterministic longest-prefix-first copy suitable for hot-path threshold lookups.

It filters invalid entries (empty prefix or negative thresholds) and de-duplicates identical prefixes after sorting.

type ValueLogExternalRefFlusher added in v0.6.0 

type ValueLogExternalRefFlusher interface {
	FlushValueLogExternalRefs(fileIDs []uint32, sync bool) error
}

ValueLogExternalRefFlusher is an optional extension for appenders that can flush the value-log lanes containing specific file IDs. When sync is true, the implementation owns durability for the referenced file IDs: active segments should follow the appender's sync policy, and older referenced segments should be synced directly if needed. Command-WAL SetRID logging uses it to make freshly written pointer records visible before RID lookup without flushing unrelated lanes.

type ValueLogGCOptions added in v0.3.0 

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
	// ObservedSourceReclaimActive permits observed-only GC to reclaim an
	// otherwise-active segment. Callers must first prove the source is
	// unreferenced and fence cached writers past the source.
	ObservedSourceReclaimActive bool
}

ValueLogGCOptions controls value-log garbage collection.

type ValueLogGCStats added in v0.3.0 

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
}

ValueLogGCStats summarizes value-log GC work.

type ValueLogGenerationConfig added in v0.4.0 

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
}

ValueLogGenerationConfig configures generational value-log behavior.

type ValueLogGenerationPolicy added in v0.4.0 

type ValueLogGenerationPolicy uint8

ValueLogGenerationPolicy controls generation-aware value-log placement. PR1 scaffolding: behavior remains legacy append-only until allocator/rewrite phases land; this policy is currently configuration + observability only. 

const (
	// ValueLogGenerationDefault selects the library default (currently
	// hot/warm/cold in cached mode).
	//
	// This is intentionally the zero value so callers can opt into the default
	// behavior without explicitly setting a policy.
	ValueLogGenerationDefault ValueLogGenerationPolicy = iota
	// ValueLogGenerationOff keeps legacy single-generation behavior (no
	// background generation maintenance).
	ValueLogGenerationOff
	// ValueLogGenerationHotWarmCold enables hot/warm/cold generation policy.
	ValueLogGenerationHotWarmCold
)

type ValueLogOptions added in v0.3.0 

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
	// CurrentWritableMmap enables mmap-backed reads for current writable
	// value-log segments. This reduces random-read ReadAt syscall pressure at
	// the cost of a larger mapped virtual-address window.
	CurrentWritableMmap bool

	// 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
}

ValueLogOptions configures value-log pointer behavior and optional compression/dict tuning.

type ValueLogRewriteChunkPlan added in v0.4.0 

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
}

ValueLogRewriteChunkPlan mirrors ValueLogRewritePlan, but at chunk granularity. It is intended for future incremental rewrite scheduling work.

type ValueLogRewriteLocalityPolicy added in v0.4.0 

type ValueLogRewriteLocalityPolicy string

ValueLogRewriteLocalityPolicy controls pointer rewrite ordering. 

const (
	// ValueLogRewriteLocalityDefault preserves scan/input order.
	ValueLogRewriteLocalityDefault ValueLogRewriteLocalityPolicy = "default"
	// ValueLogRewriteLocalityGrouped orders by old segment+offset locality.
	ValueLogRewriteLocalityGrouped ValueLogRewriteLocalityPolicy = "grouped"
)

type ValueLogRewriteOnlineOptions added in v0.4.0 

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.
	//
	// Cleanup also avoids zombifying currently-active pre-existing segments
	// because concurrent writers may still be appending records whose pointers
	// are not yet visible in the backend index.
	ProtectedPaths []string
	// LeafGenerationProtectedRootIDs are additional roots to preserve if rewrite
	// cleanup runs leaf-generation GC after publishing rewritten value pointers.
	LeafGenerationProtectedRootIDs []uint64
	// LeafGenerationProtectedSystemRootIDs are system roots whose collection
	// descriptors should be expanded if rewrite cleanup runs leaf-generation GC.
	LeafGenerationProtectedSystemRootIDs []uint64
	// 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)
}

ValueLogRewriteOnlineOptions controls online rewrite behavior.

type ValueLogRewritePlan added in v0.4.0 

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 added in v0.4.0 

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

ValueLogRewritePlanChunk summarizes one sub-file chunk of a value-log segment. This is a planning primitive for future incremental rewrite work; it does not yet change execution.

type ValueLogRewritePlanSegment added in v0.4.0 

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

ValueLogRewritePlan summarizes which segments a sparse online rewrite would target given the current value-log set and selection knobs.

It is intended for cached-mode maintenance schedulers to decide whether a rewrite run is worth performing without forcing the rewrite implementation to do expensive live-byte estimation work twice.

type ValueLogRewriteStats added in v0.3.0 

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
	// SourceSegmentsReclaimed is the number of unreferenced source segments
	// deleted by a caller-managed reclaim path after rewrite. Backend rewrite
	// itself leaves this zero when active/protected segment safety prevents
	// immediate deletion.
	SourceSegmentsReclaimed int
	// SourceBytesReclaimed is the number of unreferenced source bytes deleted by
	// a caller-managed reclaim path after rewrite.
	SourceBytesReclaimed int64

	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
}

ValueLogRewriteStats summarizes rewrite compaction results.

func ValueLogRewriteOffline added in v0.3.0 

func ValueLogRewriteOffline(opts Options) (ValueLogRewriteStats, error)

ValueLogRewriteOffline rewrites value-log pointers into new segments and swaps index.db to reference the new log. This is an offline operation (requires exclusive lock and a clean commitlog).

type WritePolicy 

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

WritePolicy defines the heuristics and thresholds for write operations.

func DefaultWritePolicy 

func DefaultWritePolicy() WritePolicy

DefaultWritePolicy returns the default policy.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.