core-framework 1.8.0__tar.gz → 2.0.0__tar.gz

core_framework-2.0.0/.cursor/rules/alembic-revision-ids.mdc

@@ -0,0 +1,39 @@
+---
+description: Alembic revision id format — short random hex, not descriptive slugs
+globs: alembic/**/alembic/versions/*.py
+alwaysApply: false
+---
+
+# Alembic revision IDs
+
+`alembic_version.version_num` is a **32-character** string. Revision ids must stay well under that limit.
+
+## New revisions (required)
+
+- Set `revision` to a **12-character lowercase hex** string (Alembic default), e.g. `a56bc6b7f799`.
+- Generate with `python -c "import secrets; print(secrets.token_hex(6))"` or `alembic revision`.
+- Put the human-readable slug in the **filename** and the module docstring `Revision ID:` line only if you mirror the hex id there — **do not** use descriptive slugs as `revision`.
+
+```python
+# ✅ Preferred
+"""replace deleted post status with tombstone statuses
+
+Revision ID: 120bf6be81eb
+Revises: a56bc6b7f799
+"""
+
+revision: str = "120bf6be81eb"
+```
+
+```python
+# ❌ Avoid — long, wastes version_num budget, inconsistent with recent migrations
+revision: str = "post_tombstone_status_model"
+```
+
+## Exceptions
+
+- Collapsed **`v1_*_init`** baseline revisions keep their stable names (`v1_post_init`, etc.) — do not rename shipped baselines.
+
+## Do not rename shipped revision ids
+
+If a revision may already be applied in any environment, **do not** change its `revision` string. Add a forward migration instead.

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

@@ -0,0 +1,46 @@
+---
+description: Anti-enumeration HTTP errors; uniform detail for indistinguishable outcomes
+globs:
+  - core_framework/api/**/router.py
+  - core_framework/application/**/*_service.py
+---
+
+# API Security: Missing resources and enumeration
+
+**Policy**: Limit what clients can infer about ids, resource types, and internal state from HTTP **`detail`** text and from distinguishable error bodies. Use **catalog generic `detail`** strings per **`client-error-visibility.mdc`**. See **`docs/platform/client-error-visibility.md`**.
+
+## Read-by-id and sensitive lookups
+
+When a client references a resource by id and the row is **missing, not visible, or withheld** from that viewer, prefer **one client-visible outcome** per endpoint class:
+
+- Same **HTTP status** where flow docs align cases (often **404**).
+- Same **`detail`** — **`GENERIC_NOT_FOUND_DETAIL`**, not resource-specific copy.
+
+This applies to public post/comment fetches, hidden/deleted/blocked cases documented as indistinguishable from unknown ids, and similar flows.
+
+**Admin** and **internal** routes may use clearer outcomes when the actor is trusted; document exceptions in flow docs.
+
+## Mutations and idempotency
+
+- **Idempotent** relationship writes (block, follow, report on missing target): **204** without leaking existence — already used for block/follow on unknown ids where documented.
+- **Idempotent DELETE** may return **204** when already gone.
+- Do not add resource-specific error text that helps bots map id validity.
+
+## List endpoints
+
+Returning an empty page (`items: []`) when nothing matches remains acceptable.
+
+## Explicit existence checks
+
+Endpoints designed to answer “does this username exist?” (and similar) are **intentional** product surface. Treat them as such: document, rate-limit, monitor — do not rely on generic errors on other routes to replace them.
+
+## Application vs domain signals
+
+- **Application** exceptions → handlers in **`setup.py`**; map to HTTP status; client **`detail`** may be useful fixed copy or catalog where approved — **per-type exposure TBD**.
+- **Typed domain** exceptions → **internal**; application translates to **`None`**, empty results, or application raises — never imported in API/application.
+- **`BaseXxxException`** → **500** catch-all only when a typed domain exception leaks past application (missing translation).
+- Do not raise or import domain **`PostNotFoundException`** / **`CommentNotFoundException`** from application; use application types when a detail route must error.
+
+## Self routes
+
+`GET /users/me/*` may use defaults or self-heal; document exceptions. Registration/login flows may create rows — not an enumeration vector for arbitrary ids.

{core_framework-1.8.0 → core_framework-2.0.0}/.cursor/rules/api-validation.mdc

@@ -99,9 +99,14 @@ class LoginRequest(BaseModel):
 4. **Add descriptive error messages** to help API consumers understand requirements
 5. **Document validation rules** in OpenAPI schema (automatically done by FastAPI/Pydantic)
 
+## Domain backstops
+
+Domain services may re-check the same rules for workers and defense-in-depth. Those failures must **not** become a second client messaging channel: **`DomainValidationError`** at HTTP returns **`GENERIC_BAD_REQUEST_DETAIL`** only. See **`client-error-visibility.mdc`** and **`docs/platform/client-error-visibility.md`**.
+
 ## 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`
+- Client error policy: `docs/platform/client-error-visibility.md`

{core_framework-1.8.0 → core_framework-2.0.0}/.cursor/rules/application-layer.mdc

@@ -15,14 +15,18 @@ Services must NOT handle HTTP concerns. They are shared by both API and worker c
 - **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
+- **Do NOT** import or raise **domain exceptions** (typed or base) — see **`domain-imports.mdc`**
 
-**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.
+**Signal outcomes** by returning `None`/`Optional`/empty collections, or by raising **application** exceptions from **`application.shared.exceptions`**. **Which application types expose client `detail` is TBD** per type and surface.
+
+- **Admin routes that load a user row for a detail payload**: missing user → **`UserNotFoundException`** (application) when the service resolves that user and signals not found (handler exposure **TBD**).
+- **Public detail routes for posts/comments by id**: missing/unavailable → **`ContentNotFoundException`** (application), or return **`None`** when the router maps not-found — **not** domain **`PostNotFoundException`** / **`CommentNotFoundException`**.
 - **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.
+- **Workers**: handle `None` or swallow expected domain-side failures according to job policy; do not let typed domain exceptions escape to HTTP.
+
+Translate domain failures inside application orchestration — domain services may raise typed exceptions internally, but application must not import those types. Prefer domain methods that return plain outcomes where that avoids exception coupling.
 
 ```python
 # ✅ Raise UserNotFoundException when a referenced user id has no row (after strong read when required)
@@ -41,8 +45,17 @@ async def get_some_resource(*, resource_id: str) -> dict | None:
 async def retrieve_user_detail(*, user_id: UserID) -> dict[str, Any]:
     if not found:
         raise HTTPException(status_code=404, detail="User not found")  # ❌
+
+# ❌ WRONG: domain exception in application
+from core_framework.domains.post import PostNotFoundException  # ❌
 ```
 
+## Application exceptions
+
+- Raise types from **`application.shared.exceptions`** for HTTP-meaningful use-case outcomes — not **`HTTPException`**, not typed domain exceptions.
+- Types include **`ContentNotFoundException`**, **`ConflictException`**, ingest exceptions, and other application boundary types in that module.
+- **Client `detail` exposure** for each type (and public vs admin) is **TBD** — use fixed reviewed copy in handlers when exposing; do not rely on ad-hoc **`message=`** at raise sites long term.
+
 ## 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.

core_framework-2.0.0/.cursor/rules/client-error-visibility.mdc

@@ -0,0 +1,75 @@
+---
+description: Application-owned HTTP errors; domain typed exceptions internal; base catch-all only
+globs:
+  - core_framework/core/exception_handlers/**/*.py
+  - core_framework/domains/**/exceptions.py
+  - core_framework/domains/**/*.py
+  - core_framework/application/**/*.py
+  - core_framework/infrastructure/**/*.py
+  - core_framework/api/**/*.py
+---
+
+# Client error visibility
+
+Platform contract: **`docs/platform/client-error-visibility.md`**. Enumeration policy: **`api-security.mdc`**. Import boundaries: **`domain-imports.mdc`**.
+
+## Layer model
+
+| Layer | Outward errors | HTTP |
+|-------|----------------|------|
+| **Application** | **`application.shared.exceptions`** | Handlers map type → status + `detail` (**TBD** per type) |
+| **Domain typed** | Internal only — **not** imported by API/application | No typed handlers (target) |
+| **Domain `BaseXxxException`** | Exported for handlers only | **500** catch-all if leaked |
+| **API** | Pydantic | **422** |
+
+## Application exceptions
+
+- **Only** channel for HTTP-meaningful use-case outcomes from orchestration.
+- **May** expose client-useful fixed copy where product approves — **which types/surfaces TBD**.
+- Prefer fixed reviewed handler strings — not ad-hoc per-call-site **`exc.message`**.
+- Application **must not** import or raise typed domain exceptions.
+
+## Domain exceptions (internal)
+
+- **Typed** exceptions inherit that domain's **`BaseXxxException`** (`PostNotFoundException`, etc.) — each **`BaseXxxException`** subclasses **`BaseDomainException`**.
+- **`DomainValidationError`** inherits **`BaseDomainException`** (`domains/exceptions.py`) — domain-only; dedicated handler → **`GENERIC_BAD_REQUEST_DETAIL`** (400).
+- **`setup.py`** registers one **`BaseDomainException`** leak handler (**500**) and **`Exception`** unmapped handler (**500**).
+- **`__init__.py` exports only `BaseXxxException`** per domain — not typed subclasses, not **`DomainValidationError`**.
+- Leaked typed exception → **`BaseDomainException`** handler → **`GENERIC_INTERNAL_SERVER_ERROR_DETAIL`** (500).
+
+## Catalog constants (`exception_handlers.common`)
+
+| Constant | Status |
+|----------|--------|
+| **`GENERIC_BAD_REQUEST_DETAIL`** | 400 |
+| **`GENERIC_NOT_FOUND_DETAIL`** | 404 |
+| **`GENERIC_FORBIDDEN_DETAIL`** | 403 |
+| **`GENERIC_CONFLICT_DETAIL`** | 409 |
+| **`GENERIC_INGEST_BODY_TOO_LARGE_DETAIL`** | 413 |
+| **`GENERIC_INGEST_UNSUPPORTED_MEDIA_TYPE_DETAIL`** | 415 |
+| **`GENERIC_INTERNAL_SERVER_ERROR_DETAIL`** | 500 |
+
+Application handlers use catalog and/or approved fixed copy.
+
+## Anti-enumeration
+
+- No resource-type phrases in catalog **`detail`** on public routes unless application exposure explicitly approves.
+- Align missing / hidden / forbidden to the same catalog **`detail`** on read-by-id routes when flow docs require it.
+
+## HTTP validation first
+
+Shape, limits, duplicates, self-block, self-follow → **API schemas/routers** (422 or catalog 400). Domain backstops → **`DomainValidationError`** → generic 400 at handler.
+
+## Logging
+
+**Do not** **`logger.error`** at every domain **`raise`**.
+
+| Tier | Handler log |
+|------|-------------|
+| Expected application 4xx | omit or **debug** |
+| **`DomainValidationError`** | **warning** or **info** |
+| **`BaseXxxException`** / unmapped | **error** / **exception** |
+
+## When editing
+
+Apply to new handlers and touched raise sites. Repo-wide migration only when scoped to client error visibility or exception boundary work.

{core_framework-1.8.0 → core_framework-2.0.0}/.cursor/rules/code-review-output.mdc

@@ -13,6 +13,7 @@ When the user asks for a **review**, **audit**, or similar (e.g. "review my code
 - **Wrong** behavior vs design docs, API contracts, or project rules
 - **Improvements** and **optimizations** worth making
 - **Contradictions** between code and documented intent (including doc drift)
+- **Parallel implementation drift** — sibling modules or flows with the same job but different structure (async layout, cleanup ordering, serialization, error/idempotency contracts) without a documented reason; see the **code-review** skill checklist
 
 Prioritize by severity. Include enough context (file, behavior, suggested fix direction) to act on each item.
 

{core_framework-1.8.0 → core_framework-2.0.0}/.cursor/rules/domain-caller-context.mdc

@@ -31,9 +31,8 @@ Domain layer names must describe domain concepts and data semantics, not who cal
   - `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` ✅
+  - `tombstone_post` ✅
+  - `detach_post_authors_by_author_id` ✅
 - Prefer naming by data shape or business rule, not persona:
   - `select_post_with_metadata_by_id` ✅
   - `retrieve_user_for_detail` ✅

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

@@ -0,0 +1,124 @@
+---
+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, constants from __init__.py
+from core_framework.domains.moderation import AppealDecision, RestrictionType
+from core_framework.domains.moderation import UserModeration, UserRestriction
+
+from core_framework.domains.user import UserRole, BlockedUser, Profile
+```
+
+**Do not import domain exceptions** in API or application — typed or base. Application uses **`application.shared.exceptions`**. Exception handlers import **`BaseDomainException`** and **`DomainValidationError`** from **`domains.exceptions`** only (single leak + backstop wiring).
+
+Translate domain outcomes in application via **`None`**, empty collections, or application exception raises after domain service calls — not by catching typed domain exceptions.
+
+### 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 domain exceptions in API or application
+```python
+# WRONG: No domain exceptions in API/application
+from core_framework.domains.post import PostNotFoundException  # ❌
+from core_framework.domains.moderation import AppealAlreadyDecidedException  # ❌
+from core_framework.domains.user import BaseUserException  # ❌
+from core_framework.domains.post.exceptions import PostNotFoundException  # ❌
+```
+
+### DO NOT import directly from other 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.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**: Typed domain exceptions are internal control-flow signals
+2. **Application boundary**: Outward HTTP errors live in **`application.shared.exceptions`**
+3. **Maintainability**: Domain exception refactors do not break application/API
+4. **Clear boundaries**: API/application access models/enums/services — not domain error types
+5. **Leak detection**: Only **`BaseXxxException`** handlers at HTTP; leaks → **500**
+
+## Domain `__init__.py` export policy
+
+Export a symbol from a domain's **`__init__.py`** only when an outer layer needs it.
+
+- **Do export**: models, enums, constants consumed by API, application, or adapters.
+- **Exceptions**: export **only** **`BaseXxxException`** per domain (subclasses **`BaseDomainException`**; used for typing and domain-internal inheritance — **not** for per-domain HTTP handler registration).
+- **Do not export**: persistence/registry shapes, repository row mappings, typed exceptions, and other types used only inside **`domains/<name>/`**.
+
+Every **typed** exception defined under a domain must **inherit** from that domain's **`BaseXxxException`**. **`DomainValidationError`** is the shared backstop in **`domains/exceptions.py`**: it inherits **`BaseDomainException`** (cross-domain root), **not** a per-domain **`BaseXxxException`**. Handler wiring imports **`DomainValidationError`** from **`domains.exceptions`** in core only — it is not exported from domain **`__init__.py`**.
+
+When adding a new exception, default to **internal** (`exceptions.py` only). Add **`BaseXxxException`** to **`__init__.py`** when the domain needs a typed base for internal inheritance — never export the typed subclasses. HTTP leak detection uses the shared **`BaseDomainException`** handler, not per-domain handler modules.
+
+## Available Domain Exports
+
+### Moderation Domain (`from core_framework.domains.moderation import ...`)
+- **Enums**: `RestrictionType`, `AppealDecision`, `ReportType`
+- **Models**: `Report`, `UserModeration`, `UserRestriction`
+- **Outcomes**: `AddAppealOutcome`, `AddUserReportOutcome`, `DecideAppealOutcome`
+- **Exceptions**: `BaseModerationException` only (handler catch-all)
+- **Service**: Use `moderation_service` from `dependencies.py`
+- **Internal** (not in `__init__.py`): `AppealNotFoundException`, `AppealAlreadyDecidedException`, `SelfReportException`, `ExistingPendingAppealException`, `AppealRequirementException`, and other typed exceptions
+
+### User Domain (`from core_framework.domains.user import ...`)
+- **Enums**: `UserRole`
+- **Models**: `CreatedUser`, `BlockedUser`, `Profile`, `UserIdentity`
+- **Outcomes**: `AddUserOutcome`, `BlockUserOutcome`, `ChangeAccountOutcome`, `FollowUserOutcome`
+- **Exceptions**: `BaseUserException` only (handler catch-all)
+- **Service**: Use `user_service` from `dependencies.py`
+- **Internal** (not in `__init__.py`): `DomainUserNotFoundException`, `SelfBlockException`, `UserIdConflictException`, `UsernameConflictException`, `UserCreationException`
+
+### Post Domain (`from core_framework.domains.post import ...`)
+- **Outcomes**: `PostEditOutcome`
+- **Exceptions**: `BasePostException` only (handler catch-all)
+- **Internal**: `PostNotFoundException`, edit-limit types, and all other typed exceptions
+
+### Comment Domain (`from core_framework.domains.comment import ...`)
+- **Outcomes**: `CommentEditOutcome`, `ReplyCreateOutcome`
+- **Exceptions**: `BaseCommentException` only (handler catch-all)
+- **Internal**: `CommentNotFoundException`, edit-limit types, and all other typed exceptions
+
+### Media Domain (`from core_framework.domains.media import ...`)
+- **Constants**: ingest limits, variant constants
+- **Models**: `AvatarIngestRegistration`, `AvatarVariantBytes`, etc.
+- **Outcomes**: `IngestContentTypeOutcome`, `IngestBodyOutcome`, `IngestLeaseOutcome`, `AttachmentStagingImageProbeOutcome`
+- **Exceptions**: `BaseMediaException` only (handler catch-all)
+- **Internal**: ingest, staging, and publish typed exceptions
+- **Internal** (not in `__init__.py`): `AvatarStagingRegistryEntry`, `AttachmentStagingRegistryEntry`
+
+## How to Fix Violations
+
+If application needs to signal an HTTP outcome after a domain call:
+
+1. **Return `None` or empty** when the use case allows it (lists, optional reads, idempotent deletes).
+2. **Raise an application exception** from **`application.shared.exceptions`** (add a type if needed).
+3. **Extend the domain service API** so typed exceptions are absorbed inside the domain and the caller sees a plain outcome — do not export the typed exception.
+
+Repositories are only wired for domain services and tests. Application code never imports them.

{core_framework-1.8.0 → core_framework-2.0.0}/.cursor/rules/domain-input-guards.mdc

@@ -11,7 +11,7 @@ Use **layered** checks: user contracts at the **API**, business preconditions at
 
 ## Policy: validate in the service; database is last line of defense
 
-- **Domain services** should enforce **policy and contract** as much as practical **before** data reaches Postgres: sane limits, non-negative counts where required, empty batches with obvious safe behavior, meaningless argument combinations, etc. Goals: clear errors (`DomainValidationError` or domain-specific exceptions), fail fast, and **one** contract for HTTP, workers, and future callers.
+- **Domain services** should enforce **policy and contract** as much as practical **before** data reaches Postgres: sane limits, non-negative counts where required, empty batches with obvious safe behavior, meaningless argument combinations, etc. Goals: fail fast with **`DomainValidationError`** (internal/backstop — HTTP **`GENERIC_BAD_REQUEST_DETAIL`**) or **typed domain exceptions** (internal control flow — application translates to outward outcomes), and **one** contract for workers and future callers.
 - **Do not rely** on CHECK, NOT NULL, FK, or UNIQUE as the *main* way invalid **application** input is caught when the service can reject it cheaply. Constraints still **must** exist where they express **data integrity** (what must never be stored wrong).
 - **Database constraints** remain **mandatory failsafes**: bugs, race conditions, code that bypasses the service, ad-hoc scripts, or missed branches. When they fire, treat that as exceptional—log/monitor and map or handle integrity errors appropriately; prefer never to depend on that path for normal validation UX.
 
@@ -27,7 +27,7 @@ Use **layered** checks: user contracts at the **API**, business preconditions at
 - **Purpose:** Preconditions and policy that apply to **any** caller that correctly uses **`{Domain}Service`** as the entrypoint.
 - **Prefer guards here** for rules like: “empty batch → default mapping / skip query,” “limit in allowed range,” “counts non-negative,” “this combination of arguments is meaningless.”
 - Keeps **repositories thin** (data access + SQL) and gives **one** canonical place for domain rules above persistence.
-- Prefer **early return** when the safe behavior is obvious (e.g. empty `comment_ids` → empty map). Use **`DomainValidationError`** (or a domain-specific exception with a registered handler) when invalid input is a **caller** mistake that should not become **500** at HTTP boundaries.
+- Prefer **early return** when the safe behavior is obvious (e.g. empty `comment_ids` → empty map). Use **`DomainValidationError`** when invalid input is a **caller** mistake that must not become **500** — HTTP maps it to generic **400**. Use **typed domain exceptions** for in-domain non-500 control flow; application translates before HTTP — typed exceptions are **not** exported or registered as HTTP handlers (see **`client-error-visibility.mdc`**). User-fixable **input shape** belongs in API Pydantic validation (**422**) first.
 
 ### Shared string / pagination helpers (`core_framework.domains.utils`)
 
@@ -38,7 +38,7 @@ Use these across domains so validation stays consistent and call sites stay read
 | Helper | Use when |
 |--------|----------|
 | **`require_non_blank(value=..., field=...)`** | A single required string must not be empty or whitespace-only. |
-| **`require_non_blank_kwargs(a_id=..., b_id=...)`** | Several required strings at once; each **keyword name** is the field label in `DomainValidationError` (e.g. `author_id=author_id, content=content`). |
+| **`require_non_blank_kwargs(a_id=..., b_id=...)`** | Several required strings at once; each **keyword name** is the field label in internal `DomainValidationError` messages (for logs — not forwarded to HTTP **`detail`**). |
 | **`require_non_blank_if_not_none(viewer_id=..., ...)`** | Optional `str \| None` arguments: validate only when not `None` (still rejects `""`). |
 | **`validate_pagination_limit(limit=...)`** | Paginated reads: `limit` in `[1, MAX_PAGE_FETCH_SIZE]` (aligned with `core_framework.core.pagination`). |
 | **`validate_pagination_offset(offset=...)`** | Paginated reads: `offset` must be **≥ 0** (aligned with `OffsetQueryParams`). |
@@ -65,7 +65,7 @@ Prefer **`require_non_blank_kwargs`** / **`require_non_blank_if_not_none`** over
 | Layer              | Role |
 |--------------------|------|
 | API (Pydantic)     | User input, **422**, documented request contract |
-| **Domain service** | **Primary** business preconditions for all service callers; validate before persistence where practical |
+| **Domain service** | **Primary** business preconditions for all service callers; validate before persistence where practical; HTTP sees generic **400** for **`DomainValidationError`** unless API already validated |
 | Repository         | **Optional** narrow checks before catastrophic / meaningless SQL |
 | Database           | **Ultimate** integrity; last line of defense—not relied on for normal invalid-input UX |
 

core_framework-2.0.0/.cursor/rules/exception-handlers.mdc

@@ -0,0 +1,59 @@
+---
+description: FastAPI exception handler registration and typing conventions
+globs:
+  - core_framework/core/exception_handlers/**/*.py
+---
+
+# Exception Handlers
+
+HTTP exception handlers live under **`core_framework/core/exception_handlers/`**.
+
+## Registration
+
+- Register handlers with **`register_exception_handler`** from **`core_framework.core.exception_handlers.common`**.
+- Do **not** call **`app.add_exception_handler`** directly from handler modules or **`setup.py`**.
+- Starlette’s **`ExceptionHandler`** type is wider than narrowly typed handlers; the single **`ty: ignore[invalid-argument-type]`** belongs in **`common.register_exception_handler`** only.
+
+## Handler channels
+
+### Application exceptions (`setup.py`)
+
+- Register types from **`application.shared.exceptions`**.
+- Map **type → HTTP status**; **`detail`** per application exposure policy (**TBD**; catalog generics and/or fixed reviewed strings).
+- Register **specific** application types before any application base catch-all if one is added later.
+
+### Domain exceptions (catch-all only)
+
+- Every **`BaseXxxException`** subclasses **`BaseDomainException`** (`domains/exceptions.py`). Typed domain exceptions inherit **`BaseXxxException`**.
+- Register **one** **`base_domain_leak_exception_handler`** on **`BaseDomainException`** in **`setup.py`** → **500** + **`GENERIC_INTERNAL_SERVER_ERROR_DETAIL`** + **error**/**exception** log.
+- **`DomainValidationError`** also subclasses **`BaseDomainException`** but has a dedicated **400** handler registered on the subclass (MRO picks it before the leak handler).
+- Typed domain exceptions must **not** have dedicated HTTP handlers; if one leaks past application, the **`BaseDomainException`** handler fires.
+
+### Unmapped exceptions
+
+- Register **`unmapped_exception_handler`** on **`Exception`** in **`setup.py`** after application and domain handlers — **500** catalog for bugs outside mapped types. Framework types (**`HTTPException`**, **`RequestValidationError`**) keep their own handlers via exact-type lookup.
+
+### `DomainValidationError`
+
+- Wired from **`core_framework.domains.exceptions`** (internal import — not domain **`__init__.py`** export).
+- Subclasses **`BaseDomainException`** (shared root) — **not** **`BasePostException`** / per-domain leak bases.
+- **400** + **`GENERIC_BAD_REQUEST_DETAIL`**; log at **warning**/**info** — not **`exc.message`** in **`detail`**.
+- Separate from the **`BaseDomainException`** leak handler (**500**); a **`DomainValidationError`** does not trigger leak detection.
+
+## Handler functions
+
+- One async handler per mapped exception type: **`(Request, ExcT) -> JSONResponse`**.
+- Type **`exc`** as the **specific** registered exception (not bare **`Exception`**).
+- Handlers translate exception → HTTP response only — no business logic or repository calls.
+- **Do not** log at **error** for expected application 4xx unless the task explicitly requires it.
+
+## Module layout
+
+- **`setup.py`** registers application handlers, **`DomainValidationError`**, **`BaseDomainException`** leak handler, and **`Exception`** unmapped handler.
+- Do **not** add per-domain handler modules for **`BasePostException`** / **`BaseUserException`** etc. — one **`BaseDomainException`** registration covers all domain leaks.
+
+## Avoid
+
+- Registering typed domain exceptions as HTTP handlers in new code.
+- Importing typed domain exceptions into handler modules.
+- Per-call-site **`ty: ignore[invalid-argument-type]`** or **`cast(ExceptionHandler, ...)`** on registrations.

core_framework-2.0.0/.cursor/rules/inline-raise-messages.mdc

@@ -0,0 +1,46 @@
+---
+description: Raise exceptions with inline message strings; do not assign msg solely for the raise on the next line.
+globs: ["core_framework/**/*.py", "tests/**/*.py"]
+---
+
+# Inline raise messages
+
+Do **not** assign an exception message to a variable on the line immediately before `raise` when that variable exists only to pass the string into the exception.
+
+## Preferred
+
+```python
+# ✅ Single-line message
+raise ValueError("title must not be empty or whitespace-only")
+
+# ✅ f-string
+raise ValueError(f"resource must be one of: {allowed}")
+
+# ✅ Long message — parenthesized string on raise (still no msg variable)
+raise RuntimeError(
+    "Core runtime is not configured on app.state. "
+    "Build the app via init_app() or assign app.state.core_runtime during bootstrap."
+)
+```
+
+## Avoid
+
+```python
+# ❌ Two-line raise solely to hold the message
+msg = "title must not be empty or whitespace-only"
+raise ValueError(msg)
+
+# ❌ Same for other exception types
+msg = f"no alembic.ini for domain {domain!r}"
+raise FileNotFoundError(msg)
+```
+
+## When a local message variable is OK
+
+- The **same** message string is reused more than once before raising.
+- The message is **built incrementally** across multiple statements (not a single literal/f-string assignment).
+
+## When editing
+
+- Apply this style to **new** raises and to any `raise` you touch in the same function or validator.
+- Do not repo-wide rewrite unrelated legacy raises unless the task asks for it.

{core_framework-1.8.0 → core_framework-2.0.0}/.cursor/rules/layer-boundaries.mdc

@@ -25,6 +25,7 @@ Use this architecture split consistently:
 - Domain layer must not import API, worker, or application modules.
 - Domain layer must not import global infrastructure except in `dependencies.py`.
 - Repositories are Postgres-only; filesystem, HTTP, SSH, and similar I/O use domain ports/adapters (separate collaborators), not repository methods.
+- Repositories must not query other domains' Postgres schemas — see **`repository-schema-isolation`**.
 - Application orchestrates multi-step flows; do not fold shared API+worker orchestration into domain services to avoid “application” existing.
 
 ## Dependency Direction

core_framework-2.0.0/.cursor/rules/repository-schema-isolation.mdc

@@ -0,0 +1,72 @@
+---
+description: Domain repositories must not query other domains' Postgres schemas
+globs:
+  - core_framework/domains/**/repository.py
+alwaysApply: false
+---
+
+# Repository schema isolation
+
+Each domain repository may only read/write tables in **its own** Postgres schema.
+
+Canonical rule: `docs/platform/layers-and-boundaries.md` — *no cross-domain schema reads, writes, joins, or foreign keys*.
+
+## Allowed in a repository
+
+- SQL qualified with that domain's schema only (e.g. `"post".posts` in `PostRepository`).
+- **Within-schema** policy gates (e.g. `insert_post_like` checks `"post".posts.status = active`).
+- **Lookup mirrors** in the same schema (`user_blocks_lookup`, `user_restrictions_lookup`, `user_followers_lookup`) — synced by application flows; mirrors are not authoritative.
+
+## Forbidden in a repository
+
+- `FROM` / `JOIN` / `EXISTS` / `INSERT … SELECT` against another domain's schema.
+- Importing another domain's `service`, `repository`, or models to enforce policy.
+
+```python
+# ❌ moderation/repository.py — cross-domain EXISTS
+insert into "moderation".post_reports (...)
+select $1, $2, $3, $4
+where exists (
+    select 1 from "post".posts
+    where id = $2 and status = 'active'
+)
+
+# ❌ notification/repository.py — cross-domain mute gate
+insert into "notification".notification_mutes (...)
+select ...
+where exists (select 1 from "comment".comments where ...)
+```
+
+## Alembic migrations (different convention)
+
+Do **not** apply repository schema-qualification rules to `alembic/**/versions/*.py`.
+
+Each domain Alembic tree sets `search_path` to that domain's schema in `env.py`. Migration SQL uses **unqualified** table and type names (`posts`, `post_reports`, `create type post_status …`) — not `"post".posts`.
+
+Cross-domain rules still apply to migrations:
+
+- No `REFERENCES` / FKs to tables in another domain's schema.
+- No DDL that reads or writes another domain's objects.
+
+Stay within the migration tree's domain; one schema per Alembic env.
+
+## Where cross-domain policy belongs
+
+**Application layer** (or domain service orchestration via dependencies, never cross-schema SQL):
+
+```python
+# ✅ application/posts/authenticated_service.py
+post = await post_deps.post_service.retrieve_post_with_metadata_by_id_if_exists(post_id=post_id)
+if post is None or post.status != PostStatus.ACTIVE:
+    return False
+return await moderation_deps.moderation_service.add_post_report(...)
+```
+
+Before adding a repository write that depends on another domain's row state:
+
+1. Can the owning domain gate it within its schema? → do that (likes, views, stats dirty).
+2. Otherwise → gate in `application/**/*_service.py` via the owning domain's service API.
+
+## Self-check (repositories only)
+
+In `domains/<name>/repository.py`, every `"<schema>".` qualifier in SQL must be `<name>` (or that domain's documented mirror tables in the same schema).

{core_framework-1.8.0 → core_framework-2.0.0}/.cursor/skills/add-config/SKILL.md

@@ -41,17 +41,21 @@ Use quotes for strings, no quotes for numbers/booleans/arrays.
 
 ## 4. Deploy Workflow (`.github/workflows/_deploy.yml`)
 
-Add to the `env` block in "Render config.toml from template" step:
+Add to the `env` block in "Render config.toml from template" step. Use **secrets** for credentials/tokens/keys; use **variables** for non-sensitive config (hosts, ports, public hostnames, paths):
 
 ```yaml
 env:
   # existing vars...
-  NEW_SETTING: ${{ secrets.NEW_SETTING }}
+  NEW_SETTING: ${{ vars.NEW_SETTING }}       # non-sensitive
+  NEW_SECRET: ${{ secrets.NEW_SECRET }}     # password, token, or private key
 ```
 
+See **`docs/deployments/deploy-playbook.md`** for the current secrets vs variables split.
+
 ## Reminder
 
-After completing all steps, remind the user to add the secret to GitHub:
+After completing all steps, remind the user to add the value to GitHub:
 
-- Settings → Secrets and variables → Actions → Environment secrets
-- Add to both `development` and `production` environments
+- **Variables:** Settings → Secrets and variables → Actions → Environments → **`development`** / **`production`** → Variables
+- **Secrets:** same path → Environment secrets
+- Add to **both** environments when the value differs per deploy target

{core_framework-1.8.0 → core_framework-2.0.0}/.cursor/skills/add-domain/SKILL.md

@@ -181,7 +181,7 @@ Worker `startup` and API `init_app` already call `configure_application_dependen
 
 Do this in a **separate step/PR** when you have DDL to apply.
 
-1. Add **`alembic/<domain>/alembic/versions/*.py`** (at least one revision); `upgrade()` may create schema/tables/enums as designed.
+1. Add **`alembic/<domain>/alembic/versions/*.py`** (at least one revision); `upgrade()` may create schema/tables/enums as designed. Use a **12-character lowercase hex** `revision` id (see **`alembic-revision-ids`**); put the descriptive slug in the filename only.
 1. **Append** `<domain>` to `ALEMBIC_DOMAINS` in `core_framework/bundled_alembic.py` **in the same change** as the first revision (so `cf-alembic` / CI stay green).
 1. `make alembic` and deploy’s `cf-alembic` step pick up the new domain automatically — no makefile or `_deploy.yml` edits needed.