Skip to content

Commit a1b3eac

Browse files
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

File tree

0 commit comments

Comments
 (0)