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

{core_framework-2.3.0 → core_framework-2.3.2}/.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.0 → core_framework-2.3.2}/.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.0 → core_framework-2.3.2}/.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.0 → core_framework-2.3.2}/.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.0 → core_framework-2.3.2}/.cursor/rules/postgres-config-conventions.mdc

@@ -45,3 +45,12 @@ Use explicit write/read configuration and keep schema names shared.
   - `read_postgres`
 - Domain dependencies pass `(write, read, strong)` explicitly to repositories.
 - Until a dedicated strong instance exists, use write instance for the strong argument intentionally.
+
+## Schema names in SQL
+
+- Schema names come only from `settings.postgres_schemas` (see **Settings Model** above).
+- Domain `dependencies.py` passes unquoted `schema=runtime.settings.postgres_schemas.schema_<domain>` into repositories (keyword-only `__init__`).
+- Repositories cache `self.schema_sql = quote_postgres_identifier(schema)` and use `{self.schema_sql}.table` in f-string SQL — never hard-coded `"post".` literals.
+- Outbox producer adapter is wired per domain with `schema` at construction; consumer adapter receives unquoted `schema` per call and caches quoted SQL.
+
+Repository isolation rules (no cross-domain schema access): **`repository-schema-isolation.mdc`**.

{core_framework-2.3.0 → core_framework-2.3.2}/.cursor/rules/repository-schema-isolation.mdc

@@ -11,10 +11,19 @@ Each domain repository may only read/write tables in **its own** Postgres schema
 
 Canonical rule: `docs/platform/layers-and-boundaries.md` — *no cross-domain schema reads, writes, joins, or foreign keys*.
 
+## Schema qualification
+
+Repositories receive unquoted `schema` from `runtime.settings.postgres_schemas` in `dependencies.py` (keyword-only `__init__` arg). In `__init__`:
+
+- `self.schema` — config schema name (e.g. `post`)
+- `self.schema_sql` — `quote_postgres_identifier(schema)` for SQL interpolation
+
+Use `{self.schema_sql}.table` in f-string SQL — not hard-coded `"post".` literals.
+
 ## Allowed in a repository
 
-- SQL qualified with that domain's schema only (e.g. `"post".posts` in `PostRepository`).
-- **Within-schema** policy gates (e.g. `insert_post_like` checks `"post".posts.status = active`).
+- SQL qualified with that domain's schema only (e.g. `{self.schema_sql}.posts` in `PostRepository`).
+- **Within-schema** policy gates (e.g. `insert_post_like` checks `{self.schema_sql}.posts.status = active`).
 - **Lookup mirrors** in the same schema (`user_blocks_lookup`, `user_restrictions_lookup`, `user_followers_lookup`) — synced by application flows; mirrors are not authoritative.
 
 ## Forbidden in a repository
@@ -23,18 +32,18 @@ Canonical rule: `docs/platform/layers-and-boundaries.md` — *no cross-domain sc
 - Importing another domain's `service`, `repository`, or models to enforce policy.
 
 ```python
-# ❌ moderation/repository.py — cross-domain EXISTS
-insert into "moderation".post_reports (...)
+# ❌ moderation/repository.py — cross-domain EXISTS (illustrative schema literals)
+insert into {moderation_schema_sql}.post_reports (...)
 select $1, $2, $3, $4
 where exists (
-    select 1 from "post".posts
+    select 1 from {post_schema_sql}.posts
     where id = $2 and status = 'active'
 )
 
 # ❌ notification/repository.py — cross-domain mute gate
-insert into "notification".notification_mutes (...)
+insert into {notification_schema_sql}.notification_mutes (...)
 select ...
-where exists (select 1 from "comment".comments where ...)
+where exists (select 1 from {comment_schema_sql}.comments where ...)
 ```
 
 ## Alembic migrations (different convention)
@@ -69,4 +78,8 @@ Before adding a repository write that depends on another domain's row state:
 
 ## Self-check (repositories only)
 
-In `domains/<name>/repository.py`, every `"<schema>".` qualifier in SQL must be `<name>` (or that domain's documented mirror tables in the same schema).
+In `domains/<name>/repository.py`:
+
+- Every table/type qualifier in SQL must use `{self.schema_sql}.…` (that domain's schema only).
+- Do not hard-code `"user".`, `"post".`, etc. — use `self.schema` / `self.schema_sql` from config.
+- Mirror lookup tables (`user_blocks_lookup`, etc.) still live under `{self.schema_sql}` when they belong to that domain's schema.

{core_framework-2.3.0 → core_framework-2.3.2}/.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.2/.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.0 → core_framework-2.3.2}/.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.0 → core_framework-2.3.2}/.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.0 → core_framework-2.3.2}/CHANGELOG.md

@@ -4,13 +4,45 @@ Notable changes to **core-framework** (import **`core_framework`**). Format foll
 
 ## [Unreleased]
 
+## [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
+
+- **Partial admin user deletions:** `tombstone_authored_posts_only` and `tombstone_authored_comments_only` on `POST /admin/users/{user_id}/deletions` — moderator tombstone of authored posts or comments while keeping the account. See **`docs/domains/deletion/users.md`**.
+- **`docs/testing.md`** — usage-focused pytest plugin guide for host adopters (wiring, fixtures, tiers, troubleshooting). Design reference remains **`docs/library/testing-plugin-design.md`**.
+- **Post/comment attachment integration tests:** v1.1 create/edit coverage — best-effort attach (unknown or already-linked assets), attach before worker publish, edit-budget enforcement, clear-all patch, and tombstone finals cleanup. See **`tests/integration/api/posts/post_attachments_integration_test.py`** and **`tests/integration/api/comments/comment_attachments_integration_test.py`**.
+- **Analytics rollup:** `retrieve_daily_fact_kind_totals_for_range` on `AnalyticsService` and `retrieve_analytics_kind_totals_for_range` in `application/analytics/read_service` — sum `daily_fact` counts per `kind` over an inclusive UTC day range (for host catalog and similar reads).
+
+### Fixed
+
+- **Admin outbox schemas:** rename response field `schema` to `producing_schema` with JSON alias `schema` so Pydantic no longer warns about shadowing `BaseModel.schema`.
+
 ## [2.3.0] - 2026-07-03
 
 Analytics rollup domain (materialized daily activity counts), admin read API, and retention prune. Hosts must add **`[analytics]`** and **`schema_analytics`**, run **`cf-alembic`**, and run the worker for rollup refresh and daily-fact prune.
 
 ### 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.
@@ -30,7 +62,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`**.
 
@@ -75,7 +107,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.
 
@@ -136,7 +168,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
 
@@ -400,4 +432,7 @@ 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
+[unreleased]: https://github.com/NepNepFFXIV/core-framework/compare/v2.3.2...HEAD

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: core-framework
-Version: 2.3.0
+Version: 2.3.2
 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.0 → core_framework-2.3.2}/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.2/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.2/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.0 → core_framework-2.3.2}/config.toml

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

{core_framework-2.3.0 → core_framework-2.3.2}/config.toml.template

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

{core_framework-2.3.0 → core_framework-2.3.2}/core_framework/api/admin/outbox/schemas.py

@@ -2,7 +2,7 @@ from datetime import datetime
 from typing import Annotated, Any
 
 from fastapi import Path, Query
-from pydantic import BaseModel
+from pydantic import BaseModel, ConfigDict, Field
 
 OutboxRowId = Annotated[
     int,
@@ -34,7 +34,9 @@ class OutboxOldestPendingRow(BaseModel):
 
 
 class OutboxSummaryResponse(BaseModel):
-    schema: str
+    model_config = ConfigDict(populate_by_name=True)
+
+    producing_schema: str = Field(alias="schema")
     total_pending: int
     total_dead: int
     pending_by_event: list[OutboxEventCountItem]
@@ -43,8 +45,10 @@ class OutboxSummaryResponse(BaseModel):
 
 
 class OutboxDeadRowResponse(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
     id: int
-    schema: str
+    producing_schema: str = Field(alias="schema")
     event_name: str
     aggregate_type: str
     aggregate_id: str

{core_framework-2.3.0 → core_framework-2.3.2}/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.0 → core_framework-2.3.2}/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.0 → core_framework-2.3.2}/core_framework/application/analytics/read_service.py

@@ -27,6 +27,31 @@ async def retrieve_analytics_daily_range(
     }
 
 
+async def retrieve_analytics_kind_totals_for_range(
+    *,
+    subject_type: str,
+    activity_type: str,
+    from_day: date,
+    to_day: date,
+    kind: str | None = None,
+) -> dict[str, Any]:
+    """Return per-kind rollup totals summed over an inclusive UTC day range."""
+    totals = await analytics_deps.analytics_service.retrieve_daily_fact_kind_totals_for_range(
+        subject_type=subject_type,
+        activity_type=activity_type,
+        from_day=from_day,
+        to_day=to_day,
+        kind=kind,
+    )
+    return {
+        "subject_type": subject_type,
+        "activity_type": activity_type,
+        "from_day": from_day,
+        "to_day": to_day,
+        "items": [{"kind": total.kind, "count": total.count} for total in totals],
+    }
+
+
 async def retrieve_analytics_daily_day(
     *,
     subject_type: str,