Document legacy overlap delay and queue attempt limits

docs/configuration/options.md

@@ -215,3 +215,19 @@ For imported v1 failures that were recorded before an exception alias existed, `
 Final v2 writes durable exception aliases when the failure is recorded, so configure stable aliases before recording failures whose throwable classes may move later.
 
 If a replayed failure cannot be resolved through the durable `exceptions` map, the class-alias map, or the recorded class, the engine does not fall back to a generic runtime exception inside workflow code. Query replay raises `UnresolvedWorkflowFailureException`, Waterline marks the failure with `exception_replay_blocked = true`, and a worker task that hits the same gap is left failed while the run stays open. Fix the mapping and repair the run rather than relying on broad `catch (RuntimeException)` blocks to handle renamed historical failures.
+
+## Legacy workflow overlap delay {#legacy-overlap-release-delay}
+
+For applications using `Workflow\Workflow`, set `overlapReleaseAfter` to a nonnegative integer number of seconds. The default is `0`. This setting applies to contended workflow, activity, signal and child-completion queue jobs. It does not change lock expiry or activity exception backoff. `Workflow\V2\Workflow` uses task claims and does not use this middleware.
+
+```php
+use Workflow\WorkflowOptions;
+use Workflow\WorkflowStub;
+
+$workflow = WorkflowStub::make(MyLegacyWorkflow::class);
+$workflow->start('argument', new WorkflowOptions(overlapReleaseAfter: 5));
+```
+
+`WorkflowOptions::set(['overlapReleaseAfter' => 5])` accepts the same setting. The value is persisted with the run and inherited by children and continue-as-new 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 a job before its handler runs. A positive delay reduces rapid retries but cannot guarantee that a low `$tries`, `--tries`, or database queue attempt limit is safe. Choose the delay and retry budget for the expected contention duration.

i18n/de/docusaurus-plugin-content-docs/current/configuration/options.md

@@ -312,3 +312,19 @@ Eine Worker-Aufgabe mit derselben Lücke bleibt fehlgeschlagen, während die
 Ausführung offen bleibt. Korrigieren Sie die Zuordnung und reparieren Sie die
 Ausführung, statt umbenannte historische Fehler über breite
 `catch (RuntimeException)`-Blöcke behandeln zu wollen.
+
+## Wartezeit bei belegten Sperren für bisherige Workflows {#legacy-overlap-release-delay}
+
+Für Anwendungen mit `Workflow\Workflow` legt `overlapReleaseAfter` die Wartezeit als nichtnegative ganze Zahl in Sekunden fest. Der Standardwert ist `0`. Die Einstellung gilt für Queue-Jobs von Workflows, Aktivitäten, Signalen und Kindworkflow-Ergebnissen, deren Sperre belegt ist. Sie ändert weder die Gültigkeitsdauer der Sperre noch den Backoff nach Aktivitätsausnahmen. `Workflow\V2\Workflow` verwendet Task-Claims und diese Middleware nicht.
+
+```php
+use Workflow\WorkflowOptions;
+use Workflow\WorkflowStub;
+
+$workflow = WorkflowStub::make(MyLegacyWorkflow::class);
+$workflow->start('argument', new WorkflowOptions(overlapReleaseAfter: 5));
+```
+
+`WorkflowOptions::set(['overlapReleaseAfter' => 5])` akzeptiert dieselbe Einstellung. Der Wert wird mit dem Lauf gespeichert. Kindworkflows und continue-as-new übernehmen ihn, wenn kein explizites `WorkflowOptions` übergeben wird. Ein explizites Optionsobjekt ersetzt die geerbten Optionen und setzt diese Wartezeit auf null Sekunden zurück, wenn sie darin fehlt.
+
+Laravel zählt Queue-Reservierungen als Versuche, auch wenn die Middleware den Job vor der Verarbeitung zurückstellt. Eine positive Wartezeit verringert schnelle Wiederholungen, garantiert aber nicht, dass niedrige Grenzwerte für `$tries`, `--tries` oder den Versuchszähler der Datenbank-Queue ausreichen. Wählen Sie Wartezeit und Versuchslimit passend zur erwarteten Dauer der Sperrkonkurrenz.

i18n/de/source-hashes.json

@@ -9,7 +9,7 @@
   "configuration/database-connection.md": "a4657d239673a4ecdc3981bcc5a7cf33aa2d37c709768131cd5ba3292987681f",
   "configuration/ensuring-same-server.md": "6c665f37cc198c7b1a775a60a94aab5ff4e55383385e76f1834c7840559b512a",
   "configuration/microservices.md": "46dc4afa07588b78829a7e3d259177ce0cf40861f0e31b88dbb6de3a83aa5488",
-  "configuration/options.md": "b8b5f1e9f425e3a8be2e76bc6c0a75ec004567f57dfea55135831660029e1cd0",
+  "configuration/options.md": "87622f9947b0042d1680197e612daf20a54ab6292a12d30e1077ba65f411e80c",
   "configuration/pruning-workflows.md": "51366f3553f6556a15518a9c5a0ac6b009aa11ad5150269b87141b8f0adb57ea",
   "configuration/publishing-config.md": "c757acd749c0d2696a6e19484249c9298dd15970ce0cf2ae0e6d2dfd82c8b6d6",
   "constraints/activity-constraints.md": "5a953d0e95e750b6c02d1c72b72199fb3ff4687540cebc56aa3b216cf667bb05",

i18n/es/docusaurus-plugin-content-docs/current/configuration/options.md

@@ -215,3 +215,19 @@ Para fallos v1 importados que se registraron antes de existir un alias, `workflo
 La versión final de v2 escribe alias duraderos al registrar el fallo. Configura alias estables antes de registrar fallos cuyas clases de throwable puedan moverse después.
 
 Si un fallo reproducido no puede resolverse con el mapa duradero `exceptions`, el mapa de alias de clase ni la clase registrada, el motor no recurre a una excepción genérica dentro del workflow. La reproducción de consultas lanza `UnresolvedWorkflowFailureException`, Waterline marca el fallo con `exception_replay_blocked = true` y una tarea de worker que encuentre el mismo problema queda fallida mientras la ejecución permanece abierta. Corrige el mapa y repara la ejecución en lugar de usar bloques amplios `catch (RuntimeException)` para fallos históricos renombrados.
+
+## Espera por bloqueo en workflows de la API anterior {#legacy-overlap-release-delay}
+
+En aplicaciones que usan `Workflow\Workflow`, configure `overlapReleaseAfter` con un número entero de segundos mayor o igual que cero. El valor predeterminado es `0`. Se aplica a los trabajos de workflow, actividad, señal y resultado de workflow hijo que no pueden adquirir su bloqueo. No cambia la caducidad del bloqueo ni la espera tras excepciones de actividad. `Workflow\V2\Workflow` usa reservas de tareas y no utiliza este middleware.
+
+```php
+use Workflow\WorkflowOptions;
+use Workflow\WorkflowStub;
+
+$workflow = WorkflowStub::make(MyLegacyWorkflow::class);
+$workflow->start('argument', new WorkflowOptions(overlapReleaseAfter: 5));
+```
+
+`WorkflowOptions::set(['overlapReleaseAfter' => 5])` admite la misma configuración. El valor se guarda con la ejecución y se hereda en los hijos y en continue-as-new cuando no se proporciona un `WorkflowOptions` explícito. Un objeto de opciones explícito sustituye las opciones heredadas y restablece esta espera a cero si se omite.
+
+Laravel cuenta las reservas de la cola como intentos, incluso cuando el middleware devuelve el trabajo a la cola antes de ejecutarlo. Una espera positiva reduce los reintentos rápidos, pero no garantiza que un límite bajo de `$tries`, `--tries` o del contador de intentos de la cola en base de datos sea suficiente. Elija la espera y el límite de intentos según la duración prevista de la contención.

i18n/es/source-hashes.json

@@ -9,7 +9,7 @@
   "configuration/database-connection.md": "a4657d239673a4ecdc3981bcc5a7cf33aa2d37c709768131cd5ba3292987681f",
   "configuration/ensuring-same-server.md": "6c665f37cc198c7b1a775a60a94aab5ff4e55383385e76f1834c7840559b512a",
   "configuration/microservices.md": "46dc4afa07588b78829a7e3d259177ce0cf40861f0e31b88dbb6de3a83aa5488",
-  "configuration/options.md": "b8b5f1e9f425e3a8be2e76bc6c0a75ec004567f57dfea55135831660029e1cd0",
+  "configuration/options.md": "87622f9947b0042d1680197e612daf20a54ab6292a12d30e1077ba65f411e80c",
   "configuration/pruning-workflows.md": "51366f3553f6556a15518a9c5a0ac6b009aa11ad5150269b87141b8f0adb57ea",
   "configuration/publishing-config.md": "c757acd749c0d2696a6e19484249c9298dd15970ce0cf2ae0e6d2dfd82c8b6d6",
   "constraints/activity-constraints.md": "5a953d0e95e750b6c02d1c72b72199fb3ff4687540cebc56aa3b216cf667bb05",

i18n/fr/docusaurus-plugin-content-docs/current/configuration/options.md

@@ -215,3 +215,19 @@ Pour les échecs v1 importés et enregistrés avant l’existence d’un alias d
 La version finale v2 écrit les alias d’exception durables lors de l’enregistrement de l’échec. Configurez donc des alias stables avant d’enregistrer des échecs dont les classes d’exception pourraient être déplacées.
 
 Si un échec relu ne peut être résolu ni par la table durable `exceptions`, ni par les alias de classes, ni par la classe enregistrée, le moteur ne le remplace pas par une exception générique dans le code du workflow. La relecture d’une requête de lecture lève `UnresolvedWorkflowFailureException`, Waterline marque l’échec avec `exception_replay_blocked = true`, et une tâche de worker rencontrant la même absence reste en échec tandis que l’exécution reste ouverte. Corrigez l’association et réparez l’exécution au lieu de compter sur des blocs généraux `catch (RuntimeException)` pour traiter les échecs historiques renommés.
+
+## Délai en cas de verrou occupé pour les workflows historiques {#legacy-overlap-release-delay}
+
+Pour les applications utilisant `Workflow\Workflow`, définissez `overlapReleaseAfter` comme un nombre entier positif ou nul de secondes. La valeur par défaut est `0`. Ce réglage s’applique aux tâches de workflow, d’activité, de signal et de résultat enfant dont le verrou est occupé. Il ne modifie ni l’expiration des verrous ni le délai après exception d’une activité. `Workflow\V2\Workflow` utilise des prises en charge de tâches et non ce middleware.
+
+```php
+use Workflow\WorkflowOptions;
+use Workflow\WorkflowStub;
+
+$workflow = WorkflowStub::make(MyLegacyWorkflow::class);
+$workflow->start('argument', new WorkflowOptions(overlapReleaseAfter: 5));
+```
+
+`WorkflowOptions::set(['overlapReleaseAfter' => 5])` accepte le même réglage. La valeur est enregistrée avec l’exécution et transmise aux enfants et à continue-as-new si aucun `WorkflowOptions` explicite n’est fourni. Un objet d’options explicite remplace les options héritées et remet ce délai à zéro s’il est omis.
+
+Laravel compte les réservations dans la file comme des tentatives, même si le middleware libère la tâche avant son traitement. Un délai positif réduit les nouvelles tentatives immédiates, mais ne garantit pas qu’une limite basse de `$tries`, de `--tries` ou du compteur de tentatives de la file en base soit suffisante. Adaptez le délai et le nombre de tentatives à la durée de contention attendue.

i18n/fr/source-hashes.json

@@ -9,7 +9,7 @@
   "configuration/database-connection.md": "a4657d239673a4ecdc3981bcc5a7cf33aa2d37c709768131cd5ba3292987681f",
   "configuration/ensuring-same-server.md": "6c665f37cc198c7b1a775a60a94aab5ff4e55383385e76f1834c7840559b512a",
   "configuration/microservices.md": "46dc4afa07588b78829a7e3d259177ce0cf40861f0e31b88dbb6de3a83aa5488",
-  "configuration/options.md": "b8b5f1e9f425e3a8be2e76bc6c0a75ec004567f57dfea55135831660029e1cd0",
+  "configuration/options.md": "87622f9947b0042d1680197e612daf20a54ab6292a12d30e1077ba65f411e80c",
   "configuration/pruning-workflows.md": "51366f3553f6556a15518a9c5a0ac6b009aa11ad5150269b87141b8f0adb57ea",
   "configuration/publishing-config.md": "c757acd749c0d2696a6e19484249c9298dd15970ce0cf2ae0e6d2dfd82c8b6d6",
   "constraints/activity-constraints.md": "5a953d0e95e750b6c02d1c72b72199fb3ff4687540cebc56aa3b216cf667bb05",

i18n/ja/docusaurus-plugin-content-docs/current/configuration/options.md

@@ -215,3 +215,19 @@ $tasks = $bridge->poll('redis', 'default', limit: 10, namespace: 'production');
 正式版 v2 は失敗記録時に永続的な例外エイリアスを書き込みます。後で throwable クラスを移動する可能性がある失敗を記録する前に、安定したエイリアスを設定してください。
 
 リプレイする失敗を永続的な `exceptions` マップ、クラスエイリアスマップ、記録済みクラスで解決できない場合、エンジンはワークフロー内で汎用ランタイム例外にフォールバックしません。クエリのリプレイは `UnresolvedWorkflowFailureException` を投げ、Waterline は `exception_replay_blocked = true` を表示します。同じ問題に遭遇した Worker タスクは失敗したまま、実行は開いたままになります。名前を変更した過去の失敗を広い `catch (RuntimeException)` に頼って処理せず、マッピングを直して実行を修復してください。
+
+## 旧APIのワークフローでロック競合時の遅延を設定する {#legacy-overlap-release-delay}
+
+`Workflow\Workflow` を使うアプリケーションでは、`overlapReleaseAfter` に秒単位の非負整数を指定します。既定値は `0` です。この設定は、ロックを取得できないワークフロー、アクティビティ、シグナル、子ワークフローの結果通知のキュージョブに適用されます。ロックの有効期限やアクティビティ例外後のバックオフは変わりません。`Workflow\V2\Workflow` はタスクの取得権を使い、このミドルウェアは使用しません。
+
+```php
+use Workflow\WorkflowOptions;
+use Workflow\WorkflowStub;
+
+$workflow = WorkflowStub::make(MyLegacyWorkflow::class);
+$workflow->start('argument', new WorkflowOptions(overlapReleaseAfter: 5));
+```
+
+`WorkflowOptions::set(['overlapReleaseAfter' => 5])` でも同じ設定ができます。この値は実行とともに永続化され、明示的な `WorkflowOptions` を渡さなければ、子ワークフローと continue-as-new に引き継がれます。明示的なオプションオブジェクトは継承した設定を置き換え、この遅延を省略するとゼロに戻します。
+
+Laravel は、ミドルウェアがハンドラーの実行前にジョブをキューへ戻した場合も、キューの予約を試行として数えます。正の遅延は短時間の再試行を減らしますが、小さい `$tries`、`--tries`、またはデータベースキューの試行回数上限で十分とは限りません。想定するロック競合の継続時間に合わせて、遅延と試行回数を設定してください。

i18n/ja/source-hashes.json

@@ -9,7 +9,7 @@
   "configuration/database-connection.md": "a4657d239673a4ecdc3981bcc5a7cf33aa2d37c709768131cd5ba3292987681f",
   "configuration/ensuring-same-server.md": "6c665f37cc198c7b1a775a60a94aab5ff4e55383385e76f1834c7840559b512a",
   "configuration/microservices.md": "46dc4afa07588b78829a7e3d259177ce0cf40861f0e31b88dbb6de3a83aa5488",
-  "configuration/options.md": "b8b5f1e9f425e3a8be2e76bc6c0a75ec004567f57dfea55135831660029e1cd0",
+  "configuration/options.md": "87622f9947b0042d1680197e612daf20a54ab6292a12d30e1077ba65f411e80c",
   "configuration/pruning-workflows.md": "51366f3553f6556a15518a9c5a0ac6b009aa11ad5150269b87141b8f0adb57ea",
   "configuration/publishing-config.md": "c757acd749c0d2696a6e19484249c9298dd15970ce0cf2ae0e6d2dfd82c8b6d6",
   "constraints/activity-constraints.md": "5a953d0e95e750b6c02d1c72b72199fb3ff4687540cebc56aa3b216cf667bb05",

i18n/pt-BR/docusaurus-plugin-content-docs/current/configuration/options.md

@@ -215,3 +215,19 @@ Para falhas importadas da v1 que foram registradas antes de existir um alias de
 A v2 final grava aliases duráveis de exceção quando a falha é registrada. Portanto, configure aliases estáveis antes de registrar falhas cujas classes lançáveis possam mudar de localização depois.
 
 Se uma falha durante o replay não puder ser resolvida pelo mapa durável `exceptions`, pelo mapa de aliases de classe ou pela classe registrada, o mecanismo não recorre a uma exceção genérica de runtime dentro do código do workflow. O replay de consulta lança `UnresolvedWorkflowFailureException`, o Waterline marca a falha com `exception_replay_blocked = true`, e uma tarefa de worker que encontre a mesma lacuna fica com falha enquanto a execução permanece aberta. Corrija o mapeamento e repare a execução em vez de depender de blocos amplos de `catch (RuntimeException)` para tratar falhas históricas renomeadas.
+
+## Espera por bloqueio em workflows da API anterior {#legacy-overlap-release-delay}
+
+Em aplicações que usam `Workflow\Workflow`, defina `overlapReleaseAfter` como um número inteiro de segundos maior ou igual a zero. O padrão é `0`. A configuração se aplica aos jobs de workflow, atividade, sinal e resultado de workflow filho que não conseguem obter o bloqueio. Ela não altera a expiração do bloqueio nem o backoff após exceções de atividade. `Workflow\V2\Workflow` usa reservas de tarefas e não utiliza esse middleware.
+
+```php
+use Workflow\WorkflowOptions;
+use Workflow\WorkflowStub;
+
+$workflow = WorkflowStub::make(MyLegacyWorkflow::class);
+$workflow->start('argument', new WorkflowOptions(overlapReleaseAfter: 5));
+```
+
+`WorkflowOptions::set(['overlapReleaseAfter' => 5])` aceita a mesma configuração. O valor é salvo com a execução e herdado pelos filhos e por continue-as-new quando nenhum `WorkflowOptions` explícito é fornecido. Um objeto de opções explícito substitui as opções herdadas e redefine essa espera para zero se ela for omitida.
+
+O Laravel conta as reservas da fila como tentativas, mesmo quando o middleware devolve o job à fila antes da execução. Uma espera positiva reduz as novas tentativas imediatas, mas não garante que um limite baixo de `$tries`, `--tries` ou do contador de tentativas da fila em banco de dados seja suficiente. Escolha a espera e o limite de tentativas conforme a duração esperada da contenção.

i18n/pt-BR/source-hashes.json

@@ -9,7 +9,7 @@
   "configuration/database-connection.md": "a4657d239673a4ecdc3981bcc5a7cf33aa2d37c709768131cd5ba3292987681f",
   "configuration/ensuring-same-server.md": "6c665f37cc198c7b1a775a60a94aab5ff4e55383385e76f1834c7840559b512a",
   "configuration/microservices.md": "46dc4afa07588b78829a7e3d259177ce0cf40861f0e31b88dbb6de3a83aa5488",
-  "configuration/options.md": "b8b5f1e9f425e3a8be2e76bc6c0a75ec004567f57dfea55135831660029e1cd0",
+  "configuration/options.md": "87622f9947b0042d1680197e612daf20a54ab6292a12d30e1077ba65f411e80c",
   "configuration/pruning-workflows.md": "51366f3553f6556a15518a9c5a0ac6b009aa11ad5150269b87141b8f0adb57ea",
   "configuration/publishing-config.md": "c757acd749c0d2696a6e19484249c9298dd15970ce0cf2ae0e6d2dfd82c8b6d6",
   "constraints/activity-constraints.md": "5a953d0e95e750b6c02d1c72b72199fb3ff4687540cebc56aa3b216cf667bb05",