Segments

A segment is an ordered record set.

ZoneTree uses segments as the movement units of the storage engine. Writes start in a writable memory segment, frozen memory segments are merged into disk segments, and large disk segments can move into the bottom segment queue.

writes
  |
  v
mutable segment
  |
  | move forward
  v
read-only segment queue
  |
  | merge
  v
DiskSegment
  |
  | exceeds DiskSegmentMaxItemCount
  v
bottom segment queue

Storage Layers

Layer	Code shape	Meaning
Mutable segment	`IMutableSegment`	Writable in-memory segment protected by a WAL.
Read-only segments	`IReadOnlySegment` queue	Frozen in-memory segments waiting for merge.
`DiskSegment`	`IDiskSegment` slot	Persistent disk segment used by normal merge.
Bottom segments	`IDiskSegment` queue	Persistent disk segments below the `DiskSegment` slot.

Disk Segment Shapes

In code, IDiskSegment<TKey, TValue> is the important abstraction. It means "a persistent segment ZoneTree can read, merge, back up, and drop."

IDiskSegment
  |
  +-- single-part disk segment
  |
  +-- multipart disk segment

Term	Meaning
Disk segment	Persistent ordered segment.
Single-part disk segment	One physical disk segment layout.
Multipart disk segment	One logical disk segment made from ordered parts.
Part	Reusable disk segment inside a multipart disk segment.

Single-part disk segments have four physical variations. ZoneTree chooses the variation from the key and value shape:

Variation	Used when
Fixed-size key + fixed-size value	both key and value have fixed unmanaged size
Fixed-size key + variable-size value	key has fixed unmanaged size, value is variable-size
Variable-size key + fixed-size value	key is variable-size, value has fixed unmanaged size
Variable-size key + variable-size value	both key and value are variable-size

These variations let compact unmanaged keys or values use simpler disk layouts, while strings, arrays, reference types, and other variable-size serialized values use header/offset layouts.

Single-Part And Multipart

A single-part disk segment owns its physical files directly.

single-part disk segment
  segment id: 10
  files:
    10.data.z
    10.data.h.z
    10.sparse.z

A multipart disk segment owns a small descriptor and points to ordered disk-segment parts.

multipart disk segment
  segment id: 20
  descriptor:
    20.multi
  parts:
    segment id: 11
    segment id: 12
    segment id: 13

From the outside, both are one IDiskSegment. They expose one logical record count, one ordered keyspace, and the same read/merge/drop surface.

Why Multipart Exists

Multipart disk segments let ZoneTree carry unchanged parts forward during merge.

old disk segment:
[ A ][ B ][ C ][ D ]

new records overlap B

new disk segment:
[ carry A ][ write B2 ][ carry C ][ carry D ]

The old part files are immutable. ZoneTree does not patch them in place. A clean part can be reused by the next logical disk segment, while changed ranges are written as new parts.

Null Disk Segment

NullDiskSegment<TKey, TValue> is an empty placeholder for the DiskSegment slot.

It appears when there is no disk segment in that slot, for example after a large disk segment moves into the bottom segment queue.

DiskSegment slot:
  NullDiskSegment

bottom segment queue:
  disk segment 101
  disk segment 102

Common Names

Name	Refers to
`MutableSegmentMaxItemCount`	record count limit before the mutable segment moves forward
`DiskSegmentMaxItemCount`	record count limit before `DiskSegment` moves to bottom segments
`ReadOnlySegmentsCount`	frozen in-memory segment count
`MutableSegmentRecordCount`	records in the writable memory segment
`ReadOnlySegmentsRecordCount`	records across frozen memory segments
`TotalRecordCount`	physical records across mutable, read-only, disk, and bottom segment layers

For the full storage flow, see LSM Tree. For multipart merge behavior, see write amplification.