Commit Graph
682 Commits
Author SHA1 Message Date
DongHyeonka 00076992f7 fix(recipes): 쿠키 세션 모드의 서버 401을 템플릿 세션에 잇는다
문제: 짝 백엔드 Redis session 모드를 쿠키 recipe와 매뉴얼 04 4.3대로
이으면 서버 401이 세션에 닿지 않는다. 1103/09-01 수정 뒤 조립 루트는
제품 provider 프로필의 401을 제품의 선택 hook `onCredentialRejected`에만
알린다. 쿠키 모드의 operation은 모두 제품 프로필(SESSION_COOKIE_*)인데
매뉴얼 예시는 그 hook을 잇지 않았고, recipe와 매뉴얼은 "서버 401 →
unauthenticated"라고 적었다. 이으려 해도 ProductCompositionContext에
세션에 알릴 길이 없었다. 리뷰 09-cookie401에서 세션 만료 뒤에도 상태가
authenticated, 이전 scope가 current로 남았다.

고른 방법: 두 가지를 더했다.
- ProductCompositionContext.notifySessionUnauthenticated(): 템플릿 세션의
  자기 401과 같은 판정(authSession.onUnauthenticated)을 제품이 부를 수
  있게 한다(리뷰 안 C).
- recipe의 createSessionCookieRejectionHandler(context): SESSION_COOKIE_*
  프로필의 401만 세션에 넘긴다. 다른 제품 프로필의 401은 넘기지 않으므로
  1103/09-01의 완료 기준(세션과 무관한 provider의 401은 로그아웃시키지
  않는다)은 그대로다.
매뉴얼 04 4.3 예시에 `onCredentialRejected` 한 줄을 넣고, recipe 주석,
매뉴얼 04 흐름도, 매뉴얼 02 5절과 7절 업로드 예시(BACKEND_SESSION 쿠키
세션)를 맞췄다. 버린 대안: recipe가 owner와 provider를 한 번에 만드는
함수(안 B). owner는 composeProductSessionOwner, provider는 composeProduct
에서 따로 만들어져 모듈 변수가 필요하다. provider 선언에 "세션 자격
증명" 표시를 두는 안(D)은 계약 칸이 늘고 판정이 선언과 hook 둘로 갈린다.

위험·한계: 제품이 이 한 줄을 빼면 여전히 세션 만료를 모른다. 이것을
막는 검사는 없다(매뉴얼과 recipe 주석이 적는다). 이미 recipe를 복사한
다운스트림은 handler를 복사본에 옮기고 composeProduct에 한 줄을 더해야
한다. ProductCompositionContext에 칸이 하나 늘었다. 이 context는 템플릿만
만들므로 제품 코드는 깨지지 않는다. 실제 Redis 백엔드에는 붙이지
않았다(1103/09-03 남은 부분).

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/recipes/session-owners-runtime.test.ts tests/recipes/cookie-session-owner.test.ts
조립 루트를 지나는 테스트가 매뉴얼 4.3 연결로 쿠키 읽기·쓰기 401 뒤
세션 unauthenticated, 이전 scope not current를 본다.

Refs: 1105/09-02
2026-11-05 22:26:27 +09:00
DongHyeonka 56c0bd053d test(cache-storage): 손상 code 목록의 경계를 code마다 한 행으로 고정한다
문제: 2026-11-03 02-02가 만든 손상 code 목록(`REPAIRABLE_READ_CODES`,
`INTEGRITY_FAILED`·`CORRUPT_DATA`·`POLICY_REJECTED`·`LIMIT_EXCEEDED`)의
경계를 테스트가 고정하지 않는다. 리뷰 배치 02-R1에서 목록에서 하나를
빼거나 `NOT_READABLE`을 더한 변이 5개가 cache 테스트 59건을 모두
통과했다. 지금 테스트는 `TypeError` 하나로 본문 실패를 만들고, stage
재사용 경로의 repair 테스트는 entry가 없는 경우만 본다.

고른 방법: 1105/02-02 묶음에 표 테스트 하나를 둔다. 행은 목록의 code
넷(바이트 변경, 정책 밖 헤더 `cache-control: no-store`, 상한을 넘는
`content-length`, `DataError` 본문)과 목록 밖 본문 실패 둘(`TypeError`,
`NotReadableError`)이다. 행마다 activate가 돌려주는 code와 recovery
(`REHYDRATE`), 다음 stage가 모든 asset을 다시 받는지(fetch 2), 그 뒤
activate 성공을 본다. 손상 넷은 activate에서 `INTEGRITY_FAILED`이고
본문 실패는 원래 code(`UNAVAILABLE`·`NOT_READABLE`)다. 그래서 목록에서
`CORRUPT_DATA`·`POLICY_REJECTED`·`LIMIT_EXCEEDED`를 빼거나 `NOT_READABLE`을
더하면 그 행의 activate code가 바뀌어 실패한다.

위험·한계: 1105/02-02 뒤 stage는 손상과 본문 읽기 실패를 모두 다시 쓴다.
그래서 목록에서 `INTEGRITY_FAILED`를 빼는 변이(F0202-int)는 이제 동등
변이다. 그 code는 목록 밖으로 가도 activate가 같은 `INTEGRITY_FAILED`/
`REHYDRATE`를 돌려주고 stage도 똑같이 다시 쓴다. 리뷰가 걱정한 "바이트가
바뀐 후보를 다시 stage로 고치지 못한다"는 1105/02-02로 막혔고, 그 동작은
이 표의 첫 행이 지킨다. 동작 코드는 바뀌지 않는다(테스트만).

검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/public-response-cache-repair.test.ts
- 변이: `public-response-cache-adapter.ts`의 `REPAIRABLE_READ_CODES`에서
  `CORRUPT_DATA`·`POLICY_REJECTED`·`LIMIT_EXCEEDED`를 하나씩 빼고,
  `NOT_READABLE`을 더해 각각 표의 해당 행이 실패하는지 본다.

Refs: 1105/02-04
2026-11-05 22:24:03 +09:00
DongHyeonka 8e9fb1fde6 fix(cache-storage): 다시 stage하면 계속 읽히지 않는 캐시 본문을 다시 쓴다
문제: 2026-11-03 02-02 수정 뒤 저장된 본문을 읽지 못하면(`UNAVAILABLE`·
`NOT_READABLE`) 손상이 아니라 "모름"이다. stage 재사용 경로는 "모름"이면
실패를 돌려주고 다시 받지 않는다. 그래서 다시 쓰기 전까지 계속 읽히지 않는
entry(blob 손실 등)는 다시 stage해도 고쳐지지 않는다(리뷰 실험 E-1).
- 새 후보: activate가 `RETRY`를 안내하는데 다시 해도 같다. cleanup으로
  후보를 지운 뒤에야 풀린다.
- rollback 대상: cleanup도 지우지 않아 되돌릴 길이 없다.
- 서비스 중 release: 그 asset 조회가 계속 `UNAVAILABLE`이다.
수정 전 판정에서는 같은 상태가 다시 stage 한 번으로 풀렸다.

고른 방법(리뷰 대안 (나)):
- 판정에 `UNREADABLE`(entry는 있는데 본문 읽기가 실패)을 따로 둔다.
  `UNKNOWN`은 중단(`ABORTED`)과 `cache.match` 자체의 실패만 뜻한다.
- stage 재사용 경로는 `REPAIRABLE`처럼 `UNREADABLE`도 모든 asset을 다시
  받아 같은 cache에 덮어쓴다. 덮어쓰는 것은 digest로 검증한 같은
  바이트이고 cache를 지우지 않으므로 서비스 중인 release를 해치지 않는다
  (STO-RR-04가 막는 것은 삭제다).
- activation은 지금처럼 본문 읽기 실패를 손상으로 보고하지 않고 code를
  그대로 둔다. recovery만 `REHYDRATE`(같은 manifest로 다시 stage)로 바꾼다.
- 조회는 그대로 `UNAVAILABLE`/`RETRY`다.
- `cache.match`가 던지는 경우는 리뷰가 제안한 "중단 제외 UNKNOWN 전부"에서
  뺐다. Cache Storage 자체가 응답하지 않을 때 모든 asset을 다시 받는 것은
  고치는 것이 없고, 2026-11-01 02-03 테스트가 그 경우의 실패 보고를 고정한다.

버린 대안:
- (가) 문서에 "cleanup 뒤 다시 stage"만 적기: rollback 대상은 못 고친다.
- (다) 실패한 entry만 다시 받기: 비용은 가장 작지만 stage 경로를 entry
  단위로 나눠야 한다.

위험·한계:
- 일시적인 본문 읽기 오류에도 다시 stage하면 모든 asset을 다시 받는다
  (수정 전과 같은 비용).
- 실제 브라우저에서 본문 읽기 실패가 지속되는지, 어떤 오류 이름으로
  오는지는 확인하지 못했다. 테스트는 메모리 fake에 오류를 주입한다.
- service-worker-pwa 번들 여유가 342 B다(FE-GATE-012). 늘어난 코드는
  분기 둘이다.

검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/public-response-cache-repair.test.ts
  tests/unit/public-response-cache.test.ts tests/unit/public-response-cache-codec.test.ts
  tests/recipes/browser-file-storage-contracts.test.ts
- corepack pnpm check:optional-recipes (번들 예산)

Refs: 1105/02-02
2026-11-05 22:22:17 +09:00
DongHyeonka fdc1db9471 feat(bootstrap): 제품이 SW blockers·observe를 composeProduct로 넘긴다
문제: SW를 켜는 선택은 제품 소유 `product-capabilities.ts`로 옮겼다
(1103/09-05 일부). 그런데 저장하지 않은 편집이 있는 탭의 활성화 거절
(`blockers`)과 page controller 관측(`observe`)은 템플릿 소유
`src/bootstrap/create-runtime-composition.ts`를 고쳐야 이어진다(매뉴얼 03
"SW 켜기", 레시피 "Service Worker를 켤 때 확인할 것" 2·3). 그 파일을 고친
제품은 템플릿 동기화마다 충돌한다.

고른 방법: 기존 제품 확장 지점에 선택 칸 하나를 더한다.
`ProductComposition.serviceWorker?: { blockers?, observe? }`
(`product-composition-contract.ts`). `createRuntimeAdapters`가 `composeProduct`
결과의 이 칸을 bundle에 `productServiceWorker`로 싣고, 템플릿 조립
(`create-runtime-composition.ts`)이 telemetry와 같은 방식으로 받아
`createOptionalRuntimeHost`에 넘긴다. blockers 목록은 한 번 복사한다. 던지는
blocker는 page controller가 이미 막는 쪽으로 본다. page controller는
`observe`의 throw를 잡지 않으므로, 제품 sink가 던져도 worker 흐름이 바뀌지
않게 조립에서 감쌌다. 매뉴얼 03과 레시피 2·3을 새 자리로 고쳤다.
버린 대안:
- `product-composition.ts`에 새 export(`composeProductServiceWorker`)를 요구.
  이미 그 파일을 가진 다운스트림이 동기화하면 import가 깨진다. 선택 칸은
  기존 `composeProduct`를 그대로 둔다.
- `composeProduct`를 조립에서 한 번 더 부르기. capability와 credential이 두
  벌 생긴다.

위험·한계: 일부만 닫는다. 남은 것:
- 활성화 화면(`onUpdateWaiting`·`requestActivation()`)과 reload 안내를 이을
  제품 소유 자리가 없다(레시피 4·5, 0925/06-05).
- realtime·Web Worker·오프라인 명령은 여전히 조립이 거절한다
  (`optional-runtime-host.ts`, 그 런타임이 템플릿에 없다).
`product-composition.ts`(제품 소유, 출하 상태 빈 값)는 고치지 않았다. 칸이
선택이라 기존 제품 파일과 1105/09-01의 타입 검사 탐침 내용이 그대로
통과한다.

검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/component/runtime-composition-service-worker-product-wiring.test.ts tests/component/runtime-composition-service-worker-telemetry.test.ts
- RED: "passes the product's blockers and observer to the page controller"가
  옛 조립에서 observe 기록이 비어 실패한다.
- 함께: check:types, lint, check:architecture, verify:documentation

Refs: 1103/09-05
2026-11-05 22:19:06 +09:00
DongHyeonka daf3474252 fix(contracts): 짝 백엔드 답 표를 pin한 백엔드 표의 사본과 대조한다
문제: 짝 백엔드 답 표 JSON(backend-idempotency-answers.json)이 pin한
백엔드 http-contract.md와 같은지 아무 검사도 보지 않는다.
backend-contract-pin.test.ts는 pin과 답 표 두 파일만 읽고, drift
스크립트는 pin과 HEAD 사이에 문서 글자가 바뀌었는지만 본다. 그래서
답 표 status 오타나 옮기지 않은 행(§4 RATE_LIMIT_*)은 어디서도 걸리지
않는다. drift 스크립트는 옆 checkout이 없으면 "skipped"로 rc=0이고
(worktree에서 늘 그렇다), 매뉴얼에는 스크립트가 없다.

고른 방법: 게이트가 백엔드 checkout 없이 볼 수 있게, 백엔드 §2·§4 표의
`|` 줄을 pin 커밋 그대로 config/contracts/backend-http-contract-excerpt.json
에 옮겼다. 읽는 함수는 scripts/lib/backend-contract-excerpt.ts 하나다.
- test:unit(backend-contract-pin.test.ts): 답 표의 행마다 사본의 같은 절에
  같은 code·status 행이 있는지, 사본의 행마다 답 표에 있거나 pin의
  `notCopied`에 이유와 함께 있는지 본다. `notCopied`에는 RATE_LIMIT_* 둘을
  적었다(리뷰가 지적한 sectionsCompared §4의 실제 범위).
- check:backend-contract-drift(게이트 밖): pin 커밋의 문서에서 같은 표를
  읽어 사본과 글자 단위로 비교하고, 답 표도 그 표와 비교하고, pin 뒤
  HEAD에서 바뀐 사본 표 행을 찍는다. checkout이 없거나 pin 커밋·문서가
  없으면 rc=2("not compared")로 끝난다. 기본 경로는 main checkout 옆이라
  linked worktree에서도 같은 백엔드를 찾는다. `--write-excerpt`는 pin을
  올릴 때 사본을 pin 커밋에서 다시 옮긴다.
- 매뉴얼 01 Envelope 단계와 계약 문서 4.1에 언제 무엇을 돌리는지 적었다.
버린 대안: 백엔드 문서의 digest만 pin에 두는 것. 게이트는 digest로 답
표를 확인할 수 없다. 계약 패키지(리뷰 안 D)는 배포 경로가 아직 없다.

위험·한계: 사본과 백엔드 문서의 일치는 여전히 백엔드 checkout이 있을
때만 drift 스크립트가 본다. 게이트는 답 표와 사본의 일치만 본다. 사본을
손으로 같이 고치면 게이트는 통과한다(drift 스크립트가 잡는다). 답 표의
refusedBeforeWrite·sameKeyResend는 백엔드 문장(클라이언트 행동)을 사람이
읽은 값이라 기계로 대조하지 않는다. 그 문장이 바뀌면 사본 diff와 drift
출력에 보인다. 백엔드 표 형식(머리글 `error.code`·`코드`·`status`)이
바뀌면 파서도 고친다. pin의 comparedOn을 사본을 옮긴 날로 올렸다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/backend-contract-pin.test.ts tests/unit/backend-contract-drift.test.ts
drift 테스트는 가짜 백엔드 git repo로 D6g(pin 뒤 status 변경), 답 표
status 오타, 사본 오타, 옮기지도 적지도 않은 행, checkout 없음,
--write-excerpt를 돈다.

Refs: 1105/07-01
2026-11-05 22:17:57 +09:00
DongHyeonka d31c7d6b18 fix(recipes): 세션 파일 레시피가 매뉴얼과 같은 capability 타입 위치를 가리킨다
문제: 세션 레시피 주석이 "`FeaturePlatformCapabilities`를
`files: SessionBrowserFiles`로 보강한다"고 적는다. 매뉴얼
(`docs/manual/03-outside-feature-folder.md`)은 그 타입을
`src/features/product-capabilities.ts`의
`ProductFeaturePlatformCapabilities`에 적으라고 하고, `declare module`
보강은 `check:types:node`가 키를 보지 못한다고 막는다. 주석대로 하면 앱
typecheck는 통과하고 node typecheck에서 키를 잃는다. 또 레시피 테스트는
`capabilities: {}`로 조립하고 `files.current()`를 레시피 객체에서 직접
불러서, capability가 기능 쪽으로 넘어가는 절반이 깨져도 통과한다.

고른 방법:
- 주석이 `ProductFeaturePlatformCapabilities`에 적는 예와 매뉴얼 경로를
  보이고, `declare module` 보강은 쓰지 말라고 적는다.
- 레시피 테스트가 `capabilities: { files }`를 돌려주고, 템플릿이 설치된
  기능의 loader에 넘기는 capability 객체(`createInstalledFeatureLoaders`의
  첫 인자)를 기록한다. 테스트의 모든 파일 동작(선택, 읽기, download,
  계정 전환 뒤 새 runtime)을 그 객체의 `files.current()`로 돈다. 같은
  mock 방식은 `tests/recipes/session-owners-runtime.test.ts`가 이미 쓴다.

버린 대안: `files`를 `needs`에 적은 가짜 기능을 생성 index에 끼워 넣기.
`ProductFeaturePlatformCapabilities`가 비어 있는 템플릿에서는 타입을
우회해야 하고, `needs`로 고르는 부분은 1103/09-08 테스트가 이미 잡는다.

위험·한계: 검사는 loader가 받는 capability 객체까지다. 기능 factory가
`needs`로 골라 받는 마지막 단계는 기존 테스트에 맡긴다. 동작 코드는
바뀌지 않는다(주석과 테스트만).

검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/recipes/browser-file-session-capability.test.ts
- 변이: 테스트 mock의 `capabilities`에서 `files`를 빼거나,
  `src/bootstrap/runtime-adapters.ts`의 `...product.capabilities`를 지우면
  "Features did not receive the files capability"로 실패해야 한다.

Refs: 1105/02-03
2026-11-05 22:16:46 +09:00
DongHyeonka 0776718c98 chore(review): 1105 CI 사전 점검·release 로그 조치 브랜치를 합친다 2026-11-05 22:15:19 +09:00
DongHyeonka f738348d9d fix(bootstrap): 실패한 scope closer를 label과 함께 진단에 남긴다
문제: 1103/02-01이 제품 closer를 scope reset에 넣었다. template
participant 하나가 제품 closer를 차례로 부르고, 하나라도 던지면 이유 없는
Error를 던진다. scope runtime은 그 실패를 `failed = true`로만 받아 scope를
`FAILED`에 둔다. 그동안 모든 서버 요청이 `SCOPE_FENCED`로 막히는데 진단
기록은 0건이다(리뷰 실험 E-3). 계약의 `ProductScopeParticipant.label`을
읽는 코드도 없다. 개발자는 "로그아웃 뒤 앱이 요청을 안 보낸다"만 보고 원인
closer를 찾으려면 closer를 하나씩 지워 봐야 한다.

고른 방법(리뷰 대안 (다)):
- scope runtime이 reset의 실패 단계마다 `cache.operation.failed`를 하나
  남긴다. `operation: "SCOPE_RESET"`, `reason`은 `PARTICIPANT_FAILED`·
  `CACHE_RESET_FAILED`·`GENERATION_ACTIVATION_FAILED`(+ 목록 함수가 던질
  때 `PARTICIPANTS_UNREADABLE`), `error_kind`, participant 실패면
  `scope_participant: <label>`. template participant 실패도 같은 길로
  남는다.
- 진단 계약에 `scope_participant` 키를 더한다(cardinality `topology`,
  값 정책 `isScopeParticipantLabel` = 소문자 kebab-case 48자 이하). label은
  제품 코드가 고른 문자열이라 projection이 받는 닫힌 토큰으로 제한했다.
- 제품 closer를 wrapper 하나로 감싸지 않고 각자 order 10 participant로
  넘긴다. 그래서 `participants`가 reset마다 읽는 함수도 받는다
  (`ServerStateScopeDependencies`, 배열은 그대로 받는다). 순서와 "하나가
  실패해도 나머지를 부른다"는 그대로다.
- 조립은 형식에 맞지 않는 제품 label을 `TypeError`로 거절한다. 부팅에서
  바로 드러나야 진단에서 label이 빠지는 일이 없다.

버린 대안:
- (가) 문서에 "closer는 던지지 않게 쓴다"만 적기: 결함이 그대로다.
- (나) wrapper만 제품 label을 기록: template participant 실패는 계속
  조용하고, 한 실패가 wrapper와 runtime에서 두 번 기록된다.
- label을 `operation`이나 `reason` 값에 섞기: 계약 변경은 없지만 그 키의
  뜻이 흐려진다.

위험·한계:
- 진단 계약(`src/contracts/diagnostics.ts`)에 키 하나, 함수 하나가 더해진다.
  더하기만 해서 호환은 깨지지 않는다. CHANGELOG [계약] 행이 필요하다.
- 제품 label 형식이 좁아졌다. `Browser Files` 같은 label을 쓰던 제품은
  부팅에서 `TypeError`가 난다. 저장소 안의 label(`browser-files`, 테스트의
  label)은 모두 맞는다.
- 화면이 `FAILED`를 어떻게 보이는지는 바꾸지 않았다(영역 08·09).

검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/server-state-scope-runtime.test.ts
  tests/unit/runtime-adapters-product-scope-participants.test.ts
  tests/unit/observability-cardinality.test.ts tests/unit/diagnostics.test.ts
- corepack pnpm check:diagnostics
- node scripts/run-vitest.ts run tests/recipes/browser-file-session-capability.test.ts

Refs: 1105/02-01
2026-11-05 22:14:54 +09:00
DongHyeonka f2f7dc4cdb test(http): Fileserver client의 5xx·deadline·읽기 전 크기 거절 규칙을 고정한다
문제: Fileserver client 규칙 셋을 바꿔도 통합 테스트 48건이 모두
통과했다(리뷰 변이 FS4·FS5·FS8 생존).
- FS4: 5xx ATOMIC_PUBLISH_UNSUPPORTED를 NOT_APPLIED에서 빼도 표에 그 행이
  없다.
- FS5: deadline에서 바이트 비례 몫을 없애도 시간 초과 테스트는 작은 고정값만
  본다. 큰 파일이 느린 망에서 기본 30초에 끊기는 회귀를 못 잡는다.
- FS8: 선언 크기가 maxFileBytes보다 큰 파일을 읽기 전에 거절하지 않아도, 읽는
  중 상한 검사가 같은 code를 내서 통과한다. 그 사이 선언 크기만큼 버퍼를 먼저
  잡는다.

고른 방법(리뷰 01-04 최소 개선 방향):
- Envelope 실패 표에 503 ATOMIC_PUBLISH_UNSUPPORTED → NOT_APPLIED 행을
  더한다. 504 TRANSFER_TIMEOUT 행은 01-02 커밋이 MAYBE_APPLIED로 더했다. 두
  방향(빼기·되넣기)이 모두 실패를 만든다.
- 가짜 setTimeout과 주입한 fetcher·monotonicNow로, 기본 1초에 바이트당 1초를
  더한 deadline 안에서 1.5초 뒤 온 답이 성공하는지, 자격 증명 owner가 받은
  deadline이 1,000 + 바이트 수 × 1,000 ms인지 본다. 실제 시간에 기대지 않아
  부하에 흔들리지 않는다.
- 선언 크기 초과에서 stream()이 한 번도 불리지 않음을 본다.
버린 대안: MSW에 지연을 넣고 실제 시간으로 deadline을 재는 방법. 부하가 큰
desktop에서 흔들릴 수 있고, 시간 여유를 키우면 테스트가 느려진다.

위험·한계: 테스트만 더했다. 지금 코드는 의도대로라서 부모 src에서도
통과한다. 검출력은 변이로만 확인할 수 있다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts
RED 없음(테스트 추가). 변이 셋이 각각 실패를 만들어야 한다:
FS4' NOT_APPLIED_5XX_CODES에서 "ATOMIC_PUBLISH_UNSUPPORTED" 줄 삭제,
FS5 timeoutMs 식의 Math.ceil(...) 몫을 0으로,
FS8 readMultipartBody의 declared > maxFileBytes 거절 블록 삭제.

Refs: 1105/01-04
2026-11-05 22:13:54 +09:00
DongHyeonka aaa782bab4 test(service-worker): 옛 탭이 지워진 route를 reload 없이 여는지 본다
문제: update spec은 옛 탭 회복을 페이지의 `fetch(removedChunk)`로만
본다. 바이트가 오는지는 알지만, B가 제어하는 A 탭에서 지워진 route를
여는 실제 경로는 아무 spec도 지나지 않는다. 워커 제어 아래 preload는
11-09 허용(`preloadunverifiable:service-worker:`) 때문에 fixture가 하나도
판정하지 못한다(리뷰 06-R9: 158줄 모두 ALLOWED). 워커가 직전 캐시로
답하지 않게 바꾼 변이(06-R10)에서 화면 단언은 통과했다. chunk 복구가
페이지를 B로 reload해 같은 not-found 화면을 그렸기 때문이다.

고른 방법: 리뷰 06-03의 (a). update spec에 test 하나를 더한다. B가
제어하는 A 탭에서 client navigation(pushState + popstate)으로 일치하지
않는 경로를 연다. `CHANGED_ROUTE_SOURCE`가 not-found 페이지라 그 경로가
지워진 chunk를 import한다. 단언:
- not-found heading이 보인다.
- 같은 문서다. navigation 전에 심은 전역 표시가 남아 있고 entry script가
  그대로다(reload 없음).
- 그 문서가 chunk를 요청했다(Resource Timing 항목, 단언이 빈 경로를
  보지 않게).
- navigation 뒤 서버 요청에 그 chunk가 없다(워커가 답했다).
- strict fixture가 허용 밖 실패 줄을 보지 않는다(기존 teardown 검사).
지워진 chunk를 찾는 코드는 기존 test와 같이 쓰도록 `removedRouteChunk`로
뺐다. Firefox는 같은 파일의 기존 격리(quarantine, 2027-03-31)를 그대로
따른다. Playwright Firefox는 워커가 페이지를 제어하지 못한다(06-R11 확인).
버린 대안: fixture가 워커 쪽 응답을 추적. Playwright 워커 network 이벤트는
Chromium 전용이다.

위험·한계: 테스트만 더했다. 지금 코드는 맞으므로 RED(부모 코드)에서도
통과한다. 결함은 변이로 보인다. 엔진마다 약 7초가 늘어난다(06-R9 기준).
WebKit에서는 chunk가 modulepreload link로 요청되어 워커 경로가 Chromium과
같은지 확인하지 않았다. 허용 패턴 자체는 그대로다.

검증: desktop batch에서 확인.
- corepack pnpm exec playwright test tests/e2e/service-worker-update.spec.ts --project=chromium --project=webkit
- 변이(06-R10과 같음, `service-worker-lifecycle.ts`의
  PREVIOUS_RELEASE_FALLBACK 분기가 `return null`): 새 test가 chromium에서
  sameDocument false(또는 fixture 실패 줄)로 실패해야 한다.

Refs: 1105/06-03
2026-11-05 22:13:53 +09:00
DongHyeonka ddbda4d21e fix(feature-index): 바뀌지 않은 기능 인덱스는 다시 쓰지 않는다
문제: 빌드, dev 서버, 타입 검사, vitest가 모두 시작할 때
`scripts/generate-product-feature-index.ts`로 `src/.generated/*.ts`를
다시 쓴다. 생성기는 `writeFile`로 파일을 제자리에서 비우고 다시 썼다.
한 checkout에서 두 실행이 겹치면, 한쪽이 파일을 비운 순간 다른 쪽의
Vite나 tsc가 빈 파일이나 반쯤 쓴 파일을 읽을 수 있다(1105/12-04의
"한 checkout 두 실행" 중 공유 소스 파일 부분).

고른 방법: 내용이 같으면 쓰지 않는다. 다르면 같은 폴더의 임시 파일에
쓰고 rename으로 바꾼다. 읽는 쪽은 옛 파일이나 새 파일 하나만 본다.
같은 선택(같은 PRODUCT_APP_ID·VITE_PRODUCT_FEATURES)으로 도는 두 실행은
아예 쓰지 않는다.
버린 대안: 실행마다 `src/.generated`를 따로 두기. 앱 소스가 이 경로를
import하므로 경로를 바꾸면 Vite·tsc·ESLint 설정이 모두 따라 바뀐다.
잠금 파일: 겹친 실행을 직렬로 만들 뿐이고, 죽은 프로세스가 잠금을
남긴다.

위험·한계: 선택이 서로 다른 두 실행(예: 한쪽만 VITE_PRODUCT_FEATURES=none)은
여전히 서로의 인덱스를 바꾼다. 그건 실행이 아니라 checkout 상태가 다른
것이라 이 커밋 범위 밖이다. 임시 파일은 `.tmp`로 끝나 tsc·Vite·ESLint
대상이 아니다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/product-feature-index-write.test.ts

Refs: 1105/12-04
2026-11-05 22:12:33 +09:00
DongHyeonka 629c713ce4 fix(ci): immutable_build가 gate 로그와 advisory 기록을 항상 올린다
문제: ci:gate는 명령 출력을 artifacts/quality/gates/FE-GATE-<NNN>.txt에만
쓰고 콘솔에는 PASS/FAIL 한 줄만 남긴다(scripts/run-ci-gate.ts). release
단계 job immutable_build는 후보 tar만, 그것도 성공했을 때만 올린다. 그래서
실제 run에서 FE-GATE-015·027이 왜 실패했는지와 FE-GATE-027이 쓰는
artifacts/security/dependency-advisories.json(1103/13-03의 신호)이 runner
작업 디렉터리와 함께 사라진다. 다른 gate job은 artifacts/를 if: always()로
올린다.

고른 방법:
- config/ci/gates.json의 immutable_build 마지막에 upload 단계를 더한다.
  transfer ID는 immutable-gate-evidence, 이름은
  immutable-gate-evidence-<run>-<attempt>, always: true. 대상은
  FE-GATE-015·027의 log와 evidence 산출물(gate 순서)과 advisory 기록 7개다.
  FE-GATE-015의 verification.json 등은 후보가 만들어지지 않으면 후보 안에도
  없으므로 같이 올린다.
- 계약(scripts/contracts/ci-gates.ts)이 이 단계를 고정한다. immutable_build의
  단계 목록에 upload 하나가 늘고, 이 upload가 always이고 마지막 단계이며
  경로가 "job이 도는 gate의 log·evidence 경로 + advisory 기록"과 같아야
  한다. 경로는 계약의 artifact 등록에서 계산하므로 log 경로가 바뀌면 함께
  따라온다. advisory 기록은 gate evidence가 아니라(막지 않는 신호) 경로를
  scripts/lib/dependency-advisories.ts의 상수로 옮기고 scan 스크립트도 그
  상수를 쓴다.
- 후보 archive의 member set, 후보 upload(always 없음), 하위 job의 download는
  그대로다. 생성 workflow를 generator 출력과 같게 손으로 고쳤다.

버린 대안:
- immutable_build도 artifacts/ 전체를 올림: 다른 job과 같지만 후보 증거가
  두 이름으로 나가 어느 것이 승격 대상인지 흐려진다. 필요한 파일만 고정했다.
- ci:gate가 실패한 명령의 마지막 N줄을 콘솔에 씀(리뷰 대안 c, d의 콘솔
  한 줄 포함): 모든 job에 걸리고 provider 출력의 비밀 노출과 로그 상한을
  다시 따져야 한다. 담당 지시 범위(업로드) 밖이라 이번에 하지 않았다.

위험·한계:
- checkout·install 단계에서 실패하면 올릴 파일이 없어 이 단계도
  if-no-files-found: error로 실패한다. job은 이미 실패한 뒤라 결과는 같다.
  merge·release job의 upload도 같은 동작이다.
- 실제 Gitea runner에서 stage=release를 돌려 산출물이 남는지는 확인하지
  못했다(runner 없음). 확인한 것은 계약·생성 workflow까지다.
- 콘솔에는 여전히 한 줄만 나온다. 사람이 산출물을 열어야 이유를 본다.

검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/ci-workflow-generation.test.ts
- corepack pnpm check:ci, check:types, lint, verify:documentation

Refs: 1105/13-01, 1103/13-03
2026-11-05 22:12:30 +09:00
DongHyeonka 8b92f45f5e fix(http): Fileserver 업로드 실패에 Envelope의 traceId를 싣는다
문제: readFailureEnvelope는 실패 Envelope의 meta.traceId를 함께 돌려주고,
V3 실행기는 그 값을 AppFailure.traceId로 싣는다(1103/03-06). Fileserver
client는 envelope.value만 넘겨 traceId를 버린다. 지원 담당이 업로드 실패를
서버 로그의 요청과 잇지 못한다. 같은 백엔드의 다른 쓰기 실패는 이을 수 있다.

고른 방법: envelopeFailure가 읽은 Envelope 전체를 받아 traceId가 있으면
createFailure의 traceId로 싣는다. V3와 같은 규칙이다. 없으면 키를 두지
않는다. 매뉴얼 7절 결과 읽기에 한 줄 적었다.

위험·한계: Envelope 실패에만 싣는다. 성공 Envelope을 읽지 못한 실패
(SCHEMA_MISMATCH 등, 202 REJECTED 포함)는 readSuccessEnvelope가 meta를
돌려주지 않아 traceId가 없다. V3도 같다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts
RED(이 커밋의 테스트 + 부모 src): Envelope failures 표 17행이 traceId
"trace-1"이 없어 모두 실패한다.

Refs: 1105/01-03
2026-11-05 22:12:19 +09:00
DongHyeonka 4d6f254438 fix(hosting): 자산 MIME probe가 redirect를 거절하고 live 분기를 테스트한다
문제: 확장자별 MIME probe(1103/06-03)는 install 조건 일부만 옮겼다.
1. install fetch는 `redirect: "error"`라 redirect가 하나라도 있으면
   실패한다. probe는 `redirect: "follow"`로 받고 최종 status와 MIME만
   본다. 같은 origin 안 redirect 뒤 200을 주는 호스트가 PASS다(리뷰
   06-R1). FE-GATE-019가 PASS인데 워커 install은 매번 실패한다.
2. 워커 없는 빌드에서도 돈다. 주석과 문서는 이유를 워커로만 적는다.
3. live 분기의 호출 줄(`verify-hosting-headers.ts`)을 지키는 테스트가
   없다. live 모드는 루프백·http를 거절해 저장소 테스트가 들어갈 수
   없다. 호출을 지우는 변이가 44건 통과로 살아남았다(06-R2).

고른 방법:
1. 자산 probe 기본 fetcher를 `redirect: "manual"`로 바꾸고,
   `response.redirected`이거나 `opaqueredirect`이면 관측 "redirected",
   이유 "install fetch가 redirect를 거절"로 FAIL이다. 3xx는 지금처럼
   `HTTP 3xx`로 FAIL이다. fetcher가 redirect를 따라가도 `redirected`로
   잡으므로 fetcher 방식과 무관하다.
2. 동작은 그대로 두고 의도를 주석과 운영 문서에 적었다. 워커가 없어도
   `nosniff` 아래 script·style은 MIME이 틀리면 페이지가 깨지고, 나중에
   워커를 켜는 릴리스가 호스팅을 다시 확인하지 않아도 된다. 글꼴·이미지는
   페이지에 피해가 없는데 FAIL한다는 것도 적었다. 워커 없는 빌드에서
   script·style만 보도록 좁히는 것은 검사를 약하게 하는 정책 결정이라
   하지 않았다(결정 대기, 템플릿 소유자).
3. live 분기 전체를 `probeLiveHosting`(release surface +
   자산 MIME)으로 빼고 스크립트는 그것만 부른다. 테스트가 fetcher
   대역으로 이 함수를 돌려 CSS `text/plain`이 FAIL인지 본다. 자산 probe
   호출을 빼면 이 테스트가 실패한다. 스크립트에서 `probeLiveHosting`
   호출을 빼면 live 결과가 비어 cache-control 행이 모두 FAIL이라 스스로
   드러난다.
버린 대안: 문서에 한계만 적기(리뷰 (b)). 1·3이 그대로다.

위험·한계: 정규 경로 규칙으로 자산을 redirect하는 호스트는 이제
FE-GATE-019에서 FAIL이다. 워커가 없는 제품도 마찬가지다(2의 판단).
실제 호스트로 live 모드를 돌리지는 않았다.

검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts
- RED: "fails an asset the host answers only after a redirect"(옛 probe는
  redirect 뒤 200을 PASS), "checks every built asset type besides the
  release surfaces"(옛 코드에 `probeLiveHosting`이 없음)가 실패한다.
- 변이(06-R2 대응): `probeLiveHosting`에서 `probeAssetContentTypes` 결과를
  빼면 "checks every built asset type ..."가 실패해야 한다.

Refs: 1105/06-02
2026-11-05 22:11:49 +09:00
DongHyeonka 471b001c40 fix(http): Fileserver 504 TRANSFER_TIMEOUT를 결과 불명으로 읽고 멱등 응답은 V3 표를 쓴다
문제: client는 504 TRANSFER_TIMEOUT을 NOT_APPLIED, retryable:true,
retryAfterMs 5000으로 준다. 매뉴얼대로면 기능이 5초 뒤 자동으로 다시
올린다. 근거로 든 "백엔드가 게시 전에 낸다"는 이 code에 맞지 않는다.
백엔드(45d2a478)는 업로드 작업을 전송 풀에 넘기고, 대기 스레드가
await-seconds가 지나면 작업 단계와 상관없이 future.cancel(true) 뒤
TRANSFER_TIMEOUT을 던진다(BlockingTransferExecutor). interrupt는 파일
복사는 멈추지만 게시 rename과 READY 커밋은 멈추지 않는다. 그래서 504 뒤에
파일이 READY가 될 수 있고, 백엔드가 멱등 키를 읽지 않으므로 다시 보내면
같은 파일이 둘 생긴다. 같은 client의 효과 표는 V3 표와도 갈라졌다. 503
IDEMPOTENCY_UNAVAILABLE을 client는 NOT_APPLIED, V3 표(backend-envelope.ts)와
매뉴얼 4절은 MAYBE_APPLIED로 본다. 계약 문서 6.1의 fileserver 행은 4xx를
MAYBE_APPLIED로 적는데 client는 NOT_APPLIED로 보고, 어느 쪽도 다른 쪽을
말하지 않는다. pin 대조도 이 표를 보지 않는다.

고른 방법:
- TRANSFER_TIMEOUT을 NOT_APPLIED_5XX_CODES에서 뺀다. 5xx 기본값대로
  MAYBE_APPLIED이고, createFailure가 retryable:false, action contact-support로
  만든다. 자동 재전송은 없다. 남은 NOT_APPLIED 5xx는 작업 스레드가 게시 전에
  내는 넷(PARTIAL_WRITE, ATOMIC_PUBLISH_UNSUPPORTED, STORAGE_UNAVAILABLE,
  STORAGE_FULL)이다.
- 멱등성 code(IDEMPOTENT_*, IDEMPOTENCY_* 접두)와 V3 표의 행(REFUSED_BEFORE_WRITE,
  MAYBE_APPLIED_ANSWERS의 status+code)은 client도 envelopeFailureEffect로
  판정한다(sharedAnswerEffect). 같은 백엔드 code의 판정이 이 repo에 하나다.
  503 IDEMPOTENCY_UNAVAILABLE은 MAYBE_APPLIED가 되고, 400
  IDEMPOTENCY_KEY_INVALID·422 IDEMPOTENT_REQUEST_MISMATCH는 그대로
  NOT_APPLIED, 409 IDEMPOTENT_IN_FLIGHT 등은 그대로 MAYBE_APPLIED다. 손으로 둔
  MAYBE_APPLIED_CODES 목록은 AMBIGUOUS_COMPLETION 비교 하나로 줄었다.
- pin 옆에 복사한 백엔드 답 표(config/contracts/backend-idempotency-answers.json)의
  행마다 client 결과의 effect가 V3 표와 같은지 통합 테스트가 본다. 그 표는
  tests/unit/backend-contract-pin.test.ts가 V3 표를 묶는 표와 같다. pin을
  옮기면 두 reader가 함께 다시 대조된다.
- Fileserver 4xx를 NOT_APPLIED로 보는 이유(업로드 use case가 취소)를 계약
  문서 6.1에 한 곳으로 적고, client 주석과 매뉴얼은 그곳을 가리킨다.
- client 주석·매뉴얼의 백엔드 SHA 표기를 bbe944bd에서 pin(45d2a478)으로
  맞췄다. 두 SHA 사이 Fileserver main 코드는 바뀌지 않았다(리뷰 2.1절).
버린 대안:
- client 효과 판정을 V3 표로 통째로 바꾼다: Fileserver 4xx가 모두 결과
  불명이 되어 413·415·422 파일 거절과 202 REJECTED 화면이 나빠진다. 단일
  업로드에서는 use case가 취소하므로 근거도 없다.
- TRANSFER_TIMEOUT 한 줄만 고친다: 위험한 줄은 없어지지만 세 표의 갈라짐과
  pin 밖 상태가 남는다.

위험·한계:
- 504 TRANSFER_TIMEOUT 뒤 화면이 "재시도"에서 "결과 불명"으로 바뀐다. 503
  IDEMPOTENCY_UNAVAILABLE도 같다. CHANGELOG [계약] 한 줄이 필요하다.
- 백엔드로 넘김: 백엔드는 TRANSFER_TIMEOUT을 retryable=true, ambiguous 없이
  보낸다(FileserverErrorCode, BlockingTransferExecutor). 요청 — (a) 작업이
  시작된 뒤의 대기 초과는 details.ambiguous=true, reconciliationRequired=true,
  retryable=false로 보내거나, (b) 작업 스레드가 게시 rename과 READY 커밋 전에
  interrupt를 확인해 504가 "READY 없음"을 보장하게 하고, 어느 쪽인지
  docs/fileserver/http-contract.md에 적는다. 백엔드가 (b)를 고르면 이 줄을
  되돌린다(재검토 조건).
- 백엔드로 넘김: POST /v1/files가 Idempotency-Key를 읽지 않는다
  (UploadFileApplicationUseCase NOT_IDEMPOTENT). 요청 — 업로드를 멱등성
  executor 뒤에 두거나, 키를 무시한다고 Fileserver 계약 문서에 적는다.
- 리뷰 최소 개선 방향 ④의 "drift 검사 대상에 docs/fileserver/http-contract.md
  추가"는 하지 않았다. scripts/check-backend-contract-drift.ts와 pin 모양은
  같은 라운드의 1105/07-01 수정이 다시 짠다. 같은 파일을 두 브랜치가 고치면
  충돌한다. 07-01과 함께 넣는 편이 낫다.
- Fileserver 자신의 code 표(NOT_APPLIED_5XX_CODES)는 여전히 손으로 읽은
  것이고 pin 대조 밖이다. 늦게 READY가 되는 경쟁은 재현하지 않았다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts
RED(이 커밋의 테스트 + 부모 src): Envelope failures 표의 "503
IDEMPOTENCY_UNAVAILABLE → SERVER_FAILURE, MAYBE_APPLIED, retryable false",
"504 TRANSFER_TIMEOUT → SERVER_FAILURE, MAYBE_APPLIED, retryable false",
"504 TRANSFER_TIMEOUT is an unknown result the client does not offer to
retry", pinned backend answer table의 "reads 503 IDEMPOTENCY_UNAVAILABLE as
the V3 Envelope table does"가 실패한다.

Refs: 1105/01-02
2026-11-05 22:11:17 +09:00
DongHyeonka 3b62ccd5db fix(registry): 응답 스키마 행을 REJECT_UNKNOWN으로 좁히면 breaking으로 본다
문제: 응답 DTO를 `.strict()`로 바꾸고 FE-REG-SCHEMA 행의
`unknownFieldPolicy`를 STRIP_UNKNOWN에서 REJECT_UNKNOWN으로 같이 고치면
check:registries가 behavior-change로 통과한다(리뷰 배치 07-R1). 1103/07-03
수정은 행과 검증기를 묶었지만 등급은 그대로였다. 그 뒤 백엔드가 응답에
필드 하나를 더하면 그 API는 SCHEMA_MISMATCH로 실패한다. 같은 경계에서
FE-REG-API는 acceptedStatuses 축소를 breaking으로 본다.

고른 방법: 분류기에 규칙 하나를 더한다. `direction: "RESPONSE"` 행의
`unknownFieldPolicy`가 REJECT_UNKNOWN이 아니던 값에서 REJECT_UNKNOWN으로
바뀌면 kind `response-reader-narrowed`, breaking이다. 반대 방향
(REJECT→STRIP, 읽는 쪽을 넓힘)과 REQUEST 행(프론트가 스스로 채우는 값)은
그대로 behavior-change다. 버린 대안: governance의 FE-REG-SCHEMA
breakingFields에 `unknownFieldPolicy`를 넣는 것(리뷰 안 B). 넓히는 변경까지
증거를 요구하게 되고, governance 계약이 바뀌어 템플릿과 다운스트림 모두
기준선을 다시 승인해야 한다. 이 규칙은 기준선과 governance를 바꾸지 않는다.
리뷰 안 (1)의 fieldTypes 선언도 같은 이유로 하지 않았다.

위험·한계: 규칙은 칸 이름(`unknownFieldPolicy`)과 값 어휘
(src/contracts/schema-registry.ts)에 묶여 있다. 어휘를 바꾸면 이 함수도
고친다. route-params·route-search(REQUEST 방향, URL을 읽는 쪽)를
REJECT_UNKNOWN으로 좁히는 변경은 여전히 behavior-change다. 지금 템플릿
스냅샷은 기준선과 같아 결과는 none 그대로다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/registry-compatibility.test.ts
리뷰 07-R1 패치(응답 DTO `.strict()` + 응답 행 두 개 REJECT_UNKNOWN)를
다시 적용하면 check:registries가 `breaking change missing evidence:
FE-REG-SCHEMA:ReferenceResource(List)Payload:unknownFieldPolicy:
response-reader-narrowed`로 실패해야 한다.

Refs: 1105/07-02
2026-11-05 22:10:05 +09:00
DongHyeonka 1c7c614b47 fix(service-worker): 사전 캐시를 Vite assets 폴더의 해시 파일로 제한한다
문제: 사전 캐시 수집기(`collectStaticAssets`)는 dist 전체를 돌고 파일
이름만 해시 정규식으로 본다. `public/` 파일은 이름 그대로 dist 루트에
복사되는데, `apple-touch-icon.png`, `android-chrome-192x192.png`,
`safari-pinned-tab.svg`는 정규식에 걸려 immutable 자산으로 들어간다(리뷰
06-R1). 제품이 같은 이름으로 아이콘을 바꾸고 CDN이 옛 바이트를 주면 새
릴리스 install이 INTEGRITY_MISMATCH로 통째로 거절된다. 이전 릴리스
fallback, 호스팅 정책 `/assets/*`, MIME probe, 레시피 문서는 모두
`assets/`만 가정한다.

고른 방법: 리뷰 06-01의 (a). 계약 모듈에 `BUILD_ASSET_DIRECTORY =
"assets/"` 하나를 두고, 수집기는 그 아래 파일만 받는다. 워커 fallback
(`service-worker-static-assets.ts`)과 probe(`hosting-probe.ts`)도 같은
상수를 읽는다. `build.assetsDir`를 바꿀 때(0925/06-08) 이 상수 한 곳만
고치면 된다. 수집기의 `.vite/` 제외는 새 조건이 덮으므로 지웠다. 레시피
문서에 루트 파일이 빠진다는 문장을 더했다.
버린 대안:
- 정규식을 Vite 해시 형식(8자 고정)으로 좁히기. 우연히 맞는 이름이 남는다.
- 문서만 고치기. 아이콘 문제가 그대로다.

위험·한계: 루트에 해시 이름 파일을 일부러 두는 제품은 그 파일이 사전
캐시에서 빠진다. Vite는 그런 파일을 만들지 않는다. 상수는 vite 설정에서
읽지 않는다. `build.assetsDir`를 바꾸는 제품은 상수도 같이 바꿔야 한다
(0925/06-08은 그대로 남는다).

검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/unit/service-worker-web-push-remediation.test.ts tests/unit/service-worker-runtime.test.ts tests/unit/hosting-probe.test.ts tests/unit/service-worker-build-output.test.ts
- RED: "precaches only the assets directory, not public files at the dist
  root"가 옛 수집기에서 루트 아이콘 세 개를 받아 실패한다.

Refs: 1105/06-01
2026-11-05 22:08:50 +09:00
DongHyeonka 2e1acb1f21 fix(bootstrap): 금지된 설정 키로 멈춘 부팅 오류에 그 키 이름을 싣는다
문제: 런타임 설정에 비밀처럼 보이는 키(`CLIENT_SECRET` 등)가 있으면
부팅이 CONFIG_SECRET_NAME_REJECTED로 멈추지만, 안전한 부팅 오류에는
buildId만 있고 어느 키인지가 없다. assertSafeConfigNames가 던진 오류의
message에는 키 이름이 있었지만 loadRuntimeConfig가 그 오류를 버렸다.
같은 파일의 스키마 실패는 키 이름을 invalidKeys로 싣는다.

고른 방법: assertSafeConfigNames가 UnsafeConfigNameError를 던지고 그
`key`에 거절한 키의 점 경로(`CAPABILITY_OVERRIDES.AUTH_TOKEN`,
`FEATURE_OVERRIDES.<id>.CLIENT_SECRET`)를 싣는다. 로더는 그 경로를
스키마 실패와 같은 SAFE_KEY_PATTERN으로 거른 뒤 invalidKeys에 넣는다.
오류 화면은 이미 invalidKeys를 "잘못된 설정 키"로 보인다. 값은 어디에도
싣지 않는다. 버린 대안: message에서 키를 정규식으로 다시 읽는 것.
message 문구가 바뀌면 조용히 빠진다.

위험·한계: 키 이름은 거절된 문서에서 온다. 그래서 길이·문자를 제한하고,
그 밖의 이름은 빼고 코드만 남긴다. 첫 번째로 걸린 키 하나만 싣는다
(검사가 첫 키에서 멈추는 동작은 그대로). assertSafeConfigNames의
시그니처와 message는 바꾸지 않았다. UnsafeConfigNameError는
src/contracts/env.ts에 새로 더한 export다(추가만).

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/runtime-schema/runtime-config.test.ts

Refs: 1103/07-04
2026-11-05 22:08:22 +09:00
DongHyeonka 23662fb23a fix(storage): 객체를 끝까지 돈 계정 삭제 purge는 늘 partition을 지운다
문제: 승인된 LOGOUT·ACCOUNT_DELETION purge는 객체 목록을 읽고, 하나씩
지우고, 마지막에 journal 행을 한 번 센 뒤 0이면 chunk sweep으로 끝나
`chunkSweep: "COMPLETED"`를 돌려준다. 목록과 세기는 각각 한 순간만 본다.
- 다른 탭이 새 객체를 put하는 중이면 purge의 remove가 그 put이 쥔
  origin lease를 기다린다. partition에 객체가 3개 이상이면 그 put은
  목록 뒤에 commit하고 세기 전에 complete까지 끝난다. 목록에도 행 수에도
  없어 sweep이 그 chunk를 건너뛰고, 계정 삭제 뒤에도 파일이 읽힌다
  (리뷰 실험 Y1b 메모리 20/20, Chromium 6/6). 저장소 테스트는 객체
  0~1개로만 돌아서 이 틈을 놓쳤다.
- FILES_READY에서 멈춘 put의 행이 `logicalKey`를 잃으면 세지 못한다.
  staging receipt가 chunk를 sweep에서 지켜 purge마다 COMPLETED인데
  receipt·chunk·manifest가 남는다(Y2).

고른 방법: 마지막 객체까지 돈 purge는 sweep 대신 늘 partition 삭제로
끝낸다(리뷰 2.1절 (d')). exclusive partition lock이 그때 진행 중인
put·delete를 모두 기다린 뒤 디렉터리 전체(staging 포함)와 그 partition
행을 지우므로 두 경우를 함께 막는다. 객체 순회는 `removedObjects`·
`releasedBytes` 보고와 예산 단위 진행을 위해 남긴다. 예산이나 다른 탭의
변경(CONFLICT) 때문에 끝까지 돌지 못한 호출은 지금처럼
`moreObjectsAvailable: true`를 돌려주고, 그때만 journal 행을 세서 끝나지
않은 행이 있으면 바로 partition을 지운다(2026-11-03 05-01 그대로).
purge 성공 report는 이제 `partitionDeleted`와 `moreObjectsAvailable`
중 정확히 하나를 가진다(walk 뒤 abort도 more로 보고).

버린 대안:
- (a) sweep 뒤에 다시 세고 committed 객체를 한 번 더 본다: ①만 막고
  ②가 남는다. 다시 볼 때 정책상 남겨야 할 객체를 가려내려면 목록을 끝까지
  다시 읽어야 한다.
- (b)+(a): 둘 다 막지만 판단 조건이 일곱 개가 된다.
- 세기를 아예 없애기: 예산에 걸린 호출의 crash 행 처리가 다음 호출로
  밀린다. 지금 동작을 바꿀 이유가 없어 남겼다.

위험·한계:
- 모든 승인 purge가 다른 탭의 진행 중 put을 기다린다(지금까지는 끝나지
  않은 행이 있을 때만). 기다림 상한은 `mutationLockWaitTimeoutMs`
  (1103/05-02)이고 abort로 멈출 수 있다.
- 같은 partition에 LOGOUT 때 남겨야 하는 객체가 섞이면 이 방법은 맞지
  않는다. 지금 정책 검사는 OPAQUE_PARTITION이면 LOGOUT·ACCOUNT_DELETION
  모두 purge만 허용해 그런 객체가 생기지 않는다.
- port의 `chunkSweep`은 아무도 채우지 않는다. 읽는 코드가 깨지지 않게
  타입은 남기고 `@deprecated`로 적었다.
- recipe fake의 purge도 늘 `partitionDeleted`다.
- `logicalKey`를 잃은 행 자체는 여전히 남는다(05-03 설계). 그 bytes는
  이제 남지 않는다.
- Firefox·WebKit에서 Y1은 돌리지 않았다. browser spec은 객체 0·3개
  두 경우로 늘렸다.

검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/opfs-worker-runtime.test.ts
  tests/unit/opfs-byte-store.test.ts tests/unit/indexeddb-opfs-journal.test.ts
- node scripts/run-vitest.ts run tests/recipes/browser-file-storage-contracts.test.ts
- corepack pnpm test:browser-capabilities tests/browser-capabilities/opfs-runtime.spec.ts --project=chromium

Refs: 1103/05-01
2026-11-05 22:08:19 +09:00
DongHyeonka 6608fef4ba fix(http): Fileserver 202 REJECTED를 파일 거절로 읽고 빈 파일은 보내지 않는다
문제: 짝 백엔드(45d2a478)는 POST /v1/files를 요청 안에서 동기로 검증하고
READY가 아닌 state를 모두 202로 답한다(FileUploadController#created).
악성 코드가 아닌 이유로 검증기가 거절하면 예외 없이 202 REJECTED다
(FinalizeUploadApplicationUseCase#applyNonAcceptVerdict). 기본 검증기 사슬의
첫 검증기(LengthVerifier)가 빈 파일을 그렇게 거절하므로, 0바이트 파일
하나로 닿는다. client schema에는 REJECTED가 없어 이 답이 SCHEMA_MISMATCH,
APPLIED_CONFIRMED, "응답 형식 오류" 문구로 끝난다. 사용자는 파일을 바꾸라는
안내 대신 지원 문의를 보게 된다. 테스트의 MSW는 202 VERIFYING만 적은 백엔드
문서에서 왔고, 매뉴얼도 202를 "아직 검사 중"으로 적어 QUARANTINED(동기
검증 202의 대부분)를 끝나지 않는 대기로 보이게 한다.

고른 방법(리뷰 01-01 최소 개선 방향 (가)):
- schema가 REJECTED를 받는다. 202 REJECTED는 성공이 아니라 실패
  VALIDATION_REJECTED, code FILE_REJECTED, NOT_APPLIED, httpStatus 202다.
  413·415·422 파일 거절과 같은 규칙이다. 백엔드는 그 레코드를 공개하지
  않고 바이트 정리를 예약하므로 쓸 수 있는 파일이 남지 않는다. 공개 타입
  FileserverFileState와 FileserverUploadedFile은 바꾸지 않았다(REJECTED는
  성공 값으로 나오지 않는다).
- 빈 파일은 읽기 전(선언 크기 0) 또는 읽은 뒤(선언 없음, 0바이트)
  보내지 않고 FILE_EMPTY, NOT_STARTED로 끝낸다. 서버의 202 REJECTED에는
  이유가 없어 기능이 "빈 파일"이라고 말할 수 없기 때문이다.
- 201⇔READY 검사, size 일치 검사, 모르는 필드 무시는 그대로다. 201
  REJECTED는 여전히 SCHEMA_MISMATCH다.
- MSW 설명을 백엔드 코드(45d2a478) 기준으로 고치고 202 QUARANTINED·
  REJECTED 행을 더했다(1103/01-01의 "MSW가 문서에서 왔다" 부분).
- 매뉴얼 7절이 202 state 셋의 뜻(VERIFYING 재검사 대기, QUARANTINED 관리자
  결정 전 내려받기 불가, REJECTED는 실패)과 FILE_EMPTY를 적는다.
버린 대안:
- REJECTED를 성공 state로 넘긴다: 타입 변경은 작지만 기능마다 성공 값에서
  거절을 다시 찾아야 하고, 공개 타입 FileserverFileState가 넓어진다.
- 빈 파일 거절만 한다: 기본 사슬은 막지만 제품이 더한 검증기의 REJECT는
  그대로 SCHEMA_MISMATCH다.

위험·한계:
- upload() 결과가 바뀐다. 202 REJECTED가 SCHEMA_MISMATCH에서
  VALIDATION_REJECTED/FILE_REJECTED로, 빈 파일이 서버 요청에서 FILE_EMPTY로
  바뀐다. CHANGELOG [계약] 한 줄이 필요하다.
- 빈 파일 거절은 짝 백엔드 기본 검증기 사슬을 가정한다. 제품이 사슬에서
  LengthVerifier를 빼 빈 파일을 받게 하면 client 규칙도 바꿔야 한다.
- 실제 짝 백엔드를 띄워 빈 파일을 올려 보지 않았다(미검증). 응답 모양은
  백엔드 코드(UploadedFileResponse, FileRecord#toDescriptor)를 읽은 것이다.
- 1103/01-01의 남은 부분은 이 커밋 밖이다: 백엔드 매뉴얼의 짝 경로 안내와
  docs/fileserver/http-contract.md의 202 state 목록(백엔드로 넘김), 실제
  업로드 검증(미검증).

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts
RED(이 커밋의 테스트 + 부모 src): "reads 202 REJECTED as a refused file,
not as a broken answer"(SCHEMA_MISMATCH로 끝남), "an empty file", "an
undeclared size that turns out empty"(fetch를 부름)가 실패한다.

Refs: 1105/01-01, 1103/01-01
2026-11-05 22:07:43 +09:00
DongHyeonka 00b12b35b9 test(bootstrap): 플랫폼 규칙 테스트 둘을 샘플 밖으로 옮긴다
문제
1103 수정이 더한 플랫폼 규칙 테스트 둘이 참조 샘플에 기댄다. 샘플을
지우면 두 테스트가 사라지거나 비어도 test:all과 제거 드릴이 통과한다.
- MAX_RETRY_ATTEMPTS가 실행기에 닿는다: 유일한 테스트가
  tests/features/reference-feature/reference-runtime-composition.test.ts
  에 있다. createRuntimeAdapters는 설치된 기능의 HTTP로만 실행기에 닿아,
  기능이 없으면 시험할 길이 없다. REQUEST_TIMEOUT_MS도 같은 모양이다.
- 복구 중인 세션은 보호 라우트에서 기다린다:
  tests/unit/navigation-policy.test.ts는 설치된 보호 라우트를 돌며
  단언하는데, 보호 라우트는 모두 샘플 것이라 샘플을 지우면 반복이 0번이다.

고른 방법과 버린 대안
- src/bootstrap/runtime-adapters.ts: 설정 두 값과 auth profile 표로
  실행기를 만드는 부분을 createRuntimeContractHttpExecutor로 뺀다.
  조립 루트는 이 함수로만 실행기를 만든다. tests/unit/runtime-adapters
  .test.ts가 테스트 계약(TEST_LIST, 재시도 예산 2)으로 MAX_RETRY_ATTEMPTS
  0·1·2에 1·2·3번 나가는지, REQUEST_TIMEOUT_MS 5가 10초 계약을 5ms에
  끊는지 본다. 이 파일은 이미 제거 드릴의 공통 테스트 목록에 있다.
- tests/unit/session-route-access.test.ts(새 파일): component 테스트와
  같은 방법으로 생성 index를 mock해 tests/helpers/fixture-feature.tsx를
  설치하고, 보호 라우트 FIXTURE_ITEMS에서 네 세션 상태의 결정을 본다.
  decideRouteAccess에 라우트 정의를 받는 순수 함수를 따로 두는 안(리뷰
  ⓐ)은 버렸다. fixture 기능을 설치하는 방법이 이미 있어서 운영 코드를
  바꾸지 않고 실제 getRoute 경로까지 시험할 수 있다.
- scripts/test-sample-removal.ts: 새 파일을 공통 테스트 목록에 넣어,
  제거 드릴이 그 파일이 남았는지 본다.
- 매뉴얼에 "샘플을 지우면 다시 고정한다"고만 적는 안(ⓒ)은 사람이
  기억해야 해서 버렸다.

위험·한계
- 조립 루트가 이 함수 대신 실행기를 직접 만들도록 바뀌면 새 unit
  테스트는 그걸 모른다. 템플릿 상태에서는 참조 기능 테스트가 계속
  조립 루트 전체를 지킨다.
- 샘플을 지운 복사본에 변이를 넣어 돌리지는 않았다.

검증
- desktop batch에서 확인:
  node scripts/run-vitest.ts run tests/unit/runtime-adapters.test.ts tests/unit/session-route-access.test.ts tests/unit/navigation-policy.test.ts tests/features/reference-feature/reference-runtime-composition.test.ts
- RED: 부모 커밋의 운영 코드에는 createRuntimeContractHttpExecutor가
  없어 runtime-adapters.test.ts의 새 4건이 실패한다.
- 변이: 새 함수의 maxRetryAttempts를 상수 2로 바꾸면 "honours
  MAX_RETRY_ATTEMPTS 0/1"이, navigation-policy.ts의 recovery-pending
  분기를 show-sign-in으로 바꾸면 session-route-access.test.ts의
  "answers a recovery-pending session …"이 실패해야 한다.

Refs: 1105/10-01
2026-11-05 22:07:09 +09:00
DongHyeonka 9655958bda fix(ci): test:system 사전 점검이 bwrap namespace를 실제로 만들어 본다
문제: FE-GATE-013의 provider sandbox는 bwrap을 --unshare-pid
--unshare-ipc --unshare-uts --unshare-net으로 띄운다. bwrap이 setuid가
아니므로 비특권 user namespace가 있어야 한다. 사전 점검
(scripts/check-system-test-prerequisites.ts)은 실행 파일·cgroup·systemd
bus만 보고 bwrap을 한 번도 실행하지 않는다. 그래서 이 제한이 있는 호스트
(Ubuntu 24.04, kernel.apparmor_restrict_unprivileged_userns=1)에서 PASS를
낸 뒤 provider 테스트 114건 중 18건이 "bwrap: loopback: Failed
RTM_NEWADDR: Operation not permitted" 또는 그 provider를 기다린 시간
초과로 실패한다. 이 조건은 runner 요구 목록, gate 정의, workflow 어디에도
없고 운영 원장의 일회성 메모에만 있다.

고른 방법:
- 사전 점검이 provider와 같은 namespace 옵션으로 bwrap에서 /bin/true를 한
  번 띄운다. 실패하면 "this host does not allow unprivileged user and
  network namespaces", bwrap stderr(최대 4줄), user namespace sysctl 값,
  고치는 방법 셋(AppArmor profile, sysctl, 다른 runner)을 적고 exit 1.
  기존 검사(실행 파일 3개, cgroup v2, systemd bus)는 그대로 둔다.
- 옵션 목록을 scripts/lib/provider-sandbox-namespaces.ts로 옮기고
  run-and-validate-provider.ts와 사전 점검이 같은 상수를 쓴다. 둘이
  갈라지면 점검이 다른 것을 시험하게 된다.
- 점검을 findSystemTestPrerequisiteFailures(host)로 내보내고 access·
  readFile·spawn을 주입받는다. CLI 동작(출력·exit 코드)은 같다.
- config/ci/gates.json의 FE-GATE-013에 hostRequirements 두 줄을 둔다.
  gate schema에 선택 필드를 더하고, generator가 그 gate를 도는 job의
  runs-on 바로 위에 "# FE-GATE-013 runner requirement: ..." 주석으로
  그린다. runner를 고르는 사람이 보는 자리다. 줄바꿈은 기존 nonEmpty
  규칙이 막으므로 주석 밖으로 나갈 수 없다. 이 필드는 gate의 명령·증거가
  아니라 runner 설명이라 기준선 gate shape 해시에는 넣지 않았다(기준선
  재기록 불필요).
- 요구 목록 세 곳(docs/operations/ci-quality-gates.md,
  docs/security/supply-chain.md, docs/testing/taxonomy.md)과 README merge
  게이트 절에 조건을 적었다. ci-quality-gates.md에 AppArmor profile 예시를
  두었다.

버린 대안:
- namespace가 없으면 provider 테스트를 skip: 거짓 초록이다.
- FE-GATE-013을 release 단계로 옮김: PR마다 sandbox 검사를 잃는다.
- probe를 systemd-run --user --scope 안에서 돌림: 리뷰 11-R10에서 scope
  안과 밖의 결과가 같았다. 직접 실행이 더 단순하다.
- workflow에 요구 사항을 runs-on label로 표현: runner label 체계가 아직
  없다. 주석이 지금 가능한 가장 작은 표시다.

위험·한계:
- probe는 bwrap에 --ro-bind / /만 준다. --size 같은 provider의 다른
  옵션 지원은 여기서 보지 않는다(기존과 같다). probe가 다른 이유로
  실패해도 namespace 문구가 나오지만 bwrap stderr를 같이 적는다.
- 호스트를 고칠지는 호스트 소유자가 정한다. 이 커밋은 조건을 적고 알리기만
  한다. 이 desktop에서 FE-GATE-013은 여전히 실패하고, 이제 첫 단계에서
  이유와 함께 실패한다.
- gate schema에 선택 필드 hostRequirements가 생겼다. 기존 gates.json과
  제품 overlay는 그대로 통과한다.

검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/system-test-prerequisites.test.ts tests/unit/ci-workflow-generation.test.ts
- corepack pnpm check:ci, check:types, lint, verify:documentation
- desktop에서 node scripts/check-system-test-prerequisites.ts가 exit 1과
  namespace 문구를 내는지, FE-GATE-013이 그 단계에서 멈추는지

Refs: 1105/12-01, 1105/11-02
2026-11-05 22:06:59 +09:00
DongHyeonka bfd9d50d2b fix(registries): 계약 조립 실패의 원인을 check:registries에 한 번만 찍는다
문제: 계약 조립이 실패하면 check:registries 출력에 같은 원인이 두 번
나온다. 1103/09-07 수정이 ContractContributionError의 message 끝에
reason을 붙였고, 1103/14-06 수정이 loadErrorText에서 message 뒤에
"(reason: ...)"를 또 붙였다. 두 수정이 다른 브랜치에서 들어왔다.
기존 테스트는 reason이 message에 없는 가짜 오류로만 시험해 중복을
보지 못했다.

고른 방법: loadErrorText가 message에 reason이 이미 들어 있으면 붙이지
않는다. reason을 message에 싣지 않는 오류(기존 테스트의 가짜 오류)는
지금처럼 "(reason: ...)"가 붙는다. 버린 대안: ContractContributionError
message에서 reason을 다시 빼는 것. message만 찍는 다른 출구(부팅 오류,
테스트 출력)가 원인을 잃는다(1103/09-07이 고친 문제).

위험·한계: message 첫 줄만 보므로 여러 줄 reason은 다시 붙는다. 지금
reason은 한 줄이다. docs/manual/reference/errors.md의 출력 형식 줄을
실제 출력에 맞췄다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/registry-governance.test.ts
새 테스트는 실제 ContractContributionError를 던지는 source로
check:registries를 돌려 원인이 한 번만 나오는지 본다.

Refs: 1105/09-03
2026-11-05 22:06:33 +09:00
DongHyeonka 397664e439 test(features): 제품 확장 타입 검사 탐침이 제품 파일을 덮어쓰지 않고 덧붙인다
문제
tests/unit/product-extension-typecheck.test.ts(1103/09-02 탐침)는 저장소
복사본의 src/contracts/product-contracts.ts와
src/bootstrap/product-composition.ts를 탐침 내용으로 통째로 바꿔 쓴다.
탐침의 composeProduct는 typecheckProbeSettings 하나만 돌려준다. 제품이
자기 capability를 product-composition.ts에서 만들고 자기 기능의 needs에
적으면, 복사본에서는 그 값이 사라져 app 프로그램이
src/bootstrap/runtime-adapters.ts에서 TS2741로 실패한다. memento와
tech-log 모두 제품 capability를 쓰므로, 동기화 직후 FE-GATE-005가 코드와
무관하게 실패한다(리뷰 실험 09-probe-downstream).

고른 방법
- 탐침은 복사본의 product-contracts.ts·product-composition.ts를 같은
  폴더의 typecheck-probe-product-contracts.ts·
  typecheck-probe-product-composition.ts로 옮긴다. 새 파일은 옮긴 모듈을
  export *로 다시 내보낸다. 그리고 런타임 설정 필드, env 행,
  composeProduct 결과와 그 capabilities를 펼친 뒤 탐침의 키·행·capability만
  더한다. 인증 프로필, credential provider, 선택 칸, session owner, 제품이
  더한 다른 export는 그대로 남는다.
- capability 타입은 저장소가 아니라 복사본의 product-capabilities.ts 끝에
  덧붙인다.
- 같은 함수로 "제품 capability를 기능에 주는 다운스트림"을 먼저 만들고 그
  위에 탐침을 올리는 케이스를 더했다(describe 1105/09-01). 다운스트림
  흉내도 덧붙이는 방식이라, 실제 다운스트림에서 이 테스트를 돌려도 그
  제품의 파일을 지우지 않는다. 이름은 예약 접두사
  typecheck-probe-downstream-*를 쓴다.
- 예약 이름 검사는 기능 폴더에 더해 context 폴더와 옮길 파일 이름도 본다.

버린 대안
- 제품 파일이 출하 상태가 아니면 탐침을 건너뛴다(리뷰의 (나)). 다운스트림
  상태의 타입 경로 확인을 잃고, 건너뛰기로 검사를 약하게 한다.
- 다운스트림 흉내를 제품 파일 전체를 새로 쓰는 방식으로 만든다. 실제
  다운스트림에서 이 테스트를 돌리면 그 제품의 capability를 지워 같은
  TS2741이 다시 난다.

위험·한계
- 제품 파일의 export 이름(composeProduct, composeProductSessionOwner,
  PRODUCT_*)에 기댄다. 템플릿이 그 이름을 import하므로 계약이다.
- credentialProviders와 인증 프로필은 Record라 빠져도 tsc가 모른다.
  펼쳐서 남기지만 테스트로 증명하지는 않는다.
- 탐침 context는 여전히 소유 앱을 template-app으로 고정한다. 앱 id를
  바꾼 제품에서는 생성기가 멈출 수 있다(리뷰 09-01의 남은 가정, 실행
  안 함). 이 커밋 범위 밖이다.
- 케이스가 하나 늘어 이 파일의 tsc 실행이 3회에서 6회가 된다. 케이스별
  제한 시간 120초는 그대로다.
- 결함이 테스트 파일 안의 탐침에 있어서, 표준 RED 구성(커밋의 테스트 +
  부모의 비테스트 파일)은 GREEN과 같다. RED는 커밋 위에 탐침을 부모처럼
  덮어쓰게 되돌리는 patch를 적용해 본다.

검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
  tests/unit/product-extension-typecheck.test.ts, check:types, lint.
  RED patch를 적용하면 1105/09-01 케이스만 TS2741로 실패해야 한다.
- 이 노트북에서는 실행하지 않았다.

Refs: 1105/09-01
2026-11-05 22:05:52 +09:00
DongHyeonka 27e3dec5dd fix(realtime): poll execute에 생성 때 검사한 descriptor를 넘긴다
문제: bounded poll은 생성 때 descriptor의 `retryBudget`이 0인지 본다
(1103/04-01). 그런데 `execute` 입력에는 descriptor가 없다. 조합 코드는
실행기에 넘길 descriptor를 스스로 골라야 하고, 같은 경로의 기본 GET
(`retryBudget: 2`)을 넘겨도 막는 것이 없다. 리뷰 04-R1 P5에서 poll 3회가
요청 9회, 실행기 대기 6번이었다. 타입 주석과 설계 9.2가 "같은 객체를
넘긴다"고 적을 뿐이다.

고른 방법: coordinator가 생성 때 검사한 그 객체를 모든 `execute` 호출에
`input.operation`으로 넘긴다. 생성 때 한 번 잡아 두므로 나중에
dependencies 객체가 바뀌어도 검사한 객체가 간다. 조합 코드는 클로저의
descriptor 대신 이것을 실행기에 넘기면 된다. 테스트의 V3 조합도 그렇게
바꿨다. 타입 주석(`bounded-polling.ts`, `bounded-poll-coordinator.ts`)과
설계 9.2를 고쳤다.
버린 대안: coordinator가 실행기를 직접 받아 부르기. 실행기 타입은
`adapters/http`에 있어 realtime 어댑터가 import할 수 없다(adapter 사이
import 금지, kernel 예외 아님). 구조 타입을 새로 두면 결과 매핑까지
coordinator가 정해야 해서 공개 모양이 크게 바뀐다.

위험·한계: 일부만 닫는다. 조합 코드가 `input.operation`을 무시하고 다른
descriptor를 실행기에 넘기면 여전히 attempt마다 요청이 최대 3번이다.
설계 9.2가 이 남은 틈을 적는다. 입력 칸을 더한 것이라 기존 `execute`는
그대로 돈다.

검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/unit/realtime/
- RED: "hands every execute call the descriptor it checked at creation"
  (받은 값이 undefined), "sends one request per poll attempt with a poll
  descriptor"(실행기에 undefined가 가서 요청 0개, PROTOCOL_MISMATCH)가
  옛 코드에서 실패한다.

Refs: 1103/04-01
2026-11-05 22:05:31 +09:00
DongHyeonka 05330e30a8 fix(realtime)!: 던지는 poll execute를 서버 장애가 아니라 PROTOCOL_MISMATCH로 끝낸다
문제: bounded poll은 `execute`의 throw를 PROVIDER_UNAVAILABLE/retryable로
바꿔 lease 안에서 다시 부른다(af00067). 설계 9.2가 권하는 조합은
`execute` 안에서 V3 실행기를 부르는 것이고, 실행기는 fetch 거절을 던지지
않고 NETWORK_FAILURE 결과로 돌려준다. 그래서 그 조합에서 throw는 결과
매핑·디코딩 같은 조합 코드 결함이다. 지금은 그 결함이 maxAttempts번의
요청과 ATTEMPT_FINISHED: PROVIDER_UNAVAILABLE, 끝으로
POLL_BUDGET_EXHAUSTED가 되어 서버 장애로 보인다. 원인 예외는 남지 않는다.

고른 방법: 리뷰 04-02의 선택지 (b). throw를 모양이 틀린 결과와 같은
계약 위반으로 본다. coordinator는 이미 `parseAttemptResult`가 거절한
결과를 재시도 없이 PROTOCOL_MISMATCH로 끝낸다. throw도 그 길로 보낸다.
lease 자신의 abort로 생긴 throw는 지금처럼 abort의 이유(ABORTED,
OFFLINE, 예산 소진 등)로 끝난다. `execute` 타입 주석, 설계 9.2와 13.1의
PROVIDER_UNAVAILABLE·PROTOCOL_MISMATCH 행을 같이 고쳤다.
버린 대안:
- (c) 주석과 13.1에만 "throw는 서버 장애로 재시도된다"를 적기. 완료
  기준은 "결과를 보고 조합 결함과 서버 장애를 구분한다"인데, (c)는 읽는
  사람만 알고 결과는 그대로라 구분할 수 없다.
- 관측에 throw 표시 칸을 더하기. 닫힌 관측 어휘를 넓히고, 결과 kind는
  여전히 서버 장애다.

위험·한계:
- 배럴로 공개된 bounded poll의 결과가 바뀐다. repo 안 소비자는 테스트뿐이다.
- `fetch`를 직접 부르는 조합은 네트워크 실패를 결과로 바꾸지 않으면 첫
  거절에서 lease가 끝난다. 설계가 권하지 않는 조합이고, 타입 주석과
  9.2가 "실패도 결과로 돌려준다"를 적는다.
- reconnect coordinator는 던지는 `attempt`를 계속 PROVIDER_UNAVAILABLE로
  재시도한다. 그쪽 attempt는 브라우저 연결 API를 감싸는 자리라 이번
  범위 밖이다.
- CHANGELOG.md 미출시 [계약] 행의 "poll은 던지는 execute도 lease 안에서
  다시 시도한다"는 이 커밋과 맞지 않는다. CHANGELOG는 오케스트레이터가
  고친다.

검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/unit/realtime/
- RED: "ends the lease with PROTOCOL_MISMATCH for an async execute that
  rejects"·"... throws before returning"가 옛 코드에서 execute 3회,
  POLL_BUDGET_EXHAUSTED로 실패한다. "keeps ABORTED ..."는 양쪽에서 통과한다
  (보존 조건).

BREAKING CHANGE: createBoundedPollCoordinator의 `execute`가 던지면(abort로
생긴 것 제외) 재시도 없이 PROTOCOL_MISMATCH(retryable: false)로 lease가
끝난다. 전에는 PROVIDER_UNAVAILABLE로 maxAttempts까지 재시도했다.
네트워크 실패를 throw로 내던 `execute`는 그것을 retryable
PROVIDER_UNAVAILABLE 결과로 바꿔 돌려준다.

Refs: 1105/04-02
2026-11-05 22:03:56 +09:00
DongHyeonka bde7fa4609 test(realtime): 조합 transport의 OFFLINE 재시도 규칙을 테스트로 다시 막는다
문제: 0929/04-01 규칙은 "환경이 online이면 transport가 낸 OFFLINE도
online 이벤트를 기다리지 않고 backoff로 재시도한다"이다
(reconnect-coordinator.ts의 RealtimeReconnectEnvironment 주석, 설계 5.3).
이 규칙을 막던 두 테스트는 SSE fetch·reader 거절이 OFFLINE이던 것을
이용했다. af00067(1103/04-04)이 SSE 거절을 PROVIDER_UNAVAILABLE로 바꾼 뒤
두 테스트는 그 kind의 재시도만 본다. 4d27b20이 지운 requireOnline() 두
줄을 되살리는 변이(MR1)에서 realtime 테스트가 모두 통과했다(리뷰 04-R4).

고른 방법: 조합 코드가 만든 transport로 그 경로를 직접 지나는 테스트
둘을 더한다. 환경은 계속 online이다.
- attempt가 OFFLINE/CONNECT/retryable로 실패한다 → 3회 시도, backoff
  [50, 100], OFFLINE retryable로 끝난다. 관측 순서도 고정한다.
- 세션이 열린 뒤 OFFLINE/RECEIVE/retryable로 닫힌다 → 3회 시도,
  OFFLINE retryable로 끝난다.
리뷰 대조 C1·C2와 같은 입력이고, `as never` 없이 파일의 도우미를 쓴다.
버린 대안: SSE 테스트 기대값을 OFFLINE으로 되돌리기. 템플릿 SSE는 이제
OFFLINE을 내지 않으므로 실제 동작과 다른 테스트가 된다.

위험·한계: 테스트만 더했다. 동작은 바뀌지 않는다. 그래서 RED(부모
코드)에서도 이 테스트는 통과한다. 결함을 보이는 방법은 변이 MR1이다.

검증: desktop batch에서 확인.
- GREEN: node scripts/run-vitest.ts run tests/unit/realtime/
- 변이 MR1(reconnect-coordinator.ts의 두 retry 분기 뒤 OFFLINE이면
  requireOnline()): 새 두 테스트가 attempts 1, result null로 실패해야 한다

Refs: 1105/04-01
2026-11-05 22:01:01 +09:00
DongHyeonka dae44f5cf4 test(http): interaction signal listener 정리도 고정한다
문제
실행기는 호출자·interaction·scope 세 signal에 abort listener를 달고
끝날 때 셋을 모두 지운다(src/adapters/http/http-execution-v3.ts:662-664).
listener 정리 테스트는 호출자와 scope signal만 감시해서, interaction
signal 쪽 제거 줄(:663)을 지운 변이 R2b가 107파일 995개를 모두
통과했다. 한 interaction 안에서 요청을 여러 번 보내면 요청마다
listener 하나(lifetime controller를 잡은 closure)가 interaction
마감까지 남는다.

고른 방법과 버린 대안
- 같은 테스트(tests/unit/http-execution-v3.test.ts)에
  createExecutionContext로 만든 interaction을 넘기고, 그
  cancellation.signal도 감시 목록에 넣는다.
- 끝나는 경우에 "interaction cancel"을 더한다. interaction 취소는
  호출자 abort와 같은 forwarder를 타지만 listener를 단 signal이 달라서
  따로 본다.
- 별도 테스트를 새로 만드는 안은 버렸다. 세 signal은 같은 정리 함수가
  지우므로 한 테스트에서 함께 보는 편이 규칙과 맞다.

위험·한계
- 테스트만 바꿨다. 실행기 코드는 그대로다. 실제 누수량은 재지 않는다.

검증
- desktop batch에서 확인:
  node scripts/run-vitest.ts run tests/unit/http-execution-v3.test.ts
- 변이 R2b(:663 제거)를 넣으면 세 경우 모두 "removes the listeners it
  added to the caller, interaction and scope signals after …"가
  실패해야 한다.

Refs: 1105/10-02
2026-11-05 21:58:39 +09:00
DongHyeonka ee37dd86a2 fix(test): capability 파일·다운로드 테스트의 버튼을 앱 위 고정 층에 둔다
문제: FE-GATE-008의 test:browser-capabilities가 firefox에서 가끔 30초 시간
초과로 떨어졌다. browser-files.spec.ts의 두 test가 번갈아 걸렸다. 하나는
"filechooser"를, 다른 하나는 "download"를 기다리다 끝났다. desktop에서
firefox capability suite를 30회씩 돌리면 두 test 60건 중 3건이 떨어졌다(두
번 모두). 부하와는 상관없었다(1.05에서도 남). 리뷰 14.7절은 이것을 "알려진
flake"로 두었다(1103/11-10).

원인: 두 test는 `goto("/")` 직후 label·input·button을 `<body>` 끝, 앱 root
뒤에 붙이고 그 button을 누른다. 그때 앱은 아직 그리는 중이다. 실패한 6건의
event 기록(진단 branch, 커밋 안 함)은 모두 같았다.
- pointerdown·mousedown은 button("Choose test file"/"Download generated").
- 30~45 ms 뒤 pointerup·mouseup은 홈 화면 내용("프로젝트 시작점…").
- click은 둘의 공통 조상(앱 root)이라 button의 handler가 돌지 않았다
  (`__browserFileResult` 없음). 그래서 picker도 download도 없었다.
- 위치까지 적은 3건에서 그 사이 scrollY는 24로 같았다. body 높이는 744에서 756으로, button top은
  696에서 708로 둘 다 12 px 늘었다. 앱 내용이 클릭 도중 12 px 자랐고,
  viewport 아래 끝의 button 중앙 좌표가 button 밖이 됐다. 통과한 run은
  pointerdown 때 이미 756이었다.

고른 방법: 두 test가 붙이는 control을 `position: fixed` 층(왼쪽 위, 가장
높은 z-index)에 둔다. 앱의 흐름 밖이라 앱이 늦게 그려도 button이 움직이지
않는다. 제품 코드는 바꾸지 않는다.

버린 대안:
- 앱이 다 그려질 때까지 기다린다. "다 그려짐"을 정할 신호가 없다. 늦게 오는
  글꼴이나 내용이 생기면 다시 깨진다.
- `dispatchEvent("click")`이나 `force` click. 신뢰된 사용자 입력이 아니어서
  firefox가 file picker를 열지 않는다. test가 증명하려는 것을 지운다.
- 재시도·timeout 늘리기·worker 줄이기. 금지된 우회이고 원인이 남는다.

위험·한계: 고정 층이 앱 header 왼쪽 위를 덮는다. 두 test는 앱 UI를 누르지
않는다. 다른 capability spec은 body에 control을 붙이지 않는다(grep).

검증 (desktop):
- RED(커밋 안 한 재현): mousedown 때 앱 root에 400 px를 더하고 layout을
  다시 계산한다(앱이 늦게 그리는 것과 같은 일). 수정 전 spec은 세 엔진 두
  test 6/6 실패(filechooser·download 대기 시간 초과).
- GREEN: 같은 재현에서 수정 뒤 6/6 통과.
- 실제 조건 firefox capability suite ×30: 수정 전 두 번 다 3 failed /
  657 passed, 수정 뒤 660 passed.
2026-11-05 09:51:10 +09:00
DongHyeonka aad005cbce fix(test): 브라우저 테스트가 WebKit의 3초 preload 추정 대신 실제 사용을 검사한다
문제: FE-GATE-008이 webkit에서 가끔 "The resource … was preloaded using
link preload but not used within a few seconds from the window's load
event" 경고로 떨어졌다(desktop 부하 0.68, i18n.spec.ts:60, 반복 10회 중
3회). 부하 탓이 아니었다. WebKit은 load 3초 뒤 한 번, 아직 아무 요청도 쓰지
않은 preload를 경고한다. 플랫폼 구성 화면은 들어갈 때 기능 실행부를 모두
불러오고(15-01), Vite는 그 청크와 정적 의존 청크를 한꺼번에 modulepreload
한다. 화면을 load 뒤 2.5초쯤 열면 module graph가 가장 깊은
reference-schemas에 닿기 전에 WebKit 검사가 돈다. 그 청크는 곧 쓰인다(표가
그려지고 link로 한 번만 받는다). 반대로 정말 안 쓰는 preload는 Chromium·
Firefox에서 늘, WebKit에서도 test가 3초 전에 끝나면 아무도 잡지 않았다
(1103/11-09).

고른 방법:
- strict fixture가 WebKit의 그 문구 하나만 정확한 패턴으로 무시한다. 다른
  console warning·error는 그대로 실패다.
- 대신 tests/support/browser/preload-use.ts가 세 엔진에서 같은 방법으로
  "preload한 script가 실제로 실행됐는가"를 본다.
  - 문서가 받은 `<link rel=modulepreload|preload>`를 첫 바이트 전부터
    MutationObserver로 적고, 끝에 남은 link도 더한다.
  - page.route로 build script(`/assets/*.js`)에 "이 URL이 평가됐다"를 적는
    문장 하나를 앞에 붙인다.
  - test 끝에 preload됐는데 평가되지 않은 script를 `preloadunused:`로
    실패시킨다. 진행 중인 dynamic import는 5초까지 기다린다.
- "사용"을 평가로 판정하는 이유: preload는 받기만 하거나(WebKit·Firefox)
  받아서 parse만 한다(Chromium). 어느 엔진도 평가하지 않는다. 그래서 그
  문장은 module graph가 그 청크를 실제로 실행했을 때만 돈다. WebKit의
  "참조됨"과 달리 시각에 기대지 않는다.
- 볼 수 없는 것은 따로 이름을 붙여 실패시킨다(fail closed).
  - script가 아닌 preload는 `preloadunverifiable:<as>:`.
  - Service Worker가 문서를 제어할 때 만든 preload는
    `preloadunverifiable:service-worker:`. 그 요청은 worker가 답해서
    page.route가 못 본다. context.route로 worker가 받는 것을 표시하면
    release manifest의 sha256 대조가 깨진다.
  - route.fetch가 세 번 실패해 표시 없이 넘어간 script는
    `preloadunverifiable:unmarked:`. 처음 구현은 이때 조용히
    route.continue()로 넘겨 쓰인 청크를 안 쓴 것으로 보고했다(webkit
    reference-form 1건).
- 일부러 실패를 일으키는 spec은 그 실패가 남기는 preload만 허용한다.
  - boot-module-failure: 깨진 build의 boot 정적 closure.
  - old-tab-chunk-recovery: 없어진 청크와 함께 preload된 청크. 전에는 이
    허용이 WebKit 경고 문구로만 있었다.
  - service-worker-update: worker 제어 중 preload만.
  - production-csp는 build script를 직접 fulfill하므로, 표시를 유지하는
    fulfillBuildScript를 쓴다.

버린 대안:
- (A) lazy dynamic import의 JS 의존성 preload를 끈다. 경고는 원리상 없어지지만
  test의 추정에 맞춰 제품을 바꾸는 것이다. lazy 라우트 첫 진입마다 1~2 RTT가
  늘고, 그 화면은 lab이 재는 화면(FE-GATE-026)이다.
- 청크 단계를 줄인다. 창이 좁아질 뿐이다.
- 3초 뒤에 화면에 들어간다. 사용자가 보는 경고를 test에서 숨긴다.

위험·한계:
- 모든 strict fixture test가 build script를 page.route로 받는다.
- 끝에 열려 있는 문서만 검사한다. 이동해 버린 문서의 기록은 같이 사라진다.
- fixture가 검사하는 것은 fixture의 page 하나다(console 검사와 같다).
- worker가 제어하는 문서의 preload는 검사하지 못한다(이름을 붙여 실패,
  service-worker-update만 허용).

검증 (desktop, CI=true와 workflow env):
- RED(검사 stub): 새 preload-use.spec 9건 중 7건 실패.
  - 변이 test는 세 엔진 모두 Expected
    ["preloadunused:/assets/async-state-Cxfod8c-.js"], Received [].
  - 부모 청크 3.5초 지연 scenario는 webkit만 "console:warning:The resource
    …/reference-schemas-DICBcHlO.js was preloaded using link preload but not
    used …"로 실패.
- GREEN: 9 passed.
- 변이를 fixture에 직접 넣은 probe(커밋 안 함), 안 쓰는 modulepreload 하나:
  - 이전 fixture(8a3b16a): chromium·firefox·webkit 3/3 통과(놓침).
  - 새 fixture: 3/3 실패,
    "preloadunused:/assets/async-state-Cxfod8c-.js".
- 부모 청크 3.5초 지연 probe:
  - 이전 fixture: webkit 실패.
  - 새 fixture: 3/3 통과. webkit은 여전히 reference-schemas 경고를 냈다
    (probe guesses ["reference-schemas-DICBcHlO.js was preloa…"]).
- 전체 e2e(playwright.config.ts): 202 passed, 3 skipped(기존 firefox SW skip).
- check:types:test, 바꾼 파일 eslint 통과.
2026-11-05 08:13:56 +09:00
DongHyeonka b693600103 fix(ci): 테스트가 만드는 로컬 빌드는 CI=true에서도 release 빌드로 검사되지 않는다
문제
workflow는 모든 job에 CI=true와 CI 빌드 식별값을 준다. 메인 세션이 깨끗한
clone에서 그 env 그대로(CI=true 포함) merge 단계 14개를 돌리자 FE-GATE-005·
008·020이 실패했다.
- vitest 안의 fixture 빌드(tests/e2e/support/fixture-builds.ts →
  build-frontend.ts)가 CI=true를 물려받아 release 빌드처럼 검사된다.
  af312de가 vitest에서 VITE_COMMIT_SHA를 지워 "missing required CI build
  environment: VITE_COMMIT_SHA"로 멈춘다(service-worker-build-output 7건이
  돌지 않음, 제거 드릴 안에서도 같다).
- 시각 골든 build(9bddfa5)가 VITE_COMMIT_SHA="local"을 받는데 CI=true가
  40·64자리 hex를 요구해 webServer가 뜨지 않는다.
내 X4가 CI=true 없이 돌아 놓쳤다. 1103/11-07과 같은 원인이다.

고른 방법
- scripts/lib/build-environment.ts에 둘을 둔다.
  - localBuildEnvironment(env): spawn하는 로컬 빌드용. CI와 CI 빌드 식별값을
    뺀 사본. fixture-builds.ts, service-worker-builds.ts가 쓴다.
  - LOCAL_BUILD_IDENTITY: Playwright web server용. Playwright가 env를
    process.env 위에 합치므로 CI를 지우지 않고 ""로 덮는다(검사는
    CI === "true"일 때만). visual·capabilities·dev 설정이 쓴다.
- assertCiBuildEnvironment의 CI=true 검사는 그대로다. job 자신의 release
  빌드(build:release-candidate 등)는 계속 검사된다.
- 버린 대안: 로컬 빌드에 유효한 가짜 커밋 id(0×40)를 주기. CI=true 검사의
  다른 칸(CI_RUNNER_IMAGE, SOURCE_DATE_EPOCH)도 함께 맞춰야 하고, 로컬
  빌드가 release 빌드인 척한다.

위험·한계
- 로컬 빌드 안에서 CI를 읽어 동작을 바꾸는 코드가 있으면 그 빌드는 이제
  CI가 아닌 쪽으로 돈다(지금은 build-environment 검사뿐이다).

검증
- tests/unit/local-build-environment.test.ts 3건: 구현 전 2건 실패(RED),
  CI job 자체 검사는 유지.
- CI=true·VITE_COMMIT_SHA·VITE_BUILD_ID=gitea-41-1·RELEASE_ID·
  CI_RUNNER_IMAGE·SOURCE_DATE_EPOCH로: service-worker-build-output 7건,
  test:visual 6/6, test:unit 2,883, test:component 270, test:integration 189
  통과. 수정 전 service-worker-build-output은 7건 미실행.
- check:types, lint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/README.md 13절 11-08
2026-11-05 04:26:44 +09:00
DongHyeonka 799ab7f667 fix(dev): dev manifest를 기능 생성·제거 때 다시 쓰는 커밋 파일로 둔다
문제
c15345c·db5728b·0eba082의 dev 전용 Vite 미들웨어(dev server가 설치된
기능의 contract set으로 manifest를 냄)를 넣은 뒤로, dev server를 쓰는
capability e2e가 "requestfailed:GET:/release-manifest.json:net::ERR_ABORTED"로
떨어졌다. 같은 호스트에서 번갈아 쟀다: 미들웨어 있음 5/30·2/30 실패, 없음
0/30·0/30(부하가 더 높았다). trace에서는 첫 manifest 요청이 200 헤더 뒤
끊기고 65 ms 뒤 두 번째 요청이 성공한다. 원인을 끝까지 좁히지는 못했다.
감시 이벤트(파일 쓰기)를 없애도 같았다.

고른 방법
- 미들웨어를 지운다. dev server는 커밋된 public/release-manifest.json을
  그대로 낸다.
- 그 파일의 contractSet을 설치된 기능으로 다시 쓰는 일을 명시적 단계로
  둔다: `create:feature`가 생성 뒤 scripts/write-dev-release-manifest.ts를
  돌리고, 기능 제거 드릴이 지운 뒤 돌린다. 매뉴얼의 되돌리기·기능 지우기
  절과 errors.md에 같은 명령을 적었다. 레지스트리 기준선과 같은 방식이다.
- tests/unit/dev-release-manifest.test.ts가 커밋된 파일이 설치된 기능의
  contract set과 같은지 보고, 다르면 다시 쓰는 명령을 말한다.
- 함께: vite.config.ts가 artifacts/·dist/·.tmp/를 감시하지 않는다.
  Playwright trace의 .html이 열린 페이지를 모두 다시 불러오게 했다(dev
  server 로그의 page reload).
- 버린 대안: dev 부팅에서 contract set 검사 건너뛰기. 검사하는 테스트와
  같은 조건을 dev만 따로 두게 된다.

위험·한계
- 기능을 손으로 지우고 명령을 잊으면 dev server가 부팅하지 못한다.
  test:unit이 그 상태를 이름과 명령으로 알린다.

검증
- test:unit 2,880건, dev-release-manifest·create-feature 테스트 45건,
  check:types, lint, verify:documentation 통과.
- 생성 기능을 넣은 clone의 dev capability e2e와 merge 단계 14개는 이 커밋
  뒤 깨끗한 clone에서 돈다.

Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.5 14.6 X2 #3, 16-09
2026-11-05 03:30:56 +09:00
DongHyeonka 0eba0821bd fix(dev): dev release manifest를 파일로 쓰지 않고 메모리에서 낸다
문제
깨끗한 clone의 FE-GATE-008에서 dev server를 쓰는 capability e2e가
"requestfailed:GET:/release-manifest.json:net::ERR_ABORTED"로 1~4건씩
떨어졌다(세 번 중 세 번, 부하 9~30). 플러그인(db5728b)이 dev server 시작
때 .generated/frontend-runtime/에 manifest를 쓰는데, polling 감시
(CHOKIDAR_USEPOLLING=1)가 그 새 파일을 서버가 뜬 뒤에 보고 부팅 중인 페이지를
다시 불러오면 진행 중인 manifest 요청이 끊긴다고 본다. 플러그인을 넣기 전
같은 부하의 회차들은 66건 모두 통과했다.

고른 방법
- 자식 프로세스가 manifest를 stdout으로 내고, 플러그인은 그 문자열을
  메모리에 두고 낸다. 파일을 쓰지 않으므로 감시가 볼 것이 없다.
  devReleaseManifest(source)가 문자열을 돌려준다.

위험·한계
- 원인을 감시 이벤트로 직접 관측하지는 않았다(추론). 수정 뒤 재실행으로
  확인한다.

검증
- tests/unit/dev-release-manifest.test.ts 2건, check:types, lint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.5 X4
2026-11-05 03:12:27 +09:00
DongHyeonka 8b382aa64f test(dev): dev release manifest 테스트가 설치된 기능에 기대지 않는다
문제
dev-release-manifest 테스트의 둘째 경우가 생성 결과를 커밋된 자리표시자와
통째로 비교한다. 템플릿 기능만 있으면 같지만, 기능을 더한 제품이나 생성
기능을 넣은 제거 드릴 fixture에서는 contract set이 달라 실패한다. 깨끗한
clone의 FE-GATE-020(test:sample-removal 안의 test:unit)에서 떨어졌다. 이
리뷰가 여러 번 고친 "템플릿 그대로일 때만 맞는 테스트"와 같은 결함을 새로
만들었다.

고른 방법
- 둘째 경우는 contract set을 뺀 나머지 칸이 자리표시자와 같고, contract
  set이 설치된 기능의 buildContractSet()과 같은지 본다.

검증
- 테스트 2건, eslint, check:types 통과.

Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.6 X2 #3
2026-11-05 01:52:53 +09:00
DongHyeonka 7f9a515dd9 fix(build): 빌드 복사본 입력 목록에 dev release-manifest 플러그인을 더한다
문제
c15345c가 vite.config.ts에서 scripts/lib/dev-release-manifest.ts를
import한다. 초기 JS를 재는 measure-feature-shape-growth.ts와
product-feature-selection-build 테스트는 빌드할 복사본에 정해진 파일만
복사하는데(BUILD_INPUTS), 그 목록에 새 파일이 없다. 그래서 복사본의 vite
build가 "Could not resolve './scripts/lib/dev-release-manifest.ts'"로 실패해
test:unit 두 파일과 세 capability 제거 드릴이 떨어졌다. c15345c 뒤에
test:unit 전체를 돌리지 않아 놓쳤다.

고른 방법
- 두 BUILD_INPUTS에 그 파일을 더한다.
- 두 목록이 같은 내용의 사본이다. 하나로 합치는 것은 이 수정의 범위 밖으로
  둔다(남은 문제).

검증
- test:unit 193파일 2,880건 통과, lint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.6 X2 #3
2026-11-05 01:39:22 +09:00
DongHyeonka 235143c5ba test(features): 제품 확장 타입 검사 탐침이 제품 이름·파일·제거 상태와 겹치지 않는다
문제
tests/unit/product-extension-typecheck.test.ts(1103/09-02)는 복사본에 제품
파일과 기능 하나를 넣고 tsc 세 프로그램을 돈다. 세 가지가 제품과
제거 드릴에서 깨진다(리뷰 조치 X2 #1, #7).
- 탐침 ID가 notice-feature·notice-context다. 매뉴얼 예시가 모두 "공지"라
  제품이 같은 ID를 쓰면 FE-GATE-005가 원인을 말하지 않는 TS 오류 약
  20줄로 실패한다.
- product-capabilities.ts가 템플릿의 빈 선언 그대로여야 한다고 단언하고
  그 선언을 바꿔 쓴다. 자기 capability를 적은 제품에서 실패한다.
- 복사 대상을 모두 복사한다. test:optional-recipe-removal의 fixture에는
  recipes/가 없어 ENOENT로 떨어진다.

고른 방법
- 탐침 이름을 typecheck-probe-*(capability typecheckProbeSettings, 설정 키
  TYPECHECK_PROBE_PAGE_SIZE)로 바꾸고, 그 기능 폴더가 이미 있으면 이름을
  말하며 실패한다.
- capability 타입은 제품 파일 끝에 같은 이름 interface로 덧붙인다.
  TypeScript가 합치므로 제품의 선언이 남는다.
- 없는 복사 대상은 건너뛴다.

위험·한계
- product-contracts.ts·product-composition.ts는 여전히 탐침 내용으로 바꿔
  쓴다. 제품 기능이 이 두 파일의 이름 있는 export를 import하면 복사본에서
  타입 오류가 날 수 있다.

검증
- 테스트 통과, eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-02, README.md 14.6 X2
2026-11-05 01:33:38 +09:00
DongHyeonka c15345cb1d fix(dev): dev server가 설치된 기능의 contract set으로 release manifest를 낸다
문제
`create:feature`가 만든 기능은 계약 패키지(`@org-contracts/<base>`)를
선언한다. dev server는 커밋된 자리표시자 public/release-manifest.json을
그대로 내주는데, 그 contractSet.packages는 고정된 빈 목록이다. 부팅이 이
집합을 설치된 선언과 대조하므로, 기능을 생성한 직후 `corepack pnpm dev`가
CONTRACT_SET_PACKAGE_MISSING으로 "애플리케이션을 시작할 수 없습니다"를
보인다. 같은 이유로 dev server를 쓰는 FE-GATE-008의
test:browser-capabilities가 38건 실패하고("Execution context was
destroyed"), 매뉴얼에는 이 파일을 고치라는 말이 없다. 매뉴얼만으로 기능을
더하는 재실험(리뷰 조치 X2 #3)에서 찾았다.

고른 방법
- dev 전용 Vite 플러그인(scripts/lib/dev-release-manifest.ts)이 dev server를
  시작할 때 scripts/write-dev-release-manifest.ts를 자식 프로세스로 돌려
  src/.generated/dev-release-manifest.json(무시되는 생성물)을 쓰고,
  `/release-manifest.json` 요청에 그것을 낸다. 내용은 자리표시자에
  설치된 기능의 contract set(build와 같은 buildContractSet)을 넣은 것이다.
- 자식 프로세스로 돌리는 이유: contract set을 만들려면 설치된 기능 선언을
  import해야 하는데, Vite 설정이 그것을 불러오면 안 된다.
- build는 바뀌지 않는다. 빌드 manifest는 generate-build-manifest.ts가 만든다.
- 버린 대안: dev 자리표시자에서 contractSet을 빼기. V2 manifest 스키마가
  contractSet을 요구한다. 생성기가 추적 파일(public/release-manifest.json)을
  다시 쓰기: 기능 선택이 바뀌는 실행마다 추적 파일이 바뀐다.

위험·한계
- dev server를 켠 뒤 기능을 더하거나 지우면 dev server를 다시 켜야 한다.
- 자리표시자의 routeChunks는 여전히 손으로 둔다(부팅이 dev에서 보지 않는다).

검증
- tests/unit/dev-release-manifest.test.ts 2건(낡은 집합을 설치된 집합으로
  바꾼다, 템플릿 그대로면 자리표시자와 같다).
- check:types, lint, check:architecture, check:ci 통과.
- 생성 기능을 더한 깨끗한 clone의 capability 실행은 X4 재실행에서 본다.

Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.6 X2 #3
2026-11-05 01:33:38 +09:00
DongHyeonka 5ca5340e11 fix(removal): 샘플 제거 뒤 남는 파일에 샘플 ID 글자를 쓰지 않는다
문제
test:sample-removal의 잔여 검사(REFERENCE_RESOURCE|reference-feature|
reference-resource)가 샘플을 지운 fixture에서 두 파일을 잡아 FE-GATE-020이
실패한다. tests/unit/hosting-probe.test.ts는 비상 스위치 예시로
FEATURE_OVERRIDES에 "reference-feature"를 쓰고(13-01), platform-examples-
context의 머리 주석은 참조 context 경로를 적는다(09-04).

고른 방법
- 테스트 값을 "platform-examples-feature"로 바꾸고, 주석은 샘플 이름 없이
  적는다. 동작은 바뀌지 않는다.

검증
- tests/unit/hosting-probe.test.ts 37건, lint 통과. 제거 드릴은 X4 재실행에서
  확인한다.

Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.5
2026-11-05 01:26:27 +09:00
DongHyeonka f92cfd9a98 test(storybook): workshop spec이 a11y 애드온 자동 검사와 겹치지 않는다
문제
깨끗한 clone의 FE-GATE-008에서 test:storybook이 "Axe is already running"으로
떨어졌고, 이 worktree에서도 두 번에 한 번 떨어진다. @storybook/addon-a11y
10.6.5(13-03이 올린 판)는 story를 그린 뒤 afterEach에서 axe를 스스로 돌린다
(globals.a11y.manual이 true가 아니면). spec의 AxeBuilder.analyze()는 그 페이지의
같은 axe 인스턴스를 쓰므로, 두 실행이 겹치면 두 번째가 거절된다.

고른 방법
- spec이 story를 `globals=a11y.manual:!true`로 연다. 애드온은 자동 검사를
  건너뛰고, 접근성 판정은 지금처럼 spec의 AxeBuilder가 한다.
- 버린 대안: 애드온 실행이 끝나길 axe 내부 상태로 기다리기. 공개 API가
  아니고, 애드온 실행이 시작되기 전에 확인하면 여전히 겹친다.
- 버린 대안: preview 전체에서 애드온 자동 검사 끄기. workshop에서 쓰는
  사람이 패널 결과를 잃는다.

위험·한계
- 이 spec만 바꿨다. 다른 storybook spec이 생기면 같은 URL을 쓴다.

검증
- test:storybook 5회 연속 통과(heavy lock). 수정 전 2회 중 1회 실패.

Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.5
2026-11-05 00:50:44 +09:00
DongHyeonka 41f8801d64 chore(review): 1103 기능 생성기·기능 패턴 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 03-07 09-06 16-01 16-04~16-07

# Conflicts:
#	docs/manual/01-add-a-feature.md
#	docs/manual/reference/create-feature.md
#	docs/manual/reference/patterns.md
#	scripts/create-feature.ts
#	scripts/test-feature-scaffold.ts
2026-11-04 23:49:27 +09:00
DongHyeonka e8c4197e0b test(reference): 참조 context 라우팅 테스트가 참조 기능의 라우트만 본다
문제
`create:feature <id> --context reference-context`로 기능을 참조 context에
넣으면 tests/features/reference-feature/installed-context-routing.test.ts가
실패한다. 그 테스트가 참조 context가 적재하는 라우트 전체를 정확히 비교하기
때문이다. 매뉴얼은 이것을 "못 잡음"으로 두고 참조 context에 넣지 말라고만
적었다(메인 세션 X1).

고른 방법
비교 대상을 참조 기능 계약의 route ID로 거른다. 테스트의 의도(참조 기능
라우트가 공개 URL 그대로 지연 적재된다)는 그대로다. 매뉴얼 01 1단계와
reference/create-feature.md의 한계 문장을 고쳤다. 생성한 context 선언을
실행하는 테스트는 앞 커밋(tests/unit/create-feature.test.ts)에 있다.

버린 대안
- 생성 명령이 reference-context를 거부: 생성기가 샘플 이름을 알게 되고, 테스트
  가정 하나를 지키려고 정상 입력을 막는다.

위험·한계
- 참조 context에 넣은 기능은 경로가 /examples/reference-resources/<base>다.
  참조 기능을 지우면 context가 남아 제거 드릴 잔여 검사에 걸린다고 매뉴얼에
  적었다. 이 경로의 드릴은 돌리지 않았다(추론).

검증
- RED: refx-feature --context reference-context --with-create를 만든 상태에서
  이 테스트가 XONE/REFX 라우트를 받아 실패(앞 커밋 검증 기록). 고친 뒤 같은
  상태에서 tests/features 124건 통과, tests/component·architecture와
  create-feature·schema-metadata-policy 49파일 374건 통과. 생성 기능은 지웠다.
- lint, check:types(test), verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 1101/16-02
2026-11-04 23:42:06 +09:00
DongHyeonka 2ec9d56008 feat(scaffold): create:feature --with-create가 짝 백엔드 생성기와 같은 slice를 만든다
문제
- 프론트 create:feature는 GET /api/<base>-items 목록 하나를 만든다. 짝 백엔드
  new-feature.sh는 POST /<plural>(201, NOT_IDEMPOTENT)과 GET /<plural>/{id}를
  만든다. 경로 규칙도, operation 쌍도 맞지 않는다(03-07).
- 짝 백엔드 모양(Envelope)의 상세 GET·작성 POST·폼·결과 불명 화면 예제는
  참조 기능뿐이고, 참조 기능은 problem details 모양이라 옮기면 짝 백엔드에서
  쓰이지 않는 분기와 값(400·422 분류, retryBudget 0, Envelope 줄 없음)을
  함께 옮긴다(09-06, 16 5.3절).
- 생성된 목록의 "총 N개"는 배열 길이다. 백엔드 meta.page.total을 쓰지
  않는다(03-02 수정이 남긴 일).

고른 방법
- 경로: 백엔드 new-feature.sh와 같은 복수형 규칙(backendPathSegment)으로
  API_PATH 상수 하나를 둔다. 백엔드 api-base-path는 API_BASE_URL에 붙인다.
- 목록: mapper가 { items, total }을 내고 total은 page?.total ?? 길이다. 빈
  목록은 EmptySurface로 같은 빈 상태를 그린다.
- --with-create: 상세 GET, 작성 POST, 상세·작성 라우트와 페이지, 폼 스키마
  (이름 100자 = 백엔드 NAME_MAX_LENGTH), 뮤테이션 정책(commandMutationIdentity),
  작성 폼 테스트를 만든다. 작성은 백엔드 기본에 맞춰 NEVER(retryBudget 0, 키
  없음)다. --keyed는 백엔드 create를 IdempotencyExecutor 뒤에 둔 경우의
  KEYED 값(IDEMPOTENCY_REPLAY, retryBudget 1)을 쓴다.
- 작성 descriptor: acceptedStatuses [201], refusedBeforeWrite
  ["<BASE>_INVALID"], classifyStatus는 401·403·429를 NOT_APPLIED(백엔드
  보안 필터·@RequiresPermission 프록시·rate-limit interceptor가 use case 전에
  거절한다). mapProblem이 <BASE>_INVALID를 이름 칸 오류로 바꾼다.
- 생성 테스트: gateway 테스트가 세 operation의 백엔드 본문(201 Envelope,
  404 <BASE>_NOT_FOUND, 400 <BASE>_INVALID → NOT_APPLIED, 응답 유실 →
  MAYBE_APPLIED, NEVER는 키 없음·KEYED는 503 IDEMPOTENCY_UNAVAILABLE 뒤 같은 키
  1회 재전송)을 손으로 적는다. 하네스 재시도 상한은 앱 기본값 2다(16-07 (3)).
  작성 폼 테스트는 라우터를 거쳐 201 저장 뒤 상세 열기, 400 거절을 이름 칸에
  보이고 저장 버튼이 켜진 채 다시 저장, 응답 유실 뒤 결과 불명(NEVER는 다시
  보내기 없음, KEYED는 같은 Idempotency-Key로 다시 보내기)을 본다.
- 페이지 테스트의 앱 조립은 <base>-test-app.tsx 하나로 모은다.
- slice 템플릿은 scripts/create-feature-write-slice.ts에 둔다. 리뷰 5.3절
  재검토 조건(템플릿 2,000줄)을 넘지 않게 하고, create-feature.ts의 수정을
  필요한 자리로 좁힌다.
- X1: 생성한 context 선언을 임시 폴더에 써서 생성기 선언 읽기로 읽고, 그
  모듈을 import해 앱 모듈 조립(라우트 루트 검사)이 기능 라우트를 받는지 보는
  단위 테스트를 더한다.

버린 대안
- 작성을 기본 KEYED로: 백엔드 생성 create는 키를 읽지 않아, 같은 키 재전송이
  새 항목을 만든다. 안전해 보이는 거짓 보장이다.
- 참조 기능을 Envelope로 옮기기(09-06 (2)): 참조 테스트와 MSW fixture를 다수
  바꾸고 problem details 예제가 사라진다.
- 목록 값을 배열로 두고 total을 배열 속성으로 싣기: TanStack 구조 공유가 배열
  속성을 버린다.

위험·한계
- 백엔드 생성기는 목록 엔드포인트를 만들지 않는다. 백엔드에 GET 페이지 목록을
  더하기 전에는 생성 목록이 405를 받는다. descriptor 주석과 매뉴얼에 적었다.
- 생성 기능의 초기 JS: 기본 +647 B, --with-create +964 B(이 브랜치 기준선
  203,702 B에서 잰 값, 기능당 1 KiB 안). 기준선의 남은 여유는 1,098 B라
  --with-create 기능 하나를 넣으면 134 B가 남는다.
- 두 생성기를 실제로 띄워 붙여 보지는 않았다. 백엔드 템플릿의 응답 본문과
  경로를 읽어 생성 테스트에 옮겼다.

검증
- RED: tests/unit/create-feature.test.ts 새 17건 실패 → GREEN 43건 통과.
- 기본·--with-create·--with-create --keyed·--context reference-context
  --with-create 네 기능을 만든 상태에서: check:types(app·test·node), lint,
  check:registries(additive), check:i18n, check:architecture,
  check:design-system, check:diagnostics, verify:documentation 통과. 생성 기능
  테스트 77건 통과. 빠른 계층 313파일 3,818건 중 참조 라우팅 테스트 1건만
  실패(X1, 다음 커밋).
- 변이: refusedBeforeWrite 삭제 → gateway·폼 테스트 2건 실패. 상세 GET의
  responseEnvelope 삭제 → 조립 거절로 테스트와 check:registries 실패. KEYED
  retryBudget 0 → 503 재전송 테스트 실패. 정책의 descriptor 상수 오타 → tsc 실패.
- flock 아래 build, check:bundle: 기준 203,702, 기본 기능 204,349, --with-create
  기능 204,666 / 204,800 B PASS.

Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-06
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-07
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-01
2026-11-04 23:42:00 +09:00
DongHyeonka 3b40f73638 fix(contracts)!: 스키마 메타의 boundary를 쓰임과 대조하고 실패 본문 행을 둔다
문제
<base>-schema-metadata.ts의 boundary는 손으로 적고, check:registries는 값이
목록 안인지만 본다. 응답 스키마에 boundary "api-request"를 적어도 타입·
레지스트리·기능 테스트가 모두 통과한다(리뷰 E-4 세 번째 변이). direction과
unknownFieldPolicy는 07-03 수정(5bee9ab)이 검증기와 대조한다. 또 FE-REG-API의
problemSchema는 breaking 칸이지만 FE-REG-SCHEMA를 참조하지 않고, 참조 기능과
생성 뼈대에 실패 본문 스키마 행이 없다(07-01 (d)).

고른 방법
- schema-metadata-policy.test.ts에 boundary 대조를 더한다. 설치된 descriptor의
  입력·응답·실패 검증기와 라우트 paramsSchema·searchSchema에서 스키마마다
  쓰인 자리를 모으고, 그 조합에서 boundary를 정해 행과 비교한다. 쓰이는데
  행이 없는 스키마도 실패한다. direction·unknownFieldPolicy 검사는 실패
  검증기까지 넓힌다.
- boundary에 "api-problem"을 더한다(SchemaDefinition, governance
  allowedValues). FE-REG-API problemSchema → FE-REG-SCHEMA.schemaId 참조를
  governance에 더한다.
- 참조 기능 ReferenceProblem, 생성 뼈대 <Base>Problem, second-api fixture에
  실패 본문 행을 더한다.

버린 대안
- 메타 행을 descriptor·라우트에서 투영(16-04 권고 (b)): 메타 파일이 거의
  사라지지만 생성 뼈대·참조 기능·레지스트리 원본을 함께 바꾼다. 리뷰가
  "빠르게 막으려면 (c) 먼저"라고 적은 대조 테스트를 골랐다.
- owner를 기능 ID에서 검사: 정한 규칙이 없다(참조 기능 owner는
  "...-vertical-slice"). 그대로 둔다.

위험·한계
- governance 참조 추가는 FE-REG-API 계약 변경이라 기준선을 다시 찍었다
  (REGISTRY_BASELINE_REASON에 1103/16-04). 다른 브랜치 변경(FE-REG-TELEMETRY
  optionalAttributes)도 같은 스냅샷에 들어갔다. 오케스트레이터가 통합 뒤 다시
  찍는다.
- 다운스트림 기능은 실패 본문 행이 없으면 check:registries가 실패한다.
  CHANGELOG에 이행 안내가 필요하다.
- 대조 테스트는 설치된 기능만 본다. 기능을 더한 상태에서 test:unit을 돌릴 때
  잡힌다.

검증
- RED: 새 boundary 테스트가 "ReferenceProblem: no FE-REG-SCHEMA row"로 실패.
  행을 더한 뒤 통과.
- 변이: ReferenceResourcePayload boundary를 api-request로 바꾸면 "row
  api-request, used as api-response"로 실패. 되돌림.
- check:registries 실패(FE-REG-API references 변경) → 기준선 갱신 뒤 PASS
  compatibility=none.
- second-api-feature-registries, registry-governance, release-artifacts,
  create-feature 테스트 통과. check:types, lint, verify:documentation 통과.

BREAKING CHANGE: FE-REG-API problemSchema가 FE-REG-SCHEMA.schemaId를 참조한다.
설치된 기능의 problemValidator 스키마마다 <base>-schema-metadata.ts에
boundary "api-problem", direction "RESPONSE" 행이 없으면 check:registries가
"FE-REG-API.<operationId>.problemSchema references unknown FE-REG-SCHEMA"로
실패한다. 행을 더하고 레지스트리 기준선을 다시 찍는다.
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-04
Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-01
2026-11-04 23:35:33 +09:00
DongHyeonka 4401ffa1ac test(docs): 문서 검사 보고서 타입에 missingPaths 칸을 적는다
문제
직전 커밋(짝 저장소 참조 테스트 범위 축소)이 보고서의 missingPaths를
읽지만, 테스트가 JSON을 읽을 때 쓰는 타입에 그 칸이 없어 check:types가
TS2339로 실패한다. vitest는 타입을 보지 않아 테스트는 통과했다.

고른 방법
- 보고서 타입에 missingPaths?: string[]를 더한다.

검증
- check:types 통과, documentation-readiness 테스트 19건 통과, eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-05
2026-11-04 23:11:22 +09:00
DongHyeonka 505a8b0fca chore(review): 1103 release·CI·성능 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 12-07 13-01~13-03 13-05 15-02~15-07

# Conflicts:
#	docs/manual/03-outside-feature-folder.md
#	docs/operations/performance-evidence.md
#	scripts/lib/hosting-probe.ts
2026-11-04 23:10:59 +09:00
DongHyeonka e979c494b3 test(docs): 짝 저장소 참조 검사 테스트가 고친 문서만 본다
문제
fix/r1103-gates(12-05)의 테스트는 옆 checkout을 흉내 낸 stub(백엔드
문서 1개)을 두고 verify:documentation 전체가 통과하기를 기대한다. 다른
브랜치를 합치자 실제 문서(매뉴얼 02·04, 백엔드 계약 문서)가 stub에 없는
백엔드 경로를 가리켜, 테스트가 status 1로 실패한다. 결함은 문서가 아니라
테스트 범위에 있다. 그 경로 14개는 실제 옆 checkout에 모두 있다.

고른 방법
- "있는 경로" 경우에서 전체 status 대신, 테스트가 고친 문서
  (CI_DOC)에 빠진 경로가 없는지만 본다(stderr와 보고서 missingPaths).
- 버린 대안: stub에 실제 문서가 가리키는 백엔드 경로를 모두 만든다.
  문서가 바뀔 때마다 테스트도 같이 바뀌어야 한다.

위험·한계
- 다른 문서의 짝 저장소 경로가 틀리면 이 테스트로는 잡지 않는다. 실제
  옆 checkout이 있는 개발 환경의 verify:documentation이 잡는다.

검증
- tests/unit/documentation-readiness.test.ts 19건 통과.
- 실제 백엔드 checkout에서 문서가 가리키는 경로 14개 존재 확인.

Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-05
2026-11-04 23:10:24 +09:00
DongHyeonka fbd8f7d148 chore(review): 1103 게이트·드릴 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 02-06 11-06 12-09 10-01 11-03~11-05 12-02 12-04 12-05 12-08 14-04 16-02

# Conflicts:
#	docs/manual/01-add-a-feature.md
#	docs/manual/02-decision-tables.md
#	docs/manual/reference/patterns.md
2026-11-04 23:08:05 +09:00
DongHyeonka 83f4dd5f8e chore(review): 1103 예제 화면·시각·접근성 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 09-04 15-01 12-01 11-01 16-03 11-02

# Conflicts:
#	docs/architecture/frontend-application-foundation.md
#	docs/architecture/starter-experience.md
#	docs/manual/03-outside-feature-folder.md
#	tests/unit/runtime-adapters.test.ts
2026-11-04 23:04:17 +09:00
DongHyeonka 68f94f5e93 refactor(server-state): 아무도 읽지 않는 쿼리·뮤테이션 정의 칸을 선택 칸으로 둔다
문제
QueryDefinition의 owner·operationId와 BoundMutation의 owner는 필수 칸이다.
bindQuery가 돌려주는 객체에는 둘 다 없고, src 어디서도 읽지 않는다. 기능
작성자는 효과 없는 값을 매번 채우고, 매뉴얼은 그 오타를 "못 잡는 위험"으로
적어 오히려 신경 쓰게 한다(리뷰 16-06 ①②).

고른 방법
세 칸을 @deprecated 선택 칸으로 바꾼다. 참조 기능과 생성 뼈대는 더는
채우지 않는다. 요청 기록의 operation ID는 지금처럼 descriptor에서 온다.
매뉴얼 6·7단계와 patterns.md에 "적지 않는다"와, 라우트 계약 title·
navigationLabel을 무엇이 읽는지(FE-REG-ROUTE, lab 측정)를 적었다.

버린 대안
- 칸을 바로 지우기: 객체 리터럴의 초과 속성 검사로 테스트 3파일과
  다운스트림 정의가 컴파일 오류가 난다. 선택 칸으로 한 릴리스 두고 지운다.
- 쿼리 operationId를 진단 이름표로 잇기: HTTP 실행 기록이 이미 descriptor의
  operation ID를 싣는다. 같은 값을 두 번 싣는다.

위험·한계
- 라우트 계약의 title·navigationLabel(16-06 ③)은 그대로 둔다. 지우려면
  FE-REG-ROUTE 기준선 행을 catalog에서 만들고, 플랫폼 라우트와
  test-performance.ts를 함께 바꿔야 한다. 다른 작업(예제 화면 이동)과 같은
  파일이라 이번에는 문서로만 적었다.

검증
- RED: application-query-scope-fence 새 테스트가 tsconfig.test에서 owner·
  operationId 누락으로 타입 오류. 선택 칸으로 바꾼 뒤 통과.
- tests/features/reference-feature, tests/unit/create-feature.test.ts,
  scope-fence 129건 통과. check:types(app·node·test), lint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-06
2026-11-04 23:02:44 +09:00
DongHyeonka f59a806429 feat(server-state): 뮤테이션 정책이 operation ID와 키 여부를 descriptor에서 받는다
문제
BoundMutation의 operationId와 requiresIdempotencyKey는 기능이 손으로 다시
적는 자유 값이다. operationId에 오타가 있어도 check:types와
check:registries가 통과하고, 실행기는 intent의 operation ID가 descriptor와
다르다며 보내기 전에 거부한다(MISSING_IDEMPOTENCY_KEY 위반). 화면은 "요청을
처리할 수 없습니다"로 멈추고 원인을 말하지 않는다(리뷰 E-2). 1101/03-03이
같은 재기술을 적었다.

고른 방법
src/contracts/server-state.ts에 commandMutationIdentity(descriptor)를 둔다.
descriptor의 operationId와 retrySemantics === "KEYED"를 돌려주고, 정책은
이것을 펼쳐 쓴다. 상수 이름 오타는 tsc가 잡는다. GET·HEAD descriptor를
넘기면 바인딩 때 throw한다. 참조 기능의 생성 정책이 이것을 쓴다.

버린 대안
- BoundMutation.operationId를 brand 타입으로: 자유 문자열도 막지만 테스트
  약 27곳과 다운스트림 정책을 깨는 공개 타입 변경이다.
- 실행기 위반 이름을 INTENT_OPERATION_MISMATCH로 나누기: http 어댑터의 닫힌
  위반 어휘와 화면 매핑을 바꾼다. 값을 descriptor에서 받으면 그 경로에 닿지
  않으므로 미뤘다.
- 타입에서 method를 쓰기 method로 좁히기: InstalledHttpContract로 주석한
  descriptor(method: HttpMethod)가 모두 타입 오류가 나서 실행 때 검사만 둔다.

위험·한계
- 정책에 operationId 문자열을 직접 적는 길은 남는다. 매뉴얼 7단계 "못 잡음"에
  적었다.
- 참조 기능 presentation이 계약 기여 파일을 import한다. 두 파일 모두 지연
  청크라 초기 JS는 바뀌지 않는다(check:bundle은 다음 커밋들과 함께 잰다).

검증
- RED: tests/unit/command-mutation-identity.test.ts 4건이 함수 없음으로 실패.
  GREEN 뒤 통과.
- tests/features/reference-feature, tests/component/application-query.test.tsx
  125건 통과.
- check:types, check:architecture, lint, verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-05
2026-11-04 22:59:48 +09:00