Merge branch 'main' into worktree-messaging-platform

# Conflicts:
#	src/config/spotbugs/exclude.xml

infra/jpa/postgres/README.md

@@ -0,0 +1,39 @@
+# infra/jpa/postgres
+
+Server-side settings the JPA platform's contracts assume, and why each one matters.
+
+The contract suites start their own containers through
+`dev.caskeleton.adapter.outbound.persistence.testkit.postgresql.PostgreSqlContainerFactory`, so
+nothing here is needed to run them. This directory records what a *deployed* PostgreSQL has to look
+like for the platform's guarantees to hold, because several of them are server settings rather than
+application code.
+
+## Settings the platform depends on
+
+| Setting | Why the platform cares |
+|---|---|
+| `statement_timeout` | The last bound on a runaway statement. The platform sets transaction timeouts, but a single statement inside a transaction can still outlive the request that asked for it. |
+| `idle_in_transaction_session_timeout` | An idle open transaction holds its locks and its snapshot indefinitely, which blocks writers and prevents vacuum. This is what turns "someone left a transaction open" into a bounded incident. |
+| `lock_timeout` | A cluster-wide floor under the per-request lock bounds in `PostgreSqlLockOptions`. |
+| `max_connections` | The number `app.jpa-platform.datasource.maximum-pool-size` must be sized against — across every instance, and allowing for `REQUIRES_NEW` taking a second connection while pinning the first. |
+| `default_transaction_isolation` | Left at `read committed`. The platform selects `repeatable read` or `serializable` per transaction profile; changing the default would silently change every transaction that did not ask. |
+
+## Suggested baseline
+
+```conf
+statement_timeout = '30s'
+idle_in_transaction_session_timeout = '60s'
+lock_timeout = '10s'
+default_transaction_isolation = 'read committed'
+```
+
+These are starting points, not recommendations: the right `statement_timeout` depends on the
+slowest legitimate query in the application, and setting it below that turns a working report into
+an error. Measure before pinning.
+
+## What is deliberately not configured here
+
+- **Roles.** Credential separation lives in [`../roles/runtime-roles.sql`](../roles/runtime-roles.sql).
+- **Schema.** Flyway owns it (design §31). Nothing in this directory creates a table.
+- **Extensions.** The platform's PostgreSQL support — JSONB, arrays, ranges, `SKIP LOCKED`,
+  `ON CONFLICT` — is all core PostgreSQL. No extension is required, and none should be assumed.

infra/jpa/roles/runtime-roles.sql

@@ -0,0 +1,54 @@
+-- Runtime / migration / admin credential separation for the JPA persistence platform.
+-- Design §36; enforced at startup by PostgreSqlRuntimeRoleVerifier + DatabaseRolePolicy.
+--
+-- The separation is what makes "Flyway owns schema change" enforceable rather than aspirational.
+-- If the application's own credential cannot execute DDL, then no code path, no library, and no
+-- injected statement can alter the schema at runtime — regardless of what the application intended.
+--
+-- Run as a superuser once per database. Replace the placeholder passwords with values from the
+-- deployment's secret store; they are intentionally not committed.
+
+-- 1. The schema the application owns. Owned by the migration role, not the runtime role.
+create schema if not exists app authorization app_migration;
+
+-- 2. Roles.
+--    app_migration : owns the schema, applies Flyway migrations. DDL.
+--    app_runtime   : the application's credential. DML only, no DDL, no CREATE.
+--    app_admin     : J4 operations — COPY, backfill, maintenance. Never used by request paths.
+create role app_migration login password 'REPLACE_FROM_SECRET_STORE';
+create role app_runtime   login password 'REPLACE_FROM_SECRET_STORE';
+create role app_admin     login password 'REPLACE_FROM_SECRET_STORE';
+
+-- 3. Revoke the PUBLIC grants that make the checks in DatabaseRolePolicy necessary.
+--    Before PostgreSQL 15, PUBLIC held CREATE on the public schema — which is how an unprivileged
+--    role ends up able to plant an object that shadows a real one through search_path.
+revoke all on database current_database() from public;
+revoke create on schema public from public;
+
+-- 4. Runtime: read and write rows in the application schema. Nothing else.
+grant connect on database current_database() to app_runtime;
+grant usage on schema app to app_runtime;
+grant select, insert, update, delete on all tables in schema app to app_runtime;
+grant usage, select on all sequences in schema app to app_runtime;
+
+-- Tables created by future migrations must inherit the same grants, or the first deployment after
+-- a new table silently fails at runtime with a permission error.
+alter default privileges for role app_migration in schema app
+    grant select, insert, update, delete on tables to app_runtime;
+alter default privileges for role app_migration in schema app
+    grant usage, select on sequences to app_runtime;
+
+-- 5. Explicitly deny the two privileges the startup verifier checks for.
+revoke create on schema app from app_runtime;
+revoke create on database current_database() from app_runtime;
+
+-- 6. Admin: bulk operations under an audited identity, still without schema ownership.
+grant connect on database current_database() to app_admin;
+grant usage on schema app to app_admin;
+grant select, insert, update, delete on all tables in schema app to app_admin;
+alter default privileges for role app_migration in schema app
+    grant select, insert, update, delete on tables to app_admin;
+
+-- 7. Pin the runtime search_path so an unqualified name cannot resolve anywhere unexpected.
+alter role app_runtime set search_path = app, pg_catalog;
+alter role app_admin   set search_path = app, pg_catalog;

infra/jpa/toxiproxy/docker-compose.yml

@@ -0,0 +1,43 @@
+# Commit-ambiguity failure injection for the JPA platform (design §39).
+#
+# The suite needs a proxy rather than a kill switch because the scenario that matters cannot be
+# produced any other way. Stopping the container, killing the process, or closing the client socket
+# all break *before* the server commits — the easy case, where the transaction rolled back and the
+# use case may simply be re-run. The hard case is a commit the server completed whose
+# acknowledgement never came back, and it only exists if you can cut the return path while leaving
+# the forward path intact.
+#
+# That is what CommitAmbiguityProxy does with a downstream-only toxic, and it is the one scenario
+# that distinguishes a platform that reports completion-unknown from one that retries a write which
+# already succeeded.
+#
+# Ordinary contract runs use Testcontainers and do not need this file; it exists for reproducing a
+# failure scenario by hand.
+
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_DB: jpa_failure
+      POSTGRES_USER: jpa_failure
+      POSTGRES_PASSWORD: jpa_failure
+    # No published port: the suite must reach PostgreSQL only through the proxy, or the injected
+    # fault can be bypassed by connecting directly and the test passes without testing anything.
+    expose:
+      - "5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U jpa_failure -d jpa_failure"]
+      interval: 2s
+      timeout: 3s
+      retries: 30
+
+  toxiproxy:
+    image: ghcr.io/shopify/toxiproxy:2.11.0
+    depends_on:
+      postgres:
+        condition: service_healthy
+    ports:
+      # 8474 is the control API the suite drives; 8666 is the proxied PostgreSQL port.
+      - "8474:8474"
+      - "8666:8666"
+    command: ["-host", "0.0.0.0"]

infra/notification/toxiproxy/docker-compose.yml

@@ -0,0 +1,94 @@
+# Toxiproxy fault injection for the notification delivery platform.
+#
+# Scope, stated up front: this is the *nightly and release* fault suite, not the PR gate. The PR
+# suite runs against a loopback socket harness in-process — deterministic, no Docker, no provider
+# sandbox — because a gate that needs infrastructure is a gate people learn to skip. What lives
+# here are the faults that harness cannot produce: real TCP behaviour under latency, bandwidth
+# starvation, and connection resets at a point the JVM's own socket layer decides.
+#
+# Usage:
+#   docker compose -f infra/notification/toxiproxy/docker-compose.yml up -d
+#   ./gradlew :adapter:outbound:notification:test -Dnotification.faultProxy=http://127.0.0.1:8474
+#
+# The proxies below front *stub* upstreams, never a provider's real API. Pointing a toxic proxy at
+# a live provider sends real notifications to real people from a test run, and adds a rate-limit
+# incident on an account the team shares.
+services:
+  toxiproxy:
+    image: ghcr.io/shopify/toxiproxy:2.11.0
+    container_name: notification-toxiproxy
+    ports:
+      - "8474:8474"   # control API
+      - "18081:18081" # -> ses-stub
+      - "18082:18082" # -> twilio-stub
+      - "18083:18083" # -> push-stub (APNs / FCM / Web Push)
+    networks: [notification-fault]
+    healthcheck:
+      test: ["CMD", "/toxiproxy-cli", "list"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+
+  # Deterministic upstreams. Each returns the provider's success shape and nothing else; the
+  # interesting behaviour is injected by the proxy in front of it, not by the stub.
+  ses-stub:
+    image: mendhak/http-https-echo:35
+    environment:
+      HTTP_PORT: "8080"
+    networks: [notification-fault]
+
+  twilio-stub:
+    image: mendhak/http-https-echo:35
+    environment:
+      HTTP_PORT: "8080"
+    networks: [notification-fault]
+
+  push-stub:
+    image: mendhak/http-https-echo:35
+    environment:
+      HTTP_PORT: "8080"
+    networks: [notification-fault]
+
+  # Creates the proxies and the toxics once the control API is up. Kept as a job rather than a
+  # README step so the topology is reproducible and reviewable rather than typed from memory.
+  provision:
+    image: ghcr.io/shopify/toxiproxy:2.11.0
+    depends_on:
+      toxiproxy:
+        condition: service_healthy
+    networks: [notification-fault]
+    entrypoint:
+      - /bin/sh
+      - -c
+      - |
+        set -e
+        CLI="/toxiproxy-cli -h toxiproxy:8474"
+        $$CLI create -l 0.0.0.0:18081 -u ses-stub:8080 ses
+        $$CLI create -l 0.0.0.0:18082 -u twilio-stub:8080 twilio
+        $$CLI create -l 0.0.0.0:18083 -u push-stub:8080 push
+
+        # Response loss after the request was committed: the provider received and acted on the
+        # message, and the answer never came back. This is the AMBIGUOUS case, and it is the one
+        # fault no provider's documentation describes.
+        $$CLI toxic add -t timeout -a timeout=0 -n response_loss --downstream --toxicity 0 ses
+        $$CLI toxic add -t timeout -a timeout=0 -n response_loss --downstream --toxicity 0 twilio
+        $$CLI toxic add -t timeout -a timeout=0 -n response_loss --downstream --toxicity 0 push
+
+        # Latency past the adapter's own timeout, to prove the timeout is the adapter's decision
+        # rather than the socket's.
+        $$CLI toxic add -t latency -a latency=8000 -n slow --toxicity 0 ses
+        $$CLI toxic add -t latency -a latency=8000 -n slow --toxicity 0 twilio
+        $$CLI toxic add -t latency -a latency=8000 -n slow --toxicity 0 push
+
+        # Partial write: the connection dies mid-body. Distinct from response loss, because the
+        # provider never got a complete request and the attempt is genuinely retryable.
+        $$CLI toxic add -t limit_data -a bytes=64 -n partial_write --upstream --toxicity 0 ses
+        $$CLI toxic add -t limit_data -a bytes=64 -n partial_write --upstream --toxicity 0 twilio
+        $$CLI toxic add -t limit_data -a bytes=64 -n partial_write --upstream --toxicity 0 push
+
+        echo "proxies ready; toxics are registered at toxicity=0 and enabled per test"
+        $$CLI list
+
+networks:
+  notification-fault:
+    driver: bridge