orchestrata_ultimate.session.exceptions

Reference › orchestrata_ultimate › session › exceptions

The session exceptions. SessionError is the base. ChecklistError is raised when the close checklist fails, by validate_and_end in the controller core, carrying the list of failures. GoalNotAchievedError is raised by the Stop gate when a goal is active but not achieved (SPEC-023 story 5). SessionStartError is raised when a session cannot be started.

At a glance


Source	`src/orchestrata_ultimate/session/exceptions.py`
Lines of code	67
Classes	4
Functions	0
Imports (internal)	`orchestrata_ultimate.core.base.traces`
Imported by	`orchestrata_ultimate.session`, `orchestrata_ultimate.session.cli.lifecycle`, `orchestrata_ultimate.session.controller._core`, `orchestrata_ultimate.session.controller._goals`
Tests that import it	`tests/session/test_exceptions.py`, `tests/session/test_goal_stop_gate.py`, `tests/session/test_session_controller_lifecycle.py`, `tests/session/test_session_session_coverage.py`, `tests/session/test_session_session_error_paths.py`, `tests/session/test_session_signatures.py`, `tests/test_session.py`

Class diagram

Dependency diagram

API

Classes

`SessionError`

Bases: Exception · Decorators: traces(spec='006', story='US-006', reqs=['REQ-006-FR12-004', 'REQ-006-FR5-004', 'REQ-006-FR6-001', 'REQ-006-FR6-002', '… · Line 24

Base exception for session operations.

`ChecklistError`

Bases: SessionError · Decorators: traces(spec='006', story='US-002', reqs=['REQ-006-US-002-001']) · Line 29

Raised when session checklist validation fails.

Method	Signature	Summary
`__init__`	`__init__(failures: list[str], message: str = 'Session checklist validation failed') -> None`

`GoalNotAchievedError`

Bases: SessionError · Decorators: traces(spec='023', story='US-005', reqs=['REQ-023-022', 'REQ-023-023']) · Line 45

Raised by the Stop gate when an active goal is not achieved (US-005).

Method	Signature	Summary
`__init__`	`__init__(message: str) -> None`

`SessionStartError`

Bases: SessionError · Decorators: traces(spec='006', story='FR-006', reqs=['REQ-006-FR6-001']) · Line 58

Raised when a session cannot be started.

Method	Signature	Summary
`__init__`	`__init__(reason: str) -> None`

Source

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

"""Session management exceptions.

Custom exceptions for session lifecycle validation.
"""

from orchestrata_ultimate.core.base.traces import traces

# Spec: 006 - Session Management


@traces(
    spec="006",
    story="US-006",
    reqs=[
        "REQ-006-FR12-004",
        "REQ-006-FR5-004",
        "REQ-006-FR6-001",
        "REQ-006-FR6-002",
        "REQ-006-FR6-004",
        "REQ-006-FR6-005",
        "REQ-006-US-006-005",
    ],
)
class SessionError(Exception):
    """Base exception for session operations."""


@traces(spec="006", story="US-002", reqs=["REQ-006-US-002-001"])
class ChecklistError(SessionError):
    """Raised when session checklist validation fails.

    Attributes:
        failures: List of checklist items that failed validation.
    """

    def __init__(
        self, failures: list[str], message: str = "Session checklist validation failed"
    ) -> None:
        self.failures = failures
        full_message = f"{message}: {', '.join(failures)}"
        super().__init__(full_message)


@traces(spec="023", story="US-005", reqs=["REQ-023-022", "REQ-023-023"])
class GoalNotAchievedError(SessionError):
    """Raised by the Stop gate when an active goal is not achieved (US-005).

    Attributes:
        message: The injected "Goal not achieved. Remaining: [...]" text.
    """

    def __init__(self, message: str) -> None:
        self.injected_message = message
        super().__init__(message)


@traces(spec="006", story="FR-006", reqs=["REQ-006-FR6-001"])
class SessionStartError(SessionError):
    """Raised when a session cannot be started.

    Attributes:
        reason: Why the session failed to start.
    """

    def __init__(self, reason: str) -> None:
        self.reason = reason
        super().__init__(f"Cannot start session: {reason}")