"""Execution handle and internal evaluation result types.

``GuardDecision`` and ``GuardDecisionReason`` are generated from
``proto/liteguard.proto`` and live in ``types.py``. This module contains
SDK-only types that are not part of the generated type surface.
"""

from __future__ import annotations

from dataclasses import dataclass


@dataclass(frozen=True)
class DetailedEvalResult:
    """Internal result from :func:`evaluate_guard_detailed`."""

    result: bool
    matched_rule_index: int


class Execution:
    """A lightweight execution correlation handle.

    Groups telemetry signals under a shared execution ID. Created by
    :meth:`LiteguardScope.start_execution` or
    :meth:`LiteguardClient.start_execution`.

    Call :meth:`end` when the logical execution boundary is complete.
    """

    def __init__(self, execution_id: str, *, _cleanup: object = None) -> None:
        self._execution_id = execution_id
        self._cleanup = _cleanup

    @property
    def execution_id(self) -> str:
        """The unique identifier for this execution."""
        return self._execution_id

    def end(self) -> None:
        """End this execution.

        After calling ``end()``, subsequent guard checks will no longer be
        correlated with this execution.
        """
        if self._cleanup is not None:
            self._cleanup()  # type: ignore[operator]
            self._cleanup = None
