Design Invariants

These are the properties contributors should preserve when changing tin. They are not slogans; they are review criteria.

Runtime Ownership Is Explicit

tin runtime objects do not create framework-owned threads. Queues, channels, actors, tasks, timers, and HSM runtimes advance only when a caller, executor, RTOS task, event loop, or test steps them.

This makes execution order reviewable and lets host tests run the same behavior without target scheduling.

Storage Is Bounded By Construction

Embedded-facing runtime paths should expose capacity in types, policies, or resource manifests. A reviewer should be able to find:

• queue slots;
• channel capacity;
• task frame bytes;
• timer slots;
• whether heap use is allowed.

When a change adds storage, update the resource snapshot, budget, or documentation that explains the new bound.

Overflow Policy Is Visible

Backpressure behavior is part of the API. A channel or queue should make clear whether it rejects newest values, drops oldest values, overwrites latest values, or uses another explicit policy.

Callers should handle the acceptance result when losing work matters.

Events Are Typed Product Facts

Events are normal C++ types. Use payload fields when behavior, diagnostics, tests, or trace replay need data such as measured values, thresholds, IDs, timestamps, or error codes.

Marker events are fine for pure signals such as BootComplete. Payload events are better when the event records something observed.

Behavior Is Target-Independent

HSM definitions should model legal behavior without depending on a board HAL, RTOS header, middleware client, socket library, or simulator API. Those belong at adapter boundaries.

This keeps behavior available to host unit tests and generated tooling.

Time Is A Runtime Input

Time should enter through ticks, timers, task sleeps, or typed timer events. Behavior code should not read wall-clock time directly. This allows replay, simulation, deterministic tests, and target-specific tick sources to share the same behavior model.

Target Code Is An Adapter

Platform-specific code may use vendor APIs, RTOS primitives, linker scripts, or board objects. It adapts those details into tin, tio, thal, or product types for shared behavior.

Evidence Moves With Semantics

If a change alters behavior semantics, queueing behavior, IR shape, generated artifacts, or target assumptions, update the corresponding tests and docs in the same change. The repository should not require a reviewer to infer whether the evidence still matches the implementation.