From 2c58db5105181942c72cdf1c263291543b96954e Mon Sep 17 00:00:00 2001 From: dailz Date: Fri, 12 Jun 2026 09:24:09 +0800 Subject: [PATCH] update WAL published sequence design Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus --- docs/design.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/docs/design.md b/docs/design.md index 8014fdb..6f0d057 100644 --- a/docs/design.md +++ b/docs/design.md @@ -167,13 +167,13 @@ WAL 写入路径的失败分类如下： #### 可见性语义 -- `publishedSequence` 表示普通读的逻辑可见 high-water mark；普通读可以读取 MemTable，但只返回 `sequence <= publishedSequence` 的 entry +- `publishedSequence` 表示 WAL 物理 mutation sequence 的连续发布边界：普通读可以读取 MemTable，但第一阶段只返回 `sequence <= publishedSequence` 的 entry - fsync 前，写入可以已经存在于 MemTable 中，但处于 pending / unpublished 状态，仅供内部提交流程使用，对普通读不可见 - pending / unpublished / aborted entry 不仅对普通读不可见，也不得进入 SSTable；MemTable flush 必须遵守 3.3 的 Flush 过滤规则，只刷 `sequence <= publishedSequence` 且非 aborted 的 entry - `Always` 默认策略下，`publishedSequence` 也是 durable high-water mark；普通读能读到的数据，必须是崩溃恢复后仍可恢复的数据 - `Periodic` / `Never` 策略下，`publishedSequence` 可以领先于 durable high-water mark；普通读能读到当前进程内已发布的数据，但这些数据不保证机器掉电后仍可恢复 - 如果 WAL Entry 引用外部持久化对象（例如 Value Log record），发布 WAL Batch 前，被引用对象也必须满足当前落盘策略对应的持久化要求；在 `Always` 下这意味着该 Batch 引用的 Value Log ranges 必须先通过 3.9 的 durable barrier，避免恢复后出现悬空指针 -- 该模型为后续 MVCC / 事务层提供统一的 read timestamp / commit sequence 基础 +- 第一阶段单 key autocommit 中，`entry.sequence == commitSequence`，因此 `publishedSequence` 可同时作为普通读可见边界；后续 MVCC / SSI 引入多 key 事务后，`publishedSequence` 不改义为事务提交时间，而是继续表示物理发布 / durable / recovery 边界，事务可见性由独立的 `commitSequence` / `visibleCommitSequence` 控制 - `Always` 下该选择牺牲的是写入进入 MemTable 后到 fsync 发布前的短暂全局可见性延迟，不是已发布数据的读路径性能 #### WAL 落盘策略 @@ -448,6 +448,17 @@ WAL Batch 解析和写入必须使用同一套可配置资源上限。默认上 WAL 的 `baseSequence + i` 是物理 mutation sequence，用于保持 WAL 重放顺序和 `publishedSequence` 连续推进；它不能直接等同于多 key 事务的逻辑提交时间。 +相关 sequence 的职责边界如下： + +| 名称 | 范围 | 职责 | +|------|------|------| +| `walSequence` / `entry.sequence` | 单条 WAL 物理 mutation | 保证 WAL append、recovery replay、MemTable flush 与 Value Log 可达性判断的物理顺序 | +| `publishedSequence` | 连续的 WAL 物理 mutation high-water mark | 表示已发布到读路径且满足当前落盘策略的物理边界；也是 recovery / durable high-water mark；MVCC 引入后仍不表示事务可见时间 | +| `commitSequence` | 事务逻辑提交记录 | 表示 MVCC reader 与 SSI 冲突检测使用的逻辑提交 timestamp；同一事务内所有 mutation 共享一个 `commitSequence` | +| `visibleCommitSequence` / reader snapshot | 读事务或普通读的逻辑可见边界 | 事务时代的读可见性 high-water mark；读路径必须同时满足 MVCC 可见性规则和底层物理 mutation 已不超过 `publishedSequence` | + +因此系统在 MVCC / SSI 阶段会同时维护两个边界：`publishedSequence` 负责物理持久化与恢复连续性，`visibleCommitSequence` 负责事务逻辑可见性。二者在第一阶段单 key autocommit 中等价，但这是阶段性简化，不是长期语义。 + 第一阶段单 key autocommit 规则： ```text