Repository navigation
Description
Current delivery status
Updated 2026-11-19. The Workflow\V2\StateMachine API is experimental: the transition contract and TransitionRunner first shipped in 2.23.0, and definitions, rules, budgets, child bindings and Workflow::startChild() in 2.29.0. The compensation-scope API it uses is stable since 2.33.0 (#1063), except DurableScope::reserveChild(), which stays experimental. The feature is not declared complete. The original acceptance criteria below remain the completion authority. No in-flight migration or recursive-child support is implied.
Already on main before this update:
- the experimental transition protocol, pinned rules and explanations, and original-generation child reservations;
- retained child participation and protected business decisions;
- shared machine definitions and the recorded Order/Shipment example;
- profile versioning for new subjects (#1157);
- configured definition, action and history budgets (Bound configured machines and preserve recovery after budget exhaustion #1158);
- the provider-backed Order/Payment/Shipment example, covering:
- the provider journal;
- reservation-first and payment-first checkout;
- refund outcomes;
- authorization and capture after stock or after delivery;
- bank, COD, advance-and-balance and subscription funding;
- Cart leases;
- unit money on the direct-capture checkout.
Merged examples, tests and engine fixes:
-
Select original partial-stock policies in the common payment-first checkout #1197: native partial-stock selection on the payment-first checkout with unit money. Supports
fulfill-partial,wait-complete(with a fixed original deadline) andcancel-all(STK-04). -
Exercise worker loss on the common checkout and replay early cancellation delivery #1202: real worker-loss (SIGKILL) controls on that checkout (TECH-01/03/06). Includes an engine fix so query-state replay delivers a recorded cancellation to a wait that never opened.
-
Return accepted units of a delivered order through a separate native process #1207: partial customer return with physical deduction (SHP-04), with unit money on the
authorization-after-stockcapture. -
Exchange a delivered unit for another size through a separate native process #1208: same-price exchange for another size (SHP-05).
-
Settle carrier-confirmed loss or transport damage with an explicit customer remedy #1209: carrier-confirmed loss and transport damage before handover (SHP-07/08), with refund or replacement policies, a separate carrier claim and damaged-goods recovery. A cancellation during a pending remedy is refused explicitly.
-
Cover subscription period charges and refunds under real worker loss #1211, Cover admitted-but-uncalled payments and subscription races under real worker loss #1212 and Cover authorized payments, COD and carrier balances under real worker loss #1223: real worker-loss coverage for:
- subscription periods and their races (PAY-06);
- payments admitted but never sent to the provider;
- authorization, capture after delivery and void (PAY-02);
- COD (PAY-04);
- the carrier-collected balance (PAY-05).
-
Remove the unreachable verifyCompensation() status checks from the examples #1225: the unreachable
verifyCompensation()checks are removed (Remove the unreachable verifyCompensation() status checks from the state-machine examples #1221). -
Stop the watchdog re-offering waiting runs past a resolved child (#1219) #1229: engine fix so the watchdog no longer re-offers a waiting run past a resolved child (Watchdog re-creates a no-op workflow task every pass for a signal-waiting run whose never-awaited child closed #1219).
-
From Support durable Saga compensation scopes across nested workflow lifecycles #1063: Refuse whole rollbacks before any down(); cover restart and failed compensation in the Order/Shipment example (#1063) #1201/Let compensation retries outlast one crashed child attempt (#1205) #1206 add automatic cancellation finalization, and automatic compensation recovery that outlasts a crashed child attempt (Compensation attempt budget runs out before a crashed child's lease repair #1205).
-
End a still-processing transit refund with an explicit owed outcome #1222: a still-processing transit refund ends with an explicit owed outcome (Transit incident: a refund still processing after 32 wakes throws #1220).
-
Document and test cancellation of an in-transit full-parcel Order end to end #1224: in-transit full-parcel cancellation is documented and tested end to end (Provider example: cancelling an in-transit full-parcel Order fails both runs with scope_compensation_unknown #1217).
Release qualification, done:
- Full dispatch qualification of main passed: run 44509674964, all 59 non-PR jobs.
- Qualify the state-machine examples across an installed 2.32.0 upgrade #1236: an installed upgrade journey for the provider-backed and configured examples. It runs from published 2.33.0 to source, and on release tags against the published package, with MySQL or PostgreSQL and Redis queue workers. It covers:
- runs left mid-flight;
- replay without business queries or provider calls;
- recovery without repeated provider effects;
- schema rollback refused while scopes are retained;
- a package downgrade, then an upgrade again.
- The journey starts from 2.33.0 because 2.32.0 gives an Order that consumed its children and waits for a signal a no-op workflow task on every watchdog pass (Watchdog re-creates a no-op workflow task every pass for a signal-waiting run whose never-awaited child closed #1219, fixed in 2.33.0). The CHANGELOG tells 2.32.0 hosts to upgrade.
- Add the business state machines guide (durable-workflow/workflow#1069) durable-workflow.github.io#574 is merged: the business state machines guide, in all 8 languages, goes live with the next docs-site deployment.
Coverage: every PAY, STK, SHP and TECH family in the consumer matrix has native source coverage. Real process-kill coverage exists for checkout, subscriptions, PAY-02/04/05, returns, exchanges and transit incidents. These are synthetic-provider source controls, not real-provider or installed-package acceptance.
Documented open policies:
- settling the remaining units after a partial return;
- price-difference and multi-unit exchanges;
- partial parcel loss and stock deduction for a replacement;
- reactivation after a late subscription payment;
- in-transit cancellation still needs a fresh authorized request after inspection, because automatic recovery is one-shot.
Stability decision:
-
Phase A, in review. Explicitly experimental, documented accurately:
- workflow Mark the business state-machine API experimental throughout (#1069 phase A) #1242 marks every public
StateMachinetype,startChild()andStartedChildWorkflow@experimentaland adds the State machines section todocs/api-stability.md. It also corrects the first-shipped versions and the staleTransitionRunnerwording. - State that the Workflow package changes experimental APIs only in minor releases durable-workflow.github.io#577 states on the compatibility page that the Workflow package changes its experimental APIs only in minor releases. The platform
experimentallevel is unchanged.
- workflow Mark the business state-machine API experimental throughout (#1069 phase A) #1242 marks every public
-
Phase B, promotion to
@api. Waits for both of these:- named consumer acceptance from this issue's reporter, as for Support durable Saga compensation scopes across nested workflow lifecycles #1063;
- at least one release cycle with the installed upgrade journey green.
It will then ship as a promotion PR with a pinned public-surface signature test and an independent review, as Promote compensation scopes to stable API (#1063, after 2.32.0) #1214/Prepare the compensation-scope surface for promotion (#1063) #1216 did for Support durable Saga compensation scopes across nested workflow lifecycles #1063. Proposed stable surface:
- the transition contract (
TransitionStep,AssessedTransitionStep,TransitionContext,FactSnapshot,SnapshotPhase,ExecutionReceipt,ExecutionReference,TransitionResult,TransitionStatus); - definitions (
MachineDefinition,MachineState,TransitionDefinition,PolicyProfile,ConditionDefinition,RuleReference,DefinitionLimits,ExecutionLimits,ResourceLimitExceeded); - rules (
RuleRegistry,ConditionRule,RecordedFacts,Decision,Verdict,RuleEvaluation,ConditionEvaluation,MachineAssessment); - the runner (
TransitionRunner,TransitionRuntime,ActivityTransitionRuntime) andCommitResult.
Proposed guarantees: replay identities and fingerprints, deterministic replay without business queries, profile selection for new executions only, explicit budget outcomes, and protected commits.
Binding\*,ChildSlot,startChild()andreserveChild()stay experimental. Phase B offers no in-flight migration, no recursive or shared child machines, and no real-provider guarantee.
Primary owning public component
Workflow engine
User problem
We need a supported business-state-machine layer built on Durable Workflow's existing execution capabilities.
Our application processes orders across multiple sales-channel and carrier integrations. The meaning of the business states is shared, but each integration can require different allowed transitions, conditions, actions, confirmation evidence, and compensation behavior.
For example, two orders can use the same Order state machine while selecting different integration-specific implementations of a transition. One integration may require an external operation before the transition becomes possible; another may already provide the required evidence and need no action.
A state can also host a nested machine. An Order may remain in DeliveryInProgress while a Shipment machine performs its own transitions. The parent needs the child's verified business outcome and must coordinate cancellation and compensation without losing the child's identity after retries, state changes, or worker restarts.
DW already provides the underlying primitives: workflow execution, activities, durable waits, child workflows, replay, retries, versioning, and Saga compensation. We currently have to assemble their relationship with business states and transition policies ourselves.
This request is to extend DW with a reusable public contract and execution layer for these scenarios, preserving the existing runtime and APIs.
Proposed public contract
Add an optional business-state-machine capability integrated with Workflow V2. Extend existing state-machine support and reuse DW execution, history, waits, retries, and native Saga.
The names below illustrate the requested contract; they are not claims about existing APIs.
- Shared machine definition and replaceable transition policies
A machine definition declares:
- Stable machine identity and definition version.
- State identifiers and their shared meaning.
- Transition identifiers and machine-wide invariants.
- Named slots for state-bound nested machines.
A versioned policy profile supplies:
- Allowed edges within that machine's state catalogue.
- Sets of target-state conditions.
- Conditions permitting execution to start.
- One or more actions, including nested-machine operations.
- Required result evidence and compensation behavior.
- Waiting, failure, and retry-policy references.
Select the profile from trusted application context, such as the instance's integration or configuration. Different instances of the same machine can select different profiles without duplicating the runner or redefining state meanings.
Profiles cannot bypass machine-wide invariants. Configuration references registered rule/action types with validated parameters, rather than arbitrary executable code.
Pin the selected definition, profile, rules, and compensation versions. Deployment or configuration changes must not silently replace them for an active execution. Any supported migration must be explicit and preserve existing compensation obligations.
- One transition-step contract for all machine types
Preserve four business operations:
canTransition(TransitionContext $context): bool
canExecute(TransitionContext $context): bool
execute(TransitionContext $context): ExecutionReceipt
compensate(
TransitionContext $context,
ExecutionReference $originalExecution
): void
The contract must not depend on Order, Shipment, a particular integration, or an ORM model.
execute() may perform ordinary actions, start/adopt a nested machine, or durably await its result. Suspension and recovery belong to DW.
- Defined execution sequence
Event
-> resolve the instance's pinned policy
-> select a structurally applicable transition
-> [1] evaluate target-state conditions
satisfied:
skip unnecessary actions and proceed to [4]
unsatisfied:
-> evaluate execution-start permission
-> if permitted, establish execution identity and compensation coverage
-> [2] execute prescribed work
-> obtain a fresh recorded fact snapshot
-> [3] evaluate target-state conditions again
-> [4] perform a protected, idempotent business-state commit
Unavailable transitions, prohibited work, missing evidence, and unknown external outcomes must remain distinguishable. A false check must not automatically authorize an action, retry, or compensation.
When execution is unnecessary, preserve existing obligations or explicitly establish adoption responsibility for existing effects.
- Pure, explainable rule evaluation
Conditions operate on immutable, recorded facts. Evaluation exposes:
- Satisfied, unsatisfied, or unknown.
- Stable reason codes.
- Evidence references and missing facts.
- Rule/profile version and fact-snapshot identity.
- The evaluated condition structure.
The boolean methods bridge this typed evaluation; a mutable shared "last result" cache is not an acceptable result channel.
Fresh database/provider reads occur through recorded execution boundaries. Replay reuses recorded inputs. Guards do not perform I/O, dispatch actions, or wait.
If several transitions match an event, selection must follow a declared deterministic policy or report ambiguity.
- State-bound nested machines
Allow any declared parent state to host a nested machine using the same machine and transition contracts.
A durable binding records:
- Authorized application/client scope.
- Parent business instance and original owning execution.
- Binding slot and immutable generation.
- Hosting parent state.
- Child machine and business-execution identity.
- Pinned parent/child policies and required outcome.
Separate starting/adopting the child from awaiting its outcome.
For example, a transition into DeliveryInProgress can confirm the Shipment start/adoption milestone before committing the parent state. A later transition can await the same child's delivery result.
A queued request alone is not confirmed start. Retries reuse the original binding. Observation does not create another child or acquire a second compensation obligation.
Leaving the hosting state does not implicitly terminate the child or erase responsibility. The parent evaluates the child's concrete business outcome; a technically completed child run is not sufficient evidence.
- Compensation through native Saga
Compensation is a separate branch, invoked by an explicit business decision.
Identify the original execution and establish compensation coverage before external effects. Compensation must work even when execute() has not returned a receipt.
The original owning step resolves its effects; observer steps do not duplicate its undo. One step may own multiple effects, with explicit operation identity and ordering.
In sequential nested compensation:
- Request compensation of the exact bound child.
- Wait for verified resolution of its required obligations.
- Then continue earlier parent compensations.
compensate(): void succeeds only after required effects are resolved or their absence is authoritatively established. Pending, unknown, refused, and technical-failure outcomes require distinct handling.
Integrate with #1063 for retained compensation scopes and recovery after originating runs close. Preserve terminal history and original business identity.
- Cancellation, retries, and external uncertainty
Accepting business cancellation prevents new ordinary forward work and competing completion commits. Already dispatched operations remain tracked and reconciled.
Use existing DW activities, timers, retry facilities, and Saga ordering. Retry the specific safe failed operation rather than restarting an entire transition or compensation sequence.
Provide integration points for operation budgets, provider backoff, and circuit-breaker decisions. Waiting for permission is not successful execution.
Technical cancellation or timeout must not imply business cancellation success. Multi-day business waits require explicit policies independent of bounded technical cleanup.
- Persistence and inspection boundaries
Provide a persistence integration contract for:
- Expected source state and revision.
- Transition/decision identity.
- Authority and cancellation checks.
- Atomic business state, decision result, and publication intent where they share a store.
- Idempotent recovery after lost commit acknowledgement.
Cross-store execution requires an explicit durable handoff; no distributed atomicity is assumed.
Expose structured inspection data for the current business state, selected profile, blocked transition, reasons, pending work, child binding, and compensation outcome.
Business state remains distinct from workflow-run status. Application-specific states, authorization decisions, provider idempotency, and evidence validation remain application responsibilities.
Initial scope: embedded Laravel, single-state machines, and sequential nested compensation. Preserve existing workflows and avoid a separate scheduler, retry engine, or compensation executor.
Acceptance criteria
- Two integrations use the same machine and state meanings with different conditions, action sequences, allowed edges, and compensation handlers.
- Profile changes affect only explicitly selected new executions or an authorized migration; replay and outstanding compensation retain their pinned versions.
- The same four-method transition contract supports parent and child machines without entity-specific dependencies.
- Already-satisfied target conditions skip unnecessary actions.
- Execution-start refusal prevents effects; post-action checks use a fresh recorded snapshot.
- Undefined/source-ineligible transitions, business prohibition, missing evidence, and unknown outcomes produce distinguishable decisions.
- Multiple matching transitions follow deterministic selection or return an explicit ambiguity.
- A transition can execute several actions and compensate partial work when no final receipt exists.
- Nested machines can be bound to different parent states through configuration without special-casing Order or Shipment.
- Starting/adopting and awaiting a child are separate operations using the same immutable binding generation.
- Worker restart, duplicate events, and lost start acknowledgements do not create duplicate logical children or compensation owners.
- Cancellation while awaiting a child resolves required child compensation before earlier parent compensation.
- Closed-child and closed-parent recovery use the retained-scope guarantees of Support durable Saga compensation scopes across nested workflow lifecycles #1063; technical termination alone never satisfies business completion.
- Lost, delayed, or uncertain external results are reconciled before unsafe retries or successful compensation acknowledgement.
- Failed compensation preserves completed evidence and unresolved obligations; exhausted retries cannot produce a false business Cancelled state.
- Cancellation-versus-completion races and lost commit acknowledgements preserve one authoritative business decision.
- Replay does not perform unrecorded provider calls, mutable configuration reads, or live guard I/O.
- Cross-client binding substitution and stale-generation requests are rejected before protected access or effects.
- Invalid definitions, incompatible handler versions, cyclic child bindings, and configured resource limits produce explicit outcomes.
- Diagnostics explain blocked transitions and correlate business execution, child work, and compensation.
- Automated crash/race tests and a runnable two-integration example demonstrate the contract using existing DW execution facilities.
- Existing workflow, Saga, and cancellation APIs remain backward compatible.
Supporting public evidence
The requested capability builds on existing DW primitives:
-
Child Workflows documents durable parent/child execution, stable invocation identity, child handles, and outcome propagation.
-
Condition Waits documents replay-safe waiting on recorded workflow state and requires waits to execute in workflow context.
-
Versioning documents compatibility mechanisms for long-running executions. The proposed machine/profile version contract applies these guarantees to configurable business behavior.
-
Sagas documents native compensation registration and ordering. This feature should compose business transitions with that existing mechanism.
-
Cooperative cancellation documents bounded cleanup and operation policies. Business-state cancellation must preserve the distinction between technical run control and verified business resolution.
-
Issue Support durable Saga compensation scopes across nested workflow lifecycles #1063 covers retained compensation obligations and closed-run recovery. This feature should consume that contract rather than introduce a competing compensation subsystem.
These sources establish the existing execution foundation. The requested addition is a supported, composable business-state-machine API connecting those capabilities.
Dependencies and affected repositories
Primary repository:
- durable-workflow/workflow
Extend existing state-machine support with the public machine/profile/transition contracts, V2 execution integration, nested bindings, persistence boundaries, inspection data, and regression tests.
Related dependency:
- Support durable Saga compensation scopes across nested workflow lifecycles #1063 — retained Saga compensation scopes across nested workflow lifecycles.
Reuse its identity, ownership, verification, retention, and closed-run recovery guarantees. Scenarios depending on those capabilities must not be marked complete before that integration is verified.
Documentation:
- durable-workflow/durable-workflow.github.io
Document authoring contracts, profile selection/versioning, nested-machine behavior, compensation, persistence guarantees, and runnable examples.
Optional presentation follow-up:
- durable-workflow/waterline
Display business states, blocked-transition reasons, selected profiles, nested bindings, and compensation progress using the core inspection contract.
Initial compatibility boundary:
- Embedded Laravel and Workflow V2.
- Existing workflows remain usable without adopting the new state-machine layer.
- No mandatory Symfony Workflow dependency. Existing graph libraries may integrate through a defined boundary.
- Service-mode and cross-SDK support may follow separately.
- No application-specific Order/Shipment models, integration names, or business status catalogue belong in DW core.
Public intake checks
- I searched open and closed GitHub issues for an existing request.
- This request contains only public product contracts and public-safe rationale.
Activity
rmcdaniel commentedon Nov 8, 2026
Intake approved and reviewed. Maintainer triage: P2 feature, ready for contract design; owner General. This is separate from the current release work. The proposed API names remain proposals until the public contract is reviewed.
The published 2.22.0 source provides graph-edge checking in StateMachine and model-state configuration in StateConfig. The existing state-machine feature test exercises WorkflowStub. Those surfaces do not establish the additional pinned-policy, business-evidence, nested-binding and protected-commit guarantees requested here. The closed state-machine work (#333/#334) therefore does not resolve this broader request.
The first deliverable is a reviewable contract and execution protocol for embedded Laravel/V2, single-state machines and sequential nested compensation, with a two-integration worked example and an acceptance-to-test map. It will settle these boundaries before implementation:
Dependency: #1063 remains open. Retained obligations, original ownership and closed-child/closed-parent recovery must consume that contract and cannot be accepted here before their integration is verified. Definition/rule/adapter design can proceed without claiming those recovery guarantees already exist.
The implementation plan will preserve existing state-machine, workflow, Saga and cancellation APIs, avoid application-specific entities and a second scheduler/retry/compensation engine, and keep service-mode/cross-SDK and optional Waterline presentation outside the initial acceptance. Public documentation follows the reviewed core contract. No version, delivery date or new runtime behavior is committed by intake approval.
Next action — General: produce that contract/sequence and crash-race test plan after the active release qualification work, then open a draft implementation PR for the agreed first slice. This issue remains the acceptance record; its checkboxes stay unchecked until corresponding evidence exists.
chrom commentedon Nov 9, 2026
@rmcdaniel pls check MR #1070
rmcdaniel commentedon Nov 9, 2026
Intake approved by the operator for the first slice, PR #1070. General reviewed it: the design is sound, and I pushed boundary/shape-validation/experimental-marker fixes so the full matrix can run. This slice doesn't complete the proposal: state-bound child bindings, durable compensation scopes (#1063) and the two-integration example remain, as the PR's design notes say.
rmcdaniel commentedon Nov 9, 2026
Main after merge
0673e4dc: all 18 test jobs passed in push run 42670327804 (MySQL ×4, PostgreSQL ×4, MariaDB, coverage, coverage-unit, both Laravel embedded-upgrade cells, quality, regression corpus, tracing). The final aggregatebuildand Sonar jobs were never created, because GitHub has an ongoing major Actions/Checks incident (since 18:24 UTC). A fresh main run will be dispatched once Actions recovers.rmcdaniel commentedon Nov 9, 2026
Main
0673e4dcis green: run 42676776260 attempt 2 succeeded, including the aggregatebuildand the Sonar quality gate. Attempt 1 ran right after GitHub's Actions incident and had two time-limit stops (MySQL shard 0, PostgreSQL shard 2 at 96%) and one timing-sensitive watchdog test; all of them pass on rerun, and none touch the StateMachine code.42 remaining items
Share post-delivery record checks between returns and exchanges
Merge the payment-families branch into the carrier-loss branch
End every transit remedy explicitly and refuse cancellation it owns
Drive the transit incident worker-loss tests with the shared driver
Merge main into the carrier-loss branch
Weigh the transit incident feature tests by their new run times
Use fixed journal queries and named arguments in the upgrade journeys
Stop the state-machine upgrade journey before a runaway writer fills …
Report a stuck upgrade-journey worker and periodic disk usage
Report run summaries and recent tasks when an upgrade-journey worker …
Start the state-machine upgrade journey from published 2.33.0
Describe the 2.32.0 watchdog defect without a tracker number in the g…
Describe compensation scopes as stable since 2.33.0 in the state mach…
Merge pull request #574 from durable-workflow/docs/1069-state-machines
Merge pull request #1242 from durable-workflow/docs/1069-state-machin…