timslite 0.1.7

High-performance mmap-backed time-series storage engine with queues and journal.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
# 数据段管理 - DataSegmentSet + DataSegment

## 五、DataSegmentSet: 数据段集合

### 5.1 职责

- 管理同一数据集下的多个 DataSegment 文件
- 按索引中的 `block_offset` 路由到正确的数据段
- 自动创建新文件 (当前文件满或 sealed 时)
- 数据读取时跨段迭代

### 5.2 结构

```rust
struct DataSegmentSet {
    base_dir: PathBuf,
    segment_size: u64,
    initial_segment_size: u64,    // 初始分配大小
    compress_level: u8,
    compress_type: u8,
    segments: BTreeMap<u64, DataSegmentEntry>, // key = data segment file_offset
    next_offset: u64,
    last_used_at: Instant,
}
```

### 5.3 生命周期管理

```rust
impl DataSegmentSet {
    /// sync 所有打开的 data segment
    pub fn sync_all(&mut self) -> Result<()>;

    /// idle-close 所有 data segment
    pub fn idle_close_all(&mut self) -> Result<()>;

    /// 按需打开已关闭的 segment
    pub fn lazy_open(&mut self, file_offset: u64) -> Result<&mut DataSegment>;

    /// 加载已有的 data segment 元数据 (Store open 时)
    pub fn load_existing(base_dir: &Path, segment_size: u64,
                         compress_level: u8, compress_type: u8) -> Result<Self>;
}
```

`compress_type` 是算法选择真源。append/seal/create single-record 路径使用当前 segment header / `DataSegmentSet.compress_type` 选择算法, `compress_level` 只表示该算法的级别。

> `DataSet::sync_all()` 需要同时调用 `segments.sync_all()` + `time_index.sync_all()`。
> `DataSet::idle_close_all()` 同理。

## 六、DataSegment: 单个数据段 (Block 管理核心)

### 6.1 结构

```rust
struct DataSegment {
    path: PathBuf,
    file_offset: u64,             // 数据区逻辑全局起点, 等于数据段文件名
    file_size: u64,              // 运行时当前文件大小 (随扩容增长)
    max_file_size: u64,          // 扩容上限 (segment_size, 不可变)
    min_timestamp: i64,          // 段内最小时间戳 (i64::MAX=空段)
    max_timestamp: i64,          // 段内最大时间戳 (i64::MIN=空段)
    header_len: u64,             // 从文件头计算出的数据区起点
    data_wrote_position: u64,    // 运行时数据区内已用字节数; header state wrote_position 保存文件内绝对偏移
    record_count: u64,
    total_uncompressed_size: u64,
    created_at: i64,
    mmap: Option<MmapMut>,       // None = closed/unmapped
    lifecycle: SegmentLifecycle,
    last_accessed_at: Instant,
    is_flushed: bool,            // 内存态: 当前 mmap 内容是否已 MS_SYNC
    queued_for_flush: bool,      // 内存态: dirty 后是否已进入 runtime flush 队列
    // Pending Block 状态
    pending_block_offset: Option<u64>, // block_segment_offset
    pending_wrote_position: u64,
    pending_record_count: u64,
}

enum SegmentLifecycle {
    Closed,          // 文件未打开, mmap=None
    OpenReady,       // 打开中, mmap 有效, 可读写
}

const BLOCK_HEADER_SIZE: u64 = 16;
const DATA_HEADER_SIZE: u64 = 124;  // v1 默认数据段 header_len
```

`DataSegmentSet` 接收索引中的 `block_offset`, 通过 `segment_size` 计算所属数据段:

```text
segment.file_offset = (block_offset / segment_size) * segment_size
block_segment_offset = block_offset - segment.file_offset
physical_file_offset = segment.header_len + block_segment_offset
```

`DataSegment` 内部读写使用数据区相对坐标: `block_segment_offset` 与运行时 `data_wrote_position` 均不包含 header。文件 header state 中的 `wrote_position` 持久化为文件内绝对偏移, 即 `header_len + data_wrote_position`; 打开文件时必须减去动态 `header_len` 恢复运行时相对坐标。任何 mmap/seek 位置都必须再加 `header_len`。

### 6.2 文件布局

```
┌──────────────────────────────────────────────────┐
│ DataFileHeader (variable, v1 default 124 bytes)  │
│ - 固定前缀: magic(4)+version(2)+fileType(1)+     │
│   meta_length(2)                                 │
│ - Meta(TLV, 41B): created_at, file_offset,       │
│   file_size, compress_level, compress_type       │
│ - state_length: 2                                │
│ - State(72B): 9×8B                               │
│   min_timestamp, max_timestamp, wrote_position,  │
│   record_count, total_uncompressed_size,         │
│   pending_block_offset, pending_wrote_position,  │
│   pending_record_count, invalid_record_count     │
├──────────────────────────────────────────────────┤
│ Block 1 (sealed, compressed)                     │
│   BlockHeader (16 bytes)                         │
│   Payload (compressed records)                   │
├──────────────────────────────────────────────────┤
│ Block 2 (sealed, compressed)                     │
├──────────────────────────────────────────────────┤
│ Current Pending Block (未完成, 未压缩)             │
│   BlockHeader (16 bytes, flags=0)               │
│   Payload (raw records)                          │
└──────────────────────────────────────────────────┘
```

### 6.3 写入核心逻辑

```rust
impl DataSegment {
    fn append_record(
        &mut self,
        timestamp: i64,
        data: &[u8],
        compress_level: u8,
    ) -> io::Result<(u64, u16)> {
        let record_size = align_up(4 + 8 + data.len(), 4);

        // 情况1: 单条 record stored span 超过 BLOCK_MAX_SIZE(256KiB) → 独占 Block
        if record_size > BLOCK_MAX_SIZE as usize {
            if let Some(off) = self.pending_block_offset {
                self.seal_pending_block(off, compress_level)?;
                self.clear_pending();
            }
            return self.create_single_record_block(timestamp, data, compress_level);
        }

        // 情况2: 有 pending block
        if let Some(pending_off) = self.pending_block_offset {
            let new_total = self.pending_block_uncomp_size + record_size as u32;

            if new_total > BLOCK_MAX_SIZE {
                self.seal_pending_block(pending_off, compress_level)?;
                self.clear_pending();
                return self.create_pending_and_append(timestamp, data);
            }

            let in_block_offset_units = self.pending_block_uncomp_size / 4;
            self.write_raw_record_to_pending(timestamp, data)?;
            self.pending_block_uncomp_size = new_total;
            self.pending_block_record_count += 1;
            return Ok((pending_off, in_block_offset_units));
        }

        // 情况3: 创建新 pending block
        self.create_pending_and_append(timestamp, data)
    }

    /// 密封 pending block: 使用 selected algorithm 压缩+写回
    fn seal_pending_block(&mut self, block_segment_offset: u64, compress_level: u8) -> io::Result<()>;
    fn write_raw_record_to_pending(&mut self, timestamp: i64, data: &[u8]) -> io::Result<()>;
    fn create_pending_and_append(&mut self, timestamp: i64, data: &[u8]) -> io::Result<(u64, u16)>;
    fn create_single_record_block(&mut self, timestamp: i64, data: &[u8], compress_level: u8) -> io::Result<(u64, u16)>;

    /// 纠正写入: 在该段最后一个 pending raw block 的最末 record 位置原地覆盖 data 字节, 支持 tail-only 变 size
    /// 若最后一个 block 含 SEALED 或 COMPRESSED flag → 返回错误 (不可原地修改)
    /// 若该 record 不是 block 最末 record → 返回错误
    /// 修改后需更新: block.payload_size/uncompressed_size + 段 wrote_position/total_uncompressed_size/pending_wrote_position(仅 pending)
    fn overwrite_in_last_block(
        &mut self,
        block_segment_offset: u64,
        in_block_offset: u16,
        new_data: &[u8],
    ) -> io::Result<()>;

    /// append 写入: 只允许向本段最后一个 pending raw block 的最末 record 追加 bytes
    /// 返回 append 前的 old_data_len, 供 journal 记录 data_offset
    fn append_to_last_record(
        &mut self,
        block_segment_offset: u64,
        in_block_offset: u16,
        append_data: &[u8],
    ) -> io::Result<u32>;
}
```

**append 发布顺序约束**:

`DataSegment::append_record` 返回的 `(block_segment_offset, in_block_offset)` 会被 `DataSet` 与当前 `segment.file_offset` 合成为 `block_offset`, 再写入 `TimeIndex`。因此 data segment 侧必须先完成 record payload 和 block/header state 更新, 再让上层发布 index entry。对于新 pending block、追加 pending block、exclusive/single-record block 三类路径, 设计上的可见性顺序都是:

1. 写入 record payload。
2. 写入或更新 `BlockHeader` 与 data segment state。
3. 返回 offset 给 `DataSet`, 由 `DataSet` 最后写 index。

如果 crash 发生在第 3 步之前, 已写入 data segment 但未被 index 引用的数据视为丢失; 查询不会扫描 data segment 来发现它。如果 crash 发生在 index 发布之后但 data/index 落盘顺序不完整, 读取路径必须通过 block 边界和 record timestamp 校验避免返回错位数据。

#### overwrite_in_last_block: 纠正写入 (In-Place Overwrite, 支持变 size)

纠正写入场景下 (`latest_written_timestamp == Some(timestamp)`), 该最大已写 timestamp 对应的记录只有在仍位于 **本数据段最后一个 pending raw block (`flags=0`)** 的 **最末位置** 时, 才可通过 mmap 直接修改该 record 的 data 字节, 支持 data 长度变化。该能力是 tail-only resize: 仅改写当前 record header/data 和尾部计数, 不移动任何后续 block/record 字节; 如果校验发现 record 后仍有字节, 直接返回错误并由 `DataSet::correct_write` 回退为乱序追加并更新索引。只要 block 已经 sealed/compressed, 也不能再原地修改:

```rust
fn overwrite_in_last_block(
    &mut self,
    block_segment_offset: u64,
    in_block_offset: u16,
    new_data: &[u8],
) -> io::Result<()> {
    // 1. 验证这是段内最后一个 block:
    //    block_abs_end = block_segment_offset + BLOCK_HEADER_SIZE + block.payload_size
    //    若 block_abs_end < self.data_wrote_position → 不是最后 block, 返回错误
    //
    // 2. 读取 block header (16B at header_len + block_segment_offset)
    //    - 检查 flags: 必须等于 0; 若含 SEALED 或 COMPRESSED → 返回错误
    //    - payload_size / uncompressed_size
    //
    // 3. 验证 record 是块内最末 record:
    //    - 读取 record.data_len (4 bytes at record_pos)
    //    - 若 in_block_offset + 12 + old_data_len != payload_size → 错误
    //
    // 4. 计算 delta = (new_data.len() + 12) - (old_data_len + 12) = new_data.len() - old_data_len
    //
    // 5. 修改 mmap 中 record 的 data_len (u32) 和 data 字节 (覆盖/扩展)
    //    record_pos = header_len + block_segment_offset + BLOCK_HEADER_SIZE + in_block_offset
    //
    // 6. 更新 block header:
    //    - payload_size       += delta  (block 内 payload 长度变化)
    //    - uncompressed_size  += delta  (block 内原始数据长度变化)
    //
    // 7. 更新段内计数字段:
    //    - self.data_wrote_position         += delta
    //    - self.total_uncompressed_size     += delta
    //    - if block is pending (pending_block_offset.matches):
    //        self.pending_wrote_position += delta
    //        更新 file header pending_wrote_position
    //    - 更新 file header wrote_position = header_len + data_wrote_position
}
```

> **前置条件**:
> - 调用方已通过 `time_index.find_entry(timestamp)` 获取 `(block_offset, in_block_offset)`, 并在 `DataSegmentSet` 层转换为当前段的 `block_segment_offset`
> - 调用方已验证该 record 位于最新数据段
> - block.flags = 0 (pending raw)
> - record 是 block 内最末 record
>
> **不支持 byte-shift**: correction 变长覆盖只允许 tail-only resize。新 data 可以变大或变小, 但 record 必须已经是最新 pending raw block 的最后一条记录, 且 record 末尾必须等于当前 block/data 尾部。实现不得移动任何后续 block/record 字节; 只更新该 record 的 `data_len`、payload bytes、block 计数和 segment 计数。若校验发现 record 后仍有字节、block 已 sealed/compressed 或目标不是最新尾部记录, 返回错误并由 `DataSet::correct_write` fallback 为 append 新 record + 更新 index。

#### append_to_last_record: 追加写入 (Tail Append)

append 追加场景下 (`latest_written_timestamp == Some(timestamp)`), 目标 record 必须位于 **本数据段最后一个 pending raw block (`flags=0`)** 的 **最末位置**, 且 record 末尾必须等于数据段当前运行时 `data_wrote_position`。该方法只负责原地增长; `DataSet` 层必须在调用前完成 4MiB 上限判断。append 不再因为比例阈值迁移为 exclusive/single-record block, 若增长后普通 pending block 无法承载则直接返回错误。

```rust
fn append_to_last_record(
    &mut self,
    block_segment_offset: u64,
    in_block_offset: u16,
    append_data: &[u8],
) -> io::Result<u32> {
    // 1. 验证 block 是段内最后一个 block:
    //    block_abs_end = block_segment_offset + BLOCK_HEADER_SIZE + block.payload_size
    //    block_abs_end 必须等于 self.data_wrote_position
    //
    // 2. 读取 block header:
    //    - flags 必须等于 0; compressed/sealed 均返回错误
    //    - payload_size 必须等于 uncompressed_size
    //
    // 3. 验证 record 是块内最末 record:
    //    - old_data_len = read_u32(record_pos)
    //    - in_block_offset + 12 + old_data_len 必须等于 payload_size
    //
    // 4. final_data_len = old_data_len + append_data.len()
    //    - final_data_len 必须 <= 4MiB
    //    - 12 + final_data_len 必须 <= BLOCK_MAX_SIZE
    //
    // 5. 在 mmap 中更新 record.data_len 并把 append_data 复制到 old data 后方
    //
    // 6. 更新 block header:
    //    - payload_size      += append_data.len()
    //    - uncompressed_size += append_data.len()
    //
    // 7. 更新段 state:
    //    - self.data_wrote_position     += append_data.len()
    //    - self.total_uncompressed_size += append_data.len()
    //    - self.pending_wrote_position  += append_data.len()
    //    - record_count/min_timestamp/max_timestamp 不变
    //
    // 8. 返回 old_data_len, 作为 journal 0x13 append_info.data_offset
}
```

与 `overwrite_in_last_block` 的差异:

1. append 只增长 record data, 不支持缩小或替换已有 data。
2. append 失败不回退为乱序写入; compressed block、非末尾 record、历史段都直接返回错误。
3. append 修改已存在 latest record 时只允许原地追加; 不触发独占 block 迁移。
4. 原地 append 不改变索引, 因为 record 起始位置不变。


### 6.4 读取: 通过索引定位 Block 内 record (含缓存)

```rust
struct SegmentReadEntry {
    timestamp: i64,
    block_segment_offset: u64,
    in_block_offset: u16,
}

impl DataSegment {
    fn read_at_index(
        &self,
        entry: &SegmentReadEntry,
        cache: Option<&BlockCache>,
    ) -> io::Result<(i64, Vec<u8>)> {
        let m = self.mmap.as_ref().ok_or_else(|| io::Error::new(io::ErrorKind::NotConnected, "segment closed"))?;
        let hdr_pos = self.header_len as usize + entry.block_segment_offset as usize;
        let block_segment_offset = entry.block_segment_offset;

        // 读取 block header, 校验 SEALED/COMPRESSED 必须同时存在或同时不存在
        // 仅 sealed+compressed block 允许查询全局缓存
        // compressed 未命中 → 从 mmap 读取 + 解压 → 存入全局缓存
        // pending raw block → 直接从 mmap 复制 payload, 不进入全局缓存
        // 定位 record → 返回 (timestamp, data)
    }
}
```

> **安全性保证**: 只有 `SEALED|COMPRESSED` block 的解压 payload 才能进入全局 `BlockCache`。pending raw block 仍在写入中, 不能进入全局缓存。sealed raw block 为非法状态。compressed block 一旦写入后不允许原地修改。
>
> **Header 起点约束**: 进入 `DataSegment` 后的 `block_segment_offset` 表示相对数据区起点的偏移, 即 `block_offset - segment.file_offset`; 运行时 `data_wrote_position` 也是相对数据区起点的已用字节数。物理文件位置必须通过 `segment.header_len + block_segment_offset` 计算。新建 v1 文件的 `header_len` 为 124, 但打开文件时必须使用 header 中的 `meta_length/state_length` 动态计算。索引中的 `block_offset` 是数据区逻辑全局偏移, 不可直接作为文件内 seek 位置。文件 header state 的 `wrote_position` 唯一保存形式是文件内绝对偏移: `header_len + data_wrote_position`。

### 6.5 生命周期方法

```rust
impl DataSegment {
    /// 确保 mmap 有效 (closed → open + mmap + pending恢复)
    pub fn ensure_open(&mut self, compress_level: u8) -> Result<()>;

    /// sync → unmmap → close, 不 seal、不压缩、不清 pending
    pub fn idle_close(&mut self, compress_level: u8) -> Result<()>;

    /// 仅 msync (不 seal/不压缩)
    pub fn sync(&mut self) -> Result<()>;

    /// 创建新 segment (初始分配 initial_size)
    pub fn create(path: &Path, file_offset: u64, initial_size: u64, max_size: u64) -> Result<Self>;

    /// 打开已有 segment (以磁盘实际大小为准)
    pub fn open(path: &Path, file_offset: u64, max_file_size: u64) -> Result<Self>;

    /// 扩容: unmap → set_len(target) → remap → 更新内存字段
    /// header file_size 不变 (始终为 max)
    pub fn expand(&mut self) -> Result<()>;
}
```

### 6.5.1 DataSegmentSet 分段注册表与定位

`DataSegmentSet` 使用单个 `BTreeMap<u64, DataSegmentEntry>` 保存所有数据分段, key 为 `file_offset`:

- `DataSegmentEntry::Open(DataSegment)`: 当前 mmap/open 的分段。
- `DataSegmentEntry::Closed(DataSegmentMeta)`: 已 idle-close 或 load-existing 后尚未打开的分段元数据。

该注册表天然按 `file_offset` 升序维护。任何生命周期迁移都只改变同一 key 下的 entry 状态, 不在 open/closed 两个列表之间搬移:

- load-existing 扫描磁盘后插入 `Closed` entry。
- lazy-open: 通过 `file_offset` 在 `BTreeMap` 中 O(log n) 命中, 若为 `Closed` 则打开文件并替换为 `Open`。
- idle-close: 遍历 registry, 将 `Open` sync+unmap 后替换为 `Closed`。
- 新建 segment: 以新 `file_offset` 插入 `Open` entry。

最高 `file_offset` 的 data segment 是 inspect 统计中的 active tail segment。active tail 的判定只看 `file_offset`,不看 `Open` / `Closed` 生命周期状态;即使它已被 idle-close, 仍然是当前可能继续追加写入的尾段。`DataSegmentSet` 创建下一 data segment 前, 旧 active tail 才通过窄 state sink 进入 dataset state 文件的归档统计。

`DataSegmentMeta` 只承担 lazy-open、路由和段级过滤所需的元数据缓存,不扩展为保存整个 dataset inspect 汇总。归档分段的 `record_count`、`data_wrote_position`、`uncompressed_size`、`invalid_record_count` 汇总由 `{dataset_dir}/state` 文件保存;普通 inspect 不需要打开所有历史 data segment。

定位规则:

```text
segment_file_offset = (block_offset / data_segment_size) * data_segment_size
```

读路径、cache invalidation、`invalid_record_count` 更新、flush target 定位都应使用该精确 key 直接从 `BTreeMap` 定位。不得在大分段数量下线性扫描全部 segment。

### 6.6 扩容机制 (详见 [懒分配与扩容](lazy-allocation.md))

- 创建时: `file.set_len(initial_size)` — 仅分配初始大小
- Header `file_size`: 始终记录 `max_file_size`, 不随扩容更新
- 打开时: `fs::metadata(path)?.len()` — 以磁盘实际大小为准
- 扩容时: `current_size * 2` → 上限 `max_file_size`
- 扩容步骤: unmap → `file.set_len(target)` → remap → 更新内存字段

### 6.7 时间戳范围跟踪

**目的**: 数据段维护 `min_timestamp` 和 `max_timestamp`, 用于 DataSegmentSet 的段级过滤优化。

**更新时机**:
- `create()`: 初始化为 `min_timestamp = i64::MAX`, `max_timestamp = i64::MIN`
- `append_record()`: 每次写入时更新
  ```rust
  if timestamp < self.min_timestamp { self.min_timestamp = timestamp; }
  if timestamp > self.max_timestamp { self.max_timestamp = timestamp; }
  ```
- `open()`: 从 DataFileMetadata 读取已有值
- `ensure_open()`: 从 DataFileMetadata 恢复

**使用场景**:
- DataSegmentSet 路由查询时, 可跳过不在 [start_ts, end_ts] 范围内的段
- 避免不必要的段打开和遍历

**状态一致性**:
- 每次 `append_record` 后立即写入 mmap state 区域
- 每次 mmap 写入后由 `DataSegment` 自身更新内存 dirty 状态: `is_flushed=false`
- `DataSegmentSet` 安装 Store 级 dirty sink 后, 当 dirty 状态首次从 flushed 变为 unflushed 时, `DataSegment` 用自身 `file_offset` 记录 `{ dataset_key, Data { file_offset } }`
- 后台 flush drain 队列后只同步 dirty segment, 成功后 `is_flushed=true`, `queued_for_flush=false`
- `idle_close()` 前 sync 确保落盘, 并清除该 segment 的 queued 标记; flush 队列中后续遇到该 stale target 时跳过
- 创建新 data segment 前, 对前一个已经完结的 data segment 直接执行 sync, 不等待后台 flush 间隔
- 崩溃恢复时从 file header 读取, 保证一致性

### 6.8 数据保留回收

**职责**: 删除超过数据有效期的数据段文件, 回收磁盘空间。

**回收规则 (DataSegmentSet)**:
```
reclaim_expired_segments(expiration_threshold: i64):
  前置条件: 调用方已 flush() 并对 data segment 执行 idle_close_all();
           所有 segment entry 均已 sync + unmap, 处于 closed/unmapped 状态
  for (file_offset, entry) in segments:
    if entry is Closed(meta) && meta.max_timestamp < expiration_threshold:
      fs::remove_file(meta.path)
      segments.remove(file_offset)
```

**判断依据**:
- 使用段文件 header 中的 `max_timestamp` (已在 `DataSegmentMeta` 中缓存)
- 无需打开文件, `segments` 中的 `Closed(DataSegmentMeta)` entry 在 idle-close/load-existing 时已读取 header 中的 min/max_timestamp
- 过期判断: `max_timestamp < expiration_threshold` (整个段的最大时间戳早于过期阈值)
- 如果一个 data segment 同时包含过期和未过期 timestamp, 该混合分段必须保留, 不做部分裁剪
- 数据段回收不检查其数据是否仍被 index entry 引用; 可见性由 `DataSet` 的 retention 读写约束保证

**触发时机**:
- 由 `DataSet::reclaim_expired_segments()` 调用 (见 [数据集操作 §6.8](dataset-operations.md))
- 后台线程按 `retention_check_hour` 指定的 UTC hour 每日执行一次
- 回收只释放和删除过期 data segment 文件; 不调用 public lifecycle `DataSet::close()`, 不关闭 queue, 不改变 Store registry 或 handle generation

`invalid_record_count` 只记录乱序写入、纠正写入回退和 delete 造成的无效 record 数量。当前版本不基于该字段执行 compaction, 也不回收段内局部空间。

---

**相关**: [架构概览](architecture.md) | [数据模型](data-model.md) | [懒分配与扩容](lazy-allocation.md)