문제: fileserver·notification의 HTTP 표면이 공용 계약(web AGENTS B8,
http-contract §1, manual 11)과 달랐다.
- fileserver batch는 part가 실패해도 success:true였고 결과를 data.results에
넣었다. fullySucceeded()를 아무도 부르지 않았다. 계약끼리도 달랐다(web B8의
BATCH_PARTIAL_FAILURE vs fileserver 계약의 200 + results[].error).
- BulkEnvelope.partial의 error.message가 영어 고정 문구였고, BulkItemResult는
호출자 문구를 그대로 실었으며 null 키를 남겼다(mix-in 없음).
- Content-Range가 CORS 노출 목록에 없어 브라우저가 다운로드를 이어 받지 못했다.
- 알림 제출·template 게시의 모르는 channel·slot·locale이 details 없는
BAD_PARAMETER였고(주석은 validation error), template 경로가 lowerCamel이 아닌
/notification-templates였다.
- 전송 넷(raw·multipart·draft-12·tus)이 이름 없는 업로드에 "upload.bin"을
지어 넣었다. 앱 정책 OriginalFilenamePolicy의 기본값은 "file"이라 업무 규칙이
두 곳에 있었다(HARD-STOP 4).
- EnvelopeWireShapeTest는 http-contract §1의 증거로 쓰이는데 data null 키 생략,
String → Envelope, unsorted page의 sort:null, 부분 실패 문구를 보지 않았다.
고른 방법:
- 리뷰 README 6절 ①대로 fileserver batch도 공용 bulk envelope다. 모두 성공 →
success:true + results, 하나라도 실패 → success:false + BATCH_PARTIAL_FAILURE +
part별 details(index, status, id, code, message). 성공한 part는 되돌리지 않는다.
BatchUploadResponse는 쓰는 곳이 없어져 지웠다.
- BulkEnvelope.partial과 BulkItemResult.error(index, ApiErrorCode)는 category
고정 문구를 쓴다. BulkItemResult에 null 생략 mix-in을 더했다.
- 알림 controller는 NotificationFieldRejection(VALIDATION_FAILED carrier, 필드를
짚는 details 하나, 거절한 값은 싣지 않음)을 던진다. template 경로는
/notificationTemplates다. 읽는 endpoint가 없어 201에 Location을 싣지 않고,
manual 11 규칙에 그 경우를 적었다.
- 전송은 이름이 없으면 빈 이름을 넘기고 OriginalFilenamePolicy가 정한다.
- EnvelopeWireShapeTest에 빠진 넷을 더했다. EnvelopeTest의 when 둘인 시험을
둘로 나눴다.
버린 대안: /notification-templates를 별칭으로 남기기 — 같은 자원의 경로가 둘이
되고 인가·공개 경로 스냅숏이 둘을 따로 봐야 한다.
위험·한계: batch를 읽는 client, 알림 template 경로를 쓰는 client와 배포
스크립트, BulkItemResult.error(index, code, message)를 부르던 코드가 바뀐다
(upgrade 안내 6·7·10·11·12, 14).
BREAKING CHANGE: fileserver batch 응답이 공용 bulk envelope가 됐다. 알림
template 경로가 /notificationTemplates다. 알림의 모르는 vocabulary 값은
VALIDATION_FAILED다. BulkItemResult.error는 ApiErrorCode를 받는다. 이름 없는
업로드의 표시 이름이 "file"이다. 할 일은 docs/upgrade/2026-11-round9-contracts.md.
Refs: RR9-03-01, RR9-03-02, RR9-03-09, RR9-03-13, RR9-03-21, RR9-05-09