public_api_boundary

Application code should use the public headers and names listed here. Anything inside tsm::detail or tsm::runtime::detail is implementation machinery and can change as the framework is optimized.

Stable Authoring Surface

• tsm.h for HSM definitions, states, events, transitions, hierarchy, synchronization, history, deferred events, and tick schedulers.
• tin/tsm.h for the same state-machine layer through the tin package namespace.
• tsm/runtime.h for runtime queues, actors, typed ports, task executors, resource contracts, and runtime composition.
• tin/runtime.h for Tin kernel runtime primitives.
• tsm/transition.h for transition authoring helpers such as tsm::T, tsm::Ts, tsm::on, tsm::Fork, tsm::Join, and history destinations.
• tsm/platform/profile.h for target profile contracts.

Consumer CMake projects may link tsm::tsm, tin::tin, or tin::tsm to use these headers. See tin.md for the full consumer build surface.

Target Adapter Surface

• tsm/bare_metal.h
• tsm/freertos.h
• tsm/zephyr.h
• tsm/qnx.h
• tsm/linux.h
• tsm/kevent.h

Target adapters expose the same executor shape where possible: wake(), wake_from_isr(), wait_for_work(), run_ready(), tick(n), start<Entry>(), spawn<Entry>(), cancel<Entry>(), and cancel_all().

Runtime Utility Surface

• tin.h for the tin compatibility umbrella.
• tio.h for portable I/O facade contracts.
• thal.h for platform/HAL boundary contracts.
• tsm/chrono_ticks.h
• tsm/io.h
• tsm/logging.h
• tsm/transport.h
• tsm/runtime/actor.h
• tsm/runtime/coroutine.h
• tsm/runtime/resource_manifest.h
• tsm/runtime/resources.h

These headers are public, but they are supporting APIs. State-machine definitions should remain centered on typed events, transition declarations, guards, actions, state methods, and context.

Consumer CMake projects may link tio::tio for I/O facade contracts and thal::thal for platform/HAL boundary contracts. See tin.md for installed CMake and pkg-config usage.

Internal Boundary

The following are not application-facing contracts:

• tsm::detail
• tsm::runtime::detail
• generated trace fixtures
• private formal-specification and evidence tooling

Examples and public documentation should avoid using internal namespaces. If a new feature needs a detail type in an example, promote a small public wrapper first.