[Paper/M2][P1] Add budgeted build- and agent-aware prefetch planning

[Ivanbeethoven]

Parent research epic: #39

背景

当前静态 scan/full/dirs/hotset 模式适合作为 baseline，但它们没有统一预算，也没有根据构建目标、Agent 阶段、历史 trace 和共享热集动态选择对象。

目标

提供可插拔 planner：

trait PrefetchPlanner {
    fn plan(
        &self,
        context: &WorkspaceContext,
        hints: &[PrefetchHint],
        budget: PrefetchBudget,
    ) -> Vec<PrefetchCandidate>;
}

预算至少包含：

max_bytes
max_objects
max_duration
max_in_flight
deadline

Hint Sources

按实现优先级：

1. 显式 path/target hint；
2. Buck2/Bazel/Cargo/CMake 构建依赖提示；
3. 当前命令和最近访问目录；
4. 历史 trace hotset；
5. 多 workspace 共享热对象；
6. 可选 learned model。

先做可解释 heuristic，不以 ML 模型作为前置条件。

Candidate Score

可以采用：

score =
  P(access) × estimated_saved_latency
  - λ × object_bytes
  - μ × queue_contention
  - ν × cache_pollution

Tasks

• 定义 planner/plugin API；
• 统一现有 scan/full/dirs/hotset 为 baseline planner；
• 实现 explicit-path planner；
• 实现 build-target planner；
• 实现 trace-hotset planner；
• 所有 planner 必须受 budget 约束；
• prefetch 使用 Issue 7 最低优先级队列；
• workspace 取消/refresh 后停止无用 prefetch；
• CAS 已命中对象不得重复计入网络预算；
• 记录 candidate、admitted、hit、unused、late 和 evicted-before-use；
• 支持 deterministic offline simulation；
• 增加 planner ablation；
• 记录对 demand latency 和其他 workspace 的干扰。

Acceptance Criteria

• planner 不影响 correctness；
• 严格遵守 bytes/object/time/in-flight budget；
• demand read 可以抢占或越过后台 prefetch；
• 可输出 precision、recall、coverage、wasted bytes 和 saved stall time；
• 相同 trace 和 seed 产生相同离线 plan；
• 一个 workspace 的 prefetch 不会使其他 workspace starvation；
• 所有现有静态模式都能通过统一接口运行。

Paper Retention Gate

至少在两个真实 workload 上满足：

• P95 mount-to-first-successful-action 降低 ≥20%，且
• 无效预取字节不超过实际 demand bytes 的 30%，且
• 并发邻居 workload 的 P95 延迟退化 <5%。

未达到时放入 appendix/negative result，不作为主论文贡献。

Dependencies

Issue 1、Issue 2、Issue 7。建议在真实 trace 到位后再投入。

---