# Requirements Archive: v1.0 Performance Optimization

**Archived:** 2026-04-26
**Milestone:** v1.0 Performance Optimization
**Core Value:** 在任意硬件上达到尽可能高的解析吞吐量（records/sec 和 GB/s）

---

## v1 Requirements — All Completed

### Measurement（测量基础设施）

- [x] **MEAS-01**: benchmark 以 GB/s 和 records/sec 报告吞吐量（criterion::Throughput）
- [x] **MEAS-02**: benchmark 包含 `parse_performance_metrics()` 调用变体（反映真实调用路径）
- [x] **MEAS-03**: benchmark 包含含多行 SQL 的真实分布合成语料库
- [x] **MEAS-04**: CI 加入 benchmark 回归门禁（对比 baseline.json，超过 5% 退化则失败）

### Correctness（正确性加固）

- [x] **CORR-01**: 编码检测采样范围扩展至全文件（head+tail 采样），消除 64 KB 截断导致的误分类
- [x] **CORR-02**: Miri 加入 CI，覆盖 unsafe 解码路径
- [x] **CORR-03**: `find_indicators_split` 针对 SQL body 内含指标关键字（如 `EXECTIME:`）的场景有测试用例

### HotPath（零风险热路径优化）

- [x] **HOT-01**: `find_indicators_split` 在记录末尾不以 `.` 结尾时快速返回，跳过 3 次 rfind
- [x] **HOT-02**: `find_indicators_split` 改为单次反向字节扫描，替代 3 个独立 `rfind` 调用
- [x] **HOT-03**: `parse_performance_metrics` 标注 `#[inline(always)]`，错误路径标注 `#[cold]`
- [x] **HOT-04**: `LogParser::from_path` 调用 `mmap.advise(Advice::Sequential)`

### CoreAlgo（核心算法优化）

- [x] **ALGO-01**: `LogIterator::next()` 使用预构建 `memmem::Finder(b"\n20")` 混合快速路径替代 `memchr(b'\n')` 逐行循环
- [x] **ALGO-02**: 时间戳检测改为打包 `u64` 掩码比较，替代 8 个独立字节比较分支

### Parallel（并行优化）

- [x] **PAR-01**: 引入 `LogParser::index()` 返回 `RecordIndex`（记录起始位置 `Vec<usize>`），支持两阶段扫描
- [x] **PAR-02**: `par_iter()` 改用 `RecordIndex` 实现记录级均匀分区（实现完成；speedup 目标 ≥1.6x 未达，实测 1.01x — Known Gap，已 accept-as-is）
- [x] **PAR-03**: `par_iter()` 在文件小于阈值（32 MB）时自动退化为串行迭代

---

## v2 Requirements（归档至下一 milestone）

### Advanced（高级优化）

- **ADV-01**: PGO（Profile-Guided Optimization）构建流水线
- **ADV-02**: `mimalloc` 可选 feature flag（`features = ["fast-alloc"]`）
- **ADV-03**: BOLT 二进制优化（待 Rust 工具链支持成熟后评估）

---

## Traceability

| Requirement | Phase | Status | Outcome |
|-------------|-------|--------|---------|
| MEAS-01 | Phase 1 | ✅ Complete | criterion Throughput::Bytes + Elements 双维度 |
| MEAS-02 | Phase 1 | ✅ Complete | parse_sqllog_metrics_5mb benchmark 变体 |
| MEAS-03 | Phase 1 | ✅ Complete | 20% 多行语料库合成函数 |
| MEAS-04 | Phase 1 | ✅ Complete | check-regression.sh + CI 门禁 |
| CORR-01 | Phase 2 | ✅ Complete | head+tail 全文件编码检测 |
| CORR-02 | Phase 2 | ✅ Complete | miri.yml CI 作业 |
| CORR-03 | Phase 2 | ✅ Complete | 验证守卫 + 6 条新测试 |
| HOT-01 | Phase 3 | ✅ Complete | O(1) 早退，末尾无 `.` 跳过 rfind |
| HOT-02 | Phase 3 | ✅ Complete | 单次 memrchr(b':') 反向扫描 |
| HOT-03 | Phase 3 | ✅ Complete | inline(always) + cold 标注 |
| HOT-04 | Phase 3 | ✅ Complete | Advice::Sequential mmap |
| ALGO-01 | Phase 4 | ✅ Complete | FINDER_RECORD_START memmem 混合快速路径 |
| ALGO-02 | Phase 4 | ✅ Complete | is_timestamp_start() u64 掩码 |
| PAR-01 | Phase 5 | ✅ Complete | RecordIndex + index() 公共 API |
| PAR-02 | Phase 5 | ⚠️ Partial | 实现完成，speedup 1.01x（目标 ≥1.6x）— Known Gap |
| PAR-03 | Phase 5 | ✅ Complete | 32 MB 阈值自动退化串行 |

**Coverage: 15/16 完全达成，1/16 实现完成但 speedup 目标未达（PAR-02）**

---

*Requirements archived: 2026-04-26 after v1.0 milestone completion*
