feat(updates): expose phase as x-medkit-phase vendor extension

SOVD UpdateStatus enum collapses prepare-completed and execute-completed
into a single 'completed' value, leaving clients unable to tell whether
the package is ready for Execute or fully installed. Surface the existing
internal UpdatePhase as a vendor extension on /updates/{id}/status so
consumers can distinguish the two without breaking the standard enum.

- Move UpdatePhase into UpdateStatusInfo and emit it as `x-medkit-phase`
- Keep the standard `status` field unchanged (pending|inProgress|completed|failed)
- Document the extension in docs/api/rest.rst with a non-standard callout
- Unit tests for prepared, executed, and freshly-registered (none) serialization

Author: bburda

docs/api/rest.rst

@@ -1134,6 +1134,7 @@ Without such a plugin, all endpoints return ``501 Not Implemented``.
 
       {
         "status": "inProgress",
+        "x-medkit-phase": "preparing",
         "progress": 65,
         "sub_progress": [
           {"name": "download", "progress": 100},
@@ -1147,6 +1148,13 @@ Without such a plugin, all endpoints return ``501 Not Implemented``.
    so this endpoint returns ``200`` with ``{"status": "pending"}`` immediately after
    registration, before any ``prepare`` or ``execute`` call.
 
+   **Vendor extension ``x-medkit-phase``** (non-standard, SOVD-compatible):
+   ``none``, ``preparing``, ``prepared``, ``executing``, ``executed``,
+   ``failed``, ``deleting``. Differentiates "prepare completed" (``status``
+   ``completed`` + ``x-medkit-phase`` ``prepared``) from "execute completed"
+   (``status`` ``completed`` + ``x-medkit-phase`` ``executed``). Clients that
+   only consume the standard ``status`` field continue to work unchanged.
+
    When ``status`` is ``failed``, an ``error`` object is included:
 
    .. code-block:: json

src/ros2_medkit_gateway/include/ros2_medkit_gateway/updates/update_manager.hpp

@@ -101,7 +101,6 @@ class UpdateManager {
   void notify_status_change(const std::string & id, const UpdateStatusInfo & status);
 
   struct PackageState {
-    UpdatePhase phase = UpdatePhase::None;
     UpdateStatusInfo status;
     std::future<void> active_task;
   };

src/ros2_medkit_gateway/include/ros2_medkit_gateway/updates/update_types.hpp

@@ -30,9 +30,14 @@ struct UpdateFilter {
   std::optional<std::string> target_version;  // Filter by target version
 };
 
-/// Status of an update operation
+/// Status of an update operation (SOVD-compliant enum values)
 enum class UpdateStatus { Pending, InProgress, Completed, Failed };
 
+/// Lifecycle phase - exposed as SOVD vendor extension `x-medkit-phase`.
+/// Differentiates "prepare completed" from "execute completed" which share
+/// status=completed in the SOVD standard enum.
+enum class UpdatePhase { None, Preparing, Prepared, Executing, Executed, Failed, Deleting };
+
 /// Detailed progress for a sub-step of an update operation
 struct UpdateSubProgress {
   std::string name;
@@ -42,14 +47,12 @@ struct UpdateSubProgress {
 /// Full status information for an update operation
 struct UpdateStatusInfo {
   UpdateStatus status = UpdateStatus::Pending;
+  UpdatePhase phase = UpdatePhase::None;
   std::optional<int> progress;                                 // 0-100
   std::optional<std::vector<UpdateSubProgress>> sub_progress;  // Detailed per-step progress
   std::optional<std::string> error_message;                    // Set when status == Failed
 };
 
-/// Internal phase tracking for update lifecycle
-enum class UpdatePhase { None, Preparing, Prepared, Executing, Executed, Failed, Deleting };
-
 /// Error codes for backend return values
 enum class UpdateBackendError {
   NotFound,       // Package does not exist
@@ -91,7 +94,30 @@ class UpdateProgressReporter {
   std::mutex & mutex_;
 };
 
-/// Serialize UpdateStatusInfo to SOVD-compliant JSON
+/// Serialize UpdatePhase to its `x-medkit-phase` string value.
+inline const char * update_phase_to_string(UpdatePhase phase) {
+  switch (phase) {
+    case UpdatePhase::None:
+      return "none";
+    case UpdatePhase::Preparing:
+      return "preparing";
+    case UpdatePhase::Prepared:
+      return "prepared";
+    case UpdatePhase::Executing:
+      return "executing";
+    case UpdatePhase::Executed:
+      return "executed";
+    case UpdatePhase::Failed:
+      return "failed";
+    case UpdatePhase::Deleting:
+      return "deleting";
+  }
+  return "none";
+}
+
+/// Serialize UpdateStatusInfo to SOVD-compliant JSON.
+/// Adds vendor extension `x-medkit-phase` to distinguish prepare-completed from
+/// execute-completed (both report SOVD status=completed).
 inline nlohmann::json update_status_to_json(const UpdateStatusInfo & status) {
   nlohmann::json j;
   switch (status.status) {
@@ -108,6 +134,7 @@ inline nlohmann::json update_status_to_json(const UpdateStatusInfo & status) {
       j["status"] = "failed";
       break;
   }
+  j["x-medkit-phase"] = update_phase_to_string(status.phase);
   if (status.progress.has_value()) {
     j["progress"] = *status.progress;
   }

src/ros2_medkit_gateway/src/updates/update_manager.cpp

@@ -113,8 +113,8 @@ tl::expected<void, UpdateError> UpdateManager::register_update(const nlohmann::j
   auto & state_ptr = states_[id];
   if (!state_ptr) {
     state_ptr = std::make_unique<PackageState>();
-    state_ptr->phase = UpdatePhase::None;
-    state_ptr->status = UpdateStatusInfo{UpdateStatus::Pending, std::nullopt, std::nullopt, std::nullopt};
+    state_ptr->status =
+        UpdateStatusInfo{UpdateStatus::Pending, UpdatePhase::None, std::nullopt, std::nullopt, std::nullopt};
   }
   return {};
 }
@@ -139,11 +139,11 @@ tl::expected<void, UpdateError> UpdateManager::delete_update(const std::string &
         it->second->active_task.wait();
       }
       // Mark as deleting so no new operations can start on this package
-      it->second->phase = UpdatePhase::Deleting;
+      it->second->status.phase = UpdatePhase::Deleting;
     } else {
       // Create sentinel to prevent concurrent start_prepare
       states_[id] = std::make_unique<PackageState>();
-      states_[id]->phase = UpdatePhase::Deleting;
+      states_[id]->status.phase = UpdatePhase::Deleting;
     }
   }
 
@@ -157,7 +157,7 @@ tl::expected<void, UpdateError> UpdateManager::delete_update(const std::string &
     if (had_state) {
       auto it = states_.find(id);
       if (it != states_.end() && it->second) {
-        it->second->phase = UpdatePhase::Failed;
+        it->second->status.phase = UpdatePhase::Failed;
       }
     } else {
       // Remove the sentinel we created - package never had state before
@@ -203,12 +203,12 @@ tl::expected<void, UpdateError> UpdateManager::start_prepare(const std::string &
     state_ptr = std::make_unique<PackageState>();
   }
 
-  if (state_ptr->phase == UpdatePhase::Deleting) {
+  if (state_ptr->status.phase == UpdatePhase::Deleting) {
     return tl::make_unexpected(UpdateError{UpdateErrorCode::Deleting, "Package is being deleted"});
   }
 
-  state_ptr->phase = UpdatePhase::Preparing;
-  state_ptr->status = UpdateStatusInfo{UpdateStatus::Pending, std::nullopt, std::nullopt, std::nullopt};
+  state_ptr->status =
+      UpdateStatusInfo{UpdateStatus::Pending, UpdatePhase::Preparing, std::nullopt, std::nullopt, std::nullopt};
   state_ptr->active_task = std::async(std::launch::async, &UpdateManager::run_prepare, this, id);
   return {};
 }
@@ -229,7 +229,7 @@ tl::expected<void, UpdateError> UpdateManager::start_execute(const std::string &
   }
 
   auto it = states_.find(id);
-  if (it == states_.end() || !it->second || it->second->phase != UpdatePhase::Prepared) {
+  if (it == states_.end() || !it->second || it->second->status.phase != UpdatePhase::Prepared) {
     return tl::make_unexpected(UpdateError{UpdateErrorCode::NotPrepared, "Package must be prepared before execution"});
   }
   if (is_task_active(id)) {
@@ -238,8 +238,8 @@ tl::expected<void, UpdateError> UpdateManager::start_execute(const std::string &
   }
 
   auto & state = *it->second;
-  state.phase = UpdatePhase::Executing;
-  state.status = UpdateStatusInfo{UpdateStatus::Pending, std::nullopt, std::nullopt, std::nullopt};
+  state.status =
+      UpdateStatusInfo{UpdateStatus::Pending, UpdatePhase::Executing, std::nullopt, std::nullopt, std::nullopt};
   state.active_task = std::async(std::launch::async, &UpdateManager::run_execute, this, id);
   return {};
 }
@@ -273,12 +273,12 @@ tl::expected<void, UpdateError> UpdateManager::start_automated(const std::string
     state_ptr = std::make_unique<PackageState>();
   }
 
-  if (state_ptr->phase == UpdatePhase::Deleting) {
+  if (state_ptr->status.phase == UpdatePhase::Deleting) {
     return tl::make_unexpected(UpdateError{UpdateErrorCode::Deleting, "Package is being deleted"});
   }
 
-  state_ptr->phase = UpdatePhase::Preparing;
-  state_ptr->status = UpdateStatusInfo{UpdateStatus::Pending, std::nullopt, std::nullopt, std::nullopt};
+  state_ptr->status =
+      UpdateStatusInfo{UpdateStatus::Pending, UpdatePhase::Preparing, std::nullopt, std::nullopt, std::nullopt};
   state_ptr->active_task = std::async(std::launch::async, &UpdateManager::run_automated, this, id);
   return {};
 }
@@ -321,11 +321,11 @@ void UpdateManager::run_prepare(const std::string & id) {
       std::lock_guard<std::mutex> lock(mutex_);
       if (result) {
         state->status.status = UpdateStatus::Completed;
-        state->phase = UpdatePhase::Prepared;
+        state->status.phase = UpdatePhase::Prepared;
       } else {
         state->status.status = UpdateStatus::Failed;
         state->status.error_message = result.error().message;
-        state->phase = UpdatePhase::Failed;
+        state->status.phase = UpdatePhase::Failed;
       }
       snapshot = state->status;
     }
@@ -338,7 +338,7 @@ void UpdateManager::run_prepare(const std::string & id) {
       if (it != states_.end() && it->second) {
         it->second->status.status = UpdateStatus::Failed;
         it->second->status.error_message = std::string("Exception: ") + e.what();
-        it->second->phase = UpdatePhase::Failed;
+        it->second->status.phase = UpdatePhase::Failed;
         snapshot = it->second->status;
       }
     }
@@ -351,7 +351,7 @@ void UpdateManager::run_prepare(const std::string & id) {
       if (it != states_.end() && it->second) {
         it->second->status.status = UpdateStatus::Failed;
         it->second->status.error_message = "Unknown exception during prepare";
-        it->second->phase = UpdatePhase::Failed;
+        it->second->status.phase = UpdatePhase::Failed;
         snapshot = it->second->status;
       }
     }
@@ -377,11 +377,11 @@ void UpdateManager::run_execute(const std::string & id) {
       std::lock_guard<std::mutex> lock(mutex_);
       if (result) {
         state->status.status = UpdateStatus::Completed;
-        state->phase = UpdatePhase::Executed;
+        state->status.phase = UpdatePhase::Executed;
       } else {
         state->status.status = UpdateStatus::Failed;
         state->status.error_message = result.error().message;
-        state->phase = UpdatePhase::Failed;
+        state->status.phase = UpdatePhase::Failed;
       }
       snapshot = state->status;
     }
@@ -394,7 +394,7 @@ void UpdateManager::run_execute(const std::string & id) {
       if (it != states_.end() && it->second) {
         it->second->status.status = UpdateStatus::Failed;
         it->second->status.error_message = std::string("Exception: ") + e.what();
-        it->second->phase = UpdatePhase::Failed;
+        it->second->status.phase = UpdatePhase::Failed;
         snapshot = it->second->status;
       }
     }
@@ -407,7 +407,7 @@ void UpdateManager::run_execute(const std::string & id) {
       if (it != states_.end() && it->second) {
         it->second->status.status = UpdateStatus::Failed;
         it->second->status.error_message = "Unknown exception during execute";
-        it->second->phase = UpdatePhase::Failed;
+        it->second->status.phase = UpdatePhase::Failed;
         snapshot = it->second->status;
       }
     }
@@ -435,7 +435,7 @@ void UpdateManager::run_automated(const std::string & id) {
         std::lock_guard<std::mutex> lock(mutex_);
         state->status.status = UpdateStatus::Failed;
         state->status.error_message = prep_result.error().message;
-        state->phase = UpdatePhase::Failed;
+        state->status.phase = UpdatePhase::Failed;
         snapshot = state->status;
       }
       notify_status_change(id, snapshot);
@@ -445,7 +445,7 @@ void UpdateManager::run_automated(const std::string & id) {
     // Phase 2: Execute (reset progress for execute phase)
     {
       std::lock_guard<std::mutex> lock(mutex_);
-      state->phase = UpdatePhase::Executing;
+      state->status.phase = UpdatePhase::Executing;
       state->status.progress = std::nullopt;
       state->status.sub_progress = std::nullopt;
     }
@@ -457,11 +457,11 @@ void UpdateManager::run_automated(const std::string & id) {
       std::lock_guard<std::mutex> lock(mutex_);
       if (exec_result) {
         state->status.status = UpdateStatus::Completed;
-        state->phase = UpdatePhase::Executed;
+        state->status.phase = UpdatePhase::Executed;
       } else {
         state->status.status = UpdateStatus::Failed;
         state->status.error_message = exec_result.error().message;
-        state->phase = UpdatePhase::Failed;
+        state->status.phase = UpdatePhase::Failed;
       }
       snapshot = state->status;
     }
@@ -474,7 +474,7 @@ void UpdateManager::run_automated(const std::string & id) {
       if (it != states_.end() && it->second) {
         it->second->status.status = UpdateStatus::Failed;
         it->second->status.error_message = std::string("Exception: ") + e.what();
-        it->second->phase = UpdatePhase::Failed;
+        it->second->status.phase = UpdatePhase::Failed;
         snapshot = it->second->status;
       }
     }
@@ -487,7 +487,7 @@ void UpdateManager::run_automated(const std::string & id) {
       if (it != states_.end() && it->second) {
         it->second->status.status = UpdateStatus::Failed;
         it->second->status.error_message = "Unknown exception during automated update";
-        it->second->phase = UpdatePhase::Failed;
+        it->second->status.phase = UpdatePhase::Failed;
         snapshot = it->second->status;
       }
     }

src/ros2_medkit_gateway/test/test_update_manager.cpp

@@ -599,3 +599,25 @@ TEST(UpdateManagerFailureTest, ExecuteExceptionSetsFailedStatus) {
   manager.reset();
   backend.reset();
 }
+
+TEST(UpdateStatusToJson, SerializesPhaseAsVendorExtension) {
+  UpdateStatusInfo status{UpdateStatus::Completed, UpdatePhase::Prepared, std::nullopt, std::nullopt, std::nullopt};
+  auto j = update_status_to_json(status);
+  EXPECT_EQ(j["status"], "completed");
+  EXPECT_EQ(j["x-medkit-phase"], "prepared");
+}
+
+TEST(UpdateStatusToJson, ExposesExecutedPhaseForTerminalCompletion) {
+  UpdateStatusInfo status{UpdateStatus::Completed, UpdatePhase::Executed, 100, std::nullopt, std::nullopt};
+  auto j = update_status_to_json(status);
+  EXPECT_EQ(j["status"], "completed");
+  EXPECT_EQ(j["x-medkit-phase"], "executed");
+  EXPECT_EQ(j["progress"], 100);
+}
+
+TEST(UpdateStatusToJson, EmitsNonePhaseForFreshlyRegistered) {
+  UpdateStatusInfo status;
+  auto j = update_status_to_json(status);
+  EXPECT_EQ(j["status"], "pending");
+  EXPECT_EQ(j["x-medkit-phase"], "none");
+}