refactor: organize app.state into typed namespaces (#31)

* docs: app.state organization design

Consolidate 15+ loose app.state attributes into one typed slot per
owner (framework + each module), delete three duplicate locale fields,
and drop runtime drift detection. Storage stays on app.state; only
the shape changes.

* docs: app.state organization implementation plan

14-task staged migration from loose app.state keys to typed slots
(app.state.sm for framework + app.state.<module> for each module).
Each task is a single revertable commit.

* feat(core): add Services dataclass for framework singletons

* test(core): match codebase test-class convention for Services

* feat(hosting): populate app.state.sm alongside loose keys

* refactor(hosting): read framework singletons via app.state.sm

* refactor(hosting): read i18n + permission singletons via app.state.sm

* refactor(host): read i18n state via app.state.sm with fallback

* refactor(modules): read framework state via app.state.sm

* feat(users): introduce UsersServices at app.state.users

* refactor(users): read module state via app.state.users

Migrate all users-module consumers from loose app.state keys
(mailer, users_settings, rate_limiter, auth_throughput_limiter, event_bus, db)
to the structured UsersServices slot introduced in Task 7. Update two test
helpers that patched the old loose keys to patch app.state.users.* instead.

* refactor(users): migrate bootstrap + its test helper to app.state.users/sm

* test(users+auth): migrate remaining app.state reads to sm/users slots

* refactor: delete deprecated loose app.state keys

* refactor: migrate consumers to read from app.state.sm.*

- Update conftest fixtures to access app.state.sm.db and app.state.sm.settings
- Update get_db FastAPI dependency to use app.state.sm.db
- Update test mocks and fixtures to use app.state.sm.* paths
- Update dashboard stats and products deps to use app.state.sm.*
- Update test assertions to verify sm instance instead of loose keys

* fix: migrate remaining app.state reads missed in Task 10

* revert: restore generated i18n files (regen had stale fixture)

* refactor: drop duplicate locale fields, update SM012, simplify i18n routes

* refactor(hosting): plumb inertia_config via return value instead of app.state

* docs+scaffold: adopt app.state.sm + app.state.<module> convention

Add services.py.tpl template and register_settings scaffolding so new
modules store settings inside a typed Services dataclass at
app.state.<module_lower> rather than the old app.state.<module>_settings
flat attribute. Update framework-conventions.md with Framework state and
Module settings subsections reflecting the new pattern.

* fix(verify): migrate remaining app.state reads in test fixtures + lint fixes

* cleanup: simplify defensive guards + remove stale migration comments

Author: antosubash

conftest.py

@@ -125,7 +125,7 @@ async def app(settings: Settings):
 
     application = create_app(settings)
 
-    await _create_all_tables(application.state.db.engine)
+    await _create_all_tables(application.state.sm.db.engine)
 
     # Trigger lifespan startup so app.state.migration is populated
     ctx = application.router.lifespan_context(application)
@@ -146,7 +146,7 @@ async def client(app) -> AsyncGenerator[httpx.AsyncClient, None]:
     requests from anonymous test flows (login, accept-invite, register) pass
     validation without first making a GET to mint a token."""
     signed = forge_session_cookie(
-        app.state.settings.secret_key, {SESSION_CSRF_TOKEN_KEY: _TEST_CSRF_TOKEN}
+        app.state.sm.settings.secret_key, {SESSION_CSRF_TOKEN_KEY: _TEST_CSRF_TOKEN}
     )
     transport = httpx.ASGITransport(app=app)
     async with httpx.AsyncClient(
@@ -163,7 +163,7 @@ async def authenticated_client(app) -> AsyncGenerator[httpx.AsyncClient, None]:
     """HTTPX client with a signed session cookie carrying a seeded admin user's id."""
     from users.bootstrap import create_admin
 
-    async with app.state.db.session_factory() as session:
+    async with app.state.sm.db.session_factory() as session:
         result = await create_admin(
             session,
             email="admin@test",
@@ -173,7 +173,7 @@ async def authenticated_client(app) -> AsyncGenerator[httpx.AsyncClient, None]:
         user_id = str(result.user.id)
 
     signed = forge_session_cookie(
-        app.state.settings.secret_key,
+        app.state.sm.settings.secret_key,
         {"user_id": user_id, SESSION_CSRF_TOKEN_KEY: _TEST_CSRF_TOKEN},
     )
 

docs/framework-conventions.md

@@ -92,15 +92,34 @@ SM_DATABASE_URL, SM_ENVIRONMENT, SM_SECRET_KEY, SM_VITE_DEV_URL,
 SM_DEBUG, SM_LOG_LEVEL, SM_LOG_FORMAT, SM_MULTI_TENANT, SM_TENANT_HEADER
 ```
 
+### Framework state
+
+Framework singletons live on `app.state.sm`, a frozen `Services` dataclass populated
+once at boot. Consumers read `request.app.state.sm.<field>` — never raw `app.state`
+attributes for framework-owned state.
+
+Fields: `settings`, `db`, `event_bus`, `menu_registry`, `permissions`,
+`feature_flags`, `health_registry`, `i18n_registry`, `inertia_config`, `modules`.
+
+Two attributes are intentionally kept outside `Services`:
+
+- `app.state.inertia_dependency` — request-scoped `Depends` factory from fastapi-inertia.
+- `app.state.migration` — dev-only boot-time check result, set in lifespan.
+
+### Module settings
+
 Module settings should:
 - Use a per-module prefix: `SM_<MODULE>_*` (e.g. `SM_USERS_ALLOW_SIGNUP`).
-- Be stored on `app.state.<module>_settings` during `register_settings(app)`.
-- `SM012` diagnostic fires if `register_settings` is overridden but no `app.state.<module>_settings` is added.
+- Be stored inside a module-owned dataclass at `app.state.<module_lower>` during `register_settings(app)`.
+- `SM012` diagnostic fires if `register_settings` is overridden but no `app.state.<module_lower>` entry is added.
 
 ```python
-class AuthModule(ModuleBase):
+class UsersModule(ModuleBase):
     def register_settings(self, app: FastAPI) -> None:
-        app.state.auth_settings = AuthSettings()
+        from users.services import UsersServices
+        from users.settings import UsersSettings
+
+        app.state.users = UsersServices(settings=UsersSettings())
 ```
 
 ## Database