#moonbitLog-StructuredDB

#特性

• 只追加日志：记录一旦写入不再修改，逻辑 offset 全局单调递增。
• 双后端：内存后端（backend_mem，可在 wasm/js 运行）+ native 文件后端（backend_native，基于 C stub FFI 的真实文件持久化），通过 io 抽象隔离核心引擎。
• 多段管理：Log 按 roll_size 滚动切段，段一旦 roll 不再修改。
• 稀疏索引：每段内嵌按间隔采样的稀疏索引（间隔随 roll_size 自适应，使每段索引条目数接近固定），get(offset) 与范围扫描先定位再顺序前进，避免全段扫描。
• 范围扫描：Segment::scan_range / Log::scan_range 支持半开区间 [from, to)。
• 崩溃恢复：Segment::recover 顺序解码、遇 torn/CRC 失败的尾部即截断到最后一个完好边界并重建索引与计数；native 侧 recover_log_dir 打开目录恢复全部 *.log 段。
• Tombstone：Log::delete 追加删除标记记录，历史不被改写。
• 保留策略：Log::drop_before / Log::retain_last / Log::retain_max_bytes / Log::retain_before（按 offset / 段数 / 总字节 / 时间戳）以整段删除方式回收旧数据。
• 可配置持久化：SyncPolicy 支持 Never / Always / Batch；CLI 默认 Always（命令返回即已 fsync），可用 MOONLOG_SYNC=batch|never 调整。
• 消费游标：ConsumerCursor 保存已提交读位置，按批 poll，可续读；位置可持久化到目录下的 CURSOR 文件。
• 物理备份/恢复：backup / restore 以独占锁 + 全量 flush 生成一致快照并原样拷贝段文件与元数据，offset 语义保留，恢复后的副本可无缝续写与续读；对已有备份目录重复执行 backup 为增量拷贝——备份副本比源端段文件新（源端自上次备份未被修改）即跳过，源端已删除的段自动清理，大目录备份成本降为 O(变更)。
• 修复模式：fsck --fix（repair_log_dir）隔离整段校验失败的段（改名 .corrupt 保留证据）、截断损坏尾部、重建缺失/损坏的 MANIFEST 与段 sidecar。
• 尾随读：follow 持续打印新追加的记录（tail -f 语义），支持从持久化游标续读并 --commit 自动提交。
• 自动维护：serve 周期性执行 maintain 管线（段合并 + 冗余回收 + 可选过期折叠）。
• KV 逻辑视图与 compaction：KeyIndex 提供 key→最新值查询（tombstone 生效），缓存索引随 append 增量维护（put 刷新、tombstone 移除，段集合结构变化才整体失效），写密集点查不再触发全量重建；Log::snapshot 生成折叠后的 live 记录，compact 命令重写目录。
• 并发安全：native 后端基于 flock 对目录加建议锁（写者独占 / 读者共享），CLI 写入与 compact/prune 互斥，读者总是观察到一致的偏移快照。
• 工程化：property/fuzz 随机截断与损坏恢复测试、moon bench 基准、GitHub Actions CI（工具链固定 + fmt --check/.mbti 快照/bench 阈值四重门禁）。
• CLI：native 命令行工具覆盖上述能力。

#包结构

#构建与测试

moon build --target native   # 构建（含 CLI）
moon test                    # wasm 目标测试
moon test --target native    # native 目标测试
moon bench --target native   # 基准：追加 / 点查 / 范围扫描 / 恢复
moon test --enable-coverage --target native   # native 覆盖率采集
moon coverage report -f summary               # 覆盖率摘要

#CLI 用法

moonlog <command> <dir> [args...]

  put <dir> <key> <value>       追加一条 key/value 记录
  put-if <dir> <key> <expected|-> <value>
                                仅当 live 值等于 expected（`-` 要求不存在）才追加
  put-batch <dir> <k> <v> ...   一次追加多组 key/value 记录
  delete <dir> <key>            追加 key 的 tombstone
  get <dir> <offset>            按 offset 读取记录
  scan <dir> [from] [to]        列出 [from, to) 区间记录
  scan-prefix <dir> <prefix>    按 key 前缀列出（结果按 key 排序）
  scan-range <dir> <lo> [hi]    按 key 半开区间 [lo, hi) 列出（hi 省略表示无上界）
  scan-time <dir> <lo> <hi>     列出 timestamp 落在 [lo, hi) 的记录
  recover <dir>                 打开并恢复，报告计数
  prune <dir> <keep-segments>   只保留最新 N 个段
  prune-bytes <dir> <bytes>     回收最旧段直到总字节 <= bytes
  prune-before <dir> <timestamp> 回收末条记录早于 timestamp 的段
  prune-expired <dir> <ttl>     回收末条记录早于 now-ttl 的段
  prune-superseded <dir>        回收所有记录均被后续覆盖的段
  merge <dir> <max-segments>    将连续的已 roll 段合并至不超过 N 段
  maintain <dir> <max-segments> [ttl]
                                一键维护：合并 + 冗余回收 + 过期折叠 + 压缩
                                已 roll 段 + fsck
  cursor <dir> <start|-> <limit>  按批读取消费游标（`-` 从持久化位置续读）
  cursor-commit <dir> <position> 持久化消费游标位置
  cursor-lag <dir>              报告每个消费游标的滞后量（next_offset -
                                position），便于发现停滞的消费者
  cursor-save <dir> <name> <pos> 持久化命名消费游标位置
  cursor-load <dir> <name>      读取命名消费游标位置
  cursor-list <dir>             列出全部命名消费游标位置
  cursor-drop <dir> <name>      删除命名消费游标位置
  follow <dir> [start|-|tail] [--once] [--commit] [--json] [--name <cursor>]
                                持续打印新追加的记录（`-` 从持久化游标续读，
                                `tail` 从当前末尾开始；`--commit` 每批后提交
                                游标，`--name` 指定命名游标以支持多消费者各
                                自 follow/提交；`--json` 以单行 JSON 输出
                                （UTF-8 文本，与 export-jsonl 同构）；`--once`
                                拉取一轮即退出；轮询间隔可用
                                `MOONLOG_FOLLOW_INTERVAL` 调整，默认 200ms）
  serve <dir> <max-segments> [ttl] [--every ms] [--fsck-every N] [--once]
                                周期性执行维护（合并 + 冗余回收 + 可选过期折
                                叠 + 压缩 + flush 元数据）；`--every` 或
                                `MOONLOG_SERVE_INTERVAL` 设置周期，默认
                                60000ms；`--fsck-every N` 每 N 轮跑一次快
                                速 fsck 并输出报告；`--once` 执行一轮即退出
  backup <dir> <dst>            将目录的一致快照拷贝到空目录 dst（独占锁内
                                flush 数据与元数据后原样拷贝段文件、sidecar
                                与 MANIFEST；不拷贝 LOCK 与游标文件）
  restore <src> <dst>           将 backup 产物还原到空目录 dst（offset 原样
                                保留，恢复后可无缝续写、游标仍有效；完成后
                                自动 verify_fast 校验并输出报告）
  getkey <dir> <key>            查询 key 的最新值（tombstone 生效）
  getkey-live <dir> <key> <ttl> 查询 key 的最新值，过期则视为不存在
  has-key <dir> <key>           用段级 Bloom 过滤判断 key 是否存在
  export <dir> <file>           导出全部记录（含 tombstone）到可移植文件
  export-jsonl <dir> <file> [base64]
                                导出全部记录为 JSON Lines（每行一个 JSON 对
                                象：offset/timestamp/kind/key/value；默认文
                                本模式假定 UTF-8 文本、控制字符转义，`base64`
                                模式对任意字节无损）
  import <dir> <file>           从可移植文件回放记录
  compact <dir>                 折叠为 live 记录并重写目录
  compact-expired <dir> <ttl>   折叠 live 记录并剔除已过期记录（offset 重排）
  fsck <dir> [fast] [--fix] [--dry-run]
                                校验完整性（fast 跳过记录解码，段级 CRC）；
                                `--fix` 先执行修复：隔离整段校验失败的段
                                （改名 `<name>.corrupt` 保留证据）、截断损坏
                                尾部、重建 MANIFEST 与全部段 sidecar，随后
                                再校验一次并输出报告；`--dry-run` 只打印修
                                复计划（将截断/隔离/删除什么），不改盘
stats <dir> [json]            打印逐段统计（含每段逻辑字节 disk 磁盘字节与
                              压缩汇总；可选 JSON）
version                       打印 moonlog 版本号（与 moon.mod 同步）

#API 概览

#在 wasm / JS 中使用

let store = @backend_mem.MemLog::new()
let log : @log.Log[@backend_mem.MemLog, @backend_mem.MemLog] = @log.Log::new(
  1_048_576,
  base => @segment.Segment::new(store, store, base),
)
ignore(log.append(b"user:1", b"alice", 0))
let recs = log.scan()

#可运行示例

moon run examples/mem_demo --target native
moon run examples/mem_demo --target wasm

moon run examples/native_demo --target native

#架构

          ┌──────────────┐
          │  cli（CLI）  │  put / scan / compact / export / fsck …
          └──────┬───────┘
                 │
          ┌──────▼───────┐
          │     log      │  Log[W,R]：多段、offset、保留、游标、KV 视图
          └───┬──────┬───┘
              │      │
    ┌─────────▼─┐  ┌─▼──────────┐
    │  segment  │  │    core    │  记录编解码 / CRC32
    └─────┬─────┘  └────────────┘
          │
   ┌──────▼───────────────────┐
   │ io：LogWriter/Reader/    │
   │     LogTruncate/IoError  │
   └───┬──────────────────┬───┘
       │                  │
┌──────▼──────┐    ┌──────▼────────┐
│ backend_mem │    │ backend_native│  flock / C stub FFI
└─────────────┘    └───────────────┘

• 存储抽象（io）让同一份 log/segment 逻辑同时运行在内存（wasm/js）与文件（native）后端之上。
• segment 负责单段的 append、稀疏索引、范围扫描与崩溃恢复；log 在其上实现多段管理、全局 offset、保留策略、消费游标、KV 视图与 compaction。

#磁盘格式

u32 body_len
body:
  u8  flags        (0 = Put, 1 = Delete)
  u64 offset
  i64 timestamp
  u32 key_len
  u32 value_len
  key[key_len]
  value[value_len]
u32 crc32          (仅覆盖 body)

#持久化元数据（M8）

• 每个段旁挂 <name>.log.index：保存该段计数、稀疏索引快照、该段 key 的 Bloom 过滤器、时间跨度（min/max timestamp），以及已 roll 段的整段数据 CRC32 与压缩标志 + 原始大小（整体含 CRC32），重开时可直接恢复，无需扫描数据。采用版本化布局，打开时按版本解析（向后兼容读取 v1–v7）：
  • v1：header + 稀疏索引条目；v2：+ Bloom 过滤器；v3：+ 时间跨度（min_ts/max_ts/time_known）
  • v4：+ 整段数据 CRC32（data_crc/crc_known，仅已 roll 段）；v5：+ 压缩标志与原始大小（compressed/raw_size）
  • v6：+ 时间有序标志（ts_sorted）；v7：+ 压缩算法（comp_algo：0 无 / 1 RLE / 2 LZSS）
• 每个段旁挂 <name>.log.keys：保存该段 key → 最新 offset（含 tombstone 标志）索引（含 CRC32），重开时直接加载；缺失或损坏则回退重建扫描。
• 目录级 MANIFEST：记录 roll_size、next_offset 与段清单（每段的 base_offset 与 byte_size，整体附 CRC32）。打开时据此校验每个段文件的真实大小，不符则回退全量恢复。
• open_log_dir 优先使用上述元数据（快速路径）；缺失或校验失败时回退到 recover_log_dir 全量恢复。
• 元数据（MANIFEST 与每段 .index）以原子替换落盘：写入 <name>.tmp → fsync → rename 覆盖 → fsync 目录。进程在任意时刻崩溃只会留下旧版或新版，不会出现半写文件。

#目录锁与游标文件（M12）

• LOCK：flock 建议锁的载体。写者取独占锁，读者取共享锁；DirLock::acquire_timeout 在有限时间内重试忙锁（CLI 默认 5s，可用 MOONLOG_LOCK_TIMEOUT 调整），使多写者排队而非立即失败；compact 会保留该文件。
• CURSOR / CURSOR.<name>：CLI 持久化的（命名）消费游标位置。编码为 u32 magic("MLCU") + u64 position + u32 crc32，损坏或缺失时回退为 0；写入采用原子替换。

#游标与段回收语义（M72）

• prune-superseded / prune-bytes / prune-before / prune-expired / maintain 会自动枚举目录下全部游标（CURSOR 与 CURSOR.*），跳过仍含未消费记录的段（段尾 offset 大于最小游标位置），消费者不会因回收而丢失未读数据；游标文件损坏时按位置 0 保守处理（保护全部段）。
• compact / compact-expired / import 会重排 offset：执行后所有游标位置失效，命令会输出警告——请用 cursor-commit 0（或 cursor-save <name> 0）重置游标后重新消费。
• merge 不删除任何记录（offset 保留），游标位置在合并后依然有效。

#运维指南（M75）

• fd 上限：每个打开的段占用 1 个文件描述符（另有 LOCK 等少量 fd）。段数接近 ulimit -n 时，open_log_dir / 写命令会以 Syscall 错误失败——用 merge <dir> <max-segments> 或 maintain 减少段数，或调高 ulimit -n。
• 维护周期：建议定期执行 maintain <dir> <max-segments> [ttl]：段合并控制读放大与 fd 占用，prune-superseded 回收冗余空间，compact-expired <ttl> 回收过期数据。
• 游标语义：prune-* 系列自动保护未消费段；compact / compact-expired / import 重排 offset 后需重置游标——详见「游标与段回收语义（M72）」。
• fsck 两档：日常巡检用 fsck <dir> fast（不解码记录体，段级 CRC）；事故排查用 fsck <dir>（全量解码，能定位记录级损坏）。
• 异地同步/复制（M92）：段文件 immutable，是天然的增量复制单元，无需专用协议即可搭建主→备同步：

  # 主机（生产者）：定时增量推送（backup 幂等，重复执行只传变更段）
  moonlog backup /data/moonlog primary-bak
  rsync -a --delete primary-bak/ backup-host:/data/moonlog-replica/
  
  # 备机（消费者）：首次落地 + 周期刷新
  moonlog backup /data/moonlog primary-bak   # 增量
  rsync -a primary-bak/ replica/

  备机目录结构与主目录字节一致（MANIFEST/段/sidecar），offset 与游标语义原样保留——备机可直接 scan / getkey / follow - 消费，故障切换时把备机目录交给写者即可（游标文件不随 backup 拷贝，如需保留消费进度先 cp CURSOR* 或在备机 cursor-commit）。注意：只做单向复制，双主互写不受支持。

#里程碑

• M0/M1 脚手架、记录编码与内存后端、单段 append
• M2 多段 Log 与 native 文件后端
• M3 稀疏索引与范围扫描
• M4 崩溃恢复（torn-tail 截断）
• M5 tombstone、保留策略、消费游标
• M6 CLI 与文档
• M7 边界测试与显式 CLI 参数校验
• M8 段索引与目录 manifest 持久化（打开免全量扫描）
• M9 流式段读取与 for_each（收敛 IO）
• M10 key 索引、快照与 compact
• M11 可配置 durability（SyncPolicy）与按字节保留
• M12 flock 目录锁、读快照与 CLI 游标持久化
• M13 property/fuzz 恢复测试、moon bench、CI 与 API/CHANGELOG 文档
• M14 compaction 提升为 Log::compact 库方法
• M15 按时间戳保留（Log::retain_before 与 prune-before）
• M16 manifest 记录段字节大小并在打开时校验
• M17 examples/mem_demo 可运行示例（wasm/js/native）
• M18 批量写入 Log::append_batch 与 CLI put-batch
• M19 完整性校验 Log::verify 与 CLI fsck
• M20 命名消费者游标（cursor-save / cursor-load）
• M21 元数据原子写（tmp + fsync + rename + fsync 目录）
• M22 组提交：SyncPolicy::Batch 与 Log::flush（批量写只 fsync 一次）
• M23 创建/删除加固：新建段与删除段后 fsync 目录，游标原子写
• M26 记录级 TTL：Log::get_latest_at / Log::scan_live 与 CLI getkey-live / prune-expired
• M27 命名游标管理：list_named_cursors / remove_named_cursor 与 CLI cursor-list / cursor-drop
• M28 导出/导入：Log::export_bytes / Log::import_bytes 与 CLI export / import
• M24 自适应稀疏索引间隔：index_interval_for 按 roll_size 估算
• M25 读取路径：实测读缓存比直接 pread 慢约 3.7×，故保留直接 pread；新增 native 顺序扫描基准
• M29 CI 增强：native 覆盖率摘要 + bench 结果归档
• M30 架构文档与发布工作流（release 触发 moon publish）
• M31 审阅修复：Log::flush 刷所有段、import_bytes 批量落盘、CLI 支持 MOONLOG_SYNC=batch
• M32 审阅修复：CLI 默认 MOONLOG_SYNC=always（命令返回即落盘），并明确 import 的 offset 语义
• M33 key 前缀扫描：Log::scan_prefix 与 CLI scan-prefix（结果按 key 排序）
• M34 段级 Bloom 过滤：BloomFilter 持久化进 .index（meta v2），Log::get_latest_bloom 跳过不可能含 key 的段；CLI has-key
• M35 时间范围查询：段级 min/max timestamp 持久化进 .index（meta v3），Log::scan_time_range 跳过无重叠段；CLI scan-time
• M36 key 区间扫描：Log::scan_key_range 按 [lo, hi) 返回每个 live key 的最新记录（按 key 排序，空 hi 表示无上界）；CLI scan-range
• M37 二进制安全 key 索引：KeyIndex 改以 key 原始字节为键（此前用有损 utf8.decode_lossy，非法 UTF-8 的不同 key 会塌缩冲突），scan_prefix 改按原始字节匹配；新增回归测试
• M38 段数据校验和：已 roll 段在 .index 记录整段数据 CRC32（meta v4，旧版本读为未校验）；Log::verify 报告首个校验和不符的段（VerifyReport::first_bad_checksum）
• M39 有序 key 索引：KeyIndex 维护按字节排序的 live key 列表，scan_prefix / scan_key_range 改为二分定位 + 点查（不再全量扫段 + 排序）
• M40 多键批量点查：Log::get_many 一次返回多个 key 的最新 live 记录（共享一次索引扫描）；CLI get-many
• M41 逆序扫描与 tail：Log::scan_reverse 按 offset 降序返回区间记录，Log::tail 返回最近 n 条（按 append 顺序）；CLI tail
• M42 缓冲写合并：NativeFileLog 把小追加合并成更少的 pwrite；读取 / flush / truncate / close 与写元数据前先 drain，写命令返回时文件大小与逻辑大小一致
• M43 段压缩：纯 MoonBit RLE（core.rle_compress / core.rle_decompress）；CLI compress 原地压缩所有已 roll 段（meta v5 记录压缩标志与原始大小），打开时透明解压为只读视图，旧版本 meta 读为未压缩
• M44 原子批量写入：Log::append_batch_atomic 失败时整体回滚（删除批中新建段、截断并重建原活跃段、恢复 offset 空间）
• M45 可观测性：Log::segment_summaries 暴露每段计数 / 大小 / 压缩标志 / 时间跨度；CLI stats 打印逐段信息并支持 stats <dir> json
• M47 持久化 key 索引：每段内存维护 key→最新 offset（含 tombstone 标志），flush_meta 写入 .keys sidecar；重开直接加载（缺失/损坏回退重建扫描），build_key_index 不再全量扫段
• M48 表驱动 CRC32：crc32 改为加载时构建 256 项查表，替代逐位计算
• M49 段内时间索引：段记录 timestamp 是否非递减（meta v6 持久化）；scan_time_range 对有序段二分定位 [lo, hi) 的 offset 窗口，无序段回退线性过滤
• M50 段压缩增强：新增纯 MoonBit LZSS（core.lz_compress / lz_decompress，4 KiB 窗口）与 RLE 并存；CLI compress <dir> [rle|lzss] 可选算法（默认 lzss），meta v7 记录算法以正确解压
• M51 冗余段回收：Log::prune_superseded 删除所有记录均被后续覆盖（同 key 更新 / tombstone）的已 roll 段，回收空间且不重排 offset；CLI prune-superseded
• M52 并发写锁超时：DirLock::acquire_timeout 在超时前重试忙锁（新增 nanosleep stub），多写者排队而非立即失败；CLI 等待上限由 MOONLOG_LOCK_TIMEOUT 控制（默认 5000ms）
• M53 CLI dry-run 与批量 key：compress / prune-superseded 支持 dry-run（经 count_compressible_segments / Log::count_superseded 只读报告）；get-many 支持 --keys <file> 按行读取 key
• M54 复杂度回归保护：CountReader 测试断言 build_key_index 不读记录体（锁定 M47 带来的 O(keys) 开销）
• M55 文档与 native 示例：新增 examples/native_demo（文件后端端到端演示）；README 补齐本轮（M47–M54）能力说明
• M56 旧格式兼容性测试：构造 v1–v7 各历史版本的段元数据字节，断言当前解码器均可正确读取（锁定向后兼容）
• M57 崩溃一致性测试：损坏 .index、删除 MANIFEST / .index / .keys 后，断言 open_log_dir 仍能从段数据恢复记录并重建 key 索引
• M58 段合并：Log::merge_segments 将 offset 连续的已 roll 段合并为更少的段（保留逻辑 offset）；CLI merge <dir> <max-segments>
• M59 key 索引缓存：Log::build_key_index 记忆化结果并在任意变更（append/delete/保留/回收/合并/compact）后失效，同进程重复 KV 查询每次变更后最多重建一次；Log::index_build_count 暴露实际构建次数
• M60 复杂度基线扩展：断言 scan_range 只读请求窗口、scan_time_range 跳过无重叠段（补充 M54 的 key 索引基线）
• M62 property 测试：固定 seed 的随机 append/delete/读校验序列对照内存模型（强制跨段滚动），结尾全量 verify
• M63 TTL 空间回收闭环：Log::compact_expired(now, ttl) 在折叠 live 时同时丢弃已过期记录与对应 tombstone（offset 重排，同 compact）；CLI compact-expired <dir> <ttl>
• M64 条件写入 CAS：Log::compare_and_swap(key, expected, value, ts) 仅当 live 值匹配期望（或要求 key 不存在）才追加；CLI put-if
• M65 sidecar 写放大优化：段级 meta_dirty 标志，flush_meta 只重写有变更段（新 roll / checksum / 压缩）的 .index/.keys，干净已 roll 段跳过
• M66 发布 0.5.0：property 测试、TTL 折叠、CAS、sidecar 写放大优化随包发布
• M67 native property 测试：文件后端随机操作 + 周期性注入 torn tail（fsync 后截断最后段数据文件），模型按存活记录数重建
• M73 选择性 fsync：段级 fsync_dirty，Log::flush / SyncPolicy::Always 只 fsync 有新数据的段；行为变化：flush() 幂等化（无新追加时为 no-op）
• M74 快速校验：Log::verify_fast / CLI fsck <dir> fast 不解码记录体，只校验段连续性、计数一致性与段级 CRC32（fast 不能发现记录级损坏，full 仍是彻底校验）
• M68 live 折叠点查化：snapshot / scan_live 经 key 索引逐 key 点查（按 offset 排序保持输出顺序），替代二次全量扫描
• M69 段内 ts 采样索引：Segment 维护与稀疏索引同步的内存 ts 采样（append/rebuild 填充），lower_bound_ts 先对采样二分（零 I/O）再至多走一个采样区间；无采样的新打开段回退点探二分
• M70 一键维护：CLI maintain <dir> <max-segments> [ttl] 聚合段合并 + 冗余段回收 + 过期折叠（可选）+ fsck 报告
• M71 发布 0.6.0：native property 测试（含 torn tail 注入）、live 折叠点查化、ts 采样索引、maintain 命令随包发布
• M76 发布 0.7.0：游标感知回收、选择性 fsync（flush 幂等化）、fsck fast、运维指南随包发布
• M77 维护/游标 property 测试 + 修复：随机维护（merge/prune-superseded/compact）与游标推进的 property 测试；修复 prune_superseded 不再删除含 tombstone 的段（防旧 put 复活）
• M78 ts 采样持久化（meta v8）：稀疏索引条目附 timestamp（兼容读 v1–v7），打开的段加载即恢复内存 ts 采样，scan_time_range 立即使用采样二分
• M79 get_many 段分组点查：批量点查按 offset 排序后单次顺序遍历段，替代逐 key 重复定位
• M80 发布 0.8.0：维护/游标 property 测试、tombstone 安全修剪修复、ts 采样持久化、get_many 段分组随包发布
• M81 物理备份/恢复：backup_log_dir / restore_log_dir 与 CLI backup / restore（独占锁内 flush 后原样拷贝，空目录强制、MANIFEST 校验，offset 保留）
• M82 修复模式：repair_log_dir 与 CLI fsck --fix（整段 CRC 失败隔离为 .corrupt、torn-tail 截断、空段清理、MANIFEST 与段 sidecar 原子重建）
• M83 尾随读：CLI follow（轮询新记录持续输出，-/tail/offset 起点、--commit 自动提交游标、--once 单轮、MOONLOG_FOLLOW_INTERVAL 间隔）
• M84 自动维护：CLI serve（周期性维护管线，--every/MOONLOG_SERVE_INTERVAL 周期、--once 单轮；maintain 核心重构为共享的 run_maintenance）
• M85 增量备份：backup_log_dir 对既有备份目录增量执行——备份副本比源端段文件新（源端自上次备份未被修改）即跳过、源端已删段自动清理、MANIFEST 与 sidecar 始终重拷（原地重写），大目录备份降为 O(变更)。M98 发现并修复了原"同名同尺寸跳过"启发式的缺陷：compact/merge 会以同名重写段文件，尺寸可能不变而内容已变——现改用纳秒级 mtime 判断（file_mtime_ns，新增 stub）
• M86 维护管线集成压缩：compress_rolled_segments 从 compress_log_dir 抽出为库 API，maintain / serve 管线自动压缩全部已 roll 段（LZSS）并输出 compressed N
• M87 消费滞后监控：CLI cursor-lag 报告默认与命名游标的 position/lag 与 next_offset
• M88 修复鲁棒性 property 测试：固定 seed 随机注入截断/翻转字节/删 MANIFEST/删 sidecar/追加 torn 尾（1–3 类/轮，40 轮），断言 repair 后存活记录与原始一致、verify 通过、可续写
• M89 流式遍历：Segment::for_each_while / Log::for_each_while（f 返回 false 提前终止，跨段传播）与 Log::for_each_time_range；CLI scan/scan-time/tail 改流式输出，大结果集不再物化 Array
• M90 批量读快路径：scan/rebuild_index/recover 改为单次读全段后内存顺序解码（decode_in），消除逐记录 pread——native bench 段恢复 86.9ms→5.2ms（16.7×）、全量顺序扫描 2.77ms→0.86ms（3.2×），点查/写入持平
• M91 观测与导出：SegmentSummary 增加逻辑字节与 disk_bytes，stats 输出每段与总体的压缩尺寸（文本/JSON）；CLI export-jsonl 以 JSON Lines 导出（text/base64 双模式，内置 RFC 4648 base64 编码器）
• M92 复制方案文档化：运维指南新增「异地同步/复制」——增量 backup + rsync 搭建主→备只读副本（offset/游标语义保留），并明确单写多读边界
• M93 恢复即校验：restore 完成后自动对恢复副本执行 verify_fast 并输出报告，静默损坏的备份在投入使用前即被拦截
• M94 修复预览：repair_log_dir 增加 dry_run 模式（只读探测 probe_records），CLI fsck --dry-run 打印修复计划——将截断/隔离/删除什么，不改盘；dry-run 计划与实际修复结果一致（测试断言）
• M95 KeyIndex 增量维护：append 将新记录增量折叠进缓存的 key 索引（KeyIndex::update——新 offset 恒更大，put 刷新 latest、tombstone 移除键），sorted_keys 视图惰性重算；仅段集合结构变化（保留/合并/压缩/导入重放）才整体失效，写密集点查消除 O(全部 key) 的全量重建
• M96 Bloom 快查 O(1) 化：latest_key_in_segment 直接查段的内存 key 映射（append/rebuild/.keys sidecar 加载恒就绪）取 latest offset 后单点读取，get_latest_bloom 从 O(段大小解码) 降为 O(1)，不再全段扫描
• M97 前缀/区间扫描段分组读取：scan_prefix / scan_key_range 按 offset 顺序单遍读取（复用 get_many 的段分组模式 M79）后按 key 序重排，消除逐 key 跨段定位的读放大
• M98 增量备份 property 测试：固定 seed 随机写序列（put/delete 交错、每三轮 compact）× 8 轮增量 backup → restore，断言与源端逐记录等价；该测试暴露并驱动修复了"同名同尺寸跳过"启发式在 compact 重写同名段时的 stale 数据缺陷（改用纳秒级 mtime 判断）
• M99 follow 程序化消费：--json 以单行 JSON 输出记录（UTF-8 文本、控制字符转义，与 export-jsonl 同构）；--name <cursor> 支持命名游标的读取与提交，多消费者可各自 follow 互不干扰
• M100 serve 周期巡检：--fsck-every N 每 N 轮维护后对日志执行 verify_fast 并输出报告，常驻守护自带完整性巡检
• M101 CLI version 命令：输出 moonlog 版本号（与 moon.mod 同步维护）
• M102 CI 性能门禁：ms 级 native 基准（顺序扫描/区间扫描/段恢复）与保守阈值（本地 pinned 工具链值的 5–6 倍余量）比较，仅拦截数量级回退，规避共享 runner 的 µs 级噪声
• M103 export/import roundtrip property 测试：固定 seed 随机 put/delete 序列 × 6 轮，导出记录流重放进全新目录，断言逐记录等价（offset 连续、timestamp/kind/payload 保留）

#许可