pz-cli 5.0.0__py3-none-any.whl

pz_core/core/extensions/registry.py

@@ -0,0 +1,790 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from importlib import import_module
+import inspect
+from typing import Any, TypeAlias
+
+from pz_core.core.errors import PzError
+
+WORKER_ROLE_KINDS = frozenset(
+    {
+        "infrastructure_worker",
+        "operator_ingress_worker",
+        "resident_actor_worker",
+        "task_driven_actor_worker",
+    }
+)
+
+
+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_extension_target(target: Any) -> Any:
+    if isinstance(target, str):
+        target = _resolve_dotted(target)
+    if inspect.isclass(target):
+        return target()
+    return target
+
+
+@dataclass(frozen=True, slots=True)
+class ExtensionSpec:
+    id: str
+    kind: str
+    owner_app: str
+    api_version: str = "v1"
+    priority: int = 100
+    title: str = ""
+    payload: dict[str, Any] = field(default_factory=dict)
+    source: str = ""
+    provides: tuple[str, ...] = ()
+    conflicts: tuple[str, ...] = ()
+
+
+def _is_declarative_payload_value(value: Any) -> bool:
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return True
+    if isinstance(value, (list, tuple)):
+        return all(_is_declarative_payload_value(item) for item in value)
+    if isinstance(value, dict):
+        return all(
+            isinstance(key, str) and _is_declarative_payload_value(item)
+            for key, item in value.items()
+        )
+    return False
+
+
+@dataclass(frozen=True, slots=True)
+class HostBuildContext:
+    project: Any
+    plan: Any
+    settings: Any
+    bindings: Any
+    lifecycle_state: Any | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class HostBuildResult:
+    app: Any
+    app_kind: str = "asgi"
+    health_path: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class HostBuilderSpec:
+    id: str
+    owner_app: str
+    builder: Any
+    kind: str = "host.builder"
+    runtime_kind: str = "web"
+    api_version: str = "v1"
+    priority: int = 100
+    title: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class SettingsPatch:
+    app_id: str
+    payload: dict[str, Any]
+    source: str
+    priority: int = 100
+
+
+@dataclass(frozen=True, slots=True)
+class SettingsProviderContext:
+    project: Any
+    snapshot: Any
+    settings: Any
+
+
+@dataclass(frozen=True, slots=True)
+class SettingsProviderSpec:
+    id: str
+    owner_app: str
+    provider: Any
+    kind: str = "settings.provider"
+    api_version: str = "v1"
+    priority: int = 100
+
+
+@dataclass(frozen=True, slots=True)
+class InfraPatch:
+    component: str
+    payload: dict[str, Any]
+    source: str
+    priority: int = 100
+
+
+@dataclass(frozen=True, slots=True)
+class InfraProviderContext:
+    project: Any
+    snapshot: Any
+
+
+@dataclass(frozen=True, slots=True)
+class InfraProviderSpec:
+    id: str
+    owner_app: str
+    provider: Any
+    kind: str = "infra.provider"
+    api_version: str = "v1"
+    priority: int = 100
+    title: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeManifestContributionSpec:
+    id: str
+    owner_app: str
+    provider: Any
+    kind: str = "runtime.manifest_contribution"
+    api_version: str = "v1"
+    priority: int = 100
+    title: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class LifecycleContributionSpec:
+    id: str
+    owner_app: str
+    handler: Any
+    phase: str
+    kind: str = "lifecycle.contribution"
+    api_version: str = "v1"
+    priority: int = 100
+
+
+@dataclass(frozen=True, slots=True)
+class WorkerRoleSpec:
+    id: str
+    owner_app: str
+    tool_name: str
+    kind: str = "worker.role"
+    api_version: str = "v1"
+    priority: int = 100
+    title: str = ""
+    name: str = ""
+    auto_start: bool = False
+    auto_start_setting: str = ""
+    restart: str = "always"
+    worker_kind: str = "infrastructure_worker"
+    replica_count_setting: str = ""
+    description: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class CliInvocationContext:
+    project: Any
+    args: Any
+    stdout: Any
+    stderr: Any
+    plan: Any | None = None
+    app_id: str = ""
+    tool_name: str = ""
+    argv: tuple[str, ...] = ()
+    remainder: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class CliToolSpec:
+    id: str
+    owner_app: str
+    command: tuple[str, ...]
+    summary: str
+    tool: Any
+    kind: str = "cli.tool"
+    api_version: str = "v1"
+    priority: int = 100
+    title: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class PageProfileProviderSpec:
+    id: str
+    owner_app: str
+    provider: Any
+    kind: str = "page.profile_provider"
+    api_version: str = "v1"
+    priority: int = 100
+    title: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class ResourceContributionSpec:
+    id: str
+    owner_app: str
+    templates_dir: str = "templates"
+    static_dir: str = "static"
+    locales_dir: str = "locales"
+    migrations_dir: str = "migrations"
+    kind: str = "resource.contribution"
+    api_version: str = "v1"
+    priority: int = 100
+    title: str = ""
+    locale_bundles: tuple[dict[str, Any], ...] = ()
+    locale_dependencies: tuple[dict[str, Any], ...] = ()
+    locale_consumer_bindings: tuple[dict[str, Any], ...] = ()
+    locale_profiles: tuple[dict[str, Any], ...] = ()
+    locale_overrides: tuple[dict[str, Any], ...] = ()
+    locale_allowlist: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class ProtocolRegistrationSpec:
+    id: str
+    owner_app: str
+    protocol_kind: str
+    spec_name: str
+    runtime_owner: str
+    required_fields: tuple[str, ...] = ()
+    string_fields: tuple[str, ...] = ()
+    import_fields: tuple[str, ...] = ()
+    callable_fields: tuple[str, ...] = ()
+    validator: Any | None = None
+    kind: str = "protocol.registration"
+    api_version: str = "v1"
+    priority: int = 100
+    title: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class ProtocolExtensionSpec:
+    id: str
+    owner_app: str
+    kind: str
+    fields: dict[str, Any] = field(default_factory=dict)
+    optional: bool = False
+    api_version: str = "v1"
+    priority: int = 100
+    title: str = ""
+
+
+FormalExtensionSpec: TypeAlias = (
+    ExtensionSpec
+    | HostBuilderSpec
+    | SettingsProviderSpec
+    | InfraProviderSpec
+    | RuntimeManifestContributionSpec
+    | LifecycleContributionSpec
+    | WorkerRoleSpec
+    | CliToolSpec
+    | PageProfileProviderSpec
+    | ResourceContributionSpec
+    | ProtocolRegistrationSpec
+    | ProtocolExtensionSpec
+)
+
+
+@dataclass(frozen=True, slots=True)
+class ExtensionRegistry:
+    extensions: tuple[FormalExtensionSpec, ...] = ()
+
+    def by_id(self) -> dict[str, FormalExtensionSpec]:
+        return {str(extension.id): extension for extension in self.extensions}
+
+    def by_kind(self, kind: str) -> tuple[FormalExtensionSpec, ...]:
+        expected = str(kind or "").strip()
+        if not expected:
+            return ()
+        return tuple(extension for extension in self.extensions if extension.kind == expected)
+
+    def validate(self) -> None:
+        registered_protocols: dict[str, ProtocolRegistrationSpec] = {}
+        protocol_extensions: list[ProtocolExtensionSpec] = []
+        ids: list[str] = []
+        for extension in self.extensions:
+            raw_id = getattr(extension, "id", None)
+            if not isinstance(raw_id, str) or not raw_id.strip():
+                raise PzError(
+                    code="PZ_EXTENSION_ID_INVALID",
+                    message="Extension id must be a non-empty string.",
+                    stage="extensions",
+                    owner="core.extensions",
+                    action="validate",
+                )
+            raw_owner = getattr(extension, "owner_app", None)
+            if not isinstance(raw_owner, str) or not raw_owner.strip():
+                raise PzError(
+                    code="PZ_EXTENSION_OWNER_INVALID",
+                    message=f"Extension '{raw_id}' must declare owner_app as a non-empty string.",
+                    stage="extensions",
+                    owner=str(raw_id),
+                    action="validate",
+                )
+            raw_kind = getattr(extension, "kind", None)
+            if not isinstance(raw_kind, str) or not raw_kind.strip():
+                raise PzError(
+                    code="PZ_EXTENSION_KIND_INVALID",
+                    message=f"Extension '{raw_id}' must declare kind as a non-empty string.",
+                    stage="extensions",
+                    owner=str(raw_owner),
+                    action="validate",
+                )
+            provides = getattr(extension, "provides", ())
+            if provides not in (None, ()) and not isinstance(provides, tuple):
+                raise PzError(
+                    code="PZ_EXTENSION_PROVIDES_INVALID",
+                    message=f"Extension '{raw_id}' must declare provides as a tuple of non-empty strings.",
+                    stage="extensions",
+                    owner=str(raw_owner),
+                    action="validate",
+                )
+            for item in tuple(provides or ()):
+                if not isinstance(item, str) or not item.strip():
+                    raise PzError(
+                        code="PZ_EXTENSION_PROVIDES_ITEM_INVALID",
+                        message=f"Extension '{raw_id}' provides contains an invalid item.",
+                        stage="extensions",
+                        owner=str(raw_owner),
+                        action="validate",
+                    )
+            if isinstance(extension, WorkerRoleSpec):
+                if not isinstance(extension.tool_name, str) or not extension.tool_name.strip():
+                    raise PzError(
+                        code="PZ_WORKER_ROLE_TOOL_INVALID",
+                        message=f"Worker role '{raw_id}' must declare tool_name as a non-empty string.",
+                        stage="extensions",
+                        owner=str(raw_owner),
+                        action="validate",
+                    )
+                if extension.restart not in {"always", "never"}:
+                    raise PzError(
+                        code="PZ_WORKER_ROLE_RESTART_INVALID",
+                        message=f"Worker role '{raw_id}' restart must be `always` or `never`.",
+                        stage="extensions",
+                        owner=str(raw_owner),
+                        action="validate",
+                    )
+                if (
+                    not isinstance(extension.worker_kind, str)
+                    or extension.worker_kind not in WORKER_ROLE_KINDS
+                ):
+                    raise PzError(
+                        code="PZ_WORKER_ROLE_KIND_INVALID",
+                        message=(
+                            f"Worker role '{raw_id}' worker_kind must be one of: "
+                            f"{', '.join(sorted(WORKER_ROLE_KINDS))}."
+                        ),
+                        stage="extensions",
+                        owner=str(raw_owner),
+                        action="validate",
+                    )
+                if (
+                    extension.auto_start_setting
+                    and (
+                        not isinstance(extension.auto_start_setting, str)
+                        or not extension.auto_start_setting.strip()
+                    )
+                ):
+                    raise PzError(
+                        code="PZ_WORKER_ROLE_AUTO_START_SETTING_INVALID",
+                        message=(
+                            f"Worker role '{raw_id}' auto_start_setting must be empty or "
+                            "a non-empty string."
+                        ),
+                        stage="extensions",
+                        owner=str(raw_owner),
+                        action="validate",
+                    )
+                if (
+                    extension.replica_count_setting
+                    and (
+                        not isinstance(extension.replica_count_setting, str)
+                        or not extension.replica_count_setting.strip()
+                    )
+                ):
+                    raise PzError(
+                        code="PZ_WORKER_ROLE_REPLICA_COUNT_SETTING_INVALID",
+                        message=(
+                            f"Worker role '{raw_id}' replica_count_setting must be empty or "
+                            "a non-empty string."
+                        ),
+                        stage="extensions",
+                        owner=str(raw_owner),
+                        action="validate",
+                    )
+            if isinstance(extension, ExtensionSpec):
+                payload = extension.payload
+                if not isinstance(payload, dict):
+                    raise PzError(
+                        code="PZ_EXTENSION_PAYLOAD_INVALID",
+                        message=f"Extension '{raw_id}' payload must be a dict.",
+                        stage="extensions",
+                        owner=str(raw_owner),
+                        action="validate",
+                        )
+                if not _is_declarative_payload_value(payload):
+                    raise PzError(
+                        code="PZ_EXTENSION_PAYLOAD_NOT_DECLARATIVE",
+                        message=(
+                            f"Extension '{raw_id}' payload must be declarative data only. "
+                            "Use import strings for runtime objects such as routers, providers, "
+                            "handlers, or factories."
+                        ),
+                        stage="extensions",
+                        owner=str(raw_owner),
+                        action="validate",
+                        )
+            if isinstance(extension, RuntimeManifestContributionSpec):
+                if str(extension.kind or "").strip() != "runtime.manifest_contribution":
+                    raise PzError(
+                        code="PZ_RUNTIME_MANIFEST_CONTRIBUTION_KIND_INVALID",
+                        message=f"Runtime manifest contribution '{raw_id}' kind must be `runtime.manifest_contribution`.",
+                        stage="extensions",
+                        owner=str(raw_owner),
+                        action="validate",
+                    )
+                provider = extension.provider
+                if provider is None:
+                    raise PzError(
+                        code="PZ_RUNTIME_MANIFEST_CONTRIBUTION_PROVIDER_INVALID",
+                        message=f"Runtime manifest contribution '{raw_id}' must declare a provider.",
+                        stage="extensions",
+                        owner=str(raw_owner),
+                        action="validate",
+                    )
+                if isinstance(provider, str) and not provider.strip():
+                    raise PzError(
+                        code="PZ_RUNTIME_MANIFEST_CONTRIBUTION_PROVIDER_INVALID",
+                        message=(
+                            f"Runtime manifest contribution '{raw_id}' must declare provider as "
+                            "a non-empty string."
+                        ),
+                        stage="extensions",
+                        owner=str(raw_owner),
+                        action="validate",
+                    )
+            if isinstance(extension, CliToolSpec):
+                if str(extension.kind or "").strip() != "cli.tool":
+                    raise PzError(
+                        code="PZ_CLI_TOOL_KIND_INVALID",
+                        message=f"CLI tool '{raw_id}' kind must be `cli.tool`.",
+                        stage="extensions",
+                        owner=str(raw_owner),
+                        action="validate",
+                    )
+                if not isinstance(extension.command, tuple) or not extension.command:
+                    raise PzError(
+                        code="PZ_CLI_TOOL_COMMAND_INVALID",
+                        message=f"CLI tool '{raw_id}' must declare command as a non-empty tuple.",
+                        stage="extensions",
+                        owner=str(raw_owner),
+                        action="validate",
+                    )
+                for part in extension.command:
+                    if not isinstance(part, str) or not part.strip():
+                        raise PzError(
+                            code="PZ_CLI_TOOL_COMMAND_INVALID",
+                            message=f"CLI tool '{raw_id}' command contains an invalid segment.",
+                            stage="extensions",
+                            owner=str(raw_owner),
+                            action="validate",
+                        )
+                tool = extension.tool
+                if not callable(getattr(tool, "configure", None)) or not callable(getattr(tool, "run", None)):
+                    raise PzError(
+                        code="PZ_CLI_TOOL_OBJECT_INVALID",
+                        message=f"CLI tool '{raw_id}' must expose configure(parser) and run(ctx).",
+                        stage="extensions",
+                        owner=str(raw_owner),
+                        action="validate",
+                    )
+            if isinstance(extension, PageProfileProviderSpec):
+                provider = extension.provider
+                if provider is None:
+                    raise PzError(
+                        code="PZ_PAGE_PROFILE_PROVIDER_INVALID",
+                        message=f"Page-profile provider '{raw_id}' must declare a provider.",
+                        stage="extensions",
+                        owner=str(raw_owner),
+                        action="validate",
+                    )
+                if isinstance(provider, str) and not provider.strip():
+                    raise PzError(
+                        code="PZ_PAGE_PROFILE_PROVIDER_INVALID",
+                        message=f"Page-profile provider '{raw_id}' must declare provider as a non-empty string.",
+                        stage="extensions",
+                        owner=str(raw_owner),
+                        action="validate",
+                    )
+            if isinstance(extension, ResourceContributionSpec):
+                if str(extension.kind or "").strip() != "resource.contribution":
+                    raise PzError(
+                        code="PZ_RESOURCE_CONTRIBUTION_KIND_INVALID",
+                        message=f"Resource contribution '{raw_id}' kind must be `resource.contribution`.",
+                        stage="extensions",
+                        owner=str(raw_owner),
+                        action="validate",
+                    )
+                for field_name in ("templates_dir", "static_dir", "locales_dir", "migrations_dir"):
+                    value = getattr(extension, field_name)
+                    if not isinstance(value, str) or not value.strip():
+                        raise PzError(
+                            code="PZ_RESOURCE_CONTRIBUTION_FIELD_INVALID",
+                            message=(
+                                f"Resource contribution '{raw_id}' field '{field_name}' "
+                                "must be a non-empty string."
+                            ),
+                            stage="extensions",
+                            owner=str(raw_owner),
+                            action="validate",
+                        )
+                for attr_name in (
+                    "locale_bundles",
+                    "locale_dependencies",
+                    "locale_consumer_bindings",
+                    "locale_profiles",
+                    "locale_overrides",
+                ):
+                    value = getattr(extension, attr_name)
+                    if value not in (None, ()) and not isinstance(value, tuple):
+                        raise PzError(
+                            code="PZ_RESOURCE_CONTRIBUTION_FIELD_INVALID",
+                            message=(
+                                f"Resource contribution '{raw_id}' field '{attr_name}' must be a tuple."
+                            ),
+                            stage="extensions",
+                            owner=str(raw_owner),
+                            action="validate",
+                        )
+                if extension.locale_allowlist not in (None, ()) and not isinstance(extension.locale_allowlist, tuple):
+                    raise PzError(
+                        code="PZ_RESOURCE_CONTRIBUTION_FIELD_INVALID",
+                        message=(
+                            f"Resource contribution '{raw_id}' field 'locale_allowlist' must be a tuple."
+                        ),
+                        stage="extensions",
+                        owner=str(raw_owner),
+                        action="validate",
+                    )
+                for item in tuple(extension.locale_allowlist or ()):
+                    if not isinstance(item, str) or not item.strip():
+                        raise PzError(
+                            code="PZ_RESOURCE_CONTRIBUTION_FIELD_INVALID",
+                            message=(
+                                f"Resource contribution '{raw_id}' field 'locale_allowlist' contains an invalid item."
+                            ),
+                            stage="extensions",
+                            owner=str(raw_owner),
+                            action="validate",
+                        )
+            if isinstance(extension, ProtocolRegistrationSpec):
+                if str(extension.kind or "").strip() != "protocol.registration":
+                    raise PzError(
+                        code="PZ_PROTOCOL_REGISTRATION_KIND_INVALID",
+                        message=f"Protocol registration '{raw_id}' kind must be `protocol.registration`.",
+                        stage="extensions",
+                        owner=str(raw_owner),
+                        action="validate",
+                    )
+                protocol_kind = str(extension.protocol_kind or "").strip()
+                if not protocol_kind:
+                    raise PzError(
+                        code="PZ_PROTOCOL_KIND_INVALID",
+                        message=f"Protocol registration '{raw_id}' must declare protocol_kind.",
+                        stage="extensions",
+                        owner=str(raw_owner),
+                        action="validate",
+                    )
+                if protocol_kind in registered_protocols:
+                    raise PzError(
+                        code="PZ_PROTOCOL_KIND_DUPLICATE",
+                        message=f"Protocol kind '{protocol_kind}' is registered more than once.",
+                        stage="extensions",
+                        owner=str(raw_owner),
+                        action="validate",
+                    )
+                if not isinstance(extension.spec_name, str) or not extension.spec_name.strip():
+                    raise PzError(
+                        code="PZ_PROTOCOL_SPEC_NAME_INVALID",
+                        message=f"Protocol registration '{raw_id}' must declare spec_name.",
+                        stage="extensions",
+                        owner=str(raw_owner),
+                        action="validate",
+                    )
+                if not isinstance(extension.runtime_owner, str) or not extension.runtime_owner.strip():
+                    raise PzError(
+                        code="PZ_PROTOCOL_RUNTIME_OWNER_INVALID",
+                        message=f"Protocol registration '{raw_id}' must declare runtime_owner.",
+                        stage="extensions",
+                        owner=str(raw_owner),
+                        action="validate",
+                    )
+                for attr_name, code in (
+                    ("required_fields", "PZ_PROTOCOL_REQUIRED_FIELDS_INVALID"),
+                    ("string_fields", "PZ_PROTOCOL_STRING_FIELDS_INVALID"),
+                    ("import_fields", "PZ_PROTOCOL_IMPORT_FIELDS_INVALID"),
+                    ("callable_fields", "PZ_PROTOCOL_CALLABLE_FIELDS_INVALID"),
+                ):
+                    value = getattr(extension, attr_name, ())
+                    if value not in (None, ()) and not isinstance(value, tuple):
+                        raise PzError(
+                            code=code,
+                            message=f"Protocol registration '{raw_id}' must declare {attr_name} as a tuple.",
+                            stage="extensions",
+                            owner=str(raw_owner),
+                            action="validate",
+                        )
+                    for item in tuple(value or ()):
+                        if not isinstance(item, str) or not item.strip():
+                            raise PzError(
+                                code=code,
+                                message=f"Protocol registration '{raw_id}' contains an invalid {attr_name} item.",
+                                stage="extensions",
+                                owner=str(raw_owner),
+                                action="validate",
+                            )
+                validator = extension.validator
+                if validator is not None and not (
+                    callable(validator) or (isinstance(validator, str) and validator.strip())
+                ):
+                    raise PzError(
+                        code="PZ_PROTOCOL_VALIDATOR_INVALID",
+                        message=f"Protocol registration '{raw_id}' validator must be callable or a non-empty string.",
+                        stage="extensions",
+                        owner=str(raw_owner),
+                        action="validate",
+                    )
+                registered_protocols[protocol_kind] = extension
+            if isinstance(extension, ProtocolExtensionSpec):
+                protocol_extensions.append(extension)
+            ids.append(raw_id)
+        if len(ids) != len(set(ids)):
+            raise PzError(
+                code="PZ_EXTENSION_DUPLICATE_ID",
+                message="ExtensionRegistry contains duplicate extension ids.",
+                stage="extensions",
+                owner="core.extensions",
+                action="validate",
+            )
+
+        for extension in self.extensions:
+            if isinstance(extension, ExtensionSpec) and extension.kind in registered_protocols:
+                raise PzError(
+                    code="PZ_PROTOCOL_EXTENSION_SPEC_REQUIRED",
+                    message=(
+                        f"Extension '{extension.id}' kind '{extension.kind}' is a registered protocol and "
+                        "must use ProtocolExtensionSpec."
+                    ),
+                    stage="extensions",
+                    owner=extension.owner_app,
+                    action="validate",
+                )
+
+        for extension in protocol_extensions:
+            raw_id = str(extension.id or "").strip()
+            raw_owner = str(extension.owner_app or "").strip()
+            protocol = registered_protocols.get(str(extension.kind or "").strip())
+            if protocol is None:
+                if extension.optional:
+                    continue
+                raise PzError(
+                    code="PZ_PROTOCOL_EXTENSION_UNREGISTERED",
+                    message=f"Protocol extension '{raw_id}' declares unknown kind '{extension.kind}'.",
+                    stage="extensions",
+                    owner=str(raw_owner),
+                    action="validate",
+                )
+            if not isinstance(extension.fields, dict):
+                raise PzError(
+                    code="PZ_PROTOCOL_FIELDS_INVALID",
+                    message=f"Protocol extension '{raw_id}' must declare fields as a dict.",
+                    stage="extensions",
+                    owner=str(raw_owner),
+                    action="validate",
+                )
+            for field_name in protocol.required_fields:
+                if field_name not in extension.fields:
+                    raise PzError(
+                        code="PZ_PROTOCOL_REQUIRED_FIELD_MISSING",
+                        message=f"Protocol extension '{raw_id}' is missing required field '{field_name}'.",
+                        stage="extensions",
+                        owner=str(raw_owner),
+                        action="validate",
+                    )
+
+            for field_name in protocol.string_fields:
+                value = extension.fields.get(field_name)
+                if not isinstance(value, str) or not value.strip():
+                    raise PzError(
+                        code="PZ_PROTOCOL_STRING_FIELD_INVALID",
+                        message=f"Protocol extension '{raw_id}' field '{field_name}' must be a non-empty string.",
+                        stage="extensions",
+                        owner=str(raw_owner),
+                        action="validate",
+                    )
+            validator = protocol.validator
+            if validator is not None:
+                validator_callable = _instantiate_extension_target(validator)
+                if not callable(validator_callable):
+                    raise PzError(
+                        code="PZ_PROTOCOL_VALIDATOR_INVALID",
+                        message=f"Protocol registration '{protocol.id}' validator must resolve to callable.",
+                        stage="extensions",
+                        owner=str(raw_owner),
+                        action="validate",
+                    )
+                validator_callable(extension)
+            for field_name in protocol.import_fields:
+                value = extension.fields.get(field_name)
+                if not isinstance(value, str) or not value.strip():
+                    raise PzError(
+                        code="PZ_PROTOCOL_IMPORT_FIELD_INVALID",
+                        message=f"Protocol extension '{raw_id}' field '{field_name}' must be a non-empty import string.",
+                        stage="extensions",
+                        owner=str(raw_owner),
+                        action="validate",
+                    )
+                try:
+                    _instantiate_extension_target(value)
+                except Exception as exc:
+                    raise PzError(
+                        code="PZ_PROTOCOL_IMPORT_RESOLVE_FAILED",
+                        message=(
+                            f"Protocol extension '{raw_id}' field '{field_name}' failed to load during "
+                            f"validation: {exc}"
+                        ),
+                        stage="extensions",
+                        owner=str(raw_owner),
+                        action="validate",
+                    ) from exc
+            for field_name in protocol.callable_fields:
+                value = extension.fields.get(field_name)
+                if value is None:
+                    raise PzError(
+                        code="PZ_PROTOCOL_CALLABLE_FIELD_INVALID",
+                        message=f"Protocol extension '{raw_id}' field '{field_name}' must be callable.",
+                        stage="extensions",
+                        owner=str(raw_owner),
+                        action="validate",
+                    )
+                if not callable(_instantiate_extension_target(value)):
+                    raise PzError(
+                        code="PZ_PROTOCOL_CALLABLE_FIELD_INVALID",
+                        message=f"Protocol extension '{raw_id}' field '{field_name}' must resolve to callable.",
+                        stage="extensions",
+                        owner=str(raw_owner),
+                        action="validate",
+                    )
+
+        installed = self.by_id()
+        for extension in self.extensions:
+            conflicts = tuple(getattr(extension, "conflicts", ()) or ())
+            owner_app = str(getattr(extension, "owner_app", "") or "")
+            extension_id = str(getattr(extension, "id", "") or "")
+            for conflict in conflicts:
+                if conflict in installed:
+                    raise PzError(
+                        code="PZ_EXTENSION_CONFLICT",
+                        message=(
+                            f"Extension '{extension_id}' conflicts with installed "
+                            f"extension '{conflict}'."
+                        ),
+                        stage="extensions",
+                        owner=owner_app or extension_id,
+                        action="validate",
+                    )