orchestrata_ultimate.core.paths

Reference › orchestrata_ultimate › core › paths

Resolves the project root and the Prolog rules directory for the rest of the core package and its callers. get_project_root returns the path named by the ORCHESTRATA_ROOT environment variable when it is set; otherwise it walks up at most ten directory levels from the module's own file to the nearest directory holding pyproject.toml, and raises FileNotFoundError if none is found. The marker is pyproject.toml because the older prolog/ marker also exists inside the package, which made the walk stop at the package directory instead of the repository root. resolve_project_root is the variant that never raises: the deployed tool tree has no pyproject.toml above it, so it falls back to the layout both trees share, three levels above the file's directory. A get_prolog_dir helper completes the pair. Both root functions carry @traces annotations for SPEC-020.

At a glance

Class diagram

No classes; see Functions.

Dependency diagram

API

Functions

Source

Permalink: https://gitlab.com/MSamy/orchestrata-ultimate-architecture/-/blob/a4cbc2bdf/src/orchestrata_ultimate/core/paths.py

"""Project root and Prolog directory path resolution."""

import os
from pathlib import Path

from orchestrata_ultimate.core.base.traces import traces

#: The environment key that overrides every project-root lookup.
ROOT_ENV_VAR = "ORCHESTRATA_ROOT"


def _nearest_pyproject(start: Path) -> Path | None:
    """The nearest directory at or above *start* (ten levels at most) that
    holds ``pyproject.toml``, or None."""
    current = start
    for _ in range(10):
        if (current / "pyproject.toml").is_file():
            return current
        current = current.parent
    return None


@traces(spec="020", story="US-002", reqs=["REQ-020-085"])
def get_project_root(environ: dict[str, str] | None = None) -> Path:
    """Resolve the project root directory.

    Args:
        environ: Optional environment mapping (defaults to os.environ).

    Uses ORCHESTRATA_ROOT env var if set, otherwise walks up from this file
    to find the directory containing ``pyproject.toml`` — the unambiguous
    repo-root marker. (``prolog/`` was the old marker, but it also exists
    inside the package, so the walk stopped at ``src/orchestrata_ultimate``
    and returned the package dir instead of the repo root — see get_prolog_dir.)
    """
    env = os.environ if environ is None else environ
    env_root = env.get(ROOT_ENV_VAR)
    if env_root:
        return Path(env_root)
    root = _nearest_pyproject(Path(__file__).resolve().parent)
    if root is None:
        raise FileNotFoundError("Cannot find project root (no pyproject.toml found)")
    return root


@traces(spec="020", story="US-002", reqs=["REQ-020-085"])
def resolve_project_root(
    environ: dict[str, str] | None = None, *, here: Path | None = None
) -> Path:
    """``get_project_root`` that never raises, for lookups that must not fail.

    The deployed tool tree (``/opt/orchestrata-tools/lib``) carries this
    package with no ``pyproject.toml`` above it, where ``get_project_root``
    raises; a module-level lookup there failed the import of
    ``orchestrata_ultimate.verification`` (2026-10-22). With no
    ``pyproject.toml`` this returns the root of the layout both trees share,
    ``<root>/{src,lib}/orchestrata_ultimate/core/paths.py``: three levels
    above this file's directory.

    Args:
        environ: Optional environment mapping (defaults to os.environ).
        here: Stands in for this file's path, so a test can place it in a
            layout of its own.
    """
    env = os.environ if environ is None else environ
    env_root = env.get(ROOT_ENV_VAR)
    if env_root:
        return Path(env_root)
    path = (here or Path(__file__)).resolve()
    return _nearest_pyproject(path.parent) or path.parents[3]


def get_prolog_dir() -> Path:
    """Get the path to the CANONICAL Prolog rules directory.

    Anchored to the package (``src/orchestrata_ultimate/prolog``), NOT to
    ``get_project_root()``: the repo-root ``prolog/`` directory holds a
    stale pre-port ``multiagent.pl`` (no ``:- dynamic`` declarations, no
    fan_out predicates) and is now a vestigial pre-port copy.
    Loading rules from there caused order-dependent engine state: whichever
    copy consulted last decided whether ``quorum_met``/``majority_reached``
    were overridable and whether ``fan_out_decision`` existed at all
    (2026-07-10 full-run flakes). This matches
    ``core.infra_config.prolog_dir``'s default — one rules dir, one truth.
    """
    return Path(__file__).resolve().parent.parent / "prolog"