Compensation scopes are stable from 2.33.0 (#1063). The classes and members
listed in docs/api-stability.md#compensation-scopes are now @api and follow
the 2.x compatibility policy. So do recorded compensation histories, which
replay on every later 2.x release, the ledger storage, and the documented
minimum limits, which never shrink. These stay experimental and may change
in a minor release: DurableScope::reserveChild(), original root admission
(Admission\*), parallel compensation and deeper nesting.
-
Compensation scopes are stable
@api(#1063). Exactly the members listed in
docs/api-stability.md#compensation-scopesare covered:- authoring:
DurableScope,RegisteredObligation,Obligation,ScopeIdentity; - handler contract:
ScopedOperation,OperationContext,ForwardResult,
Resolution,HandlerRegistry,HandlerContractViolation; - host:
ScopeAuthorization,ScopeAuthorizationRefused,
ScopeRecovery::request()anddescribe(),ScopeRetention::release(), and
the result enums, which may gain cases in a minor release.
They now follow the 2.x compatibility policy, as do their recorded replay
identities, ledger storage and minimum limits.DurableScope::reserveChild(),
original root admission, parallel compensation and deeper nesting remain
experimental.- Upgrading from 2.29, 2.30 or 2.31. Workflow 2.32.0 changed the
then-experimental API after its independent review (#1216); the 2.32.0
section lists every change. Code written against 2.29 to 2.31 needs these
upgrade notes:Resolution::verified($evidence, true)still works and raises an
E_USER_DEPRECATEDnotice; the flag is ignored.verified($evidence, false)
returnsunknown('late-forward-possible'). Drop the second argument.OperationContext::$uncertainForwardis replaced byreconcileBeforeForward
(when executing) andforwardOutcomeUnconfirmed(when compensating).- An outcome that breaks the handler contract throws
HandlerContractViolation.
The activity fails with non-retryablescope_handler_contract_violation
instead of being reported asprovider-outcome-unknownand retried. - The forward value limit (11,264 bytes, 400 values, depth 7) applies only to
runs that record thedw.compensation.registration-checkspatch. Runs
recorded before it keep the earlier envelope limit. - The five result enums (
ScopeStatus,RecoveryRoute,NextAction,
AutomaticRecovery,ObligationStatus) may gain cases in a minor release.
Handle unknown values with a default branch. - Only
ScopeAuthorizationRefusedrefuses permanently. Any other exception
fromScopeAuthorizationis transient and retried, and automatic recovery
stays on. - The
ScopeRecoveryandScopeRetentionconstructors are@internal;
resolve both from the container.
- authoring:
-
A run waiting for a signal is no longer given a no-op workflow task on every
watchdog pass after a child closed that cannot resume it (#1219). This
affected a child started withstartChild()and not yet awaited, a child
whose result the run had already consumed, and a child that completed
inside anall()group that still needs the signal. Such a run now reads
waiting_for_signalinstead ofrepair_neededorwaiting_for_child. A
child that can still resume the run, such as a member of the same
select(), a child awaited through its handle, or a failed member of the
all(), is still repaired when its wake-up task is lost. A losing signal
wait of a decidedselect()is not treated as the run's wait. Existing
summaries are corrected the next time the run is projected, which the
watchdog does before it would create a task. Recorded history is
unchanged. -
An embedded
all()that a structural limit refuses is now refused before its
first member is written (#1232). Before, a member overpayload_size_bytes, or
past the pending activity or child count, was refused only when its turn came, so
every member before it was already written: activities were recorded
ActivityScheduledand then cancelled by the run's failure, and children were
started and left to the parent-close policy. Now the group's pending activity and
child counts and each new activity's and child's stored argument size are checked,
in member order, before any member is written. The run fails with the same typed
structural_limitfailure, and its history isWorkflowStartedthen
WorkflowFailed. A continue-as-new refused for its payload size no longer changes
the instance's workflow class first. Recorded histories are unchanged: the
partial-group shape that 2.32.0 recorded replays as before
(legacy-all-oversized-member-scheduled-then-cancelled), and the new shape is
all-oversized-member-refused-before-first-write. -
A pending-timer refusal inside
all()is unchanged in every group shape (#1232).
As for a sequentialtimer(), it escapes the workflow task, whose transaction
rolls back every member written before it, and leaves the task failed and
recoverable. It keeps precedence over a later member's refusal: the check stops at
a timer the pending-timer limit may refuse and leaves that timer and every member
after it to their own dispatch, as before. A signal or condition wait with a
timeout is counted as opening its timeout timer, so the check also stops when such
a wait would leave the timer within the limit by not opening one; the members
after it are then guarded one at a time, as before. -
Error precedence inside one
all()(#1232): when an earlier member would fail a
check that the pre-write check does not repeat (a condition that throws, or an
error while writing that member) and a later activity or child is over a
structural limit, the run now fails with the later member's structural-limit error
before anything is written. Before, the earlier member's error came first. Checks
that are repeated keep their order: an earlier invalid activity class or attempt
count, or an earlier timer over the pending-timer limit, still wins. -
The state-machine examples no longer check the result of
verifyCompensation()for a status other thanverified(#1221). That branch
could never run: the call returnsverifiedor fails its recorded activity.
The activity calls and their order are unchanged, so recorded commands are the
same. Examples only.
No new migrations. Upgrading from 2.32.x, 2.31.x, 2.30.x or 2.29.x needs no schema step.