Commit a1b3eac
committed
Freeze v2 task-matching and dispatch contract
Issue #581 opens Phase 3 of the v2 multi-node architecture roadmap,
which concentrates ready-task discovery, claim/lease ownership,
dispatch publication, wake notification, and queue partitioning into
one explicit contract. Product docs, CLI reasoning, Waterline
diagnostics, server deployment guidance, and test coverage need a
single reference for how ready tasks find compatible workers without
silently rerouting work or making every node poll every shared
surface.
This lands the contract doc and a pinning test.
docs/architecture/task-matching.md:
- scopes the contract to the matching role (in-worker library,
in-server HTTP, and a future dedicated service shape), ready-task
discovery, claim/lease ownership, dispatch publication, wake
notification, partition primitives, lease-driven backpressure, and
operator-visible matching state
- freezes the ready-task discovery query shape, the one-second
availability ceiling for cross-backend (notably SQLite) timestamp
drift, and the 100-row poll batch cap
- enumerates the canonical workflow claim reason codes
(task_not_found, task_not_workflow, task_not_claimable,
run_not_found, run_closed, backend_unavailable,
compatibility_blocked) and the activity claim reason codes
(task_not_activity, task_not_ready, task_not_due,
activity_execution_missing, workflow_run_missing,
backend_unsupported, compatibility_unsupported)
- names the worker-facing reason translation owned by
ActivityWorkerBridgeReason and the 5-minute workflow-task lease
duration upper bound
- defines the LongPollWakeStore snapshot/changed contract, the
60-second cache wake TTL, the per-namespace + shared channel
signalling rule, and the explicit "wake is not the correctness
boundary" guarantee
- defines connection / queue / compatibility / namespace as the four
partition primitives and explicitly excludes priority queueing,
weighted fair scheduling, and per-tenant isolation as host policy
- freezes DB::afterCommit() dispatch deferral so rolled-back tasks
are never published, and explains the equivalence of poll-mode and
queue-mode dispatch
- names the OperatorMetrics tasks/backlog/workers blocks and
OperatorQueueVisibility surfaces that operators must consume to
detect starved partitions
- documents the coupling boundary between matching and durable
history that Phase 4 will split, while keeping projection,
lifecycle dispatch, and ActivityStarted recording synchronously
visible from the worker's point of view
- defers per-worker concurrency cap enforcement to #584, the
dedicated out-of-process matching service shape to #582, cache
independence to #583, and priority/cross-cluster routing as out
of scope
- cites docs/architecture/execution-guarantees.md (Phase 1) and
docs/architecture/worker-compatibility.md (Phase 2) as the
foundations it extends
tests/Unit/V2/TaskMatchingDocumentationTest.php:
- pins required headings, terminology, partition primitives,
workflow and activity claim reason codes, dispatch-mode config
surface, canonical implementation classes, dispatch job classes,
the three deployment shapes, and the worker HTTP route surface
- asserts the one-second availability ceiling and SQLite tolerance
language, the 100-row poll cap, the snapshot/changed wake
primitives, the 60-second wake TTL, and the
"not the correctness boundary" guarantee
- asserts the 5-minute workflow-task lease language, the
lost-race-is-normal language for task_not_claimable, the
DB::afterCommit() deferral, the multi-node shared-wake-backend
requirement, and the explicit deferral of #582, #583, and #584
- asserts the contract cites both Phase 1 and Phase 2 contracts as
its foundation
Verified:
- bash scripts/check-public-boundary.sh (exit 0)
- vendor/bin/phpunit tests/Unit/V2/TaskMatchingDocumentationTest.php
(20 tests, 109 assertions, OK) against PHP 8.4
- vendor/bin/ecs check tests/Unit/V2/TaskMatchingDocumentationTest.php
(no errors)1 parent 9a1a7d3 commit a1b3eac
2 files changed
Lines changed: 924 additions & 0 deletions
0 commit comments