horsies 0.1.0a3__py3-none-any.whl → 0.1.0a5__py3-none-any.whl

horsies/core/models/workflow.py

@@ -20,8 +20,14 @@ from typing import (
 import inspect
 import time
 from horsies.core.utils.loop_runner import LoopRunner
-from horsies.core.errors import ErrorCode, SourceLocation, ValidationReport, raise_collected
+from horsies.core.errors import (
+    ErrorCode,
+    SourceLocation,
+    ValidationReport,
+    raise_collected,
+)
 from pydantic import BaseModel
+from sqlalchemy import text
 
 if TYPE_CHECKING:
     from horsies.core.task_decorator import TaskFunction
@@ -75,11 +81,13 @@ class WorkflowStatus(str, Enum):
         return self in WORKFLOW_TERMINAL_STATES
 
 
-WORKFLOW_TERMINAL_STATES: frozenset[WorkflowStatus] = frozenset({
-    WorkflowStatus.COMPLETED,
-    WorkflowStatus.FAILED,
-    WorkflowStatus.CANCELLED,
-})
+WORKFLOW_TERMINAL_STATES: frozenset[WorkflowStatus] = frozenset(
+    {
+        WorkflowStatus.COMPLETED,
+        WorkflowStatus.FAILED,
+        WorkflowStatus.CANCELLED,
+    }
+)
 
 
 class WorkflowTaskStatus(str, Enum):
@@ -119,11 +127,13 @@ class WorkflowTaskStatus(str, Enum):
         return self in WORKFLOW_TASK_TERMINAL_STATES
 
 
-WORKFLOW_TASK_TERMINAL_STATES: frozenset[WorkflowTaskStatus] = frozenset({
-    WorkflowTaskStatus.COMPLETED,
-    WorkflowTaskStatus.FAILED,
-    WorkflowTaskStatus.SKIPPED,
-})
+WORKFLOW_TASK_TERMINAL_STATES: frozenset[WorkflowTaskStatus] = frozenset(
+    {
+        WorkflowTaskStatus.COMPLETED,
+        WorkflowTaskStatus.FAILED,
+        WorkflowTaskStatus.SKIPPED,
+    }
+)
 
 
 class OnError(str, Enum):
@@ -252,6 +262,46 @@ def _task_accepts_workflow_ctx(fn: Callable[..., Any]) -> bool:
     return 'workflow_ctx' in sig.parameters
 
 
+def _get_signature(fn: Callable[..., Any]) -> inspect.Signature | None:
+    """Return an inspectable signature for a callable, or None if unavailable."""
+    inspect_target: Callable[..., Any] = fn
+    original = getattr(fn, '_original_fn', None)
+    if callable(original):
+        inspect_target = original
+
+    try:
+        return inspect.signature(inspect_target)
+    except (TypeError, ValueError):
+        return None
+
+
+def _signature_accepts_kwargs(sig: inspect.Signature) -> bool:
+    """Return True if the signature allows **kwargs."""
+    return any(
+        param.kind == inspect.Parameter.VAR_KEYWORD
+        for param in sig.parameters.values()
+    )
+
+
+def _valid_kwarg_names(
+    sig: inspect.Signature, *, exclude: set[str] | None = None
+) -> set[str]:
+    """
+    Return names that are valid to pass by keyword.
+
+    Excludes positional-only params and *args/**kwargs.
+    """
+    names = {
+        param.name
+        for param in sig.parameters.values()
+        if param.kind
+        in (inspect.Parameter.POSITIONAL_OR_KEYWORD, inspect.Parameter.KEYWORD_ONLY)
+    }
+    if exclude:
+        names -= exclude
+    return names
+
+
 NODE_ID_PATTERN = re.compile(r'^[A-Za-z0-9_\-:.]+$')
 
 
@@ -298,6 +348,10 @@ class TaskNode(Generic[OkT_co]):
 
     fn: TaskFunction[Any, OkT_co]
     args: tuple[Any, ...] = ()
+    """
+    - Positional arguments passed to the task function
+    - Not allowed when args_from or workflow_ctx_from are set; use kwargs instead
+    """
     kwargs: dict[str, Any] = field(default_factory=lambda: {})
     waits_for: Sequence['TaskNode[Any] | SubWorkflowNode[Any]'] = field(
         default_factory=lambda: [],
@@ -441,6 +495,7 @@ class SubWorkflowNode(Generic[OkT_co]):
     args: tuple[Any, ...] = ()
     """
     - Positional arguments passed to workflow_def.build_with(app, *args, **kwargs)
+    - Not allowed when args_from or workflow_ctx_from are set; use kwargs instead
     """
 
     kwargs: dict[str, Any] = field(default_factory=lambda: {})
@@ -542,11 +597,10 @@ class SubWorkflowNode(Generic[OkT_co]):
         return NodeKey(self.node_id)
 
 
-
 AnyNode = TaskNode[Any] | SubWorkflowNode[Any]
-'''
+"""
 Type alias for any node type
-'''
+"""
 
 # =============================================================================
 # NodeKey (typed, stable id)
@@ -711,6 +765,12 @@ class WorkflowSpec:
             report.add(error)
         for error in self._collect_workflow_ctx_from_errors():
             report.add(error)
+        for error in self._collect_args_with_injection_errors():
+            report.add(error)
+        for error in self._collect_invalid_kwargs_errors():
+            report.add(error)
+        for error in self._collect_missing_required_param_errors():
+            report.add(error)
         for error in self._collect_output_errors():
             report.add(error)
         for error in self._collect_success_policy_errors():
@@ -752,66 +812,82 @@ class WorkflowSpec:
             node_id_from_workflow_name = task.node_id is None
             if node_id_from_workflow_name:
                 if task.index is None:
-                    errors.append(WorkflowValidationError(
-                        message='TaskNode index is not set before assigning node_id',
-                        code=ErrorCode.WORKFLOW_INVALID_NODE_ID,
-                    ))
+                    errors.append(
+                        WorkflowValidationError(
+                            message='TaskNode index is not set before assigning node_id',
+                            code=ErrorCode.WORKFLOW_INVALID_NODE_ID,
+                        )
+                    )
                     continue
                 task.node_id = f'{slugify(self.name)}:{task.index}'
 
             node_id = task.node_id
             if node_id is None or not node_id.strip():
-                errors.append(WorkflowValidationError(
-                    message='TaskNode node_id must be a non-empty string',
-                    code=ErrorCode.WORKFLOW_INVALID_NODE_ID,
-                ))
+                errors.append(
+                    WorkflowValidationError(
+                        message='TaskNode node_id must be a non-empty string',
+                        code=ErrorCode.WORKFLOW_INVALID_NODE_ID,
+                    )
+                )
                 continue
             if len(node_id) > 128:
                 if node_id_from_workflow_name:
-                    errors.append(WorkflowValidationError(
-                        message='workflow name too long',
-                        code=ErrorCode.WORKFLOW_INVALID_NODE_ID,
-                        notes=[
-                            f"workflow name: '{self.name}'",
-                            f"derived node_id would be {len(node_id)} characters (max 128)",
-                        ],
-                        help_text='use a shorter workflow name',
-                    ))
+                    errors.append(
+                        WorkflowValidationError(
+                            message='workflow name too long',
+                            code=ErrorCode.WORKFLOW_INVALID_NODE_ID,
+                            notes=[
+                                f"workflow name: '{self.name}'",
+                                f'derived node_id would be {len(node_id)} characters (max 128)',
+                            ],
+                            help_text='use a shorter workflow name',
+                        )
+                    )
                 else:
-                    errors.append(WorkflowValidationError(
-                        message='TaskNode node_id exceeds 128 characters',
-                        code=ErrorCode.WORKFLOW_INVALID_NODE_ID,
-                        notes=[f"node_id '{node_id}' has {len(node_id)} characters"],
-                        help_text='use a shorter node_id (max 128 characters)',
-                    ))
+                    errors.append(
+                        WorkflowValidationError(
+                            message='TaskNode node_id exceeds 128 characters',
+                            code=ErrorCode.WORKFLOW_INVALID_NODE_ID,
+                            notes=[
+                                f"node_id '{node_id}' has {len(node_id)} characters"
+                            ],
+                            help_text='use a shorter node_id (max 128 characters)',
+                        )
+                    )
                 continue
             if NODE_ID_PATTERN.match(node_id) is None:
                 if node_id_from_workflow_name:
                     # This should never happen since slugify() sanitizes the name
-                    errors.append(WorkflowValidationError(
-                        message='workflow name produced invalid characters (internal error)',
-                        code=ErrorCode.WORKFLOW_INVALID_NODE_ID,
-                        notes=[
-                            f"workflow name: '{self.name}'",
-                            f"derived node_id: '{node_id}'",
-                            'slugify() failed to sanitize the name',
-                        ],
-                        help_text='please report this bug',
-                    ))
+                    errors.append(
+                        WorkflowValidationError(
+                            message='workflow name produced invalid characters (internal error)',
+                            code=ErrorCode.WORKFLOW_INVALID_NODE_ID,
+                            notes=[
+                                f"workflow name: '{self.name}'",
+                                f"derived node_id: '{node_id}'",
+                                'slugify() failed to sanitize the name',
+                            ],
+                            help_text='please report this bug',
+                        )
+                    )
                 else:
-                    errors.append(WorkflowValidationError(
-                        message='TaskNode node_id contains invalid characters',
-                        code=ErrorCode.WORKFLOW_INVALID_NODE_ID,
-                        notes=[f"node_id '{node_id}'"],
-                        help_text='node_id must match pattern: [A-Za-z0-9_\\-:.]+',
-                    ))
+                    errors.append(
+                        WorkflowValidationError(
+                            message='TaskNode node_id contains invalid characters',
+                            code=ErrorCode.WORKFLOW_INVALID_NODE_ID,
+                            notes=[f"node_id '{node_id}'"],
+                            help_text='node_id must match pattern: [A-Za-z0-9_\\-:.]+',
+                        )
+                    )
                 continue
             if node_id in seen_ids:
-                errors.append(WorkflowValidationError(
-                    message=f"duplicate node_id '{node_id}'",
-                    code=ErrorCode.WORKFLOW_DUPLICATE_NODE_ID,
-                    help_text='each TaskNode must have a unique node_id within the workflow',
-                ))
+                errors.append(
+                    WorkflowValidationError(
+                        message=f"duplicate node_id '{node_id}'",
+                        code=ErrorCode.WORKFLOW_DUPLICATE_NODE_ID,
+                        help_text='each TaskNode must have a unique node_id within the workflow',
+                    )
+                )
             seen_ids.add(node_id)
         return errors
 
@@ -822,28 +898,32 @@ class WorkflowSpec:
         # 1. Check for roots (tasks with no dependencies)
         roots = [t for t in self.tasks if not t.waits_for]
         if not roots:
-            errors.append(WorkflowValidationError(
-                message='no root tasks found',
-                code=ErrorCode.WORKFLOW_NO_ROOT_TASKS,
-                notes=[
-                    'all tasks have dependencies, creating an impossible start condition',
-                ],
-                help_text='at least one task must have empty waits_for list',
-            ))
+            errors.append(
+                WorkflowValidationError(
+                    message='no root tasks found',
+                    code=ErrorCode.WORKFLOW_NO_ROOT_TASKS,
+                    notes=[
+                        'all tasks have dependencies, creating an impossible start condition',
+                    ],
+                    help_text='at least one task must have empty waits_for list',
+                )
+            )
 
         # 2. Validate dependency references exist in workflow
         task_ids = set(id(t) for t in self.tasks)
         for task in self.tasks:
             for dep in task.waits_for:
                 if id(dep) not in task_ids:
-                    errors.append(WorkflowValidationError(
-                        message='dependency references task not in workflow',
-                        code=ErrorCode.WORKFLOW_INVALID_DEPENDENCY,
-                        notes=[
-                            f"task '{task.name}' waits for a TaskNode not in this workflow",
-                        ],
-                        help_text='ensure all dependencies are included in the workflow tasks list',
-                    ))
+                    errors.append(
+                        WorkflowValidationError(
+                            message='dependency references task not in workflow',
+                            code=ErrorCode.WORKFLOW_INVALID_DEPENDENCY,
+                            notes=[
+                                f"task '{task.name}' waits for a TaskNode not in this workflow",
+                            ],
+                            help_text='ensure all dependencies are included in the workflow tasks list',
+                        )
+                    )
 
         # 3. Cycle detection (Kahn's algorithm) over valid dependencies only
         in_degree: dict[int, int] = {}
@@ -880,12 +960,14 @@ class WorkflowSpec:
                             queue.append(task_idx)
 
         if visited != len(self.tasks):
-            errors.append(WorkflowValidationError(
-                message='cycle detected in workflow DAG',
-                code=ErrorCode.WORKFLOW_CYCLE_DETECTED,
-                notes=['workflows must be acyclic directed graphs (DAG)'],
-                help_text='remove circular dependencies between tasks',
-            ))
+            errors.append(
+                WorkflowValidationError(
+                    message='cycle detected in workflow DAG',
+                    code=ErrorCode.WORKFLOW_CYCLE_DETECTED,
+                    notes=['workflows must be acyclic directed graphs (DAG)'],
+                    help_text='remove circular dependencies between tasks',
+                )
+            )
 
         return errors
 
@@ -896,15 +978,17 @@ class WorkflowSpec:
             deps_ids = set(id(d) for d in task.waits_for)
             for kwarg_name, source_node in task.args_from.items():
                 if id(source_node) not in deps_ids:
-                    errors.append(WorkflowValidationError(
-                        message='args_from references task not in waits_for',
-                        code=ErrorCode.WORKFLOW_INVALID_ARGS_FROM,
-                        notes=[
-                            f"task '{task.name}' args_from['{kwarg_name}'] references '{source_node.name}'",
-                            f"'{source_node.name}' must be in waits_for to inject its result",
-                        ],
-                        help_text=f"add '{source_node.name}' to waits_for list",
-                    ))
+                    errors.append(
+                        WorkflowValidationError(
+                            message='args_from references task not in waits_for',
+                            code=ErrorCode.WORKFLOW_INVALID_ARGS_FROM,
+                            notes=[
+                                f"task '{task.name}' args_from['{kwarg_name}'] references '{source_node.name}'",
+                                f"'{source_node.name}' must be in waits_for to inject its result",
+                            ],
+                            help_text=f"add '{source_node.name}' to waits_for list",
+                        )
+                    )
         return errors
 
     def _collect_workflow_ctx_from_errors(self) -> list[WorkflowValidationError]:
@@ -916,15 +1000,17 @@ class WorkflowSpec:
             deps_ids = set(id(d) for d in node.waits_for)
             for ctx_node in node.workflow_ctx_from:
                 if id(ctx_node) not in deps_ids:
-                    errors.append(WorkflowValidationError(
-                        message='workflow_ctx_from references task not in waits_for',
-                        code=ErrorCode.WORKFLOW_INVALID_CTX_FROM,
-                        notes=[
-                            f"node '{node.name}' references '{ctx_node.name}'",
-                            f"'{ctx_node.name}' must be in waits_for to use in workflow_ctx_from",
-                        ],
-                        help_text=f"add '{ctx_node.name}' to waits_for list",
-                    ))
+                    errors.append(
+                        WorkflowValidationError(
+                            message='workflow_ctx_from references task not in waits_for',
+                            code=ErrorCode.WORKFLOW_INVALID_CTX_FROM,
+                            notes=[
+                                f"node '{node.name}' references '{ctx_node.name}'",
+                                f"'{ctx_node.name}' must be in waits_for to use in workflow_ctx_from",
+                            ],
+                            help_text=f"add '{ctx_node.name}' to waits_for list",
+                        )
+                    )
 
             # Only check function parameter for TaskNode (SubWorkflowNode has no fn)
             if isinstance(node, SubWorkflowNode):
@@ -936,21 +1022,187 @@ class WorkflowSpec:
                 original_fn = getattr(task.fn, '_original_fn', task.fn)
                 fn_location = SourceLocation.from_function(original_fn)
 
-                errors.append(WorkflowValidationError(
-                    message='workflow_ctx_from declared but function missing workflow_ctx param',
-                    code=ErrorCode.WORKFLOW_CTX_PARAM_MISSING,
-                    location=fn_location,  # May be None for non-function callables
+                errors.append(
+                    WorkflowValidationError(
+                        message='workflow_ctx_from declared but function missing workflow_ctx param',
+                        code=ErrorCode.WORKFLOW_CTX_PARAM_MISSING,
+                        location=fn_location,  # May be None for non-function callables
+                        notes=[
+                            f"workflow '{self.name}'\n"
+                            f"TaskNode '{task.name}' declares workflow_ctx_from=[...]\n"
+                            f"but function '{task.name}' has no workflow_ctx parameter",
+                        ],
+                        help_text=(
+                            'either:\n'
+                            '  1. add `workflow_ctx: WorkflowContext | None` param to the function above if needs context\n'
+                            '  2. remove `workflow_ctx_from` from the TaskNode definition if this was a mistake'
+                        ),
+                    )
+                )
+        return errors
+
+    def _collect_args_with_injection_errors(self) -> list[WorkflowValidationError]:
+        """Reject positional args when args_from/workflow_ctx_from are set."""
+        errors: list[WorkflowValidationError] = []
+        for node in self.tasks:
+            if not node.args:
+                continue
+            has_args_from = bool(node.args_from)
+            has_ctx_from = node.workflow_ctx_from is not None
+            if not has_args_from and not has_ctx_from:
+                continue
+
+            injected_sources: list[str] = []
+            if has_args_from:
+                injected_sources.append('args_from')
+            if has_ctx_from:
+                injected_sources.append('workflow_ctx_from')
+
+            injected_str = ' and '.join(injected_sources)
+
+            errors.append(
+                WorkflowValidationError(
+                    message=(
+                        'positional args not allowed when using args_from or workflow_ctx_from'
+                    ),
+                    code=ErrorCode.WORKFLOW_ARGS_WITH_INJECTION,
                     notes=[
-                        f"workflow '{self.name}'\n"
-                        f"TaskNode '{task.name}' declares workflow_ctx_from=[...]\n"
-                        f"but function '{task.name}' has no workflow_ctx parameter",
+                        f"node '{node.name}' sets args=(...) and also {injected_str}",
+                        'positional args are only supported when args_from/workflow_ctx_from are not used',
                     ],
                     help_text=(
-                        'either:\n'
-                        '  1. add `workflow_ctx: WorkflowContext | None` param to the function above if needs context\n'
-                        '  2. remove `workflow_ctx_from` from the TaskNode definition if this was a mistake'
+                        'move static inputs into kwargs=... and reserve args_from/workflow_ctx_from '
+                        'for injected values'
                     ),
-                ))
+                )
+            )
+        return errors
+
+    def _collect_invalid_kwargs_errors(self) -> list[WorkflowValidationError]:
+        """Validate kwargs/args_from keys match function parameter names."""
+        errors: list[WorkflowValidationError] = []
+        for node in self.tasks:
+            if not node.kwargs and not node.args_from:
+                continue
+
+            # Get the function to inspect (TaskNode vs SubWorkflowNode)
+            if isinstance(node, TaskNode):
+                fn = node.fn
+                exclude_names: set[str] = set()
+            else:
+                # SubWorkflowNode - validate against build_with signature
+                fn = node.workflow_def.build_with
+                exclude_names = {'app', 'cls'}
+
+            sig = _get_signature(fn)
+            if sig is None:
+                continue  # Can't validate (uninspectable)
+
+            if _signature_accepts_kwargs(sig):
+                continue  # Accepts **kwargs, any key is valid
+
+            valid_names = _valid_kwarg_names(sig, exclude=exclude_names)
+
+            invalid_kwargs = set(node.kwargs.keys()) - valid_names
+            invalid_args_from = set(node.args_from.keys()) - valid_names
+            if not invalid_kwargs and not invalid_args_from:
+                continue
+
+            notes: list[str] = []
+            if invalid_kwargs:
+                notes.append(
+                    f"node '{node.name}' has unknown kwargs: {sorted(invalid_kwargs)}"
+                )
+            if invalid_args_from:
+                notes.append(
+                    f"node '{node.name}' has unknown args_from keys: {sorted(invalid_args_from)}"
+                )
+            notes.append(f"valid parameters: {sorted(valid_names)}")
+
+            errors.append(
+                WorkflowValidationError(
+                    message='invalid kwarg key(s) for callable signature',
+                    code=ErrorCode.WORKFLOW_INVALID_KWARG_KEY,
+                    notes=notes,
+                    help_text='check for typos in kwarg or args_from keys',
+                )
+            )
+        return errors
+
+    def _collect_missing_required_param_errors(self) -> list[WorkflowValidationError]:
+        """Validate required parameters are provided via args/kwargs/args_from."""
+        errors: list[WorkflowValidationError] = []
+        for node in self.tasks:
+            # Get the function to inspect (TaskNode vs SubWorkflowNode)
+            if isinstance(node, TaskNode):
+                fn = node.fn
+                args_provided = list(node.args)
+                injected_kwargs: set[str] = set()
+            else:
+                fn = node.workflow_def.build_with
+                # build_with(app, *args, **kwargs) always provides the first positional
+                args_provided = [object(), *node.args]
+                injected_kwargs = set()
+
+            sig = _get_signature(fn)
+            if sig is None:
+                continue  # Can't validate
+
+            provided_kwargs = set(node.kwargs.keys()) | set(node.args_from.keys())
+
+            # Auto-injected workflow context for TaskNode when workflow_ctx_from is set
+            if isinstance(node, TaskNode):
+                if node.workflow_ctx_from is not None and 'workflow_ctx' in sig.parameters:
+                    injected_kwargs.add('workflow_ctx')
+                # WorkflowMeta is auto-injected if declared
+                if 'workflow_meta' in sig.parameters:
+                    injected_kwargs.add('workflow_meta')
+
+            provided_kwargs |= injected_kwargs
+
+            missing: list[str] = []
+            consumed_positional = 0
+
+            for param in sig.parameters.values():
+                if param.kind in (
+                    inspect.Parameter.VAR_POSITIONAL,
+                    inspect.Parameter.VAR_KEYWORD,
+                ):
+                    continue  # *args/**kwargs do not require values
+                if param.default is not inspect.Parameter.empty:
+                    continue  # optional
+
+                if param.kind == inspect.Parameter.POSITIONAL_ONLY:
+                    if consumed_positional < len(args_provided):
+                        consumed_positional += 1
+                        continue
+                    missing.append(param.name)
+                elif param.kind == inspect.Parameter.POSITIONAL_OR_KEYWORD:
+                    if consumed_positional < len(args_provided):
+                        consumed_positional += 1
+                        continue
+                    if param.name in provided_kwargs:
+                        continue
+                    missing.append(param.name)
+                elif param.kind == inspect.Parameter.KEYWORD_ONLY:
+                    if param.name in provided_kwargs:
+                        continue
+                    missing.append(param.name)
+
+            if not missing:
+                continue
+
+            target = 'task function' if isinstance(node, TaskNode) else 'build_with'
+            errors.append(
+                WorkflowValidationError(
+                    message=f'missing required parameters for {target}',
+                    code=ErrorCode.WORKFLOW_MISSING_REQUIRED_PARAMS,
+                    notes=[
+                        f"node '{node.name}' missing required parameter(s): {sorted(missing)}",
+                    ],
+                    help_text='provide required params via args=..., kwargs=..., or args_from',
+                )
+            )
         return errors
 
     def _collect_output_errors(self) -> list[WorkflowValidationError]:
@@ -960,9 +1212,11 @@ class WorkflowSpec:
             return errors
         task_ids = set(id(t) for t in self.tasks)
         if id(self.output) not in task_ids:
-            errors.append(WorkflowValidationError(
-                f"Output task '{self.output.name}' is not in workflow",
-            ))
+            errors.append(
+                WorkflowValidationError(
+                    f"Output task '{self.output.name}' is not in workflow",
+                )
+            )
         return errors
 
     def _collect_success_policy_errors(self) -> list[WorkflowValidationError]:
@@ -973,9 +1227,11 @@ class WorkflowSpec:
 
         # Validate cases list is not empty
         if not self.success_policy.cases:
-            errors.append(WorkflowValidationError(
-                'SuccessPolicy must have at least one SuccessCase',
-            ))
+            errors.append(
+                WorkflowValidationError(
+                    'SuccessPolicy must have at least one SuccessCase',
+                )
+            )
             return errors
 
         task_ids = set(id(t) for t in self.tasks)
@@ -983,22 +1239,28 @@ class WorkflowSpec:
         # Validate each success case
         for i, case in enumerate(self.success_policy.cases):
             if not case.required:
-                errors.append(WorkflowValidationError(
-                    f'SuccessCase[{i}] has no required tasks',
-                ))
+                errors.append(
+                    WorkflowValidationError(
+                        f'SuccessCase[{i}] has no required tasks',
+                    )
+                )
             for task in case.required:
                 if id(task) not in task_ids:
-                    errors.append(WorkflowValidationError(
-                        f"SuccessCase[{i}] required task '{task.name}' is not in workflow",
-                    ))
+                    errors.append(
+                        WorkflowValidationError(
+                            f"SuccessCase[{i}] required task '{task.name}' is not in workflow",
+                        )
+                    )
 
         # Validate optional tasks
         if self.success_policy.optional:
             for task in self.success_policy.optional:
                 if id(task) not in task_ids:
-                    errors.append(WorkflowValidationError(
-                        f"SuccessPolicy optional task '{task.name}' is not in workflow",
-                    ))
+                    errors.append(
+                        WorkflowValidationError(
+                            f"SuccessPolicy optional task '{task.name}' is not in workflow",
+                        )
+                    )
 
         return errors
 
@@ -1008,26 +1270,34 @@ class WorkflowSpec:
         for task in self.tasks:
             if task.join == 'quorum':
                 if task.min_success is None:
-                    errors.append(WorkflowValidationError(
-                        f"Task '{task.name}' has join='quorum' but min_success is not set",
-                    ))
+                    errors.append(
+                        WorkflowValidationError(
+                            f"Task '{task.name}' has join='quorum' but min_success is not set",
+                        )
+                    )
                 elif task.min_success < 1:
-                    errors.append(WorkflowValidationError(
-                        f"Task '{task.name}' min_success must be >= 1, got {task.min_success}",
-                    ))
+                    errors.append(
+                        WorkflowValidationError(
+                            f"Task '{task.name}' min_success must be >= 1, got {task.min_success}",
+                        )
+                    )
                 else:
                     dep_count = len(task.waits_for)
                     if task.min_success > dep_count:
-                        errors.append(WorkflowValidationError(
-                            f"Task '{task.name}' min_success ({task.min_success}) exceeds "
-                            f'dependency count ({dep_count})',
-                        ))
+                        errors.append(
+                            WorkflowValidationError(
+                                f"Task '{task.name}' min_success ({task.min_success}) exceeds "
+                                f'dependency count ({dep_count})',
+                            )
+                        )
             elif task.join in ('all', 'any'):
                 if task.min_success is not None:
-                    errors.append(WorkflowValidationError(
-                        f"Task '{task.name}' has min_success set but join='{task.join}' "
-                        "(min_success is only used with join='quorum')",
-                    ))
+                    errors.append(
+                        WorkflowValidationError(
+                            f"Task '{task.name}' has min_success set but join='{task.join}' "
+                            "(min_success is only used with join='quorum')",
+                        )
+                    )
         return errors
 
     def _validate_conditions(self) -> None:
@@ -1057,15 +1327,17 @@ class WorkflowSpec:
             """DFS visit with cycle detection via recursion stack."""
             if workflow_name in stack:
                 # Found a back-edge - this is a cycle
-                errors.append(WorkflowValidationError(
-                    message='cycle detected in nested workflows',
-                    code=ErrorCode.WORKFLOW_CYCLE_DETECTED,
-                    notes=[
-                        f"workflow '{workflow_name}' creates a circular reference",
-                        'cycles in nested workflows are not allowed',
-                    ],
-                    help_text='remove the circular SubWorkflowNode reference',
-                ))
+                errors.append(
+                    WorkflowValidationError(
+                        message='cycle detected in nested workflows',
+                        code=ErrorCode.WORKFLOW_CYCLE_DETECTED,
+                        notes=[
+                            f"workflow '{workflow_name}' creates a circular reference",
+                            'cycles in nested workflows are not allowed',
+                        ],
+                        help_text='remove the circular SubWorkflowNode reference',
+                    )
+                )
                 return
 
             if workflow_name in visited:
@@ -1102,15 +1374,17 @@ class WorkflowSpec:
             if not isinstance(node, SubWorkflowNode):
                 continue
             if node.retry_mode != SubWorkflowRetryMode.RERUN_FAILED_ONLY:
-                errors.append(WorkflowValidationError(
-                    message='unsupported SubWorkflowRetryMode',
-                    code=ErrorCode.WORKFLOW_INVALID_SUBWORKFLOW_RETRY_MODE,
-                    notes=[
-                        f"node '{node.name}' uses retry_mode='{node.retry_mode.value}'",
-                        "only 'rerun_failed_only' is supported in this release",
-                    ],
-                    help_text='use SubWorkflowRetryMode.RERUN_FAILED_ONLY',
-                ))
+                errors.append(
+                    WorkflowValidationError(
+                        message='unsupported SubWorkflowRetryMode',
+                        code=ErrorCode.WORKFLOW_INVALID_SUBWORKFLOW_RETRY_MODE,
+                        notes=[
+                            f"node '{node.name}' uses retry_mode='{node.retry_mode.value}'",
+                            "only 'rerun_failed_only' is supported in this release",
+                        ],
+                        help_text='use SubWorkflowRetryMode.RERUN_FAILED_ONLY',
+                    )
+                )
         return errors
 
     def _register_for_conditions(self) -> None:
@@ -1365,6 +1639,57 @@ class WorkflowContext(BaseModel):
         )
 
 
+# =============================================================================
+# SQL constants for WorkflowHandle
+# =============================================================================
+
+GET_WORKFLOW_STATUS_SQL = text("""
+    SELECT status FROM horsies_workflows WHERE id = :wf_id
+""")
+
+GET_WORKFLOW_RESULT_SQL = text("""
+    SELECT result FROM horsies_workflows WHERE id = :wf_id
+""")
+
+GET_WORKFLOW_ERROR_SQL = text("""
+    SELECT error, status FROM horsies_workflows WHERE id = :wf_id
+""")
+
+GET_WORKFLOW_TASK_RESULTS_SQL = text("""
+    SELECT node_id, result
+    FROM horsies_workflow_tasks
+    WHERE workflow_id = :wf_id
+      AND result IS NOT NULL
+""")
+
+GET_WORKFLOW_TASK_RESULT_BY_NODE_SQL = text("""
+    SELECT result
+    FROM horsies_workflow_tasks
+    WHERE workflow_id = :wf_id
+      AND node_id = :node_id
+      AND result IS NOT NULL
+""")
+
+GET_WORKFLOW_TASKS_SQL = text("""
+    SELECT node_id, task_index, task_name, status, result, started_at, completed_at
+    FROM horsies_workflow_tasks
+    WHERE workflow_id = :wf_id
+    ORDER BY task_index
+""")
+
+CANCEL_WORKFLOW_SQL = text("""
+    UPDATE horsies_workflows
+    SET status = 'CANCELLED', updated_at = NOW()
+    WHERE id = :wf_id AND status IN ('PENDING', 'RUNNING', 'PAUSED')
+""")
+
+SKIP_WORKFLOW_TASKS_ON_CANCEL_SQL = text("""
+    UPDATE horsies_workflow_tasks
+    SET status = 'SKIPPED'
+    WHERE workflow_id = :wf_id AND status IN ('PENDING', 'READY')
+""")
+
+
 # =============================================================================
 # WorkflowHandle
 # =============================================================================
@@ -1409,11 +1734,9 @@ class WorkflowHandle:
 
     async def status_async(self) -> WorkflowStatus:
         """Async version of status()."""
-        from sqlalchemy import text
-
         async with self.broker.session_factory() as session:
             result = await session.execute(
-                text('SELECT status FROM horsies_workflows WHERE id = :wf_id'),
+                GET_WORKFLOW_STATUS_SQL,
                 {'wf_id': self.workflow_id},
             )
             row = result.fetchone()
@@ -1480,14 +1803,12 @@ class WorkflowHandle:
 
     async def _get_result(self) -> TaskResult[Any, TaskError]:
         """Fetch completed workflow result."""
-        from sqlalchemy import text
-
         from horsies.core.models.tasks import TaskResult
         from horsies.core.codec.serde import loads_json, task_result_from_json
 
         async with self.broker.session_factory() as session:
             result = await session.execute(
-                text('SELECT result FROM horsies_workflows WHERE id = :wf_id'),
+                GET_WORKFLOW_RESULT_SQL,
                 {'wf_id': self.workflow_id},
             )
             row = result.fetchone()
@@ -1497,14 +1818,12 @@ class WorkflowHandle:
 
     async def _get_error(self) -> TaskResult[Any, TaskError]:
         """Fetch failed workflow error."""
-        from sqlalchemy import text
-
         from horsies.core.models.tasks import TaskResult, TaskError
         from horsies.core.codec.serde import loads_json
 
         async with self.broker.session_factory() as session:
             result = await session.execute(
-                text('SELECT error, status FROM horsies_workflows WHERE id = :wf_id'),
+                GET_WORKFLOW_ERROR_SQL,
                 {'wf_id': self.workflow_id},
             )
             row = result.fetchone()
@@ -1571,18 +1890,11 @@ class WorkflowHandle:
         Keys are `node_id` values. If a TaskNode did not specify a node_id,
         WorkflowSpec auto-assigns one as "{workflow_name}:{task_index}".
         """
-        from sqlalchemy import text
-
         from horsies.core.codec.serde import loads_json, task_result_from_json
 
         async with self.broker.session_factory() as session:
             result = await session.execute(
-                text("""
-                    SELECT node_id, result
-                    FROM horsies_workflow_tasks
-                    WHERE workflow_id = :wf_id
-                      AND result IS NOT NULL
-                """),
+                GET_WORKFLOW_TASK_RESULTS_SQL,
                 {'wf_id': self.workflow_id},
             )
 
@@ -1629,8 +1941,6 @@ class WorkflowHandle:
         self, node: TaskNode[OkT] | NodeKey[OkT]
     ) -> 'TaskResult[OkT, TaskError]':
         """Async version of result_for(). See result_for() for full documentation."""
-        from sqlalchemy import text
-
         from horsies.core.codec.serde import loads_json, task_result_from_json
 
         node_id: str | None
@@ -1647,13 +1957,7 @@ class WorkflowHandle:
 
         async with self.broker.session_factory() as session:
             result = await session.execute(
-                text("""
-                    SELECT result
-                    FROM horsies_workflow_tasks
-                    WHERE workflow_id = :wf_id
-                      AND node_id = :node_id
-                      AND result IS NOT NULL
-                """),
+                GET_WORKFLOW_TASK_RESULT_BY_NODE_SQL,
                 {'wf_id': self.workflow_id, 'node_id': node_id},
             )
             row = result.fetchone()
@@ -1694,18 +1998,11 @@ class WorkflowHandle:
 
     async def tasks_async(self) -> list[WorkflowTaskInfo]:
         """Async version of tasks()."""
-        from sqlalchemy import text
-
         from horsies.core.codec.serde import loads_json, task_result_from_json
 
         async with self.broker.session_factory() as session:
             result = await session.execute(
-                text("""
-                    SELECT node_id, task_index, task_name, status, result, started_at, completed_at
-                    FROM horsies_workflow_tasks
-                    WHERE workflow_id = :wf_id
-                    ORDER BY task_index
-                """),
+                GET_WORKFLOW_TASKS_SQL,
                 {'wf_id': self.workflow_id},
             )
 
@@ -1736,26 +2033,16 @@ class WorkflowHandle:
 
     async def cancel_async(self) -> None:
         """Async version of cancel()."""
-        from sqlalchemy import text
-
         async with self.broker.session_factory() as session:
             # Cancel workflow
             await session.execute(
-                text("""
-                    UPDATE horsies_workflows
-                    SET status = 'CANCELLED', updated_at = NOW()
-                    WHERE id = :wf_id AND status IN ('PENDING', 'RUNNING', 'PAUSED')
-                """),
+                CANCEL_WORKFLOW_SQL,
                 {'wf_id': self.workflow_id},
             )
 
             # Skip pending/ready tasks
             await session.execute(
-                text("""
-                    UPDATE horsies_workflow_tasks
-                    SET status = 'SKIPPED'
-                    WHERE workflow_id = :wf_id AND status IN ('PENDING', 'READY')
-                """),
+                SKIP_WORKFLOW_TASKS_ON_CANCEL_SQL,
                 {'wf_id': self.workflow_id},
             )