core-framework 0.17.59__tar.gz → 1.2.0__tar.gz

core_framework-1.2.0/.cursor/rules/api-layer.mdc

@@ -0,0 +1,37 @@
+---
+description: API layer should contain HTTP adapters only
+globs:
+  - core_framework/api/**/*.py
+---
+
+# API Layer Conventions
+
+The API layer is an HTTP adapter, not a business-logic layer.
+
+## Scope
+
+- Keep API files focused on routers, schemas, and HTTP dependencies.
+- API code may call application services in `core_framework/application/...`.
+- API code must not contain orchestration shared with workers.
+
+## Router Responsibilities
+
+- Routers own HTTP concerns: status codes, `HTTPException`, `response_model`, request parsing.
+- When a route sets **`response_model`**, annotate the handler return type as **`typing.Any`** (OpenAPI documents the real shape; the handler may return dicts or model-adjacent values before serialization). Routes with no response body (for example **`204`** and no **`response_model`**) continue to use **`None`**.
+- Routers call `validate_*` schema helpers before invoking application services.
+- Routers should remain thin and delegate business decisions to application/domain layers.
+
+## Route decorators (OpenAPI)
+
+- Do **not** set **`summary=`** or **`description=`** on **`@router.get`**, **`post`**, **`patch`**, **`put`**, **`delete`**, or **`APIRoute`-style** registrations. Rely on paths, handler names, **`response_model`**, and Pydantic schemas. Do **not** add route **docstrings** for the same purpose either (see **`no-docstrings`**).
+
+## Response Models
+
+- **Do not** use bare collection types (e.g. `list[Item]`) as `response_model`. Wrap them in a named response `BaseModel` with an **`items`** field (e.g. `class FooListResponse(BaseModel): items: list[FooItem]`).
+- This keeps responses extensible (pagination, counts, metadata) without breaking the contract.
+
+## What to Avoid
+
+- Do NOT implement reusable business workflows in API modules.
+- Do NOT import domain internals directly; follow domain public API and dependencies rules.
+- Do NOT place worker-only logic (scheduling/task orchestration) in API modules.

core_framework-1.2.0/.cursor/rules/api-reference-docs.mdc

@@ -0,0 +1,31 @@
+---
+description: docs/api.md is a minimal API index only
+globs:
+  - docs/api.md
+---
+
+# API Reference (docs/api.md)
+
+`docs/api.md` is strictly for **quick viewing** of available APIs. It is an index, not detailed documentation.
+
+## Format
+
+- One line per endpoint: `METHOD path # Short description`
+- Group by domain/section (Auth, Users, Posts, etc.)
+- No additional content below the endpoint list
+
+## What to INCLUDE
+
+- Endpoint method and path
+- Brief description in the comment (one short phrase)
+
+## What to EXCLUDE
+
+- Request/response body formats
+- Header documentation
+- Error codes
+- Links to other docs
+- Any prose or bullet lists
+- Detailed behavior notes
+
+For detailed API behavior, create or update flow documentation in `docs/flows/` instead.

core_framework-1.2.0/.cursor/rules/api-security.mdc

@@ -0,0 +1,18 @@
+---
+description: Prefer 404 when a referenced resource does not exist; list endpoints may return empty collections
+globs:
+  - core_framework/api/**/router.py
+  - core_framework/application/**/*_service.py
+---
+
+# API Security: Missing resources
+
+**Policy**: When a client references a resource by id (user, post, comment, report, etc.) and that resource does not exist, **prefer HTTP 404** with a clear not-found message unless a different contract is explicitly documented (e.g. idempotent `DELETE` returning 204 when already gone, or list endpoints returning `[]`).
+
+This codebase **does not** optimize for hiding whether ids exist (no user-enumeration-by-status-code policy). Prefer **404** when code resolves an id to a stored row and finds nothing: e.g. **application** `UserNotFoundException` for admin user detail; **domain** `PostNotFoundException` / `CommentNotFoundException` for public post/comment fetches. Other flows (block, unblock, user report, etc.) follow domain and repository behavior without an extra application-layer identity preflight unless a route’s contract says otherwise.
+
+**List endpoints**: Returning an empty page (`items: []`) for queries that match nothing remains acceptable.
+
+**Self routes** (e.g. `GET /users/me/profile`): Prefer sensible defaults or 404 only if the contract says the row must exist; registration/self-heal flows may still create or patch missing rows—document any exception.
+
+**Admin routes**: Same default—404 for missing single-resource lookups unless the endpoint is explicitly list-shaped or idempotent-delete.

core_framework-1.2.0/.cursor/rules/api-validation.mdc

@@ -0,0 +1,107 @@
+---
+description: API layer must validate all fields that have database constraints
+globs: ["core_framework/api/**/*.py"]
+---
+
+# API Validation Rule
+
+## Principle: Fail Fast at the API Layer
+
+Any field that has a database constraint (CHECK, NOT NULL, UNIQUE, foreign key, etc.) MUST be validated at the API layer before reaching the database.
+
+## Why
+
+1. **Better User Experience**: Return clear 422 Validation Error instead of 500 Internal Server Error
+2. **Clearer Error Messages**: Pydantic validation errors are more user-friendly than database constraint violation errors
+3. **Fail Fast**: Catch invalid data early in the request lifecycle
+4. **Better Monitoring**: API validation failures are easier to track than database errors
+5. **Reduced Database Load**: Invalid requests don't reach the database
+
+## Examples
+
+### ✅ Good: Validate at API Layer
+
+Database constraint:
+```sql
+country_code varchar(2) not null,
+constraint country_code_format check (country_code ~ '^[A-Z]{2}$')
+```
+
+API validation:
+```python
+import re
+from typing import Annotated
+
+from pydantic import BaseModel, Field, field_validator
+
+# Using Field with pattern
+class LoginRequest(BaseModel):
+    country_code: Annotated[
+        str,
+        Field(
+            default="XX",
+            pattern="^[A-Z]{2}$",
+            description="ISO 3166-1 alpha-2 country code",
+        )
+    ]
+
+# Or using field_validator for complex validation
+@field_validator("country_code")
+@classmethod
+def validate_country_code(cls, v: str) -> str:
+    if not re.match(r"^[A-Z]{2}$", v):
+        raise ValueError("country_code must be 2 uppercase letters")
+    return v
+```
+
+### ❌ Bad: No API Validation
+
+```python
+class LoginRequest(BaseModel):
+    # This will cause a database constraint violation
+    country_code: str = "invalid"  # No validation!
+```
+
+## Common Database Constraints to Validate
+
+### 1. **CHECK Constraints**
+- Length limits: `varchar(50)` → `Field(max_length=50)`
+- Format patterns: `check (email ~ '^[^@]+@[^@]+$')` → `EmailStr` or `Field(pattern="...")`
+- Value ranges: `check (age >= 0)` → `Field(ge=0)`
+- Enum values: `check (status in ('active', 'inactive'))` → Python `Enum`
+
+### 2. **NOT NULL Constraints**
+- Required fields: `not null` → Don't use `| None`, or use `Field(..., required=True)`
+
+### 3. **UNIQUE Constraints**
+- Validate uniqueness where possible (e.g., check username availability before insert)
+- Consider caching frequently checked unique values (like usernames)
+
+### 4. **Foreign Key Constraints**
+- Validate referenced entities exist before insert/update
+- Use proper error messages: "User not found" instead of "Foreign key violation"
+
+### 5. **Length Constraints**
+- String lengths: `varchar(255)` → `Field(max_length=255)`
+- Array sizes: `text[] check (array_length(...) <= 5)` → validate list length
+
+## When NOT to Validate
+
+- **Free-form text fields** with no constraints (e.g., `text` columns with no CHECK)
+- **System-generated values** (e.g., timestamps, auto-increment IDs)
+- **Internal fields** not exposed in the API
+
+## Implementation Guidelines
+
+1. **Review migrations** when creating API endpoints to identify all constraints
+2. **Use Pydantic validators** for complex validation logic
+3. **Use Field constraints** for simple validations (pattern, min/max, length)
+4. **Add descriptive error messages** to help API consumers understand requirements
+5. **Document validation rules** in OpenAPI schema (automatically done by FastAPI/Pydantic)
+
+## Related Files
+
+- Database migrations: `alembic/*/alembic/versions/*.py`
+- API schemas: `core_framework/api/*/schemas.py`
+- User shared schemas: `core_framework/api/users/shared/schemas.py`
+- Auth schemas: `core_framework/api/auth/schemas.py`

core_framework-1.2.0/.cursor/rules/application-layer.mdc

@@ -0,0 +1,79 @@
+---
+description: Application services must be transport-agnostic and return plain Python types
+globs:
+  - core_framework/application/**/*_service.py
+---
+
+# Application Layer Service Conventions
+
+Services in the application layer (`core_framework/application/**/*_service.py`) are used by both HTTP routers and workers. They must remain transport-agnostic.
+
+## No HTTP Handling
+
+Services must NOT handle HTTP concerns. They are shared by both API and worker code.
+
+- **Do NOT** raise `HTTPException` or any FastAPI/Starlette HTTP types
+- **Do NOT** import from `fastapi` for HTTP-specific logic (status codes, responses)
+- **Do NOT** assume the caller is an HTTP request
+
+**Signal "not found"** by returning `None`/`Optional` or by raising **domain** exceptions that have registered global handlers (e.g. `PostNotFoundException`, `CommentNotFoundException`)—never `HTTPException`. How callers map "not found" depends on response shape and endpoint type:
+- **Admin routes that load a user row for a detail payload**: missing user → **404** via `UserNotFoundException` (`application.shared.exceptions`) when the service resolves that user and signals not found.
+- **Public detail routes for posts/comments by id**: missing row → domain service raises `PostNotFoundException` / `CommentNotFoundException`; handlers map to 404.
+- **Admin list routes**: returning an empty list when a filter matches nothing is acceptable.
+- **Admin DELETE routes**: idempotent 204 for already-missing resources is acceptable when the contract is delete-by-id.
+- **Public/authenticated list routes**: returning an empty list is acceptable.
+- **Workers**: handle `None` or propagate domain exceptions according to job policy.
+
+```python
+# ✅ Raise UserNotFoundException when a referenced user id has no row (after strong read when required)
+async def retrieve_user_detail(*, user_id: UserID) -> dict[str, Any]:
+    if user_data is None:
+        raise UserNotFoundException()
+    return {"identity": ..., "moderation": ...}
+
+# ✅ Other routes: return None when resource not found
+async def get_some_resource(*, resource_id: str) -> dict | None:
+    if not found:
+        return None
+    return {...}
+
+# ❌ WRONG: HTTP in service layer
+async def retrieve_user_detail(*, user_id: UserID) -> dict[str, Any]:
+    if not found:
+        raise HTTPException(status_code=404, detail="User not found")  # ❌
+```
+
+## No Pydantic Models as Return Types
+
+Services must return plain Python types—not Pydantic API/response `BaseModel` subclasses. Routers use `response_model`; FastAPI converts the return value to the Pydantic model automatically.
+
+- **Do NOT** return Pydantic `BaseModel` subclasses from application service functions
+- **Do** return `dict`, `list[dict]`, **domain dataclasses**, or other JSON-serializable values
+- **Routers** declare `response_model`; FastAPI validates and serializes the service return value
+
+### Dict vs domain dataclass
+
+- **Domain dataclass** when a single domain type (or a homogeneous `list` of domain rows) already matches the **`response_model` field layout**. Pass it through; no hand-built dict. Examples in this repo: `retrieve_my_preferences` → `Preferences`; `retrieve_my_profile` → `Profile`; `retrieve_my_username_suggestions` → `list[UsernameSuggestion]` with items compatible with `UserReference`.
+- **`dict[str, Any]`** (or `list[dict[…]]`) when the HTTP payload is **assembled** from several sources or **does not** map 1:1 to one domain type. Example: `retrieve_my_account` merges `UserIdentity` fields with Firebase email fields into a dict that matches `AccountResponse`.
+
+```python
+# ✅ Dict: composed payload, not one domain row
+async def retrieve_my_account(...) -> dict[str, Any]:
+    return {"username": ..., "email": ..., ...}
+
+# ✅ Domain dataclass: same shape as response_model (FastAPI adapts)
+async def retrieve_my_profile(*, user_id: str) -> Profile: ...
+
+async def retrieve_my_username_suggestions(...) -> list[UsernameSuggestion]: ...
+```
+
+## Keyword-only arguments
+
+- Application service functions (and private helpers in `*_service.py` modules) must use **keyword-only** parameters after a `*` separator, matching the domain layer convention.
+- Exception: zero-argument functions (e.g. `retrieve_admin_user_ids()`).
+
+## Validation in Schemas, Not Services
+
+- Input validation (`validate_user_id`, `validate_report_id`, etc.) belongs in schemas
+- Services do NOT raise `RequestValidationError` or import from `fastapi.exceptions`
+- Routers call `validate_*` from schemas before invoking services

core_framework-1.2.0/.cursor/rules/constants-final.mdc

@@ -0,0 +1,15 @@
+---
+description: Prefer typing.Final for module-level constants (not reassigned)
+globs: core_framework/**/*.py
+alwaysApply: false
+---
+
+# Module-level constants and `Final`
+
+When introducing or editing **module-level constants** (values that are fixed for the lifetime of the module and not meant to be reassigned):
+
+- Annotate them with **`typing.Final`** and an explicit type, e.g. **`NAME: Final[int] = 42`** or **`_INTERNAL: Final[str] = "henry"`**.
+- Prefer **`FrozenSet`**, **`frozenset` literals**, **`MappingProxyType`**, or immutable collections for grouped constants when mutation must be prevented — e.g. **`USER_PREFERENCE_UPDATE_COLUMNS`** in **`core_framework/domains/user/constants.py`**.
+- **`Final`** is for **assignment** semantics (no rebinding): it does not freeze mutable object contents unless the type/container is immutable.
+
+Do not refactor unrelated legacy constants only to add **`Final`** unless you are already touching that symbol.

core_framework-1.2.0/.cursor/rules/database-triggers.md

@@ -0,0 +1,207 @@
+# Database Triggers Rule
+
+## Core Principle
+
+**Database triggers MUST ONLY be used for audit/history tracking. Business logic MUST NEVER be implemented in triggers.**
+
+## When to Use Triggers
+
+✅ **ACCEPTABLE USE CASES:**
+
+1. **Audit Logging**
+
+   - Tracking who changed what and when
+   - Recording old and new values for compliance
+   - Capturing actor information (who made the change)
+
+1. **Change History**
+
+   - Building immutable audit trails
+   - Tracking modifications for regulatory compliance
+   - Recording metadata about changes
+
+1. **Read-Only Operations**
+
+   - Operations that don't affect business outcomes
+   - Recording timestamps of state changes
+   - Logging events for analytics (non-critical)
+
+## When NOT to Use Triggers
+
+❌ **NEVER USE TRIGGERS FOR:**
+
+1. **Business Logic**
+
+   - Validation rules (e.g., "users can only change username once per week")
+   - State transitions (e.g., "muted users cannot be warned")
+   - Conditional workflows (e.g., "send notification if X happens")
+   - Data transformations (e.g., "normalize phone numbers on insert")
+
+1. **Side Effects**
+
+   - Sending notifications
+   - Calling external APIs
+   - Updating related records based on business rules
+   - Enforcing complex constraints
+
+1. **Calculations**
+
+   - Computing derived values
+   - Aggregating data
+   - Updating summary tables
+
+## Why This Rule Exists
+
+1. **Testability**: Triggers are difficult to test in isolation and require database setup
+1. **Visibility**: Logic hidden in triggers is invisible during code review
+1. **Debugging**: Trigger failures are harder to diagnose than application errors
+1. **Maintainability**: Changing triggers requires database migrations and coordination
+1. **Performance**: Triggers add overhead to every write operation, affecting all callers
+1. **Complexity**: Trigger interactions can create subtle bugs and unexpected behavior
+
+## Examples
+
+### ✅ Good: Audit Logging
+
+```sql
+-- ACCEPTABLE: Audit trail for username changes
+create or replace function log_user_update_change()
+returns trigger as $$
+begin
+    if new.username is distinct from old.username then
+        insert into "user".user_change_history (
+            user_id, actor_id, entity_type, field, old_value, new_value
+        )
+        values (
+            new.user_id,
+            current_setting('app.actor_id', true),
+            'users',
+            'username',
+            old.username,
+            new.username
+        );
+    end if;
+    return new;
+end;
+$$ language plpgsql;
+```
+
+**Why this is acceptable:**
+
+- Records historical information without affecting business logic
+- Doesn't prevent or modify the original operation
+- Fails silently if logging fails (doesn't block the transaction)
+- Pure audit trail - no business decisions are made
+
+### ❌ Bad: Business Logic in Trigger
+
+```sql
+-- DON'T DO THIS: Username change cooldown validation
+create or replace function enforce_username_cooldown()
+returns trigger as $$
+begin
+    if new.username != old.username then
+        if exists (
+            select 1 from user_change_history
+            where user_id = new.user_id
+              and field = 'username'
+              and created_at > now() - interval '7 days'
+        ) then
+            raise exception 'Username can only be changed once per week';
+        end if;
+    end if;
+    return new;
+end;
+$$ language plpgsql;
+```
+
+**Why this is bad:**
+
+- Implements business rule (cooldown period)
+- Prevents operation from completing
+- Validation should be in service layer
+- Can't be easily tested or modified
+- Error message isn't localized
+- Makes assumptions about business rules
+
+**Correct approach:**
+
+```python
+# In service layer
+async def change_profile(
+    self,
+    *,
+    actor_id: str,
+    user_id: str,
+    validated_update_request: dict[str, Any],
+) -> None:
+    if "username" in validated_update_request:
+        recent_changes = await self.repository.select_recent_username_changes(
+            user_id=user_id, since=datetime.now(timezone.utc) - timedelta(days=7)
+        )
+        if recent_changes:
+            raise UsernameCooldownException()
+
+    await self.repository.update_profile(
+        user_id=user_id,
+        validated_update_request=validated_update_request,
+        actor_id=actor_id,
+    )
+```
+
+### ❌ Bad: Automatic State Transitions
+
+```sql
+-- DON'T DO THIS: Auto-approve appeals from first-time offenders
+create or replace function auto_approve_first_offense()
+returns trigger as $$
+begin
+    if tg_op = 'INSERT' then
+        if (select count(*) from restriction_history where user_id = new.user_id) = 1 then
+            update moderation_appeals
+            set status = 'approved', decided_at = now()
+            where user_id = new.user_id and status = 'pending';
+        end if;
+    end if;
+    return new;
+end;
+$$ language plpgsql;
+```
+
+**Why this is bad:**
+
+- Implements business policy (auto-approval rules)
+- Makes decisions that should be explicit in application code
+- Side effect (updating appeals table) is invisible to callers
+- Business rule changes require database migration
+- Can't be A/B tested or feature-flagged
+
+## When in Doubt
+
+**Ask yourself:**
+
+1. "Does this trigger make a business decision?" → If yes, move to application layer
+1. "Would I need to change this if business requirements change?" → If yes, move to application layer
+1. "Does this trigger prevent or modify the operation?" → If yes, move to application layer
+1. "Is this purely recording what happened?" → If yes, trigger is acceptable
+
+## Enforcement
+
+If an AI assistant (like me) suggests using a trigger for business logic, I should:
+
+1. **Stop and remind you** of this rule
+1. **Suggest the application-layer alternative**
+1. **Only proceed with trigger** if you explicitly confirm it's for audit/history only
+
+If you ask for a trigger for business logic, I should:
+
+1. **Flag the violation** of this rule
+1. **Explain why it's problematic**
+1. **Propose an application-layer implementation instead**
+
+## Related Documentation
+
+- `docs/database-triggers.md` - **Catalog of all triggers** (update when adding new triggers)
+- `docs/conventions.md` - Database Triggers section
+- `docs/architecture-decisions.md` - Triggers Only for Audit/History
+- `docs/flows/users/change_history.md` - Example of proper trigger usage

core_framework-1.2.0/.cursor/rules/domain-caller-context.mdc

@@ -0,0 +1,45 @@
+---
+description: Prevent caller-context leakage in domain layer naming
+globs:
+  - core_framework/domains/**/*.py
+  - core_framework/domains/**/README.md
+alwaysApply: false
+---
+
+# Domain Caller-Context Boundary
+
+Domain layer names must describe domain concepts and data semantics, not who calls them.
+
+## Do Not Encode Caller Context
+
+- Avoid role/channel/adapter names in domain symbols: `Admin*`, `Public*`, `Authenticated*`, `Api*`, `Worker*`, `Http*`.
+- Avoid method names like `*_for_admin`, `*_for_public`, `*_for_api`, `*_for_worker`.
+- Avoid transport words in domain interfaces: `request`, `response`, `router`, `endpoint`, `status_code`.
+
+## Allowed Domain Semantics
+
+- Domain names may still use role/status/visibility words when they describe the entity or filter itself, not the caller.
+- Examples:
+  - `UserRole.ADMIN` ✅
+  - `select_admin_user_ids` when it means "users whose role is admin" ✅
+  - `PostVisibility.PUBLIC` ✅
+
+## Preferred Naming
+
+- Use policy/data-shape naming:
+  - `select_posts_unfiltered` ✅
+  - `select_comments_unfiltered` ✅
+  - `PostWithMetadata` ✅
+- Use constraint-oriented naming for variants:
+  - `update_post_status_by_id` ✅
+  - `update_post_status_by_id_and_author` ✅
+  - `set_post_status_for_author` ✅
+- Prefer naming by data shape or business rule, not persona:
+  - `select_post_with_metadata_by_id` ✅
+  - `retrieve_user_for_detail` ✅
+- Keep caller-specific naming in API/application layers only.
+
+## Review Checklist
+
+- If a domain model or method name implies caller identity, flag it as boundary leakage.
+- Suggest neutral alternatives based on behavior, constraint, or data shape (not caller type).

core_framework-1.2.0/.cursor/rules/domain-imports.mdc

@@ -0,0 +1,83 @@
+---
+description: Enforce importing from domain __init__.py in API/application layers
+globs:
+  - core_framework/api/**/*.py
+  - core_framework/application/**/*.py
+---
+
+# Domain Import Rules
+
+When importing from domain layers (`core_framework/domains/*`) into the API/application layers (`core_framework/api/*`, `core_framework/application/*`), you MUST follow these rules:
+
+## ✅ Allowed Imports
+
+### 1. Import from domain `__init__.py` (Public API)
+```python
+# CORRECT: Import enums, models, exceptions from __init__.py
+from core_framework.domains.moderation import AppealDecision, RestrictionType
+from core_framework.domains.moderation import UserModeration, UserRestriction
+from core_framework.domains.moderation import BaseModerationException, AppealNotFoundException
+
+from core_framework.domains.user import UserRole, BlockedUser, Profile
+from core_framework.domains.user import BaseUserException, UserIdConflictException
+```
+
+**Domain exception boundary**: Some domain exceptions (e.g. `DomainUserNotFoundException`) are internal—not exported in `__init__.py` and must not be imported or raised outside their domain. Use `None` or `Optional` return values instead; callers map missing values by endpoint policy and response shape (e.g. admin user detail → `UserNotFoundException` → 404; list responses may return empty lists; admin DELETE may return idempotent 204).
+
+### 2. Import from `dependencies.py` (Dependency Injection)
+```python
+# CORRECT: Import services from dependencies
+from core_framework.domains.moderation.dependencies import moderation_service
+from core_framework.domains.user.dependencies import user_service
+```
+
+## ❌ Prohibited Imports
+
+### DO NOT import directly from internal domain modules
+```python
+# WRONG: Don't import from internal modules
+from core_framework.domains.moderation.models import UserModeration  # ❌
+from core_framework.domains.moderation.enums import AppealDecision   # ❌
+from core_framework.domains.moderation.exceptions import AppealNotFoundException  # ❌
+from core_framework.domains.moderation.repository import ModerationRepository  # ❌
+from core_framework.domains.moderation.service import ModerationService  # ❌
+
+from core_framework.domains.user.models import BlockedUser  # ❌
+from core_framework.domains.user.enums import UserRole  # ❌
+from core_framework.domains.user.exceptions import DomainUserNotFoundException  # ❌
+from core_framework.domains.user.repository import UserRepository  # ❌
+from core_framework.domains.user.service import UserService  # ❌
+```
+
+## Why This Rule Exists
+
+1. **Encapsulation**: The `__init__.py` defines the public API of each domain
+2. **Maintainability**: Internal refactoring doesn't break the API layer
+3. **Clear boundaries**: API layer only accesses what the domain explicitly exports
+4. **Consistency across adapters**: API and application layers follow the same domain import contract
+5. **Dependency direction**: Prevents tight coupling to internal implementation details
+
+## Available Domain Exports
+
+### Moderation Domain (`from core_framework.domains.moderation import ...`)
+- **Enums**: `RestrictionType`, `AppealDecision`, `ReportType`
+- **Models**: `Report`, `UserModeration`, `UserRestriction`
+- **Exceptions**: `BaseModerationException`, `AppealNotFoundException`, `AppealAlreadyDecidedException`, `SelfReportException`, `ExistingPendingAppealException`, `AppealRequirementException`
+- **Service**: Use `moderation_service` from `dependencies.py`
+
+### User Domain (`from core_framework.domains.user import ...`)
+- **Enums**: `UserRole`
+- **Models**: `CreatedUser`, `BlockedUser`, `Profile`, `UserIdentity`
+- **Exceptions**: `BaseUserException`, `SelfBlockException`, `UserIdConflictException`, `UsernameConflictException`, `UserCreationException`
+- **Service**: Use `user_service` from `dependencies.py`
+- **Internal** (do not import from API layer): `DomainUserNotFoundException` — handled within domain; API uses `None` return values
+
+## How to Fix Violations
+
+If you need something that's not exported in `__init__.py`:
+
+1. **Check if it should be public**: If it's needed by the API layer, add it to the domain's `__init__.py`
+2. **Reconsider the design**: If it's internal implementation, maybe the API layer shouldn't access it directly
+3. **Use the service**: Most domain logic should be accessed through `{domain}_service` from `dependencies.py`
+
+Repositories (e.g. `UserRepository`) are only wired for domain services and tests. Application code never imports them, so persistence entrypoints like `UserRepository.update_*` always go through `UserService`, which applies PATCH validation.