diff --git a/docs/source/io_pattern_design.md b/docs/source/io_pattern_design.md
new file mode 100644
index 0000000000..a1bb5fbea6
--- /dev/null
+++ b/docs/source/io_pattern_design.md
@@ -0,0 +1,1284 @@
+---
+orphan: true
+---
+## 5.4.1 设计概述
+
+```
+flowchart TD
+    subgraph 推理框架层 ["推理框架层 (vLLM/SGLang)"]
+        MC["MooncakeConnector<br/>(vLLM v1)"]
+        HC["HiCache Connector<br/>(SGLang)"]
+        PC["Prefix Cache Manager"]
+    end
+
+    subgraph CFM ["CFM (Cache Flow Manager)"]
+        COL["Collector<br/>(数据采集)"]
+        ANA["Analyzer<br/>(模式分析)"]
+        ENG["Policy Engine<br/>(策略决策)"]
+        COL --> ANA --> ENG
+        EV["Eviction Ops"]
+        PF["Prefetch Ops"]
+        AD["Admission Ops"]
+        ENG --> EV & PF & AD
+    end
+
+    MC -->|"CFM Client<br/>(采集/策略/预取)"| COL
+    HC -->|"CFM Client"| COL
+    PC -->|"CFM Client"| COL
+
+    subgraph CVM ["CVM (Cache View Manager)"]
+        VIEW["视图计算 / 发布 / 系统事件感知 / 全局 KV 映射表"]
+    end
+
+    EV --> VIEW
+    PF --> VIEW
+    AD --> VIEW
+
+    subgraph 存储层 ["存储层"]
+        L0["L0: HBM<br/>(UB2PCIe/d2h)"]
+        L1["L1: Host DRAM/SSD<br/>(计算节点本地内存/SSD(xds)"]
+        L2["L2: Segment DRAM<br/>(池化内存 URMA mem)"]
+        L3["L3: Nof SSD<br/>(SSU/远端池化 SSD)"]
+    end
+
+    VIEW --> L0
+    VIEW --> L2
+    VIEW --> L3
+    L0 <-.->|"tier down/up"| L1
+    L1 <-.->|"tier down/up"| L2
+    L2 <-.->|"offload/promotion"| L3
+```
+
+**模块总体架构图**
+
+```
+classDiagram
+    class IoPatternCollector {
+        <<interface>>
+        +ReportInferenceMetrics(metrics) void
+        +RecordAccess(key, record) void
+        +RecordStorageMetric(metric) void
+        +GetSnapshot() IoPatternSnapshot
+    }
+
+    class IoPatternAnalyzer {
+        <<interface>>
+        +AnalyzePattern(snapshot) PatternResult
+        +DetectWorkloadType(window) WorkloadType
+        +CalculateConfidence(key) float
+    }
+
+    class PolicyEngine {
+        <<interface>>
+        +ExecutePolicy(context, tier, bytes, trace, admissions) PolicyResult
+    }
+
+    class EvictionOps {
+        <<interface>>
+        +Evaluate(context, tier, bytes) EvictionPlan
+    }
+
+    class PrefetchOps {
+        <<interface>>
+        +Evaluate(context, trace) PrefetchPlan
+    }
+
+    class AdmissionOps {
+        <<interface>>
+        +Evaluate(object, tier, context) AdmissionResult
+    }
+
+    class CfmClient {
+        +ReportInferenceMetrics(metrics) void
+        +ReceivePolicy指令() void
+        +ExecutePrefetch(candidates) void
+    }
+
+    class ScoreBasedEviction {
+        +Evaluate(context, tier, bytes) EvictionPlan
+    }
+
+    class TraceBasedPrefetch {
+        +Evaluate(context, trace) PrefetchPlan
+    }
+
+    class PrefixMatchAdmission {
+        +Evaluate(object, tier, context) AdmissionResult
+    }
+
+    PolicyEngine *-- EvictionOps : contains
+    PolicyEngine *-- PrefetchOps : contains
+    PolicyEngine *-- AdmissionOps : contains
+    IoPatternCollector --> IoPatternAnalyzer : reports
+    IoPatternAnalyzer --> PolicyEngine : analyzes
+    CfmClient --> IoPatternCollector : reports metrics
+    CfmClient --> PolicyEngine : receives policy
+    EvictionOps <|.. ScoreBasedEviction : implements
+    PrefetchOps <|.. TraceBasedPrefetch : implements
+    AdmissionOps <|.. PrefixMatchAdmission : implements
+```
+
+## 5.4.2 IO Pattern 三层架构
+
+IO Pattern 模块采用**采集层 -> 分析层 -> 策略层**的三层架构。
+
+### 5.4.2.1 采集层 (IO Pattern Collector)
+
+采集层负责从各数据源采集原始 IO 指标，采用异步上报机制避免阻塞数据路径。
+
+**采集来源分三层：**
+
+| 采集层            | 数据源                                            | 采集指标                                                                                                                 | 现有代码锚点                                                            |
+| ----------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
+| 推理框架层        | vLLM MooncakeConnector / SGLang HiCache Connector | prefix match length, request priority, token 序列, recompute cost                                                        | `mooncake_connector_v1.py`, SGLang hicache connector                    |
+| SuperCache SDK 层 | Client / Master / SubMaster                       | Get/Put/Tier 命中率, 访问时序, key 频率, 前缀树深度/fanout, 副本分布, 迁移 ETA, 写路径指标 (batch_size, overwrite_ratio) | `client_service.cpp`, `master_service.cpp`, `local_hot_cache.cpp`       |
+| 存储后端层        | SSD/Nof Segment                                   | 读写带宽, 读写延迟, GC 状态, 盘内 Superblock 布局, 容量水位                                                              | `client_metric.h:SsdMetric`, `allocation_strategy.h:SsdMetricsProvider` |
+
+**采集机制设计：**
+
+1. **轻量级埋点**：复用和扩展现有 `CountMinSketch`（频率统计）、`SsdMetric`（SSD 延迟/吞吐）、`storage_backend.h:last_access_ns_`（最后访问时间）等埋点，避免重复建设
+2. **异步上报**：CFM Client 定期异步上报指标至 SubMaster，采用 batch 聚合减少 RPC 开销。上报间隔自适应负载（低负载 100ms，高负载退避至 500ms-1s）
+3. **全局聚合**：SubMaster 聚合各节点上报的指标，维护全局 token 指标流动视图
+4. **采样降级**：在高负载场景下支持采样率动态调整，优先保障数据路径性能
+5. **多租户隔离**：指标按 `TenantId` 分桶采集，避免高频租户淹没低频租户，沿用现有 `CountMinSketch` 的 `tenant_id.MakeScopedKey` 模式
+
+固定 100ms 上报间隔在大规模集群下可能产生可观开销。采用自适应间隔：
+
+| 负载状态 | 上报间隔 | 触发条件                                  |
+| -------- | -------- | ----------------------------------------- |
+| 低负载   | 100ms    | mem_used_ratio < 50%                      |
+| 中负载   | 200ms    | 50% <= mem_used_ratio < 80%               |
+| 高负载   | 500ms    | mem_used_ratio >= 80%                     |
+| 极高负载 | 1000ms   | mem_used_ratio >= 95% 或 RPC 延迟 > 100ms |
+
+> 
+> 高负载时拉长间隔减少 RPC 开销，但保持最低 1s 上报频率确保策略时效性。量化估算：4000 节点集群，100ms 间隔下每秒 40000 RPC，单 RPC ~2KB，总带宽 ~80MB/s
+
+#### 5.4.2.1.1 指标采集与上报流程
+
+```
+sequenceDiagram
+    participant INF as 推理框架 (vLLM/SGLang)
+    participant CFM as CFM Client
+    participant SUB as SubMaster
+
+    INF->>CFM: 1. 请求完成/前缀匹配
+    CFM->>SUB: 2. 批量上报指标 (InferenceMetrics)
+    CFM->>SUB: 3. SDK 层埋点 (AccessRecord)
+    CFM->>SUB: 4. 存储后端指标 (StorageMetric)
+    Note over SUB: 5. 全局聚合<br/>IoPatternSnapshot
+```
+
+#### 5.4.2.1.2 指标分类
+
+IO Pattern 采集指标分为六大类，对应分级缓存淘汰/准入/预取流程的采集指标定义：
+
+**时序指标**
+
+| 指标名                | 类型      | 描述                     | 采集来源   | 现有代码锚点                        |
+| --------------------- | --------- | ------------------------ | ---------- | ----------------------------------- |
+| `last_access_time`    | timestamp | 最近一次访问时间         | SDK 层     | `storage_backend.h:last_access_ns_` |
+| `access_count_window` | uint32    | 最近时间窗口内访问次数   | SDK 层     | `count_min_sketch.h:CountMinSketch` |
+| `idle_time`           | duration  | = now - last_access_time | 分析层计算 | -                                   |
+
+**价值指标**
+
+| 指标名           | 类型   | 描述                           | 采集来源   | 现有代码锚点     |
+| ---------------- | ------ | ------------------------------ | ---------- | ---------------- |
+| `recompute_cost` | float  | 重新计算时间 (token 数 / 时间) | 推理框架层 | connector 层估算 |
+| `block_size`     | uint64 | 数据大小 (bytes)               | SDK 层     | object metadata  |
+| `token_count`    | uint32 | token 数                       | 推理框架层 | connector 层     |
+
+**结构指标**
+
+| 指标名                     | 类型   | 描述                         | 采集来源   | 现有代码锚点         |
+| -------------------------- | ------ | ---------------------------- | ---------- | -------------------- |
+| `prefix_depth`             | uint32 | 前缀深度 (prefix tree level) | 推理框架层 | prefix cache manager |
+| `prefix_fanout`            | uint32 | 共享该前缀的请求/分支数量    | 推理框架层 | prefix cache manager |
+| `match_length`             | uint32 | 前缀匹配长度                 | 推理框架层 | connector 层         |
+| `continuous_prefix_length` | uint32 | 连续前缀长度                 | 推理框架层 | connector 层         |
+
+**副本指标**
+
+| 指标名                | 类型     | 描述                       | 采集来源   | 现有代码锚点               |
+| --------------------- | -------- | -------------------------- | ---------- | -------------------------- |
+| `replica_tiers`       | bitmap   | 当前在哪些层有副本 (L0-L3) | SDK 层     | `master_service.h:Replica` |
+| `transfer_eta`        | duration | 迁移路径预计耗时           | 分析层计算 | -                          |
+| `ssd_replica_exists`  | bool     | SSD 层是否有副本           | SDK 层     | replica metadata           |
+| `other_replica_count` | uint32   | 其他层副本数               | SDK 层     | replica metadata           |
+
+**状态指标**
+
+| 指标名   | 类型 | 描述         | 采集来源 | 现有代码锚点                  |
+| -------- | ---- | ------------ | -------- | ----------------------------- |
+| `active` | bool | 是否正在使用 | SDK 层   | `local_hot_cache.h:ref_count` |
+| `pinned` | bool | 是否不可迁移 | SDK 层   | promotion task pinning        |
+
+**存储后端指标**
+
+| 指标名              | 类型      | 描述              | 采集来源   | 现有代码锚点                                                                 |
+| ------------------- | --------- | ----------------- | ---------- | ---------------------------------------------------------------------------- |
+| `ssd_read_latency`  | histogram | SSD 读延迟分布    | 存储后端层 | `client_metric.h:SsdMetric`                                                  |
+| `ssd_write_latency` | histogram | SSD 写延迟分布    | 存储后端层 | `client_metric.h:SsdMetric`                                                  |
+| `ssd_gc_status`     | enum      | SSD GC 状态       | 存储后端层 | Nof TGT                                                                      |
+| `mem_used_ratio`    | float     | DRAM 内存水位比例 | SDK 层     | `MasterMetricManager::get_global_mem_used_ratio()` (Master 侧全局 DRAM 水位) |
+| `ssd_used_bytes`    | int64     | SSD 已用容量      | 存储后端层 | `allocation_strategy.h:SsdMetricsProvider`                                   |
+
+#### 5.4.2.1.3 指标采集接口
+
+```
+// IO Pattern Collector 接口 (新增, 位于 include/io_pattern_collector.h)
+class IoPatternCollector {
+   public:
+    virtual ~IoPatternCollector() = default;
+
+    // 推理框架层指标 (通过 CFM Client 上报)
+    virtual void ReportInferenceMetrics(const InferenceMetrics& metrics) = 0;
+
+    // SDK 层指标 (内部埋点)
+    virtual void RecordAccess(const std::string& key,
+                              const AccessRecord& record) = 0;
+
+    // 存储后端层指标
+    virtual void RecordStorageMetric(const StorageMetric& metric) = 0;
+
+    // 获取聚合后的指标快照
+    virtual IoPatternSnapshot GetSnapshot() const = 0;
+};
+
+struct AccessRecord {
+    std::string key;
+    std::chrono::steady_clock::time_point access_time;
+    uint64_t block_size;
+    ReplicaType replica_type;
+    bool is_hit;
+    std::chrono::microseconds latency;
+};
+
+struct InferenceMetrics {
+    std::string session_id;
+    uint32_t prefix_depth;
+    uint32_t prefix_fanout;
+    uint32_t match_length;
+    uint32_t continuous_prefix_length;
+    uint32_t token_count;
+    float recompute_cost;
+    uint8_t request_priority;
+};
+```
+
+### 5.4.2.2 分析层 (IO Pattern Analyzer)
+
+分析层对采集的原始指标进行模式识别和特征提取，输出结构化的 IO Pattern 描述。
+
+**分析能力：**
+
+| 分析类型      | 描述                           | 输入指标                                               | 输出                                 | 对应需求       |
+| ------------- | ------------------------------ | ------------------------------------------------------ | ------------------------------------ | -------------- |
+| 热度分析      | 基于 LFU/滑动窗口的频率统计    | access_count_window, last_access_time                  | hot/cold 分类, 频率评分              | 淘汰/准入/预取 |
+| 前缀分析      | Prefix tree 深度和 fanout 分析 | prefix_depth, prefix_fanout, match_length              | 前缀共享度, 预取候选                 | 预取/准入      |
+| 时序预测      | 访问间隔和空闲时间分析         | idle_time, access pattern, access_count_window         | 空闲评分, 预取优先级                 | 淘汰/Tier down |
+| 代价评估      | 重计算代价和迁移代价评估       | recompute_cost, token 数, block_size, transfer_eta     | 代价评分, 迁移 ROI                   | 淘汰/Tier up   |
+| 访问模式识别  | 顺序/随机、大包/小包、读写比   | IO size distribution, access sequence                  | 模式分类 (SEQ/RANDOM/KV_LOOKUP等)    | 缓存分区/分流  |
+| 副本分析      | 多层副本分布分析               | replica_tiers, active/pinned                           | 副本冗余度, 迁移安全性               | 淘汰/Tier down |
+| 写路径分析    | 写入模式分析                   | write_batch_size, write_burst, overwrite_ratio         | 写穿风险, GC 预警                    | 准入/GC        |
+| Workload 识别 | 推理场景类型自动识别           | token_count, prefix_fanout, block_size, frequency 分布 | workload_type (Code Agent/推荐/对话) | 策略模板选择   |
+
+**Workload Type 感知策略模板**
+
+不同推理场景的 IO Pattern 差异巨大，单一通用评分公式无法覆盖所有场景。
+
+**配置参数：**
+
+| 参数                                   | 默认值        | 说明                                                               |
+| -------------------------------------- | ------------- | ------------------------------------------------------------------ |
+| `workload_detection_window_sec`        | 60            | workload 识别滑动窗口大小                                          |
+| `workload_detection_method`            | `auto`        | 识别方法：`auto`(阈值+聚类)、`threshold`(仅阈值)、`kmeans`(仅聚类) |
+| `workload_template_transition_windows` | 3             | 模板切换过渡窗口数，控制平滑度                                     |
+| `workload_mixed_load_mode`             | `per_session` | 混合负载处理：`per_session`(按会话标记)、`global`(全局统一)        |
+
+**运维观测：**
+
+| 指标                                    | 描述                     |
+| --------------------------------------- | ------------------------ |
+| `workload_current_type`                 | 当前识别的 workload type |
+| `workload_type_switch_count`            | workload type 切换次数   |
+| `workload_detection_latency_us`         | 单次识别延迟             |
+| `workload_template_transition_progress` | 模板过渡进度 (0.0-1.0)   |
+
+**Workload 识别机制：**
+
+不同推理场景的 KVCache 访问模式差异巨大，单一通用评分公式无法覆盖所有场景。IO Pattern 分析层基于滑动窗口内的指标分布统计，自动识别 workload type 并切换对应策略模板。
+
+**Workload Type 特征矩阵：**
+
+| Workload Type | 典型场景                       | 访问特征                                                                  | 识别信号                                                                |
+| ------------- | ------------------------------ | ------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| Code Agent    | Cursor/Copilot 长程代码生成    | 长上下文（>32K token）、高前缀复用、大 block_size（>512KB）、多轮访问为主 | 高 token_count + 低 prefix_fanout + 大 block_size + 低 frequency        |
+| 生成式推荐    | 京东/字节 GR 精排召回          | 高频小 block（<128KB）、高复用、密集访问、低重计算代价                    | 低 token_count + 高 frequency + 小 block_size + 低 recompute_cost       |
+| 多轮对话      | ChatGPT 类对话、Agent 工具调用 | 中等 block、高前缀共享、渐进式增长、prefix cache 命中率高                 | 中 token_count + 高 prefix_fanout + 高 match_length + 高 recompute_cost |
+
+**识别算法：**
+
+分析层维护一个滑动窗口（默认 60s），统计窗口内所有请求的 `token_count`/`prefix_fanout`/`block_size`/`frequency` 四维分布。采用两阶段识别：
+
+```
+阶段 1: 特征提取
+  for each request in window:
+    feature_vector = (median(token_count), p90(prefix_fanout), 
+                      median(block_size), median(frequency))
+
+阶段 2: 分类决策
+  if feature_vector matches阈值规则:
+    -> 直接分类 (快速路径, 延迟 < 1ms)
+  else:
+    -> K-means 聚类 (慢速路径, 延迟 < 10ms, 用于混合负载场景)
+```
+
+**阈值规则（快速路径）：**
+
+| 判定条件                                                                           | → Workload Type         |
+| ---------------------------------------------------------------------------------- | ----------------------- |
+| `median(token_count) > 16KB && p90(prefix_fanout) > 16 && p90(match_length) > 256` | Code Agent              |
+| `median(block_size) < 128KB && median(frequency) > 20`                             | 生成式推荐              |
+| `p90(prefix_fanout) > 16 && p90(match_length) > 256`                               | 多轮对话                |
+| 不满足以上任一                                                                     | 混合负载 → K-means 聚类 |
+
+**策略模板对照：**
+
+每种 workload type 对应一组完整的策略参数模板，覆盖淘汰/准入/预取/Tier 四个维度：
+
+| 策略维度      | Code Agent                                | 生成式推荐                              | 多轮对话                               |
+| ------------- | ----------------------------------------- | --------------------------------------- | -------------------------------------- |
+| **预取**      | 保守（仅 prefix > 512 预取，best_effort） | 激进（prefix > 64 预取，wait_complete） | 前缀优先（prefix > 256 预取，timeout） |
+| **淘汰**      | 激进（低 idle_thres，快速释放 L0）        | 保守（高 idle_thres，保留热数据）       | 前缀感知（prefix_fanout 高权重保留）   |
+| **准入**      | 低阈值（access_count > 2 即准入）         | 高阈值（access_count > 20 才准入）      | 前缀准入（match_length > 128 即准入）  |
+| **Tier down** | 快速降级（L0→L2 跳级，跳过 L1）           | 缓慢降级（L0→L1→L2 逐层）               | 前缀亲和（共享前缀的 block 同层迁移）  |
+| **淘汰权重**  | α=0.8, γ=0.2, δ=0.3, ε=0.1                | α=0.3, γ=0.8, δ=0.2, ε=0.1              | α=0.5, γ=0.4, δ=0.6, ε=0.8             |
+
+**模板切换机制：**
+
+```
+flowchart TD
+    WIN["滑动窗口指标统计<br/>(60s)"]
+    FEAT["特征提取<br/>4 维分布向量"]
+    RULE["阈值规则匹配"]
+    KMEANS["K-means 聚类<br/>(混合负载)"]
+    CLASSIFY["Workload Type 判定"]
+    TEMPLATE["策略模板加载<br/>(淘汰/准入/预取/Tier 参数)"]
+    APPLY["应用至 Policy Engine"]
+
+    WIN --> FEAT --> RULE
+    RULE -->|"匹配成功"| CLASSIFY
+    RULE -->|"不匹配"| KMEANS --> CLASSIFY
+    CLASSIFY --> TEMPLATE --> APPLY
+```
+
+**切换平滑性：** workload type 变化时，策略参数不是瞬间切换，而是通过加权过渡（新旧模板权重在 3 个窗口周期内从 100:0 渐变到 0:100），避免策略突变导致缓存抖动。
+
+**混合负载处理：** 当 K-means 识别出多种 workload type 共存时（如同一集群同时服务对话和推荐），采用 per-session workload 标记——在请求入口处根据 session 特征打标签，各 session 独立使用对应模板，而非全局统一。
+
+### 5.4.2.3 策略层 (IO Pattern Policy Engine)
+
+策略层基于分析层的输出，通过可注册的 Ops 接口驱动各缓存机制：
+
+```
+flowchart TD
+    PE["Policy Engine"]
+
+    subgraph EvictionOps ["EvictionOps (淘汰策略)"]
+        LRU["LRU"]
+        LFU["LFU"]
+        SBE["ScoreBased<br/>(L0-L3 四层)"]
+    end
+
+    subgraph PrefetchOps ["PrefetchOps (预取策略)"]
+        BE["BestEffort"]
+        TO["Timeout"]
+        WC["WaitComplete"]
+        TB["TraceBased"]
+    end
+
+    subgraph AdmissionOps ["AdmissionOps (准入策略)"]
+        FREQ["Frequency"]
+        PM["PrefixMatch"]
+        WM["Watermark"]
+        CA["CostAware"]
+    end
+
+    PE --> EvictionOps
+    PE --> PrefetchOps
+    PE --> AdmissionOps
+```
+
+## 5.4.3 缓存机制集成与关键流程
+
+IO Pattern 模块不是重写现有机制，而是在现有机制之上增加统一的数据采集和分析层，通过 Ops 抽象接口驱动各机制。
+
+### 5.4.3.2 淘汰 (Eviction)
+
+**现有机制**：`EvictionStrategy` 抽象类（`eviction_strategy.h`）提供 LRU 和 FIFO 两种实现；`storage_backend.h` 中基于 `last_access_ns_` 维护 LRU 索引。
+
+**IO Pattern 增强**：引入基于评分的淘汰策略 (ScoreBasedEviction)，按4层缓存层级分别使用不同评分公式。所有指标先经归一化处理（`normalize(x) = x / max_observed_x`，映射到 `[0, 1]`），消除量纲差异后再加权求和。归一化基准基于滑动窗口（默认 60s）内的最大观测值动态更新。
+
+```
+flowchart TD
+    SNAP["IO Pattern Snapshot"]
+    NORM["归一化处理<br/>norm(x) = x / max_observed"]
+    PE["Policy Engine<br/>选择层级策略"]
+    SNAP --> NORM --> PE
+
+    PE --> L0S["L0 HBM Evict"]
+    PE --> L1S["L1 Host DRAM/SSD Evict"]
+    PE --> L2S["L2 Segment DRAM Evict"]
+    PE --> L3S["L3 Nof SSD Evict"]
+
+    L0S --> L0F["α\*norm(idle) - γ\*norm(freq)<br/>- δ\*norm(recompute) - ε\*norm(fanout)"]
+    L1S --> L1F["α\*norm(idle) - γ\*norm(freq)<br/>+ δ\*norm(lower_replica)<br/>- ε\*norm(fanout) - ζ*norm(recompute)"]
+    L2S --> L2F["α\*norm(idle) - γ\*norm(freq)<br/>+ δ\*norm(lower_replica)<br/>- ε\*norm(fanout) - ζ*norm(recompute)"]
+    L3S --> L3F["α\*norm(idle)\*norm(block_size)<br/>- γ\*norm(freq) - δ\*norm(recompute)<br/>+ η*norm(other_replica)"]
+
+    L0F --> L0OUT["-> L1"]
+    L1F --> L1OUT["-> L2"]
+    L2F --> L2OUT["-> L3"]
+    L3F --> L3OUT["-> 丢弃"]
+```
+
+**各层淘汰策略说明：**
+
+| 层级             | 评分侧重                                                              | 淘汰去向 | 说明                      |
+| ---------------- | --------------------------------------------------------------------- | -------- | ------------------------- |
+| L0 HBM           | `idle_time` 主导，`recompute_cost`/`prefix_fanout` 高权重保留         | → L1     | HBM 最贵，冷数据快速降级  |
+| L1 Host DRAM/SSD | 下层已有副本可安全淘汰，`prefix_fanout`/`recompute_cost` 高的数据保留 | → L2     | 本地 DRAM/SSD 到远端 DRAM |
+| L2 Segment DRAM  | `prefix_fanout`/`recompute_cost` 高的数据保留                         | → L3     | 池化内存到远端 SSD        |
+| L3 Nof SSD       | `block_size` 大 + 其他层已有副本优先淘汰                              | → 丢弃   | 最底层，无下降空间        |
+
+**集成方式**：扩展现有 `EvictionStrategy` 接口，新增 `ScoreBasedEvictionStrategy`，由 Policy Engine 根据层级动态选择策略。
+
+### 5.4.3.3 准入 (Admission)
+
+**现有机制**：
+
+- Client 侧：`CountMinSketch` + `admission_threshold_` 频率准入（`client_service.cpp`），仅频繁访问的 key 提升 hot cache
+- Master 侧：Promotion-on-Hit 的 `promotion_admission_threshold_` 频率门控 + watermark 门控（`master_service.cpp`）
+
+**IO Pattern 增强**：扩展准入策略为多层逐级准入控制，每层提升需满足对应条件：
+
+| 准入路径 | 条件                                                           | 说明                                                  |
+| -------- | -------------------------------------------------------------- | ----------------------------------------------------- |
+| L3→L2    | `access_count_window >= threshold`                             | 频率达标才从 Nof SSD 提升至 Segment DRAM              |
+| L2→L1    | `access_count_window >= threshold && upper_space <= max_space` | 频率达标且上层有空间才提升 Segment DRAM→Host DRAM/SSD |
+| L1→L0    | `max_length >= threshold (64)`                                 | 前缀长度达标才从 Host DRAM/SSD 提升至 HBM             |
+
+> 
+> SSD→HBM 跨层直达（跳过中间层）仅由推理框架 prefix cache 命中时触发，Mooncake 侧不自主执行跨层晋升到 HBM。
+
+```
+flowchart TD
+    REQ["访问请求"]
+    ANA["IO Pattern Analyzer<br/>计算准入条件"]
+    REQ --> ANA
+
+    ANA --> P1["L3→L2<br/>access_cnt >= thres"]
+    ANA --> P2["L2→L1<br/>access_cnt >= thres<br/>&& upper_space <= max"]
+    ANA --> P3["L1→L0<br/>max_length >= 64"]
+
+    P1 --> FA["频率准入<br/>(CountMin Sketch)"]
+    P2 --> FA2["频率+空间准入<br/>(Frequency + Watermark)"]
+    P3 --> PA["前缀准入<br/>(PrefixMatch Admission)"]
+```
+
+**集成方式**：扩展现有 `CountMinSketch` 准入逻辑，新增 `PrefixMatchAdmission` 和 `CostAwareAdmission` 策略。
+
+### 5.4.3.4 Tier Down / SSD Offload
+
+**现有机制**：
+
+- `enable_ssd_offload` + `ssd_offload_path` 配置 SSD offload 路径（`real_client.cpp`）
+- `offload_on_evict` 模式：在淘汰时延迟 offload 到 LOCAL_DISK（`master_service.cpp`）
+- `offload_force_evict`：超过 offload cap 时直接淘汰不 offload
+
+**IO Pattern 增强**：基于热度阈值的逐级 tier down，数据按 L0→L1→L2→L3 顺序逐层降级：
+
+```
+flowchart TD
+    START["L0 HBM 容量/水位检测"]
+    C1{"idle_time >= L0 cold_thres || frequency < L0 hot_thres ?"}
+    C2{"L2 seg_dram_avail ?"}
+    C3{"L3 nof SSD avail ?"}
+    C4{"L1 host DRAM<= thres ?"}
+    C5{"xds available ?"}
+    C6{"idle_time >= L1 cold_thres || frequency < L1 hot_thres ?"}
+    C7{"idle_time >= L2 cold_thres || frequency < L2 hot_thres ?"}
+	TD_L1A["L1 Host DRAM"]
+	TD_L1B["L1 SSD(xds)"]
+	TD_L2["L2 Segment DRAM"]
+    TD_L3["L3 Nof SSD"]
+
+    START --> C1
+    C1 -->|是| C4
+    C4 -->|是| TD_L1A
+    C4 -->|否| C5
+    C5 -->|是| TD_L1B
+    C5 -->|否| C2
+    C2 -->|是| TD_L2
+    C2 -->|否| C3
+    C3 -->|否| WAIT["下层均不可用<br/>等待重试 / 强制 evict"]
+    C3 -->|是| TD_L3
+    TD_L1A --> C6
+    C6 -->|是| C2
+    TD_L2 --> C7
+    C7 -->|是| C3
+```
+
+> 
+> 当所有下层均不可用时，数据暂留当前层并等待下层恢复，或触发强制 evict 释放空间。冷数据不会保留在高速层——高速层是最昂贵的资源，冷数据必须逐级降级。
+
+### 5.4.3.5 Tier Up / Promotion-on-Hit
+
+**现有机制**：
+
+- `promotion_on_hit` 模式（`master_service.cpp:379`）：Get 观察到 LOCAL_DISK-only key 时队列异步拷贝回 MEMORY
+- `CountMinSketch` 频率门控（`master_service.cpp:6944`）
+- watermark 门控：DRAM 低于 `eviction_high_watermark_ratio_` 才允许 promotion
+- `promotion_queue_limit` + `promotion_max_per_heartbeat` 控制 promotion 速率
+- `PromotionCandidate` 跟踪 + 重试 + TTL 过期
+
+**IO Pattern 增强**：IO Pattern 分析层为 promotion 提供更丰富的决策输入：
+
+- 前缀匹配度：高前缀匹配的 key 优先 promotion
+- 重计算代价：高 recompute_cost 的 key 优先 promotion
+- 迁移 ETA：根据带宽和 block_size 估算 transfer_eta，避免迁移耗时过长
+
+> 
+> Mooncake 侧 promotion 仅执行逐级提升（L3→L2→L1），不自主晋升到 L0 HBM。L0 HBM 层的数据加载由推理框架 prefix cache 命中时自主触发。
+
+```
+flowchart TD
+    START["prefix cache 命中/预取触发/get"]
+    CALC["Tier Up Priority 计算:<br/>priority = w0 * recompute_cost<br/>+ w1 * continuous_prefix<br/>+ w2 * request_priority<br/>- w3 * transfer_eta"]
+    SORT["按优先级排序"]
+    EXEC["执行逐级 tier up<br/>L3→L2→L1"]
+
+    START --> CALC --> SORT --> EXEC
+```
+
+### 5.4.3.6 预取 (Prefetch)
+
+**现有机制**：当前无显式预取机制，Promotion-on-Hit 在 Get 命中 LOCAL_DISK 时异步提升到 MEMORY。
+
+**IO Pattern 增强**：新增 `PrefetchOps` 抽象，SubMaster 根据 trace 和置信阈值生成预取器：
+
+**预取触发条件：** 低速层 prefix match length > 阈值 (256) 时触发预取至上一层（如 L3→L2、L2→L1）
+
+**预取策略（三种模式）：**
+
+| 策略            | 描述                                | 适用场景             |
+| --------------- | ----------------------------------- | -------------------- |
+| `best_effort`   | check & match，无论是否完成立即返回 | 对 TTFT 时延敏感业务 |
+| `timeout`       | 预取完成或超时立即返回              | 兼顾时延和命中率     |
+| `wait_complete` | 死等数据加载完成                    | 追求极致命中率       |
+
+分析层基于 trace 历史命中率和置信阈值生成策略输入。置信度 = 滑动窗口内命中次数 / 总访问次数，低于阈值时不触发操作避免误判。例如预取器生成：
+
+- SubMaster 根据 trace 历史 + 置信阈值（如 `confidence > 0.6 && prefix match length > 256`）生成预取器
+- 置信度低于阈值时不触发操作，避免误判导致的缓存污染
+- 置信阈值精确定义和各策略默认值详见
+
+**置信度计算：** 基于滑动窗口内的历史命中率，衡量当前预测的可信程度。
+
+```
+confidence = hit_count_in_window / total_access_in_window
+```
+
+**置信阈值应用：**
+
+| 策略     | 置信阈值                                        | 含义                                    | 默认值                               |
+| -------- | ----------------------------------------------- | --------------------------------------- | ------------------------------------ |
+| 预取触发 | `confidence > 0.6 && match_length > 256`        | 历史命中率 > 60% 且前缀匹配足够长才预取 | prefix_threshold=256, confidence=0.6 |
+| 准入提升 | `confidence > 0.5 && access_count >= threshold` | 历史命中率 > 50% 且频率达标才提升       | confidence=0.5                       |
+| 淘汰保守 | `confidence > 0.8` 时降低淘汰权重               | 高置信热数据更保守淘汰                  | confidence=0.8                       |
+
+> 
+> 置信度低于阈值时不触发操作，避免误判导致的缓存污染。置信度窗口默认 60s，可通过 `confidence_window_sec` 配置。
+
+预取流程仅看 `match_length > 256` 触发
+
+```
+flowchart TD
+    START["低速层 prefix match<br/>(L1-L3)"]
+    C1{"match_length > 256 ?"}
+    NOP["不预取"]
+    SEL["选择预取策略"]
+
+    START --> C1
+    C1 -->|否| NOP
+    C1 -->|是| SEL
+    SEL --> BE["best_effort"]
+    SEL --> TO["timeout"]
+    SEL --> WC["wait_complete"]
+```
+
+- `max_prefetch_ratio`：预取占用带宽上限比例，默认 20%，可通过 `prefetch_max_bw_ratio` 配置
+- 带宽不足时延迟重试，而非直接丢弃预取请求
+
+**集成方式**：在 SubMaster 中新增预取器，根据 IO Pattern 分析层的置信阈值异步预取 key 至上层。
+
+## 5.4.5 上层推理框架对接
+
+### 5.4.5.1 vLLM 集成
+
+**现有对接**：`MooncakeConnector`（`mooncake_connector_v1.py`）实现 vLLM `KVConnectorBase_V1` 接口，支持 PD disaggregation（Prefill/Decode 分离）。
+
+> 
+> **上层框架改动**：vLLM 侧无需改动。`MooncakeConnector` 作为 vLLM 的 out-of-tree connector（通过 `--kv_connector_module_path` 加载），在 connector 内部新增 CFM Client 调用即可上报指标和接收策略指令，不涉及 vLLM scheduler/engine 接口变更。vLLM v0.13.0+ 已内置 mooncake connector，后续可考虑将 CFM Client 合入上游。
+
+**IO Pattern 对接增强**：
+
+```
+flowchart TD
+    VLLM["vLLM Engine"]
+
+    subgraph MC ["MooncakeConnector (KVConnectorBase_V1)"]
+        GNMT["get_num_new_matched_tokens()<br/>上报 match_length"]
+        USA["update_state_after_alloc()<br/>上报 prefix_depth"]
+        RF["request_finished()<br/>上报 token_count, recompute_cost"]
+    end
+
+    subgraph CFMC ["CFM Client (新增)"]
+        RIM["IoPatternCollector<br/>.ReportInferenceMetrics()"]
+        POP["PrefetchOps<br/>接收预取指令"]
+        AOP["AdmissionOps<br/>接收准入策略"]
+    end
+
+    VLLM --> MC
+    VLLM --> CFMC
+    GNMT --> RIM
+    USA --> RIM
+    RF --> RIM
+```
+
+**采集对接**：在 `MooncakeConnector` 中增加 CFM Client 调用，将以下指标上报至 IO Pattern Collector：
+
+- `match_length`：prefix cache 命中长度（来自 `get_num_new_matched_tokens()`）
+- `prefix_depth` / `prefix_fanout`：前缀树结构（来自 `update_state_after_alloc()` 及 prefix cache manager）
+- `token_count`：请求 token 数（来自 `request_finished()`）
+- `recompute_cost`：重计算代价估算（connector 侧基于 token_count 和模型 FLOPS 估算）
+- `request_priority`：请求优先级（connector 层从 request metadata 提取）
+
+**策略对接**：CFM Client 接收 Policy Engine 的策略指令：
+
+- 预取指令：根据 prefix match length > 256 触发异步预取
+- 准入指令：根据频率/前缀匹配控制数据提升层级
+- 淘汰指令：根据淘汰评分驱动 L0-L3 层间淘汰
+
+### 5.4.5.2 SGLang 集成
+
+**现有对接**：SGLang HiCache 通过 `--hicache-storage-backend: mooncake` 将 Mooncake 作为存储后端，支持 layer_first / page_first 布局。
+
+**IO Pattern 对接增强**：
+
+```
+flowchart TD
+    SGL["SGLang Engine"]
+
+    subgraph HCC ["HiCache Connector"]
+        HR["hicache-ratio<br/>容量配比"]
+        HML["hicache-mem-layout<br/>layer_first / page_first"]
+        HIO["hicache-io-backend<br/>direct / async"]
+    end
+
+    subgraph CFMS ["CFM Client (新增)"]
+        RIM2["IoPatternCollector<br/>.ReportInferenceMetrics()"]
+        DLA["数据布局适配<br/>(layer_first / page_first)"]
+        PAS["预取/准入/淘汰策略"]
+    end
+
+    SGL --> HCC
+    SGL --> CFMS
+    HR --> RIM2
+    HML --> DLA
+    HIO --> RIM2
+```
+
+**数据布局适配**：IO Pattern 需感知推理框架的 KV cache 布局模式，vLLM 和 SGLang 均需适配：
+
+| 框架   | 布局模式                       | 描述                                                                      | IO Pattern 适配                                 |
+| ------ | ------------------------------ | ------------------------------------------------------------------------- | ----------------------------------------------- |
+| SGLang | `layer_first`                  | (2, layer, slot, num_head, head_dim)                                      | 前缀分析按 layer 维度，预取按 layer 批量        |
+| SGLang | `page_first`                   | (2, page_num, layer, num_head, head_dim)                                  | 前缀分析按 page 维度，预取按 page 批量          |
+| SGLang | `page_first_direct`            | 混合模型 (Full Attention + SWA/Mamba)                                     | 分区准入，full KV 固定分区 + SWA/mamba 灵活分配 |
+| vLLM   | `page-based` (block_size 粒度) | vLLM v1 默认 page-based 布局，connector 通过 `get_kv_cache_layout()` 检测 | 前缀分析按 block 维度，预取按 block 批量        |
+| vLLM   | `HMA multi-group`              | 混合模型 (attention + Mamba2)，`SupportsHMA` 多 group 布局                | 分组准入，各 group 独立淘汰/预取策略            |
+
+> 
+> vLLM connector 已在初始化时调用 `get_kv_cache_layout()` 检测布局（`mooncake_connector_v1.py:511`），并通过 `SupportsHMA` 支持 hybrid 模型多 group 布局。SGLang 通过 `--hicache-mem-layout` 参数显式配置布局。两者均需在 CFM Client 上报时附带布局信息，供 IO Pattern 分析层选择对应的预取/准入粒度。
+
+### 5.4.5.3 CFM Client 设计
+
+CFM Client 部署在推理节点侧，作为推理框架与 SuperCache 之间的策略桥梁：
+
+```
+flowchart TD
+    subgraph CFMClient ["CFM Client"]
+        MR["Metrics Reporter<br/>(采集上报)"]
+        PR["Policy Receiver<br/>(策略接收)"]
+        PE["Prefetch Executor<br/>(预取执行)"]
+        RPC["CFM RPC Channel<br/>(to SubMaster / PrefixCache Master)"]
+        MR --> RPC
+        PR --> RPC
+        PE --> RPC
+    end
+```
+
+**职责：**
+
+1. **Metrics Reporter**：定期（100ms）批量上报推理框架指标至 SubMaster
+2. **Policy Receiver**：接收 Policy Engine 的淘汰/预取/准入策略指令
+3. **Prefetch Executor**：执行异步预取，支持 best_effort / timeout / wait_complete 三种模式
+
+## 5.4.6 Ops 抽象接口设计
+
+> **接口修订（2026-09）**：本节原始的 string/vector 简化签名仅用于
+> 查询示例，不能承载租户、字节预算、评分、Tier、超时和置信度等执行
+> 元数据。实际实现统一采用文末“Revised Ops contract”中的完整计划接口。
+
+### 5.4.6.1 EvictionOps
+
+```
+// include/eviction_ops.h (扩展现有 eviction_strategy.h)
+class EvictionOps {
+   public:
+    virtual ~EvictionOps() = default;
+
+    // 基于 IO Pattern 评分选择淘汰 key
+    virtual std::vector<std::string> SelectEvictionCandidates(
+        const IoPatternSnapshot& snapshot,
+        CacheTier tier,
+        size_t target_bytes) = 0;
+
+    // 注册淘汰算法
+    static void Register(const std::string& name,
+                         std::function<std::shared_ptr<EvictionOps>()> factory);
+};
+
+// 已有实现: LRU, FIFO (eviction_strategy.h)
+// 新增实现: ScoreBasedEviction (L0-L3 四层不同评分公式)
+```
+
+### 5.4.6.2 PrefetchOps
+
+```
+// include/prefetch_ops.h (新增)
+class PrefetchOps {
+   public:
+    virtual ~PrefetchOps() = default;
+
+    // 基于 trace 和置信阈值生成预取候选
+    virtual std::vector<PrefetchCandidate> GeneratePrefetchPlan(
+        const IoPatternSnapshot& snapshot,
+        const TraceHistory& trace) = 0;
+
+    // 执行预取
+    virtual ErrorCode ExecutePrefetch(
+        const std::vector<PrefetchCandidate>& candidates,
+        PrefetchStrategy strategy) = 0;
+
+    static void Register(const std::string& name,
+                         std::function<std::shared_ptr<PrefetchOps>()> factory);
+};
+
+enum class PrefetchStrategy {
+    kBestEffort,    // 无论是否完成立即返回
+    kTimeout,       // 预取完成或超时立即返回
+    kWaitComplete,  // 死等数据加载完成
+};
+```
+
+### 5.4.6.3 AdmissionOps
+
+```
+// include/admission_ops.h (新增, 扩展现有 CountMinSketch 准入)
+class AdmissionOps {
+   public:
+    virtual ~AdmissionOps() = default;
+
+    // 准入决策：是否允许数据进入目标层
+    virtual AdmissionDecision CheckAdmission(
+        const std::string& key,
+        CacheTier target_tier,
+        const IoPatternSnapshot& snapshot) = 0;
+
+    static void Register(const std::string& name,
+                         std::function<std::shared_ptr<AdmissionOps>()> factory);
+};
+
+enum class AdmissionDecision {
+    kAdmit,           // 允许进入
+    kRejectFrequency, // 频率不足
+    kRejectWatermark, // 水位过高
+    kRejectPrefix,    // 前缀匹配不足
+    kDefer,           // 延迟决策 (记录候选)
+};
+
+// 已有实现: FrequencyAdmission (CountMinSketch)
+// 新增实现: PrefixMatchAdmission, CostAwareAdmission
+```
+
+### 5.4.6.4 Ops 注册机制
+
+```
+classDiagram
+    class EvictionOps {
+    <<interface>>
+    +SelectEvictionCandidates(snapshot, tier, bytes) vector~string~
+    +Register(name, factory) void
+    }
+    class PrefetchOps {
+    <<interface>>
+    +GeneratePrefetchPlan(snapshot, trace) vector~PrefetchCandidate~
+    +ExecutePrefetch(candidates, strategy) ErrorCode
+    +Register(name, factory) void
+    }
+    class AdmissionOps {
+    <<interface>>
+    +CheckAdmission(key, tier, snapshot) AdmissionDecision
+    +Register(name, factory) void
+    }
+    class PolicyEngine {
+        -ops_registry_ : map
+        +SelectOps(type, name) Ops
+        +ExecutePolicy(snapshot) PolicyResult
+    }
+
+    PolicyEngine --> EvictionOps : 查找/执行
+    PolicyEngine --> PrefetchOps : 查找/执行
+    PolicyEngine --> AdmissionOps : 查找/执行
+```
+
+## 5.4.7 写路径 IO Pattern
+
+### 5.4.7.1 写路径采集指标
+
+| 指标名              | 类型   | 描述                           | 采集来源            |
+| ------------------- | ------ | ------------------------------ | ------------------- |
+| `write_batch_size`  | uint32 | 批量写入 key 数                | SDK 层 (`BatchPut`) |
+| `write_object_size` | uint64 | 单次写入数据大小               | SDK 层              |
+| `write_burst`       | bool   | 是否突发写入（短时间大量 Put） | 分析层计算          |
+| `write_frequency`   | uint32 | key 写入频率                   | SDK 层              |
+| `overwrite_ratio`   | float  | 覆盖写比例 (同 key 重复 Put)   | 分析层计算          |
+
+### 5.4.7.2 写路径 Pattern 对策略的影响
+
+| Pattern    | 影响策略               | 处理方式                                                           |
+| ---------- | ---------------------- | ------------------------------------------------------------------ |
+| 突发写入   | 准入：避免写穿 SSD     | 突发写入期间提高 `admission_threshold`，冷数据暂留 DRAM 不 offload |
+| 高覆盖写   | 准入：跳过 SSD offload | 覆盖写比例高的 key 不 offload 到 SSD，避免无效写入                 |
+| 大批量写入 | GC：提前触发           | 预估写入量，提前通知 SSD 后端准备 GC 空间                          |
+| 低频写入   | 淘汰：降低保留优先级   | 低频写入的 key 在淘汰评分中 `frequency` 低，优先淘汰               |
+
+## 5.4.8 健壮性与可观测性
+
+### 5.4.8.1 失败降级
+
+IO Pattern 模块自身故障时，必须不影响数据路径，降级到现有基础机制：
+
+```
+flowchart TD
+    START["策略执行请求"]
+    C1{"IO Pattern 模块可用?"}
+    C2{"分析层响应<br/>超时?"}
+    NORMAL["正常路径:<br/>ScoreBasedEviction / PrefixMatchAdmission / TraceBasedPrefetch"]
+    DEGRADE["降级路径:<br/>LRU / FIFO / FrequencyAdmission<br/>(现有基础机制)"]
+
+    START --> C1
+    C1 -->|是| C2
+    C1 -->|否| DEGRADE
+    C2 -->|否| NORMAL
+    C2 -->|是| DEGRADE
+```
+
+| 故障场景       | 降级行为                          | 触发条件            |
+| -------------- | --------------------------------- | ------------------- |
+| SubMaster 崩溃 | 回退到 Client 本地 LRU/FIFO       | RPC 连续失败 > 3 次 |
+| 分析层超时     | 使用上一次成功快照                | 响应延迟 > 500ms    |
+| 分析层 OOM     | 丢弃 per-key 指标，仅保留全局指标 | 内存占用 > 阈值     |
+| RPC 网络抖动   | 延长上报间隔，本地缓存策略        | 丢包率 > 5%         |
+
+### 5.4.8.2 反馈闭环
+
+策略执行后需评估效果并自适应调优参数，形成闭环：
+
+```
+flowchart LR
+    EXEC["策略执行<br/>(eviction/prefetch/admission)"]
+    EVAL["效果评估<br/>(命中率/eviction抖动/TTFT)"]
+    TUNE["参数调优<br/>(权重/阈值自适应)"]
+    EXEC --> EVAL --> TUNE --> EXEC
+```
+
+**效果评估指标：**
+
+| 指标                | 描述                           | 评估窗口      |
+| ------------------- | ------------------------------ | ------------- |
+| `hit_rate_delta`    | 策略执行后命中率变化           | 60s 滑动窗口  |
+| `eviction_churn`    | 淘汰抖动（刚淘汰又被访问）     | 120s 滑动窗口 |
+| `ttft_delta`        | TTFT 时延变化                  | 30s 滑动窗口  |
+| `prefetch_accuracy` | 预取命中率（预取后是否被访问） | 60s 滑动窗口  |
+
+**参数自适应：** 当 `hit_rate_delta < 0` 持续超过 3 个评估窗口时，自动回退权重调整（如降低 `α` 权重），或切换到更保守的策略（如 ScoreBased → LRU）。
+
+### 5.4.8.3 IO Pattern 自观测
+
+IO Pattern 模块自身的运行指标，用于运维和调优：
+
+| 指标                             | 描述                                      |
+| -------------------------------- | ----------------------------------------- |
+| `io_pattern_collect_latency_us`  | 单次采集延迟                              |
+| `io_pattern_analyze_latency_us`  | 单次分析延迟                              |
+| `io_pattern_policy_decision_qps` | 策略决策 QPS                              |
+| `io_pattern_strategy_hit_rate`   | 策略命中率（策略命中 vs 总决策）          |
+| `io_pattern_false_positive_rate` | 误判率（预取未被访问 / 淘汰后被重新加载） |
+| `io_pattern_degrade_count`       | 降级次数                                  |
+| `io_pattern_report_drop_count`   | 上报丢弃数（采样降级）                    |
+
+
+# IO Pattern implementation design
+
+This page records the implementation state of the IO Pattern design and is
+updated together with the code. It is intentionally separate from the original
+proposal so that unresolved decisions are visible.
+
+## Current architecture
+
+```text
+Store/Get/Put -> Collector -> bounded Analyzer -> PolicyEngine -> Ops
+                 |                 |                   |-> Eviction handler
+                 |                 |                   |-> Prefetch handler
+                 |                 |                   `-> Admission handler
+                 |                 `-> per-session K-means fallback
+                 `-> CfmIngress <- report_metric_batch/report_snapshot (coro_rpc)
+                     (merge into the SubMaster's own runtime)
+```
+
+`MasterService` owns the runtime because it owns the authoritative replica
+metadata. Its handlers use the existing safe quota-eviction and
+promotion-on-hit queues; HBM stays inference-runtime-owned and is never moved
+by the Store master.
+
+### Current implementation architecture
+
+CFM is an embedded component of every SubMaster: the SubMaster's own
+`IoPatternRuntime` collects observations from its Store data path, evaluates
+policy and executes through the same storage-safe handlers. There is no
+standalone CFM Master deployment, no separate CFM endpoint and no auth token.
+A reporting client (inference connector / Store client) observes keys that may
+live on many SubMasters, resolves the owning SubMaster for every key through
+the CVM key->slot->submaster mapping, aggregates observations per owner and
+sends metric batches to each owning SubMaster's regular `coro_rpc` endpoint.
+The receiving SubMaster merges the report into its local runtime so
+collection, analysis and execution all stay on the SubMaster that owns the
+reported keys.
+
+```mermaid
+flowchart TB
+    subgraph producers["Metric producers"]
+        direction LR
+        inference["vLLM / SGLang bridge\nInferenceMetrics"]
+        access["Store Get/Put paths\nAccessRecord"]
+        storage["Storage and watermark paths\nStorageMetric"]
+    end
+
+    subgraph local["SubMaster MasterService (embedded CFM)"]
+        direction TB
+        runtime["IoPatternRuntime"]
+        collector["IoPatternCollectorImpl\nper-tenant/object aggregation\nrolling snapshot"]
+        ingress["CfmIngress\nmerge ownership-addressed reports"]
+        reporter["IoPatternReporter\nbounded MetricBatch queue\nadaptive 100/200/500/1000 ms flush"]
+        analyzer["ResilientAnalyzer\nSlidingWindowAnalyzer\nbudget + timeout fallback"]
+        policy["DegradingPolicyEngine\nWorkloadPolicyEngine\nper-session templates"]
+        executor["TierOperationExecutor"]
+        feedback["PolicyFeedbackWindow +\nAdaptivePolicyTuner"]
+        admission_worker["Admission worker\nbounded deferred queue"]
+
+        ingress --> runtime
+        runtime --> collector
+        collector --> reporter
+        collector --> analyzer
+        analyzer --> policy
+        policy --> executor
+        executor --> feedback
+        feedback -. "tune eviction weights" .-> policy
+        policy --> admission_worker
+    end
+
+    subgraph local_ops["Store-owned safe execution handlers"]
+        direction LR
+        evict["Eviction\ntenant-qualified quota eviction"]
+        prefetch["Prefetch\nLOCAL_DISK → MEMORY promotion queue"]
+        admit["Admission\npost-write retention / promotion"]
+    end
+
+    subgraph client["Reporting client (connector / Store client)"]
+        direction LR
+        owner["CvmOwnershipClient\nCVM key→slot→submaster bucketing"]
+        codec["CfmBinaryCodec\nversioned CFM2 wire format"]
+        channel["CfmRpcChannel\nencode/decode"]
+        rpc["CoroRpcCfmTransport\ncoro_rpc to the owning SubMaster"]
+        owner --> codec --> channel --> rpc
+    end
+
+    rpc_service["CfmRpcService::Send\non the SubMaster's coro_rpc port"]
+
+    inference -->|"ownership-addressed metric batches"| owner
+    access --> runtime
+    storage --> runtime
+    executor --> evict
+    executor --> prefetch
+    executor --> admit
+
+    reporter -->|"report_metric_batch"| ingress
+    rpc -->|"report_metric_batch / report_snapshot / execute_*"| rpc_service
+    rpc_service --> ingress
+    observability["IoPatternObservability\nlatency, hit rate, false positives,\ndegradation, report drops"] -.-> runtime
+```
+
+`CfmOwnershipClient` (or a single-endpoint `CfmRpcChannel` when one SubMaster
+is the only owner) is the normal report path. `CfmClientImpl` wraps a single
+channel for connectors; the client owns aggregation per owning SubMaster and
+explicitly drops observations whose owner cannot be resolved. The receiver
+merges every accepted report into the local runtime — there is no policy
+queue, poll, ACK or producer role to configure.
+
+Every accepted report also drives the local policy pipeline. The receiving
+SubMaster runs a background, coalescing `IoPatternRuntime` cycle after each
+`report_metric_batch` / `report_snapshot` merge. The cycle derives its
+decision inputs from the freshly aggregated snapshot: when the merged L1
+host-memory storage watermark (peak `memory_used_ratio` for `kL1Host` entries)
+exceeds the configured high ratio the cycle requests an eviction plan for host
+memory (target bytes = excess over the target ratio × reported capacity, only
+when the snapshot also contains L1 keys); keys that were recently served as
+hits and still carry L2/L3 replicas are fed to the prefetch ops, and hot
+lower-tier keys (not pinned, no L1 replica) are offered to the admission ops.
+When no storage watermark is exceeded but the runtime is configured with the
+cold-data eviction driver enabled (`report_driven_cold_eviction`), the cycle
+instead requests a bounded eviction of the coldest (idle) L1 keys so eviction
+is driven by cold/hot analysis and not only by memory pressure; the cycle
+report marks such passes with `cold_eviction=true`.
+Each cycle executes through the same storage-safe handlers, logs one
+`[IO-PATTERN-REPORT-CYCLE]` summary line (including whether the pass was a
+cold-eviction driver pass) and reports per-dimension outcomes to
+`MasterMetricManager` (`io_pattern_report_*` counters, visible on the master
+`/metrics` endpoint and in the periodic "Master Admin Metrics" log). This is
+what makes remote-mode policy execution observable: policy is no longer only
+run by the local memory-watermark thread, the local Put admission path or
+explicit `execute_*` RPCs.
+
+## Implemented
+
+- `IoPatternCollectorImpl` aggregates inference, access and storage metrics by
+  tenant/object and returns deterministic snapshots.
+- `ThresholdAnalyzer` classifies Code Agent, recommendation, conversation and
+  mixed workloads and calculates continuous confidence scores.
+- `ScoreBasedEvictionOps`, `PrefixMatchAdmissionOps` and
+  `TraceBasedPrefetchOps` provide the first production policy implementations.
+- `WorkloadPolicyEngine` selects workload templates, applies real weighted
+  transition over three detection windows, and selects independent templates
+  for K-means-labelled sessions.
+- `OpsRegistry` and `RegistryPolicyEngine` resolve named policy implementations.
+- `PolicyEngine::ExecutePolicy` returns one `PolicyResult` containing eviction,
+  prefetch and admission outcomes.
+- `IoPatternReporter` provides bounded, non-blocking batches with explicit
+  report/drop counters and a transport-agnostic sink.
+- `MetricBatchTransport` defines the transport seam, and the reporter exposes
+  load-sensitive 100/200/500/1000 ms flush recommendations.
+- `IoPatternRuntime` wires collection, bounded analysis, policy execution,
+  feedback tuning and storage handlers; `MasterService` feeds it from actual
+  Get/Put/watermark paths.
+- A coalescing report-driven execution worker (`report_driven_execution`
+  runtime config, enabled by `MasterService`) runs one full
+  Collector -> Analyzer -> PolicyEngine -> execution cycle after every merged
+  `report_metric_batch` / `report_snapshot`. The cycle derives an eviction
+  request only when the merged L1 host-memory storage watermark is above the
+  configured high ratio and the snapshot contains L1 keys, rebuilds a
+  prefetch trace from recently hit lower-tier keys and offers hot non-head
+  keys to the admission ops; an empty-candidate eviction is a clean no-op, not
+  a failure. Every cycle logs one `[IO-PATTERN-REPORT-CYCLE]` line and reports
+  its per-dimension outcome (eviction/prefetch/admission candidates, handler
+  statuses, degradation, cold-driver flag) to the process observer
+  (`MasterMetricManager` `io_pattern_report_*` counters on the master, visible
+  in `/metrics` and the "Master Admin Metrics" log). This keeps remote-mode
+  policy execution observable and data-driven instead of relying only on the
+  local eviction thread, the Put admission hook or explicit `execute_*` RPCs.
+- The cold-data eviction driver (`report_driven_cold_eviction` runtime config
+  plus `report_driven_cold_eviction_bytes` per-cycle budget and optional
+  `report_driven_cold_idle_threshold_us` gate) runs on the same report-driven
+  worker: when a cycle finds no storage-watermark pressure it still plans a
+  bounded eviction of the coldest non-pinned L1 keys, marks the pass
+  `cold_eviction=true` and executes through the same storage handlers, so
+  eviction is not only triggered at the memory high watermark. `MasterService`
+  surfaces it through `--io_pattern_cold_eviction`,
+  `--io_pattern_cold_eviction_bytes_per_cycle` and
+  `--io_pattern_cold_idle_threshold_us`.
+- `cfm_client_bench` optionally seeds real KV objects (`--master_server`,
+  `--num_keys`, `--value_size`, `--replica_num`, `--protocol` and the other
+  RealClient flags shared with `stress_cluster_bench`) before the simulated
+  vLLM request stream and reads a subset back, so the IO Pattern handlers run
+  against replicas that actually exist on the SubMaster (report-only runs leave
+  eviction/promotion/prefetch counters at zero because the handlers cannot act
+  on objects the master never stored).
+- `CfmClientImpl` wraps a single reporting channel for connectors
+  (`ReportSnapshot` / `ReportMetricBatch` / `ExecutePrefetch`); policy runs in
+  the SubMaster's own runtime, so there is no client-side dispatch loop.
+- `CfmOwnershipClient` is the multi-SubMaster report path: it resolves the
+  owning SubMaster of every key through a CVM-backed resolver, aggregates
+  observations per owner and delivers one batch per owner; unresolvable
+  observations are counted as drops.
+- `CfmIngress` is the CFM-to-Store endpoint on each SubMaster: it decodes
+  snapshot and metric-batch payloads into that SubMaster's local runtime and
+  executes prefetch/eviction plans through the same storage-safe handlers.
+- `ResilientCfmChannel` adds bounded retries and consecutive-failure
+  degradation state around a concrete reporting transport.
+- `PolicyFeedbackWindow` aggregates bounded execution-effect windows, and
+  `AdaptivePolicyTuner` adjusts eviction weights after repeated negative
+  hit-rate deltas.
+- `IoPatternObservability` provides thread-safe counters for collection and
+  analysis latency, policy hit rate, false positives, degradation and report
+  drops.
+- Its windowed snapshot also exposes strategy hit rate, false-positive rate and
+  policy decision QPS.
+- `SlidingWindowAnalyzer` keeps timestamp-bounded snapshots and computes
+  median/p90 workload features before threshold classification.
+- `IoPatternCollectorImpl` enforces an optional per-tenant key quota and
+  exposes dropped-observation counts for overload protection.
+- The vLLM connector accumulates match, allocation and completion metrics per
+  request and reports a complete layout-aware record through its optional
+  `io_pattern_bridge`. `SglangHiCacheIoPatternBridge` provides the matching
+  bounded, layout-aware adapter for HiCache request-finished/prefix hooks.
+- `TierOperationExecutor` bridges `PolicyResult` to storage-owned eviction,
+  prefetch and admission handlers and marks missing handlers as degraded.
+- `ResilientAnalyzer` caches the last successful result and falls back to it
+  (or conservative mixed mode) when analysis throws, with failure tracking.
+- `CfmBinaryCodec` defines the versioned `CFM2` protocol and fully round-trips
+  snapshots, metric batches and every policy command. `InProcessCfmRpcTransport`
+  provides embedded operation for tests, while `CfmChannelPool` reuses and
+  fails over a bounded set of reporting channels.
+- `CfmRpcChannel::SendMetricBatch` and `MakeCfmMetricBatchSink` connect the
+  bounded Reporter to the RPC path; producers only enqueue and Flush performs
+  the transport call outside the data-path critical section.
+- `IoPatternReporter::Start/Stop` provides a background flush worker with
+  adaptive intervals; `Stop` performs a final synchronous drain.
+- `IoPatternCollectorImpl` derives write-path fields for PUT records:
+  frequency, batch size, object size, overwrite ratio and burst flag.
+- `DegradingPolicyEngine` switches to a caller-provided fallback engine after
+  repeated failures and supports explicit recovery.
+- `AdaptivePolicyTuner` also reacts to eviction churn, TTFT regression and
+  prefetch accuracy, exposes conservative mode and supports persistence
+  callbacks for tuned weights. The runtime accepts feedback samples and
+  applies the resulting weights to both global and per-session engines.
+- Analyzer execution has a single in-flight worker, timeout fallback to the
+  last safe result, and an explicit key-count budget; collector key quotas and
+  reporter bounds provide the associated overload/OOM protection.
+- Access and write frequencies use timestamped buckets pruned against a true
+  rolling 60-second cutoff. Sliding analysis deduplicates objects across
+  snapshots and enforces a hard total retained-key budget (including a single
+  oversized snapshot), so repeated high-watermark evaluations cannot multiply
+  complete snapshots without bound. CFM ingress rebases process-local monotonic
+  timestamps to receiver time, and each object also has a hard bucket-count cap.
+- Store-side eviction executes only the tenant-qualified objects selected by
+  the policy. The legacy `BatchEvict` path runs only when policy execution
+  fails, avoiding a second unplanned eviction pass.
+- Non-memory PUT completions enqueue bounded, asynchronous L1 retention/
+  promotion evaluation. This is a post-write cache-admission hook, not initial
+  replica placement: the existing `PutStart` contract selects and allocates
+  replicas before write metrics such as batch and overwrite are known.
+- Reporter intervals follow the documented memory/RPC load thresholds
+  (100/200/500/1000 ms), and in-process transport callbacks execute outside the
+  transport mutex.
+
+## Interface decision: complete plans versus document shorthand
+
+The proposal's shorthand methods returned only keys, candidates or a decision.
+The implementation also needs tenant identity, byte sizes, scores, confidence,
+timeout and strategy metadata. Therefore the complete plan interfaces are the
+only Ops execution seam:
+
+- `EvictionOps::Evaluate` returns `EvictionPlan`.
+- `PrefetchOps::Evaluate` returns `PrefetchPlan`.
+- `AdmissionOps::Evaluate` returns `AdmissionResult`.
+
+The former shorthand methods (`SelectEvictionCandidates`,
+`GeneratePrefetchPlan`, `ExecutePrefetch`, and `CheckAdmission`) have been
+removed from the C++ interfaces. Callers must use complete plans and
+`TierOperationExecutor` for execution.
+
+### Revised Ops contract (2026-09)
+
+The following contract supersedes the shorthand signatures in section 5.4.6:
+
+```cpp
+class EvictionOps {
+ public:
+  virtual EvictionPlan Evaluate(const PolicyContext&, CacheTier,
+                                uint64_t target_bytes) const = 0;
+};
+
+class PrefetchOps {
+ public:
+  virtual PrefetchPlan Evaluate(const PolicyContext&,
+                                const TraceHistory&) const = 0;
+};
+
+class AdmissionOps {
+ public:
+  virtual AdmissionResult Evaluate(const ObjectRef&, CacheTier,
+                                   const PolicyContext&) const = 0;
+};
+```
+
+`EvictionPlan` carries tenant-qualified objects, byte budgets and scores;
+`PrefetchPlan` carries source/target tiers, strategy, timeout and confidence;
+`AdmissionResult` carries tenant identity, target tier, decision and
+confidence. These fields are required by execution, observability and
+multi-tenant isolation and must not be collapsed into strings.
+
+`PolicyEngine::ExecutePolicy` is the single orchestration entry point and
+returns `PolicyResult` with explicit `degraded` propagation.
+
+Registry ownership is external and thread-safe. Factories return independent
+Ops instances; callers own the returned smart pointers. Concrete storage and
+RPC resources are injected through execution handlers and CFM channels.
+
+## Production CFM wiring
+
+Every Master registers the CFM report handler (`CfmRpcService::Send`) on its
+existing `coro_rpc` port — the same endpoint all other Mooncake RPCs use. No
+extra `io_pattern_cfm_endpoint`, `io_pattern_cfm_auth_token`,
+`io_pattern_cfm_node_id` or producer credential is configured: Mooncake RPCs
+run inside the trusted deployment, and CFM is a component of the SubMaster
+that owns the reported keys.
+
+A SubMaster's embedded CFM works as follows:
+
+- The local Store data path records `AccessRecord` / `StorageMetric` straight
+  into the SubMaster's own `IoPatternRuntime`; eviction runs through the same
+  storage-safe quota/promotion handlers (no per-node runtime, policy queue or
+  poll loop).
+- A reporting client (vLLM/SGLang connector or the Store client) observes keys
+  that may belong to different SubMasters. It resolves the owner of each key
+  with the CVM mapping (`cvm::KeySlot` over the `/cvm/<ns>` master registry),
+  aggregates observations by owning SubMaster, and delivers one
+  `report_metric_batch` / `report_snapshot` per owner over coro_rpc.
+- The receiving SubMaster's `CfmIngress` merges the batch into its local
+  runtime and normalizes remote StorageMetric watermarks against the
+  transport source, so collection, analysis and execution never leave the
+  SubMaster that owns the keys.
+
+Reports that fail to resolve to an owner are counted as dropped observations
+on the client, so callers degrade explicitly instead of guessing an owner.
+Explicit `execute_prefetch` / `execute_policy` RPCs are also accepted by the
+same handler and run through the receiving SubMaster's local storage
+handlers, preserving the storage-safe execution seam for cross-node commands.
+
+The SGLang adapter remains framework-neutral because SGLang source is not
+vendored in this repository.
diff --git a/docs/yh/deployment.md b/docs/yh/deployment.md
new file mode 100644
index 0000000000..df0a0879a2
--- /dev/null
+++ b/docs/yh/deployment.md
@@ -0,0 +1,777 @@
+
+
+
+
+# POC项目Mooncake部署文档
+
+## 1 ETCD环境搭建
+### 1.1 安装
+
+```bash
+wget --no-check-certificate https://github.com/etcd-io/etcd/releases/download/v3.5.9/etcd-v3.5.9-linux-arm64.tar.gz
+tar -xzvf etcd-v3.5.9-linux-arm64.tar.gz
+rm etcd-v3.5.9-linux-arm64.tar.gz
+mv etcd-v3.5.9-linux-arm64/ etcd
+cd etcd/
+cp etcd etcdctl /usr/local/bin/
+```
+
+### 1.2 配置
+
+#### 1.2.1 方法1，一同创建（推荐）
+
+##### 1.2.1.1 设置system脚本
+
+```bash
+vim /etc/systemd/system/etcd.service
+```
+
+`ETCD_NAME,	ETCD_INITIAL_ADVERTISE_PEER_URLS,	ETCD_ADVERTISE_CLIENT_URLS`根据本机实际配置
+`ETCD_INITIAL_CLUSTER`配置集群全部节点的地址
+
+```
+[Unit]
+Description=etcd key-value store
+After=network.target
+
+[Service]
+Type=notify
+Environment=ETCD_NAME=<nodename1>
+Environment=ETCD_DATA_DIR=/var/lib/etcd
+Environment=ETCD_LISTEN_PEER_URLS=http://0.0.0.0:2380
+Environment=ETCD_LISTEN_CLIENT_URLS=http://0.0.0.0:2379
+Environment=ETCD_INITIAL_ADVERTISE_PEER_URLS=http://<node1 IP>:2380
+Environment=ETCD_ADVERTISE_CLIENT_URLS=http://<node1 IP>:2379
+Environment=ETCD_INITIAL_CLUSTER="<nodename1>=http://<node1 IP>:2380,<nodename2>=http://<node2 IP>:2380"
+Environment=ETCD_INITIAL_CLUSTER_STATE="new"
+Environment=ETCD_INITIAL_CLUSTER_TOKEN="etcd-cluster"
+ExecStart=/usr/local/bin/etcd
+Restart=on-failure
+RestartSec=5
+User=root
+
+[Install]
+WantedBy=multi-user.target
+```
+
+##### 1.2.1.2 清除缓存，应用配置，启动etcd服务
+
+为所有节点配置完成后，启动全部服务
+
+```bash
+systemctl disable etcd
+systemctl stop etcd
+rm -rf /var/lib/etcd
+systemctl daemon-reload
+systemctl start etcd
+systemctl enable etcd
+```
+
+##### 1.2.1.3 查看集群
+
+```bash
+etcdctl --endpoints=http://<node1 IP>:2379 member list --write-out=table
+```
+
+#### 1.2.2 方法2，逐个创建
+
+##### 1.2.2.1 设置system脚本
+
+```bash
+vim /etc/systemd/system/etcd.service
+```
+
+主机 （ip换为本机ip）
+
+```
+[Unit]
+Description=etcd key-value store
+After=network.target
+
+[Service]
+Type=notify
+Environment=ETCD_NAME=<nodename1>
+Environment=ETCD_DATA_DIR=/var/lib/etcd
+Environment=ETCD_LISTEN_PEER_URLS=http://0.0.0.0:2380
+Environment=ETCD_LISTEN_CLIENT_URLS=http://0.0.0.0:2379
+Environment=ETCD_INITIAL_ADVERTISE_PEER_URLS=http://<node1 IP>:2380
+Environment=ETCD_ADVERTISE_CLIENT_URLS=http://<node1 IP>:2379
+Environment=ETCD_INITIAL_CLUSTER="<nodename1>=http://<node1 IP>:2380"
+Environment=ETCD_INITIAL_CLUSTER_STATE="new"
+Environment=ETCD_INITIAL_CLUSTER_TOKEN="etcd-cluster"
+ExecStart=/usr/local/bin/etcd
+Restart=on-failure
+RestartSec=5
+User=root
+
+[Install]
+WantedBy=multi-user.target
+```
+
+##### 1.2.2.2 清除缓存，应用配置，启动etcd服务
+
+```bash
+systemctl stop etcd
+rm -rf /var/lib/etcd
+systemctl daemon-reload
+systemctl start etcd
+```
+
+##### 1.2.2.3 添加节点
+
+```bash
+etcdctl --endpoints=http://<node1 IP>:2379 member add <nodename2> --peer-urls=http://<node2 IP>:2380
+```
+
+有如下打印则为添加成功
+
+```
+[root@slot1 system]# etcdctl --endpoints=http://<node1 IP>:2379 member add <nodename2> --peer-urls=http://<node2 IP>:2380
+Member 6a5201d77502faa1 added to cluster 592c5fccdb3ab88c
+
+ETCD_NAME="<nodename2>"
+ETCD_INITIAL_CLUSTER="<nodename2>=http://<node2 IP>:2380,<nodename1>=http://<node1 IP>:2380"
+ETCD_INITIAL_ADVERTISE_PEER_URLS="http://<node2 IP>:2380"
+ETCD_INITIAL_CLUSTER_STATE="existing"
+```
+
+##### 1.2.2.4 将打印的部分内容复制到新节点etcd的配置文件
+
+例：<nodename2>的/etc/systemd/system/etcd.service配置文件
+
+```
+[Unit]
+Description=etcd key-value store
+After=network.target
+
+[Service]
+Type=notify
+Environment=ETCD_NAME=<nodename2>
+Environment=ETCD_DATA_DIR=/var/lib/etcd
+Environment=ETCD_LISTEN_PEER_URLS=http://0.0.0.0:2380
+Environment=ETCD_LISTEN_CLIENT_URLS=http://0.0.0.0:2379
+Environment=ETCD_INITIAL_ADVERTISE_PEER_URLS=http://<node2 IP>:2380
+Environment=ETCD_ADVERTISE_CLIENT_URLS=http://<node2 IP>:2379
+Environment=ETCD_INITIAL_CLUSTER="<nodename2>=http://<node2 IP>:2380,node182=http://<node1 IP>:2380"
+Environment=ETCD_INITIAL_CLUSTER_STATE="existing"
+Environment=ETCD_INITIAL_CLUSTER_TOKEN="etcd-cluster"
+ExecStart=/usr/local/bin/etcd
+Restart=on-failure
+RestartSec=5
+User=root
+
+
+[Install]
+WantedBy=multi-user.target
+```
+
+##### 1.2.2.5 在新节点的机器上启动服务
+
+```bash
+systemctl stop etcd
+rm -rf /var/lib/etcd
+systemctl daemon-reload
+systemctl start etcd
+```
+
+##### 1.2.2.6 查看集群
+
+```bash
+etcdctl --endpoints=http://<node1 IP>:2379 member list --write-out=table
+```
+
+##### 1.2.2.7 重复3-6步骤添加新节点进集群
+
+### 1.3 其他
+
+#### 1.3.1 删除节点
+
+查看当前集群成员列表
+
+```bash
+etcdctl member list
+```
+
+删除指定ID的节点
+
+```bash
+etcdctl member remove <member-id>
+```
+
+#### 1.3.2 查看etcd集群的Leader
+
+```bash
+etcdctl get mooncake-store/mooncake_cluster/master_view --print-value-only
+```
+
+
+
+## 2 MinIO（S3）环境搭建
+### 2.1 下载 MinIO 二进制文件
+
+```bash
+wget https://dl.min.io/server/minio/release/linux-amd64/minio
+```
+
+### 2.2 赋予执行权限
+
+```bash
+chmod +x minio
+```
+
+### 2.3 移动到系统路径
+
+```bash
+sudo mv minio /usr/local/bin/
+```
+
+### 2.4 创建数据目录
+
+```bash
+mkdir -p /home/minio_data
+```
+
+### 2.5 启动MinIO
+
+设置管理员用户名和密码
+
+```bash
+export MINIO_ROOT_USER=admin
+export MINIO_ROOT_PASSWORD=adminadmin
+```
+
+配置中写好所有节点的地址，在所有设备中运行
+
+```bash
+minio server \
+ --address ":9000"  \
+ --console-address ":9001" \
+ http://<node1 IP>/home/minio_data \
+ http://<node2 IP>/home/minio_data
+```
+
+
+### 2.6 配置自启动服务(可选)
+
+创建 `/etc/systemd/system/minio.service`文件：
+
+```ini
+[Unit]
+Description=MinIO Object Storage
+Documentation=https://docs.min.io
+Wants=network-online.target
+After=network-online.target
+
+[Service]
+User=root
+Group=root
+# 直接设置环境变量，不依赖外部文件
+Environment="MINIO_ROOT_USER=admin"
+Environment="MINIO_ROOT_PASSWORD=admin12345"
+Environment="MINIO_VOLUMES=http://<node1 IP>/home/minio_data http://<node2 IP>/home/minio_data"
+ExecStart=/usr/local/bin/minio server --address ":9000" --console-address ":9001" $MINIO_VOLUMES
+Restart=always
+LimitNOFILE=65536
+
+[Install]
+WantedBy=multi-user.target
+```
+
+保存后执行：
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl start minio
+sudo systemctl status minio
+```
+
+### 2.8 下载MC
+
+```bash
+# 下载 mc 客户端
+wget https://dl.min.io/client/mc/release/linux-arm64/mc
+
+# 赋予执行权限
+chmod +x mc
+
+# 移动到系统路径，方便全局使用
+sudo mv mc /usr/local/bin/
+```
+
+### 2.9 连接MinIO服务器并添加别名
+
+```bash
+mc alias set <别名> http://<你的服务器IP>:9000 <管理员用户名> <密码>
+```
+
+### 2.10 查看服务器信息
+
+```bash
+mc admin info myminio
+```
+
+### 2.11 创建桶
+
+```bash
+mc mb myminio/mooncake-snapshot
+```
+
+### 2.12 查看所有桶
+
+```bash
+mc ls myminio
+```
+
+
+## 3 Mooncake S3环境编译
+### 3.1 配置AWS-S3环境
+
+#### 3.1.1 检查环境
+
+```bash
+ls -l /usr/local/lib64/libaws-cpp-sdk-s3.so
+```
+
+或
+
+```bash
+ls -l /usr/local/lib/libaws-cpp-sdk-s3.so
+```
+
+若文件存在，则环境搭建完成
+
+#### 3.1.2 安装（AWS SDK C++）
+
+```bash
+git clone --depth 1 --recurse-submodules --shallow-submodules https://github.com/aws/aws-sdk-cpp.git
+cd aws-sdk-cpp
+mkdir build && cd build
+cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_ONLY="s3" -DENABLE_TESTING=OFF .. 
+make -j$(nproc)
+make install
+ldconfig
+```
+
+### 3.2 Mooncake安装
+
+```bash
+git config --global http.sslVerify false
+git clone --recurse-submodules https://github.com/<对应仓>/Mooncake.git
+cd Mooncake
+git checkout HA
+export GOPROXY="http://mirrors.aliyun.com/goproxy,direct"
+export GOINSECURE="go.etcd.io/etcd"
+export GOSUMDB="sum.golang.org"
+export CXXFLAGS="${CXXFLAGS} -w"
+export CFLAGS="${CFLAGS} -w"
+cmake -B build -DUSE_UB=ON -DBUILD_SHARED_LIBS=ON -DWITH_TE=ON -DWITH_STORE=ON -DWITH_P2P_STORE=ON -DUSE_ETCD=ON -DCMAKE_BUILD_TYPE=Release -DBUILD_UNIT_TESTS:BOOL=OFF -DSTORE_USE_ETCD=ON -DHAVE_AWS_SDK=ON
+cmake --build build -j$(nproc)
+git config --global http.sslVerify true
+```
+
+## 4 Mooncake HA测试脚本
+### 4.1 master运行脚本
+
+```bash
+export URMA_RPC_ENABLE=0
+export URMA_RPC_DEVICE=bonding_dev_0
+export URMA_RPC_EID_INDEX=0
+
+export MOONCAKE_SNAPSHOT_LOCAL_PATH=/home/mooncake_snapshot
+export MOONCAKE_AWS_ACCESS_KEY_ID="admin"
+export MOONCAKE_AWS_SECRET_ACCESS_KEY="adminadmin"
+export MOONCAKE_AWS_REGION="us-east-1"
+export MOONCAKE_AWS_BUCKET_NAME="mooncake-snapshot"
+export MOONCAKE_AWS_S3_ENDPOINT="http://<node ip>:9000"
+export MOONCAKE_MASTER_SERVICE_SNAPSHOT_TEST_SKIP_CLEANUP=1
+export MC_LOG_DIR="/home/master_log"
+
+mooncake_master \
+	--default_kv_lease_ttl=300000 \
+	--default_kv_soft_pin_ttl=300000 \
+	--metrics_port=9006 \
+	--rpc_port=50052 \
+	--ha_backend_type=etcd \
+	--etcd_endpoints="etcd://<node1 ip>:2379;<node2 ip>:2379" \
+	--enable_ha=true \
+	--enable_oplog=true \
+	--rpc_address=<node ip> \
+	--enable_metrics_report_to_backend=true \
+	--enable-offload=true \
+	--enable_snapshot=false \
+    --enable_snapshot_restore=false \
+    --snapshot_interval_seconds=10 \
+    --snapshot_retention_count=5 \
+    --snapshot_object_store_type="s3" \
+	--v=0 \
+    --cluster_id=mooncake_cluster
+
+```
+
+### 4.2 client运行脚本
+
+```bash
+export MC_URMA_ACTIVE_PORT=0
+export MOONCAKE_OFFLOAD_FILE_STORAGE_PATH=/home/mooncake_ssd
+export MC_STORE_CLIENT_METRIC=0
+export MC_STORE_CLIENT_METRIC_INTERVAL=3
+export MC_URMA_BONDING_MULTIPATH_ENABLE=on
+export MC_HIFREQ_LOG_SAMPLE_RATE=1
+export MOONCAKE_OFFLOAD_BUCKET_KEYS_LIMIT=1
+export GLOG_v=1
+export MC_LOG_DIR="/home/client_log"
+
+export URMA_RPC_ENABLE=0
+export URMA_RPC_DEVICE=bonding_dev_0
+export URMA_RPC_EID_INDEX=0
+
+mooncake_client \
+    --host=<node1 ip> \
+    --metadata_server="etcd://<node1 ip>:2379;<node2 ip>:2379" \
+    --master_server_address="etcd://<node1 ip>:2379;<node2 ip>:2379" \
+    --protocol=ub \
+    --device_names=bonding_dev_0 \
+    --global_segment_size=214748364080 \
+    --port=50053 \
+    --threads=32 \
+    --v=0 \
+    --enable_offload=true
+```
+
+### 4.3 数据写入脚本
+
+```bash
+export MC_STORE_CLIENT_SETUP_RETRIES=3
+export no_proxy="127.0.0.1,localhost,local,.local,192.168.0.0/16,10.0.0.0/8,172.16.0.0/12,141.61.0.0/16"
+export MC_STORE_CLIENT_METRIC_BANDWIDTH=0
+export MC_TCP_BIND_ADDRESS=<node1 ip>
+export MC_URMA_TRANS_MODE=RM
+
+export MC_URMA_BONDING_MULTIPATH_ENABLE=on
+export MC_HIFREQ_LOG_SAMPLE_RATE=1
+export MC_URMA_ACTIVE_PORT=0
+
+export URMA_RPC_ENABLE=0
+export URMA_RPC_DEVICE=bonding_dev_0
+export URMA_RPC_EID_INDEX=0
+
+export MC_LOG_DIR="/home/w00889253/client_log"
+
+stress_cluster_bench \
+    --metadata-server='etcd://<node1 ip>:2379;<node2 ip>:2379' \
+    --master-server='etcd://<node1 ip>:2379;<node2 ip>:2379' \
+    --local-hostname=$MC_TCP_BIND_ADDRESS \
+    --global-segment-size=0 \
+    --local-buffer-size=10737418240 \
+    --device-name=bonding_dev_0 \
+    --scenario=remote_memory \ # 四个场景segment_write,segment_read, remote_memory writer/reader
+    --role=writer \
+    --num-keys=10000 \
+    --protocol=ub \
+    --verify=true \
+    --num_threads=1 \
+    --batch-size=16 \
+    --duration=0 \
+    --master_admin_port=9006 \
+    --segments="<node1 ip>,<node2 ip>" \
+    --replica_num=1
+
+
+
+```
+
+### 4.4 数据读取脚本
+
+```bash
+export MC_STORE_CLIENT_SETUP_RETRIES=3
+export no_proxy="127.0.0.1,localhost,local,.local,192.168.0.0/16,10.0.0.0/8,172.16.0.0/12,141.61.0.0/16"
+export MC_STORE_CLIENT_METRIC_BANDWIDTH=0
+export MC_TCP_BIND_ADDRESS=<node1 ip>
+export MC_URMA_TRANS_MODE=RM
+
+export MC_URMA_BONDING_MULTIPATH_ENABLE=on
+export MC_HIFREQ_LOG_SAMPLE_RATE=1
+export MC_URMA_ACTIVE_PORT=0
+
+export URMA_RPC_ENABLE=0
+export URMA_RPC_DEVICE=bonding_dev_0
+export URMA_RPC_EID_INDEX=0
+
+export MC_LOG_DIR="/home/w00889253/client_log"
+
+stress_cluster_bench \
+    --metadata-server='etcd://<node1 ip>:2379;<node2 ip>:2379' \
+    --master-server='etcd://<node1 ip>:2379;<node2 ip>:2379' \
+    --local-hostname=$MC_TCP_BIND_ADDRESS \
+    --global-segment-size=0 \
+    --local-buffer-size=10737418240 \
+    --device-name=bonding_dev_0 \
+    --scenario=remote_memory \
+    --role=reader \
+    --num-keys=10000 \
+    --protocol=ub \
+    --verify=true \
+    --num_threads=1 \
+    --batch-size=16 \
+    --duration=0 \
+    --master_admin_port=9006 \
+    --segments="<node1 ip>,<node2 ip>" \
+    --replica_num=1
+
+
+```
+
+
+
+
+## 5 多副本参数配置
+### 配置说明：replica_num / nof_replica_num 与 client TTL
+
+> 代码基线：kvcache-ai/Mooncake `main`
+> 内容：① 多副本参数 `replica_num` / `nof_replica_num` 的设置位置与方式；② client TTL 的两种配置途径（摘自《故障感知延迟分析-master多久发现节点故障.md》）
+
+---
+
+### 5.1 replica_num 与 nof_replica_num
+
+#### 5.1.1 定义
+
+定义在 `mooncake-store/include/replica.h` L81-83 的 `ReplicateConfig` 结构体：
+
+```cpp
+struct ReplicateConfig {
+    size_t replica_num{1};       // 内存副本数，默认 1
+    size_t nof_replica_num{0};   // NoF（NVMe-oF SSD）副本数，默认 0
+    ...
+};
+```
+
+#### 5.1.2 设置方式（三种场景）
+
+**方式 1：C++ 代码中直接赋值**
+
+```cpp
+ReplicateConfig config;
+config.replica_num = 2;        // 2 个内存副本
+config.nof_replica_num = 1;    // 1 个 NoF 副本
+auto result = client->Put(key, slices, config);
+```
+
+参考：`mooncake-store/tests/task_integration_test.cpp`、`mooncake-store/tests/replica_count_verify_test.cpp`。
+
+**方式 2：Python API**
+
+通过 pybind11 暴露为可读写属性（`mooncake-integration/store/store_py.cpp` L1832-1833，`def_readwrite`）：
+
+```python
+from mooncake.store import ReplicateConfig
+
+config = ReplicateConfig()
+config.replica_num = 1         # 1 个内存副本
+config.nof_replica_num = 1     # 1 个 NoF 副本
+rc = store.put(key, data, config)
+```
+
+参考：`mooncake-wheel/tests/test_replicated_distributed_object_store.py`、`scripts/test_copy_move_api.py`。
+
+**方式 3：命令行参数 / 环境变量（E2E 与 Benchmark）**
+
+| 场景 | 参数 | 默认值 |
+|---|---|---|
+| E2E client（`store_client_e2e.py`） | `--memory-replica-num` / `--nof-replica-num` | 1 / 1 |
+| E2E 脚本（`run_nof_heartbeat_tcp_e2e.sh`） | 环境变量 `CLIENT_MEMORY_REPLICA_NUM` / `CLIENT_NOF_REPLICA_NUM` | 1 / 1 |
+| Benchmark（`store_kv_bench.py`） | `--memory-replica-num` / `--nof-replica-num` | 1 / 0 |
+
+E2E 用法示例：
+
+```bash
+CLIENT_MEMORY_REPLICA_NUM=1 CLIENT_NOF_REPLICA_NUM=1 bash run_nof_heartbeat_tcp_e2e.sh
+```
+
+#### 5.1.3 这两个值如何决定副本写入模式
+
+`DetermineReplicaWriteMode`（`mooncake-store/include/replica.h` L156-165）：
+
+| `replica_num` | `nof_replica_num` | 写入模式 | 语义 |
+|---|---|---|---|
+| 1 | 0 | `SINGLE_REPLICA` | 单副本 |
+| 1 | 1 | `FLEXIBLE_DUAL_REPLICA` | 灵活双副本：1 内存 + 1 NoF，best-effort，任一类型成功即可（`HasExpectedReplicaAllocation` 只检查 `memory+nof > 0`） |
+| >1 或 >1 | 任意 | `RELIABLE_MULTI_REPLICA` | 可靠多副本：必须严格凑齐（`allocated_memory == replica_num` 且 `allocated_nof == nof_replica_num`） |
+| 0 | 0 | `SINGLE_REPLICA` | 退化为单副本 |
+
+#### 5.1.4 关键约束
+
+1. **`nof_replica_num > 0` 必须 USE_NOF=ON 编译**：否则 master 的 `PutStart` 直接返回 `INVALID_PARAMS`（`master_service.cpp` L3081-3088，`#ifndef USE_NOF` 分支；测试见 `replica_count_verify_test.cpp` Test 4）。
+2. **`replica_num` 与 `nof_replica_num` 不能同时为 0**：`store_kv_bench.py` L653 有显式校验 `ValueError`。
+3. **best-effort 语义**：`nof_replica_num == 0` 时，`HasExpectedReplicaAllocation`（`master_service.cpp` L121-133）只检查 `allocated_memory > 0`，不要求严格等于 `replica_num`。实测 `replica_num=5` 而只有 4 个 segment 时，分配 4 个副本仍算成功。
+
+---
+
+### 5.2 client TTL 的两种配置
+
+#### 5.2.1 背景结论
+
+- **master 多久发现 client 故障**：默认 **9~11 秒**（= client TTL ± 1s，TTL 默认 10s）。机制是"租约到期"，不是"心跳中断检测"。
+- **可配置项**：client TTL 可配置；client 心跳间隔（1s，`client_service.cpp` L3743 硬编码）和 master 检查周期（1s，`master_service.h` L1980 硬编码）不可配。
+- **配置位置**：这是 **`mooncake_master` 的启动参数，不是 client 的**。
+
+#### 5.2.2 两种配置途径
+
+**途径 1：命令行参数 `--client_ttl`**。gflag 定义（`master.cpp` L260-264），启动时 `mooncake_master --client_ttl=5` 即生效：
+
+```cpp
+DEFINE_int64(
+    client_ttl, mooncake::DEFAULT_CLIENT_LIVE_TTL_SEC,
+    "Seconds a client stays considered alive after the last heartbeat. "
+    "If this TTL elapses without a refresh, the master treats the "
+    "client as disconnected and may unmount its segments");
+```
+
+**途径 2：master 配置文件（键名 `client_live_ttl_sec`）**。master 启动时若指定了配置文件，会从中读这个键；读不到则用 gflag 的值兜底（`master.cpp` L465-467，第三个参数就是兜底值 `FLAGS_client_ttl`）：
+
+```cpp
+    default_config.GetInt64("client_live_ttl_sec",
+                            &master_config.client_live_ttl_sec,
+                            FLAGS_client_ttl);
+```
+
+**优先级：命令行显式设置 > 配置文件**。命令行显式传了 `--client_ttl`（`!info.is_default` 判断非默认值），或根本没用配置文件（`!conf_set`），则用命令行值覆盖（`master.cpp` L949-953）：
+
+```cpp
+    if ((google::GetCommandLineFlagInfo("client_ttl", &info) &&
+         !info.is_default) ||
+        !conf_set) {
+        master_config.client_live_ttl_sec = FLAGS_client_ttl;
+    }
+```
+
+#### 5.2.3 配置速查表
+
+| 参数 | 默认 | 可配 | 配置在哪 | 源码位置 |
+|---|---|---|---|---|
+| client TTL | 10s | ✅ | `mooncake_master --client_ttl=<秒>` / master 配置文件 `client_live_ttl_sec` | `master.cpp` L260-264 / L465-467 / L949-953；`types.h` L95 `DEFAULT_CLIENT_LIVE_TTL_SEC=10` |
+| client 心跳间隔 | 1s | ❌ | —（client 代码硬编码） | `client_service.cpp` L3743 |
+| master 检查周期 | 1s | ❌ | —（master 代码硬编码） | `master_service.h` L1980 |
+
+一句话：同一个参数，命令行叫 `client_ttl`、配置文件里叫 `client_live_ttl_sec`，最终都写进 `master_config.client_live_ttl_sec`，两头都设时命令行优先。
+
+实测：E2E 中 master 以 `--client_ttl=5` 启动，kill 数据节点后感知延迟落在 4~6s 区间，与理论吻合。
+
+### 5.3 bench方案验证
+
+验证思路：验证内存存在副本和disk磁盘存在副本两种方式进行验证。
+
+#### 5.3.1 内存存在副本验证思路
+
+写入500个key，如果存在两个client，则应该两边分别写入250个key，同时应该在另外一个client上面存在副本，则每个节点client内存应该有500个key。
+操作步骤：先写入500个key，然后断连一个节点client，读取全部的key，可以从另外一个节点上全部读取。
+
+#### 5.3.2 disk磁盘存在副本验证思路
+
+写入500个key，如果存在两个client，则两边都存在250个key，，同时应该在另外一个client上面存在副本，则每个节点client内存应该有500个key。同时将这些key卸载到本地磁盘当中，磁盘当中应该在每个节点上有完整的500个key。
+
+操作步骤：先写入500个key，然后断连两个节点client， 重启其中一个client，此时磁盘中的卸载的数据可以在master上重新加载，有500个key，此时读取数据应该能够将所有的数据都读到。
+
+参考脚本：
+master
+
+```
+mooncake_master \
+	--enable_http_metadata_server=true \
+    --http_metadata_server_host=0.0.0.0 \
+    --http_metadata_server_port=9109 \
+    --default_kv_lease_ttl=300000 \
+    --default_kv_soft_pin_ttl=300000 \
+	--metrics_port=9006 \
+	--rpc_port=50052 \
+    --enable-offload=true
+
+```
+
+client
+
+```
+export MC_TCP_BIND_ADDRESS=<node1 ip>
+export MC_URMA_ACTIVE_PORT=0
+export MOONCAKE_OFFLOAD_FILE_STORAGE_PATH=/home/mooncake_ssd
+export MC_STORE_CLIENT_METRIC=0
+export MC_STORE_CLIENT_METRIC_INTERVAL=3
+export MC_URMA_BONDING_MULTIPATH_ENABLE=on
+export MC_HIFREQ_LOG_SAMPLE_RATE=0
+export MOONCAKE_OFFLOAD_BUCKET_KEYS_LIMIT=1(重要，确保所有key存入到磁盘当中）
+
+export URMA_RPC_ENABLE=0
+export URMA_RPC_DEVICE=bonding_dev_0
+export URMA_RPC_EID_INDEX=0
+mooncake_client \
+    --host=<node1 ip> \
+    --metadata_server=http://<node1 ip>:9109/metadata \
+    --master_server_address=<node1 ip>:50052 \
+    --protocol=ub \
+    --device_names=bonding_dev_0 \
+    --global_segment_size=21474836408 \
+    --port=50053 \
+    --threads=32 \
+    --v=0 \
+    --enable_offload=true
+
+```
+
+写入/读取脚本
+
+```
+export MC_STORE_CLIENT_SETUP_RETRIES=3
+export no_proxy="127.0.0.1,localhost,local,.local,192.168.0.0/16,10.0.0.0/8,172.16.0.0/12,141.61.0.0/16"
+export MC_STORE_CLIENT_METRIC_BANDWIDTH=0
+export MC_TCP_BIND_ADDRESS=<node1 ip>
+export MC_URMA_TRANS_MODE=RM
+export MC_LOG_ENABLE=off
+# export MC_LOG_DIR=/home/log
+export MC_URMA_BONDING_MULTIPATH_ENABLE=on
+export MC_HIFREQ_LOG_SAMPLE_RATE=0
+export MC_URMA_ACTIVE_PORT=0
+
+export URMA_RPC_ENABLE=0
+export URMA_RPC_DEVICE=bonding_dev_0
+export URMA_RPC_EID_INDEX=0
+
+stress_cluster_bench \
+        --metadata-server='http://<node1 ip>:9109/metadata' \
+        --master-server='<node1 ip>:50052' \
+        --local-hostname=$MC_TCP_BIND_ADDRESS \
+        --global-segment-size=0 \
+        --local-buffer-size=10737418240 \
+        --device-name=bonding_dev_0 \
+        --scenario=remote_memory \ （使用remote memory，这样key可以以固定结构写入）
+        --role=reader \ （写入数据使用writer，读取使用reader）
+        --num-keys=500 \
+        --protocol=ub \
+        --verify=false \
+        --num_threads=1 \
+        --batch-size=16 \
+        --duration=0 \
+        --master_admin_port=9006 \
+        --replica_num=2 （副本数量）
+
+```
+
+
+# 6 mooncake基础信息上报
+
+在上述启动master的脚本中，配置```enable_metrics_report_to_backend=true``,可以通过etcd命令行查找到对应数据
+参考示例如下：
+
+```
+[root@node1 Mooncake]# etcdctl --endpoints=<node1 ip>:2379,<node2 ip>:2379 get --prefix /mooncake_cluster/masters/primary
+/mooncake_cluster/masters/primary
+{"id":"4056379308262733915-15491753023959092137","hostname":"<node2 ip>:50052","role":"primary","mem_total_bytes":42949672816,"mem_used_bytes":4194304000,"mem_available_bytes":38755368816,"nof_total_bytes":0,"nof_used_bytes":0,"nof_available_bytes":0,"file_total_bytes":4398046511104,"file_used_bytes":9080668160,"file_available_bytes":4388965842944,"key_count":500,"active_clients":2,"updated_at":"2026-08-06T16:59:35+08:00"}
+[root@node1 Mooncake]# etcdctl --endpoints=<node1 ip>:2379,<node2 ip>:2379 get --prefix /mooncake_cluster/masters/primary
+/mooncake_cluster/masters/primary
+{"id":"4056379308262733915-15491753023959092137","hostname":"<node2 ip>:50052","role":"primary","mem_total_bytes":42949672816,"mem_used_bytes":4194304000,"mem_available_bytes":38755368816,"nof_total_bytes":0,"nof_used_bytes":0,"nof_available_bytes":0,"file_total_bytes":4398046511104,"file_used_bytes":9080668160,"file_available_bytes":4388965842944,"key_count":500,"active_clients":2,"updated_at":"2026-08-06T17:00:40+08:00"}
+```
+
+
+# 7 mooncake性能信息
+
+使用脚本```Mooncake/mooncake-store/benchmarks/cluster_mooncake_diag.py```
+参考其中的使用方法，在对应脚本当中设置对应log日志，则可以进行读取。
\ No newline at end of file
diff --git a/mooncake-common/etcd/etcd_wrapper.go b/mooncake-common/etcd/etcd_wrapper.go
index 7cedada048..f75a1e3415 100644
--- a/mooncake-common/etcd/etcd_wrapper.go
+++ b/mooncake-common/etcd/etcd_wrapper.go
@@ -811,8 +811,49 @@ func EtcdStoreBatchCreateWrapper(keys **C.char, values **C.char, count C.int, er
 	return 0
 }
 
+//export EtcdStoreBatchPutWithLeaseWrapper
+func EtcdStoreBatchPutWithLeaseWrapper(keys **C.char, keySizes *C.int, values **C.char, valueSizes *C.int, count C.int, leaseId int64, errMsg **C.char) int {
+	cli := getStoreClient()
+	if cli == nil {
+		*errMsg = C.CString("etcd client not initialized")
+		return -1
+	}
+
+	n := int(count)
+	if n == 0 {
+		return 0
+	}
+
+	// Unsafe casting to access C arrays as Go slices; key/value buffers are
+	// binary-safe (carry explicit sizes).
+	keyPtrs := (*[1 << 28]*C.char)(unsafe.Pointer(keys))[:n:n]
+	keySizeList := (*[1 << 28]C.int)(unsafe.Pointer(keySizes))[:n:n]
+	valPtrs := (*[1 << 28]*C.char)(unsafe.Pointer(values))[:n:n]
+	valSizeList := (*[1 << 28]C.int)(unsafe.Pointer(valueSizes))[:n:n]
+
+	ops := make([]clientv3.Op, 0, n)
+	for i := 0; i < n; i++ {
+		k := C.GoStringN(keyPtrs[i], keySizeList[i])
+		v := C.GoStringN(valPtrs[i], valSizeList[i])
+		// Bind all keys to the single master lease. Caller is responsible for
+		// fencing (the keys must already be absent / owned by self); this is an
+		// unconditional atomic batch, so it can also be reused for reaffirm.
+		ops = append(ops, clientv3.OpPut(k, v, clientv3.WithLease(clientv3.LeaseID(leaseId))))
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	_, err := cli.Txn(ctx).Then(ops...).Commit()
+	if err != nil {
+		*errMsg = C.CString(err.Error())
+		return -1
+	}
+	return 0
+}
+
 //export EtcdStoreTxnCompareAndPutWrapper
-func EtcdStoreTxnCompareAndPutWrapper(compareKeys **C.char, compareKeySizes *C.int, compareKinds *C.int, compareValues **C.char, compareValueSizes *C.int, compareCount C.int, putKeys **C.char, putKeySizes *C.int, putValues **C.char, putValueSizes *C.int, putCount C.int, errMsg **C.char) int {
+func EtcdStoreTxnCompareAndPutWrapper(compareKeys **C.char, compareKeySizes *C.int, compareKinds *C.int, compareValues **C.char, compareValueSizes *C.int, compareCount C.int, putKeys **C.char, putKeySizes *C.int, putValues **C.char, putValueSizes *C.int, putCount C.int, deleteKeys **C.char, deleteKeySizes *C.int, deleteCount C.int, errMsg **C.char) int {
 	cli := getStoreClient()
 	if cli == nil {
 		*errMsg = C.CString("etcd client not initialized")
@@ -821,6 +862,7 @@ func EtcdStoreTxnCompareAndPutWrapper(compareKeys **C.char, compareKeySizes *C.i
 
 	cmpN := int(compareCount)
 	putN := int(putCount)
+	deleteN := int(deleteCount)
 
 	cmps := make([]clientv3.Cmp, 0, cmpN)
 	if cmpN > 0 {
@@ -844,7 +886,7 @@ func EtcdStoreTxnCompareAndPutWrapper(compareKeys **C.char, compareKeySizes *C.i
 		}
 	}
 
-	ops := make([]clientv3.Op, 0, putN)
+	ops := make([]clientv3.Op, 0, putN+deleteN)
 	if putN > 0 {
 		putKeyPtrs := (*[1 << 28]*C.char)(unsafe.Pointer(putKeys))[:putN:putN]
 		putKeySizeList := (*[1 << 28]C.int)(unsafe.Pointer(putKeySizes))[:putN:putN]
@@ -856,6 +898,14 @@ func EtcdStoreTxnCompareAndPutWrapper(compareKeys **C.char, compareKeySizes *C.i
 			ops = append(ops, clientv3.OpPut(k, v))
 		}
 	}
+	if deleteN > 0 {
+		deleteKeyPtrs := (*[1 << 28]*C.char)(unsafe.Pointer(deleteKeys))[:deleteN:deleteN]
+		deleteKeySizeList := (*[1 << 28]C.int)(unsafe.Pointer(deleteKeySizes))[:deleteN:deleteN]
+		for i := 0; i < deleteN; i++ {
+			k := C.GoStringN(deleteKeyPtrs[i], deleteKeySizeList[i])
+			ops = append(ops, clientv3.OpDelete(k))
+		}
+	}
 
 	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 	defer cancel()
diff --git a/mooncake-common/include/rpc_client_io_context.h b/mooncake-common/include/rpc_client_io_context.h
index b9842f0c99..fb575df939 100644
--- a/mooncake-common/include/rpc_client_io_context.h
+++ b/mooncake-common/include/rpc_client_io_context.h
@@ -8,6 +8,7 @@
 #include <shared_mutex>
 #include <string>
 #include <string_view>
+#include <unordered_map>
 #include <utility>
 
 #include <ylt/coro_io/client_pool.hpp>
@@ -26,9 +27,10 @@ coro_io::io_context_pool& GetRpcClientIoContextPool(uint32_t thread_count) {
 }
 
 /**
- * A replaceable client pool for callers that communicate with one target at a
- * time. Requests retain a shared_ptr to the old pool while they are in flight;
- * after an address switch the old pool is destroyed when those requests end.
+ * A client pool accessor that caches one client pool per target address, so
+ * callers that alternate between several targets (e.g. submaster routing)
+ * reuse existing connections instead of recreating a pool on every switch.
+ * The most recently selected pool is also exposed via GetClientPool().
  */
 class RpcClientPool {
    public:
@@ -38,18 +40,22 @@ class RpcClientPool {
     explicit RpcClientPool(coro_io::io_context_pool& io_context_pool,
                            PoolConfig config = {})
         : io_context_pool_(io_context_pool), config_(std::move(config)) {
-        // Address replacement supersedes background recovery of the old host.
+        // Explicit target selection supersedes background recovery of an old
+        // host; the pool's own connect/retry still applies per request.
         config_.host_alive_detect_duration = std::chrono::seconds(0);
     }
 
     std::shared_ptr<ClientPool> GetOrCreateClientPool(
         std::string_view address) {
         std::lock_guard<std::shared_mutex> lock(mutex_);
-        if (!client_pool_ || address_ != address) {
-            client_pool_ =
-                ClientPool::create(address, config_, io_context_pool_);
-            address_ = address;
+        std::string addr(address);
+        auto it = pools_.find(addr);
+        if (it == pools_.end()) {
+            auto pool = ClientPool::create(addr, config_, io_context_pool_);
+            it = pools_.emplace(addr, std::move(pool)).first;
         }
+        address_ = std::move(addr);
+        client_pool_ = it->second;
         return client_pool_;
     }
 
@@ -58,12 +64,21 @@ class RpcClientPool {
         return client_pool_;
     }
 
+    std::string GetAddress() const {
+        std::shared_lock<std::shared_mutex> lock(mutex_);
+        return address_;
+    }
+
    private:
     mutable std::shared_mutex mutex_;
     coro_io::io_context_pool& io_context_pool_;
     PoolConfig config_;
     std::string address_;
     std::shared_ptr<ClientPool> client_pool_;
+    // Cache of client pools keyed by target address, so switching back and
+    // forth between submaster addresses reuses existing connections instead of
+    // recreating the pool on every switch.
+    std::unordered_map<std::string, std::shared_ptr<ClientPool>> pools_;
 };
 
 }  // namespace mooncake
diff --git a/mooncake-common/tests/rpc_client_io_context_test.cpp b/mooncake-common/tests/rpc_client_io_context_test.cpp
index c3b18c7127..d63fd5e34e 100644
--- a/mooncake-common/tests/rpc_client_io_context_test.cpp
+++ b/mooncake-common/tests/rpc_client_io_context_test.cpp
@@ -41,18 +41,19 @@ TEST(RpcClientIoContextPoolTest, UsesConfiguredSizeAndReusesPool) {
     EXPECT_NE(&first_pool, &second_pool);
 }
 
-TEST(RpcClientIoContextPoolTest, ReplacesPoolWhenTargetChanges) {
+TEST(RpcClientIoContextPoolTest, CachesPoolsPerAddress) {
     RpcClientPool pools(GetFirstTestRpcClientIoContextPool());
 
     auto first = pools.GetOrCreateClientPool("127.0.0.1:10001");
-    std::weak_ptr<RpcClientPool::ClientPool> old_pool = first;
     EXPECT_EQ(pools.GetOrCreateClientPool("127.0.0.1:10001"), first);
 
     auto second = pools.GetOrCreateClientPool("127.0.0.1:10002");
     EXPECT_NE(first, second);
-    first.reset();
-    EXPECT_TRUE(old_pool.expired());
     EXPECT_EQ(pools.GetClientPool(), second);
+
+    // Switching back reuses the cached pool instead of recreating it.
+    EXPECT_EQ(pools.GetOrCreateClientPool("127.0.0.1:10001"), first);
+    EXPECT_EQ(pools.GetClientPool(), first);
 }
 
 TEST(RpcClientIoContextPoolTest, SendsToNewAddressAfterSwitch) {
diff --git a/mooncake-store/benchmarks/CMakeLists.txt b/mooncake-store/benchmarks/CMakeLists.txt
index 817230b940..f851e0b2be 100644
--- a/mooncake-store/benchmarks/CMakeLists.txt
+++ b/mooncake-store/benchmarks/CMakeLists.txt
@@ -38,6 +38,16 @@ target_link_libraries(
   stress_cluster_bench PRIVATE mooncake_store transfer_engine asio_shared
                                gflags::gflags glog::glog pthread)
 
+# CFM client benchmark. Simulates vLLM inference requests as KV-cache block
+# accesses and reports both client performance and IO Pattern observability.
+add_executable(cfm_client_bench cfm_client_bench.cpp)
+target_link_libraries(
+  cfm_client_bench PRIVATE mooncake_store transfer_engine asio_shared
+                          gflags::gflags glog::glog pthread)
+if(STORE_USE_ETCD)
+  target_link_libraries(cfm_client_bench PRIVATE ${ETCD_WRAPPER_LIB})
+endif()
+
 # Benchmark for vLLM Store Connector path
 # Triggers: batch_put_from_multi_buffers / batchIsExist /
 # batch_get_into_multi_buffers (and setup/register_buffer/tearDownAll).
@@ -75,3 +85,10 @@ if(STORE_USE_ETCD)
     oplog_batch_bench PRIVATE mooncake_store glog::glog gflags::gflags
                               JsonCpp::JsonCpp)
 endif()
+
+if(STORE_USE_ETCD)
+  add_executable(vchunk_distributed_bench vchunk_distributed_bench.cpp)
+  target_link_libraries(
+    vchunk_distributed_bench PRIVATE mooncake_store transfer_engine asio_shared
+                                     gflags::gflags glog::glog pthread)
+endif()
diff --git a/mooncake-store/benchmarks/cfm_client_bench.cpp b/mooncake-store/benchmarks/cfm_client_bench.cpp
new file mode 100644
index 0000000000..810c035ef4
--- /dev/null
+++ b/mooncake-store/benchmarks/cfm_client_bench.cpp
@@ -0,0 +1,1517 @@
+// CFM benchmark that models the vLLM KV-cache call path in the embedded CFM
+// architecture.
+//
+// CFM is a component of every SubMaster; there is no standalone CFM Master and
+// no credential. A reporting client observes keys (KV blocks) and sends metric
+// batches over the SubMaster's regular coro_rpc endpoint. The SubMaster merges
+// reports into its local runtime, then every merged report drives a local
+// analysis -> decision -> execution cycle (eviction/prefetch/promotion/
+// admission through the storage-safe handlers) on the keys it owns.
+//
+// This benchmark exercises that path in the following modes:
+//   - embedded (default): an in-process SubMaster runtime plays the owning
+//     CFM component. Reports are delivered in-process; the runtime's
+//     report-driven worker executes policy per report, and a final manual
+//     Execute emulates the production high-watermark trigger, so the benchmark
+//     prints report latency and the resulting eviction/prefetch/admission
+//     handler activity.
+//   - remote (--cfm_endpoint=host:port): reports go over coro_rpc to a single
+//     SubMaster CFM receiver.
+//   - remote via etcd (--cfm_endpoint=etcd://connstring): resolves the cluster
+//     like a Store client, then buckets each key to its owning SubMaster.
+//     The receiving side is not observable here, so only client-side latency
+//     is reported.
+//
+// Remote policy execution is only observable when the SubMaster actually owns
+// the reported keys: its eviction/promotion/prefetch handlers operate on real
+// replicas, so a report-only run leaves the master-side counters at zero. When
+// --master_server and --num_keys are provided, a real-data seeding stage runs
+// first ("先种子后仿真"): it writes a batch of real KV objects through
+// RealClient (keys share the simulated KvKey naming and tenant) and reads a
+// subset back to simulate access heat, then the simulated vLLM request stream
+// reports on those same keys.
+
+#include <algorithm>
+#include <atomic>
+#include <chrono>
+#include <cmath>
+#include <cstdint>
+#include <cstdlib>
+#include <cstring>
+#include <iomanip>
+#include <iostream>
+#include <map>
+#include <memory>
+#include <mutex>
+#include <numeric>
+#include <optional>
+#include <set>
+#include <string>
+#include <string_view>
+#include <thread>
+#include <unordered_map>
+#include <utility>
+#include <vector>
+#include <numa.h>
+
+#include "gflags/gflags.h"
+#include "glog/logging.h"
+#include "cvm/cvm_types.h"
+#include "cvm/etcd_view_store.h"
+#include "cvm/slot_hash.h"
+#include "io_pattern/cfm_ownership_client.h"
+#include "io_pattern/cfm_protocol.h"
+#include "io_pattern/cfm_service.h"
+#include "io_pattern/rpc_transport.h"
+#include "io_pattern/runtime.h"
+#include "real_client.h"
+#include "types.h"
+#ifdef STORE_USE_ETCD
+#include "etcd_helper.h"
+#endif
+
+namespace {
+
+using Clock = std::chrono::steady_clock;
+using mooncake::ErrorCode;
+using mooncake::TenantId;
+using mooncake::toString;
+using namespace mooncake::io_pattern;
+
+DEFINE_uint64(requests, 20, "Number of vLLM-style inference requests");
+DEFINE_uint64(prompt_tokens, 1024, "Input tokens in each inference request");
+DEFINE_uint64(output_tokens, 128, "Decode tokens in each inference request");
+DEFINE_uint64(tokens_per_block, 16, "Tokens represented by one KV block");
+DEFINE_uint64(num_layers, 32, "Transformer layers represented per request");
+DEFINE_uint64(kv_block_bytes, 256 * 1024,
+              "Bytes in one layer/block KV-cache object");
+DEFINE_uint64(num_sessions, 4, "Independent vLLM request sessions");
+DEFINE_uint64(shared_prefix_tokens, 512,
+              "Per-session prompt prefix reused by later requests");
+DEFINE_uint64(report_capacity, 262144,
+              "Maximum queued IO Pattern observations before reporting");
+DEFINE_uint64(report_flush_wait_ms, 1100,
+              "Grace period for report drain before local policy evaluation");
+DEFINE_double(memory_used_ratio, 0.95,
+              "Reported L1 memory use ratio; >= 0.90 triggers eviction");
+DEFINE_string(tenant, "vllm-benchmark", "Tenant id");
+DEFINE_string(node_id, "vllm-submaster-0",
+              "CFM node/submaster id that owns the reported keys");
+DEFINE_string(cfm_endpoint, "",
+              "Remote SubMaster endpoint: either host:port or an HA entry "
+              "(e.g. etcd://host:2379;host2:2379). Empty uses an embedded "
+              "in-process SubMaster CFM component");
+DEFINE_string(cfm_cluster_namespace, "",
+              "CVM cluster namespace for etcd entry resolution; defaults to "
+              "MC_STORE_CLUSTER_ID or mooncake_cluster (same rule as the "
+              "etcd leader coordinator). When the cluster was started with a "
+              "non-default cluster_id, pass the same value here");
+
+// Real Store client parameters used by the optional real-data seeding stage.
+// Flag names and defaults mirror stress_cluster_bench.cpp so an existing
+// cluster invocation can be reused as-is. Seeding makes the SubMaster hold
+// real replicas for the reported keys, which is what the IO Pattern eviction /
+// promotion / prefetch handlers operate on (without real objects they remain
+// no-ops even when reports trigger policy cycles).
+DEFINE_string(master_server, "",
+              "Master server address (host:port) for RealClient writes; empty "
+              "disables real-data seeding");
+DEFINE_string(local_hostname, "localhost",
+              "Local hostname (with optional port, e.g. node1:12345)");
+DEFINE_string(metadata_server, "http://127.0.0.1:8080/metadata",
+              "Metadata server URL for RealClient setup");
+DEFINE_string(protocol, "tcp", "Transport protocol: tcp, rdma, ub");
+DEFINE_string(device_name, "", "RDMA/UB device name (comma-separated)");
+DEFINE_uint64(global_segment_size, 16ULL * 1024 * 1024 * 1024,
+              "Global segment size in bytes (per store node)");
+DEFINE_uint64(local_buffer_size, 512ULL * 1024 * 1024,
+              "Local client buffer size in bytes");
+DEFINE_bool(enable_ssd_offload, false,
+            "Enable LOCAL_DISK offload when seeding real keys (requires the "
+            "SubMaster to run with offload enabled)");
+DEFINE_string(ssd_offload_path, "", "SSD offload directory path");
+DEFINE_uint64(num_keys, 0,
+              "Number of real keys to write during seeding (0 = disabled)");
+DEFINE_uint64(value_size, 4ULL * 1024 * 1024,
+              "Size in bytes of each seeded real KV object");
+DEFINE_uint64(replica_num, 1, "Number of replicas for each seeded object");
+DEFINE_bool(hard_pin, false, "Pin seeded objects (disable eviction of them)");
+DEFINE_uint64(seed_get_keys, 0,
+              "How many of the seeded keys to read back with get_into "
+              "(0 = half of num_keys)");
+// Report RPC timeout. A merged report can carry hundreds of thousands of
+// observations; the old fixed 500 ms budget caused report_metric_batch RPC
+// failures on large batches. Also bounds how long the ownership client waits
+// per SubMaster delivery.
+DEFINE_uint64(cfm_rpc_timeout_ms, 5000,
+              "Timeout for each CFM report RPC (report_snapshot / "
+              "report_metric_batch) in milliseconds");
+// Client-side collector/analysis key budget. The default 100k cap drops
+// observations once the simulated request stream exceeds it (seen as nonzero
+// \"report drops\"); raise it to cover the whole run when reporting many keys.
+DEFINE_uint64(
+    max_analysis_keys, 100000,
+    "Max merged keys kept/analyzed by the client runtime and the "
+    "embedded SubMaster runtime (raise with the request stream size)");
+// Remote reports normally omit storage watermarks (the owning SubMaster
+// reports its own); enabling this attaches the reported storage metrics to
+// every owner-addressed snapshot/metric batch so a remote run can drive the
+// report-driven eviction dimension from the client side.
+DEFINE_bool(report_forward_storage, false,
+            "Forward StorageMetric observations with remote owner-addressed "
+            "reports (benchmark/simulation mode)");
+DEFINE_uint64(promotion_test_wait_sec, 0,
+              "When >0: seed keys, wait N seconds for IO Pattern cold eviction "
+              "to offload+cull MEMORY replicas, then re-read the seeded keys "
+              "with get_into to trigger promotion-on-hit. Requires real-data "
+              "seeding (--master-server + --num-keys).");
+DEFINE_uint64(post_promo_evict_wait_sec, 0,
+              "When >0 (and promotion_test_wait_sec>0): after the promotion "
+              "re-read, report ALL seeded keys as cold for N seconds so the "
+              "IO Pattern cold eviction re-evicts the freshly promoted MEMORY "
+              "replicas (S7.5: promoted replicas must be evictable again).");
+DEFINE_bool(admission_test_mode, false,
+            "S8.1: during the promotion-test wait phase report ALL seeded keys "
+            "as cold with LOCAL_DISK replica_tiers so the report-driven cold "
+            "eviction offloads all of them; then send one hot+LOCAL_DISK "
+            "report so the report-driven admission path promotes them "
+            "(master_io_pattern_report_admissions_total increments). Requires "
+            "promotion_test_wait_sec>0, real-data seeding, and a SubMaster "
+            "running with --enable_offload and "
+            "--io_pattern_admission_frequency_threshold=1.");
+DEFINE_string(force_workload_type, "",
+              "Force reported key metrics to match a specific workload type "
+              "for S4 analysis layer testing. Options: code_agent, "
+              "recommendation, conversation. Empty = use original metrics.");
+DEFINE_string(force_session_workload_types, "",
+              "S4.2: comma-separated per-session workload type overrides "
+              "applied to sessions in order (e.g. "
+              "'code_agent,recommendation' makes session 0 report code-agent "
+              "metrics and session 1 report recommendation metrics, forcing "
+              "kMixed -> K-means on the SubMaster). A session index past the "
+              "list falls back to --force_workload_type. Empty = use "
+              "--force_workload_type / original metrics.");
+DEFINE_bool(prefetch_test_mode, false,
+            "S11: report-driven prefetch test. During the promotion-test wait "
+            "phase report ALL seeded keys as cold + LOCAL_DISK so the "
+            "report-driven cold eviction offloads them (same offload as "
+            "admission_test_mode); then send --prefetch_repeat_reports "
+            "hot+LOCAL_DISK trigger reports carrying match_length="
+            "--prefetch_match_length and code-agent metrics, so "
+            "DeriveTraceHistory -> TraceBasedPrefetchOps::Evaluate emits "
+            "LOCAL_DISK -> kL1Host candidates and the master prefetch handler "
+            "pushes them into the promotion queue. Requires "
+            "promotion_test_wait_sec>0, real-data seeding, and a SubMaster "
+            "with --enable_offload and --promotion_on_hit=true.");
+DEFINE_uint64(prefetch_match_length, 1024,
+              "S11: match_length reported by the prefetch trigger. Must exceed "
+              "the workload's prefetch.match_length_threshold (code_agent=512, "
+              "Mixed default 256) for TraceBasedPrefetchOps::Evaluate to emit "
+              "candidates; a value at/below the threshold leaves candidates=0 "
+              "(S11.2).");
+DEFINE_string(prefetch_replica_variant, "local_disk_l1",
+              "S11: replica_tiers reported by the prefetch trigger. "
+              "local_disk_l1 = LOCAL_DISK|L1Host (prefetch fires, admission "
+              "suppressed via in_head), local_disk = LOCAL_DISK only (prefetch "
+              "and admission both fire), l1_only = L1Host only (no lower "
+              "replica, trace empty, candidates=0), l2_only / l3_only = lower "
+              "tier without LOCAL_DISK (in trace but Evaluate skips, "
+              "candidates=0) -- S11.3.");
+DEFINE_uint64(prefetch_repeat_reports, 1,
+              "S11.5: number of identical prefetch trigger reports to send; "
+              "the promotion queue must not grow on the repeats (dedup).");
+DEFINE_bool(prefetch_fake_local_report, false,
+            "S11.6: after the synthetic request stream (no real seeding) send "
+            "one report claiming LOCAL_DISK replicas on keys with no real "
+            "object so the prefetch handler fails "
+            "(UNAVAILABLE_IN_CURRENT_MODE / OBJECT_NOT_FOUND) and "
+            "io_pattern_report_prefetch_failures increments.");
+DEFINE_int32(prefetch_ready_poll_sec, 120,
+             "S11: max seconds to poll the master for ALL seeded keys to hold "
+             "a real LOCAL_DISK replica before sending the prefetch trigger "
+             "reports. The offload driven by the wait phase is asynchronous; "
+             "triggering before it finishes lets the same-cycle fallback "
+             "eviction delete a MEMORY-only key (OpType::REMOVE) so the "
+             "prefetch handler hits OBJECT_NOT_FOUND(-704) and aborts the "
+             "whole plan. Polling get_replica_desc both confirms readiness and "
+             "holds the keys' leases so eviction cannot delete them. 0 "
+             "disables the poll.");
+
+uint64_t SteadyNowNs() {
+    return static_cast<uint64_t>(
+        std::chrono::duration_cast<std::chrono::nanoseconds>(
+            Clock::now().time_since_epoch())
+            .count());
+}
+
+double ToMicroseconds(Clock::duration duration) {
+    return std::chrono::duration<double, std::micro>(duration).count();
+}
+
+size_t BlockCount(uint64_t tokens) {
+    return static_cast<size_t>((tokens + FLAGS_tokens_per_block - 1) /
+                               FLAGS_tokens_per_block);
+}
+
+std::string KvKey(size_t session, size_t request, size_t layer, size_t block,
+                  bool is_shared_prefix) {
+    const auto owner = is_shared_prefix
+                           ? std::string("prefix")
+                           : std::string("request-") + std::to_string(request);
+    return "vllm/" + FLAGS_node_id + "/session-" + std::to_string(session) +
+           "/" + owner + "/layer-" + std::to_string(layer) + "/block-" +
+           std::to_string(block);
+}
+
+// Per-session workload type for S4.2: index into the comma-separated
+// --force_session_workload_types list by session id; fall back to the global
+// --force_workload_type when the list is empty or the session is out of range.
+std::string SessionWorkloadType(size_t session) {
+    const std::string& spec = FLAGS_force_session_workload_types;
+    if (spec.empty()) return FLAGS_force_workload_type;
+    size_t start = 0;
+    size_t index = 0;
+    while (start <= spec.size()) {
+        const size_t comma = spec.find(',', start);
+        const std::string token =
+            spec.substr(start, comma == std::string::npos ? std::string::npos
+                                                          : comma - start);
+        if (index == session) return token;
+        if (comma == std::string::npos) break;
+        start = comma + 1;
+        ++index;
+    }
+    return FLAGS_force_workload_type;
+}
+
+// Sends reports straight into an embedded SubMaster's CFM component. This is
+// the ownership-addressed path collapsed to the single owning SubMaster of a
+// benchmark run, exercised without network.
+class EmbeddedCfmTransport final : public CfmRpcTransport {
+   public:
+    explicit EmbeddedCfmTransport(std::shared_ptr<CfmService> service)
+        : service_(std::move(service)) {}
+
+    bool Send(std::string_view method, std::string_view payload,
+              std::chrono::milliseconds) override {
+        return service_ && service_->Send(method, payload, FLAGS_node_id);
+    }
+
+   private:
+    std::shared_ptr<CfmService> service_;
+};
+
+#ifdef STORE_USE_ETCD
+// Resolves the CVM cluster namespace used by --cfm_endpoint when it carries an
+// etcd:// backend. Mirrors EtcdLeaderCoordinator::ResolveClusterNamespace:
+// explicit flag wins, then MC_STORE_CLUSTER_ID, then mooncake_cluster.
+std::string ResolveCvmNamespace() {
+    if (!FLAGS_cfm_cluster_namespace.empty()) {
+        return FLAGS_cfm_cluster_namespace;
+    }
+    const char* env_cluster_id = std::getenv("MC_STORE_CLUSTER_ID");
+    if (env_cluster_id != nullptr && std::strlen(env_cluster_id) > 0) {
+        return env_cluster_id;
+    }
+    return mooncake::DEFAULT_CLUSTER_ID;
+}
+
+// Key that stores the leader address for single-leader HA.
+// Mirrors EtcdLeaderCoordinator::BuildMasterViewKey.
+std::string BuildMasterViewKey(const std::string& cluster_namespace) {
+    std::string normalized = cluster_namespace;
+    if (!normalized.empty() && normalized.back() == '/') {
+        normalized.pop_back();
+    }
+    return "mooncake-store/" + normalized + "/master_view";
+}
+#endif  // STORE_USE_ETCD
+
+// If --cfm_endpoint names a single SubMaster directly ("host:port") this
+// returns an ownership resolver that routes every key to it. If it is an
+// etcd:// entry, it resolves the cluster like a Store client: a present
+// leader master_view yields a single target; otherwise the CVM
+// /cvm/<ns>/masters registry plus slot ownership is used to bucket keys to
+// their owning SubMaster. Returns an empty resolver on any resolution failure
+// (the caller aborts instead of hanging).
+SubmasterEndpointResolver ResolveCfmEndpointOwnership() {
+    const std::string entry = FLAGS_cfm_endpoint;
+    const size_t scheme_pos = entry.find("://");
+    if (scheme_pos == std::string::npos) {
+        // Plain host:port -> every observed key belongs to this single
+        // SubMaster (the equivalent of the old single-endpoint remote mode).
+        const std::string endpoint = entry;
+        return [endpoint](const TenantId&,
+                          const std::string&) -> std::optional<std::string> {
+            return endpoint;
+        };
+    }
+#ifndef STORE_USE_ETCD
+    LOG(FATAL) << "cfm_endpoint entry '" << entry
+               << "' requires a build with STORE_USE_ETCD; pass host:port "
+                  "instead";
+    return {};
+#else
+    const std::string scheme = entry.substr(0, scheme_pos);
+    if (scheme != "etcd") {
+        LOG(FATAL) << "cfm_endpoint backend '" << scheme
+                   << "' is not supported; use host:port or etcd://connstring";
+        return {};
+    }
+    const std::string connstring = entry.substr(scheme_pos + 3);
+    const std::string cluster_namespace = ResolveCvmNamespace();
+
+    ErrorCode err = mooncake::EtcdHelper::ConnectToEtcdStoreClient(connstring);
+    if (err != ErrorCode::OK) {
+        LOG(FATAL) << "cfm_endpoint: failed to connect etcd '" << connstring
+                   << "': " << toString(err);
+        return {};
+    }
+
+    // Single-leader HA: leader master_view holds the master address.
+    const std::string view_key = BuildMasterViewKey(cluster_namespace);
+    std::string leader_address;
+    mooncake::EtcdRevisionId revision = 0;
+    err = mooncake::EtcdHelper::Get(view_key.data(), view_key.size(),
+                                    leader_address, revision);
+    if (err == ErrorCode::OK && !leader_address.empty()) {
+        LOG(INFO) << "cfm_endpoint: single-leader HA via " << view_key << " -> "
+                  << leader_address;
+        const std::string endpoint = std::move(leader_address);
+        return [endpoint](const TenantId&,
+                          const std::string&) -> std::optional<std::string> {
+            return endpoint;
+        };
+    }
+    if (err != ErrorCode::OK && err != ErrorCode::ETCD_KEY_NOT_EXIST) {
+        LOG(FATAL) << "cfm_endpoint: failed to read " << view_key << ": "
+                   << toString(err);
+        return {};
+    }
+
+    // CVM multi-submaster: masters registry + slot ownership.
+    std::vector<mooncake::cvm::MasterRegistration> masters;
+    mooncake::ViewVersionId version = 0;
+    err = mooncake::cvm::EtcdViewStore::LoadAllMasters(cluster_namespace,
+                                                       masters, version);
+    if (err != ErrorCode::OK) {
+        LOG(FATAL) << "cfm_endpoint: LoadAllMasters failed for namespace '"
+                   << cluster_namespace << "': " << toString(err);
+        return {};
+    }
+
+    std::map<std::string, std::string> address_by_master;  // id -> host:port
+    std::vector<std::string> primary_ids;
+    for (const auto& reg : masters) {
+        if (reg.role ==
+                static_cast<int32_t>(mooncake::cvm::MasterRole::kPrimary) &&
+            !reg.address.empty()) {
+            address_by_master[reg.master_id] = reg.address;
+            primary_ids.push_back(reg.master_id);
+        }
+    }
+    if (primary_ids.empty()) {
+        LOG(FATAL) << "cfm_endpoint: no primary SubMaster registered under "
+                      "/cvm/"
+                   << cluster_namespace << "/masters";
+        return {};
+    }
+    std::sort(primary_ids.begin(), primary_ids.end());
+
+    // Prefer the authoritative slot owner table published by CvmController;
+    // fall back to the consistent-hash ring used by the masters themselves.
+    std::unordered_map<uint16_t, std::string> owner_by_slot;
+    std::vector<mooncake::cvm::SlotOwner> slot_owners;
+    const ErrorCode slot_err = mooncake::cvm::EtcdViewStore::LoadAllSlotOwners(
+        cluster_namespace, slot_owners, version);
+    if (slot_err == ErrorCode::OK) {
+        for (const auto& owner : slot_owners) {
+            if (owner.state ==
+                    static_cast<int32_t>(mooncake::cvm::SlotState::kStable) &&
+                !owner.primary_master_id.empty()) {
+                owner_by_slot[owner.slot] = owner.primary_master_id;
+            }
+        }
+    }
+    const bool has_owner_table = !owner_by_slot.empty();
+    LOG(INFO) << "cfm_endpoint: CVM namespace '" << cluster_namespace
+              << "' has " << primary_ids.size() << " primary submaster(s), "
+              << (has_owner_table ? owner_by_slot.size() : 0) << " slot owners"
+              << (has_owner_table ? "" : " (falling back to hash ring)");
+
+    return [address_by_master = std::move(address_by_master),
+            primary_ids = std::move(primary_ids),
+            owner_by_slot = std::move(owner_by_slot), has_owner_table](
+               const TenantId& tenant,
+               const std::string& key) -> std::optional<std::string> {
+        const uint16_t slot = mooncake::cvm::KeySlot(tenant, key);
+        std::string owner;
+        if (has_owner_table) {
+            const auto it = owner_by_slot.find(slot);
+            if (it != owner_by_slot.end()) owner = it->second;
+        }
+        if (owner.empty()) {
+            owner = mooncake::cvm::ResolveSlotOwnerOnRing(primary_ids, slot);
+        }
+        const auto address = address_by_master.find(owner);
+        if (address == address_by_master.end()) return std::nullopt;
+        return address->second;
+    };
+#endif
+}
+
+class LatencyStats final {
+   public:
+    void Record(double value_us) { values_us_.push_back(value_us); }
+
+    double Percentile(double percentile) const {
+        if (values_us_.empty()) return 0.0;
+        const double rank = percentile / 100.0 * (values_us_.size() - 1);
+        const auto lower = static_cast<size_t>(rank);
+        const auto upper = std::min(lower + 1, values_us_.size() - 1);
+        const double fraction = rank - lower;
+        return values_us_[lower] * (1.0 - fraction) +
+               values_us_[upper] * fraction;
+    }
+
+    void Finalize() { std::sort(values_us_.begin(), values_us_.end()); }
+
+    double Mean() const {
+        if (values_us_.empty()) return 0.0;
+        return std::accumulate(values_us_.begin(), values_us_.end(), 0.0) /
+               values_us_.size();
+    }
+
+   private:
+    std::vector<double> values_us_;
+};
+
+struct MetricReportSnapshot {
+    uint64_t calls{0};
+    uint64_t failures{0};
+    uint64_t observations{0};
+    LatencyStats latency;
+};
+
+class MetricReportStats final {
+   public:
+    void Record(const MetricBatch& batch, double latency_us, bool success) {
+        std::lock_guard lock(mutex_);
+        ++calls;
+        if (!success) ++failures;
+        observations += batch.inference.size() + batch.accesses.size() +
+                        batch.storage.size();
+        latency.Record(latency_us);
+    }
+
+    MetricReportSnapshot Finalize() {
+        std::lock_guard lock(mutex_);
+        latency.Finalize();
+        return {.calls = calls,
+                .failures = failures,
+                .observations = observations,
+                .latency = latency};
+    }
+
+   private:
+    std::mutex mutex_;
+    uint64_t calls{0};
+    uint64_t failures{0};
+    uint64_t observations{0};
+    LatencyStats latency;
+};
+
+struct RequestData {
+    IoPatternSnapshot snapshot;
+    std::vector<InferenceMetrics> inference;
+    std::vector<AccessRecord> accesses;
+};
+
+RequestData BuildRequest(size_t request_index) {
+    const size_t session = request_index % FLAGS_num_sessions;
+    const uint64_t total_tokens = FLAGS_prompt_tokens + FLAGS_output_tokens;
+    const size_t blocks = BlockCount(total_tokens);
+    const size_t shared_blocks =
+        std::min(blocks, BlockCount(FLAGS_shared_prefix_tokens));
+    const bool prefix_is_cached = request_index >= FLAGS_num_sessions;
+    const uint64_t now_ns = SteadyNowNs();
+
+    RequestData request;
+    request.snapshot.generated_at_ns = now_ns;
+    request.inference.reserve(blocks * FLAGS_num_layers);
+    request.accesses.reserve(blocks * FLAGS_num_layers);
+    request.snapshot.keys.reserve(blocks * FLAGS_num_layers);
+    const auto tenant = TenantId(FLAGS_tenant);
+    const auto session_id = "vllm-session-" + std::to_string(session);
+    const std::string workload_type = SessionWorkloadType(session);
+
+    for (size_t layer = 0; layer < FLAGS_num_layers; ++layer) {
+        for (size_t block = 0; block < blocks; ++block) {
+            const bool is_shared_prefix = block < shared_blocks;
+            const bool is_hit = is_shared_prefix && prefix_is_cached;
+            const ObjectRef object{.tenant_id = tenant,
+                                   .key = KvKey(session, request_index, layer,
+                                                block, is_shared_prefix)};
+            const auto block_end = std::min<uint64_t>(
+                total_tokens, (block + 1) * FLAGS_tokens_per_block);
+            const auto block_tokens = static_cast<uint32_t>(
+                block_end - block * FLAGS_tokens_per_block);
+
+            InferenceMetrics inference{
+                .object = object,
+                .session_id = session_id,
+                .layout = CacheLayout::kLayerFirst,
+                .layout_group = static_cast<uint32_t>(layer),
+                .prefix_depth = static_cast<uint32_t>(shared_blocks),
+                .prefix_fanout = static_cast<uint32_t>(FLAGS_num_sessions),
+                .match_length =
+                    is_hit ? static_cast<uint32_t>(FLAGS_shared_prefix_tokens)
+                           : 0U,
+                .continuous_prefix_length =
+                    is_hit ? static_cast<uint32_t>(FLAGS_shared_prefix_tokens)
+                           : 0U,
+                .token_count = block_tokens,
+                .recompute_cost =
+                    is_hit ? 0.0F : static_cast<float>(block_tokens),
+                .request_priority = 1};
+            AccessRecord access{
+                .object = object,
+                .observed_at_ns = now_ns,
+                .block_size = FLAGS_kv_block_bytes,
+                .latency_us = is_hit ? 20U : 200U,
+                .tier = CacheTier::kL1Host,
+                .operation = is_hit ? IoOperation::kGet : IoOperation::kPut,
+                .is_hit = is_hit,
+                .write_batch_size =
+                    is_hit ? 0U : static_cast<uint32_t>(FLAGS_num_layers),
+                .overwrite = !is_hit && is_shared_prefix};
+            // Override reported metrics for S4 workload type testing
+            if (!workload_type.empty()) {
+                if (workload_type == "code_agent") {
+                    inference.token_count = 16385;
+                    inference.prefix_fanout = 32;
+                    inference.match_length = 512;
+                    access.block_size = 512 * 1024;
+                } else if (workload_type == "recommendation") {
+                    access.block_size = 65536;
+                    access.is_hit = true;
+                } else if (workload_type == "conversation") {
+                    inference.token_count = 8000;
+                    inference.prefix_fanout = 32;
+                    inference.match_length = 512;
+                }
+            }
+            request.inference.push_back(inference);
+            request.accesses.push_back(access);
+            KeyMetrics key_metrics{
+                .object = object,
+                .session_id = session_id,
+                .last_access_time_ns = now_ns,
+                .access_count_window = 3,
+                .block_size = FLAGS_kv_block_bytes,
+                .token_count = block_tokens,
+                .prefix_depth = static_cast<uint32_t>(shared_blocks),
+                .prefix_fanout = static_cast<uint32_t>(FLAGS_num_sessions),
+                .match_length = inference.match_length,
+                .continuous_prefix_length = inference.continuous_prefix_length,
+                .write_batch_size = access.write_batch_size,
+                .write_frequency =
+                    access.operation == IoOperation::kPut ? 1U : 0U,
+                .write_object_size = FLAGS_kv_block_bytes,
+                .recompute_cost = inference.recompute_cost,
+                .overwrite_ratio = access.overwrite ? 1.0F : 0.0F,
+                .replica_tiers = CacheTierBit(CacheTier::kL1Host),
+                .layout = CacheLayout::kLayerFirst,
+                .layout_group = static_cast<uint32_t>(layer),
+                .request_priority = 1,
+                .active = is_hit,
+                .write_burst = !is_hit};
+            if (workload_type == "code_agent") {
+                key_metrics.token_count = 16385;
+                key_metrics.prefix_fanout = 32;
+                key_metrics.match_length = 512;
+                key_metrics.block_size = 512 * 1024;
+            } else if (workload_type == "recommendation") {
+                key_metrics.block_size = 65536;
+                key_metrics.access_count_window = 30;
+                key_metrics.recompute_cost = 0.0F;
+            } else if (workload_type == "conversation") {
+                key_metrics.token_count = 8000;
+                key_metrics.prefix_fanout = 32;
+                key_metrics.match_length = 512;
+            }
+            request.snapshot.keys.push_back(key_metrics);
+        }
+    }
+    request.snapshot.storage.push_back(StorageMetric{
+        .source_id = FLAGS_node_id,
+        .observed_at_ns = now_ns,
+        .tier = CacheTier::kL1Host,
+        .read_bandwidth_bytes_per_sec = 20ULL * 1024 * 1024 * 1024,
+        .write_bandwidth_bytes_per_sec = 10ULL * 1024 * 1024 * 1024,
+        .read_latency_us = 20,
+        .write_latency_us = 200,
+        .used_bytes =
+            static_cast<uint64_t>(FLAGS_memory_used_ratio * 1024 * 1024 * 1024),
+        .capacity_bytes = 1024ULL * 1024 * 1024,
+        .rpc_latency_us = 100,
+        .memory_used_ratio = static_cast<float>(FLAGS_memory_used_ratio)});
+    return request;
+}
+
+void PrintObservability(std::string_view name,
+                        const IoPatternObservabilitySnapshot& metrics) {
+    std::cout << "\n  " << name << " IO Pattern metrics\n"
+              << "    collect max latency:  " << metrics.collect_latency_us
+              << " us\n"
+              << "    analyze max latency:  " << metrics.analyze_latency_us
+              << " us\n"
+              << "    policy decisions:     " << metrics.policy_decisions
+              << " (" << std::fixed << std::setprecision(2)
+              << metrics.policy_decision_qps << " qps)\n"
+              << "    strategy hit rate:    " << metrics.strategy_hit_rate * 100
+              << "%\n"
+              << "    false positive rate:  "
+              << metrics.false_positive_rate * 100 << "%\n"
+              << "    degraded:             " << metrics.degrade_count << "\n"
+              << "    report drops:         " << metrics.report_drop_count
+              << "\n";
+}
+
+bool ValidateFlags() {
+    return FLAGS_requests != 0 &&
+           FLAGS_prompt_tokens + FLAGS_output_tokens != 0 &&
+           FLAGS_tokens_per_block != 0 && FLAGS_num_layers != 0 &&
+           FLAGS_kv_block_bytes != 0 && FLAGS_num_sessions != 0 &&
+           FLAGS_report_capacity != 0 && FLAGS_memory_used_ratio >= 0.0 &&
+           FLAGS_memory_used_ratio <= 1.0;
+}
+
+// Real-data seeding stage (optional). The IO Pattern runtime on the SubMaster
+// only executes storage handlers against replicas that actually exist, so a
+// report-only benchmark leaves master-side eviction/promotion/prefetch counters
+// at zero. When --master_server and --num_keys are provided this stage writes a
+// batch of real KV objects through RealClient (same key/tenant naming as the
+// simulated requests, so the analysis snapshot and the real metadata overlap)
+// and reads a subset back to simulate access heat.
+struct SeedStats {
+    uint64_t written{0};
+    uint64_t write_failures{0};
+    uint64_t reads{0};
+    uint64_t read_failures{0};
+};
+
+// Captures what the seeding stage actually created so the reporting stage can
+// address exactly the real keys (a report stream over synthetic keys whose
+// objects were never stored leaves the SubMaster handlers with nothing to act
+// on, which shows up as OBJECT_NOT_FOUND / zero master-side evictions).
+struct SeedOutcome {
+    SeedStats stats;
+    std::vector<std::string> keys;  // real keys written, stable order
+    std::vector<bool> hot;          // parallel: read back (access heat)
+};
+
+SeedOutcome RunRealSeedStage() {
+    SeedOutcome outcome;
+    if (FLAGS_master_server.empty() || FLAGS_num_keys == 0 ||
+        FLAGS_value_size == 0) {
+        return outcome;
+    }
+    LOG(INFO) << "Real-data seed stage: master_server=" << FLAGS_master_server
+              << " protocol=" << FLAGS_protocol << " keys=" << FLAGS_num_keys
+              << " value_size=" << FLAGS_value_size
+              << " replica_num=" << FLAGS_replica_num
+              << " offload=" << (FLAGS_enable_ssd_offload ? "yes" : "no");
+
+    auto client = mooncake::RealClient::create();
+    const size_t block_bytes = std::max<size_t>(FLAGS_value_size, 4096);
+    char* buffer = reinterpret_cast<char*>(numa_alloc_local(block_bytes));
+    if (buffer == nullptr) {
+        LOG(ERROR) << "numa_alloc_local failed for seed buffer of "
+                   << block_bytes << " bytes";
+        return outcome;
+    }
+    std::memset(buffer, 0xA5, block_bytes);
+    int ret = client->setup_real(
+        FLAGS_local_hostname, FLAGS_metadata_server, FLAGS_global_segment_size,
+        FLAGS_local_buffer_size, FLAGS_protocol, FLAGS_device_name,
+        FLAGS_master_server, nullptr, "", FLAGS_enable_ssd_offload,
+        FLAGS_ssd_offload_path, FLAGS_tenant);
+    if (ret != 0) {
+        LOG(ERROR) << "setup_real failed: " << ret;
+        numa_free(buffer, block_bytes);
+        return outcome;
+    }
+    ret = client->register_buffer(buffer, block_bytes);
+    if (ret != 0) {
+        LOG(ERROR) << "register_buffer failed: " << ret;
+        numa_free(buffer, block_bytes);
+        return outcome;
+    }
+
+    // Write keys that share the simulated KvKey naming so later reports and
+    // the real metadata address the same objects. Enumerate the same
+    // (session, request, layer, block) space as BuildRequest() and stop after
+    // --num_keys objects, so the seeded set is exactly the head of the
+    // reported key universe (real replicas exist for the keys policy will
+    // select).
+    mooncake::ReplicateConfig config;
+    config.replica_num = static_cast<size_t>(FLAGS_replica_num);
+    config.with_hard_pin = FLAGS_hard_pin;
+    const uint64_t total_tokens = FLAGS_prompt_tokens + FLAGS_output_tokens;
+    const size_t blocks = BlockCount(total_tokens);
+    const size_t shared_blocks =
+        std::min(blocks, BlockCount(FLAGS_shared_prefix_tokens));
+    uint64_t seeded = 0;
+    for (size_t request_index = 0;
+         request_index < FLAGS_requests && seeded < FLAGS_num_keys;
+         ++request_index) {
+        const size_t session = request_index % FLAGS_num_sessions;
+        for (size_t layer = 0;
+             layer < FLAGS_num_layers && seeded < FLAGS_num_keys; ++layer) {
+            for (size_t block = 0; block < blocks && seeded < FLAGS_num_keys;
+                 ++block) {
+                const bool is_shared_prefix = block < shared_blocks;
+                const std::string key = KvKey(session, request_index, layer,
+                                              block, is_shared_prefix);
+                const int put_ret =
+                    client->put_from(key, buffer, FLAGS_value_size, config);
+                if (put_ret == 0) {
+                    ++seeded;
+                    outcome.keys.push_back(key);
+                } else {
+                    ++outcome.stats.write_failures;
+                    LOG(WARNING) << "put_from failed for seed key " << key
+                                 << ": " << put_ret;
+                }
+            }
+        }
+    }
+    outcome.stats.written = seeded;
+
+    // Simulate reads: exercise a hot subset through the real data path so the
+    // SubMaster records real GET access heat (promotion-on-hit when offloaded).
+    // Mark the same prefix of the written key list as hot for the report pass.
+    outcome.hot.assign(outcome.keys.size(), false);
+    const uint64_t read_count =
+        FLAGS_seed_get_keys == 0
+            ? seeded / 2
+            : std::min<uint64_t>(FLAGS_seed_get_keys, seeded);
+    uint64_t read_keys = 0;
+    for (size_t request_index = 0;
+         request_index < FLAGS_requests && read_keys < read_count;
+         ++request_index) {
+        const size_t session = request_index % FLAGS_num_sessions;
+        for (size_t layer = 0;
+             layer < FLAGS_num_layers && read_keys < read_count; ++layer) {
+            for (size_t block = 0; block < blocks && read_keys < read_count;
+                 ++block) {
+                const bool is_shared_prefix = block < shared_blocks;
+                const std::string key = KvKey(session, request_index, layer,
+                                              block, is_shared_prefix);
+                // First get_into: may hit LOCAL_DISK-only replica, triggering
+                // promotion-on-hit if admission gate passes.
+                int64_t got = client->get_into(key, buffer, FLAGS_value_size);
+                if (got >= 0) {
+                    ++outcome.stats.reads;
+                    // Two more get_into calls to raise CountMinSketch frequency
+                    // above promotion_admission_threshold (default 2), which
+                    // makes the promotion admission gate pass on the first hit.
+                    got = client->get_into(key, buffer, FLAGS_value_size);
+                    if (got >= 0) ++outcome.stats.reads;
+                    got = client->get_into(key, buffer, FLAGS_value_size);
+                    if (got >= 0) ++outcome.stats.reads;
+                } else {
+                    ++outcome.stats.read_failures;
+                }
+                if (read_keys < outcome.hot.size()) {
+                    outcome.hot[read_keys] = true;
+                }
+                ++read_keys;
+            }
+        }
+    }
+
+    client->unregister_buffer(buffer);
+    numa_free(buffer, block_bytes);
+    LOG(INFO) << "Real-data seed stage done: written=" << outcome.stats.written
+              << " write_failures=" << outcome.stats.write_failures
+              << " reads=" << outcome.stats.reads
+              << " read_failures=" << outcome.stats.read_failures;
+    return outcome;
+}
+
+}  // namespace
+
+int main(int argc, char* argv[]) {
+    google::InitGoogleLogging(argv[0]);
+    gflags::ParseCommandLineFlags(&argc, &argv, true);
+    if (!ValidateFlags()) {
+        LOG(ERROR) << "All numeric size/count flags must be positive and "
+                      "--memory_used_ratio must be within [0, 1]";
+        return 1;
+    }
+
+    std::atomic<uint64_t> eviction_commands{0};
+    std::atomic<uint64_t> prefetch_commands{0};
+    std::atomic<uint64_t> admission_commands{0};
+
+    // The SubMaster-side CFM component (embedded mode) or the ownership
+    // resolver used by the remote reporter.
+    std::shared_ptr<CfmService> embedded_service;
+    std::shared_ptr<IoPatternRuntime> cfm_runtime;
+    std::shared_ptr<CfmOwnershipClient> ownership_client;
+    std::shared_ptr<CfmRpcChannel> embedded_channel;
+    std::string deployment_description;
+    if (FLAGS_cfm_endpoint.empty()) {
+        deployment_description = "embedded SubMaster (local CFM)";
+        IoPatternRuntime::Config cfm_config;
+        // Merged reports drive local analysis -> decision -> execution (same
+        // worker the production SubMaster runs), so handler counters below
+        // reflect report-triggered policy execution, not only the manual
+        // watermark evaluation at the end of the run.
+        cfm_config.report_driven_execution = true;
+        cfm_config.max_analysis_keys = FLAGS_max_analysis_keys;
+        cfm_runtime = std::make_shared<IoPatternRuntime>(
+            IoPatternRuntime::Handlers{
+                .eviction =
+                    [&eviction_commands](const EvictionPlan&) {
+                        ++eviction_commands;
+                        return ErrorCode::OK;
+                    },
+                .prefetch =
+                    [&prefetch_commands](const PrefetchPlan&) {
+                        ++prefetch_commands;
+                        return ErrorCode::OK;
+                    },
+                .admission =
+                    [&admission_commands](const AdmissionResult&) {
+                        ++admission_commands;
+                        return ErrorCode::OK;
+                    }},
+            std::move(cfm_config));
+        embedded_service = std::make_shared<CfmService>(cfm_runtime);
+        auto transport =
+            std::make_shared<EmbeddedCfmTransport>(embedded_service);
+        embedded_channel = std::make_shared<CfmRpcChannel>(
+            std::move(transport), std::make_shared<CfmBinaryCodec>(),
+            CfmRpcConfig{.timeout = std::chrono::milliseconds(
+                             FLAGS_cfm_rpc_timeout_ms)});
+    } else {
+        const auto resolver = ResolveCfmEndpointOwnership();
+        ownership_client = std::make_shared<CfmOwnershipClient>(
+            resolver, std::chrono::milliseconds(FLAGS_cfm_rpc_timeout_ms));
+        ownership_client->set_forward_storage(FLAGS_report_forward_storage);
+        deployment_description = "remote SubMaster(s) via CFM coro_rpc";
+    }
+
+    // Real-data seeding runs before the simulated request stream ("先种子后仿
+    // 真"): the SubMaster must hold real replicas for reported keys before the
+    // report-driven policy cycle can execute eviction/promotion/prefetch
+    // against them. Only meaningful with a real SubMaster endpoint
+    // (--cfm_endpoint) plus RealClient parameters; otherwise it is a no-op.
+    const SeedOutcome seed_outcome = RunRealSeedStage();
+    const SeedStats& seed_stats = seed_outcome.stats;
+
+    IoPatternRuntime::Config source_config;
+    source_config.report_capacity = FLAGS_report_capacity;
+    source_config.max_analysis_keys = FLAGS_max_analysis_keys;
+    source_config.collector.max_total_keys = FLAGS_max_analysis_keys;
+    MetricReportStats metric_reports;
+    const auto report_metric_batch = [&](const MetricBatch& batch) -> bool {
+        const auto started = Clock::now();
+        const bool success =
+            ownership_client
+                ? ownership_client->ReportMetricBatch(batch) == ErrorCode::OK
+                : (embedded_channel &&
+                   embedded_channel->SendMetricBatch(batch));
+        metric_reports.Record(batch, ToMicroseconds(Clock::now() - started),
+                              success);
+        return success;
+    };
+    source_config.report_sink = report_metric_batch;
+    auto source_runtime = std::make_shared<IoPatternRuntime>(
+        IoPatternRuntime::Handlers{
+            .eviction = [](const EvictionPlan&) { return ErrorCode::OK; },
+            .prefetch = [](const PrefetchPlan&) { return ErrorCode::OK; },
+            .admission = [](const AdmissionResult&) { return ErrorCode::OK; }},
+        source_config);
+
+    const auto send_snapshot = [&](const IoPatternSnapshot& snapshot) -> bool {
+        return ownership_client
+                   ? ownership_client->ReportSnapshot(snapshot) == ErrorCode::OK
+                   : (embedded_channel &&
+                      embedded_channel->SendSnapshot(snapshot));
+    };
+
+    LatencyStats report_latency;
+    uint64_t failed_reports = 0;
+    uint64_t total_blocks = 0;
+    const auto benchmark_start = Clock::now();
+
+    // When a real seed set was written, report exactly those keys (the ones
+    // with real replicas) instead of the synthetic request stream. Synthetic
+    // keys never stored on the SubMaster pollute the merged snapshot: the
+    // policy engine selects coldest candidates from them, and the storage
+    // handler then finds no real object to evict (OBJECT_NOT_FOUND / zero
+    // master-side evictions). The SubMaster's own data path already records
+    // the real PUT/GET heat for the seeded keys, so reporting the same keys
+    // gives the report-driven cycle candidates that actually exist.
+    const bool real_seed_mode = !seed_outcome.keys.empty();
+    size_t seed_report_requests = 0;
+    if (real_seed_mode) {
+        const auto now_ns = SteadyNowNs();
+        const TenantId tenant(FLAGS_tenant);
+        IoPatternSnapshot real_snapshot;
+        real_snapshot.generated_at_ns = now_ns;
+        real_snapshot.keys.reserve(seed_outcome.keys.size());
+        uint64_t hot_blocks = 0;
+        for (size_t i = 0; i < seed_outcome.keys.size(); ++i) {
+            const auto& key = seed_outcome.keys[i];
+            const bool is_hot = seed_outcome.hot[i];
+            const ObjectRef object{.tenant_id = tenant, .key = key};
+            // Hot keys were read back by the seed stage; cold keys carry an
+            // older last_access so the analyzer sees a hot/cold split over the
+            // real set (matching the benchmark's own read pattern).
+            KeyMetrics key_metrics{
+                .object = object,
+                .session_id = "seed-real-keys",
+                .last_access_time_ns = is_hot
+                                           ? now_ns
+                                           : (now_ns > 60'000'000'000ULL
+                                                  ? now_ns - 60'000'000'000ULL
+                                                  : 0ULL),
+                .access_count_window = is_hot ? 4U : 0U,
+                .block_size = FLAGS_value_size,
+                .token_count = 16U,
+                .write_frequency = 1U,
+                .write_object_size = FLAGS_value_size,
+                .replica_tiers = CacheTierBit(CacheTier::kL1Host),
+                .active = is_hot};
+            real_snapshot.keys.push_back(std::move(key_metrics));
+            if (is_hot) ++hot_blocks;
+            // Feed the source runtime too so the client-side printout and the
+            // per-owner report share the same picture.
+            AccessRecord access{
+                .object = object,
+                .observed_at_ns = now_ns,
+                .block_size = FLAGS_value_size,
+                .latency_us = is_hot ? 20U : 200U,
+                .tier = CacheTier::kL1Host,
+                .operation = is_hot ? IoOperation::kGet : IoOperation::kPut,
+                .is_hit = is_hot};
+            source_runtime->RecordAccess(key, access);
+            ++total_blocks;
+        }
+        real_snapshot.storage.push_back(StorageMetric{
+            .source_id = FLAGS_node_id,
+            .observed_at_ns = now_ns,
+            .tier = CacheTier::kL1Host,
+            .read_bandwidth_bytes_per_sec = 20ULL * 1024 * 1024 * 1024,
+            .write_bandwidth_bytes_per_sec = 10ULL * 1024 * 1024 * 1024,
+            .read_latency_us = 20,
+            .write_latency_us = 200,
+            .used_bytes =
+                static_cast<uint64_t>(static_cast<double>(FLAGS_value_size) *
+                                      seed_outcome.keys.size()),
+            .capacity_bytes =
+                static_cast<uint64_t>(FLAGS_num_keys) * FLAGS_value_size,
+            .rpc_latency_us = 100,
+            .memory_used_ratio = static_cast<float>(FLAGS_memory_used_ratio)});
+        const auto report_start = Clock::now();
+        const bool sent = send_snapshot(real_snapshot);
+        report_latency.Record(ToMicroseconds(Clock::now() - report_start));
+        if (!sent) ++failed_reports;
+        seed_report_requests = 1;
+        LOG(INFO) << "Real-seed report sent: keys=" << real_snapshot.keys.size()
+                  << " hot=" << hot_blocks
+                  << " cold=" << real_snapshot.keys.size() - hot_blocks
+                  << " (synthetic request stream skipped)";
+    }
+
+    // Promotion test: wait for IO Pattern cold eviction to cull MEMORY
+    // replicas, then re-read seeded keys to trigger promotion-on-hit.
+    if (FLAGS_promotion_test_wait_sec > 0 && !seed_outcome.keys.empty()) {
+        LOG(INFO) << "[PROMO-TEST] waiting " << FLAGS_promotion_test_wait_sec
+                  << "s for cold eviction, sending reports every 5s...";
+        const auto wait_end =
+            Clock::now() + std::chrono::seconds(FLAGS_promotion_test_wait_sec);
+        while (Clock::now() < wait_end) {
+            const uint64_t now_ns = SteadyNowNs();
+            const TenantId tenant(FLAGS_tenant);
+            IoPatternSnapshot snapshot;
+            snapshot.generated_at_ns = now_ns;
+            for (size_t i = 0; i < seed_outcome.keys.size(); ++i) {
+                // Keep the cold half cold during the wait so the report-driven
+                // cold eviction keeps selecting them (once leases expire) and
+                // offloads them to LOCAL_DISK; the final re-read then hits
+                // LOCAL_DISK-only replicas and triggers promotion-on-hit. In
+                // admission_test_mode / prefetch_test_mode ALL keys are
+                // reported cold + LOCAL_DISK so every seeded key gets
+                // offloaded and becomes a report-driven admission / prefetch
+                // candidate.
+                const bool offload_all =
+                    FLAGS_admission_test_mode || FLAGS_prefetch_test_mode;
+                const bool is_hot = offload_all ? false : seed_outcome.hot[i];
+                snapshot.keys.push_back(KeyMetrics{
+                    .object = {.tenant_id = tenant,
+                               .key = seed_outcome.keys[i]},
+                    .session_id = "promo-test",
+                    .last_access_time_ns =
+                        is_hot ? now_ns
+                               : (now_ns > 60'000'000'000ULL
+                                      ? now_ns - 60'000'000'000ULL
+                                      : 0ULL),
+                    .access_count_window = is_hot ? 3U : 0U,
+                    .block_size = FLAGS_kv_block_bytes,
+                    .token_count = 16,
+                    .prefix_depth = 0,
+                    .prefix_fanout = 1,
+                    .match_length = 0,
+                    .recompute_cost = 0.0F,
+                    .replica_tiers = offload_all
+                                         ? CacheTierBit(CacheTier::kLocalDisk)
+                                         : CacheTierBit(CacheTier::kL1Host),
+                    .request_priority = 1,
+                    .active = is_hot});
+            }
+            snapshot.storage.push_back(
+                StorageMetric{.source_id = FLAGS_node_id,
+                              .observed_at_ns = now_ns,
+                              .tier = CacheTier::kL1Host,
+                              .memory_used_ratio = 0.5F});
+            send_snapshot(snapshot);
+            std::this_thread::sleep_for(std::chrono::seconds(5));
+        }
+        // S8.1: report-driven admission trigger. After the wait all seeded
+        // keys have been offloaded to LOCAL_DISK; report them hot + LOCAL_DISK
+        // so DeriveAdmissionCandidates selects them and the report-driven
+        // admission path promotes them (the promotion counter increments and
+        // the admission observer raises master_io_pattern_report_admissions).
+        // Skipped in prefetch_test_mode so the prefetch trigger below is the
+        // only report-driven dimension observed for S11.
+        if (FLAGS_admission_test_mode && !FLAGS_prefetch_test_mode) {
+            const uint64_t now_ns = SteadyNowNs();
+            const TenantId tenant(FLAGS_tenant);
+            IoPatternSnapshot snapshot;
+            snapshot.generated_at_ns = now_ns;
+            for (size_t i = 0; i < seed_outcome.keys.size(); ++i) {
+                snapshot.keys.push_back(KeyMetrics{
+                    .object = {.tenant_id = tenant,
+                               .key = seed_outcome.keys[i]},
+                    .session_id = "admission-test",
+                    .last_access_time_ns = now_ns,
+                    .access_count_window = 3U,
+                    .block_size = FLAGS_kv_block_bytes,
+                    .token_count = 16,
+                    .prefix_depth = 0,
+                    .prefix_fanout = 1,
+                    .match_length = 0,
+                    .recompute_cost = 0.0F,
+                    .replica_tiers = CacheTierBit(CacheTier::kLocalDisk),
+                    .request_priority = 1,
+                    .active = true});
+            }
+            snapshot.storage.push_back(
+                StorageMetric{.source_id = FLAGS_node_id,
+                              .observed_at_ns = now_ns,
+                              .tier = CacheTier::kL1Host,
+                              .memory_used_ratio = 0.5F});
+            send_snapshot(snapshot);
+            LOG(INFO) << "[ADMISSION-TEST] sent hot+LOCAL_DISK report keys="
+                      << snapshot.keys.size();
+            std::this_thread::sleep_for(std::chrono::seconds(5));
+        }
+        // S11: report-driven prefetch trigger. After the wait all seeded keys
+        // have real LOCAL_DISK replicas (offloaded by the cold-eviction
+        // driver). Report them as active hits carrying a high match_length and
+        // code-agent metrics (RuleConfidence=1.0 >= minimum_confidence=0.6) so
+        // DeriveTraceHistory emits trace events, TraceBasedPrefetchOps::
+        // Evaluate emits LOCAL_DISK -> kL1Host candidates (match-length gate +
+        // confidence gate + LOCAL_DISK source gate), and the master prefetch
+        // handler pushes them into the promotion queue. The replica variant
+        // selects which gates S11.2/S11.3 exercise.
+        if (FLAGS_prefetch_test_mode) {
+            const uint64_t now_ns = SteadyNowNs();
+            const TenantId tenant(FLAGS_tenant);
+            const std::string& variant = FLAGS_prefetch_replica_variant;
+            CacheTierMask tiers = 0;
+            if (variant == "local_disk") {
+                tiers = CacheTierBit(CacheTier::kLocalDisk);
+            } else if (variant == "l1_only") {
+                tiers = CacheTierBit(CacheTier::kL1Host);
+            } else if (variant == "l2_only") {
+                tiers = CacheTierBit(CacheTier::kL2Segment);
+            } else if (variant == "l3_only") {
+                tiers = CacheTierBit(CacheTier::kL3NofSsd);
+            } else {
+                tiers = CacheTierBit(CacheTier::kLocalDisk) |
+                        CacheTierBit(CacheTier::kL1Host);
+            }
+            // S11 readiness gate: the wait phase queues async offloads, so a
+            // trigger sent before they finish lets the same-cycle fallback
+            // eviction delete a MEMORY-only key (OpType::REMOVE). That key is
+            // then still listed as a prefetch candidate and the handler aborts
+            // with OBJECT_NOT_FOUND(-704), which also degrades the policy
+            // engine. Poll get_replica_desc (Query also renews the keys'
+            // leases, so eviction skips them while they drain) until every
+            // seeded key holds a real LOCAL_DISK replica. Keys that are never
+            // ready (already deleted by a fallback eviction) are filtered out
+            // of the trigger report so the prefetch handler only sees objects
+            // that actually exist with a LOCAL_DISK source.
+            std::vector<std::string> prefetch_keys = seed_outcome.keys;
+            if (FLAGS_prefetch_ready_poll_sec > 0 &&
+                !seed_outcome.keys.empty() &&
+                (tiers & CacheTierBit(CacheTier::kLocalDisk)) != 0) {
+                auto wait_client = mooncake::RealClient::create();
+                const int setup_ret = wait_client->setup_real(
+                    FLAGS_local_hostname, FLAGS_metadata_server,
+                    FLAGS_global_segment_size, FLAGS_local_buffer_size,
+                    FLAGS_protocol, FLAGS_device_name, FLAGS_master_server,
+                    nullptr, "", false, "", FLAGS_tenant);
+                if (setup_ret != 0) {
+                    LOG(ERROR) << "[PREFETCH-TEST] setup_real failed for "
+                                  "LOCAL_DISK readiness poll: "
+                               << setup_ret;
+                } else {
+                    const auto poll_start = Clock::now();
+                    const auto poll_end =
+                        poll_start +
+                        std::chrono::seconds(FLAGS_prefetch_ready_poll_sec);
+                    size_t ready = 0;
+                    while (Clock::now() < poll_end) {
+                        ready = 0;
+                        prefetch_keys.clear();
+                        for (const auto& key : seed_outcome.keys) {
+                            const auto descs =
+                                wait_client->get_replica_desc(key);
+                            bool has_local_disk = false;
+                            for (const auto& d : descs) {
+                                if (d.is_local_disk_replica()) {
+                                    has_local_disk = true;
+                                    break;
+                                }
+                            }
+                            if (has_local_disk) {
+                                ++ready;
+                                prefetch_keys.push_back(key);
+                            }
+                        }
+                        const auto elapsed_s =
+                            std::chrono::duration_cast<std::chrono::seconds>(
+                                Clock::now() - poll_start)
+                                .count();
+                        LOG(INFO)
+                            << "[PREFETCH-TEST] local_disk-ready keys=" << ready
+                            << "/" << seed_outcome.keys.size()
+                            << " elapsed_sec=" << elapsed_s;
+                        if (ready == seed_outcome.keys.size()) break;
+                        std::this_thread::sleep_for(std::chrono::seconds(2));
+                    }
+                    if (ready < seed_outcome.keys.size()) {
+                        LOG(WARNING)
+                            << "[PREFETCH-TEST] LOCAL_DISK readiness "
+                               "TIMEOUT: ready="
+                            << ready << "/" << seed_outcome.keys.size()
+                            << " after " << FLAGS_prefetch_ready_poll_sec
+                            << "s; trigger will use only the "
+                               "confirmed-ready keys";
+                    }
+                }
+            }
+            for (uint64_t rep = 0; rep < FLAGS_prefetch_repeat_reports; ++rep) {
+                IoPatternSnapshot snapshot;
+                snapshot.generated_at_ns = now_ns + rep;
+                snapshot.keys.reserve(prefetch_keys.size());
+                for (size_t i = 0; i < prefetch_keys.size(); ++i) {
+                    snapshot.keys.push_back(KeyMetrics{
+                        .object = {.tenant_id = tenant,
+                                   .key = prefetch_keys[i]},
+                        .session_id = "prefetch-test",
+                        .last_access_time_ns = now_ns,
+                        .access_count_window = 3U,
+                        .block_size = 512U * 1024U,
+                        .token_count = 16385U,
+                        .prefix_depth = 0,
+                        .prefix_fanout = 32U,
+                        .match_length =
+                            static_cast<uint32_t>(FLAGS_prefetch_match_length),
+                        .continuous_prefix_length =
+                            static_cast<uint32_t>(FLAGS_prefetch_match_length),
+                        .recompute_cost = 0.0F,
+                        .replica_tiers = tiers,
+                        .request_priority = 1,
+                        .active = true});
+                }
+                snapshot.storage.push_back(
+                    StorageMetric{.source_id = FLAGS_node_id,
+                                  .observed_at_ns = now_ns,
+                                  .tier = CacheTier::kL1Host,
+                                  .memory_used_ratio = 0.5F});
+                send_snapshot(snapshot);
+                LOG(INFO) << "[PREFETCH-TEST] trigger rep=" << rep
+                          << " keys=" << snapshot.keys.size()
+                          << " match_length=" << FLAGS_prefetch_match_length
+                          << " variant=" << variant;
+                std::this_thread::sleep_for(std::chrono::seconds(3));
+            }
+            LOG(INFO) << "[PREFETCH-TEST] triggers done";
+        }
+        LOG(INFO) << "[PROMO-TEST] wait done, re-reading seeded keys...";
+        auto client = mooncake::RealClient::create();
+        const size_t block_bytes = std::max<size_t>(FLAGS_value_size, 4096);
+        char* buffer = reinterpret_cast<char*>(numa_alloc_local(block_bytes));
+        if (buffer) {
+            std::memset(buffer, 0xA5, block_bytes);
+            int ret = client->setup_real(
+                FLAGS_local_hostname, FLAGS_metadata_server,
+                FLAGS_global_segment_size, FLAGS_local_buffer_size,
+                FLAGS_protocol, FLAGS_device_name, FLAGS_master_server, nullptr,
+                "", false, "", FLAGS_tenant);
+            if (ret == 0) ret = client->register_buffer(buffer, block_bytes);
+            if (ret == 0) {
+                uint64_t promo_hits = 0, promo_misses = 0;
+                for (const auto& key : seed_outcome.keys) {
+                    for (int a = 0; a < 5; ++a) {
+                        int64_t got =
+                            client->get_into(key, buffer, FLAGS_value_size);
+                        if (got >= 0)
+                            ++promo_hits;
+                        else
+                            ++promo_misses;
+                    }
+                }
+                LOG(INFO) << "[PROMO-TEST] get_into hits=" << promo_hits
+                          << " misses=" << promo_misses;
+                client->unregister_buffer(buffer);
+            }
+            numa_free(buffer, block_bytes);
+        }
+    }
+
+    // S7.5: after promotion completes, re-mark ALL seeded keys cold so the
+    // report-driven cold eviction must re-evict the freshly promoted MEMORY
+    // replicas (they hold LOCAL_DISK copies, so eviction deletes the MEMORY
+    // replica directly). If promotion leaked pins/refcnts the eviction would
+    // stall on these keys.
+    if (FLAGS_post_promo_evict_wait_sec > 0 && !seed_outcome.keys.empty()) {
+        LOG(INFO) << "[PROMO-RECYCLE] waiting "
+                  << FLAGS_post_promo_evict_wait_sec
+                  << "s reporting all seeded keys cold for re-eviction...";
+        const auto recycle_end =
+            Clock::now() +
+            std::chrono::seconds(FLAGS_post_promo_evict_wait_sec);
+        while (Clock::now() < recycle_end) {
+            const uint64_t now_ns = SteadyNowNs();
+            const TenantId tenant(FLAGS_tenant);
+            IoPatternSnapshot snapshot;
+            snapshot.generated_at_ns = now_ns;
+            for (size_t i = 0; i < seed_outcome.keys.size(); ++i) {
+                snapshot.keys.push_back(KeyMetrics{
+                    .object = {.tenant_id = tenant,
+                               .key = seed_outcome.keys[i]},
+                    .session_id = "promo-recycle",
+                    .last_access_time_ns = now_ns > 60'000'000'000ULL
+                                               ? now_ns - 60'000'000'000ULL
+                                               : 0ULL,
+                    .access_count_window = 0U,
+                    .block_size = FLAGS_kv_block_bytes,
+                    .token_count = 16,
+                    .prefix_depth = 0,
+                    .prefix_fanout = 1,
+                    .match_length = 0,
+                    .recompute_cost = 0.0F,
+                    .replica_tiers = CacheTierBit(CacheTier::kL1Host),
+                    .request_priority = 1,
+                    .active = false});
+            }
+            snapshot.storage.push_back(
+                StorageMetric{.source_id = FLAGS_node_id,
+                              .observed_at_ns = now_ns,
+                              .tier = CacheTier::kL1Host,
+                              .memory_used_ratio = 0.5F});
+            send_snapshot(snapshot);
+            std::this_thread::sleep_for(std::chrono::seconds(5));
+        }
+        LOG(INFO) << "[PROMO-RECYCLE] recycle wait done";
+    }
+
+    for (size_t request_index = 0; request_index < FLAGS_requests;
+         ++request_index) {
+        if (real_seed_mode) break;  // real keys already reported above
+        auto request = BuildRequest(request_index);
+        total_blocks += request.accesses.size();
+        for (size_t i = 0; i < request.inference.size(); ++i) {
+            source_runtime->ReportInferenceMetrics(request.inference[i]);
+            source_runtime->RecordAccess(request.accesses[i].object.key,
+                                         request.accesses[i]);
+        }
+        source_runtime->RecordStorageMetric(request.snapshot.storage.front());
+
+        const auto report_start = Clock::now();
+        const bool sent = send_snapshot(request.snapshot);
+        report_latency.Record(ToMicroseconds(Clock::now() - report_start));
+        if (!sent) ++failed_reports;
+    }
+
+    // S11.6: prefetch failure path. Synthetic keys claim a LOCAL_DISK replica
+    // that does not exist, so the master prefetch handler finds no real object
+    // (kNotFound -> OBJECT_NOT_FOUND) or no LOCAL_DISK source and returns a
+    // non-OK status, which increments io_pattern_report_prefetch_failures.
+    // Real-data seeding must be off for the objects to be absent.
+    if (FLAGS_prefetch_fake_local_report && !real_seed_mode) {
+        const uint64_t now_ns = SteadyNowNs();
+        const TenantId tenant(FLAGS_tenant);
+        for (uint64_t rep = 0; rep < FLAGS_prefetch_repeat_reports; ++rep) {
+            IoPatternSnapshot snapshot;
+            snapshot.generated_at_ns = now_ns + rep;
+            const auto source_keys = source_runtime->Snapshot().keys;
+            snapshot.keys.reserve(source_keys.size());
+            for (const auto& key : source_keys) {
+                snapshot.keys.push_back(KeyMetrics{
+                    .object = key.object,
+                    .session_id = "prefetch-fake",
+                    .last_access_time_ns = now_ns,
+                    .access_count_window = 3U,
+                    .block_size = 512U * 1024U,
+                    .token_count = 16385U,
+                    .prefix_depth = 0,
+                    .prefix_fanout = 32U,
+                    .match_length =
+                        static_cast<uint32_t>(FLAGS_prefetch_match_length),
+                    .continuous_prefix_length =
+                        static_cast<uint32_t>(FLAGS_prefetch_match_length),
+                    .recompute_cost = 0.0F,
+                    .replica_tiers = CacheTierBit(CacheTier::kLocalDisk),
+                    .request_priority = 1,
+                    .active = true});
+            }
+            snapshot.storage.push_back(
+                StorageMetric{.source_id = FLAGS_node_id,
+                              .observed_at_ns = now_ns,
+                              .tier = CacheTier::kL1Host,
+                              .memory_used_ratio = 0.1F});
+            send_snapshot(snapshot);
+            LOG(INFO) << "[PREFETCH-TEST] fake LOCAL_DISK report rep=" << rep
+                      << " keys=" << snapshot.keys.size()
+                      << " (no real objects -> handler failure expected)";
+            std::this_thread::sleep_for(std::chrono::seconds(3));
+        }
+    }
+    const auto submission_seconds =
+        std::chrono::duration<double>(Clock::now() - benchmark_start).count();
+
+    // Stop joins the reporter worker and performs its final flush. No new
+    // metric batch can reach the SubMaster after this returns.
+    source_runtime->StopReports();
+    std::this_thread::sleep_for(
+        std::chrono::milliseconds(FLAGS_report_flush_wait_ms));
+
+    // The report-driven worker executes one cycle per merged report. Wait for
+    // it to drain before reading handler counters / snapshots so the printed
+    // numbers are deterministic.
+    if (cfm_runtime && cfm_runtime->report_driven_execution()) {
+        cfm_runtime->WaitForReportDrivenIdle();
+    }
+
+    // Embedded mode: when the report-driven worker is disabled, evaluate and
+    // execute policy once locally (the pre-worker high-watermark trigger that
+    // the production EvictionThreadFunc runs). With report_driven_execution
+    // enabled the runtime already executes a full cycle per merged report, so
+    // this extra pass is skipped to keep the printed handler counters equal to
+    // report-triggered executions only.
+    if (cfm_runtime && !cfm_runtime->report_driven_execution() &&
+        !cfm_runtime->Snapshot().keys.empty()) {
+        const auto capacity = 1024ULL * 1024 * 1024;
+        const auto target = static_cast<uint64_t>(
+            (FLAGS_memory_used_ratio - 0.80F) * static_cast<float>(capacity));
+        const auto status = cfm_runtime->Execute(
+            CacheTier::kL1Host, target > 0 ? target : capacity / 10,
+            TraceHistory{});
+        if (status.eviction != ErrorCode::OK &&
+            status.prefetch != ErrorCode::OK && status.degraded) {
+            LOG(WARNING) << "Local CFM evaluation degraded";
+        }
+    }
+
+    const auto end_to_end_seconds =
+        std::chrono::duration<double>(Clock::now() - benchmark_start).count();
+
+    const auto source_snapshot = source_runtime->Snapshot();
+    const auto source_metrics =
+        source_runtime->ObservabilitySnapshot(end_to_end_seconds);
+    source_runtime.reset();
+    report_latency.Finalize();
+    const auto metric_report_snapshot = metric_reports.Finalize();
+    const auto cfm_snapshot =
+        embedded_service ? embedded_service->Snapshot() : IoPatternSnapshot{};
+    const auto cfm_metrics =
+        embedded_service ? embedded_service->Observability(end_to_end_seconds)
+                         : IoPatternObservabilitySnapshot{};
+
+    std::cout
+        << "\n============================================================\n"
+        << "CFM CLIENT BENCHMARK (vLLM inference request model)\n"
+        << "============================================================\n"
+        << "  CFM deployment:          " << deployment_description << "\n"
+        << "  Real-data seeding:       written=" << seed_stats.written
+        << " (failures=" << seed_stats.write_failures
+        << "), reads=" << seed_stats.reads
+        << " (failures=" << seed_stats.read_failures << ")\n"
+        << "  Requests:                " << FLAGS_requests << "\n"
+        << "  Tokens/request:          "
+        << FLAGS_prompt_tokens + FLAGS_output_tokens
+        << " (prompt=" << FLAGS_prompt_tokens
+        << ", decode=" << FLAGS_output_tokens << ")\n"
+        << "  KV blocks/request:       "
+        << BlockCount(FLAGS_prompt_tokens + FLAGS_output_tokens) *
+               FLAGS_num_layers
+        << " (layers=" << FLAGS_num_layers << ")\n"
+        << "  Total KV blocks:         " << total_blocks << "\n"
+        << "  Request submission time: " << std::fixed << std::setprecision(2)
+        << submission_seconds << " s\n"
+        << "  Submission requests/sec: " << FLAGS_requests / submission_seconds
+        << "\n"
+        << "  End-to-end time:         " << end_to_end_seconds << " s\n"
+        << "\n  CFM SendSnapshot latency\n"
+        << "    failed reports:        " << failed_reports << "\n"
+        << "    mean:                  " << report_latency.Mean() << " us\n"
+        << "    p50 / p90 / p99:       " << report_latency.Percentile(50)
+        << " / " << report_latency.Percentile(90) << " / "
+        << report_latency.Percentile(99) << " us\n"
+        << "\n  CFM report_metric_batch latency\n"
+        << "    calls / failures:      " << metric_report_snapshot.calls
+        << " / " << metric_report_snapshot.failures << "\n"
+        << "    observations:          " << metric_report_snapshot.observations
+        << "\n"
+        << "    mean:                  "
+        << metric_report_snapshot.latency.Mean() << " us\n"
+        << "    p50 / p90 / p99:       "
+        << metric_report_snapshot.latency.Percentile(50) << " / "
+        << metric_report_snapshot.latency.Percentile(90) << " / "
+        << metric_report_snapshot.latency.Percentile(99) << " us\n"
+        << "\n  Local policy handlers executed\n"
+        << "    evictions:             " << eviction_commands << "\n"
+        << "    prefetches:            " << prefetch_commands << "\n"
+        << "    admissions:            " << admission_commands << "\n"
+        << "\n  IO Pattern snapshots\n"
+        << "    client keys / storage: " << source_snapshot.keys.size() << " / "
+        << source_snapshot.storage.size() << "\n";
+    if (embedded_service) {
+        std::cout << "    CFM keys / storage:    " << cfm_snapshot.keys.size()
+                  << " / " << cfm_snapshot.storage.size() << "\n";
+    } else {
+        // Remote execution cannot be read back by the client; observe the
+        // receiving SubMaster's own master admin metrics (`io_pattern_report_*`
+        // in `/metrics` and the periodic "Master Admin Metrics" log) and its
+        // [IO-PATTERN-REPORT-CYCLE] log lines.
+        std::cout
+            << "    CFM keys / storage:    remote endpoint (see SubMaster "
+               "master admin metrics)\n";
+    }
+    PrintObservability("Client", source_metrics);
+    if (embedded_service) PrintObservability("CFM", cfm_metrics);
+    std::cout
+        << "============================================================\n";
+    return failed_reports == 0 ? 0 : 2;
+}
\ No newline at end of file
diff --git a/mooncake-store/benchmarks/vchunk_distributed_bench.cpp b/mooncake-store/benchmarks/vchunk_distributed_bench.cpp
new file mode 100644
index 0000000000..712684ce27
--- /dev/null
+++ b/mooncake-store/benchmarks/vchunk_distributed_bench.cpp
@@ -0,0 +1,229 @@
+#include <gflags/gflags.h>
+#include <glog/logging.h>
+
+#include <algorithm>
+#include <atomic>
+#include <barrier>
+#include <chrono>
+#include <cstdint>
+#include <iostream>
+#include <thread>
+#include <vector>
+
+#include "master_client.h"
+#include "vchunk_client.h"
+#include "vchunk_control_plane.h"
+#include "vchunk_transfer_engine.h"
+
+DEFINE_string(master, "127.0.0.1:50051", "Master RPC address");
+DEFINE_string(routing_etcd, "",
+              "ETCD endpoints used to load the CVM SubMaster route snapshot");
+DEFINE_string(cluster_namespace, "",
+              "CVM cluster namespace; required with --routing_etcd");
+DEFINE_string(metadata, "http://127.0.0.1:8080/metadata",
+              "TransferEngine metadata connection string");
+DEFINE_string(local_server, "vchunk-bench-client:12345",
+              "Unique TransferEngine client endpoint");
+DEFINE_string(protocol, "tcp", "TransferEngine transport protocol");
+DEFINE_bool(auto_discovery, false,
+            "Enable TransferEngine device auto-discovery (normally required "
+            "for RDMA without an explicit device matrix)");
+DEFINE_string(tenant, "vchunk-benchmark", "Tenant id");
+DEFINE_uint64(object_size, 1048576, "Object size in bytes");
+DEFINE_uint64(operations, 1000, "Put/Get/Remove transactions");
+DEFINE_uint32(concurrency, 8, "Concurrent workers");
+DEFINE_uint32(timeout_ms, 30000, "Per-operation timeout");
+
+namespace mooncake {
+namespace {
+using Clock = std::chrono::steady_clock;
+
+class DisabledLegacyPath final : public VChunkLegacyPath {
+   public:
+    ErrorCode Put(const TenantId&, const std::string&, const void*, size_t)
+        override {
+        return ErrorCode::INVALID_PARAMS;
+    }
+    ErrorCode Get(const TenantId&, const std::string&, void*, size_t) override {
+        return ErrorCode::INVALID_PARAMS;
+    }
+    ErrorCode Remove(const TenantId&, const std::string&) override {
+        return ErrorCode::INVALID_PARAMS;
+    }
+};
+
+double Percentile(std::vector<double> values, double percentile) {
+    if (values.empty()) return 0;
+    std::sort(values.begin(), values.end());
+    const auto index = static_cast<size_t>(
+        percentile * static_cast<double>(values.size() - 1));
+    return values[index];
+}
+
+ErrorCode ConfigureRouting(MasterClient& master) {
+    if (FLAGS_routing_etcd.empty() && FLAGS_cluster_namespace.empty()) {
+        return ErrorCode::OK;
+    }
+    if (FLAGS_routing_etcd.empty() || FLAGS_cluster_namespace.empty()) {
+        return ErrorCode::INVALID_PARAMS;
+    }
+    return master.LoadRoutingFromEtcd(FLAGS_routing_etcd,
+                                      FLAGS_cluster_namespace);
+}
+}  // namespace
+}  // namespace mooncake
+
+int main(int argc, char** argv) {
+    gflags::ParseCommandLineFlags(&argc, &argv, true);
+    google::InitGoogleLogging(argv[0]);
+    using namespace mooncake;
+    if (FLAGS_object_size == 0 || FLAGS_operations == 0 ||
+        FLAGS_concurrency == 0 || FLAGS_timeout_ms == 0) {
+        LOG(ERROR) << "benchmark numeric arguments must be greater than zero";
+        return 2;
+    }
+
+    MasterClient master(generate_uuid(), nullptr, FLAGS_tenant);
+    if (const auto error = master.Connect(FLAGS_master);
+        error != ErrorCode::OK) {
+        LOG(ERROR) << "failed to connect master: " << toString(error);
+        return 2;
+    }
+    if (const auto error = ConfigureRouting(master); error != ErrorCode::OK) {
+        LOG(ERROR) << "failed to load SubMaster routing: " << toString(error);
+        return 2;
+    }
+    auto runtime = master.GetVChunkRuntimeInfo();
+    if (!runtime || !runtime->enabled || !runtime->persistent_metadata) {
+        LOG(ERROR) << "master must enable vchunk with persistent ETCD metadata";
+        return 2;
+    }
+    TransferEngine engine(FLAGS_auto_discovery);
+    if (engine.init(FLAGS_metadata, FLAGS_local_server) != 0 ||
+        engine.installTransport(FLAGS_protocol, nullptr) == nullptr) {
+        LOG(ERROR) << "failed to initialize TransferEngine";
+        return 2;
+    }
+    TransferEngineVChunkDataPlane data_plane(engine);
+    DisabledLegacyPath legacy;
+    const TenantId tenant(FLAGS_tenant);
+
+    std::atomic<uint64_t> next{0};
+    std::atomic<uint64_t> succeeded{0};
+    std::atomic<uint64_t> failed{0};
+    std::vector<double> latencies(FLAGS_operations);
+    std::vector<std::thread> workers;
+    workers.reserve(FLAGS_concurrency);
+    std::atomic<bool> setup_failed{false};
+    std::barrier start_barrier(FLAGS_concurrency + 1);
+    std::barrier finish_barrier(FLAGS_concurrency + 1);
+    for (uint32_t worker_id = 0; worker_id < FLAGS_concurrency; ++worker_id) {
+        workers.emplace_back([&, worker_id] {
+            MasterClient worker_master(generate_uuid(), nullptr, FLAGS_tenant);
+            const auto connect_error = worker_master.Connect(FLAGS_master);
+            const auto routing_error =
+                connect_error == ErrorCode::OK
+                    ? ConfigureRouting(worker_master)
+                    : connect_error;
+            RpcVChunkControlPlane control_plane(worker_master);
+            std::vector<uint8_t> source(FLAGS_object_size);
+            std::vector<uint8_t> destination(FLAGS_object_size);
+            const bool source_registered =
+                engine.registerLocalMemory(source.data(), source.size(),
+                                           "cpu:0") == 0;
+            const bool destination_registered =
+                engine.registerLocalMemory(destination.data(),
+                                           destination.size(), "cpu:0") == 0;
+            if (!source_registered || !destination_registered ||
+                routing_error != ErrorCode::OK) {
+                setup_failed.store(true);
+            }
+            start_barrier.arrive_and_wait();
+            if (setup_failed.load()) {
+                finish_barrier.arrive_and_wait();
+                if (source_registered)
+                    engine.unregisterLocalMemory(source.data());
+                if (destination_registered)
+                    engine.unregisterLocalMemory(destination.data());
+                return;
+            }
+            VChunkClient client(
+                true, control_plane, data_plane, legacy,
+                std::chrono::milliseconds(FLAGS_timeout_ms),
+                [] { return getCurrentTimeInMilli(); });
+            while (true) {
+                const auto operation = next.fetch_add(1);
+                if (operation >= FLAGS_operations) break;
+                for (size_t i = 0; i < source.size(); ++i) {
+                    source[i] = static_cast<uint8_t>((operation + i) & 0xff);
+                }
+                const auto key = "distributed-" +
+                                 std::to_string(worker_id) + "-" +
+                                 std::to_string(operation);
+                const auto operation_started = Clock::now();
+                auto error = client.Put(tenant, key, source.data(),
+                                        source.size());
+                if (error == ErrorCode::OK) {
+                    error = client.Get(tenant, key, destination.data(),
+                                       destination.size());
+                }
+                const bool data_matches = destination == source;
+                const auto remove_error = client.Remove(tenant, key);
+                latencies[operation] =
+                    std::chrono::duration<double, std::micro>(
+                        Clock::now() - operation_started)
+                        .count();
+                if (error == ErrorCode::OK && data_matches &&
+                    remove_error == ErrorCode::OK) {
+                    succeeded.fetch_add(1);
+                } else {
+                    failed.fetch_add(1);
+                }
+            }
+            finish_barrier.arrive_and_wait();
+            engine.unregisterLocalMemory(source.data());
+            engine.unregisterLocalMemory(destination.data());
+        });
+    }
+    start_barrier.arrive_and_wait();
+    const auto started = Clock::now();
+    finish_barrier.arrive_and_wait();
+    const auto finished = Clock::now();
+    for (auto& worker : workers) worker.join();
+    if (setup_failed.load()) {
+        LOG(ERROR) << "failed to register benchmark buffers";
+        return 2;
+    }
+    const auto seconds =
+        std::chrono::duration<double>(finished - started).count();
+    latencies.resize(static_cast<size_t>(next.load() > FLAGS_operations
+                                             ? FLAGS_operations
+                                             : next.load()));
+    const double gib = static_cast<double>(succeeded.load()) *
+                       static_cast<double>(FLAGS_object_size) * 2.0 /
+                       (1024.0 * 1024.0 * 1024.0);
+    std::cout << "{\n"
+              << "  \"production_equivalent_data_plane\": true,\n"
+              << "  \"master_rpc\": \"" << FLAGS_master << "\",\n"
+              << "  \"submaster_routing\": "
+              << (!FLAGS_routing_etcd.empty() ? "true" : "false") << ",\n"
+              << "  \"cluster_namespace\": \"" << FLAGS_cluster_namespace
+              << "\",\n"
+              << "  \"transfer_protocol\": \"" << FLAGS_protocol << "\",\n"
+              << "  \"auto_discovery\": "
+              << (FLAGS_auto_discovery ? "true" : "false") << ",\n"
+              << "  \"object_size_bytes\": " << FLAGS_object_size << ",\n"
+              << "  \"concurrency\": " << FLAGS_concurrency << ",\n"
+              << "  \"operations\": " << FLAGS_operations << ",\n"
+              << "  \"succeeded\": " << succeeded.load() << ",\n"
+              << "  \"failed\": " << failed.load() << ",\n"
+              << "  \"duration_seconds\": " << seconds << ",\n"
+              << "  \"transactions_per_second\": "
+              << succeeded.load() / seconds << ",\n"
+              << "  \"data_gib_per_second\": " << gib / seconds << ",\n"
+              << "  \"latency_p50_us\": " << Percentile(latencies, 0.50)
+              << ",\n"
+              << "  \"latency_p99_us\": " << Percentile(latencies, 0.99)
+              << "\n}\n";
+    return failed.load() == 0 && succeeded.load() == FLAGS_operations ? 0 : 1;
+}
diff --git a/mooncake-store/conf/master.json b/mooncake-store/conf/master.json
index f55bdaf2b2..01757fdc2d 100644
--- a/mooncake-store/conf/master.json
+++ b/mooncake-store/conf/master.json
@@ -15,6 +15,14 @@
   "enable_ha": false,
   "enable_oplog": false,
   "etcd_endpoints": "http://localhost:2379",
+  "enable_vchunk": false,
+  "vchunk_etcd_endpoints": "",
+  "vchunk_creating_timeout_ms": 30000,
+  "vchunk_releasing_timeout_ms": 60000,
+  "vchunk_max_slice_retry": 3,
+  "vchunk_max_slice_count": 4096,
+  "vchunk_max_metadata_bytes": 1048576,
+  "vchunk_max_creating_objects": 1024,
   "root_fs_dir": "",
   "cluster_id": "mooncake_cluster",
   "memory_allocator": "offset",
diff --git a/mooncake-store/conf/master.yaml b/mooncake-store/conf/master.yaml
index 545807008f..7f9bfd7f94 100644
--- a/mooncake-store/conf/master.yaml
+++ b/mooncake-store/conf/master.yaml
@@ -21,6 +21,16 @@ tenant_quota_connector_uri: ""
 
 enable_ha: false
 etcd_endpoints: "http://localhost:2379"
+# Distributed vchunk validation path. Keep disabled for the community path.
+enable_vchunk: false
+# Empty means reuse etcd_endpoints.
+vchunk_etcd_endpoints: ""
+vchunk_creating_timeout_ms: 30000
+vchunk_releasing_timeout_ms: 60000
+vchunk_max_slice_retry: 3
+vchunk_max_slice_count: 4096
+vchunk_max_metadata_bytes: 1048576
+vchunk_max_creating_objects: 1024
 root_fs_dir: ""
 cluster_id: "mooncake_cluster"
 memory_allocator: "offset"
diff --git a/mooncake-store/graphify-out/cache/stat-index.json b/mooncake-store/graphify-out/cache/stat-index.json
new file mode 100644
index 0000000000..26f3fefc57
--- /dev/null
+++ b/mooncake-store/graphify-out/cache/stat-index.json
@@ -0,0 +1 @@
+{"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\AGENTS.md":{"size":629,"mtime_ns":1786963737729753600,"word_count":89},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\CMakeLists.txt":{"size":3012,"mtime_ns":1786963737730754700,"word_count":175},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\benchmarks\\CMakeLists.txt":{"size":3960,"mtime_ns":1788421144221545100,"word_count":247},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\benchmarks\\README.md":{"size":3145,"mtime_ns":1786963737730754700,"word_count":367},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\benchmarks\\allocation_strategy_bench.cpp":{"size":79226,"mtime_ns":1786963737731754800,"word_count":7249},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\benchmarks\\allocator_bench.cpp":{"size":11232,"mtime_ns":1786963737731754800,"word_count":1091},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\benchmarks\\batch_evict_bench.cpp":{"size":18064,"mtime_ns":1786963737732754700,"word_count":1293},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\benchmarks\\batch_get_replica_bench.cpp":{"size":28446,"mtime_ns":1786963737732754700,"word_count":2261},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\benchmarks\\batch_remove_benchmark.py":{"size":14812,"mtime_ns":1781678985149681300,"word_count":1186},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\benchmarks\\cluster_mooncake_diag.py":{"size":97859,"mtime_ns":1786976645759111200,"word_count":8162},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\benchmarks\\file_interface_bench.cpp":{"size":34867,"mtime_ns":1781678985149681300,"word_count":3178},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\benchmarks\\master_bench.cpp":{"size":19966,"mtime_ns":1786963737733754900,"word_count":1578},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\benchmarks\\nof_worker_pool_bench.cpp":{"size":40711,"mtime_ns":1786976645759111200,"word_count":3092},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\benchmarks\\oplog_batch_bench.cpp":{"size":13726,"mtime_ns":1786963737733754900,"word_count":993},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\benchmarks\\report_oplog_batch.py":{"size":7146,"mtime_ns":1786963737733754900,"word_count":512},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\benchmarks\\run_oplog_batch_sweep.py":{"size":7127,"mtime_ns":1786963737733754900,"word_count":475},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\benchmarks\\storage_backend_bench.cpp":{"size":94331,"mtime_ns":1781678985150683700,"word_count":8403},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\benchmarks\\store_connector_bench.cpp":{"size":19331,"mtime_ns":1788421144221545100,"word_count":1730},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\benchmarks\\store_kv_bench.md":{"size":5588,"mtime_ns":1781678985150683700,"word_count":695},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\benchmarks\\store_kv_bench.py":{"size":58260,"mtime_ns":1786963737735256300,"word_count":4164},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\benchmarks\\stress_cluster_bench.cpp":{"size":74873,"mtime_ns":1788421144221545100,"word_count":6667},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\benchmarks\\stress_cluster_ranges_bench.cpp":{"size":42576,"mtime_ns":1786976645760111100,"word_count":4052},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\benchmarks\\test_report_oplog_batch.py":{"size":3598,"mtime_ns":1786963737736257800,"word_count":197},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\benchmarks\\test_run_oplog_batch_sweep.py":{"size":4288,"mtime_ns":1786963737736257800,"word_count":259},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\benchmarks\\test_store_kv_bench.py":{"size":6253,"mtime_ns":1786963737737258000,"word_count":404},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\benchmarks\\vchunk_distributed_bench.cpp":{"size":10326,"mtime_ns":1788421144221545100,"word_count":800},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\conf\\master.json":{"size":1323,"mtime_ns":1788421144221545100,"word_count":80},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\conf\\master.yaml":{"size":1516,"mtime_ns":1788421144221545100,"word_count":132},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\go\\build.sh":{"size":2932,"mtime_ns":1786963737737258000,"word_count":309},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\go\\examples\\basic\\main.go":{"size":2404,"mtime_ns":1781678985152689000,"word_count":318},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\go\\go.mod":{"size":68,"mtime_ns":1781678985152689000,"word_count":4},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\go\\mooncakestore\\config.go":{"size":1066,"mtime_ns":1781678985153691400,"word_count":141},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\go\\mooncakestore\\errors.go":{"size":1650,"mtime_ns":1786963737738730400,"word_count":180},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\go\\mooncakestore\\store.go":{"size":14159,"mtime_ns":1781678985153691400,"word_count":1791},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\go\\tests\\integration_test.go":{"size":4372,"mtime_ns":1781678985153691400,"word_count":605},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\admission_ops.h":{"size":45,"mtime_ns":1788421144377666800,"word_count":4},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\aligned_client_buffer.h":{"size":2139,"mtime_ns":1786963737738730400,"word_count":257},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\allocation_strategy.h":{"size":31158,"mtime_ns":1786963737738730400,"word_count":2636},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\allocator.h":{"size":12151,"mtime_ns":1786976645760111100,"word_count":1075},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cachelib_memory_allocator\\AllocationClass.h":{"size":20014,"mtime_ns":1786963737739832900,"word_count":2544},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cachelib_memory_allocator\\MemoryAllocator.h":{"size":20451,"mtime_ns":1786963737739832900,"word_count":2689},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cachelib_memory_allocator\\MemoryPool.h":{"size":15290,"mtime_ns":1786963737740834200,"word_count":2098},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cachelib_memory_allocator\\MemoryPoolManager.h":{"size":5543,"mtime_ns":1781678985155735100,"word_count":791},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cachelib_memory_allocator\\Slab.h":{"size":10734,"mtime_ns":1781678985155735100,"word_count":1341},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cachelib_memory_allocator\\SlabAllocator.h":{"size":8189,"mtime_ns":1781678985156737400,"word_count":1056},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cachelib_memory_allocator\\common\\CompilerUtils.h":{"size":2349,"mtime_ns":1781678985156737400,"word_count":286},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cachelib_memory_allocator\\common\\Exceptions.h":{"size":3014,"mtime_ns":1781678985156737400,"word_count":334},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cachelib_memory_allocator\\common\\Throttler.h":{"size":3643,"mtime_ns":1781678985156737400,"word_count":459},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cachelib_memory_allocator\\common\\Time.h":{"size":3123,"mtime_ns":1781678985156737400,"word_count":346},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cachelib_memory_allocator\\common\\Utils.h":{"size":1068,"mtime_ns":1781678985157739700,"word_count":165},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cachelib_memory_allocator\\fake_include\\folly\\logging\\xlog.h":{"size":30964,"mtime_ns":1781678985157739700,"word_count":3245},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cachelib_memory_allocator\\fake_include\\folly\\portability\\Config.h":{"size":1116,"mtime_ns":1781678985157739700,"word_count":145},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cachelib_memory_allocator\\include\\fmt\\args.h":{"size":7699,"mtime_ns":1781678985158742500,"word_count":716},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cachelib_memory_allocator\\include\\fmt\\chrono.h":{"size":43744,"mtime_ns":1781678985158742500,"word_count":4420},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cachelib_memory_allocator\\include\\fmt\\color.h":{"size":24752,"mtime_ns":1781678985158742500,"word_count":2221},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cachelib_memory_allocator\\include\\fmt\\compile.h":{"size":22149,"mtime_ns":1781678985159744700,"word_count":2203},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cachelib_memory_allocator\\include\\fmt\\core.h":{"size":101361,"mtime_ns":1781678985159744700,"word_count":10856},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cachelib_memory_allocator\\include\\fmt\\format-inl.h":{"size":106523,"mtime_ns":1781678985160746500,"word_count":9714},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cachelib_memory_allocator\\include\\fmt\\format.h":{"size":106448,"mtime_ns":1781678985160746500,"word_count":11421},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cachelib_memory_allocator\\include\\fmt\\locale.h":{"size":102,"mtime_ns":1781678985160746500,"word_count":11},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cachelib_memory_allocator\\include\\fmt\\os.h":{"size":15582,"mtime_ns":1781678985161748200,"word_count":1809},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cachelib_memory_allocator\\include\\fmt\\ostream.h":{"size":6152,"mtime_ns":1781678985161748200,"word_count":573},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cachelib_memory_allocator\\include\\fmt\\printf.h":{"size":21091,"mtime_ns":1781678985161748200,"word_count":2222},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cachelib_memory_allocator\\include\\fmt\\ranges.h":{"size":14927,"mtime_ns":1781678985161748200,"word_count":1478},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cachelib_memory_allocator\\include\\fmt\\xchar.h":{"size":9467,"mtime_ns":1781678985162750600,"word_count":794},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cachelib_memory_allocator\\include\\folly\\CPortability.h":{"size":10773,"mtime_ns":1781678985162750600,"word_count":1051},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cachelib_memory_allocator\\include\\folly\\Likely.h":{"size":2195,"mtime_ns":1781678985162750600,"word_count":314},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cachelib_memory_allocator\\include\\folly\\Portability.h":{"size":16275,"mtime_ns":1781678985162750600,"word_count":1906},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cachelib_memory_allocator\\include\\folly\\lang\\Builtin.h":{"size":2198,"mtime_ns":1781678985162750600,"word_count":237},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cfm_client.h":{"size":48,"mtime_ns":1788421144377666800,"word_count":4},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cfm_client_impl.h":{"size":55,"mtime_ns":1788421144492018000,"word_count":4},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\client_buffer.h":{"size":5113,"mtime_ns":1786963737740834200,"word_count":552},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\client_metric.h":{"size":28657,"mtime_ns":1786976645761558400,"word_count":2319},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\client_service.h":{"size":44657,"mtime_ns":1788421144221545100,"word_count":4178},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\collector_impl.h":{"size":54,"mtime_ns":1788421144492018000,"word_count":4},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\config_helper.h":{"size":2756,"mtime_ns":1781678985164755800,"word_count":352},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\count_min_sketch.h":{"size":2847,"mtime_ns":1781678985164755800,"word_count":332},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\crc32c.h":{"size":1348,"mtime_ns":1786963737741834400,"word_count":184},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cvm\\cvm_controller.h":{"size":5947,"mtime_ns":1788421144227958400,"word_count":485},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cvm\\cvm_http_server.h":{"size":1763,"mtime_ns":1788421144227958400,"word_count":132},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cvm\\cvm_keys.h":{"size":3551,"mtime_ns":1788421144227958400,"word_count":298},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cvm\\cvm_service_delegate.h":{"size":1329,"mtime_ns":1788421144227958400,"word_count":177},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cvm\\cvm_types.h":{"size":3902,"mtime_ns":1788421144229244100,"word_count":369},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cvm\\etcd_view_store.h":{"size":7208,"mtime_ns":1788421144229244100,"word_count":546},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cvm\\inter_master_rpc.h":{"size":8136,"mtime_ns":1788421144229244100,"word_count":867},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cvm\\slot_hash.h":{"size":6206,"mtime_ns":1788421144230337600,"word_count":674},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cvm\\slot_migrator.h":{"size":2634,"mtime_ns":1788421144230337600,"word_count":299},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\cvm\\slot_owner_heartbeat.h":{"size":3600,"mtime_ns":1788421144230337600,"word_count":408},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\deadline_scheduler.h":{"size":4366,"mtime_ns":1786963737741834400,"word_count":306},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\degrading_policy_engine.h":{"size":63,"mtime_ns":1788421144492018000,"word_count":4},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\device\\accelerator_device.h":{"size":1495,"mtime_ns":1786963737742939400,"word_count":159},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\device\\accelerator_registry.h":{"size":796,"mtime_ns":1786963737742939400,"word_count":72},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\device\\runtime_accelerator.h":{"size":772,"mtime_ns":1786963737742939400,"word_count":74},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\dummy_client.h":{"size":11336,"mtime_ns":1786963737742939400,"word_count":900},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\engram\\engram_store.h":{"size":2660,"mtime_ns":1781678985164755800,"word_count":309},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\engram\\engram_store_config.h":{"size":552,"mtime_ns":1781678985164755800,"word_count":76},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\etcd_helper.h":{"size":12275,"mtime_ns":1788421144230337600,"word_count":1472},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\eviction_ops.h":{"size":45,"mtime_ns":1788421144377666800,"word_count":4},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\eviction_strategy.h":{"size":3155,"mtime_ns":1781678985165755600,"word_count":278},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\feedback.h":{"size":48,"mtime_ns":1788421144492018000,"word_count":4},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\file_interface.h":{"size":9736,"mtime_ns":1786963737744372300,"word_count":1001},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\file_storage.h":{"size":6514,"mtime_ns":1788421144230337600,"word_count":596},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ha\\common\\redis\\redis_connection.h":{"size":1321,"mtime_ns":1781678985166263700,"word_count":112},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ha\\ha_types.h":{"size":5851,"mtime_ns":1788421144231831000,"word_count":493},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ha\\kv\\etcd_ha_kv_backend.h":{"size":545,"mtime_ns":1786963737745374500,"word_count":50},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ha\\kv\\ha_kv_backend.h":{"size":1031,"mtime_ns":1786963737745374500,"word_count":100},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ha\\leadership\\backends\\etcd\\etcd_leader_coordinator.h":{"size":2693,"mtime_ns":1786963737746760700,"word_count":177},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ha\\leadership\\backends\\k8s\\k8s_leader_coordinator.h":{"size":2345,"mtime_ns":1781678985167265600,"word_count":155},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ha\\leadership\\backends\\redis\\redis_leader_coordinator.h":{"size":3305,"mtime_ns":1781678985167265600,"word_count":210},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ha\\leadership\\leader_coordinator.h":{"size":1284,"mtime_ns":1781678985167265600,"word_count":101},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ha\\leadership\\leader_coordinator_factory.h":{"size":353,"mtime_ns":1781678985168265800,"word_count":29},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ha\\leadership\\leader_label_reconciler.h":{"size":2997,"mtime_ns":1786963737746760700,"word_count":291},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ha\\leadership\\master_service_supervisor.h":{"size":356,"mtime_ns":1781678985168265800,"word_count":33},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ha\\master_metrics_reporter.h":{"size":2974,"mtime_ns":1786976645762816900,"word_count":351},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ha\\oplog\\oplog_applier.h":{"size":2888,"mtime_ns":1786976645764055800,"word_count":312},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ha\\oplog\\oplog_batch_codec.h":{"size":539,"mtime_ns":1786963737747919400,"word_count":41},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ha\\oplog\\oplog_batch_standby_reader.h":{"size":1226,"mtime_ns":1788421144231831000,"word_count":81},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ha\\oplog\\oplog_batch_storage.h":{"size":1301,"mtime_ns":1788421144231831000,"word_count":104},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ha\\oplog\\oplog_batch_types.h":{"size":2033,"mtime_ns":1788421144231831000,"word_count":168},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ha\\oplog\\oplog_test_failpoint.h":{"size":179,"mtime_ns":1786963737747919400,"word_count":20},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ha\\oplog\\oplog_types.h":{"size":1820,"mtime_ns":1786976645764055800,"word_count":150},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ha\\oplog\\ordered_oplog_writer.h":{"size":2033,"mtime_ns":1786963737749323800,"word_count":135},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ha\\snapshot\\catalog\\backends\\embedded\\embedded_snapshot_catalog_store.h":{"size":1058,"mtime_ns":1781678985170791500,"word_count":81},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ha\\snapshot\\catalog\\backends\\redis\\redis_snapshot_catalog_store.h":{"size":1545,"mtime_ns":1781678985170791500,"word_count":110},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ha\\snapshot\\catalog\\snapshot_catalog_store.h":{"size":5587,"mtime_ns":1786976645764055800,"word_count":475},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ha\\snapshot\\catalog_backed_snapshot_provider.h":{"size":584,"mtime_ns":1781678985171793800,"word_count":58},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ha\\snapshot\\master_snapshot_codec.h":{"size":5886,"mtime_ns":1786976645765517900,"word_count":583},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ha\\snapshot\\object\\backends\\local\\local_file_snapshot_object_store.h":{"size":1937,"mtime_ns":1781678985171793800,"word_count":157},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ha\\snapshot\\object\\backends\\s3\\s3_snapshot_object_store.h":{"size":1538,"mtime_ns":1781678985171793800,"word_count":123},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ha\\snapshot\\object\\snapshot_object_store.h":{"size":4680,"mtime_ns":1781678985171793800,"word_count":532},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ha\\snapshot\\snapshot_constants.h":{"size":916,"mtime_ns":1786976645765517900,"word_count":93},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ha\\snapshot\\snapshot_logger.h":{"size":1226,"mtime_ns":1781678985171793800,"word_count":128},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ha\\snapshot\\snapshot_provider.h":{"size":1788,"mtime_ns":1786976645765517900,"word_count":193},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ha\\standby_controller.h":{"size":1641,"mtime_ns":1788421144233316700,"word_count":157},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ha_metric_manager.h":{"size":8826,"mtime_ns":1786963737750325300,"word_count":707},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\hf3fs\\hf3fs.h":{"size":3460,"mtime_ns":1781678985172795700,"word_count":342},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\hot_standby_service.h":{"size":12085,"mtime_ns":1788421144233316700,"word_count":1188},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\http_metadata_server.h":{"size":1693,"mtime_ns":1786963737751598000,"word_count":179},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\hybrid_metric.h":{"size":15710,"mtime_ns":1781678985173797700,"word_count":1131},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\io_pattern.h":{"size":52,"mtime_ns":1788421144378944000,"word_count":4},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\io_pattern\\analyzer.h":{"size":591,"mtime_ns":1788421144378944000,"word_count":59},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\io_pattern\\cfm_channel.h":{"size":1598,"mtime_ns":1788421144627563800,"word_count":147},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\io_pattern\\cfm_client_impl.h":{"size":1121,"mtime_ns":1788421144493421600,"word_count":88},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\io_pattern\\cfm_ingress.h":{"size":872,"mtime_ns":1788421144627563800,"word_count":67},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\io_pattern\\cfm_protocol.h":{"size":923,"mtime_ns":1788421144493421600,"word_count":84},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\io_pattern\\cfm_service.h":{"size":4393,"mtime_ns":1788426179828211900,"word_count":350},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\io_pattern\\client.h":{"size":520,"mtime_ns":1788421144378944000,"word_count":56},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\io_pattern\\collector.h":{"size":692,"mtime_ns":1788421144493421600,"word_count":70},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\io_pattern\\collector_impl.h":{"size":3003,"mtime_ns":1788440556672660100,"word_count":229},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\io_pattern\\degrading_policy_engine.h":{"size":1509,"mtime_ns":1788421144494781100,"word_count":113},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\io_pattern\\feedback.h":{"size":1781,"mtime_ns":1788421144494781100,"word_count":144},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\io_pattern\\io_pattern.h":{"size":1060,"mtime_ns":1788421144634371100,"word_count":56},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\io_pattern\\kmeans_analyzer.h":{"size":938,"mtime_ns":1788440380997173000,"word_count":84},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\io_pattern\\legacy_eviction_ops.h":{"size":635,"mtime_ns":1788421144494781100,"word_count":48},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\io_pattern\\observability.h":{"size":1169,"mtime_ns":1788421144496090400,"word_count":84},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\io_pattern\\ops.h":{"size":1622,"mtime_ns":1788421144496333600,"word_count":179},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\io_pattern\\policy_engine.h":{"size":15132,"mtime_ns":1788421144496333600,"word_count":979},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\io_pattern\\policy_strategies.h":{"size":2102,"mtime_ns":1788421144497337700,"word_count":155},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\io_pattern\\registry.h":{"size":1850,"mtime_ns":1788421144380824800,"word_count":143},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\io_pattern\\reporter.h":{"size":2065,"mtime_ns":1788421144634371100,"word_count":163},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\io_pattern\\resilient_analyzer.h":{"size":1397,"mtime_ns":1788421144497337700,"word_count":118},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\io_pattern\\resilient_cfm_channel.h":{"size":1256,"mtime_ns":1788421144635449700,"word_count":103},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\io_pattern\\rpc_transport.h":{"size":6678,"mtime_ns":1788421144635449700,"word_count":559},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\io_pattern\\runtime.h":{"size":5344,"mtime_ns":1788440557542777000,"word_count":394},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\io_pattern\\sliding_window_analyzer.h":{"size":1837,"mtime_ns":1788421144636607800,"word_count":134},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\io_pattern\\threshold_analyzer.h":{"size":1368,"mtime_ns":1788421144498337300,"word_count":108},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\io_pattern\\tier_executor.h":{"size":1215,"mtime_ns":1788440868041497900,"word_count":86},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\io_pattern\\types.h":{"size":6727,"mtime_ns":1788421144499337400,"word_count":516},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\io_pattern_analyzer.h":{"size":94,"mtime_ns":1788421144499337400,"word_count":6},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\io_pattern_collector.h":{"size":51,"mtime_ns":1788421144380824800,"word_count":4},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\io_pattern_registry.h":{"size":50,"mtime_ns":1788421144382219800,"word_count":4},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\io_pattern_types.h":{"size":47,"mtime_ns":1788421144382219800,"word_count":4},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\k8s_lease_helper.h":{"size":1837,"mtime_ns":1786963737752099900,"word_count":139},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\kv_event\\key_util.h":{"size":992,"mtime_ns":1786963737752099900,"word_count":105},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\kv_event\\kv_event_config.h":{"size":1357,"mtime_ns":1786963737752099900,"word_count":149},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\kv_event\\kv_event_publisher.h":{"size":3873,"mtime_ns":1786963737753101300,"word_count":298},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\legacy_eviction_ops.h":{"size":59,"mtime_ns":1788421144499337400,"word_count":4},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\local_hot_cache.h":{"size":11371,"mtime_ns":1786160474197952500,"word_count":1370},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\master_admin_service.h":{"size":4897,"mtime_ns":1786963737753101300,"word_count":241},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\master_client.h":{"size":39042,"mtime_ns":1788421144234318200,"word_count":3659},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\master_config.h":{"size":72889,"mtime_ns":1788439904229877000,"word_count":4717},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\master_metric_manager.h":{"size":33987,"mtime_ns":1786963737754101400,"word_count":2293},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\master_perf.h":{"size":508,"mtime_ns":1786976645768275400,"word_count":61},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\master_service.h":{"size":119181,"mtime_ns":1788421144637865000,"word_count":10005},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\master_snapshot_manager.h":{"size":4247,"mtime_ns":1786963737755103100,"word_count":298},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\master_snapshot_repository.h":{"size":4236,"mtime_ns":1786963737756103100,"word_count":425},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\memory_alloc.h":{"size":140,"mtime_ns":1781678985175819100,"word_count":12},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\metadata_store.h":{"size":7441,"mtime_ns":1788421144236318000,"word_count":755},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\mmap_arena.h":{"size":3516,"mtime_ns":1781678985175819100,"word_count":391},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\mutex.h":{"size":8930,"mtime_ns":1781678985175819100,"word_count":873},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\observability.h":{"size":53,"mtime_ns":1788421144500336600,"word_count":4},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\offset_allocator\\offset_allocator.h":{"size":17218,"mtime_ns":1786963737756103100,"word_count":1553},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\partition\\kv_hash_map.h":{"size":603,"mtime_ns":1788421144236318000,"word_count":62},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\partition\\partition_router.h":{"size":1346,"mtime_ns":1788421144236318000,"word_count":105},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\pinned_buffer_pool.h":{"size":4319,"mtime_ns":1786963737757223600,"word_count":372},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\pinned_host_buffer.h":{"size":1376,"mtime_ns":1786963737757223600,"word_count":131},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\policy_engine.h":{"size":55,"mtime_ns":1788421144382219800,"word_count":4},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\policy_strategies.h":{"size":59,"mtime_ns":1788421144500336600,"word_count":4},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\prefetch_ops.h":{"size":45,"mtime_ns":1788421144382219800,"word_count":4},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\pyclient.h":{"size":19997,"mtime_ns":1786976645769276700,"word_count":1655},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\random.h":{"size":2660,"mtime_ns":1786963737757223600,"word_count":231},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\real_client.h":{"size":41321,"mtime_ns":1788009798331033800,"word_count":3486},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\replica.h":{"size":25893,"mtime_ns":1786976645770732100,"word_count":2030},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\replica_selection.h":{"size":6874,"mtime_ns":1786963737759606600,"word_count":806},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\reporter.h":{"size":48,"mtime_ns":1788421144500336600,"word_count":4},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\resilient_analyzer.h":{"size":58,"mtime_ns":1788421144501826800,"word_count":4},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\resilient_cfm_channel.h":{"size":61,"mtime_ns":1788421144501826800,"word_count":4},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\rpc_helper.h":{"size":4652,"mtime_ns":1786976645770732100,"word_count":462},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\rpc_service.h":{"size":19067,"mtime_ns":1788421144637865000,"word_count":1350},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\rpc_transport.h":{"size":53,"mtime_ns":1788421144501826800,"word_count":4},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\rpc_types.h":{"size":11159,"mtime_ns":1788421144237318100,"word_count":851},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\segment.h":{"size":22925,"mtime_ns":1788421144237318100,"word_count":1999},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\serialize\\serializer.h":{"size":4779,"mtime_ns":1786963737760606500,"word_count":359},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\serializer.h":{"size":12547,"mtime_ns":1781678985178825800,"word_count":1559},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\shm_helper.h":{"size":1423,"mtime_ns":1786963737761968200,"word_count":159},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\sliding_window_analyzer.h":{"size":63,"mtime_ns":1788421144501826800,"word_count":4},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\spdk\\spdk_wrapper.h":{"size":3550,"mtime_ns":1781678985179829300,"word_count":258},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\ssd_register_client.h":{"size":1232,"mtime_ns":1781678985179829300,"word_count":115},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\standby_state_machine.h":{"size":11769,"mtime_ns":1781678985179829300,"word_count":971},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\storage\\distributed\\distributed_storage_backend.h":{"size":2253,"mtime_ns":1786963737761968200,"word_count":164},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\storage\\distributed\\fs_adapter.h":{"size":3420,"mtime_ns":1781678985180832500,"word_count":334},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\storage\\distributed\\hf3fs_adapter.h":{"size":1868,"mtime_ns":1781678985180832500,"word_count":141},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\storage_backend.h":{"size":72796,"mtime_ns":1788421144238318300,"word_count":7544},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\store_c.h":{"size":5260,"mtime_ns":1781678985180832500,"word_count":410},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\store_rpc_client_io_context.h":{"size":568,"mtime_ns":1786963737762969600,"word_count":43},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\task_manager.h":{"size":7883,"mtime_ns":1781678985181835400,"word_count":627},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\tenant_id.h":{"size":2667,"mtime_ns":1786963737762969600,"word_count":241},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\tenant_quota.h":{"size":4201,"mtime_ns":1786963737762969600,"word_count":323},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\tenant_quota_policy_store.h":{"size":1984,"mtime_ns":1786963737764195500,"word_count":142},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\tenant_quota_sharded.h":{"size":2772,"mtime_ns":1786963737764195500,"word_count":200},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\tenant_quota_sharded_impl.h":{"size":9132,"mtime_ns":1786963737764195500,"word_count":581},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\thread_pool.h":{"size":2271,"mtime_ns":1781678985181835400,"word_count":264},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\threshold_analyzer.h":{"size":60,"mtime_ns":1788421144502828700,"word_count":4},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\tier_executor.h":{"size":53,"mtime_ns":1788421144502828700,"word_count":4},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\transfer_task.h":{"size":21678,"mtime_ns":1786976645774403300,"word_count":1939},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\types.h":{"size":21758,"mtime_ns":1788421144238318300,"word_count":2444},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\uds_transport.h":{"size":2240,"mtime_ns":1786963737765196800,"word_count":203},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\utils.h":{"size":17970,"mtime_ns":1786976645774403300,"word_count":2213},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\utils\\base64.h":{"size":4714,"mtime_ns":1781678985182835000,"word_count":629},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\utils\\file_util.h":{"size":1263,"mtime_ns":1781678985182835000,"word_count":145},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\utils\\s3_helper.h":{"size":2664,"mtime_ns":1781678985183344100,"word_count":204},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\utils\\scoped_vlog_timer.h":{"size":4435,"mtime_ns":1781678985183344100,"word_count":390},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\utils\\type_util.h":{"size":1255,"mtime_ns":1786976645775882200,"word_count":166},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\utils\\zstd_util.h":{"size":8044,"mtime_ns":1781678985183344100,"word_count":564},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\vchunk_allocation_strategy.h":{"size":1567,"mtime_ns":1788421144239424500,"word_count":111},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\vchunk_client.h":{"size":3675,"mtime_ns":1788421144239424500,"word_count":271},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\vchunk_config.h":{"size":1151,"mtime_ns":1788421144239424500,"word_count":90},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\vchunk_control_plane.h":{"size":3011,"mtime_ns":1788421144239424500,"word_count":255},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\vchunk_master_manager.h":{"size":3572,"mtime_ns":1788421144239424500,"word_count":267},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\vchunk_metadata.h":{"size":3019,"mtime_ns":1788421144240919400,"word_count":231},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\vchunk_metadata_store.h":{"size":2176,"mtime_ns":1788421144240919400,"word_count":192},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\vchunk_metrics.h":{"size":2270,"mtime_ns":1788421144240919400,"word_count":173},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\include\\vchunk_transfer_engine.h":{"size":1423,"mtime_ns":1788421144240919400,"word_count":92},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\rust\\CMakeLists.txt":{"size":2712,"mtime_ns":1786963737766493000,"word_count":189},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\rust\\README.md":{"size":4434,"mtime_ns":1786963737767565400,"word_count":494},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\rust\\build.rs":{"size":15856,"mtime_ns":1786963737767565400,"word_count":1197},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\rust\\examples\\basic_usage.rs":{"size":5645,"mtime_ns":1786963737767565400,"word_count":643},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\rust\\examples\\generate_dlopen_bindings.rs":{"size":2078,"mtime_ns":1786963737768775400,"word_count":216},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\rust\\examples\\store_benchmark.rs":{"size":4657,"mtime_ns":1781678985185350300,"word_count":385},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\rust\\src\\error.rs":{"size":2793,"mtime_ns":1786963737768775400,"word_count":370},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\rust\\src\\ffi_dlopen.rs":{"size":9934,"mtime_ns":1786963737768775400,"word_count":1053},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\rust\\src\\generated\\ffi_dlopen_bindings.rs":{"size":15653,"mtime_ns":1786963737768775400,"word_count":1065},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\rust\\src\\lib.rs":{"size":2322,"mtime_ns":1786963737770142200,"word_count":307},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\rust\\src\\store.rs":{"size":27624,"mtime_ns":1786976645775882200,"word_count":2578},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\rust\\tests\\minimal_smoke.rs":{"size":2619,"mtime_ns":1781678985186368700,"word_count":230},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\CMakeLists.txt":{"size":19816,"mtime_ns":1788421144639234500,"word_count":1256},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\aligned_client_buffer.cpp":{"size":6426,"mtime_ns":1786963737771143400,"word_count":544},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\allocator.cpp":{"size":24154,"mtime_ns":1786976645776883700,"word_count":1802},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\cachelib_memory_allocator\\AllocationClass.cpp":{"size":24528,"mtime_ns":1786963737771143400,"word_count":2404},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\cachelib_memory_allocator\\CMakeLists.txt":{"size":479,"mtime_ns":1781678985187370600,"word_count":17},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\cachelib_memory_allocator\\MemoryAllocator.cpp":{"size":10858,"mtime_ns":1786963737772491500,"word_count":1062},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\cachelib_memory_allocator\\MemoryPool.cpp":{"size":13939,"mtime_ns":1786963737772992800,"word_count":1481},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\cachelib_memory_allocator\\MemoryPoolManager.cpp":{"size":4726,"mtime_ns":1781678985188372500,"word_count":514},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\cachelib_memory_allocator\\Slab.cpp":{"size":932,"mtime_ns":1781678985188372500,"word_count":127},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\cachelib_memory_allocator\\SlabAllocator.cpp":{"size":5166,"mtime_ns":1781678985188372500,"word_count":520},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\client_buffer.cpp":{"size":6712,"mtime_ns":1786963737772992800,"word_count":527},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\client_metric.cpp":{"size":8798,"mtime_ns":1786976645776883700,"word_count":718},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\client_service.cpp":{"size":209778,"mtime_ns":1788421144242920700,"word_count":16465},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\cvm\\cvm_controller.cpp":{"size":21148,"mtime_ns":1788421144242920700,"word_count":1545},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\cvm\\cvm_http_server.cpp":{"size":4097,"mtime_ns":1788421144242920700,"word_count":303},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\cvm\\etcd_view_store.cpp":{"size":23996,"mtime_ns":1788421144244220900,"word_count":1874},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\cvm\\inter_master_rpc.cpp":{"size":16952,"mtime_ns":1788421144244220900,"word_count":1252},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\cvm\\slot_migrator.cpp":{"size":11634,"mtime_ns":1788421144244220900,"word_count":849},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\cvm\\slot_owner_heartbeat.cpp":{"size":3042,"mtime_ns":1788421144245222700,"word_count":255},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\device\\accelerator_device.cpp":{"size":696,"mtime_ns":1786963737772992800,"word_count":77},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\device\\accelerator_registry.cpp":{"size":3672,"mtime_ns":1786963737772992800,"word_count":262},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\device\\ascend_accelerator_device.cpp":{"size":3610,"mtime_ns":1786963737772992800,"word_count":287},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\device\\cuda_like_accelerator_device.cpp":{"size":3591,"mtime_ns":1786963737772992800,"word_count":274},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\device\\hip_accelerator_device.cpp":{"size":2709,"mtime_ns":1786963737772992800,"word_count":229},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\device\\runtime_accelerator.cpp":{"size":1851,"mtime_ns":1786963737772992800,"word_count":145},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\device\\sunrise_accelerator_device.cpp":{"size":5723,"mtime_ns":1786963737772992800,"word_count":384},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\dummy_client.cpp":{"size":56320,"mtime_ns":1786963737772992800,"word_count":4231},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\engram\\engram_store.cpp":{"size":12078,"mtime_ns":1781678985190376400,"word_count":1037},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\etcd_helper.cpp":{"size":29363,"mtime_ns":1788421144245222700,"word_count":2212},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\file_storage.cpp":{"size":62632,"mtime_ns":1788421144246222200,"word_count":4961},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\ha\\common\\redis\\redis_connection.cpp":{"size":7247,"mtime_ns":1781678985200926800,"word_count":575},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\ha\\kv\\etcd_ha_kv_backend.cpp":{"size":2984,"mtime_ns":1786963737772992800,"word_count":225},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\ha\\leadership\\backends\\etcd\\etcd_leader_coordinator.cpp":{"size":25917,"mtime_ns":1786976645779883500,"word_count":2261},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\ha\\leadership\\backends\\k8s\\k8s_leader_coordinator.cpp":{"size":15668,"mtime_ns":1786976645779883500,"word_count":1079},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\ha\\leadership\\backends\\redis\\redis_leader_coordinator.cpp":{"size":31018,"mtime_ns":1786976645780883600,"word_count":2119},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\ha\\leadership\\leader_coordinator_factory.cpp":{"size":2006,"mtime_ns":1781678985202984100,"word_count":114},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\ha\\leadership\\master_service_supervisor.cpp":{"size":24871,"mtime_ns":1788421144246222200,"word_count":1799},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\ha\\master_metrics_reporter.cpp":{"size":7444,"mtime_ns":1786976645780883600,"word_count":670},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\ha\\oplog\\oplog_applier.cpp":{"size":10421,"mtime_ns":1788008058567345700,"word_count":838},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\ha\\oplog\\oplog_batch_codec.cpp":{"size":9183,"mtime_ns":1786963737772992800,"word_count":748},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\ha\\oplog\\oplog_batch_standby_reader.cpp":{"size":5475,"mtime_ns":1788421144247222200,"word_count":360},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\ha\\oplog\\oplog_batch_storage.cpp":{"size":12985,"mtime_ns":1788421144247222200,"word_count":1154},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\ha\\oplog\\oplog_batch_types.cpp":{"size":5538,"mtime_ns":1788421144247222200,"word_count":509},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\ha\\oplog\\oplog_test_failpoint.cpp":{"size":3135,"mtime_ns":1786963737772992800,"word_count":326},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\ha\\oplog\\oplog_types.cpp":{"size":1541,"mtime_ns":1786963737772992800,"word_count":130},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\ha\\oplog\\ordered_oplog_writer.cpp":{"size":14881,"mtime_ns":1786976645782157400,"word_count":796},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\ha\\snapshot\\catalog\\backends\\embedded\\embedded_snapshot_catalog_store.cpp":{"size":8687,"mtime_ns":1786976645783405900,"word_count":556},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\ha\\snapshot\\catalog\\backends\\redis\\redis_snapshot_catalog_store.cpp":{"size":12307,"mtime_ns":1786976645783405900,"word_count":835},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\ha\\snapshot\\catalog_backed_snapshot_provider.cpp":{"size":25268,"mtime_ns":1786976645784408300,"word_count":1871},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\ha\\snapshot\\master_snapshot_codec.cpp":{"size":6322,"mtime_ns":1786963737772992800,"word_count":489},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\ha\\snapshot\\object\\backends\\local\\local_file_snapshot_object_store.cpp":{"size":11665,"mtime_ns":1781678985207015300,"word_count":943},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\ha\\snapshot\\object\\backends\\s3\\s3_snapshot_object_store.cpp":{"size":2986,"mtime_ns":1781678985207015300,"word_count":204},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\ha\\snapshot\\object\\snapshot_object_store.cpp":{"size":1061,"mtime_ns":1781678985207015300,"word_count":72},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\ha\\standby_controller.cpp":{"size":13605,"mtime_ns":1788421144248222200,"word_count":816},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\ha_metric_manager.cpp":{"size":17497,"mtime_ns":1786963737772992800,"word_count":971},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\hf3fs\\CMakeLists.txt":{"size":214,"mtime_ns":1781678985208017900,"word_count":8},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\hf3fs\\README.md":{"size":1245,"mtime_ns":1781678985208017900,"word_count":147},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\hf3fs\\hf3fs_file.cpp":{"size":11781,"mtime_ns":1781678985208017900,"word_count":1014},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\hf3fs\\hf3fs_resource_manager.cpp":{"size":2635,"mtime_ns":1781678985208017900,"word_count":212},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\hot_standby_service.cpp":{"size":36915,"mtime_ns":1788421144248222200,"word_count":2792},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\http_metadata_server.cpp":{"size":5754,"mtime_ns":1786963737772992800,"word_count":412},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\io_pattern\\cfm_client_impl.cpp":{"size":1598,"mtime_ns":1788421144639234500,"word_count":107},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\io_pattern\\cfm_ingress.cpp":{"size":2449,"mtime_ns":1788421144640236400,"word_count":207},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\io_pattern\\cfm_protocol.cpp":{"size":17532,"mtime_ns":1788421144504174300,"word_count":1327},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\io_pattern\\cfm_service.cpp":{"size":13096,"mtime_ns":1788441063931337600,"word_count":933},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\io_pattern\\collector_impl.cpp":{"size":11109,"mtime_ns":1788421144640236400,"word_count":755},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\io_pattern\\degrading_policy_engine.cpp":{"size":1992,"mtime_ns":1788421144505176000,"word_count":162},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\io_pattern\\feedback.cpp":{"size":1962,"mtime_ns":1788421144505176000,"word_count":162},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\io_pattern\\kmeans_analyzer.cpp":{"size":6580,"mtime_ns":1788421144505176000,"word_count":533},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\io_pattern\\legacy_eviction_ops.cpp":{"size":1468,"mtime_ns":1788421144505176000,"word_count":108},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\io_pattern\\observability.cpp":{"size":2154,"mtime_ns":1788421144506176100,"word_count":128},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\io_pattern\\policy_strategies.cpp":{"size":9558,"mtime_ns":1788421144641310700,"word_count":705},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\io_pattern\\reporter.cpp":{"size":4519,"mtime_ns":1788421144641310700,"word_count":322},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\io_pattern\\resilient_analyzer.cpp":{"size":1904,"mtime_ns":1788421144506176100,"word_count":164},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\io_pattern\\resilient_cfm_channel.cpp":{"size":2633,"mtime_ns":1788421144641310700,"word_count":205},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\io_pattern\\rpc_transport.cpp":{"size":11308,"mtime_ns":1788421144641310700,"word_count":784},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\io_pattern\\runtime.cpp":{"size":15196,"mtime_ns":1788440558445802800,"word_count":980},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\io_pattern\\sliding_window_analyzer.cpp":{"size":5112,"mtime_ns":1788421144642804600,"word_count":387},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\io_pattern\\threshold_analyzer.cpp":{"size":5870,"mtime_ns":1788421144508611900,"word_count":435},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\io_pattern\\tier_executor.cpp":{"size":1423,"mtime_ns":1788421144508611900,"word_count":101},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\k8s_lease_helper.cpp":{"size":9412,"mtime_ns":1786963737772992800,"word_count":701},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\kv_event\\kv_event_publisher.cpp":{"size":12755,"mtime_ns":1786963737785618600,"word_count":875},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\local_hot_cache.cpp":{"size":19884,"mtime_ns":1786963737785618600,"word_count":1857},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\master.cpp":{"size":88503,"mtime_ns":1788441619317981400,"word_count":5518},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\master_admin_service.cpp":{"size":50115,"mtime_ns":1786963737785618600,"word_count":3061},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\master_client.cpp":{"size":88040,"mtime_ns":1788421144249638700,"word_count":6012},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\master_metric_manager.cpp":{"size":111439,"mtime_ns":1786963737785618600,"word_count":6128},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\master_service.cpp":{"size":575007,"mtime_ns":1788441910616988000,"word_count":38297},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\master_snapshot_manager.cpp":{"size":25216,"mtime_ns":1786963737788969700,"word_count":1810},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\master_snapshot_repository.cpp":{"size":13342,"mtime_ns":1786976645788931900,"word_count":883},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\memory_alloc.cpp":{"size":383,"mtime_ns":1781678985212026200,"word_count":31},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\metadata_store.cpp":{"size":1792,"mtime_ns":1786963737788969700,"word_count":108},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\mmap_arena.cpp":{"size":11119,"mtime_ns":1781678985212026200,"word_count":1152},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\offset_allocator.cpp":{"size":26141,"mtime_ns":1786963737788969700,"word_count":2404},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\partition\\partition_router.cpp":{"size":2990,"mtime_ns":1788421144252639700,"word_count":263},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\posix_file.cpp":{"size":4326,"mtime_ns":1786963737788969700,"word_count":398},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\real_client.cpp":{"size":321095,"mtime_ns":1788421144253639800,"word_count":24409},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\real_client_main.cpp":{"size":7930,"mtime_ns":1786976645789945900,"word_count":404},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\registered_pinned_memory.cpp":{"size":8695,"mtime_ns":1786976645791397500,"word_count":776},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\registered_pinned_memory.h":{"size":2274,"mtime_ns":1786963737788969700,"word_count":172},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\rpc_service.cpp":{"size":97438,"mtime_ns":1788421144646385700,"word_count":5584},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\segment.cpp":{"size":69573,"mtime_ns":1788008058575348000,"word_count":4734},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\serialize\\serializer.cpp":{"size":42113,"mtime_ns":1786976645792398900,"word_count":2631},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\shm_helper.cpp":{"size":5767,"mtime_ns":1786963737788969700,"word_count":511},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\spdk\\CMakeLists.txt":{"size":143,"mtime_ns":1781678985215033200,"word_count":6},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\spdk\\spdk_wrapper.cpp":{"size":16105,"mtime_ns":1781678985215033200,"word_count":1297},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\ssd_register_client.cpp":{"size":5600,"mtime_ns":1781678985215033200,"word_count":527},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\standby_state_machine.cpp":{"size":11520,"mtime_ns":1781678985215033200,"word_count":728},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\storage\\distributed\\distributed_storage_backend.cpp":{"size":12704,"mtime_ns":1786976645793399200,"word_count":990},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\storage\\distributed\\hf3fs_adapter.cpp":{"size":12277,"mtime_ns":1781678985216035500,"word_count":1161},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\storage_backend.cpp":{"size":257419,"mtime_ns":1788421144256353600,"word_count":20971},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\store_c.cpp":{"size":11938,"mtime_ns":1781678985217035500,"word_count":1147},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\store_c_shared.cpp":{"size":940,"mtime_ns":1786963737788969700,"word_count":140},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\task_manager.cpp":{"size":16374,"mtime_ns":1781678985217541100,"word_count":1137},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\tenant_quota.cpp":{"size":14767,"mtime_ns":1786963737788969700,"word_count":1115},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\tenant_quota_policy_store.cpp":{"size":15822,"mtime_ns":1786963737788969700,"word_count":1447},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\thread_pool.cpp":{"size":1143,"mtime_ns":1781678985217541100,"word_count":87},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\transfer_task.cpp":{"size":58102,"mtime_ns":1786976645795398900,"word_count":4785},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\types.cpp":{"size":6149,"mtime_ns":1788421144257354700,"word_count":300},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\uds_transport.cpp":{"size":10398,"mtime_ns":1786963737788969700,"word_count":1012},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\uring_file.cpp":{"size":30791,"mtime_ns":1786976645795398900,"word_count":2696},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\utils.cpp":{"size":28970,"mtime_ns":1786976645796544700,"word_count":2897},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\utils\\file_util.cpp":{"size":4547,"mtime_ns":1781678985218544000,"word_count":387},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\utils\\s3_helper.cpp":{"size":31051,"mtime_ns":1786963737788969700,"word_count":2370},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\utils\\type_util.cpp":{"size":1326,"mtime_ns":1786976645796544700,"word_count":159},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\vchunk_allocation_strategy.cpp":{"size":5666,"mtime_ns":1788421144257354700,"word_count":416},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\vchunk_client.cpp":{"size":12880,"mtime_ns":1788421144257354700,"word_count":885},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\vchunk_config.cpp":{"size":866,"mtime_ns":1788421144257354700,"word_count":89},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\vchunk_control_plane.cpp":{"size":4311,"mtime_ns":1788421144258354800,"word_count":274},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\vchunk_master_manager.cpp":{"size":14332,"mtime_ns":1788421144258354800,"word_count":1095},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\vchunk_metadata.cpp":{"size":6723,"mtime_ns":1788421144258354800,"word_count":491},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\vchunk_metadata_store.cpp":{"size":7636,"mtime_ns":1788421144259354700,"word_count":586},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\vchunk_metrics.cpp":{"size":2383,"mtime_ns":1788421144259354700,"word_count":175},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\src\\vchunk_transfer_engine.cpp":{"size":5609,"mtime_ns":1788421144259354700,"word_count":401},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\CMakeLists.txt":{"size":12942,"mtime_ns":1788421144307204800,"word_count":432},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\allocation_strategy_test.cpp":{"size":44013,"mtime_ns":1786963737788969700,"word_count":3531},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\batch_remove_test.cpp":{"size":13444,"mtime_ns":1781678985220549600,"word_count":1098},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\buffer_allocator_test.cpp":{"size":24161,"mtime_ns":1786976645797603000,"word_count":1794},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\client_buffer_test.cpp":{"size":15733,"mtime_ns":1786963737788969700,"word_count":1425},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\client_integration_test.cpp":{"size":82614,"mtime_ns":1788421144260421400,"word_count":6516},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\client_local_hot_cache_test.cpp":{"size":51492,"mtime_ns":1786963737802609400,"word_count":4775},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\client_metrics_test.cpp":{"size":21394,"mtime_ns":1786963737802609400,"word_count":1354},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\client_storage_backend_test.cpp":{"size":1748,"mtime_ns":1786963737802609400,"word_count":129},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\client_tcp_local_memcpy_test.cpp":{"size":18159,"mtime_ns":1781678985221553100,"word_count":1172},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\cxl_client_integration_test.cpp":{"size":19315,"mtime_ns":1781678985222557200,"word_count":1433},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\deadline_scheduler_test.cpp":{"size":7378,"mtime_ns":1786963737802609400,"word_count":501},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\distributed_object_store_provider.py":{"size":1083,"mtime_ns":1781678985222557200,"word_count":83},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\dummy_client_get_buffer_test.cpp":{"size":26965,"mtime_ns":1786963737802609400,"word_count":2357},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\e2e\\CMakeLists.txt":{"size":2928,"mtime_ns":1788421144261423100,"word_count":148},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\e2e\\chaos_rand_test.cpp":{"size":14954,"mtime_ns":1781678985223561200,"word_count":1385},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\e2e\\chaos_test.cpp":{"size":13407,"mtime_ns":1781678985224564800,"word_count":1203},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\e2e\\chaosctl.cpp":{"size":9795,"mtime_ns":1781678985224564800,"word_count":874},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\e2e\\client_ctl_cases\\case1.txt":{"size":211,"mtime_ns":1781678985224564800,"word_count":43},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\e2e\\client_ctl_cases\\case2.txt":{"size":617,"mtime_ns":1781678985224564800,"word_count":87},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\e2e\\client_runner.cpp":{"size":7008,"mtime_ns":1781678985225567500,"word_count":702},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\e2e\\client_wrapper.cpp":{"size":12085,"mtime_ns":1786963737804326200,"word_count":962},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\e2e\\client_wrapper.h":{"size":4287,"mtime_ns":1786963737804326200,"word_count":449},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\e2e\\clientctl.cpp":{"size":9623,"mtime_ns":1786963737804326200,"word_count":913},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\e2e\\e2e_rand_test.cpp":{"size":6986,"mtime_ns":1781678985226570000,"word_count":648},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\e2e\\e2e_utils.h":{"size":2801,"mtime_ns":1781678985226570000,"word_count":225},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\e2e\\gc_e2e_test.cpp":{"size":22595,"mtime_ns":1788421144261423100,"word_count":2181},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\e2e\\oplog_batch_e2e_test.cpp":{"size":3002,"mtime_ns":1786963737804326200,"word_count":201},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\e2e\\oplog_fault_ctl.sh":{"size":3224,"mtime_ns":1786963737804326200,"word_count":394},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\e2e\\oplog_fault_ctl_test.sh":{"size":1949,"mtime_ns":1786963737804326200,"word_count":209},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\e2e\\oplog_ha_client.cpp":{"size":10776,"mtime_ns":1786963737804326200,"word_count":1031},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\e2e\\process_handler.cpp":{"size":18424,"mtime_ns":1786963737804326200,"word_count":1758},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\e2e\\process_handler.h":{"size":6583,"mtime_ns":1786963737804326200,"word_count":714},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\e2e\\readme.md":{"size":7255,"mtime_ns":1781678985227573000,"word_count":927},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\e2e\\run_nof_heartbeat_tcp_e2e.sh":{"size":8942,"mtime_ns":1781678985227573000,"word_count":812},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\e2e\\run_oplog_batch_cluster.sh":{"size":71362,"mtime_ns":1786963737804326200,"word_count":6265},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\e2e\\run_oplog_batch_cluster_test.sh":{"size":5805,"mtime_ns":1786963737804326200,"word_count":553},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\e2e\\storage_backend_e2e_test.cpp":{"size":14871,"mtime_ns":1781678985227573000,"word_count":1297},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\e2e\\store_client_e2e.py":{"size":3713,"mtime_ns":1781678985227573000,"word_count":291},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\eviction_strategy_test.cpp":{"size":4268,"mtime_ns":1781678985228575500,"word_count":340},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\file_storage_promotion_test.cpp":{"size":17038,"mtime_ns":1781678985228575500,"word_count":1419},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\file_storage_test.cpp":{"size":32959,"mtime_ns":1786976645798653700,"word_count":1951},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\file_util_test.cpp":{"size":4144,"mtime_ns":1781678985228575500,"word_count":330},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\common\\redis\\redis_test_utils.h":{"size":1443,"mtime_ns":1781678985229577800,"word_count":105},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\leadership\\backends\\k8s\\high_availability_k8s_test.cpp":{"size":12997,"mtime_ns":1781678985229577800,"word_count":854},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\leadership\\backends\\redis\\high_availability_redis_test.cpp":{"size":8369,"mtime_ns":1781678985230577500,"word_count":428},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\leadership\\etcd_leader_hang_e2e.sh":{"size":5061,"mtime_ns":1786963737804326200,"word_count":432},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\leadership\\ha_backend_availability_test.cpp":{"size":1974,"mtime_ns":1786963737804326200,"word_count":94},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\leadership\\high_availability_test.cpp":{"size":32969,"mtime_ns":1786963737804326200,"word_count":2154},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\leadership\\high_availability_test_fixture.h":{"size":289,"mtime_ns":1781678985231083700,"word_count":32},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\leadership\\leader_label_reconciler_test.cpp":{"size":5653,"mtime_ns":1786963737804326200,"word_count":373},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\master_service_ha_test.cpp":{"size":169122,"mtime_ns":1788421144262422900,"word_count":8402},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\oplog\\mock_metadata_store.h":{"size":3762,"mtime_ns":1786976645799655300,"word_count":328},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\oplog\\mock_snapshot_provider.h":{"size":1552,"mtime_ns":1786963737804326200,"word_count":122},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\oplog\\oplog_applier_test.cpp":{"size":21124,"mtime_ns":1788008058577713700,"word_count":1393},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\oplog\\oplog_batch_auditor_test.cpp":{"size":6698,"mtime_ns":1786963737804326200,"word_count":474},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\oplog\\oplog_batch_codec_test.cpp":{"size":11961,"mtime_ns":1786963737804326200,"word_count":697},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\oplog\\oplog_batch_standby_reader_test.cpp":{"size":19562,"mtime_ns":1786963737804326200,"word_count":1081},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\oplog\\oplog_batch_storage_test.cpp":{"size":19583,"mtime_ns":1786976645800729500,"word_count":1099},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\oplog\\oplog_test_failpoint_test.cpp":{"size":2343,"mtime_ns":1786963737804326200,"word_count":160},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\oplog\\oplog_types_test.cpp":{"size":731,"mtime_ns":1786963737804326200,"word_count":46},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\oplog\\ordered_oplog_writer_test.cpp":{"size":34474,"mtime_ns":1786976645800729500,"word_count":1962},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\snapshot\\catalog\\backends\\embedded\\embedded_snapshot_catalog_store_test.cpp":{"size":10555,"mtime_ns":1781678985235623400,"word_count":535},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\snapshot\\catalog\\backends\\redis\\redis_snapshot_catalog_store_test.cpp":{"size":8911,"mtime_ns":1781678985235623400,"word_count":494},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\snapshot\\catalog_backed_snapshot_provider_test.cpp":{"size":10540,"mtime_ns":1786963737804326200,"word_count":669},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\snapshot\\master_service_promotion_test_for_snapshot.cpp":{"size":8793,"mtime_ns":1786963737804326200,"word_count":752},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\snapshot\\master_service_ssd_test_for_snapshot.cpp":{"size":20221,"mtime_ns":1786963737804326200,"word_count":1420},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\snapshot\\master_service_test_for_snapshot.cpp":{"size":180575,"mtime_ns":1786976645801828600,"word_count":13831},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\snapshot\\master_service_test_for_snapshot_base.h":{"size":35000,"mtime_ns":1786976645802828400,"word_count":2922},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\snapshot\\master_snapshot_codec_test.cpp":{"size":8747,"mtime_ns":1786976645802828400,"word_count":707},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\snapshot\\object\\backends\\local\\local_file_snapshot_object_store_test.cpp":{"size":5200,"mtime_ns":1781678985238631600,"word_count":338},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\snapshot\\snapshot_child_process_test.cpp":{"size":57516,"mtime_ns":1786976645802828400,"word_count":3627},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\snapshot\\snapshot_test_utils.h":{"size":14692,"mtime_ns":1786963737804326200,"word_count":1007},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\standby\\ha_metric_manager_test.cpp":{"size":8322,"mtime_ns":1786963737818801700,"word_count":462},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\standby\\hot_standby_service_test.cpp":{"size":35627,"mtime_ns":1788421144263423100,"word_count":2327},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\standby\\hot_standby_snapshot_bootstrap_test.cpp":{"size":9842,"mtime_ns":1788421144263423100,"word_count":520},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ha\\standby\\standby_state_machine_test.cpp":{"size":27128,"mtime_ns":1781678985240635800,"word_count":1396},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\health_check_test.cpp":{"size":8991,"mtime_ns":1781678985240635800,"word_count":668},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\host_port_fix_test.cpp":{"size":1619,"mtime_ns":1786963737819303600,"word_count":148},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\http_metadata_server_test.cpp":{"size":3730,"mtime_ns":1786963737820332700,"word_count":270},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\io_pattern_framework_test.cpp":{"size":71756,"mtime_ns":1788426265819429000,"word_count":4116},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ipv6_client_test.cpp":{"size":16051,"mtime_ns":1781678985240635800,"word_count":1489},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\kv_event_publisher_test.cpp":{"size":7605,"mtime_ns":1786963737820332700,"word_count":546},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\master_admin_server_test.cpp":{"size":48242,"mtime_ns":1786963737820332700,"word_count":2794},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\master_metrics_test.cpp":{"size":46882,"mtime_ns":1786963737820332700,"word_count":2756},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\master_service_config_test.cpp":{"size":2716,"mtime_ns":1788421144647877600,"word_count":116},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\master_service_ssd_test.cpp":{"size":39181,"mtime_ns":1786963737820332700,"word_count":2962},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\master_service_tenant_quota_test.cpp":{"size":36942,"mtime_ns":1788008058578788900,"word_count":1985},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\master_service_test.cpp":{"size":349866,"mtime_ns":1788421144264275800,"word_count":24221},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\mmap_arena_fallback_test.cpp":{"size":7309,"mtime_ns":1786963737820332700,"word_count":624},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\mmap_arena_test.cpp":{"size":25793,"mtime_ns":1786963737820332700,"word_count":2726},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\mutex_test.cpp":{"size":7305,"mtime_ns":1781678985243641600,"word_count":595},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\nof_heartbeat_test.cpp":{"size":10163,"mtime_ns":1781678985243641600,"word_count":522},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\non_ha_reconnect_test.cpp":{"size":6743,"mtime_ns":1781678985243641600,"word_count":464},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\object_data_type_test.cpp":{"size":5636,"mtime_ns":1786963737820332700,"word_count":395},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\offload_on_evict_test.cpp":{"size":17359,"mtime_ns":1786963737820332700,"word_count":1501},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\offset_allocator_test.cpp":{"size":66004,"mtime_ns":1786963737820332700,"word_count":5833},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\partition_router_test.cpp":{"size":3066,"mtime_ns":1788421144264275800,"word_count":170},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\posix_file_test.cpp":{"size":5847,"mtime_ns":1781678985244643700,"word_count":529},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\promotion_on_hit_test.cpp":{"size":119415,"mtime_ns":1788421144264275800,"word_count":10724},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\pybind_client_test.cpp":{"size":76773,"mtime_ns":1786963737820332700,"word_count":5711},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\registered_pinned_memory_test.cpp":{"size":3692,"mtime_ns":1786963737820332700,"word_count":299},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\replica_selection_test.cpp":{"size":13142,"mtime_ns":1786963737820332700,"word_count":1029},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\rpc_timeout_test.cpp":{"size":4399,"mtime_ns":1786963737820332700,"word_count":471},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\runtime_accelerator_test.cpp":{"size":3894,"mtime_ns":1786963737820332700,"word_count":294},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\scripts\\setup_dev.sh":{"size":569,"mtime_ns":1781678985245645900,"word_count":77},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\segment_test.cpp":{"size":30651,"mtime_ns":1788008058579789400,"word_count":2197},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\serializer_test.cpp":{"size":7596,"mtime_ns":1786963737820332700,"word_count":549},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\slot_hash_test.cpp":{"size":5527,"mtime_ns":1788421144264275800,"word_count":474},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\ssd_metrics_test.cpp":{"size":16705,"mtime_ns":1781678985246648300,"word_count":1247},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\storage_backend_test.cpp":{"size":206575,"mtime_ns":1788421144264275800,"word_count":14285},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\stress_cluster_benchmark.py":{"size":27143,"mtime_ns":1781678985247650000,"word_count":2199},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\stress_workload_test.cpp":{"size":15129,"mtime_ns":1781678985247650000,"word_count":1413},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\task_executor_test.cpp":{"size":17776,"mtime_ns":1781678985247650000,"word_count":1297},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\task_integration_test.cpp":{"size":57381,"mtime_ns":1781678985248651700,"word_count":4871},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\task_manager_test.cpp":{"size":17356,"mtime_ns":1781678985248651700,"word_count":1060},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\tenant_id_test.cpp":{"size":2200,"mtime_ns":1786963737820332700,"word_count":129},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\tenant_quota_test.cpp":{"size":24636,"mtime_ns":1786963737820332700,"word_count":1464},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\test_server_helpers.h":{"size":10528,"mtime_ns":1786963737820332700,"word_count":667},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\thread_pool_test.cpp":{"size":3903,"mtime_ns":1781678985248651700,"word_count":324},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\transfer_task_test.cpp":{"size":7130,"mtime_ns":1786976645807825700,"word_count":589},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\uds_transport_test.cpp":{"size":8556,"mtime_ns":1786963737820332700,"word_count":591},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\utils\\common.h":{"size":2599,"mtime_ns":1781678985249670600,"word_count":185},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\utils_test.cpp":{"size":9467,"mtime_ns":1786976645807825700,"word_count":838},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\vchunk_allocation_strategy_test.cpp":{"size":4432,"mtime_ns":1788421144264275800,"word_count":295},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\vchunk_client_test.cpp":{"size":16169,"mtime_ns":1788421144264275800,"word_count":1046},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\vchunk_config_test.cpp":{"size":2160,"mtime_ns":1788421144264275800,"word_count":134},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\vchunk_master_manager_test.cpp":{"size":8285,"mtime_ns":1788421144264275800,"word_count":488},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\vchunk_master_service_test.cpp":{"size":6013,"mtime_ns":1788421144264275800,"word_count":314},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\vchunk_metadata_store_test.cpp":{"size":10982,"mtime_ns":1788421144264275800,"word_count":652},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\vchunk_metadata_test.cpp":{"size":5231,"mtime_ns":1788421144264275800,"word_count":290},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\vchunk_test_allocator.h":{"size":1843,"mtime_ns":1788421144264275800,"word_count":156},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\vchunk_transfer_engine_test.cpp":{"size":3477,"mtime_ns":1788421144264275800,"word_count":264},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tests\\zstd_util_test.cpp":{"size":3045,"mtime_ns":1781678985249670600,"word_count":238},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tools\\CMakeLists.txt":{"size":384,"mtime_ns":1786963737820332700,"word_count":10},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tools\\oplog_batch_auditor.cpp":{"size":9284,"mtime_ns":1786963737820332700,"word_count":765},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tools\\oplog_batch_auditor.h":{"size":1369,"mtime_ns":1786963737820332700,"word_count":85},"C:\\workspace\\code\\opensource\\Mooncake\\mooncake-store\\tools\\oplog_batch_inspector.cpp":{"size":8158,"mtime_ns":1786963737820332700,"word_count":731}}
\ No newline at end of file
diff --git a/mooncake-store/include/admission_ops.h b/mooncake-store/include/admission_ops.h
new file mode 100644
index 0000000000..9ef1ade825
--- /dev/null
+++ b/mooncake-store/include/admission_ops.h
@@ -0,0 +1,3 @@
+#pragma once
+
+#include "io_pattern/ops.h"
diff --git a/mooncake-store/include/cfm_client.h b/mooncake-store/include/cfm_client.h
new file mode 100644
index 0000000000..c94a0b0929
--- /dev/null
+++ b/mooncake-store/include/cfm_client.h
@@ -0,0 +1,3 @@
+#pragma once
+
+#include "io_pattern/client.h"
diff --git a/mooncake-store/include/cfm_client_impl.h b/mooncake-store/include/cfm_client_impl.h
new file mode 100644
index 0000000000..da6bbcfe9c
--- /dev/null
+++ b/mooncake-store/include/cfm_client_impl.h
@@ -0,0 +1,2 @@
+#pragma once
+#include "io_pattern/cfm_client_impl.h"
diff --git a/mooncake-store/include/client_service.h b/mooncake-store/include/client_service.h
index 631e4328bd..108996792a 100644
--- a/mooncake-store/include/client_service.h
+++ b/mooncake-store/include/client_service.h
@@ -908,8 +908,30 @@ class Client {
     std::mutex leader_switch_mutex_;
     std::optional<ha::MasterView> current_master_view_;
     std::string direct_master_address_;
+    // Etcd endpoints parsed from the HA backend entry, used to load the KV
+    // partition routing snapshot. Empty in non-HA mode.
+    std::string etcd_connstring_;
+    // Resolved cluster namespace (cluster_id) cached after the first routing
+    // load; reused by the periodic routing refresh loop.
+    std::string cluster_id_;
+    // CVM multi-submaster mode: set when the client bootstraps from the
+    // /cvm/<ns>/masters/ registry (no single-leader master_view in etcd).
+    // Empty in single-leader HA mode and direct mode. Also drives the
+    // ping-failure re-discovery path.
+    std::string cvm_cluster_namespace_;
+    // CVM 多 submaster：已发现的全部 primary submaster 地址（含当前连接的
+    // 那个）。用于 client 侧全量 mount（同一 segment 挂到所有 submaster）与
+    // 多 submaster 心跳（防止各 submaster 因收不到 ping 而误卸载 segment）。
+    // 由 ConnectToCvmSubmasters 填充。
+    std::mutex cvm_submaster_addresses_mutex_;
+    std::vector<std::string> cvm_submaster_addresses_;
+    // 串行化 TryLoadRoutingOnce（及其内部对 cluster_id_ 的读写），
+    // 用于 routing-refresh 线程与 SLOT_NOT_OWNED 触发的按需刷新之间。
+    std::mutex routing_load_mutex_;
     std::thread leader_monitor_thread_;
     std::atomic<bool> leader_monitor_running_{false};
+    std::thread routing_refresh_thread_;
+    std::atomic<bool> routing_refresh_running_{false};
     std::thread storage_heartbeat_thread_;
     std::atomic<bool> storage_heartbeat_running_{false};
     std::thread task_poll_thread_;
@@ -918,8 +940,25 @@ class Client {
     std::atomic<bool> segment_desc_publish_pending_{false};
     std::atomic<bool> rpc_meta_publish_pending_{false};
     ErrorCode SwitchLeader(const ha::MasterView& target_view);
+    // CVM multi-submaster bootstrap/failover: connect the etcd store client,
+    // discover the cluster namespace from /cvm/<ns>/masters/, and connect to
+    // the first live primary submaster (first-registered first, matching the
+    // CvmController ranking). On success sets cvm_cluster_namespace_.
+    ErrorCode ConnectToCvmSubmasters(const std::string& etcd_endpoints);
+    void LoadPartitionRouting();
+    void TryLoadRoutingOnce();
+    void RoutingRefreshThreadMain();
     void LeaderMonitorThreadMain();
     void StorageHeartbeatThreadMain();
+    // CVM 多 submaster：向所有 primary submaster 定向 Ping（不切换当前连接），
+    // 各 submaster 收到 ping 后会保活该 client；返回 NEED_REMOUNT 的 submaster
+    // 会被重新 mount（重新注册 segment）。单 submaster 失败不影响其他。
+    void HeartbeatAllSubmasters();
+    // CVM 多 submaster：重新扫描 /cvm/<ns>/masters/ 注册表，更新已发现的
+    // primary 地址列表；对新增的 submaster 全量 mount 所有本地 segment，使
+    // 新加入的 submaster 也具备给本 client 分配副本的能力。由路由刷新线程
+    // 周期调用。
+    void RefreshSubmasterAddresses();
     void TaskPollThreadMain();
     void EnsureStorageControlPlaneStarted();
     void PollAndDispatchTasks();
diff --git a/mooncake-store/include/collector_impl.h b/mooncake-store/include/collector_impl.h
new file mode 100644
index 0000000000..f85dc274e6
--- /dev/null
+++ b/mooncake-store/include/collector_impl.h
@@ -0,0 +1,2 @@
+#pragma once
+#include "io_pattern/collector_impl.h"
diff --git a/mooncake-store/include/cvm/cvm_controller.h b/mooncake-store/include/cvm/cvm_controller.h
new file mode 100644
index 0000000000..b581cc0980
--- /dev/null
+++ b/mooncake-store/include/cvm/cvm_controller.h
@@ -0,0 +1,163 @@
+#pragma once
+
+#include <atomic>
+#include <chrono>
+#include <condition_variable>
+#include <cstdint>
+#include <memory>
+#include <mutex>
+#include <optional>
+#include <string>
+#include <thread>
+#include <unordered_map>
+#include <vector>
+
+#include "cvm/cvm_types.h"
+#include "mutex.h"
+#include "types.h"
+
+namespace mooncake {
+namespace cvm {
+
+class CvmServiceDelegate;
+class CvmHttpServer;
+
+// In-process control plane for the CVM (Cache View Master).
+//
+// Responsibilities (P1 skeleton):
+//   - Register this master under an etcd lease (liveness + role).
+//   - Load and continuously watch the KV view (slot -> primary master).
+//   - Expose local read access to the cached view (OwnsSlot / GetKvView).
+//
+// The full slot-migration / failover / segment-view state machines are added
+// in later phases.
+class CvmController {
+   public:
+    struct Config {
+        std::string cluster_namespace;
+        std::string master_id;
+        std::string address;  // RPC endpoint of this master.
+        MasterRole role = MasterRole::kPrimary;
+        int64_t registration_lease_ttl_sec = 3;
+
+        // CvmHttpServer（外部 HTTP 接口）配置；http_port == 0 表示不启动。
+        std::string http_host = "0.0.0.0";
+        uint16_t http_port = 0;
+
+        // 集群中允许同时 serving 的 submaster 上限（名额协调，先到先得）。
+        // 排名前 submaster_count 个 master 为 kPrimary，其余降级为 kStandby。
+        uint32_t submaster_count = 1;
+
+        // 视图快照生成（SyncOnce）的调度周期。
+        std::chrono::milliseconds sync_interval{5000};
+    };
+
+    explicit CvmController(Config config);
+    ~CvmController();
+
+    CvmController(const CvmController&) = delete;
+    CvmController& operator=(const CvmController&) = delete;
+
+    void SetDelegate(CvmServiceDelegate* delegate);
+
+    // 当前角色（随名额协调动态变化）。
+    MasterRole GetCurrentRole() const { return current_role_.load(); }
+
+    // 排名第一（先到先得）的 primary 的 RPC 地址，作为 standby 的单源回放
+    // 目标。当成员列表为空或本机即为排名第一的 primary 时返回空字符串。
+    std::string GetPrimaryAddress();
+
+    // 排名前 submaster_count 的 primary（submaster）成员（含 master_id 与
+    // address），作为 standby 的多源回放目标。排除本机；成员列表为空或本机
+    // 覆盖全部 primary 名额时返回空列表。
+    std::vector<MasterRegistration> GetPrimaryPeers();
+
+    // standby 动态绑定（2c）：按「本 standby 负责的 slot 区间」过滤出拥有这些
+    // slot 的 primary，作为回放源（而非回放全部 primary）。本机为 primary 或
+    // 无法确定负责区间时返回空列表。
+    std::vector<MasterRegistration> GetBindingSources();
+
+    ErrorCode Start();
+    void Stop();
+
+    // 调度 EtcdViewStore 聚合原始记录 -> 生成视图快照 -> 回写 etcd。
+    ErrorCode SyncOnce();
+
+    // 把最新视图快照路径推送给 CvmHttpServer。
+    void PushViewPaths();
+
+    // etcd lease id backing this master's registration. Callers may reuse it
+    // for their own records (slot/segment ownership) so they share the same
+    // lifecycle and are auto-removed on master death. 0 until Start() succeeds.
+    EtcdLeaseId GetLeaseId() const { return lease_id_; }
+
+    // Whether this master currently owns `slot` as primary.
+    bool OwnsSlot(uint16_t slot) const;
+
+    // Snapshot of the cached KV view and its version.
+    std::vector<SlotOwner> GetKvView() const;
+    ViewVersionId GetKvViewVersion() const;
+
+   private:
+    struct WatchState {
+        std::mutex mutex;
+        std::condition_variable cv;
+        bool dirty = false;
+        bool broken = false;
+    };
+
+    Config config_;
+    CvmServiceDelegate* delegate_ = nullptr;
+
+    mutable SharedMutex view_mutex_;
+    std::unordered_map<uint16_t, SlotOwner> kv_view_;
+    ViewVersionId kv_view_version_{0};
+
+    EtcdLeaseId lease_id_{0};
+    std::atomic<bool> running_{false};
+    std::atomic<bool> watch_armed_{false};
+    std::atomic<bool> masters_watch_armed_{false};
+
+    // 当前角色（随名额协调动态变化）；初始为启动配置的 role。
+    std::atomic<MasterRole> current_role_{MasterRole::kPrimary};
+
+    std::unique_ptr<WatchState> watch_state_;
+    std::unique_ptr<WatchState> masters_watch_state_;
+    std::thread watch_thread_;
+    std::thread masters_watch_thread_;
+    std::thread keepalive_thread_;
+    std::thread sync_thread_;
+    std::thread membership_thread_;
+
+    std::mutex sync_mutex_;
+    std::condition_variable sync_cv_;
+
+    std::mutex membership_mutex_;
+    std::condition_variable membership_cv_;
+
+    // 视图类型 -> etcd 快照路径（"kv_view"/"segment_view"）。
+    std::unordered_map<std::string, std::string> view_paths_;
+    std::unique_ptr<CvmHttpServer> http_server_;
+
+    ErrorCode RefreshKvView();
+    void CancelWatchAndWait();
+    void WatchLoop();
+    void MastersWatchLoop();
+    void KeepaliveLoop();
+    void SyncLoop();
+    void MembershipLoop();
+    // 重算并回写角色（先到先得排名）；membership 轮询与 masters watch 回调
+    // 共用，用 CAS 去重，保证并发下仅一次迁移与通知。
+    void ReconcileRole();
+    MasterRole ComputeDesiredRole();
+    // 加载所有存活 master 并按「先到先得」排序（registered_at_ms 升序，
+    // tie-break master_id 字典序）。失败返回 false。
+    bool LoadRankedMembers(std::vector<MasterRegistration>& out);
+
+    static void WatchCallback(void* ctx, const char* key, size_t key_size,
+                              const char* value, size_t value_size,
+                              int event_type, int64_t mod_revision);
+};
+
+}  // namespace cvm
+}  // namespace mooncake
diff --git a/mooncake-store/include/cvm/cvm_http_server.h b/mooncake-store/include/cvm/cvm_http_server.h
new file mode 100644
index 0000000000..13b22511ca
--- /dev/null
+++ b/mooncake-store/include/cvm/cvm_http_server.h
@@ -0,0 +1,61 @@
+#pragma once
+
+#include <atomic>
+#include <cstdint>
+#include <memory>
+#include <mutex>
+#include <string>
+
+#include <ylt/coro_http/coro_http_server.hpp>
+
+#include "types.h"
+
+namespace mooncake {
+namespace cvm {
+
+// CVM 三模块之一：外部 HTTP 接口（cvmhttpserver）。
+//
+// 提供只读 HTTP API，按 etcd 中的视图快照路径读取快照并返回 JSON，供网页 /
+// 外部客户端展示。视图快照路径由 CvmController 定期推送；未推送时使用基于
+// cluster_namespace 构造的默认快照路径（见 cvm_keys.h）。
+class CvmHttpServer {
+   public:
+    struct Config {
+        std::string host = "0.0.0.0";
+        uint16_t port = 0;
+        std::string cluster_namespace;
+    };
+
+    explicit CvmHttpServer(Config config);
+    ~CvmHttpServer();
+
+    CvmHttpServer(const CvmHttpServer&) = delete;
+    CvmHttpServer& operator=(const CvmHttpServer&) = delete;
+
+    ErrorCode Start();
+    void Stop();
+
+    // 供 CvmController 推送最新视图快照路径（etcd key）。
+    void SetKvViewSnapshotKey(const std::string& key);
+    void SetSegmentViewSnapshotKey(const std::string& key);
+
+    // 按当前路径读取快照并返回 JSON 字符串；路径为空或读取失败时返回空串。
+    std::string GetKvViewJson() const;
+    std::string GetSegmentViewJson() const;
+
+   private:
+    void InitRoutes();
+    std::string ReadSnapshot(const std::string& key) const;
+
+    Config config_;
+    std::unique_ptr<coro_http::coro_http_server> server_;
+
+    mutable std::mutex path_mutex_;
+    std::string kv_view_snapshot_key_;
+    std::string segment_view_snapshot_key_;
+
+    std::atomic<bool> running_{false};
+};
+
+}  // namespace cvm
+}  // namespace mooncake
diff --git a/mooncake-store/include/cvm/cvm_keys.h b/mooncake-store/include/cvm/cvm_keys.h
new file mode 100644
index 0000000000..0e1163ecc9
--- /dev/null
+++ b/mooncake-store/include/cvm/cvm_keys.h
@@ -0,0 +1,100 @@
+#pragma once
+
+#include <cstdint>
+#include <cstdio>
+#include <string>
+#include <string_view>
+
+namespace mooncake {
+namespace cvm {
+
+// Root prefix for all CVM keys in etcd.
+inline constexpr std::string_view kCvmRootPrefix = "/cvm/";
+
+// End key for an etcd range scan over [prefix, PrefixEnd(prefix)).
+inline std::string PrefixEnd(std::string prefix) {
+    for (int i = static_cast<int>(prefix.size()) - 1; i >= 0; --i) {
+        unsigned char c = static_cast<unsigned char>(prefix[i]);
+        if (c < 0xFF) {
+            prefix[i] = static_cast<char>(c + 1);
+            prefix.resize(i + 1);
+            return prefix;
+        }
+    }
+    return std::string(1, '\0');
+}
+
+// "/cvm/<namespace>/"
+inline std::string CvmNamespaceRoot(const std::string& cluster_namespace) {
+    return std::string(kCvmRootPrefix) + cluster_namespace + "/";
+}
+
+// "/cvm/<namespace>/kv_view/"
+inline std::string KvViewPrefix(const std::string& cluster_namespace) {
+    return CvmNamespaceRoot(cluster_namespace) + "kv_view/";
+}
+
+// "/cvm/<namespace>/kv_view/slot/<slot:05d>"
+inline std::string SlotOwnerKey(const std::string& cluster_namespace,
+                                uint16_t slot) {
+    char buf[16];
+    std::snprintf(buf, sizeof(buf), "%05u", static_cast<unsigned>(slot));
+    return KvViewPrefix(cluster_namespace) + "slot/" + buf;
+}
+
+// "/cvm/<namespace>/slot_meta/"
+inline std::string SlotMetadataExportPrefix(
+    const std::string& cluster_namespace) {
+    return CvmNamespaceRoot(cluster_namespace) + "slot_meta/";
+}
+
+// "/cvm/<namespace>/slot_meta/<slot:05d>"
+// Binary (struct_pack) value holding the object metadata exported by the
+// previous live primary owner during a slot handoff.
+inline std::string SlotMetadataExportKey(const std::string& cluster_namespace,
+                                         uint16_t slot) {
+    char buf[16];
+    std::snprintf(buf, sizeof(buf), "%05u", static_cast<unsigned>(slot));
+    return SlotMetadataExportPrefix(cluster_namespace) + buf;
+}
+
+// "/cvm/<namespace>/segment_view/"
+inline std::string SegmentViewPrefix(const std::string& cluster_namespace) {
+    return CvmNamespaceRoot(cluster_namespace) + "segment_view/";
+}
+
+// "/cvm/<namespace>/segment_view/<segment_id>"
+inline std::string SegmentOwnerKey(const std::string& cluster_namespace,
+                                   const std::string& segment_id) {
+    return SegmentViewPrefix(cluster_namespace) + segment_id;
+}
+
+// "/cvm/<namespace>/masters/"
+inline std::string MasterRegistrationPrefix(
+    const std::string& cluster_namespace) {
+    return CvmNamespaceRoot(cluster_namespace) + "masters/";
+}
+
+// "/cvm/<namespace>/masters/<master_id>"
+inline std::string MasterRegistrationKey(const std::string& cluster_namespace,
+                                         const std::string& master_id) {
+    return MasterRegistrationPrefix(cluster_namespace) + master_id;
+}
+
+// "/cvm/<namespace>/snapshot/"
+inline std::string SnapshotPrefix(const std::string& cluster_namespace) {
+    return CvmNamespaceRoot(cluster_namespace) + "snapshot/";
+}
+
+// "/cvm/<namespace>/snapshot/kv_view"
+inline std::string KvViewSnapshotKey(const std::string& cluster_namespace) {
+    return SnapshotPrefix(cluster_namespace) + "kv_view";
+}
+
+// "/cvm/<namespace>/snapshot/segment_view"
+inline std::string SegmentViewSnapshotKey(const std::string& cluster_namespace) {
+    return SnapshotPrefix(cluster_namespace) + "segment_view";
+}
+
+}  // namespace cvm
+}  // namespace mooncake
diff --git a/mooncake-store/include/cvm/cvm_service_delegate.h b/mooncake-store/include/cvm/cvm_service_delegate.h
new file mode 100644
index 0000000000..81c4c65208
--- /dev/null
+++ b/mooncake-store/include/cvm/cvm_service_delegate.h
@@ -0,0 +1,36 @@
+#pragma once
+
+#include <cstdint>
+
+#include "cvm/cvm_types.h"
+
+namespace mooncake {
+namespace cvm {
+
+// Callback interface implemented by MasterService. CvmController calls into
+// this delegate to notify the embedding master of slot ownership changes,
+// without taking a dependency on the concrete MasterService type.
+class CvmServiceDelegate {
+   public:
+    virtual ~CvmServiceDelegate() = default;
+
+    // Called when this master becomes the stable primary owner of `slot`.
+    virtual void OnSlotAcquired(uint16_t slot) = 0;
+
+    // Called when this master releases ownership of `slot`.
+    virtual void OnSlotReleased(uint16_t slot) = 0;
+
+    // Called when the CVM membership coordinator decides this master's role
+    // should change (e.g. demoted to standby because the submaster quota is
+    // full, or promoted back to primary). MasterService reacts by switching
+    // its serving/standby state machine accordingly.
+    virtual void OnRoleChanged(MasterRole new_role) = 0;
+
+    // Called when the cached slot->primary view changes (slot ownership
+    // rebalanced or a primary's lease expired). A standby uses this to re-bind
+    // its replay sources even when its own role stays kStandby.
+    virtual void OnKvViewChanged() {}
+};
+
+}  // namespace cvm
+}  // namespace mooncake
diff --git a/mooncake-store/include/cvm/cvm_types.h b/mooncake-store/include/cvm/cvm_types.h
new file mode 100644
index 0000000000..ea5d71b084
--- /dev/null
+++ b/mooncake-store/include/cvm/cvm_types.h
@@ -0,0 +1,108 @@
+#pragma once
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+#include "types.h"
+
+namespace mooncake {
+namespace cvm {
+
+// ---------------------------------------------------------------------------
+// Enumerations
+// ---------------------------------------------------------------------------
+
+// Ownership state of a logical KV slot.
+enum class SlotState : int32_t {
+    kStable = 0,     // Served by primary_master_id.
+    kMigrating = 1,  // Handing off to migrating_to_master_id.
+};
+
+// Role of a master within the CVM topology.
+enum class MasterRole : int32_t {
+    kPrimary = 0,
+    kStandby = 1,
+};
+
+// Ownership state of a segment (segment view is reserved).
+enum class SegmentOwnerState : int32_t {
+    kStable = 0,
+    kTransitioning = 1,
+};
+
+// ---------------------------------------------------------------------------
+// KV view: slot -> primary master ownership
+// ---------------------------------------------------------------------------
+
+// NOTE: enum fields are stored as int32_t so the records serialize/deserialize
+// identically across languages and compiler settings.
+struct SlotOwner {
+    uint16_t slot{0};
+    std::string primary_master_id;
+    int32_t state{0};  // SlotState
+    std::string migrating_to_master_id;  // empty when stable
+};
+YLT_REFL(SlotOwner, slot, primary_master_id, state, migrating_to_master_id);
+
+// ---------------------------------------------------------------------------
+// Segment view: segment -> owner master ownership (reserved)
+// ---------------------------------------------------------------------------
+
+struct SegmentOwner {
+    std::string segment_id;
+    std::string owner_master_id;
+    int32_t state{0};  // SegmentOwnerState
+};
+YLT_REFL(SegmentOwner, segment_id, owner_master_id, state);
+
+// ---------------------------------------------------------------------------
+// Master registration: liveness + role, persisted under an etcd lease
+// ---------------------------------------------------------------------------
+
+struct MasterRegistration {
+    std::string master_id;
+    std::string address;  // RPC endpoint, e.g. "host:port"
+    int32_t role{0};      // MasterRole
+    int64_t registered_at_ms{0};
+};
+YLT_REFL(MasterRegistration, master_id, address, role, registered_at_ms);
+
+// ---------------------------------------------------------------------------
+// Aggregated views (in-memory snapshots)
+// ---------------------------------------------------------------------------
+
+struct KvView {
+    std::vector<SlotOwner> slot_owners;
+};
+YLT_REFL(KvView, slot_owners);
+
+struct SegmentView {
+    std::vector<SegmentOwner> segment_owners;
+};
+YLT_REFL(SegmentView, segment_owners);
+
+// ---------------------------------------------------------------------------
+// Derived snapshots (persisted back to etcd)
+// ---------------------------------------------------------------------------
+
+// Aggregated, point-in-time view of slot ownership. EtcdViewStore builds this
+// from the raw slot records and writes it back to etcd so that clients can read
+// the whole mapping with a single range get instead of one key per slot.
+struct KvViewSnapshot {
+    ViewVersionId version{0};       // Etcd revision of the raw records used.
+    int64_t generated_at_ms{0};     // Build time (ms since epoch).
+    std::vector<SlotOwner> slot_owners;
+};
+YLT_REFL(KvViewSnapshot, version, generated_at_ms, slot_owners);
+
+// Aggregated, point-in-time view of segment ownership (reserved).
+struct SegmentViewSnapshot {
+    ViewVersionId version{0};       // Etcd revision of the raw records used.
+    int64_t generated_at_ms{0};     // Build time (ms since epoch).
+    std::vector<SegmentOwner> segment_owners;
+};
+YLT_REFL(SegmentViewSnapshot, version, generated_at_ms, segment_owners);
+
+}  // namespace cvm
+}  // namespace mooncake
diff --git a/mooncake-store/include/cvm/etcd_view_store.h b/mooncake-store/include/cvm/etcd_view_store.h
new file mode 100644
index 0000000000..8c146c9418
--- /dev/null
+++ b/mooncake-store/include/cvm/etcd_view_store.h
@@ -0,0 +1,134 @@
+#pragma once
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+#include "cvm/cvm_types.h"
+#include "types.h"
+
+namespace mooncake {
+namespace cvm {
+
+// Serialization + etcd persistence for CVM views, built on EtcdHelper.
+//
+// All KV view / segment view / master registration records are stored in etcd
+// under the CVM key space (see cvm_keys.h). ViewVersionId is the etcd revision
+// returned by the read, so consumers can watch from it without gaps.
+class EtcdViewStore {
+   public:
+    // ---- JSON serialization ----
+    static ErrorCode SerializeSlotOwner(const SlotOwner& owner,
+                                        std::string& out);
+    static ErrorCode DeserializeSlotOwner(const std::string& in,
+                                          SlotOwner& out);
+
+    static ErrorCode SerializeSegmentOwner(const SegmentOwner& owner,
+                                           std::string& out);
+    static ErrorCode DeserializeSegmentOwner(const std::string& in,
+                                             SegmentOwner& out);
+
+    static ErrorCode SerializeMasterRegistration(const MasterRegistration& reg,
+                                                 std::string& out);
+    static ErrorCode DeserializeMasterRegistration(const std::string& in,
+                                                   MasterRegistration& out);
+
+    static ErrorCode SerializeKvViewSnapshot(const KvViewSnapshot& snapshot,
+                                             std::string& out);
+    static ErrorCode DeserializeKvViewSnapshot(const std::string& in,
+                                               KvViewSnapshot& out);
+    static ErrorCode SerializeSegmentViewSnapshot(
+        const SegmentViewSnapshot& snapshot, std::string& out);
+    static ErrorCode DeserializeSegmentViewSnapshot(const std::string& in,
+                                                    SegmentViewSnapshot& out);
+
+    // ---- KV view ----
+    static ErrorCode LoadSlotOwner(const std::string& cluster_namespace,
+                                   uint16_t slot, SlotOwner& out,
+                                   ViewVersionId& version);
+    static ErrorCode SaveSlotOwner(const std::string& cluster_namespace,
+                                   const SlotOwner& owner);
+    static ErrorCode SaveSlotOwnerWithLease(const std::string& cluster_namespace,
+                                            const SlotOwner& owner,
+                                            EtcdLeaseId lease_id);
+    // Batch variant: writes many slot owners in chunks (each chunk a single
+    // etcd txn, all bound to lease_id). Speeds up bulk acquisition (e.g. cold
+    // start / node add) that would otherwise issue one RPC per slot. Falls back
+    // to per-slot puts within a chunk if the txn fails; returns an error only
+    // if a final per-slot put fails.
+    static ErrorCode SaveSlotOwnersWithLease(
+        const std::string& cluster_namespace,
+        const std::vector<SlotOwner>& owners, EtcdLeaseId lease_id);
+    static ErrorCode DeleteSlotOwner(const std::string& cluster_namespace,
+                                     uint16_t slot);
+    static ErrorCode DeleteSlotOwnerIfOwnedBy(
+        const std::string& cluster_namespace, uint16_t slot,
+        const std::string& master_id);
+    static ErrorCode LoadAllSlotOwners(const std::string& cluster_namespace,
+                                       std::vector<SlotOwner>& out,
+                                       ViewVersionId& version);
+
+    // ---- Segment view (reserved) ----
+    static ErrorCode LoadSegmentOwner(const std::string& cluster_namespace,
+                                      const std::string& segment_id,
+                                      SegmentOwner& out,
+                                      ViewVersionId& version);
+    static ErrorCode SaveSegmentOwner(const std::string& cluster_namespace,
+                                      const SegmentOwner& owner);
+    static ErrorCode SaveSegmentOwnerWithLease(
+        const std::string& cluster_namespace, const SegmentOwner& owner,
+        EtcdLeaseId lease_id);
+    static ErrorCode DeleteSegmentOwner(const std::string& cluster_namespace,
+                                        const std::string& segment_id);
+    static ErrorCode LoadAllSegmentOwners(const std::string& cluster_namespace,
+                                          std::vector<SegmentOwner>& out,
+                                          ViewVersionId& version);
+
+    // ---- Master registration ----
+    static ErrorCode RegisterMaster(const std::string& cluster_namespace,
+                                    const MasterRegistration& reg,
+                                    EtcdLeaseId lease_id);
+    static ErrorCode UpdateMasterRole(const std::string& cluster_namespace,
+                                      const std::string& master_id,
+                                      MasterRole role, EtcdLeaseId lease_id);
+    static ErrorCode LoadAllMasters(const std::string& cluster_namespace,
+                                    std::vector<MasterRegistration>& out,
+                                    ViewVersionId& version);
+
+    // ---- Snapshots ----
+    // Reads the raw slot/segment records, aggregates them into a point-in-time
+    // snapshot and writes it back to etcd. `version` is set to the etcd
+    // revision of the raw records that were aggregated.
+    static ErrorCode BuildAndSaveKvViewSnapshot(
+        const std::string& cluster_namespace, ViewVersionId& version);
+    static ErrorCode BuildAndSaveSegmentViewSnapshot(
+        const std::string& cluster_namespace, ViewVersionId& version);
+
+    static ErrorCode SaveKvViewSnapshot(const std::string& cluster_namespace,
+                                        const KvViewSnapshot& snapshot);
+    static ErrorCode SaveSegmentViewSnapshot(
+        const std::string& cluster_namespace, const SegmentViewSnapshot& snapshot);
+
+    // ---- Watch ----
+    using WatchCallback = void (*)(void*, const char*, size_t, const char*,
+                                   size_t, int, int64_t);
+    static ErrorCode WatchKvView(const std::string& cluster_namespace,
+                                 ViewVersionId start_revision, void* ctx,
+                                 WatchCallback cb);
+    static ErrorCode CancelWatchKvView(const std::string& cluster_namespace);
+    static ErrorCode WaitWatchKvViewStopped(const std::string& cluster_namespace,
+                                            int timeout_ms);
+
+    // ---- Master membership watch ----
+    // Watches the master registration prefix so member add/remove (e.g. lease
+    // expiry) can drive immediate role re-evaluation (P3 failover).
+    static ErrorCode WatchMasters(const std::string& cluster_namespace,
+                                  ViewVersionId start_revision, void* ctx,
+                                  WatchCallback cb);
+    static ErrorCode CancelWatchMasters(const std::string& cluster_namespace);
+    static ErrorCode WaitWatchMastersStopped(
+        const std::string& cluster_namespace, int timeout_ms);
+};
+
+}  // namespace cvm
+}  // namespace mooncake
diff --git a/mooncake-store/include/cvm/inter_master_rpc.h b/mooncake-store/include/cvm/inter_master_rpc.h
new file mode 100644
index 0000000000..baba1a5cdb
--- /dev/null
+++ b/mooncake-store/include/cvm/inter_master_rpc.h
@@ -0,0 +1,189 @@
+#pragma once
+
+#include <atomic>
+#include <condition_variable>
+#include <cstdint>
+#include <deque>
+#include <memory>
+#include <mutex>
+#include <optional>
+#include <string>
+#include <thread>
+#include <unordered_map>
+#include <vector>
+
+#include <ylt/util/tl/expected.hpp>
+
+#include "cvm/cvm_types.h"
+#include "rpc_client_io_context.h"
+#include "rpc_types.h"
+#include "types.h"
+
+namespace mooncake {
+
+class WrappedMasterService;
+
+namespace cvm {
+
+// Inter-master RPC client for the CVM multi-submaster topology (plan B:
+// forward allocation requests to the segment-owning submaster).
+//
+// Discovery is fully etcd-driven (loose coupling): a background thread
+// periodically reloads the master registration table
+// (/cvm/<ns>/masters/<master_id>) and maintains a master_id -> RPC address
+// mapping. One coro_rpc client pool is cached per target address, so
+// repeated forwarding reuses established connections.
+//
+// This first phase provides the handshake RPC used to verify the channel;
+// forwarding methods (e.g. PutStart allocation forwarding to the segment
+// owner) build on the same invoke_rpc core.
+class InterMasterRpcClient {
+   public:
+    // Refresh period for the etcd-driven member table. Matches the CVM
+    // membership/sync cadence (5s) so member add/remove is picked up with
+    // comparable latency.
+    static constexpr int kRefreshIntervalMs = 5000;
+
+    // Upper bound for the pending broadcast-free queue (eviction storms
+    // must not grow it unboundedly; dropped entries only leak handles until
+    // the segment is unmounted).
+    static constexpr size_t kMaxBroadcastFreeQueueSize = 100000;
+
+    InterMasterRpcClient();
+
+    ~InterMasterRpcClient();
+
+    InterMasterRpcClient(const InterMasterRpcClient&) = delete;
+    InterMasterRpcClient& operator=(const InterMasterRpcClient&) = delete;
+
+    // Starts the member-refresh loop. `cluster_namespace` selects the CVM
+    // namespace in etcd; empty disables the refresh thread (manual updates
+    // only). `self_master_id` is excluded from peer handshakes. The etcd
+    // client must already be connected (the supervisor's CvmController
+    // connects it before serve).
+    ErrorCode Start(const std::string& cluster_namespace,
+                    const std::string& self_master_id = "");
+
+    void Stop();
+
+    // Replaces the member table (master_id -> address). Safe to call from
+    // any thread; drops addresses of members that disappeared.
+    void UpdateMembers(const std::vector<MasterRegistration>& members);
+
+    // Current member table snapshot.
+    std::vector<MasterRegistration> GetMembers() const;
+
+    // Resolves the RPC address of `master_id` from the cached member table.
+    std::optional<std::string> ResolveAddress(
+        const std::string& master_id) const;
+
+    // Handshakes the target submaster: returns its identity + ownership
+    // summary. Used both for channel verification and liveness probing.
+    tl::expected<InterMasterHandshakeResponse, ErrorCode> Handshake(
+        const std::string& master_id);
+
+    // Handshakes every known member except `self_master_id` (logging-only
+    // helper for startup verification). Returns the number of successes.
+    size_t HandshakeAll(const std::string& self_master_id);
+
+    // ----- Allocation forwarding (CVM plan B phase 2) -----
+
+    // Asks the target submaster (segment owner) to allocate memory replicas
+    // in its locally mounted segments. When `preferred_segments` is
+    // non-empty the allocation is strict: only those segments are used.
+    // The peer keeps the real handles alive; the caller only materializes
+    // dummy-allocator replicas from the returned descriptors.
+    tl::expected<std::vector<Replica::Descriptor>, ErrorCode>
+    AllocateReplicas(const std::string& master_id, const std::string& tenant_id,
+                     const std::string& key, uint64_t slice_length,
+                     uint64_t replica_num,
+                     const std::vector<std::string>& preferred_segments);
+
+    // Frees replicas previously allocated via AllocateReplicas on the
+    // target submaster. Returns true when a keepalive entry was found.
+    tl::expected<bool, ErrorCode> FreeReplicas(const std::string& master_id,
+                                               const std::string& tenant_id,
+                                               const std::string& key);
+
+    // Fire-and-forget: broadcast the free to every known peer. Used when the
+    // slot owner erases an object whose handles live on a segment-owning
+    // peer (it does not track which peer, so all peers are asked; only the
+    // owner of the keepalive entry reacts).
+    void EnqueueBroadcastFree(const std::string& tenant_id,
+                              const std::string& key);
+
+    // ----- Read forwarding (CVM plan B phase 2) -----
+
+    // Forwards a single-key GetReplicaList to the slot-owning submaster.
+    // The target performs a local query only (no re-forward), so an
+    // inconsistent view terminates the forward chain at the first hop.
+    tl::expected<GetReplicaListResponse, ErrorCode> GetReplicaList(
+        const std::string& master_id, const std::string& key,
+        const std::string& tenant_id);
+
+    // Forwards a batch GetReplicaList to the slot-owning submaster.
+    std::vector<tl::expected<GetReplicaListResponse, ErrorCode>>
+    BatchGetReplicaList(const std::string& master_id,
+                        const std::vector<std::string>& keys,
+                        const std::string& tenant_id);
+
+    // ----- Write forwarding (model B) -----
+
+    // Relays a FULL PutStart to the slot-owning submaster. The owner executes
+    // the complete local PutStart (alloc + metadata + keepalive) and returns
+    // the descriptors, which the caller relays to the client. The owner's
+    // OwnsSlot==true so it does not re-forward (chain stops at the first hop).
+    tl::expected<std::vector<Replica::Descriptor>, ErrorCode> PutStart(
+        const std::string& master_id, const UUID& client_id,
+        const std::string& key, const std::string& tenant_id,
+        uint64_t slice_length, const ReplicateConfig& config);
+
+    // Upsert variant: relays a FULL UpsertStart to the slot owner so it
+    // overwrites-if-exists (preemption) locally rather than via PutStart.
+    tl::expected<std::vector<Replica::Descriptor>, ErrorCode> UpsertStart(
+        const std::string& master_id, const UUID& client_id,
+        const std::string& key, const std::string& tenant_id,
+        uint64_t slice_length, const ReplicateConfig& config);
+
+   private:
+    // Generic sync RPC invocation against the pool of the target address.
+    // Defined in the .cpp (needs the complete WrappedMasterService type).
+    template <auto ServiceMethod, typename ReturnType, typename... Args>
+    tl::expected<ReturnType, ErrorCode> invoke_rpc(const std::string& address,
+                                                   Args&&... args);
+
+    // Refreshes the member table from etcd and handshakes newly joined peers
+    // (channel verification + connection warmup).
+    void RefreshLoop();
+
+    // Drains the broadcast-free queue: for each task, asks every known peer
+    // to free the keepalive entry for (tenant, key) if it holds one.
+    void FreeLoop();
+
+    struct FreeTask {
+        std::string tenant_id;
+        std::string key;
+        int attempts{0};
+    };
+
+    mutable std::mutex members_mutex_;
+    std::unordered_map<std::string, std::string> members_;  // id -> address
+
+    std::string cluster_namespace_;
+    std::string self_master_id_;
+    std::atomic<bool> running_{false};
+    std::thread refresh_thread_;
+    std::thread free_thread_;
+    std::mutex cv_mutex_;
+    std::condition_variable cv_;
+
+    std::mutex free_queue_mutex_;
+    std::condition_variable free_cv_;
+    std::deque<FreeTask> free_queue_;
+
+    // Per-address cached coro_rpc client pools (see RpcClientPool).
+    RpcClientPool pool_accessor_;
+};
+
+}  // namespace cvm
+}  // namespace mooncake
diff --git a/mooncake-store/include/cvm/slot_hash.h b/mooncake-store/include/cvm/slot_hash.h
new file mode 100644
index 0000000000..1e5330386d
--- /dev/null
+++ b/mooncake-store/include/cvm/slot_hash.h
@@ -0,0 +1,163 @@
+#pragma once
+
+#include <algorithm>
+#include <cstdint>
+#include <string>
+#include <vector>
+
+#include "crc32c.h"
+#include "tenant_id.h"
+
+namespace mooncake {
+namespace cvm {
+
+// Number of logical slots, aligned with Redis Cluster (16384 == 2^14).
+constexpr uint16_t kSlotCount = 16384;
+constexpr uint16_t kSlotMask = kSlotCount - 1;  // 16383
+
+// Number of virtual nodes per master on the consistent-hash ring used for
+// dynamic slot ownership. More vnodes yield a more balanced distribution at
+// the cost of a larger ring to build/sort on each heartbeat. 128 keeps load
+// skew low (~1%) while remaining cheap to recompute.
+constexpr uint16_t kVnodeCount = 128;
+
+// Maps a stable hash value to a slot by taking the low 14 bits. This is
+// equivalent to `hash % kSlotCount` but cheaper.
+inline uint16_t SlotOf(uint32_t hash) {
+    return static_cast<uint16_t>(hash & kSlotMask);
+}
+
+// Computes the logical slot for a tenant-scoped key.
+//
+// - Default tenant: slot = hash(user_key).
+// - Non-default tenant: slot = hash(tenant + '\0' + user_key), so that keys
+//   from different tenants are isolated while remaining stable across
+//   processes/compilers (unlike std::hash).
+inline uint16_t KeySlot(const TenantId& tenant, const std::string& user_key) {
+    Crc32c crc;
+    if (!tenant.IsDefault()) {
+        crc.Extend(tenant.value().data(), tenant.value().size());
+        constexpr char kSeparator = '\0';
+        crc.Extend(&kSeparator, 1);
+    }
+    crc.Extend(user_key.data(), user_key.size());
+    return SlotOf(crc.Final());
+}
+
+// Position of a master's virtual node on the consistent-hash ring, in
+// [0, kSlotCount). Placement depends only on (master_id, vnode_index), so it
+// is deterministic across processes/compilers and independent of the current
+// master set. The vnode index is encoded as fixed little-endian bytes so the
+// hash is stable regardless of host endianness.
+inline uint16_t VNodePosition(const std::string& master_id, uint16_t vnode) {
+    Crc32c crc;
+    crc.Extend(master_id.data(), master_id.size());
+    const uint8_t vnode_bytes[2] = {
+        static_cast<uint8_t>(vnode & 0xFFu),
+        static_cast<uint8_t>((vnode >> 8) & 0xFFu),
+    };
+    crc.Extend(reinterpret_cast<const char*>(vnode_bytes),
+               sizeof(vnode_bytes));
+    return SlotOf(crc.Final());
+}
+
+// 一致性哈希环分配：给定去重后的 primary master_id 列表 ids 与本机
+// master_id，返回本机应拥有的 slot 集合。每个 primary 在环上放置
+// kVnodeCount 个虚拟节点，slot 归属「顺时针最近的虚拟节点」。ids 应为
+// 排序去重后的 primary 列表，且必须包含 master_id。
+//
+// 虚拟节点位置只依赖 (master_id, vnode_index)，因此 primary 增删时仅该
+// primary 虚拟节点覆盖的 slot（约 1/n）发生迁移，其余 primary 的 slot 保持
+// 不变，避免 naive 均分导致的「全员 slot 平移」。
+inline std::vector<uint16_t> ResolveOwnedSlotsOnRing(
+    const std::vector<std::string>& ids, const std::string& master_id) {
+    const size_t n = ids.size();
+    if (n <= 1) {
+        std::vector<uint16_t> slots;
+        slots.reserve(kSlotCount);
+        for (uint16_t s = 0; s < kSlotCount; ++s) {
+            slots.push_back(s);
+        }
+        return slots;
+    }
+
+    struct VNode {
+        uint16_t position;
+        size_t owner_index;  // 指向 ids
+    };
+    std::vector<VNode> ring;
+    ring.reserve(n * kVnodeCount);
+    for (size_t i = 0; i < n; ++i) {
+        for (uint16_t v = 0; v < kVnodeCount; ++v) {
+            ring.push_back({VNodePosition(ids[i], v), i});
+        }
+    }
+    // 稳定排序（position 相同按 owner_index）保证跨进程结果一致。
+    std::sort(ring.begin(), ring.end(), [](const VNode& a, const VNode& b) {
+        if (a.position != b.position) {
+            return a.position < b.position;
+        }
+        return a.owner_index < b.owner_index;
+    });
+
+    std::vector<uint16_t> slots;
+    slots.reserve(kSlotCount / n + 1);
+    for (uint16_t s = 0; s < kSlotCount; ++s) {
+        // 环上第一个 position >= s 的虚拟节点（越界则环绕到 ring[0]）。
+        auto it = std::lower_bound(
+            ring.begin(), ring.end(), s,
+            [](const VNode& vn, uint16_t value) { return vn.position < value; });
+        if (it == ring.end()) {
+            it = ring.begin();
+        }
+        if (ids[it->owner_index] == master_id) {
+            slots.push_back(s);
+        }
+    }
+    return slots;
+}
+
+// 一致性哈希环反查：给定去重排序后的 primary master_id 列表 ids 与单个
+// slot，返回该 slot 的 owner master_id。规则与 ResolveOwnedSlotsOnRing 一致
+// （slot 归属顺时针最近的虚拟节点）。ids 为空返回空串，n == 1 直接返回
+// 唯一成员（单主全量接管）。供读路径转发（非 owner → slot owner）使用。
+inline std::string ResolveSlotOwnerOnRing(const std::vector<std::string>& ids,
+                                          uint16_t slot) {
+    const size_t n = ids.size();
+    if (n == 0) {
+        return {};
+    }
+    if (n == 1) {
+        return ids[0];
+    }
+
+    struct VNode {
+        uint16_t position;
+        size_t owner_index;  // 指向 ids
+    };
+    std::vector<VNode> ring;
+    ring.reserve(n * kVnodeCount);
+    for (size_t i = 0; i < n; ++i) {
+        for (uint16_t v = 0; v < kVnodeCount; ++v) {
+            ring.push_back({VNodePosition(ids[i], v), i});
+        }
+    }
+    // 稳定排序（position 相同按 owner_index）保证跨进程结果一致。
+    std::sort(ring.begin(), ring.end(), [](const VNode& a, const VNode& b) {
+        if (a.position != b.position) {
+            return a.position < b.position;
+        }
+        return a.owner_index < b.owner_index;
+    });
+
+    auto it = std::lower_bound(
+        ring.begin(), ring.end(), slot,
+        [](const VNode& vn, uint16_t value) { return vn.position < value; });
+    if (it == ring.end()) {
+        it = ring.begin();
+    }
+    return ids[it->owner_index];
+}
+
+}  // namespace cvm
+}  // namespace mooncake
diff --git a/mooncake-store/include/cvm/slot_migrator.h b/mooncake-store/include/cvm/slot_migrator.h
new file mode 100644
index 0000000000..128228c466
--- /dev/null
+++ b/mooncake-store/include/cvm/slot_migrator.h
@@ -0,0 +1,72 @@
+#pragma once
+
+#include <cstdint>
+#include <functional>
+#include <string>
+#include <utility>
+#include <vector>
+
+#include "cvm/cvm_types.h"
+#include "types.h"
+
+namespace mooncake {
+namespace cvm {
+
+// Drives the slot ownership handoff state machine (P4).
+//
+// A submaster owning a set of logical slots moves each slot through a two-phase
+// transition whenever ownership changes:
+//
+//   新获得 slot: kMigrating (migrating_to = self) -> on_acquire -> kStable
+//   释放   slot: on_release -> DeleteSlotOwnerIfOwnedBy(self)
+//   不变   slot: kStable (幂等 reaffirm)
+//
+// `kMigrating` is visible to clients so they can treat a handoff-in-progress
+// slot as "not yet routable" instead of hitting a half-ready new owner.
+//
+// SlotMigrator only moves the *ownership records*; the actual object-metadata
+// materialization/drop is the caller's responsibility via the on_acquire /
+// on_release hooks (data bytes always stay in segments).
+class SlotMigrator {
+   public:
+    struct Config {
+        std::string cluster_namespace;
+        std::string master_id;
+        EtcdLeaseId lease_id{0};
+    };
+
+    using SlotCallback = std::function<void(uint16_t)>;
+
+    explicit SlotMigrator(Config config);
+    ~SlotMigrator() = default;
+
+    SlotMigrator(const SlotMigrator&) = delete;
+    SlotMigrator& operator=(const SlotMigrator&) = delete;
+
+    // Hooks invoked on ownership change. on_acquire materializes object
+    // metadata for the slot (or is a no-op when the metadata already arrived
+    // via the standby-restore path); on_release drops it.
+    void SetOnAcquire(SlotCallback cb) { on_acquire_ = std::move(cb); }
+    void SetOnRelease(SlotCallback cb) { on_release_ = std::move(cb); }
+
+    // Publishes slot ownership for `owned_slots`. Idempotent; safe to call from
+    // the heartbeat thread. Returns the last non-OK error (if any) but keeps
+    // going so a single failing slot does not block the rest.
+    ErrorCode Reconcile(const std::vector<uint16_t>& owned_slots);
+
+   private:
+    ErrorCode PublishMigrating(uint16_t slot);
+    ErrorCode PublishStable(uint16_t slot);
+
+    Config config_;
+    SlotCallback on_acquire_;
+    SlotCallback on_release_;
+    std::vector<uint16_t> last_owned_slots_;
+    // Reconcile 调用计数，用于把不变 slot 的 reaffirm 降频为低频安全网：
+    // slot key 附着在 lease 上（keepalive 保活即不过期），逐周期重写只是
+    // 徒增 etcd MVCC revision，曾导致 backend 配额被写满。
+    uint64_t reconcile_cycles_{0};
+};
+
+}  // namespace cvm
+}  // namespace mooncake
diff --git a/mooncake-store/include/cvm/slot_owner_heartbeat.h b/mooncake-store/include/cvm/slot_owner_heartbeat.h
new file mode 100644
index 0000000000..17978788e5
--- /dev/null
+++ b/mooncake-store/include/cvm/slot_owner_heartbeat.h
@@ -0,0 +1,94 @@
+#pragma once
+
+#include <atomic>
+#include <chrono>
+#include <condition_variable>
+#include <cstdint>
+#include <functional>
+#include <mutex>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include "cvm/cvm_types.h"
+#include "cvm/slot_migrator.h"
+#include "types.h"
+
+namespace mooncake {
+namespace cvm {
+
+// Publishes this submaster's slot ownership to etcd on a fixed interval.
+//
+// The submaster (a MasterService instance) owns a set of logical slots. It
+// periodically writes one `SlotOwner` record per owned slot under
+// `/cvm/{ns}/kv_view/slot/{slot:05d}` (see EtcdViewStore::SaveSlotOwner).
+// EtcdViewStore later aggregates these raw records into a `KvViewSnapshot`
+// that clients read to route keys to the right submaster.
+//
+// Slot ownership is published on a fixed interval. With a non-zero `lease_id`
+// the records are lease-bound and auto-removed when the lease expires (master
+// death), which lets the dynamic partition rebalance the freed slots. With
+// `lease_id == 0` the mapping is a persistent fact re-affirmed idempotently
+// (single-master fallback).
+class SlotOwnerHeartbeat {
+   public:
+    struct Config {
+        std::string cluster_namespace;
+        std::string master_id;
+        std::chrono::milliseconds heartbeat_interval{5000};
+
+        // Slots owned by this submaster. When empty, the submaster owns every
+        // logical slot (single-master mode).
+        std::vector<uint16_t> owned_slots;
+
+        // Optional resolver that recomputes the owned slot set on every
+        // publish. When set, it overrides `owned_slots` and is invoked before
+        // each PublishOnce so ownership tracks cluster membership changes
+        // (dynamic partition). An empty result means the submaster owns no
+        // slot. The callback must be safe to invoke from the heartbeat thread.
+        std::function<std::vector<uint16_t>()> dynamic_slot_resolver;
+
+        // Optional etcd lease id. When non-zero, each slot record is written
+        // with this lease so it is auto-deleted when the lease expires (master
+        // death), letting the dynamic partition rebalance the freed slots.
+        // When zero, slot ownership is a persistent fact re-affirmed by each
+        // heartbeat (single-master fallback).
+        EtcdLeaseId lease_id{0};
+
+        // Optional hooks fired on slot ownership change (P4). on_slot_acquired
+        // materializes object metadata for a newly-owned slot (no-op when it
+        // already arrived via the standby-restore path); on_slot_released drops
+        // it. Leave empty for ownership-publishing-only behavior.
+        std::function<void(uint16_t)> on_slot_acquired;
+        std::function<void(uint16_t)> on_slot_released;
+    };
+
+    explicit SlotOwnerHeartbeat(Config config);
+    ~SlotOwnerHeartbeat();
+
+    SlotOwnerHeartbeat(const SlotOwnerHeartbeat&) = delete;
+    SlotOwnerHeartbeat& operator=(const SlotOwnerHeartbeat&) = delete;
+
+    ErrorCode Start();
+    void Stop();
+
+    // Writes a `SlotOwner` record for every owned slot once. Idempotent; safe
+    // to call from the heartbeat thread or externally.
+    ErrorCode PublishOnce();
+
+   private:
+    void RunLoop();
+
+    Config config_;
+    std::vector<uint16_t> owned_slots_;
+    // Owns the slot handoff state machine (kMigrating -> kStable / release).
+    SlotMigrator migrator_;
+
+    std::atomic<bool> running_{false};
+    std::mutex stop_mutex_;
+    std::condition_variable stop_cv_;
+    std::thread thread_;
+};
+
+}  // namespace cvm
+}  // namespace mooncake
diff --git a/mooncake-store/include/degrading_policy_engine.h b/mooncake-store/include/degrading_policy_engine.h
new file mode 100644
index 0000000000..083068256e
--- /dev/null
+++ b/mooncake-store/include/degrading_policy_engine.h
@@ -0,0 +1,2 @@
+#pragma once
+#include "io_pattern/degrading_policy_engine.h"
diff --git a/mooncake-store/include/etcd_helper.h b/mooncake-store/include/etcd_helper.h
index 225ed6f4c3..afd24c4187 100644
--- a/mooncake-store/include/etcd_helper.h
+++ b/mooncake-store/include/etcd_helper.h
@@ -71,6 +71,18 @@ class EtcdHelper {
     static ErrorCode BatchCreate(const std::vector<std::string>& keys,
                                  const std::vector<std::string>& values);
 
+    /*
+     * @brief Atomically put a batch of key-value pairs in a single txn, all
+     *        bound to the given lease. Returns OK if all writes committed,
+     *        ETCD_OPERATION_ERROR otherwise. Caller is responsible for fencing
+     *        (the keys must already be absent / owned by self) before calling;
+     *        it never checks existence, so it can also be reused to reaffirm
+     *        existing lease-bound keys.
+     */
+    static ErrorCode BatchPutWithLease(const std::vector<std::string>& keys,
+                                       const std::vector<std::string>& values,
+                                       EtcdLeaseId lease_id);
+
     enum class TxnCompareKind {
         kValueEquals = 0,
         kKeyNotExists = 1,
@@ -94,7 +106,9 @@ class EtcdHelper {
      * fail.
      */
     static ErrorCode TxnCompareAndPut(const std::vector<TxnCompare>& compares,
-                                      const std::vector<TxnPut>& puts);
+                                      const std::vector<TxnPut>& puts,
+                                      const std::vector<std::string>&
+                                          delete_keys = {});
 
     /*
      * @brief Grant a lease from the etcd.
diff --git a/mooncake-store/include/eviction_ops.h b/mooncake-store/include/eviction_ops.h
new file mode 100644
index 0000000000..9ef1ade825
--- /dev/null
+++ b/mooncake-store/include/eviction_ops.h
@@ -0,0 +1,3 @@
+#pragma once
+
+#include "io_pattern/ops.h"
diff --git a/mooncake-store/include/feedback.h b/mooncake-store/include/feedback.h
new file mode 100644
index 0000000000..fc5b0e0b5b
--- /dev/null
+++ b/mooncake-store/include/feedback.h
@@ -0,0 +1,2 @@
+#pragma once
+#include "io_pattern/feedback.h"
diff --git a/mooncake-store/include/ha/ha_types.h b/mooncake-store/include/ha/ha_types.h
index 7c065724e8..ea934c8b52 100644
--- a/mooncake-store/include/ha/ha_types.h
+++ b/mooncake-store/include/ha/ha_types.h
@@ -93,6 +93,15 @@ struct MasterView {
     ViewVersionId view_version = 0;
 };
 
+// A single submaster replay source for a standby. master_id doubles as the
+// per-source OpLog namespace (see ha/oplog/oplog_batch_types.h).
+struct MasterSource {
+    std::string master_id;
+    std::string address;
+};
+
+using MasterSources = std::vector<MasterSource>;
+
 struct LeadershipSession {
     MasterView view;
     // Backend-issued opaque ownership token. Only the backend that created
diff --git a/mooncake-store/include/ha/oplog/oplog_batch_standby_reader.h b/mooncake-store/include/ha/oplog/oplog_batch_standby_reader.h
index 94277049c2..4945858523 100644
--- a/mooncake-store/include/ha/oplog/oplog_batch_standby_reader.h
+++ b/mooncake-store/include/ha/oplog/oplog_batch_standby_reader.h
@@ -31,7 +31,8 @@ struct OpLogBatchStandbyPollResult {
 class OpLogBatchStandbyReader {
    public:
     OpLogBatchStandbyReader(std::string cluster_id, HaKvBackend& backend,
-                            OpLogApplier& applier);
+                            OpLogApplier& applier,
+                            std::string source_id = std::string());
 
     OpLogBatchStandbyPollResult PollOnce(size_t max_batches = 1024);
 
diff --git a/mooncake-store/include/ha/oplog/oplog_batch_storage.h b/mooncake-store/include/ha/oplog/oplog_batch_storage.h
index 7ed3880133..2d13edca90 100644
--- a/mooncake-store/include/ha/oplog/oplog_batch_storage.h
+++ b/mooncake-store/include/ha/oplog/oplog_batch_storage.h
@@ -11,7 +11,11 @@ namespace mooncake {
 
 class OpLogBatchStorage {
    public:
-    OpLogBatchStorage(std::string cluster_id, HaKvBackend& backend);
+    // source_id is the stable master id of the submaster owning this OpLog
+    // stream. When empty, the legacy cluster-level (single-source) layout is
+    // used; when non-empty, keys are namespaced per source.
+    OpLogBatchStorage(std::string cluster_id, HaKvBackend& backend,
+                      std::string source_id = std::string());
 
     ErrorCode InitDurablePrefix(DurablePrefix& prefix);
     ErrorCode ReadDurablePrefix(DurablePrefix& prefix);
@@ -26,6 +30,7 @@ class OpLogBatchStorage {
     ErrorCode RejectLegacyLayout() const;
 
     std::string cluster_id_;
+    std::string source_id_;
     HaKvBackend& backend_;
     bool cluster_id_valid_{false};
 };
diff --git a/mooncake-store/include/ha/oplog/oplog_batch_types.h b/mooncake-store/include/ha/oplog/oplog_batch_types.h
index 4e315383c1..36c3bba00c 100644
--- a/mooncake-store/include/ha/oplog/oplog_batch_types.h
+++ b/mooncake-store/include/ha/oplog/oplog_batch_types.h
@@ -41,10 +41,20 @@ bool ValidateOpLogBatchClusterId(const std::string& cluster_id,
                                  std::string* reason = nullptr);
 
 std::string FormatOpLogBatchId(uint64_t batch_id);
-std::string BuildBatchRecordKey(const std::string& cluster_id,
-                                uint64_t batch_id);
-std::string BuildDurablePrefixKey(const std::string& cluster_id);
-BatchRecordRange BuildBatchRecordRange(const std::string& cluster_id,
-                                       uint64_t after_batch_id);
+
+// source_id is the stable master id of the submaster that owns this OpLog
+// stream. When empty, the legacy cluster-level (single-source) layout is used:
+//   /oplog/<cluster_id>/durable_prefix
+//   /oplog/<cluster_id>/batches/<batch_id>
+// When non-empty, the per-source layout is used:
+//   /oplog/<cluster_id>/<source_id>/durable_prefix
+//   /oplog/<cluster_id>/<source_id>/batches/<batch_id>
+std::string BuildBatchRecordKey(const std::string& cluster_id, uint64_t batch_id,
+                                const std::string& source_id = std::string());
+std::string BuildDurablePrefixKey(
+    const std::string& cluster_id, const std::string& source_id = std::string());
+BatchRecordRange BuildBatchRecordRange(
+    const std::string& cluster_id, uint64_t after_batch_id,
+    const std::string& source_id = std::string());
 
 }  // namespace mooncake
diff --git a/mooncake-store/include/ha/standby_controller.h b/mooncake-store/include/ha/standby_controller.h
index f6b738a713..4cd9b48795 100644
--- a/mooncake-store/include/ha/standby_controller.h
+++ b/mooncake-store/include/ha/standby_controller.h
@@ -31,8 +31,7 @@ class StandbyController {
 
     virtual ~StandbyController() = default;
 
-    virtual ErrorCode StartStandby(
-        const std::optional<MasterView>& observed_leader) = 0;
+    virtual ErrorCode StartStandby(const MasterSources& sources) = 0;
 
     virtual void StopStandby() = 0;
 
@@ -47,8 +46,7 @@ class StandbyController {
     virtual tl::expected<PromotionContext, ErrorCode>
     PromoteStandbyAndExport() = 0;
 
-    virtual void UpdateObservedLeader(
-        const std::optional<MasterView>& observed_leader) = 0;
+    virtual void UpdateObservedLeader(const MasterSources& sources) = 0;
 
     virtual MasterRuntimeState GetStandbyRuntimeState() const = 0;
 
diff --git a/mooncake-store/include/hot_standby_service.h b/mooncake-store/include/hot_standby_service.h
index f89bd76c0f..f3fb95b2c2 100644
--- a/mooncake-store/include/hot_standby_service.h
+++ b/mooncake-store/include/hot_standby_service.h
@@ -14,6 +14,7 @@
 #include <vector>
 
 #include "metadata_store.h"
+#include "ha/ha_types.h"
 #include "ha/oplog/oplog_applier.h"
 #include "ha/oplog/oplog_types.h"
 #include "ha/snapshot/snapshot_provider.h"
@@ -34,6 +35,9 @@ enum class OpLogBatchStandbyPollDisposition;
 struct HotStandbyConfig {
     std::string standby_id;
     std::string primary_address;
+    // Submaster replay sources (one per submaster). When empty, this standby
+    // has no OpLog source to follow.
+    std::vector<ha::MasterSource> sources;
     uint32_t replication_port{0};
     uint32_t verification_interval_sec{30};
     uint32_t max_replication_lag_entries{1000};
@@ -89,16 +93,33 @@ class HotStandbyService {
     /**
      * @brief Start standby runtime: snapshot bootstrap plus optional OpLog
      * following
-     * @param primary_address Address of the Primary Master (not used with
-     * OpLog backend-based sync)
+     * @param sources Submaster replay sources (one per submaster); each source's
+     * master_id namespaces its own OpLog stream
      * @param oplog_endpoints Comma-separated OpLog backend endpoints
      * @param cluster_id Cluster identifier for OpLog path
      * @return ErrorCode::OK on success
      */
-    ErrorCode Start(const std::string& primary_address,
+    ErrorCode Start(const std::vector<ha::MasterSource>& sources,
                     const std::string& oplog_endpoints,
                     const std::string& cluster_id);
 
+    /**
+     * @brief Re-bind replay sources while keeping the accumulated metadata.
+     *
+     * Under dynamic binding (2c) a standby's responsible slot range changes as
+     * the cluster membership changes, so its replay source set must follow. If
+     * the standby is not yet running this is equivalent to Start(); if it is
+     * running and the source set is unchanged it is a no-op; otherwise it stops
+     * and restarts the replication loop with the new source set. The shared
+     * metadata_store_ is preserved across the restart, so already-replayed
+     * object metadata is not lost.
+     *
+     * @return ErrorCode::OK on success
+     */
+    ErrorCode UpdateSources(const std::vector<ha::MasterSource>& sources,
+                            const std::string& oplog_endpoints,
+                            const std::string& cluster_id);
+
     /**
      * @brief Stop replication and disconnect from Primary
      */
@@ -201,6 +222,7 @@ class HotStandbyService {
     ErrorCode StartOplogFollowingLocked(uint64_t baseline_seq_id);
     void ActivateSnapshotOnlyStandbyLocked(uint64_t baseline_seq_id);
     uint64_t GetLocalLastAppliedSequenceIdLocked() const;
+    void CollectSegmentsLocked(std::vector<StandbySegmentInfo>& out) const;
     ErrorCode FinalCatchUpForPromotionLocked(uint64_t current_applied_seq_id);
     ErrorCode FinalCatchUpBatchRecordsLocked(HaKvBackend& backend);
     void StopReplicationLoop();
@@ -257,10 +279,18 @@ class HotStandbyService {
     std::unique_ptr<SnapshotProvider> snapshot_provider_{
         std::make_unique<NoopSnapshotProvider>()};
 
-    // OpLog replication components
-    std::unique_ptr<OpLogApplier> oplog_applier_;
+    // Segment baseline loaded from snapshot bootstrap, applied to each
+    // per-source applier when OpLog following starts.
+    std::vector<StandbySegmentInfo> baseline_segments_;
+
+    // Per-source OpLog replication components. Keyed by source master_id. All
+    // appliers share the single metadata_store_ (sources own disjoint slots).
+    struct SourceReplica {
+        std::unique_ptr<OpLogApplier> applier;
+        std::unique_ptr<OpLogBatchStandbyReader> reader;
+    };
+    std::unordered_map<std::string, SourceReplica> sources_;
     std::shared_ptr<HaKvBackend> batch_standby_kv_backend_;
-    std::unique_ptr<OpLogBatchStandbyReader> batch_standby_reader_;
 
     std::shared_ptr<HaKvBackend> catch_up_batch_kv_backend_for_testing_;
 
diff --git a/mooncake-store/include/io_pattern.h b/mooncake-store/include/io_pattern.h
new file mode 100644
index 0000000000..b382ec908e
--- /dev/null
+++ b/mooncake-store/include/io_pattern.h
@@ -0,0 +1,3 @@
+#pragma once
+
+#include "io_pattern/io_pattern.h"
diff --git a/mooncake-store/include/io_pattern/analyzer.h b/mooncake-store/include/io_pattern/analyzer.h
new file mode 100644
index 0000000000..1b5e8b6682
--- /dev/null
+++ b/mooncake-store/include/io_pattern/analyzer.h
@@ -0,0 +1,19 @@
+#pragma once
+
+#include "io_pattern/types.h"
+
+namespace mooncake::io_pattern {
+
+// Converts an immutable snapshot into workload and per-object features.
+class IoPatternAnalyzer {
+   public:
+    virtual ~IoPatternAnalyzer() = default;
+
+    virtual PatternResult Analyze(const IoPatternSnapshot& snapshot) const = 0;
+    virtual WorkloadType DetectWorkloadType(
+        const IoPatternSnapshot& snapshot) const = 0;
+    virtual float CalculateConfidence(
+        const ObjectRef& object, const IoPatternSnapshot& snapshot) const = 0;
+};
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/include/io_pattern/cfm_channel.h b/mooncake-store/include/io_pattern/cfm_channel.h
new file mode 100644
index 0000000000..1ba0886a1c
--- /dev/null
+++ b/mooncake-store/include/io_pattern/cfm_channel.h
@@ -0,0 +1,26 @@
+#pragma once
+
+#include <optional>
+#include <utility>
+
+#include "reporter.h"
+#include "types.h"
+#include "../types.h"
+
+namespace mooncake::io_pattern {
+
+// Transport-neutral CFM reporting channel. In the embedded architecture a
+// SubMaster owns CFM for the keys in its slots, so a channel delivers reports
+// (snapshots and metric batches) and explicit prefetch plans to the owning
+// SubMaster endpoint. There is no policy polling or delivery acknowledgement
+// loop: the receiver merges reports into its local runtime and policy
+// commands execute on the SubMaster that owns the reported keys.
+class CfmChannel {
+   public:
+    virtual ~CfmChannel() = default;
+    virtual bool SendSnapshot(const IoPatternSnapshot& snapshot) = 0;
+    virtual bool SendMetricBatch(const MetricBatch& batch) = 0;
+    virtual ErrorCode ExecutePrefetch(const PrefetchPlan& plan) = 0;
+};
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/include/io_pattern/cfm_client_impl.h b/mooncake-store/include/io_pattern/cfm_client_impl.h
new file mode 100644
index 0000000000..ed19094fb4
--- /dev/null
+++ b/mooncake-store/include/io_pattern/cfm_client_impl.h
@@ -0,0 +1,28 @@
+#pragma once
+
+#include <memory>
+#include <utility>
+
+#include "cfm_channel.h"
+#include "client.h"
+
+namespace mooncake::io_pattern {
+
+// Reporting client used by inference-side connectors and integration tests.
+// Network behavior is delegated to the injected channel; the client is what a
+// vLLM/SGLang connector sees when it reports IO Pattern observations for keys
+// owned by the addressed SubMaster.
+class CfmClientImpl final : public CfmClient {
+   public:
+    explicit CfmClientImpl(std::shared_ptr<CfmChannel> channel)
+        : channel_(std::move(channel)) {}
+
+    ErrorCode ReportSnapshot(const IoPatternSnapshot& snapshot) override;
+    ErrorCode ReportMetricBatch(const MetricBatch& batch) override;
+    ErrorCode ExecutePrefetch(const PrefetchPlan& plan) override;
+
+   private:
+    std::shared_ptr<CfmChannel> channel_;
+};
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/include/io_pattern/cfm_ingress.h b/mooncake-store/include/io_pattern/cfm_ingress.h
new file mode 100644
index 0000000000..f11a33079b
--- /dev/null
+++ b/mooncake-store/include/io_pattern/cfm_ingress.h
@@ -0,0 +1,28 @@
+#pragma once
+
+#include <memory>
+#include <string_view>
+
+#include "cfm_protocol.h"
+#include "runtime.h"
+
+namespace mooncake::io_pattern {
+
+// Server-side counterpart of CfmRpcChannel. Bind Handle() as an
+// InProcessCfmRpcTransport::SendHandler or adapt it to a network RPC server.
+class CfmIngress final {
+   public:
+    explicit CfmIngress(std::shared_ptr<IoPatternRuntime> runtime,
+                        std::shared_ptr<CfmBinaryCodec> codec =
+                            std::make_shared<CfmBinaryCodec>())
+        : runtime_(std::move(runtime)), codec_(std::move(codec)) {}
+
+    bool Handle(std::string_view method, std::string_view payload,
+                std::string_view source_id = {});
+
+   private:
+    std::shared_ptr<IoPatternRuntime> runtime_;
+    std::shared_ptr<CfmBinaryCodec> codec_;
+};
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/include/io_pattern/cfm_ownership_client.h b/mooncake-store/include/io_pattern/cfm_ownership_client.h
new file mode 100644
index 0000000000..837ed81d1c
--- /dev/null
+++ b/mooncake-store/include/io_pattern/cfm_ownership_client.h
@@ -0,0 +1,83 @@
+#pragma once
+
+#include <atomic>
+#include <chrono>
+#include <functional>
+#include <memory>
+#include <mutex>
+#include <optional>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+#include "client.h"
+#include "cfm_channel.h"
+#include "cfm_protocol.h"
+#include "cfm_service.h"
+#include "reporter.h"
+#include "rpc_transport.h"
+#include "types.h"
+
+namespace mooncake::io_pattern {
+
+// Resolves the SubMaster that owns a reported object. Production callers feed
+// this from the CVM key->slot->submaster mapping (cvm::KeySlot over the etcd
+// /cvm/<ns> master registry) inside the Store client / connector layer;
+// returns the SubMaster's regular coro_rpc endpoint ("host:port"), the same
+// endpoint every other Mooncake RPC of that SubMaster uses.
+using SubmasterEndpointResolver =
+    std::function<std::optional<std::string>(const TenantId&, const std::string&)>;
+
+// Ownership-addressed CFM reporting client.
+//
+// CFM is a component of every SubMaster; there is no standalone CFM Master
+// and no auth token. A caller (inference connector / Store client) observes
+// keys that may live on many SubMasters, so reports are bucketed by the CVM
+// ownership resolver: observations whose key belongs to the same SubMaster are
+// aggregated into one metric batch and delivered to that SubMaster's embedded
+// CFM over its ordinary coro_rpc endpoint. Metrics whose owner cannot be
+// resolved are dropped and counted so callers can degrade instead of guessing.
+class CfmOwnershipClient final : public CfmClient {
+   public:
+    // `resolver` maps a reported object to the owning SubMaster endpoint. It
+    // must be kept up to date with the CVM route (slot rebalance is rare).
+    // `timeout` applies to every RPC.
+    explicit CfmOwnershipClient(SubmasterEndpointResolver resolver,
+                                std::chrono::milliseconds timeout =
+                                    std::chrono::milliseconds(500));
+
+    // Sends the snapshot, grouped by the owning SubMaster of each key.
+    ErrorCode ReportSnapshot(const IoPatternSnapshot& snapshot) override;
+
+    // Sends the metric batch, grouped by the owning SubMaster of each
+    // inference/access object. Storage observations are deliberately not
+    // routed by default: the SubMaster that owns the underlying storage
+    // already reports its own watermark to its local runtime. Benchmark /
+    // simulation callers can enable forward_storage to have the storage
+    // metrics ride along with each owner-addressed report so a remote run can
+    // drive the report-driven eviction dimension.
+    ErrorCode ReportMetricBatch(const MetricBatch& batch) override;
+
+    void set_forward_storage(bool forward) { forward_storage_ = forward; }
+
+    // Sends an explicit prefetch plan to the SubMaster that owns the first
+    // candidate; that SubMaster executes it through its local storage-safe
+    // handlers.
+    ErrorCode ExecutePrefetch(const PrefetchPlan& plan) override;
+
+    // Observations dropped because no owner could be resolved.
+    uint64_t dropped_observations() const;
+
+   private:
+    std::shared_ptr<CfmChannel> ChannelFor(const std::string& endpoint);
+    std::string OwnerEndpoint(const ObjectRef& object) const;
+
+    SubmasterEndpointResolver resolver_;
+    std::chrono::milliseconds timeout_;
+    std::unordered_map<std::string, std::shared_ptr<CfmChannel>> channels_;
+    mutable std::mutex channels_mutex_;
+    std::atomic<uint64_t> dropped_observations_{0};
+    bool forward_storage_{false};
+};
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/include/io_pattern/cfm_protocol.h b/mooncake-store/include/io_pattern/cfm_protocol.h
new file mode 100644
index 0000000000..112e2b46cd
--- /dev/null
+++ b/mooncake-store/include/io_pattern/cfm_protocol.h
@@ -0,0 +1,22 @@
+#pragma once
+
+#include "rpc_transport.h"
+
+namespace mooncake::io_pattern {
+
+// Versioned binary wire codec for the CFM RPC methods. It deliberately owns
+// every serialization detail so transports only deal in method/payload bytes.
+class CfmBinaryCodec final : public CfmRpcCodec {
+   public:
+    std::string EncodeSnapshot(const IoPatternSnapshot& snapshot) const override;
+    std::string EncodePrefetch(const PrefetchPlan& plan) const override;
+    std::string EncodeMetricBatch(const MetricBatch& batch) const override;
+    std::optional<PolicyCommand> DecodePolicy(const std::string& payload) const override;
+
+    std::optional<IoPatternSnapshot> DecodeSnapshot(
+        const std::string& payload) const;
+    std::optional<MetricBatch> DecodeMetricBatch(const std::string& payload) const;
+    std::string EncodePolicy(const PolicyCommand& command) const;
+};
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/include/io_pattern/cfm_service.h b/mooncake-store/include/io_pattern/cfm_service.h
new file mode 100644
index 0000000000..3e57ebbd47
--- /dev/null
+++ b/mooncake-store/include/io_pattern/cfm_service.h
@@ -0,0 +1,67 @@
+#pragma once
+
+#include <chrono>
+#include <cstdint>
+#include <memory>
+#include <optional>
+#include <string>
+#include <string_view>
+#include <utility>
+
+#include "cfm_ingress.h"
+#include "observability.h"
+#include "types.h"
+
+namespace mooncake::io_pattern {
+
+// Embedded CFM endpoint of one SubMaster. There is no standalone CFM Master:
+// every SubMaster runs the full IO Pattern pipeline locally and accepts
+// ownership-addressed metric reports over its regular coro_rpc port (the same
+// endpoint the rest of Mooncake uses). Received batches are merged straight
+// into the local runtime so collection, analysis and policy execution all stay
+// on the SubMaster that owns the reported keys.
+//
+// Reports are addressed by key ownership, so a receiving SubMaster only ever
+// merges observations for keys that belong to its own slots. A separate node
+// identity, delivery queues and a poll/ack loop are therefore unnecessary: the
+// reporting client fans each batch out to the owning SubMaster(s) using the
+// CVM key->slot->submaster mapping.
+class CfmService final {
+   public:
+    explicit CfmService(std::shared_ptr<IoPatternRuntime> runtime);
+
+    // RPC entry point. Supported methods:
+    //   report_metric_batch / report_snapshot  -> merge into the local runtime
+    //   execute_prefetch / execute_policy      -> execute through the local
+    //                                             runtime's storage handlers
+    // `source_id` identifies the reporting process and is used to normalize
+    // remote StorageMetric watermarks.
+    bool Send(std::string_view method, std::string_view payload,
+              std::string_view source_id = {});
+
+    IoPatternSnapshot Snapshot() const;
+    IoPatternObservabilitySnapshot Observability(
+        double window_seconds = 0.0) const;
+
+   private:
+    std::shared_ptr<IoPatternRuntime> runtime_;
+    std::shared_ptr<CfmBinaryCodec> codec_;
+    CfmIngress ingress_;
+};
+
+// coro_rpc-facing adapter. Keeping the RPC signature here lets both the
+// SubMaster server and integration tests register the exact production
+// endpoint.
+class CfmRpcService final {
+   public:
+    explicit CfmRpcService(std::shared_ptr<CfmService> service)
+        : service_(std::move(service)) {}
+
+    bool Send(const std::string& method, const std::string& payload,
+              const std::string& source_id = {});
+
+   private:
+    std::shared_ptr<CfmService> service_;
+};
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/include/io_pattern/client.h b/mooncake-store/include/io_pattern/client.h
new file mode 100644
index 0000000000..bb33442798
--- /dev/null
+++ b/mooncake-store/include/io_pattern/client.h
@@ -0,0 +1,22 @@
+#pragma once
+
+#include "../types.h"
+#include "reporter.h"
+#include "types.h"
+
+namespace mooncake::io_pattern {
+
+// Adapter seam between an inference node and the Cache Flow Manager of the
+// SubMaster(s) that own the reported keys. Reports are sent over the same
+// coro_rpc endpoint every other Mooncake API uses; there is no separate CFM
+// Master and no credential to obtain.
+class CfmClient {
+   public:
+    virtual ~CfmClient() = default;
+
+    virtual ErrorCode ReportSnapshot(const IoPatternSnapshot& snapshot) = 0;
+    virtual ErrorCode ReportMetricBatch(const MetricBatch& batch) = 0;
+    virtual ErrorCode ExecutePrefetch(const PrefetchPlan& plan) = 0;
+};
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/include/io_pattern/collector.h b/mooncake-store/include/io_pattern/collector.h
new file mode 100644
index 0000000000..be43bb69ae
--- /dev/null
+++ b/mooncake-store/include/io_pattern/collector.h
@@ -0,0 +1,20 @@
+#pragma once
+
+#include "io_pattern/types.h"
+
+namespace mooncake::io_pattern {
+
+// Collects non-blocking, already-aggregated observations from data paths.
+class IoPatternCollector {
+   public:
+    virtual ~IoPatternCollector() = default;
+
+    // Implementations must not block the caller on RPC or storage I/O.
+    virtual void ReportInferenceMetrics(const InferenceMetrics& metrics) = 0;
+    virtual void RecordAccess(const std::string& key,
+                              const AccessRecord& record) = 0;
+    virtual void RecordStorageMetric(const StorageMetric& metric) = 0;
+    virtual IoPatternSnapshot GetSnapshot() const = 0;
+};
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/include/io_pattern/collector_impl.h b/mooncake-store/include/io_pattern/collector_impl.h
new file mode 100644
index 0000000000..a25e833fd9
--- /dev/null
+++ b/mooncake-store/include/io_pattern/collector_impl.h
@@ -0,0 +1,88 @@
+#pragma once
+
+#include <deque>
+#include <functional>
+#include <memory>
+#include <mutex>
+#include <unordered_map>
+#include <utility>
+
+#include "collector.h"
+#include "reporter.h"
+
+namespace mooncake::io_pattern {
+
+// Production collector that aggregates observations by tenant and object.
+// It owns only metrics state; reporting to CFM is intentionally external.
+class IoPatternCollectorImpl final : public IoPatternCollector {
+   public:
+    struct Config {
+        size_t max_keys_per_tenant{0};
+        size_t max_total_keys{0};
+        uint64_t access_window_ns{60'000'000'000ULL};
+        uint64_t access_bucket_ns{1'000'000'000ULL};
+        size_t max_access_buckets_per_key{64};
+        std::function<uint64_t()> now_ns;
+    };
+
+    IoPatternCollectorImpl()
+        : IoPatternCollectorImpl(Config{}, nullptr) {}
+    explicit IoPatternCollectorImpl(
+        Config config, std::shared_ptr<IoPatternReporter> reporter = nullptr)
+        : config_(config), reporter_(std::move(reporter)) {}
+    void ReportInferenceMetrics(const InferenceMetrics& metrics) override;
+    void RecordAccess(const std::string& key,
+                      const AccessRecord& record) override;
+    void RecordStorageMetric(const StorageMetric& metric) override;
+    // Ingests a CFM snapshot without replaying it through the asynchronous
+    // reporter. The sender is already the reporting side of that pipeline.
+    void MergeSnapshot(const IoPatternSnapshot& snapshot);
+    // Applies an authoritative tier transition reported by the owner of the
+    // replica metadata (insert, removal, or move between tiers). This is how a
+    // tier bit stops being claimed once the replica is actually gone. Presence
+    // must not be inferred from access recency: a cold key that has simply not
+    // been read has to stay eligible for eviction.
+    void RecordTierEvent(const CacheEvent& event);
+    IoPatternSnapshot GetSnapshot() const override;
+    uint64_t dropped() const;
+    bool degraded() const;
+    bool FlushReports();
+    void StopReports();
+
+   private:
+    struct StorageMetricKey {
+        std::string source_id;
+        CacheTier tier{CacheTier::kL2Segment};
+        bool operator==(const StorageMetricKey&) const = default;
+    };
+    struct StorageMetricKeyHash {
+        size_t operator()(const StorageMetricKey& key) const noexcept {
+            return std::hash<std::string>{}(key.source_id) ^
+                   (static_cast<size_t>(key.tier) << 1);
+        }
+    };
+    struct AccessWindowBucket {
+        uint64_t observed_at_ns{0};
+        uint64_t access_count{0};
+        uint64_t write_count{0};
+        uint64_t overwrite_count{0};
+        uint32_t max_write_batch_size{0};
+    };
+
+    void ApplyAccessWindow(const ObjectRef& object, uint64_t now_ns,
+                           KeyMetrics& metrics) const;
+
+    mutable std::mutex mutex_;
+    Config config_;
+    std::shared_ptr<IoPatternReporter> reporter_;
+    uint64_t dropped_{0};
+    bool degraded_{false};
+    std::unordered_map<ObjectRef, KeyMetrics, ObjectRefHash> key_metrics_;
+    std::unordered_map<ObjectRef, std::deque<AccessWindowBucket>, ObjectRefHash>
+        access_windows_;
+    std::unordered_map<TenantId, size_t, TenantIdHash> tenant_key_counts_;
+    std::unordered_map<StorageMetricKey, StorageMetric, StorageMetricKeyHash>
+        storage_metrics_;
+};
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/include/io_pattern/degrading_policy_engine.h b/mooncake-store/include/io_pattern/degrading_policy_engine.h
new file mode 100644
index 0000000000..f02e1d5b4c
--- /dev/null
+++ b/mooncake-store/include/io_pattern/degrading_policy_engine.h
@@ -0,0 +1,43 @@
+#pragma once
+
+#include <cstddef>
+#include <memory>
+#include <mutex>
+
+#include "policy_engine.h"
+
+namespace mooncake::io_pattern {
+
+// Switches from a primary policy engine to a caller-provided fallback after
+// repeated failures; recovery is explicit to avoid policy oscillation.
+class DegradingPolicyEngine final : public PolicyEngine {
+   public:
+    DegradingPolicyEngine(std::shared_ptr<PolicyEngine> primary,
+                          std::shared_ptr<PolicyEngine> fallback,
+                          size_t failure_threshold = 3)
+        : primary_(std::move(primary)),
+          fallback_(std::move(fallback)),
+          failure_threshold_(failure_threshold) {}
+
+    void RecordFailure();
+    void RecordSuccess();
+    void ForceDegraded(bool degraded);
+    bool degraded() const;
+    size_t consecutive_failures() const;
+
+    EvictionPlan PlanEviction(const PolicyContext&, CacheTier, uint64_t) const override;
+    PrefetchPlan PlanPrefetch(const PolicyContext&, const TraceHistory&) const override;
+    AdmissionResult DecideAdmission(const ObjectRef&, CacheTier,
+                                    const PolicyContext&) const override;
+
+   private:
+    std::shared_ptr<PolicyEngine> Active() const;
+    mutable std::mutex mutex_;
+    std::shared_ptr<PolicyEngine> primary_;
+    std::shared_ptr<PolicyEngine> fallback_;
+    size_t failure_threshold_;
+    size_t consecutive_failures_{0};
+    bool degraded_{false};
+};
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/include/io_pattern/feedback.h b/mooncake-store/include/io_pattern/feedback.h
new file mode 100644
index 0000000000..9801e3a7ed
--- /dev/null
+++ b/mooncake-store/include/io_pattern/feedback.h
@@ -0,0 +1,61 @@
+#pragma once
+
+#include <cstddef>
+#include <deque>
+#include <mutex>
+#include <functional>
+#include <utility>
+
+#include "policy_strategies.h"
+
+namespace mooncake::io_pattern {
+
+struct PolicyFeedbackSample {
+    float hit_rate_delta{0.0F};
+    float eviction_churn{0.0F};
+    float ttft_delta{0.0F};
+    float prefetch_accuracy{0.0F};
+};
+
+struct PolicyFeedbackStats {
+    float hit_rate_delta{0.0F};
+    float eviction_churn{0.0F};
+    float ttft_delta{0.0F};
+    float prefetch_accuracy{0.0F};
+    size_t samples{0};
+};
+
+class PolicyFeedbackWindow final {
+   public:
+    explicit PolicyFeedbackWindow(size_t capacity = 60) : capacity_(capacity) {}
+    void Record(PolicyFeedbackSample sample);
+    PolicyFeedbackStats Snapshot() const;
+
+   private:
+    const size_t capacity_;
+    mutable std::mutex mutex_;
+    std::deque<PolicyFeedbackSample> samples_;
+};
+
+// Conservative tuner: after three consecutive negative hit-rate windows,
+// reduce frequency weight and increase idle weight to curb cache churn.
+class AdaptivePolicyTuner final {
+   public:
+    explicit AdaptivePolicyTuner(size_t negative_windows = 3)
+        : negative_windows_(negative_windows) {}
+    bool Tune(const PolicyFeedbackStats& stats,
+              ScoreBasedEvictionConfig& config);
+    bool conservative() const { return conservative_; }
+    void SetPersistenceCallback(std::function<void(const ScoreBasedEvictionConfig&)>
+                                    callback) {
+        persistence_ = std::move(callback);
+    }
+
+   private:
+    const size_t negative_windows_;
+    size_t negative_streak_{0};
+    bool conservative_{false};
+    std::function<void(const ScoreBasedEvictionConfig&)> persistence_;
+};
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/include/io_pattern/io_pattern.h b/mooncake-store/include/io_pattern/io_pattern.h
new file mode 100644
index 0000000000..103901016b
--- /dev/null
+++ b/mooncake-store/include/io_pattern/io_pattern.h
@@ -0,0 +1,30 @@
+#pragma once
+
+#include "io_pattern/analyzer.h"
+#include "io_pattern/client.h"
+#include "io_pattern/cfm_channel.h"
+#include "io_pattern/cfm_ingress.h"
+#include "io_pattern/cfm_service.h"
+#include "io_pattern/cfm_ownership_client.h"
+#include "io_pattern/cfm_protocol.h"
+#include "io_pattern/cfm_client_impl.h"
+#include "io_pattern/feedback.h"
+#include "io_pattern/degrading_policy_engine.h"
+#include "io_pattern/legacy_eviction_ops.h"
+#include "io_pattern/kmeans_analyzer.h"
+#include "io_pattern/collector.h"
+#include "io_pattern/collector_impl.h"
+#include "io_pattern/ops.h"
+#include "io_pattern/observability.h"
+#include "io_pattern/policy_engine.h"
+#include "io_pattern/reporter.h"
+#include "io_pattern/resilient_analyzer.h"
+#include "io_pattern/rpc_transport.h"
+#include "io_pattern/runtime.h"
+#include "io_pattern/sliding_window_analyzer.h"
+#include "io_pattern/resilient_cfm_channel.h"
+#include "io_pattern/policy_strategies.h"
+#include "io_pattern/registry.h"
+#include "io_pattern/types.h"
+#include "io_pattern/threshold_analyzer.h"
+#include "io_pattern/tier_executor.h"
diff --git a/mooncake-store/include/io_pattern/kmeans_analyzer.h b/mooncake-store/include/io_pattern/kmeans_analyzer.h
new file mode 100644
index 0000000000..73073b543f
--- /dev/null
+++ b/mooncake-store/include/io_pattern/kmeans_analyzer.h
@@ -0,0 +1,29 @@
+#pragma once
+
+#include "threshold_analyzer.h"
+
+namespace mooncake::io_pattern {
+
+// Slow-path workload detector for mixed traffic. It clusters session feature
+// vectors, then maps each centroid to the documented workload templates.
+class KMeansWorkloadAnalyzer final : public IoPatternAnalyzer {
+   public:
+    struct Config {
+        uint32_t iterations{8};
+        ThresholdAnalyzerConfig thresholds{};
+    };
+
+    KMeansWorkloadAnalyzer() = default;
+    explicit KMeansWorkloadAnalyzer(Config config) : config_(config) {}
+
+    PatternResult Analyze(const IoPatternSnapshot& snapshot) const override;
+    WorkloadType DetectWorkloadType(
+        const IoPatternSnapshot& snapshot) const override;
+    float CalculateConfidence(const ObjectRef& object,
+                              const IoPatternSnapshot& snapshot) const override;
+
+   private:
+    Config config_{};
+};
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/include/io_pattern/legacy_eviction_ops.h b/mooncake-store/include/io_pattern/legacy_eviction_ops.h
new file mode 100644
index 0000000000..5145b8bcc1
--- /dev/null
+++ b/mooncake-store/include/io_pattern/legacy_eviction_ops.h
@@ -0,0 +1,24 @@
+#pragma once
+
+#include <memory>
+#include <mutex>
+
+#include "../eviction_strategy.h"
+#include "ops.h"
+
+namespace mooncake::io_pattern {
+
+class LegacyEvictionOps final : public EvictionOps {
+   public:
+    explicit LegacyEvictionOps(std::shared_ptr<mooncake::EvictionStrategy> strategy)
+        : strategy_(std::move(strategy)) {}
+
+    EvictionPlan Evaluate(const PolicyContext& context, CacheTier tier,
+                          uint64_t target_bytes) const override;
+
+   private:
+    std::shared_ptr<mooncake::EvictionStrategy> strategy_;
+    mutable std::mutex mutex_;
+};
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/include/io_pattern/observability.h b/mooncake-store/include/io_pattern/observability.h
new file mode 100644
index 0000000000..2608640686
--- /dev/null
+++ b/mooncake-store/include/io_pattern/observability.h
@@ -0,0 +1,39 @@
+#pragma once
+
+#include <cstdint>
+#include <mutex>
+
+namespace mooncake::io_pattern {
+
+struct IoPatternObservabilitySnapshot {
+    uint64_t collect_latency_us{0};
+    uint64_t analyze_latency_us{0};
+    uint64_t policy_decisions{0};
+    uint64_t strategy_hits{0};
+    uint64_t strategy_trials{0};
+    uint64_t false_positives{0};
+    uint64_t degrade_count{0};
+    uint64_t report_drop_count{0};
+    float strategy_hit_rate{0.0F};
+    float false_positive_rate{0.0F};
+    float policy_decision_qps{0.0F};
+};
+
+// Thread-safe counters for IO Pattern operational metrics.
+class IoPatternObservability final {
+   public:
+    void RecordCollectLatency(uint64_t latency_us);
+    void RecordAnalyzeLatency(uint64_t latency_us);
+    void RecordPolicyDecision(bool strategy_hit);
+    void RecordFalsePositive();
+    void RecordDegrade();
+    void RecordReportDrop(uint64_t count = 1);
+    IoPatternObservabilitySnapshot Snapshot() const;
+    IoPatternObservabilitySnapshot Snapshot(double window_seconds) const;
+
+   private:
+    mutable std::mutex mutex_;
+    IoPatternObservabilitySnapshot values_;
+};
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/include/io_pattern/ops.h b/mooncake-store/include/io_pattern/ops.h
new file mode 100644
index 0000000000..fbf57ac869
--- /dev/null
+++ b/mooncake-store/include/io_pattern/ops.h
@@ -0,0 +1,51 @@
+#pragma once
+
+#include <cstdint>
+
+#include "io_pattern/types.h"
+#include "../types.h"
+
+namespace mooncake::io_pattern {
+
+// Produces an eviction plan; it does not move or delete data.
+class EvictionOps {
+   public:
+    virtual ~EvictionOps() = default;
+
+    // Returns a complete plan carrying tenant, score and byte metadata.
+    virtual EvictionPlan Evaluate(const PolicyContext& context, CacheTier tier,
+                                  uint64_t target_bytes) const = 0;
+
+};
+
+// Produces a prefetch plan; execution belongs to PrefetchExecutor.
+class PrefetchOps {
+   public:
+    virtual ~PrefetchOps() = default;
+
+    // Returns a complete plan carrying strategy, timeout and confidence.
+    virtual PrefetchPlan Evaluate(const PolicyContext& context,
+                                  const TraceHistory& trace) const = 0;
+};
+
+// Decides whether an object may enter a target tier.
+class AdmissionOps {
+   public:
+    virtual ~AdmissionOps() = default;
+
+    // Returns a complete decision carrying tenant identity and confidence.
+    virtual AdmissionResult Evaluate(const ObjectRef& object,
+                                     CacheTier target_tier,
+                                     const PolicyContext& context) const = 0;
+};
+
+// Data movement is a client-side seam. Keeping it separate prevents a
+// SubMaster-side prefetch planner from depending on a concrete storage client.
+class PrefetchExecutor {
+   public:
+    virtual ~PrefetchExecutor() = default;
+
+    virtual ErrorCode Execute(const PrefetchPlan& plan) = 0;
+};
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/include/io_pattern/policy_engine.h b/mooncake-store/include/io_pattern/policy_engine.h
new file mode 100644
index 0000000000..b089d3a569
--- /dev/null
+++ b/mooncake-store/include/io_pattern/policy_engine.h
@@ -0,0 +1,373 @@
+#pragma once
+
+#include <algorithm>
+#include <cstdint>
+#include <memory>
+#include <mutex>
+#include <optional>
+#include <shared_mutex>
+#include <utility>
+#include <unordered_map>
+
+#include "io_pattern/ops.h"
+#include "io_pattern/policy_strategies.h"
+#include "io_pattern/registry.h"
+#include "io_pattern/types.h"
+
+namespace mooncake::io_pattern {
+
+// Coordinates configured Ops implementations without owning data-path state.
+class PolicyEngine {
+   public:
+    virtual ~PolicyEngine() = default;
+
+    virtual EvictionPlan PlanEviction(const PolicyContext& context,
+                                      CacheTier tier,
+                                      uint64_t target_bytes) const = 0;
+    virtual PrefetchPlan PlanPrefetch(const PolicyContext& context,
+                                     const TraceHistory& trace) const = 0;
+    virtual AdmissionResult DecideAdmission(
+        const ObjectRef& object, CacheTier target_tier,
+        const PolicyContext& context) const = 0;
+
+    // Executes the three policy dimensions through one uniform result seam.
+    // Eviction and admission target different tiers: an eviction plan reclaims
+    // from `eviction_tier`, while each admission decides whether an object may
+    // enter `admission_tier`. The two are passed separately because using the
+    // eviction tier as the admission target silently applied the eviction tier's
+    // watermark and prefix gates to the promotion decision.
+    virtual PolicyResult ExecutePolicy(const PolicyContext& context,
+                                       CacheTier eviction_tier,
+                                       uint64_t eviction_bytes,
+                                       CacheTier admission_tier,
+                                       const TraceHistory& trace,
+                                       const std::vector<ObjectRef>& admissions = {}) const {
+        PolicyResult result;
+        result.eviction = PlanEviction(context, eviction_tier, eviction_bytes);
+        result.prefetch = PlanPrefetch(context, trace);
+        for (const auto& object : admissions) {
+            result.admissions.push_back(
+                DecideAdmission(object, admission_tier, context));
+        }
+        return result;
+    }
+};
+
+// A small composition adapter that wires selected Ops instances together.
+// Missing optional Ops degrade to empty plans or a deferred admission result.
+class ComposedPolicyEngine final : public PolicyEngine {
+   public:
+    ComposedPolicyEngine(std::shared_ptr<EvictionOps> eviction,
+                         std::shared_ptr<PrefetchOps> prefetch,
+                         std::shared_ptr<AdmissionOps> admission)
+        : eviction_(std::move(eviction)),
+          prefetch_(std::move(prefetch)),
+          admission_(std::move(admission)) {}
+
+    EvictionPlan PlanEviction(const PolicyContext& context, CacheTier tier,
+                              uint64_t target_bytes) const override {
+        if (!eviction_) {
+            return EvictionPlan{.source_tier = tier,
+                                 .target_bytes = target_bytes};
+        }
+        return eviction_->Evaluate(context, tier, target_bytes);
+    }
+
+    PrefetchPlan PlanPrefetch(const PolicyContext& context,
+                              const TraceHistory& trace) const override {
+        if (!prefetch_) {
+            return {};
+        }
+        return prefetch_->Evaluate(context, trace);
+    }
+
+    AdmissionResult DecideAdmission(const ObjectRef& object,
+                                    CacheTier target_tier,
+                                    const PolicyContext& context) const override {
+        if (!admission_) {
+            return AdmissionResult{.object = object,
+                                    .target_tier = target_tier};
+        }
+        return admission_->Evaluate(object, target_tier, context);
+    }
+
+   private:
+    std::shared_ptr<EvictionOps> eviction_;
+    std::shared_ptr<PrefetchOps> prefetch_;
+    std::shared_ptr<AdmissionOps> admission_;
+};
+
+// Resolves Ops implementations by registry name and composes them for one
+// policy execution. Factories are consulted per call to avoid shared state.
+class RegistryPolicyEngine final : public PolicyEngine {
+   public:
+    RegistryPolicyEngine(std::shared_ptr<PolicyOpsRegistries> registries,
+                         std::string eviction_name,
+                         std::string prefetch_name,
+                         std::string admission_name)
+        : registries_(std::move(registries)),
+          eviction_name_(std::move(eviction_name)),
+          prefetch_name_(std::move(prefetch_name)),
+          admission_name_(std::move(admission_name)) {}
+
+    EvictionPlan PlanEviction(const PolicyContext& context, CacheTier tier,
+                              uint64_t bytes) const override {
+        auto engine = Compose();
+        return engine->PlanEviction(context, tier, bytes);
+    }
+    PrefetchPlan PlanPrefetch(const PolicyContext& context,
+                              const TraceHistory& trace) const override {
+        return Compose()->PlanPrefetch(context, trace);
+    }
+    AdmissionResult DecideAdmission(const ObjectRef& object, CacheTier tier,
+                                    const PolicyContext& context) const override {
+        return Compose()->DecideAdmission(object, tier, context);
+    }
+
+    PolicyResult ExecutePolicy(const PolicyContext& context,
+                               CacheTier tier, uint64_t bytes,
+                               CacheTier admission_tier,
+                               const TraceHistory& trace,
+                               const std::vector<ObjectRef>& admissions = {}) const override {
+        auto result = PolicyEngine::ExecutePolicy(
+            context, tier, bytes, admission_tier, trace, admissions);
+        std::shared_lock lock(mutex_);
+        result.degraded = !registries_ ||
+                          !registries_->eviction.Create(eviction_name_) ||
+                          !registries_->prefetch.Create(prefetch_name_) ||
+                          !registries_->admission.Create(admission_name_);
+        return result;
+    }
+
+   private:
+    std::shared_ptr<ComposedPolicyEngine> Compose() const {
+        if (!registries_) return std::make_shared<ComposedPolicyEngine>(nullptr, nullptr, nullptr);
+        return std::make_shared<ComposedPolicyEngine>(
+            registries_->eviction.Create(eviction_name_),
+            registries_->prefetch.Create(prefetch_name_),
+            registries_->admission.Create(admission_name_));
+    }
+
+    std::shared_ptr<PolicyOpsRegistries> registries_;
+    mutable std::shared_mutex mutex_;
+    std::string eviction_name_;
+    std::string prefetch_name_;
+    std::string admission_name_;
+};
+
+// Selects the documented policy template for the current workload.
+class WorkloadPolicyEngine final : public PolicyEngine {
+   public:
+    explicit WorkloadPolicyEngine(WorkloadType type = WorkloadType::kMixed,
+                                  uint32_t transition_windows = 3,
+                                  float admission_watermark_ratio = 0.90F,
+                                  uint32_t admission_frequency_threshold = 2)
+        : transition_windows_(transition_windows), workload_type_(type),
+          previous_type_(type),
+          admission_watermark_ratio_(admission_watermark_ratio),
+          admission_frequency_threshold_(admission_frequency_threshold) {
+        Configure(type);
+    }
+
+    void SetWorkloadType(WorkloadType type) {
+        std::unique_lock lock(mutex_);
+        if (type == workload_type_) return;
+        previous_type_ = workload_type_;
+        previous_eviction_ = active_eviction_;
+        workload_type_ = type;
+        transition_progress_ = transition_windows_ == 0 ? 1.0F : 0.0F;
+        Configure(type);
+    }
+
+    WorkloadType ActiveWorkload() const {
+        std::shared_lock lock(mutex_);
+        return workload_type_;
+    }
+
+    float TransitionProgress() const {
+        std::shared_lock lock(mutex_);
+        return transition_progress_;
+    }
+
+    // Advances the template transition by one completed detection window.
+    void AdvanceTransitionWindow() {
+        std::unique_lock lock(mutex_);
+        if (transition_progress_ < 1.0F && transition_windows_ != 0) {
+            transition_progress_ = std::min(
+                1.0F, transition_progress_ + 1.0F /
+                                  static_cast<float>(transition_windows_));
+        }
+    }
+
+    void SetSessionWorkloads(const std::vector<SessionPattern>& sessions) {
+        std::unique_lock lock(mutex_);
+        session_engines_.clear();
+        session_types_.clear();
+        for (const auto& session : sessions) {
+            if (!session.session_id.empty()) {
+                session_engines_[session.session_id] = MakeEngine(session.workload_type);
+                session_types_[session.session_id] = session.workload_type;
+            }
+        }
+    }
+
+    ScoreBasedEvictionConfig CurrentEvictionConfig() const {
+        std::shared_lock lock(mutex_);
+        return active_eviction_;
+    }
+
+    void ApplyEvictionTuning(const ScoreBasedEvictionConfig& config) {
+        std::unique_lock lock(mutex_);
+        tuned_eviction_ = config;
+        Configure(workload_type_);
+        for (auto& [session, engine] : session_engines_) {
+            engine = MakeEngine(session_types_.at(session));
+        }
+    }
+
+    EvictionPlan PlanEviction(const PolicyContext& context, CacheTier tier,
+                              uint64_t target_bytes) const override {
+        std::shared_lock lock(mutex_);
+        if (context.session_id.empty() && transition_progress_ < 1.0F) {
+            auto blended = MakeEngine(
+                workload_type_, Blend(previous_eviction_, active_eviction_,
+                                      transition_progress_));
+            return blended->PlanEviction(context, tier, target_bytes);
+        }
+        return SelectEngine(context)->PlanEviction(context, tier, target_bytes);
+    }
+    PrefetchPlan PlanPrefetch(const PolicyContext& context,
+                              const TraceHistory& trace) const override {
+        std::shared_lock lock(mutex_);
+        return SelectEngine(context)->PlanPrefetch(context, trace);
+    }
+    AdmissionResult DecideAdmission(const ObjectRef& object,
+                                    CacheTier tier,
+                                    const PolicyContext& context) const override {
+        std::shared_lock lock(mutex_);
+        return SelectEngine(context)->DecideAdmission(object, tier, context);
+    }
+
+   private:
+    void Configure(WorkloadType type) {
+        engine_ = MakeEngine(type);
+        active_eviction_ = EvictionConfigFor(type);
+        if (tuned_eviction_) active_eviction_ = *tuned_eviction_;
+    }
+
+    ScoreBasedEvictionConfig EvictionConfigFor(WorkloadType type) const {
+        ScoreBasedEvictionConfig eviction;
+        switch (type) {
+            case WorkloadType::kCodeAgent:
+                eviction.idle_weight = 0.8F;
+                eviction.frequency_weight = 0.2F;
+                eviction.prefix_weight = 0.3F;
+                eviction.tier_down_mode = TierDownMode::kSkipHost;
+                break;
+            case WorkloadType::kGenerativeRecommendation:
+                eviction.idle_weight = 0.3F;
+                eviction.frequency_weight = 0.8F;
+                eviction.prefix_weight = 0.2F;
+                eviction.tier_down_mode = TierDownMode::kStepwise;
+                break;
+            case WorkloadType::kMultiTurnConversation:
+                eviction.idle_weight = 0.5F;
+                eviction.frequency_weight = 0.4F;
+                eviction.prefix_weight = 0.6F;
+                eviction.tier_down_mode = TierDownMode::kPrefixAffinity;
+                break;
+            case WorkloadType::kUnknown:
+            case WorkloadType::kMixed:
+                break;
+        }
+        return eviction;
+    }
+
+    static ScoreBasedEvictionConfig Blend(const ScoreBasedEvictionConfig& from,
+                                          const ScoreBasedEvictionConfig& to,
+                                          float progress) {
+        const auto blend = [progress](float old_value, float new_value) {
+            return old_value * (1.0F - progress) + new_value * progress;
+        };
+        ScoreBasedEvictionConfig result = to;
+        result.idle_weight = blend(from.idle_weight, to.idle_weight);
+        result.frequency_weight = blend(from.frequency_weight, to.frequency_weight);
+        result.prefix_weight = blend(from.prefix_weight, to.prefix_weight);
+        result.recompute_weight = blend(from.recompute_weight, to.recompute_weight);
+        result.lower_replica_weight =
+            blend(from.lower_replica_weight, to.lower_replica_weight);
+        result.other_replica_weight =
+            blend(from.other_replica_weight, to.other_replica_weight);
+        // Tier routing is categorical, so switch at the midpoint while the
+        // numerical eviction weights transition continuously.
+        result.tier_down_mode = progress < 0.5F ? from.tier_down_mode
+                                                : to.tier_down_mode;
+        return result;
+    }
+
+    std::shared_ptr<ComposedPolicyEngine> MakeEngine(
+        WorkloadType type,
+        std::optional<ScoreBasedEvictionConfig> eviction_override = std::nullopt) const {
+        ScoreBasedEvictionConfig eviction =
+            eviction_override.value_or(EvictionConfigFor(type));
+        PrefixMatchAdmissionConfig admission;
+        // Applied before the per-workload switch, so a template that states its
+        // own frequency gate (generative recommendation) still wins.
+        admission.frequency_threshold = admission_frequency_threshold_;
+        TraceBasedPrefetchConfig prefetch;
+        switch (type) {
+            case WorkloadType::kCodeAgent:
+                prefetch.match_length_threshold = 512;
+                break;
+            case WorkloadType::kGenerativeRecommendation:
+                admission.frequency_threshold = 20;
+                prefetch.match_length_threshold = 64;
+                prefetch.strategy = PrefetchStrategy::kWaitComplete;
+                break;
+            case WorkloadType::kMultiTurnConversation:
+                prefetch.match_length_threshold = 256;
+                prefetch.strategy = PrefetchStrategy::kTimeout;
+                prefetch.timeout_us = 5000;
+                break;
+            case WorkloadType::kUnknown:
+            case WorkloadType::kMixed:
+                break;
+        }
+        if (tuned_eviction_ && !eviction_override) eviction = *tuned_eviction_;
+        // Derived from the store's eviction high watermark rather than a fixed
+        // 0.90: admission must stop before eviction starts, otherwise the window
+        // between the two watermarks keeps admitting objects the store is
+        // already reclaiming.
+        admission.max_memory_used_ratio = admission_watermark_ratio_;
+        return std::make_shared<ComposedPolicyEngine>(
+            std::make_shared<ScoreBasedEvictionOps>(eviction),
+            std::make_shared<TraceBasedPrefetchOps>(prefetch),
+            std::make_shared<PrefixMatchAdmissionOps>(admission));
+    }
+
+    std::shared_ptr<ComposedPolicyEngine> SelectEngine(
+        const PolicyContext& context) const {
+        if (!context.session_id.empty()) {
+            const auto it = session_engines_.find(context.session_id);
+            if (it != session_engines_.end()) return it->second;
+        }
+        return engine_;
+    }
+
+    mutable std::shared_mutex mutex_;
+    std::shared_ptr<ComposedPolicyEngine> engine_;
+    std::unordered_map<std::string, std::shared_ptr<ComposedPolicyEngine>>
+        session_engines_;
+    std::unordered_map<std::string, WorkloadType> session_types_;
+    WorkloadType workload_type_{WorkloadType::kUnknown};
+    WorkloadType previous_type_{WorkloadType::kUnknown};
+    uint32_t transition_windows_{3};
+    float transition_progress_{1.0F};
+    std::optional<ScoreBasedEvictionConfig> tuned_eviction_;
+    ScoreBasedEvictionConfig active_eviction_;
+    ScoreBasedEvictionConfig previous_eviction_;
+    float admission_watermark_ratio_{0.90F};
+    uint32_t admission_frequency_threshold_{2};
+};
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/include/io_pattern/policy_strategies.h b/mooncake-store/include/io_pattern/policy_strategies.h
new file mode 100644
index 0000000000..9ce2bbf981
--- /dev/null
+++ b/mooncake-store/include/io_pattern/policy_strategies.h
@@ -0,0 +1,78 @@
+#pragma once
+
+#include "io_pattern/ops.h"
+
+namespace mooncake::io_pattern {
+
+enum class TierDownMode : uint8_t {
+    kStepwise,
+    kSkipHost,
+    kPrefixAffinity,
+};
+
+struct ScoreBasedEvictionConfig {
+    float idle_weight{1.0F};
+    float frequency_weight{1.0F};
+    float prefix_weight{1.0F};
+    float recompute_weight{1.0F};
+    float lower_replica_weight{1.0F};
+    float other_replica_weight{1.0F};
+    TierDownMode tier_down_mode{TierDownMode::kStepwise};
+    uint64_t max_candidates{0};
+};
+
+class ScoreBasedEvictionOps final : public EvictionOps {
+   public:
+    explicit ScoreBasedEvictionOps(ScoreBasedEvictionConfig config = {})
+        : config_(config) {}
+
+    EvictionPlan Evaluate(const PolicyContext& context, CacheTier tier,
+                          uint64_t target_bytes) const override;
+
+   private:
+    ScoreBasedEvictionConfig config_;
+};
+
+struct PrefixMatchAdmissionConfig {
+    uint32_t hbm_match_length{64};
+    // Minimum accesses in the rolling window before an object may be admitted to
+    // a non-HBM tier. Defaults to 2, matching the master's own
+    // promotion_admission_threshold second-touch gate; a threshold of 1 admitted
+    // on first sight and made this gate a no-op.
+    uint64_t frequency_threshold{2};
+    float max_memory_used_ratio{0.90F};
+};
+
+class PrefixMatchAdmissionOps final : public AdmissionOps {
+   public:
+    explicit PrefixMatchAdmissionOps(PrefixMatchAdmissionConfig config = {})
+        : config_(config) {}
+
+    AdmissionResult Evaluate(const ObjectRef& object, CacheTier target_tier,
+                             const PolicyContext& context) const override;
+
+   private:
+    PrefixMatchAdmissionConfig config_;
+};
+
+struct TraceBasedPrefetchConfig {
+    uint32_t match_length_threshold{256};
+    float minimum_confidence{0.6F};
+    uint64_t max_candidates{0};
+    PrefetchStrategy strategy{PrefetchStrategy::kBestEffort};
+    uint64_t timeout_us{0};
+};
+
+class TraceBasedPrefetchOps final : public PrefetchOps {
+   public:
+    explicit TraceBasedPrefetchOps(TraceBasedPrefetchConfig config = {})
+        : config_(config) {}
+
+    PrefetchPlan Evaluate(const PolicyContext& context,
+                          const TraceHistory& trace) const override;
+
+   private:
+    TraceBasedPrefetchConfig config_;
+};
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/include/io_pattern/registry.h b/mooncake-store/include/io_pattern/registry.h
new file mode 100644
index 0000000000..518a2ef3b8
--- /dev/null
+++ b/mooncake-store/include/io_pattern/registry.h
@@ -0,0 +1,69 @@
+#pragma once
+
+#include <algorithm>
+#include <functional>
+#include <memory>
+#include <mutex>
+#include <shared_mutex>
+#include <string>
+#include <string_view>
+#include <unordered_map>
+#include <utility>
+#include <vector>
+
+#include "io_pattern/ops.h"
+
+namespace mooncake::io_pattern {
+
+template <typename Ops>
+class OpsRegistry {
+   public:
+    using Factory = std::function<std::shared_ptr<Ops>()>;
+
+    // Registration is thread-safe; duplicate names are rejected.
+    bool Register(std::string name, Factory factory) {
+        if (name.empty() || !factory) {
+            return false;
+        }
+        std::unique_lock lock(mutex_);
+        return factories_.emplace(std::move(name), std::move(factory)).second;
+    }
+
+    std::shared_ptr<Ops> Create(std::string_view name) const {
+        Factory factory;
+        {
+            std::shared_lock lock(mutex_);
+            const auto it = factories_.find(std::string(name));
+            if (it == factories_.end()) {
+                return nullptr;
+            }
+            factory = it->second;
+        }
+        return factory();
+    }
+
+    std::vector<std::string> RegisteredNames() const {
+        std::vector<std::string> names;
+        {
+            std::shared_lock lock(mutex_);
+            names.reserve(factories_.size());
+            for (const auto& entry : factories_) {
+                names.push_back(entry.first);
+            }
+        }
+        std::sort(names.begin(), names.end());
+        return names;
+    }
+
+   private:
+    mutable std::shared_mutex mutex_;
+    std::unordered_map<std::string, Factory> factories_;
+};
+
+struct PolicyOpsRegistries {
+    OpsRegistry<EvictionOps> eviction;
+    OpsRegistry<PrefetchOps> prefetch;
+    OpsRegistry<AdmissionOps> admission;
+};
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/include/io_pattern/reporter.h b/mooncake-store/include/io_pattern/reporter.h
new file mode 100644
index 0000000000..8926550fa5
--- /dev/null
+++ b/mooncake-store/include/io_pattern/reporter.h
@@ -0,0 +1,72 @@
+#pragma once
+
+#include <cstddef>
+#include <chrono>
+#include <functional>
+#include <mutex>
+#include <vector>
+#include <thread>
+#include <condition_variable>
+#include <unordered_map>
+
+#include "types.h"
+
+namespace mooncake::io_pattern {
+
+struct MetricBatch {
+    std::vector<InferenceMetrics> inference;
+    std::vector<AccessRecord> accesses;
+    std::vector<StorageMetric> storage;
+};
+
+using MetricBatchSink = std::function<bool(const MetricBatch&)>;
+
+class MetricBatchTransport {
+   public:
+    virtual ~MetricBatchTransport() = default;
+    virtual bool Send(const MetricBatch& batch) = 0;
+};
+
+// Bounded, non-blocking metric batching. Transport and RPC ownership remain
+// with the supplied sink.
+class IoPatternReporter final {
+   public:
+    explicit IoPatternReporter(size_t capacity, MetricBatchSink sink,
+                               size_t per_tenant_capacity = 0);
+    ~IoPatternReporter();
+
+    void Start();
+    void Stop();
+
+    bool Enqueue(InferenceMetrics metrics);
+    bool EnqueueAccess(AccessRecord record);
+    bool EnqueueStorage(StorageMetric metric);
+    bool Flush();
+
+    size_t pending() const;
+    uint64_t dropped() const;
+    uint64_t reported() const;
+    void UpdateLoad(float memory_used_ratio, uint64_t rpc_latency_us);
+    std::chrono::milliseconds RecommendedFlushInterval() const;
+
+   private:
+    bool EnqueueImpl(std::function<void(MetricBatch&)> append,
+                     const TenantId& tenant);
+    std::chrono::milliseconds RecommendedFlushIntervalLocked() const;
+
+    const size_t capacity_;
+    const MetricBatchSink sink_;
+    const size_t per_tenant_capacity_;
+    mutable std::mutex mutex_;
+    MetricBatch batch_;
+    uint64_t dropped_{0};
+    uint64_t reported_{0};
+    std::condition_variable condition_;
+    std::thread worker_;
+    bool running_{false};
+    float memory_used_ratio_{0.0F};
+    uint64_t rpc_latency_us_{0};
+    std::unordered_map<TenantId, size_t, TenantIdHash> tenant_pending_;
+};
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/include/io_pattern/resilient_analyzer.h b/mooncake-store/include/io_pattern/resilient_analyzer.h
new file mode 100644
index 0000000000..7f789d97b7
--- /dev/null
+++ b/mooncake-store/include/io_pattern/resilient_analyzer.h
@@ -0,0 +1,40 @@
+#pragma once
+
+#include <memory>
+#include <mutex>
+
+#include "analyzer.h"
+
+namespace mooncake::io_pattern {
+
+class ResilientAnalyzer final : public IoPatternAnalyzer {
+   public:
+    explicit ResilientAnalyzer(std::shared_ptr<IoPatternAnalyzer> primary,
+                               size_t failure_threshold = 3)
+        : primary_(std::move(primary)), failure_threshold_(failure_threshold) {}
+
+    PatternResult Analyze(const IoPatternSnapshot& snapshot) const override;
+    WorkloadType DetectWorkloadType(
+        const IoPatternSnapshot& snapshot) const override;
+    float CalculateConfidence(const ObjectRef& object,
+                              const IoPatternSnapshot& snapshot) const override;
+    bool degraded() const;
+    size_t failures() const;
+    // Returns the most recent safe answer without invoking the primary
+    // analyzer. Used by a bounded caller when its analysis budget expires.
+    PatternResult FallbackResult() const;
+
+   private:
+    void RecordFailure() const;
+    void RecordSuccess(const PatternResult& result) const;
+    PatternResult Fallback() const;
+
+    std::shared_ptr<IoPatternAnalyzer> primary_;
+    const size_t failure_threshold_;
+    mutable std::mutex mutex_;
+    mutable PatternResult last_result_;
+    mutable size_t failures_{0};
+    mutable bool degraded_{false};
+};
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/include/io_pattern/resilient_cfm_channel.h b/mooncake-store/include/io_pattern/resilient_cfm_channel.h
new file mode 100644
index 0000000000..91b6f71dfe
--- /dev/null
+++ b/mooncake-store/include/io_pattern/resilient_cfm_channel.h
@@ -0,0 +1,44 @@
+#pragma once
+
+#include <cstdint>
+#include <memory>
+#include <mutex>
+#include <utility>
+
+#include "cfm_channel.h"
+
+namespace mooncake::io_pattern {
+
+struct CfmRetryConfig {
+    uint32_t max_retries{3};
+    uint32_t degrade_after_failures{3};
+};
+
+// Adds bounded retry and health tracking to any concrete CFM transport.
+class ResilientCfmChannel final : public CfmChannel {
+   public:
+    ResilientCfmChannel(std::shared_ptr<CfmChannel> delegate,
+                        CfmRetryConfig config = {})
+        : delegate_(std::move(delegate)), config_(config) {}
+
+    bool SendSnapshot(const IoPatternSnapshot& snapshot) override;
+    bool SendMetricBatch(const MetricBatch& batch) override;
+    ErrorCode ExecutePrefetch(const PrefetchPlan& plan) override;
+
+    bool degraded() const;
+    uint64_t consecutive_failures() const;
+
+   private:
+    template <typename Operation>
+    bool Retry(Operation&& operation);
+    void RecordSuccess();
+    void RecordFailure();
+
+    std::shared_ptr<CfmChannel> delegate_;
+    CfmRetryConfig config_;
+    mutable std::mutex mutex_;
+    uint64_t consecutive_failures_{0};
+    bool degraded_{false};
+};
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/include/io_pattern/rpc_transport.h b/mooncake-store/include/io_pattern/rpc_transport.h
new file mode 100644
index 0000000000..668d86c1d3
--- /dev/null
+++ b/mooncake-store/include/io_pattern/rpc_transport.h
@@ -0,0 +1,131 @@
+#pragma once
+
+#include <atomic>
+#include <chrono>
+#include <memory>
+#include <mutex>
+#include <optional>
+#include <string>
+#include <string_view>
+#include <functional>
+#include <utility>
+#include <vector>
+
+#include "cfm_channel.h"
+#include "reporter.h"
+
+namespace mooncake::io_pattern {
+
+class CfmRpcCodec {
+   public:
+    virtual ~CfmRpcCodec() = default;
+    virtual std::string EncodeSnapshot(const IoPatternSnapshot&) const = 0;
+    virtual std::string EncodePrefetch(const PrefetchPlan&) const = 0;
+    virtual std::string EncodeMetricBatch(const MetricBatch&) const = 0;
+    virtual std::optional<PolicyCommand> DecodePolicy(
+        const std::string&) const = 0;
+};
+
+// Transport for CFM reports addressed to the SubMaster that owns the reported
+// keys. There is no authentication: Mooncake RPCs run inside the trusted
+// deployment, and CFM is an embedded component of every SubMaster reached over
+// its regular coro_rpc endpoint (the same endpoint all other Mooncake APIs
+// use). Only method/payload delivery is needed because the receiver merges
+// reports into its local runtime instead of maintaining per-node policy
+// queues.
+class CfmRpcTransport {
+   public:
+    virtual ~CfmRpcTransport() = default;
+    virtual bool Send(std::string_view method, std::string_view payload,
+                      std::chrono::milliseconds timeout) = 0;
+};
+
+// Production CFM transport over Mooncake's existing coro_rpc connection pool.
+// It targets the CFM handler registered on the Master RPC service of the
+// SubMaster that owns the reported keys.
+class CoroRpcCfmTransport final : public CfmRpcTransport {
+   public:
+    CoroRpcCfmTransport(std::string endpoint,
+                        std::chrono::milliseconds default_timeout =
+                            std::chrono::milliseconds(500));
+    ~CoroRpcCfmTransport() override;
+
+    bool Send(std::string_view method, std::string_view payload,
+              std::chrono::milliseconds timeout) override;
+
+   private:
+    class Impl;
+    std::unique_ptr<Impl> impl_;
+};
+
+struct CfmRpcConfig {
+    std::chrono::milliseconds timeout{500};
+};
+
+// An in-process CFM endpoint for embedded deployments and integration tests.
+// It is intentionally transport-agnostic at the codec boundary: a
+// socket/HTTP implementation can expose the same method names and wire bytes.
+class InProcessCfmRpcTransport final : public CfmRpcTransport {
+   public:
+    using SendHandler = std::function<bool(std::string_view, std::string_view)>;
+
+    explicit InProcessCfmRpcTransport(SendHandler send_handler = {})
+        : send_handler_(std::move(send_handler)) {}
+
+    bool Send(std::string_view method, std::string_view payload,
+              std::chrono::milliseconds) override;
+
+    void SetSendHandler(SendHandler handler);
+
+   private:
+    mutable std::mutex mutex_;
+    SendHandler send_handler_;
+};
+
+class CfmRpcChannel final : public CfmChannel {
+   public:
+    CfmRpcChannel(std::shared_ptr<CfmRpcTransport> transport,
+                  std::shared_ptr<CfmRpcCodec> codec,
+                  CfmRpcConfig config = {})
+        : transport_(std::move(transport)),
+          codec_(std::move(codec)),
+          config_(config) {}
+
+    bool SendSnapshot(const IoPatternSnapshot& snapshot) override;
+    bool SendMetricBatch(const MetricBatch& batch) override;
+    ErrorCode ExecutePrefetch(const PrefetchPlan& plan) override;
+
+   private:
+    std::shared_ptr<CfmRpcTransport> transport_;
+    std::shared_ptr<CfmRpcCodec> codec_;
+    CfmRpcConfig config_;
+};
+
+// Reuses a bounded set of CFM channels. Requests are selected round-robin; an
+// unavailable member is skipped so one failed connection does not stall
+// metric reporting.
+class CfmChannelPool final : public CfmChannel {
+   public:
+    explicit CfmChannelPool(std::vector<std::shared_ptr<CfmChannel>> channels)
+        : channels_(std::move(channels)) {}
+
+    bool SendSnapshot(const IoPatternSnapshot& snapshot) override;
+    bool SendMetricBatch(const MetricBatch& batch) override;
+    ErrorCode ExecutePrefetch(const PrefetchPlan& plan) override;
+
+   private:
+    std::shared_ptr<CfmChannel> Next() const;
+
+    std::vector<std::shared_ptr<CfmChannel>> channels_;
+    mutable std::atomic<size_t> next_{0};
+};
+
+// Adapts the RPC channel to the reporter's asynchronous batch sink.
+inline MetricBatchSink MakeCfmMetricBatchSink(
+    std::shared_ptr<CfmRpcChannel> channel) {
+    return [channel = std::move(channel)](const MetricBatch& batch) {
+        return channel && channel->SendMetricBatch(batch);
+    };
+}
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/include/io_pattern/runtime.h b/mooncake-store/include/io_pattern/runtime.h
new file mode 100644
index 0000000000..65fd8a09b1
--- /dev/null
+++ b/mooncake-store/include/io_pattern/runtime.h
@@ -0,0 +1,282 @@
+#pragma once
+
+#include <atomic>
+#include <condition_variable>
+#include <cstddef>
+#include <cstdint>
+#include <deque>
+#include <functional>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <thread>
+#include <unordered_set>
+#include <vector>
+
+#include "collector_impl.h"
+#include "degrading_policy_engine.h"
+#include "feedback.h"
+#include "legacy_eviction_ops.h"
+#include "observability.h"
+#include "policy_engine.h"
+#include "resilient_analyzer.h"
+#include "sliding_window_analyzer.h"
+#include "tier_executor.h"
+
+namespace mooncake::io_pattern {
+
+// Owns the Store-side IO Pattern pipeline. Producers only record observations;
+// policy evaluation and storage operations run through this explicit runtime
+// seam so collection never blocks the data path.
+class IoPatternRuntime final {
+   public:
+    enum class LegacyFallback { kLru, kFifo };
+    struct Handlers {
+        EvictionHandler eviction;
+        PrefetchHandler prefetch;
+        AdmissionHandler admission;
+    };
+
+    // Outcome of one report-driven policy cycle. The cycle aggregates the
+    // merged collector snapshot, runs analysis -> decision and executes the
+    // three storage-safe flows (eviction, prefetch, admission); this report
+    // lets the owning process surface each execution in its own metrics.
+    struct ReportDrivenCycleReport {
+        uint64_t cycle_id{0};
+        size_t keys_analyzed{0};
+        uint64_t analysis_elapsed_us{0};
+        bool degraded{false};
+        // Eviction dimension (derived from merged storage watermarks).
+        CacheTier eviction_tier{CacheTier::kL1Host};
+        uint64_t eviction_target_bytes{0};
+        size_t eviction_candidates{0};
+        ErrorCode eviction_status{ErrorCode::OK};
+        // True when the eviction request came from the cold-data driver
+        // (analysis-selected idle keys) rather than a storage-pressure
+        // watermark request.
+        bool cold_eviction{false};
+        // True when the eviction dimension was a demotion pass instead: the
+        // candidates were copied down to LOCAL_DISK and kept their MEMORY
+        // replica, so eviction_target_bytes is a demotion budget and
+        // eviction_status is the demotion outcome. Nothing was reclaimed.
+        bool tier_down{false};
+        // Prefetch dimension (derived from merged prefix-affinity keys).
+        size_t prefetch_candidates{0};
+        ErrorCode prefetch_status{ErrorCode::OK};
+        // Admission dimension (derived from merged lower-tier hot keys).
+        size_t admission_candidates{0};
+        size_t admissions_admitted{0};
+        ErrorCode admission_status{ErrorCode::OK};
+        // Dimensions whose storage handler declined to act because the
+        // primitive cannot run in the current mode (promotion disabled, no
+        // lower-tier source replica, HBM refusal). Such a skip is expected and
+        // is not counted as a policy failure.
+        size_t skipped_dimensions{0};
+    };
+    using ReportDrivenObserver =
+        std::function<void(const ReportDrivenCycleReport&)>;
+
+    struct Config {
+        IoPatternCollectorImpl::Config collector;
+        uint64_t analysis_window_ns{60'000'000'000ULL};
+        uint64_t analysis_timeout_us{500'000};
+        size_t max_analysis_keys{100'000};
+        size_t feedback_window{60};
+        size_t report_capacity{4096};
+        size_t report_per_tenant_capacity{0};
+        size_t max_pending_prefetches{4096};
+        size_t max_pending_admissions{4096};
+        MetricBatchSink report_sink;
+        LegacyFallback legacy_fallback{LegacyFallback::kLru};
+        // Report-driven execution: after each client report (snapshot or
+        // metric batch) is merged, the runtime runs its own full
+        // Collector -> Analyzer -> PolicyEngine -> execution cycle. The
+        // eviction dimension is triggered by merged storage watermarks; the
+        // prefetch and admission dimensions are derived from the merged key
+        // set. Defaults keep the worker off for pure collector/reporter
+        // runtimes; MasterService enables it on the SubMaster that owns the
+        // reported keys.
+        bool report_driven_execution{false};
+        // Storage metric ratio (L1Host memory) at or above which the merged
+        // snapshot is considered under pressure and an eviction cycle is
+        // executed. Mirrors the master's own high-watermark trigger.
+        float report_eviction_high_ratio{0.80F};
+        // Storage ratio at or above which admission into the head tier is
+        // refused. MasterService derives it from the same eviction high
+        // watermark so admission stops before eviction starts.
+        float admission_watermark_ratio{0.90F};
+        // Minimum accesses in the rolling window before admission into a
+        // non-HBM tier. Defaults to the ops default (2); 1 restores the previous
+        // admit-on-first-sight behaviour.
+        uint32_t admission_frequency_threshold{2};
+        // After an eviction cycle the tier is considered relieved once this
+        // ratio is reached; eviction target bytes are derived as
+        // (peak_ratio - report_eviction_target_ratio) * capacity_bytes.
+        float report_eviction_target_ratio{0.70F};
+        // Cold-data eviction driver. When enabled, a report-driven cycle that
+        // sees no storage-pressure request (merged L1 ratio below the high
+        // watermark) still runs a bounded eviction of the coldest keys, so
+        // eviction is driven by cold/hot analysis rather than only by memory
+        // pressure. Candidate selection and handler execution are identical to
+        // pressure eviction; the cycle report marks `cold_eviction=true` so
+        // logs/metrics can distinguish the two drivers.
+        bool report_driven_cold_eviction{false};
+        // Only keys idle (idle_time_us) at least this long are eligible for a
+        // cold-eviction pass. 0 disables the idle gate.
+        uint64_t report_driven_cold_idle_threshold_us{0};
+        // Max bytes a single cold-eviction pass may request (per drained
+        // cycle). 0 disables the cold driver regardless of the enable flag.
+        uint64_t report_driven_cold_eviction_bytes{0};
+        // Policy-driven tier down: the below-watermark placement action. When a
+        // report-driven cycle finds no reclaim request (neither storage pressure
+        // nor the cold-eviction driver) it spends this budget copying the coldest
+        // in-memory keys down to LOCAL_DISK while keeping their MEMORY replica,
+        // so a later reclaim of those keys can discard them safely instead of
+        // paying for the copy then. A demotion frees nothing, so a reclaim always
+        // wins the cycle, and the cycle report marks `tier_down=true` so a
+        // demotion is never counted as an eviction. There is no separate enable
+        // flag: 0 keeps the driver off, so this budget is the whole control.
+        uint64_t tier_down_bytes_per_cycle{0};
+        // Optional per-cycle observer used to surface executions in process
+        // metrics (e.g. MasterMetricManager). Never called from the report
+        // data path; only from the background cycle worker.
+        ReportDrivenObserver report_driven_observer;
+    };
+
+    explicit IoPatternRuntime(Handlers handlers);
+    IoPatternRuntime(Handlers handlers, Config config);
+    ~IoPatternRuntime();
+
+    void ReportInferenceMetrics(const InferenceMetrics& metrics);
+    void RecordAccess(const std::string& key, const AccessRecord& record);
+    void RecordStorageMetric(const StorageMetric& metric);
+    void MergeSnapshot(const IoPatternSnapshot& snapshot);
+    // Applies an authoritative tier transition reported by the owner of the
+    // replica metadata. See IoPatternCollectorImpl::RecordTierEvent.
+    void RecordTierEvent(const CacheEvent& event);
+    bool FlushReports();
+    void StopReports();
+
+    PolicyExecutionStatus Execute(
+        CacheTier eviction_tier, uint64_t eviction_bytes,
+        const TraceHistory& trace,
+        const std::vector<ObjectRef>& admissions = {},
+        const std::string& session_id = {});
+    // Requests one report-driven cycle after merged report data. Coalesces:
+    // reports that arrive while a cycle is pending or running only mark the
+    // cycle dirty; the single background worker runs at most one full cycle
+    // per drain. Non-blocking for the report path.
+    void RequestReportDrivenExecution();
+    // Blocks until the background report-driven worker has drained all
+    // currently pending reports (no pending flag and no cycle in flight).
+    // Used by benchmarks/tests that must read deterministic counters after a
+    // known report burst. No-op when report-driven execution is disabled.
+    void WaitForReportDrivenIdle();
+    bool report_driven_execution() const {
+        return config_.report_driven_execution;
+    }
+    // Runs Collector -> Analyzer -> PolicyEngine without invoking the local
+    // storage handlers. Callers use Plan when they need the raw policy result
+    // (for example the local eviction watermark path, observability or tests);
+    // Store data paths continue to use Execute().
+    PolicyResult Plan(CacheTier eviction_tier, uint64_t eviction_bytes,
+                      const TraceHistory& trace,
+                      const std::vector<ObjectRef>& admissions = {},
+                      const std::string& session_id = {});
+    // Applies a CFM-issued command through the same storage handlers as a
+    // locally planned policy. This is the CFM-to-Store execution endpoint used
+    // by the embedded SubMaster CFM receiver.
+    ErrorCode ExecuteCommand(const PolicyCommand& command);
+    bool ScheduleAdmission(ObjectRef object, CacheTier target_tier,
+                           std::string session_id = {});
+
+    void RecordFeedback(PolicyFeedbackSample sample);
+    PolicyFeedbackStats FeedbackSnapshot() const;
+    IoPatternSnapshot Snapshot() const;
+    // With no explicit window, QPS is averaged over this runtime's lifetime.
+    IoPatternObservabilitySnapshot ObservabilitySnapshot(
+        double window_seconds = 0.0) const;
+    bool degraded() const;
+
+   private:
+    PatternResult AnalyzeWithinBudget(const IoPatternSnapshot& snapshot,
+                                       bool& degraded);
+    struct PlannedPolicy {
+        IoPatternSnapshot snapshot;
+        PolicyResult result;
+        bool analysis_degraded{false};
+        uint64_t analysis_elapsed_us{0};
+    };
+    PlannedPolicy BuildPolicy(CacheTier eviction_tier,
+                              uint64_t eviction_bytes,
+                              const TraceHistory& trace,
+                              const std::vector<ObjectRef>& admissions,
+                              const std::string& session_id,
+                              uint64_t min_idle_time_us = 0,
+                              bool tier_down = false);
+    void AdmissionWorker();
+    ErrorCode ExecuteAdmission(const ObjectRef& object, CacheTier target_tier,
+                               const std::string& session_id);
+
+    // Report-driven cycle internals (single background worker).
+    void ReportDrivenWorker();
+    void RunReportDrivenCycle();
+    // Runs the executor over an already planned policy and records the shared
+    // outcome bookkeeping (policy failure/success, degradation, pending
+    // prefetch set and feedback). Used by both Execute() and the
+    // report-driven cycle so the two paths stay semantically identical.
+    PolicyExecutionStatus CommitPolicy(PlannedPolicy& planned);
+    static void DeriveEvictionRequest(const IoPatternSnapshot& snapshot,
+                                      float high_ratio, float target_ratio,
+                                      CacheTier& eviction_tier,
+                                      uint64_t& eviction_bytes);
+    static TraceHistory DeriveTraceHistory(const IoPatternSnapshot& snapshot);
+    static std::vector<ObjectRef> DeriveAdmissionCandidates(
+        const IoPatternSnapshot& snapshot);
+
+    struct PendingAdmission {
+        ObjectRef object;
+        CacheTier target_tier{CacheTier::kL1Host};
+        std::string session_id;
+    };
+
+    Config config_;
+    std::shared_ptr<IoPatternReporter> reporter_;
+    std::shared_ptr<IoPatternCollectorImpl> collector_;
+    std::shared_ptr<ResilientAnalyzer> analyzer_;
+    std::shared_ptr<WorkloadPolicyEngine> workload_policy_;
+    std::shared_ptr<DegradingPolicyEngine> policy_;
+    TierOperationExecutor executor_;
+    PolicyFeedbackWindow feedback_;
+    AdaptivePolicyTuner tuner_;
+    IoPatternObservability observability_;
+    const std::chrono::steady_clock::time_point started_at_{
+        std::chrono::steady_clock::now()};
+    mutable std::mutex feedback_state_mutex_;
+    std::unordered_set<ObjectRef, ObjectRefHash> pending_prefetches_;
+    uint64_t feedback_accesses_{0};
+    uint64_t feedback_hits_{0};
+    float previous_hit_rate_{0.0F};
+    // Shared with a timed-out detached analyzer so runtime teardown cannot
+    // leave a worker holding a pointer into a destroyed runtime instance.
+    std::shared_ptr<std::atomic<bool>> analysis_in_flight_{
+        std::make_shared<std::atomic<bool>>(false)};
+    std::mutex admission_mutex_;
+    std::condition_variable admission_condition_;
+    std::deque<PendingAdmission> pending_admissions_;
+    std::thread admission_worker_;
+    bool admission_stopping_{false};
+
+    // Report-driven cycle worker state. Guarded by report_mutex_; the worker
+    // drains the pending flag and runs one cycle, then loops so reports that
+    // arrived during the cycle coalesce into the next drain.
+    std::mutex report_mutex_;
+    std::condition_variable report_condition_;
+    std::thread report_worker_;
+    bool report_pending_{false};
+    bool report_stopping_{false};
+    bool report_worker_busy_{false};
+    uint64_t report_cycle_id_{0};
+};
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/include/io_pattern/sliding_window_analyzer.h b/mooncake-store/include/io_pattern/sliding_window_analyzer.h
new file mode 100644
index 0000000000..dfbd701c6d
--- /dev/null
+++ b/mooncake-store/include/io_pattern/sliding_window_analyzer.h
@@ -0,0 +1,54 @@
+#pragma once
+
+#include <cstdint>
+#include <deque>
+#include <mutex>
+
+#include "threshold_analyzer.h"
+#include "kmeans_analyzer.h"
+
+namespace mooncake::io_pattern {
+
+struct WorkloadFeatureStats {
+    uint32_t token_median{0};
+    uint32_t token_p90{0};
+    uint32_t fanout_p90{0};
+    uint64_t block_median{0};
+    uint64_t block_p90{0};
+    uint32_t match_p90{0};
+    uint32_t frequency_median{0};
+    size_t samples{0};
+};
+
+// Maintains a timestamp-bounded history of snapshots for workload detection.
+class SlidingWindowAnalyzer final : public IoPatternAnalyzer {
+   public:
+    explicit SlidingWindowAnalyzer(uint64_t window_ns = 60'000'000'000ULL,
+                                    ThresholdAnalyzerConfig config = {},
+                                    size_t max_history_keys = 200'000)
+        : window_ns_(window_ns),
+          max_history_keys_(max_history_keys),
+          analyzer_(config),
+          kmeans_(KMeansWorkloadAnalyzer::Config{.thresholds = config}) {}
+
+    PatternResult Analyze(const IoPatternSnapshot& snapshot) const override;
+    WorkloadType DetectWorkloadType(
+        const IoPatternSnapshot& snapshot) const override;
+    float CalculateConfidence(const ObjectRef& object,
+                              const IoPatternSnapshot& snapshot) const override;
+    WorkloadFeatureStats FeatureStats() const;
+
+   private:
+    IoPatternSnapshot Aggregate(const IoPatternSnapshot& current) const;
+    void Append(const IoPatternSnapshot& snapshot) const;
+
+    const uint64_t window_ns_;
+    const size_t max_history_keys_;
+    mutable std::mutex mutex_;
+    mutable std::deque<IoPatternSnapshot> history_;
+    mutable size_t history_key_count_{0};
+    ThresholdAnalyzer analyzer_;
+    KMeansWorkloadAnalyzer kmeans_;
+};
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/include/io_pattern/threshold_analyzer.h b/mooncake-store/include/io_pattern/threshold_analyzer.h
new file mode 100644
index 0000000000..2fd3baa0c4
--- /dev/null
+++ b/mooncake-store/include/io_pattern/threshold_analyzer.h
@@ -0,0 +1,38 @@
+#pragma once
+
+#include "io_pattern/analyzer.h"
+
+namespace mooncake::io_pattern {
+
+struct ThresholdAnalyzerConfig {
+    uint32_t code_agent_token_count{16 * 1024};
+    uint32_t code_agent_prefix_fanout{16};
+    uint32_t code_agent_match_length{256};
+    uint64_t recommendation_block_size{128 * 1024};
+    uint32_t recommendation_frequency{20};
+    uint32_t conversation_prefix_fanout{16};
+    uint32_t conversation_match_length{256};
+};
+
+// Deterministic, low-latency analyzer for the documented threshold path.
+// Mixed workloads are intentionally returned when no rule matches.
+class ThresholdAnalyzer final : public IoPatternAnalyzer {
+   public:
+    explicit ThresholdAnalyzer(ThresholdAnalyzerConfig config = {})
+        : config_(config) {}
+
+    PatternResult Analyze(const IoPatternSnapshot& snapshot) const override;
+    WorkloadType DetectWorkloadType(
+        const IoPatternSnapshot& snapshot) const override;
+    float CalculateConfidence(const ObjectRef& object,
+                              const IoPatternSnapshot& snapshot) const override;
+
+   private:
+    const KeyMetrics* FindKey(const ObjectRef& object,
+                              const IoPatternSnapshot& snapshot) const;
+    float KeyConfidence(const KeyMetrics& key) const;
+
+    ThresholdAnalyzerConfig config_;
+};
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/include/io_pattern/tier_executor.h b/mooncake-store/include/io_pattern/tier_executor.h
new file mode 100644
index 0000000000..2b28a177cc
--- /dev/null
+++ b/mooncake-store/include/io_pattern/tier_executor.h
@@ -0,0 +1,48 @@
+#pragma once
+
+#include <cstddef>
+#include <functional>
+#include <vector>
+#include <utility>
+
+#include "types.h"
+#include "../types.h"
+
+namespace mooncake::io_pattern {
+
+using EvictionHandler = std::function<ErrorCode(const EvictionPlan&)>;
+using PrefetchHandler = std::function<ErrorCode(const PrefetchPlan&)>;
+using AdmissionHandler = std::function<ErrorCode(const AdmissionResult&)>;
+
+struct PolicyExecutionStatus {
+    ErrorCode eviction{ErrorCode::OK};
+    ErrorCode prefetch{ErrorCode::OK};
+    std::vector<ErrorCode> admissions;
+    bool degraded{false};
+    // Dimensions whose handler was present but declined to act because the
+    // underlying storage primitive cannot run in the current mode (promotion
+    // disabled, no lower-tier source replica, or a refusal to move data into an
+    // inference-runtime-owned tier). A skip is not a policy failure: the policy
+    // cannot influence that outcome, so it must not drive degradation.
+    size_t skipped{0};
+};
+
+// Bridges policy output to storage/tier mechanisms owned by other modules.
+class TierOperationExecutor final {
+   public:
+    TierOperationExecutor(EvictionHandler eviction,
+                           PrefetchHandler prefetch,
+                           AdmissionHandler admission)
+        : eviction_(std::move(eviction)),
+          prefetch_(std::move(prefetch)),
+          admission_(std::move(admission)) {}
+
+    PolicyExecutionStatus Execute(const PolicyResult& result) const;
+
+   private:
+    EvictionHandler eviction_;
+    PrefetchHandler prefetch_;
+    AdmissionHandler admission_;
+};
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/include/io_pattern/types.h b/mooncake-store/include/io_pattern/types.h
new file mode 100644
index 0000000000..a4f9190f4b
--- /dev/null
+++ b/mooncake-store/include/io_pattern/types.h
@@ -0,0 +1,339 @@
+#pragma once
+
+#include <array>
+#include <cstdint>
+#include <string>
+#include <variant>
+#include <vector>
+
+#include "tenant_id.h"
+
+namespace mooncake::io_pattern {
+
+enum class CacheTier : uint8_t {
+    kL0Hbm = 0,
+    kL1Host = 1,
+    kL2Segment = 2,
+    kL3NofSsd = 3,
+    // Client-local SSD, which is the store's only promotable lower tier
+    // (LOCAL_DISK -> MEMORY). Appended last so the numeric values of the
+    // existing tiers stay stable for the CFM wire format.
+    kLocalDisk = 4,
+};
+
+using CacheTierMask = uint8_t;
+
+constexpr CacheTierMask CacheTierBit(CacheTier tier) {
+    return static_cast<CacheTierMask>(1U << static_cast<uint8_t>(tier));
+}
+
+// Every tier, so callers do not have to assume that declaration order is also
+// storage order.
+inline constexpr std::array<CacheTier, 5> kAllCacheTiers{
+    CacheTier::kL0Hbm, CacheTier::kL1Host, CacheTier::kLocalDisk,
+    CacheTier::kL2Segment, CacheTier::kL3NofSsd};
+
+// Distance from the compute along the storage ladder, for decisions that need a
+// "closer to the head tier" comparison. Declaration order is deliberately not
+// this order: kLocalDisk is appended last for wire compatibility but sits
+// directly below host memory, above the pooled segment and NoF tiers.
+constexpr int TierDepth(CacheTier tier) {
+    switch (tier) {
+        case CacheTier::kL0Hbm:
+            return 0;
+        case CacheTier::kL1Host:
+            return 1;
+        case CacheTier::kLocalDisk:
+            return 2;
+        case CacheTier::kL2Segment:
+            return 3;
+        case CacheTier::kL3NofSsd:
+            return 4;
+    }
+    return 4;
+}
+
+enum class IoOperation : uint8_t {
+    kGet,
+    kPut,
+    kTierUp,
+    kTierDown,
+};
+
+enum class CacheLayout : uint8_t {
+    kUnknown,
+    kLayerFirst,
+    kPageFirst,
+    kPageFirstDirect,
+    kPageBased,
+    kHmaMultiGroup,
+};
+
+enum class StorageGcState : uint8_t {
+    kUnknown,
+    kIdle,
+    kRunning,
+    kStalled,
+};
+
+enum class WorkloadType : uint8_t {
+    kUnknown,
+    kCodeAgent,
+    kGenerativeRecommendation,
+    kMultiTurnConversation,
+    kMixed,
+};
+
+struct ObjectRef {
+    TenantId tenant_id;
+    std::string key;
+
+    bool operator==(const ObjectRef&) const = default;
+};
+
+struct ObjectRefHash {
+    size_t operator()(const ObjectRef& object) const noexcept {
+        const size_t tenant_hash = TenantIdHash{}(object.tenant_id);
+        const size_t key_hash = std::hash<std::string>{}(object.key);
+        return tenant_hash ^ (key_hash + 0x9e3779b9 + (tenant_hash << 6) +
+                              (tenant_hash >> 2));
+    }
+};
+
+struct InferenceMetrics {
+    ObjectRef object;
+    std::string session_id;
+    CacheLayout layout{CacheLayout::kUnknown};
+    uint32_t layout_group{0};
+    uint32_t prefix_depth{0};
+    uint32_t prefix_fanout{0};
+    uint32_t match_length{0};  // tokens/blocks, as defined by the connector
+    uint32_t continuous_prefix_length{0};
+    uint32_t token_count{0};
+    float recompute_cost{0.0F};
+    uint8_t request_priority{0};
+};
+
+struct AccessRecord {
+    ObjectRef object;
+    uint64_t observed_at_ns{0};  // monotonic nanoseconds
+    uint64_t block_size{0};
+    uint64_t latency_us{0};
+    CacheTier tier{CacheTier::kL2Segment};
+    IoOperation operation{IoOperation::kGet};
+    bool is_hit{false};
+    uint32_t write_batch_size{0};
+    bool overwrite{false};
+};
+
+struct StorageMetric {
+    std::string source_id;
+    uint64_t observed_at_ns{0};
+    CacheTier tier{CacheTier::kL2Segment};
+    StorageGcState gc_state{StorageGcState::kUnknown};
+    uint64_t read_bandwidth_bytes_per_sec{0};
+    uint64_t write_bandwidth_bytes_per_sec{0};
+    uint64_t read_latency_us{0};
+    uint64_t write_latency_us{0};
+    uint64_t used_bytes{0};
+    uint64_t capacity_bytes{0};
+    uint64_t rpc_latency_us{0};
+    float memory_used_ratio{0.0F};
+};
+
+struct KeyMetrics {
+    ObjectRef object;
+    std::string session_id;
+    uint64_t last_access_time_ns{0};
+    uint64_t access_count_window{0};
+    uint64_t idle_time_us{0};
+    uint64_t block_size{0};
+    uint64_t transfer_eta_us{0};
+    uint32_t token_count{0};
+    uint32_t prefix_depth{0};
+    uint32_t prefix_fanout{0};
+    uint32_t match_length{0};
+    uint32_t continuous_prefix_length{0};
+    uint32_t other_replica_count{0};
+    uint32_t write_batch_size{0};
+    uint32_t write_frequency{0};
+    uint64_t write_object_size{0};
+    float recompute_cost{0.0F};
+    float overwrite_ratio{0.0F};
+    CacheTierMask replica_tiers{0};
+    CacheLayout layout{CacheLayout::kUnknown};
+    uint32_t layout_group{0};
+    uint8_t request_priority{0};
+    bool active{false};
+    bool pinned{false};
+    bool ssd_replica_exists{false};
+    bool write_burst{false};
+};
+
+struct IoPatternSnapshot {
+    uint64_t generated_at_ns{0};
+    std::vector<KeyMetrics> keys;
+    std::vector<StorageMetric> storage;
+};
+
+struct KeyPattern {
+    ObjectRef object;
+    float confidence{0.0F};
+    float frequency_score{0.0F};
+    float idle_score{0.0F};
+    float prefix_score{0.0F};
+    float recompute_score{0.0F};
+    float transfer_roi{0.0F};
+    bool migration_safe{false};
+};
+
+struct SessionPattern {
+    std::string session_id;
+    WorkloadType workload_type{WorkloadType::kUnknown};
+    float confidence{0.0F};
+};
+
+struct PatternResult {
+    WorkloadType workload_type{WorkloadType::kUnknown};
+    float workload_confidence{0.0F};
+    std::vector<KeyPattern> keys;
+    std::vector<SessionPattern> sessions;
+};
+
+struct PolicyContext {
+    IoPatternSnapshot snapshot;
+    PatternResult analysis;
+    std::string session_id;
+    // Cold-data eviction gate: when non-zero, only objects idle at least this
+    // long are eligible. Applied here rather than by pre-summing idle bytes into
+    // the byte target, so the budget and the selected victims describe the same
+    // keys. 0 disables the gate.
+    uint64_t min_idle_time_us{0};
+    // Tier-down driver gate. When set, the strategy labels the candidates it
+    // selects as kTierDown instead of kEvict: the same victims are chosen, but
+    // the executor copies them down instead of reclaiming them. The action is
+    // decided by the driver here and can never be derived from a candidate's
+    // target_tier: TierDownTarget() returns source+1 for every tier it is given,
+    // so deriving it would label every candidate a demotion and disable eviction
+    // entirely.
+    bool tier_down{false};
+};
+
+struct TraceEvent {
+    ObjectRef object;
+    uint64_t observed_at_ns{0};
+    uint32_t match_length{0};
+    bool is_hit{false};
+};
+
+struct TraceHistory {
+    std::vector<TraceEvent> events;
+};
+
+enum class PrefetchStrategy : uint8_t {
+    kBestEffort,
+    kTimeout,
+    kWaitComplete,
+};
+
+struct PrefetchCandidate {
+    ObjectRef object;
+    CacheTier source_tier{CacheTier::kL3NofSsd};
+    CacheTier target_tier{CacheTier::kL2Segment};
+    uint64_t bytes{0};
+    float priority{0.0F};
+    float confidence{0.0F};
+};
+
+struct PrefetchPlan {
+    PrefetchStrategy strategy{PrefetchStrategy::kBestEffort};
+    uint64_t timeout_us{0};
+    std::vector<PrefetchCandidate> candidates;
+};
+
+// What the executor must do with one selected candidate. Chosen by the driver
+// that built the plan (PolicyContext::tier_down), never inferred from
+// target_tier: see PolicyContext::tier_down.
+enum class EvictionAction : uint8_t {
+    // Reclaim the MEMORY replica (the original behaviour).
+    kEvict,
+    // Copy the object down to LOCAL_DISK and keep the MEMORY replica, so a later
+    // Get still hits memory and nothing is freed by this action.
+    kTierDown,
+};
+
+struct EvictionCandidate {
+    ObjectRef object;
+    uint64_t bytes{0};
+    float score{0.0F};
+    CacheTier target_tier{CacheTier::kL3NofSsd};
+    // Appended last so existing positional and designated initializers keep
+    // their meaning; the default preserves the previous reclaim semantics for
+    // every producer that does not set an action.
+    EvictionAction action{EvictionAction::kEvict};
+};
+
+struct EvictionPlan {
+    CacheTier source_tier{CacheTier::kL0Hbm};
+    uint64_t target_bytes{0};
+    std::vector<EvictionCandidate> candidates;
+    // How many of target_bytes are meant to be demoted rather than reclaimed.
+    // 0 for a pure eviction plan. This rides the CFM wire so a remote executor
+    // can tell a tier-down budget from a reclaim budget instead of treating the
+    // whole plan as memory to free.
+    uint64_t tier_down_target_bytes{0};
+};
+
+enum class AdmissionDecision : uint8_t {
+    kAdmit,
+    kRejectFrequency,
+    kRejectWatermark,
+    kRejectPrefix,
+    kDefer,
+};
+
+struct AdmissionResult {
+    ObjectRef object;
+    CacheTier target_tier{CacheTier::kL2Segment};
+    AdmissionDecision decision{AdmissionDecision::kDefer};
+    float confidence{0.0F};
+};
+
+struct PolicyResult {
+    EvictionPlan eviction;
+    PrefetchPlan prefetch;
+    std::vector<AdmissionResult> admissions;
+    bool degraded{false};
+};
+
+struct CacheViewEntry {
+    ObjectRef object;
+    CacheTier tier{CacheTier::kL2Segment};
+    uint64_t bytes{0};
+};
+
+struct CacheView {
+    uint64_t version{0};
+    std::vector<CacheViewEntry> entries;
+};
+
+using KVMappingTable = std::vector<CacheViewEntry>;
+
+enum class CacheEventType : uint8_t {
+    kUnknown,
+    kInserted,
+    kRemoved,
+    kTierChanged,
+};
+
+struct CacheEvent {
+    CacheEventType type{CacheEventType::kUnknown};
+    ObjectRef object;
+    CacheTier source_tier{CacheTier::kL2Segment};
+    CacheTier target_tier{CacheTier::kL2Segment};
+};
+
+using PolicyCommand =
+    std::variant<EvictionPlan, PrefetchPlan, AdmissionResult>;
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/include/io_pattern_analyzer.h b/mooncake-store/include/io_pattern_analyzer.h
new file mode 100644
index 0000000000..9ff4932701
--- /dev/null
+++ b/mooncake-store/include/io_pattern_analyzer.h
@@ -0,0 +1,4 @@
+#pragma once
+
+#include "io_pattern/analyzer.h"
+#include "io_pattern/threshold_analyzer.h"
diff --git a/mooncake-store/include/io_pattern_collector.h b/mooncake-store/include/io_pattern_collector.h
new file mode 100644
index 0000000000..448be4a72f
--- /dev/null
+++ b/mooncake-store/include/io_pattern_collector.h
@@ -0,0 +1,3 @@
+#pragma once
+
+#include "io_pattern/collector.h"
diff --git a/mooncake-store/include/io_pattern_registry.h b/mooncake-store/include/io_pattern_registry.h
new file mode 100644
index 0000000000..9b08e9df83
--- /dev/null
+++ b/mooncake-store/include/io_pattern_registry.h
@@ -0,0 +1,3 @@
+#pragma once
+
+#include "io_pattern/registry.h"
diff --git a/mooncake-store/include/io_pattern_types.h b/mooncake-store/include/io_pattern_types.h
new file mode 100644
index 0000000000..a8a6fb2610
--- /dev/null
+++ b/mooncake-store/include/io_pattern_types.h
@@ -0,0 +1,3 @@
+#pragma once
+
+#include "io_pattern/types.h"
diff --git a/mooncake-store/include/legacy_eviction_ops.h b/mooncake-store/include/legacy_eviction_ops.h
new file mode 100644
index 0000000000..8fdcc44f50
--- /dev/null
+++ b/mooncake-store/include/legacy_eviction_ops.h
@@ -0,0 +1,2 @@
+#pragma once
+#include "io_pattern/legacy_eviction_ops.h"
diff --git a/mooncake-store/include/master_client.h b/mooncake-store/include/master_client.h
index be6e1b9c24..7dc9acc89b 100644
--- a/mooncake-store/include/master_client.h
+++ b/mooncake-store/include/master_client.h
@@ -1,7 +1,10 @@
 #pragma once
 
 #include <csignal>
+#include <map>
 #include <memory>
+#include <mutex>
+#include <optional>
 #include <string>
 #include <type_traits>
 #include <vector>
@@ -22,6 +25,8 @@
 #include "store_rpc_client_io_context.h"
 #include "task_manager.h"
 #include "metadata_store.h"
+#include "partition/partition_router.h"
+#include "vchunk_metadata.h"
 
 namespace mooncake {
 
@@ -79,6 +84,8 @@ class MasterClient {
                  std::string tenant_id = "default")
         : client_accessor_(GetStoreRpcClientIoContextPool(), 
                            detail::MakeMasterRpcClientPoolConfig()),
+          targeted_accessor_(GetStoreRpcClientIoContextPool(),
+                             detail::MakeMasterRpcClientPoolConfig()),
           client_id_(client_id),
           tenant_id_(NormalizeTenantId(std::move(tenant_id))),
           metrics_(metrics) {
@@ -122,6 +129,27 @@ class MasterClient {
     [[nodiscard]] ErrorCode Connect(
         const std::string& master_addr = kDefaultMasterAddress);
 
+    /**
+     * @brief Loads the slot -> submaster mapping from the etcd KV view
+     * snapshot into the partition router. Must be called after etcd is
+     * reachable and the cluster namespace (cluster_id) is known.
+     * @param etcd_endpoints Etcd endpoints, semicolon separated.
+     * @param cluster_namespace Cluster namespace used to locate the snapshot.
+     * @return ErrorCode indicating success/failure.
+     */
+    [[nodiscard]] ErrorCode LoadRoutingFromEtcd(
+        const std::string& etcd_endpoints,
+        const std::string& cluster_namespace);
+
+    /**
+     * @brief Resolves the submaster (primary_master_id) that owns the slot of
+     * the given key, using the currently loaded partition routing table.
+     * @param key Object key.
+     * @return submaster id on success, std::nullopt if no mapping is loaded.
+     */
+    [[nodiscard]] std::optional<std::string> ResolveSubmaster(
+        const std::string& key) const;
+
     /**
      * @brief Checks if an object exists
      * @param object_key Key to query
@@ -262,6 +290,25 @@ class MasterClient {
     [[nodiscard]] tl::expected<void, ErrorCode> PutRevoke(
         const std::string& key, ReplicaType replica_type);
 
+    [[nodiscard]] tl::expected<VChunkMetadataRecord, ErrorCode> VChunkPutStart(
+        const std::string& tenant_id, const std::string& key,
+        uint64_t total_size, int64_t now_ms);
+    [[nodiscard]] tl::expected<void, ErrorCode> VChunkPutEnd(
+        const std::string& tenant_id, const std::string& key,
+        const std::string& vchunk_id, int64_t now_ms);
+    [[nodiscard]] tl::expected<void, ErrorCode> VChunkPutRevoke(
+        const std::string& tenant_id, const std::string& key,
+        const std::string& vchunk_id);
+    [[nodiscard]] tl::expected<VChunkReadLease, ErrorCode> GetVChunk(
+        const std::string& tenant_id, const std::string& key);
+    [[nodiscard]] tl::expected<void, ErrorCode> ReleaseVChunkReadLease(
+        const std::string& tenant_id, const std::string& key,
+        const std::string& lease_id);
+    [[nodiscard]] tl::expected<void, ErrorCode> RemoveVChunk(
+        const std::string& tenant_id, const std::string& key, int64_t now_ms);
+    [[nodiscard]] tl::expected<VChunkRuntimeInfo, ErrorCode>
+    GetVChunkRuntimeInfo();
+
     /**
      * @brief Revokes a put operation for a batch of objects
      * @param keys Vector of object keys
@@ -432,6 +479,14 @@ class MasterClient {
     [[nodiscard]] tl::expected<SegmentStatus, ErrorCode> QuerySegmentStatusById(
         const UUID& segment_id);
 
+    /**
+     * @brief 定向 QuerySegmentStatusById：向指定 submaster 查询 segment 状态
+     * （不切换当前连接）。用于多 submaster 优雅卸载时确认所有 primary
+     * submaster 均已移除该 segment。
+     */
+    [[nodiscard]] tl::expected<SegmentStatus, ErrorCode> QuerySegmentStatusByIdTo(
+        const std::string& address, const UUID& segment_id);
+
     [[nodiscard]] tl::expected<GetStorageConfigResponse, ErrorCode>
     GetStorageConfig();
 
@@ -442,6 +497,46 @@ class MasterClient {
      */
     [[nodiscard]] tl::expected<PingResponse, ErrorCode> Ping();
 
+    /**
+     * @brief 返回 client_accessor_ 当前连接的 submaster 地址（IP:Port）。
+     * 供后台心跳去重使用——HeartbeatAllSubmasters 跳过当前 active 地址，
+     * 避免与主循环的 Ping() 对同一 submaster 重复 ping。
+     */
+    std::string GetCurrentAddress() const;
+
+    /**
+     * @brief 定向 Ping：向指定 submaster 发送 Ping（不切换当前连接）。
+     * 用于 client 侧多 submaster 心跳，防止各 submaster 因收不到 ping 而
+     * 误判 client 过期并卸载其 segment。返回 NEED_REMOUNT 时调用方应对该
+     * submaster 重新 mount。
+     */
+    [[nodiscard]] tl::expected<PingResponse, ErrorCode> PingTo(
+        const std::string& address);
+
+    /**
+     * @brief 定向 MountSegment：向指定 submaster 注册 segment（不切换当前
+     * 连接）。用于 client 侧全量 mount——同一 segment 挂载到所有 primary
+     * submaster，使任何 slot owner 都能本地分配副本。
+     */
+    [[nodiscard]] tl::expected<void, ErrorCode> MountSegmentTo(
+        const std::string& address, const Segment& segment);
+
+    /**
+     * @brief 定向 UnmountSegment：向指定 submaster 注销 segment（不切换当前
+     * 连接）。与全量 mount 对称，保证 segment 生命周期在所有 submaster 闭合。
+     */
+    [[nodiscard]] tl::expected<void, ErrorCode> UnmountSegmentTo(
+        const std::string& address, const UUID& segment_id);
+
+    /**
+     * @brief 定向 GracefulUnmountSegment：向指定 submaster 发起优雅卸载（不
+     * 切换当前连接）。与全量 unmount 对称，保证优雅卸载在所有 submaster 生效。
+     */
+    [[nodiscard]] tl::expected<void, ErrorCode> GracefulUnmountSegmentTo(
+        const std::string& address, const UUID& segment_id,
+        uint64_t grace_period_ms);
+
+
     /**
      * @brief Mounts a local disk segment into the master.
      * @param enable_offloading If true, enables offloading (write-to-file).
@@ -698,6 +793,16 @@ class MasterClient {
     [[nodiscard]] tl::expected<ReturnType, ErrorCode> invoke_rpc(
         Args&&... args);
 
+    /**
+     * @brief 定向 RPC：向指定 submaster 发请求，使用独立的 targeted_accessor_
+     * 缓存 per-address pool，不切换 client_accessor_ 的"当前地址"。供后台心跳
+     * /全量 mount/unmount 使用，避免与业务请求（SwitchToSubmaster + invoke_rpc）
+     * 的当前地址切换竞态。
+     */
+    template <auto ServiceMethod, typename ReturnType, typename... Args>
+    [[nodiscard]] tl::expected<ReturnType, ErrorCode> invoke_rpc_to(
+        const std::string& address, Args&&... args);
+
     /**
      * @brief Generic RPC invocation helper for batch operations
      * @tparam ServiceMethod Pointer to WrappedMasterService member function
@@ -713,6 +818,34 @@ class MasterClient {
 
     void WarmupRpcPool();
 
+    /**
+     * @brief Switches the underlying RPC pool to the submaster that owns the
+     * slot of the given key (single-target switching). Keeps the current
+     * connection when the routing table is not loaded (single-master mode).
+     * @return ErrorCode::OK on switch (or no-op), otherwise an error.
+     */
+    [[nodiscard]] ErrorCode SwitchToSubmaster(const std::string& tenant_id,
+                                              const std::string& key);
+
+    // Refreshes the previously configured CVM snapshot after a server reports
+    // SLOT_NOT_OWNED. The caller remains responsible for a bounded retry.
+    [[nodiscard]] ErrorCode RefreshSubmasterRouting();
+
+    /**
+     * @brief Switches the underlying RPC pool to the given submaster address.
+     * @param address Submaster address (primary_master_id).
+     */
+    void SwitchToSubmasterByAddress(const std::string& address);
+
+    /**
+     * @brief Groups key indices by their owning submaster. Keys without a
+     * resolved submaster are grouped under an empty string ("").
+     * @return Map from submaster address to original key indices.
+     */
+    [[nodiscard]] std::map<std::string, std::vector<size_t>>
+    GroupKeysBySubmaster(const std::vector<std::string>& keys,
+                         const std::string& tenant_id);
+
     /**
      * @brief Accessor for the coro_rpc_client pool. Since coro_rpc_client pool
      * cannot reconnect to a different address, a new coro_rpc_client pool is
@@ -741,12 +874,26 @@ class MasterClient {
 
     RpcClientPool client_accessor_;
 
+    // 定向 RPC 用独立 pool 访问器：后台心跳/全量 mount/unmount 用它直发指定
+    // submaster，与业务请求的 client_accessor_（SwitchToSubmaster 切"当前地址"）
+    // 完全隔离，避免"当前地址"竞态。invoke_rpc_to 用 GetOrCreateClientPool 的
+    // 返回值发请求，不依赖该访问器的"当前地址"，因此可被多线程并发调用。
+    RpcClientPool targeted_accessor_;
+
     // The client identification.
     const UUID client_id_;
 
     // Tenant identity for this client instance.
     const TenantId tenant_id_;
 
+    // KV partition routing table (slot -> submaster). Loaded from etcd.
+    partition::PartitionRouter partition_router_;
+    mutable std::mutex routing_config_mutex_;
+    std::string routing_cluster_namespace_;
+    // Protects the target switch and the following vchunk RPC as one unit.
+    // RpcClientPool itself is thread-safe, but its selected target is shared.
+    mutable std::mutex vchunk_routed_rpc_mutex_;
+
     // Metrics for tracking RPC operations
     MasterClientMetric* metrics_;
     std::shared_ptr<coro_io::client_pools<coro_rpc::coro_rpc_client>>
diff --git a/mooncake-store/include/master_config.h b/mooncake-store/include/master_config.h
index b73d9ca61c..85435520ef 100644
--- a/mooncake-store/include/master_config.h
+++ b/mooncake-store/include/master_config.h
@@ -2,12 +2,16 @@
 
 #include <optional>
 #include <stdexcept>
+#include <string>
 #include <string_view>
+#include <utility>
 
 #include <glog/logging.h>
 
 #include "config_helper.h"
 #include "types.h"
+#include "vchunk_config.h"
+#include "vchunk_metadata_store.h"
 
 namespace mooncake {
 
@@ -44,6 +48,13 @@ struct MasterConfig {
     double eviction_high_watermark_ratio;
     double nof_eviction_ratio;
     double nof_eviction_high_watermark_ratio;
+    // Report-driven cold-data eviction driver (embedded CFM component).
+    // When true, merged client reports may drive bounded evictions of the
+    // coldest keys even when the memory watermark is not exceeded. All three
+    // default to disabled (watermark-only eviction) unless explicitly set.
+    bool io_pattern_cold_eviction = false;
+    uint64_t io_pattern_cold_eviction_bytes_per_cycle = 0;
+    uint64_t io_pattern_cold_idle_threshold_us = 0;
     int64_t client_live_ttl_sec;
     int64_t nof_heartbeat_interval_sec;
     uint32_t nof_heartbeat_probe_timeout_ms;
@@ -58,8 +69,7 @@ struct MasterConfig {
     // Master view lease TTL in seconds (HA leadership lease).
     // When the lease expires without successful renewal, the Master
     // is considered dead and a standby can take over.
-    int64_t master_view_lease_ttl_sec =
-        DEFAULT_MASTER_VIEW_LEASE_TTL_SEC;
+    int64_t master_view_lease_ttl_sec = DEFAULT_MASTER_VIEW_LEASE_TTL_SEC;
 
     // OpLog store configuration
     bool enable_oplog = false;
@@ -74,6 +84,14 @@ struct MasterConfig {
     int metrics_report_lease_ttl_sec = DEFAULT_METRICS_REPORT_LEASE_TTL_SEC;
 
     std::string cluster_id;
+    // 集群中允许同时 serving 的 submaster 上限（CVM 名额协调，先到先得）。
+    // 默认 1 保持单主行为；>1 时多 submaster 均分 slot，超出 k 名自动降级为
+    // standby。
+    uint32_t submaster_count = 1;
+    // CVM external HTTP API (CvmHttpServer) bind config. Port 0 keeps the
+    // HTTP server disabled.
+    uint16_t cvm_http_port = 0;
+    std::string cvm_http_host = "0.0.0.0";
     std::string root_fs_dir;
     int64_t global_file_segment_size;
     std::string memory_allocator;
@@ -132,6 +150,8 @@ struct MasterConfig {
     std::string cxl_path;
     size_t cxl_size;
     bool enable_cxl = false;
+    VChunkConfig vchunk_config{};
+    std::string vchunk_etcd_endpoints;
 
     // Offload-on-evict: defer LOCAL_DISK offload to eviction time
     bool offload_on_evict = false;
@@ -149,6 +169,19 @@ struct MasterConfig {
     bool promotion_on_hit = false;
     uint32_t promotion_admission_threshold = 2;
     uint32_t promotion_queue_limit = 50000;
+    // Policy-driven tier down: below the memory watermark, copy the coldest
+    // objects down to local disk while keeping their MEMORY replica (tier down is
+    // a copy, not a reclaim), so a later reclaim can discard them safely. There
+    // is no separate enable switch: a non-zero per-cycle budget is the control,
+    // and 0 keeps the driver off. A reclaim always wins, so a cycle that reaches
+    // the watermark evicts instead of demoting.
+    uint64_t io_pattern_tier_down_bytes_per_cycle = 0;
+    // Admission gates. The frequency threshold defaults to 2, matching the
+    // master's own second-touch promotion gate; 1 restores the previous
+    // admit-on-first-sight behaviour. A negative watermark means "derive it from
+    // eviction_high_watermark_ratio", so admission stops before eviction starts.
+    uint32_t io_pattern_admission_frequency_threshold = 2;
+    double io_pattern_admission_watermark_ratio = -1.0;
     // Max promotion tasks PromotionObjectHeartbeat returns to a single
     // client per call. Each task is a synchronous SSD-read + RDMA-write
     // on the client; serializing them avoids blocking past the client-
@@ -213,6 +246,12 @@ class MasterServiceSupervisorConfig {
     uint32_t batch_oplog_retry_timeout_sec = 180;
     std::string local_hostname = "0.0.0.0:50051";
     std::string cluster_id = DEFAULT_CLUSTER_ID;
+    // 集群中允许同时 serving 的 submaster 上限（CVM 名额协调，先到先得）。
+    uint32_t submaster_count = 1;
+    // CVM external HTTP API (CvmHttpServer) bind config. Port 0 keeps the
+    // HTTP server disabled.
+    uint16_t cvm_http_port = 0;
+    std::string cvm_http_host = "0.0.0.0";
 
     // Metrics reporting to HA backend (etcd/redis).
     bool enable_metrics_report_to_backend =
@@ -255,6 +294,8 @@ class MasterServiceSupervisorConfig {
     std::string cxl_path = DEFAULT_CXL_PATH;
     size_t cxl_size = DEFAULT_CXL_SIZE;
     bool enable_cxl = false;
+    VChunkConfig vchunk_config{};
+    std::string vchunk_etcd_endpoints;
     bool offload_on_evict = false;
     bool offload_force_evict = false;
     bool strict_replica_allocation = false;
@@ -263,7 +304,26 @@ class MasterServiceSupervisorConfig {
     bool promotion_on_hit = false;
     uint32_t promotion_admission_threshold = 2;
     uint32_t promotion_queue_limit = 50000;
+    // Policy-driven tier down: below the memory watermark, copy the coldest
+    // objects down to local disk while keeping their MEMORY replica (tier down is
+    // a copy, not a reclaim), so a later reclaim can discard them safely. There
+    // is no separate enable switch: a non-zero per-cycle budget is the control,
+    // and 0 keeps the driver off. A reclaim always wins, so a cycle that reaches
+    // the watermark evicts instead of demoting.
+    uint64_t io_pattern_tier_down_bytes_per_cycle = 0;
+    // Admission gates. The frequency threshold defaults to 2, matching the
+    // master's own second-touch promotion gate; 1 restores the previous
+    // admit-on-first-sight behaviour. A negative watermark means "derive it from
+    // eviction_high_watermark_ratio", so admission stops before eviction starts.
+    uint32_t io_pattern_admission_frequency_threshold = 2;
+    double io_pattern_admission_watermark_ratio = -1.0;
     uint32_t promotion_max_per_heartbeat = 1;
+    // Report-driven cold-data eviction driver (embedded CFM component).
+    // Mirrors MasterConfig / WrappedMasterServiceConfig; carried through the
+    // supervisor config used by HA deployments.
+    bool io_pattern_cold_eviction = false;
+    uint64_t io_pattern_cold_eviction_bytes_per_cycle = 0;
+    uint64_t io_pattern_cold_idle_threshold_us = 0;
     bool enable_kv_events = false;
     std::string kv_events_bind_endpoint;
     std::string kv_events_model_name;
@@ -304,6 +364,11 @@ class MasterServiceSupervisorConfig {
         nof_eviction_ratio = config.nof_eviction_ratio;
         nof_eviction_high_watermark_ratio =
             config.nof_eviction_high_watermark_ratio;
+        io_pattern_cold_eviction = config.io_pattern_cold_eviction;
+        io_pattern_cold_eviction_bytes_per_cycle =
+            config.io_pattern_cold_eviction_bytes_per_cycle;
+        io_pattern_cold_idle_threshold_us =
+            config.io_pattern_cold_idle_threshold_us;
         client_live_ttl_sec = config.client_live_ttl_sec;
         nof_heartbeat_interval_sec = config.nof_heartbeat_interval_sec;
         nof_heartbeat_probe_timeout_ms = config.nof_heartbeat_probe_timeout_ms;
@@ -318,6 +383,12 @@ class MasterServiceSupervisorConfig {
         promotion_on_hit = config.promotion_on_hit;
         promotion_admission_threshold = config.promotion_admission_threshold;
         promotion_queue_limit = config.promotion_queue_limit;
+        io_pattern_tier_down_bytes_per_cycle =
+            config.io_pattern_tier_down_bytes_per_cycle;
+        io_pattern_admission_frequency_threshold =
+            config.io_pattern_admission_frequency_threshold;
+        io_pattern_admission_watermark_ratio =
+            config.io_pattern_admission_watermark_ratio;
         promotion_max_per_heartbeat = config.promotion_max_per_heartbeat;
         enable_kv_events = config.enable_kv_events;
         kv_events_bind_endpoint = config.kv_events_bind_endpoint;
@@ -350,6 +421,9 @@ class MasterServiceSupervisorConfig {
         batch_oplog_retry_timeout_sec = config.batch_oplog_retry_timeout_sec;
         local_hostname = rpc_address + ":" + std::to_string(rpc_port);
         cluster_id = config.cluster_id;
+        submaster_count = config.submaster_count;
+        cvm_http_port = config.cvm_http_port;
+        cvm_http_host = config.cvm_http_host;
 
         enable_metrics_report_to_backend =
             config.enable_metrics_report_to_backend;
@@ -415,6 +489,10 @@ class MasterServiceSupervisorConfig {
         cxl_path = config.cxl_path;
         cxl_size = config.cxl_size;
         enable_cxl = config.enable_cxl;
+        vchunk_config = config.vchunk_config;
+        vchunk_etcd_endpoints = config.vchunk_etcd_endpoints.empty()
+                                    ? config.etcd_endpoints
+                                    : config.vchunk_etcd_endpoints;
 
         pod_name = config.pod_name;
         pod_namespace = config.pod_namespace;
@@ -496,6 +574,10 @@ class WrappedMasterServiceConfig {
     double nof_eviction_ratio = DEFAULT_NOF_EVICTION_RATIO;
     double nof_eviction_high_watermark_ratio =
         DEFAULT_NOF_EVICTION_HIGH_WATERMARK_RATIO;
+    // Report-driven cold-data eviction driver (embedded CFM component).
+    bool io_pattern_cold_eviction = false;
+    uint64_t io_pattern_cold_eviction_bytes_per_cycle = 0;
+    uint64_t io_pattern_cold_idle_threshold_us = 0;
     ViewVersionId view_version = 0;
     int64_t client_live_ttl_sec = DEFAULT_CLIENT_LIVE_TTL_SEC;
     int64_t nof_heartbeat_interval_sec = DEFAULT_NOF_HEARTBEAT_INTERVAL_SEC;
@@ -513,6 +595,19 @@ class WrappedMasterServiceConfig {
     bool promotion_on_hit = false;
     uint32_t promotion_admission_threshold = 2;
     uint32_t promotion_queue_limit = 50000;
+    // Policy-driven tier down: below the memory watermark, copy the coldest
+    // objects down to local disk while keeping their MEMORY replica (tier down is
+    // a copy, not a reclaim), so a later reclaim can discard them safely. There
+    // is no separate enable switch: a non-zero per-cycle budget is the control,
+    // and 0 keeps the driver off. A reclaim always wins, so a cycle that reaches
+    // the watermark evicts instead of demoting.
+    uint64_t io_pattern_tier_down_bytes_per_cycle = 0;
+    // Admission gates. The frequency threshold defaults to 2, matching the
+    // master's own second-touch promotion gate; 1 restores the previous
+    // admit-on-first-sight behaviour. A negative watermark means "derive it from
+    // eviction_high_watermark_ratio", so admission stops before eviction starts.
+    uint32_t io_pattern_admission_frequency_threshold = 2;
+    double io_pattern_admission_watermark_ratio = -1.0;
     uint32_t promotion_max_per_heartbeat = 1;
     bool enable_kv_events = false;
     std::string kv_events_bind_endpoint;
@@ -533,6 +628,19 @@ class WrappedMasterServiceConfig {
     int oplog_poll_interval_ms = 1000;
     uint32_t oplog_batch_max_entries = 1024;
     std::string cluster_id = DEFAULT_CLUSTER_ID;
+    // Stable identifier of this master instance, used as the SlotOwner
+    // primary_master_id for the KV partition view. Empty disables the
+    // SlotOwnerHeartbeat. In HA mode this is the local_hostname.
+    std::string master_id;
+    // CVM external HTTP API (CvmHttpServer) bind config. Port 0 keeps the
+    // HTTP server disabled; set a non-zero port to expose /kv_view,
+    // /segment_view and /health for inspection.
+    uint16_t cvm_http_port = 0;
+    std::string cvm_http_host = "0.0.0.0";
+    // 集群中允许同时 serving 的 submaster 上限（CVM 名额协调，先到先得）。
+    // 默认 1 保持单主行为；>1 时多 submaster 均分 slot，超出 k 名自动降级为
+    // standby。
+    uint32_t submaster_count = 1;
     std::string root_fs_dir = DEFAULT_ROOT_FS_DIR;
     int64_t global_file_segment_size = DEFAULT_GLOBAL_FILE_SEGMENT_SIZE;
     BufferAllocatorType memory_allocator = BufferAllocatorType::OFFSET;
@@ -568,6 +676,8 @@ class WrappedMasterServiceConfig {
     std::string cxl_path = DEFAULT_CXL_PATH;
     size_t cxl_size = DEFAULT_CXL_SIZE;
     bool enable_cxl = false;
+    VChunkConfig vchunk_config{};
+    std::string vchunk_etcd_endpoints;
     WrappedMasterServiceConfig() = default;
 
     // From MasterConfig
@@ -587,6 +697,11 @@ class WrappedMasterServiceConfig {
         nof_eviction_ratio = config.nof_eviction_ratio;
         nof_eviction_high_watermark_ratio =
             config.nof_eviction_high_watermark_ratio;
+        io_pattern_cold_eviction = config.io_pattern_cold_eviction;
+        io_pattern_cold_eviction_bytes_per_cycle =
+            config.io_pattern_cold_eviction_bytes_per_cycle;
+        io_pattern_cold_idle_threshold_us =
+            config.io_pattern_cold_idle_threshold_us;
         view_version = view_version_param;
         client_live_ttl_sec = config.client_live_ttl_sec;
         nof_heartbeat_interval_sec = config.nof_heartbeat_interval_sec;
@@ -603,6 +718,12 @@ class WrappedMasterServiceConfig {
         promotion_on_hit = config.promotion_on_hit;
         promotion_admission_threshold = config.promotion_admission_threshold;
         promotion_queue_limit = config.promotion_queue_limit;
+        io_pattern_tier_down_bytes_per_cycle =
+            config.io_pattern_tier_down_bytes_per_cycle;
+        io_pattern_admission_frequency_threshold =
+            config.io_pattern_admission_frequency_threshold;
+        io_pattern_admission_watermark_ratio =
+            config.io_pattern_admission_watermark_ratio;
         promotion_max_per_heartbeat = config.promotion_max_per_heartbeat;
         enable_kv_events = config.enable_kv_events;
         kv_events_bind_endpoint = config.kv_events_bind_endpoint;
@@ -624,6 +745,9 @@ class WrappedMasterServiceConfig {
         oplog_poll_interval_ms = config.oplog_poll_interval_ms;
         oplog_batch_max_entries = config.oplog_batch_max_entries;
         cluster_id = config.cluster_id;
+        submaster_count = config.submaster_count;
+        cvm_http_port = config.cvm_http_port;
+        cvm_http_host = config.cvm_http_host;
         root_fs_dir = config.root_fs_dir;
         global_file_segment_size = config.global_file_segment_size;
         enable_disk_eviction = config.enable_disk_eviction;
@@ -683,6 +807,10 @@ class WrappedMasterServiceConfig {
         cxl_path = config.cxl_path;
         cxl_size = config.cxl_size;
         enable_cxl = config.enable_cxl;
+        vchunk_config = config.vchunk_config;
+        vchunk_etcd_endpoints = config.vchunk_etcd_endpoints.empty()
+                                    ? config.etcd_endpoints
+                                    : config.vchunk_etcd_endpoints;
     }
 
     // From MasterServiceSupervisorConfig, enable_ha is set to true
@@ -703,6 +831,11 @@ class WrappedMasterServiceConfig {
         nof_eviction_ratio = config.nof_eviction_ratio;
         nof_eviction_high_watermark_ratio =
             config.nof_eviction_high_watermark_ratio;
+        io_pattern_cold_eviction = config.io_pattern_cold_eviction;
+        io_pattern_cold_eviction_bytes_per_cycle =
+            config.io_pattern_cold_eviction_bytes_per_cycle;
+        io_pattern_cold_idle_threshold_us =
+            config.io_pattern_cold_idle_threshold_us;
         view_version = view_version_param;
         client_live_ttl_sec = config.client_live_ttl_sec;
         nof_heartbeat_interval_sec = config.nof_heartbeat_interval_sec;
@@ -720,6 +853,12 @@ class WrappedMasterServiceConfig {
         promotion_on_hit = config.promotion_on_hit;
         promotion_admission_threshold = config.promotion_admission_threshold;
         promotion_queue_limit = config.promotion_queue_limit;
+        io_pattern_tier_down_bytes_per_cycle =
+            config.io_pattern_tier_down_bytes_per_cycle;
+        io_pattern_admission_frequency_threshold =
+            config.io_pattern_admission_frequency_threshold;
+        io_pattern_admission_watermark_ratio =
+            config.io_pattern_admission_watermark_ratio;
         promotion_max_per_heartbeat = config.promotion_max_per_heartbeat;
         enable_kv_events = config.enable_kv_events;
         kv_events_bind_endpoint = config.kv_events_bind_endpoint;
@@ -741,6 +880,10 @@ class WrappedMasterServiceConfig {
         oplog_poll_interval_ms = config.oplog_poll_interval_ms;
         oplog_batch_max_entries = config.oplog_batch_max_entries;
         cluster_id = config.cluster_id;
+        master_id = config.local_hostname;
+        submaster_count = config.submaster_count;
+        cvm_http_port = config.cvm_http_port;
+        cvm_http_host = config.cvm_http_host;
         root_fs_dir = config.root_fs_dir;
         global_file_segment_size = config.global_file_segment_size;
         memory_allocator = config.memory_allocator;
@@ -773,6 +916,8 @@ class WrappedMasterServiceConfig {
         cxl_path = config.cxl_path;
         cxl_size = config.cxl_size;
         enable_cxl = config.enable_cxl;
+        vchunk_config = config.vchunk_config;
+        vchunk_etcd_endpoints = config.vchunk_etcd_endpoints;
     }
 };
 
@@ -841,6 +986,8 @@ class MasterServiceConfigBuilder {
     std::string cxl_path_ = DEFAULT_CXL_PATH;
     size_t cxl_size_ = DEFAULT_CXL_SIZE;
     bool enable_cxl_ = false;
+    VChunkConfig vchunk_config_{};
+    std::shared_ptr<VChunkMetadataStore> vchunk_metadata_store_;
 
    public:
     MasterServiceConfigBuilder() = default;
@@ -985,6 +1132,17 @@ class MasterServiceConfigBuilder {
         return *this;
     }
 
+    MasterServiceConfigBuilder& set_vchunk_config(VChunkConfig config) {
+        vchunk_config_ = std::move(config);
+        return *this;
+    }
+
+    MasterServiceConfigBuilder& set_vchunk_metadata_store(
+        std::shared_ptr<VChunkMetadataStore> store) {
+        vchunk_metadata_store_ = std::move(store);
+        return *this;
+    }
+
     MasterServiceConfigBuilder& set_tenant_quota_connector_type(
         const std::string& type) {
         tenant_quota_connector_type_ = type;
@@ -1155,6 +1313,10 @@ class MasterServiceConfig {
     double nof_eviction_ratio = DEFAULT_NOF_EVICTION_RATIO;
     double nof_eviction_high_watermark_ratio =
         DEFAULT_NOF_EVICTION_HIGH_WATERMARK_RATIO;
+    // Report-driven cold-data eviction driver (embedded CFM component).
+    bool io_pattern_cold_eviction = false;
+    uint64_t io_pattern_cold_eviction_bytes_per_cycle = 0;
+    uint64_t io_pattern_cold_idle_threshold_us = 0;
     ViewVersionId view_version = 0;
     int64_t client_live_ttl_sec = DEFAULT_CLIENT_LIVE_TTL_SEC;
     int64_t nof_heartbeat_interval_sec = DEFAULT_NOF_HEARTBEAT_INTERVAL_SEC;
@@ -1172,6 +1334,19 @@ class MasterServiceConfig {
     bool promotion_on_hit = false;
     uint32_t promotion_admission_threshold = 2;
     uint32_t promotion_queue_limit = 50000;
+    // Policy-driven tier down: below the memory watermark, copy the coldest
+    // objects down to local disk while keeping their MEMORY replica (tier down is
+    // a copy, not a reclaim), so a later reclaim can discard them safely. There
+    // is no separate enable switch: a non-zero per-cycle budget is the control,
+    // and 0 keeps the driver off. A reclaim always wins, so a cycle that reaches
+    // the watermark evicts instead of demoting.
+    uint64_t io_pattern_tier_down_bytes_per_cycle = 0;
+    // Admission gates. The frequency threshold defaults to 2, matching the
+    // master's own second-touch promotion gate; 1 restores the previous
+    // admit-on-first-sight behaviour. A negative watermark means "derive it from
+    // eviction_high_watermark_ratio", so admission stops before eviction starts.
+    uint32_t io_pattern_admission_frequency_threshold = 2;
+    double io_pattern_admission_watermark_ratio = -1.0;
     uint32_t promotion_max_per_heartbeat = 1;
     bool enable_kv_events = false;
     std::string kv_events_bind_endpoint;
@@ -1192,6 +1367,19 @@ class MasterServiceConfig {
     int oplog_poll_interval_ms = 1000;
     uint32_t oplog_batch_max_entries = 1024;
     std::string cluster_id = DEFAULT_CLUSTER_ID;
+    // Stable identifier of this master instance, used as the SlotOwner
+    // primary_master_id for the KV partition view. Empty disables the
+    // SlotOwnerHeartbeat. In HA mode this is the local_hostname.
+    std::string master_id;
+    // CVM external HTTP API (CvmHttpServer) bind config. Port 0 keeps the
+    // HTTP server disabled; set a non-zero port to expose /kv_view,
+    // /segment_view and /health for inspection.
+    uint16_t cvm_http_port = 0;
+    std::string cvm_http_host = "0.0.0.0";
+    // 集群中允许同时 serving 的 submaster 上限（CVM 名额协调，先到先得）。
+    // 默认 1 保持单主行为；>1 时多 submaster 均分 slot，超出 k 名自动降级为
+    // standby。
+    uint32_t submaster_count = 1;
     std::string root_fs_dir = DEFAULT_ROOT_FS_DIR;
     int64_t global_file_segment_size = DEFAULT_GLOBAL_FILE_SEGMENT_SIZE;
     BufferAllocatorType memory_allocator = BufferAllocatorType::OFFSET;
@@ -1227,6 +1415,9 @@ class MasterServiceConfig {
     std::string cxl_path = DEFAULT_CXL_PATH;
     size_t cxl_size = DEFAULT_CXL_SIZE;
     bool enable_cxl = false;
+    VChunkConfig vchunk_config{};
+    std::string vchunk_etcd_endpoints;
+    std::shared_ptr<VChunkMetadataStore> vchunk_metadata_store;
     MasterServiceConfig() = default;
 
     // From WrappedMasterServiceConfig
@@ -1242,6 +1433,11 @@ class MasterServiceConfig {
         nof_eviction_ratio = config.nof_eviction_ratio;
         nof_eviction_high_watermark_ratio =
             config.nof_eviction_high_watermark_ratio;
+        io_pattern_cold_eviction = config.io_pattern_cold_eviction;
+        io_pattern_cold_eviction_bytes_per_cycle =
+            config.io_pattern_cold_eviction_bytes_per_cycle;
+        io_pattern_cold_idle_threshold_us =
+            config.io_pattern_cold_idle_threshold_us;
         view_version = config.view_version;
         client_live_ttl_sec = config.client_live_ttl_sec;
         nof_heartbeat_interval_sec = config.nof_heartbeat_interval_sec;
@@ -1258,6 +1454,12 @@ class MasterServiceConfig {
         promotion_on_hit = config.promotion_on_hit;
         promotion_admission_threshold = config.promotion_admission_threshold;
         promotion_queue_limit = config.promotion_queue_limit;
+        io_pattern_tier_down_bytes_per_cycle =
+            config.io_pattern_tier_down_bytes_per_cycle;
+        io_pattern_admission_frequency_threshold =
+            config.io_pattern_admission_frequency_threshold;
+        io_pattern_admission_watermark_ratio =
+            config.io_pattern_admission_watermark_ratio;
         promotion_max_per_heartbeat = config.promotion_max_per_heartbeat;
         enable_kv_events = config.enable_kv_events;
         kv_events_bind_endpoint = config.kv_events_bind_endpoint;
@@ -1277,6 +1479,10 @@ class MasterServiceConfig {
         oplog_poll_interval_ms = config.oplog_poll_interval_ms;
         oplog_batch_max_entries = config.oplog_batch_max_entries;
         cluster_id = config.cluster_id;
+        master_id = config.master_id;
+        cvm_http_port = config.cvm_http_port;
+        cvm_http_host = config.cvm_http_host;
+        submaster_count = config.submaster_count;
         root_fs_dir = config.root_fs_dir;
         global_file_segment_size = config.global_file_segment_size;
         memory_allocator =
@@ -1315,6 +1521,12 @@ class MasterServiceConfig {
         cxl_path = config.cxl_path;
         cxl_size = config.cxl_size;
         enable_cxl = config.enable_cxl;
+        vchunk_config = config.vchunk_config;
+        vchunk_etcd_endpoints = config.vchunk_etcd_endpoints;
+        if (vchunk_config.enabled && !vchunk_etcd_endpoints.empty()) {
+            vchunk_metadata_store = std::make_shared<EtcdVChunkMetadataStore>(
+                vchunk_etcd_endpoints, vchunk_config, cluster_id);
+        }
     }
 
     // Static factory method to create a builder
@@ -1381,6 +1593,10 @@ inline MasterServiceConfig MasterServiceConfigBuilder::build() const {
     config.cxl_path = cxl_path_;
     config.cxl_size = cxl_size_;
     config.enable_cxl = enable_cxl_;
+    config.vchunk_config = vchunk_config_;
+    config.vchunk_metadata_store = vchunk_metadata_store_;
+    config.vchunk_config = vchunk_config_;
+    config.vchunk_metadata_store = vchunk_metadata_store_;
     return config;
 }
 
diff --git a/mooncake-store/include/master_metric_manager.h b/mooncake-store/include/master_metric_manager.h
index 07e565d542..bc26c246d0 100644
--- a/mooncake-store/include/master_metric_manager.h
+++ b/mooncake-store/include/master_metric_manager.h
@@ -3,6 +3,7 @@
 #include <atomic>
 #include <chrono>
 #include <mutex>
+#include <memory>
 #include <string>
 #include <unordered_map>
 
@@ -12,6 +13,10 @@
 
 namespace mooncake {
 
+namespace io_pattern {
+class IoPatternRuntime;
+}
+
 class MasterMetricManager {
    public:
     // --- Singleton Access ---
@@ -277,8 +282,6 @@ class MasterMetricManager {
     // nof eviction metrics
     void inc_nof_eviction_success(int64_t key_count, int64_t size);
     void inc_nof_eviction_fail();  // not a single object is evicted
-
-    // Eviction Metrics Getters
     // total eviction metrics
     int64_t get_eviction_success();
     int64_t get_eviction_attempts();
@@ -295,6 +298,35 @@ class MasterMetricManager {
     int64_t get_nof_evicted_key_count();
     int64_t get_nof_evicted_size();
 
+    // Report-driven IO Pattern policy execution metrics. These count the
+    // SubMaster-local policy cycles that run when merged client reports
+    // (report_snapshot / report_metric_batch) indicate storage pressure, so
+    // remote-mode eviction/prefetch/admission execution is observable in
+    // master admin metrics (not only the embedded watermark path).
+    void inc_io_pattern_report_cycles(int64_t val = 1);
+    void inc_io_pattern_report_evictions(int64_t val = 1);
+    void inc_io_pattern_report_eviction_failures(int64_t val = 1);
+    void inc_io_pattern_report_prefetches(int64_t val = 1);
+    void inc_io_pattern_report_prefetch_failures(int64_t val = 1);
+    void inc_io_pattern_report_admissions(int64_t val = 1);
+    void inc_io_pattern_report_admission_failures(int64_t val = 1);
+    void inc_io_pattern_report_degraded(int64_t val = 1);
+    // Report-driven IO Pattern execution metrics getters
+    int64_t get_io_pattern_report_cycles();
+    int64_t get_io_pattern_report_evictions();
+    int64_t get_io_pattern_report_eviction_failures();
+    int64_t get_io_pattern_report_prefetches();
+    int64_t get_io_pattern_report_prefetch_failures();
+    int64_t get_io_pattern_report_admissions();
+    int64_t get_io_pattern_report_admission_failures();
+    int64_t get_io_pattern_report_degraded();
+
+    // Scrape the local runtime directly, including access-only traffic. A weak
+    // reference keeps the metrics singleton from extending MasterService life.
+    void set_io_pattern_runtime(
+        std::weak_ptr<io_pattern::IoPatternRuntime> runtime);
+    void clear_io_pattern_runtime(const io_pattern::IoPatternRuntime* runtime);
+
     // PutStart Discard Metrics
     void inc_put_start_discard_cnt(int64_t count, int64_t size);
     void inc_put_start_release_cnt(int64_t count, int64_t size);
@@ -426,6 +458,7 @@ class MasterMetricManager {
 
     // Update all metrics once to ensure zero values are serialized
     void update_metrics_for_zero_output();
+    std::string serialize_io_pattern_metrics();
     std::string get_summary_string(bool update_summary_snapshot);
 
     struct SummaryCounters {
@@ -528,6 +561,8 @@ class MasterMetricManager {
 
     // --- Metric Members ---
     std::mutex summary_snapshot_mutex_;
+    std::mutex io_pattern_runtime_mutex_;
+    std::weak_ptr<io_pattern::IoPatternRuntime> io_pattern_runtime_;
     SummarySnapshot summary_snapshot_;
 
     // Memory Storage Metrics
@@ -684,6 +719,16 @@ class MasterMetricManager {
     ylt::metric::counter_t nof_evicted_key_count_;
     ylt::metric::counter_t nof_evicted_size_;
 
+    // Report-driven IO Pattern policy execution metrics
+    ylt::metric::counter_t io_pattern_report_cycles_;
+    ylt::metric::counter_t io_pattern_report_evictions_;
+    ylt::metric::counter_t io_pattern_report_eviction_failures_;
+    ylt::metric::counter_t io_pattern_report_prefetches_;
+    ylt::metric::counter_t io_pattern_report_prefetch_failures_;
+    ylt::metric::counter_t io_pattern_report_admissions_;
+    ylt::metric::counter_t io_pattern_report_admission_failures_;
+    ylt::metric::counter_t io_pattern_report_degraded_;
+
     // PutStart Discard Metrics
     ylt::metric::counter_t put_start_discard_cnt_;
     ylt::metric::counter_t put_start_release_cnt_;
diff --git a/mooncake-store/include/master_service.h b/mooncake-store/include/master_service.h
index f1f14e1990..ae2e3a3dfc 100644
--- a/mooncake-store/include/master_service.h
+++ b/mooncake-store/include/master_service.h
@@ -12,6 +12,7 @@
 #include <memory>
 #include <mutex>
 #include <optional>
+#include <set>
 #include <shared_mutex>
 #include <string>
 #include <string_view>
@@ -25,6 +26,10 @@
 
 #include "allocation_strategy.h"
 #include "count_min_sketch.h"
+#include "cvm/cvm_controller.h"
+#include "cvm/inter_master_rpc.h"
+#include "cvm/slot_hash.h"
+#include "cvm/slot_owner_heartbeat.h"
 #include "deadline_scheduler.h"
 #include "master_metric_manager.h"
 #include "mutex.h"
@@ -32,6 +37,7 @@
 #include "tenant_quota_sharded.h"
 #include "tenant_quota_policy_store.h"
 #include "types.h"
+#include "vchunk_master_manager.h"
 #include "master_config.h"
 #include "rpc_types.h"
 #include "replica.h"
@@ -46,6 +52,11 @@
 
 namespace mooncake {
 
+namespace io_pattern {
+class CfmService;
+class IoPatternRuntime;
+}
+
 // Forward declaration for MasterSnapshotManager
 class MasterSnapshotManager;
 class MasterSnapshotRepository;
@@ -78,6 +89,9 @@ class SnapshotChildProcessTest;
 class PromotionOnHitTest;
 class MasterServiceTenantQuotaTest;
 class MasterServiceHATest;
+// Friended so the offload-on-evict tests can drive the legacy eviction fallback
+// that the IO Pattern eviction handler runs when a plan under-delivers.
+class OffloadOnEvictTest;
 }  // namespace test
 namespace benchmarks {
 class BatchEvictBench;
@@ -113,6 +127,7 @@ class MasterService {
                                            // members
     friend class ha::MasterSnapshotCodecTest;  // codec round-trip unit test
     friend class test::MasterServiceHATest;
+    friend class test::OffloadOnEvictTest;
 
    public:
     using NoFProbeFn =
@@ -142,6 +157,80 @@ class MasterService {
     ErrorCode SetBatchOpLogBackendForTesting(
         std::shared_ptr<HaKvBackend> backend);
 
+    // CVM slot ownership publishing. The CvmController now lives in the HA
+    // supervisor so membership keeps running even while this node is a
+    // standby; the supervisor injects the lease id it granted and drives the
+    // heartbeat around serve start/stop.
+    void SetCvmLeaseId(EtcdLeaseId lease_id);
+    ErrorCode StartSlotOwnerHeartbeat();
+    void StopSlotOwnerHeartbeat();
+
+    // CVM inter-master RPC (multi-submaster coordination). Starts the
+    // etcd-driven member refresh loop so this master can reach its peers
+    // (handshake now; allocation forwarding later). Same lifecycle as the
+    // slot owner heartbeat: called by the supervisor around serve phases.
+    ErrorCode StartInterMasterRpc();
+    void StopInterMasterRpc();
+    cvm::InterMasterRpcClient* inter_master_rpc() const {
+        return inter_master_rpc_.get();
+    }
+
+    // Inter-master handshake data: stable identity, supervisor-granted lease
+    // and current owned-slot count (read path / forwarding diagnostics).
+    const std::string& master_id() const { return master_id_; }
+    EtcdLeaseId cvm_lease_id() const { return cvm_lease_id_; }
+    uint32_t GetOwnedSlotCount() const;
+
+    // Inter-master allocation forwarding (CVM plan B phase 2). Called by
+    // WrappedMasterService when a slot-owning peer asks this submaster
+    // (segment owner) to allocate memory replicas. `preferred_segments`
+    // is honored strictly when non-empty. Real handles are kept alive in
+    // a keepalive registry until InterMasterFreeReplicas arrives.
+    tl::expected<std::vector<Replica::Descriptor>, ErrorCode>
+    InterMasterAllocateReplicas(const std::string& tenant_id,
+                                const std::string& key, uint64_t slice_length,
+                                uint64_t replica_num,
+                                const std::vector<std::string>& preferred_segments);
+
+    // Frees the keepalive entry (and the handles) for (tenant, key).
+    // Idempotent: returns false when no entry exists.
+    tl::expected<bool, ErrorCode> InterMasterFreeReplicas(
+        const std::string& tenant_id, const std::string& key);
+
+    // Inter-master read forwarding (CVM plan B phase 2). Called by
+    // WrappedMasterService when a peer submaster forwards a GetReplicaList /
+    // BatchGetReplicaList request to this submaster (the slot owner). Unlike
+    // the client-facing GetReplicaList, these do NOT re-forward: they query
+    // the local metadata directly (peer trust), so an inconsistent view
+    // terminates the forward chain at the first hop instead of looping.
+    tl::expected<GetReplicaListResponse, ErrorCode> InterMasterGetReplicaList(
+        const std::string& key, const std::string& tenant_id);
+
+    std::vector<tl::expected<GetReplicaListResponse, ErrorCode>>
+    InterMasterBatchGetReplicaList(const std::vector<std::string>& keys,
+                                   const std::string& tenant_id);
+
+    // Inter-master write forwarding (model B). Called by WrappedMasterService
+    // when a peer submaster received a PutStart for a slot it does not own: it
+    // relays the FULL PutStart to this submaster (the slot owner), which
+    // executes the complete local alloc + metadata + keepalive and returns the
+    // descriptors for the caller to relay to the client. Because this is the
+    // slot owner, its OwnsSlot==true so the forward chain terminates here
+    // (peer trust, symmetric with InterMasterGetReplicaList).
+    tl::expected<std::vector<Replica::Descriptor>, ErrorCode> InterMasterPutStart(
+        const UUID& client_id, const std::string& key,
+        const std::string& tenant_id, uint64_t slice_length,
+        const ReplicateConfig& config);
+
+    // Upsert variant of InterMasterPutStart: the slot owner executes the FULL
+    // UpsertStart (preserving the "overwrite if exists" preemption semantics
+    // that PutStart lacks), and returns the descriptors for the caller to
+    // relay to the client.
+    tl::expected<std::vector<Replica::Descriptor>, ErrorCode>
+    InterMasterUpsertStart(const UUID& client_id, const std::string& key,
+                           const std::string& tenant_id, uint64_t slice_length,
+                           const ReplicateConfig& config);
+
     /**
      * @brief Test-only wrapper around BatchEvict / NoFBatchEvict so that
      *        unit tests can drive a single eviction cycle synchronously
@@ -164,6 +253,29 @@ class MasterService {
     auto MountSegment(const Segment& segment, const UUID& client_id)
         -> tl::expected<void, ErrorCode>;
 
+    tl::expected<VChunkMetadataRecord, ErrorCode> VChunkPutStart(
+        const TenantId& tenant_id, const std::string& key,
+        uint64_t total_size, bool is_ssd_segment, int64_t now_ms,
+        const std::set<std::string>& excluded_segments = {});
+    ErrorCode VChunkPutEnd(const TenantId& tenant_id, const std::string& key,
+                           const std::string& vchunk_id, int64_t now_ms);
+    ErrorCode VChunkPutRevoke(const TenantId& tenant_id,
+                              const std::string& key,
+                              const std::string& vchunk_id);
+    tl::expected<VChunkMetadataRecord, ErrorCode> GetVChunk(
+        const TenantId& tenant_id, const std::string& key) const;
+    tl::expected<VChunkMasterManager::ReadHandle, ErrorCode> AcquireVChunkRead(
+        const TenantId& tenant_id, const std::string& key) const;
+    tl::expected<VChunkReadLease, ErrorCode> AcquireVChunkReadLease(
+        const TenantId& tenant_id, const std::string& key, int64_t now_ms);
+    ErrorCode ReleaseVChunkReadLease(const std::string& lease_id);
+    ErrorCode RemoveVChunk(const TenantId& tenant_id, const std::string& key,
+                           int64_t now_ms);
+    VChunkRuntimeInfo GetVChunkRuntimeInfo() const;
+    tl::expected<size_t, ErrorCode> ReapExpiredVChunks(int64_t now_ms,
+                                                       size_t max_scan);
+    VChunkMetricsSnapshot GetVChunkMetrics() const;
+
     /**
      * @brief Mount a NoF SSD segment for buffer allocation. This function is
      * idempotent.
@@ -330,6 +442,10 @@ class MasterService {
     bool KvEventsEnabled() const;
     KvEventPublisher::Stats GetKvEventStats() const;
 
+    std::shared_ptr<io_pattern::CfmService> GetCfmService() const {
+        return io_pattern_cfm_service_;
+    }
+
     /**
      * @brief Batch clear KV cache replicas for specified object keys.
      * @param object_keys Vector of object key strings to clear.
@@ -877,6 +993,22 @@ class MasterService {
      */
     void setHttpMetadataRemoteUrl(const std::string& metadata_connstring);
 
+    /**
+     * @brief Policy-driven tier-down dispatch counters. Independent of the
+     * eviction counters because a demotion copies an object down and keeps its
+     * MEMORY replica: it frees no bytes, so folding it into freed memory would
+     * make a tier-down plan look like a plan that under-delivered.
+     */
+    uint64_t tier_down_attempt_count() const {
+        return tier_down_attempts_.load(std::memory_order_relaxed);
+    }
+    uint64_t tier_down_success_count() const {
+        return tier_down_successes_.load(std::memory_order_relaxed);
+    }
+    uint64_t tier_down_failure_count() const {
+        return tier_down_failures_.load(std::memory_order_relaxed);
+    }
+
    private:
     std::unique_ptr<ha::SnapshotCatalogStore> CreateSnapshotCatalogStore();
 
@@ -909,7 +1041,24 @@ class MasterService {
         uint64_t evicted_objects{0};
     };
     TenantQuotaEvictionResult EvictTenantMemoryForQuota(
-        const TenantId& tenant_id, uint64_t target_bytes);
+        const TenantId& tenant_id, uint64_t target_bytes,
+        const std::unordered_set<std::string>* candidate_keys = nullptr);
+
+    // After an eviction pass, reports a kRemoved tier event for every candidate
+    // key whose MEMORY replica is actually gone, so the IO Pattern collector
+    // stops claiming an L1 replica for it. Presence is read from authoritative
+    // metadata rather than inferred from access recency: an evicted key must
+    // become promotable again, while a cold key that has simply not been read
+    // must stay eligible for eviction.
+    void ReportEvictedKeysAsTierRemovals(
+        const TenantId& tenant,
+        const std::unordered_set<std::string>& candidate_keys);
+
+    // Runs the legacy lease-ordered eviction for an IO Pattern plan that could
+    // not free its byte target (stale candidates, active leases, pins, or an
+    // empty candidate set), so a watermark request still makes progress.
+    // Returns true when the fallback ran.
+    bool RunLegacyEvictionFallback(uint64_t shortfall_bytes);
 
     // Helper to get a snapshot of alive clients (under client_mutex_ shared
     // lock)
@@ -1471,20 +1620,23 @@ class MasterService {
     bool IsTenantRegistered(const TenantId& tenant_id) const;
     bool TenantHasObjects(const TenantId& tenant_id) const;
 
-    // Helper to get shard index from tenant-scoped object identity.
+    // Helper to get the logical slot (Redis Cluster style, 16384 slots) for
+    // a tenant-scoped key. Slots are the unit of cross-master ownership.
+    uint16_t getSlot(const TenantId& tenant_id,
+                     const std::string& user_key) const {
+        return cvm::KeySlot(tenant_id, user_key);
+    }
+
+    // Helper to get shard index from tenant-scoped object identity. The
+    // physical shard is derived from the logical slot.
     size_t getShardIndex(const TenantId& tenant_id,
                          const std::string& user_key) const {
-        if (tenant_id.IsDefault()) {
-            return std::hash<std::string>{}(user_key) % kNumShards;
-        }
-        size_t seed = std::hash<std::string>{}(tenant_id.value());
-        boost::hash_combine(seed, user_key);
-        return seed % kNumShards;
+        return getSlot(tenant_id, user_key) % kNumShards;
     }
 
     // Legacy helper routes plain keys to the default tenant.
     size_t getShardIndex(const std::string& key) const {
-        return std::hash<std::string>{}(key) % kNumShards;
+        return getSlot(TenantId::Default(), key) % kNumShards;
     }
 
     size_t getMetadataShardIndex(const TenantId& tenant_id,
@@ -1507,6 +1659,9 @@ class MasterService {
         kFull,
         kPreserveOld,
         kAbortOnly,
+        // slot 交接：与 kFull 相同，但跳过 ReleaseLocalDiskUsage，因为数据字节
+        // 仍留在共享 segment（不应错误扣减 ssd_used_bytes）。
+        kHandoff,
     };
     std::unordered_map<std::string, ObjectMetadata>::iterator EraseMetadata(
         TenantState& tenant_state,
@@ -1585,6 +1740,11 @@ class MasterService {
         const std::chrono::system_clock::time_point& now)
         -> tl::expected<std::vector<Replica::Descriptor>, ErrorCode>;
 
+    auto PutEndInternal(const UUID& client_id, const ObjectMeta& object_meta,
+                        const TenantId& tenant_id, ReplicaType replica_type,
+                        uint32_t write_batch_size, bool overwrite)
+        -> tl::expected<void, ErrorCode>;
+
     /**
      * @brief Helper to discard expired processing keys.
      */
@@ -1642,6 +1802,20 @@ class MasterService {
      */
     PromotionQueueResult TryPushPromotionQueue(const ObjectIdentity& object_id,
                                                bool record_candidate = true);
+
+    /**
+     * @brief Queue one MEMORY replica of `object_id` for a LOCAL_DISK copy
+     * (tier down) and keep the MEMORY replica in place.
+     *
+     * This is the demotion counterpart of an eviction: it never removes a
+     * replica and never frees bytes, so the caller must not count its result as
+     * reclaimed memory. Acquires its own RW shard accessor; safe to call from
+     * the io_pattern eviction handler, which does not hold one while this runs.
+     * Returns false when the key vanished, has no completed MEMORY replica, or
+     * the holder client cannot accept the offload. A key that is already queued
+     * counts as success: it is already on its way down.
+     */
+    bool TryQueueTierDown(const ObjectIdentity& object_id);
     void RecordOrUpdateCandidate(TenantState& tenant_state,
                                  const std::string& key, uint8_t sketch_score,
                                  PromotionCandidateReason reason,
@@ -1695,6 +1869,10 @@ class MasterService {
     // Eviction thread related members
     std::thread eviction_thread_;
     std::atomic<bool> eviction_running_{false};
+    // Serializes legacy eviction fallbacks: the watermark thread and the
+    // report-driven worker can both observe a shortfall, and BatchEvict has no
+    // re-entrancy protection.
+    std::mutex legacy_eviction_mutex_;
     static constexpr uint64_t kEvictionThreadSleepMs =
         10;  // 10 ms sleep between eviction checks
 
@@ -2095,6 +2273,25 @@ class MasterService {
     // from any GetReplicaList caller without additional locking.
     std::unique_ptr<CountMinSketch> promotion_sketch_;
 
+    // The IO-pattern pipeline is deliberately owned by MasterService: the
+    // master has the authoritative replica map and is the only component that
+    // can safely translate a policy plan into promotion/eviction operations.
+    // CFM is embedded here as a component of this SubMaster: reports addressed
+    // to the keys this master owns are merged into the local runtime over the
+    // regular coro_rpc endpoint, so no remote reporting channel, policy poller
+    // or credential is needed.
+    std::shared_ptr<io_pattern::IoPatternRuntime> io_pattern_runtime_;
+    std::shared_ptr<io_pattern::CfmService> io_pattern_cfm_service_;
+
+    // Policy-driven tier down. Kept separate from the eviction counters because a
+    // demotion queues a disk copy and frees no memory: folding it into freed
+    // bytes would make a tier-down plan look like a plan that under-delivered.
+    // Written only from the io_pattern eviction handler; relaxed order is enough
+    // because these are advisory observability counters.
+    std::atomic<uint64_t> tier_down_attempts_{0};
+    std::atomic<uint64_t> tier_down_successes_{0};
+    std::atomic<uint64_t> tier_down_failures_{0};
+
     const std::string ha_backend_type_;
 
     const std::string ha_backend_connstring_;
@@ -2103,6 +2300,114 @@ class MasterService {
 
     // cluster id for persistent sub directory
     const std::string cluster_id_;
+    // Stable master id used by the SlotOwnerHeartbeat (empty = disabled).
+    const std::string master_id_;
+    // CVM external HTTP API (CvmHttpServer) bind config. Port 0 keeps the
+    // HTTP server disabled.
+    const uint16_t cvm_http_port_;
+    const std::string cvm_http_host_;
+    // 集群中允许同时 serving 的 submaster 上限（CVM 名额协调）。
+    const uint32_t submaster_count_;
+    // Publishes this submaster's slot ownership to etcd for the KV partition
+    // view. Only started in HA mode when a stable master_id is configured.
+    std::unique_ptr<cvm::SlotOwnerHeartbeat> slot_owner_heartbeat_;
+    // Inter-master RPC client (CVM multi-submaster coordination): etcd-driven
+    // member table + per-peer cached coro_rpc pools. Started/stopped by the
+    // supervisor around serve phases, mirroring the heartbeat above.
+    std::unique_ptr<cvm::InterMasterRpcClient> inter_master_rpc_;
+
+    // ----- Inter-master allocation forwarding (CVM plan B phase 2) -----
+
+    // Segment-owner side: keepalive for replicas allocated on behalf of
+    // slot-owning peers, keyed by scoped key. The real handles stay alive
+    // here; the peer only holds dummy-allocator replicas. Freed by
+    // InterMasterFreeReplicas (broadcast by the slot owner on erase).
+    std::mutex inter_master_keepalive_mutex_;
+    std::unordered_map<std::string, std::vector<Replica>>
+        inter_master_keepalive_;
+
+    // Slot-owner side: scoped keys whose handles live on a peer submaster
+    // (remote-allocated or migrated-in). Drives the broadcast-free on
+    // EraseMetadata; kHandoff (slot migration) keeps the handles alive and
+    // transfers the responsibility to the importing master.
+    std::mutex remote_allocated_keys_mutex_;
+    std::unordered_set<std::string> remote_allocated_keys_;
+
+    // Slot-owner side: keeps the DummyBufferAllocator of remote replicas
+    // alive (the replicas hold only weak references), keyed by endpoint.
+    std::mutex remote_replica_allocator_keepalive_mutex_;
+    std::unordered_map<std::string, std::shared_ptr<DummyBufferAllocator>>
+        remote_replica_allocator_keepalive_;
+
+    // Slot-owner side: local allocation failed, try peers (segment owners)
+    // before giving up. Called OUTSIDE the local allocator lock to avoid
+    // distributed deadlock (both masters forwarding simultaneously).
+    tl::expected<std::vector<Replica>, ErrorCode> TryAllocateReplicasRemotely(
+        const std::string& key, const TenantId& tenant_id,
+        uint64_t value_length, size_t replica_num,
+        const std::vector<std::string>& preferred_segments);
+
+    // EraseMetadata hook: when the erased object's handles live on a peer,
+    // enqueue a broadcast free (skipped for kHandoff: the data bytes must
+    // survive the slot migration).
+    void EnqueueRemoteFreeIfTracked(const TenantId& tenant_id,
+                                    const std::string& key,
+                                    QuotaEraseMode quota_mode);
+    // Lease id granted by the supervisor-owned CvmController. Reused by the
+    // SlotOwnerHeartbeat and segment owner records so they share the master
+    // registration lifecycle (auto-removed on lease expiry). 0 until the
+    // supervisor injects it via SetCvmLeaseId().
+    EtcdLeaseId cvm_lease_id_{0};
+    // 读路径 slot 所有权校验位图（A1）。由心跳 resolver 与晋升路径更新，
+    // GetReplicaList / BatchGetReplicaList 读路径校验，非 owner 拒绝服务。
+    // owned_slots_ready_ 为 false 表示 partition 未启用或尚未解析过，放行。
+    mutable std::shared_mutex owned_slots_mutex_;
+    std::vector<bool> owned_slot_lookup_;
+    bool owned_slots_ready_{false};
+    // 仅当 owned slot 数量变化时打印 INFO 日志（避免心跳周期刷屏）。
+    bool owned_slot_count_logged_{false};
+    std::size_t last_logged_owned_count_{0};
+    // Segment view (CVM) 数据源：在 segment 挂载/卸载时把 segment owner 原始
+    // 记录同步到 etcd（segment_view/<id>），供 CvmController 聚合生成 segment
+    // view 快照。仅在 etcd HA backend 下生效，其余场景为空操作。
+    void PublishSegmentOwnerForCvm(const Segment& segment);
+    void RemoveSegmentOwnerForCvm(const UUID& segment_id);
+    // 动态 KV slot 划分：以 etcd 注册表为唯一事实源，读取已注册的 primary
+    // master 列表，按一致性哈希环（cvm::ResolveOwnedSlotsOnRing）计算本机
+    // 应拥有的 slot 集合。etcd 读取失败时沿用上一轮结果（sticky），避免
+    // 瞬时抖动引发全量抢夺；本机不在 primary 列表时返回空集合（不认领）。
+    // 供 SlotOwnerHeartbeat 动态解析器回调调用（运行在心跳线程）。
+    std::vector<uint16_t> ResolveOwnedSlotsForCvm();
+    // sticky 缓存：最近一次成功解析的 owned slot 集合（etcd 抖动时沿用）。
+    std::vector<uint16_t> cvm_last_resolved_owned_slots_;
+    mutable std::mutex cvm_resolver_mutex_;
+    // live primary → live primary 的 slot 元数据交接（P4 技术债 1）。
+    // ExportSlotMetadata 把 `slot` 下所有对象的元数据序列化后写入 etcd，再
+    // 从本地 metadata_shards_ 擦除；ImportSlotMetadata 从 etcd 读回并物化到
+    // 本地 metadata_shards_。数据字节始终留在 segment，不搬移。两者均由
+    // SlotOwnerHeartbeat 的 on_slot_released / on_slot_acquired 钩子在心跳
+    // 线程调用。
+    ErrorCode ExportSlotMetadata(uint16_t slot);
+    ErrorCode ImportSlotMetadata(uint16_t slot);
+    // A1：读路径 slot 所有权校验。UpdateOwnedSlots 由心跳 resolver 与晋升路径
+    // 调用，把最新 owned slot 集合写入位图；OwnsSlot 供读路径查询（未就绪放行）。
+    void UpdateOwnedSlots(const std::vector<uint16_t>& slots);
+    bool OwnsSlot(uint16_t slot) const;
+    // 读路径转发：解析任意 slot 的 owner master_id（基于一致性哈希环与
+    // etcd 中的 primary master 列表）。解析失败返回 nullopt。供 GetReplicaList
+    // / BatchGetReplicaList 在 OwnsSlot 失败时向 slot owner 转发请求。
+    std::optional<std::string> ResolveSlotOwnerMasterId(uint16_t slot) const;
+    // GetReplicaList 的本地查询核心：不含 slot 所有权校验与转发，供
+    // client-facing GetReplicaList 与 InterMasterGetReplicaList 复用。
+    tl::expected<GetReplicaListResponse, ErrorCode> GetReplicaListLocal(
+        const ObjectIdentity& object_id);
+    // BatchGetReplicaList 的本地查询核心：不含 slot 所有权校验与转发，供
+    // client-facing BatchGetReplicaList 与 InterMasterBatchGetReplicaList
+    // 复用。
+    std::vector<tl::expected<GetReplicaListResponse, ErrorCode>>
+    BatchGetReplicaListLocal(const std::vector<std::string>& keys,
+                             const TenantId& tenant_id);
+    bool OwnsVChunkSlot(uint16_t slot) const;
     // root filesystem directory for persistent storage
     const std::string root_fs_dir_;
     // global 3fs/nfs segment size
@@ -2149,6 +2454,24 @@ class MasterService {
     // Segment management
     SegmentManager segment_manager_;
     NoFSegmentManager nof_segment_manager_;
+    VChunkMasterManager vchunk_manager_;
+    bool vchunk_enabled_{false};
+    uint64_t vchunk_reaper_interval_ms_{1000};
+    size_t vchunk_reaper_max_scan_{128};
+    std::atomic<bool> vchunk_reaper_running_{false};
+    bool vchunk_recovery_pending_{false};
+    struct VChunkRemoteReadLease {
+        VChunkMasterManager::ReadHandle handle;
+        int64_t expires_at_ms{0};
+    };
+    std::mutex vchunk_read_leases_mutex_;
+    std::unordered_map<std::string, VChunkRemoteReadLease>
+        vchunk_read_leases_;
+    std::thread vchunk_reaper_thread_;
+    std::mutex vchunk_reaper_mutex_;
+    std::condition_variable vchunk_reaper_cv_;
+    void StartVChunkReaper();
+    void VChunkReaperThreadFunc();
     BufferAllocatorType memory_allocator_type_;
     const AllocationStrategyType allocation_strategy_type_;
     std::shared_ptr<AllocationStrategy> allocation_strategy_;
diff --git a/mooncake-store/include/metadata_store.h b/mooncake-store/include/metadata_store.h
index 97c886ddf7..a91f880046 100644
--- a/mooncake-store/include/metadata_store.h
+++ b/mooncake-store/include/metadata_store.h
@@ -42,6 +42,8 @@ struct StandbyObjectMetadata {
     // Check if this metadata has valid replicas
     bool HasReplicas() const { return !replicas.empty(); }
 };
+YLT_REFL(StandbyObjectMetadata, client_id, size, replicas, last_sequence_id,
+         group_id, data_type);
 
 /**
  * Segment info stored in standby's segment registry.
@@ -72,6 +74,25 @@ struct StandbyObjectEntry {
     YLT_REFL(StandbyObjectEntry, tenant_id, key, metadata);
 };
 
+/**
+ * @brief Object-metadata export for a single KV slot (live primary -> live
+ * primary handoff).
+ *
+ * When a live primary gracefully releases a slot it no longer owns (scale-out /
+ * scale-in rebalance), it exports the object metadata of every key in that
+ * slot to etcd. The new owner then imports it to materialize the same
+ * key -> Replica::Descriptor[] mapping without moving any data bytes (which
+ * stay in their segments). Serialized with struct_pack (msgpack binary) and
+ * stored as a binary etcd value.
+ */
+struct SlotMetadataExport {
+    uint16_t slot{0};
+    std::string source_master_id;
+    std::vector<StandbyObjectEntry> objects;
+
+    YLT_REFL(SlotMetadataExport, slot, source_master_id, objects);
+};
+
 /**
  * Complete snapshot exported from standby at promotion time.
  * Includes applied OpLog sequence ID, all object metadata,
diff --git a/mooncake-store/include/observability.h b/mooncake-store/include/observability.h
new file mode 100644
index 0000000000..8e4b83cffc
--- /dev/null
+++ b/mooncake-store/include/observability.h
@@ -0,0 +1,2 @@
+#pragma once
+#include "io_pattern/observability.h"
diff --git a/mooncake-store/include/partition/kv_hash_map.h b/mooncake-store/include/partition/kv_hash_map.h
new file mode 100644
index 0000000000..65ad2f556b
--- /dev/null
+++ b/mooncake-store/include/partition/kv_hash_map.h
@@ -0,0 +1,23 @@
+#pragma once
+
+#include <cstdint>
+#include <string>
+
+#include "cvm/slot_hash.h"
+#include "tenant_id.h"
+
+namespace mooncake {
+namespace partition {
+
+// client 侧哈希分片：key → 逻辑 slot（0..16383）。
+// 复用 cvm::KeySlot（CRC32C），保证与 submaster 内部 getSlot 使用同一份实现，
+// 使 hash 相同的 key 必然落到同一个 submaster。
+class KvHashMap {
+   public:
+    static uint16_t Compute(const TenantId& tenant, const std::string& key) {
+        return cvm::KeySlot(tenant, key);
+    }
+};
+
+}  // namespace partition
+}  // namespace mooncake
diff --git a/mooncake-store/include/partition/partition_router.h b/mooncake-store/include/partition/partition_router.h
new file mode 100644
index 0000000000..f2d212e57c
--- /dev/null
+++ b/mooncake-store/include/partition/partition_router.h
@@ -0,0 +1,43 @@
+#pragma once
+
+#include <cstdint>
+#include <optional>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+#include "cvm/cvm_types.h"
+#include "mutex.h"
+#include "tenant_id.h"
+#include "types.h"
+
+namespace mooncake {
+namespace partition {
+
+// client 侧路由：应用 SlotOwner 映射，把逻辑 slot 解析为 submaster_id。
+// 映射来源为 etcd 快照（snapshot/kv_view，即 KvViewSnapshot），直读 etcd。
+class PartitionRouter {
+   public:
+    // 加载 slot → submaster 映射（覆盖式）。
+    void LoadSlotOwners(const std::vector<cvm::SlotOwner>& owners);
+
+    // 直读 etcd 快照（snapshot/kv_view）并刷新映射。
+    ErrorCode LoadFromEtcdSnapshot(const std::string& cluster_namespace);
+
+    // slot → submaster_id（primary_master_id）；未命中返回 nullopt。
+    std::optional<std::string> ResolveSubmaster(uint16_t slot) const;
+
+    // key → submaster_id（先哈希再路由）；未命中返回 nullopt。
+    std::optional<std::string> Route(const TenantId& tenant,
+                                     const std::string& key) const;
+
+    void Clear();
+    size_t Size() const;
+
+   private:
+    mutable SharedMutex mutex_;
+    std::unordered_map<uint16_t, std::string> slot_to_submaster_;
+};
+
+}  // namespace partition
+}  // namespace mooncake
diff --git a/mooncake-store/include/policy_engine.h b/mooncake-store/include/policy_engine.h
new file mode 100644
index 0000000000..9861c9c2fe
--- /dev/null
+++ b/mooncake-store/include/policy_engine.h
@@ -0,0 +1,3 @@
+#pragma once
+
+#include "io_pattern/policy_engine.h"
diff --git a/mooncake-store/include/policy_strategies.h b/mooncake-store/include/policy_strategies.h
new file mode 100644
index 0000000000..7a7c6001d4
--- /dev/null
+++ b/mooncake-store/include/policy_strategies.h
@@ -0,0 +1,3 @@
+#pragma once
+
+#include "io_pattern/policy_strategies.h"
diff --git a/mooncake-store/include/prefetch_ops.h b/mooncake-store/include/prefetch_ops.h
new file mode 100644
index 0000000000..9ef1ade825
--- /dev/null
+++ b/mooncake-store/include/prefetch_ops.h
@@ -0,0 +1,3 @@
+#pragma once
+
+#include "io_pattern/ops.h"
diff --git a/mooncake-store/include/reporter.h b/mooncake-store/include/reporter.h
new file mode 100644
index 0000000000..8877123fab
--- /dev/null
+++ b/mooncake-store/include/reporter.h
@@ -0,0 +1,2 @@
+#pragma once
+#include "io_pattern/reporter.h"
diff --git a/mooncake-store/include/resilient_analyzer.h b/mooncake-store/include/resilient_analyzer.h
new file mode 100644
index 0000000000..13e25d7901
--- /dev/null
+++ b/mooncake-store/include/resilient_analyzer.h
@@ -0,0 +1,2 @@
+#pragma once
+#include "io_pattern/resilient_analyzer.h"
diff --git a/mooncake-store/include/resilient_cfm_channel.h b/mooncake-store/include/resilient_cfm_channel.h
new file mode 100644
index 0000000000..654ac93cf9
--- /dev/null
+++ b/mooncake-store/include/resilient_cfm_channel.h
@@ -0,0 +1,2 @@
+#pragma once
+#include "io_pattern/resilient_cfm_channel.h"
diff --git a/mooncake-store/include/rpc_service.h b/mooncake-store/include/rpc_service.h
index 7abf3a34e1..25f7f56ac8 100644
--- a/mooncake-store/include/rpc_service.h
+++ b/mooncake-store/include/rpc_service.h
@@ -13,6 +13,7 @@
 #include "rpc_types.h"
 #include "master_config.h"
 #include "kv_event/kv_event_publisher.h"
+#include "io_pattern/cfm_service.h"
 #include "segment.h"
 
 namespace mooncake {
@@ -93,6 +94,24 @@ class WrappedMasterService {
         ReplicaType replica_type = ReplicaType::ALL,
         const std::string& tenant_id = "default");
 
+    tl::expected<VChunkMetadataRecord, ErrorCode> VChunkPutStart(
+        const std::string& tenant_id, const std::string& key,
+        uint64_t total_size, int64_t now_ms);
+    tl::expected<void, ErrorCode> VChunkPutEnd(
+        const std::string& tenant_id, const std::string& key,
+        const std::string& vchunk_id, int64_t now_ms);
+    tl::expected<void, ErrorCode> VChunkPutRevoke(
+        const std::string& tenant_id, const std::string& key,
+        const std::string& vchunk_id);
+    tl::expected<VChunkReadLease, ErrorCode> GetVChunk(
+        const std::string& tenant_id, const std::string& key);
+    tl::expected<void, ErrorCode> ReleaseVChunkReadLease(
+        const std::string& lease_id);
+    tl::expected<void, ErrorCode> RemoveVChunk(const std::string& tenant_id,
+                                               const std::string& key,
+                                               int64_t now_ms);
+    VChunkRuntimeInfo GetVChunkRuntimeInfo();
+
     std::vector<tl::expected<std::vector<Replica::Descriptor>, ErrorCode>>
     BatchPutStart(const UUID& client_id, const std::vector<std::string>& keys,
                   const std::vector<uint64_t>& slice_lengths,
@@ -267,6 +286,63 @@ class WrappedMasterService {
                             uint64_t initial_oplog_sequence_id,
                             const std::vector<StandbySegmentInfo>& segments);
 
+    // CVM slot ownership publishing, driven by the HA supervisor. These
+    // forward to the wrapped MasterService (NOT RPC endpoints).
+    void SetCvmLeaseId(EtcdLeaseId lease_id);
+    ErrorCode StartSlotOwnerHeartbeat();
+    void StopSlotOwnerHeartbeat();
+
+    // CVM inter-master RPC lifecycle, driven by the HA supervisor (NOT an
+    // RPC endpoint). Starts/stops the peer discovery + connection pools.
+    ErrorCode StartInterMasterRpc();
+    void StopInterMasterRpc();
+
+    // Inter-master handshake RPC: returns this submaster's identity and
+    // ownership summary so peers can verify the inter-master channel.
+    tl::expected<InterMasterHandshakeResponse, ErrorCode>
+    InterMasterHandshake();
+
+    // Inter-master allocation forwarding (CVM plan B): allocate memory
+    // replicas in this submaster's locally mounted segments on behalf of a
+    // slot-owning peer. Strictly within `preferred_segments` when given.
+    // This submaster keeps the real handles alive (keepalive registry);
+    // the slot owner materializes dummy-allocator replicas from the
+    // returned descriptors and owns the metadata.
+    tl::expected<std::vector<Replica::Descriptor>, ErrorCode>
+    InterMasterAllocateReplicas(
+        const std::string& tenant_id, const std::string& key,
+        uint64_t slice_length, uint64_t replica_num,
+        const std::vector<std::string>& preferred_segments);
+
+    // Frees the keepalive entry (and thus the handles) previously created
+    // by InterMasterAllocateReplicas. Returns true when an entry existed.
+    tl::expected<bool, ErrorCode> InterMasterFreeReplicas(
+        const std::string& tenant_id, const std::string& key);
+
+    // Inter-master read forwarding (CVM plan B): local GetReplicaList /
+    // BatchGetReplicaList query for a forwarding peer. These do NOT
+    // re-forward, so an inconsistent view terminates the chain at the first
+    // hop instead of looping.
+    tl::expected<GetReplicaListResponse, ErrorCode> InterMasterGetReplicaList(
+        const std::string& key, const std::string& tenant_id);
+
+    std::vector<tl::expected<GetReplicaListResponse, ErrorCode>>
+    InterMasterBatchGetReplicaList(const std::vector<std::string>& keys,
+                                   const std::string& tenant_id);
+
+    // Inter-master write forwarding (model B): relays a FULL PutStart to the
+    // slot-owning submaster so it allocates + writes metadata locally.
+    tl::expected<std::vector<Replica::Descriptor>, ErrorCode> InterMasterPutStart(
+        const UUID& client_id, const std::string& key,
+        const std::string& tenant_id, uint64_t slice_length,
+        const ReplicateConfig& config);
+
+    // Upsert variant of InterMasterPutStart (owner overwrites-if-exists).
+    tl::expected<std::vector<Replica::Descriptor>, ErrorCode>
+    InterMasterUpsertStart(const UUID& client_id, const std::string& key,
+                           const std::string& tenant_id, uint64_t slice_length,
+                           const ReplicateConfig& config);
+
     tl::expected<UUID, ErrorCode> CreateCopyTask(
         const std::string& key, const std::string& tenant_id,
         const std::vector<std::string>& targets);
@@ -322,8 +398,11 @@ class WrappedMasterService {
     bool KvEventsEnabled() const;
     KvEventPublisher::Stats GetKvEventStats() const;
 
+    io_pattern::CfmRpcService& CfmRpcEndpoint() { return cfm_rpc_service_; }
+
    private:
     MasterService master_service_;
+    io_pattern::CfmRpcService cfm_rpc_service_;
 };
 
 void RegisterRpcService(coro_rpc::coro_rpc_server& server,
diff --git a/mooncake-store/include/rpc_transport.h b/mooncake-store/include/rpc_transport.h
new file mode 100644
index 0000000000..b5a8f32cfc
--- /dev/null
+++ b/mooncake-store/include/rpc_transport.h
@@ -0,0 +1,2 @@
+#pragma once
+#include "io_pattern/rpc_transport.h"
diff --git a/mooncake-store/include/rpc_types.h b/mooncake-store/include/rpc_types.h
index e9c6438734..9a43629882 100644
--- a/mooncake-store/include/rpc_types.h
+++ b/mooncake-store/include/rpc_types.h
@@ -122,6 +122,22 @@ struct MoveStartResponse {
 };
 YLT_REFL(MoveStartResponse, source, target);
 
+/**
+ * @brief Response structure for InterMasterHandshake: identity + ownership
+ * summary of a submaster, used by other submasters to verify the inter-master
+ * RPC channel (CVM multi-submaster coordination, forwarding path).
+ */
+struct InterMasterHandshakeResponse {
+    std::string master_id;
+    uint64_t lease_id{0};
+    uint32_t owned_slot_count{0};
+    std::string version;
+
+    InterMasterHandshakeResponse() = default;
+};
+YLT_REFL(InterMasterHandshakeResponse, master_id, lease_id, owned_slot_count,
+         version);
+
 enum class JobType {
     DRAIN = 0,
 };
diff --git a/mooncake-store/include/sliding_window_analyzer.h b/mooncake-store/include/sliding_window_analyzer.h
new file mode 100644
index 0000000000..e9f03d51db
--- /dev/null
+++ b/mooncake-store/include/sliding_window_analyzer.h
@@ -0,0 +1,2 @@
+#pragma once
+#include "io_pattern/sliding_window_analyzer.h"
diff --git a/mooncake-store/include/threshold_analyzer.h b/mooncake-store/include/threshold_analyzer.h
new file mode 100644
index 0000000000..a0b1ffad03
--- /dev/null
+++ b/mooncake-store/include/threshold_analyzer.h
@@ -0,0 +1,3 @@
+#pragma once
+
+#include "io_pattern/threshold_analyzer.h"
diff --git a/mooncake-store/include/tier_executor.h b/mooncake-store/include/tier_executor.h
new file mode 100644
index 0000000000..efac66ffdd
--- /dev/null
+++ b/mooncake-store/include/tier_executor.h
@@ -0,0 +1,2 @@
+#pragma once
+#include "io_pattern/tier_executor.h"
diff --git a/mooncake-store/include/types.h b/mooncake-store/include/types.h
index eb53a52cab..e4c67adc94 100644
--- a/mooncake-store/include/types.h
+++ b/mooncake-store/include/types.h
@@ -375,6 +375,9 @@ enum class ErrorCode : int32_t {
         -1010,  ///< Request cannot be done in current status.
     UNAVAILABLE_IN_CURRENT_MODE =
         -1011,  ///< Request cannot be done in current mode.
+    SLOT_NOT_OWNED =
+        -1012,  ///< The key's slot is not owned by this master (KV partition
+                ///< rebalanced); the client should re-route.
 
     // FILE errors (Range: -1100 to -1199)
     FILE_NOT_FOUND = -1100,       ///< File not found.
diff --git a/mooncake-store/include/vchunk_allocation_strategy.h b/mooncake-store/include/vchunk_allocation_strategy.h
new file mode 100644
index 0000000000..2d7a845039
--- /dev/null
+++ b/mooncake-store/include/vchunk_allocation_strategy.h
@@ -0,0 +1,52 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <memory>
+#include <set>
+#include <string>
+#include <vector>
+
+#include <ylt/util/tl/expected.hpp>
+
+#include "allocator.h"
+#include "vchunk_config.h"
+
+namespace mooncake {
+
+class AllocatorManager;
+
+struct VCSliceAllocation {
+    uint32_t slice_index{0};
+    std::string segment_name;
+    uint64_t target_offset{0};
+    uint32_t logical_length{0};
+    uint32_t allocated_length{0};
+    std::unique_ptr<AllocatedBuffer> buffer;
+
+    VCSliceAllocation() = default;
+    VCSliceAllocation(VCSliceAllocation&&) noexcept = default;
+    VCSliceAllocation& operator=(VCSliceAllocation&&) noexcept = default;
+    VCSliceAllocation(const VCSliceAllocation&) = delete;
+    VCSliceAllocation& operator=(const VCSliceAllocation&) = delete;
+};
+
+class VChunkAllocationResult {
+   public:
+    VChunkAllocationResult() = default;
+    VChunkAllocationResult(VChunkAllocationResult&&) noexcept = default;
+    VChunkAllocationResult& operator=(VChunkAllocationResult&&) noexcept =
+        default;
+    VChunkAllocationResult(const VChunkAllocationResult&) = delete;
+    VChunkAllocationResult& operator=(const VChunkAllocationResult&) = delete;
+
+    size_t row_size{0};
+    std::vector<VCSliceAllocation> allocations;
+};
+
+tl::expected<VChunkAllocationResult, ErrorCode> AllocateVChunk(
+    const AllocatorManager& allocator_manager, uint64_t total_size,
+    VCSliceSizeLevel slice_size_level,
+    const std::set<std::string>& excluded_segments = {});
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/vchunk_client.h b/mooncake-store/include/vchunk_client.h
new file mode 100644
index 0000000000..a7b70988c5
--- /dev/null
+++ b/mooncake-store/include/vchunk_client.h
@@ -0,0 +1,99 @@
+#pragma once
+
+#include <atomic>
+#include <chrono>
+#include <cstddef>
+#include <cstdint>
+#include <functional>
+#include <memory>
+#include <string>
+#include <vector>
+
+#include <ylt/util/tl/expected.hpp>
+
+#include "tenant_id.h"
+#include "types.h"
+#include "vchunk_control_plane.h"
+#include "vchunk_metadata.h"
+#include "vchunk_metrics.h"
+
+namespace mooncake {
+
+class VChunkDataPlane {
+   public:
+    virtual ~VChunkDataPlane() = default;
+    virtual ErrorCode Write(const VChunkMetadataRecord& record,
+                            const void* source, size_t length,
+                            std::chrono::steady_clock::time_point deadline) = 0;
+    virtual ErrorCode Read(const VChunkMetadataRecord& record, void* destination,
+                           size_t length,
+                           std::chrono::steady_clock::time_point deadline) = 0;
+};
+
+class VChunkLegacyPath {
+   public:
+    virtual ~VChunkLegacyPath() = default;
+    virtual ErrorCode Put(const TenantId&, const std::string&, const void*,
+                          size_t) = 0;
+    virtual ErrorCode Get(const TenantId&, const std::string&, void*, size_t) = 0;
+    virtual ErrorCode Remove(const TenantId&, const std::string&) = 0;
+};
+
+class VChunkClient {
+   public:
+    using Clock = std::chrono::steady_clock;
+    using NowMs = std::function<int64_t()>;
+
+    VChunkClient(bool enabled, MasterService& master, VChunkDataPlane& data_plane,
+                 VChunkLegacyPath& legacy, std::chrono::milliseconds timeout,
+                 NowMs now_ms,
+                 uint32_t max_retries = VChunkConfig{}.max_slice_retry,
+                 uint32_t circuit_breaker_threshold = 0,
+                 std::shared_ptr<VChunkMetrics> metrics = nullptr);
+    VChunkClient(bool enabled, VChunkControlPlane& control_plane,
+                 VChunkDataPlane& data_plane, VChunkLegacyPath& legacy,
+                 std::chrono::milliseconds timeout, NowMs now_ms,
+                 uint32_t max_retries = VChunkConfig{}.max_slice_retry,
+                 uint32_t circuit_breaker_threshold = 0,
+                 std::shared_ptr<VChunkMetrics> metrics = nullptr);
+
+    ErrorCode Put(const TenantId& tenant_id, const std::string& key,
+                  const void* source, size_t length);
+    ErrorCode Get(const TenantId& tenant_id, const std::string& key,
+                  void* destination, size_t length);
+    ErrorCode Remove(const TenantId& tenant_id, const std::string& key);
+
+    struct PutRequest {
+        std::string key;
+        const void* source{nullptr};
+        size_t length{0};
+    };
+    struct GetRequest {
+        std::string key;
+        void* destination{nullptr};
+        size_t length{0};
+    };
+
+    std::vector<ErrorCode> BatchPut(const TenantId& tenant_id,
+                                    const std::vector<PutRequest>& requests);
+    std::vector<ErrorCode> BatchGet(const TenantId& tenant_id,
+                                    const std::vector<GetRequest>& requests);
+    std::vector<ErrorCode> BatchRemove(
+        const TenantId& tenant_id, const std::vector<std::string>& keys);
+    VChunkMetricsSnapshot MetricsSnapshot() const;
+
+   private:
+    bool enabled_;
+    std::unique_ptr<VChunkControlPlane> owned_control_plane_;
+    VChunkControlPlane* control_plane_;
+    VChunkDataPlane& data_plane_;
+    VChunkLegacyPath& legacy_;
+    std::chrono::milliseconds timeout_;
+    NowMs now_ms_;
+    uint32_t max_retries_;
+    uint32_t circuit_breaker_threshold_;
+    std::atomic<uint32_t> consecutive_put_failures_{0};
+    std::shared_ptr<VChunkMetrics> metrics_;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/vchunk_config.h b/mooncake-store/include/vchunk_config.h
new file mode 100644
index 0000000000..a7569a5cfd
--- /dev/null
+++ b/mooncake-store/include/vchunk_config.h
@@ -0,0 +1,42 @@
+#pragma once
+
+#include <cstdint>
+
+#include "types.h"
+
+namespace mooncake {
+
+enum class VCSliceSizeLevel : uint32_t {
+    k4K = 4U * 1024U,
+    k64K = 64U * 1024U,
+    k256K = 256U * 1024U,
+    k1M = 1024U * 1024U,
+};
+
+constexpr uint32_t SliceSizeLevelToBytes(VCSliceSizeLevel level) {
+    return static_cast<uint32_t>(level);
+}
+
+VCSliceSizeLevel SelectVChunkSliceSize(uint64_t value_size,
+                                      bool is_ssd_segment);
+
+struct VChunkConfig {
+    bool enabled{false};
+    uint64_t creating_timeout_ms{30'000};
+    uint64_t releasing_timeout_ms{60'000};
+    uint32_t max_slice_retry{3};
+    uint32_t max_slice_count{4096};
+    uint64_t max_metadata_bytes{1024U * 1024U};
+    uint32_t max_creating_objects{1024};
+    uint64_t reaper_interval_ms{1000};
+    uint32_t reaper_max_scan{128};
+
+    ErrorCode Validate() const;
+
+    YLT_REFL(VChunkConfig, enabled, creating_timeout_ms,
+             releasing_timeout_ms, max_slice_retry, max_slice_count,
+             max_metadata_bytes, max_creating_objects, reaper_interval_ms,
+             reaper_max_scan);
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/vchunk_control_plane.h b/mooncake-store/include/vchunk_control_plane.h
new file mode 100644
index 0000000000..797d40279a
--- /dev/null
+++ b/mooncake-store/include/vchunk_control_plane.h
@@ -0,0 +1,80 @@
+#pragma once
+
+#include <cstdint>
+#include <memory>
+#include <string>
+
+#include <ylt/util/tl/expected.hpp>
+
+#include "tenant_id.h"
+#include "types.h"
+#include "vchunk_metadata.h"
+
+namespace mooncake {
+
+class MasterClient;
+class MasterService;
+
+struct VChunkControlPlaneRead {
+    VChunkMetadataRecord record;
+    // Retains either the local allocator-backed read handle or the guard for a
+    // remote read lease until the data-plane transfer has finished.
+    std::shared_ptr<void> lifetime;
+};
+
+class VChunkControlPlane {
+   public:
+    virtual ~VChunkControlPlane() = default;
+
+    virtual tl::expected<VChunkMetadataRecord, ErrorCode> PutStart(
+        const TenantId& tenant_id, const std::string& key, uint64_t total_size,
+        int64_t now_ms) = 0;
+    virtual ErrorCode PutEnd(const TenantId& tenant_id, const std::string& key,
+                             const std::string& vchunk_id,
+                             int64_t now_ms) = 0;
+    virtual ErrorCode PutRevoke(const TenantId& tenant_id,
+                                const std::string& key,
+                                const std::string& vchunk_id) = 0;
+    virtual tl::expected<VChunkControlPlaneRead, ErrorCode> Get(
+        const TenantId& tenant_id, const std::string& key) = 0;
+    virtual ErrorCode Remove(const TenantId& tenant_id,
+                             const std::string& key, int64_t now_ms) = 0;
+};
+
+class LocalVChunkControlPlane final : public VChunkControlPlane {
+   public:
+    explicit LocalVChunkControlPlane(MasterService& master) : master_(master) {}
+
+    tl::expected<VChunkMetadataRecord, ErrorCode> PutStart(
+        const TenantId&, const std::string&, uint64_t, int64_t) override;
+    ErrorCode PutEnd(const TenantId&, const std::string&, const std::string&,
+                     int64_t) override;
+    ErrorCode PutRevoke(const TenantId&, const std::string&,
+                        const std::string&) override;
+    tl::expected<VChunkControlPlaneRead, ErrorCode> Get(
+        const TenantId&, const std::string&) override;
+    ErrorCode Remove(const TenantId&, const std::string&, int64_t) override;
+
+   private:
+    MasterService& master_;
+};
+
+class RpcVChunkControlPlane final : public VChunkControlPlane {
+   public:
+    explicit RpcVChunkControlPlane(MasterClient& master) : master_(master) {}
+
+    tl::expected<VChunkMetadataRecord, ErrorCode> PutStart(
+        const TenantId&, const std::string&, uint64_t, int64_t) override;
+    ErrorCode PutEnd(const TenantId&, const std::string&, const std::string&,
+                     int64_t) override;
+    ErrorCode PutRevoke(const TenantId&, const std::string&,
+                        const std::string&) override;
+    tl::expected<VChunkControlPlaneRead, ErrorCode> Get(
+        const TenantId&, const std::string&) override;
+    ErrorCode Remove(const TenantId&, const std::string&, int64_t) override;
+
+   private:
+    MasterClient& master_;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/vchunk_master_manager.h b/mooncake-store/include/vchunk_master_manager.h
new file mode 100644
index 0000000000..f7d5117c83
--- /dev/null
+++ b/mooncake-store/include/vchunk_master_manager.h
@@ -0,0 +1,100 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <functional>
+#include <memory>
+#include <mutex>
+#include <set>
+#include <string>
+#include <unordered_map>
+#include <unordered_set>
+#include <vector>
+
+#include <ylt/util/tl/expected.hpp>
+
+#include "allocator.h"
+#include "tenant_id.h"
+#include "vchunk_allocation_strategy.h"
+#include "vchunk_config.h"
+#include "vchunk_metadata.h"
+#include "vchunk_metadata_store.h"
+#include "vchunk_metrics.h"
+
+namespace mooncake {
+
+// In-memory master-side vchunk lifecycle manager. The caller must hold the
+// SegmentManager allocator access guard while PutStart uses AllocatorManager.
+class VChunkMasterManager {
+   public:
+    using OwnershipPredicate =
+        std::function<bool(const VChunkMetadataRecord&)>;
+
+    class ReadHandle {
+       public:
+        ReadHandle() = default;
+        const VChunkMetadataRecord& record() const { return record_; }
+
+       private:
+        friend class VChunkMasterManager;
+        VChunkMetadataRecord record_;
+        std::shared_ptr<const void> lifetime_;
+    };
+
+    explicit VChunkMasterManager(
+        VChunkConfig config,
+        std::shared_ptr<VChunkMetadataStore> metadata_store = nullptr,
+        std::shared_ptr<VChunkMetrics> metrics = nullptr);
+
+    VChunkMasterManager(const VChunkMasterManager&) = delete;
+    VChunkMasterManager& operator=(const VChunkMasterManager&) = delete;
+
+    tl::expected<VChunkMetadataRecord, ErrorCode> PutStart(
+        const AllocatorManager& allocator_manager, const TenantId& tenant_id,
+        const std::string& key, uint64_t total_size, bool is_ssd_segment,
+        int64_t now_ms,
+        const std::set<std::string>& excluded_segments = {});
+
+    ErrorCode PutEnd(const TenantId& tenant_id, const std::string& key,
+                     const std::string& vchunk_id, int64_t now_ms);
+    ErrorCode PutRevoke(const TenantId& tenant_id, const std::string& key,
+                        const std::string& vchunk_id);
+
+    tl::expected<VChunkMetadataRecord, ErrorCode> Get(
+        const TenantId& tenant_id, const std::string& key) const;
+    tl::expected<ReadHandle, ErrorCode> AcquireRead(
+        const TenantId& tenant_id, const std::string& key) const;
+
+    ErrorCode Remove(const TenantId& tenant_id, const std::string& key,
+                     int64_t now_ms);
+
+    ErrorCode Recover(int64_t now_ms, OwnershipPredicate owns = {});
+    tl::expected<size_t, ErrorCode> ReapExpired(int64_t now_ms,
+                                                size_t max_scan,
+                                                OwnershipPredicate owns = {});
+    VChunkMetricsSnapshot MetricsSnapshot() const;
+
+    size_t SizeForTesting() const;
+    bool HasPersistentMetadata() const { return metadata_store_->IsPersistent(); }
+
+   private:
+    struct Entry {
+        VChunkMetadataRecord record;
+        std::vector<std::unique_ptr<AllocatedBuffer>> buffers;
+    };
+
+    static std::string ScopedKey(const TenantId& tenant_id,
+                                 const std::string& key);
+    void RefreshStateMetricsLocked();
+    void ReleasePendingPut(const std::string& scoped_key);
+
+    const VChunkConfig config_;
+    const std::shared_ptr<VChunkMetadataStore> metadata_store_;
+    const std::shared_ptr<VChunkMetrics> metrics_;
+    mutable std::mutex mutex_;
+    std::unordered_map<std::string, std::shared_ptr<Entry>> entries_;
+    std::unordered_set<std::string> pending_puts_;
+    std::string reaper_cursor_key_;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/vchunk_metadata.h b/mooncake-store/include/vchunk_metadata.h
new file mode 100644
index 0000000000..cd0d3093fb
--- /dev/null
+++ b/mooncake-store/include/vchunk_metadata.h
@@ -0,0 +1,104 @@
+#pragma once
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+#include <ylt/util/tl/expected.hpp>
+
+#include "mutex.h"
+#include "types.h"
+#include "vchunk_config.h"
+
+namespace mooncake {
+
+inline constexpr uint32_t kVChunkMetadataSchemaVersion = 1;
+
+enum class VCSliceStatus : uint8_t {
+    PENDING = 0,
+    COMPLETED = 1,
+    FAILED = 2,
+};
+
+enum class VChunkStatus : uint8_t {
+    CREATING = 0,
+    ACTIVE = 1,
+    RELEASING = 2,
+    RELEASED = 3,
+    FAILED = 4,
+};
+
+struct VCSliceDescriptor {
+    uint32_t slice_index{0};
+    std::string target_segment_name;
+    uint64_t target_offset{0};
+    uint32_t logical_length{0};
+    uint32_t allocated_length{0};
+    VCSliceStatus status{VCSliceStatus::PENDING};
+    uint32_t retry_count{0};
+
+    YLT_REFL(VCSliceDescriptor, slice_index, target_segment_name,
+             target_offset, logical_length, allocated_length, status,
+             retry_count);
+};
+
+// Stable wire/storage representation. Runtime-only synchronization and indexes
+// intentionally live outside this type.
+struct VChunkMetadataRecord {
+    uint32_t schema_version{kVChunkMetadataSchemaVersion};
+    std::string vchunk_id;
+    std::string tenant_id;
+    std::string key;
+    uint64_t total_size{0};
+    uint32_t slice_count{0};
+    VCSliceSizeLevel slice_size_level{VCSliceSizeLevel::k4K};
+    std::vector<VCSliceDescriptor> slices;
+    uint32_t row_size{0};
+    VChunkStatus status{VChunkStatus::CREATING};
+    int64_t created_at_ms{0};
+    int64_t last_updated_at_ms{0};
+
+    YLT_REFL(VChunkMetadataRecord, schema_version, vchunk_id, tenant_id, key,
+             total_size, slice_count, slice_size_level, slices, row_size,
+             status, created_at_ms, last_updated_at_ms);
+};
+
+struct VChunkRuntimeInfo {
+    bool enabled{false};
+    bool persistent_metadata{false};
+
+    YLT_REFL(VChunkRuntimeInfo, enabled, persistent_metadata);
+};
+
+struct VChunkReadLease {
+    VChunkMetadataRecord record;
+    std::string lease_id;
+
+    YLT_REFL(VChunkReadLease, record, lease_id);
+};
+
+ErrorCode ValidateVChunkMetadata(const VChunkMetadataRecord& record,
+                                 const VChunkConfig& config);
+ErrorCode ValidateVChunkTransition(VChunkStatus from, VChunkStatus to);
+
+tl::expected<std::vector<char>, ErrorCode> SerializeVChunkMetadata(
+    const VChunkMetadataRecord& record, const VChunkConfig& config);
+tl::expected<VChunkMetadataRecord, ErrorCode> DeserializeVChunkMetadata(
+    const std::vector<char>& bytes, const VChunkConfig& config);
+
+class VChunkMetadata {
+   public:
+    explicit VChunkMetadata(VChunkMetadataRecord record);
+
+    VChunkMetadata(const VChunkMetadata&) = delete;
+    VChunkMetadata& operator=(const VChunkMetadata&) = delete;
+
+    VChunkMetadataRecord Snapshot() const;
+    ErrorCode TransitionTo(VChunkStatus next, int64_t updated_at_ms);
+
+   private:
+    mutable SpinLock lock_;
+    VChunkMetadataRecord record_;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/vchunk_metadata_store.h b/mooncake-store/include/vchunk_metadata_store.h
new file mode 100644
index 0000000000..c7c0e6e32d
--- /dev/null
+++ b/mooncake-store/include/vchunk_metadata_store.h
@@ -0,0 +1,63 @@
+#pragma once
+
+#include <memory>
+#include <mutex>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+#include <ylt/util/tl/expected.hpp>
+
+#include "types.h"
+#include "vchunk_metadata.h"
+
+namespace mooncake {
+
+inline constexpr char kVChunkMetadataNamespace[] = "/mooncake/vchunk/v1";
+
+std::string MakeVChunkMetadataStoreKey(const VChunkMetadataRecord& record);
+
+class VChunkMetadataStore {
+   public:
+    virtual ~VChunkMetadataStore() = default;
+    virtual ErrorCode Put(const VChunkMetadataRecord& record) = 0;
+    virtual ErrorCode Remove(const VChunkMetadataRecord& record) = 0;
+    virtual tl::expected<std::vector<VChunkMetadataRecord>, ErrorCode> List() = 0;
+    virtual bool IsPersistent() const = 0;
+};
+
+class InMemoryVChunkMetadataStore final : public VChunkMetadataStore {
+   public:
+    ErrorCode Put(const VChunkMetadataRecord& record) override;
+    ErrorCode Remove(const VChunkMetadataRecord& record) override;
+    tl::expected<std::vector<VChunkMetadataRecord>, ErrorCode> List() override;
+    bool IsPersistent() const override { return false; }
+
+   private:
+    std::mutex mutex_;
+    std::unordered_map<std::string, VChunkMetadataRecord> records_;
+};
+
+// Persistent metadata backend for distributed validation. A scoped object
+// index is stored separately from the vchunk-id record so concurrent masters
+// cannot both create the same logical object.
+class EtcdVChunkMetadataStore final : public VChunkMetadataStore {
+   public:
+    EtcdVChunkMetadataStore(std::string endpoints, VChunkConfig config,
+                            std::string cluster_id = "default");
+
+    ErrorCode Put(const VChunkMetadataRecord& record) override;
+    ErrorCode Remove(const VChunkMetadataRecord& record) override;
+    tl::expected<std::vector<VChunkMetadataRecord>, ErrorCode> List() override;
+    bool IsPersistent() const override { return true; }
+
+    ErrorCode connection_error() const { return connection_error_; }
+
+   private:
+    std::string endpoints_;
+    VChunkConfig config_;
+    std::string namespace_prefix_;
+    ErrorCode connection_error_{ErrorCode::OK};
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/vchunk_metrics.h b/mooncake-store/include/vchunk_metrics.h
new file mode 100644
index 0000000000..a6150a5bb3
--- /dev/null
+++ b/mooncake-store/include/vchunk_metrics.h
@@ -0,0 +1,63 @@
+#pragma once
+
+#include <array>
+#include <atomic>
+#include <cstddef>
+#include <cstdint>
+
+#include "vchunk_metadata.h"
+
+namespace mooncake {
+
+enum class VChunkOperation : uint8_t { PUT = 0, GET = 1, REMOVE = 2 };
+
+struct VChunkMetricsSnapshot {
+    std::array<uint64_t, 3> requests{};
+    std::array<uint64_t, 3> successes{};
+    std::array<uint64_t, 3> latency_us{};
+    uint64_t slices{0};
+    uint64_t segment_participations{0};
+    std::array<uint64_t, 4> slice_size_distribution{};
+    uint64_t allocation_failures{0};
+    uint64_t transfer_failures{0};
+    uint64_t timeouts{0};
+    uint64_t retries{0};
+    uint64_t rollbacks{0};
+    uint64_t metadata_bytes{0};
+    uint64_t allocated_bytes{0};
+    std::array<uint64_t, 5> states{};
+};
+
+class VChunkMetrics {
+   public:
+    void Observe(VChunkOperation operation, bool success, uint64_t latency_us);
+    void AddSlices(uint64_t count) { slices_.fetch_add(count); }
+    void ObserveLayout(const VChunkMetadataRecord& record);
+    void AddAllocationFailure() { ++allocation_failures_; }
+    void AddTransferFailure() { ++transfer_failures_; }
+    void AddTimeout() { ++timeouts_; }
+    void AddRetry() { ++retries_; }
+    void AddRollback() { ++rollbacks_; }
+    void AddMetadataBytes(uint64_t bytes) { metadata_bytes_.fetch_add(bytes); }
+    void SetStateCount(VChunkStatus state, uint64_t count);
+    void SetAllocatedBytes(uint64_t bytes) { allocated_bytes_.store(bytes); }
+    VChunkMetricsSnapshot Snapshot() const;
+
+   private:
+    std::array<std::atomic<uint64_t>, 3> requests_{};
+    std::array<std::atomic<uint64_t>, 3> successes_{};
+    std::array<std::atomic<uint64_t>, 3> latency_us_{};
+    std::atomic<uint64_t> slices_{0};
+    std::atomic<uint64_t> segment_participations_{0};
+    std::array<std::atomic<uint64_t>, 4> slice_size_distribution_{};
+    std::atomic<uint64_t> allocation_failures_{0};
+    std::atomic<uint64_t> transfer_failures_{0};
+    std::atomic<uint64_t> timeouts_{0};
+    std::atomic<uint64_t> retries_{0};
+    std::atomic<uint64_t> rollbacks_{0};
+    std::atomic<uint64_t> metadata_bytes_{0};
+    std::atomic<uint64_t> allocated_bytes_{0};
+    std::array<std::atomic<uint64_t>, 5> states_{};
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/vchunk_transfer_engine.h b/mooncake-store/include/vchunk_transfer_engine.h
new file mode 100644
index 0000000000..411bd7688a
--- /dev/null
+++ b/mooncake-store/include/vchunk_transfer_engine.h
@@ -0,0 +1,40 @@
+#pragma once
+
+#include <chrono>
+#include <functional>
+#include <vector>
+
+#include "transfer_engine.h"
+#include "vchunk_client.h"
+
+namespace mooncake {
+
+using VChunkSegmentResolver =
+    std::function<tl::expected<SegmentHandle, ErrorCode>(const std::string&)>;
+
+tl::expected<std::vector<TransferRequest>, ErrorCode>
+BuildVChunkTransferRequests(const VChunkMetadataRecord& record, void* buffer,
+                            size_t length, TransferRequest::OpCode opcode,
+                            const VChunkSegmentResolver& resolve_segment);
+
+class TransferEngineVChunkDataPlane final : public VChunkDataPlane {
+   public:
+    explicit TransferEngineVChunkDataPlane(TransferEngine& engine)
+        : engine_(engine) {}
+
+    ErrorCode Write(const VChunkMetadataRecord& record, const void* source,
+                    size_t length,
+                    std::chrono::steady_clock::time_point deadline) override;
+    ErrorCode Read(const VChunkMetadataRecord& record, void* destination,
+                   size_t length,
+                   std::chrono::steady_clock::time_point deadline) override;
+
+   private:
+    ErrorCode Transfer(const VChunkMetadataRecord& record, void* buffer,
+                       size_t length, TransferRequest::OpCode opcode,
+                       std::chrono::steady_clock::time_point deadline);
+
+    TransferEngine& engine_;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/CMakeLists.txt b/mooncake-store/src/CMakeLists.txt
index 3031dbda86..0931868306 100644
--- a/mooncake-store/src/CMakeLists.txt
+++ b/mooncake-store/src/CMakeLists.txt
@@ -16,6 +16,13 @@ set(MOONCAKE_STORE_SOURCES
     storage_backend.cpp
     thread_pool.cpp
     etcd_helper.cpp
+    cvm/etcd_view_store.cpp
+    cvm/cvm_controller.cpp
+    cvm/slot_owner_heartbeat.cpp
+    cvm/slot_migrator.cpp
+    cvm/cvm_http_server.cpp
+    cvm/inter_master_rpc.cpp
+    partition/partition_router.cpp
     segment.cpp
     transfer_task.cpp
     tenant_quota.cpp
@@ -61,6 +68,26 @@ set(MOONCAKE_STORE_SOURCES
     utils/file_util.cpp
     task_manager.cpp
     local_hot_cache.cpp
+    io_pattern/collector_impl.cpp
+    io_pattern/reporter.cpp
+    io_pattern/cfm_client_impl.cpp
+    io_pattern/cfm_ingress.cpp
+    io_pattern/cfm_service.cpp
+    io_pattern/cfm_ownership_client.cpp
+    io_pattern/cfm_protocol.cpp
+    io_pattern/resilient_cfm_channel.cpp
+    io_pattern/feedback.cpp
+    io_pattern/degrading_policy_engine.cpp
+    io_pattern/legacy_eviction_ops.cpp
+    io_pattern/kmeans_analyzer.cpp
+    io_pattern/observability.cpp
+    io_pattern/sliding_window_analyzer.cpp
+    io_pattern/tier_executor.cpp
+    io_pattern/resilient_analyzer.cpp
+    io_pattern/rpc_transport.cpp
+    io_pattern/runtime.cpp
+    io_pattern/threshold_analyzer.cpp
+    io_pattern/policy_strategies.cpp
     ha/oplog/oplog_types.cpp
     ha/oplog/oplog_batch_codec.cpp
     ha/oplog/oplog_batch_storage.cpp
@@ -75,6 +102,15 @@ set(MOONCAKE_STORE_SOURCES
     ha_metric_manager.cpp
     store_c.cpp
     memory_alloc.cpp
+    vchunk_config.cpp
+    vchunk_metadata.cpp
+    vchunk_allocation_strategy.cpp
+    vchunk_master_manager.cpp
+    vchunk_client.cpp
+    vchunk_control_plane.cpp
+    vchunk_transfer_engine.cpp
+    vchunk_metadata_store.cpp
+    vchunk_metrics.cpp
     ssd_register_client.cpp
     engram/engram_store.cpp)
 
diff --git a/mooncake-store/src/client_service.cpp b/mooncake-store/src/client_service.cpp
index 0dca231eca..96750b3395 100644
--- a/mooncake-store/src/client_service.cpp
+++ b/mooncake-store/src/client_service.cpp
@@ -15,6 +15,7 @@
 #include <cstdlib>
 #include <iomanip>
 #include <limits>
+#include <sstream>
 #ifdef USE_NOF
 #include <numa.h>
 #endif
@@ -34,6 +35,10 @@
 #include "transport/transport.h"
 #include "config.h"
 #include "ha/leadership/leader_coordinator_factory.h"
+#include "cvm/cvm_keys.h"
+#include "cvm/cvm_types.h"
+#include "cvm/etcd_view_store.h"
+#include "etcd_helper.h"
 #include "types.h"
 #include "client_buffer.h"
 #include "utils.h"
@@ -44,6 +49,12 @@
 #include "environ.h"
 #include "mooncake_logging.h"
 
+#if __has_include(<jsoncpp/json/json.h>)
+#include <jsoncpp/json/json.h>
+#else
+#include <json/json.h>
+#endif
+
 #define SPDIAG_PERF_DEF_FILE "mooncake_perf_points.def"
 #define SPDIAG_PROGRAM_NAME "mooncake_store"
 #include "spdiag/auto_perf.h"
@@ -347,6 +358,11 @@ Client::~Client() {
         leader_monitor_thread_.join();
     }
 
+    routing_refresh_running_ = false;
+    if (routing_refresh_thread_.joinable()) {
+        routing_refresh_thread_.join();
+    }
+
     {
         std::lock_guard<std::mutex> lock(graceful_unmount_timer_mutex_);
         graceful_unmount_timer_stopping_ = true;
@@ -557,8 +573,24 @@ ErrorCode Client::ConnectToMaster(const std::string& master_server_entry) {
             return current_view.error();
         }
         if (!current_view.value().has_value()) {
-            LOG(ERROR) << "No master is available in HA backend";
-            return ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS;
+            // No single-leader master_view is published. In the CVM
+            // multi-submaster architecture masters never write master_view;
+            // they register under /cvm/<ns>/masters/ instead. Fall back to
+            // the CVM registry to bootstrap the connection. Per-key routing
+            // is loaded afterwards via LoadPartitionRouting() from the
+            // kv_view snapshot in etcd.
+            LOG(INFO) << "No master_view in HA backend; trying CVM "
+                         "multi-submaster bootstrap from /cvm/ registry";
+            auto err =
+                ConnectToCvmSubmasters(ha_backend_spec.value()->connstring);
+            if (err != ErrorCode::OK) {
+                LOG(ERROR) << "No master is available in HA backend (nor a "
+                              "CVM submaster registry)";
+                return err;
+            }
+            direct_master_address_.clear();
+            etcd_connstring_ = ha_backend_spec.value()->connstring;
+            return ErrorCode::OK;
         }
 
         const auto& master_view = current_view.value().value();
@@ -570,6 +602,7 @@ ErrorCode Client::ConnectToMaster(const std::string& master_server_entry) {
 
         leader_coordinator_ = std::move(coordinator.value());
         direct_master_address_.clear();
+        etcd_connstring_ = ha_backend_spec.value()->connstring;
 
         leader_monitor_running_ = true;
         leader_monitor_thread_ =
@@ -591,6 +624,264 @@ ErrorCode Client::ConnectToMaster(const std::string& master_server_entry) {
     }
 }
 
+ErrorCode Client::ConnectToCvmSubmasters(const std::string& etcd_endpoints) {
+    ErrorCode err = EtcdHelper::ConnectToEtcdStoreClient(etcd_endpoints);
+    if (err != ErrorCode::OK) {
+        LOG(ERROR) << "ConnectToCvmSubmasters: failed to connect etcd: " << err;
+        return err;
+    }
+
+    // Discover cluster namespaces that have registered masters by scanning
+    // the /cvm/ key space for /cvm/<ns>/masters/<master_id> keys.
+    const std::string cvm_root(std::string(mooncake::cvm::kCvmRootPrefix));
+    const std::string cvm_root_end = mooncake::cvm::PrefixEnd(cvm_root);
+    const std::string masters_suffix("/masters/");
+    std::string json;
+    EtcdRevisionId revision = 0;
+    err = EtcdHelper::GetRangeAsJson(cvm_root.data(), cvm_root.size(),
+                                     cvm_root_end.data(), cvm_root_end.size(),
+                                     0 /* no limit */, json, revision);
+    if (err != ErrorCode::OK) {
+        LOG(ERROR) << "ConnectToCvmSubmasters: failed to scan /cvm/ prefix: "
+                   << err;
+        return err;
+    }
+
+    std::set<std::string> namespaces;
+    {
+        Json::Value root;
+        Json::CharReaderBuilder reader;
+        std::string errors;
+        std::istringstream stream(json);
+        if (!Json::parseFromStream(reader, stream, &root, &errors) ||
+            !root.isArray()) {
+            LOG(ERROR) << "ConnectToCvmSubmasters: failed to parse /cvm/ "
+                          "range JSON: "
+                       << errors;
+            return ErrorCode::INTERNAL_ERROR;
+        }
+        for (const auto& item : root) {
+            if (!item.isObject() || !item["key"].isString()) {
+                continue;
+            }
+            const std::string key = item["key"].asString();
+            if (!key.starts_with(cvm_root)) {
+                continue;
+            }
+            const size_t ns_begin = cvm_root.size();
+            const size_t masters_pos = key.find(masters_suffix, ns_begin);
+            // Key layout: /cvm/<ns>/masters/<master_id>. Reject namespaces
+            // containing '/' (not a valid masters key).
+            if (masters_pos == std::string::npos ||
+                key.find('/', ns_begin) != masters_pos) {
+                continue;
+            }
+            namespaces.insert(key.substr(ns_begin, masters_pos - ns_begin));
+        }
+    }
+    if (namespaces.empty()) {
+        LOG(ERROR) << "ConnectToCvmSubmasters: no /cvm/<ns>/masters/ "
+                      "registry found in etcd";
+        return ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS;
+    }
+    if (namespaces.size() > 1) {
+        std::ostringstream oss;
+        for (const auto& ns : namespaces) {
+            oss << " " << ns;
+        }
+        LOG(WARNING) << "ConnectToCvmSubmasters: multiple CVM namespaces "
+                        "found ("
+                     << oss.str() << "); using the first one";
+    }
+
+    // Try each namespace; within a namespace, prefer primaries ordered by
+    // registration time (first-registered first), matching the
+    // CvmController first-come-first-served ranking. Fall back to standbys
+    // only if no primary is reachable, so the client can still bootstrap.
+    for (const auto& ns : namespaces) {
+        std::vector<cvm::MasterRegistration> masters;
+        ViewVersionId version = 0;
+        err = cvm::EtcdViewStore::LoadAllMasters(ns, masters, version);
+        if (err != ErrorCode::OK) {
+            LOG(WARNING) << "ConnectToCvmSubmasters: LoadAllMasters failed "
+                            "for namespace "
+                         << ns << ": " << err;
+            continue;
+        }
+        std::sort(masters.begin(), masters.end(),
+                  [](const cvm::MasterRegistration& a,
+                     const cvm::MasterRegistration& b) {
+                      if (a.registered_at_ms != b.registered_at_ms) {
+                          return a.registered_at_ms < b.registered_at_ms;
+                      }
+                      return a.master_id < b.master_id;
+                  });
+
+        auto try_connect_group = [&](bool primaries_only) {
+            for (const auto& reg : masters) {
+                if (primaries_only &&
+                    reg.role != static_cast<int32_t>(cvm::MasterRole::kPrimary)) {
+                    continue;
+                }
+                auto connect_err = master_client_.Connect(reg.address);
+                if (connect_err != ErrorCode::OK) {
+                    LOG(WARNING) << "ConnectToCvmSubmasters: connect to "
+                                 << reg.master_id << " (" << reg.address
+                                 << ") failed: " << toString(connect_err);
+                    continue;
+                }
+                cvm_cluster_namespace_ = ns;
+                // 收集该 namespace 下所有 primary 地址，用于 client 侧全量
+                // mount 与多 submaster 心跳（同一 segment 挂到所有 submaster）。
+                {
+                    std::lock_guard<std::mutex> lock(
+                        cvm_submaster_addresses_mutex_);
+                    cvm_submaster_addresses_.clear();
+                    // 去重：etcd 中可能存在指向同一 address 的重复 primary
+                    // 注册（如重启残留 lease），不去重会导致全量 mount 对同一
+                    // submaster 重复调用、master 日志刷屏。
+                    std::set<std::string> seen;
+                    for (const auto& reg2 : masters) {
+                        if (reg2.role ==
+                                static_cast<int32_t>(
+                                    cvm::MasterRole::kPrimary) &&
+                            !reg2.address.empty() &&
+                            seen.insert(reg2.address).second) {
+                            cvm_submaster_addresses_.push_back(reg2.address);
+                        }
+                    }
+                }
+                {
+                    std::lock_guard<std::mutex> lock(leader_switch_mutex_);
+                    current_master_view_.reset();
+                }
+                // Seed cluster_id_ with the CVM namespace so
+                // TryLoadRoutingOnce skips fsdir-based discovery: GetFsdir
+                // returns an empty string when the submaster has no storage
+                // root configured, which would otherwise leave the partition
+                // routing permanently unloaded.
+                {
+                    std::lock_guard<std::mutex> lock(routing_load_mutex_);
+                    cluster_id_ = ns;
+                }
+                last_ping_success_.store(true);
+                LOG(INFO) << "ConnectToCvmSubmasters: connected to submaster "
+                         << reg.master_id << " (" << reg.address
+                         << ", role=" << reg.role
+                         << ", namespace=" << ns << ")";
+                return ErrorCode::OK;
+            }
+            return ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS;
+        };
+
+        if (try_connect_group(true) == ErrorCode::OK) {
+            return ErrorCode::OK;
+        }
+        if (try_connect_group(false) == ErrorCode::OK) {
+            return ErrorCode::OK;
+        }
+        LOG(WARNING) << "ConnectToCvmSubmasters: no reachable master in "
+                       "namespace "
+                    << ns;
+    }
+
+    LOG(ERROR) << "ConnectToCvmSubmasters: no reachable submaster in any "
+                  "CVM namespace";
+    return ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS;
+}
+
+void Client::LoadPartitionRouting() {
+    // Routing is only meaningful in HA mode where etcd is available.
+    if (etcd_connstring_.empty()) {
+        LOG(INFO) << "LoadPartitionRouting skipped: non-HA mode (no etcd "
+                     "endpoints)";
+        return;
+    }
+    LOG(INFO) << "LoadPartitionRouting: etcd_endpoints=[" << etcd_connstring_
+              << "]";
+
+    // First attempt (best effort). A failure here must not fail client
+    // startup; the refresh loop started below keeps retrying until it
+    // succeeds.
+    TryLoadRoutingOnce();
+
+    // Start the periodic refresh/retry loop unconditionally in HA mode, so a
+    // first-attempt failure (etcd temporarily unavailable, GetFsdir hiccup) is
+    // retried on the next cycle instead of leaving the client permanently in
+    // single-master fallback.
+    if (!routing_refresh_running_.exchange(true)) {
+        routing_refresh_thread_ =
+            std::thread([this]() { this->RoutingRefreshThreadMain(); });
+    }
+}
+
+void Client::TryLoadRoutingOnce() {
+    // 串行化 routing-refresh 线程与 SLOT_NOT_OWNED 触发的按需刷新，
+    // 避免并发读写 cluster_id_ 与路由表。
+    std::lock_guard<std::mutex> lock(routing_load_mutex_);
+    // Resolve the cluster namespace (cluster_id) from the fsdir returned by
+    // master, which is formatted as "<root_fs_dir>/<cluster_id>". The result is
+    // stable, so it is cached in cluster_id_ and reused across retries.
+    std::string cluster_id = cluster_id_;
+    if (cluster_id.empty()) {
+        auto fsdir_response = master_client_.GetFsdir();
+        if (!fsdir_response) {
+            LOG(WARNING) << "TryLoadRoutingOnce: GetFsdir failed, err="
+                         << toString(fsdir_response.error()) << " (will retry)";
+            return;
+        }
+        const std::string& fsdir = fsdir_response.value();
+        if (fsdir.empty()) {
+            LOG(WARNING) << "TryLoadRoutingOnce: GetFsdir returned empty fsdir";
+            return;
+        }
+        LOG(INFO) << "TryLoadRoutingOnce: fsdir=" << fsdir;
+
+        const size_t pos = fsdir.find_last_of('/');
+        if (pos == std::string::npos) {
+            LOG(WARNING) << "TryLoadRoutingOnce: invalid fsdir format (no '/'), "
+                            "fsdir="
+                         << fsdir;
+            return;
+        }
+        cluster_id = fsdir.substr(pos + 1);
+        if (cluster_id.empty()) {
+            LOG(WARNING) << "TryLoadRoutingOnce: empty cluster_id parsed from "
+                            "fsdir="
+                         << fsdir;
+            return;
+        }
+        cluster_id_ = cluster_id;
+        LOG(INFO) << "TryLoadRoutingOnce: resolved cluster_id=" << cluster_id;
+    }
+
+    ErrorCode err =
+        master_client_.LoadRoutingFromEtcd(etcd_connstring_, cluster_id);
+    if (err != ErrorCode::OK) {
+        LOG(WARNING) << "TryLoadRoutingOnce: failed to load routing, "
+                        "cluster_id="
+                     << cluster_id << " err=" << err;
+        return;
+    }
+    LOG(INFO) << "TryLoadRoutingOnce: routing loaded, cluster_id=" << cluster_id;
+}
+
+void Client::RoutingRefreshThreadMain() {
+    // Refresh cadence aligned with SlotOwnerHeartbeat (5s) and
+    // CvmController::SyncLoop (5s). Slot migration is a low-frequency event,
+    // so a fixed sleep (rather than a fast poll) keeps steady-state etcd load
+    // low while still picking up changes promptly.
+    constexpr auto kRefreshInterval = std::chrono::milliseconds(5000);
+
+    while (routing_refresh_running_.load()) {
+        std::this_thread::sleep_for(kRefreshInterval);
+        TryLoadRoutingOnce();
+        // CVM 多 submaster：同步刷新已发现的 primary 地址，并对新增的
+        // submaster 全量 mount，处理运行期 submaster 增删。
+        RefreshSubmasterAddresses();
+    }
+}
+
 ErrorCode Client::SwitchLeader(const ha::MasterView& target_view) {
     std::lock_guard<std::mutex> lock(leader_switch_mutex_);
 
@@ -923,6 +1214,10 @@ std::optional<std::shared_ptr<Client>> Client::Create(
         return std::nullopt;
     }
 
+    // Load the KV partition routing table from etcd (HA mode only). Best
+    // effort: a routing load failure must not fail client startup.
+    client->LoadPartitionRouting();
+
     // Initialize storage backend if storage_root_dir is valid
     auto config_response = client->master_client_.GetStorageConfig();
     if (!config_response) {
@@ -1100,6 +1395,19 @@ tl::expected<QueryResult, ErrorCode> Client::Query(
     std::chrono::steady_clock::time_point start_time =
         std::chrono::steady_clock::now();
     auto result = master_client_.GetReplicaList(object_key);
+    // 松耦合重路由：SLOT_NOT_OWNED 表示本地 slot→submaster 视图过期
+    // （分区已重平衡）。刷新一次路由快照后重试，submaster 经 etcd 收敛视图。
+    if (!result && result.error() == ErrorCode::SLOT_NOT_OWNED &&
+        !etcd_connstring_.empty()) {
+        LOG(WARNING) << "Query: SLOT_NOT_OWNED for key=" << object_key
+                     << ", refreshing slot routing and retrying once";
+        TryLoadRoutingOnce();
+        result = master_client_.GetReplicaList(object_key);
+        if (result) {
+            LOG(INFO) << "Query: re-route retry succeeded for key="
+                      << object_key;
+        }
+    }
     if (!result) {
         return tl::unexpected(result.error());
     }
@@ -1123,6 +1431,26 @@ std::vector<tl::expected<QueryResult, ErrorCode>> Client::BatchQuery(
         std::chrono::steady_clock::now();
     auto response = master_client_.BatchGetReplicaList(object_keys, tenant_id);
 
+    // 松耦合重路由：任一项返回 SLOT_NOT_OWNED 说明视图过期，刷新一次后
+    // 整体重试；读操作幂等，重复查询已成功项无害。
+    if (!etcd_connstring_.empty()) {
+        bool has_slot_not_owned = false;
+        for (const auto& r : response) {
+            if (!r && r.error() == ErrorCode::SLOT_NOT_OWNED) {
+                has_slot_not_owned = true;
+                break;
+            }
+        }
+        if (has_slot_not_owned) {
+            LOG(WARNING) << "BatchQuery: SLOT_NOT_OWNED in batch of "
+                         << object_keys.size()
+                         << " keys, refreshing slot routing and retrying once";
+            TryLoadRoutingOnce();
+            response =
+                master_client_.BatchGetReplicaList(object_keys, tenant_id);
+        }
+    }
+
     // Check if we got the expected number of responses
     if (response.size() != object_keys.size()) {
         LOG(ERROR) << "BatchQuery response size mismatch. Expected: "
@@ -3139,12 +3467,30 @@ tl::expected<void, ErrorCode> Client::MountSegment(
 
 tl::expected<void, ErrorCode> Client::UnmountSegmentImpl(
     std::unordered_map<UUID, Segment, boost::hash<UUID>>::iterator it) {
-    auto unmount_result = master_client_.UnmountSegment(it->second.id);
-    if (!unmount_result) {
-        ErrorCode err = unmount_result.error();
-        LOG(ERROR) << "Failed to unmount segment from master: "
-                   << toString(err);
-        return tl::unexpected(err);
+    // 全量 unmount：与全量 mount 对称，向所有 primary submaster 注销 segment
+    //（单个失败仅告警，不阻断本地 unregister）。单 master/直连走原路径。
+    std::vector<std::string> unmount_targets;
+    {
+        std::lock_guard<std::mutex> addr_lock(cvm_submaster_addresses_mutex_);
+        unmount_targets = cvm_submaster_addresses_;
+    }
+    if (!unmount_targets.empty()) {
+        for (const auto& addr : unmount_targets) {
+            auto r = master_client_.UnmountSegmentTo(addr, it->second.id);
+            if (!r) {
+                LOG(WARNING) << "unmount_segment_from_submaster_failed addr="
+                             << addr << " id=" << it->second.id
+                             << " error=" << r.error();
+            }
+        }
+    } else {
+        auto unmount_result = master_client_.UnmountSegment(it->second.id);
+        if (!unmount_result) {
+            ErrorCode err = unmount_result.error();
+            LOG(ERROR) << "Failed to unmount segment from master: "
+                       << toString(err);
+            return tl::unexpected(err);
+        }
     }
 
     int rc = transfer_engine_->unregisterLocalMemory(
@@ -3233,12 +3579,40 @@ tl::expected<UUID, ErrorCode> Client::MountSegmentAndGetId(
             segment.te_endpoint = local_hostname_;
         }
 
-        auto mount_result = master_client_.MountSegment(segment);
-        if (!mount_result) {
-            ErrorCode err = mount_result.error();
-            LOG(ERROR) << "mount_segment_to_master_failed base=" << buffer
-                       << " size=" << size << ", error=" << err;
-            return tl::unexpected(err);
+        // 全量 mount：CVM 多 submaster 模式下，同一 segment 挂到所有 primary
+        // submaster（任一成功即可），使任何 slot owner 都能本地分配副本；
+        // 单 master/直连模式下 cvm_submaster_addresses_ 为空，走原 MountSegment。
+        std::vector<std::string> mount_targets;
+        {
+            std::lock_guard<std::mutex> addr_lock(
+                cvm_submaster_addresses_mutex_);
+            mount_targets = cvm_submaster_addresses_;
+        }
+        if (!mount_targets.empty()) {
+            bool any_mounted = false;
+            for (const auto& addr : mount_targets) {
+                auto r = master_client_.MountSegmentTo(addr, segment);
+                if (r) {
+                    any_mounted = true;
+                } else {
+                    LOG(WARNING) << "mount_segment_to_submaster_failed addr="
+                                 << addr << " id=" << segment.id
+                                 << " error=" << r.error();
+                }
+            }
+            if (!any_mounted) {
+                LOG(ERROR) << "mount_segment_to_all_submasters_failed base="
+                           << buffer << " size=" << size;
+                return tl::unexpected(ErrorCode::RPC_FAIL);
+            }
+        } else {
+            auto mount_result = master_client_.MountSegment(segment);
+            if (!mount_result) {
+                ErrorCode err = mount_result.error();
+                LOG(ERROR) << "mount_segment_to_master_failed base=" << buffer
+                           << " size=" << size << ", error=" << err;
+                return tl::unexpected(err);
+            }
         }
 
         segment_id = segment.id;
@@ -3263,13 +3637,35 @@ tl::expected<void, ErrorCode> Client::UnmountSegmentById(
         return UnmountSegmentImpl(segment);
     }
 
-    auto result =
-        master_client_.GracefulUnmountSegment(segment_id, grace_period_ms);
-    if (!result) {
-        ErrorCode err = result.error();
-        LOG(ERROR) << "Failed to graceful unmount segment from master: "
-                   << toString(err);
-        return tl::unexpected(err);
+    // 全量优雅卸载：与全量 mount/unmount 对称，向所有 primary submaster 发起
+    // 优雅卸载。单个失败即返回错误，避免部分 submaster 已进入优雅卸载而其余
+    // 未生效导致状态不一致。单 master/直连模式走原路径。
+    std::vector<std::string> graceful_targets;
+    {
+        std::lock_guard<std::mutex> addr_lock(cvm_submaster_addresses_mutex_);
+        graceful_targets = cvm_submaster_addresses_;
+    }
+    if (!graceful_targets.empty()) {
+        for (const auto& addr : graceful_targets) {
+            auto r = master_client_.GracefulUnmountSegmentTo(
+                addr, segment_id, grace_period_ms);
+            if (!r) {
+                LOG(ERROR) << "Failed to graceful unmount segment from "
+                              "submaster addr="
+                           << addr << " id=" << segment_id
+                           << " error=" << r.error();
+                return tl::unexpected(r.error());
+            }
+        }
+    } else {
+        auto result =
+            master_client_.GracefulUnmountSegment(segment_id, grace_period_ms);
+        if (!result) {
+            ErrorCode err = result.error();
+            LOG(ERROR) << "Failed to graceful unmount segment from master: "
+                       << toString(err);
+            return tl::unexpected(err);
+        }
     }
 
     gracefully_unmounting_segments_.emplace(segment->first, segment->second);
@@ -3311,17 +3707,47 @@ void Client::OnGracefulUnmountTimer(const UUID& segment_id, int retry_left) {
         }
     }
 
-    auto status = master_client_.QuerySegmentStatusById(segment_id);
+    std::vector<std::string> status_targets;
+    {
+        std::lock_guard<std::mutex> addr_lock(cvm_submaster_addresses_mutex_);
+        status_targets = cvm_submaster_addresses_;
+    }
+
     bool removed = false;
-    if (!status) {
-        if (status.error() == ErrorCode::SEGMENT_NOT_FOUND) {
+    if (!status_targets.empty()) {
+        // 多 submaster：仅当所有 primary submaster 均确认移除后才视为完成，
+        // 保证优雅卸载在所有 submaster 对称生效后才释放本地 MR 与回调。
+        removed = true;
+        for (const auto& addr : status_targets) {
+            auto status =
+                master_client_.QuerySegmentStatusByIdTo(addr, segment_id);
+            if (!status) {
+                if (status.error() == ErrorCode::SEGMENT_NOT_FOUND) {
+                    continue;  // 该 submaster 已移除
+                }
+                LOG(WARNING) << "Failed to query graceful unmount segment "
+                                "status from submaster addr="
+                             << addr << " error=" << status.error();
+                removed = false;
+            } else if (status.value() == SegmentStatus::UNDEFINED) {
+                continue;  // 该 submaster 已移除
+            } else {
+                removed = false;
+            }
+        }
+    } else {
+        auto status = master_client_.QuerySegmentStatusById(segment_id);
+        if (!status) {
+            if (status.error() == ErrorCode::SEGMENT_NOT_FOUND) {
+                removed = true;
+            } else {
+                LOG(WARNING)
+                    << "Failed to query graceful unmount segment status: "
+                    << toString(status.error());
+            }
+        } else if (status.value() == SegmentStatus::UNDEFINED) {
             removed = true;
-        } else {
-            LOG(WARNING) << "Failed to query graceful unmount segment status: "
-                         << toString(status.error());
         }
-    } else if (status.value() == SegmentStatus::UNDEFINED) {
-        removed = true;
     }
 
     if (removed) {
@@ -4138,6 +4564,143 @@ void Client::ExecuteTask(const ClientTask& client_task) {
     }
 }
 
+void Client::HeartbeatAllSubmasters() {
+    std::vector<std::string> targets;
+    {
+        std::lock_guard<std::mutex> lock(cvm_submaster_addresses_mutex_);
+        targets = cvm_submaster_addresses_;
+    }
+    if (targets.empty()) {
+        return;  // 单 master/直连模式，无多 submaster 心跳
+    }
+
+    // 去重：当前 active master 由主循环 master_client_.Ping() 单独 ping，
+    // 这里跳过，避免同一 submaster 被重复 ping。
+    const std::string active_address = master_client_.GetCurrentAddress();
+
+    for (const auto& addr : targets) {
+        if (addr == active_address) {
+            continue;
+        }
+        auto ping_result = master_client_.PingTo(addr);
+        if (!ping_result) {
+            VLOG(1) << "HeartbeatAllSubmasters: ping submaster failed addr="
+                    << addr << " error=" << ping_result.error();
+            continue;
+        }
+        if (ping_result.value().client_status == ClientStatus::NEED_REMOUNT) {
+            // 该 submaster 侧没有本 client 的 segment（可能被误判过期卸载），
+            // 重新 mount 所有本地 segment 到该 submaster，恢复其分配能力。
+            LOG(INFO) << "HeartbeatAllSubmasters: submaster " << addr
+                      << " requires remount";
+            std::lock_guard<std::mutex> lock(mounted_segments_mutex_);
+            for (const auto& [seg_id, segment] : mounted_segments_) {
+                auto r = master_client_.MountSegmentTo(addr, segment);
+                if (!r) {
+                    LOG(WARNING) << "remount_segment_to_submaster_failed addr="
+                                 << addr << " id=" << seg_id
+                                 << " error=" << r.error();
+                }
+            }
+        }
+    }
+}
+
+void Client::RefreshSubmasterAddresses() {
+    // 仅在 CVM 多 submaster 模式下有意义（有已知 namespace）。
+    if (cvm_cluster_namespace_.empty()) {
+        return;
+    }
+
+    std::vector<cvm::MasterRegistration> masters;
+    ViewVersionId version = 0;
+    ErrorCode err = cvm::EtcdViewStore::LoadAllMasters(cvm_cluster_namespace_,
+                                                       masters, version);
+    if (err != ErrorCode::OK) {
+        LOG(WARNING) << "RefreshSubmasterAddresses: LoadAllMasters failed: "
+                     << err;
+        return;
+    }
+
+    std::vector<std::string> new_addresses;
+    for (const auto& reg : masters) {
+        if (reg.role == static_cast<int32_t>(cvm::MasterRole::kPrimary) &&
+            !reg.address.empty()) {
+            new_addresses.push_back(reg.address);
+        }
+    }
+    std::sort(new_addresses.begin(), new_addresses.end());
+    // 去重：与 ConnectToCvmSubmasters 保持一致，避免重复 primary 注册导致
+    // 全量 mount 对同一 submaster 重复调用。
+    new_addresses.erase(
+        std::unique(new_addresses.begin(), new_addresses.end()),
+        new_addresses.end());
+
+    // 若本轮扫描为空（etcd 抖动或所有 primary 异常），保持现有地址列表不变
+    //（sticky），避免短暂异常清空地址列表导致心跳与全量 mount 退化。
+    if (new_addresses.empty()) {
+        LOG(WARNING) << "RefreshSubmasterAddresses: no primary masters found, "
+                        "keeping existing addresses";
+        return;
+    }
+
+    // 对比现有地址，找出新增/移除的 submaster；同时用最新结果替换地址列表。
+    std::vector<std::string> added;
+    std::vector<std::string> removed;
+    {
+        std::lock_guard<std::mutex> lock(cvm_submaster_addresses_mutex_);
+        for (const auto& addr : new_addresses) {
+            if (std::find(cvm_submaster_addresses_.begin(),
+                          cvm_submaster_addresses_.end(),
+                          addr) == cvm_submaster_addresses_.end()) {
+                added.push_back(addr);
+            }
+        }
+        for (const auto& addr : cvm_submaster_addresses_) {
+            if (std::find(new_addresses.begin(), new_addresses.end(), addr) ==
+                new_addresses.end()) {
+                removed.push_back(addr);
+            }
+        }
+        cvm_submaster_addresses_ = std::move(new_addresses);
+    }
+
+    // 对新增的 submaster 全量 mount 所有本地 segment，使其具备分配能力。
+    if (!added.empty()) {
+        std::lock_guard<std::mutex> lock(mounted_segments_mutex_);
+        for (const auto& addr : added) {
+            LOG(INFO) << "RefreshSubmasterAddresses: new submaster " << addr
+                      << ", mounting all local segments";
+            for (const auto& [seg_id, segment] : mounted_segments_) {
+                auto r = master_client_.MountSegmentTo(addr, segment);
+                if (!r) {
+                    LOG(WARNING) << "mount_segment_to_new_submaster_failed addr="
+                                 << addr << " id=" << seg_id
+                                 << " error=" << r.error();
+                }
+            }
+        }
+    }
+
+    // 对被移除的 submaster 全量 unmount，保证 segment 生命周期对称闭合。
+    // 单个失败仅告警不阻断（其 lease 最终会过期回收）。
+    if (!removed.empty()) {
+        std::lock_guard<std::mutex> lock(mounted_segments_mutex_);
+        for (const auto& addr : removed) {
+            LOG(INFO) << "RefreshSubmasterAddresses: submaster removed " << addr
+                      << ", unmounting all local segments";
+            for (const auto& [seg_id, segment] : mounted_segments_) {
+                auto r = master_client_.UnmountSegmentTo(addr, segment.id);
+                if (!r) {
+                    LOG(WARNING)
+                        << "unmount_segment_from_removed_submaster_failed addr="
+                        << addr << " id=" << seg_id << " error=" << r.error();
+                }
+            }
+        }
+    }
+}
+
 void Client::StorageHeartbeatThreadMain() {
     // How many failed pings before reconnecting via the HA coordinator
     const int max_ping_fail_count = 3;
@@ -4214,6 +4777,10 @@ void Client::StorageHeartbeatThreadMain() {
             remount_segment_future = std::future<void>();
         }
 
+        // CVM 多 submaster 心跳：向所有 primary submaster 定向 ping 保活，
+        // 避免各 submaster 因收不到本 client 的 ping 而误判过期并卸载 segment。
+        HeartbeatAllSubmasters();
+
         // Ping master
         auto ping_result = master_client_.Ping();
         if (ping_result) {
@@ -4309,6 +4876,20 @@ void Client::StorageHeartbeatThreadMain() {
 
             LOG(INFO) << "Reconnected to master " << next_view.leader_address;
             ping_fail_count = 0;
+        } else if (!cvm_cluster_namespace_.empty()) {
+            // CVM multi-submaster mode: the connected submaster died or
+            // became unreachable. Re-discover live submasters from the
+            // /cvm/ registry and reconnect to another one.
+            LOG(ERROR) << "Failed to ping master for " << ping_fail_count
+                       << " times (CVM submaster mode); re-discovering "
+                          "submasters from etcd";
+            auto err = ConnectToCvmSubmasters(etcd_connstring_);
+            if (err != ErrorCode::OK) {
+                std::this_thread::sleep_for(
+                    std::chrono::milliseconds(fail_ping_interval_ms));
+                continue;
+            }
+            ping_fail_count = 0;
         } else {
             const std::string current_master_address = direct_master_address_;
             LOG(ERROR) << "Failed to ping master for " << ping_fail_count
diff --git a/mooncake-store/src/cvm/cvm_controller.cpp b/mooncake-store/src/cvm/cvm_controller.cpp
new file mode 100644
index 0000000000..4245a68be9
--- /dev/null
+++ b/mooncake-store/src/cvm/cvm_controller.cpp
@@ -0,0 +1,588 @@
+#include "cvm/cvm_controller.h"
+
+#include <algorithm>
+#include <chrono>
+#include <condition_variable>
+#include <mutex>
+#include <set>
+#include <utility>
+
+#include <glog/logging.h>
+
+#include "cvm/cvm_http_server.h"
+#include "cvm/cvm_keys.h"
+#include "cvm/cvm_service_delegate.h"
+#include "cvm/etcd_view_store.h"
+#include "cvm/slot_hash.h"
+#include "etcd_helper.h"
+
+namespace mooncake {
+namespace cvm {
+
+namespace {
+
+constexpr int kWatchEventBroken = 2;
+constexpr int kWatchStopTimeoutMs = 1000;
+constexpr int kKeepAliveReadyTimeoutMs = 1000;
+
+}  // namespace
+
+CvmController::CvmController(Config config) : config_(std::move(config)) {
+    current_role_.store(config_.role);
+}
+
+CvmController::~CvmController() { Stop(); }
+
+void CvmController::SetDelegate(CvmServiceDelegate* delegate) {
+    delegate_ = delegate;
+}
+
+ErrorCode CvmController::Start() {
+    if (running_.load()) {
+        return ErrorCode::OK;
+    }
+
+    LOG(INFO) << "CvmController::Start begin: cluster_namespace="
+              << config_.cluster_namespace << ", master_id="
+              << config_.master_id << ", address=" << config_.address
+              << ", role=" << static_cast<int32_t>(config_.role)
+              << ", registration_lease_ttl_sec="
+              << config_.registration_lease_ttl_sec << ", http_host="
+              << config_.http_host << ", http_port=" << config_.http_port
+              << ", sync_interval_ms=" << config_.sync_interval.count();
+
+    // NOTE: the etcd client is a process-global singleton (EtcdHelper); the
+    // embedding master is responsible for connecting it before Start().
+    ErrorCode err = EtcdHelper::GrantLease(config_.registration_lease_ttl_sec,
+                                           lease_id_);
+    if (err != ErrorCode::OK) {
+        LOG(ERROR) << "CvmController::Start GrantLease failed: err=" << err
+                   << ", cluster_namespace=" << config_.cluster_namespace
+                   << ", master_id=" << config_.master_id
+                   << ", registration_lease_ttl_sec="
+                   << config_.registration_lease_ttl_sec
+                   << " (etcd client may not be connected yet)";
+        return err;
+    }
+    LOG(INFO) << "CvmController::Start GrantLease ok: lease_id=" << lease_id_;
+
+    MasterRegistration reg;
+    reg.master_id = config_.master_id;
+    reg.address = config_.address;
+    reg.role = static_cast<int32_t>(config_.role);
+    reg.registered_at_ms =
+        std::chrono::duration_cast<std::chrono::milliseconds>(
+            std::chrono::system_clock::now().time_since_epoch())
+            .count();
+    LOG(INFO) << "CvmController::Start registering master: master_id="
+              << reg.master_id << ", address=" << reg.address << ", role="
+              << reg.role << ", cluster_namespace=" << config_.cluster_namespace
+              << ", lease_id=" << lease_id_;
+    err = EtcdViewStore::RegisterMaster(config_.cluster_namespace, reg,
+                                        lease_id_);
+    if (err != ErrorCode::OK) {
+        LOG(ERROR) << "CvmController::Start RegisterMaster failed: err=" << err
+                   << ", master_id=" << reg.master_id << ", address="
+                   << reg.address << ", role=" << reg.role
+                   << ", cluster_namespace=" << config_.cluster_namespace
+                   << ", lease_id=" << lease_id_;
+        (void)EtcdHelper::RevokeLease(lease_id_);
+        return err;
+    }
+    LOG(INFO) << "CvmController::Start RegisterMaster ok: master_id="
+              << reg.master_id;
+
+    err = RefreshKvView();
+    if (err != ErrorCode::OK) {
+        LOG(WARNING) << "CvmController initial RefreshKvView failed: " << err
+                     << ", cluster_namespace=" << config_.cluster_namespace;
+    } else {
+        LOG(INFO) << "CvmController initial RefreshKvView ok";
+    }
+
+    watch_state_ = std::make_unique<WatchState>();
+    masters_watch_state_ = std::make_unique<WatchState>();
+    running_.store(true);
+
+    keepalive_thread_ = std::thread([this]() { KeepaliveLoop(); });
+    watch_thread_ = std::thread([this]() { WatchLoop(); });
+    masters_watch_thread_ = std::thread([this]() { MastersWatchLoop(); });
+    sync_thread_ = std::thread([this]() { SyncLoop(); });
+    membership_thread_ = std::thread([this]() { MembershipLoop(); });
+    LOG(INFO) << "CvmController::Start started "
+                 "keepalive/watch/masters_watch/sync/membership threads";
+
+    if (config_.http_port != 0) {
+        CvmHttpServer::Config http_cfg;
+        http_cfg.host = config_.http_host;
+        http_cfg.port = config_.http_port;
+        http_cfg.cluster_namespace = config_.cluster_namespace;
+        LOG(INFO) << "CvmController::Start starting CvmHttpServer: host="
+                  << http_cfg.host << ", port=" << http_cfg.port;
+        http_server_ = std::make_unique<CvmHttpServer>(http_cfg);
+        err = http_server_->Start();
+        if (err != ErrorCode::OK) {
+            LOG(ERROR) << "CvmController start http server failed: " << err
+                       << ", host=" << http_cfg.host << ", port="
+                       << http_cfg.port;
+            http_server_.reset();
+        } else {
+            LOG(INFO) << "CvmController CvmHttpServer started";
+        }
+    }
+
+    LOG(INFO) << "CvmController::Start ok";
+    return ErrorCode::OK;
+}
+
+void CvmController::Stop() {
+    if (!running_.load() && !watch_thread_.joinable() &&
+        !masters_watch_thread_.joinable() && !keepalive_thread_.joinable() &&
+        !sync_thread_.joinable() && !membership_thread_.joinable()) {
+        return;
+    }
+
+    running_.store(false);
+
+    CancelWatchAndWait();
+
+    if (watch_state_) {
+        std::lock_guard<std::mutex> lock(watch_state_->mutex);
+        watch_state_->cv.notify_all();
+    }
+    if (masters_watch_state_) {
+        std::lock_guard<std::mutex> lock(masters_watch_state_->mutex);
+        masters_watch_state_->cv.notify_all();
+    }
+
+    if (keepalive_thread_.joinable()) {
+        (void)EtcdHelper::CancelKeepAlive(lease_id_);
+        keepalive_thread_.join();
+    }
+    if (watch_thread_.joinable()) {
+        watch_thread_.join();
+    }
+    if (masters_watch_thread_.joinable()) {
+        masters_watch_thread_.join();
+    }
+    if (sync_thread_.joinable()) {
+        sync_cv_.notify_all();
+        sync_thread_.join();
+    }
+    if (membership_thread_.joinable()) {
+        membership_cv_.notify_all();
+        membership_thread_.join();
+    }
+
+    if (http_server_) {
+        http_server_->Stop();
+        http_server_.reset();
+    }
+
+    (void)EtcdHelper::RevokeLease(lease_id_);
+    watch_state_.reset();
+    masters_watch_state_.reset();
+}
+
+bool CvmController::OwnsSlot(uint16_t slot) const {
+    SharedMutexLocker locker(&view_mutex_, shared_lock);
+    auto it = kv_view_.find(slot);
+    if (it == kv_view_.end()) {
+        return false;
+    }
+    return it->second.primary_master_id == config_.master_id &&
+           it->second.state == static_cast<int32_t>(SlotState::kStable);
+}
+
+std::vector<SlotOwner> CvmController::GetKvView() const {
+    SharedMutexLocker locker(&view_mutex_, shared_lock);
+    std::vector<SlotOwner> out;
+    out.reserve(kv_view_.size());
+    for (const auto& entry : kv_view_) {
+        out.push_back(entry.second);
+    }
+    return out;
+}
+
+ViewVersionId CvmController::GetKvViewVersion() const {
+    SharedMutexLocker locker(&view_mutex_, shared_lock);
+    return kv_view_version_;
+}
+
+ErrorCode CvmController::SyncOnce() {
+    ViewVersionId version = 0;
+    ErrorCode err = EtcdViewStore::BuildAndSaveKvViewSnapshot(
+        config_.cluster_namespace, version);
+    if (err != ErrorCode::OK) {
+        LOG(ERROR) << "CvmController build kv view snapshot failed: " << err;
+        return err;
+    }
+
+    err = EtcdViewStore::BuildAndSaveSegmentViewSnapshot(
+        config_.cluster_namespace, version);
+    if (err != ErrorCode::OK) {
+        // segment 视图为预留，失败不阻断 kv 视图路径同步。
+        LOG(WARNING) << "CvmController build segment view snapshot failed: "
+                     << err;
+    }
+
+    PushViewPaths();
+    return ErrorCode::OK;
+}
+
+void CvmController::PushViewPaths() {
+    const std::string kv_key = KvViewSnapshotKey(config_.cluster_namespace);
+    const std::string segment_key =
+        SegmentViewSnapshotKey(config_.cluster_namespace);
+
+    view_paths_["kv_view"] = kv_key;
+    view_paths_["segment_view"] = segment_key;
+
+    if (http_server_) {
+        http_server_->SetKvViewSnapshotKey(kv_key);
+        http_server_->SetSegmentViewSnapshotKey(segment_key);
+    }
+    LOG(INFO) << "CvmController pushed view paths: kv_view=" << kv_key
+              << " segment_view=" << segment_key;
+}
+
+ErrorCode CvmController::RefreshKvView() {
+    std::vector<SlotOwner> owners;
+    ViewVersionId version = 0;
+    ErrorCode err =
+        EtcdViewStore::LoadAllSlotOwners(config_.cluster_namespace, owners,
+                                         version);
+    if (err != ErrorCode::OK) {
+        return err;
+    }
+
+    std::unordered_map<uint16_t, SlotOwner> next;
+    next.reserve(owners.size());
+    for (auto& owner : owners) {
+        next.emplace(owner.slot, std::move(owner));
+    }
+
+    {
+        SharedMutexLocker locker(&view_mutex_);
+        kv_view_ = std::move(next);
+        kv_view_version_ = version;
+    }
+    return ErrorCode::OK;
+}
+
+void CvmController::CancelWatchAndWait() {
+    if (watch_armed_.exchange(false)) {
+        (void)EtcdViewStore::CancelWatchKvView(config_.cluster_namespace);
+        (void)EtcdViewStore::WaitWatchKvViewStopped(config_.cluster_namespace,
+                                                    kWatchStopTimeoutMs);
+    }
+    if (masters_watch_armed_.exchange(false)) {
+        (void)EtcdViewStore::CancelWatchMasters(config_.cluster_namespace);
+        (void)EtcdViewStore::WaitWatchMastersStopped(config_.cluster_namespace,
+                                                     kWatchStopTimeoutMs);
+    }
+}
+
+void CvmController::WatchLoop() {
+    while (running_.load()) {
+        ViewVersionId version_before = 0;
+        {
+            SharedMutexLocker locker(&view_mutex_, shared_lock);
+            version_before = kv_view_version_;
+        }
+
+        ErrorCode err = RefreshKvView();
+        if (err != ErrorCode::OK) {
+            LOG(WARNING) << "CvmController WatchLoop refresh failed: " << err;
+        }
+
+        ViewVersionId version_after = 0;
+        {
+            SharedMutexLocker locker(&view_mutex_, shared_lock);
+            version_after = kv_view_version_;
+        }
+        // slot 所有权视图变化：通知 delegate，让 standby 即使角色不变也能
+        // 重绑回放源（技术债 2 修复）。
+        if (version_after != version_before && delegate_) {
+            delegate_->OnKvViewChanged();
+        }
+
+        if (!running_.load()) {
+            break;
+        }
+
+        CancelWatchAndWait();
+
+        {
+            std::lock_guard<std::mutex> lock(watch_state_->mutex);
+            watch_state_->dirty = false;
+            watch_state_->broken = false;
+        }
+
+        ViewVersionId start_version = 0;
+        {
+            SharedMutexLocker locker(&view_mutex_, shared_lock);
+            start_version = kv_view_version_;
+        }
+
+        err = EtcdViewStore::WatchKvView(config_.cluster_namespace,
+                                         start_version, watch_state_.get(),
+                                         &CvmController::WatchCallback);
+        if (err != ErrorCode::OK) {
+            LOG(WARNING) << "CvmController arm watch failed: " << err;
+            std::this_thread::sleep_for(std::chrono::seconds(1));
+            continue;
+        }
+        watch_armed_.store(true);
+
+        std::unique_lock<std::mutex> lock(watch_state_->mutex);
+        watch_state_->cv.wait(lock, [this] {
+            return watch_state_->dirty || watch_state_->broken ||
+                   !running_.load();
+        });
+    }
+}
+
+void CvmController::MastersWatchLoop() {
+    while (running_.load()) {
+        {
+            std::lock_guard<std::mutex> lock(masters_watch_state_->mutex);
+            masters_watch_state_->dirty = false;
+            masters_watch_state_->broken = false;
+        }
+
+        // start_revision=0 → 从当前开始 watch，只关注未来的成员增删（lease
+        // 过期删除 / 新节点注册）。
+        ErrorCode err = EtcdViewStore::WatchMasters(
+            config_.cluster_namespace, /*start_revision=*/0,
+            masters_watch_state_.get(), &CvmController::WatchCallback);
+        if (err != ErrorCode::OK) {
+            LOG(WARNING) << "CvmController arm masters watch failed: " << err;
+            std::this_thread::sleep_for(std::chrono::seconds(1));
+            continue;
+        }
+        masters_watch_armed_.store(true);
+
+        std::unique_lock<std::mutex> lock(masters_watch_state_->mutex);
+        masters_watch_state_->cv.wait(lock, [this] {
+            return masters_watch_state_->dirty ||
+                   masters_watch_state_->broken || !running_.load();
+        });
+
+        // 成员增删（lease 过期）→ 立即重算角色，并唤醒 sync 线程立即重算
+        // slot 快照，使 failover 不再等待轮询周期。
+        ReconcileRole();
+        sync_cv_.notify_all();
+    }
+}
+
+void CvmController::KeepaliveLoop() {
+    (void)EtcdHelper::WaitKeepAliveReady(lease_id_, kKeepAliveReadyTimeoutMs);
+    ErrorCode rc = EtcdHelper::KeepAlive(lease_id_);
+    if (rc == ErrorCode::ETCD_OPERATION_ERROR) {
+        LOG(WARNING) << "CvmController keepalive error: " << rc;
+    }
+}
+
+void CvmController::SyncLoop() {
+    while (running_.load()) {
+        (void)SyncOnce();
+
+        std::unique_lock<std::mutex> lock(sync_mutex_);
+        sync_cv_.wait_for(lock, config_.sync_interval,
+                          [this] { return !running_.load(); });
+    }
+}
+
+bool CvmController::LoadRankedMembers(
+    std::vector<MasterRegistration>& out) {
+    std::vector<MasterRegistration> masters;
+    ViewVersionId version = 0;
+    ErrorCode err = EtcdViewStore::LoadAllMasters(config_.cluster_namespace,
+                                                  masters, version);
+    if (err != ErrorCode::OK) {
+        LOG(WARNING) << "CvmController load masters failed: " << err
+                     << ", master_id=" << config_.master_id;
+        return false;
+    }
+
+    // 收集所有存活 master（含本机）作为候选，按「先到先得」排序。
+    out.clear();
+    out.reserve(masters.size());
+    for (const auto& m : masters) {
+        if (!m.master_id.empty()) {
+            out.push_back(m);
+        }
+    }
+
+    std::sort(out.begin(), out.end(),
+              [](const MasterRegistration& a, const MasterRegistration& b) {
+                  if (a.registered_at_ms != b.registered_at_ms) {
+                      return a.registered_at_ms < b.registered_at_ms;
+                  }
+                  return a.master_id < b.master_id;
+              });
+    return true;
+}
+
+MasterRole CvmController::ComputeDesiredRole() {
+    std::vector<MasterRegistration> members;
+    if (!LoadRankedMembers(members)) {
+        return current_role_.load();
+    }
+
+    for (size_t i = 0; i < members.size(); ++i) {
+        if (members[i].master_id == config_.master_id) {
+            return i < config_.submaster_count ? MasterRole::kPrimary
+                                               : MasterRole::kStandby;
+        }
+    }
+
+    // 本机不在成员集（未注册/异常）：保守保持当前角色。
+    return current_role_.load();
+}
+
+std::string CvmController::GetPrimaryAddress() {
+    std::vector<MasterRegistration> members;
+    if (!LoadRankedMembers(members) || members.empty()) {
+        return "";
+    }
+    // 排名第一的成员是集群中最早的 primary。若本机就是它，则无需（也不能）
+    // 把自己当作回放源，返回空字符串让调用方保持纯 standby。
+    if (members.front().master_id == config_.master_id) {
+        return "";
+    }
+    return members.front().address;
+}
+
+std::vector<MasterRegistration> CvmController::GetPrimaryPeers() {
+    std::vector<MasterRegistration> members;
+    if (!LoadRankedMembers(members) || members.empty()) {
+        return {};
+    }
+    std::vector<MasterRegistration> peers;
+    peers.reserve(std::min<size_t>(members.size(), config_.submaster_count));
+    for (size_t i = 0; i < members.size() && i < config_.submaster_count; ++i) {
+        if (members[i].master_id == config_.master_id) {
+            continue;  // 本机不作为自己的回放源。
+        }
+        peers.push_back(members[i]);
+    }
+    return peers;
+}
+
+std::vector<MasterRegistration> CvmController::GetBindingSources() {
+    std::vector<MasterRegistration> members;
+    if (!LoadRankedMembers(members) || members.empty()) {
+        return {};
+    }
+
+    const size_t primary_count =
+        std::min<size_t>(members.size(), config_.submaster_count);
+
+    // 本机在「先到先得」排序列表中的位置。
+    size_t my_index = members.size();
+    for (size_t i = 0; i < members.size(); ++i) {
+        if (members[i].master_id == config_.master_id) {
+            my_index = i;
+            break;
+        }
+    }
+    // 未注册 / 本机已是 primary：不作为 standby 回放。
+    if (my_index == members.size() || my_index < primary_count) {
+        return {};
+    }
+
+    const size_t standby_count = members.size() - primary_count;
+    if (standby_count == 0) {
+        return {};
+    }
+    const size_t standby_rank = my_index - primary_count;
+
+    // 本 standby 负责的 slot 区间 [start, end)，与其它 standby 均分 16384。
+    const uint16_t start = static_cast<uint16_t>(standby_rank * kSlotCount /
+                                                 standby_count);
+    const uint16_t end = static_cast<uint16_t>((standby_rank + 1) * kSlotCount /
+                                               standby_count);
+
+    // 求出负责区间内每个 slot 的 primary owner（仅 kStable、非本机）。
+    std::set<std::string> owner_ids;
+    {
+        SharedMutexLocker locker(&view_mutex_, shared_lock);
+        for (uint16_t slot = start; slot < end; ++slot) {
+            auto it = kv_view_.find(slot);
+            if (it == kv_view_.end()) {
+                continue;
+            }
+            if (it->second.state != static_cast<int32_t>(SlotState::kStable)) {
+                continue;
+            }
+            const std::string& owner = it->second.primary_master_id;
+            if (!owner.empty() && owner != config_.master_id) {
+                owner_ids.insert(owner);
+            }
+        }
+    }
+
+    // 映射 owner master_id -> MasterRegistration（含 address）。
+    std::vector<MasterRegistration> sources;
+    sources.reserve(owner_ids.size());
+    for (const auto& m : members) {
+        if (owner_ids.count(m.master_id)) {
+            sources.push_back(m);
+        }
+    }
+    return sources;
+}
+
+void CvmController::ReconcileRole() {
+    const MasterRole desired = ComputeDesiredRole();
+    MasterRole current = current_role_.load();
+    if (desired == current) {
+        return;
+    }
+    // CAS：membership_thread_ 与 masters_watch_thread_ 并发调用时，仅一个
+    // 线程执行角色迁移与通知，避免重复 OnRoleChanged。
+    if (!current_role_.compare_exchange_strong(current, desired)) {
+        return;
+    }
+    LOG(INFO) << "CvmController role decision: master_id="
+              << config_.master_id << ", current="
+              << static_cast<int32_t>(current)
+              << ", desired=" << static_cast<int32_t>(desired)
+              << ", submaster_count=" << config_.submaster_count;
+    if (delegate_) {
+        delegate_->OnRoleChanged(desired);
+    }
+}
+
+void CvmController::MembershipLoop() {
+    while (running_.load()) {
+        ReconcileRole();
+
+        std::unique_lock<std::mutex> lock(membership_mutex_);
+        membership_cv_.wait_for(lock, config_.sync_interval,
+                                [this] { return !running_.load(); });
+    }
+}
+
+void CvmController::WatchCallback(void* ctx, const char* /*key*/,
+                                  size_t /*key_size*/, const char* /*value*/,
+                                  size_t /*value_size*/, int event_type,
+                                  int64_t /*mod_revision*/) {
+    auto* state = static_cast<WatchState*>(ctx);
+    if (state == nullptr) {
+        return;
+    }
+    {
+        std::lock_guard<std::mutex> lock(state->mutex);
+        state->dirty = true;
+        if (event_type == kWatchEventBroken) {
+            state->broken = true;
+        }
+    }
+    state->cv.notify_all();
+}
+
+}  // namespace cvm
+}  // namespace mooncake
diff --git a/mooncake-store/src/cvm/cvm_http_server.cpp b/mooncake-store/src/cvm/cvm_http_server.cpp
new file mode 100644
index 0000000000..11976cee9e
--- /dev/null
+++ b/mooncake-store/src/cvm/cvm_http_server.cpp
@@ -0,0 +1,133 @@
+#include "cvm/cvm_http_server.h"
+
+#include <utility>
+
+#include <glog/logging.h>
+
+#include "cvm/cvm_keys.h"
+#include "etcd_helper.h"
+
+namespace mooncake {
+namespace cvm {
+
+CvmHttpServer::CvmHttpServer(Config config)
+    : config_(std::move(config)),
+      server_(std::make_unique<coro_http::coro_http_server>(4, config_.port)),
+      kv_view_snapshot_key_(KvViewSnapshotKey(config_.cluster_namespace)),
+      segment_view_snapshot_key_(
+          SegmentViewSnapshotKey(config_.cluster_namespace)) {
+    InitRoutes();
+}
+
+CvmHttpServer::~CvmHttpServer() { Stop(); }
+
+void CvmHttpServer::InitRoutes() {
+    using namespace coro_http;
+
+    server_->set_http_handler<GET>(
+        "/kv_view", [this](coro_http_request& req, coro_http_response& resp) {
+            (void)req;
+            std::string json = GetKvViewJson();
+            if (json.empty()) {
+                resp.set_status_and_content(status_type::not_found,
+                                            "kv view snapshot not found");
+                return;
+            }
+            resp.add_header("Content-Type", "application/json");
+            resp.set_status_and_content(status_type::ok, json);
+        });
+
+    server_->set_http_handler<GET>(
+        "/segment_view",
+        [this](coro_http_request& req, coro_http_response& resp) {
+            (void)req;
+            std::string json = GetSegmentViewJson();
+            if (json.empty()) {
+                resp.set_status_and_content(
+                    status_type::not_found, "segment view snapshot not found");
+                return;
+            }
+            resp.add_header("Content-Type", "application/json");
+            resp.set_status_and_content(status_type::ok, json);
+        });
+
+    server_->set_http_handler<GET>(
+        "/health", [](coro_http_request& req, coro_http_response& resp) {
+            (void)req;
+            resp.set_status_and_content(status_type::ok, "OK");
+        });
+}
+
+ErrorCode CvmHttpServer::Start() {
+    if (running_.load()) {
+        return ErrorCode::OK;
+    }
+
+    // async_start() binds synchronously and returns a future that is already
+    // resolved (hasResult()) when the bind failed. Mirrors
+    // HttpMetadataServer::start().
+    auto ec = server_->async_start();
+    if (ec.hasResult()) {
+        LOG(ERROR) << "CvmHttpServer failed to start on " << config_.host << ":"
+                   << config_.port;
+        return ErrorCode::RPC_FAIL;
+    }
+    running_.store(true);
+    LOG(INFO) << "CvmHttpServer started on " << config_.host << ":"
+              << config_.port;
+    return ErrorCode::OK;
+}
+
+void CvmHttpServer::Stop() {
+    if (!running_.exchange(false)) {
+        return;
+    }
+    server_->stop();
+    LOG(INFO) << "CvmHttpServer stopped";
+}
+
+void CvmHttpServer::SetKvViewSnapshotKey(const std::string& key) {
+    std::lock_guard<std::mutex> lock(path_mutex_);
+    kv_view_snapshot_key_ = key;
+}
+
+void CvmHttpServer::SetSegmentViewSnapshotKey(const std::string& key) {
+    std::lock_guard<std::mutex> lock(path_mutex_);
+    segment_view_snapshot_key_ = key;
+}
+
+std::string CvmHttpServer::GetKvViewJson() const {
+    std::string key;
+    {
+        std::lock_guard<std::mutex> lock(path_mutex_);
+        key = kv_view_snapshot_key_;
+    }
+    return ReadSnapshot(key);
+}
+
+std::string CvmHttpServer::GetSegmentViewJson() const {
+    std::string key;
+    {
+        std::lock_guard<std::mutex> lock(path_mutex_);
+        key = segment_view_snapshot_key_;
+    }
+    return ReadSnapshot(key);
+}
+
+std::string CvmHttpServer::ReadSnapshot(const std::string& key) const {
+    if (key.empty()) {
+        return "";
+    }
+    std::string value;
+    EtcdRevisionId revision = 0;
+    ErrorCode err = EtcdHelper::Get(key.data(), key.size(), value, revision);
+    if (err != ErrorCode::OK) {
+        LOG(WARNING) << "CvmHttpServer read snapshot failed: " << key
+                     << " err=" << err;
+        return "";
+    }
+    return value;
+}
+
+}  // namespace cvm
+}  // namespace mooncake
diff --git a/mooncake-store/src/cvm/etcd_view_store.cpp b/mooncake-store/src/cvm/etcd_view_store.cpp
new file mode 100644
index 0000000000..3e547de2f6
--- /dev/null
+++ b/mooncake-store/src/cvm/etcd_view_store.cpp
@@ -0,0 +1,636 @@
+#include "cvm/etcd_view_store.h"
+
+#include <algorithm>
+#include <chrono>
+#include <memory>
+#include <sstream>
+#include <unordered_map>
+#include <utility>
+#include <vector>
+
+#include <glog/logging.h>
+
+#if __has_include(<jsoncpp/json/json.h>)
+#include <jsoncpp/json/json.h>
+#else
+#include <json/json.h>
+#endif
+
+#include "cvm/cvm_keys.h"
+#include "etcd_helper.h"
+#include "ylt/struct_json/json_reader.h"
+#include "ylt/struct_json/json_writer.h"
+
+namespace mooncake {
+namespace cvm {
+
+namespace {
+
+// Parses the JSON array returned by EtcdHelper::GetRangeAsJson, which has the
+// form [{"key":"...","value":"..."}, ...].
+ErrorCode ParseRangeJson(const std::string& json,
+                         std::vector<std::pair<std::string, std::string>>& kvs) {
+    Json::Value root;
+    Json::CharReaderBuilder reader;
+    std::string errors;
+    std::istringstream stream(json);
+    if (!Json::parseFromStream(reader, stream, &root, &errors) ||
+        !root.isArray()) {
+        LOG(ERROR) << "Failed to parse etcd range JSON: " << errors;
+        return ErrorCode::INTERNAL_ERROR;
+    }
+
+    kvs.clear();
+    kvs.reserve(root.size());
+    for (const auto& item : root) {
+        if (!item.isObject() || !item["key"].isString() ||
+            !item["value"].isString()) {
+            return ErrorCode::INTERNAL_ERROR;
+        }
+        kvs.emplace_back(item["key"].asString(), item["value"].asString());
+    }
+    return ErrorCode::OK;
+}
+
+}  // namespace
+
+// ---- JSON serialization ----
+
+ErrorCode EtcdViewStore::SerializeSlotOwner(const SlotOwner& owner,
+                                            std::string& out) {
+    try {
+        struct_json::to_json(owner, out);
+    } catch (const std::exception& e) {
+        LOG(ERROR) << "SerializeSlotOwner failed: " << e.what();
+        return ErrorCode::SERIALIZE_FAIL;
+    }
+    return ErrorCode::OK;
+}
+
+ErrorCode EtcdViewStore::DeserializeSlotOwner(const std::string& in,
+                                              SlotOwner& out) {
+    try {
+        struct_json::from_json(out, in);
+    } catch (const std::exception& e) {
+        LOG(ERROR) << "DeserializeSlotOwner failed: " << e.what();
+        return ErrorCode::DESERIALIZE_FAIL;
+    }
+    return ErrorCode::OK;
+}
+
+ErrorCode EtcdViewStore::SerializeSegmentOwner(const SegmentOwner& owner,
+                                               std::string& out) {
+    try {
+        struct_json::to_json(owner, out);
+    } catch (const std::exception& e) {
+        LOG(ERROR) << "SerializeSegmentOwner failed: " << e.what();
+        return ErrorCode::SERIALIZE_FAIL;
+    }
+    return ErrorCode::OK;
+}
+
+ErrorCode EtcdViewStore::DeserializeSegmentOwner(const std::string& in,
+                                                 SegmentOwner& out) {
+    try {
+        struct_json::from_json(out, in);
+    } catch (const std::exception& e) {
+        LOG(ERROR) << "DeserializeSegmentOwner failed: " << e.what();
+        return ErrorCode::DESERIALIZE_FAIL;
+    }
+    return ErrorCode::OK;
+}
+
+ErrorCode EtcdViewStore::SerializeMasterRegistration(const MasterRegistration& reg,
+                                                     std::string& out) {
+    try {
+        struct_json::to_json(reg, out);
+    } catch (const std::exception& e) {
+        LOG(ERROR) << "SerializeMasterRegistration failed: " << e.what();
+        return ErrorCode::SERIALIZE_FAIL;
+    }
+    return ErrorCode::OK;
+}
+
+ErrorCode EtcdViewStore::DeserializeMasterRegistration(const std::string& in,
+                                                       MasterRegistration& out) {
+    try {
+        struct_json::from_json(out, in);
+    } catch (const std::exception& e) {
+        LOG(ERROR) << "DeserializeMasterRegistration failed: " << e.what();
+        return ErrorCode::DESERIALIZE_FAIL;
+    }
+    return ErrorCode::OK;
+}
+
+ErrorCode EtcdViewStore::SerializeKvViewSnapshot(const KvViewSnapshot& snapshot,
+                                                 std::string& out) {
+    try {
+        struct_json::to_json(snapshot, out);
+    } catch (const std::exception& e) {
+        LOG(ERROR) << "SerializeKvViewSnapshot failed: " << e.what();
+        return ErrorCode::SERIALIZE_FAIL;
+    }
+    return ErrorCode::OK;
+}
+
+ErrorCode EtcdViewStore::DeserializeKvViewSnapshot(const std::string& in,
+                                                   KvViewSnapshot& out) {
+    try {
+        struct_json::from_json(out, in);
+    } catch (const std::exception& e) {
+        LOG(ERROR) << "DeserializeKvViewSnapshot failed: " << e.what();
+        return ErrorCode::DESERIALIZE_FAIL;
+    }
+    return ErrorCode::OK;
+}
+
+ErrorCode EtcdViewStore::SerializeSegmentViewSnapshot(
+    const SegmentViewSnapshot& snapshot, std::string& out) {
+    try {
+        struct_json::to_json(snapshot, out);
+    } catch (const std::exception& e) {
+        LOG(ERROR) << "SerializeSegmentViewSnapshot failed: " << e.what();
+        return ErrorCode::SERIALIZE_FAIL;
+    }
+    return ErrorCode::OK;
+}
+
+ErrorCode EtcdViewStore::DeserializeSegmentViewSnapshot(const std::string& in,
+                                                        SegmentViewSnapshot& out) {
+    try {
+        struct_json::from_json(out, in);
+    } catch (const std::exception& e) {
+        LOG(ERROR) << "DeserializeSegmentViewSnapshot failed: " << e.what();
+        return ErrorCode::DESERIALIZE_FAIL;
+    }
+    return ErrorCode::OK;
+}
+
+// ---- KV view ----
+
+ErrorCode EtcdViewStore::LoadSlotOwner(const std::string& cluster_namespace,
+                                       uint16_t slot, SlotOwner& out,
+                                       ViewVersionId& version) {
+    const std::string key = SlotOwnerKey(cluster_namespace, slot);
+    std::string value;
+    ErrorCode err = EtcdHelper::Get(key.data(), key.size(), value, version);
+    if (err != ErrorCode::OK) {
+        return err;
+    }
+    return DeserializeSlotOwner(value, out);
+}
+
+ErrorCode EtcdViewStore::SaveSlotOwner(const std::string& cluster_namespace,
+                                       const SlotOwner& owner) {
+    const std::string key = SlotOwnerKey(cluster_namespace, owner.slot);
+    std::string value;
+    ErrorCode err = SerializeSlotOwner(owner, value);
+    if (err != ErrorCode::OK) {
+        return err;
+    }
+    return EtcdHelper::Put(key.data(), key.size(), value.data(), value.size());
+}
+
+ErrorCode EtcdViewStore::SaveSlotOwnerWithLease(
+    const std::string& cluster_namespace, const SlotOwner& owner,
+    EtcdLeaseId lease_id) {
+    const std::string key = SlotOwnerKey(cluster_namespace, owner.slot);
+    std::string value;
+    ErrorCode err = SerializeSlotOwner(owner, value);
+    if (err != ErrorCode::OK) {
+        return err;
+    }
+    return EtcdHelper::PutWithLease(key.data(), key.size(), value.data(),
+                                    value.size(), lease_id);
+}
+
+ErrorCode EtcdViewStore::SaveSlotOwnersWithLease(
+    const std::string& cluster_namespace,
+    const std::vector<SlotOwner>& owners, EtcdLeaseId lease_id) {
+    // etcd 默认单事务操作数上限为 128，因此按 128 个/批分块，每批一次事务写。
+    constexpr size_t kTxnOpLimit = 128;
+    for (size_t i = 0; i < owners.size(); i += kTxnOpLimit) {
+        const size_t n = std::min(kTxnOpLimit, owners.size() - i);
+        std::vector<std::string> keys;
+        std::vector<std::string> values;
+        keys.reserve(n);
+        values.reserve(n);
+        bool serialize_ok = true;
+        for (size_t j = 0; j < n; ++j) {
+            const SlotOwner& owner = owners[i + j];
+            keys.push_back(SlotOwnerKey(cluster_namespace, owner.slot));
+            std::string value;
+            if (SerializeSlotOwner(owner, value) != ErrorCode::OK) {
+                serialize_ok = false;
+                break;
+            }
+            values.push_back(std::move(value));
+        }
+        if (!serialize_ok) {
+            return ErrorCode::SERIALIZE_FAIL;
+        }
+        ErrorCode err = EtcdHelper::BatchPutWithLease(keys, values, lease_id);
+        if (err == ErrorCode::OK) {
+            continue;
+        }
+        // 某批事务失败：退化为逐条写，避免整批丢弃。仍失败则上抛。
+        LOG(WARNING) << "SaveSlotOwnersWithLease batch of " << n
+                     << " failed: " << err << ", falling back per-slot";
+        for (size_t j = 0; j < n; ++j) {
+            err = EtcdHelper::PutWithLease(keys[j].data(), keys[j].size(),
+                                           values[j].data(), values[j].size(),
+                                           lease_id);
+            if (err != ErrorCode::OK) {
+                LOG(ERROR) << "SaveSlotOwnersWithLease per-slot put failed for "
+                           << keys[j] << ": " << err;
+                return err;
+            }
+        }
+    }
+    return ErrorCode::OK;
+}
+
+ErrorCode EtcdViewStore::DeleteSlotOwner(const std::string& cluster_namespace,
+                                         uint16_t slot) {
+    const std::string key = SlotOwnerKey(cluster_namespace, slot);
+    const std::string end = PrefixEnd(key);
+    return EtcdHelper::DeleteRange(key.data(), key.size(), end.data(),
+                                   end.size());
+}
+
+ErrorCode EtcdViewStore::DeleteSlotOwnerIfOwnedBy(
+    const std::string& cluster_namespace, uint16_t slot,
+    const std::string& master_id) {
+    SlotOwner owner;
+    ViewVersionId version = 0;
+    ErrorCode err = LoadSlotOwner(cluster_namespace, slot, owner, version);
+    if (err == ErrorCode::ETCD_KEY_NOT_EXIST) {
+        return ErrorCode::OK;  // already gone; nothing to clean up
+    }
+    if (err != ErrorCode::OK) {
+        return err;
+    }
+    if (owner.primary_master_id != master_id) {
+        return ErrorCode::OK;  // now owned by another master; leave it
+    }
+    return DeleteSlotOwner(cluster_namespace, slot);
+}
+
+ErrorCode EtcdViewStore::LoadAllSlotOwners(const std::string& cluster_namespace,
+                                           std::vector<SlotOwner>& out,
+                                           ViewVersionId& version) {
+    out.clear();
+    const std::string prefix = KvViewPrefix(cluster_namespace);
+    const std::string end = PrefixEnd(prefix);
+    std::string json;
+    ErrorCode err = EtcdHelper::GetRangeAsJson(prefix.data(), prefix.size(),
+                                               end.data(), end.size(),
+                                               /*limit=*/0, json, version);
+    if (err != ErrorCode::OK) {
+        return err;
+    }
+
+    std::vector<std::pair<std::string, std::string>> kvs;
+    err = ParseRangeJson(json, kvs);
+    if (err != ErrorCode::OK) {
+        return err;
+    }
+
+    out.reserve(kvs.size());
+    for (const auto& kv : kvs) {
+        SlotOwner owner;
+        err = DeserializeSlotOwner(kv.second, owner);
+        if (err != ErrorCode::OK) {
+            return err;
+        }
+        out.push_back(std::move(owner));
+    }
+    return ErrorCode::OK;
+}
+
+// ---- Segment view (reserved) ----
+
+ErrorCode EtcdViewStore::LoadSegmentOwner(const std::string& cluster_namespace,
+                                          const std::string& segment_id,
+                                          SegmentOwner& out,
+                                          ViewVersionId& version) {
+    const std::string key = SegmentOwnerKey(cluster_namespace, segment_id);
+    std::string value;
+    ErrorCode err = EtcdHelper::Get(key.data(), key.size(), value, version);
+    if (err != ErrorCode::OK) {
+        return err;
+    }
+    return DeserializeSegmentOwner(value, out);
+}
+
+ErrorCode EtcdViewStore::SaveSegmentOwner(const std::string& cluster_namespace,
+                                          const SegmentOwner& owner) {
+    const std::string key =
+        SegmentOwnerKey(cluster_namespace, owner.segment_id);
+    std::string value;
+    ErrorCode err = SerializeSegmentOwner(owner, value);
+    if (err != ErrorCode::OK) {
+        return err;
+    }
+    return EtcdHelper::Put(key.data(), key.size(), value.data(), value.size());
+}
+
+ErrorCode EtcdViewStore::SaveSegmentOwnerWithLease(
+    const std::string& cluster_namespace, const SegmentOwner& owner,
+    EtcdLeaseId lease_id) {
+    const std::string key =
+        SegmentOwnerKey(cluster_namespace, owner.segment_id);
+    std::string value;
+    ErrorCode err = SerializeSegmentOwner(owner, value);
+    if (err != ErrorCode::OK) {
+        return err;
+    }
+    return EtcdHelper::PutWithLease(key.data(), key.size(), value.data(),
+                                    value.size(), lease_id);
+}
+
+ErrorCode EtcdViewStore::DeleteSegmentOwner(
+    const std::string& cluster_namespace, const std::string& segment_id) {
+    const std::string key = SegmentOwnerKey(cluster_namespace, segment_id);
+    const std::string end = PrefixEnd(key);
+    return EtcdHelper::DeleteRange(key.data(), key.size(), end.data(),
+                                   end.size());
+}
+
+ErrorCode EtcdViewStore::LoadAllSegmentOwners(
+    const std::string& cluster_namespace, std::vector<SegmentOwner>& out,
+    ViewVersionId& version) {
+    out.clear();
+    const std::string prefix = SegmentViewPrefix(cluster_namespace);
+    const std::string end = PrefixEnd(prefix);
+    std::string json;
+    ErrorCode err = EtcdHelper::GetRangeAsJson(prefix.data(), prefix.size(),
+                                               end.data(), end.size(),
+                                               /*limit=*/0, json, version);
+    if (err != ErrorCode::OK) {
+        return err;
+    }
+
+    std::vector<std::pair<std::string, std::string>> kvs;
+    err = ParseRangeJson(json, kvs);
+    if (err != ErrorCode::OK) {
+        return err;
+    }
+
+    out.reserve(kvs.size());
+    for (const auto& kv : kvs) {
+        SegmentOwner owner;
+        err = DeserializeSegmentOwner(kv.second, owner);
+        if (err != ErrorCode::OK) {
+            return err;
+        }
+        out.push_back(std::move(owner));
+    }
+    return ErrorCode::OK;
+}
+
+// ---- Master registration ----
+
+ErrorCode EtcdViewStore::RegisterMaster(const std::string& cluster_namespace,
+                                        const MasterRegistration& reg,
+                                        EtcdLeaseId lease_id) {
+    const std::string key =
+        MasterRegistrationKey(cluster_namespace, reg.master_id);
+    std::string value;
+    ErrorCode err = SerializeMasterRegistration(reg, value);
+    if (err != ErrorCode::OK) {
+        return err;
+    }
+    return EtcdHelper::PutWithLease(key.data(), key.size(), value.data(),
+                                    value.size(), lease_id);
+}
+
+ErrorCode EtcdViewStore::UpdateMasterRole(const std::string& cluster_namespace,
+                                          const std::string& master_id,
+                                          MasterRole role,
+                                          EtcdLeaseId lease_id) {
+    const std::string key = MasterRegistrationKey(cluster_namespace, master_id);
+
+    MasterRegistration reg;
+    ViewVersionId version = 0;
+    std::string existing;
+    ErrorCode err =
+        EtcdHelper::Get(key.data(), key.size(), existing, version);
+    if (err == ErrorCode::OK) {
+        err = DeserializeMasterRegistration(existing, reg);
+        if (err != ErrorCode::OK) {
+            return err;
+        }
+    }
+    // On read failure (e.g. key missing) fall back to a minimal registration;
+    // the caller only flips role on a previously-registered master, so this
+    // path is defensive and preserves liveness via the lease.
+    reg.master_id = master_id;
+    reg.role = static_cast<int32_t>(role);
+
+    std::string value;
+    err = SerializeMasterRegistration(reg, value);
+    if (err != ErrorCode::OK) {
+        return err;
+    }
+    return EtcdHelper::PutWithLease(key.data(), key.size(), value.data(),
+                                    value.size(), lease_id);
+}
+
+ErrorCode EtcdViewStore::LoadAllMasters(
+    const std::string& cluster_namespace, std::vector<MasterRegistration>& out,
+    ViewVersionId& version) {
+    out.clear();
+    const std::string prefix = MasterRegistrationPrefix(cluster_namespace);
+    const std::string end = PrefixEnd(prefix);
+    std::string json;
+    ErrorCode err = EtcdHelper::GetRangeAsJson(prefix.data(), prefix.size(),
+                                               end.data(), end.size(),
+                                               /*limit=*/0, json, version);
+    if (err != ErrorCode::OK) {
+        return err;
+    }
+
+    std::vector<std::pair<std::string, std::string>> kvs;
+    err = ParseRangeJson(json, kvs);
+    if (err != ErrorCode::OK) {
+        return err;
+    }
+
+    out.reserve(kvs.size());
+    for (const auto& kv : kvs) {
+        MasterRegistration reg;
+        err = DeserializeMasterRegistration(kv.second, reg);
+        if (err != ErrorCode::OK) {
+            return err;
+        }
+        out.push_back(std::move(reg));
+    }
+    return ErrorCode::OK;
+}
+
+// ---- Snapshots ----
+
+ErrorCode EtcdViewStore::SaveKvViewSnapshot(const std::string& cluster_namespace,
+                                            const KvViewSnapshot& snapshot) {
+    const std::string key = KvViewSnapshotKey(cluster_namespace);
+    std::string value;
+    ErrorCode err = SerializeKvViewSnapshot(snapshot, value);
+    if (err != ErrorCode::OK) {
+        return err;
+    }
+    return EtcdHelper::Put(key.data(), key.size(), value.data(), value.size());
+}
+
+ErrorCode EtcdViewStore::SaveSegmentViewSnapshot(
+    const std::string& cluster_namespace, const SegmentViewSnapshot& snapshot) {
+    const std::string key = SegmentViewSnapshotKey(cluster_namespace);
+    std::string value;
+    ErrorCode err = SerializeSegmentViewSnapshot(snapshot, value);
+    if (err != ErrorCode::OK) {
+        return err;
+    }
+    return EtcdHelper::Put(key.data(), key.size(), value.data(), value.size());
+}
+
+namespace {
+// Content-dedup cache for snapshot writes. `generated_at_ms` changes on every
+// build, so a naive "write every sync cycle" put a ~MB value per cycle per
+// master and exhausted the etcd backend quota with MVCC revisions. Skip the
+// write when the owners content is unchanged since this process last wrote it.
+// Process-local: after a content change each master writes once, which is
+// acceptable (two puts per change instead of one).
+std::mutex g_snapshot_dedup_mutex;
+std::unordered_map<std::string, std::string> g_last_snapshot_content;
+}  // namespace
+
+ErrorCode EtcdViewStore::BuildAndSaveKvViewSnapshot(
+    const std::string& cluster_namespace, ViewVersionId& version) {
+    std::vector<SlotOwner> owners;
+    ErrorCode err = LoadAllSlotOwners(cluster_namespace, owners, version);
+    if (err != ErrorCode::OK) {
+        return err;
+    }
+
+    // Fingerprint over the owners only (exclude version/generated_at so the
+    // steady state produces a stable string).
+    std::string content;
+    try {
+        struct_json::to_json(owners, content);
+    } catch (const std::exception& e) {
+        LOG(WARNING) << "BuildAndSaveKvViewSnapshot: fingerprint failed: "
+                     << e.what();
+        content.clear();
+    }
+    {
+        std::lock_guard<std::mutex> lock(g_snapshot_dedup_mutex);
+        auto& last = g_last_snapshot_content["kv:" + cluster_namespace];
+        if (!content.empty() && last == content) {
+            return ErrorCode::OK;  // unchanged, skip the etcd write
+        }
+        last = content;
+    }
+
+    KvViewSnapshot snapshot;
+    snapshot.version = version;
+    snapshot.generated_at_ms =
+        std::chrono::duration_cast<std::chrono::milliseconds>(
+            std::chrono::system_clock::now().time_since_epoch())
+            .count();
+    snapshot.slot_owners = std::move(owners);
+    err = SaveKvViewSnapshot(cluster_namespace, snapshot);
+    if (err != ErrorCode::OK) {
+        // 写失败时回滚缓存，下轮重试完整写入。
+        std::lock_guard<std::mutex> lock(g_snapshot_dedup_mutex);
+        g_last_snapshot_content.erase("kv:" + cluster_namespace);
+    }
+    return err;
+}
+
+ErrorCode EtcdViewStore::BuildAndSaveSegmentViewSnapshot(
+    const std::string& cluster_namespace, ViewVersionId& version) {
+    std::vector<SegmentOwner> owners;
+    ErrorCode err = LoadAllSegmentOwners(cluster_namespace, owners, version);
+    if (err != ErrorCode::OK) {
+        return err;
+    }
+
+    std::string content;
+    try {
+        struct_json::to_json(owners, content);
+    } catch (const std::exception& e) {
+        LOG(WARNING) << "BuildAndSaveSegmentViewSnapshot: fingerprint failed: "
+                     << e.what();
+        content.clear();
+    }
+    {
+        std::lock_guard<std::mutex> lock(g_snapshot_dedup_mutex);
+        auto& last = g_last_snapshot_content["segment:" + cluster_namespace];
+        if (!content.empty() && last == content) {
+            return ErrorCode::OK;  // unchanged, skip the etcd write
+        }
+        last = content;
+    }
+
+    SegmentViewSnapshot snapshot;
+    snapshot.version = version;
+    snapshot.generated_at_ms =
+        std::chrono::duration_cast<std::chrono::milliseconds>(
+            std::chrono::system_clock::now().time_since_epoch())
+            .count();
+    snapshot.segment_owners = std::move(owners);
+    err = SaveSegmentViewSnapshot(cluster_namespace, snapshot);
+    if (err != ErrorCode::OK) {
+        std::lock_guard<std::mutex> lock(g_snapshot_dedup_mutex);
+        g_last_snapshot_content.erase("segment:" + cluster_namespace);
+    }
+    return err;
+}
+
+// ---- Watch ----
+
+ErrorCode EtcdViewStore::WatchKvView(const std::string& cluster_namespace,
+                                     ViewVersionId start_revision, void* ctx,
+                                     WatchCallback cb) {
+    const std::string prefix = KvViewPrefix(cluster_namespace);
+    return EtcdHelper::WatchWithPrefixFromRevision(prefix.data(), prefix.size(),
+                                                   start_revision, ctx, cb);
+}
+
+ErrorCode EtcdViewStore::CancelWatchKvView(const std::string& cluster_namespace) {
+    const std::string prefix = KvViewPrefix(cluster_namespace);
+    return EtcdHelper::CancelWatchWithPrefix(prefix.data(), prefix.size());
+}
+
+ErrorCode EtcdViewStore::WaitWatchKvViewStopped(
+    const std::string& cluster_namespace, int timeout_ms) {
+    const std::string prefix = KvViewPrefix(cluster_namespace);
+    return EtcdHelper::WaitWatchWithPrefixStopped(prefix.data(), prefix.size(),
+                                                  timeout_ms);
+}
+
+// ---- Master membership watch ----
+
+ErrorCode EtcdViewStore::WatchMasters(const std::string& cluster_namespace,
+                                      ViewVersionId start_revision, void* ctx,
+                                      WatchCallback cb) {
+    const std::string prefix = MasterRegistrationPrefix(cluster_namespace);
+    return EtcdHelper::WatchWithPrefixFromRevision(prefix.data(), prefix.size(),
+                                                   start_revision, ctx, cb);
+}
+
+ErrorCode EtcdViewStore::CancelWatchMasters(
+    const std::string& cluster_namespace) {
+    const std::string prefix = MasterRegistrationPrefix(cluster_namespace);
+    return EtcdHelper::CancelWatchWithPrefix(prefix.data(), prefix.size());
+}
+
+ErrorCode EtcdViewStore::WaitWatchMastersStopped(
+    const std::string& cluster_namespace, int timeout_ms) {
+    const std::string prefix = MasterRegistrationPrefix(cluster_namespace);
+    return EtcdHelper::WaitWatchWithPrefixStopped(prefix.data(), prefix.size(),
+                                                  timeout_ms);
+}
+
+}  // namespace cvm
+}  // namespace mooncake
diff --git a/mooncake-store/src/cvm/inter_master_rpc.cpp b/mooncake-store/src/cvm/inter_master_rpc.cpp
new file mode 100644
index 0000000000..55b9d54090
--- /dev/null
+++ b/mooncake-store/src/cvm/inter_master_rpc.cpp
@@ -0,0 +1,429 @@
+#include "cvm/inter_master_rpc.h"
+
+#include <algorithm>
+#include <chrono>
+
+#include <async_simple/coro/Lazy.h>
+#include <async_simple/coro/SyncAwait.h>
+#include <glog/logging.h>
+
+#include "cvm/etcd_view_store.h"
+#include "master_client.h"
+#include "rpc_service.h"
+#include "store_rpc_client_io_context.h"
+
+namespace mooncake {
+namespace cvm {
+
+namespace {
+
+std::string JoinStrings(const std::vector<std::string>& parts) {
+    std::string out;
+    for (const auto& p : parts) {
+        if (!out.empty()) {
+            out += ", ";
+        }
+        out += p;
+    }
+    return out;
+}
+
+}  // namespace
+
+InterMasterRpcClient::InterMasterRpcClient()
+    : pool_accessor_(GetStoreRpcClientIoContextPool(),
+                     detail::MakeMasterRpcClientPoolConfig()) {}
+
+InterMasterRpcClient::~InterMasterRpcClient() { Stop(); }
+
+ErrorCode InterMasterRpcClient::Start(const std::string& cluster_namespace,
+                                      const std::string& self_master_id) {
+    if (running_.load()) {
+        return ErrorCode::OK;
+    }
+    if (cluster_namespace.empty()) {
+        LOG(WARNING)
+            << "InterMasterRpcClient: no cluster namespace, refresh thread "
+               "not started (manual member updates only)";
+        return ErrorCode::INVALID_PARAMS;
+    }
+    cluster_namespace_ = cluster_namespace;
+    self_master_id_ = self_master_id;
+    running_.store(true);
+    refresh_thread_ = std::thread([this] { RefreshLoop(); });
+    free_thread_ = std::thread([this] { FreeLoop(); });
+    LOG(INFO) << "InterMasterRpcClient started: cluster_namespace="
+              << cluster_namespace_ << ", self=" << self_master_id_
+              << ", refresh_interval_ms=" << kRefreshIntervalMs;
+    return ErrorCode::OK;
+}
+
+void InterMasterRpcClient::Stop() {
+    if (!running_.exchange(false)) {
+        return;
+    }
+    {
+        std::lock_guard<std::mutex> lock(cv_mutex_);
+        cv_.notify_all();
+    }
+    {
+        std::lock_guard<std::mutex> lock(free_queue_mutex_);
+        free_cv_.notify_all();
+    }
+    if (refresh_thread_.joinable()) {
+        refresh_thread_.join();
+    }
+    if (free_thread_.joinable()) {
+        free_thread_.join();
+    }
+    LOG(INFO) << "InterMasterRpcClient stopped";
+}
+
+void InterMasterRpcClient::UpdateMembers(
+    const std::vector<MasterRegistration>& members) {
+    std::unordered_map<std::string, std::string> next;
+    next.reserve(members.size());
+    for (const auto& m : members) {
+        if (m.master_id.empty() || m.address.empty()) {
+            continue;
+        }
+        next[m.master_id] = m.address;
+    }
+
+    std::lock_guard<std::mutex> lock(members_mutex_);
+    if (next != members_) {
+        std::vector<std::string> joined, left;
+        for (const auto& [id, addr] : next) {
+            if (members_.find(id) == members_.end()) {
+                joined.push_back(id + "@" + addr);
+            }
+        }
+        for (const auto& [id, addr] : members_) {
+            if (next.find(id) == next.end()) {
+                left.push_back(id + "@" + addr);
+            }
+        }
+        members_ = std::move(next);
+        LOG(INFO) << "InterMasterRpc members updated: total=" << members_.size()
+                  << ", joined=[" << JoinStrings(joined)
+                  << "], left=[" << JoinStrings(left) << "]";
+    }
+}
+
+std::vector<MasterRegistration> InterMasterRpcClient::GetMembers() const {
+    std::lock_guard<std::mutex> lock(members_mutex_);
+    std::vector<MasterRegistration> out;
+    out.reserve(members_.size());
+    for (const auto& [id, addr] : members_) {
+        MasterRegistration reg;
+        reg.master_id = id;
+        reg.address = addr;
+        out.push_back(std::move(reg));
+    }
+    return out;
+}
+
+std::optional<std::string> InterMasterRpcClient::ResolveAddress(
+    const std::string& master_id) const {
+    std::lock_guard<std::mutex> lock(members_mutex_);
+    auto it = members_.find(master_id);
+    if (it == members_.end()) {
+        return std::nullopt;
+    }
+    return it->second;
+}
+
+tl::expected<InterMasterHandshakeResponse, ErrorCode>
+InterMasterRpcClient::Handshake(const std::string& master_id) {
+    auto address = ResolveAddress(master_id);
+    if (!address) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    return invoke_rpc<&WrappedMasterService::InterMasterHandshake,
+                      InterMasterHandshakeResponse>(*address);
+}
+
+size_t InterMasterRpcClient::HandshakeAll(const std::string& self_master_id) {
+    auto members = GetMembers();
+    size_t ok_count = 0;
+    for (const auto& m : members) {
+        if (m.master_id == self_master_id) {
+            continue;
+        }
+        auto result = Handshake(m.master_id);
+        if (result.has_value()) {
+            ++ok_count;
+            LOG(INFO) << "InterMasterRpc handshake ok: peer="
+                      << result.value().master_id
+                      << " address=" << m.address
+                      << " lease_id=" << result.value().lease_id
+                      << " owned_slots=" << result.value().owned_slot_count
+                      << " version=" << result.value().version;
+        } else {
+            LOG(WARNING) << "InterMasterRpc handshake failed: peer="
+                         << m.master_id << " address=" << m.address
+                         << " error=" << toString(result.error());
+        }
+    }
+    return ok_count;
+}
+
+tl::expected<std::vector<Replica::Descriptor>, ErrorCode>
+InterMasterRpcClient::AllocateReplicas(
+    const std::string& master_id, const std::string& tenant_id,
+    const std::string& key, uint64_t slice_length, uint64_t replica_num,
+    const std::vector<std::string>& preferred_segments) {
+    auto address = ResolveAddress(master_id);
+    if (!address) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    return invoke_rpc<&WrappedMasterService::InterMasterAllocateReplicas,
+                      std::vector<Replica::Descriptor>>(
+        *address, tenant_id, key, slice_length, replica_num,
+        preferred_segments);
+}
+
+tl::expected<bool, ErrorCode> InterMasterRpcClient::FreeReplicas(
+    const std::string& master_id, const std::string& tenant_id,
+    const std::string& key) {
+    auto address = ResolveAddress(master_id);
+    if (!address) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    return invoke_rpc<&WrappedMasterService::InterMasterFreeReplicas, bool>(
+        *address, tenant_id, key);
+}
+
+tl::expected<GetReplicaListResponse, ErrorCode>
+InterMasterRpcClient::GetReplicaList(const std::string& master_id,
+                                     const std::string& key,
+                                     const std::string& tenant_id) {
+    auto address = ResolveAddress(master_id);
+    if (!address) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    return invoke_rpc<&WrappedMasterService::InterMasterGetReplicaList,
+                      GetReplicaListResponse>(*address, key, tenant_id);
+}
+
+std::vector<tl::expected<GetReplicaListResponse, ErrorCode>>
+InterMasterRpcClient::BatchGetReplicaList(
+    const std::string& master_id, const std::vector<std::string>& keys,
+    const std::string& tenant_id) {
+    auto address = ResolveAddress(master_id);
+    if (!address) {
+        std::vector<tl::expected<GetReplicaListResponse, ErrorCode>> errs(
+            keys.size(), tl::make_unexpected(ErrorCode::INVALID_PARAMS));
+        return errs;
+    }
+    // RPC 返回值本身已是逐 key 的 expected 向量；外层只关心传输层失败。
+    auto result = invoke_rpc<
+        &WrappedMasterService::InterMasterBatchGetReplicaList,
+        std::vector<tl::expected<GetReplicaListResponse, ErrorCode>>>(
+        *address, keys, tenant_id);
+    if (!result.has_value()) {
+        return std::vector<tl::expected<GetReplicaListResponse, ErrorCode>>(
+            keys.size(), tl::make_unexpected(result.error()));
+    }
+    return std::move(result.value());
+}
+
+tl::expected<std::vector<Replica::Descriptor>, ErrorCode>
+InterMasterRpcClient::PutStart(const std::string& master_id,
+                               const UUID& client_id, const std::string& key,
+                               const std::string& tenant_id,
+                               uint64_t slice_length,
+                               const ReplicateConfig& config) {
+    auto address = ResolveAddress(master_id);
+    if (!address) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    return invoke_rpc<&WrappedMasterService::InterMasterPutStart,
+                      std::vector<Replica::Descriptor>>(
+        *address, client_id, key, tenant_id, slice_length, config);
+}
+
+tl::expected<std::vector<Replica::Descriptor>, ErrorCode>
+InterMasterRpcClient::UpsertStart(const std::string& master_id,
+                                  const UUID& client_id, const std::string& key,
+                                  const std::string& tenant_id,
+                                  uint64_t slice_length,
+                                  const ReplicateConfig& config) {
+    auto address = ResolveAddress(master_id);
+    if (!address) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    return invoke_rpc<&WrappedMasterService::InterMasterUpsertStart,
+                      std::vector<Replica::Descriptor>>(
+        *address, client_id, key, tenant_id, slice_length, config);
+}
+
+void InterMasterRpcClient::EnqueueBroadcastFree(const std::string& tenant_id,
+                                                 const std::string& key) {
+    if (!running_.load()) {
+        VLOG(1) << "InterMasterRpc: broadcast free dropped (not running): key="
+                << key;
+        return;
+    }
+    {
+        std::lock_guard<std::mutex> lock(free_queue_mutex_);
+        // Bound the queue so a free storm cannot grow it unboundedly; the
+        // entries cover handle reclamation, so dropping only leaks until the
+        // segment is unmounted.
+        if (free_queue_.size() >= kMaxBroadcastFreeQueueSize) {
+            LOG(WARNING) << "InterMasterRpc: broadcast free queue full ("
+                         << free_queue_.size() << "), dropping key=" << key;
+            return;
+        }
+        free_queue_.push_back(FreeTask{tenant_id, key, 0});
+    }
+    free_cv_.notify_one();
+}
+
+void InterMasterRpcClient::FreeLoop() {
+    constexpr int kMaxFreeAttempts = 20;  // ~10s when members not yet known
+    while (running_.load()) {
+        FreeTask task;
+        {
+            std::unique_lock<std::mutex> lock(free_queue_mutex_);
+            free_cv_.wait(lock, [this] {
+                return !running_.load() || !free_queue_.empty();
+            });
+            if (!running_.load()) {
+                return;
+            }
+            task = std::move(free_queue_.front());
+            free_queue_.pop_front();
+        }
+
+        auto members = GetMembers();
+        if (members.empty()) {
+            // Member table not populated yet (startup race): retry after a
+            // short delay, bounded by kMaxFreeAttempts.
+            if (++task.attempts < kMaxFreeAttempts) {
+                {
+                    std::lock_guard<std::mutex> lock(free_queue_mutex_);
+                    free_queue_.push_back(std::move(task));
+                }
+                std::this_thread::sleep_for(std::chrono::milliseconds(500));
+            } else {
+                LOG(WARNING)
+                    << "InterMasterRpc: broadcast free gave up (no members): "
+                    << "key=" << task.key;
+            }
+            continue;
+        }
+
+        for (const auto& member : members) {
+            if (member.master_id.empty() || member.master_id == self_master_id_) {
+                continue;
+            }
+            auto result = FreeReplicas(member.master_id, task.tenant_id,
+                                       task.key);
+            // Not-found (false) is the common case for non-owner peers.
+            if (result.has_value() && result.value()) {
+                LOG(INFO) << "InterMasterRpc: freed remote replicas on "
+                         << member.master_id << " for key=" << task.key;
+            } else if (!result.has_value()) {
+                VLOG(1) << "InterMasterRpc: free failed on "
+                        << member.master_id << " for key=" << task.key
+                        << " error=" << toString(result.error());
+            }
+        }
+    }
+}
+
+void InterMasterRpcClient::RefreshLoop() {
+    while (running_.load()) {
+        std::vector<MasterRegistration> masters;
+        ViewVersionId version = 0;
+        ErrorCode rc = EtcdViewStore::LoadAllMasters(cluster_namespace_,
+                                                    masters, version);
+        if (rc == ErrorCode::OK) {
+            // Snapshot the previous table to detect newly joined peers.
+            std::unordered_map<std::string, std::string> previous;
+            {
+                std::lock_guard<std::mutex> lock(members_mutex_);
+                previous = members_;
+            }
+            UpdateMembers(masters);
+
+            // Handshake newly joined peers: verifies the inter-master
+            // channel and warms up the connection pools.
+            std::vector<std::string> joined;
+            for (const auto& m : masters) {
+                if (m.master_id.empty() || m.master_id == self_master_id_) {
+                    continue;
+                }
+                if (previous.find(m.master_id) == previous.end()) {
+                    joined.push_back(m.master_id);
+                }
+            }
+            for (const auto& peer_id : joined) {
+                auto result = Handshake(peer_id);
+                if (result.has_value()) {
+                    LOG(INFO) << "InterMasterRpc handshake ok (new peer): peer="
+                              << result.value().master_id
+                              << " lease_id=" << result.value().lease_id
+                              << " owned_slots="
+                              << result.value().owned_slot_count
+                              << " version=" << result.value().version;
+                } else {
+                    LOG(WARNING)
+                        << "InterMasterRpc handshake failed (new peer): peer="
+                        << peer_id << " error=" << toString(result.error());
+                }
+            }
+        } else {
+            LOG(WARNING) << "InterMasterRpc: failed to load masters from "
+                            "etcd: "
+                         << toString(rc);
+        }
+        std::unique_lock<std::mutex> lock(cv_mutex_);
+        cv_.wait_for(lock, std::chrono::milliseconds(kRefreshIntervalMs),
+                     [this] { return !running_.load(); });
+    }
+}
+
+template <auto ServiceMethod, typename ReturnType, typename... Args>
+tl::expected<ReturnType, ErrorCode> InterMasterRpcClient::invoke_rpc(
+    const std::string& address, Args&&... args) {
+    auto pool = pool_accessor_.GetOrCreateClientPool(address);
+    auto rpc_result = async_simple::coro::syncAwait(
+        [&]() -> async_simple::coro::Lazy<
+                   tl::expected<ReturnType, ErrorCode>> {
+            auto ret = co_await pool->send_request(
+                [&](coro_io::client_reuse_hint,
+                    coro_rpc::coro_rpc_client& client) {
+                    return client.send_request<ServiceMethod>(
+                        std::forward<Args>(args)...);
+                });
+            if (!ret.has_value()) {
+                LOG(ERROR) << "InterMasterRpc: no available client for "
+                           << address;
+                co_return tl::make_unexpected(ErrorCode::RPC_FAIL);
+            }
+            auto result = co_await std::move(ret.value());
+            if (!result) {
+                if (result.error().code == coro_rpc::errc::timed_out) {
+                    co_return tl::make_unexpected(ErrorCode::RPC_TIMEOUT);
+                }
+                LOG(ERROR) << "InterMasterRpc call failed on " << address
+                           << ": " << result.error().msg;
+                co_return tl::make_unexpected(ErrorCode::RPC_FAIL);
+            }
+            if constexpr (std::is_void_v<ReturnType>) {
+                result->result();
+                co_return tl::expected<ReturnType, ErrorCode>{};
+            } else {
+                co_return result->result();
+            }
+        }());
+    return rpc_result;
+}
+
+// Explicit instantiation is not required: invoke_rpc is only used within
+// this translation unit (Handshake). Future forwarding methods live here too.
+
+}  // namespace cvm
+}  // namespace mooncake
diff --git a/mooncake-store/src/cvm/slot_migrator.cpp b/mooncake-store/src/cvm/slot_migrator.cpp
new file mode 100644
index 0000000000..38b34fd525
--- /dev/null
+++ b/mooncake-store/src/cvm/slot_migrator.cpp
@@ -0,0 +1,262 @@
+#include "cvm/slot_migrator.h"
+
+#include <algorithm>
+#include <iterator>
+#include <unordered_map>
+#include <utility>
+
+#include <glog/logging.h>
+
+#include "cvm/etcd_view_store.h"
+
+namespace mooncake {
+namespace cvm {
+
+SlotMigrator::SlotMigrator(Config config) : config_(std::move(config)) {}
+
+ErrorCode SlotMigrator::PublishMigrating(uint16_t slot) {
+    SlotOwner owner;
+    owner.slot = slot;
+    owner.primary_master_id = config_.master_id;
+    owner.state = static_cast<int32_t>(SlotState::kMigrating);
+    owner.migrating_to_master_id = config_.master_id;
+
+    if (config_.lease_id != 0) {
+        return EtcdViewStore::SaveSlotOwnerWithLease(config_.cluster_namespace,
+                                                     owner, config_.lease_id);
+    }
+    return EtcdViewStore::SaveSlotOwner(config_.cluster_namespace, owner);
+}
+
+ErrorCode SlotMigrator::PublishStable(uint16_t slot) {
+    SlotOwner owner;
+    owner.slot = slot;
+    owner.primary_master_id = config_.master_id;
+    owner.state = static_cast<int32_t>(SlotState::kStable);
+    // migrating_to_master_id 留空。
+
+    if (config_.lease_id != 0) {
+        return EtcdViewStore::SaveSlotOwnerWithLease(config_.cluster_namespace,
+                                                     owner, config_.lease_id);
+    }
+    return EtcdViewStore::SaveSlotOwner(config_.cluster_namespace, owner);
+}
+
+ErrorCode SlotMigrator::Reconcile(const std::vector<uint16_t>& owned_slots) {
+    std::vector<uint16_t> cur = owned_slots;
+    std::vector<uint16_t> prev = last_owned_slots_;
+    std::sort(cur.begin(), cur.end());
+    std::sort(prev.begin(), prev.end());
+
+    std::vector<uint16_t> gained;
+    std::vector<uint16_t> released;
+    std::set_difference(cur.begin(), cur.end(), prev.begin(), prev.end(),
+                        std::back_inserter(gained));
+    std::set_difference(prev.begin(), prev.end(), cur.begin(), cur.end(),
+                        std::back_inserter(released));
+
+    ErrorCode last_err = ErrorCode::OK;
+
+    // 释放：先回调清理元数据，再条件删除残留记录（确认仍指向本机才删）。
+    for (uint16_t slot : released) {
+        if (on_release_) {
+            on_release_(slot);
+        }
+        ErrorCode err = EtcdViewStore::DeleteSlotOwnerIfOwnedBy(
+            config_.cluster_namespace, slot, config_.master_id);
+        if (err != ErrorCode::OK) {
+            LOG(WARNING) << "SlotMigrator release slot " << slot
+                         << " failed: " << err;
+            last_err = err;
+        }
+    }
+    // 释放成功的聚合记录：仅在 owned 集合变化时打印一条，便于确认交接完成。
+    if (!released.empty()) {
+        LOG(INFO) << "SlotMigrator released " << released.size()
+                  << " slot(s), master_id=" << config_.master_id;
+    }
+
+    // 获得：原语义为 kMigrating -> on_acquire -> kStable 两段式交接。
+    // fencing：写入前检查 etcd 中现 owner。记录存在即说明原 owner 的
+    // lease 仍然有效（slot key 附着在其 lease 上，lease 过期 etcd 会自动
+    // 删除记录）——此时绝不抢夺，避免两个 submaster 对同一 slot 反复
+    // 互相覆盖（slot 分布震荡不收敛的根因）。仅当记录已消失（原 owner
+    // 崩溃/lease 过期/主动释放）时才允许本机接管。
+    std::vector<uint16_t> fenced;
+
+    // 冷启动 / 大批量认领（gained 达到门槛）：走批量路径。一次范围读完成
+    // 全部 fencing（等价于逐 slot 点读，只是合并为一次往返），随后把「无
+    // 前任 owner」的 slot 直接批量写 kStable（跳过 kMigrating 占位——冷启动
+    // 并无交接对象，写一步足够），并把「仍被存活 peer 持有」的 slot 继续
+    // fenced 观察等待。将原来 16384*(1 读 + 2 写) ≈ 4.9 万次串行往返压缩为
+    // 1 次范围读 + 16384/128 ≈ 128 次批量事务写。小批量交接仍走逐 slot 路径。
+    constexpr size_t kBulkClaimThreshold = 64;
+    auto settle_per_slot = [&](const std::vector<uint16_t>& pending) {
+        for (uint16_t slot : pending) {
+            SlotOwner current;
+            ViewVersionId current_version = 0;
+            ErrorCode load_err =
+                EtcdViewStore::LoadSlotOwner(config_.cluster_namespace, slot,
+                                             current, current_version);
+            if (load_err == ErrorCode::OK &&
+                !current.primary_master_id.empty() &&
+                current.primary_master_id != config_.master_id) {
+                fenced.push_back(slot);
+                continue;
+            }
+            if (load_err != ErrorCode::OK &&
+                load_err != ErrorCode::ETCD_KEY_NOT_EXIST) {
+                // etcd 读取异常：保守跳过，待下轮重试，不做盲目覆盖。
+                fenced.push_back(slot);
+                last_err = load_err;
+                LOG(WARNING) << "SlotMigrator fence check slot " << slot
+                             << " failed: " << load_err
+                             << ", master_id=" << config_.master_id;
+                continue;
+            }
+
+            ErrorCode err = PublishMigrating(slot);
+            if (err != ErrorCode::OK) {
+                LOG(WARNING) << "SlotMigrator publish migrating slot " << slot
+                             << " failed: " << err;
+                last_err = err;
+                fenced.push_back(slot);  // 发布失败同样下轮重试
+                continue;
+            }
+            if (on_acquire_) {
+                on_acquire_(slot);
+            }
+            err = PublishStable(slot);
+            if (err != ErrorCode::OK) {
+                LOG(WARNING) << "SlotMigrator publish stable slot " << slot
+                             << " failed: " << err;
+                last_err = err;
+            }
+        }
+    };
+
+    if (gained.size() >= kBulkClaimThreshold) {
+        // ---- 批量路径：1 次范围读做 fence ----
+        std::vector<SlotOwner> all;
+        ViewVersionId range_version = 0;
+        ErrorCode range_err = EtcdViewStore::LoadAllSlotOwners(
+            config_.cluster_namespace, all, range_version);
+        if (range_err == ErrorCode::OK) {
+            std::unordered_map<uint16_t, std::string> owner_map;
+            owner_map.reserve(all.size());
+            for (const auto& o : all) {
+                owner_map.emplace(o.slot, o.primary_master_id);
+            }
+
+            std::vector<SlotOwner> claim;
+            claim.reserve(gained.size());
+            for (uint16_t slot : gained) {
+                auto it = owner_map.find(slot);
+                const bool live_other =
+                    (it != owner_map.end() && !it->second.empty() &&
+                     it->second != config_.master_id);
+                if (live_other) {
+                    fenced.push_back(slot);
+                    continue;
+                }
+                SlotOwner owner;
+                owner.slot = slot;
+                owner.primary_master_id = config_.master_id;
+                owner.state = static_cast<int32_t>(SlotState::kStable);
+                claim.push_back(owner);
+            }
+
+            for (const auto& o : claim) {
+                if (on_acquire_) {
+                    on_acquire_(o.slot);
+                }
+            }
+            if (!claim.empty()) {
+                ErrorCode err = EtcdViewStore::SaveSlotOwnersWithLease(
+                    config_.cluster_namespace, claim, config_.lease_id);
+                if (err != ErrorCode::OK) {
+                    LOG(WARNING) << "SlotMigrator bulk claim "
+                                 << claim.size() << " slot(s) failed: " << err
+                                 << ", master_id=" << config_.master_id;
+                    last_err = err;
+                    // 批量失败：整批视为 fenced，下轮重试，避免误认为已落
+                    // 盘而跳过 Reconcile。
+                    for (const auto& o : claim) {
+                        fenced.push_back(o.slot);
+                    }
+                }
+            }
+        } else {
+            // 范围读失败（etcd 异常）：保守退回逐 slot 路径，不盲目批量覆盖。
+            LOG(WARNING) << "SlotMigrator bulk fence read failed: " << range_err
+                         << ", falling back to per-slot, master_id="
+                         << config_.master_id;
+            last_err = range_err;
+            settle_per_slot(gained);
+        }
+    } else {
+        settle_per_slot(gained);
+    }
+    if (!gained.empty()) {
+        size_t acquired = gained.size();
+        if (acquired >= fenced.size()) {
+            acquired -= fenced.size();  // 仅统计真正落盘的 slot
+        } else {
+            acquired = 0;
+        }
+        if (acquired > 0) {
+            // 获得成功的聚合记录：确认所有权已全部落盘。
+            LOG(INFO) << "SlotMigrator acquired " << acquired
+                      << " slot(s), master_id=" << config_.master_id;
+        }
+        if (!fenced.empty()) {
+            // fencing / 写失败汇总：这些 slot 仍由其他存活 master 持有，或
+            // 本机写入失败，观察等待下轮重试后再接管。
+            LOG(INFO) << "SlotMigrator fenced/retry " << fenced.size()
+                      << " slot(s), master_id=" << config_.master_id;
+        }
+    }
+
+    // 不变 slot：幂等 reaffirm kStable，但仅作为低频安全网（每
+    // kReaffirmIntervalCycles 个周期一次）。slot key 附着在 lease 上，
+    // keepalive 持续保活即不过期；逐周期重写等值 value 只会线性堆积 etcd
+    // MVCC revision（曾以 ~3k put/s 的速率写满 backend 配额）。正常稳态
+    // 下 lease 存活即代表所有权持续有效，无需重写。
+    constexpr uint64_t kReaffirmIntervalCycles = 12;  // ~60s @ 5s heartbeat
+    const bool do_reaffirm = (++reconcile_cycles_ % kReaffirmIntervalCycles) == 0;
+    if (do_reaffirm) {
+        for (uint16_t slot : cur) {
+            // fenced slot（本周期被拦截/发布失败）不能 reaffirm：它仍归
+            // 其他存活 master 所有，重写会重新引发覆盖。
+            if (std::binary_search(fenced.begin(), fenced.end(), slot)) {
+                continue;
+            }
+            if (std::binary_search(gained.begin(), gained.end(), slot)) {
+                continue;
+            }
+            ErrorCode err = PublishStable(slot);
+            if (err != ErrorCode::OK) {
+                LOG(WARNING) << "SlotMigrator reaffirm slot " << slot
+                             << " failed: " << err;
+                last_err = err;
+            }
+        }
+    }
+
+    // last_owned_slots_ 只记录本周期真正发布成功的 slot；fenced slot 不计入，
+    // 下一周期它们重新进入 gained 集合，重新走 fence 检查 → 观察等待。
+    if (!fenced.empty()) {
+        std::sort(fenced.begin(), fenced.end());
+        std::vector<uint16_t> committed;
+        committed.reserve(cur.size() - fenced.size());
+        std::set_difference(cur.begin(), cur.end(), fenced.begin(),
+                            fenced.end(), std::back_inserter(committed));
+        last_owned_slots_ = std::move(committed);
+    } else {
+        last_owned_slots_ = std::move(cur);
+    }
+    return last_err;
+}
+
+}  // namespace cvm
+}  // namespace mooncake
diff --git a/mooncake-store/src/cvm/slot_owner_heartbeat.cpp b/mooncake-store/src/cvm/slot_owner_heartbeat.cpp
new file mode 100644
index 0000000000..d8d83eac65
--- /dev/null
+++ b/mooncake-store/src/cvm/slot_owner_heartbeat.cpp
@@ -0,0 +1,96 @@
+#include "cvm/slot_owner_heartbeat.h"
+
+#include <algorithm>
+#include <iterator>
+#include <utility>
+
+#include <glog/logging.h>
+
+#include "cvm/etcd_view_store.h"
+#include "cvm/slot_hash.h"
+
+namespace mooncake {
+namespace cvm {
+
+namespace {
+
+// Resolves the owned slot list from config. An empty `owned_slots` means the
+// submaster owns every logical slot (single-master mode).
+std::vector<uint16_t> ResolveOwnedSlots(const SlotOwnerHeartbeat::Config& cfg) {
+    if (!cfg.owned_slots.empty()) {
+        return cfg.owned_slots;
+    }
+    std::vector<uint16_t> slots;
+    slots.reserve(kSlotCount);
+    for (uint16_t slot = 0; slot < kSlotCount; ++slot) {
+        slots.push_back(slot);
+    }
+    return slots;
+}
+
+}  // namespace
+
+SlotOwnerHeartbeat::SlotOwnerHeartbeat(Config config)
+    : config_(std::move(config)),
+      owned_slots_(ResolveOwnedSlots(config_)),
+      migrator_(SlotMigrator::Config{config_.cluster_namespace,
+                                     config_.master_id,
+                                     config_.lease_id}) {
+    migrator_.SetOnAcquire(config_.on_slot_acquired);
+    migrator_.SetOnRelease(config_.on_slot_released);
+}
+
+SlotOwnerHeartbeat::~SlotOwnerHeartbeat() { Stop(); }
+
+ErrorCode SlotOwnerHeartbeat::Start() {
+    if (running_.load()) {
+        return ErrorCode::OK;
+    }
+    running_.store(true);
+    thread_ = std::thread([this]() { RunLoop(); });
+    return ErrorCode::OK;
+}
+
+void SlotOwnerHeartbeat::Stop() {
+    if (!running_.exchange(false)) {
+        return;
+    }
+    stop_cv_.notify_all();
+    if (thread_.joinable()) {
+        thread_.join();
+    }
+}
+
+ErrorCode SlotOwnerHeartbeat::PublishOnce() {
+    // Under dynamic partition the owned slot set is recomputed every publish so
+    // it follows cluster membership changes; otherwise use the static set.
+    std::vector<uint16_t> slots = owned_slots_;
+    if (config_.dynamic_slot_resolver) {
+        slots = config_.dynamic_slot_resolver();
+    }
+
+    // Delegate the per-slot writes to the SlotMigrator state machine: it
+    // publishes kMigrating -> kStable for newly-acquired slots, deletes
+    // released slots, and re-affirms unchanged slots.
+    ErrorCode err = migrator_.Reconcile(slots);
+    if (err != ErrorCode::OK) {
+        // Reconcile 内部已有逐 slot 失败 WARNING；这里补一条周期级汇总，
+        // 便于从心跳线程视角确认本轮发布未完全成功。
+        LOG(WARNING) << "SlotOwnerHeartbeat publish incomplete: master_id="
+                     << config_.master_id << " owned_slots=" << slots.size()
+                     << " err=" << err;
+    }
+    return err;
+}
+
+void SlotOwnerHeartbeat::RunLoop() {
+    while (running_.load()) {
+        (void)PublishOnce();
+        std::unique_lock<std::mutex> lock(stop_mutex_);
+        stop_cv_.wait_for(lock, config_.heartbeat_interval,
+                          [this] { return !running_.load(); });
+    }
+}
+
+}  // namespace cvm
+}  // namespace mooncake
diff --git a/mooncake-store/src/etcd_helper.cpp b/mooncake-store/src/etcd_helper.cpp
index 29cd832a08..4888d45ffe 100644
--- a/mooncake-store/src/etcd_helper.cpp
+++ b/mooncake-store/src/etcd_helper.cpp
@@ -71,8 +71,11 @@ ErrorCode EtcdHelper::Get(const char* key, const size_t key_size,
         EtcdStoreGetWrapper(const_cast<char*>(key), (int)key_size, &value_ptr,
                             &value_size, &revision_id, &err_msg);
     if (ret == -2) {
-        LOG(ERROR) << "key=" << std::string(key, key_size)
-                   << ", error=" << err_msg;
+        // Key-not-found is an expected outcome for existence probes (e.g.
+        // ImportSlotMetadata checking for a graceful export). Downgrade to
+        // VLOG to avoid ERROR-level spam for benign misses.
+        VLOG(1) << "key=" << std::string(key, key_size)
+                << ", error=" << err_msg;
         free(err_msg);
         return ErrorCode::ETCD_KEY_NOT_EXIST;
     }
@@ -151,8 +154,54 @@ ErrorCode EtcdHelper::BatchCreate(const std::vector<std::string>& keys,
     return ErrorCode::OK;
 }
 
+ErrorCode EtcdHelper::BatchPutWithLease(const std::vector<std::string>& keys,
+                                        const std::vector<std::string>& values,
+                                        EtcdLeaseId lease_id) {
+    if (keys.size() != values.size()) {
+        return ErrorCode::INVALID_PARAMS;
+    }
+    if (keys.empty()) {
+        return ErrorCode::OK;
+    }
+
+    std::vector<char*> c_keys;
+    std::vector<int> c_key_sizes;
+    std::vector<char*> c_values;
+    std::vector<int> c_value_sizes;
+    c_keys.reserve(keys.size());
+    c_key_sizes.reserve(keys.size());
+    c_values.reserve(values.size());
+    c_value_sizes.reserve(values.size());
+
+    for (const auto& key : keys) {
+        c_keys.push_back(const_cast<char*>(key.data()));
+        c_key_sizes.push_back(static_cast<int>(key.size()));
+    }
+    for (const auto& val : values) {
+        c_values.push_back(const_cast<char*>(val.data()));
+        c_value_sizes.push_back(static_cast<int>(val.size()));
+    }
+
+    char* err_msg = nullptr;
+    int ret = EtcdStoreBatchPutWithLeaseWrapper(
+        c_keys.data(), c_key_sizes.data(), c_values.data(), c_value_sizes.data(),
+        static_cast<int>(keys.size()), lease_id, &err_msg);
+    if (ret != 0) {
+        LOG(ERROR) << "BatchPutWithLease failed (count=" << keys.size()
+                   << ", lease=" << lease_id
+                   << "): " << (err_msg == nullptr ? "" : err_msg);
+        if (err_msg != nullptr) {
+            free(err_msg);
+        }
+        return ErrorCode::ETCD_OPERATION_ERROR;
+    }
+    return ErrorCode::OK;
+}
+
 ErrorCode EtcdHelper::TxnCompareAndPut(const std::vector<TxnCompare>& compares,
-                                       const std::vector<TxnPut>& puts) {
+                                       const std::vector<TxnPut>& puts,
+                                       const std::vector<std::string>&
+                                           delete_keys) {
     std::vector<char*> compare_keys;
     std::vector<int> compare_key_sizes;
     std::vector<int> compare_kinds;
@@ -187,6 +236,14 @@ ErrorCode EtcdHelper::TxnCompareAndPut(const std::vector<TxnCompare>& compares,
         put_values.push_back(const_cast<char*>(put.value.data()));
         put_value_sizes.push_back(static_cast<int>(put.value.size()));
     }
+    std::vector<char*> deletes;
+    std::vector<int> delete_sizes;
+    deletes.reserve(delete_keys.size());
+    delete_sizes.reserve(delete_keys.size());
+    for (const auto& key : delete_keys) {
+        deletes.push_back(const_cast<char*>(key.data()));
+        delete_sizes.push_back(static_cast<int>(key.size()));
+    }
 
     char* err_msg = nullptr;
     int ret = EtcdStoreTxnCompareAndPutWrapper(
@@ -194,7 +251,8 @@ ErrorCode EtcdHelper::TxnCompareAndPut(const std::vector<TxnCompare>& compares,
         compare_values.data(), compare_value_sizes.data(),
         static_cast<int>(compares.size()), put_keys.data(),
         put_key_sizes.data(), put_values.data(), put_value_sizes.data(),
-        static_cast<int>(puts.size()), &err_msg);
+        static_cast<int>(puts.size()), deletes.data(), delete_sizes.data(),
+        static_cast<int>(delete_keys.size()), &err_msg);
     if (ret == -2) {
         if (err_msg != nullptr) {
             free(err_msg);
@@ -537,6 +595,16 @@ ErrorCode EtcdHelper::BatchCreate(const std::vector<std::string>& keys,
     return ErrorCode::ETCD_OPERATION_ERROR;
 }
 
+ErrorCode EtcdHelper::BatchPutWithLease(const std::vector<std::string>& keys,
+                                        const std::vector<std::string>& values,
+                                        EtcdLeaseId lease_id) {
+    (void)keys;
+    (void)values;
+    (void)lease_id;
+    LOG(FATAL) << "Etcd is not enabled in compilation";
+    return ErrorCode::ETCD_OPERATION_ERROR;
+}
+
 ErrorCode EtcdHelper::GrantLease(int64_t lease_ttl, EtcdLeaseId& lease_id) {
     (void)lease_ttl;
     (void)lease_id;
@@ -617,9 +685,12 @@ ErrorCode EtcdHelper::Create(const char* key, const size_t key_size,
 }
 
 ErrorCode EtcdHelper::TxnCompareAndPut(const std::vector<TxnCompare>& compares,
-                                       const std::vector<TxnPut>& puts) {
+                                       const std::vector<TxnPut>& puts,
+                                       const std::vector<std::string>&
+                                           delete_keys) {
     (void)compares;
     (void)puts;
+    (void)delete_keys;
     LOG(FATAL) << "Etcd is not enabled in compilation";
     return ErrorCode::ETCD_OPERATION_ERROR;
 }
diff --git a/mooncake-store/src/ha/leadership/master_service_supervisor.cpp b/mooncake-store/src/ha/leadership/master_service_supervisor.cpp
index 4b94942e89..9a01f09266 100644
--- a/mooncake-store/src/ha/leadership/master_service_supervisor.cpp
+++ b/mooncake-store/src/ha/leadership/master_service_supervisor.cpp
@@ -2,17 +2,20 @@
 
 #include <atomic>
 #include <chrono>
+#include <condition_variable>
 #include <csignal>
 #include <cstdlib>
+#include <functional>
 #include <memory>
+#include <mutex>
 #include <optional>
+#include <string>
 #include <string_view>
 #include <thread>
 
 #include <glog/logging.h>
 #include <ylt/coro_rpc/coro_rpc_server.hpp>
 
-#include "ha/leadership/leader_coordinator_factory.h"
 #include "ha/leadership/leader_label_reconciler.h"
 #include "ha/master_metrics_reporter.h"
 #include "ha/standby_controller.h"
@@ -21,15 +24,18 @@
 #include "rpc_service.h"
 #include "types.h"
 
+#include "cvm/cvm_controller.h"
+#include "cvm/cvm_service_delegate.h"
+#include "cvm/etcd_view_store.h"
+#include "etcd_helper.h"
+
 namespace mooncake {
 namespace ha {
 
 namespace {
 
-constexpr auto kAcquireRetryInterval = std::chrono::seconds(1);
-constexpr auto kRenewCheckInterval = std::chrono::seconds(1);
-constexpr auto kSupervisorRetryInterval = std::chrono::seconds(1);
 constexpr auto kLabelReconcileRetryInterval = std::chrono::seconds(1);
+constexpr auto kSupervisorRetryInterval = std::chrono::seconds(1);
 constexpr char kLeaderLabelKey[] = "mooncake.io/store-role";
 constexpr char kLeaderLabelValue[] = "leader";
 
@@ -88,14 +94,6 @@ bool IsFatalHABackendError(ErrorCode err) {
            err == ErrorCode::UNAVAILABLE_IN_CURRENT_MODE;
 }
 
-void LogLeadershipReleaseWarning(std::string_view context, ErrorCode err) {
-    if (err == ErrorCode::OK) {
-        return;
-    }
-    LOG(WARNING) << "Failed to release leadership after " << context << ": "
-                 << toString(err);
-}
-
 bool HandleSupervisorError(std::string_view action, ErrorCode err,
                            HABackendType backend_type) {
     if (IsFatalHABackendError(err)) {
@@ -111,46 +109,6 @@ bool HandleSupervisorError(std::string_view action, ErrorCode err,
     return false;
 }
 
-bool HandleLeadershipPhaseError(std::string_view release_context,
-                                std::string_view action,
-                                LeaderCoordinator& coordinator,
-                                const LeadershipSession& session, ErrorCode err,
-                                HABackendType backend_type) {
-    LogLeadershipReleaseWarning(release_context,
-                                coordinator.ReleaseLeadership(session));
-    return HandleSupervisorError(action, err, backend_type);
-}
-
-tl::expected<bool, ErrorCode> WarmupLeadership(
-    LeaderCoordinator& coordinator, const LeadershipSession& session) {
-    const auto deadline = std::chrono::steady_clock::now() + session.lease_ttl;
-    const auto max_sleep_interval =
-        std::chrono::duration_cast<std::chrono::milliseconds>(
-            kRenewCheckInterval);
-
-    while (true) {
-        auto renewed = coordinator.RenewLeadership(session);
-        if (!renewed) {
-            return tl::make_unexpected(renewed.error());
-        }
-        if (!renewed.value()) {
-            return false;
-        }
-
-        const auto now = std::chrono::steady_clock::now();
-        if (now >= deadline) {
-            return true;
-        }
-
-        const auto remaining =
-            std::chrono::duration_cast<std::chrono::milliseconds>(deadline -
-                                                                  now);
-        const auto sleep_interval =
-            remaining < max_sleep_interval ? remaining : max_sleep_interval;
-        std::this_thread::sleep_for(sleep_interval);
-    }
-}
-
 void SetRuntimeState(MasterAdminServer& admin_server,
                      MasterRuntimeState state) {
     admin_server.SetRuntimeState(state);
@@ -174,40 +132,31 @@ void DeactivateServingState(MasterAdminServer& admin_server,
     label_reconciler.SetLeader(false);
 }
 
-void StopLeadershipMonitor(std::unique_ptr<LeadershipMonitorHandle>& monitor) {
-    if (!monitor) {
-        return;
-    }
-    monitor->Stop();
-    monitor.reset();
-}
-
 void UpdateObservedLeader(MasterAdminServer& admin_server,
                           StandbyController& standby_controller,
-                          const std::optional<MasterView>& leader_view) {
+                          const std::optional<MasterView>& leader_view,
+                          const MasterSources& sources) {
     admin_server.SetObservedLeader(leader_view);
-    standby_controller.UpdateObservedLeader(leader_view);
-}
-
-void ApplyCurrentView(MasterAdminServer& admin_server,
-                      StandbyController& standby_controller,
-                      const ViewChangeResult& wait_result) {
-    if (!wait_result.current_view.has_value() &&
-        (wait_result.changed || wait_result.timed_out)) {
-        return;
-    }
-    UpdateObservedLeader(admin_server, standby_controller,
-                         wait_result.current_view);
+    standby_controller.UpdateObservedLeader(sources);
 }
 
-void EnterStandbyMode(MasterAdminServer& admin_server,
-                      StandbyController& standby_controller,
-                      std::atomic<bool>& accept_runtime_updates,
-                      const std::optional<MasterView>& leader_view) {
+// Forward declarations: definitions live below the CVM membership bridge.
+std::optional<MasterView> BuildCvmObservedLeader(
+    const std::unique_ptr<cvm::CvmController>& cvm_controller);
+MasterSources BuildCvmObservedSources(
+    const std::unique_ptr<cvm::CvmController>& cvm_controller);
+
+void EnterStandbyMode(
+    MasterAdminServer& admin_server,
+    StandbyController& standby_controller,
+    std::atomic<bool>& accept_runtime_updates,
+    const std::unique_ptr<cvm::CvmController>& cvm_controller) {
     accept_runtime_updates.store(true, std::memory_order_release);
-    UpdateObservedLeader(admin_server, standby_controller, leader_view);
+    const MasterSources sources = BuildCvmObservedSources(cvm_controller);
+    UpdateObservedLeader(admin_server, standby_controller,
+                         BuildCvmObservedLeader(cvm_controller), sources);
 
-    auto err = standby_controller.StartStandby(leader_view);
+    auto err = standby_controller.StartStandby(sources);
     if (err != ErrorCode::OK) {
         LOG(WARNING) << "Failed to start standby replication: "
                      << toString(err);
@@ -218,6 +167,135 @@ void EnterStandbyMode(MasterAdminServer& admin_server,
     SetRuntimeState(admin_server, standby_controller.GetStandbyRuntimeState());
 }
 
+// Bridges CvmController's membership role decisions to the supervisor's
+// serving/standby state machine. CvmController::MembershipLoop runs on its own
+// thread and calls OnRoleChanged; this class persists the role back to etcd
+// (so slot partitioning immediately excludes demoted nodes) and publishes the
+// change to the supervisor main loop. It never mutates the supervisor state
+// machine directly: on demotion it only invokes a lightweight stop-server
+// signal installed by the serve phase, and the main loop performs the full
+// downgrade sequence serially after the server unblocks.
+class CvmMembershipCoordinator : public cvm::CvmServiceDelegate {
+   public:
+    CvmMembershipCoordinator(std::string cluster_namespace,
+                             std::string master_id)
+        : cluster_namespace_(std::move(cluster_namespace)),
+          master_id_(std::move(master_id)) {}
+
+    void SetLeaseId(EtcdLeaseId lease_id) {
+        lease_id_.store(lease_id, std::memory_order_relaxed);
+    }
+
+    // Installed by the serve phase; cleared (empty) when not serving. The
+    // signal only stops the coro_rpc server so the serve phase unblocks; the
+    // main loop then reads CvmController::GetCurrentRole() and performs the
+    // full downgrade sequence.
+    void SetServeStopSignal(std::function<void()> signal) {
+        std::lock_guard<std::mutex> lock(mutex_);
+        stop_serve_signal_ = std::move(signal);
+    }
+
+    // Blocks until either a role change or a kv-view change is pending, then
+    // clears both so each change is consumed exactly once. The caller re-reads
+    // CvmController::GetCurrentRole() as the source of truth after waking; a
+    // standby uses the wake-up to re-bind its replay sources.
+    void WaitForRoleOrViewChange() {
+        std::unique_lock<std::mutex> lock(mutex_);
+        cv_.wait(lock, [this] {
+            return has_pending_role_ || has_pending_view_;
+        });
+        has_pending_role_ = false;
+        has_pending_view_ = false;
+    }
+
+    void OnSlotAcquired(uint16_t /*slot*/) override {}
+    void OnSlotReleased(uint16_t /*slot*/) override {}
+
+    void OnKvViewChanged() override {
+        {
+            std::lock_guard<std::mutex> lock(mutex_);
+            has_pending_view_ = true;
+        }
+        cv_.notify_all();
+    }
+
+    void OnRoleChanged(cvm::MasterRole new_role) override {
+        const EtcdLeaseId lease_id =
+            lease_id_.load(std::memory_order_relaxed);
+        ErrorCode err = cvm::EtcdViewStore::UpdateMasterRole(
+            cluster_namespace_, master_id_, new_role, lease_id);
+        if (err != ErrorCode::OK) {
+            LOG(WARNING) << "CvmMembershipCoordinator: failed to persist role="
+                         << static_cast<int32_t>(new_role)
+                         << " for master_id=" << master_id_ << ": " << err;
+        }
+        LOG(INFO) << "CvmMembershipCoordinator::OnRoleChanged: master_id="
+                  << master_id_ << ", role=" << static_cast<int32_t>(new_role)
+                  << ", lease_id=" << lease_id;
+
+        {
+            std::lock_guard<std::mutex> lock(mutex_);
+            has_pending_role_ = true;
+        }
+        cv_.notify_all();
+
+        if (new_role == cvm::MasterRole::kStandby) {
+            std::function<void()> signal;
+            {
+                std::lock_guard<std::mutex> lock(mutex_);
+                signal = stop_serve_signal_;
+            }
+            if (signal) {
+                signal();
+            }
+        }
+    }
+
+   private:
+    std::string cluster_namespace_;
+    std::string master_id_;
+    std::atomic<EtcdLeaseId> lease_id_{0};
+    std::mutex mutex_;
+    std::condition_variable cv_;
+    bool has_pending_role_{false};
+    bool has_pending_view_{false};
+    std::function<void()> stop_serve_signal_;
+};
+
+// Builds the representative single-leader view for the admin surface. In the
+// multi-submaster model there is no single "leader"; this reports the earliest
+// primary for display only. Returns nullopt when no primary is available yet
+// (or this node is the first primary itself, so there is no upstream).
+std::optional<MasterView> BuildCvmObservedLeader(
+    const std::unique_ptr<cvm::CvmController>& cvm_controller) {
+    if (!cvm_controller) {
+        return std::nullopt;
+    }
+    const std::string primary = cvm_controller->GetPrimaryAddress();
+    if (primary.empty()) {
+        return std::nullopt;
+    }
+    MasterView view;
+    view.leader_address = primary;
+    view.view_version = cvm_controller->GetKvViewVersion();
+    return view;
+}
+
+// Builds the standby replay source set from the CVM membership ranking. Under
+// dynamic binding (2c) a standby only follows the primary(s) that own the slot
+// range it is responsible for, instead of following every primary (2b).
+MasterSources BuildCvmObservedSources(
+    const std::unique_ptr<cvm::CvmController>& cvm_controller) {
+    MasterSources sources;
+    if (!cvm_controller) {
+        return sources;
+    }
+    for (const auto& member : cvm_controller->GetBindingSources()) {
+        sources.push_back(MasterSource{member.master_id, member.address});
+    }
+    return sources;
+}
+
 int RunSupervisorLoop(const HABackendSpec& spec,
                       const MasterServiceSupervisorConfig& config,
                       MasterAdminServer& admin_server) {
@@ -247,272 +325,209 @@ int RunSupervisorLoop(const HABackendSpec& spec,
             SetRuntimeState(admin_server, state);
         });
 
-    EnterStandbyMode(admin_server, *standby_controller,
-                     accept_standby_runtime_updates, std::nullopt);
-
-    while (true) {
-        auto coordinator = CreateLeaderCoordinator(spec);
-        if (!coordinator) {
-            if (HandleSupervisorError("create leader coordinator",
-                                      coordinator.error(), spec.type)) {
-                return -1;
+    // ── CVM membership (quota coordination) ──
+    // The CvmController owns the etcd lease, master registration, view
+    // snapshot aggregation and the membership loop that decides this node's
+    // role (primary vs standby) via first-come-first-served ranking. It lives
+    // here (supervisor layer) so membership keeps running whether or not this
+    // node is currently serving; MasterService only publishes slot ownership.
+    // NOTE: the coordinator is declared before the controller so it is
+    // destroyed after it — the controller's Stop() joins the membership thread,
+    // guaranteeing no OnRoleChanged callback is in flight when the coordinator
+    // is torn down.
+    CvmMembershipCoordinator cvm_membership_coordinator(config.cluster_id,
+                                                        config.local_hostname);
+    std::unique_ptr<cvm::CvmController> cvm_controller;
+    if (spec.type == HABackendType::ETCD && !config.local_hostname.empty() &&
+        !config.cluster_id.empty()) {
+        ErrorCode connect_err = EtcdHelper::ConnectToEtcdStoreClient(
+            ResolveHABackendConnstring(config));
+        if (connect_err != ErrorCode::OK) {
+            LOG(WARNING) << "CVM membership disabled: failed to connect etcd: "
+                         << connect_err;
+        } else {
+            cvm::CvmController::Config cc_config;
+            cc_config.cluster_namespace = config.cluster_id;
+            cc_config.master_id = config.local_hostname;
+            cc_config.address = config.local_hostname;
+            // Start as standby; the membership loop promotes to primary when
+            // this node ranks within the submaster quota.
+            cc_config.role = cvm::MasterRole::kStandby;
+            cc_config.http_port = config.cvm_http_port;
+            cc_config.http_host = config.cvm_http_host;
+            cc_config.submaster_count = config.submaster_count;
+            cvm_controller =
+                std::make_unique<cvm::CvmController>(std::move(cc_config));
+            cvm_controller->SetDelegate(&cvm_membership_coordinator);
+            ErrorCode cc_err = cvm_controller->Start();
+            if (cc_err != ErrorCode::OK) {
+                LOG(WARNING) << "Failed to start CvmController: " << cc_err;
+                cvm_controller.reset();
+            } else {
+                cvm_membership_coordinator.SetLeaseId(
+                    cvm_controller->GetLeaseId());
+                LOG(INFO) << "Started supervisor-owned CvmController: master_id="
+                          << config.local_hostname
+                          << ", cluster_namespace=" << config.cluster_id
+                          << ", lease_id=" << cvm_controller->GetLeaseId()
+                          << ", submaster_count=" << config.submaster_count;
             }
-            continue;
         }
+    }
 
-        auto& leader_coordinator = *coordinator.value();
-        std::optional<LeadershipSession> leadership_session;
-
-        while (!leadership_session.has_value()) {
-            SetRuntimeState(admin_server, MasterRuntimeState::kCandidate);
-
-            auto current_view = leader_coordinator.ReadCurrentView();
-            if (!current_view) {
-                EnterStandbyMode(admin_server, *standby_controller,
-                                 accept_standby_runtime_updates, std::nullopt);
-                if (HandleSupervisorError("read current leader view",
-                                          current_view.error(), spec.type)) {
-                    return -1;
-                }
-                break;
-            }
+    EnterStandbyMode(admin_server, *standby_controller,
+                     accept_standby_runtime_updates,
+                     cvm_controller);
 
-            UpdateObservedLeader(admin_server, *standby_controller,
-                                 current_view.value());
-            if (!current_view.value().has_value()) {
-                auto acquire = leader_coordinator.TryAcquireLeadership(
-                    config.local_hostname);
-                if (!acquire) {
+    while (true) {
+        // CVM membership decides this node's role via first-come-first-served
+        // ranking against the submaster quota. Without a CvmController
+        // (non-etcd backend or missing identity) there is no quota
+        // coordination, so fall back to unconditional primary serving.
+        const cvm::MasterRole target_role =
+            cvm_controller ? cvm_controller->GetCurrentRole()
+                           : cvm::MasterRole::kPrimary;
+
+        if (target_role == cvm::MasterRole::kPrimary) {
+            // ── Upgrade sequence (kStandby → kPrimary) ──
+            // first primary（无上游）无需 final catch-up；有上游 primary 时才
+            // 从 standby 导出回放数据。PromoteStandbyAndExport 内部完成 final
+            // catch-up + 导出 PromotionContext，新 primary 从它恢复。
+            accept_standby_runtime_updates.store(false,
+                                                 std::memory_order_release);
+            const bool has_upstream =
+                cvm_controller && !cvm_controller->GetPrimaryAddress().empty();
+            PromotionContext promotion_ctx{};
+            if (has_upstream) {
+                auto ctx = standby_controller->PromoteStandbyAndExport();
+                if (!ctx) {
                     EnterStandbyMode(admin_server, *standby_controller,
                                      accept_standby_runtime_updates,
-                                     std::nullopt);
-                    if (HandleSupervisorError("acquire leadership",
-                                              acquire.error(), spec.type)) {
-                        return -1;
-                    }
-                    break;
-                }
-
-                if (acquire->observed_view.has_value()) {
-                    UpdateObservedLeader(admin_server, *standby_controller,
-                                         acquire->observed_view);
-                }
-
-                if (acquire->status == AcquireLeadershipStatus::ACQUIRED &&
-                    acquire->session.has_value()) {
-                    leadership_session = *acquire->session;
-                    admin_server.SetObservedLeader(leadership_session->view);
-                    break;
-                }
-
-                EnterStandbyMode(admin_server, *standby_controller,
-                                 accept_standby_runtime_updates,
-                                 acquire->observed_view);
-                std::optional<ViewVersionId> observed_version = std::nullopt;
-                if (acquire->observed_view.has_value()) {
-                    observed_version = acquire->observed_view->view_version;
-                }
-                auto wait = leader_coordinator.WaitForViewChange(
-                    observed_version, kAcquireRetryInterval);
-                if (!wait) {
-                    if (HandleSupervisorError("wait for leader view change",
-                                              wait.error(), spec.type)) {
+                                     cvm_controller);
+                    if (HandleSupervisorError("promote standby for serve",
+                                              ctx.error(), spec.type)) {
                         return -1;
                     }
-                    break;
+                    continue;
                 }
-                ApplyCurrentView(admin_server, *standby_controller, *wait);
-                continue;
+                promotion_ctx = std::move(*ctx);
             }
 
-            EnterStandbyMode(admin_server, *standby_controller,
-                             accept_standby_runtime_updates,
-                             current_view.value());
-            const auto& known_view = current_view.value().value();
-            auto wait = leader_coordinator.WaitForViewChange(
-                known_view.view_version, kAcquireRetryInterval);
-            if (!wait) {
-                if (HandleSupervisorError("wait for leader view change",
-                                          wait.error(), spec.type)) {
-                    return -1;
-                }
-                break;
+            LOG(INFO) << "Starting serve phase (CVM role=kPrimary)...";
+            coro_rpc::coro_rpc_server server(
+                config.rpc_thread_num, config.rpc_port, config.rpc_address,
+                config.rpc_conn_timeout, config.rpc_enable_tcp_no_delay);
+            const char* protocol = std::getenv("MC_RPC_PROTOCOL");
+            if (protocol && std::string_view(protocol) == "rdma") {
+                server.init_ibv();
             }
-            ApplyCurrentView(admin_server, *standby_controller, *wait);
-        }
-
-        if (!leadership_session.has_value()) {
-            continue;
-        }
 
-        accept_standby_runtime_updates.store(false, std::memory_order_release);
-        auto promotion_ctx = standby_controller->PromoteStandbyAndExport();
-        if (!promotion_ctx) {
-            EnterStandbyMode(admin_server, *standby_controller,
-                             accept_standby_runtime_updates,
-                             leadership_session->view);
-            if (HandleSupervisorError("promote standby for serve",
-                                      promotion_ctx.error(), spec.type)) {
-                return -1;
+            const ViewVersionId view_version =
+                cvm_controller ? cvm_controller->GetKvViewVersion() : 0;
+            mooncake::WrappedMasterServiceConfig wrapped_config(config,
+                                                                 view_version);
+            // In HA serving-primary mode, snapshot bootstrap belongs to
+            // standby. The new primary must restore from PromotionContext only.
+            wrapped_config.enable_snapshot_restore = false;
+            auto wrapped_master_service =
+                std::make_shared<WrappedMasterService>(
+                    wrapped_config, config.http_metadata_server,
+                    config.http_metadata_remote_url);
+
+            // Inject the supervisor-owned CvmController lease so the
+            // slot/segment ownership records share this master's registration
+            // lifecycle.
+            if (cvm_controller) {
+                wrapped_master_service->SetCvmLeaseId(
+                    cvm_controller->GetLeaseId());
             }
-            continue;
-        }
 
-        LOG(INFO) << "Entering warmup phase...";
-        SetRuntimeState(admin_server, MasterRuntimeState::kLeaderWarmup);
-        auto warmup_result =
-            WarmupLeadership(leader_coordinator, *leadership_session);
-        if (!warmup_result) {
-            EnterStandbyMode(admin_server, *standby_controller,
-                             accept_standby_runtime_updates,
-                             leadership_session->view);
-            if (HandleLeadershipPhaseError(
-                    "renewal startup failure", "start leadership renewal",
-                    leader_coordinator, *leadership_session,
-                    warmup_result.error(), spec.type)) {
-                return -1;
+            // Restore from standby if we have context.
+            if (promotion_ctx.applied_seq_id > 0 ||
+                !promotion_ctx.objects.empty() ||
+                !promotion_ctx.segments.empty()) {
+                wrapped_master_service->RestoreFromStandby(
+                    promotion_ctx.objects, promotion_ctx.applied_seq_id,
+                    promotion_ctx.segments);
             }
-            continue;
-        }
-        if (!warmup_result.value()) {
-            EnterStandbyMode(admin_server, *standby_controller,
-                             accept_standby_runtime_updates, std::nullopt);
-            LogLeadershipReleaseWarning(
-                "warmup expiration",
-                leader_coordinator.ReleaseLeadership(*leadership_session));
-            LOG(WARNING) << "Leadership expired during warmup phase";
-            admin_server.SetObservedLeader(std::nullopt);
-            continue;
-        }
-
-        LOG(INFO) << "Starting serve phase...";
-        coro_rpc::coro_rpc_server server(
-            config.rpc_thread_num, config.rpc_port, config.rpc_address,
-            config.rpc_conn_timeout, config.rpc_enable_tcp_no_delay);
-        const char* protocol = std::getenv("MC_RPC_PROTOCOL");
-        if (protocol && std::string_view(protocol) == "rdma") {
-            server.init_ibv();
-        }
-
-        mooncake::WrappedMasterServiceConfig wrapped_config(
-            config, leadership_session->view.view_version);
-        // In HA serving-primary mode, snapshot bootstrap belongs to standby.
-        // The new primary must restore from PromotionContext only.
-        wrapped_config.enable_snapshot_restore = false;
-        // The serving primary handles heartbeats/unmounts, so forward the
-        // metadata cleanup config here like the non-HA path does.
-        auto wrapped_master_service = std::make_shared<WrappedMasterService>(
-            wrapped_config, config.http_metadata_server,
-            config.http_metadata_remote_url);
-
-        // Restore from standby if we have context
-        if (promotion_ctx->applied_seq_id > 0 ||
-            !promotion_ctx->objects.empty() ||
-            !promotion_ctx->segments.empty()) {
-            wrapped_master_service->RestoreFromStandby(
-                promotion_ctx->objects, promotion_ctx->applied_seq_id,
-                promotion_ctx->segments);
-        }
 
-        mooncake::RegisterRpcService(server, *wrapped_master_service);
+            mooncake::RegisterRpcService(server, *wrapped_master_service);
 
-        auto serve_preflight =
-            leader_coordinator.RenewLeadership(*leadership_session);
-        if (!serve_preflight) {
-            DeactivateServingState(admin_server, label_reconciler);
-            EnterStandbyMode(admin_server, *standby_controller,
-                             accept_standby_runtime_updates,
-                             leadership_session->view);
-            if (HandleLeadershipPhaseError(
-                    "serve preflight failure",
-                    "validate leadership before serving", leader_coordinator,
-                    *leadership_session, serve_preflight.error(), spec.type)) {
+            async_simple::Future<coro_rpc::err_code> ec = server.async_start();
+            if (ec.hasResult()) {
+                LOG(ERROR) << "Failed to start master service: "
+                           << ec.result().value();
+                DeactivateServingState(admin_server, label_reconciler);
+                EnterStandbyMode(admin_server, *standby_controller,
+                                 accept_standby_runtime_updates,
+                                 cvm_controller);
                 return -1;
             }
-            continue;
-        }
-        if (!serve_preflight.value()) {
-            DeactivateServingState(admin_server, label_reconciler);
-            EnterStandbyMode(admin_server, *standby_controller,
-                             accept_standby_runtime_updates, std::nullopt);
-            LogLeadershipReleaseWarning(
-                "serve preflight expiration",
-                leader_coordinator.ReleaseLeadership(*leadership_session));
-            LOG(WARNING) << "Leadership expired before entering serve phase";
-            admin_server.SetObservedLeader(std::nullopt);
-            continue;
-        }
 
-        std::atomic<bool> serve_shutdown_requested{false};
-        auto leadership_monitor = leader_coordinator.StartLeadershipMonitor(
-            *leadership_session,
-            [&server, &admin_server, &serve_shutdown_requested,
-             &label_reconciler, &metrics_reporter](auto reason) {
-                metrics_reporter.Stop();
-                serve_shutdown_requested.store(true, std::memory_order_release);
-                admin_server.SetServiceAvailable(false);
-                label_reconciler.SetLeader(false);
-                SetRuntimeState(admin_server, MasterRuntimeState::kStandby);
-                LOG(INFO) << "Trying to stop server, reason="
-                          << LeadershipLossReasonToString(reason);
+            // Lightweight demotion signal: only stops the coro_rpc server so
+            // the blocking get() below unblocks; the main loop then performs
+            // the full downgrade sequence serially.
+            cvm_membership_coordinator.SetServeStopSignal([&server]() {
+                LOG(INFO) << "CVM quota demotion: stopping server";
                 server.stop();
             });
-        if (!leadership_monitor) {
-            DeactivateServingState(admin_server, label_reconciler);
-            EnterStandbyMode(admin_server, *standby_controller,
-                             accept_standby_runtime_updates,
-                             leadership_session->view);
-            if (HandleLeadershipPhaseError(
-                    "serve monitor startup failure", "start leadership monitor",
-                    leader_coordinator, *leadership_session,
-                    leadership_monitor.error(), spec.type)) {
-                return -1;
-            }
-            continue;
-        }
-        auto leadership_monitor_handle = std::move(leadership_monitor.value());
 
-        async_simple::Future<coro_rpc::err_code> ec = server.async_start();
-        if (ec.hasResult()) {
-            LOG(ERROR) << "Failed to start master service: "
-                       << ec.result().value();
-            StopLeadershipMonitor(leadership_monitor_handle);
-            DeactivateServingState(admin_server, label_reconciler);
-            EnterStandbyMode(admin_server, *standby_controller,
-                             accept_standby_runtime_updates,
-                             leadership_session->view);
-            auto err =
-                leader_coordinator.ReleaseLeadership(*leadership_session);
-            if (err != ErrorCode::OK) {
-                LOG(ERROR) << "Failed to release leadership: " << toString(err);
+            // A demotion may have been decided while the server was starting
+            // up (before the stop signal was installed). If our role is no
+            // longer primary, stop the server now so the get() below returns
+            // promptly instead of blocking forever.
+            const bool demoted_during_startup =
+                cvm_controller &&
+                cvm_controller->GetCurrentRole() == cvm::MasterRole::kStandby;
+
+            if (!demoted_during_startup) {
+                ActivateServingState(admin_server, wrapped_master_service,
+                                     label_reconciler);
+                metrics_reporter.SetRole("primary");
+                metrics_reporter.Start();
+                if (wrapped_master_service->StartSlotOwnerHeartbeat() !=
+                    ErrorCode::OK) {
+                    LOG(WARNING) << "Failed to start SlotOwnerHeartbeat during "
+                                    "serve phase";
+                }
+                // Inter-master RPC channel: etcd-driven peer discovery +
+                // cached peer connections for the CVM multi-submaster
+                // coordination (handshake now, allocation forwarding later).
+                if (wrapped_master_service->StartInterMasterRpc() !=
+                    ErrorCode::OK) {
+                    LOG(WARNING) << "Failed to start InterMasterRpcClient "
+                                    "during serve phase";
+                }
+            } else {
+                LOG(INFO) << "Demoted during serve startup; stopping server";
+                server.stop();
             }
-            return -1;
-        }
 
-        if (!serve_shutdown_requested.load(std::memory_order_acquire)) {
-            ActivateServingState(admin_server, wrapped_master_service,
-                                 label_reconciler);
-            metrics_reporter.SetRole("primary");
-            metrics_reporter.Start();
-        }
+            auto server_err = std::move(ec).get();
+            LOG(INFO) << "Master service stopped: " << server_err;
 
-        auto server_err = std::move(ec).get();
-        LOG(ERROR) << "Master service stopped: " << server_err;
-
-        metrics_reporter.Stop();
-        metrics_reporter.SetRole("standby");
-        StopLeadershipMonitor(leadership_monitor_handle);
-        DeactivateServingState(admin_server, label_reconciler);
-        auto err = leader_coordinator.ReleaseLeadership(*leadership_session);
-        LOG(INFO) << "Release leadership: " << toString(err);
-        auto current_view = leader_coordinator.ReadCurrentView();
-        if (current_view) {
+            // ── Downgrade sequence (kPrimary → kStandby) ──
+            metrics_reporter.Stop();
+            metrics_reporter.SetRole("standby");
+            wrapped_master_service->StopSlotOwnerHeartbeat();
+            wrapped_master_service->StopInterMasterRpc();
+            cvm_membership_coordinator.SetServeStopSignal(nullptr);
+            DeactivateServingState(admin_server, label_reconciler);
             EnterStandbyMode(admin_server, *standby_controller,
                              accept_standby_runtime_updates,
-                             current_view.value());
+                             cvm_controller);
         } else {
+            // ── Standby (kStandby): keep replicating, wait for promotion ──
             EnterStandbyMode(admin_server, *standby_controller,
-                             accept_standby_runtime_updates, std::nullopt);
+                             accept_standby_runtime_updates,
+                             cvm_controller);
+            if (cvm_controller) {
+                cvm_membership_coordinator.WaitForRoleOrViewChange();
+            } else {
+                // Unreachable: target_role is kPrimary when cvm_controller is
+                // null. Sleep defensively to avoid a tight loop.
+                std::this_thread::sleep_for(kSupervisorRetryInterval);
+            }
         }
     }
 
diff --git a/mooncake-store/src/ha/oplog/oplog_batch_standby_reader.cpp b/mooncake-store/src/ha/oplog/oplog_batch_standby_reader.cpp
index 1c1d9295bd..c7794c6540 100644
--- a/mooncake-store/src/ha/oplog/oplog_batch_standby_reader.cpp
+++ b/mooncake-store/src/ha/oplog/oplog_batch_standby_reader.cpp
@@ -26,8 +26,10 @@ void SetPollError(OpLogBatchStandbyPollResult& result, ErrorCode error,
 
 OpLogBatchStandbyReader::OpLogBatchStandbyReader(std::string cluster_id,
                                                  HaKvBackend& backend,
-                                                 OpLogApplier& applier)
-    : storage_(std::move(cluster_id), backend), applier_(applier) {}
+                                                 OpLogApplier& applier,
+                                                 std::string source_id)
+    : storage_(std::move(cluster_id), backend, std::move(source_id)),
+      applier_(applier) {}
 
 OpLogBatchStandbyPollResult OpLogBatchStandbyReader::PollOnce(
     size_t max_batches) {
diff --git a/mooncake-store/src/ha/oplog/oplog_batch_storage.cpp b/mooncake-store/src/ha/oplog/oplog_batch_storage.cpp
index be2a66c964..f38175fac5 100644
--- a/mooncake-store/src/ha/oplog/oplog_batch_storage.cpp
+++ b/mooncake-store/src/ha/oplog/oplog_batch_storage.cpp
@@ -2,6 +2,7 @@
 
 #include <algorithm>
 #include <charconv>
+#include <string_view>
 
 #include <glog/logging.h>
 
@@ -53,8 +54,11 @@ bool TryParseBatchIdFromKey(const std::string& key, uint64_t& batch_id) {
 }  // namespace
 
 OpLogBatchStorage::OpLogBatchStorage(std::string cluster_id,
-                                     HaKvBackend& backend)
-    : cluster_id_(std::move(cluster_id)), backend_(backend) {
+                                     HaKvBackend& backend,
+                                     std::string source_id)
+    : cluster_id_(std::move(cluster_id)),
+      source_id_(std::move(source_id)),
+      backend_(backend) {
     cluster_id_valid_ =
         NormalizeAndValidateClusterId(cluster_id_) && !cluster_id_.empty();
 }
@@ -78,7 +82,7 @@ ErrorCode OpLogBatchStorage::InitDurablePrefix(DurablePrefix& prefix) {
         return ErrorCode::INVALID_PARAMS;
     }
 
-    auto batch_range = BuildBatchRecordRange(cluster_id_, 0);
+    auto batch_range = BuildBatchRecordRange(cluster_id_, 0, source_id_);
     std::vector<KvPair> existing_batches;
     err = backend_.Range(batch_range.begin_key, batch_range.end_key,
                          /*limit=*/1, existing_batches);
@@ -90,7 +94,7 @@ ErrorCode OpLogBatchStorage::InitDurablePrefix(DurablePrefix& prefix) {
         return ErrorCode::INTERNAL_ERROR;
     }
 
-    const std::string durable_key = BuildDurablePrefixKey(cluster_id_);
+    const std::string durable_key = BuildDurablePrefixKey(cluster_id_, source_id_);
     DurablePrefix initial{.batch_id = 0, .last_seq = 0};
     KvTxn txn;
     txn.compares.push_back({.key = durable_key,
@@ -114,7 +118,7 @@ ErrorCode OpLogBatchStorage::ReadDurablePrefix(DurablePrefix& prefix) {
         return ErrorCode::INVALID_PARAMS;
     }
     std::string value;
-    const std::string key = BuildDurablePrefixKey(cluster_id_);
+    const std::string key = BuildDurablePrefixKey(cluster_id_, source_id_);
     ErrorCode err = backend_.Get(key, value);
     if (err != ErrorCode::OK) {
         return err;
@@ -157,7 +161,7 @@ ErrorCode OpLogBatchStorage::WriteBatchAndAdvancePrefix(
         return ErrorCode::INVALID_PARAMS;
     }
 
-    const std::string durable_key = BuildDurablePrefixKey(cluster_id_);
+    const std::string durable_key = BuildDurablePrefixKey(cluster_id_, source_id_);
     const std::string encoded_batch = EncodeOpLogBatchRecord(batch);
 #ifdef MOONCAKE_ENABLE_OPLOG_PERF_METRICS
     HAMetricManager::instance().observe_batch_record_batch_bytes(
@@ -168,8 +172,9 @@ ErrorCode OpLogBatchStorage::WriteBatchAndAdvancePrefix(
         {.key = durable_key,
          .kind = KvCompareKind::kValueEquals,
          .expected_value = EncodeDurablePrefix(expected_prefix)});
-    txn.puts.push_back({.key = BuildBatchRecordKey(cluster_id_, batch.batch_id),
-                        .value = encoded_batch});
+    txn.puts.push_back(
+        {.key = BuildBatchRecordKey(cluster_id_, batch.batch_id, source_id_),
+         .value = encoded_batch});
     txn.puts.push_back(
         {.key = durable_key,
          .value = EncodeDurablePrefix(
@@ -200,7 +205,8 @@ ErrorCode OpLogBatchStorage::ReadBatch(uint64_t batch_id,
     }
     std::string value;
     ErrorCode err =
-        backend_.Get(BuildBatchRecordKey(cluster_id_, batch_id), value);
+        backend_.Get(BuildBatchRecordKey(cluster_id_, batch_id, source_id_),
+                     value);
     if (err != ErrorCode::OK) {
         return err;
     }
@@ -219,7 +225,7 @@ ErrorCode OpLogBatchStorage::ReadBatchesAfter(
     if (!IsValidClusterId()) {
         return ErrorCode::INVALID_PARAMS;
     }
-    auto range = BuildBatchRecordRange(cluster_id_, after_batch_id);
+    auto range = BuildBatchRecordRange(cluster_id_, after_batch_id, source_id_);
     std::string begin_key = range.begin_key;
     do {
         std::vector<KvPair> kvs;
@@ -273,27 +279,60 @@ ErrorCode OpLogBatchStorage::RejectLegacyLayout() const {
         return err;
     }
 
-    std::vector<KvPair> entries;
-    err = backend_.Range(root + "00000000000000000000", root + ":",
-                         /*limit=*/1, entries);
-    if (err != ErrorCode::OK) {
-        return err;
-    }
-    if (!entries.empty()) {
-        LOG(ERROR) << "Legacy per-entry OpLog key exists for cluster="
-                   << cluster_id_
-                   << "; clear the legacy OpLog namespace before enabling "
-                      "batch-record OpLog";
-        return ErrorCode::INCOMPLETE_OPLOG_CATCH_UP;
-    }
+    // Legacy per-entry keys have the exact shape root + <20 digits> with no
+    // trailing '/'. Batch-layout keys (root + <source_id>/batches/... and
+    // root + <source_id>/durable_prefix) can sort lexically inside the legacy
+    // numeric range when the source id starts with a digit (e.g. an
+    // "ip:port" master id such as "141.61.84.245:50052"), so a bare range
+    // probe would false-positive on this node's own batch keys after a
+    // restart. Scan the range with pagination and reject only keys matching
+    // the legacy per-entry shape.
+    std::string begin_key = root + "00000000000000000000";
+    const std::string end_key = root + ":";
+    constexpr size_t kLegacyScanPageLimit = 100;
+    do {
+        std::vector<KvPair> entries;
+        err = backend_.Range(begin_key, end_key, kLegacyScanPageLimit, entries);
+        if (err != ErrorCode::OK) {
+            return err;
+        }
+        for (const auto& kv : entries) {
+            const std::string_view suffix(kv.key.data() + root.size(),
+                                          kv.key.size() - root.size());
+            bool is_legacy_entry = suffix.size() ==
+                                       static_cast<size_t>(
+                                           kOpLogBatchIdWidth) &&
+                                   suffix.find('/') ==
+                                       std::string_view::npos;
+            if (is_legacy_entry) {
+                for (char c : suffix) {
+                    if (c < '0' || c > '9') {
+                        is_legacy_entry = false;
+                        break;
+                    }
+                }
+            }
+            if (is_legacy_entry) {
+                LOG(ERROR) << "Legacy per-entry OpLog key exists for cluster="
+                           << cluster_id_ << ": key=" << kv.key
+                           << "; clear the legacy OpLog namespace before "
+                              "enabling batch-record OpLog";
+                return ErrorCode::INCOMPLETE_OPLOG_CATCH_UP;
+            }
+        }
+        if (entries.size() < kLegacyScanPageLimit) {
+            break;
+        }
+        begin_key = entries.back().key + '\0';
+    } while (begin_key < end_key);
 
-    entries.clear();
+    std::vector<KvPair> snapshot_entries;
     err = backend_.Range(root + "snapshot/", root + "snapshot0",
-                         /*limit=*/1, entries);
+                         /*limit=*/1, snapshot_entries);
     if (err != ErrorCode::OK) {
         return err;
     }
-    if (!entries.empty()) {
+    if (!snapshot_entries.empty()) {
         LOG(ERROR) << "Legacy OpLog snapshot sidecar exists for cluster="
                    << cluster_id_
                    << "; clear the legacy OpLog namespace before enabling "
diff --git a/mooncake-store/src/ha/oplog/oplog_batch_types.cpp b/mooncake-store/src/ha/oplog/oplog_batch_types.cpp
index 2e91730d31..66cf25f813 100644
--- a/mooncake-store/src/ha/oplog/oplog_batch_types.cpp
+++ b/mooncake-store/src/ha/oplog/oplog_batch_types.cpp
@@ -25,8 +25,22 @@ std::string PrefixEnd(std::string prefix) {
     return std::string(1, '\0');
 }
 
-std::string BatchPrefix(const std::string& cluster_id) {
-    return "/oplog/" + cluster_id + "/batches/";
+std::string BatchPrefix(const std::string& cluster_id,
+                        const std::string& source_id) {
+    std::string path = "/oplog/" + cluster_id + "/";
+    if (!source_id.empty()) {
+        path += source_id + "/";
+    }
+    return path + "batches/";
+}
+
+std::string DurablePrefixPath(const std::string& cluster_id,
+                              const std::string& source_id) {
+    std::string path = "/oplog/" + cluster_id + "/";
+    if (!source_id.empty()) {
+        path += source_id + "/";
+    }
+    return path + "durable_prefix";
 }
 
 }  // namespace
@@ -114,29 +128,32 @@ std::string FormatOpLogBatchId(uint64_t batch_id) {
 }
 
 std::string BuildBatchRecordKey(const std::string& cluster_id,
-                                uint64_t batch_id) {
+                                uint64_t batch_id,
+                                const std::string& source_id) {
     std::string normalized = cluster_id;
     if (!NormalizeAndValidateClusterId(normalized) || normalized.empty()) {
         return {};
     }
-    return BatchPrefix(normalized) + FormatOpLogBatchId(batch_id);
+    return BatchPrefix(normalized, source_id) + FormatOpLogBatchId(batch_id);
 }
 
-std::string BuildDurablePrefixKey(const std::string& cluster_id) {
+std::string BuildDurablePrefixKey(const std::string& cluster_id,
+                                  const std::string& source_id) {
     std::string normalized = cluster_id;
     if (!NormalizeAndValidateClusterId(normalized) || normalized.empty()) {
         return {};
     }
-    return "/oplog/" + normalized + "/durable_prefix";
+    return DurablePrefixPath(normalized, source_id);
 }
 
 BatchRecordRange BuildBatchRecordRange(const std::string& cluster_id,
-                                       uint64_t after_batch_id) {
+                                       uint64_t after_batch_id,
+                                       const std::string& source_id) {
     std::string normalized = cluster_id;
     if (!NormalizeAndValidateClusterId(normalized) || normalized.empty()) {
         return {};
     }
-    const std::string prefix = BatchPrefix(normalized);
+    const std::string prefix = BatchPrefix(normalized, source_id);
     if (after_batch_id == UINT64_MAX) {
         return {.begin_key = PrefixEnd(prefix), .end_key = PrefixEnd(prefix)};
     }
diff --git a/mooncake-store/src/ha/standby_controller.cpp b/mooncake-store/src/ha/standby_controller.cpp
index 6576cd9a21..08ae18da0f 100644
--- a/mooncake-store/src/ha/standby_controller.cpp
+++ b/mooncake-store/src/ha/standby_controller.cpp
@@ -47,7 +47,7 @@ StandbyRuntimeCapabilities BuildStandbyRuntimeCapabilities(
 
 MasterRuntimeState MapStandbyRuntimeState(
     const StandbySyncStatus& status,
-    const std::optional<MasterView>& observed_leader,
+    const MasterSources& sources,
     const StandbyRuntimeCapabilities& capabilities) {
     switch (status.state) {
         case StandbyState::STOPPED:
@@ -60,7 +60,7 @@ MasterRuntimeState MapStandbyRuntimeState(
             return MasterRuntimeState::kRecovering;
         case StandbyState::WATCHING:
             if (capabilities.has_oplog_following &&
-                observed_leader.has_value() && status.lag_entries > 0) {
+                !sources.empty() && status.lag_entries > 0) {
                 return MasterRuntimeState::kCatchingUp;
             }
             return MasterRuntimeState::kStandby;
@@ -73,7 +73,7 @@ MasterRuntimeState MapStandbyRuntimeState(
 
 class NoopStandbyController final : public StandbyController {
    public:
-    ErrorCode StartStandby(const std::optional<MasterView>&) override {
+    ErrorCode StartStandby(const MasterSources&) override {
         return ErrorCode::OK;
     }
 
@@ -83,10 +83,12 @@ class NoopStandbyController final : public StandbyController {
 
     tl::expected<PromotionContext, ErrorCode> PromoteStandbyAndExport()
         override {
-        return tl::unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+        // 无 standby 回放能力时没有数据可导出，返回空上下文让 primary 直接
+        // serving（数据复制/迁移由 P2/P4 处理），而非让升级序列死循环。
+        return PromotionContext{};
     }
 
-    void UpdateObservedLeader(const std::optional<MasterView>&) override {}
+    void UpdateObservedLeader(const MasterSources&) override {}
 
     MasterRuntimeState GetStandbyRuntimeState() const override {
         return MasterRuntimeState::kStandby;
@@ -149,17 +151,22 @@ class CapabilityDrivenStandbyController final : public StandbyController {
         standby_service_->Stop();
     }
 
-    ErrorCode StartStandby(
-        const std::optional<MasterView>& observed_leader) override {
+    ErrorCode StartStandby(const MasterSources& sources) override {
         bool standby_running = false;
         {
             std::lock_guard<std::mutex> lock(state_mutex_);
-            observed_leader_ = observed_leader;
+            observed_sources_ = sources;
             standby_running = standby_running_;
         }
         if (standby_running) {
-            NotifyRuntimeStateIfChanged();
-            return ErrorCode::OK;
+            // 运行中：动态重绑（若源集合变化）。UpdateSources 内部幂等，未
+            // 运行则等价 Start，源集合不变则 no-op，变化则 Stop+Start。
+            ErrorCode err = standby_service_->UpdateSources(
+                sources, oplog_connstring_, config_.cluster_id);
+            if (err == ErrorCode::OK) {
+                NotifyRuntimeStateIfChanged();
+            }
+            return err;
         }
 
         if (dependency_init_error_ != ErrorCode::OK) {
@@ -169,8 +176,7 @@ class CapabilityDrivenStandbyController final : public StandbyController {
         }
 
         ErrorCode err = standby_service_->Start(
-            observed_leader.has_value() ? observed_leader->leader_address : "",
-            oplog_connstring_, config_.cluster_id);
+            sources, oplog_connstring_, config_.cluster_id);
 
         {
             std::lock_guard<std::mutex> lock(state_mutex_);
@@ -274,28 +280,27 @@ class CapabilityDrivenStandbyController final : public StandbyController {
         return ctx;
     }
 
-    void UpdateObservedLeader(
-        const std::optional<MasterView>& observed_leader) override {
+    void UpdateObservedLeader(const MasterSources& sources) override {
         {
             std::lock_guard<std::mutex> lock(state_mutex_);
-            observed_leader_ = observed_leader;
+            observed_sources_ = sources;
         }
         NotifyRuntimeStateIfChanged();
     }
 
     MasterRuntimeState GetStandbyRuntimeState() const override {
-        std::optional<MasterView> observed_leader;
+        MasterSources observed_sources;
         bool standby_running = false;
         {
             std::lock_guard<std::mutex> lock(state_mutex_);
-            observed_leader = observed_leader_;
+            observed_sources = observed_sources_;
             standby_running = standby_running_;
         }
         if (!standby_running) {
             return MasterRuntimeState::kStandby;
         }
         return MapStandbyRuntimeState(standby_service_->GetSyncStatus(),
-                                      observed_leader, capabilities_);
+                                      observed_sources, capabilities_);
     }
 
     void SetStandbyRuntimeStateCallback(
@@ -338,7 +343,7 @@ class CapabilityDrivenStandbyController final : public StandbyController {
     std::string oplog_connstring_;
 
     mutable std::mutex state_mutex_;
-    std::optional<MasterView> observed_leader_;
+    MasterSources observed_sources_;
     bool standby_running_ = false;
     ErrorCode last_standby_error_{ErrorCode::OK};
 
diff --git a/mooncake-store/src/hot_standby_service.cpp b/mooncake-store/src/hot_standby_service.cpp
index c31ae1e2e4..fa91f24822 100644
--- a/mooncake-store/src/hot_standby_service.cpp
+++ b/mooncake-store/src/hot_standby_service.cpp
@@ -4,6 +4,7 @@
 
 #include <algorithm>
 #include <chrono>
+#include <set>
 #include <thread>
 
 #include "etcd_helper.h"
@@ -19,8 +20,8 @@ namespace mooncake {
 HotStandbyService::HotStandbyService(const HotStandbyConfig& config)
     : config_(config) {
     metadata_store_ = std::make_unique<StandbyMetadataStore>();
-    // OpLogApplier is re-created in Start() with the resolved cluster_id.
-    oplog_applier_ = std::make_unique<OpLogApplier>(metadata_store_.get());
+    // Per-source OpLogApplier/reader replicas are created in Start() with the
+    // resolved cluster_id and source list.
 
     // Register callback for state change logging and metrics.
     state_machine_.RegisterCallback([this](StandbyState old_state,
@@ -153,7 +154,7 @@ HotStandbyService::~HotStandbyService() {
     }
 }
 
-ErrorCode HotStandbyService::Start(const std::string& primary_address,
+ErrorCode HotStandbyService::Start(const std::vector<ha::MasterSource>& sources,
                                    const std::string& oplog_endpoints,
                                    const std::string& cluster_id) {
     std::lock_guard<std::mutex> lock(mutex_);
@@ -174,8 +175,9 @@ ErrorCode HotStandbyService::Start(const std::string& primary_address,
     if (verification_thread_.joinable()) {
         verification_thread_.join();
     }
-    batch_standby_reader_.reset();
+    sources_.clear();
     batch_standby_kv_backend_.reset();
+    baseline_segments_.clear();
 
     last_error_.store(ErrorCode::OK, std::memory_order_release);
 
@@ -186,7 +188,7 @@ ErrorCode HotStandbyService::Start(const std::string& primary_address,
         return ErrorCode::INTERNAL_ERROR;  // State machine rejected START
     }
 
-    config_.primary_address = primary_address;
+    config_.sources = sources;
     oplog_endpoints_ = oplog_endpoints;
     cluster_id_ = cluster_id;
 
@@ -226,13 +228,41 @@ ErrorCode HotStandbyService::Start(const std::string& primary_address,
 }
 
 uint64_t HotStandbyService::GetLocalLastAppliedSequenceIdLocked() const {
-    if (oplog_applier_) {
-        uint64_t expected = oplog_applier_->GetExpectedSequenceId();
-        return expected > 0 ? expected - 1 : 0;
+    uint64_t max_applied = 0;
+    for (const auto& [source_id, replica] : sources_) {
+        if (replica.applier) {
+            const uint64_t expected = replica.applier->GetExpectedSequenceId();
+            const uint64_t applied = expected > 0 ? expected - 1 : 0;
+            max_applied = std::max(max_applied, applied);
+        }
+    }
+    if (max_applied > 0) {
+        return max_applied;
     }
     return applied_seq_id_.load(std::memory_order_acquire);
 }
 
+void HotStandbyService::CollectSegmentsLocked(
+    std::vector<StandbySegmentInfo>& out) const {
+    out.clear();
+    // Merge segment registries across per-source appliers, deduplicating by
+    // transport_endpoint (segment identity in StandbySegmentRegistry).
+    std::unordered_map<std::string, StandbySegmentInfo> by_endpoint;
+    for (const auto& [source_id, replica] : sources_) {
+        if (!replica.applier) {
+            continue;
+        }
+        for (const auto& segment :
+             replica.applier->GetSegmentRegistry().GetAllSegments()) {
+            by_endpoint[segment.transport_endpoint] = segment;
+        }
+    }
+    out.reserve(by_endpoint.size());
+    for (const auto& [endpoint, segment] : by_endpoint) {
+        out.push_back(segment);
+    }
+}
+
 ErrorCode HotStandbyService::PrepareBootstrapBaselineLocked(
     uint64_t& baseline_seq_id) {
     const uint64_t local_last_seq_id = GetLocalLastAppliedSequenceIdLocked();
@@ -248,8 +278,6 @@ ErrorCode HotStandbyService::PrepareBootstrapBaselineLocked(
         metadata_store_ = std::make_unique<StandbyMetadataStore>();
     }
 
-    oplog_applier_ =
-        std::make_unique<OpLogApplier>(metadata_store_.get(), cluster_id_);
     if (!config_.enable_oplog_following) {
         if (metadata_store_ && metadata_store_->GetKeyCount() > 0) {
             LOG(INFO) << "Snapshot-only restart discards local metadata and "
@@ -269,7 +297,6 @@ ErrorCode HotStandbyService::PrepareBootstrapBaselineLocked(
         LOG(INFO) << "Standby warm start: reuse local metadata (keys="
                   << metadata_store_->GetKeyCount()
                   << "), recover last_seq_id=" << local_last_seq_id;
-        oplog_applier_->Recover(local_last_seq_id);
         baseline_seq_id = local_last_seq_id;
     } else {
         auto snapshot_err = LoadSnapshotBaselineLocked(baseline_seq_id);
@@ -287,7 +314,7 @@ ErrorCode HotStandbyService::LoadSnapshotBaselineLocked(
     uint64_t& baseline_seq_id) {
     baseline_seq_id = 0;
     metadata_store_->Clear();
-    oplog_applier_->Recover(0);
+    baseline_segments_.clear();
 
     if (!config_.enable_snapshot_bootstrap || !snapshot_provider_) {
         return ErrorCode::OK;
@@ -327,11 +354,9 @@ ErrorCode HotStandbyService::LoadSnapshotBaselineLocked(
         metadata_store_->PutMetadata(entry.tenant_id, entry.key,
                                      entry.metadata);
     }
-    // Load segment registry from snapshot
-    if (oplog_applier_) {
-        oplog_applier_->LoadSegmentRegistry(snapshot.segments);
-    }
-    oplog_applier_->Recover(snapshot.snapshot_sequence_id);
+    // Load segment registry from snapshot; applied to each per-source applier
+    // when OpLog following starts.
+    baseline_segments_ = snapshot.segments;
     baseline_seq_id = snapshot.snapshot_sequence_id;
     return ErrorCode::OK;
 }
@@ -344,8 +369,18 @@ ErrorCode HotStandbyService::StartOplogFollowingLocked(
     } else {
         batch_standby_kv_backend_ = std::make_shared<EtcdHaKvBackend>();
     }
-    batch_standby_reader_ = std::make_unique<OpLogBatchStandbyReader>(
-        cluster_id_, *batch_standby_kv_backend_, *oplog_applier_);
+
+    sources_.clear();
+    for (const auto& source : config_.sources) {
+        auto applier =
+            std::make_unique<OpLogApplier>(metadata_store_.get(), cluster_id_);
+        applier->LoadSegmentRegistry(baseline_segments_);
+        auto reader = std::make_unique<OpLogBatchStandbyReader>(
+            cluster_id_, *batch_standby_kv_backend_, *applier, source.master_id);
+        sources_.emplace(
+            source.master_id,
+            SourceReplica{std::move(applier), std::move(reader)});
+    }
 
     state_machine_.ProcessEvent(StandbyEvent::SYNC_COMPLETE);
     replication_loop_running_.store(true, std::memory_order_release);
@@ -357,7 +392,8 @@ ErrorCode HotStandbyService::StartOplogFollowingLocked(
     }
 
     LOG(INFO) << "HotStandbyService started, watching OpLog for cluster: "
-              << cluster_id_ << ", state=" << StandbyStateToString(GetState());
+              << cluster_id_ << ", sources=" << sources_.size()
+              << ", state=" << StandbyStateToString(GetState());
     return ErrorCode::OK;
 }
 
@@ -423,19 +459,62 @@ void HotStandbyService::Stop() {
               << StandbyStateToString(GetState());
 }
 
+ErrorCode HotStandbyService::UpdateSources(
+    const std::vector<ha::MasterSource>& sources,
+    const std::string& oplog_endpoints,
+    const std::string& cluster_id) {
+    // 判断是否需要重绑（比较 master_id 集合）。
+    bool running = false;
+    bool changed = false;
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        running = IsRunning();
+        if (running) {
+            if (config_.sources.size() != sources.size()) {
+                changed = true;
+            } else {
+                std::set<std::string> old_ids;
+                std::set<std::string> new_ids;
+                for (const auto& s : config_.sources) {
+                    old_ids.insert(s.master_id);
+                }
+                for (const auto& s : sources) {
+                    new_ids.insert(s.master_id);
+                }
+                changed = (old_ids != new_ids);
+            }
+        }
+    }
+
+    if (!running) {
+        return Start(sources, oplog_endpoints, cluster_id);
+    }
+    if (!changed) {
+        return ErrorCode::OK;
+    }
+
+    // 运行中且源集合变化：停止后重启。metadata_store_ 是成员变量，Stop 不
+    // 清空，Start 里 PrepareBootstrapBaselineLocked 会复用已回放的元数据。
+    LOG(INFO) << "HotStandbyService rebinding replay sources: "
+              << config_.sources.size() << " -> " << sources.size();
+    Stop();
+    return Start(sources, oplog_endpoints, cluster_id);
+}
+
 StandbySyncStatus HotStandbyService::GetSyncStatus() const {
     StandbySyncStatus status;
 
-    // Get applied sequence ID from OpLogApplier
-    if (oplog_applier_) {
-        uint64_t expected = oplog_applier_->GetExpectedSequenceId();
-        status.applied_seq_id = (expected > 0) ? (expected - 1) : 0;
-        if (status.applied_seq_id == 0) {
-            status.applied_seq_id = applied_seq_id_.load();  // Fallback
+    // Get applied sequence ID from per-source OpLogAppliers (max across
+    // sources; each source owns an independent sequence space).
+    uint64_t max_applied = 0;
+    for (const auto& [source_id, replica] : sources_) {
+        if (replica.applier) {
+            const uint64_t expected = replica.applier->GetExpectedSequenceId();
+            max_applied = std::max(max_applied, expected > 0 ? expected - 1 : 0);
         }
-    } else {
-        status.applied_seq_id = applied_seq_id_.load();
     }
+    status.applied_seq_id =
+        max_applied > 0 ? max_applied : applied_seq_id_.load();
 
     // Primary sequence ID (best-effort): updated by ReplicationLoop via etcd
     // `/latest`.
@@ -494,9 +573,9 @@ ErrorCode HotStandbyService::FinalCatchUpForPromotionLocked(
         LOG(INFO) << "Promotion does not require final OpLog catch-up";
         return ErrorCode::OK;
     }
-    if (!oplog_applier_) {
-        LOG(ERROR) << "Final catch-up requires OpLogApplier";
-        return ErrorCode::INTERNAL_ERROR;
+    if (sources_.empty()) {
+        LOG(INFO) << "Final catch-up skipped: no OpLog sources";
+        return ErrorCode::OK;
     }
 
     if (catch_up_batch_kv_backend_for_testing_) {
@@ -510,55 +589,60 @@ ErrorCode HotStandbyService::FinalCatchUpForPromotionLocked(
 
 ErrorCode HotStandbyService::FinalCatchUpBatchRecordsLocked(
     HaKvBackend& backend) {
-    std::unique_ptr<OpLogBatchStandbyReader> local_reader;
-    OpLogBatchStandbyReader* reader = batch_standby_reader_.get();
-    if (reader == nullptr) {
-        local_reader = std::make_unique<OpLogBatchStandbyReader>(
-            cluster_id_, backend, *oplog_applier_);
-        reader = local_reader.get();
-    }
     const auto deadline =
         std::chrono::steady_clock::now() + std::chrono::seconds(30);
     const auto initial_retry_delay =
         std::chrono::milliseconds(std::max(config_.oplog_poll_interval_ms, 1));
     const auto max_retry_delay =
         std::max(initial_retry_delay, std::chrono::milliseconds(1000));
-    auto retry_delay = initial_retry_delay;
-    auto wait_to_retry = [&] {
-        const auto now = std::chrono::steady_clock::now();
-        if (now >= deadline) {
-            return false;
-        }
-        std::this_thread::sleep_for(std::min(
-            retry_delay, std::chrono::duration_cast<std::chrono::milliseconds>(
-                             deadline - now)));
-        retry_delay = std::min(retry_delay * 2, max_retry_delay);
-        return true;
-    };
-    for (;;) {
-        if (std::chrono::steady_clock::now() >= deadline) {
-            return ErrorCode::INCOMPLETE_OPLOG_CATCH_UP;
+
+    for (auto& [source_id, replica] : sources_) {
+        OpLogBatchStandbyReader* reader = replica.reader.get();
+        std::unique_ptr<OpLogBatchStandbyReader> local_reader;
+        if (reader == nullptr) {
+            local_reader = std::make_unique<OpLogBatchStandbyReader>(
+                cluster_id_, backend, *replica.applier, source_id);
+            reader = local_reader.get();
         }
-        auto result = reader->PollOnce();
-        if (result.error != ErrorCode::OK) {
-            if (result.disposition !=
-                    OpLogBatchStandbyPollDisposition::RETRYABLE ||
-                !wait_to_retry()) {
+
+        auto retry_delay = initial_retry_delay;
+        auto wait_to_retry = [&] {
+            const auto now = std::chrono::steady_clock::now();
+            if (now >= deadline) {
+                return false;
+            }
+            std::this_thread::sleep_for(std::min(
+                retry_delay,
+                std::chrono::duration_cast<std::chrono::milliseconds>(
+                    deadline - now)));
+            retry_delay = std::min(retry_delay * 2, max_retry_delay);
+            return true;
+        };
+        for (;;) {
+            if (std::chrono::steady_clock::now() >= deadline) {
                 return ErrorCode::INCOMPLETE_OPLOG_CATCH_UP;
             }
-            continue;
-        }
-        retry_delay = initial_retry_delay;
-        if (!result.durable_prefix_present) {
-            return GetLocalLastAppliedSequenceIdLocked() == 0
-                       ? ErrorCode::OK
-                       : ErrorCode::INCOMPLETE_OPLOG_CATCH_UP;
-        }
-        if (GetLocalLastAppliedSequenceIdLocked() >=
-            result.durable_prefix.last_seq) {
-            return ErrorCode::OK;
+            auto result = reader->PollOnce();
+            if (result.error != ErrorCode::OK) {
+                if (result.disposition !=
+                        OpLogBatchStandbyPollDisposition::RETRYABLE ||
+                    !wait_to_retry()) {
+                    return ErrorCode::INCOMPLETE_OPLOG_CATCH_UP;
+                }
+                continue;
+            }
+            retry_delay = initial_retry_delay;
+            if (!result.durable_prefix_present) {
+                break;  // Source has no OpLog yet.
+            }
+            const uint64_t expected = replica.applier->GetExpectedSequenceId();
+            const uint64_t source_applied = expected > 0 ? expected - 1 : 0;
+            if (source_applied >= result.durable_prefix.last_seq) {
+                break;  // This source is caught up.
+            }
         }
     }
+    return ErrorCode::OK;
 }
 
 ErrorCode HotStandbyService::Promote() {
@@ -661,11 +745,7 @@ ErrorCode HotStandbyService::PromoteAndExportSnapshot(StandbySnapshot& out) {
     } else {
         out.objects.clear();
     }
-    if (oplog_applier_) {
-        out.segments = oplog_applier_->GetSegmentRegistry().GetAllSegments();
-    } else {
-        out.segments.clear();
-    }
+    CollectSegmentsLocked(out.segments);
 
     lock.unlock();
     Stop();
@@ -686,13 +766,7 @@ size_t HotStandbyService::GetMetadataCount() const {
 
 uint64_t HotStandbyService::GetLatestAppliedSequenceId() const {
     std::lock_guard<std::mutex> lock(mutex_);
-    if (oplog_applier_) {
-        uint64_t expected_seq = oplog_applier_->GetExpectedSequenceId();
-        // GetExpectedSequenceId returns the next expected sequence_id,
-        // so the latest applied is expected_seq - 1
-        return expected_seq > 0 ? expected_seq - 1 : 0;
-    }
-    return applied_seq_id_.load();
+    return GetLocalLastAppliedSequenceIdLocked();
 }
 
 bool HotStandbyService::ExportMetadataSnapshot(
@@ -712,13 +786,8 @@ bool HotStandbyService::ExportStandbySnapshot(StandbySnapshot& out) const {
         return false;
     }
 
-    // Get applied sequence ID (inline to avoid recursive mutex lock)
-    if (oplog_applier_) {
-        uint64_t expected_seq = oplog_applier_->GetExpectedSequenceId();
-        out.oplog_sequence_id = expected_seq > 0 ? expected_seq - 1 : 0;
-    } else {
-        out.oplog_sequence_id = applied_seq_id_.load();
-    }
+    // Get applied sequence ID (max across per-source appliers)
+    out.oplog_sequence_id = GetLocalLastAppliedSequenceIdLocked();
 
     // Export object metadata
     if (metadata_store_) {
@@ -727,12 +796,8 @@ bool HotStandbyService::ExportStandbySnapshot(StandbySnapshot& out) const {
         out.objects.clear();
     }
 
-    // Export segments from OpLogApplier's registry (Patch B)
-    if (oplog_applier_) {
-        out.segments = oplog_applier_->GetSegmentRegistry().GetAllSegments();
-    } else {
-        out.segments.clear();
-    }
+    // Export segments merged across per-source appliers
+    CollectSegmentsLocked(out.segments);
 
     return true;
 }
@@ -775,10 +840,19 @@ void HotStandbyService::ReplicationLoop() {
             continue;
         }
 
-        if (batch_standby_reader_) {
+        // Poll each replay source independently. Sources own disjoint slot
+        // ranges and independent OpLog sequence spaces, so aggregate applied
+        // and primary sequence IDs as the max across all sources.
+        bool retry_backoff = false;
+        bool fatal = false;
+        for (auto& [source_id, replica] : sources_) {
+            if (!replica.reader) {
+                continue;
+            }
+
             const uint64_t expected_before =
-                oplog_applier_->GetExpectedSequenceId();
-            auto result = batch_standby_reader_->PollOnce();
+                replica.applier->GetExpectedSequenceId();
+            auto result = replica.reader->PollOnce();
             if (result.durable_prefix_present) {
                 const uint64_t current_primary = primary_seq_id_.load();
                 if (result.durable_prefix.last_seq > current_primary) {
@@ -787,10 +861,14 @@ void HotStandbyService::ReplicationLoop() {
             }
 
             const uint64_t expected_after =
-                oplog_applier_->GetExpectedSequenceId();
+                replica.applier->GetExpectedSequenceId();
             if (expected_after > 0) {
-                applied_seq_id_.store(expected_after - 1);
+                const uint64_t applied = expected_after - 1;
+                if (applied > applied_seq_id_.load()) {
+                    applied_seq_id_.store(applied);
+                }
             }
+
             if (result.error != ErrorCode::OK) {
                 last_error_.store(result.error, std::memory_order_release);
                 const bool made_progress = expected_after > expected_before;
@@ -803,39 +881,43 @@ void HotStandbyService::ReplicationLoop() {
                     }
                     if (now - *retry_started < retry_limit) {
                         LOG(WARNING)
-                            << "Transient batch-record standby poll failure, "
-                            << "retrying in " << retry_delay.count()
+                            << "Transient batch-record standby poll failure "
+                            << "for source=" << source_id << ", retrying in "
+                            << retry_delay.count()
                             << " ms, err=" << static_cast<int>(result.error);
                         NotifySyncStatus();
                         wait_for_next_poll(retry_delay);
                         retry_delay =
                             std::min(retry_delay * 2, max_retry_delay);
-                        continue;
+                        retry_backoff = true;
+                        break;
                     }
                     LOG(ERROR)
                         << "Batch-record standby retry timeout after "
                         << config_.batch_oplog_retry_timeout_sec
-                        << " seconds, err=" << static_cast<int>(result.error);
+                        << " seconds for source=" << source_id
+                        << ", err=" << static_cast<int>(result.error);
                 } else {
-                    LOG(ERROR) << "Fatal batch-record standby poll failure, "
-                               << "err=" << static_cast<int>(result.error);
+                    LOG(ERROR) << "Fatal batch-record standby poll failure "
+                               << "for source=" << source_id
+                               << ", err=" << static_cast<int>(result.error);
                 }
-                state_machine_.ProcessEvent(StandbyEvent::FATAL_ERROR);
-                replication_loop_cv_.notify_all();
+                fatal = true;
                 break;
             }
+
             retry_started.reset();
             retry_delay = retry_base;
             last_error_.store(ErrorCode::OK, std::memory_order_release);
         }
 
-        // Update applied_seq_id from OpLogApplier
-        if (oplog_applier_) {
-            uint64_t expected = oplog_applier_->GetExpectedSequenceId();
-            uint64_t current_applied = (expected > 0) ? (expected - 1) : 0;
-            if (current_applied > 0) {
-                applied_seq_id_.store(current_applied);
-            }
+        if (retry_backoff) {
+            continue;
+        }
+        if (fatal) {
+            state_machine_.ProcessEvent(StandbyEvent::FATAL_ERROR);
+            replication_loop_cv_.notify_all();
+            break;
         }
 
         const uint64_t applied_seq_id = applied_seq_id_.load();
diff --git a/mooncake-store/src/io_pattern/cfm_client_impl.cpp b/mooncake-store/src/io_pattern/cfm_client_impl.cpp
new file mode 100644
index 0000000000..b9973a5351
--- /dev/null
+++ b/mooncake-store/src/io_pattern/cfm_client_impl.cpp
@@ -0,0 +1,22 @@
+#include "io_pattern/cfm_client_impl.h"
+
+namespace mooncake::io_pattern {
+
+ErrorCode CfmClientImpl::ReportSnapshot(const IoPatternSnapshot& snapshot) {
+    if (!channel_) return ErrorCode::UNAVAILABLE_IN_CURRENT_MODE;
+    return channel_->SendSnapshot(snapshot) ? ErrorCode::OK
+                                            : ErrorCode::RPC_FAIL;
+}
+
+ErrorCode CfmClientImpl::ReportMetricBatch(const MetricBatch& batch) {
+    if (!channel_) return ErrorCode::UNAVAILABLE_IN_CURRENT_MODE;
+    return channel_->SendMetricBatch(batch) ? ErrorCode::OK
+                                            : ErrorCode::RPC_FAIL;
+}
+
+ErrorCode CfmClientImpl::ExecutePrefetch(const PrefetchPlan& plan) {
+    if (!channel_) return ErrorCode::UNAVAILABLE_IN_CURRENT_MODE;
+    return channel_->ExecutePrefetch(plan);
+}
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/src/io_pattern/cfm_ingress.cpp b/mooncake-store/src/io_pattern/cfm_ingress.cpp
new file mode 100644
index 0000000000..b281283d88
--- /dev/null
+++ b/mooncake-store/src/io_pattern/cfm_ingress.cpp
@@ -0,0 +1,67 @@
+#include "io_pattern/cfm_ingress.h"
+
+#include <chrono>
+
+namespace mooncake::io_pattern {
+
+bool CfmIngress::Handle(std::string_view method, std::string_view payload,
+                        std::string_view source_id) {
+    if (!runtime_ || !codec_) return false;
+    const std::string wire(payload);
+    if (method == "report_snapshot") {
+        const auto snapshot = codec_->DecodeSnapshot(wire);
+        if (!snapshot) return false;
+        runtime_->MergeSnapshot(*snapshot);
+        runtime_->RequestReportDrivenExecution();
+        return true;
+    }
+    if (method == "report_metric_batch") {
+        const auto batch = codec_->DecodeMetricBatch(wire);
+        if (!batch) return false;
+        const auto received_at_ns = static_cast<uint64_t>(
+            std::chrono::duration_cast<std::chrono::nanoseconds>(
+                std::chrono::steady_clock::now().time_since_epoch())
+                .count());
+        for (const auto& metric : batch->inference) {
+            runtime_->ReportInferenceMetrics(metric);
+        }
+        for (const auto& access : batch->accesses) {
+            auto normalized = access;
+            // steady_clock epochs are process-local. CFM observations must be
+            // rebased to the receiving Store's clock before windowing.
+            normalized.observed_at_ns = received_at_ns;
+            runtime_->RecordAccess(normalized.object.key, normalized);
+        }
+        for (const auto& storage : batch->storage) {
+            auto normalized = storage;
+            // The transport identity is authoritative for remote metrics. It
+            // keeps per-node watermarks distinct even when a producer omitted
+            // or accidentally reused StorageMetric::source_id.
+            if (!source_id.empty()) normalized.source_id = source_id;
+            normalized.observed_at_ns = received_at_ns;
+            runtime_->RecordStorageMetric(normalized);
+        }
+        // A merged report is a fresh aggregate: run the local policy cycle so
+        // eviction/prefetch/promotion/admission execution is driven by remote
+        // reports, not only by the local watermark/admission threads or
+        // explicit execute_* RPCs. RequestReportDrivenExecution is
+        // non-blocking and coalesces bursts on the runtime's worker.
+        if (!batch->inference.empty() || !batch->accesses.empty() ||
+            !batch->storage.empty()) {
+            runtime_->RequestReportDrivenExecution();
+        }
+        return true;
+    }
+    if (method == "execute_prefetch") {
+        const auto command = codec_->DecodePolicy(wire);
+        const auto* plan = command ? std::get_if<PrefetchPlan>(&*command) : nullptr;
+        return plan && runtime_->ExecuteCommand(*plan) == ErrorCode::OK;
+    }
+    if (method == "execute_policy") {
+        const auto command = codec_->DecodePolicy(wire);
+        return command && runtime_->ExecuteCommand(*command) == ErrorCode::OK;
+    }
+    return false;
+}
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/src/io_pattern/cfm_ownership_client.cpp b/mooncake-store/src/io_pattern/cfm_ownership_client.cpp
new file mode 100644
index 0000000000..cfb6e72b4a
--- /dev/null
+++ b/mooncake-store/src/io_pattern/cfm_ownership_client.cpp
@@ -0,0 +1,122 @@
+#include "io_pattern/cfm_ownership_client.h"
+
+#include <utility>
+
+namespace mooncake::io_pattern {
+
+CfmOwnershipClient::CfmOwnershipClient(SubmasterEndpointResolver resolver,
+                                       std::chrono::milliseconds timeout)
+    : resolver_(std::move(resolver)), timeout_(timeout) {}
+
+std::string CfmOwnershipClient::OwnerEndpoint(const ObjectRef& object) const {
+    if (!resolver_) return {};
+    const auto endpoint = resolver_(object.tenant_id, object.key);
+    return endpoint ? *endpoint : std::string{};
+}
+
+std::shared_ptr<CfmChannel> CfmOwnershipClient::ChannelFor(
+    const std::string& endpoint) {
+    if (endpoint.empty()) return nullptr;
+    {
+        std::lock_guard lock(channels_mutex_);
+        const auto existing = channels_.find(endpoint);
+        if (existing != channels_.end()) return existing->second;
+    }
+    auto transport = std::make_shared<CoroRpcCfmTransport>(endpoint, timeout_);
+    auto channel = std::make_shared<CfmRpcChannel>(
+        std::move(transport), std::make_shared<CfmBinaryCodec>(),
+        CfmRpcConfig{.timeout = timeout_});
+    std::lock_guard lock(channels_mutex_);
+    const auto inserted = channels_.emplace(endpoint, std::move(channel));
+    return inserted.first->second;
+}
+
+ErrorCode CfmOwnershipClient::ReportSnapshot(const IoPatternSnapshot& snapshot) {
+    // Bucket keys by their owning SubMaster and report one snapshot per owner.
+    // Storage observations are not routed by default: the SubMaster that owns
+    // the storage already reports its own watermark into its local runtime.
+    // When forward_storage_ is enabled (benchmark / simulation mode) every
+    // owner-addressed snapshot also carries the reported storage metrics so a
+    // remote run can drive the report-driven eviction dimension on each
+    // owning SubMaster.
+    std::unordered_map<std::string, IoPatternSnapshot> by_owner;
+    for (const auto& key : snapshot.keys) {
+        const auto endpoint = OwnerEndpoint(key.object);
+        if (endpoint.empty()) {
+            ++dropped_observations_;
+            continue;
+        }
+        auto& owned = by_owner[endpoint];
+        owned.generated_at_ns = snapshot.generated_at_ns;
+        owned.keys.push_back(key);
+    }
+    if (forward_storage_ && !snapshot.storage.empty() && !by_owner.empty()) {
+        for (auto& [endpoint, owned] : by_owner) {
+            (void)endpoint;
+            owned.storage = snapshot.storage;
+        }
+    }
+    bool all_ok = true;
+    for (const auto& [endpoint, owned] : by_owner) {
+        auto channel = ChannelFor(endpoint);
+        if (!channel || !channel->SendSnapshot(owned)) all_ok = false;
+    }
+    return all_ok ? ErrorCode::OK : ErrorCode::RPC_FAIL;
+}
+
+ErrorCode CfmOwnershipClient::ReportMetricBatch(const MetricBatch& batch) {
+    std::unordered_map<std::string, MetricBatch> by_owner;
+    for (const auto& metric : batch.inference) {
+        const auto endpoint = OwnerEndpoint(metric.object);
+        if (endpoint.empty()) {
+            ++dropped_observations_;
+            continue;
+        }
+        by_owner[endpoint].inference.push_back(metric);
+    }
+    for (const auto& access : batch.accesses) {
+        const auto endpoint = OwnerEndpoint(access.object);
+        if (endpoint.empty()) {
+            ++dropped_observations_;
+            continue;
+        }
+        by_owner[endpoint].accesses.push_back(access);
+    }
+    // batch.storage is intentionally not forwarded by default (see
+    // ReportSnapshot); forward_storage_ attaches it to every owner-addressed
+    // batch for benchmark / simulation runs.
+    if (forward_storage_ && !batch.storage.empty() && !by_owner.empty()) {
+        for (auto& [endpoint, owned] : by_owner) {
+            (void)endpoint;
+            owned.storage = batch.storage;
+        }
+    }
+    bool all_ok = true;
+    for (const auto& [endpoint, owned] : by_owner) {
+        auto channel = ChannelFor(endpoint);
+        if (!channel || !channel->SendMetricBatch(owned)) all_ok = false;
+    }
+    return all_ok ? ErrorCode::OK : ErrorCode::RPC_FAIL;
+}
+
+ErrorCode CfmOwnershipClient::ExecutePrefetch(const PrefetchPlan& plan) {
+    if (plan.candidates.empty()) return ErrorCode::OK;
+    // Address the plan to the SubMaster owning the first candidate object;
+    // a plan produced by one SubMaster concerns keys it owns, so routing by
+    // the primary candidate keeps a single endpoint target in practice.
+    const auto endpoint = OwnerEndpoint(plan.candidates.front().object);
+    if (endpoint.empty()) {
+        ++dropped_observations_;
+        return ErrorCode::OBJECT_NOT_FOUND;
+    }
+    auto channel = ChannelFor(endpoint);
+    if (!channel) return ErrorCode::RPC_FAIL;
+    const auto code = channel->ExecutePrefetch(plan);
+    return code == ErrorCode::OK ? ErrorCode::OK : ErrorCode::RPC_FAIL;
+}
+
+uint64_t CfmOwnershipClient::dropped_observations() const {
+    return dropped_observations_.load(std::memory_order_relaxed);
+}
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/src/io_pattern/cfm_protocol.cpp b/mooncake-store/src/io_pattern/cfm_protocol.cpp
new file mode 100644
index 0000000000..8b5886b09b
--- /dev/null
+++ b/mooncake-store/src/io_pattern/cfm_protocol.cpp
@@ -0,0 +1,451 @@
+#include "io_pattern/cfm_protocol.h"
+
+#include <cstring>
+#include <limits>
+#include <type_traits>
+
+namespace mooncake::io_pattern {
+namespace {
+
+constexpr char kWireVersion[] = "CFM2";
+constexpr size_t kMaxWireStringBytes = 16 * 1024 * 1024;
+constexpr size_t kMaxWirePayloadBytes = 64 * 1024 * 1024;
+constexpr uint32_t kMaxWireRecords = 1'000'000;
+
+template <typename T>
+void Append(std::string& out, T value) {
+    static_assert(std::is_trivially_copyable_v<T>);
+    const auto* bytes = reinterpret_cast<const char*>(&value);
+    out.append(bytes, sizeof(value));
+}
+
+template <typename T>
+bool Read(const std::string& input, size_t& offset, T& value) {
+    static_assert(std::is_trivially_copyable_v<T>);
+    if (input.size() - offset < sizeof(value)) return false;
+    std::memcpy(&value, input.data() + offset, sizeof(value));
+    offset += sizeof(value);
+    return true;
+}
+
+void AppendString(std::string& out, const std::string& value) {
+    const auto size = static_cast<uint32_t>(value.size());
+    Append(out, size);
+    out.append(value);
+}
+
+bool ReadString(const std::string& input, size_t& offset, std::string& value) {
+    uint32_t size = 0;
+    if (!Read(input, offset, size) || size > kMaxWireStringBytes ||
+        input.size() - offset < size) {
+        return false;
+    }
+    value.assign(input.data() + offset, size);
+    offset += size;
+    return true;
+}
+
+void AppendObject(std::string& out, const ObjectRef& object) {
+    AppendString(out, object.tenant_id.value());
+    AppendString(out, object.key);
+}
+
+bool ReadObject(const std::string& input, size_t& offset, ObjectRef& object) {
+    std::string tenant;
+    if (!ReadString(input, offset, tenant) || !ReadString(input, offset, object.key)) {
+        return false;
+    }
+    object.tenant_id = TenantId(std::move(tenant));
+    return true;
+}
+
+template <typename Enum>
+void AppendEnum(std::string& out, Enum value) {
+    Append(out, static_cast<uint8_t>(value));
+}
+
+template <typename Enum>
+bool ReadEnum(const std::string& input, size_t& offset, Enum& value) {
+    uint8_t raw = 0;
+    if (!Read(input, offset, raw)) return false;
+    value = static_cast<Enum>(raw);
+    return true;
+}
+
+void AppendPrefetchPlan(std::string& out, const PrefetchPlan& plan) {
+    AppendEnum(out, plan.strategy);
+    Append(out, plan.timeout_us);
+    Append(out, static_cast<uint32_t>(plan.candidates.size()));
+    for (const auto& candidate : plan.candidates) {
+        AppendObject(out, candidate.object);
+        AppendEnum(out, candidate.source_tier);
+        AppendEnum(out, candidate.target_tier);
+        Append(out, candidate.bytes);
+        Append(out, candidate.priority);
+        Append(out, candidate.confidence);
+    }
+}
+
+bool ReadPrefetchPlan(const std::string& input, size_t& offset, PrefetchPlan& plan) {
+    uint32_t count = 0;
+    if (!ReadEnum(input, offset, plan.strategy) || !Read(input, offset, plan.timeout_us) ||
+        !Read(input, offset, count) || count > kMaxWireRecords) {
+        return false;
+    }
+    plan.candidates.clear();
+    plan.candidates.reserve(count);
+    for (uint32_t index = 0; index < count; ++index) {
+        PrefetchCandidate candidate;
+        if (!ReadObject(input, offset, candidate.object) ||
+            !ReadEnum(input, offset, candidate.source_tier) ||
+            !ReadEnum(input, offset, candidate.target_tier) ||
+            !Read(input, offset, candidate.bytes) ||
+            !Read(input, offset, candidate.priority) ||
+            !Read(input, offset, candidate.confidence)) {
+            return false;
+        }
+        plan.candidates.push_back(std::move(candidate));
+    }
+    return true;
+}
+
+void AppendStorageMetric(std::string& out, const StorageMetric& storage) {
+    AppendString(out, storage.source_id);
+    Append(out, storage.observed_at_ns);
+    AppendEnum(out, storage.tier);
+    AppendEnum(out, storage.gc_state);
+    Append(out, storage.read_bandwidth_bytes_per_sec);
+    Append(out, storage.write_bandwidth_bytes_per_sec);
+    Append(out, storage.read_latency_us);
+    Append(out, storage.write_latency_us);
+    Append(out, storage.used_bytes);
+    Append(out, storage.capacity_bytes);
+    Append(out, storage.rpc_latency_us);
+    Append(out, storage.memory_used_ratio);
+}
+
+bool ReadStorageMetric(const std::string& input, size_t& offset,
+                       StorageMetric& storage) {
+    return ReadString(input, offset, storage.source_id) &&
+           Read(input, offset, storage.observed_at_ns) &&
+           ReadEnum(input, offset, storage.tier) &&
+           ReadEnum(input, offset, storage.gc_state) &&
+           Read(input, offset, storage.read_bandwidth_bytes_per_sec) &&
+           Read(input, offset, storage.write_bandwidth_bytes_per_sec) &&
+           Read(input, offset, storage.read_latency_us) &&
+           Read(input, offset, storage.write_latency_us) &&
+           Read(input, offset, storage.used_bytes) &&
+           Read(input, offset, storage.capacity_bytes) &&
+           Read(input, offset, storage.rpc_latency_us) &&
+           Read(input, offset, storage.memory_used_ratio);
+}
+
+void AppendHeader(std::string& out, char type) {
+    out.append(kWireVersion, sizeof(kWireVersion) - 1);
+    out.push_back(type);
+}
+
+bool ReadHeader(const std::string& input, size_t& offset, char& type) {
+    if (input.size() < sizeof(kWireVersion) || input.size() > kMaxWirePayloadBytes ||
+        input.compare(0, sizeof(kWireVersion) - 1, kWireVersion) != 0) {
+        return false;
+    }
+    offset = sizeof(kWireVersion) - 1;
+    return Read(input, offset, type);
+}
+
+}  // namespace
+
+std::string CfmBinaryCodec::EncodeSnapshot(const IoPatternSnapshot& snapshot) const {
+    std::string output;
+    AppendHeader(output, 'S');
+    Append(output, snapshot.generated_at_ns);
+    Append(output, static_cast<uint32_t>(snapshot.keys.size()));
+    for (const auto& key : snapshot.keys) {
+        AppendObject(output, key.object);
+        AppendString(output, key.session_id);
+        Append(output, key.last_access_time_ns);
+        Append(output, key.access_count_window);
+        Append(output, key.idle_time_us);
+        Append(output, key.block_size);
+        Append(output, key.transfer_eta_us);
+        Append(output, key.token_count);
+        Append(output, key.prefix_depth);
+        Append(output, key.prefix_fanout);
+        Append(output, key.match_length);
+        Append(output, key.continuous_prefix_length);
+        Append(output, key.other_replica_count);
+        Append(output, key.write_batch_size);
+        Append(output, key.write_frequency);
+        Append(output, key.write_object_size);
+        Append(output, key.recompute_cost);
+        Append(output, key.overwrite_ratio);
+        Append(output, key.replica_tiers);
+        AppendEnum(output, key.layout);
+        Append(output, key.layout_group);
+        Append(output, key.request_priority);
+        Append(output, key.active);
+        Append(output, key.pinned);
+        Append(output, key.ssd_replica_exists);
+        Append(output, key.write_burst);
+    }
+    Append(output, static_cast<uint32_t>(snapshot.storage.size()));
+    for (const auto& storage : snapshot.storage) {
+        AppendStorageMetric(output, storage);
+    }
+    return output;
+}
+
+std::string CfmBinaryCodec::EncodePrefetch(const PrefetchPlan& plan) const {
+    std::string output;
+    AppendHeader(output, 'P');
+    AppendPrefetchPlan(output, plan);
+    return output;
+}
+
+std::string CfmBinaryCodec::EncodeMetricBatch(const MetricBatch& batch) const {
+    std::string output;
+    AppendHeader(output, 'M');
+    Append(output, static_cast<uint32_t>(batch.inference.size()));
+    for (const auto& metric : batch.inference) {
+        AppendObject(output, metric.object);
+        AppendString(output, metric.session_id);
+        Append(output, metric.prefix_depth);
+        Append(output, metric.prefix_fanout);
+        Append(output, metric.match_length);
+        Append(output, metric.continuous_prefix_length);
+        Append(output, metric.token_count);
+        Append(output, metric.recompute_cost);
+        Append(output, metric.request_priority);
+        AppendEnum(output, metric.layout);
+        Append(output, metric.layout_group);
+    }
+    Append(output, static_cast<uint32_t>(batch.accesses.size()));
+    for (const auto& access : batch.accesses) {
+        AppendObject(output, access.object);
+        Append(output, access.observed_at_ns);
+        Append(output, access.block_size);
+        Append(output, access.latency_us);
+        AppendEnum(output, access.tier);
+        AppendEnum(output, access.operation);
+        Append(output, access.is_hit);
+        Append(output, access.write_batch_size);
+        Append(output, access.overwrite);
+    }
+    Append(output, static_cast<uint32_t>(batch.storage.size()));
+    for (const auto& storage : batch.storage) {
+        AppendStorageMetric(output, storage);
+    }
+    return output;
+}
+
+std::string CfmBinaryCodec::EncodePolicy(const PolicyCommand& command) const {
+    std::string output;
+    if (const auto* eviction = std::get_if<EvictionPlan>(&command)) {
+        AppendHeader(output, 'E');
+        AppendEnum(output, eviction->source_tier);
+        Append(output, eviction->target_bytes);
+        Append(output, static_cast<uint32_t>(eviction->candidates.size()));
+        for (const auto& candidate : eviction->candidates) {
+            AppendObject(output, candidate.object);
+            Append(output, candidate.bytes);
+            Append(output, candidate.score);
+            AppendEnum(output, candidate.target_tier);
+        }
+        // Tier-down trailer, appended after the original layout so a decoder
+        // that predates it still finds the candidate list it expects. Without
+        // this a plan sent to a remote SubMaster would arrive as pure eviction
+        // and the executor would reclaim the keys the driver meant to keep.
+        Append(output, eviction->tier_down_target_bytes);
+        for (const auto& candidate : eviction->candidates) {
+            AppendEnum(output, candidate.action);
+        }
+    } else if (const auto* prefetch = std::get_if<PrefetchPlan>(&command)) {
+        AppendHeader(output, 'P');
+        AppendPrefetchPlan(output, *prefetch);
+    } else {
+        const auto& admission = std::get<AdmissionResult>(command);
+        AppendHeader(output, 'A');
+        AppendObject(output, admission.object);
+        AppendEnum(output, admission.target_tier);
+        AppendEnum(output, admission.decision);
+        Append(output, admission.confidence);
+    }
+    return output;
+}
+
+std::optional<PolicyCommand> CfmBinaryCodec::DecodePolicy(
+    const std::string& payload) const {
+    size_t offset = 0;
+    char type = 0;
+    if (!ReadHeader(payload, offset, type)) return std::nullopt;
+    if (type == 'P') {
+        PrefetchPlan plan;
+        return ReadPrefetchPlan(payload, offset, plan) && offset == payload.size()
+                   ? std::optional<PolicyCommand>(std::move(plan))
+                   : std::nullopt;
+    }
+    if (type == 'E') {
+        EvictionPlan plan;
+        uint32_t count = 0;
+        if (!ReadEnum(payload, offset, plan.source_tier) ||
+            !Read(payload, offset, plan.target_bytes) ||
+            !Read(payload, offset, count) || count > kMaxWireRecords) {
+            return std::nullopt;
+        }
+        plan.candidates.reserve(count);
+        for (uint32_t index = 0; index < count; ++index) {
+            EvictionCandidate candidate;
+            if (!ReadObject(payload, offset, candidate.object) ||
+                !Read(payload, offset, candidate.bytes) ||
+                !Read(payload, offset, candidate.score) ||
+                !ReadEnum(payload, offset, candidate.target_tier)) {
+                return std::nullopt;
+            }
+            plan.candidates.push_back(std::move(candidate));
+        }
+        // Optional tier-down trailer. A payload encoded before tier down existed
+        // ends here, and both fields keep their defaults (kEvict / 0), which is
+        // exactly the pre-tier-down meaning of the plan. A partly written trailer
+        // is a decode error rather than a silent default.
+        if (offset < payload.size()) {
+            if (!Read(payload, offset, plan.tier_down_target_bytes)) {
+                return std::nullopt;
+            }
+            for (auto& candidate : plan.candidates) {
+                uint8_t raw_action = 0;
+                if (!Read(payload, offset, raw_action) ||
+                    raw_action >
+                        static_cast<uint8_t>(EvictionAction::kTierDown)) {
+                    return std::nullopt;
+                }
+                candidate.action = static_cast<EvictionAction>(raw_action);
+            }
+        }
+        return offset == payload.size()
+                   ? std::optional<PolicyCommand>(std::move(plan))
+                   : std::nullopt;
+    }
+    if (type == 'A') {
+        AdmissionResult result;
+        if (!ReadObject(payload, offset, result.object) ||
+            !ReadEnum(payload, offset, result.target_tier) ||
+            !ReadEnum(payload, offset, result.decision) ||
+            !Read(payload, offset, result.confidence) || offset != payload.size()) {
+            return std::nullopt;
+        }
+        return result;
+    }
+    return std::nullopt;
+}
+
+std::optional<IoPatternSnapshot> CfmBinaryCodec::DecodeSnapshot(
+    const std::string& payload) const {
+    size_t offset = 0;
+    char type = 0;
+    IoPatternSnapshot snapshot;
+    uint32_t key_count = 0;
+    if (!ReadHeader(payload, offset, type) || type != 'S' ||
+        !Read(payload, offset, snapshot.generated_at_ns) ||
+        !Read(payload, offset, key_count) || key_count > kMaxWireRecords) {
+        return std::nullopt;
+    }
+    snapshot.keys.reserve(key_count);
+    for (uint32_t index = 0; index < key_count; ++index) {
+        KeyMetrics key;
+        if (!ReadObject(payload, offset, key.object) ||
+            !ReadString(payload, offset, key.session_id) ||
+            !Read(payload, offset, key.last_access_time_ns) ||
+            !Read(payload, offset, key.access_count_window) ||
+            !Read(payload, offset, key.idle_time_us) ||
+            !Read(payload, offset, key.block_size) ||
+            !Read(payload, offset, key.transfer_eta_us) ||
+            !Read(payload, offset, key.token_count) ||
+            !Read(payload, offset, key.prefix_depth) ||
+            !Read(payload, offset, key.prefix_fanout) ||
+            !Read(payload, offset, key.match_length) ||
+            !Read(payload, offset, key.continuous_prefix_length) ||
+            !Read(payload, offset, key.other_replica_count) ||
+            !Read(payload, offset, key.write_batch_size) ||
+            !Read(payload, offset, key.write_frequency) ||
+            !Read(payload, offset, key.write_object_size) ||
+            !Read(payload, offset, key.recompute_cost) ||
+            !Read(payload, offset, key.overwrite_ratio) ||
+            !Read(payload, offset, key.replica_tiers) ||
+            !ReadEnum(payload, offset, key.layout) ||
+            !Read(payload, offset, key.layout_group) ||
+            !Read(payload, offset, key.request_priority) ||
+            !Read(payload, offset, key.active) || !Read(payload, offset, key.pinned) ||
+            !Read(payload, offset, key.ssd_replica_exists) ||
+            !Read(payload, offset, key.write_burst)) {
+            return std::nullopt;
+        }
+        snapshot.keys.push_back(std::move(key));
+    }
+    uint32_t storage_count = 0;
+    if (!Read(payload, offset, storage_count) || storage_count > kMaxWireRecords) {
+        return std::nullopt;
+    }
+    snapshot.storage.reserve(storage_count);
+    for (uint32_t index = 0; index < storage_count; ++index) {
+        StorageMetric storage;
+        if (!ReadStorageMetric(payload, offset, storage)) return std::nullopt;
+        snapshot.storage.push_back(std::move(storage));
+    }
+    return offset == payload.size() ? std::optional<IoPatternSnapshot>(std::move(snapshot))
+                                    : std::nullopt;
+}
+
+std::optional<MetricBatch> CfmBinaryCodec::DecodeMetricBatch(
+    const std::string& payload) const {
+    size_t offset = 0;
+    char type = 0;
+    MetricBatch batch;
+    uint32_t count = 0;
+    if (!ReadHeader(payload, offset, type) || type != 'M' ||
+        !Read(payload, offset, count) || count > kMaxWireRecords) {
+        return std::nullopt;
+    }
+    batch.inference.reserve(count);
+    for (uint32_t index = 0; index < count; ++index) {
+        InferenceMetrics metric;
+        if (!ReadObject(payload, offset, metric.object) ||
+            !ReadString(payload, offset, metric.session_id) ||
+            !Read(payload, offset, metric.prefix_depth) ||
+            !Read(payload, offset, metric.prefix_fanout) ||
+            !Read(payload, offset, metric.match_length) ||
+            !Read(payload, offset, metric.continuous_prefix_length) ||
+            !Read(payload, offset, metric.token_count) ||
+            !Read(payload, offset, metric.recompute_cost) ||
+            !Read(payload, offset, metric.request_priority) ||
+            !ReadEnum(payload, offset, metric.layout) ||
+            !Read(payload, offset, metric.layout_group)) return std::nullopt;
+        batch.inference.push_back(std::move(metric));
+    }
+    if (!Read(payload, offset, count) || count > kMaxWireRecords) return std::nullopt;
+    batch.accesses.reserve(count);
+    for (uint32_t index = 0; index < count; ++index) {
+        AccessRecord access;
+        if (!ReadObject(payload, offset, access.object) ||
+            !Read(payload, offset, access.observed_at_ns) ||
+            !Read(payload, offset, access.block_size) ||
+            !Read(payload, offset, access.latency_us) ||
+            !ReadEnum(payload, offset, access.tier) ||
+            !ReadEnum(payload, offset, access.operation) ||
+            !Read(payload, offset, access.is_hit) ||
+            !Read(payload, offset, access.write_batch_size) ||
+            !Read(payload, offset, access.overwrite)) return std::nullopt;
+        batch.accesses.push_back(std::move(access));
+    }
+    if (!Read(payload, offset, count) || count > kMaxWireRecords) return std::nullopt;
+    batch.storage.reserve(count);
+    for (uint32_t index = 0; index < count; ++index) {
+        StorageMetric storage;
+        if (!ReadStorageMetric(payload, offset, storage)) return std::nullopt;
+        batch.storage.push_back(std::move(storage));
+    }
+    return offset == payload.size() ? std::optional<MetricBatch>(std::move(batch))
+                                    : std::nullopt;
+}
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/src/io_pattern/cfm_service.cpp b/mooncake-store/src/io_pattern/cfm_service.cpp
new file mode 100644
index 0000000000..132bc9231a
--- /dev/null
+++ b/mooncake-store/src/io_pattern/cfm_service.cpp
@@ -0,0 +1,36 @@
+#include "io_pattern/cfm_service.h"
+
+#include <string>
+
+namespace mooncake::io_pattern {
+
+CfmService::CfmService(std::shared_ptr<IoPatternRuntime> runtime)
+    : runtime_(std::move(runtime)),
+      codec_(std::make_shared<CfmBinaryCodec>()),
+      ingress_(runtime_, codec_) {}
+
+bool CfmService::Send(std::string_view method, std::string_view payload,
+                      std::string_view source_id) {
+    // CFM is a component of this SubMaster: there is no per-reporting-node
+    // runtime and no policy delivery queue. Every accepted method is handled
+    // by the ingress against the local runtime so that collection, analysis
+    // and execution all observe the keys this SubMaster owns.
+    return ingress_.Handle(method, payload, source_id);
+}
+
+IoPatternSnapshot CfmService::Snapshot() const {
+    return runtime_ ? runtime_->Snapshot() : IoPatternSnapshot{};
+}
+
+IoPatternObservabilitySnapshot CfmService::Observability(
+    double window_seconds) const {
+    return runtime_ ? runtime_->ObservabilitySnapshot(window_seconds)
+                    : IoPatternObservabilitySnapshot{};
+}
+
+bool CfmRpcService::Send(const std::string& method, const std::string& payload,
+                         const std::string& source_id) {
+    return service_ && service_->Send(method, payload, source_id);
+}
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/src/io_pattern/collector_impl.cpp b/mooncake-store/src/io_pattern/collector_impl.cpp
new file mode 100644
index 0000000000..7adcb97aec
--- /dev/null
+++ b/mooncake-store/src/io_pattern/collector_impl.cpp
@@ -0,0 +1,313 @@
+#include "io_pattern/collector_impl.h"
+
+#include <algorithm>
+#include <chrono>
+#include <limits>
+#include <utility>
+
+namespace mooncake::io_pattern {
+namespace {
+uint64_t NowNs() {
+    return static_cast<uint64_t>(std::chrono::duration_cast<std::chrono::nanoseconds>(
+                                     std::chrono::steady_clock::now().time_since_epoch())
+                                     .count());
+}
+}
+
+void IoPatternCollectorImpl::ApplyAccessWindow(const ObjectRef& object,
+                                               uint64_t now_ns,
+                                               KeyMetrics& metrics) const {
+    metrics.access_count_window = 0;
+    metrics.write_frequency = 0;
+    metrics.overwrite_ratio = 0.0F;
+    metrics.write_batch_size = 0;
+    metrics.write_burst = false;
+    const auto it = access_windows_.find(object);
+    if (it == access_windows_.end()) return;
+
+    const uint64_t cutoff = config_.access_window_ns != 0 &&
+                                    now_ns > config_.access_window_ns
+                                ? now_ns - config_.access_window_ns
+                                : 0;
+    uint64_t writes = 0;
+    uint64_t overwrites = 0;
+    for (const auto& bucket : it->second) {
+        if (config_.access_window_ns != 0 && bucket.observed_at_ns < cutoff) {
+            continue;
+        }
+        metrics.access_count_window += bucket.access_count;
+        writes += bucket.write_count;
+        overwrites += bucket.overwrite_count;
+        metrics.write_batch_size =
+            std::max(metrics.write_batch_size, bucket.max_write_batch_size);
+    }
+    metrics.write_frequency =
+        static_cast<uint32_t>(std::min<uint64_t>(
+            writes, std::numeric_limits<uint32_t>::max()));
+    if (writes != 0) {
+        metrics.overwrite_ratio = static_cast<float>(overwrites) /
+                                  static_cast<float>(writes);
+    }
+    metrics.write_burst = metrics.write_batch_size >= 16;
+}
+
+void IoPatternCollectorImpl::ReportInferenceMetrics(
+    const InferenceMetrics& metrics) {
+    std::lock_guard lock(mutex_);
+    if (reporter_ && !reporter_->Enqueue(metrics)) ++dropped_;
+    if (!key_metrics_.contains(metrics.object) && config_.max_total_keys != 0 &&
+        key_metrics_.size() >= config_.max_total_keys) {
+        degraded_ = true;
+        ++dropped_;
+        return;
+    }
+    if (!key_metrics_.contains(metrics.object) &&
+        config_.max_keys_per_tenant != 0 &&
+        tenant_key_counts_[metrics.object.tenant_id] >=
+            config_.max_keys_per_tenant) {
+        ++dropped_;
+        return;
+    }
+    if (!key_metrics_.contains(metrics.object))
+        ++tenant_key_counts_[metrics.object.tenant_id];
+    auto& value = key_metrics_[metrics.object];
+    value.object = metrics.object;
+    value.session_id = metrics.session_id;
+    value.layout = metrics.layout;
+    value.layout_group = metrics.layout_group;
+    value.prefix_depth = metrics.prefix_depth;
+    value.prefix_fanout = metrics.prefix_fanout;
+    value.match_length = metrics.match_length;
+    value.continuous_prefix_length = metrics.continuous_prefix_length;
+    value.token_count = metrics.token_count;
+    value.recompute_cost = metrics.recompute_cost;
+    value.request_priority = metrics.request_priority;
+}
+
+void IoPatternCollectorImpl::RecordAccess(const std::string& key,
+                                          const AccessRecord& record) {
+    std::lock_guard lock(mutex_);
+    if (reporter_ && !reporter_->EnqueueAccess(record)) ++dropped_;
+    ObjectRef object = record.object;
+    if (!key.empty()) object.key = key;
+    if (!key_metrics_.contains(object) && config_.max_total_keys != 0 &&
+        key_metrics_.size() >= config_.max_total_keys) {
+        degraded_ = true;
+        ++dropped_;
+        return;
+    }
+    if (!key_metrics_.contains(object) && config_.max_keys_per_tenant != 0 &&
+        tenant_key_counts_[object.tenant_id] >= config_.max_keys_per_tenant) {
+        ++dropped_;
+        return;
+    }
+    if (!key_metrics_.contains(object)) ++tenant_key_counts_[object.tenant_id];
+    auto& value = key_metrics_[object];
+    value.object = object;
+    const uint64_t observed_at_ns =
+        record.observed_at_ns == 0
+            ? (config_.now_ns ? config_.now_ns() : NowNs())
+            : record.observed_at_ns;
+    auto& window = access_windows_[object];
+    const uint64_t bucket_ns = std::max<uint64_t>(1, config_.access_bucket_ns);
+    const uint64_t bucket_timestamp =
+        observed_at_ns - (observed_at_ns % bucket_ns);
+    const uint64_t reference_ns =
+        window.empty() ? observed_at_ns
+                       : std::max(observed_at_ns,
+                                  window.back().observed_at_ns);
+    AccessWindowBucket bucket{.observed_at_ns = bucket_timestamp,
+                              .access_count = 1};
+    if (record.operation == IoOperation::kPut) {
+        bucket.write_count = 1;
+        bucket.overwrite_count = record.overwrite ? 1 : 0;
+        bucket.max_write_batch_size = record.write_batch_size;
+    }
+    const auto position = std::lower_bound(
+        window.begin(), window.end(), bucket_timestamp,
+        [](const AccessWindowBucket& existing, uint64_t timestamp) {
+            return existing.observed_at_ns < timestamp;
+        });
+    if (position != window.end() &&
+        position->observed_at_ns == bucket_timestamp) {
+        position->access_count += bucket.access_count;
+        position->write_count += bucket.write_count;
+        position->overwrite_count += bucket.overwrite_count;
+        position->max_write_batch_size = std::max(
+            position->max_write_batch_size, bucket.max_write_batch_size);
+    } else {
+        window.insert(position, bucket);
+    }
+    const uint64_t cutoff = config_.access_window_ns != 0 &&
+                                    reference_ns > config_.access_window_ns
+                                ? reference_ns - config_.access_window_ns
+                                : 0;
+    while (!window.empty() && config_.access_window_ns != 0 &&
+           window.front().observed_at_ns < cutoff) {
+        window.pop_front();
+    }
+    while (config_.max_access_buckets_per_key != 0 &&
+           window.size() > config_.max_access_buckets_per_key) {
+        window.pop_front();
+    }
+    value.last_access_time_ns =
+        std::max(value.last_access_time_ns, observed_at_ns);
+    value.block_size = std::max(value.block_size, record.block_size);
+    value.replica_tiers |= CacheTierBit(record.tier);
+    value.active = value.active || record.is_hit;
+    if (record.operation == IoOperation::kPut) {
+        value.write_object_size = std::max(value.write_object_size,
+                                           record.block_size);
+    }
+    ApplyAccessWindow(object, observed_at_ns, value);
+}
+
+void IoPatternCollectorImpl::RecordStorageMetric(const StorageMetric& metric) {
+    std::lock_guard lock(mutex_);
+    if (reporter_) {
+        reporter_->UpdateLoad(metric.memory_used_ratio, metric.rpc_latency_us);
+        if (!reporter_->EnqueueStorage(metric)) ++dropped_;
+    }
+    StorageMetricKey key{metric.source_id, metric.tier};
+    auto it = storage_metrics_.find(key);
+    if (it == storage_metrics_.end() ||
+        metric.observed_at_ns >= it->second.observed_at_ns) {
+        storage_metrics_[std::move(key)] = metric;
+    }
+}
+
+void IoPatternCollectorImpl::MergeSnapshot(const IoPatternSnapshot& snapshot) {
+    std::lock_guard lock(mutex_);
+    const uint64_t received_at_ns = config_.now_ns ? config_.now_ns() : NowNs();
+    for (const auto& metrics : snapshot.keys) {
+        if (!key_metrics_.contains(metrics.object) &&
+            config_.max_total_keys != 0 &&
+            key_metrics_.size() >= config_.max_total_keys) {
+            degraded_ = true;
+            ++dropped_;
+            continue;
+        }
+        if (!key_metrics_.contains(metrics.object) &&
+            config_.max_keys_per_tenant != 0 &&
+            tenant_key_counts_[metrics.object.tenant_id] >=
+                config_.max_keys_per_tenant) {
+            ++dropped_;
+            continue;
+        }
+        if (!key_metrics_.contains(metrics.object)) {
+            ++tenant_key_counts_[metrics.object.tenant_id];
+        }
+        key_metrics_[metrics.object] = metrics;
+        auto& window = access_windows_[metrics.object];
+        window.clear();
+        window.push_back({.observed_at_ns = received_at_ns,
+                          .access_count = metrics.access_count_window,
+                          .write_count = metrics.write_frequency,
+                          .overwrite_count = static_cast<uint64_t>(
+                              metrics.overwrite_ratio *
+                              static_cast<float>(metrics.write_frequency)),
+                          .max_write_batch_size = metrics.write_batch_size});
+    }
+    for (const auto& metric : snapshot.storage) {
+        StorageMetricKey key{metric.source_id, metric.tier};
+        auto it = storage_metrics_.find(key);
+        if (it == storage_metrics_.end() ||
+            metric.observed_at_ns >= it->second.observed_at_ns) {
+            storage_metrics_[std::move(key)] = metric;
+        }
+    }
+}
+
+void IoPatternCollectorImpl::RecordTierEvent(const CacheEvent& event) {
+    if (event.type == CacheEventType::kUnknown) {
+        return;
+    }
+    std::lock_guard lock(mutex_);
+    const auto it = key_metrics_.find(event.object);
+    if (it == key_metrics_.end()) {
+        return;
+    }
+    const auto with_tier = [](CacheTierMask mask, CacheTier tier,
+                              bool present) -> CacheTierMask {
+        const CacheTierMask bit = CacheTierBit(tier);
+        return present ? static_cast<CacheTierMask>(mask | bit)
+                       : static_cast<CacheTierMask>(mask & ~bit);
+    };
+    switch (event.type) {
+        case CacheEventType::kInserted:
+            it->second.replica_tiers =
+                with_tier(it->second.replica_tiers, event.target_tier, true);
+            break;
+        case CacheEventType::kRemoved:
+            it->second.replica_tiers =
+                with_tier(it->second.replica_tiers, event.source_tier, false);
+            break;
+        case CacheEventType::kTierChanged:
+            it->second.replica_tiers =
+                with_tier(it->second.replica_tiers, event.source_tier, false);
+            it->second.replica_tiers =
+                with_tier(it->second.replica_tiers, event.target_tier, true);
+            break;
+        case CacheEventType::kUnknown:
+            return;
+    }
+}
+
+IoPatternSnapshot IoPatternCollectorImpl::GetSnapshot() const {
+    std::lock_guard lock(mutex_);
+    IoPatternSnapshot snapshot;
+    snapshot.generated_at_ns = config_.now_ns ? config_.now_ns() : NowNs();
+    snapshot.keys.reserve(key_metrics_.size());
+    for (const auto& [object, metrics] : key_metrics_) {
+        auto copy = metrics;
+        ApplyAccessWindow(object, snapshot.generated_at_ns, copy);
+        if (copy.last_access_time_ns != 0 &&
+            snapshot.generated_at_ns > copy.last_access_time_ns) {
+            copy.idle_time_us =
+                (snapshot.generated_at_ns - copy.last_access_time_ns) / 1000;
+        }
+        snapshot.keys.push_back(std::move(copy));
+    }
+    snapshot.storage.reserve(storage_metrics_.size());
+    for (const auto& [key, metric] : storage_metrics_) {
+        (void)key;
+        snapshot.storage.push_back(metric);
+    }
+    std::sort(snapshot.keys.begin(), snapshot.keys.end(),
+              [](const KeyMetrics& a, const KeyMetrics& b) {
+                  if (a.object.tenant_id != b.object.tenant_id)
+                      return a.object.tenant_id < b.object.tenant_id;
+                  return a.object.key < b.object.key;
+              });
+    return snapshot;
+}
+
+uint64_t IoPatternCollectorImpl::dropped() const {
+    std::lock_guard lock(mutex_);
+    return dropped_;
+}
+
+bool IoPatternCollectorImpl::degraded() const {
+    std::lock_guard lock(mutex_);
+    return degraded_;
+}
+
+bool IoPatternCollectorImpl::FlushReports() {
+    std::shared_ptr<IoPatternReporter> reporter;
+    {
+        std::lock_guard lock(mutex_);
+        reporter = reporter_;
+    }
+    return !reporter || reporter->Flush();
+}
+
+void IoPatternCollectorImpl::StopReports() {
+    std::shared_ptr<IoPatternReporter> reporter;
+    {
+        std::lock_guard lock(mutex_);
+        reporter = reporter_;
+    }
+    if (reporter) reporter->Stop();
+}
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/src/io_pattern/degrading_policy_engine.cpp b/mooncake-store/src/io_pattern/degrading_policy_engine.cpp
new file mode 100644
index 0000000000..bdcbe6d06f
--- /dev/null
+++ b/mooncake-store/src/io_pattern/degrading_policy_engine.cpp
@@ -0,0 +1,60 @@
+#include "io_pattern/degrading_policy_engine.h"
+
+namespace mooncake::io_pattern {
+
+void DegradingPolicyEngine::RecordFailure() {
+    std::lock_guard lock(mutex_);
+    ++consecutive_failures_;
+    if (failure_threshold_ != 0 && consecutive_failures_ >= failure_threshold_)
+        degraded_ = true;
+}
+
+void DegradingPolicyEngine::RecordSuccess() {
+    std::lock_guard lock(mutex_);
+    consecutive_failures_ = 0;
+}
+
+void DegradingPolicyEngine::ForceDegraded(bool value) {
+    std::lock_guard lock(mutex_);
+    degraded_ = value;
+    if (!value) consecutive_failures_ = 0;
+}
+
+bool DegradingPolicyEngine::degraded() const {
+    std::lock_guard lock(mutex_);
+    return degraded_;
+}
+
+size_t DegradingPolicyEngine::consecutive_failures() const {
+    std::lock_guard lock(mutex_);
+    return consecutive_failures_;
+}
+
+std::shared_ptr<PolicyEngine> DegradingPolicyEngine::Active() const {
+    std::lock_guard lock(mutex_);
+    return degraded_ ? fallback_ : primary_;
+}
+
+EvictionPlan DegradingPolicyEngine::PlanEviction(const PolicyContext& context,
+                                                 CacheTier tier,
+                                                 uint64_t bytes) const {
+    auto engine = Active();
+    return engine ? engine->PlanEviction(context, tier, bytes)
+                  : EvictionPlan{.source_tier = tier, .target_bytes = bytes};
+}
+
+PrefetchPlan DegradingPolicyEngine::PlanPrefetch(
+    const PolicyContext& context, const TraceHistory& trace) const {
+    auto engine = Active();
+    return engine ? engine->PlanPrefetch(context, trace) : PrefetchPlan{};
+}
+
+AdmissionResult DegradingPolicyEngine::DecideAdmission(
+    const ObjectRef& object, CacheTier tier,
+    const PolicyContext& context) const {
+    auto engine = Active();
+    return engine ? engine->DecideAdmission(object, tier, context)
+                  : AdmissionResult{.object = object, .target_tier = tier};
+}
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/src/io_pattern/feedback.cpp b/mooncake-store/src/io_pattern/feedback.cpp
new file mode 100644
index 0000000000..7598dbc99b
--- /dev/null
+++ b/mooncake-store/src/io_pattern/feedback.cpp
@@ -0,0 +1,58 @@
+#include "io_pattern/feedback.h"
+
+namespace mooncake::io_pattern {
+
+void PolicyFeedbackWindow::Record(PolicyFeedbackSample sample) {
+    std::lock_guard lock(mutex_);
+    if (capacity_ == 0) return;
+    if (samples_.size() == capacity_) samples_.pop_front();
+    samples_.push_back(sample);
+}
+
+PolicyFeedbackStats PolicyFeedbackWindow::Snapshot() const {
+    std::lock_guard lock(mutex_);
+    PolicyFeedbackStats stats;
+    stats.samples = samples_.size();
+    for (const auto& sample : samples_) {
+        stats.hit_rate_delta += sample.hit_rate_delta;
+        stats.eviction_churn += sample.eviction_churn;
+        stats.ttft_delta += sample.ttft_delta;
+        stats.prefetch_accuracy += sample.prefetch_accuracy;
+    }
+    if (stats.samples != 0) {
+        const float divisor = static_cast<float>(stats.samples);
+        stats.hit_rate_delta /= divisor;
+        stats.eviction_churn /= divisor;
+        stats.ttft_delta /= divisor;
+        stats.prefetch_accuracy /= divisor;
+    }
+    return stats;
+}
+
+bool AdaptivePolicyTuner::Tune(const PolicyFeedbackStats& stats,
+                               ScoreBasedEvictionConfig& config) {
+    if (stats.hit_rate_delta < 0.0F) {
+        ++negative_streak_;
+    } else {
+        negative_streak_ = 0;
+    }
+    if (negative_windows_ == 0 || negative_streak_ < negative_windows_) {
+        if (stats.eviction_churn > 0.5F || stats.prefetch_accuracy < 0.2F ||
+            stats.ttft_delta > 0.1F) {
+            conservative_ = true;
+            config.prefix_weight *= 0.9F;
+            config.recompute_weight *= 0.9F;
+            if (persistence_) persistence_(config);
+            return true;
+        }
+        return false;
+    }
+    config.frequency_weight *= 0.8F;
+    config.idle_weight *= 1.1F;
+    conservative_ = true;
+    negative_streak_ = 0;
+    if (persistence_) persistence_(config);
+    return true;
+}
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/src/io_pattern/kmeans_analyzer.cpp b/mooncake-store/src/io_pattern/kmeans_analyzer.cpp
new file mode 100644
index 0000000000..971e1a92a3
--- /dev/null
+++ b/mooncake-store/src/io_pattern/kmeans_analyzer.cpp
@@ -0,0 +1,161 @@
+#include "io_pattern/kmeans_analyzer.h"
+
+#include <algorithm>
+#include <array>
+#include <cmath>
+#include <unordered_map>
+
+namespace mooncake::io_pattern {
+namespace {
+
+// Token length, fanout, block size, access frequency and prefix-match length
+// are the five documented dimensions.  They are normalized against the active
+// sliding window before distance calculation.
+using Feature = std::array<float, 5>;
+
+struct SessionFeatures {
+    Feature values{};
+    size_t samples{0};
+};
+
+Feature ToFeature(const KeyMetrics& key) {
+    return {static_cast<float>(key.token_count),
+            static_cast<float>(key.prefix_fanout),
+            static_cast<float>(key.block_size),
+            static_cast<float>(key.access_count_window),
+            static_cast<float>(key.match_length)};
+}
+
+float Distance(const Feature& lhs, const Feature& rhs, const Feature& scale) {
+    float distance = 0.0F;
+    for (size_t index = 0; index < lhs.size(); ++index) {
+        const float normalized = (lhs[index] - rhs[index]) /
+                                 std::max(1.0F, scale[index]);
+        distance += normalized * normalized;
+    }
+    return distance;
+}
+
+WorkloadType Classify(const Feature& feature,
+                      const ThresholdAnalyzerConfig& config) {
+    if (feature[0] > config.code_agent_token_count &&
+        feature[1] > config.code_agent_prefix_fanout &&
+        feature[4] > config.code_agent_match_length) {
+        return WorkloadType::kCodeAgent;
+    }
+    if (feature[2] < config.recommendation_block_size &&
+        feature[3] > config.recommendation_frequency) {
+        return WorkloadType::kGenerativeRecommendation;
+    }
+    if (feature[1] > config.conversation_prefix_fanout &&
+        feature[4] > config.conversation_match_length) {
+        return WorkloadType::kMultiTurnConversation;
+    }
+    return WorkloadType::kMixed;
+}
+
+}  // namespace
+
+PatternResult KMeansWorkloadAnalyzer::Analyze(
+    const IoPatternSnapshot& snapshot) const {
+    PatternResult result;
+    if (snapshot.keys.empty()) {
+        result.workload_type = WorkloadType::kMixed;
+        return result;
+    }
+
+    std::unordered_map<std::string, SessionFeatures> by_session;
+    Feature scale{1.0F, 1.0F, 1.0F, 1.0F};
+    for (const auto& key : snapshot.keys) {
+        const std::string session = key.session_id.empty()
+                                        ? key.object.tenant_id.value() + ":" + key.object.key
+                                        : key.session_id;
+        auto& aggregate = by_session[session];
+        const auto feature = ToFeature(key);
+        for (size_t index = 0; index < feature.size(); ++index) {
+            aggregate.values[index] += feature[index];
+            scale[index] = std::max(scale[index], feature[index]);
+        }
+        ++aggregate.samples;
+    }
+
+    std::vector<std::string> session_ids;
+    std::vector<Feature> samples;
+    session_ids.reserve(by_session.size());
+    samples.reserve(by_session.size());
+    for (auto& [session, aggregate] : by_session) {
+        for (auto& value : aggregate.values) {
+            value /= static_cast<float>(aggregate.samples);
+        }
+        session_ids.push_back(session);
+        samples.push_back(aggregate.values);
+    }
+
+    const size_t cluster_count = std::min<size_t>(3, samples.size());
+    std::vector<Feature> centroids(samples.begin(), samples.begin() + cluster_count);
+    std::vector<size_t> assignments(samples.size(), 0);
+    for (uint32_t iteration = 0; iteration < config_.iterations; ++iteration) {
+        std::vector<Feature> sums(cluster_count);
+        std::vector<size_t> counts(cluster_count, 0);
+        for (size_t sample_index = 0; sample_index < samples.size(); ++sample_index) {
+            size_t best = 0;
+            float best_distance = Distance(samples[sample_index], centroids[0], scale);
+            for (size_t cluster = 1; cluster < cluster_count; ++cluster) {
+                const float distance = Distance(samples[sample_index], centroids[cluster], scale);
+                if (distance < best_distance) {
+                    best = cluster;
+                    best_distance = distance;
+                }
+            }
+            assignments[sample_index] = best;
+            ++counts[best];
+            for (size_t field = 0; field < samples[sample_index].size(); ++field) {
+                sums[best][field] += samples[sample_index][field];
+            }
+        }
+        for (size_t cluster = 0; cluster < cluster_count; ++cluster) {
+            if (counts[cluster] == 0) continue;
+            for (size_t field = 0; field < centroids[cluster].size(); ++field) {
+                centroids[cluster][field] = sums[cluster][field] /
+                                            static_cast<float>(counts[cluster]);
+            }
+        }
+    }
+
+    std::vector<WorkloadType> labels;
+    labels.reserve(cluster_count);
+    for (const auto& centroid : centroids) labels.push_back(Classify(centroid, config_.thresholds));
+    WorkloadType global = labels[assignments.front()];
+    bool mixed = false;
+    for (size_t index = 0; index < samples.size(); ++index) {
+        const auto type = labels[assignments[index]];
+        result.sessions.push_back(
+            SessionPattern{.session_id = session_ids[index], .workload_type = type,
+                           .confidence = 1.0F / (1.0F + Distance(
+                               samples[index], centroids[assignments[index]], scale))});
+        if (type != global) mixed = true;
+    }
+    result.workload_type = mixed ? WorkloadType::kMixed : global;
+    result.workload_confidence = mixed ? 0.5F : result.sessions.front().confidence;
+
+    ThresholdAnalyzer key_analyzer(config_.thresholds);
+    result.keys = key_analyzer.Analyze(snapshot).keys;
+    return result;
+}
+
+WorkloadType KMeansWorkloadAnalyzer::DetectWorkloadType(
+    const IoPatternSnapshot& snapshot) const {
+    return Analyze(snapshot).workload_type;
+}
+
+float KMeansWorkloadAnalyzer::CalculateConfidence(
+    const ObjectRef& object, const IoPatternSnapshot& snapshot) const {
+    const auto result = Analyze(snapshot);
+    const auto it = std::find_if(result.keys.begin(), result.keys.end(),
+                                 [&object](const KeyPattern& key) {
+                                     return key.object == object;
+                                 });
+    return it == result.keys.end() ? 0.0F : it->confidence;
+}
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/src/io_pattern/legacy_eviction_ops.cpp b/mooncake-store/src/io_pattern/legacy_eviction_ops.cpp
new file mode 100644
index 0000000000..ea35682864
--- /dev/null
+++ b/mooncake-store/src/io_pattern/legacy_eviction_ops.cpp
@@ -0,0 +1,35 @@
+#include "io_pattern/legacy_eviction_ops.h"
+
+#include <algorithm>
+
+namespace mooncake::io_pattern {
+
+EvictionPlan LegacyEvictionOps::Evaluate(const PolicyContext& context,
+                                         CacheTier tier,
+                                         uint64_t target_bytes) const {
+    EvictionPlan plan{.source_tier = tier, .target_bytes = target_bytes};
+    if (!strategy_ || target_bytes == 0) return plan;
+    std::lock_guard lock(mutex_);
+    for (const auto& key : context.snapshot.keys) {
+        if (key.replica_tiers & CacheTierBit(tier)) {
+            strategy_->AddKey(key.object.tenant_id.MakeScopedKey(key.object.key));
+        }
+    }
+    uint64_t bytes = 0;
+    while (bytes < target_bytes) {
+        const auto scoped = strategy_->EvictKey();
+        if (scoped.empty()) break;
+        auto [tenant, key] = TenantId::ParseScopedKey(scoped);
+        auto it = std::find_if(context.snapshot.keys.begin(), context.snapshot.keys.end(),
+                               [&](const KeyMetrics& value) {
+                                   return value.object.tenant_id == tenant &&
+                                          value.object.key == key;
+                               });
+        if (it == context.snapshot.keys.end()) continue;
+        plan.candidates.push_back({it->object, it->block_size, 0.0F});
+        bytes += it->block_size;
+    }
+    return plan;
+}
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/src/io_pattern/observability.cpp b/mooncake-store/src/io_pattern/observability.cpp
new file mode 100644
index 0000000000..bb920fb786
--- /dev/null
+++ b/mooncake-store/src/io_pattern/observability.cpp
@@ -0,0 +1,63 @@
+#include "io_pattern/observability.h"
+
+#include <algorithm>
+
+namespace mooncake::io_pattern {
+
+void IoPatternObservability::RecordCollectLatency(uint64_t value) {
+    std::lock_guard lock(mutex_);
+    values_.collect_latency_us = std::max(values_.collect_latency_us, value);
+}
+
+void IoPatternObservability::RecordAnalyzeLatency(uint64_t value) {
+    std::lock_guard lock(mutex_);
+    values_.analyze_latency_us = std::max(values_.analyze_latency_us, value);
+}
+
+void IoPatternObservability::RecordPolicyDecision(bool strategy_hit) {
+    std::lock_guard lock(mutex_);
+    ++values_.policy_decisions;
+    ++values_.strategy_trials;
+    if (strategy_hit) ++values_.strategy_hits;
+}
+
+void IoPatternObservability::RecordFalsePositive() {
+    std::lock_guard lock(mutex_);
+    ++values_.false_positives;
+}
+
+void IoPatternObservability::RecordDegrade() {
+    std::lock_guard lock(mutex_);
+    ++values_.degrade_count;
+}
+
+void IoPatternObservability::RecordReportDrop(uint64_t count) {
+    std::lock_guard lock(mutex_);
+    values_.report_drop_count += count;
+}
+
+IoPatternObservabilitySnapshot IoPatternObservability::Snapshot() const {
+    std::lock_guard lock(mutex_);
+    auto result = values_;
+    result.strategy_hit_rate = result.strategy_trials == 0
+                                   ? 0.0F
+                                   : static_cast<float>(result.strategy_hits) /
+                                         static_cast<float>(result.strategy_trials);
+    result.false_positive_rate = result.strategy_trials == 0
+                                     ? 0.0F
+                                     : static_cast<float>(result.false_positives) /
+                                           static_cast<float>(result.strategy_trials);
+    return result;
+}
+
+IoPatternObservabilitySnapshot IoPatternObservability::Snapshot(
+    double window_seconds) const {
+    auto result = Snapshot();
+    if (window_seconds > 0.0) {
+        result.policy_decision_qps =
+            static_cast<float>(result.policy_decisions / window_seconds);
+    }
+    return result;
+}
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/src/io_pattern/policy_strategies.cpp b/mooncake-store/src/io_pattern/policy_strategies.cpp
new file mode 100644
index 0000000000..c9169becb1
--- /dev/null
+++ b/mooncake-store/src/io_pattern/policy_strategies.cpp
@@ -0,0 +1,251 @@
+#include "io_pattern/policy_strategies.h"
+
+#include <algorithm>
+#include <limits>
+#include <unordered_map>
+
+namespace mooncake::io_pattern {
+namespace {
+
+const KeyPattern* FindPattern(const ObjectRef& object,
+                              const PatternResult& result) {
+    const auto it = std::find_if(
+        result.keys.begin(), result.keys.end(),
+        [&object](const KeyPattern& pattern) { return pattern.object == object; });
+    return it == result.keys.end() ? nullptr : &*it;
+}
+
+const KeyMetrics* FindMetrics(const ObjectRef& object,
+                              const IoPatternSnapshot& snapshot) {
+    const auto it = std::find_if(
+        snapshot.keys.begin(), snapshot.keys.end(),
+        [&object](const KeyMetrics& key) { return key.object == object; });
+    return it == snapshot.keys.end() ? nullptr : &*it;
+}
+
+// Whether the object already has a replica deeper in the storage ladder, which
+// is what makes evicting this copy safe. Compared by TierDepth rather than by
+// enum value: kLocalDisk is declared last for wire compatibility but sits
+// directly below host memory, so index order is not storage order.
+bool HasLowerTierReplica(const KeyMetrics& key, CacheTier tier) {
+    const int depth = TierDepth(tier);
+    for (const CacheTier candidate : kAllCacheTiers) {
+        if (TierDepth(candidate) <= depth) {
+            continue;
+        }
+        if (key.replica_tiers & CacheTierBit(candidate)) {
+            return true;
+        }
+    }
+    return false;
+}
+
+CacheTier TierDownTarget(CacheTier source, TierDownMode mode) {
+    if (source == CacheTier::kL3NofSsd) return CacheTier::kL3NofSsd;
+    if (mode == TierDownMode::kSkipHost && source == CacheTier::kL0Hbm) {
+        return CacheTier::kL2Segment;
+    }
+    // Prefix-affinity keeps the immediate next tier as the placement target;
+    // callers may co-locate grouped prefixes within that tier. kLocalDisk is not
+    // reachable from here: it is appended last for wire compatibility, and the
+    // MEMORY -> LOCAL_DISK demotion is selected explicitly by the tier-down
+    // driver rather than derived from this ladder.
+    return static_cast<CacheTier>(static_cast<uint8_t>(source) + 1);
+}
+
+}  // namespace
+
+EvictionPlan ScoreBasedEvictionOps::Evaluate(const PolicyContext& context,
+                                              CacheTier tier,
+                                              uint64_t target_bytes) const {
+    EvictionPlan plan{.source_tier = tier, .target_bytes = target_bytes};
+    // The driver owns the action: a tier-down pass selects the same victims an
+    // eviction pass would, and only the executor's action differs. Deriving it
+    // from target_tier is not possible -- TierDownTarget() returns source+1 for
+    // L0/L1/L2 alike, so every candidate would look like a demotion.
+    const EvictionAction action = context.tier_down
+                                      ? EvictionAction::kTierDown
+                                      : EvictionAction::kEvict;
+    if (context.tier_down) {
+        plan.tier_down_target_bytes = target_bytes;
+    }
+    uint64_t max_block_size = 0;
+    uint32_t max_other_replicas = 0;
+    for (const auto& key : context.snapshot.keys) {
+        if ((key.replica_tiers & CacheTierBit(tier)) == 0 || key.pinned) {
+            continue;
+        }
+        if (context.min_idle_time_us != 0 &&
+            key.idle_time_us < context.min_idle_time_us) {
+            continue;
+        }
+        max_block_size = std::max(max_block_size, key.block_size);
+        max_other_replicas = std::max(max_other_replicas,
+                                      key.other_replica_count);
+    }
+    for (const auto& key : context.snapshot.keys) {
+        if ((key.replica_tiers & CacheTierBit(tier)) == 0 || key.pinned) {
+            continue;
+        }
+        if (context.min_idle_time_us != 0 &&
+            key.idle_time_us < context.min_idle_time_us) {
+            continue;
+        }
+        const auto* pattern = FindPattern(key.object, context.analysis);
+        if (pattern == nullptr) {
+            continue;
+        }
+        const float normalized_block = max_block_size == 0
+                                           ? 0.0F
+                                           : static_cast<float>(key.block_size) /
+                                                 static_cast<float>(max_block_size);
+        const float normalized_other_replicas =
+            max_other_replicas == 0
+                ? 0.0F
+                : static_cast<float>(key.other_replica_count) /
+                      static_cast<float>(max_other_replicas);
+        float score = 0.0F;
+        switch (tier) {
+            case CacheTier::kL0Hbm:
+                score = config_.idle_weight * pattern->idle_score -
+                        config_.frequency_weight * pattern->frequency_score -
+                        config_.prefix_weight * pattern->prefix_score -
+                        config_.recompute_weight * pattern->recompute_score;
+                break;
+            case CacheTier::kL1Host:
+            // Host-local SSD is scored like host memory: idle time dominates,
+            // and an existing deeper replica makes reclaiming it safe.
+            case CacheTier::kLocalDisk:
+            case CacheTier::kL2Segment:
+                score = config_.idle_weight * pattern->idle_score -
+                        config_.frequency_weight * pattern->frequency_score +
+                        config_.lower_replica_weight *
+                            (HasLowerTierReplica(key, tier) ? 1.0F : 0.0F) -
+                        config_.prefix_weight * pattern->prefix_score -
+                        config_.recompute_weight * pattern->recompute_score;
+                break;
+            case CacheTier::kL3NofSsd:
+                score = config_.idle_weight * pattern->idle_score *
+                            normalized_block -
+                        config_.frequency_weight * pattern->frequency_score -
+                        config_.recompute_weight * pattern->recompute_score +
+                        config_.other_replica_weight * normalized_other_replicas;
+                break;
+        }
+        plan.candidates.push_back(
+            EvictionCandidate{.object = key.object,
+                              .bytes = key.block_size,
+                              .score = score,
+                              .target_tier = TierDownTarget(
+                                  tier, config_.tier_down_mode),
+                              .action = action});
+    }
+    std::sort(plan.candidates.begin(), plan.candidates.end(),
+              [](const EvictionCandidate& lhs, const EvictionCandidate& rhs) {
+                  return lhs.score > rhs.score;
+              });
+    if (target_bytes == 0) {
+        plan.candidates.clear();
+        return plan;
+    }
+    if (config_.max_candidates != 0 &&
+        plan.candidates.size() > config_.max_candidates) {
+        plan.candidates.resize(config_.max_candidates);
+    }
+    uint64_t selected_bytes = 0;
+    auto end = plan.candidates.begin();
+    while (end != plan.candidates.end() && selected_bytes < target_bytes) {
+        selected_bytes =
+            end->bytes > std::numeric_limits<uint64_t>::max() - selected_bytes
+                ? std::numeric_limits<uint64_t>::max()
+                : selected_bytes + end->bytes;
+        ++end;
+    }
+    plan.candidates.erase(end, plan.candidates.end());
+    return plan;
+}
+
+AdmissionResult PrefixMatchAdmissionOps::Evaluate(
+    const ObjectRef& object, CacheTier target_tier,
+    const PolicyContext& context) const {
+    AdmissionResult result{.object = object, .target_tier = target_tier};
+    const auto* key = FindMetrics(object, context.snapshot);
+    if (key == nullptr) {
+        return result;
+    }
+    if (target_tier == CacheTier::kL0Hbm) {
+        result.decision = key->match_length >= config_.hbm_match_length
+                              ? AdmissionDecision::kAdmit
+                              : AdmissionDecision::kRejectPrefix;
+        const auto threshold = std::max(1U, config_.hbm_match_length);
+        result.confidence = key->match_length == 0
+                                ? 0.0F
+                                : std::min(1.0F, static_cast<float>(
+                                                     key->match_length) /
+                                                     threshold);
+        return result;
+    }
+    result.decision = key->access_count_window >= config_.frequency_threshold
+                          ? AdmissionDecision::kAdmit
+                          : AdmissionDecision::kRejectFrequency;
+    const bool target_over_watermark = std::any_of(
+        context.snapshot.storage.begin(), context.snapshot.storage.end(),
+        [&](const StorageMetric& metric) {
+            return metric.tier == target_tier &&
+                   metric.memory_used_ratio >= config_.max_memory_used_ratio;
+        });
+    if (result.decision == AdmissionDecision::kAdmit &&
+        target_over_watermark) {
+        result.decision = AdmissionDecision::kRejectWatermark;
+    }
+    result.confidence =
+        result.decision == AdmissionDecision::kAdmit ? 1.0F : 0.0F;
+    return result;
+}
+
+PrefetchPlan TraceBasedPrefetchOps::Evaluate(
+    const PolicyContext& context, const TraceHistory& trace) const {
+    PrefetchPlan plan{.strategy = config_.strategy,
+                      .timeout_us = config_.timeout_us};
+    std::unordered_map<ObjectRef, bool, ObjectRefHash> seen;
+    for (const auto& event : trace.events) {
+        if (!event.is_hit ||
+            event.match_length <= config_.match_length_threshold ||
+            seen.contains(event.object)) {
+            continue;
+        }
+        const auto* key = FindMetrics(event.object, context.snapshot);
+        if (key == nullptr) {
+            continue;
+        }
+        PrefetchCandidate candidate;
+        candidate.object = event.object;
+        candidate.bytes = key->block_size;
+        const auto* pattern = FindPattern(event.object, context.analysis);
+        candidate.confidence = pattern == nullptr ? 0.0F : pattern->confidence;
+        if (candidate.confidence < config_.minimum_confidence) {
+            continue;
+        }
+        // Only one hop is real: the store promotes a LOCAL_DISK replica into
+        // host memory. There is no L3 -> L2 or L2 -> L1 mover, so reporting a
+        // fabricated kL2Segment target made every candidate look executable
+        // while the handler could only ever promote a local-disk source -- a
+        // NoF-only object therefore produced a plan the executor had to reject.
+        if (key->replica_tiers & CacheTierBit(CacheTier::kLocalDisk)) {
+            candidate.source_tier = CacheTier::kLocalDisk;
+            candidate.target_tier = CacheTier::kL1Host;
+        } else {
+            continue;
+        }
+        candidate.priority = static_cast<float>(event.match_length);
+        plan.candidates.push_back(candidate);
+        seen.emplace(event.object, true);
+        if (config_.max_candidates != 0 &&
+            plan.candidates.size() >= config_.max_candidates) {
+            break;
+        }
+    }
+    return plan;
+}
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/src/io_pattern/reporter.cpp b/mooncake-store/src/io_pattern/reporter.cpp
new file mode 100644
index 0000000000..a9428a45a8
--- /dev/null
+++ b/mooncake-store/src/io_pattern/reporter.cpp
@@ -0,0 +1,149 @@
+#include "io_pattern/reporter.h"
+
+#include <utility>
+
+namespace mooncake::io_pattern {
+
+IoPatternReporter::IoPatternReporter(size_t capacity, MetricBatchSink sink,
+                                     size_t per_tenant_capacity)
+    : capacity_(capacity),
+      sink_(std::move(sink)),
+      per_tenant_capacity_(per_tenant_capacity) {}
+
+IoPatternReporter::~IoPatternReporter() { Stop(); }
+
+void IoPatternReporter::Start() {
+    std::lock_guard lock(mutex_);
+    if (running_) return;
+    running_ = true;
+    worker_ = std::thread([this] {
+        std::unique_lock lock(mutex_);
+        while (running_) {
+            const auto interval = RecommendedFlushIntervalLocked();
+            condition_.wait_for(lock, interval, [this] { return !running_; });
+            if (!running_) break;
+            lock.unlock();
+            Flush();
+            lock.lock();
+        }
+    });
+}
+
+void IoPatternReporter::Stop() {
+    {
+        std::lock_guard lock(mutex_);
+        if (!running_) return;
+        running_ = false;
+    }
+    condition_.notify_all();
+    if (worker_.joinable()) worker_.join();
+    Flush();
+}
+
+bool IoPatternReporter::Enqueue(InferenceMetrics metrics) {
+    const auto tenant = metrics.object.tenant_id;
+    return EnqueueImpl(
+        [value = std::move(metrics)](MetricBatch& batch) {
+            batch.inference.push_back(value);
+        },
+        tenant);
+}
+
+bool IoPatternReporter::EnqueueAccess(AccessRecord record) {
+    const auto tenant = record.object.tenant_id;
+    return EnqueueImpl(
+        [value = std::move(record)](MetricBatch& batch) {
+            batch.accesses.push_back(value);
+        },
+        tenant);
+}
+
+bool IoPatternReporter::EnqueueStorage(StorageMetric metric) {
+    return EnqueueImpl([value = std::move(metric)](MetricBatch& batch) {
+        batch.storage.push_back(value);
+    }, TenantId::Default());
+}
+
+bool IoPatternReporter::EnqueueImpl(std::function<void(MetricBatch&)> append,
+                                    const TenantId& tenant) {
+    std::lock_guard lock(mutex_);
+    const size_t size = batch_.inference.size() + batch_.accesses.size() +
+                        batch_.storage.size();
+    if (!sink_ || size >= capacity_) {
+        ++dropped_;
+        return false;
+    }
+    if (per_tenant_capacity_ != 0 &&
+        tenant_pending_[tenant] >= per_tenant_capacity_) {
+        ++dropped_;
+        return false;
+    }
+    append(batch_);
+    ++tenant_pending_[tenant];
+    condition_.notify_one();
+    return true;
+}
+
+bool IoPatternReporter::Flush() {
+    MetricBatch outgoing;
+    {
+        std::lock_guard lock(mutex_);
+        if (batch_.inference.empty() && batch_.accesses.empty() &&
+            batch_.storage.empty()) {
+            return true;
+        }
+        outgoing = std::move(batch_);
+        batch_ = {};
+        tenant_pending_.clear();
+    }
+    if (!sink_(outgoing)) {
+        std::lock_guard lock(mutex_);
+        ++dropped_;
+        return false;
+    }
+    std::lock_guard lock(mutex_);
+    reported_ += outgoing.inference.size() + outgoing.accesses.size() +
+                 outgoing.storage.size();
+    return true;
+}
+
+size_t IoPatternReporter::pending() const {
+    std::lock_guard lock(mutex_);
+    return batch_.inference.size() + batch_.accesses.size() +
+           batch_.storage.size();
+}
+
+uint64_t IoPatternReporter::dropped() const {
+    std::lock_guard lock(mutex_);
+    return dropped_;
+}
+
+uint64_t IoPatternReporter::reported() const {
+    std::lock_guard lock(mutex_);
+    return reported_;
+}
+
+std::chrono::milliseconds IoPatternReporter::RecommendedFlushInterval() const {
+    std::lock_guard lock(mutex_);
+    return RecommendedFlushIntervalLocked();
+}
+
+void IoPatternReporter::UpdateLoad(float memory_used_ratio,
+                                   uint64_t rpc_latency_us) {
+    std::lock_guard lock(mutex_);
+    memory_used_ratio_ = memory_used_ratio;
+    rpc_latency_us_ = rpc_latency_us;
+    condition_.notify_one();
+}
+
+std::chrono::milliseconds
+IoPatternReporter::RecommendedFlushIntervalLocked() const {
+    if (memory_used_ratio_ >= 0.95F || rpc_latency_us_ > 100'000) {
+        return std::chrono::milliseconds(1000);
+    }
+    if (memory_used_ratio_ >= 0.80F) return std::chrono::milliseconds(500);
+    if (memory_used_ratio_ >= 0.50F) return std::chrono::milliseconds(200);
+    return std::chrono::milliseconds(100);
+}
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/src/io_pattern/resilient_analyzer.cpp b/mooncake-store/src/io_pattern/resilient_analyzer.cpp
new file mode 100644
index 0000000000..b850a37398
--- /dev/null
+++ b/mooncake-store/src/io_pattern/resilient_analyzer.cpp
@@ -0,0 +1,67 @@
+#include "io_pattern/resilient_analyzer.h"
+
+namespace mooncake::io_pattern {
+
+PatternResult ResilientAnalyzer::Analyze(
+    const IoPatternSnapshot& snapshot) const {
+    if (!primary_) return Fallback();
+    try {
+        auto result = primary_->Analyze(snapshot);
+        RecordSuccess(result);
+        return result;
+    } catch (...) {
+        RecordFailure();
+        return Fallback();
+    }
+}
+
+WorkloadType ResilientAnalyzer::DetectWorkloadType(
+    const IoPatternSnapshot& snapshot) const {
+    return Analyze(snapshot).workload_type;
+}
+
+float ResilientAnalyzer::CalculateConfidence(
+    const ObjectRef& object, const IoPatternSnapshot& snapshot) const {
+    const auto result = Analyze(snapshot);
+    for (const auto& key : result.keys) {
+        if (key.object == object) return key.confidence;
+    }
+    return 0.0F;
+}
+
+void ResilientAnalyzer::RecordFailure() const {
+    std::lock_guard lock(mutex_);
+    ++failures_;
+    if (failure_threshold_ != 0 && failures_ >= failure_threshold_)
+        degraded_ = true;
+}
+
+void ResilientAnalyzer::RecordSuccess(const PatternResult& result) const {
+    std::lock_guard lock(mutex_);
+    last_result_ = result;
+    failures_ = 0;
+    degraded_ = false;
+}
+
+PatternResult ResilientAnalyzer::Fallback() const {
+    std::lock_guard lock(mutex_);
+    if (!last_result_.keys.empty() || last_result_.workload_type != WorkloadType::kUnknown)
+        return last_result_;
+    PatternResult result;
+    result.workload_type = WorkloadType::kMixed;
+    return result;
+}
+
+bool ResilientAnalyzer::degraded() const {
+    std::lock_guard lock(mutex_);
+    return degraded_;
+}
+
+size_t ResilientAnalyzer::failures() const {
+    std::lock_guard lock(mutex_);
+    return failures_;
+}
+
+PatternResult ResilientAnalyzer::FallbackResult() const { return Fallback(); }
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/src/io_pattern/resilient_cfm_channel.cpp b/mooncake-store/src/io_pattern/resilient_cfm_channel.cpp
new file mode 100644
index 0000000000..5b1f5ce69e
--- /dev/null
+++ b/mooncake-store/src/io_pattern/resilient_cfm_channel.cpp
@@ -0,0 +1,68 @@
+#include "io_pattern/resilient_cfm_channel.h"
+
+namespace mooncake::io_pattern {
+
+template <typename Operation>
+bool ResilientCfmChannel::Retry(Operation&& operation) {
+    if (!delegate_) {
+        RecordFailure();
+        return false;
+    }
+    for (uint32_t attempt = 0; attempt <= config_.max_retries; ++attempt) {
+        if (operation()) {
+            RecordSuccess();
+            return true;
+        }
+    }
+    RecordFailure();
+    return false;
+}
+
+bool ResilientCfmChannel::SendSnapshot(const IoPatternSnapshot& snapshot) {
+    return Retry([&] { return delegate_->SendSnapshot(snapshot); });
+}
+
+bool ResilientCfmChannel::SendMetricBatch(const MetricBatch& batch) {
+    return Retry([&] { return delegate_->SendMetricBatch(batch); });
+}
+
+ErrorCode ResilientCfmChannel::ExecutePrefetch(const PrefetchPlan& plan) {
+    ErrorCode result = ErrorCode::RPC_FAIL;
+    if (!delegate_) {
+        RecordFailure();
+        return ErrorCode::UNAVAILABLE_IN_CURRENT_MODE;
+    }
+    for (uint32_t attempt = 0; attempt <= config_.max_retries; ++attempt) {
+        result = delegate_->ExecutePrefetch(plan);
+        if (result == ErrorCode::OK) {
+            RecordSuccess();
+            return result;
+        }
+    }
+    RecordFailure();
+    return result;
+}
+
+void ResilientCfmChannel::RecordSuccess() {
+    std::lock_guard lock(mutex_);
+    consecutive_failures_ = 0;
+    degraded_ = false;
+}
+
+void ResilientCfmChannel::RecordFailure() {
+    std::lock_guard lock(mutex_);
+    ++consecutive_failures_;
+    if (consecutive_failures_ >= config_.degrade_after_failures) degraded_ = true;
+}
+
+bool ResilientCfmChannel::degraded() const {
+    std::lock_guard lock(mutex_);
+    return degraded_;
+}
+
+uint64_t ResilientCfmChannel::consecutive_failures() const {
+    std::lock_guard lock(mutex_);
+    return consecutive_failures_;
+}
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/src/io_pattern/rpc_transport.cpp b/mooncake-store/src/io_pattern/rpc_transport.cpp
new file mode 100644
index 0000000000..14521ba949
--- /dev/null
+++ b/mooncake-store/src/io_pattern/rpc_transport.cpp
@@ -0,0 +1,151 @@
+#include "io_pattern/rpc_transport.h"
+
+#include <async_simple/coro/SyncAwait.h>
+#include <ylt/coro_io/client_pool.hpp>
+#include <ylt/coro_rpc/coro_rpc_client.hpp>
+
+#include <unordered_map>
+
+#include "io_pattern/cfm_service.h"
+#include "store_rpc_client_io_context.h"
+
+namespace mooncake::io_pattern {
+
+class CoroRpcCfmTransport::Impl {
+   public:
+    Impl(std::string endpoint, std::chrono::milliseconds default_timeout)
+        : endpoint_(std::move(endpoint)), default_timeout_(default_timeout) {}
+
+    template <auto ServiceMethod, typename ReturnType, typename... Args>
+    std::optional<ReturnType> Invoke(std::chrono::milliseconds timeout,
+                                     Args&&... args) {
+        auto pool = GetPool(timeout.count() > 0 ? timeout : default_timeout_);
+        return async_simple::coro::syncAwait(
+            [&]() -> async_simple::coro::Lazy<std::optional<ReturnType>> {
+                auto request = co_await pool->send_request(
+                    [&](coro_io::client_reuse_hint,
+                        coro_rpc::coro_rpc_client& client) {
+                        return client.send_request<ServiceMethod>(
+                            std::forward<Args>(args)...);
+                    });
+                if (!request) co_return std::nullopt;
+                auto response = co_await std::move(request.value());
+                if (!response) co_return std::nullopt;
+                co_return response->result();
+            }());
+    }
+
+    std::shared_ptr<coro_io::client_pool<coro_rpc::coro_rpc_client>> GetPool(
+        std::chrono::milliseconds timeout) {
+        std::lock_guard lock(mutex_);
+        const auto key = timeout.count();
+        const auto existing = pools_.find(key);
+        if (existing != pools_.end()) return existing->second;
+        coro_io::client_pool<coro_rpc::coro_rpc_client>::pool_config config;
+        config.client_config.request_timeout_duration = timeout;
+        config.host_alive_detect_duration = std::chrono::seconds(0);
+        auto pool = coro_io::client_pool<coro_rpc::coro_rpc_client>::create(
+            endpoint_, config, GetStoreRpcClientIoContextPool());
+        pools_.emplace(key, pool);
+        return pool;
+    }
+
+    std::string endpoint_;
+    std::chrono::milliseconds default_timeout_;
+    std::mutex mutex_;
+    std::unordered_map<
+        int64_t,
+        std::shared_ptr<coro_io::client_pool<coro_rpc::coro_rpc_client>>>
+        pools_;
+};
+
+CoroRpcCfmTransport::CoroRpcCfmTransport(
+    std::string endpoint, std::chrono::milliseconds default_timeout)
+    : impl_(std::make_unique<Impl>(std::move(endpoint), default_timeout)) {}
+
+CoroRpcCfmTransport::~CoroRpcCfmTransport() = default;
+
+bool CoroRpcCfmTransport::Send(std::string_view method,
+                               std::string_view payload,
+                               std::chrono::milliseconds timeout) {
+    if (!impl_) return false;
+    // Reports are addressed to the SubMaster endpoint this transport was
+    // created for; there is no separate node identity or credential.
+    const auto result = impl_->Invoke<&CfmRpcService::Send, bool>(
+        timeout, std::string(method), std::string(payload), std::string{});
+    return result && *result;
+}
+
+bool InProcessCfmRpcTransport::Send(std::string_view method,
+                                    std::string_view payload,
+                                    std::chrono::milliseconds) {
+    SendHandler handler;
+    {
+        std::lock_guard lock(mutex_);
+        handler = send_handler_;
+    }
+    return !handler || handler(method, payload);
+}
+
+void InProcessCfmRpcTransport::SetSendHandler(SendHandler handler) {
+    std::lock_guard lock(mutex_);
+    send_handler_ = std::move(handler);
+}
+
+bool CfmRpcChannel::SendSnapshot(const IoPatternSnapshot& snapshot) {
+    if (!transport_ || !codec_) return false;
+    return transport_->Send("report_snapshot", codec_->EncodeSnapshot(snapshot),
+                            config_.timeout);
+}
+
+bool CfmRpcChannel::SendMetricBatch(const MetricBatch& batch) {
+    if (!transport_ || !codec_) return false;
+    return transport_->Send("report_metric_batch", codec_->EncodeMetricBatch(batch),
+                            config_.timeout);
+}
+
+ErrorCode CfmRpcChannel::ExecutePrefetch(const PrefetchPlan& plan) {
+    if (!transport_ || !codec_) {
+        return ErrorCode::UNAVAILABLE_IN_CURRENT_MODE;
+    }
+    return transport_->Send("execute_prefetch", codec_->EncodePrefetch(plan),
+                            config_.timeout)
+               ? ErrorCode::OK
+               : ErrorCode::RPC_TIMEOUT;
+}
+
+std::shared_ptr<CfmChannel> CfmChannelPool::Next() const {
+    if (channels_.empty()) return nullptr;
+    const auto index = next_.fetch_add(1, std::memory_order_relaxed) %
+                       channels_.size();
+    return channels_[index];
+}
+
+bool CfmChannelPool::SendSnapshot(const IoPatternSnapshot& snapshot) {
+    for (size_t attempt = 0; attempt < channels_.size(); ++attempt) {
+        auto channel = Next();
+        if (channel && channel->SendSnapshot(snapshot)) return true;
+    }
+    return false;
+}
+
+bool CfmChannelPool::SendMetricBatch(const MetricBatch& batch) {
+    for (size_t attempt = 0; attempt < channels_.size(); ++attempt) {
+        auto channel = Next();
+        if (channel && channel->SendMetricBatch(batch)) return true;
+    }
+    return false;
+}
+
+ErrorCode CfmChannelPool::ExecutePrefetch(const PrefetchPlan& plan) {
+    ErrorCode last_error = ErrorCode::UNAVAILABLE_IN_CURRENT_MODE;
+    for (size_t attempt = 0; attempt < channels_.size(); ++attempt) {
+        auto channel = Next();
+        if (!channel) continue;
+        last_error = channel->ExecutePrefetch(plan);
+        if (last_error == ErrorCode::OK) return last_error;
+    }
+    return last_error;
+}
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/src/io_pattern/runtime.cpp b/mooncake-store/src/io_pattern/runtime.cpp
new file mode 100644
index 0000000000..e85b7beb7e
--- /dev/null
+++ b/mooncake-store/src/io_pattern/runtime.cpp
@@ -0,0 +1,663 @@
+#include "io_pattern/runtime.h"
+
+#include <chrono>
+#include <future>
+#include <limits>
+#include <thread>
+
+namespace mooncake::io_pattern {
+namespace {
+
+// A dimension that reported UNAVAILABLE_IN_CURRENT_MODE declined to act because
+// the storage primitive cannot run in this configuration. The policy cannot
+// influence that outcome, so it is not a policy failure.
+bool IsPolicyFailure(ErrorCode code) {
+    return code != ErrorCode::OK &&
+           code != ErrorCode::UNAVAILABLE_IN_CURRENT_MODE;
+}
+
+}  // namespace
+
+IoPatternRuntime::IoPatternRuntime(Handlers handlers)
+    : IoPatternRuntime(std::move(handlers), Config{}) {}
+
+IoPatternRuntime::IoPatternRuntime(Handlers handlers, Config config)
+    : config_(config),
+      executor_(std::move(handlers.eviction), std::move(handlers.prefetch),
+                std::move(handlers.admission)),
+      feedback_(config.feedback_window) {
+    // A runtime always has an OOM guard even when a caller omits collector
+    // limits.  The same bound is used by the bounded analyzer below.
+    if (config_.collector.max_total_keys == 0) {
+        config_.collector.max_total_keys = config_.max_analysis_keys;
+    }
+    if (config_.report_sink) {
+        reporter_ = std::make_shared<IoPatternReporter>(
+            config_.report_capacity, config_.report_sink,
+            config_.report_per_tenant_capacity);
+        reporter_->Start();
+    }
+    collector_ = std::make_shared<IoPatternCollectorImpl>(config_.collector,
+                                                           reporter_);
+    auto sliding = std::make_shared<SlidingWindowAnalyzer>(
+        config.analysis_window_ns);
+    analyzer_ = std::make_shared<ResilientAnalyzer>(std::move(sliding));
+    workload_policy_ = std::make_shared<WorkloadPolicyEngine>(
+        WorkloadType::kMixed, 3, config_.admission_watermark_ratio,
+        config_.admission_frequency_threshold);
+    std::shared_ptr<mooncake::EvictionStrategy> legacy_strategy;
+    if (config_.legacy_fallback == LegacyFallback::kFifo) {
+        legacy_strategy = std::make_shared<FIFOEvictionStrategy>();
+    } else {
+        legacy_strategy = std::make_shared<LRUEvictionStrategy>();
+    }
+    auto fallback = std::make_shared<ComposedPolicyEngine>(
+        std::make_shared<LegacyEvictionOps>(std::move(legacy_strategy)),
+        nullptr, std::make_shared<PrefixMatchAdmissionOps>());
+    policy_ = std::make_shared<DegradingPolicyEngine>(workload_policy_, fallback);
+    admission_worker_ = std::thread(&IoPatternRuntime::AdmissionWorker, this);
+    if (config_.report_driven_execution) {
+        report_worker_ =
+            std::thread(&IoPatternRuntime::ReportDrivenWorker, this);
+    }
+}
+
+IoPatternRuntime::~IoPatternRuntime() {
+    {
+        std::lock_guard lock(admission_mutex_);
+        admission_stopping_ = true;
+        pending_admissions_.clear();
+    }
+    admission_condition_.notify_all();
+    if (admission_worker_.joinable()) admission_worker_.join();
+    {
+        std::lock_guard lock(report_mutex_);
+        report_stopping_ = true;
+        report_pending_ = false;
+    }
+    report_condition_.notify_all();
+    if (report_worker_.joinable()) report_worker_.join();
+    if (reporter_) reporter_->Stop();
+}
+
+void IoPatternRuntime::ReportInferenceMetrics(const InferenceMetrics& metrics) {
+    const auto start = std::chrono::steady_clock::now();
+    const auto dropped_before = collector_->dropped();
+    collector_->ReportInferenceMetrics(metrics);
+    observability_.RecordCollectLatency(
+        std::chrono::duration_cast<std::chrono::microseconds>(
+            std::chrono::steady_clock::now() - start)
+            .count());
+    const auto dropped_after = collector_->dropped();
+    if (dropped_after > dropped_before)
+        observability_.RecordReportDrop(dropped_after - dropped_before);
+}
+
+void IoPatternRuntime::RecordAccess(const std::string& key,
+                                    const AccessRecord& record) {
+    const auto start = std::chrono::steady_clock::now();
+    const auto dropped_before = collector_->dropped();
+    collector_->RecordAccess(key, record);
+    observability_.RecordCollectLatency(
+        std::chrono::duration_cast<std::chrono::microseconds>(
+            std::chrono::steady_clock::now() - start)
+            .count());
+    const auto dropped_after = collector_->dropped();
+    if (dropped_after > dropped_before)
+        observability_.RecordReportDrop(dropped_after - dropped_before);
+
+    PolicyFeedbackSample feedback;
+    bool has_feedback = false;
+    {
+        std::lock_guard lock(feedback_state_mutex_);
+        ++feedback_accesses_;
+        feedback_hits_ += record.is_hit;
+        ObjectRef object = record.object;
+        if (!key.empty()) object.key = key;
+        if (pending_prefetches_.erase(object) != 0) {
+            feedback.prefetch_accuracy = record.is_hit ? 1.0F : 0.0F;
+            has_feedback = true;
+            if (!record.is_hit) observability_.RecordFalsePositive();
+        }
+        // A completed 64-access window is a stable, bounded source of actual
+        // hit-rate deltas. TTFT remains supplied by the inference bridge via
+        // the public RecordFeedback API.
+        if (feedback_accesses_ >= 64) {
+            const auto hit_rate = static_cast<float>(feedback_hits_) /
+                                  static_cast<float>(feedback_accesses_);
+            feedback.hit_rate_delta = hit_rate - previous_hit_rate_;
+            previous_hit_rate_ = hit_rate;
+            feedback_accesses_ = 0;
+            feedback_hits_ = 0;
+            has_feedback = true;
+        }
+    }
+    if (has_feedback) RecordFeedback(feedback);
+}
+
+void IoPatternRuntime::RecordStorageMetric(const StorageMetric& metric) {
+    const auto start = std::chrono::steady_clock::now();
+    const auto dropped_before = collector_->dropped();
+    collector_->RecordStorageMetric(metric);
+    observability_.RecordCollectLatency(
+        std::chrono::duration_cast<std::chrono::microseconds>(
+            std::chrono::steady_clock::now() - start)
+            .count());
+    const auto dropped_after = collector_->dropped();
+    if (dropped_after > dropped_before)
+        observability_.RecordReportDrop(dropped_after - dropped_before);
+}
+
+void IoPatternRuntime::MergeSnapshot(const IoPatternSnapshot& snapshot) {
+    const auto start = std::chrono::steady_clock::now();
+    const auto dropped_before = collector_->dropped();
+    collector_->MergeSnapshot(snapshot);
+    observability_.RecordCollectLatency(
+        std::chrono::duration_cast<std::chrono::microseconds>(
+            std::chrono::steady_clock::now() - start)
+            .count());
+    const auto dropped_after = collector_->dropped();
+    if (dropped_after > dropped_before) {
+        observability_.RecordReportDrop(dropped_after - dropped_before);
+    }
+}
+
+void IoPatternRuntime::RecordTierEvent(const CacheEvent& event) {
+    collector_->RecordTierEvent(event);
+}
+
+bool IoPatternRuntime::FlushReports() { return collector_->FlushReports(); }
+
+void IoPatternRuntime::StopReports() { collector_->StopReports(); }
+
+PatternResult IoPatternRuntime::AnalyzeWithinBudget(
+    const IoPatternSnapshot& snapshot, bool& degraded) {
+    degraded = config_.max_analysis_keys != 0 &&
+               snapshot.keys.size() > config_.max_analysis_keys;
+    if (degraded || analysis_in_flight_->exchange(true, std::memory_order_acq_rel)) {
+        degraded = true;
+        return analyzer_->FallbackResult();
+    }
+
+    std::promise<PatternResult> promise;
+    auto result = promise.get_future();
+    auto analyzer = analyzer_;
+    auto in_flight = analysis_in_flight_;
+    std::thread([analyzer = std::move(analyzer), snapshot,
+                 promise = std::move(promise), in_flight]() mutable {
+        try {
+            promise.set_value(analyzer->Analyze(snapshot));
+        } catch (...) {
+            promise.set_value(analyzer->FallbackResult());
+        }
+        in_flight->store(false, std::memory_order_release);
+    }).detach();
+
+    if (result.wait_for(std::chrono::microseconds(config_.analysis_timeout_us)) ==
+        std::future_status::ready) {
+        return result.get();
+    }
+    degraded = true;
+    return analyzer_->FallbackResult();
+}
+
+PolicyExecutionStatus IoPatternRuntime::Execute(
+    CacheTier eviction_tier, uint64_t eviction_bytes, const TraceHistory& trace,
+    const std::vector<ObjectRef>& admissions, const std::string& session_id) {
+    auto planned = BuildPolicy(eviction_tier, eviction_bytes, trace, admissions,
+                               session_id);
+    return CommitPolicy(planned);
+}
+
+PolicyExecutionStatus IoPatternRuntime::CommitPolicy(PlannedPolicy& planned) {
+    const auto& snapshot = planned.snapshot;
+    const auto& result = planned.result;
+    auto status = executor_.Execute(result);
+    status.degraded = status.degraded || result.degraded;
+    const bool failed = IsPolicyFailure(status.eviction) ||
+                        IsPolicyFailure(status.prefetch) || status.degraded;
+    if (failed)
+        policy_->RecordFailure();
+    else
+        policy_->RecordSuccess();
+    if (status.degraded || policy_->degraded()) observability_.RecordDegrade();
+    status.degraded = status.degraded || policy_->degraded();
+
+    PolicyFeedbackSample feedback;
+    bool has_feedback = false;
+    {
+        std::lock_guard lock(feedback_state_mutex_);
+        for (const auto& candidate : result.prefetch.candidates) {
+            if (config_.max_pending_prefetches == 0 ||
+                pending_prefetches_.size() < config_.max_pending_prefetches) {
+                pending_prefetches_.insert(candidate.object);
+            }
+        }
+        if (!result.prefetch.candidates.empty() &&
+            status.prefetch != ErrorCode::OK) {
+            feedback.prefetch_accuracy = 0.0F;
+            has_feedback = true;
+        }
+        if (!snapshot.keys.empty() && !result.eviction.candidates.empty()) {
+            feedback.eviction_churn = static_cast<float>(
+                result.eviction.candidates.size()) /
+                                      static_cast<float>(snapshot.keys.size());
+            has_feedback = true;
+        }
+    }
+    if (has_feedback) RecordFeedback(feedback);
+    return status;
+}
+
+PolicyResult IoPatternRuntime::Plan(
+    CacheTier eviction_tier, uint64_t eviction_bytes, const TraceHistory& trace,
+    const std::vector<ObjectRef>& admissions, const std::string& session_id) {
+    return BuildPolicy(eviction_tier, eviction_bytes, trace, admissions,
+                       session_id)
+        .result;
+}
+
+IoPatternRuntime::PlannedPolicy IoPatternRuntime::BuildPolicy(
+    CacheTier eviction_tier, uint64_t eviction_bytes, const TraceHistory& trace,
+    const std::vector<ObjectRef>& admissions, const std::string& session_id,
+    uint64_t min_idle_time_us, bool tier_down) {
+    PlannedPolicy planned;
+    planned.snapshot = collector_->GetSnapshot();
+    const auto start = std::chrono::steady_clock::now();
+    const auto analysis =
+        AnalyzeWithinBudget(planned.snapshot, planned.analysis_degraded);
+    planned.analysis_elapsed_us = static_cast<uint64_t>(
+        std::chrono::duration_cast<std::chrono::microseconds>(
+            std::chrono::steady_clock::now() - start)
+            .count());
+    observability_.RecordAnalyzeLatency(planned.analysis_elapsed_us);
+
+    workload_policy_->SetWorkloadType(analysis.workload_type);
+    workload_policy_->SetSessionWorkloads(analysis.sessions);
+    workload_policy_->AdvanceTransitionWindow();
+    planned.result = policy_->ExecutePolicy(
+        PolicyContext{.snapshot = planned.snapshot,
+                      .analysis = analysis,
+                      .session_id = session_id,
+                      .min_idle_time_us = min_idle_time_us,
+                      .tier_down = tier_down},
+        eviction_tier, eviction_bytes, CacheTier::kL1Host, trace, admissions);
+    planned.result.degraded =
+        planned.result.degraded || collector_->degraded() ||
+        planned.analysis_degraded ||
+        planned.analysis_elapsed_us > config_.analysis_timeout_us;
+    observability_.RecordPolicyDecision(
+        !planned.result.eviction.candidates.empty() ||
+        !planned.result.prefetch.candidates.empty());
+    return planned;
+}
+
+ErrorCode IoPatternRuntime::ExecuteCommand(const PolicyCommand& command) {
+    PolicyResult result;
+    if (const auto* eviction = std::get_if<EvictionPlan>(&command)) {
+        result.eviction = *eviction;
+    } else if (const auto* prefetch = std::get_if<PrefetchPlan>(&command)) {
+        result.prefetch = *prefetch;
+    } else {
+        result.admissions.push_back(std::get<AdmissionResult>(command));
+    }
+    const auto status = executor_.Execute(result);
+    if (status.degraded) {
+        observability_.RecordDegrade();
+        return ErrorCode::UNAVAILABLE_IN_CURRENT_MODE;
+    }
+    if (const auto* eviction = std::get_if<EvictionPlan>(&command)) {
+        return status.eviction;
+    }
+    if (const auto* prefetch = std::get_if<PrefetchPlan>(&command)) {
+        return status.prefetch;
+    }
+    return status.admissions.empty() ? ErrorCode::OK : status.admissions.front();
+}
+
+void IoPatternRuntime::RequestReportDrivenExecution() {
+    if (!config_.report_driven_execution) return;
+    {
+        std::lock_guard lock(report_mutex_);
+        if (report_stopping_) return;
+        report_pending_ = true;
+    }
+    // notify_all: a concurrent WaitForReportDrivenIdle() must not swallow the
+    // worker's wakeup (predicates re-check under the mutex either way).
+    report_condition_.notify_all();
+}
+
+void IoPatternRuntime::WaitForReportDrivenIdle() {
+    if (!config_.report_driven_execution) return;
+    std::unique_lock lock(report_mutex_);
+    report_condition_.wait(lock, [this] {
+        return report_stopping_ || (!report_pending_ && !report_worker_busy_);
+    });
+}
+
+void IoPatternRuntime::ReportDrivenWorker() {
+    while (true) {
+        {
+            std::unique_lock lock(report_mutex_);
+            report_condition_.wait(lock, [this] {
+                return report_stopping_ || report_pending_;
+            });
+            if (report_stopping_) return;
+            report_pending_ = false;
+            report_worker_busy_ = true;
+        }
+        try {
+            RunReportDrivenCycle();
+        } catch (...) {
+            policy_->RecordFailure();
+            observability_.RecordDegrade();
+        }
+        {
+            std::lock_guard lock(report_mutex_);
+            report_worker_busy_ = false;
+        }
+        report_condition_.notify_all();
+    }
+}
+
+void IoPatternRuntime::DeriveEvictionRequest(const IoPatternSnapshot& snapshot,
+                                             float high_ratio,
+                                             float target_ratio,
+                                             CacheTier& eviction_tier,
+                                             uint64_t& eviction_bytes) {
+    // The Store-side eviction handler is tenant-qualified MEMORY (L1) quota
+    // eviction; L2/L3 pressure is handled by the legacy NoF/SSD paths outside
+    // the IO Pattern runtime. Restrict the report-driven eviction dimension to
+    // host-memory watermarks so L2/L3 reports never route lower-tier keys into
+    // the memory quota eviction handler.
+    eviction_tier = CacheTier::kL1Host;
+    eviction_bytes = 0;
+    float peak_ratio = 0.0F;
+    uint64_t capacity_bytes = 0;
+    for (const auto& metric : snapshot.storage) {
+        if (metric.tier != CacheTier::kL1Host) continue;
+        if (metric.memory_used_ratio > peak_ratio) {
+            peak_ratio = metric.memory_used_ratio;
+            capacity_bytes = metric.capacity_bytes;
+        }
+    }
+    // No merged host-memory watermark, or below the high watermark: the merged
+    // snapshot does not indicate pressure, so the eviction dimension produces
+    // no action (the prefetch/admission dimensions are still evaluated).
+    if (peak_ratio < high_ratio) return;
+    // An eviction plan needs L1 keys to select candidates from. A report that
+    // only carries storage watermarks (no key observations for this tier)
+    // would otherwise execute an empty eviction plan through the handler on
+    // every cycle.
+    bool any_l1_keys = false;
+    for (const auto& key : snapshot.keys) {
+        if ((key.replica_tiers & CacheTierBit(CacheTier::kL1Host)) != 0) {
+            any_l1_keys = true;
+            break;
+        }
+    }
+    if (!any_l1_keys) return;
+    if (capacity_bytes == 0) {
+        for (const auto& metric : snapshot.storage) {
+            if (metric.tier == CacheTier::kL1Host &&
+                metric.memory_used_ratio == peak_ratio &&
+                metric.used_bytes != 0) {
+                capacity_bytes = static_cast<uint64_t>(
+                    static_cast<double>(metric.used_bytes) /
+                    static_cast<double>(metric.memory_used_ratio));
+                break;
+            }
+        }
+    }
+    const double reclaim_fraction =
+        static_cast<double>(peak_ratio) - static_cast<double>(target_ratio);
+    if (reclaim_fraction <= 0.0) return;
+    const double target = reclaim_fraction * static_cast<double>(capacity_bytes);
+    eviction_bytes = target > 0.0
+                         ? static_cast<uint64_t>(target)
+                         : (capacity_bytes > 0 ? capacity_bytes / 10 : 0);
+}
+
+TraceHistory IoPatternRuntime::DeriveTraceHistory(
+    const IoPatternSnapshot& snapshot) {
+    // Report-driven prefetch input: keys that were recently served as hits and
+    // still have a lower-tier replica are the ones a promotion should bring
+    // closer to the head. TraceBasedPrefetchOps re-applies its own
+    // match-length / confidence gates against this candidate trace.
+    TraceHistory trace;
+    const auto now_ns = static_cast<uint64_t>(
+        std::chrono::duration_cast<std::chrono::nanoseconds>(
+            std::chrono::steady_clock::now().time_since_epoch())
+            .count());
+    for (const auto& key : snapshot.keys) {
+        if (!key.active || key.access_count_window == 0) continue;
+        // Any replica deeper than host memory is a promotion candidate; local
+        // disk is the only one the store can actually move up, but the others
+        // still belong in the trace so the ops layer decides.
+        const bool has_lower_replica =
+            (key.replica_tiers & CacheTierBit(CacheTier::kLocalDisk)) != 0 ||
+            (key.replica_tiers & CacheTierBit(CacheTier::kL2Segment)) != 0 ||
+            (key.replica_tiers & CacheTierBit(CacheTier::kL3NofSsd)) != 0;
+        if (!has_lower_replica) {
+            continue;
+        }
+        trace.events.push_back(
+            TraceEvent{.object = key.object,
+                       .observed_at_ns = now_ns,
+                       .match_length = key.match_length,
+                       .is_hit = true});
+    }
+    return trace;
+}
+
+std::vector<ObjectRef> IoPatternRuntime::DeriveAdmissionCandidates(
+    const IoPatternSnapshot& snapshot) {
+    // Report-driven admission input: lower-tier objects that the merged
+    // reports show as hot (frequent reads) and that are not already in the
+    // head tier are promotion candidates. PrefixMatchAdmissionOps re-applies
+    // its frequency/watermark gates per object before execution.
+    std::vector<ObjectRef> candidates;
+    for (const auto& key : snapshot.keys) {
+        if (key.pinned || key.access_count_window == 0) continue;
+        const bool in_head =
+            (key.replica_tiers & CacheTierBit(CacheTier::kL1Host)) != 0;
+        const bool lower_tier =
+            (key.replica_tiers & CacheTierBit(CacheTier::kLocalDisk)) != 0 ||
+            (key.replica_tiers & CacheTierBit(CacheTier::kL2Segment)) != 0 ||
+            (key.replica_tiers & CacheTierBit(CacheTier::kL3NofSsd)) != 0;
+        if (!in_head && lower_tier) candidates.push_back(key.object);
+    }
+    return candidates;
+}
+
+void IoPatternRuntime::RunReportDrivenCycle() {
+    IoPatternSnapshot snapshot = collector_->GetSnapshot();
+    ReportDrivenCycleReport report;
+    report.cycle_id = ++report_cycle_id_;
+    report.keys_analyzed = snapshot.keys.size();
+    if (snapshot.keys.empty() && snapshot.storage.empty()) {
+        if (config_.report_driven_observer) {
+            config_.report_driven_observer(report);
+        }
+        return;
+    }
+    CacheTier eviction_tier = CacheTier::kL1Host;
+    uint64_t eviction_bytes = 0;
+    DeriveEvictionRequest(snapshot, config_.report_eviction_high_ratio,
+                          config_.report_eviction_target_ratio, eviction_tier,
+                          eviction_bytes);
+    // Tier-down driver: the below-watermark placement action. Copy the coldest
+    // in-memory keys down to LOCAL_DISK while keeping their MEMORY replica, so a
+    // later reclaim of those keys can discard them safely instead of copying then.
+    // A demotion frees nothing, so it must never win over a reclaim: the pressure
+    // request above takes the cycle whenever the watermark is reached, and this
+    // driver only fills the cycle that would otherwise do nothing. The budget is
+    // the whole control (no enable flag); the driver decides the action here, and
+    // the policy must never derive it from target_tier.
+    bool tier_down = false;
+    if (eviction_bytes == 0 && config_.tier_down_bytes_per_cycle != 0) {
+        eviction_bytes = config_.tier_down_bytes_per_cycle;
+        tier_down = true;
+        report.tier_down = true;
+    }
+    // Cold-data eviction driver: when the merged storage watermark does not
+    // trigger a pressure eviction but the analysis-relevant snapshot contains
+    // idle L1 keys, run a bounded eviction of the coldest keys so eviction is
+    // driven by cold/hot analysis and not only by memory pressure. Candidate
+    // selection still goes through the policy engine (ScoreBasedEvictionOps
+    // ranks the coldest first); this driver only supplies a byte target.
+    //
+    // It also acts below the watermark, but it reclaims instead of placing, so it
+    // only takes the slot when no tier-down budget is configured: demoting a key
+    // the same cycle would have discarded defeats the point of paving cold data
+    // down first.
+    uint64_t cold_idle_threshold_us = 0;
+    if (eviction_bytes == 0 && config_.report_driven_cold_eviction &&
+        config_.report_driven_cold_eviction_bytes != 0) {
+        // The idle gate is applied where the policy selects victims, so the byte
+        // budget and the victim set describe the same keys. Pre-summing the idle
+        // keys' bytes here produced a target the selector was free to ignore.
+        eviction_bytes = config_.report_driven_cold_eviction_bytes;
+        cold_idle_threshold_us = config_.report_driven_cold_idle_threshold_us;
+        report.cold_eviction = true;
+    }
+    report.eviction_tier = eviction_tier;
+    report.eviction_target_bytes = eviction_bytes;
+    const auto trace = DeriveTraceHistory(snapshot);
+    const auto admissions = DeriveAdmissionCandidates(snapshot);
+    report.admission_candidates = admissions.size();
+
+    auto planned = BuildPolicy(eviction_tier, eviction_bytes, trace,
+                               admissions, "report-driven",
+                               cold_idle_threshold_us, tier_down);
+    report.analysis_elapsed_us = planned.analysis_elapsed_us;
+    const auto& result = planned.result;
+    report.eviction_candidates = result.eviction.candidates.size();
+    report.prefetch_candidates = result.prefetch.candidates.size();
+    size_t admitted = 0;
+    for (const auto& admission : result.admissions) {
+        if (admission.decision == AdmissionDecision::kAdmit) ++admitted;
+    }
+    report.admissions_admitted = admitted;
+    // A pressure report with no evictable L1 keys is a clean no-op for the
+    // eviction dimension, not a policy failure: do not invoke the storage
+    // handler with an empty candidate list (TierOperationExecutor otherwise
+    // forwards any non-zero target). Keep the derived target visible in the
+    // report for observability.
+    if (report.eviction_candidates == 0) {
+        planned.result.eviction.target_bytes = 0;
+        planned.result.eviction.candidates.clear();
+    }
+    const auto status = CommitPolicy(planned);
+    report.degraded = status.degraded || planned.result.degraded;
+    report.eviction_status = status.eviction;
+    report.prefetch_status = status.prefetch;
+    report.skipped_dimensions = status.skipped;
+    if (!status.admissions.empty()) {
+        report.admission_status = status.admissions.front();
+    }
+    if (config_.report_driven_observer) {
+        config_.report_driven_observer(report);
+    }
+}
+
+bool IoPatternRuntime::ScheduleAdmission(ObjectRef object, CacheTier target_tier,
+                                         std::string session_id) {
+    {
+        std::lock_guard lock(admission_mutex_);
+        if (admission_stopping_ ||
+            (config_.max_pending_admissions != 0 &&
+             pending_admissions_.size() >= config_.max_pending_admissions)) {
+            return false;
+        }
+        pending_admissions_.push_back(
+            {.object = std::move(object),
+             .target_tier = target_tier,
+             .session_id = std::move(session_id)});
+    }
+    admission_condition_.notify_one();
+    return true;
+}
+
+void IoPatternRuntime::AdmissionWorker() {
+    while (true) {
+        PendingAdmission pending;
+        {
+            std::unique_lock lock(admission_mutex_);
+            admission_condition_.wait(lock, [this] {
+                return admission_stopping_ || !pending_admissions_.empty();
+            });
+            if (admission_stopping_) return;
+            pending = std::move(pending_admissions_.front());
+            pending_admissions_.pop_front();
+        }
+        try {
+            ExecuteAdmission(pending.object, pending.target_tier,
+                             pending.session_id);
+        } catch (...) {
+            policy_->RecordFailure();
+            observability_.RecordDegrade();
+        }
+    }
+}
+
+ErrorCode IoPatternRuntime::ExecuteAdmission(const ObjectRef& object,
+                                             CacheTier target_tier,
+                                             const std::string& session_id) {
+    const auto snapshot = collector_->GetSnapshot();
+    bool analysis_degraded = false;
+    const auto analysis = AnalyzeWithinBudget(snapshot, analysis_degraded);
+    workload_policy_->SetWorkloadType(analysis.workload_type);
+    workload_policy_->SetSessionWorkloads(analysis.sessions);
+    const auto admission = policy_->DecideAdmission(
+        object, target_tier,
+        PolicyContext{.snapshot = snapshot,
+                      .analysis = analysis,
+                      .session_id = session_id});
+    PolicyResult result;
+    result.admissions.push_back(admission);
+    auto status = executor_.Execute(result);
+    if (analysis_degraded) status.degraded = true;
+    const auto code = status.admissions.empty() ? ErrorCode::OK
+                                                 : status.admissions.front();
+    if (IsPolicyFailure(code) || status.degraded)
+        observability_.RecordDegrade();
+    return code;
+}
+
+void IoPatternRuntime::RecordFeedback(PolicyFeedbackSample sample) {
+    // Tuner state is not internally synchronized; the report-driven worker,
+    // the eviction thread and the data path can all reach RecordFeedback.
+    // feedback_state_mutex_ serializes them (all callers invoke this method
+    // outside that lock, so there is no recursive acquisition).
+    std::lock_guard lock(feedback_state_mutex_);
+    feedback_.Record(sample);
+    auto config = workload_policy_->CurrentEvictionConfig();
+    if (tuner_.Tune(feedback_.Snapshot(), config)) {
+        workload_policy_->ApplyEvictionTuning(config);
+    }
+}
+
+PolicyFeedbackStats IoPatternRuntime::FeedbackSnapshot() const {
+    return feedback_.Snapshot();
+}
+
+IoPatternSnapshot IoPatternRuntime::Snapshot() const {
+    return collector_->GetSnapshot();
+}
+
+IoPatternObservabilitySnapshot IoPatternRuntime::ObservabilitySnapshot(
+    double window_seconds) const {
+    if (window_seconds <= 0.0) {
+        window_seconds = std::chrono::duration<double>(
+                             std::chrono::steady_clock::now() - started_at_)
+                             .count();
+    }
+    return observability_.Snapshot(window_seconds);
+}
+
+bool IoPatternRuntime::degraded() const {
+    return collector_->degraded() || analyzer_->degraded() || policy_->degraded();
+}
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/src/io_pattern/sliding_window_analyzer.cpp b/mooncake-store/src/io_pattern/sliding_window_analyzer.cpp
new file mode 100644
index 0000000000..2020f8d021
--- /dev/null
+++ b/mooncake-store/src/io_pattern/sliding_window_analyzer.cpp
@@ -0,0 +1,128 @@
+#include "io_pattern/sliding_window_analyzer.h"
+
+#include <algorithm>
+#include <unordered_map>
+#include <vector>
+
+namespace mooncake::io_pattern {
+namespace {
+template <typename T>
+T Percentile(std::vector<T> values, size_t rank) {
+    if (values.empty()) return 0;
+    std::sort(values.begin(), values.end());
+    return values[std::min(rank, values.size() - 1)];
+}
+
+std::vector<KeyMetrics> LatestKeys(
+    const std::deque<IoPatternSnapshot>& history) {
+    std::unordered_map<ObjectRef, KeyMetrics, ObjectRefHash> latest;
+    for (const auto& snapshot : history) {
+        for (const auto& key : snapshot.keys) latest[key.object] = key;
+    }
+    std::vector<KeyMetrics> keys;
+    keys.reserve(latest.size());
+    for (auto& [object, key] : latest) {
+        (void)object;
+        keys.push_back(std::move(key));
+    }
+    std::sort(keys.begin(), keys.end(), [](const KeyMetrics& left,
+                                           const KeyMetrics& right) {
+        if (left.object.tenant_id != right.object.tenant_id) {
+            return left.object.tenant_id < right.object.tenant_id;
+        }
+        return left.object.key < right.object.key;
+    });
+    return keys;
+}
+}
+
+void SlidingWindowAnalyzer::Append(const IoPatternSnapshot& snapshot) const {
+    std::lock_guard lock(mutex_);
+    IoPatternSnapshot bounded = snapshot;
+    if (max_history_keys_ != 0 &&
+        bounded.keys.size() > max_history_keys_) {
+        std::sort(bounded.keys.begin(), bounded.keys.end(),
+                  [](const KeyMetrics& left, const KeyMetrics& right) {
+                      if (left.object.tenant_id != right.object.tenant_id) {
+                          return left.object.tenant_id < right.object.tenant_id;
+                      }
+                      return left.object.key < right.object.key;
+                  });
+        bounded.keys.resize(max_history_keys_);
+    }
+    if (history_.empty() ||
+        history_.back().generated_at_ns != bounded.generated_at_ns) {
+        history_key_count_ += bounded.keys.size();
+        history_.push_back(std::move(bounded));
+    }
+    const uint64_t cutoff = snapshot.generated_at_ns > window_ns_
+                                ? snapshot.generated_at_ns - window_ns_
+                                : 0;
+    while (!history_.empty() && history_.front().generated_at_ns < cutoff) {
+        history_key_count_ -= history_.front().keys.size();
+        history_.pop_front();
+    }
+    while (max_history_keys_ != 0 && history_key_count_ > max_history_keys_) {
+        history_key_count_ -= history_.front().keys.size();
+        history_.pop_front();
+    }
+}
+
+IoPatternSnapshot SlidingWindowAnalyzer::Aggregate(
+    const IoPatternSnapshot& current) const {
+    Append(current);
+    std::lock_guard lock(mutex_);
+    IoPatternSnapshot aggregate = current;
+    aggregate.keys = LatestKeys(history_);
+    return aggregate;
+}
+
+PatternResult SlidingWindowAnalyzer::Analyze(
+    const IoPatternSnapshot& snapshot) const {
+    const auto aggregate = Aggregate(snapshot);
+    auto result = analyzer_.Analyze(aggregate);
+    return result.workload_type == WorkloadType::kMixed
+               ? kmeans_.Analyze(aggregate)
+               : result;
+}
+
+WorkloadType SlidingWindowAnalyzer::DetectWorkloadType(
+    const IoPatternSnapshot& snapshot) const {
+    return Analyze(snapshot).workload_type;
+}
+
+float SlidingWindowAnalyzer::CalculateConfidence(
+    const ObjectRef& object, const IoPatternSnapshot& snapshot) const {
+    const auto result = Analyze(snapshot);
+    const auto it = std::find_if(result.keys.begin(), result.keys.end(),
+                                 [&object](const KeyPattern& key) {
+                                     return key.object == object;
+                                 });
+    return it == result.keys.end() ? 0.0F : it->confidence;
+}
+
+WorkloadFeatureStats SlidingWindowAnalyzer::FeatureStats() const {
+    std::lock_guard lock(mutex_);
+    std::vector<uint32_t> tokens, fanouts, matches, frequencies;
+    std::vector<uint64_t> blocks;
+    for (const auto& key : LatestKeys(history_)) {
+        tokens.push_back(key.token_count);
+        fanouts.push_back(key.prefix_fanout);
+        matches.push_back(key.match_length);
+        frequencies.push_back(static_cast<uint32_t>(key.access_count_window));
+        blocks.push_back(key.block_size);
+    }
+    const auto p90 = [](size_t size) { return size == 0 ? 0 : (size * 9) / 10; };
+    WorkloadFeatureStats stats;
+    stats.samples = tokens.size();
+    stats.token_median = Percentile(tokens, tokens.size() / 2);
+    stats.token_p90 = Percentile(tokens, p90(tokens.size()));
+    stats.fanout_p90 = Percentile(fanouts, p90(fanouts.size()));
+    stats.block_median = Percentile(blocks, blocks.size() / 2);
+    stats.block_p90 = Percentile(blocks, p90(blocks.size()));
+    stats.match_p90 = Percentile(matches, p90(matches.size()));
+    stats.frequency_median = Percentile(frequencies, frequencies.size() / 2);
+    return stats;
+}
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/src/io_pattern/threshold_analyzer.cpp b/mooncake-store/src/io_pattern/threshold_analyzer.cpp
new file mode 100644
index 0000000000..7bcfe4028f
--- /dev/null
+++ b/mooncake-store/src/io_pattern/threshold_analyzer.cpp
@@ -0,0 +1,158 @@
+#include "io_pattern/threshold_analyzer.h"
+
+#include <algorithm>
+
+namespace mooncake::io_pattern {
+namespace {
+
+bool IsCodeAgent(const KeyMetrics& key, const ThresholdAnalyzerConfig& config) {
+    return key.token_count > config.code_agent_token_count &&
+           key.prefix_fanout > config.code_agent_prefix_fanout &&
+           key.match_length > config.code_agent_match_length;
+}
+
+bool IsRecommendation(const KeyMetrics& key,
+                      const ThresholdAnalyzerConfig& config) {
+    return key.block_size < config.recommendation_block_size &&
+           key.access_count_window > config.recommendation_frequency;
+}
+
+// A code-agent key already satisfies the conversation dimensions (fanout and
+// match length), so conversation is scoped to the non-huge-context case.
+// Without that bound every code-agent key also matched this rule, matched > 1
+// forced kMixed, and kCodeAgent became unreachable under the default config.
+bool IsConversation(const KeyMetrics& key,
+                    const ThresholdAnalyzerConfig& config) {
+    return key.token_count <= config.code_agent_token_count &&
+           key.prefix_fanout > config.conversation_prefix_fanout &&
+           key.match_length > config.conversation_match_length;
+}
+
+// Similarity of one reported dimension to a rule threshold. A dimension the key
+// does not report at all (zero) contributes nothing instead of acting as a
+// zero-similarity term: combining dimensions with std::min forced every partial
+// match to zero as soon as a single metric was absent, which is the common case
+// for a key observed through only one data path.
+float ReportedRatio(float value, float threshold) {
+    if (value <= 0.0F) {
+        return 0.0F;
+    }
+    return std::min(1.0F, value / std::max(1.0F, threshold));
+}
+
+float RuleConfidence(const KeyMetrics& key,
+                     const ThresholdAnalyzerConfig& config) {
+    float score = 0.0F;
+    if (IsCodeAgent(key, config)) score = std::max(score, 1.0F);
+    if (IsRecommendation(key, config)) score = std::max(score, 1.0F);
+    if (IsConversation(key, config)) score = std::max(score, 1.0F);
+    // A partial match is useful to policies, but must not look like a
+    // definitive workload classification.
+    if (score == 0.0F) {
+        const float code = std::max(
+            {ReportedRatio(static_cast<float>(key.token_count),
+                           static_cast<float>(config.code_agent_token_count)),
+             ReportedRatio(static_cast<float>(key.prefix_fanout),
+                           static_cast<float>(config.code_agent_prefix_fanout)),
+             ReportedRatio(static_cast<float>(key.match_length),
+                           static_cast<float>(config.code_agent_match_length))});
+        // The recommendation rule rewards a *small* block, so its block term is
+        // inverted; an unset block_size counts as unreported.
+        const float block_ratio =
+            key.block_size == 0
+                ? 0.0F
+                : std::min(1.0F,
+                           static_cast<float>(config.recommendation_block_size) /
+                               static_cast<float>(key.block_size));
+        const float recommendation = std::max(
+            block_ratio,
+            ReportedRatio(static_cast<float>(key.access_count_window),
+                          static_cast<float>(config.recommendation_frequency)));
+        const float conversation = std::max(
+            ReportedRatio(static_cast<float>(key.prefix_fanout),
+                          static_cast<float>(config.conversation_prefix_fanout)),
+            ReportedRatio(static_cast<float>(key.match_length),
+                          static_cast<float>(config.conversation_match_length)));
+        score = std::clamp(std::max({code, recommendation, conversation}),
+                           0.0F, 1.0F);
+    }
+    return score;
+}
+
+}  // namespace
+
+PatternResult ThresholdAnalyzer::Analyze(
+    const IoPatternSnapshot& snapshot) const {
+    PatternResult result;
+    result.workload_type = DetectWorkloadType(snapshot);
+    if (!snapshot.keys.empty()) {
+        float total = 0.0F;
+        for (const auto& key : snapshot.keys) total += KeyConfidence(key);
+        result.workload_confidence =
+            std::clamp(total / static_cast<float>(snapshot.keys.size()), 0.0F,
+                       1.0F);
+    }
+    result.keys.reserve(snapshot.keys.size());
+    for (const auto& key : snapshot.keys) {
+        KeyPattern pattern;
+        pattern.object = key.object;
+        pattern.confidence = KeyConfidence(key);
+        pattern.frequency_score = std::min(
+            1.0F, static_cast<float>(key.access_count_window) / 20.0F);
+        pattern.idle_score = std::min(
+            1.0F, static_cast<float>(key.idle_time_us) / 1'000'000.0F);
+        pattern.prefix_score = std::min(
+            1.0F, static_cast<float>(key.match_length) / 256.0F);
+        pattern.recompute_score = std::min(1.0F, key.recompute_cost);
+        pattern.transfer_roi = key.transfer_eta_us == 0
+                                   ? 0.0F
+                                   : key.recompute_cost /
+                                         static_cast<float>(key.transfer_eta_us);
+        pattern.migration_safe = !key.pinned;
+        result.keys.push_back(pattern);
+    }
+    return result;
+}
+
+WorkloadType ThresholdAnalyzer::DetectWorkloadType(
+    const IoPatternSnapshot& snapshot) const {
+    if (snapshot.keys.empty()) {
+        return WorkloadType::kMixed;
+    }
+    uint32_t code_agents = 0;
+    uint32_t recommendations = 0;
+    uint32_t conversations = 0;
+    for (const auto& key : snapshot.keys) {
+        code_agents += IsCodeAgent(key, config_);
+        recommendations += IsRecommendation(key, config_);
+        conversations += IsConversation(key, config_);
+    }
+    const uint32_t matched = static_cast<uint32_t>(code_agents != 0) +
+                             static_cast<uint32_t>(recommendations != 0) +
+                             static_cast<uint32_t>(conversations != 0);
+    if (matched > 1) return WorkloadType::kMixed;
+    if (code_agents != 0) return WorkloadType::kCodeAgent;
+    if (recommendations != 0) return WorkloadType::kGenerativeRecommendation;
+    if (conversations != 0) return WorkloadType::kMultiTurnConversation;
+    return WorkloadType::kMixed;
+}
+
+float ThresholdAnalyzer::CalculateConfidence(
+    const ObjectRef& object, const IoPatternSnapshot& snapshot) const {
+    const auto* key = FindKey(object, snapshot);
+    return key == nullptr ? 0.0F : KeyConfidence(*key);
+}
+
+const KeyMetrics* ThresholdAnalyzer::FindKey(
+    const ObjectRef& object, const IoPatternSnapshot& snapshot) const {
+    const auto it = std::find_if(
+        snapshot.keys.begin(), snapshot.keys.end(),
+        [&object](const KeyMetrics& key) { return key.object == object; });
+    return it == snapshot.keys.end() ? nullptr : &*it;
+}
+
+float ThresholdAnalyzer::KeyConfidence(const KeyMetrics& key) const {
+    return RuleConfidence(key, config_);
+}
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/src/io_pattern/tier_executor.cpp b/mooncake-store/src/io_pattern/tier_executor.cpp
new file mode 100644
index 0000000000..4bfd0d1b37
--- /dev/null
+++ b/mooncake-store/src/io_pattern/tier_executor.cpp
@@ -0,0 +1,54 @@
+#include "io_pattern/tier_executor.h"
+
+namespace mooncake::io_pattern {
+namespace {
+
+// A handler that reports UNAVAILABLE_IN_CURRENT_MODE declined to act because the
+// storage primitive cannot run in this configuration. That is not a failure of
+// the plan: the policy had no way to influence it, so it must not be counted as
+// a policy failure by the caller.
+bool IsUnavailable(ErrorCode code) {
+    return code == ErrorCode::UNAVAILABLE_IN_CURRENT_MODE;
+}
+
+}  // namespace
+
+PolicyExecutionStatus TierOperationExecutor::Execute(
+    const PolicyResult& result) const {
+    PolicyExecutionStatus status;
+    const bool has_eviction_work = !result.eviction.candidates.empty() ||
+                                   result.eviction.target_bytes != 0;
+    if (eviction_ && has_eviction_work) {
+        status.eviction = eviction_(result.eviction);
+        if (IsUnavailable(status.eviction)) ++status.skipped;
+    } else if (has_eviction_work) {
+        // A missing handler is a configuration error rather than a storage
+        // limitation, so it keeps marking the execution degraded.
+        status.eviction = ErrorCode::UNAVAILABLE_IN_CURRENT_MODE;
+        status.degraded = true;
+    }
+    if (prefetch_ && !result.prefetch.candidates.empty()) {
+        status.prefetch = prefetch_(result.prefetch);
+        if (IsUnavailable(status.prefetch)) ++status.skipped;
+    } else if (!result.prefetch.candidates.empty()) {
+        status.prefetch = ErrorCode::UNAVAILABLE_IN_CURRENT_MODE;
+        status.degraded = true;
+    }
+    for (const auto& admission : result.admissions) {
+        if (admission.decision != AdmissionDecision::kAdmit) {
+            status.admissions.push_back(ErrorCode::OK);
+            continue;
+        }
+        if (!admission_) {
+            status.admissions.push_back(ErrorCode::UNAVAILABLE_IN_CURRENT_MODE);
+            status.degraded = true;
+            continue;
+        }
+        const ErrorCode code = admission_(admission);
+        if (IsUnavailable(code)) ++status.skipped;
+        status.admissions.push_back(code);
+    }
+    return status;
+}
+
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/src/master.cpp b/mooncake-store/src/master.cpp
index 8ce9aadc55..00cb663194 100644
--- a/mooncake-store/src/master.cpp
+++ b/mooncake-store/src/master.cpp
@@ -143,6 +143,31 @@ DEFINE_double(nof_eviction_ratio, mooncake::DEFAULT_NOF_EVICTION_RATIO,
 DEFINE_double(nof_eviction_high_watermark_ratio,
               mooncake::DEFAULT_NOF_EVICTION_HIGH_WATERMARK_RATIO,
               "Ratio of high watermark trigger eviction in NoF SSD");
+DEFINE_bool(io_pattern_cold_eviction, false,
+            "Enable report-driven cold-data eviction (embedded CFM component): "
+            "merged client reports may drive bounded evictions of the coldest "
+            "keys even when the memory high-watermark is not exceeded");
+DEFINE_uint64(io_pattern_cold_eviction_bytes_per_cycle, 0,
+              "Max bytes one report-driven cold-eviction pass may request "
+              "(0 disables the cold driver)");
+DEFINE_uint64(io_pattern_cold_idle_threshold_us, 0,
+              "Minimum idle_time_us for a key to be eligible for a "
+              "report-driven cold-eviction pass (0 disables the idle gate)");
+DEFINE_uint64(io_pattern_tier_down_bytes_per_cycle, 0,
+              "Max bytes one report-driven tier-down pass may copy per cycle. "
+              "The pass runs below the memory watermark and copies the coldest "
+              "objects down while keeping their MEMORY replica, so a later "
+              "reclaim can discard them safely; a cycle that reaches the "
+              "watermark evicts instead. 0 keeps the driver off, so this budget "
+              "is the only switch the driver has");
+DEFINE_uint32(io_pattern_admission_frequency_threshold, 2,
+              "Min access count for a reported key before the io_pattern "
+              "policy admits it (set 1 to admit on first sight)");
+DEFINE_double(io_pattern_admission_watermark_ratio, -1.0,
+              "Capacity watermark for io_pattern admission, as a ratio of "
+              "capacity; a negative value derives it from "
+              "eviction_high_watermark_ratio so admission stops before "
+              "eviction starts");
 // RPC server configuration parameters (new, preferred)
 // TODO: deprecate port and max_threads in the future
 DEFINE_int32(rpc_thread_num, 0,
@@ -297,6 +322,15 @@ DEFINE_int64(global_file_segment_size,
 DEFINE_string(cluster_id, mooncake::DEFAULT_CLUSTER_ID,
               "Cluster ID for the master service, used for kvcache persistence "
               "in HA mode");
+DEFINE_uint32(submaster_count, 1,
+              "Maximum number of simultaneously serving submaster in the "
+              "cluster (CVM quota coordination, first-come-first-served). "
+              "Masters ranked beyond this limit are demoted to standby.");
+DEFINE_uint32(cvm_http_port, 0,
+              "Port for the CVM external HTTP API (CvmHttpServer). 0 keeps it "
+              "disabled.");
+DEFINE_string(cvm_http_host, "0.0.0.0",
+              "Bind host for the CVM external HTTP API (CvmHttpServer).");
 
 // OpLog store configuration
 DEFINE_bool(enable_oplog, false,
@@ -460,6 +494,27 @@ void InitMasterConf(const mooncake::DefaultConfig& default_config,
     // Initialize the master service configuration from the default config
     default_config.GetBool("enable_cxl", &master_config.enable_cxl,
                            FLAGS_enable_cxl);
+    default_config.GetBool("enable_vchunk",
+                           &master_config.vchunk_config.enabled, false);
+    default_config.GetString("vchunk_etcd_endpoints",
+                             &master_config.vchunk_etcd_endpoints, "");
+    default_config.GetUInt64(
+        "vchunk_creating_timeout_ms",
+        &master_config.vchunk_config.creating_timeout_ms, 30'000);
+    default_config.GetUInt64(
+        "vchunk_releasing_timeout_ms",
+        &master_config.vchunk_config.releasing_timeout_ms, 60'000);
+    default_config.GetUInt32("vchunk_max_slice_retry",
+                             &master_config.vchunk_config.max_slice_retry, 3);
+    default_config.GetUInt32("vchunk_max_slice_count",
+                             &master_config.vchunk_config.max_slice_count,
+                             4096);
+    default_config.GetUInt64("vchunk_max_metadata_bytes",
+                             &master_config.vchunk_config.max_metadata_bytes,
+                             1024U * 1024U);
+    default_config.GetUInt32(
+        "vchunk_max_creating_objects",
+        &master_config.vchunk_config.max_creating_objects, 1024);
     default_config.GetString("cxl_path", &master_config.cxl_path,
                              FLAGS_cxl_path);
     default_config.GetUInt64("cxl_size", &master_config.cxl_size,
@@ -503,6 +558,25 @@ void InitMasterConf(const mooncake::DefaultConfig& default_config,
     default_config.GetDouble("nof_eviction_high_watermark_ratio",
                              &master_config.nof_eviction_high_watermark_ratio,
                              FLAGS_nof_eviction_high_watermark_ratio);
+    default_config.GetBool("io_pattern_cold_eviction",
+                           &master_config.io_pattern_cold_eviction,
+                           FLAGS_io_pattern_cold_eviction);
+    default_config.GetUInt64("io_pattern_cold_eviction_bytes_per_cycle",
+                             &master_config.io_pattern_cold_eviction_bytes_per_cycle,
+                             FLAGS_io_pattern_cold_eviction_bytes_per_cycle);
+    default_config.GetUInt64("io_pattern_cold_idle_threshold_us",
+                             &master_config.io_pattern_cold_idle_threshold_us,
+                             FLAGS_io_pattern_cold_idle_threshold_us);
+    default_config.GetUInt64("io_pattern_tier_down_bytes_per_cycle",
+                             &master_config.io_pattern_tier_down_bytes_per_cycle,
+                             FLAGS_io_pattern_tier_down_bytes_per_cycle);
+    default_config.GetUInt32(
+        "io_pattern_admission_frequency_threshold",
+        &master_config.io_pattern_admission_frequency_threshold,
+        FLAGS_io_pattern_admission_frequency_threshold);
+    default_config.GetDouble("io_pattern_admission_watermark_ratio",
+                             &master_config.io_pattern_admission_watermark_ratio,
+                             FLAGS_io_pattern_admission_watermark_ratio);
     default_config.GetInt64("client_live_ttl_sec",
                             &master_config.client_live_ttl_sec,
                             FLAGS_client_ttl);
@@ -867,6 +941,47 @@ void LoadConfigFromCmdline(mooncake::MasterConfig& master_config,
         master_config.nof_eviction_high_watermark_ratio =
             FLAGS_nof_eviction_high_watermark_ratio;
     }
+    if ((google::GetCommandLineFlagInfo("io_pattern_cold_eviction", &info) &&
+         !info.is_default) ||
+        !conf_set) {
+        master_config.io_pattern_cold_eviction =
+            FLAGS_io_pattern_cold_eviction;
+    }
+    if ((google::GetCommandLineFlagInfo(
+             "io_pattern_cold_eviction_bytes_per_cycle", &info) &&
+         !info.is_default) ||
+        !conf_set) {
+        master_config.io_pattern_cold_eviction_bytes_per_cycle =
+            FLAGS_io_pattern_cold_eviction_bytes_per_cycle;
+    }
+    if ((google::GetCommandLineFlagInfo("io_pattern_cold_idle_threshold_us",
+                                        &info) &&
+         !info.is_default) ||
+        !conf_set) {
+        master_config.io_pattern_cold_idle_threshold_us =
+            FLAGS_io_pattern_cold_idle_threshold_us;
+    }
+    if ((google::GetCommandLineFlagInfo("io_pattern_tier_down_bytes_per_cycle",
+                                        &info) &&
+         !info.is_default) ||
+        !conf_set) {
+        master_config.io_pattern_tier_down_bytes_per_cycle =
+            FLAGS_io_pattern_tier_down_bytes_per_cycle;
+    }
+    if ((google::GetCommandLineFlagInfo(
+             "io_pattern_admission_frequency_threshold", &info) &&
+         !info.is_default) ||
+        !conf_set) {
+        master_config.io_pattern_admission_frequency_threshold =
+            FLAGS_io_pattern_admission_frequency_threshold;
+    }
+    if ((google::GetCommandLineFlagInfo(
+             "io_pattern_admission_watermark_ratio", &info) &&
+         !info.is_default) ||
+        !conf_set) {
+        master_config.io_pattern_admission_watermark_ratio =
+            FLAGS_io_pattern_admission_watermark_ratio;
+    }
     if ((google::GetCommandLineFlagInfo("enable_ha", &info) &&
          !info.is_default) ||
         !conf_set) {
@@ -1055,6 +1170,21 @@ void LoadConfigFromCmdline(mooncake::MasterConfig& master_config,
         !conf_set) {
         master_config.cluster_id = FLAGS_cluster_id;
     }
+    if ((google::GetCommandLineFlagInfo("submaster_count", &info) &&
+         !info.is_default) ||
+        !conf_set) {
+        master_config.submaster_count = FLAGS_submaster_count;
+    }
+    if ((google::GetCommandLineFlagInfo("cvm_http_port", &info) &&
+         !info.is_default) ||
+        !conf_set) {
+        master_config.cvm_http_port = static_cast<uint16_t>(FLAGS_cvm_http_port);
+    }
+    if ((google::GetCommandLineFlagInfo("cvm_http_host", &info) &&
+         !info.is_default) ||
+        !conf_set) {
+        master_config.cvm_http_host = FLAGS_cvm_http_host;
+    }
     if ((google::GetCommandLineFlagInfo("enable_oplog", &info) &&
          !info.is_default) ||
         !conf_set) {
diff --git a/mooncake-store/src/master_client.cpp b/mooncake-store/src/master_client.cpp
index 5a266a696f..04896aa3c9 100644
--- a/mooncake-store/src/master_client.cpp
+++ b/mooncake-store/src/master_client.cpp
@@ -16,6 +16,8 @@
 #include "mutex.h"
 #include "rpc_service.h"
 #include "types.h"
+#include "etcd_helper.h"
+#include "partition/kv_hash_map.h"
 #include "utils/scoped_vlog_timer.h"
 #include "master_metric_manager.h"
 #include "version.h"
@@ -90,6 +92,35 @@ struct RpcNameTraits<&WrappedMasterService::PutRevoke> {
     static constexpr const char* value = "PutRevoke";
 };
 
+template <>
+struct RpcNameTraits<&WrappedMasterService::VChunkPutStart> {
+    static constexpr const char* value = "VChunkPutStart";
+};
+template <>
+struct RpcNameTraits<&WrappedMasterService::VChunkPutEnd> {
+    static constexpr const char* value = "VChunkPutEnd";
+};
+template <>
+struct RpcNameTraits<&WrappedMasterService::VChunkPutRevoke> {
+    static constexpr const char* value = "VChunkPutRevoke";
+};
+template <>
+struct RpcNameTraits<&WrappedMasterService::GetVChunk> {
+    static constexpr const char* value = "GetVChunk";
+};
+template <>
+struct RpcNameTraits<&WrappedMasterService::ReleaseVChunkReadLease> {
+    static constexpr const char* value = "ReleaseVChunkReadLease";
+};
+template <>
+struct RpcNameTraits<&WrappedMasterService::RemoveVChunk> {
+    static constexpr const char* value = "RemoveVChunk";
+};
+template <>
+struct RpcNameTraits<&WrappedMasterService::GetVChunkRuntimeInfo> {
+    static constexpr const char* value = "GetVChunkRuntimeInfo";
+};
+
 template <>
 struct RpcNameTraits<&WrappedMasterService::BatchPutRevoke> {
     static constexpr const char* value = "BatchPutRevoke";
@@ -454,6 +485,45 @@ tl::expected<ReturnType, ErrorCode> MasterClient::invoke_rpc(Args&&... args) {
     return rpc_result;
 }
 
+template <auto ServiceMethod, typename ReturnType, typename... Args>
+tl::expected<ReturnType, ErrorCode> MasterClient::invoke_rpc_to(
+    const std::string& address, Args&&... args) {
+    // 定向 RPC：用独立 targeted_accessor_ 按地址取 pool，不切换
+    // client_accessor_ 的"当前地址"，避免与业务请求竞态。pool 取自返回值，
+    // 不依赖 targeted_accessor_ 的当前状态，因此可被多线程并发调用。
+    auto pool = targeted_accessor_.GetOrCreateClientPool(address);
+
+    if (metrics_) {
+        metrics_->rpc_count.inc({RpcNameTraits<ServiceMethod>::value});
+    }
+
+    return async_simple::coro::syncAwait(
+        [&]() -> async_simple::coro::Lazy<tl::expected<ReturnType, ErrorCode>> {
+            auto ret = co_await pool->send_request(
+                [&](coro_io::client_reuse_hint,
+                    coro_rpc::coro_rpc_client& client) {
+                    return client.send_request<ServiceMethod>(
+                        std::forward<Args>(args)...);
+                });
+            if (!ret.has_value()) {
+                co_return tl::make_unexpected(ErrorCode::RPC_FAIL);
+            }
+            auto result = co_await std::move(ret.value());
+            if (!result) {
+                if (result.error().code == coro_rpc::errc::timed_out) {
+                    co_return tl::make_unexpected(ErrorCode::RPC_TIMEOUT);
+                }
+                co_return tl::make_unexpected(ErrorCode::RPC_FAIL);
+            }
+            if constexpr (std::is_void_v<ReturnType>) {
+                result->result();
+                co_return tl::expected<void, ErrorCode>{};
+            } else {
+                co_return std::move(result->result());
+            }
+        }());
+}
+
 template <auto ServiceMethod, typename ResultType, typename... Args>
 std::vector<tl::expected<ResultType, ErrorCode>> MasterClient::invoke_batch_rpc(
     size_t input_size, Args&&... args) {
@@ -578,11 +648,132 @@ ErrorCode MasterClient::Connect(const std::string& master_addr) {
     return ErrorCode::OK;
 }
 
+ErrorCode MasterClient::LoadRoutingFromEtcd(
+    const std::string& etcd_endpoints, const std::string& cluster_namespace) {
+    if (etcd_endpoints.empty() || cluster_namespace.empty()) {
+        LOG(ERROR) << "LoadRoutingFromEtcd requires non-empty etcd_endpoints "
+                   << "and cluster_namespace";
+        return ErrorCode::INVALID_PARAMS;
+    }
+
+    ErrorCode err = EtcdHelper::ConnectToEtcdStoreClient(etcd_endpoints);
+    if (err != ErrorCode::OK) {
+        LOG(ERROR) << "Failed to connect etcd for partition routing: " << err;
+        return err;
+    }
+
+    err = partition_router_.LoadFromEtcdSnapshot(cluster_namespace);
+    if (err != ErrorCode::OK) {
+        LOG(WARNING) << "Failed to load partition routing snapshot from etcd "
+                     << "(namespace=" << cluster_namespace << "): " << err;
+        return err;
+    }
+    {
+        std::lock_guard<std::mutex> lock(routing_config_mutex_);
+        routing_cluster_namespace_ = cluster_namespace;
+    }
+    LOG(INFO) << "Loaded partition routing from etcd: namespace="
+              << cluster_namespace << " entries=" << partition_router_.Size();
+    return ErrorCode::OK;
+}
+
+ErrorCode MasterClient::RefreshSubmasterRouting() {
+    std::string cluster_namespace;
+    {
+        std::lock_guard<std::mutex> lock(routing_config_mutex_);
+        cluster_namespace = routing_cluster_namespace_;
+    }
+    if (cluster_namespace.empty()) {
+        return ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS;
+    }
+    return partition_router_.LoadFromEtcdSnapshot(cluster_namespace);
+}
+
+std::optional<std::string> MasterClient::ResolveSubmaster(
+    const std::string& key) const {
+    const uint16_t slot = partition::KvHashMap::Compute(tenant_id_, key);
+    auto submaster = partition_router_.ResolveSubmaster(slot);
+    if (submaster) {
+        LOG(INFO) << "ResolveSubmaster hit: tenant=" << tenant_id_.value()
+                  << " key=" << key << " slot=" << slot
+                  << " submaster=" << *submaster;
+    } else {
+        LOG(WARNING) << "ResolveSubmaster miss: tenant=" << tenant_id_.value()
+                     << " key=" << key << " slot=" << slot
+                     << " (routing not loaded or slot has no owner)";
+    }
+    return submaster;
+}
+
+void MasterClient::SwitchToSubmasterByAddress(const std::string& address) {
+    const std::string old_address = client_accessor_.GetAddress();
+    client_accessor_.GetOrCreateClientPool(address);
+    if (old_address != address) {
+        LOG(INFO) << "SwitchToSubmasterByAddress: [" << old_address << "] -> ["
+                  << address << "]";
+    }
+}
+
+ErrorCode MasterClient::SwitchToSubmaster(const std::string& tenant_id,
+                                          const std::string& key) {
+    // Routing not loaded (single-master mode): keep the current connection so
+    // existing behavior is preserved. Check Size() before ResolveSubmaster to
+    // avoid its per-miss WARNING log firing on every single-key request.
+    if (partition_router_.Size() == 0) {
+        return ErrorCode::OK;
+    }
+
+    const TenantId tenant(tenant_id);
+    const uint16_t slot = partition::KvHashMap::Compute(tenant, key);
+    auto submaster = partition_router_.ResolveSubmaster(slot);
+    if (!submaster) {
+        LOG(WARNING) << "SwitchToSubmaster miss: tenant=" << tenant_id
+                     << " key=" << key << " slot=" << slot
+                     << " (slot has no owner in routing table)";
+        return ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS;
+    }
+
+    SwitchToSubmasterByAddress(*submaster);
+    LOG(INFO) << "SwitchToSubmaster: tenant=" << tenant_id << " key=" << key
+              << " slot=" << slot << " -> submaster=" << *submaster;
+    return ErrorCode::OK;
+}
+
+std::map<std::string, std::vector<size_t>> MasterClient::GroupKeysBySubmaster(
+    const std::vector<std::string>& keys, const std::string& tenant_id) {
+    std::map<std::string, std::vector<size_t>> groups;
+    const TenantId tenant(tenant_id);
+    for (size_t i = 0; i < keys.size(); ++i) {
+        const uint16_t slot = partition::KvHashMap::Compute(tenant, keys[i]);
+        auto submaster = partition_router_.ResolveSubmaster(slot);
+        groups[submaster.value_or("")].push_back(i);
+    }
+
+    std::string group_desc;
+    for (const auto& [submaster, indices] : groups) {
+        if (!group_desc.empty()) {
+            group_desc += ", ";
+        }
+        group_desc += (submaster.empty() ? std::string("<none>") : submaster);
+        group_desc += ":" + std::to_string(indices.size());
+    }
+    LOG(INFO) << "GroupKeysBySubmaster: tenant=" << tenant_id
+              << " total_keys=" << keys.size() << " groups=" << groups.size()
+              << " [" << group_desc << "]";
+    return groups;
+}
+
 tl::expected<bool, ErrorCode> MasterClient::ExistKey(
     const std::string& object_key) {
     ScopedVLogTimer timer(1, "MasterClient::ExistKey");
     timer.LogRequest("object_key=", object_key);
 
+    ErrorCode switch_err = SwitchToSubmaster(tenant_id_.value(), object_key);
+    if (switch_err != ErrorCode::OK) {
+        timer.LogResponse("error_code=", switch_err);
+        return tl::make_unexpected(switch_err);
+    }
+
     auto result = invoke_rpc<&WrappedMasterService::ExistKey, bool>(
         object_key, tenant_id_.value());
     timer.LogResponseExpected(result);
@@ -594,10 +785,43 @@ std::vector<tl::expected<bool, ErrorCode>> MasterClient::BatchExistKey(
     ScopedVLogTimer timer(1, "MasterClient::BatchExistKey");
     timer.LogRequest("keys_count=", object_keys.size());
 
-    auto result = invoke_batch_rpc<&WrappedMasterService::BatchExistKey, bool>(
-        object_keys.size(), object_keys, tenant_id_.value());
-    timer.LogResponse("result=", result.size(), " keys");
-    return result;
+    // Single-master mode (routing not loaded): use the original batch path.
+    if (partition_router_.Size() == 0) {
+        auto result =
+            invoke_batch_rpc<&WrappedMasterService::BatchExistKey, bool>(
+                object_keys.size(), object_keys, tenant_id_.value());
+        timer.LogResponse("result=", result.size(), " keys");
+        return result;
+    }
+
+    std::vector<tl::expected<bool, ErrorCode>> results(
+        object_keys.size(),
+        tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS));
+
+    auto groups = GroupKeysBySubmaster(object_keys, tenant_id_.value());
+    for (auto& [submaster, indices] : groups) {
+        if (submaster.empty()) {
+            LOG(WARNING) << "BatchExistKey: " << indices.size()
+                         << " key(s) have no submaster, marked unavailable";
+            continue;
+        }
+        SwitchToSubmasterByAddress(submaster);
+
+        std::vector<std::string> group_keys;
+        group_keys.reserve(indices.size());
+        for (size_t idx : indices) {
+            group_keys.push_back(object_keys[idx]);
+        }
+
+        auto group_result =
+            invoke_batch_rpc<&WrappedMasterService::BatchExistKey, bool>(
+                group_keys.size(), group_keys, tenant_id_.value());
+        for (size_t j = 0; j < indices.size(); ++j) {
+            results[indices[j]] = std::move(group_result[j]);
+        }
+    }
+    timer.LogResponse("result=", results.size(), " keys");
+    return results;
 }
 
 tl::expected<MasterMetricManager::CacheHitStatDict, ErrorCode>
@@ -662,6 +886,12 @@ tl::expected<GetReplicaListResponse, ErrorCode> MasterClient::GetReplicaList(
     ScopedVLogTimer timer(1, "MasterClient::GetReplicaList");
     timer.LogRequest("object_key=", object_key, ", tenant_id=", tenant_id);
 
+    ErrorCode switch_err = SwitchToSubmaster(tenant_id, object_key);
+    if (switch_err != ErrorCode::OK) {
+        timer.LogResponse("error_code=", switch_err);
+        return tl::make_unexpected(switch_err);
+    }
+
     const uint64_t trace_id = mooncake::logging::CurrentTraceId();
     auto result = invoke_rpc<&WrappedMasterService::GetReplicaList,
                              GetReplicaListResponse>(object_key, tenant_id,
@@ -682,12 +912,48 @@ MasterClient::BatchGetReplicaList(const std::vector<std::string>& object_keys,
     timer.LogRequest("keys_count=", object_keys.size(),
                      ", tenant_id=", tenant_id);
 
+    // Single-master mode (routing not loaded): use the original batch path.
+    if (partition_router_.Size() == 0) {
+        const uint64_t trace_id = mooncake::logging::CurrentTraceId();
+        auto result =
+            invoke_batch_rpc<&WrappedMasterService::BatchGetReplicaList,
+                             GetReplicaListResponse>(
+                object_keys.size(), object_keys, tenant_id, trace_id,
+                client_id_);
+        timer.LogResponse("result=", result.size(), " operations");
+        return result;
+    }
+
+    std::vector<tl::expected<GetReplicaListResponse, ErrorCode>> results(
+        object_keys.size(),
+        tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS));
+
     const uint64_t trace_id = mooncake::logging::CurrentTraceId();
-    auto result = invoke_batch_rpc<&WrappedMasterService::BatchGetReplicaList,
-                                   GetReplicaListResponse>(
-        object_keys.size(), object_keys, tenant_id, trace_id, client_id_);
-    timer.LogResponse("result=", result.size(), " operations");
-    return result;
+    auto groups = GroupKeysBySubmaster(object_keys, tenant_id);
+    for (auto& [submaster, indices] : groups) {
+        if (submaster.empty()) {
+            LOG(WARNING) << "BatchGetReplicaList: " << indices.size()
+                         << " key(s) have no submaster, marked unavailable";
+            continue;
+        }
+        SwitchToSubmasterByAddress(submaster);
+
+        std::vector<std::string> group_keys;
+        group_keys.reserve(indices.size());
+        for (size_t idx : indices) {
+            group_keys.push_back(object_keys[idx]);
+        }
+
+        auto group_result =
+            invoke_batch_rpc<&WrappedMasterService::BatchGetReplicaList,
+                             GetReplicaListResponse>(
+                group_keys.size(), group_keys, tenant_id, trace_id, client_id_);
+        for (size_t j = 0; j < indices.size(); ++j) {
+            results[indices[j]] = std::move(group_result[j]);
+        }
+    }
+    timer.LogResponse("result=", results.size(), " operations");
+    return results;
 }
 
 tl::expected<std::vector<Replica::Descriptor>, ErrorCode>
@@ -697,6 +963,12 @@ MasterClient::PutStart(const std::string& key,
     ScopedVLogTimer timer(1, "MasterClient::PutStart");
     timer.LogRequest("key=", key, ", slice_count=", slice_lengths.size());
 
+    ErrorCode switch_err = SwitchToSubmaster(tenant_id_.value(), key);
+    if (switch_err != ErrorCode::OK) {
+        timer.LogResponse("error_code=", switch_err);
+        return tl::make_unexpected(switch_err);
+    }
+
     uint64_t total_slice_length = 0;
     for (const auto& slice_length : slice_lengths) {
         total_slice_length += slice_length;
@@ -720,22 +992,60 @@ MasterClient::BatchPutStart(
 
     std::vector<uint64_t> total_slice_lengths;
     total_slice_lengths.reserve(slice_lengths.size());
-    for (const auto& slice_lengths : slice_lengths) {
+    for (const auto& per_key_lengths : slice_lengths) {
         uint64_t total_slice_length = 0;
-        for (const auto& slice_length : slice_lengths) {
+        for (const auto& slice_length : per_key_lengths) {
             total_slice_length += slice_length;
         }
         total_slice_lengths.emplace_back(total_slice_length);
     }
 
     const uint64_t trace_id = mooncake::logging::CurrentTraceId();
-    auto result = invoke_batch_rpc<&WrappedMasterService::BatchPutStart,
-                                   std::vector<Replica::Descriptor>>(
-        keys.size(), client_id_, keys, total_slice_lengths, config,
-        tenant_id_.value(),
-        trace_id);
-    timer.LogResponse("result=", result.size(), " operations");
-    return result;
+
+    // Single-master mode (routing not loaded): use the original batch path.
+    if (partition_router_.Size() == 0) {
+        auto result =
+            invoke_batch_rpc<&WrappedMasterService::BatchPutStart,
+                             std::vector<Replica::Descriptor>>(
+                keys.size(), client_id_, keys, total_slice_lengths, config,
+                tenant_id_.value(), trace_id);
+        timer.LogResponse("result=", result.size(), " operations");
+        return result;
+    }
+
+    std::vector<tl::expected<std::vector<Replica::Descriptor>, ErrorCode>>
+        results(keys.size(),
+                tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS));
+
+    auto groups = GroupKeysBySubmaster(keys, tenant_id_.value());
+    for (auto& [submaster, indices] : groups) {
+        if (submaster.empty()) {
+            LOG(WARNING) << "BatchPutStart: " << indices.size()
+                         << " key(s) have no submaster, marked unavailable";
+            continue;
+        }
+        SwitchToSubmasterByAddress(submaster);
+
+        std::vector<std::string> group_keys;
+        std::vector<uint64_t> group_total_slice_lengths;
+        group_keys.reserve(indices.size());
+        group_total_slice_lengths.reserve(indices.size());
+        for (size_t idx : indices) {
+            group_keys.push_back(keys[idx]);
+            group_total_slice_lengths.push_back(total_slice_lengths[idx]);
+        }
+
+        auto group_result = invoke_batch_rpc<
+            &WrappedMasterService::BatchPutStart,
+            std::vector<Replica::Descriptor>>(
+            group_keys.size(), client_id_, group_keys,
+            group_total_slice_lengths, config, tenant_id_.value(), trace_id);
+        for (size_t j = 0; j < indices.size(); ++j) {
+            results[indices[j]] = std::move(group_result[j]);
+        }
+    }
+    timer.LogResponse("result=", results.size(), " operations");
+    return results;
 }
 
 tl::expected<void, ErrorCode> MasterClient::PutEnd(
@@ -743,6 +1053,13 @@ tl::expected<void, ErrorCode> MasterClient::PutEnd(
     ScopedVLogTimer timer(1, "MasterClient::PutEnd");
     timer.LogRequest("key=", object_meta.key);
 
+    ErrorCode switch_err =
+        SwitchToSubmaster(tenant_id_.value(), object_meta.key);
+    if (switch_err != ErrorCode::OK) {
+        timer.LogResponse("error_code=", switch_err);
+        return tl::make_unexpected(switch_err);
+    }
+
     const uint64_t trace_id = mooncake::logging::CurrentTraceId();
     auto result = invoke_rpc<&WrappedMasterService::PutEnd, void>(
         client_id_, object_meta, replica_type, tenant_id_.value(), trace_id);
@@ -756,11 +1073,52 @@ std::vector<tl::expected<void, ErrorCode>> MasterClient::BatchPutEnd(
     timer.LogRequest("keys_count=", object_metas.size());
 
     const uint64_t trace_id = mooncake::logging::CurrentTraceId();
-    auto result = invoke_batch_rpc<&WrappedMasterService::BatchPutEnd, void>(
-        object_metas.size(), client_id_, object_metas, replica_type,
-        tenant_id_.value(), trace_id);
-    timer.LogResponse("result=", result.size(), " operations");
-    return result;
+
+    // Single-master mode (routing not loaded): use the original batch path.
+    if (partition_router_.Size() == 0) {
+        auto result =
+            invoke_batch_rpc<&WrappedMasterService::BatchPutEnd, void>(
+                object_metas.size(), client_id_, object_metas, replica_type,
+                tenant_id_.value(), trace_id);
+        timer.LogResponse("result=", result.size(), " operations");
+        return result;
+    }
+
+    std::vector<tl::expected<void, ErrorCode>> results(
+        object_metas.size(),
+        tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS));
+
+    std::vector<std::string> keys;
+    keys.reserve(object_metas.size());
+    for (const auto& meta : object_metas) {
+        keys.push_back(meta.key);
+    }
+
+    auto groups = GroupKeysBySubmaster(keys, tenant_id_.value());
+    for (auto& [submaster, indices] : groups) {
+        if (submaster.empty()) {
+            LOG(WARNING) << "BatchPutEnd: " << indices.size()
+                         << " key(s) have no submaster, marked unavailable";
+            continue;
+        }
+        SwitchToSubmasterByAddress(submaster);
+
+        std::vector<ObjectMeta> group_object_metas;
+        group_object_metas.reserve(indices.size());
+        for (size_t idx : indices) {
+            group_object_metas.push_back(object_metas[idx]);
+        }
+
+        auto group_result =
+            invoke_batch_rpc<&WrappedMasterService::BatchPutEnd, void>(
+                group_object_metas.size(), client_id_, group_object_metas,
+                replica_type, tenant_id_.value(), trace_id);
+        for (size_t j = 0; j < indices.size(); ++j) {
+            results[indices[j]] = std::move(group_result[j]);
+        }
+    }
+    timer.LogResponse("result=", results.size(), " operations");
+    return results;
 }
 
 tl::expected<void, ErrorCode> MasterClient::PutRevoke(
@@ -768,21 +1126,174 @@ tl::expected<void, ErrorCode> MasterClient::PutRevoke(
     ScopedVLogTimer timer(1, "MasterClient::PutRevoke");
     timer.LogRequest("key=", key);
 
+    ErrorCode switch_err = SwitchToSubmaster(tenant_id_.value(), key);
+    if (switch_err != ErrorCode::OK) {
+        timer.LogResponse("error_code=", switch_err);
+        return tl::make_unexpected(switch_err);
+    }
+
     auto result = invoke_rpc<&WrappedMasterService::PutRevoke, void>(
         client_id_, key, replica_type, tenant_id_.value());
     timer.LogResponseExpected(result);
     return result;
 }
 
+tl::expected<VChunkMetadataRecord, ErrorCode> MasterClient::VChunkPutStart(
+    const std::string& tenant_id, const std::string& key, uint64_t total_size,
+    int64_t now_ms) {
+    std::lock_guard<std::mutex> routed_lock(vchunk_routed_rpc_mutex_);
+    const auto switch_err = SwitchToSubmaster(tenant_id, key);
+    if (switch_err != ErrorCode::OK) {
+        return tl::make_unexpected(switch_err);
+    }
+    auto result = invoke_rpc<&WrappedMasterService::VChunkPutStart,
+                             VChunkMetadataRecord>(tenant_id, key, total_size,
+                                                   now_ms);
+    if (!result && result.error() == ErrorCode::SLOT_NOT_OWNED &&
+        RefreshSubmasterRouting() == ErrorCode::OK &&
+        SwitchToSubmaster(tenant_id, key) == ErrorCode::OK) {
+        result = invoke_rpc<&WrappedMasterService::VChunkPutStart,
+                            VChunkMetadataRecord>(tenant_id, key, total_size,
+                                                  now_ms);
+    }
+    return result;
+}
+
+tl::expected<void, ErrorCode> MasterClient::VChunkPutEnd(
+    const std::string& tenant_id, const std::string& key,
+    const std::string& vchunk_id, int64_t now_ms) {
+    std::lock_guard<std::mutex> routed_lock(vchunk_routed_rpc_mutex_);
+    const auto switch_err = SwitchToSubmaster(tenant_id, key);
+    if (switch_err != ErrorCode::OK) {
+        return tl::make_unexpected(switch_err);
+    }
+    auto result = invoke_rpc<&WrappedMasterService::VChunkPutEnd, void>(
+        tenant_id, key, vchunk_id, now_ms);
+    if (!result && result.error() == ErrorCode::SLOT_NOT_OWNED &&
+        RefreshSubmasterRouting() == ErrorCode::OK &&
+        SwitchToSubmaster(tenant_id, key) == ErrorCode::OK) {
+        result = invoke_rpc<&WrappedMasterService::VChunkPutEnd, void>(
+            tenant_id, key, vchunk_id, now_ms);
+    }
+    return result;
+}
+
+tl::expected<void, ErrorCode> MasterClient::VChunkPutRevoke(
+    const std::string& tenant_id, const std::string& key,
+    const std::string& vchunk_id) {
+    std::lock_guard<std::mutex> routed_lock(vchunk_routed_rpc_mutex_);
+    const auto switch_err = SwitchToSubmaster(tenant_id, key);
+    if (switch_err != ErrorCode::OK) {
+        return tl::make_unexpected(switch_err);
+    }
+    auto result = invoke_rpc<&WrappedMasterService::VChunkPutRevoke, void>(
+        tenant_id, key, vchunk_id);
+    if (!result && result.error() == ErrorCode::SLOT_NOT_OWNED &&
+        RefreshSubmasterRouting() == ErrorCode::OK &&
+        SwitchToSubmaster(tenant_id, key) == ErrorCode::OK) {
+        result = invoke_rpc<&WrappedMasterService::VChunkPutRevoke, void>(
+            tenant_id, key, vchunk_id);
+    }
+    return result;
+}
+
+tl::expected<VChunkReadLease, ErrorCode> MasterClient::GetVChunk(
+    const std::string& tenant_id, const std::string& key) {
+    std::lock_guard<std::mutex> routed_lock(vchunk_routed_rpc_mutex_);
+    const auto switch_err = SwitchToSubmaster(tenant_id, key);
+    if (switch_err != ErrorCode::OK) {
+        return tl::make_unexpected(switch_err);
+    }
+    auto result = invoke_rpc<&WrappedMasterService::GetVChunk,
+                             VChunkReadLease>(tenant_id, key);
+    if (!result && result.error() == ErrorCode::SLOT_NOT_OWNED &&
+        RefreshSubmasterRouting() == ErrorCode::OK &&
+        SwitchToSubmaster(tenant_id, key) == ErrorCode::OK) {
+        result = invoke_rpc<&WrappedMasterService::GetVChunk,
+                            VChunkReadLease>(tenant_id, key);
+    }
+    return result;
+}
+
+tl::expected<void, ErrorCode> MasterClient::ReleaseVChunkReadLease(
+    const std::string& tenant_id, const std::string& key,
+    const std::string& lease_id) {
+    std::lock_guard<std::mutex> routed_lock(vchunk_routed_rpc_mutex_);
+    const auto switch_err = SwitchToSubmaster(tenant_id, key);
+    if (switch_err != ErrorCode::OK) {
+        return tl::make_unexpected(switch_err);
+    }
+    return invoke_rpc<&WrappedMasterService::ReleaseVChunkReadLease, void>(
+        lease_id);
+}
+
+tl::expected<void, ErrorCode> MasterClient::RemoveVChunk(
+    const std::string& tenant_id, const std::string& key, int64_t now_ms) {
+    std::lock_guard<std::mutex> routed_lock(vchunk_routed_rpc_mutex_);
+    const auto switch_err = SwitchToSubmaster(tenant_id, key);
+    if (switch_err != ErrorCode::OK) {
+        return tl::make_unexpected(switch_err);
+    }
+    auto result = invoke_rpc<&WrappedMasterService::RemoveVChunk, void>(
+        tenant_id, key, now_ms);
+    if (!result && result.error() == ErrorCode::SLOT_NOT_OWNED &&
+        RefreshSubmasterRouting() == ErrorCode::OK &&
+        SwitchToSubmaster(tenant_id, key) == ErrorCode::OK) {
+        result = invoke_rpc<&WrappedMasterService::RemoveVChunk, void>(
+            tenant_id, key, now_ms);
+    }
+    return result;
+}
+
+tl::expected<VChunkRuntimeInfo, ErrorCode> MasterClient::GetVChunkRuntimeInfo() {
+    return invoke_rpc<&WrappedMasterService::GetVChunkRuntimeInfo,
+                      VChunkRuntimeInfo>();
+}
+
 std::vector<tl::expected<void, ErrorCode>> MasterClient::BatchPutRevoke(
     const std::vector<std::string>& keys, ReplicaType replica_type) {
     ScopedVLogTimer timer(1, "MasterClient::BatchPutRevoke");
     timer.LogRequest("keys_count=", keys.size());
 
-    auto result = invoke_batch_rpc<&WrappedMasterService::BatchPutRevoke, void>(
-        keys.size(), client_id_, keys, replica_type, tenant_id_.value());
-    timer.LogResponse("result=", result.size(), " operations");
-    return result;
+    // Single-master mode (routing not loaded): use the original batch path.
+    if (partition_router_.Size() == 0) {
+        auto result =
+            invoke_batch_rpc<&WrappedMasterService::BatchPutRevoke, void>(
+                keys.size(), client_id_, keys, replica_type,
+                tenant_id_.value());
+        timer.LogResponse("result=", result.size(), " operations");
+        return result;
+    }
+
+    std::vector<tl::expected<void, ErrorCode>> results(
+        keys.size(),
+        tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS));
+
+    auto groups = GroupKeysBySubmaster(keys, tenant_id_.value());
+    for (auto& [submaster, indices] : groups) {
+        if (submaster.empty()) {
+            LOG(WARNING) << "BatchPutRevoke: " << indices.size()
+                         << " key(s) have no submaster, marked unavailable";
+            continue;
+        }
+        SwitchToSubmasterByAddress(submaster);
+
+        std::vector<std::string> group_keys;
+        group_keys.reserve(indices.size());
+        for (size_t idx : indices) {
+            group_keys.push_back(keys[idx]);
+        }
+
+        auto group_result =
+            invoke_batch_rpc<&WrappedMasterService::BatchPutRevoke, void>(
+                group_keys.size(), client_id_, group_keys, replica_type,
+                tenant_id_.value());
+        for (size_t j = 0; j < indices.size(); ++j) {
+            results[indices[j]] = std::move(group_result[j]);
+        }
+    }
+    timer.LogResponse("result=", results.size(), " operations");
+    return results;
 }
 
 tl::expected<std::vector<Replica::Descriptor>, ErrorCode>
@@ -792,6 +1303,12 @@ MasterClient::UpsertStart(const std::string& key,
     ScopedVLogTimer timer(1, "MasterClient::UpsertStart");
     timer.LogRequest("key=", key, ", slice_count=", slice_lengths.size());
 
+    ErrorCode switch_err = SwitchToSubmaster(tenant_id_.value(), key);
+    if (switch_err != ErrorCode::OK) {
+        timer.LogResponse("error_code=", switch_err);
+        return tl::make_unexpected(switch_err);
+    }
+
     uint64_t total_slice_length = 0;
     for (const auto& slice_length : slice_lengths) {
         total_slice_length += slice_length;
@@ -822,12 +1339,50 @@ MasterClient::BatchUpsertStart(
         total_slice_lengths.emplace_back(total);
     }
 
-    auto result = invoke_batch_rpc<&WrappedMasterService::BatchUpsertStart,
-                                   std::vector<Replica::Descriptor>>(
-        keys.size(), client_id_, keys, total_slice_lengths, config,
-        tenant_id_.value());
-    timer.LogResponse("result=", result.size(), " operations");
-    return result;
+    // Single-master mode (routing not loaded): use the original batch path.
+    if (partition_router_.Size() == 0) {
+        auto result =
+            invoke_batch_rpc<&WrappedMasterService::BatchUpsertStart,
+                             std::vector<Replica::Descriptor>>(
+                keys.size(), client_id_, keys, total_slice_lengths, config,
+                tenant_id_.value());
+        timer.LogResponse("result=", result.size(), " operations");
+        return result;
+    }
+
+    std::vector<tl::expected<std::vector<Replica::Descriptor>, ErrorCode>>
+        results(keys.size(),
+                tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS));
+
+    auto groups = GroupKeysBySubmaster(keys, tenant_id_.value());
+    for (auto& [submaster, indices] : groups) {
+        if (submaster.empty()) {
+            LOG(WARNING) << "BatchUpsertStart: " << indices.size()
+                         << " key(s) have no submaster, marked unavailable";
+            continue;
+        }
+        SwitchToSubmasterByAddress(submaster);
+
+        std::vector<std::string> group_keys;
+        std::vector<uint64_t> group_total_slice_lengths;
+        group_keys.reserve(indices.size());
+        group_total_slice_lengths.reserve(indices.size());
+        for (size_t idx : indices) {
+            group_keys.push_back(keys[idx]);
+            group_total_slice_lengths.push_back(total_slice_lengths[idx]);
+        }
+
+        auto group_result = invoke_batch_rpc<
+            &WrappedMasterService::BatchUpsertStart,
+            std::vector<Replica::Descriptor>>(
+            group_keys.size(), client_id_, group_keys,
+            group_total_slice_lengths, config, tenant_id_.value());
+        for (size_t j = 0; j < indices.size(); ++j) {
+            results[indices[j]] = std::move(group_result[j]);
+        }
+    }
+    timer.LogResponse("result=", results.size(), " operations");
+    return results;
 }
 
 tl::expected<void, ErrorCode> MasterClient::UpsertEnd(
@@ -835,6 +1390,13 @@ tl::expected<void, ErrorCode> MasterClient::UpsertEnd(
     ScopedVLogTimer timer(1, "MasterClient::UpsertEnd");
     timer.LogRequest("key=", object_meta.key);
 
+    ErrorCode switch_err =
+        SwitchToSubmaster(tenant_id_.value(), object_meta.key);
+    if (switch_err != ErrorCode::OK) {
+        timer.LogResponse("error_code=", switch_err);
+        return tl::make_unexpected(switch_err);
+    }
+
     auto result = invoke_rpc<&WrappedMasterService::UpsertEnd, void>(
         client_id_, object_meta, replica_type, tenant_id_.value());
     timer.LogResponseExpected(result);
@@ -846,10 +1408,51 @@ std::vector<tl::expected<void, ErrorCode>> MasterClient::BatchUpsertEnd(
     ScopedVLogTimer timer(1, "MasterClient::BatchUpsertEnd");
     timer.LogRequest("keys_count=", object_metas.size());
 
-    auto result = invoke_batch_rpc<&WrappedMasterService::BatchUpsertEnd, void>(
-        object_metas.size(), client_id_, object_metas, tenant_id_.value());
-    timer.LogResponse("result=", result.size(), " operations");
-    return result;
+    // Single-master mode (routing not loaded): use the original batch path.
+    if (partition_router_.Size() == 0) {
+        auto result =
+            invoke_batch_rpc<&WrappedMasterService::BatchUpsertEnd, void>(
+                object_metas.size(), client_id_, object_metas,
+                tenant_id_.value());
+        timer.LogResponse("result=", result.size(), " operations");
+        return result;
+    }
+
+    std::vector<tl::expected<void, ErrorCode>> results(
+        object_metas.size(),
+        tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS));
+
+    std::vector<std::string> keys;
+    keys.reserve(object_metas.size());
+    for (const auto& meta : object_metas) {
+        keys.push_back(meta.key);
+    }
+
+    auto groups = GroupKeysBySubmaster(keys, tenant_id_.value());
+    for (auto& [submaster, indices] : groups) {
+        if (submaster.empty()) {
+            LOG(WARNING) << "BatchUpsertEnd: " << indices.size()
+                         << " key(s) have no submaster, marked unavailable";
+            continue;
+        }
+        SwitchToSubmasterByAddress(submaster);
+
+        std::vector<ObjectMeta> group_object_metas;
+        group_object_metas.reserve(indices.size());
+        for (size_t idx : indices) {
+            group_object_metas.push_back(object_metas[idx]);
+        }
+
+        auto group_result =
+            invoke_batch_rpc<&WrappedMasterService::BatchUpsertEnd, void>(
+                group_object_metas.size(), client_id_, group_object_metas,
+                tenant_id_.value());
+        for (size_t j = 0; j < indices.size(); ++j) {
+            results[indices[j]] = std::move(group_result[j]);
+        }
+    }
+    timer.LogResponse("result=", results.size(), " operations");
+    return results;
 }
 
 tl::expected<void, ErrorCode> MasterClient::UpsertRevoke(
@@ -857,6 +1460,12 @@ tl::expected<void, ErrorCode> MasterClient::UpsertRevoke(
     ScopedVLogTimer timer(1, "MasterClient::UpsertRevoke");
     timer.LogRequest("key=", key);
 
+    ErrorCode switch_err = SwitchToSubmaster(tenant_id_.value(), key);
+    if (switch_err != ErrorCode::OK) {
+        timer.LogResponse("error_code=", switch_err);
+        return tl::make_unexpected(switch_err);
+    }
+
     auto result = invoke_rpc<&WrappedMasterService::UpsertRevoke, void>(
         client_id_, key, replica_type, tenant_id_.value());
     timer.LogResponseExpected(result);
@@ -868,11 +1477,43 @@ std::vector<tl::expected<void, ErrorCode>> MasterClient::BatchUpsertRevoke(
     ScopedVLogTimer timer(1, "MasterClient::BatchUpsertRevoke");
     timer.LogRequest("keys_count=", keys.size());
 
-    auto result =
-        invoke_batch_rpc<&WrappedMasterService::BatchUpsertRevoke, void>(
-            keys.size(), client_id_, keys, tenant_id_.value());
-    timer.LogResponse("result=", result.size(), " operations");
-    return result;
+    // Single-master mode (routing not loaded): use the original batch path.
+    if (partition_router_.Size() == 0) {
+        auto result =
+            invoke_batch_rpc<&WrappedMasterService::BatchUpsertRevoke, void>(
+                keys.size(), client_id_, keys, tenant_id_.value());
+        timer.LogResponse("result=", result.size(), " operations");
+        return result;
+    }
+
+    std::vector<tl::expected<void, ErrorCode>> results(
+        keys.size(),
+        tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS));
+
+    auto groups = GroupKeysBySubmaster(keys, tenant_id_.value());
+    for (auto& [submaster, indices] : groups) {
+        if (submaster.empty()) {
+            LOG(WARNING) << "BatchUpsertRevoke: " << indices.size()
+                         << " key(s) have no submaster, marked unavailable";
+            continue;
+        }
+        SwitchToSubmasterByAddress(submaster);
+
+        std::vector<std::string> group_keys;
+        group_keys.reserve(indices.size());
+        for (size_t idx : indices) {
+            group_keys.push_back(keys[idx]);
+        }
+
+        auto group_result =
+            invoke_batch_rpc<&WrappedMasterService::BatchUpsertRevoke, void>(
+                group_keys.size(), client_id_, group_keys, tenant_id_.value());
+        for (size_t j = 0; j < indices.size(); ++j) {
+            results[indices[j]] = std::move(group_result[j]);
+        }
+    }
+    timer.LogResponse("result=", results.size(), " operations");
+    return results;
 }
 
 tl::expected<void, ErrorCode> MasterClient::Remove(const std::string& key,
@@ -880,6 +1521,12 @@ tl::expected<void, ErrorCode> MasterClient::Remove(const std::string& key,
     ScopedVLogTimer timer(1, "MasterClient::Remove");
     timer.LogRequest("key=", key, ", force=", force);
 
+    ErrorCode switch_err = SwitchToSubmaster(tenant_id_.value(), key);
+    if (switch_err != ErrorCode::OK) {
+        timer.LogResponse("error_code=", switch_err);
+        return tl::make_unexpected(switch_err);
+    }
+
     auto result = invoke_rpc<&WrappedMasterService::Remove, void>(
         key, force, tenant_id_.value());
     timer.LogResponseExpected(result);
@@ -912,10 +1559,42 @@ std::vector<tl::expected<void, ErrorCode>> MasterClient::BatchRemove(
     ScopedVLogTimer timer(1, "MasterClient::BatchRemove");
     timer.LogRequest("keys_count=", keys.size(), ", force=", force);
 
-    auto result = invoke_batch_rpc<&WrappedMasterService::BatchRemove, void>(
-        keys.size(), keys, force, tenant_id_.value());
-    timer.LogResponse("result=", result.size(), " operations");
-    return result;
+    // Single-master mode (routing not loaded): use the original batch path.
+    if (partition_router_.Size() == 0) {
+        auto result = invoke_batch_rpc<&WrappedMasterService::BatchRemove, void>(
+            keys.size(), keys, force, tenant_id_.value());
+        timer.LogResponse("result=", result.size(), " operations");
+        return result;
+    }
+
+    std::vector<tl::expected<void, ErrorCode>> results(
+        keys.size(),
+        tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS));
+
+    auto groups = GroupKeysBySubmaster(keys, tenant_id_.value());
+    for (auto& [submaster, indices] : groups) {
+        if (submaster.empty()) {
+            LOG(WARNING) << "BatchRemove: " << indices.size()
+                         << " key(s) have no submaster, marked unavailable";
+            continue;
+        }
+        SwitchToSubmasterByAddress(submaster);
+
+        std::vector<std::string> group_keys;
+        group_keys.reserve(indices.size());
+        for (size_t idx : indices) {
+            group_keys.push_back(keys[idx]);
+        }
+
+        auto group_result =
+            invoke_batch_rpc<&WrappedMasterService::BatchRemove, void>(
+                group_keys.size(), group_keys, force, tenant_id_.value());
+        for (size_t j = 0; j < indices.size(); ++j) {
+            results[indices[j]] = std::move(group_result[j]);
+        }
+    }
+    timer.LogResponse("result=", results.size(), " operations");
+    return results;
 }
 
 tl::expected<void, ErrorCode> MasterClient::MountSegment(
@@ -931,6 +1610,18 @@ tl::expected<void, ErrorCode> MasterClient::MountSegment(
     return result;
 }
 
+tl::expected<void, ErrorCode> MasterClient::MountSegmentTo(
+    const std::string& address, const Segment& segment) {
+    ScopedVLogTimer timer(1, "MasterClient::MountSegmentTo");
+    timer.LogRequest("address=", address, ", id=", segment.id,
+                     ", client_id=", client_id_);
+
+    auto result = invoke_rpc_to<&WrappedMasterService::MountSegment, void>(
+        address, segment, client_id_);
+    timer.LogResponseExpected(result);
+    return result;
+}
+
 tl::expected<void, ErrorCode> MasterClient::MountNoFSegment(
     const NoFSegment& segment) {
     ScopedVLogTimer timer(1, "MasterClient::MountNofSegment");
@@ -979,6 +1670,18 @@ tl::expected<void, ErrorCode> MasterClient::UnmountSegment(
     return result;
 }
 
+tl::expected<void, ErrorCode> MasterClient::UnmountSegmentTo(
+    const std::string& address, const UUID& segment_id) {
+    ScopedVLogTimer timer(1, "MasterClient::UnmountSegmentTo");
+    timer.LogRequest("address=", address, ", segment_id=", segment_id,
+                     ", client_id=", client_id_);
+
+    auto result = invoke_rpc_to<&WrappedMasterService::UnmountSegment, void>(
+        address, segment_id, client_id_);
+    timer.LogResponseExpected(result);
+    return result;
+}
+
 tl::expected<void, ErrorCode> MasterClient::GracefulUnmountSegment(
     const UUID& segment_id, uint64_t grace_period_ms) {
     ScopedVLogTimer timer(1, "MasterClient::GracefulUnmountSegment");
@@ -992,6 +1695,21 @@ tl::expected<void, ErrorCode> MasterClient::GracefulUnmountSegment(
     return result;
 }
 
+tl::expected<void, ErrorCode> MasterClient::GracefulUnmountSegmentTo(
+    const std::string& address, const UUID& segment_id,
+    uint64_t grace_period_ms) {
+    ScopedVLogTimer timer(1, "MasterClient::GracefulUnmountSegmentTo");
+    timer.LogRequest("address=", address, ", segment_id=", segment_id,
+                     ", client_id=", client_id_,
+                     ", grace_period_ms=", grace_period_ms);
+
+    auto result =
+        invoke_rpc_to<&WrappedMasterService::GracefulUnmountSegment, void>(
+            address, segment_id, client_id_, grace_period_ms);
+    timer.LogResponseExpected(result);
+    return result;
+}
+
 tl::expected<void, ErrorCode> MasterClient::UnmountNoFSegment(
     const UUID& segment_id) {
     ScopedVLogTimer timer(1, "MasterClient::UnmountNoFSegment");
@@ -1047,6 +1765,21 @@ tl::expected<PingResponse, ErrorCode> MasterClient::Ping() {
     return result;
 }
 
+std::string MasterClient::GetCurrentAddress() const {
+    return client_accessor_.GetAddress();
+}
+
+tl::expected<PingResponse, ErrorCode> MasterClient::PingTo(
+    const std::string& address) {
+    ScopedVLogTimer timer(1, "MasterClient::PingTo");
+    timer.LogRequest("address=", address, ", client_id=", client_id_);
+
+    auto result = invoke_rpc_to<&WrappedMasterService::Ping, PingResponse>(
+        address, client_id_);
+    timer.LogResponseExpected(result);
+    return result;
+}
+
 tl::expected<std::string, ErrorCode> MasterClient::GetFsdir() {
     ScopedVLogTimer timer(1, "MasterClient::GetFsdir");
     timer.LogRequest("action=get_fsdir");
@@ -1067,6 +1800,18 @@ tl::expected<SegmentStatus, ErrorCode> MasterClient::QuerySegmentStatusById(
     return result;
 }
 
+tl::expected<SegmentStatus, ErrorCode>
+MasterClient::QuerySegmentStatusByIdTo(const std::string& address,
+                                       const UUID& segment_id) {
+    ScopedVLogTimer timer(1, "MasterClient::QuerySegmentStatusByIdTo");
+    timer.LogRequest("address=", address, ", segment_id=", segment_id);
+
+    auto result = invoke_rpc_to<&WrappedMasterService::QuerySegmentStatusById,
+                                SegmentStatus>(address, segment_id);
+    timer.LogResponseExpected(result);
+    return result;
+}
+
 tl::expected<GetStorageConfigResponse, ErrorCode>
 MasterClient::GetStorageConfig() {
     ScopedVLogTimer timer(1, "MasterClient::GetStorageConfig");
@@ -1447,11 +2192,45 @@ std::vector<tl::expected<void, ErrorCode>> MasterClient::BatchEvictDiskReplica(
     timer.LogRequest("keys_count=", keys.size(), ", tenant_id=", tenant_id,
                      ", replica_type=", replica_type);
 
-    auto result =
-        invoke_batch_rpc<&WrappedMasterService::BatchEvictDiskReplica, void>(
-            keys.size(), client_id_, keys, tenant_id, replica_type);
-    timer.LogResponse("result=", result.size(), " operations");
-    return result;
+    // Single-master mode (routing not loaded): use the original batch path.
+    if (partition_router_.Size() == 0) {
+        auto result =
+            invoke_batch_rpc<&WrappedMasterService::BatchEvictDiskReplica,
+                             void>(keys.size(), client_id_, keys, tenant_id,
+                                   replica_type);
+        timer.LogResponse("result=", result.size(), " operations");
+        return result;
+    }
+
+    std::vector<tl::expected<void, ErrorCode>> results(
+        keys.size(),
+        tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS));
+
+    auto groups = GroupKeysBySubmaster(keys, tenant_id);
+    for (auto& [submaster, indices] : groups) {
+        if (submaster.empty()) {
+            LOG(WARNING) << "BatchEvictDiskReplica: " << indices.size()
+                         << " key(s) have no submaster, marked unavailable";
+            continue;
+        }
+        SwitchToSubmasterByAddress(submaster);
+
+        std::vector<std::string> group_keys;
+        group_keys.reserve(indices.size());
+        for (size_t idx : indices) {
+            group_keys.push_back(keys[idx]);
+        }
+
+        auto group_result =
+            invoke_batch_rpc<&WrappedMasterService::BatchEvictDiskReplica,
+                             void>(group_keys.size(), client_id_, group_keys,
+                                   tenant_id, replica_type);
+        for (size_t j = 0; j < indices.size(); ++j) {
+            results[indices[j]] = std::move(group_result[j]);
+        }
+    }
+    timer.LogResponse("result=", results.size(), " operations");
+    return results;
 }
 
 }  // namespace mooncake
diff --git a/mooncake-store/src/master_metric_manager.cpp b/mooncake-store/src/master_metric_manager.cpp
index ea52ec91df..ed85529ee5 100644
--- a/mooncake-store/src/master_metric_manager.cpp
+++ b/mooncake-store/src/master_metric_manager.cpp
@@ -6,8 +6,10 @@
 #include <sstream>  // For string building during serialization
 #include <vector>   // Required by histogram serialization
 #include <cmath>
+#include <optional>
 
 #include "utils.h"
+#include "io_pattern/runtime.h"
 
 namespace mooncake {
 
@@ -330,6 +332,36 @@ MasterMetricManager::MasterMetricManager()
       nof_evicted_size_("master_evicted_size_bytes_nof",
                         "Total bytes of evicted objects in nof"),
 
+      // Report-driven IO Pattern policy execution metrics
+      io_pattern_report_cycles_(
+          "master_io_pattern_report_cycles_total",
+          "Total report-driven IO Pattern policy cycles executed after "
+          "merged client reports"),
+      io_pattern_report_evictions_(
+          "master_io_pattern_report_evictions_total",
+          "Total eviction executions from report-driven IO Pattern cycles"),
+      io_pattern_report_eviction_failures_(
+          "master_io_pattern_report_eviction_failures_total",
+          "Total failed eviction executions from report-driven IO Pattern "
+          "cycles"),
+      io_pattern_report_prefetches_(
+          "master_io_pattern_report_prefetches_total",
+          "Total prefetch executions from report-driven IO Pattern cycles"),
+      io_pattern_report_prefetch_failures_(
+          "master_io_pattern_report_prefetch_failures_total",
+          "Total failed prefetch executions from report-driven IO Pattern "
+          "cycles"),
+      io_pattern_report_admissions_(
+          "master_io_pattern_report_admissions_total",
+          "Total admission executions from report-driven IO Pattern cycles"),
+      io_pattern_report_admission_failures_(
+          "master_io_pattern_report_admission_failures_total",
+          "Total failed admission executions from report-driven IO Pattern "
+          "cycles"),
+      io_pattern_report_degraded_(
+          "master_io_pattern_report_degraded_total",
+          "Total degraded report-driven IO Pattern policy cycles"),
+
       // Initialize Discarded Replicas Counters
       put_start_discard_cnt_("master_put_start_discard_cnt",
                              "Total number of discarded PutStart operations"),
@@ -621,6 +653,16 @@ void MasterMetricManager::update_metrics_for_zero_output() {
     evicted_key_count_.inc(0);
     evicted_size_.inc(0);
 
+    // Update report-driven IO Pattern policy execution counters
+    io_pattern_report_cycles_.inc(0);
+    io_pattern_report_evictions_.inc(0);
+    io_pattern_report_eviction_failures_.inc(0);
+    io_pattern_report_prefetches_.inc(0);
+    io_pattern_report_prefetch_failures_.inc(0);
+    io_pattern_report_admissions_.inc(0);
+    io_pattern_report_admission_failures_.inc(0);
+    io_pattern_report_degraded_.inc(0);
+
     // Update PutStart Discard Metrics
     put_start_discard_cnt_.inc(0);
     put_start_release_cnt_.inc(0);
@@ -1557,6 +1599,73 @@ int64_t MasterMetricManager::get_nof_evicted_size() {
     return nof_evicted_size_.value();
 }
 
+void MasterMetricManager::inc_io_pattern_report_cycles(int64_t val) {
+    io_pattern_report_cycles_.inc(val);
+}
+
+void MasterMetricManager::inc_io_pattern_report_evictions(int64_t val) {
+    io_pattern_report_evictions_.inc(val);
+}
+
+void MasterMetricManager::inc_io_pattern_report_eviction_failures(
+    int64_t val) {
+    io_pattern_report_eviction_failures_.inc(val);
+}
+
+void MasterMetricManager::inc_io_pattern_report_prefetches(int64_t val) {
+    io_pattern_report_prefetches_.inc(val);
+}
+
+void MasterMetricManager::inc_io_pattern_report_prefetch_failures(
+    int64_t val) {
+    io_pattern_report_prefetch_failures_.inc(val);
+}
+
+void MasterMetricManager::inc_io_pattern_report_admissions(int64_t val) {
+    io_pattern_report_admissions_.inc(val);
+}
+
+void MasterMetricManager::inc_io_pattern_report_admission_failures(
+    int64_t val) {
+    io_pattern_report_admission_failures_.inc(val);
+}
+
+void MasterMetricManager::inc_io_pattern_report_degraded(int64_t val) {
+    io_pattern_report_degraded_.inc(val);
+}
+
+int64_t MasterMetricManager::get_io_pattern_report_cycles() {
+    return io_pattern_report_cycles_.value();
+}
+
+int64_t MasterMetricManager::get_io_pattern_report_evictions() {
+    return io_pattern_report_evictions_.value();
+}
+
+int64_t MasterMetricManager::get_io_pattern_report_eviction_failures() {
+    return io_pattern_report_eviction_failures_.value();
+}
+
+int64_t MasterMetricManager::get_io_pattern_report_prefetches() {
+    return io_pattern_report_prefetches_.value();
+}
+
+int64_t MasterMetricManager::get_io_pattern_report_prefetch_failures() {
+    return io_pattern_report_prefetch_failures_.value();
+}
+
+int64_t MasterMetricManager::get_io_pattern_report_admissions() {
+    return io_pattern_report_admissions_.value();
+}
+
+int64_t MasterMetricManager::get_io_pattern_report_admission_failures() {
+    return io_pattern_report_admission_failures_.value();
+}
+
+int64_t MasterMetricManager::get_io_pattern_report_degraded() {
+    return io_pattern_report_degraded_.value();
+}
+
 // PutStart Discard Metrics Getters
 int64_t MasterMetricManager::get_put_start_discard_cnt() {
     return put_start_discard_cnt_.value();
@@ -1773,6 +1882,97 @@ int64_t MasterMetricManager::get_update_task_failures() {
     return mark_task_to_complete_failures_.value();
 }
 
+void MasterMetricManager::set_io_pattern_runtime(
+    std::weak_ptr<io_pattern::IoPatternRuntime> runtime) {
+    std::lock_guard lock(io_pattern_runtime_mutex_);
+    io_pattern_runtime_ = std::move(runtime);
+}
+
+void MasterMetricManager::clear_io_pattern_runtime(
+    const io_pattern::IoPatternRuntime* runtime) {
+    std::lock_guard lock(io_pattern_runtime_mutex_);
+    if (io_pattern_runtime_.lock().get() == runtime)
+        io_pattern_runtime_.reset();
+}
+
+std::string MasterMetricManager::serialize_io_pattern_metrics() {
+    io_pattern::IoPatternObservabilitySnapshot observation;
+    io_pattern::PolicyFeedbackStats feedback;
+    {
+        // Unregister waits for snapshots and their temporary strong reference
+        // to finish, so a scrape cannot defer runtime worker shutdown beyond
+        // the lifetime of the MasterService captured by its handlers.
+        std::lock_guard lock(io_pattern_runtime_mutex_);
+        auto runtime = io_pattern_runtime_.lock();
+        if (!runtime) return {};
+        observation = runtime->ObservabilitySnapshot();
+        feedback = runtime->FeedbackSnapshot();
+    }
+
+    // Serialize snapshots rather than incrementing counters by cumulative
+    // values. Local metric objects keep concurrent scrapes independent and
+    // cannot retain stale values from a previous runtime.
+    std::string result;
+    const auto gauge = [&result](const char* name, const char* help,
+                                 double value) {
+        ylt::metric::gauge_d metric(name, help);
+        metric.update(value);
+        metric.serialize(result);
+    };
+    const auto counter = [&result](const char* name, const char* help,
+                                   uint64_t value) {
+        ylt::metric::counter_t metric(name, help);
+        metric.inc(value);
+        metric.serialize(result);
+    };
+    gauge("master_io_pattern_collect_latency_us",
+          "Maximum collection latency in microseconds since runtime startup",
+          observation.collect_latency_us);
+    gauge("master_io_pattern_analyze_latency_us",
+          "Maximum analysis latency in microseconds since runtime startup",
+          observation.analyze_latency_us);
+    gauge("master_io_pattern_policy_decision_qps",
+          "Average policy decisions per second since runtime startup; use rate "
+          "of master_io_pattern_policy_decisions_total for a rolling rate",
+          observation.policy_decision_qps);
+    counter("master_io_pattern_policy_decisions_total",
+            "Total policy decisions since runtime startup",
+            observation.policy_decisions);
+    gauge("master_io_pattern_strategy_hit_rate",
+          "Fraction of policy decisions with eviction or prefetch candidates",
+          observation.strategy_hit_rate);
+    gauge("master_io_pattern_false_positive_rate",
+          "Observed prefetch misses divided by total policy decisions",
+          observation.false_positive_rate);
+    counter("master_io_pattern_degrade_count",
+            "Total recorded degradation events since runtime startup",
+            observation.degrade_count);
+    counter("master_io_pattern_report_drop_count",
+            "Total collector drops recorded since runtime startup",
+            observation.report_drop_count);
+    gauge(
+        "master_io_pattern_hit_rate_delta",
+        "Mean hit rate delta in the bounded feedback sample window; automatic "
+        "samples compare consecutive groups of 64 accesses",
+        feedback.hit_rate_delta);
+    gauge("master_io_pattern_eviction_churn",
+          "Mean eviction feedback in the bounded sample window; automatic "
+          "samples are eviction candidate count divided by snapshot key count",
+          feedback.eviction_churn);
+    gauge("master_io_pattern_ttft_delta",
+          "Mean externally supplied TTFT delta in the bounded feedback sample "
+          "window; zero unless supplied via RecordFeedback",
+          feedback.ttft_delta);
+    gauge("master_io_pattern_prefetch_accuracy",
+          "Mean prefetch accuracy in the bounded feedback sample window; "
+          "samples without prefetch feedback currently contribute zero",
+          feedback.prefetch_accuracy);
+    gauge("master_io_pattern_feedback_samples",
+          "Number of samples currently retained in the feedback window",
+          feedback.samples);
+    return result;
+}
+
 // --- Serialization ---
 std::string MasterMetricManager::serialize_metrics() {
     // Note: Following Prometheus style, metrics with value 0 that haven't
@@ -1937,6 +2137,17 @@ std::string MasterMetricManager::serialize_metrics() {
     serialize_metric(nof_evicted_key_count_);
     serialize_metric(nof_evicted_size_);
 
+    // Serialize report-driven IO Pattern policy execution metrics
+    serialize_metric(io_pattern_report_cycles_);
+    serialize_metric(io_pattern_report_evictions_);
+    serialize_metric(io_pattern_report_eviction_failures_);
+    serialize_metric(io_pattern_report_prefetches_);
+    serialize_metric(io_pattern_report_prefetch_failures_);
+    serialize_metric(io_pattern_report_admissions_);
+    serialize_metric(io_pattern_report_admission_failures_);
+    serialize_metric(io_pattern_report_degraded_);
+    ss << serialize_io_pattern_metrics();
+
     // Serialize PutStart Discard Metrics
     serialize_metric(put_start_discard_cnt_);
     serialize_metric(put_start_release_cnt_);
@@ -2591,6 +2802,52 @@ std::string MasterMetricManager::get_summary_string(
        << "keys=" << nof_evicted_key_count << ", "
        << "size=" << byte_size_to_string(nof_evicted_size);
 
+    // Report-driven IO Pattern policy execution summary (cumulative)
+    ss << " | IO Pattern (report-driven): "
+       << "cycles=" << io_pattern_report_cycles_.value() << ", "
+       << "evict=" << io_pattern_report_evictions_.value() << "/"
+       << io_pattern_report_eviction_failures_.value() << ", "
+       << "prefetch=" << io_pattern_report_prefetches_.value() << "/"
+       << io_pattern_report_prefetch_failures_.value() << ", "
+       << "admit=" << io_pattern_report_admissions_.value() << "/"
+       << io_pattern_report_admission_failures_.value() << ", "
+       << "degraded=" << io_pattern_report_degraded_.value();
+
+    std::optional<io_pattern::IoPatternObservabilitySnapshot> observation;
+    io_pattern::PolicyFeedbackStats feedback;
+    {
+        // As with /metrics, release the temporary strong reference under the
+        // registration lock so service shutdown cannot race a summary read.
+        std::lock_guard lock(io_pattern_runtime_mutex_);
+        auto runtime = io_pattern_runtime_.lock();
+        if (runtime) {
+            observation = runtime->ObservabilitySnapshot();
+            feedback = runtime->FeedbackSnapshot();
+        }
+    }
+    if (observation) {
+        // Keep precision local: small deltas must remain visible without
+        // changing the formatting of the rest of the admin summary.
+        std::ostringstream io_summary;
+        io_summary
+            << std::setprecision(6) << " | IO Pattern (runtime, lifetime): "
+            << "collect_latency_max_us=" << observation->collect_latency_us
+            << ", analyze_latency_max_us=" << observation->analyze_latency_us
+            << ", policy_decision_qps=" << observation->policy_decision_qps
+            << ", policy_decisions=" << observation->policy_decisions
+            << ", strategy_hit_rate=" << observation->strategy_hit_rate
+            << ", false_positive_rate=" << observation->false_positive_rate
+            << ", degrade_count=" << observation->degrade_count
+            << ", report_drop_count=" << observation->report_drop_count
+            << " | IO Pattern (feedback, sample window): "
+            << "hit_rate_delta=" << feedback.hit_rate_delta
+            << ", eviction_churn=" << feedback.eviction_churn
+            << ", ttft_delta=" << feedback.ttft_delta
+            << ", prefetch_accuracy=" << feedback.prefetch_accuracy
+            << ", feedback_samples=" << feedback.samples;
+        ss << io_summary.str();
+    }
+
     // Discard summary
     ss << " | Discard: "
        << "Released/Total=" << put_start_release_cnt << "/"
diff --git a/mooncake-store/src/master_service.cpp b/mooncake-store/src/master_service.cpp
index 2aef820aa5..1f6ad30fd0 100644
--- a/mooncake-store/src/master_service.cpp
+++ b/mooncake-store/src/master_service.cpp
@@ -10,6 +10,7 @@
 #include <cstring>
 #include <future>
 #include <limits>
+#include <map>
 #include <shared_mutex>
 #include <sstream>
 #include <stdexcept>
@@ -37,6 +38,8 @@
 #ifdef STORE_USE_ETCD
 #include "etcd_helper.h"
 #include "ha/kv/etcd_ha_kv_backend.h"
+#include "cvm/etcd_view_store.h"
+#include "cvm/cvm_keys.h"
 #endif
 #include "ha/oplog/oplog_batch_storage.h"
 #include "ha/oplog/ordered_oplog_writer.h"
@@ -56,6 +59,8 @@
 #include "master_snapshot_repository.h"
 #include "ha_metric_manager.h"
 #include "metadata_store.h"
+#include "io_pattern/runtime.h"
+#include "io_pattern/cfm_service.h"
 
 namespace mooncake {
 
@@ -197,6 +202,10 @@ MasterService::MasterService(const MasterServiceConfig& config)
                     config.ha_backend_type == "etcd"),
       oplog_batch_max_entries_(config.oplog_batch_max_entries),
       cluster_id_(config.cluster_id),
+      master_id_(config.master_id),
+      cvm_http_port_(config.cvm_http_port),
+      cvm_http_host_(config.cvm_http_host),
+      submaster_count_(config.submaster_count),
       root_fs_dir_(config.root_fs_dir),
       global_file_segment_size_(config.global_file_segment_size),
       enable_disk_eviction_(config.enable_disk_eviction),
@@ -206,6 +215,10 @@ MasterService::MasterService(const MasterServiceConfig& config)
       tenant_quota_connector_uri_(config.tenant_quota_connector_uri),
       segment_manager_(config.memory_allocator, config.enable_cxl),
       nof_segment_manager_(config.memory_allocator),
+      vchunk_manager_(config.vchunk_config, config.vchunk_metadata_store),
+      vchunk_enabled_(config.vchunk_config.enabled),
+      vchunk_reaper_interval_ms_(config.vchunk_config.reaper_interval_ms),
+      vchunk_reaper_max_scan_(config.vchunk_config.reaper_max_scan),
       memory_allocator_type_(config.memory_allocator),
       allocation_strategy_type_(config.enable_cxl
                                     ? AllocationStrategyType::CXL
@@ -228,6 +241,19 @@ MasterService::MasterService(const MasterServiceConfig& config)
       offloading_queue_limit_(config.offloading_queue_limit),
       offload_cap_ratio_(config.offload_cap_ratio),
       task_manager_(config.task_manager_config) {
+    const bool partitioned_vchunk =
+        config.vchunk_config.enabled && config.enable_ha &&
+        config.ha_backend_type == "etcd" && config.submaster_count > 1;
+    if (config.vchunk_config.enabled && config.vchunk_metadata_store) {
+        if (partitioned_vchunk) {
+            vchunk_recovery_pending_ = true;
+        } else {
+            const auto error = vchunk_manager_.Recover(getCurrentTimeInMilli());
+            if (error != ErrorCode::OK) {
+                throw std::runtime_error("failed to recover vchunk metadata");
+            }
+        }
+    }
     // Initialize HTTP metadata key prefix (read env var once at startup)
     const char* custom_prefix = std::getenv("MC_METADATA_CLUSTER_ID");
     if (custom_prefix && std::strlen(custom_prefix) > 0) {
@@ -411,6 +437,301 @@ MasterService::MasterService(const MasterServiceConfig& config)
                   << ")";
     }
 
+    io_pattern::IoPatternRuntime::Config io_pattern_config;
+    // Report-driven execution: a SubMaster that merges ownership-addressed
+    // client reports runs its own analysis -> decision -> execution cycle on
+    // every accepted report (report_snapshot / report_metric_batch). This is
+    // the driver that makes remote-mode CFM execution visible: without it
+    // policy only runs on the local watermark thread, the local Put admission
+    // path or explicit execute_* RPCs.
+    io_pattern_config.report_driven_execution = true;
+    // Mirror the master's own high/low watermark semantics so a merged-report
+    // eviction cycle reclaims the same excess as the local eviction thread
+    // (target ratio = high watermark - eviction ratio; clamped to >= 0).
+    io_pattern_config.report_eviction_high_ratio =
+        static_cast<float>(eviction_high_watermark_ratio_);
+    io_pattern_config.report_eviction_target_ratio = static_cast<float>(
+        std::max(0.0, eviction_high_watermark_ratio_ - eviction_ratio_));
+    // Admission must stop before eviction starts: a negative configured watermark
+    // means "derive it from the eviction high watermark", so the store does not
+    // evict while still admitting new objects. A non-negative value pins it.
+    io_pattern_config.admission_watermark_ratio =
+        config.io_pattern_admission_watermark_ratio >= 0.0
+            ? static_cast<float>(config.io_pattern_admission_watermark_ratio)
+            : static_cast<float>(eviction_high_watermark_ratio_);
+    // Configurable so a deployment can restore the previous admit-on-first-sight
+    // behaviour (threshold 1) without recompiling.
+    io_pattern_config.admission_frequency_threshold =
+        config.io_pattern_admission_frequency_threshold;
+    // Cold-data eviction driver: allow merged reports to reclaim the coldest
+    // real objects even below the memory watermark (opt-in via master flags).
+    io_pattern_config.report_driven_cold_eviction =
+        config.io_pattern_cold_eviction;
+    io_pattern_config.report_driven_cold_eviction_bytes =
+        config.io_pattern_cold_eviction_bytes_per_cycle;
+    io_pattern_config.report_driven_cold_idle_threshold_us =
+        config.io_pattern_cold_idle_threshold_us;
+    if (config.io_pattern_cold_eviction) {
+        LOG(INFO) << "Report-driven cold-data eviction enabled: per-cycle "
+                     "budget="
+                  << config.io_pattern_cold_eviction_bytes_per_cycle
+                  << " bytes, idle threshold="
+                  << config.io_pattern_cold_idle_threshold_us << " us";
+    }
+    // Policy-driven tier-down driver: below the memory watermark, copy the
+    // coldest in-memory keys down to LOCAL_DISK while keeping their MEMORY
+    // replica, so a later reclaim can discard them safely. The per-cycle budget
+    // is the whole control: 0 (the default) keeps the driver off.
+    io_pattern_config.tier_down_bytes_per_cycle =
+        config.io_pattern_tier_down_bytes_per_cycle;
+    if (config.io_pattern_tier_down_bytes_per_cycle != 0) {
+        LOG(INFO) << "Policy-driven tier down enabled: per-cycle budget="
+                  << config.io_pattern_tier_down_bytes_per_cycle << " bytes";
+    }
+    io_pattern_config.report_driven_observer =
+        [](const io_pattern::IoPatternRuntime::ReportDrivenCycleReport& rpt) {
+            auto& metrics = MasterMetricManager::instance();
+            metrics.inc_io_pattern_report_cycles();
+            if (rpt.degraded) metrics.inc_io_pattern_report_degraded();
+            // A cycle "executes" a dimension when a plan reached the storage
+            // handler. The report-driven cycle only forwards an eviction plan
+            // with candidate keys (an empty-candidate pressure report is a
+            // clean no-op, not a failure); prefetch/admission likewise only
+            // reach their handler when candidates were planned. Failures are
+            // counted when the storage handler rejected the plan.
+            //
+            // A tier-down cycle is excluded from the eviction counters: it copies
+            // keys down and frees nothing, so counting it as a report-driven
+            // eviction would overstate reclaim. Its outcome is visible through
+            // MasterService's own tier_down_attempt/success/failure counters.
+            if (rpt.tier_down) {
+                LOG(INFO) << "[IO-PATTERN-TIER-DOWN] report-driven tier-down "
+                             "cycle="
+                          << rpt.cycle_id
+                          << " budget=" << rpt.eviction_target_bytes
+                          << " candidates=" << rpt.eviction_candidates
+                          << " status=" << static_cast<int>(rpt.eviction_status)
+                          << " skipped=" << rpt.skipped_dimensions;
+            } else if (rpt.eviction_candidates != 0) {
+                metrics.inc_io_pattern_report_evictions();
+                if (rpt.eviction_status != ErrorCode::OK) {
+                    metrics.inc_io_pattern_report_eviction_failures();
+                }
+            }
+            if (rpt.prefetch_candidates != 0) {
+                metrics.inc_io_pattern_report_prefetches();
+                if (rpt.prefetch_status != ErrorCode::OK) {
+                    metrics.inc_io_pattern_report_prefetch_failures();
+                }
+            }
+            if (rpt.admissions_admitted != 0) {
+                metrics.inc_io_pattern_report_admissions();
+                if (rpt.admission_status != ErrorCode::OK) {
+                    metrics.inc_io_pattern_report_admission_failures();
+                }
+            }
+            LOG(INFO) << "[IO-PATTERN-REPORT-CYCLE] cycle=" << rpt.cycle_id
+                      << " keys_analyzed=" << rpt.keys_analyzed
+                      << " analysis_elapsed_us=" << rpt.analysis_elapsed_us
+                      << " degraded=" << rpt.degraded
+                      << " skipped=" << rpt.skipped_dimensions
+                      << " eviction(tier="
+                      << static_cast<int>(rpt.eviction_tier)
+                      << ", bytes=" << rpt.eviction_target_bytes
+                      << ", candidates=" << rpt.eviction_candidates
+                      << ", status=" << static_cast<int>(rpt.eviction_status)
+                      << ", cold=" << rpt.cold_eviction
+                      << ", tier_down=" << rpt.tier_down << ")"
+                      << " prefetch(candidates=" << rpt.prefetch_candidates
+                      << ", status=" << static_cast<int>(rpt.prefetch_status)
+                      << ")"
+                      << " admission(candidates=" << rpt.admission_candidates
+                      << ", admitted=" << rpt.admissions_admitted
+                      << ", status=" << static_cast<int>(rpt.admission_status)
+                      << ")";
+        };
+    // Promotion is the Store's only cross-tier primitive, and it can decline for
+    // structural reasons the policy cannot influence: promotion disabled, no
+    // LOCAL_DISK source replica, or watermark / queue-cap / second-touch
+    // backpressure. Those map to UNAVAILABLE_IN_CURRENT_MODE so the runtime
+    // records a skip instead of a policy failure -- otherwise three such cycles
+    // would permanently replace the workload policy with the legacy fallback.
+    // Only a vanished object or a genuine enqueue failure stays an error.
+    // Captured by value: a captureless lambda is an empty, copyable type, so no
+    // local outlives this constructor.
+    const auto promotion_outcome_to_error =
+        [](PromotionQueueResult outcome) -> ErrorCode {
+        switch (outcome) {
+            case PromotionQueueResult::kQueued:
+            case PromotionQueueResult::kAlreadyInFlight:
+            case PromotionQueueResult::kMemoryReplicaPresent:
+                return ErrorCode::OK;
+            case PromotionQueueResult::kDisabled:
+            case PromotionQueueResult::kFrequencyRejected:
+            case PromotionQueueResult::kWatermarkRejected:
+            case PromotionQueueResult::kQueueCapRejected:
+            case PromotionQueueResult::kNoLocalDiskSource:
+                return ErrorCode::UNAVAILABLE_IN_CURRENT_MODE;
+            case PromotionQueueResult::kNotFound:
+            case PromotionQueueResult::kPushFailed:
+                return ErrorCode::OBJECT_NOT_FOUND;
+        }
+        return ErrorCode::OBJECT_NOT_FOUND;
+    };
+    io_pattern_runtime_ = std::make_shared<io_pattern::IoPatternRuntime>(
+        io_pattern::IoPatternRuntime::Handlers{
+            .eviction =
+                [this](const io_pattern::EvictionPlan& plan) {
+                    struct TenantCandidates {
+                        uint64_t bytes{0};
+                        std::unordered_set<std::string> keys;
+                    };
+                    if (plan.target_bytes == 0) return ErrorCode::OK;
+                    // A tier-down plan copies objects down and keeps their
+                    // MEMORY replica, so it frees nothing. Only the reclaim share
+                    // of the plan may drive the legacy fallback below: counting
+                    // the demotion budget as a shortfall would make the fallback
+                    // evict exactly the keys the driver just chose to keep.
+                    const uint64_t tier_down_target =
+                        std::min(plan.tier_down_target_bytes,
+                                 plan.target_bytes);
+                    const uint64_t reclaim_target =
+                        plan.target_bytes - tier_down_target;
+                    uint64_t total_freed = 0;
+                    uint64_t tier_down_attempts = 0;
+                    uint64_t tier_down_queued = 0;
+                    uint64_t tier_down_failed = 0;
+                    std::unordered_map<TenantId, TenantCandidates, TenantIdHash>
+                        targets;
+                    for (const auto& candidate : plan.candidates) {
+                        // The action is per candidate and comes from the plan
+                        // (which got it from the driver), never from
+                        // target_tier. A kTierDown candidate is copied down and
+                        // keeps its MEMORY replica, so it is excluded from the
+                        // quota eviction below and from freed accounting.
+                        if (candidate.action ==
+                            io_pattern::EvictionAction::kTierDown) {
+                            ++tier_down_attempts;
+                            if (TryQueueTierDown(ObjectIdentity{
+                                    candidate.object.tenant_id,
+                                    candidate.object.key})) {
+                                ++tier_down_queued;
+                            } else {
+                                ++tier_down_failed;
+                            }
+                            continue;
+                        }
+                        auto& target = targets[candidate.object.tenant_id];
+                        target.bytes += candidate.bytes;
+                        target.keys.insert(candidate.object.key);
+                    }
+                    if (tier_down_attempts != 0) {
+                        tier_down_attempts_.fetch_add(
+                            tier_down_attempts, std::memory_order_relaxed);
+                        tier_down_successes_.fetch_add(
+                            tier_down_queued, std::memory_order_relaxed);
+                        tier_down_failures_.fetch_add(
+                            tier_down_failed, std::memory_order_relaxed);
+                        LOG(WARNING)
+                            << "[IO-PATTERN-TIER-DOWN] io_pattern tier down "
+                               "plan_target="
+                            << tier_down_target
+                            << " attempts=" << tier_down_attempts
+                            << " queued=" << tier_down_queued
+                            << " failed=" << tier_down_failed;
+                    }
+                    for (const auto& [tenant, target] : targets) {
+                        const auto result = EvictTenantMemoryForQuota(
+                            tenant, target.bytes, &target.keys);
+                        total_freed =
+                            result.freed_bytes >
+                                    std::numeric_limits<uint64_t>::max() -
+                                        total_freed
+                                ? std::numeric_limits<uint64_t>::max()
+                                : total_freed + result.freed_bytes;
+                        LOG(WARNING)
+                            << "[IO-PATTERN-EVICT-DIAG] io_pattern eviction "
+                               "tenant="
+                            << tenant.value() << " target=" << target.bytes
+                            << " freed=" << result.freed_bytes
+                            << " evicted_objects=" << result.evicted_objects
+                            << " candidate_keys=" << target.keys.size();
+                        size_t shown = 0;
+                        for (const auto& key : target.keys) {
+                            if (shown++ >= 3) break;
+                            LOG(WARNING)
+                                << "[IO-PATTERN-EVICT-DIAG]   candidate key="
+                                << key;
+                        }
+                        ReportEvictedKeysAsTierRemovals(tenant, target.keys);
+                    }
+                    LOG(WARNING)
+                        << "[IO-PATTERN-EVICT-DIAG] io_pattern eviction "
+                           "summary plan_target="
+                        << plan.target_bytes
+                        << " reclaim_target=" << reclaim_target
+                        << " total_freed=" << total_freed
+                        << " candidates=" << plan.candidates.size();
+                    if (total_freed >= reclaim_target) {
+                        return ErrorCode::OK;
+                    }
+                    // The plan under-delivered its *reclaim* target: its
+                    // candidates may be stale, may still hold leases or pins, or
+                    // may be empty. Fall back to the legacy lease-ordered
+                    // eviction so the watermark request still makes progress.
+                    // This covers both the local watermark
+                    // thread and the report-driven worker, which is why the
+                    // thread no longer runs its own fallback. The tier-down share
+                    // of the plan is deliberately excluded from the shortfall: a
+                    // demotion is not a failed reclaim.
+                    const uint64_t shortfall = reclaim_target - total_freed;
+                    LOG(WARNING)
+                        << "[IO-PATTERN-EVICT-FALLBACK] policy plan under-"
+                           "delivered reclaim_target="
+                        << reclaim_target << " freed=" << total_freed
+                        << " shortfall=" << shortfall;
+                    return RunLegacyEvictionFallback(shortfall)
+                               ? ErrorCode::OK
+                               : ErrorCode::OBJECT_NOT_FOUND;
+                },
+            .prefetch =
+                [this, promotion_outcome_to_error](
+                    const io_pattern::PrefetchPlan& plan) -> ErrorCode {
+                    for (const auto& candidate : plan.candidates) {
+                        // Store's safe promotion primitive is LOCAL_DISK ->
+                        // MEMORY; HBM remains inference-runtime-owned and is
+                        // never promoted from the master control plane.
+                        if (candidate.target_tier ==
+                            io_pattern::CacheTier::kL0Hbm) {
+                            return ErrorCode::UNAVAILABLE_IN_CURRENT_MODE;
+                        }
+                        const ObjectIdentity object_id{
+                            candidate.object.tenant_id, candidate.object.key};
+                        const auto code = promotion_outcome_to_error(
+                            TryPushPromotionQueue(object_id,
+                                                  /*record_candidate=*/false));
+                        if (code != ErrorCode::OK) {
+                            return code;
+                        }
+                    }
+                    return ErrorCode::OK;
+                },
+            .admission =
+                [this, promotion_outcome_to_error](
+                    const io_pattern::AdmissionResult& result) -> ErrorCode {
+                    if (result.target_tier == io_pattern::CacheTier::kL0Hbm) {
+                        return ErrorCode::UNAVAILABLE_IN_CURRENT_MODE;
+                    }
+                    const ObjectIdentity object_id{result.object.tenant_id,
+                                                   result.object.key};
+                    return promotion_outcome_to_error(TryPushPromotionQueue(
+                        object_id, /*record_candidate=*/false));
+                }},
+        std::move(io_pattern_config));
+    MasterMetricManager::instance().set_io_pattern_runtime(io_pattern_runtime_);
+    io_pattern_cfm_service_ = std::make_shared<io_pattern::CfmService>(
+        io_pattern_runtime_);
+
     kv_event_publisher_ =
         std::make_unique<KvEventPublisher>(BuildKvEventConfig(config));
 
@@ -448,6 +769,13 @@ MasterService::MasterService(const MasterServiceConfig& config)
 #endif
     }
 
+    // KV partition (CVM) ownership is now owned by the HA supervisor: the
+    // supervisor creates the CvmController (etcd lease + master registration +
+    // snapshot aggregation + membership loop), then injects the lease id and
+    // drives SlotOwnerHeartbeat around serve start/stop via
+    // SetCvmLeaseId() / StartSlotOwnerHeartbeat() / StopSlotOwnerHeartbeat().
+    // MasterService itself only publishes slot/segment ownership records.
+
     eviction_running_ = true;
     eviction_thread_ = std::thread(&MasterService::EvictionThreadFunc, this);
     VLOG(1) << "action=start_eviction_thread";
@@ -528,6 +856,173 @@ MasterService::MasterService(const MasterServiceConfig& config)
         segment_manager_.initializeCxlAllocator(cxl_path_, cxl_size_);
         VLOG(1) << "action=start_cxl_global_allocator";
     }
+
+    if (vchunk_enabled_ && !vchunk_recovery_pending_) {
+        StartVChunkReaper();
+    }
+}
+
+tl::expected<VChunkMetadataRecord, ErrorCode> MasterService::VChunkPutStart(
+    const TenantId& tenant_id, const std::string& key, uint64_t total_size,
+    bool is_ssd_segment, int64_t now_ms,
+    const std::set<std::string>& excluded_segments) {
+    if (!vchunk_enabled_) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_MODE);
+    }
+    if (!OwnsVChunkSlot(cvm::KeySlot(tenant_id, key))) {
+        return tl::make_unexpected(ErrorCode::SLOT_NOT_OWNED);
+    }
+    auto allocator_access = segment_manager_.getAllocatorAccess();
+    return vchunk_manager_.PutStart(allocator_access.getAllocatorManager(),
+                                    tenant_id, key, total_size, is_ssd_segment,
+                                    now_ms, excluded_segments);
+}
+
+ErrorCode MasterService::VChunkPutEnd(const TenantId& tenant_id,
+                                      const std::string& key,
+                                      const std::string& vchunk_id,
+                                      int64_t now_ms) {
+    if (!vchunk_enabled_) {
+        return ErrorCode::UNAVAILABLE_IN_CURRENT_MODE;
+    }
+    if (!OwnsVChunkSlot(cvm::KeySlot(tenant_id, key))) {
+        return ErrorCode::SLOT_NOT_OWNED;
+    }
+    return vchunk_manager_.PutEnd(tenant_id, key, vchunk_id, now_ms);
+}
+
+ErrorCode MasterService::VChunkPutRevoke(const TenantId& tenant_id,
+                                         const std::string& key,
+                                         const std::string& vchunk_id) {
+    if (!vchunk_enabled_) {
+        return ErrorCode::UNAVAILABLE_IN_CURRENT_MODE;
+    }
+    if (!OwnsVChunkSlot(cvm::KeySlot(tenant_id, key))) {
+        return ErrorCode::SLOT_NOT_OWNED;
+    }
+    auto allocator_access = segment_manager_.getAllocatorAccess();
+    return vchunk_manager_.PutRevoke(tenant_id, key, vchunk_id);
+}
+
+tl::expected<VChunkMetadataRecord, ErrorCode> MasterService::GetVChunk(
+    const TenantId& tenant_id, const std::string& key) const {
+    if (!vchunk_enabled_) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_MODE);
+    }
+    if (!OwnsVChunkSlot(cvm::KeySlot(tenant_id, key))) {
+        return tl::make_unexpected(ErrorCode::SLOT_NOT_OWNED);
+    }
+    return vchunk_manager_.Get(tenant_id, key);
+}
+
+tl::expected<VChunkMasterManager::ReadHandle, ErrorCode>
+MasterService::AcquireVChunkRead(const TenantId& tenant_id,
+                                 const std::string& key) const {
+    if (!vchunk_enabled_) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_MODE);
+    }
+    if (!OwnsVChunkSlot(cvm::KeySlot(tenant_id, key))) {
+        return tl::make_unexpected(ErrorCode::SLOT_NOT_OWNED);
+    }
+    return vchunk_manager_.AcquireRead(tenant_id, key);
+}
+
+tl::expected<VChunkReadLease, ErrorCode> MasterService::AcquireVChunkReadLease(
+    const TenantId& tenant_id, const std::string& key, int64_t now_ms) {
+    constexpr int64_t kRemoteReadLeaseTtlMs = 5 * 60 * 1000;
+    if (now_ms < 0 ||
+        now_ms > std::numeric_limits<int64_t>::max() - kRemoteReadLeaseTtlMs) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    auto handle = AcquireVChunkRead(tenant_id, key);
+    if (!handle) {
+        return tl::make_unexpected(handle.error());
+    }
+    VChunkReadLease lease{handle->record(), UuidToString(generate_uuid())};
+    {
+        std::lock_guard<std::mutex> guard(vchunk_read_leases_mutex_);
+        vchunk_read_leases_.emplace(
+            lease.lease_id,
+            VChunkRemoteReadLease{std::move(*handle),
+                                  now_ms + kRemoteReadLeaseTtlMs});
+    }
+    return lease;
+}
+
+ErrorCode MasterService::ReleaseVChunkReadLease(const std::string& lease_id) {
+    if (lease_id.empty()) {
+        return ErrorCode::INVALID_PARAMS;
+    }
+    std::lock_guard<std::mutex> guard(vchunk_read_leases_mutex_);
+    vchunk_read_leases_.erase(lease_id);
+    return ErrorCode::OK;
+}
+
+ErrorCode MasterService::RemoveVChunk(const TenantId& tenant_id,
+                                      const std::string& key, int64_t now_ms) {
+    if (!vchunk_enabled_) {
+        return ErrorCode::UNAVAILABLE_IN_CURRENT_MODE;
+    }
+    if (!OwnsVChunkSlot(cvm::KeySlot(tenant_id, key))) {
+        return ErrorCode::SLOT_NOT_OWNED;
+    }
+    auto allocator_access = segment_manager_.getAllocatorAccess();
+    return vchunk_manager_.Remove(tenant_id, key, now_ms);
+}
+
+VChunkRuntimeInfo MasterService::GetVChunkRuntimeInfo() const {
+    return {vchunk_enabled_, vchunk_manager_.HasPersistentMetadata()};
+}
+
+tl::expected<size_t, ErrorCode> MasterService::ReapExpiredVChunks(
+    int64_t now_ms, size_t max_scan) {
+    if (!vchunk_enabled_) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_MODE);
+    }
+    {
+        std::lock_guard<std::mutex> guard(vchunk_read_leases_mutex_);
+        std::erase_if(vchunk_read_leases_, [now_ms](const auto& item) {
+            return item.second.expires_at_ms <= now_ms;
+        });
+    }
+    auto allocator_access = segment_manager_.getAllocatorAccess();
+    return vchunk_manager_.ReapExpired(
+        now_ms, max_scan, [this](const VChunkMetadataRecord& record) {
+            return OwnsVChunkSlot(
+                cvm::KeySlot(TenantId(record.tenant_id), record.key));
+        });
+}
+
+VChunkMetricsSnapshot MasterService::GetVChunkMetrics() const {
+    return vchunk_manager_.MetricsSnapshot();
+}
+
+void MasterService::VChunkReaperThreadFunc() {
+    std::unique_lock<std::mutex> lock(vchunk_reaper_mutex_);
+    while (vchunk_reaper_running_) {
+        if (vchunk_reaper_cv_.wait_for(
+                lock, std::chrono::milliseconds(vchunk_reaper_interval_ms_),
+                [this] { return !vchunk_reaper_running_.load(); })) {
+            break;
+        }
+        lock.unlock();
+        const auto result = ReapExpiredVChunks(getCurrentTimeInMilli(),
+                                               vchunk_reaper_max_scan_);
+        if (!result) {
+            LOG(ERROR) << "vchunk reaper failed, error="
+                       << static_cast<int>(result.error());
+        }
+        lock.lock();
+    }
+}
+
+void MasterService::StartVChunkReaper() {
+    bool expected = false;
+    if (!vchunk_reaper_running_.compare_exchange_strong(expected, true)) {
+        return;
+    }
+    vchunk_reaper_thread_ =
+        std::thread(&MasterService::VChunkReaperThreadFunc, this);
 }
 
 std::unique_ptr<ha::SnapshotCatalogStore>
@@ -548,22 +1043,834 @@ MasterService::CreateSnapshotCatalogStore() {
                 "redis snapshot catalog store is unavailable in the current "
                 "build");
 #else
-            const auto connstring = !snapshot_catalog_store_connstring_.empty()
-                                        ? snapshot_catalog_store_connstring_
-                                        : ha_backend_connstring_;
-            if (connstring.empty()) {
-                throw std::invalid_argument(
-                    "redis snapshot catalog store requires a connection "
-                    "string");
-            }
-            return std::make_unique<
-                ha::backends::redis::RedisSnapshotCatalogStore>(
-                snapshot_object_store_.get(), connstring, cluster_id_);
+            const auto connstring = !snapshot_catalog_store_connstring_.empty()
+                                        ? snapshot_catalog_store_connstring_
+                                        : ha_backend_connstring_;
+            if (connstring.empty()) {
+                throw std::invalid_argument(
+                    "redis snapshot catalog store requires a connection "
+                    "string");
+            }
+            return std::make_unique<
+                ha::backends::redis::RedisSnapshotCatalogStore>(
+                snapshot_object_store_.get(), connstring, cluster_id_);
+#endif
+        }
+    }
+
+    throw std::invalid_argument("unknown snapshot catalog store type");
+}
+
+void MasterService::SetCvmLeaseId(EtcdLeaseId lease_id) {
+    cvm_lease_id_ = lease_id;
+}
+
+void MasterService::StopSlotOwnerHeartbeat() {
+    if (slot_owner_heartbeat_) {
+        slot_owner_heartbeat_->Stop();
+        slot_owner_heartbeat_.reset();
+    }
+}
+
+#ifdef STORE_USE_ETCD
+ErrorCode MasterService::StartSlotOwnerHeartbeat() {
+    const bool kv_partition_enabled =
+        enable_ha_ && ha_backend_type_ == "etcd" && !master_id_.empty() &&
+        !cluster_id_.empty();
+    if (!kv_partition_enabled) {
+        return ErrorCode::OK;
+    }
+
+    // The supervisor's CvmController already connected the etcd client before
+    // this point; ConnectToEtcdStoreClient is idempotent so re-connecting is a
+    // safe no-op for direct constructions / tests.
+    ErrorCode connect_err =
+        EtcdHelper::ConnectToEtcdStoreClient(ha_backend_connstring_);
+    if (connect_err != ErrorCode::OK) {
+        LOG(WARNING) << "StartSlotOwnerHeartbeat: failed to connect etcd: "
+                     << connect_err;
+        return connect_err;
+    }
+
+    if (slot_owner_heartbeat_) {
+        return ErrorCode::OK;  // already running
+    }
+
+    const auto initial_slots = ResolveOwnedSlotsForCvm();
+    UpdateOwnedSlots(initial_slots);
+    if (vchunk_recovery_pending_) {
+        const auto error = vchunk_manager_.Recover(
+            getCurrentTimeInMilli(),
+            [this](const VChunkMetadataRecord& record) {
+                return OwnsVChunkSlot(
+                    cvm::KeySlot(TenantId(record.tenant_id), record.key));
+            });
+        if (error != ErrorCode::OK) {
+            LOG(ERROR) << "Failed to recover owned vchunk metadata: "
+                       << static_cast<int>(error);
+            return error;
+        }
+        vchunk_recovery_pending_ = false;
+        StartVChunkReaper();
+    }
+
+    cvm::SlotOwnerHeartbeat::Config hb_config;
+    hb_config.cluster_namespace = cluster_id_;
+    hb_config.master_id = master_id_;
+    // Dynamic partition: recompute the owned slot set from the etcd master
+    // membership on every heartbeat so multiple submaster instances split the
+    // 16384 slots without overwriting each other.
+    hb_config.dynamic_slot_resolver = [this]() {
+        auto slots = ResolveOwnedSlotsForCvm();
+        UpdateOwnedSlots(slots);
+        return slots;
+    };
+    hb_config.lease_id = cvm_lease_id_;
+    // live primary → live primary 元数据交接（P4 技术债 1）：slot 平移时在
+    // 释放端导出对象元数据、在获得端导入，避免只依赖 standby 回放晋升路径。
+    hb_config.on_slot_acquired = [this](uint16_t slot) {
+        (void)ImportSlotMetadata(slot);
+    };
+    hb_config.on_slot_released = [this](uint16_t slot) {
+        (void)ExportSlotMetadata(slot);
+    };
+    const bool lease_bound = hb_config.lease_id != 0;
+    slot_owner_heartbeat_ =
+        std::make_unique<cvm::SlotOwnerHeartbeat>(std::move(hb_config));
+    ErrorCode hb_err = slot_owner_heartbeat_->Start();
+    if (hb_err != ErrorCode::OK) {
+        LOG(WARNING) << "Failed to start SlotOwnerHeartbeat: " << hb_err;
+        slot_owner_heartbeat_.reset();
+        return hb_err;
+    }
+    LOG(INFO) << "Started SlotOwnerHeartbeat: master_id=" << master_id_
+              << ", cluster_namespace=" << cluster_id_
+              << ", dynamic_partition=true"
+              << ", lease_bound=" << lease_bound;
+    return ErrorCode::OK;
+}
+
+#ifdef STORE_USE_ETCD
+ErrorCode MasterService::StartInterMasterRpc() {
+    const bool cvm_enabled = enable_ha_ && ha_backend_type_ == "etcd" &&
+                             !master_id_.empty() && !cluster_id_.empty();
+    if (!cvm_enabled) {
+        return ErrorCode::OK;
+    }
+
+    // The supervisor's CvmController already connected the etcd client;
+    // re-connecting is an idempotent no-op.
+    ErrorCode connect_err =
+        EtcdHelper::ConnectToEtcdStoreClient(ha_backend_connstring_);
+    if (connect_err != ErrorCode::OK) {
+        LOG(WARNING) << "StartInterMasterRpc: failed to connect etcd: "
+                     << connect_err;
+        return connect_err;
+    }
+
+    if (inter_master_rpc_) {
+        return ErrorCode::OK;  // already running
+    }
+
+    inter_master_rpc_ = std::make_unique<cvm::InterMasterRpcClient>();
+    ErrorCode rc = inter_master_rpc_->Start(cluster_id_, master_id_);
+    if (rc != ErrorCode::OK) {
+        LOG(WARNING) << "StartInterMasterRpc: refresh loop not started: " << rc
+                     << " (manual member updates still work)";
+        // Keep the client object for manual member updates; only the
+        // etcd-driven refresh thread is unavailable.
+    }
+    LOG(INFO) << "Started InterMasterRpcClient: master_id=" << master_id_
+              << ", cluster_namespace=" << cluster_id_;
+    return ErrorCode::OK;
+}
+
+void MasterService::StopInterMasterRpc() {
+    if (inter_master_rpc_) {
+        inter_master_rpc_->Stop();
+        inter_master_rpc_.reset();
+    }
+}
+#else
+ErrorCode MasterService::StartInterMasterRpc() { return ErrorCode::OK; }
+void MasterService::StopInterMasterRpc() {}
+#endif
+
+uint32_t MasterService::GetOwnedSlotCount() const {
+    std::shared_lock<std::shared_mutex> lock(owned_slots_mutex_);
+    if (!owned_slots_ready_) {
+        return 0;
+    }
+    return static_cast<uint32_t>(
+        std::count(owned_slot_lookup_.begin(), owned_slot_lookup_.end(), true));
+}
+
+tl::expected<std::vector<Replica::Descriptor>, ErrorCode>
+MasterService::InterMasterAllocateReplicas(
+    const std::string& tenant_id, const std::string& key, uint64_t slice_length,
+    uint64_t replica_num, const std::vector<std::string>& preferred_segments) {
+    if (key.empty() || slice_length == 0 || replica_num == 0) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+
+    ScopedAllocatorAccess allocator_access =
+        segment_manager_.getAllocatorAccess();
+    const auto& allocator_manager = allocator_access.getAllocatorManager();
+    const auto& local_names = allocator_manager.getNames();
+    if (local_names.empty()) {
+        return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
+    }
+
+    // Strict mode: when preferred segments are given, only allocate in them.
+    // Exclude every other local segment so the strategy's random fallback
+    // cannot leak the allocation into unrelated segments.
+    std::set<std::string> excluded;
+    if (!preferred_segments.empty()) {
+        const std::unordered_set<std::string> preferred(
+            preferred_segments.begin(), preferred_segments.end());
+        bool any_preferred_local = false;
+        for (const auto& name : local_names) {
+            if (preferred.count(name) > 0) {
+                any_preferred_local = true;
+            } else {
+                excluded.insert(name);
+            }
+        }
+        if (!any_preferred_local) {
+            return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
+        }
+    }
+
+    auto allocation = allocation_strategy_->Allocate(
+        allocator_manager, slice_length, replica_num, preferred_segments,
+        excluded, ReplicaType::MEMORY);
+    if (!allocation.has_value()) {
+        return tl::make_unexpected(allocation.error());
+    }
+    // Partial allocation is not forwarded: the slot owner requires the full
+    // replica count. Dropped here => destructors free the partial handles.
+    if (allocation->size() != replica_num) {
+        return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
+    }
+
+    std::vector<Replica::Descriptor> descriptors;
+    descriptors.reserve(allocation->size());
+    for (const auto& replica : allocation.value()) {
+        descriptors.push_back(replica.get_descriptor());
+    }
+    const std::string scoped_key = TenantId(tenant_id).MakeScopedKey(key);
+    {
+        std::lock_guard<std::mutex> lock(inter_master_keepalive_mutex_);
+        // Replace any stale keepalive entry for the same key: erasing frees
+        // the old handles (idempotent re-PutStart after an aborted write).
+        inter_master_keepalive_.erase(scoped_key);
+        inter_master_keepalive_.emplace(scoped_key,
+                                        std::move(allocation.value()));
+    }
+    LOG(INFO) << "InterMasterAllocateReplicas: allocated " << descriptors.size()
+              << " replica(s) for scoped_key=" << scoped_key
+              << ", slice_length=" << slice_length
+              << ", preferred_segments=" << preferred_segments.size();
+    return descriptors;
+}
+
+tl::expected<bool, ErrorCode> MasterService::InterMasterFreeReplicas(
+    const std::string& tenant_id, const std::string& key) {
+    const std::string scoped_key = TenantId(tenant_id).MakeScopedKey(key);
+    std::vector<Replica> released;
+    {
+        std::lock_guard<std::mutex> lock(inter_master_keepalive_mutex_);
+        auto it = inter_master_keepalive_.find(scoped_key);
+        if (it == inter_master_keepalive_.end()) {
+            return false;  // not the owner of this key's handles
+        }
+        released = std::move(it->second);
+        inter_master_keepalive_.erase(it);
+    }
+    // Replica destructors free the handles at this (segment owning) master.
+    LOG(INFO) << "InterMasterFreeReplicas: freed " << released.size()
+              << " replica(s) for scoped_key=" << scoped_key;
+    return true;
+}
+
+tl::expected<GetReplicaListResponse, ErrorCode>
+MasterService::InterMasterGetReplicaList(const std::string& key,
+                                         const std::string& tenant_id) {
+    const TenantId tenant(tenant_id);
+    const auto object_id = MakeObjectIdentityForRequest(key, tenant);
+    // peer 互信：不校验 OwnsSlot、不再次转发，直接本地查询（转发链止于
+    // 第一跳，避免视图不一致时的循环转发）。
+    return GetReplicaListLocal(object_id);
+}
+
+std::vector<tl::expected<GetReplicaListResponse, ErrorCode>>
+MasterService::InterMasterBatchGetReplicaList(
+    const std::vector<std::string>& keys, const std::string& tenant_id) {
+    const TenantId tenant(tenant_id);
+    return BatchGetReplicaListLocal(keys, tenant);
+}
+
+tl::expected<std::vector<Replica::Descriptor>, ErrorCode>
+MasterService::InterMasterPutStart(const UUID& client_id,
+                                   const std::string& key,
+                                   const std::string& tenant_id,
+                                   uint64_t slice_length,
+                                   const ReplicateConfig& config) {
+    const TenantId tenant(tenant_id);
+    // peer 互信：调用方已按 slot 归属解析本机为 owner，直接执行完整本地
+    // PutStart（分配 + 写元数据 + keepalive）。本机 OwnsSlot==true，不会再
+    // 二次转发（转发链止于第一跳，避免视图不一致时的循环转发）。
+    return PutStart(client_id, key, tenant, slice_length, config);
+}
+
+tl::expected<std::vector<Replica::Descriptor>, ErrorCode>
+MasterService::InterMasterUpsertStart(const UUID& client_id,
+                                      const std::string& key,
+                                      const std::string& tenant_id,
+                                      uint64_t slice_length,
+                                      const ReplicateConfig& config) {
+    const TenantId tenant(tenant_id);
+    // Upsert 转发：本机为 slot owner，执行完整本地 UpsertStart 以保留
+    // "已存在则覆盖（preemption）"语义；由 PutStart 转发走 PutStart 会丢失
+    // 该覆盖语义。peer 互信，不二次转发。
+    return UpsertStart(client_id, key, tenant, slice_length, config);
+}
+
+tl::expected<std::vector<Replica>, ErrorCode>
+MasterService::TryAllocateReplicasRemotely(
+    const std::string& key, const TenantId& tenant_id, uint64_t value_length,
+    size_t replica_num, const std::vector<std::string>& preferred_segments) {
+#ifdef STORE_USE_ETCD
+    if (!inter_master_rpc_ || replica_num == 0) {
+        return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
+    }
+    const std::string tenant_str = tenant_id.value();
+    for (const auto& member : inter_master_rpc_->GetMembers()) {
+        if (member.master_id.empty() || member.master_id == master_id_) {
+            continue;
+        }
+        auto remote = inter_master_rpc_->AllocateReplicas(
+            member.master_id, tenant_str, key, value_length,
+            static_cast<uint64_t>(replica_num), preferred_segments);
+        if (!remote.has_value()) {
+            VLOG(1) << "Remote allocation on " << member.master_id
+                    << " failed for key=" << key << ": "
+                    << toString(remote.error());
+            continue;
+        }
+        if (remote->size() < replica_num) {
+            // Partial result: free it at the peer and keep probing.
+            inter_master_rpc_->FreeReplicas(member.master_id, tenant_str, key);
+            continue;
+        }
+
+        // Materialize dummy-allocator replicas from the descriptors (same
+        // pattern as ImportSlotMetadata). The real handles stay alive at the
+        // segment owner's keepalive registry.
+        std::vector<Replica> replicas;
+        replicas.reserve(remote->size());
+        for (const auto& desc : remote.value()) {
+            if (!desc.is_memory_replica()) {
+                continue;
+            }
+            const auto& mem_desc = desc.get_memory_descriptor();
+            const std::string& endpoint =
+                mem_desc.buffer_descriptor.transport_endpoint_;
+            std::shared_ptr<DummyBufferAllocator> alloc;
+            {
+                std::lock_guard<std::mutex> lock(
+                    remote_replica_allocator_keepalive_mutex_);
+                auto& slot = remote_replica_allocator_keepalive_[endpoint];
+                if (!slot) {
+                    slot = std::make_shared<DummyBufferAllocator>(endpoint,
+                                                                  endpoint);
+                }
+                alloc = slot;
+            }
+            replicas.emplace_back(std::make_unique<AllocatedBuffer>(
+                                      alloc, mem_desc.buffer_descriptor),
+                                  desc.status);
+        }
+        if (replicas.size() != replica_num) {
+            // Unexpected descriptor types: undo at the peer and fail.
+            inter_master_rpc_->FreeReplicas(member.master_id, tenant_str, key);
+            continue;
+        }
+
+        {
+            std::lock_guard<std::mutex> lock(remote_allocated_keys_mutex_);
+            remote_allocated_keys_.insert(tenant_id.MakeScopedKey(key));
+        }
+        LOG(INFO) << "Allocated " << replicas.size()
+                  << " remote replica(s) for key=" << key
+                  << " on segment owner " << member.master_id;
+        return replicas;
+    }
+    return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
+#else
+    (void)key;
+    (void)tenant_id;
+    (void)value_length;
+    (void)replica_num;
+    (void)preferred_segments;
+    return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
+#endif
+}
+
+void MasterService::EnqueueRemoteFreeIfTracked(const TenantId& tenant_id,
+                                               const std::string& key,
+                                               QuotaEraseMode quota_mode) {
+#ifdef STORE_USE_ETCD
+    {
+        std::lock_guard<std::mutex> lock(remote_allocated_keys_mutex_);
+        if (remote_allocated_keys_.erase(tenant_id.MakeScopedKey(key)) == 0) {
+            return;  // handles (if any) are local
+        }
+    }
+    if (quota_mode == QuotaEraseMode::kHandoff) {
+        // Slot migration: the data bytes live on. The importing master
+        // re-registers the key and owns the remote free from now on.
+        return;
+    }
+    if (inter_master_rpc_) {
+        inter_master_rpc_->EnqueueBroadcastFree(tenant_id.value(), key);
+    }
+#endif
+}
+
+ErrorCode MasterService::ExportSlotMetadata(uint16_t slot) {
+    // 1. Collect this slot's object metadata across all shards.
+    SlotMetadataExport export_payload;
+    export_payload.slot = slot;
+    export_payload.source_master_id = master_id_;
+
+    for (size_t shard_idx = 0; shard_idx < kNumShards; ++shard_idx) {
+        MetadataShardAccessorRO shard(this, shard_idx);
+        for (const auto& [tenant_id, tenant_state] : shard->tenants) {
+            for (const auto& [user_key, metadata] : tenant_state.metadata) {
+                if (cvm::KeySlot(tenant_id, user_key) != slot) {
+                    continue;
+                }
+                StandbyObjectEntry entry;
+                entry.tenant_id = tenant_id.value();
+                entry.key = user_key;
+                entry.metadata.client_id = metadata.client_id;
+                entry.metadata.size = metadata.size;
+                entry.metadata.group_id = metadata.group_id;
+                entry.metadata.data_type = metadata.data_type;
+                const auto& replicas = metadata.GetAllReplicas();
+                entry.metadata.replicas.reserve(replicas.size());
+                for (const auto& replica : replicas) {
+                    entry.metadata.replicas.push_back(replica.get_descriptor());
+                }
+                export_payload.objects.push_back(std::move(entry));
+            }
+        }
+    }
+
+    // 2. Serialize (struct_pack) and persist as a binary etcd value.
+    auto bytes = struct_pack::serialize(export_payload);
+    std::string value(bytes.begin(), bytes.end());
+    const std::string key = cvm::SlotMetadataExportKey(cluster_id_, slot);
+    ErrorCode err =
+        EtcdHelper::Put(key.data(), key.size(), value.data(), value.size());
+    if (err != ErrorCode::OK) {
+        LOG(WARNING) << "ExportSlotMetadata: put failed slot=" << slot
+                     << ", objects=" << export_payload.objects.size()
+                     << ", err=" << err;
+        return err;
+    }
+
+    // 3. Drop the exported objects from local metadata (release cleanup).
+    for (size_t shard_idx = 0; shard_idx < kNumShards; ++shard_idx) {
+        MetadataShardAccessorRW shard(this, shard_idx);
+        for (auto tenant_it = shard->tenants.begin();
+             tenant_it != shard->tenants.end();) {
+            auto& tenant_state = tenant_it->second;
+            for (auto it = tenant_state.metadata.begin();
+                 it != tenant_state.metadata.end();) {
+                if (cvm::KeySlot(tenant_it->first, it->first) == slot) {
+                    it = EraseMetadata(tenant_state, it, tenant_it->first,
+                                       QuotaEraseMode::kHandoff);
+                } else {
+                    ++it;
+                }
+            }
+            if (tenant_state.Empty()) {
+                tenant_it = shard->tenants.erase(tenant_it);
+            } else {
+                ++tenant_it;
+            }
+        }
+    }
+
+    LOG(INFO) << "Exported slot metadata: slot=" << slot
+              << ", objects=" << export_payload.objects.size()
+              << ", bytes=" << value.size() << ", source=" << master_id_;
+    return ErrorCode::OK;
+}
+
+ErrorCode MasterService::ImportSlotMetadata(uint16_t slot) {
+    const std::string key = cvm::SlotMetadataExportKey(cluster_id_, slot);
+    std::string value;
+    EtcdRevisionId revision = 0;
+    ErrorCode err = EtcdHelper::Get(key.data(), key.size(), value, revision);
+    if (err == ErrorCode::ETCD_KEY_NOT_EXIST) {
+        // No graceful export available (e.g. the previous owner died and the
+        // slot was reclaimed via standby replay). Nothing to pull.
+        return ErrorCode::OK;
+    }
+    if (err != ErrorCode::OK) {
+        LOG(WARNING) << "ImportSlotMetadata: get failed slot=" << slot
+                     << ", err=" << err;
+        return err;
+    }
+
+    SlotMetadataExport export_payload;
+    if (struct_pack::deserialize_to(export_payload, value) !=
+        struct_pack::errc::ok) {
+        LOG(ERROR) << "ImportSlotMetadata: deserialize failed slot=" << slot
+                   << ", bytes=" << value.size();
+        return ErrorCode::DESERIALIZE_FAIL;
+    }
+
+    const auto resolve = [](const StandbyObjectEntry& entry) {
+        auto [scoped_tenant_id, user_key] = TenantId::ParseScopedKey(entry.key);
+        TenantId tenant_id(entry.tenant_id);
+        if (tenant_id.IsDefault() && !scoped_tenant_id.IsDefault()) {
+            tenant_id = std::move(scoped_tenant_id);
+        }
+        return std::make_pair(std::move(tenant_id), std::move(user_key));
+    };
+
+    std::unordered_map<size_t, std::vector<const StandbyObjectEntry*>>
+        objects_by_shard;
+    for (const auto& entry : export_payload.objects) {
+        auto [tenant_id, user_key] = resolve(entry);
+        if (!tenant_id.IsValid()) {
+            LOG(WARNING) << "ImportSlotMetadata: invalid tenant for slot="
+                         << slot << ", key=" << entry.key;
+            continue;
+        }
+        const auto shard_idx = entry.metadata.group_id.empty()
+                                   ? getShardIndex(tenant_id, user_key)
+                                   : getShardIndex(entry.metadata.group_id);
+        objects_by_shard[shard_idx].push_back(&entry);
+    }
+
+    size_t imported = 0;
+    for (const auto& [shard_idx, shard_objects] : objects_by_shard) {
+        MetadataShardAccessorRW shard(this, shard_idx);
+        auto now = std::chrono::system_clock::now();
+        for (const auto* entry_ptr : shard_objects) {
+            const auto& entry = *entry_ptr;
+            auto [tenant_id, user_key] = resolve(entry);
+            const auto& standby_meta = entry.metadata;
+            std::vector<Replica> replicas;
+            replicas.reserve(standby_meta.replicas.size());
+            for (const auto& desc : standby_meta.replicas) {
+                if (desc.is_memory_replica()) {
+                    const auto& mem_desc = desc.get_memory_descriptor();
+                    const std::string& endpoint =
+                        mem_desc.buffer_descriptor.transport_endpoint_;
+                    auto& alloc = standby_allocator_keepalive_[endpoint];
+                    if (!alloc) {
+                        alloc = std::make_shared<DummyBufferAllocator>(
+                            endpoint, endpoint);
+                    }
+                    replicas.emplace_back(
+                        std::make_unique<AllocatedBuffer>(
+                            alloc, mem_desc.buffer_descriptor),
+                        desc.status);
+                } else if (desc.is_nof_replica()) {
+                    const auto& nof_desc = desc.get_nof_descriptor();
+                    const std::string& endpoint =
+                        nof_desc.buffer_descriptor.transport_endpoint_;
+                    auto& alloc = standby_allocator_keepalive_[endpoint];
+                    if (!alloc) {
+                        alloc = std::make_shared<DummyBufferAllocator>(
+                            endpoint, endpoint);
+                    }
+                    replicas.emplace_back(
+                        std::make_unique<AllocatedBuffer>(
+                            alloc, nof_desc.buffer_descriptor),
+                        desc.status, ReplicaType::NOF_SSD);
+                } else if (desc.is_disk_replica()) {
+                    const auto& disk_desc = desc.get_disk_descriptor();
+                    replicas.emplace_back(disk_desc.file_path,
+                                          disk_desc.object_size, desc.status);
+                } else if (desc.is_local_disk_replica()) {
+                    const auto& local_disk_desc =
+                        desc.get_local_disk_descriptor();
+                    replicas.emplace_back(
+                        local_disk_desc.client_id, local_disk_desc.object_size,
+                        local_disk_desc.transport_endpoint, desc.status);
+                }
+            }
+
+            auto& tenant_state = shard->tenants[tenant_id];
+            auto [metadata_it, inserted] = tenant_state.metadata.emplace(
+                std::piecewise_construct, std::forward_as_tuple(user_key),
+                std::forward_as_tuple(
+                    standby_meta.client_id, now, standby_meta.size,
+                    std::move(replicas), false, false, standby_meta.data_type,
+                    standby_meta.group_id, tenant_id, user_key));
+            if (!inserted) {
+                // 新获得 slot 时理论上不应碰撞；若碰撞则跳过以避免重复记账。
+                LOG(WARNING)
+                    << "ImportSlotMetadata: duplicate key slot=" << slot
+                    << ", key=" << entry.key << ", skipped";
+                continue;
+            }
+            auto& metadata = metadata_it->second;
+            if (!standby_meta.group_id.empty()) {
+                RegisterGroupMember(tenant_state, tenant_id, user_key,
+                                    standby_meta.group_id);
+            }
+            tenant_state.processing_keys.erase(user_key);
+
+            // A2：补回交接对象的账务（object count、cache 计数、quota），与
+            // Export 侧 kHandoff 的释放对称，避免新 primary 账务缺失。
+            IncrementTenantMetadataObjectCount(tenant_id);
+            SyncCacheTotalAccounting(metadata);
+            const uint64_t committed_charge =
+                CompletedMemoryQuotaCharge(metadata);
+            metadata.reserved_quota_charge_bytes = 0;
+            metadata.pending_replaced_quota_charge_bytes = 0;
+            metadata.committed_quota_charge_bytes = 0;
+            if (committed_charge > 0) {
+                auto reserve_result =
+                    ReserveTenantQuota(tenant_id, committed_charge);
+                if (reserve_result) {
+                    CommitTenantQuota(tenant_id, committed_charge);
+                    metadata.committed_quota_charge_bytes = committed_charge;
+                } else {
+                    LOG(WARNING)
+                        << "ImportSlotMetadata: quota reserve failed tenant="
+                        << tenant_id.value() << ", bytes=" << committed_charge
+                        << ", err=" << reserve_result.error();
+                }
+            }
+            ++imported;
+        }
+    }
+
+    LOG(INFO) << "Imported slot metadata: slot=" << slot
+              << ", objects=" << imported
+              << ", source=" << export_payload.source_master_id;
+
+    // 技术债 3.3：一次性交接完成后删除 slot_meta 键，避免二进制导出残留。
+    // 删除失败仅告警不阻断——残留键会在下次 acquire 时被幂等重导。
+    const std::string end = cvm::PrefixEnd(key);
+    ErrorCode del_err =
+        EtcdHelper::DeleteRange(key.data(), key.size(), end.data(), end.size());
+    if (del_err != ErrorCode::OK) {
+        LOG(WARNING) << "ImportSlotMetadata: delete slot_meta failed slot="
+                     << slot << ", err=" << del_err;
+    }
+    return ErrorCode::OK;
+}
+#else
+ErrorCode MasterService::StartInterMasterRpc() { return ErrorCode::OK; }
+
+void MasterService::StopInterMasterRpc() {}
+
+tl::expected<std::vector<Replica>, ErrorCode>
+MasterService::TryAllocateReplicasRemotely(
+    const std::string& /*key*/, const TenantId& /*tenant_id*/,
+    uint64_t /*value_length*/, size_t /*replica_num*/,
+    const std::vector<std::string>& /*preferred_segments*/) {
+    return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
+}
+
+void MasterService::EnqueueRemoteFreeIfTracked(
+    const TenantId& /*tenant_id*/, const std::string& /*key*/,
+    QuotaEraseMode /*quota_mode*/) {}
+
+ErrorCode MasterService::StartSlotOwnerHeartbeat() { return ErrorCode::OK; }
+
+ErrorCode MasterService::ExportSlotMetadata(uint16_t /*slot*/) {
+    return ErrorCode::OK;
+}
+
+ErrorCode MasterService::ImportSlotMetadata(uint16_t /*slot*/) {
+    return ErrorCode::OK;
+}
+#endif
+
+#ifdef STORE_USE_ETCD
+void MasterService::PublishSegmentOwnerForCvm(const Segment& segment) {
+    if (!enable_ha_ || ha_backend_type_ != "etcd" || master_id_.empty() ||
+        cluster_id_.empty()) {
+        return;
+    }
+    cvm::SegmentOwner owner;
+    owner.segment_id = UuidToString(segment.id);
+    owner.owner_master_id = master_id_;
+    owner.state = static_cast<int32_t>(cvm::SegmentOwnerState::kStable);
+
+    // Bind to the supervisor-owned CvmController's lease so segment ownership
+    // is auto-removed when this master dies; fall back to a persistent record
+    // when no lease has been injected yet.
+    ErrorCode err;
+    if (cvm_lease_id_ != 0) {
+        err = cvm::EtcdViewStore::SaveSegmentOwnerWithLease(cluster_id_, owner,
+                                                            cvm_lease_id_);
+    } else {
+        err = cvm::EtcdViewStore::SaveSegmentOwner(cluster_id_, owner);
+    }
+    if (err != ErrorCode::OK) {
+        LOG(WARNING) << "PublishSegmentOwnerForCvm SaveSegmentOwner failed: "
+                        "segment="
+                     << owner.segment_id << " err=" << err;
+    }
+}
+
+void MasterService::RemoveSegmentOwnerForCvm(const UUID& segment_id) {
+    if (!enable_ha_ || ha_backend_type_ != "etcd" || master_id_.empty() ||
+        cluster_id_.empty()) {
+        return;
+    }
+    const std::string id = UuidToString(segment_id);
+    ErrorCode err = cvm::EtcdViewStore::DeleteSegmentOwner(cluster_id_, id);
+    if (err != ErrorCode::OK) {
+        LOG(WARNING) << "RemoveSegmentOwnerForCvm DeleteSegmentOwner failed: "
+                        "segment="
+                     << id << " err=" << err;
+    }
+}
+
+std::vector<uint16_t> MasterService::ResolveOwnedSlotsForCvm() {
+    // etcd 读取失败：sticky 策略——沿用上一轮成功解析的结果（可能为空）。
+    // 绝不回退为全量接管：瞬时抖动引发的全量认领会与对端产生覆盖战
+    // （双方反复重写对方 slot 记录，导致 slot 分布持续震荡不收敛）。
+    std::vector<cvm::MasterRegistration> masters;
+    ViewVersionId version;
+    ErrorCode err =
+        cvm::EtcdViewStore::LoadAllMasters(cluster_id_, masters, version);
+    if (err != ErrorCode::OK) {
+        std::lock_guard<std::mutex> lock(cvm_resolver_mutex_);
+        LOG(WARNING) << "ResolveOwnedSlotsForCvm: LoadAllMasters failed: "
+                     << err << ", keeping previous owned set (sticky), count="
+                     << cvm_last_resolved_owned_slots_.size();
+        return cvm_last_resolved_owned_slots_;
+    }
+
+    std::vector<std::string> ids;
+    ids.reserve(masters.size());
+    for (const auto& m : masters) {
+        // Only serving primaries own slots. Standbys do not publish slot
+        // ownership, so including them would strand part of the slot space.
+        if (static_cast<cvm::MasterRole>(m.role) != cvm::MasterRole::kPrimary) {
+            continue;
+        }
+        if (!m.master_id.empty()) {
+            ids.push_back(m.master_id);
+        }
+    }
+    std::sort(ids.begin(), ids.end());
+    ids.erase(std::unique(ids.begin(), ids.end()), ids.end());
+
+    // etcd 注册表是唯一事实源：本机必须已注册为 primary 才参与分配。
+    // 不再无条件注入本机 master_id——否则任一节点视图缺失对端时都会以
+    // n==1 身份全量接管，是 slot 覆盖战的直接根源。
+    const bool self_registered =
+        std::binary_search(ids.begin(), ids.end(), master_id_);
+    std::vector<uint16_t> slots;
+    if (self_registered) {
+        // 技术债 3.1：一致性哈希环分配已提取到 cvm::ResolveOwnedSlotsOnRing
+        // 纯函数（可单元测试），本机 owned slots 由 (ids, master_id_) 决定。
+        slots = cvm::ResolveOwnedSlotsOnRing(ids, master_id_);
+    } else {
+        LOG(WARNING) << "ResolveOwnedSlotsForCvm: self not registered as "
+                        "primary in etcd (masters="
+                     << ids.size() << "), owning no slots this cycle";
+    }
+
+    {
+        std::lock_guard<std::mutex> lock(cvm_resolver_mutex_);
+        cvm_last_resolved_owned_slots_ = slots;
+    }
+    return slots;
+}
+
+std::optional<std::string> MasterService::ResolveSlotOwnerMasterId(
+    uint16_t slot) const {
+    std::vector<cvm::MasterRegistration> masters;
+    ViewVersionId version;
+    ErrorCode err =
+        cvm::EtcdViewStore::LoadAllMasters(cluster_id_, masters, version);
+    if (err != ErrorCode::OK) {
+        LOG(WARNING) << "ResolveSlotOwnerMasterId: LoadAllMasters failed: "
+                     << err << ", slot=" << slot;
+        return std::nullopt;
+    }
+
+    std::vector<std::string> ids;
+    ids.reserve(masters.size());
+    for (const auto& m : masters) {
+        if (static_cast<cvm::MasterRole>(m.role) != cvm::MasterRole::kPrimary) {
+            continue;
+        }
+        if (!m.master_id.empty()) {
+            ids.push_back(m.master_id);
+        }
+    }
+    std::sort(ids.begin(), ids.end());
+    ids.erase(std::unique(ids.begin(), ids.end()), ids.end());
+
+    // 与 ResolveOwnedSlotsForCvm 保持一致：纯粹以 etcd 注册表计算环，
+    // 不注入本机 master_id，保证所有权判定与认领发布使用同一个环。
+    // 解析结果为空（注册表无 primary）时由调用方跳过转发。
+    return cvm::ResolveSlotOwnerOnRing(ids, slot);
+}
+#else
+void MasterService::PublishSegmentOwnerForCvm(const Segment&) {}
+void MasterService::RemoveSegmentOwnerForCvm(const UUID&) {}
+std::vector<uint16_t> MasterService::ResolveOwnedSlotsForCvm() { return {}; }
+std::optional<std::string> MasterService::ResolveSlotOwnerMasterId(
+    uint16_t /*slot*/) const {
+    return std::nullopt;
+}
 #endif
+
+void MasterService::UpdateOwnedSlots(const std::vector<uint16_t>& slots) {
+    std::unique_lock<std::shared_mutex> lock(owned_slots_mutex_);
+    owned_slot_lookup_.assign(cvm::kSlotCount, false);
+    for (uint16_t slot : slots) {
+        if (slot < cvm::kSlotCount) {
+            owned_slot_lookup_[slot] = true;
         }
     }
+    owned_slots_ready_ = true;
+    // 一致性哈希环分配结果（3.1）：仅在数量变化（含首次解析）时打印，
+    // 记录本机当前负责的 slot 规模；心跳周期内重复不变则静默。
+    if (!owned_slot_count_logged_ || slots.size() != last_logged_owned_count_) {
+        LOG(INFO) << "Owned slots updated (consistent-hash ring): count="
+                  << slots.size() << "/" << cvm::kSlotCount
+                  << (owned_slot_count_logged_ ? " (changed)" : "");
+        owned_slot_count_logged_ = true;
+        last_logged_owned_count_ = slots.size();
+    }
+    VLOG(1) << "UpdateOwnedSlots: " << slots.size() << " slots";
+}
 
-    throw std::invalid_argument("unknown snapshot catalog store type");
+bool MasterService::OwnsSlot(uint16_t slot) const {
+    std::shared_lock<std::shared_mutex> lock(owned_slots_mutex_);
+    if (!owned_slots_ready_) {
+        return true;  // partition 未启用或尚未解析过，放行
+    }
+    return slot < owned_slot_lookup_.size() && owned_slot_lookup_[slot];
+}
+
+bool MasterService::OwnsVChunkSlot(uint16_t slot) const {
+    std::shared_lock<std::shared_mutex> lock(owned_slots_mutex_);
+    if (!owned_slots_ready_) {
+        const bool partitioned =
+            enable_ha_ && ha_backend_type_ == "etcd" && submaster_count_ > 1;
+        return !partitioned;
+    }
+    return slot < owned_slot_lookup_.size() && owned_slot_lookup_[slot];
 }
 
 MasterService::~MasterService() {
@@ -571,6 +1878,10 @@ MasterService::~MasterService() {
         ordered_oplog_writer_->Stop();
     }
 
+    // Stop the SlotOwnerHeartbeat thread before tearing down the rest.
+    StopSlotOwnerHeartbeat();
+    StopInterMasterRpc();
+
     // Stop and join the threads
     eviction_running_ = false;
     client_monitor_running_ = false;
@@ -583,6 +1894,7 @@ MasterService::~MasterService() {
     task_cleanup_running_ = false;
     job_dispatch_running_ = false;
     http_metadata_cleanup_running_ = false;
+    vchunk_reaper_running_ = false;
     graceful_unmount_scheduler_.Stop();
 #ifdef USE_NOF
     nof_heartbeat_running_ = false;
@@ -591,6 +1903,7 @@ MasterService::~MasterService() {
     // Wake sleepers so join() doesn't block for long sleep intervals.
     task_cleanup_cv_.notify_all();
     http_metadata_cleanup_cv_.notify_all();
+    vchunk_reaper_cv_.notify_all();
 
     if (eviction_thread_.joinable()) {
         eviction_thread_.join();
@@ -612,6 +1925,16 @@ MasterService::~MasterService() {
     if (job_dispatch_thread_.joinable()) {
         job_dispatch_thread_.join();
     }
+    if (vchunk_reaper_thread_.joinable()) {
+        vchunk_reaper_thread_.join();
+    }
+
+    // Its admission worker executes handlers that capture this service. Stop
+    // and join it while all handler dependencies are still alive.
+    MasterMetricManager::instance().clear_io_pattern_runtime(
+        io_pattern_runtime_.get());
+    io_pattern_cfm_service_.reset();
+    io_pattern_runtime_.reset();
 
     // Reset snapshot manager after all other threads have joined
     // This triggers the destructor which joins the snapshot thread
@@ -833,7 +2156,27 @@ auto MasterService::MountSegment(const Segment& segment, const UUID& client_id)
         }
     }
 
-    if (enable_oplog_ && ordered_oplog_writer_) {
+    // 幂等重挂载（segment 已存在）同样要把 client 标记为 OK：Ping 仅凭
+    // ok_client_ 判定 client_status，若此处不标记，HeartbeatAllSubmasters
+    // 收到 NEED_REMOUNT 后用普通 mount 重挂永远无法消除该状态，形成
+    // 每秒一次的 remount 死循环（并持续写 OpLog/segment_view）。
+    // 注意：必须在 segment 访问释放之后再加 client_mutex_，避免与
+    // ClientMonitorFunc 的 client_mutex_ -> segment access 加锁顺序倒挂。
+    if (mount_result == ErrorCode::SEGMENT_ALREADY_EXISTS) {
+        std::unique_lock<std::shared_mutex> client_lock(client_mutex_);
+        if (ok_client_.find(client_id) == ok_client_.end()) {
+            ok_client_.insert(client_id);
+            MasterMetricManager::instance().inc_active_clients();
+            LOG(INFO) << "client_id=" << client_id
+                      << ", action=mount_segment_idempotent_ok"
+                      << ", segment_name=" << segment.name;
+        }
+    }
+
+    // 幂等重挂载不产生新的元数据变更，segment 首次挂载时已记录
+    // SEGMENT_MOUNT OpLog，重复追加只会让 OpLog 无谓增长。
+    if (enable_oplog_ && ordered_oplog_writer_ &&
+        mount_result != ErrorCode::SEGMENT_ALREADY_EXISTS) {
         SegmentMountOp op;
         op.segment_name = segment.name;
         op.transport_endpoint = segment.te_endpoint;
@@ -849,6 +2192,7 @@ auto MasterService::MountSegment(const Segment& segment, const UUID& client_id)
     if (mount_result == ErrorCode::OK) {
         RecomputeTenantEffectiveQuotas();
     }
+    PublishSegmentOwnerForCvm(segment);
     return {};
 }
 
@@ -1226,6 +2570,10 @@ auto MasterService::ReMountSegment(const std::vector<Segment>& segments,
     }
     RecomputeTenantEffectiveQuotas();
 
+    for (const auto& seg : segments) {
+        PublishSegmentOwnerForCvm(seg);
+    }
+
     return {};
 }
 
@@ -1975,8 +3323,8 @@ auto RetryOplogPersist(F&& persist_fn) -> decltype(std::declval<F>()()) {
             // KV backend. Recovery depends on the backend; bail out
             // earlier to avoid spinning on a persistent outage.
             if (attempt >= kOplogRetryMaxAttemptsUnavailable) {
-                LOG(WARNING) << "Oplog writer not accepting after "
-                             << attempt << " retries, falling back to local";
+                LOG(WARNING) << "Oplog writer not accepting after " << attempt
+                             << " retries, falling back to local";
                 return result;
             }
             std::this_thread::sleep_for(std::chrono::milliseconds(
@@ -2054,10 +3402,15 @@ MasterService::EraseMetadata(
     tenant_state.replication_tasks.erase(key);
     ErasePromotionTaskIfPresent(tenant_state, key, tenant_id);
 
-    ReleaseLocalDiskUsage(metadata.GetAllReplicas());
+    // kHandoff 跳过 ReleaseLocalDiskUsage：数据字节仍留在共享 segment，
+    // 不应在此扣减 ssd_used_bytes（否则造成账务偏差）。
+    if (quota_mode != QuotaEraseMode::kHandoff) {
+        ReleaseLocalDiskUsage(metadata.GetAllReplicas());
+    }
     AccountCacheTotalRemoval(metadata);
     switch (quota_mode) {
         case QuotaEraseMode::kFull:
+        case QuotaEraseMode::kHandoff:
             AbortTenantQuota(tenant_id, metadata.reserved_quota_charge_bytes);
             ReleaseTenantQuota(tenant_id,
                                metadata.committed_quota_charge_bytes);
@@ -2071,6 +3424,10 @@ MasterService::EraseMetadata(
             AbortTenantQuota(tenant_id, metadata.reserved_quota_charge_bytes);
             break;
     }
+    // CVM 多 submaster：若该对象的句柄由 peer 分配（远程分配/迁移入），
+    // 广播释放到所有 peer 的 keepalive 注册表；kHandoff（slot 迁移）跳过，
+    // 保留数据字节并让导入方接管远程释放责任。
+    EnqueueRemoteFreeIfTracked(tenant_id, key, quota_mode);
     auto next = tenant_state.metadata.erase(it);
     DecrementTenantMetadataObjectCount(tenant_id);
     if (had_completed_disk && shard) {
@@ -2196,13 +3553,11 @@ void MasterService::ClearInvalidHandles(
                 if (!cleanup_plan.removed_ids.empty()) {
                     if (enable_ha_) {
                         if (enable_oplog_) {
-                            auto persist_result =
-                                RetryOplogPersist([&]() {
-                                    return PersistStaleHandleCleanupForHA(
-                                        "ClearInvalidHandles",
-                                        tenant_it->first, it->first,
-                                        it->second, cleanup_plan);
-                                });
+                            auto persist_result = RetryOplogPersist([&]() {
+                                return PersistStaleHandleCleanupForHA(
+                                    "ClearInvalidHandles", tenant_it->first,
+                                    it->first, it->second, cleanup_plan);
+                            });
                             if (persist_result) {
                                 ++it;
                                 continue;
@@ -2219,19 +3574,16 @@ void MasterService::ClearInvalidHandles(
                 } else if (!it->second.IsValid()) {
                     if (enable_ha_) {
                         if (enable_oplog_) {
-                            auto persist_result =
-                                RetryOplogPersist([&]() {
-                                    return AppendOpLogWithDurableFinalize(
-                                        OpType::REMOVE,
-                                        tenant_it->first.value(),
-                                        it->first, {},
-                                        [this](
-                                            const OpLogEntry& durable_entry) {
-                                            FinalizeMetadataEraseAfterDurable(
-                                                durable_entry,
-                                                QuotaEraseMode::kFull);
-                                        });
-                                });
+                            auto persist_result = RetryOplogPersist([&]() {
+                                return AppendOpLogWithDurableFinalize(
+                                    OpType::REMOVE, tenant_it->first.value(),
+                                    it->first, {},
+                                    [this](const OpLogEntry& durable_entry) {
+                                        FinalizeMetadataEraseAfterDurable(
+                                            durable_entry,
+                                            QuotaEraseMode::kFull);
+                                    });
+                            });
                             if (persist_result) {
                                 // OPLog path succeeded – skip local erase.
                                 ++it;
@@ -2335,13 +3687,13 @@ auto MasterService::UnmountSegment(const UUID& segment_id,
                                        std::string(bytes.begin(), bytes.end()));
     }
     RecomputeTenantEffectiveQuotas();
+    RemoveSegmentOwnerForCvm(segment_id);
     return {};
 }
 
-auto MasterService::GracefulUnmountSegment(const UUID& segment_id,
-                                           const UUID& client_id,
-                                           uint64_t grace_period_ms)
-    -> tl::expected<void, ErrorCode> {
+auto MasterService::GracefulUnmountSegment(
+    const UUID& segment_id, const UUID& client_id,
+    uint64_t grace_period_ms) -> tl::expected<void, ErrorCode> {
     std::unique_lock<std::shared_mutex> lock(snapshot_mutex_);
     ScopedSegmentAccess segment_access = segment_manager_.getSegmentAccess();
 
@@ -2680,6 +4032,30 @@ void MasterService::RestoreFromStandbySnapshot(
 
     std::unordered_map<size_t, std::vector<const StandbyObjectEntry*>>
         objects_by_shard;
+
+    // P4：晋升时只物化「本机负责 slot」的对象元数据（数据字节留在 segment）。
+    // 仅在 etcd HA 动态分区下过滤；非 HA / 单机 / 测试路径 lookup 为空，退化
+    // 为恢复全部。ResolveOwnedSlotsForCvm 失败时 sticky 沿用上一轮结果
+    // （standby 晋升前为空 → 全量恢复），同样等价于不过滤。
+    std::vector<bool> owned_slot_lookup;
+    {
+        const bool kv_partition_enabled =
+            enable_ha_ && ha_backend_type_ == "etcd" && !master_id_.empty() &&
+            !cluster_id_.empty();
+        if (kv_partition_enabled) {
+            const std::vector<uint16_t> owned_slots = ResolveOwnedSlotsForCvm();
+            if (!owned_slots.empty()) {
+                owned_slot_lookup.assign(cvm::kSlotCount, false);
+                for (uint16_t slot : owned_slots) {
+                    owned_slot_lookup[slot] = true;
+                }
+                // 同步到读路径 owned-slot 位图（A1），让新 primary 立即按
+                // 最新分区拒绝非本机 slot 的读请求。
+                UpdateOwnedSlots(owned_slots);
+            }
+        }
+    }
+
     for (const auto& entry : objects) {
         auto [tenant_id, user_key] = resolve_standby_object(entry);
         if (!tenant_id.IsValid()) {
@@ -2688,6 +4064,13 @@ void MasterService::RestoreFromStandbySnapshot(
                          << ", skipping";
             continue;
         }
+        // slot 过滤：只物化本机负责 slot 的元数据（P4 元数据迁移）。
+        if (!owned_slot_lookup.empty()) {
+            const uint16_t slot = cvm::KeySlot(tenant_id, user_key);
+            if (!owned_slot_lookup[slot]) {
+                continue;
+            }
+        }
         const auto shard_idx = entry.metadata.group_id.empty()
                                    ? getShardIndex(tenant_id, user_key)
                                    : getShardIndex(entry.metadata.group_id);
@@ -3172,8 +4555,7 @@ auto MasterService::GetOffloadEndpoints()
                     [&unique_endpoints](const Replica& replica) {
                         const auto desc = replica.get_descriptor();
                         const auto& endpoint =
-                            desc.get_local_disk_descriptor()
-                                .transport_endpoint;
+                            desc.get_local_disk_descriptor().transport_endpoint;
                         if (!endpoint.empty()) {
                             unique_endpoints.emplace(endpoint);
                         }
@@ -3193,11 +4575,48 @@ auto MasterService::GetOffloadEndpoints()
 auto MasterService::GetReplicaList(const std::string& key,
                                    const TenantId& tenant_id)
     -> tl::expected<GetReplicaListResponse, ErrorCode> {
-    std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
     const auto object_id = MakeObjectIdentityForRequest(key, tenant_id);
 
+    // A1：读路径 slot 所有权校验。分区重均衡后本机不再负责该 slot 时，先
+    // 尝试向 slot owner 转发（方案 B 第二阶段）；转发失败再回退到
+    // SLOT_NOT_OWNED 让客户端根据最新 slot→master 视图重新路由。
+    const uint16_t slot = cvm::KeySlot(object_id.tenant_id, object_id.user_key);
+    if (!OwnsSlot(slot)) {
+#ifdef STORE_USE_ETCD
+        auto owner = ResolveSlotOwnerMasterId(slot);
+        if (owner && !owner->empty() && *owner != master_id_ &&
+            inter_master_rpc_) {
+            auto result = inter_master_rpc_->GetReplicaList(
+                *owner, key, object_id.tenant_id.value());
+            if (result.has_value()) {
+                LOG(INFO) << "GetReplicaList forwarded: key=" << key
+                          << " slot=" << slot << " -> owner=" << *owner;
+                return result;
+            }
+            VLOG(1) << "GetReplicaList forward failed: key=" << key
+                    << " owner=" << *owner
+                    << " error=" << toString(result.error());
+        }
+#endif
+        LOG(WARNING) << "GetReplicaList: key=" << key << " slot=" << slot
+                     << " not owned by this master and forwarding failed, "
+                        "rejecting with SLOT_NOT_OWNED (client should "
+                        "re-route)";
+        return tl::make_unexpected(ErrorCode::SLOT_NOT_OWNED);
+    }
+
+    return GetReplicaListLocal(object_id);
+}
+
+auto MasterService::GetReplicaListLocal(const ObjectIdentity& object_id)
+    -> tl::expected<GetReplicaListResponse, ErrorCode> {
+    std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
+    const std::string& key = object_id.user_key;
+
     GetReplicaListResponse resp({}, default_kv_lease_ttl_);
     bool promotion_eligible = false;
+    io_pattern::AccessRecord io_access;
+    bool record_io_access = false;
     {
         MetadataAccessorRO accessor(this, object_id);
 
@@ -3275,11 +4694,31 @@ auto MasterService::GetReplicaList(const std::string& key,
         resp = GetReplicaListResponse(std::move(replica_list),
                                       default_kv_lease_ttl_,
                                       metadata.object_checksum);
+        io_access.object = {object_id.tenant_id, key};
+        io_access.observed_at_ns = static_cast<uint64_t>(
+            std::chrono::duration_cast<std::chrono::nanoseconds>(
+                std::chrono::steady_clock::now().time_since_epoch())
+                .count());
+        io_access.block_size = metadata.size;
+        // LOCAL_DISK is reported as its own tier: it is the only tier the store
+        // can promote from, and collapsing it into kL3NofSsd made local-disk and
+        // NoF-only objects indistinguishable to the policy.
+        io_access.tier = resp.replicas[0].is_memory_replica()
+                             ? io_pattern::CacheTier::kL1Host
+                             : (resp.replicas[0].is_local_disk_replica()
+                                    ? io_pattern::CacheTier::kLocalDisk
+                                    : io_pattern::CacheTier::kL3NofSsd);
+        io_access.operation = io_pattern::IoOperation::kGet;
+        io_access.is_hit = true;
+        record_io_access = true;
     }
     // RO accessor released. Safe to take a fresh RW accessor now.
     if (promotion_eligible) {
         TryPushPromotionQueue(object_id);
     }
+    if (record_io_access && io_pattern_runtime_) {
+        io_pattern_runtime_->RecordAccess(key, io_access);
+    }
     return resp;
 }
 
@@ -3327,6 +4766,78 @@ MasterService::BatchGetReplicaList(const std::vector<std::string>& keys,
         return results;
     }
 
+    const TenantId& normalized_tenant = ResolveRequestTenantId(tenant_id);
+
+    // A1 + 方案 B 第二阶段：先按 slot 所有权把 keys 拆成「本地组」与
+    // 「转发组（按 owner master_id 分组）」。本地组走本地批量查询，转发组
+    // 通过 InterMasterRpcClient 转发给对应 slot owner。
+    std::vector<size_t> local_indices;
+    std::map<std::string, std::vector<size_t>> forward_groups;
+    for (size_t i = 0; i < keys.size(); ++i) {
+        const uint16_t slot = cvm::KeySlot(normalized_tenant, keys[i]);
+        if (OwnsSlot(slot)) {
+            local_indices.push_back(i);
+            continue;
+        }
+#ifdef STORE_USE_ETCD
+        auto owner = ResolveSlotOwnerMasterId(slot);
+        if (owner && !owner->empty() && *owner != master_id_ &&
+            inter_master_rpc_) {
+            forward_groups[*owner].push_back(i);
+            continue;
+        }
+#endif
+        LOG(WARNING) << "BatchGetReplicaList: key=" << keys[i]
+                     << " slot=" << slot
+                     << " not owned by this master and no forward target, "
+                        "rejecting with SLOT_NOT_OWNED";
+        results[i] = tl::make_unexpected(ErrorCode::SLOT_NOT_OWNED);
+    }
+
+    if (!local_indices.empty()) {
+        std::vector<std::string> local_keys;
+        local_keys.reserve(local_indices.size());
+        for (size_t idx : local_indices) {
+            local_keys.push_back(keys[idx]);
+        }
+        auto local_results =
+            BatchGetReplicaListLocal(local_keys, normalized_tenant);
+        for (size_t j = 0; j < local_indices.size(); ++j) {
+            results[local_indices[j]] = std::move(local_results[j]);
+        }
+    }
+
+#ifdef STORE_USE_ETCD
+    for (const auto& [owner, indices] : forward_groups) {
+        std::vector<std::string> group_keys;
+        group_keys.reserve(indices.size());
+        for (size_t idx : indices) {
+            group_keys.push_back(keys[idx]);
+        }
+        auto group_result = inter_master_rpc_->BatchGetReplicaList(
+            owner, group_keys, normalized_tenant.value());
+        for (size_t j = 0; j < indices.size() && j < group_result.size(); ++j) {
+            results[indices[j]] = std::move(group_result[j]);
+        }
+    }
+#endif
+
+    return results;
+}
+
+std::vector<tl::expected<GetReplicaListResponse, ErrorCode>>
+MasterService::BatchGetReplicaListLocal(const std::vector<std::string>& keys,
+                                        const TenantId& tenant_id) {
+    using GetResult = tl::expected<GetReplicaListResponse, ErrorCode>;
+
+    assert(tenant_id.IsValid());
+
+    std::vector<GetResult> results(
+        keys.size(), tl::make_unexpected(ErrorCode::OBJECT_NOT_FOUND));
+    if (keys.empty()) {
+        return results;
+    }
+
     const TenantId& normalized_tenant = ResolveRequestTenantId(tenant_id);
     constexpr size_t kInvalidKeyIndex = std::numeric_limits<size_t>::max();
     std::array<size_t, kNumShards> key_list_heads;
@@ -3357,6 +4868,7 @@ MasterService::BatchGetReplicaList(const std::vector<std::string>& keys,
         }
 
         std::vector<ObjectIdentity> promotion_candidates;
+        std::vector<io_pattern::AccessRecord> io_accesses;
         std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
         {
             MetadataShardAccessorRO shard(this, shard_idx);
@@ -3365,6 +4877,7 @@ MasterService::BatchGetReplicaList(const std::vector<std::string>& keys,
                  original_idx != kInvalidKeyIndex;
                  original_idx = next_key_indexes[original_idx]) {
                 const std::string& key = keys[original_idx];
+
                 MasterMetricManager::instance().inc_total_get_nums();
 
                 if (tenant_it == shard->tenants.end()) {
@@ -3436,12 +4949,35 @@ MasterService::BatchGetReplicaList(const std::vector<std::string>& keys,
                 results[original_idx] = GetReplicaListResponse(
                     std::move(replica_list), default_kv_lease_ttl_,
                     metadata.object_checksum);
+                io_accesses.push_back(
+                    {.object = {normalized_tenant, key},
+                     .observed_at_ns = static_cast<uint64_t>(
+                         std::chrono::duration_cast<std::chrono::nanoseconds>(
+                             std::chrono::steady_clock::now()
+                                 .time_since_epoch())
+                             .count()),
+                     .block_size = metadata.size,
+                     .tier =
+                         results[original_idx]->replicas[0].is_memory_replica()
+                             ? io_pattern::CacheTier::kL1Host
+                             : (results[original_idx]
+                                        ->replicas[0]
+                                        .is_local_disk_replica()
+                                    ? io_pattern::CacheTier::kLocalDisk
+                                    : io_pattern::CacheTier::kL3NofSsd),
+                     .operation = io_pattern::IoOperation::kGet,
+                     .is_hit = true});
             }
         }
 
         for (const auto& object_id : promotion_candidates) {
             TryPushPromotionQueue(object_id);
         }
+        if (io_pattern_runtime_) {
+            for (const auto& access : io_accesses) {
+                io_pattern_runtime_->RecordAccess(access.object.key, access);
+            }
+        }
     }
 
     return results;
@@ -3578,84 +5114,108 @@ auto MasterService::AllocateAndInsertMetadata(
                                                     : config.host_id;
         }
 
-        ScopedAllocatorAccess allocator_access =
-            segment_manager_.getAllocatorAccess();
-        const auto& allocator_manager = allocator_access.getAllocatorManager();
-        if (allocator_manager.getNames().size() >= config.replica_num) {
-            for (const auto& name : allocator_manager.getNames()) {
-                const auto* allocators = allocator_manager.getAllocators(name);
-                if (allocators != nullptr &&
-                    std::any_of(allocators->begin(), allocators->end(),
-                                [](const auto& allocator) {
-                                    return allocator && allocator->size() > 0;
-                                })) {
-                    memory_eviction_may_help = true;
-                    break;
+        std::vector<std::string> preferred_segments;
+        tl::expected<std::vector<Replica>, ErrorCode> allocation_result =
+            tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
+        {
+            ScopedAllocatorAccess allocator_access =
+                segment_manager_.getAllocatorAccess();
+            const auto& allocator_manager =
+                allocator_access.getAllocatorManager();
+            if (allocator_manager.getNames().size() >= config.replica_num) {
+                for (const auto& name : allocator_manager.getNames()) {
+                    const auto* allocators =
+                        allocator_manager.getAllocators(name);
+                    if (allocators != nullptr &&
+                        std::any_of(allocators->begin(), allocators->end(),
+                                    [](const auto& allocator) {
+                                        return allocator &&
+                                               allocator->size() > 0;
+                                    })) {
+                        memory_eviction_may_help = true;
+                        break;
+                    }
                 }
             }
-        }
 
-        std::vector<std::string> preferred_segments;
-        auto append_preferred_segment = [&preferred_segments](
-                                            const std::string& segment_name) {
-            if (!segment_name.empty() &&
-                std::find(preferred_segments.begin(), preferred_segments.end(),
-                          segment_name) == preferred_segments.end()) {
-                preferred_segments.push_back(segment_name);
-            }
-        };
-        if (!config.preferred_segment.empty()) {
-            append_preferred_segment(config.preferred_segment);
-        } else {
-            for (const auto& preferred_segment : config.preferred_segments) {
-                append_preferred_segment(preferred_segment);
-            }
-        }
-        if (!writer_host_id.empty()) {
-            auto host_ordered_segments =
-                allocator_access.GetHostOrderedSegments(writer_host_id, key);
-            for (const auto& segment_name : host_ordered_segments) {
-                append_preferred_segment(segment_name);
+            auto append_preferred_segment =
+                [&preferred_segments](const std::string& segment_name) {
+                    if (!segment_name.empty() &&
+                        std::find(preferred_segments.begin(),
+                                  preferred_segments.end(),
+                                  segment_name) == preferred_segments.end()) {
+                        preferred_segments.push_back(segment_name);
+                    }
+                };
+            if (!config.preferred_segment.empty()) {
+                append_preferred_segment(config.preferred_segment);
+            } else {
+                for (const auto& preferred_segment :
+                     config.preferred_segments) {
+                    append_preferred_segment(preferred_segment);
+                }
             }
-            if (!host_ordered_segments.empty()) {
-                VLOG(1) << "key=" << key
-                        << ", writer_host_id=" << writer_host_id
-                        << ", local_first_preferred_segments="
-                        << host_ordered_segments.size();
+            if (!writer_host_id.empty()) {
+                auto host_ordered_segments =
+                    allocator_access.GetHostOrderedSegments(writer_host_id,
+                                                            key);
+                for (const auto& segment_name : host_ordered_segments) {
+                    append_preferred_segment(segment_name);
+                }
+                if (!host_ordered_segments.empty()) {
+                    VLOG(1) << "key=" << key
+                            << ", writer_host_id=" << writer_host_id
+                            << ", local_first_preferred_segments="
+                            << host_ordered_segments.size();
+                }
             }
-        }
 
-        const SsdMetricsProvider* ssd_provider = nullptr;
-        std::optional<ScopedLocalDiskSegmentAccess> ssd_access;
-        if (allocation_strategy_type_ ==
-            AllocationStrategyType::SSD_FREE_RATIO_FIRST) {
-            ssd_access.emplace(segment_manager_.getLocalDiskSegmentAccess());
-            ssd_provider = &*ssd_access;
-        }
+            const SsdMetricsProvider* ssd_provider = nullptr;
+            std::optional<ScopedLocalDiskSegmentAccess> ssd_access;
+            if (allocation_strategy_type_ ==
+                AllocationStrategyType::SSD_FREE_RATIO_FIRST) {
+                ssd_access.emplace(
+                    segment_manager_.getLocalDiskSegmentAccess());
+                ssd_provider = &*ssd_access;
+            }
 
-        SpDiag::PerfPoint pt_alloc_mem(PerfKey::MASTER_PUT_ALLOCATE_MEM,
-                                       SpDiag::PerfLevel::KEY_MODULE);
-        pt_alloc_mem.Start();
-        auto allocation_result = allocation_strategy_->Allocate(
-            allocator_manager, value_length, config.replica_num,
-            preferred_segments, std::set<std::string>(), ReplicaType::MEMORY,
-            ssd_provider);
-        pt_alloc_mem.End(allocation_result.has_value() ? 0 : -1);
+            SpDiag::PerfPoint pt_alloc_mem(PerfKey::MASTER_PUT_ALLOCATE_MEM,
+                                           SpDiag::PerfLevel::KEY_MODULE);
+            pt_alloc_mem.Start();
+            allocation_result = allocation_strategy_->Allocate(
+                allocator_manager, value_length, config.replica_num,
+                preferred_segments, std::set<std::string>(),
+                ReplicaType::MEMORY, ssd_provider);
+            pt_alloc_mem.End(allocation_result.has_value() ? 0 : -1);
+        }  // allocator_access 在此释放；远程转发在锁外执行，避免分布式死锁
 
         if (!allocation_result.has_value()) {
-            VLOG(1) << "Failed to allocate replicas for key=" << key
+            VLOG(1) << "Failed to allocate replicas locally for key=" << key
                     << ", error: " << allocation_result.error();
-            if (allocation_result.error() == ErrorCode::INVALID_PARAMS) {
-                abort_reserved_quota();
-                return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
-            }
-            if (write_mode != ReplicaWriteMode::FLEXIBLE_DUAL_REPLICA) {
-                MasterMetricManager::instance().inc_put_start_alloc_failures();
-                if (memory_eviction_may_help) {
-                    need_mem_eviction_ = true;
+            // CVM 多 submaster（方案 B 第二阶段）：本机本地分配失败（未挂载
+            // segment 或空间不足）时，尝试向持有该 segment 的 peer submaster
+            // 转发分配。远程分配成功则以 dummy-allocator 副本物化到本机元数据，
+            // 真实句柄留在 segment owner 的 keepalive 注册表中。
+            auto remote_replicas = TryAllocateReplicasRemotely(
+                key, tenant_id, value_length, config.replica_num,
+                preferred_segments);
+            if (remote_replicas.has_value()) {
+                replicas = std::move(remote_replicas.value());
+                allocated_memory_replicas = replicas.size();
+            } else {
+                if (allocation_result.error() == ErrorCode::INVALID_PARAMS) {
+                    abort_reserved_quota();
+                    return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+                }
+                if (write_mode != ReplicaWriteMode::FLEXIBLE_DUAL_REPLICA) {
+                    MasterMetricManager::instance()
+                        .inc_put_start_alloc_failures();
+                    if (memory_eviction_may_help) {
+                        need_mem_eviction_ = true;
+                    }
+                    abort_reserved_quota();
+                    return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
                 }
-                abort_reserved_quota();
-                return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
             }
         } else {
             allocated_memory_replicas = allocation_result->size();
@@ -3832,6 +5392,32 @@ auto MasterService::PutStart(const UUID& client_id, const std::string& key,
 
     UpdateClientHostId(client_id, config.host_id);
 
+#ifdef STORE_USE_ETCD
+    // 写路径 slot 归属校验 + 完整转发（模型 B）：本机若非该 key 的 slot
+    // owner，不得在本地写入元数据（否则元数据落在"非环 owner"上，而读路径
+    // 按环归属，会造成"写后读不到/写到错误位置"的不一致）。此处把整个
+    // PutStart 转发给 slot owner，由其本地分配 + 写元数据并返回 Descriptor。
+    // owner 侧 peer 互信（OwnsSlot==true）不再二次转发，转发链止于第一跳。
+    {
+        const uint16_t slot =
+            cvm::KeySlot(object_id.tenant_id, object_id.user_key);
+        if (!OwnsSlot(slot)) {
+            auto owner = ResolveSlotOwnerMasterId(slot);
+            if (owner && !owner->empty() && *owner != master_id_ &&
+                inter_master_rpc_) {
+                LOG(INFO) << "PutStart forwarded: key=" << object_id.user_key
+                          << " slot=" << slot << " -> owner=" << *owner;
+                return inter_master_rpc_->PutStart(
+                    *owner, client_id, object_id.user_key,
+                    object_id.tenant_id.value(), slice_length, config);
+            }
+            LOG(INFO) << "PutStart rejected with SLOT_NOT_OWNED: key="
+                      << object_id.user_key << " slot=" << slot;
+            return tl::make_unexpected(ErrorCode::SLOT_NOT_OWNED);
+        }
+    }
+#endif
+
     if ((memory_allocator_type_ == BufferAllocatorType::CACHELIB) &&
         (slice_length > kMaxSliceSize)) {
         LOG(ERROR) << "key=" << key << ", slice_length=" << slice_length
@@ -3984,9 +5570,11 @@ auto MasterService::PutStart(const UUID& client_id, const std::string& key,
     return tl::make_unexpected(ErrorCode::TENANT_QUOTA_EXCEEDED);
 }
 
-auto MasterService::PutEnd(const UUID& client_id, const ObjectMeta& object_meta,
-                           const TenantId& tenant_id, ReplicaType replica_type)
-    -> tl::expected<void, ErrorCode> {
+auto MasterService::PutEndInternal(
+    const UUID& client_id, const ObjectMeta& object_meta,
+    const TenantId& tenant_id, ReplicaType replica_type,
+    uint32_t write_batch_size,
+    bool overwrite) -> tl::expected<void, ErrorCode> {
     const auto& key = object_meta.key;
     std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
     const auto object_id = MakeObjectIdentityForRequest(key, tenant_id);
@@ -4054,6 +5642,13 @@ auto MasterService::PutEnd(const UUID& client_id, const ObjectMeta& object_meta,
         metadata.pending_replaced_quota_charge_bytes = 0;
     }
 
+    // Write-through offload legacy path: every completed MEMORY replica is
+    // queued to LOCAL_DISK right after PutEnd. This only runs in legacy mode
+    // (enable_offload=true without offload_on_evict). When offload-on-evict
+    // is enabled the block below is skipped: the new object stays in L1 and
+    // demotion happens at eviction time, where the IO Pattern policy selects
+    // the coldest L1 keys and EvictTenantMemoryForQuota demotes or releases
+    // them (lower-tier-backed keys are preferred victims).
     if (enable_offload_ && !offload_on_evict_) {
         auto& tenant_state = accessor.GetTenantState();
         metadata.VisitReplicas(
@@ -4089,6 +5684,29 @@ auto MasterService::PutEnd(const UUID& client_id, const ObjectMeta& object_meta,
     metadata.GrantLease(0, default_kv_soft_pin_ttl_);
     PublishKvStored(key, replica_type, metadata, object_id.tenant_id);
 
+    if (io_pattern_runtime_) {
+        io_pattern_runtime_->RecordAccess(
+            key, {.object = {object_id.tenant_id, key},
+                  .observed_at_ns = static_cast<uint64_t>(
+                      std::chrono::duration_cast<std::chrono::nanoseconds>(
+                          std::chrono::steady_clock::now().time_since_epoch())
+                          .count()),
+                  .block_size = metadata.size,
+                  .tier = replica_type == ReplicaType::MEMORY
+                              ? io_pattern::CacheTier::kL1Host
+                              : (replica_type == ReplicaType::LOCAL_DISK
+                                     ? io_pattern::CacheTier::kLocalDisk
+                                     : io_pattern::CacheTier::kL3NofSsd),
+                  .operation = io_pattern::IoOperation::kPut,
+                  .is_hit = true,
+                  .write_batch_size = write_batch_size,
+                  .overwrite = overwrite});
+        if (replica_type != ReplicaType::MEMORY) {
+            io_pattern_runtime_->ScheduleAdmission(
+                {object_id.tenant_id, key}, io_pattern::CacheTier::kL1Host);
+        }
+    }
+
     if (enable_oplog_ && ordered_oplog_writer_) {
         std::string payload = SerializeMetadataForOpLog(metadata);
         auto result = AppendOpLogVisibleBeforeDurable(
@@ -4193,10 +5811,10 @@ auto MasterService::AddReplica(const UUID& client_id, const std::string& key,
                 OpType::PUT_END, object_id.tenant_id.value(), key,
                 oplog_payload);
             if (!persist_result) {
-                LOG(WARNING) << "AddReplica: OpLog skipped for local_disk"
-                             << " (metadata already updated), key=" << key
-                             << ", err="
-                             << static_cast<int>(persist_result.error());
+                LOG(WARNING)
+                    << "AddReplica: OpLog skipped for local_disk"
+                    << " (metadata already updated), key=" << key
+                    << ", err=" << static_cast<int>(persist_result.error());
             }
         }
         return true;
@@ -4234,16 +5852,16 @@ auto MasterService::AddReplica(const UUID& client_id, const std::string& key,
         if (!persist_result) {
             LOG(WARNING) << "AddReplica: OpLog skipped for local_disk"
                          << " (metadata already updated), key=" << key
-                         << ", err=" << static_cast<int>(persist_result.error());
+                         << ", err="
+                         << static_cast<int>(persist_result.error());
         }
     }
     return false;
 }
 
-auto MasterService::PutRevoke(const UUID& client_id, const std::string& key,
-                              const TenantId& tenant_id,
-                              ReplicaType replica_type)
-    -> tl::expected<void, ErrorCode> {
+auto MasterService::PutRevoke(
+    const UUID& client_id, const std::string& key, const TenantId& tenant_id,
+    ReplicaType replica_type) -> tl::expected<void, ErrorCode> {
     std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
     const auto object_id = MakeObjectIdentityForRequest(key, tenant_id);
     MetadataAccessorRW accessor(this, object_id);
@@ -4346,6 +5964,13 @@ auto MasterService::PutRevoke(const UUID& client_id, const std::string& key,
     return {};
 }
 
+auto MasterService::PutEnd(const UUID& client_id, const ObjectMeta& object_meta,
+                           const TenantId& tenant_id, ReplicaType replica_type)
+    -> tl::expected<void, ErrorCode> {
+    return PutEndInternal(client_id, object_meta, tenant_id, replica_type,
+                          /*write_batch_size=*/1, /*overwrite=*/false);
+}
+
 auto MasterService::PutEnd(const UUID& client_id, const std::string& key,
                            const TenantId& tenant_id, ReplicaType replica_type)
     -> tl::expected<void, ErrorCode> {
@@ -4360,8 +5985,11 @@ std::vector<tl::expected<void, ErrorCode>> MasterService::BatchPutEnd(
     std::vector<tl::expected<void, ErrorCode>> results;
     results.reserve(object_metas.size());
     for (const auto& object_meta : object_metas) {
-        results.emplace_back(
-            PutEnd(client_id, object_meta, tenant_id, replica_type));
+        results.emplace_back(PutEndInternal(
+            client_id, object_meta, tenant_id, replica_type,
+            static_cast<uint32_t>(std::min<size_t>(
+                object_metas.size(), std::numeric_limits<uint32_t>::max())),
+            /*overwrite=*/false));
     }
     return results;
 }
@@ -4432,6 +6060,31 @@ auto MasterService::UpsertStart(const UUID& client_id, const std::string& key,
 
     UpdateClientHostId(client_id, config.host_id);
 
+#ifdef STORE_USE_ETCD
+    // 写路径 slot 归属校验 + 完整转发（模型 B）：Upsert 为覆盖式写，一旦
+    // client 路由过期把请求发到非 slot owner，错位覆盖比 PutStart 危害更大。
+    // 此处与 PutStart 对称：把整个 UpsertStart 转发给 slot owner 执行。
+    // owner 侧 peer 互信（OwnsSlot==true）不再二次转发，转发链止于第一跳。
+    {
+        const uint16_t slot =
+            cvm::KeySlot(object_id.tenant_id, object_id.user_key);
+        if (!OwnsSlot(slot)) {
+            auto owner = ResolveSlotOwnerMasterId(slot);
+            if (owner && !owner->empty() && *owner != master_id_ &&
+                inter_master_rpc_) {
+                LOG(INFO) << "UpsertStart forwarded: key=" << object_id.user_key
+                          << " slot=" << slot << " -> owner=" << *owner;
+                return inter_master_rpc_->UpsertStart(
+                    *owner, client_id, object_id.user_key,
+                    object_id.tenant_id.value(), slice_length, config);
+            }
+            LOG(INFO) << "UpsertStart rejected with SLOT_NOT_OWNED: key="
+                      << object_id.user_key << " slot=" << slot;
+            return tl::make_unexpected(ErrorCode::SLOT_NOT_OWNED);
+        }
+    }
+#endif
+
     if ((memory_allocator_type_ == BufferAllocatorType::CACHELIB) &&
         (slice_length > kMaxSliceSize)) {
         LOG(ERROR) << "key=" << key << ", slice_length=" << slice_length
@@ -4734,26 +6387,24 @@ auto MasterService::UpsertStart(const UUID& client_id, const std::string& key,
     return tl::make_unexpected(ErrorCode::TENANT_QUOTA_EXCEEDED);
 }
 
-auto MasterService::UpsertEnd(const UUID& client_id,
-                              const ObjectMeta& object_meta,
-                              const TenantId& tenant_id,
-                              ReplicaType replica_type)
-    -> tl::expected<void, ErrorCode> {
-    return PutEnd(client_id, object_meta, tenant_id, replica_type);
+auto MasterService::UpsertEnd(
+    const UUID& client_id, const ObjectMeta& object_meta,
+    const TenantId& tenant_id,
+    ReplicaType replica_type) -> tl::expected<void, ErrorCode> {
+    return PutEndInternal(client_id, object_meta, tenant_id, replica_type,
+                          /*write_batch_size=*/1, /*overwrite=*/true);
 }
 
-auto MasterService::UpsertEnd(const UUID& client_id, const std::string& key,
-                              const TenantId& tenant_id,
-                              ReplicaType replica_type)
-    -> tl::expected<void, ErrorCode> {
+auto MasterService::UpsertEnd(
+    const UUID& client_id, const std::string& key, const TenantId& tenant_id,
+    ReplicaType replica_type) -> tl::expected<void, ErrorCode> {
     return UpsertEnd(client_id, ObjectMeta{key, std::nullopt}, tenant_id,
                      replica_type);
 }
 
-auto MasterService::UpsertRevoke(const UUID& client_id, const std::string& key,
-                                 const TenantId& tenant_id,
-                                 ReplicaType replica_type)
-    -> tl::expected<void, ErrorCode> {
+auto MasterService::UpsertRevoke(
+    const UUID& client_id, const std::string& key, const TenantId& tenant_id,
+    ReplicaType replica_type) -> tl::expected<void, ErrorCode> {
     return PutRevoke(client_id, key, tenant_id, replica_type);
 }
 
@@ -4794,7 +6445,17 @@ MasterService::BatchUpsertStart(const UUID& client_id,
 std::vector<tl::expected<void, ErrorCode>> MasterService::BatchUpsertEnd(
     const UUID& client_id, const std::vector<ObjectMeta>& object_metas,
     const TenantId& tenant_id) {
-    return BatchPutEnd(client_id, object_metas, tenant_id, ReplicaType::ALL);
+    assert(tenant_id.IsValid());
+    std::vector<tl::expected<void, ErrorCode>> results;
+    results.reserve(object_metas.size());
+    const auto batch_size = static_cast<uint32_t>(std::min<size_t>(
+        object_metas.size(), std::numeric_limits<uint32_t>::max()));
+    for (const auto& object_meta : object_metas) {
+        results.emplace_back(PutEndInternal(client_id, object_meta, tenant_id,
+                                            ReplicaType::ALL, batch_size,
+                                            /*overwrite=*/true));
+    }
+    return results;
 }
 
 std::vector<tl::expected<void, ErrorCode>> MasterService::BatchUpsertRevoke(
@@ -4803,11 +6464,9 @@ std::vector<tl::expected<void, ErrorCode>> MasterService::BatchUpsertRevoke(
     return BatchPutRevoke(client_id, keys, tenant_id);
 }
 
-auto MasterService::EvictDiskReplica(const UUID& client_id,
-                                     const std::string& key,
-                                     const TenantId& tenant_id,
-                                     ReplicaType replica_type)
-    -> tl::expected<void, ErrorCode> {
+auto MasterService::EvictDiskReplica(
+    const UUID& client_id, const std::string& key, const TenantId& tenant_id,
+    ReplicaType replica_type) -> tl::expected<void, ErrorCode> {
     const auto object_id = MakeObjectIdentityForRequest(key, tenant_id);
     MetadataAccessorRW accessor(this, object_id);
     if (!accessor.Exists()) {
@@ -5614,9 +7273,7 @@ auto MasterService::Remove(const std::string& key, const TenantId& tenant_id,
     auto& metadata = accessor.Get();
     std::vector<UUID> local_disk_holders;
     metadata.VisitReplicas(
-        [](const Replica& replica) {
-            return replica.is_local_disk_replica();
-        },
+        [](const Replica& replica) { return replica.is_local_disk_replica(); },
         [&local_disk_holders](Replica& replica) {
             auto client_id = replica.get_local_disk_client_id();
             if (client_id.has_value()) {
@@ -5660,15 +7317,13 @@ auto MasterService::Remove(const std::string& key, const TenantId& tenant_id,
             auto persist_result = AppendReservedOpLogWithDurableFinalize(
                 std::move(reservation.value()), OpType::REMOVE,
                 object_id.tenant_id.value(), key, {},
-                [this, removed_ids = std::move(removed_ids),
-                 local_disk_holders,
-                 tenant_id_for_task = object_id.tenant_id.value(), key](
-                    const OpLogEntry& durable_entry) {
+                [this, removed_ids = std::move(removed_ids), local_disk_holders,
+                 tenant_id_for_task = object_id.tenant_id.value(),
+                 key](const OpLogEntry& durable_entry) {
                     FinalizeRemovedReplicasAfterDurable(
                         durable_entry, removed_ids, QuotaEraseMode::kFull);
-                    EnqueueRemoveTasks(
-                        local_disk_holders,
-                        RemoveTaskItem{tenant_id_for_task, key});
+                    EnqueueRemoveTasks(local_disk_holders,
+                                       RemoveTaskItem{tenant_id_for_task, key});
                 });
             if (!persist_result) {
                 return tl::make_unexpected(persist_result.error());
@@ -5683,14 +7338,15 @@ auto MasterService::Remove(const std::string& key, const TenantId& tenant_id,
     accessor.Erase();
 
     // Push removed key to each LOCAL_DISK holder's removed_keys queue.
-    EnqueueRemoveTasks(local_disk_holders, RemoveTaskItem{tenant_id.value(), key});
+    EnqueueRemoveTasks(local_disk_holders,
+                       RemoveTaskItem{tenant_id.value(), key});
 
     return {};
 }
 
 auto MasterService::RemoveByRegex(const std::string& regex_pattern,
-                                  const TenantId& tenant_id, bool force)
-    -> tl::expected<long, ErrorCode> {
+                                  const TenantId& tenant_id,
+                                  bool force) -> tl::expected<long, ErrorCode> {
     assert(tenant_id.IsValid());
     long removed_count = 0;
     std::regex pattern;
@@ -6137,8 +7793,8 @@ auto MasterService::BatchRemove(const std::vector<std::string>& keys,
                             normalized_tenant.value(), key, {},
                             [this, removed_ids = std::move(removed_ids),
                              batch_local_disk_holders,
-                             tenant_id = normalized_tenant.value(), key](
-                                const OpLogEntry& durable_entry) {
+                             tenant_id = normalized_tenant.value(),
+                             key](const OpLogEntry& durable_entry) {
                                 FinalizeRemovedReplicasAfterDurable(
                                     durable_entry, removed_ids,
                                     QuotaEraseMode::kFull);
@@ -6165,9 +7821,8 @@ auto MasterService::BatchRemove(const std::vector<std::string>& keys,
             }
 
             // Push removed key to each LOCAL_DISK holder's removed_keys queue.
-            EnqueueRemoveTasks(
-                batch_local_disk_holders,
-                RemoveTaskItem{normalized_tenant.value(), key});
+            EnqueueRemoveTasks(batch_local_disk_holders,
+                               RemoveTaskItem{normalized_tenant.value(), key});
 
             results[original_idx] = {};  // Success
         }
@@ -6410,8 +8065,8 @@ auto MasterService::RemoveObjectHeartbeat(const UUID& client_id)
     }
 }
 
-void MasterService::EnqueueRemoveTasks(
-    const std::vector<UUID>& holder_ids, const RemoveTaskItem& task) {
+void MasterService::EnqueueRemoveTasks(const std::vector<UUID>& holder_ids,
+                                       const RemoveTaskItem& task) {
     if (holder_ids.empty()) return;
     ScopedLocalDiskSegmentAccess access =
         segment_manager_.getLocalDiskSegmentAccess();
@@ -6421,16 +8076,16 @@ void MasterService::EnqueueRemoveTasks(
         if (it == segments.end()) continue;
         MutexLocker locker(&it->second->offloading_mutex_);
         if (std::find(it->second->removed_keys.begin(),
-                      it->second->removed_keys.end(), task) ==
-            it->second->removed_keys.end()) {
+                      it->second->removed_keys.end(),
+                      task) == it->second->removed_keys.end()) {
             it->second->removed_keys.push_back(task);
         }
     }
 }
 
 auto MasterService::AckRemoveObjectHeartbeat(
-    const UUID& client_id, const std::vector<RemoveTaskItem>& tasks)
-    -> tl::expected<void, ErrorCode> {
+    const UUID& client_id,
+    const std::vector<RemoveTaskItem>& tasks) -> tl::expected<void, ErrorCode> {
     std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
     ScopedLocalDiskSegmentAccess access =
         segment_manager_.getLocalDiskSegmentAccess();
@@ -6444,8 +8099,8 @@ auto MasterService::AckRemoveObjectHeartbeat(
     pending.erase(std::remove_if(pending.begin(), pending.end(),
                                  [&tasks](const RemoveTaskItem& task) {
                                      return std::find(tasks.begin(),
-                                                      tasks.end(), task) !=
-                                            tasks.end();
+                                                      tasks.end(),
+                                                      task) != tasks.end();
                                  }),
                   pending.end());
     return {};
@@ -6530,8 +8185,8 @@ auto MasterService::NotifyOffloadSuccess(
                                          return t.source_client_id == client_id;
                                      });
                     if (offload_it != tasks.end()) {
-                        auto source =
-                            accessor.Get().GetReplicaByID(offload_it->source_id);
+                        auto source = accessor.Get().GetReplicaByID(
+                            offload_it->source_id);
                         if (source != nullptr) {
                             source->dec_refcnt();
                         }
@@ -6601,8 +8256,7 @@ auto MasterService::NotifyOffloadSuccess(
                     size_t updated = obj_metadata.VisitReplicas(
                         [client_id](const Replica& rep) {
                             return rep.type() == ReplicaType::LOCAL_DISK &&
-                                   rep.get_local_disk_client_id() ==
-                                       client_id;
+                                   rep.get_local_disk_client_id() == client_id;
                         },
                         [&metadata](Replica& rep) {
                             rep.update_local_disk_location(
@@ -6639,11 +8293,11 @@ auto MasterService::NotifyOffloadSuccess(
                 if (res.error() == ErrorCode::OBJECT_NOT_FOUND) {
                     continue;
                 }
-                LOG(WARNING) << "Failed to add replica, skipping object: "
-                             << "error=" << res.error()
-                             << ", client_id=" << client_id
-                             << ", tenant_id=" << object_id.tenant_id.value()
-                             << ", key=" << object_id.user_key;
+                LOG(WARNING)
+                    << "Failed to add replica, skipping object: "
+                    << "error=" << res.error() << ", client_id=" << client_id
+                    << ", tenant_id=" << object_id.tenant_id.value()
+                    << ", key=" << object_id.user_key;
                 continue;
             }
             added_new_local_disk_replica = res.value();
@@ -6653,6 +8307,21 @@ auto MasterService::NotifyOffloadSuccess(
             local_disk_segment->ssd_used_bytes.fetch_add(
                 metadata.data_size, std::memory_order_relaxed);
         }
+        if (added_new_local_disk_replica && io_pattern_runtime_) {
+            // The object now holds a durable lower-tier replica, so record it:
+            // once its MEMORY replica is reclaimed the key must be promotable
+            // again instead of looking like it has no replica at all. LOCAL_DISK
+            // is reported under kL3NofSsd until CacheTier grows a dedicated
+            // member for it. The per-object identity resolved inside the add
+            // branch is scoped to that branch, so use the loop-level request
+            // identity here.
+            io_pattern_runtime_->RecordTierEvent(
+                io_pattern::CacheEvent{
+                    .type = io_pattern::CacheEventType::kInserted,
+                    .object = {request_object_id.tenant_id,
+                               request_object_id.user_key},
+                    .target_tier = io_pattern::CacheTier::kL3NofSsd});
+        }
     }
 
     return {};
@@ -6709,6 +8378,54 @@ tl::expected<std::vector<UUID>, ErrorCode> MasterService::PushOffloadingQueue(
     return queued_clients;
 }
 
+// Policy-driven tier down: queue one MEMORY replica of `object_id` for a
+// LOCAL_DISK copy, keeping the MEMORY replica in place. Shares the offload
+// bookkeeping used by the offload-on-evict path (refcnt pin plus an
+// offloading_tasks entry, both released when the client reports the copy back),
+// and deliberately frees nothing: demotion is a copy, not a reclaim.
+bool MasterService::TryQueueTierDown(const ObjectIdentity& object_id) {
+    MetadataAccessorRW accessor(this, object_id);
+    if (!accessor.Exists()) {
+        return false;
+    }
+    auto& metadata = accessor.Get();
+    auto& tenant_state = accessor.GetTenantState();
+
+    // One offload per key. An in-flight task already pins the MEMORY replica this
+    // demotion would pin again, and the holder's queue is keyed by the object, so
+    // re-pushing would only fail with OBJECT_ALREADY_EXISTS. The key is already
+    // on its way down, which is what the caller asked for.
+    if (tenant_state.offloading_tasks.count(object_id.user_key) > 0) {
+        return true;
+    }
+
+    const auto now = std::chrono::system_clock::now();
+    bool queued = false;
+    metadata.VisitReplicas(
+        [](const Replica& replica) {
+            return replica.is_completed() && replica.is_memory_replica();
+        },
+        [this, &object_id, &tenant_state, &now, &queued](Replica& replica) {
+            if (queued) return;  // only one replica needs to be copied down
+            auto result = PushOffloadingQueue(object_id, replica);
+            if (!result || result.value().empty()) {
+                VLOG(1) << "tier_down_push_failed key=" << object_id.user_key
+                        << " error="
+                        << (result ? "empty_result" : toString(result.error()))
+                        << " replica_segments="
+                        << replica.get_segment_names().size();
+                return;
+            }
+            auto& tasks = tenant_state.offloading_tasks[object_id.user_key];
+            for (const auto& client_id : result.value()) {
+                replica.inc_refcnt();
+                tasks.push_back(OffloadingTask{replica.id(), now, client_id});
+            }
+            queued = true;
+        });
+    return queued;
+}
+
 // Promotion-on-hit
 
 // Push a key onto the holder client's promotion_objects map. Resolves the
@@ -7331,10 +9048,9 @@ auto MasterService::PromotionAllocStart(
     return PromotionAllocStartResponse{std::move(desc)};
 }
 
-auto MasterService::NotifyPromotionSuccess(const UUID& client_id,
-                                           const std::string& key,
-                                           const TenantId& tenant_id)
-    -> tl::expected<void, ErrorCode> {
+auto MasterService::NotifyPromotionSuccess(
+    const UUID& client_id, const std::string& key,
+    const TenantId& tenant_id) -> tl::expected<void, ErrorCode> {
     std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
     const auto object_id = MakeObjectIdentityForRequest(key, tenant_id);
     MetadataAccessorRW accessor(this, object_id);
@@ -7466,10 +9182,9 @@ auto MasterService::NotifyPromotionSuccess(const UUID& client_id,
     return {};
 }
 
-auto MasterService::NotifyPromotionFailure(const UUID& client_id,
-                                           const std::string& key,
-                                           const TenantId& tenant_id)
-    -> tl::expected<void, ErrorCode> {
+auto MasterService::NotifyPromotionFailure(
+    const UUID& client_id, const std::string& key,
+    const TenantId& tenant_id) -> tl::expected<void, ErrorCode> {
     std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
     const auto object_id = MakeObjectIdentityForRequest(key, tenant_id);
     MetadataAccessorRW accessor(this, object_id);
@@ -7553,8 +9268,26 @@ void MasterService::EvictionThreadFunc() {
             double evict_ratio_lowerbound =
                 std::max(evict_ratio_target * 0.5,
                          used_ratio - eviction_high_watermark_ratio_);
-            BatchEvict(evict_ratio_target, evict_ratio_lowerbound);
-            LOG(INFO) << "[EVICT-DONE] BatchEvict execution completed.";
+            if (io_pattern_runtime_) {
+                io_pattern_runtime_->RecordStorageMetric(
+                    {.source_id = "master-memory",
+                     .tier = io_pattern::CacheTier::kL1Host,
+                     .memory_used_ratio = static_cast<float>(used_ratio)});
+                const auto capacity = std::max<int64_t>(
+                    0,
+                    MasterMetricManager::instance().get_total_mem_capacity());
+                const auto status = io_pattern_runtime_->Execute(
+                    io_pattern::CacheTier::kL1Host,
+                    static_cast<uint64_t>(evict_ratio_target * capacity), {});
+                // A shortfall is already handled inside the runtime's eviction
+                // handler (RunLegacyEvictionFallback), which also covers the
+                // report-driven worker; running BatchEvict again here would
+                // evict twice for one watermark breach.
+                (void)status;
+            } else {
+                BatchEvict(evict_ratio_target, evict_ratio_lowerbound);
+            }
+            LOG(INFO) << "[EVICT-DONE] eviction execution completed.";
             last_discard_time = now;
         } else if (now - last_discard_time > put_start_release_timeout_sec_) {
             // Try discarding expired processing keys and ongoing replication
@@ -7818,21 +9551,21 @@ void MasterService::DiscardExpiredProcessingReplicas(
             auto& tasks = task_it->second;
             auto metadata_it = tenant_state.metadata.find(task_it->first);
             for (auto t = tasks.begin(); t != tasks.end();) {
-                const auto ttl =
-                    t->start_time + put_start_release_timeout_sec_;
+                const auto ttl = t->start_time + put_start_release_timeout_sec_;
                 if (ttl > now) {
                     t++;
                     continue;
                 }
                 if (metadata_it != tenant_state.metadata.end()) {
-                    auto source = metadata_it->second.GetReplicaByID(
-                        t->source_id);
+                    auto source =
+                        metadata_it->second.GetReplicaByID(t->source_id);
                     if (source != nullptr) {
                         source->dec_refcnt();
                     }
                 }
-                LOG(WARNING) << "Offloading task expired for key: "
-                             << task_it->first << " tenant=" << tenant_it->first;
+                LOG(WARNING)
+                    << "Offloading task expired for key: " << task_it->first
+                    << " tenant=" << tenant_it->first;
                 t = tasks.erase(t);
             }
             if (tasks.empty()) {
@@ -8151,11 +9884,58 @@ tl::expected<void, SerializationError> MasterService::ApplySnapshotState(
     return {};
 }
 
+void MasterService::ReportEvictedKeysAsTierRemovals(
+    const TenantId& tenant,
+    const std::unordered_set<std::string>& candidate_keys) {
+    if (!io_pattern_runtime_ || candidate_keys.empty()) {
+        return;
+    }
+    for (const auto& key : candidate_keys) {
+        const ObjectIdentity object_id{tenant, key};
+        MetadataAccessorRO accessor(this, object_id);
+        if (accessor.Exists() && accessor.Get().HasMemReplica()) {
+            continue;
+        }
+        // The MEMORY replica is gone, so the policy must stop treating this key
+        // as already resident in the head tier; otherwise it is never offered
+        // to admission and never promoted back.
+        io_pattern_runtime_->RecordTierEvent(
+            io_pattern::CacheEvent{
+                .type = io_pattern::CacheEventType::kRemoved,
+                .object = {tenant, key},
+                .source_tier = io_pattern::CacheTier::kL1Host});
+    }
+}
+
+bool MasterService::RunLegacyEvictionFallback(uint64_t shortfall_bytes) {
+    if (shortfall_bytes == 0) {
+        return true;
+    }
+    const auto capacity = std::max<int64_t>(
+        0, MasterMetricManager::instance().get_total_mem_capacity());
+    if (capacity == 0) {
+        return false;
+    }
+    // Only one fallback at a time: the watermark thread and the report-driven
+    // worker can both observe a shortfall, and BatchEvict has no re-entrancy
+    // protection.
+    std::unique_lock<std::mutex> lock(legacy_eviction_mutex_, std::try_to_lock);
+    if (!lock.owns_lock()) {
+        return false;
+    }
+    const double ratio =
+        std::min(1.0, static_cast<double>(shortfall_bytes) /
+                          static_cast<double>(capacity));
+    BatchEvict(ratio, ratio * 0.5);
+    return true;
+}
+
 MasterService::TenantQuotaEvictionResult
-MasterService::EvictTenantMemoryForQuota(const TenantId& tenant_id,
-                                         uint64_t target_bytes) {
+MasterService::EvictTenantMemoryForQuota(
+    const TenantId& tenant_id, uint64_t target_bytes,
+    const std::unordered_set<std::string>* candidate_keys) {
     TenantQuotaEvictionResult total;
-    if (!enable_multi_tenants_ || target_bytes == 0) {
+    if (target_bytes == 0) {
         return total;
     }
 
@@ -8234,6 +10014,19 @@ MasterService::EvictTenantMemoryForQuota(const TenantId& tenant_id,
                                 OffloadingTask{replica.id(), now, client_id});
                         }
                         queued = true;
+                    } else {
+                        // Diagnostic: surface why offload-on-evict could not
+                        // enqueue this MEMORY replica (io_pattern quota
+                        // eviction path used by the report-driven cycle).
+                        LOG(WARNING)
+                            << "[IO-PATTERN-EVICT-DIAG] quota offload enqueue "
+                               "failed for key="
+                            << key << " tenant=" << normalized_tenant.value()
+                            << " error="
+                            << (result ? toString(result.error())
+                                       : "empty_result")
+                            << " replica_segments="
+                            << replica.get_segment_names().size();
                     }
                 });
 
@@ -8270,6 +10063,17 @@ MasterService::EvictTenantMemoryForQuota(const TenantId& tenant_id,
                     .evicted_objects = freed > 0 ? 1U : 0U};
         }
 
+        // Group eviction is atomic. A policy plan naming only part of a group
+        // must not silently expand into unplanned objects; let the caller take
+        // the legacy fallback path instead.
+        if (candidate_keys &&
+            std::any_of(group_it->second.begin(), group_it->second.end(),
+                        [candidate_keys](const std::string& member_key) {
+                            return !candidate_keys->contains(member_key);
+                        })) {
+            return {};
+        }
+
         for (const auto& member_key : group_it->second) {
             auto member_it = tenant_state.metadata.find(member_key);
             if (member_it != tenant_state.metadata.end() &&
@@ -8309,6 +10113,15 @@ MasterService::EvictTenantMemoryForQuota(const TenantId& tenant_id,
 
     auto pass = [&](bool allow_soft_pinned) {
         const size_t start_shard = randomIndex(kNumShards);
+        size_t diag_candidate_hits = 0;
+        size_t diag_candidate_skipped_pin = 0;
+        size_t diag_candidate_skipped_lease = 0;
+        size_t diag_candidate_skipped_replica = 0;
+        size_t diag_candidate_evicted = 0;
+        size_t diag_no_evictable_has_mem = 0;
+        size_t diag_no_evictable_completed = 0;
+        size_t diag_no_evictable_refcnt = 0;
+        size_t diag_no_evictable_unreadable = 0;
         for (size_t scanned = 0;
              scanned < kNumShards && total.freed_bytes < target_bytes;
              ++scanned) {
@@ -8324,20 +10137,64 @@ MasterService::EvictTenantMemoryForQuota(const TenantId& tenant_id,
                 for (auto it = tenant_state.metadata.begin();
                      it != tenant_state.metadata.end() &&
                      total.freed_bytes < target_bytes;) {
+                    if (candidate_keys &&
+                        !candidate_keys->contains(it->first)) {
+                        ++it;
+                        continue;
+                    }
                     auto& metadata = it->second;
                     if (metadata.IsHardPinned() ||
                         !metadata.IsLeaseExpired(now) ||
                         (!allow_soft_pinned && metadata.IsSoftPinned(now)) ||
                         !can_evict_replicas(metadata)) {
+                        if (candidate_keys) {
+                            ++diag_candidate_hits;
+                            if (metadata.IsHardPinned() ||
+                                (!allow_soft_pinned &&
+                                 metadata.IsSoftPinned(now))) {
+                                ++diag_candidate_skipped_pin;
+                            } else if (!metadata.IsLeaseExpired(now)) {
+                                ++diag_candidate_skipped_lease;
+                            } else {
+                                ++diag_candidate_skipped_replica;
+                                // Replica-level breakdown for why no evictable
+                                // MEMORY replica exists.
+                                bool diag_has_mem = false;
+                                bool diag_all_completed = true;
+                                bool diag_any_refcnt = false;
+                                bool diag_any_unreadable = false;
+                                metadata.VisitReplicas(
+                                    &Replica::fn_is_memory_replica,
+                                    [&](Replica& r) {
+                                        diag_has_mem = true;
+                                        if (!r.is_completed())
+                                            diag_all_completed = false;
+                                        if (r.get_refcnt() != 0)
+                                            diag_any_refcnt = true;
+                                        if (!IsReplicaReadable(r))
+                                            diag_any_unreadable = true;
+                                    });
+                                diag_no_evictable_has_mem += diag_has_mem;
+                                diag_no_evictable_completed +=
+                                    diag_all_completed;
+                                diag_no_evictable_refcnt += diag_any_refcnt;
+                                diag_no_evictable_unreadable +=
+                                    diag_any_unreadable;
+                            }
+                        }
                         ++it;
                         continue;
                     }
+                    if (candidate_keys) ++diag_candidate_hits;
 
                     auto evict_result = try_evict_group_or_object(
                         it->first, metadata, tenant_state, deferred_replicas,
                         allow_soft_pinned);
                     total.freed_bytes += evict_result.freed_bytes;
                     total.evicted_objects += evict_result.evicted_objects;
+                    if (candidate_keys && evict_result.freed_bytes > 0) {
+                        ++diag_candidate_evicted;
+                    }
                     if (!metadata.IsValid()) {
                         it = EraseMetadata(tenant_state, it, normalized_tenant);
                     } else {
@@ -8349,6 +10206,24 @@ MasterService::EvictTenantMemoryForQuota(const TenantId& tenant_id,
                 }
             }
         }
+        if (candidate_keys) {
+            LOG(WARNING)
+                << "[IO-PATTERN-EVICT-DIAG] quota pass candidate scan "
+                   "tenant="
+                << normalized_tenant.value()
+                << " allow_soft_pinned=" << allow_soft_pinned
+                << " hits_in_metadata=" << diag_candidate_hits
+                << " skipped_pin=" << diag_candidate_skipped_pin
+                << " skipped_lease=" << diag_candidate_skipped_lease
+                << " skipped_no_evictable_replica="
+                << diag_candidate_skipped_replica
+                << " (has_mem=" << diag_no_evictable_has_mem
+                << " completed=" << diag_no_evictable_completed
+                << " any_refcnt=" << diag_no_evictable_refcnt
+                << " any_unreadable=" << diag_no_evictable_unreadable << ")"
+                << " evicted=" << diag_candidate_evicted
+                << " freed_bytes=" << total.freed_bytes;
+        }
     };
 
     pass(/*allow_soft_pinned=*/false);
@@ -8491,6 +10366,18 @@ void MasterService::BatchEvict(double evict_ratio_target,
                             OffloadingTask{replica.id(), now, client_id});
                     }
                     queued = true;
+                } else {
+                    // Diagnostic: surface why the offload queue rejected this
+                    // MEMORY replica (empty result = no segment names on the
+                    // replica or no matching LOCAL_DISK holder).
+                    LOG(WARNING)
+                        << "[IO-PATTERN-EVICT-DIAG] BatchEvict offload enqueue "
+                           "failed for key="
+                        << key << " tenant=" << tenant_id.value()
+                        << " error="
+                        << (result ? toString(result.error()) : "empty_result")
+                        << " replica_segments="
+                        << replica.get_segment_names().size();
                 }
             });
 
@@ -11327,7 +13214,8 @@ ErrorCode MasterService::InitializeBatchOpLogWriter(
         return ErrorCode::INVALID_PARAMS;
     }
 
-    auto storage = std::make_unique<OpLogBatchStorage>(cluster_id_, *backend);
+    auto storage =
+        std::make_unique<OpLogBatchStorage>(cluster_id_, *backend, master_id_);
     DurablePrefix durable_prefix;
     ErrorCode err = storage->InitDurablePrefix(durable_prefix);
     if (err != ErrorCode::OK) {
diff --git a/mooncake-store/src/partition/partition_router.cpp b/mooncake-store/src/partition/partition_router.cpp
new file mode 100644
index 0000000000..488230eabd
--- /dev/null
+++ b/mooncake-store/src/partition/partition_router.cpp
@@ -0,0 +1,94 @@
+#include "partition/partition_router.h"
+
+#include <utility>
+
+#include <glog/logging.h>
+
+#include "cvm/cvm_keys.h"
+#include "etcd_helper.h"
+#include "partition/kv_hash_map.h"
+#include "ylt/struct_json/json_reader.h"
+
+namespace mooncake {
+namespace partition {
+
+void PartitionRouter::LoadSlotOwners(
+    const std::vector<cvm::SlotOwner>& owners) {
+    std::unordered_map<uint16_t, std::string> next;
+    next.reserve(owners.size());
+    for (const auto& owner : owners) {
+        if (!owner.primary_master_id.empty() &&
+            owner.state == static_cast<int32_t>(cvm::SlotState::kStable)) {
+            next[owner.slot] = owner.primary_master_id;
+        }
+    }
+
+    const size_t valid = next.size();
+    {
+        SharedMutexLocker locker(&mutex_);
+        slot_to_submaster_ = std::move(next);
+    }
+    LOG(INFO) << "PartitionRouter loaded " << valid << " slot->submaster"
+              << " entries (input " << owners.size() << " SlotOwner records)";
+}
+
+ErrorCode PartitionRouter::LoadFromEtcdSnapshot(
+    const std::string& cluster_namespace) {
+    const std::string key = cvm::KvViewSnapshotKey(cluster_namespace);
+    std::string value;
+    EtcdRevisionId revision = 0;
+    ErrorCode err = EtcdHelper::Get(key.data(), key.size(), value, revision);
+    if (err != ErrorCode::OK) {
+        LOG(WARNING) << "PartitionRouter read snapshot failed: " << key
+                     << " err=" << err;
+        return err;
+    }
+
+    cvm::KvViewSnapshot snapshot;
+    try {
+        struct_json::from_json(snapshot, value);
+    } catch (const std::exception& e) {
+        LOG(ERROR) << "PartitionRouter deserialize snapshot failed: "
+                   << e.what();
+        return ErrorCode::DESERIALIZE_FAIL;
+    }
+
+    LoadSlotOwners(snapshot.slot_owners);
+    LOG(INFO) << "PartitionRouter refreshed from snapshot " << key
+              << " version=" << snapshot.version;
+    return ErrorCode::OK;
+}
+
+std::optional<std::string> PartitionRouter::ResolveSubmaster(
+    uint16_t slot) const {
+    SharedMutexLocker locker(&mutex_, shared_lock);
+    auto it = slot_to_submaster_.find(slot);
+    if (it == slot_to_submaster_.end()) {
+        LOG(WARNING) << "PartitionRouter no submaster for slot " << slot;
+        return std::nullopt;
+    }
+    return it->second;
+}
+
+std::optional<std::string> PartitionRouter::Route(
+    const TenantId& tenant, const std::string& key) const {
+    return ResolveSubmaster(KvHashMap::Compute(tenant, key));
+}
+
+void PartitionRouter::Clear() {
+    size_t old_size = 0;
+    {
+        SharedMutexLocker locker(&mutex_);
+        old_size = slot_to_submaster_.size();
+        slot_to_submaster_.clear();
+    }
+    LOG(INFO) << "PartitionRouter cleared " << old_size << " entries";
+}
+
+size_t PartitionRouter::Size() const {
+    SharedMutexLocker locker(&mutex_, shared_lock);
+    return slot_to_submaster_.size();
+}
+
+}  // namespace partition
+}  // namespace mooncake
diff --git a/mooncake-store/src/rpc_service.cpp b/mooncake-store/src/rpc_service.cpp
index 57abd06492..070269012f 100644
--- a/mooncake-store/src/rpc_service.cpp
+++ b/mooncake-store/src/rpc_service.cpp
@@ -8,6 +8,7 @@
 #include <ylt/coro_rpc/coro_rpc_server.hpp>
 #include <ylt/util/tl/expected.hpp>
 
+#include "common.h"
 #include "ha_metric_manager.h"
 #include "master_admin_service.h"
 #include "master_metric_manager.h"
@@ -100,7 +101,8 @@ WrappedMasterService::WrappedMasterService(
     const WrappedMasterServiceConfig& config,
     HttpMetadataServer* http_metadata_server,
     const std::string& http_metadata_remote_url)
-    : master_service_(MasterServiceConfig(config)) {
+    : master_service_(MasterServiceConfig(config)),
+      cfm_rpc_service_(master_service_.GetCfmService()) {
     // Configure metadata cleanup on client timeout. Prefer the co-located
     // in-process server; otherwise fall back to a separately-deployed HTTP
     // metadata server derived from the cluster configuration.
@@ -546,6 +548,81 @@ tl::expected<void, ErrorCode> WrappedMasterService::PutEnd(
     return result;
 }
 
+tl::expected<VChunkMetadataRecord, ErrorCode>
+WrappedMasterService::VChunkPutStart(const std::string& tenant_id,
+                                     const std::string& key,
+                                     uint64_t total_size, int64_t now_ms) {
+    return WithRequestTenant(
+        tenant_id,
+        [&](const TenantId& resolved_tenant_id) {
+            return master_service_.VChunkPutStart(resolved_tenant_id, key,
+                                                  total_size, false, now_ms);
+        });
+}
+
+tl::expected<void, ErrorCode> WrappedMasterService::VChunkPutEnd(
+    const std::string& tenant_id, const std::string& key,
+    const std::string& vchunk_id, int64_t now_ms) {
+    return WithRequestTenant(
+        tenant_id,
+        [&](const TenantId& resolved_tenant_id) {
+            const auto error = master_service_.VChunkPutEnd(
+                resolved_tenant_id, key, vchunk_id, now_ms);
+            return error == ErrorCode::OK
+                       ? tl::expected<void, ErrorCode>{}
+                       : tl::expected<void, ErrorCode>{tl::unexpected(error)};
+        });
+}
+
+tl::expected<void, ErrorCode> WrappedMasterService::VChunkPutRevoke(
+    const std::string& tenant_id, const std::string& key,
+    const std::string& vchunk_id) {
+    return WithRequestTenant(
+        tenant_id,
+        [&](const TenantId& resolved_tenant_id) {
+            const auto error = master_service_.VChunkPutRevoke(
+                resolved_tenant_id, key, vchunk_id);
+            return error == ErrorCode::OK
+                       ? tl::expected<void, ErrorCode>{}
+                       : tl::expected<void, ErrorCode>{tl::unexpected(error)};
+        });
+}
+
+tl::expected<VChunkReadLease, ErrorCode> WrappedMasterService::GetVChunk(
+    const std::string& tenant_id, const std::string& key) {
+    return WithRequestTenant(
+        tenant_id,
+        [&](const TenantId& resolved_tenant_id) {
+            return master_service_.AcquireVChunkReadLease(
+                resolved_tenant_id, key, getCurrentTimeInMilli());
+        });
+}
+
+tl::expected<void, ErrorCode> WrappedMasterService::ReleaseVChunkReadLease(
+    const std::string& lease_id) {
+    const auto error = master_service_.ReleaseVChunkReadLease(lease_id);
+    return error == ErrorCode::OK
+               ? tl::expected<void, ErrorCode>{}
+               : tl::expected<void, ErrorCode>{tl::unexpected(error)};
+}
+
+tl::expected<void, ErrorCode> WrappedMasterService::RemoveVChunk(
+    const std::string& tenant_id, const std::string& key, int64_t now_ms) {
+    return WithRequestTenant(
+        tenant_id,
+        [&](const TenantId& resolved_tenant_id) {
+            const auto error = master_service_.RemoveVChunk(
+                resolved_tenant_id, key, now_ms);
+            return error == ErrorCode::OK
+                       ? tl::expected<void, ErrorCode>{}
+                       : tl::expected<void, ErrorCode>{tl::unexpected(error)};
+        });
+}
+
+VChunkRuntimeInfo WrappedMasterService::GetVChunkRuntimeInfo() {
+    return master_service_.GetVChunkRuntimeInfo();
+}
+
 tl::expected<void, ErrorCode> WrappedMasterService::PutRevoke(
     const UUID& client_id, const std::string& key, ReplicaType replica_type,
     const std::string& tenant_id) {
@@ -1832,11 +1909,152 @@ void WrappedMasterService::RestoreFromStandby(
         objects, initial_oplog_sequence_id, segments);
 }
 
+void WrappedMasterService::SetCvmLeaseId(EtcdLeaseId lease_id) {
+    master_service_.SetCvmLeaseId(lease_id);
+}
+
+ErrorCode WrappedMasterService::StartSlotOwnerHeartbeat() {
+    return master_service_.StartSlotOwnerHeartbeat();
+}
+
+void WrappedMasterService::StopSlotOwnerHeartbeat() {
+    master_service_.StopSlotOwnerHeartbeat();
+}
+
+ErrorCode WrappedMasterService::StartInterMasterRpc() {
+    return master_service_.StartInterMasterRpc();
+}
+
+void WrappedMasterService::StopInterMasterRpc() {
+    master_service_.StopInterMasterRpc();
+}
+
+tl::expected<InterMasterHandshakeResponse, ErrorCode>
+WrappedMasterService::InterMasterHandshake() {
+    return execute_rpc(
+        "InterMasterHandshake",
+        [&]() -> tl::expected<InterMasterHandshakeResponse, ErrorCode> {
+            InterMasterHandshakeResponse resp;
+            resp.master_id = master_service_.master_id();
+            resp.lease_id = master_service_.cvm_lease_id();
+            resp.owned_slot_count = master_service_.GetOwnedSlotCount();
+            resp.version = GetMooncakeStoreVersion();
+            return resp;
+        },
+        [&](auto& timer) {
+            timer.LogRequest("self=", master_service_.master_id());
+        },
+        [] {}, [] {});
+}
+
+tl::expected<std::vector<Replica::Descriptor>, ErrorCode>
+WrappedMasterService::InterMasterAllocateReplicas(
+    const std::string& tenant_id, const std::string& key,
+    uint64_t slice_length, uint64_t replica_num,
+    const std::vector<std::string>& preferred_segments) {
+    return execute_rpc(
+        "InterMasterAllocateReplicas",
+        [&] {
+            return master_service_.InterMasterAllocateReplicas(
+                tenant_id, key, slice_length, replica_num, preferred_segments);
+        },
+        [&](auto& timer) {
+            timer.LogRequest("key=", key, ", slice_length=", slice_length,
+                             ", replica_num=", replica_num);
+        },
+        [] {}, [] {});
+}
+
+tl::expected<bool, ErrorCode> WrappedMasterService::InterMasterFreeReplicas(
+    const std::string& tenant_id, const std::string& key) {
+    return execute_rpc(
+        "InterMasterFreeReplicas",
+        [&] { return master_service_.InterMasterFreeReplicas(tenant_id, key); },
+        [&](auto& timer) { timer.LogRequest("key=", key); }, [] {}, [] {});
+}
+
+tl::expected<GetReplicaListResponse, ErrorCode>
+WrappedMasterService::InterMasterGetReplicaList(const std::string& key,
+                                                const std::string& tenant_id) {
+    return execute_rpc(
+        "InterMasterGetReplicaList",
+        [&] {
+            return master_service_.InterMasterGetReplicaList(key, tenant_id);
+        },
+        [&](auto& timer) { timer.LogRequest("key=", key); }, [] {}, [] {});
+}
+
+std::vector<tl::expected<GetReplicaListResponse, ErrorCode>>
+WrappedMasterService::InterMasterBatchGetReplicaList(
+    const std::vector<std::string>& keys, const std::string& tenant_id) {
+    ScopedVLogTimer timer(1, "InterMasterBatchGetReplicaList");
+    timer.LogRequest("keys_count=", keys.size());
+    return master_service_.InterMasterBatchGetReplicaList(keys, tenant_id);
+}
+
+tl::expected<std::vector<Replica::Descriptor>, ErrorCode>
+WrappedMasterService::InterMasterPutStart(
+    const UUID& client_id, const std::string& key, const std::string& tenant_id,
+    uint64_t slice_length, const ReplicateConfig& config) {
+    return execute_rpc(
+        "InterMasterPutStart", PerfKey::MASTER_RPC_PUT_START,
+        [&] {
+            return master_service_.InterMasterPutStart(
+                client_id, key, tenant_id, slice_length, config);
+        },
+        [&](auto& timer) {
+            timer.LogRequest("client_id=", client_id, ", key=", key,
+                             ", slice_length=", slice_length);
+        },
+        [] {}, [] {});
+}
+
+tl::expected<std::vector<Replica::Descriptor>, ErrorCode>
+WrappedMasterService::InterMasterUpsertStart(
+    const UUID& client_id, const std::string& key, const std::string& tenant_id,
+    uint64_t slice_length, const ReplicateConfig& config) {
+    return execute_rpc(
+        "InterMasterUpsertStart", PerfKey::MASTER_RPC_UPSERT_START,
+        [&] {
+            return master_service_.InterMasterUpsertStart(
+                client_id, key, tenant_id, slice_length, config);
+        },
+        [&](auto& timer) {
+            timer.LogRequest("client_id=", client_id, ", key=", key,
+                             ", slice_length=", slice_length);
+        },
+        [] {}, [] {});
+}
+
 void RegisterRpcService(
     coro_rpc::coro_rpc_server& server,
     mooncake::WrappedMasterService& wrapped_master_service) {
     server.register_handler<&mooncake::WrappedMasterService::ExistKey>(
         &wrapped_master_service);
+    // Inter-master handshake (CVM multi-submaster coordination).
+    server.register_handler<
+        &mooncake::WrappedMasterService::InterMasterHandshake>(
+        &wrapped_master_service);
+    // Inter-master allocation forwarding (CVM plan B phase 2).
+    server.register_handler<
+        &mooncake::WrappedMasterService::InterMasterAllocateReplicas>(
+        &wrapped_master_service);
+    server.register_handler<
+        &mooncake::WrappedMasterService::InterMasterFreeReplicas>(
+        &wrapped_master_service);
+    // Inter-master read forwarding (CVM plan B phase 2).
+    server.register_handler<
+        &mooncake::WrappedMasterService::InterMasterGetReplicaList>(
+        &wrapped_master_service);
+    server.register_handler<
+        &mooncake::WrappedMasterService::InterMasterBatchGetReplicaList>(
+        &wrapped_master_service);
+    // Inter-master write forwarding (model B).
+    server.register_handler<&mooncake::WrappedMasterService::InterMasterPutStart>(
+        &wrapped_master_service);
+    server.register_handler<
+        &mooncake::WrappedMasterService::InterMasterUpsertStart>(
+        &wrapped_master_service);
     server.register_handler<&mooncake::WrappedMasterService::BatchQueryIp>(
         &wrapped_master_service);
     server.register_handler<&mooncake::WrappedMasterService::BatchReplicaClear>(
@@ -1851,10 +2069,28 @@ void RegisterRpcService(
             &wrapped_master_service);
     server.register_handler<&mooncake::WrappedMasterService::PutStart>(
         &wrapped_master_service);
+    auto& cfm = wrapped_master_service.CfmRpcEndpoint();
+    server.register_handler<&io_pattern::CfmRpcService::Send>(&cfm);
     server.register_handler<&mooncake::WrappedMasterService::PutEnd>(
         &wrapped_master_service);
     server.register_handler<&mooncake::WrappedMasterService::PutRevoke>(
         &wrapped_master_service);
+    server.register_handler<&mooncake::WrappedMasterService::VChunkPutStart>(
+        &wrapped_master_service);
+    server.register_handler<&mooncake::WrappedMasterService::VChunkPutEnd>(
+        &wrapped_master_service);
+    server.register_handler<&mooncake::WrappedMasterService::VChunkPutRevoke>(
+        &wrapped_master_service);
+    server.register_handler<&mooncake::WrappedMasterService::GetVChunk>(
+        &wrapped_master_service);
+    server.register_handler<
+        &mooncake::WrappedMasterService::ReleaseVChunkReadLease>(
+        &wrapped_master_service);
+    server.register_handler<&mooncake::WrappedMasterService::RemoveVChunk>(
+        &wrapped_master_service);
+    server.register_handler<
+        &mooncake::WrappedMasterService::GetVChunkRuntimeInfo>(
+        &wrapped_master_service);
     server.register_handler<&mooncake::WrappedMasterService::BatchPutStart>(
         &wrapped_master_service);
     server.register_handler<&mooncake::WrappedMasterService::BatchPutEnd>(
diff --git a/mooncake-store/src/types.cpp b/mooncake-store/src/types.cpp
index 7535abccbf..904836c552 100644
--- a/mooncake-store/src/types.cpp
+++ b/mooncake-store/src/types.cpp
@@ -50,6 +50,7 @@ const std::string& toString(ErrorCode errorCode) noexcept {
         {ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS,
          "UNAVAILABLE_IN_CURRENT_STATUS"},
         {ErrorCode::UNAVAILABLE_IN_CURRENT_MODE, "UNAVAILABLE_IN_CURRENT_MODE"},
+        {ErrorCode::SLOT_NOT_OWNED, "SLOT_NOT_OWNED"},
         {ErrorCode::FILE_NOT_FOUND, "FILE_NOT_FOUND"},
         {ErrorCode::FILE_OPEN_FAIL, "FILE_OPEN_FAIL"},
         {ErrorCode::FILE_READ_FAIL, "FILE_READ_FAIL"},
diff --git a/mooncake-store/src/vchunk_allocation_strategy.cpp b/mooncake-store/src/vchunk_allocation_strategy.cpp
new file mode 100644
index 0000000000..de1327eabd
--- /dev/null
+++ b/mooncake-store/src/vchunk_allocation_strategy.cpp
@@ -0,0 +1,144 @@
+#include "vchunk_allocation_strategy.h"
+
+#include <algorithm>
+#include <limits>
+#include <unordered_set>
+
+#include "allocation_strategy.h"
+#include "random.h"
+
+namespace mooncake {
+namespace {
+
+struct Candidate {
+    std::string name;
+    const std::vector<std::shared_ptr<BufferAllocatorBase>>* allocators;
+    uint64_t remaining_slices;
+    uint64_t allocated_slices{0};
+};
+
+uint64_t AvailableBytes(const BufferAllocatorBase& allocator) {
+    const auto capacity = allocator.capacity();
+    const auto used = allocator.size();
+    if (capacity == kAllocatorUnknownFreeSpace) {
+        return allocator.getLargestFreeRegion();
+    }
+    return capacity > used ? capacity - used : 0;
+}
+
+std::unique_ptr<AllocatedBuffer> AllocateFromCandidate(Candidate& candidate,
+                                                       size_t size) {
+    for (const auto& allocator : *candidate.allocators) {
+        if (allocator && allocator->getLargestFreeRegion() >= size) {
+            if (auto buffer = allocator->allocate(size)) {
+                ++candidate.allocated_slices;
+                return buffer;
+            }
+        }
+    }
+    return nullptr;
+}
+
+}  // namespace
+
+tl::expected<VChunkAllocationResult, ErrorCode> AllocateVChunk(
+    const AllocatorManager& allocator_manager, uint64_t total_size,
+    VCSliceSizeLevel slice_size_level,
+    const std::set<std::string>& excluded_segments) {
+    const uint64_t slice_size = SliceSizeLevelToBytes(slice_size_level);
+    if (total_size == 0 || slice_size == 0 ||
+        total_size > std::numeric_limits<uint64_t>::max() - (slice_size - 1)) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    const uint64_t slice_count_u64 =
+        (total_size + slice_size - 1) / slice_size;
+    if (slice_count_u64 > std::numeric_limits<uint32_t>::max()) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+
+    std::vector<Candidate> candidates;
+    for (const auto& name : allocator_manager.getNames()) {
+        if (excluded_segments.contains(name)) {
+            continue;
+        }
+        const auto* allocators = allocator_manager.getAllocators(name);
+        if (allocators == nullptr || allocators->empty()) {
+            continue;
+        }
+        uint64_t available = 0;
+        for (const auto& allocator : *allocators) {
+            if (!allocator) {
+                continue;
+            }
+            const auto bytes = AvailableBytes(*allocator);
+            if (available > std::numeric_limits<uint64_t>::max() - bytes) {
+                available = std::numeric_limits<uint64_t>::max();
+                break;
+            }
+            available += bytes;
+        }
+        const uint64_t weight = available / slice_size;
+        if (weight > 0) {
+            candidates.push_back({name, allocators, weight, 0});
+        }
+    }
+    if (candidates.empty()) {
+        return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
+    }
+
+    const auto slice_count = static_cast<uint32_t>(slice_count_u64);
+    VChunkAllocationResult result;
+    result.row_size = std::min<size_t>(slice_count, candidates.size());
+    result.allocations.reserve(slice_count);
+    const size_t start_offset = randomIndex(candidates.size());
+
+    while (result.allocations.size() < slice_count) {
+        std::unordered_set<std::string> used_in_row;
+        used_in_row.reserve(result.row_size);
+        const size_t row = result.allocations.size() / result.row_size;
+        const size_t row_width = std::min<size_t>(
+            result.row_size, slice_count - result.allocations.size());
+        for (size_t column = 0; column < row_width; ++column) {
+            bool allocated = false;
+            for (size_t attempt = 0; attempt < candidates.size(); ++attempt) {
+                const size_t index =
+                    (start_offset + row + column + attempt) % candidates.size();
+                auto& candidate = candidates[index];
+                if (used_in_row.contains(candidate.name) ||
+                    candidate.allocated_slices >= candidate.remaining_slices) {
+                    continue;
+                }
+                auto buffer = AllocateFromCandidate(candidate, slice_size);
+                if (!buffer) {
+                    candidate.remaining_slices = candidate.allocated_slices;
+                    continue;
+                }
+
+                const auto slice_index =
+                    static_cast<uint32_t>(result.allocations.size());
+                const uint64_t consumed = slice_index * slice_size;
+                const uint32_t logical_length = static_cast<uint32_t>(
+                    std::min<uint64_t>(slice_size, total_size - consumed));
+                VCSliceAllocation allocation;
+                allocation.slice_index = slice_index;
+                allocation.segment_name = candidate.name;
+                allocation.target_offset =
+                    reinterpret_cast<uintptr_t>(buffer->data());
+                allocation.logical_length = logical_length;
+                allocation.allocated_length =
+                    static_cast<uint32_t>(buffer->size());
+                allocation.buffer = std::move(buffer);
+                result.allocations.push_back(std::move(allocation));
+                used_in_row.insert(candidate.name);
+                allocated = true;
+                break;
+            }
+            if (!allocated) {
+                return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
+            }
+        }
+    }
+    return result;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/vchunk_client.cpp b/mooncake-store/src/vchunk_client.cpp
new file mode 100644
index 0000000000..aa66c31dab
--- /dev/null
+++ b/mooncake-store/src/vchunk_client.cpp
@@ -0,0 +1,316 @@
+#include "vchunk_client.h"
+
+#include <glog/logging.h>
+
+#include "master_service.h"
+
+namespace mooncake {
+namespace {
+
+size_t SafeKeyId(const TenantId& tenant_id, const std::string& key) {
+    return std::hash<std::string>{}(tenant_id.MakeScopedKey(key));
+}
+
+bool CountsForCircuitBreaker(ErrorCode error) {
+    return error == ErrorCode::NO_AVAILABLE_HANDLE ||
+           error == ErrorCode::TRANSFER_FAIL || error == ErrorCode::RPC_TIMEOUT ||
+           error == ErrorCode::ETCD_OPERATION_ERROR ||
+           error == ErrorCode::RPC_FAIL;
+}
+
+}  // namespace
+
+VChunkClient::VChunkClient(bool enabled, MasterService& master,
+                           VChunkDataPlane& data_plane,
+                           VChunkLegacyPath& legacy,
+                           std::chrono::milliseconds timeout, NowMs now_ms,
+                           uint32_t max_retries,
+                           uint32_t circuit_breaker_threshold,
+                           std::shared_ptr<VChunkMetrics> metrics)
+    : enabled_(enabled),
+      owned_control_plane_(std::make_unique<LocalVChunkControlPlane>(master)),
+      control_plane_(owned_control_plane_.get()),
+      data_plane_(data_plane),
+      legacy_(legacy),
+      timeout_(timeout),
+      now_ms_(std::move(now_ms)),
+      max_retries_(max_retries),
+      circuit_breaker_threshold_(circuit_breaker_threshold),
+      metrics_(metrics ? std::move(metrics)
+                       : std::make_shared<VChunkMetrics>()) {}
+
+VChunkClient::VChunkClient(bool enabled, VChunkControlPlane& control_plane,
+                           VChunkDataPlane& data_plane,
+                           VChunkLegacyPath& legacy,
+                           std::chrono::milliseconds timeout, NowMs now_ms,
+                           uint32_t max_retries,
+                           uint32_t circuit_breaker_threshold,
+                           std::shared_ptr<VChunkMetrics> metrics)
+    : enabled_(enabled),
+      control_plane_(&control_plane),
+      data_plane_(data_plane),
+      legacy_(legacy),
+      timeout_(timeout),
+      now_ms_(std::move(now_ms)),
+      max_retries_(max_retries),
+      circuit_breaker_threshold_(circuit_breaker_threshold),
+      metrics_(metrics ? std::move(metrics)
+                       : std::make_shared<VChunkMetrics>()) {}
+
+ErrorCode VChunkClient::Put(const TenantId& tenant_id, const std::string& key,
+                            const void* source, size_t length) {
+    const auto started = Clock::now();
+    const auto deadline = started + timeout_;
+    if (!enabled_) {
+        return legacy_.Put(tenant_id, key, source, length);
+    }
+    if (circuit_breaker_threshold_ > 0 &&
+        consecutive_put_failures_.load() >= circuit_breaker_threshold_) {
+        metrics_->Observe(VChunkOperation::PUT, false, 0);
+        return ErrorCode::NO_AVAILABLE_HANDLE;
+    }
+    if (!source || length == 0 || timeout_.count() <= 0 || !now_ms_) {
+        metrics_->Observe(VChunkOperation::PUT, false, 0);
+        return ErrorCode::INVALID_PARAMS;
+    }
+    auto created = control_plane_->PutStart(tenant_id, key, length, now_ms_());
+    if (!created) {
+        if (CountsForCircuitBreaker(created.error())) {
+            consecutive_put_failures_.fetch_add(1);
+        }
+        metrics_->Observe(
+            VChunkOperation::PUT, false,
+            std::chrono::duration_cast<std::chrono::microseconds>(Clock::now() -
+                                                                  started)
+                .count());
+        return created.error();
+    }
+    if (Clock::now() >= deadline) {
+        (void)control_plane_->PutRevoke(tenant_id, key, created->vchunk_id);
+        metrics_->AddRollback();
+        metrics_->AddTimeout();
+        metrics_->Observe(
+            VChunkOperation::PUT, false,
+            std::chrono::duration_cast<std::chrono::microseconds>(Clock::now() -
+                                                                  started)
+                .count());
+        return ErrorCode::RPC_TIMEOUT;
+    }
+    metrics_->AddSlices(created->slice_count);
+    metrics_->ObserveLayout(*created);
+    ErrorCode transfer = ErrorCode::TRANSFER_FAIL;
+    for (uint32_t attempt = 0; attempt <= max_retries_; ++attempt) {
+        if (Clock::now() >= deadline) {
+            transfer = ErrorCode::RPC_TIMEOUT;
+            break;
+        }
+        transfer = data_plane_.Write(*created, source, length, deadline);
+        if (transfer == ErrorCode::OK ||
+            (transfer != ErrorCode::TRANSFER_FAIL &&
+             transfer != ErrorCode::RPC_TIMEOUT)) {
+            break;
+        }
+        if (attempt < max_retries_) {
+            metrics_->AddRetry();
+        }
+    }
+    if (transfer != ErrorCode::OK) {
+        if (!created->slices.empty()) {
+            const auto& slice = created->slices.front();
+            LOG(ERROR) << "vchunk write failed tenant=" << tenant_id.value()
+                       << " key_id=" << SafeKeyId(tenant_id, key)
+                       << " vchunk_id=" << created->vchunk_id
+                       << " status=" << static_cast<int>(created->status)
+                       << " slice_index=" << slice.slice_index
+                       << " segment=" << slice.target_segment_name
+                       << " slice_count=" << created->slice_count
+                       << " error=" << static_cast<int>(transfer);
+        }
+        const auto revoke =
+            control_plane_->PutRevoke(tenant_id, key, created->vchunk_id);
+        metrics_->AddRollback();
+        if (transfer == ErrorCode::RPC_TIMEOUT) {
+            metrics_->AddTimeout();
+        } else {
+            metrics_->AddTransferFailure();
+        }
+        consecutive_put_failures_.fetch_add(1);
+        const auto result = revoke == ErrorCode::OK ? transfer : revoke;
+        metrics_->Observe(
+            VChunkOperation::PUT, false,
+            std::chrono::duration_cast<std::chrono::microseconds>(Clock::now() -
+                                                                  started)
+                .count());
+        return result;
+    }
+    if (Clock::now() >= deadline) {
+        (void)control_plane_->PutRevoke(tenant_id, key, created->vchunk_id);
+        metrics_->AddRollback();
+        metrics_->AddTimeout();
+        metrics_->Observe(
+            VChunkOperation::PUT, false,
+            std::chrono::duration_cast<std::chrono::microseconds>(Clock::now() -
+                                                                  started)
+                .count());
+        return ErrorCode::RPC_TIMEOUT;
+    }
+    auto end =
+        control_plane_->PutEnd(tenant_id, key, created->vchunk_id, now_ms_());
+    // PutEnd may have committed durably while its RPC response was lost. Read
+    // back before revoking so an ambiguous timeout cannot leave a successful
+    // object reported as failed (or turn it into an orphan).
+    if (end != ErrorCode::OK) {
+        auto committed = control_plane_->Get(tenant_id, key);
+        if (committed &&
+            committed->record.vchunk_id == created->vchunk_id &&
+            committed->record.status == VChunkStatus::ACTIVE) {
+            end = ErrorCode::OK;
+        }
+    }
+    if (end != ErrorCode::OK) {
+        control_plane_->PutRevoke(tenant_id, key, created->vchunk_id);
+    }
+    if (end == ErrorCode::OK) {
+        consecutive_put_failures_.store(0);
+    } else {
+        consecutive_put_failures_.fetch_add(1);
+    }
+    metrics_->Observe(
+        VChunkOperation::PUT, end == ErrorCode::OK,
+        std::chrono::duration_cast<std::chrono::microseconds>(Clock::now() -
+                                                              started)
+            .count());
+    return end;
+}
+
+ErrorCode VChunkClient::Get(const TenantId& tenant_id, const std::string& key,
+                            void* destination, size_t length) {
+    const auto started = Clock::now();
+    const auto deadline = started + timeout_;
+    if (!enabled_) {
+        return legacy_.Get(tenant_id, key, destination, length);
+    }
+    if (!destination || timeout_.count() <= 0) {
+        metrics_->Observe(VChunkOperation::GET, false, 0);
+        return ErrorCode::INVALID_PARAMS;
+    }
+    auto read = control_plane_->Get(tenant_id, key);
+    if (!read) {
+        metrics_->Observe(VChunkOperation::GET, false, 0);
+        return read.error();
+    }
+    if (read->record.total_size != length) {
+        metrics_->Observe(VChunkOperation::GET, false, 0);
+        return ErrorCode::INVALID_PARAMS;
+    }
+    if (Clock::now() >= deadline) {
+        metrics_->AddTimeout();
+        metrics_->Observe(
+            VChunkOperation::GET, false,
+            std::chrono::duration_cast<std::chrono::microseconds>(Clock::now() -
+                                                                  started)
+                .count());
+        return ErrorCode::RPC_TIMEOUT;
+    }
+    ErrorCode result = ErrorCode::TRANSFER_FAIL;
+    for (uint32_t attempt = 0; attempt <= max_retries_; ++attempt) {
+        if (Clock::now() >= deadline) {
+            result = ErrorCode::RPC_TIMEOUT;
+            break;
+        }
+        result = data_plane_.Read(read->record, destination, length, deadline);
+        if (result == ErrorCode::OK ||
+            (result != ErrorCode::TRANSFER_FAIL &&
+             result != ErrorCode::RPC_TIMEOUT)) {
+            break;
+        }
+        if (attempt < max_retries_) {
+            metrics_->AddRetry();
+        }
+    }
+    if (result == ErrorCode::RPC_TIMEOUT) {
+        metrics_->AddTimeout();
+    } else if (result == ErrorCode::TRANSFER_FAIL) {
+        metrics_->AddTransferFailure();
+    }
+    if (result != ErrorCode::OK) {
+        if (!read->record.slices.empty()) {
+            const auto& slice = read->record.slices.front();
+            LOG(ERROR) << "vchunk read failed tenant=" << tenant_id.value()
+                       << " key_id=" << SafeKeyId(tenant_id, key)
+                       << " vchunk_id=" << read->record.vchunk_id
+                       << " status=" << static_cast<int>(read->record.status)
+                       << " slice_index=" << slice.slice_index
+                       << " segment=" << slice.target_segment_name
+                       << " slice_count=" << read->record.slice_count
+                       << " error=" << static_cast<int>(result);
+        }
+    }
+    metrics_->Observe(
+        VChunkOperation::GET, result == ErrorCode::OK,
+        std::chrono::duration_cast<std::chrono::microseconds>(Clock::now() -
+                                                              started)
+            .count());
+    return result;
+}
+
+ErrorCode VChunkClient::Remove(const TenantId& tenant_id,
+                               const std::string& key) {
+    const auto started = Clock::now();
+    if (!enabled_) {
+        return legacy_.Remove(tenant_id, key);
+    }
+    if (!now_ms_) {
+        metrics_->Observe(VChunkOperation::REMOVE, false, 0);
+        return ErrorCode::INVALID_PARAMS;
+    }
+    auto result = control_plane_->Remove(tenant_id, key, now_ms_());
+    if (result == ErrorCode::RPC_TIMEOUT || result == ErrorCode::RPC_FAIL) {
+        metrics_->AddRetry();
+        result = control_plane_->Remove(tenant_id, key, now_ms_());
+    }
+    metrics_->Observe(
+        VChunkOperation::REMOVE, result == ErrorCode::OK,
+        std::chrono::duration_cast<std::chrono::microseconds>(Clock::now() -
+                                                              started)
+            .count());
+    return result;
+}
+
+std::vector<ErrorCode> VChunkClient::BatchPut(
+    const TenantId& tenant_id, const std::vector<PutRequest>& requests) {
+    std::vector<ErrorCode> results;
+    results.reserve(requests.size());
+    for (const auto& request : requests) {
+        results.push_back(
+            Put(tenant_id, request.key, request.source, request.length));
+    }
+    return results;
+}
+
+std::vector<ErrorCode> VChunkClient::BatchGet(
+    const TenantId& tenant_id, const std::vector<GetRequest>& requests) {
+    std::vector<ErrorCode> results;
+    results.reserve(requests.size());
+    for (const auto& request : requests) {
+        results.push_back(Get(tenant_id, request.key, request.destination,
+                              request.length));
+    }
+    return results;
+}
+
+std::vector<ErrorCode> VChunkClient::BatchRemove(
+    const TenantId& tenant_id, const std::vector<std::string>& keys) {
+    std::vector<ErrorCode> results;
+    results.reserve(keys.size());
+    for (const auto& key : keys) {
+        results.push_back(Remove(tenant_id, key));
+    }
+    return results;
+}
+
+VChunkMetricsSnapshot VChunkClient::MetricsSnapshot() const {
+    return metrics_->Snapshot();
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/vchunk_config.cpp b/mooncake-store/src/vchunk_config.cpp
new file mode 100644
index 0000000000..93df6ccc28
--- /dev/null
+++ b/mooncake-store/src/vchunk_config.cpp
@@ -0,0 +1,29 @@
+#include "vchunk_config.h"
+
+namespace mooncake {
+
+VCSliceSizeLevel SelectVChunkSliceSize(uint64_t value_size,
+                                      bool is_ssd_segment) {
+    if (is_ssd_segment || value_size < 64U * 1024U) {
+        return VCSliceSizeLevel::k4K;
+    }
+    if (value_size < 256U * 1024U) {
+        return VCSliceSizeLevel::k64K;
+    }
+    if (value_size < 1024U * 1024U) {
+        return VCSliceSizeLevel::k256K;
+    }
+    return VCSliceSizeLevel::k1M;
+}
+
+ErrorCode VChunkConfig::Validate() const {
+    if (creating_timeout_ms == 0 || releasing_timeout_ms == 0 ||
+        max_slice_count == 0 || max_metadata_bytes == 0 ||
+        max_creating_objects == 0 || reaper_interval_ms == 0 ||
+        reaper_max_scan == 0) {
+        return ErrorCode::INVALID_PARAMS;
+    }
+    return ErrorCode::OK;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/vchunk_control_plane.cpp b/mooncake-store/src/vchunk_control_plane.cpp
new file mode 100644
index 0000000000..fa44c85e7c
--- /dev/null
+++ b/mooncake-store/src/vchunk_control_plane.cpp
@@ -0,0 +1,107 @@
+#include "vchunk_control_plane.h"
+
+#include "master_client.h"
+#include "master_service.h"
+
+namespace mooncake {
+
+namespace {
+
+class RpcReadLeaseGuard {
+   public:
+    RpcReadLeaseGuard(MasterClient& master, std::string tenant_id,
+                      std::string key, std::string lease_id)
+        : master_(master),
+          tenant_id_(std::move(tenant_id)),
+          key_(std::move(key)),
+          lease_id_(std::move(lease_id)) {}
+
+    ~RpcReadLeaseGuard() {
+        (void)master_.ReleaseVChunkReadLease(tenant_id_, key_, lease_id_);
+    }
+
+   private:
+    MasterClient& master_;
+    std::string tenant_id_;
+    std::string key_;
+    std::string lease_id_;
+};
+
+}  // namespace
+
+tl::expected<VChunkMetadataRecord, ErrorCode>
+LocalVChunkControlPlane::PutStart(const TenantId& tenant_id,
+                                  const std::string& key, uint64_t total_size,
+                                  int64_t now_ms) {
+    return master_.VChunkPutStart(tenant_id, key, total_size, false, now_ms);
+}
+
+ErrorCode LocalVChunkControlPlane::PutEnd(const TenantId& tenant_id,
+                                          const std::string& key,
+                                          const std::string& vchunk_id,
+                                          int64_t now_ms) {
+    return master_.VChunkPutEnd(tenant_id, key, vchunk_id, now_ms);
+}
+
+ErrorCode LocalVChunkControlPlane::PutRevoke(const TenantId& tenant_id,
+                                             const std::string& key,
+                                             const std::string& vchunk_id) {
+    return master_.VChunkPutRevoke(tenant_id, key, vchunk_id);
+}
+
+tl::expected<VChunkControlPlaneRead, ErrorCode> LocalVChunkControlPlane::Get(
+    const TenantId& tenant_id, const std::string& key) {
+    auto handle = master_.AcquireVChunkRead(tenant_id, key);
+    if (!handle) return tl::unexpected(handle.error());
+    auto lifetime = std::make_shared<VChunkMasterManager::ReadHandle>(
+        std::move(*handle));
+    return VChunkControlPlaneRead{lifetime->record(), std::move(lifetime)};
+}
+
+ErrorCode LocalVChunkControlPlane::Remove(const TenantId& tenant_id,
+                                          const std::string& key,
+                                          int64_t now_ms) {
+    return master_.RemoveVChunk(tenant_id, key, now_ms);
+}
+
+tl::expected<VChunkMetadataRecord, ErrorCode>
+RpcVChunkControlPlane::PutStart(const TenantId& tenant_id,
+                                const std::string& key, uint64_t total_size,
+                                int64_t now_ms) {
+    return master_.VChunkPutStart(tenant_id.value(), key, total_size, now_ms);
+}
+
+ErrorCode RpcVChunkControlPlane::PutEnd(const TenantId& tenant_id,
+                                        const std::string& key,
+                                        const std::string& vchunk_id,
+                                        int64_t now_ms) {
+    auto result =
+        master_.VChunkPutEnd(tenant_id.value(), key, vchunk_id, now_ms);
+    return result ? ErrorCode::OK : result.error();
+}
+
+ErrorCode RpcVChunkControlPlane::PutRevoke(const TenantId& tenant_id,
+                                           const std::string& key,
+                                           const std::string& vchunk_id) {
+    auto result = master_.VChunkPutRevoke(tenant_id.value(), key, vchunk_id);
+    return result ? ErrorCode::OK : result.error();
+}
+
+tl::expected<VChunkControlPlaneRead, ErrorCode> RpcVChunkControlPlane::Get(
+    const TenantId& tenant_id, const std::string& key) {
+    auto record = master_.GetVChunk(tenant_id.value(), key);
+    if (!record) return tl::unexpected(record.error());
+    auto lifetime = std::make_shared<RpcReadLeaseGuard>(
+        master_, tenant_id.value(), key, record->lease_id);
+    return VChunkControlPlaneRead{std::move(record->record),
+                                  std::move(lifetime)};
+}
+
+ErrorCode RpcVChunkControlPlane::Remove(const TenantId& tenant_id,
+                                        const std::string& key,
+                                        int64_t now_ms) {
+    auto result = master_.RemoveVChunk(tenant_id.value(), key, now_ms);
+    return result ? ErrorCode::OK : result.error();
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/vchunk_master_manager.cpp b/mooncake-store/src/vchunk_master_manager.cpp
new file mode 100644
index 0000000000..995e83b562
--- /dev/null
+++ b/mooncake-store/src/vchunk_master_manager.cpp
@@ -0,0 +1,371 @@
+#include "vchunk_master_manager.h"
+
+#include <algorithm>
+#include <iterator>
+#include <limits>
+#include <utility>
+
+#include "types.h"
+
+namespace mooncake {
+
+VChunkMasterManager::VChunkMasterManager(
+    VChunkConfig config, std::shared_ptr<VChunkMetadataStore> metadata_store,
+    std::shared_ptr<VChunkMetrics> metrics)
+    : config_(std::move(config)),
+      metadata_store_(metadata_store ? std::move(metadata_store)
+                                     : std::make_shared<
+                                           InMemoryVChunkMetadataStore>()),
+      metrics_(metrics ? std::move(metrics)
+                       : std::make_shared<VChunkMetrics>()) {}
+
+std::string VChunkMasterManager::ScopedKey(const TenantId& tenant_id,
+                                           const std::string& key) {
+    return tenant_id.MakeScopedKey(key);
+}
+
+tl::expected<VChunkMetadataRecord, ErrorCode> VChunkMasterManager::PutStart(
+    const AllocatorManager& allocator_manager, const TenantId& tenant_id,
+    const std::string& key, uint64_t total_size, bool is_ssd_segment,
+    int64_t now_ms, const std::set<std::string>& excluded_segments) {
+    if (!config_.enabled || config_.Validate() != ErrorCode::OK ||
+        !tenant_id.IsValid() || key.empty() || total_size == 0 || now_ms < 0) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    // The current version owns buffers from SegmentManager and supports
+    // memory segments only. SSD/NoF routing is introduced in a later stage.
+    if (is_ssd_segment) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    const auto scoped_key = ScopedKey(tenant_id, key);
+    {
+        std::lock_guard<std::mutex> guard(mutex_);
+        if (entries_.contains(scoped_key) || pending_puts_.contains(scoped_key)) {
+            return tl::make_unexpected(ErrorCode::OBJECT_ALREADY_EXISTS);
+        }
+        size_t creating = 0;
+        for (const auto& [_, entry] : entries_) {
+            creating += entry->record.status == VChunkStatus::CREATING;
+        }
+        if (creating + pending_puts_.size() >= config_.max_creating_objects) {
+            return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
+        }
+        pending_puts_.insert(scoped_key);
+    }
+
+    const auto slice_size_level =
+        SelectVChunkSliceSize(total_size, is_ssd_segment);
+    const uint64_t slice_size = SliceSizeLevelToBytes(slice_size_level);
+    if (total_size > std::numeric_limits<uint64_t>::max() - (slice_size - 1) ||
+        (total_size + slice_size - 1) / slice_size >
+            config_.max_slice_count) {
+        ReleasePendingPut(scoped_key);
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+
+    auto allocation = AllocateVChunk(allocator_manager, total_size,
+                                     slice_size_level, excluded_segments);
+    if (!allocation) {
+        ReleasePendingPut(scoped_key);
+        metrics_->AddAllocationFailure();
+        return tl::make_unexpected(allocation.error());
+    }
+
+    auto entry = std::make_shared<Entry>();
+    auto& record = entry->record;
+    record.vchunk_id = UuidToString(generate_uuid());
+    record.tenant_id = tenant_id.value();
+    record.key = key;
+    record.total_size = total_size;
+    record.slice_count =
+        static_cast<uint32_t>(allocation->allocations.size());
+    record.slice_size_level = slice_size_level;
+    record.row_size = static_cast<uint32_t>(allocation->row_size);
+    record.status = VChunkStatus::CREATING;
+    record.created_at_ms = now_ms;
+    record.last_updated_at_ms = now_ms;
+    record.slices.reserve(record.slice_count);
+    entry->buffers.reserve(record.slice_count);
+    for (auto& allocated : allocation->allocations) {
+        record.slices.push_back(VCSliceDescriptor{
+            allocated.slice_index, allocated.segment_name,
+            allocated.target_offset, allocated.logical_length,
+            allocated.allocated_length, VCSliceStatus::PENDING, 0});
+        entry->buffers.push_back(std::move(allocated.buffer));
+    }
+    const auto serialized = SerializeVChunkMetadata(record, config_);
+    if (!serialized) {
+        ReleasePendingPut(scoped_key);
+        return tl::make_unexpected(serialized.error());
+    }
+    if (const auto error = metadata_store_->Put(record);
+        error != ErrorCode::OK) {
+        ReleasePendingPut(scoped_key);
+        return tl::make_unexpected(error);
+    }
+
+    std::lock_guard<std::mutex> guard(mutex_);
+    pending_puts_.erase(scoped_key);
+    const auto snapshot = record;
+    entries_.emplace(scoped_key, std::move(entry));
+    metrics_->AddSlices(snapshot.slice_count);
+    metrics_->ObserveLayout(snapshot);
+    metrics_->AddMetadataBytes(serialized->size());
+    RefreshStateMetricsLocked();
+    return snapshot;
+}
+
+ErrorCode VChunkMasterManager::PutEnd(const TenantId& tenant_id,
+                                      const std::string& key,
+                                      const std::string& vchunk_id,
+                                      int64_t now_ms) {
+    std::lock_guard<std::mutex> guard(mutex_);
+    const auto it = entries_.find(ScopedKey(tenant_id, key));
+    if (it == entries_.end()) {
+        return ErrorCode::OBJECT_NOT_FOUND;
+    }
+    auto& record = it->second->record;
+    if (record.vchunk_id != vchunk_id) {
+        return ErrorCode::INVALID_VERSION;
+    }
+    if (record.status == VChunkStatus::ACTIVE) {
+        return ErrorCode::OK;
+    }
+    if (ValidateVChunkTransition(record.status, VChunkStatus::ACTIVE) !=
+            ErrorCode::OK ||
+        now_ms < record.last_updated_at_ms) {
+        return ErrorCode::INVALID_PARAMS;
+    }
+    auto durable = record;
+    for (auto& slice : durable.slices) {
+        slice.status = VCSliceStatus::COMPLETED;
+    }
+    durable.status = VChunkStatus::ACTIVE;
+    durable.last_updated_at_ms = now_ms;
+    if (const auto error = metadata_store_->Put(durable);
+        error != ErrorCode::OK) {
+        return error;
+    }
+    record = std::move(durable);
+    RefreshStateMetricsLocked();
+    return ErrorCode::OK;
+}
+
+ErrorCode VChunkMasterManager::PutRevoke(const TenantId& tenant_id,
+                                         const std::string& key,
+                                         const std::string& vchunk_id) {
+    std::lock_guard<std::mutex> guard(mutex_);
+    const auto it = entries_.find(ScopedKey(tenant_id, key));
+    if (it == entries_.end()) {
+        return ErrorCode::OK;
+    }
+    if (it->second->record.vchunk_id != vchunk_id) {
+        return ErrorCode::INVALID_VERSION;
+    }
+    if (it->second->record.status != VChunkStatus::CREATING &&
+        it->second->record.status != VChunkStatus::FAILED) {
+        return ErrorCode::INVALID_PARAMS;
+    }
+    if (const auto error = metadata_store_->Remove(it->second->record);
+        error != ErrorCode::OK) {
+        return error;
+    }
+    entries_.erase(it);
+    metrics_->AddRollback();
+    RefreshStateMetricsLocked();
+    return ErrorCode::OK;
+}
+
+tl::expected<VChunkMetadataRecord, ErrorCode> VChunkMasterManager::Get(
+    const TenantId& tenant_id, const std::string& key) const {
+    auto handle = AcquireRead(tenant_id, key);
+    if (!handle) {
+        return tl::make_unexpected(handle.error());
+    }
+    return handle->record();
+}
+
+tl::expected<VChunkMasterManager::ReadHandle, ErrorCode>
+VChunkMasterManager::AcquireRead(const TenantId& tenant_id,
+                                 const std::string& key) const {
+    std::lock_guard<std::mutex> guard(mutex_);
+    const auto it = entries_.find(ScopedKey(tenant_id, key));
+    if (it == entries_.end()) {
+        return tl::make_unexpected(ErrorCode::OBJECT_NOT_FOUND);
+    }
+    if (it->second->record.status != VChunkStatus::ACTIVE) {
+        return tl::make_unexpected(ErrorCode::REPLICA_IS_NOT_READY);
+    }
+    ReadHandle handle;
+    handle.record_ = it->second->record;
+    handle.lifetime_ = it->second;
+    return handle;
+}
+
+ErrorCode VChunkMasterManager::Remove(const TenantId& tenant_id,
+                                      const std::string& key,
+                                      int64_t now_ms) {
+    std::lock_guard<std::mutex> guard(mutex_);
+    const auto scoped_key = ScopedKey(tenant_id, key);
+    const auto it = entries_.find(scoped_key);
+    if (it == entries_.end()) {
+        return ErrorCode::OK;
+    }
+    auto& record = it->second->record;
+    if ((record.status != VChunkStatus::ACTIVE &&
+         record.status != VChunkStatus::RELEASING) ||
+        now_ms < record.last_updated_at_ms) {
+        return ErrorCode::INVALID_PARAMS;
+    }
+    if (record.status == VChunkStatus::ACTIVE) {
+        auto releasing = record;
+        releasing.status = VChunkStatus::RELEASING;
+        releasing.last_updated_at_ms = now_ms;
+        if (const auto error = metadata_store_->Put(releasing);
+            error != ErrorCode::OK) {
+            return error;
+        }
+        record = std::move(releasing);
+    }
+    if (const auto error = metadata_store_->Remove(record);
+        error != ErrorCode::OK) {
+        return error;
+    }
+    entries_.erase(it);
+    RefreshStateMetricsLocked();
+    return ErrorCode::OK;
+}
+
+ErrorCode VChunkMasterManager::Recover(int64_t now_ms,
+                                       OwnershipPredicate owns) {
+    if (now_ms < 0) {
+        return ErrorCode::INVALID_PARAMS;
+    }
+    auto records = metadata_store_->List();
+    if (!records) {
+        return records.error();
+    }
+    std::lock_guard<std::mutex> guard(mutex_);
+    // Validate the complete snapshot before mutating the store so recovery is
+    // deterministic even when List() returns records in a different order.
+    for (const auto& record : *records) {
+        if (owns && !owns(record)) {
+            continue;
+        }
+        const auto validation = ValidateVChunkMetadata(record, config_);
+        if (validation != ErrorCode::OK) {
+            return validation;
+        }
+        // Allocator reservations are process-local. A persisted ACTIVE record
+        // must never be published until its exact ranges have been reserved
+        // again, otherwise new allocations can overlap it.
+        if (record.status == VChunkStatus::ACTIVE) {
+            return ErrorCode::REPLICA_IS_GONE;
+        }
+    }
+    for (const auto& record : *records) {
+        if (owns && !owns(record)) {
+            continue;
+        }
+        // CREATING records cannot be resumed safely either: their buffers were
+        // owned by the previous process. Treat all incomplete writes as stale.
+        if (record.status == VChunkStatus::CREATING ||
+            record.status == VChunkStatus::RELEASING ||
+            record.status == VChunkStatus::RELEASED ||
+            record.status == VChunkStatus::FAILED) {
+            const auto error = metadata_store_->Remove(record);
+            if (error != ErrorCode::OK) {
+                return error;
+            }
+            continue;
+        }
+    }
+    RefreshStateMetricsLocked();
+    return ErrorCode::OK;
+}
+
+tl::expected<size_t, ErrorCode> VChunkMasterManager::ReapExpired(
+    int64_t now_ms, size_t max_scan, OwnershipPredicate owns) {
+    if (now_ms < 0 || max_scan == 0) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    std::lock_guard<std::mutex> guard(mutex_);
+    size_t scanned = 0;
+    size_t removed = 0;
+    if (entries_.empty()) {
+        reaper_cursor_key_.clear();
+        return removed;
+    }
+    auto it = reaper_cursor_key_.empty() ? entries_.begin()
+                                         : entries_.find(reaper_cursor_key_);
+    if (it == entries_.end()) it = entries_.begin();
+    const size_t scan_limit = std::min(max_scan, entries_.size());
+    while (!entries_.empty() && scanned < scan_limit) {
+        ++scanned;
+        auto next = std::next(it);
+        if (next == entries_.end()) next = entries_.begin();
+        const auto& record = it->second->record;
+        if (owns && !owns(record)) {
+            it = next;
+            continue;
+        }
+        const bool time_is_valid = now_ms >= record.last_updated_at_ms;
+        const auto age = time_is_valid
+                             ? static_cast<uint64_t>(now_ms -
+                                                     record.last_updated_at_ms)
+                             : 0;
+        const bool expired =
+            time_is_valid &&
+            ((record.status == VChunkStatus::CREATING &&
+              age >= config_.creating_timeout_ms) ||
+             (record.status == VChunkStatus::RELEASING &&
+              age >= config_.releasing_timeout_ms));
+        if (!expired) {
+            it = next;
+            continue;
+        }
+        if (const auto error = metadata_store_->Remove(record);
+            error != ErrorCode::OK) {
+            return tl::make_unexpected(error);
+        }
+        entries_.erase(it);
+        ++removed;
+        metrics_->AddRollback();
+        if (entries_.empty()) break;
+        it = next;
+    }
+    reaper_cursor_key_ = entries_.empty() ? std::string() : it->first;
+    RefreshStateMetricsLocked();
+    return removed;
+}
+
+VChunkMetricsSnapshot VChunkMasterManager::MetricsSnapshot() const {
+    return metrics_->Snapshot();
+}
+
+void VChunkMasterManager::RefreshStateMetricsLocked() {
+    std::array<uint64_t, 5> counts{};
+    uint64_t allocated_bytes = 0;
+    for (const auto& [_, entry] : entries_) {
+        ++counts[static_cast<size_t>(entry->record.status)];
+        for (const auto& buffer : entry->buffers) {
+            if (buffer) allocated_bytes += buffer->size();
+        }
+    }
+    for (size_t i = 0; i < counts.size(); ++i) {
+        metrics_->SetStateCount(static_cast<VChunkStatus>(i), counts[i]);
+    }
+    metrics_->SetAllocatedBytes(allocated_bytes);
+}
+
+size_t VChunkMasterManager::SizeForTesting() const {
+    std::lock_guard<std::mutex> guard(mutex_);
+    return entries_.size();
+}
+
+void VChunkMasterManager::ReleasePendingPut(const std::string& scoped_key) {
+    std::lock_guard<std::mutex> guard(mutex_);
+    pending_puts_.erase(scoped_key);
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/vchunk_metadata.cpp b/mooncake-store/src/vchunk_metadata.cpp
new file mode 100644
index 0000000000..2928d129d7
--- /dev/null
+++ b/mooncake-store/src/vchunk_metadata.cpp
@@ -0,0 +1,191 @@
+#include "vchunk_metadata.h"
+
+#include <limits>
+#include <unordered_set>
+#include <utility>
+
+namespace mooncake {
+namespace {
+
+bool IsKnownSliceSize(VCSliceSizeLevel level) {
+    switch (level) {
+        case VCSliceSizeLevel::k4K:
+        case VCSliceSizeLevel::k64K:
+        case VCSliceSizeLevel::k256K:
+        case VCSliceSizeLevel::k1M:
+            return true;
+    }
+    return false;
+}
+
+bool IsKnownSliceStatus(VCSliceStatus status) {
+    switch (status) {
+        case VCSliceStatus::PENDING:
+        case VCSliceStatus::COMPLETED:
+        case VCSliceStatus::FAILED:
+            return true;
+    }
+    return false;
+}
+
+bool IsKnownVChunkStatus(VChunkStatus status) {
+    switch (status) {
+        case VChunkStatus::CREATING:
+        case VChunkStatus::ACTIVE:
+        case VChunkStatus::RELEASING:
+        case VChunkStatus::RELEASED:
+        case VChunkStatus::FAILED:
+            return true;
+    }
+    return false;
+}
+
+}  // namespace
+
+ErrorCode ValidateVChunkMetadata(const VChunkMetadataRecord& record,
+                                 const VChunkConfig& config) {
+    if (config.Validate() != ErrorCode::OK) {
+        return ErrorCode::INVALID_PARAMS;
+    }
+    if (record.schema_version != kVChunkMetadataSchemaVersion) {
+        return ErrorCode::INVALID_VERSION;
+    }
+    if (record.vchunk_id.empty() || record.tenant_id.empty() ||
+        record.key.empty() || record.total_size == 0 ||
+        !IsKnownSliceSize(record.slice_size_level) ||
+        !IsKnownVChunkStatus(record.status)) {
+        return ErrorCode::INVALID_PARAMS;
+    }
+    if (record.slice_count == 0 ||
+        record.slice_count > config.max_slice_count ||
+        record.slices.size() != record.slice_count || record.row_size == 0 ||
+        record.row_size > record.slice_count || record.created_at_ms < 0 ||
+        record.last_updated_at_ms < record.created_at_ms) {
+        return ErrorCode::INVALID_PARAMS;
+    }
+
+    const uint64_t slice_size =
+        SliceSizeLevelToBytes(record.slice_size_level);
+    uint64_t covered_bytes = 0;
+    std::unordered_set<std::string> segments_in_row;
+    segments_in_row.reserve(record.row_size);
+    for (uint32_t i = 0; i < record.slice_count; ++i) {
+        const auto& slice = record.slices[i];
+        if (slice.slice_index != i || slice.target_segment_name.empty() ||
+            slice.logical_length == 0 ||
+            slice.logical_length > slice.allocated_length ||
+            slice.allocated_length < slice_size ||
+            !IsKnownSliceStatus(slice.status) ||
+            slice.retry_count > config.max_slice_retry) {
+            return ErrorCode::INVALID_PARAMS;
+        }
+        if (slice.target_offset >
+            std::numeric_limits<uint64_t>::max() - slice.allocated_length) {
+            return ErrorCode::INVALID_PARAMS;
+        }
+        if (covered_bytes >
+            std::numeric_limits<uint64_t>::max() - slice.logical_length) {
+            return ErrorCode::INVALID_PARAMS;
+        }
+        covered_bytes += slice.logical_length;
+
+        if (i % record.row_size == 0) {
+            segments_in_row.clear();
+        }
+        if (!segments_in_row.insert(slice.target_segment_name).second) {
+            return ErrorCode::INVALID_PARAMS;
+        }
+    }
+
+    if (covered_bytes != record.total_size) {
+        return ErrorCode::INVALID_PARAMS;
+    }
+    return ErrorCode::OK;
+}
+
+ErrorCode ValidateVChunkTransition(VChunkStatus from, VChunkStatus to) {
+    if (!IsKnownVChunkStatus(from) || !IsKnownVChunkStatus(to)) {
+        return ErrorCode::INVALID_PARAMS;
+    }
+    if (from == to) {
+        return ErrorCode::OK;
+    }
+    switch (from) {
+        case VChunkStatus::CREATING:
+            return (to == VChunkStatus::ACTIVE || to == VChunkStatus::FAILED)
+                       ? ErrorCode::OK
+                       : ErrorCode::INVALID_PARAMS;
+        case VChunkStatus::ACTIVE:
+            return (to == VChunkStatus::RELEASING ||
+                    to == VChunkStatus::FAILED)
+                       ? ErrorCode::OK
+                       : ErrorCode::INVALID_PARAMS;
+        case VChunkStatus::RELEASING:
+            return (to == VChunkStatus::RELEASED ||
+                    to == VChunkStatus::FAILED)
+                       ? ErrorCode::OK
+                       : ErrorCode::INVALID_PARAMS;
+        case VChunkStatus::FAILED:
+            return to == VChunkStatus::RELEASING ? ErrorCode::OK
+                                                 : ErrorCode::INVALID_PARAMS;
+        case VChunkStatus::RELEASED:
+            return ErrorCode::INVALID_PARAMS;
+    }
+    return ErrorCode::INVALID_PARAMS;
+}
+
+tl::expected<std::vector<char>, ErrorCode> SerializeVChunkMetadata(
+    const VChunkMetadataRecord& record, const VChunkConfig& config) {
+    const auto validation = ValidateVChunkMetadata(record, config);
+    if (validation != ErrorCode::OK) {
+        return tl::make_unexpected(validation);
+    }
+    auto bytes = struct_pack::serialize(record);
+    if (bytes.size() > config.max_metadata_bytes) {
+        return tl::make_unexpected(ErrorCode::BUFFER_OVERFLOW);
+    }
+    return bytes;
+}
+
+tl::expected<VChunkMetadataRecord, ErrorCode> DeserializeVChunkMetadata(
+    const std::vector<char>& bytes, const VChunkConfig& config) {
+    if (config.Validate() != ErrorCode::OK || bytes.empty()) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    if (bytes.size() > config.max_metadata_bytes) {
+        return tl::make_unexpected(ErrorCode::BUFFER_OVERFLOW);
+    }
+
+    VChunkMetadataRecord record;
+    if (struct_pack::deserialize_to(record, bytes) != struct_pack::errc::ok) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    const auto validation = ValidateVChunkMetadata(record, config);
+    if (validation != ErrorCode::OK) {
+        return tl::make_unexpected(validation);
+    }
+    return record;
+}
+
+VChunkMetadata::VChunkMetadata(VChunkMetadataRecord record)
+    : record_(std::move(record)) {}
+
+VChunkMetadataRecord VChunkMetadata::Snapshot() const {
+    SpinLocker guard(&lock_);
+    return record_;
+}
+
+ErrorCode VChunkMetadata::TransitionTo(VChunkStatus next,
+                                       int64_t updated_at_ms) {
+    SpinLocker guard(&lock_);
+    const auto validation = ValidateVChunkTransition(record_.status, next);
+    if (validation != ErrorCode::OK ||
+        updated_at_ms < record_.last_updated_at_ms) {
+        return ErrorCode::INVALID_PARAMS;
+    }
+    record_.status = next;
+    record_.last_updated_at_ms = updated_at_ms;
+    return ErrorCode::OK;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/vchunk_metadata_store.cpp b/mooncake-store/src/vchunk_metadata_store.cpp
new file mode 100644
index 0000000000..594e60e65c
--- /dev/null
+++ b/mooncake-store/src/vchunk_metadata_store.cpp
@@ -0,0 +1,200 @@
+#include "vchunk_metadata_store.h"
+
+#include <utility>
+
+#include <iomanip>
+#include <sstream>
+
+#if __has_include(<jsoncpp/json/json.h>)
+#include <jsoncpp/json/json.h>
+#else
+#include <json/json.h>
+#endif
+
+#include "etcd_helper.h"
+
+namespace mooncake {
+namespace {
+
+std::string HexEncode(std::string_view value) {
+    std::ostringstream stream;
+    stream << std::hex << std::setfill('0');
+    for (const unsigned char byte : value) {
+        stream << std::setw(2) << static_cast<unsigned>(byte);
+    }
+    return stream.str();
+}
+
+tl::expected<std::vector<char>, ErrorCode> HexDecode(std::string_view value) {
+    if (value.size() % 2 != 0) {
+        return tl::unexpected(ErrorCode::INVALID_VERSION);
+    }
+    auto digit = [](char c) -> int {
+        if (c >= '0' && c <= '9') return c - '0';
+        if (c >= 'a' && c <= 'f') return c - 'a' + 10;
+        if (c >= 'A' && c <= 'F') return c - 'A' + 10;
+        return -1;
+    };
+    std::vector<char> bytes;
+    bytes.reserve(value.size() / 2);
+    for (size_t i = 0; i < value.size(); i += 2) {
+        const int high = digit(value[i]);
+        const int low = digit(value[i + 1]);
+        if (high < 0 || low < 0) {
+            return tl::unexpected(ErrorCode::INVALID_VERSION);
+        }
+        bytes.push_back(static_cast<char>((high << 4) | low));
+    }
+    return bytes;
+}
+
+std::string MakeObjectIndexKey(std::string_view namespace_prefix,
+                               const VChunkMetadataRecord& record) {
+    return std::string(namespace_prefix) + "/objects/" +
+           HexEncode(record.tenant_id) + "/" + HexEncode(record.key);
+}
+
+std::string MakePersistentRecordKey(std::string_view namespace_prefix,
+                                    const VChunkMetadataRecord& record) {
+    return std::string(namespace_prefix) + "/records/" +
+           HexEncode(record.tenant_id) + "/" + record.vchunk_id;
+}
+
+std::string BytesToString(const std::vector<char>& bytes) {
+    return {bytes.data(), bytes.size()};
+}
+
+}  // namespace
+
+std::string MakeVChunkMetadataStoreKey(const VChunkMetadataRecord& record) {
+    return std::string(kVChunkMetadataNamespace) + "/" + record.tenant_id +
+           "/" + record.vchunk_id;
+}
+
+ErrorCode InMemoryVChunkMetadataStore::Put(
+    const VChunkMetadataRecord& record) {
+    std::lock_guard<std::mutex> guard(mutex_);
+    records_[MakeVChunkMetadataStoreKey(record)] = record;
+    return ErrorCode::OK;
+}
+
+ErrorCode InMemoryVChunkMetadataStore::Remove(
+    const VChunkMetadataRecord& record) {
+    std::lock_guard<std::mutex> guard(mutex_);
+    records_.erase(MakeVChunkMetadataStoreKey(record));
+    return ErrorCode::OK;
+}
+
+tl::expected<std::vector<VChunkMetadataRecord>, ErrorCode>
+InMemoryVChunkMetadataStore::List() {
+    std::lock_guard<std::mutex> guard(mutex_);
+    std::vector<VChunkMetadataRecord> result;
+    result.reserve(records_.size());
+    for (const auto& [_, record] : records_) {
+        result.push_back(record);
+    }
+    return result;
+}
+
+EtcdVChunkMetadataStore::EtcdVChunkMetadataStore(std::string endpoints,
+                                                 VChunkConfig config,
+                                                 std::string cluster_id)
+    : endpoints_(std::move(endpoints)),
+      config_(std::move(config)),
+      namespace_prefix_(std::string(kVChunkMetadataNamespace) + "/clusters/" +
+                        HexEncode(cluster_id)) {
+#ifdef STORE_USE_ETCD
+    connection_error_ = EtcdHelper::ConnectToEtcdStoreClient(endpoints_);
+#else
+    connection_error_ = ErrorCode::ETCD_OPERATION_ERROR;
+#endif
+}
+
+ErrorCode EtcdVChunkMetadataStore::Put(const VChunkMetadataRecord& record) {
+    if (connection_error_ != ErrorCode::OK) return connection_error_;
+    auto encoded = SerializeVChunkMetadata(record, config_);
+    if (!encoded) return encoded.error();
+    const auto metadata_key = MakePersistentRecordKey(namespace_prefix_, record);
+    const auto object_key = MakeObjectIndexKey(namespace_prefix_, record);
+    const auto value = HexEncode(BytesToString(*encoded));
+
+    if (record.status == VChunkStatus::CREATING) {
+        const auto error = EtcdHelper::TxnCompareAndPut(
+            {{object_key, EtcdHelper::TxnCompareKind::kKeyNotExists, {}},
+             {metadata_key, EtcdHelper::TxnCompareKind::kKeyNotExists, {}}},
+            {{object_key, record.vchunk_id}, {metadata_key, value}});
+        return error == ErrorCode::ETCD_TRANSACTION_FAIL
+                   ? ErrorCode::OBJECT_ALREADY_EXISTS
+                   : error;
+    }
+
+    std::string current;
+    EtcdRevisionId revision = 0;
+    auto error = EtcdHelper::Get(metadata_key.data(), metadata_key.size(),
+                                 current, revision);
+    if (error != ErrorCode::OK) return error;
+    return EtcdHelper::TxnCompareAndPut(
+        {{object_key, EtcdHelper::TxnCompareKind::kValueEquals,
+          record.vchunk_id},
+         {metadata_key, EtcdHelper::TxnCompareKind::kValueEquals, current}},
+        {{metadata_key, value}});
+}
+
+ErrorCode EtcdVChunkMetadataStore::Remove(
+    const VChunkMetadataRecord& record) {
+    if (connection_error_ != ErrorCode::OK) return connection_error_;
+    const auto metadata_key = MakePersistentRecordKey(namespace_prefix_, record);
+    const auto object_key = MakeObjectIndexKey(namespace_prefix_, record);
+    std::string current;
+    EtcdRevisionId revision = 0;
+    auto error = EtcdHelper::Get(metadata_key.data(), metadata_key.size(),
+                                 current, revision);
+    if (error == ErrorCode::ETCD_KEY_NOT_EXIST) return ErrorCode::OK;
+    if (error != ErrorCode::OK) return error;
+    return EtcdHelper::TxnCompareAndPut(
+        {{object_key, EtcdHelper::TxnCompareKind::kValueEquals,
+          record.vchunk_id},
+         {metadata_key, EtcdHelper::TxnCompareKind::kValueEquals, current}},
+        {}, {metadata_key, object_key});
+}
+
+tl::expected<std::vector<VChunkMetadataRecord>, ErrorCode>
+EtcdVChunkMetadataStore::List() {
+    if (connection_error_ != ErrorCode::OK) {
+        return tl::unexpected(connection_error_);
+    }
+    const std::string begin = namespace_prefix_ + "/";
+    const std::string end = namespace_prefix_ + "0";
+    std::string json;
+    EtcdRevisionId revision = 0;
+    auto error = EtcdHelper::GetRangeAsJson(begin.data(), begin.size(),
+                                            end.data(), end.size(), 0, json,
+                                            revision);
+    if (error != ErrorCode::OK) return tl::unexpected(error);
+
+    Json::Value root;
+    Json::CharReaderBuilder reader;
+    std::string errors;
+    std::istringstream stream(json);
+    if (!Json::parseFromStream(reader, stream, &root, &errors) ||
+        !root.isArray()) {
+        return tl::unexpected(ErrorCode::INTERNAL_ERROR);
+    }
+    std::vector<VChunkMetadataRecord> result;
+    for (const auto& item : root) {
+        if (!item.isObject() || !item["key"].isString() ||
+            !item["value"].isString()) {
+            return tl::unexpected(ErrorCode::INTERNAL_ERROR);
+        }
+        const auto key = item["key"].asString();
+        if (key.find(begin + "records/") != 0) continue;
+        auto bytes = HexDecode(item["value"].asString());
+        if (!bytes) return tl::unexpected(bytes.error());
+        auto record = DeserializeVChunkMetadata(*bytes, config_);
+        if (!record) return tl::unexpected(record.error());
+        result.push_back(std::move(*record));
+    }
+    return result;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/vchunk_metrics.cpp b/mooncake-store/src/vchunk_metrics.cpp
new file mode 100644
index 0000000000..2d689d98fe
--- /dev/null
+++ b/mooncake-store/src/vchunk_metrics.cpp
@@ -0,0 +1,71 @@
+#include "vchunk_metrics.h"
+
+#include <unordered_set>
+
+namespace mooncake {
+
+void VChunkMetrics::Observe(VChunkOperation operation, bool success,
+                            uint64_t latency_us) {
+    const auto index = static_cast<size_t>(operation);
+    ++requests_[index];
+    if (success) {
+        ++successes_[index];
+    }
+    latency_us_[index].fetch_add(latency_us);
+}
+
+void VChunkMetrics::SetStateCount(VChunkStatus state, uint64_t count) {
+    states_[static_cast<size_t>(state)].store(count);
+}
+
+void VChunkMetrics::ObserveLayout(const VChunkMetadataRecord& record) {
+    std::unordered_set<std::string> segments;
+    for (const auto& slice : record.slices) {
+        segments.insert(slice.target_segment_name);
+    }
+    segment_participations_.fetch_add(segments.size());
+    size_t bucket = 0;
+    switch (record.slice_size_level) {
+        case VCSliceSizeLevel::k4K:
+            bucket = 0;
+            break;
+        case VCSliceSizeLevel::k64K:
+            bucket = 1;
+            break;
+        case VCSliceSizeLevel::k256K:
+            bucket = 2;
+            break;
+        case VCSliceSizeLevel::k1M:
+            bucket = 3;
+            break;
+    }
+    slice_size_distribution_[bucket].fetch_add(record.slice_count);
+}
+
+VChunkMetricsSnapshot VChunkMetrics::Snapshot() const {
+    VChunkMetricsSnapshot result;
+    for (size_t i = 0; i < requests_.size(); ++i) {
+        result.requests[i] = requests_[i].load();
+        result.successes[i] = successes_[i].load();
+        result.latency_us[i] = latency_us_[i].load();
+    }
+    result.slices = slices_.load();
+    result.segment_participations = segment_participations_.load();
+    result.allocation_failures = allocation_failures_.load();
+    result.transfer_failures = transfer_failures_.load();
+    result.timeouts = timeouts_.load();
+    result.retries = retries_.load();
+    result.rollbacks = rollbacks_.load();
+    result.metadata_bytes = metadata_bytes_.load();
+    result.allocated_bytes = allocated_bytes_.load();
+    for (size_t i = 0; i < slice_size_distribution_.size(); ++i) {
+        result.slice_size_distribution[i] =
+            slice_size_distribution_[i].load();
+    }
+    for (size_t i = 0; i < states_.size(); ++i) {
+        result.states[i] = states_[i].load();
+    }
+    return result;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/vchunk_transfer_engine.cpp b/mooncake-store/src/vchunk_transfer_engine.cpp
new file mode 100644
index 0000000000..9029af37f0
--- /dev/null
+++ b/mooncake-store/src/vchunk_transfer_engine.cpp
@@ -0,0 +1,140 @@
+#include "vchunk_transfer_engine.h"
+
+#include <thread>
+#include <unordered_map>
+#include <vector>
+
+namespace mooncake {
+namespace {
+
+class BatchGuard {
+   public:
+    BatchGuard(TransferEngine& engine, size_t size)
+        : engine_(engine), id_(engine.allocateBatchID(size)) {}
+    ~BatchGuard() {
+        TryFree();
+    }
+    BatchID id() const { return id_; }
+    bool TryFree() {
+        if (id_ == INVALID_BATCH_ID) return true;
+        if (!engine_.freeBatchID(id_).ok()) return false;
+        id_ = INVALID_BATCH_ID;
+        return true;
+    }
+
+   private:
+    TransferEngine& engine_;
+    BatchID id_;
+};
+
+}  // namespace
+
+tl::expected<std::vector<TransferRequest>, ErrorCode>
+BuildVChunkTransferRequests(const VChunkMetadataRecord& record, void* buffer,
+                            size_t length, TransferRequest::OpCode opcode,
+                            const VChunkSegmentResolver& resolve_segment) {
+    VChunkConfig validation_config;
+    validation_config.enabled = true;
+    if (!buffer || !resolve_segment || record.total_size != length ||
+        record.slices.empty()) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    const auto validation = ValidateVChunkMetadata(record, validation_config);
+    if (validation != ErrorCode::OK) {
+        return tl::make_unexpected(validation);
+    }
+    std::unordered_map<std::string, SegmentHandle> handles;
+    std::vector<TransferRequest> requests;
+    requests.reserve(record.slices.size());
+    size_t logical_offset = 0;
+    for (const auto& slice : record.slices) {
+        auto it = handles.find(slice.target_segment_name);
+        if (it == handles.end()) {
+            auto handle = resolve_segment(slice.target_segment_name);
+            if (!handle) {
+                return tl::make_unexpected(handle.error());
+            }
+            it = handles.emplace(slice.target_segment_name, *handle).first;
+        }
+        if (slice.logical_length > length - logical_offset) {
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+        requests.push_back(TransferRequest{
+            opcode, static_cast<char*>(buffer) + logical_offset, it->second,
+            slice.target_offset, slice.logical_length});
+        logical_offset += slice.logical_length;
+    }
+    if (logical_offset != length) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    return requests;
+}
+
+ErrorCode TransferEngineVChunkDataPlane::Write(
+    const VChunkMetadataRecord& record, const void* source, size_t length,
+    std::chrono::steady_clock::time_point deadline) {
+    return Transfer(record, const_cast<void*>(source), length,
+                    TransferRequest::WRITE, deadline);
+}
+
+ErrorCode TransferEngineVChunkDataPlane::Read(
+    const VChunkMetadataRecord& record, void* destination, size_t length,
+    std::chrono::steady_clock::time_point deadline) {
+    return Transfer(record, destination, length, TransferRequest::READ,
+                    deadline);
+}
+
+ErrorCode TransferEngineVChunkDataPlane::Transfer(
+    const VChunkMetadataRecord& record, void* buffer, size_t length,
+    TransferRequest::OpCode opcode,
+    std::chrono::steady_clock::time_point deadline) {
+    auto requests = BuildVChunkTransferRequests(
+        record, buffer, length, opcode, [this](const std::string& segment) {
+            const auto handle = engine_.openSegment(segment);
+            if (handle == static_cast<SegmentHandle>(ERR_INVALID_ARGUMENT)) {
+                return tl::expected<SegmentHandle, ErrorCode>(
+                    tl::make_unexpected(ErrorCode::SEGMENT_NOT_FOUND));
+            }
+            return tl::expected<SegmentHandle, ErrorCode>(handle);
+        });
+    if (!requests) {
+        return requests.error();
+    }
+
+    BatchGuard batch(engine_, requests->size());
+    if (batch.id() == INVALID_BATCH_ID) {
+        return ErrorCode::TRANSFER_FAIL;
+    }
+    const bool submit_failed =
+        !engine_.submitTransfer(batch.id(), *requests).ok();
+    if (submit_failed && batch.TryFree()) return ErrorCode::TRANSFER_FAIL;
+    bool deadline_exceeded = false;
+    for (;;) {
+        deadline_exceeded = deadline_exceeded ||
+                            std::chrono::steady_clock::now() >= deadline;
+        TransferStatus status{};
+        if (!engine_.getBatchTransferStatus(batch.id(), status).ok()) {
+            // Do not release an in-flight batch: TransferEngine may still be
+            // using the caller's buffer. Keep draining until a terminal state.
+            if (batch.TryFree()) return ErrorCode::TRANSFER_FAIL;
+            std::this_thread::sleep_for(std::chrono::milliseconds(1));
+            continue;
+        }
+        if (status.s == TransferStatusEnum::COMPLETED) {
+            if (submit_failed) return ErrorCode::TRANSFER_FAIL;
+            if (deadline_exceeded) return ErrorCode::RPC_TIMEOUT;
+            return status.transferred_bytes == length ? ErrorCode::OK
+                                                      : ErrorCode::TRANSFER_FAIL;
+        }
+        if (status.s == TransferStatusEnum::FAILED ||
+            status.s == TransferStatusEnum::TIMEOUT ||
+            status.s == TransferStatusEnum::CANCELED ||
+            status.s == TransferStatusEnum::INVALID) {
+            return deadline_exceeded ? ErrorCode::RPC_TIMEOUT
+                                     : ErrorCode::TRANSFER_FAIL;
+        }
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    }
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/tests/CMakeLists.txt b/mooncake-store/tests/CMakeLists.txt
index 303be02254..edf6ceb951 100644
--- a/mooncake-store/tests/CMakeLists.txt
+++ b/mooncake-store/tests/CMakeLists.txt
@@ -37,6 +37,15 @@ add_store_test(buffer_allocator_test buffer_allocator_test.cpp)
 add_store_test(runtime_accelerator_test runtime_accelerator_test.cpp)
 add_store_test(registered_pinned_memory_test registered_pinned_memory_test.cpp)
 add_store_test(allocation_strategy_test allocation_strategy_test.cpp)
+add_store_test(vchunk_config_test vchunk_config_test.cpp)
+add_store_test(vchunk_metadata_test vchunk_metadata_test.cpp)
+add_store_test(vchunk_allocation_strategy_test
+               vchunk_allocation_strategy_test.cpp)
+add_store_test(vchunk_master_manager_test vchunk_master_manager_test.cpp)
+add_store_test(vchunk_master_service_test vchunk_master_service_test.cpp)
+add_store_test(vchunk_client_test vchunk_client_test.cpp)
+add_store_test(vchunk_transfer_engine_test vchunk_transfer_engine_test.cpp)
+add_store_test(vchunk_metadata_store_test vchunk_metadata_store_test.cpp)
 add_store_test(replica_selection_test replica_selection_test.cpp)
 add_test(
   NAME replica_selection_env_opt_in_test
@@ -45,6 +54,7 @@ add_test(
 set_tests_properties(replica_selection_env_opt_in_test
                      PROPERTIES ENVIRONMENT "MC_STORE_REPLICA_SCORING=1")
 add_store_test(eviction_strategy_test eviction_strategy_test.cpp)
+add_store_test(io_pattern_framework_test io_pattern_framework_test.cpp)
 add_store_test(deadline_scheduler_test deadline_scheduler_test.cpp)
 add_store_test(kv_event_publisher_test kv_event_publisher_test.cpp)
 if(ENABLE_KV_EVENTS)
@@ -101,6 +111,8 @@ add_store_test(thread_pool_test thread_pool_test.cpp)
 add_store_test(transfer_task_test transfer_task_test.cpp)
 add_store_test(tenant_quota_test tenant_quota_test.cpp)
 add_store_test(tenant_id_test tenant_id_test.cpp)
+add_store_test(slot_hash_test slot_hash_test.cpp)
+add_store_test(partition_router_test partition_router_test.cpp)
 add_store_test(segment_test segment_test.cpp)
 add_store_test(offset_allocator_test offset_allocator_test.cpp)
 add_store_test(utils_test utils_test.cpp)
diff --git a/mooncake-store/tests/client_integration_test.cpp b/mooncake-store/tests/client_integration_test.cpp
index 6710096d87..6a2de62870 100644
--- a/mooncake-store/tests/client_integration_test.cpp
+++ b/mooncake-store/tests/client_integration_test.cpp
@@ -20,6 +20,7 @@
 
 #include "allocator.h"
 #include "client_service.h"
+#include "cvm/slot_hash.h"
 #include "types.h"
 #include "utils.h"
 #include "test_server_helpers.h"
@@ -788,10 +789,11 @@ TEST_F(ClientIntegrationTest, BatchPutMixedGroupIdsThroughClient) {
     auto find_group_id_on_different_shard = [](const std::string& key) {
         static constexpr size_t kMetadataShardCountForTest = 1024;
         const size_t key_shard =
-            std::hash<std::string>{}(key) % kMetadataShardCountForTest;
+            cvm::KeySlot(TenantId::Default(), key) %
+            kMetadataShardCountForTest;
         for (int i = 0; i < 10000; ++i) {
             std::string group_id = key + "_group_" + std::to_string(i);
-            if (std::hash<std::string>{}(group_id) %
+            if (cvm::KeySlot(TenantId::Default(), group_id) %
                     kMetadataShardCountForTest !=
                 key_shard) {
                 return group_id;
diff --git a/mooncake-store/tests/ha/master_service_ha_test.cpp b/mooncake-store/tests/ha/master_service_ha_test.cpp
index 265398ff47..4fadd69554 100644
--- a/mooncake-store/tests/ha/master_service_ha_test.cpp
+++ b/mooncake-store/tests/ha/master_service_ha_test.cpp
@@ -1600,7 +1600,7 @@ TEST_F(MasterServiceBatchRecordE2ETest, PromotionCatchesUpToDurablePrefix) {
 
     HotStandbyService standby(standby_config);
     standby.SetCatchUpBatchKvBackendForTesting(backend);
-    auto start_err = standby.Start("", "", cluster_id);
+    auto start_err = standby.Start({}, "", cluster_id);
     ASSERT_EQ(ErrorCode::OK, start_err);
     ASSERT_EQ(StandbyState::WATCHING, standby.GetState());
 
diff --git a/mooncake-store/tests/ha/standby/hot_standby_service_test.cpp b/mooncake-store/tests/ha/standby/hot_standby_service_test.cpp
index 317a48d799..be3612e774 100644
--- a/mooncake-store/tests/ha/standby/hot_standby_service_test.cpp
+++ b/mooncake-store/tests/ha/standby/hot_standby_service_test.cpp
@@ -26,6 +26,10 @@ namespace mooncake::test {
 
 namespace {
 
+// Existing batch fixtures use the unscoped (empty master_id) OpLog namespace.
+const ha::MasterSources kTestSources{
+    {.master_id = "", .address = "primary_unused"}};
+
 class FakeSnapshotProvider final : public SnapshotProvider {
    public:
     explicit FakeSnapshotProvider(
@@ -104,7 +108,7 @@ std::unique_ptr<HotStandbyService> CreateSnapshotOnlyReadyStandby(
 
     service->SetSnapshotProvider(std::make_unique<FakeSnapshotProvider>(
         std::optional<LoadedSnapshot>(snapshot)));
-    EXPECT_EQ(ErrorCode::OK, service->Start("", "", cluster_id));
+    EXPECT_EQ(ErrorCode::OK, service->Start({}, "", cluster_id));
     EXPECT_EQ(StandbyState::WATCHING, service->GetState());
     return service;
 }
@@ -121,7 +125,7 @@ TEST_F(HotStandbyServiceTest, TestStart) {
         << "Requires real etcd connection, run in integration environment.";
 #else
     ErrorCode err =
-        service_->Start("primary_unused", oplog_endpoints_, cluster_id_);
+        service_->Start(kTestSources, oplog_endpoints_, cluster_id_);
     EXPECT_EQ(ErrorCode::INTERNAL_ERROR, err);
     EXPECT_EQ(StandbyState::FAILED, service_->GetState());
 #endif
@@ -135,10 +139,10 @@ TEST_F(HotStandbyServiceTest, TestStart_AlreadyRunning) {
     // After the first Start fails and state becomes FAILED, the second Start
     // should still return INTERNAL_ERROR
     ErrorCode err1 =
-        service_->Start("primary_unused", oplog_endpoints_, cluster_id_);
+        service_->Start(kTestSources, oplog_endpoints_, cluster_id_);
     EXPECT_EQ(ErrorCode::INTERNAL_ERROR, err1);
     ErrorCode err2 =
-        service_->Start("primary_unused", oplog_endpoints_, cluster_id_);
+        service_->Start(kTestSources, oplog_endpoints_, cluster_id_);
     EXPECT_EQ(ErrorCode::INTERNAL_ERROR, err2);
 #endif
 }
@@ -149,7 +153,7 @@ TEST_F(HotStandbyServiceTest, TestStart_InvalidEtcdEndpoints) {
 #else
     std::string invalid_endpoints = "invalid_endpoint";
     ErrorCode err =
-        service_->Start("primary_unused", invalid_endpoints, cluster_id_);
+        service_->Start(kTestSources, invalid_endpoints, cluster_id_);
     EXPECT_EQ(ErrorCode::INTERNAL_ERROR, err);
 #endif
 }
@@ -178,7 +182,7 @@ TEST_F(HotStandbyServiceTest, TestStateTransition_StartToWatching) {
     // to FAILED
     EXPECT_EQ(StandbyState::STOPPED, service_->GetState());
     ErrorCode err =
-        service_->Start("primary_unused", oplog_endpoints_, cluster_id_);
+        service_->Start(kTestSources, oplog_endpoints_, cluster_id_);
     EXPECT_EQ(ErrorCode::INTERNAL_ERROR, err);
     EXPECT_EQ(StandbyState::FAILED, service_->GetState());
 #endif
@@ -191,8 +195,7 @@ TEST_F(HotStandbyServiceTest, TestStateTransition_ConnectionFailed) {
 #else
     // In non-etcd mode we cannot distinguish detailed connection errors; only
     // verify it doesn't crash
-    ErrorCode err =
-        service_->Start("primary_unused", "bad_endpoint", cluster_id_);
+    ErrorCode err = service_->Start(kTestSources, "bad_endpoint", cluster_id_);
     EXPECT_EQ(ErrorCode::INTERNAL_ERROR, err);
 #endif
 }
@@ -205,7 +208,7 @@ TEST_F(HotStandbyServiceTest, TestStateTransition_SyncFailed) {
     // In non-etcd mode, the sync phase is not actually executed; just ensure
     // the call is safe
     ErrorCode err =
-        service_->Start("primary_unused", oplog_endpoints_, cluster_id_);
+        service_->Start(kTestSources, oplog_endpoints_, cluster_id_);
     EXPECT_EQ(ErrorCode::INTERNAL_ERROR, err);
 #endif
 }
@@ -229,7 +232,7 @@ TEST_F(HotStandbyServiceTest, TestGetSyncStatus_AfterSync) {
 #else
     // In non-etcd mode, calling Start will not change applied/primary, but the
     // state machine enters FAILED
-    (void)service_->Start("primary_unused", oplog_endpoints_, cluster_id_);
+    (void)service_->Start(kTestSources, oplog_endpoints_, cluster_id_);
     StandbySyncStatus status = service_->GetSyncStatus();
     EXPECT_EQ(StandbyState::FAILED, status.state);
 #endif
@@ -280,7 +283,7 @@ TEST_F(HotStandbyServiceTest, TestPromoteAndExportSnapshot_FinalCatchUp) {
     service_->SetSnapshotProvider(std::make_unique<FakeSnapshotProvider>(
         std::optional<LoadedSnapshot>(snapshot)));
 
-    ASSERT_EQ(ErrorCode::OK, service_->Start("", "", cluster_id_));
+    ASSERT_EQ(ErrorCode::OK, service_->Start({}, "", cluster_id_));
     EXPECT_EQ(StandbyState::WATCHING, service_->GetState());
     EXPECT_EQ(10u, service_->GetLatestAppliedSequenceId());
 
@@ -310,7 +313,7 @@ TEST_F(HotStandbyServiceTest, TestWarmStart_WithLocalState) {
                     "test warm start.";
 #else
     // In non-etcd mode, only verify that Start is safe to call
-    (void)service_->Start("primary_unused", oplog_endpoints_, cluster_id_);
+    (void)service_->Start(kTestSources, oplog_endpoints_, cluster_id_);
     SUCCEED();
 #endif
 }
@@ -319,7 +322,7 @@ TEST_F(HotStandbyServiceTest, TestWarmStart_WithoutLocalState) {
 #ifdef STORE_USE_ETCD
     GTEST_SKIP() << "Requires real etcd and snapshot provider configuration.";
 #else
-    (void)service_->Start("primary_unused", oplog_endpoints_, cluster_id_);
+    (void)service_->Start(kTestSources, oplog_endpoints_, cluster_id_);
     SUCCEED();
 #endif
 }
@@ -332,7 +335,7 @@ TEST_F(HotStandbyServiceTest, TestWarmStart_WithSnapshot) {
     config_.enable_snapshot_bootstrap = true;
     // Recreate service to apply the new configuration
     service_.reset(new HotStandbyService(config_));
-    (void)service_->Start("primary_unused", oplog_endpoints_, cluster_id_);
+    (void)service_->Start(kTestSources, oplog_endpoints_, cluster_id_);
     SUCCEED();
 #endif
 }
@@ -347,7 +350,7 @@ TEST_F(HotStandbyServiceTest, TestStart_SnapshotOnlyWithSnapshot) {
     service_->SetSnapshotProvider(std::make_unique<FakeSnapshotProvider>(
         std::optional<LoadedSnapshot>(snapshot)));
 
-    auto err = service_->Start("", "", cluster_id_);
+    auto err = service_->Start({}, "", cluster_id_);
     EXPECT_EQ(ErrorCode::OK, err);
     EXPECT_EQ(StandbyState::WATCHING, service_->GetState());
     EXPECT_EQ(1u, service_->GetMetadataCount());
@@ -375,7 +378,7 @@ TEST_F(HotStandbyServiceTest,
         std::make_unique<FakeSnapshotProvider>(std::optional<LoadedSnapshot>(
             MakeSnapshot("20260330_120000_000", 42, "key-old", 4096))));
 
-    ASSERT_EQ(ErrorCode::OK, service_->Start("", "", cluster_id_));
+    ASSERT_EQ(ErrorCode::OK, service_->Start({}, "", cluster_id_));
     EXPECT_EQ(StandbyState::WATCHING, service_->GetState());
     EXPECT_EQ(42u, service_->GetLatestAppliedSequenceId());
     EXPECT_EQ(1u, service_->GetMetadataCount());
@@ -385,7 +388,7 @@ TEST_F(HotStandbyServiceTest,
         std::make_unique<FakeSnapshotProvider>(std::optional<LoadedSnapshot>(
             MakeSnapshot("20260330_121500_000", 84, "key-new", 8192))));
 
-    ASSERT_EQ(ErrorCode::OK, service_->Start("", "", cluster_id_));
+    ASSERT_EQ(ErrorCode::OK, service_->Start({}, "", cluster_id_));
     EXPECT_EQ(StandbyState::WATCHING, service_->GetState());
     EXPECT_EQ(84u, service_->GetLatestAppliedSequenceId());
     EXPECT_EQ(1u, service_->GetMetadataCount());
@@ -406,7 +409,7 @@ TEST_F(HotStandbyServiceTest, TestStart_SnapshotOnlyWhenProviderFails) {
     service_->SetSnapshotProvider(std::make_unique<FakeSnapshotProvider>(
         tl::make_unexpected(ErrorCode::PERSISTENT_FAIL)));
 
-    auto err = service_->Start("", "", cluster_id_);
+    auto err = service_->Start({}, "", cluster_id_);
     EXPECT_EQ(ErrorCode::PERSISTENT_FAIL, err);
     EXPECT_EQ(StandbyState::FAILED, service_->GetState());
 }
@@ -457,7 +460,7 @@ TEST_F(HotStandbyServiceTest, TestExportStandbySnapshot_Empty) {
     service_->SetSnapshotProvider(std::make_unique<FakeSnapshotProvider>(
         std::optional<LoadedSnapshot>(LoadedSnapshot{})));
 
-    EXPECT_EQ(ErrorCode::OK, service_->Start("", "", cluster_id_));
+    EXPECT_EQ(ErrorCode::OK, service_->Start({}, "", cluster_id_));
     EXPECT_EQ(StandbyState::WATCHING, service_->GetState());
 
     StandbySnapshot snapshot;
@@ -501,7 +504,7 @@ TEST_F(HotStandbyServiceTest, TestVerificationLoop_WhenEnabled) {
 #else
     config_.enable_verification = true;
     service_.reset(new HotStandbyService(config_));
-    (void)service_->Start("primary_unused", oplog_endpoints_, cluster_id_);
+    (void)service_->Start(kTestSources, oplog_endpoints_, cluster_id_);
     service_->Stop();
     SUCCEED();
 #endif
@@ -513,7 +516,7 @@ TEST_F(HotStandbyServiceTest, TestVerificationLoop_WhenDisabled) {
 #ifdef STORE_USE_ETCD
     GTEST_SKIP() << "Requires real etcd connection to start service.";
 #else
-    (void)service_->Start("primary_unused", oplog_endpoints_, cluster_id_);
+    (void)service_->Start(kTestSources, oplog_endpoints_, cluster_id_);
     service_->Stop();
     SUCCEED();
 #endif
@@ -640,7 +643,7 @@ TEST_F(HotStandbyServiceTest,
     auto service = std::make_unique<HotStandbyService>(config);
     service->SetCatchUpBatchKvBackendForTesting(batch_backend);
     ASSERT_EQ(ErrorCode::OK,
-              service->Start("primary_unused", "unused", cluster_id));
+              service->Start(kTestSources, "unused", cluster_id));
 
     for (int i = 0; i < 100 && service->GetLatestAppliedSequenceId() < 1; ++i) {
         std::this_thread::sleep_for(std::chrono::milliseconds(2));
@@ -671,7 +674,7 @@ TEST_F(HotStandbyServiceTest, BatchRecordRetriesTransientBackendFailure) {
     auto service = std::make_unique<HotStandbyService>(config);
     service->SetCatchUpBatchKvBackendForTesting(batch_backend);
     ASSERT_EQ(ErrorCode::OK,
-              service->Start("primary_unused", "unused", cluster_id));
+              service->Start(kTestSources, "unused", cluster_id));
 
     for (int i = 0;
          i < 100 && (service->GetLatestAppliedSequenceId() < 1 ||
@@ -697,8 +700,8 @@ TEST_F(HotStandbyServiceTest, BatchRecordRetryTimeoutTransitionsToFailed) {
 
     auto service = std::make_unique<HotStandbyService>(config);
     service->SetCatchUpBatchKvBackendForTesting(batch_backend);
-    ASSERT_EQ(ErrorCode::OK, service->Start("primary_unused", "unused",
-                                            "batch-standby-timeout"));
+    ASSERT_EQ(ErrorCode::OK,
+              service->Start(kTestSources, "unused", "batch-standby-timeout"));
 
     for (int i = 0; i < 100 && service->GetState() != StandbyState::FAILED;
          ++i) {
@@ -722,8 +725,8 @@ TEST_F(HotStandbyServiceTest, BatchRecordCanRestartAfterRetryTimeout) {
 
     auto service = std::make_unique<HotStandbyService>(config);
     service->SetCatchUpBatchKvBackendForTesting(batch_backend);
-    ASSERT_EQ(ErrorCode::OK, service->Start("primary_unused", "unused",
-                                            "batch-standby-restart"));
+    ASSERT_EQ(ErrorCode::OK,
+              service->Start(kTestSources, "unused", "batch-standby-restart"));
     for (int i = 0; i < 100 && service->GetState() != StandbyState::FAILED;
          ++i) {
         std::this_thread::sleep_for(std::chrono::milliseconds(2));
@@ -731,8 +734,8 @@ TEST_F(HotStandbyServiceTest, BatchRecordCanRestartAfterRetryTimeout) {
     ASSERT_EQ(StandbyState::FAILED, service->GetState());
 
     batch_backend->SetGetError(ErrorCode::OK);
-    ASSERT_EQ(ErrorCode::OK, service->Start("primary_unused", "unused",
-                                            "batch-standby-restart"));
+    ASSERT_EQ(ErrorCode::OK,
+              service->Start(kTestSources, "unused", "batch-standby-restart"));
 
     EXPECT_EQ(StandbyState::WATCHING, service->GetState());
     EXPECT_EQ(ErrorCode::OK, service->GetSyncStatus().last_error);
@@ -787,7 +790,7 @@ TEST_F(HotStandbyServiceTest,
 
     auto service = std::make_unique<HotStandbyService>(config);
     ASSERT_EQ(ErrorCode::OK,
-              service->Start("primary_unused", etcd_endpoints, cluster_id));
+              service->Start(kTestSources, etcd_endpoints, cluster_id));
 
     const uint64_t expected_seq = prefix.last_seq + 1;
     constexpr int kMaxAttempts = 100;
@@ -811,7 +814,7 @@ TEST_F(PromotionCatchUpTest, UsesDurablePrefixLastSeqAsCatchUpTarget) {
               batch_backend_->Put(BuildBatchRecordKey(cluster_id_, 1),
                                   EncodeOpLogBatchRecord(MakeBatch(1, 1, 2))));
 
-    auto err = service_->Start("", oplog_endpoints_, cluster_id_);
+    auto err = service_->Start(kTestSources, oplog_endpoints_, cluster_id_);
     if (err != ErrorCode::OK) {
         GTEST_SKIP() << "Service could not reach WATCHING state; "
                         "skipping promotion test";
@@ -836,7 +839,7 @@ TEST_F(PromotionCatchUpTest, RetriesTransientDurablePrefixReadFailure) {
     service_->SetCatchUpBatchKvBackendForTesting(batch_backend);
 
     ASSERT_EQ(ErrorCode::OK,
-              service_->Start("", oplog_endpoints_, cluster_id_));
+              service_->Start(kTestSources, oplog_endpoints_, cluster_id_));
     batch_backend->FailNextGet(ErrorCode::ETCD_OPERATION_ERROR);
 
     StandbySnapshot out;
@@ -846,7 +849,7 @@ TEST_F(PromotionCatchUpTest, RetriesTransientDurablePrefixReadFailure) {
 
 TEST_F(PromotionCatchUpTest, MissingDurablePrefixPromotesAtSequenceZero) {
     ASSERT_EQ(ErrorCode::OK,
-              service_->Start("", oplog_endpoints_, cluster_id_));
+              service_->Start(kTestSources, oplog_endpoints_, cluster_id_));
     ASSERT_EQ(StandbyState::WATCHING, service_->GetState());
     StandbySnapshot out;
     ASSERT_EQ(ErrorCode::OK, service_->PromoteAndExportSnapshot(out));
@@ -861,7 +864,7 @@ TEST_F(PromotionCatchUpTest, MissingDurablePrefixRejectsNonzeroSequence) {
         std::optional<LoadedSnapshot>(MakeSnapshot("baseline", 1, "key", 1))));
 
     ASSERT_EQ(ErrorCode::OK,
-              service_->Start("", oplog_endpoints_, cluster_id_));
+              service_->Start(kTestSources, oplog_endpoints_, cluster_id_));
     ASSERT_EQ(StandbyState::WATCHING, service_->GetState());
     StandbySnapshot out;
     EXPECT_EQ(ErrorCode::INCOMPLETE_OPLOG_CATCH_UP,
@@ -871,7 +874,7 @@ TEST_F(PromotionCatchUpTest, MissingDurablePrefixRejectsNonzeroSequence) {
 
 TEST_F(PromotionCatchUpTest, CatchesUpPrefixThatAppearsBeforePromotion) {
     ASSERT_EQ(ErrorCode::OK,
-              service_->Start("", oplog_endpoints_, cluster_id_));
+              service_->Start(kTestSources, oplog_endpoints_, cluster_id_));
     ASSERT_EQ(StandbyState::WATCHING, service_->GetState());
     ASSERT_EQ(ErrorCode::OK,
               batch_backend_->Put(
@@ -902,7 +905,7 @@ TEST_F(PromotionCatchUpTest, PaginatesBatchRecords) {
     }
     service_->SetCatchUpBatchKvBackendForTesting(batch_backend);
 
-    auto err = service_->Start("", oplog_endpoints_, cluster_id_);
+    auto err = service_->Start(kTestSources, oplog_endpoints_, cluster_id_);
     if (err != ErrorCode::OK) {
         GTEST_SKIP() << "Service could not reach WATCHING state; "
                         "skipping promotion test";
@@ -915,7 +918,7 @@ TEST_F(PromotionCatchUpTest, PaginatesBatchRecords) {
 
 TEST_F(PromotionCatchUpTest, FailsPromotionWhenDurablePrefixUnreadable) {
     ASSERT_EQ(ErrorCode::OK,
-              service_->Start("", oplog_endpoints_, cluster_id_));
+              service_->Start(kTestSources, oplog_endpoints_, cluster_id_));
     batch_backend_->SetGetError(ErrorCode::PERSISTENT_FAIL);
 
     StandbySnapshot out;
@@ -926,7 +929,7 @@ TEST_F(PromotionCatchUpTest, FailsPromotionWhenDurablePrefixUnreadable) {
 
 TEST_F(PromotionCatchUpTest, FailsPromotionWhenTargetBatchUnreadable) {
     ASSERT_EQ(ErrorCode::OK,
-              service_->Start("", oplog_endpoints_, cluster_id_));
+              service_->Start(kTestSources, oplog_endpoints_, cluster_id_));
     ASSERT_EQ(ErrorCode::OK,
               batch_backend_->Put(
                   BuildDurablePrefixKey(cluster_id_),
diff --git a/mooncake-store/tests/ha/standby/hot_standby_snapshot_bootstrap_test.cpp b/mooncake-store/tests/ha/standby/hot_standby_snapshot_bootstrap_test.cpp
index c9a425b563..75b3224b07 100644
--- a/mooncake-store/tests/ha/standby/hot_standby_snapshot_bootstrap_test.cpp
+++ b/mooncake-store/tests/ha/standby/hot_standby_snapshot_bootstrap_test.cpp
@@ -103,7 +103,7 @@ TEST_P(HotStandbySnapshotBootstrapTest,
     HotStandbyService service(MakeSnapshotOnlyConfig());
     service.SetSnapshotProvider(std::move(provider.value()));
 
-    ASSERT_EQ(ErrorCode::OK, service.Start("", "", cluster_id_));
+    ASSERT_EQ(ErrorCode::OK, service.Start({}, "", cluster_id_));
     EXPECT_EQ(StandbyState::WATCHING, service.GetState());
     EXPECT_EQ(1u, service.GetMetadataCount());
     EXPECT_EQ(descriptor_.last_included_seq,
@@ -131,7 +131,7 @@ TEST_P(HotStandbySnapshotBootstrapTest,
     HotStandbyService service(MakeSnapshotOnlyConfig());
     service.SetSnapshotProvider(std::move(provider.value()));
 
-    ASSERT_EQ(ErrorCode::OK, service.Start("", "", cluster_id_));
+    ASSERT_EQ(ErrorCode::OK, service.Start({}, "", cluster_id_));
     EXPECT_EQ(StandbyState::WATCHING, service.GetState());
     EXPECT_EQ(0u, service.GetMetadataCount());
     EXPECT_EQ(0u, service.GetLatestAppliedSequenceId());
@@ -160,7 +160,7 @@ TEST(StandbyControllerTest, PromoteStandbyReturnsStartFailure) {
     auto controller = ha::CreateStandbyController(spec, config);
     ASSERT_NE(controller, nullptr);
     EXPECT_EQ(ErrorCode::INVALID_PARAMS,
-              controller->StartStandby(std::nullopt));
+              controller->StartStandby({}));
     EXPECT_EQ(ErrorCode::INVALID_PARAMS, controller->PromoteStandby());
 }
 
@@ -212,7 +212,7 @@ TEST(StandbyControllerTest,
 
     // After failed start
     EXPECT_EQ(ErrorCode::INVALID_PARAMS,
-              controller->StartStandby(std::nullopt));
+              controller->StartStandby({}));
     result = controller->PromoteStandbyAndExport();
     EXPECT_FALSE(result.has_value());
     EXPECT_EQ(ErrorCode::INVALID_PARAMS, result.error());
@@ -236,7 +236,7 @@ TEST_P(HotStandbySnapshotBootstrapTest,
     auto controller = ha::CreateStandbyController(spec, config);
     ASSERT_NE(controller, nullptr);
 
-    EXPECT_EQ(ErrorCode::OK, controller->StartStandby(std::nullopt));
+    EXPECT_EQ(ErrorCode::OK, controller->StartStandby({}));
 
     auto result = controller->PromoteStandbyAndExport();
     ASSERT_TRUE(result.has_value()) << toString(result.error());
diff --git a/mooncake-store/tests/io_pattern_framework_test.cpp b/mooncake-store/tests/io_pattern_framework_test.cpp
new file mode 100644
index 0000000000..e536f9842b
--- /dev/null
+++ b/mooncake-store/tests/io_pattern_framework_test.cpp
@@ -0,0 +1,2359 @@
+#include "io_pattern/io_pattern.h"
+#include "master_metric_manager.h"
+#include "io_pattern/threshold_analyzer.h"
+#include "io_pattern/policy_strategies.h"
+
+#include <memory>
+#include <atomic>
+#include <chrono>
+#include <future>
+#include <mutex>
+#include <condition_variable>
+#include <optional>
+#include <thread>
+#include <type_traits>
+#include <variant>
+#include <vector>
+#include <stdexcept>
+
+#include <gtest/gtest.h>
+#include <ylt/coro_rpc/coro_rpc_server.hpp>
+
+namespace mooncake::io_pattern {
+namespace {
+
+class TestEvictionOps final : public EvictionOps {
+   public:
+    EvictionPlan Evaluate(const PolicyContext&, CacheTier tier,
+                          uint64_t target_bytes) const override {
+        return EvictionPlan{.source_tier = tier,
+                            .target_bytes = target_bytes,
+                            .candidates = {}};
+    }
+};
+
+class TestCollector final : public IoPatternCollector {
+   public:
+    void ReportInferenceMetrics(const InferenceMetrics& metrics) override {
+        inference_metrics = metrics;
+    }
+    void RecordAccess(const std::string&, const AccessRecord& record) override {
+        access_record = record;
+    }
+    void RecordStorageMetric(const StorageMetric& metric) override {
+        storage_metric = metric;
+    }
+    IoPatternSnapshot GetSnapshot() const override { return snapshot; }
+
+    InferenceMetrics inference_metrics;
+    AccessRecord access_record;
+    StorageMetric storage_metric;
+    IoPatternSnapshot snapshot;
+};
+
+class TestAnalyzer final : public IoPatternAnalyzer {
+   public:
+    PatternResult Analyze(const IoPatternSnapshot&) const override {
+        return result;
+    }
+    WorkloadType DetectWorkloadType(
+        const IoPatternSnapshot&) const override {
+        return result.workload_type;
+    }
+    float CalculateConfidence(const ObjectRef&,
+                              const IoPatternSnapshot&) const override {
+        return result.workload_confidence;
+    }
+
+    PatternResult result{.workload_type = WorkloadType::kMixed,
+                         .workload_confidence = 0.75F};
+};
+
+class ThrowingAnalyzer final : public IoPatternAnalyzer {
+   public:
+    PatternResult Analyze(const IoPatternSnapshot&) const override {
+        throw std::runtime_error("analysis failure");
+    }
+    WorkloadType DetectWorkloadType(const IoPatternSnapshot&) const override {
+        throw std::runtime_error("analysis failure");
+    }
+    float CalculateConfidence(const ObjectRef&, const IoPatternSnapshot&) const override {
+        throw std::runtime_error("analysis failure");
+    }
+};
+
+class TestPrefetchOps final : public PrefetchOps {
+   public:
+    PrefetchPlan Evaluate(const PolicyContext&,
+                          const TraceHistory&) const override {
+        return plan;
+    }
+
+    PrefetchPlan plan;
+};
+
+class TestAdmissionOps final : public AdmissionOps {
+   public:
+    AdmissionResult Evaluate(const ObjectRef& object, CacheTier tier,
+                             const PolicyContext&) const override {
+        return AdmissionResult{.object = object,
+                                .target_tier = tier,
+                                .decision = AdmissionDecision::kAdmit};
+    }
+};
+
+class TestPrefetchExecutor final : public PrefetchExecutor {
+   public:
+    ErrorCode Execute(const PrefetchPlan& value) override {
+        plan = value;
+        return ErrorCode::OK;
+    }
+
+    PrefetchPlan plan;
+};
+
+class TestCfmChannel final : public CfmChannel {
+   public:
+    bool SendSnapshot(const IoPatternSnapshot& value) override {
+        snapshot = value;
+        return send_ok;
+    }
+    bool SendMetricBatch(const MetricBatch& value) override {
+        batch = value;
+        return send_ok;
+    }
+    ErrorCode ExecutePrefetch(const PrefetchPlan& value) override {
+        plan = value;
+        return execute_code;
+    }
+    bool send_ok{true};
+    ErrorCode execute_code{ErrorCode::OK};
+    IoPatternSnapshot snapshot;
+    MetricBatch batch;
+    PrefetchPlan plan;
+};
+
+class FlakyCfmChannel final : public CfmChannel {
+   public:
+    bool SendSnapshot(const IoPatternSnapshot&) override {
+        return send_failures-- <= 0;
+    }
+    bool SendMetricBatch(const MetricBatch&) override {
+        return send_failures-- <= 0;
+    }
+    ErrorCode ExecutePrefetch(const PrefetchPlan&) override {
+        return ErrorCode::RPC_FAIL;
+    }
+    int send_failures{0};
+};
+
+class TestRpcTransport final : public CfmRpcTransport {
+   public:
+    bool Send(std::string_view method, std::string_view payload,
+              std::chrono::milliseconds timeout) override {
+        last_method = std::string(method);
+        last_payload = std::string(payload);
+        last_timeout = timeout;
+        return send_ok;
+    }
+    bool send_ok{true};
+    std::string last_method;
+    std::string last_payload;
+    std::chrono::milliseconds last_timeout{0};
+};
+
+class TestRpcCodec final : public CfmRpcCodec {
+   public:
+    std::string EncodeSnapshot(const IoPatternSnapshot&) const override { return "snapshot"; }
+    std::string EncodePrefetch(const PrefetchPlan&) const override { return "prefetch"; }
+    std::string EncodeMetricBatch(const MetricBatch&) const override {
+        return "batch";
+    }
+    std::optional<PolicyCommand> DecodePolicy(const std::string& value) const override {
+        return value == "policy" ? std::optional<PolicyCommand>(PrefetchPlan{})
+                                   : std::nullopt;
+    }
+};
+
+TEST(IoPatternFrameworkTest, PublicSeamsRemainAbstract) {
+    static_assert(std::is_abstract_v<IoPatternCollector>);
+    static_assert(std::is_abstract_v<IoPatternAnalyzer>);
+    static_assert(std::is_abstract_v<CfmClient>);
+    static_assert(std::is_abstract_v<EvictionOps>);
+    static_assert(std::is_abstract_v<PrefetchOps>);
+    static_assert(std::is_abstract_v<AdmissionOps>);
+    static_assert(std::is_abstract_v<PrefetchExecutor>);
+    static_assert(std::is_abstract_v<PolicyEngine>);
+}
+
+TEST(IoPatternFrameworkTest, CacheTierMaskRepresentsAllTiers) {
+    const CacheTierMask all_tiers =
+        CacheTierBit(CacheTier::kL0Hbm) | CacheTierBit(CacheTier::kL1Host) |
+        CacheTierBit(CacheTier::kL2Segment) |
+        CacheTierBit(CacheTier::kL3NofSsd);
+
+    EXPECT_EQ(all_tiers, 0x0F);
+}
+
+TEST(IoPatternFrameworkTest, MetricsKeepTenantAndLayoutIdentity) {
+    InferenceMetrics metrics;
+    metrics.object = {TenantId("tenant-a"), "prefix/block-1"};
+    metrics.layout = CacheLayout::kHmaMultiGroup;
+    metrics.layout_group = 3;
+    metrics.match_length = 512;
+
+    IoPatternSnapshot snapshot;
+    KeyMetrics key_metrics;
+    key_metrics.object = metrics.object;
+    key_metrics.match_length = metrics.match_length;
+    key_metrics.layout = metrics.layout;
+    key_metrics.layout_group = metrics.layout_group;
+    snapshot.keys.push_back(key_metrics);
+
+    ASSERT_EQ(snapshot.keys.size(), 1);
+    EXPECT_EQ(snapshot.keys.front().object.tenant_id.value(), "tenant-a");
+    EXPECT_EQ(snapshot.keys.front().object.key, "prefix/block-1");
+    EXPECT_EQ(snapshot.keys.front().layout, CacheLayout::kHmaMultiGroup);
+    EXPECT_EQ(snapshot.keys.front().layout_group, 3);
+    EXPECT_EQ(snapshot.keys.front().match_length, 512);
+}
+
+TEST(IoPatternFrameworkTest, CollectorAndAnalyzerExposeValueFlow) {
+    TestCollector collector;
+    collector.inference_metrics.object =
+        {TenantId("tenant-a"), "prefix/block-1"};
+    collector.snapshot.generated_at_ns = 42;
+    collector.snapshot.keys.push_back(
+        KeyMetrics{.object = collector.inference_metrics.object});
+
+    collector.ReportInferenceMetrics(collector.inference_metrics);
+    AccessRecord access_record;
+    access_record.object = collector.inference_metrics.object;
+    access_record.observed_at_ns = 43;
+    access_record.is_hit = true;
+    collector.RecordAccess("key", access_record);
+    collector.RecordStorageMetric(StorageMetric{.source_id = "segment-1"});
+
+    const auto snapshot = collector.GetSnapshot();
+    ASSERT_EQ(snapshot.keys.size(), 1);
+    EXPECT_EQ(collector.inference_metrics.object.key, "prefix/block-1");
+    EXPECT_TRUE(collector.access_record.is_hit);
+    EXPECT_EQ(collector.storage_metric.source_id, "segment-1");
+
+    TestAnalyzer analyzer;
+    const auto result = analyzer.Analyze(snapshot);
+    EXPECT_EQ(result.workload_type, WorkloadType::kMixed);
+    EXPECT_FLOAT_EQ(analyzer.CalculateConfidence({}, snapshot), 0.75F);
+    EXPECT_EQ(analyzer.DetectWorkloadType(snapshot), WorkloadType::kMixed);
+}
+
+TEST(IoPatternFrameworkTest, CollectorImplAggregatesAndIsolatesTenants) {
+    IoPatternCollectorImpl collector;
+    AccessRecord access;
+    access.object = {TenantId("tenant-a"), "ignored"};
+    access.observed_at_ns = 200;
+    access.block_size = 4096;
+    access.tier = CacheTier::kL1Host;
+    access.is_hit = true;
+    collector.RecordAccess("shared-key", access);
+    access.object.tenant_id = TenantId("tenant-b");
+    access.observed_at_ns = 100;
+    collector.RecordAccess("shared-key", access);
+
+    const auto snapshot = collector.GetSnapshot();
+    ASSERT_EQ(snapshot.keys.size(), 2);
+    EXPECT_EQ(snapshot.keys[0].object.tenant_id.value(), "tenant-a");
+    EXPECT_EQ(snapshot.keys[1].object.tenant_id.value(), "tenant-b");
+    EXPECT_EQ(snapshot.keys[0].object.key, "shared-key");
+}
+
+TEST(IoPatternFrameworkTest, CollectorImplKeepsLatestStorageObservation) {
+    IoPatternCollectorImpl collector;
+    collector.RecordStorageMetric(StorageMetric{.source_id = "segment",
+                                                .observed_at_ns = 20,
+                                                .used_bytes = 200});
+    collector.RecordStorageMetric(StorageMetric{.source_id = "segment",
+                                                .observed_at_ns = 10,
+                                                .used_bytes = 100});
+    const auto snapshot = collector.GetSnapshot();
+    ASSERT_EQ(snapshot.storage.size(), 1);
+    EXPECT_EQ(snapshot.storage.front().used_bytes, 200);
+}
+
+TEST(IoPatternFrameworkTest, CollectorImplEnforcesPerTenantKeyQuota) {
+    IoPatternCollectorImpl collector(
+        IoPatternCollectorImpl::Config{.max_keys_per_tenant = 1});
+    InferenceMetrics first;
+    first.object = {TenantId("tenant-a"), "first"};
+    collector.ReportInferenceMetrics(first);
+    InferenceMetrics second;
+    second.object = {TenantId("tenant-a"), "second"};
+    collector.ReportInferenceMetrics(second);
+    InferenceMetrics other_tenant;
+    other_tenant.object = {TenantId("tenant-b"), "second"};
+    collector.ReportInferenceMetrics(other_tenant);
+    EXPECT_EQ(collector.GetSnapshot().keys.size(), 2);
+    EXPECT_EQ(collector.dropped(), 1);
+}
+
+TEST(IoPatternFrameworkTest, CollectorImplDegradesAtGlobalKeyLimit) {
+    IoPatternCollectorImpl collector(
+        IoPatternCollectorImpl::Config{.max_total_keys = 1});
+    InferenceMetrics first;
+    first.object = {TenantId("tenant-a"), "first"};
+    collector.ReportInferenceMetrics(first);
+    InferenceMetrics second;
+    second.object = {TenantId("tenant-b"), "second"};
+    collector.ReportInferenceMetrics(second);
+    EXPECT_TRUE(collector.degraded());
+    EXPECT_EQ(collector.dropped(), 1);
+    EXPECT_EQ(collector.GetSnapshot().keys.size(), 1);
+    collector.RecordStorageMetric(StorageMetric{.source_id = "segment"});
+    EXPECT_EQ(collector.GetSnapshot().storage.size(), 1);
+}
+
+TEST(IoPatternFrameworkTest, CollectorImplFeedsReporterWithoutInlineTransport) {
+    MetricBatch received;
+    auto reporter = std::make_shared<IoPatternReporter>(4, [&](const MetricBatch& batch) {
+        received = batch;
+        return true;
+    });
+    IoPatternCollectorImpl collector({}, reporter);
+    collector.ReportInferenceMetrics(InferenceMetrics{});
+    collector.RecordStorageMetric(StorageMetric{});
+    EXPECT_EQ(reporter->pending(), 2);
+    EXPECT_TRUE(collector.FlushReports());
+    EXPECT_EQ(received.inference.size(), 1);
+    EXPECT_EQ(received.storage.size(), 1);
+}
+
+TEST(IoPatternFrameworkTest, CollectorImplDerivesWritePathMetrics) {
+    IoPatternCollectorImpl collector;
+    AccessRecord write;
+    write.object = {TenantId("tenant-a"), "write-key"};
+    write.operation = IoOperation::kPut;
+    write.block_size = 4096;
+    write.write_batch_size = 32;
+    collector.RecordAccess("write-key", write);
+    write.overwrite = true;
+    collector.RecordAccess("write-key", write);
+    const auto snapshot = collector.GetSnapshot();
+    const auto& key = snapshot.keys.front();
+    EXPECT_EQ(key.write_frequency, 2);
+    EXPECT_EQ(key.write_batch_size, 32);
+    EXPECT_EQ(key.write_object_size, 4096);
+    EXPECT_FLOAT_EQ(key.overwrite_ratio, 0.5F);
+    EXPECT_TRUE(key.write_burst);
+}
+
+TEST(IoPatternFrameworkTest, CollectorImplBoundsAccessCountByTimeWindow) {
+    uint64_t now_ns = 10;
+    IoPatternCollectorImpl collector(IoPatternCollectorImpl::Config{
+        .access_window_ns = 100,
+        .access_bucket_ns = 1,
+        .now_ns = [&] { return now_ns; }});
+    AccessRecord access{.object = {TenantId("tenant-a"), "key"},
+                        .observed_at_ns = 10};
+    collector.RecordAccess(access.object.key, access);
+    access.observed_at_ns = 50;
+    collector.RecordAccess(access.object.key, access);
+    EXPECT_EQ(collector.GetSnapshot().keys.front().access_count_window, 2);
+
+    access.observed_at_ns = 111;
+    now_ns = 111;
+    collector.RecordAccess(access.object.key, access);
+    // A true sliding window retains the event at 50 even though the first
+    // event's fixed 10..110 bucket has ended.
+    EXPECT_EQ(collector.GetSnapshot().keys.front().access_count_window, 2);
+
+    now_ns = 212;
+    EXPECT_EQ(collector.GetSnapshot().keys.front().access_count_window, 0);
+}
+
+TEST(IoPatternFrameworkTest, CollectorExpiresMergedAccessWindowsLocally) {
+    uint64_t now_ns = 10;
+    IoPatternCollectorImpl collector(IoPatternCollectorImpl::Config{
+        .access_window_ns = 100,
+        .access_bucket_ns = 1,
+        .now_ns = [&] { return now_ns; }});
+    IoPatternSnapshot remote;
+    remote.keys.push_back(
+        KeyMetrics{.object = {TenantId("tenant-a"), "remote"},
+                   .access_count_window = 7,
+                   .write_frequency = 3});
+
+    collector.MergeSnapshot(remote);
+    EXPECT_EQ(collector.GetSnapshot().keys.front().access_count_window, 7);
+    now_ns = 111;
+    const auto expired = collector.GetSnapshot().keys.front();
+    EXPECT_EQ(expired.access_count_window, 0);
+    EXPECT_EQ(expired.write_frequency, 0);
+}
+
+TEST(IoPatternFrameworkTest, CollectorHardCapsBucketsForOutOfOrderInput) {
+    uint64_t now_ns = 3;
+    IoPatternCollectorImpl collector(IoPatternCollectorImpl::Config{
+        .access_window_ns = 1'000,
+        .access_bucket_ns = 1,
+        .max_access_buckets_per_key = 2,
+        .now_ns = [&] { return now_ns; }});
+    AccessRecord access{.object = {TenantId("tenant-a"), "key"}};
+    for (uint64_t timestamp : {1ULL, 2ULL, 3ULL}) {
+        access.observed_at_ns = timestamp;
+        collector.RecordAccess(access.object.key, access);
+    }
+    EXPECT_EQ(collector.GetSnapshot().keys.front().access_count_window, 2);
+}
+
+TEST(IoPatternFrameworkTest, ThresholdAnalyzerClassifiesDocumentedWorkloads) {
+    ThresholdAnalyzer analyzer;
+    IoPatternSnapshot code_agent;
+    KeyMetrics code_key;
+    code_key.object = {TenantId("tenant-a"), "code"};
+    code_key.token_count = 20 * 1024;
+    code_key.prefix_fanout = 20;
+    code_key.match_length = 512;
+    code_agent.keys.push_back(code_key);
+    EXPECT_EQ(analyzer.DetectWorkloadType(code_agent),
+              WorkloadType::kCodeAgent);
+
+    IoPatternSnapshot recommendation;
+    KeyMetrics recommendation_key;
+    recommendation_key.object = {TenantId("tenant-a"), "recommendation"};
+    recommendation_key.block_size = 64 * 1024;
+    recommendation_key.access_count_window = 30;
+    recommendation.keys.push_back(recommendation_key);
+    EXPECT_EQ(analyzer.DetectWorkloadType(recommendation),
+              WorkloadType::kGenerativeRecommendation);
+}
+
+TEST(IoPatternFrameworkTest, ThresholdAnalyzerFallsBackToMixed) {
+    ThresholdAnalyzer analyzer;
+    IoPatternSnapshot snapshot;
+    KeyMetrics key;
+    key.object = {TenantId("tenant-a"), "unknown"};
+    snapshot.keys.push_back(key);
+
+    const auto result = analyzer.Analyze(snapshot);
+    EXPECT_EQ(result.workload_type, WorkloadType::kMixed);
+    EXPECT_FLOAT_EQ(result.workload_confidence, 0.0F);
+    ASSERT_EQ(result.keys.size(), 1);
+    EXPECT_EQ(result.keys.front().object.key, "unknown");
+    EXPECT_FLOAT_EQ(analyzer.CalculateConfidence(key.object, snapshot), 0.0F);
+}
+
+TEST(IoPatternFrameworkTest, ThresholdAnalyzerReportsMixedAndPartialConfidence) {
+    ThresholdAnalyzer analyzer;
+    IoPatternSnapshot snapshot;
+    KeyMetrics code;
+    code.object = {TenantId("tenant-a"), "code"};
+    code.token_count = 20 * 1024;
+    code.prefix_fanout = 20;
+    code.match_length = 512;
+    snapshot.keys.push_back(code);
+    KeyMetrics recommendation;
+    recommendation.object = {TenantId("tenant-b"), "recommendation"};
+    recommendation.block_size = 64 * 1024;
+    recommendation.access_count_window = 30;
+    snapshot.keys.push_back(recommendation);
+    EXPECT_EQ(analyzer.DetectWorkloadType(snapshot), WorkloadType::kMixed);
+    EXPECT_FLOAT_EQ(analyzer.CalculateConfidence(
+                        {TenantId("tenant-a"), "code"}, snapshot),
+                    1.0F);
+    KeyMetrics partial;
+    partial.object = {TenantId("tenant-c"), "partial"};
+    partial.token_count = 8 * 1024;
+    snapshot.keys.push_back(partial);
+    EXPECT_GT(analyzer.CalculateConfidence(partial.object, snapshot), 0.0F);
+}
+
+TEST(IoPatternFrameworkTest, ScoreEvictionSelectsColdObjectsWithinBudget) {
+    ScoreBasedEvictionOps eviction;
+    PolicyContext context;
+    KeyMetrics cold;
+    cold.object = {TenantId("tenant-a"), "cold"};
+    cold.block_size = 100;
+    cold.replica_tiers = CacheTierBit(CacheTier::kL1Host);
+    KeyMetrics hot = cold;
+    hot.object.key = "hot";
+    hot.block_size = 100;
+    context.snapshot.keys = {cold, hot};
+    context.analysis.keys = {
+        {.object = cold.object, .frequency_score = 0.1F, .idle_score = 0.9F},
+        {.object = hot.object, .frequency_score = 0.9F, .idle_score = 0.1F},
+    };
+
+    const auto plan = eviction.Evaluate(context, CacheTier::kL1Host, 100);
+    ASSERT_EQ(plan.candidates.size(), 1);
+    EXPECT_EQ(plan.candidates.front().object.key, "cold");
+    EXPECT_EQ(plan.candidates.front().bytes, 100);
+}
+
+TEST(IoPatternFrameworkTest, ScoreEvictionSkipsPinnedAndZeroBudget) {
+    ScoreBasedEvictionOps eviction;
+    PolicyContext context;
+    KeyMetrics key;
+    key.object = {TenantId("tenant-a"), "pinned"};
+    key.block_size = 1;
+    key.pinned = true;
+    key.replica_tiers = CacheTierBit(CacheTier::kL1Host);
+    context.snapshot.keys.push_back(key);
+    context.analysis.keys.push_back(
+        KeyPattern{.object = key.object, .frequency_score = 0.0F});
+
+    EXPECT_TRUE(eviction.Evaluate(context, CacheTier::kL1Host, 1024)
+                    .candidates.empty());
+    key.pinned = false;
+    context.snapshot.keys.front() = key;
+    EXPECT_TRUE(eviction.Evaluate(context, CacheTier::kL1Host, 0)
+                    .candidates.empty());
+}
+
+TEST(IoPatternFrameworkTest, PrefixAdmissionUsesTierSpecificSignals) {
+    PrefixMatchAdmissionOps admission;
+    PolicyContext context;
+    KeyMetrics key;
+    key.object = {TenantId("tenant-a"), "prefix"};
+    key.access_count_window = 10;
+    key.match_length = 64;
+    context.snapshot.keys.push_back(key);
+
+    const auto hbm = admission.Evaluate(key.object, CacheTier::kL0Hbm, context);
+    EXPECT_EQ(hbm.decision, AdmissionDecision::kAdmit);
+
+    key.match_length = 1;
+    context.snapshot.keys.front() = key;
+    const auto rejected =
+        admission.Evaluate(key.object, CacheTier::kL0Hbm, context);
+    EXPECT_EQ(rejected.decision, AdmissionDecision::kRejectPrefix);
+
+    context.snapshot.storage = {
+        StorageMetric{.source_id = "ssd",
+                      .tier = CacheTier::kL3NofSsd,
+                      .memory_used_ratio = 0.1F},
+        StorageMetric{.source_id = "host",
+                      .tier = CacheTier::kL1Host,
+                      .memory_used_ratio = 0.95F}};
+    EXPECT_EQ(admission.Evaluate(key.object, CacheTier::kL1Host, context)
+                  .decision,
+              AdmissionDecision::kRejectWatermark);
+}
+
+TEST(IoPatternFrameworkTest, TracePrefetchPlansOnlyLongPrefixMatches) {
+    TraceBasedPrefetchOps prefetch;
+    PolicyContext context;
+    KeyMetrics key;
+    key.object = {TenantId("tenant-a"), "block"};
+    key.block_size = 4096;
+    key.replica_tiers = CacheTierBit(CacheTier::kLocalDisk);
+    context.snapshot.keys.push_back(key);
+    // The prefetch gate also requires analyzer confidence, so supply the key
+    // pattern the production pipeline would derive for this object.
+    context.analysis.keys = {
+        KeyPattern{.object = key.object, .confidence = 1.0F}};
+
+    TraceHistory trace;
+    trace.events.push_back(
+        TraceEvent{.object = key.object, .match_length = 512, .is_hit = true});
+    trace.events.push_back(
+        TraceEvent{.object = key.object, .match_length = 8, .is_hit = true});
+
+    const auto plan = prefetch.Evaluate(context, trace);
+    ASSERT_EQ(plan.candidates.size(), 1);
+    EXPECT_EQ(plan.candidates.front().source_tier, CacheTier::kLocalDisk);
+    EXPECT_EQ(plan.candidates.front().target_tier, CacheTier::kL1Host);
+    EXPECT_EQ(plan.candidates.front().bytes, 4096);
+}
+
+TEST(IoPatternFrameworkTest, TracePrefetchDeduplicatesObjects) {
+    TraceBasedPrefetchOps prefetch;
+    PolicyContext context;
+    KeyMetrics key;
+    key.object = {TenantId("tenant-a"), "block"};
+    key.block_size = 128;
+    key.replica_tiers = CacheTierBit(CacheTier::kLocalDisk);
+    context.snapshot.keys.push_back(key);
+    // The prefetch gate also requires analyzer confidence, so supply the key
+    // pattern the production pipeline would derive for this object.
+    context.analysis.keys = {
+        KeyPattern{.object = key.object, .confidence = 1.0F}};
+
+    TraceHistory trace;
+    trace.events.push_back(
+        TraceEvent{.object = key.object, .match_length = 300, .is_hit = true});
+    trace.events.push_back(
+        TraceEvent{.object = key.object, .match_length = 400, .is_hit = true});
+
+    EXPECT_EQ(prefetch.Evaluate(context, trace).candidates.size(), 1);
+}
+
+TEST(IoPatternFrameworkTest, PolicyContextCarriesRawAndDerivedViews) {
+    PolicyContext context;
+    context.snapshot.generated_at_ns = 123;
+    context.analysis.workload_type = WorkloadType::kMixed;
+    context.analysis.workload_confidence = 0.75F;
+
+    EXPECT_EQ(context.snapshot.generated_at_ns, 123);
+    EXPECT_EQ(context.analysis.workload_type, WorkloadType::kMixed);
+    EXPECT_FLOAT_EQ(context.analysis.workload_confidence, 0.75F);
+}
+
+TEST(IoPatternFrameworkTest, PolicyCommandAndViewRemainValueTypes) {
+    const ObjectRef object{TenantId("tenant-b"), "block"};
+    PrefetchCandidate candidate;
+    candidate.object = object;
+    candidate.bytes = 4096;
+    PrefetchPlan prefetch_plan;
+    prefetch_plan.strategy = PrefetchStrategy::kTimeout;
+    prefetch_plan.timeout_us = 1000;
+    prefetch_plan.candidates.push_back(candidate);
+    const PolicyCommand command = prefetch_plan;
+    ASSERT_TRUE(std::holds_alternative<PrefetchPlan>(command));
+    EXPECT_EQ(std::get<PrefetchPlan>(command).candidates.front().object,
+              object);
+
+    CacheView view;
+    view.version = 7;
+    view.entries.push_back({object, CacheTier::kL1Host, 4096});
+    EXPECT_EQ(view.entries.front().tier, CacheTier::kL1Host);
+    EXPECT_EQ(view.entries.front().bytes, 4096);
+}
+
+TEST(IoPatternFrameworkTest, RegistryCreatesTypedOpsAndRejectsDuplicates) {
+    OpsRegistry<EvictionOps> registry;
+
+    EXPECT_TRUE(registry.Register(
+        "test", [] { return std::make_shared<TestEvictionOps>(); }));
+    EXPECT_FALSE(registry.Register(
+        "test", [] { return std::make_shared<TestEvictionOps>(); }));
+    EXPECT_FALSE(registry.Register("", {}));
+    EXPECT_EQ(registry.RegisteredNames(), std::vector<std::string>{"test"});
+
+    const auto ops = registry.Create("test");
+    ASSERT_NE(ops, nullptr);
+    const auto plan = ops->Evaluate({}, CacheTier::kL2Segment, 4096);
+    EXPECT_EQ(plan.source_tier, CacheTier::kL2Segment);
+    EXPECT_EQ(plan.target_bytes, 4096);
+    EXPECT_EQ(registry.Create("missing"), nullptr);
+}
+
+TEST(IoPatternFrameworkTest, ComposedEngineDelegatesAndDegradesSafely) {
+    auto eviction = std::make_shared<TestEvictionOps>();
+    auto prefetch = std::make_shared<TestPrefetchOps>();
+    auto admission = std::make_shared<TestAdmissionOps>();
+    prefetch->plan.strategy = PrefetchStrategy::kWaitComplete;
+    ComposedPolicyEngine engine(eviction, prefetch, admission);
+
+    const auto delegated =
+        engine.PlanEviction({}, CacheTier::kL1Host, 2048);
+    EXPECT_EQ(delegated.source_tier, CacheTier::kL1Host);
+    EXPECT_EQ(delegated.target_bytes, 2048);
+
+    const auto prefetch_plan = engine.PlanPrefetch({}, {});
+    EXPECT_EQ(prefetch_plan.strategy, PrefetchStrategy::kWaitComplete);
+
+    const ObjectRef object{TenantId("tenant-a"), "key"};
+    const auto admitted = engine.DecideAdmission(
+        object, CacheTier::kL2Segment, {});
+    EXPECT_EQ(admitted.object, object);
+    EXPECT_EQ(admitted.target_tier, CacheTier::kL2Segment);
+    EXPECT_EQ(admitted.decision, AdmissionDecision::kAdmit);
+
+    ComposedPolicyEngine degraded(nullptr, nullptr, nullptr);
+    const auto deferred =
+        degraded.DecideAdmission(object, CacheTier::kL2Segment, {});
+    EXPECT_EQ(deferred.decision, AdmissionDecision::kDefer);
+
+    TestPrefetchExecutor executor;
+    EXPECT_EQ(executor.Execute(prefetch_plan), ErrorCode::OK);
+    EXPECT_EQ(executor.plan.strategy, PrefetchStrategy::kWaitComplete);
+}
+
+TEST(IoPatternFrameworkTest, WorkloadPolicyEngineSelectsAndTransitionsTemplates) {
+    WorkloadPolicyEngine engine(WorkloadType::kCodeAgent, 3);
+    EXPECT_EQ(engine.ActiveWorkload(), WorkloadType::kCodeAgent);
+    EXPECT_FLOAT_EQ(engine.TransitionProgress(), 1.0F);
+
+    engine.SetWorkloadType(WorkloadType::kGenerativeRecommendation);
+    EXPECT_EQ(engine.ActiveWorkload(),
+              WorkloadType::kGenerativeRecommendation);
+    EXPECT_FLOAT_EQ(engine.TransitionProgress(), 0.0F);
+    engine.AdvanceTransitionWindow();
+    EXPECT_FLOAT_EQ(engine.TransitionProgress(), 1.0F / 3.0F);
+    engine.AdvanceTransitionWindow();
+    engine.AdvanceTransitionWindow();
+    EXPECT_FLOAT_EQ(engine.TransitionProgress(), 1.0F);
+
+    PolicyContext context;
+    KeyMetrics key;
+    key.object = {TenantId("tenant-a"), "item"};
+    key.block_size = 64 * 1024;
+    key.access_count_window = 30;
+    context.snapshot.keys.push_back(key);
+    TraceHistory trace;
+    trace.events.push_back(
+        TraceEvent{.object = key.object, .match_length = 64, .is_hit = true});
+    EXPECT_EQ(engine.PlanPrefetch(context, trace).strategy,
+              PrefetchStrategy::kWaitComplete);
+}
+
+TEST(IoPatternFrameworkTest, UnifiedPolicyResultSeamDelegates) {
+    IoPatternSnapshot snapshot;
+    KeyMetrics key;
+    key.object = {TenantId("tenant-a"), "key"};
+    snapshot.keys.push_back(key);
+    ComposedPolicyEngine engine(std::make_shared<ScoreBasedEvictionOps>(),
+                                std::make_shared<TraceBasedPrefetchOps>(),
+                                std::make_shared<PrefixMatchAdmissionOps>());
+    PolicyContext context;
+    context.snapshot = snapshot;
+    const auto result = engine.ExecutePolicy(
+        context, CacheTier::kL1Host, 1024, CacheTier::kL1Host, {}, {key.object});
+    EXPECT_EQ(result.admissions.size(), 1);
+    EXPECT_EQ(result.admissions.front().object, key.object);
+}
+
+TEST(IoPatternFrameworkTest, RegistryPolicyEngineResolvesNamedOps) {
+    auto registries = std::make_shared<PolicyOpsRegistries>();
+    ASSERT_TRUE(registries->eviction.Register(
+        "score", [] { return std::make_shared<ScoreBasedEvictionOps>(); }));
+    ASSERT_TRUE(registries->prefetch.Register(
+        "trace", [] { return std::make_shared<TraceBasedPrefetchOps>(); }));
+    ASSERT_TRUE(registries->admission.Register(
+        "prefix", [] { return std::make_shared<PrefixMatchAdmissionOps>(); }));
+    RegistryPolicyEngine engine(registries, "score", "trace", "prefix");
+    const ObjectRef object{TenantId("tenant-a"), "key"};
+    const auto result = engine.ExecutePolicy(
+        {}, CacheTier::kL1Host, 1024, CacheTier::kL1Host, {}, {object});
+    ASSERT_EQ(result.admissions.size(), 1);
+    EXPECT_EQ(result.admissions.front().object, object);
+
+    RegistryPolicyEngine missing(registries, "missing", "trace", "prefix");
+    EXPECT_TRUE(
+        missing.ExecutePolicy({}, CacheTier::kL1Host, 0, CacheTier::kL1Host, {})
+            .degraded);
+}
+
+TEST(IoPatternFrameworkTest, ReporterBatchesBoundsAndCountsDrops) {
+    MetricBatch received;
+    IoPatternReporter reporter(2, [&](const MetricBatch& batch) {
+        received = batch;
+        return true;
+    });
+    EXPECT_TRUE(reporter.Enqueue(InferenceMetrics{}));
+    EXPECT_TRUE(reporter.EnqueueStorage(StorageMetric{}));
+    EXPECT_FALSE(reporter.EnqueueAccess(AccessRecord{}));
+    EXPECT_EQ(reporter.dropped(), 1);
+    EXPECT_EQ(reporter.pending(), 2);
+    EXPECT_TRUE(reporter.Flush());
+    EXPECT_EQ(reporter.pending(), 0);
+    EXPECT_EQ(reporter.reported(), 2);
+    EXPECT_EQ(received.inference.size(), 1);
+    EXPECT_EQ(received.storage.size(), 1);
+}
+
+TEST(IoPatternFrameworkTest, ReporterAdaptsFlushIntervalToLoad) {
+    IoPatternReporter reporter(4, [](const MetricBatch&) { return true; });
+    reporter.UpdateLoad(0.25F, 0);
+    EXPECT_EQ(reporter.RecommendedFlushInterval(),
+              std::chrono::milliseconds(100));
+    reporter.UpdateLoad(0.50F, 0);
+    EXPECT_EQ(reporter.RecommendedFlushInterval(),
+              std::chrono::milliseconds(200));
+    reporter.UpdateLoad(0.80F, 0);
+    EXPECT_EQ(reporter.RecommendedFlushInterval(),
+              std::chrono::milliseconds(500));
+    reporter.UpdateLoad(0.95F, 0);
+    EXPECT_EQ(reporter.RecommendedFlushInterval(),
+              std::chrono::milliseconds(1000));
+    reporter.UpdateLoad(0.25F, 101'000);
+    EXPECT_EQ(reporter.RecommendedFlushInterval(),
+              std::chrono::milliseconds(1000));
+}
+
+TEST(IoPatternFrameworkTest, ReporterEnforcesPerTenantFairness) {
+    IoPatternReporter reporter(4, [](const MetricBatch&) { return true; }, 1);
+    InferenceMetrics first;
+    first.object = {TenantId("tenant-a"), "a"};
+    InferenceMetrics second = first;
+    second.object.key = "b";
+    InferenceMetrics other = first;
+    other.object.tenant_id = TenantId("tenant-b");
+    EXPECT_TRUE(reporter.Enqueue(first));
+    EXPECT_FALSE(reporter.Enqueue(second));
+    EXPECT_TRUE(reporter.Enqueue(other));
+    EXPECT_EQ(reporter.dropped(), 1);
+}
+
+TEST(IoPatternFrameworkTest, CfmClientDelegatesToTransportChannel) {
+    auto channel = std::make_shared<TestCfmChannel>();
+    CfmClientImpl client(channel);
+    IoPatternSnapshot snapshot;
+    snapshot.generated_at_ns = 42;
+    EXPECT_EQ(client.ReportSnapshot(snapshot), ErrorCode::OK);
+    EXPECT_EQ(channel->snapshot.generated_at_ns, 42);
+    EXPECT_EQ(client.ExecutePrefetch(PrefetchPlan{}), ErrorCode::OK);
+    MetricBatch batch;
+    batch.inference.push_back(InferenceMetrics{});
+    EXPECT_EQ(client.ReportMetricBatch(batch), ErrorCode::OK);
+    EXPECT_EQ(channel->batch.inference.size(), 1);
+    channel->send_ok = false;
+    EXPECT_EQ(client.ReportSnapshot(snapshot), ErrorCode::RPC_FAIL);
+    EXPECT_EQ(client.ReportMetricBatch(batch), ErrorCode::RPC_FAIL);
+    CfmClientImpl unavailable(nullptr);
+    EXPECT_EQ(unavailable.ReportSnapshot(snapshot),
+              ErrorCode::UNAVAILABLE_IN_CURRENT_MODE);
+    EXPECT_EQ(unavailable.ReportMetricBatch(batch),
+              ErrorCode::UNAVAILABLE_IN_CURRENT_MODE);
+}
+
+TEST(IoPatternFrameworkTest, ResilientChannelRetriesAndTracksDegrade) {
+    auto flaky = std::make_shared<FlakyCfmChannel>();
+    flaky->send_failures = 2;
+    ResilientCfmChannel channel(flaky, CfmRetryConfig{.max_retries = 2,
+                                                      .degrade_after_failures = 2});
+    EXPECT_TRUE(channel.SendSnapshot({}));
+    EXPECT_FALSE(channel.degraded());
+    EXPECT_EQ(channel.ExecutePrefetch({}), ErrorCode::RPC_FAIL);
+    EXPECT_FALSE(channel.degraded());
+    EXPECT_EQ(channel.consecutive_failures(), 1);
+    EXPECT_EQ(channel.ExecutePrefetch({}), ErrorCode::RPC_FAIL);
+    EXPECT_EQ(channel.consecutive_failures(), 2);
+    EXPECT_TRUE(channel.degraded());
+}
+
+TEST(IoPatternFrameworkTest, ResilientChannelRecoversAfterSuccess) {
+    auto flaky = std::make_shared<FlakyCfmChannel>();
+    ResilientCfmChannel channel(flaky, CfmRetryConfig{.max_retries = 2,
+                                                      .degrade_after_failures = 1});
+    MetricBatch batch;
+    EXPECT_TRUE(channel.SendMetricBatch(batch));
+    EXPECT_FALSE(channel.degraded());
+    EXPECT_EQ(channel.consecutive_failures(), 0);
+}
+
+TEST(IoPatternFrameworkTest, ResilientAnalyzerFallsBackAfterFailure) {
+    ResilientAnalyzer analyzer(std::make_shared<ThrowingAnalyzer>(), 2);
+    EXPECT_EQ(analyzer.DetectWorkloadType({}), WorkloadType::kMixed);
+    EXPECT_FALSE(analyzer.degraded());
+    EXPECT_EQ(analyzer.DetectWorkloadType({}), WorkloadType::kMixed);
+    EXPECT_TRUE(analyzer.degraded());
+    EXPECT_EQ(analyzer.failures(), 2);
+}
+
+TEST(IoPatternFrameworkTest, RpcChannelUsesCodecTransportAndTimeout) {
+    auto transport = std::make_shared<TestRpcTransport>();
+    auto codec = std::make_shared<TestRpcCodec>();
+    CfmRpcChannel channel(transport, codec, CfmRpcConfig{.timeout = std::chrono::milliseconds(25)});
+    EXPECT_TRUE(channel.SendSnapshot({}));
+    EXPECT_EQ(transport->last_method, "report_snapshot");
+    EXPECT_EQ(transport->last_payload, "snapshot");
+    EXPECT_EQ(transport->last_timeout, std::chrono::milliseconds(25));
+    EXPECT_EQ(channel.ExecutePrefetch({}), ErrorCode::OK);
+    EXPECT_EQ(transport->last_method, "execute_prefetch");
+    auto rpc_channel = std::make_shared<CfmRpcChannel>(transport, codec);
+    IoPatternReporter reporter(2, MakeCfmMetricBatchSink(rpc_channel));
+    reporter.Enqueue(InferenceMetrics{});
+    EXPECT_TRUE(reporter.Flush());
+    EXPECT_EQ(transport->last_method, "report_metric_batch");
+    EXPECT_EQ(transport->last_payload, "batch");
+    transport->send_ok = false;
+    EXPECT_EQ(channel.ExecutePrefetch({}), ErrorCode::RPC_TIMEOUT);
+    EXPECT_FALSE(channel.SendSnapshot({}));
+}
+
+TEST(IoPatternFrameworkTest, BinaryCfmCodecRoundTripsAllPolicyCommands) {
+    CfmBinaryCodec codec;
+    PrefetchPlan prefetch{.strategy = PrefetchStrategy::kTimeout,
+                          .timeout_us = 42,
+                          .candidates = {PrefetchCandidate{
+                              .object = {TenantId("tenant-a"), "key"},
+                              .source_tier = CacheTier::kL3NofSsd,
+                              .target_tier = CacheTier::kL2Segment,
+                              .bytes = 512,
+                              .priority = 0.8F,
+                              .confidence = 0.9F}}};
+    const auto decoded_prefetch = codec.DecodePolicy(codec.EncodePolicy(prefetch));
+    ASSERT_TRUE(decoded_prefetch.has_value());
+    const auto& decoded_plan = std::get<PrefetchPlan>(*decoded_prefetch);
+    ASSERT_EQ(decoded_plan.candidates.size(), 1);
+    EXPECT_EQ(decoded_plan.candidates.front().object.key, "key");
+    EXPECT_EQ(decoded_plan.timeout_us, 42);
+
+    AdmissionResult admission{.object = {TenantId("tenant-b"), "admit"},
+                              .target_tier = CacheTier::kL1Host,
+                              .decision = AdmissionDecision::kAdmit,
+                              .confidence = 0.75F};
+    const auto decoded_admission = codec.DecodePolicy(codec.EncodePolicy(admission));
+    ASSERT_TRUE(decoded_admission.has_value());
+    EXPECT_EQ(std::get<AdmissionResult>(*decoded_admission).object.key, "admit");
+
+    EvictionPlan eviction{.source_tier = CacheTier::kL1Host,
+                          .target_bytes = 128,
+                          .candidates = {EvictionCandidate{
+                              .object = {TenantId("tenant-c"), "evict"},
+                              .bytes = 128,
+                              .score = 0.4F}}};
+    const auto decoded_eviction = codec.DecodePolicy(codec.EncodePolicy(eviction));
+    ASSERT_TRUE(decoded_eviction.has_value());
+    EXPECT_EQ(std::get<EvictionPlan>(*decoded_eviction).candidates.front().object.key,
+              "evict");
+
+    IoPatternSnapshot snapshot{.generated_at_ns = 9,
+                               .keys = {KeyMetrics{.object = {TenantId("tenant-d"), "full"},
+                                                   .session_id = "session",
+                                                   .token_count = 16,
+                                                   .active = true}},
+                               .storage = {StorageMetric{.source_id = "master",
+                                                         .used_bytes = 42}}};
+    const auto decoded_snapshot = codec.DecodeSnapshot(codec.EncodeSnapshot(snapshot));
+    ASSERT_TRUE(decoded_snapshot.has_value());
+    EXPECT_EQ(decoded_snapshot->keys.front().session_id, "session");
+    EXPECT_EQ(decoded_snapshot->storage.front().used_bytes, 42);
+
+    MetricBatch batch{.inference = {InferenceMetrics{.object = {TenantId("tenant"), "metric"},
+                                                      .session_id = "s"}},
+                      .accesses = {AccessRecord{.object = {TenantId("tenant"), "metric"},
+                                                .is_hit = true}}};
+    const auto decoded_batch = codec.DecodeMetricBatch(codec.EncodeMetricBatch(batch));
+    ASSERT_TRUE(decoded_batch.has_value());
+    EXPECT_EQ(decoded_batch->inference.front().session_id, "s");
+    EXPECT_TRUE(decoded_batch->accesses.front().is_hit);
+}
+
+// An EvictionPlan crosses the CFM wire to a remote SubMaster, so the
+// per-candidate action and the tier-down budget have to survive the codec:
+// otherwise the remote executor receives a plan that looks like pure eviction
+// and reclaims the very keys the driver chose to demote.
+TEST(IoPatternFrameworkTest, BinaryCfmCodecCarriesTierDownActionAndBudget) {
+    CfmBinaryCodec codec;
+    EvictionPlan plan{.source_tier = CacheTier::kL1Host,
+                      .target_bytes = 4096,
+                      .candidates = {EvictionCandidate{
+                                         .object = {TenantId("tenant"), "demote"},
+                                         .bytes = 4096,
+                                         .score = 0.5F,
+                                         .target_tier = CacheTier::kLocalDisk,
+                                         .action = EvictionAction::kTierDown},
+                                     EvictionCandidate{
+                                         .object = {TenantId("tenant"), "reclaim"},
+                                         .bytes = 4096,
+                                         .score = 0.25F,
+                                         .target_tier = CacheTier::kL3NofSsd,
+                                         .action = EvictionAction::kEvict}},
+                      .tier_down_target_bytes = 4096};
+
+    const auto payload = codec.EncodePolicy(plan);
+    const auto decoded = codec.DecodePolicy(payload);
+    ASSERT_TRUE(decoded.has_value());
+    ASSERT_TRUE(std::holds_alternative<EvictionPlan>(*decoded));
+    const auto& out = std::get<EvictionPlan>(*decoded);
+    ASSERT_EQ(out.candidates.size(), 2);
+    EXPECT_EQ(out.candidates[0].action, EvictionAction::kTierDown);
+    EXPECT_EQ(out.candidates[1].action, EvictionAction::kEvict);
+    EXPECT_EQ(out.tier_down_target_bytes, 4096u);
+    EXPECT_EQ(out.target_bytes, 4096u);
+
+    // A payload written before tier down existed stops after the candidate list
+    // and still decodes. Both new fields then keep their pre-tier-down meaning
+    // (kEvict / 0) instead of silently turning the plan into a demotion.
+    const size_t trailer_bytes = sizeof(uint64_t) + out.candidates.size();
+    ASSERT_GT(payload.size(), trailer_bytes);
+    const auto legacy =
+        codec.DecodePolicy(payload.substr(0, payload.size() - trailer_bytes));
+    ASSERT_TRUE(legacy.has_value());
+    ASSERT_TRUE(std::holds_alternative<EvictionPlan>(*legacy));
+    const auto& old = std::get<EvictionPlan>(*legacy);
+    ASSERT_EQ(old.candidates.size(), 2);
+    EXPECT_EQ(old.candidates[0].action, EvictionAction::kEvict);
+    EXPECT_EQ(old.candidates[1].action, EvictionAction::kEvict);
+    EXPECT_EQ(old.tier_down_target_bytes, 0u);
+}
+
+TEST(IoPatternFrameworkTest, InProcessCfmTransportDispatchesReports) {
+    CfmBinaryCodec codec;
+    bool received_snapshot = false;
+    auto transport = std::make_shared<InProcessCfmRpcTransport>(
+        [&received_snapshot](std::string_view method, std::string_view) {
+            received_snapshot = method == "report_snapshot";
+            return received_snapshot;
+        });
+    CfmRpcChannel channel(transport, std::make_shared<CfmBinaryCodec>());
+    EXPECT_TRUE(channel.SendSnapshot({}));
+    EXPECT_TRUE(received_snapshot);
+
+    // Without a bound handler the transport has no receiver; the embedded
+    // receiver path is exercised through CfmService/CfmIngress instead.
+    auto unbound = std::make_shared<InProcessCfmRpcTransport>();
+    CfmRpcChannel unbound_channel(unbound, std::make_shared<CfmBinaryCodec>());
+    EXPECT_TRUE(unbound_channel.SendSnapshot({}));
+}
+
+TEST(IoPatternFrameworkTest, InProcessTransportDoesNotHoldLockAcrossHandler) {
+    std::promise<void> handler_entered;
+    std::promise<void> release_handler;
+    auto release = release_handler.get_future().share();
+    // Only the first invocation blocks and signals entry: the test deliberately
+    // issues a second concurrent Send, and re-satisfying the promise from that
+    // invocation would throw std::future_error inside the handler and abort the
+    // process instead of proving that the transport lock is not held across it.
+    std::atomic<int> handler_calls{0};
+    auto transport = std::make_shared<InProcessCfmRpcTransport>(
+        [&](std::string_view, std::string_view) {
+            if (handler_calls.fetch_add(1) == 0) {
+                handler_entered.set_value();
+                release.wait();
+            }
+            return true;
+        });
+
+    std::thread sender([&] {
+        EXPECT_TRUE(transport->Send("report_snapshot", {},
+                                    std::chrono::milliseconds(10)));
+    });
+    if (handler_entered.get_future().wait_for(std::chrono::seconds(1)) !=
+        std::future_status::ready) {
+        release_handler.set_value();
+        sender.join();
+        FAIL() << "send handler did not start";
+        return;
+    }
+    // A concurrent Send must not deadlock on the transport mutex while the
+    // first handler is still executing.
+    std::thread second([&] {
+        EXPECT_TRUE(transport->Send("report_snapshot", {},
+                                    std::chrono::milliseconds(10)));
+    });
+    second.join();
+    release_handler.set_value();
+    sender.join();
+}
+
+TEST(IoPatternFrameworkTest, CfmIngressFeedsRuntimeFromMetricBatches) {
+    auto runtime = std::make_shared<IoPatternRuntime>(
+        IoPatternRuntime::Handlers{.eviction = [](const EvictionPlan&) {
+                                      return ErrorCode::OK;
+                                  },
+                                  .prefetch = [](const PrefetchPlan&) {
+                                      return ErrorCode::OK;
+                                  },
+                                  .admission = [](const AdmissionResult&) {
+                                      return ErrorCode::OK;
+                                  }});
+    auto codec = std::make_shared<CfmBinaryCodec>();
+    CfmIngress ingress(runtime, codec);
+    MetricBatch batch{.inference = {InferenceMetrics{
+                          .object = {TenantId("tenant"), "metric-key"},
+                          .session_id = "session",
+                          .token_count = 32}},
+                      .accesses = {AccessRecord{
+                          .object = {TenantId("tenant"), "metric-key"},
+                          .block_size = 64,
+                          .is_hit = true}}};
+    EXPECT_TRUE(ingress.Handle("report_metric_batch", codec->EncodeMetricBatch(batch)));
+    const auto snapshot = runtime->Snapshot();
+    ASSERT_EQ(snapshot.keys.size(), 1);
+    EXPECT_EQ(snapshot.keys.front().session_id, "session");
+    EXPECT_EQ(snapshot.keys.front().access_count_window, 1);
+}
+
+TEST(IoPatternFrameworkTest, CfmServiceMergesReportsAndExecutesLocally) {
+    int admissions = 0;
+    auto runtime = std::make_shared<IoPatternRuntime>(
+        IoPatternRuntime::Handlers{
+            .eviction = [](const EvictionPlan&) { return ErrorCode::OK; },
+            .prefetch = [](const PrefetchPlan&) { return ErrorCode::OK; },
+            .admission = [&admissions](const AdmissionResult&) {
+                ++admissions;
+                return ErrorCode::OK;
+            }});
+    CfmService service(runtime);
+    CfmBinaryCodec codec;
+
+    // Reports are merged into the single local runtime: no per-node runtime,
+    // no policy queue and no credential gate.
+    MetricBatch batch;
+    batch.inference.push_back(
+        InferenceMetrics{.object = {TenantId("tenant"), "key"},
+                         .session_id = "session",
+                         .token_count = 32});
+    ASSERT_TRUE(service.Send("report_metric_batch",
+                             codec.EncodeMetricBatch(batch)));
+    const auto merged = service.Snapshot();
+    ASSERT_EQ(merged.keys.size(), 1);
+    EXPECT_EQ(merged.keys.front().object.key, "key");
+
+    // A delivered policy command executes through the local runtime handlers.
+    const auto admission = codec.EncodePolicy(AdmissionResult{
+        .object = {TenantId("tenant"), "key"},
+        .target_tier = CacheTier::kL1Host,
+        .decision = AdmissionDecision::kAdmit});
+    ASSERT_TRUE(service.Send("execute_policy", admission));
+    EXPECT_EQ(admissions, 1);
+    EXPECT_FALSE(service.Send("execute_policy", "malformed"));
+    EXPECT_EQ(admissions, 1);
+}
+
+TEST(IoPatternFrameworkTest, CfmServiceMergesAllReportsIntoLocalRuntime) {
+    auto runtime = std::make_shared<IoPatternRuntime>(
+        IoPatternRuntime::Handlers{
+            .eviction = [](const EvictionPlan&) { return ErrorCode::OK; },
+            .prefetch = [](const PrefetchPlan&) { return ErrorCode::OK; },
+            .admission = [](const AdmissionResult&) { return ErrorCode::OK; }});
+    CfmService service(runtime);
+    CfmBinaryCodec codec;
+
+    MetricBatch first;
+    first.accesses.push_back(
+        AccessRecord{.object = {TenantId("tenant"), "key-a"},
+                     .block_size = 64,
+                     .tier = CacheTier::kL1Host,
+                     .is_hit = true});
+    MetricBatch second;
+    second.accesses.push_back(
+        AccessRecord{.object = {TenantId("tenant"), "key-b"},
+                     .block_size = 128,
+                     .tier = CacheTier::kL1Host,
+                     .is_hit = true});
+
+    ASSERT_TRUE(service.Send("report_metric_batch",
+                             codec.EncodeMetricBatch(first)));
+    ASSERT_TRUE(service.Send("report_metric_batch",
+                             codec.EncodeMetricBatch(second)));
+
+    // Ownership-addressed reports all land on the receiving SubMaster, whose
+    // CFM component owns a single local runtime.
+    const auto snapshot = service.Snapshot();
+    ASSERT_EQ(snapshot.keys.size(), 2);
+    EXPECT_EQ(snapshot.keys[0].object.key, "key-a");
+    EXPECT_EQ(snapshot.keys[1].object.key, "key-b");
+}
+
+TEST(IoPatternFrameworkTest, CoroRpcCfmTransportRunsTheProductionWirePath) {
+    auto runtime = std::make_shared<IoPatternRuntime>(
+        IoPatternRuntime::Handlers{
+            .eviction = [](const EvictionPlan&) { return ErrorCode::OK; },
+            .prefetch = [](const PrefetchPlan&) { return ErrorCode::OK; },
+            .admission = [](const AdmissionResult&) { return ErrorCode::OK; }});
+    auto service = std::make_shared<CfmService>(runtime);
+    CfmRpcService endpoint(service);
+    coro_rpc::coro_rpc_server server(1, 0, "127.0.0.1");
+    server.register_handler<&CfmRpcService::Send>(&endpoint);
+    ASSERT_FALSE(server.async_start().hasResult());
+
+    CoroRpcCfmTransport transport(
+        "127.0.0.1:" + std::to_string(server.port()),
+        std::chrono::milliseconds(500));
+
+    CfmBinaryCodec codec;
+    MetricBatch batch;
+    batch.accesses.push_back(
+        AccessRecord{.object = {TenantId("tenant"), "remote-key"},
+                     .is_hit = true});
+    batch.storage.push_back(StorageMetric{.source_id = "reporter",
+                                          .tier = CacheTier::kL1Host,
+                                          .memory_used_ratio = 0.75F});
+    EXPECT_TRUE(transport.Send("report_metric_batch",
+                               codec.EncodeMetricBatch(batch),
+                               std::chrono::milliseconds(500)));
+    // No authentication: the SubMaster merges the report into its local
+    // runtime and treats the transport source as the metric origin.
+    const auto snapshot = service->Snapshot();
+    ASSERT_EQ(snapshot.keys.size(), 1);
+    ASSERT_EQ(snapshot.storage.size(), 1);
+    EXPECT_EQ(snapshot.keys.front().object.key, "remote-key");
+    EXPECT_EQ(snapshot.storage.front().source_id, "reporter");
+
+    // Snapshot reports follow the same unauthenticated path.
+    IoPatternSnapshot snapshot_report;
+    snapshot_report.keys.push_back(
+        KeyMetrics{.object = {TenantId("tenant"), "snap-key"}});
+    EXPECT_TRUE(transport.Send("report_snapshot",
+                               codec.EncodeSnapshot(snapshot_report),
+                               std::chrono::milliseconds(500)));
+    EXPECT_EQ(service->Snapshot().keys.back().object.key, "snap-key");
+    server.stop();
+}
+
+TEST(IoPatternFrameworkTest, LocalCfmExecutesEvictionOnHighWatermarkSnapshot) {
+    // High-watermark policy now runs in the SubMaster's own runtime rather
+    // than in a separate central CFM process. Reports feed that runtime; a
+    // storage observation at >= 0.90 memory ratio then triggers a local
+    // eviction plan executed through the SubMaster handlers.
+    auto runtime = std::make_shared<IoPatternRuntime>(
+        IoPatternRuntime::Handlers{
+            .eviction = [](const EvictionPlan&) { return ErrorCode::OK; },
+            .prefetch = [](const PrefetchPlan&) { return ErrorCode::OK; },
+            .admission = [](const AdmissionResult&) { return ErrorCode::OK; }});
+    CfmService service(runtime);
+    CfmBinaryCodec codec;
+    MetricBatch batch;
+    batch.accesses.push_back(
+        AccessRecord{.object = {TenantId("tenant"), "cold-key"},
+                     .block_size = 1024,
+                     .tier = CacheTier::kL1Host,
+                     .is_hit = false});
+    ASSERT_TRUE(service.Send("report_metric_batch",
+                             codec.EncodeMetricBatch(batch)));
+    ASSERT_EQ(runtime->Snapshot().keys.size(), 1);
+
+    // Eviction is local: Execute() plans against the merged snapshot and
+    // invokes the storage handler directly (no policy delivery round trip).
+    const auto status = runtime->Execute(CacheTier::kL1Host, 1024,
+                                         TraceHistory{});
+    EXPECT_EQ(status.eviction, ErrorCode::OK);
+    EXPECT_GE(runtime->ObservabilitySnapshot().policy_decisions, 1);
+}
+
+TEST(IoPatternFrameworkTest, ReportDrivenCycleRunsAfterMergedReport) {
+    // A merged client report must drive the local analysis -> decision ->
+    // execution cycle on the receiving runtime (the driver that makes remote
+    // SubMaster CFM execution observable), not only the local watermark
+    // thread, the Put admission hook or explicit execute_* RPCs.
+    std::mutex observer_mutex;
+    std::condition_variable observer_condition;
+    std::optional<IoPatternRuntime::ReportDrivenCycleReport> last_report;
+    std::atomic<int> eviction_handled{0};
+    IoPatternRuntime::Config config;
+    config.report_driven_execution = true;
+    // Let the detached analyzer finish so pattern selection is deterministic
+    // in this test (the worker otherwise uses the 500 us bounded budget).
+    config.analysis_timeout_us = 30'000'000;
+    config.report_driven_observer =
+        [&](const IoPatternRuntime::ReportDrivenCycleReport& report) {
+            std::lock_guard lock(observer_mutex);
+            last_report = report;
+            observer_condition.notify_all();
+        };
+    auto rt = std::make_shared<IoPatternRuntime>(
+        IoPatternRuntime::Handlers{
+            .eviction = [&eviction_handled](const EvictionPlan&) {
+                ++eviction_handled;
+                return ErrorCode::OK;
+            },
+            .prefetch = [](const PrefetchPlan&) { return ErrorCode::OK; },
+            .admission = [](const AdmissionResult&) { return ErrorCode::OK; }},
+        std::move(config));
+    CfmService service(rt);
+    CfmBinaryCodec codec;
+    MetricBatch batch;
+    batch.accesses.push_back(
+        AccessRecord{.object = {TenantId("tenant"), "hot-key"},
+                     .observed_at_ns = 1,
+                     .block_size = 4096,
+                     .tier = CacheTier::kL1Host,
+                     .operation = IoOperation::kGet,
+                     .is_hit = true});
+    batch.storage.push_back(
+        StorageMetric{.source_id = "reporter",
+                      .observed_at_ns = 1,
+                      .tier = CacheTier::kL1Host,
+                      .used_bytes = 1024ULL * 1024 * 1024,
+                      .capacity_bytes = 1024ULL * 1024 * 1024,
+                      .memory_used_ratio = 0.95F});
+    ASSERT_TRUE(service.Send("report_metric_batch",
+                             codec.EncodeMetricBatch(batch)));
+
+    // Wait for the background cycle to drain the merged report.
+    std::unique_lock lock(observer_mutex);
+    ASSERT_TRUE(observer_condition.wait_for(lock, std::chrono::seconds(30), [&] {
+        return last_report.has_value();
+    }));
+    ASSERT_TRUE(last_report.has_value());
+    EXPECT_GE(last_report->cycle_id, 1);
+    EXPECT_GE(last_report->keys_analyzed, 1);
+    // 0.95 merged host-memory ratio exceeds the default 0.80 high watermark:
+    // the eviction dimension derived a target and executed through the
+    // storage handler.
+    EXPECT_GT(last_report->eviction_target_bytes, 0);
+    EXPECT_GT(eviction_handled.load(), 0);
+    EXPECT_EQ(last_report->eviction_status, ErrorCode::OK);
+}
+
+TEST(IoPatternFrameworkTest, ReportDrivenCycleSkipsEvictionWithoutPressure) {
+    // Below the high watermark the eviction dimension produces no action, but
+    // the cycle still runs so the report-driven pipeline stays observable.
+    std::mutex observer_mutex;
+    std::condition_variable observer_condition;
+    std::optional<IoPatternRuntime::ReportDrivenCycleReport> last_report;
+    std::atomic<int> eviction_handled{0};
+    IoPatternRuntime::Config config;
+    config.report_driven_execution = true;
+    config.report_driven_observer =
+        [&](const IoPatternRuntime::ReportDrivenCycleReport& report) {
+            std::lock_guard lock(observer_mutex);
+            last_report = report;
+            observer_condition.notify_all();
+        };
+    auto rt = std::make_shared<IoPatternRuntime>(
+        IoPatternRuntime::Handlers{
+            .eviction = [&eviction_handled](const EvictionPlan&) {
+                ++eviction_handled;
+                return ErrorCode::OK;
+            },
+            .prefetch = [](const PrefetchPlan&) { return ErrorCode::OK; },
+            .admission = [](const AdmissionResult&) { return ErrorCode::OK; }},
+        std::move(config));
+    CfmService service(rt);
+    CfmBinaryCodec codec;
+    MetricBatch batch;
+    batch.accesses.push_back(
+        AccessRecord{.object = {TenantId("tenant"), "key"},
+                     .observed_at_ns = 1,
+                     .block_size = 1024,
+                     .tier = CacheTier::kL1Host,
+                     .operation = IoOperation::kGet,
+                     .is_hit = true});
+    batch.storage.push_back(
+        StorageMetric{.source_id = "reporter",
+                      .observed_at_ns = 1,
+                      .tier = CacheTier::kL1Host,
+                      .used_bytes = 512ULL * 1024 * 1024,
+                      .capacity_bytes = 1024ULL * 1024 * 1024,
+                      .memory_used_ratio = 0.50F});
+    ASSERT_TRUE(service.Send("report_metric_batch",
+                             codec.EncodeMetricBatch(batch)));
+
+    std::unique_lock lock(observer_mutex);
+    ASSERT_TRUE(observer_condition.wait_for(lock, std::chrono::seconds(5), [&] {
+        return last_report.has_value();
+    }));
+    ASSERT_TRUE(last_report.has_value());
+    EXPECT_EQ(last_report->eviction_target_bytes, 0);
+    EXPECT_EQ(eviction_handled.load(), 0);
+}
+
+TEST(IoPatternFrameworkTest, ReportDrivenColdEvictionRunsWithoutPressure) {
+    // The cold-data eviction driver must run even when no storage watermark
+    // pressure is present: a report that only contains idle L1 keys still
+    // yields a bounded eviction request (cold_eviction=true) so eviction is
+    // driven by cold/hot analysis, not only by memory pressure.
+    std::mutex observer_mutex;
+    std::condition_variable observer_condition;
+    std::optional<IoPatternRuntime::ReportDrivenCycleReport> last_report;
+    std::atomic<int> eviction_handled{0};
+    IoPatternRuntime::Config config;
+    config.report_driven_execution = true;
+    config.report_driven_cold_eviction = true;
+    config.report_driven_cold_eviction_bytes = 128ULL * 1024 * 1024;
+    config.report_driven_cold_idle_threshold_us = 0;  // any idle L1 key counts
+    config.analysis_timeout_us = 30'000'000;
+    config.report_driven_observer =
+        [&](const IoPatternRuntime::ReportDrivenCycleReport& report) {
+            std::lock_guard lock(observer_mutex);
+            last_report = report;
+            observer_condition.notify_all();
+        };
+    auto rt = std::make_shared<IoPatternRuntime>(
+        IoPatternRuntime::Handlers{
+            .eviction = [&eviction_handled](const EvictionPlan&) {
+                ++eviction_handled;
+                return ErrorCode::OK;
+            },
+            .prefetch = [](const PrefetchPlan&) { return ErrorCode::OK; },
+            .admission = [](const AdmissionResult&) { return ErrorCode::OK; }},
+        std::move(config));
+    CfmService service(rt);
+    CfmBinaryCodec codec;
+    MetricBatch batch;
+    batch.accesses.push_back(
+        AccessRecord{.object = {TenantId("tenant"), "cold-key"},
+                     .observed_at_ns = 1,
+                     .block_size = 1024,
+                     .tier = CacheTier::kL1Host,
+                     .operation = IoOperation::kGet,
+                     .is_hit = true});
+    // No storage metric => no pressure path; only the cold driver can act.
+    ASSERT_TRUE(service.Send("report_metric_batch",
+                             codec.EncodeMetricBatch(batch)));
+
+    std::unique_lock lock(observer_mutex);
+    ASSERT_TRUE(observer_condition.wait_for(lock, std::chrono::seconds(30), [&] {
+        return last_report.has_value();
+    }));
+    ASSERT_TRUE(last_report.has_value());
+    EXPECT_TRUE(last_report->cold_eviction);
+    EXPECT_GT(last_report->eviction_target_bytes, 0);
+    EXPECT_GT(eviction_handled.load(), 0);
+    EXPECT_EQ(last_report->eviction_status, ErrorCode::OK);
+}
+
+TEST(IoPatternFrameworkTest, ReportDrivenTierDownLabelsCandidatesWithoutPressure) {
+    // The tier-down driver must make the policy label its candidates as
+    // demotions: the plan it produces copies the selected keys down to
+    // LOCAL_DISK and keeps their MEMORY replica, so nothing is reclaimed. It
+    // fires from a report with no storage pressure at all.
+    std::mutex observer_mutex;
+    std::condition_variable observer_condition;
+    std::optional<IoPatternRuntime::ReportDrivenCycleReport> last_report;
+    std::mutex plan_mutex;
+    std::optional<EvictionPlan> handled_plan;
+    IoPatternRuntime::Config config;
+    config.report_driven_execution = true;
+    // The budget alone enables the driver: there is no enable flag.
+    config.tier_down_bytes_per_cycle = 96ULL * 1024 * 1024;
+    // Let the detached analyzer finish so candidate selection is deterministic.
+    config.analysis_timeout_us = 30'000'000;
+    config.report_driven_observer =
+        [&](const IoPatternRuntime::ReportDrivenCycleReport& report) {
+            std::lock_guard lock(observer_mutex);
+            last_report = report;
+            observer_condition.notify_all();
+        };
+    auto rt = std::make_shared<IoPatternRuntime>(
+        IoPatternRuntime::Handlers{
+            .eviction =
+                [&](const EvictionPlan& plan) {
+                    std::lock_guard lock(plan_mutex);
+                    handled_plan = plan;
+                    return ErrorCode::OK;
+                },
+            .prefetch = [](const PrefetchPlan&) { return ErrorCode::OK; },
+            .admission = [](const AdmissionResult&) { return ErrorCode::OK; }},
+        std::move(config));
+    CfmService service(rt);
+    CfmBinaryCodec codec;
+    MetricBatch batch;
+    batch.accesses.push_back(
+        AccessRecord{.object = {TenantId("tenant"), "demote-key"},
+                     .observed_at_ns = 1,
+                     .block_size = 4096,
+                     .tier = CacheTier::kL1Host,
+                     .operation = IoOperation::kGet,
+                     .is_hit = true});
+    // No storage metric, no cold-eviction driver: only tier down can act.
+    ASSERT_TRUE(service.Send("report_metric_batch",
+                             codec.EncodeMetricBatch(batch)));
+
+    std::unique_lock lock(observer_mutex);
+    ASSERT_TRUE(observer_condition.wait_for(lock, std::chrono::seconds(30), [&] {
+        return last_report.has_value();
+    }));
+    ASSERT_TRUE(last_report.has_value());
+    EXPECT_TRUE(last_report->tier_down);
+    EXPECT_FALSE(last_report->cold_eviction);
+    EXPECT_EQ(last_report->eviction_target_bytes, 96ULL * 1024 * 1024);
+    EXPECT_GT(last_report->eviction_candidates, 0u);
+    EXPECT_EQ(last_report->eviction_status, ErrorCode::OK);
+
+    std::lock_guard plan_lock(plan_mutex);
+    ASSERT_TRUE(handled_plan.has_value());
+    // The budget is carried as a demotion budget, and every candidate is
+    // labelled a demotion -- the action comes from the driver, not target_tier.
+    EXPECT_EQ(handled_plan->tier_down_target_bytes, 96ULL * 1024 * 1024);
+    ASSERT_FALSE(handled_plan->candidates.empty());
+    for (const auto& candidate : handled_plan->candidates) {
+        EXPECT_EQ(candidate.action, EvictionAction::kTierDown);
+    }
+}
+
+TEST(IoPatternFrameworkTest, ReportDrivenTierDownYieldsToPressureEviction) {
+    // A demotion frees nothing, so a reclaim always wins the cycle: with the
+    // tier-down driver enabled and host memory above the high watermark, the
+    // same configuration must produce an eviction plan instead of a demotion.
+    std::mutex observer_mutex;
+    std::condition_variable observer_condition;
+    std::optional<IoPatternRuntime::ReportDrivenCycleReport> last_report;
+    std::mutex plan_mutex;
+    std::optional<EvictionPlan> handled_plan;
+    IoPatternRuntime::Config config;
+    config.report_driven_execution = true;
+    // Same budget-only enablement, with host memory above the high watermark.
+    config.tier_down_bytes_per_cycle = 96ULL * 1024 * 1024;
+    config.analysis_timeout_us = 30'000'000;
+    config.report_driven_observer =
+        [&](const IoPatternRuntime::ReportDrivenCycleReport& report) {
+            std::lock_guard lock(observer_mutex);
+            last_report = report;
+            observer_condition.notify_all();
+        };
+    auto rt = std::make_shared<IoPatternRuntime>(
+        IoPatternRuntime::Handlers{
+            .eviction =
+                [&](const EvictionPlan& plan) {
+                    std::lock_guard lock(plan_mutex);
+                    handled_plan = plan;
+                    return ErrorCode::OK;
+                },
+            .prefetch = [](const PrefetchPlan&) { return ErrorCode::OK; },
+            .admission = [](const AdmissionResult&) { return ErrorCode::OK; }},
+        std::move(config));
+    CfmService service(rt);
+    CfmBinaryCodec codec;
+    MetricBatch batch;
+    batch.accesses.push_back(
+        AccessRecord{.object = {TenantId("tenant"), "hot-key"},
+                     .observed_at_ns = 1,
+                     .block_size = 4096,
+                     .tier = CacheTier::kL1Host,
+                     .operation = IoOperation::kGet,
+                     .is_hit = true});
+    batch.storage.push_back(
+        StorageMetric{.source_id = "reporter",
+                      .observed_at_ns = 1,
+                      .tier = CacheTier::kL1Host,
+                      .used_bytes = 1024ULL * 1024 * 1024,
+                      .capacity_bytes = 1024ULL * 1024 * 1024,
+                      .memory_used_ratio = 0.95F});
+    ASSERT_TRUE(service.Send("report_metric_batch",
+                             codec.EncodeMetricBatch(batch)));
+
+    std::unique_lock lock(observer_mutex);
+    ASSERT_TRUE(observer_condition.wait_for(lock, std::chrono::seconds(30), [&] {
+        return last_report.has_value();
+    }));
+    ASSERT_TRUE(last_report.has_value());
+    EXPECT_FALSE(last_report->tier_down);
+    EXPECT_FALSE(last_report->cold_eviction);
+    EXPECT_GT(last_report->eviction_target_bytes, 0);
+    EXPECT_EQ(last_report->eviction_status, ErrorCode::OK);
+
+    std::lock_guard plan_lock(plan_mutex);
+    ASSERT_TRUE(handled_plan.has_value());
+    EXPECT_EQ(handled_plan->tier_down_target_bytes, 0u);
+    ASSERT_FALSE(handled_plan->candidates.empty());
+    for (const auto& candidate : handled_plan->candidates) {
+        EXPECT_EQ(candidate.action, EvictionAction::kEvict);
+    }
+}
+
+TEST(IoPatternFrameworkTest, ReportDrivenTierDownPavesColdDataBeforeColdEviction) {
+    // Both drivers act below the watermark, but only one can own the cycle. The
+    // tier-down budget takes it: demoting a key that the same cycle would have
+    // discarded defeats the point of paving cold data down first, so the
+    // cold-eviction driver only keeps the slot when no tier-down budget is
+    // configured (see ReportDrivenColdEvictionRunsWithoutPressure).
+    std::mutex observer_mutex;
+    std::condition_variable observer_condition;
+    std::optional<IoPatternRuntime::ReportDrivenCycleReport> last_report;
+    std::mutex plan_mutex;
+    std::optional<EvictionPlan> handled_plan;
+    IoPatternRuntime::Config config;
+    config.report_driven_execution = true;
+    config.tier_down_bytes_per_cycle = 96ULL * 1024 * 1024;
+    config.report_driven_cold_eviction = true;
+    config.report_driven_cold_eviction_bytes = 128ULL * 1024 * 1024;
+    config.report_driven_cold_idle_threshold_us = 0;
+    config.analysis_timeout_us = 30'000'000;
+    config.report_driven_observer =
+        [&](const IoPatternRuntime::ReportDrivenCycleReport& report) {
+            std::lock_guard lock(observer_mutex);
+            last_report = report;
+            observer_condition.notify_all();
+        };
+    auto rt = std::make_shared<IoPatternRuntime>(
+        IoPatternRuntime::Handlers{
+            .eviction =
+                [&](const EvictionPlan& plan) {
+                    std::lock_guard lock(plan_mutex);
+                    handled_plan = plan;
+                    return ErrorCode::OK;
+                },
+            .prefetch = [](const PrefetchPlan&) { return ErrorCode::OK; },
+            .admission = [](const AdmissionResult&) { return ErrorCode::OK; }},
+        std::move(config));
+    CfmService service(rt);
+    CfmBinaryCodec codec;
+    MetricBatch batch;
+    batch.accesses.push_back(
+        AccessRecord{.object = {TenantId("tenant"), "cold-key"},
+                     .observed_at_ns = 1,
+                     .block_size = 4096,
+                     .tier = CacheTier::kL1Host,
+                     .operation = IoOperation::kGet,
+                     .is_hit = true});
+    ASSERT_TRUE(service.Send("report_metric_batch",
+                             codec.EncodeMetricBatch(batch)));
+
+    std::unique_lock lock(observer_mutex);
+    ASSERT_TRUE(observer_condition.wait_for(lock, std::chrono::seconds(30), [&] {
+        return last_report.has_value();
+    }));
+    ASSERT_TRUE(last_report.has_value());
+    EXPECT_TRUE(last_report->tier_down);
+    EXPECT_FALSE(last_report->cold_eviction);
+    // The tier-down budget, not the cold-eviction budget, sized this cycle.
+    EXPECT_EQ(last_report->eviction_target_bytes, 96ULL * 1024 * 1024);
+
+    std::lock_guard plan_lock(plan_mutex);
+    ASSERT_TRUE(handled_plan.has_value());
+    EXPECT_EQ(handled_plan->tier_down_target_bytes, 96ULL * 1024 * 1024);
+    ASSERT_FALSE(handled_plan->candidates.empty());
+    for (const auto& candidate : handled_plan->candidates) {
+        EXPECT_EQ(candidate.action, EvictionAction::kTierDown);
+    }
+}
+
+TEST(IoPatternFrameworkTest, ReporterBackgroundLifecycleFlushesOnStop) {
+    size_t batches = 0;
+    IoPatternReporter reporter(4, [&](const MetricBatch&) {
+        ++batches;
+        return true;
+    });
+    reporter.Enqueue(InferenceMetrics{});
+    reporter.Start();
+    reporter.Stop();
+    EXPECT_EQ(batches, 1);
+}
+
+TEST(IoPatternFrameworkTest, DegradingPolicyEngineSwitchesToFallback) {
+    auto primary = std::make_shared<ComposedPolicyEngine>(
+        std::make_shared<TestEvictionOps>(), nullptr, nullptr);
+    auto fallback = std::make_shared<ComposedPolicyEngine>(nullptr, nullptr,
+                                                            nullptr);
+    DegradingPolicyEngine engine(primary, fallback, 2);
+    EXPECT_FALSE(engine.degraded());
+    EXPECT_EQ(engine.PlanEviction({}, CacheTier::kL1Host, 10).target_bytes, 10);
+    engine.RecordFailure();
+    engine.RecordFailure();
+    EXPECT_TRUE(engine.degraded());
+    EXPECT_TRUE(engine.PlanEviction({}, CacheTier::kL1Host, 10)
+                    .candidates.empty());
+    engine.ForceDegraded(false);
+    EXPECT_FALSE(engine.degraded());
+    EXPECT_EQ(engine.consecutive_failures(), 0);
+}
+
+TEST(IoPatternFrameworkTest, FeedbackWindowAggregatesBoundedSamples) {
+    PolicyFeedbackWindow window(2);
+    window.Record({.hit_rate_delta = -0.2F, .prefetch_accuracy = 0.5F});
+    window.Record({.hit_rate_delta = 0.1F, .prefetch_accuracy = 0.9F});
+    window.Record({.hit_rate_delta = -0.4F, .prefetch_accuracy = 0.3F});
+    const auto stats = window.Snapshot();
+    EXPECT_EQ(stats.samples, 2);
+    // Capacity 2 keeps the two most recent samples, i.e. the second and third
+    // records: (-0.4 + 0.1) / 2. The previous expectation averaged the first and
+    // third records, which no bounded window can produce.
+    EXPECT_FLOAT_EQ(stats.hit_rate_delta, (0.1F - 0.4F) / 2.0F);
+    EXPECT_FLOAT_EQ(stats.prefetch_accuracy, (0.9F + 0.3F) / 2.0F);
+}
+
+TEST(IoPatternFrameworkTest, AdaptiveTunerChangesWeightsAfterNegativeStreak) {
+    AdaptivePolicyTuner tuner(3);
+    ScoreBasedEvictionConfig config;
+    // prefetch_accuracy is stated explicitly: leaving it at its 0.0F default
+    // would trip the tuner's conservative branch (prefetch_accuracy < 0.2F) on
+    // the very first sample and the frequency/idle streak path would never run.
+    const PolicyFeedbackStats negative{.hit_rate_delta = -0.1F,
+                                       .prefetch_accuracy = 1.0F};
+    EXPECT_FALSE(tuner.Tune(negative, config));
+    EXPECT_FALSE(tuner.Tune(negative, config));
+    EXPECT_TRUE(tuner.Tune(negative, config));
+    EXPECT_FLOAT_EQ(config.frequency_weight, 0.8F);
+    EXPECT_FLOAT_EQ(config.idle_weight, 1.1F);
+    EXPECT_FALSE(tuner.Tune({.hit_rate_delta = 0.0F, .prefetch_accuracy = 1.0F},
+                            config));
+}
+
+TEST(IoPatternFrameworkTest, AdaptiveTunerHandlesChurnAndPersistsChanges) {
+    AdaptivePolicyTuner tuner(3);
+    ScoreBasedEvictionConfig config;
+    bool persisted = false;
+    tuner.SetPersistenceCallback(
+        [&](const ScoreBasedEvictionConfig&) { persisted = true; });
+    EXPECT_TRUE(tuner.Tune({.eviction_churn = 0.8F}, config));
+    EXPECT_TRUE(tuner.conservative());
+    EXPECT_TRUE(persisted);
+}
+
+TEST(IoPatternFrameworkTest, ObservabilityTracksPolicyAndDegradeCounters) {
+    IoPatternObservability metrics;
+    metrics.RecordCollectLatency(10);
+    metrics.RecordCollectLatency(3);
+    metrics.RecordAnalyzeLatency(20);
+    metrics.RecordPolicyDecision(true);
+    metrics.RecordPolicyDecision(false);
+    metrics.RecordFalsePositive();
+    metrics.RecordDegrade();
+    metrics.RecordReportDrop(2);
+    const auto snapshot = metrics.Snapshot();
+    EXPECT_EQ(snapshot.collect_latency_us, 10);
+    EXPECT_EQ(snapshot.analyze_latency_us, 20);
+    EXPECT_EQ(snapshot.policy_decisions, 2);
+    EXPECT_EQ(snapshot.strategy_hits, 1);
+    EXPECT_EQ(snapshot.strategy_trials, 2);
+    EXPECT_EQ(snapshot.false_positives, 1);
+    EXPECT_EQ(snapshot.degrade_count, 1);
+    EXPECT_EQ(snapshot.report_drop_count, 2);
+    EXPECT_FLOAT_EQ(snapshot.strategy_hit_rate, 0.5F);
+    EXPECT_FLOAT_EQ(snapshot.false_positive_rate, 0.5F);
+    EXPECT_FLOAT_EQ(metrics.Snapshot(2.0).policy_decision_qps, 1.0F);
+}
+
+TEST(IoPatternFrameworkTest, SlidingWindowAnalyzerComputesPercentiles) {
+    SlidingWindowAnalyzer analyzer(100);
+    IoPatternSnapshot first;
+    first.generated_at_ns = 10;
+    first.keys.push_back(KeyMetrics{.object = {TenantId("tenant"), "first"},
+                                    .access_count_window = 1,
+                                    .block_size = 100,
+                                    .token_count = 20 * 1024,
+                                    .prefix_fanout = 20,
+                                    .match_length = 512});
+    IoPatternSnapshot second;
+    second.generated_at_ns = 50;
+    second.keys.push_back(KeyMetrics{.object = {TenantId("tenant"), "second"},
+                                     .access_count_window = 5,
+                                     .block_size = 300,
+                                     .token_count = 30,
+                                     .prefix_fanout = 20,
+                                     .match_length = 300});
+    // Both snapshots must reach the analyzer: the aggregate has to hold two
+    // samples for kMixed (one code-agent shaped key, one conversation shaped
+    // key), and the percentile expectations below are computed over both. The
+    // first snapshot was previously built and then never fed to the analyzer,
+    // which left a single sample and made the kMixed expectation unreachable.
+    analyzer.Analyze(first);
+    EXPECT_EQ(analyzer.DetectWorkloadType(second), WorkloadType::kMixed);
+    const auto stats = analyzer.FeatureStats();
+    EXPECT_EQ(stats.samples, 2);
+    // Percentile() ranks with size/2, so two samples select the upper-middle
+    // element: sorted {30, 20480} at index 1.
+    EXPECT_EQ(stats.token_median, 20480);
+    EXPECT_EQ(stats.fanout_p90, 20);
+    EXPECT_EQ(stats.block_p90, 300);
+}
+
+TEST(IoPatternFrameworkTest, SlidingWindowDeduplicatesObjectsAndBoundsHistory) {
+    SlidingWindowAnalyzer analyzer(1'000, {}, 2);
+    const ObjectRef object{TenantId("tenant-a"), "same-key"};
+    for (uint64_t timestamp = 1; timestamp <= 3; ++timestamp) {
+        IoPatternSnapshot snapshot;
+        snapshot.generated_at_ns = timestamp;
+        snapshot.keys.push_back(KeyMetrics{.object = object,
+                                           .access_count_window = timestamp,
+                                           .token_count =
+                                               static_cast<uint32_t>(timestamp)});
+        analyzer.Analyze(snapshot);
+    }
+
+    const auto stats = analyzer.FeatureStats();
+    EXPECT_EQ(stats.samples, 1);
+    EXPECT_EQ(stats.token_median, 3);
+    EXPECT_EQ(stats.frequency_median, 3);
+}
+
+TEST(IoPatternFrameworkTest, SlidingWindowCapsASingleOversizedSnapshot) {
+    SlidingWindowAnalyzer analyzer(1'000, {}, 2);
+    IoPatternSnapshot snapshot;
+    snapshot.generated_at_ns = 1;
+    snapshot.keys = {
+        KeyMetrics{.object = {TenantId("tenant"), "c"}},
+        KeyMetrics{.object = {TenantId("tenant"), "a"}},
+        KeyMetrics{.object = {TenantId("tenant"), "b"}},
+    };
+
+    analyzer.Analyze(snapshot);
+    EXPECT_EQ(analyzer.FeatureStats().samples, 2);
+}
+
+TEST(IoPatternFrameworkTest, KMeansFallbackLabelsIndependentSessions) {
+    SlidingWindowAnalyzer analyzer;
+    IoPatternSnapshot snapshot;
+    snapshot.generated_at_ns = 1;
+    snapshot.keys = {
+        KeyMetrics{.object = {TenantId("tenant-a"), "long"},
+                   .session_id = "code-session",
+                   .token_count = 20 * 1024,
+                   .prefix_fanout = 20,
+                   .match_length = 512},
+        KeyMetrics{.object = {TenantId("tenant-b"), "small"},
+                   .session_id = "recommendation-session",
+                   .access_count_window = 30,
+                   .block_size = 64 * 1024},
+    };
+
+    const auto result = analyzer.Analyze(snapshot);
+    EXPECT_EQ(result.workload_type, WorkloadType::kMixed);
+    ASSERT_EQ(result.sessions.size(), 2);
+    EXPECT_NE(result.sessions[0].workload_type, result.sessions[1].workload_type);
+}
+
+TEST(IoPatternFrameworkTest, TierExecutorBridgesPolicyResults) {
+    int evictions = 0;
+    int prefetches = 0;
+    int admissions = 0;
+    TierOperationExecutor executor(
+        [&](const EvictionPlan&) { ++evictions; return ErrorCode::OK; },
+        [&](const PrefetchPlan&) { ++prefetches; return ErrorCode::OK; },
+        [&](const AdmissionResult&) { ++admissions; return ErrorCode::OK; });
+    PolicyResult result;
+    result.eviction.target_bytes = 1024;
+    result.prefetch.candidates.push_back(PrefetchCandidate{});
+    result.admissions.push_back(
+        AdmissionResult{.decision = AdmissionDecision::kAdmit});
+    const auto status = executor.Execute(result);
+    EXPECT_EQ(status.eviction, ErrorCode::OK);
+    EXPECT_EQ(status.prefetch, ErrorCode::OK);
+    ASSERT_EQ(status.admissions.size(), 1);
+    EXPECT_EQ(status.admissions.front(), ErrorCode::OK);
+    EXPECT_EQ(evictions, 1);
+    EXPECT_EQ(prefetches, 1);
+    EXPECT_EQ(admissions, 1);
+
+    TierOperationExecutor degraded({}, {}, {});
+    const auto degraded_status = degraded.Execute(result);
+    EXPECT_TRUE(degraded_status.degraded);
+    EXPECT_EQ(degraded_status.prefetch,
+              ErrorCode::UNAVAILABLE_IN_CURRENT_MODE);
+}
+
+TEST(IoPatternFrameworkTest, LegacyEvictionAdapterUsesLruFallback) {
+    auto lru = std::make_shared<LRUEvictionStrategy>();
+    LegacyEvictionOps fallback(lru);
+    PolicyContext context;
+    KeyMetrics first{.object = {TenantId("tenant-a"), "first"},
+                     .block_size = 10,
+                     .replica_tiers = CacheTierBit(CacheTier::kL1Host)};
+    KeyMetrics second{.object = {TenantId("tenant-a"), "second"},
+                     .block_size = 20,
+                     .replica_tiers = CacheTierBit(CacheTier::kL1Host)};
+    context.snapshot.keys = {first, second};
+    const auto plan = fallback.Evaluate(context, CacheTier::kL1Host, 10);
+    ASSERT_EQ(plan.candidates.size(), 1);
+    EXPECT_EQ(plan.candidates.front().object.key, "first");
+}
+
+TEST(IoPatternFrameworkTest, ScoreBasedEvictionMayCrossTheByteTarget) {
+    PolicyContext context;
+    context.snapshot.keys = {
+        KeyMetrics{.object = {TenantId("tenant-a"), "large"},
+                   .block_size = 64,
+                   .replica_tiers = CacheTierBit(CacheTier::kL1Host)}};
+    context.analysis.keys = {
+        KeyPattern{.object = {TenantId("tenant-a"), "large"}}};
+    ScoreBasedEvictionOps eviction;
+
+    const auto plan = eviction.Evaluate(context, CacheTier::kL1Host, 32);
+    ASSERT_EQ(plan.candidates.size(), 1);
+    EXPECT_EQ(plan.candidates.front().bytes, 64);
+}
+
+TEST(IoPatternFrameworkTest, ScoreBasedEvictionUsesTierSpecificSignals) {
+    PolicyContext context;
+    context.snapshot.keys = {
+        KeyMetrics{.object = {TenantId("tenant-a"), "small-single-copy"},
+                   .block_size = 10,
+                   .other_replica_count = 0,
+                   .replica_tiers = CacheTierBit(CacheTier::kL3NofSsd)},
+        KeyMetrics{.object = {TenantId("tenant-a"), "large-redundant"},
+                   .block_size = 100,
+                   .other_replica_count = 1,
+                   .replica_tiers = CacheTierBit(CacheTier::kL3NofSsd)},
+    };
+    context.analysis.keys = {
+        KeyPattern{.object = context.snapshot.keys[0].object, .idle_score = 1.0F},
+        KeyPattern{.object = context.snapshot.keys[1].object, .idle_score = 1.0F},
+    };
+
+    ScoreBasedEvictionOps eviction;
+    const auto plan = eviction.Evaluate(context, CacheTier::kL3NofSsd, 110);
+
+    ASSERT_EQ(plan.candidates.size(), 2);
+    EXPECT_EQ(plan.candidates.front().object.key, "large-redundant");
+    EXPECT_EQ(plan.candidates.front().target_tier, CacheTier::kL3NofSsd);
+}
+
+TEST(IoPatternFrameworkTest, TierDownTemplatesChooseDocumentedTargets) {
+    PolicyContext context;
+    context.snapshot.keys = {KeyMetrics{
+        .object = {TenantId("tenant"), "key"},
+        .block_size = 64,
+        .replica_tiers = CacheTierBit(CacheTier::kL0Hbm)}};
+    context.analysis.keys = {KeyPattern{.object = context.snapshot.keys.front().object}};
+
+    ScoreBasedEvictionOps code({.tier_down_mode = TierDownMode::kSkipHost});
+    EXPECT_EQ(code.Evaluate(context, CacheTier::kL0Hbm, 64)
+                  .candidates.front().target_tier,
+              CacheTier::kL2Segment);
+    ScoreBasedEvictionOps recommendation(
+        {.tier_down_mode = TierDownMode::kStepwise});
+    EXPECT_EQ(recommendation.Evaluate(context, CacheTier::kL0Hbm, 64)
+                  .candidates.front().target_tier,
+              CacheTier::kL1Host);
+}
+
+// The candidate action is decided by the driver (PolicyContext::tier_down) and
+// must never be derived from target_tier: TierDownTarget() returns source+1 for
+// L0/L1/L2 alike, so a derived action would label every candidate a demotion and
+// eviction would stop working entirely.
+TEST(IoPatternFrameworkTest, TierDownContextLabelsCandidatesAndBudget) {
+    PolicyContext context;
+    context.snapshot.keys = {KeyMetrics{
+        .object = {TenantId("tenant"), "key"},
+        .block_size = 64,
+        .replica_tiers = CacheTierBit(CacheTier::kL1Host)}};
+    context.analysis.keys = {
+        KeyPattern{.object = context.snapshot.keys.front().object}};
+
+    ScoreBasedEvictionOps ops;
+
+    const auto reclaimed = ops.Evaluate(context, CacheTier::kL1Host, 64);
+    ASSERT_EQ(reclaimed.candidates.size(), 1);
+    EXPECT_EQ(reclaimed.candidates.front().object.key, "key");
+    EXPECT_EQ(reclaimed.candidates.front().action, EvictionAction::kEvict);
+    EXPECT_EQ(reclaimed.tier_down_target_bytes, 0u);
+
+    context.tier_down = true;
+    const auto demoted = ops.Evaluate(context, CacheTier::kL1Host, 64);
+    ASSERT_EQ(demoted.candidates.size(), 1);
+    EXPECT_EQ(demoted.candidates.front().object.key, "key");
+    EXPECT_EQ(demoted.candidates.front().action, EvictionAction::kTierDown);
+    EXPECT_EQ(demoted.tier_down_target_bytes, 64u);
+    // Same victims either way: only the action differs.
+    EXPECT_EQ(demoted.candidates.front().target_tier,
+              reclaimed.candidates.front().target_tier);
+}
+
+TEST(IoPatternFrameworkTest, PrefetchRequiresConfidenceAndNeverPromotesToHbm) {
+    PolicyContext context;
+    context.snapshot.keys = {
+        KeyMetrics{.object = {TenantId("tenant-a"), "low-confidence"},
+                   .block_size = 64,
+                   .replica_tiers = CacheTierBit(CacheTier::kL3NofSsd)},
+        KeyMetrics{.object = {TenantId("tenant-a"), "host-only"},
+                   .block_size = 64,
+                   .replica_tiers = CacheTierBit(CacheTier::kL1Host)},
+    };
+    context.analysis.keys = {
+        KeyPattern{.object = context.snapshot.keys[0].object, .confidence = 0.5F},
+        KeyPattern{.object = context.snapshot.keys[1].object, .confidence = 0.9F},
+    };
+    TraceHistory trace{.events = {
+        TraceEvent{.object = context.snapshot.keys[0].object,
+                   .match_length = 512,
+                   .is_hit = true},
+        TraceEvent{.object = context.snapshot.keys[1].object,
+                   .match_length = 512,
+                   .is_hit = true},
+    }};
+
+    TraceBasedPrefetchOps prefetch;
+    const auto plan = prefetch.Evaluate(context, trace);
+
+    EXPECT_TRUE(plan.candidates.empty());
+}
+
+TEST(IoPatternFrameworkTest, RuntimeConnectsCollectionAnalysisPolicyAndHandlers) {
+    int evictions = 0;
+    int prefetches = 0;
+    int admissions = 0;
+    IoPatternRuntime runtime(
+        IoPatternRuntime::Handlers{
+            .eviction = [&](const EvictionPlan&) {
+                ++evictions;
+                return ErrorCode::OK;
+            },
+            .prefetch = [&](const PrefetchPlan&) {
+                ++prefetches;
+                return ErrorCode::OK;
+            },
+            .admission = [&](const AdmissionResult&) {
+                ++admissions;
+                return ErrorCode::OK;
+            },
+        });
+
+    // observed_at_ns is deliberately left unset so the collector stamps this
+    // access with its own clock: the frequency window is a true rolling window,
+    // so a synthetic epoch timestamp would be pruned and the admission would be
+    // rejected for frequency instead of exercising the handler.
+    AccessRecord access{.object = {TenantId("tenant-a"), "runtime-key"},
+                        .block_size = 64,
+                        .tier = CacheTier::kL2Segment,
+                        .is_hit = true};
+    // Two accesses: the default admission frequency gate is 2, aligned with the
+    // master's promotion_admission_threshold. A single observation would be
+    // rejected for frequency instead of exercising the handler.
+    runtime.RecordAccess(access.object.key, access);
+    runtime.RecordAccess(access.object.key, access);
+    runtime.ReportInferenceMetrics(
+        InferenceMetrics{.object = access.object, .match_length = 512});
+
+    const auto status = runtime.Execute(CacheTier::kL2Segment, 64,
+                                        TraceHistory{}, {access.object});
+
+    EXPECT_EQ(status.eviction, ErrorCode::OK);
+    ASSERT_EQ(status.admissions.size(), 1);
+    EXPECT_EQ(status.admissions.front(), ErrorCode::OK);
+    EXPECT_EQ(evictions, 1);
+    EXPECT_EQ(admissions, 1);
+    EXPECT_GE(runtime.Snapshot().keys.size(), 1);
+}
+
+TEST(IoPatternFrameworkTest, RuntimeExecutesCfmCommandsThroughStorageHandlers) {
+    int admissions = 0;
+    IoPatternRuntime runtime(
+        {.eviction = [](const EvictionPlan&) { return ErrorCode::OK; },
+         .prefetch = [](const PrefetchPlan&) { return ErrorCode::OK; },
+         .admission = [&admissions](const AdmissionResult&) {
+             ++admissions;
+             return ErrorCode::OK;
+         }});
+    // In the embedded architecture the receiving SubMaster executes delivered
+    // policy commands through its own runtime; there is no client-side
+    // dispatch loop any more.
+    EXPECT_EQ(runtime.ExecuteCommand(
+                  AdmissionResult{.object = {TenantId("tenant"), "key"},
+                                  .decision = AdmissionDecision::kAdmit}),
+              ErrorCode::OK);
+    EXPECT_EQ(admissions, 1);
+}
+
+TEST(IoPatternFrameworkTest, RuntimeSchedulesAdmissionOffTheProducerPath) {
+    std::promise<AdmissionResult> handled;
+    IoPatternRuntime runtime(
+        {.eviction = [](const EvictionPlan&) { return ErrorCode::OK; },
+         .prefetch = [](const PrefetchPlan&) { return ErrorCode::OK; },
+         .admission = [&handled](const AdmissionResult& result) {
+             handled.set_value(result);
+             return ErrorCode::OK;
+         }});
+    AccessRecord access{.object = {TenantId("tenant"), "disk-key"},
+                        .tier = CacheTier::kL3NofSsd,
+                        .operation = IoOperation::kPut};
+    // The default admission frequency gate is 2, so two observations are needed
+    // before the admission handler is reached.
+    runtime.RecordAccess(access.object.key, access);
+    runtime.RecordAccess(access.object.key, access);
+
+    EXPECT_TRUE(runtime.ScheduleAdmission(access.object, CacheTier::kL1Host));
+    auto result = handled.get_future();
+    ASSERT_EQ(result.wait_for(std::chrono::seconds(1)),
+              std::future_status::ready);
+    EXPECT_EQ(result.get().object, access.object);
+}
+
+TEST(IoPatternFrameworkTest, OwnershipClientBucketsReportsByResolvedOwner) {
+    auto runtime = std::make_shared<IoPatternRuntime>(
+        IoPatternRuntime::Handlers{
+            .eviction = [](const EvictionPlan&) { return ErrorCode::OK; },
+            .prefetch = [](const PrefetchPlan&) { return ErrorCode::OK; },
+            .admission = [](const AdmissionResult&) { return ErrorCode::OK; }});
+    auto service = std::make_shared<CfmService>(runtime);
+    CfmRpcService endpoint(service);
+    coro_rpc::coro_rpc_server server(1, 0, "127.0.0.1");
+    server.register_handler<&CfmRpcService::Send>(&endpoint);
+    ASSERT_FALSE(server.async_start().hasResult());
+    const std::string owner_endpoint =
+        "127.0.0.1:" + std::to_string(server.port());
+
+    // Only keys starting with "owned/" resolve to the single SubMaster under
+    // test; "foreign/" and empty resolver results are dropped.
+    CfmOwnershipClient client(
+        [&](const TenantId&, const std::string& key)
+            -> std::optional<std::string> {
+            return key.rfind("owned/", 0) == 0
+                       ? std::optional<std::string>(owner_endpoint)
+                       : std::nullopt;
+        },
+        std::chrono::milliseconds(500));
+
+    MetricBatch batch;
+    batch.accesses.push_back(
+        AccessRecord{.object = {TenantId("tenant"), "owned/key-a"},
+                     .block_size = 64,
+                     .tier = CacheTier::kL1Host,
+                     .is_hit = true});
+    batch.accesses.push_back(
+        AccessRecord{.object = {TenantId("tenant"), "owned/key-b"},
+                     .block_size = 64,
+                     .tier = CacheTier::kL1Host,
+                     .is_hit = true});
+    batch.inference.push_back(InferenceMetrics{
+        .object = {TenantId("tenant"), "foreign/key"}, .session_id = "s"});
+
+    EXPECT_EQ(client.ReportMetricBatch(batch), ErrorCode::OK);
+    EXPECT_EQ(client.dropped_observations(), 1);
+
+    // Both owned observations were aggregated into one batch for the resolved
+    // owner and merged into that SubMaster's local runtime.
+    const auto snapshot = service->Snapshot();
+    ASSERT_EQ(snapshot.keys.size(), 2);
+    EXPECT_EQ(snapshot.keys[0].object.key, "owned/key-a");
+    EXPECT_EQ(snapshot.keys[1].object.key, "owned/key-b");
+    server.stop();
+}
+
+TEST(IoPatternFrameworkTest, UnavailablePrefetchCapabilityDoesNotDegradePolicy) {
+    // The prefetch handler's own primitive can be structurally unavailable:
+    // promotion may be disabled, or the object may have no LOCAL_DISK source
+    // replica to promote from. The policy cannot influence either outcome, so
+    // repeating cycles must not be counted as policy failure -- otherwise the
+    // whole workload policy is permanently replaced by the legacy fallback.
+    int prefetch_calls = 0;
+    IoPatternRuntime runtime(IoPatternRuntime::Handlers{
+        .eviction = [](const EvictionPlan&) { return ErrorCode::OK; },
+        .prefetch =
+            [&prefetch_calls](const PrefetchPlan&) {
+                ++prefetch_calls;
+                return ErrorCode::UNAVAILABLE_IN_CURRENT_MODE;
+            },
+        .admission = [](const AdmissionResult&) { return ErrorCode::OK; }});
+
+    AccessRecord access{.object = {TenantId("tenant-a"), "cold-key"},
+                        .block_size = 1024,
+                        // Local disk is the only tier the store can promote from,
+                        // and the only one that yields a prefetch candidate.
+                        .tier = CacheTier::kLocalDisk,
+                        .operation = IoOperation::kGet,
+                        .is_hit = true};
+    // A recommendation-shaped key yields a definitive workload classification
+    // and a confidence of 1.0, so the prefetch gate is genuinely exercised.
+    for (int i = 0; i < 21; ++i) {
+        runtime.RecordAccess(access.object.key, access);
+    }
+    runtime.ReportInferenceMetrics(
+        InferenceMetrics{.object = access.object, .match_length = 300});
+
+    TraceHistory trace;
+    trace.events.push_back(
+        TraceEvent{.object = access.object, .match_length = 300, .is_hit = true});
+
+    // Three consecutive reported failures is the DegradingPolicyEngine
+    // threshold used by the runtime. The short pause lets the analyzer thread
+    // of the previous cycle clear its in-flight flag, which would otherwise
+    // mark a cycle degraded for reasons unrelated to this test.
+    for (int cycle = 0; cycle < 3; ++cycle) {
+        std::this_thread::sleep_for(std::chrono::milliseconds(10));
+        runtime.Execute(CacheTier::kL1Host, 0, trace, {});
+    }
+
+    ASSERT_GE(prefetch_calls, 1) << "the prefetch handler must be exercised";
+    EXPECT_FALSE(runtime.degraded())
+        << "a structurally unavailable prefetch primitive is not a policy "
+           "failure";
+}
+
+TEST(IoPatternFrameworkTest, TierRemovalEventRetiresTheReplicaBit) {
+    // An object evicted from host memory must stop claiming an L1 replica, so
+    // it becomes promotable again instead of being treated as already resident
+    // in the head tier.
+    IoPatternRuntime runtime(
+        {.eviction = [](const EvictionPlan&) { return ErrorCode::OK; },
+         .prefetch = [](const PrefetchPlan&) { return ErrorCode::OK; },
+         .admission = [](const AdmissionResult&) { return ErrorCode::OK; }});
+    AccessRecord access{.object = {TenantId("tenant-a"), "tiered-key"},
+                        .block_size = 64,
+                        .tier = CacheTier::kL1Host,
+                        .is_hit = true};
+    runtime.RecordAccess(access.object.key, access);
+    ASSERT_EQ(runtime.Snapshot().keys.size(), 1U);
+    EXPECT_EQ(runtime.Snapshot().keys.front().replica_tiers,
+              CacheTierBit(CacheTier::kL1Host));
+
+    runtime.RecordTierEvent(CacheEvent{.type = CacheEventType::kRemoved,
+                                       .object = access.object,
+                                       .source_tier = CacheTier::kL1Host});
+
+    EXPECT_EQ(runtime.Snapshot().keys.front().replica_tiers,
+              static_cast<CacheTierMask>(0));
+}
+
+TEST(IoPatternFrameworkTest, TierChangeEventMovesTheReplicaBit) {
+    // Demotion keeps the lower-tier claim without keeping the upper one; a
+    // fresh insert adds a claim.
+    IoPatternCollectorImpl collector;
+    AccessRecord access{.object = {TenantId("tenant-a"), "moved-key"},
+                        .block_size = 64,
+                        .tier = CacheTier::kL1Host,
+                        .is_hit = true};
+    collector.RecordAccess(access.object.key, access);
+
+    collector.RecordTierEvent(
+        CacheEvent{.type = CacheEventType::kTierChanged,
+                   .object = access.object,
+                   .source_tier = CacheTier::kL1Host,
+                   .target_tier = CacheTier::kL3NofSsd});
+    EXPECT_EQ(collector.GetSnapshot().keys.front().replica_tiers,
+              CacheTierBit(CacheTier::kL3NofSsd));
+
+    collector.RecordTierEvent(CacheEvent{.type = CacheEventType::kInserted,
+                                         .object = access.object,
+                                         .target_tier = CacheTier::kL2Segment});
+    EXPECT_EQ(collector.GetSnapshot().keys.front().replica_tiers,
+              static_cast<CacheTierMask>(CacheTierBit(CacheTier::kL3NofSsd) |
+                                         CacheTierBit(CacheTier::kL2Segment)));
+}
+
+TEST(IoPatternFrameworkTest, LocalDiskCountsAsALowerTierThanHostMemory) {
+    // TierDepth, not declaration order, defines the storage ladder: kLocalDisk is
+    // declared last so the existing tier values stay stable on the CFI wire.
+    EXPECT_LT(TierDepth(CacheTier::kL1Host), TierDepth(CacheTier::kLocalDisk));
+    EXPECT_LT(TierDepth(CacheTier::kLocalDisk), TierDepth(CacheTier::kL2Segment));
+    EXPECT_LT(TierDepth(CacheTier::kL2Segment), TierDepth(CacheTier::kL3NofSsd));
+
+    // A local-disk copy is what makes reclaiming the host copy safe, which is
+    // exactly what the eviction score's lower-replica term rewards.
+    ScoreBasedEvictionOps eviction;
+    PolicyContext context;
+    KeyMetrics key;
+    key.object = {TenantId("tenant-a"), "offloaded"};
+    key.block_size = 64;
+    key.replica_tiers = CacheTierBit(CacheTier::kL1Host) |
+                        CacheTierBit(CacheTier::kLocalDisk);
+    context.snapshot.keys.push_back(key);
+    context.analysis.keys = {KeyPattern{.object = key.object, .idle_score = 1.0F}};
+
+    const auto plan = eviction.Evaluate(context, CacheTier::kL1Host, 64);
+    ASSERT_EQ(plan.candidates.size(), 1);
+    // idle_weight(1.0) * idle_score(1.0) + lower_replica_weight(1.0) * 1.0.
+    EXPECT_FLOAT_EQ(plan.candidates.front().score, 2.0F);
+}
+
+TEST(IoPatternFrameworkTest, ScoreEvictionHonoursTheColdIdleGate) {
+    // The cold-eviction driver gates victims by idle time. Applying that gate
+    // where candidates are selected -- rather than pre-summing idle bytes into
+    // the byte target -- keeps the budget and the victim set describing the same
+    // keys, so a pass cannot reclaim objects the driver never considered cold.
+    PolicyContext context;
+    context.min_idle_time_us = 1'000'000;  // 1 s
+    KeyMetrics fresh;
+    fresh.object = {TenantId("tenant-a"), "fresh"};
+    fresh.idle_time_us = 500'000;  // below the gate
+    fresh.block_size = 64;
+    fresh.replica_tiers = CacheTierBit(CacheTier::kL1Host);
+    KeyMetrics cold;
+    cold.object = {TenantId("tenant-a"), "cold"};
+    cold.idle_time_us = 5'000'000;  // above the gate
+    cold.block_size = 64;
+    cold.replica_tiers = CacheTierBit(CacheTier::kL1Host);
+    context.snapshot.keys = {fresh, cold};
+    context.analysis.keys = {
+        KeyPattern{.object = fresh.object, .idle_score = 1.0F},
+        KeyPattern{.object = cold.object, .idle_score = 0.1F}};
+
+    ScoreBasedEvictionOps eviction;
+    const auto plan = eviction.Evaluate(context, CacheTier::kL1Host, 64);
+
+    ASSERT_EQ(plan.candidates.size(), 1U);
+    // Only the genuinely idle key is eligible, even though "fresh" scores higher.
+    EXPECT_EQ(plan.candidates.front().object.key, "cold");
+}
+
+TEST(IoPatternFrameworkTest, AdmissionWatermarkFollowsTheConfiguredHighWatermark) {
+    // Admission must stop before eviction starts, so the watermark is derived
+    // from the store's eviction high watermark instead of a fixed 0.90: a store
+    // configured to evict at 0.75 also refuses admission at 0.75 rather than
+    // continuing to admit through the 0.75..0.90 window.
+    WorkloadPolicyEngine engine(WorkloadType::kMixed, 3, 0.75F);
+    PolicyContext context;
+    KeyMetrics key;
+    key.object = {TenantId("tenant-a"), "hot"};
+    key.access_count_window = 32;
+    context.snapshot.keys.push_back(key);
+    context.snapshot.storage = {StorageMetric{.source_id = "host",
+                                              .tier = CacheTier::kL1Host,
+                                              .memory_used_ratio = 0.80F}};
+
+    EXPECT_EQ(engine.DecideAdmission(key.object, CacheTier::kL1Host, context)
+                  .decision,
+              AdmissionDecision::kRejectWatermark);
+}
+
+TEST(IoPatternFrameworkTest, RuntimeMetricsExport) {
+    auto& metrics = MasterMetricManager::instance();
+    IoPatternRuntime::Config config;
+    config.collector.max_total_keys = 1;
+    auto runtime = std::make_shared<IoPatternRuntime>(
+        IoPatternRuntime::Handlers{}, config);
+    metrics.set_io_pattern_runtime(runtime);
+
+    const auto value = [](const std::string& text, const std::string& name) {
+        const auto offset = text.find("\n" + name + " ");
+        EXPECT_NE(offset, std::string::npos) << name;
+        return offset == std::string::npos
+                   ? -1.0
+                   : std::stod(text.substr(offset + name.size() + 2));
+    };
+    const auto initial = metrics.serialize_metrics();
+    for (const auto* name :
+         {"policy_decisions_total", "feedback_samples", "collect_latency_us",
+          "analyze_latency_us", "strategy_hit_rate", "false_positive_rate",
+          "degrade_count", "report_drop_count"}) {
+        EXPECT_DOUBLE_EQ(
+            value(initial, std::string("master_io_pattern_") + name), 0.0);
+    }
+    runtime->RecordFeedback({.hit_rate_delta = -0.25F,
+                             .eviction_churn = 0.5F,
+                             .ttft_delta = -0.125F,
+                             .prefetch_accuracy = 0.75F});
+    runtime->Plan(CacheTier::kL1Host, 0, {});
+    const auto first = metrics.serialize_metrics();
+    EXPECT_DOUBLE_EQ(value(first, "master_io_pattern_hit_rate_delta"), -0.25);
+    EXPECT_DOUBLE_EQ(value(first, "master_io_pattern_eviction_churn"), 0.5);
+    EXPECT_DOUBLE_EQ(value(first, "master_io_pattern_ttft_delta"), -0.125);
+    EXPECT_DOUBLE_EQ(value(first, "master_io_pattern_prefetch_accuracy"), 0.75);
+    EXPECT_DOUBLE_EQ(value(first, "master_io_pattern_feedback_samples"), 1.0);
+    EXPECT_DOUBLE_EQ(value(first, "master_io_pattern_policy_decisions_total"),
+                     1.0);
+    EXPECT_GT(value(first, "master_io_pattern_policy_decision_qps"), 0.0);
+    // Both the HTTP summary and periodic Master Admin Metrics log must expose
+    // the same runtime and feedback values without consuming the counters.
+    for (const auto& summary :
+         {metrics.get_summary_string(),
+          metrics.get_summary_string_and_update_snapshot()}) {
+        EXPECT_NE(summary.find("IO Pattern (runtime, lifetime):"),
+                  std::string::npos);
+        for (const auto* field :
+             {"collect_latency_max_us=", "analyze_latency_max_us=",
+              "policy_decision_qps=", "policy_decisions=1",
+              "strategy_hit_rate=0", "false_positive_rate=0", "degrade_count=0",
+              "report_drop_count=0", "hit_rate_delta=-0.25",
+              "eviction_churn=0.5", "ttft_delta=-0.125",
+              "prefetch_accuracy=0.75", "feedback_samples=1"}) {
+            EXPECT_NE(summary.find(field), std::string::npos) << field;
+        }
+    }
+    // Scrapes must not increment cumulative counters or consume feedback.
+    const auto second = metrics.serialize_metrics();
+    EXPECT_DOUBLE_EQ(value(second, "master_io_pattern_policy_decisions_total"),
+                     1.0);
+    EXPECT_DOUBLE_EQ(value(second, "master_io_pattern_feedback_samples"), 1.0);
+    EXPECT_NE(
+        second.find("# TYPE master_io_pattern_policy_decisions_total counter"),
+        std::string::npos);
+    EXPECT_NE(second.find("# TYPE master_io_pattern_hit_rate_delta gauge"),
+              std::string::npos);
+
+    runtime->RecordAccess(
+        "one", {.object = {TenantId::Default(), "one"}, .is_hit = true});
+    runtime->RecordAccess(
+        "two", {.object = {TenantId::Default(), "two"}, .is_hit = true});
+    runtime->Execute(CacheTier::kL1Host, 0, {});
+    const auto degraded = metrics.serialize_metrics();
+    EXPECT_DOUBLE_EQ(value(degraded, "master_io_pattern_report_drop_count"),
+                     1.0);
+    EXPECT_GE(value(degraded, "master_io_pattern_degrade_count"), 1.0);
+    EXPECT_NE(metrics.get_summary_string().find("report_drop_count=1"),
+              std::string::npos);
+
+    // The singleton must not retain a runtime (or its MasterService handlers).
+    std::weak_ptr<IoPatternRuntime> weak = runtime;
+    runtime.reset();
+    EXPECT_TRUE(weak.expired());
+    EXPECT_EQ(
+        metrics.get_summary_string().find("IO Pattern (runtime, lifetime):"),
+        std::string::npos);
+    EXPECT_EQ(metrics.serialize_metrics().find(
+                  "# TYPE master_io_pattern_hit_rate_delta "),
+              std::string::npos);
+
+    auto replacement =
+        std::make_shared<IoPatternRuntime>(IoPatternRuntime::Handlers{});
+    metrics.set_io_pattern_runtime(replacement);
+    metrics.clear_io_pattern_runtime(nullptr);
+    EXPECT_DOUBLE_EQ(value(metrics.serialize_metrics(),
+                           "master_io_pattern_policy_decisions_total"),
+                     0.0);
+    metrics.clear_io_pattern_runtime(replacement.get());
+    EXPECT_EQ(metrics.get_summary_string_and_update_snapshot().find(
+                  "IO Pattern (feedback, sample window):"),
+              std::string::npos);
+    EXPECT_EQ(metrics.serialize_metrics().find(
+                  "# TYPE master_io_pattern_hit_rate_delta "),
+              std::string::npos);
+}
+
+}  // namespace
+}  // namespace mooncake::io_pattern
diff --git a/mooncake-store/tests/master_metrics_test.cpp b/mooncake-store/tests/master_metrics_test.cpp
index 6f6889d59e..36d47760c1 100644
--- a/mooncake-store/tests/master_metrics_test.cpp
+++ b/mooncake-store/tests/master_metrics_test.cpp
@@ -18,6 +18,7 @@
 #include "types.h"
 #include "master_config.h"
 #include "master_metric_manager.h"
+#include "io_pattern/runtime.h"
 
 namespace mooncake::test {
 
@@ -920,6 +921,9 @@ TEST_F(MasterMetricsTest, SsdOffloadCacheHitAndTotalConsistent) {
     const int64_t base_file_cache_nums = metrics.get_file_cache_nums();
 
     // Step 1: Mount segment and create a completed MEMORY replica.
+    // MountSegment registers the owner in client_host_id_ only with a host ID.
+    // LOCAL_DISK reads filter out replicas whose owner is not registered.
+    segment.host_id = "ssd-metrics-host";
     auto mount_result = service_.MountSegment(segment, client_id);
     ASSERT_TRUE(mount_result.has_value());
     auto put_start_result =
@@ -1021,6 +1025,44 @@ TEST_F(MasterMetricsTest, SsdOffloadCacheHitAndTotalConsistent) {
     service_.Remove(ssd_only_key, "default");
 }
 
+TEST_F(MasterMetricsTest, AdminMetricsExposeIoPatternFeedbackFromAccesses) {
+    const int http_port = getFreeTcpPort();
+    WrappedMasterServiceConfig config;
+    config.default_kv_lease_ttl = 100;
+    config.enable_metric_reporting = false;
+    WrappedMasterService service(config);
+    MasterAdminServer admin_server(static_cast<uint16_t>(http_port),
+                                   /*enable_metric_reporting=*/true);
+    ASSERT_TRUE(admin_server.Start());
+
+    // Exercise the production CFM ingress and MasterService registration.
+    io_pattern::MetricBatch batch;
+    for (int i = 0; i < 64; ++i) {
+        batch.accesses.push_back(
+            {.object = {TenantId::Default(), "missing"}, .is_hit = false});
+    }
+    io_pattern::CfmBinaryCodec codec;
+    ASSERT_TRUE(service.CfmRpcEndpoint().Send("report_metric_batch",
+                                              codec.EncodeMetricBatch(batch)));
+    const auto response = FetchUrl(http_port, "/metrics");
+    ASSERT_EQ(response.http_status, 200);
+    EXPECT_NE(
+        response.body.find("\nmaster_io_pattern_feedback_samples 1.000000\n"),
+        std::string::npos);
+    EXPECT_NE(
+        response.body.find("# TYPE master_io_pattern_collect_latency_us gauge"),
+        std::string::npos);
+    EXPECT_NE(response.body.find(
+                  "# TYPE master_io_pattern_policy_decisions_total counter"),
+              std::string::npos);
+    const auto summary = FetchUrl(http_port, "/metrics/summary");
+    ASSERT_EQ(summary.http_status, 200);
+    EXPECT_NE(summary.body.find("IO Pattern (runtime, lifetime):"),
+              std::string::npos);
+    EXPECT_NE(summary.body.find("feedback_samples=1"), std::string::npos);
+    admin_server.Stop();
+}
+
 }  // namespace mooncake::test
 
 int main(int argc, char** argv) {
diff --git a/mooncake-store/tests/master_service_test.cpp b/mooncake-store/tests/master_service_test.cpp
index bc3614949a..cd1e193e67 100644
--- a/mooncake-store/tests/master_service_test.cpp
+++ b/mooncake-store/tests/master_service_test.cpp
@@ -199,10 +199,11 @@ class MasterServiceTest : public ::testing::Test {
     std::string FindGroupIdOnDifferentShard(const std::string& key) const {
         static constexpr size_t kMetadataShardCountForTest = 1024;
         const size_t key_shard =
-            std::hash<std::string>{}(key) % kMetadataShardCountForTest;
+            cvm::KeySlot(TenantId::Default(), key) %
+            kMetadataShardCountForTest;
         for (int i = 0; i < 10000; ++i) {
             std::string group_id = key + "_group_" + std::to_string(i);
-            if (std::hash<std::string>{}(group_id) %
+            if (cvm::KeySlot(TenantId::Default(), group_id) %
                     kMetadataShardCountForTest !=
                 key_shard) {
                 return group_id;
@@ -1043,8 +1044,8 @@ TEST_F(MasterServiceTest, GroupRoutingIsTenantScopedForSameUserKey) {
     std::string group_b;
     for (int i = 0; i < 10000; ++i) {
         group_b = key + "_tenant_b_group_" + std::to_string(i);
-        if (std::hash<std::string>{}(group_b) % 1024 !=
-            std::hash<std::string>{}(group_a) % 1024) {
+        if (cvm::KeySlot(TenantId::Default(), group_b) % 1024 !=
+            cvm::KeySlot(TenantId::Default(), group_a) % 1024) {
             break;
         }
     }
@@ -1325,8 +1326,8 @@ TEST_F(MasterServiceTest,
     std::string group_b;
     for (int i = 0; i < 10000; ++i) {
         group_b = key + "_other_group_" + std::to_string(i);
-        if (std::hash<std::string>{}(group_b) % 1024 !=
-            std::hash<std::string>{}(group_a) % 1024) {
+        if (cvm::KeySlot(TenantId::Default(), group_b) % 1024 !=
+            cvm::KeySlot(TenantId::Default(), group_a) % 1024) {
             break;
         }
     }
diff --git a/mooncake-store/tests/offload_on_evict_test.cpp b/mooncake-store/tests/offload_on_evict_test.cpp
index 08810e6fdf..85d49e835a 100644
--- a/mooncake-store/tests/offload_on_evict_test.cpp
+++ b/mooncake-store/tests/offload_on_evict_test.cpp
@@ -11,6 +11,10 @@
 #include <vector>
 
 #include "types.h"
+#include "io_pattern/cfm_protocol.h"
+#include "io_pattern/cfm_service.h"
+#include "io_pattern/runtime.h"
+#include "io_pattern/types.h"
 
 namespace mooncake::test {
 
@@ -23,6 +27,52 @@ class OffloadOnEvictTest : public ::testing::Test {
 
     void TearDown() override { google::ShutdownGoogleLogging(); }
 
+    // Friend access to the private legacy-eviction fallback, which the runtime's
+    // eviction handler runs when an IO Pattern plan cannot free its byte target.
+    // OffloadOnEvictTest is friended; TEST_F-generated subclasses are not, hence
+    // this static funnel.
+    static bool RunLegacyEvictionFallbackForTesting(MasterService* service,
+                                                    uint64_t shortfall_bytes) {
+        return service->RunLegacyEvictionFallback(shortfall_bytes);
+    }
+
+    // Friend access to the embedded io_pattern runtime, so a test can hand the
+    // eviction handler a plan directly and observe how each candidate action is
+    // dispatched. OffloadOnEvictTest is friended; TEST_F-generated subclasses are
+    // not, hence this static funnel.
+    static ErrorCode ExecuteEvictionPlan(MasterService* service,
+                                         const io_pattern::EvictionPlan& plan) {
+        return service->io_pattern_runtime_->ExecuteCommand(plan);
+    }
+
+    // Friend access to the embedded CFM endpoint, so a test can drive a real
+    // report-driven cycle through the MasterService wiring (flags -> config ->
+    // runtime driver -> policy -> handler) instead of calling the runtime
+    // directly. Returns false when the report was rejected.
+    static bool SendIoPatternReport(MasterService* service,
+                                    const io_pattern::MetricBatch& batch) {
+        io_pattern::CfmBinaryCodec codec;
+        return service->io_pattern_cfm_service_->Send(
+            "report_metric_batch", codec.EncodeMetricBatch(batch));
+    }
+
+    // A demotion must leave a readable MEMORY replica behind; an eviction must
+    // not. Reads the same client-facing view a Get would.
+    bool HasCompleteMemoryReplica(MasterService& service,
+                                  const std::string& key) const {
+        auto replica_list = service.GetReplicaList(key, TenantId::Default());
+        if (!replica_list.has_value()) {
+            return false;
+        }
+        for (const auto& descriptor : replica_list.value().replicas) {
+            if (descriptor.is_memory_replica() &&
+                descriptor.status == ReplicaStatus::COMPLETE) {
+                return true;
+            }
+        }
+        return false;
+    }
+
     static constexpr size_t kDefaultSegmentBase = 0x300000000;
 
     Segment MakeSegment(std::string name, size_t base, size_t size) const {
@@ -424,6 +474,196 @@ TEST_F(OffloadOnEvictTest, BatchRemoveDropsOffloadingObjectsMirror) {
            "offloading_objects.";
 }
 
+// The runtime's eviction handler falls back to the legacy lease-ordered
+// eviction when an IO Pattern plan cannot free its byte target. That path is
+// what keeps a watermark request making progress when the plan's candidates are
+// stale, leased, pinned, or empty -- the report-driven worker relies on it
+// because it has no eviction thread of its own.
+TEST_F(OffloadOnEvictTest, LegacyEvictionFallbackRunsForUnderDeliveringPlan) {
+    MasterServiceConfig config;
+    config.default_kv_lease_ttl = 100;
+    auto service = std::make_unique<MasterService>(config);
+    auto ctx = PrepareSegment(*service, "fallback-segment", kDefaultSegmentBase,
+                              8 * 1024 * 1024);
+    for (int i = 0; i < 8; ++i) {
+        PutObject(*service, ctx.client_id, "fb-" + std::to_string(i), 4096);
+    }
+
+    // No shortfall is a no-op and reports success.
+    EXPECT_TRUE(RunLegacyEvictionFallbackForTesting(service.get(), 0));
+
+    // A real shortfall runs the legacy path: the segment is mounted, so a
+    // capacity is known and the guard mutex is free.
+    EXPECT_TRUE(RunLegacyEvictionFallbackForTesting(service.get(), 1));
+}
+
+// =============================================================================
+// Policy-driven tier down: the io_pattern eviction handler must copy the key
+// down to LOCAL_DISK while keeping its MEMORY replica. A demotion frees no
+// bytes, so it may not be counted as freed memory and may not turn the plan into
+// a reclaim shortfall -- otherwise the legacy fallback evicts exactly the keys
+// the driver chose to keep.
+// =============================================================================
+
+TEST_F(OffloadOnEvictTest, TierDownPlanQueuesOffloadAndKeepsMemoryReplica) {
+    MasterServiceConfig config;
+    config.enable_offload = true;
+    config.offload_on_evict = true;
+    // No lease protection: if the handler wrongly treated the demotion budget as
+    // a reclaim shortfall, the legacy fallback would be free to reclaim one of
+    // these keys immediately, so a surviving MEMORY replica is real evidence the
+    // fallback never ran.
+    config.default_kv_lease_ttl = 0;
+    auto service = std::make_unique<MasterService>(config);
+
+    constexpr size_t seg_size = 1024 * 1024 * 16;
+    auto ctx = PrepareSegment(*service, "tier_down_segment", kDefaultSegmentBase,
+                              seg_size);
+    auto mount_ld = service->MountLocalDiskSegment(ctx.client_id, true);
+    ASSERT_TRUE(mount_ld.has_value());
+
+    PutObject(*service, ctx.client_id, "td_demote");
+    PutObject(*service, ctx.client_id, "td_keep");
+
+    const io_pattern::EvictionPlan plan{
+        .source_tier = io_pattern::CacheTier::kL1Host,
+        .target_bytes = 1024,
+        .candidates = {io_pattern::EvictionCandidate{
+            .object = {TenantId::Default(), "td_demote"},
+            .bytes = 1024,
+            .score = 1.0F,
+            .target_tier = io_pattern::CacheTier::kLocalDisk,
+            .action = io_pattern::EvictionAction::kTierDown}},
+        .tier_down_target_bytes = 1024};
+
+    EXPECT_EQ(ExecuteEvictionPlan(service.get(), plan), ErrorCode::OK);
+
+    // The chosen key was queued for a LOCAL_DISK copy ...
+    auto queued = DrainOffloadQueue(*service, ctx.client_id);
+    ASSERT_EQ(queued.size(), 1u);
+    EXPECT_TRUE(queued.count("td_demote") > 0);
+
+    // ... and both keys still serve from MEMORY: demotion is a copy, not a
+    // reclaim, so nothing was freed and the fallback was never asked to free it.
+    EXPECT_TRUE(HasCompleteMemoryReplica(*service, "td_demote"));
+    EXPECT_TRUE(HasCompleteMemoryReplica(*service, "td_keep"));
+
+    // Tier down is counted on its own counters, independently of freed bytes.
+    EXPECT_EQ(service->tier_down_attempt_count(), 1u);
+    EXPECT_EQ(service->tier_down_success_count(), 1u);
+    EXPECT_EQ(service->tier_down_failure_count(), 0u);
+
+    service->RemoveAll();
+}
+
+// The contrast case: the same plan shape labelled kEvict must go to the quota
+// eviction path and never to the demotion path.
+//
+// The configuration matters here. With offload_on_evict enabled, ordinary
+// eviction *also* defers its victim to the offload queue ("No memory freed ...
+// deferred for disk offload"), so an empty queue would prove nothing. This test
+// therefore runs the legacy write-through mode (enable_offload=true,
+// offload_on_evict=false), where only a tier-down dispatch can queue an offload:
+// PutEnd pushes one entry, which is drained before the plan runs, and eviction
+// reclaims without offloading.
+TEST_F(OffloadOnEvictTest, EvictActionPlanNeverQueuesOffload) {
+    MasterServiceConfig config;
+    config.enable_offload = true;
+    config.offload_on_evict = false;
+    config.default_kv_lease_ttl = 0;
+    auto service = std::make_unique<MasterService>(config);
+
+    constexpr size_t seg_size = 1024 * 1024 * 16;
+    auto ctx = PrepareSegment(*service, "evict_action_segment",
+                              kDefaultSegmentBase, seg_size);
+    auto mount_ld = service->MountLocalDiskSegment(ctx.client_id, true);
+    ASSERT_TRUE(mount_ld.has_value());
+
+    PutObject(*service, ctx.client_id, "ev_reclaim");
+
+    // Legacy write-through: one entry from PutEnd, drained so that anything left
+    // in the queue afterwards can only have come from the plan below.
+    auto pre_plan = DrainOffloadQueue(*service, ctx.client_id);
+    ASSERT_EQ(pre_plan.size(), 1u);
+
+    const io_pattern::EvictionPlan plan{
+        .source_tier = io_pattern::CacheTier::kL1Host,
+        .target_bytes = 1024,
+        .candidates = {io_pattern::EvictionCandidate{
+            .object = {TenantId::Default(), "ev_reclaim"},
+            .bytes = 1024,
+            .score = 1.0F,
+            .target_tier = io_pattern::CacheTier::kL3NofSsd,
+            .action = io_pattern::EvictionAction::kEvict}},
+        .tier_down_target_bytes = 0};
+
+    ExecuteEvictionPlan(service.get(), plan);
+
+    auto queued = DrainOffloadQueue(*service, ctx.client_id);
+    EXPECT_TRUE(queued.empty())
+        << "a kEvict candidate must not be queued for a LOCAL_DISK copy";
+    EXPECT_EQ(service->tier_down_attempt_count(), 0u);
+    EXPECT_EQ(service->tier_down_success_count(), 0u);
+    EXPECT_EQ(service->tier_down_failure_count(), 0u);
+
+    service->RemoveAll();
+}
+
+// End to end through the MasterService wiring: the config flag must reach the
+// report-driven driver, the driver must label the plan, and the handler must
+// copy the key down while keeping it in memory.
+TEST_F(OffloadOnEvictTest, TierDownDriverDemotesReportedKeyWithoutReclaiming) {
+    MasterServiceConfig config;
+    config.enable_offload = true;
+    config.offload_on_evict = true;
+    config.default_kv_lease_ttl = 0;
+    // The wiring under test: the budget alone enables the driver, there is no
+    // enable flag.
+    config.io_pattern_tier_down_bytes_per_cycle = 4096;
+    auto service = std::make_unique<MasterService>(config);
+
+    constexpr size_t seg_size = 1024 * 1024 * 16;
+    auto ctx = PrepareSegment(*service, "tier_down_report_segment",
+                              kDefaultSegmentBase, seg_size);
+    auto mount_ld = service->MountLocalDiskSegment(ctx.client_id, true);
+    ASSERT_TRUE(mount_ld.has_value());
+
+    PutObject(*service, ctx.client_id, "td_report", 4096);
+
+    // No storage metric: the merged report carries no pressure, so only the
+    // tier-down driver can act on this cycle. The access record is what puts the
+    // key into the analyzed snapshot with an L1 replica bit.
+    io_pattern::MetricBatch batch;
+    batch.accesses.push_back(io_pattern::AccessRecord{
+        .object = {TenantId::Default(), "td_report"},
+        .observed_at_ns = 1,
+        .block_size = 4096,
+        .tier = io_pattern::CacheTier::kL1Host,
+        .operation = io_pattern::IoOperation::kGet,
+        .is_hit = true});
+    ASSERT_TRUE(SendIoPatternReport(service.get(), batch));
+
+    // The cycle runs on the runtime's background worker, so wait for the
+    // demotion to reach the offload queue.
+    std::unordered_map<std::string, int64_t> queued;
+    WaitUntil([&] {
+        queued = DrainOffloadQueue(*service, ctx.client_id);
+        return !queued.empty();
+    });
+    ASSERT_EQ(queued.size(), 1u) << "tier-down driver queued "
+                                 << queued.size() << " object(s)";
+    EXPECT_TRUE(queued.count("td_report") > 0);
+
+    // The demotion copied the key down and kept serving it from MEMORY: nothing
+    // was reclaimed, so the reclaim path was never involved.
+    EXPECT_TRUE(HasCompleteMemoryReplica(*service, "td_report"));
+    EXPECT_GE(service->tier_down_attempt_count(), 1u);
+    EXPECT_GE(service->tier_down_success_count(), 1u);
+    EXPECT_EQ(service->tier_down_failure_count(), 0u);
+
+    service->RemoveAll();
+}
+
 }  // namespace mooncake::test
 
 int main(int argc, char** argv) {
diff --git a/mooncake-store/tests/partition_router_test.cpp b/mooncake-store/tests/partition_router_test.cpp
new file mode 100644
index 0000000000..54ffb1f50d
--- /dev/null
+++ b/mooncake-store/tests/partition_router_test.cpp
@@ -0,0 +1,93 @@
+#include "partition/partition_router.h"
+
+#include <gtest/gtest.h>
+
+#include <string>
+#include <vector>
+
+#include "cvm/slot_hash.h"
+#include "tenant_id.h"
+
+namespace mooncake::test {
+namespace {
+
+cvm::SlotOwner MakeOwner(uint16_t slot, const std::string& primary) {
+    cvm::SlotOwner owner;
+    owner.slot = slot;
+    owner.primary_master_id = primary;
+    owner.state = static_cast<int32_t>(cvm::SlotState::kStable);
+    return owner;
+}
+
+TEST(PartitionRouterTest, LoadAndResolve) {
+    partition::PartitionRouter router;
+    router.LoadSlotOwners({MakeOwner(10, "m-a"), MakeOwner(20, "m-b")});
+
+    EXPECT_EQ(router.Size(), 2u);
+    ASSERT_TRUE(router.ResolveSubmaster(10).has_value());
+    EXPECT_EQ(*router.ResolveSubmaster(10), "m-a");
+    ASSERT_TRUE(router.ResolveSubmaster(20).has_value());
+    EXPECT_EQ(*router.ResolveSubmaster(20), "m-b");
+}
+
+TEST(PartitionRouterTest, MissingSlotReturnsNullopt) {
+    partition::PartitionRouter router;
+    router.LoadSlotOwners({MakeOwner(10, "m-a")});
+    EXPECT_FALSE(router.ResolveSubmaster(11).has_value());
+}
+
+TEST(PartitionRouterTest, SkipsEmptyPrimary) {
+    partition::PartitionRouter router;
+    router.LoadSlotOwners({MakeOwner(10, ""), MakeOwner(11, "m-b")});
+
+    EXPECT_EQ(router.Size(), 1u);
+    EXPECT_FALSE(router.ResolveSubmaster(10).has_value());
+    EXPECT_TRUE(router.ResolveSubmaster(11).has_value());
+}
+
+TEST(PartitionRouterTest, SkipsMigratingSlotUntilOwnerIsStable) {
+    auto migrating = MakeOwner(10, "m-a");
+    migrating.state = static_cast<int32_t>(cvm::SlotState::kMigrating);
+    migrating.migrating_to_master_id = "m-b";
+
+    partition::PartitionRouter router;
+    router.LoadSlotOwners({migrating, MakeOwner(11, "m-b")});
+
+    EXPECT_FALSE(router.ResolveSubmaster(10).has_value());
+    EXPECT_EQ(router.ResolveSubmaster(11), "m-b");
+}
+
+TEST(PartitionRouterTest, OverwritesOnReload) {
+    partition::PartitionRouter router;
+    router.LoadSlotOwners({MakeOwner(10, "m-a")});
+    router.LoadSlotOwners({MakeOwner(10, "m-b"), MakeOwner(20, "m-c")});
+
+    EXPECT_EQ(router.Size(), 2u);
+    ASSERT_TRUE(router.ResolveSubmaster(10).has_value());
+    EXPECT_EQ(*router.ResolveSubmaster(10), "m-b");
+    EXPECT_TRUE(router.ResolveSubmaster(20).has_value());
+}
+
+TEST(PartitionRouterTest, RouteUsesKeySlot) {
+    partition::PartitionRouter router;
+    const std::string key = "route-me";
+    const TenantId tenant("tenant-r");
+    const uint16_t slot = cvm::KeySlot(tenant, key);
+    router.LoadSlotOwners({MakeOwner(slot, "m-target")});
+
+    ASSERT_TRUE(router.Route(tenant, key).has_value());
+    EXPECT_EQ(*router.Route(tenant, key), "m-target");
+}
+
+TEST(PartitionRouterTest, ClearAndSize) {
+    partition::PartitionRouter router;
+    router.LoadSlotOwners({MakeOwner(10, "m-a"), MakeOwner(20, "m-b")});
+    EXPECT_EQ(router.Size(), 2u);
+
+    router.Clear();
+    EXPECT_EQ(router.Size(), 0u);
+    EXPECT_FALSE(router.ResolveSubmaster(10).has_value());
+}
+
+}  // namespace
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/promotion_on_hit_test.cpp b/mooncake-store/tests/promotion_on_hit_test.cpp
index eb496cfde1..751c8857db 100644
--- a/mooncake-store/tests/promotion_on_hit_test.cpp
+++ b/mooncake-store/tests/promotion_on_hit_test.cpp
@@ -752,11 +752,11 @@ TEST_F(PromotionOnHitTest, QueueLimitRejectsBeyondCap) {
 
     // Find two keys that hash to the same shard. MasterService::
     // getShardIndex is private but the formula is deterministic
-    // (std::hash<std::string>{}(key) % kNumShards), so we can mirror
-    // it here. kNumShards=1024 (master_service.h:889).
+    // (cvm::KeySlot(default_tenant, key) % kNumShards), so we can mirror
+    // it here. kNumShards=1024.
     constexpr size_t kNumShardsLocal = 1024;
     auto shard_of = [](const std::string& k) {
-        return std::hash<std::string>{}(k) % kNumShardsLocal;
+        return cvm::KeySlot(TenantId::Default(), k) % kNumShardsLocal;
     };
     const std::string k1 = "qlim_first";
     std::string k2;
@@ -986,7 +986,7 @@ TEST_F(PromotionOnHitTest, QueueLimitRejectsCrossShard) {
     // independently). With the global counter, only the first goes in.
     constexpr size_t kNumShardsLocal = 1024;
     auto shard_of = [](const std::string& k) {
-        return std::hash<std::string>{}(k) % kNumShardsLocal;
+        return cvm::KeySlot(TenantId::Default(), k) % kNumShardsLocal;
     };
     const std::string k1 = "xshard_first";
     std::string k2;
diff --git a/mooncake-store/tests/slot_hash_test.cpp b/mooncake-store/tests/slot_hash_test.cpp
new file mode 100644
index 0000000000..183145200d
--- /dev/null
+++ b/mooncake-store/tests/slot_hash_test.cpp
@@ -0,0 +1,145 @@
+#include "cvm/slot_hash.h"
+
+#include <gtest/gtest.h>
+
+#include <set>
+#include <string>
+#include <vector>
+
+#include "crc32c.h"
+#include "partition/kv_hash_map.h"
+#include "tenant_id.h"
+
+namespace mooncake::test {
+namespace {
+
+TEST(SlotHashTest, SlotOfUsesLow14Bits) {
+    EXPECT_EQ(cvm::SlotOf(0u), 0u);
+    EXPECT_EQ(cvm::SlotOf(1u), 1u);
+    EXPECT_EQ(cvm::SlotOf(cvm::kSlotCount - 1), cvm::kSlotCount - 1);
+    // 第 15 位及以上被丢弃：16384 (2^14) 映射回 0。
+    EXPECT_EQ(cvm::SlotOf(cvm::kSlotCount), 0u);
+    EXPECT_EQ(cvm::SlotOf(0xFFFFFFFFu), cvm::kSlotMask);
+}
+
+TEST(SlotHashTest, KeySlotInRange) {
+    const std::vector<std::string> keys = {"", "a", "hello", "key-123",
+                                           "a-longer-key-for-coverage"};
+    for (const auto& key : keys) {
+        EXPECT_LT(cvm::KeySlot(TenantId::Default(), key), cvm::kSlotCount);
+        EXPECT_LT(cvm::KeySlot(TenantId("tenant-a"), key), cvm::kSlotCount);
+    }
+}
+
+TEST(SlotHashTest, KeySlotDeterministic) {
+    const std::string key = "deterministic-key";
+    const TenantId tenant("tenant-x");
+    const uint16_t first = cvm::KeySlot(tenant, key);
+    for (int i = 0; i < 100; ++i) {
+        EXPECT_EQ(first, cvm::KeySlot(tenant, key));
+    }
+}
+
+namespace {
+uint16_t ManualDefaultKeySlot(const std::string& key) {
+    Crc32c crc;
+    crc.Extend(key.data(), key.size());
+    return cvm::SlotOf(crc.Final());
+}
+
+uint16_t ManualScopedKeySlot(const std::string& tenant,
+                             const std::string& key) {
+    Crc32c crc;
+    crc.Extend(tenant.data(), tenant.size());
+    constexpr char kSeparator = '\0';
+    crc.Extend(&kSeparator, 1);
+    crc.Extend(key.data(), key.size());
+    return cvm::SlotOf(crc.Final());
+}
+}  // namespace
+
+TEST(SlotHashTest, KeySlotMatchesManualCrc) {
+    const std::string key = "scope-me";
+    // 默认 tenant：slot = hash(user_key)。
+    EXPECT_EQ(cvm::KeySlot(TenantId::Default(), key),
+              ManualDefaultKeySlot(key));
+    // 非默认 tenant：slot = hash(tenant + '\0' + user_key)。
+    EXPECT_EQ(cvm::KeySlot(TenantId("tenant-a"), key),
+              ManualScopedKeySlot("tenant-a", key));
+}
+
+TEST(SlotHashTest, VNodePositionInRangeAndDeterministic) {
+    const std::string master = "master-1:10001";
+    for (uint16_t vnode = 0; vnode < cvm::kVnodeCount; ++vnode) {
+        const uint16_t pos = cvm::VNodePosition(master, vnode);
+        EXPECT_LT(pos, cvm::kSlotCount);
+        EXPECT_EQ(pos, cvm::VNodePosition(master, vnode));
+    }
+}
+
+TEST(SlotHashTest, KvHashMapMatchesKeySlot) {
+    // client 侧路由（KvHashMap）与 submaster 侧校验（KeySlot）必须用同一份
+    // 哈希，否则 key 会路由到错误的 submaster。
+    const std::string key = "consistency-key";
+    const TenantId tenant("tenant-c");
+    EXPECT_EQ(partition::KvHashMap::Compute(tenant, key),
+              cvm::KeySlot(tenant, key));
+}
+
+TEST(SlotHashTest, ResolveOwnedSlotsOnRingSingleMaster) {
+    // n=1 时退化：本机拥有全部 slot。
+    const std::vector<std::string> ids = {"m-a"};
+    const auto slots = cvm::ResolveOwnedSlotsOnRing(ids, "m-a");
+    EXPECT_EQ(slots.size(), static_cast<size_t>(cvm::kSlotCount));
+}
+
+TEST(SlotHashTest, ResolveOwnedSlotsOnRingCoversAllSlots) {
+    const std::vector<std::string> ids = {"m-a", "m-b", "m-c"};
+    std::vector<bool> covered(cvm::kSlotCount, false);
+    size_t total = 0;
+    for (const auto& id : ids) {
+        const auto slots = cvm::ResolveOwnedSlotsOnRing(ids, id);
+        for (uint16_t s : slots) {
+            EXPECT_FALSE(covered[s]) << "slot " << s << " owned by >1 master";
+            covered[s] = true;
+            ++total;
+        }
+    }
+    // 每个 slot 恰好归属一个 primary（不重叠 + 全覆盖）。
+    EXPECT_EQ(total, static_cast<size_t>(cvm::kSlotCount));
+    for (size_t s = 0; s < cvm::kSlotCount; ++s) {
+        EXPECT_TRUE(covered[s]) << "slot " << s << " has no owner";
+    }
+}
+
+TEST(SlotHashTest, ResolveOwnedSlotsOnRingStableOnRemoval) {
+    // 一致性哈希环核心性质：移除一个 primary 后，其余 primary 原有 slot 不
+    // 丢（只增不减），仅被移除 primary 覆盖的 slot 发生重分配——即「非全员
+    // 平移」。
+    const std::vector<std::string> ids3 = {"m-a", "m-b", "m-c"};
+    const auto a = cvm::ResolveOwnedSlotsOnRing(ids3, "m-a");
+    const auto b = cvm::ResolveOwnedSlotsOnRing(ids3, "m-b");
+
+    const std::vector<std::string> ids2 = {"m-a", "m-b"};
+    const auto a2 = cvm::ResolveOwnedSlotsOnRing(ids2, "m-a");
+    const auto b2 = cvm::ResolveOwnedSlotsOnRing(ids2, "m-b");
+
+    const std::set<uint16_t> a_set(a.begin(), a.end());
+    const std::set<uint16_t> a2_set(a2.begin(), a2.end());
+    const std::set<uint16_t> b_set(b.begin(), b.end());
+    const std::set<uint16_t> b2_set(b2.begin(), b2.end());
+
+    for (uint16_t s : a_set) {
+        EXPECT_TRUE(a2_set.count(s)) << "a lost slot " << s << " on removal";
+    }
+    for (uint16_t s : b_set) {
+        EXPECT_TRUE(b2_set.count(s)) << "b lost slot " << s << " on removal";
+    }
+    // 移除后 a/b 覆盖全量 slot，且总量较移除前增加（接管了被移除者的 slot）。
+    EXPECT_EQ(a2_set.size() + b2_set.size(),
+              static_cast<size_t>(cvm::kSlotCount));
+    EXPECT_GT(a2_set.size() + b2_set.size(), a_set.size() + b_set.size());
+}
+
+}  // namespace
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/vchunk_allocation_strategy_test.cpp b/mooncake-store/tests/vchunk_allocation_strategy_test.cpp
new file mode 100644
index 0000000000..e5fb1fd82e
--- /dev/null
+++ b/mooncake-store/tests/vchunk_allocation_strategy_test.cpp
@@ -0,0 +1,118 @@
+#include "vchunk_allocation_strategy.h"
+
+#include <gtest/gtest.h>
+
+#include <memory>
+#include <set>
+#include <string>
+#include <unordered_set>
+#include <vector>
+
+#include "allocation_strategy.h"
+#include "vchunk_test_allocator.h"
+
+namespace mooncake {
+namespace {
+
+using test::VChunkTestAllocator;
+
+TEST(VChunkAllocationStrategyTest, AllocatesTransposeRowsAndRollsBack) {
+    AllocatorManager manager;
+    std::vector<std::shared_ptr<VChunkTestAllocator>> allocators;
+    for (size_t i = 0; i < 3; ++i) {
+        auto allocator = std::make_shared<VChunkTestAllocator>(
+            "segment-" + std::to_string(i), 0x100000000ULL + i * 0x100000,
+            64U * 1024U);
+        manager.addAllocator(allocator->getSegmentName(), allocator);
+        allocators.push_back(std::move(allocator));
+    }
+
+    {
+        auto result = AllocateVChunk(manager, 9U * 4096U,
+                                     VCSliceSizeLevel::k4K);
+        ASSERT_TRUE(result.has_value());
+        EXPECT_EQ(result->row_size, 3U);
+        ASSERT_EQ(result->allocations.size(), 9U);
+        for (size_t row = 0; row < 3; ++row) {
+            std::unordered_set<std::string> segments;
+            for (size_t column = 0; column < 3; ++column) {
+                const auto& allocation =
+                    result->allocations[row * 3 + column];
+                EXPECT_TRUE(segments.insert(allocation.segment_name).second);
+                EXPECT_EQ(allocation.slice_index, row * 3 + column);
+                EXPECT_EQ(allocation.logical_length, 4096U);
+                EXPECT_EQ(allocation.allocated_length, 4096U);
+                EXPECT_NE(allocation.buffer, nullptr);
+            }
+        }
+        for (const auto& allocator : allocators) {
+            EXPECT_EQ(allocator->size(), 3U * 4096U);
+        }
+    }
+    for (const auto& allocator : allocators) {
+        EXPECT_EQ(allocator->size(), 0U);
+    }
+}
+
+TEST(VChunkAllocationStrategyTest, TracksShortFinalLogicalSlice) {
+    AllocatorManager manager;
+    auto allocator = std::make_shared<VChunkTestAllocator>(
+        "segment-a", 0x200000000ULL, 64U * 1024U);
+    manager.addAllocator("segment-a", allocator);
+
+    auto result =
+        AllocateVChunk(manager, 10U * 1024U, VCSliceSizeLevel::k4K);
+    ASSERT_TRUE(result.has_value());
+    ASSERT_EQ(result->allocations.size(), 3U);
+    EXPECT_EQ(result->allocations.back().logical_length, 2048U);
+    EXPECT_EQ(result->allocations.back().allocated_length, 4096U);
+}
+
+TEST(VChunkAllocationStrategyTest, HonorsExcludedSegments) {
+    AllocatorManager manager;
+    auto first = std::make_shared<VChunkTestAllocator>(
+        "segment-a", 0x300000000ULL, 64U * 1024U);
+    auto second = std::make_shared<VChunkTestAllocator>(
+        "segment-b", 0x400000000ULL, 64U * 1024U);
+    manager.addAllocator("segment-a", first);
+    manager.addAllocator("segment-b", second);
+
+    auto result = AllocateVChunk(manager, 8192, VCSliceSizeLevel::k4K,
+                                 std::set<std::string>{"segment-a"});
+    ASSERT_TRUE(result.has_value());
+    for (const auto& allocation : result->allocations) {
+        EXPECT_EQ(allocation.segment_name, "segment-b");
+    }
+    EXPECT_EQ(first->size(), 0U);
+}
+
+TEST(VChunkAllocationStrategyTest, PartialFailureRollsBackAllBuffers) {
+    AllocatorManager manager;
+    auto first = std::make_shared<VChunkTestAllocator>(
+        "segment-a", 0x500000000ULL, 4096);
+    auto second = std::make_shared<VChunkTestAllocator>(
+        "segment-b", 0x600000000ULL, 4096);
+    manager.addAllocator("segment-a", first);
+    manager.addAllocator("segment-b", second);
+
+    auto result =
+        AllocateVChunk(manager, 3U * 4096U, VCSliceSizeLevel::k4K);
+    ASSERT_FALSE(result.has_value());
+    EXPECT_EQ(result.error(), ErrorCode::NO_AVAILABLE_HANDLE);
+    EXPECT_EQ(first->size(), 0U);
+    EXPECT_EQ(second->size(), 0U);
+}
+
+TEST(VChunkAllocationStrategyTest, RejectsInvalidAndEmptyInputs) {
+    AllocatorManager manager;
+    auto empty = AllocateVChunk(manager, 4096, VCSliceSizeLevel::k4K);
+    EXPECT_FALSE(empty.has_value());
+    EXPECT_EQ(empty.error(), ErrorCode::NO_AVAILABLE_HANDLE);
+
+    auto zero = AllocateVChunk(manager, 0, VCSliceSizeLevel::k4K);
+    EXPECT_FALSE(zero.has_value());
+    EXPECT_EQ(zero.error(), ErrorCode::INVALID_PARAMS);
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/vchunk_client_test.cpp b/mooncake-store/tests/vchunk_client_test.cpp
new file mode 100644
index 0000000000..1b52e200c4
--- /dev/null
+++ b/mooncake-store/tests/vchunk_client_test.cpp
@@ -0,0 +1,399 @@
+#include "vchunk_client.h"
+
+#include <gtest/gtest.h>
+
+#include <algorithm>
+#include <array>
+#include <condition_variable>
+#include <cstdint>
+#include <cstring>
+#include <mutex>
+#include <random>
+#include <string>
+#include <thread>
+#include <unordered_map>
+#include <vector>
+
+#include "master_config.h"
+#include "master_service.h"
+
+namespace mooncake {
+namespace {
+
+Segment MakeSegment(const std::string& name, uintptr_t base) {
+    Segment segment;
+    segment.name = name;
+    segment.base = base;
+    segment.size = 32U * 1024U * 1024U;
+    segment.protocol = "tcp";
+    segment.te_endpoint = name;
+    return segment;
+}
+
+class MemoryDataPlane final : public VChunkDataPlane {
+   public:
+    ErrorCode Write(const VChunkMetadataRecord& record, const void* source,
+                    size_t length,
+                    std::chrono::steady_clock::time_point deadline) override {
+        ++write_attempts;
+        if (write_failures_remaining > 0) {
+            --write_failures_remaining;
+            return ErrorCode::TRANSFER_FAIL;
+        }
+        if (fail_write || std::chrono::steady_clock::now() >= deadline) {
+            return fail_write ? ErrorCode::TRANSFER_FAIL
+                              : ErrorCode::RPC_TIMEOUT;
+        }
+        if (!source || record.total_size != length) {
+            return ErrorCode::INVALID_PARAMS;
+        }
+        std::vector<std::vector<uint8_t>> slices;
+        size_t offset = 0;
+        for (const auto& slice : record.slices) {
+            if (slice.slice_index != slices.size() ||
+                slice.logical_length > length - offset) {
+                return ErrorCode::INVALID_PARAMS;
+            }
+            const auto* begin = static_cast<const uint8_t*>(source) + offset;
+            slices.emplace_back(begin, begin + slice.logical_length);
+            offset += slice.logical_length;
+        }
+        if (offset != length) {
+            return ErrorCode::INVALID_PARAMS;
+        }
+        std::lock_guard<std::mutex> guard(mutex);
+        objects[record.vchunk_id] = std::move(slices);
+        return ErrorCode::OK;
+    }
+
+    ErrorCode Read(const VChunkMetadataRecord& record, void* destination,
+                   size_t length,
+                   std::chrono::steady_clock::time_point deadline) override {
+        ++read_attempts;
+        if (read_failures_remaining > 0) {
+            --read_failures_remaining;
+            return ErrorCode::TRANSFER_FAIL;
+        }
+        if (fail_read || std::chrono::steady_clock::now() >= deadline) {
+            return fail_read ? ErrorCode::TRANSFER_FAIL
+                             : ErrorCode::RPC_TIMEOUT;
+        }
+        if (block_reads) {
+            std::unique_lock<std::mutex> guard(sync_mutex);
+            read_entered = true;
+            sync_cv.notify_all();
+            sync_cv.wait(guard, [&] { return release_read; });
+        }
+        std::lock_guard<std::mutex> guard(mutex);
+        const auto it = objects.find(record.vchunk_id);
+        if (it == objects.end()) {
+            return ErrorCode::OBJECT_NOT_FOUND;
+        }
+        size_t offset = 0;
+        for (size_t i = 0; i < it->second.size(); ++i) {
+            if (record.slices[i].slice_index != i ||
+                it->second[i].size() > length - offset) {
+                return ErrorCode::TRANSFER_FAIL;
+            }
+            std::memcpy(static_cast<uint8_t*>(destination) + offset,
+                        it->second[i].data(), it->second[i].size());
+            offset += it->second[i].size();
+        }
+        return offset == length ? ErrorCode::OK : ErrorCode::TRANSFER_FAIL;
+    }
+
+    bool fail_write{false};
+    bool fail_read{false};
+    int write_failures_remaining{0};
+    int read_failures_remaining{0};
+    int write_attempts{0};
+    int read_attempts{0};
+    bool block_reads{false};
+    bool read_entered{false};
+    bool release_read{false};
+    std::mutex sync_mutex;
+    std::condition_variable sync_cv;
+    std::mutex mutex;
+    std::unordered_map<std::string, std::vector<std::vector<uint8_t>>> objects;
+};
+
+class LegacySpy final : public VChunkLegacyPath {
+   public:
+    ErrorCode Put(const TenantId&, const std::string&, const void*,
+                  size_t) override {
+        ++puts;
+        return ErrorCode::OK;
+    }
+    ErrorCode Get(const TenantId&, const std::string&, void*, size_t) override {
+        ++gets;
+        return ErrorCode::OK;
+    }
+    ErrorCode Remove(const TenantId&, const std::string&) override {
+        ++removes;
+        return ErrorCode::OK;
+    }
+    int puts{0};
+    int gets{0};
+    int removes{0};
+};
+
+class DelayingControlPlane final : public VChunkControlPlane {
+   public:
+    DelayingControlPlane(VChunkControlPlane& delegate,
+                         std::chrono::milliseconds delay)
+        : delegate_(delegate), delay_(delay) {}
+
+    tl::expected<VChunkMetadataRecord, ErrorCode> PutStart(
+        const TenantId& tenant_id, const std::string& key, uint64_t total_size,
+        int64_t now_ms) override {
+        std::this_thread::sleep_for(delay_);
+        return delegate_.PutStart(tenant_id, key, total_size, now_ms);
+    }
+
+    ErrorCode PutEnd(const TenantId& tenant_id, const std::string& key,
+                     const std::string& vchunk_id, int64_t now_ms) override {
+        return delegate_.PutEnd(tenant_id, key, vchunk_id, now_ms);
+    }
+
+    ErrorCode PutRevoke(const TenantId& tenant_id, const std::string& key,
+                        const std::string& vchunk_id) override {
+        return delegate_.PutRevoke(tenant_id, key, vchunk_id);
+    }
+
+    tl::expected<VChunkControlPlaneRead, ErrorCode> Get(
+        const TenantId& tenant_id, const std::string& key) override {
+        std::this_thread::sleep_for(delay_);
+        return delegate_.Get(tenant_id, key);
+    }
+
+    ErrorCode Remove(const TenantId& tenant_id, const std::string& key,
+                     int64_t now_ms) override {
+        return delegate_.Remove(tenant_id, key, now_ms);
+    }
+
+   private:
+    VChunkControlPlane& delegate_;
+    std::chrono::milliseconds delay_;
+};
+
+struct ClientFixture : testing::Test {
+    ClientFixture() : service(MakeConfig()) {
+        const auto client_id = generate_uuid();
+        EXPECT_TRUE(service.MountSegment(
+                               MakeSegment("vchunk-a", 0xB00000000ULL),
+                               client_id)
+                        .has_value());
+        EXPECT_TRUE(service.MountSegment(
+                               MakeSegment("vchunk-b", 0xC00000000ULL),
+                               client_id)
+                        .has_value());
+    }
+
+    static MasterServiceConfig MakeConfig() {
+        MasterServiceConfig config;
+        config.memory_allocator = BufferAllocatorType::OFFSET;
+        config.vchunk_config.enabled = true;
+        return config;
+    }
+
+    int64_t now{100};
+    MasterService service;
+    MemoryDataPlane data;
+    LegacySpy legacy;
+};
+
+TEST_F(ClientFixture, PutGetRemoveRoundTripForPiercingSizes) {
+    const std::array<size_t, 6> sizes{4096, 64U * 1024U, 256U * 1024U,
+                                      1024U * 1024U, 4U * 1024U * 1024U,
+                                      1024U * 1024U + 17U};
+    VChunkClient client(true, service, data, legacy,
+                        std::chrono::seconds(1), [this] { return ++now; });
+    std::mt19937 random(7);
+    for (const auto size : sizes) {
+        std::vector<uint8_t> source(size);
+        std::generate(source.begin(), source.end(), [&] { return random(); });
+        std::vector<uint8_t> destination(size, 0);
+        const auto key = "key-" + std::to_string(size);
+        ASSERT_EQ(client.Put(TenantId("tenant"), key, source.data(), size),
+                  ErrorCode::OK);
+        ASSERT_EQ(client.Get(TenantId("tenant"), key, destination.data(), size),
+                  ErrorCode::OK);
+        EXPECT_EQ(destination, source);
+        EXPECT_EQ(client.Remove(TenantId("tenant"), key), ErrorCode::OK);
+        EXPECT_EQ(client.Remove(TenantId("tenant"), key), ErrorCode::OK);
+        EXPECT_EQ(client.Get(TenantId("tenant"), key, destination.data(), size),
+                  ErrorCode::OBJECT_NOT_FOUND);
+    }
+}
+
+TEST_F(ClientFixture, FailedWriteRevokesCreatingObject) {
+    VChunkClient client(true, service, data, legacy,
+                        std::chrono::seconds(1), [this] { return ++now; });
+    std::vector<uint8_t> source(8192, 1);
+    data.fail_write = true;
+    EXPECT_EQ(client.Put(TenantId("tenant"), "key", source.data(),
+                         source.size()),
+              ErrorCode::TRANSFER_FAIL);
+    EXPECT_EQ(service.GetVChunk(TenantId("tenant"), "key").error(),
+              ErrorCode::OBJECT_NOT_FOUND);
+}
+
+TEST_F(ClientFixture, FailedReadDoesNotReturnPartialSuccess) {
+    VChunkClient client(true, service, data, legacy,
+                        std::chrono::seconds(1), [this] { return ++now; });
+    std::vector<uint8_t> source(8192, 3);
+    ASSERT_EQ(client.Put(TenantId("tenant"), "key", source.data(),
+                         source.size()),
+              ErrorCode::OK);
+    std::vector<uint8_t> destination(source.size(), 0);
+    data.fail_read = true;
+    EXPECT_EQ(client.Get(TenantId("tenant"), "key", destination.data(),
+                         destination.size()),
+              ErrorCode::TRANSFER_FAIL);
+}
+
+TEST_F(ClientFixture, DisabledVChunkUsesOnlyLegacyPath) {
+    VChunkClient client(false, service, data, legacy,
+                        std::chrono::seconds(1), [this] { return ++now; });
+    uint8_t value = 1;
+    EXPECT_EQ(client.Put(TenantId("tenant"), "key", &value, 1), ErrorCode::OK);
+    EXPECT_EQ(client.Get(TenantId("tenant"), "key", &value, 1), ErrorCode::OK);
+    EXPECT_EQ(client.Remove(TenantId("tenant"), "key"), ErrorCode::OK);
+    EXPECT_EQ(legacy.puts, 1);
+    EXPECT_EQ(legacy.gets, 1);
+    EXPECT_EQ(legacy.removes, 1);
+    EXPECT_EQ(service.GetVChunk(TenantId("tenant"), "key").error(),
+              ErrorCode::OBJECT_NOT_FOUND);
+}
+
+TEST_F(ClientFixture, InflightGetCompletesWhileRemoveBlocksNewReads) {
+    VChunkClient client(true, service, data, legacy,
+                        std::chrono::seconds(1), [this] { return ++now; });
+    std::vector<uint8_t> source(8192, 9);
+    ASSERT_EQ(client.Put(TenantId("tenant"), "key", source.data(),
+                         source.size()),
+              ErrorCode::OK);
+    data.block_reads = true;
+    std::vector<uint8_t> destination(source.size(), 0);
+    ErrorCode read_result = ErrorCode::INTERNAL_ERROR;
+    std::thread reader([&] {
+        read_result = client.Get(TenantId("tenant"), "key", destination.data(),
+                                 destination.size());
+    });
+    {
+        std::unique_lock<std::mutex> guard(data.sync_mutex);
+        data.sync_cv.wait(guard, [&] { return data.read_entered; });
+    }
+
+    EXPECT_EQ(client.Remove(TenantId("tenant"), "key"), ErrorCode::OK);
+    std::vector<uint8_t> second(source.size(), 0);
+    EXPECT_EQ(client.Get(TenantId("tenant"), "key", second.data(),
+                         second.size()),
+              ErrorCode::OBJECT_NOT_FOUND);
+    {
+        std::lock_guard<std::mutex> guard(data.sync_mutex);
+        data.release_read = true;
+    }
+    data.sync_cv.notify_all();
+    reader.join();
+    EXPECT_EQ(read_result, ErrorCode::OK);
+    EXPECT_EQ(destination, source);
+}
+
+TEST_F(ClientFixture, BatchKeepsPerKeyFailuresIndependent) {
+    VChunkClient client(true, service, data, legacy,
+                        std::chrono::seconds(1), [this] { return ++now; });
+    std::vector<uint8_t> first(4096, 1);
+    std::vector<uint8_t> third(4096, 3);
+    const std::vector<VChunkClient::PutRequest> puts{
+        {"first", first.data(), first.size()}, {"bad", nullptr, 4096},
+        {"third", third.data(), third.size()}};
+    const auto put_results = client.BatchPut(TenantId("tenant"), puts);
+    ASSERT_EQ(put_results.size(), 3U);
+    EXPECT_EQ(put_results[0], ErrorCode::OK);
+    EXPECT_EQ(put_results[1], ErrorCode::INVALID_PARAMS);
+    EXPECT_EQ(put_results[2], ErrorCode::OK);
+
+    std::vector<uint8_t> first_out(first.size());
+    std::vector<uint8_t> missing(first.size());
+    std::vector<uint8_t> third_out(third.size());
+    const std::vector<VChunkClient::GetRequest> gets{
+        {"first", first_out.data(), first_out.size()},
+        {"missing", missing.data(), missing.size()},
+        {"third", third_out.data(), third_out.size()}};
+    const auto get_results = client.BatchGet(TenantId("tenant"), gets);
+    EXPECT_EQ(get_results[0], ErrorCode::OK);
+    EXPECT_EQ(get_results[1], ErrorCode::OBJECT_NOT_FOUND);
+    EXPECT_EQ(get_results[2], ErrorCode::OK);
+    EXPECT_EQ(first_out, first);
+    EXPECT_EQ(third_out, third);
+}
+
+TEST_F(ClientFixture, RetriesRetryableTransfersWithinConfiguredLimit) {
+    VChunkClient client(true, service, data, legacy,
+                        std::chrono::seconds(1), [this] { return ++now; }, 2);
+    std::vector<uint8_t> source(4096, 5);
+    data.write_failures_remaining = 1;
+    EXPECT_EQ(client.Put(TenantId("tenant"), "key", source.data(),
+                         source.size()),
+              ErrorCode::OK);
+    EXPECT_EQ(data.write_attempts, 2);
+    const auto metrics = client.MetricsSnapshot();
+    EXPECT_EQ(metrics.retries, 1U);
+    EXPECT_EQ(metrics.requests[static_cast<size_t>(VChunkOperation::PUT)], 1U);
+    EXPECT_EQ(metrics.successes[static_cast<size_t>(VChunkOperation::PUT)], 1U);
+}
+
+TEST_F(ClientFixture, CircuitBreakerStopsOnlyNewVChunkCreation) {
+    VChunkClient client(true, service, data, legacy,
+                        std::chrono::seconds(1), [this] { return ++now; }, 0,
+                        1);
+    std::vector<uint8_t> source(4096, 5);
+    ASSERT_EQ(client.Put(TenantId("tenant"), "active", source.data(),
+                         source.size()),
+              ErrorCode::OK);
+    data.fail_write = true;
+    EXPECT_EQ(client.Put(TenantId("tenant"), "failed", source.data(),
+                         source.size()),
+              ErrorCode::TRANSFER_FAIL);
+    data.fail_write = false;
+    EXPECT_EQ(client.Put(TenantId("tenant"), "blocked", source.data(),
+                         source.size()),
+              ErrorCode::NO_AVAILABLE_HANDLE);
+    EXPECT_EQ(data.write_attempts, 2);
+    std::vector<uint8_t> output(source.size());
+    EXPECT_EQ(client.Get(TenantId("tenant"), "active", output.data(),
+                         output.size()),
+              ErrorCode::OK);
+    EXPECT_EQ(output, source);
+    EXPECT_EQ(client.Remove(TenantId("tenant"), "active"), ErrorCode::OK);
+}
+
+TEST_F(ClientFixture, ControlPlaneLatencyConsumesOperationTimeout) {
+    LocalVChunkControlPlane local(service);
+    DelayingControlPlane delayed(local, std::chrono::milliseconds(20));
+    VChunkClient timed_client(true, delayed, data, legacy,
+                              std::chrono::milliseconds(1),
+                              [this] { return ++now; });
+    std::vector<uint8_t> source(4096, 7);
+    EXPECT_EQ(timed_client.Put(TenantId("tenant"), "slow-put", source.data(),
+                               source.size()),
+              ErrorCode::RPC_TIMEOUT);
+    EXPECT_EQ(service.GetVChunk(TenantId("tenant"), "slow-put").error(),
+              ErrorCode::OBJECT_NOT_FOUND);
+
+    VChunkClient setup_client(true, service, data, legacy,
+                              std::chrono::seconds(1),
+                              [this] { return ++now; });
+    ASSERT_EQ(setup_client.Put(TenantId("tenant"), "slow-get", source.data(),
+                               source.size()),
+              ErrorCode::OK);
+    std::vector<uint8_t> destination(source.size());
+    EXPECT_EQ(timed_client.Get(TenantId("tenant"), "slow-get",
+                               destination.data(), destination.size()),
+              ErrorCode::RPC_TIMEOUT);
+    EXPECT_EQ(data.read_attempts, 0);
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/vchunk_config_test.cpp b/mooncake-store/tests/vchunk_config_test.cpp
new file mode 100644
index 0000000000..88e0e7960d
--- /dev/null
+++ b/mooncake-store/tests/vchunk_config_test.cpp
@@ -0,0 +1,63 @@
+#include "vchunk_config.h"
+
+#include <gtest/gtest.h>
+
+namespace mooncake {
+namespace {
+
+TEST(VChunkConfigTest, DefaultsAreSafeForProductionOptIn) {
+    VChunkConfig config;
+    EXPECT_FALSE(config.enabled);
+    EXPECT_EQ(config.Validate(), ErrorCode::OK);
+    EXPECT_EQ(config.max_slice_count, 4096U);
+    EXPECT_EQ(config.max_metadata_bytes, 1024U * 1024U);
+    EXPECT_EQ(config.max_creating_objects, 1024U);
+    EXPECT_EQ(config.reaper_interval_ms, 1000U);
+    EXPECT_EQ(config.reaper_max_scan, 128U);
+}
+
+TEST(VChunkConfigTest, RejectsInvalidLimits) {
+    VChunkConfig config;
+    config.max_slice_count = 0;
+    EXPECT_EQ(config.Validate(), ErrorCode::INVALID_PARAMS);
+
+    config = VChunkConfig{};
+    config.max_metadata_bytes = 0;
+    EXPECT_EQ(config.Validate(), ErrorCode::INVALID_PARAMS);
+
+    config = VChunkConfig{};
+    config.creating_timeout_ms = 0;
+    EXPECT_EQ(config.Validate(), ErrorCode::INVALID_PARAMS);
+
+    config = VChunkConfig{};
+    config.max_creating_objects = 0;
+    EXPECT_EQ(config.Validate(), ErrorCode::INVALID_PARAMS);
+
+    config = VChunkConfig{};
+    config.reaper_interval_ms = 0;
+    EXPECT_EQ(config.Validate(), ErrorCode::INVALID_PARAMS);
+}
+
+TEST(VChunkConfigTest, SelectsMemorySliceBoundaries) {
+    EXPECT_EQ(SelectVChunkSliceSize(0, false), VCSliceSizeLevel::k4K);
+    EXPECT_EQ(SelectVChunkSliceSize(64U * 1024U - 1, false),
+              VCSliceSizeLevel::k4K);
+    EXPECT_EQ(SelectVChunkSliceSize(64U * 1024U, false),
+              VCSliceSizeLevel::k64K);
+    EXPECT_EQ(SelectVChunkSliceSize(256U * 1024U - 1, false),
+              VCSliceSizeLevel::k64K);
+    EXPECT_EQ(SelectVChunkSliceSize(256U * 1024U, false),
+              VCSliceSizeLevel::k256K);
+    EXPECT_EQ(SelectVChunkSliceSize(1024U * 1024U - 1, false),
+              VCSliceSizeLevel::k256K);
+    EXPECT_EQ(SelectVChunkSliceSize(1024U * 1024U, false),
+              VCSliceSizeLevel::k1M);
+}
+
+TEST(VChunkConfigTest, SsdAlwaysUsesFourKiB) {
+    EXPECT_EQ(SelectVChunkSliceSize(8U * 1024U * 1024U, true),
+              VCSliceSizeLevel::k4K);
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/vchunk_master_manager_test.cpp b/mooncake-store/tests/vchunk_master_manager_test.cpp
new file mode 100644
index 0000000000..a85694879e
--- /dev/null
+++ b/mooncake-store/tests/vchunk_master_manager_test.cpp
@@ -0,0 +1,216 @@
+#include "vchunk_master_manager.h"
+
+#include <gtest/gtest.h>
+
+#include <atomic>
+#include <memory>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include "allocation_strategy.h"
+#include "vchunk_test_allocator.h"
+
+namespace mooncake {
+namespace {
+
+using test::VChunkTestAllocator;
+
+struct ManagerFixture {
+    AllocatorManager allocators;
+    std::shared_ptr<VChunkTestAllocator> first =
+        std::make_shared<VChunkTestAllocator>("segment-a", 0x700000000ULL,
+                                              1024U * 1024U);
+    std::shared_ptr<VChunkTestAllocator> second =
+        std::make_shared<VChunkTestAllocator>("segment-b", 0x800000000ULL,
+                                              1024U * 1024U);
+
+    ManagerFixture() {
+        allocators.addAllocator("segment-a", first);
+        allocators.addAllocator("segment-b", second);
+    }
+};
+
+VChunkConfig EnabledConfig() {
+    VChunkConfig config;
+    config.enabled = true;
+    return config;
+}
+
+TEST(VChunkMasterManagerTest, RunsPutGetRemoveLifecycle) {
+    ManagerFixture fixture;
+    VChunkMasterManager manager(EnabledConfig());
+    const TenantId tenant("tenant-a");
+
+    auto created = manager.PutStart(fixture.allocators, tenant, "key", 10U * 1024U,
+                                    false, 100);
+    ASSERT_TRUE(created.has_value());
+    EXPECT_EQ(created->status, VChunkStatus::CREATING);
+    EXPECT_EQ(created->slice_count, 3U);
+    EXPECT_EQ(created->row_size, 2U);
+    EXPECT_FALSE(manager.Get(tenant, "key").has_value());
+
+    EXPECT_EQ(manager.PutEnd(tenant, "key", "wrong-id", 200),
+              ErrorCode::INVALID_VERSION);
+    EXPECT_EQ(manager.PutEnd(tenant, "key", created->vchunk_id, 200),
+              ErrorCode::OK);
+    EXPECT_EQ(manager.PutEnd(tenant, "key", created->vchunk_id, 200),
+              ErrorCode::OK);
+
+    auto active = manager.Get(tenant, "key");
+    ASSERT_TRUE(active.has_value());
+    EXPECT_EQ(active->status, VChunkStatus::ACTIVE);
+    for (const auto& slice : active->slices) {
+        EXPECT_EQ(slice.status, VCSliceStatus::COMPLETED);
+    }
+
+    EXPECT_EQ(manager.Remove(tenant, "key", 300), ErrorCode::OK);
+    EXPECT_EQ(manager.Remove(tenant, "key", 301), ErrorCode::OK);
+    EXPECT_EQ(manager.SizeForTesting(), 0U);
+    EXPECT_EQ(fixture.first->size(), 0U);
+    EXPECT_EQ(fixture.second->size(), 0U);
+}
+
+TEST(VChunkMasterManagerTest, RevokeIsIdempotentAndReleasesBuffers) {
+    ManagerFixture fixture;
+    VChunkMasterManager manager(EnabledConfig());
+    const TenantId tenant("tenant-a");
+    auto created = manager.PutStart(fixture.allocators, tenant, "key", 8192,
+                                    false, 100);
+    ASSERT_TRUE(created.has_value());
+    EXPECT_GT(fixture.first->size() + fixture.second->size(), 0U);
+
+    EXPECT_EQ(manager.PutRevoke(tenant, "key", created->vchunk_id),
+              ErrorCode::OK);
+    EXPECT_EQ(manager.PutRevoke(tenant, "key", created->vchunk_id),
+              ErrorCode::OK);
+    EXPECT_EQ(fixture.first->size() + fixture.second->size(), 0U);
+}
+
+TEST(VChunkMasterManagerTest, ConcurrentPutStartPublishesOneObject) {
+    ManagerFixture fixture;
+    VChunkMasterManager manager(EnabledConfig());
+    const TenantId tenant("tenant-a");
+    std::atomic<int> success{0};
+    std::atomic<int> already_exists{0};
+    std::vector<std::thread> threads;
+    for (int i = 0; i < 8; ++i) {
+        threads.emplace_back([&] {
+            auto result = manager.PutStart(fixture.allocators, tenant, "key",
+                                           8192, false, 100);
+            if (result.has_value()) {
+                ++success;
+            } else if (result.error() == ErrorCode::OBJECT_ALREADY_EXISTS) {
+                ++already_exists;
+            }
+        });
+    }
+    for (auto& thread : threads) {
+        thread.join();
+    }
+    EXPECT_EQ(success.load(), 1);
+    EXPECT_EQ(already_exists.load(), 7);
+    EXPECT_EQ(manager.SizeForTesting(), 1U);
+}
+
+TEST(VChunkMasterManagerTest, IsolatesSameKeyAcrossTenants) {
+    ManagerFixture fixture;
+    VChunkMasterManager manager(EnabledConfig());
+    auto first = manager.PutStart(fixture.allocators, TenantId("tenant-a"),
+                                  "key", 4096, false, 100);
+    auto second = manager.PutStart(fixture.allocators, TenantId("tenant-b"),
+                                   "key", 4096, false, 100);
+    ASSERT_TRUE(first.has_value());
+    ASSERT_TRUE(second.has_value());
+    EXPECT_NE(first->vchunk_id, second->vchunk_id);
+    EXPECT_EQ(manager.SizeForTesting(), 2U);
+}
+
+TEST(VChunkMasterManagerTest, GetAndRemoveAreSerializedSafely) {
+    ManagerFixture fixture;
+    VChunkMasterManager manager(EnabledConfig());
+    const TenantId tenant("tenant-a");
+    auto created = manager.PutStart(fixture.allocators, tenant, "key", 8192,
+                                    false, 100);
+    ASSERT_TRUE(created.has_value());
+    ASSERT_EQ(manager.PutEnd(tenant, "key", created->vchunk_id, 200),
+              ErrorCode::OK);
+
+    std::atomic<bool> stop{false};
+    std::atomic<int> valid_reads{0};
+    std::thread reader([&] {
+        while (!stop.load()) {
+            auto result = manager.Get(tenant, "key");
+            if (result.has_value()) {
+                EXPECT_EQ(result->status, VChunkStatus::ACTIVE);
+                ++valid_reads;
+            } else {
+                EXPECT_EQ(result.error(), ErrorCode::OBJECT_NOT_FOUND);
+            }
+        }
+    });
+    EXPECT_EQ(manager.Remove(tenant, "key", 300), ErrorCode::OK);
+    stop.store(true);
+    reader.join();
+
+    EXPECT_EQ(manager.SizeForTesting(), 0U);
+    EXPECT_EQ(fixture.first->size() + fixture.second->size(), 0U);
+}
+
+TEST(VChunkMasterManagerTest, ReadLeaseDefersBufferReleaseAfterRemove) {
+    ManagerFixture fixture;
+    VChunkMasterManager manager(EnabledConfig());
+    const TenantId tenant("tenant-a");
+    auto created = manager.PutStart(fixture.allocators, tenant, "key", 8192,
+                                    false, 100);
+    ASSERT_TRUE(created.has_value());
+    ASSERT_EQ(manager.PutEnd(tenant, "key", created->vchunk_id, 200),
+              ErrorCode::OK);
+
+    const auto allocated = fixture.first->size() + fixture.second->size();
+    ASSERT_GT(allocated, 0U);
+    {
+        auto read = manager.AcquireRead(tenant, "key");
+        ASSERT_TRUE(read.has_value());
+        EXPECT_EQ(manager.Remove(tenant, "key", 300), ErrorCode::OK);
+        EXPECT_FALSE(manager.Get(tenant, "key").has_value());
+        EXPECT_EQ(fixture.first->size() + fixture.second->size(), allocated);
+    }
+    EXPECT_EQ(fixture.first->size() + fixture.second->size(), 0U);
+}
+
+TEST(VChunkMasterManagerTest, DisabledConfigurationRejectsCreation) {
+    ManagerFixture fixture;
+    VChunkMasterManager manager(VChunkConfig{});
+    auto result = manager.PutStart(fixture.allocators, TenantId::Default(),
+                                   "key", 4096, false, 100);
+    EXPECT_FALSE(result.has_value());
+    EXPECT_EQ(result.error(), ErrorCode::INVALID_PARAMS);
+}
+
+TEST(VChunkMasterManagerTest, PiercingVersionRejectsSsdSegments) {
+    ManagerFixture fixture;
+    VChunkMasterManager manager(EnabledConfig());
+    auto result = manager.PutStart(fixture.allocators, TenantId::Default(),
+                                   "key", 4096, true, 100);
+    EXPECT_FALSE(result.has_value());
+    EXPECT_EQ(result.error(), ErrorCode::INVALID_PARAMS);
+    EXPECT_EQ(fixture.first->size() + fixture.second->size(), 0U);
+}
+
+TEST(VChunkMasterManagerTest, CreatingBacklogTripsAllocationCircuitBreaker) {
+    ManagerFixture fixture;
+    auto config = EnabledConfig();
+    config.max_creating_objects = 1;
+    VChunkMasterManager manager(config);
+    ASSERT_TRUE(manager.PutStart(fixture.allocators, TenantId("tenant"),
+                                 "first", 4096, false, 100)
+                    .has_value());
+    auto blocked = manager.PutStart(fixture.allocators, TenantId("tenant"),
+                                    "second", 4096, false, 101);
+    ASSERT_FALSE(blocked.has_value());
+    EXPECT_EQ(blocked.error(), ErrorCode::NO_AVAILABLE_HANDLE);
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/vchunk_master_service_test.cpp b/mooncake-store/tests/vchunk_master_service_test.cpp
new file mode 100644
index 0000000000..091e13e21a
--- /dev/null
+++ b/mooncake-store/tests/vchunk_master_service_test.cpp
@@ -0,0 +1,151 @@
+#include "master_service.h"
+
+#include <gtest/gtest.h>
+
+#include <chrono>
+#include <memory>
+#include <string>
+#include <thread>
+
+#include "master_config.h"
+#include "types.h"
+
+namespace mooncake {
+namespace {
+
+Segment MakeVChunkSegment(const std::string& name, uintptr_t base) {
+    Segment segment;
+    segment.id = generate_uuid();
+    segment.name = name;
+    segment.base = base;
+    segment.size = 64U * 1024U * 1024U;
+    segment.te_endpoint = name;
+    return segment;
+}
+
+TEST(VChunkMasterServiceTest, BuilderPropagatesVChunkConfiguration) {
+    VChunkConfig vchunk_config;
+    vchunk_config.enabled = true;
+    vchunk_config.max_slice_count = 128;
+    auto metadata_store = std::make_shared<InMemoryVChunkMetadataStore>();
+    const auto config = MasterServiceConfig::builder()
+                            .set_vchunk_config(vchunk_config)
+                            .set_vchunk_metadata_store(metadata_store)
+                            .build();
+    EXPECT_TRUE(config.vchunk_config.enabled);
+    EXPECT_EQ(config.vchunk_config.max_slice_count, 128U);
+    EXPECT_EQ(config.vchunk_metadata_store, metadata_store);
+}
+
+TEST(VChunkMasterServiceTest, DisabledModeRejectsAllControlPlaneOperations) {
+    MasterServiceConfig config;
+    config.vchunk_config.enabled = false;
+    MasterService service(config);
+    const TenantId tenant("tenant");
+
+    EXPECT_EQ(service.VChunkPutStart(tenant, "key", 4096, false, 1).error(),
+              ErrorCode::UNAVAILABLE_IN_CURRENT_MODE);
+    EXPECT_EQ(service.VChunkPutEnd(tenant, "key", "id", 2),
+              ErrorCode::UNAVAILABLE_IN_CURRENT_MODE);
+    EXPECT_EQ(service.VChunkPutRevoke(tenant, "key", "id"),
+              ErrorCode::UNAVAILABLE_IN_CURRENT_MODE);
+    EXPECT_EQ(service.GetVChunk(tenant, "key").error(),
+              ErrorCode::UNAVAILABLE_IN_CURRENT_MODE);
+    EXPECT_EQ(service.AcquireVChunkRead(tenant, "key").error(),
+              ErrorCode::UNAVAILABLE_IN_CURRENT_MODE);
+    EXPECT_EQ(service.RemoveVChunk(tenant, "key", 3),
+              ErrorCode::UNAVAILABLE_IN_CURRENT_MODE);
+    EXPECT_EQ(service.ReapExpiredVChunks(4, 1).error(),
+              ErrorCode::UNAVAILABLE_IN_CURRENT_MODE);
+}
+
+TEST(VChunkMasterServiceTest, PartitionedModeRejectsBeforeSlotViewIsReady) {
+    MasterServiceConfig config;
+    config.enable_ha = true;
+    config.ha_backend_type = "etcd";
+    config.submaster_count = 2;
+    config.vchunk_config.enabled = true;
+    MasterService service(config);
+
+    EXPECT_EQ(service
+                  .VChunkPutStart(TenantId("tenant"), "key", 4096, false, 1)
+                  .error(),
+              ErrorCode::SLOT_NOT_OWNED);
+    EXPECT_EQ(service.GetVChunk(TenantId("tenant"), "key").error(),
+              ErrorCode::SLOT_NOT_OWNED);
+}
+
+TEST(VChunkMasterServiceTest, BackgroundReaperStopsAndCleansExpiredCreating) {
+    MasterServiceConfig config;
+    config.memory_allocator = BufferAllocatorType::OFFSET;
+    config.vchunk_config.enabled = true;
+    config.vchunk_config.creating_timeout_ms = 1;
+    config.vchunk_config.reaper_interval_ms = 5;
+    config.vchunk_config.reaper_max_scan = 4;
+    MasterService service(config);
+    ASSERT_TRUE(service
+                    .MountSegment(
+                        MakeVChunkSegment("reaper-segment", 0xE00000000ULL),
+                        generate_uuid())
+                    .has_value());
+    const TenantId tenant("tenant");
+    ASSERT_TRUE(
+        service.VChunkPutStart(tenant, "expired", 4096, false, 0).has_value());
+    for (int i = 0; i < 100; ++i) {
+        if (service.GetVChunk(tenant, "expired").error() ==
+            ErrorCode::OBJECT_NOT_FOUND) {
+            break;
+        }
+        std::this_thread::sleep_for(std::chrono::milliseconds(5));
+    }
+    EXPECT_EQ(service.GetVChunk(tenant, "expired").error(),
+              ErrorCode::OBJECT_NOT_FOUND);
+    const auto metrics = service.GetVChunkMetrics();
+    EXPECT_EQ(metrics.states[static_cast<size_t>(VChunkStatus::CREATING)], 0U);
+    EXPECT_GE(metrics.rollbacks, 1U);
+}
+
+TEST(VChunkMasterServiceTest, ExposesIsolatedVChunkControlPlane) {
+    MasterServiceConfig config;
+    config.memory_allocator = BufferAllocatorType::OFFSET;
+    config.vchunk_config.enabled = true;
+    MasterService service(config);
+    const auto client_id = generate_uuid();
+    ASSERT_TRUE(service
+                    .MountSegment(
+                        MakeVChunkSegment("vchunk-segment-a", 0x900000000ULL),
+                        client_id)
+                    .has_value());
+    ASSERT_TRUE(service
+                    .MountSegment(
+                        MakeVChunkSegment("vchunk-segment-b", 0xA00000000ULL),
+                        client_id)
+                    .has_value());
+
+    const TenantId tenant("tenant-a");
+    auto created =
+        service.VChunkPutStart(tenant, "key", 10U * 1024U, false, 100);
+    ASSERT_TRUE(created.has_value());
+    EXPECT_EQ(created->row_size, 2U);
+    EXPECT_EQ(service.VChunkPutEnd(tenant, "key", created->vchunk_id, 200),
+              ErrorCode::OK);
+
+    auto active = service.GetVChunk(tenant, "key");
+    ASSERT_TRUE(active.has_value());
+    EXPECT_EQ(active->status, VChunkStatus::ACTIVE);
+    auto remote_read = service.AcquireVChunkReadLease(tenant, "key", 250);
+    ASSERT_TRUE(remote_read.has_value());
+    EXPECT_FALSE(remote_read->lease_id.empty());
+    EXPECT_EQ(remote_read->record.vchunk_id, created->vchunk_id);
+    EXPECT_EQ(service.RemoveVChunk(tenant, "key", 300), ErrorCode::OK);
+    EXPECT_EQ(service.ReleaseVChunkReadLease(remote_read->lease_id),
+              ErrorCode::OK);
+    EXPECT_EQ(service.ReleaseVChunkReadLease(remote_read->lease_id),
+              ErrorCode::OK);
+    EXPECT_EQ(service.ReleaseVChunkReadLease(""), ErrorCode::INVALID_PARAMS);
+    EXPECT_EQ(service.GetVChunk(tenant, "key").error(),
+              ErrorCode::OBJECT_NOT_FOUND);
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/vchunk_metadata_store_test.cpp b/mooncake-store/tests/vchunk_metadata_store_test.cpp
new file mode 100644
index 0000000000..175386a36b
--- /dev/null
+++ b/mooncake-store/tests/vchunk_metadata_store_test.cpp
@@ -0,0 +1,278 @@
+#include "vchunk_metadata_store.h"
+
+#include <gtest/gtest.h>
+
+#include <algorithm>
+#include <memory>
+#include <string>
+#include <vector>
+
+#include "allocation_strategy.h"
+#include "master_service.h"
+#include "vchunk_master_manager.h"
+#include "vchunk_test_allocator.h"
+
+namespace mooncake {
+namespace {
+
+class FaultStore final : public VChunkMetadataStore {
+   public:
+    ErrorCode Put(const VChunkMetadataRecord& record) override {
+        if (fail_put) return ErrorCode::ETCD_OPERATION_ERROR;
+        for (auto& current : records) {
+            if (current.vchunk_id == record.vchunk_id) {
+                current = record;
+                return ErrorCode::OK;
+            }
+        }
+        records.push_back(record);
+        return ErrorCode::OK;
+    }
+    ErrorCode Remove(const VChunkMetadataRecord& record) override {
+        if (fail_remove) return ErrorCode::ETCD_OPERATION_ERROR;
+        std::erase_if(records, [&](const auto& current) {
+            return current.vchunk_id == record.vchunk_id;
+        });
+        return ErrorCode::OK;
+    }
+    tl::expected<std::vector<VChunkMetadataRecord>, ErrorCode> List() override {
+        if (fail_list) {
+            return tl::make_unexpected(ErrorCode::ETCD_OPERATION_ERROR);
+        }
+        return records;
+    }
+    bool IsPersistent() const override { return true; }
+
+    bool fail_put{false};
+    bool fail_remove{false};
+    bool fail_list{false};
+    std::vector<VChunkMetadataRecord> records;
+};
+
+struct StoreFixture {
+    AllocatorManager allocators;
+    std::shared_ptr<test::VChunkTestAllocator> allocator =
+        std::make_shared<test::VChunkTestAllocator>(
+            "segment", 0xD00000000ULL, 4U * 1024U * 1024U);
+    std::shared_ptr<FaultStore> store = std::make_shared<FaultStore>();
+    VChunkConfig config;
+
+    StoreFixture() {
+        allocators.addAllocator("segment", allocator);
+        config.enabled = true;
+        config.creating_timeout_ms = 100;
+    }
+};
+
+TEST(VChunkMetadataStoreTest, UsesStableTenantAndVChunkNamespace) {
+    VChunkMetadataRecord record;
+    record.tenant_id = "tenant-a";
+    record.vchunk_id = "id-a";
+    EXPECT_EQ(MakeVChunkMetadataStoreKey(record),
+              "/mooncake/vchunk/v1/tenant-a/id-a");
+}
+
+TEST(VChunkMetadataStoreTest, PutStartIsNotVisibleWhenDurableWriteFails) {
+    StoreFixture fixture;
+    fixture.store->fail_put = true;
+    VChunkMasterManager manager(fixture.config, fixture.store);
+    auto result = manager.PutStart(fixture.allocators, TenantId("tenant"),
+                                   "key", 4096, false, 10);
+    ASSERT_FALSE(result.has_value());
+    EXPECT_EQ(result.error(), ErrorCode::ETCD_OPERATION_ERROR);
+    EXPECT_EQ(manager.SizeForTesting(), 0U);
+    EXPECT_EQ(fixture.allocator->size(), 0U);
+
+    fixture.store->fail_put = false;
+    EXPECT_TRUE(manager.PutStart(fixture.allocators, TenantId("tenant"),
+                                 "key", 4096, false, 11)
+                    .has_value());
+}
+
+TEST(VChunkMetadataStoreTest, PersistsCreatingThenActiveBeforeVisibility) {
+    StoreFixture fixture;
+    VChunkMasterManager manager(fixture.config, fixture.store);
+    auto created = manager.PutStart(fixture.allocators, TenantId("tenant"),
+                                    "key", 4096, false, 10);
+    ASSERT_TRUE(created.has_value());
+    ASSERT_EQ(fixture.store->records.size(), 1U);
+    EXPECT_EQ(fixture.store->records[0].status, VChunkStatus::CREATING);
+    ASSERT_EQ(manager.PutEnd(TenantId("tenant"), "key", created->vchunk_id,
+                             20),
+              ErrorCode::OK);
+    EXPECT_EQ(fixture.store->records[0].status, VChunkStatus::ACTIVE);
+}
+
+TEST(VChunkMetadataStoreTest, RecoveryRejectsActiveWithoutAllocatorRestore) {
+    StoreFixture fixture;
+    VChunkMetadataRecord active;
+    {
+        VChunkMasterManager writer(fixture.config, fixture.store);
+        auto created = writer.PutStart(fixture.allocators, TenantId("tenant"),
+                                       "active", 4096, false, 10);
+        ASSERT_TRUE(created.has_value());
+        ASSERT_EQ(writer.PutEnd(TenantId("tenant"), "active",
+                                created->vchunk_id, 20),
+                  ErrorCode::OK);
+        active = *writer.Get(TenantId("tenant"), "active");
+    }
+    auto expired = active;
+    expired.vchunk_id = "expired";
+    expired.key = "expired";
+    expired.status = VChunkStatus::CREATING;
+    expired.last_updated_at_ms = 10;
+    for (auto& slice : expired.slices) {
+        slice.status = VCSliceStatus::PENDING;
+    }
+    ASSERT_EQ(fixture.store->Put(expired), ErrorCode::OK);
+
+    VChunkMasterManager recovered(fixture.config, fixture.store);
+    EXPECT_EQ(recovered.Recover(200), ErrorCode::REPLICA_IS_GONE);
+    EXPECT_EQ(recovered.SizeForTesting(), 0U);
+    // Validation is atomic: no incomplete record is removed when an ACTIVE
+    // record makes the whole snapshot unsafe to restore.
+    ASSERT_EQ(fixture.store->List()->size(), 2U);
+}
+
+TEST(VChunkMetadataStoreTest, RecoveryCleansIncompleteWrites) {
+    StoreFixture fixture;
+    VChunkMasterManager writer(fixture.config, fixture.store);
+    ASSERT_TRUE(writer.PutStart(fixture.allocators, TenantId("tenant"),
+                                "creating", 4096, false, 10)
+                    .has_value());
+
+    VChunkMasterManager recovered(fixture.config, fixture.store);
+    EXPECT_EQ(recovered.Recover(20), ErrorCode::OK);
+    EXPECT_TRUE(fixture.store->List()->empty());
+}
+
+TEST(VChunkMetadataStoreTest, RecoveryOnlyProcessesOwnedSubmasterRecords) {
+    StoreFixture fixture;
+    VChunkMetadataRecord foreign_active;
+    {
+        VChunkMasterManager writer(fixture.config, fixture.store);
+        auto foreign = writer.PutStart(fixture.allocators, TenantId("tenant"),
+                                       "foreign", 4096, false, 10);
+        ASSERT_TRUE(foreign.has_value());
+        ASSERT_EQ(writer.PutEnd(TenantId("tenant"), "foreign",
+                                foreign->vchunk_id, 20),
+                  ErrorCode::OK);
+        foreign_active = *writer.Get(TenantId("tenant"), "foreign");
+    }
+
+    auto owned_incomplete = foreign_active;
+    owned_incomplete.vchunk_id = "owned-incomplete";
+    owned_incomplete.key = "owned";
+    owned_incomplete.status = VChunkStatus::CREATING;
+    owned_incomplete.last_updated_at_ms = 10;
+    for (auto& slice : owned_incomplete.slices) {
+        slice.status = VCSliceStatus::PENDING;
+    }
+    ASSERT_EQ(fixture.store->Put(owned_incomplete), ErrorCode::OK);
+
+    VChunkMasterManager recovered(fixture.config, fixture.store);
+    EXPECT_EQ(recovered.Recover(
+                  100, [](const VChunkMetadataRecord& record) {
+                      return record.key == "owned";
+                  }),
+              ErrorCode::OK);
+    auto records = fixture.store->List();
+    ASSERT_TRUE(records.has_value());
+    ASSERT_EQ(records->size(), 1U);
+    EXPECT_EQ(records->front().vchunk_id, foreign_active.vchunk_id);
+}
+
+TEST(VChunkMetadataStoreTest, ReaperIsBoundedAndRetryable) {
+    StoreFixture fixture;
+    VChunkMasterManager manager(fixture.config, fixture.store);
+    for (int i = 0; i < 3; ++i) {
+        ASSERT_TRUE(manager.PutStart(fixture.allocators, TenantId("tenant"),
+                                     "key-" + std::to_string(i), 4096, false,
+                                     10)
+                        .has_value());
+    }
+    auto first = manager.ReapExpired(200, 2);
+    ASSERT_TRUE(first.has_value());
+    EXPECT_EQ(*first, 2U);
+    EXPECT_EQ(manager.SizeForTesting(), 1U);
+    fixture.store->fail_remove = true;
+    EXPECT_EQ(manager.ReapExpired(200, 2).error(),
+              ErrorCode::ETCD_OPERATION_ERROR);
+    EXPECT_EQ(manager.SizeForTesting(), 1U);
+    fixture.store->fail_remove = false;
+    EXPECT_EQ(*manager.ReapExpired(200, 2), 1U);
+    EXPECT_EQ(manager.SizeForTesting(), 0U);
+}
+
+TEST(VChunkMetadataStoreTest, ReaperSkipsRecordsOwnedByAnotherSubmaster) {
+    StoreFixture fixture;
+    VChunkMasterManager manager(fixture.config, fixture.store);
+    ASSERT_TRUE(manager.PutStart(fixture.allocators, TenantId("tenant"),
+                                 "owned", 4096, false, 10)
+                    .has_value());
+    ASSERT_TRUE(manager.PutStart(fixture.allocators, TenantId("tenant"),
+                                 "foreign", 4096, false, 10)
+                    .has_value());
+
+    auto result = manager.ReapExpired(
+        200, 2, [](const VChunkMetadataRecord& record) {
+            return record.key == "owned";
+        });
+    ASSERT_TRUE(result.has_value());
+    EXPECT_EQ(*result, 1U);
+    EXPECT_EQ(manager.SizeForTesting(), 1U);
+    EXPECT_EQ(manager.Get(TenantId("tenant"), "foreign")->key, "foreign");
+}
+
+TEST(VChunkMetadataStoreTest, RemoveFailureLeavesReleasingObjectRetryable) {
+    StoreFixture fixture;
+    VChunkMasterManager manager(fixture.config, fixture.store);
+    const TenantId tenant("tenant");
+    auto created = manager.PutStart(fixture.allocators, tenant, "key", 4096,
+                                    false, 10);
+    ASSERT_TRUE(created.has_value());
+    ASSERT_EQ(manager.PutEnd(tenant, "key", created->vchunk_id, 20),
+              ErrorCode::OK);
+    fixture.store->fail_remove = true;
+    EXPECT_EQ(manager.Remove(tenant, "key", 30),
+              ErrorCode::ETCD_OPERATION_ERROR);
+    EXPECT_EQ(manager.Get(tenant, "key").error(),
+              ErrorCode::REPLICA_IS_NOT_READY);
+    fixture.store->fail_remove = false;
+    EXPECT_EQ(manager.Remove(tenant, "key", 31), ErrorCode::OK);
+    EXPECT_EQ(manager.SizeForTesting(), 0U);
+}
+
+TEST(VChunkMetadataStoreTest, StartupRejectsUnavailableStore) {
+    auto store = std::make_shared<FaultStore>();
+    store->fail_list = true;
+    MasterServiceConfig unavailable;
+    unavailable.vchunk_config.enabled = true;
+    unavailable.vchunk_metadata_store = store;
+    EXPECT_THROW(MasterService service(unavailable), std::runtime_error);
+}
+
+TEST(VChunkMetadataStoreTest, StartupAllowsVChunkWithHaEnabled) {
+    MasterServiceConfig coexistence;
+    coexistence.vchunk_config.enabled = true;
+    coexistence.enable_ha = true;
+
+    MasterService service(coexistence);
+    EXPECT_TRUE(service.GetVChunkRuntimeInfo().enabled);
+}
+
+TEST(VChunkMetadataStoreTest, RecoveryRejectsUnknownSchemaVersion) {
+    StoreFixture fixture;
+    VChunkMetadataRecord record;
+    record.schema_version = kVChunkMetadataSchemaVersion + 1;
+    record.vchunk_id = "future";
+    record.tenant_id = "tenant";
+    record.key = "key";
+    fixture.store->records.push_back(record);
+    VChunkMasterManager manager(fixture.config, fixture.store);
+    EXPECT_EQ(manager.Recover(100), ErrorCode::INVALID_VERSION);
+    EXPECT_EQ(manager.SizeForTesting(), 0U);
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/vchunk_metadata_test.cpp b/mooncake-store/tests/vchunk_metadata_test.cpp
new file mode 100644
index 0000000000..e98c1e5c45
--- /dev/null
+++ b/mooncake-store/tests/vchunk_metadata_test.cpp
@@ -0,0 +1,141 @@
+#include "vchunk_metadata.h"
+
+#include <gtest/gtest.h>
+
+#include <limits>
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace mooncake {
+namespace {
+
+VChunkMetadataRecord MakeValidRecord() {
+    VChunkMetadataRecord record;
+    record.vchunk_id = "vchunk-1";
+    record.tenant_id = "tenant-1";
+    record.key = "key-1";
+    record.total_size = 10U * 1024U;
+    record.slice_count = 3;
+    record.slice_size_level = VCSliceSizeLevel::k4K;
+    record.row_size = 2;
+    record.status = VChunkStatus::CREATING;
+    record.created_at_ms = 100;
+    record.last_updated_at_ms = 100;
+    record.slices = {
+        VCSliceDescriptor{0, "segment-a", 0, 4096, 4096,
+                          VCSliceStatus::PENDING, 0},
+        VCSliceDescriptor{1, "segment-b", 0, 4096, 4096,
+                          VCSliceStatus::PENDING, 0},
+        VCSliceDescriptor{2, "segment-a", 4096, 2048, 4096,
+                          VCSliceStatus::PENDING, 0},
+    };
+    return record;
+}
+
+TEST(VChunkMetadataTest, AcceptsValidLayout) {
+    EXPECT_EQ(ValidateVChunkMetadata(MakeValidRecord(), VChunkConfig{}),
+              ErrorCode::OK);
+}
+
+TEST(VChunkMetadataTest, RoundTripsStableRecord) {
+    const auto original = MakeValidRecord();
+    auto serialized = SerializeVChunkMetadata(original, VChunkConfig{});
+    ASSERT_TRUE(serialized.has_value());
+
+    auto restored =
+        DeserializeVChunkMetadata(serialized.value(), VChunkConfig{});
+    ASSERT_TRUE(restored.has_value());
+    EXPECT_EQ(restored->schema_version, original.schema_version);
+    EXPECT_EQ(restored->vchunk_id, original.vchunk_id);
+    EXPECT_EQ(restored->tenant_id, original.tenant_id);
+    EXPECT_EQ(restored->key, original.key);
+    EXPECT_EQ(restored->total_size, original.total_size);
+    EXPECT_EQ(restored->slices.size(), original.slices.size());
+    EXPECT_EQ(restored->slices.back().logical_length, 2048U);
+    EXPECT_EQ(restored->created_at_ms, 100);
+}
+
+TEST(VChunkMetadataTest, RejectsUnsupportedSchema) {
+    auto record = MakeValidRecord();
+    record.schema_version = kVChunkMetadataSchemaVersion + 1;
+    EXPECT_EQ(ValidateVChunkMetadata(record, VChunkConfig{}),
+              ErrorCode::INVALID_VERSION);
+}
+
+TEST(VChunkMetadataTest, RejectsGapsAndDuplicateSegmentsWithinRow) {
+    auto record = MakeValidRecord();
+    record.slices[1].slice_index = 3;
+    EXPECT_EQ(ValidateVChunkMetadata(record, VChunkConfig{}),
+              ErrorCode::INVALID_PARAMS);
+
+    record = MakeValidRecord();
+    record.slices[1].target_segment_name = "segment-a";
+    EXPECT_EQ(ValidateVChunkMetadata(record, VChunkConfig{}),
+              ErrorCode::INVALID_PARAMS);
+}
+
+TEST(VChunkMetadataTest, RejectsIncorrectCoverageAndAllocation) {
+    auto record = MakeValidRecord();
+    record.slices.back().logical_length = 1024;
+    EXPECT_EQ(ValidateVChunkMetadata(record, VChunkConfig{}),
+              ErrorCode::INVALID_PARAMS);
+
+    record = MakeValidRecord();
+    record.slices.back().allocated_length = 1024;
+    EXPECT_EQ(ValidateVChunkMetadata(record, VChunkConfig{}),
+              ErrorCode::INVALID_PARAMS);
+}
+
+TEST(VChunkMetadataTest, RejectsOffsetOverflowAndRetryOverflow) {
+    auto record = MakeValidRecord();
+    record.slices[0].target_offset =
+        std::numeric_limits<uint64_t>::max() - 1024;
+    EXPECT_EQ(ValidateVChunkMetadata(record, VChunkConfig{}),
+              ErrorCode::INVALID_PARAMS);
+
+    record = MakeValidRecord();
+    record.slices[0].retry_count = VChunkConfig{}.max_slice_retry + 1;
+    EXPECT_EQ(ValidateVChunkMetadata(record, VChunkConfig{}),
+              ErrorCode::INVALID_PARAMS);
+}
+
+TEST(VChunkMetadataTest, EnforcesMetadataSizeLimit) {
+    auto config = VChunkConfig{};
+    config.max_metadata_bytes = 8;
+    auto serialized = SerializeVChunkMetadata(MakeValidRecord(), config);
+    ASSERT_FALSE(serialized.has_value());
+    EXPECT_EQ(serialized.error(), ErrorCode::BUFFER_OVERFLOW);
+}
+
+TEST(VChunkMetadataTest, RejectsCorruptedBytes) {
+    auto serialized =
+        SerializeVChunkMetadata(MakeValidRecord(), VChunkConfig{});
+    ASSERT_TRUE(serialized.has_value());
+    serialized->pop_back();
+
+    auto restored =
+        DeserializeVChunkMetadata(serialized.value(), VChunkConfig{});
+    EXPECT_FALSE(restored.has_value());
+    EXPECT_EQ(restored.error(), ErrorCode::INVALID_PARAMS);
+}
+
+TEST(VChunkMetadataTest, RuntimeStateTransitionsAreValidated) {
+    VChunkMetadata metadata(MakeValidRecord());
+    EXPECT_EQ(metadata.TransitionTo(VChunkStatus::ACTIVE, 200), ErrorCode::OK);
+    EXPECT_EQ(metadata.TransitionTo(VChunkStatus::CREATING, 300),
+              ErrorCode::INVALID_PARAMS);
+    EXPECT_EQ(metadata.TransitionTo(VChunkStatus::RELEASING, 199),
+              ErrorCode::INVALID_PARAMS);
+    EXPECT_EQ(metadata.TransitionTo(VChunkStatus::RELEASING, 300),
+              ErrorCode::OK);
+    EXPECT_EQ(metadata.TransitionTo(VChunkStatus::RELEASED, 400),
+              ErrorCode::OK);
+
+    const auto snapshot = metadata.Snapshot();
+    EXPECT_EQ(snapshot.status, VChunkStatus::RELEASED);
+    EXPECT_EQ(snapshot.last_updated_at_ms, 400);
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/vchunk_test_allocator.h b/mooncake-store/tests/vchunk_test_allocator.h
new file mode 100644
index 0000000000..d6834f3c0e
--- /dev/null
+++ b/mooncake-store/tests/vchunk_test_allocator.h
@@ -0,0 +1,59 @@
+#pragma once
+
+#include <atomic>
+#include <cstddef>
+#include <cstdint>
+#include <memory>
+#include <string>
+
+#include "allocator.h"
+
+namespace mooncake::test {
+
+class VChunkTestAllocator
+    : public BufferAllocatorBase,
+      public std::enable_shared_from_this<VChunkTestAllocator> {
+   public:
+    VChunkTestAllocator(std::string segment_name, uintptr_t base,
+                        size_t capacity)
+        : segment_name_(std::move(segment_name)),
+          base_(base),
+          capacity_(capacity) {}
+
+    std::unique_ptr<AllocatedBuffer> allocate(size_t size) override {
+        size_t current = used_.load();
+        while (current <= capacity_ && size <= capacity_ - current) {
+            if (used_.compare_exchange_weak(current, current + size)) {
+                const auto offset = next_offset_.fetch_add(size);
+                return std::make_unique<AllocatedBuffer>(
+                    shared_from_this(), reinterpret_cast<void*>(base_ + offset),
+                    size);
+            }
+        }
+        return nullptr;
+    }
+
+    void deallocate(AllocatedBuffer* handle) override {
+        used_.fetch_sub(handle->size());
+    }
+
+    size_t capacity() const override { return capacity_; }
+    size_t size() const override { return used_.load(); }
+    std::string getSegmentName() const override { return segment_name_; }
+    std::string getTransportEndpoint() const override {
+        return segment_name_;
+    }
+    size_t getLargestFreeRegion() const override {
+        const auto used = used_.load();
+        return used < capacity_ ? capacity_ - used : 0;
+    }
+
+   private:
+    std::string segment_name_;
+    uintptr_t base_;
+    size_t capacity_;
+    std::atomic<size_t> used_{0};
+    std::atomic<size_t> next_offset_{0};
+};
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/vchunk_transfer_engine_test.cpp b/mooncake-store/tests/vchunk_transfer_engine_test.cpp
new file mode 100644
index 0000000000..ccaa57f388
--- /dev/null
+++ b/mooncake-store/tests/vchunk_transfer_engine_test.cpp
@@ -0,0 +1,98 @@
+#include "vchunk_transfer_engine.h"
+
+#include <gtest/gtest.h>
+
+#include <array>
+#include <string>
+
+namespace mooncake {
+namespace {
+
+VChunkMetadataRecord MakeRecord() {
+    VChunkMetadataRecord record;
+    record.vchunk_id = "id";
+    record.tenant_id = "tenant";
+    record.key = "key";
+    record.total_size = 4096 + 17;
+    record.slice_count = 2;
+    record.slice_size_level = VCSliceSizeLevel::k4K;
+    record.row_size = 2;
+    record.status = VChunkStatus::CREATING;
+    record.created_at_ms = 1;
+    record.last_updated_at_ms = 1;
+    record.slices = {
+        {0, "a", 1000, 4096, 4096, VCSliceStatus::PENDING, 0},
+        {1, "b", 2000, 17, 4096, VCSliceStatus::PENDING, 0}};
+    return record;
+}
+
+TEST(VChunkTransferEngineTest, BuildsAllRequestsBeforeSubmission) {
+    auto record = MakeRecord();
+    std::array<char, 4096 + 17> buffer{};
+    int resolutions = 0;
+    auto requests = BuildVChunkTransferRequests(
+        record, buffer.data(), buffer.size(), TransferRequest::WRITE,
+        [&](const std::string& name)
+            -> tl::expected<SegmentHandle, ErrorCode> {
+            ++resolutions;
+            return name == "a" ? 11 : 22;
+        });
+    ASSERT_TRUE(requests.has_value());
+    ASSERT_EQ(requests->size(), 2U);
+    EXPECT_EQ(resolutions, 2);
+    EXPECT_EQ((*requests)[0].source, buffer.data());
+    EXPECT_EQ((*requests)[0].target_id, 11U);
+    EXPECT_EQ((*requests)[0].target_offset, 1000U);
+    EXPECT_EQ((*requests)[0].length, 4096U);
+    EXPECT_EQ((*requests)[1].source, buffer.data() + 4096);
+    EXPECT_EQ((*requests)[1].target_id, 22U);
+    EXPECT_EQ((*requests)[1].length, 17U);
+}
+
+TEST(VChunkTransferEngineTest, RejectsAnyUnresolvableSliceAsAWhole) {
+    auto record = MakeRecord();
+    std::array<char, 4096 + 17> buffer{};
+    auto requests = BuildVChunkTransferRequests(
+        record, buffer.data(), buffer.size(), TransferRequest::READ,
+        [](const std::string& name)
+            -> tl::expected<SegmentHandle, ErrorCode> {
+            if (name == "b") {
+                return tl::make_unexpected(ErrorCode::SEGMENT_NOT_FOUND);
+            }
+            return 11;
+        });
+    ASSERT_FALSE(requests.has_value());
+    EXPECT_EQ(requests.error(), ErrorCode::SEGMENT_NOT_FOUND);
+}
+
+TEST(VChunkTransferEngineTest, ReusesHandleWithinOneSegment) {
+    auto record = MakeRecord();
+    record.slices[1].target_segment_name = "a";
+    record.row_size = 1;
+    std::array<char, 4096 + 17> buffer{};
+    int resolutions = 0;
+    auto requests = BuildVChunkTransferRequests(
+        record, buffer.data(), buffer.size(), TransferRequest::WRITE,
+        [&](const std::string&)
+            -> tl::expected<SegmentHandle, ErrorCode> {
+            ++resolutions;
+            return 11;
+        });
+    ASSERT_TRUE(requests.has_value());
+    EXPECT_EQ(resolutions, 1);
+}
+
+TEST(VChunkTransferEngineTest, RejectsUnknownMetadataVersion) {
+    auto record = MakeRecord();
+    record.schema_version = kVChunkMetadataSchemaVersion + 1;
+    std::array<char, 4096 + 17> buffer{};
+    auto requests = BuildVChunkTransferRequests(
+        record, buffer.data(), buffer.size(), TransferRequest::WRITE,
+        [](const std::string&)
+            -> tl::expected<SegmentHandle, ErrorCode> { return 11; });
+    ASSERT_FALSE(requests.has_value());
+    EXPECT_EQ(requests.error(), ErrorCode::INVALID_VERSION);
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-wheel/mooncake/io_pattern_bridge.py b/mooncake-wheel/mooncake/io_pattern_bridge.py
new file mode 100644
index 0000000000..bdce2f7da0
--- /dev/null
+++ b/mooncake-wheel/mooncake/io_pattern_bridge.py
@@ -0,0 +1,89 @@
+"""Framework-neutral, non-blocking CFM metric bridges.
+
+CFM is an embedded component of every SubMaster and is reached over the
+SubMaster's ordinary Mooncake RPC endpoint; there is no separate CFM Master
+endpoint and no auth token to obtain. A deployment wires ``report`` to a
+client that resolves the owning SubMaster of each observed key through the CVM
+mapping, aggregates observations per SubMaster, and delivers them to that
+SubMaster's CFM receiver.
+
+The vLLM connector accepts these objects through ``vllm_config``.  SGLang's
+HiCache integration can instantiate :class:`SglangHiCacheIoPatternBridge` at
+its request-finished and prefix-match hooks without depending on vLLM.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from queue import Empty, Full, Queue
+from threading import Event, Thread
+from typing import Any
+
+
+MetricSink = Callable[[Mapping[str, Any]], None]
+
+
+class BatchedIoPatternBridge:
+    """Bounded asynchronous bridge to a CFM metric reporter.
+
+    ``report`` receives complete records (for example, a CVM ownership-aware
+    CFM client method such as ``CfmOwnershipClient.ReportMetricBatch``).
+    Back pressure drops metrics instead of delaying inference.
+    """
+
+    def __init__(self, report: MetricSink, capacity: int = 4096) -> None:
+        self._report = report
+        self._queue: Queue[dict[str, Any]] = Queue(maxsize=capacity)
+        self._stopping = Event()
+        self._worker = Thread(target=self._run, name="io-pattern-cfm",
+                              daemon=True)
+        self._worker.start()
+        self.dropped = 0
+
+    def report_inference_metrics(self, **metrics: Any) -> None:
+        try:
+            self._queue.put_nowait(dict(metrics))
+        except Full:
+            self.dropped += 1
+
+    def close(self) -> None:
+        self._stopping.set()
+        self._worker.join(timeout=1.0)
+
+    def _run(self) -> None:
+        while not self._stopping.is_set() or not self._queue.empty():
+            try:
+                metrics = self._queue.get(timeout=0.1)
+            except Empty:
+                continue
+            try:
+                self._report(metrics)
+            except Exception:
+                # A failed CFM report must remain isolated from inference.
+                self.dropped += 1
+
+
+class SglangHiCacheIoPatternBridge(BatchedIoPatternBridge):
+    """Adapter for SGLang HiCache request and prefix-match hooks.
+
+    ``layout`` must be the active ``--hicache-mem-layout`` value, normally
+    ``layer_first``, ``page_first`` or ``page_first_direct``.
+    """
+
+    def request_finished(self, *, session_id: str, token_count: int,
+                         prefix_depth: int, prefix_fanout: int,
+                         match_length: int, continuous_prefix_length: int,
+                         recompute_cost: float, request_priority: int = 0,
+                         layout: str = "layer_first", layout_group: int = 0) -> None:
+        self.report_inference_metrics(
+            session_id=session_id,
+            token_count=token_count,
+            prefix_depth=prefix_depth,
+            prefix_fanout=prefix_fanout,
+            match_length=match_length,
+            continuous_prefix_length=continuous_prefix_length,
+            recompute_cost=recompute_cost,
+            request_priority=request_priority,
+            layout=layout,
+            layout_group=layout_group,
+        )
diff --git a/mooncake-wheel/mooncake/mooncake_connector_v1.py b/mooncake-wheel/mooncake/mooncake_connector_v1.py
index 18873b38fc..79a9b721ae 100644
--- a/mooncake-wheel/mooncake/mooncake_connector_v1.py
+++ b/mooncake-wheel/mooncake/mooncake_connector_v1.py
@@ -17,7 +17,7 @@
 from dataclasses import dataclass
 from queue import Queue
 from os import getenv
-from typing import TYPE_CHECKING, Any, Optional
+from typing import TYPE_CHECKING, Any, Callable, Optional
 
 import msgspec
 import numpy as np
@@ -71,6 +71,31 @@
 logger = init_logger(__name__)
 
 
+class IoPatternBridge:
+    """Optional connector-side bridge for IO Pattern metric reporting.
+
+    Deployments may attach an object implementing ``report_inference_metrics``
+    to ``vllm_config``. The connector remains usable when it is absent.
+    """
+
+    def report_inference_metrics(self, **metrics: Any) -> None:
+        raise NotImplementedError
+
+
+class CallbackIoPatternBridge(IoPatternBridge):
+    """Concrete bridge that forwards complete metric records to a CFM adapter.
+
+    The callback is deliberately injected by the deployment so this connector
+    stays independent of a particular Python/C++ RPC binding.
+    """
+
+    def __init__(self, report: Callable[..., None]) -> None:
+        self._report = report
+
+    def report_inference_metrics(self, **metrics: Any) -> None:
+        self._report(**metrics)
+
+
 class MooncakeAgentMetadata(
         msgspec.Struct,
         omit_defaults=True,  # type: ignore[call-arg]
@@ -131,6 +156,8 @@ def __init__(self, vllm_config: VllmConfig, role: KVConnectorRole):
         assert vllm_config.kv_transfer_config.engine_id is not None
         super().__init__(vllm_config, role)
         self.engine_id: EngineId = vllm_config.kv_transfer_config.engine_id
+        self.io_pattern_bridge: Optional[IoPatternBridge] = getattr(
+            vllm_config, "io_pattern_bridge", None)
         
         if role == KVConnectorRole.SCHEDULER:
             self.connector_scheduler: Optional[MooncakeConnectorScheduler] = \
@@ -235,6 +262,12 @@ class MooncakeConnectorScheduler:
     def __init__(self, vllm_config: VllmConfig, engine_id: str):
         self.vllm_config = vllm_config
         self.engine_id: EngineId = engine_id
+        self.io_pattern_bridge: Optional[IoPatternBridge] = getattr(
+            vllm_config, "io_pattern_bridge", None)
+        # Kept on the scheduler, which owns all three hook points below.
+        # Each request contributes partial observations until completion.
+        self._io_pattern_metrics: dict[ReqId, dict[str, Any]] = {}
+        self.io_pattern_layout = get_kv_cache_layout()
         self.side_channel_host = get_ip()
         self.side_channel_port = get_mooncake_side_channel_port(vllm_config)
 
@@ -277,6 +310,11 @@ def get_num_new_matched_tokens(
             # Remote prefill: get all prompt blocks from remote.
             count = len(request.prompt_token_ids) - num_computed_tokens
             if count > 0:
+                self._io_pattern_metrics.setdefault(request.request_id, {}).update(
+                    match_length=count,
+                    continuous_prefix_length=count,
+                    token_count=len(request.prompt_token_ids),
+                )
                 return count, True
 
         # No remote prefill for this request.
@@ -295,6 +333,12 @@ def update_state_after_alloc(self, request: "Request",
         if not params:
             return
 
+        self._io_pattern_metrics.setdefault(request.request_id, {}).update(
+            prefix_depth=params.get("prefix_depth", len(blocks.get_unhashed_block_ids())),
+            prefix_fanout=params.get("prefix_fanout", 0),
+            continuous_prefix_length=num_external_tokens,
+        )
+
         if params.get("do_remote_prefill"):
             assert self.kv_role != "kv_producer"
             if all(p in params for p in ("remote_host", "remote_port")):
@@ -357,7 +401,29 @@ def request_finished(
             "MooncakeConnector request_finished, request_status=%s, "
             "kv_transfer_params=%s", request.status, params)
         if not params:
+            # A request may finish before allocation; discard any partial
+            # observation so aborted requests cannot accumulate indefinitely.
+            self._io_pattern_metrics.pop(request.request_id, None)
             return False, None
+        if self.io_pattern_bridge is not None:
+            try:
+                metrics = self._io_pattern_metrics.pop(request.request_id, {})
+                token_count = metrics.get("token_count", len(block_ids))
+                self.io_pattern_bridge.report_inference_metrics(
+                    session_id=request.request_id,
+                    token_count=token_count,
+                    prefix_depth=metrics.get("prefix_depth", params.get("prefix_depth", 0)),
+                    prefix_fanout=metrics.get("prefix_fanout", params.get("prefix_fanout", 0)),
+                    match_length=metrics.get("match_length", params.get("match_length", 0)),
+                    continuous_prefix_length=metrics.get(
+                        "continuous_prefix_length", params.get("continuous_prefix_length", 0)),
+                    recompute_cost=params.get("recompute_cost", float(token_count)),
+                    request_priority=getattr(request, "priority", 0),
+                    layout=self.io_pattern_layout,
+                    layout_group=params.get("layout_group", 0),
+                )
+            except Exception:  # metrics must never affect the data path
+                logger.debug("IO Pattern metric report failed", exc_info=True)
 
         if params.get("do_remote_prefill"):
             # If do_remote_prefill is still True when the request is finished,