[Paper/M1][P0] Implement transactional lower-generation switching with crash recovery

[Ivanbeethoven]

Parent research epic: #39

背景

当前 refresh-plan 只做前置检查，不会切换真实 lower。系统论文需要给出明确的版本切换语义，并证明在失败或 crash 下不会出现控制面与实际文件树不一致。

目标

新增实际 mutation API：

POST /mounts/{mount_id}/worktree/refresh

建议请求：

{
  "expected_generation": 7,
  "expected_snapshot": "...",
  "target_revision": "...",
  "require_clean": true
}

State Machine

Ready
  -> Quiescing
  -> Refreshing
  -> Ready(new generation)

Refreshing
  -> Ready(old generation)     // rollback
  -> FailedRecoverable
  -> Conflict                  // VCS owner must resolve

Switch Protocol

1. 解析并准备 target SnapshotId；
2. pin target snapshot/CAS objects；
3. 验证 expected generation 和 upper cleanliness；
4. 阻止新的控制面 mutation；
5. quiesce workspace；
6. 写 prepare WAL/state；
7. 原子切换 active lower generation；
8. 失效相关 kernel entry/inode cache，或使用安全 remount fallback；
9. 持久化 committed generation；
10. 恢复 workload；
11. 异步回收旧 generation。

Open-Handle Semantics

必须明确：

• refresh 前已打开的 handle 继续绑定旧 generation，直到 close；
• refresh commit 后的新 lookup/open 只能看到新 generation；
• refresh 不修改 private upper；
• 如果实现无法提供 generation-pinned handle，必须在 quiesce 阶段拒绝存在打开 handle 的切换，并在 API 中明确返回原因。

不得留下未定义行为。

Tasks

• 实现 Refreshing/FailedRecoverable/Conflict 生命周期；
• 增加 generation counter；
• 实现 refresh API 和 capability refresh.v1；
• 增加 WAL 或等价的 crash-recovery record；
• active generation 切换必须原子发布；
• 实现 kernel cache invalidation 或安全 remount；
• 保留旧 generation，直到所有旧 handle 释放；
• 上层 dirty 时默认拒绝；
• 支持同 snapshot idempotent refresh；
• expected generation mismatch 返回明确冲突；
• 在每个 protocol phase 加 fault injection point；
• daemon restart 时恢复 prepared/committed/rolled-back 状态；
• 增加并发 lookup/open/read 测试；
• 更新 worktree state transition 文档。

Acceptance Criteria

• quiesce 完成后，恢复的客户端只看到 target snapshot；
• 旧 open handle 的行为符合文档；
• upper 中的所有本地修改在成功、失败和 crash 后都不会丢失；
• 任一 fault injection point crash 后只能恢复旧或新 generation，不出现第三种半完成状态；
• control-plane snapshot 与实际 active lower identity 始终一致；
• refresh 对相同请求幂等；
• failed refresh 可重试；
• state file/WAL corruption 能被检测并 fail closed。

Paper Measurements

• refresh latency；
• quiesce duration；
• open-handle retention cost；
• invalidation/remount cost；
• crash recovery time；
• fault matrix。

Relevant Files

src/daemon/antares.rs
src/antares/fuse.rs
src/dicfuse/
docs/worktree-state-transitions.md
docs/worktree-api.md

Dependencies

Issue 3、Issue 4。

---