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

{core_framework-2.1.0 → core_framework-2.2.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.2.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.2.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.2.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.2.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.2.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.2.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.2.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.2.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.2.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.2.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.2.0}/.github/workflows/_deploy.yml

@@ -55,10 +55,12 @@ 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 }}
         run: |
           set -euo pipefail
 

{core_framework-2.1.0 → core_framework-2.2.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.2.0}/CHANGELOG.md

@@ -4,6 +4,37 @@ Notable changes to **core-framework** (import **`core_framework`**). Format foll
 
 ## [Unreleased]
 
+## [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 +380,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.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: core-framework
-Version: 2.1.0
+Version: 2.2.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.2.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.2.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.2.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;")

core_framework-2.2.0/alembic/post/alembic/versions/post_post_views_retention_high_water_mark.py

@@ -0,0 +1,64 @@
+"""post_views retention: view_count_aggregated_up_to and created_at indexes
+
+Revision ID: 1602f054c545
+Revises: 10849f6f72ff
+Create Date: 2026-06-30 12:00:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "1602f054c545"
+down_revision: str | Sequence[str] | None = "10849f6f72ff"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        alter table post_stats
+        add column view_count_aggregated_up_to timestamptz;
+    """)
+
+    op.execute("""
+        update post_stats ps
+        set view_count = sub.cnt
+        from (
+            select post_id, count(*)::bigint as cnt
+            from post_views
+            group by post_id
+        ) sub
+        where ps.post_id = sub.post_id;
+    """)
+
+    op.execute("""
+        update post_stats ps
+        set view_count_aggregated_up_to = sub.max_created_at
+        from (
+            select post_id, max(created_at) as max_created_at
+            from post_views
+            group by post_id
+        ) sub
+        where ps.post_id = sub.post_id;
+    """)
+
+    op.execute("""
+        create index idx_post_views_created_at
+        on post_views (created_at);
+    """)
+
+    op.execute("""
+        create index idx_post_views_post_created_at
+        on post_views (post_id, created_at desc);
+    """)
+
+
+def downgrade() -> None:
+    op.execute("drop index if exists idx_post_views_post_created_at")
+    op.execute("drop index if exists idx_post_views_created_at")
+    op.execute("""
+        alter table post_stats
+        drop column if exists view_count_aggregated_up_to;
+    """)

core_framework-2.2.0/alembic/user/alembic/versions/user_add_event_outbox.py

@@ -0,0 +1,52 @@
+"""add event_outbox table for transactional outbox
+
+Revision ID: 5f7110e39a55
+Revises: 946c8f297876
+Create Date: 2026-06-27 12:00:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "5f7110e39a55"
+down_revision: str | Sequence[str] | None = "946c8f297876"
+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.2.0/alembic/user/alembic/versions/user_add_event_outbox_dead_indexes.py

@@ -0,0 +1,34 @@
+"""add dead-row partial indexes on event_outbox for admin ops
+
+Revision ID: d528956664b9
+Revises: 5f7110e39a55
+Create Date: 2026-06-28 12:00:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "d528956664b9"
+down_revision: str | Sequence[str] | None = "5f7110e39a55"
+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.2.0/alembic/user/alembic/versions/user_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: 9d9611e47ce2
+Revises: d528956664b9
+Create Date: 2026-06-29 12:00:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "9d9611e47ce2"
+down_revision: str | Sequence[str] | None = "d528956664b9"
+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;")

{core_framework-2.1.0 → core_framework-2.2.0}/config.toml

@@ -79,7 +79,7 @@ allowed_headers = [
     "Profiling-Key",
 ]
 
-[http-client]
+[http_client]
 timeout = 5.0
 max_connections = 100
 max_keepalive_connections = 10
@@ -102,6 +102,17 @@ db_name = "postgres"
 min_connections = 8
 max_connections = 15
 
+[outbox]
+min_connections = 2
+max_connections = 4
+
+[worker]
+max_jobs = 10
+max_tries = 2
+
+[retention]
+post_views_retention_days = 90
+
 [postgres_schemas]
 schema_extension = "extension"
 schema_user = "user"

{core_framework-2.1.0 → core_framework-2.2.0}/config.toml.template

@@ -39,7 +39,7 @@ connect_timeout = 30.0
 level = "$LOG_LEVEL"
 
 [observability]
-enabled = true
+enabled = $OBSERVABILITY_ENABLED
 logfire_token = "$LOGFIRE_TOKEN"
 profiling_enabled = $PROFILING_ENABLED
 profiling_key = "$PROFILING_KEY"
@@ -63,7 +63,7 @@ allowed_headers = [
     "Profiling-Key",
 ]
 
-[http-client]
+[http_client]
 timeout = 5.0
 max_connections = 100
 max_keepalive_connections = 10
@@ -86,6 +86,17 @@ db_name = "$READ_POSTGRES_DB"
 min_connections = 8
 max_connections = 15
 
+[outbox]
+min_connections = 2
+max_connections = 4
+
+[worker]
+max_jobs = 10
+max_tries = 2
+
+[retention]
+post_views_retention_days = $RETENTION_POST_VIEWS_DAYS
+
 [postgres_schemas]
 schema_extension = "extension"
 schema_user = "user"