decision_guide

Decision Guide

Use this page when you know what you need to build but are not sure which tin surface should own it.

Which Layer Owns The Change?

You are changing	Put it in	Because
Legal product states, events, guards, actions, or hierarchy	tsm	This is behavior semantics.
Bounded movement of values between local components	tin::channel, tin::queue, runtime transport	This is runtime mechanics.
Composition of several local components in a fixed order	actors and tin::actor_group	This is caller-owned local scheduling.
A workflow that waits on a signal, channel, timer, or runtime event	coroutine tasks and executors	This is cooperative asynchronous work.
GPIO, ADC, PWM, CAN, UART, SPI, I2C, or driver payload shape	tio	This is portable I/O vocabulary.
Compiler, RTOS, board, scheduler, or HAL assumption	thal or platform adapter	This is target integration.
Package include paths, CMake targets, or pkg-config names	tin facade and package files	This is user-facing packaging.
Machine import/export, YAML/JSON IR, diagrams, Python, or codegen	tools and spec/ir	This is authoring/tooling infrastructure.

Which Runtime Shape Should I Use?

Use tsm::hsm<Definition> directly when the caller can synchronously dispatch one event at a time and does not need backlog.

Use tsm::Runtime with a queued runtime policy when producers need bounded backlog and a caller should decide when events are dispatched.

Use tin::channel<T, N> when raw values or adapter records must move between components without becoming HSM events yet.

Use actors when a system has several local components with typed input/output ports and a deterministic stepping order.

Use coroutine tasks when the code reads more clearly as a sequence of waits: wait for channel input, wait for a signal, sleep for ticks, then send a typed event.

Use tsm::app when the runtime, task executor, and delayed events should be packaged as one application object.

Where Should Data Live?

Data	Typical owner
Current state	HSM runtime
Product context fields	HSM context
Raw samples waiting for processing	tin::channel
Events waiting for behavior dispatch	queued runtime
Output commands waiting for an adapter	channel, actor output, or context field
Vendor SDK handles	target adapter
Build and platform assumptions	thal profile, CMake, platform smoke test

Questions To Ask Before Coding

1. Is this behavior or mechanics?
2. Does this need bounded backlog?
3. Who owns stepping or draining?
4. What happens when storage is full?
5. Can a host test run this without target headers?
6. Which docs and tests will prove the contract?