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

{core_framework-3.0.0 → core_framework-3.1.0}/.cursor/rules/constitution.mdc

@@ -16,7 +16,12 @@ alwaysApply: true
 
 - Python 3.14, Pydantic v2, PostgreSQL 18, orjson (not stdlib json).
 - Absolute imports only (`from core_framework....`). Comma-style `except A, B:` is intentional.
-- Prefer newer APIs (`asyncio.TaskGroup` over `gather`).
+- Prefer newer APIs and **current Python syntax** over older equivalents still legal on 3.14, for example:
+  - `asyncio.TaskGroup` over `asyncio.gather`
+  - PEP 695 type parameters (`def f[T](...)`, `def f[**P, R](...)`) over module-level `TypeVar` / `ParamSpec`
+  - Built-in generics (`list[str]`, `dict[str, int]`) over `typing.List` / `typing.Dict`
+  - `X | Y` over `Optional[X]` / `Union[X, Y]` unless a library API requires the old form
+  - Do **not** add `from __future__ import annotations` — 3.14 deferred annotations are the default (PEP 649)
 
 ## Layers
 

{core_framework-3.0.0 → core_framework-3.1.0}/.cursor/skills/code-review/SKILL.md

@@ -28,6 +28,7 @@ Do **not** flag documented accepted trade-offs in **`docs/platform/architecture-
 - 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
 

{core_framework-3.0.0 → core_framework-3.1.0}/.github/workflows/_deploy.yml

@@ -20,8 +20,6 @@ on:
         required: true
       READ_POSTGRES_PASSWORD:
         required: true
-      LOGFIRE_TOKEN:
-        required: true
       FIREBASE_CONFIG:
         required: true
       IMAGE_SERVER_SSH_PRIVATE_KEY:
@@ -79,13 +77,14 @@ jobs:
           IMAGE_SERVER_HOST: ${{ vars.IMAGE_SERVER_HOST }}
           IMAGE_SERVER_PORT: ${{ vars.IMAGE_SERVER_PORT }}
           IMAGE_SERVER_USER: ${{ vars.IMAGE_SERVER_USER }}
-          LOGFIRE_TOKEN: ${{ secrets.LOGFIRE_TOKEN }}
           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 }}
         run: |
           set -euo pipefail
@@ -150,6 +149,9 @@ jobs:
           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:

{core_framework-3.0.0 → core_framework-3.1.0}/.github/workflows/dev-ci-cd.yaml

@@ -133,7 +133,7 @@ jobs:
         uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
         with:
           context: .
-          file: ./dockerfile
+          file: ./deploy/app/dockerfile
           target: api
           push: true
           tags: ${{ steps.meta.outputs.tags }}
@@ -170,7 +170,7 @@ jobs:
         uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
         with:
           context: .
-          file: ./dockerfile
+          file: ./deploy/app/dockerfile
           target: worker
           push: true
           tags: ${{ steps.meta.outputs.tags }}
@@ -187,7 +187,6 @@ jobs:
       SECRET_KEY: ${{ secrets.SECRET_KEY }}
       WRITE_POSTGRES_PASSWORD: ${{ secrets.WRITE_POSTGRES_PASSWORD }}
       READ_POSTGRES_PASSWORD: ${{ secrets.READ_POSTGRES_PASSWORD }}
-      LOGFIRE_TOKEN: ${{ secrets.LOGFIRE_TOKEN }}
       FIREBASE_CONFIG: ${{ secrets.FIREBASE_CONFIG }}
       IMAGE_SERVER_SSH_PRIVATE_KEY: ${{ secrets.IMAGE_SERVER_SSH_PRIVATE_KEY }}
       IMAGE_SERVER_KNOWN_HOSTS: ${{ secrets.IMAGE_SERVER_KNOWN_HOSTS }}

{core_framework-3.0.0 → core_framework-3.1.0}/.github/workflows/manual-deployment.yaml

@@ -45,7 +45,6 @@ jobs:
       SECRET_KEY: ${{ secrets.SECRET_KEY }}
       WRITE_POSTGRES_PASSWORD: ${{ secrets.WRITE_POSTGRES_PASSWORD }}
       READ_POSTGRES_PASSWORD: ${{ secrets.READ_POSTGRES_PASSWORD }}
-      LOGFIRE_TOKEN: ${{ secrets.LOGFIRE_TOKEN }}
       FIREBASE_CONFIG: ${{ secrets.FIREBASE_CONFIG }}
       IMAGE_SERVER_SSH_PRIVATE_KEY: ${{ secrets.IMAGE_SERVER_SSH_PRIVATE_KEY }}
       IMAGE_SERVER_KNOWN_HOSTS: ${{ secrets.IMAGE_SERVER_KNOWN_HOSTS }}

core_framework-3.1.0/.github/workflows/manual-observability-deployment.yaml

@@ -0,0 +1,225 @@
+name: Manual Observability Deployment
+
+# Syncs deploy/observability/ to the LGTM host and runs docker compose up -d
+# --force-recreate --remove-orphans (so bind-mounted config changes reload).
+# Uses OBSERVABILITY_DEPLOY_* (not DEPLOY_SERVER_*) so the stack can move hosts later.
+# Optional PROMETHEUS_TARGETS_{NODE,POSTGRES,REDIS} (GitHub Environment vars) are
+# written to targets/*/hosts.yml at stage time — host inventory stays out of the repo.
+
+on:
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: "Target environment (development or production)"
+        required: true
+        type: choice
+        options:
+          - development
+          - production
+      confirm:
+        description: "Type the environment name to confirm (development or production)"
+        required: true
+
+permissions: {}
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    permissions: {}
+    steps:
+      - name: Validate confirmation
+        env:
+          CONFIRM: ${{ inputs.confirm }}
+          ENVIRONMENT: ${{ inputs.environment }}
+        run: |
+          if [ "$CONFIRM" != "$ENVIRONMENT" ]; then
+            echo "Deployment cancelled: confirmation mismatch."
+            echo "Expected: '$ENVIRONMENT', got: '$CONFIRM'"
+            exit 1
+          fi
+
+  deploy:
+    needs: validate
+    runs-on: ubuntu-latest
+    environment: ${{ inputs.environment }}
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      # Stage as staging/observability (not deploy/observability). Upload uses
+      # strip_components: 1 so remote is .../app_configs/observability.
+      # Host scrape inventory comes from GitHub Environment vars (not the repo).
+      - name: Stage observability stack for upload
+        env:
+          PROMETHEUS_TARGETS_NODE: ${{ vars.PROMETHEUS_TARGETS_NODE }}
+          PROMETHEUS_TARGETS_POSTGRES: ${{ vars.PROMETHEUS_TARGETS_POSTGRES }}
+          PROMETHEUS_TARGETS_REDIS: ${{ vars.PROMETHEUS_TARGETS_REDIS }}
+        run: |
+          set -euo pipefail
+          mkdir -p staging/observability
+          cp -a deploy/observability/. staging/observability/
+          rm -f staging/observability/.env
+          rm -rf staging/observability/targets.example
+          mkdir -p \
+            staging/observability/targets/node \
+            staging/observability/targets/postgres \
+            staging/observability/targets/redis
+          rm -f staging/observability/targets/*/.gitkeep
+          python3 -m pip install --user -q pyyaml
+          python3 <<'PY'
+          import os
+          import sys
+          from pathlib import Path
+
+          import yaml
+
+          def write_targets(dest, body, var_name):
+              text = body or ""
+              stripped = text.strip()
+              path = Path(dest)
+              if not stripped:
+                  path.write_text("[]\n", encoding="utf-8")
+                  print(f"{var_name}: empty → []")
+                  return
+              try:
+                  data = yaml.safe_load(text)
+              except yaml.YAMLError as exc:
+                  print(f"ERROR: {var_name} is not valid YAML: {exc}", file=sys.stderr)
+                  sys.exit(1)
+              if data is None:
+                  # Comment-only or empty document
+                  path.write_text("[]\n", encoding="utf-8")
+                  print(f"{var_name}: comment-only/null → []")
+                  return
+              if not isinstance(data, list):
+                  print(
+                      f"ERROR: {var_name} must be a YAML list of file_sd target groups, "
+                      f"got {type(data).__name__}",
+                      file=sys.stderr,
+                  )
+                  sys.exit(1)
+              out = text if text.endswith("\n") else text + "\n"
+              path.write_text(out, encoding="utf-8")
+              print(f"{var_name}: wrote {len(data)} target group(s) → {dest}")
+
+          write_targets(
+              "staging/observability/targets/node/hosts.yml",
+              os.environ.get("PROMETHEUS_TARGETS_NODE", ""),
+              "PROMETHEUS_TARGETS_NODE",
+          )
+          write_targets(
+              "staging/observability/targets/postgres/hosts.yml",
+              os.environ.get("PROMETHEUS_TARGETS_POSTGRES", ""),
+              "PROMETHEUS_TARGETS_POSTGRES",
+          )
+          write_targets(
+              "staging/observability/targets/redis/hosts.yml",
+              os.environ.get("PROMETHEUS_TARGETS_REDIS", ""),
+              "PROMETHEUS_TARGETS_REDIS",
+          )
+          PY
+
+      - name: Ensure remote app_configs directory
+        uses: appleboy/ssh-action@0ff4204d59e8e51228ff73bce53f80d53301dee2 # v1.2.5
+        env:
+          OBSERVABILITY_DEPLOY_USER: ${{ vars.OBSERVABILITY_DEPLOY_USER }}
+        with:
+          host: ${{ vars.OBSERVABILITY_DEPLOY_HOST }}
+          username: ${{ vars.OBSERVABILITY_DEPLOY_USER }}
+          key: ${{ secrets.OBSERVABILITY_DEPLOY_SSH_KEY }}
+          port: ${{ vars.OBSERVABILITY_DEPLOY_PORT }}
+          envs: OBSERVABILITY_DEPLOY_USER
+          script: |
+            set -euo pipefail
+            mkdir -p "/home/$OBSERVABILITY_DEPLOY_USER/app_configs"
+
+      # Drop any leftover file_sd YAML under targets/ before upload (SCP overwrite
+      # does not delete extras; Prometheus scrapes targets/*/*.yml).
+      - name: Reset remote Prometheus targets directory
+        uses: appleboy/ssh-action@0ff4204d59e8e51228ff73bce53f80d53301dee2 # v1.2.5
+        env:
+          OBSERVABILITY_DEPLOY_USER: ${{ vars.OBSERVABILITY_DEPLOY_USER }}
+        with:
+          host: ${{ vars.OBSERVABILITY_DEPLOY_HOST }}
+          username: ${{ vars.OBSERVABILITY_DEPLOY_USER }}
+          key: ${{ secrets.OBSERVABILITY_DEPLOY_SSH_KEY }}
+          port: ${{ vars.OBSERVABILITY_DEPLOY_PORT }}
+          envs: OBSERVABILITY_DEPLOY_USER
+          script: |
+            set -euo pipefail
+            STACK_DIR="/home/$OBSERVABILITY_DEPLOY_USER/app_configs/observability"
+            mkdir -p "$STACK_DIR"
+            rm -rf "$STACK_DIR/targets"
+            mkdir -p \
+              "$STACK_DIR/targets/node" \
+              "$STACK_DIR/targets/postgres" \
+              "$STACK_DIR/targets/redis"
+
+      - name: Upload observability stack
+        uses: appleboy/scp-action@ff85246acaad7bdce478db94a363cd2bf7c90345 # v1.0.0
+        with:
+          host: ${{ vars.OBSERVABILITY_DEPLOY_HOST }}
+          username: ${{ vars.OBSERVABILITY_DEPLOY_USER }}
+          key: ${{ secrets.OBSERVABILITY_DEPLOY_SSH_KEY }}
+          port: ${{ vars.OBSERVABILITY_DEPLOY_PORT }}
+          # Stage path is staging/observability; strip "staging/" so remote is
+          # .../app_configs/observability (not .../app_configs/staging/observability).
+          source: "staging/observability"
+          target: "/home/${{ vars.OBSERVABILITY_DEPLOY_USER }}/app_configs"
+          strip_components: 1
+          overwrite: true
+
+      - name: Compose up on observability host
+        uses: appleboy/ssh-action@0ff4204d59e8e51228ff73bce53f80d53301dee2 # v1.2.5
+        env:
+          OBSERVABILITY_DEPLOY_USER: ${{ vars.OBSERVABILITY_DEPLOY_USER }}
+          GRAFANA_ADMIN_USER: ${{ vars.GRAFANA_ADMIN_USER }}
+          GRAFANA_ADMIN_PASSWORD: ${{ secrets.GRAFANA_ADMIN_PASSWORD }}
+          GRAFANA_ROOT_URL: ${{ vars.GRAFANA_ROOT_URL }}
+        with:
+          host: ${{ vars.OBSERVABILITY_DEPLOY_HOST }}
+          username: ${{ vars.OBSERVABILITY_DEPLOY_USER }}
+          key: ${{ secrets.OBSERVABILITY_DEPLOY_SSH_KEY }}
+          port: ${{ vars.OBSERVABILITY_DEPLOY_PORT }}
+          envs: OBSERVABILITY_DEPLOY_USER,GRAFANA_ADMIN_USER,GRAFANA_ADMIN_PASSWORD,GRAFANA_ROOT_URL
+          script: |
+            set -euo pipefail
+
+            STACK_DIR="/home/$OBSERVABILITY_DEPLOY_USER/app_configs/observability"
+            test -d "$STACK_DIR"
+            cd "$STACK_DIR"
+
+            # Never overwrite an existing host .env (password / local tweaks).
+            if [ ! -f .env ]; then
+              if [ -z "${GRAFANA_ADMIN_PASSWORD:-}" ]; then
+                echo "ERROR: $STACK_DIR/.env is missing and GRAFANA_ADMIN_PASSWORD is not set."
+                echo "Add the secret in the GitHub environment, then re-run this workflow."
+                exit 1
+              fi
+              ADMIN_USER="${GRAFANA_ADMIN_USER:-admin}"
+              # GRAFANA_ROOT_URL optional: set for observability.{ZONE} (Caddy);
+              # leave empty for SSH-tunnel-only access.
+              umask 077
+              printf '%s\n' \
+                "GRAFANA_ADMIN_USER=${ADMIN_USER}" \
+                "GRAFANA_ADMIN_PASSWORD=${GRAFANA_ADMIN_PASSWORD}" \
+                "GRAFANA_ROOT_URL=${GRAFANA_ROOT_URL:-}" \
+                > .env
+              if [ -z "${GRAFANA_ROOT_URL:-}" ]; then
+                echo "Created .env (first install); GRAFANA_ROOT_URL empty (SSH-tunnel fallback)"
+              else
+                echo "Created .env (first install); GRAFANA_ROOT_URL=${GRAFANA_ROOT_URL}"
+              fi
+            else
+              echo "Keeping existing .env"
+            fi
+
+            docker compose pull
+            docker compose up -d --force-recreate --remove-orphans
+            docker compose ps
+
+            echo "Observability stack deployment complete"

{core_framework-3.0.0 → core_framework-3.1.0}/.github/workflows/test.yaml

@@ -35,7 +35,12 @@ jobs:
         run: uv sync --locked --all-extras --dev
 
       - name: ruff
-        run: uv run ruff check
+        run: |
+          uv run ruff check
+          uv run ruff format --check
+
+      - name: ty
+        run: uv run ty check
 
       - name: Install Firebase CLI
         working-directory: .github/ci
@@ -43,11 +48,23 @@ jobs:
 
       - name: pytest
         run: |
+          set -euo pipefail
           export PATH="$PWD/.github/ci/node_modules/.bin:$PATH"
           firebase --version
-          uv run pytest tests/unit tests/integration -n 2
-        env:
-          FIREBASE_AUTH_EMULATOR_HOST: 127.0.0.1:9099
+          echo "Starting Firebase Auth emulator..."
+          firebase emulators:start --only auth --project=test > /dev/null 2>&1 &
+          EMULATOR_PID=$!
+          # Mirror makefile warm-up; the testing plugin also waits for Identity Toolkit HTTP readiness.
+          sleep 3
+          echo "Running unit and integration tests with emulator..."
+          set +e
+          FIREBASE_AUTH_EMULATOR_HOST=127.0.0.1:9099 uv run pytest tests/unit tests/integration -n 2
+          TEST_EXIT=$?
+          set -e
+          echo "Stopping emulator..."
+          kill "$EMULATOR_PID" 2>/dev/null || true
+          wait "$EMULATOR_PID" 2>/dev/null || true
+          exit "$TEST_EXIT"
 
   package-smoke:
     runs-on: ubuntu-latest
@@ -155,7 +172,7 @@ jobs:
         uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
         with:
           context: .
-          file: ./dockerfile
+          file: ./deploy/app/dockerfile
           target: api
           push: false
           tags: core-framework:ci
@@ -164,7 +181,7 @@ jobs:
         uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
         with:
           context: .
-          file: ./dockerfile
+          file: ./deploy/app/dockerfile
           target: worker
           push: false
           tags: core-framework-worker:ci

{core_framework-3.0.0 → core_framework-3.1.0}/.gitignore

@@ -33,3 +33,6 @@ image_server_ssh_key
 # Cursor debug
 firebase-debug.log
 ui-debug.log
+
+# Tach
+tach_module_graph.dot

{core_framework-3.0.0 → core_framework-3.1.0}/.pre-commit-config.yaml

@@ -19,18 +19,6 @@ repos:
       args: ['--maxkb=750']
       exclude: ^uv.lock$
 
-- repo: https://github.com/asottile/pyupgrade
-  rev: v3.21.2
-  hooks:
-    - id: pyupgrade
-      args: [--py314-plus]
-      name: Upgrade code to Python 3.14+
-
-- repo: https://github.com/asottile/yesqa
-  rev: v1.5.0
-  hooks:
-    - id: yesqa
-
 - repo: https://github.com/astral-sh/uv-pre-commit
   rev: 0.11.24
   hooks:
@@ -43,17 +31,20 @@ repos:
       entry: uv run --frozen ruff check --fix
       language: system
       types_or: [python, pyi]
+
     - id: ruff-format
       name: ruff format
       entry: uv run --frozen ruff format
       language: system
       types_or: [python, pyi]
+
     - id: ty
       name: ty check
       entry: uv run --frozen ty check
       language: system
       types_or: [python, pyi]
       pass_filenames: false
+
     - id: zizmor
       name: zizmor
       entry: uv run --frozen zizmor .github/workflows

{core_framework-3.0.0 → core_framework-3.1.0}/CHANGELOG.md

@@ -4,6 +4,62 @@ Notable changes to **core-framework** (import **`core_framework`**). Format foll
 
 ## [Unreleased]
 
+## [3.1.0] - 2026-07-16
+
+### Fixed
+
+- **HTTP request correlation on failures/aborts:** `ContextMiddleware` always emits **`HTTP request completed`** (with **`aborted=true`** / null **`status_code`** when no response starts), always attaches **`X-Request-ID`** (including missing-client 400s), stores **`request_id`** on ASGI scope state for 500 handlers, and stays outermost over profiling so profile HTML keeps the header.
+- **Structlog logger caching:** `setup_logging` keeps `cache_logger_on_first_use=False` so the OTel reconfigure can attach; `configure_observability_providers` (OTLP or kill-switch-off) finalizes with `True`.
+- **Observability polish:** Direct ARQ enqueue propagates **`request_id`** (worker ContextVar + span attribute) so Loki filters match media/variant jobs, not only outbox handlers. ARQ job timeouts/`CancelledError` mark the consumer span ERROR (metrics already set `error.type`). **`shutdown_observability`** uninstruments FastAPI/httpx/asyncpg/Redis before shutting providers. Shared **`PROBE_PATHS`** for health/readiness. **`otlp_endpoint`** requires an **`http(s)://`** base URL (stored stripped) and rejects signal paths (`.../v1/traces` etc.). FastAPI probe **`excluded_urls`** match host + exact path (`://[^/]+/health$`). Collector Compose healthcheck removed (distroless image; Grafana depends on start-order). Tempo→Loki **`tracesToLogsV2`** maps **`service.name`** / **`deployment.environment.name`**. Provisioned dashboards set **`allowUiUpdates: false`** and **`editable: false`**.
+- **Observability review pass:** Structlog OTLP processor skips export when instrumentation is disabled (exporter failure feedback loop guard); trims duplicate **`level`**/**`timestamp`** and native **`trace_id`**/**`span_id`** attributes; truncates large **`exception`** strings. FastAPI instrumentation uses **`exclude_spans=["receive","send"]`**. Sampler uses **`get_value`** for suppress-instrumentation keys. OTLP headers parsed via **`parse_env_headers`**. Worker metrics include **`messaging.system=arq`** and **`error.type`** on generic exceptions. **`shutdown_observability`** isolates per-provider failures and clears the job duration histogram; API and worker shut it down via **`asyncio.to_thread`**. ARQ job metrics skip recording after the kill switch flips. Outbox origin metadata reuses **`capture_request_id_for_job`**. Compose **`mem_limit`** / **`GOMEMLIMIT`** on Tempo, Loki, Prometheus, and Grafana.
+
+### Added
+
+- **Manual Observability Deployment:** GitHub Actions **`manual-observability-deployment.yaml`** syncs **`deploy/observability/`** and runs Compose on the LGTM host. Uses separate **`OBSERVABILITY_DEPLOY_*`** / **`GRAFANA_ADMIN_PASSWORD`** / optional **`GRAFANA_ROOT_URL`** (not app **`DEPLOY_SERVER_*`**). First run seeds host **`.env`**; later runs keep it.
+
+- **Grafana hostname:** Preferred UI access is **`observability.{ZONE}`** via Caddy ([`Caddyfile.observability.example`](docs/deployments/examples/Caddyfile.observability.example)) + Cloudflare DNS + WAF IP allowlist. OTLP stays private. Compose sets **`GF_SERVER_ROOT_URL`** from **`GRAFANA_ROOT_URL`**.
+
+- **LGTM image bumps:** Collector **0.156.0**, Tempo **3.0.2** (monolithic config: drop `ingester`/`compactor`; retention via `backend_worker.compaction.block_retention`), Loki **3.7.3**, Prometheus **v3.13.0**, Grafana **13.1.0**.
+
+- **API request correlation:** Non-probe responses include **`X-Request-ID`** (also exposed for CORS). **`ContextMiddleware`** sets `request_id` on the current HTTP SERVER span after generating the ULID; emits a structured **`HTTP request completed`** log so quiet successes remain searchable in Loki → Tempo. Uvicorn **`--no-access-log`** is unchanged.
+
+- **HTTP metrics semconv:** When OTLP is enabled, core sets **`OTEL_SEMCONV_STABILITY_OPT_IN=http`** (unless already set) before FastAPI/ASGI instrumentation so Prometheus series match **`api-http`** (`http_server_request_duration_seconds_*`).
+
+- **Loki storage paths:** **`deploy/observability/loki.yaml`** uses **`path_prefix: /loki`** with explicit TSDB index/cache and WAL dirs under **`/loki`**, matching the Compose **`loki-data:/loki`** volume (avoids writing outside the mount).
+
+- **Dashboard env filter:** API/worker dashboards include a **`deployment.environment.name`** variable (Prometheus label **`deployment_environment_name`**).
+
+- **Worker telemetry coverage:** **`instrument_arq_jobs`** wraps core **`functions`** and **`cron_jobs`** at registration; timeouts/cancellations set **`error.type=CancelledError`**; hosts must wrap custom jobs the same way.
+
+- **LGTM ops hardening:** Collector **`memory_limiter`** + Compose **`mem_limit`/`GOMEMLIMIT`**; Prometheus **8GB** size retention; Loki ingestion caps; Loki **`3.6.12`** native **`-health`** (distroless-safe); Tempo and Collector start-order only (distroless — no in-container wget healthcheck); Grafana waits on Loki/Prometheus healthy + Collector/Tempo started; optional exporter scrape jobs commented by default; Grafana password required; Grafana UI via **`observability.{ZONE}`** (Caddy + WAF allowlist) or SSH tunnel; Tempo datasource omits **`nodeGraph`** (metrics_generator off); docs clarify Loki/Tempo are time-retention only (no size quota).
+
+- **Observability lifecycle / naming:** **`shutdown_observability`** is process-end only (OTLP globals cannot be unset); clears kill-switch flags; structlog OTel processor no-ops when the kill switch is off; ARQ job span/metric names use ARQ **`Function.name`/`CronJob.name`**; HTTP **`request_id`** via **`ContextMiddleware`** on the SERVER span; **`HTTP request completed`** covers full response duration (structlog OTel processor injects **`trace_id`** for Loki → Tempo); shared-runtime worker docs note API **`service.name`**.
+
+- **Same-host exporter scrapes:** Setup guides allow Docker bridge (**`172.16.0.0/12`**) to node/Postgres/Redis exporter ports so Compose Prometheus (`host.docker.internal`) is not blocked by UFW rules that only permit **`{ADMIN_IP}`**.
+
+### Changed
+
+- **Dashboard uid prefix:** Renamed Grafana dashboards **`cf-api-http`** → **`api-http`** and **`cf-worker-jobs`** → **`worker-jobs`** (files and uids). Existing Grafana bookmarks / `/d/cf-*` links need updating after re-provision.
+
+### Removed
+
+- **Exporter Grafana dashboards:** Dropped **`cf-host.json`**, **`cf-postgres.json`**, and **`cf-redis.json`**. v1 provisioned dashboards are app/worker OTLP only (API HTTP, Worker jobs). Optional Prometheus scrape jobs for node/Postgres/Redis exporters remain commented in **`prometheus.yml`**.
+- **Runtime dashboard shells:** Dropped deferred **`cf-api-runtime.json`** and **`cf-worker-runtime.json`** (no in-app process metrics in v1).
+
+### Breaking
+
+- **Breaking (hosts — observability):** Replace Logfire with OpenTelemetry OTLP on the API and worker. Remove **`logfire`** / **`LOGFIRE_TOKEN`** / **`observability.logfire_token`**. Add **`observability.otlp_endpoint`** (required when enabled outside **`local`**) and **`observability.otlp_headers`** (TOML; deploy template hardcodes empty). Deploy variables **`OBSERVABILITY_OTLP_ENDPOINT`** (and existing **`OBSERVABILITY_ENABLED`**). Pins: **`opentelemetry-api`/`sdk`/`exporter-otlp-proto-http` ≥1.43.0,\<1.44**, instrumentation + **`opentelemetry-semantic-conventions` ≥0.64b0,\<0.65** (FastAPI OPTIONS / `_IncludedRouter` fix). Resource attribute **`deployment.environment.name`** (not deprecated **`deployment.environment`**). ARQ spans use **`messaging.operation.type=process`**, **`messaging.destination.name=<queue>`**, **`messaging.operation.name=<job>`**. Direct ARQ enqueue propagates W3C context; outbox jobs keep a separate consumer span linked to the originating request via persisted **`event_outbox.metadata`** (**`request_id`**, W3C carrier) plus outbox span attributes (`outbox_id`, `idempotency_key`, …). No in-process **`SystemMetricsInstrumentor`**; v1 ships no host/Postgres/Redis or process-runtime Grafana dashboards (optional exporter scrapes stay commented in **`prometheus.yml`**).
+
+- **Breaking (API):** **`POST /posts`**, **`POST /comments`**, and **`POST /comments/{comment_id}/replies`** return **`201`** with **`{ "id": "<ulid>" }`** (first success and idempotency replay return the same id). Previously these returned an empty body. See **`docs/domains/posts/create_post.md`**, **`docs/domains/comments/create_comment.md`**, and **`docs/design/create-idempotency-design.md`**.
+
+- **Breaking (hosts — config):** Add **`retention.read_notifications_retention_days`** under **`[retention]`** (default **90**). Deploy variable **`RETENTION_READ_NOTIFICATIONS_DAYS`**. The worker runs **`schedule_prune_read_notifications`** (daily **05:05 UTC**) to delete read notifications past that window; unread rows are never pruned. See **`docs/library/workers.md`** and **`docs/domains/notifications/notification_inbox.md`**.
+
+### Migration
+
+- **Observability (Logfire → OTLP):** Drop **`LOGFIRE_TOKEN`** / **`observability.logfire_token`**. Add **`observability.otlp_endpoint`** (and optional **`otlp_headers`**) under **`[observability]`**; set **`OBSERVABILITY_OTLP_ENDPOINT`** when **`OBSERVABILITY_ENABLED=true`** outside **`local`**. See **`docs/library/package-api.md`** (Host upgrade — observability OTLP) and **`docs/deployments/guides/setup/observability-lgtm-setup.md`**.
+
+- **`notification` schema:** Run **`cf-alembic`** so the stream applies **`2fdd68777706`** (`idx_notifications_read_at_retention` on **`read_at`** where not null) before relying on age-based read-notification pruning at scale.
+
 ## [3.0.0] - 2026-07-11
 
 ### Breaking
@@ -515,4 +571,5 @@ First **SemVer-stable** release per **`docs/library/package-api.md`**.
 [2.3.2]: https://github.com/NepNepFFXIV/core-framework/compare/v2.3.1...v2.3.2
 [2.3.3]: https://github.com/NepNepFFXIV/core-framework/compare/v2.3.2...v2.3.3
 [3.0.0]: https://github.com/NepNepFFXIV/core-framework/compare/v2.3.3...v3.0.0
-[unreleased]: https://github.com/NepNepFFXIV/core-framework/compare/v3.0.0...HEAD
+[3.1.0]: https://github.com/NepNepFFXIV/core-framework/compare/v3.0.0...v3.1.0
+[unreleased]: https://github.com/NepNepFFXIV/core-framework/compare/v3.1.0...HEAD

{core_framework-3.0.0 → core_framework-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: core-framework
-Version: 3.0.0
+Version: 3.1.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
@@ -20,8 +20,15 @@ Requires-Dist: fastapi[standard]>=0.139.0
 Requires-Dist: firebase-admin>=7.5.0
 Requires-Dist: httpx[http2]>=0.28.1
 Requires-Dist: itsdangerous>=2.2.0
-Requires-Dist: logfire[asyncpg,fastapi,httpx,redis]>=4.37.0
 Requires-Dist: mashumaro[orjson]>=3.22
+Requires-Dist: opentelemetry-api<1.44,>=1.43.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-http<1.44,>=1.43.0
+Requires-Dist: opentelemetry-instrumentation-asyncpg<0.65,>=0.64b0
+Requires-Dist: opentelemetry-instrumentation-fastapi<0.65,>=0.64b0
+Requires-Dist: opentelemetry-instrumentation-httpx<0.65,>=0.64b0
+Requires-Dist: opentelemetry-instrumentation-redis<0.65,>=0.64b0
+Requires-Dist: opentelemetry-sdk<1.44,>=1.43.0
+Requires-Dist: opentelemetry-semantic-conventions<0.65,>=0.64b0
 Requires-Dist: orjson>=3.11.9
 Requires-Dist: pillow-heif>=1.4.0
 Requires-Dist: pillow>=12.3.0
@@ -40,18 +47,30 @@ Description-Content-Type: text/markdown
 
 Install from PyPI as **`core-framework`**, import **`core_framework`**. MIT — [LICENSE](LICENSE). [Repository](https://github.com/NepNepFFXIV/core-framework), [PyPI](https://pypi.org/project/core-framework/).
 
+## Documentation
+
+| Doc                                                        | Purpose                                                   |
+| ---------------------------------------------------------- | --------------------------------------------------------- |
+| [docs/README.md](docs/README.md)                           | Doc map (platform, design, library, domains, deployments) |
+| [docs/library/package-api.md](docs/library/package-api.md) | Host import surface and upgrade tables                    |
+| [CHANGELOG.md](CHANGELOG.md)                               | Release notes (SemVer)                                    |
+
 ## Install
 
 ```bash
 uv add core-framework
 ```
 
+Pin hosts to a locked version. On each bump, read **[CHANGELOG.md](CHANGELOG.md)** and the host-upgrade tables in **[package-api.md](docs/library/package-api.md)**.
+
 ## Local development
 
 Use **Python 3.14**. Install **uv** and **Docker**.
 
+Tracked **`config.toml`** at the repo root is the local-dev settings file (dummy values; no production secrets). Production renders from **`config.toml.template`** via deploy **`envsubst`** — see [architecture decisions](docs/platform/architecture-decisions.md).
+
 ```bash
-docker compose -f docker-compose.dev.yaml up -d
+docker compose -f deploy/app/docker-compose.dev.yaml up -d
 uv sync --locked --all-extras --dev
 uv run cf-alembic
 make run
@@ -59,7 +78,7 @@ make run
 
 **Firebase:** copy **`firebase_config.example.json`** to **`firebase_config.json`** at the repo root and replace with your Firebase project’s **service account** JSON from the console.
 
-For **`make test`**, use the Firebase CLI (Auth emulator). Stop DB/Redis: **`docker compose -f docker-compose.dev.yaml down`**.
+For **`make test`**, use the Firebase CLI (Auth emulator). Stop DB/Redis: **`docker compose -f deploy/app/docker-compose.dev.yaml down`**.
 
 **Pre-commit:** `uv sync --dev` installs **pre-commit**. Enable hooks with **`uv run pre-commit install`** (ruff, mdformat, uv-lock, and other checks in **`.pre-commit-config.yaml`**).
 
@@ -92,6 +111,10 @@ def build_app(settings: HostSettings | None = None) -> FastAPI:
 
 From the host repository root, run **`uv run cf-alembic`**. See [core-framework-migration](docs/library/core-framework-migration.md).
 
+**Worker:** production also runs the ARQ worker (`arq core_framework.worker.main.WorkerSettings`, or a host composition that calls the same startup path). Schedules and tasks: [workers.md](docs/library/workers.md). Composition details: [package-api.md](docs/library/package-api.md) (Default deployment entrypoints).
+
+**Observability:** OpenTelemetry OTLP (not Logfire). Under **`[observability]`**, set **`enabled`** and **`otlp_endpoint`** (required when enabled outside **`local`**); drop **`logfire_token`** / **`LOGFIRE_TOKEN`**. Same-host Grafana LGTM stack: **`deploy/observability/`** and [observability-lgtm-setup.md](docs/deployments/guides/setup/observability-lgtm-setup.md). Host upgrade table: [package-api.md — observability OTLP](docs/library/package-api.md).
+
 ## Host pytest
 
 In your host repository, add the **`core-framework[testing]`** extra to dev or test dependencies. In **`tests/conftest.py`**, register **`pytest_core_framework_config`** (returns **`TestConfig`**) and a session-scoped **`anyio_backend`** fixture that returns **`"asyncio"`**.

{core_framework-3.0.0 → core_framework-3.1.0}/README.md

@@ -2,18 +2,30 @@
 
 Install from PyPI as **`core-framework`**, import **`core_framework`**. MIT — [LICENSE](LICENSE). [Repository](https://github.com/NepNepFFXIV/core-framework), [PyPI](https://pypi.org/project/core-framework/).
 
+## Documentation
+
+| Doc                                                        | Purpose                                                   |
+| ---------------------------------------------------------- | --------------------------------------------------------- |
+| [docs/README.md](docs/README.md)                           | Doc map (platform, design, library, domains, deployments) |
+| [docs/library/package-api.md](docs/library/package-api.md) | Host import surface and upgrade tables                    |
+| [CHANGELOG.md](CHANGELOG.md)                               | Release notes (SemVer)                                    |
+
 ## Install
 
 ```bash
 uv add core-framework
 ```
 
+Pin hosts to a locked version. On each bump, read **[CHANGELOG.md](CHANGELOG.md)** and the host-upgrade tables in **[package-api.md](docs/library/package-api.md)**.
+
 ## Local development
 
 Use **Python 3.14**. Install **uv** and **Docker**.
 
+Tracked **`config.toml`** at the repo root is the local-dev settings file (dummy values; no production secrets). Production renders from **`config.toml.template`** via deploy **`envsubst`** — see [architecture decisions](docs/platform/architecture-decisions.md).
+
 ```bash
-docker compose -f docker-compose.dev.yaml up -d
+docker compose -f deploy/app/docker-compose.dev.yaml up -d
 uv sync --locked --all-extras --dev
 uv run cf-alembic
 make run
@@ -21,7 +33,7 @@ make run
 
 **Firebase:** copy **`firebase_config.example.json`** to **`firebase_config.json`** at the repo root and replace with your Firebase project’s **service account** JSON from the console.
 
-For **`make test`**, use the Firebase CLI (Auth emulator). Stop DB/Redis: **`docker compose -f docker-compose.dev.yaml down`**.
+For **`make test`**, use the Firebase CLI (Auth emulator). Stop DB/Redis: **`docker compose -f deploy/app/docker-compose.dev.yaml down`**.
 
 **Pre-commit:** `uv sync --dev` installs **pre-commit**. Enable hooks with **`uv run pre-commit install`** (ruff, mdformat, uv-lock, and other checks in **`.pre-commit-config.yaml`**).
 
@@ -54,6 +66,10 @@ def build_app(settings: HostSettings | None = None) -> FastAPI:
 
 From the host repository root, run **`uv run cf-alembic`**. See [core-framework-migration](docs/library/core-framework-migration.md).
 
+**Worker:** production also runs the ARQ worker (`arq core_framework.worker.main.WorkerSettings`, or a host composition that calls the same startup path). Schedules and tasks: [workers.md](docs/library/workers.md). Composition details: [package-api.md](docs/library/package-api.md) (Default deployment entrypoints).
+
+**Observability:** OpenTelemetry OTLP (not Logfire). Under **`[observability]`**, set **`enabled`** and **`otlp_endpoint`** (required when enabled outside **`local`**); drop **`logfire_token`** / **`LOGFIRE_TOKEN`**. Same-host Grafana LGTM stack: **`deploy/observability/`** and [observability-lgtm-setup.md](docs/deployments/guides/setup/observability-lgtm-setup.md). Host upgrade table: [package-api.md — observability OTLP](docs/library/package-api.md).
+
 ## Host pytest
 
 In your host repository, add the **`core-framework[testing]`** extra to dev or test dependencies. In **`tests/conftest.py`**, register **`pytest_core_framework_config`** (returns **`TestConfig`**) and a session-scoped **`anyio_backend`** fixture that returns **`"asyncio"`**.