Repository navigation
2.34.0 adds one migration (#1231): workflow tasks gain lost_lease_count and
last_lease_lost_at, and run summaries gain task_attention. Every column is
nullable or has a constant default, so nothing is backfilled; run
php artisan migrate when upgrading. Definition fingerprint version 2, the
workflow task job timeout and failing a run on repeated lost leases are all
opt-in. New runs still record fingerprint version 1.
-
The business state-machine API is explicitly experimental (#1069). Every
public class, interface and enum inWorkflow\V2\StateMachine, native child
start (Workflow::startChild(),startChild()andStartedChildWorkflow) and
DurableScope::reserveChild()are marked@experimental. They may change
incompatibly in a minor release, never in a patch release.
docs/api-stability.md#state-machineslists them and the release each first
shipped in: the transition contract andTransitionRunnerin 2.23.0, and the
definitions, rules, budgets, child bindings and native child start in 2.29.0.
Docblocks and documentation only; no behavior changes. -
A workflow task that keeps losing its lease without completing no longer
retries silently forever (#1231). A lease is lost when the worker running
the task is killed, times out, or loses its connection.- Opt-in
workflows.v2.workflow_task_job_timeout_seconds
(DW_V2_WORKFLOW_TASK_JOB_TIMEOUT_SECONDS, unset by default) gives workflow
task jobs their own queue timeout, kept 10 s below the connection's
retry_after, in place of the worker's--timeout. Unset, the worker's
--timeoutapplies as before. A worker on the workflow queue logs one
warning at start when the timeout its workflow tasks run under is below
the workflow task lease. - Task repair counts each lost lease on the task (
lost_lease_count,
last_lease_lost_at). The next claim logs a typed
workflow_task_lease_lostdiagnostic. No history is written, and run
semantics are unchanged. - At three consecutive lost leases
(workflows.v2.workflow_task_lost_leases.attention_threshold), the run
summary, list items and describe carry an additivetask_attentionfield
(reason,consecutive,threshold), and operator metrics add
runs.task_attention,tasks.lease_lost_repeatedlyand
tasks.max_lost_lease_count. Repair-blocked reasons, repair attention
andcan_repairare unchanged. - Opt-in (
workflows.v2.workflow_task_lost_leases.fail_run, off by default;
boot refuses a threshold below 2): at the threshold, the next claim fails
the run with a typedWorkflowTaskLeaseLostException(task_failure)
instead of retrying. - The migration adds the columns outside a transaction under the schema
lock budget.
- Opt-in
-
A wide
all()no longer makes its workflow tasks grow with the square of the
fan-out width (#1231, #1203). A 300-member fan-out of 10 KB activities took
134 s to schedule and 58–85 s to finish on 2.32.0, so Laravel's default
60-second queue job timeout killed it on every retry. Per-member cost is now
roughly constant:- A workflow task publishes the tasks it committed in bounded batches and
refreshes each affected run summary once, instead of rebuilding the run's
whole summary, in its own transaction, for every member it published. - Replay, child-call, parallel-group, lineage and activity lookups index the
loaded history by sequence once, instead of rescanning the whole history
for every member. A child closure no longer rescans the parent's history
for every sibling. - Activity starts refresh only their own timeline points, like outcomes, and
projections skip decoding payloads that cannot name the activity or a
failure.
Recorded history and every projection row are unchanged. Each member's own
activity or child task still rebuilds its run summary once. - A workflow task publishes the tasks it committed in bounded batches and
-
Workflow definition and
await()condition fingerprints are versioned, and
a new opt-in version 2 makes comment-only and whitespace-only edits replay-safe
(#1227). The prefix names the version:- Version 1,
sha256:, hashes raw source lines, as before. Editing a comment
in a workflow class, its traits or parent workflow classes, or anawait()
condition closure changes it: a missinggetVersion()orpatched()
marker then takesDEFAULT_VERSION, and a waiting condition fails replay. - Version 2,
sha256-tokens:, hashes the PHP code tokens without comments
and whitespace, so those edits no longer change replay. - This release compares both versions, each run by the version it recorded,
and new runs still record version 1 by default. Set
DW_DEFINITION_FINGERPRINT_VERSION=v2(workflows.definition_fingerprint_version)
to record version 2, only after every worker that can claim these runs
is on this release or later. Any other value stops the application or
worker at boot; recording never fails a run over this setting. An older worker compares a version 2 run
by version 1, sees a changed definition, and takes the legacy default for
a missing marker; a newer worker would then take the current branch for
the same run. Switching back tov1is safe: existing runs keep the
version they recorded. Rolling a worker back below this release requires
draining the runs that recorded version 2 first. A later release will
make version 2 the default. - A run keeps its version for every condition wait it opens, and failed-run
redrive keeps the source run's version. Class pinning
(resolveClassForRun()), run detail drift
(workflow_definition_current_fingerprintis computed with the recorded
version, version 1 when none was recorded) and determinism diagnostics
compare by the recorded version. - Compensation root and child reservation descriptors and recovery-run
admission receipts stay version 1 under either setting, so a comment edit
to a workflow they bind still invalidates them, as before. CompiledWorkflowDefinitionuses the recording version for
source.workflow_definition_fingerprintand the default
definition_version. Underv2both becomesha256-tokens:values, so the
same code compiles to a new version string once, and comment-only edits no
longer produce a new one.
- Version 1,
-
Upgrade 2.32.0 hosts to 2.33.0. On 2.32.0, a run that waits for a signal
after it consumed a child's result receives a no-op workflow task on every
watchdog pass, for as long as it waits (#1219). The business state-machine
examples hit this: a booked Order waits forfinishafter its payment and
booking children complete, so a queue worker run with--stop-when-empty
never stops. 2.33.0 fixes it. Existing rows self-heal: the watchdog
re-projects the run before it would create a task, so the run then reads
waiting_for_signal. Recorded history is unchanged. -
CI now installs published 2.33.0 into a new Laravel application and checks
the state-machine examples across an upgrade (#1069). Provider-backed and
configured Orders are left mid-flight on queue workers with MySQL or
PostgreSQL and Redis. One has a cancellation waiting on a processing provider
refund. After the upgrade, every recorded run replays, and the Orders finish
or recover without repeating a provider effect. The job also checks that
schema rollback is refused while their scopes are retained. It checks a
package downgrade that keeps that state, followed by an upgrade that recovers
it. It runs on pull requests that change the examples, state-machine,
compensation or migration code, and on stable release tags against the
published package.docs/business-state-machines.mddescribes what it
checks. The compensation-scope and state-machine journeys now share
scripts/ci/upgrade-journey-lib.sh. -
A v1 activity whose job failed no longer runs a second time when the
workflow replays before the failure is recorded (#1241). The failure is
recorded by a separately queuedWorkflow\Exceptionjob after the activity's
unique lock is released, so a wake in between (a signal, timer or sibling
result) dispatched the activity again and the copy executed it, adding an
exception row and repeating its side effects. The failed job now marks the
activity in the cache before its lock is released. A copy that finds the mark
completes without executing, recording a result or firing activity events, and
the Exception job removes the mark once it has recorded the failure or let it
go. Recorded history, job payloads and replay are unchanged.- The mark expires after
workflows.activity_failure_mark_seconds
(DW_V1_ACTIVITY_FAILURE_MARK_SECONDS, default 3600). If the Exception job
is lost (a flushed queue, an undecryptable payload), a later wake then runs
the activity again, as before this release, instead of the workflow waiting
forever. Keep it well above the time an Exception job can wait behind
earlier pending work. - A job that times out, or exhausts its attempts after a worker crash, fails
without running the activity's catch block, so it writes no mark and the
redispatch race stays open on those paths, as before.
- The mark expires after
-
In the carrier-loss example (
examples/provider-state-machines), a refund
still processing after its last bounded wake no longer fails the Order run
(#1220). The wait makes one last check of the same refund. If the provider has
confirmed, the remedy isrefunded; otherwise it isowedwith resolution
refund-unresolved, and the Order completesunsettled. A later provider
confirmation pays that same refund exactly once, and
IncidentStore::refund($key)shows its status. The wake bound is read from
the incident's recorded initialization (Authority(..., transitWakes:),
default and maximum 32); histories recorded without it replay unchanged. A
cancellation while a full-parcel Shipment is in transit is now documented and
tested end to end (#1217). Examples only.
One new migration (2026_11_18_000100_add_lost_lease_tracking); run php artisan migrate when upgrading from 2.33.x or earlier. See CHANGELOG.md.