orchestrata_ultimate.postman.delivery_outcome

Reference › orchestrata_ultimate › postman › delivery_outcome

The value types that describe the result of a single routing attempt, added so that callers can tell apart outcomes the older aroute call collapsed into one None. DeliveryFailure has three members: OK, NO_ROUTE (no handler registered, or no destination) and HANDLER_ERROR (a handler raised). DeliveryOutcome is a frozen dataclass holding whether the packet was delivered, the reason, the handler's response (if any) and an error message. postman builds it in aroute_outcome, and agents.tool_registry imports it. It serves SPEC-001 story US-002 requirements such as REQ-001-US-002-009 and -031.

At a glance

Class diagram

Dependency diagram

API

Classes

DeliveryFailure (enum)

Bases: Enum · Decorators: traces(spec='001', story='FR-002', reqs=['REQ-001-US-002-009', 'REQ-001-US-002-031', 'REQ-001-US-002-033', 'REQ-001-US-… · Line 38

Why a routing attempt did or did not deliver.

DeliveryOutcome (dataclass)

Decorators: dataclass(frozen=True), traces(spec='001', story='FR-002', reqs=['REQ-001-US-002-009', 'REQ-001-US-002-031', 'REQ-001-US-002-033', 'REQ-001-US-… · Line 57

The full result of a single Postman routing attempt.

Source

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

# mypy: ignore-errors
"""
Honest delivery status for volk<->volk messaging (SPEC-001 US-002 / SPEC-002).

``Postman.aroute`` returns ``None`` indistinguishably for three different
outcomes: no handler registered for the destination, the handler raising,
and the handler legitimately returning ``None``. Callers cannot tell
"unroutable" from "delivered, no reply" from that single ``None`` value, so
they end up reporting unroutable messages as delivered (gap G4).

``DeliveryOutcome`` carries the full, unambiguous result of a routing
attempt. ``Postman.aroute_outcome`` produces it; ``Postman.aroute`` stays
backward compatible by delegating to it and collapsing the outcome back to
the old ``response | None`` shape.
"""

from __future__ import annotations

from dataclasses import dataclass
from enum import Enum
from typing import Any

from orchestrata_ultimate.core.base.traces import traces

# Spec: 002 - Postman Message Broker


@traces(
    spec="001",
    story="FR-002",
    reqs=[
        "REQ-001-US-002-009",
        "REQ-001-US-002-031",
        "REQ-001-US-002-033",
        "REQ-001-US-002-035",
    ],
)
class DeliveryFailure(Enum):
    """Why a routing attempt did or did not deliver."""

    OK = "ok"
    NO_ROUTE = "no_route"
    HANDLER_ERROR = "handler_error"


@dataclass(frozen=True)
@traces(
    spec="001",
    story="FR-002",
    reqs=[
        "REQ-001-US-002-009",
        "REQ-001-US-002-031",
        "REQ-001-US-002-033",
        "REQ-001-US-002-035",
    ],
)
class DeliveryOutcome:
    """The full result of a single ``Postman`` routing attempt."""

    delivered: bool
    reason: DeliveryFailure
    response: Any | None
    error: str = ""