HSM (Hierarchical State Machine)

Active contributors: alex, david, yichaoyang

Purpose

HSM is the in-shard hierarchical state-machine library that powered callbacks and Nexus operations before CHASM existed. It is being gradually superseded but still ships in production code paths.

Directory layout

service/history/hsm/
├── ...                        # Core HSM types (state, transition, event)
└── (component-specific subpackages)

The library is small (a few thousand lines) and tightly coupled to the History shard's persistence model. Look for hsm. references in components/callbacks/ and components/nexusoperations/ to see consumers.

Key abstractions

Concept	Description
Node	One state-machine instance, addressed by a path of names from the workflow root.
Transition	A registered state change. The HSM library validates that the current state is a legal predecessor.
Event	An event that triggers a transition.
Task	A side-effect to run after the transition is persisted (e.g. dispatch a callback HTTP request).

How it works

HSM lives inside the workflow's Mutable State: each HSM tree is a sub-tree of nodes attached to a workflow execution. Transitions are recorded synchronously with mutable-state updates and replicated as part of the workflow's history events. Tasks emitted by transitions go onto the History shard's outbound or callback queues.

graph TD
    MS[MutableState] --> HSMRoot[HSM root node]
    HSMRoot --> Cb[Callback nodes]
    HSMRoot --> Nx[NexusOperation nodes]
    HSMRoot --> Other[Component-specific nodes]
    Cb -->|task| OutboundQ[Outbound queue]
    Nx -->|task| OutboundQ
    OutboundQ -->|http/grpc| Targets[External services]

Migration status

The team is moving callbacks and Nexus operations from HSM to CHASM Libraries. The two systems coexist:

• HSM nodes remain the canonical persistence layout for older state machines.
• New state machines should use CHASM unless there is a reason not to.
• Some Components (callbacks, NexusOperations) have an HSM and a CHASM implementation in flight; the CHASM versions live in components/callbacks/ (HSM glue) and chasm/lib/callback/ (CHASM Library).

Integration points

• Inbound: state transitions triggered by workflow tasks, timers, or callbacks landing on the Frontend.
• Outbound: Outbound History queue (delivery of HTTP/gRPC requests via the executor in service/history/outbound_queue_active_task_executor.go).
• Persistence: part of the workflow execution row (Mutable State).

Entry points for modification

• Adding an HSM-backed component: the canonical examples are components/callbacks/ and components/nexusoperations/. Each registers its node types with the HSM machinery in service/history/hsm/.
• For new state machines, prefer CHASM.

Related pages

• CHASM — the successor framework.
• Nexus — primary HSM consumer.
• History service — the host of all HSM trees.