# Changelog & Release Notes (/docs/changelog)





This page documents all notable architectural evolutions, breaking changes, security patches, and migration paths across ZCore releases.

<Callout type="info" emoji="📦">
  **Upgrading ZCore:**
  To fetch the latest pre-release build, run:

  ```bash
  pip install --upgrade "fastapi-zcore-framework[all]==0.1.0rc2"
  ```
</Callout>

***

<Accordions type="multiple" defaultValue="['v0.1.0-rc.2']">
  <Accordion id="v0.1.0-rc.2" title="v0.1.0-rc.2 (Latest Pre-release) — October 06, 2026 🚀">
    Welcome to &#x2A;*v0.1.0-rc.2 (Release Candidate 2)** of the ZCore Framework! 🚀

    As we approach the final validation phase before tagging our official **v1.0.0 Stable GA**, `v0.1.0-rc.2` focuses on framework-wide error normalization, operational robustness, and developer ergonomic refinements.

    This release introduces an automated, normalized exception handling system conforming all HTTP errors to the `ResponseWrapper` envelope; implements an end-to-end soft-delete, restoration, and forced hard-delete lifecycle; scaffolds a high-performance, schema-projected `/lookup` endpoint; expands the dynamic AST search engine with negated operators and logical `NOT` grouping; establishes re-entrant, depth-aware Unit of Work coordination; generalizes user identifiers (`int`, `str`, `UUID`) across all subsystems; and introduces schema-level private field shielding for unauthenticated guests.

    ### 🚀 Core Features & Architectural Advancements [#-core-features--architectural-advancements]

    #### 1. 🛡️ Unified Exception Handling & Error Normalization (`ResponseWrapper`) [#1-️-unified-exception-handling--error-normalization-responsewrapper]

    All HTTP exceptions, validation failures, and internal server errors now strictly conform to the `ResponseWrapper` JSON envelope:

    * **Pydantic Error Sanitization (`_sanitize_error_item`, `_format_error_location`):** Converts raw Pydantic error `loc` tuples into readable dot-separated paths (e.g., `body.email`, `query.limit`) and safely extracts validation context.
    * **Standardized Handlers:**
      * `request_validation_exception_handler`: Formats 422 errors with clean field-level error lists and a human-readable summary.
      * `http_exception_handler`: Preserves original response headers while wrapping Starlette/FastAPI `HTTPException` instances.
      * `response_validation_exception_handler`: Intercepts internal schema mismatch errors (500) and displays field diagnostics only when `settings.DEBUG` is enabled.
      * `unhandled_exception_handler`: Catch-all fallback for uncaught runtime crashes with debug-gated stack traces.
    * **Centralized Registration (`register_exception_handlers`):** Attach all handlers with a single call to `register_exception_handlers(app)` with selective inclusion flags.
    * **Lazy Module Packaging:** Handlers are exported at the root package level via dynamic `__getattr__` resolution to prevent circular import overhead.

    #### 2. 🗑️ End-to-End Soft-Delete Lifecycle & Restoration (`restore`, `force`) [#2-️-end-to-end-soft-delete-lifecycle--restoration-restore-force]

    Soft deletion is now seamlessly integrated across the Repository, Service, and Web layers:

    * **Atomic Batch Soft-Delete:** `delete_multi()` executes atomic `UPDATE ... SET deleted_at=now()` with SQL dialect-aware `RETURNING` support and pre-fetch fallbacks.
    * **Single & Batch Restoration:** Added `restore(target)` and `restore_multi(ids)` to `WriteRepositoryMixin` and `WriteServiceMixin` to recover soft-deleted records (`deleted_at=None`).
    * **Forced Physical Hard Deletes:** Added `force: bool = False` across repository, service execution orchestrators, and lifecycle hooks (`pre_delete`, `post_delete`, `pre_delete_multi`, `post_delete_multi`).
    * **Web Router Query Flag:** Auto-scaffolded DELETE endpoints accept `?force=true` (e.g., `DELETE /tasks/{id}?force=true`) to permanently purge records when requested.

    #### 3. 🔍 Lightweight `LOOKUP` Endpoint & Schema-Driven Projections (`POST /lookup`) [#3--lightweight-lookup-endpoint--schema-driven-projections-post-lookup]

    Designed for autocomplete selectors, dropdown lists, and relational references:

    * **Automatic Schema Projection (`_resolve_lookup_projections`):** Introspects `lookup_schema` against SQLAlchemy model metadata to selectively generate `load_only(*columns)` statements, always including primary keys.
    * **Automatic Eager-Loader Configuration:** Detects relationships declared in `lookup_schema` and attaches optimal loader strategies (`selectinload` for collections, `joinedload` for scalar relations).
    * **Strict Whitelist Protection (`allowed_lookup_fields`):** Client queries attempting to filter or sort on unauthorized fields are immediately rejected with a 400 `ValidationError`.
    * **RBAC Integration:** Mapped to `Actions.LOOKUP` (`model.actions().LOOKUP`) for granular permission checks.

    #### 4. ⚡ Search Engine Negation & Logical `NOT` Grouping (`SearchEngine`) [#4--search-engine-negation--logical-not-grouping-searchengine]

    The dynamic JSON search engine now supports inverted filter operations:

    * **Inverted Operators:** Added `not_like`, `not_ilike`, `not_contains`, `not_startswith`, `not_endswith`, `not_in`, `not_between`, and `is_not_null`.
    * **SQL Expression Wrapping:** `_compare_column` detects `not_` prefixes and wraps clauses in SQLAlchemy's `not_()` expression.
    * **Logical `NOT` Blocks:** Evaluates nested filter groups under `op="not"` as `not_(and_(*sub_exprs))` or single-field inversions.
    * **Null Semantics:** `is_null` and `is_not_null` now accept boolean flags (`True`/`False`) or `None` values consistently.

    #### 5. 🔗 Re-entrant Unit of Work & Deferred Domain Events (`UnitOfWork`) [#5--re-entrant-unit-of-work--deferred-domain-events-unitofwork]

    Coordinates multi-service business transactions across complex modular monolith architectures:

    * **Depth-Aware Re-entrancy (`uow_depth`):** Tracks execution nesting depth in `session.info['uow_depth']`. Nested `UnitOfWork` blocks execute safe intermediate `session.flush()` calls, delegating the physical `session.commit()` solely to the outermost root boundary.
    * **Buffered Post-Commit Events:** Domain events registered via `uow.register_event()` across nested scopes accumulate in `session.info['uow_events']` and dispatch atomically **only after the root transaction commits**.
    * **Global Rollback Safeguard:** Any unhandled exception resets depth to `0`, clears pending events, and executes an immediate session rollback.

    #### 6. 🆔 Polymorphic User Identifiers (`int`, `str`, `UUID`) [#6--polymorphic-user-identifiers-int-str-uuid]

    Removed strict `uuid.UUID` type enforcement from core identity layers:

    * **Polymorphic `ZContext` & `UserProtocol`:** `ZContext.user_id` and `UserProtocol.id` now accept `Any | None` (supporting integer IDs, UUIDs, Auth0/Firebase string IDs, or custom tenant keys).
    * **Real-time Streaming (`StreamManager`):** Subscriber mapping queues (`users_queues`) now accept arbitrary user ID types with mixed-type string comparison routing.
    * **Cursor Pagination PK Inspection:** Keyset cursor pagination dynamically inspects column types (`mapper.primary_key[0].type.python_type`), coercing cursor payload keys to `int` or `UUID` automatically.

    #### 7. 🔒 Optional Authentication & Schema-Level Private Fields (`Zchema.__private__`) [#7--optional-authentication--schema-level-private-fields-zchema__private__]

    Enables clean guest-friendly routes and sensitive field filtering:

    * **Optional Authentication (`BaseAuth(auto_error=False)`):** Allows endpoints to accept optional authentication without raising `401 Unauthorized` on missing or invalid tokens.
    * **Dependency Anchor (`get_optional_user_stub`):** Exported across `zcore` and `zcore.security` for optional route parameters.
    * **Private Field Pruning (`__private__`):** Schemas can declare sensitive fields via `__private__: ClassVar[set[str]] = {"cost_price", "notes"}`. ZCore automatically prunes these fields from response payloads, input validations, and generated JSON schemas (`?schema=true`) when no authenticated user is present.

    #### 8. ⚙️ Tunable Framework Settings & Dynamic Bounds Validation [#8-️-tunable-framework-settings--dynamic-bounds-validation]

    Replaced magic numbers across subsystems with environment-driven settings in `Settings`:

    * **Subsystem Tuning:** Added `PAGINATION_DEFAULT_SIZE` (20), `PAGINATION_MAX_SIZE` (100), `SEARCH_MAX_DEPTH` (3), `CACHE_LOCAL_MAXSIZE` (1000), `CACHE_DEFAULT_TTL` (3600), `CACHE_EVICTION_INTERVAL` (60), `STREAM_QUEUE_MAXSIZE` (100), and `AUTH_CACHE_TTL` (300).
    * **Dynamic Parameter Validation:** Added Pydantic `@model_validator` across `PageNumberParams`, `CursorParams`, and `SearchRequest` to clamp requested page sizes within configured minimum and maximum boundaries.

    #### 9. 🧪 Advanced Testing Harness & Sandboxing Engine (`zcore.testing`) [#9--advanced-testing-harness--sandboxing-engine-zcoretesting]

    * **Database Table Lifecycle (`setup_test_database`):** Drop and recreate test database tables across sync fixtures or running event loops via `ThreadPoolExecutor` safely.
    * **Event Sandboxing (`EventDispatcherSandbox`):** Snapshots and restores registered event subscribers across test runs, eliminating listener pollution.
    * **Multi-Dependency Overrides:** `DatabaseRollback` and `ZTestClient` support custom engine injections, multiple authentication stub overrides, and strict Pydantic user model validation (`user_model`).

    #### 10. 🪵 Non-Intrusive Logging & Scope Context Isolation [#10--non-intrusive-logging--scope-context-isolation]

    * **Status-Code-Aware Exception Logging:** Application and HTTP exceptions log at `DEBUG` for client errors (`< 500`) and `ERROR` for server failures (`>= 500`).
    * **Independent Slow-Query Interceptor:** Slow queries exceeding `slow_query_threshold_ms` are logged even if general `log_sql_queries` is disabled.
    * **Developer Console Mode:** Development mode preserves native Uvicorn console formatting via `passthrough_loggers`, switching cleanly to `ProcessorFormatter` JSON rendering in production.
    * **Background Scope Context:** `background_scope` isolates Structlog contextvars, binds `task_id=scope_id`, and restores parent context on exit.

    #### 11. 🖥️ Cascading CLI Server Configuration & Dynamic Scaffolding [#11-️-cascading-cli-server-configuration--dynamic-scaffolding]

    * **Cascading Precedence (`zc run`):** Server parameters resolve with the precedence: `CLI Arguments > .env File > Defaults`.
    * **Transparent Uvicorn Passthrough:** Uses `parse_known_args()` to forward arbitrary flags (e.g., `--root-path`, `--proxy-headers`) directly to Uvicorn.
    * **Multi-Worker Safety:** Automatically disables `--reload` when `--workers > 1`.
    * **Dynamic Test Filename Pattern:** `zc startapp <app_name>` generates Pytest files following standard naming conventions (`test_<app_name>.py`).

    ***

    ### ⚠️ Breaking Changes & Migration Guide [#️-breaking-changes--migration-guide]

    <Tabs items="['1. Exception Handler Registration', '2. Delete Hook Signatures', '3. User Identifier Typing', '4. SQL Query Logging Default']">
      <Tab value="1. Exception Handler Registration">
        Replace manual exception handler bindings in `main.py` with the unified `register_exception_handlers` utility.

        ```python
        # Before (v0.1.0-rc.1)
        from zcore.exceptions import AppException, app_exception_handler

        app.add_exception_handler(AppException, app_exception_handler)

        # After (v0.1.0-rc.2)
        from zcore import register_exception_handlers

        register_exception_handlers(app)
        ```
      </Tab>

      <Tab value="2. Delete Hook Signatures">
        Custom service classes overriding delete hooks must now accept the optional `force: bool = False` keyword argument.

        ```python
        # Before (v0.1.0-rc.1)
        class TaskService(BaseService[Task]):
            async def pre_delete(self, id: Any) -> None:
                ...

            async def post_delete(self, model: Task) -> None:
                ...

        # After (v0.1.0-rc.2)
        class TaskService(BaseService[Task]):
            async def pre_delete(self, id: Any, force: bool = False) -> None:
                ...

            async def post_delete(self, model: Task, force: bool = False) -> None:
                ...
        ```
      </Tab>

      <Tab value="3. User Identifier Typing">
        If your custom code strictly expected `uuid.UUID` for `ctx.user_id` or `UserProtocol.id`, update type annotations to accept `Any`.

        ```python
        # Before (v0.1.0-rc.1)
        user_id: uuid.UUID | None = ctx.user_id

        # After (v0.1.0-rc.2)
        user_id: Any | None = ctx.user_id  # Supports int, str, and uuid.UUID
        ```
      </Tab>

      <Tab value="4. SQL Query Logging Default">
        `LoggingSettings.log_sql_queries` now defaults to `False` to reduce log noise. To enable SQL query dumping in development, update your settings or `.env`:

        ```bash
        LOG_SQL_QUERIES=true
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion id="v0.1.0-rc.1" title="v0.1.0-rc.1 — September 12, 2026 🚀">
    Welcome to &#x2A;*v0.1.0-rc.1 (Release Candidate 1)** of the ZCore Framework! 🚀

    As we officially transition from the Beta phase toward our milestone **v1.0.0** Stable GA, `v0.1.0-rc.1` marks a major milestone in framework stability, security hardening, and production readiness.

    This release delivers dynamic primary key detection across REST endpoints, introduces an anti-shadowing weighted route sorting algorithm, optimizes ORM mutations to accept model instances directly (bypassing duplicate database fetches), adds dialect-aware batch fallbacks for non-RETURNING databases (such as MySQL), integrates a centralized IANA timezone subsystem (`ZDateTime`), redesigns the structured logging pipeline via `ProcessorFormatter`, completely hardens the file storage layer with strict sandboxing and active XSS/executable scanning, and achieves complete unit and integration test coverage across all subsystems.

    ### 🚀 Core Features & Architectural Advancements [#-core-features--architectural-advancements-1]

    #### 1. 🎯 Dynamic Primary Key Resolution & Generalized Routing (`BaseRouter`) [#1--dynamic-primary-key-resolution--generalized-routing-baserouter]

    Previously, `BaseRouter` assumed model primary keys were strictly UUIDs. In `v0.1.0-rc.1`, routing infrastructure dynamically inspects ORM metadata:

    * **Automatic PK Type Detection (`_resolve_pk_type`):** Automatically resolves whether the primary key is an `int`, `uuid.UUID`, or other scalar type via SQLAlchemy column inspection.
    * **Dynamic Path Mapping (`_get_pk_path`):** Generates type-safe URL converter paths (e.g., `/{id:int}` for integer PKs, `/{id:uuid}` for UUIDs, or `/{id}` as a fallback).
    * **Explicit PK Override:** Models or routers can explicitly declare `pk_type = int` to override dynamic reflection.
    * **Streamlined Endpoint Signatures:** Cleaned up internal wrapper signatures by removing unused `**kwargs` and enforcing explicit parameter typing.

    #### 2. ⚖️ Weighted Route Specificity Sorting (Anti-Path Shadowing) [#2-️-weighted-route-specificity-sorting-anti-path-shadowing]

    A notorious issue in REST frameworks is Path Shadowing—where dynamic parameterized routes accidentally capture requests intended for static endpoints (e.g., `GET /{id}` shadowing `POST /search`):

    * **Multi-Tier Weighted Scoring (`_sort_routes`):** Replaced basic string sorting with an advanced scoring tuple: `(has_dynamic, total_dynamic, segment_scores, -len(segments))`.
    * **Strict Route Precedence:** Guarantees that static segment routes (`/search`) are always matched before single dynamic parameters (`/{id}`) and catch-all path parameters (`/{path:path}`), regardless of declaration order.

    #### 3. ⚡ Optimized Instance-Aware ORM Mutations (`update`, `delete`, `update_multi`) [#3--optimized-instance-aware-orm-mutations-update-delete-update_multi]

    To eliminate redundant database lookups when an entity is already loaded in memory:

    * **Direct Model Acceptance:** `BaseRepository.update()` and `BaseRepository.delete()` now accept `target: ModelType | Any`. If a model instance is passed directly, the preliminary `SELECT` query is completely skipped.
    * **Instance-Keyed Batch Updates:** `update_multi` now accepts dictionaries keyed by either model instances or primary key scalars (`dict[ModelType | Any, BaseModel]`), resolving the PK seamlessly via `getattr(key, self.pk_name, key)`.
    * **Aligned Service Hooks:** Updated `pre_update`, `on_update`, `pre_delete`, and `on_delete` in `BaseService` to accept `target: ModelType | Any`.

    #### 4. 🔄 Cross-Dialect Batch Compatibility (Dialect-Aware Fallbacks) [#4--cross-dialect-batch-compatibility-dialect-aware-fallbacks]

    Enables seamless database portability across SQL engines that lack native `RETURNING` support:

    * **Dialect-Aware `create_multi`:** Inspects the engine's `insert_returning` capability. If supported (PostgreSQL, modern SQLite), it executes `insert().returning()`. Otherwise (MySQL, older SQLite), it falls back gracefully to `db.add_all()` and `db.flush()`.
    * **Dialect-Aware `delete_multi`:** Inspects `delete_returning`. If unsupported, it fetches records via `get_by_ids()` prior to atomic deletion, guaranteeing deleted instances are returned intact.

    #### 5. ⏱️ Centralized Timezone Management & `ZDateTime` Subsystem [#5-️-centralized-timezone-management--zdatetime-subsystem]

    Introduced `zcore.utils.timezone` for robust, timezone-aware datetime manipulation:

    * **IANA ZoneInfo Resolution (`get_app_timezone`):** Resolves timezones with LRU caching and falls back safely to UTC if an invalid timezone is provided.
    * **`ZDateTime` Type Alias:** Custom type alias utilizing Pydantic's `PlainSerializer` to automatically format datetimes as timezone-aware ISO 8601 strings with offsets during JSON serialization.
    * **Timezone-Aware Helpers:** Added `now()`, `utc_now()`, `to_app_timezone()`, and `format_iso_with_app_timezone()`.
    * **Soft Delete & JSON Sync:** `SoftDeleteMixin` and `CustomJSONEncoder` now natively utilize timezone-aware timestamps.
    * **Windows Support:** Added `tzdata>=2024.1` for guaranteed IANA timezone database resolution on Windows environments.

    #### 6. 🪵 Enterprise Structured Logging (`LoggingSettings` & `ProcessorFormatter`) [#6--enterprise-structured-logging-loggingsettings--processorformatter]

    Redesigned the logging pipeline to seamlessly unify structlog and Python's standard logging library:

    * **`ProcessorFormatter` Integration:** Eliminates duplicate log emissions and bridges third-party loggers (`uvicorn`, `sqlalchemy.engine`) into a unified structlog pipeline.
    * **`LoggingSettings` Model:** Configured via `Settings.LOGGING` with backward-compatible bidirectional synchronization to legacy `LOG_LEVEL`.
    * **Slow Query Interceptor:** Added `slow_query_threshold_ms` to silently filter out fast queries and log only statements exceeding latency thresholds.
    * **Built-in File Rotation & DictConfig:** Added `RotatingFileHandler` support (10MB, 5 backups) via `file_path` setting and support for full `logging.config.dictConfig` overrides.
    * **Enhanced Telemetry:** `RequestLogMiddleware` now captures real HTTP status codes from `http.response.start` and client IPs.

    #### 7. 📦 Sandboxed Local Storage & Advanced Threat Validation [#7--sandboxed-local-storage--advanced-threat-validation]

    Expanded `zcore.storage` into an enterprise-grade, sandboxed asset management subsystem:

    * **Path Traversal Defense:** `LocalStorageProvider` incorporates `_extract_key`, `_key_to_path`, and `_resolve_path` to strictly bound all read/write/delete operations within `base_path`.
    * **URL Resolution & Existence Check:** Added `get_url(file_path_or_url)` and `exists(file_path_or_url)` to the `StorageProvider` base interface.
    * **Executable & XSS Threat Detection (`SafeMimeTypeValidator`):**
      * Increased sample inspection buffer from 2KB to 8KB.
      * Rejects binary executable headers (`MZ` for `.exe`/`.dll`, `#!/` for shell scripts, `\x7fELF` for Linux binaries).
      * Scans file payloads for Stored XSS and active script injections (`<script>`, `<?php`, `javascript:`, `onload=`, `onerror=`, `<iframe>`, etc.).

    #### 8. 🔍 Search Engine Hardening & Operator Unification [#8--search-engine-hardening--operator-unification]

    * **Consolidated Text Operators:** Unified `contains` into the `ilike` operator family with automatic SQL wildcard escaping (`%`, `_`).
    * **Non-String Column Text Search:** Automatically casts non-string database columns (e.g., UUIDs, integers) via `cast(col, String)` when text operators (`ilike`, `startswith`, `endswith`, `contains`) are applied.
    * **Expanded Type Coercion:** Supports `set` collections alongside `list` and `tuple` for `in` operators, and provides clear, column-aware `ValidationError` messages when coercion fails.

    #### 9. 🗄️ Native Engine JSON Serialization & Guaranteed Lifespan Teardown [#9-️-native-engine-json-serialization--guaranteed-lifespan-teardown]

    * **Custom JSON Column Serializer:** `DatabaseManager` passes `json_dumps` and `json_loads` directly to `create_async_engine`, enabling native persistence of `UUID`, `Decimal`, `date`, and `datetime` types in database JSON/JSONB columns.
    * **Guaranteed Shutdown Teardown:** `Kernel.lifespan` automatically executes `await close_cache()` and `await db_manager.close()` in its `finally` block, ensuring clean connection pool disposal upon application shutdown.
    * **Event-Loop Safe Cache Eviction:** Background cache eviction task in `BaseCache` lazily schedules sweeps only when an active event loop is running, preventing `RuntimeError` during CLI/import time.

    ***

    ### ⚠️ Breaking Changes & Migration Guide [#️-breaking-changes--migration-guide-1]

    <Tabs items="['1. get_list Parameter Ordering', '2. Instance Mutations', '3. Structured DB Configuration', '4. Storage Upload Return Type']">
      <Tab value="1. get_list Parameter Ordering">
        In `BaseRepository` and `BaseService`, variadic filter expressions (`*criterion`) have been moved to the beginning of the parameter list to match standard Python conventions and prevent positional shifting.

        ```python
        # Before (v0.1.0-beta.8) — ambiguous positional parameter placement
        items = await repo.get_list(pagination_params, fields_list, User.is_active == True)

        # After (v0.1.0-rc.1) — positional criterion first, optional controls via keyword arguments
        items = await repo.get_list(
            User.is_active == True,
            pagination=pagination_params,
            fields=fields_list
        )
        ```
      </Tab>

      <Tab value="2. Instance Mutations">
        You can now pass either the primary key or the instantiated model directly to `service.update()` and `service.delete()`.

        ```python
        # Before (v0.1.0-beta.8) — required passing ID, triggering an unnecessary second SELECT query
        user = await user_service.get(id=user_id)
        updated = await user_service.update(user.id, user_update_schema)

        # After (v0.1.0-rc.1) — direct instance update (zero redundant SELECT queries)
        user = await user_service.get(id=user_id)
        updated = await user_service.update(user, user_update_schema)
        ```
      </Tab>

      <Tab value="3. Structured DB Configuration">
        `db_manager.init_app` now accepts structured `DatabaseSettings` objects directly.

        ```python
        # Before (v0.1.0-beta.8)
        db_manager.init_app(
            db_url=settings.DATABASE_URL,
            pool_size=settings.POOL_SIZE,
            max_overflow=settings.MAX_OVERFLOW,
            echo=settings.DEBUG
        )

        # After (v0.1.0-rc.1) — pass structured settings directly
        db_manager.init_app(config=settings.DATABASE)
        ```
      </Tab>

      <Tab value="4. Storage Upload Return Type">
        `StorageProvider.upload()` and `upload_stream()` now return the web-accessible URL directly instead of a raw storage path.

        ```python
        # Before (v0.1.0-beta.8)
        file_path = await storage.upload("uploads", file)
        url = storage.get_url(file_path)

        # After (v0.1.0-rc.1)
        url = await storage.upload("uploads", file)  # Returns the web-accessible URL directly
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion id="v0.1.0-beta.8" title="v0.1.0-beta.8 — August 24, 2026 🚀">
    Welcome to **v0.1.0-beta.8** of the ZCore Framework! 🚀

    As we approach our milestone **v1.0.0** stable release, `v0.1.0-beta.8` delivers major performance breakthroughs in relational data mutations, introduces an enterprise-grade isolated background task execution pipeline with automatic dependency injection, embeds native soft-delete capabilities, significantly expands dynamic search operators, completely redesigns the developer experience with a rich, interactive Terminal User Interface (TUI), and aligns all CLI scaffolding templates with the latest single-generic architecture.

    ### 🚀 Core Features & Architectural Advancements [#-core-features--architectural-advancements-2]

    #### 1. ⚡ High-Performance Bulk DBAPI Mutations (`create_multi`, `update_multi`, `delete_multi`) [#1--high-performance-bulk-dbapi-mutations-create_multi-update_multi-delete_multi]

    We completely revamped the bulk data modification pipelines in `BaseRepository` to bypass individual ORM hydration overhead and leverage native database acceleration:

    * **`create_multi` via `INSERT ... RETURNING`:** Batch insertions now execute in a single roundtrip using atomic `INSERT ... RETURNING` clauses, eliminating individual entity flushes while returning fully hydrated model instances.
    * **`update_multi` via DBAPI `executemany`:** Batch updates now bypass pre-fetching and hydrating ORM entities in memory. Updates are executed directly at the DBAPI level with compiled parameterized payloads, followed by a single consolidated batch query fetch.
    * **`delete_multi` via `DELETE ... RETURNING`:** Bulk deletions are executed in a single atomic SQL statement without prior entity fetching, returning all deleted records cleanly.

    #### 2. ⏱️ Isolated Background Tasks & Scope Management (`background_scope`, `@background_task`) [#2-️-isolated-background-tasks--scope-management-background_scope-background_task]

    Running background jobs in FastAPI that access request-scoped dependencies or database sessions often triggers `RuntimeError: Session is closed`. ZCore resolves this at the architectural layer:

    * **`background_scope` Async Context Manager:** Provisions an independent IoC scope, allocates a fresh, dedicated `AsyncSession` from `db_manager`, and safely clones the active user context (`inherit_context=True`) for background execution.
    * **`@background_task` Decorator:** Automatically wraps any async coroutine or synchronous function (executed in a non-blocking threadpool via `anyio.to_thread`) inside `background_scope()`.
    * **Automatic IoC Auto-Wiring:** Any type-annotated parameter omitted during invocation is automatically resolved directly from the IoC container.

    #### 3. 🗑️ Built-in Soft Deletion Infrastructure (`SoftDeleteMixin`) [#3-️-built-in-soft-deletion-infrastructure-softdeletemixin]

    Soft deletion is now an out-of-the-box framework primitive rather than a manual scoping pattern:

    * **`SoftDeleteMixin`:** Add timestamp-based soft deletion to any model with `class Task(Base, SoftDeleteMixin):`.
    * **Automatic Query Scoping:** Injects an indexed, timezone-aware `deleted_at: Mapped[datetime | None]` column and automatically filters all repository operations (`get()`, `get_list()`, `count()`, `exist()`, `search()`) with `WHERE deleted_at IS NULL`.
    * **Lifecycle Helpers:** Provides clean `task.soft_delete()`, `task.restore()`, and `task.is_deleted` properties.

    #### 4. 🔍 Advanced Dynamic Search Operators & Configurable Depth (`SearchEngine`) [#4--advanced-dynamic-search-operators--configurable-depth-searchengine]

    The dynamic query engine has been significantly expanded with powerful string-matching and range operators:

    * **`contains`:** Performs substring matching on text columns (with automatic wildcard sanitization) and collection containment.
    * **`startswith` & `endswith`:** String prefix and suffix matching with automated SQL wildcard escaping.
    * **`between`:** Range evaluations for numerical, date, and timestamp columns accepting inclusive `[min, max]` boundaries with automatic type coercion.
    * **Configurable `__max_search_depth__`:** Filter and relation inclusion (`include`) depth limits can now be customized per model via the `__max_search_depth__` attribute (defaulting safely to `3` to defend against query DoS attacks).

    #### 5. 🛡️ Scope-Aware Existence Verifications (`exist`) [#5-️-scope-aware-existence-verifications-exist]

    * `BaseRepository.exist()` now strictly evaluates and enforces model-level `scope_query` and soft-delete filters before checking record existence via `limit(1)`, preventing cross-tenant or deleted entity enumeration.

    #### 6. 🖥️ Interactive TUI & Scaffolding Engine (`zc`) [#6-️-interactive-tui--scaffolding-engine-zc]

    The `zc` CLI has been completely rewritten into an interactive Terminal User Interface powered by **Rich** and **Questionary**:

    * **Context-Aware Dashboard:** Running `zc` automatically detects whether you are in an active project or a workspace with multiple microservices.
    * **Multi-Database Bootstrapping:** `zc init` interactively configures SQLite (`aiosqlite`), PostgreSQL (`asyncpg`), or MySQL (`aiomysql`) with pre-configured `.env` and `requirements.txt` files.
    * **Automated Virtual Environment Setup:** Automatically initializes isolated `.venv` environments and installs dependencies using ultra-fast `uv` or standard `pip`.
    * **Granular 7-Layer Scaffolding:** `zc startapp` supports *Full Boilerplate*, *Clean/Blank*, or *Custom Layer Selection* across Models, Schemas, Repositories, Services, Routers, Plugins, and Pytest suites.
    * **Automatic Secret Key Generation:** `zc init` automatically provisions fresh 64-character cryptographic `SECRET_KEY` strings into `.env`.

    ### 🐛 Bug Fixes & Refinements [#-bug-fixes--refinements]

    #### 7. 🛠️ CLI Scaffolding Template Alignment [#7-️-cli-scaffolding-template-alignment]

    * **Fixed `BaseRepository` & `BaseService` Boilerplate:** Corrected scaffolding templates in `zcore.cli.templates` (`REPOSITORY_TEMPLATE` and `SERVICE_TEMPLATE`) to use the streamlined single-generic signature (`BaseRepository[Model]` and `BaseService[Model]`) introduced in `v0.1.0-beta.7`, removing obsolete schema generic parameters and redundant imports.
    * **AST Compilation Test Guard:** Added explicit AST compilation testing to the test suite (`test_scaffolded_templates_are_valid_python`) to guarantee all generated boilerplates are 100% valid, error-free Python code.

    ***

    ### ⚠️ Breaking Changes & Migration Guide [#️-breaking-changes--migration-guide-2]

    <Tabs items="['1. Bulk Mutation Signatures', '2. SoftDeleteMixin', '3. Background Tasks']">
      <Tab value="1. Bulk Mutation Signatures">
        Because `create_multi`, `update_multi`, and `delete_multi` now utilize database-level `RETURNING` clauses and direct DBAPI execution, manual `refresh=True` loops are no longer needed.

        ```python
        # Before (v0.1.0-beta.7)
        created_items = await repo.create_multi(schemas, refresh=True)

        # After (v0.1.0-beta.8)
        created_items = await repo.create_multi(schemas)
        ```
      </Tab>

      <Tab value="2. SoftDeleteMixin">
        If you previously wrote manual `WHERE is_deleted == False` clauses in `scope_query`, you can now inherit directly from `SoftDeleteMixin`.

        ```python
        # Before (v0.1.0-beta.7)
        class Task(Base):
            __tablename__ = "tasks"
            is_deleted: Mapped[bool] = mapped_column(default=False)

            @classmethod
            def scope_query(cls, query: Select) -> Select:
                return query.where(cls.is_deleted.is_(False))

        # After (v0.1.0-beta.8)
        from zcore import Base, SoftDeleteMixin

        class Task(Base, SoftDeleteMixin):
            __tablename__ = "tasks"
            # Automatically provides deleted_at, is_deleted, soft_delete(), restore(), and scope_query
        ```
      </Tab>

      <Tab value="3. Background Tasks">
        Replace manual session allocations inside background routines with `@background_task`.

        ```python
        # Before (v0.1.0-beta.7)
        async def process_task(task_id: uuid.UUID):
            session = container.resolve(AsyncSession)
            await session.execute(...)

        # After (v0.1.0-beta.8)
        from zcore.kernel import background_task
        from zcore import Inject

        @background_task
        async def process_task(task_id: uuid.UUID, service: Inject[TaskService]):
            # Automatically runs in an isolated IoC scope & independent AsyncSession
            await service.process(task_id)
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion id="v0.1.0-beta.7" title="v0.1.0-beta.7 — August 16, 2026 🚀">
    Welcome to **v0.1.0-beta.7** of the ZCore Framework! 🚀

    This is one of the most substantial and transformative releases in ZCore's history. Guided by our foundational philosophy of &#x2A;*Engineered Simplicity (KISS)** and **Clean Architecture**, `v0.1.0-beta.7` eliminates generic boilerplate across data layers, introduces a complete asynchronous testing framework with transaction rollback guarantees, unifies request-scoped context state and security primitives, and introduces event-driven subscriber mechanics.

    ### 🚀 Core Features & Architectural Advancements [#-core-features--architectural-advancements-3]

    #### 1. 🧪 Comprehensive Async Testing Infrastructure (`zcore.testing`) [#1--comprehensive-async-testing-infrastructure-zcoretesting]

    Writing integration and unit tests for database-backed FastAPI services is now effortless and boilerplate-free:

    * **`ZTestFixture` Engine:** Modular async fixtures including `ContainerSandbox` (snapshots and restores IoC state), `DatabaseRollback` (wraps tests in isolated savepoint transactions), `UserContext` (injects user identities and security scopes), and `AppLifespan` (manages FastAPI lifecycle hooks).
    * **`ZTestClient`:** An asynchronous test client extending `httpx.AsyncClient` that coordinates test sandboxes with zero manual mock setups.
    * **`BaseZTest`:** An abstract class providing clean, class-based test suites using an intuitive `async with self.run(use_db=True)` context manager.
    * **CLI Test Generator:** Run `zc startapp <domain> --test` to scaffold ready-to-run test files automatically.

    #### 2. 🌐 Centralized Request Context & Scopes (`ZContext` & `ctx`) [#2--centralized-request-context--scopes-zcontext--ctx]

    Replaced fragmented context functions with a unified, high-performance, contextvar-isolated `ZContext` class:

    * **Global `ctx` Singleton:** Access context variables anywhere in the request lifecycle via strongly-typed properties (`ctx.user_id`, `ctx.restricted_fields`, `ctx.action`).
    * **`ctx.scope()` Context Manager:** Create isolated, temporary context overrides for background tasks, cron jobs, or test sandboxing.
    * **Action-Aware Routing:** Route operations (`create`, `view`, `update`, `delete`) are automatically detected and injected into `ZContext`, driving action-scoped field pruning in `Zchema`.

    #### 3. 🧹 Streamlined Data Layer Generics & Dynamic Hook Propagation [#3--streamlined-data-layer-generics--dynamic-hook-propagation]

    We eliminated the verbose schema generic clutter from data access layers:

    * **Single Generic Parameter:** `BaseRepository[Model]` and `BaseService[Model]` now only require the database model type.
    * **Dynamic Criterion & Query Filters:** Repository `get()`, `exist()`, and `get_list()` now accept arbitrary positional SQLAlchemy binary expressions (`*criterion`) and keyword arguments (`**filters`) consolidated via `_apply_filters`.
    * **Dynamic Pre-Hook Data Injection:** Service `pre_create` and `pre_update` lifecycle hooks can now return a dictionary (`Optional[dict[str, Any]]`) that automatically merges context-derived data (e.g., `user_id` from `ctx`) directly into repository database flushes.

    #### 4. 🔐 Consolidated Security & Generic Authentication (`BaseAuth`) [#4--consolidated-security--generic-authentication-baseauth]

    * **Unified `Security` Class:** Merged scattered hashing and JWT logic into a centralized `Security` coordinator supporting Argon2id password hashing, PyJWT token encoding/decoding, and cryptographic token generation.
    * **Template Method `BaseAuth`:** A generic authentication dependency that extracts and validates tokens, integrates with `BaseCache` for user-lookup caching, and automatically binds the resolved user to `ZContext`.
    * **Dynamic Scope Resolution:** `HasScopes` permission dependencies now evaluate scopes dynamically from `ZContext` (`ctx.get("scopes")`) with automatic type coercion for lists, tuples, and sets.

    #### 5. ⚡ Modern Constructor Auto-Wiring (`Inject[T]`) [#5--modern-constructor-auto-wiring-injectt]

    * Converted `Inject` into a subscriptable type marker (`Inject[T]`), which seamlessly maps to `Annotated[T, Depends(Injector(T))]`.
    * Allows clean, idiomatic constructor type-hinting in services and routes without importing or declaring raw FastAPI `Depends()` chains.

    #### 6. 📡 Event-Driven Architecture (`@on_event`) & SQL Diagnostics [#6--event-driven-architecture-on_event--sql-diagnostics]

    * **`@on_event` Decorator:** Mark service methods as event subscribers with automatic container-backed resolution via `EventDispatcher.register_listeners()`.
    * **SQL Execution Telemetry:** Built-in connection interceptors log SQL execution durations in milliseconds and filter out Postgres system catalog query noise.
    * **Static Route Protection:** Added `_sort_routes()` to ensure parameterized paths (e.g., `/{id:uuid}`) never shadow sibling static endpoints like `/search`.

    ***

    ### 🛠️ CLI & Subsystem Enhancements [#️-cli--subsystem-enhancements]

    * **`zc genenv`:** Introspects registered Pydantic `Settings` classes and scaffolds a clean `.env.example` file automatically.
    * **`Settings` Simplification:** Renamed `ZCoreCoreSettings` to `Settings` and replaced `ENVIRONMENT` strings with boolean `DEBUG` flags.
    * **`ZCoreJSONResponse`:** Replaces standard JSON responses to safely serialize complex types (UUIDs, ISO datetimes, Decimals).
    * **Standalone Documentation Portal:** Decoupled documentation from the core repository into the official standalone repository [Baseryn/zcore-docs](https://baseryn.github.io/zcore-docs/).

    ***

    ### ⚠️ Breaking Changes & Migration Guide [#️-breaking-changes--migration-guide-3]

    <Tabs items="['1. Generics Simplification', '2. Settings & Debug', '3. Inject[T] Syntax', '4. Security Coordinator']">
      <Tab value="1. Generics Simplification">
        You no longer need to pass schema types to `BaseRepository` or `BaseService`.

        ```python
        # Before (v0.1.0-beta.6)
        class TaskRepo(BaseRepository[Task, TaskCreate, TaskUpdate]):
            ...

        class TaskService(BaseService[Task, TaskCreate, TaskUpdate]):
            ...

        # After (v0.1.0-beta.7)
        class TaskRepo(BaseRepository[Task]):
            ...

        class TaskService(BaseService[Task]):
            ...
        ```
      </Tab>

      <Tab value="2. Settings & Debug">
        The settings class name has been simplified to `Settings`, and `ENVIRONMENT` is replaced by the boolean `DEBUG` flag.

        ```python
        # Before (v0.1.0-beta.6)
        from zcore import ZCoreCoreSettings

        class AppSettings(ZCoreCoreSettings):
            ENVIRONMENT: str = "development"

        # After (v0.1.0-beta.7)
        from zcore import Settings

        class AppSettings(Settings):
            DEBUG: bool = True
        ```
      </Tab>

      <Tab value="3. Inject[T] Syntax">
        Update route handlers and constructors to use `Inject[T]` type annotations instead of default values.

        ```python
        # Before (v0.1.0-beta.6)
        @router.post("/tasks")
        async def create_task(service: TaskService = Inject(TaskService)):
            ...

        # After (v0.1.0-beta.7)
        from zcore import Inject

        @router.post("/tasks")
        async def create_task(service: Inject[TaskService]):
            ...
        ```
      </Tab>

      <Tab value="4. Security Coordinator">
        Scattered imports from `zcore.security.hashing` and `zcore.security.jwt` are merged under `Security`.

        ```python
        # Before (v0.1.0-beta.6)
        from zcore.security.hashing import hash_password, verify_password
        from zcore.security.jwt import create_access_token

        # After (v0.1.0-beta.7)
        from zcore import Security

        hashed = Security.hash_password(raw_password)
        token = Security.create_jwt({"sub": str(user_id)})
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion id="v0.1.0-beta.6" title="v0.1.0-beta.6 — July 16, 2026 🚀">
    Welcome to **v0.1.0-beta.6** of the ZCore Framework! 🚀

    This release represents a significant step forward in robust data handling, security validation, and comprehensive project governance. Following our core philosophy of &#x2A;*Engineered Simplicity (KISS)**, we addressed critical edge-cases in timezone serialization, refined schema semantics to align with Domain-Driven Design (DDD), and overhauled repository testing pipelines.

    ### 🚀 Core Architectural Refinements [#-core-architectural-refinements]

    #### 🌐 Decoupled Presentation Layer Domain (`__model__`) [#-decoupled-presentation-layer-domain-__model__]

    In `Zchema` (`zcore/web/projection.py`), the class attribute `__db_name__&#x60; has been officially deprecated in favor of a more semantic and architecturally accurate attribute: &#x2A;*`__model__`**.

    * **The Rationale:** Schemas (DTOs) belong purely to the presentation layer and should not be tightly coupled to database nomenclature by name.
    * **The Alignment:** All internal recursion, pruning logics, and CLI code-generation templates have been fully migrated to use `__model__` for strict domain binding.

    ```python
    # Before (beta.5)
    class TaskResponse(Zchema):
        __db_name__ = "tasks"

    # After (beta.6+)
    class TaskResponse(Zchema):
        __model__ = "tasks"
    ```

    #### 🔌 Lazy-Loaded Root Namespace Imports [#-lazy-loaded-root-namespace-imports]

    Developers can now import highly utilized core framework constructs directly from the root namespace:

    ```python
    from zcore import RouteKey, Plugin, on_event, EventDispatcher
    ```

    * Implemented dynamic, lazy-loaded import resolutions within `src/zcore/__init__.py` using Python's dynamic `__getattr__` module block, ensuring zero performance or startup overhead during initialization.

    ### 🐛 Data Integrity & Security Fixes [#-data-integrity--security-fixes]

    #### 🔢 Precision-Preserving Decimal Serialization [#-precision-preserving-decimal-serialization]

    Changed JSON encoding for `Decimal` instances from standard floating-point (`float`) to string (`str`) inside `CustomJSONEncoder`.

    * **The Fix:** Converting Decimals to floats introduces floating-point arithmetic inaccuracies and precision loss right before data is dispatched to clients.
    * **The Result:** Preserves exact decimal precision, establishing the industry standard for financial calculations and highly accurate APIs.

    #### 🗺️ Timezone-Aware Pagination Cursors [#️-timezone-aware-pagination-cursors]

    Refactored the `_encode_cursor` method inside `zcore/db/pagination.py` to intercept naive datetime instances.

    * Naive datetimes are now explicitly normalized to UTC, and timezone-aware instances are converted safely to UTC before being base64 encoded into cursor payloads.
    * Resolves cursor misalignment and timezone-awareness dropouts in geographically distributed deployments.

    #### 🛡️ Robust Security Path Normalization [#️-robust-security-path-normalization]

    Eliminated overzealous string prefix stripping in path resolutions inside `SearchEngine` and `Zchema`.

    * **The Fix:** Previously, `path.replace("resource.", "")` acted globally and could corrupt legitimate nested relation paths (e.g., `project.resource.status` incorrectly mutated to `project.status`).
    * **The Result:** Replaced with a strict, localized prefix-matching resolution to secure nested relationships without false positives during access checks.

    #### ⏱️ Native ISO-8601 Datetime Parsing [#️-native-iso-8601-datetime-parsing]

    Simplified UTC datetime coercion in `zcore/db/search.py` by removing legacy `.replace("Z", "+00:00")` string manipulation workarounds. The coercion layer now fully relies on native, optimized Python 3.11+ `datetime.fromisoformat()` UTC suffix parsing out-of-the-box.

    ### ⚙️ Automated CI/CD & Project Governance [#️-automated-cicd--project-governance]

    * **GitHub Actions Test Suite (CI):** Deployed automated pull-request code quality gates using `ruff check` linting and the `hatch` test suite (blocking merges unless all status checks pass).
    * **Standardized Issue Templates:** Added customized Bug Report and Feature Request templates to capture environmental diagnostics (DB engines, SQLAlchemy, and Redis versions).
    * **Automated Semantic Changelogs:** Configured `.github/release.yml` to automatically categorize pull requests under semantic sections based on metadata tags.
    * **Community Guidelines:** Introduced formal `CONTRIBUTING.md` and `SECURITY.md` files to clarify local setup steps and private vulnerability reporting workflows.
  </Accordion>

  <Accordion id="v0.1.0-beta.5" title="v0.1.0-beta.5 — July 13, 2026 🚀">
    Welcome to **v0.1.0-beta.5** of the ZCore Framework! This release centers on &#x2A;*Engineered Simplicity (KISS)**. We deprecated complex, reflection-based configuration variables and brittle runtime hacks, replacing them with standard Object-Oriented patterns, native Pydantic V2 integrations, and cleaner dependency structures.

    ### 🚀 Core Features & Enhancements [#-core-features--enhancements]

    #### 🛡️ Unified Schema Security (`Zchema`) [#️-unified-schema-security-zchema]

    Completely overhauled data pruning and shielding mechanisms. Previously, data masking was handled globally in the web layer via a generic `resource.*` prefix, which was prone to namespace collisions.

    * **The `Zchema` Class:** All schemas now inherit from `Zchema` (extending Pydantic `BaseModel`).
    * **Domain-Specific Namespacing:** Define a class-level `__db_name__` (migrated to `__model__` in beta.6).
    * **3-Tier Protection:** Dynamic Schemas (`?schema=true`), Input Filtering (Anti-Mass Assignment), and Response Serialization Pruning.

    #### 🚦 Template Method Service Hooks [#-template-method-service-hooks]

    To guarantee that business-critical `pre_` and `post_` lifecycle hooks and transaction boundaries are never skipped, we separated orchestration from execution:

    * **Custom Database Operations:** Developers now override dedicated `on_create`, `on_update`, and `on_delete` callback hooks instead of overriding the public `create()` orchestrator.
    * The orchestrator guarantees that validation, hooks, and transaction commits (`_safe_commit`) execute in the exact correct order.

    #### 🔗 FastAPI-Native Route Dependencies [#-fastapi-native-route-dependencies]

    Conceptually renamed the routing security layer from "Permissions" to "Dependencies", matching FastAPI's core design:

    * Removed 8 static class variables (`DEFAULT_PERMISSIONS`, `POST_PERMISSIONS`, etc.).
    * Introduced a single, elegant factory method: `get_route_dependencies(self, route_key: RouteKey, action: str) -> list[Any]`.
    * Developers can now use standard Python inheritance and `super()` to customize specific endpoints while maintaining default scopes for others.

    #### 📦 Robust Modular Monolith Imports [#-robust-modular-monolith-imports]

    Resolved `ModuleNotFoundError` across nested modules (such as importing from `shared/` within `modules/identity/`) using a 3-layer approach across CLI, Runtime, and IDE configuration.

    ### ⚠️ Breaking Changes & Migration Guide [#️-breaking-changes--migration-guide-4]

    <Tabs items="['1. Schema Base Class', '2. Router Dependencies', '3. Service Overrides']">
      <Tab value="1. Schema Base Class">
        Replace `BaseModel` with `Zchema` and define your domain identifier on schemas:

        ```python
        # Before (v0.1.0-beta.4)
        from pydantic import BaseModel

        class UserResponse(BaseModel):
            email: str

        # After (v0.1.0-beta.5)
        from zcore import Zchema

        class UserResponse(Zchema):
            __db_name__ = "user"  # Note: renamed to __model__ in beta.6
            email: str
        ```
      </Tab>

      <Tab value="2. Router Dependencies">
        Static permission variables have been deprecated. Move custom security logic to the `get_route_dependencies` method:

        ```python
        # Before (v0.1.0-beta.4)
        class ProductRouter(BaseRouter):
            DEFAULT_PERMISSIONS = "AUTO"
            DELETE_PERMISSIONS = [AdminOnly()]

        # After (v0.1.0-beta.5)
        class ProductRouter(BaseRouter):
            def get_route_dependencies(self, route_key: RouteKey, action: str):
                if route_key == RouteKey.DELETE:
                    return [AdminOnly()]
                return super().get_route_dependencies(route_key, action)
        ```
      </Tab>

      <Tab value="3. Service Overrides">
        If you previously overrode `create`, `update`, or `delete` directly, move that database logic to the corresponding `on_*` execution hook:

        ```python
        # Before (v0.1.0-beta.4)
        async def create(self, schema: ProductCreate):
            return await self.repository.create(schema)

        # After (v0.1.0-beta.5)
        async def on_create(self, schema: ProductCreate) -> Product:
            return await self.repository.create(schema)
        ```
      </Tab>
    </Tabs>

    ### 🐛 Bug Fixes & Refactoring [#-bug-fixes--refactoring]

    * Fixed `ModuleNotFoundError` in subfolders of modular directory layouts (#53).
    * Corrected `IoCContainer` resolution for `Annotated` type hints and manual request-scope instance registration (#48).
    * Simplified `ZCoreJSONResponse` and removed `ResponseProjector` to avoid redundant serialization overhead.
  </Accordion>

  <Accordion id="v0.1.0-beta.4" title="v0.1.0-beta.4 (DI Overhaul & Architecture Refinement) — July 07, 2026 🚀">
    Welcome to **v0.1.0-beta.4** of the ZCore Framework! This version introduces critical architectural refinements, improves ASGI/Async performance by eliminating thread-pool bottlenecks, and simplifies developer experience (DX) for database-backed microservices.

    ### 🚀 Key Improvements & Features [#-key-improvements--features]

    #### 1. Complete DI Overhaul & Web-Decoupled Scoping [#1-complete-di-overhaul--web-decoupled-scoping]

    The dependency injection (DI) layer has been restructured to strictly adhere to Clean Architecture:

    * **ASGI Middleware Session Scoping:** The lifetime of the `AsyncSession` database connection is now managed at the ASGI middleware level (`ScopedDependencyMiddleware`). This guarantees that a request-scoped database session is initialized and registered in the DI container before FastAPI resolves routing dependency graphs.
    * **Annotated Type Unpacking:** The custom DI container (`_auto_wire`) supports Python's native `typing.Annotated` patterns, gracefully extracting the core class definition.
    * **High-Performance Async Injector:** Modified `Injector.__call__` to be asynchronous (`async def`), evaluating dependencies directly on the main event loop.

    #### 2. Base Query Hook & Extension Layer [#2-base-query-hook--extension-layer]

    Introduced structured hook methods in the base repository layer to allow granular control over queries:

    * `_get_base_query()`: Reusable hook returning the default `Select` statement.
    * Integrated the base query pipeline seamlessly with the `SearchEngine` dynamic filter compiler.

    #### 3. One-Command Database Bootstrapping [#3-one-command-database-bootstrapping]

    Running `zc init <project_name>` through the ZCore CLI automatically creates the default SQLite database file (`zcore_dev.db`) on the filesystem.

    #### 4. Dependency Management [#4-dependency-management]

    Added `uvicorn` as a primary core dependency inside `pyproject.toml` to guarantee `zc run` functions correctly out of the box.

    ### ⚠️ Breaking Changes & Migration Guide [#️-breaking-changes--migration-guide-5]

    <Tabs items="['1. Clean Constructor Parameters', '2. Inject vs Depends']">
      <Tab value="1. Clean Constructor Parameters">
        You no longer need to write `= Inject(...)` default values or rely on `SessionDep` in repository/service constructors. Use clean, native Python type hints:

        ```python
        # Before (v0.1.0-beta.3)
        class UsersRepository(BaseRepository):
            def __init__(self, db: SessionDep):
                super().__init__(model=Users, db=db)

        class UsersService(BaseService):
            def __init__(self, repository: UsersRepository = Inject(UsersRepository)):
                super().__init__(model=Users, repository=repository)

        # After (v0.1.0-beta.4)
        class UsersRepository(BaseRepository):
            def __init__(self, db: AsyncSession):  # Standard AsyncSession
                super().__init__(model=Users, db=db)

        class UsersService(BaseService):
            def __init__(self, repository: UsersRepository):  # Pure Python, no defaults
                super().__init__(model=Users, repository=repository)
        ```
      </Tab>

      <Tab value="2. Inject vs Depends">
        When writing custom FastAPI dependencies (e.g., `get_current_user`), ensure you use `Inject[T]` instead of `Depends(T)` so that the container handles recursive resolution properly:

        ```python
        # Custom Route Dependency Example
        async def get_current_user(
            token: str = Depends(oauth2_scheme),
            service: Inject[UsersService]
        ) -> Users:
            ...
        ```
      </Tab>
    </Tabs>
  </Accordion>
</Accordions>


# Comparisons (/docs/comparisons)





Choosing the right architectural pattern directly impacts the maintainability and velocity of your engineering team. ZCore is not designed to be a universal winner; it is a composable, opt-in layer designed for specific scaling patterns.

This page provides an objective, technical comparison to help you determine which paradigm fits your system architecture.

<Callout type="info" emoji="⚖️">
  **Evaluation Rule:** Every tool evaluated below is highly optimized for its specific target workflow. Choose the tool that aligns with your scaling requirements, rather than adopting abstractions prematurely.
</Callout>

***

## ZCore vs. Plain FastAPI [#zcore-vs-plain-fastapi]

ZCore does not replace FastAPI; it runs alongside it to address common boilerplate patterns.

| Architectural Decision       | Plain FastAPI                                           | ZCore                                                                                                                                                    |
| ---------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Underlying Engine**        | Standard ASGI Web Framework                             | Standard ASGI Web Framework + Composable Utilities                                                                                                       |
| **Design Philosophy**        | Minimalist, highly explicit                             | Minimalist, with optional architectural abstractions                                                                                                     |
| **Data Access (CRUD)**       | Manual SQL or ORM execution per route                   | Automated inheritance via `BaseRepository` (with dialect-aware `RETURNING` fallback, soft-delete awareness, restoration, and forced hard-deletes)        |
| **Dependency Injection**     | Nested, parameter-level `Depends()` chains              | Clean constructor auto-wiring via `Inject[T]` and `IoCContainer`                                                                                         |
| **Field-Level Security**     | Multiple separate Pydantic output schemas               | Dynamic, role-based field pruning inside a single `Zchema`                                                                                               |
| **Transactional Boundaries** | Manual `session.commit()` execution                     | Context-manager encapsulation via `UnitOfWork` (post-commit events)                                                                                      |
| **Background Routines**      | Manual session management (risks closed session errors) | `@background_task` / `background_scope` with auto-wired DI, session leak warnings, and fresh sessions                                                    |
| **Soft Delete**              | Manual query filtering per route                        | Built-in `SoftDeleteMixin` with timezone-aware timestamps, automatic `scope_query`, atomic batch restore, and `?force=true` query support                |
| **Error Normalization**      | Inconsistent error schemas (raw 422 arrays, HTML 500s)  | Unified `ResponseWrapper[None]` with Pydantic dot-path sanitization and debug-gated 500 tracebacks via `register_exception_handlers`                     |
| **Structured Logging**       | Manual configuration                                    | Non-intrusive logging with tri-split loggers (`muted`, `passthrough`, `intercept`), status-aware exception levels (\<500 DEBUG), and slow-query tracking |
| **Module Organization**      | Undefined (User-driven)                                 | Structured, topologically sorted domain modules (`Plugin`)                                                                                               |
| **CLI & Scaffolding**        | Manual file setup                                       | Interactive TUI (`zc`) with cascading config hierarchy (`CLI > .env > defaults`), transparent Uvicorn passthrough, and multi-DB driver support           |

### When to choose plain FastAPI [#when-to-choose-plain-fastapi]

* Your application has a small domain model (1–3 tables) with simple, unique queries.
* You prefer explicit, inline code and want to avoid introducing any class-level abstractions.
* You have no requirements for complex, role-based data masking or dynamic schema generation.
* You are prototyping and want zero architectural layers between your database sessions and routes.

### When ZCore adds value [#when-zcore-adds-value]

* Your application is expanding, and you are writing identical CRUD and bulk mutation operations for multiple models.
* You need to dynamically prune sensitive attributes (like `email`, `salary`, or `internal_notes`) from responses based on active scopes, without maintaining multiple duplicate Pydantic models.
* You must coordinate multiple database writes atomically while ensuring that side-effect events only publish once the database commit succeeds.
* You want clean, type-hinted constructor dependency injection without nested `Depends()` parameter lists.

```python
# You can mix both paradigms seamlessly in the same file
from fastapi import APIRouter
from zcore import BaseRepository, Inject, SessionDep
from .models import Task

class TaskRepo(BaseRepository[Task]):
    pass  # This route layer uses ZCore's BaseRepository

router = APIRouter()

# This route remains a standard, native FastAPI controller
# SessionDep is ZCore's Annotated[AsyncSession, Depends(get_db)]
@router.get("/health")
async def health_check(db: SessionDep):
    return {"status": "healthy"}
```

***

## ZCore vs. Django / Django REST Framework [#zcore-vs-django--django-rest-framework]

These frameworks solve fundamentally different architectural problems. Django is a batteries-included monolith, whereas ZCore is a composable architectural extension for FastAPI.

| Feature Boundary           | Django + DRF                                              | ZCore                                                                      |
| -------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------- |
| **Architecture Style**     | Monolithic, opinionated                                   | Composable, modular, opt-in layers                                         |
| **Asynchronous Execution** | Historically synchronous, with partial async adaptations  | Native, fully asynchronous from the ground up (FastAPI + SQLAlchemy Async) |
| **Data Mapping (ORM)**     | Django ORM (tightly coupled and required)                 | Standard SQLAlchemy 2.0 Async (fully decoupled)                            |
| **Administration Portal**  | Built-in, automated admin panel                           | Projection-driven dynamic dashboard (on the roadmap)                       |
| **User Authentication**    | Built-in authentication model, session management, and UI | Decoupled `BaseAuth` token decoding and `ZContext` injection               |
| **Database Migrations**    | Built-in migration engine                                 | Native integration with Alembic                                            |
| **API Abstractions**       | Class-Based Views (CBVs) and Serializers                  | Standard Pydantic models and functional FastAPI controllers                |

### When Django is the optimal choice [#when-django-is-the-optimal-choice]

* You are building a standard, monolithic web application (API + admin portal + server-rendered HTML templates).
* Your project requires a fully-featured, out-of-the-box admin dashboard immediately.
* Your team is highly productive within the Django ecosystem and prefers built-in, non-negotiable standards.
* You do not require high-performance, fully asynchronous execution across the entire transaction lifecycle.

### When ZCore is the optimal choice [#when-zcore-is-the-optimal-choice]

* You are building an API-first service optimized for high-throughput, async operation.
* You want to leverage SQLAlchemy 2.0's advanced query capabilities directly without ORM-level lock-in.
* You prefer composing your own modular abstractions over inheriting a monolithic framework.
* You want to avoid class-based views in favor of explicit, lightweight FastAPI endpoints with automated schema projection.

***

## ZCore vs. FastAPI-Users [#zcore-vs-fastapi-users]

`FastAPI-Users` is a dedicated library for comprehensive user authentication, while ZCore's `BaseAuth` is an abstract helper designed to bind authentication state to the active context.

| Feature                 | FastAPI-Users                                            | ZCore (`BaseAuth`)                                                                                      |
| ----------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **Primary Focus**       | Complete out-of-the-box user registration and management | Contextual authentication and scope-based security binding                                              |
| **Auth Flows**          | Registration, verification, password reset, OAuth logins | JWT decoding, Argon2id hashing, and optional authentication (`auto_error=False`)                        |
| **Password Hashing**    | Typically Bcrypt                                         | Argon2id (Default, high-entropy PHC winner)                                                             |
| **User Schema & Model** | Enforced user and database schema templates              | Bring Your Own User Model (BYOUM) matching `UserProtocol` (supports arbitrary ID types: int, str, UUID) |
| **Database Coupling**   | Tightly coupled to database adapters (SQLAlchemy/Beanie) | Completely decoupled; relies on standard repository interfaces                                          |
| **Scope of Utilities**  | Authentication only                                      | Full architectural stack (Repository, Service, Zchema, UoW, CLI)                                        |

### When FastAPI-Users is better [#when-fastapi-users-is-better]

* You need a complete, turn-key authentication system, including email verification, password reset, and registration endpoints, with minimal manual coding.
* You do not want to design or write user database structures.

### When ZCore's BaseAuth is better [#when-zcores-baseauth-is-better]

* You already have an established user model and database strategy and simply need to integrate JWT claims with your request pipeline.
* You want to seamlessly bind user permissions to `ZContext.restricted_fields` to drive ZCore's automated `Zchema` field-pruning serialization.
* You prefer custom, lightweight authentication callbacks over relying on a third-party user-management engine.

***

## ZCore vs. Standalone SQLAlchemy 2.0 [#zcore-vs-standalone-sqlalchemy-20]

ZCore does not replace SQLAlchemy; it builds on top of it. However, it is important to understand the level of abstraction introduced by `BaseRepository` and `SearchEngine`.

| Query Feature                     | Standalone SQLAlchemy                        | ZCore's `BaseRepository`                                                                                                                             |
| --------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Data Retrieval**                | `session.execute(select(Model).where(...))`  | `repo.get(id=id)` or `repo.get(Model.field == val)`                                                                                                  |
| **Mutations (Update/Delete)**     | Requires query execution by primary key      | `repo.update()`, `repo.delete(force=...)`, `repo.restore()`, `repo.restore_multi()` (accepts model instance or ID)                                   |
| **Bulk Insert / Update / Delete** | Manual `insert().values().returning()` setup | `repo.create_multi()`, `repo.update_multi()`, `repo.delete_multi(force=...)` with dialect-aware `RETURNING` fallback                                 |
| **Soft Delete**                   | Manual filter per query                      | Inherit `SoftDeleteMixin` for automatic query scoping with timezone support                                                                          |
| **Keyset Pagination**             | Written manually per query                   | Built-in via `CursorPagination` and `CursorParams` (Base64 encoded)                                                                                  |
| **Dynamic Search**                | Hand-crafted filter parsing                  | Automated SQL compilation from `SearchRequest` payloads                                                                                              |
| **Search Operators**              | Manual operator translation                  | Built-in comparisons (`eq`, `gt`, `lt`, `like`), inverted operators (`not_like`, `not_in`, `not_between`, `is_not_null`), and boolean `not` grouping |
| **Search Security**               | Manual validation required                   | Configurable `__max_search_depth__` and restricted field checking                                                                                    |
| **Execution Hooks**               | Hand-written or mapped via event listeners   | Overridable lifecycle hooks: `pre_create`, `pre_update`, `pre_delete` (with `force`), `pre_restore`, `post_restore` (single & bulk)                  |

<Callout type="info" emoji="🔄">
  **No Obscurity:** `BaseRepository` does not wrap or obscure SQLAlchemy sessions. It executes standard async SQLAlchemy statements internally. You can override any method to write custom SQL queries whenever default patterns fall short.
</Callout>

***

## Where ZCore Introduces Trade-offs [#where-zcore-introduces-trade-offs]

A balanced architecture means acknowledging that every abstraction carries a cost:

| ZCore Component      | Introduced Overhead                                                         | When the abstraction is unnecessary                                                      |
| -------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| **`BaseRepository`** | Introduces an extra class layer per model.                                  | Your database queries are unique, highly custom, or rarely repeat.                       |
| **`BaseService`**    | Requires learning the pre/post-action hook lifecycle.                       | Your business logic is simple enough to reside cleanly within route controllers.         |
| **`Zchema`**         | Requires model metadata configuration and scope mappings.                   | Your API does not serve different user roles or have field-level visibility constraints. |
| **`UnitOfWork`**     | Introduces context manager encapsulation for database sessions.             | Your API writes only to single tables within single requests.                            |
| **`BaseRouter`**     | Generates 8 standard endpoints which must be configured or excluded.        | You only need 1 or 2 specific endpoints for a given model.                               |
| **`Inject[T]`**      | Requires understanding container lifecycles (Singleton, Scoped, Transient). | Standard FastAPI `Depends()` parameters meet your modular requirements.                  |


# Quick Start (/docs/quick-start)





**Every step below is optional.** ZCore is designed to be an incremental, opt-in companion for FastAPI. This guide demonstrates the fastest integration path. Feel free to skip any component that does not suit your project's architectural requirements.

***

## 1. Install [#1-install]

```bash
pip install fastapi-zcore-framework[all]
```

ZCore extends FastAPI by providing modular helper patterns — it does not hide or replace standard FastAPI structures.

***

## 2. Scaffold a Project [#2-scaffold-a-project]

Use the built-in interactive CLI tool to quickly bootstrap a clean, modular starting structure:

```bash
# Interactive setup (prompts for DB driver, uv/pip, and virtual environment)
zc init my_api && cd my_api

# Or non-interactive default (SQLite driver)
# zc init my_api --db sqlite -y && cd my_api
```

This command automatically generates a production-ready starting layout, sets up an isolated `.venv`, and creates a fresh cryptographic `SECRET_KEY`:

<Files>
  <Folder name="my_api">
    <File name="main.py" />

    <File name=".env" />

    <File name="requirements.txt" />

    <File name=".gitignore" />

    <File name="zcore_dev.db" />
  </Folder>
</Files>

`main.py` is a standard FastAPI entrypoint. ZCore does not introduce hidden magic; you retain absolute control over the FastAPI application instance.

***

## 3. Create an App Module (Domain) [#3-create-an-app-module-domain]

ZCore projects are organized as decoupled, modular domains. Let's scaffold a `tasks` domain:

```bash
zc startapp tasks --template
```

This command generates a structured, independent directory layout for your domain directly in the project directory:

<Files>
  <Folder name="my_api">
    <Folder name="tasks">
      <File name="__init__.py" />

      <File name="models.py" />

      <File name="schemas.py" />

      <File name="repositories.py" />

      <File name="services.py" />

      <File name="routers.py" />

      <File name="plugin.py" />

      <File name="test_tasks.py" />
    </Folder>

    <File name="main.py" />

    <File name=".env" />

    <File name="requirements.txt" />

    <File name=".gitignore" />
  </Folder>
</Files>

***

## 4. Define a Model & Schemas [#4-define-a-model--schemas]

Open the auto-generated `tasks/models.py` file and customize your standard SQLAlchemy 2.0 model:

```python
# tasks/models.py
import uuid
from sqlalchemy.orm import Mapped, mapped_column
from zcore import Base

class Task(Base):
    __tablename__ = "tasks"
    
    id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
    title: Mapped[str]
    is_completed: Mapped[bool] = mapped_column(default=False)
```

Let's also define the basic schemas in `tasks/schemas.py`:

```python
# tasks/schemas.py
import uuid
from pydantic import ConfigDict
from zcore import Zchema

class TaskBase(Zchema):
    __model__ = "tasks"
    title: str
    is_completed: bool = False

class TaskCreate(TaskBase):
    pass

class TaskUpdate(TaskBase):
    title: str | None = None
    is_completed: bool | None = None

class TaskResponse(TaskBase):
    id: uuid.UUID
    
    model_config = ConfigDict(from_attributes=True)
```

At this stage, you have a normal declarative model. You can stop right here and write raw SQLAlchemy queries using `AsyncSession`.
**Or** read on to see how ZCore can optionally reduce your boilerplate.

<Callout type="info" emoji="💡">
  **Tip:** Don't forget to include your domain's router inside the plugin's `setup` method:

  ```python
  # tasks/plugin.py
  from fastapi import FastAPI
  from zcore import Plugin
  from .routers import router_instance

  class TaskPlugin(Plugin):
      name = "tasks"
      version = "0.1.0"
      dependencies = []

      def setup(self, app: FastAPI) -> None:
          app.include_router(router_instance.router)
  ```
</Callout>

***

## 5. Register the Plugin [#5-register-the-plugin]

For the `Kernel` to recognize your domain and attach its routes to the FastAPI application, register the generated `TaskPlugin` inside your `main.py` file.

Open `main.py` and register the plugin before `kernel.setup(app)`:

```python
# main.py
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parent))

from fastapi import FastAPI
from zcore import (
    Kernel,
    db_manager,
    register_db_event_dispatcher,
    register_exception_handlers,
    settings,
)
from zcore.logging import setup_logging
from zcore.web import RequestLogMiddleware, ScopedDependencyMiddleware

# Import your domain plugin
from tasks.plugin import TaskPlugin  # <--- ADD THIS

setup_logging()

# Initialize Database Manager using structured settings
db_manager.init_app(config=settings.DATABASE)

kernel = Kernel()
register_db_event_dispatcher(kernel.dispatcher)

# Register the domain plugin
kernel.add_plugin(TaskPlugin())  # <--- ADD THIS

app = FastAPI(
    title=settings.PROJECT_NAME,
    lifespan=kernel.lifespan
)

kernel.setup(app)

app.add_middleware(RequestLogMiddleware)
app.add_middleware(ScopedDependencyMiddleware)

register_exception_handlers(app)

@app.get("/")
async def root():
    return {
        "status": "healthy",
        "framework": "ZCore",
        "version": "0.1.0-rc.2",
        "debug": settings.DEBUG
    }
```

***

## 6. Run the Server [#6-run-the-server]

Start the development server with live reload and automatic environment resolution:

```bash
zc run
```

Your API is live at &#x2A;*[http://127.0.0.1:8000](http://127.0.0.1:8000)**.

If you navigate to `http://127.0.0.1:8000/docs`, you will see the standard FastAPI Swagger UI. Let's incrementally adopt ZCore features — **only the ones you actually need**.

***

## Now Add ZCore (Optional) [#now-add-zcore-optional]

Each layer is decoupled. You can pick any single component without being forced to adopt the rest.

<Tabs items="['BaseRouter', 'BaseRepository', 'BaseService', 'Zchema', 'UnitOfWork', 'Skip all']">
  <Tab value="BaseRouter">
    ### Add Router — Auto-generated, secure endpoints [#add-router--auto-generated-secure-endpoints]

    <Callout type="info" emoji="🔴">
      **Orchestrated.** Requires a Service and Repository configuration to auto-scaffold endpoints.
    </Callout>

    Open `tasks/routers.py` and define your router configuration:

    ```python
    # tasks/routers.py
    from zcore import BaseRouter
    from .models import Task
    from .schemas import TaskCreate, TaskResponse, TaskUpdate
    from .services import TaskService

    class TaskRouter(BaseRouter[TaskCreate, TaskUpdate]):
        model = Task
        create_schema = TaskCreate
        update_schema = TaskUpdate
        schema_out = TaskResponse
        service = TaskService
        
        prefix = "/tasks"
        tags = ["Tasks"]

    router_instance = TaskRouter()
    ```

    Now, ensure the router is included in `tasks/plugin.py`:

    ```python
    # tasks/plugin.py
    from fastapi import FastAPI
    from zcore import Plugin
    from .routers import router_instance

    class TaskPlugin(Plugin):
        name = "tasks"
        version = "0.1.0"
        dependencies = []

        def setup(self, app: FastAPI) -> None:
            app.include_router(router_instance.router)

        async def before_startup(self) -> None:
            pass

        async def on_startup(self) -> None:
            pass

        async def after_startup(self) -> None:
            pass

        async def on_shutdown(self) -> None:
            pass
    ```

    This single class scaffolds 8 secure endpoints out-of-the-box: `POST /`, `GET /{id}`, `GET /` (with pagination), `POST /search`, `POST /lookup`, `PUT /{id}`, `PATCH /{id}`, and `DELETE /{id}` (with optional `?force=true`).

    <Callout type="info" emoji="−">
      **Or don't.** Write standard `@router.get` and `@router.post` handlers inside your `plugin.py` setup method. You get the exact same raw FastAPI performance either way.
    </Callout>
  </Tab>

  <Tab value="BaseRepository">
    ### Add Repository — CRUD without repetitive queries [#add-repository--crud-without-repetitive-queries]

    <Callout type="info" emoji="🟢">
      **Independent.** Works completely alone. No other ZCore component or configuration is required.
    </Callout>

    **Before** (Standard SQLAlchemy block in route):

    ```python
    import uuid
    from fastapi import Depends
    from sqlalchemy import select
    from sqlalchemy.ext.asyncio import AsyncSession
    from tasks.models import Task

    @router.get("/tasks/{id}")
    async def get_task(id: uuid.UUID, db: AsyncSession = Depends(get_db)):
        result = await db.execute(select(Task).where(Task.id == id))
        task = result.scalars().first()
        return task
    ```

    **After** (Inheriting from BaseRepository in `tasks/repositories.py`):

    ```python
    # tasks/repositories.py
    from sqlalchemy.ext.asyncio import AsyncSession
    from zcore import BaseRepository
    from .models import Task

    class TaskRepository(BaseRepository[Task]):
        def __init__(self, db: AsyncSession):
            super().__init__(model=Task, db=db)
    ```

    By simply defining this class, you gain access to async single & bulk CRUD operations (`create_multi`, `update_multi`, `delete_multi`), automatic soft-delete and atomic batch restoration (`restore`, `restore_multi`), forced physical deletions (`force=True`), structured dynamic search filters (`contains`, `between`, `not_in`, inverted operators), and keyset cursor-based pagination.

    <Callout type="info" emoji="−">
      **No lock-in:** You can bypass the repository at any time and write raw SQLAlchemy query statements directly in your routes whenever complex query logic demands it.
    </Callout>
  </Tab>

  <Tab value="BaseService">
    ### Add Service — Orchestration with structured hooks [#add-service--orchestration-with-structured-hooks]

    <Callout type="info" emoji="🟡">
      **Composable.** Pairs beautifully with BaseRepository, but works independently with any data-mapping strategy.
    </Callout>

    ```python
    # tasks/services.py
    from typing import Any
    from pydantic import BaseModel
    from zcore import BaseService
    from .models import Task
    from .repositories import TaskRepository

    class TaskService(BaseService[Task]):
        def __init__(self, repository: TaskRepository):
            super().__init__(model=Task, repository=repository)

        async def pre_create(self, schema: BaseModel) -> dict[str, Any] | None:
            # Perform validation or auto-generate fields before saving
            return {"slug": "slugified-title"}
    ```

    Available lifecycle hooks include `pre_create`, `post_create`, `pre_update`, `post_update`, `pre_delete`, `post_delete` (with `force` flag propagation), `pre_restore`, `post_restore`, and their `_multi` counterparts to cleanly separate business logic from routing layers.

    <Callout type="info" emoji="−">
      **Or don't.** You can keep your business logic directly inside standard route functions. ZCore doesn't force a strict service layer structure.
    </Callout>
  </Tab>

  <Tab value="Zchema">
    ### Add Zchema — Secure Projection and Dynamic Field Pruning [#add-zchema--secure-projection-and-dynamic-field-pruning]

    <Callout type="info" emoji="🟡">
      **Composable.** Integrates directly with native FastAPI route schemas to prevent Mass Assignment and data leaks.
    </Callout>

    **Before** (Writing multiple redundant Pydantic models):

    ```python
    from pydantic import BaseModel

    class TaskPublic(BaseModel):
        title: str

    class TaskInternal(BaseModel):
        title: str
        assignee_email: str  # Sensitive field
    ```

    **After** (A single, role-aware Zchema as defined in Step 4):

    ```python
    # tasks/schemas.py
    import uuid
    from pydantic import ConfigDict
    from zcore import Zchema

    class TaskResponse(Zchema):
        __model__ = "tasks"
        __private__ = {"cost_price"}  # Automatically hidden for unauthenticated guests
        
        id: uuid.UUID
        title: str
        assignee_email: str | None = None  # Automatically hidden if the active user lacks scope
        cost_price: float | None = None
        
        model_config = ConfigDict(from_attributes=True)
    ```

    When a user logs in, their profile maps restricted fields (e.g., `["tasks.assignee_email"]`) into `ctx.restricted_fields`. `Zchema` automatically intercepts serialization and prunes restricted attributes from responses, input validation, and OpenAPI documentation (`?schema=true`). For unauthenticated visitors, fields declared in `__private__` are stripped automatically.

    <Callout type="info" emoji="−">
      **Or don't.** You are welcome to use standard Pydantic models and define separate response schemas manually.
    </Callout>
  </Tab>

  <Tab value="UnitOfWork">
    ### Add Unit of Work — Atomic transactions and Event Isolation [#add-unit-of-work--atomic-transactions-and-event-isolation]

    <Callout type="info" emoji="🟢">
      **Independent.** Works seamlessly with any asynchronous DB session or repository.
    </Callout>

    **Before** (Manual commits and early events):

    ```python
    await repo.create(order_data)
    await repo.decrement_stock(product_id, qty)
    await db.commit() 
    # If db.commit fails, our system might have already fired side-effects!
    ```

    **After** (Safe, atomic commit block):

    ```python
    from zcore import UnitOfWork

    # Coordinate database changes and delay event dispatching until commit succeeds
    async with UnitOfWork(session, dispatcher) as uow:
        await repo.create(order_data)
        await repo.decrement_stock(product_id, qty)
        uow.register_event("order.placed", {"id": order_data.id})
        # Events are only dispatched once the database transaction commits successfully
    ```

    If any database statement fails inside the context manager, the entire transaction automatically rolls back and pending events are cleared.

    <Callout type="info" emoji="💡">
      **Re-entrant Depth Tracking:** `UnitOfWork` is depth-aware. Nested service calls safely flush changes without prematurely committing, while domain events are held until the outermost root transaction succeeds.
    </Callout>

    <Callout type="info" emoji="−">
      **Or don't.** Use `db.commit()` directly for basic, single-write transactions.
    </Callout>
  </Tab>

  <Tab value="Skip all">
    ### Skip ZCore entirely [#skip-zcore-entirely]

    You are never locked into ZCore. You can keep your project as a standard, native FastAPI structure while still benefiting from the clean settings management, structured environment file support, and scaffolding CLI.

    You can adopt any of ZCore's components next week, next month, or never:

    ```python
    # Today: Native, standard FastAPI route
    from fastapi import APIRouter

    router = APIRouter()

    # Next month: Drop in a ZCore helper without refactoring existing routes
    from zcore import BaseRepository
    ```

    No major rewrites required.
  </Tab>
</Tabs>

***

## Architecture Summary: When to reach for ZCore [#architecture-summary-when-to-reach-for-zcore]

| When you want to...                                        | Use this ZCore component      | Or write this natively                      |
| ---------------------------------------------------------- | ----------------------------- | ------------------------------------------- |
| Stop writing repetitive CRUD queries                       | `BaseRepository`              | Raw SQLAlchemy query executions             |
| Execute validation and hooks before/after DB writes        | `BaseService`                 | Code inside your route functions            |
| Dynamically hide fields on a schema based on user roles    | `Zchema`                      | Multiple separate Pydantic schemas          |
| Group database writes and isolate domain events            | `UnitOfWork`                  | Manual `session.commit()` blocks            |
| Scaffold standard CRUD API endpoints with zero boilerplate | `BaseRouter`                  | Explicit `@router` path functions           |
| Auto-wire service and repository dependencies              | `Inject[T]`                   | Hand-written `Depends()` parameters         |
| Run isolated background jobs with IoC injection            | `background_task`             | Manual session & scope handling             |
| Normalize API errors into a unified envelope               | `register_exception_handlers` | Manual `@app.exception_handler` definitions |

Every native pattern in the right-hand column remains 100% valid. ZCore simply streamlines your architecture when you want to write less boilerplate.


# What is ZCore? (/docs/what-is-zcore)





## Core Definition [#core-definition]

**FastAPI ZCore Framework is a high-performance modular architectural framework built on top of FastAPI, created by [Ali Alf Ostovar](https://github.com/alialfostovar) and maintained by [Baseryn](https://github.com/Baseryn).**

It provides a cohesive set of enterprise-grade design patterns—such as constructor dependency injection with auto-wiring, repository pattern abstractions with bulk mutation optimizations, complete soft-delete restoration lifecycles, dynamic schema projections (`Zchema`), automated 8-endpoint CRUD/Lookup scaffolding, transactional Unit of Work, unified exception normalization with debug-gated diagnostics, and isolated background tasks—designed to eliminate repetitive boilerplate in growing, high-throughput FastAPI applications.

Every architectural layer in ZCore is **strictly opt-in**. You can adopt a single pattern in an existing codebase, combine multiple layers, or ignore them entirely. Your application remains a standard FastAPI project at its core.

***

## What ZCore is NOT [#what-zcore-is-not]

Misconceptions often arise when comparing modular frameworks to monolithic, opinionated tools. Here is how ZCore differs:

| ZCore is NOT                        | Why this misconception occurs                               | The Architectural Reality                                                                                                                                                                                     |
| ----------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **A rigid framework (like Django)** | It features CLI scaffolding and architectural base classes. | The `zc` CLI generates clean, standard files that you can freely modify or delete. Base classes provide flexible working defaults, not enforced monolithic structures.                                        |
| **An enterprise monolith**          | It includes Unit of Work and plugin management.             | `UnitOfWork` is a lightweight context manager; `Plugin` is an optional startup registry with DAG topological sorting. Both function seamlessly even in a small, two-file project.                             |
| **A replacement for FastAPI**       | It exposes its own classes and is imported via `zcore`.     | ZCore **extends** FastAPI natively. You continue writing standard `@router` endpoints, using native Pydantic models, and leveraging `Depends()`. ZCore simply offers higher-level architectural abstractions. |
| **Opinionated or intrusive**        | It provides pre-built `Base` classes.                       | Every method across ZCore base components is fully overridable. "Base" implies a sensible default implementation, not a closed black box.                                                                     |
| **All-or-nothing**                  | It carries the umbrella name of a framework.                | You can import and use `Inject[T]`, `background_task`, `register_exception_handlers`, or `BaseRepository` independently in a project that utilizes zero other ZCore modules.                                  |

<Callout type="info" emoji="💡">
  **Architectural Rule:** If a specific ZCore component does not directly solve a structural pain point in your route, model, or service, do not use it. ZCore never imposes self-dependency.
</Callout>

***

## How ZCore Relates to FastAPI [#how-zcore-relates-to-fastapi]

ZCore does not wrap or abstract away FastAPI; it runs **alongside** it.

* **Standard Routing:** You retain full access to FastAPI's `APIRouter`, native background tasks, and exception handlers.
* **Native Pydantic V2:** ZCore models (`Zchema`) inherit directly from Pydantic `BaseModel`, ensuring 100% compatibility with native data validation pipelines.
* **Dependency Injection Integration:** `Inject[T]` compiles internally down to standard FastAPI `Annotated[T, Depends()]` structures, keeping OpenAPI introspection, Swagger UI documentation, and dependency overrides fully intact.
* **Unified Error Normalization:** Integrates with Starlette and FastAPI exception lifecycles to automatically wrap domain errors, 422 validation issues, and uncaught 500 runtime exceptions into a single structured envelope (`ResponseWrapper`), sanitizing Pydantic error traces and gating server internals in production.
* **Async Native:** Built specifically for async Python 3.11+, SQLAlchemy 2.0 Async, and ASGI middleware lifecycles.

***

## Core Design Principles [#core-design-principles]

### 1. Optional by Default [#1-optional-by-default]

There is no global initialization hook or mandatory app factory that hijacks your project structure. You import and instantiate precisely what you require:

```python
# Import and use only the DI container helper — nothing else
from zcore import Inject

class NotificationService:
    def __init__(self, client: Inject[EmailClient]):
        self.client = client
```

### 2. Overridable by Design [#2-overridable-by-design]

Base classes are structured to be extended or replaced. If a default implementation does not match your business rules, override it cleanly:

```python
from typing import Any
from zcore import BaseService
from pydantic import BaseModel

class TaskService(BaseService[Task]):
    # Override a specific lifecycle hook (Hooks live in the Service layer)
    async def pre_create(self, schema: TaskCreate) -> dict[str, Any] | None:
        return {"slug": slugify(schema.title)}

    # Or override the entire core method when absolute control is needed
    async def on_create(self, schema: BaseModel, **extra_data: Any) -> Task:
        task = await self.repository.create(schema, **extra_data)
        await external_cache.set(f"task:{task.id}", task)
        return task
```

### 3. Composable, Not Coupled [#3-composable-not-coupled]

You can mix and match ZCore components with native FastAPI patterns freely:

<Tabs items="['Repository Only', 'Service + Repository', 'Zchema with Plain Router', 'Isolated Background Tasks']">
  <Tab value="Repository Only">
    ```python
    from zcore import BaseRepository, Inject

    class TaskRepo(BaseRepository[Task]):
        pass

    @router.get("/tasks")
    async def list_tasks(repo: Inject[TaskRepo]):
        # Includes dynamic search, soft-delete, and restoration out-of-the-box
        return await repo.get_list()
    ```

    *No service layer, no base router—just clean repository abstraction.*
  </Tab>

  <Tab value="Service + Repository">
    ```python
    from zcore import BaseService, Inject

    class TaskService(BaseService[Task]):
        def __init__(self, repo: TaskRepo):
            super().__init__(model=Task, repository=repo)

        async def pre_create(self, schema):
            return {"slug": slugify(schema.title)}
    ```

    *Encapsulated business logic without enforcing automated routing.*
  </Tab>

  <Tab value="Zchema with Plain Router">
    ```python
    from zcore import Zchema
    from fastapi import APIRouter, Depends
    from sqlalchemy.ext.asyncio import AsyncSession

    class TaskResponse(Zchema):
        __model__ = "tasks"
        title: str
        internal_score: float  # Automatically stripped if unauthorized

    @router.get("/tasks/{id}", response_model=TaskResponse)
    async def get_task(id: int, db: AsyncSession = Depends(get_db)):
        ...
    ```

    *Role-aware schema projection working inside a standard native route.*
  </Tab>

  <Tab value="Isolated Background Tasks">
    ```python
    import uuid
    from zcore import background_task

    @background_task
    async def send_invoice(order_id: uuid.UUID, service: InvoiceService):
        # Automatically resolved from IoC container with an isolated AsyncSession!
        await service.process(order_id)
    ```

    *Safe background execution without closed session leaks.*
  </Tab>
</Tabs>

***

## Boundaries: What ZCore Does NOT Do [#boundaries-what-zcore-does-not-do]

Clarity regarding framework boundaries helps determine when ZCore is an appropriate fit:

| ZCore does NOT                          | Underlying Implementation / Alternative                                                                       |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Replace SQLAlchemy                      | ZCore builds directly on top of SQLAlchemy 2.0 async engines and sessions.                                    |
| Replace Pydantic                        | ZCore extends Pydantic V2 via `Zchema` for field-level security projection.                                   |
| Enforce strict project layouts          | The `zc` CLI provides an interactive, modular scaffolding wizard; you can adapt or delete it.                 |
| Manage database migrations              | Use Alembic directly for full control over migration histories.                                               |
| Provide built-in user authentication UI | It offers `BaseAuth` utilities and Argon2id hashing, but authentication state and models are yours to define. |

***

## When to Adopt ZCore (And When to Skip It) [#when-to-adopt-zcore-and-when-to-skip-it]

### ZCore helps when... [#zcore-helps-when]

* You are writing repetitive CRUD and field-projected lookup endpoints across multiple models.
* You need full soft-delete lifecycles, batch restorations (`restore_multi`), and hard-delete bypasses (`?force=true`).
* You need dynamic, role-based field visibility on schemas without maintaining dozens of duplicate Pydantic models.
* You require atomic multi-table writes with deferred event publishing via Unit of Work.
* You prefer clean constructor injection with auto-wiring over verbose, nested `Depends()` parameters.
* You need to run asynchronous background routines with guaranteed database session and context isolation.
* You want a unified, production-safe error envelope across all domain, validation, and unhandled 500 exceptions.

### ZCore is unnecessary when... [#zcore-is-unnecessary-when]

* Your application consists of 1–2 simple endpoints with minimal business logic.
* You have no requirements for field-level security masking or complex audit trails.
* You prefer writing explicit, manual `Depends()` chains and inline SQL statements.

<Callout type="info" emoji="🎯">
  **Pragmatic Rule:** If your FastAPI application is scaling cleanly and meeting your architectural needs without friction, you do not need ZCore. Adopt ZCore only when addressing specific structural scaling bottlenecks.
</Callout>

***

## The Adoption Spectrum [#the-adoption-spectrum]

You control the pace of adoption. Moving rightward along the spectrum is entirely optional and driven solely by project growth:

1. **Plain FastAPI** (Zero ZCore dependencies)
2. **Targeted Utilities** (Adopting `Inject[T]`, `background_task`, `register_exception_handlers`, or `UnitOfWork`)
3. **Data Access Layer** (`BaseRepository` with soft-delete/restoration, and `BaseService`)
4. **Security & Projection** (`Zchema` for role-based field filtering and input protection)
5. **Full Orchestration** (`BaseRouter` with 8 standard endpoints including `/lookup`, and modular `Plugin` architectures)

***

## Explore the Components [#explore-the-components]

<Cards>
  <Card title="Inject & IoC Container" href="/docs/api-reference/ioc-container/">
    Explore automatic type-safe constructor auto-wiring and signature caching.
  </Card>

  <Card title="Background Tasks & Scopes" href="/docs/api-reference/background-tasks">
    Isolated AsyncSessions and IoC auto-wiring for background routines.
  </Card>

  <Card title="BaseRepository" href="/docs/api-reference/repository">
    Async CRUD, soft-delete restoration, bulk RETURNING mutations, keyset pagination, and dynamic search.
  </Card>

  <Card title="BaseRouter & Lookups" href="/docs/api-reference/router">
    Scaffold 8 standard endpoints with field-projected lookups and route specificity sorting.
  </Card>

  <Card title="Zchema" href="/docs/api-reference/zchema">
    Dynamic field-level security pruning for responses, inputs, and OpenAPI schemas.
  </Card>

  <Card title="UnitOfWork" href="/docs/api-reference/uow">
    Atomic transactions and post-commit deferred event dispatching.
  </Card>

  <Card title="Exception Handlers" href="/docs/api-reference/exceptions">
    Unified error normalization, Pydantic trace sanitization, and debug-gated diagnostics.
  </Card>
</Cards>


# ZCoreAPIRoute & Web Adapters (/docs/api-reference/api-router)





`ZCoreAPIRoute` extends FastAPI's standard `APIRoute`. It configures routes to use `ZCoreJSONResponse`, intercepts `?schema=true` dynamic schema requests, binds action contexts, and manages HTTP `Vary` caching headers.

## Class Definition [#class-definition]

```python
from fastapi.routing import APIRoute
from zcore.web import ZCoreAPIRoute

class ZCoreAPIRoute(APIRoute):
    def __init__(self, *args: Any, **kwargs: Any):
        ...
```

***

## Attributes [#attributes]

<TypeTable
  type="{
  expose_schema: {
    type: 'bool',
    description: 'Determines if the route intercepts ?schema=true requests (derived from openapi_extra[&#x22;expose_schema&#x22;]).',
  },
  target_model: {
    type: 'type[BaseModel] | None',
    description: 'The resolved target Pydantic schema model used for dynamic schema generation.',
  }
}"
/>

***

## Execution Flow & Lifecycle Interception [#execution-flow--lifecycle-interception]

<Callout type="info" emoji="⚙️">
  **Route Execution Pipeline:**

  1. **Unified Response Class Swap:** If `response_class` is standard `JSONResponse`, it is swapped to `ZCoreJSONResponse` to use the unified serialization pipeline (`json_dumps`).
  2. **Context Action Binding:** Extracts or calculates the action context (e.g., `POST` $\rightarrow$ `"create"`, `GET` $\rightarrow$ `"view"`, `PUT` $\rightarrow$ `"update"`) and binds it via `ctx.set("action", custom_action)`.
  3. **Dynamic Schema Interception (`?schema=true`):** If `expose_schema=True` and `?schema=true` is present in query parameters, execution skips the endpoint handler, invokes `target_model.model_json_schema()`, and returns the pruned schema wrapped in a `ResponseWrapper`.
  4. **CDN Cache Protection (`Vary` Header):** If `ctx.restricted_fields` are active on a JSON response, `ZCoreAPIRoute` automatically appends `Vary: Authorization, Cookie` to prevent intermediate proxies or CDN caches from serving masked responses to unrestricted users.
</Callout>

***

## Helper Classes & Functions [#helper-classes--functions]

### `ZCoreRequest` [#zcorerequest]

Custom HTTP `Request` subclass that caches the raw body byte stream to prevent multi-read stream lockups downstream:

```python
from zcore.web import ZCoreRequest

class ZCoreRequest(Request):
    async def body(self) -> bytes:
        # Caches and returns evaluated request payload bytes
        ...
```

### `ZCoreJSONResponse` [#zcorejsonresponse]

Specialized `JSONResponse` subclass rendering payloads through ZCore's custom serialization pipeline (`json_dumps`), supporting ISO dates, Decimals, UUIDs, and Pydantic models:

```python
from zcore.web import ZCoreJSONResponse

class ZCoreJSONResponse(JSONResponse):
    def render(self, content: Any) -> bytes:
        return json_dumps(content).encode("utf-8")
```

### Schema Discovery Helpers [#schema-discovery-helpers]

These utility functions inspect FastAPI route signatures to locate the target Pydantic models:

* **`find_input_schema(dependant: Any) -> type[BaseModel] | None`:** Analyzes route body parameters on `POST`, `PUT`, and `PATCH` endpoints to resolve creation/update input models.
* **`find_output_schema(response_model: Any) -> type[BaseModel] | None`:** Recursively unpacks generic types (like `ResponseWrapper[list[TaskResponse]]`) on `GET` endpoints to extract the underlying response model.


# Background Tasks & Scopes (/docs/api-reference/background-tasks)





ZCore provides `background_scope` and `@background_task` to ensure asynchronous background jobs run in an independent IoC container lifecycle, with dedicated database sessions, context isolation, and automatic dependency auto-wiring.

***

## Functions [#functions]

### `background_scope` [#background_scope]

An asynchronous context manager that provisions an isolated execution context, allocated database session (`AsyncSession`), and independent `ZContext` store.

```python
from collections.abc import AsyncGenerator
from contextlib import asynccontextmanager
from typing import Any

@asynccontextmanager
async def background_scope(
    inherit_context: bool = True,
    **custom_context: Any,
) -> AsyncGenerator[None, None]:
    ...
```

#### Parameters [#parameters]

<TypeTable
  type="{
  inherit_context: {
    type: 'bool',
    default: 'True',
    description: 'If True, clones active request context parameters (e.g., user_id, scopes, action) into the background scope.',
  },
  custom_context: {
    type: 'dict[str, Any]',
    default: '{}',
    description: 'Explicit key-value attributes to override or populate in the background context store.',
  }
}"
/>

***

### `@background_task` [#background_task]

A function decorator that automatically wraps execution inside `background_scope()` and inspects parameter type annotations to auto-wire dependencies from the global IoC container.

```python
from collections.abc import Callable
from typing import Any

def background_task(func: Callable[..., Any]) -> Callable[..., Any]:
    ...
```

#### Behavior & Execution Matrix [#behavior--execution-matrix]

| Function Type                  | Execution Strategy                                                          | Dependency Resolution                                                  |
| ------------------------------ | --------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| **Asynchronous (`async def`)** | Executed directly on the asyncio event loop within `background_scope()`.    | Auto-resolved from `container.resolve()` for type-annotated arguments. |
| **Synchronous (`def`)**        | Offloaded asynchronously to a worker thread via `anyio.to_thread.run_sync`. | Auto-resolved from `container.resolve()` before thread dispatch.       |

***

## Lifecycle Guarantee [#lifecycle-guarantee]

<Callout type="info" emoji="🛡️">
  **Why background\_scope is necessary:**
  When FastAPI finishes sending an HTTP response, `ScopedDependencyMiddleware` closes the request's `AsyncSession` and clears the request's IoC scope.

  If a standard `BackgroundTasks` job accesses that session, it encounters a `RuntimeError: Session is closed`.

  `background_scope` solves this by:

  1. Generating a fresh, independent UUID `scope_id`.
  2. Opening a dedicated, standalone `AsyncSession` from `db_manager.session()`.
  3. Registering the new session as a scoped instance in the IoC container.
  4. Guaranteeing session commit/rollback and scope purging upon completion or failure.
</Callout>


# BaseAuth (/docs/api-reference/base-auth)





`BaseAuth` is a generic Template-Method authentication dependency. It coordinates JWT decoding, automatic user session caching, active-state assertions, and dynamically binds schema attributes directly onto the shared `ZContext`.

## Class Definition [#class-definition]

```python
from typing import Generic, TypeVar, Any
from pydantic import BaseModel
from zcore import BaseAuth

T = TypeVar("T", bound=BaseModel)

class BaseAuth(Generic[T]):
    def __init__(
        self,
        user_schema: type[T],
        identity_claim: str = "sub",
        token_type: str = "access",
        cache_prefix: str = "auth",
        cache_ttl: int | None = None,
        auto_error: bool = True
    ) -> None:
        ...
```

***

## Initialization Parameters [#initialization-parameters]

<TypeTable
  type="{
  user_schema: {
    type: 'type[T]',
    description: 'The validated Pydantic model representation of the user.',
  },
  identity_claim: {
    type: 'str',
    default: '&#x22;sub&#x22;',
    description: 'The JWT payload claim key denoting user identity (e.g., &#x22;sub&#x22; or &#x22;user_id&#x22;).',
  },
  token_type: {
    type: 'str',
    default: '&#x22;access&#x22;',
    description: 'The required value of the &#x22;type&#x22; claim in the validated JWT.',
  },
  cache_prefix: {
    type: 'str',
    default: '&#x22;auth&#x22;',
    description: 'Cache prefix namespace used by BaseCache for storing resolved user profiles.',
  },
  cache_ttl: {
    type: 'int | None',
    default: 'settings.AUTH_CACHE_TTL (300)',
    description: 'Expiration lifespan of cached user instances in seconds. If None, resolves dynamically from settings.AUTH_CACHE_TTL (default: 300s / 5 minutes).',
  },
  auto_error: {
    type: 'bool',
    default: 'True',
    description: 'Whether to raise AuthError on missing or invalid tokens. When False, returns None gracefully to support optional authentication.',
  }
}"
/>

***

## Methods [#methods]

### `fetch_user` [#fetch_user]

Fetches the active user record from persistent storage. This is the **Template Method hook** that must be implemented by concrete subclass implementations in your application layer.

```python
async def fetch_user(self, identity: str) -> Any: ...
```

<TypeTable
  type="{
  identity: {
    type: 'str',
    description: 'Uniquely identifying string value extracted from the token (e.g., user ID, username, or email).',
  },
  returns: {
    type: 'Any',
    description: 'The database user entity or dictionary. Raises NotImplementedError if not overridden.',
  }
}"
/>

### `__call__` [#__call__]

Executes the core request interception authentication workflow. Functions as a callable FastAPI dependency (`Depends(auth_instance)`).

```python
async def __call__(
    self, 
    request: Request, 
    token: str | None = Depends(oauth2_scheme)
) -> T | None: ...
```

<TypeTable
  type="{
  request: {
    type: 'Request',
    description: 'The incoming FastAPI HTTP request instance.',
  },
  token: {
    type: 'str | None',
    description: 'The extracted Bearer token from the Authorization header, or None if omitted.',
  },
  returns: {
    type: 'T | None',
    description: 'The validated Pydantic schema model instance representing the authenticated user, or None if unauthenticated and auto_error is False. Raises AuthError on failures when auto_error is True.',
  }
}"
/>

***

## Execution Flow & Context Binding [#execution-flow--context-binding]

<Callout type="info" emoji="🧩">
  **The `BaseAuth` Pipeline:**

  1. **Token Extraction:** Extracts the Bearer token via `OAuth2PasswordBearer(tokenUrl="token", auto_error=False)`.
  2. **Token & Claims Verification:** If no token is provided and `auto_error=False`, it exits early returning `None`. Otherwise, decodes the token using `Security.decode_jwt()`, validating the signature, expiration, and asserting `type == token_type`.
  3. **Cache-Aside Check:** Checks `BaseCache(prefix="auth")` for key `user:{identity}`. If a cache hit occurs, it deserializes directly into `user_schema`.
  4. **Database Resolution:** If a cache miss occurs, invokes `await self.fetch_user(identity)`, asserts `is_active == True`, validates with `user_schema.model_validate(db_user)`, and populates the cache using the resolved `cache_ttl` (`settings.AUTH_CACHE_TTL`).
  5. **Dynamic Context Population:**
     * `user.id` $\rightarrow$ `ctx.user_id`
     * `user.all_restricted_fields` $\rightarrow$ `ctx.restricted_fields` (as an immutable `frozenset`)
     * All remaining fields (e.g., `scopes`, `roles`, `email`) $\rightarrow$ `ctx.set(field_name, value)`
</Callout>


# BaseCache & Caching Layer (/docs/api-reference/base-cache)





`BaseCache` provides a unified caching interface supporting distributed caching (via Redis) with an asynchronous, thread-safe local memory fallback (via `TTLLRUCache`). It coordinates global cache lifecycles, structured serialization, and periodic background eviction routines safely within active event loops.

## Class Definition [#class-definition]

```python
from typing import Generic, TypeVar
from zcore.cache import BaseCache

T = TypeVar("T")

class BaseCache(Generic[T]):
    def __init__(
        self, 
        prefix: str, 
        local_maxsize: int | None = None, 
        default_ttl: int | None = None
    ) -> None:
        ...
```

***

## Initialization Parameters [#initialization-parameters]

<TypeTable
  type="{
  prefix: {
    type: 'str',
    description: 'Namespace prefix applied to all keys managed by this instance (e.g., &#x22;tasks&#x22; creates keys like &#x22;tasks:123&#x22;).',
  },
  local_maxsize: {
    type: 'int | None',
    default: 'settings.CACHE_LOCAL_MAXSIZE (1000)',
    description: 'Optional maximum entries allowed in the local fallback store before LRU eviction.',
  },
  default_ttl: {
    type: 'int | None',
    default: 'settings.CACHE_DEFAULT_TTL (3600)',
    description: 'Optional default expiration lifespan in seconds for stored cache records.',
  }
}"
/>

***

## Properties [#properties]

<TypeTable
  type="{
  redis_client: {
    type: 'Any | None',
    description: 'The active shared Redis client connection, or None if distributed caching is uninitialized.',
  }
}"
/>

***

## Methods [#methods]

### `get` [#get]

Retrieves and deserializes a cache record by its key. Looks up records from Redis first, falling back to the local memory store on connection errors or missing pools.

```python
async def get(
    self, 
    key: str, 
    target_type: type[BaseModel] | None = None
) -> T | BaseModel | Any | None: ...
```

<TypeTable
  type="{
  key: {
    type: 'str',
    description: 'The unique identifier key query (without the prefix).',
  },
  target_type: {
    type: 'type[BaseModel] | None',
    default: 'None',
    description: 'Optional Pydantic model class type to validate the decoded payload against.',
  },
  returns: {
    type: 'T | BaseModel | Any | None',
    description: 'The parsed data structure or validated Pydantic model instance, or None if missing or corrupted.',
  }
}"
/>

<Callout type="info" emoji="🔄">
  **Automatic Pydantic Validation:** If `target_type` is provided (e.g., `TaskResponse`), `BaseCache` automatically deserializes the raw JSON and invokes `target_type.model_validate(parsed_data)`.
</Callout>

### `set` [#set]

Serializes and persists a key-value record with a Time-To-Live (TTL). Stores in Redis if available, falling back to the thread-safe local memory buffer on network failures.

```python
async def set(self, key: str, value: T, ttl: int | None = None) -> None: ...
```

<TypeTable
  type="{
  key: {
    type: 'str',
    description: 'The unique identifier key to store.',
  },
  value: {
    type: 'T',
    description: 'The data payload to serialize (using custom JSON encoder) and cache.',
  },
  ttl: {
    type: 'int | None',
    default: 'self.default_ttl (3600)',
    description: 'Maximum cache lifespan in seconds. If omitted, falls back to the instance default_ttl.',
  }
}"
/>

### `delete` [#delete]

Evicts a record from both distributed Redis and local memory fallback caches.

```python
async def delete(self, key: str) -> None: ...
```

<TypeTable
  type="{
  key: {
    type: 'str',
    description: 'The unique key identifier to evict.',
  }
}"
/>

***

## Global Cache Functions [#global-cache-functions]

### `init_cache` [#init_cache]

Configures the shared distributed Redis client and attempts to schedule the background in-memory garbage collection worker loop if an active event loop is running (with lazy scheduling ensuring execution across subsequent cache operations).

```python
from zcore.cache import init_cache

def init_cache(redis_url: str | None = None, **kwargs: Any) -> None: ...
```

<TypeTable
  type="{
  redis_url: {
    type: 'str | None',
    default: 'None',
    description: 'Connection URL pointing to a Redis server instance (e.g., &#x22;redis://localhost:6379&#x22;).',
  },
  '**kwargs': {
    type: 'Any',
    description: 'Connection pool parameters forwarded directly to the Redis client initialization.',
  }
}"
/>

### `close_cache` [#close_cache]

Cancels background eviction worker loops and cleanly closes shared distributed Redis connections.

```python
from zcore.cache import close_cache

async def close_cache() -> None: ...
```

***

## Local In-Memory Fallback: `TTLLRUCache` [#local-in-memory-fallback-ttllrucache]

Thread-safe in-memory cache featuring granular record-level expiration boundaries and LRU eviction, dynamically bounded by settings:

```python
from zcore.cache import TTLLRUCache

class TTLLRUCache:
    def __init__(self, maxsize: int | None = None) -> None: ...
    def get(self, key: str) -> Any | None: ...
    def set(self, key: str, value: Any, ttl: int | None = None) -> None: ...
    def delete(self, key: str) -> None: ...
    def evict_expired(self) -> None: ...
    
    @classmethod
    def evict_all_expired(cls) -> None: ...
```

<TypeTable
  type="{
  'maxsize': {
    type: 'int | None',
    default: 'settings.CACHE_LOCAL_MAXSIZE (1000)',
    description: 'Maximum volume of elements cached simultaneously before LRU eviction.',
  },
  'ttl in set()': {
    type: 'int | None',
    default: 'settings.CACHE_DEFAULT_TTL (3600)',
    description: 'Lifespan limit in seconds before key is marked expired.',
  }
}"
/>


# BaseRouter (/docs/api-reference/base-router)





`BaseRouter` automatically scaffolds 8 standard security-aware CRUD, search, and field-projected lookup endpoints (`POST`, `GET`, `GET_ALL`, `SEARCH`, `LOOKUP`, `UPDATE`, `PATCH`, `DELETE`) with primary key reflection, dependency injection, and specificity route sorting.

## Class Definition [#class-definition]

```python
from zcore import BaseRouter, RouteKey

class BaseRouter(Generic[CreateSchemaType, UpdateSchemaType]):
    def __init__(self) -> None:
        ...
```

***

## Class Attributes [#class-attributes]

These attributes configure the scaffolded endpoints in your subclass:

<TypeTable
  type="{
  model: {
    type: 'Type[Base]',
    description: 'The database declarative model class. Used for resolving primary keys and permission actions.',
  },
  create_schema: {
    type: 'Type[CreateSchemaType] | None',
    default: 'None',
    description: 'Pydantic schema class for validating entity creations (POST /).',
  },
  update_schema: {
    type: 'Type[UpdateSchemaType] | None',
    default: 'None',
    description: 'Pydantic schema class for validating entity updates (PUT & PATCH /{id}).',
  },
  schema_out: {
    type: 'Type[BaseModel] | None',
    default: 'None',
    description: 'Pydantic schema class representing response payloads.',
  },
  lookup_schema: {
    type: 'Type[BaseModel] | None',
    default: 'None',
    description: 'Minimal schema class representing relational reference lookups (POST /lookup).',
  },
  allowed_lookup_fields: {
    type: 'set[str] | None',
    default: 'None',
    description: 'Explicit whitelist of filterable/sortable fields for lookup queries. If None, derived from lookup_schema.',
  },
  max_lookup_size: {
    type: 'int | None',
    default: 'None',
    description: 'Maximum records threshold allowed in lookup responses (falls back to max_page_size or settings.PAGINATION_MAX_SIZE).',
  },
  max_page_size: {
    type: 'int | None',
    default: 'None',
    description: 'Upper bound on page size across list and search queries (falls back to settings.PAGINATION_MAX_SIZE).',
  },
  default_page_size: {
    type: 'int | None',
    default: 'None',
    description: 'Fallback record count per page when omitted in query requests (falls back to settings.PAGINATION_DEFAULT_SIZE).',
  },
  service: {
    type: 'Type[BaseService] | Any',
    description: 'Business service class callable. Auto-wired via Injector.',
  },
  pk_type: {
    type: 'Type[Any] | None',
    default: 'None',
    description: 'Optional explicit primary key type. If None, auto-resolved from model metadata.',
  },
  prefix: {
    type: 'str',
    default: '&#x22;&#x22;',
    description: 'Path prefix representing the router (e.g., &#x22;/tasks&#x22;).',
  },
  tags: {
    type: 'list[str] | None',
    default: 'None',
    description: 'Endpoint classification tags for Swagger / OpenAPI docs.',
  },
  exclude: {
    type: 'set[RouteKey] | None',
    default: 'set()',
    description: 'Explicit endpoints to omit from route generation (e.g., {RouteKey.DELETE}).',
  },
  pagination_class: {
    type: 'Type[BasePagination] | None',
    default: 'None',
    description: 'Pagination engine class (PageNumberPagination or CursorPagination).',
  },
  route_class: {
    type: 'Type[APIRoute]',
    default: 'ZCoreAPIRoute',
    description: 'Custom routing processing class supporting ?schema=true and body caching.',
  },
  expose_schemas: {
    type: 'set[RouteKey] | bool',
    default: 'False',
    description: 'Exposes target endpoint schemas dynamically via ?schema=true.',
  }
}"
/>

***

## RouteKey Enumeration [#routekey-enumeration]

The `RouteKey` enum identifies standard HTTP endpoints managed by `BaseRouter`:

```python
from zcore import RouteKey
```

<TypeTable
  type="{
  POST: {
    type: '&#x22;POST&#x22;',
    description: 'Single entity creation endpoint (POST /).',
  },
  GET: {
    type: '&#x22;GET&#x22;',
    description: 'Single entity lookup endpoint by primary key (GET /{id}).',
  },
  GET_ALL: {
    type: '&#x22;GET_ALL&#x22;',
    description: 'Batch listing endpoint with optional pagination (GET /).',
  },
  SEARCH: {
    type: '&#x22;SEARCH&#x22;',
    description: 'Dynamic search query endpoint with JSON filters (POST /search).',
  },
  LOOKUP: {
    type: '&#x22;LOOKUP&#x22;',
    description: 'Lightweight, field-projected relational reference query endpoint (POST /lookup).',
  },
  UPDATE: {
    type: '&#x22;UPDATE&#x22;',
    description: 'Full record update endpoint (PUT /{id}).',
  },
  PATCH: {
    type: '&#x22;PATCH&#x22;',
    description: 'Partial record modification endpoint (PATCH /{id}).',
  },
  DELETE: {
    type: '&#x22;DELETE&#x22;',
    description: 'Single entity deletion endpoint (DELETE /{id}) with optional ?force=true support.',
  }
}"
/>

***

## Dependency Methods [#dependency-methods]

### `get_route_action` [#get_route_action]

Retrieves the database/permission action name for a given route key using `model.actions()`.

```python
def get_route_action(self, route_key: RouteKey) -> str: ...
```

* `RouteKey.POST` $\rightarrow$ `model.actions().CREATE`
* `RouteKey.GET` $\rightarrow$ `model.actions().VIEW`
* `RouteKey.GET_ALL` / `RouteKey.SEARCH` $\rightarrow$ `model.actions().LISTVIEW`
* `RouteKey.LOOKUP` $\rightarrow$ `model.actions().LOOKUP`
* `RouteKey.UPDATE` / `RouteKey.PATCH` $\rightarrow$ `model.actions().UPDATE`
* `RouteKey.DELETE` $\rightarrow$ `model.actions().DELETE`

### `get_route_dependencies` [#get_route_dependencies]

Generates default route dependencies (authentication, authorization, logging, etc.). Subclasses can override this method to inject dynamic, runtime dependencies per operation.

```python
def get_route_dependencies(self, route_key: RouteKey, action: str) -> list[Any]: ...
```

<TypeTable
  type="{
  route_key: {
    type: 'RouteKey',
    description: 'The target operational route key (e.g., RouteKey.LOOKUP).',
  },
  action: {
    type: 'str',
    description: 'The computed database permission action identifier (e.g., &#x22;tasks:lookup&#x22;).',
  },
  returns: {
    type: 'list[Any]',
    description: 'A list of callables, classes, or FastAPI Depends dependencies. Defaults to [HasScopes(action)].',
  }
}"
/>

***

## Overridable Endpoint Handlers [#overridable-endpoint-handlers]

Subclasses can override the core endpoint execution methods to customize response envelopes, inject custom query parameters, or set specialized HTTP status codes:

### `create_endpoint` [#create_endpoint]

```python
async def create_endpoint(self, data_in: Any, service: BaseService) -> ResponseWrapper: ...
```

### `get_endpoint` [#get_endpoint]

```python
async def get_endpoint(self, id: Any, service: BaseService) -> ResponseWrapper: ...
```

### `get_all_endpoint` [#get_all_endpoint]

```python
async def get_all_endpoint(self, service: BaseService, pagination: Any = None) -> ResponseWrapper: ...
```

### `search_endpoint` [#search_endpoint]

```python
async def search_endpoint(self, search_in: SearchRequest, service: BaseService) -> ResponseWrapper: ...
```

### `lookup_endpoint` [#lookup_endpoint]

```python
async def lookup_endpoint(self, search_in: SearchRequest, service: BaseService) -> ResponseWrapper: ...
```

### `update_endpoint` [#update_endpoint]

```python
async def update_endpoint(self, id: Any, data_in: Any, service: BaseService) -> ResponseWrapper: ...
```

### `patch_endpoint` [#patch_endpoint]

```python
async def patch_endpoint(self, id: Any, data_in: Any, service: BaseService) -> ResponseWrapper: ...
```

### `delete_endpoint` [#delete_endpoint]

```python
async def delete_endpoint(self, id: Any, service: BaseService, force: bool = False) -> ResponseWrapper: ...
```

***

## Architectural Mechanisms [#architectural-mechanisms]

<Callout type="info" emoji="⚡">
  **Intelligent Projection (`_resolve_lookup_projections`):**
  When processing `/lookup` queries, `BaseRouter` introspects `lookup_schema` and maps declared properties directly to model column attributes. It builds a database `load_only(*fields)` projection, automatically incorporates the primary key, and configures relationship loaders (`selectinload` for collections, `joinedload` for scalars). Only attributes declared in the lookup schema are loaded from the database.
</Callout>

<Callout type="warn" emoji="🛡️">
  **Route Specificity Sorting (`_sort_routes`):**
  `BaseRouter` sorts registered routes using hierarchical specificity scoring. Static path segments (such as `/search` and `/lookup`) are prioritized and evaluated before dynamic parameterized paths (such as `/{id}`), preventing FastAPI route shadowing collisions.
</Callout>


# EventDispatcher & @on_event (/docs/api-reference/events)





The `EventDispatcher` coordinates event subscriptions and concurrent asynchronous execution. It allows decoupled application services to communicate via event channels without holding direct references to each other.

## Class Definition & Decorator [#class-definition--decorator]

```python
from zcore import EventDispatcher, on_event
# or: from zcore.kernel.events import EventDispatcher, on_event
```

***

## Decorator: `@on_event` [#decorator-on_event]

Marks an asynchronous service method as an active subscriber for a specific event channel.

```python
def on_event(event_name: str) -> Callable[[Any], Any]: ...
```

<TypeTable
  type="{
  event_name: {
    type: 'str',
    description: 'The unique string identifier of the event channel to subscribe to (e.g., &#x22;order.completed&#x22;).',
  },
  returns: {
    type: 'Callable[[Any], Any]',
    description: 'The decorated method tagged with internal _event_listener metadata.',
  }
}"
/>

***

## Class: `EventDispatcher` [#class-eventdispatcher]

```python
class EventDispatcher:
    def __init__(self) -> None:
        ...
```

***

## Methods [#methods]

### `register_listeners` [#register_listeners]

Inspects a service class for methods decorated with `@on_event` and registers them as lazy event handlers in the dispatcher.

```python
def register_listeners(self, cls: Type[Any], container: Any) -> None: ...
```

<TypeTable
  type="{
  cls: {
    type: 'Type[Any]',
    description: 'The service class type to inspect for @on_event decorated methods.',
  },
  container: {
    type: 'IoCContainer',
    description: 'The active IoCContainer instance used to resolve the class dynamically at execution time.',
  },
  returns: {
    type: 'None',
  }
}"
/>

<Callout type="info" emoji="⚡">
  **Scoped Resolution:** `register_listeners` does not instantiate the class immediately. When the event fires, it invokes `container.resolve(cls)` dynamically. This ensures that request-scoped dependencies (such as database sessions) are resolved cleanly within the active execution scope.
</Callout>

### `dispatch` [#dispatch]

Asynchronously dispatches an event, executing all registered handlers concurrently.

```python
async def dispatch(
    self, 
    event_name: str, 
    *args: Any, 
    **kwargs: Any
) -> list[Any]: ...
```

<TypeTable
  type="{
  event_name: {
    type: 'str',
    description: 'The unique event channel identifier to trigger.',
  },
  '*args': {
    type: 'Any',
    description: 'Positional arguments forwarded directly to subscriber handlers.',
  },
  '**kwargs': {
    type: 'Any',
    description: 'Keyword arguments forwarded directly to subscriber handlers.',
  },
  returns: {
    type: 'list[Any]',
    description: 'A compiled list containing return values from all invoked event handlers.',
  }
}"
/>

<Callout type="info" emoji="🛡️">
  **Concurrent Execution & Error Isolation:**

  * Asynchronous coroutines are gathered using `asyncio.gather(*tasks, return_exceptions=True)`.
  * Synchronous subscriber functions are executed inline safely.
  * If an individual handler raises an unhandled exception, `EventDispatcher` logs the error with full traceback diagnostics, preventing a single failing subscriber from crashing other handlers or breaking the caller.
</Callout>

### `subscribe` [#subscribe]

Directly registers a standalone callback function to listen for an event channel.

```python
def subscribe(self, event_name: str, handler: EventHandler) -> None: ...
```

<TypeTable
  type="{
  event_name: {
    type: 'str',
    description: 'The target event channel identifier.',
  },
  handler: {
    type: 'Callable[..., Coroutine[Any, Any, Any] | Any]',
    description: 'An async or sync callable handler to invoke when the event is triggered.',
  }
}"
/>

### `unsubscribe` [#unsubscribe]

Deregisters a previously registered callback handler from an event channel.

```python
def unsubscribe(self, event_name: str, handler: EventHandler) -> None: ...
```

<TypeTable
  type="{
  event_name: {
    type: 'str',
    description: 'The target event channel identifier.',
  },
  handler: {
    type: 'EventHandler',
    description: 'The callback handler to remove from the subscriber list.',
  }
}"
/>


# Exceptions & Centralized Error Handling (/docs/api-reference/exceptions)





ZCore provides a unified exception hierarchy and a centralized normalization pipeline. When errors occur anywhere across services, repositories, schemas, or routing lifecycles, they are intercepted and rendered in the standard `ResponseWrapper[None]` JSON envelope.

***

## Base Class: `AppException` [#base-class-appexception]

The root runtime exception for all custom business and domain errors in ZCore.

```python
from zcore.exceptions import AppException

class AppException(Exception):
    status_code: int = 500

    def __init__(self, message: str, payload: dict | None = None) -> None:
        super().__init__(message)
        self.message = message
        self.payload = payload
```

<TypeTable
  type="{
  message: {
    type: 'str',
    description: 'A human-readable diagnostic error message.',
  },
  payload: {
    type: 'dict | None',
    default: 'None',
    description: 'Optional structured metadata dictionary providing additional context (e.g., invalid fields, entity IDs).',
  },
  status_code: {
    type: 'int',
    default: '500',
    description: 'The HTTP status code associated with this error response.',
  }
}"
/>

***

## Built-In Domain Exceptions [#built-in-domain-exceptions]

ZCore provides pre-configured domain exceptions mapped to standard HTTP status codes:

```python
from zcore.exceptions import (
    AppException,
    EntityNotFound,
    DuplicateEntity,
    ValidationError,
    AuthError,
    ForbiddenError
)
```

<TypeTable
  type="{
  EntityNotFound: {
    type: 'status_code = 404 (Not Found)',
    description: 'Raised when a requested database record or entity identifier is missing.',
  },
  DuplicateEntity: {
    type: 'status_code = 409 (Conflict)',
    description: 'Raised when a unique constraint or deduplication validation fails.',
  },
  ValidationError: {
    type: 'status_code = 400 (Bad Request)',
    description: 'Raised when dynamic search queries, storage validators, or business rules are violated.',
  },
  AuthError: {
    type: 'status_code = 401 (Unauthorized)',
    description: 'Raised when JWT tokens are invalid, expired, or authentication is required.',
  },
  ForbiddenError: {
    type: 'status_code = 403 (Forbidden)',
    description: 'Raised when an authenticated user lacks required scopes or attempts to access restricted paths.',
  }
}"
/>

***

## Unified Handler Registration: `register_exception_handlers` [#unified-handler-registration-register_exception_handlers]

Attaches all standardized exception normalization handlers to your FastAPI application in a single call, with granular boolean inclusion flags:

```python
from zcore import register_exception_handlers

register_exception_handlers(app)
```

### Function Signature [#function-signature]

```python
def register_exception_handlers(
    app: FastAPI,
    include_app_exceptions: bool = True,
    include_validation_exceptions: bool = True,
    include_http_exceptions: bool = True,
    include_response_validation_exceptions: bool = True,
    include_unhandled_exceptions: bool = True,
) -> None: ...
```

<TypeTable
  type="{
  app: {
    type: 'FastAPI',
    description: 'The target FastAPI application instance.',
  },
  include_app_exceptions: {
    type: 'bool',
    default: 'True',
    description: 'Register handler for domain-level AppException subclasses.',
  },
  include_validation_exceptions: {
    type: 'bool',
    default: 'True',
    description: 'Register handler for FastAPI RequestValidationError (422).',
  },
  include_http_exceptions: {
    type: 'bool',
    default: 'True',
    description: 'Register handler for Starlette/FastAPI HTTPException.',
  },
  include_response_validation_exceptions: {
    type: 'bool',
    default: 'True',
    description: 'Register handler for internal ResponseValidationError (500).',
  },
  include_unhandled_exceptions: {
    type: 'bool',
    default: 'True',
    description: 'Register catch-all fallback handler for generic Exception (500).',
  }
}"
/>

***

## Core Handlers Reference [#core-handlers-reference]

ZCore exports five specialized asynchronous handlers:

### 1. `app_exception_handler` [#1-app_exception_handler]

Intercepts any `AppException`, logs structured diagnostics via `structlog`, and returns a `ZCoreJSONResponse` matching `exc.status_code`.

### 2. `request_validation_exception_handler` [#2-request_validation_exception_handler]

Intercepts `RequestValidationError` (422 errors) raised by FastAPI/Pydantic on invalid request bodies or query parameters. Sanitizes nested error tuples into readable dot-separated paths.

### 3. `http_exception_handler` [#3-http_exception_handler]

Intercepts `StarletteHTTPException` instances, mapping custom headers and exception details cleanly into the error envelope.

### 4. `response_validation_exception_handler` [#4-response_validation_exception_handler]

Intercepts internal `ResponseValidationError` (500 errors). Masks sensitive schema details in production, revealing granular errors only when `settings.DEBUG = True`.

### 5. `unhandled_exception_handler` [#5-unhandled_exception_handler]

Catch-all fallback handler for uncaught runtime exceptions. Records the full stack trace in structured logs while returning a safe, sanitized generic message in production.

***

## Error Sanitization Helpers [#error-sanitization-helpers]

ZCore formats complex Pydantic validation errors through internal sanitization utilities:

* **`_format_error_location(loc)`**: Converts Pydantic location tuples (e.g. `("body", "items", 0, "title")`) into clean dot-separated field paths (`"body.items.0.title"`).
* **`_sanitize_error_item(err)`**: Safely extracts `field`, `message`, `type`, and stringified `context` from raw error dictionaries.

***

## Standardized JSON Error Envelopes [#standardized-json-error-envelopes]

### Domain Exception (404 Not Found) [#domain-exception-404-not-found]

```json
{
  "success": false,
  "message": "Task not found.",
  "data": null,
  "meta": {
    "error_type": "EntityNotFound",
    "payload": {
      "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  }
}
```

### Request Validation Error (422 Unprocessable Entity) [#request-validation-error-422-unprocessable-entity]

```json
{
  "success": false,
  "message": "Validation error on 'body.title': Field required",
  "data": null,
  "meta": {
    "error_type": "RequestValidationError",
    "errors": [
      {
        "field": "body.title",
        "message": "Field required",
        "type": "missing"
      }
    ]
  }
}
```

<Callout type="info" emoji="🔒">
  **Production Debug-Gating:**
  For 500-level errors (`ResponseValidationError` and generic `Exception`), detailed error messages and raw validation lists are only exposed in the JSON response if `settings.DEBUG = True`. In production, a safe generic message is returned to prevent sensitive system disclosures.
</Callout>


# Inject & Injector (/docs/api-reference/inject)





`Inject` is a dynamic type marker that implements unified `Annotated` dependency injection. It allows clean, elegant type annotations in FastAPI route handlers, expanding under the hood into FastAPI `Depends(Injector(T))` resolvers.

## Class Definition [#class-definition]

```python
from typing import Type, TypeVar, Any
from zcore import Inject

T = TypeVar("T")

class Inject:
    def __class_getitem__(cls, interface: Type[T]) -> Any:
        ...
```

***

## How It Works [#how-it-works]

When you annotate a route parameter with `service: Inject[TaskService]`, the `__class_getitem__` dunder method intercepts the generic bracket access. It compiles the type into:

```python
Annotated[TaskService, Depends(Injector(TaskService))]
```

This guarantees 100% compatibility with FastAPI's endpoint dependency resolver and OpenAPI schema generators, while delegating object graph resolution directly to ZCore's `IoCContainer`.

<Callout type="warn" emoji="⚠️">
  **Bracket Notation Required:**
  Always use generic bracket notation (`Inject[Type]`), never function call syntax (`Inject(Type)`). `Inject` relies on Python's `__class_getitem__` class method to generate `Annotated` type wrappers.
</Callout>

***

## Route Usage Example [#route-usage-example]

Use `Inject[T]` to inject services, repositories, or external providers directly into FastAPI router endpoints without boilerplate:

```python
from fastapi import APIRouter
from zcore import Inject
from .services import TaskService

router = APIRouter(prefix="/tasks", tags=["Tasks"])

@router.get("/")
async def get_all_tasks(service: Inject[TaskService]):
    # 'service' is resolved dynamically via container.resolve(TaskService)
    return await service.get_list()
```

<Callout type="info" emoji="💡">
  **Constructor vs Route Injection:**

  * **In FastAPI Routes:** Use `service: Inject[TaskService]` as a type annotation.
  * **In Class Constructors (`__init__`):** Plain Python type hints (`def __init__(self, repo: TaskRepo):`) are sufficient. ZCore's IoC container inspects signatures and auto-wires dependencies automatically.
</Callout>

***

## Helper Class: `Injector` [#helper-class-injector]

A callable wrapper class that integrates standard container resolution lookups with FastAPI's `Depends` system.

```python
from typing import Type, Any
from zcore.kernel.di import container

class Injector:
    def __init__(self, interface: Type[Any]):
        self.interface = interface

    async def __call__(self) -> Any:
        return container.resolve(self.interface)
```

<TypeTable
  type="{
  interface: {
    type: 'Type[Any]',
    description: 'The target dependency class or interface to resolve from the IoC container.',
  },
  '__call__()': {
    type: 'Any',
    description: 'Asynchronous dependency callable returning container.resolve(self.interface).',
  }
}"
/>


# IoC Container & Dependency Injection (/docs/api-reference/ioc-container)





The `IoCContainer` manages class instantiation and lifecycles across your application. It handles registration, constructor auto-wiring via cached reflection signatures, and circular dependency detection across **Singleton**, **Scoped**, and **Transient** lifecycles.

## Class Definition [#class-definition]

```python
from zcore.kernel.di import IoCContainer

class IoCContainer:
    def __init__(self) -> None:
        ...
```

***

## Global Instance [#global-instance]

ZCore exposes a pre-initialized global container instance used throughout the framework:

```python
from zcore import container
# or: from zcore.kernel.di import container
```

***

## Registration Methods [#registration-methods]

### `register_singleton` [#register_singleton]

Registers a pre-constructed instance as a shared global singleton.

```python
def register_singleton(self, interface: Type[Any], instance: Any) -> None: ...
```

<TypeTable
  type="{
  interface: {
    type: 'Type[Any]',
    description: 'The interface or class type key to map against.',
  },
  instance: {
    type: 'Any',
    description: 'The pre-constructed object instance to share across the entire application.',
  }
}"
/>

### `register_scoped` [#register_scoped]

Registers a class bound to a request-scoped lifecycle. The class is instantiated once per context scope (`scope_id`) and cached across the dependency graph for the duration of that request.

```python
def register_scoped(self, interface: Type[Any], implementation: Type[Any]) -> None: ...
```

<TypeTable
  type="{
  interface: {
    type: 'Type[Any]',
    description: 'The interface or class type key to map against.',
  },
  implementation: {
    type: 'Type[Any]',
    description: 'The target implementation class to auto-wire per request scope.',
  }
}"
/>

### `register_scoped_instance` [#register_scoped_instance]

Registers a pre-constructed instance directly into the active request scope store.

```python
def register_scoped_instance(self, interface: Type[Any], instance: Any) -> None: ...
```

<TypeTable
  type="{
  interface: {
    type: 'Type[Any]',
    description: 'The interface or class type key to map against.',
  },
  instance: {
    type: 'Any',
    description: 'The active object instance to bind to the active request scope.',
  }
}"
/>

<Callout type="warn" emoji="⚠️">
  Raises `DIException` if invoked outside of an active request scope boundary.
</Callout>

### `register_transient` [#register_transient]

Registers a class bound to a transient lifecycle. A fresh instance is constructed on every resolution call.

```python
def register_transient(self, interface: Type[Any], implementation: Type[Any]) -> None: ...
```

<TypeTable
  type="{
  interface: {
    type: 'Type[Any]',
    description: 'The interface or class type key to map against.',
  },
  implementation: {
    type: 'Type[Any]',
    description: 'The target implementation class to instantiate fresh on demand.',
  }
}"
/>

***

## Resolution & Scope Management [#resolution--scope-management]

### `resolve` [#resolve]

Dynamically evaluates registered bindings (Singleton, Scoped, Transient) or executes constructor auto-wiring to assemble the dependency tree.

```python
def resolve(
    self, 
    interface: Type[T], 
    _stack: Optional[Set[Type[Any]]] = None
) -> T: ...
```

<TypeTable
  type="{
  interface: {
    type: 'Type[T]',
    description: 'The interface or class type to resolve.',
  },
  returns: {
    type: 'T',
    description: 'The fully constructed and resolved instance of type T.',
  }
}"
/>

<Callout type="info" emoji="⚡">
  **Constructor Reflection & Signature Caching:** If a type is not explicitly registered, `resolve` analyzes its `__init__` constructor parameters. Evaluated dependencies are cached in `_dependency_signature_cache` to eliminate reflection overhead on subsequent resolutions.
</Callout>

### `clear_scope` [#clear_scope]

Explicit scope cleanup hook called during middleware teardown to purge request-scoped instances.

```python
def clear_scope(self, scope_id: str | None = None) -> None: ...
```

***

## FastAPI Integration Helpers [#fastapi-integration-helpers]

### `Inject[T]` [#injectt]

Dynamic type marker bridging FastAPI route parameters with the IoC container via `Annotated`:

```python
from zcore import Inject

@router.get("/dashboard")
async def get_dashboard(service: Inject[DashboardService]):
    return await service.get_data()
```

### `Injector` [#injector]

Callable wrapper class converting a type interface lookup into a FastAPI `Depends` resolver.

***

## Background Task & Scope Helpers [#background-task--scope-helpers]

### `background_scope` [#background_scope]

Asynchronous context manager providing an isolated IoC container scope, a dedicated `AsyncSession` database session, and `ZContext` variable storage for background execution independent of the originating HTTP request lifecycle.

```python
from zcore import background_scope

async def process_report():
    async with background_scope(inherit_context=True):
        ...
```

<TypeTable
  type="{
  inherit_context: {
    type: 'bool',
    default: 'True',
    description: 'Whether to clone active request context parameters (such as user_id and scopes) into the background scope.',
  },
  custom_context: {
    type: 'Any',
    description: 'Explicit key-value pairs to set or override in the background context store.',
  }
}"
/>

### `background_task` [#background_task]

Decorator that wraps a background task with an isolated `background_scope` and automatically resolves any unprovided type-annotated parameters from the IoC container. Supports both asynchronous coroutines and synchronous functions (executed in a worker threadpool).

```python
from zcore import background_task
from zcore.db.setup import SessionDep

@background_task
async def send_welcome_email(user_id: uuid.UUID, email_service: EmailService):
    await email_service.send(user_id)
```

<Callout type="warn" emoji="⚠️">
  Passing an active request `AsyncSession` directly as an argument to background tasks is discouraged. Let `@background_task` automatically inject a dedicated, isolated session.
</Callout>

***

## Exceptions [#exceptions]

### `CircularDependencyError` [#circulardependencyerror]

Raised when a cyclic resolution loop is detected during dependency auto-wiring (e.g., `ServiceA -> ServiceB -> ServiceA`). Inherits from `DIException`.

### `DIException` [#diexception]

Base exception class for all container-level dependency injection runtime errors.


# Kernel & Plugin Architecture (/docs/api-reference/kernel)





The `Kernel` is the central core coordinator for the application lifespan and modular plugins. It assembles registered plugins into a Directed Acyclic Graph (DAG), resolves inter-plugin dependencies topologically, and orchestrates deterministic lifespan transitions.

## Class Definition [#class-definition]

```python
from zcore import Kernel
# or: from zcore.kernel.engine import Kernel

class Kernel:
    def __init__(self) -> None:
        ...
```

***

## Properties [#properties]

<TypeTable
  type="{
  plugins: {
    type: 'Dict[str, Plugin]',
    description: 'Internal mapping of registered plugin instances keyed by their unique string names.',
  },
  dispatcher: {
    type: 'EventDispatcher',
    description: 'The central asynchronous application event dispatcher instance.',
  },
  _sorted_plugins: {
    type: 'List[Plugin]',
    description: 'Cached sequence of sorted plugin instances after topological dependency resolution.',
  }
}"
/>

***

## Methods [#methods]

### `add_plugin` [#add_plugin]

Registers an application plugin instance into the Kernel's local registry.

```python
def add_plugin(self, plugin: Plugin) -> None: ...
```

<TypeTable
  type="{
  plugin: {
    type: 'Plugin',
    description: 'The modular plugin instance conforming to the Plugin protocol interface.',
  }
}"
/>

### `setup` [#setup]

Initializes plugin structures and registers core singletons in the IoC container. Sorts dependencies topologically, calls `plugin.setup(app)` on each plugin, and registers `EventDispatcher`.

```python
def setup(self, app: FastAPI) -> None: ...
```

<TypeTable
  type="{
  app: {
    type: 'FastAPI',
    description: 'The root FastAPI application instance.',
  }
}"
/>

<Callout type="info" emoji="⚙️">
  **Dependency Resolution (`_resolve_dependencies`):** During `setup()`, the Kernel builds a dependency graph from declared plugin structures using `graphlib.TopologicalSorter`. It asserts graph integrity, raising a `RuntimeError` if a missing dependency is detected or if a cyclic dependency loop exists.
</Callout>

### `lifespan` [#lifespan]

Asynchronous context manager governing the active FastAPI application lifespan. Sequentially invokes startup lifecycle phases on sorted plugins and guarantees clean, reversed teardown triggers upon termination, including automatic database and cache connection disposal.

```python
@asynccontextmanager
async def lifespan(self, app: FastAPI) -> AsyncGenerator[None, None]: ...
```

<TypeTable
  type="{
  app: {
    type: 'FastAPI',
    description: 'The active running FastAPI instance.',
  },
  returns: {
    type: 'AsyncGenerator[None, None]',
    description: 'An active async execution state context manager.',
  }
}"
/>

<Callout type="warn" emoji="⚠️">
  **Lifespan Execution Order:**

  * **Startup (Topological Order):** `before_startup` $\rightarrow$ `on_startup` $\rightarrow$ `after_startup`.
  * **Shutdown (Reversed Topological Order):** `on_shutdown` is invoked in strictly reversed dependency order to ensure upstream resources remain available until dependents have closed cleanly. Following plugin shutdowns, automatic teardown of the cache subsystem (`close_cache()`) and database engine (`db_manager.close()`) is performed.
</Callout>

***

## The `Plugin` Protocol [#the-plugin-protocol]

Any domain module intended to plug into the ZCore Kernel must implement the runtime-checkable `Plugin` protocol:

```python
from typing import Protocol, runtime_checkable
from fastapi import FastAPI

@runtime_checkable
class Plugin(Protocol):
    name: str
    version: str
    dependencies: list[str]

    def setup(self, app: FastAPI) -> None: ...
    async def before_startup(self) -> None: ...
    async def on_startup(self) -> None: ...
    async def after_startup(self) -> None: ...
    async def on_shutdown(self) -> None: ...
```

<TypeTable
  type="{
  name: {
    type: 'str',
    description: 'Unique string identifying the plugin domain (e.g., &#x22;auth&#x22;, &#x22;tasks&#x22;).',
  },
  version: {
    type: 'str',
    description: 'Semantic version string description of the plugin.',
  },
  dependencies: {
    type: 'list[str]',
    description: 'List of upstream plugin names that must be initialized and started before this plugin.',
  }
}"
/>


# LocalStorageProvider (/docs/api-reference/local-storage-provider)





`LocalStorageProvider` implements storage operations targeting the host filesystem. It defends against path traversal attacks by enforcing strict path bounds checks, generates high-entropy collision-free identifiers, resolves web-accessible URL paths dynamically, and evaluates uploaded files through configurable security validators.

## Class Definition [#class-definition]

```python
from typing import Optional, List
from zcore.storage import LocalStorageProvider, StorageProvider, BaseStorageValidator

class LocalStorageProvider(StorageProvider):
    def __init__(
        self, 
        base_path: str = "./storage", 
        url_prefix: str = "/storage", 
        validators: Optional[List[BaseStorageValidator]] = None
    ) -> None:
        ...
```

***

## Initialization Parameters [#initialization-parameters]

<TypeTable
  type="{
  base_path: {
    type: 'str',
    default: '&#x22;./storage&#x22;',
    description: 'The root directory reserved for file uploads.',
  },
  url_prefix: {
    type: 'str',
    default: '&#x22;/storage&#x22;',
    description: 'The normalized HTTP URL prefix mapped to exposed static assets.',
  },
  validators: {
    type: 'List[BaseStorageValidator] | None',
    default: '[]',
    description: 'A list of security/validation rules (e.g., SafeMimeTypeValidator, MaxFileSizeValidator) executed against uploaded files.',
  }
}"
/>

***

## Methods [#methods]

### `upload` [#upload]

Uploads an incoming file to the local directory. Runs configured validators, generates a collision-resistant UUID filename, and asynchronously streams chunks to disk.

```python
async def upload(self, file: UploadFile, folder: str = "") -> str: ...
```

<TypeTable
  type="{
  file: {
    type: 'UploadFile',
    description: 'The FastAPI UploadFile payload to validate and persist.',
  },
  folder: {
    type: 'str',
    default: '&#x22;&#x22;',
    description: 'Subdirectory categorization partition (e.g., &#x22;avatars&#x22; or &#x22;documents&#x22;).',
  },
  returns: {
    type: 'str',
    description: 'The normalized web URL path of the saved file. Raises AppException on traversal or save failures.',
  }
}"
/>

### `upload_stream` [#upload_stream]

Directly streams binary raw chunks from an asynchronous generator to a local file destination.

```python
async def upload_stream(
    self, 
    file_stream: AsyncGenerator[bytes, None], 
    filename: str, 
    folder: str = ""
) -> str: ...
```

<TypeTable
  type="{
  file_stream: {
    type: 'AsyncGenerator[bytes, None]',
    description: 'An asynchronous generator yielding raw chunks of file bytes.',
  },
  filename: {
    type: 'str',
    description: 'Target filename to assign to the streamed asset.',
  },
  folder: {
    type: 'str',
    default: '&#x22;&#x22;',
    description: 'Subdirectory categorization partition.',
  },
  returns: {
    type: 'str',
    description: 'The normalized web URL path of the saved file.',
  }
}"
/>

### `delete` [#delete]

Securely removes a file from local storage using its physical path or web URL. Asserts that the target path resides within `base_path` before unlinking to prevent arbitrary file deletion exploits.

```python
async def delete(self, file_path_or_url: str) -> bool: ...
```

<TypeTable
  type="{
  file_path_or_url: {
    type: 'str',
    description: 'Stored web URL or relative/absolute path of the file to remove.',
  },
  returns: {
    type: 'bool',
    description: 'True if unlinking succeeds, False if path traversal is detected or deletion fails.',
  }
}"
/>

### `exists` [#exists]

Verifies the physical presence of an asset within the local storage sandbox using its web URL or relative path.

```python
async def exists(self, file_path_or_url: str) -> bool: ...
```

<TypeTable
  type="{
  file_path_or_url: {
    type: 'str',
    description: 'Stored web URL or relative path of the target file.',
  },
  returns: {
    type: 'bool',
    description: 'True if the target file exists and is within storage boundaries, False otherwise.',
  }
}"
/>

### `get_url` [#get_url]

Resolves the normalized web-accessible URL for a stored asset.

```python
async def get_url(self, file_path_or_url: str) -> str: ...
```

<TypeTable
  type="{
  file_path_or_url: {
    type: 'str',
    description: 'Stored web URL or relative path of the target file.',
  },
  returns: {
    type: 'str',
    description: 'The normalized web URL string.',
  }
}"
/>

<Callout type="warn" emoji="🛡️">
  **Path Traversal Prevention:**
  `LocalStorageProvider` normalizes paths and validates sandbox boundaries against `base_path`. Operations attempting directory breakouts (e.g., `../../etc/passwd`) are blocked immediately.
</Callout>


# Pagination (/docs/api-reference/pagination)





ZCore provides two distinct pagination engines for relational SQLAlchemy queries: &#x2A;*`PageNumberPagination`*&#x2A; (offset-based with optional total count queries) and &#x2A;*`CursorPagination`** (keyset-based with URL-safe Base64 coordinate tokens and dynamic primary key inspection).

## Module Imports [#module-imports]

All pagination classes and parameter models can be imported directly from the root package or the database subsystem:

```python
from zcore import (
    BasePagination,
    CursorPagination,
    CursorParams,
    PageNumberPagination,
    PageNumberParams,
    PaginatedResult,
)
# or: from zcore.db.pagination import ...
```

***

## Result Container: `PaginatedResult[T]` [#result-container-paginatedresultt]

A standardized generic envelope housing the retrieved slice of database entities alongside structural metadata.

```python
class PaginatedResult(Generic[T]):
    def __init__(self, data: Sequence[T], meta: dict[str, Any]):
        self.data = data
        self.meta = meta
```

<TypeTable
  type="{
  data: {
    type: 'Sequence[T]',
    description: 'The list or sequence of retrieved model entities.',
  },
  meta: {
    type: 'dict[str, Any]',
    description: 'Structural pagination metadata (e.g., page, total_pages, next_cursor, has_more).',
  }
}"
/>

***

## Parameter Models [#parameter-models]

### `PageNumberParams` [#pagenumberparams]

Pydantic V2 schema validating query parameters for offset-based pagination. Page sizes are automatically bounded between `1` and `settings.PAGINATION_MAX_SIZE`.

```python
class PageNumberParams(BaseModel):
    page: int = Field(default=1, ge=1)
    size: int | None = None
    sort_by: str | None = None
    sort_order: Literal["asc", "desc"] = "asc"
    include_count: bool = True
```

<TypeTable
  type="{
  page: {
    type: 'int',
    default: '1',
    description: 'Target page number (must be >= 1).',
  },
  size: {
    type: 'int | None',
    default: 'settings.PAGINATION_DEFAULT_SIZE (20)',
    description: 'Maximum records per page. Automatically clamped to settings.PAGINATION_MAX_SIZE (100).',
  },
  sort_by: {
    type: 'str | None',
    default: 'None',
    description: 'Model attribute name to apply sorting on. Validated against model columns.',
  },
  sort_order: {
    type: 'Literal[&#x22;asc&#x22;, &#x22;desc&#x22;]',
    default: '&#x22;asc&#x22;',
    description: 'Sorting direction for the sort_by column.',
  },
  include_count: {
    type: 'bool',
    default: 'True',
    description: 'When True, executes a count subquery to calculate total records and pages. When False, uses limit(size + 1) to determine has_next without count overhead.',
  }
}"
/>

### `CursorParams` [#cursorparams]

Pydantic V2 schema validating query parameters for keyset-based cursor pagination.

```python
class CursorParams(BaseModel):
    cursor: str | None = None
    size: int | None = None
```

<TypeTable
  type="{
  cursor: {
    type: 'str | None',
    default: 'None',
    description: 'URL-safe Base64-encoded keyset cursor coordinate. If None, queries from the start.',
  },
  size: {
    type: 'int | None',
    default: 'settings.PAGINATION_DEFAULT_SIZE (20)',
    description: 'Maximum records per dataset. Clamped to settings.PAGINATION_MAX_SIZE (100).',
  }
}"
/>

***

## Pagination Engines [#pagination-engines]

### `PageNumberPagination[T]` [#pagenumberpaginationt]

Offset-based pagination strategy supporting dynamic column sorting and optional count execution.

```python
class PageNumberPagination(BasePagination[T]):
    params_class = PageNumberParams

    async def paginate(
        self,
        session: AsyncSession,
        query: Select,
        params: PageNumberParams,
        model: Any
    ) -> PaginatedResult[T]: ...
```

#### Execution Logic [#execution-logic]

1. Computes SQL offset: `(params.page - 1) * params.size`.
2. Validates `sort_by` against model columns via SQLAlchemy reflection, raising `ValidationError` if the column does not exist.
3. If `include_count=True`:
   * Executes a `func.count()` subquery without ordering to compute `total` and `total_pages`.
   * Queries the bounded slice via `query.offset(offset).limit(size)`.
4. If `include_count=False`:
   * Queries `limit(size + 1)`. If the returned items exceed `size`, sets `has_next = True` and trims the extra item, avoiding count scans on large tables.

#### Generated `meta` Structure [#generated-meta-structure]

```json
{
  "total": 150,
  "page": 1,
  "size": 20,
  "total_pages": 8,
  "has_next": true,
  "has_prev": false
}
```

***

### `CursorPagination[T]` [#cursorpaginationt]

High-performance keyset pagination strategy designed for infinite feeds and high-throughput tables. It relies on indexed inequality comparisons (`WHERE col < val`) rather than expensive `OFFSET` scans.

```python
class CursorPagination(BasePagination[T]):
    params_class = CursorParams

    def __init__(
        self,
        cursor_field: str | None = None,
        order: str = "desc"
    ): ...

    async def paginate(
        self,
        session: AsyncSession,
        query: Select,
        params: CursorParams,
        model: Any
    ) -> PaginatedResult[T]: ...
```

<TypeTable
  type="{
  cursor_field: {
    type: 'str | None',
    default: 'None',
    description: 'Model attribute key used as coordinate. If None, dynamically inspects the declarative model and defaults to its primary key column.',
  },
  order: {
    type: 'str',
    default: '&#x22;desc&#x22;',
    description: 'Sorting direction (&#x22;asc&#x22; or &#x22;desc&#x22;).',
  }
}"
/>

#### Dynamic Primary Key Inspection & Tie-Breaking [#dynamic-primary-key-inspection--tie-breaking]

When paginating by non-unique fields (e.g. `created_at`), duplicate timestamps can cause missing records. `CursorPagination` automatically pairs the coordinate field with the model's primary key (`pk`):

* **Desc Order:** `WHERE (col < val) OR (col == val AND pk < last_pk)`
* **Asc Order:** `WHERE (col > val) OR (col == val AND pk > last_pk)`

The cursor string is an opaque, URL-safe Base64 token encoding `{"value": ..., "pk": ...}`. Type coercion safely handles datetime ISO strings, integer IDs, and UUID instances automatically.

#### Generated `meta` Structure [#generated-meta-structure-1]

```json
{
  "next_cursor": "eyJ2YWx1ZSI6ICIyMDI2LTA4LTE1VDA4OjAwOjAwIiwgInBrIjogImExYjJjM2Q0Li4uIn0",
  "has_more": true,
  "size": 20
}
```

***

## Standalone Usage Example [#standalone-usage-example]

You can use pagination engines directly on raw SQLAlchemy queries without inheriting from `BaseRepository` or `BaseRouter`:

```python
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
from zcore.db.pagination import CursorPagination, CursorParams
from my_app.models import Task

async def fetch_tasks_feed(
    db: AsyncSession, 
    cursor_token: str | None = None, 
    page_size: int = 25
):
    query = select(Task)
    params = CursorParams(cursor=cursor_token, size=page_size)
    
    # Defaults to primary key if cursor_field is omitted
    paginator = CursorPagination(order="desc")
    result = await paginator.paginate(db, query, params, model=Task)
    
    return {
        "items": result.data,
        "next_cursor": result.meta["next_cursor"],
        "has_more": result.meta["has_more"]
    }
```

***

## Router Configuration [#router-configuration]

To configure pagination on a `BaseRouter`, set `pagination_class`:

```python
from zcore import BaseRouter
from zcore.db.pagination import CursorPagination, PageNumberPagination

class TaskRouter(BaseRouter):
    model = Task
    service = TaskService
    
    # 1. Keyset Cursor Pagination (GET /tasks accepts cursor & size)
    pagination_class = CursorPagination
    
    # 2. Or Page-Number Pagination (GET /tasks accepts page, size, sort_by, etc.)
    # pagination_class = PageNumberPagination
```

<Callout type="info" emoji="⚙️">
  **Tunable Defaults in Settings:**
  Fallback boundaries across all pagination parameters are managed centrally via `.env`:

  * `PAGINATION_DEFAULT_SIZE` (Default: `20`)
  * `PAGINATION_MAX_SIZE` (Default: `100`)
</Callout>


# Plugin Protocol (/docs/api-reference/plugin)





The `Plugin` module defines the structured contract interface (a `runtime_checkable` Protocol) that all modular ZCore domain plugins must satisfy to register with the central application orchestrator `Kernel`.

## Protocol Definition [#protocol-definition]

```python
from typing import Protocol, runtime_checkable
from fastapi import FastAPI
from zcore import Plugin

@runtime_checkable
class Plugin(Protocol):
    name: str
    version: str
    dependencies: list[str]

    def setup(self, app: FastAPI) -> None: ...
    async def before_startup(self) -> None: ...
    async def on_startup(self) -> None: ...
    async def after_startup(self) -> None: ...
    async def on_shutdown(self) -> None: ...
```

***

## Required Protocol Attributes [#required-protocol-attributes]

<TypeTable
  type="{
  name: {
    type: 'str',
    description: 'Unique string identifying the plugin module (e.g., &#x22;tasks&#x22;, &#x22;billing&#x22;).',
  },
  version: {
    type: 'str',
    description: 'Semantic version description string of the plugin (e.g., &#x22;0.1.0&#x22;).',
  },
  dependencies: {
    type: 'list[str]',
    description: 'Identifiers listing direct upstream plugin dependency names that must initialize before this plugin.',
  }
}"
/>

***

## Lifecycle Methods [#lifecycle-methods]

All classes implementing `Plugin` must provide these lifecycle methods:

### `setup` [#setup]

Executes core module registration tasks and attaches routers/middlewares to the FastAPI app. Invoked during `kernel.setup(app)`.

```python
def setup(self, app: FastAPI) -> None: ...
```

<TypeTable
  type="{
  app: {
    type: 'FastAPI',
    description: 'The parent FastAPI application instance.',
  },
  returns: {
    type: 'None',
  }
}"
/>

### `before_startup` [#before_startup]

Performs pre-initialization operations before any other application startup phases begin.

```python
async def before_startup(self) -> None: ...
```

### `on_startup` [#on_startup]

Executes core asynchronous logic during application startup (e.g., warming local caches, validating external services).

```python
async def on_startup(self) -> None: ...
```

### `after_startup` [#after_startup]

Executes post-initialization processes after all plugins have finished their primary startup phases.

```python
async def after_startup(self) -> None: ...
```

### `on_shutdown` [#on_shutdown]

Performs graceful cleanup and releases external resources (e.g., connection pools, background workers) during application termination.

```python
async def on_shutdown(self) -> None: ...
```

***

## Implementation Example [#implementation-example]

```python
from fastapi import FastAPI
from zcore import Plugin
from .routers import router_instance

class TasksPlugin(Plugin):
    name: str = "tasks"
    version: str = "1.0.0"
    dependencies: list[str] = ["auth"]  # Requires AuthPlugin to start first

    def setup(self, app: FastAPI) -> None:
        # Attach this module's sub-router to the main app
        app.include_router(router_instance.router)

    async def before_startup(self) -> None:
        pass

    async def on_startup(self) -> None:
        # Perform startup logic
        pass

    async def after_startup(self) -> None:
        pass

    async def on_shutdown(self) -> None:
        # Cleanup resources
        pass
```

<Callout type="info" emoji="💡">
  **Scaffolding Plugins:** Running `zc startapp <name> --template` in your terminal automatically generates a populated `plugin.py` file satisfying this protocol.
</Callout>


# BaseRepository (/docs/api-reference/repository)





`BaseRepository` provides standard asynchronous database access, combining Read, Write, Bulk Mutation, Soft-Delete Restoration, and Search capabilities. It decouples business logic from SQLAlchemy 2.0 sessions and enforces context security through model-level query scoping.

## Class Definition [#class-definition]

```python
from typing import Generic, TypeVar
from sqlalchemy.ext.asyncio import AsyncSession
from zcore import BaseRepository
from zcore.db.setup import Base

ModelType = TypeVar("ModelType", bound=Base)

class BaseRepository(
    Generic[ModelType],
    ReadRepositoryMixin[ModelType],
    WriteRepositoryMixin[ModelType],
    SearchRepositoryMixin[ModelType]
):
    def __init__(self, model: type[ModelType], db: AsyncSession):
        ...
```

***

## Properties [#properties]

<TypeTable
  type="{
  db: {
    type: 'AsyncSession',
    description: 'The active asynchronous database session.',
  },
  model: {
    type: 'type[ModelType]',
    description: 'The SQLAlchemy declarative model class bound to the repository.',
  },
  pk: {
    type: 'Any',
    description: 'The SQLAlchemy primary key column representation of the bound model.',
  },
  pk_name: {
    type: 'str',
    description: 'The string identifier name of the primary key field (e.g., &#x22;id&#x22;).',
  },
  cursor_field: {
    type: 'str',
    default: 'self.pk_name',
    description: 'The model field used to coordinate boundary coordinates during keyset cursor pagination.',
  }
}"
/>

***

## Query Scoping & Soft Delete (`_get_base_query`) [#query-scoping--soft-delete-_get_base_query]

`BaseRepository` constructs its initial `SELECT` statements via `_get_base_query()`.

If your SQLAlchemy model declares a classmethod named &#x2A;*`scope_query`** (or inherits from `SoftDeleteMixin`), `_get_base_query()` automatically passes the query through this hook before applying any route-level filters:

```python
# Internal mechanics in BaseRepository
def _get_base_query(self) -> Select:
    query = select(self.model)
    scoper = getattr(self.model, "scope_query", None)
    if scoper:
        return scoper(query)
    return query

def _supports_soft_delete(self) -> bool:
    """Determine whether the underlying model implements SoftDeleteMixin."""
    return hasattr(self.model, "deleted_at") and hasattr(self.model, "soft_delete")
```

<Callout type="info" emoji="💡">
  **Model Scoping Hooks:**

  ```python
  # Inheriting SoftDeleteMixin automatically filters out deleted records
  class Task(Base, SoftDeleteMixin):
      __tablename__ = "tasks"
      ...
  ```

  All read, listing, count, search, and existence queries automatically apply row-level scoping and soft-deletion filters.
</Callout>

***

## Read Methods [#read-methods]

### `get` [#get]

Fetches a single model instance matching dynamic criteria.

```python
async def get(
    self, 
    *criterion: Any, 
    fields: list[Any] | None = None, 
    options: list[ExecutableOption] | None = None,
    **filters: Any
) -> ModelType | None: ...
```

<TypeTable
  type="{
  '*criterion': {
    type: 'Any',
    description: 'Positional binary SQLAlchemy filter expressions (e.g., Task.status == &#x22;active&#x22;).',
  },
  fields: {
    type: 'list[Any] | None',
    default: 'None',
    description: 'Specific entity attributes to selectively load (load_only).',
  },
  options: {
    type: 'list[ExecutableOption] | None',
    default: 'None',
    description: 'SQLAlchemy execution/loader options (e.g., joinedload, selectinload).',
  },
  '**filters': {
    type: 'Any',
    description: 'Keyword arguments for standard equality filters (e.g., is_completed=True).',
  },
  returns: {
    type: 'ModelType | None',
    description: 'The retrieved database model instance, or None if not found.',
  }
}"
/>

### `get_by_ids` [#get_by_ids]

Fetches a sequence of records matching a list of primary keys in a single query.

```python
async def get_by_ids(
    self, 
    ids: list[Any], 
    fields: list[Any] | None = None, 
    options: list[ExecutableOption] | None = None
) -> Sequence[ModelType]: ...
```

<TypeTable
  type="{
  ids: {
    type: 'list[Any]',
    description: 'A list of primary key values to retrieve.',
  },
  fields: {
    type: 'list[Any] | None',
    default: 'None',
    description: 'Specific entity attributes to selectively load.',
  },
  options: {
    type: 'list[ExecutableOption] | None',
    default: 'None',
    description: 'SQLAlchemy execution options.',
  },
  returns: {
    type: 'Sequence[ModelType]',
    description: 'A sequence of retrieved database model instances.',
  }
}"
/>

### `get_list` [#get_list]

Fetches a paginated or complete listing of records.

```python
async def get_list(
    self, 
    *criterion: Any,
    pagination: Any = None, 
    fields: list[Any] | None = None, 
    options: list[ExecutableOption] | None = None,
    **filters: Any
) -> Sequence[ModelType] | PaginatedResult[ModelType]: ...
```

<TypeTable
  type="{
  '*criterion': {
    type: 'Any',
    description: 'Positional binary SQLAlchemy filter expressions.',
  },
  pagination: {
    type: 'PageNumberParams | CursorParams | None',
    default: 'None',
    description: 'Pagination parameter schema. If None, returns all unpaginated records.',
  },
  fields: {
    type: 'list[Any] | None',
    default: 'None',
    description: 'Specific entity attributes to selectively load.',
  },
  options: {
    type: 'list[ExecutableOption] | None',
    default: 'None',
    description: 'SQLAlchemy execution loader options.',
  },
  '**filters': {
    type: 'Any',
    description: 'Keyword key-value arguments for equality filters.',
  },
  returns: {
    type: 'Sequence[ModelType] | PaginatedResult[ModelType]',
    description: 'A list of matching records or a PaginatedResult container.',
  }
}"
/>

### `exist` [#exist]

Checks if records matching the filters exist in the database (automatically applies `scope_query`).

```python
async def exist(self, *criterion: Any, **filters: Any) -> bool: ...
```

<TypeTable
  type="{
  '*criterion': {
    type: 'Any',
    description: 'Positional binary SQLAlchemy filter expressions.',
  },
  '**filters': {
    type: 'Any',
    description: 'Keyword arguments for standard equality filters.',
  },
  returns: {
    type: 'bool',
    description: 'True if matching records exist, False otherwise.',
  }
}"
/>

### `count` [#count]

Counts records matching dynamic criteria.

```python
async def count(self, *criterion: Any, **filters: Any) -> int: ...
```

<TypeTable
  type="{
  '*criterion': {
    type: 'Any',
    description: 'Positional binary SQLAlchemy filter expressions.',
  },
  '**filters': {
    type: 'Any',
    description: 'Keyword arguments for standard equality filters.',
  },
  returns: {
    type: 'int',
    description: 'The total volume of matching records.',
  }
}"
/>

***

## Write, Bulk Mutation & Restoration Methods [#write-bulk-mutation--restoration-methods]

### `create` [#create]

Creates and persists a single record from a Pydantic schema.

```python
async def create(self, schema: BaseModel, **extra_data: Any) -> ModelType: ...
```

<TypeTable
  type="{
  schema: {
    type: 'BaseModel',
    description: 'Validated Pydantic schema containing properties for the new record.',
  },
  '**extra_data': {
    type: 'Any',
    description: 'Dynamic fields to merge into the payload before database insertion.',
  },
  returns: {
    type: 'ModelType',
    description: 'The created and refreshed database model instance.',
  }
}"
/>

### `create_multi` [#create_multi]

Creates multiple database records with dialect-aware fallback for returning support.

```python
async def create_multi(
    self, 
    schemas: list[BaseModel], 
    refresh: bool = False
) -> Sequence[ModelType]: ...
```

<TypeTable
  type="{
  schemas: {
    type: 'list[BaseModel]',
    description: 'A list of Pydantic schemas representing the new database objects.',
  },
  refresh: {
    type: 'bool',
    default: 'False',
    description: 'If True, executes an explicit database refresh on each record individually.',
  },
  returns: {
    type: 'Sequence[ModelType]',
    description: 'A sequence of created database model instances.',
  }
}"
/>

### `update` [#update]

Updates an existing database record from a model instance or primary key.

```python
async def update(
    self, 
    target: ModelType | Any, 
    schema: BaseModel, 
    partial: bool = False, 
    **extra_data: Any
) -> ModelType | None: ...
```

<TypeTable
  type="{
  target: {
    type: 'ModelType | Any',
    description: 'The model instance or primary key identifier of the record to update.',
  },
  schema: {
    type: 'BaseModel',
    description: 'The Pydantic update schema containing modified parameters.',
  },
  partial: {
    type: 'bool',
    default: 'False',
    description: 'If True, applies modifications as a partial patch (ignoring unset fields).',
  },
  '**extra_data': {
    type: 'Any',
    description: 'Dynamic fields to merge into the update payload.',
  },
  returns: {
    type: 'ModelType | None',
    description: 'The updated and refreshed model instance, or None if not found.',
  }
}"
/>

### `update_multi` [#update_multi]

Bulk updates multiple database records using DBAPI executemany.

```python
async def update_multi(
    self, 
    data: dict[ModelType | Any, BaseModel], 
    partial: bool = False, 
    refresh: bool = False
) -> Sequence[ModelType]: ...
```

<TypeTable
  type="{
  data: {
    type: 'dict[ModelType | Any, BaseModel]',
    description: 'A mapping of model instances or primary keys to their update schemas.',
  },
  partial: {
    type: 'bool',
    default: 'False',
    description: 'If True, ignores unset schema fields.',
  },
  refresh: {
    type: 'bool',
    default: 'False',
    description: 'Maintained for interface consistency.',
  },
  returns: {
    type: 'Sequence[ModelType]',
    description: 'A sequence containing the updated database model instances.',
  }
}"
/>

### `delete` [#delete]

Deletes a single record by its model instance or primary key identifier. Automatically applies soft-deletion if supported by the model unless `force=True`.

```python
async def delete(self, target: ModelType | Any, force: bool = False) -> ModelType | None: ...
```

<TypeTable
  type="{
  target: {
    type: 'ModelType | Any',
    description: 'The model instance or primary key value of the target record to delete.',
  },
  force: {
    type: 'bool',
    default: 'False',
    description: 'If True, executes a permanent physical hard deletion even if SoftDeleteMixin is present.',
  },
  returns: {
    type: 'ModelType | None',
    description: 'The deleted or soft-deleted database model instance, or None if not found.',
  }
}"
/>

### `delete_multi` [#delete_multi]

Deletes multiple records matching the provided list of primary keys. Automatically executes an atomic soft-delete update (`deleted_at = now()`) unless `force=True`.

```python
async def delete_multi(self, ids: list[Any], force: bool = False) -> Sequence[ModelType]: ...
```

<TypeTable
  type="{
  ids: {
    type: 'list[Any]',
    description: 'A list of primary key values of records to delete.',
  },
  force: {
    type: 'bool',
    default: 'False',
    description: 'If True, executes permanent physical hard deletions.',
  },
  returns: {
    type: 'Sequence[ModelType]',
    description: 'A sequence containing the deleted or soft-deleted database model instances.',
  }
}"
/>

### `restore` [#restore]

Restores a previously soft-deleted record by primary key or model instance.

```python
async def restore(self, target: ModelType | Any) -> ModelType | None: ...
```

<TypeTable
  type="{
  target: {
    type: 'ModelType | Any',
    description: 'The model instance or primary key value of the soft-deleted record to restore.',
  },
  returns: {
    type: 'ModelType | None',
    description: 'The restored database model instance, or None if not found or unsupported.',
  }
}"
/>

### `restore_multi` [#restore_multi]

Restores multiple soft-deleted records using an atomic batch `UPDATE ... WHERE deleted_at IS NOT NULL` statement with dialect-aware `RETURNING` optimization.

```python
async def restore_multi(self, ids: list[Any]) -> Sequence[ModelType]: ...
```

<TypeTable
  type="{
  ids: {
    type: 'list[Any]',
    description: 'A list of primary key values of records to restore.',
  },
  returns: {
    type: 'Sequence[ModelType]',
    description: 'A sequence of restored database model instances.',
  }
}"
/>

***

## Search Methods [#search-methods]

### `search` [#search]

Dynamically parses and executes a structured `SearchRequest` with automatic security checks, inverted operators, logical negation, column projection, and relation eager-loading.

```python
async def search(
    self, 
    search_in: SearchRequest, 
    pagination: Any = None,
    fields: list[Any] | None = None,
    options: list[ExecutableOption] | None = None,
) -> Sequence[ModelType] | PaginatedResult[ModelType]: ...
```

<TypeTable
  type="{
  search_in: {
    type: 'SearchRequest',
    description: 'The dynamic search parameter model containing filters, includes, and sorting.',
  },
  pagination: {
    type: 'PageNumberParams | CursorParams | None',
    default: 'None',
    description: 'Pagination settings to apply to search results.',
  },
  fields: {
    type: 'list[Any] | None',
    default: 'None',
    description: 'Specific entity attributes to selectively load (load_only).',
  },
  options: {
    type: 'list[ExecutableOption] | None',
    default: 'None',
    description: 'Additional SQLAlchemy execution or relation loader options.',
  },
  returns: {
    type: 'Sequence[ModelType] | PaginatedResult[ModelType]',
    description: 'A paginated result wrapper or a list of matched models.',
  }
}"
/>


# ResponseWrapper (/docs/api-reference/response-wrapper)





`ResponseWrapper` is a standardized generic Pydantic model that enforces a consistent payload structure for all application endpoints. It inherits from `Zchema`, meaning the encapsulated `data` payload participates natively in dynamic, role-based field pruning.

## Class Definition [#class-definition]

```python
from typing import Generic, TypeVar, Optional, Any
from zcore import Zchema, ResponseWrapper

T = TypeVar("T")

class ResponseWrapper(Zchema, Generic[T]):
    success: bool = True
    message: str = "Success"
    data: Optional[T] = None
    meta: Optional[dict[str, Any]] = None
```

***

## Attributes [#attributes]

<TypeTable
  type="{
  success: {
    type: 'bool',
    default: 'True',
    description: 'Boolean flag indicating if the HTTP operation was successful.',
  },
  message: {
    type: 'str',
    default: '&#x22;Success&#x22;',
    description: 'Diagnostic string describing the outcome of the request.',
  },
  data: {
    type: 'Optional[T]',
    default: 'None',
    description: 'The typed payload content of the response.',
  },
  meta: {
    type: 'Optional[dict[str, Any]]',
    default: 'None',
    description: 'Optional unstructured key-value metadata (e.g., pagination cursors, error diagnostics).',
  }
}"
/>

***

## Class Methods [#class-methods]

### `success_response` [#success_response]

Convenience factory method constructing a successful `ResponseWrapper` container:

```python
@classmethod
def success_response(
    cls, 
    data: T, 
    message: str = "Success", 
    meta: Optional[dict[str, Any]] = None
) -> ResponseWrapper[T]: ...
```

<TypeTable
  type="{
  data: {
    type: 'T',
    description: 'The primary typed payload to wrap.',
  },
  message: {
    type: 'str',
    default: '&#x22;Success&#x22;',
    description: 'Custom output diagnostic message detailing the outcome.',
  },
  meta: {
    type: 'Optional[dict[str, Any]]',
    default: 'None',
    description: 'Unstructured metadata dictionary (e.g., execution metrics).',
  },
  returns: {
    type: 'ResponseWrapper[T]',
    description: 'A populated ResponseWrapper container instance.',
  }
}"
/>

***

## Usage Example [#usage-example]

```python
from fastapi import APIRouter
from zcore import ResponseWrapper

router = APIRouter()

@router.get("/metrics")
async def get_metrics():
    stats = {"cpu_usage": 12.5, "uptime": 3600}
    return ResponseWrapper.success_response(
        data=stats, 
        message="Metrics resolved successfully"
    )
```

<Callout type="info" emoji="💡">
  **Automatic Router Integration:** When using `BaseRouter`, you do not need to wrap return values manually. The router automatically encloses service outputs inside `ResponseWrapper` and populates pagination cursor metadata directly into `meta`.
</Callout>


# SearchEngine (/docs/api-reference/search)





The `SearchEngine` translates nested JSON filter trees into secure, optimized SQLAlchemy expressions while enforcing configurable depth limits, wildcard escaping, inverted operators, and context security policies.

## Class Definition [#class-definition]

```python
from collections.abc import Callable
from typing import Any, TypeVar
from zcore import SearchRequest
from zcore.config import settings
from zcore.db.setup import Base

ModelType = TypeVar("ModelType", bound=Base)

class SearchEngine:
    def __init__(self, model: type[ModelType]):
        self.model = model
        self.max_depth: int = getattr(
            model,
            "__max_search_depth__",
            getattr(settings, "SEARCH_MAX_DEPTH", 3),
        )
        self.custom_handlers: dict[str, Callable[[Any], Any]] = {}
        ...
```

***

## Properties [#properties]

<TypeTable
  type="{
  model: {
    type: 'type[ModelType]',
    description: 'The root database model bound to this search instance.',
  },
  max_depth: {
    type: 'int',
    default: 'model.__max_search_depth__ -> settings.SEARCH_MAX_DEPTH -> 3',
    description: 'The maximum allowable filter nesting and relation join depth.',
  },
  custom_handlers: {
    type: 'dict[str, Callable[[Any], Any]]',
    description: 'Registered custom translation callbacks mapped to specific field names.',
  }
}"
/>

***

## Methods [#methods]

### `register_handler` [#register_handler]

Binds a custom callback handler to parse a specific field's values dynamically into custom SQL clauses.

```python
def register_handler(
    self, 
    field_name: str, 
    handler: Callable[[Any], Any]
) -> SearchEngine: ...
```

<TypeTable
  type="{
  field_name: {
    type: 'str',
    description: 'The attribute name to register the custom translation handler for.',
  },
  handler: {
    type: 'Callable[[Any], Any]',
    description: 'A callback accepting raw filter values and returning computed SQLAlchemy expressions.',
  },
  returns: {
    type: 'SearchEngine',
    description: 'The current active instance of the SearchEngine for method chaining.',
  }
}"
/>

### `build_base_query` [#build_base_query]

Parses search inputs, validates context security policies, and constructs the base `Select` statement with filters, eager loading joins, and sorting (without limit/offset).

```python
def build_base_query(
    self, 
    search_in: SearchRequest, 
    base_query: Select | None = None
) -> Select: ...
```

<TypeTable
  type="{
  search_in: {
    type: 'SearchRequest',
    description: 'The user-supplied search and filter request model.',
  },
  base_query: {
    type: 'Select | None',
    default: 'None',
    description: 'Optional existing SQLAlchemy Select query to extend. If None, uses select(model).',
  },
  returns: {
    type: 'Select',
    description: 'A secure, compiled SQLAlchemy SELECT statement complete with filters, joins, and sorting.',
  }
}"
/>

### `build_query` [#build_query]

Constructs the base `Select` query and applies size (limit) and page (offset) boundaries.

```python
def build_query(self, search_in: SearchRequest) -> Select: ...
```

<TypeTable
  type="{
  search_in: {
    type: 'SearchRequest',
    description: 'The search and filter request model containing pagination parameters.',
  },
  returns: {
    type: 'Select',
    description: 'A securely configured, size-bounded SQLAlchemy SELECT statement.',
  }
}"
/>

***

## Pydantic Models [#pydantic-models]

### `SearchRequest` [#searchrequest]

Comprehensive request model containing dynamic search parameters. Automatically validates and bounds `size` via `model_validator(mode="after")`.

```python
from zcore import SearchRequest
```

<TypeTable
  type="{
  filters: {
    type: 'list[FilterItem] | None',
    default: '[]',
    description: 'A recursive collection of filter constraints.',
  },
  include: {
    type: 'list[str] | None',
    default: '[]',
    description: 'Relationship dot-paths indicating database relationships to eager load (bounded by max_depth).',
  },
  sort: {
    type: 'list[SortItem] | None',
    default: '[]',
    description: 'Explicit ordering instructions.',
  },
  size: {
    type: 'int | None',
    default: 'settings.PAGINATION_DEFAULT_SIZE (20)',
    description: 'The limit on retrieved records. Clamped between 1 and settings.PAGINATION_MAX_SIZE (100).',
  },
  page: {
    type: 'int',
    default: '1',
    description: 'The target page offset index (min: 1).',
  },
  cursor: {
    type: 'str | None',
    default: 'None',
    description: 'Keyset pagination indicator cursor string.',
  }
}"
/>

### `FilterItem` [#filteritem]

Pydantic model representing a single filtering condition, inverted operator, or nested boolean group.

<TypeTable
  type="{
  field: {
    type: 'str | None',
    default: 'None',
    description: 'The dotted path representation of the field to filter (e.g., &#x22;owner.email&#x22;).',
  },
  op: {
    type: 'Literal[&#x22;eq&#x22;, &#x22;ne&#x22;, &#x22;gt&#x22;, &#x22;lt&#x22;, &#x22;ge&#x22;, &#x22;le&#x22;, &#x22;like&#x22;, &#x22;not_like&#x22;, &#x22;ilike&#x22;, &#x22;not_ilike&#x22;, &#x22;contains&#x22;, &#x22;not_contains&#x22;, &#x22;startswith&#x22;, &#x22;not_startswith&#x22;, &#x22;endswith&#x22;, &#x22;not_endswith&#x22;, &#x22;in&#x22;, &#x22;not_in&#x22;, &#x22;between&#x22;, &#x22;not_between&#x22;, &#x22;is_null&#x22;, &#x22;is_not_null&#x22;, &#x22;or&#x22;, &#x22;and&#x22;, &#x22;not&#x22;]',
    description: 'The comparison, pattern matching, range, inverted operator, or logical grouping operator to evaluate.',
  },
  value: {
    type: 'Any | None',
    default: 'None',
    description: 'The parameter value used during evaluation (e.g., scalar, string, or [min, max] list for between/not_between).',
  },
  items: {
    type: 'list[FilterItem] | None',
    default: 'None',
    description: 'Nested list of sub-filters to evaluate when the operator is &#x22;or&#x22;, &#x22;and&#x22;, or &#x22;not&#x22;.',
  }
}"
/>

<Callout type="info" emoji="⚡">
  **Logical Negation (`not`):**
  When `op="not"` is used with `items`, the sub-expressions are compiled as `not_(and_(*sub_exprs))`. When used with a single `field`, it compiles to `not_(field == value)`.
</Callout>

### `SortItem` [#sortitem]

Pydantic model mapping explicit sorting configurations for query results.

<TypeTable
  type="{
  field: {
    type: 'str',
    description: 'The dotted target field path on the model to sort by.',
  },
  order: {
    type: 'Literal[&#x22;asc&#x22;, &#x22;desc&#x22;]',
    default: '&#x22;asc&#x22;',
    description: 'The direction to apply: &#x22;asc&#x22; (ascending) or &#x22;desc&#x22; (descending).',
  }
}"
/>


# Security Services (/docs/api-reference/security)





The `Security` class is a unified coordinator for cryptographic and authentication operations. It provides memory-hard password hashing (Argon2id), JSON Web Token (JWT) encoding/decoding, secure hexadecimal generation, and SHA-256 digests.

## Class Definition [#class-definition]

```python
from zcore import Security
# or: from zcore.security import Security

class Security:
    ...
```

***

## Password Hashing Methods (Argon2id) [#password-hashing-methods-argon2id]

ZCore configures `argon2-cffi` with dynamic hardware parameter tuning (`memory_cost`, `time_cost`, `parallelism`) from the active `Settings`.

### `hash_password` [#hash_password]

Generates a secure Argon2id hash from a plain-text password.

```python
@staticmethod
def hash_password(password: str) -> str: ...
```

<TypeTable
  type="{
  password: {
    type: 'str',
    description: 'The plain-text password to hash.',
  },
  returns: {
    type: 'str',
    description: 'The computed Argon2id cryptographic hash string.',
  }
}"
/>

### `verify_password` [#verify_password]

Verifies a plain-text password against a stored Argon2id hash.

```python
@staticmethod
def verify_password(plain_password: str, hashed_password: str) -> bool: ...
```

<TypeTable
  type="{
  plain_password: {
    type: 'str',
    description: 'The unhashed candidate password.',
  },
  hashed_password: {
    type: 'str',
    description: 'The valid stored Argon2id hash string.',
  },
  returns: {
    type: 'bool',
    description: 'True if the candidate password matches the hash, False otherwise.',
  }
}"
/>

***

## JWT Methods [#jwt-methods]

### `create_jwt` [#create_jwt]

Creates a signed JWT access token.

```python
@classmethod
def create_jwt(
    cls, 
    data: dict, 
    expires_delta: Optional[timedelta] = None
) -> str: ...
```

<TypeTable
  type="{
  data: {
    type: 'dict',
    description: 'The payload claims dictionary to encode.',
  },
  expires_delta: {
    type: 'timedelta | None',
    default: 'None',
    description: 'Optional custom lifetime duration. Defaults to settings.ACCESS_TOKEN_EXPIRE_MINUTES.',
  },
  returns: {
    type: 'str',
    description: 'The signed JWT token string.',
  }
}"
/>

### `decode_jwt` [#decode_jwt]

Decodes, validates the signature, and checks the expiration of a signed JWT string.

```python
@classmethod
def decode_jwt(cls, token: str) -> dict: ...
```

<TypeTable
  type="{
  token: {
    type: 'str',
    description: 'The signed JWT token string to decode.',
  },
  returns: {
    type: 'dict',
    description: 'The decoded payload claims dictionary. Raises AuthError if expired or structurally invalid.',
  }
}"
/>

### `is_token_expired` [#is_token_expired]

Checks if a Unix timestamp expiration claim has expired against UTC current time.

```python
@staticmethod
def is_token_expired(token_exp: int) -> bool: ...
```

<TypeTable
  type="{
  token_exp: {
    type: 'int',
    description: 'The Unix timestamp integer (the &#x22;exp&#x22; claim) to verify.',
  },
  returns: {
    type: 'bool',
    description: 'True if the timestamp is in the past or missing, False otherwise.',
  }
}"
/>

<Callout type="warn" emoji="🚨">
  **Fail-Fast Production Secret Assertion:**
  The internal key resolver `_get_signing_keys()` actively asserts that if `settings.DEBUG` is `False` (Production) and `settings.SECRET_KEY` matches the default insecure fallback string, application startup is **aborted immediately** with a critical `RuntimeError`.
</Callout>

***

## Cryptographic Utilities [#cryptographic-utilities]

### `generate_secure_token` [#generate_secure_token]

Generates a cryptographically secure random hexadecimal token.

```python
@staticmethod
def generate_secure_token(length: int = 32) -> str: ...
```

<TypeTable
  type="{
  length: {
    type: 'int',
    default: '32',
    description: 'Target byte capacity to encode into hex (results in a string of length*2 characters).',
  },
  returns: {
    type: 'str',
    description: 'A cryptographically secure hex string.',
  }
}"
/>

### `hash_sha256` [#hash_sha256]

Generates a SHA-256 hex digest of the provided string data.

```python
@staticmethod
def hash_sha256(data: str) -> str: ...
```

<TypeTable
  type="{
  data: {
    type: 'str',
    description: 'Raw text parameters to digest.',
  },
  returns: {
    type: 'str',
    description: 'A 64-character hexadecimal SHA-256 hash string.',
  }
}"
/>


# BaseService (/docs/api-reference/service)





`BaseService` orchestrates domain logic, coordinates transaction boundaries via `_safe_commit()`, manages soft-delete recovery lifecycles, and exposes comprehensive single and batch (`_multi`) lifecycle interception hooks.

## Class Definition [#class-definition]

```python
from typing import Generic, TypeVar
from zcore import BaseService
from zcore.db.setup import Base

ModelType = TypeVar("ModelType", bound=Base)

class BaseService(
    Generic[ModelType],
    ReadServiceMixin[ModelType],
    WriteServiceMixin[ModelType],
    SearchServiceMixin[ModelType]
):
    def __init__(self, model: type[ModelType], repository: "BaseRepository"):
        ...
```

***

## Properties [#properties]

<TypeTable
  type="{
  model: {
    type: 'type[ModelType]',
    description: 'The declarative SQLAlchemy model class matching this service domain.',
  },
  repository: {
    type: 'BaseRepository',
    description: 'The data persistence repository layer coordinating model access.',
  }
}"
/>

***

## Read Methods [#read-methods]

### `get` [#get]

Fetches a single domain entity by dynamic filters and applies the `post_get` hook.

```python
async def get(
    self, 
    *criterion: Any, 
    fields: list[Any] | None = None, 
    options: list[ExecutableOption] | None = None,
    **filters: Any
) -> ModelType: ...
```

<TypeTable
  type="{
  '*criterion': {
    type: 'Any',
    description: 'Dynamic positional filter expressions.',
  },
  fields: {
    type: 'list[Any] | None',
    default: 'None',
    description: 'Selective list of model fields to return (load_only).',
  },
  options: {
    type: 'list[ExecutableOption] | None',
    default: 'None',
    description: 'SQLAlchemy execution/loader options.',
  },
  '**filters': {
    type: 'Any',
    description: 'Dynamic keyword equality filters.',
  },
  returns: {
    type: 'ModelType',
    description: 'The processed database model instance. Raises EntityNotFound if not found.',
  }
}"
/>

### `get_by_ids` [#get_by_ids]

Fetches a sequence of domain entities by their identifiers, applying the `post_get_multi` hook.

```python
async def get_by_ids(
    self, 
    ids: list[Any], 
    fields: list[Any] | None = None, 
    options: list[ExecutableOption] | None = None
) -> Sequence[ModelType]: ...
```

### `get_list` [#get_list]

Fetches a paginated or complete listing of entities, applying the `post_get_multi` hook.

```python
async def get_list(
    self, 
    *criterion: Any,
    pagination: Any = None, 
    fields: list[Any] | None = None, 
    options: list[ExecutableOption] | None = None,
    **filters: Any
) -> Sequence[ModelType] | PaginatedResult[ModelType]: ...
```

### `exist` [#exist]

Verifies the existence of a target entity matching criteria in the database.

```python
async def exist(self, *criterion: Any, **filters: Any) -> bool: ...
```

### `count` [#count]

Counts the volume of entities matching dynamic criteria.

```python
async def count(self, *criterion: Any, **filters: Any) -> int: ...
```

***

## Write, Mutation & Restoration Methods [#write-mutation--restoration-methods]

### `create` [#create]

Orchestrates the creation of an entity, merging `pre_create` data, calling `on_create`, executing `post_create`, and invoking `_safe_commit()`.

```python
async def create(self, schema: BaseModel, **extra_data: Any) -> ModelType: ...
```

### `create_multi` [#create_multi]

Orchestrates batch creation of multiple domain entities with `pre_create_multi` / `post_create_multi` lifecycle hooks and safe commit.

```python
async def create_multi(
    self, 
    schemas: list[BaseModel], 
    refresh: bool = False
) -> Sequence[ModelType]: ...
```

### `update` [#update]

Orchestrates modifications to an existing entity, merging `pre_update` data, calling `on_update`, executing `post_update`, and invoking `_safe_commit()`.

```python
async def update(
    self, 
    target: ModelType | Any, 
    schema: BaseModel, 
    partial: bool = False, 
    **extra_data: Any
) -> ModelType: ...
```

### `update_multi` [#update_multi]

Orchestrates batch modifications to multiple existing domain entities with `pre_update_multi` / `post_update_multi` hooks.

```python
async def update_multi(
    self, 
    data: dict[ModelType | Any, BaseModel], 
    partial: bool = False, 
    refresh: bool = False
) -> Sequence[ModelType]: ...
```

### `delete` [#delete]

Orchestrates the deletion of a single entity, triggering `pre_delete(target, force)`, calling `on_delete(target, force)`, executing `post_delete(model, force)`, and invoking `_safe_commit()`.

```python
async def delete(self, target: ModelType | Any, force: bool = False) -> ModelType: ...
```

### `delete_multi` [#delete_multi]

Orchestrates batch deletions of multiple database records matching primary keys with `pre_delete_multi(ids, force)` / `post_delete_multi(models, force)` hooks.

```python
async def delete_multi(self, ids: list[Any], force: bool = False) -> Sequence[ModelType]: ...
```

### `restore` [#restore]

Orchestrates the restoration of a soft-deleted domain entity, triggering `pre_restore`, calling `on_restore`, executing `post_restore`, and invoking `_safe_commit()`.

```python
async def restore(self, target: ModelType | Any) -> ModelType: ...
```

### `restore_multi` [#restore_multi]

Orchestrates batch restorations of multiple soft-deleted records with `pre_restore_multi` / `post_restore_multi` hooks and safe commit.

```python
async def restore_multi(self, ids: list[Any]) -> Sequence[ModelType]: ...
```

***

## Search Methods [#search-methods]

### `search` [#search]

Triggers `pre_search`, executes `on_search` (with optional `fields` load\_only and `options`), and processes results through `post_search`.

```python
async def search(
    self, 
    search_in: SearchRequest, 
    pagination: Any = None,
    fields: list[Any] | None = None,
    options: list[ExecutableOption] | None = None,
) -> Sequence[ModelType] | PaginatedResult[ModelType]: ...
```

***

## Core Execution Methods (`on_*`) [#core-execution-methods-on_]

These methods directly delegate to the bound repository and can be overridden to customize persistence mechanics:

* `async def on_create(self, schema: BaseModel, **extra_data: Any) -> ModelType`
* `async def on_create_multi(self, schemas: list[BaseModel], refresh: bool = False) -> Sequence[ModelType]`
* `async def on_update(self, target: ModelType | Any, schema: BaseModel, partial: bool = False, **extra_data: Any) -> ModelType | None`
* `async def on_update_multi(self, data: dict[ModelType | Any, BaseModel], partial: bool = False, refresh: bool = False) -> Sequence[ModelType]`
* `async def on_delete(self, target: ModelType | Any, force: bool = False) -> ModelType | None`
* `async def on_delete_multi(self, ids: list[Any], force: bool = False) -> Sequence[ModelType]`
* `async def on_restore(self, target: ModelType | Any) -> ModelType | None`
* `async def on_restore_multi(self, ids: list[Any]) -> Sequence[ModelType]`
* `async def on_search(self, search_in: SearchRequest, pagination: Any = None, fields: list[Any] | None = None, options: list[ExecutableOption] | None = None) -> Any`

***

## Lifecycle Hooks Reference [#lifecycle-hooks-reference]

Override these hooks in your service to execute custom business logic before or after operations:

<TypeTable
  type="{
  'pre_create(schema)': {
    type: 'dict | None',
    description: 'Triggered before insert. Returning a dict merges values into the insert payload.',
  },
  'post_create(model)': {
    type: 'None',
    description: 'Triggered immediately after database insert and flush.',
  },
  'pre_create_multi(schemas)': {
    type: 'None',
    description: 'Triggered before batch insertion.',
  },
  'post_create_multi(models)': {
    type: 'None',
    description: 'Triggered after batch insertion.',
  },
  'pre_update(target, schema, partial)': {
    type: 'dict | None',
    description: 'Triggered before update. Returning a dict merges values into the update payload.',
  },
  'post_update(model)': {
    type: 'None',
    description: 'Triggered immediately after database update and flush.',
  },
  'pre_update_multi(data, partial)': {
    type: 'None',
    description: 'Triggered before batch update.',
  },
  'post_update_multi(models)': {
    type: 'None',
    description: 'Triggered after batch update.',
  },
  'pre_delete(id, force=False)': {
    type: 'None',
    description: 'Triggered before single-record deletion. Receives force flag.',
  },
  'post_delete(model, force=False)': {
    type: 'None',
    description: 'Triggered after single-record deletion. Receives force flag.',
  },
  'pre_delete_multi(ids, force=False)': {
    type: 'None',
    description: 'Triggered before batch deletion. Receives force flag.',
  },
  'post_delete_multi(models, force=False)': {
    type: 'None',
    description: 'Triggered after batch deletion. Receives force flag.',
  },
  'pre_restore(id)': {
    type: 'None',
    description: 'Triggered before single-record soft-delete recovery.',
  },
  'post_restore(model)': {
    type: 'None',
    description: 'Triggered immediately after restoring a soft-deleted record.',
  },
  'pre_restore_multi(ids)': {
    type: 'None',
    description: 'Triggered before batch soft-delete restoration.',
  },
  'post_restore_multi(models)': {
    type: 'None',
    description: 'Triggered after batch soft-delete restoration.',
  },
  'post_get(model)': {
    type: 'ModelType',
    description: 'Extension interceptor executed after a single entity is retrieved.',
  },
  'post_get_multi(models)': {
    type: 'Sequence[ModelType]',
    description: 'Extension interceptor executed after a batch sequence is retrieved.',
  },
  'pre_search(search_in)': {
    type: 'None',
    description: 'Triggered before dynamic search query execution.',
  },
  'post_search(models)': {
    type: 'None',
    description: 'Triggered after dynamic search query execution.',
  }
}"
/>


# Settings & Configuration (/docs/api-reference/settings)





The `Settings` class parses and validates environment variables and file-based sources (`.env`). It integrates directly with ZCore's IoC container to support singleton management and provides a dynamic proxy for lazy resolution.

## Class Definition [#class-definition]

```python
import os
from pydantic_settings import BaseSettings, SettingsConfigDict
from zcore.config import Settings

class Settings(BaseSettings):
    model_config = SettingsConfigDict(
        env_file=os.getenv("ENV_FILE", ".env"),
        extra="ignore",
        case_sensitive=True
    )
```

***

## Core Configuration Attributes [#core-configuration-attributes]

<TypeTable
  type="{
  DATABASE: {
    type: 'DatabaseSettings',
    default: 'DatabaseSettings()',
    description: 'Structured configuration model for database engine and connection pool parameters.',
  },
  DATABASE_URL: {
    type: 'str',
    default: '&#x22;sqlite+aiosqlite:///zcore.db&#x22;',
    description: 'Primary relational database async connection URI.',
  },
  DATABASE_TEST_URL: {
    type: 'str',
    default: '&#x22;sqlite+aiosqlite:///zcore_test.db&#x22;',
    description: 'Dedicated test runner database connection URI.',
  },
  POOL_SIZE: {
    type: 'int',
    default: '5',
    description: 'Base connection pool capacity for non-SQLite relational engines.',
  },
  MAX_OVERFLOW: {
    type: 'int',
    default: '10',
    description: 'Maximum overflowing connections allowed beyond POOL_SIZE.',
  },
  LOGGING: {
    type: 'LoggingSettings',
    default: 'LoggingSettings()',
    description: 'Structured configuration model for framework and application logging settings.',
  },
  LOG_LEVEL: {
    type: 'str',
    default: '&#x22;INFO&#x22;',
    description: 'Fallback environment logging level string.',
  },
  LOG_SQL_QUERIES: {
    type: 'bool | None',
    default: 'None',
    description: 'Flat environment variable overriding LOGGING.log_sql_queries with bidirectional synchronization.',
  },
  TIMEZONE: {
    type: 'str',
    default: '&#x22;UTC&#x22;',
    description: 'IANA standard timezone string used across the application.',
  },
  AUTO_CONVERT_TIMEZONE: {
    type: 'bool',
    default: 'True',
    description: 'Boolean flag determining automatic API timezone conversions during serialization.',
  },
  PROJECT_NAME: {
    type: 'str',
    default: '&#x22;ZCore Application&#x22;',
    description: 'Human-readable title name for the project and OpenAPI documentation.',
  },
  DEBUG: {
    type: 'bool',
    default: 'True',
    description: 'Boolean flag indicating whether the application runs in debug mode (affects logging and fail-fast checks).',
  },
  SECRET_KEY: {
    type: 'str',
    default: '&#x22;zcore-insecure-fallback-secret-key-must-be-changed&#x22;',
    description: 'Cryptographic secret key used for signing JWTs and hashes. Must be changed in production.',
  },
  ALGORITHM: {
    type: 'str',
    default: '&#x22;HS256&#x22;',
    description: 'Cryptographic signing algorithm utilized for JWT generation.',
  },
  ACCESS_TOKEN_EXPIRE_MINUTES: {
    type: 'int',
    default: '30',
    description: 'Lifespan duration for authentication access tokens in minutes.',
  },
  REFRESH_TOKEN_EXPIRE_DAYS: {
    type: 'int',
    default: '7',
    description: 'Lifespan duration for refresh tokens in days.',
  },
  AUTH_CACHE_TTL: {
    type: 'int',
    default: '300',
    description: 'Expiration duration in seconds for cached user authentication sessions.',
  },
  PAGINATION_DEFAULT_SIZE: {
    type: 'int',
    default: '20',
    description: 'Default page size for paginated list queries when omitted in requests.',
  },
  PAGINATION_MAX_SIZE: {
    type: 'int',
    default: '100',
    description: 'Maximum allowed upper bound for page size parameters across queries.',
  },
  SEARCH_MAX_DEPTH: {
    type: 'int',
    default: '3',
    description: 'Default fallback depth limit for dynamic search filters and relation eager-loading.',
  },
  CACHE_LOCAL_MAXSIZE: {
    type: 'int',
    default: '1000',
    description: 'Maximum entries permitted simultaneously in the local in-memory fallback cache.',
  },
  CACHE_DEFAULT_TTL: {
    type: 'int',
    default: '3600',
    description: 'Default Time-To-Live in seconds for cached records.',
  },
  CACHE_EVICTION_INTERVAL: {
    type: 'int',
    default: '60',
    description: 'Rest period in seconds between background memory cache garbage collection sweeps.',
  },
  STREAM_QUEUE_MAXSIZE: {
    type: 'int',
    default: '100',
    description: 'Maximum capacity of bounded user listener queues in StreamManager.',
  },
  STORAGE_PATH: {
    type: 'str',
    default: '&#x22;./storage&#x22;',
    description: 'Local filesystem base directory path reserved for file uploads (aliases: STORAGE_PATH, STORAGE_BASE_PATH).',
  },
  STORAGE_URL_PREFIX: {
    type: 'str',
    default: '&#x22;/storage&#x22;',
    description: 'HTTP URL prefix mapped to exposed static assets (aliases: STORAGE_URL_PREFIX, STORAGE_PREFIX).',
  },
  REDIS_URL: {
    type: 'str | None',
    default: 'None',
    description: 'Distributed Redis connection URI, or None for local memory caching and streaming.',
  }
}"
/>

***

## Nested Configuration Models [#nested-configuration-models]

### `DatabaseSettings` [#databasesettings]

Schema defining connection pool and execution parameters for SQLAlchemy asynchronous engines:

```python
from pydantic import BaseModel, Field
from typing import Any

class DatabaseSettings(BaseModel):
    url: str = "sqlite+aiosqlite:///zcore.db"
    pool_size: int = 5
    max_overflow: int = 10
    pool_recycle: int = 1800
    pool_pre_ping: bool = True
    echo: bool = False
    connect_args: dict[str, Any] = Field(default_factory=dict)
    execution_options: dict[str, Any] = Field(default_factory=dict)
    extra_engine_kwargs: dict[str, Any] = Field(default_factory=dict)
```

<TypeTable
  type="{
  url: {
    type: 'str',
    default: '&#x22;sqlite+aiosqlite:///zcore.db&#x22;',
    description: 'Primary asynchronous database connection URL.',
  },
  pool_size: {
    type: 'int',
    default: '5',
    description: 'The connection pool size for non-SQLite databases.',
  },
  max_overflow: {
    type: 'int',
    default: '10',
    description: 'Maximum overflowing connections allowed beyond pool_size.',
  },
  pool_recycle: {
    type: 'int',
    default: '1800',
    description: 'Connection recycle duration in seconds.',
  },
  pool_pre_ping: {
    type: 'bool',
    default: 'True',
    description: 'Boolean flag to enable pool pre-ping connection liveness checks.',
  },
  echo: {
    type: 'bool',
    default: 'False',
    description: 'Direct SQLAlchemy engine echo flag.',
  },
  connect_args: {
    type: 'dict[str, Any]',
    default: '{}',
    description: 'Custom connection arguments forwarded directly to the database driver.',
  },
  execution_options: {
    type: 'dict[str, Any]',
    default: '{}',
    description: 'Execution options passed to the SQLAlchemy engine.',
  },
  extra_engine_kwargs: {
    type: 'dict[str, Any]',
    default: '{}',
    description: 'Additional keyword arguments forwarded to create_async_engine.',
  }
}"
/>

### `LoggingSettings` [#loggingsettings]

Schema configuring structured logging, file rotation parameters, and SQL query interception:

```python
from pydantic import BaseModel, Field
from typing import Any

class LoggingSettings(BaseModel):
    level: str = "INFO"
    json_format: bool | None = None
    log_sql_queries: bool = False
    slow_query_threshold_ms: float | None = None
    file_path: str | None = None
    max_bytes: int = 10 * 1024 * 1024
    backup_count: int = 5
    muted_loggers: list[str] = Field(
        default_factory=lambda: [
            "sqlalchemy.engine",
        ]
    )
    passthrough_loggers: list[str] = Field(
        default_factory=lambda: [
            "uvicorn",
            "uvicorn.access",
            "uvicorn.error",
        ]
    )
    intercept_loggers: list[str] = Field(
        default_factory=lambda: [
            "uvicorn",
            "uvicorn.access",
            "uvicorn.error",
        ]
    )
    custom_processors: list[Any] = Field(default_factory=list)
```

<TypeTable
  type="{
  level: {
    type: 'str',
    default: '&#x22;INFO&#x22;',
    description: 'Active logging level string (DEBUG, INFO, WARNING, ERROR, CRITICAL).',
  },
  json_format: {
    type: 'bool | None',
    default: 'None',
    description: 'Explicit JSON output flag. If None, defaults to JSON in production and colored console in debug mode.',
  },
  log_sql_queries: {
    type: 'bool',
    default: 'False',
    description: 'Boolean flag to toggle SQL statement execution logging.',
  },
  slow_query_threshold_ms: {
    type: 'float | None',
    default: 'None',
    description: 'Execution threshold in milliseconds to log slow SQL queries specifically.',
  },
  file_path: {
    type: 'str | None',
    default: 'None',
    description: 'Target filesystem path for rotating log files.',
  },
  max_bytes: {
    type: 'int',
    default: '10485760 (10MB)',
    description: 'Maximum size in bytes before a log file is rotated.',
  },
  backup_count: {
    type: 'int',
    default: '5',
    description: 'Number of backup log files to retain after rotation.',
  },
  muted_loggers: {
    type: 'list[str]',
    default: '[&#x22;sqlalchemy.engine&#x22;]',
    description: 'List of external logger names whose outputs are suppressed and propagation disabled.',
  },
  passthrough_loggers: {
    type: 'list[str]',
    default: '[&#x22;uvicorn&#x22;, &#x22;uvicorn.access&#x22;, &#x22;uvicorn.error&#x22;]',
    description: 'List of external loggers whose native formatting is preserved in development mode.',
  },
  intercept_loggers: {
    type: 'list[str]',
    default: '[&#x22;uvicorn&#x22;, &#x22;uvicorn.access&#x22;, &#x22;uvicorn.error&#x22;]',
    description: 'List of external loggers channeled into structlog JSON formatting in production mode.',
  },
  custom_processors: {
    type: 'list[Any]',
    default: '[]',
    description: 'List of custom structlog processors to append to the pipeline.',
  }
}"
/>

***

## The Settings Proxy (Lazy Resolution) [#the-settings-proxy-lazy-resolution]

ZCore exposes a global `settings` object via `SettingsProxy`:

```python
from zcore import settings
```

<Callout type="info" emoji="⚙️">
  **Lazy Resolution Architecture:** When you import `settings`, you are importing a dynamic `SettingsProxy` object. Configuration lookups are resolved against the active registered `Settings` singleton **only when an attribute is accessed**. This eliminates circular import errors and prevents premature database pool instantiation during module loading.
</Callout>

***

## Helper Functions [#helper-functions]

### `initialize_settings` [#initialize_settings]

Registers a settings instance (or custom subclass) into the IoC container as a Singleton. If a subclass is provided, it binds both the subclass and the base `Settings` interface.

```python
from zcore.config import initialize_settings

initialize_settings(AppSettings())
```

<TypeTable
  type="{
  settings_inst: {
    type: 'Settings',
    description: 'An instance of Settings (or its subclass) to bind to the global IoC container.',
  }
}"
/>

### `get_settings` [#get_settings]

Resolves the active settings singleton from the IoC container. If uninitialized, it automatically instantiates and registers the specified class as a fallback.

```python
from zcore.config import get_settings

active_settings = get_settings()
```

<TypeTable
  type="{
  settings_class: {
    type: 'type[T]',
    default: 'Settings',
    description: 'The class type of the settings to resolve.',
  },
  returns: {
    type: 'T',
    description: 'The resolved settings instance of type T.',
  }
}"
/>


# Storage Validators (/docs/api-reference/storage-validators)





This module provides validation controls to protect server integrity during file uploads. It includes file extension checks, file size limit enforcement to defend against Denial of Service (DoS) attacks, and MIME-type verification using binary Magic Bytes.

## Base Class [#base-class]

### `BaseStorageValidator` [#basestoragevalidator]

Base interface protocol defining standard storage validators. All custom validators must inherit from this class and implement `__call__`.

```python
from fastapi import UploadFile
from zcore.storage import BaseStorageValidator

class BaseStorageValidator:
    def __call__(self, file: UploadFile) -> None:
        raise NotImplementedError
```

<Callout type="info" emoji="⚙️">
  Validators are callables. When invoked, they inspect the `UploadFile` instance and raise a `ValidationError` with descriptive metadata if validation fails.
</Callout>

***

## Built-in Security Validators [#built-in-security-validators]

### `FileExtensionValidator` [#fileextensionvalidator]

Enforces extension whitelist checks on incoming file names.

```python
from zcore.storage import FileExtensionValidator

validator = FileExtensionValidator(
    allowed_extensions=[".png", ".jpg", ".pdf"],
    message="Custom invalid extension message"
)
```

<TypeTable
  type="{
  allowed_extensions: {
    type: 'Union[List[str], Set[str]]',
    description: 'List or set of allowed extension strings (e.g., [&#x22;.png&#x22;, &#x22;jpg&#x22;]). Extensions are normalized automatically.',
  },
  message: {
    type: 'Optional[str]',
    default: 'None',
    description: 'Custom validation diagnostic error message dispatched on failures.',
  }
}"
/>

### `MaxFileSizeValidator` [#maxfilesizevalidator]

Enforces file size thresholds to prevent Denial of Service (DoS) and disk space exhaustion.

```python
from zcore.storage import MaxFileSizeValidator

validator = MaxFileSizeValidator(
    max_size_mb=10.0,
    message="File size exceeds limit"
)
```

<TypeTable
  type="{
  max_size_mb: {
    type: 'float',
    description: 'Maximum allowable file size threshold specified in Megabytes (MB).',
  },
  message: {
    type: 'Optional[str]',
    default: 'None',
    description: 'Custom validation diagnostic message dispatched on failures.',
  }
}"
/>

<Callout type="info" emoji="💡">
  **Chunked Stream Support:** If the Starlette `file.size` attribute is unavailable, `MaxFileSizeValidator` safely seeks to the end of the byte stream (`file.file.seek(0, 2)`), measures the stream position (`tell()`), and rewinds to the beginning (`seek(0)`) without buffering payloads into RAM.
</Callout>

### `SafeMimeTypeValidator` [#safemimetypevalidator]

MIME-type validator utilizing binary **Magic Byte verification**. Reads the first 8192 header bytes of the file to verify that the file's raw binary signature matches its declared format.

```python
from zcore.storage import SafeMimeTypeValidator

validator = SafeMimeTypeValidator(
    allowed_mimes=["image/png", "image/jpeg", "application/pdf"]
)
```

<TypeTable
  type="{
  allowed_mimes: {
    type: 'Union[List[str], Set[str]]',
    description: 'Set or list of approved MIME strings (e.g., [&#x22;image/png&#x22;, &#x22;image/jpeg&#x22;]).',
  },
  message: {
    type: 'Optional[str]',
    default: 'None',
    description: 'Custom validation diagnostic message dispatched on failures.',
  }
}"
/>

<Callout type="warn" emoji="🚨">
  **Executable & Injection Firewall:**
  Before validating formats, `SafeMimeTypeValidator` inspects header bytes for high-risk binary headers and script patterns:

  * **Executable Headers (`BLOCKED_HEADER_PREFIXES`):** Windows PE (`MZ`), Unix Shebang scripts (`#!/`), Linux ELF binaries (`\x7fELF`).
  * **Malicious Content Patterns (`MALICIOUS_CONTENT_PATTERNS`):** Active scripts and XSS vectors including `<?php`, `<script`, `javascript:`, `vbscript:`, `data:text/html`, `<!doctype html`, `<html`, `<iframe>`, `<object>`, `<embed>`, DOM event attributes (`onload=`, `onerror=`, `onclick=`), and SVG xlink JavaScript links.

  Any file containing these execution signatures is immediately rejected with a critical security alert, regardless of its extension.
</Callout>

***

## Default Supported Binary Signatures (`SIGNATURES`) [#default-supported-binary-signatures-signatures]

`SafeMimeTypeValidator` validates against the following built-in magic byte headers:

| Format   | Magic Byte Signature      | MIME Type         |
| -------- | ------------------------- | ----------------- |
| **PNG**  | `b"\x89PNG\r\n\x1a\n"`    | `image/png`       |
| **JPEG** | `b"\xff\xd8\xff"`         | `image/jpeg`      |
| **GIF**  | `b"GIF87a"` / `b"GIF89a"` | `image/gif`       |
| **PDF**  | `b"%PDF"`                 | `application/pdf` |
| **WebP** | `b"RIFF"`                 | `image/webp`      |


# StreamManager (/docs/api-reference/stream-manager)





`StreamManager` coordinates active listener queues and Redis PubSub operations. It facilitates cluster-wide event routing via subscription channels formatted as `stream:user:<user_id>`, falling back to local memory queues if Redis is unconfigured or offline.

## Class Definition [#class-definition]

```python
from zcore.web import StreamManager

class StreamManager:
    def __init__(self) -> None:
        ...
```

***

## Global Setup Function [#global-setup-function]

### `init_stream_redis` [#init_stream_redis]

Initializes the shared Redis connection client for the streaming subsystem.

```python
from typing import Any
from zcore.web import init_stream_redis

def init_stream_redis(client: Any) -> None: ...
```

<TypeTable
  type="{
  client: {
    type: 'Any',
    description: 'The active async Redis client instance (e.g., aioredis.from_url(...)).',
  }
}"
/>

***

## Properties [#properties]

<TypeTable
  type="{
  redis_client: {
    type: 'Any | None',
    description: 'The active shared streaming Redis client, or None if uninitialized.',
  },
  users_queues: {
    type: 'dict[Any, list[asyncio.Queue[Any]]]',
    description: 'In-memory mapping of active polymorphic user IDs (UUID, int, str) to lists of active bounded asyncio listener queues.',
  }
}"
/>

***

## Methods [#methods]

### `subscribe` [#subscribe]

Subscribes a user, returning a bounded async listener queue. Queue capacity is dynamically resolved from `settings.STREAM_QUEUE_MAXSIZE` (Default: 100). Initializes background Redis PubSub listeners if this is the first active subscription for a user on this node.

```python
async def subscribe(self, user_id: Any) -> asyncio.Queue[Any]: ...
```

<TypeTable
  type="{
  user_id: {
    type: 'Any',
    description: 'The target recipient user identifier key (supports int, str, or uuid.UUID).',
  },
  returns: {
    type: 'asyncio.Queue[Any]',
    description: 'A bounded asyncio Queue (maxsize configured via settings.STREAM_QUEUE_MAXSIZE) configured to receive incoming event dictionaries.',
  }
}"
/>

### `unsubscribe` [#unsubscribe]

Unsubscribes a specific listener queue for a user. Shuts down background Redis tasks if no active listeners remain in the local registry.

```python
async def unsubscribe(self, user_id: Any, queue: asyncio.Queue[Any]) -> None: ...
```

<TypeTable
  type="{
  user_id: {
    type: 'Any',
    description: 'The target user identifier key.',
  },
  queue: {
    type: 'asyncio.Queue[Any]',
    description: 'The active asyncio Queue instance to deregister.',
  }
}"
/>

### `subscription` [#subscription]

Asynchronous context manager safely wrapping active user event streams. Guarantees automatic cleanup and queue unregistration upon block exit or connection drops.

```python
@asynccontextmanager
async def subscription(
    self, 
    user_id: Any
) -> AsyncGenerator[asyncio.Queue[Any], None]: ...
```

<TypeTable
  type="{
  user_id: {
    type: 'Any',
    description: 'The target user identifier key to stream.',
  },
  returns: {
    type: 'AsyncGenerator[asyncio.Queue[Any], None]',
    description: 'Yields a bounded async Queue populated with real-time event dictionaries.',
  }
}"
/>

### `publish` [#publish]

Publishes an event payload to a target user's stream. Broadcasts cluster-wide across Redis PubSub channel `stream:user:{user_id}`, falling back to local memory delivery if unconfigured.

```python
async def publish(self, user_id: Any, data: dict[str, Any]) -> None: ...
```

<TypeTable
  type="{
  user_id: {
    type: 'Any',
    description: 'The target recipient user identifier (UUID, int, or str).',
  },
  data: {
    type: 'dict[str, Any]',
    description: 'JSON-serializable event dictionary to transmit.',
  }
}"
/>

### `start_listening` [#start_listening]

Explicitly initiates background Redis PubSub pattern-matching subscribers (`stream:user:*`).

```python
async def start_listening(self) -> None: ...
```

***

## Usage Example (Server-Sent Events) [#usage-example-server-sent-events]

```python
from fastapi import APIRouter
from fastapi.responses import StreamingResponse
from zcore.web import StreamManager

router = APIRouter()
stream_manager = StreamManager()

@router.get("/notifications/stream/{user_id}")
async def stream_notifications(user_id: str):
    async def event_generator():
        # Automatically registers and safely tears down queue on client disconnect
        async with stream_manager.subscription(user_id) as queue:
            while True:
                payload = await queue.get()
                yield f"data: {payload}\n\n"

    return StreamingResponse(event_generator(), media_type="text/event-stream")
```

<Callout type="warn" emoji="🛡️">
  **Slow-Consumer Overflow Protection:**
  If a client consumes messages too slowly and their bounded queue reaches maximum capacity (`settings.STREAM_QUEUE_MAXSIZE`, default: **100 items**), `StreamManager` catches `asyncio.QueueFull`, immediately unregisters the stalled queue, and drops it to protect host node memory from buffer bloat.
</Callout>


# Testing Fixtures & Orchestrator (/docs/api-reference/testing-fixtures)





ZCore provides a suite of composable test fixtures (`ZTestFixture` subclasses) that isolate your tests by managing state setup and teardown. `ZTestClient` orchestrates these internally, but you can compose them directly for bespoke test setups.

## Base Class: `ZTestFixture` [#base-class-ztestfixture]

Abstract base class for all testing fixtures:

```python
from abc import ABC, abstractmethod

class ZTestFixture(ABC):
    @abstractmethod
    async def setUp(self) -> None: ...

    @abstractmethod
    async def tearDown(self) -> None: ...
```

***

## Built-in Fixtures [#built-in-fixtures]

### `ContainerSandbox` [#containersandbox]

Takes a snapshot of `container._singletons`, `_scoped_definitions`, and `_factories` during `setUp` and restores them during `tearDown`. Guarantees that mock services registered during a test do not leak into subsequent tests.

```python
from zcore.testing import ContainerSandbox

sandbox = ContainerSandbox()
```

***

### `EventDispatcherSandbox` [#eventdispatchersandbox]

Snapshots all registered subscribers on `EventDispatcher` during `setUp` and restores them during `tearDown`. Prevents event listeners or handlers registered dynamically in one test from leaking into subsequent test suites.

```python
from zcore.testing import EventDispatcherSandbox

# Resolves EventDispatcher automatically from IoC container if dispatcher is None
event_sandbox = EventDispatcherSandbox(dispatcher=None)
```

<TypeTable
  type="{
  dispatcher: {
    type: 'EventDispatcher | None',
    default: 'None',
    description: 'Target EventDispatcher instance to sandbox. If None, resolves from the IoC container automatically.',
  }
}"
/>

***

### `DatabaseRollback` [#databaserollback]

Provides a lightning-fast database testing strategy using nested savepoints without dropping tables or running migrations. Supports both native `DatabaseManager` configurations and custom engines with dependency overrides.

```python
from zcore.testing import DatabaseRollback

db_rollback = DatabaseRollback(
    engine=None,           # Custom AsyncEngine (defaults to db_manager._engine)
    db_dependency=None,    # Target dependency callable(s) to override
    app=None               # FastAPI application requiring dependency overrides
)
```

<TypeTable
  type="{
  engine: {
    type: 'AsyncEngine | None',
    default: 'None',
    description: 'Custom SQLAlchemy AsyncEngine instance. Defaults to db_manager._engine if unconfigured.',
  },
  db_dependency: {
    type: 'Any | Sequence[Any] | None',
    default: 'None',
    description: 'Single or sequence of database session dependencies to override with the savepoint session.',
  },
  app: {
    type: 'FastAPI | None',
    default: 'None',
    description: 'Target FastAPI application instance requiring dependency overrides.',
  }
}"
/>

<Callout type="info" emoji="⚙️">
  **The Savepoint Pipeline:**

  1. Opens an asynchronous connection on the target engine (`db_manager._engine` or explicit `engine`).
  2. Begins a root transaction on that connection.
  3. Instantiates an `AsyncSession` with `join_transaction_mode="create_savepoint"`.
  4. Registers this session as the active scoped instance in the `IoCContainer`, mocks `db_manager.session`, and overrides any configured `db_dependency` on `app`.
  5. On `tearDown`, it rolls back the root transaction, closes the connection, and restores original session providers.
</Callout>

***

### `UserContext` [#usercontext]

Injects mock user metadata into the request-scoped `_request_context_store` during `setUp` and resets the `contextvars.Token` on `tearDown`.

```python
import uuid
from zcore.testing import UserContext

user_fixture = UserContext(
    user_id=uuid.uuid4(),
    scopes=["tasks:view", "tasks:create"],
    is_superuser=False,
    extra_context={"restricted_fields": ["tasks.view.salary"]}
)
```

<TypeTable
  type="{
  user_id: {
    type: 'Any',
    description: 'The polymorphic user identifier (UUID, int, or str) to bind to ctx.user_id.',
  },
  scopes: {
    type: 'list[str] | None',
    default: '[]',
    description: 'Security permission scopes to bind to ctx.scopes.',
  },
  is_superuser: {
    type: 'bool',
    default: 'False',
    description: 'Boolean flag indicating if the mock user possesses administrator bypass privileges.',
  },
  extra_context: {
    type: 'dict[str, Any] | None',
    default: '{}',
    description: 'Additional key-value pairs to populate in the active ZContext store.',
  }
}"
/>

***

### `DependencyOverride` [#dependencyoverride]

Wraps FastAPI's `app.dependency_overrides` dictionary. Applies the override during `setUp` and safely removes it during `tearDown`.

```python
from zcore.testing import DependencyOverride
from zcore.security import get_current_user_stub

override_fixture = DependencyOverride(
    app=app,
    stub=get_current_user_stub,
    override_func=mock_user_callable
)
```

<TypeTable
  type="{
  app: {
    type: 'FastAPI',
    description: 'The target FastAPI application instance.',
  },
  stub: {
    type: 'Any',
    description: 'The dependency callable stub to override (e.g., get_current_user_stub).',
  },
  override_func: {
    type: 'Any',
    description: 'The mock callable or replacement dependency provider.',
  }
}"
/>

***

### `AppLifespan` [#applifespan]

Manages the FastAPI application lifespan context during testing. Enters `app.router.lifespan_context` during `setUp` (triggering plugin startup hooks) and exits it during `tearDown` (triggering shutdown hooks).

```python
from zcore.testing import AppLifespan

lifespan_fixture = AppLifespan(app=app)
```

<TypeTable
  type="{
  app: {
    type: 'FastAPI',
    description: 'The FastAPI application whose lifespan context to execute.',
  }
}"
/>

***

## The `ZTest` Meta-Orchestrator [#the-ztest-meta-orchestrator]

A composite fixture that chains multiple `ZTestFixture` instances, executing `setUp` in sequential order and `tearDown` in **reversed dependency order**:

```python
from zcore.testing import (
    AppLifespan,
    ContainerSandbox,
    DatabaseRollback,
    EventDispatcherSandbox,
    UserContext,
    ZTest,
)

orchestrator = ZTest(
    ContainerSandbox(),
    EventDispatcherSandbox(),
    AppLifespan(app),
    DatabaseRollback(),
    UserContext(user_id=mock_id, scopes=["admin"])
)

# In your custom test runner:
await orchestrator.setUp()
try:
    # Run assertions
    pass
finally:
    # Tears down in reverse order cleanly
    await orchestrator.tearDown()
```


# UnitOfWork (/docs/api-reference/uow)





The `UnitOfWork` (UoW) coordinates transactional boundaries and buffers domain events, guaranteeing that events are dispatched only after database modifications have successfully committed. It implements the asynchronous context manager protocol and supports depth-aware nested execution.

## Class Definition [#class-definition]

```python
from sqlalchemy.ext.asyncio import AsyncSession
from zcore import UnitOfWork
from zcore.kernel.events import EventDispatcher

class UnitOfWork:
    def __init__(self, session: AsyncSession, dispatcher: EventDispatcher):
        ...
```

***

## Properties [#properties]

<TypeTable
  type="{
  session: {
    type: 'AsyncSession',
    description: 'The underlying active asynchronous SQLAlchemy database session.',
  },
  dispatcher: {
    type: 'EventDispatcher',
    description: 'The central system event dispatcher used for publishing domain events.',
  },
  _pending_events: {
    type: 'list[tuple[str, Any]]',
    description: 'Direct reference to the session-level buffered domain event queue awaiting successful commit.',
  }
}"
/>

***

## Methods [#methods]

### `register_event` [#register_event]

Queues a domain event for post-commit dispatch. Events registered across nested unit-of-work scopes are buffered into the shared session store (`session.info["uow_events"]`) and dispatched collectively upon the successful root commit.

```python
def register_event(self, event_name: str, payload: Any) -> None: ...
```

<TypeTable
  type="{
  event_name: {
    type: 'str',
    description: 'The unique string identifier name of the domain event to queue.',
  },
  payload: {
    type: 'Any',
    description: 'Contextual payload data accompanying the event.',
  },
  returns: {
    type: 'None',
    description: 'Appends the event tuple to the session pending queue.',
  }
}"
/>

### `commit` [#commit]

Commits the database session and sequentially dispatches all buffered domain events. In nested transaction scopes, this method flushes pending operations to the database without committing the physical transaction until the outermost scope concludes.

```python
async def commit(self) -> None: ...
```

<Callout type="info" emoji="🔄">
  **Nested Scope Flushing:**
  When called inside a nested `UnitOfWork` scope (`session.info["uow_depth"] > 1`), `commit()` executes `await self.session.flush()` instead of a physical database commit. The actual database commit and post-commit event dispatching are deferred until the outermost root context exits.
</Callout>

<Callout type="warn" emoji="⚠️">
  If the database commit fails, the session is rolled back immediately, all pending events are purged, and the original database exception is re-raised.
</Callout>

<TypeTable
  type="{
  returns: {
    type: 'None',
    description: 'Awaits database commit and executes self.dispatcher.dispatch() on all buffered events upon root exit.',
  }
}"
/>

### `rollback` [#rollback]

Rolls back the database session, clears all pending domain events, and resets the transaction depth.

```python
async def rollback(self) -> None: ...
```

<TypeTable
  type="{
  returns: {
    type: 'None',
    description: 'Rolls back the active session, resets uow_depth, and clears the _pending_events buffer.',
  }
}"
/>

***

## Context Manager Protocol [#context-manager-protocol]

`UnitOfWork` is designed to be used via `async with`. Entering the context increments `session.info["uow_depth"]` and marks the session with `session.info["uow_managed"] = True` to coordinate with `BaseService._safe_commit()`:

```python
from zcore import UnitOfWork, EventDispatcher

async def checkout(order_repo, inventory_repo, dispatcher: EventDispatcher, order_data):
    # Automatically manages transaction commit/rollback and event queue on context exit
    async with UnitOfWork(order_repo.db, dispatcher) as uow:
        order = await order_repo.create(order_data)
        await inventory_repo.decrement_stock(order.product_id, 1)
        
        # Buffered in memory; dispatched only if the database commit succeeds!
        uow.register_event("order.completed", {"order_id": str(order.id)})
```

Upon block exit (`__aexit__`), `UnitOfWork` decrements `uow_depth`. If an exception occurred, it rolls back the entire session and discards all buffered events. If exiting the root boundary (`depth == 0`), it executes the final database commit and dispatches all accumulated events concurrently.


# Utilities & Helpers (/docs/api-reference/utilities)





ZCore includes a collection of utility functions and serialization helpers designed to handle advanced Python data types, dynamic application timezones, Draft-7 JSON Schema validation, URL-safe slug generation, and database-to-application event bridging.

## 1. JSON Serialization & Parsing [#1-json-serialization--parsing]

Standard Python `json` fails when serializing `UUID`, `datetime`, `date`, `time`, or `Decimal` objects. ZCore provides custom encoders and wrapper functions:

```python
from zcore.utils.helpers import json_dumps, json_loads, CustomJSONEncoder
```

### `json_dumps` [#json_dumps]

Serializes a Python object or Pydantic data structure into a JSON string using `CustomJSONEncoder`.

```python
def json_dumps(obj: Any, **kwargs: Any) -> str: ...
```

<TypeTable
  type="{
  obj: {
    type: 'Any',
    description: 'The target Python object or collection to serialize (coerces UUID, Decimal, Date, DateTime automatically).',
  },
  '**kwargs': {
    type: 'Any',
    description: 'Additional keyword arguments forwarded directly to json.dumps.',
  },
  returns: {
    type: 'str',
    description: 'The serialized JSON string payload.',
  }
}"
/>

### `json_loads` [#json_loads]

Deserializes a JSON string or binary byte stream back into Python structures.

```python
def json_loads(s: str | bytes, **kwargs: Any) -> Any: ...
```

***

## 2. Dynamic Timezone Management (`zcore.utils.timezone`) [#2-dynamic-timezone-management-zcoreutilstimezone]

Provides timezone-aware datetime operations powered by Python's `zoneinfo` standard library, falling back to UTC if misconfigured or running across system platforms without native zoneinfo tables.

```python
from zcore.utils.timezone import (
    now,
    utc_now,
    to_app_timezone,
    get_app_timezone,
    format_iso_with_app_timezone,
    ZDateTime
)
```

### `now` [#now]

Returns the current timezone-aware `datetime` bound to the application's configured timezone (`settings.TIMEZONE`).

```python
def now() -> datetime: ...
```

### `utc_now` [#utc_now]

Returns the current timezone-aware `datetime` explicitly bound to UTC.

```python
def utc_now() -> datetime: ...
```

### `to_app_timezone` [#to_app_timezone]

Converts any `datetime` object (naive or aware) to the application's configured timezone. Naive datetimes are assumed to be UTC before transformation.

```python
def to_app_timezone(dt: datetime | None) -> datetime | None: ...
```

<TypeTable
  type="{
  dt: {
    type: 'Optional[datetime]',
    description: 'The source datetime object to convert to application timezone.',
  },
  returns: {
    type: 'Optional[datetime]',
    description: 'The converted datetime instance in the application timezone, or None if input was None.',
  }
}"
/>

### `format_iso_with_app_timezone` [#format_iso_with_app_timezone]

Converts a datetime to the application's timezone and outputs a standardized ISO 8601 string. Respects `settings.AUTO_CONVERT_TIMEZONE`.

```python
def format_iso_with_app_timezone(dt: datetime | None) -> str | None: ...
```

### `ZDateTime` [#zdatetime]

Pydantic `Annotated` type wrapper for `datetime` attributes that automatically formats fields to ISO 8601 strings in the application's configured timezone during JSON response serialization.

```python
from pydantic import BaseModel
from zcore.utils.timezone import ZDateTime

class TaskResponse(BaseModel):
    created_at: ZDateTime
```

***

## 3. JSON Schema Validation (`validate_json_schema`) [#3-json-schema-validation-validate_json_schema]

Validates arbitrary dictionary payloads or schema structures using the **Draft-7 JSON Schema** specification.

```python
from zcore.utils.validators import validate_json_schema

# Validate payload against a schema
validate_json_schema(data={"name": "Task 1"}, schema=my_draft7_schema)

# Or assert that a schema definition itself is structurally valid
validate_json_schema(data=my_draft7_schema)
```

<TypeTable
  type="{
  data: {
    type: 'Any',
    description: 'The target data dictionary to validate, or a schema dictionary to check if schema is None.',
  },
  schema: {
    type: 'Optional[dict[str, Any]]',
    default: 'None',
    description: 'The Draft-7 JSON Schema dictionary to evaluate the data against.',
  },
  returns: {
    type: 'None',
    description: 'Raises ValidationError if data violates constraints or if the schema definition is corrupted.',
  }
}"
/>

***

## 4. Text & Type Utilities [#4-text--type-utilities]

### `slugify` [#slugify]

Transforms an input text string into a sanitized, URL-safe, hyphenated slug.

```python
from zcore.utils.helpers import slugify

slug = slugify("Hello World & Welcome!") # -> "hello-world-welcome"
```

<TypeTable
  type="{
  text: {
    type: 'str',
    description: 'The raw text string to slugify (strips whitespace, normalizes casing, and removes non-alphanumeric chars).',
  },
  returns: {
    type: 'str',
    description: 'The URL-safe, lowercase slug string.',
  }
}"
/>

### `SafeUrl` [#safeurl]

Pydantic `Annotated` type wrapper for `HttpUrl` that automatically serializes URL instances cleanly to plain strings during model dumps.

```python
from zcore.utils.helpers import SafeUrl
from pydantic import BaseModel

class WebhookConfig(BaseModel):
    target_url: SafeUrl  # Serializes directly to str in JSON exports
```

***

## 5. Database Event Bridge (`zcore.db.events`) [#5-database-event-bridge-zcoredbevents]

Provides a decoupled, non-blocking bridge between low-level database operations and the application's central `EventDispatcher`.

```python
from zcore.db.events import register_db_event_dispatcher, dispatch_db_event
```

### `register_db_event_dispatcher` [#register_db_event_dispatcher]

Configures the central event dispatcher used by database modules to notify downstream systems of lifecycle transitions. Invoked during `main.py` bootstrap.

```python
register_db_event_dispatcher(kernel.dispatcher)
```

<TypeTable
  type="{
  dispatcher: {
    type: 'EventDispatcher',
    description: 'The core application EventDispatcher instance.',
  }
}"
/>

### `dispatch_db_event` [#dispatch_db_event]

Safely dispatches database lifecycle events asynchronously within the active event loop, catching and logging handler errors to protect calling database engines.

```python
await dispatch_db_event("db.record_created", {"table": "tasks", "id": str(task_id)})
```

<Callout type="info" emoji="⚡">
  **Non-Blocking & Fault-Tolerant:** `dispatch_db_event` executes in the background of the active event loop. If a listener handler fails, the error is logged to `structlog` without breaking synchronous database transactions.
</Callout>


# Zchema (Schema Projection) (/docs/api-reference/zchema)





`Zchema` inherits directly from Pydantic V2 `BaseModel`. It acts as the unified, domain-aware security schema base class. It intercepts Pydantic's core lifecycle hooks to dynamically prune restricted fields based on the active user's execution context.

## Class Definition [#class-definition]

```python
from pydantic import BaseModel
from typing import ClassVar, Optional
from zcore import Zchema

class Zchema(BaseModel):
    __model__: ClassVar[Optional[str]] = None
    __private__: ClassVar[set[str] | list[str] | None] = None
```

***

## Class Attributes [#class-attributes]

<TypeTable
  type="{
  __model__: {
    type: 'ClassVar[Optional[str]]',
    default: 'None',
    description: 'The database table or domain name this schema represents (e.g., &#x22;tasks&#x22;). Used to match and extract relative paths from ctx.restricted_fields.',
  },
  __private__: {
    type: 'ClassVar[set[str] | list[str] | None]',
    default: 'None',
    description: 'Set or list of sensitive field names automatically pruned from responses, input payloads, and OpenAPI schemas for unauthenticated requests (ctx.user_id is None).',
  }
}"
/>

***

## How Context Shielding Works [#how-context-shielding-works]

`Zchema` automatically interacts with the global `ctx` object. When a user authenticates, their restricted field paths (e.g., `"tasks.view.salary"` or `"tasks.create.is_admin"`) are loaded into `ctx.restricted_fields`.

For unauthenticated public visitors (`ctx.user_id is None`), any attributes listed in `__private__` are automatically merged into the active restriction set.

<Callout type="info" emoji="🛡️">
  **Triple Pruning Pipeline:**

  1. **Input Validation (Mass Assignment Defense):** Silently drops restricted fields from input payloads before validation occurs.
  2. **Output Serialization (Data Leakage Defense):** Recursively removes restricted attributes from the dictionary payload before rendering to JSON.
  3. **JSON Schema Generation (OpenAPI Masking):** Modifies the generated Pydantic schema on the fly, removing restricted keys from both `properties` and `required` definitions.
</Callout>

***

## Internal Lifecycle Interceptors [#internal-lifecycle-interceptors]

These methods are implemented internally by `Zchema` and require no manual invocation:

### `filter_restricted_inputs` [#filter_restricted_inputs]

`@model_validator(mode="before")` — Intercepts raw input payloads before Pydantic validation begins. It computes relative restricted paths and strips unauthorized attributes from incoming dictionaries to prevent Mass Assignment attacks.

### `secure_serializer` [#secure_serializer]

`@model_serializer(mode="wrap")` — Wraps the serialization process. It invokes the default serializer, then executes recursive pruning on the resulting dictionary before rendering to JSON. Early-exit guards bypass recursive traversals when no restrictions exist.

### `__get_pydantic_json_schema__` [#__get_pydantic_json_schema__]

Customizes dynamic JSON Schema generation. It prunes restricted properties and cleans the `required` validation array in schema specifications generated for OpenAPI or `?schema=true` requests.

### `_get_relative_restricted_paths` [#_get_relative_restricted_paths]

`@classmethod` — Extracts and normalizes restricted field paths mapped to this schema's domain (`__model__`). It evaluates unauthenticated guest attributes (`__private__`), action-specific rules (`tasks.view.salary`), global rules (`tasks.salary`), and wildcard model masks (`tasks.view` $\rightarrow$ `*`).

### `_prune_data` [#_prune_data]

`@classmethod` — Recursively traverses nested dictionaries and lists of dictionaries to strip attributes matching relative restriction dot-paths with early-termination optimization.


# ZContext (/docs/api-reference/zcontext)





`ZContext` provides a robust, thread-safe, and coroutine-aware context storage system built on Python's native `contextvars`. It manages request-scoped state (such as user identity and restricted fields), ensuring absolute state isolation across concurrent asynchronous task boundaries.

## Class Definition & Global Instance [#class-definition--global-instance]

ZCore exposes both the class definition and the pre-initialized global `ctx` singleton:

```python
from zcore import ctx, ZContext
# or: from zcore.context import ctx, ZContext

class ZContext:
    ...
```

***

## Strongly-Typed Properties [#strongly-typed-properties]

### `user_id` [#user_id]

Retrieves or sets the authenticated user identifier for the active coroutine context.

```python
# Access
current_id: Any | None = ctx.user_id

# Set (Accepts integer, string, uuid.UUID, or None)
ctx.user_id = 1054
ctx.user_id = "auth0|64f1b2c3"
ctx.user_id = uuid.uuid4()
```

<TypeTable
  type="{
  returns: {
    type: 'Any | None',
    description: 'The polymorphic user identifier (int, str, UUID) if set, otherwise None.',
  }
}"
/>

<Callout type="info" emoji="💡">
  **Polymorphic Identity:** As of `rc.2`, `ctx.user_id` no longer enforces strict UUID coercion. It supports arbitrary integer, string, or UUID primary keys without raising type errors.
</Callout>

### `restricted_fields` [#restricted_fields]

Accesses or updates the collection of data fields restricted in the current context.

```python
# Access
restrictions: frozenset[str] = ctx.restricted_fields

# Set
ctx.restricted_fields = ["tasks.view.salary", "tasks.create.role"]
```

<TypeTable
  type="{
  returns: {
    type: 'frozenset[str]',
    description: 'An immutable frozenset of restricted field paths (defaults to frozenset()).',
  }
}"
/>

<Callout type="info" emoji="🔒">
  The setter converts incoming iterables into an immutable `frozenset`. This prevents business logic layers from accidentally mutating security restriction rules mid-flight.
</Callout>

***

## Dynamic Key-Value Methods [#dynamic-key-value-methods]

### `set` [#set]

Stores an arbitrary key-value entry in the current execution context store.

```python
ctx.set("tenant_id", "enterprise_01")
```

<TypeTable
  type="{
  key: {
    type: 'str',
    description: 'The unique string identifier for the context entry.',
  },
  value: {
    type: 'Any',
    description: 'The data payload to persist in the current scope.',
  }
}"
/>

### `get` [#get]

Retrieves a value from the current execution context.

```python
tenant = ctx.get("tenant_id", default="public")
```

<TypeTable
  type="{
  key: {
    type: 'str',
    description: 'The identifier key for the requested context entry.',
  },
  default: {
    type: 'Any',
    default: 'None',
    description: 'The fallback value to return if the key is not found.',
  },
  returns: {
    type: 'Any',
    description: 'The associated value or the specified default.',
  }
}"
/>

### `remove` [#remove]

Deletes a specific entry from the current execution context store.

```python
ctx.remove("tenant_id")
```

<TypeTable
  type="{
  key: {
    type: 'str',
    description: 'The identifier key to remove from the context store.',
  }
}"
/>

***

## Scoping & Contextvars Lifecycle [#scoping--contextvars-lifecycle]

### `scope` [#scope]

Context manager for localized state overrides within a specific code block. Temporarily sets attributes (including properties like `user_id`) and automatically restores the previous state upon block exit.

```python
# Temporarily act as System User for a specific batch operation
with ctx.scope(user_id=SYSTEM_UUID, tenant_id="system"):
    await perform_maintenance_task()

# Context automatically reverts to original user_id and tenant_id here
```

<TypeTable
  type="{
  '**kwargs': {
    type: 'Any',
    description: 'Key-value pairs to set temporarily in the context scope.',
  },
  returns: {
    type: 'ContextManager',
    description: 'A context manager restoring previous state upon exit.',
  }
}"
/>

### `initialize` [#initialize]

Resets the context store to an empty state for the current async task scope. Returns a `contextvars.Token` used for restoring previous state.

```python
token: Token[Dict[str, Any]] = ctx.initialize()
```

### `reset` [#reset]

Restores the context store to the state corresponding to the provided token.

```python
ctx.reset(token)
```


# ZTestClient & BaseZTest (/docs/api-reference/ztest-client)





`ZTestClient` is an asynchronous test orchestrator wrapping `httpx.AsyncClient`. It coordinates the entire ZCore runtime lifecycle (IoC container sandboxing, event subscriber snapshots, savepoint database rollbacks, and request context mocking) for seamless, zero-boilerplate integration testing.

## Class Definition [#class-definition]

```python
from collections.abc import Sequence
from typing import Any
from fastapi import FastAPI
from pydantic import BaseModel
from sqlalchemy.ext.asyncio import AsyncEngine
from zcore.testing import ZTestClient

class ZTestClient:
    def __init__(
        self,
        app: FastAPI,
        user_id: Any | None = None,
        scopes: list[str] | None = None,
        is_superuser: bool = False,
        use_db: bool = True,
        engine: AsyncEngine | None = None,
        db_dependency: Any | Sequence[Any] | None = None,
        user_dependency: Any | Sequence[Any] | None = None,
        user_model: type[BaseModel] | None = None,
        extra_context: dict[str, Any] | None = None,
        extra_user_attrs: dict[str, Any] | None = None,
    ) -> None:
        ...
```

***

## Initialization Parameters [#initialization-parameters]

<TypeTable
  type="{
  app: {
    type: 'FastAPI',
    description: 'The FastAPI application instance to mount and test.',
  },
  user_id: {
    type: 'Any | None',
    default: 'None',
    description: 'Mock user ID for authentication. When provided, automatically configures UserContext and DependencyOverride fixtures.',
  },
  scopes: {
    type: 'list[str] | None',
    default: 'None',
    description: 'Security permission scopes assigned to the mock user for authorization assertions.',
  },
  is_superuser: {
    type: 'bool',
    default: 'False',
    description: 'Boolean flag indicating if the mock user has superuser privileges (bypassing scope checks).',
  },
  use_db: {
    type: 'bool',
    default: 'True',
    description: 'If True, wraps the test execution in an isolated database transaction that rolls back on exit.',
  },
  engine: {
    type: 'AsyncEngine | None',
    default: 'None',
    description: 'Custom SQLAlchemy AsyncEngine instance to use instead of the global DatabaseManager.',
  },
  db_dependency: {
    type: 'Any | Sequence[Any] | None',
    default: 'None',
    description: 'Single or sequence of database session dependencies to override on the target app.',
  },
  user_dependency: {
    type: 'Any | Sequence[Any] | None',
    default: 'None',
    description: 'Single or sequence of custom authentication dependencies to override alongside default stubs.',
  },
  user_model: {
    type: 'type[BaseModel] | None',
    default: 'None',
    description: 'Custom Pydantic model class to validate and instantiate the mock user instance via user_model.model_validate().',
  },
  extra_context: {
    type: 'dict[str, Any] | None',
    default: 'None',
    description: 'Additional key-value pairs to inject directly into the request-scoped ZContext (e.g., {&#x22;restricted_fields&#x22;: [...]}).',
  },
  extra_user_attrs: {
    type: 'dict[str, Any] | None',
    default: 'None',
    description: 'Additional domain attributes to attach to the mock user instance (e.g., {&#x22;department&#x22;: &#x22;HR&#x22;}).',
  }
}"
/>

***

## Context Manager Protocol [#context-manager-protocol]

`ZTestClient` implements the asynchronous context manager protocol (`__aenter__` and `__aexit__`), returning a fully configured `httpx.AsyncClient` bound to the application:

```python
import pytest
import uuid
from zcore.testing import ZTestClient
from main import app

@pytest.mark.asyncio
async def test_create_task_endpoint():
    user_id = uuid.uuid4()
    
    async with ZTestClient(
        app=app, 
        user_id=user_id, 
        scopes=["tasks:create", "tasks:view"],
        use_db=True
    ) as client:
        # Executes HTTP requests against the application transport
        response = await client.post("/tasks/", json={"title": "Write Unit Tests"})
        assert response.status_code == 201
        
    # Database changes are automatically rolled back and IoC sandboxes are restored here!
```

***

## Class-Based Testing: `BaseZTest` [#class-based-testing-baseztest]

An abstract base class for structuring declarative test suites sharing identical user attributes and application setups:

```python
from collections.abc import Sequence
from typing import Any
from fastapi import FastAPI
from pydantic import BaseModel
from sqlalchemy.ext.asyncio import AsyncEngine
from zcore.testing import BaseZTest

class BaseZTest(ABC):
    app: FastAPI = None
    user_id: Any = None
    is_active: bool = True
    is_superuser: bool = False
    scopes: list[str] | None = None
    engine: AsyncEngine | None = None
    db_dependency: Any | Sequence[Any] | None = None
    user_dependency: Any | Sequence[Any] | None = None
    user_model: type[BaseModel] | None = None
    extra_user_attrs: dict[str, Any] | None = None
    extra_context: dict[str, Any] | None = None
```

<TypeTable
  type="{
  app: {
    type: 'FastAPI',
    description: 'The root FastAPI application instance (required).',
  },
  user_id: {
    type: 'Any',
    default: 'uuid.uuid4()',
    description: 'Mock user ID used across tests in the suite.',
  },
  is_active: {
    type: 'bool',
    default: 'True',
    description: 'User active state status.',
  },
  is_superuser: {
    type: 'bool',
    default: 'False',
    description: 'Superuser permission bypass flag.',
  },
  scopes: {
    type: 'list[str] | None',
    default: 'None',
    description: 'List of permission scopes assigned to the suite user.',
  },
  engine: {
    type: 'AsyncEngine | None',
    default: 'None',
    description: 'Custom AsyncEngine bound to transactional savepoints.',
  },
  db_dependency: {
    type: 'Any | Sequence[Any] | None',
    default: 'None',
    description: 'Database session dependency targets to override.',
  },
  user_dependency: {
    type: 'Any | Sequence[Any] | None',
    default: 'None',
    description: 'Custom user dependency targets to override.',
  },
  user_model: {
    type: 'type[BaseModel] | None',
    default: 'None',
    description: 'Pydantic model class to validate and instantiate the suite user.',
  },
  extra_user_attrs: {
    type: 'dict[str, Any] | None',
    default: 'None',
    description: 'Custom domain attributes attached to the mock user.',
  },
  extra_context: {
    type: 'dict[str, Any] | None',
    default: 'None',
    description: 'Context parameters injected into ZContext.',
  }
}"
/>

### `run` Method [#run-method]

An asynchronous context manager method on `BaseZTest` that instantiates `ZTestClient` using the class-level attributes and yields the `httpx.AsyncClient`:

```python
import pytest
from zcore.testing import BaseZTest
from main import app

class TestTaskSuite(BaseZTest):
    app = app
    scopes = ["tasks:view", "tasks:create"]

    @pytest.mark.asyncio
    async def test_get_tasks_list(self):
        async with self.run() as client:
            res = await client.get("/tasks/")
            assert res.status_code == 200
```

<Callout type="info" emoji="🧪">
  **Orchestrated Internal Fixtures:**
  `ZTestClient` automatically coordinates `ContainerSandbox` (IoC isolation), `EventDispatcherSandbox` (event subscriber isolation), `AppLifespan` (plugin startup/shutdown lifespans), `DatabaseRollback` (savepoint transactions), `UserContext` (`ContextVar` store injection), and `DependencyOverride` (`get_current_user_stub`, `get_optional_user_stub`, and any custom targets) on every test run.
</Callout>


# Caching & Real-Time Streaming (/docs/core-concepts/cache-and-streams)





ZCore provides unified infrastructure for high-speed distributed data access and real-time event streaming, designed to operate seamlessly with Redis in clustered environments while gracefully degrading to in-memory fallbacks when standalone.

***

## 1. The `BaseCache` Dual-Layer Resilience Architecture [#1-the-basecache-dual-layer-resilience-architecture]

`BaseCache` acts as a transparent, fault-tolerant caching gateway. When configured with a Redis connection URL (`init_cache(redis_url)`), all operations are directed to distributed Redis keyspaces.

<Mermaid
  chart="graph TB
Op[cache.get / cache.set] --> CheckRedis{Is Redis Connected?}
CheckRedis -- Yes --> RedisCmd[Execute Redis Command]
RedisCmd -- Success --> Done[Return Data]
RedisCmd -- Connection Error / Timeout --> Log[Log Error & Fallback]
CheckRedis -- No / Unconfigured --> Local[Execute TTLLRUCache In-Memory]
Log --> Local
Local --> Done"
/>

<Callout type="warn" emoji="🛡️">
  **Graceful Network Degradation:*&#x2A;
  If a network partition or Redis outage occurs mid-request, ZCore catches the connection error, logs the diagnostic warning, and immediately serves/stores the record in the local, thread-safe in-memory &#x2A;*`TTLLRUCache`**. When Redis recovers, operations automatically route back to distributed caching without restarting the application.
</Callout>

### Dynamic Framework Boundaries [#dynamic-framework-boundaries]

Both `BaseCache` and `TTLLRUCache` dynamically bind to centralized framework configuration settings with sensible fallbacks:

* **Default Lifespan (`CACHE_DEFAULT_TTL`):** Fallback TTL (default: **3600 seconds**) applied automatically when `ttl` is omitted in `cache.set()`.
* **Local In-Memory Capacity (`CACHE_LOCAL_MAXSIZE`):** Maximum key volume (default: **1000 items**) retained in the local fallback store before LRU eviction triggers.
* **Garbage Collection Sweep (`CACHE_EVICTION_INTERVAL`):** Interval in seconds (default: **60 seconds**) between non-blocking background sweeps purging expired records.

### Automatic Pydantic V2 Deserialization [#automatic-pydantic-v2-deserialization]

You can supply `target_type=TaskResponse` to `cache.get()`. ZCore automatically deserializes the raw JSON string and executes `TaskResponse.model_validate()`, returning strongly-typed model instances:

```python
# Fetches from Redis/Local cache and validates schema automatically
task: TaskResponse | None = await cache.get("task_123", target_type=TaskResponse)
```

### Background Garbage Collection (`weakref.WeakSet`) [#background-garbage-collection-weakrefweakset]

`TTLLRUCache` instances are registered in a global `weakref.WeakSet`. This allows the background asynchronous eviction loop (`_start_eviction_loop`) to sweep expired keys across all active caches at intervals defined by `settings.CACHE_EVICTION_INTERVAL` without creating circular memory references or preventing clean de-allocation.

***

## 2. Real-Time Streaming Engine (`StreamManager`) [#2-real-time-streaming-engine-streammanager]

For real-time features like WebSockets, Server-Sent Events (SSE), and live notifications, ZCore provides the &#x2A;*`StreamManager`**.

### Cluster-Wide Message Propagation [#cluster-wide-message-propagation]

`StreamManager` connects to Redis PubSub using pattern subscription (`stream:user:*`). When any worker node in your cluster publishes an event to a user, all nodes receive the frame and route it to the active local queues for that user.

```python
# Stream Manager Subscription Lifecycle (e.g., in an SSE or WebSocket route)
from fastapi.responses import StreamingResponse
from zcore.web import StreamManager

stream_manager = StreamManager()

@router.get("/tasks/stream/{user_id}")
async def stream_user_events(user_id: str):  # Accepts polymorphic user IDs (UUID, int, or str)
    async def event_generator():
        # Automatically subscribes and handles cleanup upon connection closure
        async with stream_manager.subscription(user_id) as queue:
            while True:
                data = await queue.get()
                yield f"data: {data}\n\n"
                
    return StreamingResponse(event_generator(), media_type="text/event-stream")
```

### Slow-Consumer Overflow Protection [#slow-consumer-overflow-protection]

Each connected client listener is allocated a bounded `asyncio.Queue` whose capacity is resolved dynamically from `settings.STREAM_QUEUE_MAXSIZE` (default: **100 items**):

* If a publisher pushes events faster than a client can consume them and the queue reaches capacity, `StreamManager` catches `asyncio.QueueFull`.
* It immediately unregisters and drops the overflowing queue, safeguarding node memory against buffer bloat and memory exhaustion.

<Callout type="info" emoji="⚡">
  **Standalone Mode:** If Redis is uninitialized, `StreamManager` routes events directly through local memory queues, allowing real-time features to function in single-node development environments out of the box.
</Callout>


# CLI & Structured Logging (/docs/core-concepts/cli-and-logging)





ZCore provides native tooling to streamline developer ergonomics and guarantee production observability through introspection-driven CLI commands, cascading development servers, and a centralized, context-aware logging pipeline.

***

## 1. Dynamic Environment Introspection (`zc genenv`) [#1-dynamic-environment-introspection-zc-genenv]

Out-of-sync environment templates (`.env.example`) are a frequent source of deployment failures. ZCore eliminates manual `.env` synchronization through runtime class introspection.

### How `zc genenv` Works [#how-zc-genenv-works]

1. Imports your application package context (`main.py`).
2. Evaluates all registered subclasses of `Settings` via `Settings.__subclasses__()` and selects the active schema configuration.
3. Iterates over Pydantic's `model_fields`, formats default values, and writes a clean `.env.example` file.

```bash
# Generate .env.example based on your active AppSettings class
zc genenv

# Overwrite an existing configuration template
zc genenv --force -o .env.production.example
```

***

## 2. Cascading Server Runner (`zc run`) [#2-cascading-server-runner-zc-run]

ZCore provides an intelligent development and production server runner that resolves configuration hierarchically:

> **CLI Arguments*&#x2A; $\longrightarrow$ **.env File Variables** $\longrightarrow$ **Built-in Defaults**

### Architecture & Precedence Resolution [#architecture--precedence-resolution]

When executing `zc run [app]`, the CLI runner executes the following lifecycle:

1. **Environment File Parsing:** Reads key-value pairs safely from `.env` (or custom file via `--env-file`), resolving `APP_MODULE`, `UVICORN_APP`, `HOST`, `PORT`, `RELOAD`, `DEBUG`, `WORKERS`, and `LOG_LEVEL`.
2. **CLI Override Enforcement:** Explicit flags (e.g. `--host 0.0.0.0 --port 8080`) take immediate precedence over `.env` variables and defaults (`127.0.0.1:8000`).
3. **Smart Multi-Worker Protection:** When `--workers` is set to greater than `1` (or specified in `.env`), live code reloading (`--reload`) is **automatically disabled** to prevent worker race conditions.
4. **Transparent Uvicorn Passthrough:** The CLI uses `parse_known_args()` to capture any arbitrary Uvicorn flags (such as `--proxy-headers`, `--ssl-keyfile`, or `--forwarded-allow-ips`) and forwards them directly to the underlying server process.

```bash
# Example: Production multi-worker execution with arbitrary Uvicorn flags
zc run --workers 4 --log-level warning --proxy-headers --forwarded-allow-ips="*"
```

***

## 3. Structured Logging Pipeline (`structlog`) [#3-structured-logging-pipeline-structlog]

Standard FastAPI, Uvicorn, and SQLAlchemy logging often outputs unformatted, duplicated text streams that are difficult to parse in log aggregators.

ZCore's `setup_logging()` intercepts and unifies this pipeline through `ProcessorFormatter`:

<Mermaid
  chart="graph TB
App[App & Service Logs] --> Struct[Unified structlog Engine]
Muted[muted_loggers: sqlalchemy.engine] --> Drop[Clear Handlers & Suppress]
PassDev[passthrough_loggers: uvicorn in Dev] --> Console[Native Formatted Console Output]
InterceptProd[intercept_loggers: uvicorn in Prod] --> Struct
Struct --> Context[structlog.contextvars merge request_id]
Context --> Mode[JSONRenderer in Prod / ConsoleRenderer in Dev]"
/>

1. **Granular Logger Routing (Tri-Split Loggers):** ZCore categorizes loggers into three distinct groups in `LoggingSettings`:
   * `muted_loggers` (default: `["sqlalchemy.engine"]`): Clears handlers and sets `propagate = False` to prevent noisy low-level logs.
   * `passthrough_loggers` (default: `["uvicorn", "uvicorn.access", "uvicorn.error"]`): Preserves native, colorized Uvicorn console formatting in development mode (`propagate = False`).
   * `intercept_loggers` (default: `["uvicorn", "uvicorn.access", "uvicorn.error"]`): Clears handlers and channels Uvicorn output into `structlog` as structured JSON records when running in production mode (`propagate = True`).
2. **Contextual Distributed Tracing:** `RequestLogMiddleware` extracts or generates an `x-request-id` header (validated against `^[a-zA-Z0-9\-\.\_\:]{8,64}$`), binds it via `structlog.contextvars.bind_contextvars(request_id=...)`, and appends the correlation ID to response headers. Every log message emitted across repositories, services, or events automatically includes the unique `request_id`, while HTTP requests log `status_code`, `client_ip`, and `duration_ms`.
3. **Adaptive Output Rendering:**
   * **Development (`DEBUG = True` or `json_format = False`):** Colorized, human-readable console rendering with formatted tracebacks via `rich.traceback`.
   * **Production (`DEBUG = False` or `json_format = True`):** Serialized, high-throughput JSON records containing ISO timestamps, log levels, and contextual metadata, ready for ingestion by Grafana Loki, ELK, or Datadog.

### Declarative Configuration (`LoggingSettings`) [#declarative-configuration-loggingsettings]

Logging can be configured declaratively through `Settings.LOGGING` using the `LoggingSettings` schema or overridden directly in `setup_logging()`:

```python
from zcore.config import LoggingSettings, Settings

class AppSettings(Settings):
    LOGGING: LoggingSettings = LoggingSettings(
        level="INFO",
        json_format=None,              # None: Console in Debug, JSON in Production
        log_sql_queries=False,         # Defaults to False in rc.2 to avoid noise
        slow_query_threshold_ms=200.0, # Log only queries exceeding 200ms (works independently!)
        file_path="./logs/app.log",    # Enables RotatingFileHandler
        max_bytes=10 * 1024 * 1024,    # Rotate when file reaches 10MB (Default: 10MB)
        backup_count=5,                # Retain 5 rotated log backups (Default: 5)
        muted_loggers=["sqlalchemy.engine"],
        passthrough_loggers=["uvicorn", "uvicorn.access", "uvicorn.error"],
        custom_processors=[]
    )
```

### Advanced `setup_logging` Overrides [#advanced-setup_logging-overrides]

`setup_logging()` supports programmatic configuration, file rotation, custom processors, extra standard library handlers, and complete `dictConfig` overrides:

```python
from zcore.logging import setup_logging, LoggingSettings
import logging

# 1. Zero-code initialization (reads from settings.LOGGING)
setup_logging()

# 2. Programmatic LoggingSettings or dict config
setup_logging(
    config=LoggingSettings(
        level="DEBUG",
        file_path="./logs/app.log",
        max_bytes=20 * 1024 * 1024,
        backup_count=10,
        slow_query_threshold_ms=100.0
    )
)

# 3. Custom processors and extra handlers
setup_logging(
    custom_processors=[my_structlog_processor],
    extra_handlers=[logging.StreamHandler()],
    log_level="DEBUG"
)

# 4. Full logging.config.dictConfig override
setup_logging(
    dict_config={
        "version": 1,
        "disable_existing_loggers": False,
        "handlers": {
            "console": {"class": "logging.StreamHandler", "level": "INFO"}
        },
        "root": {"handlers": ["console"], "level": "INFO"}
    }
)
```

<Callout type="info" emoji="⚡">
  **SQL Query Diagnostics:**
  `DatabaseManager` hooks directly into SQLAlchemy cursor lifecycle events (`before_cursor_execute` and `after_cursor_execute`). When `log_sql_queries` is enabled, it logs clean, sanitized SQL statements along with execution durations in milliseconds (`duration_ms`), while automatically filtering out internal schema catalog noise. If `slow_query_threshold_ms` is configured, slow queries are tracked and logged independently, even if general query logging is turned off.
</Callout>


# Configuration & Context Management (/docs/core-concepts/context)





One of the most critical challenges in asynchronous web frameworks is managing state safely across concurrent requests. ZCore provides two foundational primitives for this: &#x2A;*`SettingsProxy`*&#x2A; for global application settings and &#x2A;*`ZContext`** for thread-safe, coroutine-aware request state.

***

## 1. The Settings Proxy (Lazy Resolution) [#1-the-settings-proxy-lazy-resolution]

In standard Python applications, importing settings modules at the top of files often causes circular dependency errors or triggers premature database engine instantiation before the application is ready.

ZCore solves this using `SettingsProxy`.

<Callout type="info" emoji="⚙️">
  **Under the Hood:** When you execute `from zcore import settings`, you are not importing a static instance. You are importing a lightweight `SettingsProxy` object.
  This proxy intercepts all attribute lookups (via `__getattr__`) and dynamically resolves the active `Settings` singleton from the `IoCContainer` **only when an attribute is actually accessed**.
</Callout>

This guarantees that `settings.DATABASE.url`, `settings.DATABASE_URL`, or `settings.SECRET_KEY` can be safely imported anywhere in your codebase without premature execution.

### Structured Settings Schemas & Subsystems [#structured-settings-schemas--subsystems]

Settings in ZCore are structured into dedicated sub-models and framework-wide parameters:

* **`DATABASE` (`DatabaseSettings`)**: Manages connection URL, pool sizing (`pool_size`, `max_overflow`), connection recycles (`pool_recycle`), health checks (`pool_pre_ping`), and engine parameters (`connect_args`, `execution_options`, `extra_engine_kwargs`).
* **`LOGGING` (`LoggingSettings`)**: Manages log levels, formatters (`json_format`), SQL query logging (`log_sql_queries`), slow query thresholds (`slow_query_threshold_ms`), rotating file logs (`file_path`), file rotation bounds (`max_bytes`, `backup_count`), and muted loggers (`muted_loggers`).
* **Timezone Policies**: Global timezone configurations (`TIMEZONE="UTC"`) and automatic ISO serialization conversions (`AUTO_CONVERT_TIMEZONE=True`).

### Framework-Wide Tunable Parameters [#framework-wide-tunable-parameters]

ZCore exposes centralized, environment-driven boundaries across all framework subsystems:

| Subsystem          | Setting Key               | Default         | Description                                                              |
| ------------------ | ------------------------- | --------------- | ------------------------------------------------------------------------ |
| **Pagination**     | `PAGINATION_DEFAULT_SIZE` | `20`            | Fallback page size when omitted in requests.                             |
| **Pagination**     | `PAGINATION_MAX_SIZE`     | `100`           | Hard upper bound enforced on page size parameters.                       |
| **Search**         | `SEARCH_MAX_DEPTH`        | `3`             | Maximum allowed depth for nested filters and relation eager-loading.     |
| **Authentication** | `AUTH_CACHE_TTL`          | `300` (5 min)   | Lifespan of cached user sessions in `BaseAuth`.                          |
| **Cache**          | `CACHE_DEFAULT_TTL`       | `3600` (1 hour) | Default fallback TTL for `BaseCache.set()`.                              |
| **Cache**          | `CACHE_LOCAL_MAXSIZE`     | `1000`          | Maximum capacity of the local in-memory `TTLLRUCache`.                   |
| **Cache**          | `CACHE_EVICTION_INTERVAL` | `60`            | Duration in seconds between background memory cleanup sweeps.            |
| **Streaming**      | `STREAM_QUEUE_MAXSIZE`    | `100`           | Bounded capacity for user real-time streaming queues in `StreamManager`. |

<Callout type="info" emoji="🔄">
  **Bidirectional Sync:** ZCore maintains backward compatibility by automatically synchronizing flat environment variables (such as `DATABASE_URL`, `POOL_SIZE`, `MAX_OVERFLOW`, and `LOG_LEVEL`) with their corresponding structured `DATABASE` and `LOGGING` models.
</Callout>

### Extending Settings [#extending-settings]

ZCore automatically binds your `Settings` instance into the IoC container. To add domain-specific variables or configure structured sub-models, inherit from `Settings` and pass the instance to `initialize_settings` at the top of your `main.py`:

```python
# main.py
from zcore.config import DatabaseSettings, LoggingSettings, Settings, initialize_settings

class AppSettings(Settings):
    AWS_BUCKET: str = "default-bucket"
    EXTERNAL_API_KEY: str = ""
    DATABASE: DatabaseSettings = DatabaseSettings(
        url="postgresql+asyncpg://postgres:postgres@localhost:5432/production_db",
        pool_size=20,
    )
    LOGGING: LoggingSettings = LoggingSettings(
        level="DEBUG",
        slow_query_threshold_ms=200.0,
        max_bytes=20 * 1024 * 1024,
        backup_count=10,
    )

# Register the subclass into ZCore's IoC container
initialize_settings(AppSettings())
```

***

## 2. ZContext (Request-State Isolation) [#2-zcontext-request-state-isolation]

FastAPI processes thousands of concurrent async requests within a single event loop. Storing request state (such as the active user's identity or tenant ID) in global variables causes race conditions where concurrent requests overwrite each other's data.

ZCore provides &#x2A;*`ZContext`** (`ctx`), an asynchronous execution context store built directly on Python's native `contextvars`.

### How Contextvars Work in ZCore [#how-contextvars-work-in-zcore]

1. When an HTTP connection hits `RequestLogMiddleware`, ZCore calls `ctx.initialize()`, creating an isolated memory dictionary tied to that specific coroutine execution tree.
2. During the request lifecycle, authentication and authorization layers attach state to `ctx`.
3. When the HTTP response finishes, `ctx.reset(token)` is triggered in a `finally` block, releasing the memory cleanly.

<Mermaid
  chart="graph TB
Req[Incoming HTTP Request] --> Init[ctx.initialize]
Init --> Auth[BaseAuth binds user_id & restricted_fields]
Auth --> App[Business Logic & Zchema Projection]
App --> Clean[ctx.reset token]
Clean --> Res[HTTP Response Sent]"
/>

### Strongly-Typed Properties [#strongly-typed-properties]

Instead of relying on unstructured dictionary strings, `ZContext` exposes strongly-typed, validated properties:

* **`ctx.user_id`**: Stores the authenticated user identifier as `Any | None`. As of `rc.2`, it seamlessly supports arbitrary identifier formats (such as auto-incrementing integers, UUIDs, or external strings like Auth0/Firebase IDs) without enforcing rigid type constraints.
* **`ctx.restricted_fields`**: Managed as an immutable `frozenset`. Once loaded during authentication, business logic cannot accidentally mutate restriction paths mid-flight.

### Dynamic Context Operations [#dynamic-context-operations]

```python
from zcore import ctx

# Store arbitrary request-scoped data
ctx.set("tenant_id", "enterprise_001")

# Retrieve values with optional fallbacks
tenant = ctx.get("tenant_id", default="public")

# Delete specific keys
ctx.remove("tenant_id")
```

### Temporary Context Scoping (`ctx.scope`) [#temporary-context-scoping-ctxscope]

If you need to temporarily override context values for a specific block of logic (e.g., executing a background task as a System User or impersonating an account), use the `ctx.scope()` context manager:

```python
from zcore import ctx

async def perform_system_migration():
    # Temporarily override user_id and scopes within this block
    with ctx.scope(user_id=SYSTEM_BOT_UUID, scopes=["system:admin"]):
        # All services, repos, and logs inside this block see the System Bot identity
        await run_migration_task()
        
    # The context automatically reverts to its original caller state here
```

<Callout type="info" emoji="🔒">
  **Security Assurance:** `ZContext` variables do not bleed across async task boundaries. Each concurrent coroutine maintains absolute state isolation.
</Callout>


# Dependency Injection (IoC Container) (/docs/core-concepts/di)





ZCore does not rely on FastAPI's native `Depends()&#x60; chains for internal service wiring. Instead, it implements a high-performance &#x2A;*`IoCContainer`** designed for constructor auto-wiring and clean architecture separation.

***

## 1. The Problem with Nested `Depends()` [#1-the-problem-with-nested-depends]

In standard FastAPI, if a route depends on a service, the service depends on a repository, and the repository depends on an `AsyncSession`, you end up with deeply nested, tightly coupled `Depends()` chains in your HTTP layer:

```python
# Standard FastAPI (High coupling & boilerplate)
@router.post("/tasks")
def create_task(
    service: TaskService = Depends(get_task_service) # get_task_service must resolve repo & session
):
    pass
```

This couples web routes directly to internal persistence details, degrades IDE type-hinting, and makes unit testing difficult.

***

## 2. The `Inject[T]` Abstraction [#2-the-injectt-abstraction]

ZCore uses Python's `Annotated` metadata system to seamlessly bridge FastAPI's route dependency injection with ZCore's IoC container:

```python
# ZCore Approach (Clean & Decoupled)
from zcore import Inject

@router.post("/tasks")
async def create_task(service: Inject[TaskService]):
    await service.create(...)
```

<Callout type="info" emoji="🧩">
  **Compilation Magic:** When you annotate a parameter with `service: Inject[TaskService]`, the `Inject` class intercepts the `__class_getitem__` dunder method. It compiles this into:
  `Annotated[TaskService, Depends(Injector(TaskService))]`.

  This preserves 100% compatibility with FastAPI's OpenAPI generation while delegating full dependency graph assembly to ZCore's IoC container.
</Callout>

***

## 3. Lifecycle Management [#3-lifecycle-management]

The `IoCContainer` coordinates three distinct instance lifecycles:

1. **Singleton:** Instantiated once for the entire application lifespan and stored in `container._singletons` (e.g., `EventDispatcher`, `Settings`).
2. **Scoped:** Instantiated once per ASGI HTTP request and bound to the coroutine context via `ContextVar` (`_scoped_instances`). Managed and automatically purged by `ScopedDependencyMiddleware` after the response is sent (e.g., `AsyncSession`).
3. **Transient:** A fresh, independent instance is created every time `container.resolve()` is executed (e.g., stateless helper utilities).

***

## 4. Auto-Wiring & Signature Caching [#4-auto-wiring--signature-caching]

Inside your classes and services, you do not need decorators. Declare dependencies in the constructor via standard type hints:

```python
class TaskService:
    # ZCore inspects the type hint and resolves TaskRepo automatically
    def __init__(self, repository: TaskRepo):
        self.repository = repository
```

When `container.resolve(TaskService)` is invoked:

1. The container inspects `TaskService.__init__` using `inspect.signature` and `typing.get_type_hints`.
2. **Signature Caching:** To eliminate the runtime performance overhead of Python reflection, ZCore caches the constructor parameter dependencies in `_dependency_signature_cache` and constructor references in `_constructor_cache`.
3. Subsequent resolutions bypass reflection completely, reading directly from the warm signature cache to construct instances with near-zero latency.

***

## 5. Circular Dependency Detection [#5-circular-dependency-detection]

If `ServiceA` depends on `ServiceB`, and `ServiceB` depends on `ServiceA`, a naive container would enter infinite recursion and crash the interpreter.

ZCore tracks the active resolution graph using an internal `_stack` set during auto-wiring. If a class is encountered that already exists in the active stack, it raises a readable `CircularDependencyError`:

```text
CircularDependencyError: Circular dependency detected: ServiceA -> ServiceB -> ServiceA
```

<Callout type="info" emoji="⚡">
  **Constructor vs Route Usage:**

  * **In Class Constructors (`__init__`):** Use plain Python type hints (`def __init__(self, repo: TaskRepo):`).
  * **In FastAPI Route Endpoints:** Use `Inject[T]` (`async def route(service: Inject[TaskService]):`).
</Callout>

***

## 6. Background Tasks & Isolated Scope (`background_scope`, `@background_task`) [#6-background-tasks--isolated-scope-background_scope-background_task]

When an HTTP request completes, the ASGI middleware disposes of the request-scoped database session and purges `_scoped_instances`. Running background routines after the request finishes requires an independent scope.

ZCore provides two utilities for safe background processing:

### A. The `@background_task` Decorator [#a-the-background_task-decorator]

Decorate any asynchronous coroutine or standard synchronous function. The decorator:

1. Spawns an isolated `background_scope()`.
2. Automatically allocates a fresh, dedicated `AsyncSession`.
3. Inspects the function's signature and auto-resolves any missing type-annotated dependencies via `container.resolve()`.
4. Executes synchronous functions in a dedicated worker threadpool via `anyio.to_thread.run_sync`.

```python
from zcore import background_task
from tasks.services import TaskService

@background_task
async def send_welcome_email(user_id: uuid.UUID, service: TaskService):
    # 'service' and its underlying AsyncSession are automatically resolved in an isolated scope
    await service.notify(user_id)
```

<Callout type="warn" emoji="⚠️">
  **Avoid Passing Active Request Sessions:** Do not pass an existing `AsyncSession` from an HTTP route directly into a background task. The request session will be closed when the HTTP response completes. Let `@background_task` inject an isolated session automatically; passing an active session triggers a runtime logger warning.
</Callout>

### B. The `background_scope` Context Manager [#b-the-background_scope-context-manager]

For manual execution blocks, `background_scope` provides explicit boundary control:

```python
from zcore import background_scope

async with background_scope(inherit_context=True, custom_flag="worker"):
    # Clean, isolated IoC and DB session lifecycle
    ...
```


# Kernel & Plugin Orchestration (/docs/core-concepts/kernel)





As monolithic applications or microservices grow, managing disparate `@app.on_event("startup")&#x60; hooks across multiple domains leads to non-deterministic startup bugs. ZCore introduces the &#x2A;*`Kernel`*&#x2A; and a runtime-checkable &#x2A;*`Plugin`** protocol to enforce a deterministic Directed Acyclic Graph (DAG) lifecycle.

***

## 1. The Plugin Protocol [#1-the-plugin-protocol]

A ZCore plugin is a modular domain unit conforming to the `Plugin` protocol. Each plugin declares its metadata, upstream dependencies, and lifecycle hooks:

```python
# plugins.py
from fastapi import FastAPI
from zcore import Plugin

class TasksPlugin(Plugin):
    name: str = "tasks"
    version: str = "1.0.0"
    dependencies: list[str] = ["auth"]  # Requires AuthPlugin to start first

    def setup(self, app: FastAPI) -> None:
        # Attach routers and middleware during application initialization
        from .routers import router_instance
        app.include_router(router_instance.router)

    async def before_startup(self) -> None:
        # Pre-initialization routines
        pass

    async def on_startup(self) -> None:
        # Core domain startup (e.g., cache warming)
        pass

    async def after_startup(self) -> None:
        # Post-initialization tasks
        pass

    async def on_shutdown(self) -> None:
        # Teardown logic (e.g., closing domain-specific connection pools)
        pass
```

***

## 2. Topological Sorting (DAG Resolution) [#2-topological-sorting-dag-resolution]

When `kernel.setup(app)` is executed, the Kernel inspects all registered plugins and builds a dependency graph. Using Python's native `graphlib.TopologicalSorter`, it flattens the graph into a strictly ordered execution sequence:

<Mermaid
  chart="graph LR
Auth[AuthPlugin] --> Tasks[TasksPlugin]
Auth --> Billing[BillingPlugin]
Tasks --> Reports[ReportsPlugin]
Billing --> Reports"
/>

<Callout type="warn" emoji="⚠️">
  **Strict Dependency Integrity:**

  * **Missing Dependencies:** If `TasksPlugin` declares `dependencies = ["auth"]`, but no plugin with `name = "auth"` was added to the Kernel, startup aborts immediately with a descriptive `RuntimeError`.
  * **Cyclic Dependencies:** If Plugin A depends on Plugin B, and Plugin B depends on Plugin A, the Kernel detects the cycle and raises a `RuntimeError` before running any application code.
</Callout>

***

## 3. Deterministic Lifespan Orchestration [#3-deterministic-lifespan-orchestration]

The Kernel integrates natively with FastAPI's `lifespan` context manager (`FastAPI(lifespan=kernel.lifespan)`).

### Startup Sequence (Topological Order) [#startup-sequence-topological-order]

1. Runs `before_startup()` for all plugins in dependency order.
2. Runs `on_startup()` for all plugins in dependency order.
3. Runs `after_startup()` for all plugins in dependency order.

### Shutdown Sequence (Strictly Reversed Order) [#shutdown-sequence-strictly-reversed-order]

Upon application termination, the Kernel executes `on_shutdown()` in **reverse topological order**.

If `AuthPlugin` started before `TasksPlugin`, then `TasksPlugin` will shut down **before** `AuthPlugin`. This prevents orphaned state transitions or database errors if `TasksPlugin` attempts to write audit logs during shutdown.

Once all plugins have safely completed their shutdown hooks, the Kernel automatically releases framework resources by closing active cache connections (`close_cache()`) and disposing the database engine pool (`db_manager.close()`).

***

## 4. Centralized Event Dispatching [#4-centralized-event-dispatching]

During `kernel.setup(app)`, the Kernel automatically registers its active `EventDispatcher` instance as a global Singleton in the `IoCContainer`:

```python
# Kernel registers the singleton internally:
container.register_singleton(EventDispatcher, self.dispatcher)
```

This decouples your application layers: any service or repository can inject `EventDispatcher` and publish domain events without holding direct references to listening modules.


# Dynamic Search Engine & Security (/docs/core-concepts/search)





Exposing arbitrary database filtering to frontend clients is traditionally dangerous. ZCore's &#x2A;*`SearchEngine`** provides a declarative, expressive JSON search protocol that compiles down to safe, optimized SQLAlchemy 2.0 AST expressions while enforcing strict security boundaries.

***

## 1. The Compilation Pipeline [#1-the-compilation-pipeline]

When a `SearchRequest` payload is received (typically via `POST /search` or `POST /lookup`), the `SearchEngine` coordinates execution across three distinct phases:

<Mermaid
  chart="graph TB
Req[SearchRequest JSON] --> Val[1. Security & Depth Validation]
Val --> Exp[2. Expression & Loader Compilation]
Exp --> Exec[3. SQLAlchemy Execution & Pagination]"
/>

1. **Validation & Security Assertion:** Inspects all requested field paths, sort columns, and inclusion routes against `ctx.restricted_fields` and schema mappers.
2. **Expression Building & Type Coercion:** Recursively translates structured JSON comparison operators (`eq`, `ne`, `gt`, `lt`, `ge`, `le`, `like`, `ilike`, `contains`, `startswith`, `endswith`, `in`, `between`, `is_null`), inverted operators (`not_like`, `not_ilike`, `not_contains`, `not_startswith`, `not_endswith`, `not_in`, `not_between`, `is_not_null`), and logical grouping blocks (`and`, `or`, `not`) into SQLAlchemy comparison clauses while safely coercing input types (`int`, `float`, `date`, `datetime`, `UUID`, `bool`, and `set`).
3. **Execution & Eager-Loading:** Injects relation loaders (`joinedload` / `selectinload`), applies column projection (`fields` via `load_only`), custom SQLAlchemy options (`options`), sorting rules, and passes the query to the repository paginator.

***

## 2. Supported Filter Operators & Logical Negation [#2-supported-filter-operators--logical-negation]

The compiler supports a comprehensive catalog of relational, pattern-matching, range, and boolean operators:

| Operator Category         | Operators                                                                 | AST Transformation / Behavior                                                                           |
| ------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **Equality & Comparison** | `eq`, `ne`, `gt`, `lt`, `ge`, `le`                                        | Standard binary SQL comparisons (`=`, `!=`, `>`, `<`, `>=`, `<=`) with auto-coercion.                   |
| **Pattern Matching**      | `like`, `ilike`, `contains`, `startswith`, `endswith`                     | Escapes wildcards (`%`, `_`) and compiles to `.like()` or `.ilike()`.                                   |
| **Inverted Matching**     | `not_like`, `not_ilike`, `not_contains`, `not_startswith`, `not_endswith` | Wraps escaped pattern-matching expressions inside `not_()`.                                             |
| **Range & Lists**         | `between`, `not_between`, `in`, `not_in`                                  | Coerces lists of values and compiles to `.between()` / `not_(.between())` or `.in_()` / `not_(.in_())`. |
| **Nullability**           | `is_null`, `is_not_null`                                                  | Compiles to `col.is_(None)` or `col.isnot(None)` (accepts `true` or `null`).                            |
| **Logical Grouping**      | `and`, `or`                                                               | Evaluates sub-filters in `items` recursively and wraps in `and_(*sub_exprs)` or `or_(*sub_exprs)`.      |
| **Logical Negation**      | `not`                                                                     | Negates a single field (`not_(col == val)`) or negates an entire sub-block (`not_(and_(*sub_exprs))`).  |

```python
# Example: Nested logical NOT compilation in search.py
if f.op == "not":
    if f.items:
        sub_exprs = [self._get_operator_expression(item) for item in f.items if item is not None]
        return not_(and_(*sub_exprs)) if sub_exprs else None
    elif f.field:
        expr = self._build_expression_for_field(self.model, f.field, "eq", f.value)
        return not_(expr) if expr is not None else None
```

***

## 3. Security: Column & Relation Level Access Control [#3-security-column--relation-level-access-control]

The defining security feature of `SearchEngine&#x60; is its seamless integration with &#x2A;*`ZContext`**.

Before compiling any comparison clause, the engine invokes `_validate_filter_field`. This recursively resolves dot-paths (e.g., `assignee.profile.salary`) and validates them against the active user's `ctx.restricted_fields`:

```python
# Internal security validation in search.py
if self._is_path_restricted(current_path, restricted):
    raise ForbiddenError(f"Filtering by restricted path '{current_path}' is forbidden.")
```

<Callout type="info" emoji="🛡️">
  **Protection Against Data Inference:**
  If a user lacks permission to view `tasks.salary`, and attempts to deduce salaries by sending:
  `{ "field": "salary", "op": "gt", "value": 80000 }`

  The engine blocks the query before it hits the database and raises a `ForbiddenError`. Users cannot probe or infer values for columns they are unauthorized to access.
</Callout>

***

## 4. Security: Denial of Service (DoS) Defense & Bounds [#4-security-denial-of-service-dos-defense--bounds]

Malicious clients can craft massive, deeply nested `AND`/`OR` trees or infinite recursive relation joins to exhaust server memory and CPU cycles.

ZCore enforces strict, hierarchical boundaries during the validation sweep:

* **Search Depth Hierarchy:** Filter nesting and relation eager-loading depth (`include`) are resolved hierarchically:

  > **model.**max\_search\_depth**** $\longrightarrow$ **settings.SEARCH\_MAX\_DEPTH** $\longrightarrow$ &#x2A;*Default (3)**

  Exceeding this threshold raises a `ValidationError("Search query filter structure is too complex.")`.
* **Automatic Page Size Clamping:** The `size` parameter in `SearchRequest` is validated via Pydantic V2 `model_validator(mode="after")`. If omitted, it defaults to `settings.PAGINATION_DEFAULT_SIZE` (default: 20). If specified, it is strictly clamped between `1` and `settings.PAGINATION_MAX_SIZE` (default: 100), preventing massive unbounded database dumps.

***

## 5. Selective Projection & Custom Options (`fields` & `options`) [#5-selective-projection--custom-options-fields--options]

In addition to dynamic compilation, the `search()` method in both `BaseRepository` and `BaseService` accepts explicit column projection and SQLAlchemy options:

```python
# Selective loading and custom SQLAlchemy options
results = await task_repo.search(
    search_request,
    fields=[Task.id, Task.title],           # Applies load_only(*fields)
    options=[selectinload(Task.assignee)],   # Applies custom executable options
    pagination=CursorParams(size=20)
)
```

This ensures that endpoints like `/lookup` can load only minimal columns while executing dynamic search and relation joins safely.

***

## 6. Intelligent Eager-Loading Optimization [#6-intelligent-eager-loading-optimization]

The `include` parameter allows clients to request relational graphs dynamically without triggering N+1 database queries. The engine inspects SQLAlchemy model mappers to choose the optimal loader strategy:

* **To-Many Relationships (`rel.uselist == True`):*&#x2A; Automatically compiled with &#x2A;*`selectinload`** to prevent Cartesian product row duplication.
* **To-One Relationships (`rel.uselist == False`):*&#x2A; Automatically compiled with &#x2A;*`joinedload`** for single-query JOIN efficiency.

***

## 7. Relational Dot-Path Resolution & Type Safety [#7-relational-dot-path-resolution--type-safety]

When filtering across foreign relations (e.g., `{ "field": "author.email", "op": "eq", "value": "test@core.com" }`), the engine resolves the target model dynamically:

* For **To-One** relations: Compiles to `Model.author.has(Author.email == "test@core.com")`.
* For **To-Many** relations: Compiles to `Model.comments.any(Comment.status == "approved")`.

<Callout type="info" emoji="⚡">
  **Wildcard Sanitization & Automatic Type Casting:**

  * All text operators (`ilike`, `contains`, `startswith`, `endswith` and their `not_*` counterparts) automatically escape SQL wildcard characters (`%`, `_`, `\`) to prevent query distortion or wildcard injection attacks.
  * When applying text-matching operators to non-string columns (e.g., searching numeric IDs or UUIDs), the engine automatically applies `cast(col, String)` to guarantee safe and valid SQL execution.
</Callout>


# Security & Authentication Architecture (/docs/core-concepts/security)





Security in ZCore is not an afterthought; it is integrated directly into the architectural core. The framework provides modern cryptographic primitives, fail-fast production safeguards, and an automated authentication/authorization pipeline.

***

## 1. Cryptographic Services (Argon2id & JWT) [#1-cryptographic-services-argon2id--jwt]

### Memory-Hard Password Hashing [#memory-hard-password-hashing]

ZCore uses **Argon2id** (via `argon2-cffi`), the winner of the Password Hashing Competition. Unlike legacy algorithms like bcrypt or PBKDF2, Argon2id is memory-hard, providing strong resistance against GPU and ASIC cracking rigs.

ZCore exposes dynamic parameter tuning directly via the `Settings` class:

* `ARGON2_MEMORY_COST`: Memory capacity allocated per hash calculation (Default: `65536` KB / 64 MB).
* `ARGON2_TIME_COST`: Number of hashing iterations (Default: `3`).
* `ARGON2_PARALLELISM`: Parallel processing threads (Default: `4`).

```python
from zcore.security import Security

# Generate Argon2id hash
hashed_pwd = Security.hash_password("SuperSecretPassword123")

# Verify plain password against stored hash
is_valid = Security.verify_password("SuperSecretPassword123", hashed_pwd)
```

### JWT Management & Asymmetric Key Support [#jwt-management--asymmetric-key-support]

`Security` handles JSON Web Token creation, signature verification, and expiration assertions. It supports both symmetric (`SECRET_KEY`) and enterprise asymmetric key pairs (`JWT_PRIVATE_KEY` and `JWT_PUBLIC_KEY` for algorithms like RS256).

***

## 2. Fail-Fast Production Secret Assertion [#2-fail-fast-production-secret-assertion]

A common deployment disaster in web engineering is deploying an application to production while forgetting to change the default secret key.

ZCore implements an active **Fail-Fast Startup Assertion** in `Security._get_signing_keys()`:

```python
# Internal fail-fast validation
if is_prod and is_fallback:
    raise RuntimeError(
        "FATAL SECURITY VIOLATION: You are running in PRODUCTION environment "
        "using the insecure default fallback SECRET_KEY. Application startup aborted."
    )
```

If `settings.DEBUG` is `False` (Production) and `settings.SECRET_KEY` matches the default insecure fallback, the application **aborts startup immediately**.

***

## 3. The `BaseAuth[T]` Template Pipeline [#3-the-baseautht-template-pipeline]

ZCore does not couple your application to a rigid user table. Instead, &#x2A;*`BaseAuth[T]`** is a Generic template class that coordinates token extraction, cryptographic verification, caching, and context binding:

<Mermaid
  chart="graph TB
Req[Incoming HTTP Request with Bearer Token] --> Extract[1. Extract token via OAuth2PasswordBearer]
Extract --> Decode[2. Security.decode_jwt validates signature & exp]
Decode --> CacheCheck{3. Check BaseCache user:identity}
CacheCheck -- Hit --> ActiveCheck[4. Validate is_active == True]
CacheCheck -- Miss --> Fetch[5. Execute self.fetch_user identity]
Fetch --> SetCache[Store in BaseCache TTL from AUTH_CACHE_TTL]
SetCache --> ActiveCheck
ActiveCheck --> Bind[6. Bind attributes to ZContext ctx.user_id, restricted_fields]
Bind --> Done[Proceed to Route Handler]"
/>

### Dynamic User Cache Lifespan (`AUTH_CACHE_TTL`) [#dynamic-user-cache-lifespan-auth_cache_ttl]

`BaseAuth` caches resolved user sessions to eliminate redundant database queries on every authenticated request. The cache expiration time is dynamically resolved from `settings.AUTH_CACHE_TTL` (default: **300 seconds** / 5 minutes) or can be passed explicitly via `cache_ttl` in the constructor.

### Custom Authentication Implementation [#custom-authentication-implementation]

`UserProtocol` models user characteristics flexibly: `id` is typed as `Any`, seamlessly supporting auto-incrementing integers, UUIDs, or external strings:

```python
# auth.py
from typing import Any
from pydantic import BaseModel
from zcore import BaseAuth

class AppUser(BaseModel):
    id: Any  # Supports UUID, int, or str
    is_active: bool = True
    is_superuser: bool = False
    scopes: list[str] = []
    all_restricted_fields: list[str] = []

class CustomAuth(BaseAuth[AppUser]):
    # cache_ttl is optional; falls back to settings.AUTH_CACHE_TTL (300s)
    def __init__(self, auto_error: bool = True):
        super().__init__(user_schema=AppUser, cache_prefix="auth", auto_error=auto_error)

    async def fetch_user(self, identity: str) -> AppUser | None:
        # Resolve user from database repository
        db_user = await user_repo.get_by_username(identity)
        return AppUser.model_validate(db_user) if db_user else None
```

### Optional Authentication & Guest Support (`auto_error=False`) [#optional-authentication--guest-support-auto_errorfalse]

For endpoints that support both authenticated users and anonymous guests (e.g., public catalogs, guest checkouts):

```python
# main.py
from zcore.security import get_current_user_stub, get_optional_user_stub
from auth import CustomAuth

# Standard strict authentication (raises 401 on missing/invalid token)
strict_auth = CustomAuth(auto_error=True)
app.dependency_overrides[get_current_user_stub] = strict_auth

# Optional authentication (returns None if unauthenticated)
optional_auth = CustomAuth(auto_error=False)
app.dependency_overrides[get_optional_user_stub] = optional_auth
```

When `auto_error=False`, missing tokens, expired tokens, or inactive accounts return `None` gracefully instead of raising an `AuthError` (401), allowing downstream routes to serve unauthenticated requests while letting `Zchema` prune fields defined in `__private__`.

***

## 4. Scope-Based Authorization (`HasScopes`) [#4-scope-based-authorization-hasscopes]

ZCore employs an OAuth2/OIDC compatible scope authorization model via the &#x2A;*`HasScopes`** permission class:

* **Scope Resolution:** Resolves user scopes dynamically from `ctx.get("scopes")` or the `UserProtocol` instance.
* **Superuser Bypass:** If `allow_superuser=True` (default), users with `is_superuser = True` bypass scope assertions entirely, simplifying administrative workflows.
* **Standardized Status Codes:**
  * Unauthenticated or inactive user $\rightarrow$ `401 Unauthorized`.
  * Insufficient scopes $\rightarrow$ `403 Forbidden`.

```python
from fastapi import APIRouter, Depends
from zcore.security import HasScopes

router = APIRouter()

@router.delete(
    "/finance/invoices/{id}",
    dependencies=[Depends(HasScopes("invoices:delete", "finance:admin"))]
)
async def delete_invoice(id: str):
    return {"status": "deleted"}
```

<Callout type="info" emoji="👑">
  **Zero-Boilerplate Routing:** When using `BaseRouter`, `HasScopes` dependencies are automatically calculated and injected for every CRUD/Lookup endpoint based on `model.actions()`.
</Callout>


# File Storage Security Architecture (/docs/core-concepts/storage)





File upload endpoints are among the highest-risk attack vectors in web applications. ZCore's &#x2A;*`LocalStorageProvider`** and storage validator suite implement deep defense-in-depth mechanisms to protect host servers against remote code execution (RCE), directory traversal, and resource exhaustion attacks.

***

## 1. Path Traversal & Arbitrary File Deletion Defense [#1-path-traversal--arbitrary-file-deletion-defense]

Attackers frequently craft malicious filenames or folder parameters (e.g., `../../etc/shadow` or `..\..\Windows\System32`) to escape the upload root directory.

ZCore mitigates this using multi-stage path sanitization:

1. **Path Normalization & Key Extraction:** Normalizes slashes and strips path prefixes via `_extract_key` to produce isolated POSIX storage keys.
2. **Sandbox Boundary Assertion:** Resolves system symlinks and relative path operators (`..`) and strictly verifies that the resulting destination resides within the root upload path:

```python
# Internal security validation in local.py
normalized_folder = folder.strip("/\\").replace("\\", "/")
ext = StdPath(filename).suffix.lower()
secure_filename = f"{uuid.uuid4().hex}{ext}"
storage_key = f"{normalized_folder}/{secure_filename}" if normalized_folder else secure_filename

physical_path = self._key_to_path(storage_key)
if physical_path is None:
    raise AppException("Path traversal attempt detected")
```

<Callout type="warn" emoji="🛡️">
  **Arbitrary Deletion Protection:**
  This same boundary verification executes inside `storage.delete(file_path_or_url)`. Incoming web URLs or filesystem paths are resolved via `_resolve_path`, preventing attackers from exploiting delete endpoints to remove arbitrary system configuration files.
</Callout>

***

## 2. Magic Byte Verification & Script Firewall [#2-magic-byte-verification--script-firewall]

Relying purely on file extensions (`.png`, `.pdf`) or client-provided `Content-Type` headers is completely insecure, as attackers can disguise PHP web shells or executable binaries as images.

ZCore's &#x2A;*`SafeMimeTypeValidator`** reads the first 8192 header bytes to evaluate actual file signatures and detect stored XSS / script vectors:

<Mermaid
  chart="graph TB
File[Uploaded Binary Stream] --> Read[Read First 8192 Header Bytes]
Read --> HeaderCheck{Blocked Binary Header? MZ, #!/, or \x7fELF}
HeaderCheck -- Yes --> CriticalBin[Raise ValidationError: Executable Binary Forbidden]
HeaderCheck -- No --> ScriptCheck{Contains Active Script/XSS Pattern?}
ScriptCheck -- Yes --> CriticalScript[Raise ValidationError: Scripts & Injections Forbidden]
ScriptCheck -- No --> Magic[Compare against SIGNATURES Dictionary]
Magic -- Match Found --> Allowed{Is MIME in allowed_mimes?}
Allowed -- Yes --> Save[Allow Upload to Disk]
Allowed -- No --> Reject[Raise ValidationError: MIME Not Allowed]"
/>

### Executable & Stored XSS Injection Firewall [#executable--stored-xss-injection-firewall]

Even before checking legitimate magic bytes, `SafeMimeTypeValidator` inspects the initial byte sample against binary headers and active script injection patterns:

* **Executable Binary Headers:** Windows PE (`MZ`), Unix Shebang (`#!/`), and Linux ELF (`\x7fELF`) binaries.
* **PHP Script Blocks:** `<?php`
* **HTML/JavaScript Injections:** `<script`, `javascript:`, `vbscript:`, `data:text/html`, `<!doctype html`, `<html`
* **Embedded Vectors & Handlers:** `<iframe>`, `<object>`, `<embed>`, `onload=`, `onerror=`, `onclick=`, `xlink:href=javascript:`

If any of these signatures are present, ZCore immediately logs a critical security alert and rejects the request.

***

## 3. Denial of Service (DoS) & Memory Exhaustion Mitigation [#3-denial-of-service-dos--memory-exhaustion-mitigation]

Uploading multi-gigabyte files can saturate disk space and crash server memory. &#x2A;*`MaxFileSizeValidator`** calculates byte capacities safely without buffering entire payloads into RAM:

1. **Native Inspection:** Checks Starlette's `file.size` attribute if available.
2. **Safe Stream Seeking:** For chunked multipart streams, it seeks to the end of the byte stream (`file.file.seek(0, 2)`), measures the stream position (`file.file.tell()`), and immediately rewinds to the beginning (`file.file.seek(0)`).
3. If the computed size exceeds `max_size_bytes`, the upload is rejected before asynchronous disk writes begin.

***

## 4. Collision-Resistant Randomized Filenames [#4-collision-resistant-randomized-filenames]

To prevent attackers from overwriting existing files or guessing storage locations, `LocalStorageProvider` ignores original client filenames when storing on disk.

It generates an isolated, 32-character hexadecimal UUID prefix paired with the normalized extension:

```python
# Generates secure filename: "3f9a8b1c4e2d7a9f8c1b2a3d4e5f6a7b.png"
ext = StdPath(filename).suffix.lower()
secure_filename = f"{uuid.uuid4().hex}{ext}"
```

<Callout type="info" emoji="⚡">
  **Asynchronous Disk Streaming:**
  Once validated, files are written asynchronously using `aiofiles` in 1 MB chunks, keeping the event loop responsive during concurrent uploads, and returning normalized web URLs prefixed with `STORAGE_URL_PREFIX`.
</Callout>


# Testing Infrastructure (ZTestClient) (/docs/core-concepts/testing)





Testing multi-layered enterprise applications is notoriously difficult because of shared mutable state (database connections, IoC container singletons, context variables). ZCore solves this with &#x2A;*`ZTestClient`*&#x2A; and a suite of composable &#x2A;*`ZTestFixture`** orchestrators.

***

## 1. The Fixture Composition Pipeline [#1-the-fixture-composition-pipeline]

When you open an `async with ZTestClient(...)` context, ZCore orchestrates a composite pipeline of isolated fixtures:

<Mermaid
  chart="graph TB
Client[ZTestClient Entry] --> Sand[1. ContainerSandbox Snapshot]
Sand --> EvtSand[2. EventDispatcherSandbox Snapshot]
EvtSand --> Life[3. AppLifespan Startup Hooks]
Life --> DB[4. DatabaseRollback Open Savepoint]
DB --> User[5. UserContext & DependencyOverride]
User --> Exec[Execute Async Test Logic]
Exec --> CleanDB[Rollback DB Transaction]
CleanDB --> CleanLife[AppLifespan Shutdown Hooks]
CleanLife --> CleanEvt[Restore Event Subscribers]
CleanEvt --> CleanSand[Restore Container Snapshot]
CleanSand --> Done[Test Complete & Clean]"
/>

***

## 2. IoC Container Sandboxing (`ContainerSandbox`) [#2-ioc-container-sandboxing-containersandbox]

During integration testing, you may override dependencies or register mock services in the container. If test A mutates the container, test B might fail unexpectedly.

`ContainerSandbox` captures a complete snapshot of `container._singletons`, `_scoped_definitions`, and `_factories` during `setUp()`. During `tearDown()`, it restores the exact snapshot, guaranteeing 100% test isolation.

```python
# Internal ContainerSandbox mechanics
async def setUp(self):
    self._singletons = dict(container._singletons)
    self._scoped = dict(container._scoped_definitions)
    self._factories = dict(container._factories)

async def tearDown(self):
    container._singletons = self._singletons
    container._scoped_definitions = self._scoped
    container._factories = self._factories
```

***

## 3. Event Bus Isolation (`EventDispatcherSandbox`) [#3-event-bus-isolation-eventdispatchersandbox]

Domain-driven systems frequently attach ephemeral or test-specific event listeners. Without rigorous sandboxing, event subscriptions registered in one test case bleed into subsequent executions.

`EventDispatcherSandbox` captures an isolated dictionary snapshot of all registered event callbacks in `EventDispatcher._subscribers`. Upon test completion, it clears active subscribers and restores the pristine pre-test subscriber registry.

***

## 4. Lightning-Fast Database Rollbacks (`DatabaseRollback`) [#4-lightning-fast-database-rollbacks-databaserollback]

Dropping tables, re-running database migrations, or truncating rows between test runs introduces severe latency.

<Callout type="info" emoji="⚡">
  **The Savepoint Strategy:**

  1. `DatabaseRollback` opens a dedicated connection on the async engine and begins a root transaction.
  2. It initializes an `AsyncSession` using `join_transaction_mode="create_savepoint"`.
  3. It overrides `db_manager.session` and registers this session as the active request-scoped database dependency in the IoC container.
  4. All test inserts, updates, and repository operations execute inside this savepoint.
  5. Upon test exit, it executes `transaction.rollback()`. The database is instantly reverted to its pre-test state in milliseconds.
</Callout>

### Schema Provisioning with `setup_test_database` [#schema-provisioning-with-setup_test_database]

Before running tests that interact with transactional rollbacks, the database tables themselves must exist. ZCore provides `setup_test_database()` to synchronously create or refresh your schema:

```python
# conftest.py
import pytest
from zcore.testing import setup_test_database

@pytest.fixture(scope="session", autouse=True)
def initialize_test_database():
    # Safely creates all tables across existing event loops without async boilerplate
    setup_test_database(drop_first=True)
```

`setup_test_database()` automatically detects whether an event loop is already active in the current thread (e.g. under pytest-asyncio) and safely dispatches execution via a background worker thread, eliminating loop conflicts.

***

## 5. Context & User Dependency Overrides [#5-context--user-dependency-overrides]

Testing role-based endpoints in standard FastAPI requires manually manipulating `app.dependency_overrides` and generating dummy JWT tokens.

`ZTestClient` coordinates this automatically when `user_id` is passed:

1. **`UserContext`:** Injects `user_id`, `scopes`, `is_superuser`, and `extra_context` directly into the `ZContext` store for the active async coroutine tree.
2. **`DependencyOverride`:** Replaces `get_current_user_stub` and `get_optional_user_stub` (along with any targets in `user_dependency`) with an authentic Pydantic user instance (when `user_model` is specified) or an internal `GenericMockUser` implementing `UserProtocol`.

```python
# Seamless user mocking without JWT logic
async with ZTestClient(
    app=app,
    user_id=uuid.uuid4(),
    user_model=AppUser,
    scopes=["tasks:delete", "tasks:create"],
    extra_context={"restricted_fields": ["tasks.view.salary"]}
) as client:
    response = await client.delete(f"/tasks/{task_id}")
    assert response.status_code == 200
```

***

## 6. Application Lifespan Execution (`AppLifespan`) [#6-application-lifespan-execution-applifespan]

`ZTestClient` automatically invokes FastAPI's `router.lifespan_context`. This guarantees that:

* Kernel plugins execute their `before_startup` and `on_startup` hooks.
* Global singletons (like `EventDispatcher` and cache workers) are active during tests.
* Upon test completion, `on_shutdown` hooks execute in reverse order to release connection pools cleanly.


# Unit of Work & Deferred Events (/docs/core-concepts/uow)





In distributed applications, one of the most common sources of data corruption and phantom side-effects is dispatching notifications or domain events *before&#x2A; a database transaction is guaranteed to commit. ZCore's &#x2A;*`UnitOfWork`** (UoW) eliminates the "Dual-Write" problem by buffering events and coordinating atomic multi-repository boundaries.

***

## 1. The Atomic Transaction Boundary [#1-the-atomic-transaction-boundary]

`UnitOfWork` is an asynchronous context manager. Upon entering the context (`__aenter__`), it injects a state flag directly into the active SQLAlchemy session metadata:

```python
# Internal lifecycle flag set by UnitOfWork
self.session.info["uow_managed"] = True
```

This flag signals `BaseService` instances to **delegate commit authority**. When any service method (`create`, `update`, `delete`) invokes its internal `_safe_commit()`, it inspects `session.info["uow_managed"]`. Detecting an active UoW, the service skips its individual commit, allowing multiple repositories to participate in a single atomic transaction.

If any exception is raised inside the `async with` block, `UnitOfWork` catches the error, calls `session.rollback()`, and purges the pending event queue.

<Mermaid
  chart="graph TB
Start[async with UnitOfWork] --> Flag[Set session uow_managed = True]
Flag --> Repos[Execute Multiple Repository Mutations]
Repos --> Buffer[uow.register_event Buffered in Memory]
Buffer --> Depth{Outermost Root Scope?}
Depth -- No: depth > 1 --> Flush[session.flush: Sync DB Constraints]
Depth -- Yes: depth == 0 --> Commit{Physical DB Commit Succeeds?}
Commit -- Yes --> Dispatch[Dispatch Pending Events Concurrently]
Commit -- No / Exception --> Rollback[session.rollback & Purge Events]"
/>

***

## 2. Nested & Re-entrant Coordination (Depth Tracking) [#2-nested--re-entrant-coordination-depth-tracking]

In modular monolithic architectures, domain services frequently invoke each other (e.g., `OrderService` calling `InventoryService` and `BillingService`). If each service declares its own `UnitOfWork` boundary, a naive implementation would prematurely commit when the inner service finishes.

ZCore solves this with **Depth-Aware Re-entrancy**:

1. **Depth Counter (`uow_depth`):** `UnitOfWork.__aenter__` increments `session.info["uow_depth"]`.
2. **Nested Flushes:** When an inner scope (`depth > 1`) exits, `uow.commit()` executes `await session.flush()` instead of a physical commit. This assigns database-generated IDs, validates foreign key constraints, and synchronizes session state without ending the physical database transaction.
3. **Shared Event Buffer (`uow_events`):** Domain events registered at any nesting depth are buffered in a shared list at `session.info["uow_events"]`.
4. **Root Commit & Atomic Dispatch:** Only when the outermost context manager (`depth == 0`) concludes does ZCore execute the physical database commit and dispatch all accumulated domain events concurrently via `EventDispatcher`.
5. **Chain Rollback:** If an exception is raised at *any* depth, the active depth resets to `0`, `uow_managed` is cleared, all pending events are discarded, and the entire multi-service transaction is rolled back immediately.

***

## 3. Deferred Event Dispatching (Solving the Dual-Write Problem) [#3-deferred-event-dispatching-solving-the-dual-write-problem]

Standard event dispatchers trigger listener callbacks immediately when `dispatch()` is called. In transactional systems, this creates severe consistency bugs:

<Callout type="warn" emoji="🚨">
  **The Premature Event Trap:**

  1. `db.flush()` (Order inserted into session)
  2. `dispatcher.dispatch("order.completed")` (Sends order confirmation email)
  3. `db.commit()` (Fails due to a serialization or unique constraint error!)

  **The Bug:** The database transaction rolled back (no order exists), but the customer already received a confirmation email!
</Callout>

### The ZCore Solution [#the-zcore-solution]

Inside a `UnitOfWork`, calling `uow.register_event("order.completed", payload)` does **not** execute listeners immediately. Instead, it buffers the event tuple in the session's pending events store:

```python
async with UnitOfWork(self.repository.db, self.dispatcher) as uow:
    order = await self.order_repo.create(order_data)
    await self.inventory_repo.decrement_stock(product_id, quantity)

    # Buffered safely: Not dispatched yet!
    uow.register_event("order.completed", {"order_id": str(order.id)})
    
# Dispatches ONLY after the physical database commit succeeds on root exit!
```

Only **after** `await self.session.commit()` completes successfully does the UoW pop each event from `_pending_events` and invoke `self.dispatcher.dispatch(...)`. If the commit fails, all buffered events are permanently discarded.

This provides absolute transactional consistency: &#x2A;*If a domain event fires, the database state is guaranteed to be committed.**

***

## 4. Integration with `BaseRepository` [#4-integration-with-baserepository]

Because all repository instances resolve the active, request-scoped `AsyncSession` managed by `ScopedDependencyMiddleware`, they automatically participate in the `UnitOfWork` lifecycle without any custom configuration. You can orchestrate updates across multiple independent domain repositories within a single atomic UoW block.

<Callout type="info" emoji="🔒">
  **Handler Failure Isolation:**
  During post-commit event dispatching, if an individual async listener raises an unhandled exception (e.g., an external webhook timeout), `UnitOfWork` catches and logs the failure with full traceback diagnostics, ensuring remaining event handlers continue to execute without interrupting the request lifecycle.
</Callout>


# Zchema & Context Shielding (/docs/core-concepts/zchema)





Maintaining distinct Pydantic models for different user roles (e.g., `TaskCreatePublic`, `TaskCreateAdmin`, `TaskResponseUser`, `TaskResponseAdmin&#x60;) leads to massive code duplication and violates the DRY principle. ZCore solves this with &#x2A;*`Zchema`**, an intelligent schema abstraction that intercepts Pydantic V2 core compilation and execution hooks.

***

## 1. The Triple Pruning Pipeline [#1-the-triple-pruning-pipeline]

`Zchema` enforces security boundaries across all three phases of the HTTP data lifecycle:

<Mermaid
  chart="graph TB
subgraph 1. Inbound Request
Input[Incoming HTTP JSON] --> VBefore[@model_validator before]
VBefore --> PruneIn[Drop Restricted Fields: Mass Assignment Safe]
PruneIn --> Validated[Validated Pydantic Instance]
end

subgraph 2. Outbound Response
Validated --> Wrap[@model_serializer wrap]
Wrap --> PruneOut[Prune Restricted Keys Recursively]
PruneOut --> JSON[Filtered Response JSON]
end

subgraph 3. Documentation
Swagger[GET /endpoint?schema=true] --> GetSchema[__get_pydantic_json_schema__]
GetSchema --> PruneDoc[Remove from properties & required]
PruneDoc --> SafeSchema[Masked OpenAPI Specification]
end"
/>

1. **Input Validation (Mass Assignment Prevention):**
   By intercepting `@model_validator(mode="before")`, `Zchema` inspects incoming JSON payloads. If an unauthorized user attempts to inject restricted fields (e.g., submitting `is_superuser: true` or `salary: 100000`), the forbidden fields are silently stripped before Pydantic initializes the model.
2. **Output Serialization (Data Leakage Prevention):**
   By wrapping `@model_serializer(mode="wrap")`, `Zchema` intercepts the serialized dictionary before it is rendered to JSON. It recursively traverses nested dictionaries and lists to purge any restricted attributes.
3. **JSON Schema Generation (OpenAPI & Dynamic Forms):**
   By overriding `__get_pydantic_json_schema__`, `Zchema` dynamically alters the generated Draft-7 JSON Schema. Forbidden fields are stripped from both the `properties` definition and the `required` validation array.

### Guest Masking (`__private__`) & Performance Early-Exit [#guest-masking-__private__--performance-early-exit]

* **Unauthenticated Contexts (`__private__`):** In addition to active user permissions, `Zchema` allows declaring sensitive attributes that should never appear for guests:
  ```python
  class ProductResponse(Zchema):
      __model__ = "products"
      __private__ = {"wholesale_cost", "margin"}  # Hidden when ctx.user_id is None
  ```
  When `ctx.user_id` is missing, fields listed in `__private__` are automatically merged into the relative restriction paths across validation, serialization, and schema queries.
* **Zero-Overhead Serialization:** `Zchema` implements early-exit guards. If a request context contains no active restrictions (or if serialized payloads evaluate to non-dictionary primitives), data pruning bypasses recursive traversal entirely, serializing clean payloads with native Pydantic V2 speed.

***

## 2. Context-Aware Path Resolution [#2-context-aware-path-resolution]

`Zchema` computes relative restriction paths by cross-referencing `ctx.restricted_fields` against the schema's `__model__` attribute:

```python
# schemas.py
from zcore import Zchema

class TaskResponse(Zchema):
    __model__ = "tasks"  # Binds this schema domain
    
    id: uuid.UUID
    title: str
    salary: float
    assignee: AssigneeInfo | None = None
```

### Supported Path Resolution Syntax [#supported-path-resolution-syntax]

* **Action-Scoped Restrictions:** If `ctx.restricted_fields` contains `"tasks.view.salary"`, `Zchema` strips `salary` strictly on `view` (GET) operations. Standard actions recognized include `listview`, `view`, `create`, `update`, `delete`, and `lookup`.
* **Global Domain Restrictions:** If `restricted_fields` contains `"tasks.salary"`, `Zchema` strips `salary` across all actions (create, update, view).
* **Recursive Nested Restrictions:** If `restricted_fields` contains `"tasks.view.assignee.email"`, `Zchema` traverses the nested `assignee` dictionary/list and prunes only the `email` key.
* **Full-Model Masking (Wildcard):** If `restricted_fields` contains `"tasks.view"` or `"tasks"`, `Zchema` prunes the entire model (`*`), returning an empty representation.

<Callout type="info" emoji="🛣️">
  **Action Context:** `ZCoreAPIRoute` automatically populates `ctx.set("action", "view" | "create" | "update" | "delete")` based on the active HTTP method or custom OpenAPI route metadata.
</Callout>

***

## 3. `ZCoreAPIRoute` Integration & CDN Safety [#3-zcoreapiroute-integration--cdn-safety]

To orchestrate `Zchema&#x60; seamlessly with FastAPI, ZCore provides the specialized &#x2A;*`ZCoreAPIRoute`**:

### Fast Dynamic Schema Queries (`?schema=true`) [#fast-dynamic-schema-queries-schematrue]

When a client requests `GET /tasks?schema=true`:

1. `ZCoreAPIRoute` intercepts the connection before route handlers or database sessions are invoked.
2. It executes `target_model.model_json_schema()`, triggering `Zchema`'s masked schema generation.
3. It returns the pruned JSON Schema wrapped in `ResponseWrapper` directly, bypassing the database entirely.

### Automatic HTTP Cache Invalidation (`Vary` Header) [#automatic-http-cache-invalidation-vary-header]

If an endpoint returns data where restricted fields have been pruned, `ZCoreAPIRoute` automatically appends:

```http
Vary: Authorization, Cookie
```

This prevents downstream CDNs, reverse proxies, and browser caches from serving masked responses to high-privilege administrative users.


# Step 1 - Installation & Environment (/docs/quick-learn/step-1)





In this first step, we will set up the foundation of our project. ZCore is designed to be zero-config out of the box, with automated virtual environment initialization and cryptographically secure secret generation.

<Steps>
  <Step>
    ### Install the Framework [#install-the-framework]

    Install ZCore with all its standard dependencies (FastAPI, SQLAlchemy, Pydantic, Questionary, Rich, etc.). The `[all]` extra ensures you get the complete toolkit.

    ```bash
    pip install fastapi-zcore-framework[all]
    ```
  </Step>

  <Step>
    ### Scaffold the Project with the CLI [#scaffold-the-project-with-the-cli]

    Use the `zc init` command to create a project structure. The CLI will interactively ask for your database preference (SQLite, PostgreSQL, or MySQL) and package manager (`uv` or `pip`).

    ```bash
    zc init task_manager && cd task_manager
    ```

    This command automatically:

    * Generates a pre-configured `.env` file with a freshly generated 64-character `SECRET_KEY`.
    * Creates `main.py`, `requirements.txt`, and `.gitignore`.
    * Initializes an isolated virtual environment (`.venv`) and installs project dependencies if selected.

    <Files>
      <Folder name="task_manager">
        <File name="main.py" />

        <File name=".env" />

        <File name="requirements.txt" />

        <File name=".gitignore" />

        <File name="zcore_dev.db" />
      </Folder>
    </Files>
  </Step>

  <Step>
    ### Secret Keys & Environment Management [#secret-keys--environment-management]

    `zc init` already populates `.env` with a cryptographically strong `SECRET_KEY`. However, if you need to generate a new key or rotate credentials later, run:

    ```bash
    zc gensecret
    ```

    To generate a clean `.env.example` schema from your Pydantic settings at any time:

    ```bash
    zc genenv -o .env.example -f
    ```
  </Step>

  <Step>
    ### Understand the Settings Class [#understand-the-settings-class]

    Open `main.py`. You will see that ZCore imports `settings` from `zcore`. This `settings` object is a `SettingsProxy` that reads from your `.env` file using Pydantic V2 Settings.

    ```python
    # main.py (excerpt)
    from zcore import settings

    # ZCore reads DATABASE_URL, SECRET_KEY, DEBUG, etc., automatically
    print(settings.PROJECT_NAME)
    print(settings.DATABASE.url)
    ```

    In addition to core connectivity, all framework runtime boundaries are tunable via environment variables with sensible defaults:

    ```bash
    # .env (Tunable framework parameters)
    PAGINATION_DEFAULT_SIZE=20
    PAGINATION_MAX_SIZE=100
    SEARCH_MAX_DEPTH=3
    AUTH_CACHE_TTL=300
    CACHE_DEFAULT_TTL=3600
    CACHE_LOCAL_MAXSIZE=1000
    CACHE_EVICTION_INTERVAL=60
    STREAM_QUEUE_MAXSIZE=100
    ```

    <Callout type="info" emoji="💡">
      **Deep Dive:** The `settings` object is a Proxy. This means importing it at the top of your files is completely safe and doesn't trigger premature initialization of the Dependency Injection container. Values are resolved lazily when accessed.
    </Callout>
  </Step>
</Steps>

Excellent! Your environment is now secure and ready. In the next step, we will examine database initialization.


# Step 10 - Testing & Expected Output (/docs/quick-learn/step-10)





Testing architectural layers can be tricky. ZCore provides `ZTestClient`, which handles Dependency Injection sandboxes, database rollbacks, and user mocking automatically.

<Steps>
  <Step>
    ### Write the Test [#write-the-test]

    Create a file `test_tasks.py` in your root directory:

    ```python
    # test_tasks.py
    import pytest
    import uuid
    from zcore.testing import ZTestClient
    from main import app

    @pytest.mark.asyncio
    async def test_create_task_masks_assignee():
        # Mock a user ID for the test
        mock_user_id = uuid.uuid4()
        
        async with ZTestClient(
            app=app, 
            user_id=mock_user_id,
            scopes=["tasks:create", "tasks:view"],
            # Explicitly load the restriction metadata into the request context sandbox
            extra_context={"restricted_fields": ["tasks.view.assignee_email"]}
        ) as client:
            # 1. Create a task with an assignee_email
            response = await client.post("/tasks", json={
                "title": "Write Docs",
                "assignee_email": "secret@example.com"
            })
            assert response.status_code == 201
            task_id = response.json()["data"]["id"]
            
            # 2. Fetch the task
            get_response = await client.get(f"/tasks/{task_id}")
            data = get_response.json()["data"]
            
            # 3. Assertions
            assert data["title"] == "WRITE DOCS" # pre_create hook worked
            assert "assignee_email" not in data   # Zchema pruned it!
    ```
  </Step>

  <Step>
    ### Run the Test [#run-the-test]

    Execute the test using pytest:

    ```bash
    pytest test_tasks.py -v
    ```
  </Step>

  <Step>
    ### Why This is Powerful [#why-this-is-powerful]

    <Callout type="success" emoji="🧪">
      **Automated Test Isolation:**

      * **DatabaseRollback:** The test inserted a task, but because `ZTestClient` uses a savepoint transaction, the database is rolled back to a clean state after the test. No cleanup needed.
      * **UserContext:** The `mock_user_id`, `scopes`, and `restricted_fields` were automatically injected into `ZContext` for the duration of the request.
      * **EventDispatcherSandbox:** Automatically snapshots and restores event subscribers so test events never leak across test cases.
      * **Typed User Models:** You can pass `user_model=AppUser` directly to `ZTestClient` to mock authentic, validated Pydantic user instances.
      * **Zero Mocking Boilerplate:** You didn't have to mock `Depends(get_db)` or override complex service layers. The `ZTestClient` orchestrated the IoC container for you.
    </Callout>

    <Callout type="info" emoji="💡">
      **Tip for Test Sessions:** Use `setup_test_database()` in a pytest session fixture to recreate clean tables before executing your test suite without writing boilerplate asyncio loop runners.
    </Callout>
  </Step>
</Steps>

**Congratulations!** You have successfully built a secure, modular, and fully tested FastAPI application using ZCore. You've seen how ZCore eliminates boilerplate without locking you into rigid patterns.

To dive deeper into specific components, explore the [How-To Guides](/docs/how-to/extend-settings/) or the [Core Concepts](/docs/core-concepts/context/).


# Step 2 - Database Engine Setup (/docs/quick-learn/step-2)





ZCore does not hide SQLAlchemy; it orchestrates it. In this step, we will initialize the `DatabaseManager` and understand how ZCore handles asynchronous connection pooling and structured query logging.

<Steps>
  <Step>
    ### Configure the Database URL [#configure-the-database-url]

    Open your `.env` file. By default, ZCore uses an asynchronous SQLite database for local development.

    ```dotenv
    # .env
    DATABASE_URL=sqlite+aiosqlite:///task_manager.db
    ```

    <Callout type="info" emoji="💡">
      For production, you would switch this to PostgreSQL (e.g., `postgresql+asyncpg://user:pass@host:port/db`). ZCore's `DatabaseManager` automatically adjusts connection pooling based on the database dialect.
    </Callout>
  </Step>

  <Step>
    ### Initialize the Engine in `main.py` [#initialize-the-engine-in-mainpy]

    Open `main.py`. The CLI generated the initialization code for you, but let's understand what it does.

    ```python
    # main.py
    from zcore import Kernel, db_manager, settings

    # Initialize Database Manager
    db_manager.init_app(config=settings.DATABASE)
    ```

    * `config`: Accepts a `DatabaseSettings` instance (like `settings.DATABASE`) or a dictionary.
    * `pool_size`: The number of connections to keep open in the pool (Default: 5).
    * `max_overflow`: How many connections to allow beyond `pool_size` under heavy load (Default: 10).
    * `pool_recycle`: Recycles connections after a specified timeout (Default: 1800s).
    * `pool_pre_ping`: Tests connections before handing them out to prevent stale connection errors (Default: True).
  </Step>

  <Step>
    ### The Query Timing Logger [#the-query-timing-logger]

    <Callout type="info" emoji="⚙️">
      **Under the hood:** ZCore attaches event listeners to the SQLAlchemy engine. Every time a query is executed, ZCore calculates the duration in milliseconds and logs it using `structlog`. It also intelligently filters out noisy system queries (like `pg_catalog` lookups) so your logs remain clean.
    </Callout>

    In `rc.2`, SQL query logging defaults to `False` to prevent console noise during development. You can enable it via `.env` or capture slow queries exclusively:

    ```dotenv
    # .env
    LOG_SQL_QUERIES=True                # Enable logging all SQL queries
    # OR keep it False and set a slow-query threshold:
    # SLOW_QUERY_THRESHOLD_MS=100.0     # Only log queries exceeding 100ms
    ```

    When query logging is enabled, your logs will look like this:

    ```log
    [info] sql_query sql=SELECT tasks.id FROM tasks params=() duration_ms=1.23
    ```
  </Step>

  <Step>
    ### Dependency Injection for Sessions [#dependency-injection-for-sessions]

    ZCore provides a ready-to-use FastAPI dependency for database sessions. You don't need to write a `get_db` generator function manually.

    ```python
    from zcore import SessionDep
    from sqlalchemy.ext.asyncio import AsyncSession

    @app.get("/health")
    async def health_check(db: SessionDep):
        # db is an AsyncSession injected by ZCore's DI container
        return {"status": "healthy"}
    ```

    `SessionDep` is an `Annotated[AsyncSession, Depends(get_db)]`. It resolves the active request-scoped session from the `IoCContainer`.
  </Step>
</Steps>

Your database engine is configured and optimized. In Step 3, we will scaffold our first domain module (the `tasks` app) using the CLI.


# Step 3 - Scaffolding Domain Modules (/docs/quick-learn/step-3)





A core philosophy of ZCore is organizing applications into decoupled, modular domains. Instead of throwing all files into a single `routers.py` or `models.py`, we structure them by business capability.

<Steps>
  <Step>
    ### Generate the Domain Module [#generate-the-domain-module]

    Run the `zc startapp` command to scaffold a `tasks` domain. The `--template` flag populates all standard layers with working boilerplate code.

    ```bash
    zc startapp tasks --template
    ```

    You can also run `zc startapp tasks` without flags for an interactive prompt where you can select specific architectural layers to generate.
  </Step>

  <Step>
    ### Examine the 7-Layer Structure [#examine-the-7-layer-structure]

    ZCore generates a self-contained directory for your domain:

    <Files>
      <Folder name="tasks">
        <File name="__init__.py" />

        <File name="models.py" />

        <File name="schemas.py" />

        <File name="repositories.py" />

        <File name="services.py" />

        <File name="routers.py" />

        <File name="plugin.py" />

        <File name="test_tasks.py" />
      </Folder>
    </Files>

    <Callout type="info" emoji="💡">
      **Separation of Concerns:** This structure cleanly decouples:

      * **Data Mapping:** `models.py` (SQLAlchemy 2.0)
      * **Validation & Projection:** `schemas.py` (Zchema / Pydantic V2)
      * **Data Access:** `repositories.py` (BaseRepository)
      * **Business Logic:** `services.py` (BaseService)
      * **HTTP Endpoints:** `routers.py` (BaseRouter)
      * **Lifecycle & Wiring:** `plugin.py` (Plugin)
      * **Integration Tests:** `test_tasks.py` (ZTestClient)
    </Callout>
  </Step>
</Steps>

Now we have a clean modular domain ready. In the next step, we will define our database model inside `tasks/models.py`.


# Step 4 - Defining Models & Permissions (/docs/quick-learn/step-4)





ZCore uses standard SQLAlchemy 2.0 declarative models. It does not force you to learn a new ORM syntax. Let's define our `Task` model.

<Steps>
  <Step>
    ### Write the Model [#write-the-model]

    Open `tasks/models.py` and define the model:

    ```python
    # tasks/models.py
    import uuid
    from sqlalchemy import String
    from sqlalchemy.orm import Mapped, mapped_column
    from zcore import Base, SoftDeleteMixin

    class Task(Base, SoftDeleteMixin):
        __tablename__ = "tasks"

        id: Mapped[uuid.UUID] = mapped_column(
            primary_key=True,
            default=uuid.uuid4,
        )
        title: Mapped[str] = mapped_column(String(255))
        is_completed: Mapped[bool] = mapped_column(default=False)
        assignee_email: Mapped[str | None] = mapped_column(String(255), nullable=True)
    ```
  </Step>

  <Step>
    ### Create an Alembic Migration [#create-an-alembic-migration]

    ZCore does not use `Base.metadata.create_all()` as a replacement for database migrations.

    For a real application, schema changes should be tracked through **Alembic migrations**. This gives you a versioned database schema that can be reproduced across development, staging, and production environments.

    If your project does not have Alembic initialized yet, initialize it from the project root:

    ```bash
    alembic init alembic
    ```

    Configure Alembic to use your database connection and make sure its `env.py` can access the application's SQLAlchemy metadata.

    Then generate a migration from the `Task` model:

    ```bash
    alembic revision --autogenerate -m "create tasks table"
    ```

    Alembic will generate a migration inside the `alembic/versions/` directory.

    Review the generated migration before applying it. Autogenerated migrations should always be treated as a starting point rather than blindly trusted.

    Finally, apply the migration:

    ```bash
    alembic upgrade head
    ```

    <Callout type="info" emoji="🗃️">
      **Why Alembic?** `Base.metadata.create_all()` is useful for quick experiments, but it does not provide versioned schema changes, upgrade paths, downgrade paths, or a reliable migration history. Alembic is the appropriate tool for managing a production database schema.

      After applying the migration, you can inspect the current database revision with:

      ```bash
      alembic current
      ```

      And inspect the complete migration history with:

      ```bash
      alembic history
      ```

      When you later modify the `Task` model, create a new migration instead of modifying the database manually:

      ```bash
      alembic revision --autogenerate -m "add task field"
      ```

      Then apply the new migration:

      ```bash
      alembic upgrade head
      ```

      This keeps your database schema synchronized with your application's models through an explicit, version-controlled migration history.
    </Callout>
  </Step>

  <Step>
    ### The Magic of `model.actions()` [#the-magic-of-modelactions]

    <Callout type="info" emoji="🔐">
      **Under the hood:** The `Base` class you inherited from provides a special classmethod called `actions()`.

      If you call `Task.actions()`, it returns an `Actions` dataclass mapping standard operations and lookups to permission strings based on your table name:

      * `CREATE`: `"tasks:create"`
      * `VIEW`: `"tasks:view"`
      * `LISTVIEW`: `"tasks:listview"`
      * `LOOKUP`: `"tasks:lookup"`
      * `UPDATE`: `"tasks:update"`
      * `DELETE`: `"tasks:delete"`

      We will use these strings later to secure our endpoints automatically.
    </Callout>
  </Step>
</Steps>

Your database schema is ready. Next, we will define the Pydantic schemas (with security rules) for this model.


# Step 5 - Schemas & Dynamic Security (Zchema) (/docs/quick-learn/step-5)





Instead of writing multiple Pydantic models for different user roles (e.g., `TaskResponsePublic`, `TaskResponseAdmin`), ZCore provides role-aware field projection through `Zchema`.

<Steps>
  <Step>
    ### Define Schemas [#define-schemas]

    Open `tasks/schemas.py` and define your creation, update, and response schemas:

    ```python
    # tasks/schemas.py
    import uuid
    from zcore import Zchema
    from pydantic import ConfigDict

    class TaskCreate(Zchema):
        __model__ = "tasks"  # Binds this schema to the Task domain
        
        title: str
        is_completed: bool = False
        assignee_email: str | None = None

    class TaskUpdate(Zchema):
        __model__ = "tasks"
        
        title: str | None = None
        is_completed: bool | None = None
        assignee_email: str | None = None

    class TaskResponse(Zchema):
        __model__ = "tasks"
        __private__ = {"assignee_email"}  # Automatically hidden for unauthenticated guests
        
        id: uuid.UUID
        title: str
        is_completed: bool
        assignee_email: str | None = None
        
        model_config = ConfigDict(from_attributes=True)
    ```

    <Callout type="info" emoji="💡">
      **Eliminating Role-Based Schema Duplication**

      `Zchema` eliminates the need to maintain duplicate schemas for different permission levels (such as `TaskCreatePublic` vs `TaskCreateAdmin` or `TaskResponseUser` vs `TaskResponseAdmin`). By dynamically sanitizing inputs (preventing Mass Assignment) and pruning response fields based on `ctx.restricted_fields`, a single schema definition per operation handles all authorization levels automatically.
    </Callout>
  </Step>

  <Step>
    ### How Zchema Works [#how-zchema-works]

    <Callout type="info" emoji="🛡️">
      **Context Shielding:** By setting `__model__ = "tasks"`, `Zchema` is now aware of its domain.

      During the request lifecycle, if the active user lacks certain permissions, their restricted fields are loaded into `ctx.restricted_fields` (e.g., `"tasks.view.assignee_email"`).

      When `TaskResponse` serializes the data, `Zchema` intercepts the process and **automatically prunes** the `assignee_email` from the JSON output. No `if` statements required.
    </Callout>

    <Callout type="info" emoji="🔒">
      **Guest-Level Masking (`__private__`):** In addition to role-based pruning via `ctx.restricted_fields`, you can declare `__private__ = {"assignee_email"}` on your `Zchema`. These fields are automatically pruned for unauthenticated guest requests (`ctx.user_id is None`) across responses, inputs, and OpenAPI schemas.
    </Callout>
  </Step>
</Steps>

We now have secure data transfer objects. Let's build the data access layer.


# Step 6 - Data Access Layer (BaseRepository) (/docs/quick-learn/step-6)





Writing the same `SELECT`, `INSERT`, and `UPDATE` queries for every model is tedious. ZCore's `BaseRepository` eliminates this boilerplate.

<Steps>
  <Step>
    ### Create the Repository [#create-the-repository]

    Open `tasks/repositories.py`. Inherit from `BaseRepository` and pass your model type:

    ```python
    # tasks/repositories.py
    from sqlalchemy.ext.asyncio import AsyncSession
    from zcore import BaseRepository
    from .models import Task

    class TaskRepo(BaseRepository[Task]):
        def __init__(self, db: AsyncSession):
            super().__init__(model=Task, db=db)
    ```
  </Step>

  <Step>
    ### What You Just Unlocked [#what-you-just-unlocked]

    <Callout type="info" emoji="📦">
      **Out-of-the-box features:** By writing this empty class, `TaskRepo` now has access to:

      * **CRUD & Mutations:** `create`, `create_multi`, `get`, `get_by_ids`, `exist`, `count`, `update`, and `delete` (with direct primary key or model instance support).
      * **Soft-Delete & Restoration:** Built-in `restore` and atomic batch `restore_multi` for recovering soft-deleted records, plus a `force=True` flag on `delete`/`delete_multi` for permanent hard-deletes.
      * **Batch Operations:** `update_multi`, `delete_multi` (with dialect-aware `RETURNING` optimizations).
      * **Pagination:** `get_list` (supports both Page-Number and high-performance Keyset Cursor pagination).
      * **Dynamic Search & Projection:** `search` with selective column loading (`fields` via `load_only`), custom SQLAlchemy options (`options`), depth-limit validation, inverted operators (`not_like`, `not_in`, `not_between`, `is_not_null`), and boolean `not` grouping.

      All methods are fully asynchronous and type-hinted.
    </Callout>
  </Step>

  <Step>
    ### No Lock-In [#no-lock-in]

    If you have a complex query that requires a raw SQL `JOIN` or a CTE, you can simply write a new custom method or override any existing CRUD method inside `TaskRepo`. Because ZCore never hides the `AsyncSession` from you, you have full access to SQLAlchemy's power directly inside your repository.
  </Step>
</Steps>

Next, we will add our business logic layer using `BaseService`.


# Step 7 - Business Logic Layer (BaseService & DI) (/docs/quick-learn/step-7)





The Service layer orchestrates business rules between the web layer and the database layer. ZCore's `BaseService` provides structured hooks to intercept operations before and after they execute.

<Steps>
  <Step>
    ### Create the Service with Auto-Wiring [#create-the-service-with-auto-wiring]

    Open `tasks/services.py`. ZCore's dependency injection container resolves type hints automatically, allowing clean constructor signatures:

    ```python
    # tasks/services.py
    from typing import Any
    from zcore import BaseService
    from .models import Task
    from .repositories import TaskRepo
    from .schemas import TaskCreate

    class TaskService(BaseService[Task]):
        # The repository dependency is automatically resolved and injected by the IoC container
        def __init__(self, repo: TaskRepo):
            super().__init__(model=Task, repository=repo)

        async def pre_create(self, schema: TaskCreate) -> dict[str, Any] | None:
            # This hook runs BEFORE the database insert.
            # Data returned here is merged with the schema payload.
            return {"title": schema.title.upper()}  # Example: force title to uppercase
    ```
  </Step>

  <Step>
    ### Understanding the Hooks [#understanding-the-hooks]

    <Callout type="info" emoji="🪝">
      **Complete Lifecycle Hooks:** `BaseService` exposes a comprehensive suite of hooks to intercept database operations:

      * **Read operations:** `post_get`, `post_get_multi`
      * **Create operations:** `pre_create`, `post_create`, `pre_create_multi`, `post_create_multi`
      * **Update operations:** `pre_update`, `post_update`, `pre_update_multi`, `post_update_multi`
      * **Delete operations:** `pre_delete`, `post_delete`, `pre_delete_multi`, `post_delete_multi&#x60; &#x2A;(all receive `force: bool = False` to distinguish between soft-deletes and hard-deletes)*
      * **Restore operations:** `pre_restore`, `post_restore`, `pre_restore_multi`, `post_restore_multi`
      * **Search operations:** `pre_search`, `post_search`

      Returning a dictionary from any `pre_*` hook merges that data directly into the database payload. This is ideal for tasks like auto-generating slug fields, populating audit timestamps, or running external API checks before finalizing database writes.
    </Callout>
  </Step>

  <Step>
    ### Transaction Autonomy [#transaction-autonomy]

    ZCore simplifies transaction boundaries by automating database commits internally. Rather than scattering `db.commit()` across your code, `BaseService` invokes `_safe_commit()`. It dynamically checks whether the session is managed under a `UnitOfWork`. If it is, ZCore delegates commit orchestration to the UoW; otherwise, it commits the changes safely and immediately.
  </Step>
</Steps>

Our logic is ready. Now, let's expose it to the web with an auto-scaffolding router.


# Step 8 - Web Layer & Plugin System (/docs/quick-learn/step-8)





Instead of writing 8 redundant route functions for every model, ZCore's `BaseRouter` generates them securely out-of-the-box (including dynamic search and field-projected lookups). We then register everything cleanly via the `Plugin` system.

<Steps>
  <Step>
    ### Configure the Router [#configure-the-router]

    Open `tasks/routers.py` and link your schemas, model, and service:

    ```python
    # tasks/routers.py
    from zcore import BaseRouter, RouteKey
    from .models import Task
    from .schemas import TaskCreate, TaskUpdate, TaskResponse
    from .services import TaskService

    class TaskRouter(BaseRouter):
        model = Task
        create_schema = TaskCreate
        update_schema = TaskUpdate
        schema_out = TaskResponse
        lookup_schema = TaskResponse  # Required to activate the /lookup endpoint
        service = TaskService
        prefix = "/tasks"
        tags = ["Tasks"]
        
        # Example: Exclude the DELETE endpoint
        exclude = {RouteKey.DELETE}

    router_instance = TaskRouter()
    ```

    <Callout type="info" emoji="🗑️">
      **Tip:** When the `DELETE` endpoint is enabled, it automatically supports the `?force=true` query parameter to execute permanent physical hard-deletions when using soft-delete models.
    </Callout>
  </Step>

  <Step>
    ### Wire the Plugin [#wire-the-plugin]

    Open `tasks/plugin.py`. The `Plugin` class manages the lifecycle of your domain. Ensure it includes your router:

    ```python
    # tasks/plugin.py
    from zcore import Plugin
    from fastapi import FastAPI
    from .routers import TaskRouter

    class TaskPlugin(Plugin):
        name = "tasks"
        version = "0.1.0"
        dependencies = [] # Can list other plugin names if needed

        def setup(self, app: FastAPI) -> None:
            from .routers import router_instance
            app.include_router(router_instance.router)
    ```
  </Step>

  <Step>
    ### Register with the Kernel [#register-with-the-kernel]

    Finally, open your root `main.py` and register the plugin with the `Kernel`. The Kernel uses topological sorting to ensure plugins start in the correct order.

    ```python
    # main.py (Add this before kernel.setup(app))
    from tasks.plugin import TaskPlugin

    # ... existing setup code ...
    kernel.add_plugin(TaskPlugin())
    kernel.setup(app)
    ```

    <Callout type="success" emoji="✅">
      **Check it out:** Run `zc run` and navigate to `http://127.0.0.1:8000/docs`. You will see 7 fully functional, secure endpoints (POST, GET, GET\_ALL, SEARCH, LOOKUP, UPDATE, PATCH) generated automatically!
    </Callout>
  </Step>
</Steps>

We have a working API. But how do we secure it and make the `Zchema` masking actually work? Let's add authentication.


# Step 9 - Security & Context (Auth & Scopes) (/docs/quick-learn/step-9)





To make our `Zchema` field-pruning work, we need to authenticate the user, extract their permissions (scopes), and load them into the `ZContext`.

<Steps>
  <Step>
    ### Define the User Protocol [#define-the-user-protocol]

    ZCore does not enforce a rigid user model. You just need a class that matches the `UserProtocol` (has `id`, `is_active`, `is_superuser`). Let's define a simple mock user and an auth dependency.

    Create `auth.py` in your root directory:

    ```python
    # auth.py
    import uuid
    from zcore import BaseAuth, ctx
    from pydantic import BaseModel

    class AppUser(BaseModel):
        id: uuid.UUID
        is_active: bool = True
        is_superuser: bool = False
        scopes: list[str] = []
        # Binds securely to ZCore's context manager
        all_restricted_fields: list[str] = []

    class AppAuth(BaseAuth[AppUser]):
        async def fetch_user(self, identity: str) -> AppUser | None:
            # In a real app, fetch from DB. Here, we mock a user.
            return AppUser(
                id=uuid.UUID(identity),
                scopes=["tasks:view"],
                # This user CANNOT view the assignee_email
                all_restricted_fields=["tasks.view.assignee_email"] 
            )
    ```

    <Callout type="info" emoji="⚡">
      **Dynamic User Caching:** `BaseAuth` automatically caches resolved user sessions to eliminate redundant database hits. The default cache lifespan is dynamically configured via `settings.AUTH_CACHE_TTL` (Default: 300s) or can be passed explicitly via `cache_ttl`.
    </Callout>
  </Step>

  <Step>
    ### Override the Auth Stub [#override-the-auth-stub]

    In `main.py`, bind this auth class to ZCore's dependency override system:

    ```python
    # main.py
    from zcore.security import get_current_user_stub
    from auth import AppAuth, AppUser

    app.dependency_overrides[get_current_user_stub] = AppAuth(user_schema=AppUser)
    ```

    <Callout type="warn" emoji="🔑">
      **Authentication Requirement:**
      Because `BaseAuth` validates the incoming Bearer token automatically, any incoming request must provide a valid JWT token signed by `Security.create_jwt()` containing the user's ID as the `sub` claim and `type="access"`.
    </Callout>

    <Callout type="info" emoji="🛡️">
      **Optional Authentication & Polymorphic IDs:**

      * `UserProtocol.id` accepts arbitrary ID types (`int`, `str`, or `uuid.UUID`).
      * For public routes that optionally accept authentication (like public task boards or guest checkouts), configure `BaseAuth(user_schema=AppUser, auto_error=False)` and override `get_optional_user_stub` instead of `get_current_user_stub`.
    </Callout>
  </Step>

  <Step>
    ### How Context Shielding Activates [#how-context-shielding-activates]

    <Callout type="info" emoji="🔗">
      **The Flow:**

      1. A request hits a `BaseRouter` endpoint.
      2. `HasScopes` dependency checks if the user has `tasks:view`.
      3. `BaseAuth.__call__` decodes the JWT, fetches the user (with cache verification), and automatically maps `all_restricted_fields` to `ctx.restricted_fields` as an immutable `frozenset`.
      4. The endpoint returns a `TaskResponse` object.
      5. `Zchema` intercepts serialization, sees the restriction, and **removes** `assignee_email` from the JSON response automatically.
    </Callout>
  </Step>
</Steps>

Our API is now secure. The final step is to write a test to prove everything works.


# How to build complex search queries (/docs/how-to/build-complex-search)





ZCore's `SearchEngine` translates nested JSON payloads into secure, optimized SQLAlchemy queries on the fly. It is exposed automatically on the `POST /search` and `POST /lookup` endpoints of any `BaseRouter`.

<Steps>
  <Step>
    ### Supported Filter Operators [#supported-filter-operators]

    | Operator                        | Meaning                                                        | Example Value                                       |
    | ------------------------------- | -------------------------------------------------------------- | --------------------------------------------------- |
    | `eq` / `ne`                     | Equal / Not Equal                                              | `"active"`, `true`, `123`                           |
    | `gt` / `lt`                     | Greater Than / Less Than                                       | `100`, `"2026-01-01"`                               |
    | `ge` / `le`                     | Greater/Less Than or Equal                                     | `50`, `"2026-08-15"`                                |
    | `between`                       | Range check (inclusive `[min, max]`, requires exactly 2 items) | `[10, 50]`, `["2026-01-01", "2026-12-31"]`          |
    | `not_between`                   | Inverted range check (`NOT BETWEEN`)                           | `[10, 50]`                                          |
    | `contains` / `not_contains`     | Substring match / Negated substring match                      | `"invoice"` (searches `%invoice%`)                  |
    | `startswith` / `not_startswith` | String prefix match / Negated prefix match                     | `"INV-"` (searches `INV-%`)                         |
    | `endswith` / `not_endswith`     | String suffix match / Negated suffix match                     | `".pdf"` (searches `%.pdf`)                         |
    | `like` / `not_like`             | Case-sensitive pattern / Negated pattern                       | `"%urgent%"`                                        |
    | `ilike` / `not_ilike`           | Case-insensitive search / Negated search                       | `"urgent"` (searches `%urgent%`)                    |
    | `in` / `not_in`                 | In a list of values / Not in list                              | `["pending", "in_progress"]`                        |
    | `is_null`                       | Check for `NULL`                                               | `true` or `null` (is null), `false` (is not null)   |
    | `is_not_null`                   | Check for `NOT NULL`                                           | `true` or `null` (is not null), `false` (is null)   |
    | `and` / `or`                    | Logical conjunction / disjunction                              | Array of sub-filters in `items`                     |
    | `not`                           | Logical negation                                               | Array of sub-filters in `items` or a single `field` |
  </Step>

  <Step>
    ### Example Search Payload [#example-search-payload]

    Send a `POST` request to `/tasks/search`. You can paginate using traditional offset parameters (`page`) or pass a Keyset token (`cursor`) for drift-free lookups on large datasets:

    ```json
    POST /tasks/search
    Content-Type: application/json

    {
      "filters": [
        {
          "op": "and",
          "items": [
            { "field": "is_completed", "op": "eq", "value": false },
            { "field": "title", "op": "not_contains", "value": "draft" },
            { "field": "priority", "op": "between", "value": [1, 5] },
            { "field": "code", "op": "startswith", "value": "TSK-" },
            { "field": "deleted_at", "op": "is_null", "value": true }
          ]
        },
        {
          "op": "not",
          "items": [
            { "field": "status", "op": "in", "value": ["archived", "cancelled"] }
          ]
        },
        { 
          "field": "assignee.email", 
          "op": "eq", 
          "value": "admin@example.com" 
        }
      ],
      "include": ["assignee"],
      "sort": [
        { "field": "created_at", "order": "desc" }
      ],
      "page": 1,
      "cursor": null,
      "size": 20
    }
    ```
  </Step>

  <Step>
    ### Configuring Max Search Depth & Page Boundaries [#configuring-max-search-depth--page-boundaries]

    ZCore dynamically resolves limits and depth constraints hierarchically:

    1. **Search Depth Limit:** Resolved first from the model attribute `__max_search_depth__`, falling back to `settings.SEARCH_MAX_DEPTH` (default: **3**).
    2. **Pagination Bounds:** The `size` parameter in `SearchRequest` is automatically bounded between `1` and `settings.PAGINATION_MAX_SIZE` (default: **100**), with a fallback to `settings.PAGINATION_DEFAULT_SIZE` (default: **20**).
    3. **Keyset Cursor Support:** When `cursor` is provided, `SearchEngine` executes keyset comparisons against the model primary key, bypassing table offset scans.

    To allow deeper relation eager-loading or deeply nested filter structures on a specific model:

    ```python
    # tasks/models.py
    from zcore import Base

    class Task(Base):
        __tablename__ = "tasks"
        __max_search_depth__ = 5  # <--- Overrides settings.SEARCH_MAX_DEPTH for this model
        ...
    ```
  </Step>
</Steps>

<Callout type="info" emoji="🛡️">
  **Built-In Security & Safeguards:**

  * **Context Shielding:** If the active user has a restricted field in `ctx.restricted_fields` (e.g. `tasks.assignee.email`), any attempt to filter, sort, or include that field immediately raises a `ForbiddenError`.
  * **SQL Injection & Wildcard Protection:** Wildcard characters like `%` and `_` inside `ilike`, `contains`, `startswith`, `endswith`, and their `not_*` counterparts are automatically escaped.
  * **Non-String Column Casting:** Text operators applied to non-string columns (such as numbers or UUIDs) are automatically cast to `String` under the hood.
  * **DoS Defense (Max Depth & Size Clamping):** Filter nesting and relation joins (`include`) are strictly bounded by `__max_search_depth__` / `SEARCH_MAX_DEPTH`. Requested page sizes are automatically clamped to `PAGINATION_MAX_SIZE`.
  * **Automatic Type Coercion:** Strings representing numbers (`int`, `float`), ISO timestamps, dates, booleans, and UUIDs (including elements inside `between` ranges and `in` collections) are safely converted to their matching Python column types.
</Callout>


# How to cache database queries (/docs/how-to/cache-database-queries)





ZCore's `BaseCache` provides a unified caching interface. It connects to distributed Redis instances while seamlessly degrading to a thread-safe in-memory `TTLLRUCache` if Redis is offline or unconfigured.

<Steps>
  <Step>
    ### 1. Initialize the Cache Client [#1-initialize-the-cache-client]

    Configure the global cache client in your `main.py` (or within a plugin lifecycle hook):

    ```python
    # main.py
    from zcore import settings
    from zcore.cache import init_cache

    # Initializes distributed Redis connection and starts background local eviction loop
    init_cache(redis_url=settings.REDIS_URL)
    ```
  </Step>

  <Step>
    ### 2. Implement the Cache-Aside Pattern [#2-implement-the-cache-aside-pattern]

    Instantiate `BaseCache` with a domain prefix namespace. `BaseCache` automatically derives default TTLs and local size boundaries from your `Settings`, and accepts `target_type` to auto-deserialize JSON into validated Pydantic models:

    ```python
    # services.py or repositories.py
    import uuid
    from zcore.cache import BaseCache
    from .schemas import TaskResponse
    from .models import Task

    class TaskService:
        def __init__(self, repo):
            self.repo = repo
            # Inherits default TTL from settings.CACHE_DEFAULT_TTL (default: 3600s)
            # and local maxsize from settings.CACHE_LOCAL_MAXSIZE (default: 1000 items)
            self.cache = BaseCache[TaskResponse](prefix="tasks")

        async def get_task_details(self, task_id: uuid.UUID) -> TaskResponse:
            cache_key = str(task_id)

            # 1. Attempt to fetch from Cache (Auto-deserializes into TaskResponse)
            cached_data = await self.cache.get(cache_key, target_type=TaskResponse)
            if cached_data:
                return cached_data

            # 2. Cache Miss: Fetch from database
            db_record = await self.repo.get(id=task_id)
            task_response = TaskResponse.model_validate(db_record)

            # 3. Populate Cache (ttl is optional; falls back to instance default_ttl)
            await self.cache.set(cache_key, task_response)
            
            return task_response
    ```
  </Step>

  <Step>
    ### 3. Invalidate Cache on Mutations [#3-invalidate-cache-on-mutations]

    Purge cached records when modifying or deleting database entities:

    ```python
    async def update_task(self, task_id: uuid.UUID, schema):
        updated = await self.repo.update(task_id, schema)
        
        # Evict key from both Redis and local memory fallback store
        await self.cache.delete(str(task_id))
        return updated
    ```
  </Step>
</Steps>

***

## Dynamic Framework Settings [#dynamic-framework-settings]

ZCore manages caching boundaries centrally via environment variables and the `Settings` class:

| Setting Key               | Default         | Description                                                                      |
| ------------------------- | --------------- | -------------------------------------------------------------------------------- |
| `CACHE_DEFAULT_TTL`       | `3600` (1 hour) | Default fallback TTL in seconds when `ttl` is omitted in `cache.set()`.          |
| `CACHE_LOCAL_MAXSIZE`     | `1000`          | Maximum entries retained simultaneously in the local in-memory `TTLLRUCache`.    |
| `CACHE_EVICTION_INTERVAL` | `60`            | Duration in seconds between automated garbage collection sweeps on expired keys. |

<Callout type="info" emoji="🛡️">
  **Fail-Safe In-Memory Fallback:**
  If Redis is unavailable or unconfigured (`REDIS_URL=None`), `BaseCache` automatically stores records in an in-memory `TTLLRUCache`. Expired keys are periodically swept by a non-blocking background worker loop scheduled at `settings.CACHE_EVICTION_INTERVAL` seconds.
</Callout>


# How to configure Database and Logging (/docs/how-to/configure-database-and-logging)





ZCore provides structured configuration schemas for the database engine (`DatabaseSettings`) and observability pipeline (`LoggingSettings`), supporting environment variable synchronization, declarative classes, and programmatic runtime initialization.

***

## 1. Configuring the Database Engine [#1-configuring-the-database-engine]

<Steps>
  <Step>
    ### Option A: Environment Variables (Zero-Code) [#option-a-environment-variables-zero-code]

    Set database variables in your `.env` file. ZCore automatically synchronizes flat environment variables with `settings.DATABASE`:

    ```dotenv
    # .env
    DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/production_db
    POOL_SIZE=20
    MAX_OVERFLOW=10
    ```

    Bootstrap `db_manager` in `main.py`:

    ```python
    # main.py
    from zcore import db_manager, settings

    db_manager.init_app(config=settings.DATABASE)
    ```
  </Step>

  <Step>
    ### Option B: Declarative Settings Subclass [#option-b-declarative-settings-subclass]

    To configure engine options like connection arguments (`connect_args`) or execution options (`execution_options`), declare `DATABASE` in your custom `Settings` class:

    ```python
    # config.py
    from zcore.config import Settings, DatabaseSettings

    class AppSettings(Settings):
        DATABASE: DatabaseSettings = DatabaseSettings(
            url="postgresql+asyncpg://postgres:postgres@localhost:5432/production_db",
            pool_size=20,
            max_overflow=30,
            pool_recycle=3600,
            pool_pre_ping=True,
            connect_args={"server_settings": {"jit": "off"}},
            execution_options={"isolation_level": "REPEATABLE READ"},
            extra_engine_kwargs={}
        )
    ```
  </Step>

  <Step>
    ### Option C: Direct `db_manager.init_app` Invocation [#option-c-direct-db_managerinit_app-invocation]

    Pass a `DatabaseSettings` model instance or dictionary directly during startup:

    ```python
    # main.py
    from zcore import db_manager
    from zcore.config import DatabaseSettings

    db_manager.init_app(
        config=DatabaseSettings(
            url="postgresql+asyncpg://postgres:postgres@localhost:5432/production_db",
            pool_size=15,
            connect_args={"timeout": 30}
        )
    )
    ```
  </Step>
</Steps>

***

## 2. Configuring Structured Logging [#2-configuring-structured-logging]

<Steps>
  <Step>
    ### Option A: Standard Setup with `.env` [#option-a-standard-setup-with-env]

    ```dotenv
    # .env
    LOG_LEVEL=INFO
    LOG_SQL_QUERIES=False              # Flat setting for query logging
    SLOW_QUERY_THRESHOLD_MS=200.0      # Independently track slow queries
    ```

    Initialize logging at the beginning of `main.py`:

    ```python
    # main.py
    from zcore.logging import setup_logging

    setup_logging()
    ```
  </Step>

  <Step>
    ### Option B: Declarative `LoggingSettings` [#option-b-declarative-loggingsettings]

    Configure file rotation boundaries (`max_bytes`, `backup_count`), slow SQL query thresholds, and distinct logger behaviors (`muted`, `passthrough`, `intercept`) in your `Settings` subclass:

    ```python
    # config.py
    from zcore.config import Settings, LoggingSettings

    class AppSettings(Settings):
        LOGGING: LoggingSettings = LoggingSettings(
            level="INFO",
            json_format=None,              # None: Console in Debug, JSON in Production
            log_sql_queries=False,         # Disabled by default in rc.2 to avoid noise
            slow_query_threshold_ms=200.0, # Log only queries exceeding 200ms (works independently!)
            file_path="./logs/app.log",    # Enables RotatingFileHandler
            max_bytes=20 * 1024 * 1024,    # Rotate when file reaches 20MB (default: 10MB)
            backup_count=10,               # Retain 10 rotated log backups (default: 5)
            muted_loggers=["sqlalchemy.engine"],
            passthrough_loggers=["uvicorn", "uvicorn.access", "uvicorn.error"]
        )
    ```
  </Step>

  <Step>
    ### Option C: Advanced Programmatic Overrides [#option-c-advanced-programmatic-overrides]

    `setup_logging` supports custom structlog processors, extra standard library handlers, and complete `logging.config.dictConfig` overrides:

    ```python
    # main.py
    import logging
    from zcore.logging import setup_logging, LoggingSettings

    # 1. Custom handlers and processors
    setup_logging(
        config=LoggingSettings(
            level="DEBUG",
            file_path="./logs/app.log",
            max_bytes=10 * 1024 * 1024,
            backup_count=5
        ),
        extra_handlers=[logging.StreamHandler()],
        log_level="DEBUG"
    )

    # 2. Complete dictConfig override
    setup_logging(
        dict_config={
            "version": 1,
            "disable_existing_loggers": False,
            "handlers": {
                "console": {"class": "logging.StreamHandler", "level": "INFO"}
            },
            "root": {"handlers": ["console"], "level": "INFO"}
        }
    )
    ```
  </Step>
</Steps>

<Callout type="info" emoji="⚡">
  **SQL Query Logging:**
  When `log_sql_queries` is enabled, executed statements are formatted with duration metrics (`duration_ms`). If `slow_query_threshold_ms` is set, queries exceeding this limit are tracked and logged independently, even if general query logging is turned off.
</Callout>


# How to enforce Permission Scopes (/docs/how-to/enforce-permission-scopes)





ZCore eliminates authorization boilerplate by automatically generating and enforcing scope permissions per database model.

### Automated Model Actions [#automated-model-actions]

When a model inherits from ZCore's `Base`, it automatically exposes the `.actions()` descriptor mapped to its `__tablename__`:

| Model Action              | Generated Scope Key | Mapped Route Key            |
| ------------------------- | ------------------- | --------------------------- |
| `Task.actions().CREATE`   | `"tasks:create"`    | `POST /`                    |
| `Task.actions().VIEW`     | `"tasks:view"`      | `GET /{id}`                 |
| `Task.actions().LISTVIEW` | `"tasks:listview"`  | `GET /` & `POST /search`    |
| `Task.actions().LOOKUP`   | `"tasks:lookup"`    | `POST /lookup`              |
| `Task.actions().UPDATE`   | `"tasks:update"`    | `PUT /{id}` & `PATCH /{id}` |
| `Task.actions().DELETE`   | `"tasks:delete"`    | `DELETE /{id}`              |

<Steps>
  <Step>
    ### 1. Automatic Scoping in `BaseRouter` (Zero-Config) [#1-automatic-scoping-in-baserouter-zero-config]

    By simply declaring `model = Task` on your `BaseRouter`, all 8 standard endpoints are **automatically protected** with their corresponding `HasScopes(...)` rules:

    ```python
    # routers.py
    from zcore import BaseRouter
    from .models import Task
    from .schemas import TaskCreate, TaskUpdate, TaskResponse
    from .services import TaskService

    class TaskRouter(BaseRouter[TaskCreate, TaskUpdate]):
        model = Task
        create_schema = TaskCreate
        update_schema = TaskUpdate
        schema_out = TaskResponse
        service = TaskService
        prefix = "/tasks"

    # POST /tasks automatically requires "tasks:create"
    # GET /tasks/{id} automatically requires "tasks:view"
    # POST /tasks/lookup automatically requires "tasks:lookup"
    # DELETE /tasks/{id} automatically requires "tasks:delete"
    router_instance = TaskRouter()
    ```
  </Step>

  <Step>
    ### 2. Customizing Route Dependencies [#2-customizing-route-dependencies]

    To override or inject custom permissions for specific operations, override `get_route_dependencies`:

    ```python
    from typing import Any
    from zcore import BaseRouter, RouteKey, HasScopes

    class TaskRouter(BaseRouter[TaskCreate, TaskUpdate]):
        # ... standard configurations ...

        def get_route_dependencies(self, route_key: RouteKey, action: str) -> list[Any]:
            # Enforce an extra high-privilege scope strictly for deletion
            if route_key == RouteKey.DELETE:
                return [HasScopes("admin:all", "tasks:delete")]
                
            # Fallback to default automated model actions for other routes
            return super().get_route_dependencies(route_key, action)
    ```
  </Step>

  <Step>
    ### 3. Using `HasScopes` in Custom Routes [#3-using-hasscopes-in-custom-routes]

    For standalone or non-CRUD FastAPI endpoints, use `HasScopes` directly as a dependency:

    ```python
    from fastapi import APIRouter, Depends
    from zcore.security import HasScopes

    custom_router = APIRouter()

    @custom_router.get(
        "/tasks/analytics/summary",
        dependencies=[Depends(HasScopes("tasks:analytics", "reports:view"))]
    )
    async def get_analytics_summary():
        return {"metrics": "active"}
    ```
  </Step>
</Steps>

<Callout type="info" emoji="👑">
  **Superuser Bypass:**
  By default, `HasScopes(*required_scopes, allow_superuser=True)` automatically allows users with `is_superuser = True` to bypass scope checks.
</Callout>

<Callout type="warn" emoji="🚫">
  **Security Responses:**

  * If the user is unauthenticated or marked `is_active = False&#x60; $\rightarrow$ &#x2A;*`401 Unauthorized`**.
  * If the user lacks any of the required scopes $\rightarrow$ &#x2A;*`403 Forbidden`**.
</Callout>


# How to expose dynamic schemas (?schema=true) (/docs/how-to/expose-dynamic-schemas)





Frontend developers and low-code platforms (like Retool, Appsmith, or JSON Schema form generators) can append `?schema=true` to any ZCore endpoint to fetch its active schema definition.

<Steps>
  <Step>
    ### 1. Enable Dynamic Schemas on the Router [#1-enable-dynamic-schemas-on-the-router]

    Set `expose_schemas = True` globally, or specify a targeted set of `RouteKey` actions:

    ```python
    # routers.py
    from zcore import BaseRouter, RouteKey
    from .models import Task
    from .schemas import TaskCreate, TaskUpdate, TaskResponse
    from .services import TaskService

    class TaskRouter(BaseRouter[TaskCreate, TaskUpdate]):
        model = Task
        create_schema = TaskCreate
        update_schema = TaskUpdate
        schema_out = TaskResponse
        service = TaskService
        prefix = "/tasks"

        # Option A: Enable for all CRUD endpoints
        expose_schemas = True

        # Option B: Enable selectively (e.g., only Create & Update forms)
        # expose_schemas = {RouteKey.POST, RouteKey.UPDATE}

    router_instance = TaskRouter()
    ```
  </Step>

  <Step>
    ### 2. Request Schema via HTTP [#2-request-schema-via-http]

    Append `?schema=true` to the target endpoint:

    ```bash
    # Fetch Output Display Schema for viewing tasks (GET)
    curl -X GET "http://localhost:8000/tasks?schema=true"

    # Fetch Input Form Schema for creating a task (POST)
    curl -X POST "http://localhost:8000/tasks?schema=true"
    ```
  </Step>

  <Step>
    ### 3. Real-World Response Structure [#3-real-world-response-structure]

    ZCore returns the full Pydantic v2 JSON Schema specification (including `$defs` for nested relations and validation rules). Any restricted field defined in `ctx.restricted_fields` is **automatically pruned** from both `properties` and `required` arrays:

    ```json
    {
      "success": true,
      "message": "Schema generated successfully",
      "data": {
        "$defs": {
          "TaskResponse": {
            "properties": {
              "id": { "format": "uuid", "title": "Id", "type": "string" },
              "title": { "title": "Title", "type": "string" },
              "is_completed": { "default": false, "title": "Is Completed", "type": "boolean" }
              // Sensitive fields like 'salary' or 'assignee_email' are pruned automatically!
            },
            "required": ["id", "title"],
            "title": "TaskResponse",
            "type": "object"
          }
        },
        "properties": {
          "success": { "default": true, "title": "Success", "type": "boolean" },
          "message": { "default": "Success", "title": "Message", "type": "string" },
          "data": {
            "anyOf": [
              { "items": { "$ref": "#/$defs/TaskResponse" }, "type": "array" },
              { "type": "null" }
            ],
            "default": null,
            "title": "Data"
          },
          "meta": {
            "anyOf": [
              { "additionalProperties": true, "type": "object" },
              { "type": "null" }
            ],
            "default": null,
            "title": "Meta"
          }
        },
        "title": "ResponseWrapper[list[TaskResponse]]",
        "type": "object"
      },
      "meta": {
        "restricted_fields": ["tasks.view.salary"]
      }
    }
    ```
  </Step>
</Steps>

<Callout type="info" emoji="🧠">
  **Intelligent Method Resolution:**

  * For `POST`, `PUT`, and `PATCH` requests, ZCore automatically resolves and returns the **Input Body Schema** (`create_schema` / `update_schema`).
  * For `GET` requests, ZCore resolves and returns the **Output Serialization Schema** (`schema_out`).
</Callout>


# How to extend BaseRouter with Custom Reusable Endpoints (/docs/how-to/extend-base-router)





ZCore's `BaseRouter` scaffolds 8 standard CRUD and search endpoints out of the box (`POST`, `GET`, `GET_ALL`, `SEARCH`, `LOOKUP`, `UPDATE`, `PATCH`, `DELETE`).

However, enterprise applications often require company-wide shared endpoints across multiple models—such as a &#x2A;*batch status changer (`PATCH /bulk-status`)**, &#x2A;*soft-delete bulk recovery (`POST /bulk-restore`)**, or &#x2A;*data export (`GET /export`)**.

Instead of writing these handlers repeatedly in every domain, you can create a centralized `AppBaseRouter` that extends `BaseRouter` and attaches reusable endpoints across your entire architecture.

<Callout type="info" emoji="💡">
  **Looking for the `/lookup` endpoint?**
  As of ZCore `v0.1.0-rc.2`, field-projected relational lookups (`POST /lookup`) are &#x2A;*built directly into `BaseRouter`**. You only need to define `lookup_schema = YourLookupSchema` in your router class.
</Callout>

***

<Steps>
  <Step>
    ### 1. Define the Shared Request & Response Schemas [#1-define-the-shared-request--response-schemas]

    Create the shared Pydantic payload models that your custom endpoint will accept:

    ```python
    # shared/schemas.py
    import uuid
    from pydantic import BaseModel, Field


    class BulkStatusUpdateIn(BaseModel):
        ids: list[uuid.UUID] = Field(..., min_length=1, max_length=100)
        status: str = Field(..., max_length=50)


    class BulkOperationResult(BaseModel):
        affected_count: int
        message: str = "Operation completed successfully"
    ```
  </Step>

  <Step>
    ### 2. Create the Custom `AppBaseRouter` [#2-create-the-custom-appbaserouter]

    Create a reusable base class that inherits from `BaseRouter`. Override `_register_routes()`, register your custom route using FastAPI's `add_api_route()`, and invoke `self._sort_routes()` to ensure proper route specificity ordering:

    ```python
    # shared/base/router.py
    from typing import Any, Generic, TypeVar
    from fastapi import Depends, status
    from pydantic import BaseModel
    from zcore import BaseRouter, BaseService, ResponseWrapper
    from zcore.kernel import Injector
    from shared.schemas import BulkOperationResult, BulkStatusUpdateIn

    CreateSchemaType = TypeVar("CreateSchemaType", bound=BaseModel)
    UpdateSchemaType = TypeVar("UpdateSchemaType", bound=BaseModel)


    class AppBaseRouter(
        BaseRouter[CreateSchemaType, UpdateSchemaType],
        Generic[CreateSchemaType, UpdateSchemaType]
    ):
        """Custom enterprise base router adding organization-wide endpoints."""

        enable_bulk_status: bool = False

        def _register_routes(self) -> None:
            # 1. Register the standard 8 ZCore CRUD endpoints
            super()._register_routes()

            # 2. Register custom company-wide endpoints conditionally
            if self.enable_bulk_status:
                self._register_bulk_status_route()

            # 3. Always sort routes by specificity to prevent path shadowing
            self._sort_routes()

        def _register_bulk_status_route(self) -> None:
            service_callable = self.service
            service_dependency = Depends(Injector(service_callable))

            async def _bulk_status_endpoint(
                payload: BulkStatusUpdateIn,
                service_inst: BaseService = service_dependency,
            ) -> ResponseWrapper[BulkOperationResult]:
                return await self.bulk_status_endpoint(payload, service_inst)

            # Resolve route action for RBAC permissions (e.g. "tasks:update")
            action = self.get_route_action("UPDATE") if self.model else ""
            dependencies = self._normalize_dependencies(
                self.get_route_dependencies("UPDATE", action)
            )

            self.router.add_api_route(
                path="/bulk-status",
                endpoint=_bulk_status_endpoint,
                methods=["PATCH"],
                dependencies=dependencies,
                status_code=status.HTTP_200_OK,
                response_model=ResponseWrapper[BulkOperationResult],
                summary=f"Bulk update status for {self.model.__name__}",
            )

        async def bulk_status_endpoint(
            self,
            payload: BulkStatusUpdateIn,
            service: BaseService,
        ) -> ResponseWrapper[BulkOperationResult]:
            """Execute bulk status update via the service layer."""
            if hasattr(service, "bulk_update_status"):
                count = await service.bulk_update_status(payload.ids, payload.status)
            else:
                # Fallback: update records using the service update_multi
                update_data = {
                    item_id: {"status": payload.status} for item_id in payload.ids
                }
                # Using dummy update schema or direct dictionary
                results = await service.on_update_multi(update_data, partial=True)
                count = len(results)

            return ResponseWrapper(
                data=BulkOperationResult(
                    affected_count=count,
                    message=f"Successfully updated {count} records."
                )
            )
    ```
  </Step>

  <Step>
    ### 3. Inherit from `AppBaseRouter` in Domain Routers [#3-inherit-from-appbaserouter-in-domain-routers]

    Use `AppBaseRouter` instead of `BaseRouter` in your domain modules and activate the feature flag:

    ```python
    # tasks/routers.py
    from zcore import RouteKey
    from shared.base.router import AppBaseRouter
    from .models import Task
    from .schemas import TaskCreate, TaskResponse, TaskUpdate
    from .services import TaskService


    class TaskRouter(AppBaseRouter[TaskCreate, TaskUpdate]):
        model = Task
        create_schema = TaskCreate
        update_schema = TaskUpdate
        schema_out = TaskResponse
        service = TaskService
        prefix = "/tasks"
        tags = ["Tasks"]

        # Enable our custom shared endpoint
        enable_bulk_status = True


    router_instance = TaskRouter()
    ```
  </Step>

  <Step>
    ### 4. Client Execution Example [#4-client-execution-example]

    Start your server with `zc run` and execute a batch status update request:

    ```bash
    curl -X PATCH "http://localhost:8000/tasks/bulk-status" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer <token>" \
      -d '{
        "ids": [
          "a3b8e284-8392-491a-a5f1-39c89284910a",
          "b4c9f395-9403-402b-b6f2-40d90395021b"
        ],
        "status": "completed"
      }'
    ```

    **Response:**

    ```json
    {
      "success": true,
      "message": "Success",
      "data": {
        "affected_count": 2,
        "message": "Successfully updated 2 records."
      },
      "meta": null
    }
    ```
  </Step>
</Steps>

<Callout type="warn" emoji="⚖️">
  **Route Specificity Notice:**
  Whenever you add static endpoints like `/bulk-status` or `/export`, always call `self._sort_routes()` at the end of `_register_routes()`. ZCore’s specificity sorter guarantees that static paths are evaluated before dynamic primary key patterns (like `/{id}`), preventing route collisions.
</Callout>


# How to extend the Settings class (/docs/how-to/extend-settings)





ZCore uses Pydantic v2 for settings management. To introduce your own configuration variables (e.g., `AWS_BUCKET`, `REDIS_PASSWORD`), simply extend the core `Settings` class.

<Callout type="info" emoji="💡">
  **Circular-Dependency Safe:** ZCore's exported `settings` object is a dynamic `SettingsProxy`. You can import and access it anywhere across your application without triggering premature evaluation or circular import errors.
</Callout>

<Steps>
  <Step>
    ### Define and Register Custom Settings in `main.py` [#define-and-register-custom-settings-in-mainpy]

    At the very top of your `main.py` (before initializing the database and Kernel), define your `AppSettings` subclass and pass its instance to `initialize_settings`:

    ```python
    # main.py
    from zcore.config import Settings, initialize_settings

    class AppSettings(Settings):
        AWS_BUCKET: str = "default-bucket"
        MAX_RETRIES: int = 3

    # Register your custom settings singleton into ZCore's IoC container at startup
    initialize_settings(AppSettings())

    # --- Continue with your standard main.py setup ---
    from fastapi import FastAPI
    from zcore import Kernel, settings, db_manager
    # ...
    ```
  </Step>

  <Step>
    ### Access Settings Anywhere [#access-settings-anywhere]

    Import the global `settings` proxy directly from `zcore` inside any router, service, or plugin:

    ```python
    # any_service.py or any_router.py
    from zcore import settings

    def connect_aws():
        bucket = settings.AWS_BUCKET
        retries = settings.MAX_RETRIES
        print(f"Connecting to {bucket} with {retries} retries...")
    ```
  </Step>
</Steps>

<Callout type="success" emoji="⚡">
  **CLI Integration:** Once you declare `AppSettings` in `main.py`, running `zc genenv` in your terminal will automatically inspect your subclass and scaffold a `.env.example` file containing your newly declared variables!
</Callout>


# How to handle and raise domain exceptions (/docs/how-to/handle-custom-exceptions)





ZCore eliminates inconsistent error payloads across endpoints. Raising any `AppException` subclass or encountering runtime validation errors automatically formats the response into a unified `ResponseWrapper` envelope with the correct HTTP status code.

<Steps>
  <Step>
    ### 1. Raising Built-In Exceptions in Services [#1-raising-built-in-exceptions-in-services]

    Raise typed exceptions directly inside your services, repositories, or hooks:

    ```python
    # tasks/services.py
    import uuid
    from zcore import BaseService
    from zcore.exceptions import EntityNotFound, ValidationError
    from .models import Task
    from .repositories import TaskRepo
    from .schemas import TaskCreate

    class TaskService(BaseService[Task]):
        def __init__(self, repo: TaskRepo):
            super().__init__(model=Task, repository=repo)

        async def mark_task_as_done(self, task_id: uuid.UUID):
            task = await self.repository.get(id=task_id)
            if not task:
                # Raises 404 with structured payload context
                raise EntityNotFound(
                    message=f"Task with ID {task_id} does not exist.",
                    payload={"task_id": str(task_id)}
                )

            if task.is_completed:
                # Raises 400 Bad Request
                raise ValidationError(
                    message="Task is already marked as completed."
                )

            return await self.repository.update(task_id, {"is_completed": True})
    ```
  </Step>

  <Step>
    ### 2. Creating Custom Business Exceptions [#2-creating-custom-business-exceptions]

    To define domain-specific exceptions, subclass `AppException` and specify your desired `status_code`:

    ```python
    # tasks/exceptions.py
    from zcore.exceptions import AppException

    class TaskLimitExceeded(AppException):
        status_code = 422  # Unprocessable Entity
        
        def __init__(self, current_count: int, max_limit: int):
            super().__init__(
                message=f"Account task limit reached ({current_count}/{max_limit}).",
                payload={"current_count": current_count, "max_limit": max_limit}
            )

    class PaymentRequired(AppException):
        status_code = 402  # Payment Required
    ```
  </Step>

  <Step>
    ### 3. Registering Unified Handlers in `main.py` [#3-registering-unified-handlers-in-mainpy]

    ZCore provides a single registration function, `register_exception_handlers`, that registers normalization handlers for all exception categories:

    ```python
    # main.py
    from fastapi import FastAPI
    from zcore import register_exception_handlers

    app = FastAPI(...)

    # Normalizes domain errors, Pydantic 422s, HTTPExceptions, and 500 runtime errors
    register_exception_handlers(app)
    ```

    You can also selectively toggle specific handlers using boolean flags:

    ```python
    register_exception_handlers(
        app,
        include_app_exceptions=True,
        include_validation_exceptions=True,
        include_http_exceptions=True,
        include_response_validation_exceptions=True,
        include_unhandled_exceptions=True,
    )
    ```
  </Step>
</Steps>

<Callout type="info" emoji="📦">
  **Uniform Response Envelope:**
  Every error intercepted by ZCore is serialized into a standard `ResponseWrapper[None]` structure:

  ```json
  {
    "success": false,
    "message": "Account task limit reached (100/100).",
    "data": null,
    "meta": {
      "error_type": "TaskLimitExceeded",
      "payload": {
        "current_count": 100,
        "max_limit": 100
      }
    }
  }
  ```
</Callout>

***

## Handlers & Debug-Gated Security [#handlers--debug-gated-security]

`register_exception_handlers(app)` attaches five dedicated exception handlers:

| Exception Category            | HTTP Status       | Response Handling                                                                                                                |
| ----------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **`AppException`**            | `exc.status_code` | Extracts custom message and context payload into `meta.payload`.                                                                 |
| **`RequestValidationError`**  | `422`             | Converts Pydantic error tuples into clean dot-separated paths (e.g. `body.items.0.title`) and returns sanitized error summaries. |
| **`StarletteHTTPException`**  | `exc.status_code` | Preserves custom HTTP headers and maps the detail message.                                                                       |
| **`ResponseValidationError`** | `500`             | Catches internal endpoint output schema mismatches.                                                                              |
| **`Exception` (Catch-all)**   | `500`             | Catches any uncaught runtime errors to prevent server crashes.                                                                   |

<Callout type="warn" emoji="🔒">
  **Production Data Leak Protection (Debug-Gating):**
  For `ResponseValidationError` and generic `Exception` (500 errors), full stack traces and diagnostic details are &#x2A;*only rendered in the JSON response when `settings.DEBUG = True`**.

  In production (`DEBUG = False`), internal error details are masked with a safe, generic message (`"Internal server error"`) while the complete stack trace is safely recorded in your structured logs.
</Callout>


# How to implement Cursor Pagination (/docs/how-to/implement-cursor-pagination)





For high-throughput datasets or infinite-scroll feeds, offset pagination causes query slowdowns and duplicate items (offset drift). ZCore provides `CursorPagination` based on encoded keysets.

<Steps>
  <Step>
    ### 1. Enable Cursor Pagination on the Router [#1-enable-cursor-pagination-on-the-router]

    Open your router file and set `pagination_class = CursorPagination`. This automatically changes the `GET /` endpoint query signature to accept `cursor` and `size`:

    ```python
    # routers.py
    from zcore import BaseRouter
    from zcore.db.pagination import CursorPagination
    from .models import Task
    from .schemas import TaskCreate, TaskUpdate, TaskResponse
    from .services import TaskService

    class TaskRouter(BaseRouter[TaskCreate, TaskUpdate]):
        model = Task
        create_schema = TaskCreate
        update_schema = TaskUpdate
        schema_out = TaskResponse
        service = TaskService
        
        # Switch from default Page-Number to Keyset Cursor pagination
        pagination_class = CursorPagination
        prefix = "/tasks"
        tags = ["Tasks"]

    router_instance = TaskRouter()
    ```
  </Step>

  <Step>
    ### 2. Client Requests [#2-client-requests]

    The client can fetch the first page by simply requesting the desired size, then passing the returned `cursor` for subsequent pages:

    ```bash
    # Initial request (First page)
    curl -X GET "http://localhost:8000/tasks/?size=20"

    # Subsequent request using the received next_cursor
    curl -X GET "http://localhost:8000/tasks/?size=20&cursor=eyJ2YWx1ZSI6ICI...=="
    ```
  </Step>

  <Step>
    ### 3. Response Structure [#3-response-structure]

    The response is wrapped in ZCore's `ResponseWrapper`. The `meta` block contains the pagination state:

    ```json
    {
      "success": true,
      "message": "Success",
      "data": [
        {
          "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "title": "Complete documentation",
          "is_completed": false
        }
      ],
      "meta": {
        "next_cursor": "eyJ2YWx1ZSI6ICIyMDI2LTA4LTE1VDA4OjAwOjAwIiwgInBrIjogImExYjJjM2Q0Li4uIn0",
        "has_more": true,
        "size": 20
      }
    }
    ```
  </Step>
</Steps>

<Callout type="info" emoji="⚡">
  **Dynamic Primary Key Inspection:**
  As of `rc.2`, `CursorPagination()` automatically inspects your model's primary key column (supporting both `uuid.UUID` and `int` primary keys). The cursor token encapsulates `{"value": ..., "pk": ...}` into a URL-safe Base64 token to execute fast indexed lookups (`WHERE col < val`) without scanning rows via `OFFSET`.
</Callout>


# How to structure inter-module contracts and dependency wiring (/docs/how-to/inter-module-contracts-and-wiring)





In a **Modular Monolith** architecture, modules often need data or business validation from other domains. Direct cross-module imports (e.g., importing `UserService` or `Users` model directly into `CRMService`) create circular dependency traps and high coupling.

ZCore resolves this using a 4-tier pattern:

1. **Contracts (Protocols):** Abstract interfaces defined in `shared/contract/`.
2. **Wiring (Dependencies):** FastAPI `Annotated` dependency definitions in `shared/wiring/`.
3. **Upstream/Downstream Dependency Resolution:** Declared in `Plugin.dependencies`.
4. **IoC Binding:** Mapping protocols to concrete implementations in `Plugin.setup()`.

***

<Steps>
  <Step>
    ### 1. Define the Abstract Contract (`shared/contract/`) [#1-define-the-abstract-contract-sharedcontract]

    Define a Python `typing.Protocol` representing the methods exposed by the upstream module to the rest of the application:

    ```python
    # shared/contract/auth/users.py
    import uuid
    from typing import Any, Optional, Protocol
    from zcore.db import PaginatedResult


    class UserValidator(Protocol):
        async def get(self, id: uuid.UUID) -> Optional[Any]: ...
        async def get_list(self, params: Any) -> PaginatedResult: ...
    ```

    ```python
    # shared/contract/crm/contacts.py
    import uuid
    from typing import Any, Optional, Protocol


    class Contacts(Protocol):
        async def validate_contact(self, id: uuid.UUID | None) -> None: ...
        async def create(self, schema: Any) -> Any: ...
        async def update(self, id: uuid.UUID, schema: Any, partial: bool = False) -> Any: ...
    ```
  </Step>

  <Step>
    ### 2. Create the Dependency Wiring (`shared/wiring/`) [#2-create-the-dependency-wiring-sharedwiring]

    Create an `Annotated` type alias in `shared/wiring/` that resolves the contract from the IoC container via `Depends`:

    ```python
    # shared/wiring/auth.py
    from typing import Annotated
    from fastapi import Depends
    from shared.contract.auth.users import UserValidator
    from zcore import container


    async def get_user_contract() -> UserValidator:
        return container.resolve(UserValidator)


    UserContractDep = Annotated[UserValidator, Depends(get_user_contract)]
    ```

    ```python
    # shared/wiring/crm.py
    from typing import Annotated
    from fastapi import Depends
    from shared.contract.crm.contacts import Contacts
    from zcore import container


    async def get_contact_contract() -> Contacts:
        return container.resolve(Contacts)


    ContactContractDep = Annotated[Contacts, Depends(get_contact_contract)]
    ```
  </Step>

  <Step>
    ### 3. Implement the Contract in the Upstream Service [#3-implement-the-contract-in-the-upstream-service]

    The upstream service (`UserService` or `ContactService`) implements the business logic matching the protocol:

    ```python
    # modules/crm/service.py
    import uuid
    from zcore import BaseService
    from zcore.exceptions import EntityNotFound
    from .models import Contacts
    from .repository import ContactRepository
    from .schemas import ContactCreate, ContactUpdate


    class ContactService(BaseService[Contacts]):
        def __init__(self, repository: ContactRepository):
            super().__init__(Contacts, repository)

        async def validate_contact(self, id: uuid.UUID | None) -> None:
            if id is not None and not await self.repository.exist(id=id):
                raise EntityNotFound(message="Contact not found.")
    ```
  </Step>

  <Step>
    ### 4. Register the Interface in `Plugin.setup()` [#4-register-the-interface-in-pluginsetup]

    In the upstream module's `Plugin`, bind the protocol to the concrete service in the IoC container:

    ```python
    # modules/crm/plugin.py
    from typing import ClassVar
    from fastapi import FastAPI
    from shared.contract.crm.contacts import Contacts as ContactsProtocol
    from zcore import Plugin, container
    from .service import ContactService


    class CRMPlugin(Plugin):
        name = "crm"
        version = "0.1.0"
        dependencies: ClassVar[list[str]] = []

        def setup(self, app: FastAPI) -> None:
            # Register the abstract protocol to the concrete service
            container.register_scoped(ContactsProtocol, ContactService)
            container.register_scoped(ContactService, ContactService)
    ```
  </Step>

  <Step>
    ### 5. Consume the Contract in Downstream Modules [#5-consume-the-contract-in-downstream-modules]

    The downstream module (`IdentityPlugin` or `DoctorService`) declares the upstream plugin in `dependencies` and injects `ContactContractDep`:

    ```python
    # modules/identity/plugin.py
    from typing import ClassVar
    from fastapi import FastAPI
    from zcore import Plugin


    class IdentityPlugin(Plugin):
        name = "identity"
        version = "0.1.0"
        # Declares that CRM must start and register its contracts first
        dependencies: ClassVar[list[str]] = ["crm"]

        def setup(self, app: FastAPI) -> None:
            ...
    ```

    ```python
    # modules/identity/services.py
    from shared.wiring.crm import ContactContractDep
    from zcore import BaseService
    from .models import Users
    from .repositories import UserRepository
    from .schemas import UserCreate


    class UserService(BaseService[Users]):
        def __init__(
            self,
            repository: UserRepository,
            contact_contract: ContactContractDep,
        ):
            super().__init__(Users, repository)
            self.contact_contract = contact_contract

        async def pre_create(self, schema: UserCreate) -> None:
            # Validates or creates contacts via the contract without direct model imports!
            if schema.contact_id:
                await self.contact_contract.validate_contact(schema.contact_id)
    ```
  </Step>
</Steps>

***

## Decoupled Side-Effects via `EventDispatcher` [#decoupled-side-effects-via-eventdispatcher]

When an action in one module requires side-effects or safety checks across other domains (e.g., preventing contact deletion if linked to a User or Doctor), use `EventDispatcher`:

```python
# 1. Dispatch event in upstream service
class ContactService(BaseService[Contacts]):
    async def pre_delete(self, target: Contacts | Any) -> None:
        contact = target if isinstance(target, Contacts) else await self.get(id=target)
        await self.dispatcher.dispatch(
            "crm.before_contact_delete",
            {"contact_id": contact.id}
        )
```

```python
# 2. Subscribe in downstream plugin
# modules/identity/plugin.py
async def handle_contact_delete_for_users(payload: dict) -> None:
    service = container.resolve(UserService)
    await service.handle_before_contact_delete(payload)


class IdentityPlugin(Plugin):
    async def before_startup(self) -> None:
        dispatcher = container.resolve(EventDispatcher)
        dispatcher.subscribe(
            "crm.before_contact_delete",
            handle_contact_delete_for_users
        )
```

<Callout type="info" emoji="📐">
  **Architectural Rule:**

  * Downstream modules import **Protocols** (`shared/contract/`) and **Wiring** (`shared/wiring/`), never internal models or repositories of upstream modules.
  * The `Kernel` uses `Plugin.dependencies` to guarantee that upstream plugins initialize their IoC bindings before downstreams resolve them.
</Callout>


# How to listen to and dispatch domain events (/docs/how-to/listen-to-events)





ZCore's `EventDispatcher` enables completely decoupled communication between domains. Services can publish domain occurrences, while other services listen and react asynchronously without direct coupling.

<Steps>
  <Step>
    ### 1. Decorate Service Methods with `@on_event` [#1-decorate-service-methods-with-on_event]

    Decorate any asynchronous method in your service with `@on_event("channel_name")`:

    ```python
    # tasks/services.py
    from zcore import BaseService, on_event
    from .models import Task
    from .repositories import TaskRepo

    class TaskService(BaseService[Task]):
        def __init__(self, repo: TaskRepo):
            super().__init__(model=Task, repository=repo)

        @on_event("user.registered")
        async def on_user_registered(self, payload: dict):
            # Automatically creates an onboarding task when a new user registers
            user_id = payload.get("user_id")
            user_email = payload.get("email")
            
            print(f"Creating welcome task for user {user_email} ({user_id})")
            # await self.create(...)
    ```
  </Step>

  <Step>
    ### 2. Register Service Listeners in the Plugin [#2-register-service-listeners-in-the-plugin]

    In your domain's `plugin.py`, resolve the global `EventDispatcher` and register the service class using `register_listeners`:

    ```python
    # tasks/plugin.py
    from fastapi import FastAPI
    from zcore import Plugin, container, EventDispatcher
    from .routers import router_instance
    from .services import TaskService

    class TasksPlugin(Plugin):
        name = "tasks"
        version = "0.1.0"
        dependencies = []

        def setup(self, app: FastAPI) -> None:
            app.include_router(router_instance.router)

            # Register all @on_event listeners on TaskService into the global dispatcher
            dispatcher = container.resolve(EventDispatcher)
            dispatcher.register_listeners(TaskService, container)
    ```

    <Callout type="info" emoji="💡">
      **Dynamic Auto-Wiring:** When an event is dispatched, `EventDispatcher` resolves `TaskService` from the `IoCContainer` dynamically. All dependencies (such as repositories and database sessions) are injected automatically.
    </Callout>
  </Step>

  <Step>
    ### 3. Dispatching Events [#3-dispatching-events]

    You can dispatch events in two ways:

    #### Option A: Post-Commit via `UnitOfWork` (Recommended for DB operations) [#option-a-post-commit-via-unitofwork-recommended-for-db-operations]

    Ensures events only fire **after** the database transaction commits successfully:

    ```python
    async with UnitOfWork(self.repository.db, self.dispatcher) as uow:
        user = await self.repository.create(user_data)
        
        # Buffered in memory and dispatched only after commit succeeds!
        uow.register_event("user.registered", {"user_id": str(user.id), "email": user.email})
    ```

    #### Option B: Direct Dispatching (Immediate) [#option-b-direct-dispatching-immediate]

    For immediate, non-transactional triggers:

    ```python
    from zcore import container, EventDispatcher

    dispatcher = container.resolve(EventDispatcher)
    await dispatcher.dispatch("user.registered", {"user_id": "123", "email": "test@example.com"})
    ```
  </Step>
</Steps>

<Callout type="info" emoji="🛡️">
  **Concurrent & Resilient:** All asynchronous handlers listening to the same event channel execute concurrently via `asyncio.gather`. If one listener raises an error, it is caught and logged without aborting other listeners.
</Callout>


# How to manage Timezones and DateTime serialization (/docs/how-to/manage-timezones)





ZCore provides timezone management built on Python's `zoneinfo` standard library, ensuring consistent UTC storage in databases and formatted timezone-aware outputs for API consumers.

<Steps>
  <Step>
    ### 1. Configure the Application Timezone [#1-configure-the-application-timezone]

    Set your desired IANA timezone in `.env`:

    ```dotenv
    # .env
    TIMEZONE="America/New_York"
    AUTO_CONVERT_TIMEZONE=True
    ```

    Or declare it in your `Settings` subclass:

    ```python
    # config.py
    from zcore.config import Settings

    class AppSettings(Settings):
        TIMEZONE: str = "Europe/London"
        AUTO_CONVERT_TIMEZONE: bool = True
    ```
  </Step>

  <Step>
    ### 2. Using Timezone Utilities in Code [#2-using-timezone-utilities-in-code]

    Import timezone helpers directly from `zcore` or `zcore.utils.timezone`:

    ```python
    from zcore.utils.timezone import now, utc_now, to_app_timezone, format_iso_with_app_timezone

    # Get current datetime in configured application timezone
    local_time = now()

    # Get current datetime in UTC
    utc_time = utc_now()

    # Convert a database datetime (naive or aware) to the application timezone
    converted_time = to_app_timezone(task.created_at)

    # Format datetime as ISO 8601 string with application timezone offset
    iso_string = format_iso_with_app_timezone(task.created_at)
    ```
  </Step>

  <Step>
    ### 3. Automatic Response Formatting with `ZDateTime` [#3-automatic-response-formatting-with-zdatetime]

    Use the `ZDateTime` type annotation in your Pydantic schemas. When the schema is serialized to JSON, it is automatically converted and formatted to the application's timezone:

    ```python
    # schemas.py
    import uuid
    from datetime import datetime
    from zcore import Zchema
    from zcore.utils.timezone import ZDateTime

    class TaskResponse(Zchema):
        __model__ = "tasks"

        id: uuid.UUID
        title: str
        created_at: ZDateTime
        updated_at: ZDateTime | None = None
    ```
  </Step>
</Steps>

<Callout type="info" emoji="🌍">
  **Timezone Fallback:**
  If an invalid or unrecognized timezone string is configured, `get_app_timezone()` logs a warning and automatically falls back to `UTC`.
</Callout>


# How to mask sensitive fields dynamically (/docs/how-to/mask-sensitive-fields)





Instead of maintaining separate Pydantic models for public, user, and admin views (e.g., `TaskPublic`, `TaskAdmin`), ZCore provides dynamic, role-aware projection via `Zchema`.

<Steps>
  <Step>
    ### 1. Bind Schema to a Domain [#1-bind-schema-to-a-domain]

    Inherit from `Zchema` and set the `__model__` class attribute to your domain identifier:

    ```python
    # schemas.py
    import uuid
    from zcore import Zchema
    from pydantic import ConfigDict

    class TaskResponse(Zchema):
        __model__ = "tasks"  # Binds this schema to the 'tasks' domain
        
        id: uuid.UUID
        title: str
        salary: float        # Sensitive field!
        
        model_config = ConfigDict(from_attributes=True)
    ```
  </Step>

  <Step>
    ### 2. Guest-Level Masking with `__private__` [#2-guest-level-masking-with-__private__]

    If certain fields must never be exposed to unauthenticated public visitors (guests), declare them directly in the `__private__` class variable:

    ```python
    # schemas.py
    import uuid
    from zcore import Zchema
    from pydantic import ConfigDict

    class TaskResponse(Zchema):
        __model__ = "tasks"
        __private__ = {"internal_notes", "cost_price"}  # Stripped for unauthenticated visitors

        id: uuid.UUID
        title: str
        salary: float
        cost_price: float = 0.0
        internal_notes: str | None = None

        model_config = ConfigDict(from_attributes=True)
    ```

    When an unauthenticated request hits the endpoint (`ctx.user_id is None`), ZCore automatically purges these fields from response serialization, input validation, and dynamic OpenAPI schema generation without requiring active context lookups.
  </Step>

  <Step>
    ### 3. Set Restrictions in Context [#3-set-restrictions-in-context]

    During your authentication flow (or inside `BaseAuth`), load the active user's restricted paths into `ctx.restricted_fields`:

    ```python
    from zcore import ctx

    # Mask 'salary' specifically on view/GET requests for the 'tasks' domain
    ctx.restricted_fields = ["tasks.view.salary"]
    ```
  </Step>

  <Step>
    ### 4. Automatic Response Pruning [#4-automatic-response-pruning]

    When your endpoint returns a `TaskResponse` model or dictionary, `Zchema` intercepts serialization and removes restricted keys:

    ```json
    // Normal Output (Admin)
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "title": "Build Architecture",
      "salary": 120000.0
    }

    // Filtered Output (Restricted User)
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "title": "Build Architecture"
      // 'salary' is pruned automatically!
    }
    ```
  </Step>
</Steps>

### Restriction Path Syntax [#restriction-path-syntax]

| Pattern                           | Example                   | Effect                                                              |
| --------------------------------- | ------------------------- | ------------------------------------------------------------------- |
| `<domain>.<action>.<field>`       | `tasks.view.salary`       | Prunes `salary` only on `view` (GET) actions.                       |
| `<domain>.<field>`                | `tasks.salary`            | Globally prunes `salary` across all actions (create, update, view). |
| `<domain>.<action>.<nested.path>` | `tasks.view.author.email` | Recursively traverses dicts/lists to prune `email`.                 |
| `<domain>.<action>`               | `tasks.view`              | Masks the entire model representation (`*`).                        |

<Callout type="info" emoji="🛡️">
  **Bidirectional Protection & CDN Safety:**

  * **Input Sanitization (Mass Assignment):** `Zchema` also filters incoming input payloads, silently dropping restricted fields before they reach your database services.
  * **Cache Protection (`Vary` Header):** When fields are pruned, ZCore automatically appends `Vary: Authorization, Cookie` to HTTP response headers to prevent intermediate proxies or CDN caches from serving masked data to authorized users.
</Callout>


# How to mock authenticated users in tests (/docs/how-to/mock-users-in-tests)





When writing integration tests, generating, signing, and refreshing JWT tokens introduces unnecessary test complexity. `ZTestClient` lets you mock user identities, scopes, and context attributes directly.

<Steps>
  <Step>
    ### 1. Mocking Scopes & Permissions [#1-mocking-scopes--permissions]

    Pass `user_id` and the desired `scopes` list to simulate role-based authorization:

    ```python
    # test_permissions.py
    import pytest
    import uuid
    from zcore.testing import ZTestClient
    from main import app

    @pytest.mark.asyncio
    async def test_user_with_view_scope_only():
        user_id = uuid.uuid4()
        
        async with ZTestClient(
            app=app,
            user_id=user_id,
            scopes=["tasks:view"] # User only has read permissions
        ) as client:
            # 1. Allowed: GET /tasks
            get_res = await client.get("/tasks")
            assert get_res.status_code == 200

            # 2. Forbidden: DELETE /tasks/{id} (Requires 'tasks:delete' scope)
            del_res = await client.delete(f"/tasks/{uuid.uuid4()}")
            assert del_res.status_code == 403
    ```
  </Step>

  <Step>
    ### 2. Testing Superuser Privileges [#2-testing-superuser-privileges]

    Set `is_superuser=True` to test permission bypass mechanisms:

    ```python
    @pytest.mark.asyncio
    async def test_superuser_bypasses_all_scopes():
        async with ZTestClient(
            app=app,
            user_id=uuid.uuid4(),
            scopes=[],            # Zero scopes provided
            is_superuser=True     # Superuser flag bypasses checks
        ) as client:
            res = await client.delete(f"/tasks/{uuid.uuid4()}")
            assert res.status_code in [200, 404]  # Did not get blocked by 403 Forbidden
    ```
  </Step>

  <Step>
    ### 3. Custom Attributes and Context Restrictions [#3-custom-attributes-and-context-restrictions]

    Use `extra_user_attrs` to attach domain-specific fields to the mock user, and `extra_context` to test `Zchema` field-masking:

    ```python
    @pytest.mark.asyncio
    async def test_masked_fields_for_restricted_user():
        async with ZTestClient(
            app=app,
            user_id=uuid.uuid4(),
            scopes=["tasks:view"],
            extra_user_attrs={"organization_id": uuid.uuid4(), "department": "Finance"},
            extra_context={"restricted_fields": ["tasks.view.salary"]}
        ) as client:
            res = await client.get("/tasks")
            assert res.status_code == 200
            
            # Assert that Zchema masked the salary field
            for task in res.json()["data"]:
                assert "salary" not in task
    ```
  </Step>

  <Step>
    ### 4. Typed Pydantic User Models & Guest Requests [#4-typed-pydantic-user-models--guest-requests]

    Instead of relying on a generic mock object, pass your authentic Pydantic user schema via `user_model`. This ensures endpoint dependencies receive a properly validated model instance:

    ```python
    from auth import AppUser

    @pytest.mark.asyncio
    async def test_with_typed_user_model():
        user_id = uuid.uuid4()

        async with ZTestClient(
            app=app,
            user_id=user_id,
            user_model=AppUser,
            extra_user_attrs={"department": "Engineering"}
        ) as client:
            res = await client.get("/tasks")
            assert res.status_code == 200
    ```

    To test public or guest-facing endpoints, simply omit `user_id` (or pass `user_id=None`). This exercises unauthenticated execution paths and validates optional authentication stubs (`get_optional_user_stub`).
  </Step>
</Steps>

<Callout type="info" emoji="🎭">
  **Dual Context & Dependency Injection:**
  When `user_id` is supplied, `ZTestClient` simultaneously:

  1. Overrides `get_current_user_stub` and `get_optional_user_stub` (along with any custom `user_dependency` targets) with an authentic Pydantic model (if `user_model` is provided) or a compliant mock object conforming to `UserProtocol`.
  2. Binds `user_id`, `scopes`, and `extra_context` directly to the request-scoped `ZContext` (`ctx`).
</Callout>


# How to override BaseRepository methods (/docs/how-to/override-repository)





`BaseRepository` provides built-in CRUD operations out of the box. You can override any default method or add completely custom database queries.

<Steps>
  <Step>
    ### 1. Overriding a Built-In CRUD Method [#1-overriding-a-built-in-crud-method]

    To customize how entities are persisted or apply low-level database transformations, override the method and invoke `super()`:

    ```python
    # repositories.py
    import uuid
    from sqlalchemy.ext.asyncio import AsyncSession
    from zcore import BaseRepository
    from .models import Task
    from .schemas import TaskCreate

    class TaskRepo(BaseRepository[Task]):
        def __init__(self, db: AsyncSession):
            super().__init__(model=Task, db=db)

        async def create(self, schema: TaskCreate, **extra_data) -> Task:
            # Low-level persistence logic (e.g., injecting DB-level generated attributes)
            extra_data["internal_reference"] = f"REF-{uuid.uuid4().hex[:8].upper()}"
                
            # Execute standard parent insert and flush logic
            return await super().create(schema, **extra_data)
    ```
  </Step>

  <Step>
    ### 2. Adding Custom Queries with `self.db` [#2-adding-custom-queries-with-selfdb]

    You have direct, unrestricted access to `self.db` (the active `AsyncSession`). You can write standard SQLAlchemy 2.0 select statements, joins, aggregations, or raw SQL:

    ```python
    from sqlalchemy import select, func

    class TaskRepo(BaseRepository[Task]):
        def __init__(self, db: AsyncSession):
            super().__init__(model=Task, db=db)

        async def get_completed_tasks_count(self) -> int:
            """Custom query counting all completed tasks."""
            query = select(func.count(self.pk)).where(self.model.is_completed.is_(True))
            result = await self.db.execute(query)
            return result.scalar_one()
    ```
  </Step>
</Steps>

<Callout type="warn" emoji="📐">
  **Clean Architecture Note:**
  Keep **business validation** (e.g., checking input rules or user permissions) inside your `BaseService` (using hooks like `pre_create`). The repository layer should strictly focus on **data access and database persistence**.
</Callout>

<Callout type="info" emoji="💡">
  **Why `AsyncSession` instead of `SessionDep`?**
  Use `AsyncSession` type hints in your repositories. ZCore's IoC container auto-wires the request-scoped session directly. `SessionDep` is intended strictly for FastAPI route handler endpoints.
</Callout>


# How to register Singleton vs Scoped services (/docs/how-to/register-singleton-vs-scoped)





ZCore's `IoCContainer` manages three distinct dependency lifecycles to balance performance and thread/request isolation.

### Supported Lifecycles [#supported-lifecycles]

<Steps>
  <Step>
    ### 1. Singleton (Application-Wide) [#1-singleton-application-wide]

    Instantiated once and shared across the entire lifespan of the application.

    ```python
    from zcore.kernel.di import container

    # Pass the interface and the pre-constructed instance
    container.register_singleton(RedisClient, RedisClient())
    ```

    * **Best for:** External client pools (Redis, S3/MinIO), shared configuration objects, or resource-heavy factories.
  </Step>

  <Step>
    ### 2. Scoped (Request-Wide) [#2-scoped-request-wide]

    Resolved once per HTTP request context (`scope_id`) and cached for the duration of that request. It is automatically purged when the connection closes.

    ```python
    # Register an implementation to be resolved per request scope
    container.register_scoped(IUnitOfWork, UnitOfWork)

    # Or register a pre-constructed instance into the active scope (used by middlewares)
    container.register_scoped_instance(AsyncSession, db_session)
    ```

    * **Best for:** Database sessions, user context objects, transaction units.
  </Step>

  <Step>
    ### 3. Transient (Always Instantiated) [#3-transient-always-instantiated]

    A completely new instance is created on every resolution request.

    ```python
    container.register_transient(PdfReportGenerator, PdfReportGenerator)
    ```

    * **Best for:** Stateless helper classes, dynamic template compilers, lightweight utilities.
  </Step>
</Steps>

<Callout type="info" emoji="💡">
  **Automatic Auto-Wiring:**
  You **do not** need to manually register your `BaseRepository` or `BaseService` subclasses. ZCore's IoC container automatically auto-wires them on the fly and binds them to the active request-scoped `AsyncSession` managed by `ScopedDependencyMiddleware`.
</Callout>


# How to run isolated background tasks (/docs/how-to/run-background-tasks)





In standard FastAPI applications, running background tasks that access database sessions or request-scoped dependencies often causes `Session is closed` errors. ZCore provides `@background_task` and `background_scope` to solve this seamlessly.

<Steps>
  <Step>
    ### 1. Using `@background_task` with Auto-Wiring [#1-using-background_task-with-auto-wiring]

    Decorate your task with `@background_task`. Any type-annotated parameter that you don't explicitly pass when calling the function will be **automatically resolved from the IoC container**:

    ```python
    # tasks/tasks.py
    import uuid
    from zcore import background_task
    from .services import TaskService

    @background_task
    async def process_task_analytics(
        task_id: uuid.UUID,
        service: TaskService  # <--- Auto-injected from IoC container!
    ):
        # Operates in its own dedicated AsyncSession & IoC scope
        await service.recalculate_metrics(task_id)
    ```

    <Callout type="info" emoji="💡">
      **Both Sync & Async Supported:** If your task is synchronous (`def`), `@background_task` automatically runs it in a non-blocking worker thread using `anyio.to_thread.run_sync`.
    </Callout>
  </Step>

  <Step>
    ### 2. Scheduling with FastAPI `BackgroundTasks` [#2-scheduling-with-fastapi-backgroundtasks]

    Inject FastAPI's standard `BackgroundTasks` into your router and schedule the decorated task. You only need to pass the arguments that cannot be auto-wired (like `task_id`):

    ```python
    # tasks/routers.py
    import uuid
    from fastapi import APIRouter, BackgroundTasks
    from .tasks import process_task_analytics

    router = APIRouter(prefix="/tasks", tags=["Tasks"])

    @router.post("/{id}/process")
    async def trigger_task_processing(
        id: uuid.UUID,
        background_tasks: BackgroundTasks
    ):
        # Pass only the explicit arguments
        background_tasks.add_task(process_task_analytics, task_id=id)
        
        return {"message": "Task processing queued in background"}
    ```
  </Step>

  <Step>
    ### 3. Manual Scoping with `background_scope` [#3-manual-scoping-with-background_scope]

    If you prefer explicit context manager blocks instead of decorators, use `background_scope()` directly:

    ```python
    from zcore.kernel import background_scope, container
    from sqlalchemy.ext.asyncio import AsyncSession
    from tasks.services import TaskService

    async def custom_background_worker(user_id: uuid.UUID):
        # Creates an isolated IoC scope & independent database transaction
        async with background_scope(inherit_context=True):
            service = container.resolve(TaskService)
            await service.send_digest(user_id)
    ```
  </Step>
</Steps>

<Callout type="warn" emoji="🔒">
  **Context Inheritance & Session Safety:**

  * By default, `inherit_context=True` clones the active user context (`user_id`, `scopes`, etc.) into the background task, allowing role-based operations and audit trails to persist even after the HTTP connection has closed.
  * Do not pass active HTTP request sessions (`AsyncSession`) as arguments to background tasks. `@background_task` automatically detects this and logs a warning, encouraging you to let the decorator provision a dedicated, isolated session safely.
</Callout>

<Callout type="info" emoji="🪵">
  **Structured Log Correlation (`task_id`):**
  Every execution wrapped with `@background_task` or `background_scope` automatically generates and binds an isolated `task_id` UUID to `structlog` contextvars. This allows you to filter and trace all log events originating from a specific background job execution cleanly.
</Callout>


# How to test API endpoints (/docs/how-to/test-endpoints)





Testing layered architectures often requires mocking database connections, overriding dependencies, and cleaning up test records. ZCore's `ZTestClient` automates this entire pipeline using transactions with savepoints and container sandboxing.

<Steps>
  <Step>
    ### 1. Initializing Test Database Schemas [#1-initializing-test-database-schemas]

    Before executing your test suite, use `setup_test_database` in your `conftest.py` to ensure test tables are created cleanly across synchronous or asynchronous test runners:

    ```python
    # conftest.py
    import pytest
    from zcore.testing import setup_test_database

    @pytest.fixture(scope="session", autouse=True)
    def initialize_test_db():
        setup_test_database(drop_first=True)
    ```
  </Step>

  <Step>
    ### 2. Basic Endpoint Test with Database Rollback [#2-basic-endpoint-test-with-database-rollback]

    By default (`use_db=True`), any database mutations performed during the test are rolled back on exit:

    ```python
    # test_tasks.py
    import pytest
    from zcore.testing import ZTestClient
    from main import app

    @pytest.mark.asyncio
    async def test_create_and_get_tasks():
        async with ZTestClient(app=app) as client:
            # 1. Create a task
            create_res = await client.post("/tasks", json={"title": "Test Task"})
            assert create_res.status_code == 201
            task_id = create_res.json()["data"]["id"]

            # 2. Fetch the created task
            get_res = await client.get(f"/tasks/{task_id}")
            assert get_res.status_code == 200
            assert get_res.json()["data"]["title"] == "Test Task"
            
        # The database transaction is automatically rolled back here!
    ```
  </Step>

  <Step>
    ### 3. Testing Authenticated Routes & Permissions [#3-testing-authenticated-routes--permissions]

    Pass `user_id`, `scopes`, and `is_superuser` to simulate authenticated requests without generating real JWT tokens:

    ```python
    import uuid

    @pytest.mark.asyncio
    async def test_admin_delete_operation():
        admin_id = uuid.uuid4()
        
        async with ZTestClient(
            app=app,
            user_id=admin_id,
            scopes=["tasks:delete", "admin:all"],
            is_superuser=True,
            extra_context={"restricted_fields": []}
        ) as client:
            response = await client.delete(f"/tasks/{uuid.uuid4()}")
            # Validates that HasScopes dependency allows execution
            assert response.status_code in [200, 404]
    ```
  </Step>

  <Step>
    ### 4. Class-Based Testing with `BaseZTest` [#4-class-based-testing-with-baseztest]

    For test suites sharing identical user attributes and configuration, inherit from `BaseZTest`:

    ```python
    from zcore.testing import BaseZTest
    from main import app

    class TestTaskSuite(BaseZTest):
        app = app
        scopes = ["tasks:view", "tasks:create"]
        extra_user_attrs = {"department": "Engineering"}

        @pytest.mark.asyncio
        async def test_suite_operation(self):
            async with self.run() as client:
                res = await client.get("/tasks")
                assert res.status_code == 200
    ```
  </Step>
</Steps>

<Callout type="info" emoji="🧪">
  **Behind the Scenes Orchestration:**

  * **Database Savepoints:** Connects to the engine, opens a transaction with `create_savepoint`, and binds it to `db_manager.session`. It rolls back instantly on exit without dropping or truncating tables.
  * **IoC Container Sandboxing:** Backs up singletons, scoped instances, and factories before each test, completely preventing test pollution.
  * **Event Dispatcher Sandboxing:** Automatically snapshots and restores registered event subscribers so test-specific event listeners never leak across test cases.
  * **Application Lifespan:** Automatically executes plugin `before_startup`, `on_startup`, and `on_shutdown` hooks.
</Callout>


# How to securely upload files (/docs/how-to/upload-files-securely)





File uploads are high-risk entry points. ZCore's `LocalStorageProvider` defends your server against Path Traversal, Denial of Service (large files), and executable masquerading (e.g., PHP scripts or `.exe` binaries disguised as `.jpg`).

<Steps>
  <Step>
    ### 1. Configure the Storage Provider [#1-configure-the-storage-provider]

    Initialize `LocalStorageProvider` with your security validators and register it in the IoC container:

    ```python
    # main.py or storage_config.py
    from zcore.storage import (
        LocalStorageProvider,
        SafeMimeTypeValidator,
        MaxFileSizeValidator,
        FileExtensionValidator,
        StorageProvider
    )
    from zcore.kernel.di import container

    storage = LocalStorageProvider(
        base_path="./storage/uploads",
        url_prefix="/storage",
        validators=[
            # 1. Enforce strict 5 MB file size limit
            MaxFileSizeValidator(max_size_mb=5),
            
            # 2. Check file extension
            FileExtensionValidator(allowed_extensions=[".png", ".jpg", ".jpeg", ".webp", ".pdf"]),
            
            # 3. Inspect binary Magic Bytes and scan against disguised scripts/XSS
            SafeMimeTypeValidator(allowed_mimes=["image/png", "image/jpeg", "image/webp", "application/pdf"])
        ]
    )

    # Register as the active storage provider singleton
    container.register_singleton(StorageProvider, storage)
    ```
  </Step>

  <Step>
    ### 2. Create the Upload Endpoint [#2-create-the-upload-endpoint]

    Inject `StorageProvider` into your FastAPI route and upload the `UploadFile` payload:

    ```python
    # routers.py
    from fastapi import APIRouter, UploadFile, File
    from zcore import Inject
    from zcore.storage import StorageProvider

    router = APIRouter(prefix="/media", tags=["Media"])

    @router.post("/avatar")
    async def upload_avatar(
        file: UploadFile = File(...),
        storage: Inject[StorageProvider] = None
    ):
        # Saves to ./storage/uploads/avatars/ with collision-free UUID filename
        # Returns normalized web URL: "/storage/avatars/a3b8...png"
        web_url = await storage.upload(file, folder="avatars")
        return {"url": web_url}
    ```

    <Callout type="info" emoji="🌐">
      **Web URL Resolution:** Both `upload()` and `upload_stream()` save the file securely and immediately return the normalized, web-accessible public path (e.g., `/storage/avatars/5f8c41...png`) ready to be persisted into your database or sent back to clients.
    </Callout>
  </Step>

  <Step>
    ### 3. Secure File Deletion [#3-secure-file-deletion]

    Delete stored assets safely. ZCore accepts either the web URL or relative path, verifies that the target resides strictly inside `base_path`, and prevents sandbox traversal:

    ```python
    @router.delete("/avatar")
    async def delete_avatar(
        url: str,
        storage: Inject[StorageProvider]
    ):
        # Accepts "/storage/avatars/5f8c41...png" or relative paths
        success = await storage.delete(url)
        return {"deleted": success}
    ```
  </Step>
</Steps>

<Callout type="info" emoji="🛡️">
  **Triple-Layer Security Architecture:**

  * **Magic Bytes & Script Inspection:** Reads the initial 8192 header bytes against known binary signatures and scans against PHP execution tags (`<?php`), HTML scripts (`<script`), event handlers (`onerror=`), Unix shebangs (`#!/`), and Windows PE headers (`MZ`).
  * **Path Traversal Defense:** `upload()`, `upload_stream()`, and `delete()` resolve system paths strictly and assert `.is_relative_to(base)`. Any directory breakout attempt (e.g., `../../etc/passwd`) is safely blocked.
  * **Collision-Free Naming:** Uploaded files are automatically renamed with high-entropy randomized UUIDs (`uuid4().hex + ext`) to prevent filesystem overwrites and preserve privacy.
</Callout>


# How to use CLI commands (/docs/how-to/use-cli-commands)





The `zc` CLI tool accelerates your entire development lifecycle — from interactive multi-database bootstrapping and 7-layer domain scaffolding to cryptographically secure secret generation and cascading server orchestration with transparent Uvicorn argument forwarding.

***

### Command Overview [#command-overview]

| Command              | Purpose                                                                 | Flags / Options                                                                                                                                                          |
| -------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `zc`                 | Launches the interactive dashboard with auto-detected project context.  | —                                                                                                                                                                        |
| `zc init [name]`     | Scaffolds a full ZCore project with driver selection and `.venv` setup. | `--db [sqlite\|postgres\|mysql]`<br />`-y, --yes` (Use defaults)                                                                                                         |
| `zc startapp [name]` | Generates a 7-layer modular domain module / plugin.                     | `--template / --no-template`<br />`--test / --no-test`<br />`-y, --yes` (All layers)                                                                                     |
| `zc run [app]`       | Launches the development/production server with cascading config.       | `--host <ip>`<br />`--port <port>`<br />`--reload / --no-reload`<br />`--workers <n>`<br />`--log-level <level>`<br />`--env-file <path>`<br />`[extra uvicorn args...]` |
| `zc gensecret`       | Generates a 64-character cryptographically secure `SECRET_KEY`.         | —                                                                                                                                                                        |
| `zc genenv`          | Introspects the `Settings` class and exports an `.env.example` schema.  | `-o, --output` (Default: `.env.example`)<br />`-f, --force` (Overwrite)                                                                                                  |
| `zc --version`       | Displays the active ZCore Framework version.                            | —                                                                                                                                                                        |

***

<Steps>
  <Step>
    ### 1. Interactive Dashboard (`zc`) [#1-interactive-dashboard-zc]

    Running `zc` with no arguments opens the interactive terminal dashboard powered by **Rich** and **Questionary**. It automatically detects whether you are inside an active ZCore project or managing a multi-project workspace:

    ```bash
    zc
    ```

    ```text
    ⚡ ZCore Framework v0.1.0-rc.2 • Modern Modular Monolith
       FastAPI • SQLAlchemy 2.0 • Pydantic V2

      Context: Active Project (core_api)

    ? What framework task would you like to perform?
    ❯ 🧩  startapp   — Scaffold a modular domain app / plugin
      ⚡  run        — Launch Uvicorn development server
      📋  genenv     — Generate template .env from Settings class
      🔑  gensecret  — Generate cryptographically secure SECRET_KEY
      📦  init       — Scaffold another ZCore project
      🚪  exit       — Exit CLI
    ```
  </Step>

  <Step>
    ### 2. Initializing a New Project (`zc init`) [#2-initializing-a-new-project-zc-init]

    Create a complete project structure with automated database driver configuration and isolated virtual environment setup:

    #### Interactive Mode: [#interactive-mode]

    ```bash
    zc init my_project
    ```

    You will be prompted to choose:

    * **Primary Database Driver:** SQLite (`aiosqlite`), PostgreSQL (`asyncpg`), or MySQL (`aiomysql`).
    * **Virtual Environment & Dependencies:** Automatically create `.venv` and install packages using `uv` (ultra-fast) or `pip`.

    #### Non-Interactive (CI/CD or Quick Scripts): [#non-interactive-cicd-or-quick-scripts]

    ```bash
    # Scaffold with PostgreSQL driver without prompts
    zc init my_project --db postgres -y
    ```

    #### Generated Project Tree: [#generated-project-tree]

    ```text
    📁 my_project/
    ├── 📄 main.py            # FastAPI lifespan, kernel setup, and middleware stack
    ├── 📄 .env               # Pre-configured DATABASE_URL and fresh SECRET_KEY
    ├── 📄 requirements.txt   # Core framework + selected async database driver
    ├── 📄 .gitignore         # Comprehensive Python and environment ignore rules
    └── 📦 .venv/             # Optional isolated virtual environment
    ```
  </Step>

  <Step>
    ### 3. Scaffolding Modular Domain Apps (`zc startapp`) [#3-scaffolding-modular-domain-apps-zc-startapp]

    ZCore promotes a **Modular Monolith** architecture where each business domain is an isolated plugin folder containing up to 7 architectural layers:

    #### Interactive Mode: [#interactive-mode-1]

    ```bash
    zc startapp order_management
    ```

    You can choose between:

    1. **Full Boilerplate:** Generates ready-to-use template code for all selected layers.
    2. **Clean / Blank:** Generates clean, empty files for all selected layers.
    3. **Custom / Mixed:** Granularly select which layers get boilerplate templates and which stay blank.

    #### Non-Interactive Mode: [#non-interactive-mode]

    ```bash
    # Generate all layers with boilerplate and tests
    zc startapp order_management -y

    # Scaffold without boilerplate templates
    zc startapp order_management --no-template
    ```

    #### Generated Domain Module: [#generated-domain-module]

    ```text
    📁 order_management/
    ├── 📄 __init__.py
    ├── 📄 models.py                 # SQLAlchemy 2.0 mapped model with UUID PK
    ├── 📄 schemas.py                # Zchema Pydantic V2 schemas (Base, Create, Update, Response)
    ├── 📄 repositories.py           # BaseRepository subclass with full async CRUD and soft-delete/restore
    ├── 📄 services.py               # BaseService subclass with pre/post execution hooks
    ├── 📄 routers.py                # BaseRouter scaffold exposing 8 RESTful & lookup endpoints
    ├── 📄 plugin.py                 # Modular Plugin lifecycle class for Kernel registration
    └── 📄 test_order_management.py  # Pytest async test suite using ZTestClient
    ```
  </Step>

  <Step>
    ### 4. Running the Server (`zc run`) [#4-running-the-server-zc-run]

    Launch the server with cascading configuration resolution (**CLI Arguments > `.env` File > Defaults**) and transparent Uvicorn argument forwarding:

    #### Basic Execution (Reads `.env`): [#basic-execution-reads-env]

    ```bash
    zc run
    ```

    #### Advanced Parameter Overrides: [#advanced-parameter-overrides]

    ```bash
    # Custom host, port, and disabled reload
    zc run --host 0.0.0.0 --port 8080 --no-reload

    # Multi-worker production setup (automatically disables --reload)
    zc run --workers 4 --log-level warning

    # Custom entrypoint and custom env file
    zc run app.api:app --env-file .env.production
    ```

    #### Transparent Uvicorn Passthrough: [#transparent-uvicorn-passthrough]

    Any unrecognized flags passed to `zc run` are forwarded directly to the underlying Uvicorn process:

    ```bash
    zc run --proxy-headers --forwarded-allow-ips="*" --timeout-keep-alive 30
    ```

    <Callout type="info" emoji="⚙️">
      **Cascading Precedence:**
      `zc run` checks `.env` for keys like `APP_MODULE`, `UVICORN_APP`, `HOST`, `PORT`, `RELOAD`, `WORKERS`, and `LOG_LEVEL`. Explicit CLI arguments take highest priority, followed by `.env` variables, falling back to safe defaults (`127.0.0.1:8000`).
    </Callout>
  </Step>

  <Step>
    ### 5. Managing Secrets and Environment Schemas [#5-managing-secrets-and-environment-schemas]

    #### Generate a Cryptographic Secret: [#generate-a-cryptographic-secret]

    ```bash
    zc gensecret
    ```

    Outputs a secure 64-character hexadecimal key (using `secrets.token_hex(32)`) ready for your production `.env` under `SECRET_KEY`.

    #### Generate `.env.example` from Pydantic Settings: [#generate-envexample-from-pydantic-settings]

    ```bash
    zc genenv -o .env.example -f
    ```

    Introspects your registered `Settings` class (including all custom subclassed fields and defaults) and writes a synchronized `.env.example` template.
  </Step>
</Steps>

<Callout type="warn" emoji="🔐">
  **Security Best Practice:**
  Always run `zc genenv` and commit the generated `.env.example` to version control. &#x2A;*Never commit actual `.env` files.** Keep real secrets in environment variables or your secure production vault.
</Callout>


# How to use pre/post hooks in Services (/docs/how-to/use-pre-post-hooks)





ZCore's `BaseService` divides database operations into three structured layers: **Pre-hooks** (intercept/merge payload), **On-methods** (core repository execution), and **Post-hooks** (side-effects, external notifications & cleanup).

<Steps>
  <Step>
    ### 1. Using `pre_*` and `post_*` Hooks [#1-using-pre_-and-post_-hooks]

    Return a `dict` from any `pre_*` mutation hook to automatically merge that data into the database payload:

    ```python
    # services.py
    from typing import Any
    from zcore import BaseService
    from zcore.utils.helpers import slugify
    from .models import Task
    from .schemas import TaskCreate, TaskUpdate
    from .repositories import TaskRepo

    class TaskService(BaseService[Task]):
        def __init__(self, repo: TaskRepo):
            super().__init__(model=Task, repository=repo)
        
        async def pre_create(self, schema: TaskCreate) -> dict[str, Any] | None:
            # Merges automatically into the insert payload
            return {"slug": slugify(schema.title)}

        async def post_delete(self, model: Task, force: bool = False) -> None:
            # Executes after deletion (e.g., delete files from storage if hard-deleted)
            if force and getattr(model, "file_path", None):
                # await storage.delete(model.file_path)
                pass

        async def post_restore(self, model: Task) -> None:
            # Executes after a soft-deleted task is successfully restored
            # logger.info(f"Task {model.id} restored")
            pass
    ```
  </Step>

  <Step>
    ### 2. Overriding Core Execution (`on_*` Methods) [#2-overriding-core-execution-on_-methods]

    If you need to change **how** an entity is persisted in the repository (e.g., routing to a custom repository method or decorating execution), override the `on_*` methods directly:

    ```python
    class TaskService(BaseService[Task]):
        def __init__(self, repo: TaskRepo):
            super().__init__(model=Task, repository=repo)

        async def on_create(self, schema: TaskCreate, **extra_data) -> Task:
            # Custom persistence delegation (surrounded safely by pre_create and post_create)
            return await self.repository.create(schema, **extra_data)
            
        async def on_delete(self, target: Task | Any, force: bool = False) -> Task | None:
            # Core delete delegation (delegates soft vs hard delete to repository)
            return await self.repository.delete(target, force=force)
    ```
  </Step>

  <Step>
    ### 3. Complete Lifecycle Hook Reference [#3-complete-lifecycle-hook-reference]

    | Hook                                     | Category         | Return Type       | Purpose / Description                                         |
    | ---------------------------------------- | ---------------- | ----------------- | ------------------------------------------------------------- |
    | `post_get(model)`                        | Read (Single)    | `Model`           | Modify or append computed runtime fields after fetching.      |
    | `post_get_multi(models)`                 | Read (Batch)     | `Sequence[Model]` | Intercept and process a batch list of retrieved entities.     |
    | `pre_create(schema)`                     | Create (Single)  | `dict \| None`    | Compute/merge data (e.g., slugs, hashes) before insert.       |
    | `post_create(model)`                     | Create (Single)  | `None`            | Trigger post-insert events (e.g., send emails, webhooks).     |
    | `pre_create_multi(schemas)`              | Create (Batch)   | `None`            | Pre-validation check before inserting multiple records.       |
    | `post_create_multi(models)`              | Create (Batch)   | `None`            | Run notifications or logging after bulk insertions.           |
    | `pre_update(target, schema, partial)`    | Update (Single)  | `dict \| None`    | Compute/merge data into the update payload.                   |
    | `post_update(model)`                     | Update (Single)  | `None`            | Clear cache keys or log modification audit trails.            |
    | `pre_update_multi(data, partial)`        | Update (Batch)   | `None`            | Intercept batch dictionary updates before execution.          |
    | `post_update_multi(models)`              | Update (Batch)   | `None`            | Perform side-effects after bulk updates finish.               |
    | `pre_delete(id, force=False)`            | Delete (Single)  | `None`            | Verify dependencies or cascade rules before row removal.      |
    | `post_delete(model, force=False)`        | Delete (Single)  | `None`            | Purge associated files from storage after deletion.           |
    | `pre_delete_multi(ids, force=False)`     | Delete (Batch)   | `None`            | Validate or check permissions for a list of target IDs.       |
    | `post_delete_multi(models, force=False)` | Delete (Batch)   | `None`            | Batch cleanup of external resources after deletions.          |
    | `pre_restore(id)`                        | Restore (Single) | `None`            | Pre-validation checks before restoring a soft-deleted record. |
    | `post_restore(model)`                    | Restore (Single) | `None`            | Trigger side-effects or logging after a record is restored.   |
    | `pre_restore_multi(ids)`                 | Restore (Batch)  | `None`            | Validate or check permissions before restoring batch records. |
    | `post_restore_multi(models)`             | Restore (Batch)  | `None`            | Run notifications or audit logs after batch restorations.     |
    | `pre_search(search_in)`                  | Search           | `None`            | Inspect or mutate `SearchRequest` filters dynamically.        |
    | `post_search(models)`                    | Search           | `None`            | Post-process or enrich dynamic search query results.          |
  </Step>
</Steps>

<Callout type="info" emoji="🔒">
  **Atomic Transaction Safety:**
  All `pre_*`, `on_*`, and `post_*` operations execute within the active transaction before `_safe_commit()` is invoked. If any hook raises an error, the entire operation is automatically rolled back.
</Callout>


# How to enforce multi-tenancy & soft deletion (/docs/how-to/use-scope-query)





Writing manual `WHERE tenant_id == ...` or `WHERE deleted_at IS NULL` clauses on every single database query is error-prone and risks catastrophic data leaks.

ZCore solves this at the architectural root:

1. **`SoftDeleteMixin`:** Provides out-of-the-box timestamp-based soft deletion with automatic query filtering, `soft_delete()`, `restore()`, and atomic batch recovery helpers.
2. **`scope_query`:** `BaseRepository` automatically inspects models for a `@classmethod` named `scope_query` before executing *any* read, listing, count, or dynamic search query.

***

<Steps>
  <Step>
    ### 1. Built-in Soft Deletion (`SoftDeleteMixin`) [#1-built-in-soft-deletion-softdeletemixin]

    To add soft-delete capabilities to any model, simply inherit from `SoftDeleteMixin`:

    ```python
    # tasks/models.py
    import uuid
    from sqlalchemy.orm import Mapped, mapped_column
    from sqlalchemy import String
    from zcore import Base, SoftDeleteMixin

    class Task(Base, SoftDeleteMixin):
        __tablename__ = "tasks"

        id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
        title: Mapped[str] = mapped_column(String(255))
    ```

    `SoftDeleteMixin` automatically injects:

    * `deleted_at: Mapped[datetime | None]` (indexed timezone-aware timestamp, nullable).
    * `task.is_deleted` property (evaluates whether `deleted_at` is set).
    * `task.soft_delete()` (sets `deleted_at = now()`).
    * `task.restore()` (resets `deleted_at = None`).
    * Automatic `scope_query` filtering `WHERE deleted_at IS NULL` for all repository queries.
  </Step>

  <Step>
    ### 2. Combining Soft Deletion with Multi-Tenancy [#2-combining-soft-deletion-with-multi-tenancy]

    If your model requires both soft-delete filtering **and** tenant isolation, override `scope_query` and chain it with `super().scope_query(query)`:

    ```python
    # tasks/models.py
    import uuid
    from sqlalchemy import String, Select
    from sqlalchemy.orm import Mapped, mapped_column
    from zcore import Base, SoftDeleteMixin, ctx

    class Task(Base, SoftDeleteMixin):
        __tablename__ = "tasks"

        id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
        title: Mapped[str] = mapped_column(String(255))
        tenant_id: Mapped[str] = mapped_column(String(64), index=True)

        @classmethod
        def scope_query(cls, query: Select) -> Select:
            # 1. Apply base soft-delete filter (deleted_at IS NULL)
            query = super().scope_query(query)

            # 2. Enforce Multi-Tenant isolation from active request context
            active_tenant = ctx.get("tenant_id")
            if active_tenant:
                query = query.where(cls.tenant_id == active_tenant)

            return query
    ```
  </Step>

  <Step>
    ### 3. Setting Context in Auth / Middleware [#3-setting-context-in-auth--middleware]

    Set the tenant identifier in `ZContext` (`ctx`) during authentication or inside your authentication dependency:

    ```python
    # Inside your BaseAuth or dependency provider
    from zcore import ctx

    # Binds the active organization/tenant to the current coroutine context
    ctx.set("tenant_id", "org_enterprise_99")
    ```
  </Step>

  <Step>
    ### 4. Automatic Repository Protection [#4-automatic-repository-protection]

    Once defined, **every** operation executed by `BaseRepository` and `BaseRouter` respects your scoping rules automatically with zero extra code:

    ```python
    # Standard repository calls:
    task = await task_repo.get(id=task_id)          # Automatically filtered: non-deleted & matching tenant
    all_tasks = await task_repo.get_list()          # Returns only active tenant records
    count = await task_repo.count()                 # Counts only active tenant records
    search = await task_repo.search(search_request) # Dynamic search applies tenant & soft-delete filter
    ```
  </Step>

  <Step>
    ### 5. Soft-Deleting, Restoring, and Forced Deletions [#5-soft-deleting-restoring-and-forced-deletions]

    In addition to instance-level methods, `BaseRepository` and `BaseService` provide high-level, atomic operations:

    ```python
    # 1. Soft-delete a record (or list of records) via repository
    await task_repo.delete(task_id)                        # Automatic soft-delete
    await task_repo.delete_multi([task_id_1, task_id_2])   # Batch atomic soft-delete

    # 2. Force permanent physical deletion (Hard Delete)
    await task_repo.delete(task_id, force=True)
    await task_repo.delete_multi([task_id_1, task_id_2], force=True)

    # 3. Restore soft-deleted records
    restored_task = await task_repo.restore(task_id)       # Single restoration
    restored_list = await task_repo.restore_multi(         # Atomic batch restoration
        [task_id_1, task_id_2]
    )

    # 4. Instance-level mutation fallback
    task = await task_repo.get(id=task_id)
    task.soft_delete()
    await db.flush()
    ```
  </Step>
</Steps>

<Callout type="info" emoji="🛡️">
  **Comprehensive Operation Coverage:**
  `scope_query` is executed inside `_get_base_query()` and automatically wraps all repository operations: `get()`, `get_by_ids()`, `get_list()`, `exist()`, `count()`, and `search()`.
</Callout>

<Callout type="warn" emoji="⚡">
  **Bypassing Scoping for Superadmins & Audits:**
  If a background worker or superadmin needs to query across all tenants or include soft-deleted records:

  ```python
  @classmethod
  def scope_query(cls, query: Select) -> Select:
      if ctx.get("is_superuser"):
          return query # Unfiltered access for audits/superadmins
          
      query = super().scope_query(query)
      tenant = ctx.get("tenant_id")
      return query.where(cls.tenant_id == tenant) if tenant else query
  ```
</Callout>


# How to use UnitOfWork for atomic transactions (/docs/how-to/use-unit-of-work)





When multiple services or repositories must modify the database within a single transaction, instantiate a `UnitOfWork` block to guarantee atomicity.

<Steps>
  <Step>
    ### 1. Instantiate `UnitOfWork` Inside the Service Method [#1-instantiate-unitofwork-inside-the-service-method]

    Inject the system `EventDispatcher` and your repositories into the service constructor. Then, wrap multi-step database mutations inside `async with UnitOfWork(...)`:

    ```python
    # services.py
    from zcore import BaseService, UnitOfWork, EventDispatcher
    from .models import Order
    from .repositories import OrderRepo, InventoryRepo
    from .schemas import OrderCreate

    class CheckoutService(BaseService[Order]):
        def __init__(
            self, 
            repository: OrderRepo,
            inventory_repo: InventoryRepo,
            dispatcher: EventDispatcher
        ):
            super().__init__(model=Order, repository=repository)
            self.inventory_repo = inventory_repo
            self.dispatcher = dispatcher

        async def process_checkout(self, order_data: OrderCreate, product_id: str, quantity: int):
            # 1. Open an isolated transaction boundary using the active session and dispatcher
            async with UnitOfWork(self.repository.db, self.dispatcher) as uow:
                # Both operations share the exact same database transaction
                order = await self.repository.create(order_data)
                await self.inventory_repo.decrement_stock(product_id, quantity)

                # 2. Buffer domain events to dispatch ONLY after successful commit
                uow.register_event("order.completed", {"order_id": str(order.id)})
                
            # If any step fails, BOTH operations roll back and the event is never dispatched.
    ```
  </Step>

  <Step>
    ### 2. Nested & Re-entrant Transactions [#2-nested--re-entrant-transactions]

    In modular applications, domain services frequently invoke one another (e.g. `CheckoutService` calling an `InventoryService`). Each service can safely wrap its persistence operations within `async with UnitOfWork(...)`:

    * **Inner Scopes (`depth > 1`):** Calls to `uow.commit()` safely execute `session.flush()` to populate database IDs and apply constraints without committing the physical transaction.
    * **Root Scope (`depth == 0`):** The outermost context manager boundary executes the final physical database commit.
    * **Deferred Events Buffer:** Events registered across all nested levels (`session.info['uow_events']`) are accumulated in the shared session buffer and dispatched together **only after the root transaction commits**.
    * **Chain Rollback:** An unhandled error at any depth immediately resets `uow_depth`, cancels all pending events, and rolls back the entire transaction chain.
  </Step>

  <Step>
    ### 3. Post-Commit Domain Events [#3-post-commit-domain-events]

    `UnitOfWork.register_event(event_name, payload)` prevents side-effects on transaction failures:

    * Events are queued in an internal buffer.
    * If the database commit succeeds, all buffered events are dispatched concurrently via `EventDispatcher`.
    * If a database error occurs or an exception is raised, the transaction rolls back and all pending events are discarded immediately.
  </Step>
</Steps>

<Callout type="info" emoji="⚡">
  **Automatic Coordination with `BaseService`:**
  Entering `async with UnitOfWork(...)` automatically marks the session as `uow_managed = True`. Any `BaseService` calls (such as `self.repository.create`) inside the block will automatically skip their individual commits and let `UnitOfWork` finalize the transaction on block exit.
</Callout>

<Callout type="warn" emoji="⚠️">
  **No Manual Commits:**
  Never call `db.commit()` manually when working inside a `UnitOfWork` block. Commit and rollback transitions are orchestrated automatically upon context exit (`__aexit__`).
</Callout>


# How to wire dependencies with Inject[T] (/docs/how-to/wire-dependencies)





ZCore eliminates verbose `Depends(...)` chains. It provides automatic constructor auto-wiring for classes, and the dynamic `Inject[T]` marker for FastAPI route handlers.

<Steps>
  <Step>
    ### Register External Clients (Singleton or Transient) [#register-external-clients-singleton-or-transient]

    If you have external clients (e.g., an `EmailClient` or third-party SDK), register them in ZCore's IoC container during startup:

    ```python
    # main.py or plugins
    from zcore.kernel.di import container

    class EmailClient:
        def send_email(self, to: str, message: str) -> None:
            print(f"Sending email to {to}: {message}")

    # Register as a shared singleton
    container.register_singleton(EmailClient, EmailClient())
    ```
  </Step>

  <Step>
    ### Constructor Auto-Wiring (Service-to-Service) [#constructor-auto-wiring-service-to-service]

    Inside your classes and services, you **do not** need any decorators or helpers. Simply declare your dependencies in the `__init__` method using standard Python type hints:

    ```python
    # services.py
    from .clients import EmailClient

    class NotificationService:
        # ZCore automatically inspects type hints and injects EmailClient
        def __init__(self, email_client: EmailClient):
            self.email_client = email_client

        async def notify(self, user_email: str) -> None:
            self.email_client.send_email(user_email, "Welcome to ZCore!")
    ```
  </Step>

  <Step>
    ### Use `Inject[T]` in FastAPI Routes [#use-injectt-in-fastapi-routes]

    To inject any container-managed dependency into a FastAPI route, annotate the parameter with `Inject[T]`:

    ```python
    # routers.py
    from fastapi import APIRouter
    from zcore import Inject
    from .services import NotificationService

    router = APIRouter()

    @router.post("/notify")
    async def send_notification(service: Inject[NotificationService]):
        await service.notify("user@example.com")
        return {"status": "sent"}
    ```
  </Step>
</Steps>

<Callout type="info" emoji="💡">
  **How `Inject[T]` Works:** Under the hood, `Inject[NotificationService]` resolves to `Annotated[NotificationService, Depends(Injector(NotificationService))]`. It seamlessly bridges FastAPI's dependency injection with ZCore's IoC container lifecycle.
</Callout>