문제: complete 응답을 잃은 뒤 다음 upload()가 재조정해 서버 status
QUARANTINED를 찾았을 때, 로컬 checkpoint 삭제가 한 번 실패하면 runtime이
그 실패를 그대로 돌려준다({UNAVAILABLE, UPLOAD_RECONCILE, retryable:true,
RESUME}). 서버에는 자원이 이미 있는데 이 호출은 resourceId를 잃는다. 같은
상황의 complete 경로는 삭제 실패를 무시하고 성공을 준다.
고친 방법: 재조정의 QUARANTINED 분기도 complete 경로와 같이 삭제 결과와
상관없이 {QUARANTINED, resourceId, replayed:true}를 준다. 남은 행은 다음
upload()나 abort()가 같은 자원으로 정리한다. 설계 문서 4.3절의 같은 규칙
줄에 재조정 경우를 더했다.
위험·한계: 삭제가 계속 실패하는 저장소에서는 행이 남는다. 다음 호출마다
status를 한 번 읽고 같은 resourceId를 replayed로 준다. complete 경로와 같은
한계다.
검증:
- 새 테스트: 고치기 전 {ok:false, UNAVAILABLE, UPLOAD_RECONCILE} (리뷰 X4와
같다), 고친 뒤 {ok:true, QUARANTINED, resource_01, replayed:true}, 행 남음,
다음 호출이 정리
- 영역 단위 테스트 15파일 276건 통과
- check:types(test), eslint(바꾼 파일) 통과
Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 0929/01-02
문제: FILE_BYTE_SOURCE로 이어 올리면 runtime이 서버가 이미 받은 part까지
SHA-256으로 다시 검증한다. 검증(verifyUploadPartBytes)이 수락 확인보다
앞에 있기 때문이다. 8 part 중 6개가 수락된 뒤 이어 올리면 part 해시가
16번 돈다. RANGE_READER 경로는 같은 상황에서 10번이다(manifest 8 + 보낼
part 2).
고친 방법: 스트림 경로에서 수락된 part는 검증 전에 건너뛴다. 보내지 않는
part의 바이트는 검증할 필요가 없다. 파일이 checkpoint와 같은지는 그 앞의
manifest 계산이 이미 확인한다(다른 파일이면 STALE_RESULT). part의
offset·길이 확인은 그대로 모든 part에 한다.
위험·한계: 스트림은 여전히 처음부터 끝까지 읽는다. 읽기를 건너뛰는 것은
스트림 모양상 할 수 없다.
검증:
- 새 테스트(8 part 중 6개 수락 뒤 FILE 재개, part 크기 digest 수): 고치기
전 16, 고친 뒤 10
- 영역 단위 테스트 15파일 275건 통과
- check:types(test), eslint(바꾼 파일) 통과
Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 1101/01-02
문제: part 단계(BFF 발급, object store PUT)가 상한(maxRetryAfterMs, 기본
30초)보다 긴 Retry-After로 429·503을 받으면 runtime은 기다리지 않고
멈춘다. 그런데 앱에 주는 실패는 retryable:true다. 포트 표대로면 "자동
재시도해도 된다"는 뜻이라, 서버가 45초 기다리라고 한 요청을 앱이 바로
다시 보낸다. 같은 429에 control plane 전송은 retryable:false를 준다.
control plane도 전송 상한이 정책 상한보다 크면 retryable:true가 된다.
고친 방법: provider 실패를 앱 실패로 바꾸는 한 곳(stripProviderFailure)이
정책 상한을 받아, 지우는 retryAfterMs가 상한을 넘었으면 retryable을
false로 만든다. control plane 전송이 이미 쓰는 규칙이다. 한 곳에서 하므로
두 단계와 두 factory 상한 조합이 모두 같은 답을 낸다. 포트 주석과 설계
문서(presigned-transfer-and-image-cdn.md 7절)에 같은 규칙을 적었다.
버린 대안: 현상 유지 + 포트 주의 한 줄은 앱이 기다릴 값을 모르므로 지킬
수 없다. 앱 실패에 retryAfterMs를 싣는 안은 공유 타입 BrowserDataFailure를
바꿔 다른 포트까지 퍼진다. 상한 밖 값도 기다리는 안은 한 호출이 끝없이
늘어지지 않는다는 상한의 목적을 깬다(리뷰 5절 D2).
위험·한계: upload()·abort()의 실패 값이 바뀐다. 상한 밖 Retry-After는
RESUME에 retryable:false가 되어, 자동 재시도하던 다운스트림은 사람이
누르는 재시도로 넘어간다. 상한 안 대기, PUT 403 재발급, 발급 401/403
NONE은 바뀌지 않는다(기존 테스트 그대로 통과). 헤더 없는 part 단계 429가
backoff로 재시도하는 차이는 이 변경 범위 밖이다.
검증:
- 고치기 전: 새 단언 5건 실패(part 단계 4건, 전송 상한 60초 조합 1건)
- 고친 뒤: 영역 단위 테스트 15파일 274건 통과
- check:types, eslint(바꾼 파일) 통과
Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 01-02
문제: 문서와 주석이 적은 규칙 세 개를 바꿔도 영역 단위 테스트가 모두
통과한다. 리뷰 변이 N2(part 단계가 503의 Retry-After를 읽지 않음),
N10(abort 재시도마다 ABORT 멱등 키를 바꿈, 세 라운드째 생존),
N17(control plane이 헤더 없는 429를 retryable:true로 냄)이 살아남았다.
고친 방법: 규칙마다 실패하는 테스트를 더한다.
- part 단계 Retry-After 묶음에 503을 더한다. 실제 presigned provider·
vault·실행기로 발급과 PUT 두 단계를 본다.
- abort가 한 호출 안에서 재시도하고 다음 abort() 호출에서 다시 보낼 때
세 요청의 idempotencyKey가 모두 같은지 본다. 같은 파일의
createSession·part·complete 키 테스트와 같은 방식이다.
- fetch transport가 헤더 없는 429와 상한 밖 429를 retryable:false,
retryAfterMs 없음으로 내는지 본다.
위험·한계: 테스트만 더했다. 동작은 바뀌지 않는다.
검증:
- 영역 단위 테스트(resumable-upload, presigned-transfer, image-cdn,
upload-cancellation) 15파일 272건 통과
- 변이를 하나씩 넣고 돌렸다: N2 4건 실패, N10 1건 실패, N17 2건 실패.
변이는 원본으로 되돌렸다
- check:types, eslint(바꾼 두 파일) 통과
Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 01-03
문제: part 발급(BFF)이 401/403으로 거절하면 upload()가
{PERMISSION_DENIED, UPLOAD_PART, retryable:false, RESUME}을 돌려준다.
세션 만료나 권한 회수라서 재인증 전에는 다시 불러도 같은 거절이다.
그런데 RESUME을 믿는 화면은 "다시 시도"를 띄우고, 다시 부르면 파일
전체를 재해시한 뒤 같은 거절을 받는다. 지난 수정(9142390)은 이 경로를
남겼다. object store PUT 403과 code·단계·recovery가 모두 같아서
toUploadAction 한 곳에서 가를 수 없었다.
고른 방법: 실패의 출처를 아는 곳에서 표시한다. runtime의
uploadPartWithRetry 발급 분기만 그 실패가 BFF 발급에서 왔다는 것을
안다. 그 분기에서 PERMISSION_DENIED를 {retryable:false, NONE}으로
만든다. 표시는 별도 필드 대신 기존 recovery 값(NONE)이다. 번역
(toUploadAction)은 NONE을 그대로 두고 retryable:false를 강제한다. 공개
타입은 바뀌지 않는다. 발급 분기는 모든 control plane 구현이 지나는
곳이라 http-control-plane-adapter 말고 다른 구현에도 같은 답이 나온다.
PUT 403은 그대로 RESUME이다. 서명 만료가 보통 원인이고 다음 시도가 새
capability를 받는다(지난 수정의 보존 조건).
버린 대안:
- 백엔드가 code를 나눈다: 두 repo 계약이 바뀌고 다른 백엔드에도 기대야
한다.
- code만 보고 번역에서 추측한다: 두 출처의 code가 같아 불가능하다.
PERMISSION_DENIED를 모두 NONE으로 하면 PUT 403 테스트 2건이 깨진다.
- 실패의 stage(operation) union에 발급 값을 더한다: 공개 타입 변경이라
[계약]이다. 같은 일을 기존 값으로 할 수 있다.
- 내부 표시 필드나 WeakSet: 발급 분기와 번역 사이에서 실패는 공개
BrowserDataFailure로 오간다. 필드를 실으려면 타입 단언이 필요하고,
WeakSet은 객체 동일성에 기대는 숨은 결합이다. 중간에 실패를 다시
만들면 말없이 표시가 사라진다.
- control plane adapter에서 바꾼다: 다른 control plane 구현은 여전히
RESUME을 낸다.
위험·한계:
- BFF 발급 401/403의 recovery가 RESUME → NONE으로 바뀐다. 다운스트림
화면이 이 값으로 분기하므로 CHANGELOG [계약] 한 줄이 필요하다.
- control plane이 발급 거절을 retryable:true로 줘도 이제 재시도하지
않는다. 재인증 전에는 결과가 같기 때문이다.
- 재인증 자체는 앱 세션 계층 몫이라 다루지 않았다.
- 실제 BFF·object store가 아니라 fetch 가짜 서버로 확인했다.
- file-transfer 레시피 번들 56,031 → 56,053 gzip B(예산 56,100).
검증:
- RED(수정 전): resumable-upload-runtime-recovery.test.ts 새 3건 중
BFF 발급 401·403 2건 실패(recovery 기대 NONE, 실제 RESUME). PUT 403
1건은 수정 전에도 RESUME으로 통과(보존 조건 고정).
- GREEN: 같은 파일 37건 통과. 세 경로 모두 retryable:false를 단언한다.
- 변이: 번역에 "PERMISSION_DENIED → NONE"을 넣으면 PUT 403 2건(새
테스트, 기존 01-05 표 테스트)이 실패한다.
- 회귀: resumable-upload·presigned·upload-cancellation·browser-file·
image-cdn 단위 20파일 329건 통과. tsc app·test·recipes 통과. 바꾼
파일 eslint 통과. verify-documentation-readiness PASS_SCOPED.
check-optional-recipes(source) file-transfer 56053/56100.
- 미실행: check:architecture(pnpm 필요).
Refs: docs/reviews/2026-09-29-maturity-review/01-adapters-browser-transfer.md
문제: 포트는 upload() 실패의 recovery가 호출자 행동 하나를 가리킨다고
적는다. 번역은 toUploadAction 한 곳이 하는데 recovery 단어만 본다. 표
밖 값이면 REISSUE_CAPABILITY·RETRY만 RESUME, 나머지는 NONE으로 바꾸고
retryable은 그대로 둔다. 그래서 지난 리뷰 실험 X1의 경로들이 표와 다른
행동을 가리킨다.
- ① 고른 파일이 바뀜(NOT_READABLE/REOPEN): NONE에 retryable:true.
표대로면 RESELECT다.
- ② IndexedDB 일시 오류(UNAVAILABLE/REOPEN, retryable:true): NONE.
다시 부르면 성공한다.
- ③ part 발급 404(서버가 session을 모름): NONE. 다시 부르면 새
session으로 성공한다.
- ⑤ 닫힌 runtime: RESUME. 같은 runtime은 늘 같은 답이다.
- ⑥ session보다 긴 capability(POLICY_REJECTED/REISSUE_CAPABILITY):
RESUME. 서버가 같은 값을 다시 준다.
고른 방법(지난 리뷰 3절 D1의 (a), 번역 기준 보강): 번역은 계속 한 곳에
둔다. 몇 가지 code가 먼저 정한다. POLICY_REJECTED → NONE, file store의
NOT_READABLE/REOPEN → RESELECT, UPLOAD_PART의 NOT_FOUND → RECONCILE.
나머지는 지금처럼 표 안 값은 그대로 두고, 표 밖이면 retryable:true나
REISSUE_CAPABILITY·RETRY일 때 RESUME, 아니면 NONE이다. NONE과 RESELECT는
번역 끝에서 retryable:false로 맞춘다. 닫힌 runtime은 NONE을 돌려준다.
포트 표 주석과 설계 문서 표에 이 규칙을 적었다.
버린 대안:
- 리뷰 예시의 STALE_RESULT → RESELECT. 기존 STALE_RESULT/RECONCILE
경로(resumable-upload-runtime.ts의 재조정)를 깨뜨린다. 지금
STALE_RESULT는 모두 표 안 값을 갖고 있어 규칙이 필요 없다.
- 리뷰 예시의 NOT_READABLE → RESELECT(조건 없이). PUT 중 네트워크 읽기
실패도 NOT_READABLE(REISSUE_CAPABILITY)이라 파일 재선택으로 잘못
보낸다. 그래서 REOPEN(file store가 붙이는 값)일 때만 RESELECT다.
- 출처마다 포트 어휘를 만들게 하는 안(b), action 필드 추가(c). 지난
리뷰가 다른 포트를 틀어지게 하거나 공유 타입을 바꾼다고 기각했다.
위험·한계:
- ④ part 발급(BFF) 401/403은 고치지 않았다. 지금도 RESUME이다. object
store PUT 403(재발급으로 풀리고, 기존 01-05 표 테스트가 RESUME으로
고정)과 code·단계·recovery가 모두 같아 번역 한 곳에서 가를 수 없다.
리뷰 예시("PERMISSION_DENIED는 단계와 무관하게 NONE")와 보존 조건
("기존 7경로 기대값 유지")이 이 경로에서 서로 어긋난다. runtime
호출 지점에서 발급 거절만 따로 표시할지는 소유자 판단이 필요하다.
그래서 이 발견은 부분 충족이다.
- 몇 경로의 recovery 값이 바뀐다(위 ①②③⑤⑥). 기존 테스트 하나
(resumable-upload-runtime-contract.test.ts "rejects a part capability
that outlives its session")의 기대값을 RESUME → NONE으로 바꿨다.
다운스트림 화면이 이 값으로 분기하므로 CHANGELOG [계약] 한 줄이
필요하다. 이번 수정 묶음은 CHANGELOG를 한 번에 쓰므로 여기서는 쓰지
않았다.
- 실제 브라우저 오류 발생은 재현하지 않았다. 단위 harness에서 오류
값을 주입했다.
- file-transfer 레시피 번들이 55,937 → 56,031 gzip bytes가 되어 예산
56,000을 넘었다. 다음 백 단위 규칙대로 56,100으로 올렸다.
검증:
- RED(수정 전): resumable-upload-runtime-recovery.test.ts 새 5건 실패.
① recovery NONE·retryable true(기대 RESELECT·false), ② NONE(기대
RESUME), ③ NONE(기대 RECONCILE), ⑤ RESUME(기대 NONE), ⑥ RESUME(기대
NONE). 수정 전 번역 규칙으로 되돌리면 같은 5건이 실패한다.
- GREEN: 같은 파일 통과. 기존 7경로 표 테스트에 "NONE이면
retryable:false" 단언을 더했고 통과한다.
- 회귀: resumable-upload·presigned·upload-cancellation·browser-file·
image-cdn 단위 20파일 326건 통과. tsc app·test·recipes 통과. 바꾼
파일 eslint 통과. verify-documentation-readiness PASS_SCOPED.
check-architecture(exec 전용 shim) 통과. check-optional-recipes
(source) file-transfer 56031/56100.
Refs: docs/reviews/2026-09-29-maturity-review/01-adapters-browser-transfer.md
문제: part 단계(BFF capability 발급, object store PUT)의 상태표
statusFailure는 상태 코드만 받아 429의 Retry-After를 버린다. 서버가
`429 Retry-After: 5`로 답해도 runtime은 지수 backoff(기본 250·500·
1000ms)로 다시 보내고, 1.75초 안에 요청 8개를 쓴 뒤 retryable 실패를
돌려준다. 설계 문서 두 곳(presigned-transfer-and-image-cdn.md,
server-file-capability-infrastructure.md)은 part 단계도 bounded
Retry-After를 따른다고 적는다. 헤더를 읽는 곳은 control plane
transport뿐이었다.
고른 방법: statusFailure가 Response와 현재 시각을 받아 429·503이면
kernel parseRetryAfterDelay로 retryAfterMs를 채운다. 상한
maxRetryAfterMs는 runtime의 canRetry·waitForRetry가 이미 적용하므로
presigned 계층은 값을 그대로 넘긴다. 상한을 넘으면 재시도하지 않는다
(control plane과 같은 규칙). PresignedUploadPartCapabilityProvider.
issueUploadPart와 PresignedUploadPartPort.put의 반환 타입을
UploadProviderResult로 넓혔다. 기존 구현은 그대로 대입되므로
추가형이다. HTTP control plane 어댑터의 발급 브리지가 실패를 다시
만들면서 retryAfterMs를 버리던 것도 넘기게 했다.
버린 대안:
- 문서를 "part 단계는 Retry-After를 읽지 않는다"로 고친다. 재시도
증폭이 그대로 남는다.
- BFF 응답 본문에 대기 시간을 넣는 별도 계약. 표준 헤더를 두고 서버와
클라이언트를 함께 바꿔야 한다.
- download 경로만 빼고 읽는다. 하나로 합친 상태표(Q-6.1-9)를 다시
둘로 가르게 된다. download 소비자(browser-files 전달 어댑터)는
실패를 다시 만들어 이 값을 읽지 않는다.
위험·한계:
- 다른 origin의 object store가 Access-Control-Expose-Headers에
Retry-After를 넣지 않으면 헤더가 없는 것으로 읽혀 지금처럼 backoff만
쓴다. statusFailure 주석에 적었다.
- part 단계에서 Retry-After가 없거나 형식이 틀린 429는 지금처럼
retryable backoff다. control plane은 이 경우 재시도하지 않는다. 이
차이는 이번에 바꾸지 않았다.
- issueDownload·open 실패에도 retryAfterMs가 실린다. 이 두 포트의
타입(BrowserDataResult)에는 드러나지 않는다.
- file-transfer 레시피 번들이 55,623 → 55,725 gzip bytes가 되어 예산
55,700을 넘었다. 측정값 위 약 100바이트로 반올림하는 기존 규칙
(4b0e44a9)대로 55,800으로 올렸다.
- 포트 반환 타입이 넓어졌으므로 CHANGELOG [계약] 한 줄이 필요하다.
이번 수정 묶음은 CHANGELOG를 한 번에 쓰므로 여기서는 쓰지 않았다.
검증:
- RED(수정 전): resumable-upload-runtime-recovery.test.ts 새 4건 실패.
발급·PUT이 `429 Retry-After: 5`일 때 "expected 0 to be greater than
or equal to 5000"(첫 sleep 0ms). maxRetryAfterMs 1000을 넘을 때
재시도해서 ok:true. resumable-upload-http-control-plane.test.ts 새
1건 실패: 브리지 결과에 retryAfterMs 5000이 없다.
- GREEN: 두 파일 33건 통과.
- 회귀: browser-file·image-cdn·presigned·resumable-upload·
upload-cancellation·json-schema 단위 21파일 322건 통과. tsc app·
test·node·recipes 통과. 바꾼 파일 eslint 통과. check-architecture
(exec 전용 shim, pnpm 미사용) 통과, check-adapter-inventory 통과,
check-optional-recipes(source) PASS file-transfer 55725/55800.
Refs: docs/reviews/2026-11-01-maturity-review/01-adapters-browser-transfer.md
The executor and the runtime both recorded UPLOAD_PART, so a part retried once
became one FAILED and two SUCCEEDED records, and no retry bucket existed. PUT
attempts are now PRESIGNED_TRANSFER; the runtime records the part once with
its attempt count as countBucket.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Resume re-ran the current policy against the stored session, so a build that
lowered maxConcurrency or maxSessionLifetimeMs failed every upload an older
build had started with INTEGRITY_FAILED. Resume now checks the session only
against its checkpoint.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A server lifetime equal to the client ceiling was refused as soon as the
device clock ran slightly behind, and the error did not read as a clock
problem. Both ceilings now allow maxClockSkewMs (default 60 s), as image-cdn
already does; the doc states the server-side lifetime conditions.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ABORT_PENDING and a checkpoint CAS race returned the same failure, and some
recoveries (REISSUE_CAPABILITY, RESTART for a replayed create) named actions
the caller cannot take or that repeat the failure. The port now documents a
five-value recovery table and upload() returns only those values.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A fixed 30 s attempt deadline never let a 5 MiB part finish below ~1.4 Mbit/s,
and a download had one deadline for its whole body. PUT and download limits
now add bytes / minTransferBytesPerSecond (default 64 KiB/s), and a stalled
download ends at a per-chunk idle limit.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A failed checkpoint cleanup after a committed complete returned a failure and
dropped the resourceId, and abort() on ALREADY_COMPLETED returned no id. The
upload now succeeds, abort() reads the id from status first, and the port and
design doc state the in-progress complete contract (429 + Retry-After).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Mutations that changed the create, part or complete key per call or per
attempt passed every test. Four tests now fail on M1, M6, M7; SHA-256 gains
the two-block FIPS vector and a node:crypto comparison.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A single object-store refusal ended the whole upload as PERMISSION_DENIED
with retryable:false. The next attempt already issues a fresh capability, so
REISSUE_CAPABILITY PUT failures now retry within maxRetries; BFF issuance
refusals still stop at once.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>