Crucible State Machine — Evolution Guide

[joshua-temple]

Policy. Applies from the moment the first machine ships. See the JSON, Mermaid & DOT discussion for the machine.json artifact this discipline is enforced against.

Treat the machine as a schema

A machine definition is a schema. The invariants that govern database-schema and shared-message changes apply here: silent renames break downstream consumers, removals break replay, and additive changes are safe as long as defaults hold.

The crucial difference from ordinary Go refactoring: violations surface as ErrInvalidTransition at runtime, not at compile time, because machines are bound to persisted entity state. An entity persisted under an old state name cannot be loaded once that name is gone.

Treat any machine change the way you would treat a migration of a shared message contract or a database table.

Additive-only evolution / reserved drop-in surface

This is the design tenet that makes the kernel safe to grow: every deferred capability has its IR field and API hook reserved in v1, so landing it later is purely additive — never a breaking change. It is the forward-looking counterpart to the schema discipline below. Schema discipline governs how your machine changes; the reserved drop-in surface governs how the kernel grows under you.

The contract has two halves, and a kernel feature only counts as "reserved" if it satisfies both:

1. The IR field exists in v1 — serialized as an inert default (historyType: "none", invoke: [], an unused effect contract), so older JSON and newer JSON share one schema. No schema-version bump when the feature lands.
2. A one-line "drops in by:" path proves the landing is additive — a later release reads the already-present field; it does not move or rename anything.

Deferred capability	Reserved IR shape (ships v1, inert)	Drops in by
History states (shallow/deep)	a history pseudo-state kind (historyType enum)	the resolver honoring the reserved kind on re-entry
Invoked services	an invoke block (named-ref + params) on states	binding invoke names against a services registry
Actor model	actor refs reserved on the instance	each instance gets a mailbox; Fire becomes a message send
after scheduler (runtime)	the ScheduleAfter effect contract (the after representation already ships)	a host scheduler consuming the effect and re-firing on expiry
Full SCXML microstep ordering nuance	the step model in Trace.Microsteps	refining ordering within the already-recorded steps

Because these fields already serialize as inert defaults, a machine authored today round-trips unchanged through a kernel that later activates them — the same lossless-round-trip guarantee, projected forward in time. A reserved field that ever needs to be renamed or re-typed to land its feature was not properly reserved; that is the review bar for any "reserved" claim.

Allowed changes (safe without a deprecation window)

Change	Why safe
Add a new state	No existing entity is in it; no transition references it until you wire one.
Add a new transition (new event on an existing state)	Entities already in that state gain a new legal event; existing Fire calls are unaffected.
Add a new guard to a transition	Guards evaluate on Fire; safe if every entity currently in that state satisfies the new guard.
Add a new effect to a transition	The new side-effect fires on future transitions; historical traces are unaffected.
Add/update OwnedBy metadata	Metadata-only; visualization updates, no behavior change.
Add/update WaitMode on a transition	Changes that transition's synchronization; safe if consumers handle both modes.

Caveat on guard additions: adding a guard that some currently-in-that-state entities do not satisfy is a breaking change disguised as an addition. Audit your data before shipping it.

Disallowed changes (require migration)

Change	Risk	Required process
Rename a state	Entities persisted with the old name can't load.	Deprecation window + data migration.
Remove a state	Entities in it hit ErrInvalidTransition on every Fire.	Verify zero live entities in that state first.
Rename an event	Existing scenario JSON + trace replay break.	Deprecation window; keep the old name as an alias.
Remove a transition	Paths that relied on it become ErrNoPath.	Audit PlanPath callers; migrate affected entities.
Reorder iota-based state values	Reordering changes persisted integer values.	Never reorder; only append.
Repurpose a state for a different stage	Entities already in it gain unintended semantics.	Rename (with migration) + add a new state instead.

Versioning & deprecation pattern

Add freely; never rename or repurpose without a Deprecated -> Removed lifecycle.

stateDiagram-v2
    [*] --> Active : Initial declaration
    Active --> Active : Add states (additive)
    Active --> Active : Add transitions
    Active --> Deprecated : Deprecated marker added
    Deprecated --> Deprecated : Migrate callers (multiple PRs)
    Deprecated --> Removed : All callers migrated; item deleted
    Removed --> [*]
    Deprecated --> Active : Revert (rare)

Loading

1. Mark the old state/transition deprecated (a // Deprecated: comment and/or a Deprecated() DSL marker).
2. Add the replacement alongside it — machines support additive coexistence.
3. Migrate entities from the deprecated state to the replacement (a one-time script or a lazy upgrade on the read path).
4. Verify zero entities remain in the deprecated state. This is a precondition for removal, not a nice-to-have.
5. Remove the deprecated item in a follow-up change after verification.

The deprecation window is the gap between steps 1 and 5; keep it at least one full release cycle.

Worked example — renaming a state

Suppose Assigned is renamed to Accepted in the UX:

Change 1 — Add Accepted (new state). Wire its transitions. Mark Assigned deprecated.
           Both coexist. New code paths use Accepted.

Migration — Move all entities Assigned -> Accepted.
            Verify zero entities remain in Assigned across all environments.

Change 2 — Remove Assigned, its transitions, and its guards.
           machine.json diff shows one state + its transitions removed.
           CI confirms zero references outside history/trace replay.

Do not combine the two changes. The split is the gap that allows zero-downtime migration without coordinating every consumer that reads entity state.

Semver guidance

The machine definition has no independent semantic version. Instead:

• The committed machine.json artifact is the versioned snapshot.
• A change that modifies the graph produces a machine.json diff — reviewers treat that diff as a schema-migration review.
• Adding states/transitions is backward-compatible (minor); removing or renaming is breaking (major) and requires the full deprecation process.

Hot-reload is versioning, not mutation. Quench freezes a definition into an immutable *Machine; you never mutate a live one. To change behavior at runtime you roll a new version of the machine (a new *Machine from new IR) and route new instances to it while in-flight instances drain on the old one. This is why hot-reload is a non-goal at the kernel level — versioned, frozen machines give you the same capability with none of the live-mutation hazards.

CI enforcement

machine.json is committed and regenerated via go generate. Any change that modifies the machine definition must produce a machine.json diff — CI fails if the committed file is stale. Reviewers get a machine-readable, human-readable diff of structural graph changes alongside the Go code change.

Linking from machine READMEs

Each machine package should link to this guide from its README.md so engineers planning a change have the discipline in front of them before they open a PR.

---

Crucible State Machine series: Overview & Roadmap · Kernel Core · HSM · Path Planning · JSON / Mermaid / DOT · Evolution Guide · Conformance · Phase 2