Files
clean-architecture-backend-…/docs/notification/support-matrix.md
T
DongHyeonkaandClaude Opus 5.5 6d27356e2b refactor: 부가 기능을 capability 모듈로 포장하고 기본 조립을 web-only로 전환
설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md

- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
  (compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
  messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
  outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
  Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
  qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용

삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(208077fd)과 함께 기록.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-25 12:49:07 +09:00

6.0 KiB

Notification support matrix

What each channel can actually prove, and what the platform refuses to claim.

The grade column is not an opinion. docs/notification/evidence-manifest.json declares which claims each grade requires and which executable artifact proves each claim, and NotificationEvidenceVerifierTest (in :adapter:outbound:notification:test) refuses a grade whose claims are not all backed by a file that exists. Raising a grade means adding the artifact first.

Five channels read Stable until 2026-08-15. Nothing in the pipeline had ever sent a request to a provider — the sandbox job's whole body was two echo statements behind continue-on-error — and no test killed a worker mid-dispatch. The protocols are implemented and their contracts are proven against real PostgreSQL; the wire and the crash are not. That is what the grade now says.

Channels

Channel Reference implementation Grade Strongest evidence the platform records by default
Email SMTP, Amazon SES API Contract implemented / runtime unqualified Provider acceptance; recipient mail-server delivery, bounce and complaint when the provider publishes events
SMS Twilio Programmable Messaging Contract implemented / runtime unqualified accepted/queued, sent, and carrier-DLR delivered/undelivered
Mobile push (Android and cross-platform) FCM, FID-first with legacy registration token compatibility Contract implemented / runtime unqualified FCM acceptance and explicit failures
Mobile push (Apple) APNs HTTP/2 provider API Contract implemented / runtime unqualified APNs acceptance
Web Push RFC 8030, RFC 8291, RFC 8292 Contract implemented / runtime unqualified Push-service acceptance; user-agent acknowledgement only where the service offers receipts
In-app inbox Own database Optional stable PERSISTED, SEEN, READ
Webhook HTTP client platform Extension Whatever the receiving HTTP contract states

Shipped provider assembly reachability

The grade above describes protocol/reliability evidence. It does not mean every reference implementation is selectable in the default composition. Dispatch reachability is a separate axis:

Provider family Dispatch assembler in shipped composition Callback assembler Current use
SMTP yes no EMAIL dispatch reference family
SES yes yes EMAIL dispatch + SNS callback ingestion; disabled reference profile ships in config/module-defaults/notification.yml (composition:notification-platform)
Twilio no no contract implementation / extension wiring
FCM no no contract implementation / extension wiring
APNs no no contract implementation / extension wiring
Web Push no no contract implementation / extension wiring
Webhook no no extension wiring

An enabled dispatch profile with no assembler fails startup by profile/family; it never silently assembles into an empty runtime. SMTP additionally names spring.mail.host when its shipped assembler is absent because the relay was not configured.

What each grade requires

Grade Requires
Stable durable, multi-worker-safe, callback-supported, recoverable, provider-wire-qualified
Contract implemented / runtime unqualified durable, multi-worker-safe, callback-supported
Optional stable durable
Extension nothing; the receiving contract owns its own guarantees
Experimental nothing; the grade is the warning

recoverable was met on 2026-08-15 by WorkerCrashRecoveryContractTest, which walks the four phases a dispatch passes through — claimed, attempt written, request started, body committed — and asserts for each that the delivery becomes claimable again or becomes a question for the provider, never both and never neither.

The remaining unmet claim, and what would meet it:

  • provider-wire-qualified — a real provider sandbox call producing an immutable, uploaded artifact with a correlation id. No request has ever left the process in CI.

Evidence levels

NONE → PLATFORM_QUEUED → PROVIDER_ACCEPTED → NETWORK_OR_CARRIER_ACCEPTED → DEVICE_DELIVERED → USER_AGENT_DISPLAYED → USER_READ

Provider signal Highest evidence it may produce
Internal queue commit PLATFORM_QUEUED
SES MessageId PROVIDER_ACCEPTED
SES Delivery NETWORK_OR_CARRIER_ACCEPTED
Twilio accepted / queued PROVIDER_ACCEPTED
Twilio sent NETWORK_OR_CARRIER_ACCEPTED
Twilio delivered DEVICE_DELIVERED
FCM send success PROVIDER_ACCEPTED
APNs 2xx PROVIDER_ACCEPTED
Web Push 201 PROVIDER_ACCEPTED
Web Push receipt capability DEVICE_DELIVERED
In-app row commit PROVIDER_ACCEPTED
In-app seen endpoint USER_AGENT_DISPLAYED
In-app read endpoint, authenticated app receipt USER_READ

Promotions the platform will not make, in code or in configuration:

  • FCM send success is not DEVICE_DELIVERED.
  • An APNs 2xx is not DELIVERED.
  • An SES MessageId is not DELIVERED.
  • An SMTP 250 is not inbox delivery.

Submission outcomes

NOT_SUBMITTED, CONFIRMED_ACCEPTED, CONFIRMED_REJECTED, AMBIGUOUS.

AMBIGUOUS is a first-class stored state, not an error path. It means the request body was committed to the provider and the outcome could not be read. While an ambiguous attempt exists on a recipient delivery, automatic retry and automatic cross-channel fallback are both blocked.

Not supported

The platform will not claim any of the following, because no channel above can support them:

  • guaranteed delivery
  • guaranteed read
  • exactly-once human notification
  • unconditional multi-provider failover after an unread response
  • provider SDK types in the public API
  • audience selection, campaign segmentation or jurisdiction rulings

Target model

FCM_FID is the primary mobile push target. FCM_REGISTRATION_TOKEN_LEGACY and APNS_DEVICE_TOKEN are separate types with separate lifecycles; they are never flattened into one string field.