go-kv/docs/phase1-wal-plan.md

# Phase 1: WAL 子系统开发方案

基于 `docs/design.md` §3.2 设计文档。

## 目标

实现完整的 WAL（预写日志）子系统，使其能够支撑单 key autocommit 的写入、崩溃恢复和读可见性语义。

## 开发阶段总览

```
Phase 1A: 项目骨架 + WAL 编码格式层
Phase 1B: WAL 文件写入 + Segment 管理
Phase 1C: WAL Writer（Group Commit）
Phase 1D: WAL Recovery
Phase 1E: MemTable（SkipList + Arena）
Phase 1F: 写入路径集成（WAL → MemTable 完整流水线）
Phase 1G: 读路径 + 嵌入式 API
Phase 1H: MANIFEST + 文件管理
Phase 1I: 集成测试 + Benchmark
```

---

## Phase 1A: 项目骨架 + WAL 编码格式层

**目标**: 建立 Go 项目结构，实现 WAL 物理格式（Block / Physical Record / WAL Batch / Entry）的编码与解码。

### 任务

#### 1A-1: 项目初始化
- `go.mod` 初始化（模块名 `github.com/dailz/go-kv`）
- 目录结构：
  ```
  go-kv/
  ├── go.mod
  ├── wal/           # WAL 子系统
  │   ├── wal.go     # 公共类型、常量、配置
  │   ├── record.go  # Physical Record 编解码
  │   ├── batch.go   # WAL Batch 编解码
  │   ├── entry.go   # Entry 编解码
  │   ├── header.go  # WAL File Header 编解码
  │   └── wal_test.go
  ├── memtable/      # MemTable（Phase 1E）
  ├── config/        # 全局配置
  ├── errors.go      # 公共错误类型
  └── db.go          # DB 入口
  ```
- `.golangci.yml` 配置（参考 golang-lint skill）

#### 1A-2: 公共错误类型 (`errors.go`)
- `ErrCommitUnknown` — maybe committed 语义
- `ErrWriteStopped` — 引擎 write-stopped
- `ErrSequenceExhausted` — sequence 耗尽
- `ErrWALCorrupted` — WAL 损坏
- `ErrInvalidConfig` — 配置不合法

#### 1A-3: WAL 常量与配置 (`wal/wal.go`)
```go
const (
    WalMagic         uint32 = 0x... // 待定
    WalFormatVersion uint16 = 1
    WalFileHeaderSize       = 32
    WalBlockSize            = 32 * 1024 // 32KB
    PhysicalRecordHeaderSize = 7
    WalBatchHeaderSize      = 18
    MaxWalBatchEntryCount   = 10_000
    MaxWalBatchEntriesSize  = 4 * 1024 * 1024 // 4MB
    MaxWalKeyBytes          = 4 * 1024        // 4KB
    MaxWalInlineValueBytes  = 4 * 1024        // 4KB
    MaxWalVarintBytes       = 5
    DefaultMaxWalSegmentSize = 64 * 1024 * 1024 // 64MB
    DefaultImmutableCount   = 2
)

// Fragment types
const (
    RecInvalid uint8 = 0
    RecFull    uint8 = 1
    RecFirst   uint8 = 2
    RecMiddle  uint8 = 3
    RecLast    uint8 = 4
)

// OpType
const (
    OpInvalid uint8 = 0
    OpPut     uint8 = 1
    OpDelete  uint8 = 2
)

// ValueKind
const (
    VKNone            uint8 = 0
    VKInline          uint8 = 1
    VKValueLogPointer uint8 = 2
)
```

WAL 配置结构体：
```go
type WalConfig struct {
    MaxSegmentSize  uint64 // default 64MB
    BlockSize       uint32 // default 32KB
    SyncMode        SyncMode // Always/Periodic/Never
    PeriodicSyncMs  uint32 // Periodic 模式的 fsync 间隔
    MaxBatchEntries uint32 // default 10000
    MaxBatchSize    uint32 // default 4MB
    MaxKeyBytes     uint32 // default 4KB
    MaxInlineValue  uint32 // default 4KB
}
```

配置校验函数 — 必须在 DB 打开时验证不变量：
```text
maxWalSegmentPayload >= maxEncodedWalBatchSize + worstCasePhysicalRecordOverhead + worstCaseBlockPadding
```

#### 1A-4: WAL File Header 编解码 (`wal/header.go`)
- `WalFileHeader` 结构体：magic, formatVersion, headerSize, blockSize, segmentID, startSequence, headerCRC
- `EncodeWalHeader(h *WalFileHeader) [WalFileHeaderSize]byte`
- `DecodeWalHeader(data []byte) (*WalFileHeader, error)` — 校验 magic、formatVersion、headerSize、headerCRC
- CRC 覆盖范围：magic 到 startSequence，不包含 headerCRC 自身
- 字节序：little-endian

#### 1A-5: Physical Record 编解码 (`wal/record.go`)
- `PhysicalRecord` 结构体：CRC, Length, Type, Payload
- `EncodePhysicalRecord(recType uint8, payload []byte) []byte` — 返回编码后的 bytes
- `DecodePhysicalRecord(data []byte) (*PhysicalRecord, error)` — CRC 校验
- Block 边界处理辅助函数：
  - `PaddingNeeded(blockOffset, blockSize uint32) int` — 剩余空间 <= 7 时返回需要 padding 的字节数
  - `CanFitRecord(blockOffset, blockSize, payloadLen uint32) bool`

#### 1A-6: WAL Batch 编解码 (`wal/batch.go`)
- `WalBatch` 结构体：Flags, BaseSequence, EntryCount, EntriesSize, Entries
- `EncodeWalBatch(batch *WalBatch) ([]byte, error)` — 编码 Batch Header + Entries
- `DecodeWalBatch(data []byte) (*WalBatch, error)` — 校验 flags、entryCount、entriesSize
- Batch 分片：`SplitIntoRecords(encodedBatch []byte, blockSize uint32) [][]byte` — 将编码后的 Batch 拆分为 Physical Record payloads
- Batch 重组：`FragmentCollector` — 收集 fragments 并重组成完整 Batch

FragmentCollector 状态机：
```
Idle → 收到 Full → 重放 batch → Idle
Idle → 收到 First → CollectingFragments
CollectingFragments → 收到 Middle → 追加
CollectingFragments → 收到 Last → 重组 → 重放 → Idle
```

#### 1A-7: Entry 编解码 (`wal/entry.go`)
- `WalEntry` 结构体：OpType, ValueKind, Key, Value
- `EncodeEntry(e *WalEntry) ([]byte, error)` — 编码为 varint 长度 + bytes
- `DecodeEntry(data []byte) (*WalEntry, int, error)` — 解码，返回 entry 和 consumed bytes
- 校验规则：
  - keyLen > 0 && keyLen <= maxKeyBytes
  - Put 要求 valueKind ∈ {Inline, ValueLogPointer}
  - Put + Inline: valLen <= maxInlineValueBytes (允许 valLen = 0)
  - Put + ValueLogPointer: valLen > 0
  - Delete: valueKind == None, valLen == 0

#### 1A-8: WAL Batch 资源校验
- `ValidateBatchLimits(entries []*WalEntry) error` — 在 sequence 分配之前检查：
  - entryCount <= maxBatchEntries
  - 每个 keyLen <= maxKeyBytes
  - 每个 inline valLen <= maxInlineValueBytes
  - entries 编码后总大小 <= maxBatchSize
  - 单个 Batch 的最坏 Physical Record overhead 不超过 segment capacity

### 验收标准
- [ ] 所有编解码函数有 table-driven test
- [ ] CRC 校验正确
- [ ] Fragment 分片/重组 round-trip 正确
- [ ] 资源限制校验覆盖所有边界条件
- [ ] `go vet` / `golangci-lint` 通过

---

## Phase 1B: WAL 文件写入 + Segment 管理

**目标**: 实现 WAL segment 文件的写入、轮转和持久化协议。

### 任务

#### 1B-1: Segment 文件格式写入器 (`wal/segment_writer.go`)
- `SegmentWriter` — 封装 WAL segment 文件的追加写入
- 状态：当前 segment fd、当前 block offset、当前 segmentID、payload written bytes
- `NewSegmentWriter(dir string, segmentID uint64, startSequence uint64, cfg *WalConfig) (*SegmentWriter, error)`
  - 创建 segment-N.wal.tmp
  - 写入 WAL File Header
  - fsync
  - rename → segment-N.wal
  - fsync directory
  - 进入 durable-ready 状态
- `AppendBatch(batch *WalBatch) error` — 编码 batch → split into records → 按 block 边界写入
- `Sync() error` — fsync 当前 segment 文件
- `Close() error`
- `RemainingPayload() uint64` — 当前 segment 剩余可用 payload 空间
- `CurrentOffset() uint64` — 当前写入偏移

#### 1B-2: Block 写入缓冲 (`wal/block_writer.go`)
- 管理 32KB block 的填充和 padding
- `BlockWriter` — 封装 block 内的 Physical Record 写入
- 自动处理 block 边界：剩余 <= 7 bytes 时 padding
- 跨 block 的 batch fragment 自动拆分

#### 1B-3: Segment 轮转逻辑
- 写入 batch 前检查 `RemainingPayload()` 是否足够容纳整个 batch
- 不足时：当前 segment 完成（在 batch 边界）、创建新 segment
- 新 segment 的 durable-ready 协议：
  1. create segment-N+1.wal.tmp
  2. write WAL File Header（含 startSequence = nextExpectedSequence）
  3. fsync segment-N+1.wal.tmp
  4. rename → segment-N+1.wal
  5. fsync WAL directory
  6. segment-N+1 进入 durable-ready
- 旧的 active segment 密封

#### 1B-4: CURRENT 文件管理
- best-effort 更新 CURRENT 文件
- temp + rename 模式
- 更新失败不影响已 durable-ready 的 segment

#### 1B-5: WAL 目录管理工具
- 扫描 WAL 目录中的 segment 文件
- 按 segmentID 排序
- 解析文件名中的 segmentID
- 文件名格式：`segment-{id}.wal`

### 验收标准
- [ ] Segment 创建遵循 durable-ready 协议
- [ ] Batch 不跨 segment
- [ ] Block padding 正确
- [ ] Segment 轮转在 batch 边界发生
- [ ] 多 segment 写入后，每个 segment 的 header 可以正确解析
- [ ] 测试覆盖：正常写入、跨 block batch、segment 轮转触发

---

## Phase 1C: WAL Writer（Group Commit）

**目标**: 实现完整的 WAL 写入路径，包括 group commit、sequence 管理、fsync 策略和错误分类。

### 任务

#### 1C-1: Sequence 管理器 (`wal/sequence.go`)
- `SequenceManager` — 管理 WAL 物理 mutation sequence
- `atomic.Uint64` 存储 nextSequence、publishedSequence、durableSequence
- `AllocateBatch(count uint32) (baseSequence uint64, err error)` — checked arithmetic 检查溢出
- `Publish(sequence uint64)` — release 语义 store publishedSequence
- `MarkDurable(snapshot SegmentEndState)` — 推进 durableSequence
- `Published() uint64` — load publishedSequence
- `Durable() uint64` — load durableSequence

#### 1C-2: Commit Queue (`wal/commit_queue.go`)
- 写请求进入的队列
- 每个写请求关联一个 `*sync.Cond` 或 channel 用于等待/唤醒
- `CommitBatch` 结构体：entries、完成 channel、错误结果、baseSequence

#### 1C-3: WAL Writer 主循环 (`wal/writer.go`)
核心写入循环：
```
loop:
  1. 从 commit queue 收集一批写入
  2. 等待触发条件（500µs 或 32KB）或 queue 非空
  3. 组装 WAL Batch
  4. 校验 batch 资源限制
  5. 预留 MemTable Arena 容量
  6. 分配 sequence（baseSequence）
  7. 在私有缓冲区编码 WAL Batch
  8. 检查/触发 segment 轮转
  9. Append WAL Batch 到 segment 文件
  10. 写入 MemTable（pending/unpublished）
  11. fsync（Always 模式）
  12. 发布 publishedSequence
  13. 唤醒所有等待的调用方
```

错误分类逻辑：
- 步骤 4-7 失败（未分配 sequence）→ 普通错误，可继续
- 步骤 6 后失败（sequence 已分配）→ write-stopped
- 步骤 9 后失败（WAL write 已尝试）→ ErrCommitUnknown + write-stopped
- 步骤 11 失败（fsync）→ ErrCommitUnknown + write-stopped

#### 1C-4: Fsync 策略实现 (`wal/fsync.go`)
- `SyncMode` 类型：Always / Periodic / Never
- `Always`: 每次 batch fsync 后再 publish
- `Periodic`: 后台 goroutine 定期 fsync，write 成功即可 publish
- `Never`: 不主动 fsync
- `Periodic` 的 fsync worker：
  - 快照当前 append high-water mark: (segmentID, endOffset, endSequence)
  - fsync 成功后按连续 batch 推进 durableSequence
  - fsync 失败 → write-stopped

#### 1C-5: durableSequence 推进逻辑
- 每个 batch 记录 `(segmentID, endOffset, endSequence)`
- fsync snapshot 后只推进满足条件的最大连续 batch
- 跨 segment 推进需要 segment 已 durable-ready

#### 1C-6: Write-Stopped 状态管理
- `atomic.Bool` 存储 writeStopped
- 进入 write-stopped 后拒绝新写入
- 已存在的 MemTable / Immutable MemTable 可继续后台处理
- 提供 `IsWriteStopped() bool` 查询接口

### 验收标准
- [ ] Group commit 正确合并多个写请求
- [ ] 双触发（时间/大小）工作正常
- [ ] Sequence 分配无溢出
- [ ] Always 模式下 publish 在 fsync 之后
- [ ] 错误分类准确（普通错误 / write-stopped / ErrCommitUnknown）
- [ ] 并发写入正确（多 goroutine 同时 Put）
- [ ] Write-stopped 后新写入被拒绝

---

## Phase 1D: WAL Recovery

**目标**: 实现 WAL 崩溃恢复，包括 segment 扫描、fragment 重组、batch 校验和尾部截断。

### 任务

#### 1D-1: Segment 扫描器 (`wal/scanner.go`)
- 从 WAL 目录扫描 segment 文件
- 按 segmentID 排序
- 从 MANIFEST 指定的 recoverySegmentID 开始
- 过滤掉 segmentID < recoverySegmentID 的旧 segment
- 校验连续性：segmentID 和 startSequence 都必须连续

#### 1D-2: Physical Record 解析器 (`wal/record_parser.go`)
- Block 级别的顺序解析
- 处理 padding（全 0 校验）
- Physical Record header 解析和 CRC 校验
- 错误分类：尾部 vs 中间损坏

#### 1D-3: Fragment 重组器 (`wal/fragment_collector.go`)
- 实现 Idle / CollectingFragments 状态机
- 收集 First / Middle / Last fragments
- Buffer 大小限制（Batch Header 长度 + entriesSize 上限）
- Fragment 顺序合法性检查

#### 1D-4: Batch 校验与重放 (`wal/recovery.go`)
- Batch Header 校验：flags、entryCount、entriesSize
- Batch sequence 连续性：batch.baseSequence == expectedSequence
- Entry 逐条校验：opType、valueKind、keyLen、valLen
- 重放回调：对每个合法 entry 调用 replay 函数
- Sequence 推进：expectedSequence += entryCount

#### 1D-5: 尾部截断持久化 (`wal/truncation.go`)
- 识别最后一个完整 batch 的结束位置
- ftruncate segment 文件
- fsync 被截断的 segment
- 删除不含任何 complete batch 的后续空 segment
- fsync WAL directory
- 任一步失败 → recovery 报错

#### 1D-6: Recovery 主流程 (`wal/recovery.go`)
```
1. 读取 MANIFEST → recoverySegmentID
2. 扫描 WAL 目录 → 过滤出 recovery segments
3. 排序并校验连续性
4. 逐 segment 扫描：
   a. 校验 File Header
   b. 逐 Block 解析 Physical Records
   c. Fragment 重组 → 完整 Batch
   d. Batch 校验 → 重放
   e. 更新 expectedSequence
5. 处理尾部异常
6. 持久化截断（如需要）
7. 返回恢复结果：recoveredSequence, nextSequence, publishedSequence
```

### 验收标准
- [ ] 正常 WAL 完整恢复
- [ ] 尾部 partial write 正确截断
- [ ] 中间损坏正确报错
- [ ] 跨 segment 恢复正确
- [ ] Fragment 重组 round-trip 正确
- [ ] Segment 连续性校验
- [ ] Sequence 溢出检测
- [ ] 资源限制校验（recovery 侧）

---

## Phase 1E: MemTable（SkipList + Arena）

**目标**: 实现基于 Arena 的 SkipList，支持 pending/unpublished/aborted 状态，容量预留，和原子发布。

### 任务

#### 1E-1: Arena 分配器 (`memtable/arena.go`)
- 固定大小 Arena（默认 64MB）
- 线程安全的内存分配
- 对齐分配
- 剩余容量查询
- 支持预留（reserve）操作

#### 1E-2: SkipList (`memtable/skiplist.go`)
- 最大 20 层
- Mutex 写 + 无锁读
- `atomic.Pointer` 发布 next 指针（release 语义）
- 有序遍历（Iterator）
- key 比较（bytes comparison）

#### 1E-3: Entry 状态管理 (`memtable/entry.go`)
- Entry 结构：key、value、sequence、pending/aborted 标记
- 原子发布：`atomic.Pointer` store-release
- 可见性判断：`entry.sequence <= loadedPublishedSequence && !aborted`

#### 1E-4: MemTable (`memtable/memtable.go`)
- 封装 SkipList + Arena
- `Put(key, value, sequence) error` — 写入 pending entry
- `PublishEntries(upToSequence)` — 批量发布 pending entries
- `AbortEntries(fromSequence)` — 标记 aborted
- `Get(key, publishedSequence) (GetResult, error)` — 无锁读，只返回 sequence <= publishedSequence 且非 aborted 的 entry
- `NewIterator(publishedSequence) Iterator` — 无锁有序遍历
- `ApproximateSize() uint64` — 近似内存使用量
- `IsFull() bool`
- `Reserve(entries []ReserveEntry) (uint64, error)` — 容量预留（最坏情况计算）

#### 1E-5: 容量预留计算
- 每个 entry 的预留大小 = key bytes + value bytes + skiplist node overhead + next 指针数组（最大层高）+ arena 对齐 padding
- 批量预留必须覆盖整个 batch
- checked arithmetic 检查单个 batch 是否超过空 MemTable 容量

#### 1E-6: Immutable MemTable 管理
- Freeze 流程：当前 MemTable → Immutable
- Immutable 队列（上限 2）
- 队列满时阻塞

### 验收标准
- [ ] SkipList 正确性：插入、查找、有序遍历
- [ ] Arena 分配无泄漏
- [ ] 并发读写正确（racetest）
- [ ] pending/unpublished entry 对读不可见
- [ ] 发布后 entry 可见
- [ ] aborted entry 对读不可见
- [ ] 容量预留准确
- [ ] 内存序正确（go test -race 通过）

---

## Phase 1F: 写入路径集成

**目标**: 将 WAL Writer 和 MemTable 连通，实现完整的写入流水线。

### 任务

#### 1F-1: DB 写入 API (`db.go`)
```go
type DB struct { ... }

func Open(dir string, opts ...Option) (*DB, error)
func (db *DB) Close() error
func (db *DB) Put(key, value []byte) error
func (db *DB) Delete(key []byte) error
```

#### 1F-2: 写入路径集成
完整写入流程：
```
Put(key, value)
  → commit queue
  → group commit 组装 batch
  → 校验 batch limits
  → 预留 MemTable Arena
  → 分配 sequence
  → 私有缓冲编码
  → 检查 segment 轮转
  → WAL append
  → MemTable pending write
  → fsync（Always 模式）
  → 原子发布 MemTable entries
  → 推进 publishedSequence
  → 唤醒调用方
```

#### 1F-3: MemTable Freeze + Switch
- 写入前检查容量，不足时 freeze + switch
- Immutable 队列满时阻塞等待
- Freeze 时确保当前 MemTable 已完成所有 pending 发布

#### 1F-4: 恢复启动集成
- Open 时执行 recovery
- 恢复的 entries 写入 MemTable 并标记为 published
- 设置 nextSequence、publishedSequence

### 验收标准
- [ ] 单条 Put 写入成功
- [ ] 并发 Put 正确
- [ ] 写入后读取可见（Always 模式）
- [ ] WAL crash recovery 后数据完整
- [ ] MemTable freeze/switch 正确
- [ ] Sequence 连续无间隙
- [ ] `go test -race` 通过

---

## Phase 1G: 读路径 + 嵌入式 API

**目标**: 实现完整的读路径和嵌入式 API。

### 任务

#### 1G-1: Get API
```go
type GetResult struct {
    Value []byte
    Found bool
}

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

#### 1G-2: 读路径实现
- 读取 publishedSequence（atomic load）
- 遍历 MemTable → Immutable MemTables
- 只返回 `sequence <= publishedSequence` 且非 aborted 的 entry
- Delete (tombstone) 返回 `Found=false`

#### 1G-3: 辅助 API
```go
func (db *DB) GetDurableSequence() uint64
func (db *DB) IsWriteStopped() bool
```

### 验收标准
- [ ] Put 后 Get 返回正确值
- [ ] Delete 后 Get 返回 Found=false
- [ ] 空 value 正确区分（Found=true, Value=[]byte{}）
- [ ] 并发读写正确
- [ ] 未发布 entry 对 Get 不可见

---

## Phase 1H: MANIFEST + 文件管理

**目标**: 实现 MANIFEST 持久化和 WAL segment 生命周期管理。

### 任务

#### 1H-1: MANIFEST 格式
- 记录 recovery 起点的 recoverySegmentID
- temp + rename 原子更新
- MANIFEST 只在 checkpoint（MemTable flush）后推进

#### 1H-2: 首次创建 DB 流程
- 创建目录结构
- 创建初始 MANIFEST（recoverySegmentID=0）
- 创建初始 WAL segment

#### 1H-3: WAL Segment 生命周期
- 旧 segment 删除条件：已被 MANIFEST checkpoint 覆盖
- 删除顺序：先删除文件，再 fsync directory

### 验收标准
- [ ] 首次创建 DB 成功
- [ ] 重复打开 DB 正确恢复
- [ ] MANIFEST 原子更新
- [ ] 旧 WAL segment 正确清理

---

## Phase 1I: 集成测试 + Benchmark

**目标**: 端到端测试和性能基准。

### 任务

#### 1I-1: 集成测试
- 正常写入 + 读取 round-trip
- 并发写入 + 读取一致性
- 崩溃恢复（kill -9 模拟）
- WAL 尾部损坏恢复
- Write-stopped 后的行为
- Sequence 耗尽处理
- 配置校验拒绝非法配置
- 空 value 写入/读取
- 大量数据写入（触发 segment 轮转）

#### 1I-2: Benchmark
- 单线程 Put 吞吐
- 多线程 Put 吞吐
- 单线程 Get 延迟
- 多线程 Get 延迟
- WAL Recovery 时间
- 写入放大测量

#### 1I-3: Race Condition 测试
- `go test -race -count=100`
- 并发 Put + Get
- 并发 Put + Close

### 验收标准
- [ ] 所有集成测试通过
- [ ] Benchmark 数字可作为后续优化基线
- [ ] Race test 无 data race

---

## 依赖关系与并行度

```
1A ─────┐
        ├── 1B ─────┐
        │           ├── 1C ─────┐
        │           │           ├── 1F ── 1G ── 1I
        │           │           │
1A ── 1E ──────────┘           │
        │                       │
        ├── 1D ─────────────────┘
        │
        └── 1H ────────────────────────────── 1I
```

可并行开发的模块：
- 1A 完成后，1B/1D/1E/1H 可以并行开发
- 1B 完成后，1C 可以开始
- 1C + 1D + 1E 完成后，1F 可以集成
- 1F + 1H 完成后，1G 可以集成
- 所有完成后，1I 集成测试

## 技术要点备忘

### 内存序（最关键）
- skiplist next 指针：`atomic.Pointer` store-release
- `publishedSequence`：`atomic.Uint64` store（在所有 entry 节点发布后）
- 读者先 load publishedSequence（acquire），再遍历 skiplist

### WAL 副作用边界
- 未调用 `write()` → 普通错误
- 已调用 `write()` → ErrCommitUnknown + write-stopped
- 私有缓冲区编码，不共享 bufio.Writer

### ErrCommitUnknown 语义
- maybe committed，不是 definitely failed
- 不盲目重试
- 第一阶段为弱确认

### WAL Batch 资源前置校验
- sequence 分配之前完成所有可失败校验
- 减少 write-stopped 触发机会