Commit Graph
1022 Commits
Author SHA1 Message Date
DongHyeonka 703a33559f chore(review): 1105 가드레일·CI 조치 브랜치를 합친다 2026-11-06 02:59:02 +09:00
DongHyeonka 1a29d4aa85 chore(review): 1105 실행 격리 조치 브랜치를 합친다 2026-11-06 02:59:02 +09:00
DongHyeonka d5a70b4267 chore(review): 1105 테스트 조치 브랜치를 합친다 2026-11-06 02:59:02 +09:00
DongHyeonka 45c9c4dc48 chore(review): 1105 계약·앱 코어 조치 브랜치를 합친다
합치며 고친 것: 두 브랜치가 따로는 맞고 합치면 어긋나는 곳 하나.
- 1105/03-02(HTTP 판정 브랜치)가 §4의 503 `RATE_LIMIT_UNAVAILABLE`·
  `RATE_LIMIT_INCOMPATIBLE`을 답 표(`backend-idempotency-answers.json`)에
  옮겼다. 1105/07-01(이 브랜치)은 같은 두 code를 pin의 `notCopied`에
  두었다. 합친 트리에서 `backend-contract-pin.test.ts`의 "copies the
  answers from the backend table rows at the pin"이 "is both copied and
  listed in notCopied"로 실패한다.
- pin의 `notCopied`를 비우고, 계약 문서 4.1절의 "지금은 §4의 `RATE_LIMIT_*`
  둘"과 "§4 행은 `REQUEST_TIMEOUT` 하나"를 답 표에 맞게 고친다.
- `docs/manual/01-add-a-feature.md` 충돌은 앞 통합(1a4a220c)과 같게
  푼다: "5xx 여섯" 줄과 pin·사본·drift 명령 세 줄을 함께 둔다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/backend-contract-pin.test.ts tests/unit/backend-contract-drift.test.ts

Refs: 1105/03-02, 1105/07-01
2026-11-06 02:59:02 +09:00
DongHyeonka 57c34ea626 chore(review): 1105 realtime·Service Worker 조치 브랜치를 합친다 2026-11-06 02:59:01 +09:00
DongHyeonka 7af80859e5 chore(review): 1105 브라우저 파일·캐시·저장소 조치 브랜치를 합친다 2026-11-06 02:59:01 +09:00
DongHyeonka 19d10538d6 chore(review): 1105 HTTP 판정·폼 조치 브랜치를 합친다 2026-11-06 02:59:01 +09:00
DongHyeonka 510e2bbceb docs(testing): 한 checkout 두 실행의 run ID·포트 변수를 적는다
문제: 실행 격리(앞 두 커밋)의 변수(`TEST_RUN_ID`, `RUN_OUTPUT_ROOT`,
`TEST_*_PORT`)와 "게이트는 한 checkout에서 하나씩"이라는 전제가 어디에도
적혀 있지 않다. 테스트 전략 13.1은 dev E2E가 떠 있는 서버를 재사용한다고
적고 있어 바뀐 동작과 다르다(1105/12-04 "결정의 근거"는 이 선택이 어디에도
적혀 있지 않다고 지적했다).

고른 방법: 테스트 전략에 13.6절을 더한다. 핵심, 흐름도, 변수 표, 두 실행
예, 한계(게이트·증거 검사는 기본 경로만 읽음, 같은 run ID, 선택이 다른 두
실행의 `src/.generated`, Storybook 캐시, `.tmp/runs` 정리)를 적는다. 13.1의
재사용 문구를 고친다. 매뉴얼 "merge 전에 돌릴 것"과 README 게이트 반복문
아래에 짧게 적고 13.6절을 가리킨다.
버린 대안: README에 표 전체를 두기. README는 게이트를 돌리는 법만 적고
상세는 테스트 전략 문서에 두는 지금 구조를 따른다.

위험·한계: 문서만 바꾼다. 경로·스크립트 이름·링크는 verify:documentation이
검사한다.

검증: desktop batch에서 확인.
corepack pnpm verify:documentation

Refs: 1105/12-04
2026-11-06 02:58:00 +09:00
DongHyeonka 0e72c0c116 fix(test-run): Playwright 서버가 빈 포트를 고르고 dev 서버를 재사용하지 않는다
문제: 다섯 Playwright 설정의 서버 포트가 고정이다(e2e 4173, visual과
capability가 둘 다 4174, storybook 6006, dev 5173). 한 checkout이든 같은
기계의 두 worktree든 두 번째 실행은 `http://127.0.0.1:4173 is already
used`로 시작하지 못한다(00-R1). dev 설정만 `reuseExistingServer: true`라
5173에 다른 checkout·브랜치의 dev 서버가 떠 있으면 말없이 그 서버를
검사한다. vite는 `--strictPort` 없이 떠서, 포트가 그 사이 잡히면 다음
포트로 옮기고 Playwright는 원래 URL의 남의 서버를 검사할 수 있다
(1105/12-04).

고른 방법: 설정마다 `reservePort(TEST_<이름>_PORT)`로 빈 포트를 고른다
(`scripts/lib/run-isolation.ts`). 커널이 port 0에 준 포트를 받고 바로
닫는다. 고른 포트를 그 변수에 써 둔다. Playwright는 worker마다 설정을
다시 평가하고 worker는 runner 환경을 물려받으므로, worker의 평가가 같은
포트를 읽어 `baseURL`이 어디서나 같다. 변수를 미리 주면 그 포트를 쓴다
(디버깅용 고정). vite 서버 넷 모두 `--strictPort`로 띄우고, dev 설정은
`reuseExistingServer: false`로 바꿨다. run ID가 없어도 빈 포트를 쓴다.
두 worktree는 출력 경로가 이미 다르고 포트만 부딪히기 때문이다. 고정
번호를 읽는 곳은 없다. spec은 `baseURL`에서 origin을 얻는다
(`resumable-upload.spec.ts`, `production-csp.spec.ts`).
버린 대안: 포트 범위를 run ID에서 계산하기. 두 checkout이 같은 run ID를
쓰거나 다른 프로그램이 그 포트를 쓰면 다시 부딪힌다. Playwright
`webServer.wait`로 서버가 고른 포트를 stdout에서 읽기: `use.baseURL`은
설정을 읽을 때 정해져서 쓸 수 없다.

위험·한계: 포트를 고른 뒤 서버가 잡기 전에 다른 프로세스가 같은 포트를
잡을 수 있다. 그때는 `--strictPort`/serve-static의 listen 실패나
Playwright의 "already used"로 시작이 실패한다. 남의 서버로 검사가 새지
않는다. 기본 실행의 포트 번호가 매번 달라진다. 고정이 필요하면
`TEST_E2E_PORT=4173`처럼 준다. `test:e2e:dev`는 이제 떠 있는 dev 서버를
쓰지 않고 자기 서버를 띄운다. capability 설정이 없는 사본
(test:browser-file-storage-removal)에서는 그 설정의 포트 테스트를 돌리지 않는다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/run-isolation.test.ts tests/unit/playwright-run-isolation.test.ts
corepack pnpm test:browser-file-storage-removal

Refs: 1105/12-04
2026-11-06 02:58:00 +09:00
DongHyeonka f849d781d1 fix(home): 홈 시작 링크가 런타임에 꺼진 기능을 고르지 않는다
문제
home-page.tsx의 STARTER_ROUTES는 모듈을 불러올 때 NAVIGATION_ROUTES에서
APP_HOME을 빼고 앞 3개를 고른다. 기능이 켜져 있는지는 보지 않는다. 셸 탐색은
같은 목록을 runtime.isFeatureActive(owner)로 거르고, 라우터는 꺼진 기능의
라우트에 사용 중지 화면을 그린다. 그래서 운영자가 런타임 설정으로
platform-examples-feature를 끄면 홈의 주요 버튼 셋 중 둘(/examples/ui,
/examples/states)이 사용 중지 화면으로 간다(리뷰 08-R1 C, 1103/09-04 수정
b96d61d8이 만듦).

고른 방법
셸과 홈이 같은 함수를 쓴다. navigation-policy.ts에 activeNavigationRoutes
(isFeatureActive)를 두고(설치된 레지스트리를 읽어도 되는 기존 예외 파일이다),
셸 탐색과 홈 시작 링크가 렌더 때 그 목록을 읽는다. 홈은 그 뒤에 APP_HOME을 빼고
앞 3개를 고른다. 홈은 여전히 기능 라우트를 이름으로 부르지 않는다(1103/09-04의
보존 조건). 테스트는 platform-examples-feature 테스트 폴더에 두어 기능을 지울 때
함께 지워진다.

버린 대안
홈에서만 같은 filter를 한 번 더 쓴다: 셸과 홈의 조건이 다시 갈라질 수 있다.

위험·한계
빌드에서 뺀 기능은 처음부터 목록에 없으므로 해당 없다. 시작 링크가 셋보다 적을
수 있다(템플릿에서 예제를 끄면 둘).

검증
desktop batch에서 확인:
node scripts/run-vitest.ts run tests/features/platform-examples-feature/example-pages.test.tsx
tests/component/product-feature-switch.test.tsx tests/component/starter-pages.test.tsx
tests/unit/navigation-policy.test.ts

Refs: 1105/08-03
2026-11-06 02:33:16 +09:00
DongHyeonka 90c489c31a fix(scaffold): 생성 폼이 "변경됨으로 확인" 뒤 목록을 연다
문제
create:feature --with-create가 만드는 작성 폼의 feedback은 form.failure와 결과
불명 두 가지뿐이다. 저장 성공은 상세로 이동해서 알리는데, "변경됨으로 확인"은
reconcileUnknownEffect(...).then(form.settleApplied)이고 이동하지 않는다.
settleApplied가 결과를 success로 바꾸고 기본값 resetOnSuccess로 입력을 비우므로,
결과 불명 화면이 사라진 뒤 빈 폼만 남는다. 짝 백엔드 기본(NEVER)에서는 이것이
화면 안의 유일한 행동이다. 사용자는 확인이 받아들여졌는지 모르고, 다시 입력해
저장하면 키 없는 생성이 한 번 더 나간다(실제로 저장됐던 경우 중복). 참조 폼은
같은 경우 "저장했습니다."를 보인다.

고른 방법
확인 뒤 폼을 정리하고(settleApplied, flushSync라 이동 전에 dirty 가드가 풀린다)
목록으로 이동한다. 목록은 항목이 실제로 저장됐는지를 보여 주는 화면이고,
reconcileUnknownEffect가 이미 목록 topic을 무효화한다. 라우터가 목록 제목으로
포커스를 옮기므로 08-01의 포커스 문제도 이 폼에서는 생기지 않는다. 생성 기능
테스트에 "응답을 잃은 생성 → 변경됨으로 확인 → 목록 제목과 항목"을 한 행 더했다
(NEVER·KEYED 공통). 매뉴얼 02의 생성 테스트 행에 적었다.

버린 대안
참조 폼처럼 success 가지에 확인 문구를 둔다: 생성 catalog에 키가 하나 늘고,
항목이 실제로 있는지는 여전히 보이지 않는다.

위험·한계
- 짝 백엔드 생성기에는 목록 GET이 아직 없다(1103/03-07 결정 대기). 실제 짝
  백엔드에서는 이동한 목록이 405를 받는다(생성 목록 페이지가 지금 그렇다).
  생성 테스트는 MSW로 목록을 답한다.
- 생성 결과 파일은 단위 테스트가 문자열로만 보고, 동작은 test:feature-scaffold
  (KEYED, FE-GATE-020)와 test:sample-removal(NEVER)에서 생성한 테스트가 본다.

검증
desktop batch에서 확인:
node scripts/run-vitest.ts run tests/unit/create-feature.test.ts
corepack pnpm test:feature-scaffold
corepack pnpm test:sample-removal

Refs: 1105/08-02
2026-11-06 02:33:16 +09:00
DongHyeonka f2b8ba75d3 fix(forms): 다른 저장이 진행 중이면 저장 버튼을 끄고 진행 문구를 보인다
문제
1103/08-02 수정(2d5d41f8)이 저장 버튼을 disabled 대신 pending으로 바꾸면서
버튼은 결과 불명일 때만 꺼진다. 코디네이터가 mutation-pending이어도 이 폼이
저장 중이 아닐 수 있다. 저장 중에 화면을 떠났다가 같은 세션에서 돌아온 경우
(진행 중 시도가 있는 동안 채널이 남는다)와 "변경됨으로 확인"을 처리하는
동안이다. 그때 onSubmit은 아무것도 하지 않고 돌아가고 feedback에도 아무것도
없다. 저장을 눌러도 반응이 없고, 첫 저장이 끝난 뒤에도 그 클릭은 실행되지
않는다(리뷰 08-R1 D). 참조 폼과 생성기 템플릿이 같다.

고른 방법
"코디네이터가 mutation-pending인데 이 폼은 저장 중이 아님"을 otherSaveRunning으로
두고 두 가지를 함께 한다.
- 저장 버튼을 그동안 끈다. 이 폼 자신의 저장 중에는 지금처럼 끄지 않고 busy로
  둔다(포커스 유지, 1103/08-02). 그때 포커스는 저장 버튼에 있지 않다(다시
  마운트한 폼이거나, 누른 버튼은 "변경됨으로 확인"이다).
- feedback에 코디네이터 상태를 AsyncSurface로 그려 "변경 사항을 저장하고
  있습니다."를 보인다. 이 폼의 결과 불명을 확인하는 동안(결과가 effect-unknown)은
  그리지 않는다. 확인이 끝나면 곧 결과가 바뀌고, 그 사이에 상태 문구가 하나 더
  생기지 않게 한다.
참조 폼 페이지와 create:feature 쓰기 슬라이스 템플릿을 같이 고쳤다.

버린 대안
문구만 보이고 버튼은 켜 둔다(리뷰 문서가 포커스 때문에 권한 쪽): 확인 중에는
문구를 그릴 수 없어(위) 그때 버튼이 다시 무반응이 된다. 끄는 버튼에 포커스가
없으므로 포커스를 잃지 않는다.

위험·한계
- 생성기 쪽은 생성 결과 문자열만 단위 테스트가 본다. 다시 마운트하는 동작은
  참조 폼 테스트로만 확인한다. 생성 기능의 기존 테스트는 test:feature-scaffold
  (FE-GATE-020)와 test:sample-removal에서 돈다.
- 다른 탭이나 새로고침은 해당 없다(코디네이터는 앱 메모리 안이다).

검증
desktop batch에서 확인:
node scripts/run-vitest.ts run tests/features/reference-feature/reference-page.test.tsx
tests/unit/create-feature.test.ts

Refs: 1105/08-04
2026-11-06 02:33:16 +09:00
DongHyeonka 4f3c10bc56 fix(forms): 복구 버튼으로 끝낸 저장 뒤 포커스를 feedback 자리에 둔다
문제
1103/08-02 수정으로 저장이 실패 상태나 결과 불명으로 끝나면 포커스가 feedback
자리로 가고, Tab 한 번에 복구 버튼("변경됨으로 확인", "같은 요청으로 다시
보내기", "다시 시도")에 닿는다. 그런데 그 버튼을 키보드로 눌러 일이 끝나면
버튼을 그리던 상태가 "저장했습니다."로 바뀌며 버튼이 문서에서 빠지고, 브라우저가
포커스를 body로 돌린다. 폼은 실패 결과일 때만 포커스를 옮기고 성공 쪽
settleSuccessfulValues는 옮기지 않는다(리뷰 08-R2: chromium·firefox·webkit × 세
경우 9건 모두 body, jsdom 08-R1 B1~B3도 BODY).

고른 방법
useAppForm의 포커스 effect가 직전에 그린 결과를 기억한다. 결과가 상태
결과(reauth-required·forbidden·retry-later·unavailable)나 effect-unknown에서
success로 바뀌었고 그때 포커스가 body(잃음)이면 feedback 자리로 옮긴다. 페이지마다
복사하지 않고 폼 하나에서 고친다. 포커스를 잃었을 때만 옮기므로 버튼이나 필드에
남아 있는 포커스는 빼앗지 않고, 처음 저장이 그냥 성공할 때는 옮기지 않는다
(1103/08-02의 보존 조건). success를 그릴 feedback이 없는 화면(생성 폼은 저장 뒤
상세로 이동)에서는 아무것도 하지 않는다.

버린 대안
settleSuccessfulValues에서 늘 feedback으로 옮긴다: 마우스로 누른 첫 저장에서도
포커스가 움직인다. 리뷰 문서의 (2)(확인 중에도 feedback 자리를 비우지 않는다)는
08-04에서 다룬다. 자리를 유지해도 눌렀던 버튼은 빠지므로 끝난 뒤 포커스는 이
커밋이 정한다.

위험·한계
- 확인·재전송이 진행되는 동안(끝나기 전)에는 포커스가 잠깐 body에 있다. 끝난
  뒤만 고친다(완료 기준).
- 포커스를 받는 feedback 자리에 역할·이름이 없어 스크린 리더가 어떻게 읽는지는
  확인하지 않았다(리뷰 3.5절 관찰 그대로).

검증
desktop batch에서 확인:
node scripts/run-vitest.ts run tests/features/reference-feature/reference-page.test.tsx
tests/component/form-foundation.test.tsx
corepack pnpm exec playwright test tests/e2e/reference-save.spec.ts
--project=chromium --project=firefox --project=webkit

Refs: 1105/08-01
2026-11-06 02:33:16 +09:00
DongHyeonka 12d97d7469 feat(forms): 기능이 백엔드 거절 code에 자기 문구를 붙인다
문제
refusedBeforeWrite로 선언한 업무 거절은 이제 결과 불명이 아니고 다시
저장된다. 그런데 거절 이유가 사용자 말로 보이지 않는다. 선언한 400은 kind
UNKNOWN_CLIENT_FAILURE라 "요청을 처리할 수 없습니다." + "지원 정보 확인"이고,
409는 kind CONFLICT라 "다른 변경과 충돌했습니다."다. 고칠 수 있는 입력인데
지원 문의로 보낸다. mapProblem으로 필드 오류를 만들어도 문구는 플랫폼 표에서
issue code로만 고르므로(표에 없는 DUPLICATE는 "입력값을 확인해 주세요.")
기능이 *_ALREADY_EXISTS 같은 거절에 자기 문구를 붙일 자리가 없다(리뷰 08-R1
A1~A3). conflict 결과에서는 form.failure가 null이라 페이지가 code를 읽어 따로
그릴 수도 없다.

고른 방법
useAppForm에 refusalMessages 옵션을 더한다. 실패 code별로 기능 catalog의
메시지 키와(선택) 필드를 적는다. 적용 안 됨(effect NOT_APPLIED)으로 끝난 실패의
code가 있으면 그 문구를 필드 오류로(필드가 없거나 allowedServerFields 밖이면 오류
요약으로) 보이고 결과를 validation-error로 둔다. 필드면 그 필드로 포커스를
옮긴다. 키는 렌더 때 번역한다(다른 폼 오류와 같다). Object.hasOwn으로 자기 키만
읽는다(1103/08-03). 재로그인(action reauth)이 먼저다. 결과 불명은 code와 상관없이
결과 불명이다. 매뉴얼 02 4절에 적었다.

버린 대안
- 플랫폼 문구 표(form-contracts.ts)에 code를 더한다: 기능 code를 템플릿 파일에
  적게 된다.
- mapProblem이 문구까지 돌려주게 한다: 어댑터가 presentation 메시지 키를 알게
  된다.
- 지난 리뷰 5.3절 (B)(useAppForm이 코디네이터 상태를 받아 결과를 하나로 낸다):
  더 넓은 구조 변경이라 이 커밋에서 하지 않았다.

위험·한계
- 1103/03-01 남은 부분 중 이 커밋은 "이유 문구와 기능 문구 자리"만 고친다.
  KEYED 결과 불명의 같은 키 재전송이 500 IDEMPOTENCY_RECOVERY_REQUIRED를 받아도
  재전송 버튼이 남는 것(08-R1 A5)은 결정 대기로 남긴다. 백엔드 §2는 이 답에
  "같은 키 재전송은 안전하다, 첫 시도가 늦게 끝났으면 그 결과를 재생한다"고 적고
  답 표 사본도 sameKeyResend: true다. 버튼을 거두면 그 회복 길도 닫힌다. 고르는
  사람: 프론트 템플릿 담당(frontend-platform). 선택지: (a) RECOVERY_REQUIRED 뒤
  재전송을 거두고 "목록에서 확인" 안내를 둔다(AppFailure에 답의 원인을 싣는 계약
  추가 필요), (b) 백엔드가 KEYED 작업 안의 업무 예외(트랜잭션 롤백)를 "효과 없음"
  으로 기록해 같은 키 재전송이 다시 실행되게 한다(백엔드 변경), (c) 지금대로 둔다
  (재전송은 안전하고, 참조 폼은 목록 새로 보기 링크가 있다).
- 선언하지 않은 code는 지금처럼 결과 불명이고 "변경됨으로 확인"이 남는다(완료
  기준의 설계). 참조 기능과 생성기는 이 옵션을 쓰지 않는다. 생성기는 이미
  <FEATURE>_INVALID를 필드 오류로 보인다.

검증
desktop batch에서 확인:
node scripts/run-vitest.ts run tests/component/form-foundation.test.tsx

Refs: 1103/03-01
2026-11-06 02:33:16 +09:00
DongHyeonka 683ccfb56b fix(query): 키 없는 결과 불명 요청의 같은 입력 재제출을 훅이 막는다
문제
0929/03-03은 화면 버튼 쪽만 고쳐졌다. 남은 길이 둘이다.
- useApplicationMutation의 submit은 같은 canonical input의 결과 불명
  admission을 찾아 그 intent를 그대로 다시 보낸다. 키 없는 intent(NEVER)면
  서버가 가려낼 수 없는 두 번째 요청이다. 막는 곳은 폼(unknownSubmissionRef)과
  두 페이지의 버튼·onSubmit 검사뿐이라, 폼 밖에서 submit을 부르는 화면은 같은
  항목을 둘 만들 수 있다(리뷰 실험 X1: 재전송은 null인데 같은 입력 submit이
  두 번째 POST를 보냈고 keys=[null,null]).
- AsyncSurface는 state.unknownEffectResendable !== false일 때 재전송 버튼을
  그린다. 코디네이터 없이 손으로 만든 AsyncState(플래그 없음)는 지금도 버튼을
  그린다(실험 X3).

고른 방법
- submit이 같은 입력의 결과 불명 admission을 찾았는데 그 intent에 키가 없으면
  보내지 않고 NOT_STARTED DUPLICATE_IN_FLIGHT(code UNKNOWN_EFFECT_PENDING)를
  돌려준다. admission을 만들기 전이라 결과 불명 상태와 identity lease는 그대로다.
  KEYED의 같은 키 재전송, 입력이 바뀐 새 요청은 바뀌지 않는다. LEGACY(테스트
  하네스) 경로는 intent가 없어 replay 자체가 없으므로 영향이 없다.
- AsyncSurface는 unknownEffectResendable === true일 때만 재전송 버튼을 그린다.
  코디네이터의 state는 늘 이 값을 싣는다(canResendUnknownEffect).
- 기존 async-surface 테스트 "renders unknown mutation effects with
  confirm-applied and resend only"는 플래그 없는 상태로 버튼을 기대했다. 이
  수정의 의도대로 isUnknownEffectResendable: true를 입력에 적었다. 단언은 그대로다.
- 런북 6.3-4와 매뉴얼 01에 키 없는 재제출과 손으로 만든 상태를 적었다.

버린 대안
FailureKind에 새 kind를 더한다: 닫힌 레지스트리를 넓히는 계약 변경이다.
"같은 논리 요청이 아직 끝나지 않았다"는 DUPLICATE_IN_FLIGHT(action none)로
충분하다.

위험·한계
- 다운스트림이 AsyncSurface에 손으로 만든 결과 불명 상태와 onResendUnknownEffect를
  넘기던 화면은 재전송 버튼이 사라진다. 코디네이터의 state를 넘기면 그대로다.
- 결과 불명 admission은 메모리에만 있다. 새로고침 뒤 같은 입력은 막지 못한다
  (런북 6.3-7의 한계 그대로).

검증
desktop batch에서 확인:
node scripts/run-vitest.ts run tests/component/application-mutation-admission.test.tsx
tests/component/async-surface.test.tsx tests/component/application-query.test.tsx

Refs: 0929/03-03
2026-11-06 02:33:16 +09:00
DongHyeonka c6c37f395b fix(http): 백엔드 rate-limit 503 두 code를 쓰기 전 거절로 읽는다
문제
짝 백엔드 http-contract.md §4는 web 전용 code 넷을 적는다. 그중 503
RATE_LIMIT_UNAVAILABLE(저장소 응답 없음, retryable, Retry-After 있음)과 503
RATE_LIMIT_INCOMPATIBLE(제공자 불일치)이 답 표 사본에도 프론트 판정 표에도
없다. 그래서 이 503은 기능 분류기가 정하고, create:feature가 만든 쓰기의
분류기는 늘 MAYBE_APPLIED다. 아무 일도 일어나지 않은 저장이 결과 불명이 되고,
NEVER 쓰기는 사실과 다른 "변경됨으로 확인"을 눌러야 폼이 풀린다(리뷰 실험 X4:
429는 NOT_APPLIED, 503 둘은 SERVER_FAILURE/MAYBE_APPLIED). pin은 §4를
대조했다고 적었지만 사본에는 REQUEST_TIMEOUT 한 행만 있었다.

고른 방법
백엔드 45d2a478을 읽기만 해서 code마다 판정했다. 두 code는
RateLimitInterceptor.preHandle이 false를 돌려주며 쓰고(Unavailable·
Indeterminate → RATE_LIMIT_UNAVAILABLE, Incompatible →
RATE_LIMIT_INCOMPATIBLE), main 소스에서 두 code를 내는 곳은 그 두 줄뿐이다.
preHandle이 false면 handler를 부르지 않으므로 둘 다 쓰기 전이다. 백엔드는 같은
키 재전송을 요구하지 않는다(멱등성 executor 전). 그래서 답 표 사본에
refusedBeforeWrite: true, sameKeyResend: false로 두 행을 더하고, 프론트 거절 표
REFUSED_BEFORE_WRITE에 status 503과 함께 더했다. pin 테스트의 "답 표대로 읽는다"
규칙이 그대로 NOT_APPLIED를 요구하고 양방향 대조가 두 표를 함께 지킨다. kind는
지금처럼 SERVER_FAILURE(action retry)이고, KEYED도 자동 재전송은 없다(같은 키를
요구하는 답은 503 IDEMPOTENCY_UNAVAILABLE 하나다). pin의 comparedOn을 §4를 다시
대조한 날짜로 올렸다. 계약 문서 4.1·6.1절과 매뉴얼 01·02의 5xx 행 수를 고쳤다.

버린 대안
생성기 분류기가 503을 code별로 보게 한다: 생성 기능에만 고쳐지고 손으로 쓴
Envelope operation은 그대로 남는다. 판정은 백엔드 답 표 한 곳이 정한다는 지금
규칙을 따랐다.

위험·한계
- 추론(실행 확인 안 함): Spring MVC는 비동기 처리(Callable·DeferredResult) 뒤
  ASYNC 재디스패치에서도 interceptor의 preHandle을 다시 부르고, 이 interceptor는
  dispatcher 종류를 보지 않는다. 비동기 쓰기 컨트롤러라면 이 503(그리고 429)이
  쓰기 뒤에도 나올 수 있다. 45d2a478에는 Envelope을 돌려주는 비동기 쓰기
  컨트롤러가 없다(web-advanced 스트리밍과 fileserver 전송뿐). 계약 6.1절에 적었다.
  백엔드에 넘길 요청: RateLimitInterceptor가 DispatcherType.REQUEST에서만
  평가하게 한다.
- fileserver-upload.ts는 같은 백엔드 답을 자기 표로 따로 판정한다(01 영역).
  여기서는 바꾸지 않았다.
- NOT_APPLIED가 되면서 IDEMPOTENT 쓰기는 이 503에 retryBudget 안에서 자동으로
  다시 보낼 수 있게 됐다(503은 재시도 status다). 쓰기 전 거절이라 중복은 없다.
  RATE_LIMIT_INCOMPATIBLE은 백엔드가 retryable false로 보내지만 실행기는 status로
  판단하므로 같은 답을 한 번 더 받을 수 있다. KEYED·NEVER는 자동 재전송이 없다.

검증
desktop batch에서 확인:
node scripts/run-vitest.ts run tests/unit/backend-envelope.test.ts
tests/unit/backend-contract-pin.test.ts
tests/integration/http-execution-v3-envelope.test.ts

Refs: 1105/03-02
2026-11-06 02:33:16 +09:00
DongHyeonka 5c0b37e39e fix(contracts)!: 쓰기 뒤에도 나오는 플랫폼 code를 쓰기 전 거절로 적지 못하게 한다
문제
commandEffect.refusedBeforeWrite의 조립 검사는 code 문법, 멱등성 접두사,
중복, Envelope 여부만 본다. 계약 문서 6.1절은 BAD_PARAMETER(어느 층이든
IllegalArgumentException), MAPPING_FAILED(멱등성 응답 직렬화는 action 뒤),
DB_* 8개, LOCK_ACQUISITION_TIMEOUT, fileserver code를 "쓰기 뒤 가능"으로
적는다. 이 code를 목록에 적어도 조립이 통과하고, 그 code로 온 400·409·422가
NOT_APPLIED가 된다. 쓰기 뒤에 난 실패를 사용자가 다시 저장하면 새 키나 키
없는 새 요청이 나가 같은 항목이 둘 생길 수 있다(리뷰 실험 X2: 네 code가
조립을 통과하고 모두 NOT_APPLIED).

고른 방법
6.1절의 "쓰기 뒤 가능" 플랫폼 code를 src/contracts/external-contract-runtime.ts에
PLATFORM_CODES_POSSIBLY_AFTER_WRITE로 두고, assertRefusedBeforeWrite가 그
code의 선언을 6.1절을 이유로 거절한다. 실행기의 fail-close(조립 없이 부른
경우)도 같은 목록을 무시한다. 목록을 adapters가 아니라 contracts에 둔 것은
조립 검사가 adapters를 import할 수 없기 때문이다(리뷰 문서의 최소 개선은
backend-envelope.ts에 두라고 했다). backend-contract-pin.test.ts가 계약 문서
6.1절 표의 "쓰기 뒤 가능" 행을 읽어 목록과 양방향으로 대조한다. 참조 도메인
code와 web-advanced patch code는 엔드포인트가 단계를 정하므로 테스트의 예외
목록에 적고 선언할 수 있게 둔다.

버린 대안
- 매뉴얼 문장만 둔다(현상 유지): 폼을 막는 code를 넣고 싶어지는 바로 그
  자리에 통제가 없다.
- 업무 code 접두사 규칙(<FEATURE>_로 시작하는 code만 허용): 다운스트림 code
  이름을 강제해 과하다.

위험·한계
- 이미 이 code를 적은 다운스트림 계약은 부팅에서 조립이 실패한다. 의도한
  실패다.
- 6.1절 표에 플랫폼 code가 더해지면 목록도 같이 고쳐야 한다. 대조 테스트가
  알린다. 백엔드가 code를 더한 것은 pin을 올릴 때 6.1절을 다시 읽어야 안다.
- 업무 code를 잘못 선언하는 것은 여전히 막지 못한다(기능 작성자의 판단).
- 대조 테스트는 계약 문서를 읽으므로, 문서를 복사하지 않는 기능 제거
  드릴(FE-GATE-020의 optional-recipe·browser-file-storage·realtime)에서는
  돌지 않는다. `scripts/lib/removal-fixture.ts`의 문서 테스트 목록에
  `tests/unit/backend-contract-pin.test.ts`를 더했다. 저장소 자신의 test:unit은
  그대로 돌린다.

검증
desktop batch에서 확인:
node scripts/run-vitest.ts run tests/unit/external-contract-runtime.test.ts
tests/unit/backend-envelope.test.ts tests/unit/backend-contract-pin.test.ts
corepack pnpm test:optional-recipe-removal

BREAKING CHANGE: refusedBeforeWrite에 계약 문서 6.1절이 "쓰기 뒤 가능"으로 둔
플랫폼 code(PLATFORM_CODES_POSSIBLY_AFTER_WRITE)를 적으면
composeContractContributions가 거절한다. 그 code를 목록에서 지운다. 그 code의
실패는 결과 불명으로 남는다.

Refs: 1105/03-01
2026-11-06 02:33:16 +09:00
DongHyeonka f4d5761a2a fix(test-run): 실행마다 빌드·Playwright 출력 폴더를 따로 쓴다
문제: 빌드는 `dist`, `.generated/frontend-runtime`, `artifacts/release`·
`artifacts/quality`에 고정으로 쓰고, 다섯 Playwright 설정은 결과·report·
JUnit을 `artifacts/tests/<이름>/`에 고정으로 쓴다. 한 checkout에서 두
번째 e2e 실행이 시작하면 빌드 1단계가 첫 실행의 preview가 서빙 중인
`dist`를 지우고, Playwright가 `outputDir`을 비워 첫 실행의 trace를 지운다.
증거 파일도 늦게 끝난 쪽 것으로 섞인다(1105/12-04).

고른 방법: 변수 두 개로 나눈다(`scripts/lib/run-isolation.ts`).
- `TEST_RUN_ID`: Playwright 설정이 읽는다. 값이 있으면 그 실행의 결과·
  report·JUnit과 서빙할 빌드를 `.tmp/runs/<id>/` 아래 같은 상대 경로에
  둔다. 없으면 지금 경로 그대로라 게이트, CI upload, 증거 검사가 읽는
  곳이 바뀌지 않는다.
- `RUN_OUTPUT_ROOT`: 설정이 web server에만 넘긴다. 빌드 단계 전부
  (`build-frontend`, contract set, runtime config, SW asset 목록, SW 빌드,
  build manifest)와 `vite.config.ts`가 읽어 `dist`·생성 모듈·증거·Vite
  캐시를 그 아래에 쓴다. preview는 `--outDir`로 같은 `dist`를 서빙한다.
빌드 코드는 `TEST_RUN_ID`를 읽지 않는다. e2e worker가 저장소 복사본을
빌드할 때(fixture-builds, service-worker-builds) runner 환경을 물려받는데,
그 빌드는 복사본 자기 `dist`에 써야 하기 때문이다.
두 루트는 `.` 또는 `.tmp/` 아래만 받는다. git, Tailwind 소스 스캔(report
안 문자열이 CSS에 들어가지 않게), Vite watcher, vitest, 저장소 복사
helper가 모두 `.tmp`를 건너뛴다. service-worker-builds의 복사 제외 목록에
`.tmp`를 더했다(fixture-builds와 같아짐). build manifest의 경로는 빌드가
쓴 폴더 기준 상대 경로로 둔다.
`vite.config.ts`가 새로 가져오는 `scripts/lib/run-isolation.ts`는 저장소
일부를 임시 루트에 복사해 빌드하는 두 목록(초기 JS 측정
`scripts/scale/measure-feature-shape-growth.ts`,
`tests/unit/product-feature-selection-build.test.ts`)에도 더한다.
Storybook은 run ID가 있으면 `build:storybook`의 두 단계를 다른 `-o`로
돌린다. 같은 단계인지는 단위 테스트가 package script와 대조한다.
버린 대안: 운영 증거 경로(54개 스크립트, `config/ci/gates.json`)까지 run
ID로 옮기기. 게이트와 workflow upload가 고정 경로를 읽으므로 이번 범위
밖이다(아래 한계). 실행마다 저장소를 임시 폴더로 복사하기: 매번 수십
MB 복사와 node_modules 링크가 들고, 개발자가 보는 결과 위치가 사라진다.

위험·한계: 포트는 아직 고정이라 이 커밋만으로는 두 실행이 함께 돌지
못한다(다음 커밋). `ci:gate`와 증거 검사(`check:test-evidence`,
`verify:browser-capability-evidence`)는 기본 경로만 읽는다. run ID를 준
채 게이트를 돌리면 증거가 기본 경로에 새로 생기지 않아 게이트가 "not
freshly produced"로 실패한다(통과로 새지 않는다). Storybook 내부 캐시
(`node_modules/.cache`)는 여전히 공유한다. capability 설정
(`playwright.capabilities.config.ts`)은 test:browser-file-storage-removal이
capability와 함께 지운다. 설정 테스트는 그 파일이 있을 때만 그 설정을 읽고,
경로를 변수로 두어 타입 검사가 그 파일을 요구하지 않는다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/run-isolation.test.ts tests/unit/playwright-run-isolation.test.ts tests/unit/run-output-root-build.test.ts
node scripts/run-vitest.ts run tests/unit/feature-shape-growth.test.ts tests/unit/product-feature-selection-build.test.ts
corepack pnpm test:browser-file-storage-removal

Refs: 1105/12-04
2026-11-06 02:11:17 +09:00
DongHyeonka f2a4f32a91 docs(cache-storage): inspect의 verified 뜻과 비용을 port에 적고 판정 불가를 고정한다
문제: `PublicResponseCacheAdminPort.inspect()`의 port 계약은 비용·취소·
판정 불가를 적지 않는다. `verified: false`가 "손상"인지 "읽지 못함"인지
알 수 없고, inspect가 모든 후보의 모든 entry를 다시 읽는다는 것도 port만
보고는 모른다. 판정 불가를 `verified: true`로 바꾸는 변이 M05가 cache 테스트
59건을 모두 통과한다(0929/02-02).

고른 방법:
- port 주석에 적는다. `releaseCandidates`는 entry를 모두 다시 읽어 채우므로
  비용이 cache 수 × entry 수에 비례하고 cursor·deadline·signal이 없다.
  `verified`는 모든 entry를 읽어 manifest와 맞을 때만 `true`이고, 없거나
  다를 때와 읽지 못했을 때(본문 읽기·조회 실패) 모두 `false`다. 둘을 가르는
  것은 activation이고, 같은 manifest로 다시 stage하면 둘 다 다시 쓴다
  (1105/02-02).
- 테스트: 본문을 읽지 못하는 후보와 `cache.match`가 던지는 후보를 inspect가
  `verified: false`로, 성한 후보를 `true`로 보이는지 고정한다. M05를 잡는다.

남긴 것(일부): inspect에 `signal`을 더하거나 판정 불가를 따로 보이는 칸을
더하지 않았다. 둘 다 port 모양을 바꾸고, VD-15 목표 runtime(cursor·deadline)과
같이 정할 일이다. service-worker-pwa 번들 여유(342 B)도 좁다. 결정은 템플릿
소유자 몫이다.

위험·한계: 동작 코드는 바뀌지 않는다(주석과 테스트만).

검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/public-response-cache-repair.test.ts
- 변이 M05: `inspect`의 `verified: candidate.kind === "VERIFIED"`를
  `candidate.kind !== "REPAIRABLE"`로 바꾸면 새 테스트가 실패해야 한다.

Refs: 0929/02-02
2026-11-06 02:07:47 +09:00
DongHyeonka 11a0fd0f49 test(cross-context): host가 캡처한 localStorage의 pulse만 받는지 고정한다
문제: cross-context host는 `storage` 이벤트의 `storageArea`를 캡처한
`localStorage` 객체와 동일성으로 비교해 sessionStorage 등 다른 영역의 같은
key 이벤트를 거절한다(`browser-cross-context-host.ts` `storageEventTarget`).
transport 테스트는 core에 이미 판정된 영역 값을 넘기므로 이 비교를 지워도
(변이 N38) cross-context 테스트 46건이 모두 통과한다(1101/02-04 ②, 지난
커밋 `3bfe6a8`이 하네스가 필요해 미룸).

고른 방법: `createBrowserCrossContextInvalidationFromHost`에 탭 둘을 흉내 낸
host를 넘기는 단위 테스트를 둔다. host에는 BroadcastChannel이 없어 storage
pulse만 쓴다. 한 탭의 `localStorage.setItem`이 다른 탭 listener에 `storage`
이벤트를 보낸다. 이벤트의 `storageArea`가 받는 탭의 sessionStorage이거나
모양만 같은 다른 객체이면 구독자가 받지 않고, 받는 탭의 localStorage이면 한
번 받는다.

버린 대안: browser spec에 sessionStorage `storage` 이벤트 행을 더하기. 실제
브라우저 증거는 더 강하지만 3엔진 spec 시간이 늘고, 비교 하나를 고정하는 데는
host 단위 테스트로 충분하다.

위험·한계: 테스트만 더한다. 실제 브라우저의 `StorageEvent.storageArea`
동작은 이 테스트가 보지 않는다(기존 browser spec 몫).

검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/cross-tab-invalidation.test.ts
- 변이 N38: `storageArea === expectedLocalStorage` 비교를 지우면(늘
  `EXPECTED_LOCAL_STORAGE`) 새 테스트가 실패해야 한다.

Refs: 1101/02-04
2026-11-06 02:07:47 +09:00
DongHyeonka dc7c95b005 fix(recipes): OIDC PKCE 레시피가 sessionStorage 키를 registry에서 가져온다
문제: OIDC PKCE session owner 레시피가 sign-in transaction의
sessionStorage 키를 글자 그대로 적는다
(`"ca-frontend:auth:v1:oidc-pkce-transaction"`). 주석은
`buildPhysicalKey(...)`라고 하지만 함수를 부르지 않는다. 템플릿의 다른
Web Storage 키는 모두 `src/contracts/storage-keys.ts` registry가
`APP_NAMESPACE`로 만들고, 어댑터가 직접 쓰는 키도 `backend: "external"`
행으로 둔다. 그래서 제품이 `APP_NAMESPACE`를 바꾸면(memento 설계가
예정한 일) 이 키만 `ca-frontend:`로 남고, registry는 앱이 쓰는 Web
Storage 키 목록이 아니게 된다. registry로 로그아웃 때 지울 키를 정하는
제품은 버려진 sign-in의 verifier·state·nonce·돌아갈 경로를 지우지 못한다.

고른 방법:
- registry에 `AUTH_REDIRECT_TRANSACTION` 행을 둔다. `scope: "auth"`,
  `name: "oidc-pkce-transaction"`, `backend: "external"`(pulse 키와 같은
  모양, StoragePort는 거절), `ttl: "session"`. 물리 키는 지금 글자와 같다
  (`ca-frontend:auth:v1:oidc-pkce-transaction`)라서 진행 중인 sign-in을
  잃지 않는다.
- 레시피의 `OIDC_PKCE_TRANSACTION_KEY`는 그 행의 `physicalKey`다.
  매뉴얼의 복사 규칙(`../../src/` → `../`)이 새 import에도 그대로 맞는다.
- 분류는 `opaque-cache`다. `sensitive-forbidden`은 "저장하지 않는다"는
  뜻이고 backend가 disabled·forbidden이어야 해서 맞지 않는다. 이 값은
  리다이렉트 한 번 동안 저장하는 것이 설계다.
- FE-REG-STORAGE의 `orphanExemptRows`에 이 행을 더한다
  (`config/contracts/registry-governance.json`). 이 행을 쓰는 곳은 레시피
  하나뿐이고, 레시피는 제품이 지울 수 있다(test:optional-recipe-removal).
  행은 registry로 지울 키를 정하는 제품을 위해 남는다. `AUTH_TOKEN`처럼
  사용처 없이 선언만 하는 행이다. 빼지 않으면 `src`만 복사해
  check:registries를 돌리는 `tests/unit/second-api-feature-registries.test.ts`가
  "has no executable consumer"로 실패한다.
  버린 대안: consumer 폴더에 `recipes`를 더하기. 레시피를 지운 사본(FE-GATE-020)
  에서 다시 사용처가 사라진다.

버린 대안: registry에 새 분류(예: `session-transaction`)를 더하기. 계약
타입의 union과 registry 기준선의 허용 값이 함께 바뀌는데, 분류가 코드
동작을 바꾸는 곳은 `sensitive-forbidden` 검사뿐이라 얻는 것이 없다.

위험·한계:
- `src/contracts/storage-keys.ts`에 행 하나가 더해진다(FE-REG-STORAGE
  additive). CHANGELOG [계약] 행이 필요하다.
- 이미 레시피를 복사한 제품은 자기 복사본을 같은 diff로 고쳐야 키가
  namespace를 따른다.
- orphan 검사가 이 행을 보지 않는다. 레시피가 키를 registry에서 가져오는지는
  `tests/recipes/oidc-pkce-session-owner.test.ts`가 본다.

검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/storage-registry.test.ts
  tests/recipes/oidc-pkce-session-owner.test.ts
- corepack pnpm check:registries (additive 행)
- node scripts/run-vitest.ts run tests/unit/second-api-feature-registries.test.ts
- corepack pnpm test:optional-recipe-removal

Refs: 1105/05-01
2026-11-06 02:07:47 +09:00
DongHyeonka ce191bef4b test: 운영 시간 상수를 실제 시계로 기다리는 테스트 5개를 빠르게 한다
문제
테스트 5개가 운영 코드의 시간 상수를 실제 시계로 기다린다.
- tests/unit/service-worker-runtime.test.ts "bounds a stream that never
  produces a chunk": ACTIVATION_MARKER_READ_DEADLINE_MS(5초)를 그대로
  기다린다. 10초 제한 중 5초를 쓴다.
- tests/unit/browser-rpc/browser-rpc-remediation.test.ts "keeps the
  operation DRAINING when waitClosed …" 4개: 닫힘 확인이 없으면 stream
  정리가 STREAM_CLEANUP_BOUND_MS(1초)를 기다린다. 각 1초.

고른 방법과 버린 대안
- SW 테스트: 이 테스트만 vi.useFakeTimers()로 돌리고 deadline을
  advanceTimersByTimeAsync로 넘긴다. 마커를 여러 번 읽을 수 있어
  끝날 때까지 5초씩 최대 4번 넘긴다. deadline이 없으면 활성화가 끝나지
  않아 "settled" 단언에서 실패한다.
- RPC 테스트: 런타임은 이미 ClockPort를 주입받는다. 모든 대기를 30ms로
  자르는 시스템 시계를 넘긴다. 작업 자체의 25ms deadline은 그 아래라
  그대로다.
- SW lifecycle이 deadline을 의존성으로 받게 하는 안은 버렸다. 운영
  코드에 테스트용 손잡이를 하나 더 열어야 한다.
- 상수 값(5,000·1,000)은 운영 코드 한 곳에 그대로 있다.

위험·한계
- 가짜 시계가 stream·마이크로태스크 순서와 얽히면 SW 테스트가
  불안정해질 수 있다. 그때는 실제 시계로 되돌린다(1101/10-07 재검토
  조건).
- 완료 기준(각 100ms 아래)은 junit 시간으로 desktop에서 본다.

검증
- desktop batch에서 확인:
  node scripts/run-vitest.ts run tests/unit/service-worker-runtime.test.ts tests/unit/browser-rpc/browser-rpc-remediation.test.ts --reporter=junit --outputFile.junit=artifacts/tests/r1105-10-07.xml
- 실행 시간만 바꾼 커밋이라 RED는 없다. 두 파일이 통과하고 다섯
  테스트가 각각 100ms 아래여야 한다.

Refs: 1101/10-07
2026-11-06 01:05:22 +09:00
DongHyeonka 7ead8d369a fix(test): test:all이 test:coverage가 도는 Vitest 경로를 모두 돌린다
문제
taxonomy는 test:all을 일상 개발 루프라고 적는다. 그런데 test:all은
tests/features 중 참조 샘플만(test:reference-feature) 돌리고,
test:coverage(FE-GATE-005)가 도는 tests/features의 나머지(설치 표면,
feature-module, 예제 기능 2파일), tests/scripts,
tests/scale/browser-soak.contract.test.ts를 빠뜨린다. 로컬에서 초록이고
CI에서 빨강이 될 수 있다.

고른 방법과 버린 대안
- package.json test:all의 test:reference-feature 자리를 tests/features
  전체 + tests/scripts + browser-soak 계약 테스트를 한 번에 도는 Vitest
  실행으로 바꾼다. 참조 샘플 테스트도 tests/features 안이라 그대로
  돈다. 샘플을 지우면 그 폴더만 빠진다.
- tests/unit/test-all-paths.test.ts(새 파일): package script graph로
  test:all과 test:coverage의 Vitest 경로를 모아, coverage 쪽 경로가
  모두 test:all 경로 안에 있는지 본다. 다시 빠지면 이 테스트가 잡는다.
- 새 package script(test:features)를 만드는 안은 버렸다. 그 이름이
  tests/scripts까지 도는 것을 말하지 못하고, test:all만 쓰는 스크립트가
  하나 늘 뿐이다.
- taxonomy에 "CI와 같은 집합은 test:coverage"라고만 적는 안은 버렸다.
  완료 기준(test:all ⊇ test:coverage의 Vitest 파일)을 못 채운다.
- docs/testing/taxonomy.md의 test:all 설명을 바꾼다.

위험·한계
- 제거 드릴 셋(optional recipe, realtime, browser-file-storage)은
  fixture 안에서 test:all만 돈다. 이제 이 파일들도 그 fixture에서
  처음 돈다. import를 보면 제거 대상에 기대지 않지만 실행으로는 확인하지
  못했다. 드릴 시간이 몇 초씩 는다(1101/10-06과 반대 방향).

검증
- desktop batch에서 확인:
  node scripts/run-vitest.ts run tests/unit/test-all-paths.test.ts
  corepack pnpm test:all, corepack pnpm check:ci, FE-GATE-020
- RED: 부모 커밋의 package.json에서 "runs every Vitest path
  test:coverage runs"가 tests/features·tests/scripts·browser-soak
  경로를 빠졌다고 실패한다.

Refs: 0929/10-05
2026-11-06 01:05:22 +09:00
DongHyeonka c842bac0d5 test(http): 오래된 scope의 성공 응답을 버리는 마지막 검사를 고정한다
문제
§10.8의 마지막 검사(src/adapters/http/http-execution-v3.ts:1493-1499,
검증을 통과한 성공 응답이라도 scope가 이미 현재가 아니면 SCOPE_FENCED)
를 false로 바꿔도 네 라운드째 모든 테스트가 통과한다(변이 L01). 지금
scope fence 테스트는 scope signal도 abort해서, abort 경로가 먼저
답하고 이 검사까지 오지 않는다.

고른 방법과 버린 대안
- tests/unit/http-execution-v3.test.ts에 경우 둘(조회·명령)을 더한다.
  fetch 안에서 scope의 isCurrent만 false로 바꾸고 signal은 abort하지
  않는다. JSON 성공 경로에서 dispatch 뒤 scope를 보는 곳은 이 검사
  하나라서, 검사를 지우면 SUCCESS가 나와 테스트가 실패한다.
- 기대값: CONTRACT_VIOLATION/SCOPE_FENCED, 조회는 NOT_APPLICABLE,
  명령은 MAYBE_APPLIED(보냈으니 적용됐을 수 있다).
- 기존 abort 테스트를 바꾸는 안은 버렸다. 그 테스트는 abort가 먼저
  이기는 경로를 지킨다.

위험·한계
- 테스트만 더했다. 실행기 코드는 그대로다.

검증
- desktop batch에서 확인:
  node scripts/run-vitest.ts run tests/unit/http-execution-v3.test.ts
- 변이 L01(:1494 조건을 false로)을 넣으면 "discards a valid read/command
  success that arrives after its scope stopped being current" 2건이
  실패해야 한다.

Refs: 0929/10-04
2026-11-06 01:05:22 +09:00
DongHyeonka 757d1c736b fix(a11y)!: 실패 화면으로만 검사한 라우트를 a11y.json에서 통과로 세지 않는다
문제
접근성 e2e는 보호 라우트의 목록 조회에 빈 목록을 답한다. 자원 하나를
읽는 상세 라우트(참조 기능의 상세, 생성기 --with-create의 상세)는
일반 답이 없어 실패 화면에서 axe를 돌린다. 그런데
scripts/write-a11y-report.ts는 설치된 라우트 전체를 scope에 넣고
automatedStatus "passed"를 쓴다. 화면 내용은 한 번도 검사하지 않은
라우트가 통과로 보고된다. annotation은 test 결과에만 남는다.

고른 방법과 버린 대안
- scripts/lib/a11y-data-state.ts(새 파일): 라우트 test가 끝날 때
  자기 상태를 artifacts/tests/a11y-data-state/<ROUTE_ID>.json에 남긴다.
  실패 화면으로만 봤으면 이유를 쓰고, 아니면 지운다. 그래서 라우트마다
  마지막 실행이 정한다. 세 엔진이 같은 파일을 쓰므로 임시 파일에 쓰고
  rename한다.
- tests/e2e/accessibility.spec.ts: 위 기록을 남긴다(공개 라우트와
  데이터 상태로 본 라우트는 지운다).
- a11y.json schemaVersion 2: scope에는 자기 상태로 검사한 라우트만,
  notChecked에는 실패 화면으로만 본 라우트와 이유를 넣는다. 둘을
  합치면 설치된 라우트 레지스트리와 같아야 한다(schema가 본다).
- 상세 라우트를 실제 데이터 상태로 검사하는 안은 버렸다. 출력
  validator에서 유효한 값을 일반적으로 만들 수 없고, 기능마다 견본
  응답을 받는 자리를 새로 열어야 한다.
- annotation을 Playwright JSON reporter로 읽는 안은 버렸다. test:a11y
  스크립트의 reporter와 산출물 경로를 바꿔야 하고, 경로는 다른 작업
  (12-04)이 바꾸는 중이다.
- 매뉴얼(docs/manual/reference/create-feature.md)에 상세 라우트가
  notChecked로 적히고 수동 검토가 맡는다고 적는다.

위험·한계
- a11y.json 모양이 바뀐다(schemaVersion 1 → 2, scope 의미, 새 필드).
  템플릿 안의 소비자는 ci-artifact-validator 하나이고 같이 바꿨다.
- 템플릿 상태에서도 참조 기능의 상세 라우트가 notChecked로 나온다.
  지금까지 실제로 검사하지 않던 것이 드러나는 것이다.
- 기록 디렉터리는 artifacts/tests 아래 고정 경로다. 12-04가 산출물
  경로를 실행마다 나누면 이 경로도 따라가야 한다.
- 라우트 test가 돌지 않은 실행에서는 그 라우트의 지난 기록이 남는다.
  지난 기록이 "검사 안 함"이면 덜 주장하는 쪽이라 위험하지 않다.

검증
- desktop batch에서 확인:
  node scripts/run-vitest.ts run tests/unit/a11y-report.test.ts
  corepack pnpm test:a11y (세 엔진) 뒤 artifacts/tests/a11y.json의
  notChecked에 REFERENCE_RESOURCE_DETAIL이 있고 scope에 없어야 한다.
- RED: 부모 커밋에는 scripts/lib/a11y-data-state.ts가 없어 새 unit
  test 파일 전체가 실패한다.

Refs: 1103/11-01
BREAKING CHANGE: artifacts/tests/a11y.json이 schemaVersion 2가 된다. scope는 실패 화면으로만 본 라우트를 빼고, 그 라우트는 새 notChecked 배열에 { routeId, reason }으로 들어간다. scope를 설치된 라우트 전체로 읽던 도구는 scope와 notChecked를 합쳐 읽는다.
2026-11-06 01:05:22 +09:00
DongHyeonka e02552998d test(e2e): strict fixture가 preload 기록으로 test를 실패시키는지 고정한다
문제
tests/e2e/preload-use.spec.ts는 preload tracker만 증명한다. 안 쓴
preload를 넣는 test는 맨 test에서 tracker를 직접 부르고, strict
fixture를 쓰는 test는 "통과해야 한다" 방향 하나뿐이다. 그래서
strict-browser-test.ts가 tracker 결과를 버려도(11-R3) 커밋된 test는
하나도 실패하지 않았고, WebKit 무시 정규식을 넓혀도 볼 test가 없다.
3번 test는 지연시킬 청크를 못 찾으면 조용히 평범한 방문이 된다.

고른 방법과 버린 대안
- strict fixture의 마지막 판정을 browserFailureVerdict fixture로
  뺀다. 기본값은 지금과 같다(allowedBrowserFailure로 거르고 빈 목록
  단언). page fixture는 기록을 그 판정에 넘긴다.
- spec은 그 판정을 "기록을 받아 두는" 판정으로 바꾼 recordedTest를
  둔다. page fixture가 판정에 의존하므로 판정의 teardown은 page
  teardown 뒤에 돈다. 거기서 fixture가 넘긴 줄이 fixtureReports와 정확히
  같은지 본다.
  - 안 쓴 modulepreload 하나 → `preloadunused:/assets/<청크>.js` 한 줄.
  - WebKit 문구 그대로(무시), Chromium 문구, WebKit 문구 + 뒤 글자,
    같은 문구의 console.error, 다른 warning → 뒤의 네 줄만, 순서대로.
- 기본 판정이 실제로 test를 실패시키는지는 strictTest.fail()로 console
  error 한 줄을 내는 test 하나가 본다. 기록이 맞다는 것은 위 두 test가
  따로 증명하므로, 이 test가 엉뚱한 이유로 실패해도 놓치는 것이 적다.
- 3번 test는 지연시킬 청크가 없으면 이유를 적고 실패한다.
- 모든 probe를 test.fail()로만 고정하는 안은 버렸다. 어떤 이유로든
  실패하면 통과해서 fixture가 무엇을 기록했는지 보지 못한다.
- 커밋한 문서: docs/testing/frontend-platform-testing-strategy.md에
  증명 위치와 판정을 바꾸는 곳이 그 spec 하나라는 것을 적는다.

위험·한계
- 모든 browser spec이 쓰는 fixture의 구조가 바뀐다. 판정 내용은 같다.
- 다른 spec도 browserFailureVerdict를 바꿔 strict 검사를 끌 수 있다.
  allowedBrowserFailure를 /.*/로 주는 것과 같은 수준의 노출이고 막는
  검사는 더하지 않았다.
- 샘플을 지운 제품에서 기능 실행부 모양이 바뀌면 3번 test가 실패한다.
  그때는 test를 다른 청크로 옮기거나 이유를 적고 지워야 한다.

검증
- desktop batch에서 확인:
  corepack pnpm exec playwright test tests/e2e/preload-use.spec.ts (세 엔진)
- 테스트 장치만 바꾼 커밋이라 RED는 변이로 본다.
  - 11-R3(strict fixture가 check 결과를 버림): "records a modulepreload
    the page never runs"가 세 엔진에서 실패해야 한다.
  - WEBKIT_UNUSED_PRELOAD_GUESS를 /.*/로: "ignores WebKit's
    unused-preload guess word for word and nothing else"가 실패해야 한다.
  - browserFailureVerdict 기본값의 expect 제거: "fails a test whose page
    writes a console error"가 "expected to fail" 위반으로 실패해야 한다.

Refs: 1105/11-01
2026-11-06 01:05:22 +09:00
DongHyeonka a37ebba39c fix(architecture): 기능 안 계층 밖 폴더가 src/adapters에 닿으면 막는다
문제
feature-and-app-roots-do-not-reach-adapters는 기능 루트 파일
(src/features/*.ts, src/features/<id>/*.ts), src/contexts, src/apps만 본다.
그래프는 간선 하나씩 검사하므로, 기능 안에 계층이 아닌 폴더(support/ 등)를
만들어 그 파일이 http adapter 배럴을 import하고 기능 presentation이 그 파일을
import하면 presentation이 구체 adapter에 닿는다. 1105 리뷰 12-R3 변이에서
check:architecture와 ESLint가 둘 다 통과했다.

고른 방법
- 규칙의 from을 "src/features 아래 모든 파일, 기능의 adapters/ 폴더 밖"으로
  바꾼다(`^src/(features/|contexts/|apps/)`, pathNot
  `^src/features/([^/]+/adapters/|feature-adapter-contribution\.ts$)`). 규칙
  주석이 이미 "기능 안에서는 adapters/ 폴더만 src/adapters에 닿는다"고 적고
  있었고, 그 문장을 경로로 옮긴 것이다. 파일 단위 예외는 기존 하나
  (feature-adapter-contribution.ts, type only) 그대로고 새로 더하지 않았다.
- domain·application·presentation은 자기 규칙이 이미 src/adapters를 막는다.
  이제 그 파일들이 src/adapters를 import하면 이 규칙도 같이 걸린다(위반 두 줄).
  더 엄격해질 뿐 허용이 바뀌지는 않는다.
- 지금 src/features에서 src/adapters를 import하는 곳은 reference-feature의
  adapters/ 두 파일과 feature-adapter-contribution.ts뿐이라 새 위반은 없다.
  create:feature가 만드는 adapter import도 adapters/ 안이다.
- 그래프 회귀 fixture에 support/ 재수출(거절), 그것을 읽는 presentation,
  기능 adapters/ import(허용)를 더하고 check:architecture에 두 단언을 더했다.
  규칙 경로를 check:architecture와 같은 방식으로 읽는 vitest 테스트를 더했다.
- layers.md 표와 매뉴얼 01의 설명을 고쳤다.
- 버린 대안: 계층 밖 폴더 자체를 금지(폴더 이름 목록 검사). 제품이 contracts/
  같은 다른 이름을 쓰면 계속 목록을 고쳐야 한다. 규칙마다 support/ 패턴 추가:
  다음 폴더 이름에서 같은 틈이 난다.

위험·한계
- 다운스트림이 기능 안 adapters/ 밖에서 src/adapters를 import하고 있었다면 이제
  check:architecture가 실패한다. 그 파일을 adapters/로 옮기면 된다.
- ESLint는 여전히 간선 하나만 보므로 이 경로를 잡지 않는다. 그래프가 잡는다.

검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
  tests/architecture/feature-adapter-reach.test.ts, corepack pnpm
  check:architecture(그래프 fixture 단언 2개 추가 PASS, 저장소 위반 0 기대).
- RED 기대: "rejects a concrete adapter import from a feature folder that is not
  a layer", "leaves a feature's adapters folder and the type-only contribution
  file to reach adapters"(support/adapters/ 경로 단언).

Refs: 0929/12-03
2026-11-05 22:41:50 +09:00
DongHyeonka e72fb6e290 docs(testing): 테스트 전략이 지운 auth-recovery 테스트 대신 V3의 401 판정을 가리킨다
문제
docs/testing/frontend-platform-testing-strategy.md 11.2절이 "401 뒤 인증 복구
흐름은 tests/integration/auth-recovery.test.ts가 다룬다"고 적는다. 그 파일은
V2 클라이언트를 지울 때(048f490a) 같이 지웠고, V3 실행기에는 401 뒤 복구·재전송
흐름이 없다. 문서를 따라가면 없는 테스트와 없는 동작을 찾게 된다. 이 문서는
docs/README.md 1절 밖(목표 설계)이라 verify:documentation이 보지 않는다.

고른 방법
- 문장을 지금 동작으로 고친다: V3는 401을 UNAUTHENTICATED로 끝내고 다시 보내지
  않는다(http-execution-v3.ts), 판정은 tests/unit/http-execution-v3.test.ts가
  검사한다. 지운 파일 이름은 backtick 경로로 남기지 않는다.
- 1103/12-05의 남은 둘(지운 심볼 이름 검사, 1절 밖 문서 검사)은 이 커밋에서
  하지 않는다. 심볼 검사는 지난 리뷰가 버린 대안이다(지운 이름 목록을 따로
  관리해야 하고 오탐이 많다). 1절 밖 문서는 목표 설계라 일부러 없는 경로를
  적는다. 2절 문서의 backtick repo 경로 중 없는 것이 15개쯤이고 대부분
  계획 경로다(src/domain, src/generated, V2 파일 등). 검사로 넓히려면 문서별
  예외 방식부터 정해야 한다(결정 대기).

위험·한계
- 같은 종류의 옛 경로는 1절 밖 다른 문서에 남아 있다(2026-07-30 결정 정본의
  V2 http 파일 등). 이 커밋은 리뷰가 든 한 곳만 고친다.

검증
- 문서만 바꿨다. 이 문서를 보는 자동 검사는 없다(1절 밖). desktop batch에서
  corepack pnpm verify:documentation이 그대로 통과하는지만 본다.

Refs: 1103/12-05
2026-11-05 22:41:50 +09:00
DongHyeonka 92d5019c6d fix(ci): 제품 merge 게이트가 실패하면 같은 run의 release 단계를 멈춘다
문제
제품 overlay(config/ci/product-gates.json)의 mergeGates는 product_merge_gate
job으로 렌더링되는데, 다른 job이 이 job을 기다리지 않는다. release_gate는
merge_gate만 기다린다. 그래서 제품 검사(예: 짝 백엔드 계약 검사)가 실패해도
같은 run의 release·immutable_build·promotion·deployment는 그대로 돈다. 브랜치
필수 검사는 PR merge만 막는다. job 그래프는 계약이 고정해서(ci-gates.ts의
expectedJobGraph) 제품이 연결을 더할 방법도 없다.

고른 방법
- overlay에 게이트가 있으면 release_gate의 needs에 product_merge_gate를 더해
  렌더링한다(`needs: [merge_gate, product_merge_gate]`). release_gate는 release
  단계의 첫 job이고 뒤의 job은 모두 그것을 거쳐 기다린다. 템플릿 게이트가
  release를 막는 방식과 같다.
- 연결은 렌더링에서만 더한다. gates.json과 계약 그래프 검사는 그대로라 템플릿
  job 그래프와 check:ci의 엄격함은 바뀌지 않는다. 게이트가 없으면 workflow
  바이트가 같다(.gitea/workflows/quality-gates.yml 변경 없음).
- workflowGateExecutionFailures(check:ci가 부름)가 제품 게이트가 있는데
  release_gate가 product_merge_gate를 기다리지 않는 workflow를 거절한다.
  "실행된다"와 "막는다"를 따로 본다.
- 문서(ci-quality-gates.md, README)에 release 단계가 제품 job을 기다린다고
  적었다.
- 버린 대안: (a) 문서에만 "막지 않는다"고 적기. 제품이 막을 방법이 계속 없다.
  (c) 게이트마다 blocksRelease 칸. 선택권은 주지만 칸이 늘고, 불안정한 제품
  검사가 생기기 전에는 필요가 없다. 계약 그래프 검사에 overlay 예외를 넣는 것:
  템플릿 계약이 제품 overlay를 알아야 한다.

위험·한계
- 불안정한 제품 게이트는 이제 release도 멈춘다. 그때는 (c)로 간다.
- Gitea가 needs와 기본 success() 조건을 GitHub Actions처럼 처리한다고 본다.
  실제 runner에서는 확인하지 못했다(Actions 꺼짐).
- 제품 게이트를 이미 쓰는 다운스트림은 generate:ci-workflow를 다시 돌려야
  check:ci를 통과한다(생성 YAML의 release_gate needs 한 줄이 바뀐다).

검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
  tests/unit/product-ci-overlay.test.ts tests/unit/ci-workflow-generation.test.ts,
  corepack pnpm check:ci.
- RED 기대: "holds the release stage until the product merge gates pass",
  "runs product merge gates in a job of their own, apart from the template gates".

Refs: 1105/13-02
2026-11-05 22:41:50 +09:00
DongHyeonka aa5d8e6c12 chore(review): 1105 업로드 client 조치 브랜치를 합친다 2026-11-05 22:37:50 +09:00
DongHyeonka fc95672ad5 fix(docs): 문서 검사가 짝 백엔드 참조를 pin 커밋의 트리에서 찾는다
문제
verify:documentation(FE-GATE-017)은 짝 백엔드 경로·링크를 옆 checkout의
작업 트리에서 찾았다. 그래서 같은 커밋이 놓인 곳마다 결과가 달랐다. desktop은
옆 checkout이 ef947e5(9월)에 미커밋 변경까지 있어 문서와 무관하게 rc=1,
짝이 없는 worktree는 PASS(17개 미확인)였다. 옆 checkout이 pin보다 새로우면
pin에 없는 파일을 적어도 통과하고, 저장소 이름을 틀린 `../` 링크는
"확인 못 함"으로 통과했다. config/contracts/backend-contract-pin.json은 읽지
않았다.

고른 방법
- 짝 저장소 목록과 기준 커밋을 pin 파일에서 읽는다. pin은 문서와 같이
  작업 디렉터리에서 읽는다(문서가 어느 커밋을 설명하는지 적은 파일이라서).
- 옆 checkout에 pin 커밋이 있으면 `git ls-tree -r -t <pin>`으로 그 커밋의
  트리(파일과 폴더)를 한 번 읽어 찾는다. 작업 트리와 HEAD는 보지 않는다.
  hook이 넘긴 GIT_DIR 같은 GIT_* 변수는 지우고 git을 부른다.
- checkout이 없거나, pin 커밋이 없거나, git이 읽지 못하면 실패 대신
  unverifiedLinks로 남기고, 출력에 이유(짝 HEAD, pin 앞 12자)를 적는다.
- `../`로 나가는 링크의 첫 폴더가 pin에 없는 저장소면 missingPaths로 실패한다.
  실패하면 "pin 커밋에서 찾았다"는 줄을 stderr에 하나 더 적는다.
- 버린 대안: 짝 HEAD가 pin과 다르면 전부 unverified(리뷰 (c)). 더 단순하지만
  pin 뒤로 앞서 있는 흔한 checkout에서 아무것도 확인하지 못한다. 경로마다
  `git cat-file -e`: 같은 결과지만 참조 수만큼 프로세스를 띄운다.

위험·한계
- pin 커밋을 fetch하지 않은 checkout(desktop 지금 상태)에서는 짝 참조가 전부
  "not verified"다. 실패하지 않는 대신 확인도 하지 않는다.
- 짝 저장소는 여전히 하나(pin 파일의 backend)다. 둘째 짝이 생기면 pin 모양부터
  바꿔야 한다.
- pin 파일이 없으면 짝 저장소가 없는 것으로 보고 `../` 링크를 전부 실패로 센다.
- 보고서 schema는 그대로다(unverifiedLinks 주석만 고침).

검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
  tests/unit/documentation-readiness.test.ts, 그리고 corepack pnpm
  verify:documentation(옆 짝이 ef947e5인 desktop에서 PASS_SCOPED +
  not verified 기대).
- RED 기대: "looks a reference up in the pinned commit, not in a later HEAD or
  the working tree", "reports the references as not verified when the
  checkout does not have the pinned commit", "fails a link out of the
  repository into a repository that is not paired".

Refs: 1105/12-02
2026-11-05 22:29:19 +09:00
DongHyeonka 48c1ab7ab6 fix(server-state)!: 손으로 적은 뮤테이션 operation ID를 타입 검사에서 막는다
문제: 1103/16-05 수정으로 commandMutationIdentity가 생겼지만
BoundMutation.operationId는 여전히 string이다. 정책에 operation ID를
문자열로 직접 적으면 오타가 check:types와 check:registries를 통과하고,
저장할 때마다 실행기가 보내기 전에 MISSING_IDEMPOTENCY_KEY 위반으로
거부한다. 매뉴얼 01은 이것을 "못 잡음"으로 적고 있었다.

고른 방법: BoundMutation.operationId를 brand 타입 MutationOperationId로
바꾼다. 이 값을 돌려주는 것은 commandMutationIdentity뿐이라, 문자열을
직접 적으면 check:types가 실패한다. 런타임 값은 descriptor의 문자열
그대로이고 실행기·intent factory는 바뀌지 않는다. 참조 기능과 쓰기 slice
생성기는 이미 commandMutationIdentity를 spread하므로 고칠 것이 없다.
템플릿 테스트의 손글씨 ID 20곳은 tests/helpers/mutation-operation-id.ts
(commandMutationIdentity를 거치는 test helper)나 그 파일의 descriptor로
바꿨다. 매뉴얼 01·patterns 표·state 설계 예시를 맞췄다.
버린 대안: (1) 위반 이름을 INTENT_OPERATION_MISMATCH로 나누는 것. 실행
때만 드러나는 것은 같고, 공개 위반 어휘에 값이 하나 늘어 다운스트림
분기가 바뀐다. (2) 설치된 operation ID의 union 타입. 기능마다 늦게
적재되는 계약 전체를 타입으로 모을 곳이 없다.

위험·한계: 공개 타입(src/contracts/server-state.ts)이 좁아진다. 정책에
operation ID를 문자열로 적은 다운스트림 코드는 동기화 뒤 check:types가
실패한다. commandMutationIdentity에 descriptor 상수 대신 손으로 만든
객체를 넘기면 여전히 오타가 통과한다(매뉴얼 "못 잡음"). HTTP가 아닌
뮤테이션은 descriptor 모양 객체를 넘겨야 한다. 이 repo에는 그런 소비자가
없다.

검증: desktop batch에서 확인.
corepack pnpm check:types:test
tests/unit/command-mutation-identity.test.ts의 @ts-expect-error가 부모
커밋에서는 쓰이지 않아(TS2578) 실패하고 이 커밋에서 통과한다.
node scripts/run-vitest.ts run tests/unit/command-mutation-identity.test.ts tests/component/application-mutation-admission.test.tsx tests/component/application-mutation-scope-fence.test.tsx tests/component/application-query.test.tsx tests/component/form-foundation.test.tsx

BREAKING CHANGE: BoundMutation.operationId는 string이 아니라
MutationOperationId다. 뮤테이션 정책의 `operationId: "<ID>"`와
`requiresIdempotencyKey`를 `...commandMutationIdentity(<OPERATION>_CONTRACT)`
로 바꾼다(src/contracts/server-state.ts). commandMutationIdentity의 반환
타입도 operationId가 MutationOperationId다.

Refs: 1103/16-05
2026-11-05 22:26:27 +09:00
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 a793b83e82 docs(changelog): 1105 P1 조치 셋을 새 미출시 절에 적는다
CHANGELOG의 미출시 절은 `752a61f` → `fix/maturity-review-2026-11-03`
범위다. 그 범위는 main `409d72e`에 합쳐졌고, 2026-11-05 리뷰의 P1
조치 셋(1105/09-01, 12-01, 13-01)은 어느 절에도 없다. 다운스트림이
FE-GATE-013 러너 요구와 release job의 새 upload를 알 수 없다.

`409d72e` → `fix/maturity-review-2026-11-05` 범위의 새 미출시 절을
위에 두고 세 조치를 적었다. CI 러너 요구와 workflow upload가 바뀌므로
12-01·13-01은 [계약]이다. 기존 절은 지우지 않고 main에 합쳐졌다고만
머리에 적었다. 두 절을 하나로 합칠지는 남은 조치(PR B)의 CHANGELOG
정리에서 정한다.

위험·한계: 문서만 바꿨다.

검증: desktop batch에서 changelog-review-ids, documentation-readiness
테스트.

Refs: 1105/09-01, 1105/12-01, 1105/13-01
2026-11-05 22:18:15 +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 54d0d0c7b0 chore(review): 1105 제품 확장 탐침 조치 브랜치를 합친다 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