feat(service): add service composition primitives

[cofin]

Summary

• Add ServiceComposition[Unpack[Ts]] for typed async service composition on a caller-owned session
• Add public ServiceProvider and ServiceWithSession typing primitives
• Re-export the new service composition API from advanced_alchemy.service
• Add runtime and typing tests for provider cleanup and per-position variadic typing

Stack

• Base branch: litestar-org:feat/service-composition-utility-extraction at 204887dd
• Parent PR: refactor: extract provider dependency utilities #721
• Head branch: litestar-org:feat/service-composition-core-composition at 3cf18d5a
• Rebased after the v1.10.0 release and refactor: extract provider dependency utilities #721 branch rebuild
• This PR is Ch.2 / advanced-alchemy-4vb

Notes

• composition.py uses a local async-generator closing helper because Python 3.9 lacks contextlib.aclosing; it can be refactored to contextlib.aclosing once 3.9 support is dropped.
• No unasyncd mapping was added because the current config enumerates only _async.py sources; composition.py is intentionally async-only and is not picked up.
• The intended app workflow remains the fullstack SPA shape: keep normal singular create_service_provider(...) providers, then compose those existing providers with async with provide_services(...) in listeners/jobs/CLI/guards. Ch.3 will add the Litestar wrapper for that path.

Validation

• .venv/bin/pytest tests/unit/test_utils/test_dependencies.py tests/unit/test_extensions/test_litestar/test_providers_wire_compat.py tests/unit/test_extensions/test_litestar/test_providers.py tests/unit/test_extensions/test_fastapi/test_providers.py tests/unit/test_service -q
• .venv/bin/ruff check advanced_alchemy/utils/dependencies.py advanced_alchemy/extensions/litestar/providers.py advanced_alchemy/extensions/fastapi/providers.py advanced_alchemy/service/composition.py advanced_alchemy/service/_typing.py tests/unit/test_utils/test_dependencies.py tests/unit/test_extensions/test_litestar/test_providers_wire_compat.py tests/unit/test_extensions/test_litestar/test_providers.py tests/unit/test_extensions/test_fastapi/test_providers.py tests/unit/test_service/test_composition.py tests/unit/test_service/test_composition_typing.py
• .venv/bin/mypy advanced_alchemy/utils/dependencies.py advanced_alchemy/extensions/litestar/providers.py advanced_alchemy/extensions/fastapi/providers.py advanced_alchemy/service/composition.py advanced_alchemy/service/_typing.py tests/unit/test_utils/test_dependencies.py tests/unit/test_extensions/test_litestar/test_providers_wire_compat.py tests/unit/test_extensions/test_fastapi/test_providers.py tests/unit/test_service/test_composition.py tests/unit/test_service/test_composition_typing.py
• .venv/bin/pyright advanced_alchemy/utils/dependencies.py advanced_alchemy/extensions/litestar/providers.py advanced_alchemy/extensions/fastapi/providers.py advanced_alchemy/service/composition.py advanced_alchemy/service/_typing.py tests/unit/test_utils/test_dependencies.py tests/unit/test_extensions/test_litestar/test_providers_wire_compat.py tests/unit/test_extensions/test_fastapi/test_providers.py tests/unit/test_service/test_composition.py tests/unit/test_service/test_composition_typing.py

---

📚 Documentation preview: https://litestar-org.github.io/advanced-alchemy-docs-preview/722

[sonarqubecloud]

Quality Gate failed

Failed conditions
0.0% Coverage on New Code (required ≥ 80%)

See analysis details on SonarQube Cloud