zipper

type ApplyOptions struct {
	// PrepareReadOnly asks ApplyWithOptions to run the read-only preparation
	// pass before applying the delta. This is opt-in because it traverses the
	// captured root in addition to the apply pass. It does not publish roots,
	// allocate output pages, append leaf/value-log records, retire old pages, or
	// transfer durable output ownership.
	PrepareReadOnly bool

	// ReadOnlyPrepare reuses buffers for the optional read-only preparation
	// pass. It is ignored unless PrepareReadOnly is true or ParallelApplyConcurrency
	// requests opt-in parallel apply gating.
	ReadOnlyPrepare ReadOnlyPrepareOptions

	// ReadOnlyPrepareWorkers requests deterministic leaf-span worker ranges for
	// reporting. Values <=0 use ParallelApplyConcurrency when opt-in parallel
	// apply is requested.
	ReadOnlyPrepareWorkers int

	// ParallelApplyConcurrency enables the M2 opt-in COW apply worker-pool path.
	// Values <=1 leave the existing apply path unchanged. The effective worker
	// count is also bounded by GOMAXPROCS, planned leaf spans, span bytes, and the
	// minimum work thresholds below.
	ParallelApplyConcurrency int
	// ParallelApplyWorkerPool supplies reusable workers for opt-in parallel apply.
	// If nil, ApplyWithOptions falls back to the existing per-call worker path.
	ParallelApplyWorkerPool *ApplyWorkerPool
	// ParallelApplyMinSpans gates opt-in worker-pool apply by planned leaf spans.
	// Values <=0 disable the span-count gate.
	ParallelApplyMinSpans int
	// ParallelApplyMinSpanOps gates opt-in worker-pool apply by span-local work.
	// Values <=0 disable the op-count gate.
	ParallelApplyMinSpanOps int
	// ParallelApplyMinSpanBytes gates opt-in worker-pool apply by estimated bytes.
	// Values <=0 disable the byte-count gate.
	ParallelApplyMinSpanBytes int

	// SpanNativeApply enables the M10 opt-in span-native apply candidate path.
	// The initial gate is deliberately narrower than M2 parallel COW apply: exact
	// point-only leaf spans, no cold build, no maintenance rewrite, and bounded
	// workers. Unsupported runs fail closed to the recursive apply fallback.
	SpanNativeApply bool
	// SpanNativeAllowMaintenancePointOps lets trusted ordered-root callers use
	// span-native apply for point-delete maintenance plans whose tombstone/edge
	// semantics are intentionally preserved. Raw DB apply must leave this false so
	// delete maintenance keeps using the recursive path that prunes and rebalances
	// empty or underfull pages.
	SpanNativeAllowMaintenancePointOps bool
	// SpanNativeForceFallbackReason forces a prepared span-native candidate to use
	// the safe recursive/parallel fallback and report this stable reason string.
	// It is used by checkpoint/close drains and emergency gates that must not
	// produce span-native durable output.
	SpanNativeForceFallbackReason string
}

type ApplyResult struct {
	RootID              uint64
	PendingRetiredPages []uint64
	Metrics             adaptive.Metrics

	// ReadOnlyPrepare is populated only when ApplyOptions.PrepareReadOnly is
	// true or opt-in parallel apply needs the M1 span plan for gating. It is
	// planning metadata only; it owns no pager or leaf-log output.
	ReadOnlyPrepare ReadOnlyPrepareResult
	// ReadOnlyPrepareNs is the time spent in the optional read-only preparation
	// pass. It is zero when no read-only preparation ran.
	ReadOnlyPrepareNs uint64
	// ReadOnlyPrepareRequested reports that read-only preparation was requested
	// explicitly or by the opt-in parallel apply gate.
	ReadOnlyPrepareRequested bool
	// ReadOnlyPrepareValidationFailed distinguishes validation failures from
	// read/decode failures for stats.
	ReadOnlyPrepareValidationFailed bool
	// ReadOnlyPrepareFailed distinguishes read/decode failures from later apply
	// failures for callers that need stable fallback labels.
	ReadOnlyPrepareFailed bool
	// ReadOnlyPrepareWorkerSummary is the deterministic worker-range aggregate for
	// the requested read-only worker target.
	ReadOnlyPrepareWorkerSummary ReadOnlyLeafSpanWorkerRangeSummary
	// ParallelApplyWorkers is the effective opt-in worker count selected after
	// applying all gates. ParallelApplyUsed is true when that count was >1.
	ParallelApplyWorkers int
	ParallelApplyUsed    bool

	// SpanNativeEligible reports that the M10 opt-in span-native gate accepted the
	// read-only plan. SpanNativeWorkers is the bounded worker count selected for
	// future span jobs. SpanNativeUsed remains false until the real span-native
	// execution engine replaces recursive fallback for eligible runs.
	SpanNativeEligible bool
	SpanNativeWorkers  int
	SpanNativeUsed     bool
	// SpanNativeFallbackReason is a stable fallback reason string when the
	// span-native candidate failed closed before, during, or after execution. DB
	// callers map it onto their append-only fallback reason enum for stats.
	SpanNativeFallbackReason string
}

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

type LeafPageBatchLog interface {
	AppendLeafPages(leafPages [][]byte) ([]page.LeafLogPtr, error)
}

type LeafPageConcurrentAppendLog interface {
	ConcurrentLeafPageAppends() bool
}

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

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

type LeafPagePreparedAppendLog interface {
	PreparedLeafPageAppends() bool
}

type LeafPagePreparedBatchAppendLog interface {
	PreparedLeafPageBatchAppends() bool
}

type LeafPagePreparedBatchLog interface {
	AppendPreparedLeafPages(leafPages [][]byte, preparedPayloads [][]byte) ([]page.LeafLogPtr, error)
}

type LeafPagePreparedChildRefBatchLog interface {
	AppendPreparedLeafPageChildRefs(leafPages [][]byte, preparedPayloads [][]byte, refs []page.ChildRef) ([]page.ChildRef, error)
}

type LeafPagePreparedLog interface {
	AppendPreparedLeafPage(leafPage []byte, preparedPayload []byte) (page.LeafLogPtr, error)
}

type LeafPageReader interface {
	ReadUnsafe(ptr page.ValuePtr) ([]byte, error)
}

type PageAllocator interface {
	Alloc(hint uint64) (uint64, error)
}

type ParallelMergePressureLevel uint8

type ParallelMergePressureSource func() ParallelMergePressureLevel

type ReadOnlyLeafSpan struct {
	// Ref identifies the existing leaf that owns this span. When ColdBuild is
	// true there is no existing leaf; Ref is the zero ChildRef and is not
	// actionable.
	Ref page.ChildRef

	// LowKey is the inclusive lower bound for the leaf span. HighKey is the
	// exclusive upper bound. A nil bound is open-ended. Non-nil bound slices and
	// op-key slices are owned by ReadOnlyPrepareResult until ReuseOptions is used.
	LowKey  []byte
	HighKey []byte

	// FirstOpKey and LastOpKey describe the point operations assigned to this
	// span. They are nil for range-only spans.
	FirstOpKey []byte
	LastOpKey  []byte

	// OpCount is the span-local work count: PointOpCount plus DeleteRangeCount.
	// Delete ranges that overlap multiple leaves are counted once per touched
	// span, because future workers need each overlapping range in every touched
	// leaf span.
	OpCount          int
	PointOpCount     int
	DeleteRangeCount int
	ByteCount        int

	// PointOpStart/PointOpEnd index the canonical point-op slice returned by the
	// batch apply plan. DeleteRangeStart/DeleteRangeEnd index the canonical merged
	// delete-range slice. The ranges are half-open and intended for future worker
	// construction; they do not keep the originating batch alive.
	PointOpStart     int
	PointOpEnd       int
	DeleteRangeStart int
	DeleteRangeEnd   int
}

type ReadOnlyLeafSpanSummary struct {
	// Ops is the logical root apply operation count: canonical point ops plus
	// canonical delete ranges.
	Ops          int
	PointOps     int
	DeleteRanges int

	// SpanOps and SpanBytes are summed over spans. SpanOps may exceed Ops when a
	// delete range overlaps multiple leaf spans.
	SpanOps   int
	SpanBytes int
	Spans     int

	ExactLeafSpans bool
	ColdBuild      bool
	Maintenance    bool

	// MinSpanOps/MaxSpanOps and MinSpanBytes/MaxSpanBytes are zero when Spans is
	// zero.
	MinSpanOps    int
	MaxSpanOps    int
	MinSpanBytes  int
	MaxSpanBytes  int
	SingleOpSpans int
	OpenLowSpans  int
	OpenHighSpans int
}

type ReadOnlyLeafSpanWorkerRange struct {
	FirstSpan int
	SpanCount int
	Ops       int
	Bytes     int
}

type ReadOnlyLeafSpanWorkerRangeSummary struct {
	TargetWorkers    int
	Ranges           int
	Ops              int
	Bytes            int
	MinRangeOps      int
	MaxRangeOps      int
	MinRangeBytes    int
	MaxRangeBytes    int
	SingleSpanRanges int
}

type ReadOnlyPrepareOptions struct {
	// OmitKeys skips copying span boundary and first/last op key bytes for
	// point-only plans. It is for hot-path aggregate/chunk planning that only
	// needs op indexes/counts; callers that consume exact span bounds for future
	// execution should leave it false. Plans containing delete ranges retain keys
	// because range-overlap planning needs exact span bounds.
	OmitKeys bool

	// DiscardLeafSpans streams spans to LeafSpanCallback without retaining them in
	// the result. It is only for aggregate/chunk planning callers that do not need
	// ValidateLeafSpans or exact span ownership after PrepareReadOnlyPlan returns.
	DiscardLeafSpans bool
	LeafSpanCallback func(ReadOnlyLeafSpan)

	// AllowMaintenancePointLeafSpans marks point-delete maintenance plans as exact
	// prepared-output ownership for ordered-root span-native apply. Normal raw DB
	// maintenance leaves this false so the prepared spans remain planning hints.
	AllowMaintenancePointLeafSpans bool
	// contains filtered or unexported fields
}

type ReadOnlyPrepareResult struct {
	RootID       uint64
	Ops          int
	PointOps     int
	DeleteRanges int
	ColdBuild    bool
	Maintenance  bool
	OmitKeys     bool

	// ExactLeafSpans is true when LeafSpans fully describe the existing leaves
	// touched by the delta. Delete-containing maintenance can merge/rebalance
	// adjacent leaves, so its direct key spans are useful planning hints but are
	// not complete prepared-output ownership. Range deletes do not enable
	// maintenance in the current apply path, so their overlapping leaf spans are
	// exact for planning purposes.
	ExactLeafSpans bool

	LeafSpans []ReadOnlyLeafSpan
	Metrics   adaptive.Metrics
	// contains filtered or unexported fields
}

type Split struct {
	Key []byte
	Ref page.ChildRef
}

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