b5e7f54bd1f3fd4e2ff4e6f7e44d727cfcbc3bd3
1165
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
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 |
||
|
|
0edc3fc90a |
fix(provider): worktree의 .git 파일을 샌드박스에서 가리고 다른 checkout은 복사하지 않는다
문제 scripts/run-and-validate-provider.ts는 작업 폴더에 .git이 있으면 그 자리에 --tmpfs를 건다. git worktree나 서브모듈 checkout에서는 .git이 디렉터리가 아니라 "gitdir:" 한 줄짜리 파일이라 bubblewrap이 "Can't mkdir …/.git: Not a directory"로 끝난다. 그래서 worktree에서 test:system을 돌리면 사전 점검은 PASS인데 provider 테스트 16개가 샌드박스 회귀처럼 실패한다. 또 provider 기반 fixture는 현재 폴더를 통째로 복사해, checkout 안의 .claude/worktrees/*나 .tmp/* 같은 다른 checkout·드릴 fixture와 그 node_modules까지 /tmp/ci-provider-upload-*에 복사했다(시간 초과, ENOTEMPTY). 고른 방법 - .git이 디렉터리면 지금처럼 tmpfs로 가린다. 디렉터리가 아니면 /dev/null을 --ro-bind로 겹친다. bubblewrap은 bind를 nodev로 걸어서 provider는 그 줄을 읽지도 그 경로에 쓰지도 못한다. 파일이 가리키는 실제 git 디렉터리는 작업 폴더 밖이라 원래 샌드박스에 들어오지 않는다. - 리뷰 최소 개선 (1)(사전 점검이 worktree를 거부) 대신 (2)를 골랐다. 이 repo의 리뷰·수정 절차가 영역마다 worktree를 쓰므로, worktree에서 샌드박스 경계 테스트를 돌릴 수 있어야 한다. 비용도 몇 줄로 비슷하다. - 기반 fixture 복사에서 .claude, .worktrees, .tmp, graphify-out을 뺀다. 모두 추적하지 않는 폴더라 후보의 추적 파일 목록에는 영향이 없다. - 새 system 테스트 2건이 .git이 디렉터리일 때와 파일일 때 provider가 그 내용을 보지도 바꾸지도 못함을 확인한다. - 버린 대안: --dev-bind /dev/null. 읽으면 빈 내용이지만 쓰기를 받는다. --remount-ro를 더하면 nodev가 다시 걸려 --ro-bind와 같아진다. 빈 일반 파일을 호스트에 만들어 bind. 임시 파일의 수명·정리 경로가 하나 는다. 위험·한계 - .git 파일 자리에서 provider는 빈 파일이 아니라 열 수 없는 문자 장치를 본다(EACCES). 작업 폴더를 훑는 provider가 그 오류를 실패로 다루면 거기서 드러난다. - 마스크를 지우는 변이 확인은 부하(load 24) 때문에 systemd unit 수거가 늦어 결론을 내지 못했다(두 경우 모두 "provider unit remained loaded"). 검증 - RED: worktree에서 test:system 16 failed / 96 passed(모두 provider 묶음, 같은 bwrap 오류). 새 테스트는 수정 전 "file" 경우만 실패. - 수정 뒤 새 테스트 2건 통과(-t "hides repository metadata"). - eslint 통과. Refs: docs/reviews/2026-11-03-maturity-review/11-tests-browser-release-scale.md 11-04 |
||
|
|
1d17e7d2d1 |
docs(manual): 업무 거절 code를 refusedBeforeWrite에 적으라고 기능 추가 안내에 쓴다
문제 매뉴얼 01은 "필요하면 mapProblem을 둔다(예: 409, 422를 업무 실패로)"라고만 적는다. Envelope operation에서 mapProblem은 kind·code·필드 오류만 바꾸고 적용 여부는 바꾸지 못한다. 이 안내만 따르면 필드 오류는 보이지만 저장 버튼은 꺼진 채로 남는다(리뷰 08-01 P1의 mapProblem 행). 1e8b3d0이 더한 refusedBeforeWrite는 매뉴얼 02 4절에만 있다. 고른 방법 Envelope 실패 흐름 목록과 "정할 것"의 mapProblem 줄에 한 문장씩 더해 refusedBeforeWrite와 02 결정표 4절을 가리킨다. 5xx 판정 문장도 지금 표에 맞췄다. 위험·한계 문서만 바꿨다. 검증 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 |
||
|
|
90440082f9 |
test(system): provider 테스트 묶음 전체에 provider 시간 예산을 쓴다
문제 tests/system/ci-runner/ci-artifact-contract.test.ts는 provider 묶음에 30초 예산(PROCESS_HEAVY_TIMEOUT_MS)을 두고 "10s default is sized for pure-JS unit tests"라고 적는다. 그런데 같은 describe의 테스트 선언 8개(케이스 10개)는 여전히 10초다. 그래서 바쁜 호스트에서 "kills descendants … timeout termination"이 10,116 ms로 시간 초과해 FE-GATE-013이 가끔 빨개진다. 또 기반 fixture(build:release-candidate)를 처음 createProviderFixture()를 부른 테스트 안에서 만들어서, -t로 하나만 골라 돌리면 그 테스트가 빌드를 떠안아 항상 실패한다. 고른 방법 - describe 옵션으로 묶음 전체에 PROCESS_HEAVY_TIMEOUT_MS를 주고, 테스트마다 적은 10_000·15_000·20_000·30_000을 지운다. 40_000을 준 tar 폭탄 테스트 하나는 그대로 둔다. - 기반 fixture는 describe의 beforeAll에서 만든다. 상한은 빌드의 spawn 상한(120초)에 복사·압축 여유를 더한 180초다. - 버린 대안: 전역 testTimeout 올리기. 파일 주석이 이미 버렸다(진짜 멈춘 테스트를 숨긴다). 테스트마다 상수로 바꾸기. 상수를 안 쓰는 테스트가 다시 생길 수 있다. 위험·한계 - 실제로 멈춘 provider 테스트는 실패까지 최대 30초 걸린다. - runProviderSupervisor의 spawn 상한(기본 8초)은 바꾸지 않았다. 부하에서 systemd user manager가 느리면 "provider unit remained loaded"로 따로 실패할 수 있다(이번 실행에서 load 24일 때 한 번 봄, 운영 코드의 상한). - loadavg 20 이상에서 test:system 전체 5회 반복은 하지 않았다. 검증 - -t "kills descendants|hides repository metadata"로 골라 돌렸을 때 두 kills descendants 테스트가 통과(3.0 s, 2.9 s). 기반 빌드는 beforeAll이 떠안았다. - eslint 통과. Refs: docs/reviews/2026-11-03-maturity-review/11-tests-browser-release-scale.md 11-03 |
||
|
|
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 |
||
|
|
d9ca6537d8 |
docs(architecture): 캐시 문서의 밀린 줄 번호 참조를 심볼 이름으로 바꾼다
문제: 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 |
||
|
|
c4d587052e |
fix(removal): 참조 기능을 지워도 문서 게이트가 통과하고 드릴이 그것을 본다
문제 README는 참조 기능을 지울 수 있다고 적는다. 그러나 매뉴얼·입구 문서 10개가 참조 기능과 그 드릴 전용 파일의 경로를 백틱으로 적고, verify:documentation(FE-GATE-017)은 백틱 경로의 존재를 검사한다. 그래서 참조 기능을 지운 복사본에서 문서 게이트가 경로 24개로 실패한다. 제거 드릴(test:sample-removal)은 문서를 복사하지 않고 그 게이트와 lint· check:i18n·check:design-system을 돌리지 않아 이 충돌을 보지 못했다. 고른 방법 - 리뷰 5.2절 (b): 참조 기능이 가진 경로는 백틱 없이 "예제(참조 기능)"으로 적는다. 기능 공통 모양은 생성 경로 꼴(`src/features/<id>/domain`)로 적는다. 규칙은 docs/manual/reference/patterns.md 첫머리에 적었다. - 드릴은 REMOVAL_FIXTURE_DOCUMENT_TARGETS(README·CHANGELOG·docs)까지 복사하고, 지운 뒤와 생성 기능을 더한 뒤 두 번 모두 lint, verify:documentation, check:i18n, check:design-system을 돈다 (FOLLOW-UP 09-07). 문서 테스트 두 개도 fixture에서 다시 돈다. - 버린 대안: 검사기가 참조 기능 경로를 "없어도 되는 경로"로 보기(5.2 (c)). 매뉴얼이 없는 파일을 가리키는 상태를 허용한다. 참조 기능을 지울 수 없게 하기(5.2 (d)). README 약속과 드릴의 존재 이유가 바뀐다. 위험·한계 - 템플릿 자신에서도 참조 기능 경로의 존재를 문서 검사가 더는 보지 않는다. 참조 기능 파일 이름을 바꾸면 그 문장은 사람이 고쳐야 한다. - 드릴 시간이 lint·문서 검사 두 번만큼 는다. - 드릴 실제 실행 결과는 이 커밋 메시지에 적지 않았다(공유 잠금 대기). 검증 - 참조 기능·참조 context·SAMPLE_EXTRAS를 지운 복사본(scratchpad sim-sample-docs.sh)에서 수정 전 FAIL_UNVERIFIED(문서 10개), 수정 뒤 PASS_SCOPED. - 저장소에서 verify:documentation PASS_SCOPED, documentation-readiness 14건 통과, eslint 통과. Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-04 |
||
|
|
3bfe6a8580 |
test(cache-storage): 조회가 eviction 판정 전에 캐시 목록을 다시 읽는지 고정한다
문제: 조회는 cache 이름 목록을 pointer보다 먼저 읽는다. 그 사이 다른 탭의 activation이 pointer를 새 캐시로 옮기면 목록에 그 캐시가 없다. 코드는 목록을 한 번 더 읽고서야 STORAGE_EVICTED를 낸다 (1101/02-04 ⑤, N39). 이 재확인을 지워도 테스트가 모두 통과했다. 빠지면 방금 배포한 release의 첫 조회가 "지워졌다"로 끝나고 REHYDRATE로 간다. 고른 방법: 첫 keys()만 배포 전 목록을 돌려주는 저장소로 r2 활성화 뒤 조회한다. adapter는 만들 때 keys를 잡아 두므로 저장소 하위 클래스로 한 번만 낡은 답을 준다. 위험·한계: 테스트만 바꾼다. 1101/02-04의 N38(host storageArea 비교)은 pulse wire 값을 만드는 하네스가 필요해 이번에 하지 않았다. 검증: N39 변이를 넣으면 이 테스트가 STORAGE_EVICTED로 실패하고(cache 단위 3파일 + tests/recipes 71건 중 1건), 되돌리면 같은 파일 14건 통과. check:types:test, eslint 통과. Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 1101/02-04 |
||
|
|
f08c93ab2e |
fix(removal): 문서를 읽는 테스트 제외 목록을 모든 제거 드릴이 같이 쓴다
문제 FE-GATE-020의 제거 드릴은 정해진 목록만 fixture에 복사하고, 그 목록에 README.md·CHANGELOG.md·docs/가 없다. 그런데 fixture에서 도는 test:all에는 그 문서를 읽는 테스트 두 개(documentation-readiness, changelog-review-ids)가 들어 있다. sample-removal 드릴만 두 테스트를 지웠고, browser-file-storage·realtime·optional-recipe 드릴은 제거 대상과 무관하게 `test` 검사에서 ENOENT로 항상 실패했다. 세 드릴의 실패는 merge 게이트를 빨갛게 하고 release 단계도 막는다. 고른 방법 - scripts/lib/removal-fixture.ts에 문서 목록 (REMOVAL_FIXTURE_DOCUMENT_TARGETS)과 그 문서를 읽는 테스트 목록 (REMOVAL_FIXTURE_DOCUMENT_TESTS)을 한 번만 둔다. prepareRemovalFixture는 문서를 복사하지 않은 fixture에서 그 테스트를 지운다. 문서를 복사하는 드릴(test:feature-scaffold)에서는 그대로 돈다. - sample-removal 드릴의 자체 제외 두 줄을 지운다. - 버린 대안: 모든 드릴이 문서까지 복사. capability 드릴은 문서가 설명하는 runtime을 지우므로, 문서 테스트가 지운 경로를 실패로 본다. 드릴마다 문서 예외가 필요해진다. 드릴마다 제외를 복사. 지금 고장의 원인(갈라진 목록)을 되풀이한다. - 단위 테스트가 목록을 고정한다: 문서 없이 복사하면 제외, 문서를 복사하면 제외 없음, 제외 대상이 실제로 문서를 읽음, 다섯 드릴이 모두 prepareRemovalFixture를 쓰고 자체 제외 목록을 두지 않음. 위험·한계 - 저장소 루트 문서를 읽는 테스트가 더 생기면 이 목록에 더해야 한다. 더하지 않으면 capability 드릴이 다시 ENOENT로 실패한다(조용히 통과하지는 않는다). - 세 드릴의 실제 실행 결과는 이 커밋 메시지에 적지 않았다(공유 잠금 대기). 검증 - RED: 새 테스트 "is the only exclusion list"가 수정 전 sample 드릴의 자체 목록 때문에 실패. - tests/unit/removal-fixture.test.ts 12건 통과, 바꾼 파일 eslint 통과. Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 02-06 |
||
|
|
de2670cda5 |
test(cache-storage): no-cache와 Set-Cookie 응답 거절을 따로 고정한다
문제: 1101/02-04의 두 변이가 이번에도 cache 단위 테스트를 모두
통과했다. N26b는 Cache-Control: no-cache 거절, N26은 Set-Cookie 응답
거절을 지운다. 둘 다 빠지면 사용자별이거나 재검증이 필요한 응답이 익명
공용 캐시에 들어간다. 기존 표는 no-store·pragma·www-authenticate만 따로
보았다.
고른 방법: 응답 검증 표("keeps response validation failure codes")에 두
행을 더한다. 각 행은 규칙 하나만 어긴다.
위험·한계: 테스트만 바꾼다.
검증: 두 변이를 하나씩 넣고 cache 단위 3파일 + tests/recipes를 돌렸다.
둘 다 이 테스트가 실패했고 되돌린 뒤 통과. eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 1101/02-04
|
||
|
|
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
|
||
|
|
0a74bd42b0 |
test(browser-files): handoff 실패 lease 반환과 남은 보호 규칙 3개를 고정한다
문제: 이번 리뷰에서도 아래 browser-files 변이가 관련 unit 파일을 모두 통과했다. - M10(0929/02-05): bounded download의 catch에서 lease?.release()를 지운다. handoff가 던지면 만든 blob URL이 runtime dispose까지 남는다. - N27(1101/02-04 ③): 같은 파일을 다시 inspect할 때 이전 receipt를 무효화하지 않는다. 다른 정책으로 검사한 옛 receipt로 preview가 열린다. - N29(1101/02-04 ①): object URL lease의 합계 바이트 상한을 지운다. 기존 테스트는 개수 상한이 먼저 막아 바이트 상한을 보지 못했다. - N30(1101/02-04 ⑥): browser-managed handoff의 fragment 거절을 지운다. 고른 방법: 규칙마다 실패하는 테스트 하나. N29는 개수 여유가 있을 때도 바이트가 막는 경우를 기존 상한 테스트 끝에 더했고, N30은 target 규칙 표에 fragment href 한 줄을 더했다. 위험·한계: 테스트만 바꾼다. 1101/02-04의 나머지(N26·N26b는 다음 커밋, N38 host storageArea, N39 조회 keys() 재확인)는 이 커밋에 없다. 검증: 네 변이를 하나씩 넣고 browser-files 단위 5파일 + tests/recipes를 돌렸다. 모두 새 테스트(또는 늘린 행)가 실패했고 되돌린 뒤 통과. 원래 코드에서 두 파일 47건 통과. check:types:test, eslint 통과. Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 0929/02-05, 1101/02-04 |
||
|
|
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 |
||
|
|
b5c7128bda |
test(storage): Web Storage의 Firefox quota 이름과 만료 경계를 고정한다
문제: 2026-11-01 05-06에서 남은 두 분기를 테스트가 잡지 못한다. 이번 리뷰에서도 두 변이가 Web Storage 관련 테스트 3파일 49건을 통과했다. - W4: quota 판정 목록에서 Firefox의 NS_ERROR_DOM_QUOTA_REACHED를 빼도 테스트가 통과한다. 빠지면 Firefox의 quota 실패가 memory fallback 없이 STORAGE_UNAVAILABLE이 된다. - W8: 만료 비교 `<=`를 `<`로 바꿔도 통과한다. 만료 시각과 같은 순간에 값을 돌려준다. 고른 방법: 각 분기에 실패하는 테스트 하나씩. 저장소 test double에 Firefox 이름으로 던지는 모드를 더했고, 만료 경계는 expiresAt 100·101을 now 100에서 읽는다. 위험·한계: 테스트만 바꾼다. codec을 직접 부르는 테스트는 여전히 없다. 검증: W4·W8 변이를 하나씩 넣고 storage-registry·runtime-adapters· browser-storage-policy 테스트를 돌렸다. 둘 다 새 테스트가 실패했고, 원래 코드에서 storage-registry 26건 통과. check:types:test, eslint 통과. Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 1101/05-06 |
||
|
|
a6b85e878c |
test(http): MAX_RETRY_ATTEMPTS 전달과 signal listener 정리를 고정한다
문제
V2를 지울 때(
|
||
|
|
2f6df14f4b |
test(features): 제품 확장 typecheck 픽스처가 샘플 제거 뒤에도 통과한다 (1103/09-02)
문제
test:sample-removal은 참조 기능을 지운 복사본에서 test:unit을 돈다. 그때
product-extension-typecheck 픽스처 기능이 유일한 기능이 되는데, 메시지
catalog가 비어 있어(messages: {}) 메시지 키 타입이 무너져 tsc app이 presentation
파일 수십 곳에서 실패했다. 템플릿 결함이 아니라 픽스처 기능의 모양 문제다.
고른 방법
픽스처 기능에 두 locale의 메시지를 준다. two-feature-install-typecheck 픽스처와
같은 모양이다.
위험·한계
없다고 보는 이유: 테스트 픽스처 문자열만 바뀐다.
검증
- product-extension-typecheck.test.ts 통과(전체 repo).
- test:sample-removal 재실행 결과는 브랜치 보고에 적는다.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-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 |
||
|
|
f485e51e21 |
feat(bootstrap): 제품이 세션과 함께 닫을 것을 scopeParticipants로 넘긴다
문제: 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 |
||
|
|
f3fd10f17c |
docs(manual): 짝 백엔드에 처음 붙이기 절을 더한다
문제: 제품이 짝 백엔드에 처음 붙을 때 볼 문서가 없다. 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 |
||
|
|
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
|
||
|
|
4c4248aac5 |
feat(ci): 제품이 배포 job과 merge 검사를 제품 소유 overlay에 적는다
문제: 배포 슬롯을 채우거나 제품 전용 merge 검사를 더하려면 템플릿 소유 config/ci/gates.json(약 3,000줄)과 생성 workflow를 고쳐야 했다. 문서도 "deployment job을 gates.json에서 고치라"고 적었다. 템플릿 gates.json이 바뀔 때마다 제품은 큰 JSON과 생성 YAML의 충돌을 손으로 풀어야 했고, 다운스트림 tech-log는 이미 제품 커밋 3개에서 gates.json을 고쳤다. 고른 방법: 제품 소유 config/ci/product-gates.json을 둔다. 템플릿은 빈 파일로 싣고 고치지 않는다. 담을 수 있는 것은 둘뿐이다. - deployment: deploy package script와 vars.*·secrets.* 바인딩. 나머지 슬롯(promoted-release download, digest로 확인하는 extract, deploy)은 템플릿이 렌더링하고, 채운 계약을 다시 parse해 슬롯 규칙(앞 커밋)을 그대로 적용한다. secret은 deploy 단계에만 간다. gates.json과 overlay 양쪽에서 슬롯을 채우면 거절한다. - mergeGates: PRODUCT-GATE-NNN id의 package script. 템플릿 job 뒤의 product_merge_gate job이 merge와 같은 조건에서 matrix로 돈다. FE-GATE id·명령·산출물·readiness 공식은 건드리지 못한다. loadCiGateContract와 생성기, check:ci가 두 파일을 함께 읽고, 계약 기준선(contract-baseline.json)은 템플릿 계약만 센다. 없는 script는 거절하고, 제품 gate script는 ungated 검사에서 gated로 센다. 버린 대안: 저장소 변수로 배포 명령만 받기(제품 게이트를 못 풀고 실행할 명령이 저장소 밖에 숨는다), 제품 전용 workflow 파일(Gitea에서 run 사이 산출물 전달이 검증되지 않았다). 위험·한계: 제품 gate는 ci:gate의 로그·증거 산출물과 readiness 공식 밖이다. merge를 막으려면 제품이 그 job을 필수 검사로 지정한다. 생성 workflow는 여전히 커밋되는 파일이라, 템플릿 변경과 같은 줄을 건드리면 재생성이 필요하다. 실제 Gitea runner에서는 돌리지 않았다. 검증: tests/unit/product-ci-overlay.test.ts 11건(빈 overlay, 슬롯 채우기와 기준선 유지, 양쪽 채우기 거절, 없는 script 거절, 제품 job 렌더링과 실행 확인, 스키마 거절 6건). 작업 트리에서 overlay와 script를 채워 generate:ci-workflow → check:ci PASS, CI workflow bytes PASS, 생성 YAML 파싱 확인 후 되돌렸다. 그 상태의 workflow와 gates.json에 템플릿 변경(게이트 이름 2개)을 diff3로 3-way 병합하면 충돌 0이다. ci-workflow-generation 425건, check:ci PASS. Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-07 |
||
|
|
05958bbdb6 |
feat(recipes): 짝 백엔드 두 인증 모드의 세션 owner recipe를 더한다
문제: AUTH_MODE external은 제품이 owner 8개 메서드를 직접 써야 하는데, 짝 백엔드(JWT·Keycloak 또는 Redis session)에 맞는 owner가 src·recipes 어디에도 없다. 쿠키 owner 모양은 테스트 파일 안 스케치뿐이다. 그래서 제품마다 첫 연동 전에 토큰 획득·갱신·subject·상태 전이·401 처리를 처음부터 쓴다. 짝 백엔드(bbe944bd)에서 확인한 계약: - jwt 모드(기본): OAuth2 resource server. iss = APP_SECURITY_JWT_ISSUER (local http://localhost:8081/realms/ca-skeleton), aud 필수. CSRF·세션 없음. 그러나 realm에는 서비스용 confidential client(ca-skeleton-api, standard flow 꺼짐)만 있고 브라우저용 public client가 없다. - redis-session 모드: CA_SESSION httpOnly 쿠키, CookieCsrfTokenRepository (XSRF-TOKEN 쿠키, X-XSRF-TOKEN 헤더, plain handler). 로그인·로그아웃· 세션 조회·CSRF 발급 엔드포인트는 운영 코드에 없다(테스트 픽스처만). 고른 방법: recipes/session-owners/에 둘을 둔다. 제품은 src/bootstrap/로 복사해 composeProductSessionOwner에서 돌려준다. - oidc-pkce-session-owner.ts: authorization code + PKCE S256, WebCrypto와 context fetch만 쓴다(라이브러리 없음). 토큰은 메모리에만, sessionStorage 에는 10분짜리 거래(verifier·state·nonce·returnTo)만 두고 콜백이 먼저 지운다. 콜백 URL에서 code를 네트워크 호출 전에 지운다. state·RFC 9207 iss·nonce·aud·azp·exp·sub를 검사하고, 갱신 때 sub가 바뀌면 로그아웃. bearer는 apiOrigins에만 보낸다. 만료 30초 전 갱신은 한 번만 하고 상태 알림이 없다. 401이면 refresh token으로 한 번 복구하고, 그 토큰도 401이면 로그아웃. 설정이 틀리면 integration-failed로 닫는다. - cookie-session-owner.ts: 세션 조회·로그아웃 URL과 로그인 시작을 기본값 없이 받는다(백엔드에 없는 엔드포인트를 지어내지 않는다). 200+subject → authenticated, 401 → unauthenticated, 그 밖은 reject(상태 유지). SESSION_COOKIE_READ/WRITE 프로필과 XSRF-TOKEN → x-xsrf-token provider. 쿠키가 없으면 쓰기는 UNAVAILABLE로 아무것도 보내지 않는다. - 두 owner 모두 SessionState·recover 전이 계약을 따른다. - PRODUCTION_IMPORTS_RECIPE 검사를 recipes/session-owners에도 건다. recipe는 복사하지 import하지 않는다(초기 번들 밖). 버린 대안: src에 기본 owner 내장(IdP 결합이 템플릿 본체에 들어간다), OIDC 라이브러리 의존(fetch·WebCrypto로 충분), 매뉴얼만(같은 실수 반복). 위험·한계: 실제 Keycloak·Redis session 백엔드에 붙여 보지 않았다. ID token 서명은 검사하지 않는다(토큰 엔드포인트 직접 응답, OIDC Core 3.1.3.7 (6)); access token 서명은 백엔드가 본다. 새로고침하면 메모리 토큰이 사라져 다시 로그인한다(Keycloak SSO면 비밀번호 없이 돌아온다). 쿠키 모드는 페이지와 API가 같은 host여야 XSRF-TOKEN을 읽는다. 검증: tests/recipes 3파일 52건(구현 전 모듈 없음으로 실패 확인). 변이 15개(state·origin·401 한 번·nonce·iss·URL 정리·갱신 sub·TTL, CSRF 헤더·401·로그아웃 실패·notify·단일 조회·subject 상한·credentials) 모두 실패로 잡힘. runtime 조립 테스트 4건이 실제 createRuntimeAdapters로 EXTERNAL_BEARER bearer, 401 뒤 갱신, 쿠키 쓰기의 x-xsrf-token을 확인. check:optional-recipe-fixtures(regex 변경 없이는 실패 확인), check:optional-recipes:source, check:types, eslint 통과. 두 recipe의 minify+gzip 크기 3.8 kB, 1.1 kB. Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-03 |
||
|
|
d02efe7bc9 |
feat(bootstrap): 세션 owner context에 시간 제한 있는 fetch와 페이지를 준다
문제: composeProductSessionOwner는 config와 raw fetcher만 받는다. owner는 http보다 먼저 만들어져 세션 조회·토큰 호출을 직접 해야 하는데, 응답하지 않는 호출 하나가 세션을 recovery-pending에 영원히 둔다. 픽스처의 쿠키 owner 스케치가 바로 그렇게 쓴다. 로그인 리다이렉트에 필요한 페이지 (location·history)와 sessionStorage도 bootstrap lint가 전역 접근을 막아 제품 파일에서 얻을 길이 없다. 고른 방법: ProductSessionOwnerContext에 넷을 더한다. - fetch: 헤더와 본문 전체에 마감 하나(REQUEST_TIMEOUT_MS가 상한, 호출이 줄일 수만 있다). 본문은 64 KiB까지 메모리로 읽어 새 Response로 준다. redirect는 항상 error. fetcher가 signal을 무시해도 경합으로 끝난다. - readCookie: composeProduct와 같은 host cookie 읽기. - page: href·replaceUrl·assign. host에 없으면 throw로 닫힌다. replaceUrl은 라우터의 history state를 그대로 둔다. - redirectStorage: host sessionStorage. 토큰이 아니라 리다이렉트 한 번 동안의 상태만 둔다고 계약에 적었다. 조립은 새 파일 product-session-owner-context.ts에 두고 runtime-adapters.ts는 호출 한 곳만 바꿨다. fetch 구현 (session-owner-fetch.ts)은 처음 쓸 때 동적 import로 읽는다. 초기 번들 여유가 3 KB 남짓이라 demo 모드나 owner 없는 제품이 이 코드를 내려받지 않게 했다. 버린 대안: - platform 커널 createAbortableOperation 사용. 커널이 boot가 이미 읽는 배럴과 같은 청크로 묶여 지연 청크로 빼도 초기 번들에 남았다(빌드로 확인). 그래서 read-bounded-boot-json.ts와 같은 마감 방식을 쓴다. - 마감만 주고 본문은 owner가 읽게 두기. 본문이 멈추면 다시 무한 대기다. 위험·한계: fetch는 필수 필드라 ProductSessionOwnerContext를 직접 만드는 제품 테스트는 컴파일이 깨진다. 기존 fetcher는 그대로 둔다. 지연 청크 적재 시간은 마감에 들어가지 않는다(라우트 청크와 같다). 검증: tests/unit/product-session-owner-context.test.ts 12건(구현 전 모듈 없음으로 실패 확인), product-composition-fixture·runtime-adapters 테스트 통과, check:types, eslint 통과. build + check:bundle: initial JS 202,242 / 204,800 B gzip(09-11 포함, 기준 201,848), 지연 청크 session-owner-fetch 0.81 kB gzip. Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-03 |
||
|
|
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
|
||
|
|
36ff633794 |
fix(recipes): OPFS fake가 FILES_READY에서 멈춘 put을 runtime처럼 commit한다
문제: recipe fake MemoryDurableObjectStore의 reconcile은 멈춘 put 행을 모두 rollback으로 센다. runtime은 FILES_READY 행을 다시 검증한 뒤 commit하고 finalize한다(runbook, 설계 문서의 roll-forward). recipe 테스트 주석은 "Like the runtime, reconcile rolls a stopped put back"이라고 적는다. 이 fake로 쓴 다운스트림 테스트는 "멈춘 업로드는 reconcile 뒤 사라진다"를 통과하지만 실제로는 객체가 다시 생긴다. fake의 LOGOUT·ACCOUNT_DELETION도 멈춘 행을 보지 않아 05-01을 fake 테스트로 찾을 수 없었다. 고른 방법: fake가 멈춘 단계를 기억한다. FILES_READY까지 간 행은 commit될 객체를 함께 둔다. reconcile은 그 행을 runtime과 같은 generation 검사로 commit하고(committedTransactions), PREPARING 행은 rollback한다. LOGOUT·ACCOUNT_DELETION은 멈춘 행도 지우고, 그런 행이 있었으면 runtime처럼 chunkSweep 대신 partitionDeleted를 보고한다. 같은 네 시나리오(두 단계 × reconcile 전 계정 삭제 여부)를 메모리 OPFS·IndexedDB 위의 실제 runtime과 fake에 돌려 결과가 같은지 보는 parity 테스트를 tests/recipes에 더했다. unit 테스트가 recipe를 import하면 optional-recipe 제거 드릴이 깨지므로 parity 테스트는 recipe 쪽에 두었다(앞 커밋이 메모리 OPFS를 helper로 옮긴 이유). 위험·한계: 이 fake를 쓰는 다운스트림 테스트 중 FILES_READY 멈춤 뒤 rollback을 기대하던 것은 기대값이 바뀐다. 기존 recipe 테스트는 같은 흐름을 유지하려고 PREPARING 멈춤으로 바꿨다. fake는 runtime의 재검증 실패(digest 불일치) 경로는 흉내 내지 않는다. 검증: - RED: parity 테스트 4건 중 3건 실패(fake가 FILES_READY를 rollback, 계정 삭제가 partitionDeleted 없이 COMPLETED). runtime 쪽 기대값은 처음부터 통과. - GREEN: tests/recipes 24건 통과. check:types, 바꾼 파일 eslint, check:optional-recipes:source PASS. Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 05-04 |
||
|
|
2e12d2f0d1 |
fix(ci): 배포 슬롯이 승격 후보를 받게 하고 secret을 deploy 단계에만 준다
문제: (1) 배포 슬롯 계약은 단계 종류만 제한하고 "마지막이 deploy 하나"만 강제했다. checkout → setup-node → frozen-install → deploy(script)처럼 후보 archive를 받지 않고 다시 빌드하는 슬롯도 check:ci를 통과했고, 생성된 job 이름은 그대로 deploy-promoted-release였다(리뷰 실험 E-3). (2) 생성기는 슬롯의 환경 바인딩을 job 수준 env:로 썼다. 그래서 secrets.* 배포 자격 증명이 checkout, setup-node, frozen-install과 제3자 download action에도 보였다. 고른 방법: (1) deploy 단계에 script가 있으면 promoted-release 전송 하나만 download하고, 그 경로의 release-candidate.tar.gz를 extract하고, CANDIDATE_ARCHIVE_SHA256을 immutable_build의 digest로 바인딩해야 한다. extract는 verify-ci-candidate-archive.ts가 digest로 확인한다. 빈 슬롯은 그대로 허용한다. (2) 배포 슬롯의 secrets.* 바인딩은 deploy 단계의 env:로만 렌더링한다. vars.*와 후보 digest는 job 수준에 남는다(extract가 digest를 쓴다). 버린 대안: 슬롯 단계를 템플릿이 통째로 고정하기. 다음 커밋의 제품 overlay가 채우는 모양을 고정하고, gates.json으로 채우는 길은 이 규칙으로 막는다. 위험·한계: 슬롯이 받은 파일을 deploy 스크립트가 실제로 올리는지는 계약이 볼 수 없다. 그것은 FE-GATE-019의 config.json·entry 대조(앞 커밋)가 결과로 본다. 템플릿 슬롯은 비어 있어 생성 workflow 바이트는 바뀌지 않는다. 검증: ci-workflow-generation.test.ts에 후보 없이 deploy하는 슬롯과 digest 없이 extract하는 슬롯의 거절, secret이 deploy 단계 env에만 한 번 나오는 것을 더했다(고치기 전 3건 실패). 425건 통과. check:ci PASS, CI workflow bytes PASS. Refs: docs/reviews/2026-11-03-maturity-review/13-build-release-supply-chain.md 13-01, 13-05 |
||
|
|
2017ef76ff |
fix(query): 키 없는 결과 불명 요청에는 재전송을 주지 않는다
문제 resendUnknownEffect는 가장 오래된 admission이 UNKNOWN이고 intent가 있는지만 본다. 키 없는 명령(NEVER)도 intent는 있다. 그래서 응답을 잃은 NEVER 쓰기의 결과 불명 화면에서 "같은 요청으로 다시 보내기"를 누르면 키 없이 다시 나가고, 서버가 두 요청을 가려낼 수 없어 같은 항목이 두 번 생길 수 있다(리뷰 실험 X-D: fetch 2회, 키 [null, null]). 짝 백엔드 생성 기능의 create가 NOT_IDEMPOTENT이고 매뉴얼이 "모르면 NEVER"를 권하므로 이것이 짝 사용의 기본 경로다. 화면(AsyncSurface)은 콜백이 있으면 버튼을 그린다. 훅에도 화면에도 이 버튼을 숨기는 장치가 없다. 고른 방법 - application-query.ts canResend: head가 UNKNOWN이고 intent에 idempotencyKey가 있고 reconciliation 중이 아닐 때만 참. resendUnknownEffect는 거짓이면 null을 돌려준다. 컨트롤러가 canResendUnknownEffect로 같은 값을 낸다. - AsyncState에 선택 칸 unknownEffectResendable(결과 불명일 때만)을 두고, 훅이 deriveAsyncState 신호로 채운다. AsyncSurface는 이 값이 false면 onResendUnknownEffect가 있어도 재전송 버튼을 그리지 않는다. 그래서 기존 페이지 배선(참조 폼)은 바꾸지 않아도 키 없는 명령에서 버튼이 사라진다. - KEYED는 지금처럼 같은 키로 재전송한다. 버린 대안 - 페이지가 canResendUnknownEffect를 보고 콜백을 넘기지 않게만 하기: 기존 배선을 복사한 다운스트림 페이지에 버튼이 남는다(누르면 아무 일도 없다). - AsyncSurface에 별도 prop: 같은 사실을 페이지가 한 번 더 옮겨야 한다. 위험·한계 - 키 없는 결과 불명 화면에는 "변경됨으로 확인"과 목록 새로고침만 남는다. "적용 안 됨"으로 닫는 길은 없다(근거 없는 확정을 주지 않는 기존 결정). - 같은 입력으로 submit을 다시 부르는 경로(D-1 replay)는 바꾸지 않았다. 폼은 결과 불명 동안 제출을 막는다. - hand-built AsyncState(칸 없음)는 지금처럼 버튼을 그린다. 검증 - RED: application-mutation-admission 2건(NEVER: canResend false·resend null· execute 1회, KEYED: canResend true), async-surface 2건 실패. - GREEN: tests/unit·integration·component·features·contract 250파일 3,147건 통과. 변이(훅이 키를 보지 않음, 화면이 칸을 보지 않음) 모두 검출. - check:types, lint, check:architecture, verify:documentation 통과. Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 0929/03-03 Refs: docs/reviews/2026-11-03-maturity-review/README.md 2.1 |
||
|
|
af4ebacb68 |
docs(browser-transfer): presigned 업로드 레시피가 짝 백엔드와 맞지 않음을 적는다
문제: 프론트 업로드 레시피(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 |
||
|
|
2d5d41f85d |
fix(forms): 필드 오류가 아닌 저장 실패 뒤 키보드 포커스를 실패 상태로 옮긴다 (1103/08-02)
문제 참조 폼 페이지는 저장 중과 결과 불명 동안 저장 버튼에 disabled를 준다. 포커스가 있던 버튼이 꺼지면 브라우저가 포커스를 body로 내려놓는다. 폼은 필드 오류일 때만 포커스를 옮겼으므로, 키보드로 저장했다가 결과 불명(500)이나 429를 받으면 세 엔진 모두 포커스가 body로 떨어졌다. 복구 버튼은 폼 위 feedback 자리에 있어 셸 머리말부터 다시 지나야 닿았다. 고른 방법 - useAppForm이 feedbackId를 내고, 필드 오류·성공이 아닌 결과(결과 불명, 재인증, 권한 없음, 다시 시도, 사용 불가, 충돌)로 끝나면 렌더 뒤 그 요소에 포커스를 준다. FormPage(StandardPage)는 feedbackId를 받으면 feedback 자리를 id + tabIndex=-1인 포커스 대상으로 만든다. 페이지마다 포커스 코드를 복사하지 않게 하려고 hook과 템플릿에 두었다. - 참조 폼의 저장 버튼은 저장 중에 disabled 대신 Button의 pending(aria-busy)을 쓴다. 중복 제출은 지금처럼 폼(submitForm)과 onSubmit 가드가 막는다. 결과 불명 동안에는 여전히 꺼진다(08-01 범위). 그때는 위의 포커스 이동이 받는다. - 첫 행동 버튼 대신 feedback 자리 전체를 포커스한 이유: 실패 종류마다 버튼 구성이 다르고, Tab 한 번에 첫 복구 버튼에 닿는다. 매뉴얼 02 6절 FormPage에 feedbackId와 pending을 적었다. 위험·한계 - 스크린 리더가 포커스된 feedback 자리를 어떻게 읽는지는 확인하지 않았다. - 파생 폼 페이지는 feedbackId를 넘겨야 이 동작을 얻는다. - "deduplicates create" 테스트의 저장 중 단언을 disabled에서 aria-busy와 포커스 유지로 바꿨다. 한 번만 호출되는 단언은 그대로다. 검증 - RED: reference-page.test.tsx 새 2행(결과 불명, 429)이 수정 전 실패. e2e reference-save.spec.ts 새 2건이 수정 전 소스에서 chromium·firefox·webkit 6건 모두 실패(feedback 자리 focused 아님). - 수정 후 reference-save·reference-form e2e 3엔진 45건 통과(heavy lock, CHOKIDAR_USEPOLLING=1). tests/component·tests/features 60 files / 368 tests 통과. check:types, eslint, check:design-system, check:i18n, verify:documentation 통과. Refs: docs/reviews/2026-11-03-maturity-review/08-presentation.md 08-02 |
||
|
|
4bce8bf379 |
fix(hosting): FE-GATE-019가 후보의 설정·entry와 HTTP/2·압축 전제를 대조한다
문제: (1) live probe는 배포된 release-manifest.json의 buildId·releaseId만 후보와 비교했다. 두 값은 CI run 번호로 만든 이름이라, 같은 run에서 로컬 프로필로 다시 빌드한 release(APP_ENV=local, AUTH_MODE=demo, loopback API)를 올려도 PASS(live)였다(리뷰 실험 E-2c). 공개 대상 승인 (FE-GATE-027)을 받은 것은 후보의 config.json인데, 호스트가 내주는 config.json은 헤더만 보았다. entry script도 호스트의 두 응답끼리만 비교했다. (2) 템플릿은 HTTP/2와 압축을 전제로 초기 청크를 나누고 gzip 바이트로 예산을 재는데, 그 전제가 호스팅 계약에 없고 probe도 보지 않았다. 템플릿 nginx 예시는 http2도 gzip도 켜지 않았다. 고른 방법: - 받은 /config.json을 후보 dist/config.json과 비교한다. 비상 스위치 두 개(CAPABILITY_OVERRIDES, FEATURE_OVERRIDES) 밖의 필드가 다르거나 읽을 수 없으면 FAIL. 규칙은 check-release-admission과 같은 함수 (scripts/lib/runtime-config-switches.ts)로 옮겨 같이 쓴다. - 받은 index.html의 entry script를 후보 index.html의 것과 비교한다. - cache-policy.json에 transport.alpnProtocols(["h2"])와 hashedAsset.contentEncodings(br, gzip, zstd)를 선언한다. probe는 TLS handshake의 ALPN(node:tls, h2와 http/1.1을 제안)과 entry script 응답의 Content-Encoding을 본다. Node fetch는 h2를 지원하는 서버에도 HTTP/1.1로 붙어서 프로토콜은 따로 확인해야 한다. - nginx 예시에 http2 on과 gzip·gzip_types를 넣고, static-delivery.md와 release-cache-rollback.md에 두 전제와 실패 조건을 적었다. 두 수정은 같은 probe 함수와 테스트를 고쳐 한 커밋에 넣었다. 버린 대안: archive SHA를 호스트에 올려 대조하기(호스트에 새 파일 규약이 생기고 일부 파일만 다른 배포는 못 잡는다). HTTP/2를 기록만 하기 (아무도 읽지 않는 경고는 청크를 묶는 결정을 부르지 못한다. 선언을 바꾸면 제품이 끌 수 있다). 위험·한계: HTTP/1.1만 되는 호스트는 이제 FE-GATE-019에서 FAIL한다. 그 제품은 cache-policy.json 선언을 바꾸고 초기 청크를 묶는다. 실제 nginx와 Gitea runner에서는 돌리지 않았다. 슬롯이 후보를 받도록 강제하는 계약 규칙은 다음 커밋(제품 overlay)에 있다. 검증: hosting-probe.test.ts에 같은 이름·다른 config.json → FAIL, 비상 스위치만 다름 → PASS, 읽을 수 없는 config.json → FAIL, 다른 entry → FAIL, ALPN http/1.1·없음 → FAIL, 압축 없는 entry → FAIL, 정책 선언 확인을 더했다(고치기 전 실패). 33건 통과. 로컬 자체 서명 TLS 서버 실험: http2.createSecureServer → "h2", https.createServer → "http/1.1", 인증서 이름 불일치 → ERR_TLS_CERT_ALTNAME_INVALID. verify:hosting-headers(fixture) UNVERIFIED exit 3, deployment-admission 통과. Refs: docs/reviews/2026-11-03-maturity-review/13-build-release-supply-chain.md 13-01, 13-02 |
||
|
|
8da33a5cf0 |
test(storage): 메모리 OPFS 파일 시스템을 테스트 helper로 옮긴다
문제: OPFS worker runtime을 메모리에서 돌리는 MemoryDirectory·MemoryFile이 tests/unit/opfs-worker-runtime.test.ts 안에만 있다. 05-04를 고치려면 recipe fake와 runtime에 같은 시나리오를 돌리는 parity 테스트가 tests/recipes에 필요한데, 그 테스트는 이 파일 시스템을 쓸 수 없다. unit 테스트가 recipe를 import하면 optional-recipe 제거 드릴이 깨지므로 parity 테스트를 unit 쪽에 둘 수도 없다. 고른 방법: 그 블록(MemoryNode·MemoryFile·MemoryDirectory·fileHandle· notFound)을 그대로 tests/helpers/memory-opfs.ts로 옮기고 export한다. memory-indexeddb.ts와 같은 자리다. 코드는 바꾸지 않았다. helper는 src를 import하지 않아 browser-file-storage 제거 드릴에서도 남아도 된다. 위험·한계: 동작 변경 없음. 검증: opfs-worker-runtime.test.ts 82건 통과. check:types:test, 바꾼 파일 eslint 통과. Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 05-04 |
||
|
|
4f19cd9e8b |
test(service-worker): 살아남던 워커 보호 장치 변이 4건을 테스트로 잡는다
문제
워커 보호 장치 넷은 지워도 테스트가 모두 통과한다(1101/06-04, 이번
리뷰에서 다시 생존). install fetch의 credentials: "omit"·redirect:
"error"(M1), activate nonce 한 번만 쓰기(M3), 요청받지 않은 client의
CLIENT_DRAINED 거절(M9), 첫 설치를 "업데이트 대기"로 알리지 않기(N8).
고른 방법
- service-worker-runtime.test.ts에 테스트 3건을 더한다.
- install이 자산마다 cache no-store, credentials omit, redirect error로
요청한다(M1).
- 같은 nonce의 두 번째 ACTIVATE_REQUEST는 REJECTED, 요청받지 않은
client의 drain 응답은 세지 않는다(M3, M9).
- active 워커가 없는 첫 설치는 onUpdateWaiting을 부르지 않는다(N8).
- 동작은 바꾸지 않는다.
위험·한계
- N8 테스트는 시작 뒤 registration.active를 null로 바꿔 첫 설치를
흉내 낸다. 실제 브라우저 첫 설치 순서는 e2e가 본다.
검증
- service-worker-runtime 64건 통과.
- 변이 4건(M1·M3·M9·N8)을 하나씩 넣어 각각 1건 실패를 확인하고
되돌렸다.
- 바꾼 파일 eslint, check:types:test 통과.
Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 2절 1101/06-04
|
||
|
|
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 |
||
|
|
c99b7a7f63 |
docs(contracts): 두 오류 어휘와 commandRecovery를 누가 읽는지 타입 옆에 적는다
문제 - AppFailure(닫힌 kind, retryable, action)와 AppError(열린 owner.reason kind, retryability)의 관계가 타입 옆에 없다. AppFailure.retryable과 action "retry"는 뜻이 다른데(CONFLICT는 retryable false, action retry) 설명이 없어 모순으로 읽고 "고치는" 변경이 나올 수 있다(1101/07-05). - CommandRecoveryDescriptor는 KEYED 쓰기에 필수지만 HTTP 실행기는 읽지 않는다. 결과 불명 쓰기를 기능 gateway가 수습한다는 것은 설계서 4.4절에만 있다(1101/07-07). - 07-01(c)에서 더한 읽기 retrySemantics 거절 문구가 errors.md reason 표에 없다. 고른 방법 주석만 더한다. AppFailure 위에 어느 경계에서 어느 어휘를 쓰는지와, 둘 다 재시도 동작을 바꾸지 않는다는 것. retryable 칸에 "src에서 읽는 곳이 없고, 화면 버튼은 action"이라는 것. CommandRecoveryDescriptor 위에 실행기가 읽지 않고 기능 gateway가 재전송·조회를 정한다는 것. errors.md reason 표에 한 행. 버린 대안 - retryable을 autoRetryable 같은 이름으로 바꾸기: 다운스트림 import를 깨는 비용에 비해 얻는 것이 작다. 위험·한계 - 동작은 바뀌지 않는다. "src에서 읽는 곳이 없다"는 grep으로 확인한 지금 상태다. 검증 - grep: src/presentation·bootstrap·features·application에서 AppFailure.retryable을 읽는 곳 0. commandRecovery를 읽는 곳은 플랫폼 개요 화면뿐. - eslint, verify:documentation 통과. Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 1101/07-05, 1101/07-07 |
||
|
|
64f19ac665 |
fix(architecture): zod 하위 경로 import도 src/contracts/zod.ts를 거치게 한다
문제 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 |
||
|
|
84d6e526a3 |
fix(registries): 계약 조립 실패의 reason을 적고 읽지 못한 레지스트리를 지운 것으로 세지 않는다
문제
기능 계약 조립이 실패하면(예: 없는 authProfileId) check:registries 출력은
"missing registry source src/features/loaded-feature-runtimes.ts: Installed
contract contribution is not composable" 두 줄, "FE-REG-API is not an
object registry", "FE-REG-ROUTE references unknown registry FE-REG-SCHEMA",
"breaking change missing evidence: FE-REG-API:*:*:removed" 등이다. 원인은
ContractContributionError.reason에 있는데 검사기는 message 첫 줄만 적는다.
끝의 removed 줄은 "breaking 증거를 더하라"로 읽혀 틀린 다음 행동을
제안한다(실험 E-9).
고른 방법
- source를 읽다 난 오류에 문자열 reason이 있으면 "(reason: ...)"로 함께
적는다.
- 읽지 못한 레지스트리는 따로 모은다. 그 레지스트리에 대해서는 행 검사
("is not an object registry"), 그것을 가리키는 참조 검사, 기준선 비교
(removed 증거 요구)를 하지 않는다. 같은 실패를 다른 이름으로 다시 적지
않기 위해서다. 게이트는 load 실패 한 줄로 그대로 실패한다.
- errors.md 레지스트리 표에 이 메시지 행을 더했다.
버린 대안
- 메시지 접두어를 "failed to load"로 바꾸기: 의미는 더 맞지만 기존 테스트와
CI 진단 기대값이 "missing registry source"를 쓴다. 이번에는 바꾸지 않았다.
위험·한계
- source 파일을 실수로 지운 경우에도 removed 증거 요구를 건너뛴다. 그래도
"missing registry source" 실패로 게이트는 막힌다. 레지스트리를 의도해서
지우면 governance에서도 빠지므로 removed 증거 요구는 그대로다.
- FE-REG-API와 FE-REG-SCHEMA가 같은 source라 load 실패 줄은 두 번 나온다.
검증
- RED: registry-governance에 임시 디렉터리 fixture(두 레지스트리, 하나가
다른 하나를 참조, 기준선 있음)를 더했다. source가 reason 있는 오류를
던지면 출력이 load 실패 한 줄이어야 한다. 고치기 전에는 reason이 없고
cascade 3줄이 더 나와 실패했다.
- GREEN: registry-governance 11건 통과. E-9 재실행(참조 기능 목록
operation의 authProfileId를 NOTICE_NOPE로): 출력이 "... (reason:
reference-feature/LIST_REFERENCE_RESOURCES: unknown authProfileId
NOTICE_NOPE)" 두 줄뿐이고 removed 줄이 없다.
- check:registries:fixture·check:routes:fixture·baseline-fixture가 기대
진단으로 실패한다. eslint, check:types:node, check:types:test 통과.
Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-06
|
||
|
|
5bee9abed9 |
test(contracts): FE-REG-SCHEMA 행의 방향·모르는 필드 정책을 검증기와 대조한다
문제 참조 기능의 FE-REG-SCHEMA 행은 응답 스키마를 STRIP_UNKNOWN, 요청 스키마를 REJECT_UNKNOWN이라 적는다. 실제 정책은 zod .strip()·.strict()가 정하고, unknownFieldPolicy·direction을 읽는 실행 코드는 없다. 응답 DTO를 .strict()로 바꿔도 check:registries와 관련 테스트가 모두 통과한다(실험 X8). 그러면 백엔드가 응답에 필드 하나를 더할 때마다 그 API가 SCHEMA_MISMATCH로 실패하는데, 스냅샷과 docs/contracts/compatibility.md는 여전히 additive라 말한다. 고른 방법 설치된 기능의 HTTP descriptor마다 입력·출력 검증기를 FE-REG-SCHEMA 행과 대조하는 테스트를 더한다. - direction: 입력 검증기 행은 REQUEST, 출력 검증기 행은 RESPONSE. - unknownFieldPolicy: 아무 스키마도 선언하지 않는 키 하나를 가진 객체와, 그 객체 하나를 담은 배열을 검증기에 넣는다. 그 객체 위치의 unrecognized_keys면 REJECT_UNKNOWN, 객체 안을 봤는데 그 issue가 없으면 STRIP_UNKNOWN이다. 정책을 적은 행만 본다. loaded-feature-runtimes를 읽으므로 다운스트림이 더한 기능도 같은 검사를 받는다. create:feature 뼈대(NoRequest strict, 목록 응답 strip)도 맞는다. 버린 대안 - 메타데이터에서 두 칸을 지우기: 읽는 곳이 없어 가장 단순하지만 호환 문서의 근거가 사라지고 기준선 재승인이 필요하다. 메타데이터 생성은 다른 작업(16-04~06) 범위다. - 스키마마다 유효한 예시 값을 두고 모르는 키를 더하기: 기능마다 예시를 손으로 써야 해 다운스트림 기능을 자동으로 덮지 못한다. 위험·한계 - 탐침은 payload의 첫 객체 단계(객체, 또는 배열의 항목)만 본다. 그 아래 중첩 객체의 정책은 보지 않는다. - problem 검증기는 FE-REG-SCHEMA 행이 없어 대상이 아니다. 검증 - 변이: 응답 DTO .strip()→.strict()(X8), 생성 명령 .strict()→.strip(), 응답 행 direction을 REQUEST로 바꾸면 각각 실패한다. 되돌리면 2건 통과. 설치된 기능이 없으면(샘플 제거 뒤) 두 건 모두 빈 채로 통과한다. - eslint, check:types:test 통과. Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-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 |
||
|
|
c3aa5eba35 |
docs(recipes): Service Worker 레시피가 오프라인 셸을 약속하지 않게 한다
문제 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 |
||
|
|
2963c6f42c |
fix(features): 선택 런타임(SW 등) 선택을 제품 소유 파일로 옮긴다 (1103/09-05)
문제 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 |
||
|
|
c9e7bab2d7 |
test(scale): 기능·context 비용을 따로 재고 초기 JS 기준선을 빌드와 대조한다
문제: (1) 기능당 1 KiB 상한 테스트는 복사본 0개와 1개만 쟀다. 첫 복사본은 새 context(shape-context-0)도 만들어서, 잰 값에 context 비용이 섞였고 상한까지 40 B만 남았다. 넘으면 기능이 커졌는지 context가 비싸졌는지 알 수 없었다. (2) 성능 기준선 숫자는 performance-evidence.md, static-delivery.md, feature-shape-ceilings.json에 손으로 적혀 있었고 현재 빌드와도, 같은 파일 안에서도 서로 달랐다(1101/15-02 재발). (3) 이 테스트는 vitest 안에서 돌아 NODE_ENV=test를 물려받았다. 그래서 픽스처 vite build가 React 개발 빌드를 묶었고, 잰 합계가 운영 빌드 (약 201 KB)가 아니라 약 264 KB였다. 고른 방법: 복사본 0·1·2개를 잰다. 둘째 복사본은 같은 context에 들어가 기능 하나의 비용이고, 첫 복사본에서 그것을 뺀 나머지가 context 하나의 비용이다. 기능은 1 KiB, context는 512 B로 따로 막고 실패 메시지에 잰 값을 넣는다. 기준선은 feature-shape-ceilings.json의 initialJavascript 한 곳에 기계가 읽는 칸으로 두고, 같은 테스트가 빌드와 대조한다(합계 1%, 파일 수 정확히, 기능·context 비용 10%). 기록은 `measure-feature-shape-growth.ts --initial-baseline --write`로 다시 쓴다. 문서는 숫자 대신 그 칸을 가리킨다. 픽스처 명령은 NODE_ENV를 지우고 돈다. 버린 대안: 문서 숫자를 다시 손으로 고치기(두 번 낡았다), 문서에서 숫자를 지우고 bundle.json만 가리키기(예산을 정할 숫자를 보려면 빌드가 필요하다). 위험·한계: unit에 빌드가 하나 늘었다(약 3초). 초기 JS를 움직이는 변경은 기록도 다시 써야 test:unit이 통과한다. 그것이 목적이다. `298201f` 출처별 크기 표와 `ec7435c` HTTP/1.1 측정 표는 날짜가 붙은 측정 기록으로 남겼다. 검증: 기록을 쓰기 전 새 테스트가 실패했다. 기록 gzipBytes를 2% 바꾸면 실패하고 되돌리면 통과한다. 지금 기록: 200,939 B, 파일 25개, 기능 +765 B, context +214 B. feature-shape-growth 7건 통과, verify:documentation PASS_SCOPED. Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-02, 15-04 |
||
|
|
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
|
||
|
|
8d328c9cea |
test(indexeddb): 차단 업그레이드 테스트가 500 ms 전이 상태를 폴링하지 않는다
문제 tests/browser-capabilities/indexeddb-runtime.spec.ts의 차단 업그레이드 테스트는 v2 runtime을 blockedTimeoutMs 500으로 시작한 뒤 expect.poll(lifecycleStatus)로 BLOCKED 상태를 기다린다. 이 상태는 500 ms 뒤 CLOSED/NOT_OPENED로 바뀌고, 폴링 한 번은 page.evaluate 왕복이다. 그래서 바쁜 호스트에서는 첫 관찰 전에 창이 닫혀 FE-GATE-008이 코드와 무관하게 떨어진다(리뷰 전체 실행에서 chromium·webkit 실패). 고른 방법 - 전이 상태 폴링을 지우고, 바로 뒤 settleLifecycleRuntime 결과 (opened.error.code BLOCKED, recovery RELOAD_OTHER_CONTEXTS, status CLOSED/NOT_OPENED)로 차단을 판정한다. 전이 상태 BLOCKED는 제어한 scheduler로 tests/unit/indexeddb-runtime.test.ts가 이미 고정한다. - 버린 대안: blockedTimeoutMs를 늘리기. 창이 넓어질 뿐 경쟁이 남는다. runtime이 상태 변화를 기록하게 하기. 운영 코드에 테스트용 기록이 생긴다. 위험·한계 - 실제 브라우저에서 getStatus()가 BLOCKED를 돌려주는 순간은 이 spec이 더는 보지 않는다(단위 테스트가 본다). 검증 - RED: 창을 20 ms로 줄이면 수정 전 테스트가 chromium·webkit에서 CLOSED/NOT_OPENED를 받아 실패했다(리뷰 실패와 같은 모양). 수정 뒤 같은 20 ms에서 세 엔진 통과. 값은 500으로 되돌렸다. - test:browser-capabilities 전체 63 passed(load 15~20). 5회 반복은 하지 않았다. Refs: docs/reviews/2026-11-03-maturity-review/11-tests-browser-release-scale.md 11-05 |
||
|
|
3bc690d3fb |
test(realtime): WebSocket 구독별 초당 event 상한을 테스트로 고정한다
문제 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 |
||
|
|
0cc2553381 |
docs(operations): 워커 제거 1단계를 최대 미방문 기간 이상 유지하라고 적는다
문제 자기 해제 service-worker.js는 REMOVE_REGISTRATION release만 낸다 (build-frontend.ts). 다음 단계 release에는 워커 파일이 없어 update 검사가 404로 실패한다. PURGE_OWNED_RESOURCES는 부팅한 페이지만 다시 unregister하고, null은 아무것도 하지 않는다. 1단계 기간에 오지 않은 사용자에게 부팅을 막는 워커나 옛 워커가 남는다(리뷰 1103 실험 L3). 운영 문서는 세 단계 순서만 적고 각 단계 유지 기간이 없다. 고른 방법 - 0929/06-06의 최소 방향 중 문서 한 줄을 고른다. SW runbook 8절과 release-cache-rollback.md 4단계에 "1단계를 최대 미방문 기간 이상 유지, 그 뒤 남은 사용자가 보이면 1단계를 다시 배포"를 적는다. - 버린 대안: 2단계도 자기 해제 워커를 내보내고 hosting 허용 목록을 맞추기. 빌드·hosting 검사·e2e를 함께 바꿔야 해서 이월 항목의 작은 수정 범위를 넘는다. 위험·한계 - 동작은 그대로다. 유지 기간을 지키는지는 운영자 몫이다. 검증 - 문서와 코드(build-frontend.ts, service-worker-page-controller.ts PURGE_OWNED_RESOURCES 분기, service-worker-removal.ts)를 대조했다. - verify:documentation PASS_SCOPED. Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 2절 0929/06-06 |
||
|
|
1239566290 |
test(provider): scope wrapper EOF 테스트가 준비 신호 뒤에 stdin을 닫는다
문제
tests/unit/task3-selective-integration.test.ts의 EOF 테스트는
provider-scope-wrapper.ts를 새 Node로 띄우고, 준비 신호 없이 75 ms를 잔
뒤 stdin을 닫고 1초 안에 끝나기를 기다린다. 75 ms 안에 자식이 기동을
끝내지 못하면 Node 기동과 TS 모듈 import가 그 1초에 들어간다. 그래서
부하가 걸린 호스트에서 "provider scope EOF close timed out"으로 merge
게이트가 코드와 무관하게 떨어진다.
고른 방법
- guardian 테스트(
|
||
|
|
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 |
||
|
|
245f428123 |
fix(features): 제품 capability 타입과 기본값 설정 키가 타입 검사 3종을 통과한다 (1103/09-02)
문제 제품 확장 지점이 실행 경로에서는 동작했지만 타입 검사 경로에서 막혔다. (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 |