release(v0.1.0-rc.2): framework stabilization, soft-delete, and lookup (#126)

## Description

This release candidate (`v0.1.0-rc.2`) introduces major architectural
stabilization, performance optimizations, and core feature additions to
prepare the framework for the upcoming `v1.0.0` stable milestone.

### Summary
- **Unified Exception Envelope & Normalization**: Implemented
standardized error normalization across all exception types
(`AppException`, `RequestValidationError`, `StarletteHTTPException`,
`ResponseValidationError`, and generic `Exception`) wrapping responses
in `ResponseWrapper[None]`, with Pydantic error sanitization
(`_sanitize_error_item`, `_format_error_location`), debug-gated response
details, and one-call registration via
`register_exception_handlers(app)`.
- **End-to-End Soft-Delete & Restoration Lifecycle**: Added declarative
soft-delete support across Repository, Service, and Router layers.
Includes `restore()` / `restore_multi()` with atomic SQL dialect-aware
`RETURNING` updates, lifecycle hooks (`pre/post_restore`), and `force:
bool = False` flag propagation for physical deletion via `DELETE
/resource/{id}?force=true`.
- **Field-Restricted `LOOKUP` Endpoint & Query Projections**: Introduced
`RouteKey.LOOKUP` (`POST /lookup`) with automatic schema-driven column
projection (`load_only`), relationship eager-loading (`selectinload` /
`joinedload`), allowed field validation, and `Actions.LOOKUP` RBAC
permission integration.
- **Search Engine Inversion & Logical NOT Groups**: Added inverted
comparison operators (`not_like`, `not_ilike`, `not_contains`,
`not_startswith`, `not_endswith`, `not_in`, `not_between`,
`is_not_null`) and logical `not` grouping to the AST query builder.
- **Re-entrant Unit of Work & Deferred Event Dispatching**: Added
depth-aware transaction coordination (`uow_depth`) for nested
`UnitOfWork` scopes, buffering domain events in
`session.info['uow_events']` to ensure atomic root-level dispatching.
- **Polymorphic Identifier Support**: Generalized user identity types
across `ZContext`, `UserProtocol`, `StreamManager`, and keyset
`CursorPagination` to seamlessly support `int`, `str`, and `UUID`
identifiers.
- **Optional Auth & Guest Field Shielding**: Added `auto_error=False`
support to `BaseAuth`, exported `get_optional_user_stub`, and introduced
`__private__` class attributes on `Zchema` to prune sensitive fields for
unauthenticated requests automatically.
- **Tunable Configuration & Parameter Bounding**: Added framework-wide
settings for pagination bounds, search depth, caching TTL/maxsize, and
stream queue limits, enforced dynamically via Pydantic model validators.
- **Logging Refinement & Context Isolation**: Implemented
status-code-aware log levels (DEBUG for `<500`, ERROR for `>=500`),
decoupled slow-query logging, preserved native Uvicorn console
formatting in dev mode vs JSON intercept in production, and hardened
Structlog contextvar isolation across background scopes.
- **Enhanced Test Harness & Fixtures**: Added `setup_test_database`,
`EventDispatcherSandbox`, custom engine/dependency overrides in
`DatabaseRollback`, and guest/superuser mocking in `ZTestClient`.
- **Tooling, Docs & CI**: Upgraded `zc run` with cascading configuration
(`CLI > .env > Defaults`) and transparent Uvicorn argument forwarding,
added dynamic test suite naming (`test_<app_name>.py`), restructured
`README.md` with the ZShop showcase, and split GitHub Actions CI into
quality check, cross-platform matrix, and smoke installation jobs.

### Impact
Standardizes error handling, transaction lifecycles, and data exposure
mechanisms across all layers of the framework. These changes resolve
multi-tenancy, typing, and background execution edge cases while
boosting serialization performance and providing developer tooling for
the stable `v1.0.0` release.

## Type of change

- [x] Bug fix (non-breaking change which fixes an issue)
- [x] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to not work as expected)
- [x] Refactoring (architectural or code cleanup with no functional
changes)
- [x] Documentation update

## How Has This Been Tested?

- [x] Unit/Integration tests (`hatch test`)
- Validated full test suite (515+ tests) across Python 3.11, 3.12, and
3.13 on Ubuntu, Windows, and macOS.
- Verified exception envelope conformity and header preservation across
all HTTP handlers.
- Tested single and bulk soft-delete, hard-delete (`force=True`), and
restoration lifecycles.
- Tested dynamic search operators, negation logic, and nested filter
depth validation.
- Verified `ZTestClient` savepoint rollbacks, polymorphic user IDs, and
optional auth mocking.
- Validated `Zchema` guest pruning (`__private__`) and role-based field
restrictions.
- [x] Static type check passing (`mypy src/`)
  - Strict type checking passed with zero errors across all modules.
- [x] Code style and formatting checks (`ruff check src/`, `ruff format
--check src/`).
- [x] Smoke install build test (`pip install dist/*.whl` and CLI
verification).

## Checklist:

- [x] My code follows the style guidelines and architectural rules of
this project
- [x] I have performed a self-review of my own code
- [x] My changes pass strict static type analysis (`mypy src/` generates
no warnings)
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have updated the documentation in `zcore-docs` if applicable
- [x] My changes generate no new runtime warnings
- [x] I have added tests that prove my fix is effective or that my
feature works

Author: alialfostovar

.github/workflows/test.yml

@@ -2,17 +2,17 @@ name: Test Suite (CI)
 
 on:
   pull_request:
-    branches:
-      - master
-      - develop
+    branches: [master, develop]
   push:
-    branches:
-      - master
-      - develop
+    branches: [master, develop]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
 
 jobs:
-  test:
-    name: test
+  quality-check:
+    name: Code Quality & Type Check
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -22,14 +22,86 @@ jobs:
           python-version: "3.11"
           cache: "pip"
 
-      - name: Upgrade pip
-        run: python -m pip install --upgrade pip
-
-      - name: Install Hatch and Ruff
-        run: pip install hatch ruff
+      - name: Install Dependencies & Tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install ruff mypy
+          pip install -e ".[all]"
 
-      - name: Run Ruff Lint Check
+      - name: Ruff Linter
         run: ruff check src/zcore
 
-      - name: Run Hatch Tests
-        run: hatch test
+      - name: Ruff Formatter Check
+        run: ruff format --check src/zcore
+
+      - name: Mypy Strict Type Analysis
+        run: mypy src/zcore
+
+  matrix-tests:
+    name: test (${{ matrix.os }} / py${{ matrix.python-version }})
+    needs: quality-check
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+
+      - name: Upgrade pip & install hatch
+        run: |
+          python -m pip install --upgrade pip
+          pip install hatch
+
+      - name: Run 515+ Tests via Hatch
+        run: hatch test
+
+  smoke-install-test:
+    name: smoke test (${{ matrix.os }})
+    needs: matrix-tests
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install Hatch & Build Wheel
+        run: |
+          pip install hatch
+          hatch build
+
+      - name: Install Generated Wheel & Test CLI
+        shell: bash
+        run: |
+          pip install dist/*.whl
+          zc --version
+          python -c "import zcore; print('ZCore successfully imported from:', zcore.__file__)"
+
+  all-checks-passed:
+    name: all-checks-passed
+    needs: [quality-check, matrix-tests, smoke-install-test]
+    runs-on: ubuntu-latest
+    if: always()
+    steps:
+      - name: Verify all dependencies succeeded
+        run: |
+          if [ "${{ needs.quality-check.result }}" != "success" ] || \
+             [ "${{ needs.matrix-tests.result }}" != "success" ] || \
+             [ "${{ needs.smoke-install-test.result }}" != "success" ]; then
+            echo "One or more checks failed!"
+            exit 1
+          fi
+          echo "All 13 checks passed with 100% success!"

.gitignore

@@ -1,46 +1,48 @@
-# Byte-compiled / optimized / DLL files
+# Byte-compiled / optimized / compiled files
 __pycache__/
-*.py[cod]
-*$py.class
+*.pyc
+*.pyd
+*.pyo
+*.egg-info/
+.eggs/
 
-# C extensions
-*.so
+# Virtual environment
+venv/
+.venv/
+env
+.env
 
 # Distribution / packaging
-bin/
-build/
-develop-eggs/
 dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-share/python-wheels/
-*.egg-info/
-.installed.cfg
+build/
 *.egg
+*.whl
 
-# Virtual Environments
-.venv/
-venv/
-ENV/
-env/
-
-# IDEs and editors
-.idea/
+# Editor and IDE files
 .vscode/
+.idea/
 *.swp
+*.bak
 *.swo
 
-# Local configuration & environment variables
-.env
-.env.local
-.env.*
+# OS generated files
+.DS_Store
+Thumbs.db
+
+# Logs and databases
+*.log
+*.sqlite3
+*.db
+
+# Temporary files
+tmp/
+*.tmp
+
+# Jupyter Notebook files
+.ipynb_checkpoints/
 
-# database
-*.db
+# Miscellaneous
+.pytest_cache/
+htmlcov/
+.coverage
+.mypy_cache