문제
fix/r1103-http는 짝 백엔드 계약 pin을 bbe944bd에 두었다. 그 뒤 백엔드에
70fb80bf(늦게 끝난 멱등 실행 기록)와 c508b1ba(회복 필요 응답 안내)가
들어왔다. 새 `check:backend-contract-drift`가 §2의 500
IDEMPOTENCY_RECOVERY_REQUIRED 행 변경을 알린다. 전에는 "재전송도
재실행도 안전하지 않다"였고, 지금은 "자동 재시도하지 않는다. 같은 키
재전송은 안전하다"다.
고른 방법
- pin과 답 표 JSON의 기준을 c508b1ba 전체 SHA로 옮기고,
IDEMPOTENCY_RECOVERY_REQUIRED의 sameKeyResend를 true로 바꾼다.
- 프론트 판정은 바꾸지 않는다. 이 code는 이미 MAYBE_APPLIED이고 키를
붙들며 자동 재전송하지 않는다. 결과 불명 화면의 같은 키 재전송은 새
문장과 맞는다.
- 6.1절이 인용하는 IdempotencyExecutor를 c508b1ba에서 다시 읽었다.
처리 중·불일치 판정은 그대로 action 전이고 줄 번호만 옮겼다
(127-130, 166-169, 267).
위험·한계
- c508b1ba에서는 §1·§2·§4와 IdempotencyExecutor만 다시 대조했다.
나머지 6.1절 파일은 bbe944bd 판독 그대로다(두 커밋 사이에 바뀌지
않았다).
검증
- check:backend-contract-drift --backend <백엔드 checkout>: pin과 HEAD가
같다.
- tests/unit/backend-contract-pin.test.ts 10건, verify:documentation
PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-06, README.md 10.6
문제: download 정책 registry는 safeExtension의 형식만 본다. 파일명
금지 목록(.exe, .html, .js 등)은 사용자가 준 이름에만 쓴다
(1101/02-02). 그래서 mediaType application/pdf + safeExtension .exe
정책이 조립되고, invoice.pdf가 invoice.exe로 browser handoff된다
(리뷰 E-7).
고른 방법: snapshotDownload가 금지 목록에 있거나 그것으로 끝나는
(.tar.js) safeExtension을 다른 정책 오류와 같이 TypeError로 거절한다.
목록은 file-policy.ts의 DEFAULT_FORBIDDEN_EXTENSIONS 하나를 쓰고,
isForbiddenDownloadExtension으로 내보낸다. browser-managed capability는
정책과 같은 safeExtension이어야 하므로 그 경로도 함께 막힌다.
버린 대안: media type과 확장자 짝 표를 두는 것. 표를 누가 소유할지
정해야 하고 범위가 크다. 이번에는 하지 않았다.
위험·한계: 이 확장자를 쓰던 다운스트림 정책은 조립 때 실패한다(보안
강화 방향). media type과 확장자가 서로 맞는지는 여전히 보지 않는다
(설계 문서에 적었다). file-transfer 번들 56,068 → 56,100 / 57,800 gzip B.
검증:
- RED: browser-file-policy-registry.test.ts 새 3건(.exe, .HTML, .tar.js)이
throw 없음으로 실패.
- GREEN: browser-files 단위 5파일 + tests/recipes 98건 통과.
check:types, 바꾼 파일 eslint, check:optional-recipes:source PASS,
verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 1101/02-02
문제: layers.md와 .dependency-cruiser.json 규칙 주석은 kernel
(src/adapters/platform/**)을 "clock, abort primitive, capacity guard"로만
적는다(0929/05-08). 실제 폴더에는 IndexedDB 연결·트랜잭션, Retry-After,
JSON member scanner와 bootstrap만 쓰는 lifecycle runtime·mutation intent
factory까지 10개 파일이 있다. 편입 기준("must never own")은
indexeddb-connection.ts 머리 주석에만 있어, 폴더에 무엇을 넣어도 되는지
문서로는 알 수 없다.
고른 방법: 리뷰 5.3절 (b). 두 곳의 설명을 실제 목록으로 고치고, 공유
메커니즘과 bootstrap 전용 서비스를 나눠 적고, 기준이 있는 위치를
가리킨다. 파일을 옮기는 (c)·(d)는 하지 않았다(1101/05-04, 남음).
위험·한계: 문서와 규칙 주석만 바꾼다. 규칙 동작은 같다. 폴더에 무엇을
넣을지를 기계가 보지 않는 것은 그대로다.
검증: check:architecture, verify:documentation 통과. bootstrap 밖에서
lifecycle·mutation intent factory를 쓰는 곳이 없음을 grep으로 확인했다.
Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 0929/05-08
문제: 두 템플릿을 짝으로 쓰면 파일 업로드 경로가 없다. 프론트 업로드
레시피는 PRESIGNED_MULTIPART_V1 서버를 가정하는데 짝 백엔드는 그 코드를
지웠고, 짝 백엔드 Fileserver(POST /v1/files)를 부를 프론트 client는 없다.
src 전체에 multipart 요청을 만드는 코드가 없다.
고친 방법(리뷰 D1 (나-1)): src/adapters/http/fileserver-upload.ts에
createFileserverUploadClient를 둔다. 백엔드 bbe944bd 계약 그대로다.
- 입력은 FileContentPort.openSource가 주는 FileByteSource다. 바이트를 한
번 읽어 multipart 본문(파트 이름 file, RFC 7578, 파일 이름은 HTML 폼
인코더처럼 escape)을 직접 만든다. File·Blob은 이 adapter에 들어오지
않는다(eslint browser-data 경계). 선언 크기가 maxFileBytes보다 크면 읽기
전에 거절하고, 읽는 중에 넘어도 멈춘다. 선언 크기가 있으면 본문 버퍼
하나에 바로 쓴다.
- 전송 규칙은 레시피와 V3 실행기와 같다. credentials는 인증 프로필이
정하고, 자격 증명 헤더는 admitCredentialHeaders로 프로필에 맞춰 받는다.
redirect "error", no-referrer, no-store, 응답 본문 상한, 바이트에 비례한
deadline 하나, 호출자 abort(커널 createAbortableOperation).
- 성공: 201 READY / 202 그 밖의 state를 Envelope에서 읽는다. 201과 202의
state가 맞지 않거나 size가 보낸 바이트와 다르면 SCHEMA_MISMATCH,
APPLIED_CONFIRMED.
- 실패: backend-envelope.ts의 readFailureEnvelope와 envelopeFailureReading을
그대로 쓴다. 효과 판정은 Fileserver 계약을 따른다. details.ambiguous,
AMBIGUOUS_COMPLETION, IDEMPOTENT_IN_FLIGHT, IDEMPOTENCY_COMPLETION_UNKNOWN은
MAYBE_APPLIED. 그 밖의 4xx는 NOT_APPLIED(백엔드 UploadFile use case가
모호하지 않은 실패에서 업로드를 취소한다). 5xx는 이름 붙인 Fileserver
code만 NOT_APPLIED이고 나머지는 MAYBE_APPLIED. 보낸 뒤 네트워크 실패·
시간 초과·abort도 MAYBE_APPLIED. Envelope의 retryable:false와 상한(기본
30초)을 넘는 Retry-After는 retryable을 false로 만든다(01-02와 같은 규칙).
- Idempotency-Key 헤더를 보낸다. client는 스스로 다시 보내지 않는다.
위치를 http adapter로 고른 이유: Envelope 해석(backend-envelope.ts), 자격
증명 admission(http-contract-bridge.ts), bounded reader를 adapter 안
import로 다시 쓴다. 새 adapter 사이 import 예외가 필요 없다. 바꾼 http
파일은 index.ts의 export 한 묶음뿐이다.
버린 대안:
- backend-envelope.ts를 커널(src/adapters/platform/)로 옮기고 client를
browser-transfer에 둔다. 다른 작업이 지금 고치는 파일을 옮겨야 하고,
커널은 제품 중립 primitive 자리인데 백엔드 짝 정책이 들어간다.
file-transfer 레시피 예산 여유도 1.7KB뿐이고, 이 client는 presigned
레시피와 무관한데 그 제거 드릴에 함께 지워진다.
- browser-transfer에 Envelope 파서를 하나 더 둔다. 갈라진 사본이다.
- V3 실행기에 multipart 본문을 더한다. 1,900줄짜리 실행기를 다른 작업과
동시에 크게 고쳐야 한다.
- FormData와 Blob을 쓴다. http adapter는 File·Blob을 쓸 수 없고(eslint),
기능은 Blob을 갖지 않는다.
조립: 제품이 product-composition.ts에서 client 재료
(FileserverUploadClientDependencies)를 capability로 넘기고, 기능 adapter가
createFileserverUploadClient를 부른다. 그래서 템플릿 boot 번들에는 들지
않는다. 매뉴얼 02 결정표 7절, patterns.md, 두 architecture 문서, 레시피
fallback이 이 경로를 가리킨다. adapter INVENTORY와 상세 리뷰 표에 행을
더했다(번호는 끝에 141로 붙였다).
위험·한계:
- 재개가 없다. 파일 전체를 메모리에 한 번 읽는다(maxFileBytes까지). tus
client는 없다.
- 짝 백엔드 bbe944bd의 POST /v1/files는 멱등 키를 읽지 않는다
(NOT_IDEMPOTENT). MAYBE_APPLIED 뒤 같은 키로 다시 보내도 파일이 두 개
생길 수 있다. 매뉴얼에 적었다.
- 효과 판정 표(NOT_APPLIED_5XX_CODES, MAYBE_APPLIED_CODES)는 백엔드
bbe944bd 기준이다. 어긋남을 알리는 검사는 없다(12-06과 같은 종류).
- 실제 짝 백엔드를 띄운 업로드는 하지 않았다. 테스트는 계약대로 답하는
MSW다. 실제 브라우저(Playwright)에서도 돌리지 않았다.
- 템플릿 기본 product-composition.ts가 자격 증명 owner를 노출하지 않으므로,
템플릿 세션(EXTERNAL_BEARER)으로 올리려면 제품이 자기 credential
provider를 써야 한다.
검증:
- tests/integration/fileserver-upload.test.ts 48건 통과(201/202 본문,
Envelope 실패 16종, 409 IDEMPOTENT_IN_FLIGHT + Retry-After 2, 상한 밖
Retry-After, 보낸 뒤 네트워크 실패 뒤 같은 키 재전송, 시간 초과, abort,
자격 증명 거절, 크기·입력 거절). multipart 본문은 undici FormData
파서로 다시 읽어 확인했다.
- 변이 7건(4xx 판정, ambiguous 무시, 상한 무시, credentials 고정, 키 누락,
201/202 state 검사 제거, Envelope retryable 무시) 모두 실패를 만들었다.
- check:types, lint(바꾼 파일), check:architecture, check:adapter-inventory,
verify:documentation, check:registries, check:ci 통과
- check:bundle PASS: initial JS 201,921 / 204,800 gzip bytes. 빌드 산출물
어디에도 client 코드가 없다(dist grep). check:optional-recipes:source PASS
(file-transfer 56,082 / 57,800)
Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 01-01
문제
짝 백엔드 계약의 기준 커밋은 계약 문서의 문장(백엔드 5786126c)뿐이고, 이
SHA를 읽는 코드·설정·테스트가 없다. 쓰기 전 거절 표 REFUSED_BEFORE_WRITE와
5xx 판정은 백엔드 http-contract.md §2를 손으로 옮긴 것이다. 리뷰 중 백엔드에
bbe944bd가 들어와 503 IDEMPOTENCY_COMPLETION_UNKNOWN이 새로 생겼는데 프론트의
어떤 검사도 알리지 않았다(README 10.6).
고른 방법 (결정 D6 (1)+(2))
- config/contracts/backend-contract-pin.json: repo, 전체 SHA(bbe944bd), 대조한
문서와 절(§1·§2·§4), 프론트 쪽 계약 절·판정 파일, 담당.
- config/contracts/backend-idempotency-answers.json: 백엔드 §2 표 여섯 행과
§4 REQUEST_TIMEOUT을 code·status·쓰기 전 거절·같은 키 재전송 열로 옮겼다.
백엔드가 문서에 적은 사실만 담는다.
- tests/unit/backend-contract-pin.test.ts: 두 JSON의 모양과 같은 SHA를
확인하고, 답마다 프론트 판정이 그 두 열에서 나오는 값인지(쓰기 전 거절이면서
같은 키 재전송이 아니면 NOT_APPLIED, 아니면 MAYBE_APPLIED, 자동 재전송은
둘 다 참일 때만) 본다. 반대로 프론트 표의 행이 모두 이 답 표나 6.1절
읽기(VALIDATION_FAILED)로 뒷받침되는지 본다. 그래서 백엔드 표에 행이
늘거나 status가 바뀐 JSON을 넣으면 실패한다.
- scripts/check-backend-contract-drift.ts(check:backend-contract-drift):
형제 디렉터리(또는 --backend)의 백엔드 checkout이 pin 뒤에 http-contract.md를
바꿨는지 알리고 바뀐 표 행을 보인다. CI에는 백엔드가 없어 게이트 밖이다.
ungated-scripts.json에 이유를 적었다.
- 계약 문서 4.1·6절의 기준 커밋을 bbe944bd와 pin 파일로 옮겼다. 6.1절 표는
5786126c..bbe944bd 사이 바뀐 백엔드 파일 다섯을 다시 읽었다. 판정은 같고
줄 번호만 옮겼다(IdempotencyExecutor, GlobalExceptionHandler →
HttpStatusErrorCodes, FailureCategory, PersistenceExceptionTranslator).
버린 대안
- 백엔드 error-codes.yaml과 문서 다이제스트를 기록: 다이제스트는 바뀐 것만
알리고 무엇을 고칠지 말하지 않는다.
- 백엔드가 계약 패키지를 발행: 백엔드 빌드에 JS 발행이 생긴다. 지금 규모에는
pin과 표가 작다.
위험·한계
- 답 표 JSON은 사람이 백엔드 문서에서 옮긴다. 옮기는 실수는 drift 스크립트와
리뷰가 잡는다. 백엔드 쪽이 같은 JSON을 자기 레지스트리와 대조하는 일은
백엔드 저장소 몫이다.
- 백엔드 HEAD는 이미 pin 뒤로 갔다(지금 c508b1ba). http-contract.md §2의 500
IDEMPOTENCY_RECOVERY_REQUIRED 행이 "같은 키 재전송은 안전하다"로 바뀌었다.
프론트 판정(MAYBE_APPLIED, 자동 재전송 없음, 사용자 재전송은 같은 키)은 그
문장과도 맞는다. pin은 지시대로 bbe944bd에 두었다.
검증
- 새 테스트 10건 통과. 변이 4종 검출: 답 표에 503 새 code 행 추가, 프론트
표에서 COMPLETION_UNKNOWN 제거, 프론트 표에 근거 없는 400 BAD_PARAMETER
추가, 답 표의 RECOVERY_REQUIRED status 변경.
- check:backend-contract-drift: worktree에서 skipped(exit 0), 실제 백엔드
checkout으로 exit 1과 바뀐 RECOVERY_REQUIRED 행 출력.
- test:unit 178파일 2,645건, check:ci, check:types, eslint,
verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-06
Refs: docs/reviews/2026-11-03-maturity-review/README.md 10.6
문제: client-cache-and-storage.md의 cross-context 조립 설명이
runtime-adapters.ts·server-state-scope-runtime.ts·tanstack-cache-
coordinator.ts의 줄 번호를 가리키는데, 네 곳 모두 다른 코드로 밀렸다
(0929/02-04). 문서 줄 번호를 보는 검사는 없어서 다음 변경에도 또 밀린다.
browser-file-and-origin-storage.md의 participant 등록 예 줄 번호는 앞
커밋(02-01)이 이미 고쳤다.
고른 방법: 줄 번호 대신 함수·호출 이름을 적는다(1101/05-05와 같은
방식). 리뷰가 맞다고 확인한 다른 줄 번호는 그대로 둔다.
위험·한계: 문서만 바꾼다. 다른 문서의 줄 번호 참조는 건드리지 않았다.
검증: verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 0929/02-04
문제: 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
문제
실행 관측(HttpExecutionObservation)에는 effect가 있지만 조립 루트 projector는
진단에도 텔레메트리에도 싣지 않는다. 진단 허용 키에 effect가 없고 status는
묶음(4xx)만 남는다. 그래서 진단 버퍼에서 결과 불명과 적용 안 됨, 처리 중
409와 업무 409, 503 IDEMPOTENCY_UNAVAILABLE 재전송 소진이 같은 줄이 된다.
텔레메트리로는 결과 불명 쓰기의 비율을 셀 수 없다. 03-01이 고쳐져도 업무
거절은 선언 전까지 결과 불명이라 이 구분이 필요하다.
고른 방법
- effect_certainty 키: 진단·텔레메트리(api.request.failed 선택 속성) 모두
HttpEffectCertainty 다섯 값만 받는 닫힌 value policy(isEffectCertainty)를
쓴다. cardinality는 bounded. projector가 두 sink에 싣는다.
- 결과 불명 원인: Envelope 명령에서 표가 MAYBE_APPLIED를 줄 때 닫힌
UnknownEffectReason을 진단 reason으로 싣는다. IN_FLIGHT(409 처리 중),
IDEMPOTENCY_UNAVAILABLE, COMPLETION_UNKNOWN, RECOVERY_REQUIRED,
SERVER_TIMEOUT(503 REQUEST_TIMEOUT), STAGE_UNKNOWN(단계를 모르는 400·409·
422). 텔레메트리에는 싣지 않는다(VD-07: reason은 진단 전용).
- VD-07 5-1의 projector 키 목록과 reason 값 목록을 고쳤다. 남아 있던
"effect_certainty는 필요해지면 더한다" 문장은 지웠다.
버린 대안
- 백엔드 error.code 원문을 진단에 싣기: cardinality 결정(1101 README 14.6)이
먼저다. 닫힌 원인 집합이면 그 결정과 무관하다.
- 원인도 텔레메트리에: 텔레메트리 reason은 전달 실패용 닫힌 집합이라 뜻이
섞인다. 비율은 effect_certainty로 센다.
위험·한계
- Envelope가 아닌 operation의 MAYBE_APPLIED는 원인 없이 effect만 남는다.
응답을 잃은 경우는 outcome(TRANSPORT_FAILURE)이 원인을 보인다.
- 텔레메트리 수집기가 속성 목록을 고정해 두었다면 새 선택 속성을 받도록
맞춰야 한다.
검증
- RED: envelope 진단 9행(effect·reason), observability 1건, cardinality
8건 실패.
- GREEN: 처리 중 409는 reason IN_FLIGHT, 업무 409는 STAGE_UNKNOWN, 둘 다
effect_certainty MAYBE_APPLIED. 진단 투영이 모두 통과한다.
tests/unit·integration·component·features·contract·runtime-schema·platform
282파일 중 281파일 통과. 남은 1건은 provider-guardian-transaction의 inotify
한도(ENOSPC)로 이 변경과 무관하다.
- check:diagnostics, check:types, lint, verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-05
문제: browser-files runtime은 세션을 모르고, 닫는 수단은
runtime.dispose() 하나다. 설계 문서는 로그아웃·계정 전환에 "server-state
scope reset participant로 dispose()를 등록하라"며 템플릿 소유 파일
runtime-adapters.ts를 가리키는데, 매뉴얼은 제품이 그 파일을 고치지
않는다고 한다(09-02). 제품 확장 지점 composeProduct는 부팅 때 한 번
불리고, context에 participant 등록도 lifecycle 구독도 없다. 그래서
연결하지 않으면 이전 사용자가 고른 File, preview blob URL, 진행 중
download가 다음 세션까지 남는다(공유 기기에서 이전 사용자 파일이
메모리와 다운로드 폴더에 남을 수 있다).
고른 방법(리뷰 5.3절 (다) + 레시피 예제):
- ProductComposition에 선택 칸 scopeParticipants(ProductScopeParticipant:
label, close)를 둔다. 템플릿은 scope reset의 §10.6 10단계(offline
lease 해제) 자리에 "product" participant 하나를 두고, composeProduct가
돌려준 것을 순서대로 부른다. 하나가 실패해도 나머지를 부르고, 실패가
있으면 template participant와 같이 READY로 가지 않는다(FAILED).
composeProduct는 scope가 생긴 뒤 불리므로(context가 fence를 쓴다) 이
자리를 미리 만들고 나중에 채운다.
- recipes/frontend-capabilities/browser-file-session-capability.ts:
기능에는 runtime 대신 current() getter를 주고, participant가 dispose한
뒤 다음 호출에서 새 runtime을 만든다. indexeddb 레시피와 같은 자리다.
- 설계 문서와 매뉴얼 03 C절이 이 방법을 가리킨다. 제거 드릴이 새
레시피 파일도 같이 지운다.
버린 대안: (가) 문서만 고침 — feature presentation은 adapter를 만들 수
없어 제품마다 factory를 다시 설계한다. (나) context에 lifecycle 구독
위임 — FENCED → participant → READY 순서와 "실패는 READY를 막는다"를
제품이 직접 지켜야 한다. (라) runtime이 세대 AbortSignal을 받음 —
adapter가 세대를 알게 되고 다른 opt-in runtime도 따로 받아야 한다.
위험·한계:
- 제품 계약 표면이 하나 는다(선택 칸이라 기존 제품 파일은 그대로
컴파일된다, [계약]).
- 기능은 current()를 작업마다 불러야 한다. 이전 세대에서 받은 runtime을
들고 있으면 UNAVAILABLE을 받는다. FENCED 동안 current()를 부르면 다음
세대 runtime이 미리 만들어진다(빈 runtime이라 이전 사용자 데이터는
없다).
- app dispose(infrastructure.dispose)는 제품 participant를 부르지 않는다.
- 실제 브라우저 2탭 로그아웃 E2E는 없다(조립된 화면이 없다).
- scripts/test-browser-file-storage-runtime-removal.ts는 02-06 담당 작업도
고칠 수 있는 파일이다. runtimePaths에 한 줄만 더했다.
검증:
- RED: tests/recipes/browser-file-session-capability.test.ts가 계정 전환
뒤에도 이전 runtime의 readRange가 ok로 실패.
- GREEN: 같은 테스트에서 계정 전환 뒤 ① 이전 runtime readRange
UNAVAILABLE ② 진행 중 bounded download ABORTED, handoff 0회 ③ 새 세대
runtime의 파일 선택 SELECTED. tests/unit/runtime-adapters-product-scope-
participants.test.ts 2건(순서, 실패 시 FAILED와 나머지 실행).
- 변이 4개(등록 누락, 실패 삼킴, 첫 실패에서 멈춤, 레시피 dispose 누락)
모두 새 테스트가 잡았다.
- runtime-adapters 관련 unit 3파일 + tests/recipes 47건 통과.
check:types, 바꾼 파일 eslint, check:architecture, verify:documentation
통과.
Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 02-01
문제: 제품이 짝 백엔드에 처음 붙을 때 볼 문서가 없다. owner 작성자는
SessionGateway 주석, subject·scope fence 규칙, R-3.2, recover 규약을
여러 파일에서 모아야 하고, 백엔드가 무엇을 주고 무엇을 안 주는지(realm의
브라우저 client, 로그인·로그아웃·세션 엔드포인트)는 백엔드 코드를 읽어야
안다.
고른 방법: docs/manual/04-paired-backend-session.md를 새로 둔다.
- 두 모드 비교표와 근거 위치(백엔드 bbe944bd의 SecurityConfig,
security.yml, application-local.yml, realm JSON).
- 공통 준비: AUTH_MODE external, 백엔드 local CORS 출처
http://localhost:3000에 맞춘 dev 포트, owner context 필드, recipe는
복사(import 금지).
- jwt: 흐름도, realm에 더할 public client JSON(audience mapper 포함),
제품 설정 키 OIDC_ISSUER·OIDC_CLIENT_ID, product-composition 예시,
하지 않는 것(새로고침 로그아웃, ID token 서명, id_token_hint).
- redis-session: 흐름도, 제품이 더할 엔드포인트 셋과 CSRF 토큰 읽기,
프로필을 product-contracts.ts에 옮겨 적는 이유, 예시, 같은 host 조건.
- 상태 전이 표, 확인 방법(실제 백엔드 e2e는 아직 없음), 증상별 원인.
매뉴얼 README·02 §5, starter-experience·foundation·optional-adapter-
recipes에는 위치만 가리키는 줄을 더했다. 백엔드 표는 복사하지 않고 위치만
적었다(매뉴얼 README 규칙).
위험·한계: 백엔드 설정이 바뀌면 이 문서가 낡는다. 기준 커밋을 문서
첫머리에 적었다. Keycloak client JSON은 실제 Keycloak에 넣어 보지 않았다.
검증: verify:documentation PASS_SCOPED(새 문서와 고친 문서 모두 경로·
명령·게이트 ID 누락 0).
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-03
문제
AppFailure와 createFailure는 traceId를 받는다. 이를 채우던 곳은 V2
client.ts의 Envelope meta.traceId였고, 048f490이 V2를 지운 뒤 src에서
traceId를 넘기는 곳이 없다. 빈 칸을 믿고 만든 화면·진단 코드는 늘
undefined를 받는다. 짝 백엔드는 모든 실패 Envelope의 meta에 W3C trace id를
싣는다(http-contract.md §1).
고른 방법
- readFailureEnvelope가 error와 함께 meta.traceId를 돌려준다. 값은 이미
meta 스키마의 id 문법([A-Za-z0-9._:-]{1,128})을 통과한 것이다.
- 실행기가 그 값을 PROBLEM 결과의 SafeResponseMetadata.traceReference에
싣고, 바인딩이 AppFailure.traceId로 옮긴다. requestId 경로(반사 헤더 →
보낸 id)는 그대로다.
- 계약 문서 5절의 correlation 문단에 한 줄 더했다.
버린 대안
traceId를 타입에서 지우기(리뷰의 다른 선택지): 다운스트림이 쓰는지 확인이
필요하고, 백엔드가 이미 주는 지원용 id를 버린다.
위험·한계
- Envelope operation의 실패 응답만 채운다. 성공 뒤 매핑 실패, 전송 실패,
Envelope 없는 operation은 traceId가 없다.
- 텔레메트리에는 싣지 않는다(요청 단위 값).
- 같은 발견의 VD-23 401 문장은 다른 작업 몫이라 건드리지 않았다.
검증
- RED: envelope 통합 1건 실패(404 실패의 traceId 없음).
- GREEN: meta.traceId가 있으면 그 값, 없으면 칸 없음. tests/unit·
integration·component·features·contract·runtime-schema 253파일 중 252파일
통과. 남은 1건(provider-guardian-transaction "cleans a linked raw inode")은
이 기계의 inotify 한도(ENOSPC watch)로 단독 실행에서도 실패하며 이 변경과
무관하다.
- check:types, lint, verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-06
문제
짝 백엔드는 페이지 목록의 전체 수·페이지 번호를 meta.page(number·size·
total·sort)에 싣는다(http-contract.md §1). 프론트 Envelope 읽기는 meta에서
id 셋만 남기고 data만 꺼낸다. 그래서 목록 기능은 첫 페이지(기본 20개)만 받고
전체 수를 모른다. 생성된 목록 화면의 "총 N개 항목"은 배열 길이라 페이지
크기를 전체 수처럼 보인다(리뷰 실험 X-G). 우회하려면 responseEnvelope를 빼야
하고, 그러면 Envelope 실패 판정을 함께 잃는다.
고른 방법
- backend-envelope.ts: meta에 page 스키마(정수, number·total 0 이상,
size 1~100, sort 문자열 또는 null). 범위 밖이면 page만 버리고 응답은 읽는다.
readSuccessEnvelope가 data와 함께 page를 돌려준다.
- 실행기의 SUCCESS 결과에 선택 칸 page. outputValidator는 지금처럼 data만
본다.
- 바인딩: mapSuccess(value, context)의 두 번째 인자 FeatureHttpSuccessContext
{ page? }. 한 인자짜리 기존 mapSuccess는 그대로 맞는다.
- 배럴에서 EnvelopePage·FeatureHttpSuccessContext 타입을 낸다.
- 계약 문서 4.1절에 meta.page 경로와 "bulk results는 지원하지 않는다", 7절에
"짝 백엔드는 offset meta.page"를 적었다.
버린 대안
- outputValidator에 { data, page }를 넘기기: 기존 기능 스키마가 모두 깨진다.
- 기능 스키마가 Envelope 전체를 읽기: 실패 판정을 잃는다.
- page가 범위 밖이면 응답 전체를 거절: meta의 모르는 키는 무시한다는 백엔드
§1 규칙과 어긋난다.
위험·한계
- 생성기(create-feature.ts)의 목록 화면은 아직 배열 길이를 보인다. 생성기
담당 작업이 page.total을 쓰도록 이어 받는다.
- bulk는 지원하지 않고 문서로만 알린다.
검증
- RED: envelope 통합 3건 실패(mapSuccess가 page를 받지 못함, 정렬 없는
page 2건).
- GREEN: 같은 파일 51건 통과. 범위 밖 page 3건(size 500, number -1, total
1.5)은 page 없이 SUCCESS. tests/unit·integration·component·features·
contract·runtime-schema 253파일 3,209건 통과.
- check:types, lint, check:architecture, verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-02
문제: 프론트 업로드 레시피(PRESIGNED_MULTIPART_V1, 브라우저가 object
store에 직접 PUT)를 받는 서버가 짝 백엔드 템플릿에 없다. 짝 백엔드는
2026-09-25에 presigned·direct multipart 코드를 지웠고, 파일은 자기
Fileserver가 직접 받는다(POST /v1/files, POST /v1/files:raw, tus). 그런데
서버 handoff 문서는 아직 "서버 구현 대기", "이후 서버 template에서 구현"
이라고 적고, docs/manual에는 업로드 언급이 없다. 팀은 조립 단계에서야
짝이 아님을 안다.
고친 방법(리뷰 D1 (다)):
- server-file-capability-infrastructure.md 상태 줄을 "짝 백엔드 템플릿은
구현하지 않음(2026-09-25 제거)"으로, 대상을 "제품 backend가 직접 구현"
으로 고치고 짝 아님 안내를 머리에 둔다.
- presigned-transfer-and-image-cdn.md 머리에 같은 안내를 둔다. presigned
다운로드와 private Image CDN descriptor 발급 서버도 짝 백엔드에 없다.
- 레시피 카탈로그 file-transfer의 fallback에 짝 백엔드 경로(Fileserver
POST /v1/files)를 적는다.
- docs/manual/02-decision-tables.md에 7절 "파일 업로드"를 더한다. 두 경로
비교와 고르는 기준이다. 매뉴얼 README의 목차 줄도 고친다.
위험·한계: 문서만 바꾼다. 짝 백엔드로 파일을 올리는 프론트 client는 이
커밋에 없다(다음 커밋, D1 (나-1)). 백엔드 매뉴얼에 같은 안내를 적는 일은
백엔드 repo 몫이라 하지 않았다.
검증:
- verify:documentation PASS_SCOPED
- check:optional-recipes:source PASS (file-transfer 56,084/57,800)
Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 01-01
문제
zod-is-reached-through-contracts-zod 규칙의 to.path가 ^zod$다. src 파일이
"zod/v4"를 import하면 check:architecture가 rc=0으로 통과한다(실험 Z1). 그
모듈은 src/contracts/zod.ts의 jitless 설정보다 먼저 스키마를 만들 수 있고,
그러면 운영 CSP가 zod의 Function 탐침을 부팅마다 보고한다(F-7).
고른 방법
to.path를 ^zod(/|$)로 넓힌다. 그래프 fixture에 "zod/v4"를 import하는 파일과
그것이 거절되는지 보는 회귀 검사를 더했다. layers.md 규칙 표도 고쳤다.
버린 대안
- eslint no-restricted-imports에 zod 패턴 추가: 같은 규칙을 두 도구에
둔다. 경계 규칙은 dependency-cruiser가 정본이다.
위험·한계
- src 안에 zod 하위 경로 import는 지금 없다(grep). 다운스트림이 쓰고
있으면 check:architecture가 실패한다. src/contracts/zod.ts의 z로 바꾼다.
검증
- 수정 뒤: 참조 기능 스키마 파일 import를 "zod/v4"로 바꾸면
"Architecture violation [zod-is-reached-through-contracts-zod]: ... ->
zod/v4"로 실패, "zod"도 실패.
- 규칙을 ^zod$로 되돌리면 새 회귀 검사 "zod subpath import outside
src/contracts/zod.ts is rejected"가 실패한다.
- check:architecture(29 regression checks PASS), check:types, eslint,
verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md P-07-06
문제
Envelope operation의 400·409·422는 백엔드 표의 세 code만 NOT_APPLIED이고
나머지는 모두 MAYBE_APPLIED다. 기능의 classifyProblem은 이를 바꿀 수 없다.
짝 백엔드 생성 기능의 create는 이름 규칙을 트랜잭션 전에 검사하고 400
<FEATURE>_INVALID를 준다. 그런데 폼은 "변경 결과를 확인할 수 없습니다"를
띄우고 저장 버튼을 끈다. 입력을 고쳐도 다시 저장할 수 없다(리뷰 실험
X-A·X-B). 401·403·429는 classifyStatus로 operation이 정할 수 있는데
400·409·422는 정할 자리가 없다.
고른 방법 (결정 D2 ①)
- CommandEffectDescriptor에 선택 칸 refusedBeforeWrite?: readonly string[].
표 밖 400·409·422가 이 목록의 code면 NOT_APPLIED다. 함수가 아니라 code
목록이라 리뷰할 수 있고, status 범위를 통째로 NOT_APPLIED로 만들 수 없다.
- 조립 검사(assertRefusedBeforeWrite): 목록은 Envelope operation에만,
code는 백엔드 문법, 중복 금지. IDEMPOTENT_*·IDEMPOTENCY_*는 거절한다
(409 IDEMPOTENT_IN_FLIGHT의 앞선 요청은 적용될 수 있다).
- 실행기도 같은 code와 표의 code(VALIDATION_FAILED 등)를 무시한다. 조립
없이 실행기를 부르는 경로의 fail-close다.
- 조립이 목록을 얼려 복사한다(LIVE-03). classifier는 지금처럼 참조로
두고, 설치본이 원본을 prototype으로 물려받아 classifier의 this가 그대로다.
- 매뉴얼 02 4절과 계약 문서 6.1절에 언제 적고 언제 적지 않는지,
<FEATURE>_INVALID 예와 거부 문구를 적었다.
버린 대안
- 표 밖 400 전체를 NOT_APPLIED: BAD_PARAMETER·MAPPING_FAILED는 쓰기 뒤에도
나온다.
- 분류기 판정 복원: 3261208이 버린 길. 400 전체를 NOT_APPLIED로 보는
분류기가 키 보호를 푼다.
- 결과 불명 화면에 "적용되지 않음" 버튼: 사용자가 모르고 누르면 새 키로
중복이 생긴다.
- 백엔드 단계 신호(error.applied): 두 repo 계약 변경이다(D2 ②).
위험·한계
- 쓰기 뒤에도 나오는 code를 잘못 적으면 결과 불명 요청이 새 키로 나가
중복이 생길 수 있다. 책임은 선언한 기능 작성자에게 간다. 매뉴얼이 백엔드
코드에서 던지는 곳을 확인한 code만 적으라고 한다.
- 생성기(scripts/create-feature.ts)는 이 칸을 아직 쓰지 않는다. 다른 작업이
이어 받는다.
- 결과 불명 화면이 거절 code의 문구를 보이는 것(08-01 (가))은 하지 않았다.
검증
- RED: 새 테스트 17건이 이 변경 전 소스에서 실패(조립 규칙 10, 판정 3,
envelope 통합 3, form-foundation 1).
- GREEN: tests/unit·integration·component·features·contract·runtime-schema
253파일 3,199건 통과. 폼: WORKLOG_INVALID를 선언하면 결과 unavailable,
저장 켜짐, 고친 값 저장 fetch 2회, 키 key-1 → key-2. 선언하지 않으면
effect-unknown, 저장 꺼짐, fetch 1회.
- 변이: 실행기의 멱등성·표 code 무시 제거, 조립의 멱등성 규칙 제거, 목록
복사 제거, 실행기가 목록을 넘기지 않음 모두 검출. 보존 조건 M5·M10·M24도
계속 검출.
- check:types, lint, check:registries, check:architecture,
verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-01
Refs: docs/reviews/2026-11-03-maturity-review/08-presentation.md 08-01
문제
catalog의 service-worker-pwa trigger는 "a measured offline-shell
requirement"를 설치 조건으로 적고 failureKinds에 offline-fallback이
있다. 레시피 표도 "install/offline shell"이다. 그러나 reference 워커는
navigation을 NETWORK_ONLY로 두고, 사전 캐시에 index.html을 넣지 않으며,
설계는 cached index.html fallback을 금지한다(closed deep design 18.8).
catalog를 보고 온 제품은 템플릿 파일을 고쳐야 한다는 것을 뒤늦게
알고, 이후 동기화마다 같은 파일에서 충돌한다(0929 리뷰의 memento 사례).
고른 방법
- 0929/06-03 최소 방향대로 주장을 설계에 맞춘다. trigger에서 오프라인
셸을 빼고 "navigation network-only, offline shell 없음, 별도 제품
capability"를 적는다. failureKinds의 offline-fallback을
offline-navigation-network-error로 바꾼다.
- 레시피 3절 표를 고치고, 같은 절에 졸업 경로(넘겨받는 파일 넷, 다시
증명할 e2e 단언과 성질, 동기화 충돌)를 적는다.
- 버린 대안: 선택 handler로 오프라인 셸 확장 지점을 만들기. 설계가
금지한 동작이고 재검토 조건(제품 요구)이 아직 없다.
위험·한계
- catalog 문구만 바뀐다. 오프라인 셸을 켜는 확장 지점은 여전히 없다.
검증
- json-schema 테스트 6건 통과, check:remediation-ledger·
check:optional-recipe-fixtures PASS, verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 2절 0929/06-03
문제
Service Worker를 켜는 유일한 방법은 src/features/installed-runtime-capabilities.ts의
SERVICE_WORKER 상수를 바꾸는 것이었다. 그 파일에는 "Product-owned." 표시가
없고, 매뉴얼 03 D절은 src/features/installed-*.ts를 고치지 말라고 한다.
매뉴얼대로 하면 SW를 켤 수 없고, 켜면 동기화마다 템플릿 파일을 손으로
병합한다. 템플릿 상태 설명과 제품 선택 상수가 한 블록에 섞여 있었다(1101/09-05).
고른 방법
리뷰의 최소 방향을 따른다.
- 선택 상수 넷(REALTIME, WEB_WORKERS, SERVICE_WORKER, OFFLINE_COMMANDS)을 제품
소유 src/features/product-capabilities.ts의
PRODUCT_RUNTIME_CAPABILITY_SELECTION으로 옮긴다. 09-02에서 만든 같은 새 제품
소유 파일이다. product-contracts.ts에 넣지 않은 이유: 계약 층(src/contracts)이
아니라 기능 카탈로그 옆의 선택이고, 템플릿은 복사 뒤 기존 제품 소유 파일에
칸을 더하지 않는다.
- installed-runtime-capabilities.ts는 템플릿 소유로 남고 그 선택을 검사
(validateRealtimeContributions, validateWebWorkerContributions)하고 투영만
한다. §3.5 설명과 템플릿 상태 설명은 여기에 남는다.
- 매뉴얼 03 C절에 "SW 켜기"를 넣었다. 조립 거절 메시지, e2e SW 빌드 도우미의
편집 대상(premise 1), 레시피·운영 문서, dependency-cruiser 주석의 경로를
새 파일로 바꿨다.
- 09-02 typecheck 테스트는 이제 출하된 product-capabilities.ts에 타입만 채우고
(선택은 유지), 복사 목록은 REMOVAL_FIXTURE_COPY_TARGETS 하나를 쓴다.
위험·한계
- 리뷰가 함께 제안한 composeProduct의 SW 연결 칸(blockers, observe)은 만들지
않았다. 그 연결은 여전히 템플릿 파일 create-runtime-composition.ts를 고쳐야
한다. 매뉴얼 "SW 켜기"에 적었다.
- 템플릿 안의 선택을 이미 바꾼 다운스트림은 값을 새 파일로 옮겨야 한다.
검증
- RED: tests/unit/product-runtime-capability-selection.test.ts 3건(선택이 제품
소유 파일에만 있음, 제품 SW 선택 투영, 잘못된 선택은 여전히 검사)이 수정 전
실패.
- 그 테스트, service-worker-build-output, optional-runtime-host,
runtime-composition-service-worker-telemetry, product-features,
product-extension-typecheck, runtime-adapters 통과.
- check:types, check:architecture, eslint, verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-05
문제
WebSocket 연결은 구독마다 1초 창에 maxEventsPerSecond(256, server가
알린 값과 작은 쪽)를 넘는 event가 오면 EVENT_RATE_EXCEEDED recovery를
요청하고 QUEUE_OVERFLOW로 닫는다. 이를 확인하는 테스트가 없어 검사를
꺼도 모든 테스트가 통과한다(리뷰 변이 R7, 두 라운드째). 설계 11절
상한표에도 행이 없다.
고른 방법
- 상한을 2로 낮춘 연결에서 2개 → 1초 뒤 2개(열림 유지) → 1개 더(닫힘,
EVENT_RATE_EXCEEDED)를 보내는 테스트 1건을 더한다. 창 초기화와 상한
값 출처까지 한 테스트가 본다.
- 설계 11절 상한표에 행 하나를 더한다.
위험·한계
- 동작은 바꾸지 않았다. 실제 서버 부하로는 확인하지 않았다.
검증
- 새 테스트 통과(websocket-connection 24건).
- 변이 3건 모두 검출: 상한 검사 끄기(R7), 1초 창 초기화 삭제, 협상된
상한 대신 256 고정.
- 바꾼 파일 eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 2절 1101/04-03
문제
heartbeatEligible()이 false면 WebSocket 연결은 HEARTBEAT를 보내지
않는다. 그러면 HEARTBEAT_ACK가 없고, 이벤트도 없는 조용한 stream은
유효 신호가 없어 reconnect 예산이 초기화되지 않는다(0929 실험 E7).
훅에 주석이 없어 채택자가 이 결과를 코드 두 곳(heartbeat 송신,
isReconnectAttemptResetEligible)을 같이 읽어야 안다.
고른 방법
- 0929/04-04의 최소 방향대로 훅 옆에 주석을 달고 설계 5.3 예산 문단에
같은 문장을 더한다. hidden 연결은 닫거나 visible 복귀 때 새 run을
만들라고 적는다. 동작은 바꾸지 않는다.
위험·한계
- 동작 변경이 없다. 주석이 코드와 어긋나면 잡는 검사는 없다.
검증
- 바꾼 파일 eslint 통과. 주석만 바꿨다.
Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 2절 0929/04-04
문제
Envelope 판정 표가 정하는 5xx는 503 IDEMPOTENCY_UNAVAILABLE 하나다. 짝
백엔드 http-contract.md가 직접 정한 다른 답 셋은 기능의 classifyProblem이
정한다.
- §2 500 IDEMPOTENCY_RECOVERY_REQUIRED: 이전 시도의 효과를 증명할 수 없다.
- §2 503 IDEMPOTENCY_COMPLETION_UNKNOWN(백엔드 bbe944bd): 작업은 돌았고
결과 기록이 실패했다. 같은 키로 나중에, 새 키 금지.
- §4 503 REQUEST_TIMEOUT: 비동기 요청이 시간을 넘겼고 처리가 계속될 수 있다.
분류기가 5xx를 NOT_APPLIED로 보면 셋 다 SERVER_FAILURE/NOT_APPLIED가 되고,
retryBudget이 있으면 실행기가 다시 보낸다. 폼은 "다시 시도"를 새 키로
연다(리뷰 실험 X-F). 백엔드가 "새 키 금지"라고 한 요청이다.
고른 방법
backend-envelope.ts에 MAYBE_APPLIED_ANSWERS(code → status)를 두고 IU와
같은 줄에 셋을 더했다. status와 code가 함께 맞을 때만 MAYBE_APPLIED다.
MAYBE_APPLIED는 retryHint를 끄므로 자동 재전송이 없고, 코디네이터가 키를
붙들어 결과 불명 화면의 재전송이 같은 키로 나간다. 자동 같은 키 재전송은
지금처럼 KEYED의 503 IU뿐이다.
버린 대안
RECOVERY_REQUIRED에 "재전송 불가" 표시를 실어 화면 버튼을 숨기기(리뷰 최소
개선의 뒷부분): 완료 기준 밖이고 바인딩·코디네이터·화면을 함께 바꾼다.
같은 키 재전송은 백엔드가 다시 실행하지 않고 같은 500이나 재생으로 답한다.
남은 문제로 보고한다.
위험·한계
500 DB_COMPLETION_UNKNOWN(백엔드 error-codes.yaml, http-contract.md 밖)은
넣지 않았다. 계속 분류기가 정한다.
검증
- RED: backend-envelope 단위 3건, envelope 통합 4건(LENIENT 분류기 세 code의
effect, retryBudget 2에서 fetch 1회·같은 키) 실패.
- GREEN: tests/unit·integration·component·features·contract 250파일
3,121건 통과. check:types:app·test, eslint, verify:documentation 통과.
- 매뉴얼 02 4절, 계약 문서 6.1절, descriptor 주석에 네 답을 적었다.
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-04
Refs: docs/reviews/2026-11-03-maturity-review/README.md 10.6
문제
제품 확장 지점이 실행 경로에서는 동작했지만 타입 검사 경로에서 막혔다.
(a) 문서대로 product-composition.ts에서 FeaturePlatformCapabilities를
보강하면 check:types:node가 실패했다. scripts 프로그램은 기능 코드를 끌어오지만
product-composition.ts는 끌어오지 않아 보강이 보이지 않았고, 오류는 기능
파일을 가리켰다. (b) 기본값 있는 제품 설정 키(.default()) 하나가 RuntimeConfig를
리터럴로 쓰는 템플릿 테스트 7개 파일의 타입을 깼다. 픽스처는 vi.mock이라 이
경로를 지나지 않았다.
고른 방법
- 제품 소유 빈 파일 src/features/product-capabilities.ts를 두고
FeaturePlatformCapabilities가 그 ProductFeaturePlatformCapabilities를
extends한다. feature-adapter-contribution.ts가 import하므로 기능을 보는 모든
프로그램에 들어간다. 문서만 "기능 파일 안에서 보강"으로 고치는 최소안은
capability 하나를 여러 기능이 쓸 때 보강 위치가 갈려 버렸다. 기존 제품 소유
파일에 칸을 더하지 않고 새 파일로 둔 이유: 템플릿은 복사 뒤 제품 소유 파일을
고치지 않으므로, 새 파일이어야 동기화 때 충돌 없이 들어간다.
- tests/helpers/runtime-config.ts의 testRuntimeConfig: 템플릿 키는 테스트가
쓰고, 제품 키는 실제 스키마(validateRuntimeConfig)로 기본값을 채운다. 템플릿
테스트 6개 파일이 이것을 쓰고, release-coherence는 문서 타입을 z.input으로
바꿨다. 제품 키를 모두 Partial로 하는 대안은 기본값 키에도 undefined 처리를
강요해 버렸다.
- tests/unit/product-extension-typecheck.test.ts: 복사본에 제품 소유 파일 세 개와
기능 하나를 실제 파일로 채우고 tsc app·node·test를 돈다.
- 문서: starter-experience 표, 매뉴얼 01·03·patterns·create-feature,
frontend-application-foundation, 계약 주석.
위험·한계
- 기본값 없는 필수 제품 키는 여전히 템플릿 테스트에서 실패한다(이제 타입이
아니라 helper가 이유를 적고 throw). 문서에 ".default() 또는 .optional()"을
적었다.
- product-composition.ts 안에서 이미 보강한 다운스트림은 보강을 새 파일로
옮겨야 node 검사가 통과한다.
검증
- RED: 새 typecheck 테스트가 수정 전 app·node(보강 미연결)와 test(템플릿
테스트 8건, E-PROD와 같은 위치)에서 실패.
- 수정 후 그 테스트와 영향받는 9개 테스트 파일 → 10 files / 83 tests 통과.
- check:types(tsc app·node·test), check:architecture, eslint,
verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-02
문제
realtime 레지스트리는 schemaCodecs·mappers·apiOperations 세 바인딩을
받아 event type과 checkpoint를 대조한다. V2 삭제(12f3bb7)로 기능의
runtimeSchemas·mappers 칸이 사라져 지금 출처가 있는 것은
apiOperations뿐이다. 레시피는 "제품 feature는 이 runtime에
schema/codec/query … 주입"이라고만 적어 조합자가 codec·mapper를 어디서
만드는지 알 수 없다.
고른 방법
- 리뷰의 최소 방향대로 레시피 Realtime 절에 세 바인딩의 출처를 적는다.
apiOperations는 loadInstalledFeatureRuntimeRegistries().apiOperations,
schemaCodecs는 V3 events[].payloadValidator·checkpoint outputValidator를
runtimeSchemaCodecFromValidator + composeRuntimeSchemaCodecs로,
mappers는 조합 코드의 BoundaryMapper + composeBoundaryMapperRegistry다.
등록 때 맞아야 하는 id(payloadSchemaId = validator schemaId =
mapper inputSchemaId)도 적었다(realtime-streams.ts 등록 검사).
- 버린 대안: 지금 기능 모듈에 realtimeMappers 칸을 더하거나 V3 events에서
event type을 뽑기. 공개 계약이 바뀌고, 04-02의 push 경로(STOMP hint면
delta mapper가 필요 없을 수 있음)를 고른 뒤 정하는 것이 맞다.
위험·한계
- 코드 변경이 없다. 같은 이벤트를 V3 events와 realtime 등록 두 곳에
적는 중복은 문서 규칙으로만 막는다.
검증
- verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 04-06
문제
짝 백엔드의 실시간 출구는 STOMP-over-SockJS 채널(/ws, /topic 구독 1개,
Map<String,String> 투영, 재전송 없음)과 raw WebSocket 라이브러리 API,
NDJSON·JSON text sequence writer다. 프론트 SSE 어댑터는
text/event-stream과 REALTIME_EVENT_V1 envelope을, WebSocket 어댑터는
subprotocol "realtime.v1"을 요구한다. 어느 repo에도 이 불일치와 지금
되는 경로가 적혀 있지 않아, 채택자가 두 repo를 다 읽어야 안다.
고른 방법
- 리뷰의 최소 방향을 프론트 repo 안에서 따른다. 설계 문서에 0.1절을
두고 transport별 대응표(지금 연결되나·이유), push가 필요할 때의 세
길, 재검토 조건을 적는다. 레시피 Realtime 절과 매뉴얼 03 C절에서 한
줄로 링크한다.
- 다시 확인한 백엔드 사실(읽기만): 아키텍처 테스트가 MVC SseEmitter를
금지한다(ForbiddenApiArchitectureTest NO_SSE_EMITTER, 결정 D3).
StreamMediaType.SSE는 OpenAPI 생성기만 쓴다. subprotocol 협상 코드는
없다. 그래서 첫째 길을 SSE가 아니라 realtime.v1 WebSocket handler로
적었다.
- 지금 되는 경로(bounded polling)는 사실로 적고, push 경로는 고르지
않았다. 제품 결정이다.
- 버린 대안: desktop-server-git/design-docs/에 쓰기. 이 브랜치 밖이라
함께 합쳐지지 않는다. 필요하면 그쪽에서 이 절을 링크한다.
위험·한계
- 백엔드 사실은 지금 백엔드 HEAD(70fb80bf)를 읽은 것이다. 백엔드가
바뀌면 표가 낡는다. 재검토 조건에 적었다.
- 실제 연결은 실행하지 않았다(리뷰와 같음).
검증
- verify:documentation PASS_SCOPED. documentation-readiness·
changelog-review-ids 테스트 15건 통과.
Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 04-02
문제
Envelope 실패 해석이 422를 모두 필드 검증으로 본다
(isFieldValidationFailure). 짝 백엔드의 422 IDEMPOTENT_REQUEST_MISMATCH는
"같은 키를 다른 본문으로 보냈다"는 뜻이고 필드 목록이 없다. 그런데 kind가
VALIDATION_REJECTED가 되어 폼이 "입력값을 다시 확인해 주세요."를 띄운다.
사용자는 고칠 것이 없는 입력을 고치라는 말을 듣고, validation-error 상태는
지원 참조도 보이지 않는다. fileserver의 422(INTEGRITY_MISMATCH 등)도 같다.
고른 방법
422는 details에서 필드 목록(safeValidationIssues가 읽는 모양)이 나올 때만
필드 검증으로 본다. 필드 목록이 없는 422의 kind는 UNKNOWN_CLIENT_FAILURE다.
400 IDEMPOTENCY_KEY_INVALID와 같은 읽기다. 폼은 unavailable 상태와 지원
참조를 보인다. effect 판정(표)은 바꾸지 않았다. 422 MISMATCH는 그대로
NOT_APPLIED, 표 밖 422는 그대로 MAYBE_APPLIED다.
버린 대안
IDEMPOTENT_REQUEST_MISMATCH 한 code만 빼기: fileserver 422처럼 필드 목록
없는 다른 422가 계속 입력 오류로 보인다.
위험·한계
422로 필드 오류를 보내면서 details에 목록을 싣지 않는 백엔드는 이제 필드
오류 대신 실패 상태를 보인다. 짝 백엔드는 필드 검증을 400으로 보낸다.
검증
- RED: backend-envelope 단위 1건, envelope 통합 2건(422 MISMATCH·
INTEGRITY_MISMATCH의 kind), form-foundation 1건(결과 unavailable, 문구
없음) 실패.
- GREEN: tests/unit·integration·component·features·contract 250파일
3,114건 통과. details.issues가 있는 422는 그대로 필드 오류다
("keeps the save off after a 422 the backend may have applied").
- check:types:app·test, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/08-presentation.md 08-05
문제
registry path는 router base path를 뺀 앱 경로이고, 정상 클릭은
`${appBasePath}${path}`를 URL로 풀어 연다. registry 검사는 `/` 시작,
`//`·`\`·`#` 금지, 같은 origin만 본다. URL parser는 `..`와 `%2e%2e`를
dot segment로 풀기 때문에 scope `/app/`에서 `/../admin`과
`/%2e%2e/admin`이 모두 `https://app.example.test/admin`을 연다(리뷰
실험 ⑤). 검사를 통과한 경로가 앱 밖을 연다.
고른 방법
- safePath가 `new URL(path, base)`의 pathname + search가 입력과 같을 때만
받는다. `..`·`.`·`%2e%2e`(대소문자 무관)는 parser가 바꾸므로 거절된다.
query는 그대로 남는다.
- 버린 대안: 클릭 때 target.pathname이 앱 루트 아래인지 보기. 잘못된
registry가 클릭할 때에야 드러난다. registry는 제품 코드라 생성 시점에
throw하는 쪽이 이르고 작다(리뷰 5.3 (a)).
위험·한계
- 정규화되지 않은 경로(인코딩 안 된 비ASCII 문자, 빈 query `?`)도
거절된다. registry를 쓰는 제품 코드는 아직 없다.
- registry가 서버가 내려주는 런타임 데이터가 되면 클릭 때 검사도 함께
둬야 한다(리뷰 재검토 조건).
검증
- 새 테스트를 옛 코드에 돌림: 5건 실패(RED). 새 코드: web-push 단위
6파일 76건 통과.
- 바꾼 파일 eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 06-02
문제
브라우저는 online인데 서버·프록시만 닿지 않을 때 실패 이름이
transport마다 다르다. SSE는 fetch·reader 거절을 OFFLINE, poll은
execute 거절을 OFFLINE, WebSocket은 error를 PROVIDER_UNAVAILABLE로
낸다. reconnect coordinator는 transport OFFLINE을 backoff로 재시도하고
예산을 다 쓰면 online인데도 OFFLINE으로 끝낸다. 설계 13.1의 OFFLINE
행은 "online hint 뒤 bounded check"라 5.3과 다른 말을 한다. kind로
화면 문구나 조합 판단을 고르면 같은 서버 장애가 SSE에서는 "오프라인",
WS에서는 "서비스 이용 불가"가 되고, "OFFLINE이면 online 이벤트를
기다린다"는 조합 코드는 다시 멈춘다(0929/04-01의 모양).
고른 방법
- 리뷰 5.3절 판단대로 어휘를 맞춘다. SSE fetch 거절(CONNECT)과 reader
거절(RECEIVE), poll execute 거절을 PROVIDER_UNAVAILABLE(retryable)로
바꾼다. 이제 OFFLINE은 환경 신호에서만 나온다.
- poll은 PROVIDER_UNAVAILABLE을 lease 안에서 재시도하므로, 던지는
execute는 바로 끝나지 않고 backoff로 maxAttempts까지 다시 시도한다.
executor가 PROVIDER_UNAVAILABLE을 돌려준 경우와 같은 처리다.
- 설계 13.1의 OFFLINE·PROVIDER_UNAVAILABLE 행과 5.3 문단을 고친다.
- 버린 대안: 13.1에 OFFLINE의 두 뜻을 적기만 하기. 비용은 1행이지만
조합자가 navigator.onLine을 따로 봐야 원인을 안다. 운영 중인 제품이
없는 지금 어휘를 바꾸는 비용이 가장 작다(리뷰 5.3).
위험·한계
- 배럴로 공개된 SSE 연결·poll coordinator의 결과 kind가 바뀐다. repo
안 소비자는 테스트뿐이다.
- 던지는 execute(조합 코드의 버그 포함)는 이제 lease 예산만큼 다시
불린다. 상한은 maxAttempts·maxElapsed 그대로다.
- 환경 신호가 늦게 offline이 되는 경우 첫 실패는 PROVIDER_UNAVAILABLE로
보인다. offline 대기는 kind가 아니라 환경 신호로 걸리므로 멈춤은 없다
(before/after 테스트 그대로 통과).
검증
- 바꾼 기대값 3건을 옛 코드에 돌림: 3건 실패(RED). 새 코드: realtime
단위 241건 통과.
- check:types 통과, 바꾼 파일 eslint 통과.
BREAKING CHANGE: SSE 연결의 fetch·reader 거절과 bounded poll의 execute
거절이 OFFLINE 대신 PROVIDER_UNAVAILABLE(retryable)로 끝난다. poll은
던지는 execute를 lease 안에서 재시도한다. OFFLINE을 서버 장애로 읽던
조합 코드는 PROVIDER_UNAVAILABLE을 함께 본다.
Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 04-04
문제
ContractContributionError의 message는 "Installed contract contribution is not
composable" 하나였고 원인은 reason 속성에만 있었다. check:registries는
message 첫 줄만 적으므로, 제품 인증 프로필 id를 잘못 적으면 게이트 출력에
operation id도 프로필 id도 없었다("missing registry source …: Installed
contract contribution is not composable"). 매뉴얼 02 5절과 starter-experience
정본 표는 V2 해석기와 함께 지워진 "REST security profiles are incoherent …"
메시지를 약속했다.
고른 방법
message에 reason을 붙인다: "Installed contract contribution is not composable:
<reason>". 메시지를 읽는 모든 곳(check:registries, vitest, 부팅 오류)이 원인을
보게 된다. check-registries.ts만 reason을 적게 하는 대안은 다른 출력 경로를
그대로 두어 버렸다. reason은 기능·operation·프로필 id 같은 개발자 식별자뿐이다.
문서 세 곳(매뉴얼 02 5절, errors.md, starter-experience 표)을 실제 출력으로
고쳤고, V3 descriptor에 없는 auth 칸 조합 문장을 지웠다.
위험·한계
- check:registries가 같은 실패 뒤에 적는 연쇄 줄(FE-REG-API is not an object
registry, breaking change missing evidence … removed)은 그대로다(14-06 범위).
- message 문자열 전체를 비교하는 다운스트림 테스트가 있으면 바뀐다.
검증
- RED: second-api-feature-registries.test.ts에 authProfileId를 SECOND_UNKNOWN
으로 바꾼 행을 더했고, 수정 전 stderr에 원인이 없어 실패.
- 같은 파일, external-contract-runtime, http-execution-v3-auth-profile,
reference-fixture-provenance, tests/platform → 33 files / 255 tests 통과.
- eslint, tsc(test), verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-07
문제: 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
문제
BoundedPollOperationContract는 지운 V2 행의 어휘(contractVersion: 2,
protocol, semantics, replayPolicy, retry, transportMaxAttempts,
authRecoveryCount, maxCumulativeSleepMs, serverStream)로 된 자기 선언이다.
assertBoundedPollOperation은 리터럴만 보고 실제로 실행할 descriptor와
대조하지 않는다. 조합 코드가 execute를 V3 실행기와 기본 GET
descriptor(retryBudget 2)로 만들면 503마다 실행기가 두 번 더 보낸다.
poll 3회가 요청 9회가 되고, poll 관측에는 1건씩만 보인다(리뷰 실험 P).
고른 방법
- coordinator의 operation을 V3 descriptor(InstalledHttpContract)로 바꾼다.
실행기는 재시도 상한을 그 descriptor의 frontend.retryBudget에서 읽는다
(http-execution-v3.ts retryCeiling). 그래서 생성 때
retryBudget === 0을 요구하면 실행기 옵션 없이 poll 한 attempt가 요청
한 번이 된다. 실행기(src/adapters/http)는 고치지 않았다.
- 검사: operationId 일치, method GET·HEAD, retrySemantics SAFE·IDEMPOTENT,
retryBudget 0, responseByteLimit 1..8 MiB. execute에 넘기는
maxResponseBytes는 min(policy.maxResponseBytes, responseByteLimit)이다.
- V2 리터럴 필드는 모두 지운다. command descriptor·요청 본문은 조립
(composeContractContributions)이 GET·HEAD에서 이미 거절한다.
- 버린 대안: (a) ApiOperationRow + HttpExecutionPolicy 두 인자. 행에는
retryBudget이 없고, 실행기가 실제로 받는 것은 descriptor 하나라 같은
객체를 넘기는 쪽이 어긋날 틈이 작다. (b) 실행기에 호출별 재시도 끄기
옵션 추가. 다른 에이전트가 고치는 http 영역을 건드리고, descriptor가
재시도를 허용한다는 사실은 그대로 남는다. (c) 문서에만 적기. 검출이
없다.
위험·한계
- 공개 타입이 바뀐다. repo 안 소비자는 테스트뿐이다.
- 조합 코드가 coordinator에 넘긴 descriptor와 다른 객체를 실행기에
넘기면 막지 못한다. 타입 주석과 설계 9.2에 "같은 객체를 넘긴다"고
적었다. 조립된 행은 동결돼 있어 검사 뒤 값이 바뀌지 않는다.
- 기능의 기본 GET(retryBudget 2)은 poll에 쓸 수 없다. poll 전용
operation을 따로 등록해야 한다.
검증
- 새 테스트를 옛 코드에 돌림: 21건 실패(RED). 새 코드: 32건 통과.
- 실험 P를 테스트로 옮김: 기본 descriptor는 생성 때 TypeError,
retryBudget 0 descriptor + maxRetryAttempts 2 실행기 + 503 서버에서
poll 3회 = 요청 3회.
- 변이 5건(retryBudget·method·retrySemantics·operationId·응답 상한 검사
삭제) 모두 검출.
- check:types 통과, 바꾼 파일 eslint 통과.
BREAKING CHANGE: BoundedPollOperationContract를 지운다.
createBoundedPollCoordinator의 operation과 assertBoundedPollOperation의
둘째 인자는 V3 descriptor(BoundedPollOperation = InstalledHttpContract)다.
조립된 행(composeContractContributions(...).httpByOperationId.get(id))을
넘기고, frontend.retryBudget을 0으로 둔 poll 전용 operation을 등록한다.
execute 안에서는 같은 descriptor를 실행기에 넘긴다.
Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 04-01
문제
FeatureRuntime은 featureId·schemas·adapters·contractContributions인데, 네 곳이
지워진 V2 모양을 적었다. feature-module.ts 머리 주석("API contracts with their
runtime schemas and mappers"), installed-feature-contracts.ts("The V2 API
registries"), frontend-application-foundation.md("composes the V2 API
registries"), starter-experience.md 기능 추가 2단계("the API contract
(operations, schema metadata, runtime schemas, mappers)"). 기능 작성자가 없는
칸을 찾게 된다. 07-05(starter-experience 같은 문장)를 함께 닫는다.
고른 방법
네 문장을 지금 모양으로 고친다: schemas는 FE-REG-SCHEMA 행, 어댑터 기여는
application input, 계약 기여는 HTTP operation이고 FE-REG-API 행은 거기서
투영한다(installed-feature-runtime-registries.ts와 같다).
위험·한계
verify:documentation은 문장 내용을 보지 않으므로 다시 낡아도 게이트가 모른다.
검증
- git grep "V2 API registr|runtime schemas, mappers|runtime schemas and
mappers" -- src docs/architecture → 0건.
- verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-10
Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-05
문제
src/features/<dir>/NOT_INSTALLED 표시는 "기능이 아닌 샘플 폴더"라는 뜻인데,
같은 단어가 런타임 상태 "선언됐지만 빌드·FEATURE_OVERRIDES가 뺀 기능"으로도
쓰였다(product-features.ts). 생성기는 feature-module.ts를 못 읽을 때만 표시를
찾았으므로, 샘플을 졸업시키며 표시를 지우지 않으면 표시가 "설치 안 됨"이라고
말하는 채로 조용히 설치됐다.
고른 방법
- 표시 이름을 NOT_A_FEATURE로 바꾼다(local-draft-feature 파일 이름 변경).
런타임 상태 NOT_INSTALLED는 그대로 둔다.
- 생성기가 표시와 feature-module.ts가 함께 있으면 둘 중 무엇을 지울지 적고
실패한다.
- 옛 이름 표시는 받지 않는다. 받으면 같은 다의가 남는다. 옛 표시만 있는
폴더는 "has no feature-module.ts; … mark the directory with NOT_A_FEATURE"로
실패해 새 이름을 알려 준다.
README 상태 표, starter-experience, 매뉴얼 errors·patterns 표를 맞췄다.
위험·한계
다운스트림이 자기 폴더에 NOT_INSTALLED 표시를 두었다면 생성 단계가 실패한다.
파일 이름만 바꾸면 된다.
검증
- RED: 생성기 테스트 3건(새 이름 허용, 옛 이름 거절, 동시 존재 거절)이
수정 전 실패.
- generate-product-feature-index.test.ts 17건 통과. generate:feature-index
통과. verify:documentation PASS_SCOPED. eslint, tsc(node·test) 통과.
BREAKING CHANGE: src/features/<dir>/NOT_INSTALLED 표시 파일은 더 이상
인식되지 않는다. 같은 자리에 NOT_A_FEATURE라는 이름으로 옮긴다.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-09
문제: inspect()는 active pointer 읽기가 실패하면 그 실패를 그대로
돌려준다. 손상 pointer(CORRUPT_DATA)는 조회·cleanup을 막고 다음
activation이 rollback 없이 덮어쓰는 상태인데, 그 상태를 진단할 유일한
관리 API도 같이 멈춘다. 운영자는 어떤 후보가 남았는지, 다음 activation이
무엇을 덮어쓰고 그 뒤 cleanup이 무엇을 지울지 모른 채 배포한다.
PublicCacheInspection에는 pointer 상태를 담을 칸이 없다.
고른 방법: PublicCacheInspection에 activePointer("NONE" | "READABLE" |
"UNREADABLE")를 둔다. pointer 읽기가 CORRUPT_DATA면 UNREADABLE로 적고
activeReleaseRegistryId는 null로 둔 채 후보 목록을 끝까지 채운다. 일시
오류(UNAVAILABLE 등)는 지금처럼 실패로 돌려준다. activation이 이미 쓰는
"CORRUPT_DATA만 손상으로 본다" 규칙과 같다. recipe fake도 같은 칸을
채운다. 리뷰가 함께 적은 inspect 전용 operation 이름은 공유 operation
union을 바꾸는 일이라 이번에 하지 않았다.
위험·한계: 공개 포트 타입에 필수 칸이 하나 는다. 결과를 읽는 쪽은
그대로지만 이 포트를 직접 구현한 쪽은 칸을 채워야 한다([계약]).
repo 안 소비자는 없다. inspect의 signal·판정 불가(0929/02-02)는
그대로다. service-worker-pwa 번들 9,733 → 9,758 / 10,100 gzip B.
검증:
- RED: public-response-cache-repair.test.ts 새 테스트가 activePointer
없음으로 실패.
- GREEN: 같은 파일 11건 통과(손상 중 inspect ok, UNREADABLE, 후보
r1·r2 verified, 일시 오류는 UNAVAILABLE). cache 단위 3파일 +
tests/recipes 63건 통과. check:types, 바꾼 파일 eslint,
check:optional-recipes:source PASS, verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 02-05
문제
2026-11-03 전체 리뷰는 출시될 코드 전체를 봐야 한다. 오늘 고친 것이 두 브랜치에
나뉘어 있다. claude/happy-easley-233d07(Envelope, V2 삭제, 거절 표, CSRF·KEYED
재전송)과 fix/ui-design-audit-2026-11-01(남은 위험 16커밋)이다. 사용자가 두
브랜치를 합친 상태를 리뷰 기준으로 골랐다.
고른 방법
새 브랜치 review/2026-11-03-merged에서 두 브랜치를 합쳤다. 원래 두 브랜치는
건드리지 않았다. 충돌은 계약 문서 4.1·6절 두 곳이었다.
- 4.1: 백엔드 기준 SHA(5786126c) 문장은 fix 쪽을, Envelope를 읽는 곳은 V2가
없어진 이쪽을 택했다.
- 6절: 거절 판정 위치는 backend-envelope.ts 표다.
- 6.1 "프론트 판정과 표가 다른 곳"에서 3261208이 고친 두 항목을 지웠다.
위험·한계
- 이 합치기는 리뷰 기준을 고정하려는 것이다. 어느 브랜치를 main에 합칠지는
사용자가 정한다.
검증
- check:types 통과. 나머지 게이트는 리뷰 기록(9절)에 적는다.
문제
V2 클라이언트는 보낸 KEYED 요청이 503·408·425·502·504·network·timeout으로
끝나면 같은 키로 자동 재시도했다. 048f490으로 그 동작이 없어졌다. 설계 정본
(2026-07-30 closed deep design 8.3)은 KEYED 자동 재시도를 "known response
status가 retry 가능하다고 package가 명시한 경우만" 허용하고, 응답 없는
network·timeout 뒤에는 금지한다. V2는 응답 없는 실패 뒤에도 보내 정본과
어긋났고, V3는 응답이 재시도를 허락해도 보내지 않아 정본보다 좁았다. 짝
백엔드는 503 IDEMPOTENCY_UNAVAILABLE을 "작업 실행 전에 거부됐다. 같은 키로
나중에 다시 보낸다"로 정한다(http-contract.md §2).
고른 방법
- backend-envelope.ts의 invitesKeyedResend: 503 + IDEMPOTENCY_UNAVAILABLE.
- Envelope operation의 실패 해석에서 KEYED 명령이 그 답을 받으면
AdmissionOutcome에 keyedResend를 싣는다. 재시도 루프는 그때 retryBudget·
MAX_RETRY_ATTEMPTS·상한 2 안에서 같은 frozen 요청(같은 Idempotency-Key)을
다시 보낸다. certainty는 MAYBE_APPLIED로 두어, 다 쓰면 결과 불명으로 끝나고
키를 지킨다.
버린 대안
- V2처럼 KEYED의 모든 재시도 가능 status·network 실패에서 재시도: 정본 8.3이
응답 없는 실패 뒤 재시도를 금지한다.
- 409 IDEMPOTENT_IN_FLIGHT도 자동 재시도: 처리 중 요청은 47fec5c의 사용자
재전송(Retry-After 대기)이 이미 같은 키로 다룬다. V2도 409는 자동으로 다시
보내지 않았다.
위험·한계
- retryBudget이 0인 명령(참조 기능 CREATE)은 그대로 다시 보내지 않는다.
- Envelope가 아닌 operation은 백엔드 code를 몰라 이 재전송이 없다.
검증
- RED: tests/integration/http-execution-v3-envelope.test.ts "KEYED resend on
the backend's pre-execution refusal" 3건 중 2건 실패(한 번만 보내고
PROBLEM). 다른 503(REQUEST_TIMEOUT)을 다시 보내지 않는 행은 처음부터 통과.
- GREEN: 같은 파일 35건 통과. 두 번 보낸 키가 같다.
- check:types, lint, check:architecture, test:unit 2,568, test:integration 117,
test:component 245, tests/features 99 통과.
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.7
문제
기능 하나가 같은 HTTP API를 두 번 적는다. *-api-contract.ts의 V2 행
(defineRestOperation)은 check:registries(FE-REG-API)가 검사하는 선언이고,
contract contribution의 V3 descriptor가 실제로 실행된다. 둘이 어긋나지 않게
http-operation-v2-v3-parity 테스트를 따로 둔다. 048f490으로 V2 클라이언트가
없어져 V2 행을 읽는 실행 코드는 없고, 검사만 남은 두 번째 사본이다. V2 행을
위한 기능별 runtimeSchemas·mappers 레지스트리와 V2 보안 프로필 해석
(resolveRestSecurityProfiles)도 같이 남아 있다. 사용자 지시: 최신 경로 하나만
남기고, 레지스트리 기준선 재승인을 승인했다.
고른 방법
- src/contracts/api-operations.ts를 projectApiOperationRows 하나로 바꿨다.
조립된 contribution의 descriptor마다 operationId, featureId, method, path,
authProfileId, retrySemantics, requestBody, responseBody, responseEnvelope,
request/response/problemSchema(검증기 schemaId) 행을 만든다. FE-REG-API는
같은 export(API_OPERATIONS)를 읽고, governance 정의를 이 필드로 바꿨다.
requestSchema·responseSchema는 그대로 FE-REG-SCHEMA를 참조한다.
- FeatureRuntime은 apiContract 대신 schemas(FE-REG-SCHEMA 행)만 받는다.
installed-feature-runtime-registries는 schemas로 스키마 레지스트리를 만들고
FE-REG-API 행을 descriptor에서 뽑는다. RUNTIME_SCHEMA_CODECS, MAPPER_REGISTRY,
REST_PROFILE_BINDINGS_VALID, API_RUNTIME_BINDINGS_VALID를 지웠다.
- realtime snapshot 바인딩은 ApiOperationRow를 받고 method GET과
retrySemantics SAFE·IDEMPOTENT를 본다(V2의 contractVersion·semantics·
replayPolicy 대신).
- rest-profiles.ts에서 V2 행용 provider·CSRF 프로필 해석을 지웠다. V3는 조립
때 auth profile을 검사하고 자격증명 헤더를 프로필로 거른다.
- 참조 기능: reference-api-contract.ts를 reference-schema-metadata.ts로
바꾸고(스키마 행만), V2 runtime codec·operation mapper·레지스트리 mapper를
지웠다. V3 descriptor가 쓰지 않는 NoRequest 스키마 행도 지웠다.
- create:feature: <base>-api-contract.ts 대신 <base>-schema-metadata.ts를
만든다. codec·mapper 레지스트리 행과 그 테스트를 만들지 않는다.
- 레지스트리 기준선을 update:registry-baseline으로 다시 만들고 승인했다
(digest 16f72742…, 승인자 DongHyeonka, 이유에 사용자 승인을 적음).
- 매뉴얼 01·02·reference, starter-experience, 계약 문서의 V2 설명을 지웠다.
버린 대안
- V2 행을 남기고 V3에서 생성하기: 생성 단계와 생성물이 하나 더 생긴다. 행은
실행되지 않으므로 메모리에서 뽑아 검사하면 충분하다.
- 스키마 메타데이터(FE-REG-SCHEMA 행)도 검증기에서 뽑기: boundary·
unknownFieldPolicy·owner는 검증기에 없고, 라우트 스키마도 같은 레지스트리를
쓴다. 이 행은 V2가 아니라 스키마 레지스트리라 남겼다.
위험·한계
- BREAKING: FeatureRuntime 모양, contracts·rest-profiles·loaded-feature-runtimes
의 이름이 바뀌거나 없어졌다. memento-frontend의 memento-web이 V2 행을 쓴다.
옮기는 법은 CHANGELOG에 적는다.
- V2 보안 프로필 일관성 검사(auth "none"과 ANONYMOUS, 쿠키 프로필의 CSRF
모드)가 사라졌다. V3 descriptor에는 그 칸이 없다.
- BoundedPollOperationContract(realtime polling recipe)는 contractVersion: 2
필드를 갖지만 자체 계약이라 바꾸지 않았다.
검증
- check:types, lint, check:architecture, check:registries(11 registries PASS,
compatibility=none), check:ci, check:diagnostics, check:adapter-inventory,
verify:documentation 통과.
- test:unit 2,566(새 tests/unit/api-operation-rows.test.ts 3건 포함),
test:integration 114, test:component 245, test:contract 23,
test:runtime-schema 56, tests/features 99 통과.
- tests/unit/second-api-feature-registries.test.ts: V3 descriptor만 가진 두
번째 기능을 복사본에 넣으면 기준선을 고치지 않고 check:registries가 통과한다.
- check:bundle 통과. 초기 JS 201,598 → 200,911 B.
- test:feature-scaffold 16개, test:sample-removal 23개 검사 통과.
BREAKING CHANGE: FeatureRuntime이 apiContract 대신 schemas를 받는다.
defineRestOperation, ApiOperation, RestOperationV2, composeApiOperations,
validateApiRuntimeBindings, getApiOperation, contracts의 API_OPERATIONS,
createRestProviderProfile, RestProviderProfile, resolveRestSecurityProfiles,
validateRestProfileBindings, REST_CSRF_PROFILES, RestCsrfProfile,
loaded-feature-runtimes의 RUNTIME_SCHEMA_CODECS, MAPPER_REGISTRY,
REST_PROFILE_BINDINGS_VALID, API_RUNTIME_BINDINGS_VALID가 없어졌다. 기능은
operation을 contract contribution에만 적고, schemas 행을 feature-runtime에
넘긴다.
문제
HTTP 실행 경로가 둘이다. V3 실행기(createContractHttpExecutor)가 모든 기능을
실행하고, V2 클라이언트(createHttpClient)는 bootstrap의
createRuntimeHttpClient에서만 만들어지는데 그 함수를 앱 안에서 부르는 곳이
없다(테스트만 부른다). tech-log·memento도 같다. 그런데도 V2는 초기 청크에
들어가고, 짝 백엔드 해석(7db32e1~3261208)과 테스트를 두 벌로 유지하게 했다.
사용자 지시: 레거시를 두지 말고 최신 경로 하나만 남긴다.
고른 방법
- src/adapters/http/의 client.ts, bounded-json.ts, request-builder.ts,
resource-mapper.ts, retry-policy.ts, schema-registry.ts를 지웠다. Envelope
스키마는 backend-envelope.ts로 옮겼다. V3가 retry-policy.ts에서 쓰던
parseRetryAfter는 그것이 감싸던 platform/retry-after.ts의
parseRetryAfterDelay를 직접 부른다.
- 배럴의 V2 export와 bootstrap의 createRuntimeHttpClient·RuntimeHttpContract를
지웠다.
- V2 전용 테스트(http-client, http-diagnostics, auth-recovery,
legacy-http-credential-authority, bounded-json-compatibility,
request-builder, retry-policy)와 tests/helpers/http-contract-fixture.ts를
지웠다. 섞인 파일(http-execution-contract, runtime-adapters,
boundary-mapper)은 V2 블록만 지웠다.
- V2로 돌던 폼 테스트(form-foundation)는 Envelope을 읽는 V3 keyed create
계약으로 옮겼다. 400 VALIDATION_FAILED 필드 오류, {cause} 뒤 다시 저장,
422 뒤 저장 꺼짐을 그대로 검사한다. http-execution-v3-envelope 테스트는 V2와
비교하던 행을 기대 판정을 직접 적는 행으로 바꿨다.
- drill:runbook FE-RB-003은 V2 shouldRetry 대신 V3 실행기를 실제로 돌려
보낸 요청 수를 센다(NEVER 503: 1회, SAFE 503: 재시도, SAFE 스키마 불일치:
1회).
- check:diagnostics의 http 이벤트 생산자, registry-governance의 오류 표 소비자,
risk-coverage 고위험 경로, 아키텍처 금지 fixture, adapter INVENTORY, 문서의
경로를 V3 파일로 바꿨다.
버린 대안
- V2를 @deprecated로 한 릴리스 남기기: 템플릿과 두 다운스트림 모두 부르는
곳이 없어 옮겨 갈 사용자가 없다. 남기면 초기 JS와 두 벌 유지 비용만 남는다.
위험·한계
- BREAKING: 배럴과 bootstrap의 V2 이름을 쓰던 제품 코드는 컴파일이 깨진다.
CHANGELOG에 옮기는 방법을 적었다.
- V2에만 있던 동작이 사라졌다: 401 뒤 세션 복구 후 한 번 재전송, KEYED 503
자동 재시도. V3는 401을 UNAUTHENTICATED로 넘기고 KEYED 요청은 보낸 뒤
재시도하지 않는다.
- 기능마다 적는 V2 API 행(*-api-contract.ts, check:registries가 읽음)은 이
커밋에서 지우지 않았다. 다음 커밋이 지운다.
검증
- check:types, lint, check:architecture(금지 fixture 9건 거절),
check:adapter-inventory(140 files), check:diagnostics, check:registries,
check:ci, verify:documentation 통과.
- test:unit 2,585, test:integration 114, test:component 245, test:contract 23,
test:runtime-schema 56, tests/features 101 통과.
- drill:runbook FE-RB-003: no local check failed.
- check:bundle 통과. 초기 JS 203,354 → 201,598 B(−1,756 B).
BREAKING CHANGE: src/adapters/http/index.ts가 createHttpClient, HttpClient,
HttpClientDependencies, HttpFailure, HttpResult, LegacyHttpInput, Scheduler,
OperationRequestInput를, src/bootstrap/runtime-adapters.ts가
createRuntimeHttpClient, RuntimeHttpContract를 내보내지 않는다. 그 operation의
V3 descriptor를 만들어 createFeatureHttpBinding으로 실행한다.
문제
계약 문서 4.2절은 422를 "field validation"으로 적는다. 3261208 뒤로 프론트는
422 중 IDEMPOTENT_REQUEST_MISMATCH만 적용 안 됨으로 보고, 짝 백엔드는 필드
검증을 400 VALIDATION_FAILED로 보낸다. 같은 문서의 6.1절 표와 4.2절이 서로
다른 말을 한다.
고른 방법
- 400 행에 짝 백엔드 필드 검증이 400 VALIDATION_FAILED라는 것을 더하고
적용 여부는 6.1절을 가리킨다.
- 422 행을 짝 백엔드 기준으로 바꿨다. 기본 배포는 IDEMPOTENT_REQUEST_MISMATCH만,
fileserver는 쓰기 뒤에도 나오는 code를 422로 보낸다. 폼 필드 오류는
details.issues[]가 있으면 여전히 읽는다.
- 리뷰 README 14.6의 위험 줄을 고친 상태로 바꿨다.
버린 대안
- 422 행을 그대로 두고 6.1절만 믿기: 같은 문서 안에서 두 절이 어긋난다.
위험·한계
- 422로 필드 검증을 보내는 다른 백엔드를 쓰는 프로젝트는 422 뒤에 폼에서
다시 저장할 수 없다. 문서는 그 동작을 적을 뿐 바꾸지 않는다.
검증
- verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.6
문제: 3f9c087은 초기 청크를 묶지 않는 근거로 "템플릿은 HTTP/2 이상으로
서빙한다"를 정했다. 그런데 이 전제는 작업 기록인 performance-evidence.md
에만 있다. 호스팅을 정하는 사람이 읽는 현재 계약 문서(static-delivery.md)
에는 서빙 프로토콜 이야기가 없다.
고른 방법: static-delivery.md 끝에 한 단락을 더한다. HTTP/2 이상으로
서빙한다는 것, HTTP/1.1에서 늦어지는 정도(Fast 3G 약 1초), HTTP/2에서의
차이(100 ms 미만), HTTP/1.1만 되는 제품이 할 일을 적고 측정 기록으로
링크한다.
버린 대안: README의 배포 절에 적기. README는 배포 변수와 명령을 다루고,
호스트 동작은 static-delivery.md가 다룬다.
위험·한계: 수치는 2026-11-03 한 번의 측정이다. 셸이 바뀌면 달라진다.
검증: node scripts/verify-documentation-readiness.ts PASS_SCOPED
문제: context gateway가 라우트 적재 실패를 `ui.render.failed`로 남길 때
`route_id`를 URL에서 고른다. 고르는 곳이 세 군데이고 결과가 서로 다르다.
- 청크 누락이 아닌 실패: `registeredRouteIdAt(...) ?? routeModule.id`.
레지스트리의 NOT_FOUND splat이 모든 URL에 맞아서 등록 라우트가 없는 URL은
`NOT_FOUND`가 되고 대체값은 한 번도 쓰이지 않는다. 운영에서는 not-found
화면이 깨진 것처럼 읽혀 플랫폼 담당에게 간다. 실제로 실패한 것은 context의
라우트 모듈이다.
- 복구하지 못한 청크 실패: 늘 `routeModule.id`(context id). telemetry는
`route_id`를 `^[A-Z][A-Z0-9_]{0,63}$`로만 받는다. 그래서 이 이벤트는
`invalid-attribute-value`로 버려진다(`projectTelemetryEvent`로 확인).
- 레이아웃 청크 실패: `?? "NOT_FOUND"`. 레이아웃 아래 context는 등록 경로에만
붙어서 지금은 닿지 않는 값이다.
이 진단이 구분해야 하는 것은 둘이다. 어느 화면(그래서 어느 기능)이 실패했나,
그리고 not-found 화면 자체가 실패했나. 그 값은 telemetry까지 가야 한다.
고른 방법: 세 곳이 `failedRouteIdAt(pathname)` 하나를 쓴다. URL의 등록
라우트 id를 쓰고, 등록 라우트가 없으면(NOT_FOUND만 맞으면) 명시값
`UNREGISTERED_ROUTE`(`UNREGISTERED_ROUTE_ID`, src/contracts/routes.ts)를
쓴다. 등록 URL의 청크 실패는 context id 대신 그 라우트 id가 된다. 라우트
id로 소유 기능과 context를 찾을 수 있다. 청크 복구의 chunkId 선택은 바꾸지
않았다.
버린 대안:
- context id(`routeModule.id`, 원래 의도한 대체값): 실패한 모듈을 정확히
가리키지만 telemetry가 버린다. 받게 하려면 `route_id` 문법을 소문자
kebab까지 넓혀야 한다. 그러면 `api.request.failed` 등 모든 이벤트의
`route_id` 검사가 약해진다.
- context id를 대문자 snake로 바꿔 쓰기: 숨은 이름 규칙이 생기고 실제 라우트
id와 섞인다.
- `context_id` 속성 추가: 진단·telemetry 허용 목록과 레지스트리 기준선을
바꿔야 한다. 기준선 재승인은 이 작업 범위가 아니다.
위험·한계:
- 등록 라우트가 없는 URL의 실패는 어느 context인지 진단에 남지 않는다. 같은
결함은 그 context의 등록 URL에서도 나므로 그 보고로 찾는다.
- [계약] `ui.render.failed`의 `route_id`에 `UNREGISTERED_ROUTE` 값이 생긴다.
복구하지 못한 context 라우트 청크 실패는 context id 대신 라우트 id를 적는다.
`route_id` 이름과 허용 문법은 그대로다.
- 기능이 `UNREGISTERED_ROUTE`라는 route id를 선언하면 구분되지 않는다. 막지
않았다.
검증:
- RED: context-boundary-diagnostics "unregistered handle" 1건이
`"route_id": "NOT_FOUND"`로 실패. context-route-gateway 새 2건이
`"route_id": "context-offline"`로 실패(8건 중 3 실패).
- GREEN: 두 파일과 context-layouts 14건 통과. 각 보고는 telemetry 투영
(`projectTelemetryEvent`)도 통과한다.
- 회귀: tests/{architecture,unit,features,platform,component,contract,
runtime-schema,integration,scripts,scale}(pnpm을 띄우는 3개 제외) 306
files, 3,572건 통과.
- tsc app·test 통과. 바꾼 파일 eslint 통과. check-registries,
check-diagnostics 통과. verify-documentation-readiness PASS_SCOPED.
문제: 라우터는 `AppShell` 아래 플랫폼 라우트를 모든 context보다 먼저 붙인다.
그래서 기능 라우트를 플랫폼 라우트도 받으면 오류 없이 플랫폼 화면이 나온다.
React Router `matchRoutes`로 라우터와 같은 구조를 만들어 확인했다.
- 같은 경로: context `examples/*`의 `/examples/ui`는 `EXAMPLES_UI`가 받는다.
레이아웃 아래에서도 순위가 같으면 앞에 있는 `AppShell`이 이긴다.
- `APP_HOME`이 아닌 id로 선언한 `/`는 플랫폼 홈이 받는다(ca16187 한계).
- 레이아웃 없는 `*` 루트 context는 모든 URL을 NOT_FOUND splat에 뺏긴다.
splat끼리 순위가 같고 플랫폼 쪽이 먼저다. 7139c7c의 루트 검사는 context
루트끼리만 비교해 이 셋을 통과시킨다.
고른 방법: 라우트 조립 런타임, 곧 `defineDeployableAppModule`의 09-06 검사
(`assertFeatureRoutesReachOwningContext`)에 한 단계를 더한다. 기능 라우트
경로마다 `[대체되지 않은 플랫폼 라우트..., context가 붙는 자리]`로
`matchRoutes`를 돌려, 그 context가 받지 않으면 route id, 경로, 기능, context,
가로챈 플랫폼 라우트를 담아 TypeError로 실패한다. context가 붙는 자리는
라우터와 같다. 레이아웃이 없으면 루트이고, 있으면 그 라우트의 경로다. 기능이
대신한 `APP_HOME`은 플랫폼 쪽에서 빼고, `APP_HOME` 라우트 자체는 지금처럼
건너뛴다.
- 앱 모듈을 평가할 때 실패하므로 부트와 앱 모듈을 불러오는 모든 테스트가
막힌다(fail-closed). 기존 09-06 검사와 같은 자리이고, 라우트 정의는 이미
초기 그래프에 있다.
버린 대안:
- 라우터(`createRegisteredRoutes`)에서 검사: 라우터 표 자체로 보니 순위가
정확하다. 하지만 `AppRouter`가 마운트될 때에야 실패하고, 앱 모듈을 fixture로
바꿔 끼우는 테스트를 따로 만들어야 한다.
- 아키텍처 테스트: 템플릿에 설치된 기능만 보고, 다운스트림이 기능을 더한
빌드는 실행 때 지켜지지 않는다.
- 레지스트리 검사(`check:registries`) 또는 생성기: 생성기는 정규식으로
리터럴만 읽어 라우트 경로를 모른다.
- 경로 문자열 비교: `*` 루트와 파라미터 모양이 같은 경로를 놓친다.
위험·한계:
- 라우터 순서를 이 함수가 따라 한다. `app-router.tsx`가 플랫폼 라우트를
context 뒤로 옮기면 이 검사도 같이 바꿔야 한다. 주석에 적었다.
- 일부만 겹치는 경우(`/examples/:slug`의 `ui` 값)는 막지 않는다. 그 기능
라우트는 다른 값으로는 닿는다.
- 기능끼리 같은 경로는 이 커밋 범위가 아니다.
검증:
- RED: tests/architecture/context-route-roots.test.ts 새 5건 중 거절 4건이
"expected [Function] to throw an error"로 실패(21건 중 4 실패).
- GREEN: 21건 통과. 메시지 예: "Route EXAMPLES_UI_COPY (/examples/ui) of
feature examples-feature in context examples is answered by platform route
EXAMPLES_UI (/examples/ui). A feature replaces a platform route only by
declaring its id (APP_HOME)."
- 회귀: tests/{architecture,unit,features,platform,component,contract,
runtime-schema,integration,scripts,scale}(pnpm을 띄우는 3개 제외) 306
files 중 3,569 통과, 1 실패. 실패는 telemetry-storm.test.ts 10초
timeout(부하 44)이고 단독 재실행에서 4건 통과했다.
- tsc app·test·node 통과. 바꾼 파일 eslint 통과. check-registries 통과.
verify-documentation-readiness PASS_SCOPED.
문제: 라우터는 경로가 바뀔 때마다 `#main-content`로 focus를 옮긴다.
그래서 라우터가 붙이는 모든 레이아웃은 skip link와 `<main id="main-content">`
하나를 그려야 한다. ca16187이 context 레이아웃을 열면서 이 규칙을 타입 주석과
starter-experience.md, fixture로만 지켰다. 레이아웃에서 `<main>`을 빼도
실패하는 테스트가 없다(리뷰 README 14.4 09-03 첫 줄).
고른 방법: 등록된 레이아웃을 읽어 도는 component 테스트
`tests/component/layout-landmarks.test.tsx`.
- 대상: `AppShell`, 설치된 제품(`TEMPLATE_APP_MODULE.contexts`)의 각
`loadLayout`, fixture 제품(`LAYOUT_PRODUCT_CONTEXT_MODULES`)의 각
`loadLayout`. 제품이 `context-layout.tsx`를 추가하면 이 파일을 고치지 않아도
검사 대상이 된다.
- 각 레이아웃을 메모리 라우터에 붙이고 자식 페이지(probe h1)를 그린다.
확인: `main`/`role="main"`이 정확히 하나, 그 id가 `main-content`, 자식
페이지가 그 안에 있음, `href="#main-content"` 링크가 있음.
- fixture의 offline 레이아웃은 청크가 오지 않도록 만든 것이라 id로 뺐다.
버린 대안:
- context-layouts.test.tsx에 넣기: 그 파일은 생성 인덱스를 fixture로 mock한다.
설치된 제품의 레이아웃은 그 안에서 읽을 수 없고, 읽더라도 fixture 레지스트리
아래라 제품 라우트를 가리키는 레이아웃(`routePath`)이 다른 이유로 깨진다.
- `AppRouter`로 레이아웃마다 URL을 열기: 레이아웃마다 파라미터 없는 경로를
골라야 하고 설치된 제품과 fixture를 한 파일에서 돌릴 수 없다.
위험·한계:
- 레이아웃 단독 렌더라 페이지가 자기 `<main>`을 하나 더 그리는 경우는 이
테스트가 못 잡는다. 라우터를 거친 확인은 context-layouts.test.tsx가 fixture로
한다.
- skip link가 첫 focus 대상인지는 보지 않는다.
- 템플릿 자체에는 레이아웃을 선언한 context가 없어, 설치된 제품 쪽은 지금
`AppShell`만 돈다.
검증:
- RED(변이): fixture 레이아웃의 `<main>`을 `<div>`로 바꾸면 4건 중 3건 실패
("expected to have a length of 1 but got +0"). AppShell skip link href를
`#content`로 바꾸면 1건 실패("expected null not to be null"). 둘 다 되돌렸다.
- GREEN: 4건 통과(AppShell, context site, topics, studio).
- tsc test 통과. 새 파일 eslint 통과. verify-documentation-readiness
PASS_SCOPED.
문제
09-02(da1e128) 뒤에도 tech-log가 하는 일 두 가지는 템플릿 파일을 고쳐야
한다(리뷰 1101 README 14.4 "09-02 이식").
- 제품 설정 키의 FE-REG-ENV 행: tech-log는 템플릿 src/contracts/env.ts의
ENV_REGISTRY에 TECH_LOG_STUDIO_SOURCE·TECH_LOG_PUBLIC_SOURCE 행을 직접
넣었다(tech-log env.ts:63-70).
- 부트 전 BFF 세션 owner: 세션이 httpOnly 쿠키라 owner가 백엔드에 묻는다.
tech-log는 템플릿 create-runtime-composition.ts에서 AUTH_MODE external이고
Studio가 HTTP일 때 createRuntimeAdapters 전에 host 전역
__CA_FRONTEND_AUTH_OWNER__에 owner를 넣는다(:2, :36-52,
bff-session-owner.ts:188-194). composeProduct는 http가 생긴 뒤에 불리고
http는 세션이 필요해서 이 일을 받을 수 없다.
고른 방법
- product-contracts.ts에 PRODUCT_ENV_REGISTRY를 빈 값으로 둔다. env.ts는
PRODUCT_REST_AUTH_PROFILES·PRODUCT_RUNTIME_CONFIG_FIELDS와 같은 모양으로
그 행을 ENV_REGISTRY에 합친다. 템플릿 키와 이름이 겹치면 모듈 로드 때
throw한다. check:registries와 vite.config.ts가 같은 객체를 읽으므로 제품
행도 같은 필드 검사를 받는다. 행을 더하기만 하면 additive라 기준선을
고치지 않는다(실험: 제품 행 2개 → compatibility=additive PASS, 허용 밖
classification → 실패).
- product-composition.ts에 composeProductSessionOwner(context)를 둔다.
템플릿은 null을 돌려준다. 조립 루트가 세션을 고르기 전에, AUTH_MODE가
external일 때만 부른다. 제품 owner가 host 전역보다 먼저다. null이면
지금처럼 host 전역, 없으면 unavailable이다. demo 모드는 묻지 않는다.
context는 config와 fetcher뿐이다(http 전이라 capability가 없다).
버린 대안
- owner를 composeProduct 반환값에 넣기: http가 세션을 쓰므로 순서가 꼬인다.
- 제품이 host 전역에 계속 넣게 두고 문서화: 부트 전 훅이 템플릿 파일
(create-runtime-composition.ts)에 남는다.
- FE-REG-ENV 행을 PRODUCT_RUNTIME_CONFIG_FIELDS에서 자동으로 만들기: zod
필드로는 classification·required를 알 수 없다.
- 행 타입·도우미를 product-contracts.ts가 env.ts에서 import: 순환 의존
(no-circular-dependencies)이다. 타입 검사는 env.ts의 대입에서 한다.
위험·한계
- product-composition.ts에 export가 하나 늘었다. 이 파일을 이미 복사한
제품은 composeProductSessionOwner를 더해야 한다. da1e128은 아직 main에
없고 두 다운스트림 모두 받지 않았다.
- 제품 행을 as const 없이 쓰면 phase가 string으로 넓어져 tsc 오류가
env.ts:78(템플릿 파일)에서 난다. 메시지에 키 이름은 나온다. product-
contracts.ts 주석에 as const를 적었다.
- 제품 설정 키에 FE-REG-ENV 행이 있는지 요구하는 검사는 여전히 없다.
템플릿 키도 RELEASE_ID·BUILD_ID는 행이 없어서 이 변경에서 넣지 않았다.
- 제품 owner가 throw하면 createRuntimeAdapters가 실패해 부트 실패
화면이 된다. composeProduct와 같다.
- tech-log의 owner는 subject를 null로 돌려준다(템플릿 동작대로 매 변경
fence). 이 변경과 무관하다.
검증
- RED: tests/unit/product-composition-fixture.test.ts 13건 중 3건 실패.
FE-REG-ENV 행 없음, external 모드 세션이 authenticated가 아니라
integration-failed, env 이름 충돌을 거절하지 않음.
- GREEN: 같은 파일 13/13, runtime-adapters-credential-order 7/7(mock에
composeProductSessionOwner: () => null 추가).
- fixture는 vi.mock 대상이 제품 소유 두 파일(머리 주석 "Product-owned.")과
설치 기능 seam 두 개뿐이고, tech-log가 고친 템플릿 파일 4개(env.ts,
create-runtime-composition.ts, runtime-config-schema.ts,
runtime-adapters.ts)는 대상이 아님을 이 파일의 소스를 읽어 확인한다.
- 회귀: tests/unit·contract·runtime-schema·integration 198 files 2861
tests 통과(heavy lock 아래).
- tsc app·node·test 통과, 바꾼 파일 eslint 통과, check:registries PASS
(compatibility=none, 재승인 불필요), verify:documentation PASS_SCOPED,
check:adapter-inventory PASS.
- 초기 JS gzip 202,770 → 202,931 B(+161, 예산 204,800). 같은 방법(dist
manifest의 초기 파일 26개, gzipSync 기본 레벨)으로 전·후를 쟀다.
- 미실행: check:architecture(pnpm 필요), test:component, e2e.
문제: 1196b86은 stream coordinator의 마감 실패만 13.1 어휘로 바꿨다.
live↔Poll handoff coordinator는 아직 네 마감을 모두 `IDLE_TIMEOUT`으로
보고한다. 설계 13.1에서 `IDLE_TIMEOUT`은 전송 idle(heartbeat/byte
deadline → close + bounded reconnect)이다. 그래서 관측에서 "서버가
조용함"과 "우리 effect·checkpoint가 멈춤"을 kind로 나눌 수 없다.
- switchToPoll quiescence 마감: IDLE_TIMEOUT/RECOVER
- activateProbe quiescence 마감: IDLE_TIMEOUT/RECOVER
- checkpoint 마감: IDLE_TIMEOUT/RECOVER
- close drain 마감: IDLE_TIMEOUT/CLOSE
고른 방법: 결정 (a)를 1196b86과 같은 방식으로 적용한다. kind만 바꾸고
operation, retryable(전과 같이 true), fail-close 동작은 그대로 둔다.
- quiescence 마감 → APPLY_FAILED/RECOVER. 기다리는 것은 이전 writer의
apply effect tail이다. stream coordinator의 effect 마감과 같은 kind다.
APPLY_FAILED의 기본 retryable은 false라 true를 명시했다. 두 곳의 같은
분기를 `quiescenceFailure` 하나로 합쳤다.
- checkpoint 마감 → PROVIDER_UNAVAILABLE/RECOVER. checkpoint authority가
throw할 때와 같은 kind다.
- close drain 마감 → PROVIDER_UNAVAILABLE/CLOSE. stream·reconnect
coordinator의 drain 상한과 같다. 이전부터 timer 실패도 같은 값이라 두
분기를 하나로 합쳤다.
- 13.1 표: IDLE_TIMEOUT 행에서 handoff를 빼고 "내부 task 마감에는 쓰지
않는다"로 적었다. APPLY_FAILED·PROVIDER_UNAVAILABLE 행에 handoff 마감과
retryable 값, 뒤 동작을 적었다. 남은 IDLE_TIMEOUT 생성 지점은 SSE·WS의
RECEIVE·SUBSCRIBE(전송 idle)뿐이다.
버린 대안:
- retryable도 kind 기본값으로(quiescence가 false가 됨): 결정 범위는
어휘다. 재시도 판단 변경은 따로 정한다.
- close 마감에 CLOSED: 1196b86과 같은 이유로 버렸다. 아직 writer가
settle하지 않았는데 "닫힘"으로 읽힌다.
위험·한계:
- 배럴로 공개된 handoff coordinator 결과의 kind가 바뀐다. IDLE_TIMEOUT을
보던 조합 코드는 APPLY_FAILED·PROVIDER_UNAVAILABLE을 봐야 한다. repo
안에 소비자는 없다(AVAILABLE_NOT_COMPOSED).
- handoff에는 observer가 없어 관측 reason은 바뀌는 것이 없다.
- 같은 APPLY_FAILED라도 stream coordinator는 retryable:false, handoff는
true다. 13.1 표에 둘 다 적었다.
- realtime 레시피 gzip 40,902 → 40,878 B(한도 42,200).
검증:
- RED: 기대값을 먼저 바꾸고 activateProbe quiescence 마감 테스트를 새로
넣은 뒤 live-poll-handoff-coordinator.test.ts 실행 → 7 failed | 9
passed. 7건 모두 received kind IDLE_TIMEOUT(close 4건, switchToPoll
quiescence, activateProbe quiescence, checkpoint).
- GREEN: `node scripts/run-vitest.ts run tests/unit/realtime` 14 files,
231 passed.
- tsc app·test·recipes 통과, 바꾼 두 파일 eslint 통과,
`check-optional-recipes`(source) PASS, `verify-documentation-readiness`
PASS_SCOPED, `check-adapter-inventory` PASS.
- 미실행: `check:architecture`(pnpm 필요).
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.1 04-02, 14.4
문제
"검증 거절은 적용 안 됨" 판정(64e98ee)의 근거가 추론이었다. 백엔드
http-contract.md 4절은 VALIDATION_FAILED의 출처를 적지만 "상태를 바꾸지
않는다"는 문장이 없다. 그 밖의 400·409·422 code는 어느 단계에서 나오는지
적힌 곳이 없었다. 계약 4.1·6절은 백엔드 커밋이 없어 기준을 결정일로 적었다.
고른 방법
- 백엔드 5786126c 코드에서 400·409·422를 내는 곳을 모두 찾고, code마다
단계(쓰기 전 / 쓰기 뒤 가능)와 프론트 결과(NOT_APPLIED / MAYBE_APPLIED),
백엔드 파일:줄을 6.1절 표에 적었다. 같은 code가 쓰기 전과 뒤에서 모두
나오면 쓰기 뒤 가능으로 둔다. 프론트는 code만으로 둘을 가르지 못한다.
- 4.1·6절 기준을 결정일에서 백엔드 SHA 5786126c로 바꿨다.
- 표와 지금 프론트 판정이 다른 곳을 같은 절에 적었다. client.ts는 다른
작업이 고치고 있어 이 변경에서 건드리지 않았다.
찾은 것
- 쓰기 전: VALIDATION_FAILED(출처 5곳 모두 바인딩·검증 단계, CVE handler는
지금 요청 경로 출처 없음), IDEMPOTENCY_KEY_INVALID, IDEMPOTENT_REQUEST_
MISMATCH. IDEMPOTENT_IN_FLIGHT도 이번 요청은 쓰기 전이지만 앞선 요청이
적용될 수 있어 MAYBE_APPLIED다.
- 쓰기 뒤 가능: BAD_PARAMETER(모든 층의 IllegalArgumentException),
MAPPING_FAILED(멱등성 응답 직렬화는 action이 끝난 뒤), DB_* 409 8종,
LOCK_ACQUISITION_TIMEOUT, 참조 도메인 400·409 6종, 선택 모듈 11종.
fileserver INTEGRITY_MISMATCH·MALWARE_DETECTED(422)는 레코드를 REJECTED로
쓴 뒤 던진다.
- 프론트와 다른 곳: 필드 목록 없는 400 VALIDATION_FAILED는 표로 NOT_APPLIED인데
V2는 effect가 없다. V2는 422 전체를 NOT_APPLIED로 보지만 fileserver 422는
MAYBE_APPLIED다. V3 참조 분류기는 400·422 전체를 NOT_APPLIED로 본다(참조
fixture용, 짝 백엔드에는 맞지 않는다).
버린 대안
- 백엔드 문서 표를 프론트 문서에 복사: 단계 정보는 백엔드 문서에 없다.
복사할 것이 아니라 프론트가 코드에서 읽은 판정이라 SHA와 파일:줄로 적었다.
- 프론트에 백엔드 소스를 읽는 검사 추가: 두 repo가 나란히 있어야만 돈다.
표를 SHA에 묶고, SHA를 올릴 때 표를 다시 확인하라고 적었다.
위험·한계
- "쓰기 전"은 지금 코드에서 handler에 닿는 출처를 센 결과다. 백엔드가
application bean에 @Validated를 달거나 JPA entity에 Bean Validation 제약을
넣으면 필드 목록 있는 VALIDATION_FAILED가 use case 안에서도 나온다. 백엔드에
이것을 막는 검사는 없다.
- 줄 번호는 5786126c 기준이다. 백엔드가 바뀌면 어긋난다.
검증
- node scripts/generate-product-feature-index.ts &&
node scripts/verify-documentation-readiness.ts: PASS_SCOPED
- 표의 파일:줄은 백엔드 5786126c에서 grep·sed로 다시 열어 확인했다.
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.3, 14.4