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

core_framework-2.1.0/.cursor/rules/alembic-revision-ids.mdc → core_framework-2.3.0/.cursor/rules/alembic-migrations.mdc

@@ -1,14 +1,16 @@
 ---
-description: Alembic revision id format — short random hex, not descriptive slugs
+description: Alembic migrations — revision id format and index DDL conventions
 globs: alembic/**/alembic/versions/*.py
 alwaysApply: false
 ---
 
-# Alembic revision IDs
+# Alembic migrations
+
+## Revision IDs
 
 `alembic_version.version_num` is a **32-character** string. Revision ids must stay well under that limit.
 
-## New revisions (required)
+### New revisions (required)
 
 - Set `revision` to a **12-character lowercase hex** string (Alembic default), e.g. `a56bc6b7f799`.
 - Generate with `python -c "import secrets; print(secrets.token_hex(6))"` or `alembic revision`.
@@ -30,10 +32,29 @@ revision: str = "120bf6be81eb"
 revision: str = "post_tombstone_status_model"
 ```
 
-## Exceptions
+### Exceptions
 
 - Collapsed **`v1_*_init`** baseline revisions keep their stable names (`v1_post_init`, etc.) — do not rename shipped baselines.
 
-## Do not rename shipped revision ids
+### Do not rename shipped revision ids
 
 If a revision may already be applied in any environment, **do not** change its `revision` string. Add a forward migration instead.
+
+## Index DDL
+
+### New index migrations (required)
+
+In **`upgrade()`**, create indexes with **`IF NOT EXISTS`** so migrations succeed when an index was already applied manually in production:
+
+```python
+op.execute("""
+    create index if not exists idx_example_created_at
+    on example_table (created_at);
+""")
+```
+
+Use **`drop index if exists`** in **`downgrade()`**.
+
+### Do not retrofit index DDL
+
+Do **not** edit shipped migrations only to add `if not exists` — those revisions may already be applied. New forward migrations follow this rule; legacy `create index` without `if not exists` stays as-is.

{core_framework-2.1.0 → core_framework-2.3.0}/.cursor/rules/api-layer.mdc

@@ -6,7 +6,7 @@ globs:
 
 # API layer (core-framework)
 
-**Framework patterns:** use the **fastapi** skill (`.cursor/skills/fastapi/`) — `Annotated`, dependencies, routers, Pydantic v2, CLI.
+**Framework patterns:** use the **fastapi** skill (`.agents/skills/fastapi/`) — `Annotated`, dependencies, routers, Pydantic v2, CLI.
 
 **Validation:** **`api-validation.mdc`**. **Errors:** **`error-boundary.mdc`**. **Domain imports:** **`domain-imports.mdc`**.
 

{core_framework-2.1.0 → core_framework-2.3.0}/.cursor/rules/application-layer.mdc

@@ -18,7 +18,7 @@ Application services orchestrate use cases shared by API and workers. They stay
 
 - Return plain Python/domain values: `dict`, `list[dict]`, dataclasses, primitives, `None`, or empty collections.
 - Do not return API/Pydantic `BaseModel` instances.
-- Signal HTTP-meaningful failures with **`application.shared.exceptions`** or plain outcomes (`None`, empty), never typed domain exceptions. See **`error-boundary.mdc`**.
+- Signal HTTP-meaningful failures with **`application.shared.exceptions`** or plain outcomes (`None`, empty), never typed domain exceptions. Full boundary contract: **`error-boundary.mdc`**.
 
 Use a domain dataclass when one domain row matches the response shape; use a `dict` when the payload is composed from several sources.
 

{core_framework-2.1.0 → core_framework-2.3.0}/.cursor/rules/constitution.mdc

@@ -10,6 +10,7 @@ alwaysApply: true
 - State assumptions; ask when unclear. Prefer the simplest correct solution.
 - Touch only what the task requires. Match existing style. Remove orphans your edits create.
 - Define verifiable success criteria for non-trivial work.
+- **Inline small single-use helpers** — do not extract a private function used once and only a few lines (identifier quoting, a short SQL fragment, pass-through wrappers). Extract when the logic is **reused**, **~15+ lines / non-obvious branching**, or a scoped rule requires sharing (e.g. normal + `*_strong` repository reads in **`strong-reads.mdc`**). Do not repo-wide refactor unrelated existing helpers.
 
 ## Tech stack
 
@@ -25,7 +26,12 @@ Dependencies point inward: API/worker → application → domain. Never reverse.
 - **Application** — orchestration shared by API + worker; no FastAPI types.
 - **Domain** — models, repositories (Postgres only), services. No API/worker/application imports except wiring in `dependencies.py`.
 
-Path-scoped rules under `.cursor/rules/` add detail (API, domains, docs, etc.). For FastAPI/Pydantic work in `core_framework/api/`, use the **fastapi** skill (`.cursor/skills/fastapi/`).
+Path-scoped rules under `.cursor/rules/` add detail (API, domains, docs, etc.). For FastAPI/Pydantic work in `core_framework/api/`, use the **fastapi** skill (`.agents/skills/fastapi/`).
+
+## Agent skills
+
+- Package skills (for example **fastapi**) are Library Skills-managed symlinks under **`.agents/skills/<name>/`**. Rules and hand-authored skills reference that path, not a copied tree under **`.cursor/skills/`**.
+- **`.cursor/skills/<name>`** may symlink to **`.agents/skills/<name>`** for Cursor; Library Skills repairs **`.agents/skills`** links when packages move. After **`uv sync`** or a dependency upgrade, run **`uvx library-skills --yes`** if symlinks are stale.
 
 ## Host applications
 

{core_framework-2.1.0 → core_framework-2.3.0}/.cursor/rules/domain-caller-context.mdc

@@ -34,7 +34,7 @@ Domain layer names must describe domain concepts and data semantics, not who cal
   - `tombstone_post` ✅
   - `detach_post_authors_by_author_id` ✅
 - Prefer naming by data shape or business rule, not persona:
-  - `select_post_with_metadata_by_id` ✅
+  - `select_post_with_metadata_by_id_if_exists` ✅
   - `retrieve_user_for_detail` ✅
 - Keep caller-specific naming in API/application layers only.
 

{core_framework-2.1.0 → core_framework-2.3.0}/.cursor/rules/domain-imports.mdc

@@ -16,7 +16,7 @@ When importing from **`core_framework/domains/*`** in API or application code:
 
 ## Prohibited
 
-- Typed or base **domain exceptions** in API/application — use **`application.shared.exceptions`**.
+- Typed or base **domain exceptions** in API/application — use **`application.shared.exceptions`**. Full policy: **`error-boundary.mdc`**.
 - Direct imports from internal modules (`models`, `enums`, `repository`, `service`, `exceptions`).
 
 ```python
@@ -41,4 +41,4 @@ To see what a domain exports, check its **`__init__.py`** **`__all__`**.
 2. Raise an **application** exception when HTTP must signal failure.
 3. Extend the domain service API to absorb typed exceptions internally.
 
-Application code never imports repositories. Exception boundary details: **`error-boundary.mdc`**.
+Application code never imports repositories. Exception boundary: **`error-boundary.mdc`**.

{core_framework-2.1.0 → core_framework-2.3.0}/.cursor/rules/domain-repository-exceptions.mdc

@@ -6,15 +6,18 @@ globs:
 
 # Domain: repository exceptions vs service
 
+Canonical HTTP/application boundary: **`error-boundary.mdc`**. Application and API must not import or handle typed domain exceptions.
+
 ## Thin service + single persistence step
 
-When a **`Service`** method in **`core_framework/domains/*/service.py`** only performs **shared input guards** (e.g. **`require_*`**, **`validate_pagination_limit`**) **and** delegates to **one** repository call with **no branching** afterward, **prefer raising domain exceptions inside the repository** when the persistence outcome is an error condition (empty `RETURNING`, unexpected row absence on insert).
+When a **`Service`** method in **`core_framework/domains/*/service.py`** only performs **shared input guards** (e.g. **`require_*`**, **`validate_pagination_limit`**) **and** delegates to **one** repository call with **no branching** afterward, the repository may raise typed domain exceptions for persistence error outcomes (empty `RETURNING`, unexpected row absence on insert).
 
-The service stays a façade: validate arguments, then **`await`** the repository method and let **domain exceptions** propagate.
+That propagation is **intra-domain only**. Methods that **application** or **workers** call must **not** leak typed exceptions outward — absorb them inside the service (return **`None`**, outcomes, or **`bool`**) or branch before re-raising. See **`error-boundary.mdc`**.
 
 ## Prefer service-side translation when
 
 - The service **composes multiple** repository calls, **branches** on outcomes, or maps the same SQL outcome to **different domain errors**.
+- The method is an **application-callable** entrypoint (anything imported via **`dependencies.py`** and used from **`core_framework/application/`** or **`core_framework/api/`**).
 - Keeping the repository purely “data shaped” (**`Optional`** / **`bool`**) materially improves reuse or clarity for **multiple** service entrypoints calling the same repository method.
 
 Existing domains may mix both styles; use this guide for **new work** and when **refactoring** a call site for clarity.

{core_framework-2.1.0 → core_framework-2.3.0}/.cursor/rules/error-boundary.mdc

@@ -2,8 +2,9 @@
 description: HTTP error boundaries — application vs domain exceptions, handlers, anti-enumeration
 globs:
   - core_framework/core/exception_handlers/**/*.py
-  - core_framework/application/**/*_service.py
+  - core_framework/application/**/*.py
   - core_framework/api/**/router.py
+  - core_framework/api/**/schemas.py
   - core_framework/domains/**/exceptions.py
 ---
 
@@ -15,7 +16,7 @@ Platform contract: **`docs/platform/client-error-visibility.md`**. Domain import
 
 | Layer | Outward errors | HTTP |
 |-------|----------------|------|
-| **Application** | **`application.shared.exceptions`** | Handlers map type → status + `detail` |
+| **Application** | **`application.shared.exceptions`**, **`InvalidPageTokenError`** | Handlers map type → 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** |
@@ -30,7 +31,7 @@ Platform contract: **`docs/platform/client-error-visibility.md`**. Domain import
 ## Handler registration
 
 - Use **`register_exception_handler`** from **`core_framework.core.exception_handlers.common`** — not raw **`app.add_exception_handler`** elsewhere.
-- **`setup.py`**: application types (specific before any base), **`DomainValidationError`**, one **`BaseDomainException`** leak handler, then **`Exception`** unmapped.
+- Register handlers in **`core_framework/core/exception_handlers/setup.py`** and **`application.py`**: application types (specific before any base), **`InvalidPageTokenError`**, **`DomainValidationError`**, one **`BaseDomainException`** leak handler, then **`Exception`** unmapped.
 - No per-domain handler modules for typed exceptions. Handlers translate only — no business logic or repository calls.
 - Do not log **error** for expected application 4xx; **`DomainValidationError`** at **warning**/**info**.
 

{core_framework-2.1.0 → core_framework-2.3.0}/.cursor/rules/layer-boundaries.mdc

@@ -18,7 +18,7 @@ Dependencies point inward: **API/worker → application → domain**. Never reve
 
 ## Cross-layer rules
 
-- Worker code must not import `core_framework.domains` directly, except documented housekeeping cron handlers that call a configured domain facade.
+- Worker code must not import `core_framework.domains` directly; call **application** services from worker tasks and schedules.
 - Domain code imports global infrastructure only in `dependencies.py`.
 - Repositories are Postgres-only and must not query other domains' schemas. See **`repository-schema-isolation`**.
 - Non-SQL I/O uses domain ports/components plus infrastructure adapters. See **`domain-services-and-adapters`**.

{core_framework-2.1.0 → core_framework-2.3.0}/.cursor/rules/strong-reads.mdc

@@ -4,7 +4,7 @@ globs:
   - core_framework/domains/**/repository.py
   - core_framework/domains/**/service.py
   - core_framework/domains/**/dependencies.py
-  - core_framework/application/**/*_service.py
+  - core_framework/application/**/*.py
 ---
 
 # Strong reads
@@ -13,6 +13,7 @@ globs:
 
 - **Read-after-write** in the same HTTP request or worker job → **strong** read (required). Refetch with `strong_read_database`, `*_strong` repository methods, or service accessors that call them.
 - **Decision-critical guards** where stale data can cause incorrect branching → **strong** read (required). These are reads performed to decide a branch (for example pre-write existence, role, or state checks that determine whether a write runs or which outcome is returned), even when there is no immediate prior write in the flow. See the "Read Consistency (Strong vs Normal Reads)" ADR.
+- **Accepted exception:** **`check_not_banned`** / **`get_user_detail`** (`USER_DETAIL` cache + normal reads) — ban visibility is eventually consistent by design. See **`docs/platform/architecture-decisions.md`** → *Ban enforcement via cached `USER_DETAIL` is eventually consistent*. Do not flag as a strong-read defect unless that ADR is updated.
 - **All other strong-read usage** (e.g., list/browse freshness) → opt-in unless the user explicitly requested it in the task.
 - If a flow writes then reads and only a normal-read API exists, add or extend the `*_strong` path and call it from that flow.
 - Repositories accept `strong_read_database: Postgres` on `__init__` for wiring symmetry even when unused.
@@ -21,9 +22,8 @@ globs:
 
 - Normal reads: explicit methods (e.g. `select_appeal`) using `read_database`.
 - Strong reads: separate methods only where needed (e.g. `select_appeal_strong`) using `strong_read_database`.
-- Share one private helper that accepts a database handle — do not duplicate SQL or mapping.
-- If only strong-read behavior is needed today, use a single method with `_strong` in the name.
-- Service accessors that call strong repository methods should also include `_strong`.
+- Share one private helper that accepts a database handle when **both** normal and strong public methods exist — do not duplicate SQL or mapping. If only a `*_strong` method exists today, keep SQL inline in that method (constitution → inline small single-use helpers).
+- Service accessors that call strong repository methods should use **`retrieve_*_strong`** naming (repositories keep **`select_*_strong`**).
 
 ```python
 # Preferred

{core_framework-2.1.0 → core_framework-2.3.0}/.cursor/skills/add-domain/SKILL.md

@@ -192,7 +192,7 @@ Worker `startup` and API `init_app` already call `configure_application_dependen
 
 Do this in a **separate step/PR** when you have DDL to apply.
 
-1. Add **`alembic/<domain>/alembic/versions/*.py`** (at least one revision); `upgrade()` may create schema/tables/enums as designed. Use a **12-character lowercase hex** `revision` id (see **`alembic-revision-ids`**); put the descriptive slug in the filename only.
+1. Add **`alembic/<domain>/alembic/versions/*.py`** (at least one revision); `upgrade()` may create schema/tables/enums as designed. Use a **12-character lowercase hex** `revision` id (see **`alembic-migrations`**); put the descriptive slug in the filename only.
 1. **Append** `<domain>` to `ALEMBIC_DOMAINS` in `core_framework/bundled_alembic.py` **in the same change** as the first revision (so `cf-alembic` / CI stay green).
 1. `make alembic` and deploy’s `cf-alembic` step pick up the new domain automatically — no makefile or `_deploy.yml` edits needed.
 

{core_framework-2.1.0 → core_framework-2.3.0}/.cursor/skills/code-review/SKILL.md

@@ -25,7 +25,7 @@ Do **not** flag documented accepted trade-offs in **`docs/platform/architecture-
 ## Quick checks
 
 - Application services: no HTTP types, no domain exceptions, no Pydantic return types, one-line docstrings.
-- API: thin routers, validation in schemas, orchestration in application — **fastapi** skill + **`api-layer`** / **`api-validation`** / **`error-boundary`** rules.
+- API: thin routers, validation in schemas, orchestration in application — **fastapi** skill (`.agents/skills/fastapi/`) + **`api-layer`** / **`api-validation`** / **`error-boundary`** rules.
 - Domain: imports only via **`__init__.py`** / **`dependencies`** from outer layers; no caller-context names (**`domain-caller-context`**).
 - Read-after-write refetches use **`*_strong`** where applicable.
 

{core_framework-2.1.0 → core_framework-2.3.0}/.cursor/skills/implement-feature/SKILL.md

@@ -24,7 +24,7 @@ Implement **one step at a time**. Stop after each step and wait for user review.
 After the user accepts database changes (or if there were none):
 
 - **Only** implement the API layer: schemas and router.
-- Follow the **fastapi** skill and **`api-layer`** / **`api-validation`** / **`error-boundary`** rules.
+- 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.

{core_framework-2.1.0 → core_framework-2.3.0}/.github/workflows/_deploy.yml

@@ -55,10 +55,13 @@ jobs:
           IMAGE_SERVER_PORT: ${{ vars.IMAGE_SERVER_PORT }}
           IMAGE_SERVER_USER: ${{ vars.IMAGE_SERVER_USER }}
           LOGFIRE_TOKEN: ${{ secrets.LOGFIRE_TOKEN }}
+          OBSERVABILITY_ENABLED: ${{ vars.OBSERVABILITY_ENABLED }}
           PROFILING_KEY: ${{ vars.PROFILING_KEY }}
           PROFILING_ENABLED: ${{ vars.PROFILING_ENABLED }}
           LOG_LEVEL: ${{ vars.LOG_LEVEL }}
           CORS_ALLOWED_ORIGINS: ${{ vars.CORS_ALLOWED_ORIGINS }}
+          RETENTION_POST_VIEWS_DAYS: ${{ vars.RETENTION_POST_VIEWS_DAYS }}
+          ANALYTICS_REFRESH_INTERVAL_SECONDS: ${{ vars.ANALYTICS_REFRESH_INTERVAL_SECONDS }}
         run: |
           set -euo pipefail
 

{core_framework-2.1.0 → core_framework-2.3.0}/.github/workflows/test.yaml

@@ -32,19 +32,14 @@ jobs:
         run: uv run ruff check
 
       - name: Install Firebase CLI
-        run: npm install -g firebase-tools
-
-      - name: Start Firebase Emulator
-        run: |
-          firebase emulators:start --only auth --project=test &
-          sleep 5
-        env:
-          FIREBASE_AUTH_EMULATOR_HOST: localhost:9099
+        run: npm install -g firebase-tools@15.20.0
 
       - name: pytest
-        run: uv run pytest tests/unit tests/integration -n 2
+        run: |
+          firebase --version
+          uv run pytest tests/unit tests/integration -n 2
         env:
-          FIREBASE_AUTH_EMULATOR_HOST: localhost:9099
+          FIREBASE_AUTH_EMULATOR_HOST: 127.0.0.1:9099
 
   package-smoke:
     runs-on: ubuntu-latest

{core_framework-2.1.0 → core_framework-2.3.0}/CHANGELOG.md

@@ -4,6 +4,56 @@ Notable changes to **core-framework** (import **`core_framework`**). Format foll
 
 ## [Unreleased]
 
+## [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 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.
+- **Analytics rollup (Phase 5):** admin read API — `GET /admin/analytics/daily/range` and `GET /admin/analytics/daily/day` via `read_service` and Phase 2 domain read helpers.
+- **Analytics rollup (Phase 6):** one-year `daily_fact` retention prune (`schedule_prune_analytics_daily_facts`, daily **05:10 UTC**); `idx_daily_fact_day` migration. Source-feed `created_at` indexes for refresh counts already exist on `posts`, `comments`, `users`, and `post_views`.
+- **Analytics rollup (Phase 7):** integration tests for refresh planner/executor, admin read API, and retention prune.
+
+### Breaking
+
+- **Breaking (hosts — config):** Add **`[analytics]`** with **`refresh_interval_seconds`** (required on **`Settings`**; core **`config.toml`** ships **300**). Deploy variable **`ANALYTICS_REFRESH_INTERVAL_SECONDS`**. Add **`schema_analytics`** under **`[postgres_schemas]`** (default **`analytics`**).
+- **Breaking (hosts — migration):** When upgrading to a release that includes analytics rollup, run **`cf-alembic`** so the **`analytics`** migration stream applies **`analytics_daily_fact`** (`analytics.daily_fact`) and **`analytics_daily_fact_day_index`** (`idx_daily_fact_day`). The worker must run **`schedule_refresh_analytics`** and **`schedule_prune_analytics_daily_facts`** (registered in core worker schedules) for rollup materialization and one-year retention prune.
+
+## [2.2.0] - 2026-06-30
+
+Transactional outbox (block, follow, restriction), post views retention, and incremental view-count aggregation. Hosts must update **`config.toml`**, run **`cf-alembic`**, and run the worker for mirror fanout and retention jobs.
+
+### 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 (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`**.
+
+### Fixed
+
+- **Appeal approval retry:** Same-decision retries on already-approved appeals re-run `clear_user_restriction` instead of returning **400**, recovering when restriction removal failed after the appeal was persisted.
+- **Worker staging sweeps:** Avatar and banner stale-staging cron schedules call **`sweep_*_staging_housekeeping`** application entrypoints instead of domain dependencies directly.
+
+### Changed
+
+- **Post stats aggregation:** **`view_count`** is maintained incrementally from **`post_views`** since the last high-water mark instead of a full **`count(*)`** per run; tombstone resets clear **`view_count_aggregated_up_to`**.
+
+### Breaking
+
+- **Breaking (hosts — config):** When upgrading to a release that includes the outbox block pilot, update **`config.toml`** (and deploy templates) before startup:
+  - Rename **`[http-client]`** → **`[http_client]`** (field name on **`Settings`** is now **`http_client`** with no hyphen alias).
+  - Add **`[outbox]`** with **`min_connections`** and **`max_connections`** (defaults in core **`config.toml.template`**: **2** / **12**). The outbox pool is opened only by the **worker** process (and test workers via **`create_worker_settings_for_shared_runtime`**), not the API lifespan.
+  - Run **`cf-alembic`** so the **`user`** migration stream applies **`user_add_event_outbox`** (`"user".event_outbox`).
+  - Hosts that only run the API (no worker) still need **`[outbox]`** in config because **`Settings`** requires it; the API does not connect that pool.
+- **Breaking (hosts — migration):** When upgrading to a release that includes restriction outbox (Phase 3), run **`cf-alembic`** so the **`moderation`** migration stream applies **`moderation_add_event_outbox`** (`moderation.event_outbox`). The worker must run **`schedule_poll_moderation_outbox`** (registered in core worker schedules) for durable restriction mirror fanout.
+- **Breaking (hosts — config):** Add **`[retention]`** with **`post_views_retention_days`** (default **90**). Deploy variable **`RETENTION_POST_VIEWS_DAYS`**. Hosts that subclass **`Settings`** may extend **`RetentionConfig`** with additional retention keys (for example calculator views on Henry).
+- **Breaking (hosts — migration):** When upgrading to a release that includes post views retention, run **`cf-alembic`** so the **`post`** migration stream applies **`post_post_views_retention_high_water_mark`** (`post_stats.view_count_aggregated_up_to`, **`post_views`** retention indexes, backfill). The worker must run **`schedule_prune_post_views`** (registered in core worker schedules) for age-based **`post_views`** pruning.
+
 ## [2.1.0] - 2026-06-25
 
 Dependency and tooling refresh. No API, schema, or host config changes — bump the package and redeploy; no **`cf-alembic`** step.
@@ -349,4 +399,5 @@ First **SemVer-stable** release per **`docs/library/package-api.md`**.
 [1.8.1]: https://github.com/NepNepFFXIV/core-framework/compare/v1.8.0...v1.8.1
 [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
-[unreleased]: https://github.com/NepNepFFXIV/core-framework/compare/v2.1.0...HEAD
+[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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: core-framework
-Version: 2.1.0
+Version: 2.3.0
 Summary: Core framework package (import as core_framework)
 Project-URL: Homepage, https://github.com/NepNepFFXIV/core-framework
 Project-URL: Repository, https://github.com/NepNepFFXIV/core-framework

core_framework-2.3.0/alembic/analytics/alembic/env.py

@@ -0,0 +1,74 @@
+import asyncio
+from logging.config import fileConfig
+
+from sqlalchemy import pool, text
+from sqlalchemy.engine import Connection
+from sqlalchemy.ext.asyncio import async_engine_from_config
+
+from alembic import context
+from core_framework.core.settings import load_default_settings
+
+settings = load_default_settings()
+
+config = context.config
+
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+target_metadata = None
+
+config.set_main_option("sqlalchemy.url", settings.write_postgres.alembic_postgres_url)
+
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode."""
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    quoted_schema_name = f'"{settings.postgres_schemas.schema_analytics.replace('"', '""')}"'
+
+    with context.begin_transaction():
+        context.execute(text(f"set search_path to {quoted_schema_name}"))
+        context.run_migrations()
+
+
+def do_run_migrations(connection: Connection) -> None:
+    quoted_schema_name = f'"{settings.postgres_schemas.schema_analytics.replace('"', '""')}"'
+
+    connection.execute(text(f"create schema if not exists {quoted_schema_name}"))
+    connection.execute(text(f"set search_path to {quoted_schema_name}"))
+    connection.commit()
+
+    context.configure(connection=connection, target_metadata=target_metadata)
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_async_migrations() -> None:
+    """Run migrations in 'online' mode."""
+    connectable = async_engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+
+    await connectable.dispose()
+
+
+def run_migrations_online() -> None:
+    asyncio.run(run_async_migrations())
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

core_framework-2.3.0/alembic/analytics/alembic/versions/5b9ac98bb150_analytics_daily_fact.py

@@ -0,0 +1,33 @@
+"""analytics daily_fact
+
+Revision ID: 5b9ac98bb150
+Revises:
+Create Date: 2026-07-01 12:00:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "5b9ac98bb150"
+down_revision: str | Sequence[str] | None = None
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        create table daily_fact (
+            subject_type   text   not null,
+            activity_type  text   not null,
+            day            date   not null,
+            kind           text   not null default '',
+            count          bigint not null default 0,
+            primary key (subject_type, activity_type, day, kind)
+        );
+    """)
+
+
+def downgrade() -> None:
+    op.execute("drop table if exists daily_fact;")

core_framework-2.3.0/alembic/analytics/alembic/versions/7f2a9c1d4e8b_analytics_daily_fact_day_index.py

@@ -0,0 +1,27 @@
+"""analytics daily_fact day index for retention prune
+
+Revision ID: 7f2a9c1d4e8b
+Revises: 5b9ac98bb150
+Create Date: 2026-07-02 12:00:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "7f2a9c1d4e8b"
+down_revision: str | Sequence[str] | None = "5b9ac98bb150"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        create index if not exists idx_daily_fact_day
+        on daily_fact (day);
+    """)
+
+
+def downgrade() -> None:
+    op.execute("drop index if exists idx_daily_fact_day;")

core_framework-2.3.0/alembic/moderation/alembic/versions/moderation_add_event_outbox.py

@@ -0,0 +1,52 @@
+"""add event_outbox table for transactional outbox
+
+Revision ID: 3a8e61ac8ae2
+Revises: v1_mod_init
+Create Date: 2026-06-27 12:00:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "3a8e61ac8ae2"
+down_revision: str | Sequence[str] | None = "v1_mod_init"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        create table event_outbox (
+            id bigint generated always as identity primary key,
+            created_at timestamptz not null default now(),
+            event_name text not null,
+            payload jsonb not null,
+            payload_version smallint not null default 1,
+            idempotency_key text not null,
+            aggregate_type text not null,
+            aggregate_id text not null,
+            status text not null default 'pending',
+            available_at timestamptz not null default now(),
+            attempt_count integer not null default 0,
+            failure_count integer not null default 0,
+            locked_at timestamptz,
+            locked_by text,
+            last_error text,
+            metadata jsonb,
+            constraint event_outbox_idempotency_key_unique unique (idempotency_key),
+            constraint event_outbox_status_valid
+                check (status in ('pending', 'processing', 'done', 'dead'))
+        );
+    """)
+
+    op.execute("""
+        create index idx_event_outbox_pending_available
+            on event_outbox (available_at, id)
+            where status = 'pending';
+    """)
+
+
+def downgrade() -> None:
+    op.execute("drop table if exists event_outbox;")

core_framework-2.3.0/alembic/moderation/alembic/versions/moderation_add_event_outbox_dead_indexes.py

@@ -0,0 +1,34 @@
+"""add dead-row partial indexes on event_outbox for admin ops
+
+Revision ID: de7c41fba3e8
+Revises: 3a8e61ac8ae2
+Create Date: 2026-06-28 12:00:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "de7c41fba3e8"
+down_revision: str | Sequence[str] | None = "3a8e61ac8ae2"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        create index idx_event_outbox_dead_created_at
+            on event_outbox (created_at desc, id)
+            where status = 'dead';
+    """)
+    op.execute("""
+        create index idx_event_outbox_dead_event_created
+            on event_outbox (event_name, created_at)
+            where status = 'dead';
+    """)
+
+
+def downgrade() -> None:
+    op.execute("drop index if exists idx_event_outbox_dead_event_created;")
+    op.execute("drop index if exists idx_event_outbox_dead_created_at;")

core_framework-2.3.0/alembic/moderation/alembic/versions/moderation_add_event_outbox_pending_created_at_index.py

@@ -0,0 +1,28 @@
+"""add pending created_at partial index on event_outbox for admin oldest-pending
+
+Revision ID: cf840f06eff3
+Revises: de7c41fba3e8
+Create Date: 2026-06-29 12:00:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "cf840f06eff3"
+down_revision: str | Sequence[str] | None = "de7c41fba3e8"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        create index idx_event_outbox_pending_created_at
+            on event_outbox (created_at, id)
+            where status = 'pending';
+    """)
+
+
+def downgrade() -> None:
+    op.execute("drop index if exists idx_event_outbox_pending_created_at;")