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

core_framework-3.3.0/.cursor/rules/alembic-migrations.mdc

@@ -0,0 +1,61 @@
+---
+description: Alembic migrations — revision id format and index DDL conventions
+globs: alembic/**/alembic/versions/*.py
+alwaysApply: false
+---
+
+# Alembic migrations
+
+## Revision IDs
+
+`alembic_version.version_num` is a **32-character** string. Revision ids must stay well under that limit.
+
+### New revisions (required)
+
+- Set `revision` to a **12-character lowercase hex** string (Alembic default), e.g. `a56bc6b7f799`.
+- Generate with `python -c "import secrets; print(secrets.token_hex(6))"` or `alembic revision`.
+- Put the human-readable slug in the **filename** and the module docstring `Revision ID:` line only if you mirror the hex id there — **do not** use descriptive slugs as `revision`.
+
+```python
+# ✅ Preferred
+"""replace deleted post status with tombstone statuses
+
+Revision ID: 120bf6be81eb
+Revises: a56bc6b7f799
+"""
+
+revision: str = "120bf6be81eb"
+```
+
+```python
+# ❌ Avoid — long, wastes version_num budget, inconsistent with recent migrations
+revision: str = "post_tombstone_status_model"
+```
+
+### Exceptions
+
+- Collapsed **`v1_*_init`** baseline revisions keep their stable names (`v1_post_init`, etc.) — do not rename shipped baselines.
+- **Legacy descriptive slug** revision ids (e.g. `post_add_post_mentions`, `user_add_date_of_birth`) stay as-is. Do not rewrite or collapse history just to convert them to hex. Do not re-flag them on B11 unless a deliberate baseline collapse is in progress.
+
+### Do not rename shipped revision ids
+
+If a revision may already be applied in any environment, **do not** change its `revision` string. Add a forward migration instead.
+
+## Index DDL
+
+### New index migrations (required)
+
+In **`upgrade()`**, create indexes with **`IF NOT EXISTS`** so migrations succeed when an index was already applied manually in production:
+
+```python
+op.execute("""
+    create index if not exists idx_example_created_at
+    on example_table (created_at);
+""")
+```
+
+Use **`drop index if exists`** in **`downgrade()`**.
+
+### Do not retrofit index DDL
+
+Do **not** edit shipped migrations only to add `if not exists` — those revisions may already be applied. New forward migrations follow this rule; legacy `create index` without `if not exists` stays as-is.

core_framework-3.3.0/.cursor/rules/domain-imports.mdc

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

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

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

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

@@ -0,0 +1,87 @@
+---
+description: Domain repositories must not query other domains' Postgres schemas
+globs:
+  - core_framework/domains/**/repository.py
+alwaysApply: false
+---
+
+# Repository schema isolation
+
+Each domain repository may only read/write tables in **its own** Postgres schema.
+
+Canonical rule: `docs/platform/layers-and-boundaries.md` — *no cross-domain schema reads, writes, joins, or foreign keys*.
+
+## Schema qualification
+
+Repositories receive unquoted `schema` from `runtime.settings.postgres_schemas` in `dependencies.py` (keyword-only `__init__` arg). In `__init__`:
+
+- `self.schema` — config schema name (e.g. `post`)
+- `self.schema_sql` — `quote_postgres_identifier(schema)` for SQL interpolation
+
+Use `{self.schema_sql}.table` in f-string SQL — not hard-coded `"post".` literals.
+
+## Allowed in a repository
+
+- SQL qualified with that domain's schema only (e.g. `{self.schema_sql}.posts` in `PostRepository`).
+- **Within-schema** policy gates (e.g. `insert_post_like` checks `{self.schema_sql}.posts.status = active`).
+- **Lookup mirrors** in the same schema (`user_blocks_lookup`, `user_restrictions_lookup`, `user_followers_lookup`) — synced by application flows; mirrors are not authoritative.
+
+## Forbidden in a repository
+
+- `FROM` / `JOIN` / `EXISTS` / `INSERT … SELECT` against another domain's schema.
+- Importing another domain's `service`, `repository`, or models to enforce policy.
+
+```python
+# ❌ moderation/repository.py — cross-domain EXISTS (illustrative schema literals)
+insert into {moderation_schema_sql}.post_reports (...)
+select $1, $2, $3, $4
+where exists (
+    select 1 from {post_schema_sql}.posts
+    where id = $2 and status = 'active'
+)
+
+# ❌ notification/repository.py — cross-domain mute gate
+insert into {notification_schema_sql}.notification_mutes (...)
+select ...
+where exists (select 1 from {comment_schema_sql}.comments where ...)
+```
+
+## Alembic migrations (different convention)
+
+Do **not** apply repository schema-qualification rules to `alembic/**/versions/*.py`.
+
+Each domain Alembic tree sets `search_path` to that domain's schema in `env.py`. Migration SQL uses **unqualified** table and type names (`posts`, `post_reports`, `create type post_status …`) — not `"post".posts`.
+
+**Exception — PL/pgSQL trigger / function bodies:** Runtime `search_path` for functions is not the migration session’s path, so audit trigger bodies may **hard-code** that domain’s schema qualifier (e.g. `"user".user_change_history`, `moderation.restriction_history`). That is required and accepted. Keep `[postgres_schemas]` values aligned with those literals; do not treat this as a B11 isolation violation.
+
+Cross-domain rules still apply to migrations:
+
+- No `REFERENCES` / FKs to tables in another domain's schema.
+- No DDL that reads or writes another domain's objects.
+
+Stay within the migration tree's domain; one schema per Alembic env.
+
+## Where cross-domain policy belongs
+
+**Application layer** (or domain service orchestration via dependencies, never cross-schema SQL):
+
+```python
+# ✅ application/posts/authenticated_service.py
+post = await post_deps.post_service.retrieve_post_with_metadata_by_id_if_exists(post_id=post_id)
+if post is None or post.status != PostStatus.ACTIVE:
+    return False
+return await moderation_deps.moderation_service.add_post_report(...)
+```
+
+Before adding a repository write that depends on another domain's row state:
+
+1. Can the owning domain gate it within its schema? → do that (likes, views, stats dirty).
+2. Otherwise → gate in `application/**/*_service.py` via the owning domain's service API.
+
+## Self-check (repositories only)
+
+In `domains/<name>/repository.py`:
+
+- Every table/type qualifier in SQL must use `{self.schema_sql}.…` (that domain's schema only).
+- Do not hard-code `"user".`, `"post".`, etc. — use `self.schema` / `self.schema_sql` from config.
+- Mirror lookup tables (`user_blocks_lookup`, etc.) still live under `{self.schema_sql}` when they belong to that domain's schema.

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

@@ -0,0 +1,35 @@
+---
+name: code-review
+description: Review code for quality, architecture compliance, and best practices. Use when the user asks for a code review, audit, or review.
+---
+
+# Code Review
+
+## Output format (required)
+
+**Actionable findings only:**
+
+- Bugs, wrong behavior, improvements, optimizations, doc/code contradictions, parallel implementation drift (sibling flows that diverge without documented reason).
+- Prioritize by severity with file context and fix direction.
+- **Do not** praise, summarize strengths, or pad with checklist pass narratives.
+- One-line scope is fine. If nothing is wrong, say so in one sentence.
+
+Do **not** flag documented accepted trade-offs in **`docs/platform/architecture-decisions.md`** unless the implementation violates them.
+
+## Workflow
+
+1. Read **`docs/platform/layers-and-boundaries.md`**, **`conventions.md`**, and **`architecture-decisions.md`** for the reviewed scope.
+1. Apply **scoped rules** (`.cursor/rules/*.mdc`) matching files under review — especially **`error-boundary`**, **`domain-imports`**, **`api-layer`**, **`application-layer`**, **`strong-reads`**.
+1. Report findings only — no filler.
+
+## Quick checks
+
+- Application services: no HTTP types, no domain exceptions, no Pydantic return types, one-line docstrings.
+- API: thin routers, validation in schemas, orchestration in application — **fastapi** skill (`.agents/skills/fastapi/`) + **`api-layer`** / **`api-validation`** / **`error-boundary`** rules.
+- Domain: imports only via **`__init__.py`** / **`dependencies`** from outer layers; no caller-context names (**`domain-caller-context`**).
+- Read-after-write refetches use **`*_strong`** where applicable.
+- **Python modernity (constitution):** prefer current 3.14 syntax in reviewed code — PEP 695 type params over module-level `TypeVar`/`ParamSpec`; no unnecessary `from __future__ import annotations`; builtins / `X | Y` over legacy `typing` aliases; `asyncio.TaskGroup` over `gather`.
+
+## Parallel drift
+
+Flag sibling modules with the same job but different structure (async layout, cleanup order, error/idempotency contracts) when docs do not explain the difference. Do **not** flag differences called out as intentional in design/flow docs or in **`docs/reviews/slices.md`** B7 **Do not flag** (for example root vs reply create-idempotency replay placement in **`docs/design/create-idempotency-design.md`**).

core_framework-3.3.0/.cursor/skills/sync-host-rules/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: sync-host-rules
+description: Sync core-framework rules, skills, and platform docs to consuming host applications. Use when the user asks to sync rules to a host, bump core-framework in a host, upgrade a host dependency, or port shared cursor/docs content.
+---
+
+# Sync Host Rules and Docs
+
+Consuming applications embed **core-framework** as a dependency.
+
+## Default (core-framework work)
+
+When changing **core-framework** code, migrations, tests, or **`docs/`**:
+
+- **Do not** edit host repos in the same task.
+- **Do not** port **`docs/platform/`**, **`docs/design/`**, **`docs/deployments/`**, **`.cursor/rules/`**, or **`.cursor/skills/`** to hosts proactively.
+- Mention that host sync is **deferred until the host bumps its core-framework version** (unless the user asked otherwise).
+
+## When host changes are allowed
+
+1. User explicitly scopes work to a host repo.
+1. User explicitly asks to sync or upgrade the core dependency in a host.
+1. You are editing a host repo directly — follow that repo's rules.
+
+## Sync procedure
+
+Diff by **basename** against the host's **`.cursor/`** and applicable **`docs/`** paths. Port shared content and **adapt**:
+
+- globs: **`core_framework/**`** → host source tree where applicable
+- imports: **`core_framework....`** → host package prefix
+- strong reads: **`strong-reads`** → host equivalent rule if present
+
+**Do not overwrite** host-only rules, skills, or product docs.
+
+### Transactional email (when the bumped core ships it)
+
+Remind the host (via upgrade notes / playbook, not code changes here):
+
+1. Put **`register_email_content`** in the **same** shared host bootstrap helper API and worker already call — worker is load-bearing.
+1. Register branded renderers **before** **`EMAIL_ENABLED=true`** (core default deletion copy is generic English).
+1. Do **not** **`enqueue_transactional_email`** for **`account_deletion_scheduled`** unless the host re-implements gated checks — use the core gated task.
+
+### `docs/deployments/guides/` layout
+
+Core walkthroughs live under **`docs/deployments/guides/setup/`** (one-time install) and **`docs/deployments/guides/playbook/`** (ops / incident runbooks) — not a flat **`guides/`** directory.
+
+When syncing **`docs/deployments/`** to a host:
+
+1. **Match the directory layout** — create **`guides/setup/`** and **`guides/playbook/`** on the host; move or rewrite files into those paths. Do **not** leave stale flat **`guides/*.md`** copies beside the new tree.
+1. **Basename alone is not enough** — a host may still have **`guides/ubuntu-server-setup.md`** while core has **`guides/setup/ubuntu-server-setup.md`**. Diff by relative path under **`docs/deployments/`**, then port.
+1. **Renames** — e.g. **`postgres-backup-ops.md`** → **`guides/playbook/postgres-backup-playbook.md`**. Delete the old host path after porting.
+1. **Adapt host paths** in playbooks (Compose project dir, image names, **`app_configs/<host>/`**) — keep Henry-specific notes in host **`deploy-playbook.md`** / **`release-playbook.md`**.
+
+## Docs boundaries
+
+**Core `docs/` must stay host-agnostic** — no references to specific consuming applications.
+
+| Core path                                                         | Host behavior                                                 |
+| ----------------------------------------------------------------- | ------------------------------------------------------------- |
+| **`docs/platform/`**, **`docs/design/`**, **`docs/deployments/`** | Sync on dependency upgrade or explicit sync request           |
+| **`docs/domains/`**, **`docs/library/`**                          | Canonical in core only — do not mirror product trees to hosts |

core_framework-3.3.0/.github/workflows/_deploy.yml

@@ -0,0 +1,238 @@
+name: Reusable Deployment
+
+on:
+  workflow_call:
+    inputs:
+      env_name:
+        type: string
+        required: true
+      dockerhub_username:
+        type: string
+        required: true
+      worker_replicas:
+        type: number
+        required: false
+        default: 1
+    secrets:
+      SECRET_KEY:
+        required: true
+      WRITE_POSTGRES_PASSWORD:
+        required: true
+      READ_POSTGRES_PASSWORD:
+        required: true
+      FIREBASE_CONFIG:
+        required: true
+      IMAGE_SERVER_SSH_PRIVATE_KEY:
+        required: true
+      IMAGE_SERVER_KNOWN_HOSTS:
+        required: true
+      DEPLOY_SERVER_SSH_KEY:
+        required: true
+      DOCKERHUB_TOKEN:
+        required: true
+
+permissions: {}
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment: ${{ inputs.env_name }}
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Render config.toml from template
+        env:
+          ENVIRONMENT: ${{ inputs.env_name }}
+          SECRET_KEY: ${{ secrets.SECRET_KEY }}
+          WRITE_POSTGRES_HOST: ${{ vars.WRITE_POSTGRES_HOST }}
+          WRITE_POSTGRES_PORT: ${{ vars.WRITE_POSTGRES_PORT }}
+          WRITE_POSTGRES_USER: ${{ vars.WRITE_POSTGRES_USER }}
+          WRITE_POSTGRES_PASSWORD: ${{ secrets.WRITE_POSTGRES_PASSWORD }}
+          WRITE_POSTGRES_DB: ${{ vars.WRITE_POSTGRES_DB }}
+          READ_POSTGRES_HOST: ${{ vars.READ_POSTGRES_HOST }}
+          READ_POSTGRES_PORT: ${{ vars.READ_POSTGRES_PORT }}
+          READ_POSTGRES_USER: ${{ vars.READ_POSTGRES_USER }}
+          READ_POSTGRES_PASSWORD: ${{ secrets.READ_POSTGRES_PASSWORD }}
+          READ_POSTGRES_DB: ${{ vars.READ_POSTGRES_DB }}
+          REDIS_HOST: ${{ vars.REDIS_HOST }}
+          REDIS_PORT: ${{ vars.REDIS_PORT }}
+          ALLOWED_HOSTS: ${{ vars.ALLOWED_HOSTS }}
+          APP_TITLE: ${{ vars.APP_TITLE }}
+          APP_DEBUG: ${{ vars.APP_DEBUG }}
+          OPENAPI_URL: ${{ vars.OPENAPI_URL }}
+          AVATAR_HOST_DOMAIN: ${{ vars.AVATAR_HOST_DOMAIN }}
+          AVATAR_DEFAULT_IMAGE: ${{ vars.AVATAR_DEFAULT_IMAGE }}
+          AVATAR_PUBLISH_ROOT: ${{ vars.AVATAR_PUBLISH_ROOT }}
+          BANNER_HOST_DOMAIN: ${{ vars.BANNER_HOST_DOMAIN }}
+          BANNER_DEFAULT_IMAGE: ${{ vars.BANNER_DEFAULT_IMAGE }}
+          BANNER_PUBLISH_ROOT: ${{ vars.BANNER_PUBLISH_ROOT }}
+          ATTACHMENT_HOST_DOMAIN: ${{ vars.ATTACHMENT_HOST_DOMAIN }}
+          ATTACHMENT_DEFAULT_IMAGE: ${{ vars.ATTACHMENT_DEFAULT_IMAGE }}
+          ATTACHMENT_PUBLISH_ROOT: ${{ vars.ATTACHMENT_PUBLISH_ROOT }}
+          IMAGE_SERVER_HOST: ${{ vars.IMAGE_SERVER_HOST }}
+          IMAGE_SERVER_PORT: ${{ vars.IMAGE_SERVER_PORT }}
+          IMAGE_SERVER_USER: ${{ vars.IMAGE_SERVER_USER }}
+          OBSERVABILITY_ENABLED: ${{ vars.OBSERVABILITY_ENABLED }}
+          OBSERVABILITY_OTLP_ENDPOINT: ${{ vars.OBSERVABILITY_OTLP_ENDPOINT }}
+          PROFILING_KEY: ${{ vars.PROFILING_KEY }}
+          PROFILING_ENABLED: ${{ vars.PROFILING_ENABLED }}
+          LOG_LEVEL: ${{ vars.LOG_LEVEL }}
+          CORS_ALLOWED_ORIGINS: ${{ vars.CORS_ALLOWED_ORIGINS }}
+          RETENTION_POST_VIEWS_DAYS: ${{ vars.RETENTION_POST_VIEWS_DAYS }}
+          RETENTION_READ_NOTIFICATIONS_DAYS: ${{ vars.RETENTION_READ_NOTIFICATIONS_DAYS }}
+          ANALYTICS_REFRESH_INTERVAL_SECONDS: ${{ vars.ANALYTICS_REFRESH_INTERVAL_SECONDS }}
+          EMAIL_ENABLED: ${{ vars.EMAIL_ENABLED }}
+          EMAIL_PROVIDER: ${{ vars.EMAIL_PROVIDER }}
+          EMAIL_API_KEY: ${{ secrets.EMAIL_API_KEY }}
+          EMAIL_FROM_ADDRESS: ${{ vars.EMAIL_FROM_ADDRESS }}
+          EMAIL_FROM_NAME: ${{ vars.EMAIL_FROM_NAME }}
+        run: |
+          set -euo pipefail
+
+          echo "Rendering config..."
+          envsubst < config.toml.template > config.toml
+          test -s config.toml
+          python3 - <<'PY'
+          import sys
+          import tomllib
+
+          try:
+              with open("config.toml", "rb") as f:
+                  tomllib.load(f)
+          except Exception as e:
+              print("ERROR: config.toml is invalid TOML", file=sys.stderr)
+              print(e, file=sys.stderr)
+              sys.exit(1)
+          PY
+
+      - name: Generate firebase_config.json from secret
+        env:
+          FIREBASE_CONFIG: ${{ secrets.FIREBASE_CONFIG }}
+        run: |
+          set -euo pipefail
+
+          echo "Generating firebase_config.json..."
+          echo "$FIREBASE_CONFIG" > firebase_config.json
+          test -s firebase_config.json
+          python3 - <<'PY'
+          import sys
+          import json
+
+          try:
+              with open("firebase_config.json", "r") as f:
+                  json.load(f)
+          except Exception as e:
+              print("ERROR: firebase_config.json is invalid JSON", file=sys.stderr)
+              print(e, file=sys.stderr)
+              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: Stage docker-compose.yml for upload
+        run: cp deploy/app/docker-compose.yml ./docker-compose.yml
+
+      - name: Upload rendered config.toml, firebase_config.json and docker-compose.yml
+        uses: appleboy/scp-action@ff85246acaad7bdce478db94a363cd2bf7c90345 # v1.0.0
+        with:
+          host: ${{ vars.DEPLOY_SERVER_HOST }}
+          username: ${{ vars.DEPLOY_SERVER_USER }}
+          key: ${{ secrets.DEPLOY_SERVER_SSH_KEY }}
+          port: ${{ vars.DEPLOY_SERVER_PORT }}
+          source: "config.toml,firebase_config.json,docker-compose.yml,image_server_ssh_key,image_server_known_hosts"
+          target: "/home/${{ vars.DEPLOY_SERVER_USER }}/app_configs/core-framework"
+
+      - name: Deploy to Server via SSH
+        uses: appleboy/ssh-action@0ff4204d59e8e51228ff73bce53f80d53301dee2 # v1.2.5
+        env:
+          DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
+          DOCKERHUB_USERNAME: ${{ inputs.dockerhub_username }}
+          DEPLOY_SERVER_USER: ${{ vars.DEPLOY_SERVER_USER }}
+          WORKER_REPLICAS: ${{ inputs.worker_replicas }}
+        with:
+          host: ${{ vars.DEPLOY_SERVER_HOST }}
+          username: ${{ vars.DEPLOY_SERVER_USER }}
+          key: ${{ secrets.DEPLOY_SERVER_SSH_KEY }}
+          port: ${{ vars.DEPLOY_SERVER_PORT }}
+          envs: DOCKERHUB_TOKEN,DOCKERHUB_USERNAME,DEPLOY_SERVER_USER,WORKER_REPLICAS
+          script: |
+            set -euo pipefail
+
+            echo "Logging in to Docker Hub"
+            printf '%s' "$DOCKERHUB_TOKEN" | docker login -u "$DOCKERHUB_USERNAME" --password-stdin
+
+            COMPOSE_FILE="/home/$DEPLOY_SERVER_USER/app_configs/core-framework/docker-compose.yml"
+            CONFIG_PATH="/home/$DEPLOY_SERVER_USER/app_configs/core-framework/config.toml"
+            FIREBASE_CONFIG_PATH="/home/$DEPLOY_SERVER_USER/app_configs/core-framework/firebase_config.json"
+            MEDIA_STAGING_PATH="/home/$DEPLOY_SERVER_USER/app_configs/core-framework/media-staging"
+            IMAGE_SERVER_SSH_KEY_PATH="/home/$DEPLOY_SERVER_USER/app_configs/core-framework/image_server_ssh_key"
+            IMAGE_SERVER_KNOWN_HOSTS_PATH="/home/$DEPLOY_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" \
+            MEDIA_STAGING_PATH="$MEDIA_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 media staging directory and image server SSH key permissions"
+            mkdir -p "$MEDIA_STAGING_PATH"
+            docker run --rm \
+              --user root \
+              -v "$MEDIA_STAGING_PATH:/app/media-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/media-staging && chown -R appuser:appgroup /app/media-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 \
+              -v "$CONFIG_PATH:/app/config.toml:ro" \
+              "$DOCKERHUB_USERNAME/core-framework:latest" \
+              cf-alembic
+
+            echo "Starting services with Docker Compose"
+            DOCKERHUB_USERNAME="$DOCKERHUB_USERNAME" \
+            CONFIG_PATH="$CONFIG_PATH" \
+            FIREBASE_CONFIG_PATH="$FIREBASE_CONFIG_PATH" \
+            MEDIA_STAGING_PATH="$MEDIA_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 \
+              --scale worker="$WORKER_REPLICAS"
+
+            echo "Cleaning up dangling Docker images"
+            docker image prune -f
+
+            echo "Deployment complete"