8b92f45f5eefe85c92a58a3cd65fc7b2bd6b30b1
219
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
8b92f45f5e |
fix(http): Fileserver 업로드 실패에 Envelope의 traceId를 싣는다
문제: readFailureEnvelope는 실패 Envelope의 meta.traceId를 함께 돌려주고, V3 실행기는 그 값을 AppFailure.traceId로 싣는다(1103/03-06). Fileserver client는 envelope.value만 넘겨 traceId를 버린다. 지원 담당이 업로드 실패를 서버 로그의 요청과 잇지 못한다. 같은 백엔드의 다른 쓰기 실패는 이을 수 있다. 고른 방법: envelopeFailure가 읽은 Envelope 전체를 받아 traceId가 있으면 createFailure의 traceId로 싣는다. V3와 같은 규칙이다. 없으면 키를 두지 않는다. 매뉴얼 7절 결과 읽기에 한 줄 적었다. 위험·한계: Envelope 실패에만 싣는다. 성공 Envelope을 읽지 못한 실패 (SCHEMA_MISMATCH 등, 202 REJECTED 포함)는 readSuccessEnvelope가 meta를 돌려주지 않아 traceId가 없다. V3도 같다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts RED(이 커밋의 테스트 + 부모 src): Envelope failures 표 17행이 traceId "trace-1"이 없어 모두 실패한다. Refs: 1105/01-03 |
||
|
|
471b001c40 |
fix(http): Fileserver 504 TRANSFER_TIMEOUT를 결과 불명으로 읽고 멱등 응답은 V3 표를 쓴다
문제: client는 504 TRANSFER_TIMEOUT을 NOT_APPLIED, retryable:true, retryAfterMs 5000으로 준다. 매뉴얼대로면 기능이 5초 뒤 자동으로 다시 올린다. 근거로 든 "백엔드가 게시 전에 낸다"는 이 code에 맞지 않는다. 백엔드(45d2a478)는 업로드 작업을 전송 풀에 넘기고, 대기 스레드가 await-seconds가 지나면 작업 단계와 상관없이 future.cancel(true) 뒤 TRANSFER_TIMEOUT을 던진다(BlockingTransferExecutor). interrupt는 파일 복사는 멈추지만 게시 rename과 READY 커밋은 멈추지 않는다. 그래서 504 뒤에 파일이 READY가 될 수 있고, 백엔드가 멱등 키를 읽지 않으므로 다시 보내면 같은 파일이 둘 생긴다. 같은 client의 효과 표는 V3 표와도 갈라졌다. 503 IDEMPOTENCY_UNAVAILABLE을 client는 NOT_APPLIED, V3 표(backend-envelope.ts)와 매뉴얼 4절은 MAYBE_APPLIED로 본다. 계약 문서 6.1의 fileserver 행은 4xx를 MAYBE_APPLIED로 적는데 client는 NOT_APPLIED로 보고, 어느 쪽도 다른 쪽을 말하지 않는다. pin 대조도 이 표를 보지 않는다. 고른 방법: - TRANSFER_TIMEOUT을 NOT_APPLIED_5XX_CODES에서 뺀다. 5xx 기본값대로 MAYBE_APPLIED이고, createFailure가 retryable:false, action contact-support로 만든다. 자동 재전송은 없다. 남은 NOT_APPLIED 5xx는 작업 스레드가 게시 전에 내는 넷(PARTIAL_WRITE, ATOMIC_PUBLISH_UNSUPPORTED, STORAGE_UNAVAILABLE, STORAGE_FULL)이다. - 멱등성 code(IDEMPOTENT_*, IDEMPOTENCY_* 접두)와 V3 표의 행(REFUSED_BEFORE_WRITE, MAYBE_APPLIED_ANSWERS의 status+code)은 client도 envelopeFailureEffect로 판정한다(sharedAnswerEffect). 같은 백엔드 code의 판정이 이 repo에 하나다. 503 IDEMPOTENCY_UNAVAILABLE은 MAYBE_APPLIED가 되고, 400 IDEMPOTENCY_KEY_INVALID·422 IDEMPOTENT_REQUEST_MISMATCH는 그대로 NOT_APPLIED, 409 IDEMPOTENT_IN_FLIGHT 등은 그대로 MAYBE_APPLIED다. 손으로 둔 MAYBE_APPLIED_CODES 목록은 AMBIGUOUS_COMPLETION 비교 하나로 줄었다. - pin 옆에 복사한 백엔드 답 표(config/contracts/backend-idempotency-answers.json)의 행마다 client 결과의 effect가 V3 표와 같은지 통합 테스트가 본다. 그 표는 tests/unit/backend-contract-pin.test.ts가 V3 표를 묶는 표와 같다. pin을 옮기면 두 reader가 함께 다시 대조된다. - Fileserver 4xx를 NOT_APPLIED로 보는 이유(업로드 use case가 취소)를 계약 문서 6.1에 한 곳으로 적고, client 주석과 매뉴얼은 그곳을 가리킨다. - client 주석·매뉴얼의 백엔드 SHA 표기를 bbe944bd에서 pin(45d2a478)으로 맞췄다. 두 SHA 사이 Fileserver main 코드는 바뀌지 않았다(리뷰 2.1절). 버린 대안: - client 효과 판정을 V3 표로 통째로 바꾼다: Fileserver 4xx가 모두 결과 불명이 되어 413·415·422 파일 거절과 202 REJECTED 화면이 나빠진다. 단일 업로드에서는 use case가 취소하므로 근거도 없다. - TRANSFER_TIMEOUT 한 줄만 고친다: 위험한 줄은 없어지지만 세 표의 갈라짐과 pin 밖 상태가 남는다. 위험·한계: - 504 TRANSFER_TIMEOUT 뒤 화면이 "재시도"에서 "결과 불명"으로 바뀐다. 503 IDEMPOTENCY_UNAVAILABLE도 같다. CHANGELOG [계약] 한 줄이 필요하다. - 백엔드로 넘김: 백엔드는 TRANSFER_TIMEOUT을 retryable=true, ambiguous 없이 보낸다(FileserverErrorCode, BlockingTransferExecutor). 요청 — (a) 작업이 시작된 뒤의 대기 초과는 details.ambiguous=true, reconciliationRequired=true, retryable=false로 보내거나, (b) 작업 스레드가 게시 rename과 READY 커밋 전에 interrupt를 확인해 504가 "READY 없음"을 보장하게 하고, 어느 쪽인지 docs/fileserver/http-contract.md에 적는다. 백엔드가 (b)를 고르면 이 줄을 되돌린다(재검토 조건). - 백엔드로 넘김: POST /v1/files가 Idempotency-Key를 읽지 않는다 (UploadFileApplicationUseCase NOT_IDEMPOTENT). 요청 — 업로드를 멱등성 executor 뒤에 두거나, 키를 무시한다고 Fileserver 계약 문서에 적는다. - 리뷰 최소 개선 방향 ④의 "drift 검사 대상에 docs/fileserver/http-contract.md 추가"는 하지 않았다. scripts/check-backend-contract-drift.ts와 pin 모양은 같은 라운드의 1105/07-01 수정이 다시 짠다. 같은 파일을 두 브랜치가 고치면 충돌한다. 07-01과 함께 넣는 편이 낫다. - Fileserver 자신의 code 표(NOT_APPLIED_5XX_CODES)는 여전히 손으로 읽은 것이고 pin 대조 밖이다. 늦게 READY가 되는 경쟁은 재현하지 않았다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts RED(이 커밋의 테스트 + 부모 src): Envelope failures 표의 "503 IDEMPOTENCY_UNAVAILABLE → SERVER_FAILURE, MAYBE_APPLIED, retryable false", "504 TRANSFER_TIMEOUT → SERVER_FAILURE, MAYBE_APPLIED, retryable false", "504 TRANSFER_TIMEOUT is an unknown result the client does not offer to retry", pinned backend answer table의 "reads 503 IDEMPOTENCY_UNAVAILABLE as the V3 Envelope table does"가 실패한다. Refs: 1105/01-02 |
||
|
|
6608fef4ba |
fix(http): Fileserver 202 REJECTED를 파일 거절로 읽고 빈 파일은 보내지 않는다
문제: 짝 백엔드(45d2a478)는 POST /v1/files를 요청 안에서 동기로 검증하고 READY가 아닌 state를 모두 202로 답한다(FileUploadController#created). 악성 코드가 아닌 이유로 검증기가 거절하면 예외 없이 202 REJECTED다 (FinalizeUploadApplicationUseCase#applyNonAcceptVerdict). 기본 검증기 사슬의 첫 검증기(LengthVerifier)가 빈 파일을 그렇게 거절하므로, 0바이트 파일 하나로 닿는다. client schema에는 REJECTED가 없어 이 답이 SCHEMA_MISMATCH, APPLIED_CONFIRMED, "응답 형식 오류" 문구로 끝난다. 사용자는 파일을 바꾸라는 안내 대신 지원 문의를 보게 된다. 테스트의 MSW는 202 VERIFYING만 적은 백엔드 문서에서 왔고, 매뉴얼도 202를 "아직 검사 중"으로 적어 QUARANTINED(동기 검증 202의 대부분)를 끝나지 않는 대기로 보이게 한다. 고른 방법(리뷰 01-01 최소 개선 방향 (가)): - schema가 REJECTED를 받는다. 202 REJECTED는 성공이 아니라 실패 VALIDATION_REJECTED, code FILE_REJECTED, NOT_APPLIED, httpStatus 202다. 413·415·422 파일 거절과 같은 규칙이다. 백엔드는 그 레코드를 공개하지 않고 바이트 정리를 예약하므로 쓸 수 있는 파일이 남지 않는다. 공개 타입 FileserverFileState와 FileserverUploadedFile은 바꾸지 않았다(REJECTED는 성공 값으로 나오지 않는다). - 빈 파일은 읽기 전(선언 크기 0) 또는 읽은 뒤(선언 없음, 0바이트) 보내지 않고 FILE_EMPTY, NOT_STARTED로 끝낸다. 서버의 202 REJECTED에는 이유가 없어 기능이 "빈 파일"이라고 말할 수 없기 때문이다. - 201⇔READY 검사, size 일치 검사, 모르는 필드 무시는 그대로다. 201 REJECTED는 여전히 SCHEMA_MISMATCH다. - MSW 설명을 백엔드 코드(45d2a478) 기준으로 고치고 202 QUARANTINED· REJECTED 행을 더했다(1103/01-01의 "MSW가 문서에서 왔다" 부분). - 매뉴얼 7절이 202 state 셋의 뜻(VERIFYING 재검사 대기, QUARANTINED 관리자 결정 전 내려받기 불가, REJECTED는 실패)과 FILE_EMPTY를 적는다. 버린 대안: - REJECTED를 성공 state로 넘긴다: 타입 변경은 작지만 기능마다 성공 값에서 거절을 다시 찾아야 하고, 공개 타입 FileserverFileState가 넓어진다. - 빈 파일 거절만 한다: 기본 사슬은 막지만 제품이 더한 검증기의 REJECT는 그대로 SCHEMA_MISMATCH다. 위험·한계: - upload() 결과가 바뀐다. 202 REJECTED가 SCHEMA_MISMATCH에서 VALIDATION_REJECTED/FILE_REJECTED로, 빈 파일이 서버 요청에서 FILE_EMPTY로 바뀐다. CHANGELOG [계약] 한 줄이 필요하다. - 빈 파일 거절은 짝 백엔드 기본 검증기 사슬을 가정한다. 제품이 사슬에서 LengthVerifier를 빼 빈 파일을 받게 하면 client 규칙도 바꿔야 한다. - 실제 짝 백엔드를 띄워 빈 파일을 올려 보지 않았다(미검증). 응답 모양은 백엔드 코드(UploadedFileResponse, FileRecord#toDescriptor)를 읽은 것이다. - 1103/01-01의 남은 부분은 이 커밋 밖이다: 백엔드 매뉴얼의 짝 경로 안내와 docs/fileserver/http-contract.md의 202 state 목록(백엔드로 넘김), 실제 업로드 검증(미검증). 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts RED(이 커밋의 테스트 + 부모 src): "reads 202 REJECTED as a refused file, not as a broken answer"(SCHEMA_MISMATCH로 끝남), "an empty file", "an undeclared size that turns out empty"(fetch를 부름)가 실패한다. Refs: 1105/01-01, 1103/01-01 |
||
|
|
3d3d6527ef |
fix(http): Fileserver 업로드 client가 browser-file-storage 포트를 import하지 않는다
문제 src/adapters/http/fileserver-upload.ts(1103/01-01)가 입력 타입으로 application/ports/browser-file-storage의 FileByteSource를 import한다. test:browser-file-storage-removal(FE-GATE-020)은 그 선택 런타임과 포트를 지우고 남은 코드가 import하지 않는지 본다. 그래서 "Removed browser file/storage runtime is still imported by: src/adapters/http/ fileserver-upload.ts"로 항상 실패한다(리뷰 조치 X2 #7). 고른 방법 - client 안에 같은 모양의 FileserverByteSource(byteLength, stream이 Result<Uint8Array, { code }>를 낸다)를 두고 배럴로 낸다. client가 쓰는 것은 이 셋뿐이다. 제품은 FileContentPort.openSource가 준 FileByteSource를 그대로 넘긴다(구조 타입). - 버린 대안: 드릴이 이 client도 함께 지우기. http 배럴이 export하므로 배럴도 고쳐야 하고, 파일 runtime을 쓰지 않는 제품도 업로드 client를 잃는다. 위험·한계 - FileByteSource 모양이 바뀌면 두 타입이 어긋날 수 있다. 통합 테스트가 FileByteSource 값을 client에 넘기므로 check:types가 그 어긋남을 잡는다. 검증 - check:types(테스트의 FileByteSource → client 호환), lint, check:architecture, test:integration 통과. 드릴은 이 커밋 뒤 재실행한다. Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 01-01, README.md 14.6 X2 #7 |
||
|
|
20a5b084fd |
fix(http): Fileserver 422 파일 거절은 입력 거절로, 키 재사용 불일치는 공통 표대로 읽는다
문제 fix/r1103-transfer의 Fileserver 업로드 client는 실패 kind를 공유 Envelope 판정(envelopeFailureReading)에서 받고 413·415만 VALIDATION_REJECTED로 바꾼다. fix/r1103-http(1103/08-05)는 필드 목록 없는 422를 UNKNOWN_CLIENT_FAILURE로 읽게 했다. 두 브랜치를 합치자 Fileserver의 422(digest·서명·검사기 거절, 예: MALWARE_DETECTED)가 입력 거절이 아니게 되어 통합 테스트 2건이 실패한다. 고른 방법 - Fileserver 계약에서 422는 파일 자체의 거절이다(백엔드 docs/fileserver/http-contract.md 상태 표). 사용자가 파일을 바꿔야 하는 413·415와 같이 VALIDATION_REJECTED로 둔다. - 422 IDEMPOTENT_REQUEST_MISMATCH(같은 키, 다른 본문)는 파일 문제가 아니므로 08-05의 공통 판정(UNKNOWN_CLIENT_FAILURE)을 따른다. 테스트 기대값도 그렇게 바꿨다. - 버린 대안: 공통 판정을 422 전체 입력 거절로 되돌리기. 08-05가 고친 결함(같은 키 불일치를 입력 오류로 보임)이 다시 생긴다. 위험·한계 - 422 code 목록을 파일 거절로 고정하지 않고 "불일치가 아니면 파일 거절"로 본다. 백엔드가 파일 업로드에 다른 뜻의 422를 더하면 다시 본다. 검증 - test:integration 189건(fileserver-upload 48건 포함), check:types, lint 통과. Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 01-01, 08-presentation.md 08-05 |
||
|
|
6088f6e533 |
chore(review): 1103 HTTP 쓰기 경로 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 03-01~03-06 0929/03-03 08-05 10-02 10-04 12-06 # Conflicts: # docs/manual/02-decision-tables.md |
||
|
|
e20b5bfe3a |
chore(review): 1103 업로드·전송 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 01-01 01-02 01-03 |
||
|
|
55d0d48424 |
chore(review): 1103 저장소·파일 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 02-01~02-05 05-01~05-04 # Conflicts: # docs/manual/03-outside-feature-folder.md # src/bootstrap/product-composition-contract.ts # src/bootstrap/runtime-adapters.ts |
||
|
|
c17b3a05d6 |
chore(review): 1103 세션 owner 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 09-03 09-11 # Conflicts: # docs/manual/02-decision-tables.md |
||
|
|
4f78890576 |
fix(browser-files): 위험 확장자를 safe extension으로 쓰는 다운로드 정책을 거절한다
문제: 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 |
||
|
|
f800549315 |
feat(http): 짝 백엔드 Fileserver의 multipart 한 번 업로드 client를 더한다
문제: 두 템플릿을 짝으로 쓰면 파일 업로드 경로가 없다. 프론트 업로드 레시피는 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 |
||
|
|
ba2b4f4c6d |
feat(contracts): 짝 백엔드 계약 기준점을 기계가 읽는 pin과 답 표로 둔다
문제 짝 백엔드 계약의 기준 커밋은 계약 문서의 문장(백엔드 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 |
||
|
|
af7d0b1824 |
fix(browser-transfer): 재조정에서 checkpoint 삭제가 실패해도 resourceId를 준다
문제: 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
|
||
|
|
274ae69088 |
perf(browser-transfer): 이어 올리는 스트림 업로드는 보낼 part만 해시한다
문제: 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 |
||
|
|
f6b74ed496 |
fix(storage): put idle 상한이 lock 대기 상한보다 짧지 않은 OPFS 정책을 거절한다
문제: putIdleTimeoutMs < mutationLockWaitTimeoutMs는 05-07이 기대는 관계다(멈춘 put이 idle 상한에서 origin lock을 놓아야 줄 선 writer가 대기 상한 전에 돈다). 이 관계가 opfs-policy.ts 주석에만 있고, 정책 검사는 각 값의 범위만 본다. 두 값을 뒤집은 정책은 조용히 통과하고, 멈춘 put 하나가 다른 탭의 모든 쓰기를 BLOCKED로 끝낸다. 고른 방법: assertOpfsRuntimePolicy가 putIdleTimeoutMs >= mutationLockWaitTimeoutMs를 TypeError로 거절한다. 다른 정책 오류와 같은 자리·같은 방식이다. 기본값(2분 < 10분)과 repo 안의 모든 정책은 이미 관계를 지킨다. 위험·한계: 이 관계를 어긴 정책을 쓰던 다운스트림은 조립 때 실패한다. 의도한 동작이다. 검증: - RED: opfs-worker-runtime.test.ts 새 2건(같음, 김)이 throw 없음으로 실패. - GREEN: OPFS 단위 3파일 + tests/recipes + tests/contract 174건 통과. check:types, 바꾼 파일 eslint 통과. Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 0929/05-09 |
||
|
|
39c1de2e5e |
feat(diagnostics): 결과 불명 쓰기의 effect와 원인을 진단에 싣는다
문제 실행 관측(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 |
||
|
|
631ce339b9 |
fix(http): 실패 Envelope의 meta.traceId를 AppFailure.traceId로 싣는다
문제
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
|
||
|
|
49a09868ad |
feat(http): Envelope 목록의 meta.page를 mapSuccess에 넘긴다
문제
짝 백엔드는 페이지 목록의 전체 수·페이지 번호를 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
|
||
|
|
fd6b6315c0 |
fix(storage): 소속 partition이 없는 손상 journal 행을 따로 세고 경보에서 뺀다
문제: partition 삭제는 journal 행을 LOGICAL_KEY_INDEX로 찾는다. 인덱스에는 logicalKey 값이 있는 행만 들어가므로, 그 값까지 깨진 행은 승인된 ACCOUNT_DELETION으로도 지워지지 않는다(X4: partition 파일 0개인데 행은 남음). 그 행은 reconcile마다 corruptTransactions 1, OBJECT_RECONCILE DEGRADED/CORRUPT_DATA로 남는다. runbook은 "키로 찾으므로 손상 row도 지워진다", "partition이 승인된 purge로 지워질 때만 함께 지워진다"고 적고 수동 삭제를 금지한다. 운영자는 늘 켜진 경보를 받지만 할 수 있는 일이 없고, 그 경보가 진짜 손상을 가린다. 고른 방법(리뷰 (a)+(b)): 소속을 모르는 행은 지울 근거가 없으므로 지우지 않는다. 대신 - journal의 listIncomplete가 손상 행 가운데 이 authority의 partition 키 범위에 들지 않는 행을 unattributedRows로 따로 센다(0이면 칸 없음). - reconcile report에 unattributedCorruptTransactions를 싣고(0이면 칸 없음), DEGRADED 관측은 purge가 지울 수 있는 손상 행이 있을 때만 낸다. - runbook §0·§7 문장을 코드와 맞추고, 이런 행에 대해 할 일(같은 수면 없음, 늘면 writer를 찾음, 수동 삭제 금지)을 적었다. 버린 대안: (a)만 — 경보가 계속 켜진다. (c) 소속을 모르는 행 자동 삭제 — 그 행이 가리키던 staging을 추적할 근거가 사라진다(runbook §0 3번). 위험·한계: 공개 타입에 선택 칸 두 개가 는다(OpfsJournalPage .unattributedRows, OpfsReconciliationReport .unattributedCorruptTransactions). 직접 만든 journal이 칸을 채우지 않으면 지금처럼 모든 손상 행이 경보에 남는다. 소속 없는 행만 있을 때 관측이 SUCCEEDED가 되므로, 그 수는 report로만 보인다. 이런 행의 staging은 purge의 partition 삭제 조건(countPartitionTransactions)에 잡히지 않는다. offline-indexeddb 번들 37,555 → 37,705 / 38,500 gzip B. 검증: - RED: indexeddb-opfs-journal.test.ts 새 테스트가 unattributedRows 없음, opfs-worker-runtime.test.ts 새 X4 테스트가 unattributedCorruptTransactions 없음으로 실패. - GREEN: 키 있는 손상 행은 removePartition이 지우고 키 없는 행은 남는다. 키 없는 행만 있으면 관측 SUCCEEDED, 키 있는 손상 행이 더해지면 DEGRADED:CORRUPT_DATA. OPFS 단위 3파일 + optional-runtime-host + tests/recipes + tests/contract 176건 통과. check:types, 바꾼 파일 eslint, check:optional-recipes:source PASS, verify:documentation 통과. Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 05-03 |
||
|
|
1e8b3d049f |
feat(http): operation이 쓰기 전 업무 거절 code를 선언한다
문제 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 |
||
|
|
7b55f0f83d |
fix(storage): partition lock을 기다리는 put·delete가 자기 abort로 끝난다
문제: withTransactionLock은 partition lock을 signal 없이 요청한다
(withPartitionLock("shared", operation, undefined, run)). put·remove의
request.signal이 거기까지 오지 않고, Web Locks 요청은 signal이 없으면
시간 제한도 없다. mutationLockWaitTimeoutMs는 worker의 origin lease에만
걸린다. 다른 탭의 partition 삭제가 큰 업로드를 기다리는 동안 같은
partition에 put·remove(또는 만료 객체를 지우는 open)를 부르고 취소하면,
삭제가 끝날 때까지 결과가 오지 않는다(X5: abort 뒤 200 ms 동안 대기).
05-01로 정상 purge도 partition 삭제를 쓰게 되어 이 대기가 더 자주 난다.
고른 방법: put·remove가 request.signal을 withTransactionLock에 넘기고,
withPartitionLock은 kernel createAbortableOperation으로 caller signal과
mutationLockWaitTimeoutMs를 묶은 signal로 lock을 요청한다. caller
abort면 ABORTED, 시간이 다 되면 BLOCKED(retryable, RETRY)다. worker의
acquireLease와 같은 값·같은 결과다. lock을 얻으면 바로 close해 타이머를
지운다(얻은 lock에 대한 abort는 Web Locks에서 아무 일도 하지 않는다).
lock 전 abort는 journal begin 전이라 보상할 것이 없다.
버린 대안: signal만 넘기기(리뷰 최소안). 취소는 되지만 "상한 없음"이
남는다. 새 정책 값 추가. 같은 의미의 값이 이미 있다.
위험·한계: 같은 상한이 partition 삭제(exclusive)의 기다림에도 걸린다.
다른 탭 put이 10분(기본값)보다 오래 걸리면 purge가 BLOCKED로 끝나고
호출자가 다시 부른다. 전에는 끝없이 기다렸다. 실제 브라우저에서 abort
경합은 돌리지 않았고 Node Web Locks로만 확인했다. offline-indexeddb
번들 37,521 → 37,555 / 38,500 gzip B.
검증:
- RED: opfs-worker-runtime.test.ts 새 2건. abort한 put이 200 ms 안에
끝나지 않음(STILL_WAITING), 가짜 시계로 상한을 넘겨도 put이 끝나지
않아 10초 timeout.
- GREEN: OPFS 단위 3파일 + optional-runtime-host + tests/recipes 151건
통과. check:types, 바꾼 파일 eslint, check:optional-recipes:source
PASS, verify:documentation 통과.
- browser: heavy lock 안에서 opfs-runtime·indexeddb-runtime spec 3엔진
27/27 통과. 첫 실행은 dev server가 실행 중에 페이지를 다시 불러
5건이 "Execution context was destroyed"로 떨어졌고, 다시 돌려 통과했다.
Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 05-02
|
||
|
|
5d0f5ad7f8 |
docs(realtime): heartbeat를 멈춘 WebSocket이 예산을 새로 받지 못함을 적는다
문제 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 |
||
|
|
37615072e9 |
fix(http): 백엔드가 정한 5xx 결과 불명 답을 분류기와 상관없이 고정한다
문제 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 |
||
|
|
d13a393600 |
fix(storage): 계정 삭제 purge가 끝나지 않은 put을 보면 partition을 지운다
문제: 손상이 없는 LOGOUT·ACCOUNT_DELETION purge는 commit된 object 행과
참조 없는 chunk만 본다. 같은 partition의 끝나지 않은 journal 행
(PREPARING·FILES_READY)은 보지 않고, sweep은 staging receipt가 가리키는
chunk를 건너뛰면서도 COMPLETED를 돌려준다. 그래서
- 다른 탭이 put 중이면 purge가 "COMPLETED"를 보고한 뒤 그 객체가
그대로 읽힌다(X1, 실제 Chromium·Firefox에서도 같음).
- commit 직전에 멈춘 put(FILES_READY)은 purge 뒤 다음 reconcile이
commit해 계정 삭제한 사용자 파일이 객체로 다시 생긴다(X2).
- 업로드 중 멈춘 put(PREPARING)은 chunk가 grace 기간 동안 남고(X2b),
그 행이 손상됐으면 partition 삭제도 일어나지 않아 영원히 남는다(X3).
손상이 있을 때만 partition 삭제가 진행 중 put까지 기다렸다 지웠다.
고른 방법(리뷰 5.1절 (c)): LOGOUT·ACCOUNT_DELETION이 객체를 다 돈 뒤
그 partition 키를 가진 journal 행 수를 센다. 하나라도 있으면(읽을 수
있든 없든) sweep 대신 이미 있는 partition 삭제로 넘긴다. partition
삭제는 exclusive partition lock으로 진행 중 put·delete가 돌아오기를
기다린 뒤 디렉터리와 그 partition의 행을 모두 지운다(
|
||
|
|
613c1cfd0c |
fix(http): 필드 목록이 없는 422를 입력 오류로 읽지 않는다
문제
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
|
||
|
|
a145f30b48 |
fix(web-push): dot segment가 든 registry path를 생성 때 거절한다
문제
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
|
||
|
|
d7c6cb4fd2 |
fix(auth): 세션 복구가 no-session이면 로그인 버튼을 보인다
문제: useSessionAction이 recover()의 결과를 버린다. owner가 "no-session"을 돌려주고 상태를 recovery-pending으로 두면 보호 라우트와 셸은 계속 "세션 복구" 버튼만 보이고, 로그인으로 갈 길이 없다. owner가 지켜야 할 상태 전이도 어디에도 적혀 있지 않아 owner 작성자가 화면 코드를 읽고 추론해야 했다. 고른 방법: 두 가지를 함께 한다. - SessionState·SessionGateway.recover·ExternalSessionOwner에 전이 계약을 적는다. restored면 authenticated, no-session이면 unauthenticated(또는 integration-failed), reject면 상태 유지. - SessionProvider가 recover()의 답을 쓴다. no-session을 받았는데 owner가 아직 recovery-pending이면, owner가 다음에 알릴 때까지 화면에 unauthenticated로 보인다. 그래서 라우트 문과 셸 모두 로그인 버튼을 보인다. 버린 대안: 어댑터가 전이를 검사해 throw. 그러면 화면은 "작업 실패"만 보이고 여전히 로그인 버튼이 없다. 어댑터가 상태를 덮어쓰는 것은 구독 알림을 새로 만들어야 해서 scope fence와 얽힌다. 위험·한계: 계약을 어기는 owner의 상태를 화면에서만 바로잡는다. application·scope fence는 owner의 상태를 그대로 본다. 검증: tests/component/session-recovery.test.tsx 4건(수정 전 2건 실패 확인), router·app-shell·route-status-surfaces·auth-session-adapter 테스트 통과, check:types, eslint 통과. Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-11 |
||
|
|
af000673ef |
fix(realtime)!: 서버에 닿지 않은 SSE·poll 실패를 PROVIDER_UNAVAILABLE로 낸다
문제 브라우저는 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 |
||
|
|
c695898aee |
fix(browser-transfer): 상한보다 긴 Retry-After는 앱에도 retryable:false로 준다
문제: 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 |
||
|
|
a65df74046 |
fix(realtime)!: bounded poll을 V3 descriptor에 묶어 실행기 재시도를 막는다
문제 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 |
||
|
|
60b721fd1c |
fix(browser-files): inspect 중에 놓은 ref에는 receipt를 발급하지 않는다
문제: vault inspect()는 이전 receipt를 무효화한 뒤 파일을 읽으며 두 번 await한다. 그 뒤 #disposed는 다시 보지만 ref가 아직 있는지는 보지 않고 receipt를 발급한다. 그 사이 release(ref)가 record와 receipt를 지우면, inspect는 사라진 ref에 ok와 receipt를 돌려주고 receipt 기록이 놓은 File을 runtime dispose까지 붙잡는다(activeReferenceCount 0, activeVerificationCount 1). 지금은 resolveVerifiedFile의 records.has 검사가 preview를 막지만, 그 검사를 지운 변이(L11)를 잡는 테스트가 없었다. 고른 방법: #disposed 재확인 바로 뒤에서 record가 없으면 NOT_FOUND/RESELECT로 끝낸다. resolveFile이 ref를 못 찾을 때와 같은 결과라 호출자가 이미 처리하는 분기다. 리뷰의 최소 개선 방향 그대로다. 위험·한계: 같은 ref에 inspect 두 개가 겹치면 receipt가 둘 생기는 것은 이 변경 범위 밖이다(두 receipt 모두 release·dispose가 지운다). 이 수정 뒤에는 놓은 ref에 receipt가 남는 경로가 없어서, L11 검사는 다시 두 번째 방어선이 된다. 새 테스트는 이 커밋의 검사를 지우면 실패한다. file-transfer 번들 56,053 → 56,068 / 57,800 gzip B. 검증: - RED: browser-file-content.test.ts 새 테스트가 inspect ok(기대 NOT_FOUND)로 실패. - GREEN: browser-files 단위 5파일 + tests/recipes 85건 통과. check:types, 바꾼 파일 eslint, check:optional-recipes:source PASS. Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 02-04 |
||
|
|
7e7614fd48 |
fix(cache-storage): 손상 pointer에서도 inspect가 상태와 후보를 보여 준다
문제: 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
|
||
|
|
f19d4c6e9c |
fix(cache-storage): 활성화가 본문 읽기 일시 오류를 손상으로 보고하지 않는다
문제: verifyReleaseCandidate는 cache.match()가 던질 때만 UNKNOWN으로 본다. 본문 stream 읽기가 끊기면 readAndValidateResponse가 UNAVAILABLE(retry=true)이나 NOT_READABLE을 돌려주는데, 판정이 ABORTED 밖의 실패를 모두 REPAIRABLE로 바꾼다. 그래서 같은 I/O 오류가 조회에서는 UNAVAILABLE/RETRY, 활성화에서는 INTEGRITY_FAILED/REHYDRATE가 된다. stage 재사용 경로는 후보를 고치려고 모든 asset을 네트워크로 다시 받는다. 같은 파일의 타입 주석은 "unreadable candidate"를 UNKNOWN이라고 적는다. 고른 방법: 저장된 바이트·헤더에 대한 판정인 INTEGRITY_FAILED· CORRUPT_DATA·POLICY_REJECTED·LIMIT_EXCEEDED만 REPAIRABLE로 두고, 나머지 (UNAVAILABLE·NOT_READABLE·ABORTED 등)는 UNKNOWN으로 둔다. 활성화와 stage 재사용은 이미 UNKNOWN을 자기 operation으로 rebase해 돌려준다. 리뷰가 적은 최소 개선 방향 그대로다. 거꾸로 "실패 code 목록을 UNKNOWN 쪽에 적는" 방식은 새 code가 생기면 손상으로 떨어지므로 버렸다. 위험·한계: stage 재사용 경로는 본문을 읽지 못하면 이제 repair 대신 실패를 돌려준다. 손상이 아닌 것을 손상으로 고치지 않는다는 STO-RR-04와 같은 방향이다. inspect()가 판정 불가를 verified:false로 합치는 것 (0929/02-02)은 그대로다. service-worker-pwa 번들 9,716 → 9,733 / 10,100 gzip B. 검증: - RED: public-response-cache-repair.test.ts 새 테스트가 활성화 INTEGRITY_FAILED/REHYDRATE(기대 UNAVAILABLE/RETRY)로 실패. - GREEN: 같은 파일 10건 통과. 바이트가 다르면 여전히 INTEGRITY_FAILED 인지 보는 테스트를 같이 넣었다. cache 단위 3파일 + tests/recipes 62건 통과. check:types 통과. check:optional-recipes:source PASS. Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 02-02 |
||
|
|
e40684b4e1 |
chore(review): 리뷰 기준으로 두 작업 브랜치를 합친다
문제 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절)에 적는다. |
||
|
|
c05f41a63e |
fix(http): KEYED 명령이 백엔드의 실행 전 거절에 같은 키로 다시 보낸다
문제 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 |
||
|
|
048f490ada |
refactor(http)!: V2 HTTP 클라이언트를 지우고 V3 실행기 하나만 남긴다
문제
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으로 실행한다.
|
||
|
|
326120867c |
fix(http): 거절의 적용 여부를 백엔드 기준 표 하나로 V2·V3가 판정한다
문제 계약 문서 6.1절( |
||
|
|
17fa8d1f65 |
fix(realtime): live-poll handoff 마감 실패를 13.1의 kind로 보고한다 (04-02)
문제: 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 |
||
|
|
e5b7b3e857 |
fix(storage): partition 삭제가 다른 탭의 진행 중인 put을 기다린다 (0929/05-01)
문제: 손상 때문에 끝나지 못한 LOGOUT·ACCOUNT_DELETION purge의 partition 삭제는 두 단계다. 디렉터리를 origin lease 안에서 지우고, 이어서 journal row를 lease 밖에서 지운다. origin lease는 put의 BEGIN~FINISH만 막는다. 그래서 다른 탭에서 journal `begin`을 끝낸 put이 두 단계 사이에 BEGIN을 하면 새 디렉터리에 파일을 쓰고, 두 번째 단계가 그 put의 row를 지운다. put은 다음 journal 단계에서 `CONFLICT`로 실패하지만 파일을 치울 주체가 없다. - markFilesReady 전에 row가 지워지면: 보상이 manifest·staging을 지우고 chunk가 남는다. - commitPut 전에 지워지면: 보상이 없어 manifest·FILES_READY staging receipt·chunk가 남는다. staging receipt가 chunk를 GC·sweep에서 지키고 row가 없어 reconcile도 보지 않으므로 영원히 남는다. 다음 LOGOUT purge는 `chunkSweep: COMPLETED`를 보고하면서 이 bytes를 남긴다. - commit 뒤 complete 전에 지워지면: put은 성공하지만 object는 없고 manifest·chunk가 남는다. 삭제 전체가 put의 FINISH~commit 사이에 들어가는 경우(72edb55가 가정한 경우)는 수정 전에도 put이 `CONFLICT`로 실패하고 bytes가 남지 않았다. 고른 방법: partition 단위 Web Lock (`<mutationLockName>:partition:<a>:<ns>:<p>`)을 둔다. 모든 put·delete는 `withTransactionLock` 안에서 journal `begin`부터 끝날 때까지 shared로 쥐고, partition 삭제는 디렉터리·journal 두 단계를 exclusive로 쥔 채 한다. mutation은 삭제 전체보다 앞이거나 뒤에만 놓인다. 진행 중이던 put은 끝난 뒤 삭제가 지우고, 삭제가 lock을 요청한 뒤 온 put은 삭제 뒤에 돈다. lock 순서는 partition lock → origin lease 하나뿐이라 교착이 없다 (per-transaction lock은 `ifAvailable`이라 기다리지 않는다). 기다리는 동안 purge `signal`을 abort하면 `ABORTED`를 반환한다. 버린 대안: - commitPut `CONFLICT`면 보상: commitPut 전 경우만 고치고 chunk와 commit 뒤 경우가 남는다. 또 port가 "CONFLICT = 아무것도 commit 안 됨"을 약속하지 않아 동봉 구현에 기대는 숨은 결합이 생긴다. - commit까지 origin lease 쥐기: lease는 worker 안에 있고 journal은 page 쪽이다. 두 번째 단계(row 삭제)가 lease를 쓰지 않아 commitPut 전 경우가 그대로다. - row를 먼저 지우고 디렉터리를 나중에: 그 사이 begin한 put이 디렉터리 단계 전에 FINISH하면 파일 없는 COMMITTED row가 생긴다. 중간 실패 뒤 재호출로 이어서 끝나는 성질도 잃는다. - 디렉터리 → row → 디렉터리: 같은 이유로 파일 없는 commit이 생긴다. 위험·한계: - 삭제는 진행 중인 put·delete를 기다린다. source가 멈춘 put은 put idle bound(05-07)까지 삭제를 붙잡는다. 수정 전에도 그 put은 origin lease를 쥐고 있어 디렉터리 단계가 같은 시간을 기다렸다. - reconcile은 partition lock을 쥐지 않는다. reconcile은 파일을 새로 쓰지 않으므로(검증·정리·finalize만) 삭제와 겹쳐도 bytes를 남기지 않는다고 보았고, 이 경우는 테스트하지 않았다. - put·delete마다 Web Lock 요청이 하나 늘어난다. - offline-indexeddb 레시피 gzip 37,327 → 37,423 B(한도 38,500). - 공개 타입·배럴 변경 없음. 검증: - RED(수정 전, put 결과 단언을 넣기 전): 새 it.each 5건 중 3건 실패. 디렉터리를 put BEGIN 전에 지운 경우만 실패했다. markFilesReady 앞: chunk 1개 남음. commitPut 앞: staging receipt·chunk· manifest 남음. complete 앞: chunk·manifest 남음. 삭제 전체가 FINISH~commit 사이인 2건은 통과(put CONFLICT, bytes 0). "put은 삭제 앞에 끝난다" 단언을 더한 뒤 수정 전 코드: 5건 모두 실패. - GREEN: 5건 + abort 테스트 1건 통과. 같은 5건 10회 반복 10/10. - `node scripts/run-vitest.ts run tests/unit/opfs-worker-runtime.test.ts tests/unit/opfs-byte-store.test.ts tests/unit/indexeddb-opfs-journal.test.ts tests/recipes` 136건 통과. - tsc app·test·web-worker·recipes 통과. 바꾼 파일 eslint 통과. `check-adapter-inventory` PASS, `check-optional-recipes`(source) PASS, `verify-documentation-readiness` PASS_SCOPED. - 미실행: `check:browser-file-storage-boundaries`·`check:architecture` (pnpm 필요), Playwright OPFS spec(webServer가 pnpm). Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.4 |
||
|
|
bd83b496cc |
fix(http): V3 Envelope 진단이 V2와 같은 멱등성 거절 reason을 싣는다
문제 V2 클라이언트는 짝 백엔드의 422 IDEMPOTENT_REQUEST_MISMATCH와 400 IDEMPOTENCY_KEY_INVALID를 진단(http.request.completed)의 reason으로 남긴다( |
||
|
|
7db32e1343 |
fix(http): V3 실행기가 짝 백엔드 Envelope를 operation 단위로 읽는다
문제
create:feature가 만든 기능과 참조 기능이 쓰는 V3 실행기
(http-execution-v3.ts, feature-http-binding.ts)는 성공 본문을 DTO로,
실패 본문을 problem details(최상위 code)로 바로 검증한다. 짝 백엔드는
모든 JSON 응답을 Envelope {success, data|error, meta}로 보내고 null 필드는
키째 뺀다(백엔드 docs/web/http-contract.md 1절). 그래서 생성한 기능은 짝
백엔드의 성공을 SCHEMA_MISMATCH로, 실패를 PROBLEM_SCHEMA_INVALID(쓰기는
결과 불명)로 읽는다. 백엔드 맞추기(969979d~64e98ee)는 V2 클라이언트에만
들어갔다.
고른 방법: (가) V3 실행기에 operation 단위 Envelope 읽기
- V3 descriptor에 선택 필드 responseEnvelope("NONE" | "ENVELOPE_V1")를
둔다. 조립은 이 키를 허용하고 모르는 값을 거부한다. 값이 없으면 지금과
같다.
- ENVELOPE_V1이면 실행기가 바이트 상한·구조 예산을 Envelope 전체에 건 뒤
프레임을 확인한다. outputValidator는 data(키가 없으면 null),
problemValidator는 error를 받는다. 성공 status에 Envelope가 아닌 본문은
새 위반 ENVELOPE_MISMATCH다. 실패 Envelope의 바이트 상한은
min(64 KiB, responseByteLimit)이다.
- V2 client.ts의 멱등성 거절 표·필드 검증 판정·gateway status 규칙을
backend-envelope.ts로 옮기고 V2, V3 실행기, feature binding이 함께
읽는다. 실행기는 그 표의 판정(422·400 거절, 필드 목록 400은 적용 안 됨,
409 IDEMPOTENT_IN_FLIGHT·503 IDEMPOTENCY_UNAVAILABLE은 결과 불명)을
classifyProblem보다 먼저 쓴다. binding은 mapProblem이 답하지 않으면 V2와
같은 kind·code·validationIssues로 읽는다. V2 출력은 바뀌지 않았다.
- create:feature 뼈대: contribution이 ENVELOPE_V1을 선언하고 problem
스키마가 Envelope error(code 필수)다. 백엔드 본문을 그대로 적은
<base>-http-gateway.test.ts를 생성한다.
- MSW createHttpScenarioHandler는 descriptor가 ENVELOPE_V1이면 Envelope로
답한다.
버린 대안
- provider 단위(실행기 전체): V3 실행기는 baseUrl 하나라 앱 전체가 바뀐다.
참조 기능·테스트 계약의 problem details fixture가 모두 깨지고 한 앱이 두
모양의 API를 쓸 수 없다.
- (나) 백엔드 problem+json·DTO 모드: 백엔드 소유자 결정 2(JSON은 모두
Envelope)와 반대이고 백엔드가 두 모양을 계속 유지해야 한다.
- (다) 기능 스키마가 Envelope를 감쌈: 기능마다 null 생략·success 판별·
멱등성 판정을 다시 쓰고, V2 행(data 스키마)과 V3 스키마 ID가 갈라진다.
위험·한계
- HttpContractViolationKind에 ENVELOPE_MISMATCH가 더해졌다. default 없는
exhaustive switch는 분기를 더해야 한다.
- 실행기가 ENVELOPE_V1 operation의 위 판정을 classifyProblem보다 먼저
정한다. 패키지가 409 IDEMPOTENT_IN_FLIGHT를 적용 안 됨이라 해도 결과
불명이다.
- V2와 남은 차이: 64 KiB를 넘는 실패 Envelope는 V3만 읽지 않는다. 보낸
KEYED 요청의 503은 V2만 같은 키로 자동 재시도한다(판정은 같다). 구조
예산은 V3에만 있다.
- 참조 기능은 그대로 DTO·problem details다. tests/e2e/accessibility.spec.ts는
모든 API에 []로 답하므로 생성한 기능 라우트는 오류 화면이 검사된다(e2e는
돌리지 않았다).
- 초기 JS 202,770 → 203,321 B(+551 B, 예산 204,800 B).
검증
- RED: tests/integration/http-execution-v3-envelope.test.ts 19건 중 17건
실패(성공 → SCHEMA_MISMATCH, 실패 → PROBLEM_SCHEMA_INVALID·MAYBE_APPLIED,
조립 → unexpected key: responseEnvelope). 크기 2건은 처음부터 통과(동작
고정).
- GREEN: 같은 파일 25건 통과. 같은 응답을 V2와 V3에 보내 kind·code·
httpStatus·effect·retryAfterMs·validationIssues가 같음을 7가지 응답으로
비교한다.
- check:types, lint, check:architecture, check:adapter-inventory,
check:registries, check:diagnostics, check:i18n, check:ci 통과.
test:unit 2,604, test:component 244, test:integration 200 통과.
tests/features·tests/contract 124건 통과.
test:feature-scaffold 16개 검사 통과(생성한 gateway 테스트 5건,
Envelope로 답하는 목록 화면 테스트 3건 포함).
test:sample-removal 23개 검사 통과.
check:bundle 통과(203,321 / 204,800 B).
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.3, 14.6
|
||
|
|
b26517e6f2 |
fix(docs): 설계 주석에 문서 이름을 붙이고 지운 뒤 끊기는 링크를 없앤다 (1101/14-01)
문제: 코드 주석 87곳(74파일, .dependency-cruiser.json 포함)이 "Spec §N" 처럼 문서 이름 없이 절 번호만 적는다(대문자 83, 소문자 "spec §" 4). 가리키는 설계서는 README가 복사 뒤 지워도 된다고 한 docs/reviews/ 안에 있었다. 지울 수 있는 기록 검사는 경로 문자열만 찾아 이 참조를 잡지 못했다. 현재 계약 문서도 지울 수 있는 파일로 링크한다: docs/reviews/adapters/INVENTORY.md 145행이 옆의 adapter 리뷰로, docs/operations/adapter-remediation-ledger.md가 adapter 리뷰와 docs/superpowers/plans의 계획으로. 고른 방법: - 주석의 "Spec §"/"spec §"를 "scale-architecture.md §"로 바꾼다(앞 커밋이 옮긴 docs/architecture/scale-architecture.md). 설명 문장과 절 번호는 그대로다. 절 번호가 없는 "Spec §"는 없었다. - tests/unit/deletable-history-documents.test.ts에 "spec" + 선택 공백 + "§"(대소문자 무시)를 거부하는 검사를 더하고, 검사 대상에 .dependency-cruiser.json을 넣는다. - README "Files you can delete after copying"에서 INVENTORY.md 한 파일 대신 docs/reviews/adapters/ 폴더를 남기게 하고 이유(INVENTORY 행과 ledger가 그 리뷰로 링크한다)를 적는다. docs/README.md §3도 같게 고친다. INVENTORY의 행 구조는 바꾸지 않는다. - 남긴 adapter 리뷰와 ledger가 docs/superpowers/plans로 거는 링크 5곳은 링크를 풀고 "작업 이력 계획, 복사본은 지울 수 있다"로 적는다. 버린 대안: INVENTORY 145칸의 링크를 그룹 이름으로 바꾸기. 템플릿에서도 상세 리뷰로 가는 길이 없어지고 수정이 145곳이다. 계획 3개도 지우기 목록에서 빼기. 지울 수 있는 폴더 안에 예외가 흩어지고, 계획이 다시 다른 이력을 가리키면 남길 목록이 계속 커진다. 위험·한계: 검사는 "HTML spec §4"처럼 다른 명세를 "spec §"로 부르는 주석도 거부한다. 그때는 "HTML Standard §4"처럼 이름을 쓴다. src/contracts/storage-keys.ts:79의 "release-coherence plan Task 6"처럼 이름 없는 계획 참조는 이 검사가 잡지 않는다. 복사한 프로젝트가 이미 docs/reviews/adapters/를 지웠다면 링크는 계속 끊겨 있다. CHANGELOG.md의 이력 언급 4곳(:15 두 경로, :75 PRODUCT.md, :93)은 고치지 않았다. check:remediation-ledger는 이 변경 전후 같은 4줄로 실패한다(이미 있던 실패, 게이트 밖). tests/unit/telemetry.test.ts의 describe 이름 하나가 바뀐다. 검증: - RED: 치환 전 새 검사가 87줄을 들어 실패(1 failed | 1 passed). - GREEN: 같은 테스트 2 passed. 변이 "// Spec §4. budgets live here"를 src/platform/errors/app-error.ts에 넣으면 그 한 줄로 실패, 되돌림. - 치환 diff: 바뀐 87줄 쌍이 토큰 외에 같음(스크립트 대조, 불일치 0). - 삭제 실험(작업 트리 복사본에서 README 목록대로 지움): 끊긴 링크 148→0, 끊긴 경로 언급 10→4(남은 4는 CHANGELOG.md), 이름 없는 설계 참조 87→0, scale-architecture.md §N 87곳 중 없는 절 0. 같은 복사본에서 verify-documentation-readiness PASS_SCOPED, 지울 수 있는 기록 테스트 2 passed. - node scripts/verify-documentation-readiness.ts: PASS_SCOPED - node scripts/check-adapter-inventory.ts: PASS - node scripts/run-vitest.ts run tests/unit/deletable-history-documents.test.ts tests/unit/documentation-readiness.test.ts tests/unit/telemetry.test.ts: 50 passed. tests/architecture: 39 passed. - npx tsc --noEmit (app·node·test): 모두 통과. 바꾼 TS 74파일 eslint 통과. .dependency-cruiser.json JSON 파싱 통과. - 미실행: check:architecture(pnpm 필요). |
||
|
|
64e98ee2fa |
fix(http): V2 검증 거절을 적용 안 됨으로 보고 고친 값을 다시 저장하게 한다 (백엔드 1101/02-01)
문제
V2 클라이언트(client.ts)는 필드 검증 거절(422, 짝 백엔드의 400
VALIDATION_FAILED + 필드 목록)에 effect를 붙이지 않는다. mutation
코디네이터(application-query.ts mutationFailureWithEffect)는 effect가 없으면
MAYBE_APPLIED로 보고 admission을 UNKNOWN으로 붙든다. 폼은 VALIDATION_
REJECTED를 필드 오류로 보여 주지만, 참조 폼 페이지는 코디네이터가 결과 불명을
들고 있으면 저장 버튼을 끈다(reference-resource-form-page.tsx
mutationBlocked). 사용자가 필드를 고쳐도 다시 저장할 수 없다. use-app-form
자체는 VALIDATION_REJECTED에서 unknownSubmissionRef를 비우므로 막지 않는다.
막는 것은 코디네이터 상태다.
V3 참조 기능은 재현되지 않는다. 생성 분류기가 400·422를 NOT_APPLIED로
본다(reference-feature-contract-contribution.ts classifyProblem).
고른 방법
V2에서 필드 검증 거절(fieldValidation: 422, 또는 400 VALIDATION_FAILED +
배열 details)에 effect NOT_APPLIED를 붙인다. 멱등성 거절(IDEMPOTENCY_
REFUSALS)과 같은 자리에서 붙이고, 진단 reason은 멱등성 거절에만 남긴다.
근거(백엔드 계약)
- docs/web/http-contract.md 4절과 web adapter README 예외 표가 VALIDATION_
FAILED의 출처를 적는다: 요청 본문 바인딩(MethodArgumentNotValid
Exception), 컨트롤러 파라미터 제약(HandlerMethodValidationException),
Bean Validation(ConstraintViolationException), 페이지 파라미터, 읽을 수
없는 본문. 모두 요청을 묶는 단계에서 컨트롤러·use case보다 먼저 거절한다.
- 4절에 "상태를 바꾸지 않는다"는 문장은 없다. 이 판정은 위 출처에서
끌어낸 것이다.
버린 대안
- 코디네이터가 effect 없는 VALIDATION_REJECTED를 모두 NOT_APPLIED로 보기:
거절을 판정하는 곳은 응답을 읽는 클라이언트다. 코디네이터의 "모르면
MAYBE_APPLIED" 규칙은 그대로 둔다.
- 폼 페이지가 VALIDATION_REJECTED 뒤 결과 불명을 무시하기: 키가 붙은 채
남아 같은 입력을 다시 저장하면 같은 키가 나간다.
위험·한계
- application 층에서 쓰기 뒤에 VALIDATION_FAILED를 던지는 백엔드 코드가
있다면 이 판정은 틀린다. 짝 백엔드 IdempotencyExecutor는 실행 중 예외를
EFFECT_UNKNOWN_ABANDONED로 기록한다. 이 경우 같은 키 재전송은 500
IDEMPOTENCY_RECOVERY_REQUIRED를 받는다. NOT_APPLIED면 다음 저장이 새 키를
쓰므로 그 경로를 타지 않는다.
- 필드 목록 없는 400 VALIDATION_FAILED({cause}, 본문 파싱 실패)와 그 밖의
400·409는 effect 없이 둔다(결과 불명으로 붙듦). 이번 범위 밖이다.
- 422 IDEMPOTENT_REQUEST_MISMATCH는 원래 NOT_APPLIED였고 그대로다.
검증
- RED: tests/component/form-foundation.test.tsx "saves the corrected value
after a $status field error" 2행(422, 400 VALIDATION_FAILED) 실패. 필드
오류 뒤 저장 버튼이 disabled다.
- V3: tests/features/reference-feature/reference-production-vertical.test.tsx
"saves the corrected value after a server 422 field error"는 수정 전에도
통과한다(재현 안 됨, 동작 고정).
- GREEN: 위 행 통과. tests/integration/http-diagnostics.test.ts의 "unrelated
422" 행은 effect가 없다고 기대하던 것을 NOT_APPLIED로 바꾸고, 409 행을
더해 다른 거절은 effect가 없음을 고정했다. tests/integration/http-client.
test.ts에 400 VALIDATION_FAILED effect 단언을 더했다.
tests/unit·contract·runtime-schema·integration·component·features·platform
3398 tests 통과, 1개 실패(tests/unit/second-api-feature-registries.test.ts,
기준 3b7d73a에서도 같은 메시지로 실패). tsc app·test, 바꾼 파일 eslint
통과.
Refs: clean-architecture-backend-template docs/web/http-contract.md 4절, src/adapter/inbound/web/README.md 예외 표
|
||
|
|
02e35d2b38 |
fix(http): 짝 백엔드의 400 VALIDATION_FAILED를 폼 필드 오류로 읽는다 (백엔드 1101/02-01)
문제
짝 백엔드는 필드 검증 실패를 400 VALIDATION_FAILED로 보낸다. details는
위반 하나마다 {field, code, message}인 배열이다(백엔드 docs/web/http-
contract.md 4절, ClientSafeValidationDetails). field는 점으로 이은 속성
이름이고 인덱스는 뺀다. 클래스 수준 오류는 "request"다.
프론트 V2 클라이언트(client.ts)는 422만 필드 검증으로 읽는다. 400은
UNKNOWN_CLIENT_FAILURE이고 validationIssues가 없어서, 폼(use-app-form.ts)이
필드 오류 대신 "unavailable" 상태를 보인다. safeValidationIssues도
{issues}·{fieldErrors} 객체만 읽어서 배열 details를 버린다.
고른 방법
- V2: 400 + code VALIDATION_FAILED + details가 배열이면 422와 같은 것으로
본다. kind VALIDATION_REJECTED와 validationIssues를 422 경로와 같은 식으로
만든다. 폼은 기존 mapValidationFailureToFields와 allowedServerFields를
그대로 쓴다. 새 폼 경로는 없다.
- safeValidationIssues: details가 배열이면 각 항목의 field를 path로 읽는다.
message는 버린다. 후보 수는 기존 상한(MAX_VALIDATION_ISSUE_CANDIDATES)으로
자른 뒤 projectValidationIssues에 넘긴다.
- 그 밖의 400은 그대로 둔다: details가 {cause}인 VALIDATION_FAILED(본문
파싱 실패), details 없는 VALIDATION_FAILED, BAD_PARAMETER,
IDEMPOTENCY_KEY_INVALID(NOT_APPLIED 판정 유지).
버린 대안
- 400 VALIDATION_FAILED 전체를 VALIDATION_REJECTED로: 파싱 실패 같은
클라이언트 버그가 "입력값을 다시 확인해 주세요."로 보인다. 필드 목록이
있을 때만 바꾼다.
- 공용 projectValidationIssues가 field를 path 별칭으로 받게: zod 이슈와
V3 경로까지 같은 규칙을 갖게 된다. 백엔드 wire 모양은 V2 전용
safeValidationIssues에서만 읽는다.
- V3 참조 기능 mapProblem도 바꾸기: 참조 fixture는 problem+json
(type·title·status·issues)이라 짝 백엔드 Envelope가 problem 검증을 통과하지
않는다. 짝 백엔드 wire를 읽는 곳은 V2다.
위험·한계
- 백엔드 code(NOT_BLANK, SIZE 등)는 폼 문구 표(VALIDATION_COPY)에 없어서
필드 문구가 "입력값을 확인해 주세요."(form.validation.unknown)다. 필드
위치는 맞게 표시된다. 코드별 문구는 이 변경 밖이다.
- 페이지·정렬 파라미터 검증(PageValidationException)은 details가 배열이
아닌 단일 {field, code}라 지금처럼 UNKNOWN_CLIENT_FAILURE로 남는다. 폼
입력이 아니라 목록 조회 파라미터다.
- V2 필드 검증 실패에는 effect가 없다(422와 같다). mutation 코디네이터는
이것을 MAYBE_APPLIED로 보고 admission을 붙든다. 422에도 있던 기존 동작이다.
검증
- RED: tests/component/form-foundation.test.tsx 새 행이 실패. V2
클라이언트가 400 VALIDATION_FAILED를 받으면 폼 결과가 "unavailable"이고
Name 필드에 aria-invalid가 없다. tests/integration/http-client.test.ts
"reads the field details as validation issues" 실패(kind
UNKNOWN_CLIENT_FAILURE, issues 없음). 다른 400 3행은 처음부터 통과(유지
동작 고정).
- GREEN: 위 행 모두 통과. tests/unit·contract·runtime-schema·integration·
component·features·platform 283 files 중 282 통과, 3394 tests 통과.
실패 1개(tests/unit/second-api-feature-registries.test.ts "passes
check-registries…")는 기준 3b7d73a에서도 같은 메시지로 실패한다.
tsc app·test·node 통과, 바꾼 파일 eslint 통과, check:registries PASS.
Refs: clean-architecture-backend-template docs/web/http-contract.md 4절
|
||
|
|
47fec5c27c |
fix(query): 처리 중 409의 Retry-After 전 재전송은 그 시각까지 기다린다 (백엔드 1101/02-01)
문제
짝 백엔드는 같은 키의 첫 요청이 아직 실행 중이면 409
IDEMPOTENT_IN_FLIGHT, retryable=true, Retry-After: 2를 준다(백엔드
docs/web/http-contract.md §2). 클라이언트 행동은 "같은 키로 Retry-After 뒤
재전송"이다.
- 같은 키: 0929/03-01이 이 409를 MAYBE_APPLIED로 두어 코디네이터가 intent를
붙든다. 재전송은 같은 키를 쓴다(기존 vertical 테스트가 [K, K, K]를
고정). 이 부분은 이미 맞다.
- Retry-After: 지키지 않는다. V3는 응답 metadata에 retryAfterMs를 읽지만
feature binding이 PROBLEM을 AppFailure로 옮길 때 버린다. V2는 409의
Retry-After를 읽지 않는다. 그래서 결과 불명 화면의 "같은 요청으로 다시
보내기"(또는 같은 입력 다시 저장)를 바로 누르면 즉시 나가서 같은 409를
한 번 더 받는다.
고른 방법
재전송이 그 시각 전이면 기다렸다 보낸다.
- feature binding이 PROBLEM의 metadata.retryAfterMs를 AppFailure에 싣는다.
V2는 409의 Retry-After도 읽는다(409는 여전히 자동 재시도하지 않는다).
- mutation 코디네이터(application-query.ts)가 MAYBE_APPLIED로 남기는
admission에 resendNotBefore = 지금 + min(retryAfterMs, 5초)를 적는다.
같은 intent를 다시 쓰는 submit(재전송 버튼, 같은 입력 저장)이 그 시각까지
기다린 뒤 보낸다. 기다리는 동안 admission이 ACTIVE라 화면은 pending이다.
scope가 바뀌면 기존 mutationFn 검사가 NOT_STARTED로 막는다.
- 상한 5초는 V3 실행기의 Retry-After 상한(RETRY_AFTER_CEILING_MS)과 같다.
더 일찍 보내도 같은 키라 서버가 다시 409를 줄 뿐 두 번 적용하지 않으므로,
긴 Retry-After를 다 기다리게 하지 않는다.
버린 대안
- Retry-After 전에는 버튼을 막기: 화면과 시각 회귀 골든이 바뀌고, 다시
열어 줄 타이머와 문구가 더 든다. 기다렸다 보내는 쪽이 변경이 작다.
- V3 실행기가 키별 "이 시각 전 금지" 표를 들기: 실행기에 키를 기억하는
상태와 정리 규칙이 생긴다. 재전송을 만드는 곳은 코디네이터 하나다.
- 그대로 두기(이른 재전송은 409를 한 번 더 받을 뿐): 서버 문서가 허용하는
동작이지만 사용자는 같은 결과 불명 화면을 한 번 더 본다. 요구는
Retry-After를 지키는 것이다.
위험·한계
- AppFailure.retryAfterMs가 V3 PROBLEM에도 실린다(추가 필드). 이 값을 읽는
곳은 코디네이터뿐이다.
- 기다림은 MAYBE_APPLIED로 남은 admission을 다시 보낼 때만 생긴다. 다른
상태(NOT_APPLIED 등)는 그대로다.
- 시계는 performance.now(), 대기는 setTimeout이다. 탭이 백그라운드면
브라우저가 타이머를 늦출 수 있다(더 늦게 보낼 뿐이다).
검증
- RED: 4행 실패.
- tests/features/reference-feature/reference-production-vertical.test.tsx
처리 중 409(Retry-After: 1) 뒤 재전송 간격 39.7ms(기대 990ms 이상)
- tests/component/application-mutation-admission.test.tsx 재전송이
retryAfterMs 300을 기다리지 않음
- tests/features/reference-feature/reference-http-problem-mapping.test.ts
retryAfterMs 없음
- tests/integration/http-client.test.ts V2 409 retryAfterMs 없음
상한 행은 수정 전에도 통과하고, 상한을 뺀 변이에서 시간 초과로 실패하는
것을 확인했다.
- GREEN: 위 행 모두 통과. tests/component·features·contract/reusable-
capability, tests/integration/http-client·http-diagnostics, tests/unit/
http-execution-v3 62 files 491 tests 통과. tsc app·test 통과, 바꾼 파일
eslint 통과.
Refs: clean-architecture-backend-template docs/reviews/2026-11-01-maturity-review/README.md 14.3, 15
|
||
|
|
93782b0fce |
fix(http): 멱등성 거절 422·400을 적용 안 됨으로 보고 원인을 남긴다 (백엔드 1101/02-01)
문제
짝 백엔드는 KEYED 요청을 실행하기 전에 두 가지를 거절한다(백엔드
docs/web/http-contract.md §2).
- 422 IDEMPOTENT_REQUEST_MISMATCH: 같은 키에 다른 본문. 클라이언트 버그.
- 400 IDEMPOTENCY_KEY_INVALID(details.reason MISSING·MALFORMED): 키 누락·
형식 오류.
둘 다 이 요청은 적용되지 않았고, 그대로 다시 보내면 같은 답이 온다.
- V2(client.ts)는 이 실패에 effect를 붙이지 않는다. mutation 코디네이터는
effect가 없으면 MAYBE_APPLIED로 보고(application-query.ts
mutationFailureWithEffect) 키를 붙든다. 400은 결과 불명 화면으로 가고,
같은 입력을 다시 저장하면 같은 키로 같은 400·422를 계속 받는다. 진단
이벤트(http.request.completed)에는 원인이 없다.
- V3 참조 기능은 분류기가 400·422를 이미 NOT_APPLIED로 본다. 다만
mapProblem이 400을 다루지 않아 code가 CONTRACT_PROBLEM으로 바뀌고
서버의 IDEMPOTENCY_KEY_INVALID가 사라진다.
고른 방법
- V2: 문서에 적힌 status와 code가 둘 다 맞을 때만 effect NOT_APPLIED를
붙인다(IDEMPOTENCY_REFUSALS 표). 같은 표가 진단 reason을 준다.
- 422 → reason IDEMPOTENT_REQUEST_MISMATCH
- 400 → reason IDEMPOTENCY_KEY_RULE_MISMATCH. 프론트는 보내기 전에
isValidIdempotencyKey로 키를 검사한다. 서버의 400은 두 키 규칙이
어긋났다는 뜻이라 그 이름으로 남긴다. 보내기 전 거절(VALIDATION_
REJECTED, httpStatus 없음)은 표에 걸리지 않는다.
reason은 diagnostics에만 넣는다. telemetry 속성은 그대로다(VD-07).
- V3 참조 mapProblem: 400 + IDEMPOTENCY_KEY_INVALID만 UNKNOWN_CLIENT_
FAILURE와 서버 code로 둔다. 다른 400은 기존 fallback 그대로다.
- kind는 바꾸지 않았다(422 VALIDATION_REJECTED, 400 UNKNOWN_CLIENT_
FAILURE). 둘 다 retryable:false이고 V2 재시도 대상이 아니다.
- 키 문법은 백엔드 IdempotencyKeyHeader([\x21-\x7E]{1,256}, trim 없음)와
같다. 1자 키를 받는 행을 더해 경계를 고정했다.
버린 대안
- code만 보고 판정: 다른 status에 같은 code가 오면 NOT_APPLIED를 잘못
붙인다. NOT_APPLIED는 다음 저장이 새 키를 쓰게 하는 판정이라 문서의
짝(status+code)만 믿는다.
- 422 mismatch를 UNKNOWN_CLIENT_FAILURE로 바꾸기: 화면 문구가 바뀐다.
요구는 재전송 금지·결과 불명 화면 금지·원인 code 보존이라 kind는 두었다.
- 서버 code를 진단 reason에 그대로 넣기: 서버 code는 무제한이라 진단
cardinality 규칙(taxonomy)을 깬다. 표에 있는 두 값만 넣는다.
위험·한계
- 422 mismatch를 NOT_APPLIED로 보면 다음 저장이 새 키를 쓴다. 같은 키의
앞선 요청이 적용됐을 수 있지만, 프론트는 canonical 입력이 같을 때만 키를
재사용하므로 mismatch는 지문 규칙이 어긋난 버그다. 결정(15절)대로 이번
요청은 적용되지 않았다고 본다.
- 422 화면 문구는 "입력값을 다시 확인해 주세요."다. 사용자가 고칠 입력이
아니지만 다시 저장하면 새 키로 나간다.
- V3 실행기의 진단은 problem code를 모른다(Problem 타입은 계약 패키지
소유). V3에서 원인은 AppFailure.code·httpStatus로만 보인다.
검증
- RED: tests/integration/http-diagnostics.test.ts 새 2행 실패(effect
undefined, reason 없음). tests/features/reference-feature/reference-http-
problem-mapping.test.ts 400 IDEMPOTENCY_KEY_INVALID 행 실패(code
CONTRACT_PROBLEM). 422 mismatch 매핑, 분류기 2행, 1자 키 행은 처음부터
통과(이미 맞는 동작을 고정).
- GREEN: 위 파일과 tests/features/reference-feature, tests/integration/
http-client·http-execution-contract·auth-recovery·legacy-http-credential-
authority, tests/contract/reusable-capability/feature-http-binding 24 files
207 tests 통과. tests/unit/legacy-and-optional-network-remediation 6/6.
tsc app·test 통과, 바꾼 파일 eslint 통과.
Refs: clean-architecture-backend-template docs/reviews/2026-11-01-maturity-review/README.md 14.3, 15
|
||
|
|
969979d904 |
fix(http): 짝 백엔드가 생략한 Envelope 키를 null과 같이 읽는다 (백엔드 1101/02-02)
문제 짝 백엔드는 이제 값이 null인 필드를 키째 뺀다(백엔드 docs/web/http-contract.md §1). V2 Envelope 스키마 (src/adapters/http/schema-registry.ts)는 두 곳에서 "키 없음"을 null과 다르게 읽는다. - 성공 응답의 data: z.unknown()은 키가 없으면 거절한다(zod 4). 백엔드가 data:null을 빼고 보낸 성공이 ENVELOPE_MISMATCH 실패가 된다. data:null은 그대로 통과한다. - meta.requestId·traceId가 필수다. 백엔드는 요청 id 필터 앞에서 끊긴 응답(보안 entry point 등)에서 이 키를 뺄 수 있다고 적는다. 그러면 실패 Envelope 전체가 거절되어 백엔드 error.code가 HTTP_FAILURE로 바뀐다. error.details(키 없음 허용), meta.correlationId(선택), meta.page(strip)는 이미 키가 없어도 받는다. 고른 방법 - data를 z.unknown().default(null)로 둔다. 키가 없으면 스키마가 null을 채우므로 client.ts의 "data" in 검사와 payload 검증이 data:null과 같은 길을 탄다. 정규화가 wire 스키마 한 곳에 있다. - meta.requestId·traceId를 optional로 둔다. safeMeta()는 이미 키가 없는 경우를 처리한다. 버린 대안 - client.ts에서 "data" in 검사를 빼고 data ?? null로 읽기: 스키마와 클라이언트 두 곳이 같은 규칙을 나눠 갖는다. - 성공의 error:null, 실패의 data:null도 다시 받기: 백엔드가 더는 보내지 않는 모양이다. 최상위 strict는 그대로 둔다. 위험·한계 - meta id가 없는 Envelope도 이제 유효하다. 그런 응답의 HttpResult.meta와 AppFailure에는 requestId·traceId가 없다(이전에는 응답 전체가 거절됐다). - V3 실행기는 Envelope를 읽지 않는다(DTO 자체를 검증). 이 변경은 V2 경로만 바꾼다. bulk Envelope(results)는 프론트에 쓰는 곳이 없어 다루지 않았다. 검증 - RED: tests/integration/http-client.test.ts "envelope keys the paired backend omits" 5행 중 2행 실패. data 키 없는 성공이 ok:false, id 키 없는 403이 code HTTP_FAILURE. - GREEN: 같은 5행 통과. tests/integration/http-client·http-diagnostics· http-execution-contract·auth-recovery·legacy-http-credential-authority, tests/runtime-schema 8 files 150 tests 통과. tsc app·test 통과, 바꾼 파일 eslint 통과. Refs: clean-architecture-backend-template docs/reviews/2026-11-01-maturity-review/README.md 14.3, 15 |
||
|
|
72edb55475 |
fix(storage): 손상 행을 건너뛰고 끝나지 못한 삭제는 partition을 지운다 (0929/05-01)
문제: OPFS journal의 `listCommittedObjects`·`listIncomplete`는 손상 행
하나에 목록 전체를 `CORRUPT_DATA`로 실패시킨다. 그래서
- 승인된 LOGOUT·ACCOUNT_DELETION purge가 그 partition의 정상 객체까지
하나도 지우지 못하고, 개인 바이트가 기기에 계속 남는다.
- journal DB는 authority 단위라 손상 행 하나가 모든 partition의
reconcile과 orphan GC를 멈춘다.
스스로 풀리지 않고, runbook은 journal 수동 삭제를 금지해 출구가 없다.
고른 방법 (리뷰의 (c)):
1. 두 목록은 손상 행을 건너뛰고 `corruptRows`로 센다. 행은 지우지
않는다. 꽉 찬 페이지는 다음 행 앞에서 멈추므로 한 행은 그 행에 닿은
페이지에서 한 번만 센다. reconcile은 `corruptTransactions`로 보고하고,
0이 아니면 `OBJECT_RECONCILE` `DEGRADED` / `CORRUPT_DATA`로 관측한다.
2. LOGOUT·ACCOUNT_DELETION purge가 손상 때문에 끝날 수 없으면(건너뛴
object 행, 손상으로 `CORRUPT_DATA`가 된 remove나 chunk sweep,
`STAGING_STATE_UNREADABLE`) partition을 통째로 지운다.
- 승인: 기존 `maintenanceReasonAllowed` + authority proof 요청·소비를
통과한 뒤에만 이 지점에 온다. IndexedDB의 database 전체 삭제
(0929 05-03)와 같은 조건이다.
- 파일: 새 worker 요청 `REMOVE_PARTITION`이 origin mutation lease를
쥔 채 `authorities/<a>/<ns>/<p>`를 지운다.
- 행: 새 journal 메서드 `removePartition`이 그 partition 키로 시작하는
object·journal·chunk reference 행과 budget 행을 키로 찾아 지운다.
손상 행도 지워진다. scope binding 행은 남긴다.
- 보고: `partitionDeleted: true`, `corruptObjects`,
`moreObjectsAvailable: false`. 파일을 먼저, 행을 나중에 지워서 중간에
실패해도 다시 부르면 이어서 끝난다.
버린 대안:
- 현상 유지: 손상이 있으면 삭제가 영구히 실패한다.
- 1만: reconcile·GC와 정상 객체 purge는 돌지만 손상 행의 바이트가 남는다.
- journal DB 전체 삭제: 같은 authority의 다른 partition까지 지운다.
기존 테스트 주석("손상 행이 목록 전체를 실패시키는 것이 의도")과
runbook(`browser-file-storage-recovery.md`)을 새 동작에 맞게 고쳤다.
위험·한계:
- 공개 계약 변경. `OpfsJournalPort`에 `removePartition`, 두 page 타입에
`corruptRows`가 필수로 생겼다. journal이나 worker gateway를 직접 구현한
쪽은 추가해야 한다(adapter가 생성 시점에 TypeError로 알린다).
report에는 `corruptTransactions`(필수)와 `corruptObjects`·
`partitionDeleted`(선택)가 생겼다.
- lease는 put의 BEGIN~FINISH만 막는다. 그 밖에 있던 다른 tab의 같은
partition put은 journal 행이 지워져 다음 journal 단계에서 실패할
것으로 보지만, 이 경합은 실행으로 확인하지 않았다.
- partition 삭제는 IndexedDB 전체 삭제처럼 시간 예산에 묶이지 않는다.
- reconcile GC의 `isChunkReferenced` 손상(리뷰 근거 ③)과 reconcile 쪽
`STAGING_STATE_UNREADABLE`(④)은 이번 결정 범위 밖이다. purge에서만
partition 삭제로 빠져나간다.
- offline-indexeddb 레시피 gzip: 36,889 → 37,327 B (한도 36,900, 427 B
초과). 예산은 올리지 않았다.
- 실제 브라우저(Playwright OPFS spec)에서는 돌리지 않았다.
검증:
- RED (수정 전): journal 4건 실패 — `listIncomplete`·
`listCommittedObjects`가 `CORRUPT_DATA`, `removePartition is not a
function`. adapter·worker 4건 실패 — LOGOUT·ACCOUNT_DELETION purge가
`CORRUPT_DATA`, reconcile이 `CORRUPT_DATA`, `REMOVE_PARTITION` 뒤에도
디렉터리가 남음. 승인 거절 테스트는 수정 전후 모두 통과(가드).
- GREEN: `node scripts/run-vitest.ts run tests/unit tests/recipes`
177 files 2,523건 통과, `tests/contract` 41건 통과.
`tsc` app·test·node·web-worker·service-worker·recipes 통과, 바꾼 파일
eslint 통과, `check-adapter-inventory` 통과.
- 미실행: `check:browser-file-storage-boundaries`(pnpm 필요),
`check:architecture`(pnpm 필요), Playwright OPFS spec.
Refs: docs/reviews/2026-09-29-maturity-review/05-adapters-storage-kernel.md 05-01
|
||
|
|
c4052f0f8e |
fix(storage): 여러 페이지를 다 지운 purge를 끝났다고 보고한다 (1101/13.6)
문제: OPFS `enforcePolicies`의 LOGOUT·ACCOUNT_DELETION purge가 journal 목록을 두 페이지 이상 읽으면, 객체를 모두 지워도 `moreObjectsAvailable: true`를 보고하고 chunk sweep을 하지 않는다. 페이지를 넘길 때 `moreObjectsAvailable = page.value.moreAvailable`가 true를 넣고, 마지막 페이지의 `||=`가 그 값을 그대로 둔다. 호출자는 다시 불러야 끝나고, 그 사이 chunk 바이트가 기기에 남는다. 고른 방법: 페이지 넘김 대입을 지운다. 대신 "다음 페이지를 읽기 전에 멈췄다"(객체 한도나 시간 예산 소진)는 루프 머리에서 true로 적는다. `while` 조건을 루프 안 첫 검사로 옮긴 것이다. 0929/05-02(`85d8b59`)의 "건너뛴 객체가 있으면 true" 규칙은 그대로다. 그 값을 지우는 대입이 없다(마지막 페이지는 `||=`, PRESSURE 대입은 sweep하지 않는 purge). 버린 대안: 건너뜀 표시를 별도 변수로 나누기. 페이지 넘김 true가 남는 한 마지막 페이지에서 여전히 섞여 고쳐지지 않는다. 위험·한계: - 동봉 IndexedDB journal은 페이지 한도를 "남은 객체 한도"로 받아 꽉 찬 페이지를 돌려주므로, 한 번의 호출에서 두 번째 페이지가 생기지 않는다. 결함은 port가 허용하는 짧은 페이지를 돌려주는 journal에서 드러난다. 테스트도 그 journal(페이지 1개씩)로 재현했다. - 동작 차이 하나: 앞선 시간 검사를 통과한 직후 첫 페이지를 읽기 전에 시간이 다 되면, 전에는 `moreObjectsAvailable: false`로 sweep을 시도했고 이제는 true로 보고하고 sweep하지 않는다. 아무 객체도 읽지 않았으니 이쪽이 사실에 맞다. - offline-indexeddb 레시피 gzip: 36,896 → 36,889 B (한도 36,900). 검증: - RED: 새 테스트 "finishes a purge that walked more than one journal page"가 수정 전 `moreObjectsAvailable: true`, `chunkSweep` 없음으로 실패했다. - GREEN: `node scripts/run-vitest.ts run tests/unit/opfs-worker-runtime.test.ts tests/unit/opfs-byte-store.test.ts tests/unit/indexeddb-opfs-journal.test.ts` 103건 통과. `tsc` app·test·web-worker 통과, 바꾼 파일 eslint 통과. Refs: docs/reviews/2026-11-01-maturity-review/README.md 13.6절 |
||
|
|
6c5818faec |
refactor(contracts): bearer 인증 프로필을 EXTERNAL_BEARER로 바꾼다 (1101/16-03)
문제
유일한 bearer 인증 프로필 이름이 샘플 이름 REFERENCE_EXTERNAL_BEARER다.
세션이 필요한 제품 기능은 지운 샘플의 이름을 계속 쓰거나 템플릿 소유
파일에 프로필을 더해야 한다. 샘플 제거 드릴의 잔여 검사 정규식도 이
이름을 잡지 않아 샘플을 지운 제품에 그대로 남는다. 리뷰 (2) 오류
메시지는 abf3ce5가 했고 (1) 이름 변경이 남았다.
고른 방법 (2026-11-03 결정)
- 프로필 이름을 EXTERNAL_BEARER로 바꿨다. 참조 기능의 V2 operation 3개와
V3 descriptor 3개, external-session-adapter 주석, 테스트, VD-23 문서를
새 이름으로 옮겼다.
- 옛 이름은 한 릴리스 동안 REST_AUTH_PROFILES에 별칭 한 줄로 남기고
JSDoc @deprecated를 붙였다. 레지스트리는 키와 authProfileId가 같아야
하므로 별칭은 EXTERNAL_BEARER를 펼치고 id만 옛 이름으로 둔 객체다.
그래서 옛 이름을 적은 다운스트림 operation도 같은 transport·헤더로
해석된다.
- scripts/scale의 PLATFORM_TOKENS에서 이 이름을 뺐다. 참조 기능에 더는
"REFERENCE"가 든 프로필 이름이 없어 이름 바꾸기에서 보호할 것이 없다.
- 새 테스트 두 개: 별칭이 id만 빼고 EXTERNAL_BEARER와 같게 설치되는지,
src에 옛 이름이 별칭 한 줄 외에 없는지(완료 기준).
버린 대안
- 별칭 없이 바로 바꾸기: 옛 이름을 쓰는 다운스트림 기능이 모듈 로드에서
바로 실패한다. 공개 이름을 깨는 변경은 BREAKING 결정이 있을 때만 한다.
- 조회 시점의 이름 매핑(alias 표): resolve·executor·composition 세 곳이
매핑을 알아야 한다. 프로필 항목 하나가 더 작다.
위험·한계
- 설치된 프로필이 셋이 된다. 같은 설정이 두 id로 있을 뿐 권한이 넓어지지
않는다. 별칭은 다음 minor에서 지우고 CHANGELOG [계약] 행을 남긴다.
그때 "src only on the alias line" 테스트의 기대값을 빈 목록으로 바꾼다.
- 다운스트림 문자열 id("REFERENCE_EXTERNAL_BEARER")에는 @deprecated 표시가
보이지 않는다. CHANGELOG로 알린다.
- FE-REG-API 행 3개의 authProfileId가 바뀐다. breakingFields가 아니라
behavior-change이므로 증거 없이 게이트를 통과한다. 기준선 재승인은 이번
작업 묶음 끝에서 한 번에 한다.
- 초기 JS gzip(초기 청크 파일별 gzip 합) 203,818 → 203,840 B(+22 B). 별칭
항목이 rest-profiles가 있는 초기 청크에 실린다. 참조 기능 계약은 lazy
청크라 초기 크기에 영향이 없다.
검증
- RED(수정 전): rest-profile-contract.test.ts 새 사례 2건 실패("expected
undefined to match object { transport: 'BEARER_HEADER', …(1) }",
"expected [ …(9) ] to deeply equal [ Array(1) ]").
- GREEN: 같은 파일 10/10 통과. check-registries "11 registries PASS"
(FE-REG-API authProfileId 3건 behavior-change).
- 회귀: tests/{unit,integration,features,contract,runtime-schema}
207 파일 2,366건 통과(pnpm·corepack을 띄우는 6개 제외:
http-scenario-evidence, ci-workflow-generation, lab-performance,
fixture-node-modules, deployment-admission, security-followup-archive).
tsc app·test·node rc=0, 바꾼 파일 eslint rc=0. vite build 성공.
- 미실행: check:architecture, test:sample-removal(pnpm 필요), e2e.
Refs: docs/reviews/2026-11-01-maturity-review/16-structure-patterns.md
|