Operation history and undo/redo
An operation is one logical user action, independent of how many events it emits: renaming a module is one operation and one event, deleting a hierarchy is one operation and many. The operation history records each operation with its scope, actor, kind, lifecycle and the event sequence numbers it produced. The undo/redo engine builds on it to reverse and reissue an actor’s operations as new operations, so the original history is never rewritten.
Both live in Cratis.Choreography and Cratis.Choreography.Storage (namespace Cratis.Choreography.Operations). They depend on neither Orleans grains, Chronicle nor any application type.
Record an operation
Section titled “Record an operation”var entry = await history.Record("model-1", "alice", "RenameModule", async recording =>{ var sequenceNumbers = await AppendEvents(recording.Id); await recording.Associate(sequenceNumbers); // zero, one or many events, any number of calls});OperationIdis stable and generated.OperationScope,OperationActorandOperationKindare opaque strings you map your own identity onto.- Event sequence numbers are plain
ulongreferences. They never prove that reversing something is safe. - A throw inside the work records the operation as
Failed(keeping any references already made) and rethrows. IOperationHistoryalso offersGetFor(scope, actor?), in order, andGetLatest(scope, actor).- Entries are only appended; a later change touches lifecycle fields, never identity or the events.
Register storage and the history with AddCratisChoreographyInMemoryOperationHistory() and AddCratisChoreographyOperations(). Only an in-memory storage ships; implement IOperationHistoryStorage for a durable one.
Define undo and redo
Section titled “Define undo and redo”Reversal is explicit. The definition supplies the inverse command; the engine never infers one from events.
definitions.Define<RenameModule>() .UndoWith(ctx => new RenameModule(ctx.Command.Module, ctx.GetMemento<string>()!)) .CanUndoWhen(ctx => modules.Get(ctx.Command.Module).Name == ctx.Command.NewName, "The module was renamed again after this operation") .CanRedoWhen(ctx => modules.Get(ctx.Command.Module).Name == ctx.GetMemento<string>(), "The module changed since the undo");CanUndoWhenandCanRedoWhenare evaluated against current state (read throughctx.Services), so an unrelated later change does not block an undo and a conflicting one does.RedoWithis optional; without it redo reissues the original command after validation. It never replays event payloads.…Asyncvariants take asynchronous delegates.- The host can return a memento (for example the previous name) from its executor; it comes back as
ctx.GetMemento<T>().
Run it
Section titled “Run it”The host implements one interface, which keeps the engine independent of transport and Chronicle:
public class HostExecutor : IOperationExecutor{ public async Task<OperationExecutionResult> Execute(object command, OperationExecutionContext context) { var sequenceNumbers = await Dispatch(command, context.OperationId); return OperationExecutionResult.Success(sequenceNumbers); }}IOperationEngine is the facade:
| Call | Does |
|---|---|
Execute(scope, actor, command) |
Performs and records a defined operation; clears the actor’s redo stack |
Undo(scope, actor) |
Reverses the actor’s latest active operation in the scope |
Redo(scope, actor) |
Reissues the actor’s most recently undone operation |
GetHistory(scope, actor) |
The actor’s history with CanUndo/CanRedo and BlockedReason |
Each returns an OperationOutcome: Succeeded, Blocked (with a reason), NothingToUndo, NothingToRedo or Failed.
Rules the engine follows
Section titled “Rules the engine follows”- The latest operation is never skipped. If it is blocked, the outcome says why and an older operation is left alone.
- Reversal is new activity. An undo is a new
Undooperation targeting the original, with its own events; the original becomesUndone. A redo is a newRedooperation. - Multi-event operations are one unit. One inverse command, one undo operation, all its events associated with it.
- A new operation clears the actor’s redo stack (the undone operations become
Discarded). Other actors’ operations do not, but may make redo ineligible throughCanRedoWhen. - A serialized intent of each forward command is stored with its operation. Commands, mementos and outcomes serialize with System.Text.Json, so they can cross to a client as plain records.
For the frontend, see Use operation history and undo/redo in React.