pz-cli 5.0.0__py3-none-any.whl

pz_core/assembly/apps/compiler.py

@@ -0,0 +1,824 @@
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from importlib import import_module
+import inspect
+from pathlib import Path
+from types import ModuleType, SimpleNamespace
+from typing import Any
+
+from pz_core.assembly.app_discovery import (
+    discover_leaf_app_packages,
+    import_app_entrypoint_module_from_decl,
+    read_static_app_declaration,
+)
+from pz_core.assembly.project import active_project_import_root
+from pz_core.assembly.settings import SettingsSnapshot
+from pz_core.core.errors import PzError
+from pz_core.runtime.environment_integrity import validate_installed_app_identities
+
+
+@dataclass(frozen=True, slots=True)
+class AppDecl:
+    app_id: str
+    name: str
+    version: str
+    required_pz: str
+    module_path: str
+    entrypoint: str
+    owner: str
+    priority: int = 100
+    requires_apps: tuple[str, ...] = ()
+    required_protocols: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class AppRegistry:
+    apps: tuple[AppDecl, ...]
+    initialized_app_ids: tuple[str, ...] = ()
+
+    def by_id(self) -> dict[str, AppDecl]:
+        return {app.app_id: app for app in self.apps}
+
+
+@dataclass(frozen=True, slots=True)
+class AppInitContext:
+    app: AppDecl
+    settings: SettingsSnapshot
+    project_dir: Path | None
+    phase: str = "declared"
+
+
+_DEFAULT_APP_PRIORITY = 100
+
+
+def _loaded_pz_version() -> str:
+    from pz_core import __version__
+
+    return __version__
+
+
+def _read_app_module_path(module_path: object, *, owner: str) -> str:
+    if not isinstance(module_path, str) or not module_path.strip():
+        raise PzError(
+            code="PZ_APP_INVALID_PATH",
+            message="installed_apps contains an empty or invalid app path.",
+            stage="apps",
+            owner=owner,
+            action="compile_app_registry",
+        )
+    return module_path.strip()
+
+
+def _normalize_app_path(module_path: str) -> str:
+    value = _read_app_module_path(module_path, owner="apps")
+    if ":" in value or value.endswith(".apps"):
+        raise PzError(
+            code="PZ_APP_INVALID_PATH",
+            message=(
+                f"App path '{value}' must declare a directory/package name only; "
+                "installed_apps does not accept '<pkg>.apps' or '<pkg>.apps:app'."
+            ),
+            stage="apps",
+            owner=value,
+            action="compile_app_registry",
+        )
+    return f"{value}.apps:app"
+
+
+def _import_app_module(entrypoint: str) -> tuple[ModuleType, Any]:
+    module_name, _, attr_name = entrypoint.partition(":")
+    try:
+        module = import_module(module_name)
+    except Exception as exc:
+        raise PzError(
+            code="PZ_APP_IMPORT_FAILED",
+            message=f"Failed to import app module '{module_name}': {exc}",
+            stage="apps",
+            owner=module_name,
+            action="compile_app_registry",
+        ) from exc
+    try:
+        app = getattr(module, attr_name)
+    except AttributeError as exc:
+        raise PzError(
+            code="PZ_APP_ENTRY_MISSING",
+            message=f"App module '{module_name}' does not expose '{attr_name}'.",
+            stage="apps",
+            owner=module_name,
+            action="compile_app_registry",
+        ) from exc
+    return module, app
+
+
+def load_app_object_from_decl(decl: AppDecl) -> Any:
+    _, app = _import_app_module(decl.entrypoint)
+    return app
+
+
+def load_app_entrypoint_object_from_decl(decl: AppDecl) -> Any:
+    try:
+        module = import_app_entrypoint_module_from_decl(
+            decl.module_path,
+            action="load_app_entrypoint_object",
+        )
+    except PzError:
+        raise
+    attr_name = decl.entrypoint.partition(":")[2] or "app"
+    try:
+        return getattr(module, attr_name)
+    except AttributeError as exc:
+        raise PzError(
+            code="PZ_APP_ENTRY_MISSING",
+            message=f"App module '{decl.module_path}.apps' does not expose '{attr_name}'.",
+            stage="apps",
+            owner=decl.module_path,
+            action="load_app_entrypoint_object",
+        ) from exc
+
+
+def _declaration_fingerprint(app: Any) -> tuple[object, ...]:
+    requires_apps = getattr(app, "requires_apps", ())
+    if isinstance(requires_apps, (list, tuple)):
+        normalized_requires_apps = tuple(requires_apps)
+    else:
+        normalized_requires_apps = requires_apps
+
+    required_protocols = getattr(app, "required_protocols", ())
+    if isinstance(required_protocols, (list, tuple)):
+        normalized_required_protocols = tuple(required_protocols)
+    else:
+        normalized_required_protocols = required_protocols
+
+    return (
+        getattr(app, "id", None),
+        getattr(app, "name", None),
+        getattr(app, "version", None),
+        getattr(app, "required_pz", None),
+        getattr(app, "priority", None),
+        normalized_requires_apps,
+        normalized_required_protocols,
+    )
+
+
+def _read_required_str(app: Any, field_name: str, *, owner: str) -> str:
+    value = getattr(app, field_name, None)
+    if not isinstance(value, str) or not value.strip():
+        raise PzError(
+            code=f"PZ_APP_{field_name.upper()}_MISSING",
+            message=f"App '{owner}' must declare non-empty '{field_name}'.",
+            stage="apps",
+            owner=owner,
+            action="compile_app_registry",
+        )
+    return value.strip()
+
+
+def _read_priority(app: Any, *, owner: str) -> int:
+    value = getattr(app, "priority", None)
+    if value is None:
+        return _DEFAULT_APP_PRIORITY
+    if isinstance(value, bool):
+        raise PzError(
+            code="PZ_APP_PRIORITY_INVALID",
+            message=f"App '{owner}' must declare integer priority when provided.",
+            stage="apps",
+            owner=owner,
+            action="compile_app_registry",
+        )
+    if isinstance(value, int):
+        return int(value)
+    if isinstance(value, str) and value.strip():
+        try:
+            return int(value.strip())
+        except ValueError as exc:
+            raise PzError(
+                code="PZ_APP_PRIORITY_INVALID",
+                message=f"App '{owner}' must declare integer priority when provided.",
+                stage="apps",
+                owner=owner,
+                action="compile_app_registry",
+            ) from exc
+    raise PzError(
+        code="PZ_APP_PRIORITY_INVALID",
+        message=f"App '{owner}' must declare integer priority when provided.",
+        stage="apps",
+        owner=owner,
+        action="compile_app_registry",
+    )
+
+
+def _read_sequence(app: Any, field_name: str) -> tuple[str, ...]:
+    value = getattr(app, field_name, ())
+    if value is None:
+        return ()
+    if not isinstance(value, (tuple, list)):
+        raise PzError(
+            code=f"PZ_APP_{field_name.upper()}_INVALID",
+            message=f"App field '{field_name}' must be declared as a list or tuple of strings.",
+            stage="apps",
+            owner=getattr(app, "id", "<unknown>"),
+            action="compile_app_registry",
+        )
+    out: list[str] = []
+    for index, item in enumerate(value):
+        if not isinstance(item, str):
+            raise PzError(
+                code=f"PZ_APP_{field_name.upper()}_ITEM_INVALID",
+                message=(
+                    f"App field '{field_name}' entry at index {index} must be a non-empty string."
+                ),
+                stage="apps",
+                owner=getattr(app, "id", "<unknown>"),
+                action="compile_app_registry",
+            )
+        current = item.strip()
+        if not current:
+            raise PzError(
+                code=f"PZ_APP_{field_name.upper()}_ITEM_INVALID",
+                message=(
+                    f"App field '{field_name}' entry at index {index} must be a non-empty string."
+                ),
+                stage="apps",
+                owner=getattr(app, "id", "<unknown>"),
+                action="compile_app_registry",
+            )
+        out.append(current)
+    return tuple(out)
+
+
+def _parse_version_tuple(value: str, *, owner: str) -> tuple[int, ...]:
+    normalized = value.strip()
+    if not normalized:
+        raise PzError(
+            code="PZ_APP_REQUIRED_PZ_INVALID",
+            message=f"App '{owner}' declares an empty required_pz version segment.",
+            stage="apps",
+            owner=owner,
+            action="compile_app_registry",
+        )
+    parts: list[int] = []
+    for raw in normalized.split("."):
+        segment = raw.strip()
+        if not segment or not segment.isdigit():
+            raise PzError(
+                code="PZ_APP_REQUIRED_PZ_INVALID",
+                message=(
+                    f"App '{owner}' declares invalid required_pz version segment '{raw}'. "
+                    "Use dot-separated numeric versions."
+                ),
+                stage="apps",
+                owner=owner,
+                action="compile_app_registry",
+            )
+        parts.append(int(segment))
+    return tuple(parts)
+
+
+def _compare_versions(left: str, right: str, *, owner: str) -> int:
+    l_parts = list(_parse_version_tuple(left, owner=owner))
+    r_parts = list(_parse_version_tuple(right, owner=owner))
+    width = max(len(l_parts), len(r_parts), 1)
+    l_parts.extend([0] * (width - len(l_parts)))
+    r_parts.extend([0] * (width - len(r_parts)))
+    if tuple(l_parts) < tuple(r_parts):
+        return -1
+    if tuple(l_parts) > tuple(r_parts):
+        return 1
+    return 0
+
+
+def _satisfies_required_pz(required_pz: str, *, current_pz: str, owner: str) -> bool:
+    for raw_spec in required_pz.split(","):
+        spec = raw_spec.strip()
+        if not spec:
+            continue
+        for operator in (">=", "<=", "==", "!=", ">", "<"):
+            if spec.startswith(operator):
+                target = spec[len(operator):].strip()
+                if not target:
+                    raise PzError(
+                        code="PZ_APP_REQUIRED_PZ_INVALID",
+                        message=(
+                            f"App '{owner}' declares invalid required_pz constraint "
+                            f"'{required_pz}'."
+                        ),
+                        stage="apps",
+                        owner=owner,
+                        action="compile_app_registry",
+                    )
+                cmp = _compare_versions(current_pz, target, owner=owner)
+                if operator == ">=":
+                    ok = cmp >= 0
+                elif operator == "<=":
+                    ok = cmp <= 0
+                elif operator == "==":
+                    ok = cmp == 0
+                elif operator == "!=":
+                    ok = cmp != 0
+                elif operator == ">":
+                    ok = cmp > 0
+                else:
+                    ok = cmp < 0
+                if not ok:
+                    return False
+                break
+        else:
+            raise PzError(
+                code="PZ_APP_REQUIRED_PZ_INVALID",
+                message=(
+                    f"App '{owner}' declares invalid required_pz constraint "
+                    f"'{required_pz}'."
+                ),
+                stage="apps",
+                owner=owner,
+                action="compile_app_registry",
+            )
+    return True
+
+
+def _validate_protocol_names(app: AppDecl) -> None:
+    invalid = tuple(
+        item for item in app.required_protocols if ":" in item or "/" in item or "\\" in item
+    )
+    if invalid:
+        raise PzError(
+            code="PZ_APP_PROTOCOL_INVALID",
+            message=(
+                f"App '{app.app_id}' has invalid required_protocols entries: "
+                + ", ".join(invalid)
+            ),
+            stage="apps",
+            owner=app.app_id,
+            action="compile_app_registry",
+        )
+
+
+def _run_init_hook(
+    decl: AppDecl,
+    app_obj: Any,
+    *,
+    settings: SettingsSnapshot,
+    project_dir: Path | None,
+) -> None:
+    hook = getattr(app_obj, "init", None)
+    if hook is None:
+        return
+    if not callable(hook):
+        raise PzError(
+            code="PZ_APP_INIT_INVALID",
+            message=f"App '{decl.app_id}' exposes non-callable hook 'init'.",
+            stage="apps",
+            owner=decl.app_id,
+            action="compile_app_registry",
+        )
+    before = _declaration_fingerprint(app_obj)
+    signature = inspect.signature(hook)
+    param_count = len(signature.parameters)
+    context = AppInitContext(app=decl, settings=settings, project_dir=project_dir)
+    if param_count == 0:
+        result = hook()
+    elif param_count == 1:
+        result = hook(context)
+    else:
+        raise PzError(
+            code="PZ_APP_INIT_SIGNATURE_INVALID",
+            message=f"App '{decl.app_id}' init() must accept zero or one argument.",
+            stage="apps",
+            owner=decl.app_id,
+            action="compile_app_registry",
+        )
+    try:
+        if inspect.isawaitable(result):
+            try:
+                asyncio.get_running_loop()
+            except RuntimeError:
+                asyncio.run(result)
+            else:
+                raise PzError(
+                    code="PZ_APP_INIT_ASYNC_IN_RUNNING_LOOP",
+                    message=(
+                        f"App '{decl.app_id}' init() returned an awaitable inside a running loop. "
+                        "Compile-time init must complete synchronously."
+                    ),
+                    stage="apps",
+                    owner=decl.app_id,
+                    action="compile_app_registry",
+                )
+    except PzError:
+        raise
+    except Exception as exc:
+        raise PzError(
+            code="PZ_APP_INIT_FAILED",
+            message=f"App '{decl.app_id}' init() failed: {exc}",
+            stage="apps",
+            owner=decl.app_id,
+            action="compile_app_registry",
+        ) from exc
+    after = _declaration_fingerprint(app_obj)
+    if after != before:
+        raise PzError(
+            code="PZ_APP_INIT_MUTATES_DECLARATION",
+            message=(
+                f"App '{decl.app_id}' init() mutated formal declaration fields. "
+                "Declaration metadata must stay stable across declared -> compiled."
+            ),
+            stage="apps",
+            owner=decl.app_id,
+            action="compile_app_registry",
+        )
+
+
+def _load_decl(module_path: str, *, current_pz: str) -> AppDecl:
+    module_path = _read_app_module_path(module_path, owner="apps")
+    entrypoint = _normalize_app_path(module_path)
+    try:
+        static_decl = read_static_app_declaration(module_path, action="compile_app_registry")
+    except PzError as exc:
+        if exc.code == "PZ_APP_DECLARATION_NOT_FOUND":
+            raise PzError(
+                code="PZ_APP_IMPORT_FAILED",
+                message=f"Failed to locate app module '{module_path}.apps'.",
+                stage="apps",
+                owner=module_path,
+                action="compile_app_registry",
+                detail=exc.detail,
+            ) from exc
+        raise
+    app = SimpleNamespace(
+        id=static_decl.app_id,
+        name=static_decl.name,
+        version=static_decl.version,
+        required_pz=static_decl.required_pz,
+        priority=static_decl.priority,
+        requires_apps=static_decl.requires_apps,
+        required_protocols=static_decl.required_protocols,
+    )
+
+    app_id = _read_declared_app_id(app, module_path=module_path)
+    decl = AppDecl(
+        app_id=app_id,
+        name=_read_required_str(app, "name", owner=app_id),
+        version=_read_required_str(app, "version", owner=app_id),
+        required_pz=_read_required_str(app, "required_pz", owner=app_id),
+        module_path=module_path,
+        entrypoint=entrypoint,
+        owner=app_id,
+        priority=_read_priority(app, owner=app_id),
+        requires_apps=_read_sequence(app, "requires_apps"),
+        required_protocols=_read_sequence(app, "required_protocols"),
+    )
+    _validate_protocol_names(decl)
+    if not _satisfies_required_pz(
+        decl.required_pz,
+        current_pz=current_pz,
+        owner=decl.app_id,
+    ):
+        raise PzError(
+            code="PZ_APP_REQUIRED_PZ_MISMATCH",
+            message=(
+                f"App '{decl.app_id}' requires pz '{decl.required_pz}', "
+                f"current pz is '{current_pz}'."
+            ),
+            stage="apps",
+            owner=decl.app_id,
+            action="compile_app_registry",
+    )
+    return decl
+
+
+def _read_declared_app_id(app: Any, *, module_path: str) -> str:
+    candidate = getattr(app, "id", None)
+    if isinstance(candidate, str) and candidate.strip():
+        app_id = candidate.strip()
+    else:
+        app_id = ""
+    if not app_id:
+        raise PzError(
+            code="PZ_APP_ID_MISSING",
+            message=f"App '{module_path}' must explicitly declare app.id.",
+            stage="apps",
+            owner=module_path,
+            action="compile_app_registry",
+        )
+    if not app_id.isidentifier():
+        raise PzError(
+            code="PZ_APP_ID_INVALID",
+            message=f"App '{module_path}' must declare a valid app.id identifier.",
+            stage="apps",
+            owner=module_path,
+            action="compile_app_registry",
+        )
+    return app_id
+
+
+def _validate_replacements(
+    installed_by_path: dict[str, AppDecl],
+    app_replacements: dict[str, str],
+) -> tuple[dict[str, str], set[str]]:
+    target_to_replacement: dict[str, str] = {}
+    replacement_sources: set[str] = set()
+    for target_path, replacement_path in app_replacements.items():
+        if target_path not in installed_by_path:
+            raise PzError(
+                code="PZ_APP_REPLACEMENT_TARGET_MISSING",
+                message=f"Replacement target '{target_path}' is not in installed_apps.",
+                stage="apps",
+                owner=target_path,
+                action="compile_app_registry",
+            )
+        if replacement_path not in installed_by_path:
+            raise PzError(
+                code="PZ_APP_REPLACEMENT_SOURCE_MISSING",
+                message=f"Replacement source '{replacement_path}' is not in installed_apps.",
+                stage="apps",
+                owner=replacement_path,
+                action="compile_app_registry",
+            )
+        if target_path in target_to_replacement:
+            raise PzError(
+                code="PZ_APP_REPLACEMENT_DUPLICATE_TARGET",
+                message=f"Replacement target '{target_path}' is declared more than once.",
+                stage="apps",
+                owner=target_path,
+                action="compile_app_registry",
+            )
+        if replacement_path in replacement_sources:
+            raise PzError(
+                code="PZ_APP_REPLACEMENT_DUPLICATE_SOURCE",
+                message=f"Replacement source '{replacement_path}' replaces more than one app.",
+                stage="apps",
+                owner=replacement_path,
+                action="compile_app_registry",
+            )
+        if target_path == replacement_path:
+            raise PzError(
+                code="PZ_APP_REPLACEMENT_SELF_REFERENCE",
+                message=f"App '{target_path}' cannot replace itself.",
+                stage="apps",
+                owner=target_path,
+                action="compile_app_registry",
+            )
+        target_to_replacement[target_path] = replacement_path
+        replacement_sources.add(replacement_path)
+    for target_path, replacement_path in target_to_replacement.items():
+        current = replacement_path
+        seen = {target_path}
+        while current in target_to_replacement:
+            if current in seen:
+                raise PzError(
+                    code="PZ_APP_REPLACEMENT_CYCLE",
+                    message="app_replacements must be acyclic.",
+                    stage="apps",
+                    owner=target_path,
+                    action="compile_app_registry",
+                )
+            seen.add(current)
+            current = target_to_replacement[current]
+        target_decl = installed_by_path[target_path]
+        replacement_decl = installed_by_path[replacement_path]
+        if target_decl.app_id != replacement_decl.app_id:
+            raise PzError(
+                code="PZ_APP_REPLACEMENT_ID_MISMATCH",
+                message=(
+                    f"Replacement '{replacement_path}' must keep app_id '{target_decl.app_id}', "
+                    f"got '{replacement_decl.app_id}'."
+                ),
+                stage="apps",
+                owner=replacement_decl.app_id,
+                action="compile_app_registry",
+            )
+    return target_to_replacement, replacement_sources
+
+
+def _toposort_apps(apps: tuple[AppDecl, ...]) -> tuple[AppDecl, ...]:
+    seen_ids: set[str] = set()
+    for app in apps:
+        if app.app_id in seen_ids:
+            raise PzError(
+                code="PZ_APP_DUPLICATE_ID",
+                message=f"Duplicate app_id '{app.app_id}' in installed_apps.",
+                stage="apps",
+                owner=app.app_id,
+                action="compile_app_registry",
+            )
+        seen_ids.add(app.app_id)
+    by_id = {app.app_id: app for app in apps}
+    incoming: dict[str, set[str]] = {app.app_id: set() for app in apps}
+    outgoing: dict[str, set[str]] = {app.app_id: set() for app in apps}
+    order_index = {app.app_id: idx for idx, app in enumerate(apps)}
+
+    def _sort_key(app_id: str) -> tuple[int, int]:
+        current = by_id[app_id]
+        return (int(current.priority), order_index[app_id])
+
+    for app in apps:
+        for dep_id in app.requires_apps:
+            if dep_id not in by_id:
+                raise PzError(
+                    code="PZ_APP_DEPENDENCY_MISSING",
+                    message=f"App '{app.app_id}' requires missing app '{dep_id}'.",
+                    stage="apps",
+                    owner=app.app_id,
+                    action="compile_app_registry",
+                )
+            incoming[app.app_id].add(dep_id)
+            outgoing[dep_id].add(app.app_id)
+
+    ready = [app_id for app_id, deps in incoming.items() if not deps]
+    ready.sort(key=_sort_key)
+    out: list[AppDecl] = []
+    while ready:
+        current_id = ready.pop(0)
+        out.append(by_id[current_id])
+        for dependent_id in sorted(outgoing[current_id], key=_sort_key):
+            incoming[dependent_id].discard(current_id)
+            if not incoming[dependent_id] and dependent_id not in [item.app_id for item in out] and dependent_id not in ready:
+                ready.append(dependent_id)
+        ready.sort(key=_sort_key)
+
+    if len(out) != len(apps):
+        raise PzError(
+            code="PZ_APP_DEPENDENCY_CYCLE",
+            message="App dependency graph contains a cycle.",
+            stage="apps",
+            owner="apps",
+            action="compile_app_registry",
+        )
+    return tuple(out)
+
+
+def _load_active_apps(
+    settings: SettingsSnapshot,
+    *,
+    project_dir: Path | str | None = None,
+) -> tuple[AppDecl, ...]:
+    current_pz = _loaded_pz_version()
+    resolved_project_dir = Path(project_dir).resolve() if project_dir is not None else None
+    import_context_project_dir = resolved_project_dir or settings.project_dir
+    with active_project_import_root(
+        import_context_project_dir,
+        extra_import_roots=getattr(settings, "import_roots", ()),
+        preserve_loaded_modules=True,
+    ):
+        loaded_apps: list[AppDecl] = []
+        seen_paths: set[str] = set()
+        for module_path in settings.installed_apps:
+            normalized_path = _read_app_module_path(module_path, owner="installed_apps")
+            discovered_paths = discover_leaf_app_packages(
+                normalized_path,
+                project_dir=import_context_project_dir,
+            ) or (normalized_path,)
+            for discovered_path in discovered_paths:
+                if discovered_path in seen_paths:
+                    raise PzError(
+                        code="PZ_APP_DUPLICATE_PATH",
+                        message=f"Duplicate app path '{discovered_path}' in installed_apps.",
+                        stage="apps",
+                        owner=discovered_path,
+                        action="compile_app_registry",
+                    )
+                seen_paths.add(discovered_path)
+                decl = _load_decl(discovered_path, current_pz=current_pz)
+                loaded_apps.append(decl)
+
+    installed_by_path = {app.module_path: app for app in loaded_apps}
+    replacements, _ = _validate_replacements(installed_by_path, settings.app_replacements)
+    return tuple(app for app in loaded_apps if app.module_path not in replacements)
+
+
+def compile_conventional_app_order(
+    settings: SettingsSnapshot,
+    *,
+    project_dir: Path | str | None = None,
+) -> tuple[str, ...]:
+    return tuple(app.module_path for app in _toposort_apps(_load_active_apps(settings, project_dir=project_dir)))
+
+
+def merge_explicit_app_order(
+    existing: tuple[str, ...] | list[str],
+    conventional: tuple[str, ...] | list[str],
+) -> tuple[str, ...]:
+    conventional_items = tuple(str(item).strip() for item in conventional if str(item).strip())
+    conventional_set = set(conventional_items)
+    existing_items = tuple(
+        str(item).strip()
+        for item in existing
+        if str(item).strip() and str(item).strip() in conventional_set
+    )
+    if not existing_items:
+        return conventional_items
+
+    existing_set = set(existing_items)
+    inserted: set[str] = set()
+    out: list[str] = []
+    cursor = 0
+
+    for current in existing_items:
+        while cursor < len(conventional_items) and conventional_items[cursor] != current:
+            candidate = conventional_items[cursor]
+            cursor += 1
+            if candidate in existing_set or candidate in inserted:
+                continue
+            out.append(candidate)
+            inserted.add(candidate)
+        if cursor < len(conventional_items) and conventional_items[cursor] == current:
+            cursor += 1
+        out.append(current)
+
+    while cursor < len(conventional_items):
+        candidate = conventional_items[cursor]
+        cursor += 1
+        if candidate in existing_set or candidate in inserted:
+            continue
+        out.append(candidate)
+        inserted.add(candidate)
+    return tuple(out)
+
+
+def _validate_explicit_app_order(apps: tuple[AppDecl, ...]) -> None:
+    _toposort_apps(apps)
+    explicit_index = {app.app_id: idx for idx, app in enumerate(apps)}
+    for app in apps:
+        for dep_id in app.requires_apps:
+            dep_index = explicit_index.get(dep_id)
+            app_index = explicit_index.get(app.app_id)
+            if dep_index is None or app_index is None or dep_index < app_index:
+                continue
+            raise PzError(
+                code="PZ_APP_DEPENDENCY_ORDER_INVALID",
+                message=(
+                    f"App '{app.app_id}' must appear after required app '{dep_id}' in installed_apps."
+                ),
+                stage="apps",
+                owner=app.app_id,
+                action="compile_app_registry",
+            )
+
+
+def _declared_installed_apps(
+    settings: SettingsSnapshot,
+) -> tuple[str, ...]:
+    declared = tuple(str(item).strip() for item in getattr(settings, "declared_installed_apps", ()) if str(item).strip())
+    if declared:
+        return declared
+    return tuple(str(item).strip() for item in settings.installed_apps if str(item).strip())
+
+
+def _uses_explicit_leaf_app_sequence(
+    settings: SettingsSnapshot,
+    *,
+    project_dir: Path | None,
+) -> bool:
+    declared_apps = _declared_installed_apps(settings)
+    if not declared_apps:
+        return True
+    discovery_project_dir = project_dir if project_dir is not None else settings.project_dir
+    for module_path in declared_apps:
+        discovered_paths = discover_leaf_app_packages(module_path, project_dir=discovery_project_dir)
+        if not discovered_paths:
+            continue
+        if len(discovered_paths) != 1 or discovered_paths[0] != module_path:
+            return False
+    return True
+
+
+def compile_app_registry(
+    settings: SettingsSnapshot,
+    *,
+    project_dir: Path | str | None = None,
+    run_init_hooks: bool = True,
+) -> AppRegistry:
+    resolved_project_dir = Path(project_dir).resolve() if project_dir is not None else None
+    validate_installed_app_identities(
+        (*_declared_installed_apps(settings), *tuple(settings.installed_apps))
+    )
+    active_apps = _load_active_apps(settings, project_dir=resolved_project_dir)
+    validate_installed_app_identities(app.app_id for app in active_apps)
+    if _uses_explicit_leaf_app_sequence(settings, project_dir=resolved_project_dir):
+        _validate_explicit_app_order(active_apps)
+        ordered_apps = active_apps
+    else:
+        ordered_apps = _toposort_apps(active_apps)
+    import_context_project_dir = resolved_project_dir or settings.project_dir
+    with active_project_import_root(
+        import_context_project_dir,
+        extra_import_roots=getattr(settings, "import_roots", ()),
+        preserve_loaded_modules=True,
+    ):
+        initialized_app_ids: list[str] = []
+        if run_init_hooks:
+            for decl in ordered_apps:
+                app_obj = load_app_object_from_decl(decl)
+                _run_init_hook(
+                    decl,
+                    app_obj,
+                    settings=settings,
+                    project_dir=resolved_project_dir,
+                )
+                initialized_app_ids.append(decl.app_id)
+    return AppRegistry(
+        apps=ordered_apps,
+        initialized_app_ids=tuple(initialized_app_ids),
+    )