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

core_framework-2.2.0/.agents/skills/fastapi

@@ -0,0 +1 @@
+../../.venv/lib/python3.14/site-packages/fastapi/.agents/skills/fastapi

core_framework-2.2.0/.agents/skills/library-skills/.library-skills.json

@@ -0,0 +1,4 @@
+{
+  "kind": "tool-skill",
+  "version": "0.0.19"
+}

core_framework-2.2.0/.agents/skills/library-skills/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: library-skills
+description: Use Library Skills to discover, install, refresh, repair, check, and manage agent skills from installed packages.
+---
+
+# Library Skills
+
+Use this skill when a project might benefit from agent skills bundled by its installed packages, or when existing Library Skills-managed symlinks are stale, broken, orphaned, or need to be checked.
+
+Run commands from the project root.
+
+Agents bundle their own skills by including an `.agents/skills` directory. More details in [Library Skills](https://library-skills.io).
+
+## First-Time Setup
+
+- Make sure project dependencies are installed first, for example with `uv sync` for Python projects or `npm install` / `bun install` for Node.js projects.
+- Run `uvx library-skills` or `npx library-skills` to discover skills bundled by the installed packages and install selected skills interactively.
+- Use `uvx library-skills --all` or `npx library-skills --all` only when all newly discovered skills should be installed without selecting individual skills.
+- Use `uvx library-skills --tool-skill` or `npx library-skills --tool-skill` to copy this Library Skills tool skill into the project so future agents know how to discover, install, update, repair, and check skills.
+
+## Commands
+
+- Run `uvx library-skills` or `npx library-skills` to discover package-provided skills, install selected new skills, and reconcile existing managed symlinks.
+- Run `uvx library-skills list` or `npx library-skills list` to inspect discovered and installed skills.
+- Run `uvx library-skills list --json` or `npx library-skills list --json` for machine-readable installed status.
+- Run `uvx library-skills scan --json` or `npx library-skills scan --json` for discovery-only automation.
+- Run `uvx library-skills --check` or `npx library-skills --check` to validate managed skill symlink state without changing files.
+- Run `uvx library-skills --yes` or `npx library-skills --yes` to repair stale managed symlinks and remove orphaned managed symlinks non-interactively.
+- Add `--claude` when `.claude/skills` should also be managed.
+- Add `--skill NAME` to install a specific discovered skill by name.
+
+## Safety
+
+- Prefer rerunning `library-skills` over editing managed symlinks manually.
+- If installed skill symlinks are broken, dependencies may not be installed yet. Try the project's normal install command first, such as `uv sync`, `npm install`, or `bun install`, then rerun `library-skills`.
+- Do not delete or overwrite hand-authored skill directories.
+- Library Skills only removes managed symlinks. It should not remove copied or hand-authored skill directories.

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

@@ -0,0 +1,36 @@
+---
+description: Core-framework API architecture — HTTP adapters only. FastAPI/Pydantic patterns in the fastapi skill.
+globs:
+  - core_framework/api/**/*.py
+---
+
+# API layer (core-framework)
+
+**Framework patterns:** use the **fastapi** skill (`.agents/skills/fastapi/`) — `Annotated`, dependencies, routers, Pydantic v2, CLI.
+
+**Validation:** **`api-validation.mdc`**. **Errors:** **`error-boundary.mdc`**. **Domain imports:** **`domain-imports.mdc`**.
+
+## Architecture
+
+The API layer is an HTTP adapter, not a business-logic layer.
+
+- Routers, schemas, and HTTP dependencies only.
+- Call **application** services in `core_framework/application/...` — not domain repositories.
+- No orchestration shared with workers; no worker-only logic here.
+
+## 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 shape; services may return dicts or domain types). Body-less routes (**`204`**, no **`response_model`**) use **`None`**.
+- Call `validate_*` schema helpers before invoking application services.
+- Do **not** set **`summary=`** or **`description=`** on route decorators or use route docstrings for OpenAPI prose — paths, handler names, **`response_model`**, and schemas suffice.
+
+## Response models
+
+- Do **not** use bare collection types (e.g. `list[Item]`) as `response_model`. Wrap in a named `BaseModel` with an **`items`** field for extensibility.
+
+## Avoid
+
+- Reusable business workflows in API modules.
+- Direct imports from domain internals (only `__init__.py` and `dependencies.py`).
+- `ORJSONResponse` / `UJSONResponse` — use return types / `response_model` per the fastapi skill.

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

@@ -0,0 +1,22 @@
+---
+description: API layer must validate all fields that have database constraints
+globs: ["core_framework/api/**/*.py"]
+---
+
+# API validation
+
+Any field with a database constraint (CHECK, NOT NULL, UNIQUE, FK, length) **must** be validated at the API layer before Postgres — return **422**, not **500** from constraint violations.
+
+## How
+
+1. Review migrations when adding endpoints; mirror constraints in Pydantic (`Field`, `field_validator`, enums).
+2. Map common patterns: `varchar(n)` → `max_length`, CHECK patterns → `pattern`/`EmailStr`, enums → Python `Enum`, required → no bare `| None`.
+3. Skip validation only for unconstrained free text, system-generated fields, and internal-only values.
+
+## Layer split
+
+- **API** — client contract, **422**, OpenAPI accuracy.
+- **Domain service** — business preconditions for all callers (workers too); see **`domain-input-guards.mdc`**.
+- Domain backstops must not become a second client channel: **`DomainValidationError`** → **`GENERIC_BAD_REQUEST_DETAIL`** per **`error-boundary.mdc`**.
+
+Canonical doc: **`docs/platform/client-error-visibility.md`**.

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

@@ -0,0 +1,29 @@
+---
+description: Application services must be transport-agnostic and return plain Python types
+globs:
+  - core_framework/application/**/*_service.py
+---
+
+# Application layer
+
+Application services orchestrate use cases shared by API and workers. They stay transport-agnostic.
+
+## No HTTP concerns
+
+- Do not import FastAPI/Starlette types, `HTTPException`, `RequestValidationError`, status codes, request/response classes, or background task types.
+- Do not assume the caller is HTTP.
+- Input shape validation belongs in API schemas/routers; services handle use-case orchestration.
+
+## Outcomes
+
+- Return plain Python/domain values: `dict`, `list[dict]`, dataclasses, primitives, `None`, or empty collections.
+- Do not return API/Pydantic `BaseModel` instances.
+- Signal HTTP-meaningful failures with **`application.shared.exceptions`** or plain outcomes (`None`, empty), never typed domain exceptions. Full boundary contract: **`error-boundary.mdc`**.
+
+Use a domain dataclass when one domain row matches the response shape; use a `dict` when the payload is composed from several sources.
+
+## Function shape
+
+- Use keyword-only arguments after `*` for application service functions and private helpers.
+- Zero-argument functions are exempt.
+- Use one-line docstrings only; see **`docstrings.mdc`**.

core_framework-2.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] = "example"`**.
+- Prefer **`FrozenSet`**, **`frozenset` literals**, **`MappingProxyType`**, or immutable collections for grouped constants when mutation must be prevented — e.g. **`ProfileUpdate.UPDATE_COLUMNS`** on domain update types.
+- **`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-2.2.0/.cursor/rules/constitution.mdc

@@ -0,0 +1,42 @@
+---
+description: Core non-negotiables — behavior, tech stack, layer direction, host scope
+alwaysApply: true
+---
+
+# Constitution
+
+## Behavior
+
+- State assumptions; ask when unclear. Prefer the simplest correct solution.
+- Touch only what the task requires. Match existing style. Remove orphans your edits create.
+- Define verifiable success criteria for non-trivial work.
+- **Inline small single-use helpers** — do not extract a private function used once and only a few lines (identifier quoting, a short SQL fragment, pass-through wrappers). Extract when the logic is **reused**, **~15+ lines / non-obvious branching**, or a scoped rule requires sharing (e.g. normal + `*_strong` repository reads in **`strong-reads.mdc`**). Do not repo-wide refactor unrelated existing helpers.
+
+## Tech stack
+
+- Python 3.14, Pydantic v2, PostgreSQL 18, orjson (not stdlib json).
+- Absolute imports only (`from core_framework....`). Comma-style `except A, B:` is intentional.
+- Prefer newer APIs (`asyncio.TaskGroup` over `gather`).
+
+## Layers
+
+Dependencies point inward: API/worker → application → domain. Never reverse.
+
+- **API/worker** — transport adapters; call application services.
+- **Application** — orchestration shared by API + worker; no FastAPI types.
+- **Domain** — models, repositories (Postgres only), services. No API/worker/application imports except wiring in `dependencies.py`.
+
+Path-scoped rules under `.cursor/rules/` add detail (API, domains, docs, etc.). For FastAPI/Pydantic work in `core_framework/api/`, use the **fastapi** skill (`.agents/skills/fastapi/`).
+
+## Agent skills
+
+- Package skills (for example **fastapi**) are Library Skills-managed symlinks under **`.agents/skills/<name>/`**. Rules and hand-authored skills reference that path, not a copied tree under **`.cursor/skills/`**.
+- **`.cursor/skills/<name>`** may symlink to **`.agents/skills/<name>`** for Cursor; Library Skills repairs **`.agents/skills`** links when packages move. After **`uv sync`** or a dependency upgrade, run **`uvx library-skills --yes`** if symlinks are stale.
+
+## Host applications
+
+Do not edit consuming host repos in the same task as core-framework work unless the user scopes work to a host or asks to sync/upgrade. See the **sync-host-rules** skill.
+
+## Feature implementation
+
+Greenfield features (DB → API → repository → service → tests): use the **implement-feature** skill — one layer per response unless the user says otherwise.

core_framework-2.2.0/.cursor/rules/database-triggers.mdc

@@ -0,0 +1,23 @@
+---
+description: Triggers are for audit/history only — never business logic
+globs:
+  - alembic/**/alembic/versions/*.py
+  - docs/domains/**/*.md
+alwaysApply: false
+---
+
+# Database triggers
+
+**Triggers are for audit/history tracking only.** Never implement business logic, validation policy, side effects, or state transitions in triggers.
+
+## Acceptable
+
+- Immutable change history, actor/timestamp capture, read-only audit rows that do not block the original operation.
+
+## Not acceptable
+
+- Validation that prevents writes, conditional workflows, notifications, cross-table business updates, derived calculations.
+
+Enforce policy in domain services and application orchestration instead. When adding an audit trigger, update **`docs/platform/database-triggers.md`**.
+
+Full rationale: **`docs/platform/conventions.md`** and **`docs/platform/architecture-decisions.md`**.

core_framework-2.2.0/.cursor/rules/docstrings.mdc

@@ -0,0 +1,29 @@
+---
+description: Docstring depth by layer — one-line in application, full Args/Returns/Raises in domain and infrastructure
+globs:
+  - core_framework/application/**/*.py
+  - core_framework/domains/**/*.py
+  - core_framework/infrastructure/**/*.py
+---
+
+# Docstrings by layer
+
+Docstring depth follows the layer boundary.
+
+- **Application** (`core_framework/application/`): one short sentence. No `Args`, `Returns`, or `Raises` sections.
+- **Domain** (`core_framework/domains/`): full docstrings on public service, repository, component, and port methods that implement or define behavior.
+- **Infrastructure** (`core_framework/infrastructure/`): same as domain; document I/O side effects and failure modes.
+
+## Domain/infrastructure contract
+
+Use `Args`, `Returns`, and `Raises` when they clarify the boundary. Repositories should document non-obvious query semantics (filters, empty results, strong vs normal reads).
+
+## When editing
+
+- New functions follow the style for their layer.
+- When changing an existing function, update only that function's docstring if it is out of style.
+- Do not repo-wide migrate unrelated docstrings unless the task asks for it.
+
+## Out of scope
+
+API routers/schemas rely on OpenAPI and Pydantic. Worker wrappers follow application style.

core_framework-2.2.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` ✅
+  - `select_comments_unfiltered` ✅
+  - `PostWithMetadata` ✅
+- Use constraint-oriented naming for variants:
+  - `tombstone_post` ✅
+  - `detach_post_authors_by_author_id` ✅
+- Prefer naming by data shape or business rule, not persona:
+  - `select_post_with_metadata_by_id_if_exists` ✅
+  - `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-2.2.0/.cursor/rules/domain-imports.mdc

@@ -0,0 +1,44 @@
+---
+description: Enforce importing from domain __init__.py in API/application layers
+globs:
+  - core_framework/api/**/*.py
+  - core_framework/application/**/*.py
+---
+
+# Domain imports
+
+When importing from **`core_framework/domains/*`** in API or application code:
+
+## Allowed
+
+- Public symbols from domain **`__init__.py`** (models, enums, constants, outcomes).
+- Services from **`dependencies.py`** (e.g. **`user_service`**).
+
+## Prohibited
+
+- Typed or base **domain exceptions** in API/application — use **`application.shared.exceptions`**. Full policy: **`error-boundary.mdc`**.
+- Direct imports from internal modules (`models`, `enums`, `repository`, `service`, `exceptions`).
+
+```python
+# ✅
+from core_framework.domains.user import Profile, UserRole
+from core_framework.domains.user.dependencies import user_service
+
+# ❌
+from core_framework.domains.post import PostNotFoundException
+from core_framework.domains.user.models import Profile
+```
+
+## Export policy
+
+Export from **`__init__.py`** only what outer layers need. Typed exceptions stay internal; export **only** **`BaseXxxException`** per domain for inheritance typing — not for per-domain HTTP handlers. **`DomainValidationError`** lives in **`domains/exceptions.py`** (core handler wiring only).
+
+To see what a domain exports, check its **`__init__.py`** **`__all__`**.
+
+## After a domain call
+
+1. Return **`None`** or empty when the use case allows.
+2. Raise an **application** exception when HTTP must signal failure.
+3. Extend the domain service API to absorb typed exceptions internally.
+
+Application code never imports repositories. Exception boundary: **`error-boundary.mdc`**.

core_framework-2.2.0/.cursor/rules/domain-input-guards.mdc

@@ -0,0 +1,32 @@
+---
+description: Where to place input guards—API validation vs domain service vs repository vs database
+globs:
+  - core_framework/domains/**/service.py
+  - core_framework/domains/**/repository.py
+---
+
+# Domain input guards
+
+Use layered checks:
+
+- **API/Pydantic**: client contract, **422**, OpenAPI accuracy. See **`api-validation.mdc`**.
+- **Domain service**: primary business preconditions for all callers (HTTP, workers, scripts).
+- **Repository**: thin SQL/data access; only rare SQL-specific safety checks.
+- **Database**: mandatory integrity failsafe, not the normal invalid-input UX path.
+
+## Service policy
+
+- Enforce cheap, clear domain preconditions before persistence: empty batches, pagination bounds, non-negative counts, non-blank required strings, meaningless argument combinations.
+- Prefer early return when safe behavior is obvious.
+- Use **`DomainValidationError`** for caller mistakes that must not become 500; HTTP maps it to generic 400 per **`error-boundary.mdc`**.
+- Typed domain exceptions remain internal control flow; application translates before HTTP.
+
+Use shared helpers in **`core_framework.domains.utils`** (`require_non_blank*`, `validate_pagination_*`, `require_positive_int`) rather than repeating validation logic.
+
+## Repository policy
+
+- Do not duplicate service guards in repositories.
+- Do not use repositories as the main home for product rules.
+- Keep CHECK/NOT NULL/FK/UNIQUE constraints where they express truth in the data model; service checks do not replace them.
+
+When refactoring, move guards toward the service instead of growing repository-only validation.

core_framework-2.2.0/.cursor/rules/domain-repository-exceptions.mdc

@@ -0,0 +1,23 @@
+---
+description: When domain repositories vs services raise domain exceptions (thin façade)
+globs:
+  - core_framework/domains/**/*.py
+---
+
+# Domain: repository exceptions vs service
+
+Canonical HTTP/application boundary: **`error-boundary.mdc`**. Application and API must not import or handle typed domain exceptions.
+
+## Thin service + single persistence step
+
+When a **`Service`** method in **`core_framework/domains/*/service.py`** only performs **shared input guards** (e.g. **`require_*`**, **`validate_pagination_limit`**) **and** delegates to **one** repository call with **no branching** afterward, the repository may raise typed domain exceptions for persistence error outcomes (empty `RETURNING`, unexpected row absence on insert).
+
+That propagation is **intra-domain only**. Methods that **application** or **workers** call must **not** leak typed exceptions outward — absorb them inside the service (return **`None`**, outcomes, or **`bool`**) or branch before re-raising. See **`error-boundary.mdc`**.
+
+## Prefer service-side translation when
+
+- The service **composes multiple** repository calls, **branches** on outcomes, or maps the same SQL outcome to **different domain errors**.
+- The method is an **application-callable** entrypoint (anything imported via **`dependencies.py`** and used from **`core_framework/application/`** or **`core_framework/api/`**).
+- Keeping the repository purely “data shaped” (**`Optional`** / **`bool`**) materially improves reuse or clarity for **multiple** service entrypoints calling the same repository method.
+
+Existing domains may mix both styles; use this guide for **new work** and when **refactoring** a call site for clarity.

core_framework-2.2.0/.cursor/rules/error-boundary.mdc

@@ -0,0 +1,56 @@
+---
+description: HTTP error boundaries — application vs domain exceptions, handlers, anti-enumeration
+globs:
+  - core_framework/core/exception_handlers/**/*.py
+  - core_framework/application/**/*.py
+  - core_framework/api/**/router.py
+  - core_framework/api/**/schemas.py
+  - core_framework/domains/**/exceptions.py
+---
+
+# Error boundary
+
+Platform contract: **`docs/platform/client-error-visibility.md`**. Domain imports: **`domain-imports.mdc`**.
+
+## Layers
+
+| Layer | Outward errors | HTTP |
+|-------|----------------|------|
+| **Application** | **`application.shared.exceptions`**, **`InvalidPageTokenError`** | Handlers map type → status + `detail` |
+| **Domain typed** | Internal — not imported by API/application | No typed handlers |
+| **Domain `BaseXxxException`** | Handler catch-all only | **500** if leaked |
+| **API** | Pydantic | **422** |
+
+## Application and domain
+
+- Application **must not** import or raise typed domain exceptions. Signal via **`None`**, empty collections, or **`application.shared.exceptions`**.
+- Typed domain exceptions inherit domain **`BaseXxxException`** → **`BaseDomainException`**. Export **only** **`BaseXxxException`** from domain **`__init__.py`**, not typed subclasses.
+- **`DomainValidationError`** → dedicated **400** handler + **`GENERIC_BAD_REQUEST_DETAIL`**; do not put internal reason in HTTP **`detail`**.
+- Leaked typed domain exception → **`BaseDomainException`** handler → **500** + **`GENERIC_INTERNAL_SERVER_ERROR_DETAIL`**.
+
+## Handler registration
+
+- Use **`register_exception_handler`** from **`core_framework.core.exception_handlers.common`** — not raw **`app.add_exception_handler`** elsewhere.
+- Register handlers in **`core_framework/core/exception_handlers/setup.py`** and **`application.py`**: application types (specific before any base), **`InvalidPageTokenError`**, **`DomainValidationError`**, one **`BaseDomainException`** leak handler, then **`Exception`** unmapped.
+- No per-domain handler modules for typed exceptions. Handlers translate only — no business logic or repository calls.
+- Do not log **error** for expected application 4xx; **`DomainValidationError`** at **warning**/**info**.
+
+## Catalog constants
+
+**`GENERIC_BAD_REQUEST_DETAIL`** (400), **`GENERIC_NOT_FOUND_DETAIL`** (404), **`GENERIC_FORBIDDEN_DETAIL`** (403), **`GENERIC_CONFLICT_DETAIL`** (409), ingest 413/415, **`GENERIC_INTERNAL_SERVER_ERROR_DETAIL`** (500).
+
+## Anti-enumeration (public routes)
+
+- Read-by-id: missing / hidden / withheld → same status + **`GENERIC_NOT_FOUND_DETAIL`** where flow docs align.
+- Idempotent writes on unknown ids → **204** without leaking existence. Empty list pages are OK.
+- Admin/internal routes may differ when documented. Intentional existence-check endpoints are separate product surface.
+
+## Validation order
+
+User-fixable input shape → API schemas (**422**). Domain backstops → **`DomainValidationError`** → generic **400**.
+
+## Logging
+
+Do not **`logger.error`** at every domain **`raise`**.
+
+Apply to new handlers and touched raise sites unless the task scopes repo-wide migration.

core_framework-2.2.0/.cursor/rules/flow-documentation.mdc

@@ -0,0 +1,15 @@
+---
+description: Flow docs describe user-facing API behavior only — no implementation code
+globs:
+  - docs/domains/**/*.md
+alwaysApply: false
+---
+
+# Flow documentation
+
+Flow docs under **`docs/domains/{domain}/`** describe **client-visible API behavior**, not implementation.
+
+- **Include**: endpoints, auth, request/response fields (text, not JSON examples), errors, idempotency, side effects.
+- **Exclude**: Python/SQL snippets, function names, layer internals, schema DDL — see **`no-code-in-docs.mdc`**.
+
+When creating or rewriting flow docs, use the **write-flow-doc** skill and match existing docs (e.g. **`profile.md`**, **`restrictions.md`**).

core_framework-2.2.0/.cursor/rules/layer-boundaries.mdc

@@ -0,0 +1,24 @@
+---
+description: Enforce API, worker, application, and domain layer responsibilities
+globs:
+  - core_framework/api/**/*.py
+  - core_framework/worker/**/*.py
+  - core_framework/application/**/*.py
+  - core_framework/domains/**/*.py
+---
+
+# Layer boundaries
+
+Dependencies point inward: **API/worker → application → domain**. Never reverse.
+
+- **API**: HTTP adapter only; shared orchestration belongs in application.
+- **Worker**: schedules/tasks/job handlers; call application services.
+- **Application**: transport-agnostic orchestration; no FastAPI/Starlette types.
+- **Domain**: business rules, models, repositories, services; no API/worker/application imports.
+
+## Cross-layer rules
+
+- Worker code must not import `core_framework.domains` directly; call **application** services from worker tasks and schedules.
+- Domain code imports global infrastructure only in `dependencies.py`.
+- Repositories are Postgres-only and must not query other domains' schemas. See **`repository-schema-isolation`**.
+- Non-SQL I/O uses domain ports/components plus infrastructure adapters. See **`domain-services-and-adapters`**.

core_framework-2.2.0/.cursor/rules/no-code-in-docs.mdc

@@ -0,0 +1,35 @@
+---
+description: Docs avoid implementation code; HTTP interface listings and schema DDL are OK
+globs: docs/**/*.md
+alwaysApply: false
+---
+
+# No Code in Documentation
+
+Documentation under **`docs/`** must not carry **implementation** snippets that belong in the repo (executable Python, shell, operational SQL queries, etc.). **`docs/`** describes **what** and **why**; the codebase shows **how**.
+
+## What to exclude
+
+- Python class/function definitions or examples
+- **SQL for data access or mutation** — `SELECT`, `INSERT`, `UPDATE`, `DELETE`, `MERGE`, CTE-heavy reports, cleanup queries, etc. (describe behavior in prose or name the operation; do not paste DML/query text)
+- Shell commands — **except** in deployment runbooks under **`docs/deployments/`** (see *Exceptions* below)
+- Pseudocode that mimics real code syntax
+- Inline backticked references to internal function/method/class names when prose suffices (prefer describing behavior)
+
+## What is allowed
+
+- **HTTP API interface listings** — fenced **`http`** blocks or plain lines listing `METHOD /path # short note`. That is **surface contract**, not implementation code.
+- **SQL for table creation / physical design** — e.g. `CREATE TABLE` (and table-level DDL in the same design story, such as `CREATE INDEX`). DDL is a design artifact, not runtime query text.
+- ASCII diagrams and flowcharts (box-drawing characters)
+- Markdown tables of fields and types (`jsonb`, `varchar(26)`, etc.)
+- Plain-text lifecycle diagrams (arrows, boxes)
+- File/directory tree layouts (plain text or a neutral fence such as `text` if helpful)
+
+## Exceptions
+
+- **Deployment runbooks** under **`docs/deployments/`** (setup guides, deploy/release playbooks, SSH/image-server guides) may include fenced **`bash`** shell blocks. These are operator instructions for interactive server setup, not implementation that drifts from source; copy-paste commands are the practical content. This exemption does **not** extend to **`docs/deployments/*-design.md`** design docs, which follow the general rules above.
+- **Design docs** under **`docs/platform/`** and **`docs/library/`** (and **`docs/deployments/*-design.md`**) follow the general allow/exclude lists — DDL is allowed, DML and Python are not. Flow docs under **`docs/domains/**`** are stricter: see **`flow-documentation.mdc`** (no DDL, no JSON request bodies, fields described as text/tables).
+
+## Rationale
+
+Implementation snippets in docs drift from source. **HTTP listings** stay stable as the public contract. **DDL** documents intended physical shape. **DML** and **application code** belong in migrations and modules. Deployment runbooks are operator-facing setup instructions where shell commands are the deliverable, not source-bound implementation.

core_framework-2.2.0/.cursor/rules/postgres-config-conventions.mdc

@@ -0,0 +1,47 @@
+---
+description: Postgres write/read config and wiring conventions
+globs:
+  - core_framework/core/settings.py
+  - core_framework/core/runtime.py
+  - config.toml
+  - config.toml.template
+  - docs/deployments/**/*.md
+alwaysApply: false
+---
+
+# Postgres Config Conventions
+
+Use explicit write/read configuration and keep schema names shared.
+
+## Settings Model
+
+- Use `PostgresConnectionConfig` for connection and pool settings.
+- Use `PostgresSchemasConfig` for schema names.
+- Settings fields must be:
+  - `write_postgres`
+  - `read_postgres`
+  - `postgres_schemas`
+- Do not reintroduce `settings.postgres`.
+
+## Config Files
+
+- `config.toml` and `config.toml.template` must contain:
+  - `[write_postgres]`
+  - `[read_postgres]`
+  - `[postgres_schemas]`
+- Keep schema values only in `[postgres_schemas]` (no schema duplication inside write/read sections).
+
+## Deploy Variables
+
+- Use separate env vars for write/read DB rendering:
+  - `WRITE_POSTGRES_HOST`, `WRITE_POSTGRES_PORT`, `WRITE_POSTGRES_USER`, `WRITE_POSTGRES_PASSWORD`, `WRITE_POSTGRES_DB`
+  - `READ_POSTGRES_HOST`, `READ_POSTGRES_PORT`, `READ_POSTGRES_USER`, `READ_POSTGRES_PASSWORD`, `READ_POSTGRES_DB`
+- Do not use shared `POSTGRES_*` vars for both sections.
+
+## Runtime Wiring
+
+- Core exports separate instances:
+  - `write_postgres`
+  - `read_postgres`
+- Domain dependencies pass `(write, read, strong)` explicitly to repositories.
+- Until a dedicated strong instance exists, use write instance for the strong argument intentionally.

core_framework-2.2.0/.cursor/rules/strong-reads.mdc

@@ -0,0 +1,37 @@
+---
+description: Strong read policy and repository naming for read-after-write consistency
+globs:
+  - core_framework/domains/**/repository.py
+  - core_framework/domains/**/service.py
+  - core_framework/domains/**/dependencies.py
+  - core_framework/application/**/*.py
+---
+
+# Strong reads
+
+## Policy
+
+- **Read-after-write** in the same HTTP request or worker job → **strong** read (required). Refetch with `strong_read_database`, `*_strong` repository methods, or service accessors that call them.
+- **Decision-critical guards** where stale data can cause incorrect branching → **strong** read (required). These are reads performed to decide a branch (for example pre-write existence, role, or state checks that determine whether a write runs or which outcome is returned), even when there is no immediate prior write in the flow. See the "Read Consistency (Strong vs Normal Reads)" ADR.
+- **Accepted exception:** **`check_not_banned`** / **`get_user_detail`** (`USER_DETAIL` cache + normal reads) — ban visibility is eventually consistent by design. See **`docs/platform/architecture-decisions.md`** → *Ban enforcement via cached `USER_DETAIL` is eventually consistent*. Do not flag as a strong-read defect unless that ADR is updated.
+- **All other strong-read usage** (e.g., list/browse freshness) → opt-in unless the user explicitly requested it in the task.
+- If a flow writes then reads and only a normal-read API exists, add or extend the `*_strong` path and call it from that flow.
+- Repositories accept `strong_read_database: Postgres` on `__init__` for wiring symmetry even when unused.
+
+## Repository pattern
+
+- Normal reads: explicit methods (e.g. `select_appeal`) using `read_database`.
+- Strong reads: separate methods only where needed (e.g. `select_appeal_strong`) using `strong_read_database`.
+- Share one private helper that accepts a database handle when **both** normal and strong public methods exist — do not duplicate SQL or mapping. If only a `*_strong` method exists today, keep SQL inline in that method (constitution → inline small single-use helpers).
+- Service accessors that call strong repository methods should use **`retrieve_*_strong`** naming (repositories keep **`select_*_strong`**).
+
+```python
+# Preferred
+async def select_appeal(self, *, appeal_id: int) -> Appeal:
+    return await self._select_appeal_with_database(appeal_id=appeal_id, database=self.read_database)
+
+async def select_appeal_strong(self, *, appeal_id: int) -> Appeal:
+    return await self._select_appeal_with_database(appeal_id=appeal_id, database=self.strong_read_database)
+```
+
+Keep consistency decisions in services/use-case orchestration, not hidden in unrelated call paths.