Commit Graph
1165 Commits
Author SHA1 Message Date
DongHyeonka 5b2106df25 docs(realtime): realtime 레지스트리 세 바인딩의 출처를 레시피에 적는다
문제
realtime 레지스트리는 schemaCodecs·mappers·apiOperations 세 바인딩을
받아 event type과 checkpoint를 대조한다. V2 삭제(12f3bb7)로 기능의
runtimeSchemas·mappers 칸이 사라져 지금 출처가 있는 것은
apiOperations뿐이다. 레시피는 "제품 feature는 이 runtime에
schema/codec/query … 주입"이라고만 적어 조합자가 codec·mapper를 어디서
만드는지 알 수 없다.

고른 방법
- 리뷰의 최소 방향대로 레시피 Realtime 절에 세 바인딩의 출처를 적는다.
  apiOperations는 loadInstalledFeatureRuntimeRegistries().apiOperations,
  schemaCodecs는 V3 events[].payloadValidator·checkpoint outputValidator를
  runtimeSchemaCodecFromValidator + composeRuntimeSchemaCodecs로,
  mappers는 조합 코드의 BoundaryMapper + composeBoundaryMapperRegistry다.
  등록 때 맞아야 하는 id(payloadSchemaId = validator schemaId =
  mapper inputSchemaId)도 적었다(realtime-streams.ts 등록 검사).
- 버린 대안: 지금 기능 모듈에 realtimeMappers 칸을 더하거나 V3 events에서
  event type을 뽑기. 공개 계약이 바뀌고, 04-02의 push 경로(STOMP hint면
  delta mapper가 필요 없을 수 있음)를 고른 뒤 정하는 것이 맞다.

위험·한계
- 코드 변경이 없다. 같은 이벤트를 V3 events와 realtime 등록 두 곳에
  적는 중복은 문서 규칙으로만 막는다.

검증
- verify:documentation PASS_SCOPED.

Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 04-06
2026-11-04 20:30:22 +09:00
DongHyeonka 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의 행을 모두 지운다(e5b7b3e).
OpfsJournalPort에 countPartitionTransactions(scope)를 더했다.
removePartition이 지우는 같은 LOGICAL_KEY_INDEX 범위를 세므로, 센 행은
삭제가 지운다.
버린 대안: (a) 문서에 "reconcile 먼저" 안내 — X1·X3을 막지 못한다.
(b) report에 수만 추가 — 지울 방법이 없다(X3). (d) 항상 partition
삭제 — 더 단순하지만 끝나지 않은 행이 없을 때의 예산 단위 진행과
removedObjects·releasedBytes 보고를 잃는다.

위험·한계:
- 공개 포트에 필수 메서드가 하나 는다. OpfsJournalPort를 직접 구현한
  쪽은 추가해야 한다([계약]).
- 끝나지 않은 행이 하나라도 있으면 purge가 예산 없는 partition 삭제가
  되고, 다른 탭의 진행 중 put이 끝날 때까지 기다린다. 그 put의 결과도
  지운다(손상 경로와 같은 의미). purge가 행을 센 뒤 시작한 put은
  남는다(point-in-time).
- 기존 테스트 "never sweeps the chunk of a put that runs while the purge
  does"는 X1 동작을 기대값으로 고정하고 있었다. 새 의미로 바꿨다.
  0929/05-02 테스트는 덮어쓰기가 purge의 목록과 remove 사이에 끝나도록
  바꿔 CONFLICT 경로를 계속 본다.
- 소속을 알 수 없는(logicalKey가 깨진) 행은 여기서도 세지 못한다(05-03).
- WebKit은 기본 정책에서 OPFS 지원 판정을 통과하지 못해 browser spec이
  일찍 끝난다. offline-indexeddb 번들 37,423 → 37,521 / 38,500 gzip B.

검증:
- RED: opfs-worker-runtime.test.ts 새 4건(X1, FILES_READY, PREPARING,
  손상 행)이 partitionDeleted 없음으로 실패.
- GREEN: OPFS 단위 3파일 + optional-runtime-host + tests/recipes +
  tests/contract 172건 통과. journal에 countPartitionTransactions 테스트
  1건(손상 행 포함, 다른 partition 제외, 삭제 뒤 0).
- browser: opfs-runtime.spec.ts에 X1 2탭 판을 더했다. heavy lock 안에서
  3엔진 9/9 통과(WebKit은 지원 판정에서 끝남).
- check:types, 바꾼 파일 eslint, check:optional-recipes:source PASS,
  verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 05-01
2026-11-04 20:29:34 +09:00
DongHyeonka 615da352b9 docs(realtime): 짝 백엔드 실시간 출구와 프론트 transport 대응표를 적는다
문제
짝 백엔드의 실시간 출구는 STOMP-over-SockJS 채널(/ws, /topic 구독 1개,
Map<String,String> 투영, 재전송 없음)과 raw WebSocket 라이브러리 API,
NDJSON·JSON text sequence writer다. 프론트 SSE 어댑터는
text/event-stream과 REALTIME_EVENT_V1 envelope을, WebSocket 어댑터는
subprotocol "realtime.v1"을 요구한다. 어느 repo에도 이 불일치와 지금
되는 경로가 적혀 있지 않아, 채택자가 두 repo를 다 읽어야 안다.

고른 방법
- 리뷰의 최소 방향을 프론트 repo 안에서 따른다. 설계 문서에 0.1절을
  두고 transport별 대응표(지금 연결되나·이유), push가 필요할 때의 세
  길, 재검토 조건을 적는다. 레시피 Realtime 절과 매뉴얼 03 C절에서 한
  줄로 링크한다.
- 다시 확인한 백엔드 사실(읽기만): 아키텍처 테스트가 MVC SseEmitter를
  금지한다(ForbiddenApiArchitectureTest NO_SSE_EMITTER, 결정 D3).
  StreamMediaType.SSE는 OpenAPI 생성기만 쓴다. subprotocol 협상 코드는
  없다. 그래서 첫째 길을 SSE가 아니라 realtime.v1 WebSocket handler로
  적었다.
- 지금 되는 경로(bounded polling)는 사실로 적고, push 경로는 고르지
  않았다. 제품 결정이다.
- 버린 대안: desktop-server-git/design-docs/에 쓰기. 이 브랜치 밖이라
  함께 합쳐지지 않는다. 필요하면 그쪽에서 이 절을 링크한다.

위험·한계
- 백엔드 사실은 지금 백엔드 HEAD(70fb80bf)를 읽은 것이다. 백엔드가
  바뀌면 표가 낡는다. 재검토 조건에 적었다.
- 실제 연결은 실행하지 않았다(리뷰와 같음).

검증
- verify:documentation PASS_SCOPED. documentation-readiness·
  changelog-review-ids 테스트 15건 통과.

Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 04-02
2026-11-04 20:29:32 +09:00
DongHyeonka e440ece9fe build(vite): 폐기 예정 build.rollupOptions를 rolldownOptions로 바꾼다
문제: 앱·Service Worker·선택 레시피 번들의 청크 설정이 Vite 8에서
@deprecated인 build.rollupOptions 별칭에 있었다(0929/13-07, 세 라운드
남음). 별칭이 지워지는 Vite 버전으로 올리면 청크 그룹과 treeshake 설정이
조용히 빠질 수 있다.

고른 방법: 세 곳의 키 이름만 rolldownOptions로 바꾼다. 내용은 그대로다.

위험·한계: 없음에 가깝다. 같은 설정의 정식 이름이다.

검증: 바꾸기 전후 빌드의 dist/assets 파일 이름이 모두 같다(해시가 같아
출력이 같다). service-worker-build-output 7건 통과,
check:optional-recipes PASS(레시피 예산 4개 그대로).

Refs: docs/reviews/2026-11-03-maturity-review/13-build-release-supply-chain.md 0929/13-07
2026-11-04 20:28:52 +09:00
DongHyeonka 9800bc89f3 test(contracts): 금지 조각이 든 런타임 설정 키를 test:unit에서 막는다
문제
설정 키 금지 조각 검사(assertSafeConfigNames: TOKEN, COOKIE, SECRET 등)는
부팅 때 한 곳에서만 돈다. ece944d가 연 제품 키 경로로 PRODUCT_COOKIE_NOTICE
같은 키를 zod 필드·FE-REG-ENV 행·config/runtime 값으로 더하면
generateRuntimeConfig, 범위 테스트, check:registries가 모두 통과한다. 그
config.json으로 배포하면 모든 사용자가 부팅 실패 화면을 보고, 오류 코드
CONFIG_SECRET_NAME_REJECTED에는 키 이름이 없다(실험 E-4).

고른 방법
env-registry-coverage에 사례 하나를 더한다. V2 스키마가 읽는 키와
FE-REG-ENV 런타임 행 키 전부로, 값은 스키마 기본값(CAPABILITY_OVERRIDES의
중첩 키 포함)으로 문서를 만들어 assertSafeConfigNames에 넣는다. 실패
메시지가 키 이름을 말한다. 규칙은 매뉴얼 03 C절의 product-contracts.ts
항목에 적었다.

버린 대안
- product-contracts.ts 주석에 규칙 적기: 이 파일은 제품 소유이고 템플릿이
  복사 뒤에 고치지 않는다고 약속한 파일이다. 동기화 때 충돌을 만든다.
- generate-runtime-config에서도 검사: 스키마가 strict라 제품 키는 스키마
  필드여야 들어가고, 그 키는 이 테스트가 먼저 잡는다. 같은 검사를 한 곳
  더 두지 않았다.

위험·한계
- 부팅 오류 CONFIG_SECRET_NAME_REJECTED에 거절한 키 이름을 싣는 것은 하지
  않았다(src/bootstrap/load-runtime-config.ts, 다른 작업 범위).
- 제품 record 필드의 임의 중첩 키(값으로만 생기는 키)는 기본값에 없으면
  이 테스트가 보지 못한다. 부팅 검사가 여전히 막는다.

검증
- E-4 재실행: PRODUCT_COOKIE_NOTICE를 제품 zod 필드와 행으로 더하면 이
  사례가 "Forbidden client configuration key: PRODUCT_COOKIE_NOTICE"로
  실패한다. 되돌리면 4건 통과.
- eslint, verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-04
2026-11-04 20:28:49 +09:00
DongHyeonka 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
2026-11-04 20:27:53 +09:00
DongHyeonka a144b575e5 fix(contracts): FE-REG-ENV 런타임 행의 필수 여부·기본값을 스키마와 맞춘다
문제
FE-REG-ENV 런타임 행 13개 중 5개의 required·defaultValue가 실제 V2
runtime config 스키마(runtimeConfigV2ArtifactSchema)와 다르다.
- TELEMETRY_ENABLED: 행 기본값 false / 스키마 필수, 기본값 없음
- AUTH_MODE: 행 기본값 "external" / 스키마 기본값 없음
- RELEASE_MANIFEST_URL: 행 required true / 스키마 선택(기본값 있음)
- CAPABILITY_OVERRIDES: 행 기본값 null / 스키마 기본값 네 항목 DEFAULT
- FEATURE_OVERRIDES: 행 기본값 null / 스키마 기본값 {}
d0414c8의 테스트는 스키마 키마다 행이 있는지만 본다. 스키마에 없는 런타임
행도, 값이 다른 행도 통과한다. 이 레지스트리는 기준선 호환 검사 대상이라
틀린 값이 계약으로 굳는다. AUTH_MODE를 빼도 external이 된다고 읽으면
부팅이 스키마 오류로 멈춘다.

고른 방법
- env-registry-coverage에 두 방향을 더한다. 스키마가 읽지 않는 런타임 행은
  실패한다. 각 행의 required·defaultValue는 스키마 필드에 undefined를 넣은
  결과(실패 = 필수·기본값 없음, 성공 = 선택·그 값)와 같아야 한다. 차이는
  키·행 값·스키마 값을 한 줄로 보인다. 제품 키(PRODUCT_*)도 같은 검사를
  받는다.
- 5개 행을 스키마에 맞춘다. 두 override 기본값은 객체라 governance의
  defaultValue 타입에 object를 더했다.
- ENV_REGISTRY 주석에 두 칸의 뜻(null = 스키마가 기본값을 주지 않음)을
  적었다.

버린 대안
- 행의 required·defaultValue를 스키마에서 계산해 채우기: 손으로 맞출 일이
  사라지지만 env.ts가 zod 스키마를 import해야 한다. env.ts는 부팅 경로
  (getBuildConfig)에 있어 초기 청크에 zod 스키마가 끌려 들어간다.

위험·한계
- RELEASE_MANIFEST_URL required true→false는 breaking 칸 변경이고
  governance fieldTypes도 바뀌어 기준선을 다시 승인했다.
- 스키마 superRefine의 조건부 필수(TELEMETRY_ENABLED면 TELEMETRY_ENDPOINT)는
  행에 표현하지 않는다.

검증
- RED: 새 대조 테스트가 위 5개 행을 정확히 보고하며 실패했다.
- GREEN: env-registry-coverage 3건 통과. 변이: 스키마 REQUEST_TIMEOUT_MS
  기본값만 20,000으로 바꾸면 실패, 스키마 필드 없는 제품 행을 더하면 실패.
- check:registries(재승인 뒤 compatibility=none), run-vitest related
  (env.ts, governance) 18파일 154건, registry-governance·product-composition
  23건, check:types, eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/13-build-release-supply-chain.md 13-04
Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md P-07-05
2026-11-04 20:27:35 +09:00
DongHyeonka b4ae4c1ed3 docs(operations): waiting 기간에 소유 캐시가 쌓이는 것과 정리 시점을 적는다
문제
캐시를 지우는 곳은 activate 하나다(현재 + 마커가 가장 높은 직전 1개).
템플릿은 requestActivation()을 부르지 않으므로 활성화는 그 scope의
탭이 모두 닫혀야 일어난다. 그 사이 release마다 새 후보가 waiting
워커를 밀어내지만 밀려난 캐시는 남는다(리뷰 실험 L2: A 활성 + 탭
유지에서 B, C를 받으면 소유 캐시 3개, 활성화 뒤 2개). 운영 문서는
"현재 + 직전 1개"만 말해 waiting 기간의 캐시 수가 보이지 않는다.

고른 방법
- 리뷰 5.1 판단대로 (a) 문서만 고친다. SW runbook 8절에 쌓이는 규칙,
  예, 크기 상한, 쿼터에 닿았을 때의 결과, 줄이는 방법
  (requestActivation 화면)과 install이 지우지 않는 이유를 적는다.
  release-cache-rollback.md SW 1단계에 한 문장과 링크를 둔다.
- 버린 대안: (b) install 성공 뒤 "무마커 + 이번 후보 아님 + 활성 캐시
  아님"을 지우기. install하는 워커는 활성 캐시 이름을 모르고, 마커
  쓰기에 실패한 활성 캐시는 후보와 구별되지 않는다. (c) 이번 후보를 뺀
  무마커 캐시를 모두 지우기. 그 활성 캐시를 지워 직전 캐시 보존 성질을
  깬다.

위험·한계
- 쌓이는 동작 자체는 그대로다. 사전 캐시가 1 MiB를 넘고 release가 잦아
  지면 (b)를 다시 본다(리뷰 재검토 조건).
- 브라우저 종료로 활성화되는지는 확인하지 않았다.

검증
- 문서와 코드(service-worker-lifecycle.ts onActivate,
  service-worker-static-assets.ts QUOTA_EXCEEDED, service-worker.ts
  assetSetBytes)를 대조했다.

Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 06-04
2026-11-04 20:27:30 +09:00
DongHyeonka 7144653109 docs(operations): 워커 스크립트 헤더 검사 범위를 지금 코드에 맞춘다
문제
SW runbook(browser-file-storage-recovery.md 8절)은
"verify:hosting-headers는 파일이 있는지만 보고 이 헤더는 보지 않는다"고
적는다. 지금은 워커를 싣는 빌드에서 serviceWorker surface가 필수이고
Cache-Control이 no-cache가 아니면 FAIL이다(cache-policy.json
serviceWorker, verify-hosting-headers.ts). release-cache-rollback.md는
맞게 적어 두 운영 문서가 반대로 말한다.

고른 방법
- 그 문장을 live 모드가 /service-worker.js의 no-cache를 확인한다로
  고친다. fixture 모드가 UNVERIFIED라는 것과, 하위 경로 base는 probe가
  아직 받지 않아 손으로 확인해야 한다는 것을 함께 적는다.

위험·한계
- 하위 경로 문장은 0929/13-06이 고쳐지면 지워야 한다.

검증
- 문서와 코드(cache-policy.json, verify-hosting-headers.ts,
  hosting-probe.ts classifyLiveHostingBaseUrl)를 대조했다.

Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 06-01
2026-11-04 20:27:00 +09:00
DongHyeonka 0f58abbd32 fix(hosting): live probe가 사전 캐시 확장자마다 Content-Type을 확인한다
문제
워커 install은 사전 캐시 자산마다 응답 MIME이 manifest 값
(CACHEABLE_ASSET_CONTENT_TYPES: .css .js .mjs .png .svg .webp .woff2)과
정확히 같아야 하고, 하나라도 틀리면 release 전체를 거절한다. 호스팅
live probe는 index가 가리키는 entry script 하나만 요청하고
hashedAsset.contentTypes도 JavaScript뿐이다. 그래서 CSS를 text/plain,
글꼴을 octet-stream으로 보내는 호스트도 게이트는 PASS다. 페이지는
글꼴을 그대로 쓰므로 워커만 조용히 설치되지 않는다.

고른 방법
- probeAssetContentTypes를 더한다. 후보 dist의 assets/에서 확장자마다
  첫 파일(이름순)을 요청하고, 그 확장자의 워커 표 MIME과 비교한다.
  결과는 surface hashedAsset.<ext>, header content-type이다.
  verify-hosting-headers live 모드에서만 부른다.
- 기대 MIME은 워커 표에서 바로 읽는다. .js 계열은 hashedAsset surface와
  같이 application/javascript도 받는다. 두 목록이 같다는 것을 테스트가
  지킨다(acceptedAssetContentTypes(".js") = cache-policy hashedAsset).
- 운영 문서(release-cache-rollback.md)에 새 검사를 적는다.
- 버린 대안: (b) 워커가 비JS 자산 MIME을 느슨하게 받기 — 캐시에서 꺼낸
  응답이 틀린 MIME을 그대로 갖고 설계 §18 확인 순서 4와 어긋난다.
  (c) 사전 캐시를 JS·CSS로 줄이기 — 글꼴 캐시 이득을 잃는다. (d) 문서만
  — 검출이 없다(리뷰 5.2).

위험·한계
- live probe 요청이 확장자 수만큼 는다(지금 빌드는 .js·.css 2개).
- 확장자마다 파일 하나만 본다. 같은 확장자 안에서 경로마다 MIME이
  다른 호스트는 잡지 못한다.
- cache-control은 이 자산들에서 다시 보지 않는다. entry script의
  hashedAsset 검사가 그대로 본다.
- 실제 호스트로 live 모드를 돌리지 않았다. fetcher 대역으로만 확인했다.
- 하위 경로 base는 probe가 아직 거절한다(0929/13-06, 다른 영역). 새
  함수는 base 기준 상대 경로로 요청하므로 그 수정 뒤에도 그대로 쓴다.

검증
- 새 테스트 4건을 옛 코드에 돌림: 4건 실패(RED). 새 코드:
  hosting-probe·service-worker-build-output 테스트 통과.
- CSS를 text/plain으로 보내는 호스트 → hashedAsset.css FAIL.
- check:types:node·check:types:test 통과, 바꾼 파일 eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 06-03
2026-11-04 20:26:24 +09:00
DongHyeonka 61f70cb9b8 fix(contracts)!: 쓰기 operation의 SAFE 재시도 의미를 조립에서 거절한다
문제
설계 정본 8.3은 SAFE를 "GET/HEAD; 보낸 뒤 network 실패에도 재시도 허용"
으로 정한다. 실행기는 그 규칙대로 SAFE면 보낸 뒤 응답을 잃어도 다시
보낸다(http-retry-lifecycle.ts canRetryTransport). 그런데 조립 검사는
쓰기가 SAFE인지 보지 않는다. 생성된 뼈대 descriptor가 GET·SAFE·
retryBudget 2이고, 매뉴얼은 쓰기를 더할 때 이 파일을 고쳐 쓰라고 한다.
retrySemantics를 바꾸지 않으면 POST가 조립을 통과하고, 응답을 잃은 생성
요청이 최대 두 번 더 나간다(리뷰 실험 X-E: fetch 2회, 결과 SUCCESS).
V2에도 이 규칙은 없었다.

고른 방법
assertHttpContract의 쓰기 가지(GET·HEAD 밖)에서 retrySemantics가 SAFE면
operation·method와 고를 값(IDEMPOTENT·KEYED·NEVER), 매뉴얼 절을 담아
거절한다. 매뉴얼 02 3절 "틀리면"에 같은 문장을 더했다.

버린 대안
실행기에서 쓰기의 SAFE를 NEVER처럼 다루기: 잘못 적은 계약이 조용히
다른 뜻으로 돈다. 조립 때 알리는 쪽이 고칠 곳을 바로 보여 준다.

위험·한계
쓰기를 SAFE로 적은 다운스트림은 부팅에서 실패한다. 의도한 실패다.
실행기를 조립 없이 직접 부르는 테스트 경로는 이 검사를 거치지 않는다.

검증
- RED: tests/unit/external-contract-runtime.test.ts의 POST·PUT·PATCH·DELETE
  × SAFE 4건 실패(조립 통과).
- GREEN: 같은 파일 23건 통과. GET·SAFE와 PUT·IDEMPOTENT는 그대로 조립된다.
- tests/unit·integration·contract·features·runtime-schema 214파일 2,904건
  통과. check:types:app·test, eslint, verify:documentation 통과.

BREAKING CHANGE: POST·PUT·PATCH·DELETE operation에 retrySemantics "SAFE"를
쓰면 composeContractContributions가 거절한다. 서버 보장에 맞춰 IDEMPOTENT,
KEYED(commandRecovery 필요) 또는 NEVER(retryBudget 0)로 바꾼다.

Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-03
2026-11-04 20:25:54 +09:00
DongHyeonka 9f9e459c4d perf(build): 운영 빌드가 react-router의 운영 빌드를 싣는다
문제: react-router 7.18.1의 exports는 모든 조건에서
dist/development/*를 가리킨다. 그 파일은 ENABLE_DEV_WARNINGS = true라
운영 번들의 초기 청크에 라우터 개발 경고 문구("You rendered descendant
…")가 들어 있었다. 운영 콘솔에 개발 경고가 뜨고, 초기 JS가 약 600 B 크다.

고른 방법: vite build일 때만 react-router-dom이 import하는 두 진입점
(react-router, react-router/dom)을 같은 패키지의 dist/production 파일로
alias한다. 경로는 react-router-dom에서 react-router를 resolve한 개발
진입점 옆에서 찾고, 파일이 없으면 빌드를 멈춘다. 개발 서버와 테스트는
개발 빌드를 그대로 써서 경고를 받는다.
버린 대안: 고정 경로 alias(리뷰 실험). 업그레이드로 배치가 바뀌면
조용히 깨진다. react-router에 production 조건을 요청하기는 시점을 정할
수 없어 이 alias를 지울 조건으로만 적었다.

위험·한계: exports 밖 경로를 쓴다. 업그레이드 때 배치가 바뀌면 빌드가
실패한다(조용히 개발 빌드로 돌아가지 않는다). Firefox·WebKit e2e는
돌리지 않았다.

검증: tests/unit/build-environment-bundle.test.ts가 빌드한 JS에 개발
경고 문구가 없음을 본다(고치기 전 chunk-KS7C4IRE 1개에서 실패).
같은 빌드(local-build) 초기 JS 201,552 → 200,939 B(−613 B), 파일 25개.
라우터를 쓰는 e2e 5개 spec 14건(app-shell, reference-route,
reference-save, scroll-restoration, platform-overview, chromium) 통과.

Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-07
2026-11-04 20:25:48 +09:00
DongHyeonka 529615dc8e chore(artifacts): 실행 로그를 추적하지 않는다
문제
scripts/scale/run-scale-profile.ts는 단계 출력을
artifacts/scale/<tier>/<step>.log에 쓴다. 이 로그와
verify:extreme-scale·phase5 로그 63개가 git에 추적되고, .gitignore는
artifacts의 json·xml·txt·sarif만 무시한다. 그래서 merge 게이트
check:scale:pr(FE-GATE-005)를 로컬에서 한 번 돌리면 추적 로그 3개가
바뀌고 새 로그 1개가 생겨 작업 트리가 더러워진다. 커밋된 판은 다른
기계의 경로와 ANSI 색 코드를 담고, 읽는 코드·테스트·설정은 없다.

고른 방법
- .gitignore에 artifacts/**/*.log를 넣고 63개 추적을 끊는다. scale
  로그(12-08) 35개만이 아니라 같은 원인의 extreme-scale·phase5 로그도
  같이 뺀다(0929/11-09 남은 항목).
- 기준 측정은 이미 config/scale/benchmark-baseline.json 같은 정해진
  JSON이 맡는다. 로그를 증거로 쓰는 곳은 없다(git grep).

위험·한계
- 동기화 때 다운스트림에서 이 파일들이 지워진다. 두 다운스트림은 이미
  지웠다(지난 리뷰 기록).

검증
- check:scale:pr PASSED 뒤 git status에 로그 변경이 없다.

Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-08
Refs: docs/reviews/2026-11-03-maturity-review/11-tests-browser-release-scale.md 0929/11-09
2026-11-04 20:24:58 +09:00
DongHyeonka 08ed0a088d fix(contracts)!: FE-REG-API 행에 status 목록·상한·재시도 예산·검증 생략을 담는다
문제
V2 행과 V2/V3 parity 테스트를 지운 뒤 FE-REG-API 행은 descriptor에서
12칸만 뽑는다. acceptedStatuses, emptyBodyStatuses, 바이트 상한, 마감,
retryBudget, traffic, commandEffect, commandRecovery, 검증 생략 표시는 행에
없다. 그래서 생성 API의 acceptedStatuses를 [200, 201]에서 [201]로 줄여도
check:registries가 통과한다(실험 X2). 이전 커밋 d99301b에서는 같은 변경이
breaking 증거 누락으로 실패했다. 응답 상한·마감 변경은 기록에서 사라졌고
(X3·X6), problemSchema는 breaking 칸이 아니어서 problem 검증기 id를 바꿔도
behavior-change로 통과했다(X4). 짝 백엔드는 생성에 201, 본문 없는 응답에
204를 쓴다. 이 status를 빼면 배포 뒤 그 API가 모두 실패한다.

고른 방법
- projectApiOperationRows가 함수 밖의 descriptor 값을 모두 뽑는다:
  acceptedStatuses, emptyBodyStatuses, unvalidated(검증을 건너뛰는 검증기
  칸 이름: input·output·problem), requestByteLimit, responseByteLimit,
  totalDeadlineMs, retryBudget, traffic, commandEffect, commandRecovery.
- commandEffect는 함수를 빼고 데이터만 남긴다: classifyStatus가 있는지
  (classifiesStatus)와, descriptor가 이름을 붙였을 때만 refusedBeforeWrite
  목록. refusedBeforeWrite는 다른 작업에서 더해지는 선택 칸이라 구조로
  읽고, 없으면 행에도 없다.
- governance: problemSchema와 unvalidated를 breakingFields에 넣는다.
  status 배열은 breakingFields에 넣지 않는다. 분류기가 배열에서 값이
  빠지면 이미 allowed-value-removed breaking으로 본다. breakingFields에
  넣으면 status를 더하는 것(전에 받던 응답을 모두 계속 받는 변경)까지
  증거를 요구한다. 숫자 칸·traffic·command 칸은 behavior-change로 기록한다.
- 매뉴얼 01 9단계에 무엇이 breaking이고 무엇이 behavior-change인지,
  descriptor 함수는 행에 없다는 것을 적었다.

버린 대안
- descriptor 전체(함수 제외)를 투영: policyId·diagnosticsOperation까지
  기준선이 흔들려 리뷰 잡음만 는다. 둘은 wire 값이 아니다.
- V2/V3 parity 테스트 부활: 사본이 다시 둘이 된다.
- 숫자 칸 감소를 breaking으로: 분류기에 방향 규칙이 없고, 상한·마감
  조정은 자주 하는 운영 값이다. 기록만 하고 PR에서 본다.

위험·한계
- governance 계약(requiredFields·fieldTypes·breakingFields)이 바뀌어
  기준선을 다시 승인했다. 다운스트림은 동기화 때 재승인 1회가 필요하다.
- FE-REG-SCHEMA에 problem 스키마 행이 없어 problemSchema는 참조 검사
  대상이 아니다. breaking 칸으로만 잠근다.
- classifyProblem이 무엇을 NOT_APPLIED로 보는지는 함수라 기록되지 않는다.

검증
- 기준선 재승인 뒤 실험 재실행(check:registries):
  X2 [200,201]->[201] 실패(acceptedStatuses:allowed-value-removed 증거 누락),
  X4 problem 검증기 id 변경 실패(problemSchema:field-changed 3건),
  X5 GET 출력 검증기 생략 실패(unvalidated:field-changed),
  X3 응답 상한·X6 마감 변경은 behavior-change로 통과하고 스냅샷에 남는다.
- tests/unit/api-operation-rows.test.ts: 새 칸 고정, refusedBeforeWrite
  있음·없음, governance JSON으로 분류한 8가지 변경.
- run-vitest related(api-operations.ts, governance) 21파일 156건,
  registry 테스트 4파일 63건, check:registries:compatibility-fixtures,
  check:types, eslint, verify:documentation 통과.

BREAKING CHANGE: FE-REG-API governance 계약이 바뀌어 다운스트림의
check:registries가 FE-REG-API:$contract:* contract-field-changed로
실패한다. 동기화 뒤 REGISTRY_BASELINE_OWNER·REGISTRY_BASELINE_REASON을
주고 update:registry-baseline을 한 번 돌린다.

Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-01
Refs: docs/reviews/2026-11-03-maturity-review/README.md 3절
2026-11-04 20:24:41 +09:00
DongHyeonka 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
2026-11-04 20:24:14 +09:00
DongHyeonka 5d0f8454c6 test(http): Envelope 판정 경계와 처리 중 409 무재전송을 고정한다
문제
Envelope 실패 판정 표(backend-envelope.ts)와 실행기의 실패 Envelope
처리는 커버리지가 100%인데 경계 다섯 곳이 테스트에 걸리지 않는다. 표의
code를 다른 status로 보내는 행, 표 밖 422, 게이트웨이 408·425, 응답
한도보다 크고 64 KiB보다 작은 실패 본문, JSON이 아닌 실패 본문이 없다.
그래서 변이 H14(=M6, status 대조 제거)·H45(표 밖 422를 분류기로)·H15
(408·425 제거)·H23(실패 한도를 64 KiB 고정)·H10b(실패 media type 검사
제거)가 살아남았다. 처리 중 409를 자동 재전송하게 바꾼 변이 M7도
살아남았다. Envelope 표 테스트는 재시도 예산이 0이라 재전송을 볼 수
없었다. 같은 문서의 이월 항목 둘도 그대로다. 결과 불명 동안 입력
identity를 잡는 네 줄(M1, 0929/03-06)과 반사 correlation 문법 검사(M3,
1101/03-06)를 지워도 테스트가 통과한다.

고른 방법
- tests/unit/backend-envelope.test.ts: envelopeFailureEffect·
  idempotencyRefusalReason·envelopeFailureReading을 status × code 표로
  직접 부른다.
- envelope 통합 테스트: LENIENT 묶음에 422 INTEGRITY_MISMATCH 한 행,
  한도를 넘는 실패 Envelope와 text/plain 실패 본문(네이티브 Response),
  retryBudget 1인 KEYED가 409 IDEMPOTENT_IN_FLIGHT에 한 번만 보내는 행.
- 결과 불명 입력이 두 칸짜리 identity 레지스트리에서 밀려나지 않는지,
  문법 밖 반사 id가 보낸 id로 바뀌는지를 각각 한 건씩 더한다.

위험·한계
테스트만 더했다. 동작은 바꾸지 않았다.

검증
- 변이 8종(H14·H45·H15·H23·H10b·M7·M1·M3)을 하나씩 넣고 관련 테스트를
  돌렸다. 모두 새 테스트에서 실패하고, 되돌리면 통과한다.
- check:types, lint 통과. 바뀐 4파일 83건 통과.

Refs: docs/reviews/2026-11-03-maturity-review/10-tests-fast-layers.md 10-02
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-08
2026-11-04 20:24:09 +09:00
DongHyeonka 4e37b07ff9 fix(removal): CI 스크립트가 없는 기능 제거도 CI 기준선 사유를 만든다
문제
test:sample-removal -- --feature=<id>는 참조 기능이 아닌 기능에
ciScripts: []를 쓴다. pruneRemovalFixtureCiContract가 그 빈 집합으로
기준선 사유를 "removal fixture pruned "(끝 공백)로 만들고, 바로 뒤
기준선 검사가 "leading/trailing whitespace is forbidden"으로 거부한다.
그래서 create:feature로 만든 모든 기능의 제거 드릴이 3초 만에 무관한
오류로 끝나고 게이트 검사는 하나도 돌지 않는다.

고른 방법
- 지운 스크립트가 없으면 사유를 "removal fixture pruned no CI scripts"로
  쓴다.
- 이 길을 merge 게이트가 돌게 하는 것(test:feature-scaffold가 생성
  기능에 --feature 드릴을 한 번 돌림)은 같은 발견의 둘째 절반이라
  드릴 범위를 고치는 다음 커밋에서 한다.

위험·한계
- 이 커밋만으로는 제품 기능 제거 드릴 전체를 실행해 보지 않았다.

검증
- RED: 새 테스트 "re-baselines a removal that prunes no CI script" 실패
  (reason 'removal fixture pruned ').
- 수정 뒤 tests/unit/removal-fixture.test.ts 9건 통과.

Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-02
2026-11-04 20:24:02 +09:00
DongHyeonka af6d0a9f01 perf(build): react-dom을 자기 청크로 빼 build id만 바뀐 release의 캐시 손실을 줄인다
문제: build id는 부트 실패 화면이 보여 주므로 render-boot-failure 청크에
들어간다. react-dom과 scheduler(약 56 KB gzip)가 같은 청크에 있어서
build id만 다른 두 빌드에서 boot·index·render-boot-failure 세 파일의
이름이 바뀌었다. 합계 99,785 B로 초기 JS의 49.4%다. 해시 자산은 1년
immutable로 캐시되는데, 재방문 사용자는 코드가 같아도 release마다 이만큼
다시 받았다. 1101 O1이 같은 것을 재고 채택을 권했지만 결정 기록이 없었다.

고른 방법: codeSplitting.groups에 react-dom·scheduler 그룹을 더한다
(includeDependenciesRecursively: false라 라이브러리 모듈만 묶는다).
같은 비교에서 바뀐 초기 JS가 44,297 B(22.0%)로 준다. 초기 JS는
201,857 → 201,552 B, 초기 파일 수는 25개 그대로다(react-dom 진입
모듈 1.3 KB 청크가 합쳐졌다).
버린 대안: build id를 JS에 넣지 않고 release-manifest.json에서만 읽기.
boot까지 바뀌지 않아 더 줄지만, 부트 실패 화면이 build id를 보여 주는
계약을 바꿔야 한다.

위험·한계: boot(39 KB)는 build id로 설정을 대조하므로 계속 바뀐다.
그룹 정규식은 pnpm의 node_modules 배치를 가정한다. 배치가 바뀌어 그룹이
비면 새 테스트가 실패한다.

검증: tests/unit/build-environment-bundle.test.ts가 build id만 다른 두
빌드에서 react-dom이 든 청크의 이름이 같고 그 청크가
render-boot-failure가 아님을 본다(고치기 전 실패). 부트 실패 화면
e2e(tests/e2e/boot-module-failure.spec.ts, chromium) 통과.
feature-shape-growth·design-system-initial-chunk·bundle-classification
통과. 두 빌드 비교는 docs/operations/performance-evidence.md에 기록했다.

Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-06
2026-11-04 20:23:54 +09:00
DongHyeonka b3ce732249 test(e2e): compact smoke가 빌드에 준 VITE_BUILD_ID를 기대값으로 쓴다
문제
tests/e2e/compact-smoke.spec.ts가 html의 data-build-id를 "local-build"로
고정해 비교한다. workflow는 전체 env에 VITE_BUILD_ID=gitea-<run>-<attempt>를
넣고, preview 서버가 그 env로 빌드한다. 그래서 실제 CI에서 FE-GATE-008이
코드와 무관하게 항상 실패한다.

고른 방법
- 기대값을 이 프로세스의 VITE_BUILD_ID에서 읽고, 비었으면 "local-build"를
  쓴다. playwright webServer가 같은 env로 빌드하고,
  scripts/generate-runtime-config.ts가 같은 규칙(값 || "local-build")으로
  BUILD_ID를 정한다.
- 버린 대안: build id가 비어 있지 않은지만 보기. 빌드에 준 값이 화면까지
  오는지(release manifest·runtime config 일치)를 더는 확인하지 못한다.
  vite loadEnv로 .env 파일까지 읽기. build id는 .env가 아니라 프로세스
  env에서만 온다(generate-runtime-config.ts, generate-build-manifest.ts).

위험·한계
- CI=true와 러너 이미지 조건, ci:gate FE-GATE-008 전체는 돌리지 않았다.

검증
- RED: VITE_BUILD_ID=gitea-1-1로 chromium-compact 1건 실패
  (data-build-id "local-build" 기대).
- 수정 뒤 VITE_BUILD_ID=gitea-1-1, 기본값 두 경우 모두 1 passed.

Refs: docs/reviews/2026-11-03-maturity-review/README.md 11-06
2026-11-04 20:23:33 +09:00
DongHyeonka 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
2026-11-04 20:23:22 +09:00
DongHyeonka 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
2026-11-04 20:23:21 +09:00
DongHyeonka e7d63586b6 fix(features): 기능 어댑터 기여에 needs에 적은 capability만 넘긴다 (1103/09-08)
문제
조립 루트 주석과 생성 뼈대 주석은 "기능은 needs에 적은 capability만 받는다"고
했지만, invokeContribution은 context 전체를 넘겼다. needs: ["telemetry"] 기여가
["telemetry","http"]를 받았다(E6). 제품 capability도 모든 기능에 갔다. 타입이
막고 있어 cast가 있어야 생기지만, 그러면 needs가 실제 의존을 다 말하지 않는다.

고른 방법
invokeContribution이 needs의 키만 골라 새 frozen 객체로 넘긴다. 주석을 "타입만
그렇다"로 고치는 대안은 생성 뼈대 주석(scripts/create-feature.ts)까지 모든
기능에 퍼진 설명을 바꿔야 해서 버렸다. 이제 두 주석이 실행과 맞는다.

위험·한계
needs에 적지 않은 capability를 cast로 쓰던 다운스트림 기능은 그 값이
undefined가 된다. repo 안에는 그런 기능이 없다.

검증
- RED: feature-adapter-composition.test.ts에 E6 행(받은 키가 ["telemetry"])을
  더했고 수정 전 실패.
- tests/contract/reusable-capability, tests/features, runtime-adapters 계열,
  product-composition-fixture → 27 files / 178 tests 통과.
- check:types, eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-08
2026-11-04 20:22:58 +09:00
DongHyeonka 46dfe23f69 fix(bundle): 예산을 넘으면 넘은 한도와 초과량을 출력하고 초기 파일 수를 막는다
문제: 초기 JS가 예산을 넘으면 check:bundle은
"Bundle budget or manifest integrity failed: " 한 줄만 쓰고 콜론 뒤가
비어 있었다. 측정값과 한도는 artifacts/performance/bundle.json에만 있어
예산 실패인지 manifest 무결성 실패인지, 몇 바이트 넘었는지 알 수 없었다.
또 초기 JS 파일 수에는 상한이 없어 08-08처럼 파일을 16개에서 25개로
늘리는 변경도 모든 게이트를 통과했다. 템플릿은 HTTP/2를 전제로 초기
청크를 나눠 두었는데, 파일 수를 늘리는 결정이 어디에도 드러나지 않았다.

고른 방법: 예산 실패와 무결성 실패를 다른 문장으로 쓴다. 예산 실패는
넘은 한도마다 측정값·한도·초과량을 한 줄로 쓴다
(describeBundleBudgetFailures). config/performance/budgets.json에
initialJsFiles(지금 25)를 두고 check:bundle이 entry를 포함한 초기 파일
수를 센다. bundle.json 스키마는 측정값·한도·결과와 자가 검사 fixture를
하나씩 더 가진다. 두 변경은 같은 함수와 스키마를 고치므로 한 커밋에
넣었다.
버린 대안: 파일 수를 문서에만 적기. 08-08이 그 상태에서 파일을 늘렸다.

위험·한계: 초기 파일을 하나라도 늘리는 변경은 이제 budgets.json을 같이
고쳐야 통과한다. 그것이 목적이다. HTTP/2 확인 자체는 이 커밋에 없다
(13-02에서 probe에 넣는다).

검증: tests/unit/check-bundle-output.test.ts가 손으로 만든 빌드 출력에
check-bundle.ts를 돌려 통과·초기 바이트 초과·lazy 초과·파일 수 초과·
무결성 실패의 출력을 본다(고치기 전 4건 실패). bundle-artifact-contract,
performance-budgets 통과. 실제 빌드에서 check:bundle PASS(25 / 25 files).

Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-03, 15-05
2026-11-04 20:22:27 +09:00
DongHyeonka bca5fc2796 fix(ci): coverage 증거 검사가 summary의 branchesTrue를 받는다
문제
FE-GATE-005의 증거 검사(scripts/lib/ci-artifact-validator.ts)는
coverage-summary.json 항목마다 lines·statements·functions·branches만
허용하는 .strict() schema를 쓴다. istanbul-lib-coverage 3.2.2는 빈
summary에 branchesTrue를 항상 넣으므로 total에 그 키가 있다. 그래서
테스트가 모두 통과해도 증거 단계에서 게이트가 실패한다. 같은 파일을
읽는 risk-coverage 게이트는 이 키를 허용해 두 검사기가 갈라져 있었다.

고른 방법
- 키 목록을 scripts/lib/coverage-summary-metrics.ts 한 곳에 두고 두
  검사기가 같이 쓴다. 평가하는 네 지표와, 보고기가 더할 수 있는 선택
  지표(branchesTrue)를 나눴다. 선택 지표도 counter 형식(pct 정확성
  포함)은 그대로 검사한다.
- 버린 대안: validator schema에만 branchesTrue를 더하기. 지금 고장의
  원인(두 목록)이 그대로 남는다. 상수를 risk-coverage.ts에서
  export하기. validator가 @babel/eslint-parser까지 읽게 된다.

위험·한계
- 다른 미지의 키는 여전히 거절한다(의도). 보고기를 올리면 새 키가 생길
  수 있다.
- ci:gate FE-GATE-005 전체는 이 커밋에서 돌리지 않았다.

검증
- RED: 새 tests/unit/coverage-summary-artifact.test.ts 3건 중 2건 실패
  (Unrecognized key: "branchesTrue").
- 수정 뒤 coverage-summary-artifact·risk-coverage·risk-coverage-files
  44건 통과. check:types 통과, 바꾼 파일 eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/README.md 12-09
2026-11-04 20:22:13 +09:00
DongHyeonka f98d0c3663 fix(contracts): 계약 조립 오류 메시지에 원인을 싣는다 (1103/09-07)
문제
ContractContributionError의 message는 "Installed contract contribution is not
composable" 하나였고 원인은 reason 속성에만 있었다. check:registries는
message 첫 줄만 적으므로, 제품 인증 프로필 id를 잘못 적으면 게이트 출력에
operation id도 프로필 id도 없었다("missing registry source …: Installed
contract contribution is not composable"). 매뉴얼 02 5절과 starter-experience
정본 표는 V2 해석기와 함께 지워진 "REST security profiles are incoherent …"
메시지를 약속했다.

고른 방법
message에 reason을 붙인다: "Installed contract contribution is not composable:
<reason>". 메시지를 읽는 모든 곳(check:registries, vitest, 부팅 오류)이 원인을
보게 된다. check-registries.ts만 reason을 적게 하는 대안은 다른 출력 경로를
그대로 두어 버렸다. reason은 기능·operation·프로필 id 같은 개발자 식별자뿐이다.
문서 세 곳(매뉴얼 02 5절, errors.md, starter-experience 표)을 실제 출력으로
고쳤고, V3 descriptor에 없는 auth 칸 조합 문장을 지웠다.

위험·한계
- check:registries가 같은 실패 뒤에 적는 연쇄 줄(FE-REG-API is not an object
  registry, breaking change missing evidence … removed)은 그대로다(14-06 범위).
- message 문자열 전체를 비교하는 다운스트림 테스트가 있으면 바뀐다.

검증
- RED: second-api-feature-registries.test.ts에 authProfileId를 SECOND_UNKNOWN
  으로 바꾼 행을 더했고, 수정 전 stderr에 원인이 없어 실패.
- 같은 파일, external-contract-runtime, http-execution-v3-auth-profile,
  reference-fixture-provenance, tests/platform → 33 files / 255 tests 통과.
- eslint, tsc(test), verify:documentation PASS_SCOPED.

Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-07
2026-11-04 20:21:55 +09:00
DongHyeonka 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
2026-11-04 20:21:39 +09:00
DongHyeonka 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
2026-11-04 20:21:39 +09:00
DongHyeonka e4caafda30 fix(contracts)!: 읽기 operation은 SAFE·IDEMPOTENT일 때만 조립한다
문제
GET에 `retrySemantics: "KEYED"`(commandRecovery 없음)나 `"NEVER"`를
적어도 계약 조립이 통과하고 FE-REG-API 행에 그 값이 남는다. KEYED 복구
descriptor 검사가 쓰기 분기 안에만 있기 때문이다. 실행기는 이 GET을
쓰기로 보지 않아 재시도 없는 읽기로 돌린다. 매뉴얼은 "읽기(GET)는 늘
SAFE"라 적는다. V2 `defineRestOperation`은 조회에 SAFE·IDEMPOTENT만
허용했는데 V2 삭제 때 이 규칙이 V3로 옮겨지지 않았다(실험 R1).

고른 방법
assertHttpContract의 읽기 분기에서 GET·HEAD의 retrySemantics가 SAFE나
IDEMPOTENT가 아니면 method와 값을 담아 거절한다. realtime snapshot 바인딩이
요구하는 짝(GET + SAFE·IDEMPOTENT)과 같은 어휘다. 매뉴얼 02 3절 "틀리면"에
거절 문구를 더했다.

버린 대안
- 레지스트리 governance의 allowedValues로 막기: method별 허용값을 표현할
  칸이 없고, 조립(부팅 경로)이 아니라 check:registries에서만 걸린다.

위험·한계
- GET·HEAD를 KEYED나 NEVER로 적은 다운스트림 descriptor는 부팅에서 계약
  조립 실패가 된다. 템플릿 안에는 그런 descriptor가 없다(grep).
- 쓰기의 SAFE 금지(03-03)는 이 커밋 범위가 아니다.

검증
- RED: tests/unit/external-contract-runtime.test.ts의 GET·HEAD × KEYED·NEVER
  4건이 실패(조립 통과)했다.
- GREEN: `run-vitest related src/contracts/external-contract-runtime.ts`
  105파일 950건 통과. check:types, eslint, check:registries,
  verify:documentation 통과.

BREAKING CHANGE: GET·HEAD operation의 retrySemantics가 KEYED나 NEVER이면
계약 조립이 CONTRACT_CONTRIBUTION_INVALID로 실패한다. SAFE(재시도 허용)나
IDEMPOTENT로 바꾼다. 재시도를 막으려면 frontend.retryBudget을 0으로 둔다.

Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-01
2026-11-04 20:21:04 +09:00
DongHyeonka 3af2c8ea2b test(browser-transfer): Retry-After와 abort 멱등 키 규칙 세 개를 테스트로 고정한다
문제: 문서와 주석이 적은 규칙 세 개를 바꿔도 영역 단위 테스트가 모두
통과한다. 리뷰 변이 N2(part 단계가 503의 Retry-After를 읽지 않음),
N10(abort 재시도마다 ABORT 멱등 키를 바꿈, 세 라운드째 생존),
N17(control plane이 헤더 없는 429를 retryable:true로 냄)이 살아남았다.

고친 방법: 규칙마다 실패하는 테스트를 더한다.
- part 단계 Retry-After 묶음에 503을 더한다. 실제 presigned provider·
  vault·실행기로 발급과 PUT 두 단계를 본다.
- abort가 한 호출 안에서 재시도하고 다음 abort() 호출에서 다시 보낼 때
  세 요청의 idempotencyKey가 모두 같은지 본다. 같은 파일의
  createSession·part·complete 키 테스트와 같은 방식이다.
- fetch transport가 헤더 없는 429와 상한 밖 429를 retryable:false,
  retryAfterMs 없음으로 내는지 본다.

위험·한계: 테스트만 더했다. 동작은 바뀌지 않는다.

검증:
- 영역 단위 테스트(resumable-upload, presigned-transfer, image-cdn,
  upload-cancellation) 15파일 272건 통과
- 변이를 하나씩 넣고 돌렸다: N2 4건 실패, N10 1건 실패, N17 2건 실패.
  변이는 원본으로 되돌렸다
- check:types, eslint(바꾼 두 파일) 통과

Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 01-03
2026-11-04 20:20:51 +09:00
DongHyeonka 1dfe86a372 test(browser-files): 손상 데이터·로그아웃 경로의 보호 규칙 5개를 고정한다
문제: 2026-11-03 리뷰 변이 중 아래 5개가 관련 unit 파일을 모두
통과했다. 규칙을 고치는 사람은 테스트가 통과해도 손상·로그아웃 보호가
남았는지 알 수 없다.
- L6 cleanupOwned()가 읽을 수 없는 pointer를 "pointer 없음"으로 보고
  지금 서비스 중인 release까지 지운다.
- L7 stage가 손상된 marker를 고치지 않고 실패한다. REHYDRATE 안내가
  기대는 회복 경로다.
- L4 preview가 파일 resolve 뒤 #disposed를 다시 보지 않는다.
- L5 vault resolveFile이 load 뒤 #disposed를 다시 보지 않는다.
- L1 vault dispose()가 File 참조 Map을 비우지 않는다.
L4·L5는 lease registry가 dispose 뒤에도 lease를 내주기 때문에 소비자
쪽 검사가 유일한 방어선이다.

고른 방법: 규칙마다 실패하는 테스트 하나를 더한다. 리뷰가 L5에
제안한 readRange()는 slice 읽기 뒤에 #disposed를 한 번 더 보므로 L5를
잡지 못한다. 그래서 resolve 직후 소스를 돌려주는 openSource()로
고정했다.

위험·한계: 테스트만 바꾼다. 동작 변경 없음.

검증: 5개 변이를 하나씩 넣고 browser-files 단위 5파일 + tests/recipes,
cache 단위 3파일 + tests/recipes를 돌렸다. L1·L4·L5·L6·L7 모두 새
테스트 하나씩이 실패했고(되돌린 뒤 통과), 원래 코드에서 두 파일 34건
통과. check:types:test, 바꾼 파일 eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 02-03
2026-11-04 20:20:11 +09:00
DongHyeonka bf9df9a5c2 docs(features): 기능 실행부 설명 네 곳을 V2 삭제 뒤 모양으로 고친다 (1103/09-10)
문제
FeatureRuntime은 featureId·schemas·adapters·contractContributions인데, 네 곳이
지워진 V2 모양을 적었다. feature-module.ts 머리 주석("API contracts with their
runtime schemas and mappers"), installed-feature-contracts.ts("The V2 API
registries"), frontend-application-foundation.md("composes the V2 API
registries"), starter-experience.md 기능 추가 2단계("the API contract
(operations, schema metadata, runtime schemas, mappers)"). 기능 작성자가 없는
칸을 찾게 된다. 07-05(starter-experience 같은 문장)를 함께 닫는다.

고른 방법
네 문장을 지금 모양으로 고친다: schemas는 FE-REG-SCHEMA 행, 어댑터 기여는
application input, 계약 기여는 HTTP operation이고 FE-REG-API 행은 거기서
투영한다(installed-feature-runtime-registries.ts와 같다).

위험·한계
verify:documentation은 문장 내용을 보지 않으므로 다시 낡아도 게이트가 모른다.

검증
- git grep "V2 API registr|runtime schemas, mappers|runtime schemas and
  mappers" -- src docs/architecture → 0건.
- verify:documentation PASS_SCOPED.

Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-10
Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-05
2026-11-04 20:19:59 +09:00
DongHyeonka a94006b9da test(contracts): 쿠키 쓰기 CSRF와 realtime snapshot 검사를 method별 표로 고정한다
문제
V2에서 옮긴 두 조립 검사가 한 사례씩만 테스트된다. 쿠키 쓰기 CSRF
검사는 POST와 x-xsrf-token 한 쌍만 본다. 그래서 `!isRead`를
`method === "POST"`로 좁히거나, CSRF 헤더 이름 대신 "필수 헤더가 하나라도
있으면"으로 바꾸거나, x-csrf-token 허용을 지워도 테스트가 통과한다.
realtime snapshot 바인딩(GET + SAFE·IDEMPOTENT)은 거절 사례가 없어
method 조건이나 retrySemantics 조건을 지워도 통과한다.

고른 방법
- rest-profile-contract: POST·PUT·PATCH·DELETE마다 CSRF 없는 쿠키 프로필과
  x-tenant-context만 요구하는 쿠키 프로필을 거절하고, x-csrf-token과
  x-xsrf-token을 각각 받는지 본다. GET·HEAD 쿠키 읽기는 CSRF 없이 된다.
- realtime-stream-registry: 6 method × 4 retrySemantics 표를 CURSOR와
  SNAPSHOT_ONLY 두 복구 모드로 돈다. 받는 조합은 GET×SAFE, GET×IDEMPOTENT
  뿐이다. 행은 조립한 descriptor를 projectApiOperationRows로 뽑은 것에서
  method와 retrySemantics만 바꾼다. 투영 칸 이름이 바뀌어도 이 표가 같이
  깨진다. FE-REG-API 행이 없는 id도 거절한다.

버린 대안
- 손으로 쓴 행(fixture.ts)을 그대로 쓰기: 투영과 realtime 검사가 따로
  바뀌는 것을 못 잡는다.

위험·한계
- 검사 코드는 바꾸지 않았다. 테스트만 더했다.
- resumable upload 제어 요청의 쿠키 POST는 descriptor 밖이라 이 검사
  범위가 아니다(영역 01).

검증
- 변이 7종을 하나씩 넣고 두 테스트 파일을 돌렸다. 모두 실패한다:
  M2(POST만), M3(아무 필수 헤더), H19(x-csrf-token 허용 삭제),
  M9(method 조건 삭제), M9b(method·retry 조건 삭제), S2(retry 조건 삭제),
  H21-PUT(GET 또는 PUT 허용).
- 변이 없이 두 파일 47건 통과. check:types, eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-02
Refs: docs/reviews/2026-11-03-maturity-review/10-tests-fast-layers.md 10-03, 10-04
Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 04-03
2026-11-04 20:19:33 +09:00
DongHyeonka 9edc8307b0 fix(features)!: 기능이 아닌 폴더 표시를 NOT_A_FEATURE로 바꾸고 선언과 함께 두면 실패한다 (1103/09-09)
문제
src/features/<dir>/NOT_INSTALLED 표시는 "기능이 아닌 샘플 폴더"라는 뜻인데,
같은 단어가 런타임 상태 "선언됐지만 빌드·FEATURE_OVERRIDES가 뺀 기능"으로도
쓰였다(product-features.ts). 생성기는 feature-module.ts를 못 읽을 때만 표시를
찾았으므로, 샘플을 졸업시키며 표시를 지우지 않으면 표시가 "설치 안 됨"이라고
말하는 채로 조용히 설치됐다.

고른 방법
- 표시 이름을 NOT_A_FEATURE로 바꾼다(local-draft-feature 파일 이름 변경).
  런타임 상태 NOT_INSTALLED는 그대로 둔다.
- 생성기가 표시와 feature-module.ts가 함께 있으면 둘 중 무엇을 지울지 적고
  실패한다.
- 옛 이름 표시는 받지 않는다. 받으면 같은 다의가 남는다. 옛 표시만 있는
  폴더는 "has no feature-module.ts; … mark the directory with NOT_A_FEATURE"로
  실패해 새 이름을 알려 준다.
README 상태 표, starter-experience, 매뉴얼 errors·patterns 표를 맞췄다.

위험·한계
다운스트림이 자기 폴더에 NOT_INSTALLED 표시를 두었다면 생성 단계가 실패한다.
파일 이름만 바꾸면 된다.

검증
- RED: 생성기 테스트 3건(새 이름 허용, 옛 이름 거절, 동시 존재 거절)이
  수정 전 실패.
- generate-product-feature-index.test.ts 17건 통과. generate:feature-index
  통과. verify:documentation PASS_SCOPED. eslint, tsc(node·test) 통과.

BREAKING CHANGE: src/features/<dir>/NOT_INSTALLED 표시 파일은 더 이상
인식되지 않는다. 같은 자리에 NOT_A_FEATURE라는 이름으로 옮긴다.

Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-09
2026-11-04 20:19:17 +09:00
DongHyeonka 851fdedbcd fix(apps): 대소문자·끝 슬래시만 다른 기능 라우트도 같은 경로로 거절한다 (1103/08-04)
문제
같은 모양 검사가 파라미터 이름만 지운 문자열로 비교했다. React Router는
대소문자를 무시하고 끝 슬래시를 같은 경로로 본다. 그래서 /shop/items/:itemId와
/shop/Items/:id, /shop/items와 /shop/items/가 조립을 통과했고 라우터는 그중
하나만 그렸다. 메뉴·레지스트리에는 둘 다 나왔다.

고른 방법
모양 키를 만들 때 소문자로 바꾸고 끝 슬래시를 지운다. 라우트 경로 문법을
소문자·끝 슬래시 없음으로 제한하는 검사는 기존 라우트에 새 규칙을 거는
것이라 버렸다.

위험·한계
라우터가 caseSensitive를 켜면 이 검사가 과하게 거절한다. src에 caseSensitive
사용은 없다.

검증
- RED: context-route-roots.test.ts의 새 두 행이 수정 전 실패.
- tests/architecture, router, context-layouts → 9 files / 64 tests 통과.
  /a/new와 /a/:id 허용 행은 그대로 통과. eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/08-presentation.md 08-04
2026-11-04 20:19:07 +09:00
DongHyeonka b0195e3d59 ci(visual): 브라우저 설치 단계가 시각 테스트 글꼴 패키지를 설치한다
문제
tests/visual/fonts.conf는 Noto Sans·Noto Sans CJK·Liberation Mono가
있는 OS 글꼴 디렉터리만 읽는다. 생성 workflow의 브라우저 설치 단계는
`playwright install --with-deps` 한 줄이고, Playwright 의존 패키지에는
이 글꼴이 없다. 그래서 빈 러너에서는 FE-GATE-008이 코드와 무관하게
`visual-fonts` 단계에서 실패한다(1101/11-02의 남은 절반).

고른 방법
- 생성기(scripts/generate-ci-workflow.ts)의 browser-install 단계가
  `--with-deps` 뒤에 글꼴 패키지 4개를 apt-get으로 설치한다.
  `--with-deps`가 이미 패키지 목록을 갱신했으므로 update를 다시 하지
  않는다. root가 아닌 러너에서만 sudo를 붙인다.
- 패키지 목록을 scripts/lib/visual-test-fonts.ts 한 곳에 두고 생성기와
  tests/visual/fonts.setup.ts의 설치 안내가 같이 읽는다.
- 글꼴이 필요한 것은 FE-GATE-008뿐이지만 브라우저 단계 두 곳 모두에
  넣었다. 게이트 ID로 갈라 쓰면 생성기가 게이트 목록에 묶인다.
- 버린 대안: job container 고정(러너의 컨테이너 지원 미확인),
  ci:gate가 패키지 설치(개발자 PC에서도 sudo 요구).

위험·한계
- 실제 러너나 깨끗한 Ubuntu 24.04 컨테이너에서 이 단계를 돌리지
  않았다. 패키지 이름과 디렉터리는 이 호스트(Ubuntu)와 fonts.conf로만
  확인했다.
- CJK 패키지 때문에 브라우저 job 설치 시간이 수십 MB만큼 는다.
- gates.json은 바꾸지 않았다(단계 종류는 그대로 browser-install).

검증
- ci-workflow-generation 새 테스트: 생성기 수정 전 실패, 수정 뒤 통과.
  파일 전체 424건 통과(스냅샷 1건 갱신).
- generate:ci-workflow로 workflow 재생성. check:ci PASS.
- lint, check:types:node, check:types:test, verify:documentation PASS.

Refs: docs/reviews/2026-11-03-maturity-review/11-tests-browser-release-scale.md 11-02
2026-11-04 20:18:40 +09:00
DongHyeonka 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
2026-11-04 20:17:50 +09:00
DongHyeonka 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
2026-11-04 20:16:38 +09:00
DongHyeonka 4282a541d0 fix(forms): 필드 code 문구를 표의 자기 키로만 찾는다 (1103/08-03)
문제
validationMessage가 VALIDATION_COPY[code]로 찾았다. Object.freeze({...})는
Object.prototype을 물려받으므로 constructor·toString·hasOwnProperty·
__proto__는 undefined가 아니라 함수·객체가 되고 ?? 대체가 걸리지 않았다.
그 값이 문구 키로 넘어가 "요청한 문구를 표시할 수 없습니다."가 나왔다.

고른 방법
같은 영역의 다른 표(route-codecs.ts, backend-envelope.ts)처럼
Object.hasOwn으로 자기 키만 본다. 표를 Object.create(null)로 바꾸는 대안은
타입 선언과 다른 표의 관용이 갈려 버렸다.

위험·한계
짝 백엔드는 대문자 code만 보내므로 짝 구성의 화면 결과는 바뀌지 않는다.

검증
- RED: 내장 이름 4개 행이 수정 전 실패, SOME_FUTURE_CODE 행은 통과.
- form-foundation.test.tsx 28건 통과. eslint, tsc(app) 통과.

Refs: docs/reviews/2026-11-03-maturity-review/08-presentation.md 08-03
2026-11-04 20:16:19 +09:00
DongHyeonka 0aada28b91 fix(bootstrap): 401을 그 요청의 자격 증명을 낸 쪽에만 알린다 (1103/09-01)
문제
조립 루트는 응답이 있는 UNAUTHENTICATED면 프로필을 보지 않고
authSession.onUnauthenticated()를 불렀다. ANONYMOUS 요청은 세션을 묻지 않고
헤더 없이 나가는데도, 그 401이 로그인한 사용자를 로그아웃시키고 scope fence가
서버 상태 캐시를 모두 비웠다. 제품 credentialProviders가 자격 증명을 낸
요청의 401도 템플릿 세션을 로그아웃시켰다.

고른 방법
attachCredentials와 같은 순서로 401의 주인을 가른다(reportServerUnauthenticated).
- ANONYMOUS 프로필: 아무에게도 알리지 않는다.
- 제품 provider 프로필: 세션은 그대로 두고, ProductComposition의 선택 hook
  onCredentialRejected({operationId, authProfileId})를 부른다. BFF 제품은
  거기서 자기 owner에게 알린다. hook의 throw는 결과를 바꾸지 않는다.
- 나머지(템플릿 세션이 낸 자격 증명): 지금처럼 onUnauthenticated().
버린 대안: ANONYMOUS만 빼기(2줄)는 provider 경로의 과잉 로그아웃이 남는다.
owner가 401을 직접 판단하게 하면 owner 계약이 바뀌고 모든 owner가 판단
로직을 쓴다.

위험·한계
- 제품 provider가 템플릿 세션과 같은 세션의 자격 증명을 내는 경우, 제품이
  hook을 쓰지 않으면 그 401은 세션을 바꾸지 않는다. 계약 주석과 매뉴얼 02
  5절에 적었다.
- 401 도착과 계정 전환이 겹치는 경쟁은 여전히 확인하지 않았다.

검증
- RED: 새 테스트 3건(ANONYMOUS 401 demo·external, provider 401)이 수정 전
  실패했다. bearer 대조군은 수정 전후 모두 통과.
- node scripts/run-vitest.ts run runtime-adapters-{auth-profile,credential-order},
  runtime-adapters, product-composition-fixture, reference-runtime-composition
  → 5 files / 62 tests 통과. check:types 통과. eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-01
2026-11-04 20:15:26 +09:00
DongHyeonka 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
2026-11-04 20:14:34 +09:00
DongHyeonka 004a205748 docs(review): 리뷰가 놓친 merge 게이트 결함 2건을 더한다
문제
리뷰 README 10.1절의 게이트 목록은 merge stage 전체가 아니었다.
coverage 증거 검사, storybook, a11y, browser-capabilities, CI env 값의
e2e가 빠졌다. 리뷰를 맡긴 세션이 병합의 한쪽 부모 8c39e77에서
`ci:gate FE-GATE-NNN` 14개를 돌려, 실제 러너에서 항상 실패하는 merge
게이트 두 개를 찾았다.

고른 방법
- 11-06: tests/e2e/compact-smoke.spec.ts:18이 build id를 "local-build"로
  고정하고, workflow는 VITE_BUILD_ID를 gitea-<run>-<attempt>로 준다.
  FE-GATE-008이 CI에서 항상 실패한다.
- 12-09: scripts/lib/ci-artifact-validator.ts:79-91의 .strict() schema가
  istanbul-lib-coverage 3.2.2 summary의 branchesTrue를 거절한다.
  FE-GATE-005가 테스트가 모두 통과해도 실패한다.
- 두 결함의 코드를 e40684b에서 다시 읽고, README 13절에 36.3 양식으로
  적었다. 사용 결정, P1 표, 개선 순서 2, 관점 21, 색인(90건), 미검증,
  오케스트레이터 실수(10.5)에 반영했다. 등급은 02-06과 같은 기준으로
  Medium·P1이다.
- 셋째 결함(FE-GATE-020)은 02-06과 같아 따로 세지 않았다.
  worktree 안 checkout·inotify 부족은 환경 조건이라 결함으로 세지
  않았다.

위험·한계
- e40684b에서 ci:gate를 실행하지 않았다. 재현은 8c39e77 깨끗한
  복제본에서 다른 세션이 했다. CI=true와 러너 이미지 조건은 아무도
  재현하지 않았다.
- 코드는 고치지 않았다.

검증
- verify:documentation PASS_SCOPED.
- documentation-readiness·changelog-review-ids 테스트 15건 통과.

Refs: docs/reviews/2026-11-03-maturity-review/README.md 13절
2026-11-04 00:31:18 +09:00
DongHyeonka 9c521ecd75 docs(review): 2026-11-03 프론트 전체 성숙도 리뷰를 기록한다
문제
V2 HTTP 경로를 지운 뒤(048f490, 12f3bb7) 사용자가 "V2에만 있던 동작이
없어져도 되는가"를 묻고, 프론트 전체를 다시 리뷰하라고 했다. 기준은
docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md다.

고른 방법
- 두 작업 브랜치를 합친 e40684b를 기준 커밋으로 고정했다(사용자 선택).
- 지난 리뷰의 16개 영역을 그대로 나눠, 격리 worktree 에이전트가 병렬로
  읽고 변이·실험을 했다. 무거운 실행은 공유 잠금으로 한 번에 하나씩
  돌렸다.
- High 제안 6건과 상향 제안 1건을 코드에서 다시 확인했다. 제거 드릴
  5개, feature-scaffold, lab 게이트는 직접 돌렸다.
- README에 범위(36.1), 28개 관점 판정(36.2), 최종 요약(36.5), 발견
  색인을 적었다. 영역 문서의 발견 96건 중 같은 결함 8건을 대표 항목에
  합쳐 색인은 88건이다.
- 버린 대안: 두 브랜치를 따로 리뷰하기. 병합 뒤 상태(문서 충돌을 푼
  6.1절, 두 쪽 변경이 겹친 번들 크기)를 보지 못한다.

위험·한계
- High는 3건이다: 03-01(=08-01), 01-01, 0929/03-03(Medium에서 상향).
  03-01은 이 작성자가 3261208에서 만든 판정 표가 원인이다. 14-02와
  04-01도 작성자의 문장·판정이 틀렸다(README 10.5).
- V2 판정을 다시 보니 V2가 하던 일이 셋보다 많았다. 레지스트리의 wire
  칸 감시(07-01), traceId 채우기(03-06), 테스트 3건(10-04), 조회
  SAFE·IDEMPOTENT 제한(03-03)이 같이 사라졌다(README 3절).
- 영역이 High로 제안한 02-06·12-01·15-01은 Medium·P1로 낮췄다.
  지난 라운드의 같은 모양(1101/11-01, 1101/15-01)과 등급을 맞췄다.
  P1이라 첫 조치 묶음에 그대로 있다(README 2.3).
- 짝 백엔드가 리뷰 도중 7ef8d0b4에서 bbe944bd로 바뀌었다. 새 code
  IDEMPOTENCY_COMPLETION_UNKNOWN 하나만 대조했다(README 10.6).
- CI 러너, 짝 백엔드 실연동, d99301b와의 lab A/B는 직접 확인하지
  않았다(README 7절).
- 리뷰 중 코드는 고치지 않았다.

검증
- e40684b 게이트: check:architecture, check:types, lint, test:unit
  2,580, test:component 263, test:integration 117, test:contract 23,
  test:runtime-schema 56, verify:documentation, check:adapter-inventory,
  check:ci, check:registries, check:i18n, check:design-system,
  check:diagnostics, check:bundle(201,848 / 204,800 B) 통과.
- test:sample-removal(23 checks), test:feature-scaffold(16 checks) 통과.
- test:browser-file-storage-removal, test:realtime-removal,
  test:optional-recipe-removal 실패. 세 드릴 모두 fixture에 README.md·
  CHANGELOG.md가 없어 문서 테스트 2파일만 떨어진다(02-06).
- test:performance 실패: 상호작용 중앙값 227 ms > 200 ms(15-01).
- 이 문서를 넣은 뒤 verify:documentation PASS_SCOPED,
  documentation-readiness·changelog-review-ids 테스트 15건 통과.

Refs: docs/reviews/2026-11-03-maturity-review/README.md
2026-11-04 00:18:59 +09:00
DongHyeonka 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절)에 적는다.
2026-11-03 22:49:20 +09:00
DongHyeonka 93c81dfc6f docs: 사라진 V2 동작 셋의 판정과 되살린 것을 기록한다
문제
14.7은 V2 삭제로 "401 뒤 세션 복구 재전송"과 "보낸 KEYED 요청 자동 재시도"가
사라졌다고만 적었다. 사용자가 없어져도 되는지 물었고, V2 보안 프로필 일관성
검사도 같이 사라졌다.

고른 방법
14.7에 세 동작의 판정 표를 적었다. 기준은 설계 정본(2026-07-30 closed deep
design) 8절이다.
- 401 재전송: 없어져도 된다(8.4 FRT-D016 hidden replay 금지). VD-23의 낡은
  문장은 리뷰 대상으로 남긴다.
- KEYED 자동 재시도: 정본 8.3이 허용하는 부분(재시도를 허락하는 알려진 응답)만
  되살렸다(c05f41a).
- 보안 프로필 검사: 쿠키 인증 쓰기의 CSRF 요구만 보안 불변식이라 되살렸다
  (365d8c3).
CHANGELOG에 [보안] 행과 [계약] 행을 더했다.

검증
- verify:documentation PASS_SCOPED, tests/unit/changelog-review-ids.test.ts 통과.

Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.7
2026-11-03 22:22:48 +09:00
DongHyeonka 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
2026-11-03 22:22:35 +09:00
DongHyeonka 365d8c3c02 fix(contracts): 쿠키 인증 쓰기는 CSRF 헤더를 요구하는 프로필만 조립한다
문제
브라우저는 쿠키를 어느 사이트의 요청에든 붙이므로, 쿠키로 인증하는 쓰기
요청은 페이지만 넣을 수 있는 헤더(CSRF 토큰)가 있어야 서버가 진짜 요청을
가른다. V2 클라이언트는 resolveRestSecurityProfiles로 "쿠키 프로필 + GET·HEAD
밖 method면 HEADER CSRF 프로필"을 강제했다. 048f490·12f3bb7이 V2를 지운 뒤
V3에는 이 검사가 없다. V3 프로필 설치 규칙은 SAME_ORIGIN_COOKIE에 쿠키
전송과 bearer 금지만 요구한다. 그래서 제품이 CSRF 헤더 없는 쿠키 프로필을
POST에 붙여도 조립이 통과한다.

고른 방법
assertHttpContract가 operation의 auth profile을 설치된 레지스트리에서 찾아,
쓰기(GET·HEAD 밖)인데 SAME_ORIGIN_COOKIE이고 requiredCredentialHeaders에
x-csrf-token·x-xsrf-token이 없으면 operation·method·프로필 이름을 담아
거절한다. 읽기 쿠키 프로필은 CSRF 없이 그대로 된다(tech-log·memento 예시와
같다).

버린 대안
- 프로필 설치 때 모든 쿠키 프로필에 CSRF 요구: 읽기 전용 쿠키 프로필
  (MEMENTO_BFF_READ 등)까지 막는다. method는 operation에만 있다.
- 요청 때(attachCredentials) 검사: 조립 때 잡을 수 있는 설정 실수를 사용자
  요청 시점까지 미룬다.

위험·한계
- 이미 CSRF 없는 쿠키 쓰기 프로필을 쓰는 제품은 조립이 실패한다. 의도한
  실패다(CHANGELOG [보안]).
- 헤더 값이 올바른 CSRF 토큰인지는 서버만 안다. 프론트는 헤더가 반드시
  실리는지만 보장한다(requiredCredentialHeaders가 없으면 fetch 0회).

검증
- RED: tests/unit/rest-profile-contract.test.ts "refuses a write whose cookie
  profile requires no CSRF header" 실패(조립이 통과).
- GREEN: 같은 파일 7건 통과. CSRF를 요구하는 쓰기와 CSRF 없는 쿠키 읽기는
  조립된다.
- check:types, lint, check:architecture, check:registries, test:unit 2,568,
  test:integration 117, test:component 245 통과.

Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.7
2026-11-03 22:22:35 +09:00
DongHyeonka dcadc0be92 docs: V2 HTTP 경로 삭제를 CHANGELOG와 리뷰 기록에 적는다
문제
048f490(V2 클라이언트 삭제)과 12f3bb7(V2 API 행 삭제)은 공개 이름을 깨는
변경인데 CHANGELOG 미출시 절에 행이 없고, "먼저 할 일" 절의 기능 모양 옮기기
순서가 아직 apiContract(V2 API 필드 네 개)를 만들라고 적는다. 리뷰 README
14.6의 "V2와 남은 차이"도 V2가 있는 것으로 적는다.

고른 방법
- CHANGELOG: [계약] BREAKING 행 둘(지운 이름, 옮기는 법, memento-web 영향)을
  더하고, "먼저 할 일" 1·3번을 schemas 하나로 고쳤다.
- 리뷰 README 14.7: 사용자 지시, 지우기 전·후 도식, 두 커밋이 지운 것과 바꾼
  것, 레지스트리 재승인 digest, 초기 JS 변화, 사라진 V2 전용 동작, 남긴
  BoundedPollOperationContract, 다운스트림 영향. 14.6의 차이 절에 지금은 없다고
  적었다.

위험·한계
- 다운스트림 동기화 방법은 CHANGELOG의 문장뿐이다. memento-web을 직접 옮겨
  보지는 않았다.

검증
- verify:documentation PASS_SCOPED.
- tests/unit/changelog-review-ids.test.ts 통과.

Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.7
2026-11-03 21:38:04 +09:00
DongHyeonka 12f3bb7862 refactor(contracts)!: V2 API 행을 지우고 FE-REG-API를 HTTP descriptor에서 뽑는다
문제
기능 하나가 같은 HTTP API를 두 번 적는다. *-api-contract.ts의 V2 행
(defineRestOperation)은 check:registries(FE-REG-API)가 검사하는 선언이고,
contract contribution의 V3 descriptor가 실제로 실행된다. 둘이 어긋나지 않게
http-operation-v2-v3-parity 테스트를 따로 둔다. 048f490으로 V2 클라이언트가
없어져 V2 행을 읽는 실행 코드는 없고, 검사만 남은 두 번째 사본이다. V2 행을
위한 기능별 runtimeSchemas·mappers 레지스트리와 V2 보안 프로필 해석
(resolveRestSecurityProfiles)도 같이 남아 있다. 사용자 지시: 최신 경로 하나만
남기고, 레지스트리 기준선 재승인을 승인했다.

고른 방법
- src/contracts/api-operations.ts를 projectApiOperationRows 하나로 바꿨다.
  조립된 contribution의 descriptor마다 operationId, featureId, method, path,
  authProfileId, retrySemantics, requestBody, responseBody, responseEnvelope,
  request/response/problemSchema(검증기 schemaId) 행을 만든다. FE-REG-API는
  같은 export(API_OPERATIONS)를 읽고, governance 정의를 이 필드로 바꿨다.
  requestSchema·responseSchema는 그대로 FE-REG-SCHEMA를 참조한다.
- FeatureRuntime은 apiContract 대신 schemas(FE-REG-SCHEMA 행)만 받는다.
  installed-feature-runtime-registries는 schemas로 스키마 레지스트리를 만들고
  FE-REG-API 행을 descriptor에서 뽑는다. RUNTIME_SCHEMA_CODECS, MAPPER_REGISTRY,
  REST_PROFILE_BINDINGS_VALID, API_RUNTIME_BINDINGS_VALID를 지웠다.
- realtime snapshot 바인딩은 ApiOperationRow를 받고 method GET과
  retrySemantics SAFE·IDEMPOTENT를 본다(V2의 contractVersion·semantics·
  replayPolicy 대신).
- rest-profiles.ts에서 V2 행용 provider·CSRF 프로필 해석을 지웠다. V3는 조립
  때 auth profile을 검사하고 자격증명 헤더를 프로필로 거른다.
- 참조 기능: reference-api-contract.ts를 reference-schema-metadata.ts로
  바꾸고(스키마 행만), V2 runtime codec·operation mapper·레지스트리 mapper를
  지웠다. V3 descriptor가 쓰지 않는 NoRequest 스키마 행도 지웠다.
- create:feature: <base>-api-contract.ts 대신 <base>-schema-metadata.ts를
  만든다. codec·mapper 레지스트리 행과 그 테스트를 만들지 않는다.
- 레지스트리 기준선을 update:registry-baseline으로 다시 만들고 승인했다
  (digest 16f72742…, 승인자 DongHyeonka, 이유에 사용자 승인을 적음).
- 매뉴얼 01·02·reference, starter-experience, 계약 문서의 V2 설명을 지웠다.

버린 대안
- V2 행을 남기고 V3에서 생성하기: 생성 단계와 생성물이 하나 더 생긴다. 행은
  실행되지 않으므로 메모리에서 뽑아 검사하면 충분하다.
- 스키마 메타데이터(FE-REG-SCHEMA 행)도 검증기에서 뽑기: boundary·
  unknownFieldPolicy·owner는 검증기에 없고, 라우트 스키마도 같은 레지스트리를
  쓴다. 이 행은 V2가 아니라 스키마 레지스트리라 남겼다.

위험·한계
- BREAKING: FeatureRuntime 모양, contracts·rest-profiles·loaded-feature-runtimes
  의 이름이 바뀌거나 없어졌다. memento-frontend의 memento-web이 V2 행을 쓴다.
  옮기는 법은 CHANGELOG에 적는다.
- V2 보안 프로필 일관성 검사(auth "none"과 ANONYMOUS, 쿠키 프로필의 CSRF
  모드)가 사라졌다. V3 descriptor에는 그 칸이 없다.
- BoundedPollOperationContract(realtime polling recipe)는 contractVersion: 2
  필드를 갖지만 자체 계약이라 바꾸지 않았다.

검증
- check:types, lint, check:architecture, check:registries(11 registries PASS,
  compatibility=none), check:ci, check:diagnostics, check:adapter-inventory,
  verify:documentation 통과.
- test:unit 2,566(새 tests/unit/api-operation-rows.test.ts 3건 포함),
  test:integration 114, test:component 245, test:contract 23,
  test:runtime-schema 56, tests/features 99 통과.
- tests/unit/second-api-feature-registries.test.ts: V3 descriptor만 가진 두
  번째 기능을 복사본에 넣으면 기준선을 고치지 않고 check:registries가 통과한다.
- check:bundle 통과. 초기 JS 201,598 → 200,911 B.
- test:feature-scaffold 16개, test:sample-removal 23개 검사 통과.

BREAKING CHANGE: FeatureRuntime이 apiContract 대신 schemas를 받는다.
defineRestOperation, ApiOperation, RestOperationV2, composeApiOperations,
validateApiRuntimeBindings, getApiOperation, contracts의 API_OPERATIONS,
createRestProviderProfile, RestProviderProfile, resolveRestSecurityProfiles,
validateRestProfileBindings, REST_CSRF_PROFILES, RestCsrfProfile,
loaded-feature-runtimes의 RUNTIME_SCHEMA_CODECS, MAPPER_REGISTRY,
REST_PROFILE_BINDINGS_VALID, API_RUNTIME_BINDINGS_VALID가 없어졌다. 기능은
operation을 contract contribution에만 적고, schemas 행을 feature-runtime에
넘긴다.
2026-11-03 21:37:48 +09:00
DongHyeonka 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으로 실행한다.
2026-11-03 21:12:34 +09:00
DongHyeonka bf86fe5cd0 docs(contract): 4.2절의 400·422 행을 짝 백엔드 거절 표에 맞춘다
문제
계약 문서 4.2절은 422를 "field validation"으로 적는다. 3261208 뒤로 프론트는
422 중 IDEMPOTENT_REQUEST_MISMATCH만 적용 안 됨으로 보고, 짝 백엔드는 필드
검증을 400 VALIDATION_FAILED로 보낸다. 같은 문서의 6.1절 표와 4.2절이 서로
다른 말을 한다.

고른 방법
- 400 행에 짝 백엔드 필드 검증이 400 VALIDATION_FAILED라는 것을 더하고
  적용 여부는 6.1절을 가리킨다.
- 422 행을 짝 백엔드 기준으로 바꿨다. 기본 배포는 IDEMPOTENT_REQUEST_MISMATCH만,
  fileserver는 쓰기 뒤에도 나오는 code를 422로 보낸다. 폼 필드 오류는
  details.issues[]가 있으면 여전히 읽는다.
- 리뷰 README 14.6의 위험 줄을 고친 상태로 바꿨다.

버린 대안
- 422 행을 그대로 두고 6.1절만 믿기: 같은 문서 안에서 두 절이 어긋난다.

위험·한계
- 422로 필드 검증을 보내는 다른 백엔드를 쓰는 프로젝트는 422 뒤에 폼에서
  다시 저장할 수 없다. 문서는 그 동작을 적을 뿐 바꾸지 않는다.

검증
- verify:documentation PASS_SCOPED.

Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.6
2026-11-03 20:55:50 +09:00