python-platform 0.1.1__py3-none-any.whl

python_platform/application_services/catalog.py

@@ -0,0 +1,500 @@
+"""Protocol/implementation mapping、method compilation 与 immutable public catalog。"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass, field, replace
+from types import MappingProxyType
+from typing import Any, cast, get_type_hints
+
+from pydantic import ConfigDict, validate_call
+
+from ..auditing.control import _AUDITING_ATTRIBUTE
+from ..authorization import PermissionCatalog, PermissionName
+from ..authorization.contracts import (
+    _ALLOW_ANONYMOUS_ATTRIBUTE,
+    _AUTHORIZATION_ATTRIBUTE,
+    _authorization_requirement,
+    _AuthorizationRequirement,
+)
+from ..authorization.errors import AuthorizationDefinitionError
+from ..diagnostics import SourceLocation
+from ..modularity import ModuleKey
+from ..unit_of_work.options import _UNIT_OF_WORK_ATTRIBUTE, UnitOfWorkDeclaration, _declaration
+from .contracts import (
+    ApplicationService,
+    ApplicationServiceContract,
+    IntegrationService,
+    _ApplicationServiceDefinition,
+    _inherited_contracts,
+    _is_internal_contributor,
+)
+from .errors import ApplicationServiceDefinitionError, ApplicationServiceMethodError
+from .interceptors import InterceptionStage, InterceptorRegistration, _InterceptorRule
+from .policies import _VALIDATION_ATTRIBUTE, _effective_switch
+from .signature import _business_signature
+
+_APPLICATION_SERVICE_COMPONENT = "__python_platform_application_service_implementation__"
+
+
+@dataclass(frozen=True, slots=True)
+class ApplicationServiceMethod:
+    name: str
+    source: SourceLocation
+    requires_authenticated_user: bool
+    permissions: tuple[PermissionName, ...]
+    allows_anonymous: bool
+    service: type[object]
+    implementation: type[object]
+    method: Callable[..., Awaitable[object]]
+    validation_enabled: bool
+    auditing_enabled: bool
+    policy_sources: tuple[SourceLocation, ...]
+    interceptors: tuple[InterceptorRegistration, ...] = ()
+    unit_of_work: UnitOfWorkDeclaration = field(default_factory=UnitOfWorkDeclaration)
+
+
+@dataclass(frozen=True, slots=True)
+class ApplicationServiceRegistration:
+    contract: type[object]
+    implementation: type[ApplicationService]
+    connection_name: str
+    owner: ModuleKey
+    implementation_owner: ModuleKey
+    source: SourceLocation
+    implementation_source: SourceLocation
+    replaced_sources: tuple[SourceLocation, ...]
+    declaration_index: int
+    methods: tuple[ApplicationServiceMethod, ...]
+    is_public_service: bool
+    has_contract: bool
+    is_integration_service: bool
+
+
+@dataclass(frozen=True, slots=True)
+class _DiscoveredApplicationService:
+    service_type: type[ApplicationService]
+    definition: _ApplicationServiceDefinition
+    owner: ModuleKey
+    source: SourceLocation
+    declaration_index: int
+
+
+@dataclass(frozen=True, slots=True)
+class _ApplicationServiceBinding:
+    discovery: _DiscoveredApplicationService
+    implementation: type[ApplicationService]
+    implementation_owner: ModuleKey
+    implementation_source: SourceLocation
+    replaced_sources: tuple[SourceLocation, ...]
+
+
+_ValidatedArguments = tuple[tuple[object, ...], dict[str, object]]
+
+
+@dataclass(frozen=True, slots=True)
+class _CompiledMethod:
+    name: str
+    contract_method: Callable[..., Awaitable[object]]
+    implementation_method: Callable[..., Awaitable[object]]
+    validator: Callable[..., Awaitable[_ValidatedArguments]]
+    parameter_names: frozenset[str]
+    authorization: _AuthorizationRequirement
+    descriptor: ApplicationServiceMethod
+    signature: inspect.Signature
+    interceptor_steps: Mapping[InterceptionStage, tuple[InterceptorRegistration, ...]]
+
+
+@dataclass(frozen=True, slots=True)
+class _CompiledApplicationService:
+    registration: ApplicationServiceRegistration
+    methods: Mapping[str, _CompiledMethod]
+
+
+class ApplicationServiceCatalog:
+    """唯一发布 contract、最终 implementation、owner、method 与 override provenance。"""
+
+    __slots__ = ("_by_contract", "_by_method", "_compiled", "_registrations")
+
+    def __init__(self, services: tuple[_CompiledApplicationService, ...]) -> None:
+        self._compiled = services
+        self._registrations = tuple(item.registration for item in services)
+        public_services = tuple(item for item in services if item.registration.is_public_service)
+        self._by_contract: Mapping[type[object], _CompiledApplicationService] = MappingProxyType(
+            {item.registration.contract: item for item in public_services}
+        )
+        methods_by_identity: dict[
+            object,
+            tuple[_CompiledApplicationService, _CompiledMethod],
+        ] = {}
+        for service in public_services:
+            for method in service.methods.values():
+                previous = methods_by_identity.get(method.contract_method)
+                if previous is not None:
+                    # method-only invoke 不能靠遍历顺序裁决继承或复用造成的 identity 歧义。
+                    contract = service.registration.contract
+                    raise ApplicationServiceDefinitionError(
+                        symbol=f"{contract.__module__}.{contract.__qualname__}.{method.name}",
+                        reason="contract method identity must be unique within an Application",
+                    )
+                methods_by_identity[method.contract_method] = (service, method)
+        self._by_method: Mapping[
+            object,
+            tuple[_CompiledApplicationService, _CompiledMethod],
+        ] = MappingProxyType(methods_by_identity)
+
+    @property
+    def registrations(self) -> tuple[ApplicationServiceRegistration, ...]:
+        return self._registrations
+
+    def for_contract(
+        self,
+        contract: type[object],
+    ) -> ApplicationServiceRegistration | None:
+        compiled = self._by_contract.get(contract)
+        return compiled.registration if compiled is not None else None
+
+    def _resolve_method(
+        self,
+        method: object,
+    ) -> tuple[_CompiledApplicationService, _CompiledMethod]:
+        resolved = self._by_method.get(method)
+        if resolved is None:
+            raise ApplicationServiceMethodError(
+                service=ApplicationServiceContract,
+                method=method,
+                reason="method is not a cataloged ApplicationServiceContract method",
+            )
+        return resolved
+
+    def _for_registration(
+        self,
+        registration: ApplicationServiceRegistration,
+    ) -> _CompiledApplicationService:
+        for compiled in self._compiled:
+            if compiled.registration is registration:
+                return compiled
+        raise AssertionError("Application Service registration is not owned by this catalog")
+
+
+def _build_application_service_catalog(
+    bindings: tuple[_ApplicationServiceBinding, ...],
+    permission_catalog: PermissionCatalog,
+    interceptor_rules: tuple[_InterceptorRule, ...] = (),
+) -> ApplicationServiceCatalog:
+    return ApplicationServiceCatalog(
+        tuple(_compile_service(item, permission_catalog, interceptor_rules) for item in bindings)
+    )
+
+
+def _compile_service(
+    binding: _ApplicationServiceBinding,
+    permission_catalog: PermissionCatalog,
+    interceptor_rules: tuple[_InterceptorRule, ...] = (),
+) -> _CompiledApplicationService:
+    """把 contract declaration 与仲裁胜出的 implementation 编译成唯一调用事实。"""
+
+    discovery = binding.discovery
+    implementation = binding.implementation
+    contract: type[object] = discovery.definition.contract or discovery.service_type
+    has_contract = discovery.definition.contract is not None
+    is_public_service = not _is_internal_contributor(implementation)
+    is_integration = issubclass(implementation, IntegrationService)
+    _validate_policy_locations(contract if has_contract else None, implementation, is_integration)
+    if is_integration and not has_contract:
+        raise ApplicationServiceDefinitionError(
+            symbol=implementation.__qualname__,
+            reason="IntegrationService requires an independent Contract",
+        )
+    implementation_symbol = f"{implementation.__module__}.{implementation.__qualname__}"
+    if inspect.isabstract(implementation):
+        raise ApplicationServiceDefinitionError(
+            symbol=implementation_symbol,
+            reason="application service implementation must be concrete",
+        )
+
+    # public surface 以 Protocol 为权威；override 只能替换实现，不能暗中增删业务方法。
+    contract_methods = _public_method_names(contract, is_contract=has_contract)
+
+    compiled_methods: dict[str, _CompiledMethod] = {}
+    public_methods: list[ApplicationServiceMethod] = []
+    for name in contract_methods:
+        contract_method = _require_async_instance_method(contract, name, role="contract")
+        implementation_method = _require_async_instance_method(
+            implementation,
+            name,
+            role="implementation",
+        )
+        contract_signature, annotations = _resolved_signature(contract_method)
+        implementation_signature, _ = _resolved_signature(implementation_method)
+        if contract_signature.return_annotation is inspect.Signature.empty:
+            raise ApplicationServiceDefinitionError(
+                symbol=f"{implementation_symbol}.{name}",
+                reason="public service methods must declare a return annotation",
+            )
+        if _business_signature(contract_signature) != _business_signature(implementation_signature):
+            raise ApplicationServiceDefinitionError(
+                symbol=f"{implementation_symbol}.{name}",
+                reason="implementation signature must exactly match its public contract",
+            )
+        try:
+            validator = _compile_argument_validator(
+                contract_method,
+                contract_signature,
+                annotations,
+            )
+        except Exception as original_error:
+            raise ApplicationServiceDefinitionError(
+                symbol=f"{contract.__module__}.{contract.__qualname__}.{name}",
+                reason=f"Pydantic could not compile the method: {type(original_error).__name__}",
+            ) from None
+        source = _method_source(contract_method, discovery.owner)
+        authorization = _authorization_requirement(implementation, implementation_method)
+        unknown_permissions = tuple(
+            permission
+            for permission in authorization.permissions
+            if permission not in permission_catalog
+        )
+        if unknown_permissions:
+            raise AuthorizationDefinitionError(
+                symbol=f"{contract.__module__}.{contract.__qualname__}.{name}",
+                reason=(
+                    "authorization references unknown permissions: "
+                    f"{tuple(str(item) for item in unknown_permissions)!r}"
+                ),
+            )
+        descriptor = ApplicationServiceMethod(
+            name=name,
+            source=source,
+            requires_authenticated_user=authorization.requires_authenticated_user,
+            permissions=authorization.permissions,
+            allows_anonymous=authorization.allows_anonymous,
+            service=contract,
+            implementation=implementation,
+            method=implementation_method,
+            unit_of_work=_declaration(implementation, implementation_method),
+            validation_enabled=_effective_switch(
+                implementation, implementation_method, _VALIDATION_ATTRIBUTE, True
+            ),
+            auditing_enabled=_effective_switch(
+                implementation, implementation_method, _AUDITING_ATTRIBUTE, not is_integration
+            ),
+            policy_sources=_policy_sources(
+                implementation, implementation_method, binding.implementation_owner
+            ),
+        )
+        descriptor = replace(
+            descriptor, interceptors=_match_interceptors(descriptor, interceptor_rules)
+        )
+        compiled_methods[name] = _CompiledMethod(
+            name=name,
+            contract_method=contract_method,
+            implementation_method=implementation_method,
+            validator=validator,
+            parameter_names=frozenset(tuple(contract_signature.parameters)[1:]),
+            authorization=authorization,
+            descriptor=descriptor,
+            signature=contract_signature,
+            interceptor_steps=MappingProxyType(
+                {
+                    stage: tuple(item for item in descriptor.interceptors if item.before is stage)
+                    for stage in InterceptionStage
+                }
+            ),
+        )
+        public_methods.append(descriptor)
+
+    if not public_methods:
+        raise ApplicationServiceDefinitionError(
+            symbol=f"{contract.__module__}.{contract.__qualname__}",
+            reason="application service contract must declare at least one public async method",
+        )
+    registration = ApplicationServiceRegistration(
+        contract=contract,
+        implementation=implementation,
+        connection_name=discovery.definition.connection_name,
+        owner=discovery.owner,
+        implementation_owner=binding.implementation_owner,
+        source=discovery.source,
+        implementation_source=binding.implementation_source,
+        replaced_sources=binding.replaced_sources,
+        declaration_index=discovery.declaration_index,
+        methods=tuple(public_methods),
+        is_public_service=is_public_service,
+        has_contract=has_contract,
+        is_integration_service=is_integration,
+    )
+    return _CompiledApplicationService(
+        registration=registration,
+        methods=MappingProxyType(compiled_methods),
+    )
+
+
+_POLICY_ATTRIBUTES = (
+    _UNIT_OF_WORK_ATTRIBUTE,
+    _AUTHORIZATION_ATTRIBUTE,
+    _ALLOW_ANONYMOUS_ATTRIBUTE,
+    _VALIDATION_ATTRIBUTE,
+    _AUDITING_ATTRIBUTE,
+)
+
+
+def _validate_policy_locations(
+    contract: type[object] | None, implementation: type[object], integration: bool
+) -> None:
+    # provides 只仲裁公开身份；最终实现继承的其他业务 Contract 同样不能持有策略。
+    contracts = dict.fromkeys((contract, *_inherited_contracts(implementation)))
+    for root, attributes in (
+        *((candidate, _POLICY_ATTRIBUTES) for candidate in contracts if candidate is not None),
+        (implementation if integration else None, _POLICY_ATTRIBUTES[:2]),
+    ):
+        if root is None:
+            continue
+        for owner in root.__mro__:
+            for target in (
+                owner,
+                *(value for value in vars(owner).values() if inspect.isfunction(value)),
+            ):
+                if any(attribute in vars(target) for attribute in attributes):
+                    raise ApplicationServiceDefinitionError(
+                        symbol=getattr(target, "__qualname__", root.__qualname__),
+                        reason="Contract policies must move to implementation"
+                        if root in contracts
+                        else "IntegrationService cannot declare user authorization",
+                    )
+
+
+def _policy_sources(
+    implementation: type[object], method: Callable[..., Any], owner: ModuleKey
+) -> tuple[SourceLocation, ...]:
+    return tuple(
+        _method_source(target, owner)
+        for target in (*reversed(implementation.__mro__), method)
+        if any(attribute in vars(target) for attribute in _POLICY_ATTRIBUTES)
+    )
+
+
+def _match_interceptors(
+    method: ApplicationServiceMethod, rules: tuple[_InterceptorRule, ...]
+) -> tuple[InterceptorRegistration, ...]:
+    matched: list[InterceptorRegistration] = []
+    for rule in rules:
+        try:
+            accepted = rule.match(method)
+            if not isinstance(accepted, bool):
+                raise TypeError("interceptor match must return bool")
+        except Exception as error:
+            raise ApplicationServiceDefinitionError(
+                symbol=rule.registration.source.symbol
+                or rule.registration.interceptor.__qualname__,
+                reason=(
+                    f"interceptor match failed for {rule.registration.owner}: "
+                    f"{type(error).__name__}"
+                ),
+            ) from None
+        if accepted:
+            matched.append(rule.registration)
+    return tuple(sorted(matched, key=lambda item: tuple(InterceptionStage).index(item.before)))
+
+
+def _public_method_names(candidate: type[object], *, is_contract: bool) -> tuple[str, ...]:
+    names: dict[str, None] = {}
+    for owner in reversed(candidate.__mro__):
+        if owner in (object, ApplicationService, ApplicationServiceContract):
+            continue
+        if is_contract and owner.__module__ == "typing":
+            continue
+        for name, value in owner.__dict__.items():
+            if name.startswith("_"):
+                continue
+            if inspect.isfunction(value) or isinstance(value, (staticmethod, classmethod)):
+                names[name] = None
+    return tuple(names)
+
+
+def _require_async_instance_method(
+    owner: type[object],
+    name: str,
+    *,
+    role: str,
+) -> Callable[..., Awaitable[object]]:
+    symbol = f"{owner.__module__}.{owner.__qualname__}.{name}"
+    descriptor = inspect.getattr_static(owner, name)
+    if isinstance(descriptor, (staticmethod, classmethod)):
+        raise ApplicationServiceDefinitionError(
+            symbol=symbol,
+            reason=f"public {role} methods must be instance methods",
+        )
+    method = getattr(owner, name)
+    if not inspect.isfunction(method) or not inspect.iscoroutinefunction(method):
+        raise ApplicationServiceDefinitionError(
+            symbol=symbol,
+            reason=f"public {role} methods must use async def",
+        )
+    parameters = tuple(inspect.signature(method).parameters.values())
+    if not parameters or parameters[0].kind not in (
+        inspect.Parameter.POSITIONAL_ONLY,
+        inspect.Parameter.POSITIONAL_OR_KEYWORD,
+    ):
+        # Catalog 与 HTTP generator 都会剥离 receiver；缺少首个位置参数时不能伪装成实例方法。
+        raise ApplicationServiceDefinitionError(
+            symbol=symbol,
+            reason=f"public {role} methods must declare an instance receiver",
+        )
+    return cast(Callable[..., Awaitable[object]], method)
+
+
+def _resolved_signature(
+    method: Callable[..., Awaitable[object]],
+) -> tuple[inspect.Signature, dict[str, object]]:
+    annotations = get_type_hints(method, include_extras=True)
+    signature = inspect.signature(method)
+    parameters = tuple(
+        parameter.replace(annotation=annotations.get(name, parameter.annotation))
+        for name, parameter in signature.parameters.items()
+    )
+    resolved = signature.replace(
+        parameters=parameters,
+        return_annotation=annotations.get("return", signature.return_annotation),
+    )
+    return resolved, annotations
+
+
+def _compile_argument_validator(
+    method: Callable[..., Awaitable[object]],
+    signature: inspect.Signature,
+    annotations: Mapping[str, object],
+) -> Callable[..., Awaitable[_ValidatedArguments]]:
+    async def capture(*args: object, **kwargs: object) -> _ValidatedArguments:
+        # 第一个值是 validation-only self sentinel；业务 implementation 尚未解析或执行。
+        return tuple(args[1:]), dict(kwargs)
+
+    capture.__name__ = method.__name__
+    capture.__qualname__ = method.__qualname__
+    cast(Any, capture).__signature__ = signature
+    capture.__annotations__ = dict(annotations)
+    validated = validate_call(
+        config=ConfigDict(
+            arbitrary_types_allowed=True,
+            validate_by_name=True,
+            hide_input_in_errors=True,
+        )
+    )(capture)
+    return cast(Callable[..., Awaitable[_ValidatedArguments]], validated)
+
+
+def _method_source(method: Any, owner: ModuleKey) -> SourceLocation:
+    file_name: str | None = None
+    line: int | None = None
+    try:
+        file_name = inspect.getsourcefile(method)
+        _, line = inspect.getsourcelines(method)
+    except (OSError, TypeError):
+        pass
+    return SourceLocation(
+        owner=str(owner),
+        file=file_name,
+        line=line,
+        symbol=f"{method.__module__}.{method.__qualname__}",
+    )

python_platform/application_services/contracts.py

@@ -0,0 +1,188 @@
+"""Application Service 的公开 Protocol 与 concrete implementation metadata。"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Protocol, TypeVar
+
+from .errors import ApplicationServiceDefinitionError
+
+if TYPE_CHECKING:
+    from ..settings.provider import SettingProvider
+
+_APPLICATION_SERVICE_DEFINITION_ATTRIBUTE = "__python_platform_application_service_definition__"
+_TApplicationService = TypeVar("_TApplicationService", bound="ApplicationService")
+_DEFAULT_CONNECTION_NAME = "default"
+
+
+class ApplicationServiceContract(Protocol):
+    """跨 Module 注入的业务服务必须显式继承此 Protocol marker。"""
+
+
+class ApplicationService:
+    """业务实现；无独立 Contract 时，以自身类型发布受管理代理。"""
+
+    _setting_provider: SettingProvider | None = None
+
+    @property
+    def setting_provider(self) -> SettingProvider:
+        # 由受管理调用绑定到当前 Application；不要求业务构造函数调用 super。
+        if self._setting_provider is None:
+            raise RuntimeError("setting_provider is only bound during managed invocation")
+        return self._setting_provider
+
+
+class IntegrationService(ApplicationService):
+    """仅供应用内协作的服务；必须声明 Contract，不承载用户授权。"""
+
+
+class _InternalApplicationServiceContributor(ApplicationService):
+    """框架内部多贡献者基类；不发布含糊的 single Protocol。"""
+
+
+@dataclass(frozen=True, slots=True)
+class _ApplicationServiceDefinition:
+    contract: type[ApplicationServiceContract] | None
+    connection_name: str
+
+
+def application_service(
+    *,
+    provides: type[ApplicationServiceContract] | None = None,
+    connection_name: str = _DEFAULT_CONNECTION_NAME,
+) -> Callable[[type[_TApplicationService]], type[_TApplicationService]]:
+    """显式声明契约或连接；唯一名义继承的业务契约可以按约定识别。"""
+
+    normalized_connection = _validate_connection_name(connection_name)
+
+    def decorate(
+        service_type: type[_TApplicationService],
+    ) -> type[_TApplicationService]:
+        symbol = getattr(service_type, "__qualname__", type(service_type).__qualname__)
+        if not isinstance(service_type, type) or not issubclass(service_type, ApplicationService):
+            raise ApplicationServiceDefinitionError(
+                symbol=symbol,
+                reason="application_service decorator requires an ApplicationService subclass",
+            )
+        if _APPLICATION_SERVICE_DEFINITION_ATTRIBUTE in service_type.__dict__:
+            raise ApplicationServiceDefinitionError(
+                symbol=f"{service_type.__module__}.{service_type.__qualname__}",
+                reason="application service metadata is already declared",
+            )
+        contract = provides
+        if contract is None:
+            if not _is_internal_contributor(service_type):
+                contract = _infer_contract(service_type)
+        else:
+            _validate_contract(
+                provides,
+                symbol=f"{service_type.__module__}.{service_type.__qualname__}",
+            )
+        setattr(
+            service_type,
+            _APPLICATION_SERVICE_DEFINITION_ATTRIBUTE,
+            _ApplicationServiceDefinition(
+                contract=contract,
+                connection_name=normalized_connection,
+            ),
+        )
+        return service_type
+
+    return decorate
+
+
+def _definition_for(
+    candidate: type[object],
+) -> _ApplicationServiceDefinition | None:
+    if not issubclass(candidate, ApplicationService) or candidate in (
+        ApplicationService,
+        IntegrationService,
+        _InternalApplicationServiceContributor,
+    ):
+        return None
+    metadata = candidate.__dict__.get(_APPLICATION_SERVICE_DEFINITION_ATTRIBUTE)
+    if metadata is None:
+        # 只读取类的继承事实，不把推导结果写回共享类或全局 registry。
+        return _ApplicationServiceDefinition(
+            contract=_infer_contract(candidate),
+            connection_name=_DEFAULT_CONNECTION_NAME,
+        )
+    if not isinstance(metadata, _ApplicationServiceDefinition):
+        raise ApplicationServiceDefinitionError(
+            symbol=f"{candidate.__module__}.{candidate.__qualname__}",
+            reason="application service decorator metadata has an invalid runtime shape",
+        )
+    if metadata.contract is None:
+        if issubclass(candidate, IntegrationService):
+            raise ApplicationServiceDefinitionError(
+                symbol=f"{candidate.__module__}.{candidate.__qualname__}",
+                reason="IntegrationService requires an independent Contract",
+            )
+    else:
+        _validate_contract(
+            metadata.contract,
+            symbol=f"{candidate.__module__}.{candidate.__qualname__}",
+        )
+    _validate_connection_name(metadata.connection_name)
+    return metadata
+
+
+def _inherited_contracts(candidate: type[object]) -> tuple[type[object], ...]:
+    return tuple(
+        base
+        for base in candidate.__mro__[1:]
+        if base is not ApplicationServiceContract
+        and ApplicationServiceContract in base.__mro__
+        and getattr(base, "_is_protocol", False)
+    )
+
+
+def _infer_contract(candidate: type[object]) -> type[ApplicationServiceContract] | None:
+    contracts = _inherited_contracts(candidate)
+    most_specific = tuple(
+        base for base in contracts if not any(base in other.__mro__[1:] for other in contracts)
+    )
+    if not most_specific and not issubclass(candidate, IntegrationService):
+        return None
+    if len(most_specific) != 1:
+        raise ApplicationServiceDefinitionError(
+            symbol=f"{candidate.__module__}.{candidate.__qualname__}",
+            reason=(
+                "ApplicationService requires one inherited business contract "
+                "or explicit provides=Contract"
+            ),
+        )
+    return most_specific[0]
+
+
+def _validate_contract(candidate: object, *, symbol: str) -> None:
+    is_protocol = isinstance(candidate, type) and bool(getattr(candidate, "_is_protocol", False))
+    inherits_marker = (
+        isinstance(candidate, type) and ApplicationServiceContract in candidate.__mro__
+    )
+    if not is_protocol or not inherits_marker or candidate is ApplicationServiceContract:
+        raise ApplicationServiceDefinitionError(
+            symbol=symbol,
+            reason="provides must be an ApplicationServiceContract Protocol",
+        )
+
+
+def _is_internal_contributor(candidate: type[object]) -> bool:
+    return issubclass(candidate, _InternalApplicationServiceContributor)
+
+
+def _validate_connection_name(connection_name: str) -> str:
+    if not isinstance(connection_name, str) or not connection_name:
+        raise ApplicationServiceDefinitionError(
+            symbol="<decorator>",
+            reason="connection_name must be a non-empty string",
+        )
+    if connection_name != connection_name.strip() or any(
+        not (character.isalnum() or character in "_-") for character in connection_name
+    ):
+        raise ApplicationServiceDefinitionError(
+            symbol="<decorator>",
+            reason="connection_name must contain only letters, digits, '_' or '-'",
+        )
+    return connection_name