core-framework 3.3.0__tar.gz → 4.0.1__tar.gz

core_framework-4.0.1/.cursor/rules/constitution.mdc

@@ -0,0 +1,50 @@
+---
+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.
+- Use the terms in [`docs/platform/glossary.md`](docs/platform/glossary.md) in **new** writing. Do not invent synonyms for those concepts. Do not rewrite shipped ADRs or docs solely to match the glossary.
+- Touch only what the task requires. Match existing style. Remove orphans your edits create.
+- Define verifiable success criteria for non-trivial work.
+- **Wait for the third copy before you extract** — do not extract a private function used once or twice when it is only a few lines (identifier quoting, a short SQL fragment, pass-through wrappers). Extract on the **third** real copy, or earlier when the logic is **~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 and **current Python syntax** over older equivalents still legal on 3.14, for example:
+  - `asyncio.TaskGroup` over `asyncio.gather`
+  - PEP 695 type parameters (`def f[T](...)`, `def f[**P, R](...)`) over module-level `TypeVar` / `ParamSpec`
+  - Built-in generics (`list[str]`, `dict[str, int]`) over `typing.List` / `typing.Dict`
+  - `X | Y` over `Optional[X]` / `Union[X, Y]` unless a library API requires the old form
+  - Do **not** add `from __future__ import annotations` — 3.14 deferred annotations are the default (PEP 649)
+
+## 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
+
+When the user asks to **grill**, interview, or sharpen a design before building, use the **grill** skill (`.cursor/skills/grill/`). Do not start **implement-feature** until that alignment is done (or the user skips it).
+
+Greenfield features (DB → API → repository → service → **documentation** → tests): use the **implement-feature** skill — one layer per response unless the user says otherwise. A feature is **not done** until documentation is updated. A **main feature** is **not done** until its design doc includes a mermaid flowchart of the main control flow (see the **implement-feature** skill). Do not backfill charts onto unrelated older design docs in the same task.

core_framework-4.0.1/.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 + catalog **`detail`** |
+| **API** | Pydantic; **`HTTPException`** for transport-local guards | **422** field errors; router-chosen status + **`detail`** |
+| **Domain typed** | Internal — not imported by API/application | No typed handlers |
+| **Domain `BaseXxxException`** | Handler catch-all only | **500** if leaked |
+
+## 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`**, cashews **`RateLimitError`** (**429**), **`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_UNPROCESSABLE_ENTITY_DETAIL`** (422), **`GENERIC_TOO_MANY_REQUESTS_DETAIL`** (429), **`GENERIC_SERVICE_UNAVAILABLE_DETAIL`** (503), **`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**) or router **`HTTPException`**. Use-case outcomes → application exceptions + handlers. Domain backstops → **`DomainValidationError`** → generic **400** (never domain text in **`detail`**).
+
+## 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-4.0.1/.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. A mermaid **flowchart** when the flow is a main multi-step lifecycle (schedule/cancel/worker, command then fan-out) — match **`account_deletion.md`**, **`restrictions.md`**. Skip for a single CRUD endpoint; do not backfill unrelated older flow docs in the same task.
+- **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-4.0.1/.cursor/rules/ignore-analytics-warehouse.mdc

@@ -0,0 +1,21 @@
+---
+description: Ignore exploratory ClickHouse warehouse notes unless the user explicitly opens that topic
+alwaysApply: true
+---
+
+# Ignore analytics-warehouse notes
+
+[`docs/design/analytics-warehouse-design.md`](docs/design/analytics-warehouse-design.md) is an **exploratory scratchpad**. It is **not** in the pipeline, **not** a backlog item, and **not** a constraint on the shipped system.
+
+## Do not
+
+- Read, cite, or align work to that document when changing events ingest, analytics rollup, `post_views` / `*_stats`, settings, workers, hosts, or any other area.
+- Add ClickHouse, a richer `POST /events` envelope, warehouse sinks, or “buffer vs diary” migrations **because** that doc exists.
+- Treat its placement rules, sequence, or sale/consent notes as accepted ADRs.
+
+## Do
+
+- Follow shipped docs: [`docs/domains/events/events.md`](docs/domains/events/events.md), [`docs/design/events-ingest-design.md`](docs/design/events-ingest-design.md), [`docs/design/analytics-rollup-design.md`](docs/design/analytics-rollup-design.md), [`docs/domains/posts/post_stats_aggregation.md`](docs/domains/posts/post_stats_aggregation.md).
+- Open the warehouse notes **only** when the user explicitly asks about that file, ClickHouse warehouse, or returning to that idea.
+
+If the user later wants it implemented, they will say so; then make it fit the system as it exists at that time.

core_framework-4.0.1/.cursor/rules/integration-test-strategy.mdc

@@ -0,0 +1,30 @@
+---
+description: Integration tests should prefer API-level assertions when endpoints exist
+globs:
+  - tests/integration/**/*.py
+---
+
+# Integration Test Strategy
+
+Treat integration tests as black-box API behavior tests whenever possible.
+
+## Core Rule
+
+- Prefer exercising behavior through HTTP endpoints and asserting API responses.
+- Use internal/database assertions only when no API endpoint exists yet for that behavior.
+- Name the test so a failure line states the broken invariant, not the endpoint/function or a generic `success` / `happy_path`.
+
+## Lifecycle Guidance
+
+- During initial endpoint implementation (for example, POST exists but GET does not), internal assertions are acceptable to confirm persistence/side effects.
+- After the corresponding read/inspect endpoint is implemented, migrate assertions to that API path and avoid direct DB checks for the same behavior.
+
+## Allowed Internal Checks
+
+- Setup/seed data when there is no practical API path for test preconditions.
+- Verify side effects that are intentionally not exposed via API (for example, queue internals, non-user-facing audit fields).
+
+## Avoid
+
+- Testing API behavior by primarily querying the database when an API route already exposes that behavior.
+- Coupling integration tests to repository internals when a stable endpoint contract is available.

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

@@ -0,0 +1,36 @@
+---
+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)
+- Mermaid diagrams (preferred for main-feature control flow: fenced `mermaid` with `flowchart TD` / `flowchart LR`)
+- 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/design/`**, **`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-4.0.1/.cursor/rules/postgres-config-conventions.mdc

@@ -0,0 +1,57 @@
+---
+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 module globals (`core_framework.core`) export separate instances:
+  - `write_postgres`
+  - `read_postgres`
+- `CoreRuntime` also holds `outbox_postgres`: same database as `write_postgres`, separate pool sized from `[outbox]` (`min_connections` / `max_connections`). The worker connects it at startup; the API lifespan does not. Do not rebind it as a `core_framework.core` global.
+- Domain dependencies pass `(write, read, strong)` explicitly to repositories.
+- Until a dedicated strong instance exists, use write instance for the strong argument intentionally.
+
+## Schema names in SQL
+
+- Schema names come only from `settings.postgres_schemas` (see **Settings Model** above).
+- Domain `dependencies.py` passes unquoted `schema=runtime.settings.postgres_schemas.schema_<domain>` into repositories (keyword-only `__init__`).
+- Repositories cache `self.schema_sql = quote_postgres_identifier(schema)` and use `{self.schema_sql}.table` in f-string SQL — never hard-coded `"post".` literals.
+- Outbox producer adapter is wired per domain with `schema` at construction; consumer adapter receives unquoted `schema` per call and caches quoted SQL.
+
+Repository isolation rules (no cross-domain schema access): **`repository-schema-isolation.mdc`**.

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

@@ -0,0 +1,89 @@
+---
+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*.
+
+## Schema qualification
+
+Repositories receive unquoted `schema` from `runtime.settings.postgres_schemas` in `dependencies.py` (keyword-only `__init__` arg). In `__init__`:
+
+- `self.schema` — config schema name (e.g. `post`)
+- `self.schema_sql` — `quote_postgres_identifier(schema)` for SQL interpolation
+
+Use `{self.schema_sql}.table` in f-string SQL — not hard-coded `"post".` literals.
+
+## Allowed in a repository
+
+- SQL qualified with that domain's schema only (e.g. `{self.schema_sql}.posts` in `PostRepository`).
+- **Within-schema** policy gates (e.g. `insert_post_like` checks `{self.schema_sql}.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 (illustrative schema literals)
+insert into {moderation_schema_sql}.post_reports (...)
+select $1, $2, $3, $4
+where exists (
+    select 1 from {post_schema_sql}.posts
+    where id = $2 and status = 'active'
+)
+
+# ❌ notification/repository.py — cross-domain mute gate
+insert into {notification_schema_sql}.notification_mutes (...)
+select ...
+where exists (select 1 from {comment_schema_sql}.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`.
+
+**Exception — PL/pgSQL trigger / function bodies:** Runtime `search_path` for functions is not the migration session’s path, so audit trigger bodies may **hard-code** that domain’s schema qualifier (e.g. `"user".user_change_history`, `moderation.restriction_history`). That is required and accepted. Keep `[postgres_schemas]` values aligned with those literals; do not treat this as a B11 isolation violation.
+
+**Exception — shared extension-schema types:** Domain Alembic `env.py` sets `search_path` to that domain’s schema only, so types and operator classes that live in the shared extensions schema must be **hard-coded** as `extension.…` (e.g. `extension.ltree` on comment `path`, `extension.gin_trgm_ops` on user `username`). That is required and accepted. Leave `[postgres_schemas].schema_extension` as **`extension`** (see `docs/library/overview.md`); do not treat this as a B11 isolation violation.
+
+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 table/type qualifier in SQL must use `{self.schema_sql}.…` (that domain's schema only).
+- Do not hard-code `"user".`, `"post".`, etc. — use `self.schema` / `self.schema_sql` from config.
+- Mirror lookup tables (`user_blocks_lookup`, etc.) still live under `{self.schema_sql}` when they belong to that domain's schema.

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

@@ -0,0 +1,39 @@
+---
+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_caller_identity`** / **`check_not_banned`** (alias) / **`get_user_detail`** (`USER_DETAIL_V2` cache + normal reads) — ban, deleted-user, and account-removal-in-progress visibility are eventually consistent by design. The removal-started fence rides that cache; do not strong-read it on every gated request. See **`docs/platform/architecture-decisions.md`** → *Ban / identity gate via cached `USER_DETAIL` is eventually consistent*. Do not flag as a strong-read defect unless that ADR is updated.
+- **Accepted exception:** account-removal media **owner listing** of avatar/banner/attachment staging-registry rows uses the **read replica**. Replica lag or swallowed per-blob staging deletes can leave orphan staging after a successful spine. See **`docs/platform/architecture-decisions.md`** → *Account-removal staging leftovers (Accepted)*. Do not flag as a must-succeed or strong-read defect unless that ADR is updated.
+- **Accepted exception:** followers-only **mention** recipient filtering uses the **follow replica** (`retrieve_follow_exists`, not `_strong`). Lag-window miss or extra mention is accepted. See **`docs/platform/architecture-decisions.md`** → *Followers-only mention eligibility uses the follow replica (Accepted)*. 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.

core_framework-4.0.1/.cursor/skills/code-review/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: code-review
+description: >-
+  Review code and report a single list of items to address. Use when the user
+  asks for a code review, audit of code/implementation, or review of code
+  changes — and when they ask to elaborate, expand, or explain those findings.
+  Do not use for design / system-design / product-design doc readiness reviews
+  (use design-review).
+---
+
+# Code Review
+
+Report **one list of items to address**. Check repo rules and originating docs internally. Do **not** split the report into Standards vs Spec (or any other axis). Do **not** tag findings by source.
+
+## What to check
+
+**Repo rules.** Does the diff follow this repo’s rules and accepted decisions?
+
+Layers, conventions, scoped `.cursor/rules`, **Residue**, parallel drift, third-copy, strong reads, test names, main-feature flowchart when this change adds or alters a design doc. Use [`docs/platform/glossary.md`](docs/platform/glossary.md) terms.
+
+Do **not** flag documented accepted trade-offs in **`docs/platform/architecture-decisions.md`** unless the implementation violates them. Do **not** flag two similar copies as needing extraction (wait for the third). Do **not** import a generic smell list that fights those rules.
+
+**Originating docs.** Does the diff match the design and flow docs?
+
+- Missing or partial relative to the spec
+- Behavior the spec did not ask for
+- Implemented but wrong relative to a spec line (quote that line)
+
+**Spec sources** (first that applies): docs the user named; design/flow docs the change clearly belongs to; matching `docs/design/*-design.md` / `docs/domains/**/*-design.md` plus the paired flow doc. If none exist, skip this check — do not mention that there is no spec.
+
+## Output format (required)
+
+**Actionable findings only**, under `## Findings`:
+
+- Bugs, wrong behavior, improvements, optimizations, doc/code contradictions, parallel implementation drift (sibling flows that diverge without documented reason), **Residue** after an implementation or refactor, spec gaps / extras / mismatches.
+- One numbered list, prioritized by severity. Each item: file context, what is wrong, fix direction.
+- **Do not** praise, summarize strengths, pad with checklist pass narratives, or emit empty-axis sentences.
+- One-line scope is fine. If there is nothing to address, say so in one sentence — no `## Findings` heading.
+
+## Elaborating review points (required)
+
+When the user asks to elaborate, expand, explain, or go deeper on review findings (one point, several, or all):
+
+- **Always include concrete examples** for each point — never prose-only elaboration.
+- Prefer examples from the reviewed code: cite the relevant snippet, then show a corrected or alternative version when a fix is implied.
+- If the issue is behavioral (race, ordering, missing branch), give a short before/after scenario or input sequence that triggers it.
+- Keep the example tight (a few lines); do not re-dump the whole review.
+
+## Workflow
+
+1. Pin the diff (named files, or `git diff` against the branch base / range the user gave).
+1. Identify spec sources (see **Originating docs** above).
+1. Read **`docs/platform/layers-and-boundaries.md`**, **`conventions.md`**, **`architecture-decisions.md`**, and **`glossary.md`** for the reviewed scope.
+1. Apply **scoped rules** (`.cursor/rules/*.mdc`) matching files under review — especially **`error-boundary`**, **`domain-imports`**, **`api-layer`**, **`application-layer`**, **`strong-reads`**.
+1. Check for **Residue** from this implementation or refactor (section below). Flag it with delete-now direction unless a live consumer still needs the old path.
+1. Check rules and originating docs. If the diff is large, parallel exploration is fine; **merge into one severity-ordered list** before reporting. Do not paste unmerged sub-agent reports.
+1. Report findings only — no filler.
+1. On elaborate/expand follow-ups, re-read this skill and apply **Elaborating review points**.
+
+## Quick checks
+
+- Application services: no HTTP types, no domain exceptions, no Pydantic return types, one-line docstrings.
+- API: thin routers, validation in schemas, orchestration in application — **fastapi** skill (`.agents/skills/fastapi/`) + **`api-layer`** / **`api-validation`** / **`error-boundary`** rules.
+- Domain: imports only via **`__init__.py`** / **`dependencies`** from outer layers; no caller-context names (**`domain-caller-context`**).
+- Read-after-write refetches use **`*_strong`** where applicable.
+- **Python modernity (constitution):** prefer current 3.14 syntax in reviewed code — PEP 695 type params over module-level `TypeVar`/`ParamSpec`; no unnecessary `from __future__ import annotations`; builtins / `X | Y` over legacy `typing` aliases; `asyncio.TaskGroup` over `gather`.
+- **Wait for the third copy before you extract** (`docs/platform/conventions.md`): flag a new private helper with one or two call sites unless it is ~15+ lines / non-obvious branching, or a scoped rule requires sharing (`strong-reads`). Do **not** flag two similar inlined copies as needing extraction.
+- **Test name should tell me what broke:** flag tests whose names only name the unit under test or a generic outcome (`test_create_post`, `test_success`, `test_happy_path`). The pytest failure line must state the invariant (e.g. `test_public_feed_excludes_others_followers_only_post`).
+- **Main-feature design flowchart:** if this change introduces a new `*-design.md` (or changes that design’s control flow) and there is no mermaid **`flowchart`** of the main control flow, flag it. Do **not** flag older design docs that never had a chart.
+
+## Residue
+
+Leftover seams after the new path shipped. Flag them; they are not “later retirement” unless a live producer or in-flight consumer still needs the old path. On greenfield (no hosts, no traffic), treat as **safe to delete now**.
+
+Look for:
+
+- Dead registration — worker tasks, enums, schedules, or “keep registered for drain” docs with no remaining producer.
+- Compatibility branches the new producers never write (old payload versions, dual handlers, mirrors-only v1).
+- Incomplete moves — logic still in the old module, a shared helper unused while call sites inline the same shape, types left as `Any` after a typed model exists.
+- Docs / OpenAPI still describing the pre-change stored shape, cutover drain, or a history/status value that is never written.
+- Naming leftovers after a rename (old helper name used for a different role).
+
+## Parallel drift
+
+Flag sibling modules with the same job but different structure (async layout, cleanup order, error/idempotency contracts) when docs do not explain the difference. Do **not** flag differences called out as intentional in design/flow docs or in **`docs/reviews/slices.md`** B7 **Do not flag** (for example root vs reply create-idempotency replay placement in **`docs/design/create-idempotency-design.md`**).

core_framework-4.0.1/.cursor/skills/design-review/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: design-review
+description: >-
+  Review design / system-design docs for implementation readiness. Use when the
+  user asks to review a design, system-design, or product-design doc; asks if it
+  is clear enough for implementation; or asks for blockers before implementation
+  — and when they ask to elaborate, expand, or explain those review findings.
+  Do not use when the user wants to grill or interview a design into existence
+  (use grill).
+---
+
+# Design Review
+
+This skill reviews an **existing** design doc. If there is no doc yet, or the user wants to form or sharpen one, use the **grill** skill first.
+
+## Goal
+
+Review comprehensively to see if everything is clear enough for implementation.
+
+## Output filter (required)
+
+- **Ignore** things that can be decided during implementation.
+- **Only** report things that are blockers or should be addressed before implementation.
+- No praise, strength summaries, or “looks good except…” padding.
+- If nothing blocks implementation, say so in one sentence.
+
+## Finding shape
+
+For each finding:
+
+- What is unclear, underspecified, or contradictory for an implementer.
+- Why it is a pre-implementation blocker (not a coding preference).
+- Where in the doc (section / quote) the gap shows up.
+
+## Elaborating review points (required)
+
+When the user asks to elaborate, expand, explain, or go deeper on review findings (one point, several, or all):
+
+- **Always include concrete examples** for each point — never prose-only elaboration.
+- Prefer examples grounded in the doc: quote the ambiguous passage, then show 2+ plausible implementer interpretations or a minimal scenario the doc does not settle.
+- When a fix is implied, show a short sample clarification the doc could add (a few lines).
+- Keep examples tight; do not re-dump the whole review.
+
+## Workflow
+
+1. Locate and read the named design doc (and closely linked sibling design/flow docs if the doc depends on them).
+1. Judge only implementation readiness: missing contracts, ambiguous states/transitions, unresolved ownership, contradictory requirements, undefined error/idempotency/auth boundaries that an implementer cannot safely invent.
+1. For a **main-feature** design being written or implemented **now**: a missing mermaid **`flowchart`** of the main control flow is a blocker (see **Main-feature flowchart** below).
+1. Drop niceties, optional polish, and choices that are safe to defer to implementation.
+1. Report blockers / must-address-before-implementation only.
+1. On elaborate/expand follow-ups, re-read this skill and apply **Elaborating review points**.
+
+## Main-feature flowchart
+
+A main feature is one with a design doc (`docs/design/*-design.md` or `docs/domains/**/*-design.md`) covering a spine, registry, multi-phase pipeline, or product system.
+
+If that doc is the subject of this review because it is being designed or implemented **now**, and it has no mermaid **`flowchart`** of the main control flow (phases, barriers, branches — style of `docs/design/account-removal-spine-design.md` and `docs/design/moderation-restriction-fanout-design.md`), that is a **pre-implementation blocker**. An implementer should not have to invent the order of phases.
+
+Do **not** flag a historic shipped design **solely** for lacking a chart — that backfill is a separate pass. Do flag a missing or stale chart when **this** change alters that design’s control flow.

core_framework-4.0.1/.cursor/skills/grill/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: grill
+description: >-
+  Relentless interview to align a plan or design, then write glossary terms,
+  offered ADRs, and the design doc. Use only when the user asks to grill,
+  interview, sharpen, or stress-test a design before implementation.
+disable-model-invocation: true
+---
+
+# Grill
+
+Interview until the design tree is resolved. Then write the paper trail. Do **not** implement.
+
+This is how a design **forms**. **design-review** checks an existing doc for implementation readiness. **implement-feature** builds after that.
+
+## Surfaces (this repo)
+
+| Write here                                                                                                   | Not here                               |
+| ------------------------------------------------------------------------------------------------------------ | -------------------------------------- |
+| [`docs/platform/glossary.md`](docs/platform/glossary.md) — terms only                                        | Root `CONTEXT.md`                      |
+| [`docs/platform/architecture-decisions.md`](docs/platform/architecture-decisions.md) — ADRs the user accepts | `docs/adr/`                            |
+| Design doc: `docs/design/*-design.md` (cross-cutting) or `docs/domains/**/*-design.md` (one product area)    | GitHub issues, tickets, `docs/todo.md` |
+
+Glossary is **not** a spec. ADRs are **not** a glossary. The design doc holds the plan.
+
+## Design tree
+
+Map the work as a tree: each settled decision unlocks the questions that hang off it.
+
+The **frontier** is every unresolved decision whose prerequisites are already settled. Ask the whole frontier in one round. Wait for answers before the next round. A question that depends on another still-open question in this round belongs to a later round.
+
+The session is done when the frontier is empty and the user confirms shared understanding.
+
+## Facts vs decisions
+
+**Facts** are the agent's job (code, docs, current behavior). Look them up; do not ask the user for anything you can read. Dispatch exploration rather than blocking the whole round: questions that do not depend on the lookup still go in this round.
+
+**Decisions** are the user's. Put each on the frontier and wait.
+
+## Round format
+
+Number questions. Each has a recommended answer. Use this shape:
+
+```
+❓ **Q1** — **<title>**: <body; choices if useful>
+
+➡️ <recommended answer>
+```
+
+Do not implement, scaffold, or start **implement-feature** during grilling.
+
+## Language (inline)
+
+Read [`docs/platform/glossary.md`](docs/platform/glossary.md) at the start.
+
+- If the user uses a term that conflicts with the glossary, challenge it immediately.
+- If they use a vague or overloaded word, propose one canonical term and list what to avoid.
+- When a term is resolved, **update the glossary in the same turn**. Do not batch terms until the end.
+- Glossary entries: one or two sentences of what it **is**; `_Avoid_:` for names not to use in **new** writing. Do not rewrite shipped ADRs or docs to match. No implementation, no API paths, no file names.
+
+## ADRs (offer, do not dump)
+
+Offer an entry in `architecture-decisions.md` only when **all three** are true:
+
+1. **Hard to reverse** — changing it later is costly.
+1. **Surprising without context** — a future reader will wonder why it is this way.
+1. **A real trade-off** — genuine alternatives, picked for stated reasons.
+
+If any gate fails, skip the ADR. Copy headings from a nearby entry in that file. Required: **Decision**, **Rationale**, **Location**. Add **Policy** when the decision has standing operational constraints (same as neighboring entries). Ask before inserting. Place it in the right section of that file.
+
+## After the frontier is empty
+
+1. Confirm shared understanding with the user. Do not write the design doc until they confirm.
+1. Create or update the design doc. Follow existing design docs and **`no-code-in-docs.mdc`**. A **main feature** (spine, registry, multi-phase pipeline, product system) needs a mermaid **`flowchart`** of the main control flow — same role as `docs/design/account-removal-spine-design.md`. If this creates a new `*-design.md`, add it to the index: `docs/design/README.md` when cross-cutting, `docs/domains/README.md` when domain-scoped.
+1. Point the user at **design-review** next, then **implement-feature**. Stop.