pz-cli 5.0.0__py3-none-any.whl

pz_core/runtime/settings.py

@@ -0,0 +1,888 @@
+from __future__ import annotations
+
+import copy
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from functools import lru_cache
+import os
+from pathlib import Path
+from typing import Any, Callable, Iterator, TypeVar
+
+from pz_core.assembly.project import compile_project_context
+from pz_core.assembly.settings import SettingsSnapshot, compile_settings_snapshot, load_project_env_file
+from pz_core.core.extensions import SettingsPatch, SettingsProviderContext, SettingsProviderSpec
+from pz_core.runtime.errors import PzError
+from pz_core.runtime.plan_context import current_runtime_plan
+from pz_core.utils import (
+    has_env_value,
+    iter_env_items,
+    load_jsonc_file,
+    read_env_bool,
+    read_env_float,
+    read_env_int,
+    read_env_string,
+)
+from pz_core.utils.project_jsonc import PROJECT_JSONC_NAME
+
+
+TAppSettings = TypeVar("TAppSettings")
+
+_SETTINGS_SNAPSHOTS: dict[str, SettingsSnapshot] = {}
+_SETTINGS_SNAPSHOT_REFCOUNTS: dict[str, int] = {}
+_SETTINGS_NAMESPACE_CACHE: dict[int, tuple[SettingsSnapshot, frozenset[str]]] = {}
+_SETTINGS_PROVIDER_SPECS_CACHE: dict[int, tuple[object, tuple[SettingsProviderSpec, ...]]] = {}
+_SETTINGS_PROVIDER_VALUES_CACHE: dict[tuple[int, str | None], tuple[SettingsSnapshot, dict[str, dict[str, Any]]]] = {}
+_RESOLVED_SETTINGS_CACHE: dict[tuple[int, str | None], tuple[SettingsSnapshot, "ResolvedSettings"]] = {}
+_ACTIVE_SETTINGS_PROJECT_DIR: ContextVar[str | None] = ContextVar(
+    "pz_runtime_settings_active_project_dir",
+    default=None,
+)
+_SETTINGS_PROVIDER_RESOLUTION_DEPTH: ContextVar[int] = ContextVar(
+    "pz_runtime_settings_provider_resolution_depth",
+    default=0,
+)
+
+_ROUTE_TOKEN_CATALOG_PROVIDER: Callable[[str | Path | None], Any] | None = None
+
+
+def _invalidate_settings_runtime_caches() -> None:
+    _SETTINGS_NAMESPACE_CACHE.clear()
+    _SETTINGS_PROVIDER_SPECS_CACHE.clear()
+    _SETTINGS_PROVIDER_VALUES_CACHE.clear()
+    _RESOLVED_SETTINGS_CACHE.clear()
+
+
+@lru_cache(maxsize=None)
+def _resolve_path_text(value: str) -> str:
+    return str(Path(value).resolve())
+
+
+def _local_default_config_path(anchor: str | os.PathLike[str]) -> Path:
+    location = Path(anchor).resolve()
+    base = location.parent if location.is_file() else location
+    if base.name == "settings":
+        base = base.parent
+    return base / "configs" / "default.jsonc"
+
+
+@lru_cache(maxsize=None)
+def _cached_local_default_settings(anchor: str) -> dict[str, Any]:
+    jsonc_path = _local_default_config_path(anchor)
+    if not jsonc_path.is_file():
+        return {}
+    return load_jsonc_file(
+        jsonc_path,
+        code="PZ_APP_DEFAULTS_INVALID",
+        owner="runtime.settings",
+        action="load_local_default_settings",
+    )
+
+
+def load_local_default_settings(anchor: str | os.PathLike[str]) -> dict[str, Any]:
+    """Read package default templates for authoring-time settings tools.
+
+    This helper is kept for compatibility with settings init/update style code.
+    Runtime settings compilation must not call it.
+    """
+    return copy.deepcopy(_cached_local_default_settings(_resolve_path_text(str(anchor))))
+
+
+def build_local_default_settings(anchor: str | os.PathLike[str], settings_type: type[TAppSettings]) -> TAppSettings:
+    return settings_type(**load_local_default_settings(anchor))
+
+
+def _deep_merge_local_defaults(base: dict[str, Any], incoming: dict[str, Any]) -> dict[str, Any]:
+    merged = dict(base)
+    for key, value in incoming.items():
+        if isinstance(value, dict) and isinstance(merged.get(key), dict):
+            merged[key] = _deep_merge_local_defaults(merged[key], value)
+            continue
+        merged[key] = copy.deepcopy(value)
+    return merged
+
+
+def load_local_default_settings_chain(*anchors: str | os.PathLike[str]) -> dict[str, Any]:
+    merged: dict[str, Any] = {}
+    for anchor in anchors:
+        merged = _deep_merge_local_defaults(merged, load_local_default_settings(anchor))
+    return merged
+
+
+def build_local_default_settings_chain(
+    settings_type: type[TAppSettings],
+    *anchors: str | os.PathLike[str],
+) -> TAppSettings:
+    return settings_type(**load_local_default_settings_chain(*anchors))
+
+
+def _deep_merge_payload(base: dict[str, Any], incoming: dict[str, Any]) -> dict[str, Any]:
+    merged = dict(base)
+    for key, value in incoming.items():
+        if isinstance(value, dict) and isinstance(merged.get(key), dict):
+            merged[key] = _deep_merge_payload(dict(merged[key]), value)
+            continue
+        merged[key] = copy.deepcopy(value)
+    return merged
+
+
+def _normalize_project_dir(project_dir: str | Path | None) -> str | None:
+    if project_dir is None:
+        return None
+    value = str(project_dir).strip()
+    if not value:
+        return None
+    return _resolve_path_text(value)
+
+
+def _runtime_plan_project_dir() -> str | None:
+    runtime_plan = current_runtime_plan()
+    return _normalize_project_dir(getattr(getattr(runtime_plan, "project", None), "project_dir", None))
+
+
+def _configured_project_dir() -> str | None:
+    raw_env_project_dir = os.getenv("PZ_PROJECT_DIR")
+    if raw_env_project_dir is not None:
+        return _normalize_project_dir(compile_project_context(project_dir=None).project_dir)
+
+    current = Path.cwd().resolve()
+    for candidate in (current, *current.parents):
+        if (candidate / PROJECT_JSONC_NAME).is_file():
+            return _normalize_project_dir(candidate)
+    return None
+
+
+def _effective_project_dir(project_dir: str | Path | None = None) -> str | None:
+    explicit_project_dir = _normalize_project_dir(project_dir)
+    if explicit_project_dir:
+        return explicit_project_dir
+    active = _ACTIVE_SETTINGS_PROJECT_DIR.get()
+    if active:
+        return active
+    runtime_project_dir = _runtime_plan_project_dir()
+    if runtime_project_dir:
+        return runtime_project_dir
+    configured_project_dir = _configured_project_dir()
+    if configured_project_dir:
+        return configured_project_dir
+    if len(_SETTINGS_SNAPSHOTS) == 1:
+        return next(iter(_SETTINGS_SNAPSHOTS.keys()))
+    return None
+
+
+def current_settings_project_dir() -> str | None:
+    active = _ACTIVE_SETTINGS_PROJECT_DIR.get()
+    if active:
+        return active
+    runtime_project_dir = _runtime_plan_project_dir()
+    if runtime_project_dir:
+        return runtime_project_dir
+    if len(_SETTINGS_SNAPSHOTS) == 1:
+        return next(iter(_SETTINGS_SNAPSHOTS.keys()))
+    return None
+
+
+def _normalize_current_pz_env(value: object, *, default: str = "develop") -> str:
+    raw = str(value or "").strip().lower()
+    if raw in {"dev", "development"}:
+        return "develop"
+    if raw in {"prod", "production"}:
+        return "product"
+    if raw in {"develop", "test", "product"}:
+        return raw
+    fallback = str(default or "develop").strip().lower()
+    if fallback in {"test", "product"}:
+        return fallback
+    return "develop"
+
+
+def current_pz_env(*, project_dir: str | Path | None = None, default: str = "develop") -> str:
+    bound_snapshot = _resolve_bound_snapshot(project_dir)
+    if bound_snapshot is not None:
+        try:
+            resolved = resolve_settings(project_dir=_normalize_project_dir(project_dir))
+            return _normalize_current_pz_env(getattr(resolved.project, "pz_env", None), default=default)
+        except Exception:
+            pass
+        payload = getattr(bound_snapshot, "data", {}) or {}
+        project_payload = payload.get("project") if isinstance(payload, dict) else {}
+        return _normalize_current_pz_env(
+            project_payload.get("pz_env") if isinstance(project_payload, dict) else None,
+            default=default,
+        )
+    resolved = resolve_settings(project_dir=_normalize_project_dir(project_dir))
+    return _normalize_current_pz_env(getattr(resolved.project, "pz_env", None), default=default)
+
+
+def bind_settings_snapshot(
+    snapshot: SettingsSnapshot,
+    *,
+    project_dir: str | Path | None = None,
+) -> SettingsSnapshot:
+    normalized_project_dir = _normalize_project_dir(
+        project_dir if project_dir is not None else _snapshot_project_dir(snapshot)
+    )
+    if normalized_project_dir:
+        _SETTINGS_SNAPSHOTS[normalized_project_dir] = snapshot
+        _SETTINGS_SNAPSHOT_REFCOUNTS[normalized_project_dir] = (
+            int(_SETTINGS_SNAPSHOT_REFCOUNTS.get(normalized_project_dir, 0)) + 1
+        )
+    _invalidate_settings_runtime_caches()
+    return snapshot
+
+
+def reset_settings_binding(project_dir: str | Path | None = None) -> None:
+    normalized_project_dir = _normalize_project_dir(project_dir)
+    if normalized_project_dir is None:
+        _SETTINGS_SNAPSHOTS.clear()
+        _SETTINGS_SNAPSHOT_REFCOUNTS.clear()
+        _invalidate_settings_runtime_caches()
+        return
+    remaining = int(_SETTINGS_SNAPSHOT_REFCOUNTS.get(normalized_project_dir, 0)) - 1
+    if remaining > 0:
+        _SETTINGS_SNAPSHOT_REFCOUNTS[normalized_project_dir] = remaining
+        return
+    _SETTINGS_SNAPSHOT_REFCOUNTS.pop(normalized_project_dir, None)
+    _SETTINGS_SNAPSHOTS.pop(normalized_project_dir, None)
+    _invalidate_settings_runtime_caches()
+
+
+@contextmanager
+def active_settings_project(project_dir: str | Path | None) -> Iterator[None]:
+    token = _ACTIVE_SETTINGS_PROJECT_DIR.set(_normalize_project_dir(project_dir))
+    try:
+        yield
+    finally:
+        _ACTIVE_SETTINGS_PROJECT_DIR.reset(token)
+
+
+@contextmanager
+def bound_settings_snapshot(
+    snapshot: SettingsSnapshot,
+    *,
+    project_dir: str | Path | None = None,
+) -> Iterator[None]:
+    bind_settings_snapshot(snapshot, project_dir=project_dir)
+    try:
+        yield
+    finally:
+        reset_settings_binding(project_dir=project_dir)
+
+
+def _env_string(*names: str) -> str:
+    return read_env_string("", *names)
+
+
+def _env_int(default: int, *names: str) -> int:
+    return read_env_int(default, *names)
+
+
+def has_runtime_env_value(*names: str) -> bool:
+    return has_env_value(*names)
+
+
+def iter_runtime_env_items() -> tuple[tuple[str, str], ...]:
+    return iter_env_items()
+
+
+def read_runtime_env_string(*names: str) -> str:
+    return _env_string(*names)
+
+
+def read_runtime_env_int(default: int, *names: str) -> int:
+    return _env_int(default, *names)
+
+
+def read_runtime_env_bool(default: bool, *names: str) -> bool:
+    return read_env_bool(default, *names)
+
+
+def read_runtime_env_float(default: float, *names: str) -> float:
+    return read_env_float(default, *names)
+
+
+def register_route_token_catalog_provider(provider: Callable[[str | Path | None], Any]) -> None:
+    global _ROUTE_TOKEN_CATALOG_PROVIDER
+    _ROUTE_TOKEN_CATALOG_PROVIDER = provider
+
+
+def reset_route_token_catalog_provider() -> None:
+    global _ROUTE_TOKEN_CATALOG_PROVIDER
+    _ROUTE_TOKEN_CATALOG_PROVIDER = None
+
+
+def _ensure_route_token_catalog_provider() -> Callable[[str | Path | None], Any]:
+    provider = _ROUTE_TOKEN_CATALOG_PROVIDER
+    if provider is not None:
+        return provider
+    raise PzError(
+        code="PZ_ROUTE_TOKEN_CATALOG_PROVIDER_MISSING",
+        message=(
+            "Route token catalog provider is not registered. "
+            "Owner packages must register it from their own formal surface."
+        ),
+        stage="settings",
+        owner="runtime.settings",
+        action="get_route_token_catalog",
+    )
+
+
+class _RouteTokenCatalogProxy:
+    def __init__(self, project_dir: str | Path | None = None) -> None:
+        self._project_dir = _normalize_project_dir(project_dir)
+
+    def _facade(self) -> Any:
+        return _ensure_route_token_catalog_provider()(self._project_dir)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._facade(), name)
+
+
+def get_route_token_catalog(*, project_dir: str | Path | None = None) -> _RouteTokenCatalogProxy:
+    return _RouteTokenCatalogProxy(project_dir=project_dir)
+
+
+def _resolve_bound_snapshot(project_dir: str | Path | None = None) -> SettingsSnapshot | None:
+    normalized_project_dir = _normalize_project_dir(project_dir)
+    runtime_plan = current_runtime_plan()
+    runtime_project_dir = _runtime_plan_project_dir()
+    runtime_settings = getattr(runtime_plan, "settings", None) if runtime_plan is not None else None
+    if runtime_settings is not None and (normalized_project_dir is None or runtime_project_dir == normalized_project_dir):
+        return runtime_settings
+    if normalized_project_dir is not None:
+        return _SETTINGS_SNAPSHOTS.get(normalized_project_dir)
+    active_project_dir = current_settings_project_dir()
+    if active_project_dir and active_project_dir in _SETTINGS_SNAPSHOTS:
+        return _SETTINGS_SNAPSHOTS[active_project_dir]
+    if len(_SETTINGS_SNAPSHOTS) == 1:
+        return next(iter(_SETTINGS_SNAPSHOTS.values()))
+    return None
+
+
+def load_project_env_values(project_dir: str | None = None) -> dict[str, str]:
+    project = compile_project_context(project_dir=project_dir)
+    return load_project_env_file(project)
+
+
+def _provider_values(snapshot: SettingsSnapshot, app_id: str, *, project_dir: str | None = None) -> dict[str, Any]:
+    if _SETTINGS_PROVIDER_RESOLUTION_DEPTH.get() > 0:
+        return {}
+    structured_values = _structured_provider_values(
+        snapshot,
+        project_dir=_normalize_project_dir(project_dir if project_dir is not None else _snapshot_project_dir(snapshot)),
+    )
+    return copy.deepcopy(structured_values.get(str(app_id).strip(), {}) or {})
+
+
+def _settings_provider_specs(
+    snapshot: SettingsSnapshot,
+    *,
+    project_dir: str | None,
+) -> tuple[SettingsProviderSpec, ...]:
+    runtime_plan = current_runtime_plan()
+    normalized_project_dir = _normalize_project_dir(
+        project_dir if project_dir is not None else _snapshot_project_dir(snapshot)
+    )
+    if runtime_plan is not None:
+        runtime_project_dir = _normalize_project_dir(getattr(getattr(runtime_plan, "project", None), "project_dir", None))
+        if runtime_project_dir == normalized_project_dir:
+            return tuple(getattr(runtime_plan, "settings_providers", ()) or ())
+
+    return _discover_settings_provider_extensions(snapshot)
+
+
+def _discover_settings_provider_extensions(snapshot: SettingsSnapshot) -> tuple[SettingsProviderSpec, ...]:
+    from pz_core.assembly.apps import compile_app_registry
+    from pz_core.assembly.extensions import compile_extension_registry
+
+    cache_key = id(snapshot)
+    cached = _SETTINGS_PROVIDER_SPECS_CACHE.get(cache_key)
+    if cached is not None and cached[0] is snapshot:
+        return cached[1]
+
+    app_registry = compile_app_registry(
+        snapshot,
+        project_dir=_snapshot_project_dir(snapshot),
+        run_init_hooks=False,
+    )
+    extension_registry = compile_extension_registry(snapshot, app_registry)
+    discovered = tuple(
+        spec
+        for spec in extension_registry.by_kind("settings.provider")
+        if isinstance(spec, SettingsProviderSpec)
+    )
+    _SETTINGS_PROVIDER_SPECS_CACHE[cache_key] = (snapshot, discovered)
+    return discovered
+
+
+def _normalize_settings_patch(
+    payload: Any,
+    *,
+    owner: str,
+    default_priority: int,
+) -> tuple[SettingsPatch, ...]:
+    def _coerce_patch(item: Any) -> SettingsPatch:
+        if isinstance(item, SettingsPatch):
+            return item
+        app_id = getattr(item, "app_id", None)
+        patch_payload = getattr(item, "payload", None)
+        source = getattr(item, "source", None)
+        priority = getattr(item, "priority", default_priority)
+        if not isinstance(app_id, str) or not app_id.strip():
+            raise PzError(
+                code="PZ_SETTINGS_PROVIDER_RESULT_INVALID",
+                message=f"Settings provider '{owner}' must return SettingsPatch objects.",
+                stage="settings",
+                owner=owner,
+                action="load_app_settings",
+            )
+        if not isinstance(patch_payload, dict):
+            raise PzError(
+                code="PZ_SETTINGS_PROVIDER_RESULT_INVALID",
+                message=f"Settings provider '{owner}' must return SettingsPatch objects.",
+                stage="settings",
+                owner=owner,
+                action="load_app_settings",
+            )
+        if not isinstance(source, str) or not source.strip():
+            raise PzError(
+                code="PZ_SETTINGS_PROVIDER_RESULT_INVALID",
+                message=f"Settings provider '{owner}' must return SettingsPatch objects.",
+                stage="settings",
+                owner=owner,
+                action="load_app_settings",
+            )
+        return SettingsPatch(
+            app_id=app_id.strip(),
+            payload=dict(patch_payload),
+            source=source.strip(),
+            priority=int(priority if priority is not None else default_priority),
+        )
+
+    if payload in (None, (), []):
+        return ()
+    if payload is not None and not isinstance(payload, (list, tuple)):
+        return (_coerce_patch(payload),)
+    if isinstance(payload, (list, tuple)):
+        out: list[SettingsPatch] = []
+        for item in payload:
+            out.append(_coerce_patch(item))
+        return tuple(out)
+    raise PzError(
+        code="PZ_SETTINGS_PROVIDER_RESULT_INVALID",
+        message=f"Settings provider '{owner}' must return a SettingsPatch or tuple of SettingsPatch.",
+        stage="settings",
+        owner=owner,
+        action="load_app_settings",
+    )
+
+
+def _iter_patch_paths(payload: dict[str, Any], prefix: tuple[str, ...] = ()) -> tuple[tuple[str, ...], ...]:
+    paths: list[tuple[str, ...]] = []
+    for key, value in payload.items():
+        current = prefix + (str(key),)
+        if isinstance(value, dict) and value:
+            paths.extend(_iter_patch_paths(value, current))
+            continue
+        paths.append(current)
+    return tuple(paths)
+
+
+def _structured_provider_values(
+    snapshot: SettingsSnapshot,
+    *,
+    project_dir: str | None,
+) -> dict[str, dict[str, Any]]:
+    normalized_project_dir = _normalize_project_dir(project_dir)
+    cache_key = (id(snapshot), normalized_project_dir)
+    cached = _SETTINGS_PROVIDER_VALUES_CACHE.get(cache_key)
+    if cached is not None and cached[0] is snapshot:
+        return cached[1]
+    token = _SETTINGS_PROVIDER_RESOLUTION_DEPTH.set(_SETTINGS_PROVIDER_RESOLUTION_DEPTH.get() + 1)
+    try:
+        providers = sorted(
+            _settings_provider_specs(snapshot, project_dir=normalized_project_dir),
+            key=lambda item: (int(item.priority), str(item.owner_app), str(item.id)),
+        )
+        if not providers:
+            return {}
+
+        project = compile_project_context(project_dir=normalized_project_dir)
+        resolved_settings = ResolvedSettings(
+            snapshot=snapshot,
+            project_dir=normalized_project_dir or _snapshot_project_dir(snapshot),
+        )
+        merged_by_app: dict[str, dict[str, Any]] = {}
+        seen_paths: dict[tuple[str, tuple[str, ...]], tuple[int, str]] = {}
+
+        for spec in providers:
+            provide = getattr(spec.provider, "provide", None)
+            if not callable(provide):
+                raise PzError(
+                    code="PZ_SETTINGS_PROVIDER_INVALID",
+                    message=f"Settings provider '{spec.id}' must declare a provider object with provide(ctx).",
+                    stage="settings",
+                    owner=spec.owner_app,
+                    action="load_app_settings",
+                )
+            try:
+                patches = _normalize_settings_patch(
+                    provide(
+                        SettingsProviderContext(
+                            project=project,
+                            snapshot=snapshot,
+                            settings=resolved_settings,
+                        )
+                    ),
+                    owner=spec.id,
+                    default_priority=int(spec.priority),
+                )
+            except PzError:
+                raise
+            except Exception as exc:
+                raise PzError(
+                    code="PZ_SETTINGS_PROVIDER_FAILED",
+                    message=f"Settings provider '{spec.id}' failed: {exc}",
+                    stage="settings",
+                    owner=spec.owner_app,
+                    action="load_app_settings",
+                ) from exc
+            for patch in patches:
+                app_name = _read_app_id(patch.app_id, action="load_app_settings")
+                payload = dict(patch.payload or {})
+                priority = int(patch.priority)
+                for path in _iter_patch_paths(payload):
+                    key = (app_name, path)
+                    previous = seen_paths.get(key)
+                    if previous is not None and previous[0] == priority:
+                        raise PzError(
+                            code="PZ_SETTINGS_PROVIDER_CONFLICT",
+                            message=(
+                                f"Settings providers '{previous[1]}' and '{patch.source}' both write "
+                                f"'{app_name}.{'.'.join(path)}' at priority {priority}."
+                            ),
+                            stage="settings",
+                            owner=app_name,
+                            action="load_app_settings",
+                        )
+                    seen_paths[key] = (priority, patch.source)
+                merged_by_app[app_name] = _deep_merge_payload(dict(merged_by_app.get(app_name, {}) or {}), payload)
+        _SETTINGS_PROVIDER_VALUES_CACHE[cache_key] = (snapshot, merged_by_app)
+        return merged_by_app
+    finally:
+        _SETTINGS_PROVIDER_RESOLUTION_DEPTH.reset(token)
+
+
+def _snapshot_project_dir(snapshot: SettingsSnapshot) -> str | None:
+    value = getattr(snapshot, "project_dir", None)
+    if value is None:
+        return None
+    try:
+        return str(value)
+    except Exception:
+        return None
+
+
+def _load_snapshot(project_dir: str | None = None) -> SettingsSnapshot:
+    project = compile_project_context(project_dir=project_dir)
+    return compile_settings_snapshot(project)
+
+
+def _snapshot() -> SettingsSnapshot:
+    return _load_snapshot()
+
+
+def _lookup_key(mapping: dict[str, Any], name: str) -> Any:
+    if name in mapping:
+        return mapping[name]
+    raise KeyError(name)
+
+
+def _declared_settings_namespaces(snapshot: SettingsSnapshot) -> frozenset[str]:
+    cache_key = id(snapshot)
+    cached = _SETTINGS_NAMESPACE_CACHE.get(cache_key)
+    if cached is not None and cached[0] is snapshot:
+        return cached[1]
+    namespaces: set[str] = set()
+    for app_id in dict(getattr(snapshot, "apps", {}) or {}).keys():
+        normalized = str(app_id or "").strip()
+        if normalized:
+            namespaces.add(normalized)
+    result = frozenset(namespaces)
+    _SETTINGS_NAMESPACE_CACHE[cache_key] = (snapshot, result)
+    return result
+
+
+def _merged_app_settings(
+    snapshot: SettingsSnapshot,
+    app_id: str,
+    *,
+    project_dir: str | None = None,
+) -> tuple[str, dict[str, Any]]:
+    values = dict(snapshot.app_settings(app_id))
+    provider_values = _provider_values(
+        snapshot,
+        app_id,
+        project_dir=project_dir if project_dir is not None else _snapshot_project_dir(snapshot),
+    )
+    if provider_values:
+        values.update(provider_values)
+    return app_id, values
+
+
+def _root_settings_payload(snapshot: SettingsSnapshot) -> dict[str, Any]:
+    payload = dict(getattr(snapshot, "data", {}) or {})
+    payload.setdefault("project_dir", getattr(snapshot, "project_dir", None))
+    payload.setdefault("installed_apps", tuple(getattr(snapshot, "installed_apps", ()) or ()))
+    payload.setdefault("app_replacements", dict(getattr(snapshot, "app_replacements", {}) or {}))
+    payload.setdefault("apps", dict(getattr(snapshot, "apps", {}) or {}))
+    payload["project"] = _project_settings_payload(snapshot, payload)
+    return payload
+
+
+def _project_settings_payload(snapshot: SettingsSnapshot, root_payload: dict[str, Any]) -> dict[str, Any]:
+    project_payload: dict[str, Any] = {}
+    for key, value in root_payload.items():
+        if key in {"project", "apps", "app_replacements"}:
+            continue
+        project_payload[key] = copy.deepcopy(value)
+
+    declared_project = root_payload.get("project")
+    if isinstance(declared_project, dict):
+        project_payload = _deep_merge_payload(project_payload, copy.deepcopy(declared_project))
+
+    if "pz_env" not in project_payload and root_payload.get("PZ_ENV") is not None:
+        project_payload["pz_env"] = copy.deepcopy(root_payload.get("PZ_ENV"))
+    project_payload.setdefault("project_dir", getattr(snapshot, "project_dir", None))
+    project_payload.setdefault("installed_apps", tuple(getattr(snapshot, "installed_apps", ()) or ()))
+    project_payload.setdefault("app_replacements", dict(getattr(snapshot, "app_replacements", {}) or {}))
+    return project_payload
+
+
+def _mapping_path_value(mapping: dict[str, Any], path: tuple[str, ...], *, default: Any = None) -> Any:
+    current: Any = mapping
+    for raw_key in path:
+        key = str(raw_key)
+        if not isinstance(current, dict):
+            return default
+        try:
+            current = _lookup_key(current, key)
+        except KeyError:
+            return default
+    return default if current is None else current
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedSettings:
+    snapshot: SettingsSnapshot
+    project_dir: str | None = None
+    _root_settings_cache: dict[str, Any] | None = field(default=None, init=False, repr=False, compare=False)
+    _project_namespace_cache: "NamespaceProxy | None" = field(default=None, init=False, repr=False, compare=False)
+    _app_settings_cache: dict[str, dict[str, Any]] = field(default_factory=dict, init=False, repr=False, compare=False)
+
+    def _root_settings_cached(self) -> dict[str, Any]:
+        cached = self._root_settings_cache
+        if cached is None:
+            cached = _root_settings_payload(self.snapshot)
+            object.__setattr__(self, "_root_settings_cache", cached)
+        return cached
+
+    def _app_settings_payload(self, app_id: str) -> tuple[str, dict[str, Any]]:
+        normalized_app_id = _read_app_id(app_id, action="resolved_settings.app_settings")
+        cached = self._app_settings_cache.get(normalized_app_id)
+        if cached is not None:
+            return normalized_app_id, cached
+        resolved_app_id, values = _merged_app_settings(
+            self.snapshot,
+            normalized_app_id,
+            project_dir=self.project_dir if self.project_dir is not None else _snapshot_project_dir(self.snapshot),
+        )
+        cached_values = dict(values)
+        self._app_settings_cache[normalized_app_id] = cached_values
+        return resolved_app_id, cached_values
+
+    def root_settings(self) -> dict[str, Any]:
+        return dict(self._root_settings_cached())
+
+    @property
+    def project(self) -> "NamespaceProxy":
+        cached = self._project_namespace_cache
+        if cached is not None:
+            return cached
+        payload = _mapping_path_value(self._root_settings_cached(), ("project",), default={})
+        namespace = NamespaceProxy(payload if isinstance(payload, dict) else {})
+        object.__setattr__(self, "_project_namespace_cache", namespace)
+        return namespace
+
+    @property
+    def route_token_catalog(self) -> _RouteTokenCatalogProxy:
+        return get_route_token_catalog(
+            project_dir=self.project_dir if self.project_dir is not None else _snapshot_project_dir(self.snapshot)
+        )
+
+    def app_settings(self, app_id: str) -> dict[str, Any]:
+        _resolved, values = self._app_settings_payload(app_id)
+        return dict(values)
+
+    def typed_app_settings(
+        self,
+        app_id: str,
+        settings_type: type[TAppSettings],
+        *,
+        normalize: Callable[[dict[str, Any]], dict[str, Any]] | None = None,
+    ) -> TAppSettings:
+        normalized_app_id = _read_app_id(app_id, action="resolved_settings.typed_app_settings")
+        payload = self.app_settings(normalized_app_id)
+        if isinstance(payload, settings_type):
+            return payload
+        values = dict(payload or {})
+        if normalize is not None:
+            try:
+                values = dict(normalize(values) or {})
+            except Exception as exc:
+                raise PzError(
+                    code="PZ_APP_SETTINGS_NORMALIZE_FAILED",
+                    message=f"Failed to normalize typed app settings for '{normalized_app_id}': {exc}",
+                    stage="settings",
+                    owner=normalized_app_id,
+                    action="load_typed_app_settings",
+                ) from exc
+        try:
+            return settings_type(**values)
+        except Exception as exc:
+            raise PzError(
+                code="PZ_APP_SETTINGS_TYPE_INVALID",
+                message=f"Failed to build typed app settings for '{normalized_app_id}': {exc}",
+                stage="settings",
+                owner=normalized_app_id,
+                action="load_typed_app_settings",
+            ) from exc
+
+    def get(self, *path: str, default: Any = None) -> Any:
+        if not path:
+            return default
+        head = str(path[0]).strip()
+        if head in _declared_settings_namespaces(self.snapshot):
+            _resolved, app_values = self._app_settings_payload(head)
+            if len(path) == 1:
+                return dict(app_values)
+            return _mapping_path_value(app_values, tuple(str(item) for item in path[1:]), default=default)
+        return _mapping_path_value(self._root_settings_cached(), tuple(str(item) for item in path), default=default)
+
+    def to_dict(self) -> dict[str, Any]:
+        payload = dict(self._root_settings_cached())
+        payload["apps"] = {
+            str(app_id): self.app_settings(str(app_id))
+            for app_id in dict(getattr(self.snapshot, "apps", {}) or {}).keys()
+        }
+        return payload
+
+    def __getattr__(self, name: str) -> Any:
+        if name in _declared_settings_namespaces(self.snapshot):
+            _resolved, values = self._app_settings_payload(name)
+            return NamespaceProxy(values)
+        raise AttributeError(name)
+
+
+class NamespaceProxy:
+    def __init__(self, payload: Any) -> None:
+        self._payload = payload
+
+    def _mapping(self) -> dict[str, Any]:
+        if isinstance(self._payload, dict):
+            return self._payload
+        return getattr(self._payload, "__dict__", {})
+
+    def get(self, key: str, default: Any = None) -> Any:
+        try:
+            value = _lookup_key(self._mapping(), key)
+        except KeyError:
+            return default
+        return _wrap(value)
+
+    def to_dict(self) -> dict[str, Any]:
+        return dict(self._mapping())
+
+    def __getattr__(self, name: str) -> Any:
+        try:
+            value = _lookup_key(self._mapping(), name)
+        except KeyError as exc:
+            raise AttributeError(name) from exc
+        return _wrap(value)
+
+    def __bool__(self) -> bool:
+        return bool(self._payload)
+
+    def __iter__(self):
+        return iter(self._mapping())
+
+    def items(self):
+        return self._mapping().items()
+
+
+def _wrap(value: Any) -> Any:
+    if isinstance(value, dict):
+        return NamespaceProxy(value)
+    return value
+
+
+def _read_app_id(app_id: object, *, action: str) -> str:
+    if not isinstance(app_id, str) or not app_id.strip():
+        raise PzError(
+            code="PZ_APP_SETTINGS_IDENTIFIER_INVALID",
+            message="app_id must be a non-empty string.",
+            stage="settings",
+            owner="runtime.settings",
+            action=action,
+        )
+    return app_id.strip()
+
+
+def resolve_settings(project_dir: str | None = None) -> ResolvedSettings:
+    effective_project_dir = _effective_project_dir(project_dir)
+    snapshot = ensure_full_settings(project_dir=effective_project_dir)
+    resolved_project_dir = effective_project_dir or _snapshot_project_dir(snapshot)
+    cache_key = (id(snapshot), resolved_project_dir)
+    cached = _RESOLVED_SETTINGS_CACHE.get(cache_key)
+    if cached is not None and cached[0] is snapshot:
+        return cached[1]
+    resolved = ResolvedSettings(
+        snapshot=snapshot,
+        project_dir=resolved_project_dir,
+    )
+    _RESOLVED_SETTINGS_CACHE[cache_key] = (snapshot, resolved)
+    return resolved
+
+
+def ensure_full_settings(_current: Any = None, *, project_dir: str | None = None):
+    effective_project_dir = _effective_project_dir(project_dir)
+    snapshot = _resolve_bound_snapshot(effective_project_dir)
+    if snapshot is not None:
+        return snapshot
+    return _load_snapshot(project_dir=effective_project_dir)
+
+__all__ = [
+    "active_settings_project",
+    "bound_settings_snapshot",
+    "build_local_default_settings",
+    "build_local_default_settings_chain",
+    "bind_settings_snapshot",
+    "current_pz_env",
+    "current_settings_project_dir",
+    "ensure_full_settings",
+    "get_route_token_catalog",
+    "has_runtime_env_value",
+    "iter_runtime_env_items",
+    "load_local_default_settings",
+    "load_local_default_settings_chain",
+    "load_project_env_values",
+    "ResolvedSettings",
+    "resolve_settings",
+    "register_route_token_catalog_provider",
+    "read_runtime_env_bool",
+    "read_runtime_env_float",
+    "read_runtime_env_int",
+    "read_runtime_env_string",
+    "reset_route_token_catalog_provider",
+    "reset_settings_binding",
+]