[manager/meta] refactor group spec names

Author: lucky-zzz

docs/api/report_event.md

@@ -62,7 +62,10 @@ unsigned uint64；KVCM 按相同的 64-bit bit pattern 归一化，例如
 使用 uint64 的约定兼容；超出 uint64 或 int64 表示范围、带正号或空白的字符串会被拒绝。
 
 - `medium` 是 block 级属性，例如 `gpu`、`hbm`、`memory`、`disk`；
-- `spec.name` 区分一个 block 内的多个物理组成部分，例如不同 TP、full attention 或 mamba state；
+- `spec.name` 区分一个 block 内的多个物理组成部分，例如 `F0`、`L1` 等 cache group；
+- ADD、DELETE 和 SNAPSHOT 中使用的每个 spec name 都必须已在
+  `RegisterInstance.location_spec_infos` 中注册；未注册的 spec 对应 item 返回
+  `INVALID_ARGUMENT`，且不会修改 metadata。同一请求中的其他合法 item 仍可生效；
 - 同一 `block_key` 可以同时存在于多个 medium；
 - 同一 `block_key + medium` 可以包含多个不同的 spec name；
 - 同一 `block_key + medium + spec.name` 是集合语义，不是引用计数。
@@ -249,11 +252,11 @@ InstanceGroup 必须把对应 EventReport storage 配置在
     "medium": "gpu",
     "specs": [
       {
-        "name": "full_attention:group=0:tp=0",
+        "name": "F0",
         "uri": "event_report://10.0.0.8:9600/gpu/123?size=4096"
       },
       {
-        "name": "mamba_state:group=0:tp=0",
+        "name": "L1",
         "uri": "event_report://10.0.0.8:9600/gpu/123?size=1024"
       }
     ]
@@ -266,7 +269,7 @@ InstanceGroup 必须把对应 EventReport storage 配置在
 - `block_key` 必须是可解析的十进制整数文本；
 - `medium` 非空，且不能包含 location id 分隔符 `#`；
 - `specs` 非空；
-- 每个 `spec.name` 非空，且同一事件内不能重复；
+- 每个 `spec.name` 非空、已在 `RegisterInstance.location_spec_infos` 中注册，且同一事件内不能重复；
 - 每个 URI 必须合法；
 - 客户端 URI 不能带 `s_version`；
 - 旧字段 `block_add.uri` 已废弃，只有 `specs` 生效。
@@ -288,7 +291,7 @@ InstanceGroup 必须把对应 EventReport storage 配置在
     "block_key": "123",
     "medium": "gpu",
     "spec_names": [
-      "full_attention:group=0:tp=0"
+      "F0"
     ]
   }
 }
@@ -298,7 +301,7 @@ InstanceGroup 必须把对应 EventReport storage 配置在
 
 - `block_key`、`medium` 非空且合法；`medium` 不能包含 location id 分隔符 `#`；
 - `spec_names` 非空；
-- spec name 非空且同一事件内不能重复。
+- spec name 非空、已在 `RegisterInstance.location_spec_infos` 中注册，且同一事件内不能重复。
 
 行为：
 
@@ -321,11 +324,11 @@ InstanceGroup 必须把对应 EventReport storage 配置在
         "medium": "gpu",
         "specs": [
           {
-            "name": "full_attention:group=0:tp=0",
+            "name": "F0",
             "uri": "event_report://10.0.0.8:9600/gpu/123?size=4096"
           },
           {
-            "name": "mamba_state:group=0:tp=0",
+            "name": "L1",
             "uri": "event_report://10.0.0.8:9600/gpu/123?size=1024"
           }
         ]
@@ -335,7 +338,7 @@ InstanceGroup 必须把对应 EventReport storage 配置在
         "medium": "memory",
         "specs": [
           {
-            "name": "full_attention:group=0:tp=0",
+            "name": "F0",
             "uri": "event_report://10.0.0.8:9600/memory/456"
           }
         ]
@@ -353,7 +356,8 @@ Snapshot 的完整性规则：
 - 同一 `block_key + medium` 只能出现一次；
 - 相同 block key 可以出现在不同 medium；
 - `medium` 不能包含 location id 分隔符 `#`；
-- 每个 block 的 specs 必须非空，且 spec name 不能重复；
+- 每个 block 的 specs 必须非空，且 spec name 必须已在
+  `RegisterInstance.location_spec_infos` 中注册并且不能重复；
 - `blocks=[]` 表示该 reporter 当前没有任何 cache，会异步清理其全部旧 location。
 
 Snapshot 的更新语义：

integration_test/meta_service/test_report_event.py

@@ -352,6 +352,14 @@ def _ensure_instance_registered(cls):
                 },
                 "location_spec_infos": [
                     {"name": "tp0", "size": 1024},
+                    {"name": "mem_spec", "size": 1024},
+                    {"name": "disk_spec", "size": 1024},
+                    {"name": "spec_4096", "size": 1024},
+                    {"name": "spec_8192", "size": 1024},
+                    {"name": "keep_spec", "size": 1024},
+                    {"name": "drop_spec", "size": 1024},
+                    {"name": "l1p5_spec", "size": 1024},
+                    {"name": "l2_spec", "size": 1024},
                 ],
             })
         except Exception as e:

kv_cache_manager/manager/cache_manager.cc

@@ -2789,6 +2789,21 @@ ErrorCode CacheManager::ReportEvent(RequestContext *request_context,
         return EC_INSTANCE_NOT_EXIST;
     }
 
+    auto instance_info = registry_manager_->GetInstanceInfo(request_context, instance_id);
+    if (!instance_info) {
+        KVCM_LOG_WARN("trace_id [%s] | ReportEvent: instance info not found for instance [%s]",
+                      trace_id.c_str(),
+                      instance_id.c_str());
+        response_status->set_code(proto::meta::INSTANCE_NOT_EXIST);
+        response_status->set_message("instance info not found for instance: " + instance_id);
+        return EC_INSTANCE_NOT_EXIST;
+    }
+    std::unordered_set<std::string_view> registered_spec_names;
+    registered_spec_names.reserve(instance_info->location_spec_infos().size());
+    for (const auto &spec_info : instance_info->location_spec_infos()) {
+        registered_spec_names.insert(spec_info.name());
+    }
+
     const int events_size = request->events_size();
     std::vector<ErrorCode> per_item_ec(events_size, EC_OK);
     DeltaMutationGuard delta_mutations(event_backend, reporter_key);
@@ -3142,7 +3157,8 @@ ErrorCode CacheManager::ReportEvent(RequestContext *request_context,
             }
             std::uint64_t event_total_size = 0;
             for (const auto &spec : params.specs()) {
-                if (params.specs_size() > 1 && !seen_spec_names.insert(std::string_view(spec.name())).second) {
+                if (registered_spec_names.find(spec.name()) == registered_spec_names.end() ||
+                    (params.specs_size() > 1 && !seen_spec_names.insert(std::string_view(spec.name())).second)) {
                     per_item_ec[i] = EC_BADARGS;
                     break;
                 }
@@ -3232,7 +3248,7 @@ ErrorCode CacheManager::ReportEvent(RequestContext *request_context,
                 seen_spec_names.reserve(params.spec_names_size());
             }
             for (const auto &spec_name : params.spec_names()) {
-                if (spec_name.empty() ||
+                if (spec_name.empty() || registered_spec_names.find(spec_name) == registered_spec_names.end() ||
                     (params.spec_names_size() > 1 && !seen_spec_names.insert(std::string_view(spec_name)).second)) {
                     per_item_ec[i] = EC_BADARGS;
                     break;
@@ -3306,7 +3322,8 @@ ErrorCode CacheManager::ReportEvent(RequestContext *request_context,
                     seen_spec_names.reserve(block.specs_size());
                 }
                 for (const auto &spec : block.specs()) {
-                    if (block.specs_size() > 1 && !seen_spec_names.insert(std::string_view(spec.name())).second) {
+                    if (registered_spec_names.find(spec.name()) == registered_spec_names.end() ||
+                        (block.specs_size() > 1 && !seen_spec_names.insert(std::string_view(spec.name())).second)) {
                         per_item_ec[i] = EC_BADARGS;
                         break;
                     }

kv_cache_manager/manager/meta_searcher.cc

@@ -791,9 +791,54 @@ int64_t ComputePrefixMatchBlocks(const std::vector<std::set<std::string>> &specs
     return prefix_len;
 }
 
-bool IsFullLocationSpecGroup(const LocationSpecGroup &group) {
-    const auto &name = group.name();
-    return name.rfind("full", 0) == 0 || name.rfind("FULL", 0) == 0;
+ErrorCode ClassifySpecGroups(RequestContext *request_context,
+                             const std::vector<LocationSpecGroup> &location_spec_groups,
+                             std::vector<const LocationSpecGroup *> &full_groups,
+                             std::vector<const LocationSpecGroup *> &mamba_state_groups) {
+    full_groups.clear();
+    mamba_state_groups.clear();
+    for (const auto &group : location_spec_groups) {
+        const auto &group_name = group.name();
+        const char category = group_name.empty() ? '?' : group_name.front();
+        switch (category) {
+        case 'F':
+            full_groups.push_back(&group);
+            break;
+        case 'L':
+            mamba_state_groups.push_back(&group);
+            break;
+        case 'W':
+        case 'C':
+        case 'E':
+        case 'X': {
+            std::string error_msg =
+                "unsupported location spec category for QT_PREFIX_MATCH_WITH_MAMBA, group: " + group_name +
+                ", category: " + std::string(1, category);
+            request_context->error_tracer()->AddErrorMsg(error_msg);
+            KVCM_LOG_WARN("%s", error_msg.c_str());
+            return EC_BADARGS;
+        }
+        default: {
+            std::string error_msg =
+                "invalid location spec category for QT_PREFIX_MATCH_WITH_MAMBA, group: " + group_name +
+                ", category: " + std::string(1, category);
+            request_context->error_tracer()->AddErrorMsg(error_msg);
+            KVCM_LOG_WARN("%s", error_msg.c_str());
+            return EC_BADARGS;
+        }
+        }
+    }
+
+    if (full_groups.empty() || mamba_state_groups.empty()) {
+        std::string group_names = Jsonizable::ToJsonString(location_spec_groups);
+        std::string error_msg =
+            full_groups.empty() ? "no full location spec group" : "no mamba state location spec group";
+        error_msg += ", location_spec_groups: " + group_names;
+        request_context->error_tracer()->AddErrorMsg(error_msg);
+        KVCM_LOG_WARN("%s", error_msg.c_str());
+        return EC_BADARGS;
+    }
+    return EC_OK;
 }
 
 bool HasAllLocationSpecGroups(const std::set<std::string> &spec_names,
@@ -1814,21 +1859,9 @@ ErrorCode MetaSearcher::PrefixMatchWithMambaByHost(RequestContext *request_conte
 
     std::vector<const LocationSpecGroup *> full_groups;
     std::vector<const LocationSpecGroup *> mamba_state_groups;
-    for (const auto &group : location_spec_groups) {
-        if (IsFullLocationSpecGroup(group)) {
-            full_groups.push_back(&group);
-        } else {
-            mamba_state_groups.push_back(&group);
-        }
-    }
-    if (full_groups.empty() || mamba_state_groups.empty()) {
-        std::string group_names = Jsonizable::ToJsonString(location_spec_groups);
-        std::string error_msg =
-            full_groups.empty() ? "no full location spec group" : "no mamba state location spec group";
-        error_msg += ", location_spec_groups: " + group_names;
-        request_context->error_tracer()->AddErrorMsg(error_msg);
-        KVCM_LOG_WARN("%s", error_msg.c_str());
-        return EC_BADARGS;
+    auto ec = ClassifySpecGroups(request_context, location_spec_groups, full_groups, mamba_state_groups);
+    if (ec != EC_OK) {
+        return ec;
     }
     if (p2p_host_count == 0) {
         return PrefixMatchWithMambaByHostWithoutP2P(meta_indexer_.get(),