Table/YAML-driven refactor (Layer 1 start)

Move equipment capabilities and the E30 control state machine out of C++
code and into YAML data files; introduce a Router for SECS dispatch;
consolidate small files.

Behavioural changes: none.  Demo identical (15 SxFy transactions +
3 equipment-initiated primaries), 67 test cases / 384 assertions still
all green.  Structural changes only.

Why
---

The previous server.cpp held the equipment data dictionary (3 SVIDs,
2 ECIDs, 3 CEIDs, 2 alarms, 2 recipes, 4 host commands) as imperative
C++ in a 50-line `populate()` function, and routed inbound messages
through a 150-line if-ladder.  Adding a new SVID required a recompile.
Adding a new state transition required editing two switch statements
(`operator_*` and `on_host_request_*`).  The control state machine's
behavioural rules were spread across imperative code in two methods.

This is exactly what implementation_plan.md calls out as the wrong
shape: behavioural rules should live in versioned data, and every
runtime/test/analyzer should read from that data rather than re-encode
it.  This commit starts that move.

What's new
----------

data/equipment.yaml
  Equipment data dictionary.  Declarative SVIDs / ECIDs / CEIDs /
  alarms / recipes / host commands.  Host commands carry their HCACK
  ack code plus optional `emit_ceid` and `set_alarm` side-effects.
  Adding a new SVID or command is a YAML edit, no recompile.

data/control_state.yaml
  The E30 §6.2 control state transition table as data.  Each row is
  (from, on) -> (to [, then] [, ack]).  `then` chains an auto-advance
  through the transient AttemptOnline state.  The previous
  imperative switch is gone.

include/secsgem/config/loader.hpp + src/config/loader.cpp
  yaml-cpp-backed loader.  `load_control_state(path)` returns a
  ControlTransitionTable + initial state; `load_equipment(path, model)`
  populates the EquipmentDataModel and returns the device descriptor
  (id, MDLN, SOFTREV, optional auto-emit CEID).  Surfaces config
  errors with file path + field name via ConfigError.

include/secsgem/gem/router.hpp  (header-only)
  Small (stream, function) -> handler map.  Server registers all
  handlers once at startup, then the Connection's message handler is
  just `router.dispatch(msg)`.  Unhandled primaries with W set get
  SxF0 by default.  Replaces the if-ladder in secs_server.cpp.

include/secsgem/gem/control_state.hpp + .cpp
  ControlTransitionTable is the new pure data type.  ControlStateMachine
  is now a thin engine over the table: `fire(event)` looks up the row,
  optionally transitions, optionally chains a `then` transition, returns
  the ack code.  Behaviour rules no longer live in C++ switches.
  The default in-code table matches data/control_state.yaml row for row;
  tests rely on it so they don't need the YAML file.

include/secsgem/gem/data_model.hpp + .cpp
  `register_command(rcmd, CommandSpec)` replaces the function-handler
  signature.  CommandSpec = (HostCmdAck, optional emit_ceid, optional
  set_alarm).  `dispatch_command` returns a CommandResult so the server
  can fire the side-effects after S2F42 is sent.

apps/secs_server.cpp
  No populate(), no if-ladder.  Loads equipment.yaml + control_state.yaml
  at startup (clean error on bad config), wires the Router once,
  delegates dispatch.  Sm change handler reads emit_on_control_change
  from the YAML.  Welcome S10F3 removed for parity with config (a future
  YAML rule could re-introduce it declaratively).

tests/test_loader.cpp  (new)
  Verifies the YAML loader produces the same shape as the in-code
  default table, and that equipment.yaml populates every section
  (SVIDs/ECIDs/CEIDs/alarms/recipes/commands).  SECSGEM_DATA_DIR
  CMake define points at ${CMAKE_SOURCE_DIR}/data so tests don't
  depend on cwd.

CMakeLists.txt, Dockerfile
  find_package(yaml-cpp) and link.  libyaml-cpp-dev added to the
  Ubuntu base image (yaml-cpp 0.8 ships the modern target name).

File consolidation
------------------

Five small files removed; their content lives in fewer headers:

  - secs2/item.cpp        -> inline in secs2/item.hpp
  - secs2/message.cpp     -> inline in secs2/message.hpp
  - hsms/types.hpp        -> merged into hsms/header.hpp
  - hsms/frame.hpp        -> merged into hsms/header.hpp
  - hsms/frame.cpp        -> merged into hsms/header.cpp

hsms/header.hpp is now "the HSMS wire format" in one place: SType + status
enums + Timers + Header + Frame + constants.  All includers updated.

Net effect
----------

Before: equipment data dictionary lived in 50 lines of imperative
populate() inside secs_server.cpp; dispatch in a 20-branch if-ladder.

After: equipment data dictionary lives in 47 lines of YAML; dispatch
is a Router built once.  Adding a new capability is now a YAML edit
in the common case.

Test count up to 67 cases / 384 assertions (+4 cases / +106 assertions)
covering the loader and the new table-driven SM paths.

What's NOT changed
------------------

The per-SxFy reply construction still lives in C++ (each message has a
unique body shape).  Moving those into YAML/JSON message-shape
definitions is the next refactor step but requires a generic typed
encoder/decoder driven by shape descriptors; out of scope here.

Spooling, the S9 error stream, S1F19/F20, and the other gaps in
COMPLIANCE.md remain unchanged.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

tests/test_control_state.cpp

@@ -10,7 +10,6 @@ namespace {
 
 struct Recorder {
   std::vector<std::tuple<ControlState, ControlState, ControlEvent>> changes;
-
   ControlStateMachine::StateChangeHandler handler() {
     return [this](ControlState from, ControlState to, ControlEvent ev) {
       changes.emplace_back(from, to, ev);
@@ -18,6 +17,10 @@ struct Recorder {
   }
 };
 
+ControlStateMachine make_sm(ControlState initial) {
+  return ControlStateMachine(ControlTransitionTable::default_table(), initial);
+}
+
 }  // namespace
 
 TEST_CASE("default initial state is HostOffline") {
@@ -27,7 +30,7 @@ TEST_CASE("default initial state is HostOffline") {
 }
 
 TEST_CASE("custom initial state") {
-  ControlStateMachine sm({.initial = ControlState::EquipmentOffline});
+  auto sm = make_sm(ControlState::EquipmentOffline);
   CHECK(sm.state() == ControlState::EquipmentOffline);
 }
 
@@ -60,7 +63,7 @@ TEST_CASE("host request online when already online -> AlreadyOnline, no transiti
 }
 
 TEST_CASE("host request online from EquipmentOffline -> NotAccept") {
-  ControlStateMachine sm({.initial = ControlState::EquipmentOffline});
+  auto sm = make_sm(ControlState::EquipmentOffline);
   CHECK(sm.on_host_request_online() == OnlineAck::NotAccept);
   CHECK(sm.state() == ControlState::EquipmentOffline);
 }
@@ -89,42 +92,36 @@ TEST_CASE("host request offline when already offline is idempotent Accept") {
   CHECK(rec.changes.empty());
 }
 
-TEST_CASE("operator online from EquipmentOffline -> OnlineLocal by default") {
-  ControlStateMachine sm({.initial = ControlState::EquipmentOffline});
+TEST_CASE("operator online from EquipmentOffline -> OnlineLocal (default table)") {
+  auto sm = make_sm(ControlState::EquipmentOffline);
   CHECK(sm.operator_online());
   CHECK(sm.state() == ControlState::OnlineLocal);
 }
 
-TEST_CASE("operator online with default_remote -> OnlineRemote") {
-  ControlStateMachine sm({.initial = ControlState::HostOffline, .operator_default_remote = true});
-  CHECK(sm.operator_online());
-  CHECK(sm.state() == ControlState::OnlineRemote);
-}
-
 TEST_CASE("operator online when already online is rejected") {
-  ControlStateMachine sm({.initial = ControlState::OnlineLocal});
+  auto sm = make_sm(ControlState::OnlineLocal);
   CHECK_FALSE(sm.operator_online());
   CHECK(sm.state() == ControlState::OnlineLocal);
 }
 
 TEST_CASE("operator offline from any online state -> HostOffline") {
-  ControlStateMachine sm({.initial = ControlState::OnlineRemote});
+  auto sm = make_sm(ControlState::OnlineRemote);
   CHECK(sm.operator_offline());
   CHECK(sm.state() == ControlState::HostOffline);
 }
 
 TEST_CASE("operator local toggles only from OnlineRemote") {
-  ControlStateMachine sm({.initial = ControlState::OnlineRemote});
+  auto sm = make_sm(ControlState::OnlineRemote);
   CHECK(sm.operator_local());
   CHECK(sm.state() == ControlState::OnlineLocal);
-  CHECK_FALSE(sm.operator_local());  // already local
+  CHECK_FALSE(sm.operator_local());
 }
 
 TEST_CASE("operator remote toggles only from OnlineLocal") {
-  ControlStateMachine sm({.initial = ControlState::OnlineLocal});
+  auto sm = make_sm(ControlState::OnlineLocal);
   CHECK(sm.operator_remote());
   CHECK(sm.state() == ControlState::OnlineRemote);
-  CHECK_FALSE(sm.operator_remote());  // already remote
+  CHECK_FALSE(sm.operator_remote());
 }
 
 TEST_CASE("is_online classifier") {
@@ -134,3 +131,23 @@ TEST_CASE("is_online classifier") {
   CHECK(is_online(ControlState::OnlineLocal));
   CHECK(is_online(ControlState::OnlineRemote));
 }
+
+TEST_CASE("default table covers all expected (state, event) pairs") {
+  auto t = ControlTransitionTable::default_table();
+  // Every state must have an entry for each host event.
+  for (auto s : {ControlState::EquipmentOffline, ControlState::AttemptOnline,
+                 ControlState::HostOffline, ControlState::OnlineLocal,
+                 ControlState::OnlineRemote}) {
+    CHECK(t.find(s, ControlEvent::HostRequestOnline) != nullptr);
+    CHECK(t.find(s, ControlEvent::HostRequestOffline) != nullptr);
+  }
+}
+
+TEST_CASE("custom table: a row that only sets ack, no transition") {
+  ControlTransitionTable t;
+  t.add({ControlState::HostOffline, ControlEvent::HostRequestOnline, std::nullopt,
+         std::nullopt, static_cast<uint8_t>(OnlineAck::NotAccept)});
+  ControlStateMachine sm(t, ControlState::HostOffline);
+  CHECK(sm.on_host_request_online() == OnlineAck::NotAccept);
+  CHECK(sm.state() == ControlState::HostOffline);
+}

tests/test_data_model.cpp

@@ -45,14 +45,26 @@ TEST_CASE("set_time_string accepts well-formed and rejects malformed") {
 
 TEST_CASE("host command registry") {
   EquipmentDataModel m;
-  m.register_command("START", [](const auto&) { return HostCmdAck::Accept; });
-  m.register_command("STOP", [](const auto&) { return HostCmdAck::CannotDoNow; });
+  m.register_command("START", {HostCmdAck::Accept,      300, std::nullopt});
+  m.register_command("STOP",  {HostCmdAck::CannotDoNow, std::nullopt, std::nullopt});
+  m.register_command("FAULT", {HostCmdAck::Accept,      std::nullopt, 1});
 
   CHECK(m.has_command("START"));
   CHECK_FALSE(m.has_command("PAUSE"));
-  CHECK(m.dispatch_command("START", {}) == HostCmdAck::Accept);
-  CHECK(m.dispatch_command("STOP", {}) == HostCmdAck::CannotDoNow);
-  CHECK(m.dispatch_command("UNKNOWN", {}) == HostCmdAck::InvalidCommand);
+
+  auto start = m.dispatch_command("START", {});
+  CHECK(start.ack == HostCmdAck::Accept);
+  CHECK(start.emit_ceid.value_or(0) == 300);
+  CHECK_FALSE(start.set_alarm.has_value());
+
+  auto stop = m.dispatch_command("STOP", {});
+  CHECK(stop.ack == HostCmdAck::CannotDoNow);
+
+  auto fault = m.dispatch_command("FAULT", {});
+  CHECK(fault.ack == HostCmdAck::Accept);
+  CHECK(fault.set_alarm.value_or(0) == 1);
+
+  CHECK(m.dispatch_command("UNKNOWN", {}).ack == HostCmdAck::InvalidCommand);
 }
 
 // ---- Event reports -------------------------------------------------------

tests/test_hsms.cpp

@@ -1,6 +1,5 @@
 #include <doctest/doctest.h>
 
-#include "secsgem/hsms/frame.hpp"
 #include "secsgem/hsms/header.hpp"
 #include "secsgem/secs2/codec.hpp"
 

tests/test_loader.cpp

@@ -0,0 +1,72 @@
+#include <doctest/doctest.h>
+
+#include <fstream>
+#include <string>
+
+#include "secsgem/config/loader.hpp"
+#include "secsgem/secs2/item.hpp"
+
+using namespace secsgem;
+namespace gem = secsgem::gem;
+namespace s2  = secsgem::secs2;
+
+#ifndef SECSGEM_DATA_DIR
+#error "SECSGEM_DATA_DIR not defined; see CMakeLists.txt"
+#endif
+
+TEST_CASE("control_state.yaml parses into the same shape as default_table()") {
+  auto cfg = config::load_control_state(SECSGEM_DATA_DIR "/control_state.yaml");
+  auto baseline = gem::ControlTransitionTable::default_table();
+
+  CHECK(cfg.initial == gem::ControlState::HostOffline);
+  // Same row count; same (from, on) pairs map to the same destination.
+  CHECK(cfg.table.size() == baseline.size());
+
+  for (const auto& r : baseline.rows()) {
+    const auto* loaded = cfg.table.find(r.from, r.on);
+    REQUIRE(loaded != nullptr);
+    CHECK(loaded->to == r.to);
+    CHECK(loaded->then == r.then);
+    CHECK(loaded->ack_code == r.ack_code);
+  }
+}
+
+TEST_CASE("equipment.yaml populates SVIDs, ECIDs, CEIDs, alarms, recipes, commands") {
+  gem::EquipmentDataModel m;
+  auto desc = config::load_equipment(SECSGEM_DATA_DIR "/equipment.yaml", m);
+
+  CHECK(desc.model_name == "SECSGEM-SIM");
+  CHECK(desc.software_rev == "0.1.0");
+  REQUIRE(desc.emit_on_control_change.has_value());
+  CHECK(*desc.emit_on_control_change == 100);
+
+  CHECK(m.all_status_variables().size() == 3);
+  CHECK(m.status_variable(1)->name == "ControlState");
+  CHECK(m.status_variable(3)->value == s2::Item::boolean(true));
+
+  CHECK(m.all_equipment_constants().size() == 2);
+  CHECK(m.equipment_constant(10)->value == s2::Item::u4(uint32_t{1}));
+
+  CHECK(m.all_events().size() == 3);
+  CHECK(m.has_event(100));
+  CHECK(m.has_event(300));
+
+  CHECK(m.all_alarms().size() == 2);
+  CHECK(m.alarm(1)->text == "Chiller Temp High");
+  CHECK(m.alarm(1)->severity_category == 4);
+
+  CHECK(m.process_program_list().size() == 2);
+  CHECK(m.process_program("RECIPE-A").value().find("CHAMBER ARGON") != std::string::npos);
+
+  CHECK(m.has_command("START"));
+  auto start = m.dispatch_command("START", {});
+  CHECK(start.ack == gem::HostCmdAck::Accept);
+  CHECK(start.emit_ceid.value_or(0) == 300);
+  auto fault = m.dispatch_command("FAULT", {});
+  CHECK(fault.set_alarm.value_or(0) == 1);
+}
+
+TEST_CASE("loader surfaces YAML errors with file path") {
+  CHECK_THROWS_AS(config::load_equipment("/tmp/does-not-exist.yaml", *new gem::EquipmentDataModel),
+                  config::ConfigError);
+}