pz-cli 5.0.0__py3-none-any.whl

pz_core/assembly/extensions/compiler.py

@@ -0,0 +1,696 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from importlib import import_module
+import inspect
+from typing import Any
+
+from pz_core.assembly.apps import AppRegistry, load_app_object_from_decl
+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.core.extensions import (
+    CliToolSpec,
+    ExtensionRegistry,
+    ExtensionSpec,
+    FormalExtensionSpec,
+    HostBuilderSpec,
+    InfraProviderSpec,
+    LifecycleContributionSpec,
+    PageProfileProviderSpec,
+    ResourceContributionSpec,
+    RuntimeManifestContributionSpec,
+    ProtocolExtensionSpec,
+    ProtocolRegistrationSpec,
+    SettingsProviderSpec,
+    WorkerRoleSpec,
+)
+
+
+_MISSING = object()
+
+
+def _payload_field(payload: Any, name: str, *, default: Any = None) -> Any:
+    if isinstance(payload, Mapping):
+        return payload.get(name, default)
+    value = getattr(payload, name, _MISSING)
+    if value is _MISSING:
+        return default
+    return value
+
+
+def _resolve_dotted(target: str) -> Any:
+    module_name, attr_name = str(target or "").rsplit(".", 1)
+    module = import_module(module_name)
+    return getattr(module, attr_name)
+
+
+def _instantiate_page_profile_provider(provider: Any) -> Any:
+    if isinstance(provider, str):
+        provider = _resolve_dotted(provider)
+    if inspect.isclass(provider):
+        return provider()
+    return provider
+
+
+def _validate_page_profile_provider_spec(spec: PageProfileProviderSpec) -> PageProfileProviderSpec:
+    try:
+        provider = _instantiate_page_profile_provider(spec.provider)
+    except PzError:
+        raise
+    except Exception as exc:
+        raise PzError(
+            code="PZ_PAGE_PROFILE_PROVIDER_IMPORT_FAILED",
+            message=f"Page-profile provider '{spec.id}' failed to load during extension compilation: {exc}",
+            stage="extensions",
+            owner=spec.owner_app,
+            action="compile_extension_registry",
+        ) from exc
+    resolver = getattr(provider, "resolve_page_profile", None)
+    if not callable(resolver):
+        raise PzError(
+            code="PZ_PAGE_PROFILE_PROVIDER_INVALID",
+            message=f"Page-profile provider '{spec.id}' must expose resolve_page_profile(...).",
+            stage="extensions",
+            owner=spec.owner_app,
+            action="compile_extension_registry",
+        )
+    return spec
+
+
+def _lifecycle_handlers_match(left: Any, right: Any) -> bool:
+    if left is right:
+        return True
+    left_func = getattr(left, "__func__", None)
+    right_func = getattr(right, "__func__", None)
+    if left_func is None or right_func is None:
+        return False
+    return left_func is right_func and getattr(left, "__self__", None) is getattr(right, "__self__", None)
+
+
+def _declares_matching_lifecycle_hook(
+    declared: tuple[FormalExtensionSpec, ...],
+    *,
+    owner_app: str,
+    phase: str,
+    handler: Any,
+) -> bool:
+    for item in declared:
+        if not isinstance(item, LifecycleContributionSpec):
+            continue
+        if item.owner_app != owner_app or item.phase != phase:
+            continue
+        if _lifecycle_handlers_match(item.handler, handler):
+            return True
+    return False
+
+
+def _synthesized_lifecycle_contributions(
+    app_decl: Any,
+    app_obj: Any,
+    *,
+    declared: tuple[FormalExtensionSpec, ...],
+) -> tuple[LifecycleContributionSpec, ...]:
+    out: list[LifecycleContributionSpec] = []
+    for phase in ("startup", "shutdown"):
+        hook = getattr(app_obj, phase, None)
+        if hook is None:
+            continue
+        if not callable(hook):
+            raise PzError(
+                code="PZ_APP_LIFECYCLE_HOOK_INVALID",
+                message=f"App '{app_decl.app_id}' exposes non-callable hook '{phase}'.",
+                stage="extensions",
+                owner=app_decl.app_id,
+                action="compile_extension_registry",
+            )
+        if _declares_matching_lifecycle_hook(
+            declared,
+            owner_app=app_decl.app_id,
+            phase=phase,
+            handler=hook,
+        ):
+            continue
+        out.append(
+            LifecycleContributionSpec(
+                id=f"{app_decl.app_id}.app_hook.{phase}",
+                owner_app=app_decl.app_id,
+                phase=phase,
+                handler=hook,
+            )
+        )
+    return tuple(out)
+
+
+def _coerce_extension_spec(payload: Any, *, owner_hint: str) -> ExtensionSpec | None:
+    raw_kind = _payload_field(payload, "kind")
+    raw_id = _payload_field(payload, "id")
+    raw_owner = _payload_field(payload, "owner_app", default=owner_hint)
+    if not isinstance(raw_kind, str) or not raw_kind.strip():
+        return None
+    if not isinstance(raw_id, str) or not raw_id.strip():
+        return None
+    if not isinstance(raw_owner, str) or not raw_owner.strip():
+        return None
+    return ExtensionSpec(
+        id=raw_id,
+        kind=raw_kind,
+        owner_app=raw_owner,
+        api_version=str(_payload_field(payload, "api_version", default="v1") or "v1"),
+        priority=int(_payload_field(payload, "priority", default=100) or 100),
+        title=str(_payload_field(payload, "title", default="") or ""),
+        payload=dict(_payload_field(payload, "payload", default=None) or {}),
+        source=str(_payload_field(payload, "source", default="") or ""),
+        provides=tuple(_payload_field(payload, "provides", default=()) or ()),
+        conflicts=tuple(_payload_field(payload, "conflicts", default=()) or ()),
+    )
+
+
+def _coerce_host_builder_spec(payload: Any, *, owner_hint: str) -> HostBuilderSpec | None:
+    builder = _payload_field(payload, "builder")
+    if builder is None:
+        return None
+    raw_id = _payload_field(payload, "id")
+    raw_owner = _payload_field(payload, "owner_app", default=owner_hint)
+    raw_kind = _payload_field(payload, "kind", default="host.builder")
+    if not isinstance(raw_id, str) or not raw_id.strip():
+        return None
+    if not isinstance(raw_owner, str) or not raw_owner.strip():
+        return None
+    if str(raw_kind or "").strip() != "host.builder":
+        return None
+    return HostBuilderSpec(
+        id=raw_id,
+        owner_app=raw_owner,
+        builder=builder,
+        kind="host.builder",
+        runtime_kind=str(_payload_field(payload, "runtime_kind", default="web") or "web"),
+        api_version=str(_payload_field(payload, "api_version", default="v1") or "v1"),
+        priority=int(_payload_field(payload, "priority", default=100) or 100),
+        title=str(_payload_field(payload, "title", default="") or ""),
+    )
+
+
+def _coerce_settings_provider_spec(payload: Any, *, owner_hint: str) -> SettingsProviderSpec | None:
+    provider = _payload_field(payload, "provider")
+    if provider is None:
+        return None
+    raw_id = _payload_field(payload, "id")
+    raw_owner = _payload_field(payload, "owner_app", default=owner_hint)
+    raw_kind = _payload_field(payload, "kind", default="settings.provider")
+    if not isinstance(raw_id, str) or not raw_id.strip():
+        return None
+    if not isinstance(raw_owner, str) or not raw_owner.strip():
+        return None
+    if str(raw_kind or "").strip() != "settings.provider":
+        return None
+    return SettingsProviderSpec(
+        id=raw_id,
+        owner_app=raw_owner,
+        provider=provider,
+        kind="settings.provider",
+        api_version=str(_payload_field(payload, "api_version", default="v1") or "v1"),
+        priority=int(_payload_field(payload, "priority", default=100) or 100),
+    )
+
+
+def _coerce_infra_provider_spec(payload: Any, *, owner_hint: str) -> InfraProviderSpec | None:
+    provider = _payload_field(payload, "provider")
+    if provider is None:
+        return None
+    raw_id = _payload_field(payload, "id")
+    raw_owner = _payload_field(payload, "owner_app", default=owner_hint)
+    raw_kind = _payload_field(payload, "kind", default="infra.provider")
+    if not isinstance(raw_id, str) or not raw_id.strip():
+        return None
+    if not isinstance(raw_owner, str) or not raw_owner.strip():
+        return None
+    if str(raw_kind or "").strip() != "infra.provider":
+        return None
+    return InfraProviderSpec(
+        id=raw_id,
+        owner_app=raw_owner,
+        provider=provider,
+        kind="infra.provider",
+        api_version=str(_payload_field(payload, "api_version", default="v1") or "v1"),
+        priority=int(_payload_field(payload, "priority", default=100) or 100),
+        title=str(_payload_field(payload, "title", default="") or ""),
+    )
+
+
+def _coerce_runtime_manifest_contribution_spec(
+    payload: Any,
+    *,
+    owner_hint: str,
+) -> RuntimeManifestContributionSpec | None:
+    provider = _payload_field(payload, "provider")
+    if provider is None:
+        return None
+    raw_id = _payload_field(payload, "id")
+    raw_owner = _payload_field(payload, "owner_app", default=owner_hint)
+    raw_kind = _payload_field(payload, "kind", default="runtime.manifest_contribution")
+    if not isinstance(raw_id, str) or not raw_id.strip():
+        return None
+    if not isinstance(raw_owner, str) or not raw_owner.strip():
+        return None
+    if str(raw_kind or "").strip() != "runtime.manifest_contribution":
+        return None
+    return RuntimeManifestContributionSpec(
+        id=raw_id,
+        owner_app=raw_owner,
+        provider=provider,
+        kind="runtime.manifest_contribution",
+        api_version=str(_payload_field(payload, "api_version", default="v1") or "v1"),
+        priority=int(_payload_field(payload, "priority", default=100) or 100),
+        title=str(_payload_field(payload, "title", default="") or ""),
+    )
+
+
+def _coerce_lifecycle_contribution_spec(payload: Any, *, owner_hint: str) -> LifecycleContributionSpec | None:
+    handler = _payload_field(payload, "handler")
+    phase = _payload_field(payload, "phase")
+    raw_id = _payload_field(payload, "id")
+    raw_owner = _payload_field(payload, "owner_app", default=owner_hint)
+    raw_kind = _payload_field(payload, "kind", default="lifecycle.contribution")
+    if handler is None:
+        return None
+    if not isinstance(raw_id, str) or not raw_id.strip():
+        return None
+    if not isinstance(raw_owner, str) or not raw_owner.strip():
+        return None
+    if not isinstance(phase, str) or not phase.strip():
+        return None
+    if str(raw_kind or "").strip() != "lifecycle.contribution":
+        return None
+    return LifecycleContributionSpec(
+        id=raw_id,
+        owner_app=raw_owner,
+        handler=handler,
+        phase=phase.strip(),
+        kind="lifecycle.contribution",
+        api_version=str(_payload_field(payload, "api_version", default="v1") or "v1"),
+        priority=int(_payload_field(payload, "priority", default=100) or 100),
+    )
+
+
+def _coerce_worker_role_spec(payload: Any, *, owner_hint: str) -> WorkerRoleSpec | None:
+    tool_name = _payload_field(payload, "tool_name")
+    raw_id = _payload_field(payload, "id")
+    raw_owner = _payload_field(payload, "owner_app", default=owner_hint)
+    raw_kind = _payload_field(payload, "kind", default="worker.role")
+    if not isinstance(tool_name, str) or not tool_name.strip():
+        return None
+    if not isinstance(raw_id, str) or not raw_id.strip():
+        return None
+    if not isinstance(raw_owner, str) or not raw_owner.strip():
+        return None
+    if str(raw_kind or "").strip() != "worker.role":
+        return None
+    return WorkerRoleSpec(
+        id=raw_id,
+        owner_app=raw_owner,
+        tool_name=tool_name.strip(),
+        kind="worker.role",
+        api_version=str(_payload_field(payload, "api_version", default="v1") or "v1"),
+        priority=int(_payload_field(payload, "priority", default=100) or 100),
+        title=str(_payload_field(payload, "title", default="") or ""),
+        name=str(_payload_field(payload, "name", default="") or "").strip(),
+        auto_start=bool(_payload_field(payload, "auto_start", default=False)),
+        auto_start_setting=str(_payload_field(payload, "auto_start_setting", default="") or "").strip(),
+        restart=str(_payload_field(payload, "restart", default="always") or "always").strip() or "always",
+        worker_kind=(
+            str(
+                _payload_field(payload, "worker_kind", default="infrastructure_worker")
+                or "infrastructure_worker"
+            )
+            .strip()
+            or "infrastructure_worker"
+        ),
+        replica_count_setting=str(_payload_field(payload, "replica_count_setting", default="") or "").strip(),
+        description=str(_payload_field(payload, "description", default="") or "").strip(),
+    )
+
+
+def _coerce_cli_tool_spec(payload: Any, *, owner_hint: str) -> CliToolSpec | None:
+    tool = _payload_field(payload, "tool")
+    command = _payload_field(payload, "command")
+    summary = _payload_field(payload, "summary")
+    raw_id = _payload_field(payload, "id")
+    raw_owner = _payload_field(payload, "owner_app", default=owner_hint)
+    raw_kind = _payload_field(payload, "kind", default="cli.tool")
+    if tool is None:
+        return None
+    if not isinstance(raw_id, str) or not raw_id.strip():
+        return None
+    if not isinstance(raw_owner, str) or not raw_owner.strip():
+        return None
+    if str(raw_kind or "").strip() != "cli.tool":
+        return None
+    if isinstance(command, str):
+        command_parts = (command.strip(),) if command.strip() else ()
+    else:
+        command_parts = tuple(str(item).strip() for item in tuple(command or ()) if str(item).strip())
+    if not command_parts:
+        return None
+    return CliToolSpec(
+        id=raw_id,
+        owner_app=raw_owner,
+        command=command_parts,
+        summary=str(summary or "").strip(),
+        tool=tool,
+        kind="cli.tool",
+        api_version=str(_payload_field(payload, "api_version", default="v1") or "v1"),
+        priority=int(_payload_field(payload, "priority", default=100) or 100),
+        title=str(_payload_field(payload, "title", default="") or ""),
+    )
+
+
+def _coerce_page_profile_provider_spec(payload: Any, *, owner_hint: str) -> PageProfileProviderSpec | None:
+    provider = _payload_field(payload, "provider")
+    if provider is None:
+        return None
+    raw_id = _payload_field(payload, "id")
+    raw_owner = _payload_field(payload, "owner_app", default=owner_hint)
+    raw_kind = _payload_field(payload, "kind", default="page.profile_provider")
+    if not isinstance(raw_id, str) or not raw_id.strip():
+        return None
+    if not isinstance(raw_owner, str) or not raw_owner.strip():
+        return None
+    if str(raw_kind or "").strip() != "page.profile_provider":
+        return None
+    return PageProfileProviderSpec(
+        id=raw_id,
+        owner_app=raw_owner,
+        provider=provider,
+        kind="page.profile_provider",
+        api_version=str(_payload_field(payload, "api_version", default="v1") or "v1"),
+        priority=int(_payload_field(payload, "priority", default=100) or 100),
+        title=str(_payload_field(payload, "title", default="") or ""),
+    )
+
+
+def _coerce_resource_contribution_spec(payload: Any, *, owner_hint: str) -> ResourceContributionSpec | None:
+    raw_kind = _payload_field(payload, "kind", default="resource.contribution")
+    if str(raw_kind or "").strip() != "resource.contribution":
+        return None
+    raw_id = _payload_field(payload, "id")
+    raw_owner = _payload_field(payload, "owner_app", default=owner_hint)
+    if not isinstance(raw_id, str) or not raw_id.strip():
+        return None
+    if not isinstance(raw_owner, str) or not raw_owner.strip():
+        return None
+
+    def _read_tuple(field_name: str) -> tuple[Any, ...]:
+        value = _payload_field(payload, field_name, default=())
+        if value in (None, ()):
+            return ()
+        if isinstance(value, tuple):
+            return value
+        if isinstance(value, list):
+            return tuple(value)
+        return ()
+
+    def _read_locale_allowlist(field_name: str) -> tuple[str, ...]:
+        items = _read_tuple(field_name)
+        out: list[str] = []
+        for item in items:
+            if not isinstance(item, str) or not item.strip():
+                return ()
+            out.append(item.strip())
+        return tuple(out)
+
+    return ResourceContributionSpec(
+        id=raw_id,
+        owner_app=raw_owner,
+        templates_dir=str(_payload_field(payload, "templates_dir", default="templates") or "templates"),
+        static_dir=str(_payload_field(payload, "static_dir", default="static") or "static"),
+        locales_dir=str(_payload_field(payload, "locales_dir", default="locales") or "locales"),
+        migrations_dir=str(_payload_field(payload, "migrations_dir", default="migrations") or "migrations"),
+        kind="resource.contribution",
+        api_version=str(_payload_field(payload, "api_version", default="v1") or "v1"),
+        priority=int(_payload_field(payload, "priority", default=100) or 100),
+        title=str(_payload_field(payload, "title", default="") or ""),
+        locale_bundles=tuple(dict(item) for item in _read_tuple("locale_bundles") if isinstance(item, dict)),
+        locale_dependencies=tuple(
+            dict(item) for item in _read_tuple("locale_dependencies") if isinstance(item, dict)
+        ),
+        locale_consumer_bindings=tuple(
+            dict(item) for item in _read_tuple("locale_consumer_bindings") if isinstance(item, dict)
+        ),
+        locale_profiles=tuple(dict(item) for item in _read_tuple("locale_profiles") if isinstance(item, dict)),
+        locale_overrides=tuple(dict(item) for item in _read_tuple("locale_overrides") if isinstance(item, dict)),
+        locale_allowlist=_read_locale_allowlist("locale_allowlist"),
+    )
+
+
+def _coerce_protocol_registration_spec(payload: Any, *, owner_hint: str) -> ProtocolRegistrationSpec | None:
+    raw_kind = _payload_field(payload, "kind", default="protocol.registration")
+    if str(raw_kind or "").strip() != "protocol.registration":
+        return None
+    protocol_kind = _payload_field(payload, "protocol_kind")
+    spec_name = _payload_field(payload, "spec_name")
+    runtime_owner = _payload_field(payload, "runtime_owner")
+    raw_id = _payload_field(payload, "id")
+    raw_owner = _payload_field(payload, "owner_app", default=owner_hint)
+    if not isinstance(raw_id, str) or not raw_id.strip():
+        return None
+    if not isinstance(raw_owner, str) or not raw_owner.strip():
+        return None
+    if not isinstance(protocol_kind, str) or not protocol_kind.strip():
+        return None
+    if not isinstance(spec_name, str) or not spec_name.strip():
+        return None
+    if not isinstance(runtime_owner, str) or not runtime_owner.strip():
+        return None
+    return ProtocolRegistrationSpec(
+        id=raw_id,
+        owner_app=raw_owner,
+        protocol_kind=protocol_kind.strip(),
+        spec_name=spec_name.strip(),
+        runtime_owner=runtime_owner.strip(),
+        required_fields=tuple(_payload_field(payload, "required_fields", default=()) or ()),
+        string_fields=tuple(_payload_field(payload, "string_fields", default=()) or ()),
+        import_fields=tuple(_payload_field(payload, "import_fields", default=()) or ()),
+        callable_fields=tuple(_payload_field(payload, "callable_fields", default=()) or ()),
+        validator=_payload_field(payload, "validator", default=None),
+        kind="protocol.registration",
+        api_version=str(_payload_field(payload, "api_version", default="v1") or "v1"),
+        priority=int(_payload_field(payload, "priority", default=100) or 100),
+        title=str(_payload_field(payload, "title", default="") or ""),
+    )
+
+
+def _coerce_protocol_extension_spec(payload: Any, *, owner_hint: str) -> ProtocolExtensionSpec | None:
+    raw_kind = _payload_field(payload, "kind")
+    if not isinstance(raw_kind, str) or not raw_kind.strip():
+        return None
+    if raw_kind.strip() in {
+        "host.builder",
+        "settings.provider",
+        "infra.provider",
+        "runtime.manifest_contribution",
+        "lifecycle.contribution",
+        "worker.role",
+        "cli.tool",
+        "page.profile_provider",
+        "resource.contribution",
+        "protocol.registration",
+    }:
+        return None
+    raw_id = _payload_field(payload, "id")
+    raw_owner = _payload_field(payload, "owner_app", default=owner_hint)
+    fields = _payload_field(payload, "fields", default=None)
+    if not isinstance(raw_id, str) or not raw_id.strip():
+        return None
+    if not isinstance(raw_owner, str) or not raw_owner.strip():
+        return None
+    if not isinstance(fields, Mapping):
+        return None
+    return ProtocolExtensionSpec(
+        id=raw_id,
+        owner_app=raw_owner,
+        kind=raw_kind.strip(),
+        fields={str(key): value for key, value in dict(fields).items()},
+        optional=bool(_payload_field(payload, "optional", default=False)),
+        api_version=str(_payload_field(payload, "api_version", default="v1") or "v1"),
+        priority=int(_payload_field(payload, "priority", default=100) or 100),
+        title=str(_payload_field(payload, "title", default="") or ""),
+    )
+
+
+def _normalize_decl(payload: Any, *, owner_hint: str) -> FormalExtensionSpec:
+    if isinstance(payload, HostBuilderSpec):
+        return payload
+    if isinstance(payload, SettingsProviderSpec):
+        return payload
+    if isinstance(payload, InfraProviderSpec):
+        return payload
+    if isinstance(payload, RuntimeManifestContributionSpec):
+        return payload
+    if isinstance(payload, LifecycleContributionSpec):
+        return payload
+    if isinstance(payload, WorkerRoleSpec):
+        return payload
+    if isinstance(payload, CliToolSpec):
+        return payload
+    if isinstance(payload, PageProfileProviderSpec):
+        return _validate_page_profile_provider_spec(payload)
+    if isinstance(payload, ProtocolRegistrationSpec):
+        return payload
+    if isinstance(payload, ProtocolExtensionSpec):
+        return payload
+    if isinstance(payload, ExtensionSpec):
+        if payload.kind in {
+            "host.builder",
+            "settings.provider",
+            "infra.provider",
+            "runtime.manifest_contribution",
+            "lifecycle.contribution",
+            "worker.role",
+            "cli.tool",
+            "page.profile_provider",
+            "protocol.registration",
+        }:
+            raise PzError(
+                code="PZ_EXTENSION_DECL_INVALID",
+                message=(
+                    f"App '{owner_hint}' must declare '{payload.kind}' via the dedicated formal spec "
+                    "instead of generic ExtensionSpec."
+                ),
+                stage="extensions",
+                owner=owner_hint,
+                action="compile_extension_registry",
+            )
+        return payload
+    shaped_host_builder = _coerce_host_builder_spec(payload, owner_hint=owner_hint)
+    if shaped_host_builder is not None:
+        return shaped_host_builder
+    shaped_settings_provider = _coerce_settings_provider_spec(payload, owner_hint=owner_hint)
+    if shaped_settings_provider is not None:
+        return shaped_settings_provider
+    shaped_infra_provider = _coerce_infra_provider_spec(payload, owner_hint=owner_hint)
+    if shaped_infra_provider is not None:
+        return shaped_infra_provider
+    shaped_runtime_manifest_contribution = _coerce_runtime_manifest_contribution_spec(
+        payload,
+        owner_hint=owner_hint,
+    )
+    if shaped_runtime_manifest_contribution is not None:
+        return shaped_runtime_manifest_contribution
+    shaped_lifecycle_contribution = _coerce_lifecycle_contribution_spec(payload, owner_hint=owner_hint)
+    if shaped_lifecycle_contribution is not None:
+        return shaped_lifecycle_contribution
+    shaped_worker_role = _coerce_worker_role_spec(payload, owner_hint=owner_hint)
+    if shaped_worker_role is not None:
+        return shaped_worker_role
+    shaped_cli_tool = _coerce_cli_tool_spec(payload, owner_hint=owner_hint)
+    if shaped_cli_tool is not None:
+        return shaped_cli_tool
+    shaped_page_profile_provider = _coerce_page_profile_provider_spec(payload, owner_hint=owner_hint)
+    if shaped_page_profile_provider is not None:
+        return _validate_page_profile_provider_spec(shaped_page_profile_provider)
+    shaped_resource_contribution = _coerce_resource_contribution_spec(payload, owner_hint=owner_hint)
+    if shaped_resource_contribution is not None:
+        return shaped_resource_contribution
+    shaped_protocol_registration = _coerce_protocol_registration_spec(payload, owner_hint=owner_hint)
+    if shaped_protocol_registration is not None:
+        return shaped_protocol_registration
+    shaped_protocol_extension = _coerce_protocol_extension_spec(payload, owner_hint=owner_hint)
+    if shaped_protocol_extension is not None:
+        return shaped_protocol_extension
+    shaped_extension = _coerce_extension_spec(payload, owner_hint=owner_hint)
+    if shaped_extension is not None:
+        if shaped_extension.kind in {
+            "host.builder",
+            "settings.provider",
+            "infra.provider",
+            "runtime.manifest_contribution",
+            "lifecycle.contribution",
+            "worker.role",
+            "cli.tool",
+            "page.profile_provider",
+            "resource.contribution",
+            "protocol.registration",
+        }:
+            raise PzError(
+                code="PZ_EXTENSION_DECL_INVALID",
+                message=(
+                    f"App '{owner_hint}' must declare '{shaped_extension.kind}' via the dedicated formal spec "
+                    "instead of generic ExtensionSpec."
+                ),
+                stage="extensions",
+                owner=owner_hint,
+                action="compile_extension_registry",
+            )
+        return shaped_extension
+    raise PzError(
+        code="PZ_EXTENSION_DECL_INVALID",
+        message=(
+            f"Extension declaration from '{owner_hint}' must be a formal protocol object "
+            "ExtensionSpec, HostBuilderSpec, SettingsProviderSpec, InfraProviderSpec, "
+            "RuntimeManifestContributionSpec, LifecycleContributionSpec, WorkerRoleSpec, "
+            "CliToolSpec, PageProfileProviderSpec, "
+            "ResourceContributionSpec, "
+            "ProtocolRegistrationSpec, or ProtocolExtensionSpec."
+        ),
+        stage="extensions",
+        owner=owner_hint,
+        action="compile_extension_registry",
+    )
+
+
+def _load_app_declared_extensions(app_registry: AppRegistry) -> tuple[FormalExtensionSpec, ...]:
+    out: list[FormalExtensionSpec] = []
+    for app in app_registry.apps:
+        app_obj = load_app_object_from_decl(app)
+        normalized: list[FormalExtensionSpec] = []
+        extensions_factory = getattr(app_obj, "extensions", None)
+        if extensions_factory is None:
+            declared = ()
+        else:
+            if not callable(extensions_factory):
+                raise PzError(
+                    code="PZ_APP_EXTENSIONS_INVALID",
+                    message=f"App '{app.app_id}' exposes non-callable extensions().",
+                    stage="extensions",
+                    owner=app.app_id,
+                    action="compile_extension_registry",
+                )
+            declared = extensions_factory()
+            if declared not in (None, (), []):
+                if not isinstance(declared, (list, tuple)):
+                    raise PzError(
+                        code="PZ_APP_EXTENSIONS_INVALID",
+                        message=f"App '{app.app_id}' extensions() must return a list or tuple.",
+                        stage="extensions",
+                        owner=app.app_id,
+                        action="compile_extension_registry",
+                    )
+                normalized.extend(_normalize_decl(payload, owner_hint=app.app_id) for payload in declared)
+        normalized.extend(
+            _synthesized_lifecycle_contributions(
+                app,
+                app_obj,
+                declared=tuple(normalized),
+            )
+        )
+        out.extend(normalized)
+    return tuple(out)
+
+
+def compile_extension_registry(
+    settings: SettingsSnapshot,
+    app_registry: AppRegistry,
+) -> ExtensionRegistry:
+    project_dir = getattr(settings, "project_dir", None)
+    import_roots = getattr(settings, "import_roots", ())
+    with active_project_import_root(
+        project_dir,
+        extra_import_roots=import_roots,
+    ):
+        registry = ExtensionRegistry(extensions=_load_app_declared_extensions(app_registry))
+    registry.validate()
+    return registry
+
+
+__all__ = ["compile_extension_registry"]