Vec 运行与验证

Vec 的持久化以文档快照和 WAL 为准。派生索引不是提交点，也不能决定文档是否已保存。

持久化与恢复

每次变更先写入带修订身份的 WAL，再按耐久性策略确认。manifest 是提交点，记录活动 WAL 的已提交边界。

恢复时，Vec 读取 manifest 指定的快照，并重放该快照之后的 WAL。边界后的部分帧不属于已提交数据，边界内的损坏会返回错误。

派生缓存失效不等于集合打开失败。Vec 从权威文档重建索引，查询仍保持精确语义。

资源上限

这些值由调用方通过 CollectionOptions 或 ConfigBuilder 设置。Vec 不根据主机内存或剩余磁盘自动推断上限。

manifest 读取上限为 1 MiB，单个 WAL 帧上限为 64 MiB。它们属于协议保护，不是 StorageCeilings 的产品配额。

维护与健康

start_maintenance 启动显式拥有的维护器。维护器可以按间隔检查并触发检查点，也可以在测试中手动触发。

健康信息区分权威修订、派生索引退化和 WAL 检查点滞后。checkpoint_pending 表示仍有待处理的检查点，不代表文档已经损坏。

只读句柄不会更新派生文件。维护器关闭后，maintenance_active 应为 false。

I/O 与平台

默认派生文件后端使用 positioned reads。可选 mmap 后端在完整校验后创建只读匿名副本，不直接映射可变外部文件。

性能证据

公开基准只覆盖指定语料、维度、索引参数、主机和查询形状。Flat 的 recall 为 1.0 是精确扫描的结果，不代表 ANN 的召回目标。

比较 ANN 时必须同时记录召回、构建时间、查询延迟和精确重排设置。不能通过降低 ef、删除精确重排或把公开分数改成 f32 来制造性能结论。

基准结果不是容量 SLO，也不是所有引擎的统一排名。

验收清单

1. 运行 cargo fmt --all -- --check。
2. 运行 cargo test --locked。
3. 运行 cargo test --locked --all-features。
4. 运行 cargo clippy --locked --all-targets -- -D warnings。
5. 运行 cargo +1.75.0 test --locked，检查默认功能的 MSRV。
6. 在 WAL 写入、检查点和恢复边界执行故障测试。
7. 删除或破坏派生缓存，确认权威文档仍可恢复查询。
8. 比较 ANN 与 Flat 的召回和延迟，记录完整实验参数。

实现依据

• 持久化与恢复合同
• 资源上限
• 维护与健康示例
• 基准方法与限制