# paths.py — unified HOME_DIR and filesystem path resolution contract (N0)

import os

def resolve_home(home_dir=None):
    """
    Unified HOME_DIR resolution contract across lib_py modules and adapters.
    Tries: 1. explicit home_dir argument, 2. HOME_DIR env var, 3. HOME env var, 4. os.path.expanduser('~').
    Raises ValueError if result is empty or filesystem root ('/'), preventing root-relative silent fail-close.
    """
    h = home_dir or os.environ.get("HOME_DIR") or os.environ.get("HOME") or os.path.expanduser("~")
    if not h or h == "/":
        raise ValueError("HOME_DIR unresolvable — refusing to build paths from the filesystem root")
    return h