"""Filesystem anchors for the released training package.

``PACKAGE_ROOT`` is the release root (the directory containing ``staplebridge/``,
``configs/`` and ``scripts/``). It is used only to resolve *relative* paths given
in a config -- every absolute path in a config is honoured as-is -- so the
release can be checked out anywhere without editing code.
"""
from __future__ import annotations

from pathlib import Path

#: Release root: <this file>/../../.. == release/staplebridge_training/
PACKAGE_ROOT = Path(__file__).resolve().parents[2]


def resolve_path(raw: str | Path, root: Path | None = None) -> Path:
    """Absolute paths pass through; relative ones resolve against ``root``."""
    path = Path(raw)
    return path if path.is_absolute() else (root or PACKAGE_ROOT) / path