[TENT] Add IntentType enum to Request for Transfer Intent API (#2810)

catyans · 彦纾 · Yanshu · web-flow · commit d409ed8986c2 · 2026-07-10T18:37:43.000+08:00
* [TENT] Add IntentType enum to Request for Transfer Intent API

Define standard intent categories (FOREGROUND_GET, BACKGROUND_PREFETCH,
MIGRATION, CHECKPOINT, WEIGHT_LOADING, STAGING_INTERNAL) so TENT can
identify a request's business semantics before scheduling.

Changes:
- types.h: add IntentType enum class + Request::intent_type field
  (default INTENT_UNSPEC, behavior byte-identical to today)
- pybind.cpp: export IntentType enum, add intent_type/policy_name/
  deadline_ns to Request constructor and as readwrite attributes
- intent_type_test.cpp: 6 gtest cases covering defaults, assignment,
  integer values, field independence, copy, and batch usage

Relates to: TENT roadmap "Transfer Intent API"

* ci: retrigger CI

* fix: keep intent type binding scoped

* test: wire intent type coverage into cmake

---------

Co-authored-by: 彦纾 &lt;wangyanshu.wys@alibaba-inc.com&gt;
Co-authored-by: Yanshu &lt;237344440@qq.com&gt;
diff --git a/mooncake-transfer-engine/tent/include/tent/common/types.h b/mooncake-transfer-engine/tent/include/tent/common/types.h
@@ -66,6 +66,16 @@ inline TransportType c_to_transport_hint(int v) {
     return static_cast<TransportType>(v);
 }
 
+enum class IntentType : int {
+    INTENT_UNSPEC = 0,
+    FOREGROUND_GET,
+    BACKGROUND_PREFETCH,
+    MIGRATION,
+    CHECKPOINT,
+    WEIGHT_LOADING,
+    STAGING_INTERNAL,
+};
+
 struct Request {
     enum OpCode { READ, WRITE };
     OpCode opcode;
@@ -86,6 +96,7 @@ struct Request {
     // (MLU = actual transfer time / available window) on completion; it does
     // not yet drive any admission or scheduling decision. See RFC #2519.
     uint64_t deadline_ns = 0;
+    IntentType intent_type = IntentType::INTENT_UNSPEC;
 };
 
 enum TransferStatusEnum {
diff --git a/mooncake-transfer-engine/tent/src/python/pybind.cpp b/mooncake-transfer-engine/tent/src/python/pybind.cpp
@@ -302,6 +302,16 @@ PYBIND11_MODULE(tent, m) {
         .value("SUNRISE_LINK", TransportType::SUNRISE_LINK)
         .export_values();
 
+    py::enum_<IntentType>(m, "IntentType")
+        .value("INTENT_UNSPEC", IntentType::INTENT_UNSPEC)
+        .value("FOREGROUND_GET", IntentType::FOREGROUND_GET)
+        .value("BACKGROUND_PREFETCH", IntentType::BACKGROUND_PREFETCH)
+        .value("MIGRATION", IntentType::MIGRATION)
+        .value("CHECKPOINT", IntentType::CHECKPOINT)
+        .value("WEIGHT_LOADING", IntentType::WEIGHT_LOADING)
+        .value("STAGING_INTERNAL", IntentType::STAGING_INTERNAL)
+        .export_values();
+
     py::enum_<SegmentInfo::Type>(m, "SegmentInfoType")
         .value("Memory", SegmentInfo::Type::Memory)
         .value("File", SegmentInfo::Type::File)
@@ -324,7 +334,7 @@ PYBIND11_MODULE(tent, m) {
                          size_t length, int priority,
                          TransportType transport_hint,
                          std::optional<std::string> policy_name,
-                         uint64_t deadline_ns) {
+                         uint64_t deadline_ns, IntentType intent_type) {
                  Request r;
                  r.opcode = opcode;
                  r.source = U64ToPtr(source);
@@ -335,13 +345,15 @@ PYBIND11_MODULE(tent, m) {
                  r.transport_hint = transport_hint;
                  r.policy_name = std::move(policy_name);
                  r.deadline_ns = deadline_ns;
+                 r.intent_type = intent_type;
                  return r;
              }),
              py::arg("opcode"), py::arg("source"), py::arg("target_id"),
              py::arg("target_offset"), py::arg("length"),
              py::arg("priority") = PRIO_HIGH,
              py::arg("transport_hint") = TransportType::UNSPEC,
-             py::arg("policy_name") = std::nullopt, py::arg("deadline_ns") = 0)
+             py::arg("policy_name") = std::nullopt, py::arg("deadline_ns") = 0,
+             py::arg("intent_type") = IntentType::INTENT_UNSPEC)
         .def_property(
             "opcode", [](const Request& r) { return r.opcode; },
             [](Request& r, Request::OpCode op) { r.opcode = op; })
@@ -354,7 +366,8 @@ PYBIND11_MODULE(tent, m) {
         .def_readwrite("priority", &Request::priority)
         .def_readwrite("transport_hint", &Request::transport_hint)
         .def_readwrite("policy_name", &Request::policy_name)
-        .def_readwrite("deadline_ns", &Request::deadline_ns);
+        .def_readwrite("deadline_ns", &Request::deadline_ns)
+        .def_readwrite("intent_type", &Request::intent_type);
 
     py::class_<TransferStatus>(m, "TransferStatus")
         .def(py::init<>())
diff --git a/mooncake-transfer-engine/tent/tests/CMakeLists.txt b/mooncake-transfer-engine/tent/tests/CMakeLists.txt
@@ -189,6 +189,13 @@ target_include_directories(tent_transport_hint_test
                            PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
 add_test(NAME tent_transport_hint_test COMMAND tent_transport_hint_test)
 
+add_executable(tent_intent_type_test intent_type_test.cpp)
+target_link_libraries(tent_intent_type_test PRIVATE gtest gtest_main
+                                                    tent_common)
+target_include_directories(tent_intent_type_test
+                           PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+add_test(NAME tent_intent_type_test COMMAND tent_intent_type_test)
+
 # ProgressWorker skeleton test: covers default-off behavior, event-driven
 # progress without poll-failover, and freeBatch races (issue #2116).
 add_executable(tent_progress_worker_test progress_worker_test.cpp)
diff --git a/mooncake-transfer-engine/tent/tests/intent_type_test.cpp b/mooncake-transfer-engine/tent/tests/intent_type_test.cpp
@@ -0,0 +1,95 @@
+// Copyright 2026 KVCache.AI
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// Unit tests for IntentType enum and its integration with Request.
+
+#include <gtest/gtest.h>
+
+#include <vector>
+
+#include "tent/common/types.h"
+
+namespace mooncake {
+namespace tent {
+namespace {
+
+TEST(IntentTypeTest, DefaultIsUnspec) {
+    Request r{};
+    EXPECT_EQ(r.intent_type, IntentType::INTENT_UNSPEC);
+}
+
+TEST(IntentTypeTest, AllValuesAssignable) {
+    Request r{};
+    r.intent_type = IntentType::FOREGROUND_GET;
+    EXPECT_EQ(r.intent_type, IntentType::FOREGROUND_GET);
+    r.intent_type = IntentType::BACKGROUND_PREFETCH;
+    EXPECT_EQ(r.intent_type, IntentType::BACKGROUND_PREFETCH);
+    r.intent_type = IntentType::MIGRATION;
+    EXPECT_EQ(r.intent_type, IntentType::MIGRATION);
+    r.intent_type = IntentType::CHECKPOINT;
+    EXPECT_EQ(r.intent_type, IntentType::CHECKPOINT);
+    r.intent_type = IntentType::WEIGHT_LOADING;
+    EXPECT_EQ(r.intent_type, IntentType::WEIGHT_LOADING);
+    r.intent_type = IntentType::STAGING_INTERNAL;
+    EXPECT_EQ(r.intent_type, IntentType::STAGING_INTERNAL);
+}
+
+TEST(IntentTypeTest, IntegerValues) {
+    EXPECT_EQ(static_cast<int>(IntentType::INTENT_UNSPEC), 0);
+    EXPECT_EQ(static_cast<int>(IntentType::FOREGROUND_GET), 1);
+    EXPECT_EQ(static_cast<int>(IntentType::BACKGROUND_PREFETCH), 2);
+    EXPECT_EQ(static_cast<int>(IntentType::MIGRATION), 3);
+    EXPECT_EQ(static_cast<int>(IntentType::CHECKPOINT), 4);
+    EXPECT_EQ(static_cast<int>(IntentType::WEIGHT_LOADING), 5);
+    EXPECT_EQ(static_cast<int>(IntentType::STAGING_INTERNAL), 6);
+}
+
+TEST(IntentTypeTest, DoesNotAffectOtherFields) {
+    Request r{};
+    r.opcode = Request::READ;
+    r.priority = PRIO_LOW;
+    r.deadline_ns = 12345;
+    r.transport_hint = RDMA;
+    r.intent_type = IntentType::CHECKPOINT;
+
+    EXPECT_EQ(r.opcode, Request::READ);
+    EXPECT_EQ(r.priority, PRIO_LOW);
+    EXPECT_EQ(r.deadline_ns, 12345u);
+    EXPECT_EQ(r.transport_hint, RDMA);
+    EXPECT_EQ(r.intent_type, IntentType::CHECKPOINT);
+}
+
+TEST(IntentTypeTest, CopyPreservesIntentType) {
+    Request r{};
+    r.intent_type = IntentType::WEIGHT_LOADING;
+    Request copy = r;
+    EXPECT_EQ(copy.intent_type, IntentType::WEIGHT_LOADING);
+}
+
+TEST(IntentTypeTest, VectorOfRequests) {
+    std::vector<Request> batch(4);
+    batch[0].intent_type = IntentType::FOREGROUND_GET;
+    batch[1].intent_type = IntentType::BACKGROUND_PREFETCH;
+    batch[2].intent_type = IntentType::MIGRATION;
+    batch[3].intent_type = IntentType::INTENT_UNSPEC;
+
+    EXPECT_EQ(batch[0].intent_type, IntentType::FOREGROUND_GET);
+    EXPECT_EQ(batch[1].intent_type, IntentType::BACKGROUND_PREFETCH);
+    EXPECT_EQ(batch[2].intent_type, IntentType::MIGRATION);
+    EXPECT_EQ(batch[3].intent_type, IntentType::INTENT_UNSPEC);
+}
+
+}  // namespace
+}  // namespace tent
+}  // namespace mooncake
