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

{core_framework-2.3.1 → core_framework-2.3.3}/.cursor/rules/api-reference-docs.mdc

@@ -29,3 +29,12 @@ globs:
 - Detailed behavior notes
 
 For detailed API behavior, create or update flow documentation in `docs/domains/` instead.
+
+## CI contract
+
+`tests/unit/docs/api_routes_test.py` parses this file and asserts **bidirectional** parity with the core FastAPI app:
+
+- every listed `(METHOD, path)` exists on the app with **matching path-param names**
+- every app `(METHOD, path)` (GET/POST/PUT/PATCH/DELETE) is listed here
+
+Flow docs under `docs/domains/` must not list endpoints in their `http` blocks unless those exact routes appear here. Update this index when adding or renaming routes.

{core_framework-2.3.1 → core_framework-2.3.3}/.cursor/rules/constitution.mdc

@@ -39,4 +39,4 @@ Do not edit consuming host repos in the same task as core-framework work unless
 
 ## Feature implementation
 
-Greenfield features (DB → API → repository → service → tests): use the **implement-feature** skill — one layer per response unless the user says otherwise.
+Greenfield features (DB → API → repository → service → **documentation** → tests): use the **implement-feature** skill — one layer per response unless the user says otherwise. A feature is **not done** until documentation is updated.

{core_framework-2.3.1 → core_framework-2.3.3}/.cursor/rules/error-boundary.mdc

@@ -16,10 +16,10 @@ Platform contract: **`docs/platform/client-error-visibility.md`**. Domain import
 
 | Layer | Outward errors | HTTP |
 |-------|----------------|------|
-| **Application** | **`application.shared.exceptions`**, **`InvalidPageTokenError`** | Handlers map type → status + `detail` |
+| **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 |
-| **API** | Pydantic | **422** |
 
 ## Application and domain
 
@@ -47,7 +47,7 @@ Platform contract: **`docs/platform/client-error-visibility.md`**. Domain import
 
 ## Validation order
 
-User-fixable input shape → API schemas (**422**). Domain backstops → **`DomainValidationError`** → generic **400**.
+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
 

{core_framework-2.3.1 → core_framework-2.3.3}/.cursor/rules/no-code-in-docs.mdc

@@ -28,7 +28,7 @@ Documentation under **`docs/`** must not carry **implementation** snippets that
 ## Exceptions
 
 - **Deployment runbooks** under **`docs/deployments/`** (setup guides, deploy/release playbooks, SSH/image-server guides) may include fenced **`bash`** shell blocks. These are operator instructions for interactive server setup, not implementation that drifts from source; copy-paste commands are the practical content. This exemption does **not** extend to **`docs/deployments/*-design.md`** design docs, which follow the general rules above.
-- **Design docs** under **`docs/platform/`** and **`docs/library/`** (and **`docs/deployments/*-design.md`**) follow the general allow/exclude lists — DDL is allowed, DML and Python are not. Flow docs under **`docs/domains/**`** are stricter: see **`flow-documentation.mdc`** (no DDL, no JSON request bodies, fields described as text/tables).
+- **Design docs** under **`docs/design/`**, **`docs/platform/`**, and **`docs/library/`** (and **`docs/deployments/*-design.md`**) follow the general allow/exclude lists — DDL is allowed, DML and Python are not. Flow docs under **`docs/domains/**`** are stricter: see **`flow-documentation.mdc`** (no DDL, no JSON request bodies, fields described as text/tables).
 
 ## Rationale
 

{core_framework-2.3.1 → core_framework-2.3.3}/.cursor/skills/add-domain/SKILL.md

@@ -18,7 +18,7 @@ Follow the **implement-feature** skill: one step per response, wait for review.
 Not every domain owns persistence. A **capability-only** domain wraps a non-SQL capability (for example `auth`, which wraps Firebase Admin via `domains/auth/ports/`, `domains/auth/service.py`, and `core_framework/infrastructure/firebase/`). For those, **skip** schema config, the Alembic tree, and `ALEMBIC_DOMAINS` entirely — no `schema_<domain>` in `PostgresSchemasConfig` / `[postgres_schemas]`, no `alembic/<domain>/`, no repository. Scaffold only:
 
 - `domains/<domain>/{__init__.py, exceptions.py, models.py, ports/, service.py, dependencies.py}`
-- A port (`<Name>Port`) describing the capability, a facade `*Service` over it, and an adapter under `core_framework/infrastructure/<domain>/` wired in `dependencies.py` — see `docs/platform/domain-services-and-adapters.md` (Auth section) for the layout.
+- A port (`<Name>Port`) describing the capability, a facade `*Service` over it, and an adapter under `core_framework/infrastructure/<domain>/` wired in `dependencies.py` — see `docs/platform/domain-services-and-adapters.md` (rules) and `docs/library/capability-wiring.md` (Auth example).
 - Export only `Base<Domain>Exception` + public models from `__init__.py`; keep the facade service in `dependencies.py`.
 - Wire `configure_<domain>_dependencies()` in `application/bootstrap.py` (no `runtime` needed when there is no Postgres handle).
 

core_framework-2.3.3/.cursor/skills/implement-feature/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: implement-feature
+description: Step-by-step feature implementation — DB → API → repository → service/application → documentation → tests. Use when adding a new feature, endpoint, or domain behavior across layers, or when the user asks to follow the implementation workflow.
+---
+
+# Implement Feature
+
+Implement **one step at a time**. Stop after each step and wait for user review. Do **not** skip ahead or implement multiple layers in one response unless the user **explicitly** says "implement everything" or "do it all at once".
+
+## Definition of done
+
+A feature is **not complete** until **all** documentation for the shipped behavior is updated. Code merged without matching docs is **unfinished work** — do not treat the feature as done or move on until the documentation step is accepted.
+
+## Before you start
+
+- Do **not** implement repository, service, or application code when doing the API layer.
+- Do **not** implement multiple layers in a single response.
+- When in doubt, do **less** and wait for review.
+
+## 1. Database changes (if needed)
+
+- **Only** create the Alembic migration file(s).
+- **No** code changes anywhere else.
+- Wait for the user to review and accept the database structure before proceeding.
+
+## 2. API layer (if needed)
+
+After the user accepts database changes (or if there were none):
+
+- **Only** implement the API layer: schemas and router.
+- Follow the **fastapi** skill (`.agents/skills/fastapi/`) and **`api-layer`** / **`api-validation`** / **`error-boundary`** rules.
+- **No** changes in domain, service, or application layers.
+- Include request/response schemas, error handling, and HTTP-related logic.
+- If the feature is not yet implemented, return 501 Not Implemented from the route.
+- Wait for the user to review and accept before proceeding.
+
+## 3. Repository and domain model
+
+After the user accepts the API layer (or if there was no API layer):
+
+- Implement the **Repository** for the domain layer (Postgres only).
+- Include the **domain model** if data is retrieved from the database.
+- If the feature needs non-SQL I/O (filesystem, HTTP, SSH), add **ports** in the domain and **adapter implementations** under `core_framework/infrastructure/<domain>/` per `docs/platform/domain-services-and-adapters.md` — not in the repository.
+- Wait for the user to review and accept before proceeding.
+
+## 4. Service and application layer
+
+After the user accepts the repository (and any ports/adapters):
+
+- Implement **domain service(s)** (persistence and any port-backed collaborators); wire in `dependencies.py`.
+- Implement the **application** layer (orchestration across domains and transports — no permanent home for raw I/O libraries).
+- Wire everything together (replace 501 with real logic).
+- Wait for the user to review and accept before proceeding.
+
+## 5. Documentation (required)
+
+After the user accepts the service and application layer:
+
+Update **every** doc surface the feature touches. Use the **write-flow-doc** skill for new or changed HTTP behavior. Follow **`no-code-in-docs.mdc`** and **`flow-documentation.mdc`**.
+
+| Change                                      | Update                                                                           |
+| ------------------------------------------- | -------------------------------------------------------------------------------- |
+| New or changed HTTP endpoint                | Flow doc under `docs/domains/{domain}/`; add **`Current Implementation Status`** |
+| New or changed route in the index           | `docs/library/api.md` (endpoint list only — see **`api-reference-docs.mdc`**)    |
+| New flow or design doc file                 | `docs/domains/README.md` (and `docs/design/README.md` if cross-cutting)          |
+| New cross-cutting mechanism                 | `docs/design/*-design.md`                                                        |
+| New or changed worker schedule or ARQ task  | `docs/library/workers.md`; link from domain flow or design doc                   |
+| Domain scope, tables, or invariants changed | `core_framework/domains/{domain}/README.md`                                      |
+| New audit trigger                           | `docs/platform/database-triggers.md`                                             |
+| Settings / config the host must wire        | `docs/library/package-api.md` and/or **add-config** skill targets                |
+| Accepted policy or ADR                      | `docs/platform/architecture-decisions.md` when the feature locks a new decision  |
+
+**Do not** mark a feature done while any row above still applies and is missing an update.
+
+Wait for the user to review and accept documentation before proceeding (or before declaring the feature complete when tests are skipped).
+
+## 6. Tests (when requested)
+
+After documentation is accepted:
+
+- Add or update integration tests when the user asks for tests in this task.
+- If the user did not ask for tests, the feature is **done** after step 5 is accepted.
+
+## Flexibility
+
+If the feature has no database change (e.g., pure logic, workers) or no API layer (e.g., background workers, internal jobs), skip the irrelevant steps and follow the remaining order. **Documentation (step 5) still applies** whenever behavior ships.
+
+## Checklist (verify before every response)
+
+- [ ] Did I implement only one step?
+- [ ] Did I stop and wait for review?
+- [ ] Did I skip ahead to other layers? (If yes, roll back and redo.)
+- [ ] If this step finishes the feature: is **all** required documentation updated? (If no, the feature is **not** done.)

{core_framework-2.3.1 → core_framework-2.3.3}/.cursor/skills/sync-host-rules/SKILL.md

@@ -12,7 +12,7 @@ Consuming applications embed **core-framework** as a dependency.
 When changing **core-framework** code, migrations, tests, or **`docs/`**:
 
 - **Do not** edit host repos in the same task.
-- **Do not** port **`docs/platform/`**, **`docs/deployments/`**, **`.cursor/rules/`**, or **`.cursor/skills/`** to hosts proactively.
+- **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
@@ -35,7 +35,7 @@ Diff by **basename** against the host's **`.cursor/`** and applicable **`docs/`*
 
 **Core `docs/` must stay host-agnostic** — no references to specific consuming applications.
 
-| Core path                                     | Host behavior                                                 |
-| --------------------------------------------- | ------------------------------------------------------------- |
-| **`docs/platform/`**, **`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 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-2.3.1 → core_framework-2.3.3}/.cursor/skills/write-flow-doc/SKILL.md

@@ -74,5 +74,6 @@ Concise, active voice, present tense, client perspective. Horizontal rules betwe
 
 - [ ] Endpoint list at top; each endpoint has Goal, Preconditions, Flow, Errors
 - [ ] No implementation identifiers or code snippets
-- [ ] Links to **`docs/platform/architecture-decisions.md`** when referencing design choices
+- [ ] Links to **`docs/platform/architecture-decisions.md`** when referencing accepted policy or ADR decisions
+- [ ] Links to **`docs/design/`** when referencing cross-cutting mechanisms (outbox, events ingest, idempotency, analytics rollup, etc.)
 ```

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

@@ -4,6 +4,52 @@ 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
+
+- **UTM attribution ingest:** `POST /events` with `type: "utm_data"` records `analytics.utm_events` (`utm` and `request_context` jsonb; optional `user_id`). UTM keys are sent as `events[]` items (`subject_type` = field name, `subject` = value). See **`docs/domains/events/events.md`** and **`docs/design/utm-events-design.md`**.
+- **Signup telemetry:** `POST /events` with `type: "signup"` records `user_signup_events` (one row per user, `request_context` jsonb) after `POST /auth/register`. See **`docs/domains/events/events.md`**.
+- **Request context parsing:** `application/shared/request_context.py` normalizes `User-Agent`, `client-referrer` (`referrer_url`, `referrer_host`), and `Cf-Ipcountry` for events ingest.
+
+### Breaking
+
+- **Breaking (clients — events ingest):** Traffic source for request context uses the **`client-referrer`** header instead of browser **`Referer`**. Clients should send an explicit referrer URL (for example captured from `document.referrer` on first load).
+- **Breaking (clients — events ingest):** Rename event type **`view`** → **`impression`** on `POST /events`. Clients and hosts must send `type: "impression"` for subject-impression batches (post views, calculator opens, etc.). Core enum: **`EventType.IMPRESSION`** (replaces **`EventType.VIEW`**). Host handlers registered on `"view"` must re-register on **`"impression"`** (for example Henry calculator view ingest).
+- **Breaking (hosts — imports):** Rename **`EVENT_TOKEN_MAX_AGE_VIEW_SECONDS`** → **`EVENT_TOKEN_MAX_AGE_SECONDS`** in **`core_framework.application.events.event_token`** (behavior unchanged; token max-age remains 600s for all event types).
+
+### Migration
+
+- **`analytics` schema:** **`585105e1149e_analytics_add_utm_events`** — `utm_events` table. Run **`cf-alembic`** when upgrading.
+- **`user` schema:** **`44df70a45ba6_user_add_signup_events`** — `user_signup_events` table (`user_id` unique, `request_context` jsonb). Run **`cf-alembic`** when upgrading.
+
 ## [2.3.1] - 2026-07-03
 
 ### Added
@@ -23,7 +69,7 @@ Analytics rollup domain (materialized daily activity counts), admin read API, an
 
 ### Added
 
-- **Analytics rollup (Phase 1):** `analytics` domain scaffold, `schema_analytics`, `[analytics].refresh_interval_seconds` (required on **`Settings`**; core **`config.toml`** ships **300**), Alembic tree with `daily_fact` table (PK only), and activity source registry shell. See **`docs/platform/analytics-rollup-design.md`**.
+- **Analytics rollup (Phase 1):** `analytics` domain scaffold, `schema_analytics`, `[analytics].refresh_interval_seconds` (required on **`Settings`**; core **`config.toml`** ships **300**), Alembic tree with `daily_fact` table (PK only), and activity source registry shell. See **`docs/design/analytics-rollup-design.md`**.
 - **Analytics rollup (Phase 2):** `AnalyticsService.list_refreshable_days` and `is_final_bucket_refresh` (planner inputs), `refresh_daily_fact_bucket` (single-bucket executor), optional `refresh_all_open_buckets` for tests; transactional `replace_daily_fact_bucket`; admin read helpers.
 - **Analytics rollup (Phase 3):** `post` / `created` activity source, planner (`enqueue_refresh_analytics_buckets`) and executor (`refresh_analytics_bucket`) application entrypoints, `schedule_refresh_analytics` + `process_refresh_analytics_bucket` worker (cron from `refresh_interval_seconds`).
 - **Analytics rollup (Phase 4):** `comment` / `created`, `user` / `registered`, and `post` / `viewed` activity sources with domain UTC-day count accessors and registry registration.
@@ -43,7 +89,7 @@ Transactional outbox (block, follow, restriction), post views retention, and inc
 ### Added
 
 - **Post views retention:** Incremental **`view_count`** aggregation via **`post_stats.view_count_aggregated_up_to`** (high-water mark on **`post_views.created_at`**); daily worker **`schedule_prune_post_views`** (05:00 UTC) deletes aggregated rows older than **`retention.post_views_retention_days`** (default **90**). See **`docs/domains/posts/post_stats_aggregation.md`**.
-- **Transactional outbox (block pilot):** `user.event_outbox`, worker poller/handler for **`user.block.relationship_changed`**, durable post/comment/notification block mirror fanout. See **`docs/platform/event-outbox-design.md`**.
+- **Transactional outbox (block pilot):** `user.event_outbox`, worker poller/handler for **`user.block.relationship_changed`**, durable post/comment/notification block mirror fanout. See **`docs/design/event-outbox-design.md`**.
 - **Transactional outbox (follow, Phase 2):** **`user.follow.relationship_changed`** enqueued with truth changes; worker reconciles **`post.user_followers_lookup`** (outbox-only mirror path, matching block). Non-retryable handler errors dead-letter immediately (decision **#22**).
 - **Transactional outbox (restriction, Phase 3):** **`moderation.restriction.relationship_changed`** enqueued on truth changes and no-op healing; worker reconciles post/comment/user/notification restriction lookup mirrors (outbox-only, matching block/follow). Poller E2E in **`tests/integration/worker/moderation_outbox_test.py`**. Run **`cf-alembic`** for **`moderation_add_event_outbox`**.
 
@@ -88,7 +134,7 @@ First production-ready **2.x** release. Hosts must run **`cf-alembic`**, configu
 
 - **Post and comment image attachments (v1):** **`POST /attachments`** compose-time ingest; worker encodes and publishes **`thumb`** / **`display`** WebP finals; **`attachment_ids`** on post/comment create and **`PATCH`** diff edit — attach is **best-effort per added asset** on create **and** edit (failing assets are skipped and burned; the post/comment write still succeeds and mention notifications proceed; malformed sets — duplicates or over-cap — fail request validation with **`422`**, with the same guards re-checked in the post/comment domain services); public and admin read **`attachments`** wrapper on post/comment responses; staging housekeeping sweeps; admin hard delete and account removal enqueue attachment finals cleanup. Tables **`post_image_attachments`**, **`comment_image_attachments`**, **`attachment_staging_registry`**. Config **`[attachment]`** and deploy vars **`ATTACHMENT_*`**. See **`docs/domains/media/post-comment-attachments-design.md`**.
 
-- **HTTP create idempotency (v1):** Optional **`Idempotency-Key`** on **`POST /posts`**, **`POST /comments`**, and **`POST /comments/{comment_id}/replies`**. At most one committed row per **`(author_id, key, operation)`**; replays return **`201`** with empty body and skip mention notifications, attachment attach, and stats-dirty side effects. See **`docs/platform/create-idempotency-design.md`**.
+- **HTTP create idempotency (v1):** Optional **`Idempotency-Key`** on **`POST /posts`**, **`POST /comments`**, and **`POST /comments/{comment_id}/replies`**. At most one committed row per **`(author_id, key, operation)`**; replays return **`201`** with empty body and skip mention notifications, attachment attach, and stats-dirty side effects. See **`docs/design/create-idempotency-design.md`**.
 
 - **Request profiling (opt-in):** **`PROFILING_ENABLED`** and **`PROFILING_KEY`** — pyinstrument middleware gated by **`Profiling-Key`** header.
 
@@ -149,7 +195,7 @@ Run **`uv run cf-alembic`** (or host **`cf-alembic`**) before deploying **2.0.0*
 
 ### Documentation
 
-- **`docs/platform/client-error-visibility.md`**, **`docs/platform/create-idempotency-design.md`**, **`docs/deployments/edge-upload-limits.md`**, **`docs/deployments/deploy-playbook.md`**, deletion refactor docs under **`docs/domains/deletion/`**.
+- **`docs/platform/client-error-visibility.md`**, **`docs/design/create-idempotency-design.md`**, **`docs/deployments/edge-upload-limits.md`**, **`docs/deployments/deploy-playbook.md`**, deletion refactor docs under **`docs/domains/deletion/`**.
 
 ## [1.8.1] - 2026-06-07
 
@@ -413,4 +459,8 @@ First **SemVer-stable** release per **`docs/library/package-api.md`**.
 [2.0.0]: https://github.com/NepNepFFXIV/core-framework/compare/v1.8.1...v2.0.0
 [2.1.0]: https://github.com/NepNepFFXIV/core-framework/compare/v2.0.0...v2.1.0
 [2.2.0]: https://github.com/NepNepFFXIV/core-framework/compare/v2.1.0...v2.2.0
-[unreleased]: https://github.com/NepNepFFXIV/core-framework/compare/v2.2.0...HEAD
+[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
+[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.1 → core_framework-2.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: core-framework
-Version: 2.3.1
+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
@@ -10,7 +10,6 @@ Requires-Python: >=3.14
 Requires-Dist: aiofiles>=25.1.0
 Requires-Dist: alembic>=1.18.4
 Requires-Dist: arq>=0.28.0
-Requires-Dist: async-lru>=2.1.0
 Requires-Dist: asyncer>=0.0.14
 Requires-Dist: asyncpg>=0.31.0
 Requires-Dist: asyncssh>=2.23.0
@@ -62,6 +61,8 @@ make run
 
 For **`make test`**, use the Firebase CLI (Auth emulator). Stop DB/Redis: **`docker compose -f 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`**).
+
 ## Hosts
 
 In your host app, load **`Settings`** or a **`Settings`** subclass from **`core_framework.core.settings`**, pass it to **`init_app`** from **`core_framework.main`**, then wire host-specific dependencies, exception handlers, and routers.

{core_framework-2.3.1 → core_framework-2.3.3}/README.md

@@ -23,6 +23,8 @@ make run
 
 For **`make test`**, use the Firebase CLI (Auth emulator). Stop DB/Redis: **`docker compose -f 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`**).
+
 ## Hosts
 
 In your host app, load **`Settings`** or a **`Settings`** subclass from **`core_framework.core.settings`**, pass it to **`init_app`** from **`core_framework.main`**, then wire host-specific dependencies, exception handlers, and routers.

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.3/alembic/analytics/alembic/versions/585105e1149e_analytics_add_utm_events.py

@@ -0,0 +1,38 @@
+"""analytics utm_events for client UTM attribution ingest
+
+Revision ID: 585105e1149e
+Revises: 7f2a9c1d4e8b
+Create Date: 2026-07-05 12:00:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "585105e1149e"
+down_revision: str | Sequence[str] | None = "7f2a9c1d4e8b"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        create table utm_events (
+            id bigint generated always as identity primary key,
+            created_at timestamptz not null default now(),
+            token varchar(256) not null,
+            user_id varchar(128),
+            utm jsonb not null default '{}'::jsonb,
+            request_context jsonb not null default '{}'::jsonb
+        );
+    """)
+    op.execute("""
+        create index if not exists idx_utm_events_created_at
+        on utm_events (created_at);
+    """)
+
+
+def downgrade() -> None:
+    op.execute("drop index if exists idx_utm_events_created_at;")
+    op.execute("drop table if exists utm_events;")

core_framework-2.3.3/alembic/user/alembic/versions/44df70a45ba6_user_add_signup_events.py

@@ -0,0 +1,32 @@
+"""add user_signup_events for registration telemetry
+
+Revision ID: 44df70a45ba6
+Revises: 9d9611e47ce2
+Create Date: 2026-07-04 12:00:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "44df70a45ba6"
+down_revision: str | Sequence[str] | None = "9d9611e47ce2"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        create table user_signup_events (
+            id bigint generated always as identity primary key,
+            user_id varchar(128) not null references users(user_id) on delete cascade,
+            created_at timestamptz not null default now(),
+            request_context jsonb not null default '{}'::jsonb,
+            constraint user_signup_events_user_id_unique unique (user_id)
+        );
+    """)
+
+
+def downgrade() -> None:
+    op.execute("drop table if exists user_signup_events")

{core_framework-2.3.1 → core_framework-2.3.3}/config.toml

@@ -80,6 +80,7 @@ allowed_headers = [
     "Content-Type",
     "Idempotency-Key",
     "Profiling-Key",
+    "Client-Referrer",
 ]
 
 [http_client]

{core_framework-2.3.1 → core_framework-2.3.3}/config.toml.template

@@ -64,6 +64,7 @@ allowed_headers = [
     "Content-Type",
     "Idempotency-Key",
     "Profiling-Key",
+    "Client-Referrer",
 ]
 
 [http_client]

{core_framework-2.3.1 → core_framework-2.3.3}/core_framework/api/auth/schemas.py

@@ -1,18 +1,7 @@
-from typing import Annotated
-
-from pydantic import BaseModel, EmailStr, Field
+from pydantic import BaseModel, EmailStr
 
 from core_framework.api.users.shared.schemas import UserID, Username
 
-CountryCode = Annotated[
-    str,
-    Field(
-        description="ISO 3166-1 alpha-2 country code",
-        pattern="^[A-Z]{2}$",
-        examples=["US", "GB"],
-    ),
-]
-
 
 class CreatedUserResponse(BaseModel):
     user_id: UserID

{core_framework-2.3.1 → core_framework-2.3.3}/core_framework/api/dependencies.py

@@ -1,17 +1,20 @@
 from typing import Annotated
 
-from async_lru import alru_cache
 from fastapi import Depends, Header, Query, Security
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
 from pydantic import ValidationError
 
 import core_framework.domains.auth.dependencies as auth_deps
-from core_framework.api.auth.schemas import CountryCode, FirebaseUser
+from core_framework.api.auth.schemas import FirebaseUser
 from core_framework.api.users.shared.schemas import UserID, parse_user_id
 from core_framework.application.auth.access_service import get_user_detail
 from core_framework.application.auth.models import UserDetail
 from core_framework.application.shared.exceptions import BadRequestException, ForbiddenException, UnauthorizedException
-from core_framework.application.shared.user_agent import parse_user_agent
+from core_framework.application.shared.request_context import (
+    parse_cf_ipcountry,
+    parse_client_referrer,
+    parse_user_agent,
+)
 from core_framework.application.users.admin_service import retrieve_admin_user_ids
 from core_framework.core.context import user_id
 from core_framework.domains.auth import VerifiedTokenClaims
@@ -21,11 +24,6 @@ from core_framework.domains.user import UserIdentity
 bearer_scheme = HTTPBearer(auto_error=False)
 
 
-@alru_cache(maxsize=5000, ttl=300)  # ~10MB per worker, 5 minutes TTL
-async def _verify_id_token(token: str) -> VerifiedTokenClaims | None:
-    return await auth_deps.auth_service.verify_id_token(token=token)
-
-
 def _build_firebase_user_from_claims(claims: VerifiedTokenClaims) -> FirebaseUser | None:
     try:
         return FirebaseUser(
@@ -54,7 +52,7 @@ async def _get_firebase_user(token: Annotated[str | None, Depends(_get_bearer_to
     if not token:
         return None
 
-    claims = await _verify_id_token(token)
+    claims = await auth_deps.auth_service.verify_id_token(token=token)
     if claims is None:
         return None
 
@@ -106,18 +104,18 @@ async def check_not_banned(user_detail: Annotated[UserDetail, Depends(_get_user_
 async def _get_request_context(
     firebase_user: Annotated[FirebaseUser | None, Depends(_get_firebase_user)],
     user_agent: Annotated[str | None, Header()] = None,
-    cf_ipcountry: Annotated[CountryCode | None, Header()] = None,
+    cf_ipcountry: Annotated[str | None, Header()] = None,
+    client_referrer: Annotated[str | None, Header()] = None,
 ) -> dict[str, str]:
     metadata: dict[str, str] = {}
 
     if firebase_user:
         metadata["viewer_id"] = firebase_user.user_id
         metadata["provider"] = firebase_user.sign_in_provider
-    if cf_ipcountry:
-        metadata["country_code"] = cf_ipcountry
 
-    client_info = parse_user_agent(user_agent=user_agent)
-    metadata.update(client_info)
+    metadata.update(parse_cf_ipcountry(cf_ipcountry=cf_ipcountry))
+    metadata.update(parse_client_referrer(client_referrer=client_referrer))
+    metadata.update(parse_user_agent(user_agent=user_agent))
 
     return {k: v for k, v in metadata.items() if v is not None}
 

{core_framework-2.3.1 → core_framework-2.3.3}/core_framework/application/auth/access_service.py

@@ -9,8 +9,9 @@ from core_framework.core import CacheKey
 from core_framework.domains.user import UserIdentity
 
 
-@cache.cache(
+@cache.early(
     ttl=lambda *_args, **_kwargs: CacheKey.USER_DETAIL.ttl_seconds,
+    early_ttl=lambda *_args, **_kwargs: CacheKey.USER_DETAIL.early_ttl_seconds,
     key=CacheKey.USER_DETAIL.key_template,
     condition=lambda result, args, kwargs, key=None: result.identity != UserIdentity.DEFAULT,
 )

{core_framework-2.3.1 → 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)
@@ -39,8 +41,3 @@ def configure_application_dependencies(*, runtime: CoreRuntime) -> None:
             runtime.settings.postgres_schemas.schema_moderation: moderation_deps.moderation_outbox_service,
         }
     )
-
-    # alru_cache on user id set must not survive a rebound UserService instance
-    import core_framework.application.users.admin_service as admin_service
-
-    admin_service.retrieve_admin_user_ids.cache_clear()

core_framework-2.3.3/core_framework/application/events/README.md

@@ -0,0 +1,31 @@
+# Events Application Layer
+
+Client-initiated, eventually consistent side effects: token verification, handler
+registry, and built-in handlers.
+
+## Role
+
+`POST /events` dispatches batched client work to registered handlers. Handlers are
+**loss-tolerant** (errors logged, not raised to the client).
+
+**Canonical core event catalog** (shipped and planned `type` values, auth, dedup,
+side effects): `docs/domains/events/events.md` → **Core event catalog**.
+
+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`
+- `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
+
+## Flow
+
+1. Client obtains a token via `GET /events/token`
+1. Client posts via `POST /events` with `type`, `token`, and `events`
+1. Invalid token → early return (HTTP still 202)
+1. Registered handlers for `type` are queued on FastAPI `BackgroundTasks` and run **sequentially** after the response
+1. Unknown `type` → warning log, no handler run