# messaging — local authority for the messaging platform family 이 문서는 messaging family의 **local authority**다. leaf 목록·gradle path·허용 의존성은 `src/config/architecture/modules.json`이 SSOT이며 이 문서는 그것을 복제하지 않는다. 여기서 정하는 것은 registry가 표현할 수 없는 것들이다: family별 framework 규칙, public surface 정책, Stable 승격에 필요한 증거, runtime membership이 비어 있다는 사실의 의미. Root 정책(`CLAUDE.md` / `AGENTS.md`)과 충돌하면 root가 이긴다. ## Family와 framework 규칙 leaf의 정확한 id는 registry에서 읽는다. family는 **디렉터리 이름의 접두사**가 아니라 아래 표의 역할로 정해진다. | Family | 역할 | 허용 framework | | --- | --- | --- | | `*-api` (`core-api`, `schema-api`, `policy`, `reliability-api`, `admin-api`, `transport-spi`) | 값 타입, 포트, 정책 계약 | Java stdlib만. Spring/broker SDK/logging framework 금지 | | `schema-*` (json/avro/protobuf), `cloudevents` | 인코딩 구현 | 해당 codec 라이브러리만. Spring 금지 | | `runtime-core`, `security`, `observability`, `admin-runtime` | framework-free 실행 로직 | Micrometer는 `observability`에서만. 나머지는 stdlib | | `kafka`, `rabbit`, `pulsar-experimental`, `nats-experimental`, `kafka-share-experimental` | broker adapter | 해당 broker client. Spring은 `rabbit`의 `spring-rabbit`처럼 client가 곧 Spring인 경우만 | | `outbox-jdbc-postgresql`, `inbox-jdbc-postgresql` | 관계형 신뢰성 adapter | Spring JDBC / Spring TX. **JPA 아님** — 이름이 곧 계약이다 | | `spring-boot-starter`, `spring-cloud-stream-bridge` | 조립 경계 | Spring Boot autoconfigure. 여기서만 | | `testkit` | 테스트 지원 | Testcontainers, JUnit. production leaf가 의존하지 않는다 | `outbox`/`inbox` leaf가 `jdbc-postgresql`로 명명된 이유: 구현은 Spring JDBC이고 SQL은 `?::jsonb` · `FOR UPDATE SKIP LOCKED` · `ON CONFLICT` · `TIMESTAMPTZ`로 PostgreSQL 전용이다. `jpa`라는 이름은 사용하지 않는 기술을 광고하고, vendor 중립 port가 어디 있는지도 숨겼다. vendor 중립 계약은 `messaging-reliability-api`에 있다. ## Public surface 정책 - **vendor 타입을 public signature에 노출하면 그 의존성은 `api`로 선언한다.** 숨긴다고 타입이 숨겨지지 않는다 — consumer가 이 모듈이 문서화한 API에 대해 컴파일하지 못하게 만들 뿐이다. (`kafka-clients`, `spring-rabbit`, `cloudevents-api`, `micrometer-core`, `avro`, `protobuf-java`, `reactor-core`가 이 규칙으로 `api`다.) - 반대로 **노출하지 않는 것은 `implementation`으로 낮춘다.** starter가 노출하지 않는 하위 모듈을 `implementation`으로 내린 것이, JSON codec이 `ObjectMapper`를 private으로만 쓰고 Jackson을 `implementation`으로 둔 것이 그 예다. - 이 규칙은 문서가 아니라 `MessagingPublicSurfaceContractTest`가 붙들고 있다. leaf의 production source에서 public/protected 시그니처에 등장하는 vendor 라이브러리를 뽑아 그 leaf의 `build.gradle`이 `api`로 선언했는지 대조하고, starter의 `api` closure에 broker client 두 개가 들어오지 않는 것도 함께 본다. Spring Framework/Boot는 대상이 아니다 — 조립 경계 안에서만 등장하고 adopter가 이름 부를 일이 없다. - 새 public 타입은 그 모듈의 계약이다. 삭제·시그니처 변경은 breaking change로 취급한다. ## Application runtime에 포함되는 기준 Messaging family는 기본 application이 `messaging-spring-boot-starter`를 dependency로 가지므로 그 transitive project graph가 runtime에 포함된다. 이 사실의 SSOT는 Gradle `runtimeClasspath`이며 registry에 동일한 membership 목록을 복제하지 않는다. `app.messaging.enabled=false`가 기본값이고 master switch가 activation을 결정한다. experimental transport, 일부 codec/bridge/testkit처럼 starter graph에 들어오지 않는 leaf는 build-only다. 새 leaf를 application에 채택할 때는 starter 또는 composition dependency와 architecture edge policy, qualification/support 상태를 함께 변경한다. ## application이 이 family에 도달하는 경로 (MSG-015, canonical bridge 구현 / legacy cutover 잔존) 리뷰(`docs/reviews/2026-08-14-messaging-module-code-review.md` §6.1·§6.3)가 정한 `application-owned port → platform anti-corruption bridge → platform` 경로는 이제 존재한다. - application-owned port: `IntegrationEventPublishPort` - bridge: `adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapter` - platform boundary: `EncodedMessagePublisher` - central implementation: `DefaultMessagePublisher` bridge는 exact canonical envelope bytes를 다시 serialize하지 않고, destination/access/admission/runtime lease/transport/outcome normalization/observation은 platform 중앙 publish path를 그대로 탄다. bridge package는 `messaging-core-api`와 `messaging-schema-api`만 보며 concrete runtime/transport/Kafka 타입을 직접 보지 않는다. 다만 **MSG-015의 전체 cutover가 끝난 것은 아니다.** legacy `OutboxEvent`와 realtime publisher는 schema/order/tenant 등 canonical metadata가 부족해 아직 `MessageBroker → KafkaSender` R0 경로를 사용한다. 그 metadata를 추측해 platform envelope를 만드는 것은 금지한다. 따라서 legacy outbox storage/relay migration을 별도 change set으로 완료한 뒤에만 R0 seam을 제거한다. canonical bridge의 producer identity는 `app.messaging.producer-id`로 명시한다. 값이 없으면 bridge bean을 만들지 않으며 `spring.application.name`/host/pod 이름에서 identity를 발명하지 않는다. `ca-skeleton.outbox.canonical-transport-enabled=true`는 bridge 존재만으로 충분하지 않다. Stable composition은 애플리케이션 계약 catalog/schema source를 임의로 만들지 않으므로 adopter가 `IntegrationEventEncoderPort`를 명시적으로 제공해야 한다. 저장소의 후보 구현은 `JsonSchemaIntegrationEventEncoder`이지만 이를 사용하려면 compiled contract descriptor, `LocalJsonSchemaRegistry`, payload/envelope limits와 key material에 해당하는 application-owned 입력을 같이 조립해야 한다. `OutboxCanonicalTransportRequirementValidator`는 publisher 또는 encoder 중 하나라도 없으면 startup을 거부한다. 즉 canonical flag가 켜졌는데 정본 encoder가 없는 상태로 성공 기동하는 경로는 없다. ## Stable 승격에 필요한 증거 adapter를 Experimental → Stable로 올릴 때 필요한 것 (`docs/messaging/support-matrix.md`가 현재 상태를 기록한다): 1. 실제 broker container를 쓰는 fault 시나리오 lane이 존재하고, 그 lane이 `BrokerCertificationEvidence`를 산출한다. 2. `NetworkFaultScenario` 전 항목에 대해 evidence가 있거나, 없는 항목이 `knownGaps`로 명시된다. 3. capability 선언이 코드에서 파생된다 — `MessagingCapabilities`에 손으로 `true`를 쓰는 것은 증거가 아니다. 4. publish 실패 분류가 typed signal에서만 나온다. exception class 이름 substring 판정은 Experimental에서도 금지다(MSG-022). 5. unknown failure의 기본값이 `AMBIGUOUS`다. `REJECTED`는 전송이 시작되지 않았다는 typed 증거가 있을 때만. Stable 문구는 evidence manifest가 존재할 때만 문서에 쓴다. 증거를 만드는 것은 인증 레인이고, manifest는 그 실행의 출력이다: ```bash ./gradlew :messaging:messaging-kafka:verifyMessagingCertificationEvidence --console=plain ``` 레인(`messagingCertificationTest`)은 Toxiproxy를 broker 앞에 두고 장애를 주입하며, 통과한 시나리오마다 `BrokerCertificationEvidence` 한 줄을 `messaging-testkit/src/main/resources/messaging/broker-certification-evidence.jsonl`에 쓴다. 게이트는 커밋된 manifest와 이번 실행의 출력을 대조한다 — **manifest를 손으로 고치면 실패하고, 레인을 돌리면 manifest가 다시 쓰인다.** 이 레인만은 Docker 가드를 달지 않는다(없으면 실패한다). skip하는 인증 레인은 아무도 켜지 않은 브로커에 대해 성공을 보고하기 때문이며, 그래서 `test`에서는 `messaging-certification` 태그로 제외된다. ## Focused test leaf의 `gradle_path`를 registry에서 읽어 파생한다. ```bash cd src ./gradlew :test --console=plain ``` Family 전체 검증: ```bash ./gradlew verifyCleanArchitectureDependencies --console=plain ./gradlew architectureCheck --console=plain ./gradlew verifyDependencyLocks --console=plain ```