core-framework 2.3.2__tar.gz → 2.3.3__tar.gz

{core_framework-2.3.2 → core_framework-2.3.3}/CHANGELOG.md

@@ -4,6 +4,33 @@ Notable changes to **core-framework** (import **`core_framework`**). Format foll
 
 ## [Unreleased]
 
+## [2.3.3] - 2026-07-05
+
+### Added
+
+- **UTM capture `kind`:** `POST /events` with `type: "utm_data"` requires a `kind`
+  item in `events[]` (`subject_type` `kind`, `subject` the capture context). Core
+  ships `registration`; hosts register additional kinds via
+  `register_utm_capture_kind`. See **`docs/design/utm-events-design.md`** and
+  **`docs/domains/events/events.md`**.
+
+### Changed
+
+- **`analytics` schema:** **`2d61a5e88d76_analytics_utm_events_add_kind`** — `utm_events.kind`
+  column and `idx_utm_events_kind_created_at`. **Deletes all existing `utm_events` rows**
+  before adding the column (legacy UTM-only rows are not backfilled). Run **`cf-alembic`**
+  when upgrading.
+
+### Breaking
+
+- **Breaking (clients — `utm_data`):** Batches without a valid `kind` item and at
+  least one allowlisted UTM key no longer persist. UTM-only payloads from 2.3.2
+  stop writing rows.
+
+- **Breaking (operators — `utm_events` data):** Upgrading through
+  **`2d61a5e88d76_analytics_utm_events_add_kind`** clears **`analytics.utm_events`**
+  before the **`kind`** column is added.
+
 ## [2.3.2] - 2026-07-05
 
 ### Added
@@ -435,4 +462,5 @@ First **SemVer-stable** release per **`docs/library/package-api.md`**.
 [2.3.0]: https://github.com/NepNepFFXIV/core-framework/compare/v2.2.0...v2.3.0
 [2.3.1]: https://github.com/NepNepFFXIV/core-framework/compare/v2.3.0...v2.3.1
 [2.3.2]: https://github.com/NepNepFFXIV/core-framework/compare/v2.3.1...v2.3.2
-[unreleased]: https://github.com/NepNepFFXIV/core-framework/compare/v2.3.2...HEAD
+[2.3.3]: https://github.com/NepNepFFXIV/core-framework/compare/v2.3.2...v2.3.3
+[unreleased]: https://github.com/NepNepFFXIV/core-framework/compare/v2.3.3...HEAD

{core_framework-2.3.2 → core_framework-2.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: core-framework
-Version: 2.3.2
+Version: 2.3.3
 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

core_framework-2.3.3/alembic/analytics/alembic/versions/2d61a5e88d76_analytics_utm_events_add_kind.py

@@ -0,0 +1,36 @@
+"""analytics utm_events add capture kind column
+
+Revision ID: 2d61a5e88d76
+Revises: 585105e1149e
+Create Date: 2026-07-05 13:30:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "2d61a5e88d76"
+down_revision: str | Sequence[str] | None = "585105e1149e"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.execute("delete from utm_events;")
+    op.execute("""
+        alter table utm_events
+            add column kind varchar(64) not null;
+    """)
+    op.execute("""
+        create index if not exists idx_utm_events_kind_created_at
+        on utm_events (kind, created_at);
+    """)
+
+
+def downgrade() -> None:
+    op.execute("drop index if exists idx_utm_events_kind_created_at;")
+    op.execute("""
+        alter table utm_events
+            drop column if exists kind;
+    """)

{core_framework-2.3.2 → core_framework-2.3.3}/core_framework/application/bootstrap.py

@@ -2,6 +2,7 @@ import core_framework.domains.moderation.dependencies as moderation_deps
 import core_framework.domains.user.dependencies as user_deps
 from core_framework.application.analytics.registry import configure_activity_sources
 from core_framework.application.events.event_service import configure_event_handlers
+from core_framework.application.events.utm_capture_kinds import configure_utm_capture_kinds
 from core_framework.application.shared.worker_jobs import configure_worker_jobs
 from core_framework.core.cache import configure_cashews_backend
 from core_framework.core.runtime import CoreRuntime
@@ -19,6 +20,7 @@ from core_framework.domains.user.dependencies import configure_user_dependencies
 def configure_application_dependencies(*, runtime: CoreRuntime) -> None:
     """Wire application-level dependencies from the shared runtime."""
     configure_event_handlers()
+    configure_utm_capture_kinds()
     configure_activity_sources()
     configure_worker_jobs(runtime=runtime)
     configure_cashews_backend(redis_cache_url=runtime.settings.redis.redis_cache_url)

{core_framework-2.3.2 → core_framework-2.3.3}/core_framework/application/events/README.md

@@ -16,7 +16,9 @@ Platform design and host extension: `docs/design/events-ingest-design.md`.
 ## Host extension
 
 - `register_event_handler(event_type, handler)` — append a handler after `configure_application_dependencies`
-- `configure_event_handlers()` — reset registry and register core built-ins
+- `register_utm_capture_kind(kind)` — append a `utm_data` capture kind after `configure_application_dependencies`
+- `configure_event_handlers()` — reset handler registry and register core built-ins
+- `configure_utm_capture_kinds()` — reset capture-kind registry and seed core kinds (`registration`)
 - `type` and `subject_type` are plain strings at the schema boundary
 - Each handler receives the full batch and filters its own `subject_type` values
 

{core_framework-2.3.2 → core_framework-2.3.3}/core_framework/application/events/event_service.py

@@ -6,9 +6,10 @@ import core_framework.domains.analytics.dependencies as analytics_deps
 import core_framework.domains.post.dependencies as post_deps
 import core_framework.domains.user.dependencies as user_deps
 from core_framework.application.events.models import Event
+from core_framework.application.events.utm_capture_kinds import get_utm_capture_kinds
 from core_framework.application.posts.aggregation_service import mark_post_stats_dirty
 from core_framework.application.shared.enums import EventType, SubjectType
-from core_framework.domains.analytics import UTM_ALLOWLISTED_KEYS
+from core_framework.domains.analytics import MAX_UTM_KIND_LENGTH, UTM_ALLOWLISTED_KEYS, UTM_KIND_SUBJECT_TYPE
 
 logger = get_logger(__name__)
 
@@ -76,8 +77,12 @@ async def record_signup_events(*, events: list[Event], token: str, request_conte
 
 async def record_utm_events(*, events: list[Event], token: str, request_context: dict[str, str]) -> None:
     """Persist UTM attribution from batched client events."""
+    capture_kind: str | None = None
     utm: dict[str, str] = {}
     for event in events:
+        if event.subject_type == UTM_KIND_SUBJECT_TYPE:
+            capture_kind = event.subject
+            continue
         if event.subject_type in UTM_ALLOWLISTED_KEYS:
             utm[event.subject_type] = event.subject
             continue
@@ -85,9 +90,19 @@ async def record_utm_events(*, events: list[Event], token: str, request_context:
             "UTM event item ignored: unknown subject_type",
             subject_type=event.subject_type,
         )
+    normalized_kind: str | None = None
+    if capture_kind is not None:
+        trimmed_kind = capture_kind.strip()
+        if trimmed_kind:
+            normalized_kind = trimmed_kind[:MAX_UTM_KIND_LENGTH]
+    if normalized_kind is None or normalized_kind not in get_utm_capture_kinds():
+        return
+    if not any(value.strip() for value in utm.values()):
+        return
     try:
         await analytics_deps.analytics_service.add_utm_event(
             token=token,
+            kind=normalized_kind,
             utm=utm,
             user_id=request_context.get("viewer_id"),
             client_context=request_context,

core_framework-2.3.3/core_framework/application/events/utm_capture_kinds.py

@@ -0,0 +1,30 @@
+from typing import Final
+
+from core_framework.domains.analytics import MAX_UTM_KIND_LENGTH
+
+CORE_UTM_CAPTURE_KIND_REGISTRATION: Final[str] = "registration"
+
+_utm_capture_kinds: set[str] = set()
+
+
+def configure_utm_capture_kinds() -> None:
+    """Reset the capture-kind registry and register core built-in kinds."""
+    global _utm_capture_kinds
+    _utm_capture_kinds = {CORE_UTM_CAPTURE_KIND_REGISTRATION}
+
+
+def register_utm_capture_kind(kind: str) -> None:
+    """Register one ``utm_data`` capture kind (host extension point)."""
+    trimmed = kind.strip()
+    if not trimmed:
+        raise ValueError("utm capture kind must not be empty or whitespace-only")
+    if len(trimmed) > MAX_UTM_KIND_LENGTH:
+        raise ValueError(f"utm capture kind exceeds max length ({MAX_UTM_KIND_LENGTH})")
+    if trimmed in _utm_capture_kinds:
+        raise ValueError(f"duplicate utm capture kind: {trimmed!r}")
+    _utm_capture_kinds.add(trimmed)
+
+
+def get_utm_capture_kinds() -> frozenset[str]:
+    """Return registered capture kinds for ``utm_data`` ingest."""
+    return frozenset(_utm_capture_kinds)

{core_framework-2.3.2 → core_framework-2.3.3}/core_framework/domains/analytics/README.md

@@ -35,7 +35,8 @@ Host registration (Phase 8) is documented in the design doc for consuming applic
 #### utm_events
 
 - Append-only UTM attribution captures from `POST /events` with `type: "utm_data"`
-- Columns: `id`, `created_at`, `token`, optional `user_id`, `utm` jsonb, `request_context` jsonb
-- `utm` holds folded client UTM key/value pairs; `request_context` holds server-derived metadata (same shape as login telemetry)
+- Columns: `id`, `created_at`, `token`, optional `user_id`, `kind`, `utm` jsonb, `request_context` jsonb
+- `kind` names the capture context (for example `registration`); distinct from `daily_fact.kind`
+- `utm` holds folded client UTM key/value pairs only; `request_context` holds server-derived metadata (same shape as login telemetry)
 - No dedup on `token` — each accepted ingest may append a row
 - Design: `docs/design/utm-events-design.md`

{core_framework-2.3.2 → core_framework-2.3.3}/core_framework/domains/analytics/__init__.py

@@ -1,6 +1,8 @@
 from core_framework.domains.analytics.constants import (
     DAILY_FACT_RETENTION_DAYS,
+    MAX_UTM_KIND_LENGTH,
     UTM_ALLOWLISTED_KEYS,
+    UTM_KIND_SUBJECT_TYPE,
 )
 from core_framework.domains.analytics.exceptions import BaseAnalyticsException
 from core_framework.domains.analytics.models import DailyFactBucket, DailyFactDayTotal, DailyFactKindTotal
@@ -14,5 +16,7 @@ __all__ = [
     "DailyFactBucket",
     "DailyFactDayTotal",
     "DailyFactKindTotal",
+    "MAX_UTM_KIND_LENGTH",
     "UTM_ALLOWLISTED_KEYS",
+    "UTM_KIND_SUBJECT_TYPE",
 ]

{core_framework-2.3.2 → core_framework-2.3.3}/core_framework/domains/analytics/constants.py

@@ -4,6 +4,10 @@ DAILY_FACT_RETENTION_DAYS: Final[int] = 365
 
 MAX_UTM_VALUE_LENGTH: Final[int] = 128
 
+MAX_UTM_KIND_LENGTH: Final[int] = 64
+
+UTM_KIND_SUBJECT_TYPE: Final[str] = "kind"
+
 UTM_ALLOWLISTED_KEYS: Final[frozenset[str]] = frozenset(
     {
         "utm_source",

{core_framework-2.3.2 → core_framework-2.3.3}/core_framework/domains/analytics/repository.py

@@ -235,6 +235,7 @@ class AnalyticsRepository:
         *,
         token: str,
         user_id: str | None,
+        kind: str,
         utm: dict[str, str],
         client_context: dict[str, str],
     ) -> None:
@@ -244,6 +245,7 @@ class AnalyticsRepository:
         Args:
             token: Event ingest token from the client request.
             user_id: Authenticated user id when present; otherwise ``None``.
+            kind: Capture context for this attribution row.
             utm: Normalized UTM key/value pairs for jsonb storage.
             client_context: Server-derived request metadata.
 
@@ -251,8 +253,8 @@ class AnalyticsRepository:
             None.
         """
         query = f"""
-            insert into {self.schema_sql}.utm_events (token, user_id, utm, request_context)
-            values ($1, $2, $3::jsonb, $4::jsonb)
+            insert into {self.schema_sql}.utm_events (token, user_id, kind, utm, request_context)
+            values ($1, $2, $3, $4::jsonb, $5::jsonb)
         """
         async with self.write_database.get_connection() as connection:
-            await connection.execute(query, token, user_id, utm, client_context)
+            await connection.execute(query, token, user_id, kind, utm, client_context)

{core_framework-2.3.2 → core_framework-2.3.3}/core_framework/domains/analytics/service.py

@@ -5,6 +5,7 @@ from structlog import get_logger
 
 from core_framework.domains.analytics.constants import (
     DAILY_FACT_RETENTION_DAYS,
+    MAX_UTM_KIND_LENGTH,
     MAX_UTM_VALUE_LENGTH,
     UTM_ALLOWLISTED_KEYS,
 )
@@ -229,30 +230,36 @@ class AnalyticsService:
         self,
         *,
         token: str,
+        kind: str,
         utm: dict[str, str],
         user_id: str | None,
         client_context: dict[str, str],
     ) -> bool:
         """
-        Persist one UTM attribution capture when normalized payload is non-empty.
+        Persist one UTM attribution capture when normalized payload is valid.
 
         Args:
             token: Event ingest token from the client request.
+            kind: Capture context from the ingest batch.
             utm: Folded UTM key/value pairs from the ingest batch.
             user_id: Authenticated user id when present; otherwise ``None``.
             client_context: Server-derived request metadata.
 
         Returns:
-            ``True`` when a row was inserted; ``False`` when validation yields an empty ``utm`` object.
+            ``True`` when a row was inserted; ``False`` when validation fails.
         """
-        require_non_blank_kwargs(token=token)
+        require_non_blank_kwargs(token=token, kind=kind)
         require_non_blank_if_not_none(user_id=user_id)
+        normalized_kind = _normalize_capture_kind(kind)
+        if not normalized_kind:
+            return False
         normalized_utm = _normalize_utm_payload(utm)
         if not normalized_utm:
             return False
         await self.repository.insert_utm_event(
             token=token,
             user_id=user_id,
+            kind=normalized_kind,
             utm=normalized_utm,
             client_context=client_context,
         )
@@ -263,6 +270,13 @@ def _start_of_utc_day(day: date) -> datetime:
     return datetime.combine(day, time.min, tzinfo=timezone.utc)
 
 
+def _normalize_capture_kind(kind: str) -> str | None:
+    trimmed = kind.strip()
+    if not trimmed:
+        return None
+    return trimmed[:MAX_UTM_KIND_LENGTH]
+
+
 def _normalize_utm_payload(utm: dict[str, str]) -> dict[str, str]:
     normalized: dict[str, str] = {}
     for key, value in utm.items():

core_framework-2.3.3/docs/deployments/guides/app-server-deploy-ssh.md

@@ -0,0 +1,78 @@
+# App server deploy SSH
+
+Wire GitHub Actions SSH deploy to the **app server** deploy user. This guide generates
+the key on your **laptop** (`deploy-to-app-server`). For server-side generation during
+[ubuntu-server-setup.md](ubuntu-server-setup.md) section 5 (`~/.ssh/id_ed25519` on the
+deploy user), paste `cat ~/.ssh/id_ed25519` into the same GitHub secret instead — there
+is no `deploy-to-app-server` file in that path.
+
+| Machine        | Role in this guide                                                                                      |
+| -------------- | ------------------------------------------------------------------------------------------------------- |
+| **Laptop**     | Generate keys, install public key via SSH, verify, paste GitHub secrets                                 |
+| **App server** | Receives the public key in `/home/{USER}/.ssh/authorized_keys` — no manual shell commands in this guide |
+
+GitHub → Environments → **`development`** / **`production`**:
+
+**Variables**
+
+- **`DEPLOY_SERVER_HOST`**
+- **`DEPLOY_SERVER_PORT`**
+- **`DEPLOY_SERVER_USER`** — deploy user; must be in **`docker`** group
+
+**Secrets**
+
+- **`DEPLOY_SERVER_SSH_KEY`** — contents of **`deploy-to-app-server`** (laptop path) or **`~/.ssh/id_ed25519`** (ubuntu-server-setup path)
+
+______________________________________________________________________
+
+## 1. Generate key pair
+
+**Where:** your **laptop** (creates `deploy-to-app-server` and `deploy-to-app-server.pub` in the current directory).
+
+```bash
+ssh-keygen -t ed25519 -f deploy-to-app-server -N ""
+```
+
+______________________________________________________________________
+
+## 2. Install public key on app server
+
+**Where:** your **laptop** — SSHs into the **app server** as `root` and configures the deploy user.
+
+Install the public key:
+
+```bash
+ssh -p {PORT} root@{HOST} "mkdir -p /home/{USER}/.ssh && chmod 700 /home/{USER}/.ssh && cat >> /home/{USER}/.ssh/authorized_keys && chmod 600 /home/{USER}/.ssh/authorized_keys && chown -R {USER}:{USER} /home/{USER}/.ssh" < deploy-to-app-server.pub
+```
+
+Add the deploy user to the **`docker`** group (required for deploy):
+
+```bash
+ssh -p {PORT} root@{HOST} "usermod -aG docker {USER}"
+```
+
+______________________________________________________________________
+
+## 3. Add config to GitHub
+
+**Where:** your **laptop** — copy the private key, then paste in the GitHub UI.
+
+```bash
+cat deploy-to-app-server
+```
+
+Paste into **`DEPLOY_SERVER_SSH_KEY`** (environment **secret**). Set **`DEPLOY_SERVER_HOST`**, **`DEPLOY_SERVER_PORT`**, and **`DEPLOY_SERVER_USER`** as environment **variables** (same **`{HOST}`** / **`{PORT}`** / **`{USER}`** as above).
+
+______________________________________________________________________
+
+## 4. Verify
+
+**Where:** your **laptop**.
+
+```bash
+ssh -i deploy-to-app-server -p {PORT} {USER}@{HOST}
+```
+
+A shell on the app server as the deploy user means the setup is correct.
+
+______________________________________________________________________

core_framework-2.3.3/docs/deployments/guides/image-server-ssh.md

@@ -0,0 +1,93 @@
+# Image server SSH
+
+Wire SSH from the **app server** (worker) to the **image server** (`root`). Keys are
+generated on your **laptop**; the public key is installed on the image server; the
+private key and host fingerprint go to GitHub for deploy.
+
+| Machine          | Role in this guide                                                           |
+| ---------------- | ---------------------------------------------------------------------------- |
+| **Laptop**       | Generate keys, `ssh-keyscan`, paste GitHub secrets                           |
+| **Image server** | Receives the public key in `/root/.ssh/authorized_keys` — no manual commands |
+| **App server**   | Optional verify step (step 5)                                                |
+
+GitHub → Environments → **`development`** / **`production`**:
+
+**Variables**
+
+- **`IMAGE_SERVER_HOST`**
+- **`IMAGE_SERVER_PORT`**
+- **`IMAGE_SERVER_USER`** — **`root`**
+
+**Secrets**
+
+- **`IMAGE_SERVER_SSH_PRIVATE_KEY`** — contents of **`worker-to-image-server`**
+- **`IMAGE_SERVER_KNOWN_HOSTS`** — output of **`ssh-keyscan`** (step 3); trust anchor, not a credential
+
+______________________________________________________________________
+
+## 1. Generate key pair
+
+**Where:** your **laptop** (creates `worker-to-image-server` and `worker-to-image-server.pub` in the current directory).
+
+```bash
+ssh-keygen -t ed25519 -f worker-to-image-server -N ""
+```
+
+______________________________________________________________________
+
+## 2. Install public key on image server
+
+**Where:** your **laptop** — SSHs into the **image server** and appends the public key to `authorized_keys`.
+
+```bash
+ssh -p {PORT} root@{HOST} "mkdir -p /root/.ssh && chmod 700 /root/.ssh && cat >> /root/.ssh/authorized_keys && chmod 600 /root/.ssh/authorized_keys" < worker-to-image-server.pub
+```
+
+______________________________________________________________________
+
+## 3. Get `IMAGE_SERVER_KNOWN_HOSTS`
+
+**Where:** your **laptop**.
+
+```bash
+ssh-keyscan -p {PORT} {HOST}
+```
+
+Paste all output into GitHub environment secret **`IMAGE_SERVER_KNOWN_HOSTS`**. Use the same **`{HOST}`** / **`{PORT}`** as the other image-server settings.
+
+______________________________________________________________________
+
+## 4. Add secrets to GitHub
+
+**Where:** your **laptop** — copy the private key, then paste in the GitHub UI (step 3 output → **`IMAGE_SERVER_KNOWN_HOSTS`**, below → **`IMAGE_SERVER_SSH_PRIVATE_KEY`**).
+
+```bash
+cat worker-to-image-server
+```
+
+Paste into **`IMAGE_SERVER_SSH_PRIVATE_KEY`**.
+
+______________________________________________________________________
+
+## 5. Verify
+
+**Where:** **app server** — confirms the worker host can reach the image server with this key.
+
+Copy the private key from your laptop to the app server:
+
+**Laptop:**
+
+```bash
+scp -P {DEPLOY_SERVER_PORT} worker-to-image-server {DEPLOY_SERVER_USER}@{APP_SERVER_HOST}:~/
+```
+
+**App server:**
+
+```bash
+chmod 600 ~/worker-to-image-server
+ssh -i ~/worker-to-image-server -p {PORT} root@{HOST}
+```
+
+A shell on the image server means the setup is correct. You can delete `~/worker-to-image-server` on the app server after testing — deploy uses the GitHub secret, not this file.
+
+______________________________________________________________________

{core_framework-2.3.2 → core_framework-2.3.3}/docs/deployments/guides/ubuntu-server-setup.md

@@ -88,6 +88,7 @@ On the server as **`{DEPLOY_USER}`**:
 ```bash
 mkdir -p ~/.ssh
 chmod 700 ~/.ssh
+ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -N ""
 cat ~/.ssh/id_ed25519.pub >> ~/.ssh/authorized_keys
 chmod 600 ~/.ssh/authorized_keys
 cat ~/.ssh/id_ed25519

{core_framework-2.3.2 → core_framework-2.3.3}/docs/design/README.md

@@ -7,16 +7,16 @@ a capability is built, not day-to-day coding rules.
 **Rules** (conventions, layering, ADRs) live in [`../platform/`](../platform/).
 **Product flows** and per-domain feature design live in [`../domains/`](../domains/).
 
-| Doc                                                            | Purpose                                                                       |
-| -------------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| [`event-outbox-design.md`](event-outbox-design.md)             | Transactional outbox (mirror fanout)                                          |
-| [`events-ingest-design.md`](events-ingest-design.md)           | Client events ingest — host-extensible handler dispatch                       |
-| [`analytics-rollup-design.md`](analytics-rollup-design.md)     | Analytics rollup domain — time-bucketed activity rollups                      |
-| [`utm-events-design.md`](utm-events-design.md)                 | UTM attribution ingest — `utm_data` on `POST /events`, `analytics.utm_events` |
-| [`outbox-admin-ops-design.md`](outbox-admin-ops-design.md)     | Admin API: list dead outbox rows, replay one row                              |
-| [`create-idempotency-design.md`](create-idempotency-design.md) | HTTP create idempotency for post/comment create                               |
-| [`cache-invalidation-design.md`](cache-invalidation-design.md) | Cache invalidation — write-path, admin API, planned events hints              |
-| [`media-storage-topology.md`](media-storage-topology.md)       | Rack media layout: staging vs finals; no S3/R2                                |
+| Doc                                                            | Purpose                                                                                       |
+| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| [`event-outbox-design.md`](event-outbox-design.md)             | Transactional outbox (mirror fanout)                                                          |
+| [`events-ingest-design.md`](events-ingest-design.md)           | Client events ingest — host-extensible handler dispatch                                       |
+| [`analytics-rollup-design.md`](analytics-rollup-design.md)     | Analytics rollup domain — time-bucketed activity rollups                                      |
+| [`utm-events-design.md`](utm-events-design.md)                 | UTM attribution ingest — `utm_data` on `POST /events`, `analytics.utm_events`, capture `kind` |
+| [`outbox-admin-ops-design.md`](outbox-admin-ops-design.md)     | Admin API: list dead outbox rows, replay one row                                              |
+| [`create-idempotency-design.md`](create-idempotency-design.md) | HTTP create idempotency for post/comment create                                               |
+| [`cache-invalidation-design.md`](cache-invalidation-design.md) | Cache invalidation — write-path, admin API, planned events hints                              |
+| [`media-storage-topology.md`](media-storage-topology.md)       | Rack media layout: staging vs finals; no S3/R2                                                |
 
 When adding a new cross-cutting mechanism, add a `*-design.md` here and a client
 flow doc under `docs/domains/` when the HTTP surface is ready.

{core_framework-2.3.2 → core_framework-2.3.3}/docs/design/events-ingest-design.md

@@ -1,6 +1,10 @@
 # Client Events Ingest — Host-Extensible Design
 
-**Status:** **Shipped (v1)** for core event types **`impression`**, **`login`**, **`signup`**, and **`utm_data`**. Hosts may register additional types at bootstrap. Application-level rate limiting is **not** implemented — use edge limits and client-side batching (see [`events.md`](../domains/events/events.md)).
+**Status:** **Shipped** for core event types **`impression`**, **`login`**, **`signup`**, and
+**`utm_data`** (including capture **`kind`** on UTM rows). Hosts may register additional
+event types and `utm_data` capture kinds at bootstrap. Application-level rate limiting
+is **not** implemented — use edge limits and client-side batching (see
+[`events.md`](../domains/events/events.md)).
 
 Core provides a generic, token-gated, client-initiated channel for **eventually
 consistent side effects**. Clients fetch a signed token and post a batch; the
@@ -108,21 +112,22 @@ ______________________________________________________________________
 | Built-in `impression` | Filters `subject_type == "post"`; dedup by `(post_id, token)`; marks post dirty on new row                                                                                                         |
 | Built-in `login`      | Uses `viewer_id` from request context (not the payload); auto-provisions application user row when missing                                                                                         |
 | Built-in `signup`     | Uses `viewer_id` from request context (not the payload)                                                                                                                                            |
-| Built-in `utm_data`   | Folds allowlisted `events[]` items into `analytics.utm_events`; append-all; optional auth — see [utm-events-design.md](utm-events-design.md)                                                       |
+| Built-in `utm_data`   | Extracts `kind`, folds allowlisted UTM items into `analytics.utm_events`; append-all; optional auth — see [utm-events-design.md](utm-events-design.md)                                             |
 
 `EventType` / `SubjectType` StrEnums in `core_framework/application/shared/enums.py`
 are **internal constants** for core handler registration only — not schema validators.
 
 ### Code locations
 
-| Piece            | Location                                                                  |
-| ---------------- | ------------------------------------------------------------------------- |
-| Schema           | `core_framework/api/events/schemas.py`                                    |
-| Model            | `core_framework/application/events/models.py`                             |
-| Token            | `core_framework/application/events/event_token.py`                        |
-| Handler registry | `core_framework/application/events/event_service.py`                      |
-| Route            | `core_framework/api/events/router.py`                                     |
-| Bootstrap        | `configure_event_handlers()` in `core_framework/application/bootstrap.py` |
+| Piece                     | Location                                                                                                      |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| Schema                    | `core_framework/api/events/schemas.py`                                                                        |
+| Model                     | `core_framework/application/events/models.py`                                                                 |
+| Token                     | `core_framework/application/events/event_token.py`                                                            |
+| Handler registry          | `core_framework/application/events/event_service.py`                                                          |
+| UTM capture-kind registry | `core_framework/application/events/utm_capture_kinds.py`                                                      |
+| Route                     | `core_framework/api/events/router.py`                                                                         |
+| Bootstrap                 | `configure_event_handlers()` and `configure_utm_capture_kinds()` in `core_framework/application/bootstrap.py` |
 
 ______________________________________________________________________
 
@@ -163,6 +168,24 @@ A host **impression** handler should:
 Core never imports host code. The host owns its `type` and `subject_type` string
 literals.
 
+### `utm_data` capture kinds
+
+Hosts extend the **`utm_data`** capture-kind allowlist without a core release:
+
+1. Call `register_utm_capture_kind(kind)` after `configure_application_dependencies`
+   (same bootstrap timing as `register_event_handler`).
+1. Document the new `kind` string in host flow docs — core documents `registration`
+   only in [events.md](../domains/events/events.md).
+1. Clients send the `kind` as an `events[]` item with `subject_type` `kind` and
+   `subject` set to the registered string, plus at least one allowlisted UTM item.
+
+Core resets and seeds `registration` in `configure_utm_capture_kinds()` during
+application bootstrap. The single core `utm_data` handler enforces the merged
+allowlist; hosts do not register a second handler for additional kinds.
+
+See [utm-events-design.md](utm-events-design.md) for persistence rules (`kind` and
+non-empty `utm` both required).
+
 ### Dispatch semantics
 
 - All handlers for the event type are scheduled as separate `BackgroundTasks` entries; they run **one after another** after the response (not concurrently).
@@ -194,6 +217,7 @@ ______________________________________________________________________
 | `EventType` / `SubjectType` as internal constants only | Core handlers use named constants; schema does not gate hosts                                                                                                                                  |
 | Single global token max-age                            | Token is type-agnostic; one expiry for all event types                                                                                                                                         |
 | Multi-handler registry keyed by string                 | Hosts attach to existing or new event types without core imports                                                                                                                               |
+| `register_utm_capture_kind` for `utm_data`             | Hosts add funnel capture kinds without core releases; single handler and `analytics.utm_events` table                                                                                          |
 | Each handler filters its own subject types             | Post and host handlers coexist on `impression`                                                                                                                                                 |
 | Unknown types accepted as 202, no-op                   | Typos do not 422; safe for fire-and-forget                                                                                                                                                     |
 | `(subject, token)` dedup for impression handlers       | Same semantics as post views                                                                                                                                                                   |