"""Resolver for the location of the shared framework-neutral core (S3, R1-forberedelse; 4a pakket).

``shared/`` is a pull-only subtree of the commons repo at the repository root. Every MAF-side
runtime consumer (``persona``, ``simulation``) resolves its location through this ONE seam, so a
re-point is an env var, not a code change. Since Fase 4a the wheel also carries a byte-identical
mirror of the tree as packaged data (``portfolio_optimiser/_shared/``, hatchling force-include in
pyproject.toml), so an installed distribution — and a container built from it — works without a
checkout. Resolution order at CALL time: explicit env override → the working tree's ``shared/``
when present (a repo checkout stays authoritative, which is what keeps the subtree contract and
the byte-level goldens untouched) → the packaged copy. Test fixtures pointing at the real in-repo
bundle hardcode the path deliberately — they must not be redirected by a production env var. Pure
stdlib — the shared core itself stays framework-free.
"""

from __future__ import annotations

import os
from pathlib import Path

ENV_VAR = "PORTFOLIO_SHARED_ROOT"

_WORKTREE = Path(__file__).resolve().parents[2] / "shared"
_PACKAGED = Path(__file__).resolve().parent / "_shared"


def shared_root() -> Path:
    """Resolve the shared-core root at CALL time: ``PORTFOLIO_SHARED_ROOT`` if set (non-empty),
    else the working tree's ``shared/`` when it exists (a checkout), else the packaged copy
    shipped inside the distribution. The call-time read is what keeps the override testable and
    the ordering observable; when neither directory exists the packaged path is returned so the
    consumer's own fail-fast names the installed distribution's gap, not a checkout that was
    never there."""
    override = os.environ.get(ENV_VAR)
    if override:
        return Path(override)
    if _WORKTREE.is_dir():
        return _WORKTREE
    return _PACKAGED