deploy: 6c0bdbf

Author: github-actions[bot]

2.0/llms-full.txt

@@ -11569,6 +11569,11 @@ execute the same workflows.
 
 Use `DW_V2_GUARDRAILS_BOOT` in CI and deployment manifests. The older `WORKFLOW_V2_GUARDRAILS_BOOT` name is retained only so `env:audit` can point alpha-era operators at the rename; the workflow package no longer reads it as a runtime fallback.
 
+Use [Task Matching and Dispatch](/docs/2.0/polyglot/task-matching-dispatch)
+when you configure `DW_V2_MATCHING_ROLE_QUEUE_WAKE` or a dedicated
+`workflow:v2:repair-pass --loop` daemon. Those settings change where
+ready-task discovery runs, not the worker-protocol contract itself.
+
 ## Runtime Infrastructure Variables
 
 Runtime infrastructure variables are framework and dependency controls. The
@@ -14725,6 +14730,8 @@ Before polling, each worker must register its namespace, task queue, runtime,
 supported type keys, and local capacity through `POST /api/worker/register`.
 The [Namespace, Auth, And Worker Registration](/docs/2.0/polyglot/namespace-auth-workers)
 reference freezes that registration payload and the role-scoped auth contract.
+For the broader ready-task discovery and lease-assignment contract behind these
+verbs, see [Task Matching and Dispatch](/docs/2.0/polyglot/task-matching-dispatch).
 
 ## Workflow Task Bridge
 
@@ -15128,6 +15135,194 @@ $activityBridge = app(ActivityTaskBridge::class);
   activity-grade worker, bridge, and handler contracts that build on the worker
   protocol.
 
+<!-- Source: docs/polyglot/task-matching-dispatch.md -->
+
+# Task Matching and Dispatch
+
+Use this guide when you need to reason about how Durable Workflow finds ready
+work, assigns it to compatible workers, and scales that assignment path beyond
+"every node polls everything." This is the contract behind workflow-task polls,
+activity-task polls, queue wake behavior, and dedicated matching-role
+deployments.
+
+The core idea is that Durable Workflow separates two concerns:
+
+- durable history and task state stay in the database
+- task matching decides which live worker gets the next eligible task
+
+That separation matters even before you introduce a separate matching service.
+It lets operators talk about ready-task discovery, queue ownership, lease
+churn, and backpressure as one explicit role instead of as incidental side
+effects of every worker process.
+
+## What the matching role does
+
+The matching role is responsible for:
+
+- discovering ready workflow and activity tasks
+- narrowing the eligible set by namespace, connection, queue, and
+  compatibility family
+- surfacing tasks to one worker at a time
+- converting a successful claim into a lease with expiry
+- preserving the same task when a claim fails, a lease expires, or a worker
+  disappears
+- making wake and backlog state visible to operators
+
+Matching does not replace durable history, workflow replay, or task execution.
+It decides who gets a chance to execute next.
+
+## Deployment shapes
+
+Durable Workflow supports three practical shapes today:
+
+### In-worker matching
+
+This is the default shape. Worker processes long-poll for ready work and use
+claim-time fencing to ensure only one worker owns a task lease at a time.
+
+Use this when:
+
+- you run a single node or a small fleet
+- queue pressure is moderate
+- you do not need a dedicated matching daemon yet
+
+### In-server HTTP matching
+
+In standalone-server deployments, external workers reach the same matching
+contract through the worker protocol:
+
+- `POST /api/worker/workflow-tasks/poll`
+- `POST /api/worker/activity-tasks/poll`
+
+The server becomes the network entrypoint for the same ready-task discovery,
+claim, heartbeat, and completion flow.
+
+### Dedicated matching-role deployment
+
+Larger fleets can concentrate broad ready-task discovery into a dedicated
+matching-role process. The documented operator shape today is:
+
+```bash
+php artisan workflow:v2:repair-pass --loop
+```
+
+Run that daemon in a dedicated process and set
+`DW_V2_MATCHING_ROLE_QUEUE_WAKE=0` on execution-only nodes so they stop doing
+the broad queue-worker wake on every loop tick.
+
+Use this shape when:
+
+- execution nodes should focus on replay and activity execution
+- broad independent polling is creating unnecessary contention
+- operators want an explicit place to own ready-task discovery and sweep
+  cadence
+
+The dedicated role changes where matching happens, not the worker-protocol
+contract. Poll, claim, lease, and redelivery semantics stay the same.
+
+## Ready-task discovery
+
+The matching role looks for durable tasks that are actually ready to run now:
+
+- the task kind matches the poller (`workflow` or `activity`)
+- the task is in `ready` state
+- the task's `available_at` has arrived
+- namespace, queue, connection, and compatibility filters still match
+- activity polls also require a matching advertised activity type
+
+Long-poll wakeups are an acceleration path, not the correctness path. If the
+wake signal is delayed or missing, the task still becomes visible through
+durable polling. A wake failure should raise latency, not strand work.
+
+## Claim, lease, and backpressure
+
+Matching only offers an opportunity. Ownership starts when one worker
+successfully claims the task and receives a lease.
+
+That lease gives Durable Workflow its backpressure behavior:
+
+- one worker owns the task until the lease is renewed, completed, released, or
+  expired
+- a failed or stale worker does not permanently trap the task
+- redelivery is normal and must be handled as part of at-least-once execution
+- incompatible workers do not steal the lease; they get an explicit rejection
+
+Because work is lease-based, queue pressure shows up as backlog, stale leases,
+or repeated redelivery instead of as hidden in-memory loss.
+
+## Queue partitioning
+
+The main partitioning primitives are:
+
+- **namespace** for tenant or environment boundaries
+- **connection** and **queue** for work-routing boundaries
+- **compatibility family** for mixed-version routing safety
+- **activity type filters** for workers that only execute selected activities
+
+Use separate queues when you want stronger isolation, independent worker pools,
+or different downstream budgets. Use compatibility families when the same
+queue must stay live across a rollout or rollback without letting in-flight
+work drift to incompatible executors.
+
+## Wake signals and dedicated sweeps
+
+Wake signals shorten the time between "task became ready" and "a poller noticed
+it." They are not the durable source of truth.
+
+In the default shape, queue workers can emit wake signals as part of their
+normal loop. In a dedicated matching-role deployment, execution-only nodes
+disable that broad wake path and the matching daemon owns the sweep cadence
+instead.
+
+Treat these as tuning levers:
+
+- `DW_V2_MATCHING_ROLE_QUEUE_WAKE` controls whether execution nodes perform the
+  in-worker wake
+- `DW_WAKE_SIGNAL_TTL_SECONDS` controls how long wake markers remain visible
+- long-poll timeout settings control how long pollers stay parked waiting for
+  work
+
+## What operators should watch
+
+Use these surfaces together:
+
+- task-queue visibility for ready depth, active slots, and throttling
+- worker fleet visibility for active vs stale pollers on each queue
+- health and Waterline diagnostics for unhealthy tasks, stale leases, and
+  compatible-worker gaps
+- rolling-upgrade checks when mixed versions are live and matching must block
+  unsafe claims
+
+If the oldest ready-task age grows while compatible workers are available, the
+matching path is not making forward progress quickly enough. If ready tasks are
+preserved but no compatible worker can claim them, that is a compatibility
+problem, not a matching-loss problem.
+
+## When to introduce a dedicated matching role
+
+Move from default in-worker matching to a dedicated matching-role shape when:
+
+- broad polling is creating visible database or cache contention
+- execution nodes should stop paying the overhead of ready-task sweeps
+- queue fairness and dispatch ownership need to be reasoned about as one
+  explicit subsystem
+- operators want a distinct process to scale, supervise, and debug for
+  ready-task discovery
+
+Stay on the default shape when the current fleet is small and the main need is
+clear rollout and compatibility behavior rather than a new topology.
+
+## Related references
+
+- [Worker Protocol](/docs/2.0/polyglot/worker-protocol) for poll, heartbeat,
+  complete, and fail verbs
+- [Task Queue Admission](/docs/2.0/polyglot/task-queue-admission) for slot,
+  lease, and dispatch budgets on top of matching
+- [Rolling Upgrades](/docs/2.0/rolling-upgrades) for rollout procedure when
+  matching and compatibility are both in play
+- [Server Config Reference](/docs/2.0/polyglot/server-config-reference) for
+  `DW_V2_MATCHING_ROLE_QUEUE_WAKE`, poll timing, and wake-signal settings
+
 <!-- Source: docs/polyglot/task-queue-admission.md -->
 
 # Task Queue Admission
@@ -15142,6 +15337,11 @@ Task queue admission keeps one queue, tenant, or downstream dependency from cons
 
 Use admission controls when a queue is tied to a rate-limited dependency, tenants share the same server, or operators need to prove why a workflow is waiting.
 
+Admission sits on top of the matching contract. Read
+[Task Matching and Dispatch](/docs/2.0/polyglot/task-matching-dispatch) for
+how ready work is discovered and leased before these budgets decide whether the
+next task is allowed through.
+
 ## How The Budget Is Applied
 
 Workflow and activity polling starts with the workers that are currently registered for a namespace and task queue. Each worker advertises `max_concurrent_workflow_tasks` and `max_concurrent_activity_tasks`; the server sums active, non-stale workers to calculate the queue's registered slot capacity.
@@ -15683,6 +15883,13 @@ has not run yet, and start the new one. The window between the two is
 bounded by how long it takes the new container to come up; schedule
 firing resumes from the persisted state on next tick.
 
+If the rollout also introduces a dedicated matching-role deployment, make that
+topology change explicit instead of assuming every execution node will keep
+doing broad ready-task sweeps. See
+[Task Matching and Dispatch](/docs/2.0/polyglot/task-matching-dispatch) for
+the documented `workflow:v2:repair-pass --loop` plus
+`DW_V2_MATCHING_ROLE_QUEUE_WAKE=0` shape.
+
 ## Readiness and cutover
 
 Use the readiness contract — not just the liveness probe — to decide