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
457
458
459
460
461
462
463
464
465
# 核心数据模型

## 三、核心数据模型

### 3.1 Record (逻辑数据记录)

每条数据由调用方提供:

```
┌─────────────────┬──────────────────────────────┐
│ timestamp       │ data                         │
│ i64 (8 bytes)   │ bytes (可变长度)              │
└─────────────────┴──────────────────────────────┘
```

### 3.2 Block (物理存储单元)

多条 record 聚合为一个 Block, 压缩仅针对单个 Block。

**Block 大小限制**: 普通聚合 Block 的未压缩 payload 最大 256KiB (262144 字节)。如果单条 record 的编码后 stored span 超过 256KiB, 则该 record **独占一个 Block** (`SINGLE_RECORD`, exclusive/single-record block)。因此 `SINGLE_RECORD` 表示该 block 只服务一条 record, 不再等同于 record 一定超过 256KiB。该上限约束 payload 内容, 不要求或暗示每个 Block 在磁盘上预分配 256KiB。

**单条 Record 上限**: `write` 与 `append` 都必须拒绝纯数据长度超过 4MiB 的单条 record。普通写入校验 `data.len() <= 4MiB`; append 校验追加后的逻辑 record 数据长度 `old_data_len + append_len <= 4MiB`。该限制独立于 `data_len:u32` 的磁盘编码上限, 是当前实现的资源保护边界。

**Append 增长边界**: `DataSet::append` 修改已存在的最新 record 时只允许原地增长最后一个 pending raw block 的最末 record。追加后的逻辑 record 仍受 4MiB 资源上限约束, 且编码后大小必须能继续落在当前普通聚合 block 内; 不再因为比例阈值迁移为独占 block。若目标 block 已压缩、目标 record 不是分段最末尾, 或增长后超过普通 block 可承载范围, append 返回错误。

**纠正写入 (Correction Write)**: 当 `latest_written_timestamp == Some(timestamp)` 时触发纠正写入。该最大已写 timestamp 对应的记录只有在仍位于 **最新数据段最后一个 pending raw block (`flags=0`)** 的最末位置时, 才可通过 mmap 直接修改该 record 的 data 字节, **支持改变 data 长度** (增长或缩小)。索引条目保持不变 (`block_offset`/`in_block_offset` 不变, 其中 `block_offset` 是数据区逻辑全局偏移, 不含 header)。修改时 delta = new_data.len() - old_data_len, 需同步更新 5 个字段: block 头的 payload_size/uncompressed_size + 段的 pending_wrote_position / total_uncompressed_size / wrote_position。**回退行为**: 若目标 block 已经 `SEALED|COMPRESSED` 或不是可原地修改位置, 则自动回退为更新写入: 数据追加到最新数据段、更新索引值, 同时旧数据所在段的 `invalid_record_count` 加一, 并 invalidate 旧索引对应的全局缓存 key。compressed block 一旦写入后不允许再被修改, 这是全局 BlockCache 只缓存 compressed block 解压结果的前提。

### 3.3 Block Layout (磁盘上的 Block 结构)

```
┌──────────────────────────────────────────────────────────┐
│ BlockHeader (16 bytes)                                   │
├──────────────────────────────────────────────────────────┤
│ Block Payload (compressed 或 uncompressed)               │
│ ┌──────────────────────────┬───────────────────────────┐  │
│ │ data_len:4 + ts:8 + data │ data_len:4 + ts:8 + data  │  │
│ │ (record 1)               │ (record 2)                │  │
│ └──────────────────────────┴───────────────────────────┘  │
│ ...                                                       │
└──────────────────────────────────────────────────────────┘
```

#### BlockHeader (16 bytes)

```
Offset  Size  Field                    Description
0-3     u32   block_payload_size       Block payload 总字节数 (不含 header 自身的 16 字节)
4-5     u16   flags
                  bit 0: 1=compressed, 0=uncompressed
                  bit 1: 1=sealed (不再写入)
                  bit 2: 1=single_record (exclusive/single-record block)
6-7     u16   record_count             Block 内 record 数量
8-11    u32   uncompressed_size        Block 内所有 record 的原始数据总大小 (含 data_len+timestamp)
12-15   u32   reserved                 保留
```

合法状态只有两类:
- `flags = 0`: pending raw block, 可继续追加、可纠正写、可读取, 不进入全局缓存。
- `flags` 同时包含 `SEALED | COMPRESSED`: sealed compressed block, 不再修改, 可进入全局缓存。

`SEALED && !COMPRESSED` 与 `COMPRESSED && !SEALED` 均为非法状态。

#### Block Payload 内部结构 (Record 编码)

每条 record 在 Block Payload 中的存储:

```
┌──────────┬─────────────────┬──────────────────────────────┐
│ data_len │ timestamp       │ data              │ padding │
│ u32      │ i64 (8 bytes)   │ bytes (data_len)  │ 0-3B    │
│ 4 bytes  │                 │                   │ zero    │
└──────────┴─────────────────┴──────────────────────────────┘
```

- `data_len`: 纯数据长度 (不含 data_len 的 4 字节和 timestamp 的 8 字节), little-endian `u32`
- Record header 固定 12 字节 (`data_len:4 + timestamp:8`)
- 每条 record 的 stored span 为 `align_up(12 + data_len, 4)` 字节。末尾的 0 到 3 字节必须写为零 padding,不属于 data。
- 每条 record 都从 Block Payload 起始算的 4 字节边界开始。遍历方式: `offset += align_up(12 + data_len, 4)`。
- 写入路径必须保证单条 record 的纯数据长度不超过 4MiB; append 路径增长 `data_len` 时同样受该限制约束

### 3.4 IndexEntry (索引条目)

当前 index segment 使用 **16 字节核心 + 固定扩展区 + 8 字节对齐 padding**:

```text
timestamp:i64 LE | block_offset_delta:u48 LE | in_block_offset_units:u16 LE
index_data_size bytes | zero padding to align_up(16 + index_data_size, 8)
```

`index_data_size: u32` 默认 0,仅创建 dataset 时指定,dataset meta 和 index segment immutable meta 都保存。segment immutable `base_block_offset:u64` 来自触发创建的真实 entry 的 block 起点;filler 创建流程传递同一次真实写入的 block 起点。内存使用绝对 u64 offset,磁盘为相对 base 的差值。真实 delta 最大 `0xFFFFFFFFFFFE`,不足 base 或超限显式报错。磁盘 filler 为全 1 u48 与全 1 u16,解码恢复内存 `u64::MAX/u16::MAX`。

in_block_offset_units 仍以 4 字节为单位;真实 record 禁止使用 0xFFFF。预留自定义区本轮没有读写 API,新建时清零,定位字段更新保留,删除清零;允许读取非零预留区。对齐 padding 必须全零。完整格式及校验见 [时间索引 §7.3](time-index.md)。不提供旧格式兼容或迁移。

#### Block Offset 坐标系

为避免和物理文件偏移混淆, 文档统一使用 `block_offset` 表达索引中保存的值。它不是文件内物理 offset, 而是所有数据段的数据区串联后的逻辑 offset。

| 名称 | 含义 | 是否包含 header |
|------|------|----------------|
| `segment.file_offset` | 数据段在同一数据流坐标系中的起始 offset, 也是数据段文件名和 `DataSegment.file_offset` | 否 |
| `block_offset` | `IndexEntry.block_offset` 存储的值, 指向 BlockHeader 起始位置 | 否 |
| `block_offset - segment.file_offset` | BlockHeader 在所属数据段**数据区内**的相对 offset | 否 |
| `segment.header_len + (block_offset - segment.file_offset)` | 实际 mmap/seek 读取 BlockHeader 的文件内物理字节位置 | 是 |

转换公式:

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

因此 `block_offset / data_segment_size` 可定位第几个数据段, `block_offset % data_segment_size` 可定位该段数据区内的 block 起点; 真正读写文件时必须再加运行时解析出的 `segment.header_len`。可变 header 设计要求 index 中的 `block_offset` 永远不包含 header, 否则文件格式扩展会改变历史索引含义。

#### On-Disk Integer 编码与校验约束

所有 on-disk 多字节整数均使用 **Little Endian (LE)**, 不使用 native endian。signed/unsigned 按字段语义区分:

| 字段类别 | 磁盘类型 | 说明 |
|----------|----------|------|
| 时间戳、时间范围、创建时间 | `i64 LE` | `timestamp`, `min_timestamp`, `max_timestamp`, `created_at/create_time`。允许业务使用负 timestamp; 空数据段使用 `i64::MAX` / `i64::MIN` 作为 sentinel。 |
| segment header 的 `file_offset` | `i64 LE` | 复用字段: data segment 中必须为非负数据区逻辑起点; index segment 中表示 `start_timestamp`, 因此保持 signed。 |
| 数据长度、payload 长度、压缩前长度 | `u32 LE` | `data_len`, `block_payload_size`, `uncompressed_size`。写入时必须拒绝超过 `u32::MAX` 的值; 当前 API 还必须拒绝纯数据长度超过 4MiB 的单条 record; 读取时必须校验不会越过 block/file 边界。 |
| 逻辑 offset、写入位置、计数、retention、segment size、timestamp scale | `u64 LE` | `block_offset`, `wrote_position`, `record_count`, `pending_*`, `invalid_record_count`, `*_segment_size`, segment header `file_size`, `retention_window`, `timestamp_units_per_seconds`。`retention_window` 使用 timestamp unit, 有效范围为 `0..=i64::MAX`。所有加法/乘法必须使用 checked/saturating 语义并校验上界。 |
| block 内 offset 单位、flags、version、length | `u16 LE` | `in_block_offset_units`, `flags`, `version`, `meta_length`, `state_length`, TLV length。`0xFFFF` 是 `in_block_offset_units` filler sentinel, 真实 record 不得使用该单位值。 |
| type、fileType、compress_level、boolean flag | `u8` | 单字节字段不涉及端序。 |

读取已有文件时必须执行以下校验:

- `meta_length + state_length` 计算 `header_len` 时不得溢出, 且 `header_len <= file_len`; v1 已知 state 长度不得短于对应最小值。
- data segment 的 `wrote_position` 必须满足 `header_len <= wrote_position <= file_len`。index segment 的 entry area 固定从文件内绝对偏移 128 开始, 因此 index `wrote_position` 必须满足 `128 <= wrote_position <= file_len`, 且 `wrote_position - 128` 必须是 `entry_stride` 的整数倍。
- `block_payload_size` 必须完全落在所属 segment 文件内; compressed block 解压后的长度必须等于 `uncompressed_size`。
- 遍历 record 时, 每个 `data_len` 必须满足 `record_pos + align_up(12 + data_len, 4) <= block_payload_len`; record padding 必须全为零, `timestamp` 直接按 `i64 LE` 读取。
- real `IndexEntry` 不得使用 filler sentinel: `block_offset != u64::MAX` 且 `in_block_offset_units != 0xFFFF`; filler 必须同时使用 `block_offset = u64::MAX` 与 `in_block_offset_units = 0xFFFF`。
- data segment header 中的 `file_offset` 必须可转换为非负 `u64`; index segment header 中的 `file_offset` 作为 signed `start_timestamp` 使用,但不参与 IndexEntry timestamp 解码。
- 写入路径中所有 size/offset/count 累加必须使用 `checked_add`/`try_from` 或等价校验, 溢出时返回 `InvalidData` 或对应参数错误。

### 3.5 FileMetadata (文件头, meta + state)

每个数据段和索引段的头部元数据。**数据段和索引段的 state 字段已分化**, 各自维护不同的可变状态。

#### 设计原则: 可变(state) 与 不可变(meta) 分离

```
┌──────────────────────────────────────────────────────────┐
│ 固定前缀 (9 bytes)                                        │
│  magic:4 + version:2 + fileType:1 + meta_length:2         │
├──────────────────────────────────────────────────────────┤
│ Meta 不可变 TLV 区 (data 41B, index 59B)              │  ← 创建时写入一次, 永不修改
│  {type:1}{len:2}{value}, 可多个, 可跳过未知 type          │
├──────────────────────────────────────────────────────────┤
│ state_length: u16 (2 bytes)                               │  ← 告知后续 state 总字节数
├──────────────────────────────────────────────────────────┤
│ State 可变区 (按文件类型分化)                              │  ← 每次写入时动态更新
│  数据段: 72 bytes (9×8B)                                 │
│  索引段: 8 bytes (1×8B)                                  │
└──────────────────────────────────────────────────────────┘
```

#### 固定前缀 (数据段和索引段共享, 9 bytes)

```
Offset  Size  Field                    Description
0-3     4     magic = b"TMSL"
4-5     u16   version                  data segment = 1, index segment = 2
6       u8    fileType                 1 = index segment, 2 = data segment
7-8     u16   meta_length              Meta TLV 区总字节数
```

#### Meta 不可变 TLV 区 (创建时写入, 永不修改, 数据段和索引段共享)

| Meta Type (hex) | 名称 | 长度 | 数据类型 | 说明 |
|-----------------|------|------|---------|------|
| 0x01 | created_at | 8 | i64 LE | 创建时间(unix ms) |
| 0x02 | file_offset | 8 | i64 LE | data segment: `segment.file_offset` (数据区逻辑全局起点, 不含 header); index segment: 起始 timestamp |
| 0x03 | file_size | 8 | u64 LE | 文件总大小(字节) — 始终记录 max segment_size |
| 0x04 | compress_level | 1 | u8 | 压缩级别 |
| 0x05 | compress_type | 1 | u8 | Compression algorithm: 0=zstd, 1=deflate |

> Meta TLV 可向前扩展: 未知 type 通过 length 字段跳过, 不影响解析。

#### Data Segment State 可变区 (每值固定 8 字节, 顺序存储)

```
Offset  (相对 state 起始)    Size  Field                       Description
0       i64(8)  min_timestamp             段内所有 record 的最小时间戳 (i64::MAX=空段)
8       i64(8)  max_timestamp             段内所有 record 的最大时间戳 (i64::MIN=空段)
16      u64(8)  wrote_position            当前写入位置(文件内绝对偏移, 含动态 header_len)
24      u64(8)  record_count              已写入记录总数
32      u64(8)  total_uncompressed_size   文件内所有 record 原始数据总大小
40      u64(8)  pending_block_offset      当前未完成 block 相对偏移 (u64::MAX=无)
48      u64(8)  pending_wrote_position    pending block 内已写入位置(从 payload 起始)
56      u64(8)  pending_record_count      pending block 内 record 数量
64      u64(8)  invalid_record_count      段内无效记录数 (仅统计, 不触发 compaction)
```

> `min_timestamp` / `max_timestamp`: 每次 `append_record` 更新, 用于 DataSegmentSet 的时间范围段级过滤优化。空段时 `min_timestamp = i64::MAX`, `max_timestamp = i64::MIN`。

#### Index Segment State 可变区 (仅 1 个字段)

```
Offset  (相对 state 起始)    Size  Field                    Description
0       u64(8)  wrote_position           当前写入位置(文件内绝对偏移, index entry area 固定从 128 开始)
```

> `wrote_count` 可从 `wrote_position` 计算: `wrote_count = (wrote_position - 128) / entry_stride`。不再单独持久化 `record_count`、`total_uncompressed_size` 等数据段相关字段。

#### Header 长度与数据区起点

Header 采用可变长度设计。Data segment 的 Block 区从动态 `header_len` 开始。Index segment 为保持连续模式 timestamp 路由稳定, 文件前 128 字节固定保留给 fixed prefix、Meta TLV、state 和未来扩展, 所有 index entry 无论连续/非连续模式都从文件内绝对偏移 128 开始。

运行时必须从文件自身读取长度并计算:

```text
meta_start          = 9
state_length_offset = meta_start + meta_length
state_start         = state_length_offset + 2
header_len          = state_start + state_length
```

所有 state 字段偏移均以 `state_start` 为基准。数据段 Block 区从动态 `header_len` 开始; 索引段 Entry 区固定从 128 开始。未来新增 index meta TLV 或 state 字段必须仍放入 128 字节保留区, 不能改变 entry area 起点或连续索引 `segment_capacity`。

#### v1 默认 Header 长度计算

**数据段 (DataSegment):**
```
固定前缀:     4 + 2 + 1 + 2     = 9 bytes
Meta TLV:     11 + 11 + 11 + 4 + 4 = 41 bytes  (5 个 TLV 条目)
state_length: 2                 = 2 bytes
State 值:     9 × 8            = 72 bytes   (9 个字段)
────────────────────────────────────────────
DATA_HEADER_SIZE = 124 bytes
```

**索引段 (IndexSegment):**
```
固定前缀:     4 + 2 + 1 + 2     = 9 bytes
Meta TLV:     11 + 11 + 11 + 4 + 4 = 41 bytes  (5 个 TLV 条目)
state_length: 2                 = 2 bytes
State 值:     1 × 8            = 8 bytes    (1 个字段)
Reserved:      68               = 68 bytes   (padding to fixed entry area)
────────────────────────────────────────────
INDEX_HEADER_SIZE = 128 bytes
```

#### 常量定义

```rust
pub const DATA_HEADER_SIZE: u64 = 124;   // v1 默认 data header_len
pub const INDEX_HEADER_SIZE: u64 = 128;   // index entry area fixed start
```

> 新建 v1 文件时 data Block 区起点为 124, index Entry 区起点为 128。打开已有 data 文件时, Block 区起点必须使用文件 header 中计算出的 `header_len`; 打开 index 文件时仍解析可变 header 内容, 但 Entry 区起点固定为 128。
> `wrote_position` 是文件内绝对偏移。data 运行时可派生 `data_wrote_position = wrote_position - header_len` 作为数据区相对已用字节数; index 运行时可派生 `wrote_count = (wrote_position - 128) / entry_stride`。

#### 兼容性设计

| 场景 | 行为 |
|------|------|
| v1 reader 读 v1 文件 | 正常读取, 解析已知 meta type, 跳过未知 |
| v2 reader 读 v1 文件 | 读 `meta_length` 跳过未知 meta; 读 `state_length` 对齐 state |
| v1 reader 读 v2 文件 | 读固定前缀 (9B) + `meta_length` 定位 state + `state_length` 计算 `header_len`, 解析已知 state 字段 |
| 未来添加新 meta 字段 | 增加新 TLV type, `meta_length` 增加, 旧版本通过 length 跳过 |
| 未来添加新 state 字段 | 增加 state 条目, `state_length` 增加, 旧版本只读前 N 个 8B |
| 数据段 vs 索引段区分 | 通过 `fileType` 字段 (byte 6) 选择已知 state 字段集合, 不用固定 HEADER_SIZE 推导数据区 |

## 四、核心类型定义

```rust
/// 存储实例句柄 (线程安全)
pub struct Store {
    data_dir: PathBuf,
    datasets: RwLock<HashMap<DataSetKey, Arc<DataSet>>>,
    config: StoreConfig,
    block_cache: Arc<BlockCache>,      // 全局读缓存池 (0=禁用)
    bg_handle: Option<JoinHandle<()>>,
    shutdown_tx: Option<mpsc::Sender<()>>,
}

/// 数据集唯一标识
#[derive(Clone, PartialEq, Eq, Hash, Debug)]
struct DataSetKey {
    name: String,
    dataset_type: String,
}

// Store 层只接受非空且匹配 ^[0-9A-Za-z_-]+$ 的 name/type。
// name/type 直接作为目录组件, 不做 escaping。

/// Store-managed public dataset operation view.
/// C ABI wrapper has its own opaque dataset pointer in wrapper/cffi.
struct DataSet {
    inner: Arc<Mutex<DataSetInner>>,
}

/// Store 配置: 后台/缓存等运行时设置 + 新建 DataSet 默认值。
/// 字段在实现中保持 crate-private, public API 通过 builder 和 getters 暴露。
pub struct StoreConfig { /* active fields见本节下方 */ }

/// 数据集创建/open 配置。
/// 字段在实现中保持 crate-private, public API 通过 builder 和 getters 暴露。
pub struct DataSetConfig { /* active fields见本节下方 */ }

/// Block 头
struct BlockHeader {
    block_payload_size: u32,
    flags: u16,
    record_count: u16,
    uncompressed_size: u32,
    _reserved: u32,
}

const BLOCK_FLAG_COMPRESSED: u16     = 0x0001;
const BLOCK_FLAG_SEALED: u16         = 0x0002;
const BLOCK_FLAG_SINGLE_RECORD: u16  = 0x0004;
const BLOCK_MAX_SIZE: u32            = 256 * 1024;  // 普通聚合 Block 未压缩 payload 固定上限

/// File type constants
const FILE_TYPE_INDEX: u8  = 1;
const FILE_TYPE_DATA: u8   = 2;

/// Meta TLV types (immutable, written once at creation)
const META_TYPE_CREATED_AT:     u8 = 0x01;  // i64 LE, unix ms
const META_TYPE_FILE_OFFSET:    u8 = 0x02;  // i64 LE
const META_TYPE_FILE_SIZE:      u8 = 0x03;  // u32 LE
const META_TYPE_COMPRESS_LEVEL: u8 = 0x04;  // u8

/// 数据段文件元数据头 (DataFileHeader, v1 默认 124 bytes)
struct DataFileMetadata {
    // === 固定前缀 (所有版本必须可读, 9 bytes) ===
    magic: [u8; 4],
    version: u16,
    file_type: u8,  // FILE_TYPE_DATA = 2
    // === Meta 不可变 (TLV, 创建时写入) ===
    created_at: i64,
    file_offset: i64,
    file_size: u64,
    compress_level: u8,
    compress_type: u8,
    meta_length: u16,
    state_length: u16,
    header_len: u64,
    // === State 可变 (每值固定 8 字节, 顺序存储, 9 个字段) ===
    min_timestamp: i64,         // 段内最小时间戳 (i64::MAX 表示空段)
    max_timestamp: i64,         // 段内最大时间戳 (i64::MIN 表示空段)
    wrote_position: u64,
    record_count: u64,
    total_uncompressed_size: u64,
    pending_block_offset: u64,
    pending_wrote_position: u64,
    pending_record_count: u64,
    invalid_record_count: u64,  // 段内无效记录数 (仅统计, 不触发 compaction)
}

/// 索引段文件元数据头 (IndexFileHeader, entry area 固定从 128 bytes 开始)
struct IndexFileMetadata {
    // === 固定前缀 (所有版本必须可读, 9 bytes) ===
    magic: [u8; 4],
    version: u16,
    file_type: u8,  // FILE_TYPE_INDEX = 1
    // === Meta 不可变 (TLV, 创建时写入) ===
    created_at: i64,
    file_offset: i64,
    file_size: u64,
    compress_level: u8,
    compress_type: u8,
    meta_length: u16,
    state_length: u16,
    header_len: u64,
    // === State 可变 (仅 1 个字段) ===
    wrote_position: u64,
}

const DATA_HEADER_SIZE: u64 = 124;   // v1 默认数据段 header_len
const INDEX_HEADER_SIZE: u64 = 128;   // index entry area 固定起点

/// 索引条目
#[derive(Clone, Copy, Debug)]
struct IndexEntry {
    timestamp: i64,
    block_offset: u64,    // 数据区逻辑全局 offset
    in_block_offset: u16,
}
```

---

**相关**: [架构概览](architecture.md) | [元数据格式](meta-format.md) | [数据段管理](data-segment.md)

## P1-2 Active Contract: Segment Size And Compression Type

- All on-disk multi-byte integers use little-endian encoding.
- Dataset meta `data_segment_size` / `index_segment_size` are `u64 LE`.
- Data/index segment header immutable meta `file_size` is `u64 LE`; it records the configured max segment size, not the current lazy-allocated physical file length.
- The active format no longer has segment header `file_size:u32`. The project is still in initial development, so no old-layout compatibility shim is required.
- Dataset meta and data/index segment header immutable meta both store `compress_type:u8`.
- `compress_type = 0` means zstd and is the default for new stores, datasets, and segments. `compress_type = 1` means deflate.
- Unknown `compress_type` values must be rejected on config decode, open, and before compress/decompress.
- `compress_level` remains `u8`, defaults to `6`, and is interpreted by the selected compression algorithm.
- The current public/persisted `compress_level` contract is `0..=9`. Builders clamp larger values to `9`; on-disk meta values greater than `9` are invalid on open.
- Reads must use the owning segment header `compress_type`, not the current Store/DataSet default.

Active segment header immutable TLV set:

| Meta Type (hex) | Name | Length | Type | Description |
|-----------------|------|--------|------|-------------|
| 0x01 | created_at | 8 | i64 LE | Creation time in unix milliseconds |
| 0x02 | file_offset | 8 | i64 LE | Data segment logical base offset or index segment base timestamp |
| 0x03 | file_size | 8 | u64 LE | Configured max segment size |
| 0x04 | compress_level | 1 | u8 | Compression level |
| 0x05 | compress_type | 1 | u8 | Compression algorithm: 0=zstd, 1=deflate |

## Active Contract: StoreConfig And DataSetConfig

The authoritative field list is `src/config.rs`; this section records the active design-level contract so the data model document does not omit current fields.

`StoreConfig` contains runtime settings and defaults for newly created datasets. Fields are crate-private in implementation; callers use `StoreConfig::builder()` and getters.

```rust
pub struct StoreConfig {
    flush_interval: Duration,          // default 15s
    idle_timeout: Duration,            // default 30min
    data_segment_size: u64,            // default 64MiB
    index_segment_size: u64,           // default 16MiB
    initial_data_segment_size: u64,    // default 256KiB
    initial_index_segment_size: u64,   // default 16KiB
    compress_level: u8,                // default 6
    compress_type: u8,                 // default 0=zstd, 1=deflate
    cache_max_memory: usize,           // default 256MiB, 0=disabled
    cache_idle_timeout: Duration,      // default 30min
    retention_check_hour: u8,          // UTC hour 0..=23, default 0
    enable_background_thread: bool,    // default true
    enable_journal: bool,              // default true
    read_only: Option<bool>,           // default None: auto-fallback to read-only when store lock is held
}
```

`StoreConfig.read_only` is a tri-state open-mode setting. `None` is the default auto mode: `Store::open` attempts the Store `.lock` OS lock and falls back to read-only if another writer holds it. `Some(false)` requires writable mode and fails when the OS lock cannot be acquired. `Some(true)` forces read-only mode and does not create, inspect, or acquire the `.lock` file. The presence of a stale `.lock` file is not meaningful by itself.

`DataSetConfig` contains dataset creation/open configuration. Fields are crate-private in implementation; callers use `DataSetConfig::builder()`, `DataSetConfigBuilder::from_store()`, and getters. Values persisted in dataset meta must be read from meta on reopen, not compared against Store defaults:

```rust
pub struct DataSetConfig {
    data_segment_size: u64,
    index_segment_size: u64,
    compress_level: u8,
    compress_type: u8,
    index_continuous: u8,
    initial_data_segment_size: u64,
    initial_index_segment_size: u64,
    retention_window: u64, // same unit as timestamp, 0=no limit
    enable_journal: bool,  // default false, persisted in meta
    timestamp_units_per_seconds: u64, // default 0, persisted immutable scale
    create_time: i64,      // unix milliseconds
}
```

`timestamp_units_per_seconds` is an immutable dataset setting. It defines how many dataset timestamp units equal one Unix second and is persisted as `DataSetMeta` TLV `0x0B` (`u64 LE`). The default `0` preserves legacy retention: its threshold remains `latest_written_timestamp - retention_window` and does not read wall-clock time. A nonzero value enables wall-clock retention in the same timestamp domain. This integer scale has no float representation. On reopen the value comes from meta and cannot be changed by current Store defaults or mutable state.

`DataSetConfig.enable_journal` is a dataset creation/open setting, not a Store runtime setting. Journal records for a dataset are emitted only when `StoreConfig.enable_journal && DataSetConfig.enable_journal` is true.

## Compact Index Metadata Generation

Dataset meta version is exactly 2; index file version is exactly 2, independently from data-file version 1. Required dataset TLV `0x0C` is `index_data_size:u32 LE` (4B); index-only TLVs `0x06` and `0x07` are `base_block_offset:u64 LE` (8B) and `index_data_size:u32 LE` (4B). Missing, duplicate or incorrectly sized new fields are errors. Dataset metadata TLV values total 100B. Dataset and segment sizing must agree. Old versions are rejected without migration.