feat(ota_plugin): write manifest fragments + notify gateway on install/uninstall

Without this, OTA-installed apps (obstacle_classifier_v2 after the
Install flow) showed up in the gateway runtime graph but never got
attached to a manifest entity, so the Foxglove tree treated them as
orphans and they never appeared under the turtlebot3 component or in
any function's host list. The catalog said "this update adds the
obstacle_classifier app", the runtime saw the new node, but the
manifest tree stayed unchanged.

Wire the gateway's plugin-side manifest fragment contract:

1. Plugin reads `fragments_dir` from its config (matches the
   gateway's discovery.manifest.fragments_dir param). Empty = legacy
   "no fragments" behavior preserved.
2. set_context() now stores the PluginContext so post-execute we
   can call notify_entities_changed and have the gateway re-merge
   the base manifest with the fragments dir.
3. On Install: render a minimal manifest YAML for the new app
   (id from added_components[0], node_name from x_medkit_executable,
   located on the single turtlebot3 component), atomic-publish via
   tmp-rename per the ManifestManager fragment contract, then
   notify. Gateway picks the entity up; new app shows under
   /components/turtlebot3/hosts and any function that lists it.
4. On Uninstall: drop the fragment file (no-op if the entity was in
   the base manifest, like broken_lidar_legacy). Notify either way
   so the cache stops returning a now-dead app.
5. On Update: no fragment change (same app id, just different
   binary), but still notify so the entity cache rebuilds with the
   new pid.

Adds the dirs to Dockerfile and threads fragments_dir through both
gateway_config.yaml (discovery.manifest.fragments_dir) and the
plugin config block (plugins.ota_update_plugin.fragments_dir) so
they stay in lockstep.

Author: bburda

demos/ota_nav2_sensor_fix/Dockerfile.gateway

@@ -94,6 +94,12 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 COPY --from=builder /ws/install /ws/install
 COPY gateway_config.yaml /etc/ros2_medkit/gateway_config.yaml
 COPY manifest.yaml /etc/ros2_medkit/manifest.yaml
+
+# Pre-create the fragments directory so the gateway's manifest manager
+# scans an existing (empty) dir at boot rather than logging "missing
+# fragments_dir" warnings. Plugin writes / removes yaml files here at
+# OTA install / uninstall time.
+RUN mkdir -p /etc/ros2_medkit/manifest_fragments
 COPY entrypoint.sh /usr/local/bin/entrypoint.sh
 RUN chmod +x /usr/local/bin/entrypoint.sh
 

demos/ota_nav2_sensor_fix/gateway_config.yaml

@@ -26,12 +26,18 @@ ros2_medkit_gateway:
 
     discovery:
       # Hybrid: manifest defines areas/components/apps/functions, runtime
-      # fills in topics/services/params and surfaces OTA-installed nodes
-      # (e.g. obstacle_classifier_v2 after trigger-install.sh) without
-      # needing a manifest entry for them.
+      # fills in topics/services/params, and OTA-deployed apps land via
+      # manifest fragments dropped in fragments_dir below.
       mode: "hybrid"
       manifest_path: "/etc/ros2_medkit/manifest.yaml"
       manifest_strict_validation: false
+      manifest:
+        # ota_update_plugin writes one fragment per Install operation
+        # here and calls notify_entities_changed; the gateway re-merges
+        # the base manifest + every yaml in this dir on each reload.
+        # Path is shared with the plugin via plugins.ota_update_plugin
+        # .fragments_dir below - keep them in lockstep.
+        fragments_dir: "/etc/ros2_medkit/manifest_fragments"
       runtime:
         # Manifest defines components, no need for synthetic ones.
         create_synthetic_components: false
@@ -48,3 +54,6 @@ ros2_medkit_gateway:
     plugins.ota_update_plugin.catalog_url: "http://ota_update_server:9000"
     plugins.ota_update_plugin.staging_dir: "/tmp/ota_staging"
     plugins.ota_update_plugin.install_dir: "/ws/install"
+    # Same path the gateway has under discovery.manifest.fragments_dir.
+    # Plugin drops one yaml per Install and removes it on Uninstall.
+    plugins.ota_update_plugin.fragments_dir: "/etc/ros2_medkit/manifest_fragments"

demos/ota_nav2_sensor_fix/ota_update_plugin/include/ota_update_plugin/ota_update_plugin.hpp

@@ -73,9 +73,22 @@ class OtaUpdatePlugin : public ros2_medkit_gateway::GatewayPlugin, public ros2_m
   void poll_and_register_catalog();
 
  private:
+  // Manifest-fragment helpers. Plugins that deploy new nodes at runtime
+  // are expected to drop a fragment yaml in `fragments_dir_` and then
+  // notify the gateway so its ManifestManager re-merges. Without this
+  // the new app shows up as an "Orphan node (not in manifest)" warn
+  // log and never attaches to the manifest entity tree.
+  tl::expected<void, std::string> write_install_fragment(const std::string & update_id,
+                                                          const nlohmann::json & metadata);
+  tl::expected<void, std::string> remove_install_fragment(const std::string & update_id);
+  void notify_manifest_changed();
+
   std::string catalog_url_;
   std::string staging_dir_;
   std::string install_dir_;
+  std::string fragments_dir_;
+
+  ros2_medkit_gateway::PluginContext * context_{nullptr};
 
   std::mutex mu_;
   std::map<std::string, nlohmann::json> registry_;

demos/ota_nav2_sensor_fix/ota_update_plugin/src/ota_update_plugin.cpp

@@ -16,9 +16,14 @@
 
 #include <cstdio>
 #include <cstdlib>
+#include <cstring>
 #include <filesystem>
+#include <fstream>
 #include <utility>
 
+#include <ros2_medkit_gateway/plugins/entity_change_scope.hpp>
+#include <ros2_medkit_gateway/plugins/plugin_context.hpp>
+
 #include "catalog_client.hpp"
 #include "operation_dispatcher.hpp"
 #include "process_runner.hpp"
@@ -76,12 +81,22 @@ void OtaUpdatePlugin::configure(const nlohmann::json & config) {
   catalog_url_ = config.value("catalog_url", "http://ota_update_server:9000");
   staging_dir_ = config.value("staging_dir", "/tmp/ota_staging");
   install_dir_ = config.value("install_dir", "/ws/install");
+  // Where this plugin drops manifest fragments for OTA-installed apps.
+  // Must equal the path the gateway has configured under
+  // discovery.manifest.fragments_dir, otherwise the gateway won't pick
+  // them up on reload. Empty disables fragment writes (legacy behavior:
+  // installed nodes appear as orphans in the entity tree).
+  fragments_dir_ = config.value("fragments_dir", "");
   if (!catalog_client_) {
     catalog_client_ = std::make_unique<CatalogClient>(catalog_url_);
   }
 }
 
-void OtaUpdatePlugin::set_context(ros2_medkit_gateway::PluginContext & /*context*/) {
+void OtaUpdatePlugin::set_context(ros2_medkit_gateway::PluginContext & context) {
+  // Hold on to the context so post-execute we can ask the gateway to
+  // re-merge manifest fragments and rerun discovery via
+  // notify_entities_changed.
+  context_ = &context;
   poll_and_register_catalog();
 }
 
@@ -245,6 +260,12 @@ tl::expected<void, UpdateBackendErrorInfo> OtaUpdatePlugin::execute(
     if (!sp) {
       return tl::make_unexpected(UpdateBackendErrorInfo{UpdateBackendError::Internal, "spawn failed: " + sp.error()});
     }
+    // Update flow: same app id (the binary swapped in is bound to the
+    // same scan_sensor_node entity as the binary it replaced) - no
+    // manifest fragment to write, but the gateway still needs to
+    // rerun discovery so the new pid / process metadata replaces the
+    // stale entries in the entity cache.
+    notify_manifest_changed();
     reporter.set_progress(100);
     return {};
   }
@@ -267,6 +288,17 @@ tl::expected<void, UpdateBackendErrorInfo> OtaUpdatePlugin::execute(
     if (!sp) {
       return tl::make_unexpected(UpdateBackendErrorInfo{UpdateBackendError::Internal, "spawn failed: " + sp.error()});
     }
+    // Install flow: NEW app entity. Write a manifest fragment so the
+    // gateway picks the new app up under the manifest tree (otherwise
+    // it stays as an "Orphan node (not in manifest)" warn log and
+    // never appears under the turtlebot3 component / Functions
+    // listing). Notify even when fragment write fails - the spawn
+    // already happened and discovery should still see the new node.
+    if (auto fr = write_install_fragment(id, metadata); !fr) {
+      std::fprintf(stderr, "[ota_update_plugin] fragment write failed for %s: %s\n", id.c_str(),
+                   fr.error().c_str());
+    }
+    notify_manifest_changed();
     reporter.set_progress(100);
     return {};
   }
@@ -282,6 +314,16 @@ tl::expected<void, UpdateBackendErrorInfo> OtaUpdatePlugin::execute(
       std::error_code ec;
       fs::remove_all(install_dir_ + "/" + target_package, ec);
     }
+    // Uninstall: drop any fragment we wrote at install time and rerun
+    // discovery so the entity tree no longer lists the now-dead app.
+    // Entities defined in the base manifest stay - fragments only
+    // ADD, they can't remove base-manifest declarations - those
+    // entries just go offline.
+    if (auto fr = remove_install_fragment(id); !fr) {
+      std::fprintf(stderr, "[ota_update_plugin] fragment remove failed for %s: %s\n", id.c_str(),
+                   fr.error().c_str());
+    }
+    notify_manifest_changed();
     reporter.set_progress(100);
     return {};
   }
@@ -293,4 +335,87 @@ tl::expected<bool, UpdateBackendErrorInfo> OtaUpdatePlugin::supports_automated(c
   return false;
 }
 
+namespace {
+
+// Build the YAML body for a single OTA-installed app. We hand-emit the
+// minimal subset the gateway's manifest parser accepts (no quoting
+// edge cases in our generated values, so a yaml-cpp roundtrip would be
+// overkill). The base manifest defines the `turtlebot3` component;
+// fragments only ever add apps onto it.
+std::string render_install_fragment(const std::string & app_id, const std::string & node_name,
+                                    const std::string & description) {
+  std::string out;
+  out += "manifest_version: \"1.0\"\n";
+  out += "apps:\n";
+  out += "  - id: " + app_id + "\n";
+  out += "    name: \"" + app_id + "\"\n";
+  out += "    category: \"ota-installed\"\n";
+  out += "    is_located_on: turtlebot3\n";
+  out += "    description: \"" + description + "\"\n";
+  out += "    ros_binding: { node_name: " + node_name + ", namespace: / }\n";
+  return out;
+}
+
+}  // namespace
+
+tl::expected<void, std::string> OtaUpdatePlugin::write_install_fragment(const std::string & update_id,
+                                                                         const nlohmann::json & metadata) {
+  if (fragments_dir_.empty()) return {};
+
+  const std::string node_name = metadata.value("x_medkit_executable", "");
+  // SOVD ISO 17978-3 reports the target entity via `added_components`
+  // (it's an array; for an OTA install we always have exactly one).
+  std::string app_id;
+  if (metadata.contains("added_components") && metadata["added_components"].is_array()
+      && !metadata["added_components"].empty()) {
+    app_id = metadata["added_components"][0].get<std::string>();
+  }
+  if (node_name.empty() || app_id.empty()) {
+    return tl::make_unexpected(
+        "metadata missing x_medkit_executable / added_components for fragment");
+  }
+  const std::string description = "OTA-installed via " + update_id;
+
+  std::error_code ec;
+  fs::create_directories(fragments_dir_, ec);
+  if (ec) {
+    return tl::make_unexpected("create fragments_dir failed: " + ec.message());
+  }
+
+  const std::string final_path = fragments_dir_ + "/" + update_id + ".yaml";
+  const std::string tmp_path = fragments_dir_ + "/.tmp-" + update_id + ".yaml";
+  // Atomic publish per ManifestManager's fragment contract: write to
+  // tmp, fsync, rename. The gateway's fragment scanner runs on the
+  // notify_entities_changed thread - a half-written file would fail
+  // the manifest reload and roll back the entire merge.
+  {
+    std::ofstream f(tmp_path, std::ios::binary | std::ios::trunc);
+    if (!f) return tl::make_unexpected("open tmp fragment failed: " + tmp_path);
+    f << render_install_fragment(app_id, node_name, description);
+    f.flush();
+    if (!f) return tl::make_unexpected("write tmp fragment failed: " + tmp_path);
+  }
+  if (std::rename(tmp_path.c_str(), final_path.c_str()) != 0) {
+    return tl::make_unexpected("rename fragment failed: " + std::string(std::strerror(errno)));
+  }
+  return {};
+}
+
+tl::expected<void, std::string> OtaUpdatePlugin::remove_install_fragment(const std::string & update_id) {
+  if (fragments_dir_.empty()) return {};
+  std::error_code ec;
+  fs::remove(fragments_dir_ + "/" + update_id + ".yaml", ec);
+  // Missing-file is fine (uninstall of an entity that lived in the
+  // base manifest, never had a fragment); other errors are reported.
+  if (ec && ec != std::errc::no_such_file_or_directory) {
+    return tl::make_unexpected("remove fragment failed: " + ec.message());
+  }
+  return {};
+}
+
+void OtaUpdatePlugin::notify_manifest_changed() {
+  if (!context_) return;
+  context_->notify_entities_changed(ros2_medkit_gateway::EntityChangeScope::full_refresh());
+}
+
 }  // namespace ota_update_plugin