Polling, task delivery, and partition lifetime

Run pnpm matching:concurrency. The walkthrough shows a worker waiting for a Workflow Task, a task arriving through History's transfer queue, a poll deadline, namespace failover, partition reload, and an Activity that stays in flight while another Workflow completes.

A waiting poll and a backlog record are different

A worker poll carries its worker identity, queue partition, deployment version, deadline, and the generation of the loaded partition manager. It exists only while that manager is running. If a task arrives while a suitable poll waits, Matching can deliver it immediately. If no poll can accept it, Matching stores a delivery record in the backlog. engine.ts implements both paths; test/polling.test.ts checks delivery, expiry, cancellation, and child-partition forwarding.

A waiting poll answers four questions cleanly. What is running: the RPC handler fiber for the worker's poll, awaiting a Deferred under the deadline the caller sent. Who owns it: the caller owns the fiber; the partition manager owns only the registration. What is it waiting for: a sync match, backlog delivery, the deadline, or the partition's end. What stops it: delivery, an Interrupt frame from the caller's side, the clock reaching the deadline, or the manager unloading and settling every registered poll empty.

flowchart LR
  History[History transfer task] --> Processor[History queue processor]
  Processor --> Matching[Matching partition]
  Matching -->|suitable poll waiting| Worker[SDK worker]
  Matching -->|no suitable poll| Backlog[Durable backlog]
  Backlog -->|later poll| Worker

A partition manager is loaded state

Namespace failover or a change in Matching host ownership stops the old manager generation. Its waiting polls end, and its gauges are cleared. Backlog records remain in the typed database. A later request loads a new manager generation and reads that backlog. Namespace revision and host ownership generation are separate values. See partition-manager.ts and test/lifecycle.test.ts.

Dispatch does not finish an Activity

Matching asks History to record a task start before returning it to a worker. After that handoff, the Activity may still be running in the worker. History validates the attempt when completion arrives. The walkthrough holds one Activity open, completes an unrelated Workflow, then releases the Activity. This distinguishes a waiting poll, a queued delivery record, and an in-flight Activity.

Poll deadlines, workflow timers, and rate-limit windows all read the one Effect Clock; walkthroughs use real time, while focused tests use TestClock to exercise deadlines deterministically. pnpm matching:dispatch shows retryable and obsolete deliveries; pnpm matching:lifecycle shows unload and reload with backlog gauges.

Parent forwarding

A normal child partition tries its local matcher, then offers the task to its parent in a fixed binary tree (for example, 5 → 2 → 0) with MatchingService.AddWorkflowTask carrying forward_info. The parent may live on another Matching host. If no poll is waiting there, the parent answers Canceled and the child stores the task: only the partition that first received a task writes it to a backlog. The background reader later offers stored child tasks to the parent the same way.

A child poll that finds no backlog is forwarded to its parent with PollWorkflowTaskQueue and forwarded_source, and waits at the root. Only one registration exists, at the hop where the poll waits. Cancelling the original caller interrupts each RPC hop, and an unload at the root ends the poll empty. test/cluster.test.ts forwards a poll from a child partition on one host to the root on another. The toy does not model forwarder rate limits or distributed backlog readers.