Files
clean-architecture-backend-…/docs/notification/adr/NOTIF-ADR-005-canonical-namespace.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

4.3 KiB

NOTIF-ADR-005 — 어느 notification API가 canonical인가

상태

Accepted (2026-08-15). NTF-018 대응.

갱신 (2026-09-25): R1 type은 삭제됐다. production consumer가 끝까지 0건이었고 fake로만 증명된 계약이라, 새 consumer를 막는 ArchUnit 규칙을 유지할 이유가 없어졌다. 남은 것은 adapter core의 RoutingNotifier가 구현하는 단순 알림 포트 3개(NotificationPort, Notification, NotificationChannel)뿐이다. 그래서 아래 「강제」의 NOTIFICATION_R1_AND_PLATFORM_DO_NOT_DEPEND_ON_EACH_OTHER 규칙과 compatibility.r1 예외 패키지도 함께 없어졌다. 삭제 목록과 마지막 커밋은 docs/capability-status.md의 「제거된 코드」 표에 있다. 아래 본문은 결정 당시 기록이다.

문제

같은 저장소에 notification 모델이 두 개 있다.

세대 위치 규모
R0 legacy adapter:outbound:notification의 router/provider seam 삭제 예정
R1 dev.caskeleton.application.notification (직속) public type 100개
Platform dev.caskeleton.application.notification.platform.. 신규

application-core/CLAUDE.md는 R1을 "R1 canonical"이라 부르고, docs/notification/migration-guide.md는 R0 → platform 이행만 설명하며 R1의 처분을 전혀 다루지 않는다. Channel, plan, dispatch, receipt/evidence 모델이 두 namespace에 중복 존재하고 둘 사이에 production bridge도 import도 없다.

실패 모드는 "무엇이 깨지는가"가 아니라 "무엇을 써야 하는가"다. 새 consumer가 어느 API를 쓸지 알 수 없고, 두 모델이 각자 진화하며, R0를 지운 뒤에도 R1 graph가 고아로 남거나 platform이 R1 정책을 우회하는 이중 canonical이 된다.

결정

Platform이 canonical이다. R1은 유지되지만 새 production consumer를 받지 않는다.

이유는 능력이 아니라 증거다. platform은 durable acceptance, fenced claim, event ledger, projection, reconciliation을 실제 PostgreSQL 레인으로 증명한다(NOTIF-ADR-001~003). R1은 fake로 증명된 R1 계약이며 스스로 그렇게 선언한다 — application-core/CLAUDE.md가 "R1 application contract proven with fakes. It does not claim PostgreSQL schema/locking, provider protocol, cryptographic verifier, or runtime wiring qualification"이라고 적어 둔 그대로다.

Disposition

R1 public type 100개의 처분은 네 가지 중 하나다.

처분 의미 대상
replace platform에 동등물이 있다. 새 consumer는 platform을 쓴다 Channel, plan/dispatch/receipt/evidence 계열
bridge 변환이 필요하다. 변환은 ACL 한 곳에만 둔다 writer-cutover / receipt 적용 경로
retain platform이 다루지 않는 관심사다. 그대로 둔다 consent/quiescence verifier port
delete R0와 함께 사라진다 R0 router가 쓰던 seam

전수 분류표는 이 ADR이 아니라 docs/notification/module-mapping.md가 소유한다. ADR은 규칙을, mapping 문서는 목록을 소유한다 — 목록을 두 곳에 복제하면 드리프트하는 쪽이 늘어난다.

강제

두 namespace 사이의 production dependency는 0건이며, 이것은 문서가 아니라 ArchUnit 규칙이 지킨다 (ApplicationBoundaryArchitectureTest의 NOTIFICATION_R1_AND_PLATFORM_DO_NOT_DEPEND_ON_EACH_OTHER).

변환이 필요해지면 dev.caskeleton.application.notification.compatibility.r1 한 패키지에만 두고, 그 패키지만 규칙에서 예외로 인정한다. 예외를 한 곳으로 모으는 것이 목적이다 — 두 모델이 서로를 아는 지점이 여러 곳이면 "어느 쪽이 canonical인가"라는 질문에 코드가 답하지 못한다.

결과

  • 새 production consumer는 ..notification.platform..만 쓴다.
  • R1 type은 남지만, 새 코드가 그것을 import하면 ArchUnit이 막는다.
  • R0 삭제는 이 ADR과 무관하게 진행된다. R1은 R0와 함께 사라지지 않는다.

하지 않은 것

R1 100개 type에 @Deprecated(forRemoval = true)를 붙이지 않았다. 제거 시점이 정해지지 않았고, forRemoval은 "이 릴리스 이후 사라진다"는 약속이라 시점 없이 붙이면 그 자체가 거짓 신호다. 경계는 ArchUnit이 강제하고, deprecation은 제거 계획이 생길 때 붙인다.