core-framework 1.3.0__tar.gz → 1.5.0__tar.gz

core_framework-1.5.0/.cursor/rules/code-review-output.mdc

@@ -0,0 +1,31 @@
+---
+description: When the user asks for a code review or audit, report only issues and improvements—not strengths
+alwaysApply: true
+---
+
+# Code review output
+
+When the user asks for a **review**, **audit**, or similar (e.g. "review my code", "comprehensive review", "what's wrong with"):
+
+## Report only
+
+- **Bugs** and correctness risks
+- **Wrong** behavior vs design docs, API contracts, or project rules
+- **Improvements** and **optimizations** worth making
+- **Contradictions** between code and documented intent (including doc drift)
+
+Prioritize by severity. Include enough context (file, behavior, suggested fix direction) to act on each item.
+
+## Do not report
+
+- Sections praising what is **solid**, **well done**, or **correctly implemented**
+- **"What's good"** / **"Overall assessment"** summaries that restate strengths
+- Long **checklist pass** narratives ("layering is clean", "DI is wired correctly") unless a listed item is actually broken
+
+A one-line **scope** (what was reviewed) is fine. If nothing actionable is found, say so briefly—do not pad with compliments.
+
+## Accepted trade-offs
+
+Do **not** list documented accepted trade-offs as findings unless the user asked about them or the implementation **violates** the documented trade-off (then report the violation).
+
+Follow the **code-review** skill for *how* to review (docs to read, checklists); this rule governs *what to include in the answer*.

{core_framework-1.3.0 → core_framework-1.5.0}/.cursor/rules/constants-final.mdc

@@ -9,7 +9,7 @@ alwaysApply: false
 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`**.
+- 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-1.3.0 → core_framework-1.5.0}/.cursor/rules/database-triggers.md

@@ -124,30 +124,7 @@ $$ language plpgsql;
 - Error message isn't localized
 - Makes assumptions about business rules
 
-**Correct approach:**
-
-```python
-# In service layer
-async def change_profile(
-    self,
-    *,
-    actor_id: str,
-    user_id: str,
-    validated_update_request: dict[str, Any],
-) -> None:
-    if "username" in validated_update_request:
-        recent_changes = await self.repository.select_recent_username_changes(
-            user_id=user_id, since=datetime.now(timezone.utc) - timedelta(days=7)
-        )
-        if recent_changes:
-            raise UsernameCooldownException()
-
-    await self.repository.update_profile(
-        user_id=user_id,
-        validated_update_request=validated_update_request,
-        actor_id=actor_id,
-    )
-```
+**Correct approach:** enforce cooldown (or other policy) in the service, then call the repository with a typed **`ProfileUpdate`** (or the relevant `*Update`).
 
 ### ❌ Bad: Automatic State Transitions
 

{core_framework-1.3.0 → core_framework-1.5.0}/.cursor/rules/domain-imports.mdc

@@ -57,6 +57,15 @@ from core_framework.domains.user.service import UserService  # ❌
 4. **Consistency across adapters**: API and application layers follow the same domain import contract
 5. **Dependency direction**: Prevents tight coupling to internal implementation details
 
+## Domain `__init__.py` export policy
+
+Export a symbol from a domain's **`__init__.py`** only when it is consumed **outside** that domain package — for example API, application, infrastructure adapters, exception handlers, or workers (via application services).
+
+- **Do export**: exceptions, constants, and models that outer layers or adapters import.
+- **Do not export**: persistence/registry shapes, repository row mappings, and other types used only inside **`domains/<name>/`** (repository, service, components). Import those from submodule paths within the domain.
+
+When adding a new model or exception, default to **not** exporting; add to **`__init__.py`** only when an outer layer needs it.
+
 ## Available Domain Exports
 
 ### Moderation Domain (`from core_framework.domains.moderation import ...`)
@@ -72,11 +81,18 @@ from core_framework.domains.user.service import UserService  # ❌
 - **Service**: Use `user_service` from `dependencies.py`
 - **Internal** (do not import from API layer): `DomainUserNotFoundException` — handled within domain; API uses `None` return values
 
+### Media Domain (`from core_framework.domains.media import ...`)
+- **Constants**: `AVATAR_INGEST_MAX_BYTES`, `AVATAR_INGEST_UPLOAD_CHUNK_BYTES`, `AVATAR_FINAL_VARIANT_128`, `AVATAR_FINAL_VARIANT_500`
+- **Models**: `AvatarIngestRegistration`, `AvatarVariantBytes`
+- **Exceptions**: `BaseMediaException`, `AvatarIngestBodyTooLargeException`, `AvatarIngestLeaseConflictException`, `AvatarIngestUnsupportedContentTypeException`, `AvatarStagingBlobNotFoundException`, `AvatarFinalsPublishException`
+- **Service**: Use `avatar_service` / `media_service` from `dependencies.py`
+- **Internal** (not in `__init__.py`): `AvatarStagingRegistryEntry` — repository and `AvatarService` only; application uses service methods, not the registry row type
+
 ## How to Fix Violations
 
 If you need something that's not exported in `__init__.py`:
 
-1. **Check if it should be public**: If it's needed by the API layer, add it to the domain's `__init__.py`
+1. **Check if it should be public**: If an outer layer (API, application, infrastructure adapter, exception handler) needs it, add it to the domain's `__init__.py`. If only repository/service code inside the domain needs it, keep it internal.
 2. **Reconsider the design**: If it's internal implementation, maybe the API layer shouldn't access it directly
 3. **Use the service**: Most domain logic should be accessed through `{domain}_service` from `dependencies.py`
 

{core_framework-1.3.0 → core_framework-1.5.0}/.cursor/rules/domain-input-guards.mdc

@@ -43,13 +43,14 @@ Use these across domains so validation stays consistent and call sites stay read
 | **`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`**). |
 
 Prefer **`require_non_blank_kwargs`** / **`require_non_blank_if_not_none`** over many repeated **`require_non_blank`** lines when a method checks several fields.
 
+**PATCH partial updates:** domain `*Update` dataclasses (e.g. **`ProfileUpdate`**) expose **`require_has_updates()`** (non-empty body with at least one allowed field) and **`fields_set`** (which keys the client sent). API mappers build these from Pydantic **`model_fields_set`**; services call **`update.require_has_updates()`** before repository writes. Empty PATCH bodies remain rejected at the API via **`BasePatchRequest`**.
+
 ## Repository (thin data access; no duplicate validation)
 
-- **Call path**: API and application code must not import repositories directly (see **`domain-imports.mdc`**); they use **`{domain}_service`** from **`dependencies.py`**. So e.g. **`UserRepository.update_preferences` / `update_profile` / `update_account`** are only reached through **`UserService`**, which runs **`require_validated_update_has_allowed_fields`**—there is no supported bypass for empty or all-unknown PATCH bodies in product code.
+- **Call path**: API and application code must not import repositories directly (see **`domain-imports.mdc`**); they use **`{domain}_service`** from **`dependencies.py`**. PATCH flows reach **`UserRepository.update_*`** (and post/comment equivalents) only through **`UserService.change_*`**, which runs **`require_has_updates()`** on the typed update—there is no supported bypass for empty or all-unknown PATCH bodies in product code.
 - **Prefer no input-validation guards** in repositories (empty batches, non-blank strings, pagination limits, positive int IDs): the **domain service** owns those contracts. The repository runs SQL; **`WHERE … = any($1)`** with an empty array is valid in Postgres and returns no rows.
 - Only add a repository guard for **SQL-specific** hazards that are awkward to express as service policy (rare); **do not** duplicate service-level “skip if empty” logic.
 - **Do not** use the repository as the **main** home for product rules that belong in the service.

core_framework-1.5.0/.cursor/rules/domain-services-and-adapters.mdc

@@ -0,0 +1,47 @@
+---
+description: Domain bounded contexts may use multiple services and ports; application orchestrates; repositories stay Postgres-only
+globs:
+  - core_framework/domains/**/*.py
+  - core_framework/application/**/*.py
+---
+
+# Domain Services and Adapters
+
+See **`docs/domain-services-and-adapters.md`** for the full model. Apply when adding or changing domain packages and application orchestration.
+
+## Application = orchestration
+
+- **`core_framework/application/...`** sequences multi-step use cases shared by API and worker (call domain services, enqueue jobs, coordinate cross-domain steps).
+- Do **not** move shared orchestration into API routers or worker handlers when it is reused across transports.
+- Do **not** treat application modules as the long-term home for concrete filesystem/HTTP/SSH clients—use domain ports + components + adapters (below).
+
+## Domain ≠ database only
+
+- A bounded context owns **business rules and contracts** for all of its capabilities, not only its Postgres schema.
+- **Repositories** remain **Postgres-only** (SQL in repository + row mapping).
+- **Non-SQL I/O** uses **ports**, **components**, and **adapters**—not `*Repository`.
+
+## Multiple services per domain
+
+- Facade **`*Service`** is wired in `dependencies`; internal **`*Component`** classes wrap ports.
+- Do not mix SQL, `aiofiles`, HTTP, or SSH in one class.
+- Application resolves facade services via **`import ...dependencies as ..._deps`**.
+
+## Ports, components, and adapters
+
+- **Port** — `*Port` in `domains/<capability>/ports/`; no I/O imports.
+- **Component** — `*Component` in `domains/<capability>/components/`; port + domain rules; composed by facade `*Service`.
+- **Adapter** — `*Adapter` in `infrastructure/<domain>/`; transport prefix when multiple impls.
+- Wire adapters only in `dependencies.py`; application uses facade `*_deps` services.
+
+## Prohibited
+
+- SQL and filesystem/HTTP/SSH in the same **repository** or god **service** class.
+- Domain imports from `core_framework.api`, `core_framework.worker`, or `core_framework.application`.
+- Infrastructure imports in domain modules except **`dependencies.py`** (existing rule).
+
+## Media ingest (v1)
+
+- **Layout:** `domains/media/shared/`, `avatar/ports/`, `avatar/components/`, `AvatarService`.
+- **Avatar:** `media_deps.avatar_service` only (not individual components).
+- **Cross-domain:** `avatar_ingest_sequence` / profile `avatar_id` via **user** domain; orchestration in `application/media/avatar_service`.

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

@@ -0,0 +1,33 @@
+---
+description: FastAPI exception handler registration and typing conventions
+globs:
+  - core_framework/core/exception_handlers/**/*.py
+---
+
+# Exception Handlers
+
+Domain-specific HTTP exception handlers live under **`core_framework/core/exception_handlers/`**.
+
+## Registration
+
+- Register handlers with **`register_exception_handler`** from **`core_framework.core.exception_handlers.common`**.
+- Do **not** call **`app.add_exception_handler`** directly from domain handler modules or **`setup.py`**.
+- Starlette’s **`ExceptionHandler`** type is wider than narrowly typed handlers; the single **`ty: ignore[invalid-argument-type]`** belongs in **`common.register_exception_handler`** only.
+
+## Handler functions
+
+- One async handler per mapped exception type: **`(Request, ExcT) -> JSONResponse`**.
+- Type **`exc`** as the **specific** domain exception (not bare **`Exception`**) so handler bodies stay narrow.
+- Map domain exceptions to HTTP status codes; use **`exc.message`** in **`{"detail": ...}`** for client-facing errors.
+- Register **specific** exceptions before domain **base** catch-alls (e.g. **`BasePostException`** last in that module).
+
+## Module layout
+
+- One module per domain (e.g. **`post.py`**, **`media.py`**) exporting **`add_*_exception_handlers(app)`**.
+- **`setup.py`** registers cross-cutting handlers, then calls each domain **`add_*_exception_handlers`**.
+- Base domain handlers return **`GENERIC_INTERNAL_SERVER_ERROR_DETAIL`** — not raw exception messages.
+
+## Avoid
+
+- Per-call-site **`ty: ignore[invalid-argument-type]`** or **`cast(ExceptionHandler, ...)`** on registrations.
+- Business logic or repository calls inside handlers — translate exception → HTTP response only.

core_framework-1.5.0/.cursor/rules/henry-cursor-rules-sync.mdc

@@ -0,0 +1,52 @@
+---
+description: When editing Cursor rules or skills in core-framework, sync applicable changes to henry-backend
+alwaysApply: true
+---
+
+# Henry cursor rules sync
+
+**Henry backend** embeds **core-framework** and shares most **`.cursor/rules/`** and **`.cursor/skills/`** content. Treat both repos as one rules surface unless the user scopes work to core-framework only.
+
+## When this applies
+
+Whenever you **add, edit, or remove** a file under **`.cursor/rules/`** or **`.cursor/skills/`** in **this** repository — including new always-on rules, skill workflow updates, and convention changes from feature work (e.g. media/avatar).
+
+## Required follow-up
+
+1. **Sync to henry-backend** in the **same task** or as the **immediate next step** after the user accepts the core-framework rule change.
+2. Diff by **basename** against **`henry-backend/.cursor/`** (sibling repo or second workspace root).
+3. Mention in your response that henry-backend was synced, or that it still needs sync if you stopped at core-only per user scope.
+
+## How to sync
+
+- **Shared rules/skills** — port into henry-backend and **adapt** for the host:
+  - globs: **`core_framework/**`** → **`src/**`** where host code applies
+  - imports: **`core_framework....`** vs **`src....`**
+  - strong reads: **`strong-read-opt-in`** → **`host-strong-read-opt-in`**
+  - host boundaries: reference **`henry-host-context`**
+- **Do not overwrite** henry-only files:
+  - **`.cursor/rules/henry-host-context.mdc`**
+  - **`.cursor/rules/host-strong-read-opt-in.mdc`**
+  - **`.cursor/skills/add-host-domain/SKILL.md`**
+- **Henry-only equivalents** — if core adds a rule with core-only globs (e.g. **`domain-input-guards`** on **`core_framework/**`**), ensure henry has coverage for **`src/**`** via an existing or new host-scoped rule.
+
+## Related docs
+
+When a rule encodes a new convention, check whether **`docs/`** in both repos need the same story.
+
+**Core `docs/` must stay host-agnostic** — no references to Henry, henry-backend, or other specific consuming applications. Use generic “host application” language only.
+
+Sync to henry when core changes:
+
+- **`docs/architecture.md`** → henry **`docs/architecture.md`** (Henry preamble + synced body; adapt `docs/flows/…` links in henry to **`docs/core-product-docs.md`**)
+- **`docs/domain-services-and-adapters.md`** → update henry host summary; core remains canonical
+- **`docs/conventions.md`**, **`docs/architecture-decisions.md`** → synced copies in henry when they exist in core (adapt flow-doc links in henry)
+- **`docs/deployment/`**, **`docs/media-upload-pipeline-design.md`** → sync when shared deploy/media docs change (adapt flow links in henry)
+
+**Do not** mirror **`docs/flows/`** into henry-backend. Henry maintains **`docs/core-product-docs.md`** as a pointer/index to core product documentation.
+
+Do not overwrite henry-only docs (e.g. **`docs/henry-users-architecture.md`**, calculator architecture, **`docs/core-product-docs.md`**, **`docs/flows/henry/`**).
+
+## User-triggered sync
+
+Phrases like **"sync rules with henry"** mean: diff **`.cursor/rules/`** and **`.cursor/skills/`** between repos and port any missing or stale shared content.

{core_framework-1.3.0 → core_framework-1.5.0}/.cursor/rules/implementation-workflow.mdc

@@ -36,17 +36,17 @@ After the user accepts database changes (or if there were none):
 
 After the user accepts the API layer (or if there was no API layer):
 
-- Implement the **Repository** for the domain layer.
+- Implement the **Repository** for the domain layer (Postgres only).
 - Include the **domain model** if data is retrieved from the database.
-- Focus on how data is read from and written to the database.
+- If the feature needs non-SQL I/O (filesystem, HTTP, SSH), add **ports** in the domain and **adapter implementations** under `core_framework/infrastructure/<domain>/` per `docs/domain-services-and-adapters.md`—not in the repository.
 - Wait for the user to review and accept before proceeding.
 
 ## 4. Service and Application Layer
 
-After the user accepts the repository:
+After the user accepts the repository (and any ports/adapters):
 
-- Implement the **service** layer.
-- Implement the **application** layer.
+- Implement **domain service(s)** (persistence and any port-backed collaborators); wire in `dependencies.py`.
+- Implement the **application** layer (orchestration across domains and transports—no permanent home for raw I/O libraries).
 - Wire everything together (replace 501 with real logic).
 - Wait for the user to review and accept before proceeding.
 

{core_framework-1.3.0 → core_framework-1.5.0}/.cursor/rules/layer-boundaries.mdc

@@ -14,16 +14,18 @@ Use this architecture split consistently:
 - `core_framework/api/...` -> HTTP routers/schemas/dependencies only
 - `core_framework/worker/...` -> schedules/tasks/job handlers only
 - `core_framework/application/...` -> transport-agnostic orchestration shared by API + worker
-- `core_framework/domains/...` -> core domain logic, models, repositories
+- `core_framework/domains/...` -> core domain logic, models, repositories (and optional ports/adapters for non-SQL I/O — see `domain-services-and-adapters`)
 
 ## Rules
 
 - API layer must not contain business orchestration that is shared with workers.
 - 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).
+- Worker code must not import **`core_framework.domains`** packages (no direct domain repository/service usage from workers), **except** narrow **housekeeping cron** handlers that call a configured domain service facade (e.g. **`schedule_sweep_stale_avatar_staging`** → **`media_deps.avatar_service`**). Do not add new worker→domain shortcuts without the same documented housekeeping rationale.
 - 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`.
+- Repositories are Postgres-only; filesystem, HTTP, SSH, and similar I/O use domain ports/adapters (separate collaborators), not repository methods.
+- Application orchestrates multi-step flows; do not fold shared API+worker orchestration into domain services to avoid “application” existing.
 
 ## Dependency Direction
 

core_framework-1.5.0/.cursor/rules/structured-logging.mdc

@@ -0,0 +1,35 @@
+---
+description: Use concise English sentences for structlog event strings
+alwaysApply: true
+---
+
+# Structured logging (structlog)
+
+Use **structlog** (`get_logger`, `logger.info`, `logger.exception`, etc.). The **first positional argument** is the **event** string (JSON `"event"` in non-local environments).
+
+## Event strings
+
+- Write the event as a **short English sentence** — readable in local console and in log viewers.
+- Use **sentence case**. Prefer past tense for failures (**"Failed to …"**, **"… failed"**).
+- Put **IDs, counts, and context** in **keyword fields**, not in the event string.
+- Do **not** use snake_case machine identifiers as events (for example `process_media_asset_variants_failed`).
+
+```python
+# ✅ Preferred
+logger.info(
+    "Skipped variant processing: staging registry missing",
+    owner_user_id=owner_user_id,
+    asset_id=asset_id,
+)
+logger.exception("Avatar variant processing failed", asset_id=asset_id)
+
+# ❌ Avoid
+logger.info("process_media_asset_variants_skipped_missing_registry", asset_id=asset_id)
+logger.exception("delete_superseded_avatar_finals_failed", asset_id=asset_id)
+```
+
+## When editing
+
+- **New** log calls must use English event strings.
+- When you **change** logging in a function or module, convert nearby snake_case events in that same touch to English.
+- Do **not** repo-wide migrate unrelated legacy event names unless the task asks for it.

{core_framework-1.3.0 → core_framework-1.5.0}/.cursor/skills/add-domain/SKILL.md

@@ -111,6 +111,8 @@ A single `class <Domain>Service:` whose **`__init__`** takes `<Domain>Repository
 
 When real behavior is added later, apply `repository-read-consistency` (`/.cursor/rules/repository-read-consistency.mdc`) for reads and `_strong` naming.
 
+If the bounded context needs filesystem, HTTP, or SSH, add **ports/adapters** or extra domain collaborators per `docs/domain-services-and-adapters.md` — do not put that I/O in `repository.py`.
+
 ### `__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.

{core_framework-1.3.0 → core_framework-1.5.0}/.cursor/skills/code-review/SKILL.md

@@ -7,6 +7,14 @@ description: Review code for quality, architecture compliance, and best practice
 
 When performing a code review, follow this workflow.
 
+## Output format (required)
+
+Apply **`.cursor/rules/code-review-output.mdc`**. The user wants **actionable findings only**:
+
+- Report bugs, wrong behavior, improvements, optimizations, and doc/code contradictions.
+- **Do not** include "what's solid", praise sections, or positive overall assessments.
+- If nothing is wrong, say so in one sentence—no filler.
+
 ## How to Ask (for the user)
 
 **Phrases that trigger this skill:** "review my code", "audit", "comprehensive review", "review comprehensively"
@@ -28,9 +36,10 @@ When performing a code review, follow this workflow.
 Read these files **before** proceeding with the review:
 
 1. **`docs/architecture.md`** – Domain boundaries, prohibited practices, and dependency rules
+1. **`docs/domain-services-and-adapters.md`** – Application orchestration vs domain services, ports/adapters, multiple collaborators per bounded context
 1. **`docs/conventions.md`** – Coding conventions, domain rules, caching, Redis, exception handling, API layer rules
 1. **`docs/architecture-decisions.md`** – Intentional design choices; do not flag these as issues
-1. **`.cursor/rules/api-layer.mdc`**, **`.cursor/rules/application-layer.mdc`**, **`.cursor/rules/domain-imports.mdc`**, **`.cursor/rules/domain-caller-context.mdc`** – Apply when reviewing API/application/domain code
+1. **`.cursor/rules/api-layer.mdc`**, **`.cursor/rules/application-layer.mdc`**, **`.cursor/rules/domain-services-and-adapters.mdc`**, **`.cursor/rules/domain-imports.mdc`**, **`.cursor/rules/domain-caller-context.mdc`** – Apply when reviewing API/application/domain code
 
 ## Step 2: Key Context
 

{core_framework-1.3.0 → core_framework-1.5.0}/.dockerignore

@@ -25,9 +25,8 @@ htmlcov/
 *.swo
 *~
 
-# Documentation
-README.md
-*.md
+# Documentation (wheel build needs root README.md; skip large doc tree)
+docs/
 
 # CI/CD
 .github/

{core_framework-1.3.0 → core_framework-1.5.0}/.github/workflows/_deploy.yml

@@ -39,10 +39,13 @@ jobs:
           REDIS_HOST: ${{ secrets.REDIS_HOST }}
           REDIS_PORT: ${{ secrets.REDIS_PORT }}
           ALLOWED_HOSTS: ${{ secrets.ALLOWED_HOSTS }}
-          AVATAR_BASE_URL: ${{ secrets.AVATAR_BASE_URL }}
-          AVATAR_DEFAULT_URL: ${{ secrets.AVATAR_DEFAULT_URL }}
-          BANNER_BASE_URL: ${{ secrets.BANNER_BASE_URL }}
-          BANNER_DEFAULT_URL: ${{ secrets.BANNER_DEFAULT_URL }}
+          AVATAR_HOST_DOMAIN: ${{ secrets.AVATAR_HOST_DOMAIN }}
+          AVATAR_DEFAULT_IMAGE: ${{ secrets.AVATAR_DEFAULT_IMAGE }}
+          BANNER_HOST_DOMAIN: ${{ secrets.BANNER_HOST_DOMAIN }}
+          BANNER_DEFAULT_IMAGE: ${{ secrets.BANNER_DEFAULT_IMAGE }}
+          IMAGE_SERVER_HOST: ${{ secrets.IMAGE_SERVER_HOST }}
+          IMAGE_SERVER_PORT: ${{ secrets.IMAGE_SERVER_PORT }}
+          IMAGE_SERVER_USER: ${{ secrets.IMAGE_SERVER_USER }}
           LOGFIRE_TOKEN: ${{ secrets.LOGFIRE_TOKEN }}
           CORS_ALLOWED_ORIGINS: ${{ secrets.CORS_ALLOWED_ORIGINS }}
         run: |
@@ -86,6 +89,28 @@ jobs:
               sys.exit(1)
           PY
 
+      - name: Generate image_server_ssh_key from secret
+        env:
+          IMAGE_SERVER_SSH_PRIVATE_KEY: ${{ secrets.IMAGE_SERVER_SSH_PRIVATE_KEY }}
+        run: |
+          set -euo pipefail
+
+          echo "Generating image_server_ssh_key..."
+          printf '%s\n' "$IMAGE_SERVER_SSH_PRIVATE_KEY" > image_server_ssh_key
+          test -s image_server_ssh_key
+          chmod 600 image_server_ssh_key
+
+      - name: Generate image_server_known_hosts from secret
+        env:
+          IMAGE_SERVER_KNOWN_HOSTS: ${{ secrets.IMAGE_SERVER_KNOWN_HOSTS }}
+        run: |
+          set -euo pipefail
+
+          echo "Generating image_server_known_hosts..."
+          printf '%s\n' "$IMAGE_SERVER_KNOWN_HOSTS" > image_server_known_hosts
+          test -s image_server_known_hosts
+          chmod 644 image_server_known_hosts
+
       - name: Upload rendered config.toml, firebase_config.json and docker-compose.yml
         uses: appleboy/scp-action@v1
         with:
@@ -93,7 +118,7 @@ jobs:
           username: ${{ secrets.SERVER_USER }}
           key: ${{ secrets.SERVER_SSH_KEY }}
           port: ${{ secrets.PORT }}
-          source: "config.toml,firebase_config.json,docker-compose.yml"
+          source: "config.toml,firebase_config.json,docker-compose.yml,image_server_ssh_key,image_server_known_hosts"
           target: "/home/${{ secrets.SERVER_USER }}/app_configs/core-framework"
 
       - name: Deploy to Server via SSH
@@ -113,13 +138,30 @@ jobs:
             DOCKERHUB_USERNAME="${{ inputs.dockerhub_username }}"
             CONFIG_PATH="/home/${{ secrets.SERVER_USER }}/app_configs/core-framework/config.toml"
             FIREBASE_CONFIG_PATH="/home/${{ secrets.SERVER_USER }}/app_configs/core-framework/firebase_config.json"
+            AVATAR_STAGING_PATH="/home/${{ secrets.SERVER_USER }}/app_configs/core-framework/avatar-staging"
+            IMAGE_SERVER_SSH_KEY_PATH="/home/${{ secrets.SERVER_USER }}/app_configs/core-framework/image_server_ssh_key"
+            IMAGE_SERVER_KNOWN_HOSTS_PATH="/home/${{ secrets.SERVER_USER }}/app_configs/core-framework/image_server_known_hosts"
 
             echo "Pulling latest image"
             DOCKERHUB_USERNAME="$DOCKERHUB_USERNAME" \
             CONFIG_PATH="$CONFIG_PATH" \
             FIREBASE_CONFIG_PATH="$FIREBASE_CONFIG_PATH" \
+            AVATAR_STAGING_PATH="$AVATAR_STAGING_PATH" \
+            IMAGE_SERVER_SSH_KEY_PATH="$IMAGE_SERVER_SSH_KEY_PATH" \
+            IMAGE_SERVER_KNOWN_HOSTS_PATH="$IMAGE_SERVER_KNOWN_HOSTS_PATH" \
             docker compose -f "$COMPOSE_FILE" pull
 
+            echo "Preparing avatar staging directory and image server SSH key permissions"
+            mkdir -p "$AVATAR_STAGING_PATH"
+            docker run --rm \
+              --user root \
+              -v "$AVATAR_STAGING_PATH:/app/avatar-staging" \
+              -v "$IMAGE_SERVER_SSH_KEY_PATH:/app/image-server-ssh-key" \
+              -v "$IMAGE_SERVER_KNOWN_HOSTS_PATH:/app/image-server-known-hosts" \
+              --entrypoint "" \
+              "$DOCKERHUB_USERNAME/core-framework:latest" \
+              sh -c 'mkdir -p /app/avatar-staging && chown -R appuser:appgroup /app/avatar-staging && chown appuser:appgroup /app/image-server-ssh-key && chmod 600 /app/image-server-ssh-key && chown appuser:appgroup /app/image-server-known-hosts && chmod 644 /app/image-server-known-hosts'
+
             echo "Running database migrations (cf-alembic iterates core_framework.bundled_alembic.ALEMBIC_DOMAINS in order)"
             docker run --rm \
               --network host \
@@ -131,6 +173,9 @@ jobs:
             DOCKERHUB_USERNAME="$DOCKERHUB_USERNAME" \
             CONFIG_PATH="$CONFIG_PATH" \
             FIREBASE_CONFIG_PATH="$FIREBASE_CONFIG_PATH" \
+            AVATAR_STAGING_PATH="$AVATAR_STAGING_PATH" \
+            IMAGE_SERVER_SSH_KEY_PATH="$IMAGE_SERVER_SSH_KEY_PATH" \
+            IMAGE_SERVER_KNOWN_HOSTS_PATH="$IMAGE_SERVER_KNOWN_HOSTS_PATH" \
             docker compose -f "$COMPOSE_FILE" up -d \
               --remove-orphans \
               --force-recreate \

{core_framework-1.3.0 → core_framework-1.5.0}/.gitignore

@@ -10,6 +10,9 @@ wheels/
 .venv
 .env
 
+# Avatar ingest staging (local disk)
+avatar-staging/
+
 # Logs
 logs/
 
@@ -21,6 +24,11 @@ htmlcov/
 # Firebase
 firebase_config.json
 
+# Image server SSH (local dev; production via deploy secrets)
+image-server-known-hosts
+image_server_known_hosts
+image_server_ssh_key
+
 # Cursor debug
 firebase-debug.log
 ui-debug.log

{core_framework-1.3.0 → core_framework-1.5.0}/CHANGELOG.md

@@ -4,6 +4,68 @@ Notable changes to **core-framework** (import **`core_framework`**). Format foll
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-05-26
+
+### Added
+
+- **Avatar upload (v1):** **`POST /users/me/profile/avatar`**, **`media`** schema, worker variant processing, staging sweep cron, **`[avatar].staging_root`** config. See **`docs/flows/media/upload_pipeline.md`** and **`docs/flows/users/profile.md`**.
+
+### Fixed
+
+- **Stale staging sweep:** **`delete_avatar_staging_blobs`** returns removed filenames; registry rows are deleted only when the staging file was removed or already missing (failed disk deletes retain the registry row for retry).
+- **ARQ queue mismatch:** API **`RedisQueue`** pool now uses **`default_queue_name=core_framework:queue`**, matching worker consumers, so application enqueues (for example avatar variant processing) are no longer dropped on ARQ's default **`arq:queue`**.
+
+### Changed
+
+- **Breaking:** **`[image_server].known_hosts_path`** is required; **`SshAvatarFinalsPublisherAdapter`** verifies the image server SSH host key (no longer **`known_hosts=None`**). Deploy must provide **`IMAGE_SERVER_KNOWN_HOSTS`** and mount **`/app/image-server-known-hosts`** on the worker. See **`docs/deployment/image-server-ssh.md`**.
+- **Breaking:** **`[avatar].avatar_host_domain`** is **host-only** in **`config.toml`** and deploy secret **`AVATAR_HOST_DOMAIN`** (for example **`avatar.example.com`**, no **`https://`**). The application prepends **`https://`** when assembling public avatar URLs. Values that still include a scheme are normalized at load time.
+- **Breaking:** **`[banner]`** config aligns with **`[avatar]`**: **`banner_host_domain`** + **`default_banner_image`** (deploy secrets **`BANNER_HOST_DOMAIN`**, **`BANNER_DEFAULT_IMAGE`**) replace **`base_url`** / **`default_url`**. Hostname is host-only; public banner URLs derive **`https://`** in application code.
+
+### Database
+
+- **Media** baseline **`v1_media_init`**: **`media`** schema with **`avatar_staging_registry`** and **`avatar_ingest_lease`**. Hosts must set **`schema_media`** under **`[postgres_schemas]`**.
+- **User** migration **`user_add_avatar_ingest_sequences`**: **`avatar_ingest_sequence`** and **`avatar_applied_sequence`** on **`user_profiles`**.
+- Run **`uv run cf-alembic`** (or the host **`cf-alembic`** step) before deploying code that uses avatar upload or variant processing.
+
+### Documentation
+
+- **Avatar upload edge limits:** **`docs/deployment/edge-upload-limits.md`**, **`docs/deployment/Caddyfile.example`** — route-scoped reverse-proxy **`max_size`** (**6 MiB** recommended) for **`POST /users/me/profile/avatar`**; updated **`docs/flows/media/upload_pipeline.md`** and **`docs/flows/users/profile.md`**.
+- **Image server SSH:** **`docs/deployment/image-server-ssh.md`**, **`docs/deployment/image-server-known-hosts.example`** — production checklist for **`known_hosts_path`** and **`IMAGE_SERVER_KNOWN_HOSTS`**.
+- **`docs/flows/media/upload_pipeline.md`**: status and HTTP surface aligned with shipped v1 implementation.
+- **`docs/flows/users/profile.md`**: **`POST /users/me/profile/avatar`** flow; **`PATCH`** no longer documents **`avatar_id`** as planned.
+- **`docs/flows/users/avatar.md`**, **`docs/flows/users/change_history.md`**: avatar change path and ingest MIME notes updated.
+- **`docs/flows/users/avatar.md`**, **`docs/flows/users/profile.md`**: **`avatar_host_domain`** documented as host-only; public URLs derive **`https://`** in application code.
+- **`docs/domain-services-and-adapters.md`**: **`banner_host_domain`** / **`default_banner_image`** config shape documented alongside avatar.
+
+## [1.4.0] - 2026-05-19
+
+### Changed
+
+- **Breaking:** **`avatar`** on profile and related user responses is an object (**`size_128`**, **`size_500`**, **`fallback`**) instead of a single URL string. See **`docs/flows/users/avatar.md`**.
+- **Breaking:** **`[avatar]`** config uses **`avatar_host_domain`** + **`default_avatar_image`** (deploy env **`AVATAR_HOST_DOMAIN`**, **`AVATAR_DEFAULT_IMAGE`**) instead of **`base_url`** / **`default_url`**.
+- **Typed PATCH payloads** — user (preferences, account, profile + admin profile), post, and comment PATCH routes map Pydantic requests to domain `*Update` types at the API boundary; no `model_dump(mode="json")` or dict partial-update payloads through application/domain/repository. See `docs/patch-update-typed-payload.md` and `docs/conventions.md` (*PATCH partial updates*).
+- Self-service profile PATCH invalidates **`USER_DETAIL`** only when **`display_name`** or **`avatar_id`** change (fields present in cached identity). **`profile_visibility`** is coerced to **`ProfileVisibility`** on repository read.
+
+### Added
+
+- Optional **`date_of_birth`** on user profiles: calendar date (`YYYY-MM-DD`), not in the future, omit unchanged / **`null`** clears. Exposed on **`GET`** / **`PATCH /users/me/profile`** and on admin user detail plus **`PATCH /admin/users/{user_id}/profile`**. Not returned on other users’ public surfaces (follow lists, post author cards, etc.).
+
+### Database
+
+- User domain migration **`user_add_date_of_birth`**: nullable **`date_of_birth`** column on **`user_profiles`**. Run **`uv run cf-alembic`** (or your host migration step) before deploying application code that reads or writes the field.
+
+### Documentation
+
+- **`docs/flows/users/avatar.md`**: multi-size **`avatar`** response shape and CDN URL convention.
+- **`docs/flows/media/upload_pipeline.md`**: upload pipeline design and v1 implementation reference.
+- **`docs/flows/users/profile.md`**: DOB on get/update flows and validation errors.
+- **`docs/flows/users/change_history.md`**: profile **`date_of_birth`** changes are not written to change history (audit trigger unchanged).
+- **`docs/patch-update-typed-payload.md`**: typed PATCH decisions and patterns for partial-update endpoints.
+
+### Fixed
+
+- **Dockerfile**: include **`README.md`** in the build context so hatchling can resolve the package readme.
+
 ## [1.3.0] - 2026-05-16
 
 ### Added
@@ -140,4 +202,6 @@ First **SemVer-stable** release per **`docs/package-api.md`**.
 [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
 [1.3.0]: https://github.com/NepNepFFXIV/core-framework/compare/v1.2.0...v1.3.0
-[unreleased]: https://github.com/NepNepFFXIV/core-framework/compare/v1.3.0...HEAD
+[1.4.0]: https://github.com/NepNepFFXIV/core-framework/compare/v1.3.0...v1.4.0
+[1.5.0]: https://github.com/NepNepFFXIV/core-framework/compare/v1.4.0...v1.5.0
+[unreleased]: https://github.com/NepNepFFXIV/core-framework/compare/v1.5.0...HEAD

{core_framework-1.3.0 → core_framework-1.5.0}/PKG-INFO

@@ -1,17 +1,19 @@
 Metadata-Version: 2.4
 Name: core-framework
-Version: 1.3.0
+Version: 1.5.0
 Summary: Core framework package (import as core_framework)
 Project-URL: Homepage, https://github.com/NepNepFFXIV/core-framework
 Project-URL: Repository, https://github.com/NepNepFFXIV/core-framework
 License-Expression: MIT
 License-File: LICENSE
 Requires-Python: >=3.14
+Requires-Dist: aiofiles>=25.1.0
 Requires-Dist: alembic>=1.18.4
 Requires-Dist: arq>=0.28.0
 Requires-Dist: async-lru>=2.1.0
 Requires-Dist: asyncer>=0.0.14
 Requires-Dist: asyncpg>=0.31.0
+Requires-Dist: asyncssh>=2.23.0
 Requires-Dist: brotli-asgi>=1.6.0
 Requires-Dist: cashews[redis]>=7.5.0
 Requires-Dist: device-detector>=6.2.0
@@ -22,6 +24,7 @@ Requires-Dist: itsdangerous>=2.2.0
 Requires-Dist: logfire[asyncpg,fastapi,httpx,redis]>=4.32.1
 Requires-Dist: mashumaro[orjson]>=3.20
 Requires-Dist: orjson>=3.11.7
+Requires-Dist: pillow>=12.2.0
 Requires-Dist: python-ulid>=3.1.0
 Requires-Dist: structlog>=25.5.0
 Requires-Dist: tenacity>=9.1.4