"""Shared runtime error types and extent planning values.

These primitives sit below both ``session`` (execution state) and the
executor modules, so geometry-independent helpers can raise the same stable
execution errors without importing the session or any executor.
"""

from __future__ import annotations

from dataclasses import dataclass
from typing import Any

from .topology import RuntimeDiagnostic, Vector3


class RuntimeExecutionError(RuntimeError):
    """A feature execution failure with serializable runtime evidence."""

    def __init__(self, diagnostic: RuntimeDiagnostic, selector_resolutions: list[dict[str, Any]]) -> None:
        super().__init__(diagnostic.message)
        self.diagnostic = diagnostic
        self.selector_resolutions = selector_resolutions


class FeatureExecutionError(RuntimeError):
    """An expected feature-level execution rejection with a stable code."""

    def __init__(self, code: str, message: str, **detail: Any) -> None:
        super().__init__(message)
        self.code = code
        self.detail = detail


@dataclass(frozen=True)
class ExtentVector:
    """Single-directional extrusion displacement for one profile face.

    ``trim_to`` stays ``None`` for an exact vector extrusion.  When set, the
    extent means "extrude until the target face, trimming any profile region
    that does not reach it" (up_to_surface trim semantics, issue #5).  The
    piercing distance is computed inside the adapter, so ``vector`` only
    supplies the direction.
    """

    vector: Vector3
    trim_to: Any | None = None