Core concepts

Command

A command is a typed description of intent. The same command object is admitted at most once, but multiple commands of the same type may produce independent executions.

Execution

An execution is one admitted attempt to handle a command. It has its own UseCaseExecutionId, phase, result, timestamps, group identity, cancellation state, and error context. This distinction matters whenever retries, repeated input, history, or concurrent work exist.

Snapshot

UseCaseSnapshot<S> combines application state with lifecycle metadata. Reading only snapshot.state answers “what value is published?” Reading the whole snapshot also answers “what is running, which phase is active, and how did it finish?”

Phase and result

Phase describes where an execution is now. Result describes the terminal outcome. A processing execution does not have a final result yet; a finished execution must have an explicit terminal meaning.

Execution group

Commands can expose an executionKey. The runtime combines that key with the registered command lane to form a group. Processing policies compare related executions inside that group rather than accidentally serializing unrelated application work.

Hook

Hooks expose lifecycle boundaries for application policy and observability. A hook is not an alternate handler. Admission rejection, execution errors, snapshot publication, and finalization retain distinct responsibilities.