create explicit methods for ambiguously typed Task kwargs

[zzstoatzz]

Describe the current behavior

Problem

There are many ways to use the task decorator, whether on functions or instance methods, which today we try to handle all this with overloads.

In particular, using keyword arguments like return_state and wait_for in task calls makes proper type checking (nearly, if not) impossible. These kwargs modify the return type of a task (e.g., changing from R to State[R] when return_state=True), which breaks static type checking in mypy and pyright. This creates frustrating developer experiences and makes it difficult to rely on type checkers for preventing bugs.

state = my_task(arg1, return_state=True)  # we can't quite handle all cases with overloads

Describe the proposed behavior

Create explicit methods on Task objects that clearly indicate their return type, e.g.

• call_and_return_state
• submit_and_return_state
• existing __call__
• existing submit

Example Use

# Use explicit methods that return exactly what they say
state = my_task.call_and_return_state(...)
state = my_task.submit_and_return_state(...)

Additional context

We'll want to re-use some interface so we don't have to maintain even more methods in different places

related to #17379