Configure legacy overlap-lock release delay (#903)

Add optional nonnegative overlapReleaseAfter with zero-default and serialized-options compatibility. Preserve legacy lock ownership and inheritance; keep V2 portable behavior unchanged. Refs #897.

Author: rmcdaniel

.github/workflows/php.yml

@@ -394,6 +394,20 @@ jobs:
           tests/Unit/V2/ProjectionSqliteContentionTest.php \
           --fail-on-warning --log-junit build/test-results/pr-database-queue-recovery.xml
 
+    - name: Run legacy overlap releases on a real database queue
+      env:
+        DB_CONNECTION: sqlite
+        DB_DATABASE: ${{ runner.temp }}/workflow-overlap-release.sqlite
+        CACHE_DRIVER: array
+        CACHE_STORE: array
+        QUEUE_CONNECTION: sync
+        REDIS_HOST: ''
+      run: |
+        touch "$DB_DATABASE"
+        vendor/bin/phpunit tests/Unit/WorkflowOverlapReleaseTest.php \
+          tests/Unit/WorkflowOptionsTest.php \
+          tests/Unit/V2/LegacyOverlapOptionsBoundaryTest.php --testdox --fail-on-warning
+
     - name: Run retained execution authority and process-loss controls
       run: >-
         vendor/bin/phpunit tests/Unit/V2/EmbeddedContinuationTest.php

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 2.11.0 - 2026-10-22
+
+- Add the opt-in `WorkflowOptions::overlapReleaseAfter` delay for legacy
+  workflow, activity, signal and child-completion jobs contending on overlap
+  locks. Preserve the zero default, stored options, lock ownership and expiry.
+- Preserve the delay through child inheritance and continue-as-new. Queue
+  releases still count toward Laravel attempt limits.
+
 ## 2.10.2 - 2026-10-22
 
 - Preserve recorded activity lease expiry and worker deregistration in canonical

composer.json

@@ -87,7 +87,7 @@
             "dev-main": "2.0.x-dev"
         },
         "durable-workflow": {
-            "product-train": "2.10.2",
+            "product-train": "2.11.0",
             "laravel-embedded-upgrade-contract": "resources/laravel-embedded-upgrade-contract.json",
             "laravel-dependency-security-policy": "resources/laravel-dependency-security-policy.json"
         },

docs/architecture/routing-precedence.md

@@ -133,10 +133,11 @@ The contract authorities are:
   `RoutingResolver::activityConnection`, and
   `RoutingResolver::activityQueue`. No other class is allowed to
   compute `(connection, queue)` from the same inputs.
-- **`WorkflowOptions`** — the durable wire value for workflow start
-  routing overrides. The type carries only `?string $connection` and
-  `?string $queue`. Any additional fields on `WorkflowOptions` are a
-  protocol change.
+- **`WorkflowOptions`** — workflow start routing overrides are
+  `?string $connection` and `?string $queue`. The optional nonnegative
+  `int $overlapReleaseAfter` controls only the legacy `Workflow\\Workflow`
+  queue middleware. It defaults to zero, is omitted from stored metadata at
+  that default, and does not change V2 routing or the portable service protocol.
 - **`ActivityOptions`** — the durable wire value for activity
   scheduling overrides. Routing fields on `ActivityOptions` are
   `?string $connection` and `?string $queue`; retry and timeout

docs/legacy-overlap-release.md

@@ -0,0 +1,32 @@
+# Legacy overlap release delay
+
+Applications using `Workflow\Workflow` can back off queue jobs that cannot
+acquire an overlap lock:
+
+```php
+use Workflow\WorkflowOptions;
+use Workflow\WorkflowStub;
+
+$workflow = WorkflowStub::make(MyWorkflow::class);
+$workflow->start('argument', new WorkflowOptions(overlapReleaseAfter: 5));
+```
+
+`WorkflowOptions::set(['overlapReleaseAfter' => 5])` accepts the same setting.
+The delay is a nonnegative integer in seconds. Its default is zero, preserving
+existing behavior and stored options. It applies to contended workflow,
+activity, signal and child-completion queue jobs. It does not change lock
+expiry, semaphore ownership, or activity exception backoff.
+
+The setting is saved with the run. Children and continue-as-new inherit it
+when no explicit `WorkflowOptions` is supplied. An explicit options object
+replaces inherited options, including resetting this delay to zero if omitted.
+
+Laravel counts queue reservations as attempts even when middleware releases
+the job before its handler executes. A positive delay reduces rapid retries;
+it does not make a low `$tries`, `--tries`, or database queue attempt limit
+safe for arbitrary contention. Choose the delay and retry budget for the
+expected lock duration. Keep queue visibility and worker timeout settings
+consistent with activity duration.
+
+This option belongs to the legacy API. `Workflow\V2\Workflow` uses durable
+task claims and does not use this overlap middleware.

src/Activity.php

@@ -138,7 +138,8 @@ public function middleware()
             new WithoutOverlappingMiddleware(
                 $this->storedWorkflow->id,
                 WithoutOverlappingMiddleware::ACTIVITY,
-                0,
+                $this->storedWorkflow->workflowOptions()
+->overlapReleaseAfter,
                 $this->timeout
             ),
             new ActivityMiddleware(),

src/ChildWorkflow.php

@@ -73,7 +73,13 @@ public function handle()
     public function middleware()
     {
         return [
-            new WithoutOverlappingMiddleware($this->parentWorkflow->id, WithoutOverlappingMiddleware::ACTIVITY, 0, 15),
+            new WithoutOverlappingMiddleware(
+                $this->parentWorkflow->id,
+                WithoutOverlappingMiddleware::ACTIVITY,
+                $this->parentWorkflow->workflowOptions()
+->overlapReleaseAfter,
+                15
+            ),
         ];
     }
 }

src/ChildWorkflowStub.php

@@ -121,7 +121,7 @@ public static function make($workflow, ...$arguments): PromiseInterface
             if (! $hasOptions) {
                 $options = $context->storedWorkflow->workflowOptions();
 
-                if ($options->connection !== null || $options->queue !== null) {
+                if ($options->connection !== null || $options->queue !== null || $options->overlapReleaseAfter !== 0) {
                     $arguments[] = $options;
                 }
             }

src/Signal.php

@@ -46,7 +46,8 @@ public function middleware()
             new WithoutOverlappingMiddleware(
                 $this->storedWorkflow->id,
                 WithoutOverlappingMiddleware::WORKFLOW,
-                0,
+                $this->storedWorkflow->workflowOptions()
+->overlapReleaseAfter,
                 15
             ),
         ];

src/Traits/Continues.php

@@ -67,7 +67,7 @@ public static function continueAsNew(...$arguments): PromiseInterface
             if (! collect($arguments)->contains(static fn ($argument): bool => $argument instanceof WorkflowOptions)) {
                 $options = $context->storedWorkflow->workflowOptions();
 
-                if ($options->connection !== null || $options->queue !== null) {
+                if ($options->connection !== null || $options->queue !== null || $options->overlapReleaseAfter !== 0) {
                     $arguments[] = $options;
                 }
             }