epic(build): 加速 RocksDB native 依赖的本地与 CI 编译

[AlexStocks]

背景

Kiwi 通过自定义 arana-db/rust-rocksdb fork 使用 RocksDB。当前 native 依赖构建会编译约 330 个 RocksDB C++ 源文件；在一次代表性的 WSL dev 构建中，生成约 334 个对象文件，librocksdb.a 约 943 MiB，整个 target 目录约 6.27 GiB。

现有开发与 CI 配置已经启用了部分 Rust 构建优化，但 RocksDB native 编译仍存在以下问题：

1. WSL 构建产物位于 /mnt/d/.../target，大量 C++ 对象和静态库通过 Windows 挂载文件系统写入。
2. Windows 与 WSL 在未指定独立 CARGO_TARGET_DIR 时可能共用工作区 target/debug，导致不同宿主工具链的 fingerprint 和 native 产物互相失效。
3. 根 Cargo.toml 的 dev profile 使用 debug = 1，该设置会通过 Cargo 的 DEBUG 环境变量传给 cc-rs，使 RocksDB C++ 对象包含调试信息。
4. .cargo/config.toml 固定 jobs = 8，不能根据开发机 CPU 和内存自动调整；当前 rust-librocksdb-sys 已启用 cc-rs 的 parallel feature。
5. 本地环境没有统一启用 sccache；CI 只设置了 RUSTC_WRAPPER=sccache，没有用 CC / CXX 包装 RocksDB 的 C/C++ 编译器。
6. clippy 与 build/test 主 job 只缓存 ~/.cargo/registry 和 ~/.cargo/git，没有复用已经编译的 native dependency artifacts。
7. 直接设置 ROCKSDB_LIB_DIR=/usr/lib 不能安全解决 Kiwi 的问题：当前 fork 额外编译 rocksdb_ext/c_ext.cc，提供 TablePropertiesCollector FFI，而普通系统 RocksDB 不包含这些符号。

本 Epic 统一组织本地构建、WSL、Cargo profile、C/C++ 编译缓存、CI 缓存、预编译 RocksDB 以及 fork 扩展拆分工作。

已确认的技术约束

• 当前依赖固定为 arana-db/rust-rocksdb@f7abb18c64fac810f3c4736aef833c340396449b。
• 对应 rust-librocksdb-sys 版本为 0.41.0+10.9.1，RocksDB submodule revision 为 5fbc1cd5bcf63782675168b98e114151490de6d9。
• fork 默认启用 snappy、lz4、zstd、zlib、bzip2 和 bindgen-runtime；当前 Kiwi 配置公开支持全部五种压缩算法，默认使用 LZ4。
• rocksdb_ext/c_ext.cc 提供以下 Kiwi/Raft 路径实际使用的符号：
  • rocksdb_table_properties_collector_create
  • rocksdb_table_properties_collector_factory_create
  • rocksdb_options_add_table_properties_collector_factory
• 当前 build script 在发现 ROCKSDB_LIB_DIR 后会跳过 build_rocksdb()，同时也跳过 rocksdb_ext/c_ext.cc；因此普通系统库不能直接替代 bundled build。
• ROCKSDB_STATIC 按“环境变量是否存在”判断；ROCKSDB_STATIC=0 仍会选择静态链接，动态链接必须 unset 该变量。
• ROCKSDB_COMPILE=1 应保留为强制回退 bundled build 的逃生路径。

目标

1. 未修改代码的第二次构建不重新执行 RocksDB C/C++ 编译。
2. 普通 Rust 源码修改不使 rust-librocksdb-sys 变为 Dirty。
3. Windows、WSL/Linux、macOS 的 native 产物互不污染。
4. 降低冷构建时间、热构建时间、target 体积和 CI native 编译次数，并用可复现数据证明效果。
5. 让本地和 CI 的 sccache 真正覆盖 Rust、C 与 C++ 编译。
6. 建立版本化、可校验、包含 Kiwi 自定义 FFI 的预编译 RocksDB 方案。
7. 在预编译库不可用或不兼容时，仍可可靠回退到 bundled source build。

非目标

• 本 Epic 不替换 RocksDB 作为 Kiwi 的生产存储后端。
• 本 Epic 不直接决定 [FEATURE] Replace the rocksdb dependency library #213 中是否迁移到 TiKV 或其他 RocksDB wrapper。
• 第一阶段不删除 Kiwi 已公开支持的压缩算法。
• 不通过降低测试、Lint、Raft 持久化或 TablePropertiesCollector 功能换取构建速度。
• 不要求所有开发者把源码 checkout 迁入 WSL；优先只隔离并移动 target。
• 不缓存或发布包含私有路径、凭据、用户数据的构建产物。

初始成功指标

• 连续两次无修改 cargo build -vv：第二次显示 Fresh rust-librocksdb-sys，且没有 RocksDB C/C++ compiler invocation。
• 修改普通 Kiwi .rs 文件后重建：不执行 RocksDB C/C++ 编译。
• WSL 和 Windows 使用不同 CARGO_TARGET_DIR 后，交替构建不再使对方的 native dependency fingerprint 失效。
• dev profile 构建日志中 rust-librocksdb-sys 收到 DEBUG=false；同时保留显式 C++ 调试 profile。
• 启用 sccache 后，第二次等价 native 构建可从 sccache --show-stats 看到 RocksDB translation units 的 cache hit。
• CI 每个 OS/target 输出 sccache 统计；cache hit、miss、compile time 和 restore time 可审计。
• 使用预编译路径时，Cargo 构建不编译 330 个 RocksDB 源文件，并通过自定义 FFI 符号和 Raft TablePropertiesCollector 测试。
• bundled build 与 prebuilt build 均通过格式、Lint、单元测试、Raft/Storage 定向测试和适用平台构建。

执行顺序

Phase 0：建立可复现基线和重编译诊断

Task 1：冻结构建基准与测量方法

涉及文件：

• 新建 scripts/build/benchmark-rocksdb-build.sh

• 新建 scripts/build/benchmark-rocksdb-build.ps1

• 新建 docs/development/build-performance.md

• 记录 Linux/WSL、Windows/MSVC、macOS 和 GitHub Actions runner 的 OS、CPU、内存、文件系统、Rust toolchain、C/C++ compiler、linker、Cargo profile 和 RocksDB fork SHA。

• 脚本覆盖 cold build、no-op build、普通 Rust 修改后的 warm build、独立 target 下的 sccache warm build。

• 每次测量记录 wall time、CPU time、峰值内存、target 总体积、librocksdb.a/.lib 体积、C/C++ invocation 数量和 sccache stats。

• 使用 cargo build --timings 与 cargo build -vv 保存 Cargo 侧证据。

• 将当前约 330 个 RocksDB C++ 源文件、约 334 个对象文件、约 943 MiB 静态库和约 6.27 GiB target 作为初始观察值；正式对比以脚本重测结果为准。

• 基准脚本不得执行 cargo clean 清理用户的默认 target；cold build 使用新的、显式的临时 CARGO_TARGET_DIR。

验收： 同一开发者或 CI runner 能按文档复现四类构建，并产出结构一致的结果表。

Task 2：定位无修改构建仍触发 RocksDB 重编译的 Dirty 原因

涉及文件：

• 修改 scripts/build/benchmark-rocksdb-build.sh

• 修改 scripts/build/benchmark-rocksdb-build.ps1

• 修改 docs/development/build-performance.md

• 从 cargo build -vv 中提取 Fresh/Dirty rust-librocksdb-sys、build-script invocation、ROCKSDB_*、CC/CXX、CXXFLAGS、RUSTFLAGS、profile、features、host 与 target。

• 分别验证：连续 no-op、Windows/WSL 交替构建、切换 dev/release、切换 toolchain、切换 --target、改变 native compiler 环境变量。

• 确认 [FEATURE] skip librocksdb-sys compilation process #205 所述现象属于哪一种 fingerprint 失效，而不是把一次 cold build 或超时误判为“每次都会重编”。

• 将每种可复现 Dirty 原因及对应修复写入构建文档。

验收： #205 的 Windows/WSL 场景有完整复现命令、Cargo Dirty 证据和对应处理路径。

Phase 1：低风险本地构建优化

Task 3：隔离 Windows、WSL/Linux 与 macOS 的 target 目录

涉及文件：

• 修改 docs/development/build-performance.md

• 按需要修改 README.md 或 CONTRIBUTING.md

• WSL 示例使用 $HOME/.cache/cargo-target/kiwi-linux，确保 native 输出位于 WSL ext4，而不是 /mnt/<drive>。

• Windows 示例使用独立目录，例如 D:\cargo-target\kiwi-msvc。

• macOS 示例使用独立目录，例如 $HOME/Library/Caches/cargo-target/kiwi-macos。

• 不把开发者用户名、盘符或绝对平台路径硬编码进仓库 .cargo/config.toml；通过用户级 Cargo config、shell environment、mise 或 direnv 配置。

• 验证 Windows 与 WSL 交替构建不会删除、覆盖或使另一平台的 rust-librocksdb-sys 失效。

• 记录源码仍在 Windows 文件系统、仅 target 移入 WSL ext4 时的收益；再单独记录源码和 target 全部位于 WSL ext4 的上限收益。

验收： 三个平台的 target 目录规则清晰、互斥、可复制，WSL 构建不再向 /mnt/d/.../target 写 native 对象。

Task 4：关闭依赖调试信息并保留显式调试 profile

涉及文件：

• 修改 Cargo.toml

• 修改 docs/development/build-performance.md

• 先采用最小改动验证 [profile.dev.package.rust-librocksdb-sys] debug = 0。

• 对比 Cargo 官方推荐方案：workspace member 使用 debug = "line-tables-only"，非 workspace dependency 使用 [profile.dev.package."*"] debug = false。

• 选择能保留 Kiwi panic/backtrace 文件行号、且不为 RocksDB 和其他依赖生成完整调试信息的配置。

• 新增显式 debugging profile，用于需要进入 Rust 依赖或 RocksDB C++ 单步调试的场景。

• 验证 rust-librocksdb-sys build output 中 DEBUG=false。

• 对比修改前后的 cold build 时间、librocksdb.a 体积、target 总体积和最终链接时间。

验收： 日常 dev build 不生成 RocksDB C++ 调试信息；cargo build --profile debugging 仍可获得完整调试能力。

Task 5：让 native 并行度按机器资源自适应

涉及文件：

• 修改 .cargo/config.toml

• 修改 docs/development/build-performance.md

• 删除固定 jobs = 8，默认让 Cargo 根据逻辑 CPU 数设置 NUM_JOBS。

• 在 16 GiB、32 GiB 或可用代表性机器上比较 jobs=8、默认 jobs 和受控 jobs 的 wall time 与峰值内存。

• 文档说明内存不足时如何用 CARGO_BUILD_JOBS 临时限流，而不是再次提交固定的全局机器值。

• 确认没有 OOM、系统持续换页或 CI runner 因过度并行变慢。

验收： 默认配置不人为限制高配机器；低内存机器有明确、可覆盖的限流方式。

Task 6：为本地 Rust、C 和 C++ 启用 sccache

涉及文件：

• 修改 docs/development/build-performance.md

• 按需要新增 scripts/build/setup-sccache.sh

• 按需要新增 scripts/build/setup-sccache.ps1

• 文档同时配置 RUSTC_WRAPPER=sccache、CC="sccache cc" 和 CXX="sccache c++"。

• macOS 使用 clang/clang++，Windows 验证 cl.exe wrapper 和 PDB/debug 参数。

• sccache cache directory 使用 native 文件系统，不放在 WSL /mnt/<drive>。

• 基准脚本在构建前后执行 sccache --zero-stats 和 sccache --show-stats。

• 验证首次 cold build、等价 warm build、删除 Cargo target 后的 sccache warm build三种场景。

• 文档说明 sccache 首次构建没有收益，以及 compiler、flags、headers 或 fork SHA 变化会导致 cache miss。

验收： RocksDB C++ 编译请求出现在 sccache stats 中，等价重编译产生稳定 cache hit；不能只验证 Rust cache hit。

Phase 2：CI native 编译缓存和任务复用

Task 7：让 GitHub Actions 的 sccache 覆盖 C/C++

涉及文件：

• 修改 .github/workflows/ci.yml

• 修改 .github/workflows/release.yml

• 修改 .github/workflows/codeql.yml

• 修改 .github/workflows/benchmark.yml

• Linux job 设置 CC="sccache cc"、CXX="sccache c++"。

• macOS job 设置 CC="sccache clang"、CXX="sccache clang++"。

• Windows job 验证 CC/CXX="sccache cl.exe" 或 cc-rs 支持的等价写法。

• 保留 RUSTC_WRAPPER=sccache 和 GHA backend 配置。

• 每个会编译 Rust/RocksDB 的 job 在 if: always() 步骤输出 sccache stats。

• cache namespace/key 区分 OS、architecture、compiler、toolchain、profile、fork SHA 和 relevant features。

• 验证 fork PR 或不可信分支不能写入受信任分支的共享 cache，避免 cache poisoning。

验收： Linux、macOS、Windows 至少各有一次成功 native cache hit；缓存不可用时构建可安全回退到真实编译。

Task 8：评估 dependency target cache，并统一 clippy/build/test 缓存策略

涉及文件：

• 修改 .github/workflows/ci.yml

• 修改 .github/workflows/clean-cache.yml

• 修改 docs/development/build-performance.md

• 在关闭 dependency debug info 后，评估 Swatinem/rust-cache 或等价方案对 rust-librocksdb-sys dependency artifacts 的缓存效果。

• 不直接长期缓存未经清理的完整 workspace target；缓存范围聚焦依赖产物。

• 统一 clippy 与 build/test 的 key 设计，避免当前 runner.os-clippy-* 与 runner.os-cargo-* 完全割裂且重复编译 native dependency。

• 比较“仅 sccache”“仅 dependency target cache”“二者同时使用”的 restore、compile、save 和总耗时。

• 只有 cache restore/save 的净收益为正时保留 target cache。

• 保持 PR 关闭后的 cache 清理策略，并避免删除 main 分支仍在使用的共享 cache。

验收： 选定策略有数据支持；CI 日志能说明每次构建是 sccache 命中、target artifact 命中还是实际重新编译。

Task 9：减少同一 commit 在多个 CI job 中的重复 RocksDB 构建

涉及文件：

• 修改 .github/workflows/ci.yml

• 按需要新增 reusable workflow 或 composite action 到 .github/actions/

• 统计同一 commit 在 clippy、build/test、Python integration、sanitizer、CodeQL 和 benchmark job 中触发 native build 的次数。

• 将 toolchain、protoc、sccache、native compiler wrapper 和 cache key 逻辑收敛为 reusable workflow/composite action。

• 对相同 OS、target、profile 和 feature set 复用 dependency artifact 或 sccache namespace。

• sanitizer、cross target 和 release profile 使用独立 namespace，不能错误复用 ABI/flags 不一致的 native 产物。

• 记录优化前后每个 workflow 的 RocksDB 实际编译次数和总 CI minutes。

验收： 相同构建配置不因 job 拆分而重复执行全部 330 个 RocksDB C++ 编译单元。

Phase 3：建立安全的预编译 RocksDB 路径

Task 10：定义 Kiwi native artifact contract

涉及文件：

• 新建 docs/development/rocksdb-native-artifact.md

• 按需要新增 scripts/build/verify-rocksdb-artifact.sh

• 按需要新增 scripts/build/verify-rocksdb-artifact.ps1

• artifact identity 包含 rust-rocksdb fork SHA、RocksDB submodule SHA、target triple、compiler/ABI、C++ standard、static/dynamic、profile、compression features 和 extension revision。

• 定义目录结构、headers、libraries、manifest、checksums、license/NOTICE 和构建命令记录。

• verifier 检查 RocksDB 版本、architecture、link mode 和三个自定义 TablePropertiesCollector FFI 符号。

• 定义动态开发库与静态 release 库的使用边界。

• 明确 ROCKSDB_STATIC 的 presence semantics，禁止用 ROCKSDB_STATIC=0 表示动态链接。

• 明确 prebuilt 不匹配时使用 ROCKSDB_COMPILE=1 回退 bundled build。

验收： 任意 artifact 在进入 Cargo 构建前都能被脚本判定为兼容或拒绝，不能依赖人工猜测 ABI。

Task 11：修改 rust-rocksdb fork，使外部 RocksDB 与 Kiwi extension 可独立链接

涉及仓库： arana-db/rust-rocksdb

涉及文件：

• 修改 librocksdb-sys/build.rs

• 修改 librocksdb-sys/rocksdb_ext/c_ext.cc

• 修改 librocksdb-sys/rocksdb_ext/c_ext.h

• 新增或修改 librocksdb-sys build/link tests

• 当未设置 ROCKSDB_LIB_DIR 时，保持现有 bundled RocksDB + c_ext.cc 构建行为。

• 当设置 ROCKSDB_LIB_DIR 时，跳过 330 个 RocksDB core sources，但仍单独编译并链接小型 rocksdb_ext companion library。

• ROCKSDB_INCLUDE_DIR 同时用于 bindgen 和 extension C++ compilation。

• external shared/static RocksDB 两种模式均覆盖。

• build test 验证三个自定义符号最终可链接。

• Rust integration test 实际注册 TablePropertiesCollectorFactory，并验证 collector 回调和 readable properties。

• 不复制更多 RocksDB 私有内部类型；对当前 rocksdb_options_t 布局依赖记录版本约束和安全依据。

• 发布新的 fork revision，并在 Kiwi 中单独提交依赖升级 PR。

验收： external RocksDB 路径不再要求把 c_ext.cc 预先塞进 librocksdb.a，且 Kiwi Raft TablePropertiesCollector 测试通过。

Task 12：实现 Linux x86_64 预编译 artifact 试点

涉及文件：

• 新建 .github/workflows/build-rocksdb-artifact.yml

• 新建 scripts/build/build-rocksdb-artifact.sh

• 修改 docs/development/rocksdb-native-artifact.md

• 从精确 fork/submodule SHA 构建 RocksDB，禁止跟随浮动 branch。

• 生成 release-mode native library，并包含当前压缩依赖与 manifest/checksum。

• 运行 symbol verifier 和最小 C/C++ link smoke test。

• 在独立 Cargo target 中使用 ROCKSDB_LIB_DIR / ROCKSDB_INCLUDE_DIR 构建 Kiwi。

• 运行 cargo test -p raft、cargo test -p storage、workspace build 和 lint。

• 测量 artifact 下载/解压/验证时间与 bundled cold compile 时间。

• 验证 artifact 缺失、checksum 错误或 ABI 不匹配时能够显式失败或回退 bundled build，不能静默链接错误版本。

验收： Linux x86_64 Cargo build 不编译 RocksDB core C++ sources，同时功能、测试和自定义 FFI 完整。

Task 13：扩展预编译 artifact 到 CI 支持平台

涉及文件：

• 修改 .github/workflows/build-rocksdb-artifact.yml

• 修改 .github/workflows/ci.yml

• 修改 .github/workflows/release.yml

• 新增或修改各平台 native build scripts

• 增加 Linux aarch64、macOS x86_64、macOS arm64 和 Windows x86_64 artifacts。

• 每个平台记录 compiler toolset 和 ABI，不能跨 compiler major version 复用。

• Windows 验证 .lib/.dll、runtime library 模式和符号导出；macOS 验证 deployment target 和 architecture。

• release 构建与 dev 构建分别验证静态/动态策略。

• CI 默认优先使用验证通过的 prebuilt artifact，并保留定期 bundled source build job，防止源码构建路径腐化。

• artifact retention、更新、回滚和 fork SHA 升级流程写入文档。

验收： 主 CI 矩阵平台均能稳定使用匹配 artifact；至少一个定期 job 继续验证 bundled build。

Phase 4：依赖图和 feature 收敛

Task 14：移除不必要的 RocksDB 依赖边

涉及文件：

• 修改 src/kstd/Cargo.toml

• 修改 src/conf/Cargo.toml

• 修改 src/conf/src/config.rs

• 修改 storage/engine 中承接 compression mapping 的文件

• 确认 kstd 未实际使用 RocksDB 后移除直接依赖。

• 将 CompressionType -> rocksdb::DBCompressionType 转换从 conf 移到 storage 或 engine 边界。

• 保持配置文件支持的字符串、默认 LZ4、验证错误和序列化格式不变。

• 验证 cargo test -p conf、cargo test -p kstd 不再构建 RocksDB。

• 不为完整 workspace build 宣称不存在的收益；该任务目标是改善局部 check/test 和 IDE feedback。

验收： 轻量 crate 的定向构建不再拉入 rust-librocksdb-sys，配置兼容性不变。

Task 15：评估压缩 feature 裁剪，但不破坏现有配置

涉及文件：

• 修改 Cargo.toml（仅当评估结论支持）

• 修改配置、文档和测试（仅当正式收窄能力）

• 修改 docs/development/build-performance.md

• 分别测量完整默认 codecs 与仅 LZ4 所减少的编译时间和产物体积。

• 验证禁用 snappy/zstd/zlib/bzip2 后，相关配置在打开 DB 时的实际行为。

• 若收益不足以覆盖兼容性成本，保留全部默认 codecs，并在 Issue 中记录否决依据。

• 若决定收窄能力，使用独立 breaking-change proposal，提供配置迁移、错误提示和兼容测试；本 Epic 不直接静默删除 codec。

验收： feature 决策由测量和兼容性证据支持，不把小幅附属库收益误当成解决核心 330 个 C++ 文件编译的主方案。

Phase 5：文档、回归门禁和结果对账

Task 16：固化开发者与 CI 构建文档

涉及文件：

• 修改 README.md

• 修改 CONTRIBUTING.md

• 完成 docs/development/build-performance.md

• 完成 docs/development/rocksdb-native-artifact.md

• 给出 WSL、Windows、macOS 的 target 隔离和 sccache 配置。

• 给出普通 dev、C++ debugging、bundled build、prebuilt build 和强制 fallback 命令。

• 解释 ROCKSDB_LIB_DIR、ROCKSDB_INCLUDE_DIR、ROCKSDB_STATIC、ROCKSDB_COMPILE、SNAPPY_LIB_DIR 的精确语义。

• 增加“为什么 RocksDB 又重编了”的诊断表。

• 文档中的命令由 CI smoke test 或构建脚本实际执行，避免示例腐化。

验收： 新开发者无需阅读 build.rs 即可配置快速构建、识别 cache miss 并安全回退源码构建。

Task 17：最终跨平台验证与收益报告

涉及文件：

• 更新 docs/development/build-performance.md

• 在本 Epic 发布最终结果评论

• 执行 cargo fmt --check。

• 执行 cargo clippy --all-features --workspace -- -D warnings -D clippy::unwrap_used。

• 执行 cargo test -p conf、cargo test -p kstd、cargo test -p storage、cargo test -p raft。

• 在适用环境执行 cargo test --workspace 和 Python integration tests。

• Linux、macOS、Windows 分别验证 bundled 和 prebuilt build。

• 对比初始基线与最终 cold/no-op/warm/sccache/prebuilt 构建结果。

• 报告 target 体积、native compile invocation、CI minutes、cache hit rate 和 artifact restore time。

• 确认 TablePropertiesCollector、Raft LogIndex properties、压缩配置和 RocksDB 数据兼容性没有回归。

验收： 所有任务关闭，结果数据可复现，快速路径与 bundled fallback 均保持在 CI 门禁中。

依赖关系

Task 1 -> Task 2
             |
             +-> Task 3 -> Task 4 -> Task 5 -> Task 6
                                      |
                                      +-> Task 7 -> Task 8 -> Task 9

Task 1 -> Task 10 -> Task 11 -> Task 12 -> Task 13

Task 2 -> Task 14
Task 1 -> Task 15

Tasks 3-15 -> Task 16 -> Task 17

关键顺序：先测量和定位 fingerprint 失效，再做低风险本地优化；CI 缓存建立在可观察的 sccache/native 指标之上；预编译方案必须先定义 artifact contract，再修改 fork extension 链接路径，最后扩展平台。

跨任务质量门禁

• 每个 Task 使用独立 PR 或明确单一目的的 PR 组，禁止把 profile、CI、fork ABI 和 feature breaking change 混成一个不可回滚 PR。
• 所有性能结论必须记录环境、命令、cold/warm 条件、重复次数和原始输出。
• 工具缺失、cache backend 故障、网络失败和 runner 变化必须标记为环境问题，不伪装成代码收益或回归。
• 预编译 artifact 必须校验 SHA、checksum、architecture、ABI、features 和自定义 FFI symbols。
• main/release 的受信任 cache 与 fork PR 的写权限必须隔离。
• bundled source build 不能删除；至少保留定期 CI 验证和显式 fallback。
• 不通过 cargo clean、删除断言、跳过测试或缩减现有压缩能力来制造虚假的构建优化结果。

关联 Issue

• [FEATURE] skip librocksdb-sys compilation process #205：原始问题，描述 cargo build / cargo run 频繁重新编译 librocksdb-sys。本 Epic 的 Task 1-6 负责复现、定位和本地处理。
• [FEATURE] Replace the rocksdb dependency library #213：更换 RocksDB dependency wrapper。与 fork 长期维护有关，但是否迁移 wrapper 不阻塞本 Epic 的 profile、cache 和 prebuilt 工作。
• epic(storage): 收敛 RocksDB 架构并精简存储执行链路 #347：RocksDB storage/runtime 架构收敛 Epic。本 Epic 仅处理构建链和 native 产物，不改变其存储架构决策。

完成定义

• Task 1-17 均有可验证结果并关闭。
• [FEATURE] skip librocksdb-sys compilation process #205 的具体重编译原因已被复现和消除，或明确记录为特定环境/命令导致。
• 本地开发默认使用平台隔离的 native target，WSL 不在 /mnt/<drive> 写大规模 native 产物。
• 日常 dev profile 不生成依赖 C/C++ 调试信息，显式 debugging profile 可用。
• 本地和 CI sccache 均覆盖 RocksDB C++，统计可见且 cache miss 可解释。
• CI 不再在等价配置下跨多个 job 重复完整编译 RocksDB。
• Linux、macOS、Windows 的 prebuilt 路径或经数据证明更合适的缓存路径稳定可用。
• external RocksDB 与 Kiwi rocksdb_ext 的链接方式有明确、经过测试的实现。
• bundled source build、prebuilt build、TablePropertiesCollector、压缩配置和 Raft/Storage 测试均通过。

参考资料

• Cargo：减少依赖调试信息：https://doc.rust-lang.org/cargo/guide/build-performance.html#reduce-amount-of-generated-debug-information
• Cargo build cache 与 target layout：https://doc.rust-lang.org/cargo/reference/build-cache.html
• Microsoft WSL 文件系统性能建议：https://learn.microsoft.com/en-us/windows/wsl/filesystems#file-storage-and-performance-across-file-systems
• cc-rs compiler wrapper 与 parallel compilation：https://github.com/rust-lang/cc-rs
• sccache：https://github.com/mozilla/sccache
• RocksDB 官方构建说明：https://github.com/facebook/rocksdb/blob/main/INSTALL.md
• rust-cache dependency artifact 策略：https://github.com/Swatinem/rust-cache
• Estuary Flow 的固定版本预编译 RocksDB 配置：https://github.com/estuary/flow/blob/2eb058e50f26c618cfdd22edeea85fdf4587e3aa/mise.toml
• KumoMTA 的 ROCKSDB_LIB_DIR 构建路径：https://github.com/KumoCorp/kumomta/blob/0acaa1b6a5ef8f67e5942c196f32874c1d99347a/.github/workflows/reusable-kumomta-build.yml
• Convex 的系统 RocksDB 版本检查与 bundled fallback：https://github.com/get-convex/convex-backend/blob/63c1c3b9b275f3952aa4be9c4d6f7ca9957bfe43/mise.toml