An audit of doc code blocks against the real headers found APIs that do
not exist in the codebase, presented as authoritative walkthroughs:
- ch35 (dispatch): an entirely fabricated callback architecture —
HostCommandRegistry::set_emit_ceid_handler, CommandOutcome, emit_ceids.
Rewritten to the real Spec/Result/dispatch + the new set_handler hook.
- ch13 (E30): wrong store names — EventStore/ReportStore -> EventReportSubscriptions,
SvidStore -> StatusVariableStore, AlarmStore/AlarmDispatcher -> AlarmRegistry,
ClockStore -> Clock, TerminalServiceStore -> (no store), in both the
capability tables and the worked S2F33 example.
- ch17 (E116): EptStore/seconds/bucket_ -> EptStateMachine/milliseconds/buckets_.
- ch51 (extending): stale host-command handler -> the real set_handler signature.
Verified clean by grep: no fabricated symbols remain in docs/.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Seven chapters walking the implementation top-to-bottom.
30 — Repository tour. Top-level layout, directory by directory.
The eight built binaries. The dependency graph from TCP socket
up through EquipmentDataModel. CMake's role. Test layout.
31 — Spec-as-data and codegen. Why the design choice fits SECS/
GEM specifically. The five YAML files: messages catalog,
control/PJ/CJ transition tables, equipment dictionary. How
tools/gen_messages.py turns messages.yaml into typed C++ at build
time. The --validate-config multi-error validator. How to add a
new SVID / CEID / host command / state / message without C++.
32 — Stores and the data model. What a store IS (records + API +
change handler + optional persistence). Every store in the
codebase mapped to the SEMI standard it serves (table of 21).
EquipmentDataModel as plain composition + cross-store convenience
methods (vid_value, compose_reports_for). The no-locks single-
threaded contract. How to add a new store.
33 — Transport. hsms::Connection read path (length+payload async
chain), write path (queue + one outstanding write), timer model
(5 steady_timers + per-request T3). The asio executor / strand
model and why it's the right shape. secsi::Protocol as the IO-
free FSM with Action / Event variants; secsi::TcpTransport as the
asio adapter. Pattern repeats for E84 + GEM comm-state.
34 — Codec and SML. The four files (170 + 30 + 52 + 32 lines of
header, 229 + 220 lines of impl). Item variant storage layout
(11 alternatives, 16 formats, shared storage where E5 permits).
encode_into recursion; decode_at with bounds checks throwing
CodecError. Message wrapper. SML printer + try_parse_sml +
why SML round-trips Items but not necessarily bytes.
35 — State machines and dispatch. gem::Router as a typed
(stream, function) dispatch table. How an S2F41 round-trip walks
through parser → store dispatch → side-effect → CEID emission →
S6F11 build → spool-aware deliver. The 11 FSMs all sharing the
same three-property shape (pure data table + pure FSM + observer
pattern). CEID cascading from FSM transitions to wire bytes.
36 — Persistence, validation, metrics. Which 7 stores have file
journals + why the others don't. Per-record file pattern (atomic
rename, partial-write safe). Schema versioning + multi-version
read. Multi-error YAML validator (--validate-config) + cross-file
reference checks. Prometheus registry + HTTP exporter + worked
metric patterns from the PVD example.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
raphael