fix(objectstorage): 포트 계약 시험을 두고 그 시험이 찾은 결함을 고친다 #35

Merged
donghyeon.kang merged 7 commits from claude/r9-objstore-contract into main 2026-11-13 09:42:53 +00:00
Owner

무엇을, 왜

round9 리뷰가 고치며 찾은 RR9-03-31을 고친다. capability 기준 5(docs/manual/10-capabilities.md)는 포트를 가진 모듈의 testFixtures에 포트 계약(추상 클래스)을 두고 fake와 실제 adapter가 모두 통과하게 한다. application-objectstorage에는 testFixtures도 fake도 없었고, 포트 인터페이스는 결과와 예외를 적지 않았다.

  • 포트 계약 셋과 fake(application-objectstorage testFixtures testkit): ManagedObjectStoragePortContract(관리 게시·조회·전송·복구 조회·회수), StagedObjectPublicationPortContract(stage·검증·handoff·finalize·중단), ObjectScanMaintenancePortContract(scan gate), InMemoryObjectStorage(포트 여덟). fake(이 leaf test)와 adapter routing 구현(local-dev provider, adapter test의 contract/LocalDev*)이 같은 계약을 상속한다.
  • 포트 Javadoc: 포트 여덟에 결과(APPLIED·REPLAYED·REJECTED 등)와 예외를 적었다. 계약은 그 선언만 단언한다.
  • 계약이 찾은 운영 결함 둘:
    • 불변 Set(Set.of)으로 만든 게시·stage 요청이 ObjectRequestSupport의 contains(null)에서 NPE를 냈다(RR9-03-33).
    • 실패한 managed 게시를 다시 하면 이번 호출이 게시했는데도 REPLAYED였다(stage 재시도는 APPLIED). 이제 PUBLISHED로 바꾼 호출 하나만 APPLIED다. 같은 key로 겹친 호출은 REPLAYED다(ManagedPublicationOutcomeTest가 겹침을 결정적으로 재현한다, RR9-03-35).
    • 검증한 뒤 중단한 stage를 다시 검증하면 REPLAYED였다. 중단된 operation의 검증을 거절한다.
  • 리뷰가 찾은 게이트 구멍: 순수성 검사가 순수 모듈의 testFixturesCompileOnly를 보지 않았다(RR9-04-47). testFixtures classpath도 같은 금지 group으로 본다.
  • 문서: .claude/rules/java-tests.md 규칙 5(공유 계약은 포트가 선언한 것만 단언), application-objectstorage AGENTS·README, adapter README 「포트 계약」, docs/testing/TESTING_STRATEGY.md 9.4, docs/capability-status.md Object storage 증거 칸(「app-bootstrap 통합 시험이 MinIO로 조립」 → 실제는 local-dev, RR9-04-46).

고른 방법과 버린 대안

  • 포트 예외는 지금 adapter 동작(IllegalArgumentException=요청 그대로 거절, IllegalStateException=지금 상태에서 거절)의 타입을 선언하는 안을 골랐다. 메시지는 구현의 것이라 계약이 단언하지 않는다. 시험 리뷰는 메시지 단언을, 구조 리뷰는 adapter 문구가 application 계약에 새는 것을 지적했다. 이 둘이 부딪쳐 아키텍처 규칙(포트는 저장소와 상관없는 말로 쓴다)을 앞에 뒀다. 타입 있는 결과로 바꾸는 안은 공개 API를 바꾸는 일이라 버렸다. 유스케이스가 감싸 기능 오류(상태 충돌이면 CONFLICT carrier)로 바꾸라고 AGENTS에 적었다. 리뷰 기록 6절 ⑨로 남긴다.
  • MinIO에서 포트 계약을 돌리는 안은 이번에 하지 않았다. S3 provider는 readiness registry(docs/registries/object-storage-readiness.yaml)에서 아직 배포 대상이 아니다. 포트 경로를 MinIO로 묶는 일은 S3를 배포 대상으로 올릴 때 같이 한다. MinIO에서는 지금처럼 provider 계약이 돈다(기준 5의 「실제 벤더 시험 1개 이상」).
  • fake는 이 저장소 안에 소비자가 없다(TESTING_STRATEGY 9.2의 「소비자 없는 fake 금지」). 기준 5가 fake를 요구하고 소비자는 객체 저장소를 쓰는 서비스의 유스케이스 시험이라, 9.4에 예외로 적었다(리뷰 기록 6절 ⑧).

정한 기본값

  • 결정 ⑧(소비자 없는 fake 예외), ⑨(포트 예외를 선언으로 고정). 소유자가 뒤집을 수 있다.

위험과 영향(파생 서비스가 따라 할 일)

docs/upgrade/2026-11-round9-objectstorage.md 1~4행. 요점:

  • 실패한 managed 게시를 같은 key로 다시 하면 이제 APPLIED다(전에는 REPLAYED). 같은 key로 겹친 호출은 하나만 APPLIED다. 재시도 결과로 분기하던 코드가 있으면 확인한다.
  • 중단된 stage의 verifyIntegrity는 이제 IllegalStateException이다(전에는 검증 뒤 중단이면 REPLAYED).
  • 불변 Set capability로 만든 요청이 이제 동작한다(전에는 NPE).
  • 객체 저장소를 쓰는 서비스의 유스케이스 시험은 testImplementation testFixtures(project(':application-objectstorage'))로 fake와 계약을 쓸 수 있다.
  • 남은 것: adapter 전용 ObjectStorageProviderException이 포트 밖으로 나간다. 그래서 바이트 불일치와 consumer 실패는 계약이 unchecked 예외까지만 단언한다. RR9-03-34로 따로 고친다(포트 수준 예외 타입).

검증

desktop, --no-build-cache.

  • RED: 기준 + 새 시험만 → 「불변 Set으로 만든 요청」이 NPE로 실패(b20-red), 「testFixturesCompileOnly에 Spring」이 빌드 통과로 실패(b20-red-purity). 계약 첫 실행에서 fake·adapter 모두 같은 NPE로 실패한 것이 RR9-03-33을 찾은 경로다.
  • 돌연변이: adapter의 회수 재시도를 REPLAYED→APPLIED로 바꾸면 계약 1건(「같은 회수를 다시 하면 REPLAYED다」)만 실패한다(b20-mutant).
  • RED: main에 ManagedPublicationOutcomeTest만 얹으면 실패(b20-red-overlap).
  • GREEN: 두 leaf check + :app-bootstrap:architectureTest + architectureCheck + -p build-logic test 726건 실패 0(b20-green5). 최신 main 위로 다시 쌓은 뒤 -p build-logic test 156건 실패 0.
  • desktop scripts/verify.sh pr --no-cache: head 1ab96de0(트리 f02c9da0) 7006건 실패 0, rc=0, FROM-CACHE 0. 기준 main 3e908c02.
  • 노트북: check-docs.py·check-work-docs.py rc=0.
  • 그 뒤 3e1c629d·d95e8dc0(최종 head, 트리 8eb8d69b)는 문서만 더했다: .claude/rules/java-tests.md 한 줄(시험 규칙 5가 메시지 단언을 요구해 9.4와 갈리던 것)과 업그레이드 안내. 노트북 scripts/verify.sh docs rc=0.
  • 새 눈 리뷰 세 바퀴: reviewer(be-testing)와 arch-reviewer. 1·2차 발견(fake가 실패 경로·early return·capability intent·ABORTED에서 adapter와 다름, 겹친 managed 게시 둘이 모두 APPLIED, 검증 뒤 중단한 stage 재검증, 포트 Javadoc 문구)을 모두 고쳤다. 3차는 둘 다 새 결함 0, HARD-STOP 0. 겹친 호출에서 진 쪽은 CAS 충돌 예외를 받아 publishedHere가 서지 않는 것을 코드로 확인했다(ObjectOperationKernel.replace).
  • 넘긴 것: managed 게시가 PUBLISHED CAS 직전에 다른 호출에 지면 진 쪽이 REPLAYED가 아니라 adapter의 ObjectControlConflictException을 받는다(이 PR 전부터). adapter 타입이 포트 밖으로 나가는 같은 부류라 RR9-03-34에 넣었다.

발견 ID 표

ID 판정 커밋
RR9-03-31 고침 1ab96de0, 3e1c629d, d95e8dc0
RR9-03-33 고침(고치며 찾음: 불변 Set NPE) 42d84d50
RR9-03-35 고침(고치며 찾음: managed 재시도 결과) 1ab96de0
RR9-04-46 고침(고치며 찾음: capability-status MinIO 주장) 1ab96de0
RR9-04-47 고침(고치며 찾음: 순수성 검사 testFixtures 구멍) b44aa49e
RR9-03-34 해당 없음(이 PR 밖: 포트 수준 예외 타입을 새로 설계하는 일, 따로 고친다. 겹친 managed 게시의 CAS 충돌 예외도 여기) —

관련

  • 리뷰 기록: docs/reviews/2026-11-12-round9-review/(기록 갱신 PR에서 위 ID를 더한다).
## 무엇을, 왜 round9 리뷰가 고치며 찾은 RR9-03-31을 고친다. capability 기준 5(`docs/manual/10-capabilities.md`)는 포트를 가진 모듈의 testFixtures에 포트 계약(추상 클래스)을 두고 fake와 실제 adapter가 모두 통과하게 한다. `application-objectstorage`에는 testFixtures도 fake도 없었고, 포트 인터페이스는 결과와 예외를 적지 않았다. - **포트 계약 셋과 fake**(`application-objectstorage` testFixtures `testkit`): `ManagedObjectStoragePortContract`(관리 게시·조회·전송·복구 조회·회수), `StagedObjectPublicationPortContract`(stage·검증·handoff·finalize·중단), `ObjectScanMaintenancePortContract`(scan gate), `InMemoryObjectStorage`(포트 여덟). fake(이 leaf `test`)와 adapter routing 구현(local-dev provider, adapter `test`의 `contract/LocalDev*`)이 같은 계약을 상속한다. - **포트 Javadoc**: 포트 여덟에 결과(`APPLIED`·`REPLAYED`·`REJECTED` 등)와 예외를 적었다. 계약은 그 선언만 단언한다. - **계약이 찾은 운영 결함 둘**: - 불변 Set(`Set.of`)으로 만든 게시·stage 요청이 `ObjectRequestSupport`의 `contains(null)`에서 NPE를 냈다(RR9-03-33). - 실패한 managed 게시를 다시 하면 이번 호출이 게시했는데도 `REPLAYED`였다(stage 재시도는 `APPLIED`). 이제 `PUBLISHED`로 바꾼 호출 하나만 `APPLIED`다. 같은 key로 겹친 호출은 `REPLAYED`다(`ManagedPublicationOutcomeTest`가 겹침을 결정적으로 재현한다, RR9-03-35). - 검증한 뒤 중단한 stage를 다시 검증하면 `REPLAYED`였다. 중단된 operation의 검증을 거절한다. - **리뷰가 찾은 게이트 구멍**: 순수성 검사가 순수 모듈의 `testFixturesCompileOnly`를 보지 않았다(RR9-04-47). testFixtures classpath도 같은 금지 group으로 본다. - **문서**: `.claude/rules/java-tests.md` 규칙 5(공유 계약은 포트가 선언한 것만 단언), `application-objectstorage` AGENTS·README, adapter README 「포트 계약」, `docs/testing/TESTING_STRATEGY.md` 9.4, `docs/capability-status.md` Object storage 증거 칸(「app-bootstrap 통합 시험이 MinIO로 조립」 → 실제는 local-dev, RR9-04-46). ## 고른 방법과 버린 대안 - 포트 예외는 지금 adapter 동작(`IllegalArgumentException`=요청 그대로 거절, `IllegalStateException`=지금 상태에서 거절)의 타입을 선언하는 안을 골랐다. 메시지는 구현의 것이라 계약이 단언하지 않는다. 시험 리뷰는 메시지 단언을, 구조 리뷰는 adapter 문구가 application 계약에 새는 것을 지적했다. 이 둘이 부딪쳐 아키텍처 규칙(포트는 저장소와 상관없는 말로 쓴다)을 앞에 뒀다. 타입 있는 결과로 바꾸는 안은 공개 API를 바꾸는 일이라 버렸다. 유스케이스가 감싸 기능 오류(상태 충돌이면 CONFLICT carrier)로 바꾸라고 AGENTS에 적었다. 리뷰 기록 6절 ⑨로 남긴다. - MinIO에서 포트 계약을 돌리는 안은 이번에 하지 않았다. S3 provider는 readiness registry(`docs/registries/object-storage-readiness.yaml`)에서 아직 배포 대상이 아니다. 포트 경로를 MinIO로 묶는 일은 S3를 배포 대상으로 올릴 때 같이 한다. MinIO에서는 지금처럼 provider 계약이 돈다(기준 5의 「실제 벤더 시험 1개 이상」). - fake는 이 저장소 안에 소비자가 없다(TESTING_STRATEGY 9.2의 「소비자 없는 fake 금지」). 기준 5가 fake를 요구하고 소비자는 객체 저장소를 쓰는 서비스의 유스케이스 시험이라, 9.4에 예외로 적었다(리뷰 기록 6절 ⑧). ## 정한 기본값 - 결정 ⑧(소비자 없는 fake 예외), ⑨(포트 예외를 선언으로 고정). 소유자가 뒤집을 수 있다. ## 위험과 영향(파생 서비스가 따라 할 일) `docs/upgrade/2026-11-round9-objectstorage.md` 1~4행. 요점: - 실패한 managed 게시를 같은 key로 다시 하면 이제 `APPLIED`다(전에는 `REPLAYED`). 같은 key로 겹친 호출은 하나만 `APPLIED`다. 재시도 결과로 분기하던 코드가 있으면 확인한다. - 중단된 stage의 `verifyIntegrity`는 이제 `IllegalStateException`이다(전에는 검증 뒤 중단이면 `REPLAYED`). - 불변 Set capability로 만든 요청이 이제 동작한다(전에는 NPE). - 객체 저장소를 쓰는 서비스의 유스케이스 시험은 `testImplementation testFixtures(project(':application-objectstorage'))`로 fake와 계약을 쓸 수 있다. - 남은 것: adapter 전용 `ObjectStorageProviderException`이 포트 밖으로 나간다. 그래서 바이트 불일치와 consumer 실패는 계약이 unchecked 예외까지만 단언한다. RR9-03-34로 따로 고친다(포트 수준 예외 타입). ## 검증 desktop, `--no-build-cache`. - RED: 기준 + 새 시험만 → 「불변 Set으로 만든 요청」이 NPE로 실패(`b20-red`), 「testFixturesCompileOnly에 Spring」이 빌드 통과로 실패(`b20-red-purity`). 계약 첫 실행에서 fake·adapter 모두 같은 NPE로 실패한 것이 RR9-03-33을 찾은 경로다. - 돌연변이: adapter의 회수 재시도를 `REPLAYED`→`APPLIED`로 바꾸면 계약 1건(「같은 회수를 다시 하면 REPLAYED다」)만 실패한다(`b20-mutant`). - RED: main에 `ManagedPublicationOutcomeTest`만 얹으면 실패(`b20-red-overlap`). - GREEN: 두 leaf `check` + `:app-bootstrap:architectureTest` + `architectureCheck` + `-p build-logic test` 726건 실패 0(`b20-green5`). 최신 main 위로 다시 쌓은 뒤 `-p build-logic test` 156건 실패 0. - desktop `scripts/verify.sh pr --no-cache`: head `1ab96de0`(트리 `f02c9da0`) 7006건 실패 0, rc=0, `FROM-CACHE` 0. 기준 main `3e908c02`. - 노트북: `check-docs.py`·`check-work-docs.py` rc=0. - 그 뒤 `3e1c629d`·`d95e8dc0`(최종 head, 트리 `8eb8d69b`)는 문서만 더했다: `.claude/rules/java-tests.md` 한 줄(시험 규칙 5가 메시지 단언을 요구해 9.4와 갈리던 것)과 업그레이드 안내. 노트북 `scripts/verify.sh docs` rc=0. - 새 눈 리뷰 세 바퀴: reviewer(be-testing)와 arch-reviewer. 1·2차 발견(fake가 실패 경로·early return·capability intent·ABORTED에서 adapter와 다름, 겹친 managed 게시 둘이 모두 `APPLIED`, 검증 뒤 중단한 stage 재검증, 포트 Javadoc 문구)을 모두 고쳤다. 3차는 둘 다 새 결함 0, HARD-STOP 0. 겹친 호출에서 진 쪽은 CAS 충돌 예외를 받아 `publishedHere`가 서지 않는 것을 코드로 확인했다(`ObjectOperationKernel.replace`). - 넘긴 것: managed 게시가 `PUBLISHED` CAS 직전에 다른 호출에 지면 진 쪽이 `REPLAYED`가 아니라 adapter의 `ObjectControlConflictException`을 받는다(이 PR 전부터). adapter 타입이 포트 밖으로 나가는 같은 부류라 RR9-03-34에 넣었다. ## 발견 ID 표 | ID | 판정 | 커밋 | | --- | --- | --- | | RR9-03-31 | 고침 | 1ab96de0, 3e1c629d, d95e8dc0 | | RR9-03-33 | 고침(고치며 찾음: 불변 Set NPE) | 42d84d50 | | RR9-03-35 | 고침(고치며 찾음: managed 재시도 결과) | 1ab96de0 | | RR9-04-46 | 고침(고치며 찾음: capability-status MinIO 주장) | 1ab96de0 | | RR9-04-47 | 고침(고치며 찾음: 순수성 검사 testFixtures 구멍) | b44aa49e | | RR9-03-34 | 해당 없음(이 PR 밖: 포트 수준 예외 타입을 새로 설계하는 일, 따로 고친다. 겹친 managed 게시의 CAS 충돌 예외도 여기) | — | ## 관련 - 리뷰 기록: `docs/reviews/2026-11-12-round9-review/`(기록 갱신 PR에서 위 ID를 더한다).
donghyeon.kang added 4 commits 2026-11-13 06:02:38 +00:00
문제: ObjectRequestSupport.immutableCapabilities가 null 원소를 거르려고
capabilities.contains(null)을 불렀다. JDK의 불변 Set(Set.of, Set.copyOf)은
contains(null)에서 false 대신 NullPointerException을 던진다. 그래서 게시·stage 요청을
Set.of(...) capability로 만들면 생성자가 NPE로 실패했다. 지금 호출자가 모두 EnumSet을
넘겨 드러나지 않았고, 포트 계약 시험(다음 커밋)이 처음 잡았다.

고친 것: 원소를 하나씩 보고 null이면 지금처럼 IllegalArgumentException을 던진다.

검증: desktop, 기준 4ca61cd9에 새 시험만 → 「불변 Set으로 만든 요청」이 NPE로 실패.
고친 뒤 :application-objectstorage:check 통과(다음 커밋의 GREEN 실행에 포함).

Refs: RR9-03-33
문제: verifyModuleDependencyPurity는 순수 모듈(application-*, domain-core,
shared-contract)의 compile·runtime·test classpath만 풀어 봤다. test classpath는
testFixturesImplementation을 거쳐 보지만 testFixturesCompileOnly는 보지 않는다. 그래서
공유 fixtures에 Spring을 compileOnly로 두면 순수성 검사를 통과했다. testFixtures를 쓰는
순수 leaf 다섯 곳에 같은 구멍이 있었다.

고친 것: java-test-fixtures를 쓴 순수 모듈은 testFixturesCompileClasspath·
testFixturesRuntimeClasspath도 같은 금지 group으로 본다. 지금 다섯 leaf의 fixtures에는
금지 group이 없어 기존 빌드는 그대로 통과한다(lockfile 대조).

검증: desktop, 기준 4ca61cd9 + 새 functional 시험만 → testFixturesCompileOnly Spring
케이스가 빌드 통과로 실패(RED). 고친 뒤 -p build-logic test 통과(다음 커밋의 GREEN
실행에 포함).

Refs: RR9-04-47
문제: capability 기준 5(docs/manual/10-capabilities.md)는 포트를 가진 모듈의
testFixtures에 포트 계약을 두고 fake와 실제 adapter가 모두 통과하게 한다.
application-objectstorage에는 testFixtures도 fake도 없었다. 포트 수준 동작은 adapter
안의 local-dev 시험으로만 봤고, 포트 인터페이스는 결과와 예외를 적지 않았다.
capability-status는 app-bootstrap 통합 시험이 MinIO로 조립한다고 적었지만 실제로는
local-dev다.

고친 것:
- 포트 여덟의 Javadoc에 결과(APPLIED·REPLAYED·REJECTED 등)와 예외 타입을 적었다.
  IllegalArgumentException은 요청 그대로를, IllegalStateException은 지금 상태에서의
  거절이다. 유스케이스가 감싸 기능 오류로 바꾸고, 설정이 틀린 destination은 조립
  오류(500)로 바꾼다(AGENTS 규칙). 예외 메시지는 구현의 것이라 계약이 단언하지 않는다.
- testFixtures testkit: 계약 셋(ManagedObjectStoragePortContract 관리 게시·조회·
  전송·복구 조회·회수, StagedObjectPublicationPortContract 단계 게시·handoff·중단,
  ObjectScanMaintenancePortContract scan gate), in-memory fake InMemoryObjectStorage,
  destination 설명 ObjectStorageDestinationPolicy.
- fake(이 leaf test)와 adapter routing 구현(local-dev, adapter test contract/LocalDev*)이
  같은 계약을 상속한다. adapter 쪽 destination 설명은 조립된 policySnapshot에서 읽는다.
- adapter에서 계약이 드러낸 것 둘:
  - 실패한 managed 게시를 다시 하면 이번 호출이 게시했는데도 REPLAYED였다(stage 재시도는
    APPLIED). 이제 PUBLISHED로 바꾼 호출 하나만 APPLIED다. 같은 key로 겹친 호출은
    REPLAYED다(ManagedPublicationOutcomeTest가 겹침을 결정적으로 재현한다).
  - 검증한 뒤 중단한 stage를 다시 검증하면 REPLAYED였다. 중단된 operation의 검증을
    거절한다.
- 문서: application-objectstorage AGENTS·README, adapter README 「포트 계약」,
  TESTING_STRATEGY 9.4, capability-status Object storage 증거 칸.

버린 대안: MinIO에서 포트 계약 돌리기. S3 provider는 readiness registry에서 아직 배포
대상이 아니다(docs/registries/object-storage-readiness.yaml). 포트 경로를 MinIO로 묶는
일은 S3를 배포 대상으로 올리는 일과 같이 간다. MinIO에서는 provider 계약이 돈다.
남은 것: adapter 전용 ObjectStorageProviderException이 포트 밖으로 나가 바이트
불일치·consumer 실패는 계약이 unchecked 예외까지만 단언한다(RR9-03-34, 따로 고친다).

검증: desktop, :application-objectstorage:check :adapter:outbound:objectstorage:check
:app-bootstrap:architectureTest architectureCheck -p build-logic test 726건 실패 0.
RED: main에 ManagedPublicationOutcomeTest만 → 실패. 돌연변이: adapter의 회수 재시도를
REPLAYED→APPLIED로 바꾸면 계약 1건이 실패한다.

Refs: RR9-03-31, RR9-03-35, RR9-04-46
시험 규칙 5는 예외 메시지까지 단언하라고 했다. fake와 adapter가 함께
상속하는 계약에서는 메시지가 구현마다 달라 그 규칙을 따를 수 없다.
TESTING_STRATEGY 9.4가 이미 그렇게 정했는데 규칙 문서가 가리키지 않아,
다음 작성자가 메시지 단언을 다시 넣을 수 있었다.

Refs: RR9-03-31
donghyeon.kang added 1 commit 2026-11-13 06:09:36 +00:00
실패한 managed 게시를 다시 하면 APPLIED가 되고, 중단한 stage의 재검증은
IllegalStateException이 되며, 불변 Set capability가 동작한다. 이 셋과
testFixtures의 fake·계약을 쓰는 법을 업그레이드 안내에 적는다.

Refs: RR9-03-31, RR9-03-33, RR9-03-35
donghyeon.kang added 1 commit 2026-11-13 06:29:02 +00:00
Merge branch 'main' into claude/r9-objstore-contract
pr / done (pull_request) Canceled after 4m7s
e742e47921
donghyeon.kang added 1 commit 2026-11-13 07:58:23 +00:00
Merge branch 'main' into claude/r9-objstore-contract
pr / done (pull_request) Successful in 12m57s
228f20391a
donghyeon.kang merged commit c7a18ec7fa into main 2026-11-13 09:42:53 +00:00
donghyeon.kang deleted branch claude/r9-objstore-contract 2026-11-13 09:42:53 +00:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: donghyeon.kang/clean-architecture-backend-template#35