Add hardware.require_live_session fail-fast guard with config parsing, tests, and troubleshooting docs

Author: CameronBrooks11

docs/build.md

@@ -114,6 +114,9 @@ Start the provider for ADPP clients:
 The committed sample config seeds one RLHT and one DCMT device so `Hello`, `WaitReady`,
 `ListDevices`, `DescribeDevice`, and `GetHealth` are testable without real hardware.
 
+If a config sets `hardware.require_live_session: true`, no-hardware builds fail fast at startup.
+Use this for Linux hardware validation profiles to avoid silent config-seeded fallback.
+
 ## Test Taxonomy
 
 Two test executables are produced by every build:

docs/troubleshooting.md

@@ -51,6 +51,22 @@ sudo setfacl -m u:$USER:rw /dev/i2c-1  # or run as root temporarily during dev
 
 Confirm `hardware.bus_path` in your config matches the actual device node.
 
+### Required live session on no-hardware build
+
+If config sets `hardware.require_live_session: true` but the provider binary was built with
+`ANOLIS_PROVIDER_BREAD_ENABLE_HARDWARE=OFF`, startup fails immediately:
+
+```
+[ERROR] hardware.require_live_session=true but provider was built without hardware support ...
+```
+
+Fix by rebuilding with a Linux hardware preset:
+
+```bash
+cmake --preset dev-linux-hardware-release
+cmake --build --preset dev-linux-hardware-release
+```
+
 ---
 
 ## Device Not Responding During Startup

src/config/provider_config.cpp

@@ -69,6 +69,17 @@ int parse_int_value(const YAML::Node &node,
     }
 }
 
+bool parse_bool_value(const YAML::Node &node, const std::string &field_name) {
+    const std::string text = require_scalar(node, field_name);
+    if(text == "true") {
+        return true;
+    }
+    if(text == "false") {
+        return false;
+    }
+    throw std::runtime_error(field_name + " must be true or false");
+}
+
 int parse_address_text(const std::string &text, const std::string &field_name) {
     const int base = (text.size() > 2 && text[0] == '0' &&
                       (text[1] == 'x' || text[1] == 'X'))
@@ -173,9 +184,16 @@ ProviderConfig load_config(const std::string &path) {
         throw std::runtime_error("Missing required section: hardware");
     }
     ensure_map(hardware_node, "hardware");
-    reject_unknown_keys(hardware_node, "hardware", {"bus_path", "query_delay_us", "timeout_ms", "retry_count"});
+    reject_unknown_keys(
+        hardware_node,
+        "hardware",
+        {"bus_path", "require_live_session", "query_delay_us", "timeout_ms", "retry_count"});
 
     config.bus_path = require_scalar(hardware_node["bus_path"], "hardware.bus_path");
+    if(hardware_node["require_live_session"]) {
+        config.require_live_session =
+            parse_bool_value(hardware_node["require_live_session"], "hardware.require_live_session");
+    }
     if(hardware_node["query_delay_us"]) {
         config.query_delay_us = parse_int_value(hardware_node["query_delay_us"], "hardware.query_delay_us", false);
     }
@@ -267,6 +285,7 @@ std::string summarize_config(const ProviderConfig &config) {
     std::ostringstream out;
     out << "provider.name=" << config.provider_name
         << ", hardware.bus_path=" << config.bus_path
+        << ", hardware.require_live_session=" << (config.require_live_session ? "true" : "false")
         << ", hardware.query_delay_us=" << config.query_delay_us
         << ", hardware.timeout_ms=" << config.timeout_ms
         << ", hardware.retry_count=" << config.retry_count

src/config/provider_config.hpp

@@ -26,6 +26,7 @@ struct ProviderConfig {
     std::string config_file_path;
     std::string provider_name = "anolis-provider-bread";
     std::string bus_path;
+    bool require_live_session = false;
     int query_delay_us = 10000;
     int timeout_ms = 100;
     int retry_count = 2;

src/core/runtime_state.cpp

@@ -104,6 +104,12 @@ void initialize(const ProviderConfig &config) {
 
 #else
     // No-hardware path: seed inventory from config.
+    if(config.require_live_session) {
+        throw std::runtime_error(
+            "hardware.require_live_session=true but provider was built without hardware support "
+            "(ANOLIS_PROVIDER_BREAD_ENABLE_HARDWARE=OFF). Rebuild with dev-linux-hardware-release.");
+    }
+
     state.devices         = inventory::build_seed_inventory(config);
     state.inventory_mode  = inventory::to_string(inventory::InventorySource::ConfigSeeded);
     state.unsupported_probe_count = 0;

tests/unit/proto_smoke_test.cpp

@@ -1,6 +1,7 @@
 #include <gtest/gtest.h>
 
 #include <sstream>
+#include <stdexcept>
 #include <string>
 #include <vector>
 
@@ -167,3 +168,16 @@ TEST(ProtoSmokeTest, InMemoryProviderLoopCanRoundTripHello) {
         io_error)) << io_error;
     EXPECT_FALSE(framed_response.str().empty());
 }
+
+TEST(ProtoSmokeTest, RequireLiveSessionConfigBehaviorMatchesBuildMode) {
+    auto config = make_stub_config();
+    config.require_live_session = true;
+
+    anolis_provider_bread::runtime::reset();
+
+#if !defined(ANOLIS_PROVIDER_BREAD_HAS_CRUMBS)
+    EXPECT_THROW(anolis_provider_bread::runtime::initialize(config), std::runtime_error);
+#else
+    GTEST_SKIP() << "no-hardware guard is only applicable when hardware integration is disabled";
+#endif
+}

tests/unit/provider_config_test.cpp

@@ -76,6 +76,7 @@ TEST(ProviderConfigTest, AppliesDefaultsForOptionalHardwareFields) {
     const ProviderConfig parsed = load_config(config.path().string());
     EXPECT_EQ(parsed.provider_name, "bread-lab");
     EXPECT_EQ(parsed.bus_path, "/dev/i2c-1");
+    EXPECT_FALSE(parsed.require_live_session);
     EXPECT_EQ(parsed.query_delay_us, 10000);
     EXPECT_EQ(parsed.timeout_ms, 100);
     EXPECT_EQ(parsed.retry_count, 2);
@@ -114,6 +115,19 @@ TEST(ProviderConfigTest, ParsesManualDiscoveryAddressesAndDevices) {
     EXPECT_EQ(parsed.devices[1].address, 0x09);
 }
 
+TEST(ProviderConfigTest, ParsesRequireLiveSession) {
+    const TempConfigFile config(R"(
+hardware:
+  bus_path: /dev/i2c-1
+  require_live_session: true
+discovery:
+  mode: scan
+)");
+
+    const ProviderConfig parsed = load_config(config.path().string());
+    EXPECT_TRUE(parsed.require_live_session);
+}
+
 TEST(ProviderConfigTest, RejectsMissingHardwareBusPath) {
     expect_config_error(R"(
 hardware:
@@ -152,6 +166,16 @@ unexpected: true
 )", "Unknown root key");
 }
 
+TEST(ProviderConfigTest, RejectsInvalidRequireLiveSessionValue) {
+    expect_config_error(R"(
+hardware:
+  bus_path: /dev/i2c-1
+  require_live_session: maybe
+discovery:
+  mode: scan
+)", "hardware.require_live_session");
+}
+
 TEST(ProviderConfigTest, RejectsUnknownDeviceType) {
     expect_config_error(R"(
 hardware: