Added

• HTTP: Log translated upstream HTTP errors with structured context, including service, error type, request method, upstream URL, status code, and capped upstream response body details.
• Exceptions: Include upstream status and response body details in UpstreamRequestException responses for upstream HTTP 400/422 failures.

Fixed

• HTTP: Handle httpx.RequestError instances without request metadata without raising a secondary exception during upstream error translation.
• Exception Handlers: Log inbound request context when returning standardized upstream error responses.
• Docs: Document upstream error logging fields and 400/422 response details.

Added

• HTTP: Add translate_upstream_errors(service) to convert httpx upstream status and request failures into standardized ZodiacCore exceptions for both async and sync functions.
• Exceptions: Add UpstreamServiceException and UpstreamRequestException for explicit upstream service failures, including service name and upstream error classification.
• Exception Handlers: Register a dedicated upstream exception handler that returns standardized HTTP 400 responses for translated upstream failures.
• Templates: Update the standard-3tier external client example to use ZodiacClient with translate_upstream_errors.
• Docs: Document upstream error translation, manual upstream business-error mapping, and the new upstream exception types in the exceptions API guide.
• Tests: Add coverage for upstream exception behavior, handler registration, async/sync HTTP translation, and template usage.

Fixed

• Exceptions: Respect http_code declared on direct ZodiacException subclasses when converting them to HTTP responses, while preserving fixed HTTP statuses for built-in exception families.

Changed

• Docs: Clarify the distinction between HTTP status codes and business error codes, including how built-in exception families and direct ZodiacException subclasses should be used.

Added

• CLI: --package-name option for zodiac new command to customize the generated Python package name (defaults to app).
• Middleware: ServiceNameMiddleware for scoping service names in request context, allowing per-app log attribution in multi-app deployments.
• Context: service_name_scope and get_service_name for managing service-level context in zodiac_core.context.
• Logging: Loguru patcher now prefers service_name from context if available, enabling accurate service tagging in shared logging sinks.
• Templates: standard-3tier template now fully supports dynamic package names and includes ServiceNameMiddleware registration by default.
• Tests: Comprehensive multi-app integration tests (tests/multi_app/dual_full_apps/) using real Uvicorn servers to validate isolation and shared resources.

Changed

• CLI: zodiac new now validates package names against Python identifiers and reserved names (main, config, tests).
• Middleware: register_middleware now accepts an optional service_name to automatically enable ServiceNameMiddleware.
• Docs: Documentation updated with --package-name usage and architectural details for multi-app setups.

Added

• Database: get_session() accepts an optional name parameter for multi-database support; defaults to the default database for backward compatibility.
• Config: StrictConfig base model (extra='forbid', frozen=True) for configuration section Pydantic models — rejects typo keys and prevents mutation after creation.
• Utils: strtobool() as a Python 3.13+ compatible drop-in replacement for the removed distutils.util.strtobool, returning bool instead of int.
• Docs: Best practices guide for dependency-injector Configuration (strict mode, required files, type conversion pitfalls, environment variable interpolation).
• Docs: API reference page for the zodiac_core.utils module.
• Tests: Integration tests for dependency-injector strict=True + required=True + as_(strtobool) and StrictConfig constraints; dependency-injector added as dev dependency.

Changed

• Template: Generated projects use providers.Configuration(strict=True) and from_ini(path, required=True) for fail-fast configuration loading.
• Template: Config models (DbConfig, CacheConfig) inherit StrictConfig instead of BaseModel; type conversion uses Pydantic models via ConfigManagement.provide_config() instead of manual as_() calls.
• Docs: All code examples across config, context, architecture, and getting-started guides updated to use strict=True, required=True, and strtobool imports from zodiac_core.utils.

Fixed

• Config: Replace as_(bool) / as_=bool with as_(strtobool) for boolean config values — bool("false") evaluates to True, causing silent misconfiguration.
• Tests: Force reinstall zodiac-core in generated project quality test to prevent stale uv cache from masking template breakage.

Added

• Cache: Optional include_cls and include_self on @cached so the default key builder can fold receiver class identity into the key for classmethods (cls) and instance methods (self), gated by conventional first-parameter names; document that include_self is class-scoped (not per-instance) and that inheritance changes cache partitioning when enabled.
• Tests: Expand @cached coverage for custom key_builder, include_cls with base/derived classes, include_self sharing across instances of the same class, parent/child class separation, and instance methods that still require an explicit key_builder when receiver-aware keys are omitted.

Changed

• Docs: Add a “Receiver-aware default keys” section to the cache API guide (constraints, warnings, and examples for class vs instance methods).

Added

• HTTP: Add init_http_client() as a lifecycle helper for creating and closing a shared ZodiacClient within an application or DI resource.
• Database: Add scoped shutdown support via db.shutdown(name="...") so a single named database can be released without disposing all registered engines.
• Cache: Add scoped shutdown support via cache.shutdown(name="...") so a single named cache can be released without clearing all registered caches.
• Tests: Add coverage for named database/cache shutdown and for init_db_resource() cleaning up only its own database name.

Changed

• Database: Make DatabaseManager.setup() deterministic by allowing repeated setup only for the same effective configuration and raising RuntimeError for conflicting configuration on an existing name.
• Database: Make init_db_resource() release only the database registered under its own name, preserving other shared database resources in the same process.
• Template: Manage the shared HTTP client as an application resource in the standard 3-tier template and initialize app resources through AsyncExitStack.
• Template: Align generated project configuration loading with APPLICATION_ENVIRONMENT and default the template fallback environment to develop.
• CLI: Clarify that zodiac new --force allows generation into an existing directory without removing unrelated files.
• Docs: Update database, cache, config, context, architecture, CLI, and getting-started documentation to reflect the scoped resource lifecycle and template conventions.

Fixed

• Template: Ensure generated projects use resource lifecycle management for shared HTTP clients instead of relying on unmanaged singleton client instances.

Changed

• Cache: Restrict the default @cached key builder to stable immutable parameters and require an explicit key_builder for complex arguments instead of falling back to unstable automatic keys.
• Cache: Make cache.setup(...) deterministic by allowing repeated setup only for identical effective configuration and raising RuntimeError for conflicting settings.
• Docs: Clarify cache setup idempotency rules and document the supported/default key-builder constraints for @cached.

Fixed

• Cache: Decode the internal cached-None sentinel in public get() while preserving correct get_or_set() hit detection under lock rechecks.
• Cache: Preserve default_ttl when rebuilding a ZodiacCache wrapper from an existing aiocache alias.

Added

• Tests: Expand cache coverage for tuple-based default keys, deterministic setup behavior, wrapper rebuild state, public get() after cached None, and the cached-None lock recheck path.

Fixed

• Logging: When json_format=True, use empty "text" in serialized JSON so the message appears only in record.message, avoiding duplication and reducing log size (loguru#594).

Changed

• Logging: Unify console and file sink defaults in setup_loguru() via shared _sink_defaults and _apply_sink_defaults(); document empty-text behavior and override via console_options/file_options in docstring.

Fixed

• HTTP: Use HTTP_422_UNPROCESSABLE_CONTENT (RFC 9110) instead of deprecated HTTP_422_UNPROCESSABLE_ENTITY in UnprocessableEntityException and response_unprocessable_entity(), resolving Starlette deprecation warnings.

Changed

• Dependencies: Require starlette>=0.48.0 so the RFC 9110 status constant is available.