orchestrata_ultimate.core.packet.exceptions

Reference › orchestrata_ultimate › core › packet › exceptions

The two CXP exceptions that belong to the layer-0 vocabulary. CXPPacket raises StateTransitionError from its state-machine methods, so that exception and its base CXPError must be in core (decision K6: core imports nothing from cxp). CXPError carries a message, a machine-readable code (default CXP_ERROR) and a details dictionary. StateTransitionError is constructed with the current state, the target state and a state type (delivery or work). The rest of the CXP exception hierarchy stays in cxp.exceptions (layer 2), which re-exports these two classes as the same objects so existing except clauses keep working. Used by packet.

At a glance

Class diagram

Dependency diagram

API

Classes

CXPError

Bases: Exception · Decorators: traces(spec='004', story='US-003', reqs=['REQ-004-US-003-019']) · Line 26

Base exception for all CXP protocol errors.

StateTransitionError

Bases: CXPError · Decorators: traces(spec='004', story='US-004', reqs=['REQ-004-US-004-011', 'REQ-004-US-005-011']) · Line 61

Raised when an invalid state transition is attempted.

Source

Permalink: https://gitlab.com/MSamy/orchestrata-ultimate-architecture/-/blob/a4cbc2bdf/src/orchestrata_ultimate/core/packet/exceptions.py

"""
CXP packet exceptions that are part of the Layer-0 vocabulary.

``CXPPacket`` (``core.packet.packet``) raises ``StateTransitionError`` from
its delivery/work state-machine methods, so the exception — and its base
``CXPError`` — must live in Layer 0 alongside the packet (K6: ``core``
imports nothing from ``cxp``). The rest of the CXP exception hierarchy
remains in ``orchestrata_ultimate.cxp.exceptions`` (Layer 2), which
re-exports these two classes so existing ``cxp.exceptions`` import paths
and ``except`` clauses keep working unchanged (same class objects).

Spec: 004 - CXP Protocol
"""

from typing import Any

from orchestrata_ultimate.core.base.traces import traces

__all__ = [
    "CXPError",
    "StateTransitionError",
]


@traces(spec="004", story="US-003", reqs=["REQ-004-US-003-019"])
class CXPError(Exception):
    """Base exception for all CXP protocol errors.

    Attributes:
        message: Human-readable error description.
        code: Machine-readable error code.
        details: Optional structured error details.
    """

    def __init__(
        self,
        message: str,
        code: str = "CXP_ERROR",
        details: dict[str, Any] | None = None,
    ) -> None:
        super().__init__(message)
        self.message = message
        self.code = code
        self.details = details or {}

    def to_dict(self) -> dict[str, Any]:
        result: dict[str, Any] = {
            "error": self.code,
            "message": self.message,
        }
        if self.details:
            result["details"] = self.details
        return result


@traces(
    spec="004",
    story="US-004",
    reqs=["REQ-004-US-004-011", "REQ-004-US-005-011"],
)
class StateTransitionError(CXPError):
    """Raised when an invalid state transition is attempted."""

    def __init__(
        self,
        current_state: str,
        target_state: str,
        state_type: str = "delivery",
        details: dict[str, Any] | None = None,
    ) -> None:
        d = details or {}
        d["current_state"] = current_state
        d["target_state"] = target_state
        d["state_type"] = state_type
        super().__init__(
            message=f"Invalid {state_type} transition: {current_state} -> {target_state}",
            code="INVALID_STATE_TRANSITION",
            details=d,
        )
        self.current_state = current_state
        self.target_state = target_state
        self.state_type = state_type