tsm is organized so application code depends on a small set of stable headers and target-specific adapters. State-machine definitions remain portable C++ types; platform choices are made at the runtime, executor, and board-support boundary.

Core Headers

tsm.h defines tsm::hsm, transition selection, hierarchy traversal, history, deferred events, orthogonal regions, and synchronization behavior.
tsm/transition.h defines transition authoring types such as tsm::T, tsm::Ts, fork/join rules, history destinations, and transition semantics.
tsm/core_algorithms.h exposes constexpr hierarchy algorithms used by the HSM runtime and isolated algorithm tests.
tsm/type_list.h provides bounded compile-time list and map utilities used by state, event, transition, and hierarchy metadata.

The embedded core is checked for accidental dynamic-allocation, exception, and RTTI vocabulary. Placement-new remains allowed where fixed erased storage constructs an event in caller-provided memory.

Runtime Headers

tsm/runtime.h is the aggregate include for queues, delayed events, runtime policies, resource accounting, and task execution.
tsm/runtime/coroutine.h provides static coroutine tasks, wake primitives, channels, signals, fixed timer storage, and task lifecycle reporting. The authoring and execution model is documented in coroutines.
tsm/runtime/executor.h provides caller-driven and cooperative executor building blocks.
tsm/runtime/resources.h provides compile-time resource snapshots and budget contracts.
tsm/runtime/resource_manifest.h emits stable JSON resource manifests for host-side review artifacts.

Runtime code keeps storage explicit. Queue capacity, event payload capacity, timer slots, task frame bytes, and task counts are part of the authored configuration or derived from it.

Platform Headers

tsm/platform/profile.h defines target profile contracts for Linux host, bare-metal ARM, FreeRTOS ARM, Zephyr ARM, QNX Neutrino 7.x, and conservative production builds.
tsm/bare_metal.h, tsm/freertos.h, tsm/zephyr.h, tsm/qnx.h, tsm/linux.h, and tsm/kevent.h adapt executor wake behavior to the selected target.
tsm/chrono_ticks.h converts host or adapter wall-clock durations into integer ticks before they reach the HSM runtime.

Profiles are compile-time declarations of deployment assumptions. A safety or bare-metal profile can require compiler flags that disable exceptions and RTTI. Heap policy is enforced through resource contracts, code review, and the core no-allocation vocabulary check. Embedded-focused examples are also checked at the binary-symbol level for heap allocation entry points, which helps catch accidental host-library dependencies that are not visible in a single header.

Application Boundary

Application code exposes product-facing methods and typed events. A board or application shell owns the runtime, executor, drivers, and HSM instance. HSM definitions own states, transitions, guards, actions, and context.

This split keeps state-machine artifacts reviewable while allowing the same definition to run under host tests, Linux simulation, FreeRTOS, Zephyr, or bare-metal ARM adapters.