Purpose

tools/tsm_tool.py is the dependency-free command line tool for moving state machine definitions between authoring formats, reviewed YAML/JSON IR, diagrams, test simulators, and generated integration skeletons.

Use it when a machine definition needs to cross a boundary:

review a compact .hsm or YAML file as canonical JSON;
validate YAML or JSON before code generation or CI replay;
record target and runtime intent next to the machine definition;
generate diagrams for design reviews;
generate a Python simulator for tests and notebooks;
generate C++ or pybind11 skeletons that a product team can fill in.

The tool does not replace production C++ execution. Production behavior still runs through tsm::hsm, runtime policies, and the selected executor.

Inputs

The tool accepts:

.hsm or .tsm: human authoring syntax documented in hsm_dsl_grammar;
.yaml or .yml: compact verified-tsm.machine.v1 authoring with inferred states and events;
.json: verified-tsm.machine.v1 machine IR documented in machine_ir_json.

The importer treats .hsm and .tsm as the same DSL family. YAML and JSON use the same schema and normalize to the same internal machine model.

Compact YAML is usually the easiest form to review:

schema: verified-tsm.machine.v1
machine:
  initial: Booting
 
# ISR and ADC details stay outside the behavior model.
transitions: [
  {Booting, BootComplete, Running},
  {Running, OvervoltageFault, SafeHold}
]

Commands

Import a human-authored machine to JSON IR:

python3 tools/tsm_tool.py import test/tsm_dsl/flat_inferred.hsm \
  --format hsm \
  -o build/motor.machine.json

Validate an IR file:

python3 tools/tsm_tool.py validate build/motor.machine.yaml

Export review artifacts:

python3 tools/tsm_tool.py export build/motor.machine.yaml --format plantuml -o build/motor.puml
python3 tools/tsm_tool.py export build/motor.machine.yaml --format mermaid  -o build/motor.mmd
python3 tools/tsm_tool.py export build/motor.machine.yaml --format scxml    -o build/motor.scxml
python3 tools/tsm_tool.py export build/motor.machine.yaml --format python   -o build/motor_model.py
python3 tools/tsm_tool.py export build/motor.machine.yaml --format artifacts -o build/motor.artifacts.json

Generate implementation skeletons:

python3 tools/tsm_tool.py generate build/motor.machine.yaml --format cpp-skeleton -o build/motor.h

python3 tools/tsm_tool.py generate build/motor.machine.yaml --format pybind11 -o build/motor_pybind.cpp

Output Matrix

Format	Command	Use
`json`	`export` or `import`	canonical machine IR for tooling and automation
`artifacts`	`export`	tin artifact manifest for target, runtime, generated outputs, evidence, and package metadata
`scxml`	`export`	interchange with state-machine tools
`plantuml`	`export`	diagram review in PlantUML workflows
`mermaid`	`export`	diagram review in Markdown workflows
`python`	`export`	lightweight simulator for tests and notebooks
`cpp-skeleton`	`generate`	initial C++ authoring scaffold
`pybind11`	`generate`	Python extension bridge scaffold

Typical Pipeline

.hsm / .tsm / .yaml
  -> import
verified-tsm.machine.v1 JSON
  -> validate
  -> export tin artifact manifest
  -> export diagrams
  -> export Python simulator
  -> generate C++ or pybind11 skeletons

For product code, keep the generated skeleton under review and edit it into a normal tsm definition. For tests and tools, use YAML for human-owned source and JSON as the stable machine interchange format.

Target And Runtime Metadata

Machine JSON can carry deployment intent that tools should preserve even when the production C++ runtime remains hand-selected:

{
  "target": {
    "profile": "host-linux",
    "architecture": "x86_64",
    "platform": "linux",
    "compiler": "gcc",
    "tick": {
      "rep": "std::uint64_t",
      "period": "std::micro"
    },
    "constraints": {
      "no_heap_runtime": true,
      "exceptions_disabled": true,
      "rtti_disabled": true
    }
  },
  "runtime": {
    "dispatch_model": "queued",
    "queue": {
      "storage": {
        "kind": "static_storage",
        "capacity": 8
      },
      "overflow": "reject_newest"
    },
    "timer_slots": 2
  }
}

The validator checks the shape of this metadata:

target.profile is required when a target object is present;
target.tick.rep and target.tick.period record the configured tick type;
target constraints are boolean flags;
runtime dispatch model, queue storage kind, and queue overflow policy are checked against the runtime vocabulary;
runtime capacities and slot counts must be non-negative, and queue capacity must be greater than zero.

Tin Artifact Manifest

export --format artifacts emits a tin.artifacts.v1 manifest. It gives build, review, and CI tooling one place to inspect the machine, selected target metadata, runtime metadata, transport metadata, evidence obligations, tin version, public headers, and related generated artifact kinds.

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

The manifest includes entries for:

verified-tsm.machine.v1 machine IR;
SCXML, PlantUML, and Mermaid diagrams;
generated Python simulator;
generated C++ and pybind11 skeletons;
tsm.resource_manifest.v1 runtime resource manifests;
verified-tsm.trace.v1 replay traces;
verified-tsm.traceability.v1 traceability records.

Use the artifact manifest as the index for a generated evidence bundle. The individual generated files still come from their normal commands.

CI Coverage

The quality suite already exercises the tool path:

.hsm import to JSON;
JSON validation;
export to JSON, artifact manifest, SCXML, PlantUML, Mermaid, and Python;
generation of C++ and pybind11 skeletons;
generated Python smoke import;
generated pybind11 extension build/import when pybind11 is available.