CHASM

Active contributors: yichaoyang, alex, david

Purpose

CHASM (Coordinated Heterogeneous Application State Machines) is a generalised state-machine runtime built into the History service. It treats Workflow as one Application State Machine (ASM) among many, lets new ASMs reuse Temporal's sharding / persistence / failover infrastructure, and hides distributed-systems plumbing behind a typed Go API.

The full reference document is docs/architecture/chasm.md. This page is the wiki entry point: it explains where the source lives and how it connects to the rest of the server.

Directory layout

chasm/
├── component.go               # Component contract
├── engine.go                  # Engine API (Read / Write)
├── registry.go                # Registry of all Libraries
├── library.go / library_core.go # Library type
├── library_mock.go
├── ref.go                     # ComponentRef
├── tree.go                    # The Component tree (~105KB)
├── transition_history.go
├── search_attribute.go
├── visibility.go / visibility_manager.go / visibility_value.go
├── path_encoder.go
├── nexus_completion.go
├── nexus_operation_processor.go
├── statemachine.go            # State-machine declaration helpers
├── task.go / task_handler_base.go
├── lib/                       # Concrete ASM libraries
│   ├── workflow/              # Workflow as a CHASM Library
│   ├── scheduler/             # Scheduled-workflow engine
│   ├── nexusoperation/        # Nexus operation state machines
│   ├── callback/              # External callback delivery
│   ├── activity/              # Standalone activity (no parent workflow)
│   └── ...
└── chasmtest/                 # Test scaffolding

chasm/lib is the most heavily-modified directory in the entire repo over the last 90 days (571 commits) — most of the active migration work is here.

Key abstractions

Concept	Where it lives	Description
Registry	chasm/registry.go	Global catalog of all registered Libraries.
Library	chasm/library.go	Groups Component types, Tasks, and service handlers under a name.
Component	chasm/component.go	A registered type with state (Fields) and behaviour.
Field / Map	chasm/field.go	Framework-managed containers for persisted state.
Engine	chasm/engine.go	Entry point for Read / Write to an Execution.
Execution / Tree	chasm/tree.go	The runtime instance of an ASM and its tree of nodes (~105KB).
ComponentRef	chasm/ref.go	Serialised "return address" used by callbacks.
VersionedTransition	chasm/transition_history.go	(FailoverVersion, TransitionCount) — the logical clock.
Pure / SideEffect Task	chasm/task.go	Two task kinds: in-transaction Pure, post-commit Side Effect.

How it works

graph TD
    Client[gRPC client] --> Lib[Library frontend]
    Lib --> Eng[chasm.Engine]
    Eng --> Tree[Execution tree]
    Tree --> Comp[Components]
    Comp -->|Field writes| TX[(Persistence transaction)]
    Comp -->|schedule task| TX
    TX -->|commit| QP[History queue processors]
    QP -->|Pure Task in tx| TX
    QP -->|Side Effect Task post-commit| Ext[External services]
    Ext -->|callback w/ ComponentRef| Eng

A Transition is the atomic unit of state change: it operates on the entire Execution, can read or mutate any node, and either commits as one DB write (with all scheduled Pure Tasks fanned in) or rolls back entirely. Side Effect Tasks run after commit; their handlers cannot mutate state directly — they call back through the same Engine API as any external caller.

The "Engine" here is logically global per shard; physically it is chasmEngine in service/history/chasm_engine.go, which sits next to the classic historyEngine.

Libraries shipping today

Library	What it provides
chasm/lib/workflow/	Workflow execution as a CHASM Library — the migration target.
chasm/lib/scheduler/	Schedule semantics (cron, calendar, intervals).
chasm/lib/nexusoperation/	Nexus operation state machine.
chasm/lib/callback/	External callback delivery (HTTP / gRPC).
chasm/lib/activity/	Standalone activity (an activity not bound to a workflow).

Integration points

• History service — the runtime is wired into each shard via service/history/chasm_engine.go. When the shard starts, every registered Library gets its own dispatcher.
• Frontend service — public-facing gRPC entry for each Library is exposed via the Library's own frontend.go (e.g. chasm/lib/scheduler/frontend.go contains scheduler-specific frontend wiring).
• Persistence — Components and Tasks are written through the same persistence interface as workflow events; CHASM extends but does not replace it.
• Replication — VersionedTransitions are the unit of replication; the replication path treats CHASM tasks the same way it treats history events.
• Visibility — the built-in Visibility Component contributes search-attribute and memo data; see chasm/visibility.go.

Entry points for modification

• Adding a new ASM: create a chasm/lib/<name>/ package mirroring chasm/lib/scheduler/. Provide a library.go that registers Components and Tasks, an fx.go that wires the Library into the runtime, and (if the ASM has a public API) a frontend.go.
• Adding a Component to an existing Library: define its Fields, register it in the Library's library.go, write a transition function.
• Tuning runtime behaviour: dynamic-config keys live alongside each Library's config.go.
• Custom search-attribute providers: implement the provider interface from chasm/search_attribute.go.

Related pages

• HSM — the older library CHASM is gradually superseding.
• Workflow execution primitive
• Nexus
• Scheduling
• docs/architecture/chasm.md — the maintained design doc.