fastapi-m8 4.2.2__tar.gz → 4.4.0__tar.gz

fastapi_m8-4.4.0/.markdownlint.yaml

@@ -0,0 +1,43 @@
+---
+# markdownlint configuration, also consumed by Codacy's markdownlint engine when
+# the repository is set to use its own configuration files.
+#
+# Scope note: a config file supplies markdownlint's *defaults* for every rule it
+# does not mention, so this file deliberately restates the rules this repository
+# already does not enforce. Without them, adding this file would turn one
+# reported rule into five and ~534 findings across README.md + CHANGELOG.md.
+
+# MD024/no-duplicate-heading — restrict to sibling headings.
+#
+# CHANGELOG.md follows Keep a Changelog, where every release section repeats the
+# same subsection names (### Added / ### Changed / ### Security / ### Docs …).
+# Under the default setting that makes each release after the first a stack of
+# duplicate-heading errors — 28 of them at 4.2.2, purely as a function of how
+# many releases the file records, and growing by ~3 with every release. The
+# duplication is the format, not a defect, and renaming the sections to be
+# unique would break the convention every reader of this changelog relies on.
+#
+# siblings_only flags a duplicate only when it shares a parent heading, so
+# "### Added" under [4.3.0] and "### Added" under [4.2.0] both pass, while two
+# "### Added" blocks inside one release — a real editing mistake — still fail.
+MD024:
+  siblings_only: true
+
+# MD013/line-length — off. README.md and CHANGELOG.md wrap prose for readability
+# rather than to a fixed column, and carry long table rows, URLs and code lines
+# that cannot be wrapped at all (328 findings). Python line length is enforced
+# separately and for real, by ruff (line-length = 88 in pyproject.toml).
+MD013: false
+
+# MD060/table-column-style — off. The documentation tables use compact pipes
+# (194 findings); this is a presentation preference with no effect on rendering.
+MD060: false
+
+# The three below are off to preserve the status quo, NOT because they are
+# wrong — each flags something worth fixing, and the count is small enough to
+# fix in one pass: MD031 blanks-around-fences (7), MD040 fenced-code-language
+# (3), MD028 no-blanks-blockquote (2). Left as a follow-up rather than folded
+# into an unrelated release commit; re-enable once those 12 spots are cleaned.
+MD031: false
+MD040: false
+MD028: false

{fastapi_m8-4.2.2 → fastapi_m8-4.4.0}/CHANGELOG.md

@@ -5,6 +5,204 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) · Versioning:
 
 ---
 
+## [4.4.0] — 2026-08-15 · Fail closed on a missing compatibility row; make the bare install importable
+
+Two independent release-integrity fixes ship together.
+
+`_assert_compat()` read its requirements with
+`COMPAT_MATRIX.get(minor, {})`. A `fastapi-m8` minor with no row yielded an
+empty dict, the validation loop ran zero times, and the function returned
+**successfully** — so a release that forgot its row disabled the
+`auth-sdk-m8` version check entirely, silently, for every consumer on that
+minor. That is fail-**open** on an authorization-adjacent dependency guard.
+
+Separately, the package's own minimal install had never been importable — see
+*Fixed*, below.
+
+### Changed
+
+- **`_assert_compat()` now fails closed.** An unlisted minor raises
+  `RuntimeError` naming the missing row (`"… has no COMPAT_MATRIX row for
+  minor 'X.Y' …"`) instead of booting unchecked. The behavior for a *listed*
+  minor is unchanged.
+
+- **`auth-sdk-m8` floor raised to `>=3.1.3,<4.0.0`** (was `>=3.1.2`) in
+  `pyproject.toml`, `constraints.txt`/`constraints-all.txt` (pinned to
+  `3.1.3`), and `COMPAT_MATRIX["4.4"]`, updated in place to match — `3.1.3` is
+  published, dependency maintenance only (no new SDK API, no source change on
+  either side). Folded into this still-unpublished release rather than a
+  separate bump, per the same one-bump-per-unpublished-release rule the
+  *Notes* below already applies to the bare-install fix.
+
+### Added
+
+- **`COMPAT_MATRIX["4.4"] = {"auth-sdk-m8": ">=3.1.3,<4.0.0"}`** — shipped in
+  the same commit as the fail-closed change, and load-bearing: without it this
+  release would be unbootable for every consumer resolving
+  `fastapi-m8>=4.3.0,<5.0.0`. No new SDK API is consumed; the floor tracks
+  `pyproject.toml`'s (`>=3.1.2` at the time this row was first added, raised to
+  `>=3.1.3` before publish — see the dependency-maintenance bullet above).
+- **`tests/test_compat.py::test_assert_compat_fails_closed_on_unlisted_minor`**
+  — reproduces the boot failure on an unlisted minor.
+- **`tests/test_compat.py::test_compat_matrix_current_minor_row_matches_pyproject_floor`**
+  — generalizes the existing `4.0`-specific row-vs-floor test to the *current*
+  minor, so a stale copy-pasted row can no longer pass.
+  `test_compat_matrix_40_row_matches_pyproject_floor` is retained: it also
+  backs the `4.0`-gate accept/reject tests.
+
+### Fixed
+
+- **`pip install fastapi-m8` with no extras now produces an importable
+  package.** Since `4.2.1` — when the SDK re-export block landed — a no-extras
+  install succeeded and then `import fastapi_m8` raised
+  `ModuleNotFoundError: No module named 'sqlalchemy'`, from `__init__.py`'s
+  module-level `from auth_sdk_m8.controllers.base import BaseController`.
+  SQLAlchemy arrives only through the `db` extra, so the "minimal (no database)"
+  install the README documents had never worked. Reproduced against the
+  published wheels for `4.2.0`, `4.2.1`, `4.2.2` and `4.3.0` in a clean
+  `python:3.14-slim` container. **No consumer in the fleet was exposed**: all
+  three declare `fastapi-m8[db,postgres(,mysql)]`, so they resolve SQLAlchemy
+  through the extra.
+
+  `BaseController` and `TimestampMixin` — the only two re-exports that need the
+  `db` extra — are now resolved by a module-level `__getattr__` (PEP 562)
+  instead of at import time. Both remain in `__all__`, remain importable as
+  `from fastapi_m8 import BaseController`, and **keep their object identity**:
+  the accessor returns the SDK object itself and caches it in the module
+  globals, so ORM models mixing in the re-exported `TimestampMixin` register
+  byte-identical metadata. Touching either without the extra now raises a
+  `ModuleNotFoundError` naming `fastapi-m8[db]` rather than a bare
+  `No module named 'sqlalchemy'`.
+
+  Option (a) of three was chosen — deferring the imports, rather than moving
+  `sqlalchemy` into the base dependencies or withdrawing the minimal-install
+  claim — because it keeps the SDK import boundary intact without forcing an ORM
+  on a service that has no database. **PEP 562 moves the failure from
+  `import fastapi_m8` to first attribute access; for these two names that is
+  still the consumer's own module-import time** (`BaseController` is subclassed
+  and `TimestampMixin` is mixed in at class-definition time), so the deferral
+  does not push an `ImportError` into a request path. This is recorded in the
+  `__getattr__` docstring so the laziness is not later mistaken for a
+  runtime-path hazard.
+
+- **`tests/test_packaging.py::test_package_imports_without_the_db_extra`** — a
+  no-extras clean-install probe alongside the existing one. The existing probe
+  installs `--no-deps` into a target dir and therefore runs against whatever the
+  development environment already has on `sys.path`, so it is structurally blind
+  to this class of defect; the new probe installs the same built wheel and runs
+  with `sqlalchemy`/`sqlmodel`/`alembic` made unimportable, asserting first that
+  the blocker really blocks. `tests/test_public_typing.py` gains four tests
+  covering lazy-lookup stability, the unknown-name `AttributeError`, and the
+  actionable missing-extra message.
+
+### Notes
+
+- The bare-install fix and the `auth-sdk-m8 3.1.3` floor raise **ship no
+  version bump of their own**: both ride this same `4.4.0`, per the wave's
+  version-bump rule (one bump per unpublished release).
+- `COMPAT_MATRIX` and `_assert_compat` exist in `fastapi-m8` only; a sweep of
+  the other nine Python repositories in the fleet found no second copy, so this
+  guard has exactly one implementation.
+- Historical rows are **not** revised by this release. The `"4.2"` row states
+  `>=3.1.0` where `pyproject.toml` at the time declared `>=3.1.2`; the new
+  row-vs-floor test is scoped to the current minor, and whether historical rows
+  are corrected or grandfathered remains an open decision.
+
+---
+
+## [4.3.0] — 2026-08-14 · Complete the SDK re-export surface
+
+Adds the five `auth-sdk-m8` primitives the consumer fleet still imports
+directly, so a consumer service can depend on `fastapi-m8` alone and reach
+**zero** `auth_sdk_m8` imports. Additive only: no existing export, signature or
+behavior changes, and no new `auth-sdk-m8` API is required.
+
+Until this release the boundary was literally unsatisfiable — five of the twelve
+symbols the fleet imports had no `fastapi_m8` re-export, so every consumer had
+to keep a direct SDK import or invent a local shim.
+
+### Added
+
+- **`has_minimum_role`** (from `auth_sdk_m8.authorization`) — the canonical
+  role-ordering predicate. One implementation of the hierarchy, re-exported
+  rather than re-derived at a call site.
+- **`RoleType`** (from `auth_sdk_m8.schemas.base`) — the role enum those
+  thresholds are expressed in, and the argument type of
+  `AuthDeps.require_role()`.
+- **`ValidationConstants`** (from `auth_sdk_m8.schemas.shared`) — the shared
+  field-length/format constants consumer schemas validate against.
+- **`make_scrape_credential_guard`** (from `auth_sdk_m8.security.guards`) — the
+  `/metrics` scrape-credential guard factory.
+- **`REGISTRY`** (from `auth_sdk_m8.observability.metrics`) — the shared
+  Prometheus collector registry that `render_metrics` (already re-exported)
+  renders.
+
+All five are documented in the module docstring's *Reusable SDK primitives*
+block and listed in `__all__`; `has_superuser_privileges`, `BaseController`,
+`ResponseModelBase`, `ResponseMessage`, `TimestampMixin`, `UserModel`,
+`find_dotenv` and `render_metrics` were already re-exported and are unchanged.
+
+### Changed
+
+- `COMPAT_MATRIX` gains its `"4.3"` row (`auth-sdk-m8 >=3.1.2,<4.0.0`). Without
+  it `_assert_compat()` would find no requirement for the new minor and silently
+  skip the startup check. The floor is stated as `>=3.1.2` — the floor
+  `pyproject.toml` already declares — rather than `4.2`'s looser `>=3.1.0`.
+
+### Documentation
+
+- `README.md` gains a **Reusable SDK Primitives** section listing every
+  re-exported symbol, its SDK origin and its purpose, and states the boundary
+  rule: a consumer service imports these from `fastapi-m8`, never from
+  `auth-sdk-m8`. The database example now imports `TimestampMixin` from
+  `fastapi_m8` accordingly, and the compatibility table gains the `4.3.0` row.
+
+### Tests
+
+- `tests/test_public_typing.py` type-checks all twelve re-exported primitives
+  through the public surface and asserts each one **is** the SDK object it
+  claims to re-export (identity, not just importability).
+- `tests/test_packaging.py`'s clean-install probe imports the five new names
+  from the built wheel, which is the acceptance condition for this release.
+
+---
+
+## [4.2.2] — 2026-07-31 · Dependency maintenance
+
+Reconstructed from Git history (`ed259a1`, `0c3123b`) — the release shipped
+without a changelog entry.
+
+### Changed
+
+- `auth-sdk-m8` floor raised to `>=3.1.2,<4.0.0` in `pyproject.toml` and pinned
+  to `3.1.2` in the compiled constraints files. No source change.
+
+---
+
+## [4.2.1] — 2026-07-31 · Re-exports, Python floor, docs
+
+Reconstructed from Git history (`86830ee` and the commits it bumped for:
+`b105e01`, `23020fe`, `be5c382`, `a57811c`) — the release shipped without a
+changelog entry.
+
+### Added
+
+- Re-export of the reusable `auth-sdk-m8` primitives (`has_superuser_privileges`,
+  `BaseController`, `ResponseModelBase`, `ResponseMessage`, `TimestampMixin`,
+  `UserModel`, `find_dotenv`, `render_metrics`) — the first half of the surface
+  `4.3.0` completes.
+
+### Changed
+
+- Python floor raised to `>=3.12`; truncated lockfiles regenerated.
+
+### Documentation
+
+- Documented hybrid mode's expiry-bounded revocation contract; reformatted the
+  embedded Python snippets in `CHANGELOG.md`/`README.md`.
+
+---
+
 ## [4.2.0] — 2026-07-23 · Role-capability demonstration surface (Phase 7)
 
 Adds a centralized `require_role(required_role: RoleType)` JWT dependency

{fastapi_m8-4.2.2 → fastapi_m8-4.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: fastapi-m8
-Version: 4.2.2
+Version: 4.4.0
 Summary: FastAPI application framework for m8 consumer microservices.
 Author-email: Eli Serra <e.serra173@gmail.com>
 License:                                  Apache License
@@ -215,7 +215,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.12
 Requires-Dist: anyio>=4.0
-Requires-Dist: auth-sdk-m8[config,events,fastapi,observability,security]<4.0.0,>=3.1.2
+Requires-Dist: auth-sdk-m8[config,events,fastapi,observability,security]<4.0.0,>=3.1.3
 Requires-Dist: fastapi>=0.136.3
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: packaging>=24.0
@@ -284,6 +284,7 @@ boilerplate from every consumer service.
    - [build_auth_deps()](#build_auth_deps)
    - [create_db_engine()](#create_db_engine)
    - [Health Checks](#health-checks)
+   - [Reusable SDK Primitives](#reusable-sdk-primitives)
 7. [Authentication](#authentication)
    - [Token Modes](#token-modes)
    - [Role System](#role-system)
@@ -389,6 +390,20 @@ pip install "fastapi-m8[all]"
 
 **Runtime requirements:** Python 3.12+
 
+**What the minimal install gives you (since 4.4.0):** everything except the two
+SQLModel-backed re-exports. `create_app`, `build_auth_deps`,
+`ConsumerServiceSettings`, the health building blocks, the API-key and event-stream
+clients, and the extra-free SDK primitives (`RoleType`, `has_minimum_role`,
+`UserModel`, `REGISTRY`, …) all work with no extras. `BaseController` and
+`TimestampMixin` are resolved lazily and raise a `ModuleNotFoundError` naming
+`fastapi-m8[db]` if you touch them without that extra — install `[db]` (plus a
+driver) as soon as your service has a database.
+
+> Before 4.4.0 the minimal install did not actually work: `import fastapi_m8`
+> raised `ModuleNotFoundError: No module named 'sqlalchemy'` on any release from
+> 4.2.1 onward, because those two names were imported at module level. If you are
+> on 4.2.1–4.3.0 and want a database-free install, upgrade to 4.4.0.
+
 ---
 
 ## Quick Start
@@ -1162,6 +1177,53 @@ class RedisCheck:
 | `LENIENT` (default) | Any check is `fail` |
 | `STRICT` | Any check is `fail` or `unknown` |
 
+### Reusable SDK Primitives
+
+`fastapi-m8` already depends on `auth-sdk-m8` and pins its major range, so it
+re-exports the SDK primitives a consumer service actually needs. **Import them
+from `fastapi_m8`, never from `auth_sdk_m8`.** A consumer service that imports
+the SDK directly takes on a second dependency whose major range it does not
+control, and can be broken by an SDK change `fastapi-m8` has already absorbed.
+
+| Re-export | SDK origin | Purpose |
+|---|---|---|
+| `has_superuser_privileges` | `auth_sdk_m8` | Dual-evidence superuser predicate (`role == SUPERADMIN` **and** `is_superuser`) |
+| `has_minimum_role` | `auth_sdk_m8.authorization` | Canonical role-ordering predicate — the single implementation of the hierarchy |
+| `RoleType` | `auth_sdk_m8.schemas.base` | Role enum; the argument type of `AuthDeps.require_role()` |
+| `BaseController` | `auth_sdk_m8.controllers.base` | CRUD controller base class |
+| `ResponseModelBase` | `auth_sdk_m8.schemas.base` | Base response schema |
+| `ResponseMessage` | `auth_sdk_m8.schemas.base` | Simple `{"message": ...}` response schema |
+| `ValidationConstants` | `auth_sdk_m8.schemas.shared` | Shared field length/format constants for consumer schemas |
+| `TimestampMixin` | `auth_sdk_m8.models.shared` | `created_at` / `updated_at` UTC columns for SQLModel tables |
+| `UserModel` | `auth_sdk_m8.schemas.user` | The authenticated principal every JWT dependency resolves to |
+| `find_dotenv` | `auth_sdk_m8.utils.paths` | Locate the service `.env` file |
+| `render_metrics` | `auth_sdk_m8.observability.metrics` | Render the Prometheus exposition payload |
+| `REGISTRY` | `auth_sdk_m8.observability.metrics` | The shared Prometheus collector registry `render_metrics` renders |
+| `make_scrape_credential_guard` | `auth_sdk_m8.security.guards` | Build the `/metrics` scrape-credential guard |
+
+```python
+from fastapi_m8 import (
+    REGISTRY,
+    BaseController,
+    ResponseMessage,
+    ResponseModelBase,
+    RoleType,
+    TimestampMixin,
+    UserModel,
+    ValidationConstants,
+    find_dotenv,
+    has_minimum_role,
+    has_superuser_privileges,
+    make_scrape_credential_guard,
+    render_metrics,
+)
+```
+
+Every name above is the SDK object itself, not a wrapper — `fastapi_m8.RoleType
+is auth_sdk_m8.schemas.base.RoleType` — so rerouting an import changes nothing
+at runtime, including SQLModel/SQLAlchemy table metadata built on
+`TimestampMixin`.
+
 ---
 
 ## Authentication
@@ -1420,13 +1482,15 @@ TABLES_PREFIX=app
 `SQLALCHEMY_DATABASE_URI` is assembled automatically. You can also set it directly
 to override the assembly.
 
-Define models with `TimestampMixin` from `auth-sdk-m8` (adds `created_at` /
-`updated_at` UTC columns):
+Define models with `TimestampMixin` (adds `created_at` / `updated_at` UTC
+columns). It originates in `auth-sdk-m8` and is
+[re-exported by `fastapi-m8`](#reusable-sdk-primitives) — import it from here,
+not from the SDK:
 
 ```python
 import uuid
 from sqlmodel import SQLModel, Field
-from auth_sdk_m8.models.shared import TimestampMixin
+from fastapi_m8 import TimestampMixin
 
 
 class Item(TimestampMixin, SQLModel, table=True):
@@ -1636,6 +1700,8 @@ async def test_health(client):
 
 | `fastapi-m8` | `auth-sdk-m8` | Python |
 |---|---|---|
+| `4.4.0` | `>=3.1.3, <4.0.0` | 3.12, 3.13, 3.14 |
+| `4.3.0` | `>=3.1.2, <4.0.0` | 3.12, 3.13, 3.14 |
 | `4.2.0` | `>=3.1.0, <4.0.0` | 3.12, 3.13, 3.14 |
 | `4.1.0` | `>=3.1.0, <4.0.0` | 3.11, 3.12, 3.13, 3.14 |
 | `4.0.0` | `>=3.0.0, <4.0.0` | 3.11, 3.12, 3.13, 3.14 |
@@ -1658,6 +1724,11 @@ The compatibility matrix is enforced at startup via `COMPAT_MATRIX`. A
 `RuntimeError` is raised immediately if the installed `auth-sdk-m8` version is
 outside the supported range.
 
+Since `4.4.0` the check **fails closed**: if the running `fastapi-m8` minor has
+no `COMPAT_MATRIX` row at all, startup raises a `RuntimeError` naming the
+missing row instead of skipping validation. Before `4.4.0` an unlisted minor
+booted with the dependency check silently disabled.
+
 Check at runtime:
 
 ```python

{fastapi_m8-4.2.2 → fastapi_m8-4.4.0}/README.md

@@ -27,6 +27,7 @@ boilerplate from every consumer service.
    - [build_auth_deps()](#build_auth_deps)
    - [create_db_engine()](#create_db_engine)
    - [Health Checks](#health-checks)
+   - [Reusable SDK Primitives](#reusable-sdk-primitives)
 7. [Authentication](#authentication)
    - [Token Modes](#token-modes)
    - [Role System](#role-system)
@@ -132,6 +133,20 @@ pip install "fastapi-m8[all]"
 
 **Runtime requirements:** Python 3.12+
 
+**What the minimal install gives you (since 4.4.0):** everything except the two
+SQLModel-backed re-exports. `create_app`, `build_auth_deps`,
+`ConsumerServiceSettings`, the health building blocks, the API-key and event-stream
+clients, and the extra-free SDK primitives (`RoleType`, `has_minimum_role`,
+`UserModel`, `REGISTRY`, …) all work with no extras. `BaseController` and
+`TimestampMixin` are resolved lazily and raise a `ModuleNotFoundError` naming
+`fastapi-m8[db]` if you touch them without that extra — install `[db]` (plus a
+driver) as soon as your service has a database.
+
+> Before 4.4.0 the minimal install did not actually work: `import fastapi_m8`
+> raised `ModuleNotFoundError: No module named 'sqlalchemy'` on any release from
+> 4.2.1 onward, because those two names were imported at module level. If you are
+> on 4.2.1–4.3.0 and want a database-free install, upgrade to 4.4.0.
+
 ---
 
 ## Quick Start
@@ -905,6 +920,53 @@ class RedisCheck:
 | `LENIENT` (default) | Any check is `fail` |
 | `STRICT` | Any check is `fail` or `unknown` |
 
+### Reusable SDK Primitives
+
+`fastapi-m8` already depends on `auth-sdk-m8` and pins its major range, so it
+re-exports the SDK primitives a consumer service actually needs. **Import them
+from `fastapi_m8`, never from `auth_sdk_m8`.** A consumer service that imports
+the SDK directly takes on a second dependency whose major range it does not
+control, and can be broken by an SDK change `fastapi-m8` has already absorbed.
+
+| Re-export | SDK origin | Purpose |
+|---|---|---|
+| `has_superuser_privileges` | `auth_sdk_m8` | Dual-evidence superuser predicate (`role == SUPERADMIN` **and** `is_superuser`) |
+| `has_minimum_role` | `auth_sdk_m8.authorization` | Canonical role-ordering predicate — the single implementation of the hierarchy |
+| `RoleType` | `auth_sdk_m8.schemas.base` | Role enum; the argument type of `AuthDeps.require_role()` |
+| `BaseController` | `auth_sdk_m8.controllers.base` | CRUD controller base class |
+| `ResponseModelBase` | `auth_sdk_m8.schemas.base` | Base response schema |
+| `ResponseMessage` | `auth_sdk_m8.schemas.base` | Simple `{"message": ...}` response schema |
+| `ValidationConstants` | `auth_sdk_m8.schemas.shared` | Shared field length/format constants for consumer schemas |
+| `TimestampMixin` | `auth_sdk_m8.models.shared` | `created_at` / `updated_at` UTC columns for SQLModel tables |
+| `UserModel` | `auth_sdk_m8.schemas.user` | The authenticated principal every JWT dependency resolves to |
+| `find_dotenv` | `auth_sdk_m8.utils.paths` | Locate the service `.env` file |
+| `render_metrics` | `auth_sdk_m8.observability.metrics` | Render the Prometheus exposition payload |
+| `REGISTRY` | `auth_sdk_m8.observability.metrics` | The shared Prometheus collector registry `render_metrics` renders |
+| `make_scrape_credential_guard` | `auth_sdk_m8.security.guards` | Build the `/metrics` scrape-credential guard |
+
+```python
+from fastapi_m8 import (
+    REGISTRY,
+    BaseController,
+    ResponseMessage,
+    ResponseModelBase,
+    RoleType,
+    TimestampMixin,
+    UserModel,
+    ValidationConstants,
+    find_dotenv,
+    has_minimum_role,
+    has_superuser_privileges,
+    make_scrape_credential_guard,
+    render_metrics,
+)
+```
+
+Every name above is the SDK object itself, not a wrapper — `fastapi_m8.RoleType
+is auth_sdk_m8.schemas.base.RoleType` — so rerouting an import changes nothing
+at runtime, including SQLModel/SQLAlchemy table metadata built on
+`TimestampMixin`.
+
 ---
 
 ## Authentication
@@ -1163,13 +1225,15 @@ TABLES_PREFIX=app
 `SQLALCHEMY_DATABASE_URI` is assembled automatically. You can also set it directly
 to override the assembly.
 
-Define models with `TimestampMixin` from `auth-sdk-m8` (adds `created_at` /
-`updated_at` UTC columns):
+Define models with `TimestampMixin` (adds `created_at` / `updated_at` UTC
+columns). It originates in `auth-sdk-m8` and is
+[re-exported by `fastapi-m8`](#reusable-sdk-primitives) — import it from here,
+not from the SDK:
 
 ```python
 import uuid
 from sqlmodel import SQLModel, Field
-from auth_sdk_m8.models.shared import TimestampMixin
+from fastapi_m8 import TimestampMixin
 
 
 class Item(TimestampMixin, SQLModel, table=True):
@@ -1379,6 +1443,8 @@ async def test_health(client):
 
 | `fastapi-m8` | `auth-sdk-m8` | Python |
 |---|---|---|
+| `4.4.0` | `>=3.1.3, <4.0.0` | 3.12, 3.13, 3.14 |
+| `4.3.0` | `>=3.1.2, <4.0.0` | 3.12, 3.13, 3.14 |
 | `4.2.0` | `>=3.1.0, <4.0.0` | 3.12, 3.13, 3.14 |
 | `4.1.0` | `>=3.1.0, <4.0.0` | 3.11, 3.12, 3.13, 3.14 |
 | `4.0.0` | `>=3.0.0, <4.0.0` | 3.11, 3.12, 3.13, 3.14 |
@@ -1401,6 +1467,11 @@ The compatibility matrix is enforced at startup via `COMPAT_MATRIX`. A
 `RuntimeError` is raised immediately if the installed `auth-sdk-m8` version is
 outside the supported range.
 
+Since `4.4.0` the check **fails closed**: if the running `fastapi-m8` minor has
+no `COMPAT_MATRIX` row at all, startup raises a `RuntimeError` naming the
+missing row instead of skipping validation. Before `4.4.0` an unlisted minor
+booted with the dependency check silently disabled.
+
 Check at runtime:
 
 ```python

{fastapi_m8-4.2.2 → fastapi_m8-4.4.0}/constraints-all.txt

@@ -25,7 +25,7 @@ attrs==26.1.0
     # via
     #   outcome
     #   trio
-auth-sdk-m8[config,events,fastapi,observability,security]==3.1.2
+auth-sdk-m8[config,events,fastapi,observability,security]==3.1.3
     # via
     #   fastapi-m8
     #   fastapi-m8 (pyproject.toml)

{fastapi_m8-4.2.2 → fastapi_m8-4.4.0}/constraints.txt

@@ -16,7 +16,7 @@ anyio==4.14.1
     #   fastapi-m8 (pyproject.toml)
     #   httpx
     #   starlette
-auth-sdk-m8[config,events,fastapi,observability,security]==3.1.2
+auth-sdk-m8[config,events,fastapi,observability,security]==3.1.3
     # via
     #   fastapi-m8
     #   fastapi-m8 (pyproject.toml)

{fastapi_m8-4.2.2 → fastapi_m8-4.4.0}/fastapi_m8/__init__.py

@@ -27,11 +27,17 @@ Tier 2 — health building blocks::
     )
 
 Reusable SDK primitives (re-exported from auth-sdk-m8, so consumers depend
-only on fastapi-m8)::
+only on fastapi-m8 — a consumer service must never import ``auth_sdk_m8``
+directly)::
 
-    from fastapi_m8 import has_superuser_privileges
+    from fastapi_m8 import has_superuser_privileges, has_minimum_role, RoleType
     from fastapi_m8 import BaseController, ResponseModelBase, ResponseMessage
-    from fastapi_m8 import TimestampMixin, UserModel, find_dotenv, render_metrics
+    from fastapi_m8 import TimestampMixin, UserModel, ValidationConstants
+    from fastapi_m8 import find_dotenv, render_metrics, REGISTRY
+    from fastapi_m8 import make_scrape_credential_guard
+
+``BaseController`` and ``TimestampMixin`` are the only two of those that need
+the ``[db]`` extra; both are resolved lazily — see ``__getattr__`` below.
 
 Tier 3 — informational / future::
 
@@ -39,15 +45,19 @@ Tier 3 — informational / future::
     from fastapi_m8 import COMPAT_MATRIX, __version__
 """
 
+from typing import TYPE_CHECKING, Any
+
 # Tier 1
 # Reusable SDK primitives — re-exported so consumers only need fastapi-m8,
 # never a direct auth-sdk-m8 dependency.
 from auth_sdk_m8 import has_superuser_privileges
-from auth_sdk_m8.controllers.base import BaseController
-from auth_sdk_m8.models.shared import TimestampMixin
+from auth_sdk_m8.authorization import has_minimum_role
+from auth_sdk_m8.observability.metrics import REGISTRY
 from auth_sdk_m8.observability.metrics import render as render_metrics
-from auth_sdk_m8.schemas.base import ResponseMessage, ResponseModelBase
+from auth_sdk_m8.schemas.base import ResponseMessage, ResponseModelBase, RoleType
+from auth_sdk_m8.schemas.shared import ValidationConstants
 from auth_sdk_m8.schemas.user import UserModel
+from auth_sdk_m8.security.guards import make_scrape_credential_guard
 from auth_sdk_m8.utils.paths import find_dotenv
 
 from fastapi_m8._api_key import (
@@ -92,6 +102,68 @@ from fastapi_m8._route_audit import BareApiKeyDependency, audit_api_key_routes
 from fastapi_m8._version import __version__
 from fastapi_m8.config import ConsumerServiceSettings
 
+if TYPE_CHECKING:  # pragma: no cover - type-checker-only, never executed
+    # Imported eagerly for type checkers and IDEs only. At runtime these two
+    # names are served by ``__getattr__`` below, so a bare install can import
+    # the package without the ``[db]`` extra.
+    from auth_sdk_m8.controllers.base import BaseController
+    from auth_sdk_m8.models.shared import TimestampMixin
+
+# The SDK re-exports that require the ``[db]`` extra, mapped to their source
+# module. ``auth_sdk_m8.controllers.base`` imports ``sqlalchemy.exc`` and
+# ``sqlmodel``; ``auth_sdk_m8.models.shared`` imports ``sqlalchemy`` and
+# ``sqlmodel``. Every other re-export above is extra-free.
+_DB_REEXPORTS: dict[str, str] = {
+    "BaseController": "auth_sdk_m8.controllers.base",
+    "TimestampMixin": "auth_sdk_m8.models.shared",
+}
+
+
+def __getattr__(name: str) -> Any:
+    """
+    Resolve the ``[db]``-extra SDK re-exports on first access (PEP 562).
+
+    ``pip install fastapi-m8`` with no extras must yield an importable
+    package. Importing ``BaseController`` / ``TimestampMixin`` at module level
+    made ``import fastapi_m8`` raise ``ModuleNotFoundError: No module named
+    'sqlalchemy'`` on a bare install, because both come from SQLModel-backed
+    SDK modules and SQLAlchemy arrives only through the ``db`` extra.
+
+    Deferring them costs a bare install nothing and keeps the import boundary
+    intact: a consumer still writes ``from fastapi_m8 import BaseController``.
+    The object returned **is** the SDK object — identity is preserved, so ORM
+    models mixing in the re-exported ``TimestampMixin`` register exactly the
+    same metadata as before, and the resolved value is cached in the module
+    globals so later lookups skip this function entirely.
+
+    Note on where the failure now surfaces: PEP 562 moves it from
+    ``import fastapi_m8`` to first attribute access. For both of these names
+    that is still the consumer's own module-import time — ``BaseController``
+    is subclassed and ``TimestampMixin`` is mixed in at class-definition
+    time — so the deferral does **not** push an ``ImportError`` into a request
+    path. It is a packaging fix, not a runtime-path hazard.
+    """
+    module_path = _DB_REEXPORTS.get(name)
+    if module_path is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    from importlib import import_module  # noqa: PLC0415
+
+    try:
+        value = getattr(import_module(module_path), name)
+    except ModuleNotFoundError as exc:
+        raise ModuleNotFoundError(
+            f"fastapi_m8.{name} is re-exported from {module_path}, which requires"
+            f" the 'db' extra: install fastapi-m8[db] (or fastapi-m8[all])."
+        ) from exc
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    """Keep the lazy names discoverable by ``dir()`` and tab completion."""
+    return sorted(set(globals()) | set(_DB_REEXPORTS))
+
+
 __all__ = [
     "__version__",
     # Tier 1
@@ -127,13 +199,18 @@ __all__ = [
     "HealthAggregatePolicy",
     # Reusable SDK primitives (from auth-sdk-m8)
     "has_superuser_privileges",
+    "has_minimum_role",
+    "RoleType",
     "BaseController",
     "ResponseModelBase",
     "ResponseMessage",
     "TimestampMixin",
     "UserModel",
+    "ValidationConstants",
     "find_dotenv",
     "render_metrics",
+    "REGISTRY",
+    "make_scrape_credential_guard",
     # Tier 3
     "create_async_app",
     "CAPABILITIES",