Mutable state

The mutable state of a workflow execution is the persisted-and-cached summary the History service uses to make decisions about the workflow without replaying its full event history.

Aspect	Detail
What it holds	In-progress activities, timers, child workflows, signals, queries, updates, callbacks, Nexus operations, retry state.
Storage	One row per execution in the persistence backend's executions table.
Cache	Per-shard LRU; entries are evicted when memory pressure rises.
Concurrency	Per-execution mutex held in workflow.Context.
Update model	Optimistic — every write increments a version stamp; concurrent writers fail with ConditionFailedError and reload.
Implementation	MutableStateImpl — the largest hand-maintained file in the repo (~357KB).

Code references

• Implementation: service/history/workflow/mutable_state_impl.go.
• Loading: service/history/workflow/context.go.
• Persistence layout: executions table, see schema/cassandra/temporal/schema.cql.
• Cache: service/history/workflow/cache/.

Why the summary?

In principle, every workflow decision could be made by replaying the History Events from scratch. In practice this would be too slow — even modest workflows accumulate thousands of events. Mutable State is the cached, structured summary that supports O(1) lookups for "is this activity still in flight?" and similar questions.

Where to read more

• History service
• Workflow execution
• docs/architecture/history-service.md