feat: Register workflow via WorkflowDefinition instead of raw callable

[timl3136]

What changed?

• Added WorkflowDefinition class with type-safe wrapper for workflow functions, including .fn, .name, and .params properties for metadata access
• Registry now stores WorkflowDefinition internally instead of raw callables, with get_workflow() returning the typed wrapper
• Introduced WorkflowParameter dataclass for parameter introspection (name, type hints, defaults) and @defn decorator for standalone workflow definition

Why?

• Enables compile-time type checking via mypy and better IDE support, consistent with existing ActivityDefinition pattern
• Enables parameter validation, automatic API documentation, dynamic workflow discovery, and better error messages

How did you test it?
unit tests

Potential risks

Release notes

Documentation Changes

[natemort]

I think one other question is whether we want to add workflow.defn, which would be analogous to activity.defn. It defines it as a Workflow type that can later be added to a Registry.

For activities this is important because we have activity classes and interfaces, where we need to define and register them separately. That isn't strictly required for Workflows, but users might find it useful. For example, if they wanted to conditionally add a WorkflowDefinition to a registry or add it to multiple registries.

[natemort]

Nit: If the return type is the same as the input type, we can use generics to indicate that. We can do this as a followup.

[timl3136]

Thanks, I've added a generic for this

[natemort]

Nit: All of our other decorators treat the parenthesis as optional. I think there's an argument for us not doing that, but we should be consistent across all of them.

[natemort]

Nit: Maybe validate the function is async

[timl3136]

Added validation logic.

[natemort]

I don't think we need this, I think it's fine if run is in the root of the module.

If they import like this:

from cadence import workflow

Then they'd get:

@workflow.workflow.run

This does mean that it's possible for them to do from cadence.workflow import run but I think that's fine.

[timl3136]

Thanks

[natemort]

Nit: This type signature is slightly wrong. It's saying that it accepts a function with any type of inputs and returns a function with any type of inputs and the same return type as the other function. It doesn't say that they accept the same inputs.

You could use ParamSpec to represent the arguments to the Callable to enforce that they're the same, or alternatively have T represent the Callable and its arguments, rather than just its return type. Having T represent the entire Callable is probably the easiest, and can be done by adding a bound to the TypeVar.

Feel free to address later.

[timl3136]

Thanks, I add a bound to TypeVar with callable.