generation_pipeline

Purpose

The generation pipeline keeps machine behavior reviewable while letting tools produce diagrams, simulators, and implementation scaffolds from the same machine description.

human authoring
  C++ or .hsm
      |
      v
verified-tsm.machine.v1 JSON
      |
      +--> validation
      +--> tin artifact manifest
      +--> diagrams: PlantUML, Mermaid, SCXML
      +--> Python simulator
      +--> C++ skeleton
      +--> pybind11 skeleton

Source Formats

C++ is the production authoring surface. Use it when the machine is already part of the firmware, library, or application.

.hsm is the compact review surface. Use it when a machine needs to be edited or reviewed outside C++ syntax while still lowering to the same state/event model.

YAML and JSON are the tooling surfaces. Use YAML for hand-authored machines and JSON as the stable interchange format between importers, validators, generators, diagrams, and test harnesses.

Validation Boundary

Every generated path should pass through validation:

python3 tools/tsm_tool.py validate machine.yaml

Validation catches:

• unsupported schema versions;
• duplicate state, event, or transport names;
• transitions that reference missing states or events;
• composite state references to missing parents or initial children;
• transport records that reference missing events.

The .hsm importer performs additional syntax and inference checks before emitting JSON.

Generated Artifacts

Diagram exports are review artifacts generated from the machine definition:

python3 tools/tsm_tool.py export machine.yaml --format plantuml -o machine.puml
python3 tools/tsm_tool.py export machine.yaml --format mermaid  -o machine.mmd
python3 tools/tsm_tool.py export machine.yaml --format scxml    -o machine.scxml

The tin artifact manifest indexes target, runtime, transport, evidence, package version, and generated artifact metadata:

python3 tools/tsm_tool.py export machine.yaml --format artifacts -o machine.artifacts.json

Python export is a simulator artifact:

python3 tools/tsm_tool.py export machine.yaml --format python -o machine_model.py

C++ and pybind11 outputs are scaffolds:

python3 tools/tsm_tool.py generate machine.yaml --format cpp-skeleton -o machine.h
python3 tools/tsm_tool.py generate machine.yaml --format pybind11     -o machine_pybind.cpp

Generated scaffolds are starting points for product integration and should be reviewed like source code.