core-framework 1.4.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.4.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.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.4.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.4.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.4.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.4.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.4.0 → core_framework-1.5.0}/.github/workflows/_deploy.yml

@@ -41,8 +41,11 @@ jobs:
           ALLOWED_HOSTS: ${{ secrets.ALLOWED_HOSTS }}
           AVATAR_HOST_DOMAIN: ${{ secrets.AVATAR_HOST_DOMAIN }}
           AVATAR_DEFAULT_IMAGE: ${{ secrets.AVATAR_DEFAULT_IMAGE }}
-          BANNER_BASE_URL: ${{ secrets.BANNER_BASE_URL }}
-          BANNER_DEFAULT_URL: ${{ secrets.BANNER_DEFAULT_URL }}
+          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.4.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.4.0 → core_framework-1.5.0}/CHANGELOG.md

@@ -4,6 +4,39 @@ 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
@@ -24,7 +57,7 @@ Notable changes to **core-framework** (import **`core_framework`**). Format foll
 ### Documentation
 
 - **`docs/flows/users/avatar.md`**: multi-size **`avatar`** response shape and CDN URL convention.
-- **`docs/flows/media/upload_pipeline.md`**: upload pipeline design (implementation pending).
+- **`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.
@@ -170,4 +203,5 @@ First **SemVer-stable** release per **`docs/package-api.md`**.
 [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
 [1.4.0]: https://github.com/NepNepFFXIV/core-framework/compare/v1.3.0...v1.4.0
-[unreleased]: https://github.com/NepNepFFXIV/core-framework/compare/v1.4.0...HEAD
+[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.4.0 → core_framework-1.5.0}/PKG-INFO

@@ -1,17 +1,19 @@
 Metadata-Version: 2.4
 Name: core-framework
-Version: 1.4.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

core_framework-1.5.0/alembic/media/alembic/env.py

@@ -0,0 +1,72 @@
+import asyncio
+from logging.config import fileConfig
+
+from sqlalchemy import pool, text
+from sqlalchemy.engine import Connection
+from sqlalchemy.ext.asyncio import async_engine_from_config
+
+from alembic import context
+from core_framework.core.settings import load_default_settings
+
+settings = load_default_settings()
+
+config = context.config
+
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+target_metadata = None
+
+config.set_main_option("sqlalchemy.url", settings.write_postgres.alembic_postgres_url)
+
+
+def run_migrations_offline() -> None:
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    quoted_schema_name = f'"{settings.postgres_schemas.schema_media.replace('"', '""')}"'
+
+    with context.begin_transaction():
+        context.execute(text(f"set search_path to {quoted_schema_name}"))
+        context.run_migrations()
+
+
+def do_run_migrations(connection: Connection) -> None:
+    quoted_schema_name = f'"{settings.postgres_schemas.schema_media.replace('"', '""')}"'
+
+    connection.execute(text(f"create schema if not exists {quoted_schema_name}"))
+    connection.execute(text(f"set search_path to {quoted_schema_name}"))
+    connection.commit()
+
+    context.configure(connection=connection, target_metadata=target_metadata)
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_async_migrations() -> None:
+    connectable = async_engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+
+    await connectable.dispose()
+
+
+def run_migrations_online() -> None:
+    asyncio.run(run_async_migrations())
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

core_framework-1.5.0/alembic/media/alembic/versions/v1_media_init_baseline.py

@@ -0,0 +1,45 @@
+"""v1 media baseline
+
+Initial migration for the media schema: avatar staging registry and ingest lease.
+
+Revision ID: v1_media_init
+Revises:
+Create Date: 2026-05-20 12:00:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "v1_media_init"
+down_revision: str | Sequence[str] | None = None
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        create table avatar_staging_registry (
+            asset_id varchar(26) not null primary key,
+            owner_user_id varchar(128) not null,
+            staging_filename text not null,
+            created_at timestamptz not null default now()
+        );
+    """)
+
+    op.execute("""
+        create index idx_avatar_staging_registry_created_at
+            on avatar_staging_registry (created_at);
+    """)
+
+    op.execute("""
+        create table avatar_ingest_lease (
+            owner_user_id varchar(128) not null primary key,
+            lease_expires_at timestamptz not null
+        );
+    """)
+
+
+def downgrade() -> None:
+    raise RuntimeError("downgrade is not supported for v1 baseline migrations")