diff --git a/.github/workflows/integration-main.yml b/.github/workflows/integration-main.yml index 6f8d8366..c69cb539 100644 --- a/.github/workflows/integration-main.yml +++ b/.github/workflows/integration-main.yml @@ -162,6 +162,8 @@ jobs: # and container start-up between lanes. A hosted runner adds cold image pulls (about 5 GB # uncompressed across the PostgreSQL, MongoDB, Kafka, nginx, httpbin and Toxiproxy images) and a # cold Gradle cache; expect 25 to 40 minutes (an estimate, not a measured hosted run). The 240-minute timeout is a ceiling for a hung container, not a budget. + # Since 2026-11-08 messagingCertificationTest and the messaging starter's integrationTest run in the + # messaging-library repository, not here; the measurement above predates that. integration-check: runs-on: ubuntu-latest timeout-minutes: 240 diff --git a/.github/workflows/messaging-certification.yml b/.github/workflows/messaging-certification.yml deleted file mode 100644 index 726ba8e8..00000000 --- a/.github/workflows/messaging-certification.yml +++ /dev/null @@ -1,51 +0,0 @@ -# The messaging platform's broker certification lane. -# -# Separate from ci-quality-gates.yml because it needs a container runtime and several minutes of it. -# The lane deliberately carries no Docker guard: every other container suite in the messaging tree -# skips with a stated reason when Docker is absent, and a certification lane that skipped would -# report success for a broker nobody started — which is the exact claim the evidence exists to rule -# out. -# -# The job runs the evidence gate rather than the lane, and the gate depends on the lane. What it -# proves is not only that the scenarios pass but that the committed manifest -# (messaging-testkit/src/main/resources/messaging/broker-certification-evidence.jsonl) is what this -# run produced, so "certified against a live broker" cannot be restored by editing a file. -name: messaging-certification - -on: - pull_request: - paths: - - "src/platforms/messaging/**" - - ".github/workflows/messaging-certification.yml" - # Every Gradle job here installs its toolchain through this composite action, so a change to - # it changes what this gate runs. - - ".github/actions/setup-gradle-java/action.yml" - schedule: - - cron: "41 4 * * 3" - workflow_dispatch: - -permissions: - contents: read - -env: - # Reuse would hand one scenario the broker another scenario had already faulted. - TESTCONTAINERS_REUSE_ENABLE: "false" - -jobs: - broker-certification: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Certify the Kafka adapter against a real broker - working-directory: src - # GITHUB_SHA is read by the lane and written into every evidence line, because "certified" - # is a claim about one source tree. - run: ./gradlew :messaging:messaging-kafka:verifyMessagingCertificationEvidence --stacktrace - - name: Publish the certification evidence - if: always() - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2 - with: - name: messaging-broker-certification-evidence - path: src/platforms/messaging/messaging-kafka/build/messaging-certification/ - if-no-files-found: warn diff --git a/scripts/check-repo-layout.py b/scripts/check-repo-layout.py index 8c6e3412..28759245 100755 --- a/scripts/check-repo-layout.py +++ b/scripts/check-repo-layout.py @@ -58,7 +58,8 @@ ROOT_ALLOWED = { "testcontainers.properties.example": "Testcontainers 로컬 설정 예", } -# src/ 바로 아래: 계층·조립 leaf, 들여온 제품 묶음, Gradle 루트 표준 폴더와 빌드 파일. +# src/ 바로 아래: 계층·조립 leaf, Gradle 루트 표준 폴더와 빌드 파일. 계층이 아닌 라이브러리(메시징·gRPC)는 +# 2026-11-08에 별도 repo로 나갔다(docs/work/reference/related-repos.md). 그 자리(platforms)는 다시 두지 않는다. SRC_ALLOWED = { # 계층과 조립 "domain-core": "계층", @@ -70,8 +71,6 @@ SRC_ALLOWED = { "adapter": "계층(adapter leaf 묶음)", "composition": "조립(Clean Architecture의 Main)", "app-bootstrap": "조립 루트", - # 들여온 제품 - "platforms": "들여온 제품(messaging). gRPC는 2026-11-08 별도 repo grpc-library로", # Gradle 루트 표준 "build-logic": "빌드 규칙(included build)", "config": "빌드 전체 도구 설정(registry, checkstyle, spotbugs, 테스트 이미지)", diff --git a/scripts/hooks/hooks.py b/scripts/hooks/hooks.py index 1d32adb3..5110ecb4 100644 --- a/scripts/hooks/hooks.py +++ b/scripts/hooks/hooks.py @@ -46,14 +46,17 @@ SKIPPED = "포맷을 건너뛰었다" # --- N1: the layer rules the gates hold, checked on the imports of one edited main source -------------- # Mirrors DomainPurityArchitectureTest (DOMAIN_IS_PURE, DOMAIN_HAS_NO_LOGGER). +# dev.cakit.: the owner's libraries (messaging-library, grpc-library) are reached only through adapters; +# a layer row may not list one in allowed_libraries (registry library_groups, build-logic ArchitecturePlugin). DOMAIN_FORBIDDEN = ("org.springframework.", "jakarta.persistence.", "javax.persistence.", "jakarta.servlet.", "org.hibernate.", "lombok.", "org.slf4j.", "java.util.logging.", "ch.qos.logback.", - "org.apache.logging.log4j.") + "org.apache.logging.log4j.", "dev.cakit.") # Mirrors VerifyApplicationCoreDependencyPurityTask and the application-core AGENTS.md forbidden list. APPLICATION_FORBIDDEN = ("org.springframework.", "org.slf4j.", "ch.qos.logback.", "org.apache.logging.log4j.", "io.micrometer.", "java.util.logging.", "jakarta.persistence.", "javax.persistence.", - "lombok.") -SHARED_FORBIDDEN = ("org.springframework.", "jakarta.", "javax.persistence.", "org.hibernate.", "lombok.") + "lombok.", "dev.cakit.") +SHARED_FORBIDDEN = ("org.springframework.", "jakarta.", "javax.persistence.", "org.hibernate.", "lombok.", + "dev.cakit.") # HARD-STOP 2: an inbound adapter reaching the store. INBOUND_FORBIDDEN = ("org.springframework.data.repository.", "org.springframework.data.jpa.", "org.springframework.data.mongodb.repository.", "jakarta.persistence.", "javax.persistence.") diff --git a/scripts/tests/test_hooks.py b/scripts/tests/test_hooks.py index b5c1fa08..3808a3ea 100644 --- a/scripts/tests/test_hooks.py +++ b/scripts/tests/test_hooks.py @@ -252,6 +252,11 @@ class BoundaryNudgeTest(RepositoryTestCase): self.assertIn("HARD-STOP 1 의심: `domain-core`가 `org.springframework.stereotype.Component`", text) self.assertIn("architectureCheck", text) + def test_an_owned_library_in_the_application_is_flagged(self) -> None: + text = self.nudge("src/application-core", "dev/caskeleton/application/order/Notify.java", + "import dev.cakit.messaging.api.MessageEnvelope;") + self.assertIn("`application-core`가 `dev.cakit.messaging.api.MessageEnvelope`", text) + def test_an_inbound_dto_in_the_application_is_hard_stop_3(self) -> None: text = self.nudge("src/application-core", "dev/caskeleton/application/order/Place.java", "import dev.caskeleton.adapter.inbound.web.order.OrderRequest;") diff --git a/src/adapter/inbound/messaging/build.gradle b/src/adapter/inbound/messaging/build.gradle index 1c67b2ba..9eab0546 100644 --- a/src/adapter/inbound/messaging/build.gradle +++ b/src/adapter/inbound/messaging/build.gradle @@ -3,7 +3,7 @@ plugins { id 'ca.spring-config' } -// The application's consume side of the vendored messaging platform (review 2026-11-01 06-08), +// The application's consume side of the messaging library (dev.cakit.messaging, review 2026-11-01 06-08), // selected by one line in a composition root: // // runtimeOnly project(':adapter:inbound:messaging') @@ -29,14 +29,14 @@ base { dependencies { implementation project(':application-core') - implementation project(':messaging:messaging-core-api') - implementation project(':messaging:messaging-reliability') - implementation project(':messaging:messaging-reliability-api') - // JdbcInboxRepository only. The leaf also exports the platform admin journal (api - // messaging-admin), which this leaf has no use for and no registered edge to; the starter puts it - // on the runtime classpath anyway. - implementation(project(':messaging:messaging-reliability-jdbc-postgresql')) { - exclude group: 'dev.caskeleton', module: 'messaging-admin' + implementation libs.messaging.core.api + implementation libs.messaging.reliability + implementation libs.messaging.reliability.api + // JdbcInboxRepository only. The module also exports the library's admin journal (api + // messaging-admin), which this leaf has no use for and no registered library edge to; the starter + // puts it on the runtime classpath anyway. + implementation(libs.messaging.reliability.jdbc.postgresql) { + exclude group: 'dev.cakit.messaging', module: 'messaging-admin' } implementation 'org.springframework.boot:spring-boot-autoconfigure' @@ -76,7 +76,7 @@ configurations { // Test-only edges of the redelivery lane: the publishing side as a composition root selects it // (the Kafka capability, the outbox relay, the JPA outbox over PostgreSQL), the port owner's event -// fixture, and the platform's MessageContracts holder the consumer registers its payload type in. +// fixture, and the library's MessageContracts holder the consumer registers its payload type in. // Test edges are outside the registry gate. dependencies { integrationTestImplementation project(':adapter:outbound:messaging-kafka') @@ -84,8 +84,8 @@ dependencies { integrationTestImplementation project(':adapter:outbound:persistence-jpa') integrationTestImplementation project(':application-core') integrationTestImplementation testFixtures(project(':application-core')) - integrationTestImplementation project(':messaging:messaging-core-api') - integrationTestImplementation project(':messaging:messaging-spring-boot-starter') + integrationTestImplementation libs.messaging.core.api + integrationTestImplementation libs.messaging.spring.boot.starter integrationTestImplementation 'org.springframework:spring-jdbc' integrationTestImplementation 'org.flywaydb:flyway-core' integrationTestImplementation 'org.apache.kafka:kafka-clients' diff --git a/src/adapter/inbound/messaging/gradle.lockfile b/src/adapter/inbound/messaging/gradle.lockfile index cca8539f..feedb258 100644 --- a/src/adapter/inbound/messaging/gradle.lockfile +++ b/src/adapter/inbound/messaging/gradle.lockfile @@ -50,6 +50,20 @@ commons-collections:commons-collections:3.2.2=checkstyle commons-io:commons-io:2.20.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath commons-io:commons-io:2.21.0=spotbugs commons-logging:commons-logging:1.3.6=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-admin:1.0.0=integrationTestRuntimeClasspath +dev.cakit.messaging:messaging-core-api:1.0.0=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-kafka:1.0.0=integrationTestRuntimeClasspath +dev.cakit.messaging:messaging-observability:1.0.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath +dev.cakit.messaging:messaging-policy:1.0.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath +dev.cakit.messaging:messaging-reliability-api:1.0.0=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-reliability-jdbc-postgresql:1.0.0=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-reliability:1.0.0=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +dev.cakit.messaging:messaging-runtime-core:1.0.0=integrationTestRuntimeClasspath +dev.cakit.messaging:messaging-schema-json:1.0.0=integrationTestRuntimeClasspath +dev.cakit.messaging:messaging-security:1.0.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath +dev.cakit.messaging:messaging-spring-boot-starter-kafka:1.0.0=integrationTestRuntimeClasspath +dev.cakit.messaging:messaging-spring-boot-starter:1.0.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath +dev.cakit.messaging:messaging-transport-spi:1.0.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath info.picocli:picocli:4.7.7=checkstyle io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor diff --git a/src/adapter/inbound/messaging/src/integrationTest/java/dev/caskeleton/adapter/inbound/messaging/InboxRedeliveryIntegrationTest.java b/src/adapter/inbound/messaging/src/integrationTest/java/dev/caskeleton/adapter/inbound/messaging/InboxRedeliveryIntegrationTest.java index 527e3fe0..4f4d911b 100644 --- a/src/adapter/inbound/messaging/src/integrationTest/java/dev/caskeleton/adapter/inbound/messaging/InboxRedeliveryIntegrationTest.java +++ b/src/adapter/inbound/messaging/src/integrationTest/java/dev/caskeleton/adapter/inbound/messaging/InboxRedeliveryIntegrationTest.java @@ -3,6 +3,13 @@ package dev.caskeleton.adapter.inbound.messaging; import static org.assertj.core.api.Assertions.assertThat; import static org.awaitility.Awaitility.await; +import dev.cakit.messaging.api.MessageId; +import dev.cakit.messaging.api.MessageType; +import dev.cakit.messaging.api.delivery.HandleResult; +import dev.cakit.messaging.api.delivery.MessageDelivery; +import dev.cakit.messaging.api.delivery.MessageHandler; +import dev.cakit.messaging.api.destination.DestinationName; +import dev.cakit.messaging.api.destination.MessageDestination; import dev.caskeleton.application.capability.Idempotency; import dev.caskeleton.application.capability.RepositoryAccess; import dev.caskeleton.application.capability.UseCaseCapability; @@ -13,13 +20,6 @@ import dev.caskeleton.application.security.SystemCaller; import dev.caskeleton.application.security.SystemInvoked; import dev.caskeleton.application.transaction.TransactionMode; import dev.caskeleton.application.transaction.TransactionPort; -import dev.caskeleton.messaging.api.MessageId; -import dev.caskeleton.messaging.api.MessageType; -import dev.caskeleton.messaging.api.delivery.HandleResult; -import dev.caskeleton.messaging.api.delivery.MessageDelivery; -import dev.caskeleton.messaging.api.delivery.MessageHandler; -import dev.caskeleton.messaging.api.destination.DestinationName; -import dev.caskeleton.messaging.api.destination.MessageDestination; import java.time.Clock; import java.time.Duration; import java.time.Instant; diff --git a/src/adapter/inbound/messaging/src/main/java/dev/caskeleton/adapter/inbound/messaging/MessagingInboxAutoConfiguration.java b/src/adapter/inbound/messaging/src/main/java/dev/caskeleton/adapter/inbound/messaging/MessagingInboxAutoConfiguration.java index b45d514a..52dae485 100644 --- a/src/adapter/inbound/messaging/src/main/java/dev/caskeleton/adapter/inbound/messaging/MessagingInboxAutoConfiguration.java +++ b/src/adapter/inbound/messaging/src/main/java/dev/caskeleton/adapter/inbound/messaging/MessagingInboxAutoConfiguration.java @@ -1,9 +1,9 @@ package dev.caskeleton.adapter.inbound.messaging; -import dev.caskeleton.messaging.api.delivery.MessageHandler; -import dev.caskeleton.messaging.inbox.IdempotentConsumer; -import dev.caskeleton.messaging.inbox.JdbcInboxRepository; -import dev.caskeleton.messaging.reliability.InboxRepository; +import dev.cakit.messaging.api.delivery.MessageHandler; +import dev.cakit.messaging.inbox.IdempotentConsumer; +import dev.cakit.messaging.inbox.JdbcInboxRepository; +import dev.cakit.messaging.reliability.InboxRepository; import javax.sql.DataSource; import org.springframework.boot.autoconfigure.AutoConfiguration; import org.springframework.boot.autoconfigure.condition.ConditionalOnBean; @@ -43,7 +43,7 @@ import org.springframework.transaction.support.TransactionTemplate; "org.springframework.boot.hibernate.autoconfigure.HibernateJpaAutoConfiguration", "org.springframework.boot.jdbc.autoconfigure.DataSourceTransactionManagerAutoConfiguration" }, - beforeName = "dev.caskeleton.messaging.autoconfigure.MessagingPlatformRootAutoConfiguration") + beforeName = "dev.cakit.messaging.autoconfigure.MessagingPlatformRootAutoConfiguration") @ConditionalOnBean({MessageHandler.class, DataSource.class, PlatformTransactionManager.class}) public class MessagingInboxAutoConfiguration { diff --git a/src/adapter/inbound/messaging/src/test/java/dev/cakit/messaging/autoconfigure/MessagingPlatformRootAutoConfiguration.java b/src/adapter/inbound/messaging/src/test/java/dev/cakit/messaging/autoconfigure/MessagingPlatformRootAutoConfiguration.java new file mode 100644 index 00000000..f34ded1b --- /dev/null +++ b/src/adapter/inbound/messaging/src/test/java/dev/cakit/messaging/autoconfigure/MessagingPlatformRootAutoConfiguration.java @@ -0,0 +1,31 @@ +package dev.cakit.messaging.autoconfigure; + +import dev.cakit.messaging.reliability.InboxRepository; +import org.springframework.boot.autoconfigure.AutoConfiguration; +import org.springframework.boot.autoconfigure.AutoConfigureOrder; +import org.springframework.boot.autoconfigure.condition.ConditionalOnBean; +import org.springframework.context.annotation.Bean; +import org.springframework.core.Ordered; + +/** + * Test stand-in with the exact name of the messaging library's root auto-configuration. + * + *
The library builds its inbox consumer only from an {@link InboxRepository} the application
+ * provides, so the application's {@code MessagingInboxAutoConfiguration} must run first ({@code
+ * beforeName}). This stand-in asks to run first itself ({@code HIGHEST_PRECEDENCE}) and records, as
+ * a bean, whether it saw the repository: it does only if the constraint put the inbox configuration
+ * ahead of it. The starter is not on this leaf's test classpath, so the name does not collide.
+ */
+@AutoConfiguration
+@AutoConfigureOrder(Ordered.HIGHEST_PRECEDENCE)
+public class MessagingPlatformRootAutoConfiguration {
+
+ /** Present only when the application's inbox repository existed as this root was processed. */
+ public record SawTheInbox() {}
+
+ @Bean
+ @ConditionalOnBean(InboxRepository.class)
+ SawTheInbox sawTheInbox() {
+ return new SawTheInbox();
+ }
+}
diff --git a/src/adapter/inbound/messaging/src/test/java/dev/caskeleton/adapter/inbound/messaging/MessagingInboxAutoConfigurationTest.java b/src/adapter/inbound/messaging/src/test/java/dev/caskeleton/adapter/inbound/messaging/MessagingInboxAutoConfigurationTest.java
index e5b7ed4f..2a144703 100644
--- a/src/adapter/inbound/messaging/src/test/java/dev/caskeleton/adapter/inbound/messaging/MessagingInboxAutoConfigurationTest.java
+++ b/src/adapter/inbound/messaging/src/test/java/dev/caskeleton/adapter/inbound/messaging/MessagingInboxAutoConfigurationTest.java
@@ -3,25 +3,25 @@ package dev.caskeleton.adapter.inbound.messaging;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.catchThrowable;
-import dev.caskeleton.messaging.api.ContentType;
-import dev.caskeleton.messaging.api.MessageEnvelope;
-import dev.caskeleton.messaging.api.MessageId;
-import dev.caskeleton.messaging.api.MessageType;
-import dev.caskeleton.messaging.api.ProducerId;
-import dev.caskeleton.messaging.api.SchemaVersion;
-import dev.caskeleton.messaging.api.TraceContext;
-import dev.caskeleton.messaging.api.delivery.DeliveryContext;
-import dev.caskeleton.messaging.api.delivery.DeliveryMetadata;
-import dev.caskeleton.messaging.api.delivery.HandleResult;
-import dev.caskeleton.messaging.api.delivery.MessageDelivery;
-import dev.caskeleton.messaging.api.delivery.MessageHandler;
-import dev.caskeleton.messaging.api.destination.DestinationName;
-import dev.caskeleton.messaging.api.destination.MessageDestination;
-import dev.caskeleton.messaging.api.header.MessageHeaders;
-import dev.caskeleton.messaging.inbox.IdempotentConsumer;
-import dev.caskeleton.messaging.inbox.InboxMessageHandler;
-import dev.caskeleton.messaging.inbox.JdbcInboxRepository;
-import dev.caskeleton.messaging.reliability.InboxRepository;
+import dev.cakit.messaging.api.ContentType;
+import dev.cakit.messaging.api.MessageEnvelope;
+import dev.cakit.messaging.api.MessageId;
+import dev.cakit.messaging.api.MessageType;
+import dev.cakit.messaging.api.ProducerId;
+import dev.cakit.messaging.api.SchemaVersion;
+import dev.cakit.messaging.api.TraceContext;
+import dev.cakit.messaging.api.delivery.DeliveryContext;
+import dev.cakit.messaging.api.delivery.DeliveryMetadata;
+import dev.cakit.messaging.api.delivery.HandleResult;
+import dev.cakit.messaging.api.delivery.MessageDelivery;
+import dev.cakit.messaging.api.delivery.MessageHandler;
+import dev.cakit.messaging.api.destination.DestinationName;
+import dev.cakit.messaging.api.destination.MessageDestination;
+import dev.cakit.messaging.api.header.MessageHeaders;
+import dev.cakit.messaging.inbox.IdempotentConsumer;
+import dev.cakit.messaging.inbox.InboxMessageHandler;
+import dev.cakit.messaging.inbox.JdbcInboxRepository;
+import dev.cakit.messaging.reliability.InboxRepository;
import java.sql.SQLException;
import java.time.Instant;
import java.util.ArrayList;
@@ -73,6 +73,26 @@ class MessagingInboxAutoConfigurationTest {
});
}
+ @Test
+ @DisplayName("inbox 조립은 라이브러리 root보다 먼저 돌아 root의 bean 조건이 inbox를 본다")
+ void theInboxIsAssembledBeforeTheLibraryRootThatNeedsIt() {
+ // given: a root stand-in that asks to run first and records whether it saw the inbox.
+ ApplicationContextRunner assembled =
+ runner.withConfiguration(
+ AutoConfigurations.of(
+ dev.cakit.messaging.autoconfigure.MessagingPlatformRootAutoConfiguration.class));
+
+ // when & then
+ assembled
+ .withBean(MessageHandler.class, () -> exampleHandler(new ArrayList<>()))
+ .run(
+ context ->
+ assertThat(context)
+ .hasSingleBean(
+ dev.cakit.messaging.autoconfigure.MessagingPlatformRootAutoConfiguration
+ .SawTheInbox.class));
+ }
+
@Test
@DisplayName("소비할 handler가 없으면 inbox를 조립하지 않는다")
void withoutAHandlerNothingIsAssembled() {
diff --git a/src/adapter/inbound/messaging/src/test/java/dev/caskeleton/adapter/inbound/messaging/SystemInvokedConsumePathTest.java b/src/adapter/inbound/messaging/src/test/java/dev/caskeleton/adapter/inbound/messaging/SystemInvokedConsumePathTest.java
index 040d33fd..c684e249 100644
--- a/src/adapter/inbound/messaging/src/test/java/dev/caskeleton/adapter/inbound/messaging/SystemInvokedConsumePathTest.java
+++ b/src/adapter/inbound/messaging/src/test/java/dev/caskeleton/adapter/inbound/messaging/SystemInvokedConsumePathTest.java
@@ -2,6 +2,24 @@ package dev.caskeleton.adapter.inbound.messaging;
import static org.assertj.core.api.Assertions.assertThat;
+import dev.cakit.messaging.api.ContentType;
+import dev.cakit.messaging.api.MessageEnvelope;
+import dev.cakit.messaging.api.MessageId;
+import dev.cakit.messaging.api.MessageType;
+import dev.cakit.messaging.api.ProducerId;
+import dev.cakit.messaging.api.SchemaVersion;
+import dev.cakit.messaging.api.TraceContext;
+import dev.cakit.messaging.api.delivery.DeliveryContext;
+import dev.cakit.messaging.api.delivery.DeliveryMetadata;
+import dev.cakit.messaging.api.delivery.HandleResult;
+import dev.cakit.messaging.api.delivery.MessageDelivery;
+import dev.cakit.messaging.api.delivery.MessageHandler;
+import dev.cakit.messaging.api.destination.DestinationName;
+import dev.cakit.messaging.api.destination.MessageDestination;
+import dev.cakit.messaging.api.header.MessageHeaders;
+import dev.cakit.messaging.inbox.IdempotentConsumer;
+import dev.cakit.messaging.inbox.InboxMessageHandler;
+import dev.cakit.messaging.reliability.InboxRepository;
import dev.caskeleton.adapter.outbound.support.startup.StartupFailureException;
import dev.caskeleton.application.capability.Idempotency;
import dev.caskeleton.application.capability.RepositoryAccess;
@@ -12,24 +30,6 @@ import dev.caskeleton.application.transaction.TransactionMode;
import dev.caskeleton.application.transaction.TransactionPort;
import dev.caskeleton.application.transaction.testkit.DirectTransactionPort;
import dev.caskeleton.composition.runtime.authorization.PermissionEnforcementConfig;
-import dev.caskeleton.messaging.api.ContentType;
-import dev.caskeleton.messaging.api.MessageEnvelope;
-import dev.caskeleton.messaging.api.MessageId;
-import dev.caskeleton.messaging.api.MessageType;
-import dev.caskeleton.messaging.api.ProducerId;
-import dev.caskeleton.messaging.api.SchemaVersion;
-import dev.caskeleton.messaging.api.TraceContext;
-import dev.caskeleton.messaging.api.delivery.DeliveryContext;
-import dev.caskeleton.messaging.api.delivery.DeliveryMetadata;
-import dev.caskeleton.messaging.api.delivery.HandleResult;
-import dev.caskeleton.messaging.api.delivery.MessageDelivery;
-import dev.caskeleton.messaging.api.delivery.MessageHandler;
-import dev.caskeleton.messaging.api.destination.DestinationName;
-import dev.caskeleton.messaging.api.destination.MessageDestination;
-import dev.caskeleton.messaging.api.header.MessageHeaders;
-import dev.caskeleton.messaging.inbox.IdempotentConsumer;
-import dev.caskeleton.messaging.inbox.InboxMessageHandler;
-import dev.caskeleton.messaging.reliability.InboxRepository;
import java.time.Instant;
import java.util.ArrayList;
import java.util.LinkedHashSet;
diff --git a/src/adapter/outbound/messaging-kafka/build.gradle b/src/adapter/outbound/messaging-kafka/build.gradle
index e80caa39..7d643c35 100644
--- a/src/adapter/outbound/messaging-kafka/build.gradle
+++ b/src/adapter/outbound/messaging-kafka/build.gradle
@@ -7,16 +7,18 @@ plugins {
//
// runtimeOnly project(':adapter:outbound:messaging-kafka')
//
-// That line brings the broker-neutral application bridge (adapter:outbound:messaging), the vendored
-// messaging platform with its Kafka transport, and the capability's settings
+// That line brings the broker-neutral application bridge (adapter:outbound:messaging), the messaging
+// library (dev.cakit.messaging, messaging-library repo) with its Kafka transport, and the capability's settings
// (config/module-defaults/messaging.yml). Deleting it removes all of them. The leaf has no code of
// its own: it is the selection, not an adapter. Its one test boots the capability the way an
// application gets it.
-// Every project shares the group dev.caskeleton, and the vendored transport is also named
-// messaging-kafka (:messaging:messaging-kafka). Same group and name is the same module to Gradle,
-// which silently substituted this project for the vendored one wherever both were reachable, so the
-// platform's Kafka transport classes went missing at runtime. A group of its own keeps them apart.
+// Every project shares the group dev.caskeleton. The messaging library's Kafka transport used to be
+// a project here too, also named messaging-kafka (:messaging:messaging-kafka), and same group and
+// name is the same module to Gradle: it silently substituted this project for the transport wherever
+// both were reachable, so the Kafka transport classes went missing at runtime. The library is now
+// dev.cakit.messaging:messaging-kafka (messaging-library repo); a group of its own still keeps this
+// project apart from :adapter:outbound:messaging and from any project a service adds.
group = 'dev.caskeleton.adapter'
// And a jar file name of its own: a Boot jar stores libraries in BOOT-INF/lib/ by file name, so the
// two messaging-kafka- The broker itself is a build-time choice: a transport leaf (messaging-kafka) brings the
- * vendored platform and its transport, and this root stays broker-neutral — it binds the
- * application's ports to the platform's pre-encoded publish path and nothing else.
+ * messaging library ({@code dev.cakit.messaging}) and its transport, and this root stays
+ * broker-neutral — it binds the application's ports to the library's pre-encoded publish path and
+ * nothing else.
*
* On when present: an application that selected a messaging leaf wants messaging, so a missing
* {@code app.messaging.enabled} means on and only an explicit {@code false} turns it off.
*/
@AutoConfiguration(
- afterName = "dev.caskeleton.messaging.autoconfigure.MessagingPlatformRootAutoConfiguration")
+ afterName = "dev.cakit.messaging.autoconfigure.MessagingPlatformRootAutoConfiguration")
@ConditionalOnProperty(
prefix = "app.messaging",
name = "enabled",
@@ -58,8 +59,9 @@ public class MessagingBridgeRootAutoConfiguration {
* identity environment-dependent.
*
* {@code @ConditionalOnBean} only sees the publisher because this class is ordered after the
- * platform root: auto-configurations are sorted by name first, and {@code
- * dev.caskeleton.adapter…} sorts before {@code dev.caskeleton.messaging…}.
+ * library's root ({@code afterName} above). Auto-configurations are sorted by name first, and
+ * {@code dev.cakit.messaging…} happens to sort before {@code dev.caskeleton.adapter…}; the
+ * constraint, not the name, is what keeps the order through any rename.
*/
@Bean
@ConditionalOnBean(EncodedMessagePublisher.class)
diff --git a/src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapter.java b/src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapter.java
index 8b81e8ae..bc4b7f52 100644
--- a/src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapter.java
+++ b/src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapter.java
@@ -1,32 +1,32 @@
package dev.caskeleton.adapter.outbound.messaging.platformbridge;
+import dev.cakit.messaging.api.CausationId;
+import dev.cakit.messaging.api.ContentType;
+import dev.cakit.messaging.api.CorrelationId;
+import dev.cakit.messaging.api.MessageEnvelope;
+import dev.cakit.messaging.api.MessageId;
+import dev.cakit.messaging.api.MessageType;
+import dev.cakit.messaging.api.ProducerId;
+import dev.cakit.messaging.api.SchemaVersion;
+import dev.cakit.messaging.api.TenantContext;
+import dev.cakit.messaging.api.TraceContext;
+import dev.cakit.messaging.api.destination.DestinationName;
+import dev.cakit.messaging.api.destination.MessageDestination;
+import dev.cakit.messaging.api.error.FailureDescriptor;
+import dev.cakit.messaging.api.header.HeaderName;
+import dev.cakit.messaging.api.header.HeaderValue;
+import dev.cakit.messaging.api.header.MessageHeaders;
+import dev.cakit.messaging.api.publish.PublishCompletion;
+import dev.cakit.messaging.api.publish.PublishOptions;
+import dev.cakit.messaging.api.publish.PublishResult;
+import dev.cakit.messaging.api.publish.TransmissionEvidence;
+import dev.cakit.messaging.schema.EncodedMessage;
+import dev.cakit.messaging.schema.EncodedMessagePublisher;
+import dev.cakit.messaging.schema.SchemaReference;
import dev.caskeleton.application.messaging.event.IntegrationEventPublishPort;
import dev.caskeleton.application.messaging.event.ValidatedIntegrationEvent;
import dev.caskeleton.application.outbox.OutboxPublishAttempt;
import dev.caskeleton.application.outbox.OutboxPublishOutcome;
-import dev.caskeleton.messaging.api.CausationId;
-import dev.caskeleton.messaging.api.ContentType;
-import dev.caskeleton.messaging.api.CorrelationId;
-import dev.caskeleton.messaging.api.MessageEnvelope;
-import dev.caskeleton.messaging.api.MessageId;
-import dev.caskeleton.messaging.api.MessageType;
-import dev.caskeleton.messaging.api.ProducerId;
-import dev.caskeleton.messaging.api.SchemaVersion;
-import dev.caskeleton.messaging.api.TenantContext;
-import dev.caskeleton.messaging.api.TraceContext;
-import dev.caskeleton.messaging.api.destination.DestinationName;
-import dev.caskeleton.messaging.api.destination.MessageDestination;
-import dev.caskeleton.messaging.api.error.FailureDescriptor;
-import dev.caskeleton.messaging.api.header.HeaderName;
-import dev.caskeleton.messaging.api.header.HeaderValue;
-import dev.caskeleton.messaging.api.header.MessageHeaders;
-import dev.caskeleton.messaging.api.publish.PublishCompletion;
-import dev.caskeleton.messaging.api.publish.PublishOptions;
-import dev.caskeleton.messaging.api.publish.PublishResult;
-import dev.caskeleton.messaging.api.publish.TransmissionEvidence;
-import dev.caskeleton.messaging.schema.EncodedMessage;
-import dev.caskeleton.messaging.schema.EncodedMessagePublisher;
-import dev.caskeleton.messaging.schema.SchemaReference;
import java.time.Duration;
import java.util.LinkedHashMap;
import java.util.Map;
diff --git a/src/adapter/outbound/messaging/src/test/java/dev/cakit/messaging/autoconfigure/MessagingPlatformRootAutoConfiguration.java b/src/adapter/outbound/messaging/src/test/java/dev/cakit/messaging/autoconfigure/MessagingPlatformRootAutoConfiguration.java
new file mode 100644
index 00000000..528c0206
--- /dev/null
+++ b/src/adapter/outbound/messaging/src/test/java/dev/cakit/messaging/autoconfigure/MessagingPlatformRootAutoConfiguration.java
@@ -0,0 +1,34 @@
+package dev.cakit.messaging.autoconfigure;
+
+import dev.cakit.messaging.schema.EncodedMessagePublisher;
+import org.springframework.boot.autoconfigure.AutoConfiguration;
+import org.springframework.boot.autoconfigure.AutoConfigureOrder;
+import org.springframework.context.annotation.Bean;
+import org.springframework.core.Ordered;
+
+/**
+ * Test stand-in with the exact name of the messaging starter's root auto-configuration.
+ *
+ * The bridge orders itself after that root by name ({@code afterName}). Boot sorts
+ * auto-configurations alphabetically before applying {@code after} constraints; while the library
+ * was {@code dev.caskeleton.messaging} the bridge sorted first, so the constraint carried the
+ * order. Since the package became {@code dev.cakit.messaging} (2026-11-08) the root sorts first by
+ * name as well, and the constraint is what keeps that true for any rename. A stand-in with the same
+ * name reproduces the ordering without pulling the starter, and a broker, onto this leaf's test
+ * classpath. The starter is not on that classpath, so the name does not collide.
+ *
+ * The stand-in asks to run last ({@code LOWEST_PRECEDENCE}), which the real root does not: with
+ * the name sorting it first, a test without that would pass even if the bridge lost its {@code
+ * afterName}. Ordered last, the bridge still comes after it only because of the constraint.
+ */
+@AutoConfiguration
+@AutoConfigureOrder(Ordered.LOWEST_PRECEDENCE)
+public class MessagingPlatformRootAutoConfiguration {
+
+ @Bean
+ EncodedMessagePublisher encodedMessagePublisher() {
+ return (destination, message, options) -> {
+ throw new AssertionError("publisher is not invoked while wiring the bridge");
+ };
+ }
+}
diff --git a/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/autoconfigure/MessagingPlatformBridgeAutoConfigurationTest.java b/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/autoconfigure/MessagingPlatformBridgeAutoConfigurationTest.java
index bc50447a..7b96ba7a 100644
--- a/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/autoconfigure/MessagingPlatformBridgeAutoConfigurationTest.java
+++ b/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/autoconfigure/MessagingPlatformBridgeAutoConfigurationTest.java
@@ -2,10 +2,10 @@ package dev.caskeleton.adapter.outbound.messaging.autoconfigure;
import static org.assertj.core.api.Assertions.assertThat;
+import dev.cakit.messaging.schema.EncodedMessagePublisher;
import dev.caskeleton.adapter.outbound.messaging.MessagingSettings;
import dev.caskeleton.application.messaging.event.IntegrationEventPublishPort;
import dev.caskeleton.application.outbox.OutboxMessagePublishPort;
-import dev.caskeleton.messaging.schema.EncodedMessagePublisher;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
@@ -48,8 +48,7 @@ class MessagingPlatformBridgeAutoConfigurationTest {
.withConfiguration(
AutoConfigurations.of(
MessagingBridgeRootAutoConfiguration.class,
- dev.caskeleton.messaging.autoconfigure.MessagingPlatformRootAutoConfiguration
- .class))
+ dev.cakit.messaging.autoconfigure.MessagingPlatformRootAutoConfiguration.class))
.withPropertyValues(
"app.messaging.enabled=true", "app.messaging.producer-id=portfolio-service");
diff --git a/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapterTest.java b/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapterTest.java
index d1564cd4..72e6bef7 100644
--- a/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapterTest.java
+++ b/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapterTest.java
@@ -3,6 +3,20 @@ package dev.caskeleton.adapter.outbound.messaging.platformbridge;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.catchThrowable;
+import dev.cakit.messaging.api.ContentType;
+import dev.cakit.messaging.api.MessageEnvelope;
+import dev.cakit.messaging.api.destination.MessageDestination;
+import dev.cakit.messaging.api.error.FailureCategory;
+import dev.cakit.messaging.api.error.FailureDescriptor;
+import dev.cakit.messaging.api.publish.ConfirmationLevel;
+import dev.cakit.messaging.api.publish.PublishCompletion;
+import dev.cakit.messaging.api.publish.PublishEvidence;
+import dev.cakit.messaging.api.publish.PublishOptions;
+import dev.cakit.messaging.api.publish.PublishResult;
+import dev.cakit.messaging.api.publish.RoutingOutcome;
+import dev.cakit.messaging.api.publish.TransmissionEvidence;
+import dev.cakit.messaging.schema.EncodedMessage;
+import dev.cakit.messaging.schema.EncodedMessagePublisher;
import dev.caskeleton.application.messaging.contract.ContractId;
import dev.caskeleton.application.messaging.contract.LogicalDestinationId;
import dev.caskeleton.application.messaging.event.AggregateIdentity;
@@ -14,20 +28,6 @@ import dev.caskeleton.application.messaging.event.testkit.BrokerAnswer;
import dev.caskeleton.application.messaging.event.testkit.IntegrationEventPublishContract;
import dev.caskeleton.application.outbox.OutboxPublishAttempt;
import dev.caskeleton.application.outbox.OutboxPublishOutcome;
-import dev.caskeleton.messaging.api.ContentType;
-import dev.caskeleton.messaging.api.MessageEnvelope;
-import dev.caskeleton.messaging.api.destination.MessageDestination;
-import dev.caskeleton.messaging.api.error.FailureCategory;
-import dev.caskeleton.messaging.api.error.FailureDescriptor;
-import dev.caskeleton.messaging.api.publish.ConfirmationLevel;
-import dev.caskeleton.messaging.api.publish.PublishCompletion;
-import dev.caskeleton.messaging.api.publish.PublishEvidence;
-import dev.caskeleton.messaging.api.publish.PublishOptions;
-import dev.caskeleton.messaging.api.publish.PublishResult;
-import dev.caskeleton.messaging.api.publish.RoutingOutcome;
-import dev.caskeleton.messaging.api.publish.TransmissionEvidence;
-import dev.caskeleton.messaging.schema.EncodedMessage;
-import dev.caskeleton.messaging.schema.EncodedMessagePublisher;
import dev.caskeleton.shared.digest.Sha256;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
diff --git a/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingPlatformRootAutoConfiguration.java b/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingPlatformRootAutoConfiguration.java
deleted file mode 100644
index 0dbab8d7..00000000
--- a/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingPlatformRootAutoConfiguration.java
+++ /dev/null
@@ -1,25 +0,0 @@
-package dev.caskeleton.messaging.autoconfigure;
-
-import dev.caskeleton.messaging.schema.EncodedMessagePublisher;
-import org.springframework.boot.autoconfigure.AutoConfiguration;
-import org.springframework.context.annotation.Bean;
-
-/**
- * Test stand-in with the exact name of the messaging starter's root auto-configuration.
- *
- * The bridge orders itself after that root by name, and Boot sorts auto-configurations
- * alphabetically before applying {@code after} constraints — {@code dev.caskeleton.adapter…} comes
- * before {@code dev.caskeleton.messaging…}. A stand-in with the same name reproduces that ordering
- * without pulling the starter, and a broker, onto this leaf's test classpath. The starter is not on
- * that classpath, so the name does not collide.
- */
-@AutoConfiguration
-public class MessagingPlatformRootAutoConfiguration {
-
- @Bean
- EncodedMessagePublisher encodedMessagePublisher() {
- return (destination, message, options) -> {
- throw new AssertionError("publisher is not invoked while wiring the bridge");
- };
- }
-}
diff --git a/src/adapter/outbound/persistence-jpa/build.gradle b/src/adapter/outbound/persistence-jpa/build.gradle
index 6ef7a85e..a79b738a 100644
--- a/src/adapter/outbound/persistence-jpa/build.gradle
+++ b/src/adapter/outbound/persistence-jpa/build.gradle
@@ -296,6 +296,34 @@ tasks.named('postgresqlSecurityBaselineIntegrationTest') {
// Which JPA lanes block a release is declared by release/release-registry.json (jpaReleaseQualification below).
// This leaf declares the lanes and how each runs; it does not own release orchestration.
+// The messaging library's migration tree (db/migration/messaging in messaging-reliability-jdbc-postgresql,
+// messaging-library repo) runs against the database this leaf owns once the consume side is
+// selected, through the same Flyway history, so AppliedMigrationImmutabilityTest and
+// MigrationLockWaitTest hold it to the same rules as this leaf's own trees (MigrationTrees). While
+// the library lived in this repository they read its source folder by path; now the tree is a
+// resource of the published jar, at the version the catalog names (`messagingLibrary`), which is
+// exactly what a service applies. Only the jar, not its dependencies, and only to read: the module is
+// on no classpath of this leaf, so no test context sees the library.
+configurations {
+ messagingMigrations {
+ canBeConsumed = false
+ canBeResolved = true
+ transitive = false
+ description = 'The messaging library jar whose db/migration tree the migration tests read.'
+ }
+}
+dependencies {
+ messagingMigrations libs.messaging.reliability.jdbc.postgresql
+}
+def messagingMigrationDirectory = layout.buildDirectory.dir('library-migrations/messaging-reliability-jdbc-postgresql')
+def messagingMigrationTree = tasks.register('messagingMigrationTree', Sync) {
+ description = 'Extracts the messaging library\'s db/migration tree for the migration tests.'
+ from({ zipTree(configurations.messagingMigrations.singleFile) }) {
+ include 'db/migration/**'
+ }
+ into messagingMigrationDirectory
+}
+
// The unit lane reads three files that are not Java sources: the release registry and its two
// renderings. Without declaring them, Gradle calls the lane up-to-date after a registry demotion or
// a workflow edit — so the drift check that exists to catch exactly that edit never runs on it.
@@ -321,9 +349,14 @@ tasks.named('test') {
.withPropertyName('notificationMigrations')
inputs.dir(file('../persistence-fileserver/src/main/resources/db/migration'))
.withPropertyName('fileserverMigrations')
- // ...and the messaging platform's tree, whose inbox range the consume side applies here.
- inputs.dir(file('../../../platforms/messaging/messaging-reliability-jdbc-postgresql/src/main/resources/db/migration'))
+ // ...and the messaging library's tree, whose inbox range the consume side applies here: read out of
+ // the jar this build receives (messagingMigrationTree above), not from the library's sources.
+ dependsOn messagingMigrationTree
+ inputs.dir(messagingMigrationDirectory)
+ .withPathSensitivity(PathSensitivity.RELATIVE)
.withPropertyName('messagingMigrations')
+ systemProperty 'persistence.migration.messagingTree',
+ messagingMigrationDirectory.get().dir('db/migration').asFile.absolutePath
}
// verifyJpaApiSurface — every public type this leaf exposes is a committed decision.
diff --git a/src/adapter/outbound/persistence-jpa/gradle.lockfile b/src/adapter/outbound/persistence-jpa/gradle.lockfile
index ace35092..f0c903d9 100644
--- a/src/adapter/outbound/persistence-jpa/gradle.lockfile
+++ b/src/adapter/outbound/persistence-jpa/gradle.lockfile
@@ -54,6 +54,7 @@ commons-collections:commons-collections:3.2.2=checkstyle
commons-io:commons-io:2.20.0=jpaPlatformPerformanceTestCompileClasspath,jpaPlatformPerformanceTestRuntimeClasspath,postgresqlIntegrationTestCompileClasspath,postgresqlIntegrationTestRuntimeClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
commons-io:commons-io:2.21.0=spotbugs
commons-logging:commons-logging:1.3.6=compileClasspath,jpaPlatformPerformanceTestCompileClasspath,jpaPlatformPerformanceTestRuntimeClasspath,postgresqlIntegrationTestCompileClasspath,postgresqlIntegrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
+dev.cakit.messaging:messaging-reliability-jdbc-postgresql:1.0.0=messagingMigrations
eu.rekawek.toxiproxy:toxiproxy-java:2.1.11=jpaPlatformPerformanceTestRuntimeClasspath,postgresqlIntegrationTestCompileClasspath,postgresqlIntegrationTestRuntimeClasspath,testRuntimeClasspath
eu.rekawek.toxiproxy:toxiproxy-java:2.1.7=testFixturesCompileClasspath,testFixturesRuntimeClasspath
info.picocli:picocli:4.7.7=checkstyle
diff --git a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/migration/MigrationTrees.java b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/migration/MigrationTrees.java
index 018843b1..2c817a73 100644
--- a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/migration/MigrationTrees.java
+++ b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/migration/MigrationTrees.java
@@ -28,22 +28,37 @@ final class MigrationTrees {
* adapter:outbound:persistence-fileserver}) runs against the same database through the same
* Flyway history and was never pinned at all; it is checked here on the same terms.
*
- * The messaging platform's tree ({@code db/migration/messaging}, in {@code
- * messaging-reliability-jdbc-postgresql}) runs against it too once the consume side is selected:
- * {@code adapter:inbound:messaging} applies its inbox range (V11xx). The tree is pinned whole —
- * the platform outbox range ships from the same location to deployments that use it, and an
- * edited migration stops those just the same.
+ * The messaging library's tree ({@code db/migration/messaging}, in {@code
+ * dev.cakit.messaging:messaging-reliability-jdbc-postgresql}) runs against it too once the
+ * consume side is selected: {@code adapter:inbound:messaging} applies its inbox range (V11xx).
+ * The tree is pinned whole — the library's outbox range ships from the same location to
+ * deployments that use it, and an edited migration stops those just the same. The library lives
+ * in its own repository (messaging-library) since 2026-11-08, so the tree is read out of the jar
+ * this build receives: the build extracts it ({@code messagingMigrationTree}) and names the
+ * folder in {@value #MESSAGING_TREE_PROPERTY}.
*/
static final List Vendored platforms keep their own subtree under the same root: {@code app.messaging.*} belongs
- * to the {@code messaging:*} platform, and gRPC's settings sit in {@code app.grpc.server} and
- * {@code app.grpc.platform} side by side, never one at the shared parent — two strict binders on a
- * shared parent would each refuse the other's keys.
+ * The libraries published from their own repositories keep their own subtree under the same
+ * root: {@code app.messaging.*} belongs to the messaging library ({@code dev.cakit.messaging}), and
+ * gRPC's settings sit in {@code app.grpc.server} and {@code app.grpc.platform} side by side, never
+ * one at the shared parent — two strict binders on a shared parent would each refuse the other's
+ * keys.
*/
class ConfigurationNamespaceContractTest {
diff --git a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/messaging/MessagingAuthorityContractTest.java b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/messaging/MessagingAuthorityContractTest.java
index 2554634a..083eaf93 100644
--- a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/messaging/MessagingAuthorityContractTest.java
+++ b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/messaging/MessagingAuthorityContractTest.java
@@ -19,9 +19,15 @@ import org.junit.jupiter.api.Test;
*
* Two types declare {@code @ConfigurationProperties} on that prefix: {@code MessagingSettings}
* in the outbound adapter, which owns {@code producer-id}, and {@code MessagingSettings} in the
- * starter, which owns everything else, {@code broker} included. Spring binds both without complaint
- * — each takes the fields it declares — so the split is invisible at runtime and shows up only as
- * two places to look, neither of which validates the other's view.
+ * messaging library's starter, which owns everything else, {@code broker} included. Spring binds
+ * both without complaint — each takes the fields it declares — so the split is invisible at runtime
+ * and shows up only as two places to look, neither of which validates the other's view.
+ *
+ * Since the library moved to its own repository (messaging-library, 2026-11-08) each repository
+ * counts its own half: this test holds this repository to exactly one owner, and the library's
+ * {@code MessagingSettingsOwnerContractTest} holds the library to exactly one. A source scan cannot
+ * see across the two repositories any more, and the "two in total" of before is the sum of the two
+ * checks (design-docs {@code repo-structure/05-library-repos.md} 4.2절, 16절 H7).
*
* This test does not assert the split away. Collapsing it means the adapter stops selecting a
* broker and becomes a port bridge over the platform's publish contract, which it can only do once
@@ -51,13 +57,13 @@ class MessagingAuthorityContractTest {
Pattern.compile("String PREFIX\\s*=\\s*\"app\\.messaging\"");
private static final List A Gradle {@code implementation} dependency is not encapsulation. It removes the library from
- * the consumer's compile classpath, but it does not remove the library's types from this module's
- * public signatures. When both are true the artifact ships an API nobody can call: the method is
- * there, the javadoc describes it, and the caller cannot name its parameter or its return type
- * without guessing which library and which version to add to their own build. Every case below was
- * exactly that — a Kafka {@code Producer}, a Spring AMQP {@code Message}, a CloudEvent, a
- * Micrometer {@code MeterRegistry}, an Avro {@code Schema}, a protobuf {@code Parser}, a Reactor
- * {@code Mono}.
- *
- * So the rule is one-directional and mechanical: a vendor library named in a public or protected
- * signature is declared {@code api}; one used only behind private members stays {@code
- * implementation}. {@code src/platforms/messaging/AGENTS.md} states it as policy — this holds it to
- * the source so the two cannot drift.
- *
- * The libraries checked are the ones an adopter would otherwise have to reverse-engineer into
- * their own build: broker clients, codec libraries, the metrics registry, the reactive facade.
- * Spring Framework and Spring Boot are deliberately out of scope. They appear only inside the
- * composition boundary, where the container constructs the types rather than an adopter naming
- * them, and that boundary is where the family policy already confines them.
- */
-@Tag("repository-contract")
-class MessagingPublicSurfaceContractTest {
-
- /**
- * Package prefix to the Gradle coordinate that supplies it.
- *
- * Prefixes rather than exact packages, because a library's types are spread across its own
- * sub-packages and a consumer needs the whole artifact either way.
- */
- private static final Map Two ways a type gets named: imported and used by its simple name, or written out in full.
- * Both are checked, because the auto-configuration style in this repository uses fully qualified
- * names for one-off types rather than adding an import.
- */
- private static boolean isNamedInDeclarations(String source, String declarations, String prefix) {
- if (declarations.contains(prefix + ".")) {
- return true;
- }
- Matcher imports = IMPORT.matcher(source);
- while (imports.find()) {
- String imported = imports.group(1).trim();
- if (!imported.startsWith(prefix + ".")) {
- continue;
- }
- String simpleName = imported.substring(imported.lastIndexOf('.') + 1);
- if (Pattern.compile("\\b" + Pattern.quote(simpleName) + "\\b").matcher(declarations).find()) {
- return true;
- }
- }
- return false;
- }
-
- /**
- * Reduces a source file to its declarations: type headers, member signatures, record components.
- *
- * Method bodies are dropped, because a vendor type used inside one is an implementation detail
- * and is exactly the case that may stay {@code implementation}. Field initialisers are dropped
- * for the same reason. Anything a {@code private} modifier reaches is dropped last: a private
- * member is not a signature a consumer compiles against.
- *
- * A brace walk rather than a parser. It only has to answer "is this text a declaration or a
- * body", which brace depth settles, and a parser here would be more machinery than the question
- * deserves.
- */
- private static String declarationsOnly(String source) {
- String text = stripCommentsAndLiterals(source);
- StringBuilder kept = new StringBuilder();
- StringBuilder pending = new StringBuilder();
- int depth = 0;
- int bodyDepth = -1;
- int initializerDepth = -1;
-
- for (int index = 0; index < text.length(); index++) {
- char character = text.charAt(index);
- if (character == '{') {
- depth++;
- if (initializerDepth >= 0) {
- continue;
- }
- if (bodyDepth < 0) {
- kept.append(pending).append(';');
- if (!TYPE_KEYWORD.matcher(pending).find() && pending.indexOf("(") >= 0) {
- bodyDepth = depth;
- }
- }
- pending.setLength(0);
- continue;
- }
- if (character == '}') {
- if (bodyDepth == depth) {
- bodyDepth = -1;
- }
- depth--;
- pending.setLength(0);
- continue;
- }
- if (character == ';') {
- if (initializerDepth == depth) {
- initializerDepth = -1;
- } else if (bodyDepth < 0) {
- kept.append(pending).append(';');
- }
- pending.setLength(0);
- continue;
- }
- if (bodyDepth >= 0 || initializerDepth >= 0) {
- continue;
- }
- if (character == '=' && isAssignment(text, index)) {
- kept.append(pending).append(';');
- pending.setLength(0);
- initializerDepth = depth;
- continue;
- }
- pending.append(character);
- }
-
- return Stream.of(kept.toString().split(";", -1))
- .filter(fragment -> !fragment.contains("private "))
- .filter(fragment -> !fragment.contains("import "))
- .reduce("", (left, right) -> left + " ; " + right);
- }
-
- /** Distinguishes a field initialiser from {@code ==}, {@code <=}, {@code >=} and {@code !=}. */
- private static boolean isAssignment(String text, int index) {
- char before = index == 0 ? ' ' : text.charAt(index - 1);
- char after = index + 1 >= text.length() ? ' ' : text.charAt(index + 1);
- return before != '=' && before != '<' && before != '>' && before != '!' && after != '=';
- }
-
- private static String stripCommentsAndLiterals(String source) {
- return source
- .replaceAll("(?s)/\\*.*?\\*/", " ")
- .replaceAll("(?m)//.*$", " ")
- .replaceAll("\"\"\"(?s).*?\"\"\"", "\"\"")
- .replaceAll("\"(\\\\.|[^\"\\\\])*\"", "\"\"")
- .replaceAll("'(\\\\.|[^'\\\\])*'", "' '");
- }
-
- /** The external coordinates a build script exports to its consumers. */
- private static List {@code gradle/libs.versions.toml} declares {@code archunit-junit5 = { module = "..." }} and
- * Gradle exposes it as {@code libs.archunit.junit5}; the alias separators become dots. Parsing
- * the file rather than hard-coding the mapping keeps this test honest when an alias is renamed —
- * a stale table here would silently stop resolving and report the library as unexported.
- */
- private static Map Approvals expire. An open-ended approval becomes a standing permission, which is the same
- * thing as no approval at all — the window is what keeps "we approved a redrive last quarter" from
- * authorising one today.
- *
- * @param ticket the change reference
- * @param approvedBy the approver's identity
- * @param approvedAt when the approval was granted
- * @param validUntil when the approval stops authorising anything
- */
-public record AdminApproval(
- String ticket, String approvedBy, Instant approvedAt, Instant validUntil) {
-
- public AdminApproval {
- Objects.requireNonNull(approvedAt, "approvedAt must not be null");
- Objects.requireNonNull(validUntil, "validUntil must not be null");
- if (ticket == null || ticket.isBlank()) {
- throw new IllegalArgumentException("ticket must not be blank");
- }
- if (approvedBy == null || approvedBy.isBlank()) {
- throw new IllegalArgumentException("approvedBy must not be blank");
- }
- if (validUntil.isBefore(approvedAt)) {
- throw new IllegalArgumentException("an approval cannot expire before it was granted");
- }
- }
-
- /**
- * Reports whether the approval still authorises an operation.
- *
- * @param now the current instant
- * @return true while inside the window
- */
- public boolean isValidAt(Instant now) {
- Objects.requireNonNull(now, "now must not be null");
- return !now.isBefore(approvedAt) && now.isBefore(validUntil);
- }
-}
diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminOperationJournal.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminOperationJournal.java
deleted file mode 100644
index 012b2d09..00000000
--- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminOperationJournal.java
+++ /dev/null
@@ -1,93 +0,0 @@
-package dev.caskeleton.messaging.admin;
-
-import java.time.Duration;
-import java.time.Instant;
-import java.util.Optional;
-
-/**
- * Where a destructive operation records that it started, how far it got, and how it ended.
- *
- * The implementation this replaced was a {@code ConcurrentHashMap} registered by the starter as
- * the default. Two consequences followed, and both are worse than having no store at all because
- * the map made the platform look protected. A restart forgot every claim, so the same approval
- * could be executed again by the same process. And two replicas each had their own map, so both
- * could claim the same approval at the same moment and each believe it was the only one.
- *
- * Implementations must therefore be shared and durable, must enforce uniqueness on {@code
- * (approvalTicket, planDigest)}, and must hand out leases with a monotonic fencing token so a
- * process that stalled past its lease cannot write over the replica that took over from it.
- */
-public interface AdminOperationJournal {
-
- /**
- * Claims an operation, or resumes the previous attempt at it.
- *
- * @param approvalTicket the approval authorising the operation
- * @param planDigest the exact plan
- * @param operationId this execution's identity
- * @param leaseOwner the runtime claiming it
- * @param leaseDuration how long the lease holds before another runtime may take over
- * @param now the current instant
- * @return the lease, carrying the point to resume from
- * @throws dev.caskeleton.messaging.api.error.MessageAuthorizationException when the operation
- * already completed, or another runtime holds a live lease on it
- */
- AdminOperationLease begin(
- String approvalTicket,
- PlanDigest planDigest,
- String operationId,
- String leaseOwner,
- Duration leaseDuration,
- Instant now);
-
- /**
- * Records durable progress and extends the lease.
- *
- * @param lease the lease held
- * @param itemsCompleted how many items are now durably done
- * @param leaseDuration how much longer to hold the lease
- * @param now the current instant
- * @throws dev.caskeleton.messaging.api.error.MessageAuthorizationException when the lease has
- * been taken over by a newer token
- */
- void checkpoint(
- AdminOperationLease lease, int itemsCompleted, Duration leaseDuration, Instant now);
-
- /**
- * Marks the operation finished. The approval is spent.
- *
- * @param lease the lease held
- * @param itemsCompleted the final count
- * @param now the current instant
- */
- void complete(AdminOperationLease lease, int itemsCompleted, Instant now);
-
- /**
- * Marks the operation failed at its current checkpoint, leaving it resumable.
- *
- * @param lease the lease held
- * @param itemsCompleted how many items are durably done
- * @param failureCode a sanitised, bounded reason
- * @param now the current instant
- */
- void fail(AdminOperationLease lease, int itemsCompleted, String failureCode, Instant now);
-
- /**
- * Reads the journal entry for an operation.
- *
- * @param approvalTicket the approval
- * @param planDigest the plan
- * @return the record, when the operation has been journalled
- */
- Optional Declared rather than inferred so the starter can refuse to run a production profile on an
- * in-memory journal instead of discovering the gap during an incident.
- *
- * @return true when the journal is durable and shared
- */
- boolean isDurable();
-}
diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminOperationLease.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminOperationLease.java
deleted file mode 100644
index de2fb5a6..00000000
--- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminOperationLease.java
+++ /dev/null
@@ -1,55 +0,0 @@
-package dev.caskeleton.messaging.admin;
-
-import java.util.Objects;
-
-/**
- * The right to execute one journalled operation, and the point to resume it from.
- *
- * {@code resumeFrom} is the whole reason a lease is handed out rather than a boolean. A retry
- * after a crash is not a new execution of the approval — it is the same operation continuing, and
- * treating it as new is what republishes the items the first attempt already moved.
- *
- * @param approvalTicket the approval being executed
- * @param planDigest the plan being executed
- * @param operationId this execution's identity
- * @param leaseOwner the runtime holding the lease
- * @param leaseToken the fencing token; a write from an older token must be refused
- * @param resumeFrom how many items the previous attempt durably completed
- */
-public record AdminOperationLease(
- String approvalTicket,
- PlanDigest planDigest,
- String operationId,
- String leaseOwner,
- long leaseToken,
- int resumeFrom) {
-
- /** Validates the lease. */
- public AdminOperationLease {
- Objects.requireNonNull(planDigest, "planDigest must not be null");
- if (approvalTicket == null || approvalTicket.isBlank()) {
- throw new IllegalArgumentException("approvalTicket must not be blank");
- }
- if (operationId == null || operationId.isBlank()) {
- throw new IllegalArgumentException("operationId must not be blank");
- }
- if (leaseOwner == null || leaseOwner.isBlank()) {
- throw new IllegalArgumentException("leaseOwner must not be blank");
- }
- if (leaseToken < 1) {
- throw new IllegalArgumentException("a lease token starts at one");
- }
- if (resumeFrom < 0) {
- throw new IllegalArgumentException("resumeFrom must not be negative");
- }
- }
-
- /**
- * Reports whether this lease continues an earlier attempt.
- *
- * @return true when items were already completed
- */
- public boolean isResumption() {
- return resumeFrom > 0;
- }
-}
diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminOperationRecord.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminOperationRecord.java
deleted file mode 100644
index 752d862d..00000000
--- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/AdminOperationRecord.java
+++ /dev/null
@@ -1,63 +0,0 @@
-package dev.caskeleton.messaging.admin;
-
-import java.time.Instant;
-import java.util.Objects;
-import java.util.Optional;
-
-/**
- * One row of the destructive-operation journal.
- *
- * Keyed by {@code (approvalTicket, planDigest)} rather than by the ticket alone, because the
- * ticket alone cannot distinguish "this approval already ran" from "this approval is being reused
- * for a different plan" — and those need opposite answers.
- *
- * @param approvalTicket the approval that authorised the operation
- * @param planDigest the exact plan that was authorised
- * @param operationId the caller-side identity of this execution
- * @param state where the operation stands
- * @param itemsCompleted how many items are durably done
- * @param leaseOwner which runtime currently holds the lease
- * @param leaseToken the fencing token, incremented on every takeover
- * @param leaseExpiresAt when another runtime may take the lease over
- * @param startedAt when the operation first began
- * @param finishedAt when it reached a terminal state
- * @param failureCode the sanitised reason it failed, when it did
- */
-public record AdminOperationRecord(
- String approvalTicket,
- PlanDigest planDigest,
- String operationId,
- AdminOperationState state,
- int itemsCompleted,
- String leaseOwner,
- long leaseToken,
- Instant leaseExpiresAt,
- Instant startedAt,
- Optional The store this replaces recorded one fact — "this approval was claimed" — and recorded it
- * before any work happened. A run that died halfway had consumed its approval, left no record of
- * how far it got, and offered the operator two equally bad choices: request a fresh approval and
- * redo work that may already have been done, or leave the operation half-applied.
- */
-public enum AdminOperationState {
-
- /** Claimed and in progress. A lease is held; the checkpoint says how far it got. */
- STARTED,
-
- /** Every item finished. The approval is spent and must not run again. */
- COMPLETED,
-
- /** The run stopped before finishing. It may be resumed from its checkpoint under a new lease. */
- FAILED
-}
diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ApprovalGrant.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ApprovalGrant.java
deleted file mode 100644
index 7cd97ace..00000000
--- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ApprovalGrant.java
+++ /dev/null
@@ -1,98 +0,0 @@
-package dev.caskeleton.messaging.admin;
-
-import dev.caskeleton.messaging.api.destination.DestinationName;
-import java.time.Instant;
-import java.util.Objects;
-import java.util.Optional;
-
-/**
- * Everything an issuer signs when granting one destructive operation.
- *
- * {@link AdminApproval} carried a ticket, an approver, and a window. Nothing in it said which
- * operation, on which destination, against which topology, or up to what impact — so the same
- * approval authorised every plan presented inside the window, and the audit trail recorded a ticket
- * that proved nothing about what was executed.
- *
- * Every field here is part of the signed canonical form, which is what makes the grant
- * non-transferable: change the target, the topology version, the impact ceiling, or the plan, and
- * the signature no longer verifies.
- *
- * @param approval the ticket, approver, and validity window
- * @param requestedBy the operator who will execute it, kept separate from the approver
- * @param operation the destructive operation being authorised
- * @param source the destination read from
- * @param target the destination written to, when the operation has one
- * @param topologyVersion the topology the impact estimate was computed against
- * @param maxImpact the largest number of messages the approver agreed to
- * @param planDigest the fingerprint of the exact plan
- */
-public record ApprovalGrant(
- AdminApproval approval,
- String requestedBy,
- DestructiveOperation operation,
- DestinationName source,
- Optional Every field is length-prefixed rather than delimited. A delimiter can be smuggled into a
- * ticket or an identity to make two different grants render identically; a length prefix cannot.
- *
- * @return the canonical form
- */
- public String canonicalForm() {
- StringBuilder canonical = new StringBuilder("v1");
- appendField(canonical, approval.ticket());
- appendField(canonical, approval.approvedBy());
- appendField(canonical, requestedBy);
- appendField(canonical, operation.name());
- appendField(canonical, source.value());
- appendField(canonical, target.map(DestinationName::value).orElse(""));
- appendField(canonical, topologyVersion);
- appendField(canonical, Long.toString(maxImpact));
- appendField(canonical, planDigest.value());
- appendField(canonical, approval.approvedAt().toString());
- appendField(canonical, approval.validUntil().toString());
- return canonical.toString();
- }
-
- private static void appendField(StringBuilder canonical, String value) {
- canonical.append(value.length()).append(':').append(value);
- }
-
- /**
- * Reports whether the grant still authorises anything.
- *
- * @param now the current instant
- * @return true while inside the approval window
- */
- public boolean isValidAt(Instant now) {
- return approval.isValidAt(now);
- }
-}
diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ApprovalVerifier.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ApprovalVerifier.java
deleted file mode 100644
index a44fb021..00000000
--- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ApprovalVerifier.java
+++ /dev/null
@@ -1,29 +0,0 @@
-package dev.caskeleton.messaging.admin;
-
-import java.time.Instant;
-
-/**
- * The only thing that can turn a signed grant into a {@link VerifiedApproval}.
- *
- * An implementation must check, at minimum: the issuer's signature over {@link
- * ApprovalGrant#canonicalForm()}, that the approval window is open at {@code now}, and that the
- * digest the caller is about to execute is the digest that was signed. Everything else the grant
- * binds — operation, source, target, topology version, impact ceiling, approver-versus-operator
- * separation — is inside the canonical form, so a signature check covers them all at once.
- */
-public interface ApprovalVerifier {
-
- /**
- * Verifies a signed grant against the plan actually about to run.
- *
- * @param grant what the issuer signed
- * @param signature the issuer's signature over the grant's canonical form
- * @param executingDigest the digest of the plan the caller is about to execute
- * @param now the current instant
- * @return the verified approval
- * @throws dev.caskeleton.messaging.api.error.MessageAuthorizationException when anything about
- * the grant, the signature, the window, or the digest does not hold
- */
- VerifiedApproval verify(
- ApprovalGrant grant, String signature, PlanDigest executingDigest, Instant now);
-}
diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ApprovedRedrivePlan.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ApprovedRedrivePlan.java
deleted file mode 100644
index 7142a2b6..00000000
--- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ApprovedRedrivePlan.java
+++ /dev/null
@@ -1,95 +0,0 @@
-package dev.caskeleton.messaging.admin;
-
-import dev.caskeleton.messaging.api.destination.DestinationName;
-import dev.caskeleton.messaging.api.error.MessageAuthorizationException;
-import java.time.Instant;
-import java.util.Objects;
-
-/**
- * A redrive plan that a named human has approved.
- *
- * Carries {@code loopAcknowledged} separately from the approval itself. Approving a redrive of
- * 900 parked messages and approving a redrive that will re-fail 400 of them are different
- * decisions, and the second one needs the approver to have seen the number — so the plan cannot
- * execute on a loop-risking set unless that was acknowledged explicitly.
- *
- * @param plan the plan that was approved
- * @param approval the approval authorising it
- * @param loopAcknowledged whether the approver accepted the previously-redriven candidates
- */
-public record ApprovedRedrivePlan(
- RedrivePlan plan, VerifiedApproval approval, boolean loopAcknowledged) {
-
- /** Binds the approval to this exact plan at construction. */
- public ApprovedRedrivePlan {
- Objects.requireNonNull(plan, "plan must not be null");
- Objects.requireNonNull(approval, "approval must not be null");
- if (!approval.grant().planDigest().equals(plan.digest())) {
- throw new MessageAuthorizationException(
- "APPROVAL_PLAN_MISMATCH",
- "approval %s was issued for a different plan than the one it is attached to"
- .formatted(approval.ticket()));
- }
- if (approval.grant().operation() != DestructiveOperation.REDRIVE) {
- throw new MessageAuthorizationException(
- "APPROVAL_OPERATION_MISMATCH",
- "approval %s authorises %s, not a redrive"
- .formatted(approval.ticket(), approval.grant().operation()));
- }
- if (!approval.grant().source().equals(plan.request().source())
- || !approval.grant().target().equals(java.util.Optional.of(plan.request().target()))) {
- throw new MessageAuthorizationException(
- "APPROVAL_SOURCE_MISMATCH",
- "approval %s authorises %s to %s, not %s to %s"
- .formatted(
- approval.ticket(),
- approval.grant().source().value(),
- approval.grant().target().map(DestinationName::value).orElse("(none)"),
- plan.request().source().value(),
- plan.request().target().value()));
- }
- if (plan.candidates() > approval.grant().maxImpact()) {
- throw new MessageAuthorizationException(
- "APPROVAL_IMPACT_EXCEEDED",
- "the plan moves %d messages but the approver agreed to at most %d"
- .formatted(plan.candidates(), approval.grant().maxImpact()));
- }
- }
-
- /**
- * Refuses execution when the approval, the topology, or the loop risk no longer permits it.
- *
- * @param now the current instant
- * @param currentTopologyVersion the topology version at execution time
- * @throws MessageAuthorizationException when the plan may not execute
- */
- public void requireExecutable(Instant now, String currentTopologyVersion) {
- Objects.requireNonNull(now, "now must not be null");
- Objects.requireNonNull(currentTopologyVersion, "currentTopologyVersion must not be null");
-
- if (!approval.isValidAt(now)) {
- throw new MessageAuthorizationException(
- "APPROVAL_EXPIRED", "approval %s is not valid at %s".formatted(approval.ticket(), now));
- }
- if (!approval.grant().topologyVersion().equals(currentTopologyVersion)) {
- throw new MessageAuthorizationException(
- "TOPOLOGY_CHANGED_SINCE_APPROVAL",
- "approval %s was signed against topology %s but the broker is now at %s"
- .formatted(
- approval.ticket(), approval.grant().topologyVersion(), currentTopologyVersion));
- }
- if (!plan.topologyVersion().equals(currentTopologyVersion)) {
- throw new MessageAuthorizationException(
- "TOPOLOGY_CHANGED_SINCE_APPROVAL",
- "the plan was approved against topology %s but the broker is now at %s"
- .formatted(plan.topologyVersion(), currentTopologyVersion));
- }
- if (plan.risksALoop() && !loopAcknowledged) {
- throw new MessageAuthorizationException(
- "REDRIVE_LOOP_NOT_ACKNOWLEDGED",
- "%d of the %d candidates already failed a previous redrive; re-running them without "
- .formatted(plan.alreadyRedrivenCandidates(), plan.candidates())
- + "fixing the cause produces a loop that looks like progress");
- }
- }
-}
diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ApprovedReplayPlan.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ApprovedReplayPlan.java
deleted file mode 100644
index 54b4afeb..00000000
--- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ApprovedReplayPlan.java
+++ /dev/null
@@ -1,86 +0,0 @@
-package dev.caskeleton.messaging.admin;
-
-import dev.caskeleton.messaging.api.error.MessageAuthorizationException;
-import java.time.Instant;
-import java.util.Objects;
-
-/**
- * A replay plan that a named human has approved.
- *
- * A distinct type from {@link ReplayPlan} rather than a boolean on it. The execute method takes
- * this type, so an unapproved plan cannot reach it — the authorisation is enforced by the compiler
- * instead of by a runtime check somebody can forget to write.
- *
- * @param plan the plan that was approved
- * @param approval the approval authorising it
- */
-public record ApprovedReplayPlan(ReplayPlan plan, VerifiedApproval approval) {
-
- /** Binds the approval to this exact plan at construction. */
- public ApprovedReplayPlan {
- Objects.requireNonNull(plan, "plan must not be null");
- Objects.requireNonNull(approval, "approval must not be null");
- if (!approval.grant().planDigest().equals(plan.digest())) {
- // A genuine, verified approval for a different plan. Checking it here means the mismatch
- // cannot survive to the execute call under any code path.
- throw new MessageAuthorizationException(
- "APPROVAL_PLAN_MISMATCH",
- "approval %s was issued for a different plan than the one it is attached to"
- .formatted(approval.ticket()));
- }
- if (approval.grant().operation() != DestructiveOperation.REPLAY) {
- throw new MessageAuthorizationException(
- "APPROVAL_OPERATION_MISMATCH",
- "approval %s authorises %s, not a replay"
- .formatted(approval.ticket(), approval.grant().operation()));
- }
- if (!approval.grant().source().equals(plan.request().destination())) {
- throw new MessageAuthorizationException(
- "APPROVAL_SOURCE_MISMATCH",
- "approval %s authorises %s, not %s"
- .formatted(
- approval.ticket(),
- approval.grant().source().value(),
- plan.request().destination().value()));
- }
- if (plan.estimatedMessages() > approval.grant().maxImpact()) {
- throw new MessageAuthorizationException(
- "APPROVAL_IMPACT_EXCEEDED",
- "the plan moves about %d messages but the approver agreed to at most %d"
- .formatted(plan.estimatedMessages(), approval.grant().maxImpact()));
- }
- }
-
- /**
- * Refuses execution when the approval or the plan no longer applies.
- *
- * @param now the current instant
- * @param currentTopologyVersion the topology version at execution time
- * @throws MessageAuthorizationException when the approval has expired or the topology moved
- */
- public void requireExecutable(Instant now, String currentTopologyVersion) {
- Objects.requireNonNull(now, "now must not be null");
- Objects.requireNonNull(currentTopologyVersion, "currentTopologyVersion must not be null");
-
- if (!approval.isValidAt(now)) {
- throw new MessageAuthorizationException(
- "APPROVAL_EXPIRED", "approval %s is not valid at %s".formatted(approval.ticket(), now));
- }
- if (!approval.grant().topologyVersion().equals(currentTopologyVersion)) {
- throw new MessageAuthorizationException(
- "TOPOLOGY_CHANGED_SINCE_APPROVAL",
- "approval %s was signed against topology %s but the broker is now at %s"
- .formatted(
- approval.ticket(), approval.grant().topologyVersion(), currentTopologyVersion));
- }
- if (!plan.topologyVersion().equals(currentTopologyVersion)) {
- // Every number in the plan was computed against the old topology, so the approver agreed to
- // an impact estimate that no longer describes what would happen.
- throw new MessageAuthorizationException(
- "TOPOLOGY_CHANGED_SINCE_APPROVAL",
- "the plan was approved against topology %s but the broker is now at %s; the estimated "
- .formatted(plan.topologyVersion(), currentTopologyVersion)
- + "impact no longer applies and the plan must be rebuilt");
- }
- }
-}
diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/DestinationTopology.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/DestinationTopology.java
deleted file mode 100644
index cf639cf5..00000000
--- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/DestinationTopology.java
+++ /dev/null
@@ -1,46 +0,0 @@
-package dev.caskeleton.messaging.admin;
-
-import java.util.Map;
-import java.util.Objects;
-
-/**
- * What the broker actually reports for one destination.
- *
- * The counterpart to {@link TopologyManifest}: the manifest is what was declared, this is what
- * exists. Kept as a separate type rather than reusing the manifest so that a comparison cannot
- * accidentally compare a manifest with itself and report success.
- *
- * @param physicalName the broker-side name
- * @param partitions the observed partition count
- * @param replicationFactor the observed replication factor
- * @param configuration the observed configuration entries
- * @param exists whether the destination is present at all
- */
-public record DestinationTopology(
- String physicalName,
- int partitions,
- int replicationFactor,
- Map Enumerated so the guard is exhaustive rather than a list of {@code if} statements that a new
- * operation can quietly avoid.
- */
-public enum DestructiveOperation {
-
- /** Re-read a destination from an earlier position. */
- REPLAY,
-
- /** Move messages from a dead letter destination back to their source. */
- REDRIVE,
-
- /** Move a consumer group's committed position. */
- OFFSET_RESET,
-
- /** Discard the contents of a destination. */
- PURGE,
-
- /** Remove a destination entirely. */
- DELETE_DESTINATION
-}
diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/DestructiveOperationGuard.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/DestructiveOperationGuard.java
deleted file mode 100644
index edeb82ff..00000000
--- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/DestructiveOperationGuard.java
+++ /dev/null
@@ -1,95 +0,0 @@
-package dev.caskeleton.messaging.admin;
-
-import dev.caskeleton.messaging.api.destination.DestinationName;
-import dev.caskeleton.messaging.api.error.MessageAuthorizationException;
-import java.time.Instant;
-import java.util.Objects;
-import java.util.Optional;
-
-/**
- * The single gate every destructive messaging operation passes through.
- *
- * Four conditions, all required. The caller must hold the admin credential — an application
- * runtime does not, by construction. The approval must be present and inside its validity window.
- * And a dry run is always permitted, because the way to make operators plan before they act is to
- * make planning free.
- *
- * Centralised so that adding a new destructive operation means adding an enum constant, not
- * remembering to re-implement the checks.
- */
-public final class DestructiveOperationGuard {
-
- private final boolean adminCredentialPresent;
-
- /**
- * Creates a guard for a runtime.
- *
- * @param adminCredentialPresent whether this runtime holds the admin credential
- */
- public DestructiveOperationGuard(boolean adminCredentialPresent) {
- this.adminCredentialPresent = adminCredentialPresent;
- }
-
- /**
- * Authorises one destructive operation.
- *
- * @param operation the operation
- * @param destination the destination affected
- * @param approval the verified approval, when one was supplied
- * @param dryRun whether this is a plan-only run
- * @param now the current instant
- * @throws MessageAuthorizationException when the operation is not authorised
- */
- public void authorize(
- DestructiveOperation operation,
- DestinationName destination,
- Optional A shared secret rather than a public-key signature is a deliberate scope choice: the issuer is
- * the change-management system operated by the same organisation as the runtime, so key
- * distribution is already solved and the property that matters — that an operator cannot mint an
- * approval for themselves — holds as long as the key is not on the operator's machine. A public-key
- * verifier can be substituted by implementing {@link ApprovalVerifier}; nothing else in the
- * platform depends on how the signature is produced.
- *
- * Comparison is constant-time. A verifier that compares with {@code equals} leaks the signature
- * one byte at a time to a caller who can retry, which for an offline attacker with unlimited
- * attempts is the whole secret.
- */
-public final class HmacApprovalVerifier implements ApprovalVerifier {
-
- private static final String ALGORITHM = "HmacSHA256";
-
- private final byte[] issuingKey;
-
- /**
- * Creates a verifier over the issuing key.
- *
- * @param issuingKey the shared secret the approval issuer signs with
- */
- public HmacApprovalVerifier(byte[] issuingKey) {
- Objects.requireNonNull(issuingKey, "issuingKey must not be null");
- if (issuingKey.length < 32) {
- throw new IllegalArgumentException(
- "the approval issuing key must be at least 256 bits; a shorter key makes the signature"
- + " brute-forceable offline");
- }
- this.issuingKey = issuingKey.clone();
- }
-
- /**
- * Produces the signature an issuer would attach to a grant.
- *
- * Present because the issuer and the verifier must agree on the canonical form exactly, and a
- * second implementation of that agreement is a second thing to drift. Holding this key is what
- * makes a caller an issuer — it is not, and must not become, available to the runtime that
- * executes operations.
- *
- * @param grant the grant to sign
- * @return the hexadecimal signature
- */
- public String sign(ApprovalGrant grant) {
- Objects.requireNonNull(grant, "grant must not be null");
- return HexFormat.of().formatHex(mac(grant.canonicalForm()));
- }
-
- @Override
- public VerifiedApproval verify(
- ApprovalGrant grant, String signature, PlanDigest executingDigest, Instant now) {
- Objects.requireNonNull(grant, "grant must not be null");
- Objects.requireNonNull(signature, "signature must not be null");
- Objects.requireNonNull(executingDigest, "executingDigest must not be null");
- Objects.requireNonNull(now, "now must not be null");
-
- if (!grant.planDigest().equals(executingDigest)) {
- // The signature would verify: this is a genuine approval, for a different plan. Replaying one
- // approval across plans is the attack the digest binding exists to stop.
- throw new MessageAuthorizationException(
- "APPROVAL_PLAN_MISMATCH",
- "approval %s was issued for plan %s but the plan about to execute is %s"
- .formatted(
- grant.approval().ticket(), grant.planDigest().value(), executingDigest.value()));
- }
- if (!grant.isValidAt(now)) {
- throw new MessageAuthorizationException(
- "APPROVAL_EXPIRED",
- "approval %s is not valid at %s".formatted(grant.approval().ticket(), now));
- }
- byte[] presented;
- try {
- presented = HexFormat.of().parseHex(signature);
- } catch (IllegalArgumentException malformed) {
- throw new MessageAuthorizationException(
- "APPROVAL_SIGNATURE_INVALID", "the approval signature is not hexadecimal");
- }
- if (!MessageDigest.isEqual(mac(grant.canonicalForm()), presented)) {
- throw new MessageAuthorizationException(
- "APPROVAL_SIGNATURE_INVALID",
- ("approval %s does not verify against the issuing key; the grant was altered after it"
- + " was signed, or it was never issued")
- .formatted(grant.approval().ticket()));
- }
- return VerifiedApproval.of(grant);
- }
-
- private byte[] mac(String canonicalForm) {
- try {
- Mac mac = Mac.getInstance(ALGORITHM);
- mac.init(new SecretKeySpec(issuingKey, ALGORITHM));
- return mac.doFinal(canonicalForm.getBytes(StandardCharsets.UTF_8));
- } catch (java.security.GeneralSecurityException failure) {
- throw new IllegalStateException("HMAC-SHA256 is required of every Java runtime", failure);
- }
- }
-}
diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/PlanDigest.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/PlanDigest.java
deleted file mode 100644
index d11a4d1d..00000000
--- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/PlanDigest.java
+++ /dev/null
@@ -1,47 +0,0 @@
-package dev.caskeleton.messaging.admin;
-
-import java.nio.charset.StandardCharsets;
-import java.security.MessageDigest;
-import java.security.NoSuchAlgorithmException;
-import java.util.HexFormat;
-import java.util.Objects;
-
-/**
- * The fingerprint of exactly what an approver agreed to.
- *
- * An approval used to name a ticket and a window and nothing else, so it authorised any plan
- * presented within that window. The operator who got a redrive of one dead-letter destination
- * approved could execute a redrive of a different one with the same ticket, and every audit record
- * would look correct. Binding the signature to this digest is what makes an approval about a plan
- * rather than about a period of time.
- *
- * @param value the lowercase hexadecimal SHA-256 of the plan's canonical form
- */
-public record PlanDigest(String value) {
-
- /** Validates the digest shape. */
- public PlanDigest {
- Objects.requireNonNull(value, "value must not be null");
- if (!value.matches("[0-9a-f]{64}")) {
- throw new IllegalArgumentException("a plan digest is 64 lowercase hexadecimal characters");
- }
- }
-
- /**
- * Digests a plan's canonical form.
- *
- * @param canonicalForm the plan rendered deterministically, field by field
- * @return the digest
- */
- public static PlanDigest ofCanonical(String canonicalForm) {
- Objects.requireNonNull(canonicalForm, "canonicalForm must not be null");
- try {
- byte[] digest =
- MessageDigest.getInstance("SHA-256")
- .digest(canonicalForm.getBytes(StandardCharsets.UTF_8));
- return new PlanDigest(HexFormat.of().formatHex(digest));
- } catch (NoSuchAlgorithmException impossible) {
- throw new IllegalStateException("SHA-256 is required of every Java runtime", impossible);
- }
- }
-}
diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/RedrivePlan.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/RedrivePlan.java
deleted file mode 100644
index d462fb21..00000000
--- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/RedrivePlan.java
+++ /dev/null
@@ -1,86 +0,0 @@
-package dev.caskeleton.messaging.admin;
-
-import java.time.Instant;
-import java.util.Objects;
-
-/**
- * What a redrive would do, produced before anything is moved.
- *
- * {@code alreadyRedrivenCandidates} is the number that matters most. A message with a non-zero
- * redrive count has been sent back to its source before and failed again; redriving it a second
- * time without fixing the cause produces a loop that looks like progress in every dashboard.
- * Surfacing the count at plan time is what lets an operator notice before starting it.
- *
- * @param request the request this plan was built from
- * @param candidates how many messages are eligible
- * @param alreadyRedrivenCandidates how many of those have been redriven before
- * @param plannedAt when the plan was produced
- * @param topologyVersion the topology the estimate was computed against
- */
-public record RedrivePlan(
- RedriveRequest request,
- int candidates,
- int alreadyRedrivenCandidates,
- Instant plannedAt,
- String topologyVersion) {
-
- public RedrivePlan {
- Objects.requireNonNull(request, "request must not be null");
- Objects.requireNonNull(plannedAt, "plannedAt must not be null");
- if (candidates < 0) {
- throw new IllegalArgumentException("candidates must not be negative");
- }
- if (alreadyRedrivenCandidates < 0 || alreadyRedrivenCandidates > candidates) {
- throw new IllegalArgumentException(
- "alreadyRedrivenCandidates must be between 0 and the candidate count");
- }
- if (topologyVersion == null || topologyVersion.isBlank()) {
- throw new IllegalArgumentException("topologyVersion must not be blank");
- }
- }
-
- /**
- * The fingerprint an approver's signature is bound to.
- *
- * Source, target, batch size, and both candidate counts are in it, so an approval for a
- * redrive of one dead-letter destination cannot be presented for a redrive of another.
- *
- * @return the digest of this exact plan
- */
- public PlanDigest digest() {
- return PlanDigest.ofCanonical(
- String.join(
- "|",
- "REDRIVE",
- request.redriveId().toString(),
- request.source().value(),
- request.target().value(),
- Integer.toString(request.batchSize()),
- Integer.toString(candidates),
- Integer.toString(alreadyRedrivenCandidates),
- topologyVersion));
- }
-
- /**
- * Reports whether this redrive would replay messages that already failed a redrive.
- *
- * @return true when any candidate has been redriven before
- */
- public boolean risksALoop() {
- return alreadyRedrivenCandidates > 0;
- }
-
- /**
- * Returns a one-line operator-facing summary of the impact.
- *
- * @return the sanitized summary
- */
- public String describeImpact() {
- String loop =
- risksALoop()
- ? ", %d of which already failed a previous redrive".formatted(alreadyRedrivenCandidates)
- : "";
- return "redrive %d messages from %s to %s%s"
- .formatted(candidates, request.source().value(), request.target().value(), loop);
- }
-}
diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/RedriveRequest.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/RedriveRequest.java
deleted file mode 100644
index fd924af6..00000000
--- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/RedriveRequest.java
+++ /dev/null
@@ -1,37 +0,0 @@
-package dev.caskeleton.messaging.admin;
-
-import dev.caskeleton.messaging.api.destination.DestinationName;
-import java.util.Objects;
-import java.util.UUID;
-
-/**
- * A request to move messages from a dead letter destination back to their source.
- *
- * The redrive id is a separate identifier from the message id, and both travel with the message.
- * Reusing the message id as the operation id would make "this message was redriven" and "this
- * message is a different message" indistinguishable, and an operator could not tell a redrive loop
- * from ordinary traffic.
- *
- * @param redriveId the operation identity
- * @param source the dead letter destination to drain
- * @param target the destination to publish back to
- * @param batchSize how many messages to move per pass
- * @param dryRun whether to plan without moving anything
- */
-public record RedriveRequest(
- UUID redriveId, DestinationName source, DestinationName target, int batchSize, boolean dryRun) {
-
- private static final int MAX_BATCH = 100;
-
- public RedriveRequest {
- Objects.requireNonNull(redriveId, "redriveId must not be null");
- Objects.requireNonNull(source, "source must not be null");
- Objects.requireNonNull(target, "target must not be null");
- if (source.equals(target)) {
- throw new IllegalArgumentException("a redrive cannot target its own source");
- }
- if (batchSize < 1 || batchSize > MAX_BATCH) {
- throw new IllegalArgumentException("redrive batch size must be between 1 and " + MAX_BATCH);
- }
- }
-}
diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/RedriveResult.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/RedriveResult.java
deleted file mode 100644
index e0896eb6..00000000
--- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/RedriveResult.java
+++ /dev/null
@@ -1,51 +0,0 @@
-package dev.caskeleton.messaging.admin;
-
-import java.time.Duration;
-import java.util.Objects;
-import java.util.UUID;
-
-/**
- * What a redrive actually did.
- *
- * {@code stillParked} is not simply {@code candidates - moved}. A message stays parked when its
- * republish did not confirm, and the redrive deliberately leaves it there rather than settling it —
- * the DLQ-confirm-before-settle rule applies to a redrive exactly as it does to the original
- * dead-lettering, because a redrive that settles an unconfirmed republish deletes the last copy.
- *
- * @param redriveId the operation identity
- * @param candidates how many messages were eligible
- * @param moved how many were republished and settled
- * @param stillParked how many stayed on the dead letter destination
- * @param elapsed how long the redrive took
- * @param dryRun whether nothing was actually moved
- */
-public record RedriveResult(
- UUID redriveId, int candidates, int moved, int stillParked, Duration elapsed, boolean dryRun) {
-
- public RedriveResult {
- Objects.requireNonNull(redriveId, "redriveId must not be null");
- Objects.requireNonNull(elapsed, "elapsed must not be null");
- if (candidates < 0 || moved < 0 || stillParked < 0) {
- throw new IllegalArgumentException("redrive counters must not be negative");
- }
- if (moved + stillParked > candidates) {
- throw new IllegalArgumentException(
- "a redrive cannot account for more messages than it had candidates");
- }
- if (dryRun && moved > 0) {
- throw new IllegalArgumentException("a dry run must not move anything");
- }
- }
-
- /**
- * Reports whether every candidate was accounted for.
- *
- * An unaccounted message is a bug, not a partial success: it was neither republished nor left
- * parked, which means the redrive lost track of it.
- *
- * @return true when moved plus still-parked covers every candidate
- */
- public boolean isFullyAccounted() {
- return moved + stillParked == candidates;
- }
-}
diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ReplayPlan.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ReplayPlan.java
deleted file mode 100644
index 4e6cb57b..00000000
--- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ReplayPlan.java
+++ /dev/null
@@ -1,79 +0,0 @@
-package dev.caskeleton.messaging.admin;
-
-import java.time.Instant;
-import java.util.Objects;
-
-/**
- * What a replay would do, produced before anything is read.
- *
- * The plan exists so the estimate can be reviewed. "Replay from yesterday" is a sentence; "this
- * will re-deliver 4.2 million messages into the live consumer group" is a decision, and the only
- * moment an operator can make it is before the replay starts.
- *
- * {@code topologyVersion} is captured here and re-checked at execution. A plan approved against
- * one topology and executed against another is estimating a different thing entirely — a partition
- * count that changed in between invalidates every number in this record.
- *
- * @param request the request this plan was built from
- * @param estimatedMessages how many messages the window covers
- * @param plannedAt when the plan was produced
- * @param topologyVersion the topology the estimate was computed against
- * @param targetsLiveConsumerGroup whether the replay would feed the live group rather than an
- * isolated one
- */
-public record ReplayPlan(
- ReplayRequest request,
- long estimatedMessages,
- Instant plannedAt,
- String topologyVersion,
- boolean targetsLiveConsumerGroup) {
-
- public ReplayPlan {
- Objects.requireNonNull(request, "request must not be null");
- Objects.requireNonNull(plannedAt, "plannedAt must not be null");
- if (estimatedMessages < 0) {
- throw new IllegalArgumentException("estimatedMessages must not be negative");
- }
- if (topologyVersion == null || topologyVersion.isBlank()) {
- throw new IllegalArgumentException("topologyVersion must not be blank");
- }
- }
-
- /**
- * The fingerprint an approver's signature is bound to.
- *
- * Every field that changes what would happen is in it. An approval signed over this digest
- * cannot be presented for a plan that reads a different destination, targets a different consumer
- * group, starts from a different position, or estimates a different impact.
- *
- * @return the digest of this exact plan
- */
- public PlanDigest digest() {
- return PlanDigest.ofCanonical(
- String.join(
- "|",
- "REPLAY",
- request.replayId().toString(),
- request.destination().value(),
- Boolean.toString(request.isolatedConsumerGroup()),
- request.from().toString(),
- request.to().map(Object::toString).orElse(""),
- Long.toString(estimatedMessages),
- topologyVersion,
- Boolean.toString(targetsLiveConsumerGroup)));
- }
-
- /**
- * Returns a one-line operator-facing summary of the impact.
- *
- * @return the sanitized summary
- */
- public String describeImpact() {
- return "replay %s from %s: about %d messages into %s"
- .formatted(
- request.destination().value(),
- request.from(),
- estimatedMessages,
- targetsLiveConsumerGroup ? "the LIVE consumer group" : "an isolated group");
- }
-}
diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ReplayRequest.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ReplayRequest.java
deleted file mode 100644
index 055bee1a..00000000
--- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/ReplayRequest.java
+++ /dev/null
@@ -1,36 +0,0 @@
-package dev.caskeleton.messaging.admin;
-
-import dev.caskeleton.messaging.api.destination.DestinationName;
-import java.time.Instant;
-import java.util.Objects;
-import java.util.Optional;
-import java.util.UUID;
-
-/**
- * A request to re-read a destination from an earlier position.
- *
- * @param replayId the operation identity
- * @param destination the destination to replay
- * @param from the replay start point
- * @param to the replay end point, when bounded
- * @param isolatedConsumerGroup whether to replay into a throwaway group
- * @param dryRun whether to plan without reading anything
- */
-public record ReplayRequest(
- UUID replayId,
- DestinationName destination,
- Instant from,
- Optional Reports the delivered count against the plan's estimate. They routinely differ — retention may
- * have expired part of the window, or the stream may have grown while the plan was being approved —
- * and the difference is the operator's signal that the replay covered something other than what was
- * approved.
- *
- * @param replayId the operation identity
- * @param estimatedMessages what the plan predicted
- * @param deliveredMessages what was actually re-delivered
- * @param elapsed how long the replay took
- * @param completed whether the whole window was covered
- * @param dryRun whether nothing was actually read
- */
-public record ReplayResult(
- UUID replayId,
- long estimatedMessages,
- long deliveredMessages,
- Duration elapsed,
- boolean completed,
- boolean dryRun) {
-
- public ReplayResult {
- Objects.requireNonNull(replayId, "replayId must not be null");
- Objects.requireNonNull(elapsed, "elapsed must not be null");
- if (estimatedMessages < 0 || deliveredMessages < 0) {
- throw new IllegalArgumentException("replay counters must not be negative");
- }
- if (dryRun && deliveredMessages > 0) {
- throw new IllegalArgumentException("a dry run must not deliver anything");
- }
- }
-
- /**
- * Reports whether the replay covered materially less than was approved.
- *
- * @return true when fewer than 90% of the estimated messages were delivered
- */
- public boolean fellShortOfTheEstimate() {
- return completed && estimatedMessages > 0 && deliveredMessages * 10 < estimatedMessages * 9;
- }
-}
diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/TopologyIssue.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/TopologyIssue.java
deleted file mode 100644
index fdd3e4c7..00000000
--- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/TopologyIssue.java
+++ /dev/null
@@ -1,82 +0,0 @@
-package dev.caskeleton.messaging.admin;
-
-import java.util.Objects;
-
-/**
- * One discrepancy between a declared topology and what the broker actually has.
- *
- * Severity is part of the finding because the two kinds behave differently at startup. A {@link
- * Severity#BLOCKING} issue means the destination cannot deliver its declared guarantee —
- * replication factor 1 on a destination promising durability is not a warning, it is a promise the
- * platform cannot keep — so the context refuses to start. A {@link Severity#ADVISORY} issue is a
- * drift worth reporting that does not break a guarantee.
- *
- * @param destination the logical destination
- * @param attribute the topology attribute that differs
- * @param declared what the manifest declared
- * @param actual what the broker reported
- * @param severity how the platform should react
- */
-public record TopologyIssue(
- String destination, String attribute, String declared, String actual, Severity severity) {
-
- /** How the platform reacts to a topology discrepancy. */
- public enum Severity {
- /** The destination cannot deliver a declared guarantee; startup must fail. */
- BLOCKING,
- /** Drift worth reporting that does not break a guarantee. */
- ADVISORY
- }
-
- public TopologyIssue {
- Objects.requireNonNull(severity, "severity must not be null");
- requireText(destination, "destination");
- requireText(attribute, "attribute");
- requireText(declared, "declared");
- requireText(actual, "actual");
- }
-
- /**
- * Creates a blocking issue.
- *
- * @param destination the logical destination
- * @param attribute the differing attribute
- * @param declared the declared value
- * @param actual the observed value
- * @return the issue
- */
- public static TopologyIssue blocking(
- String destination, String attribute, String declared, String actual) {
- return new TopologyIssue(destination, attribute, declared, actual, Severity.BLOCKING);
- }
-
- /**
- * Creates an advisory issue.
- *
- * @param destination the logical destination
- * @param attribute the differing attribute
- * @param declared the declared value
- * @param actual the observed value
- * @return the issue
- */
- public static TopologyIssue advisory(
- String destination, String attribute, String declared, String actual) {
- return new TopologyIssue(destination, attribute, declared, actual, Severity.ADVISORY);
- }
-
- /**
- * Returns a one-line operator-facing description.
- *
- * @return the sanitized description
- */
- public String describe() {
- return "%s: %s declared %s but the broker has %s"
- .formatted(destination, attribute, declared, actual);
- }
-
- private static void requireText(String value, String field) {
- if (value == null || value.isBlank()) {
- throw new IllegalArgumentException(field + " must not be blank");
- }
- }
-}
diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/TopologyManagementMode.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/TopologyManagementMode.java
deleted file mode 100644
index 47d530cd..00000000
--- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/TopologyManagementMode.java
+++ /dev/null
@@ -1,37 +0,0 @@
-package dev.caskeleton.messaging.admin;
-
-import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
-
-/**
- * Whether the application may create broker topology, or only check it.
- *
- * {@link #VALIDATE_ONLY} in production, always. An application that auto-creates topology will
- * auto-create it after a configuration typo too, and the topic it makes is indistinguishable from a
- * real one — same broker, same client, same metrics — while carrying the broker's default partition
- * count and replication factor instead of the ones the destination needs. The failure surfaces
- * weeks later as data loss on a partition that was never replicated.
- */
-public enum TopologyManagementMode {
-
- /** Compare the declared topology against the broker and fail on a mismatch. */
- VALIDATE_ONLY,
-
- /** Create missing topology. Permitted outside production only. */
- CREATE_IF_MISSING;
-
- /**
- * Refuses auto-creation on a production runtime.
- *
- * @param production whether this runtime is production
- * @throws MessagingConfigurationException when auto-creation is configured in production
- */
- public void requireSafeFor(boolean production) {
- if (production && this == CREATE_IF_MISSING) {
- throw new MessagingConfigurationException(
- "AUTO_CREATE_IN_PRODUCTION",
- "topology auto-creation is not permitted in production: a mistyped destination would be "
- + "created with the broker's default partition count and replication factor, and "
- + "would look exactly like a correctly provisioned one");
- }
- }
-}
diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/TopologyManifest.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/TopologyManifest.java
deleted file mode 100644
index 7466a17d..00000000
--- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/TopologyManifest.java
+++ /dev/null
@@ -1,76 +0,0 @@
-package dev.caskeleton.messaging.admin;
-
-import java.util.List;
-import java.util.Map;
-import java.util.Objects;
-
-/**
- * The declared shape of a destination's broker topology.
- *
- * Production topology is created by infrastructure code and only validated by the
- * application. An application that creates topology on startup will happily create it in the wrong
- * place after a configuration mistake, and the resulting topic looks exactly like a real one.
- *
- * @param destination the logical destination
- * @param physicalName the broker-side name
- * @param partitions the expected partition count, where the broker has partitions
- * @param replicationFactor the expected replication factor
- * @param requiredConfiguration configuration entries that must match exactly
- */
-public record TopologyManifest(
- String destination,
- String physicalName,
- int partitions,
- int replicationFactor,
- Map Reports both severities together rather than failing on the first blocking issue. An operator
- * fixing a topology wants the whole list — fixing one attribute, redeploying, and discovering the
- * next one is how a ten-minute fix becomes an afternoon.
- *
- * @param issues every discrepancy found
- * @param destinationsChecked how many destinations were compared
- */
-public record TopologyValidationReport(List The approved-plan types used to hold a plain {@code AdminApproval} record with a public
- * constructor, so "this plan was approved" was a claim the caller made about itself. Any code that
- * could reach the execute method could write {@code new AdminApproval("TICKET-1", "someone", now,
- * later)} and the platform believed it.
- *
- * This class has no public constructor and no public factory. The only way to obtain one is to
- * present a grant and a signature to a verifier, which is exactly the property the type is for:
- * holding a {@code VerifiedApproval} is itself the evidence that verification happened.
- */
-public final class VerifiedApproval {
-
- private final ApprovalGrant grant;
-
- private VerifiedApproval(ApprovalGrant grant) {
- this.grant = Objects.requireNonNull(grant, "grant must not be null");
- }
-
- /**
- * Mints a verified approval. Package-private on purpose: only a verifier in this package may call
- * it, so the type cannot be forged from application or adapter code.
- */
- static VerifiedApproval of(ApprovalGrant grant) {
- return new VerifiedApproval(grant);
- }
-
- /**
- * The grant that was verified.
- *
- * @return the grant
- */
- public ApprovalGrant grant() {
- return grant;
- }
-
- /**
- * The approval ticket, for audit records and journal keys.
- *
- * @return the ticket
- */
- public String ticket() {
- return grant.approval().ticket();
- }
-
- /**
- * Who approved the operation.
- *
- * @return the approver identity
- */
- public String approvedBy() {
- return grant.approval().approvedBy();
- }
-
- /**
- * Reports whether the approval window is still open.
- *
- * @param now the current instant
- * @return true while inside the window
- */
- public boolean isValidAt(Instant now) {
- return grant.isValidAt(now);
- }
-
- @Override
- public boolean equals(Object other) {
- return other instanceof VerifiedApproval verified && grant.equals(verified.grant);
- }
-
- @Override
- public int hashCode() {
- return grant.hashCode();
- }
-
- @Override
- public String toString() {
- // Deliberately not the whole grant: this string reaches logs, and the plan digest plus the
- // ticket identify the operation without restating who approved what to an audience that has
- // not been authorised to read it.
- return "VerifiedApproval[" + ticket() + " " + grant.planDigest().value().substring(0, 12) + "]";
- }
-}
diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/BrokerTopologyInspector.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/BrokerTopologyInspector.java
deleted file mode 100644
index 27a86aa5..00000000
--- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/BrokerTopologyInspector.java
+++ /dev/null
@@ -1,33 +0,0 @@
-package dev.caskeleton.messaging.admin.runtime;
-
-import dev.caskeleton.messaging.admin.DestinationTopology;
-import java.util.Optional;
-
-/**
- * Reads the broker's current topology.
- *
- * Read-only by construction. The inspector is what the application's own credential uses, and
- * that credential holds no destructive grant, so the type exposes no way to create, alter, or
- * delete — an application cannot reach a destructive operation even by mistake because there is no
- * method to reach.
- */
-public interface BrokerTopologyInspector {
-
- /**
- * Describes one destination.
- *
- * @param physicalName the broker-side name
- * @return the observed topology, absent when the broker has no such destination
- */
- Optional Used to invalidate an approved plan whose impact estimate was computed against an earlier
- * shape. Any value that changes when the topology changes is sufficient; it is never parsed.
- *
- * @return the topology version
- */
- String topologyVersion();
-}
diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/CompositeTopologyValidator.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/CompositeTopologyValidator.java
deleted file mode 100644
index d12e912e..00000000
--- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/CompositeTopologyValidator.java
+++ /dev/null
@@ -1,52 +0,0 @@
-package dev.caskeleton.messaging.admin.runtime;
-
-import dev.caskeleton.messaging.admin.DestinationTopology;
-import dev.caskeleton.messaging.admin.TopologyIssue;
-import dev.caskeleton.messaging.admin.TopologyManifest;
-import dev.caskeleton.messaging.admin.TopologyValidationReport;
-import java.util.ArrayList;
-import java.util.List;
-import java.util.Objects;
-
-/**
- * Validates every declared topology in one pass and reports the whole result.
- *
- * Collects all issues rather than stopping at the first blocking one. An operator fixing a
- * topology mismatch wants the complete list — discovering the next problem only after a redeploy
- * turns one fix into a sequence of them, and each redeploy is another restart of a production
- * service.
- */
-public final class CompositeTopologyValidator {
-
- private final BrokerTopologyInspector inspector;
- private final TopologyValidator validator = new TopologyValidator();
-
- /**
- * Creates a validator over a broker inspector.
- *
- * @param inspector reads the broker's current topology
- */
- public CompositeTopologyValidator(BrokerTopologyInspector inspector) {
- this.inspector = Objects.requireNonNull(inspector, "inspector must not be null");
- }
-
- /**
- * Compares every manifest against the broker.
- *
- * @param manifests the declared topologies
- * @return the complete report
- */
- public TopologyValidationReport validate(List Execution runs four checks, in this order, and the order is the point.
- *
- * The journal entry is written before the work rather than after it. Writing it
- * afterwards leaves a window where a second execution starts while the first is still running,
- * which is precisely the double-redrive the journal exists to prevent.
- *
- * Writing it first used to have a cost the previous store never paid: an operation that died
- * halfway had consumed its approval and left no record of how far it got. The journal keeps a
- * checkpoint and hands back a lease that says where to resume, so a retry continues the same
- * operation instead of either redoing it or requiring a new approval.
- */
-public final class DefaultMessagingAdminService implements MessagingAdminService {
-
- /**
- * How long a runtime holds an operation before another may take it over.
- *
- * Long enough that a slow batch does not lose its lease mid-flight, short enough that a dead
- * replica does not park an approval for an hour.
- */
- private static final Duration LEASE_DURATION = Duration.ofMinutes(5);
-
- private final CompositeTopologyValidator topologyValidator;
- private final BrokerTopologyInspector inspector;
- private final AdminOperationJournal journal;
- private final String leaseOwner;
- private final ReplayService replayService;
- private final RedriveService redriveService;
- private final Supplier The journal is read by operators during incidents and its contents outlive the process. A
- * raw exception message can carry a destination, a payload fragment, or a credential from a
- * driver's own error text, so only the platform's own code or the exception's simple name goes
- * in.
- */
- private static String failureCodeOf(RuntimeException failure) {
- if (failure instanceof dev.caskeleton.messaging.api.error.MessagingException messaging) {
- return messaging.failure().code();
- }
- return failure.getClass().getSimpleName();
- }
-
- /** Estimates how many messages a replay would re-deliver. */
- @FunctionalInterface
- public interface ReplayEstimator {
-
- /**
- * Estimates a replay's message count without reading anything.
- *
- * @param request the replay request
- * @return the estimated count
- */
- long estimate(ReplayRequest request);
- }
-
- /** How many messages a redrive would move, and how many already failed one. */
- record RedriveEstimate(int candidates, int alreadyRedriven) {}
-
- /** Estimates a redrive's candidates. */
- @FunctionalInterface
- public interface RedriveEstimator {
-
- /**
- * Estimates a redrive's candidates without moving anything.
- *
- * @param request the redrive request
- * @return the estimate
- */
- RedriveEstimate estimate(RedriveRequest request);
- }
-}
diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/DestructiveMessagingAdmin.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/DestructiveMessagingAdmin.java
deleted file mode 100644
index a853d31d..00000000
--- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/DestructiveMessagingAdmin.java
+++ /dev/null
@@ -1,82 +0,0 @@
-package dev.caskeleton.messaging.admin.runtime;
-
-import dev.caskeleton.messaging.admin.DestructiveOperation;
-import dev.caskeleton.messaging.admin.VerifiedApproval;
-import dev.caskeleton.messaging.api.destination.DestinationName;
-import java.time.Duration;
-import java.time.Instant;
-import java.util.Objects;
-
-/**
- * The operations that destroy data an application cannot recreate.
- *
- * A separate interface from {@link MessagingAdminService}, and no bean for it is ever registered
- * in an application runtime. The separation is the control: an application that never receives this
- * type cannot purge a topic even if every other guard is bypassed, because the method does not
- * exist on anything it holds.
- *
- * Each operation takes an {@link Approved} argument rather than an approval parameter, so the
- * authorisation cannot be forgotten at a call site — there is no way to call these without one.
- */
-public interface DestructiveMessagingAdmin {
-
- /** An authorised destructive request. */
- record Approved(
- DestructiveOperation operation,
- DestinationName destination,
- VerifiedApproval approval,
- long estimatedMessagesAffected) {
-
- public Approved {
- Objects.requireNonNull(operation, "operation must not be null");
- Objects.requireNonNull(destination, "destination must not be null");
- Objects.requireNonNull(approval, "approval must not be null");
- if (estimatedMessagesAffected < 0) {
- throw new IllegalArgumentException("estimatedMessagesAffected must not be negative");
- }
- }
- }
-
- /** What a destructive operation did. */
- record DestructiveResult(
- DestructiveOperation operation,
- DestinationName destination,
- long messagesAffected,
- Duration elapsed,
- Instant executedAt) {
-
- public DestructiveResult {
- Objects.requireNonNull(operation, "operation must not be null");
- Objects.requireNonNull(destination, "destination must not be null");
- Objects.requireNonNull(elapsed, "elapsed must not be null");
- Objects.requireNonNull(executedAt, "executedAt must not be null");
- if (messagesAffected < 0) {
- throw new IllegalArgumentException("messagesAffected must not be negative");
- }
- }
- }
-
- /**
- * Moves a consumer group's committed position.
- *
- * @param request the authorised request
- * @return what the reset did
- */
- DestructiveResult resetOffset(Approved request);
-
- /**
- * Discards the messages a destination currently holds.
- *
- * @param request the authorised request
- * @return what the purge did
- */
- DestructiveResult purge(Approved request);
-
- /**
- * Removes a destination entirely.
- *
- * @param request the authorised request
- * @return what the deletion did
- */
- DestructiveResult deleteDestination(Approved request);
-}
diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/InMemoryAdminOperationJournal.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/InMemoryAdminOperationJournal.java
deleted file mode 100644
index 574dfa57..00000000
--- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/InMemoryAdminOperationJournal.java
+++ /dev/null
@@ -1,237 +0,0 @@
-package dev.caskeleton.messaging.admin.runtime;
-
-import dev.caskeleton.messaging.admin.AdminOperationJournal;
-import dev.caskeleton.messaging.admin.AdminOperationLease;
-import dev.caskeleton.messaging.admin.AdminOperationRecord;
-import dev.caskeleton.messaging.admin.AdminOperationState;
-import dev.caskeleton.messaging.admin.PlanDigest;
-import dev.caskeleton.messaging.api.error.MessageAuthorizationException;
-import java.time.Duration;
-import java.time.Instant;
-import java.util.List;
-import java.util.Map;
-import java.util.Objects;
-import java.util.Optional;
-import java.util.concurrent.ConcurrentHashMap;
-
-/**
- * A single-process journal, for tests and for local development.
- *
- * It reports {@link #isDurable()} as false, and the starter refuses to run a production profile
- * on a journal that says so. That declaration is the point of this class existing at all: the
- * previous in-memory store was registered as the production default and nothing distinguished it
- * from a shared one, so the gap was invisible until two replicas executed the same approval.
- *
- * The semantics are otherwise the real ones — uniqueness on {@code (ticket, digest)}, lease
- * takeover with a monotonic token, resume from checkpoint — so a test that passes here is testing
- * the protocol rather than a simplification of it.
- */
-public final class InMemoryAdminOperationJournal implements AdminOperationJournal {
-
- private final Map Every mutating operation is split into plan and execute, and the execute methods take an
- * {@code Approved*} type. A caller cannot execute something it has not planned, because it has no
- * way to construct the argument — the plan/approve/execute sequence is enforced by the types rather
- * than by a runtime check.
- *
- * Destructive operations live in {@link DestructiveMessagingAdmin}, a separate interface that an
- * application runtime never receives a bean for. Splitting them means a compromised handler that
- * somehow reaches this service still has no method that deletes anything.
- */
-public interface MessagingAdminService {
-
- /**
- * Compares every declared topology against the broker.
- *
- * @return the discrepancies found
- */
- TopologyValidationReport validateTopology();
-
- /**
- * Estimates what a replay would do, without reading anything.
- *
- * @param request the replay request
- * @return the plan, including its impact estimate
- */
- ReplayPlan planReplay(ReplayRequest request);
-
- /**
- * Executes an approved replay.
- *
- * @param plan the approved plan
- * @return what the replay actually did
- */
- ReplayResult executeReplay(ApprovedReplayPlan plan);
-
- /**
- * Estimates what a redrive would do, without moving anything.
- *
- * @param request the redrive request
- * @return the plan, including how many candidates already failed a redrive
- */
- RedrivePlan planRedrive(RedriveRequest request);
-
- /**
- * Executes an approved redrive.
- *
- * @param plan the approved plan
- * @return what the redrive actually did
- */
- RedriveResult executeRedrive(ApprovedRedrivePlan plan);
-}
diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/RedriveReport.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/RedriveReport.java
deleted file mode 100644
index 3d76d3cf..00000000
--- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/RedriveReport.java
+++ /dev/null
@@ -1,18 +0,0 @@
-package dev.caskeleton.messaging.admin.runtime;
-
-/**
- * What one redrive pass did.
- *
- * @param candidates how many messages were eligible
- * @param moved how many were republished and settled
- * @param failed how many did not confirm and stay parked
- * @param dryRun whether this was a plan-only run
- */
-public record RedriveReport(int candidates, int moved, int failed, boolean dryRun) {
-
- public RedriveReport {
- if (candidates < 0 || moved < 0 || failed < 0) {
- throw new IllegalArgumentException("redrive counters must not be negative");
- }
- }
-}
diff --git a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/RedriveService.java b/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/RedriveService.java
deleted file mode 100644
index 8079d8e9..00000000
--- a/src/platforms/messaging/messaging-admin/src/main/java/dev/caskeleton/messaging/admin/runtime/RedriveService.java
+++ /dev/null
@@ -1,210 +0,0 @@
-package dev.caskeleton.messaging.admin.runtime;
-
-import dev.caskeleton.messaging.admin.DestructiveOperation;
-import dev.caskeleton.messaging.admin.DestructiveOperationGuard;
-import dev.caskeleton.messaging.admin.RedriveRequest;
-import dev.caskeleton.messaging.admin.VerifiedApproval;
-import dev.caskeleton.messaging.api.MessageId;
-import dev.caskeleton.messaging.api.publish.PublishCompletion;
-import dev.caskeleton.messaging.api.publish.PublishResult;
-import java.time.Instant;
-import java.util.ArrayList;
-import java.util.List;
-import java.util.Objects;
-import java.util.Optional;
-
-/**
- * Moves messages from a dead letter destination back to their source.
- *
- * A redrive is a publish followed by a settlement, in that order, exactly like dead lettering in
- * reverse. A message whose republish did not confirm stays in the dead letter destination: losing
- * it on the way back would be the one outcome worse than leaving it parked.
- *
- * The redrive id and a redrive counter travel with each message. Without them a message that
- * fails again is indistinguishable from a new one, and a redrive loop is invisible until the dead
- * letter destination is full.
- */
-public final class RedriveService {
-
- private final DestructiveOperationGuard guard;
- private final RedriveSource source;
- private final RedrivePublisher publisher;
- private final AuditSink audit;
-
- /**
- * Creates a redrive service.
- *
- * @param guard the destructive operation guard
- * @param source reads and settles dead letter messages
- * @param publisher republishes to the target destination
- * @param audit records the operation
- */
- public RedriveService(
- DestructiveOperationGuard guard,
- RedriveSource source,
- RedrivePublisher publisher,
- AuditSink audit) {
- this.guard = Objects.requireNonNull(guard, "guard must not be null");
- this.source = Objects.requireNonNull(source, "source must not be null");
- this.publisher = Objects.requireNonNull(publisher, "publisher must not be null");
- this.audit = Objects.requireNonNull(audit, "audit must not be null");
- }
-
- /**
- * Runs one redrive pass.
- *
- * @param request what to move
- * @param approval the verified approval, when one was supplied
- * @param subject the operator identity
- * @param now the current instant
- * @return what the pass did
- */
- public RedriveReport redrive(
- RedriveRequest request, Optional Three things were wrong with running this as a plain loop. A synchronous failure from the
- * publisher — a broker that refuses the connection rather than the message — propagated out of
- * the loop, so the remaining candidates were never attempted and the audit record was never
- * written: the operation left no trace of the items it had already moved. A retry then started
- * from the first candidate and republished them. And nothing bounded how many times one message
- * could be redriven.
- *
- * @param request what to move
- * @param approval the verified approval, when one was supplied
- * @param subject the operator identity
- * @param now the current instant
- * @param resumeFrom how many candidates a previous attempt durably moved
- * @param checkpoint called with the running completed count after each item
- * @return what the pass did
- */
- public RedriveReport redrive(
- RedriveRequest request,
- Optional The request carries an {@code isolatedConsumerGroup} intent flag, but a caller-supplied
- * boolean is not proof that the executor actually created or used an isolated broker group.
- * Therefore every non-dry-run replay goes through the destructive guard until the runtime can
- * attest isolation itself. Dry-run remains approval-free because it changes no broker state.
- */
-public final class ReplayService {
-
- private final DestructiveOperationGuard guard;
- private final ReplayExecutor executor;
- private final RedriveService.AuditSink audit;
-
- /**
- * Creates a replay service.
- *
- * @param guard the destructive operation guard
- * @param executor performs the replay
- * @param audit records the operation
- */
- public ReplayService(
- DestructiveOperationGuard guard, ReplayExecutor executor, RedriveService.AuditSink audit) {
- this.guard = Objects.requireNonNull(guard, "guard must not be null");
- this.executor = Objects.requireNonNull(executor, "executor must not be null");
- this.audit = Objects.requireNonNull(audit, "audit must not be null");
- }
-
- /**
- * Runs one replay.
- *
- * @param request what to replay
- * @param approval the verified approval, when one was supplied
- * @param subject the operator identity
- * @param now the current instant
- * @return what the replay did
- */
- public ReplayReport replay(
- ReplayRequest request, Optional Validate-only, and it fails startup rather than logging. A partition count that silently
- * differs from the manifest changes the ordering guarantee the destination advertises, and a
- * missing {@code min.insync.replicas} changes what {@code acks=all} actually means — both are the
- * kind of drift that is invisible until the incident.
- */
-public final class TopologyValidationRuntime {
-
- private final TopologyReader reader;
-
- /**
- * Creates a validator over a broker reader.
- *
- * @param reader reads the observed topology
- */
- public TopologyValidationRuntime(TopologyReader reader) {
- this.reader = Objects.requireNonNull(reader, "reader must not be null");
- }
-
- /**
- * Validates every manifest, reporting all differences at once.
- *
- * @param manifests the declared topology
- * @throws MessageTopologyException when the broker does not match
- */
- public void validate(List Which discrepancies block is a judgement encoded here rather than left to configuration.
- * Replication factor and absence are blocking because a destination that is missing or unreplicated
- * cannot deliver the durability its profile promises. A partition count that is higher
- * than declared is advisory rather than blocking: extra partitions do not break durability, and
- * someone scaling a topic up deliberately should not be met with a refusal to start.
- *
- * A partition count that is lower is blocking, because it silently reduces the
- * concurrency the destination was sized for and, on a keyed topic, changes which key lands where.
- */
-public final class TopologyValidator {
-
- /**
- * Compares a manifest against observed topology.
- *
- * @param manifest what was declared
- * @param observed what the broker reports
- * @return the discrepancies found, empty when they agree
- */
- public List The guard used to take a plain {@code AdminApproval} record, which any caller could
- * construct. Every case below now has to go through a real signature to get an approval object at
- * all, which is the property the type change was made for.
- */
- private static VerifiedApproval verified(
- DestructiveOperation operation, DestinationName source, Instant from, Instant until) {
- PlanDigest digest = PlanDigest.ofCanonical(operation + "|" + source.value());
- ApprovalGrant grant =
- new ApprovalGrant(
- new AdminApproval("CHG-1001", "approver", from, until),
- "operator",
- operation,
- source,
- Optional.empty(),
- "v1",
- Long.MAX_VALUE,
- digest);
- return ISSUER.verify(grant, ISSUER.sign(grant), digest, from);
- }
-
- @Test
- void anApplicationRuntimeCannotRedrive() {
- DestructiveOperationGuard guard = new DestructiveOperationGuard(false);
-
- assertThatThrownBy(
- () ->
- guard.authorize(
- DestructiveOperation.REDRIVE, ORDERS, Optional.of(VALID), false, NOW))
- .isInstanceOf(MessageAuthorizationException.class)
- .hasMessageContaining("admin credential");
- }
-
- @Test
- void anAdminRuntimeStillNeedsAnApproval() {
- DestructiveOperationGuard guard = new DestructiveOperationGuard(true);
-
- assertThatThrownBy(
- () -> guard.authorize(DestructiveOperation.PURGE, ORDERS, Optional.empty(), false, NOW))
- .isInstanceOf(MessageAuthorizationException.class)
- .hasMessageContaining("approval");
- }
-
- @Test
- void anExpiredApprovalDoesNotAuthorise() {
- DestructiveOperationGuard guard = new DestructiveOperationGuard(true);
- VerifiedApproval expired =
- verified(
- DestructiveOperation.OFFSET_RESET,
- ORDERS,
- NOW.minusSeconds(7200),
- NOW.minusSeconds(60));
-
- assertThatThrownBy(
- () ->
- guard.authorize(
- DestructiveOperation.OFFSET_RESET, ORDERS, Optional.of(expired), false, NOW))
- .isInstanceOf(MessageAuthorizationException.class)
- .hasMessageContaining("validity window");
- }
-
- @Test
- void aDryRunIsAlwaysPermitted() {
- DestructiveOperationGuard guard = new DestructiveOperationGuard(false);
-
- assertThatCode(
- () ->
- guard.authorize(
- DestructiveOperation.DELETE_DESTINATION, ORDERS, Optional.empty(), true, NOW))
- .doesNotThrowAnyException();
- }
-
- @Test
- void anApprovedAdminOperationIsAuthorised() {
- DestructiveOperationGuard guard = new DestructiveOperationGuard(true);
-
- assertThatCode(
- () ->
- guard.authorize(
- DestructiveOperation.REPLAY, ORDERS, Optional.of(VALID), false, NOW))
- .doesNotThrowAnyException();
- }
-
- @Test
- void aRedriveCannotTargetItsOwnSource() {
- assertThatThrownBy(() -> new RedriveRequest(UUID.randomUUID(), ORDERS, ORDERS, 100, false))
- .isInstanceOf(IllegalArgumentException.class);
- }
-
- @Test
- void aRedriveBatchIsBoundedSoOneOperationCannotFloodTheSource() {
- assertThatThrownBy(
- () ->
- new RedriveRequest(
- UUID.randomUUID(), new DestinationName("order-events-dlq"), ORDERS, 101, false))
- .isInstanceOf(IllegalArgumentException.class);
- }
-
- @Test
- void aTopologyManifestReportsEveryDifference() {
- TopologyManifest manifest =
- new TopologyManifest(
- "order-events", "order.events.v1", 6, 3, Map.of("min.insync.replicas", "2"));
-
- assertThat(manifest.differencesFrom(3, 3, Map.of("min.insync.replicas", "1")))
- .hasSize(2)
- .anySatisfy(difference -> assertThat(difference).contains("partitions"))
- .anySatisfy(difference -> assertThat(difference).contains("min.insync.replicas"));
- }
-
- @Test
- void aMatchingTopologyReportsNoDifferences() {
- TopologyManifest manifest =
- new TopologyManifest(
- "order-events", "order.events.v1", 6, 3, Map.of("min.insync.replicas", "2"));
-
- assertThat(manifest.differencesFrom(6, 3, Map.of("min.insync.replicas", "2"))).isEmpty();
- }
-}
diff --git a/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/AdminOperationJournalTest.java b/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/AdminOperationJournalTest.java
deleted file mode 100644
index 76b5e32c..00000000
--- a/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/AdminOperationJournalTest.java
+++ /dev/null
@@ -1,145 +0,0 @@
-package dev.caskeleton.messaging.admin.runtime;
-
-import static org.assertj.core.api.Assertions.assertThat;
-import static org.assertj.core.api.Assertions.assertThatCode;
-import static org.assertj.core.api.Assertions.assertThatThrownBy;
-
-import dev.caskeleton.messaging.admin.AdminOperationLease;
-import dev.caskeleton.messaging.admin.AdminOperationState;
-import dev.caskeleton.messaging.admin.PlanDigest;
-import dev.caskeleton.messaging.api.error.MessageAuthorizationException;
-import java.time.Duration;
-import java.time.Instant;
-import org.junit.jupiter.api.DisplayName;
-import org.junit.jupiter.api.Test;
-
-/**
- * The protocol the journal has to implement, proven against the in-memory one.
- *
- * What it replaced recorded a single fact — "this approval was claimed" — before any work
- * happened, in a map. An operation that died halfway had spent its approval, left no record of what
- * it had already moved, and gave a retry no way to continue: either request a new approval and
- * republish everything, or leave the redrive half applied.
- */
-class AdminOperationJournalTest {
-
- private static final Instant NOW = Instant.parse("2026-08-10T09:00:00Z");
- private static final Duration LEASE = Duration.ofMinutes(5);
- private static final String TICKET = "CHG-1042";
- private static final PlanDigest DIGEST = PlanDigest.ofCanonical("REDRIVE|orders.v1.dlq|50");
- private static final PlanDigest OTHER_DIGEST = PlanDigest.ofCanonical("REDRIVE|payments.dlq|50");
-
- private final InMemoryAdminOperationJournal journal = new InMemoryAdminOperationJournal();
-
- @Test
- @DisplayName("two replicas racing for one approval produce exactly one lease")
- void twoReplicasRacingProduceExactlyOneLease() {
- journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW);
-
- assertThatThrownBy(
- () -> journal.begin(TICKET, DIGEST, "op-2", "replica-b", LEASE, NOW.plusSeconds(1)))
- .as("both replicas executing one approval is a duplicate storm, not a faster redrive")
- .isInstanceOf(MessageAuthorizationException.class)
- .hasMessageContaining("replica-a");
- }
-
- @Test
- @DisplayName("a completed operation cannot be executed again")
- void aCompletedOperationCannotBeExecutedAgain() {
- AdminOperationLease lease = journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW);
- journal.complete(lease, 50, NOW.plusSeconds(30));
-
- assertThatThrownBy(
- () -> journal.begin(TICKET, DIGEST, "op-2", "replica-a", LEASE, NOW.plusSeconds(60)))
- .as("an arrow-up in the shell must not re-run an approved redrive")
- .isInstanceOf(MessageAuthorizationException.class)
- .hasMessageContaining("already executed");
- }
-
- @Test
- @DisplayName("a crashed run resumes from its checkpoint rather than starting over")
- void aCrashedRunResumesFromItsCheckpoint() {
- AdminOperationLease first = journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW);
- journal.checkpoint(first, 30, LEASE, NOW.plusSeconds(10));
- // No fail() call: this replica died. The lease simply runs out.
-
- AdminOperationLease resumed =
- journal.begin(TICKET, DIGEST, "op-1", "replica-b", LEASE, NOW.plus(Duration.ofMinutes(10)));
-
- assertThat(resumed.resumeFrom())
- .as("the 30 already moved must not be republished")
- .isEqualTo(30);
- assertThat(resumed.leaseToken()).isGreaterThan(first.leaseToken());
- assertThat(resumed.isResumption()).isTrue();
- }
-
- @Test
- @DisplayName("a failed run stays resumable without waiting for the lease to expire")
- void aFailedRunStaysResumableImmediately() {
- AdminOperationLease first = journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW);
- journal.checkpoint(first, 12, LEASE, NOW.plusSeconds(5));
- journal.fail(first, 12, "MESSAGE_BROKER_UNAVAILABLE", NOW.plusSeconds(6));
-
- AdminOperationLease resumed =
- journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW.plusSeconds(7));
-
- assertThat(resumed.resumeFrom()).isEqualTo(12);
- assertThat(journal.find(TICKET, DIGEST))
- .hasValueSatisfying(
- record -> assertThat(record.state()).isEqualTo(AdminOperationState.STARTED));
- }
-
- @Test
- @DisplayName("a runtime that lost its lease cannot write over the one that took over")
- void aRuntimeThatLostItsLeaseCannotWriteOverTheSuccessor() {
- AdminOperationLease stale = journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW);
- journal.checkpoint(stale, 30, LEASE, NOW.plusSeconds(10));
- AdminOperationLease successor =
- journal.begin(TICKET, DIGEST, "op-1", "replica-b", LEASE, NOW.plus(Duration.ofMinutes(10)));
- journal.checkpoint(successor, 45, LEASE, NOW.plus(Duration.ofMinutes(11)));
-
- assertThatThrownBy(() -> journal.complete(stale, 30, NOW.plus(Duration.ofMinutes(12))))
- .as("a stalled replica waking up must not mark the operation done at its own count")
- .isInstanceOf(MessageAuthorizationException.class)
- .hasMessageContaining("no longer owns");
-
- assertThat(journal.find(TICKET, DIGEST))
- .hasValueSatisfying(
- record -> {
- assertThat(record.itemsCompleted()).isEqualTo(45);
- assertThat(record.state()).isEqualTo(AdminOperationState.STARTED);
- });
- }
-
- @Test
- @DisplayName("the same ticket presented for a different plan is a different operation")
- void theSameTicketForADifferentPlanIsADifferentOperation() {
- journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW);
-
- // Keyed on the ticket alone this would have been refused as a duplicate execution, which reads
- // as protection but is actually the wrong answer: it is a different plan, and it must be
- // refused by the approval binding rather than silently treated as the same operation.
- assertThatCode(() -> journal.begin(TICKET, OTHER_DIGEST, "op-2", "replica-a", LEASE, NOW))
- .doesNotThrowAnyException();
- assertThat(journal.size()).isEqualTo(2);
- }
-
- @Test
- @DisplayName("a checkpoint never moves backwards")
- void aCheckpointNeverMovesBackwards() {
- AdminOperationLease lease = journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW);
- journal.checkpoint(lease, 40, LEASE, NOW.plusSeconds(10));
- journal.checkpoint(lease, 5, LEASE, NOW.plusSeconds(20));
-
- assertThat(journal.find(TICKET, DIGEST))
- .hasValueSatisfying(record -> assertThat(record.itemsCompleted()).isEqualTo(40));
- }
-
- @Test
- @DisplayName("the in-memory journal declares itself non-durable")
- void theInMemoryJournalDeclaresItselfNonDurable() {
- assertThat(journal.isDurable())
- .as("the starter refuses a production profile on a journal that says this")
- .isFalse();
- }
-}
diff --git a/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/ApprovalForgeryTest.java b/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/ApprovalForgeryTest.java
deleted file mode 100644
index abc54be1..00000000
--- a/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/ApprovalForgeryTest.java
+++ /dev/null
@@ -1,243 +0,0 @@
-package dev.caskeleton.messaging.admin.runtime;
-
-import static org.assertj.core.api.Assertions.assertThat;
-import static org.assertj.core.api.Assertions.assertThatCode;
-import static org.assertj.core.api.Assertions.assertThatThrownBy;
-
-import dev.caskeleton.messaging.admin.AdminApproval;
-import dev.caskeleton.messaging.admin.ApprovalGrant;
-import dev.caskeleton.messaging.admin.ApprovedRedrivePlan;
-import dev.caskeleton.messaging.admin.DestructiveOperation;
-import dev.caskeleton.messaging.admin.HmacApprovalVerifier;
-import dev.caskeleton.messaging.admin.RedrivePlan;
-import dev.caskeleton.messaging.admin.RedriveRequest;
-import dev.caskeleton.messaging.admin.VerifiedApproval;
-import dev.caskeleton.messaging.api.destination.DestinationName;
-import dev.caskeleton.messaging.api.error.MessageAuthorizationException;
-import java.nio.charset.StandardCharsets;
-import java.time.Duration;
-import java.time.Instant;
-import java.util.Optional;
-import java.util.UUID;
-import org.junit.jupiter.api.DisplayName;
-import org.junit.jupiter.api.Test;
-
-/**
- * Whether "this was approved" is a fact or a claim the caller makes about itself.
- *
- * It was a claim. {@code AdminApproval} was a public record and {@code ApprovedRedrivePlan} a
- * public record over it, so any code that could reach the execute method could write its own
- * approval and the platform believed it. Nothing bound an approval to an operation, a destination,
- * a topology version, or an impact ceiling either, so a genuine approval for one redrive authorised
- * a redrive of anything else inside its window.
- */
-class ApprovalForgeryTest {
-
- private static final Instant NOW = Instant.parse("2026-08-10T09:00:00Z");
- private static final UUID OPERATION_ID = UUID.fromString("0199aaaa-bbbb-7ccc-8ddd-eeeeffff0000");
- private static final DestinationName DLQ = new DestinationName("orders.v1.dlq");
- private static final DestinationName ORDERS = new DestinationName("orders.v1");
-
- private static final HmacApprovalVerifier ISSUER =
- new HmacApprovalVerifier(
- "an-issuing-key-of-at-least-32-bytes!".getBytes(StandardCharsets.UTF_8));
-
- private static final HmacApprovalVerifier ANOTHER_ISSUER =
- new HmacApprovalVerifier(
- "a-different-key-of-at-least-32-bytes".getBytes(StandardCharsets.UTF_8));
-
- @Test
- @DisplayName("a verified approval cannot be constructed outside the verifier")
- void aVerifiedApprovalCannotBeConstructedOutsideTheVerifier() {
- // Written as a reflection probe because the property is about the type's shape, not its
- // behaviour: if a public constructor or factory ever appears, every other test here becomes
- // decorative.
- assertThat(VerifiedApproval.class.getConstructors())
- .as("a public constructor would let any caller mint an approval for itself")
- .isEmpty();
- assertThat(
- java.util.Arrays.stream(VerifiedApproval.class.getDeclaredMethods())
- .filter(method -> java.lang.reflect.Modifier.isStatic(method.getModifiers()))
- .filter(method -> java.lang.reflect.Modifier.isPublic(method.getModifiers()))
- .toList())
- .as("nor may a public static factory")
- .isEmpty();
- }
-
- @Test
- @DisplayName("an unsigned or altered grant does not verify")
- void anAlteredGrantDoesNotVerify() {
- RedrivePlan plan = plan(50, 0);
- ApprovalGrant signed = grant(plan, DestructiveOperation.REDRIVE, DLQ, ORDERS, 50);
- String signature = ISSUER.sign(signed);
-
- ApprovalGrant raised = grant(plan, DestructiveOperation.REDRIVE, DLQ, ORDERS, 5_000);
-
- assertThatThrownBy(() -> ISSUER.verify(raised, signature, plan.digest(), NOW))
- .as("raising the impact ceiling after the approver signed it")
- .isInstanceOf(MessageAuthorizationException.class)
- .hasMessageContaining("does not verify");
- }
-
- @Test
- @DisplayName("a signature from another issuer does not verify")
- void aSignatureFromAnotherIssuerDoesNotVerify() {
- RedrivePlan plan = plan(50, 0);
- ApprovalGrant granted = grant(plan, DestructiveOperation.REDRIVE, DLQ, ORDERS, 50);
-
- assertThatThrownBy(
- () -> ISSUER.verify(granted, ANOTHER_ISSUER.sign(granted), plan.digest(), NOW))
- .isInstanceOf(MessageAuthorizationException.class)
- .hasMessageContaining("does not verify");
- }
-
- @Test
- @DisplayName("an approval for one plan cannot execute another")
- void anApprovalForOnePlanCannotExecuteAnother() {
- RedrivePlan approvedPlan = plan(50, 0);
- RedrivePlan biggerPlan = plan(900, 0);
- ApprovalGrant granted = grant(approvedPlan, DestructiveOperation.REDRIVE, DLQ, ORDERS, 900);
- String signature = ISSUER.sign(granted);
-
- assertThatThrownBy(() -> ISSUER.verify(granted, signature, biggerPlan.digest(), NOW))
- .as("the approver saw 50 candidates; this plan moves 900")
- .isInstanceOf(MessageAuthorizationException.class)
- .hasMessageContaining("was issued for plan");
- }
-
- @Test
- @DisplayName("a verified approval for the wrong source cannot be attached to a plan")
- void aVerifiedApprovalForTheWrongSourceCannotBeAttached() {
- RedrivePlan plan = plan(50, 0);
- // A genuine, correctly-signed approval — for a different dead-letter destination, with this
- // plan's digest smuggled in. The digest check passes; the source binding is what catches it.
- ApprovalGrant granted =
- new ApprovalGrant(
- approval(),
- "operator@example.com",
- DestructiveOperation.REDRIVE,
- new DestinationName("payments.v1.dlq"),
- Optional.of(ORDERS),
- "v1",
- 900,
- plan.digest());
- VerifiedApproval verified = ISSUER.verify(granted, ISSUER.sign(granted), plan.digest(), NOW);
-
- assertThatThrownBy(() -> new ApprovedRedrivePlan(plan, verified, false))
- .isInstanceOf(MessageAuthorizationException.class)
- .hasMessageContaining("payments.v1.dlq");
- }
-
- @Test
- @DisplayName("a plan beyond the approved impact ceiling cannot execute")
- void aPlanBeyondTheApprovedImpactCeilingCannotExecute() {
- RedrivePlan plan = plan(900, 0);
- ApprovalGrant granted = grant(plan, DestructiveOperation.REDRIVE, DLQ, ORDERS, 100);
- VerifiedApproval verified = ISSUER.verify(granted, ISSUER.sign(granted), plan.digest(), NOW);
-
- assertThatThrownBy(() -> new ApprovedRedrivePlan(plan, verified, false))
- .as("the approver agreed to at most 100")
- .isInstanceOf(MessageAuthorizationException.class)
- .hasMessageContaining("at most 100");
- }
-
- @Test
- @DisplayName("an approval for a replay cannot authorise a redrive")
- void anApprovalForAReplayCannotAuthoriseARedrive() {
- RedrivePlan plan = plan(50, 0);
- ApprovalGrant granted = grant(plan, DestructiveOperation.REPLAY, DLQ, ORDERS, 900);
- VerifiedApproval verified = ISSUER.verify(granted, ISSUER.sign(granted), plan.digest(), NOW);
-
- assertThatThrownBy(() -> new ApprovedRedrivePlan(plan, verified, false))
- .isInstanceOf(MessageAuthorizationException.class)
- .hasMessageContaining("authorises REPLAY");
- }
-
- @Test
- @DisplayName("an expired grant does not verify")
- void anExpiredGrantDoesNotVerify() {
- RedrivePlan plan = plan(50, 0);
- ApprovalGrant granted = grant(plan, DestructiveOperation.REDRIVE, DLQ, ORDERS, 50);
-
- assertThatThrownBy(
- () ->
- ISSUER.verify(
- granted, ISSUER.sign(granted), plan.digest(), NOW.plus(Duration.ofDays(1))))
- .isInstanceOf(MessageAuthorizationException.class)
- .hasMessageContaining("not valid at");
- }
-
- @Test
- @DisplayName("the approver and the operator must be different people")
- void theApproverAndTheOperatorMustBeDifferentPeople() {
- RedrivePlan plan = plan(50, 0);
-
- assertThatThrownBy(
- () ->
- new ApprovalGrant(
- approval(),
- "ops@example.com",
- DestructiveOperation.REDRIVE,
- DLQ,
- Optional.of(ORDERS),
- "v1",
- 50,
- plan.digest()))
- .as("an operator approving their own destructive operation is the control not existing")
- .isInstanceOf(IllegalArgumentException.class);
- }
-
- @Test
- @DisplayName("destructive admin plans can only carry a verified approval")
- void destructiveAdminUsesTheUnforgeableApprovalType() {
- assertThat(
- java.util.Arrays.stream(DestructiveMessagingAdmin.Approved.class.getRecordComponents())
- .filter(component -> component.getName().equals("approval"))
- .findFirst()
- .orElseThrow()
- .getType())
- .isEqualTo(VerifiedApproval.class);
- }
-
- @Test
- @DisplayName("a correctly issued approval executes")
- void aCorrectlyIssuedApprovalExecutes() {
- RedrivePlan plan = plan(50, 0);
- ApprovalGrant granted = grant(plan, DestructiveOperation.REDRIVE, DLQ, ORDERS, 50);
- VerifiedApproval verified = ISSUER.verify(granted, ISSUER.sign(granted), plan.digest(), NOW);
-
- assertThatCode(
- () -> new ApprovedRedrivePlan(plan, verified, false).requireExecutable(NOW, "v1"))
- .doesNotThrowAnyException();
- }
-
- private static ApprovalGrant grant(
- RedrivePlan plan,
- DestructiveOperation operation,
- DestinationName source,
- DestinationName target,
- long maxImpact) {
- return new ApprovalGrant(
- approval(),
- "operator@example.com",
- operation,
- source,
- Optional.of(target),
- "v1",
- maxImpact,
- plan.digest());
- }
-
- private static AdminApproval approval() {
- return new AdminApproval("CHG-1042", "ops@example.com", NOW, NOW.plus(Duration.ofHours(2)));
- }
-
- private static RedrivePlan plan(int candidates, int alreadyRedriven) {
- return new RedrivePlan(
- new RedriveRequest(OPERATION_ID, DLQ, ORDERS, 50, false),
- candidates,
- alreadyRedriven,
- NOW,
- "v1");
- }
-}
diff --git a/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/ApprovedPlanExecutionTest.java b/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/ApprovedPlanExecutionTest.java
deleted file mode 100644
index 02dd2dc8..00000000
--- a/src/platforms/messaging/messaging-admin/src/test/java/dev/caskeleton/messaging/admin/runtime/ApprovedPlanExecutionTest.java
+++ /dev/null
@@ -1,226 +0,0 @@
-package dev.caskeleton.messaging.admin.runtime;
-
-import static org.assertj.core.api.Assertions.assertThat;
-import static org.assertj.core.api.Assertions.assertThatCode;
-import static org.assertj.core.api.Assertions.assertThatThrownBy;
-
-import dev.caskeleton.messaging.admin.AdminApproval;
-import dev.caskeleton.messaging.admin.ApprovalGrant;
-import dev.caskeleton.messaging.admin.ApprovedRedrivePlan;
-import dev.caskeleton.messaging.admin.ApprovedReplayPlan;
-import dev.caskeleton.messaging.admin.DestructiveOperation;
-import dev.caskeleton.messaging.admin.HmacApprovalVerifier;
-import dev.caskeleton.messaging.admin.PlanDigest;
-import dev.caskeleton.messaging.admin.RedrivePlan;
-import dev.caskeleton.messaging.admin.RedriveRequest;
-import dev.caskeleton.messaging.admin.RedriveResult;
-import dev.caskeleton.messaging.admin.ReplayPlan;
-import dev.caskeleton.messaging.admin.ReplayRequest;
-import dev.caskeleton.messaging.admin.ReplayResult;
-import dev.caskeleton.messaging.admin.VerifiedApproval;
-import dev.caskeleton.messaging.api.destination.DestinationName;
-import dev.caskeleton.messaging.api.error.MessageAuthorizationException;
-import java.time.Duration;
-import java.time.Instant;
-import java.util.Optional;
-import java.util.UUID;
-import org.junit.jupiter.api.Test;
-
-class ApprovedPlanExecutionTest {
-
- private static final Instant NOW = Instant.parse("2026-08-10T09:00:00Z");
- private static final UUID OPERATION_ID = UUID.fromString("0199aaaa-bbbb-7ccc-8ddd-eeeeffff0000");
-
- private static final byte[] ISSUING_KEY =
- "an-issuing-key-of-at-least-32-bytes!".getBytes(java.nio.charset.StandardCharsets.UTF_8);
-
- private static final HmacApprovalVerifier VERIFIER = new HmacApprovalVerifier(ISSUING_KEY);
-
- private static AdminApproval approval() {
- return new AdminApproval("CHG-1042", "ops@example.com", NOW, NOW.plus(Duration.ofHours(2)));
- }
-
- /** A grant the issuer signed for exactly this plan, verified the way the runtime verifies it. */
- static VerifiedApproval verified(
- PlanDigest digest,
- DestructiveOperation operation,
- DestinationName source,
- Optional The loop had no per-item boundary. A publisher that threw — a broker refusing the connection
- * rather than the message — propagated straight out, so every candidate behind it was abandoned and
- * the audit record was never written. The operation left no trace of what it had already moved, and
- * a retry started again from the first candidate and republished it.
- */
-class RedriveResumptionTest {
-
- private static final Instant NOW = Instant.parse("2026-08-10T09:00:00Z");
- private static final DestinationName DLQ = new DestinationName("orders.v1.dlq");
- private static final DestinationName ORDERS = new DestinationName("orders.v1");
-
- private static final HmacApprovalVerifier ISSUER =
- new HmacApprovalVerifier(
- "an-issuing-key-of-at-least-32-bytes!".getBytes(java.nio.charset.StandardCharsets.UTF_8));
-
- private final RecordingSource source = new RecordingSource();
- private final RecordingAudit audit = new RecordingAudit();
-
- @Test
- @DisplayName("one message that throws does not abandon the ones behind it")
- void oneThrowingMessageDoesNotAbandonTheRest() {
- List Not retryable. A digest mismatch means the object at that key is not the object the producer
- * wrote — the key was reused, the object was overwritten, or something truncated it — and fetching
- * it again returns the same wrong bytes. Retrying would only delay the dead-letter.
- *
- * Deliberately distinct from "the object is gone". An expired claim check is an operational
- * problem with a known cause and a known fix; a digest mismatch means something wrote data nobody
- * expected, and the two must not be diagnosed as one.
- */
-public class ClaimCheckIntegrityException extends MessagingException {
-
- @Serial private static final long serialVersionUID = 1L;
-
- private static final FailureCategory CATEGORY = FailureCategory.POISON_MESSAGE;
-
- /**
- * Creates the exception with a stable code and sanitized message.
- *
- * @param code the stable failure code
- * @param sanitizedMessage the operator-facing description
- */
- public ClaimCheckIntegrityException(String code, String sanitizedMessage) {
- super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty()));
- }
-
- /**
- * Creates the exception from an explicit descriptor.
- *
- * @param failure the sanitized failure description
- */
- public ClaimCheckIntegrityException(FailureDescriptor failure) {
- super(failure);
- }
-}
diff --git a/src/platforms/messaging/messaging-claim-check/src/main/java/dev/caskeleton/messaging/claimcheck/ClaimCheckIntegrityGuard.java b/src/platforms/messaging/messaging-claim-check/src/main/java/dev/caskeleton/messaging/claimcheck/ClaimCheckIntegrityGuard.java
deleted file mode 100644
index 461f966a..00000000
--- a/src/platforms/messaging/messaging-claim-check/src/main/java/dev/caskeleton/messaging/claimcheck/ClaimCheckIntegrityGuard.java
+++ /dev/null
@@ -1,71 +0,0 @@
-package dev.caskeleton.messaging.claimcheck;
-
-import dev.caskeleton.messaging.api.error.MessageValidationException;
-import dev.caskeleton.messaging.reliability.ClaimCheckReference;
-import java.security.MessageDigest;
-import java.security.NoSuchAlgorithmException;
-import java.time.Instant;
-import java.util.HexFormat;
-import java.util.Objects;
-
-/**
- * Verifies a fetched claim check payload before it is handed to a codec.
- *
- * A claim check turns one message into two systems that can drift. The payload store has its own
- * retention, its own replication, and its own access control, and none of them are coordinated with
- * the broker's. So a consumer that fetches bytes and decodes them without checking is trusting
- * something the message never proved.
- *
- * Both checks fail closed. An expired reference is reported before the fetch, because a
- * not-found from the store is ambiguous between "reaped" and "never written". A digest mismatch is
- * reported as validation rather than deserialization, because the bytes are not corrupt JSON — they
- * are the wrong bytes.
- */
-public final class ClaimCheckIntegrityGuard {
-
- /**
- * Verifies a payload against its reference.
- *
- * @param reference the claim check reference
- * @param payload the bytes fetched from the store
- * @param now the current instant
- * @return the verified payload
- * @throws MessageValidationException when the reference expired or the digest does not match
- */
- public byte[] verify(ClaimCheckReference reference, byte[] payload, Instant now) {
- Objects.requireNonNull(reference, "reference must not be null");
- Objects.requireNonNull(payload, "payload must not be null");
- Objects.requireNonNull(now, "now must not be null");
-
- if (reference.isExpired(now)) {
- throw new MessageValidationException(
- "CLAIM_CHECK_EXPIRED",
- "the claim check payload retention expired at " + reference.expiresAt());
- }
- if (payload.length != reference.sizeBytes()) {
- throw new MessageValidationException(
- "CLAIM_CHECK_SIZE_MISMATCH",
- "expected " + reference.sizeBytes() + " bytes but read " + payload.length);
- }
- String actual = sha256(payload);
- if (!actual.equals(reference.sha256())) {
- throw new MessageValidationException(
- "CLAIM_CHECK_DIGEST_MISMATCH", "the fetched payload does not match its reference digest");
- }
- return payload.clone();
- }
-
- /**
- * Returns the lowercase hex SHA-256 of a payload.
- *
- * @param payload the bytes to digest
- * @return the digest
- */
- public static String sha256(byte[] payload) {
- try {
- return HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(payload));
- } catch (NoSuchAlgorithmException exception) {
- throw new IllegalStateException("Java runtime does not provide SHA-256", exception);
- }
- }
-}
diff --git a/src/platforms/messaging/messaging-claim-check/src/main/java/dev/caskeleton/messaging/claimcheck/ClaimCheckPolicy.java b/src/platforms/messaging/messaging-claim-check/src/main/java/dev/caskeleton/messaging/claimcheck/ClaimCheckPolicy.java
deleted file mode 100644
index 7458a4fc..00000000
--- a/src/platforms/messaging/messaging-claim-check/src/main/java/dev/caskeleton/messaging/claimcheck/ClaimCheckPolicy.java
+++ /dev/null
@@ -1,89 +0,0 @@
-package dev.caskeleton.messaging.claimcheck;
-
-import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
-import java.time.Duration;
-import java.util.Objects;
-
-/**
- * When a payload is offloaded, and how long the object must outlive the message.
- *
- * The retention rule is the one that matters. A claim check object deleted while its message is
- * still deliverable turns a large message into an undeliverable one — the consumer fetches, gets
- * nothing, and the message dead-letters for a reason that has nothing to do with the message. So
- * retention must exceed the broker's own retention plus the full retry and dead-letter window, and
- * the constructor refuses a configuration where it does not.
- *
- * The threshold is separate from the destination's payload limit. Offloading starts well below
- * the limit, because the limit is where the broker refuses the message and the threshold is where
- * carrying it inline stops being a good idea.
- *
- * @param thresholdBytes the encoded size above which a payload is offloaded
- * @param retention how long the stored object must remain readable
- * @param brokerRetention how long the broker keeps the message
- * @param maxRedeliveryWindow the longest retry and dead-letter path a message can take
- */
-public record ClaimCheckPolicy(
- int thresholdBytes,
- Duration retention,
- Duration brokerRetention,
- Duration maxRedeliveryWindow) {
-
- /** The default offload threshold: a quarter of the portable payload limit. */
- public static final int DEFAULT_THRESHOLD_BYTES = 262_144;
-
- public ClaimCheckPolicy {
- Objects.requireNonNull(retention, "retention must not be null");
- Objects.requireNonNull(brokerRetention, "brokerRetention must not be null");
- Objects.requireNonNull(maxRedeliveryWindow, "maxRedeliveryWindow must not be null");
- if (thresholdBytes < 1) {
- throw new IllegalArgumentException("thresholdBytes must be positive");
- }
- requirePositive(retention, "retention");
- requirePositive(brokerRetention, "brokerRetention");
- requirePositive(maxRedeliveryWindow, "maxRedeliveryWindow");
-
- Duration required = brokerRetention.plus(maxRedeliveryWindow);
- if (retention.compareTo(required) < 0) {
- throw new MessagingConfigurationException(
- "CLAIM_CHECK_RETENTION_TOO_SHORT",
- "claim check retention of %s is below the %s the message can remain deliverable; the "
- .formatted(retention, required)
- + "object would be reaped while a consumer can still be handed its message");
- }
- }
-
- /**
- * Returns a policy for a broker retaining one day with a one-day retry path.
- *
- * @return the default policy
- */
- public static ClaimCheckPolicy defaults() {
- return new ClaimCheckPolicy(
- DEFAULT_THRESHOLD_BYTES, Duration.ofDays(3), Duration.ofDays(1), Duration.ofDays(1));
- }
-
- /**
- * Reports whether a payload of this size is offloaded.
- *
- * @param payloadBytes the encoded payload size
- * @return true when the payload travels by reference
- */
- public boolean shouldOffload(int payloadBytes) {
- return payloadBytes > thresholdBytes;
- }
-
- /**
- * Returns the shortest retention this deployment allows.
- *
- * @return the minimum safe retention
- */
- public Duration requiredRetention() {
- return brokerRetention.plus(maxRedeliveryWindow);
- }
-
- private static void requirePositive(Duration value, String field) {
- if (value.isNegative() || value.isZero()) {
- throw new IllegalArgumentException(field + " must be positive");
- }
- }
-}
diff --git a/src/platforms/messaging/messaging-claim-check/src/main/java/dev/caskeleton/messaging/claimcheck/ClaimCheckPublisher.java b/src/platforms/messaging/messaging-claim-check/src/main/java/dev/caskeleton/messaging/claimcheck/ClaimCheckPublisher.java
deleted file mode 100644
index 630b5035..00000000
--- a/src/platforms/messaging/messaging-claim-check/src/main/java/dev/caskeleton/messaging/claimcheck/ClaimCheckPublisher.java
+++ /dev/null
@@ -1,91 +0,0 @@
-package dev.caskeleton.messaging.claimcheck;
-
-import dev.caskeleton.messaging.reliability.ClaimCheckReference;
-import java.util.Objects;
-import java.util.Optional;
-
-/**
- * Decides whether a payload travels inline or by reference, and stores it when it does not.
- *
- * The object is written before the message is published, and that order is the whole
- * design. Publishing first would let a consumer receive a reference to an object that does not
- * exist yet — a race that is rare in a test and routine under load, because the broker hop is
- * faster than the object store write.
- *
- * Nothing here deletes on failure. If the publish is rejected the object is left behind, and the
- * retention sweep reclaims it; deleting eagerly would delete the object out from under a publish
- * that turned out to be ambiguous rather than rejected.
- */
-public final class ClaimCheckPublisher {
-
- private final ClaimCheckStore store;
- private final ClaimCheckPolicy policy;
-
- /**
- * Creates a claim check publisher.
- *
- * @param store the payload store
- * @param policy the offload threshold and retention
- */
- public ClaimCheckPublisher(ClaimCheckStore store, ClaimCheckPolicy policy) {
- this.store = Objects.requireNonNull(store, "store must not be null");
- this.policy = Objects.requireNonNull(policy, "policy must not be null");
- }
-
- /**
- * Offloads a payload when the policy calls for it.
- *
- * @param payload the encoded payload bytes
- * @return the outcome, carrying either the inline payload or the stored reference
- */
- public Offloaded offload(byte[] payload) {
- Objects.requireNonNull(payload, "payload must not be null");
-
- if (!policy.shouldOffload(payload.length)) {
- return new Offloaded(payload.clone(), Optional.empty());
- }
- ClaimCheckReference reference = store.put(payload, policy.retention());
- // The published message carries no payload bytes at all, only the reference. Carrying both
- // would double the transfer for no benefit and let the two disagree.
- return new Offloaded(new byte[0], Optional.of(reference));
- }
-
- /**
- * Returns the policy this publisher applies.
- *
- * @return the claim check policy
- */
- public ClaimCheckPolicy policy() {
- return policy;
- }
-
- /**
- * What a payload became after the offload decision.
- *
- * @param payload the payload to publish, empty when offloaded
- * @param reference the stored object's reference, present when offloaded
- */
- @SuppressWarnings("ArrayRecordComponent")
- public record Offloaded(byte[] payload, Optional Verification is not optional and cannot be skipped by a caller. An object store key is a
- * string, and a message carrying the wrong one — through a bug, a replay against a rotated bucket,
- * or a deliberate tamper — fetches bytes that decode perfectly into the wrong object. The digest is
- * the only thing standing between that and a handler acting on someone else's data.
- *
- * Failures are classified rather than merged. An expired reference is an operational problem
- * whose fix is a retention change; a digest mismatch means something wrote data nobody expected.
- * Both dead-letter the message, but an operator seeing one code should not have to guess which
- * happened.
- */
-public final class ClaimCheckResolver {
-
- private final ClaimCheckStore store;
- private final ClaimCheckIntegrityGuard guard = new ClaimCheckIntegrityGuard();
-
- /**
- * Creates a resolver.
- *
- * @param store the payload store
- */
- public ClaimCheckResolver(ClaimCheckStore store) {
- this.store = Objects.requireNonNull(store, "store must not be null");
- }
-
- /**
- * Returns the payload a message carries, fetching it when it travels by reference.
- *
- * @param inline the payload bytes the message carried, empty when it travels by reference
- * @param reference the claim check reference, when the message carried one
- * @param now the current instant
- * @return the payload the handler should see
- * @throws ClaimCheckIntegrityException when the stored object is not the one referenced
- * @throws MessageValidationException when the reference has expired
- */
- public byte[] resolve(byte[] inline, Optional CloudEvents requires extension names to be lowercase alphanumeric, which is why these are not
- * simply the envelope field names.
- */
-public final class CloudEventExtensions {
-
- /** Carries the envelope's correlation id. */
- public static final String CORRELATION_ID = "correlationid";
-
- /** Carries the envelope's causation id. */
- public static final String CAUSATION_ID = "causationid";
-
- /** Carries the envelope's schema version. */
- public static final String SCHEMA_VERSION = "schemaversion";
-
- /** Carries the envelope's tenant identity. */
- public static final String TENANT_CONTEXT = "tenantcontext";
-
- private CloudEventExtensions() {}
-}
diff --git a/src/platforms/messaging/messaging-cloudevents/src/main/java/dev/caskeleton/messaging/cloudevents/CloudEventMapper.java b/src/platforms/messaging/messaging-cloudevents/src/main/java/dev/caskeleton/messaging/cloudevents/CloudEventMapper.java
deleted file mode 100644
index b6d0bf42..00000000
--- a/src/platforms/messaging/messaging-cloudevents/src/main/java/dev/caskeleton/messaging/cloudevents/CloudEventMapper.java
+++ /dev/null
@@ -1,33 +0,0 @@
-package dev.caskeleton.messaging.cloudevents;
-
-import dev.caskeleton.messaging.api.MessageEnvelope;
-import dev.caskeleton.messaging.schema.EncodedMessage;
-import io.cloudevents.CloudEvent;
-import java.net.URI;
-
-/**
- * Maps between the platform envelope and CloudEvents 1.0.2.
- *
- * Offered for domain and integration events only. Commands and work items are not forced through
- * CloudEvents: they are internal contracts where the interoperability the specification buys does
- * not pay for the attributes it requires.
- */
-public interface CloudEventMapper {
-
- /**
- * Converts an envelope to a CloudEvent.
- *
- * @param envelope the envelope carrying an already-encoded payload
- * @param source the event source URI
- * @return the CloudEvent
- */
- CloudEvent toCloudEvent(MessageEnvelope> envelope, URI source);
-
- /**
- * Converts a CloudEvent back to an envelope.
- *
- * @param event the CloudEvent
- * @return an envelope whose payload is the still-encoded data
- */
- MessageEnvelope Two mapping decisions are deliberate. An event without {@code occurredAt} is rejected rather
- * than defaulted to the production instant, because {@code time} is read downstream as when the
- * fact happened, not when the platform got around to serialising it. And an event with no data maps
- * to an envelope with empty bytes, never to a Kafka null value: a tombstone deletes a key, and
- * inventing one from an absent CloudEvent payload would turn an empty notification into a deletion.
- */
-public final class DefaultCloudEventMapper implements CloudEventMapper {
-
- private static final String SPEC_CONTENT_TYPE_FALLBACK = "application/json";
-
- @Override
- public CloudEvent toCloudEvent(MessageEnvelope> envelope, URI source) {
- Objects.requireNonNull(envelope, "envelope must not be null");
- Objects.requireNonNull(source, "source must not be null");
-
- Instant occurredAt =
- envelope
- .occurredAt()
- .orElseThrow(
- () ->
- new MessageValidationException(
- "CLOUDEVENT_TIME_REQUIRED",
- "an event mapped to CloudEvents requires occurredAt"));
-
- CloudEventBuilder builder =
- CloudEventBuilder.v1()
- .withId(envelope.messageId().value().toString())
- .withSource(source)
- .withType(envelope.messageType().value())
- .withTime(OffsetDateTime.ofInstant(occurredAt, ZoneOffset.UTC))
- .withDataContentType(envelope.contentType().value())
- .withExtension(
- CloudEventExtensions.SCHEMA_VERSION,
- Integer.toString(envelope.schemaVersion().value()));
-
- envelope
- .correlationId()
- .ifPresent(
- value -> builder.withExtension(CloudEventExtensions.CORRELATION_ID, value.value()));
- envelope
- .causationId()
- .ifPresent(
- value ->
- builder.withExtension(
- CloudEventExtensions.CAUSATION_ID, value.value().value().toString()));
- envelope
- .tenantContext()
- .ifPresent(
- value -> builder.withExtension(CloudEventExtensions.TENANT_CONTEXT, value.tenantId()));
-
- if (envelope.payload() instanceof EncodedMessage encoded) {
- encoded
- .schemaReference()
- .flatMap(reference -> reference.schemaUri())
- .ifPresent(builder::withDataSchema);
- builder.withData(BytesCloudEventData.wrap(encoded.bytes()));
- } else if (envelope.payload() instanceof byte[] bytes) {
- builder.withData(BytesCloudEventData.wrap(bytes.clone()));
- } else {
- throw new MessageValidationException(
- "CLOUDEVENT_PAYLOAD_NOT_ENCODED",
- "CloudEvents mapping requires an already-encoded payload");
- }
-
- return builder.build();
- }
-
- @Override
- public MessageEnvelope The last path or scheme-specific segment is used so that a long URI does not become an
- * unbounded producer name, which would leak straight into metric tags.
- */
- private static String producerFrom(URI source) {
- String text = source.toString();
- int separator = Math.max(text.lastIndexOf('/'), text.lastIndexOf(':'));
- String candidate =
- separator >= 0 && separator + 1 < text.length() ? text.substring(separator + 1) : text;
- return candidate.isBlank() ? "unknown" : candidate;
- }
-}
diff --git a/src/platforms/messaging/messaging-cloudevents/src/test/java/dev/caskeleton/messaging/cloudevents/CloudEventMappingTest.java b/src/platforms/messaging/messaging-cloudevents/src/test/java/dev/caskeleton/messaging/cloudevents/CloudEventMappingTest.java
deleted file mode 100644
index f82c6da6..00000000
--- a/src/platforms/messaging/messaging-cloudevents/src/test/java/dev/caskeleton/messaging/cloudevents/CloudEventMappingTest.java
+++ /dev/null
@@ -1,162 +0,0 @@
-package dev.caskeleton.messaging.cloudevents;
-
-import static org.assertj.core.api.Assertions.assertThat;
-import static org.assertj.core.api.Assertions.assertThatThrownBy;
-
-import dev.caskeleton.messaging.api.ContentType;
-import dev.caskeleton.messaging.api.CorrelationId;
-import dev.caskeleton.messaging.api.MessageEnvelope;
-import dev.caskeleton.messaging.api.MessageId;
-import dev.caskeleton.messaging.api.MessageType;
-import dev.caskeleton.messaging.api.ProducerId;
-import dev.caskeleton.messaging.api.SchemaVersion;
-import dev.caskeleton.messaging.api.TenantContext;
-import dev.caskeleton.messaging.api.TraceContext;
-import dev.caskeleton.messaging.api.error.MessageValidationException;
-import dev.caskeleton.messaging.api.header.MessageHeaders;
-import dev.caskeleton.messaging.schema.EncodedMessage;
-import io.cloudevents.CloudEvent;
-import java.net.URI;
-import java.nio.charset.StandardCharsets;
-import java.time.Instant;
-import java.util.Optional;
-import java.util.UUID;
-import org.junit.jupiter.api.Test;
-
-class CloudEventMappingTest {
-
- private static final URI SOURCE = URI.create("urn:service:order-api");
-
- private final DefaultCloudEventMapper mapper = new DefaultCloudEventMapper();
-
- @Test
- void mapsLogicalIdentityAndExtensions() {
- MessageEnvelope Unlike {@link CorrelationId}, which spans a whole workflow, this points at exactly one
- * predecessor and forms the causal edge used when reconstructing a flow.
- *
- * @param value the predecessor message identity
- */
-public record CausationId(MessageId value) {
-
- public CausationId {
- Objects.requireNonNull(value, "causationId value must not be null");
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/ContentType.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/ContentType.java
deleted file mode 100644
index 2fcbdba2..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/ContentType.java
+++ /dev/null
@@ -1,46 +0,0 @@
-package dev.caskeleton.messaging.api;
-
-import java.util.Locale;
-
-/**
- * Media type of an encoded payload, resolved through the codec registry.
- *
- * @param value the media type, for example {@code application/json}
- */
-public record ContentType(String value) {
-
- private static final int MAX_LENGTH = 160;
-
- /** {@code type/subtype} with the optional parameters RFC 9110 allows. */
- private static final java.util.regex.Pattern MEDIA_TYPE =
- java.util.regex.Pattern.compile(
- "[A-Za-z0-9][A-Za-z0-9!#$%&'*+.^_`|~-]*"
- + "/[A-Za-z0-9][A-Za-z0-9!#$%&'*+.^_`|~-]*"
- + "(;\\s*[A-Za-z0-9!#$%&'*+.^_`|~-]+=[^;\\s]+)*");
-
- /** The Stable default codec's content type. */
- public static final ContentType JSON = new ContentType("application/json");
-
- /** Avro binary content type. */
- public static final ContentType AVRO = new ContentType("application/avro");
-
- /** Protobuf binary content type. */
- public static final ContentType PROTOBUF = new ContentType("application/x-protobuf");
-
- /** Opaque bytes, only reachable through the M2 raw codec. */
- public static final ContentType OCTET_STREAM = new ContentType("application/octet-stream");
-
- public ContentType {
- if (value == null || value.isBlank() || value.length() > MAX_LENGTH) {
- throw new IllegalArgumentException("contentType must contain 1 to 160 characters");
- }
- // A media type, not merely a string containing a slash. `a/b/c`, `/json` and `text/` all
- // passed the old check and are all rejected by a broker or a codec registry later, with an
- // error that names the message rather than the configuration that produced it.
- if (!MEDIA_TYPE.matcher(value).matches()) {
- throw new IllegalArgumentException(
- "contentType must be a type/subtype media type: '" + value + '\'');
- }
- value = value.toLowerCase(Locale.ROOT);
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/CorrelationId.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/CorrelationId.java
deleted file mode 100644
index 00b96bfa..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/CorrelationId.java
+++ /dev/null
@@ -1,24 +0,0 @@
-package dev.caskeleton.messaging.api;
-
-/**
- * Workflow-scoped correlation value shared by every message of one business flow.
- *
- * This value is copied onto every message of a flow and onto the header set of every broker the
- * flow touches, so it is bounded in {@link WireSafeText UTF-8 bytes} rather than in Java
- * characters: the previous 160-character bound admitted a 640-byte value, which a broker with a
- * byte-counted header budget rejects at publish time, mid-flow, on a message the caller cannot
- * resend under a different identity.
- *
- * @param value the correlation value, 1 to 160 UTF-8 bytes and free of control characters
- */
-public record CorrelationId(String value) {
-
- private static final int MAX_BYTES = 160;
-
- public CorrelationId {
- if (value == null || value.isBlank()) {
- throw new IllegalArgumentException("correlationId must not be blank");
- }
- WireSafeText.require(value, "a correlation id", MAX_BYTES);
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/MessageEnvelope.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/MessageEnvelope.java
deleted file mode 100644
index d5ecaa19..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/MessageEnvelope.java
+++ /dev/null
@@ -1,181 +0,0 @@
-package dev.caskeleton.messaging.api;
-
-import dev.caskeleton.messaging.api.header.MessageHeaders;
-import java.time.Instant;
-import java.util.Objects;
-import java.util.Optional;
-
-/**
- * The platform's unit of transfer: identity, provenance, routing intent, and payload.
- *
- * The payload is never null. A null Kafka value is a tombstone, which is a distinct
- * broker-native operation with different retention semantics, so generalising it into "an envelope
- * with no payload" would silently turn a delete into an event on brokers that have no such concept.
- *
- * @param Encoding, decoding, Claim Check offloading, and DLQ forwarding all need this, and every one
- * of them must keep {@link #messageId()} intact — which is exactly what this method guarantees by
- * construction.
- *
- * @param This value survives publish retry, broker redelivery, retry destinations, dead lettering, and
- * redrive. A new {@code MessageId} is minted only for a genuinely new business fact or command, so
- * an Inbox can use it to suppress duplicate side effects.
- *
- * @param value the UUIDv7 identity
- */
-public record MessageId(UUID value) {
-
- /** The UUID version this identity is documented to carry. */
- private static final int VERSION_7 = 7;
-
- public MessageId {
- Objects.requireNonNull(value, "messageId value must not be null");
- // The type says UUIDv7 and the constructor accepted any UUID, including v4 and the nil UUID.
- // Version 7 is what makes the identity time-ordered, which is what the outbox index and every
- // "oldest first" claim depend on; a v4 stored in the same column silently defeats both.
- if (value.version() != VERSION_7) {
- throw new IllegalArgumentException(
- "a message identity is UUIDv7 (time-ordered); this is version " + value.version());
- }
- if (value.variant() != 2) {
- throw new IllegalArgumentException("a message identity must use the RFC 4122 variant");
- }
- }
-
- /**
- * Mints a new logical message identity.
- *
- * @return a fresh time-ordered identity
- */
- public static MessageId newId() {
- return new MessageId(UuidV7.next());
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/MessageType.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/MessageType.java
deleted file mode 100644
index 953757b2..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/MessageType.java
+++ /dev/null
@@ -1,21 +0,0 @@
-package dev.caskeleton.messaging.api;
-
-/**
- * Stable catalog name of a message, such as {@code order.created}.
- *
- * Java class names are deliberately not usable as a message type: renaming or repackaging a
- * class must never change the wire contract.
- *
- * @param value the catalog name, 1 to 240 UTF-8 bytes and free of control characters
- */
-public record MessageType(String value) {
-
- private static final int MAX_BYTES = 240;
-
- public MessageType {
- if (value == null || value.isBlank()) {
- throw new IllegalArgumentException("messageType must not be blank");
- }
- WireSafeText.require(value, "a message type", MAX_BYTES);
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/ProducerId.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/ProducerId.java
deleted file mode 100644
index 0bb858a3..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/ProducerId.java
+++ /dev/null
@@ -1,21 +0,0 @@
-package dev.caskeleton.messaging.api;
-
-/**
- * Logical service identity of the component that produced a message.
- *
- * This is a deployment-independent service name, not a host, pod, or connection identity, so
- * that it stays a bounded value safe for metric tags.
- *
- * @param value the service name, 1 to 120 UTF-8 bytes and free of control characters
- */
-public record ProducerId(String value) {
-
- private static final int MAX_BYTES = 120;
-
- public ProducerId {
- if (value == null || value.isBlank()) {
- throw new IllegalArgumentException("producerId must not be blank");
- }
- WireSafeText.require(value, "a producer id", MAX_BYTES);
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/SchemaVersion.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/SchemaVersion.java
deleted file mode 100644
index 5c6b46a2..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/SchemaVersion.java
+++ /dev/null
@@ -1,15 +0,0 @@
-package dev.caskeleton.messaging.api;
-
-/**
- * Monotonic schema revision of a {@link MessageType}.
- *
- * @param value the revision, starting at 1
- */
-public record SchemaVersion(int value) {
-
- public SchemaVersion {
- if (value < 1) {
- throw new IllegalArgumentException("schemaVersion must be positive");
- }
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/TenantContext.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/TenantContext.java
deleted file mode 100644
index a71c33cc..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/TenantContext.java
+++ /dev/null
@@ -1,24 +0,0 @@
-package dev.caskeleton.messaging.api;
-
-import java.util.regex.Pattern;
-
-/**
- * Bounded tenant identity carried with a message.
- *
- * The value is deliberately constrained to a short slug. Tenant identity is one of the few
- * envelope fields that observability code is tempted to use as a metric label, and an unbounded
- * tenant id turns that into a cardinality explosion.
- *
- * @param tenantId the tenant slug
- */
-public record TenantContext(String tenantId) {
-
- private static final Pattern VALID = Pattern.compile("[a-z0-9][a-z0-9._-]{0,63}");
-
- public TenantContext {
- if (tenantId == null || !VALID.matcher(tenantId).matches()) {
- throw new IllegalArgumentException(
- "tenantId must match [a-z0-9][a-z0-9._-]{0,63}: " + tenantId);
- }
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/TraceContext.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/TraceContext.java
deleted file mode 100644
index b71623f4..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/TraceContext.java
+++ /dev/null
@@ -1,155 +0,0 @@
-package dev.caskeleton.messaging.api;
-
-import java.nio.charset.StandardCharsets;
-import java.util.Objects;
-import java.util.Optional;
-import java.util.regex.Pattern;
-
-/**
- * W3C trace propagation values carried with a message.
- *
- * The platform creates and propagates these; handlers do not set them. Keeping them on the
- * envelope rather than only in headers means a trace survives an Outbox round trip through the
- * database, where broker headers do not exist yet.
- *
- * The three values used to be checked for non-nullness and nothing more, which made this record
- * a general-purpose string carrier wearing the name of a standard. Anything accepted here is
- * written to the {@code traceparent}, {@code tracestate} and {@code baggage} headers of every
- * broker the message touches, so an unvalidated value is both a header-injection vector and a
- * silent trace break: a collector that cannot parse {@code traceparent} drops the span rather than
- * reporting a bad value, and the trace disappears at exactly the hop being investigated.
- *
- * @param traceparent the {@code traceparent} value when a trace is active
- * @param tracestate the {@code tracestate} value when present
- * @param baggage the {@code baggage} value when present
- */
-public record TraceContext(
- Optional Uppercase hex is refused rather than folded: the standard defines the field as lowercase,
- * and a receiver comparing trace IDs as strings — which collectors do — would treat the two cases
- * as two different traces.
- */
- private static final Pattern TRACEPARENT =
- Pattern.compile("[0-9a-f]{2}-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}");
-
- private static final String ALL_ZERO_TRACE_ID = "0".repeat(32);
-
- private static final String ALL_ZERO_SPAN_ID = "0".repeat(16);
-
- /** {@code key=value} or {@code tenant@vendor=value}, per the standard's list-member grammar. */
- private static final Pattern TRACESTATE_MEMBER =
- Pattern.compile(
- "[a-z0-9][_\\-*/a-z0-9]{0,255}(@[a-z0-9][_\\-*/a-z0-9]{0,13})?=[\\x20-\\x7E&&[^,=]]{0,255}");
-
- /**
- * The standard's bounds: at most 32 list members, and a field a receiver is allowed to truncate.
- */
- private static final int MAX_TRACESTATE_MEMBERS = 32;
-
- private static final int MAX_TRACESTATE_BYTES = 512;
-
- /** W3C Baggage bounds: 8192 bytes total across at most 64 members. */
- private static final int MAX_BAGGAGE_BYTES = 8192;
-
- private static final int MAX_BAGGAGE_MEMBERS = 64;
-
- public TraceContext {
- Objects.requireNonNull(traceparent, "traceparent must not be null");
- Objects.requireNonNull(tracestate, "tracestate must not be null");
- Objects.requireNonNull(baggage, "baggage must not be null");
- traceparent.ifPresent(TraceContext::requireValidTraceparent);
- tracestate.ifPresent(TraceContext::requireValidTracestate);
- baggage.ifPresent(TraceContext::requireValidBaggage);
- if (tracestate.isPresent() && traceparent.isEmpty()) {
- // A tracestate without a traceparent is vendor state belonging to no trace. Propagating it
- // hands the next hop a key it will attribute to whatever trace that hop starts.
- throw new IllegalArgumentException("tracestate must not be present without a traceparent");
- }
- }
-
- private static void requireValidTraceparent(String value) {
- if (!TRACEPARENT.matcher(value).matches()) {
- throw new IllegalArgumentException(
- "traceparent must be version-traceid-spanid-flags in lowercase hex: '" + value + '\'');
- }
- String version = value.substring(0, 2);
- if ("ff".equals(version)) {
- // The standard reserves ff and requires a receiver to reject it, rather than treat it as a
- // future version to be forwarded.
- throw new IllegalArgumentException("traceparent version ff is invalid");
- }
- String traceId = value.substring(3, 35);
- if (ALL_ZERO_TRACE_ID.equals(traceId)) {
- throw new IllegalArgumentException("traceparent carries an all-zero trace id");
- }
- String spanId = value.substring(36, 52);
- if (ALL_ZERO_SPAN_ID.equals(spanId)) {
- throw new IllegalArgumentException("traceparent carries an all-zero parent span id");
- }
- }
-
- private static void requireValidTracestate(String value) {
- int bytes = value.getBytes(StandardCharsets.UTF_8).length;
- if (bytes > MAX_TRACESTATE_BYTES) {
- throw new IllegalArgumentException("tracestate exceeds 512 bytes: " + bytes);
- }
- String[] members = value.split(",", -1);
- if (members.length > MAX_TRACESTATE_MEMBERS) {
- throw new IllegalArgumentException(
- "tracestate carries more than 32 list members: " + members.length);
- }
- for (String member : members) {
- String trimmed = member.strip();
- if (trimmed.isEmpty()) {
- // The grammar permits empty members for forward compatibility; nothing is propagated for
- // them, so they are dropped by the receiver rather than being an error here.
- continue;
- }
- if (!TRACESTATE_MEMBER.matcher(trimmed).matches()) {
- throw new IllegalArgumentException("tracestate member is not valid: '" + trimmed + '\'');
- }
- }
- }
-
- private static void requireValidBaggage(String value) {
- int bytes = value.getBytes(StandardCharsets.UTF_8).length;
- if (bytes > MAX_BAGGAGE_BYTES) {
- throw new IllegalArgumentException("baggage exceeds 8192 bytes: " + bytes);
- }
- WireSafeText.requireNoControls(value, "baggage");
- String[] members = value.split(",", -1);
- if (members.length > MAX_BAGGAGE_MEMBERS) {
- throw new IllegalArgumentException("baggage carries more than 64 members: " + members.length);
- }
- for (String member : members) {
- String trimmed = member.strip();
- int equals = trimmed.indexOf('=');
- if (equals <= 0 || equals == trimmed.length() - 1) {
- throw new IllegalArgumentException("baggage member must be key=value: '" + trimmed + '\'');
- }
- }
- }
-
- /**
- * Returns a context with no active trace.
- *
- * @return an empty trace context
- */
- public static TraceContext none() {
- return new TraceContext(Optional.empty(), Optional.empty(), Optional.empty());
- }
-
- /**
- * Returns a context carrying only a trace parent.
- *
- * @param traceparent the {@code traceparent} value
- * @return a trace context
- */
- public static TraceContext of(String traceparent) {
- return new TraceContext(Optional.of(traceparent), Optional.empty(), Optional.empty());
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/UuidV7.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/UuidV7.java
deleted file mode 100644
index b5d920d1..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/UuidV7.java
+++ /dev/null
@@ -1,62 +0,0 @@
-package dev.caskeleton.messaging.api;
-
-import java.security.SecureRandom;
-import java.util.UUID;
-import java.util.concurrent.atomic.AtomicLong;
-
-/**
- * Generates RFC 9562 UUIDv7 values.
- *
- * The platform needs message identifiers that sort by creation time so that outbox scans, DLQ
- * listings, and broker partitions stay locality-friendly, while still being globally unique. The 12
- * bit {@code rand_a} field is used as a monotonic intra-millisecond counter instead of random bits:
- * two calls in the same millisecond are then still strictly ordered, which is what makes "same
- * logical message keeps the same id" auditable across a retry.
- */
-public final class UuidV7 {
-
- private static final SecureRandom RANDOM = new SecureRandom();
-
- /** Packs the 48-bit millisecond timestamp in the high bits and the 12-bit counter in the low. */
- private static final AtomicLong STATE = new AtomicLong();
-
- private static final long COUNTER_BITS = 12L;
- private static final long COUNTER_MASK = 0xFFFL;
- private static final long VERSION_7 = 0x7L;
- private static final long VARIANT_RFC9562 = 0x8000_0000_0000_0000L;
- private static final long RANDOM_B_MASK = 0x3FFF_FFFF_FFFF_FFFFL;
-
- private UuidV7() {}
-
- /**
- * Returns the next monotonically increasing UUIDv7.
- *
- * @return a version 7, variant 2 UUID
- */
- public static UUID next() {
- long state = STATE.updateAndGet(UuidV7::advance);
- long timestamp = state >>> COUNTER_BITS;
- long counter = state & COUNTER_MASK;
-
- long mostSignificantBits = (timestamp << 16) | (VERSION_7 << COUNTER_BITS) | counter;
- long leastSignificantBits = (RANDOM.nextLong() & RANDOM_B_MASK) | VARIANT_RFC9562;
- return new UUID(mostSignificantBits, leastSignificantBits);
- }
-
- /**
- * Advances the packed state.
- *
- * When the clock moved forward the counter restarts at zero. Otherwise the packed value is
- * simply incremented: that bumps the counter and, once the 12-bit counter overflows, carries into
- * the timestamp field. A backwards clock step therefore never produces a duplicate or a
- * descending id, it only borrows from the future.
- */
- private static long advance(long previous) {
- long now = System.currentTimeMillis();
- long previousTimestamp = previous >>> COUNTER_BITS;
- if (now > previousTimestamp) {
- return now << COUNTER_BITS;
- }
- return previous + 1;
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/WireSafeText.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/WireSafeText.java
deleted file mode 100644
index f919c320..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/WireSafeText.java
+++ /dev/null
@@ -1,65 +0,0 @@
-package dev.caskeleton.messaging.api;
-
-import java.nio.charset.StandardCharsets;
-
-/**
- * The one place that decides which text may reach a broker.
- *
- * Every wire-facing value used to bound itself in Java {@code char}s and check nothing else. A
- * {@code char} count bounds nothing on a wire: a 240-character string is up to 960 UTF-8 bytes, so
- * a "240 character" limit is a 960-byte limit against a broker that counts bytes. And a control
- * character passes a length check untouched — CR and LF split records on line-oriented protocols,
- * NUL truncates them in C string handling inside a broker, and DEL is stripped by some
- * intermediaries and preserved by others. A value that survives one broker and corrupts the next is
- * worse than a rejected one.
- *
- * The rule is refused rather than sanitised on purpose. Silently stripping a CR turns a caller's
- * two-line value into a one-line value that no longer means what they wrote, and the caller never
- * learns; the broker downstream cannot tell the difference between that and a legitimate value.
- *
- * Each copy of this check that lived in its own record was one more place for the rule to drift.
- */
-public final class WireSafeText {
-
- private WireSafeText() {}
-
- /**
- * Refuses text that no broker should be asked to carry.
- *
- * Horizontal tab is refused along with the rest of the C0 range. It is legal in an HTTP field
- * value, and that is exactly the problem: a header carried over a line-folding binding and the
- * same header carried over a length-prefixed one disagree about whether a tab ends the value.
- * Nothing in this platform needs a tab in an identifier or a header.
- *
- * @param value the text to check
- * @param what a noun phrase naming the value, used in the failure message
- * @param maxBytes the inclusive UTF-8 byte bound
- * @throws IllegalArgumentException when the text carries a control character or exceeds the bound
- */
- public static void require(String value, String what, int maxBytes) {
- requireNoControls(value, what);
- int bytes = value.getBytes(StandardCharsets.UTF_8).length;
- if (bytes > maxBytes) {
- throw new IllegalArgumentException(
- what + " exceeds " + maxBytes + " UTF-8 bytes: " + bytes + " bytes");
- }
- }
-
- /**
- * Refuses control characters without applying a size bound.
- *
- * @param value the text to check
- * @param what a noun phrase naming the value, used in the failure message
- * @throws IllegalArgumentException when the text carries a control character
- */
- public static void requireNoControls(String value, String what) {
- for (int index = 0; index < value.length(); index++) {
- char character = value.charAt(index);
- if (character < 0x20 || character == 0x7F) {
- throw new IllegalArgumentException(
- "%s must not contain control characters (found U+%04X at index %d)"
- .formatted(what, (int) character, index));
- }
- }
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/DeliveryContext.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/DeliveryContext.java
deleted file mode 100644
index 2a44d71f..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/DeliveryContext.java
+++ /dev/null
@@ -1,36 +0,0 @@
-package dev.caskeleton.messaging.api.delivery;
-
-import java.time.Instant;
-import java.util.Objects;
-
-/**
- * Runtime context handed to a handler alongside a delivery.
- *
- * {@code shutdownRequested} is visible to handlers on purpose: during a graceful drain the
- * platform stops creating new retry attempts, and a long-running handler that can wind down early
- * shortens the drain instead of being cancelled at the deadline.
- *
- * @param handlerDeadline the instant after which the handler is considered timed out
- * @param shutdownRequested whether the consumer has begun draining
- * @param consumerId the stable, low-cardinality consumer identity
- */
-public record DeliveryContext(
- Instant handlerDeadline, boolean shutdownRequested, String consumerId) {
-
- public DeliveryContext {
- Objects.requireNonNull(handlerDeadline, "handlerDeadline must not be null");
- if (consumerId == null || consumerId.isBlank()) {
- throw new IllegalArgumentException("consumerId must not be blank");
- }
- }
-
- /**
- * Reports whether the handler deadline has passed.
- *
- * @param now the current instant
- * @return true when the deadline has elapsed
- */
- public boolean isExpired(Instant now) {
- return !now.isBefore(handlerDeadline);
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/DeliveryGuarantee.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/DeliveryGuarantee.java
deleted file mode 100644
index 492247c0..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/DeliveryGuarantee.java
+++ /dev/null
@@ -1,18 +0,0 @@
-package dev.caskeleton.messaging.api.delivery;
-
-/**
- * Broker-level delivery guarantee offered by the common contract.
- *
- * There is deliberately no {@code EXACTLY_ONCE} constant. No broker delivers exactly-once across
- * an external side effect; what real systems provide is at-least-once delivery combined with an
- * idempotent or transactional consumer. Naming a guarantee the platform cannot honour would push
- * that responsibility out of sight, so the enum stops where the evidence stops.
- */
-public enum DeliveryGuarantee {
-
- /** Delivery may be lost; duplicate suppression is preferred over durability. */
- AT_MOST_ONCE,
-
- /** Redelivery is possible; durability is preferred over duplicate suppression. */
- AT_LEAST_ONCE
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/DeliveryMetadata.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/DeliveryMetadata.java
deleted file mode 100644
index 3e107c2f..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/DeliveryMetadata.java
+++ /dev/null
@@ -1,46 +0,0 @@
-package dev.caskeleton.messaging.api.delivery;
-
-import dev.caskeleton.messaging.api.destination.DestinationName;
-import dev.caskeleton.messaging.api.publish.BrokerPosition;
-import java.time.Instant;
-import java.util.Objects;
-import java.util.Optional;
-
-/**
- * Transport-side facts about one delivery attempt.
- *
- * The first delivery is attempt one, not zero. Off-by-one confusion here directly changes how
- * many times a poison message is replayed before it is parked, so the counting rule is fixed at the
- * contract rather than left to each adapter.
- *
- * @param destination the logical destination
- * @param deliveryAttempt the attempt number, starting at one
- * @param redelivered whether the broker flagged this as a redelivery
- * @param brokerPosition the broker coordinate when available
- * @param partitionOrQueue the ordering unit when available
- * @param consumerGroup the consumer group when applicable
- * @param receivedAt when the consumer received the delivery
- */
-public record DeliveryMetadata(
- DestinationName destination,
- int deliveryAttempt,
- boolean redelivered,
- Optional The handler states an intent; the platform performs the settlement. That split is what keeps
- * "acknowledge only after the handler succeeded" a platform invariant rather than something each
- * handler has to remember, and it is why no variant here carries a broker acknowledgement handle.
- */
-public sealed interface HandleResult
- permits HandleResult.Success, HandleResult.Retry, HandleResult.DeadLetter, HandleResult.Reject {
-
- /** Processing succeeded; the platform may settle the source. */
- record Success() implements HandleResult {}
-
- /**
- * Processing failed in a way that may succeed later.
- *
- * @param failure the sanitized failure description
- */
- record Retry(FailureDescriptor failure) implements HandleResult {
- public Retry {
- Objects.requireNonNull(failure, "failure must not be null");
- }
- }
-
- /**
- * Processing failed permanently; route to the dead letter destination.
- *
- * @param failure the sanitized failure description
- */
- record DeadLetter(FailureDescriptor failure) implements HandleResult {
- public DeadLetter {
- Objects.requireNonNull(failure, "failure must not be null");
- }
- }
-
- /**
- * Discard the message without dead lettering.
- *
- * @param failure the sanitized failure description
- */
- record Reject(FailureDescriptor failure) implements HandleResult {
- public Reject {
- Objects.requireNonNull(failure, "failure must not be null");
- }
- }
-
- /**
- * Returns a successful result.
- *
- * @return the success variant
- */
- static HandleResult success() {
- return new Success();
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/MessageDelivery.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/MessageDelivery.java
deleted file mode 100644
index ac1bc230..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/MessageDelivery.java
+++ /dev/null
@@ -1,22 +0,0 @@
-package dev.caskeleton.messaging.api.delivery;
-
-import dev.caskeleton.messaging.api.MessageEnvelope;
-import java.util.Objects;
-
-/**
- * One decoded message handed to a handler.
- *
- * @param Handlers state an outcome and never touch broker acknowledgement APIs. Duplicate delivery is a
- * normal condition, not an error: implementations are expected to be idempotent, or to consume a
- * destination whose profile declares {@code INBOX_TRANSACTIONAL}, where the platform runs the
- * handler inside the inbox reservation's transaction.
- *
- * Registering an implementation as a bean is what turns consumption on: the broker starter opens
- * a consumer for every destination at least one handler names. There is no second, batch or manual
- * settlement contract; the platform settles, after the handler has answered.
- *
- * @param A destination may carry several message types; each type has at most one handler.
- *
- * @return what this handler consumes
- */
- MessageDestination This declaration is the consumer's whole registration. The platform decodes a delivery only
- * against a contract — message type and schema version — it knows the payload class for, and it
- * builds that list from the handler beans: each version here, with the destination's message
- * type, decodes into the destination's payload class. A service writes no registration code of
- * its own, so a handler cannot exist while its messages are dead-lettered as undecodable for want
- * of one.
- *
- * A version the handler does not name is still refused ({@code SCHEMA_VERSION_NOT_REGISTERED})
- * rather than decoded into a class written for another version. A handler that reads a second
- * version says so here when the producer starts sending it.
- *
- * @return the versions this handler reads; version 1 unless it declares otherwise
- */
- default Set There is deliberately no {@code GLOBAL} constant. Ordering is a property of a partition, a key
- * mapping, or a single consumer — never of a whole destination — and advertising a global scope
- * would promise something no partitioned broker can keep.
- */
-public enum OrderingScope {
-
- /** No order is promised. */
- NONE,
-
- /** Order holds across the destination, which requires a single ordering unit. */
- DESTINATION,
-
- /** Order holds inside one broker partition. */
- PARTITION,
-
- /** Order holds for one key while its mapping to an ordering unit is stable. */
- KEY
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/ConfirmationRequirement.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/ConfirmationRequirement.java
deleted file mode 100644
index e260c916..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/ConfirmationRequirement.java
+++ /dev/null
@@ -1,20 +0,0 @@
-package dev.caskeleton.messaging.api.destination;
-
-/**
- * The publish confirmation a destination profile demands.
- *
- * This is the requested level. What the broker actually supplied is reported separately as a
- * confirmation level on the publish evidence, so a profile asking for replication evidence against
- * an adapter that can only prove a broker ack fails at startup instead of silently downgrading.
- */
-public enum ConfirmationRequirement {
-
- /** No confirmation is required; only valid for at-most-once profiles. */
- NONE,
-
- /** The broker must acknowledge receipt. */
- BROKER_ACK,
-
- /** The broker must acknowledge replication or persistence. */
- REPLICATION_OR_PERSISTENCE_ACK
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/DestinationCapabilities.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/DestinationCapabilities.java
deleted file mode 100644
index fc212e0e..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/DestinationCapabilities.java
+++ /dev/null
@@ -1,26 +0,0 @@
-package dev.caskeleton.messaging.api.destination;
-
-import java.util.Objects;
-
-/**
- * A capability snapshot bound to one logical destination.
- *
- * Capabilities are per destination, not per broker: the same Kafka cluster offers keyed ordering
- * on a partitioned topic and none on a share group, and the same RabbitMQ node offers native dead
- * lettering only where the queue was declared with one.
- *
- * @param destination the logical destination
- * @param broker the adapter's broker name
- * @param capabilities what the adapter can prove for this destination
- */
-public record DestinationCapabilities(
- DestinationName destination, String broker, MessagingCapabilities capabilities) {
-
- public DestinationCapabilities {
- Objects.requireNonNull(destination, "destination must not be null");
- Objects.requireNonNull(capabilities, "capabilities must not be null");
- if (broker == null || broker.isBlank()) {
- throw new IllegalArgumentException("broker must not be blank");
- }
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/DestinationKind.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/DestinationKind.java
deleted file mode 100644
index 7051e788..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/DestinationKind.java
+++ /dev/null
@@ -1,32 +0,0 @@
-package dev.caskeleton.messaging.api.destination;
-
-/**
- * The interaction pattern a destination implements.
- *
- * This drives validation rather than transport: an event stream may keep ordering and replay, a
- * work queue may not, and a request-reply destination needs a correlation strategy no other kind
- * requires.
- */
-public enum DestinationKind {
-
- /** Point-to-point command delivered to exactly one logical handler. */
- ASYNC_COMMAND,
-
- /** Fact published inside one bounded context. */
- DOMAIN_EVENT,
-
- /** Fact published across bounded contexts under a stable schema contract. */
- INTEGRATION_EVENT,
-
- /** Competing consumers draining a shared backlog. */
- WORK_QUEUE,
-
- /** Fan-out to independent subscribers. */
- PUBLISH_SUBSCRIBE,
-
- /** Retained, replayable, partitioned log. */
- EVENT_STREAM,
-
- /** Correlated request and reply, available only as an M2 capability. */
- REQUEST_REPLY
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/DestinationName.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/DestinationName.java
deleted file mode 100644
index c5a12dfb..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/DestinationName.java
+++ /dev/null
@@ -1,24 +0,0 @@
-package dev.caskeleton.messaging.api.destination;
-
-import java.util.regex.Pattern;
-
-/**
- * Logical name of a destination.
- *
- * The pattern excludes {@code :}, {@code /}, and whitespace so that a broker address can never
- * be smuggled in as a logical name. {@code topic://orders} has to fail here, otherwise the physical
- * mapping owned by the destination profile could be bypassed from application code.
- *
- * @param value the logical name
- */
-public record DestinationName(String value) {
-
- private static final Pattern VALID = Pattern.compile("[a-z0-9][a-z0-9.-]{0,159}");
-
- public DestinationName {
- if (value == null || !VALID.matcher(value).matches()) {
- throw new IllegalArgumentException(
- "destination name must match [a-z0-9][a-z0-9.-]{0,159}: " + value);
- }
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/MessageDestination.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/MessageDestination.java
deleted file mode 100644
index 253a588f..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/destination/MessageDestination.java
+++ /dev/null
@@ -1,26 +0,0 @@
-package dev.caskeleton.messaging.api.destination;
-
-import dev.caskeleton.messaging.api.MessageType;
-import java.util.Objects;
-
-/**
- * The application-facing handle for a destination.
- *
- * It carries a logical name, the catalog message type, and the payload class — never a topic,
- * exchange, queue, or subject. The physical mapping lives in the destination profile, which is what
- * lets the same code run against Kafka in production and an in-memory harness in tests.
- *
- * @param The common API does not assume every broker supports every feature. When a profile asks for
- * something absent here the platform fails loudly — at startup where possible, otherwise with a
- * capability exception — rather than quietly degrading, because a silently weakened guarantee is
- * indistinguishable from a working one until the incident.
- *
- * A set of named capabilities rather than a row of positional booleans. The record used to take
- * twelve booleans in a fixed order, and an adapter declared itself with {@code new
- * MessagingCapabilities(true, true, …, false, true)} — a line where swapping two arguments changes
- * a guarantee and still compiles. Only the capabilities the platform reads are named: a flag
- * nothing consults is a promise nobody checks.
- *
- * @param supported the capabilities the adapter can prove
- */
-public record MessagingCapabilities(Set Categories exist so that retry decisions are made from a declared class of failure rather than
- * from exception type matching, which drifts every time a client library is upgraded.
- */
-public enum FailureCategory {
-
- /** Broker or network fault expected to clear on its own. */
- TRANSIENT_INFRASTRUCTURE,
-
- /** The broker or a downstream applied backpressure or a quota. */
- THROTTLED,
-
- /** The handler failed in a way that may succeed on redelivery. */
- PROCESSING_TRANSIENT,
-
- /** The business rejected the message; redelivery cannot help. */
- PERMANENT_BUSINESS,
-
- /** The message repeatedly destroys its consumer and must be parked. */
- POISON_MESSAGE,
-
- /** The payload could not be decoded against its schema. */
- DESERIALIZATION,
-
- /** Broker authentication failed. */
- AUTHENTICATION,
-
- /** Broker authorization denied the operation. */
- AUTHORIZATION,
-
- /** The outcome could not be determined. */
- AMBIGUOUS,
-
- /** The platform or destination is misconfigured. */
- CONFIGURATION
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/FailureDescriptor.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/FailureDescriptor.java
deleted file mode 100644
index ff8dd47a..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/FailureDescriptor.java
+++ /dev/null
@@ -1,88 +0,0 @@
-package dev.caskeleton.messaging.api.error;
-
-import java.util.Objects;
-import java.util.Optional;
-
-/**
- * A sanitized, transportable description of a failure.
- *
- * This travels in reserved headers to retry destinations and DLQs, so it deliberately holds no
- * payload, no stack trace, no credential, and no actual message key. Stack traces belong in secure
- * log storage; a DLQ is read by more people than the log is.
- *
- * @param category the stable classification
- * @param code a stable, machine-readable code
- * @param retryable whether automatic retry is permitted
- * @param sanitizedMessage a short operator-facing description
- * @param exceptionType the originating exception's simple type name, when known
- */
-public record FailureDescriptor(
- FailureCategory category,
- String code,
- boolean retryable,
- String sanitizedMessage,
- Optional Deserialization, authentication, authorization, and configuration failures are never retried
- * automatically: each of them fails identically on every redelivery, so retrying only multiplies
- * the load while the message is still poison.
- *
- * A default, not a rule every descriptor follows. A publish rejection may carry {@code
- * retryable = true} with an authentication or authorization category: the broker did not store
- * the record, and a credential being rotated or an ACL deployed after the application refuses
- * every publish for a few minutes and then stops (the Kafka publish classifier). The
- * consumer-side retry engine requires this default as well as the flag unless its policy names
- * the category, so redelivery of an unauthorised message is still not retried; only a publisher
- * that reads {@link #retryable()} sees the difference.
- *
- * @param category the classification
- * @return true when automatic retry is allowed by default
- */
- public static boolean defaultRetryable(FailureCategory category) {
- return switch (category) {
- case TRANSIENT_INFRASTRUCTURE, THROTTLED, PROCESSING_TRANSIENT -> true;
- case PERMANENT_BUSINESS,
- POISON_MESSAGE,
- DESERIALIZATION,
- AUTHENTICATION,
- AUTHORIZATION,
- AMBIGUOUS,
- CONFIGURATION ->
- false;
- };
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageAuthorizationException.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageAuthorizationException.java
deleted file mode 100644
index 5f373006..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageAuthorizationException.java
+++ /dev/null
@@ -1,49 +0,0 @@
-package dev.caskeleton.messaging.api.error;
-
-import java.io.Serial;
-import java.util.Optional;
-
-/** The broker denied the operation for these credentials. */
-public class MessageAuthorizationException extends MessagingException {
-
- @Serial private static final long serialVersionUID = 1L;
-
- private static final FailureCategory CATEGORY = FailureCategory.AUTHORIZATION;
-
- /**
- * Creates the exception with a stable code and sanitized message.
- *
- * @param code the stable failure code
- * @param sanitizedMessage the operator-facing description
- */
- public MessageAuthorizationException(String code, String sanitizedMessage) {
- super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty()));
- }
-
- /**
- * Creates the exception with an originating cause.
- *
- * @param code the stable failure code
- * @param sanitizedMessage the operator-facing description
- * @param cause the originating throwable
- */
- public MessageAuthorizationException(String code, String sanitizedMessage, Throwable cause) {
- super(
- new FailureDescriptor(
- CATEGORY,
- code,
- false,
- sanitizedMessage,
- Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
- cause);
- }
-
- /**
- * Creates the exception from an explicit descriptor.
- *
- * @param failure the sanitized failure description
- */
- public MessageAuthorizationException(FailureDescriptor failure) {
- super(failure);
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageBackpressureException.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageBackpressureException.java
deleted file mode 100644
index aee51346..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageBackpressureException.java
+++ /dev/null
@@ -1,40 +0,0 @@
-package dev.caskeleton.messaging.api.error;
-
-import java.io.Serial;
-import java.util.Optional;
-
-/**
- * Admission was refused because the platform is already at its in-flight or buffer ceiling.
- *
- * Retryable, and deliberately raised rather than absorbed by an unbounded wait. Blocking the
- * caller until a slot frees turns producer-side saturation into thread exhaustion in the calling
- * application, which is a far worse failure than a fast rejection the caller can shed or retry.
- *
- * Nothing was transmitted when this is thrown, so the message has no ambiguity: the caller may
- * resubmit it under the same {@code messageId} without risking a duplicate.
- */
-public class MessageBackpressureException extends MessagingException {
-
- @Serial private static final long serialVersionUID = 1L;
-
- private static final FailureCategory CATEGORY = FailureCategory.TRANSIENT_INFRASTRUCTURE;
-
- /**
- * Creates the exception with a stable code and sanitized message.
- *
- * @param code the stable failure code
- * @param sanitizedMessage the operator-facing description
- */
- public MessageBackpressureException(String code, String sanitizedMessage) {
- super(new FailureDescriptor(CATEGORY, code, true, sanitizedMessage, Optional.empty()));
- }
-
- /**
- * Creates the exception from an explicit descriptor.
- *
- * @param failure the sanitized failure description
- */
- public MessageBackpressureException(FailureDescriptor failure) {
- super(failure);
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessagePublishTimeoutException.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessagePublishTimeoutException.java
deleted file mode 100644
index 959cd7a8..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessagePublishTimeoutException.java
+++ /dev/null
@@ -1,54 +0,0 @@
-package dev.caskeleton.messaging.api.error;
-
-import java.io.Serial;
-import java.util.Optional;
-
-/**
- * The publish deadline expired before a confirmation arrived.
- *
- * A timeout is not a rejection. The bytes may already be replicated, so this is classified as
- * ambiguous rather than failed.
- */
-public class MessagePublishTimeoutException extends MessagingException {
-
- @Serial private static final long serialVersionUID = 1L;
-
- private static final FailureCategory CATEGORY = FailureCategory.AMBIGUOUS;
-
- /**
- * Creates the exception with a stable code and sanitized message.
- *
- * @param code the stable failure code
- * @param sanitizedMessage the operator-facing description
- */
- public MessagePublishTimeoutException(String code, String sanitizedMessage) {
- super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty()));
- }
-
- /**
- * Creates the exception with an originating cause.
- *
- * @param code the stable failure code
- * @param sanitizedMessage the operator-facing description
- * @param cause the originating throwable
- */
- public MessagePublishTimeoutException(String code, String sanitizedMessage, Throwable cause) {
- super(
- new FailureDescriptor(
- CATEGORY,
- code,
- false,
- sanitizedMessage,
- Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
- cause);
- }
-
- /**
- * Creates the exception from an explicit descriptor.
- *
- * @param failure the sanitized failure description
- */
- public MessagePublishTimeoutException(FailureDescriptor failure) {
- super(failure);
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageSchemaIncompatibleException.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageSchemaIncompatibleException.java
deleted file mode 100644
index 5709d961..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageSchemaIncompatibleException.java
+++ /dev/null
@@ -1,49 +0,0 @@
-package dev.caskeleton.messaging.api.error;
-
-import java.io.Serial;
-import java.util.Optional;
-
-/** The payload's schema is incompatible with the registered contract. */
-public class MessageSchemaIncompatibleException extends MessagingException {
-
- @Serial private static final long serialVersionUID = 1L;
-
- private static final FailureCategory CATEGORY = FailureCategory.DESERIALIZATION;
-
- /**
- * Creates the exception with a stable code and sanitized message.
- *
- * @param code the stable failure code
- * @param sanitizedMessage the operator-facing description
- */
- public MessageSchemaIncompatibleException(String code, String sanitizedMessage) {
- super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty()));
- }
-
- /**
- * Creates the exception with an originating cause.
- *
- * @param code the stable failure code
- * @param sanitizedMessage the operator-facing description
- * @param cause the originating throwable
- */
- public MessageSchemaIncompatibleException(String code, String sanitizedMessage, Throwable cause) {
- super(
- new FailureDescriptor(
- CATEGORY,
- code,
- false,
- sanitizedMessage,
- Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
- cause);
- }
-
- /**
- * Creates the exception from an explicit descriptor.
- *
- * @param failure the sanitized failure description
- */
- public MessageSchemaIncompatibleException(FailureDescriptor failure) {
- super(failure);
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageSerializationException.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageSerializationException.java
deleted file mode 100644
index fce4c892..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageSerializationException.java
+++ /dev/null
@@ -1,49 +0,0 @@
-package dev.caskeleton.messaging.api.error;
-
-import java.io.Serial;
-import java.util.Optional;
-
-/** The payload could not be encoded or decoded. */
-public class MessageSerializationException extends MessagingException {
-
- @Serial private static final long serialVersionUID = 1L;
-
- private static final FailureCategory CATEGORY = FailureCategory.DESERIALIZATION;
-
- /**
- * Creates the exception with a stable code and sanitized message.
- *
- * @param code the stable failure code
- * @param sanitizedMessage the operator-facing description
- */
- public MessageSerializationException(String code, String sanitizedMessage) {
- super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty()));
- }
-
- /**
- * Creates the exception with an originating cause.
- *
- * @param code the stable failure code
- * @param sanitizedMessage the operator-facing description
- * @param cause the originating throwable
- */
- public MessageSerializationException(String code, String sanitizedMessage, Throwable cause) {
- super(
- new FailureDescriptor(
- CATEGORY,
- code,
- false,
- sanitizedMessage,
- Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
- cause);
- }
-
- /**
- * Creates the exception from an explicit descriptor.
- *
- * @param failure the sanitized failure description
- */
- public MessageSerializationException(FailureDescriptor failure) {
- super(failure);
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageTooLargeException.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageTooLargeException.java
deleted file mode 100644
index c62fb934..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageTooLargeException.java
+++ /dev/null
@@ -1,54 +0,0 @@
-package dev.caskeleton.messaging.api.error;
-
-import java.io.Serial;
-import java.util.Optional;
-
-/**
- * The encoded payload exceeds the destination's byte limit.
- *
- * Payloads above the portability limit are expected to use Claim Check rather than a larger
- * broker frame, so this failure points at a design choice and never at a transient fault.
- */
-public class MessageTooLargeException extends MessagingException {
-
- @Serial private static final long serialVersionUID = 1L;
-
- private static final FailureCategory CATEGORY = FailureCategory.PERMANENT_BUSINESS;
-
- /**
- * Creates the exception with a stable code and sanitized message.
- *
- * @param code the stable failure code
- * @param sanitizedMessage the operator-facing description
- */
- public MessageTooLargeException(String code, String sanitizedMessage) {
- super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty()));
- }
-
- /**
- * Creates the exception with an originating cause.
- *
- * @param code the stable failure code
- * @param sanitizedMessage the operator-facing description
- * @param cause the originating throwable
- */
- public MessageTooLargeException(String code, String sanitizedMessage, Throwable cause) {
- super(
- new FailureDescriptor(
- CATEGORY,
- code,
- false,
- sanitizedMessage,
- Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
- cause);
- }
-
- /**
- * Creates the exception from an explicit descriptor.
- *
- * @param failure the sanitized failure description
- */
- public MessageTooLargeException(FailureDescriptor failure) {
- super(failure);
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageTopologyException.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageTopologyException.java
deleted file mode 100644
index 7a156a2e..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageTopologyException.java
+++ /dev/null
@@ -1,49 +0,0 @@
-package dev.caskeleton.messaging.api.error;
-
-import java.io.Serial;
-import java.util.Optional;
-
-/** The broker topology does not match the declared manifest. */
-public class MessageTopologyException extends MessagingException {
-
- @Serial private static final long serialVersionUID = 1L;
-
- private static final FailureCategory CATEGORY = FailureCategory.CONFIGURATION;
-
- /**
- * Creates the exception with a stable code and sanitized message.
- *
- * @param code the stable failure code
- * @param sanitizedMessage the operator-facing description
- */
- public MessageTopologyException(String code, String sanitizedMessage) {
- super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty()));
- }
-
- /**
- * Creates the exception with an originating cause.
- *
- * @param code the stable failure code
- * @param sanitizedMessage the operator-facing description
- * @param cause the originating throwable
- */
- public MessageTopologyException(String code, String sanitizedMessage, Throwable cause) {
- super(
- new FailureDescriptor(
- CATEGORY,
- code,
- false,
- sanitizedMessage,
- Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
- cause);
- }
-
- /**
- * Creates the exception from an explicit descriptor.
- *
- * @param failure the sanitized failure description
- */
- public MessageTopologyException(FailureDescriptor failure) {
- super(failure);
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageValidationException.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageValidationException.java
deleted file mode 100644
index 56cdcf69..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessageValidationException.java
+++ /dev/null
@@ -1,49 +0,0 @@
-package dev.caskeleton.messaging.api.error;
-
-import java.io.Serial;
-import java.util.Optional;
-
-/** The envelope failed platform validation before transport. */
-public class MessageValidationException extends MessagingException {
-
- @Serial private static final long serialVersionUID = 1L;
-
- private static final FailureCategory CATEGORY = FailureCategory.PERMANENT_BUSINESS;
-
- /**
- * Creates the exception with a stable code and sanitized message.
- *
- * @param code the stable failure code
- * @param sanitizedMessage the operator-facing description
- */
- public MessageValidationException(String code, String sanitizedMessage) {
- super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty()));
- }
-
- /**
- * Creates the exception with an originating cause.
- *
- * @param code the stable failure code
- * @param sanitizedMessage the operator-facing description
- * @param cause the originating throwable
- */
- public MessageValidationException(String code, String sanitizedMessage, Throwable cause) {
- super(
- new FailureDescriptor(
- CATEGORY,
- code,
- false,
- sanitizedMessage,
- Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
- cause);
- }
-
- /**
- * Creates the exception from an explicit descriptor.
- *
- * @param failure the sanitized failure description
- */
- public MessageValidationException(FailureDescriptor failure) {
- super(failure);
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessagingCapabilityUnavailableException.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessagingCapabilityUnavailableException.java
deleted file mode 100644
index 84dc2678..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessagingCapabilityUnavailableException.java
+++ /dev/null
@@ -1,56 +0,0 @@
-package dev.caskeleton.messaging.api.error;
-
-import java.io.Serial;
-import java.util.Optional;
-
-/**
- * A requested feature is not supported by the destination's adapter.
- *
- * Thrown instead of quietly degrading. Downgrading replication evidence to a bare ack, or
- * ordered delivery to unordered, produces a system that looks healthy right up to the moment the
- * guarantee actually mattered.
- */
-public class MessagingCapabilityUnavailableException extends MessagingException {
-
- @Serial private static final long serialVersionUID = 1L;
-
- private static final FailureCategory CATEGORY = FailureCategory.CONFIGURATION;
-
- /**
- * Creates the exception with a stable code and sanitized message.
- *
- * @param code the stable failure code
- * @param sanitizedMessage the operator-facing description
- */
- public MessagingCapabilityUnavailableException(String code, String sanitizedMessage) {
- super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty()));
- }
-
- /**
- * Creates the exception with an originating cause.
- *
- * @param code the stable failure code
- * @param sanitizedMessage the operator-facing description
- * @param cause the originating throwable
- */
- public MessagingCapabilityUnavailableException(
- String code, String sanitizedMessage, Throwable cause) {
- super(
- new FailureDescriptor(
- CATEGORY,
- code,
- false,
- sanitizedMessage,
- Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
- cause);
- }
-
- /**
- * Creates the exception from an explicit descriptor.
- *
- * @param failure the sanitized failure description
- */
- public MessagingCapabilityUnavailableException(FailureDescriptor failure) {
- super(failure);
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessagingConfigurationException.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessagingConfigurationException.java
deleted file mode 100644
index c32678d7..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessagingConfigurationException.java
+++ /dev/null
@@ -1,55 +0,0 @@
-package dev.caskeleton.messaging.api.error;
-
-import java.io.Serial;
-import java.util.Optional;
-
-/**
- * The platform or a destination profile is misconfigured.
- *
- * Raised at startup wherever possible. A configuration fault discovered at publish time has
- * already cost a request, so the destination profile validator promotes as many of these as it can
- * to application startup.
- */
-public class MessagingConfigurationException extends MessagingException {
-
- @Serial private static final long serialVersionUID = 1L;
-
- private static final FailureCategory CATEGORY = FailureCategory.CONFIGURATION;
-
- /**
- * Creates the exception with a stable code and sanitized message.
- *
- * @param code the stable failure code
- * @param sanitizedMessage the operator-facing description
- */
- public MessagingConfigurationException(String code, String sanitizedMessage) {
- super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty()));
- }
-
- /**
- * Creates the exception with an originating cause.
- *
- * @param code the stable failure code
- * @param sanitizedMessage the operator-facing description
- * @param cause the originating throwable
- */
- public MessagingConfigurationException(String code, String sanitizedMessage, Throwable cause) {
- super(
- new FailureDescriptor(
- CATEGORY,
- code,
- false,
- sanitizedMessage,
- Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
- cause);
- }
-
- /**
- * Creates the exception from an explicit descriptor.
- *
- * @param failure the sanitized failure description
- */
- public MessagingConfigurationException(FailureDescriptor failure) {
- super(failure);
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessagingException.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessagingException.java
deleted file mode 100644
index 81b648c4..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/MessagingException.java
+++ /dev/null
@@ -1,66 +0,0 @@
-package dev.caskeleton.messaging.api.error;
-
-import java.io.Serial;
-import java.util.Objects;
-
-/**
- * Root of the platform's stable exception hierarchy.
- *
- * Every subclass carries a {@link FailureDescriptor} so that a caller catching the base type can
- * still classify and route the failure without matching on exception classes. The message exposed
- * here is the sanitized one; nothing on this type carries payload or credentials.
- */
-public abstract class MessagingException extends RuntimeException {
-
- @Serial private static final long serialVersionUID = 1L;
-
- private final FailureDescriptor failure;
-
- /**
- * Creates an exception from a descriptor.
- *
- * @param failure the sanitized failure description
- */
- protected MessagingException(FailureDescriptor failure) {
- super(Objects.requireNonNull(failure, "failure must not be null").sanitizedMessage());
- this.failure = failure;
- }
-
- /**
- * Creates an exception from a descriptor and an originating cause.
- *
- * @param failure the sanitized failure description
- * @param cause the originating throwable
- */
- protected MessagingException(FailureDescriptor failure, Throwable cause) {
- super(Objects.requireNonNull(failure, "failure must not be null").sanitizedMessage(), cause);
- this.failure = failure;
- }
-
- /**
- * Returns the sanitized failure description.
- *
- * @return the descriptor
- */
- public FailureDescriptor failure() {
- return failure;
- }
-
- /**
- * Returns the stable classification.
- *
- * @return the failure category
- */
- public FailureCategory category() {
- return failure.category();
- }
-
- /**
- * Reports whether automatic retry is permitted.
- *
- * @return true when retryable
- */
- public boolean retryable() {
- return failure.retryable();
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/header/CanonicalEnvelopeHeaders.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/header/CanonicalEnvelopeHeaders.java
deleted file mode 100644
index 4e955264..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/header/CanonicalEnvelopeHeaders.java
+++ /dev/null
@@ -1,79 +0,0 @@
-package dev.caskeleton.messaging.api.header;
-
-import java.util.Locale;
-import java.util.Set;
-
-/**
- * Splits the reserved namespace into the part an envelope field already owns and the part that only
- * a header can carry.
- *
- * {@link ReservedHeaders} answers one question — does the platform own this name — and every
- * adapter that asked it treated the whole namespace as forgeable content. That is right for {@code
- * msg.id} and wrong for {@code msg.retry-attempt}: the first restates a value the envelope already
- * holds, so a header claiming it can only overwrite the canonical one, while the second has no
- * envelope field at all and exists precisely to survive a hop through a broker. Refusing both is
- * how a retry re-publish becomes an error, and dropping both on the way back is how an attempt
- * counter silently restarts at one and a retry budget stops capping anything.
- *
- * The split is derived from the envelope's own shape rather than listed by hand per adapter, so
- * Kafka and RabbitMQ cannot disagree about which headers are identity and which are bookkeeping — a
- * disagreement that would make the same message mean different things on two brokers.
- */
-public final class CanonicalEnvelopeHeaders {
-
- /**
- * Reserved names that restate a value the envelope already carries in a field.
- *
- * Every one of these is written by the adapter from an envelope field on the way out and read
- * back into that field on the way in. A copy of it inside the header map is therefore never the
- * source of truth, only a way to disagree with it.
- */
- private static final Set Header names are compared case-insensitively because brokers disagree on case handling: AMQP
- * preserves it, HTTP-style bindings fold it. Storing the name verbatim but normalising for lookup
- * keeps a forged {@code MSG.ID} from slipping past the reserved-name check.
- *
- * @param value the header name as written by the caller
- */
-public record HeaderName(String value) {
-
- private static final int MAX_BYTES = 128;
-
- /**
- * The one grammar a header name may use.
- *
- * The previous check was "not blank, at most 128 bytes", which accepted a name containing CR,
- * LF, NUL, a colon or leading whitespace. Those are not cosmetic: a newline in a header name is a
- * header-injection primitive on any line-oriented protocol, a NUL truncates the name in C string
- * handling inside a broker, and a colon is the field separator in several wire formats. A name
- * that survives one broker and corrupts the next is worse than a rejected one.
- *
- * The character set is the HTTP token set, which every broker this platform targets accepts
- * verbatim.
- */
- private static final java.util.regex.Pattern TOKEN =
- java.util.regex.Pattern.compile("[a-zA-Z0-9!#$%&'*+._|~-]+");
-
- public HeaderName {
- if (value == null || value.isBlank()) {
- throw new IllegalArgumentException("header name must not be blank");
- }
- if (!value.equals(value.strip())) {
- // Trimming would mean `Authorization ` and `Authorization` are the same name to the
- // denylist and different names on the wire, which is precisely how the check was bypassed.
- throw new IllegalArgumentException(
- "header name must not have leading or trailing whitespace: '" + value + '\'');
- }
- if (!TOKEN.matcher(value).matches()) {
- throw new IllegalArgumentException(
- "header name must be an ASCII token; control characters, spaces, colons and non-ASCII"
- + " are refused because a broker that accepts one may truncate or split on it");
- }
- int bytes = value.getBytes(StandardCharsets.UTF_8).length;
- if (bytes > MAX_BYTES) {
- throw new IllegalArgumentException("header name exceeds 128 bytes: " + bytes);
- }
- }
-
- /**
- * Returns the lowercase form used for reserved and secret name matching.
- *
- * @return the normalised name
- */
- public String normalized() {
- return value.toLowerCase(java.util.Locale.ROOT);
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/header/HeaderValue.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/header/HeaderValue.java
deleted file mode 100644
index c365fd1d..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/header/HeaderValue.java
+++ /dev/null
@@ -1,26 +0,0 @@
-package dev.caskeleton.messaging.api.header;
-
-import dev.caskeleton.messaging.api.WireSafeText;
-
-/**
- * Value of a single message header.
- *
- * The bound used to be the only rule, so a value containing CR, LF or NUL reached the broker
- * intact. On a line-oriented binding a CRLF inside a value ends the header and starts a new one the
- * caller wrote — the same header-injection primitive as in HTTP, with the broker's own control
- * headers as the target. A NUL truncates the value inside a broker that hands it to C string
- * handling, so a subscriber receives a prefix of what was published and cannot tell.
- *
- * @param value the header value, at most 4096 UTF-8 bytes and free of control characters
- */
-public record HeaderValue(String value) {
-
- private static final int MAX_BYTES = 4096;
-
- public HeaderValue {
- if (value == null) {
- throw new IllegalArgumentException("header value must not be null");
- }
- WireSafeText.require(value, "a header value", MAX_BYTES);
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/header/MessageHeaders.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/header/MessageHeaders.java
deleted file mode 100644
index 21bbc765..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/header/MessageHeaders.java
+++ /dev/null
@@ -1,211 +0,0 @@
-package dev.caskeleton.messaging.api.header;
-
-import java.nio.charset.StandardCharsets;
-import java.util.Collections;
-import java.util.LinkedHashMap;
-import java.util.Locale;
-import java.util.Map;
-import java.util.Optional;
-import java.util.Set;
-
-/**
- * An immutable, bounded header map.
- *
- * Two separate factories exist on purpose. {@link #application(Map)} is what business code calls
- * and it refuses both reserved and secret names; {@link #platform(Map)} is what adapters call when
- * rehydrating an envelope off the wire and it may write reserved names. Secret names are refused in
- * both: a credential that reaches a header ends up in broker storage, DLQ dumps, and operator
- * tooling, and no downstream redaction can undo that.
- */
-public final class MessageHeaders {
-
- private static final int MAX_COUNT = 64;
- private static final int MAX_TOTAL_BYTES = 32_768;
-
- private static final Set Exact-name matching only refuses the spellings someone thought of. {@code x-api-key}, {@code
- * auth-token} and {@code db_password} are the same credential leak as {@code authorization} and
- * none of them was on the list. Matching whole segments rather than substrings is what keeps
- * {@code tokenizer-version} or {@code secretariat-id} from being refused for containing the
- * letters of a secret.
- */
- private static final Set These carry envelope identity, trace propagation, and redrive bookkeeping. Applications cannot
- * write them: if a caller could set {@code msg.id}, the logical identity that Inbox deduplication
- * and DLQ correlation depend on would become caller-controlled.
- */
-public final class ReservedHeaders {
-
- /** Logical message identity. */
- public static final String MESSAGE_ID = "msg.id";
-
- /** Stable catalog message type. */
- public static final String MESSAGE_TYPE = "msg.type";
-
- /** Schema revision of the payload. */
- public static final String SCHEMA_VERSION = "msg.schema-version";
-
- /** Logical producing service. */
- public static final String PRODUCER = "msg.producer";
-
- /** Instant the platform created the envelope. */
- public static final String PRODUCED_AT = "msg.produced-at";
-
- /** Instant the business fact occurred. */
- public static final String OCCURRED_AT = "msg.occurred-at";
-
- /** Workflow correlation value. */
- public static final String CORRELATION_ID = "msg.correlation-id";
-
- /** Identity of the directly causing message. */
- public static final String CAUSATION_ID = "msg.causation-id";
-
- /** Codec content type. */
- public static final String CONTENT_TYPE = "msg.content-type";
-
- /** Distribution key. */
- public static final String PARTITION_KEY = "msg.partition-key";
-
- /** Ordering key. */
- public static final String ORDERING_KEY = "msg.ordering-key";
-
- /**
- * Bounded tenant identity.
- *
- * The envelope carried a tenant and no header name existed for it, so the write side had
- * nothing to write and the read side rebuilt every consumed message with an empty tenant. A
- * message published by one tenant and consumed as belonging to none is not a lost label: it is
- * the field every downstream authorization and data-partitioning decision reads.
- */
- public static final String TENANT = "msg.tenant";
-
- /** Identity of the redrive operation that replayed this message. */
- public static final String REDRIVE_ID = "msg.redrive-id";
-
- /** How many times this message has been redriven. */
- public static final String REDRIVE_COUNT = "msg.redrive-count";
-
- /** Current retry attempt, counting the first delivery as one. */
- public static final String RETRY_ATTEMPT = "msg.retry-attempt";
-
- /** Instant of the first recorded failure. */
- public static final String FIRST_FAILURE_AT = "msg.first-failure-at";
-
- /** Instant of the most recent recorded failure. */
- public static final String LAST_FAILURE_AT = "msg.last-failure-at";
-
- /** Stable failure category recorded when parking or dead lettering. */
- public static final String FAILURE_CATEGORY = "msg.failure-category";
-
- /** Stable failure code recorded when parking or dead lettering. */
- public static final String FAILURE_CODE = "msg.failure-code";
-
- /** Logical destination the message was originally published to. */
- public static final String ORIGIN_DESTINATION = "msg.origin-destination";
-
- /** W3C trace parent. */
- public static final String TRACEPARENT = "traceparent";
-
- /** W3C trace state. */
- public static final String TRACESTATE = "tracestate";
-
- /** W3C baggage. */
- public static final String BAGGAGE = "baggage";
-
- private static final Set The check used to be exact membership of {@link #NAMES}, so {@code msg.anything} that this
- * release has not defined was an ordinary application header — until a later release defined it,
- * at which point every application already writing it silently started overwriting envelope
- * metadata. Owning the prefix means a new platform header is a compatible change.
- */
- private static final String PLATFORM_PREFIX = "msg.";
-
- /**
- * Reports whether a header name belongs to the platform.
- *
- * @param name the header name in any case
- * @return true when the platform owns the name
- */
- public static boolean isReserved(String name) {
- if (name == null) {
- return false;
- }
- String normalized = name.toLowerCase(Locale.ROOT);
- return NAMES.contains(normalized) || normalized.startsWith(PLATFORM_PREFIX);
- }
-
- /**
- * Returns every reserved header name.
- *
- * @return an immutable set of lowercase names
- */
- public static Set Positions exist for diagnostics and replay. Business logic must not branch on them: the whole
- * point of the logical destination model is that a handler behaves identically whether it is
- * reading a Kafka offset or a RabbitMQ delivery tag.
- */
-public interface BrokerPosition {
-
- /**
- * Returns the broker family that produced this position.
- *
- * @return a stable, low-cardinality broker name
- */
- String broker();
-
- /**
- * Returns the position as diagnostic attributes.
- *
- * @return an immutable map safe for structured logs
- */
- Map Kept separate from the requested confirmation requirement so that "we asked for replication
- * and got a leader ack" is representable, and therefore rejectable, instead of being rounded up to
- * success.
- */
-public enum ConfirmationLevel {
-
- /** No confirmation was received. */
- NONE,
-
- /** The broker acknowledged receipt without proving durability. */
- BROKER_ACK,
-
- /** The broker acknowledged replication or persistence. */
- REPLICATION_OR_PERSISTENCE_ACK
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/MessagePublisher.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/MessagePublisher.java
deleted file mode 100644
index 5ffca2a1..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/MessagePublisher.java
+++ /dev/null
@@ -1,26 +0,0 @@
-package dev.caskeleton.messaging.api.publish;
-
-import dev.caskeleton.messaging.api.MessageEnvelope;
-import dev.caskeleton.messaging.api.destination.MessageDestination;
-import java.util.concurrent.CompletionStage;
-
-/**
- * The M1 typed publish entry point used by ordinary business code.
- *
- * The core contract is {@link CompletionStage}. Blocking and Reactor facades live in separate
- * modules so that {@code messaging-core-api} keeps no dependency on either programming model.
- */
-public interface MessagePublisher {
-
- /**
- * Publishes one message.
- *
- * @param Publish is not a boolean. Collapsing "the broker refused this" and "we never learned what the
- * broker did" into one failure is what produces duplicate orders: the first is safe to abandon, the
- * second is not safe to retry with a new identity.
- */
-public enum PublishCompletion {
-
- /** The broker accepted the message at the required confirmation level. */
- CONFIRMED,
-
- /** The message was definitively not accepted. It is safe to abandon this attempt. */
- REJECTED,
-
- /** The outcome is unknown. The broker may or may not hold the message. */
- AMBIGUOUS
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishDeduplication.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishDeduplication.java
deleted file mode 100644
index 2421550d..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishDeduplication.java
+++ /dev/null
@@ -1,27 +0,0 @@
-package dev.caskeleton.messaging.api.publish;
-
-import java.time.Duration;
-import java.util.Objects;
-
-/**
- * Requests broker-side duplicate suppression for a publish.
- *
- * The deduplication key defaults to the logical message id, which is what makes an Outbox relay
- * able to retry an ambiguous publish without creating a second message. Requesting this on a broker
- * without the {@code deduplicatedPublish} capability is a startup failure, not a silent no-op.
- *
- * @param key the stable deduplication key
- * @param window how long the broker should remember the key
- */
-public record PublishDeduplication(String key, Duration window) {
-
- public PublishDeduplication {
- Objects.requireNonNull(window, "deduplication window must not be null");
- if (key == null || key.isBlank()) {
- throw new IllegalArgumentException("deduplication key must not be blank");
- }
- if (window.isNegative() || window.isZero()) {
- throw new IllegalArgumentException("deduplication window must be positive");
- }
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishEvidence.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishEvidence.java
deleted file mode 100644
index 9ad9611a..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishEvidence.java
+++ /dev/null
@@ -1,66 +0,0 @@
-package dev.caskeleton.messaging.api.publish;
-
-import java.util.Objects;
-
-/**
- * The observable facts behind a publish outcome.
- *
- * Evidence is recorded before a completion is chosen, not derived from it. That ordering is what
- * lets an operator answer "could the broker be holding this message?" from a stored result.
- *
- * @param queuedLocally the adapter buffered the message in process
- * @param transmission what is known about bytes reaching the broker
- * @param brokerAccepted the broker positively acknowledged the message
- * @param confirmationLevel the strength of that acknowledgement
- */
-public record PublishEvidence(
- boolean queuedLocally,
- TransmissionEvidence transmission,
- boolean brokerAccepted,
- ConfirmationLevel confirmationLevel) {
-
- public PublishEvidence {
- Objects.requireNonNull(transmission, "transmission must not be null");
- Objects.requireNonNull(confirmationLevel, "confirmationLevel must not be null");
- if (!brokerAccepted && confirmationLevel != ConfirmationLevel.NONE) {
- throw new IllegalArgumentException(
- "confirmation level requires broker acceptance: " + confirmationLevel);
- }
- if (transmission == TransmissionEvidence.NOT_TRANSMITTED && brokerAccepted) {
- throw new IllegalArgumentException("untransmitted message cannot be broker accepted");
- }
- }
-
- /**
- * Returns evidence for a message rejected before anything was sent.
- *
- * @return local rejection evidence
- */
- public static PublishEvidence notTransmitted() {
- return new PublishEvidence(
- false, TransmissionEvidence.NOT_TRANSMITTED, false, ConfirmationLevel.NONE);
- }
-
- /**
- * Returns evidence for a message whose fate is unknown.
- *
- * @return ambiguous evidence
- */
- public static PublishEvidence ambiguous() {
- return new PublishEvidence(
- true, TransmissionEvidence.MAY_HAVE_BEEN_TRANSMITTED, false, ConfirmationLevel.NONE);
- }
-
- /**
- * Returns evidence for a confirmed publish.
- *
- * @param level the confirmation the broker supplied
- * @return confirmed evidence
- */
- public static PublishEvidence confirmed(ConfirmationLevel level) {
- if (level == ConfirmationLevel.NONE) {
- throw new IllegalArgumentException("confirmed evidence requires a confirmation level");
- }
- return new PublishEvidence(true, TransmissionEvidence.TRANSMITTED, true, level);
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishOptions.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishOptions.java
deleted file mode 100644
index f3d07e5c..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/PublishOptions.java
+++ /dev/null
@@ -1,45 +0,0 @@
-package dev.caskeleton.messaging.api.publish;
-
-import dev.caskeleton.messaging.api.destination.ConfirmationRequirement;
-import java.time.Duration;
-import java.util.Objects;
-import java.util.Optional;
-
-/**
- * Per-call publish options.
- *
- * There is no free-form hint map. One existed for a native surface that does not read it, so the
- * only thing a caller could do with it was pass adapter settings that the publish path refused at
- * runtime — an escape hatch around destination policy that never opened. A broker-specific option
- * belongs in that broker's own typed API, where the adapter that honours it can be seen to.
- *
- * @param timeout the publish operation deadline
- * @param confirmation the confirmation this call requires
- * @param deduplication optional broker-side duplicate suppression
- */
-public record PublishOptions(
- Duration timeout,
- ConfirmationRequirement confirmation,
- Optional A batch is a list of independent publishes, not one publish of many payloads, so each entry
- * carries its own destination. Nothing forces the entries of a batch to share a destination; an
- * adapter groups them itself when its wire protocol rewards grouping.
- *
- * @param The constructor refuses every combination that would let a caller read a stronger guarantee
- * than was actually obtained, and every one that contradicts itself: a rejection the broker
- * acknowledged, a confirmation that does not know whether it routed, an ambiguous outcome the
- * broker routed, a broker coordinate for bytes that never left. An adapter that cannot decide must
- * report {@link PublishCompletion#AMBIGUOUS} with no confirmation level, which is the conservative
- * answer, rather than picking a completion that happens to make the call site simpler.
- *
- * Validating here rather than trusting call sites is deliberate: the record is public, every
- * adapter builds one, and a contradiction assembled in an adapter is only ever read much later, by
- * an operator deciding whether to re-publish.
- *
- * @param completion how the attempt ended
- * @param evidence the observable facts behind that outcome
- * @param routingOutcome whether the broker routed the message
- * @param position the broker coordinate when known
- * @param attempts transport attempts made, counting the first as one
- * @param elapsed wall-clock time spent
- * @param failure the sanitized failure when the attempt did not confirm
- */
-public record PublishResult(
- PublishCompletion completion,
- PublishEvidence evidence,
- RoutingOutcome routingOutcome,
- Optional Routing is {@link RoutingOutcome#NOT_APPLICABLE}: nothing reached a broker that could have
- * routed it.
- *
- * @param elapsed wall-clock time spent
- * @param failure why it was refused
- * @return the rejected result
- */
- public static PublishResult rejected(Duration elapsed, FailureDescriptor failure) {
- return new PublishResult(
- PublishCompletion.REJECTED,
- PublishEvidence.notTransmitted(),
- RoutingOutcome.NOT_APPLICABLE,
- Optional.empty(),
- 1,
- elapsed,
- Optional.of(failure));
- }
-
- /**
- * A publish whose fate is unknown: the broker may or may not hold the message.
- *
- * @param elapsed wall-clock time spent
- * @param failure what made the outcome unknowable
- * @return the ambiguous result
- */
- public static PublishResult ambiguous(Duration elapsed, FailureDescriptor failure) {
- return new PublishResult(
- PublishCompletion.AMBIGUOUS,
- PublishEvidence.ambiguous(),
- RoutingOutcome.UNKNOWN,
- Optional.empty(),
- 1,
- elapsed,
- Optional.of(failure));
- }
-
- /**
- * Reports whether the broker may be holding this message.
- *
- * Callers use this to decide between abandoning an attempt and re-publishing under the same
- * logical id.
- *
- * @return true when the outcome is ambiguous
- */
- public boolean mayHaveBeenStored() {
- return completion == PublishCompletion.AMBIGUOUS;
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/RoutingOutcome.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/RoutingOutcome.java
deleted file mode 100644
index 601aef65..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/RoutingOutcome.java
+++ /dev/null
@@ -1,23 +0,0 @@
-package dev.caskeleton.messaging.api.publish;
-
-/**
- * Whether the broker could route the message to a destination.
- *
- * Routing is separate from confirmation because RabbitMQ can confirm a publish the exchange
- * accepted and simultaneously return it as unroutable. Reporting only the confirm would turn a
- * dropped message into a success.
- */
-public enum RoutingOutcome {
-
- /** The broker has no routing stage, as with a Kafka topic publish. */
- NOT_APPLICABLE,
-
- /** The message reached at least one destination. */
- ROUTED,
-
- /** The broker accepted the publish but found no destination. */
- UNROUTABLE,
-
- /** Routing could not be determined. */
- UNKNOWN
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/TransmissionEvidence.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/TransmissionEvidence.java
deleted file mode 100644
index 1bb8434f..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/publish/TransmissionEvidence.java
+++ /dev/null
@@ -1,14 +0,0 @@
-package dev.caskeleton.messaging.api.publish;
-
-/** What the adapter can prove about bytes leaving the process. */
-public enum TransmissionEvidence {
-
- /** Nothing was written to the broker connection. */
- NOT_TRANSMITTED,
-
- /** Bytes may have been written; the connection failed before that could be established. */
- MAY_HAVE_BEEN_TRANSMITTED,
-
- /** Bytes were written to the broker connection. */
- TRANSMITTED
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/settlement/SettlementCompletion.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/settlement/SettlementCompletion.java
deleted file mode 100644
index 2773188e..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/settlement/SettlementCompletion.java
+++ /dev/null
@@ -1,14 +0,0 @@
-package dev.caskeleton.messaging.api.settlement;
-
-/** How a settlement attempt ended. */
-public enum SettlementCompletion {
-
- /** The broker confirmed the settlement. */
- SETTLED,
-
- /** The broker refused the settlement. */
- REJECTED,
-
- /** The settlement outcome is unknown and redelivery remains possible. */
- UNKNOWN
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/settlement/SettlementEvidence.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/settlement/SettlementEvidence.java
deleted file mode 100644
index f6400cc2..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/settlement/SettlementEvidence.java
+++ /dev/null
@@ -1,66 +0,0 @@
-package dev.caskeleton.messaging.api.settlement;
-
-import java.util.Objects;
-
-/**
- * What is known about a settlement reaching the broker.
- *
- * @param transmitted the settlement was written to the broker connection
- * @param brokerConfirmed the broker confirmed the settlement
- * @param redeliveryPossible the message may still be redelivered
- */
-public record SettlementEvidence(
- boolean transmitted, boolean brokerConfirmed, boolean redeliveryPossible) {
-
- public SettlementEvidence {
- if (brokerConfirmed && !transmitted) {
- throw new IllegalArgumentException("an unsent settlement cannot be broker confirmed");
- }
- }
-
- /**
- * Returns evidence for a confirmed settlement.
- *
- * @return confirmed evidence
- */
- public static SettlementEvidence confirmed() {
- return new SettlementEvidence(true, true, false);
- }
-
- /**
- * Returns evidence for a settlement whose fate is unknown.
- *
- * @return unknown evidence
- */
- public static SettlementEvidence unknown() {
- return new SettlementEvidence(true, false, true);
- }
-
- /**
- * Returns evidence for a settlement that never left the process.
- *
- * @return unsent evidence
- */
- public static SettlementEvidence notTransmitted() {
- return new SettlementEvidence(false, false, true);
- }
-
- /**
- * Returns a settlement evidence value, validating the combination.
- *
- * @param object the value to compare
- * @return whether the values are equal
- */
- @Override
- public boolean equals(Object object) {
- return object instanceof SettlementEvidence other
- && transmitted == other.transmitted
- && brokerConfirmed == other.brokerConfirmed
- && redeliveryPossible == other.redeliveryPossible;
- }
-
- @Override
- public int hashCode() {
- return Objects.hash(transmitted, brokerConfirmed, redeliveryPossible);
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/settlement/SettlementResult.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/settlement/SettlementResult.java
deleted file mode 100644
index 9712901d..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/settlement/SettlementResult.java
+++ /dev/null
@@ -1,47 +0,0 @@
-package dev.caskeleton.messaging.api.settlement;
-
-import dev.caskeleton.messaging.api.error.FailureDescriptor;
-import java.util.Objects;
-import java.util.Optional;
-
-/**
- * The outcome of one settlement call.
- *
- * {@link SettlementCompletion#UNKNOWN} means redelivery remains possible and must not be read as
- * success. Treating an unconfirmed acknowledgement as settled is the classic route to a message
- * that looks processed in logs and is processed again minutes later.
- *
- * @param completion how the settlement ended
- * @param evidence what is known about it reaching the broker
- * @param failure the sanitized failure when settlement did not confirm
- */
-public record SettlementResult(
- SettlementCompletion completion,
- SettlementEvidence evidence,
- Optional Every codec here used to serialize into an unbounded buffer and compare {@code bytes.length}
- * to the configured maximum afterwards. That makes the maximum a reporting threshold rather than an
- * allocation bound: a payload whose graph expands to hundreds of megabytes exhausts the heap while
- * being written, and the check that would have rejected it never runs. Under a broker consumer that
- * is a process-wide outage caused by one message.
- *
- * This sink fails on the write that would cross the limit, so peak allocation is bounded by the
- * limit itself plus whatever the encoder buffers. The exception is the same {@link
- * MessageTooLargeException} the after-the-fact check raised, carrying the codec's own error code,
- * so callers and evidence records see no behavioural difference for payloads that merely exceed the
- * bound.
- *
- * Not thread-safe, and not meant to be: an instance belongs to a single encode call.
- */
-public final class BoundedByteSink extends OutputStream {
-
- private final int maxBytes;
- private final String errorCode;
- private final ByteArrayOutputStream buffer;
- private int written;
-
- private BoundedByteSink(int maxBytes, String errorCode) {
- if (maxBytes < 1) {
- throw new IllegalArgumentException("maxBytes must be positive");
- }
- this.maxBytes = maxBytes;
- this.errorCode = Objects.requireNonNull(errorCode, "errorCode must not be null");
- // Sized to the limit only when the limit is small: a 1 GiB bound must not pre-allocate 1 GiB.
- this.buffer = new ByteArrayOutputStream(Math.min(maxBytes, 8_192));
- }
-
- /**
- * Creates a sink that refuses to accumulate more than {@code maxBytes}.
- *
- * @param maxBytes the inclusive byte limit
- * @param errorCode the code the codec reports for an oversized payload
- * @return a bounded sink
- */
- public static BoundedByteSink of(int maxBytes, String errorCode) {
- return new BoundedByteSink(maxBytes, errorCode);
- }
-
- @Override
- public void write(int b) {
- reserve(1);
- buffer.write(b);
- }
-
- @Override
- public void write(byte[] bytes, int offset, int length) {
- Objects.checkFromIndexSize(offset, length, bytes.length);
- reserve(length);
- buffer.write(bytes, offset, length);
- }
-
- /**
- * Checks a size the caller can compute before serializing, without consuming the budget.
- *
- * Protobuf knows its serialized size exactly, so the whole encode can be refused before the
- * first byte is written. The subsequent writes are still bounded — this is a cheaper refusal, not
- * a replacement for the bound.
- *
- * @param size the number of bytes the caller is about to produce
- */
- public void requireFits(int size) {
- if (size < 0) {
- throw new IllegalArgumentException("size must not be negative");
- }
- refuseIfBeyondLimit(size);
- }
-
- private void reserve(int size) {
- refuseIfBeyondLimit(size);
- written += size;
- }
-
- private void refuseIfBeyondLimit(int size) {
- if (size > maxBytes - written) {
- throw new MessageTooLargeException(
- errorCode,
- ("the encoded payload exceeds the %d byte limit; it was refused at byte %d rather than"
- + " buffered in full")
- .formatted(maxBytes, written + size));
- }
- }
-
- /**
- * The bytes accumulated so far.
- *
- * @return a copy of the buffered bytes
- */
- public byte[] toByteArray() {
- return buffer.toByteArray();
- }
-
- /**
- * How many bytes have been admitted.
- *
- * @return the running total
- */
- public int written() {
- return written;
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/EncodedMessage.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/EncodedMessage.java
deleted file mode 100644
index 51f5e422..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/EncodedMessage.java
+++ /dev/null
@@ -1,66 +0,0 @@
-package dev.caskeleton.messaging.schema;
-
-import dev.caskeleton.messaging.api.ContentType;
-import java.util.Arrays;
-import java.util.Objects;
-import java.util.Optional;
-
-/**
- * An encoded payload together with the facts needed to decode it again.
- *
- * The byte array is defensively copied on both construction and access. These bytes travel
- * through retry, DLQ, and redrive paths where a shared mutable array would let one stage corrupt
- * another's copy of the same logical message.
- *
- * @param bytes the encoded payload
- * @param contentType the codec media type
- * @param schemaReference the schema the payload was written against
- */
-@SuppressWarnings("ArrayRecordComponent")
-public record EncodedMessage(
- byte[] bytes, ContentType contentType, Optional This is intentionally narrower than the transport SPI. Callers may skip only the codec step;
- * destination resolution, access policy, admission, runtime leasing, transport normalization and
- * observation remain owned by the platform's central publisher.
- */
-@FunctionalInterface
-public interface EncodedMessagePublisher {
-
- CompletionStage Implementations operate against a closed message-type registry. Accepting an unregistered type
- * would let a producer introduce a wire contract nothing has reviewed, which is the same class of
- * problem that makes Java serialization unsupported here.
- */
-public interface MessageCodec {
-
- /**
- * Returns the media type this codec produces.
- *
- * @return the content type
- */
- ContentType contentType();
-
- /**
- * Encodes a payload.
- *
- * @param type the catalog message type
- * @param version the schema revision
- * @param payload the payload to encode
- * @return the encoded message
- */
- EncodedMessage encode(MessageType type, SchemaVersion version, Object payload);
-
- /**
- * Decodes a payload from raw bytes.
- *
- * @param The raw bytes codec is never eligible: selecting it by default would silently disable schema
- * validation for every destination that forgot to declare one.
- *
- * @return the default codec
- */
- MessageCodec defaultCodec();
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/MessageContractKey.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/MessageContractKey.java
deleted file mode 100644
index 2605a488..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/MessageContractKey.java
+++ /dev/null
@@ -1,49 +0,0 @@
-package dev.caskeleton.messaging.schema;
-
-import dev.caskeleton.messaging.api.MessageType;
-import dev.caskeleton.messaging.api.SchemaVersion;
-import java.util.Objects;
-
-/**
- * The identity a codec registry is keyed on: a message type at a specific schema version.
- *
- * Keying on the message type alone is what let an unregistered version decode. The version
- * travels in the envelope and in {@link SchemaReference}, so a consumer receiving {@code
- * order.created v999} would look up {@code order.created}, find the v1 class or parser, decode
- * against it, and then keep the v999 label on the result. Nothing failed, and every downstream
- * compatibility gate and audit record then described a version that was never registered.
- *
- * With the version in the key that lookup misses, which is the only honest outcome: the platform
- * has no contract for that version and must say so rather than guess one.
- *
- * @param type the catalog message type
- * @param version the schema version the contract is registered for
- */
-public record MessageContractKey(MessageType type, SchemaVersion version) {
-
- /** Validates both components. */
- public MessageContractKey {
- Objects.requireNonNull(type, "messageType must not be null");
- Objects.requireNonNull(version, "schemaVersion must not be null");
- }
-
- /**
- * Creates a key from raw components.
- *
- * @param type the catalog message type
- * @param version the schema version
- * @return the key
- */
- public static MessageContractKey of(String type, int version) {
- return new MessageContractKey(new MessageType(type), new SchemaVersion(version));
- }
-
- /**
- * Renders the key the way error messages and audit records name a contract.
- *
- * @return for example {@code order.created v1}
- */
- public String describe() {
- return type.value() + " v" + version.value();
- }
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/RawBytesMessageCodec.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/RawBytesMessageCodec.java
deleted file mode 100644
index 30079ec5..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/RawBytesMessageCodec.java
+++ /dev/null
@@ -1,76 +0,0 @@
-package dev.caskeleton.messaging.schema;
-
-import dev.caskeleton.messaging.api.ContentType;
-import dev.caskeleton.messaging.api.MessageType;
-import dev.caskeleton.messaging.api.SchemaVersion;
-import dev.caskeleton.messaging.api.error.MessageSerializationException;
-import dev.caskeleton.messaging.api.error.MessageTooLargeException;
-import java.util.Objects;
-import java.util.Optional;
-
-/**
- * The M2 escape hatch for payloads that carry no schema.
- *
- * It still enforces the byte limit, and it is deliberately excluded from default codec
- * selection: schema-free publishing has to be an explicit, auditable choice per destination, never
- * something a destination falls back to because its codec was misconfigured.
- */
-public final class RawBytesMessageCodec implements MessageCodec {
-
- /** The default encoded byte limit shared with the Stable codecs. */
- public static final int DEFAULT_MAX_BYTES = 1_048_576;
-
- private final int maxBytes;
-
- /** Creates a codec with the default one mebibyte limit. */
- public RawBytesMessageCodec() {
- this(DEFAULT_MAX_BYTES);
- }
-
- /**
- * Creates a codec with an explicit byte limit.
- *
- * @param maxBytes the maximum encoded size
- */
- public RawBytesMessageCodec(int maxBytes) {
- if (maxBytes < 1) {
- throw new IllegalArgumentException("maxBytes must be positive");
- }
- this.maxBytes = maxBytes;
- }
-
- @Override
- public ContentType contentType() {
- return ContentType.OCTET_STREAM;
- }
-
- @Override
- public EncodedMessage encode(MessageType type, SchemaVersion version, Object payload) {
- Objects.requireNonNull(type, "messageType must not be null");
- Objects.requireNonNull(version, "schemaVersion must not be null");
- if (!(payload instanceof byte[] bytes)) {
- throw new MessageSerializationException(
- "RAW_BYTES_PAYLOAD_REQUIRED", "raw bytes codec accepts only byte[] payloads");
- }
- if (bytes.length > maxBytes) {
- throw new MessageTooLargeException(
- "RAW_BYTES_TOO_LARGE", "encoded payload exceeds " + maxBytes + " bytes");
- }
- return new EncodedMessage(bytes, ContentType.OCTET_STREAM, Optional.empty());
- }
-
- @Override
- public Transitive modes check every historical version, not just the immediate predecessor. That
- * matters for integration events, where a consumer may be several releases behind and a chain of
- * individually-compatible changes can still be collectively breaking.
- */
-public enum SchemaCompatibility {
-
- /** A new schema can read data written by the previous schema. */
- BACKWARD,
-
- /** A new schema can read data written by every previous schema. */
- BACKWARD_TRANSITIVE,
-
- /** The previous schema can read data written by the new schema. */
- FORWARD,
-
- /** Every previous schema can read data written by the new schema. */
- FORWARD_TRANSITIVE,
-
- /** Both directions hold against the previous schema. */
- FULL,
-
- /** Both directions hold against every previous schema. */
- FULL_TRANSITIVE,
-
- /** No compatibility is enforced; permitted only for M2 raw bytes. */
- NONE_EXPERIMENTAL
-}
diff --git a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/SchemaCompatibilityValidator.java b/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/SchemaCompatibilityValidator.java
deleted file mode 100644
index 3fa0c5ed..00000000
--- a/src/platforms/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/schema/SchemaCompatibilityValidator.java
+++ /dev/null
@@ -1,113 +0,0 @@
-package dev.caskeleton.messaging.schema;
-
-import dev.caskeleton.messaging.api.SchemaVersion;
-import dev.caskeleton.messaging.api.error.MessageSchemaIncompatibleException;
-import java.util.List;
-import java.util.Objects;
-
-/**
- * The format-independent half of schema evolution: which versions have to be compared, and whether
- * a mode is even allowed on a production destination.
- *
- * Split from the per-format gates on purpose. Whether v3 must be checked against v1 as well as
- * v2 is a property of the compatibility mode, not of Avro or Protobuf, and duplicating that
- * reasoning in each codec is how the two formats drift apart.
- *
- * {@link SchemaCompatibility#NONE_EXPERIMENTAL} is refused for production destinations. A mode
- * that checks nothing is useful while a message type is being designed and actively dangerous once
- * a retained log exists, because the log outlives every consumer that could still read it.
- */
-public final class SchemaCompatibilityValidator {
-
- private final SchemaRegistry registry;
-
- /**
- * Creates a validator over a registry.
- *
- * @param registry the schema source
- */
- public SchemaCompatibilityValidator(SchemaRegistry registry) {
- this.registry = Objects.requireNonNull(registry, "registry must not be null");
- }
-
- /**
- * Returns the versions a candidate must be checked against, newest first.
- *
- * Transitive modes return the whole history; pairwise modes return only the immediate
- * predecessor; {@link SchemaCompatibility#NONE_EXPERIMENTAL} returns nothing.
- *
- * @param subject the registry subject
- * @return the versions to compare against
- */
- public List Carried alongside the bytes rather than inferred from the message type, because a consumer
- * that guesses the schema from the type is exactly the consumer that breaks when a producer rolls
- * forward.
- *
- * @param subject the registry subject or schema name
- * @param version the schema revision
- * @param schemaUri the resolvable schema location, when one exists
- */
-public record SchemaReference(String subject, SchemaVersion version, Optional Deliberately a port. A hosted registry, a classpath directory of schema files, and a static
- * in-process map are all legitimate sources depending on the deployment, and the platform's
- * compatibility rules must hold identically across all three. Binding to a vendor client here would
- * make the rules untestable without that vendor running.
- *
- * {@link #history} returns oldest first. Transitive compatibility checks read the whole list, so
- * an ordering mistake here silently converts a transitive check into a pairwise one.
- */
-public interface SchemaRegistry {
-
- /**
- * Resolves one schema definition.
- *
- * @param subject the registry subject
- * @param version the schema revision
- * @return the schema text, or empty when the subject or version is unknown
- */
- Optional
- *
- *
- * > manifests;
- private final ReplayEstimator replayEstimator;
- private final RedriveEstimator redriveEstimator;
- private final Supplier
> manifests,
- ReplayEstimator replayEstimator,
- RedriveEstimator redriveEstimator,
- Supplier