문제: 포트는 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
문서 색인
docs/의 문서를 세 묶음으로 나눈다.
1. 현재 계약 지금 코드가 지키는 규칙. 게이트가 검사한다
2. 목표 설계 앞으로의 설계와 결정. 구현됐다는 뜻이 아니다
3. 작업 이력 리뷰·계획·작업 추적. 복사한 프로젝트는 지워도 된다
문서와 코드가 다르면 코드가 맞다. 목표 설계 문서에 적힌 기능이 지금 동작하는지는
문서 안의 상태 값(COMPOSED, AVAILABLE_NOT_COMPOSED, DESIGNED_NOT_IMPLEMENTED 등)으로
확인한다. 상태 값의 뜻은 README.md의 "Support scope" 절에 있다.
README와 입구 문서는 영어, recipe·ledger·스타일 문서는 한국어다.
1. 현재 계약
처음 읽을 입구 문서 6개다.
| 문서 | 정하는 것 |
|---|---|
README.md |
시작, 런타임 설정과 배포 변수, 검증 명령, CI, 지원 범위, 원본 업데이트 반영 |
architecture/frontend-application-foundation.md |
이 repo의 역할(스타터 + 재사용 capability)과 기본·선택의 경계 |
architecture/layers.md, architecture/overview.md |
계층과 import 방향. check:architecture가 검사한다 |
architecture/starter-experience.md |
기본 라우트, 인증 모드, 기능 추가·제거 절차 |
architecture/optional-adapter-recipes.md |
선택 기능(recipe)을 넣고 빼는 절차 |
operations/ci-quality-gates.md, testing/taxonomy.md |
게이트, 테스트 계층, 새 프로젝트가 초기화할 기준선 |
입구 문서가 가리키는 세부 규칙:
- 계약 소유와 호환성:
architecture/contract-ownership.md,contracts/compatibility.md - 정적 배포와 런타임 설정:
architecture/static-delivery.md - 기능 개발자가 알아야 하는 양:
architecture/capability-consumer-experience.md - 운영·복구:
operations/,runbooks/ - 보안과 공급망:
security/browser-boundary.md,security/supply-chain.md - 디자인 토큰과 수동 접근성 검토:
styling/design-tokens.md,accessibility/manual-checklist.md - 버전별 변경:
../CHANGELOG.md
게이트가 직접 읽는 파일이라 지우거나 옮기면 게이트가 실패한다.
| 파일 | 읽는 명령 |
|---|---|
architecture/review-ledger.json, architecture/review-evidence.md, accessibility/manual-checklist.md |
verify:documentation (FE-GATE-017) |
reviews/adapters/INVENTORY.md |
check:adapter-inventory (FE-GATE-010) |
operations/adapter-remediation-ledger.md, operations/adapter-remediation-dispositions.json |
check:remediation-ledger (게이트 밖. 이유는 config/ci/ungated-scripts.json) |
2. 목표 설계
설계와 결정 기록이다. 구현된 부분과 계획이 한 문서에 섞여 있다. 행마다 상태 값을 본다.
- 런타임 capability 결정의 정본:
architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md - 상태 원장:
architecture/browser-data-capability-completion-ledger.md - 전체 검토와 로드맵:
architecture/frontend-platform-capability-review.md,architecture/frontend-platform-implementation-roadmap.md - 포트·경계·데이터 흐름:
architecture/frontend-ports-adapters-and-boundaries.md,architecture/typescript-state-and-data-flow.md,architecture/routing-pages-and-patterns.md - API와 서버 상태:
architecture/api-contract-schema-mapper-and-server-state.md,architecture/backend-api-and-server-state-contract.md,architecture/protobuf-browser-transport-and-rest-gateway.md - 브라우저 데이터:
architecture/client-cache-and-storage.md,architecture/browser-file-and-origin-storage.md,architecture/presigned-transfer-and-image-cdn.md,architecture/server-file-capability-infrastructure.md - 실시간:
architecture/realtime-events-web-push-and-bounded-polling.md - 디자인 시스템과 테스트 전략:
styling/design-system-platform.md,testing/frontend-platform-testing-strategy.md - 결정 기록(ADR):
architecture/decisions/VD-*.md
3. 작업 이력·리뷰
템플릿을 만들면서 쓴 계획, 리뷰, 작업 추적이다. 현재 계약이 아니다.
복사한 프로젝트는 지워도 된다. 지울 때 남길 파일은 README.md의
"Files you can delete after copying" 절에 있다.
| 경로 | 내용 |
|---|---|
superpowers/ |
과거 작업 계획과 스펙 |
reviews/ |
리뷰 결과와 리뷰 가이드. reviews/adapters/INVENTORY.md만 게이트가 읽는다 |
../SPEC.md, ../tasks/ |
2026-09-25 리뷰 수정 라운드의 요구사항과 작업 목록. 이 라운드가 쓰는 중이라 docs/ 밖에 그대로 둔다 |