
ID	0082
Class	API
Severity	2
Status	blocked

Models: —

Found: 2026-10-24, docs review (plan P8, decision D2)

Decision needed: owner: install both headers (and what they pull in), or keep them in-tree only. This changes the public API surface (fhsim_workspace doc/agents/contracts.md).

Evidence

find include -name SimulationManagerFactory.h -o -name IStateObserverPlugin.h is empty: both live only in src/engine/io/. The same holds for IStateObserverBase.h and SpscQueue.h, which examples/plugin_observer_file/StateFileObserverPlugin.cpp:37 pulls in (IStateObserverBase.h:4 includes SpscQueue.h). The example plugin therefore builds only in-tree. User docs show snippets that include them: doc/user/developing-models/testtools.md, doc/user/developing-models/testing.md (CreateSimulationManagerFromFile) and doc/user/input-file/observers.md (observer plugin). The in-tree tests find them through the src/engine/io include directory only.

Effect

A package consumer who copies those snippets gets "No such file or directory". The docs now say the snippets work in-tree only.

Possible fix

Install the headers (also IStateObserverBase.h and SpscQueue.h) under include/fhsim/ with the headers they include, and update the three snippets. Or keep them private and document an installed alternative.

Test that would prove it

A small consumer build against the installed package that includes both headers.

Risk

New public API to keep stable.