Reference

Migrations

Package Trax.StateMachineNamespace Trax.StateMachineSource Fluent.cs, SnapshotMachine.cs, MachineDefinition.cs

A stored draft carries the definition version it was written against. MigrateFrom registers a forward migration from one older version, so a draft stored at that version is upgraded when it is rehydrated instead of being refused.

Signature

IMachineBuilder<TState, TTrigger> MigrateFrom(
    int fromVersion,
    Func<string, JsonObject, MigrationResult> migrate);
 
public sealed record MigrationResult(string State, JsonObject Context);

Parameters

ParameterMeaning
fromVersionThe stored version this step upgrades. One step is registered per source version; steps chain across several versions.
migrateGiven the stored state name and context, returns the upgraded MigrationResult(string State, JsonObject Context). It computes a fresh context and does not mutate its input.

Returns

The IMachineBuilder<TState, TTrigger>, for chaining.

Behavior

Migration runs on rehydrate, before the target state's context rule is checked, so the upgraded context must satisfy the current definition's schema. Every path that reads a snapshot rehydrates it:

PathWhat happens to an older snapshot
loadSnapshotA stored older draft comes back at the current version. The row itself is rewritten only by the next save, advance or send.
advanceSnapshot, sendSnapshotThe stored older draft is upgraded first, then the trigger fires on the upgraded draft, and the result is stored at the current version.
saveSnapshotA snapshot an older client sends at an older version is upgraded, validated, and stored at the current version; the response carries the upgraded snapshot.

A draft whose version has no migration path to the current definition, or is newer than it, rehydrates as VERSION_MISMATCH.

The machines in Trax.StateMachine/conformance/machines/ pin a migration with a migration golden, machines/<machine>/migration.json: a committed set of stored older-version snapshots and the exact canonical wire each must become. The tests of both runtimes replay it, so a migration that drops, renames or reorders a surviving field fails, and the two runtimes cannot upgrade the same draft differently.

Example

The State Machine sample's checkout version 2 adds a denormalised total. A version 1 draft has none, so it would fail version 2 validation; the migration backfills it:

From Trax.Samples/samples/StateMachine/Trax.Samples.StateMachine/Machines.cs

m.Id("checkout")
    .Version(2)
    .StartsAt(CheckoutState.Cart, Fresh)
    // v1 -> v2: backfill total from the item count so a pre-total draft stays valid under v2.
    .MigrateFrom(
        1,
        (state, ctx) =>
        {
            var next = (JsonObject)ctx.DeepClone();
            next["total"] = ItemsCount(ctx) * UnitPriceCents;
            return new MigrationResult(state, next);
        }
    )

See also