Business State Machines
The Workflow\V2\StateMachine API, and the confirmed child start
(Workflow::startChild()) and DurableScope::reserveChild() it uses, are
experimental. They ship experimentally from Workflow 2.29.0, are not covered by
the package's stability guarantees, and may change in a minor release. They are
an experimental surface under the
stability levels. The rest of the
retained compensation-scope API it uses is stable since Workflow 2.33.0.
The examples on this page are repository source examples with synthetic providers. They are not installed-package or real-provider qualification. Nothing on this page implies:
- migration of an in-flight execution to a new definition, profile, rule or handler version;
- recursive or shared child machines;
- guarantees for any real payment, carrier or warehouse provider;
- that the business state-machine feature is complete or has a stable release.
This guide covers the optional business transition protocol for embedded Laravel
workflows using Workflow\V2\Workflow. It is built from existing primitives:
activities, child workflows, durable waits, replay and Saga
compensation. Existing workflows and Workflow\States\StateMachine are
unchanged.
When to use it
Use the protocol when business states have one shared meaning but the way to reach them differs between integrations:
- Shared machine meanings. One
MachineDefinitiondeclares the state meanings, transition identities, a mandatory invariant and named child slots. - Integration-specific policies. Each
PolicyProfilechooses its edges, handler versions and named conditions within that definition. One integration can require an external operation before a transition; another can already supply the evidence and skip the work. - Nested child machines. An Order can host a Shipment machine while it is in a declared state. The binding keeps the child's original identity across retries, state changes and worker restarts.
- Protected business decisions. The new business state is committed through an application-owned boundary that checks the expected state, revision and accepted cancellation.
- Retained compensation. Obligations can outlive the run that created them through retained compensation scopes.
If one workflow with a saga is enough, use Sagas and Child Workflows directly.
The transition contract
Every transition handler implements the same four methods, whatever the machine or integration:
interface TransitionStep
{
public function canTransition(TransitionContext $context): bool;
public function canExecute(TransitionContext $context): bool;
public function execute(TransitionContext $context): ExecutionReceipt;
public function compensate(TransitionContext $context, ExecutionReference $originalExecution): void;
}
canTransition()answers whether the target is already reached. It is a pure projection of the recorded target assessment.canExecute()answers whether the work is permitted. It is a pure projection of the recorded permission assessment.execute()orchestrates recorded activities or durable waits and returns anExecutionReceipt. The receipt acknowledges the work; it does not establish readiness to commit.compensate()receives the originalExecutionReference. Return only after the required effects, or their absence, are verified. Unknown or pending work must wait or fail explicitly, never return successfully.
Extend AssessedTransitionStep to implement the two guards directly from the
recorded snapshot. The runner rejects a custom guard that contradicts the
recorded assessment.
How the runner executes a transition
TransitionRunner::run() takes the workflow, the pinned profile, the original
ExecutionReference, the event, a TransitionRuntime and a closed handler
registry. It then:
- Selects the unique edge for the event and source state. No candidate returns
Unavailable; several returnAmbiguous. - Requests a recorded
beforesnapshot and, when the profile has a definition, checks its shared invariant. An unsatisfied invariant returnsBlocked; an unknown one returnsUnknown. - Checks the target guard. A satisfied target skips the work but still goes
through the protected commit; skipping does not adopt ownership of external
effects that already exist. An unknown target returns
Unknown. - Returns
Pendingwhen the edge declares no work. Otherwise it checks the execution guard and records live admission. A refusal returnsBlocked; an unknown answer returnsUnknown. - Registers the original step's compensation with native Saga, then calls
execute(). - Requests a fresh
aftersnapshot and checks the invariant and target again. A stale source state or revision returnsConflict, an unsatisfied resultPendingand an unknown oneUnknown. A satisfied target proceeds to the protected commit. - Commits through the runtime, which reports
Committed,ConflictorCancellationRequested.
TransitionStatus values are processing outcomes, not your business state
catalogue. The runner never retries a whole transition and never compensates a
blocked transition by itself. The application decides whether to wait, retry,
reconcile or compensate. A result is not permission to close the owning
workflow: keep it open while forward work or compensation obligations remain.
ActivityTransitionRuntime implements TransitionRuntime with three
application activities (snapshot, admission and commit) and an optional
MachineDefinition. It uses ordinary activity history and adds no worker
command or history event. In the configured Order/Shipment example, every
transition goes through the same runner call:
return (new TransitionRunner())->run(
$this->workflow,
$this->profile,
$execution,
Catalogue::transition($this->profile, $key)->event,
new ActivityTransitionRuntime(
SnapshotActivity::class,
AdmissionActivity::class,
CommitActivity::class,
$this->profile->definition
),
$handlers
);
The three activity classes are application code, not package classes.
Definitions, profiles and versions
A MachineDefinition holds what every integration shares. The example's
version-two definition declares four states, the transition identities, an
invariant rule and the Shipment child slot:
return new MachineDefinition(
$machine,
'2',
[
new MachineState('received', 'Business input accepted; completion has not been committed.'),
new MachineState('working', 'Original work admitted; business completion remains pending.'),
new MachineState('completed', 'The original execution has verified its required business outcome.'),
new MachineState('cancelled', 'Original compensation verified and business cancellation committed.'),
],
$machine === 'orders' ? ['begin', 'finish', 'cancel', 'reconcile'] : ['deliver'],
self::fact('model_consistent'),
$machine === 'orders' ? [
new ChildSlot('shipment', ['received', 'working'], 'shipments', '2', 'completed'),
] : []
);
PolicyProfile::forDefinition() attaches an integration's
TransitionDefinition edges and named conditions to that definition. A profile
cannot add an undeclared state or transition identity, and named profile
conditions cannot replace the shared invariant.
Versioning follows these rules:
- Fingerprints. The definition fingerprint covers state meanings, the invariant and slot declarations. The profile fingerprint covers the definition and profile metadata, the graph, condition structures, handler versions and any limits. Neither hashes PHP implementations.
- Pinned executions. An
ExecutionReferencepins the scope, business subject, execution ID, policy fingerprint, expected source state and revision. Record the selected fingerprint before work starts and supply it again on replay. Never compute it from the newest configuration when resuming. - New executions only. A new definition or profile version is selected for new executions. Rewriting a running subject's assignment changes its fingerprint, and the original execution then refuses. There is no in-flight migration API.
- Retained implementations. Keep old definitions, rules, handlers and
authorization versions deployed while their executions or retained obligations
remain recoverable. Handlers come from a closed type/version registry keyed by
TransitionDefinition::handlerKey(). Stored data cannot select a PHP class, and a missing handler fails before any application I/O.
See Versioning for the general rules of changing workflow code.
Rules, conditions and recorded facts
Configuration selects conditions; rule implementations stay trusted application
code. A RuleRegistry built in trusted bootstrap maps a rule type and version to a ConditionRule object. A
RuleReference pins the type, version and parameters, and
ConditionDefinition::rule(), all(), any() and not() combine those leaves.
A condition has at most 64 nodes.
Decisions have three values: Verdict::Satisfied, Verdict::Unsatisfied and
Verdict::Unknown. For all(), an unsatisfied child makes the group
unsatisfied; otherwise an unknown child makes it unknown. For any(), a
satisfied child makes the group satisfied; otherwise an unknown child makes it
unknown. Negating unknown stays unknown.
Facts are collected only in the recorded snapshot activity. The example's
AssessmentStore records the facts with evidence references and evaluates the
profile's target and permission conditions:
$facts = new RecordedFacts($id, $values, array_combine(array_keys($values), array_map(
static fn (string $name): string => 'recorded-fact:' . $id . ':' . $name,
array_keys($values)
)));
$registry = Catalogue::registry();
$target = $registry->evaluateCondition($profile->condition($transition->key . '.target'), $facts);
$permission = $registry->evaluateCondition($profile->condition($transition->key . '.permission'), $facts);
When the profile has a definition, the same activity evaluates
MachineDefinition::assess() and returns
MachineAssessment::fromEvaluation() as the snapshot's machineAssessment.
Retain the complete ConditionEvaluation::toArray() explanation with the
snapshot. A missing assessment, a changed definition or a changed condition
refuses before work. A recorded assessment is host evidence, not authorization:
the protected commit must still check live authority, revision and cancellation.
Deterministic replay
The protocol relies on recorded history, so the usual workflow constraints apply strictly:
- Guards and rules perform no I/O. They do not read the database, configuration, a provider or the container.
- Live reads happen inside the snapshot activity. On replay, completed activities return their recorded results; rules are not re-evaluated against live data.
- An
aftersnapshot must use a different snapshot ID and freshly collected facts.SnapshotPhaseseparatesbefore,afterandcompensationevidence, so one phase cannot stand in for another. execute()andcompensate()call activities. Wrap a synchronous provider or application handler in an activity; calling it directly from workflow code can repeat its effects during replay.- Admission records authority and permission only. It must not perform the forward business effect before Saga registration.
- Use
TransitionResult::toArray()across workflow and history boundaries. Application domain objects stay behind your step and runtime adapters.
Protected business commits
The commit activity is the application's business authority. It must:
- Bind the decision ID to its scope, subject, policy, transition and content. An exact duplicate returns the recorded result; reusing the ID for other content refuses.
- Re-check live authority, the expected source state and revision, and any accepted cancellation under the application's authoritative lock.
- Atomically record the business state, the decision and any publication intent when they share a store.
- After a lost acknowledgement, look up or retry that exact decision instead of repeating effects.
It returns a CommitResult with committed, conflict or
cancellation_requested. The last status means accepted cancellation prevented
this commit. It does not mean that compensation finished or that the business
entity is cancelled. No distributed transaction is implied between the
application store and Durable Workflow.
Child machines bound to parent states
A ChildSlot in the parent definition names the slot, its hosting states, the
child machine and definition version, and the required business outcome.
MachineDefinition::assertBinding() checks a binding against that declaration.
It performs no lookup, authorization or admission.
A BindingIdentity pins the original parent execution, namespace, parent
instance and run, slot, generation, hosting state, child workflow type, child
policy fingerprint, required outcome, input fingerprint and child options. The
generation identifies one state entry. Requests for an old generation never
redirect to a newer child after the parent changes or re-enters a state.
Starting and awaiting a child are separate transitions:
- Start. The parent reserves and admits the child, records the exact
binding, and only then commits the hosting state. If the binding is already
recorded, the step reuses it instead of starting again. With retained scopes,
DurableScope::reserveChild()returns aChildReservation, andChildReservation::start()uses the confirmed native child start.ChildReservationStore::close()later returns either the admittedChildBindingor a permanentNeverAdmittedChild. - Await. A later transition observes that same admission. It creates neither a second child nor a second compensation owner.
The example's shared step shows both transitions:
if ($key === 'begin') {
$childScope = Ownership::childScope($execution);
$reservation = $this->scope->reserveChild(
$execution->executionId . '.shipment',
$childScope,
Ownership::binding(
$execution,
$this->initialization['rootRun'],
$this->initialization['integration'],
$this->initialization['version']
)
);
$existing = Workflow::activity(BoundaryActivity::class, 'binding', [
'reservation' => $reservation->toArray(),
]);
if ($existing === null) {
$reservation->start(
$execution->subject,
$this->initialization['rootRun'],
$execution->toArray(),
$childScope->toArray()
);
$existing = Workflow::activity(BoundaryActivity::class, 'record-start', [
'reservation' => $reservation->toArray(),
]);
}
$binding = ChildBinding::fromArray($existing);
$operations[] = 'child:' . $binding->admission->childRunId;
} elseif ($key === 'finish') {
$value = Workflow::activity(BoundaryActivity::class, 'active-binding', []);
$binding = ChildBinding::fromArray($value);
$outcome = StartedChildWorkflow::fromArray($binding->admission->toArray())->await();
Workflow::activity(BoundaryActivity::class, 'outcome', [
'binding' => $value,
'outcome' => $outcome,
]);
} elseif ($key !== 'deliver') {
throw new LogicException('A proof-only transition must not dispatch work.');
}
Without a reservation, Workflow::startChild() returns a StartedChildWorkflow
receipt that a later step can await(). The parent must verify the child's
business outcome; technical child completion, an accepted signal or a timeout is
not enough. Workflow::startChild() is embedded-only; worker-protocol
execution refuses it.
Compensation and retained scopes
The runner registers the original step with native Saga before execute() can
suspend or fail. The callback captures the original execution and step, not the
receipt. During compensation, the runner requests a fresh compensation
snapshot and calls compensate() with the original execution. Use the default
sequential compensation.
A run-local Saga callback ends with its run. Retained compensation scopes
(Workflow\V2\Compensation) keep each obligation in a durable ledger, so it
can be compensated after the originating run closes. The
compensation scopes guide describes that API and
which parts of it are stable. In the examples, every external effect is registered as an
Obligation through DurableScope::execute() before it is dispatched, and a
child scope is verified before earlier parent effects are undone. The step's
own compensation then verifies only its original obligations:
public function compensate(TransitionContext $context, ExecutionReference $originalExecution): void
{
Workflow::activity(RequestScopeActivity::class, $this->identity->toArray(), $this->principal);
// Scope callbacks registered within execute() run first. Check only this step's original subset:
// verifying the whole scope here would block earlier steps before their callbacks can run.
Workflow::activity(BoundaryActivity::class, 'verify-step', [
'execution' => $originalExecution->toArray(),
'key' => $context->transition->key,
]);
}
Business cancellation is a separate decision. In the examples, a proof-only
transition commits cancelled only after the retained scope verifies. A
technical cancellation, a queued recovery request or failed compensation does
not establish it. The current retained graph has one parent/child level, at most
16 children and 256 obligations per scope. Root and child forward ownership do
not transfer to continue-as-new or redrive successors, and retention release
stays explicit.
Budgets and explicit outcomes
Trusted configuration can bound a machine:
DefinitionLimits(states,transitions,childSlots,ruleNodes) is passed toMachineDefinitionaslimits:. Each bound profile also checks its expanded source edges and total condition nodes.ExecutionLimits(commands,historyEvents,historyBytes,groupDepth) is attached withPolicyProfile::withLimits()or thelimits:argument ofPolicyProfile::forDefinition(). The command budget covers every durable suspension insideTransitionRunner, up to 4,096 commands and 64 group levels. History values are admission thresholds measured withWorkflow::historyBudgetAtStep()before each command, not absolute ceilings.
Both limits enter their fingerprints. Omitting them keeps earlier fingerprints; adding or changing a budget requires an explicitly selected version for new executions.
A budget reached during execution returns TransitionStatus::Blocked with the
reason state_machine_<dimension>_limit_exceeded. An invalid definition raises
ResourceLimitExceeded with the dimension, observed count and limit before any
handler runs. Neither outcome means that cancellation succeeded or that an
earlier external effect did not happen. Workflow::compensate() runs outside
the forward budgets.
Diagnostics
TransitionResult::toArray()returns the execution, status, reason, assessment and transition key.ConditionEvaluation::toArray()keeps the structure fingerprint, snapshot ID, rule versions, reasons, evidence references and missing facts.MachineAssessment::toArray()records the invariant decision bound to the definition and snapshot.ResourceLimitExceededexposesdimension,observedandlimit.ScopeRecovery::describe()reports the state of a retained scope, including when a fresh authorized cancellation request is needed.
Runnable examples
The examples live in the workflow repository and run against its development dependencies and test database. They use their own disposable application tables, not package migrations.
| Example | What it demonstrates |
|---|---|
| Configured Order and Shipment | Two integration profiles, prepare and imported, with the same states and one shared step. Preparation hosts Shipment in working; import hosts it in received. A proof-only reconcile edge skips work when evidence exists. Version two adds shared definitions for new subjects while version one stays pinned. Includes child reservation, retained compensation and cancellation finalization. |
| Provider-backed Order, Payment and Shipment | Three machines on the same protocol against a synthetic provider journal. Recipes cover reservation-first and payment-first checkout, refund outcomes, authorization and capture after stock or delivery, bank, COD, advance-and-balance and subscription funding, Cart leases, unit money, partial stock, returns, exchanges, carrier incidents and worker-loss recovery. |
| SQL business decisions | An application-owned protected commit with SQL fencing for cancellation, revision conflicts, authority revocation, publication intent and lost acknowledgements, plus native nested Order and Shipment compensation. |
Run the configured example's tests from the workflow repository:
vendor/bin/phpunit tests/Feature/V2/V2ConfiguredStateMachineExampleTest.php
All three use synthetic or same-database providers. They do not qualify a real carrier, payment provider or warehouse, an installed package upgrade, or in-flight migration. A real integration must supply its own idempotency, fencing and reconciliation of uncertain results.
The engine repository's business state-machine reference documents the complete contract, including the activity payload shapes. Delivery status is tracked in durable-workflow/workflow#1069.