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

``shared/`` is today an in-repo directory, but is slated for extraction into its own commons repo
(R1/S4). Every MAF-side runtime consumer (``persona``, ``simulation``) resolves its location through
this ONE seam so the extraction is a re-point (env var), not a code change. 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"

_DEFAULT = Path(__file__).resolve().parents[2] / "shared"


def shared_root() -> Path:
    """Resolve the shared-core root at CALL time: ``PORTFOLIO_SHARED_ROOT`` if set (non-empty),
    else the in-repo default. The call-time read is what keeps the override testable and the S4
    extraction re-pointable without touching consumers."""
    override = os.environ.get(ENV_VAR)
    return Path(override) if override else _DEFAULT