core-framework 0.3.0__tar.gz

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

@@ -0,0 +1,27 @@
+---
+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.
+- Routers call `validate_*` schema helpers before invoking application services.
+- Routers should remain thin and delegate business decisions to application/domain layers.
+
+## 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-0.3.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-0.3.0/.cursor/rules/api-security.mdc

@@ -0,0 +1,29 @@
+---
+description: Public and authenticated routes must not reveal user existence; only admin routes may return 404 for user not found
+globs:
+  - core_framework/api/**/router.py
+  - core_framework/application/**/*_service.py
+---
+
+# API Security: User Existence
+
+**User existence visibility**: Public and authenticated (non-admin) endpoints must NOT reveal whether a `user_id` exists. This prevents user enumeration attacks.
+Apply the rule by **response shape**, not HTTP method:
+- **List responses** (`list[...]`, paginated list items): returning an empty list for nonexistent users is acceptable.
+- **Non-list responses** (detail/object/single resource): apply default/non-enumerating behavior for public/authenticated routes and 404 behavior for admin detail routes.
+
+- **Public/authenticated non-list routes**: Do NOT return 404 for missing resources tied to user existence. Prefer a safe default payload/value; if no safe default exists, return a success for idempotent operations or a generic error (e.g. 400, 403) that does not disclose existence.
+- **Public/authenticated list routes**: returning empty lists is acceptable.
+- **Admin non-list routes**: Return 404 for missing single-resource lookups/details (user, profile, note, etc.).
+- **Admin list endpoints**: Returning an empty list for missing/nonexistent target users is acceptable.
+- **Admin DELETE endpoints**: Prefer idempotent behavior. Returning 204 when the target is already missing is acceptable.
+
+**Examples:**
+- Block non-existent user → 204 (silent success)
+- Unblock non-existent user → 204 (idempotent)
+- Report non-existent user → 204 or generic error, never 404
+- GET `/users/me/profile` with missing profile row → 200 with default profile payload
+- Admin GET /admin/users/{user_id} → 404 when user does not exist ✓
+- Admin profile lookup with missing profile → 404 ✓
+- Admin GET `/admin/users/{user_id}/change-history` for nonexistent user → 200 with `[]` is acceptable
+- Admin DELETE `/admin/users/{user_id}` when already missing → 204 is acceptable

core_framework-0.3.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-0.3.0/.cursor/rules/application-layer.mdc

@@ -0,0 +1,74 @@
+---
+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` or `Optional`, not by raising HTTP exceptions. How callers map "not found" depends on response shape and endpoint type:
+- **Admin non-list routes (detail/single-resource)**: convert missing resources to 404 (typically via `UserNotFoundException`).
+- **Admin list routes**: returning an empty list for nonexistent target users is acceptable.
+- **Admin DELETE routes**: idempotent 204 for already-missing resources is acceptable.
+- **Public/authenticated non-list routes**: return a safe default or non-enumerating response, not 404.
+- **Public/authenticated list routes**: returning an empty list is acceptable.
+- **Workers**: handle `None` according to their own logic.
+
+**Admin routes only**: For user lookups, admin services may raise `UserNotFoundException` (from `application.shared.exceptions`). The global exception handler converts it to 404. Do NOT use this in public or authenticated (non-admin) routes—see api-security rule.
+
+```python
+# ✅ Admin service: raise UserNotFoundException for user not found
+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 models. Routers use `response_model`; FastAPI converts the return value to the Pydantic model automatically.
+
+- **Do NOT** return Pydantic `BaseModel` subclasses from service functions
+- **Return** `dict`, `list[dict]`, dataclasses, or other JSON-serializable types
+- **Routers** declare `response_model`; FastAPI validates and serializes the service return value
+
+```python
+# ✅ CORRECT: Return dict or dataclass
+async def retrieve_users(...) -> list[dict[str, Any]]:
+    ...
+
+async def get_profile(...) -> Profile:  # dataclass
+    ...
+```
+
+## 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-0.3.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-0.3.0/.cursor/rules/domain-caller-context.mdc

@@ -0,0 +1,44 @@
+---
+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` ✅
+  - `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-0.3.0/.cursor/rules/domain-imports.mdc

@@ -0,0 +1,81 @@
+---
+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 (admin non-list -> 404, list responses may return empty lists, admin DELETE may return idempotent 204, public/authenticated non-list -> default or non-enumerating response).
+
+### 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`