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

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

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

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

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

{core_framework-1.0.0 → core_framework-1.2.0}/.cursor/rules/domain-input-guards.mdc

@@ -31,6 +31,8 @@ Use **layered** checks: user contracts at the **API**, business preconditions at
 
 ### Shared string / pagination helpers (`core_framework.domains.utils`)
 
+**Import boundary:** `domains/utils.py` may import **`MAX_PAGE_FETCH_SIZE`** from **`core_framework.core.pagination`** only. That module is shared pagination constants, not Postgres/Redis/HTTP infrastructure; it is not subject to the “core imports only in `dependencies.py`” rule for DB/cache clients.
+
 Use these across domains so validation stays consistent and call sites stay readable:
 
 | Helper | Use when |
@@ -39,6 +41,7 @@ Use these across domains so validation stays consistent and call sites stay read
 | **`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_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`). |
 | **`require_positive_int(value=..., field=...)`** | **Integer** surrogate keys only (e.g. moderation `report_id`, `appeal_id`, `note_id`). Must be **≥ 1**. Domains that identify entities with **string** IDs (ULIDs) use **`require_non_blank_*`** instead—do not add this helper there. |
 | **`require_validated_update_has_allowed_fields(validated_update_request=..., allowed_fields=...)`** | PATCH-style dict updates: reject empty bodies and bodies with **no** recognized keys (use domain constants such as **`USER_*_UPDATE_FIELDS`**). |
 

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

@@ -0,0 +1,20 @@
+---
+description: When domain repositories vs services raise domain exceptions (thin façade)
+globs:
+  - core_framework/domains/**/*.py
+---
+
+# Domain: repository exceptions vs service
+
+## 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, **prefer raising domain exceptions inside the repository** when the persistence outcome is an error condition (empty `RETURNING`, unexpected row absence on insert).
+
+The service stays a façade: validate arguments, then **`await`** the repository method and let **domain exceptions** propagate.
+
+## Prefer service-side translation when
+
+- The service **composes multiple** repository calls, **branches** on outcomes, or maps the same SQL outcome to **different domain errors**.
+- 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-1.0.0 → core_framework-1.2.0}/.cursor/rules/layer-boundaries.mdc

@@ -19,7 +19,8 @@ Use this architecture split consistently:
 ## Rules
 
 - API layer must not contain business orchestration that is shared with workers.
-- Worker layer must not contain domain business rules; call application services.
+- Worker layer must not contain domain business rules; call application services only.
+- Worker code must not import **`core_framework.domains`** packages (no direct domain repository/service usage from workers).
 - Application layer must not import FastAPI/Starlette HTTP types.
 - Domain layer must not import API, worker, or application modules.
 - Domain layer must not import global infrastructure except in `dependencies.py`.
@@ -29,7 +30,7 @@ Use this architecture split consistently:
 Dependencies point inward:
 
 - API -> application and/or domains
-- worker -> application and/or domains
+- worker -> application
 - application -> domains
 
 Never the reverse.

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

@@ -0,0 +1,30 @@
+---
+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
+- 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)
+
+## 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.

{core_framework-1.0.0 → core_framework-1.2.0}/.cursor/rules/repository-read-consistency.mdc

@@ -5,10 +5,12 @@ alwaysApply: true
 
 # Repository Read Consistency
 
-When a repository supports both replica reads and strong reads, choose consistency at the use-case level.
+**Policy** (see **`strong-read-opt-in`**): use **strong** reads for **read-after-write** refetches in the same request or job; treat **other** strong-read additions as **opt-in** unless the user asked for them in that task. Repositories may still take **`strong_read_database`** on **`__init__`** for wiring symmetry while it remains unused.
+
+When a repository supports both replica and strong reads, choose consistency at the use-case level.
 
 - Keep normal reads explicit (for example, `select_appeal`).
-- Add separate strong-read methods for read-after-write paths (for example, `select_appeal_strong`).
+- Add separate strong-read methods only where needed for those flows (for example, `select_appeal_strong`).
 - Services decide which method to call based on consistency needs.
 
 ## Method Structure
@@ -29,9 +31,9 @@ When a repository supports both replica reads and strong reads, choose consisten
 
 ## Consistency Selection
 
-- Use strong reads for read-after-write behavior in the same request flow.
-- Use strong reads for decision-critical guards where stale data can cause incorrect branching.
-- Use normal reads for list/browse/history endpoints unless strict freshness is required.
+- **Read-after-write** in the same request or worker job → **strong** read (required).
+- **Decision-critical guards** where stale data causes wrong branching → strong reads only when the task adds that surface (**opt-in** unless the flow is read-after-write).
+- **List/browse/history** → normal reads unless strict freshness is explicitly required (**opt-in**).
 - Keep consistency decisions in services/use-case orchestration, not hidden in unrelated call paths.
 
 ```python

core_framework-1.2.0/.cursor/rules/strong-read-opt-in.mdc

@@ -0,0 +1,22 @@
+---
+description: Strong reads after writes are required; other strong-read surface is opt-in
+alwaysApply: true
+---
+
+# Strong reads (core-framework)
+
+When editing **`core_framework/**/*.py`** in this repository:
+
+## Read-after-write (required)
+
+After a **write** in the **same** HTTP request or worker job flow, any **refetch** of that persisted state must use a **strong** read (`strong_read_database`, **`*_strong`** repository methods, or service accessors that call them) so callers do not hit stale replica data. 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.
+
+## Other uses (opt-in)
+
+Do **not** add **`strong_read_database`** usage, new **`*_strong`** repository or service accessors, or strong refetches for reasons **other** than read-after-write (for example list/browse freshness, or decision guards unrelated to an immediate prior write in the same flow) unless the **user explicitly requested** strong reads in the same task or message.
+
+## Wiring
+
+Repositories should still accept **`strong_read_database: Postgres`** on **`__init__`** where that matches existing dependency wiring **even when no method reads from it yet**; keep **`self.strong_read_database`** unused until a caller needs strong reads.
+
+Existing `*_strong` APIs and call sites stay as-is unless a task explicitly changes them.

{core_framework-1.0.0 → core_framework-1.2.0}/.cursor/rules/tech-stack.mdc

@@ -9,4 +9,6 @@ alwaysApply: true
 - **Exception syntax**: In this codebase, Python 3.14 comma-style multi-exception handling (for example, `except A, B:`) is valid and intentional.
 - **Pydantic v2**: Use only Pydantic v2 APIs. No v1 patterns (e.g. use `model_dump` not `dict()`, `model_validate` not `parse_obj`, `model_config` not nested `Config` class, `field_validator` not `validator`).
 - **Prefer newer APIs**: When multiple APIs exist for the same purpose, prefer the newer, recommended one (e.g. `asyncio.TaskGroup` over `asyncio.gather` for concurrent async operations).
+- **Imports**: Use **absolute** imports only (`from core_framework....`). Do not use relative imports (`from .module import ...`, `from ..parent import ...`). Applies across application, domains, API, core, workers, and tests (including **`__init__.py`** re-exports).
+- **orjson over stdlib json**: Use `orjson` for all JSON serialization and deserialization. Do not use `import json` from the standard library.
 - **PostgreSQL 18**: SQL and migrations must be compatible with PostgreSQL 18. Use supported syntax and avoid deprecated features.

core_framework-1.2.0/.cursor/skills/add-domain/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: add-domain
+description: Scaffold a new domain in core-framework (settings, empty Alembic tree, domain package + bootstrap). Use when adding a brand-new domain under `core_framework/domains/<name>/` with a dedicated Postgres schema name and `alembic/<name>/` layout, when the user asks to "add a domain", "create a domain", or "bootstrap <name> domain".
+---
+
+# Adding a New Domain (with its own DB schema)
+
+This skill covers **scaffolding only**: settings, a full **Alembic directory layout** with an **empty** `versions/` folder (no `.py` migrations yet), domain package shells + bootstrap wiring.
+
+**Do not** add `<domain>` to `ALEMBIC_DOMAINS` until at least one revision exists under `versions/` — otherwise `cf-alembic` would run `upgrade head` for an empty branch and fail.
+
+It does **not** cover the API layer or tests — handle those separately following the existing rules.
+
+Follow `implementation-workflow` (`/.cursor/rules/implementation-workflow.mdc`): one step per response, wait for review.
+
+## Inputs
+
+- `<domain>` — snake_case singular name (e.g. `billing`, `audit`, `feed`).
+- Postgres schema name — usually `<domain>` (no quoting needed unless reserved like `user`).
+
+Reserve the schema name in config so code and future migrations agree; the **physical schema in Postgres** does not exist until a migration creates it.
+
+## Order
+
+1. Schema config wiring
+1. Alembic tree (all support files; **`versions/` empty**)
+1. Domain skeleton (files, **class shells only**, dependencies + bootstrap wiring — **no example methods, no SQL/queries**)
+1. Application bootstrap wiring
+1. Domain README and changelog
+
+Stop after each step and wait for review.
+
+## 1. Schema config wiring
+
+Per `postgres-config-conventions` (`/.cursor/rules/postgres-config-conventions.mdc`).
+
+`core_framework/core/settings.py`:
+
+```text
+class PostgresSchemasConfig(BaseModel):
+    schema_extension: str
+    schema_user: str
+    schema_moderation: str
+    schema_post: str
+    schema_comment: str
+    schema_notification: str
+    schema_<domain>: str  # add
+```
+
+`config.toml` and `config.toml.template` — add under `[postgres_schemas]`:
+
+```text
+[postgres_schemas]
+schema_<domain> = "<domain>"
+```
+
+Do **not** add the schema name anywhere else. Schema lives only in `[postgres_schemas]`.
+
+## 2. Alembic tree (skeleton, empty `versions/`)
+
+Create `alembic/<domain>/` by copying layout from an existing domain (e.g. `alembic/comment/`): **`alembic.ini`**, `alembic/env.py`, `alembic/script.py.mako`, `alembic/README`, and directory **`alembic/versions/`**.
+
+- **`env.py`**: keep the same pattern as siblings (e.g. `config.set_main_option("sqlalchemy.url", settings.write_postgres.alembic_postgres_url)`).
+- **`alembic/versions/`**: **must contain no `*.py` files** at scaffold time. Optional: add a **`.gitkeep`** so Git keeps the empty folder.
+
+**Do not** append `<domain>` to `ALEMBIC_DOMAINS` in this step. The new tree is **not** part of `cf-alembic` until the follow-up adds the first revision **and** updates `ALEMBIC_DOMAINS` together.
+
+```
+alembic/<domain>/
+├── alembic.ini
+└── alembic/
+    ├── env.py
+    ├── README
+    ├── script.py.mako
+    └── versions/
+        └── .gitkeep   # optional; no *.py here initially
+```
+
+## 3. Domain skeleton (shells + wiring only)
+
+Create `core_framework/domains/<domain>/` with **stub types and wiring only**. Do **not** add example domain methods, repository queries, SQL strings, or business logic until a later change.
+
+```
+core_framework/domains/<domain>/
+├── __init__.py
+├── README.md
+├── exceptions.py
+├── models.py          # placeholder only (see below)
+├── repository.py
+├── service.py
+├── dependencies.py
+```
+
+Skip `enums.py`, `constants.py`, and `utils.py` until needed.
+
+### `exceptions.py`
+
+One base exception class only, e.g. `class Base<Domain>Exception(Exception): ...` with an empty body (or `pass`). No concrete exception subclasses yet unless required for imports.
+
+### `models.py`
+
+No dataclasses or table-shaped models at scaffold time. Either an empty module or a single short comment that models will be added with the first real migration. **Do not** invent placeholder fields.
+
+### `repository.py`
+
+A single `class <Domain>Repository:` whose **`__init__`** takes `(write_postgres, read_postgres, strong_read_postgres)` (or the project’s `Postgres` type) and assigns them to **private** instance attributes (e.g. `_write_database`, `_read_database`, `_strong_read_database`). **No other methods.**
+
+### `service.py`
+
+A single `class <Domain>Service:` whose **`__init__`** takes `<Domain>Repository` and stores it on a **private** attribute (e.g. `_repository`). **No other methods.** No FastAPI/Starlette imports. No caller-context names per `domain-caller-context`.
+
+When real behavior is added later, apply `repository-read-consistency` (`/.cursor/rules/repository-read-consistency.mdc`) for reads and `_strong` naming.
+
+### `__init__.py`
+
+Export the **classes** other layers may import: base exception, `<Domain>Repository`, `<Domain>Service`. List them in `__all__` per `domain-imports`. Do **not** re-export module-level `*_repository` / `*_service` instances from `dependencies` here.
+
+### `dependencies.py`
+
+Wire repository and service the same way as other domains (e.g. `domains/comment/dependencies.py`):
+
+```text
+from core_framework.core.runtime import CoreRuntime, unconfigured_dependency
+from core_framework.domains.<domain>.repository import <Domain>Repository
+from core_framework.domains.<domain>.service import <Domain>Service
+
+
+def build_<domain>_repository(runtime: CoreRuntime) -> <Domain>Repository:
+    return <Domain>Repository(
+        runtime.write_postgres,
+        runtime.read_postgres,
+        runtime.write_postgres,  # strong placeholder until a dedicated handle exists
+    )
+
+
+def build_<domain>_service(runtime: CoreRuntime) -> <Domain>Service:
+    return <Domain>Service(build_<domain>_repository(runtime))
+
+
+def configure_<domain>_dependencies(runtime: CoreRuntime) -> None:
+    global <domain>_repository, <domain>_service
+    <domain>_repository = build_<domain>_repository(runtime)
+    <domain>_service = build_<domain>_service(runtime)
+
+
+<domain>_repository = unconfigured_dependency("<Domain>Repository")
+<domain>_service = unconfigured_dependency("<Domain>Service")
+
+__all__ = [
+    "build_<domain>_repository",
+    "build_<domain>_service",
+    "configure_<domain>_dependencies",
+    "<domain>_repository",
+    "<domain>_service",
+]
+```
+
+## 4. Application bootstrap wiring
+
+`core_framework/application/bootstrap.py` — add the configure call:
+
+```text
+from core_framework.domains.<domain>.dependencies import configure_<domain>_dependencies
+
+def configure_application_dependencies(*, runtime: CoreRuntime) -> None:
+    ...
+    configure_<domain>_dependencies(runtime)
+```
+
+Worker `startup` and API `init_app` already call `configure_application_dependencies(runtime=...)`, so both processes pick up the new domain automatically.
+
+## 5. Docs
+
+- `core_framework/domains/<domain>/README.md` — domain exists in code; `alembic/<domain>/` exists with **empty** `versions/`; **not** in `ALEMBIC_DOMAINS` until first revision; **no** DB schema object until a migration creates it.
+- `CHANGELOG.md` — `### Added` under `[Unreleased]` for domain package, `schema_<domain>`, and Alembic skeleton path (optional). **Do not** list `ALEMBIC_DOMAINS` or revision ids until the first migration lands.
+- Update `docs/architecture.md` and `docs/package-api.md` only when the domain exposes anything to the public surface.
+
+## Follow-up: first revision + enroll in `cf-alembic`
+
+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. **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.
+
+`downgrade()` policy for baselines in this repo: raise `RuntimeError` when downgrades are unsupported, per existing `v1_*_init` migrations.
+
+## What you do NOT need to touch
+
+- `makefile` `alembic` target — uses `cf-alembic`.
+- `.github/workflows/_deploy.yml` migration step — uses `cf-alembic`.
+- `pyproject.toml` `[tool.hatch.build.targets.wheel.force-include] "alembic"` — already directory-level, ships new trees automatically.
+
+## Drift safety
+
+`tests/unit/core/bundled_alembic_test.py` exercises `iter_alembic_ini_paths()` over **only** `ALEMBIC_DOMAINS`. A scaffolded domain with an empty `versions/` folder is **invisible** to that test until it is appended — which must happen **together** with the first revision.
+
+## Reminders
+
+- One step per response, wait for review (`implementation-workflow`).
+- Domain imports follow `domain-imports`; do not import API/application from domain.
+- Never name domain symbols by caller (`Admin*`, `Api*`, `Worker*`) per `domain-caller-context`.
+- When adding real repository methods later, follow `repository-read-consistency` (`_strong` naming where applicable).

{core_framework-1.0.0 → core_framework-1.2.0}/.github/workflows/_deploy.yml

@@ -120,47 +120,12 @@ jobs:
             FIREBASE_CONFIG_PATH="$FIREBASE_CONFIG_PATH" \
             docker compose -f "$COMPOSE_FILE" pull
 
-            echo "Running database migrations (extension)"
+            echo "Running database migrations (cf-alembic iterates core_framework.bundled_alembic.ALEMBIC_DOMAINS in order)"
             docker run --rm \
               --network host \
               -v "$CONFIG_PATH:/app/config.toml:ro" \
               "$DOCKERHUB_USERNAME/core-framework:latest" \
-              alembic -c /app/alembic/extension/alembic.ini upgrade head
-
-            echo "Running database migrations (user)"
-            docker run --rm \
-              --network host \
-              -v "$CONFIG_PATH:/app/config.toml:ro" \
-              "$DOCKERHUB_USERNAME/core-framework:latest" \
-              alembic -c /app/alembic/user/alembic.ini upgrade head
-
-            echo "Running database migrations (moderation)"
-            docker run --rm \
-              --network host \
-              -v "$CONFIG_PATH:/app/config.toml:ro" \
-              "$DOCKERHUB_USERNAME/core-framework:latest" \
-              alembic -c /app/alembic/moderation/alembic.ini upgrade head
-
-            echo "Running database migrations (post)"
-            docker run --rm \
-              --network host \
-              -v "$CONFIG_PATH:/app/config.toml:ro" \
-              "$DOCKERHUB_USERNAME/core-framework:latest" \
-              alembic -c /app/alembic/post/alembic.ini upgrade head
-
-            echo "Running database migrations (comment)"
-            docker run --rm \
-              --network host \
-              -v "$CONFIG_PATH:/app/config.toml:ro" \
-              "$DOCKERHUB_USERNAME/core-framework:latest" \
-              alembic -c /app/alembic/comment/alembic.ini upgrade head
-
-            echo "Running database migrations (notification)"
-            docker run --rm \
-              --network host \
-              -v "$CONFIG_PATH:/app/config.toml:ro" \
-              "$DOCKERHUB_USERNAME/core-framework:latest" \
-              alembic -c /app/alembic/notification/alembic.ini upgrade head
+              cf-alembic
 
             echo "Starting services with Docker Compose"
             DOCKERHUB_USERNAME="$DOCKERHUB_USERNAME" \
@@ -168,6 +133,7 @@ jobs:
             FIREBASE_CONFIG_PATH="$FIREBASE_CONFIG_PATH" \
             docker compose -f "$COMPOSE_FILE" up -d \
               --remove-orphans \
+              --force-recreate \
               --scale worker="${{ inputs.worker_replicas }}"
 
             echo "Cleaning up dangling Docker images"

{core_framework-1.0.0 → core_framework-1.2.0}/.github/workflows/dev-ci-cd.yaml

@@ -79,6 +79,7 @@ jobs:
         with:
           context: .
           file: ./dockerfile
+          target: api
           push: true
           tags: ${{ steps.meta.outputs.tags }}
 
@@ -110,7 +111,8 @@ jobs:
         uses: docker/build-push-action@v6
         with:
           context: .
-          file: ./dockerfile.worker
+          file: ./dockerfile
+          target: worker
           push: true
           tags: ${{ steps.meta.outputs.tags }}
 

{core_framework-1.0.0 → core_framework-1.2.0}/.github/workflows/test.yaml

@@ -100,6 +100,7 @@ jobs:
         with:
           context: .
           file: ./dockerfile
+          target: api
           push: false
           tags: core-framework:ci
 
@@ -107,6 +108,7 @@ jobs:
         uses: docker/build-push-action@v6
         with:
           context: .
-          file: ./dockerfile.worker
+          file: ./dockerfile
+          target: worker
           push: false
           tags: core-framework-worker:ci

{core_framework-1.0.0 → core_framework-1.2.0}/.gitignore

@@ -20,3 +20,7 @@ htmlcov/
 
 # Firebase
 firebase_config.json
+
+# Cursor debug
+firebase-debug.log
+ui-debug.log

{core_framework-1.0.0 → core_framework-1.2.0}/.pre-commit-config.yaml

@@ -34,7 +34,7 @@ repos:
     - id: uv-lock
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.15.10
+  rev: v0.15.12
   hooks:
     - id: ruff-check
       args: [ --fix ]

core_framework-1.2.0/CHANGELOG.md

@@ -0,0 +1,127 @@
+# Changelog
+
+Notable changes to **core-framework** (import **`core_framework`**). Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning is [SemVer](https://semver.org/spec/v2.0.0.html). Stable surface: **`docs/package-api.md`**.
+
+## [Unreleased]
+
+## [1.2.0] - 2026-05-02
+
+### Changed
+
+- **Breaking:** Caching is **cashews-only** — removed **`RedisCache`**, **`core_framework.core.redis_cache`**, legacy **`@cache`**, **`redis_cache_status`** on readiness; **`invalidate_cache`** targets cashews keys only.
+- **Breaking:** Workers use **ARQ** (not SAQ). Run **`arq core_framework.worker.main.WorkerSettings`**; tests use **`TestConfig.include_arq_fixtures`**. Queue name pinned to **`core_framework:queue`** (**`CORE_FRAMEWORK_QUEUE_NAME`**).
+- **Breaking:** **`WorkerLifecycleContext`** merged into **`WorkerJobContext`**; **`worker_context`** exports **`WorkerStartupContext`** and **`WorkerJobContext`** only.
+
+### Internal
+
+- Worker startup defers cashews until **`startup`** (fixes pytest + Testcontainers ordering).
+- Shared idempotent **`init_firebase(settings)`** for API lifespan and worker.
+- Worker schedules/tasks use **`logger.exception`** for tracebacks.
+
+### Documentation
+
+- Follow feature (HTTP, notifications, stats worker, mirrors, **`docs/follow-system-design.md`**, architecture decisions, domain READMEs, **`docs/api.md`**).
+
+## [1.1.1] - 2026-04-24
+
+### Changed
+
+- **`core_framework.testing`:** configurable ASGI lifespan timeouts for pytest / HTTP client fixtures.
+
+### Internal
+
+- **`uv.lock`** refresh.
+
+## [1.1.0] - 2026-04-22
+
+### Added
+
+- **`core-framework[testing]`** extra: pytest plugin (**`pytest11`** → **`core_framework.testing.plugin`**), **`TestConfig`**, session fixtures (Postgres, Redis, **`AsyncClient`**, migrations, Firebase helpers, optional SAQ). Parallel (**`pytest -n`**) coordination — see **`docs/testing-plugin-design.md`**. **`create_firebase_user_token`** helper.
+
+### Changed
+
+- **Breaking (bootstrap):** **`core_framework.asgi:app`** is **`init_app(load_default_settings())`** at import; **`core_framework.main`** no longer exposes module-level **`app`**. **`core_framework.core`** no longer re-exports **`settings`** — use **`core_framework.core.settings`**.
+
+### Documentation
+
+- **`docs/package-api.md`**, **`docs/core-framework-migration.md`**, **`README.md`**, **`docs/testing-plugin-design.md`** updated for testing and entrypoints.
+
+## [1.0.0] - 2026-04-18
+
+First **SemVer-stable** release per **`docs/package-api.md`**.
+
+### Breaking
+
+- **Alembic collapsed to six baselines** (`v1_ext_init` … `v1_notif_init`; order **`ALEMBIC_DOMAINS`**). **Fresh DB:** unchanged. **Already on pre-1.0 heads:** per-schema **`alembic stamp`** to the matching **`v1_*_init`** baseline before upgrading; **no supported downgrade** (baselines’ **`downgrade`** raises).
+- Pre-1.0 revision IDs in older notes are **historical** only (files removed).
+
+### Changed
+
+- Index tweaks in baselines (e.g. author/blocker lookup indexes; drops of unused indexes) — see git history for DDL detail.
+
+### Removed
+
+- Tests no longer **downgrade-to-base** per schema (empty DB + baselines only).
+
+## [0.5.0] - 2026-04-17
+
+### Added
+
+- **`author_context.is_notification_muted`** on post/comment when viewer is author. **`actor_id` NOT NULL** on user/moderation history (migration + backfill). **`user_restrictions_lookup`** in user schema + mirror sync with post/comment.
+
+### Changed
+
+- **`GET /notifications`:** **`actor`** object replaces top-level **`actor_id`**. History endpoints require **`actor`**. **`Postgres.get_transaction_with_actor_id`** supports explicit **`actor_id`**.
+
+### Documentation
+
+- Mentions flow, **`GET /users/usernames/suggest`**, **`docs/api.md`**.
+
+## [0.4.0] - 2026-03-26
+
+### Added
+
+- Bundled Alembic in wheel (**`core_framework/alembic/`**), **`core_framework.bundled_alembic`**, console script **`cf-alembic`**.
+
+### Changed
+
+- Script renamed from **`cff-migrate`** to **`cf-alembic`**. **`pyproject`**: dropped **`readme`** from **`[project]`** for lean Docker builds. OpenAPI title **`core-framework API`**. **`main.app`** / worker **`task_worker`** import-time behavior adjusted (SAQ). Application DI: domain modules as namespaces; **`configure_application_dependencies`**; cashews wiring.
+
+### Fixed
+
+- **Worker Docker image:** builder copies **`alembic/`** for Hatch force-include.
+
+### CI
+
+- **package-smoke** and **docker-build** on PRs; Docker Hub image name **`core-framework`**.
+
+### Documentation
+
+- **`README`**, **`docs/core-framework-migration.md`**, **`docs/package-api.md`**, **`docs/architecture.md`** (runtime / bootstrap).
+
+### Removed
+
+- **`load_default_runtime()`**, **`DependencyHolder`**, **`core_framework.core.runtime`** package attribute shadowing the runtime module.
+
+## [0.3.0] - 2026-03-25
+
+### Added
+
+- **`init_app(settings)`**, **`create_task_worker(settings)`**, **`CoreRuntime`**, **`build_core_runtime`**, **`configure_application_dependencies`**, **`load_default_settings()`**, **`configure_core_runtime`**. **`docs/package-api.md`**.
+
+### Changed
+
+- Embedding: prefer full bootstrap via **`init_app`**; **`/readiness`** needs **`app.state.core_runtime`**. Pagination, event tokens, media URLs, cache fail fast if not configured.
+
+### Migration
+
+- Host: **`Settings`** from host config → **`init_app(settings)`**; **`configure_core_runtime(runtime)`** if using **`core_framework.core`** globals directly.
+
+[0.3.0]: https://github.com/NepNepFFXIV/core-framework/compare/v0.2.0...v0.3.0
+[0.4.0]: https://github.com/NepNepFFXIV/core-framework/compare/v0.3.0...v0.4.0
+[0.5.0]: https://github.com/NepNepFFXIV/core-framework/compare/v0.4.0...v0.5.0
+[1.0.0]: https://github.com/NepNepFFXIV/core-framework/compare/v0.5.0...v1.0.0
+[1.1.0]: https://github.com/NepNepFFXIV/core-framework/compare/v1.0.0...v1.1.0
+[1.1.1]: https://github.com/NepNepFFXIV/core-framework/compare/v1.1.0...v1.1.1
+[1.2.0]: https://github.com/NepNepFFXIV/core-framework/compare/v1.1.1...v1.2.0
+[unreleased]: https://github.com/NepNepFFXIV/core-framework/compare/v1.2.0...HEAD