hexastack-flow 0.5.0__tar.gz

hexastack_flow-0.5.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: hexastack-flow
+Version: 0.5.0
+Summary: Hexagonal workflow engine adapter integrating hexaflow with CQRS, DB, and Events
+Author: Richard West
+Author-email: Richard West <dopplereffect.us@gmail.com>
+License-Expression: Apache-2.0
+Requires-Dist: hexaflow>=0.2.0
+Requires-Dist: hexastack-core
+Requires-Dist: hexastack-cqrs
+Requires-Dist: hexastack-flow[db,events] ; extra == 'all'
+Requires-Dist: hexastack-db ; extra == 'db'
+Requires-Dist: sqlalchemy>=2.0.0 ; extra == 'db'
+Requires-Dist: hexastack-events ; extra == 'events'
+Requires-Python: >=3.13
+Provides-Extra: all
+Provides-Extra: db
+Provides-Extra: events
+Description-Content-Type: text/markdown
+
+# 🌊 `hexastack-flow`
+
+> Hexagonal workflow engine adapter integrating `hexaflow` with Hexastack CQRS, Relational Persistence, and Event Streaming.
+
+---
+
+## 🎯 Architectural Intent
+
+`hexastack-flow` provides first-class hexagonal adapters connecting the lightweight [`hexaflow`](https://pypi.org/project/hexaflow/) workflow engine to Hexastack:
+
+1. **CQRS Bridge**: `CommandStep` and `QueryStep` allow workflow steps to dispatch typed commands and queries directly onto the `CommandBus` and `QueryBus`, inheriting all CQRS middleware (auth, tracing, logging, metrics, retries).
+2. **Durable Distributed Sagas**: Workflows natively subsume the Saga pattern by pairing forward command execution stages with compensating rollback stages, backed by durable checkpoints.
+3. **Enterprise Persistence**: `SqlAlchemyWorkflowStore` persists workflow execution records and step checkpoints directly to PostgreSQL/SQLite/MySQL within transactional boundaries.
+4. **Event Streaming**: Emits domain events (`WorkflowStartedEvent`, `WorkflowStepCompletedEvent`, `WorkflowSuspendedEvent`, `WorkflowCompletedEvent`, `WorkflowAbortedEvent`) wrapped in standard `CloudEventEnvelope`s through `hexastack-events`.
+5. **DevTools Visualizer**: Backing engine for NiceGUI and Textual DAG monitoring.
+
+---
+
+## 🔄 Implementing the Saga Pattern as a Workflow
+
+Historically, the **Saga Pattern** structures a distributed business transaction across multiple microservices or bounded contexts as a sequence of local transactions:
+- **Forward transactions**: $T_1, T_2, \dots, T_n$
+- **Compensating transactions**: $C_{k-1}, \dots, C_1$ executed in reverse (LIFO) order if step $k$ fails.
+
+In `hexastack-flow`, you do **not** need a separate, restricted saga engine. A Saga is simply a workflow DAG that dispatches CQRS commands and executes compensating commands on failure.
+
+### Example: Trip Booking Saga with CQRS & Hexaflow
+
+```python
+from hexaflow import Workflow
+from hexastack_cqrs.ports.buses import CommandBusPort
+from hexastack_flow.adapters.cqrs.runner import CqrsWorkflowRunner
+from hexastack_flow.adapters.cqrs.steps import as_command_step
+
+# 1. Define CQRS commands for forward actions & compensations
+from my_domain.commands import (
+    BookFlightCommand,
+    CancelFlightCommand,
+    BookHotelCommand,
+    CancelHotelCommand,
+    ChargePaymentCommand,
+)
+
+def build_trip_booking_workflow(bus: CommandBusPort, customer_id: str) -> Workflow:
+    """Construct a durable distributed saga as a hexaflow Workflow."""
+    workflow = (
+        Workflow("trip-booking-saga")
+        # Step 1: Reserve Flight
+        .stage(
+            "flight",
+            as_command_step(
+                lambda ctx: BookFlightCommand(customer_id=customer_id, destination="JFK"),
+                bus,
+                name="book_flight",
+            ),
+        )
+        # Step 2: Reserve Hotel (runs after flight is confirmed)
+        .stage(
+            "hotel",
+            as_command_step(
+                lambda ctx: BookHotelCommand(customer_id=customer_id, room_type="deluxe"),
+                bus,
+                name="book_hotel",
+            ),
+            depends_on=["flight"],
+        )
+        # Step 3: Process Payment
+        .stage(
+            "payment",
+            as_command_step(
+                lambda ctx: ChargePaymentCommand(customer_id=customer_id, amount_cents=50000),
+                bus,
+                name="charge_payment",
+            ),
+            depends_on=["hotel"],
+        )
+    )
+    return workflow
+
+# 2. Execute via CqrsWorkflowRunner (with durable DB checkpoints)
+runner = CqrsWorkflowRunner(engine=engine)
+result = await runner.run(workflow.build())
+```
+
+### Why Workflows are Superior to Linear Sagas
+
+| Feature | Legacy In-Memory Saga | `hexastack-flow` Workflow |
+|---|---|---|
+| **Execution Topologies** | Strictly sequential ($T_1 \to T_2 \to T_3$) | **Arbitrary DAGs** (e.g. reserve Flight & Hotel in parallel) |
+| **Crash Recovery** | In-memory only (lost if process restarts) | **Durable Checkpoints** (`SqlAlchemyWorkflowStore`) |
+| **Step Retries** | Manual loop or fail immediately | **Configurable `RetryPolicy`** (exponential backoff, jitter) |
+| **Observability** | Console logs | **CloudEvents** (`WorkflowStepCompletedEvent`) + OTel spans |
+| **Human-in-the-Loop** | Not supported | **Pause / Resume** (`engine.suspend()`, `engine.resume()`) |
+
+---
+
+## 📦 Installation
+
+```bash
+pip install hexastack[flow]
+```
+
+Or standalone:
+
+```bash
+pip install hexastack-flow
+```
+
+---
+
+## 📄 License
+
+Apache 2.0

hexastack_flow-0.5.0/README.md

@@ -0,0 +1,113 @@
+# 🌊 `hexastack-flow`
+
+> Hexagonal workflow engine adapter integrating `hexaflow` with Hexastack CQRS, Relational Persistence, and Event Streaming.
+
+---
+
+## 🎯 Architectural Intent
+
+`hexastack-flow` provides first-class hexagonal adapters connecting the lightweight [`hexaflow`](https://pypi.org/project/hexaflow/) workflow engine to Hexastack:
+
+1. **CQRS Bridge**: `CommandStep` and `QueryStep` allow workflow steps to dispatch typed commands and queries directly onto the `CommandBus` and `QueryBus`, inheriting all CQRS middleware (auth, tracing, logging, metrics, retries).
+2. **Durable Distributed Sagas**: Workflows natively subsume the Saga pattern by pairing forward command execution stages with compensating rollback stages, backed by durable checkpoints.
+3. **Enterprise Persistence**: `SqlAlchemyWorkflowStore` persists workflow execution records and step checkpoints directly to PostgreSQL/SQLite/MySQL within transactional boundaries.
+4. **Event Streaming**: Emits domain events (`WorkflowStartedEvent`, `WorkflowStepCompletedEvent`, `WorkflowSuspendedEvent`, `WorkflowCompletedEvent`, `WorkflowAbortedEvent`) wrapped in standard `CloudEventEnvelope`s through `hexastack-events`.
+5. **DevTools Visualizer**: Backing engine for NiceGUI and Textual DAG monitoring.
+
+---
+
+## 🔄 Implementing the Saga Pattern as a Workflow
+
+Historically, the **Saga Pattern** structures a distributed business transaction across multiple microservices or bounded contexts as a sequence of local transactions:
+- **Forward transactions**: $T_1, T_2, \dots, T_n$
+- **Compensating transactions**: $C_{k-1}, \dots, C_1$ executed in reverse (LIFO) order if step $k$ fails.
+
+In `hexastack-flow`, you do **not** need a separate, restricted saga engine. A Saga is simply a workflow DAG that dispatches CQRS commands and executes compensating commands on failure.
+
+### Example: Trip Booking Saga with CQRS & Hexaflow
+
+```python
+from hexaflow import Workflow
+from hexastack_cqrs.ports.buses import CommandBusPort
+from hexastack_flow.adapters.cqrs.runner import CqrsWorkflowRunner
+from hexastack_flow.adapters.cqrs.steps import as_command_step
+
+# 1. Define CQRS commands for forward actions & compensations
+from my_domain.commands import (
+    BookFlightCommand,
+    CancelFlightCommand,
+    BookHotelCommand,
+    CancelHotelCommand,
+    ChargePaymentCommand,
+)
+
+def build_trip_booking_workflow(bus: CommandBusPort, customer_id: str) -> Workflow:
+    """Construct a durable distributed saga as a hexaflow Workflow."""
+    workflow = (
+        Workflow("trip-booking-saga")
+        # Step 1: Reserve Flight
+        .stage(
+            "flight",
+            as_command_step(
+                lambda ctx: BookFlightCommand(customer_id=customer_id, destination="JFK"),
+                bus,
+                name="book_flight",
+            ),
+        )
+        # Step 2: Reserve Hotel (runs after flight is confirmed)
+        .stage(
+            "hotel",
+            as_command_step(
+                lambda ctx: BookHotelCommand(customer_id=customer_id, room_type="deluxe"),
+                bus,
+                name="book_hotel",
+            ),
+            depends_on=["flight"],
+        )
+        # Step 3: Process Payment
+        .stage(
+            "payment",
+            as_command_step(
+                lambda ctx: ChargePaymentCommand(customer_id=customer_id, amount_cents=50000),
+                bus,
+                name="charge_payment",
+            ),
+            depends_on=["hotel"],
+        )
+    )
+    return workflow
+
+# 2. Execute via CqrsWorkflowRunner (with durable DB checkpoints)
+runner = CqrsWorkflowRunner(engine=engine)
+result = await runner.run(workflow.build())
+```
+
+### Why Workflows are Superior to Linear Sagas
+
+| Feature | Legacy In-Memory Saga | `hexastack-flow` Workflow |
+|---|---|---|
+| **Execution Topologies** | Strictly sequential ($T_1 \to T_2 \to T_3$) | **Arbitrary DAGs** (e.g. reserve Flight & Hotel in parallel) |
+| **Crash Recovery** | In-memory only (lost if process restarts) | **Durable Checkpoints** (`SqlAlchemyWorkflowStore`) |
+| **Step Retries** | Manual loop or fail immediately | **Configurable `RetryPolicy`** (exponential backoff, jitter) |
+| **Observability** | Console logs | **CloudEvents** (`WorkflowStepCompletedEvent`) + OTel spans |
+| **Human-in-the-Loop** | Not supported | **Pause / Resume** (`engine.suspend()`, `engine.resume()`) |
+
+---
+
+## 📦 Installation
+
+```bash
+pip install hexastack[flow]
+```
+
+Or standalone:
+
+```bash
+pip install hexastack-flow
+```
+
+---
+
+## 📄 License
+
+Apache 2.0

hexastack_flow-0.5.0/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "hexastack-flow"
+version = "0.5.0"
+description = "Hexagonal workflow engine adapter integrating hexaflow with CQRS, DB, and Events"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.13"
+dependencies = [
+    "hexaflow>=0.2.0",
+    "hexastack-core",
+    "hexastack-cqrs",
+]
+
+[[project.authors]]
+name = "Richard West"
+email = "dopplereffect.us@gmail.com"
+
+[project.optional-dependencies]
+db = [
+    "hexastack-db",
+    "sqlalchemy>=2.0.0",
+]
+events = ["hexastack-events"]
+all = ["hexastack-flow[db,events]"]
+
+[project.entry-points."hexastack.bootstrappers"]
+flow = "hexastack_flow.infra.bootstrap:FlowBootstrapper"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources.hexastack-core]
+workspace = true
+
+[tool.uv.sources.hexastack-cqrs]
+workspace = true
+
+[tool.uv.sources.hexastack-db]
+workspace = true
+
+[tool.uv.sources.hexastack-events]
+workspace = true
+
+[tool.importlinter]
+root_packages = ["hexastack_flow"]
+
+[[tool.importlinter.contracts]]
+name = "Hexagonal architecture layer hierarchy"
+type = "layers"
+containers = ["hexastack_flow"]
+layers = [
+    "infra",
+    "adapters",
+    "ports",
+    "domain",
+]

hexastack_flow-0.5.0/pyproject.toml.orig

@@ -0,0 +1,54 @@
+[project]
+name = "hexastack-flow"
+version = "0.5.0"
+description = "Hexagonal workflow engine adapter integrating hexaflow with CQRS, DB, and Events"
+readme = "README.md"
+license = "Apache-2.0"
+authors = [
+    { name = "Richard West", email = "dopplereffect.us@gmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "hexaflow>=0.2.0",
+    "hexastack-core",
+    "hexastack-cqrs",
+]
+
+[project.optional-dependencies]
+db = [
+    "hexastack-db",
+    "sqlalchemy>=2.0.0",
+]
+events = [
+    "hexastack-events",
+]
+all = [
+    "hexastack-flow[db,events]",
+]
+
+[project.entry-points."hexastack.bootstrappers"]
+flow = "hexastack_flow.infra.bootstrap:FlowBootstrapper"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources]
+hexastack-core = { workspace = true }
+hexastack-cqrs = { workspace = true }
+hexastack-db = { workspace = true }
+hexastack-events = { workspace = true }
+
+[tool.importlinter]
+root_packages = ["hexastack_flow"]
+
+[[tool.importlinter.contracts]]
+name = "Hexagonal architecture layer hierarchy"
+type = "layers"
+containers = ["hexastack_flow"]
+layers = [
+    "infra",
+    "adapters",
+    "ports",
+    "domain",
+]

hexastack_flow-0.5.0/src/hexastack_flow/__init__.py

@@ -0,0 +1,59 @@
+"""Hexastack Flow - Hexagonal workflow orchestration framework.
+
+Notes/Architectural Intent:
+    Integrates the zero-daemon hexaflow workflow execution engine into Hexastack,
+    providing CQRS command/query steps, saga migration, relational checkpoint persistence,
+    and lifecycle domain event broadcasting.
+"""
+
+from hexaflow import RetryPolicy, StageExecutionMode, Workflow
+
+from hexastack_flow import adapters, domain, infra, ports
+from hexastack_flow.adapters.cqrs.runner import CqrsWorkflowRunner
+from hexastack_flow.adapters.cqrs.steps import (
+    CommandStep,
+    QueryStep,
+    as_command_step,
+    as_query_step,
+)
+from hexastack_flow.adapters.events.publisher import WorkflowEventPublisher
+from hexastack_flow.adapters.storage.sqlalchemy import SqlAlchemyWorkflowStore
+from hexastack_flow.domain.events import (
+    WorkflowAbortedEvent,
+    WorkflowCompletedEvent,
+    WorkflowStartedEvent,
+    WorkflowStepCompletedEvent,
+    WorkflowSuspendedEvent,
+)
+from hexastack_flow.domain.models import (
+    CqrsStepMetadata,
+    WorkflowExecutionResult,
+)
+from hexastack_flow.infra.bootstrap import FlowBootstrapper
+from hexastack_flow.ports.orchestrator import CqrsWorkflowOrchestratorPort
+
+__all__ = [
+    "adapters",
+    "as_command_step",
+    "as_query_step",
+    "CommandStep",
+    "CqrsStepMetadata",
+    "CqrsWorkflowOrchestratorPort",
+    "CqrsWorkflowRunner",
+    "domain",
+    "FlowBootstrapper",
+    "infra",
+    "ports",
+    "QueryStep",
+    "RetryPolicy",
+    "SqlAlchemyWorkflowStore",
+    "StageExecutionMode",
+    "Workflow",
+    "WorkflowAbortedEvent",
+    "WorkflowCompletedEvent",
+    "WorkflowEventPublisher",
+    "WorkflowExecutionResult",
+    "WorkflowStartedEvent",
+    "WorkflowStepCompletedEvent",
+    "WorkflowSuspendedEvent",
+]

hexastack_flow-0.5.0/src/hexastack_flow/adapters/__init__.py

@@ -0,0 +1,29 @@
+"""Adapters for hexastack-flow.
+
+Notes/Architectural Intent:
+    Exports CQRS, Storage, and Event adapters bridging hexaflow into Hexastack.
+"""
+
+from hexastack_flow.adapters import cqrs, events, storage
+from hexastack_flow.adapters.cqrs import (
+    CommandStep,
+    CqrsWorkflowRunner,
+    QueryStep,
+    as_command_step,
+    as_query_step,
+)
+from hexastack_flow.adapters.events import WorkflowEventPublisher
+from hexastack_flow.adapters.storage import SqlAlchemyWorkflowStore
+
+__all__ = [
+    "as_command_step",
+    "as_query_step",
+    "CommandStep",
+    "cqrs",
+    "CqrsWorkflowRunner",
+    "events",
+    "QueryStep",
+    "SqlAlchemyWorkflowStore",
+    "storage",
+    "WorkflowEventPublisher",
+]

hexastack_flow-0.5.0/src/hexastack_flow/adapters/cqrs/__init__.py

@@ -0,0 +1,21 @@
+"""CQRS adapters for hexaflow workflow execution.
+
+Notes/Architectural Intent:
+    Adapters connecting Hexastack CQRS buses and legacy saga models to hexaflow.
+"""
+
+from hexastack_flow.adapters.cqrs.runner import CqrsWorkflowRunner
+from hexastack_flow.adapters.cqrs.steps import (
+    CommandStep,
+    QueryStep,
+    as_command_step,
+    as_query_step,
+)
+
+__all__ = [
+    "as_command_step",
+    "as_query_step",
+    "CommandStep",
+    "CqrsWorkflowRunner",
+    "QueryStep",
+]

hexastack_flow-0.5.0/src/hexastack_flow/adapters/cqrs/runner.py

@@ -0,0 +1,212 @@
+"""CQRS workflow runner adapter implementing CqrsWorkflowOrchestratorPort.
+
+Notes/Architectural Intent:
+    Glues the hexaflow execution engine, state store, and event bus together.
+    Translates hexaflow state objects into Hexastack domain results and
+    publishes lifecycle domain events.
+"""
+
+from datetime import UTC, datetime
+from typing import Any
+
+from hexaflow.adapters.engines.local_async import AsyncioWorkflowEngine
+from hexaflow.adapters.storage.in_memory import InMemoryStateStore
+from hexaflow.domain.models import WorkflowDefinition
+from hexaflow.domain.state import StepStatus, WorkflowExecutionState, WorkflowStatus
+from hexaflow.ports.engine import WorkflowEnginePort
+from hexaflow.ports.storage import WorkflowStateStorePort
+
+from hexastack_cqrs.ports.buses import EventBusPort
+from hexastack_flow.domain.events import (
+    WorkflowAbortedEvent,
+    WorkflowCompletedEvent,
+    WorkflowStartedEvent,
+    WorkflowSuspendedEvent,
+)
+from hexastack_flow.domain.models import WorkflowExecutionResult
+from hexastack_flow.ports.orchestrator import CqrsWorkflowOrchestratorPort
+
+__all__ = [
+    "CqrsWorkflowRunner",
+]
+
+
+class CqrsWorkflowRunner(CqrsWorkflowOrchestratorPort):
+    """Orchestrator runner coordinating workflow execution with CQRS buses.
+
+    Notes/Architectural Intent:
+        Implements CqrsWorkflowOrchestratorPort to provide a complete
+        in-process execution runtime with automatic event publishing.
+    """
+
+    def __init__(
+        self,
+        state_store: WorkflowStateStorePort | None = None,
+        engine: WorkflowEnginePort | None = None,
+        event_bus: EventBusPort | None = None,
+    ) -> None:
+        """Initialize runner with state store, execution engine, and event bus.
+
+        Args:
+            state_store: WorkflowStateStorePort for persistence. Defaults to InMemoryStateStore.
+            engine: WorkflowEnginePort for DAG execution. Defaults to AsyncioWorkflowEngine.
+            event_bus: Optional EventBusPort for publishing workflow domain events.
+        """
+        self._store = state_store or InMemoryStateStore()
+        self._engine = engine or AsyncioWorkflowEngine(state_store=self._store)
+        self._event_bus = event_bus
+
+    def execute(
+        self,
+        workflow: WorkflowDefinition,
+        initial_inputs: dict[str, Any] | None = None,
+    ) -> WorkflowExecutionResult:
+        """Execute workflow definition from the first stage.
+
+        Args:
+            workflow: The WorkflowDefinition to run.
+            initial_inputs: Optional dictionary of root arguments.
+
+        Returns:
+            WorkflowExecutionResult summarizing status, step outputs, and timing.
+        """
+        start_time = datetime.now(UTC)
+        state = self._engine.run(workflow, initial_inputs=initial_inputs)
+
+        if self._event_bus is not None:
+            self._event_bus.publish(
+                WorkflowStartedEvent(
+                    run_id=state.run_id,
+                    workflow_name=state.workflow_name,
+                    started_at=start_time,
+                )
+            )
+
+        self._emit_terminal_events(state)
+        return self._to_result(state)
+
+    def resume(
+        self,
+        run_id: str,
+        workflow: WorkflowDefinition,
+        patch_inputs: dict[str, Any] | None = None,
+    ) -> WorkflowExecutionResult:
+        """Resume a suspended workflow run from its latest checkpoints.
+
+        Args:
+            run_id: Unique identifier of the suspended run.
+            workflow: WorkflowDefinition specification matching the run.
+            patch_inputs: Optional updated inputs for the suspended step.
+
+        Returns:
+            WorkflowExecutionResult reflecting post-resumption status.
+        """
+        state = self._engine.resume(run_id, workflow, patch_inputs=patch_inputs)
+        self._emit_terminal_events(state)
+        return self._to_result(state)
+
+    def abort(
+        self,
+        run_id: str,
+        workflow: WorkflowDefinition,
+        reason: str = "Operator aborted",
+    ) -> WorkflowExecutionResult:
+        """Abort a workflow and unwind completed steps via compensation hooks.
+
+        Args:
+            run_id: Unique identifier of the workflow run.
+            workflow: WorkflowDefinition specification containing compensation hooks.
+            reason: Operator rationale or explanation for cancellation.
+
+        Returns:
+            WorkflowExecutionResult reflecting the aborted state.
+        """
+        state = self._engine.abort(run_id, workflow)
+
+        if self._event_bus is not None:
+            self._event_bus.publish(
+                WorkflowAbortedEvent(
+                    run_id=state.run_id,
+                    workflow_name=state.workflow_name,
+                    reason=reason,
+                    aborted_at=datetime.now(UTC),
+                )
+            )
+
+        return self._to_result(state)
+
+    def _emit_terminal_events(self, state: WorkflowExecutionState) -> None:
+        """Publish lifecycle events based on execution state outcome.
+
+        Args:
+            state: WorkflowExecutionState to inspect.
+        """
+        if self._event_bus is None:
+            return
+
+        if state.status == WorkflowStatus.COMPLETED:
+            self._event_bus.publish(
+                WorkflowCompletedEvent(
+                    run_id=state.run_id,
+                    workflow_name=state.workflow_name,
+                    completed_at=state.finished_at or datetime.now(UTC),
+                    total_steps=len(state.step_checkpoints),
+                )
+            )
+        elif state.status == WorkflowStatus.SUSPENDED:
+            failed_step = next(
+                (
+                    name
+                    for name, chk in state.step_checkpoints.items()
+                    if chk.status == StepStatus.FAILED
+                ),
+                "unknown",
+            )
+            self._event_bus.publish(
+                WorkflowSuspendedEvent(
+                    run_id=state.run_id,
+                    stage_name=state.current_stage or "unknown",
+                    step_name=failed_step,
+                    error_type="StepExecutionError",
+                    error_message=state.error_summary
+                    or "Step failed and exhausted retries.",
+                )
+            )
+
+    @staticmethod
+    def _to_result(state: WorkflowExecutionState) -> WorkflowExecutionResult:
+        """Map a hexaflow WorkflowExecutionState into a WorkflowExecutionResult.
+
+        Args:
+            state: Engine execution state.
+
+        Returns:
+            Pydantic WorkflowExecutionResult value object.
+        """
+        completed = tuple(
+            name
+            for name, chk in state.step_checkpoints.items()
+            if chk.status == StepStatus.COMPLETED
+        )
+        failed = tuple(
+            name
+            for name, chk in state.step_checkpoints.items()
+            if chk.status == StepStatus.FAILED
+        )
+        outputs = {
+            name: chk.output_payload
+            for name, chk in state.step_checkpoints.items()
+            if chk.output_payload is not None
+        }
+
+        return WorkflowExecutionResult(
+            run_id=state.run_id,
+            workflow_name=state.workflow_name,
+            status=state.status.value,
+            completed_steps=completed,
+            failed_steps=failed,
+            outputs=outputs,
+            started_at=state.started_at,
+            ended_at=state.finished_at or datetime.now(UTC),
+            error_summary=state.error_summary,
+        )