refactor: 리펙토링 문서 추가

This commit is contained in:
DongHyeonka
2026-10-02 14:25:27 +09:00
parent af3d8e6ffe
commit 752a61f28b
17 changed files with 6397 additions and 5 deletions
@@ -0,0 +1,337 @@
# 01 browser-transfer 성숙도 리뷰 (2026-09-29)
> 기준: `main` / `af3d8e6` (태그 `v0.2.0` + docs 커밋 1개) · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` · 체크리스트: `docs/reviews/TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md`
> 영역 판정(35.8): **조건부 사용 가능**. 기본 production 구성에는 조립돼 있지 않다(`AVAILABLE_NOT_COMPOSED`). 조립하는 다운스트림은 01-01의 recovery 번역을 그대로 믿으면 안 된다.
## 요약
- 지난 라운드 발견 11건(01-01~01-11)의 수정이 현재 코드에 있다. 변형 13종 중 12종을 테스트가 잡았다. 지난번에 살아남던 멱등 키 변형(M1·M6·M7)도 이제 잡힌다.
- **새로 확인한 결함(Medium).** `upload()` 실패의 recovery 번역(`toUploadAction`)은 recovery 어휘만 보고 code·단계는 보지 않는다. 그래서 6개 경로에서 포트 표와 다른 행동을 가리킨다. 파일이 바뀌거나 IndexedDB가 잠깐 실패하면 `retryable:true`인데 `recovery:NONE`이 나온다(01-01).
- **01-02 수정의 빈틈(Low).** complete가 반영된 뒤 로컬 정리 실패를 성공으로 보는 규칙이 `completeUpload`에만 있다. 재호출(재조정) 경로에서는 resourceId를 버린다(01-02).
- **01-03 수정의 연결 문제(Low).** 느린 업링크 설정이 runtime 정책과 presigned 실행기 두 곳에 있다. 문서대로 정책만 낮추면 실행기 deadline이 PUT을 끊는다(01-03).
- **제거 경로(Low).** file-transfer 어댑터만 지우면 게이트 3개가 실패한다. 제품 2곳은 이 영역을 조립하지 않으면서 이번 동기화로 37파일 +4,632/−2,085줄을 받았다(01-04).
- 레시피 번들은 55,623 / 55,700 gzip bytes다. 여유는 77바이트다(FOLLOW-UP 유효).
## 0. 머리말 (36.1)
| 항목 | 기록 |
|---|---|
| 영역·경로 | `src/adapters/browser-transfer/` 27파일 약 12.6k줄(`resumable-upload/` 13, `presigned/` 6, `image-cdn/` 7, 배럴 1), `src/application/ports/browser-transfer/` 약 0.8k줄, file-transfer 레시피(`config/recipes/frontend-capability-recipes.json:155-201`), 단위 테스트 15파일, Playwright spec 3개 |
| 커밋·상태 | `main` `af3d8e6`. 코드는 이 커밋과 같다. 주 워킹트리에서 쓴 파일은 이 문서 하나다 |
| 전제 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. 이 영역은 조립되지 않은 선택 레시피다. 배럴(`src/adapters/browser-transfer/index.ts`)이 공개 경계다 |
| 지난 리뷰 이후 변경 | `4626b73..af3d8e6`에서 src 11파일 +474/−77, 단위 테스트 12파일 +1,782/−44 |
| 읽은 코드 | resumable-upload 13파일 중 runtime·정책·검증·checkpoint store·lock·byte source·part 실행기·control plane·fetch 전송의 실패 경로 전부. presigned는 실행기(PUT·download deadline, vault 반환)·`http-common.ts` 상태표. image-cdn은 01-11 변경(probe 동시 상한·재사용). kernel `platform/abortable-operation.ts` 기본 타이머, `browser-file-storage/result.ts` 예외표 2개 |
| 읽은 문서(주장으로만) | `docs/architecture/presigned-transfer-and-image-cdn.md` 3.2·4.3·4.4·7절, `server-file-capability-infrastructure.md` 15.3, CHANGELOG 0.2.0, 지난 리뷰 `01-*.md`·README 11절·FOLLOW-UP |
| 실행한 명령 | 분리 worktree(`git worktree add --detach .../01/wt af3d8e6`, 메인 `node_modules` 링크)에서: 영역 단위 테스트 15파일 → **15 files / 249 tests 통과**. `check-optional-recipes.ts`(source) → file-transfer 55,623 / 55,700. Playwright `playwright.capabilities.config.ts`의 영역 spec 3개 × chromium·firefox·webkit → **9 통과** |
| worktree 안 pnpm 실행 | 실험 X4의 게이트 5개와 Playwright webServer는 worktree에서 `corepack pnpm`으로 돌렸다(`pnpm_config_verify_deps_before_run=false`). 첫 시도는 pnpm 의존성 검사에서 설치 전에 멈췄다. 이후 오케스트레이터 경고(링크된 `node_modules`를 pnpm이 지울 수 있음)를 받았다. 메인 `node_modules`는 그대로다(`.modules.yaml`·`.pnpm` 수정 시각 16:26, worktree 생성 전). 번들 제거 드릴처럼 fixture에 pnpm을 설치하는 스크립트는 돌리지 않았다 |
| 실험 | X1 `upload()` recovery 경로 6개(①~⑥)와 `abort()` 실패 1개(⑦), X2 재조정 중 삭제 실패, X3 deadline 두 겹(실제 provider·vault·실행기), X4 file-transfer 어댑터만 제거 후 게이트 5개, X5 변형 13종(M1, M6~M17. 번호는 지난 라운드와 맞췄다). 실험 파일은 scratchpad `review-2026-09-29/01/`(`zz-area01-experiments.test.ts`, `mutate.py`, 로그)에 있다. worktree는 끝난 뒤 지웠다 |
| 제품 repo 증거 | `../tech-log-frontend`, `../memento-frontend`의 `chore/template-sync-v0.2.0`을 `git grep`·`git show`로만 읽었다 |
| 확인하지 못한 범위 | 두 탭 실제 경쟁, 실제 object store·BFF, 느린 실제 네트워크, 번들 단위 제거 드릴(`test:browser-file-storage-removal`), `check:types`·`lint` 전체(오케스트레이터 PASS) |
| 지난 리뷰와 비교 | 지난 결과는 증거로 쓰지 않았다. 01-01~01-11은 현재 코드와 변형 실험으로 다시 확인했다(5절, 변형표) |
**변형 실험 X5** (코드 한 곳을 일부러 틀리게 바꾸고, 영역 테스트 12파일 215개가 실패하는지 본다)
| ID | 바꾼 것 | 결과 |
|---|---|---|
| M1 | 모든 멱등 키에 난수 추가(`upload-byte-source.ts:297-302`) | 2 실패 — 검출 |
| M6 | COMPLETE 키를 시도마다 바꿈(`resumable-upload-runtime.ts:1121`) | 3 실패 — 검출 |
| M7 | CREATE 키를 시도마다 바꿈(`:672`) | 1 실패 — 검출 |
| M8 | PART 키를 시도 번호로 바꿈(`:983`) | 4 실패 — 검출 |
| M9 | ABORT 키를 시도마다 바꿈(`:1219`) | **215 통과 — 검출 못 함** |
| M10 | `REISSUE_CAPABILITY`·`RETRY`도 `NONE`으로 번역(`:1720-1724`) | 3 실패 — 검출 |
| M11 | `toUploadAction` 무력화 | 3 실패 — 검출 |
| M12 | complete 뒤 정리 실패를 다시 실패로(`:1153`) | 1 실패 — 검출 |
| M13 | PUT의 `REISSUE_CAPABILITY` 재시도 제거(`:1060-1062`) | 3 실패 — 검출 |
| M14 | PUT deadline에서 바이트 몫 제거(`:1035-1039`) | 2 실패 — 검출 |
| M15 | abort `ALREADY_COMPLETED`에서 resourceId 조회 생략(`:1260`) | 2 실패 — 검출 |
| M16 | session 상한에서 `maxClockSkewMs` 무시(`upload-response-validation.ts:242`) | 1 실패 — 검출 |
| M17 | `ABORT_PENDING`을 `RECONCILE`로 보고(`resumable-upload-runtime.ts:409-415`) | 1 실패 — 검출 |
## 1. 대표 흐름 (체크리스트 2절)
### 1.1 정상 흐름 — 새 파일 업로드
```text
upload(request) resumable-upload-runtime.ts:169
→ 입력 snapshot·검증 → Web Lock(uploadKey) :179, :205 / upload-mutation-lock.ts:40-56
→ 파일 전체 읽기 + part별 SHA-256 manifest :363-374
→ request binding 해시 → checkpoint 읽기(없음) :375-396
→ createSession(CREATE 키) → checkpoint CAS rev1 :643-710 / indexeddb-checkpoint-store.ts:345-386
→ getStatus로 재조정 :546-641
→ part마다: 발급(PART 키) → 발급값 검증 :970-1014 / upload-response-validation.ts:38-76
→ presigned PUT(vault resolve·claim·consume, presigned-transfer-executor.ts:312-396
credentials omit, redirect error)
→ receipt 검증 → checkpoint CAS :1041-1054, :731-773
→ 재조정 → complete(COMPLETE 키) → 응답 검증 :1082-1148
→ checkpoint 삭제 → { QUARANTINED, resourceId, replayed:false } :1149-1156
```
- 정책: 파일·part 상한(`:355-362`), in-flight 바이트 상한(`runtime-policy.ts:104-107`), 재시도 상한·jitter·`Retry-After` 상한(`:1455-1504`).
- 상태 변화: IndexedDB checkpoint 행 생성 → part마다 revision 증가 → 삭제.
- 외부 I/O: BFF control plane(create·status·issue·complete), object store PUT.
- 실패: 재시도는 runtime 한 계층만 한다. 실패는 `toUploadAction`을 거쳐 5개 recovery로 나간다(`:1714-1726`).
- 결과: 이 경로는 실제 브라우저 3종에서 통과했다(`tests/browser-capabilities/resumable-upload.spec.ts:42`).
### 1.2 피해가 큰 흐름 — complete 응답 유실 (29.2)
```text
complete(COMPLETE 키) ── 서버 반영, 응답 유실(timeout)
→ 같은 키로 maxRetries번 재시도 → 모두 실패 :1110-1125
← { UNAVAILABLE, UPLOAD_COMPLETE, retryable:true, RESUME } checkpoint(ACTIVE, 모든 part 수락) 남음
경로 A: 같은 파일로 upload() → 파일 전체 재해시 → getStatus = QUARANTINED
→ checkpoint 삭제 → { QUARANTINED, resourceId, replayed:true } :583-600
(삭제가 실패하면 → { UNAVAILABLE, UPLOAD_RECONCILE, retryable:true, NONE }, resourceId 없음 — 01-02)
경로 B: abort() → ABORT_PENDING 기록 → 서버 abort = ALREADY_COMPLETED
→ getStatus로 resourceId 읽기 → checkpoint 삭제
→ { ALREADY_COMPLETED, resourceId } :1185-1278, :1281-1316
경로 C: complete 성공 + 로컬 삭제 실패 → 성공 반환, 행은 다음 호출이 정리 :1149-1156
```
- 멱등성: CREATE·PART·COMPLETE·ABORT 키는 binding·session·part에서만 만든다(`upload-byte-source.ts:289-326`). 시도·호출이 바뀌어도 같다. 변형 M1·M6·M7·M8이 검출된다.
- 서버 계약: complete 진행 중이면 `429 + Retry-After`, `409` 금지, status는 확정 전까지 `ACTIVE`(`resumable-upload.ts:222-230`). 서버 구현과의 대조는 미검증이다.
- 결과: 경로 A·B·C 모두 테스트가 있다(`tests/unit/resumable-upload-runtime-recovery.test.ts` 01-02 절). 경로 A의 삭제 실패 분기만 테스트와 수정이 없다(실험 X2).
### 1.3 변경·삭제 흐름 — file-transfer 어댑터만 제거 (실험 X4)
```text
제품이 file-transfer를 쓰지 않음
→ 제거 드릴 범위 확인: 번들 전체만 지운다 scripts/test-browser-file-storage-runtime-removal.ts:24-37
→ browser-files가 ports/browser-transfer 타입을 씀 src/adapters/browser-files/download-delivery-adapter.ts:16
→ port 폴더는 남기고 src/adapters/browser-transfer/ + 단위 테스트 15파일만 삭제
→ 게이트 실행
check:architecture PASS
check:browser-file-storage-boundaries PASS
check:types FAIL Playwright spec 2개의 import 5건
check:adapter-inventory FAIL 이름으로 고정된 필수 소비자 4파일(check-adapter-inventory.ts:139-144)
check:optional-recipes FAIL ZodError "must cover every reference runtime"(release-artifacts.ts:1147)
```
- 결과: 레시피 하나만 떼는 경로는 문서에도 드릴에도 없다. 실패 메시지 하나(ZodError)는 원인을 가리키지 않는다(01-04).
- 정책 변경 흐름(정책을 낮춘 빌드가 이전 checkpoint를 이어 감)은 테스트가 있다(`resumable-upload-runtime-recovery.test.ts:951-999`).
## 2. 28개 관점 판정표 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 굵은 번호가 이 영역에서 깊게 본 관점이다.
| 번호 | 관점 | 판정 | 목표·확인 통제 | 증거 | 근거와 잔여 위험 |
|---|---|---|---|---|---|
| **1** | 코드 성숙도 | O | 목표 M3 / 확인 M3 | E2 | checkpoint는 정확한 key 목록만 받는다(`checkpoint-schema.ts:29-143`). 상태는 `ACTIVE → ABORT_PENDING → 삭제`뿐이고 revision CAS로만 바뀐다(`indexeddb-checkpoint-store.ts:345-417`). 변형 M12·M15·M17을 잡았다 |
| 2 | 구조적 성숙도 | O | M4 | E1, 게이트 | 배럴 4개가 공개 경계다. 다른 adapter import는 kernel(`platform/`, `browser-file-storage/result.ts`)뿐이다. `check:architecture` PASS(오케스트레이터) |
| 3 | 변경 용이성 | O | M3 | E2 | 정책을 낮춘 빌드가 이전 checkpoint를 이어 간다(테스트 `recovery.test.ts:951-999`, 변형 없음). 01-08 해소 |
| 4 | 인지 부하 | P | M1~M2 | E1 | recovery 표가 포트에 생겼다(`resumable-upload.ts:104-121`). 하지만 조립에 factory 6개가 필요하고, 같은 뜻의 값(timeout·min rate·`maxRetryAfterMs`)을 여러 곳에 넣는다. 조립 예는 Playwright spec뿐이다(`resumable-upload.spec.ts:266-390`) |
| **5** | 위험 가시성 | P | 목표 M2 / 확인 M1~M2 | E2 | 29.4 문장을 코드로 채울 수 있다(1.1·1.2). complete 진행 중 계약도 포트에 있다(`resumable-upload.ts:222-230`). 남은 것: 포트 표가 6개 경로에서 틀림(01-01), 느린 링크 설정 문서가 한쪽만 적음(01-03), `abort()` 실패 뜻 없음(01-05) |
| **6** | 실패 성숙도 | P | 목표 M3 / 확인 M3(주요 경로) | E2(X1~X3, X5) | 재시도는 한 계층, 상한·jitter·`Retry-After` 상한이 있다. PUT 403·만료는 새 capability로 다시 보낸다(M13 검출). 결과 불명 complete는 재호출·abort로 조정된다(M12·M15 검출). 남은 것: 01-01, 01-02 |
| 7 | 운영 성숙도 | O | M2(연결점) | E2 | part마다 `UPLOAD_PART` 1건 + 시도 수 bucket(`resumable-upload-runtime.ts:833-839`, 테스트 `recovery.test.ts:1001-1029`). 수집·알림은 다운스트림 몫 |
| 8 | 디버깅 가능성 | P | M2 | E2 | code·operation·recovery가 닫힌 분류다. `ABORT_PENDING`은 operation `UPLOAD_ABORT`로 구분된다. 하지만 `NONE`+`retryable:true`처럼 서로 맞지 않는 조합이 나온다(01-01) |
| 9 | 유지보수 성숙도 | P | M2 | E1 | 갈라진 사본이 남았다. `isAbortSignal`은 두 벌(`checkpoint-schema.ts:195` duck typing, `http-common.ts:209` brand 검사). `MEDIA_TYPE`도 두 벌(`checkpoint-schema.ts:26` 길이 63 제한, `presigned-capability-http-provider.ts:47` 제한 없음). `RECOVERIES` 집합(`resumable-upload-runtime.ts:118-132`)은 공유 union을 손으로 복사했다. 새 값이 union에만 추가되면 provider 실패가 `UNAVAILABLE/RESUME`으로 바뀐다. 지금 도달하는 피해는 없다 |
| 10 | 테스트 성숙도 | P | 목표 M3 / 확인 M3(대부분) | E2(249 통과, 변형 12/13 검출), E3(브라우저 9 통과) | 지난 01-04 해소. 남은 것: ABORT 키 재사용은 고정되지 않았다(M9 생존). 01-05 표 테스트는 7경로만 보고 `retryable`을 단언하지 않는다(01-01). 브라우저 spec은 정상 경로만 본다 |
| 11 | 데이터 성숙도 | P | M2~M4 | E2 | 계정 partition, 저장 key allowlist, partition 삭제의 `PENDING/UNKNOWN` 보고는 그대로다. 버려진 checkpoint 정리(inventory·TTL)는 문서가 미구현으로 선언했다(`presigned-transfer-and-image-cdn.md` 4.4). 재조정 경로에서 resourceId 연결을 잃는다(01-02) |
| **12** | 동시성 성숙도 | O | 목표 M3 / 확인 M3 | E2, E3(브라우저 Web Locks·IndexedDB, 단일 탭) | 같은 uploadKey는 Web Lock으로 직렬화하고 대기는 signal로 끊긴다(`upload-mutation-lock.ts:40-56`). checkpoint는 revision CAS(`indexeddb-checkpoint-store.ts:345-386`). receipt 저장은 한 줄로 직렬화(`resumable-upload-runtime.ts:731-773`). worker 하나가 실패하면 형제를 끊는다(`:781-796`). `abort()`는 lock 전에 로컬·다른 탭 작업을 끊는다(`:255-258`). `dispose()`는 provider의 실제 작업까지 기다린다(`:1413-1424`). 두 탭 실제 경쟁은 미검증 |
| 13 | 확장성 | P | M2 | E1 | part 수와 전송 바이트 상한 검사는 조립 코드가 `maxPartCount`를 넘길 때만 돈다(`fetch-json-transport.ts:157-166`). 유일한 조립 예도 넘기지 않는다(`resumable-upload.spec.ts:329-341`) |
| **14** | 성능 성숙도 | P | 목표 M3 / 확인 M3 | E2(X3), 측정 | PUT deadline이 바이트에 비례한다(`resumable-upload-runtime.ts:1033-1039`, 실행기 `presigned-transfer-executor.ts:340-345`). download는 idle 제한이 따로 있다(`:241`). image probe는 동시 4개 상한과 통과 결과 재사용(`image-cdn-runtime.ts:197-221, 587-676`). 남은 것: part마다 SHA-256을 3번 계산한다(manifest, runtime 검증, 실행기). 재개할 때 파일 전체를 다시 해시한다. 업로드 PUT에는 idle 제한이 없다. 두 deadline의 설정이 따로다(01-03). 레시피 번들 55,623 / 55,700 gzip bytes |
| 15 | 보안 성숙도 | O | M4 | E2 | vault identity, HTTPS, `credentials:"omit"`, `redirect:"error"`, `no-referrer`는 그대로다(`presigned-transfer-executor.ts:385-396`). 쓰지 못한 capability도 `finally`에서 vault에서 뺀다(`:107-120`, 01-07 해소) |
| 16 | 의존성 성숙도 | O | M2 | E1 | 외부 패키지가 없다. WebCrypto와 자체 SHA-256만 쓴다 |
| **17** | API / Contract 성숙도 | P | 목표 M3 / 확인 M1~M3 | E2(X1) | 포트 변경은 추가형이다(`UploadAbortOutcome.resourceId?`, 정책 필드는 `Partial`로 받음 `runtime-dependencies.ts:41`). CHANGELOG 0.2.0에 [계약]으로 적혔다. 하지만 "recovery가 행동 하나를 가리킨다"는 주장은 6개 경로에서 틀리다(01-01). `abort()` 실패에는 표가 없다(01-05). 사라진 session의 발급 응답 코드는 서버 문서에 없다 |
| 18 | 배포 성숙도 | O | M3 | E2 | 정책을 낮춘 새 빌드가 이전 checkpoint를 이어 간다(01-08 해소). 모르는 schema 행은 `abort()`로 지운다 |
| 19 | 설정 성숙도 | P | M2 | E2(X3) | 각 factory는 조립 시점에 값을 검증한다. 하지만 factory 사이의 값은 서로 검사하지 않는다. 느린 링크 설정(01-03), `maxPartCount`(13행), `maxRetryAfterMs`(전송·runtime 두 곳)가 그렇다 |
| 20 | 개발자 경험 | P | M1 | E1 | resumable upload 조립 문서가 없다. 조립 예는 Playwright spec 하나다 |
| 21 | Guardrail 성숙도 | P | M3 | E2(X5), E3(X4) | 영역 규칙은 변형으로 검출된다. 하지만 `check-adapter-inventory.ts:139-144`가 이 영역 파일 이름을 고정해 레시피 단위 제거를 막는다(01-04) |
| 22 | 추상화 성숙도 | O | M3 | E1, 제품 E1 | 앱 쪽 포트는 `upload()`·`abort()` 두 개로 작다. 프로토콜 전용 내용은 control plane 포트에 있다. 번역을 한 곳에 둔 선택은 맞다(3절 D1). 제품 1곳(memento)은 백엔드가 offset-append 방식이라 이 영역 대신 자체 실행기 172줄을 만들었다(`memento-frontend` `src/adapters/http/offset-upload.ts`). 템플릿이 한 프로토콜만 지원한다는 범위를 보여 주는 사례이고 결함은 아니다 |
| 23 | 일관성 | P | M2 | E2(X1, X2) | 같은 BFF 403이 createSession에서는 `NONE`, 발급에서는 `RESUME`이다(01-01). 서버 확정 뒤 로컬 정리 실패의 처리가 complete와 재조정에서 다르다(01-02) |
| 24 | 네이밍 / 의미 성숙도 | P | M2 | E2 | `NONE`이 `retryable:true`와 함께 나온다. 닫힌 runtime이 `RESUME`을 준다(01-01) |
| 25 | 조직 확장성 | - | - | - | 적용 제외: 팀 1인. 제품 2곳의 사용 증거는 22·27행에 적었다 |
| 26 | Ownership 성숙도 | P | M1 | E0~E1 | 서버 문서는 status의 404/410만 정한다(`server-file-capability-infrastructure.md:1663`). 발급 단계에서 사라진 session을 어떤 코드로 알릴지는 주인이 없다(01-01 ③). 백엔드 멱등 키 계약은 U-5로 사용자 몫 |
| 27 | 삭제 가능성 | P | 번들 단위 M3 주장 / 레시피 단위 M0 | E3(X4), 제품 E1 | 레시피는 조립되지 않아 production 번들에서는 이미 빠져 있다. 소스 삭제는 번들 전체 단위로만 검증된다(드릴은 이번에 실행하지 않음). 어댑터만 지우면 게이트 3개가 실패한다(01-04). 제품 2곳 모두 조립하지 않으면서 이 영역을 싣고 있다 |
| **28** | 회복 가능성 | P | 목표 M3 / 확인 M3(주 경로) | E2 | 중단 뒤 재개, 결과 불명 complete의 조정(경로 A·B·C), `ABORT_PENDING`, 읽을 수 없는 행 제거가 모두 테스트된다(M12·M15·M17 검출). 남은 것: 재조정 경로 삭제 실패(01-02). 버려진 checkpoint 자동 정리는 선언된 미구현 |
충족 O 9 · 부분 충족 P 18 · 미충족 X 0 · 미검증 ? 0 · 적용 제외 1.
## 3. 설계 선택 설명 (41절)
### D1. `upload()` 실패를 포트 경계 한 곳(`toUploadAction`)에서 호출자 행동 다섯 개로 번역한다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 다운스트림 UI가 실패마다 버튼 하나(다시 / 재조정 / abort 후 다시 / 파일 다시 선택 / 없음)를 고른다. 공유 타입 `BrowserDataRecovery`는 13개 값이다(`src/application/ports/browser-file-storage/shared.ts:69-82`). upload에서 뜻이 있는 것은 5개다 |
| 2. 지킬 성질 | 모든 `upload()` 실패의 recovery가 포트 표의 한 행이다. 그 행동을 하면 상황이 나아지거나, `NONE`이면 정말 할 일이 없다 |
| 3. 현재 보장 | [확인한 사실] 번역은 한 곳이다(`resumable-upload-runtime.ts:1714-1726`). 표 밖의 값은 나가지 않는다(변형 M11 검출). [보장하지 않음] 번역 기준이 recovery 어휘뿐이다. 같은 `REOPEN`이 "파일이 바뀜"(재선택 필요)과 "IndexedDB 일시 오류"(다시 부르면 됨)를 모두 뜻하는데 둘 다 `NONE`이 된다(01-01) |
| 4. 대안 | (a) 한 곳 번역 유지 + code·retryable 기준 추가. (b) 각 출처(store·provider·file)가 포트 어휘를 직접 만든다. (c) 실패에 `action` 필드를 새로 둔다 |
| 5. 비교 | (a) 수십 줄. "`NONE`이면 `retryable:false`" 같은 불변식 하나로 검증된다. (b) 번역이 흩어진다. store·provider·file 표는 다른 포트도 쓰므로 upload 전용 어휘를 넣으면 다른 포트가 틀어진다. (c) 가장 명확하다. 공유 타입 변경이라 다른 포트까지 이행 비용이 든다 |
| 6. 판단 | 번역 위치는 유지가 맞다. [기록된 의도] 주석 `:1708-1713`은 "호출자가 직접 할 수 없는 provider 어휘를 행동으로 바꾼다"고 적는다. [리뷰어 추론] 기준만 고치면 되고 구조는 바꿀 필요가 없다 |
| 7. 재검토 조건 | 공유 recovery 어휘가 바뀔 때. `abort()`에도 표가 필요해질 때(01-05). 포트가 action 필드를 갖게 될 때 |
### D2. 멱등 키를 요청 binding·session·part에서 결정적으로 만든다 — 현 상태 유지
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 응답을 잃은 create·part·complete를 재시도하거나, 다른 탭·다음 호출에서 다시 보내도 서버가 같은 작업으로 알아본다(29.2) |
| 2. 지킬 성질 | 같은 논리 작업은 시도·호출·탭이 달라도 같은 키다. 다른 작업(새 session)은 다른 키다 |
| 3. 현재 보장 | [확인한 사실] `deriveUploadIdempotencyKey`(`upload-byte-source.ts:289-326`)는 label·request binding·sessionId·part 값만 쓴다. 시도 번호·시각·난수가 없다. session을 새로 만들 때는 이전 sessionId를 넣어 새 키를 만든다(`resumable-upload-runtime.ts:650-656`). 변형 M1·M6·M7·M8이 모두 검출된다. [보장하지 않음] 서버의 키 범위·보관 기간(U-5). ABORT 키 재사용은 테스트가 없다(M9 생존. abort는 서버에서 본래 멱등이라 피해는 작다) |
| 4. 대안 | (a) 현상 유지. (b) 호출마다 UUID를 만들어 checkpoint에 저장. (c) 키 없이 서버 상태를 먼저 조회한 뒤 쓰기 |
| 5. 비교 | (b) create 응답을 잃으면 checkpoint를 쓰기 전이라 키도 잃는다. 다음 호출이 새 키로 보낸다 — 가이드 6절의 위험 신호다. (c) 조회와 쓰기 사이에 다른 탭이 끼면 session이 둘 생긴다. (a)는 저장 없이 같은 키를 다시 만든다. 대신 같은 파일·같은 uploadKey로 다시 올리면 새 자원이 아니라 이전 자원이 `replayed:true`로 돌아온다. 포트는 uploadKey를 "caller-stable operation key"로 정해 이 비용을 계약에 둔다(`resumable-upload.ts:76`) |
| 6. 판단 | 현재 조건에서 유지할 근거가 있다. 변경 제안 없음 |
| 7. 재검토 조건 | 서버 키 보관 기간이 upload session 수명보다 짧아질 때. 같은 파일을 같은 key로 의도적으로 다시 올리는 요구가 생길 때 |
### D3. PUT 한 번에 runtime deadline과 실행기 deadline을 둘 다 건다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 느린 링크에서도 part가 끝나고, 멈춘 연결은 끊긴다(01-03). presigned 실행기는 resumable runtime 없이 download에도 쓰인다 |
| 2. 지킬 성질 | 어느 모듈을 단독으로 써도 PUT·download에 한도가 있다. 조립했을 때 설정한 최저 처리량이 실제로 적용된다 |
| 3. 현재 보장 | [확인한 사실] runtime은 `providerAttemptTimeoutMs + bytes/policy.minTransferBytesPerSecond`(`resumable-upload-runtime.ts:1033-1039`), 실행기는 `timeoutMs + bytes/options.minTransferBytesPerSecond`(`presigned-transfer-executor.ts:137-143, 340-345`). 단독 사용 시 한도는 보장된다. [보장하지 않음] 두 값이 따로 설정되고 짧은 쪽이 이긴다. 문서는 정책만 낮추라고 한다(`presigned-transfer-and-image-cdn.md:292-298`). 실험 X3에서 정책만 낮추면 실패했다(01-03) |
| 4. 대안 | (a) 두 겹 유지 + 문서에 두 곳을 적음. (b) runtime이 PUT deadline을 실행기에 넘긴다(port 입력 추가). (c) 실행기 PUT deadline 제거 |
| 5. 비교 | (a) 가장 작다. 실수는 막지 못한다. (b) 한 값이 두 계층을 정한다. `UploadPartExecutor` 입력이 바뀐다. (c) 실행기를 단독으로 쓸 때 한도가 없어진다. 성질 2를 깨므로 후보가 아니다 |
| 6. 판단 | 두 겹 자체는 유지할 근거가 있다(성질 2). 연결이 문서에만 있어야 한다면 (a), 실수를 막으려면 (b)다. 지금은 조립하는 제품이 없으므로 (a)가 비용에 맞다 |
| 7. 재검토 조건 | 제품이 이 레시피를 조립하거나 조립 helper를 만들 때 (b)를 다시 본다. 업로드 PUT에 idle 제한(FOLLOW-UP 01-03)을 넣을 때 함께 본다 |
## 4. 발견 사항 (36.3)
### 01-01 `upload()` 실패의 recovery가 6개 경로에서 포트 표와 다른 행동을 가리킨다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(공개 계약과 구현 불일치) |
| 관련 관점 | 17, 5, 6, 8, 23, 24 |
| 근거 | 포트는 "recovery가 호출자 행동 하나를 가리킨다"고 적는다(`src/application/ports/browser-transfer/resumable-upload.ts:104-121`). 문서도 같다(`docs/architecture/presigned-transfer-and-image-cdn.md:725-737`). 번역은 `toUploadAction`(`src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts:1714-1726`) 한 곳이 한다. 이 함수는 code와 단계를 보지 않는다. 표 밖의 값이면 `REISSUE_CAPABILITY`·`RETRY`만 `RESUME`으로 바꾸고 나머지는 모두 `NONE`으로 바꾼다. `retryable`은 그대로 둔다. 실험 X1 결과: ① 파일이 바뀜 — browser-files 예외표가 `NotReadableError`를 `NOT_READABLE, retryable:true, REOPEN`으로 만든다(`src/adapters/browser-file-storage/result.ts:75-79`, 파일 vault `src/adapters/browser-files/browser-file-vault.ts:474, 536`). `upload()`는 `{NOT_READABLE, UPLOAD_SESSION, retryable:true, NONE}`을 돌려준다. 다시 불러도 같다. 표대로면 `RESELECT`다. ② IndexedDB 일시 오류 — checkpoint store가 `UnknownError`를 `UNAVAILABLE, retryable:true, REOPEN`으로 만든다(`result.ts:160-164`, `indexeddb-checkpoint-store.ts:127-130`). 결과는 `{UNAVAILABLE, UPLOAD_RECONCILE, retryable:true, NONE}`이다. 같은 runtime으로 한 번 더 부르면 성공했다. ③ BFF 발급 404 — presigned provider가 `NOT_FOUND/NONE`으로 만들고(`src/adapters/browser-transfer/presigned/http-common.ts:167-170`), control plane이 그대로 넘긴다(`http-control-plane-adapter.ts:202-209`). 결과는 `{NOT_FOUND, UPLOAD_PART, retryable:false, NONE}`이다. 서버가 session을 잊은 조건에서 `upload()`를 다시 부르면 새 session으로 성공했다. ④ BFF 401/403 — 발급 단계에서는 `PERMISSION_DENIED/REISSUE_CAPABILITY`(`http-common.ts:164-166`)라서 `RESUME`이 된다. 같은 403이 createSession에서 오면 `NONE`이다(`fetch-json-transport.ts:560-561`). 표는 권한 거절을 `NONE`으로 적는다. ⑤ 닫힌 runtime — `{UNAVAILABLE, UPLOAD_SESSION, retryable:false, RESUME}`이다(`resumable-upload-runtime.ts:172-176`). 같은 runtime에 다시 부르면 늘 같은 답이다. ⑥ capability 만료가 session보다 늦음 — `POLICY_REJECTED/REISSUE_CAPABILITY`(`upload-response-validation.ts:70-74`)가 `RESUME`이 된다. 서버가 같은 값을 다시 주면 같은 실패다. 01-05 표 테스트(`tests/unit/resumable-upload-runtime-recovery.test.ts:729-890`)는 손으로 고른 7경로만 보고 `retryable`은 단언하지 않는다. 위 6경로에는 테스트가 없다 |
| 발생 조건 | ① 선택한 파일을 업로드 중이나 재개 전에 수정·이동. ② 브라우저 IndexedDB 백엔드 일시 오류. ③ BFF가 만료·정리된 session의 발급 요청에 404로 답함. ④ 세션 만료·권한 회수. ⑤ 로그아웃 teardown 뒤 늦게 도착한 호출. ⑥ 서버가 session보다 긴 capability를 줌 |
| 영향 | 포트 표대로 화면을 만든 다운스트림은 ①②③에서 "할 일 없음"으로 멈춘다. 실제로는 파일 재선택이나 재호출로 풀린다. `retryable`을 먼저 보는 다운스트림은 ①에서 같은 실패를 자기 재시도 한도까지 반복한다. ④⑥에서는 "다시 시도"가 파일 전체 재해시 뒤 같은 거절을 받는다. 데이터 손상과 부작용 중복은 없다 |
| 심각도·우선순위 | Medium · P2 — 지난 01-05와 같은 급이다. CHANGELOG 0.2.0 [계약]이 recovery 정리를 알렸으므로 다운스트림은 이 표를 믿는다. 피해는 막다른 화면과 불필요한 재해시에 그친다 |
| 통제·증거 | 7경로 M3(표 테스트) · 위 6경로 M1(주석은 있으나 구현이 다름) · E2(실험 X1. 단위 harness에서 실제 매핑 함수로 오류를 주입했다. 실제 브라우저 오류 발생은 미재현) |
| 확실성과 남은 가정 | ①②④⑤⑥은 코드와 실험으로 확정했다. ③은 "BFF가 사라진 session의 발급에 404를 준다"는 가정이 필요하다. 서버 문서는 status의 404/410만 정한다(`server-file-capability-infrastructure.md:1663`) |
| 결정의 근거 | 번역을 한 곳에 두는 선택은 유지할 만하다(3절 D1). 결함은 번역 기준이 recovery 어휘뿐이라는 점이다 |
| 이해 비용 | 다운스트림 UI 작성자는 포트 표를 믿으면 틀리고, 믿지 않으면 runtime·provider 상태표·store 예외표 세 곳을 읽어야 한다 |
| 최소 개선 방향 | `toUploadAction`이 code와 `retryable`을 함께 본다. 예: `NOT_READABLE`·`STALE_RESULT` → `RESELECT`. 표 밖이면서 `retryable:true` → `RESUME`. `UPLOAD_PART` 단계의 `NOT_FOUND`·`EXPIRED_RESOURCE` → `RECONCILE`. `PERMISSION_DENIED`와 서버 정책 거절 → 단계와 무관하게 `NONE`. 닫힌 runtime → `NONE`(또는 표에 "새 runtime 필요" 행). 불변식 "`NONE`이면 `retryable:false`"를 번역 끝에서 강제한다 |
| 대안 비교 | 3절 D1. (a) 번역 기준 보강이 가장 작다. (b) 출처마다 포트 어휘 생성은 다른 포트를 틀어지게 한다. (c) action 필드 추가는 공유 타입 변경이라 비용이 크다 |
| 단순화의 보존 조건 | 기존 7경로의 기대값(`recovery.test.ts:843-880`)을 유지한다. PUT 403 재발급(M13)과 complete 결과 보고(M12·M15)를 바꾸지 않는다 |
| 비용·부작용 | 수십 줄. 몇 경로의 recovery 값이 바뀌므로 CHANGELOG [계약] 한 줄이 필요하다 |
| 재검토 조건 | `BrowserDataRecovery`에 값이 추가될 때. 포트가 action 필드를 갖게 될 때 |
| 완료 기준 | 실험 X1의 6경로가 표의 행동과 맞는 recovery를 낸다. 모든 `upload()` 실패에서 `recovery === "NONE"`이면 `retryable === false`다 |
| 검증 방법 | 01-05 표 테스트에 6경로를 추가하고 `retryable`도 단언한다. `toUploadAction`을 지금 규칙으로 되돌리는 변형이 새 테스트를 실패시켜야 한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 01-05 수정(`426b6b8`)이 남긴 빈틈. 01-05의 완료 기준("실패 경로마다 행동 하나")은 7경로에서만 확인됐다 |
### 01-02 complete가 반영된 뒤 재조정 경로에서 checkpoint 삭제가 실패하면 resourceId를 버린다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 28, 6, 11, 23 |
| 근거 | 01-02 수정은 `completeUpload`에서만 로컬 정리 실패를 무시하고 성공을 돌려준다(`resumable-upload-runtime.ts:1149-1156`). 같은 상황의 다른 경로는 그대로다. complete 응답을 잃은 뒤 `upload()`를 다시 부르면 `reconcileActiveCheckpoint`가 status `QUARANTINED`와 resourceId를 받는다. 그다음 `removeCheckpoint`가 실패하면 그 실패를 돌려준다(`:583-589`). 문서는 "서버가 complete를 반영한 뒤 로컬 삭제가 실패해도 `upload()`는 성공"이라고 적는다(`presigned-transfer-and-image-cdn.md:382-384`). 실험 X2: 첫 호출 `{UNAVAILABLE, UPLOAD_COMPLETE, retryable:true, RESUME}`. 둘째 호출(삭제 1회 실패 주입) `{UNAVAILABLE, UPLOAD_RECONCILE, retryable:true, NONE}`, resourceId 없음. 셋째 호출 `{QUARANTINED, resource_01, replayed:true}`. 둘째 호출의 `NONE`은 01-01의 번역 때문이다 |
| 발생 조건 | complete 응답 유실 뒤 재호출에서 IndexedDB 일시 오류. status 응답 직후 caller abort도 같은 분기를 타지만 이때 `ABORTED`는 맞는 답이다 |
| 영향 | 서버에는 자원이 확정됐는데 화면은 실패를 보인다. 01-01 때문에 "할 일 없음"으로 보인다. 행은 남으므로 다음 `upload()`나 `abort()`가 같은 resourceId를 준다. 다만 파일 전체를 다시 해시한다 |
| 심각도·우선순위 | Low · P3 — 두 실패가 겹쳐야 하고 다음 호출로 복구된다 |
| 통제·증거 | complete 경로 M3(변형 M12 검출) · 재조정 경로 M0 · E2(실험 X2) |
| 확실성과 남은 가정 | 코드와 실험으로 확정했다 |
| 결정의 근거 | 적용 제외 — 01-02에서 정한 규칙("서버 확정 뒤의 로컬 정리 실패는 성공")을 같은 조건의 다른 경로에 적용하는 문제다 |
| 이해 비용 | 적용 제외 — 지역 결함 |
| 최소 개선 방향 | `reconcileActiveCheckpoint`의 `QUARANTINED` 분기에서 삭제 실패를 무시하고 `COMPLETED`를 돌려준다. caller abort는 지금처럼 `ABORTED`로 둬도 된다 |
| 대안 비교 | 적용 제외 — 기대 계약이 이미 문서에 있다 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 몇 줄. 남은 행은 다음 호출이 정리한다(경로 C와 같음) |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 실험 X2의 둘째 호출이 `replayed:true`와 resourceId를 돌려준다 |
| 검증 방법 | `recovery.test.ts`의 01-02 절에 "재조정 중 삭제 실패" 테스트를 추가한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 지난 01-02 ②와 같은 성질의 다른 경로 |
### 01-03 느린 업링크 설정이 runtime 정책과 presigned 실행기에 따로 있고, 문서는 한쪽만 바꾸라고 한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(문서와 동작 불일치) |
| 관련 관점 | 19, 5, 14, 20 |
| 근거 | PUT 한 번에 deadline이 두 개 걸린다. runtime은 `providerAttemptTimeoutMs + bytes/policy.minTransferBytesPerSecond`다(`resumable-upload-runtime.ts:1033-1039`). presigned 실행기는 자기 `timeoutMs + bytes/options.minTransferBytesPerSecond`다(`presigned-transfer-executor.ts:137-143, 340-345`, 기본 64KiB/s). 두 값은 다른 factory에 들어가고 서로 검사하지 않는다. 짧은 쪽이 이긴다. 문서는 "이보다 느리면 정책의 `minTransferBytesPerSecond`를 낮춘다"고만 적는다(`presigned-transfer-and-image-cdn.md:292-298`). 실험 X3(실제 provider·vault·실행기, fake timer, PUT 7초): runtime만 낮추면(runtime 9초, 실행기 5초) PUT 3번 뒤 `{UNAVAILABLE, UPLOAD_PART, retryable:true, RESUME}`. 실행기도 낮추면 PUT 1번에 성공했다 |
| 발생 조건 | 다운스트림이 기본 약 0.5Mbit/s보다 느린 업링크를 지원하려고 문서대로 정책만 바꾼다 |
| 영향 | 설정을 바꿨는데 그 사용자는 여전히 업로드하지 못한다. 호출마다 part를 `maxRetries+1`번 보내고 버린다 |
| 심각도·우선순위 | Low · P3 — 기본값에서는 두 값이 같다. 설정을 바꾸는 다운스트림에만 생긴다 |
| 통제·증거 | M1(문서가 한쪽만 적음) · E2(실험 X3) |
| 확실성과 남은 가정 | 실험으로 확인했다. 실제 저속 네트워크는 미검증 |
| 결정의 근거 | 두 겹 deadline은 유지할 근거가 있다(3절 D3). 실행기는 runtime 없이도 쓰이므로 자기 한도가 필요하다 |
| 이해 비용 | 조립하는 사람이 두 factory의 네 값(`timeoutMs`, 실행기 min rate, `providerAttemptTimeoutMs`, 정책 min rate)을 함께 맞춰야 한다는 사실을 코드를 읽어야 안다 |
| 최소 개선 방향 | 문서 3.x에 "실행기의 `timeoutMs`·`minTransferBytesPerSecond`도 같이 낮춘다"를 적는다 |
| 대안 비교 | 3절 D3. (a) 문서만 고침: 몇 줄, 실수는 못 막음. (b) runtime이 PUT deadline을 실행기에 넘김: port 입력 추가. (c) 실행기 deadline 제거: 단독 사용 시 한도가 사라져 후보 아님 |
| 단순화의 보존 조건 | 실행기를 단독으로 쓸 때 PUT·download에 한도가 있어야 한다 |
| 비용·부작용 | (a) 몇 줄. (b) 작음, port 변경이라 [계약] |
| 재검토 조건 | 조립 helper가 생기거나 업로드 PUT에 idle 제한을 넣을 때 (b)를 다시 본다 |
| 완료 기준 | 문서가 두 곳을 모두 적거나, 한 곳만 바꿔도 실험 X3이 성공한다 |
| 검증 방법 | 실험 X3을 `recovery.test.ts`의 01-03 절로 옮긴다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 01-03 수정(`5a6665a`)이 두 계층에 같은 식을 넣으면서 생긴 연결 문제. 지난 19행 "factory 사이 값을 서로 검사하지 않음"과 같은 계열 |
### 01-04 file-transfer 어댑터만 지우면 게이트 3개가 실패한다 — 가드레일이 이 영역 파일 이름에 고정돼 있다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 27, 21, 20 (+30.4, 30.7) |
| 근거 | 카탈로그는 file-transfer를 독립 선택 레시피로 둔다(`config/recipes/frontend-capability-recipes.json:155-201`). 제거 드릴은 browser-file-storage 번들 전체를 한꺼번에만 지운다(`scripts/test-browser-file-storage-runtime-removal.ts:24-37`). 이 한계는 주석에 기록돼 있다(`src/adapters/storage/index.ts:1-9`). browser-files는 `ports/browser-transfer/presigned-transfer.ts` 타입을 import하므로(`src/adapters/browser-files/download-delivery-adapter.ts:16`, `download-input-validation.ts:11`) port 폴더는 남겨야 한다. 실험 X4에서 `src/adapters/browser-transfer/`와 단위 테스트 15파일만 지웠다. `check:architecture`·`check:browser-file-storage-boundaries`는 통과했다. `check:types`는 Playwright spec 2개의 import 5건으로 실패했다. `check:adapter-inventory`는 이름으로 박힌 필수 소비자 4파일(`scripts/check-adapter-inventory.ts:139-144`)이 없어 실패했다. `check:optional-recipes`는 원인을 말하지 않는 ZodError "must cover every reference runtime"(`scripts/contracts/release-artifacts.ts:1147`)으로 멈췄다. 제품 증거: 두 제품의 `chore/template-sync-v0.2.0`에는 browser-transfer나 browser-file-storage 번들을 조립하는 코드가 없다(참조는 설치되지 않은 샘플 `local-draft-feature`뿐). 두 제품 모두 이 영역 37파일 +4,632/−2,085줄 변경을 이번 동기화로 받았다 |
| 발생 조건 | 번들의 일부(browser-files 등)는 쓰고 file-transfer는 빼려는 제품. 지금 제품 2곳은 번들 전체를 쓰지 않으므로 번들 드릴로도 지울 수 있다. 그러나 그렇게 하지 않았고 이유는 기록에 없다 |
| 영향 | 레시피 하나를 빼려면 드릴이 확인하지 않는 편집(게이트 스크립트·카탈로그·spec)을 손으로 해야 한다. 한 실패 메시지는 원인을 가리키지 않는다. 사용자·데이터 피해는 없다 |
| 심각도·우선순위 | Low · P3 — 지금 제품 조건에서는 번들 단위 제거로 우회할 수 있다. 가드레일이 템플릿 자신의 모양에 고정된 점은 지난 14-02와 같은 계열이다 |
| 통제·증거 | 번들 단위 제거 M3 주장(드릴은 이번에 미실행) · 레시피 단위 M0 · E3(실험 X4), 제품 repo E1 |
| 확실성과 남은 가정 | 게이트 실패는 실행으로 확인했다. `lint`·`test:unit`·build는 돌리지 않았다. 제품이 이 영역을 남긴 이유는 미확인이다 |
| 결정의 근거 | [기록된 의도] 번들 단위 드릴은 "두 폴더 중 하나만 지우는 경우는 드릴이 검증하지 않는다"고 명시한 선택이다(`storage/index.ts:6-9`). [확인한 사실] 번들 안 모듈이 port 타입을 공유하므로 번들 단위 검증이 가장 싸다. [리뷰어 추론] 드릴 범위는 유지해도 된다. 문제는 게이트가 파일 이름을 고정해 부분 제거에서 설명 없이 깨진다는 점이다 |
| 이해 비용 | 레시피를 빼려는 제품 담당자는 카탈로그, `check-adapter-inventory.ts`의 고정 목록, `optional-recipes.ts`, Playwright spec을 스스로 찾아야 한다. 이 목록은 어디에도 없다 |
| 최소 개선 방향 | (1) `check-adapter-inventory.ts`의 필수 소비자 목록을 존재하는 파일로만 검사한다. (2) `check:optional-recipes`가 사라진 sourceRoot를 "레시피 X의 경로가 없음"으로 보고한다. (3) 레시피 단위 제거 절차를 카탈로그의 `removal`이나 문서에 적는다 |
| 대안 비교 | (a) 현상 유지: 비용 없음, 부분 제거는 손으로. (b) 위 (1)~(3): 게이트 두 곳 + 문서. (c) 드릴에 `--recipe=file-transfer` 모드 추가: 가장 확실하지만 CI 시간이 드릴 한 번만큼 늘어난다. 조립하는 제품이 없으므로 (b)가 비용에 맞다 |
| 단순화의 보존 조건 | 파일이 있을 때 `check-adapter-inventory`는 abort 사본 재발을 계속 막아야 한다. 번들 전체 제거 드릴은 그대로 통과해야 한다 |
| 비용·부작용 | 게이트 스크립트 두 곳, 문서 몇 줄 |
| 재검토 조건 | 제품이 번들의 일부만 조립하기 시작하면 (c)를 다시 비교한다 |
| 완료 기준 | browser-transfer 어댑터만 지운 fixture에서 `check:adapter-inventory`와 `check:optional-recipes`가 원인을 말하는 메시지로 실패하거나 통과한다 |
| 검증 방법 | 실험 X4를 다시 실행한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 지난 27행은 "미검증(드릴 미실행)"이었다. 새로 확인한 사실이다. 12(가드레일)·14(템플릿·제품) 영역과 겹칠 수 있다 |
### 01-05 `abort()` 실패의 recovery에는 호출자 행동 표가 없다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 17, 5, 24 |
| 근거 | 행동 표는 `upload()`에만 있다(`resumable-upload.ts:104-121`). `abort()`는 `toUploadAction`을 거치지 않는다(`resumable-upload-runtime.ts:237-278`). 그래서 store의 `REOPEN`·`READ_ONLY`·`RETRY`와 provider 값이 그대로 나온다. 서버가 모르는 state를 주면 `CORRUPT_DATA/UPLOAD_ABORT/RECONCILE`이다(`:1241-1253`). 표에서 `RECONCILE`은 "`upload()`를 다시 부른다"다. 그런데 그러면 `ABORT_PENDING` 때문에 `RESTART`("먼저 `abort()`")가 온다(실험 X1 ⑦). 표의 `RESTART` 행이 호출자를 `abort()`로 보내므로 `abort()` 실패의 뜻도 정해져야 한다 |
| 발생 조건 | abort 중 IndexedDB 오류, 서버 409·5xx·형식이 틀린 응답 |
| 영향 | 다운스트림이 `abort()` 실패를 각자 해석한다. 형식이 틀린 서버 응답에서는 사람이 `upload()`와 `abort()`를 번갈아 누르는 순환이 생긴다(자동 반복은 아님) |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M0(abort 행동 표 없음) · E2(실험 X1 ⑦) |
| 확실성과 남은 가정 | 코드와 실험으로 확인했다 |
| 결정의 근거 | 적용 제외 — 이미 정한 upload 표를 abort로 넓히는 문제다 |
| 이해 비용 | abort 실패 처리를 정하려면 runtime·store·전송 상태표를 읽어야 한다 |
| 최소 개선 방향 | 포트 주석에 `abort()` 실패의 행동(`abort()` 다시 / 할 일 없음)을 적고, `abort()`에도 01-01과 같은 번역을 둔다 |
| 대안 비교 | 적용 제외 — 01-01의 번역 기준을 공유한다 |
| 단순화의 보존 조건 | `ABORT_PENDING` 유지, `ALREADY_COMPLETED`의 resourceId 반환(M15)을 바꾸지 않는다 |
| 비용·부작용 | 작음 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | `abort()` 실패 경로마다 recovery가 포트에 적힌 행동 하나다 |
| 검증 방법 | 01-05 표 테스트와 같은 each 테스트 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 지난 01-05는 `upload()`만 다뤘다 |
## 5. FOLLOW-UP 재확인
지난 라운드 발견 01-01~01-11의 해소 여부는 머리말 변형표(M12~M17 등)와 판정표에 적었다. 모두 현재 코드에 수정과 검출 테스트가 있다(01-06은 결정으로 종료). 아래는 `FOLLOW-UP.md`의 이 영역 항목이다.
| FOLLOW-UP 항목 | 결과 | 현재 근거 |
|---|---|---|
| 1절 P2 file-transfer 레시피 번들 예산 55,600 → 55,700, 코드를 줄이지 않음 | **유효** | 측정 55,623 / 55,700 gzip bytes(여유 77바이트, `check-optional-recipes.ts` source 실행). 예산 이력은 52,000 → 54,600 → 55,600 → 55,700으로 라운드마다 측정값 + 약 100바이트로 올렸다(`docs/operations/adapter-remediation-ledger.md:441-450, 459`, 커밋 `6fe4aa9`, `4b0e44a`). 늘어난 원인별 분석은 없다. 다음 수정이 이 영역에 77바이트 넘게 더하면 게이트가 실패한다 |
| 1절 P2 `check:remediation-ledger`의 file-transfer 예산 문구 | **유효** | 원장은 54,600을 적는다(`adapter-remediation-ledger.md:448, 459`). 제품 `tech-log-frontend` 동기화 기록도 `af3d8e6`에서 이 검사가 실패한다고 적는다(`docs/operations/template-sync-2026-09-29.md:473`). 전체 판단은 12영역 몫 |
| 4절 P3 01-06 하한은 skew를 반영하지 않음(사용자 결정) | **유효**(결정 유지) | 조건이 문서에 있다(`presigned-transfer-and-image-cdn.md:167-174`). 상한 쪽 skew는 변형 M16이 검출된다 |
| 4절 P3 01-11 probe 재사용 테스트가 공개 이미지만 씀 | **유효** | `tests/unit/image-cdn-runtime.test.ts:1444-1578`의 3개 테스트가 모두 `acceptPublicImmutable(publicAsset())`을 쓴다. capability가 필요한 비공개 이미지 경로의 재사용·만료 재확인은 테스트가 없다 |
| 4절 P3 01-09 바이트 한도 검사는 transport에 `maxPartCount`를 넘길 때만 동작 | **유효** | `fetch-json-transport.ts:157-166`. 유일한 조립 예도 넘기지 않는다(`resumable-upload.spec.ts:329-341`) |
| 4절 P3 01-03 업로드 PUT에 idle 제한 없음 | **유효** | 문서가 그렇게 적는다(`presigned-transfer-and-image-cdn.md:295-297`). 멈춘 5MiB part는 약 110초 뒤 끊긴다. 01-03(이번)의 두 deadline 문제와 함께 볼 항목이다 |
| 5절 P2 `resumable-upload.spec.ts:7` `PAGE_ORIGIN` 포트 4174 고정 | **유효** | `tests/browser-capabilities/resumable-upload.spec.ts:7`. 설정은 `playwright.capabilities.config.ts:24, 30-31`에서 따로 4174를 쓴다. 이번 브라우저 실행은 기본 포트라 통과했다 |
## 6. 미검증 목록
| 항목 | 이유 | 확인하려면 |
|---|---|---|
| 두 탭이 같은 uploadKey로 동시에 upload/abort | 단위 테스트는 메모리 lock·채널만 쓴다. 브라우저 spec은 탭 하나다 | Playwright page 두 개에서 같은 key로 upload와 abort를 겹친다 |
| 01-01 ①②가 실제 브라우저에서 나는 조건 | 실험은 실제 예외 매핑 함수로 주입했다. 파일 수정·IndexedDB 오류를 브라우저에서 일으키지 않았다 | 브라우저에서 선택한 파일을 바꾼 뒤 `openSource` 스트림으로 upload |
| BFF가 사라진 session의 발급에 주는 응답 코드 | 서버 문서는 status만 정한다 | 서버 계약에 발급 단계 404/410 의미를 추가하고 conformance 테스트 |
| 실제 object store의 PUT 403 조건, 같은 키 재발급 응답, complete 소요 시간 | repo 밖 시스템 | provider conformance 테스트(서버 문서 10.2) |
| 저속 실제 네트워크 | 실험은 fake timer | 네트워크 throttling(0.3Mbit/s)으로 5MiB part 업로드 |
| part 버퍼 실제 메모리(copyFactor 4 추정) | 측정 환경 없음 | 브라우저 메모리 프로파일 |
| 번들 단위 제거 드릴 | `test:browser-file-storage-removal`은 fixture에 pnpm을 돌리는 무거운 스크립트라 동시 작업 중 돌리지 않았다 | 단독 환경에서 실행 |
| 레시피 단위 제거 뒤 `lint`·`test:unit`·build | 실험 X4는 게이트 5개만 돌렸다 | X4 fixture에서 나머지 게이트 실행 |
| 레시피 번들 증가분의 원인별 크기 | 모듈별 측정 도구가 없다 | 번들 metafile로 모듈별 gzip 기여를 뽑는다 |
| logout 때 checkpoint partition 삭제 순서 | 조립 코드가 repo에 없다(`AVAILABLE_NOT_COMPOSED`) | 다운스트림 조립에서 `dispose()` → `deletePartition()` 순서 검증 |
@@ -0,0 +1,392 @@
# 02 — browser-files / cache-storage / cross-context-invalidation 성숙도 리뷰
> 검토일: 2026-09-29 · 기준: `main` / `af3d8e6` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`, `docs/reviews/TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md`
> 영역 판정(35.8): **조건부 사용 가능** — cross-context-invalidation과 browser-files는 지금 범위에서 쓸 수 있다. cache-storage는 정책 값을 바꾸는 배포 전에 02-01을 고쳐야 한다.
## 0. 머리말
### 0.1 결론
- 지난 라운드의 02 발견 9건은 현재 코드에서 회귀가 없다. 코드·테스트로 고친 7건(02-01·02-02·02-04~02-08)의 규칙 12개에 변이를 넣었고 테스트가 모두 잡았다(6.2절).
- 새로 확인한 가장 큰 문제는 **Cache Storage의 active pointer를 현재 정책으로 검증한다는 점이다(02-01, Medium).**
- `retainedPreviousReleaseCount`를 줄인 배포나 pointer 손상 뒤에는 조회·활성화·정리가 모두 `CORRUPT_DATA`로 멈춘다.
- 어댑터 API로는 되돌릴 방법이 없다. 배포마다 캐시가 하나씩 쌓인다.
- 실제 Chromium·Firefox·WebKit Cache API에서 재현했다.
- cross-context-invalidation의 kernel 예외는 지금 query-cache의 **타입 import 2개**에만 쓰인다. 예외는 barrel 전체(런타임 팩토리 포함)를 모든 adapter에 연다. 타입을 contracts로 옮기면 예외 없이 게이트를 통과한다(02-06, 개선 제안, 소유자 결정 필요).
- 나머지는 Low다. `inspect()`의 비용·취소·판정 불가 표현(02-02), CHANGELOG 0.2.0의 영향 경로 오류(02-03), 설계 문서 줄 번호 drift(02-04, FOLLOW-UP 02-09 유효), handoff 실패 시 lease 반환 규칙의 테스트 공백(02-05).
### 0.2 리뷰 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 | `clean-architecture-frontend-template`, 영역 02 |
| 커밋·작업 상태 | `main` / `af3d8e6`(태그 `v0.2.0` + docs 1). 워킹트리의 미커밋 변경은 리뷰 가이드 문서 2개뿐이고 코드는 `af3d8e6`과 같다 |
| 목적과 실행 구성 | 템플릿. 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음 |
| 조립 상태 | cross-context-invalidation은 기본 조립이다(`src/bootstrap/runtime-adapters.ts:359-403`). browser-files는 file-transfer recipe, cache-storage는 service-worker-pwa recipe의 `AVAILABLE_NOT_COMPOSED` 런타임이다(`config/recipes/frontend-capability-recipes.json:121-128`). repo 안에서 두 런타임을 조립하는 코드는 없다 |
| 제품 repo 증거 | `tech-log-frontend`, `memento-frontend`(둘 다 `chore/template-sync-v0.2.0`)는 세 폴더를 `af3d8e6`과 똑같이 들고 있다(`git diff af3d8e6 <branch> -- <3 폴더>` 차이 없음). 둘 다 cross-context만 `src/bootstrap/runtime-adapters.ts`에서 쓰고 browser-files·cache-storage는 조립하지 않는다 |
| 규모·운영 목표 | 합의된 목표 없음. 상한 값(개수·바이트)만 코드에 있다 |
| 읽은 코드 | 세 폴더 전체(18파일, 8,140줄). 포트 `src/application/ports/browser-file-storage/{file,shared,cache-storage-ports}.ts`. kernel `src/adapters/browser-file-storage/result.ts`. 계약 `src/contracts/cache-invalidation.ts`. 소비·조립 `src/adapters/query-cache/tanstack-cache-coordinator.ts`, `src/bootstrap/runtime-adapters.ts:330-420`, `src/bootstrap/server-state-generation-store.ts` |
| 읽은 설정·문서(주장) | `.dependency-cruiser.json:241-251`, `docs/architecture/layers.md:40-60`, `CHANGELOG.md` 0.2.0, `README.md:315-340`, `docs/architecture/browser-file-and-origin-storage.md` 3.5·8.3·9절, `docs/architecture/client-cache-and-storage.md` 앞부분 |
| 실행한 테스트 | 영역 unit 11파일 → **146/146 통과**(`node scripts/run-vitest.ts run tests/unit/{browser-file-*,cross-tab-invalidation,public-response-cache*,tanstack-cache-coordinator,abortable-operation}.test.ts`) |
| 실행한 브라우저 테스트 | 분리 worktree에서 `tests/browser-capabilities/{browser-files,cross-context-invalidation,public-cache-storage}.spec.ts`를 chromium·firefox·webkit으로 실행 → **21/21 통과**. 다른 에이전트와 포트가 겹치지 않게 설정 사본의 포트만 4192로 바꿨다 |
| 실험 | E-1 pointer 호환성(Node, 테스트 대역) · E-2 같은 시나리오를 실제 Cache API 3엔진에서 · E-3 변이 19개 · E-4 kernel 예외 probe 2개 · E-5 browser-file-storage 런타임 제거 드릴. 결과는 해당 절에 적었다. worktree는 끝나고 지웠다 |
| 확인하지 못한 범위 | 실제 제품 화면에서의 사용(소비자 없음). 다른 탭에서 계정이 바뀐 뒤의 무효화 hint 영향(auth 영역 의존). Safari의 blob URL 30초 grace 충분성. 7절에 정리했다 |
| 이전 리뷰와 비교 | `docs/reviews/2026-09-25-maturity-review/02-adapters-browser-files-cache.md`(`4626b73`). 지난 결과는 증거로 쓰지 않았고 현재 코드와 실행으로 다시 확인했다 |
### 0.3 실험 기록
| ID | 방법 | 결과 |
|---|---|---|
| E-1 | worktree에 `tests/unit/zz-review02-pointer.test.ts`를 임시로 두었다. `MemoryCacheStorage` 위에서 retained 3으로 release 3개를 활성화한 뒤, 같은 저장소에 retained 1 정책으로 adapter를 새로 만들었다. pointer JSON을 잘라 넣는 경우도 따로 돌렸다 | 조회·활성화·정리·inspect가 모두 `CORRUPT_DATA`/`REHYDRATE`. stage는 성공해 캐시만 늘어난다. 손상 JSON 경우도 활성화 2회와 정리가 같은 실패 |
| E-2 | 같은 시나리오를 Playwright로 실제 `caches`·`navigator.locks`에서 실행(`tests/browser-capabilities/zz-review02-pointer.spec.ts`, 임시) | chromium·firefox·webkit 모두 `{"lookup":"CORRUPT_DATA","deploys":[{"staged":"ok","activated":"CORRUPT_DATA"} ×2],"cleanup":"CORRUPT_DATA","ownedCaches":6}` |
| E-3 | 규칙 한 줄씩 바꾸고 관련 unit 파일만 실행 | 19개 중 14개 검출, 5개 생존. 표는 6.2절 |
| E-4 | P1: `src/adapters/realtime/`에 cross-context 런타임 팩토리를 import하는 파일 추가. P2: query-cache가 쓰는 3개 멤버 타입을 `src/contracts/cache-invalidation.ts`로 옮기고 kernel 예외에서 `cross-context-invalidation/index.ts`를 뺐다 | P1: `check:architecture` 통과(예외가 런타임까지 연다). P2: `check:architecture` 통과, `tsc -p tsconfig.app.json`·`tsconfig.test.json` 오류 0, 관련 unit 30/30 통과 |
| E-5 | worktree에서 `corepack pnpm test:browser-file-storage-removal`(바깥 pnpm의 설치 점검은 `pnpm_config_verify_deps_before_run=false`로 껐다). worktree의 `node_modules`는 메인 repo로의 심볼릭 링크였다. 이 방식은 pnpm이 링크를 통해 메인 `node_modules`를 설치·삭제할 위험이 있다는 오케스트레이터 경고를 받기 **전에** 실행했다 | 3회 실행, 3회째 PASS. 상세는 2.3절. 세 로그 모두 설치·삭제 시도(`ERR_PNPM`, `Packages:`, `Progress:`)가 없다. 메인 `node_modules/.modules.yaml`·`.pnpm/lock.yaml` 수정 시각은 첫 실행 전(16:26) 그대로다. 다음 리뷰에서는 이 드릴을 worktree에서 pnpm으로 돌리지 않는다 |
`check:architecture`는 worktree에서 pnpm이 설치 점검을 시도하지 않도록 `npm_execpath`에 `pnpm exec`만 대신하는 shim을 넣어 실행했다.
## 1. 확인된 강점
1. **캐시에 사용자 응답이 들어갈 경로를 여러 겹으로 막고, 그 규칙이 테스트로 고정돼 있다.** stage 요청은 `credentials: "omit"`, `mode: "same-origin"`, `redirect: "error"`다(`src/adapters/cache-storage/public-cache-response-validation.ts:223-238`). `private`·`no-store`·`Set-Cookie`·`Vary: Cookie` 응답은 거절한다(`:54-66`, `:187-193`). `credentials`를 `"include"`로 바꾼 변이는 테스트가 잡았다(E-3 M08).
2. **캐시 교체는 검증 뒤에만 성공을 말한다.** 기존 후보는 교체본이 검증되기 전에 지우지 않고(`public-response-cache-adapter.ts:452-498`), abort 뒤에는 자산·marker를 쓰지 않는다(`:416-437`, `:566-569`). 활성화는 후보의 모든 entry를 다시 읽고 SHA-256을 맞춘다(`:672-691`, `:1068-1118`). 실제 3엔진에서 "B stage 실패 중에도 A 유지 → B 활성화 → owned만 정리"가 통과했다.
3. **여러 탭의 중복·역순·누락을 명시적으로 처리한다.** eventId 중복 제거, source별 watermark, 빠진 순번은 `GAP` → 전체 topic 무효화(`browser-cross-context-invalidation.ts:484-514`, `tanstack-cache-coordinator.ts:109-116`). STALE 검사와 `storageArea` 검사를 지운 변이는 테스트가 잡았다(M11, M12). 실제 3엔진에서 BroadcastChannel과 localStorage fallback이 모두 통과했다.
4. **파일 이름·MIME을 신뢰하지 않는다.** 저장 이름은 정책의 `safeExtension`만 붙이고 실행 확장자를 무력화한다(`file-policy.ts:310-371`). preview MIME은 서명 바이트에서 오고, 그 타입으로 Blob을 다시 만든다(`object-url-lease.ts:296-318`).
5. **취소·닫기·권한 거부·자원 소진을 Result에서 구분한다.** 닫은 선택 창·저장 창은 `DISMISSED` 성공이고(`browser-file-picker.ts:283-288`, `download-delivery-adapter.ts:531-569`) 관측에서도 `DISMISSED`로 남는다(`file-observer.ts:28-44`). 같은 턴 abort는 `ABORTED`다(`object-url-lease.ts:292-295`). lease 소진은 `retryable:true`, 단일 Blob 한도 초과는 재시도 불가다(`object-url-lease.ts:53-71`, `:122-139`).
## 2. 대표 흐름
### 2.1 정상 흐름 — 탭 A의 저장이 탭 B의 캐시를 무효화한다
```text
탭 A: 명령 성공 → coordinator.invalidate(topics) tanstack-cache-coordinator.ts:184-205
→ invalidateLocal: 활성 query refetch :62-93
→ crossContext.publish({topic, topicVersion}) browser-cross-context-invalidation.ts:292-365
→ 자기 envelope 검사 → sequence+1 → BroadcastChannel.postMessage
→ postMessage가 던지면 localStorage pulse(setItem → removeItem) :377-439
탭 B: message / storage 이벤트
→ parse: protocol·cacheEpoch(같은 release)·topic 버전·TTL contracts/cache-invalidation.ts:123-205
→ storage 이벤트는 캡처한 localStorage와 같은 객체만 browser-cross-context-invalidation.ts:197-212
→ SELF_ECHO / DUPLICATE / STALE 폐기, 순번이 빠지면 GAP :469-514
→ coordinator.receiveRemote → pendingRemote(GAP이면 전체 topic) tanstack-cache-coordinator.ts:95-118
→ 그 topic의 mutation lease가 없을 때 invalidateQueries :120-157
```
| 단계 | 내용 |
|---|---|
| 입력 | 명령 성공 뒤의 등록 topic과 version |
| 정책 | 등록 topic만, 같은 release(`cacheEpoch`)끼리만, TTL 60초(`browser-cross-context-invalidation.ts:160`) |
| 상태 변화 | 탭 B의 TanStack 캐시가 stale이 되고 활성 query가 다시 읽힌다 |
| 외부 I/O | BroadcastChannel, localStorage `storage` 이벤트 |
| 실패 | 두 전송이 모두 없으면 `DEGRADED_LOCAL_ONLY`이고 `cache.operation.failed` 진단을 남긴다(`runtime-adapters.ts:374-386`). 부팅은 막지 않는다 |
| 결과 | 성공 시 탭 B가 새 값을 읽는다. 실패 시 탭 B는 focus refetch 전까지 오래된 값을 본다. release가 다른 탭끼리는 hint가 오가지 않는다(설계상 선언) |
### 2.2 피해가 큰 흐름 — Cache Storage release 배포와 정책 변경
```text
빌드 manifest → admin.stageRelease public-response-cache-adapter.ts:387-606
→ manifest digest 검증 → Web Lock → 자산 fetch(익명) → 검증 → put → marker
→ admin.activateRelease(id, digest) :608-759
→ 후보 전체 재검증 :672-691
→ 이전 pointer 읽기 ← 여기서 CORRUPT_DATA면 끝 :693-702
→ 새 pointer(current + rollback 목록) put
→ responses.matchActiveExact(url) :217-383
→ keys → pointer 읽기 ← 같은 검증 :246-254
→ admin.cleanupOwned() :761-844
→ pointer 읽기 ← 같은 검증 :783-789
pointer 검증 isActivePointer public-cache-codec.ts:430-469
→ rollback 목록 길이 ≤ 현재 retainedPreviousReleaseCount :455-456
→ releaseRegistryId가 현재 정책에서 허용 :441, :459-464
```
| 단계 | 내용 |
|---|---|
| 입력 | 빌드가 만든 manifest, composition이 준 정책 |
| 정책 | 검증한 후보만 활성화, 보존 집합은 pointer와 `retainedPreviousReleaseCount`로 계산(`browser-file-and-origin-storage.md:966-968`) |
| 상태 변화 | release cache 추가, control cache의 pointer 교체, 오래된 owned cache 삭제 |
| 외부 I/O | fetch, Cache API, Web Locks |
| 실패 | 정책을 바꾼 배포(E-2에서는 retained 3 → 1)나 pointer 손상 뒤에는 조회·활성화·정리·inspect가 모두 `CORRUPT_DATA`/`REHYDRATE`다. REHYDRATE를 따라 다시 stage·activate해도 activate가 같은 pointer에서 멈춘다 |
| 결과 | 오프라인 자산 캐시가 계속 꺼지고, 배포마다 release cache가 하나씩 쌓인다(E-2 `ownedCaches: 6`). 되돌리는 방법은 사용자가 사이트 데이터를 지우는 것뿐이다 → **02-01** |
### 2.3 변경·삭제 흐름
**변경 — cross-context kernel 예외를 없애는 작업(E-4 P2)**
```text
query-cache가 쓰는 타입 3개 멤버(publish·subscribe·close) + delivery 타입
→ src/contracts/cache-invalidation.ts에 13줄 추가
→ tanstack-cache-coordinator.ts:16-19 import 1곳 변경
→ .dependency-cruiser.json:250 pathNot에서 cross-context-invalidation/index.ts 삭제
→ check:architecture PASS · tsc app/test 0 errors · unit 30/30
```
바꾼 곳은 3파일이다. bootstrap이 넘기는 `BrowserCrossContextInvalidation`은 새 타입에 구조적으로 들어맞아 조립 코드는 그대로다. 문서는 `layers.md:47-49`와 규칙 주석 두 곳을 같이 고쳐야 한다 → **02-06**
**삭제 — browser-file-storage 런타임 제거 드릴(E-5)**
`scripts/test-browser-file-storage-runtime-removal.ts`는 browser-files·cache-storage·browser-transfer·storage/indexeddb·opfs와 포트를 fixture에서 지우고 게이트를 다시 돌린다(`:24-37`). cross-context-invalidation은 기본 조립이라 대상이 아니다.
세 번 돌렸다.
| 회차 | 결과 | 실패 내용 |
|---|---|---|
| 1 | test 단계 실패 | component 3개 시간 초과(`boot-unexpected-failure`, `runtime-application`, `router`). 당시 부하 평균 약 36(22코어) |
| 2 | test 단계 실패 | integration `provider-guardian-transaction` 1개 시간 초과. component는 211/211 통과 |
| 3 | **PASS** | `Browser file/storage runtime removal: PASS (7 base checks, 55 runtime-dependent tests removed by import graph)`. 55개에는 리뷰용 임시 테스트 1개가 들어 있다 |
- 타입 검사·lint·`check:architecture`·빌드·optional recipes·CI 계약은 세 번 모두 통과했다.
- 1·2회의 실패 테스트는 제거하지 않은 worktree에서 단독으로 다시 돌려 모두 통과했다. `runtime-application`과 `provider-guardian-transaction`은 FOLLOW-UP 3절의 알려진 부하 flaky다.
- 결론: 런타임 묶음은 지금 지울 수 있다. 다만 이 드릴의 test 단계도 부하 flaky 테스트를 그대로 물려받는다(영역 10·11 몫).
## 3. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 굵은 번호는 깊게 본 관점이다.
| 번호 | 관점 | 판정 | 목표·확인 통제 | 증거 | 근거와 잔여 위험 |
|---|---|---|---|---|---|
| **1** | 코드 성숙도 | P | 목표 M2 / 확인 M2 | E2, E3 | lease 수·바이트 상한, preview의 같은 턴 abort(`object-url-lease.ts:292-295`), 캐시의 "검증 뒤에만 성공"은 코드와 테스트로 지켜진다(M01·M04 검출). 다만 pointer의 유효성을 **저장 당시가 아니라 현재 정책**으로 판단한다(`public-cache-codec.ts:441`, `:455-456`). 정책이 바뀌면 멀쩡한 pointer가 손상으로 분류된다(02-01) |
| 2 | 구조적 성숙도 | P | M3 / M3 | E3(E-4) | adapter 사이 import는 kernel만 쓴다. `check:architecture`가 이를 강제한다. kernel 예외는 쓰임(타입 2개)보다 넓어 런타임 팩토리까지 모든 adapter에 열린다(P1 통과, 02-06) |
| 3 | 변경 용이성 | O | M2 / M2 | E1, E3 | 새 파일 정책은 profile 추가, 새 topic은 registry 추가로 끝난다. 예외 제거 같은 구조 변경도 3파일이었다(E-4 P2) |
| 4 | 인지 부하 | P | — / — | E1 | 본 파일 2개가 1.1k줄대다(`download-delivery-adapter.ts` 1,157, `public-response-cache-adapter.ts` 1,185). 리뷰 ID 주석이 37곳이다. 대부분 이유 문장이 따라와 39.8절의 "ID만 있는 주석"은 아니다 |
| **5** | 위험 가시성 | P | M1~M2 / M1~M2 | E1, E3 | `BROWSER_HANDOFF`/`SAVED`/`DISMISSED`, `integrity: NOT_PROVIDED`, `retryable` 구분은 호출자가 읽을 수 있다. 그러나 pointer 실패의 `recovery: "REHYDRATE"`(`public-response-cache-adapter.ts:1016-1020`)는 존재하지 않는 복구 경로를 안내한다(02-01). `inspect()`는 모든 후보의 모든 바이트를 읽고 해시하는데 포트에 signal이 없고 문서는 cache 수 비례로만 적는다(`cache-storage-ports.ts:84`, `browser-file-and-origin-storage.md:974-977`, 02-02) |
| **6** | 실패 성숙도 | P | M2 / M2 | E2, E3 | 취소·닫기·권한·소진·무결성을 나누고 늦게 온 자원을 kernel race로 보상한다(`download-delivery-adapter.ts:601-609`, `:917-929`). pointer가 한번 읽히지 않으면 활성화·정리가 영구히 멈춘다(02-01, E-2). handoff가 실패했을 때 lease를 반환하는 규칙은 코드에 있지만 테스트가 없다(`:853-854`, M10 생존, 02-05) |
| 7 | 운영 성숙도 | P | M2 / M2 | E1 | cross-context 실패·저하는 bootstrap이 진단으로 연결한다(`runtime-adapters.ts:374-386`). file·cache observer는 recipe 조립 몫이라 repo에서는 연결되지 않는다 |
| 8 | 디버깅 가능성 | P | M2 / M2 | E1 | 관측에 파일명·URL·키가 없다. 저장 창 닫기와 handoff 성공이 이제 구분된다(M06 검출). 다만 pointer 손상과 marker 손상이 같은 `CORRUPT_DATA`·`CACHE_LOOKUP`으로 남아(`public-response-cache-adapter.ts:973-975`, `:1017-1019`) 02-01 상태를 관측만으로는 알아보기 어렵다 |
| 9 | 유지보수 성숙도 | P | M1 / M1 | E1 | 설계 문서의 줄 번호가 다시 밀렸다(FOLLOW-UP 02-09 유효, 02-03 수정에서 넣은 참조 3개도 1줄씩 밀림 → 02-04). CHANGELOG 영향 경로가 실제와 다르다(02-03) |
| 10 | 테스트 성숙도 | P | M3 / M3 | E2(146 통과), E3(브라우저 21 통과, 변이 19) | 지난 수정 규칙 12개는 모두 검출. 생존 5개: inspect의 판정 불가(M05, 02-02), handoff 실패 lease 반환(M10, 02-05), pointer 호환 규칙 2개(M13·M14, 02-01 완료 기준에 포함). M09(preview 단독 dispose)는 runtime 조립에서는 download dispose가 같은 registry를 비워 동등하다 |
| **11** | 데이터 성숙도 | P | M2 / M1 | E3(E-2) | Cache Storage에는 익명 공개 응답만 들어가 로그아웃 purge가 필요 없다(M08 검출). control 데이터(pointer)는 `schemaVersion: 1`만 있고, 정책이 달라진 배포에서 읽는 호환 규칙이 없다. 멈춘 동안 release cache가 계속 쌓여 origin 저장 한도를 쓴다(02-01). 소유 prefix를 바꾸는 배포는 옛 캐시를 정리하지 않는다(문서화된 제한, `browser-file-and-origin-storage.md:1004-1008`) |
| **12** | 동시성 성숙도 | O | M3 / M3 | E2, E3 | 탭 간 중복·역순·누락(M11 검출), 캐시 변경의 Web Lock 직렬화(실제 `navigator.locks`로 3엔진 통과), picker별 pending, 같은 턴 abort(M01 검출). stage 뒤 activate 전 cleanup이 후보를 지우는 창은 문서화된 허용이다(`browser-file-and-origin-storage.md` 8.3절) |
| 13 | 확장성 | O | M2 / M2 | E1 | source 256·dedupe 1,024 LRU(`browser-cross-context-invalidation.ts:160-166`), 정책 profile·entry·바이트 상한. 부하 측정은 없다(목표 없음) |
| 14 | 성능 성숙도 | P | M2 / M2 | E1, E2 | 조회 한 번은 `keys()` 1회·본문 복사 2회다(M07 검출). `inspect()`는 후보 수 × 최대 128 MiB를 읽고 해시하며 중간에 멈출 수 없다(02-02) |
| **15** | 보안 성숙도 | O | M2~M3 / M3 | E2, E3 | 익명 캐시 요청(M08), 파일명 무력화, 서명 기반 MIME, active content 금지, canonical handoff URL, 불투명 참조. 지난 02-08의 규칙별 테스트가 유지된다. wire event에 계정 scope가 없는 것은 설계상 선언(`client-cache-and-storage.md:99-101`)이라 결함으로 세지 않았다(7절 미검증) |
| 16 | 의존성 성숙도 | - | — | E1 | 세 폴더 모두 외부 패키지 import가 없다(`grep 'from "[^.]'` 0건) |
| 17 | API / Contract 성숙도 | P | M2 / M2 | E1 | 포트 타입과 wire 계약은 닫혀 있다. CHANGELOG 0.2.0 [계약] 행의 영향 경로·recipe·표현이 실제 변경과 다르다(02-03). `PublicCacheInspection.verified`에 뜻 설명이 없다(02-02) |
| 18 | 배포 성숙도 | P | M2 / M0(정책 변경 호환) | E3(E-2) | release별 cacheEpoch와 후보 stage/activate/보존은 있다. 정책 값을 바꾼 배포 하나가 이후 모든 배포의 캐시 활성화를 막는다(02-01) |
| 19 | 설정 성숙도 | P | M3 / M3 | E2 | 잘못된 상한·정책은 조립 시 TypeError다. 그러나 `retainedPreviousReleaseCount`(1~5, `public-cache-policy.ts:124-126`)를 줄이는 정상 설정 변경이 런타임을 멈춘다(02-01) |
| 20 | 개발자 경험 | > | — | — | 영역 14 |
| 21 | Guardrail 성숙도 | P | M3 / M3 | E3(E-4) | kernel 예외는 `check:architecture`가 강제한다. 예외 범위는 쓰임보다 넓다(02-06). 설계 문서 줄 번호는 어떤 검사도 보지 않는다(02-04) |
| 22 | 추상화 성숙도 | P | — / — | E1, E3 | 네이티브 API를 조립 시 bind·snapshot하는 facade와 공유 lease registry는 목적이 분명하다(4.2절). concrete transport 전체를 "kernel"로 부르는 것은 kernel의 뜻(공용 primitive)과 다르다(02-06) |
| 23 | 일관성 | P | — / — | E1 | 같은 `QUOTA_EXCEEDED`가 경로에 따라 recovery가 다르다. native 예외는 `READ_ONLY`(`result.ts:80-85`), `failureForCode`는 `ONLINE_ONLY`(`public-cache-codec.ts:592-598`)인데 후자는 쓰이지 않는 분기다. cache 관측과 file 관측의 bucket 어휘가 다르다(지난 라운드와 같음) |
| **24** | 네이밍 / 의미 | P | M2 / M2 | E1, E3 | `inspect().verified`는 이제 "모든 entry가 있고 맞다"를 뜻한다(M04 검출). 다만 읽지 못한 경우(UNKNOWN)도 `false`로 합쳐 "검증 실패"와 "판정 불가"가 같다(M05 생존, 02-02). `REHYDRATE`가 pointer 실패에서는 약속을 지킬 수 없다(02-01). preview가 자기 lease로 한도를 채운 경우에도 `retryable:true`라, 그때의 "재시도"는 다른 lease를 놓은 뒤에만 성공한다 |
| 25 | 조직 확장성 | - | — | — | 1인 관리. 팀 경계 검증 대상 없음 |
| 26 | Ownership | > | — | — | 영역 12. kernel 규칙 주석에 담당(frontend-platform)은 있고 재검토 조건은 없다(02-06에 적음) |
| 27 | 삭제 가능성 | O | M3 / M3 | E3(E-5) | 제거 드릴이 browser-files·cache-storage를 포함한 런타임 묶음을 지우고 게이트를 다시 통과한다(3회째 PASS, 2.3절). cross-context는 topic이 0개면 브라우저 기능을 조회하지 않는다(`browser-cross-context-host.ts:60-62`) |
| **28** | 회복 가능성 | X | 목표 M2 / 확인 M0(cache pointer) | E3(E-2) | cross-context는 GAP·재생성으로, browser-files는 dispose로 회복한다. cache-storage는 pointer가 한번 읽히지 않으면 어댑터 API로 회복할 수 없다(02-01). 범위는 opt-in cache-storage 한정이다 |
집계(적용 24개): O 5(3, 12, 13, 15, 27) · P 18 · X 1(28) · ? 0 · 적용 제외 2(16, 25) · 다른 영역 2(20, 26).
## 4. 설계 선택 설명 (41절)
### 4.1 Cache Storage control pointer를 현재 정책으로 엄격하게 읽는다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 활성 release를 가리키는 값이 손상돼도 검증 안 된 release를 서비스하지 않아야 한다. 동시에 다음 배포가 새 release를 활성화하고 오래된 캐시를 지울 수 있어야 한다 |
| 2. 지킬 성질 | (a) 검증한 후보만 활성화한다. (b) manifest와 다른 바이트를 돌려주지 않는다. (c) 읽을 수 있는 pointer가 가리키는 캐시는 cleanup이 지우지 않는다. (d) 나쁜 pointer 하나가 이후 배포를 영구히 막지 않는다 |
| 3. 현재 보장 | (a)·(b)·(c)는 보장한다: 활성화 전 전체 재검증(`public-response-cache-adapter.ts:672-691`), 조회마다 본문 SHA-256(`public-cache-response-validation.ts:87-96`), 보존 집합 계산(`:796-814`). (d)는 보장하지 않는다. `isActivePointer`가 정책에 묶인 조건을 읽기 시점에 검사하고(`public-cache-codec.ts:441`, `:455-464`), 네 연산이 모두 그 결과에서 멈춘다(E-1, E-2) |
| 4. 대안 | (가) 현상 유지 + "사이트 데이터 삭제" 안내. (나) `activateRelease`가 읽을 수 없는 이전 pointer를 "없음"으로 보고 새 pointer로 덮어쓴다(rollback 목록은 비움). (다) 읽을 때는 구조만 검사하고, 정책 조건(목록 길이, 허용 ID)은 쓸 때 적용한다. 쓰기 쪽은 이미 `slice(0, retained)`를 한다(`:703-716`). (라) control을 지우는 admin API를 추가한다 |
| 5. 비교 | (가) 코드 0줄. 운영자가 원인을 알 수 없고 캐시가 쌓인다. (나) 몇 줄. (a)~(c)를 잃지 않는다. 새 후보는 여전히 전체 재검증을 거친다. 잃는 것은 손상된 pointer의 rollback 목록뿐이고, 어차피 읽을 수 없던 값이다. (다) 두 줄 정도. 정책 변경은 해결하지만 JSON 손상은 해결하지 못한다. (라) 포트가 늘고 호출자가 언제 불러야 하는지 알아야 한다 |
| 6. 선택 | 확인한 조건(소비자 없음, SW drain 미구현)에서는 (나)+(다)가 가장 작다. 기존 규칙 (a)~(c)를 그대로 두고 (d)만 되찾는다. 현재 구현의 "fail-closed"는 무결성 쪽으로는 맞지만 진행성(d)을 대가로 치르고 있다 |
| 7. 재검토 조건 | Service Worker가 요청마다 이 조회를 쓰고, 구버전 탭이 drain될 때까지 rollback 캐시를 계속 서비스해야 하면(VD-15 drain 프로토콜) 덮어쓰기 뒤의 cleanup이 그 탭의 캐시를 지울 수 있다. 그때는 (라)나 drain을 아는 보존 규칙을 다시 비교한다 |
구분: 현재 동작은 코드와 E-1·E-2로 확인했다. 작성 의도 기록은 찾지 못했다. 설계 문서는 control JSON의 크기 상한과 schema 검증만 말하고 정책이 바뀐 뒤의 읽기는 다루지 않는다(`browser-file-and-origin-storage.md:968-973`). (나)·(다)의 비용은 리뷰어의 추정이고 구현하지 않았다.
### 4.2 object URL lease registry 하나를 preview와 download가 같이 쓴다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | blob URL은 revoke 전까지 Blob을 메모리에 붙잡는다. 탭 하나가 붙잡는 양에 상한이 필요하다 |
| 2. 지킬 성질 | 활성 URL 수·합계 바이트 ≤ 상한, lease마다 revoke 정확히 한 번, dispose는 전부 revoke |
| 3. 현재 보장 | registry 하나를 두 소비자에 넘긴다(`create-browser-file-runtime.ts:109-120`, `:151-168`). download lease는 handoff 뒤 30초 유지된다(`download-delivery-adapter.ts:149`, `:835-842`). 소진은 `retryable:true`, 단일 Blob 초과는 재시도 불가다(`object-url-lease.ts:53-71`). M02·M03 검출 |
| 4. 대안 | 소비자별 registry 분리, 한 registry 안의 소비자별 몫, grace 단축 |
| 5. 비교 | 분리하면 download 폭주가 preview를 막지 않지만, 같은 메모리 상한을 지키려면 상한을 나눠 설정해야 하고 합계 보호가 두 곳으로 갈라진다. 몫을 나누면 설정이 하나 는다. grace를 줄이면 느린 브라우저에서 handoff가 끊길 수 있다(Safari 미검증) |
| 6. 선택 | 보호할 성질이 "탭 전체 메모리"라서 한 예산이 가장 직접적인 표현이다. 02-04 수정으로 소진이 일시적이라는 신호도 호출자에게 간다. **현 상태 유지가 맞다** |
| 7. 재검토 조건 | 제품이 30초 안에 16개가 넘는 다운로드(일괄 내보내기)를 하거나, 관측에서 `PREVIEW`/`DOWNLOAD`의 `LIMIT_EXCEEDED`가 자주 보이면 몫 분리를 다시 비교한다 |
### 4.3 cross-context transport를 adapter kernel 예외로 공유한다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | query-cache coordinator가 탭 간 hint를 보내고 받아야 한다. transport 생성과 수명은 bootstrap이 세대마다 맡는다(`runtime-adapters.ts:359-403`) |
| 2. 지킬 성질 | concrete adapter끼리 구현에 기대지 않는다. transport 인스턴스는 조립 쪽만 만든다 |
| 3. 현재 보장 | query-cache는 `import type`으로 타입 2개만 쓴다(`tanstack-cache-coordinator.ts:16-19`). 규칙은 barrel 전체를 모든 adapter에 연다(`.dependency-cruiser.json:241-251`, `layers.md:47-49`). 다른 adapter가 런타임 팩토리를 import해도 통과한다(E-4 P1) |
| 4. 대안 | (가) 현상 유지(12-07 때 소유자가 kernel 예외로 정함). (나) 3개 멤버 채널 타입과 delivery 타입을 `src/contracts/cache-invalidation.ts`로 옮기고 예외를 지운다. (다) 같은 타입을 `src/application/ports/`에 둔다 |
| 5. 비교 | (가) 비용 0. 예외가 쓰임보다 넓게 남고, 두 번째 adapter가 transport를 직접 만들 수 있다. (나) E-4 P2에서 13줄 추가·import 1곳·정규식 1곳으로 게이트와 타입 검사를 통과했다. 계약 타입 하나가 늘지만 bootstrap에서 TypeScript가 구조 일치를 검사한다. (다) (나)와 같지만 wire 계약과 떨어진다 |
| 6. 선택 | 현재 조건(소비자 1곳, 타입만 사용)에서는 (나)가 더 작고 경계가 좁다. 다만 kernel 분류는 소유자 결정이므로 **제안**으로 남긴다(02-06) |
| 7. 재검토 조건 | 두 번째 adapter(SW, realtime 등)가 런타임 transport 동작을 직접 써야 하면 (가)나 transport의 `platform/` 이동을 다시 비교한다 |
## 5. 발견 사항 (36.3)
### 02-01 Cache Storage pointer를 현재 정책으로 검증해, 정책을 바꾼 배포나 손상 뒤에는 조회·활성화·정리가 영구히 멈춘다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 28, 11, 18, 6, 19, 5, 24, 1 |
| 근거 | `isActivePointer`가 rollback 목록 길이를 **현재** `retainedPreviousReleaseCount`와 비교하고(`src/adapters/cache-storage/public-cache-codec.ts:455-456`), ID와 캐시 이름도 현재 정책으로 검사한다(`:441`, `:459-464`). 실패는 `CORRUPT_DATA`/`REHYDRATE`다(`public-response-cache-adapter.ts:1016-1020`). 조회(`:247-254`), 활성화(`:693-702`), 정리(`:783-789`), inspect(`:855-859`)가 모두 이 결과에서 멈춘다. control cache를 지우는 API는 없다(`cache-storage-ports.ts:59-85`). E-2: 실제 Chromium·Firefox·WebKit Cache API에서 retained 3으로 release 3개를 활성화한 뒤 retained 1 adapter로 바꾸면 조회 `CORRUPT_DATA`, 새 release 2개의 stage는 성공·activate는 `CORRUPT_DATA`, cleanup `CORRUPT_DATA`, owned cache 6개. E-1: pointer JSON이 잘려도 같은 결과 |
| 발생 조건 | (1) `retainedPreviousReleaseCount`를 줄이는 배포. 허용 범위 1~5의 정상 설정 변경이다(`public-cache-policy.ts:124-126`). (2) `isReleaseRegistryIdAllowed`를 좁히는 배포. (3) 디스크·브라우저 오류로 pointer가 손상 |
| 영향 | 그 origin의 오프라인 자산 캐시가 계속 꺼진다. 조회 실패는 네트워크로 떨어지므로 온라인 화면은 동작한다. cleanup이 막혀 배포마다 release cache(최대 128 MiB)가 쌓이고 origin 저장 한도를 IndexedDB·OPFS와 나눠 쓴다. 안내된 복구 `REHYDRATE`(`browser-file-and-origin-storage.md:1026` "quarantine/re-fetch")를 따라도 벗어날 수 없다. 사용자가 사이트 데이터를 지워야 한다 |
| 심각도·우선순위 | Medium · P2 — 사용자 데이터 손실은 없고 opt-in 런타임이다. 하지만 정상 설정 변경 하나로 들어가고, 되돌릴 수 없고, 저장 공간을 계속 쓴다. 제품 repo 2곳이 이 코드를 그대로 들고 있다 |
| 통제·증거 | 무결성 M2 / 진행성 M0 확인 · E3(E-2, 3엔진), E2(E-1). pointer 호환 규칙을 지키는 테스트는 없다(M13·M14 생존) |
| 확실성과 남은 가정 | 경로와 결과는 확정. 실제 제품에서 정책을 바꿀 빈도는 모른다. 저장 한도 도달 시 다른 저장소에 주는 영향은 측정하지 않았다 |
| 결정의 근거 | 4.1절. 무결성 fail-closed는 유지하고 진행성만 되찾는 선택이다 |
| 이해 비용 | 운영자는 관측에서 `CACHE_LOOKUP` `CORRUPT_DATA`만 본다. pointer 손상인지 marker 손상인지 구분하려면 Cache Storage를 직접 열어야 한다 |
| 최소 개선 방향 | (1) `activateRelease`에서 이전 pointer가 `CORRUPT_DATA`면 없음으로 보고 새 pointer로 덮어쓴다. 새 후보 재검증은 그대로 둔다. (2) `isActivePointer`에서 정책 의존 조건(목록 길이)을 빼고 쓰기 쪽 `slice`에 맡긴다 |
| 대안 비교 | 4.1절 (가)~(라) |
| 단순화의 보존 조건 | 검증하지 않은 후보를 활성화하지 않는다. 읽을 수 있는 pointer가 가리키는 캐시는 cleanup이 지우지 않는다. 조회는 manifest digest가 맞는 바이트만 돌려준다 |
| 비용·부작용 | 코드 몇 줄과 테스트 2~3개. 덮어쓴 뒤 cleanup이 구버전 탭이 쓰던 캐시를 지울 수 있다. 그 탭의 조회는 `STORAGE_EVICTED`로 네트워크로 떨어진다(안전한 방향) |
| 재검토 조건 | 4.1절 7 |
| 완료 기준 | E-1의 두 시나리오에서 다음 배포의 activate가 성공하고, 그 뒤 cleanup이 성공한다. 손상 pointer 상태에서도 검증 안 된 후보는 활성화되지 않는다 |
| 검증 방법 | E-1을 `tests/unit/public-response-cache-repair.test.ts`에 옮긴다. M13·M14 변이가 실패하는지 확인한다. 가능하면 E-2를 `public-cache-storage.spec.ts`에 추가한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 02-02 `inspect()`의 비용·취소·판정 불가가 포트 계약에 드러나지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 5, 14, 24, 10 |
| 근거 | 지난 02-05 수정으로 `inspect()`가 owned 후보마다 모든 entry를 읽고 SHA-256을 계산한다(`public-response-cache-adapter.ts:864-891`, `verifyReleaseCandidate` `:1068-1118`). 포트는 signal을 받지 않는다(`cache-storage-ports.ts:84`, 호출부 `:883`에서 `undefined`). 문서는 비용을 "cache count"에 비례한다고만 적는다(`browser-file-and-origin-storage.md:974-977`). 읽기 오류(`UNKNOWN`)도 `verified: false`가 되어(`:888`) 없거나 틀린 후보(`REPAIRABLE`)와 같아진다. `unreadableOwnedCacheCount`는 marker 실패만 센다(`:872-874`). `UNKNOWN`을 `true`로 바꾼 변이가 테스트를 통과한다(M05) |
| 발생 조건 | 운영 도구나 조립 코드가 부팅·주기 작업에서 `inspect()`를 부른다. 또는 일시적인 Cache API 오류 중에 부른다 |
| 영향 | 후보 수 × 최대 128 MiB를 읽고 해시하는 동안 멈출 수 없다. 일시 오류가 난 멀쩡한 후보가 rollback 대상에서 빠진다(보수적 방향) |
| 심각도·우선순위 | Low · P3 — 소비자가 없고, 문서가 부팅 경로 연결을 금지한다. 잘못 판단해도 활성화는 다시 검증한다 |
| 통제·증거 | M1 · E1, E3(M05 생존) |
| 확실성과 남은 가정 | 코드로 확정. 실제 소요 시간은 측정하지 않았다 |
| 결정의 근거 | 적용 제외 — 이름이 약속하는 보장은 이미 맞췄고, 남은 것은 계약 설명과 취소 입력이라 대안 비교가 필요하지 않다 |
| 이해 비용 | 호출자는 구현을 읽어야 비용과 `false`의 뜻을 안다 |
| 최소 개선 방향 | `inspect({ signal })`를 받는다. `verified: boolean`을 `VERIFIED`·`INVALID`·`UNREADABLE` 세 값으로 바꾸거나, 판정 불가를 `unreadableOwnedCacheCount`에 넣는다. 포트 주석과 문서 974행에 "entry 바이트에 비례"를 적는다 |
| 비용·부작용 | 포트 타입 변경([계약]). 소비자는 repo 안에 없다 |
| 완료 기준 | 읽기 오류 후보가 "검증 실패"와 구분되어 보고되고, abort로 중간에 멈출 수 있다 |
| 검증 방법 | entry 읽기에서 던지는 가짜 cache로 `inspect()` 결과를 확인하는 테스트. M05 변이가 실패하는지 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 02-03 CHANGELOG 0.2.0의 browser-files [계약] 행이 실제 변경 경로·대상과 다르다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(문서 불일치) |
| 관련 관점 | 17, 9 (+30.4 업데이트 전파) |
| 근거 | `CHANGELOG.md:51`의 영향 경로는 `src/adapters/browser-file-storage/`, `src/adapters/cache-storage/`다. 이 행의 커밋이 실제로 바꾼 곳은 `src/adapters/browser-files/{object-url-lease,download-delivery-adapter,file-observer}.ts`, `src/application/ports/browser-file-storage/shared.ts`, cache-storage 3파일이다(`git show --name-only c9be8d6 d76653b 0b41cb3 55c0bf5 2cbf500`). `src/adapters/browser-file-storage/`는 이 행의 어느 커밋도 건드리지 않았다. 공개 포트 `BrowserDataObservation.outcome`에 `DISMISSED`가 추가됐는데(`shared.ts:99-100`) 경로에 없다. "닫은 선택 창은 `DISMISSED`"는 Result 변경처럼 읽히지만 Result는 원래 `DISMISSED`였고 바뀐 것은 관측 값이다. cache-storage는 service-worker-pwa recipe 소속인데(`frontend-capability-recipes.json:121-128`) 행은 "browser-files recipe를 쓰는 프로젝트만 해당"이라 적는다. README는 CHANGELOG가 "영향 경로를 적는다"고 약속한다(`README.md:317-320`) |
| 발생 조건 | 복사한 프로젝트가 README 절차대로 경로를 보고 가져올 수정을 고른다 |
| 영향 | browser-files 수정 3건과 포트 타입 변경을 놓칠 수 있다. 관측 소비자가 `outcome`을 전수 분기하면 새 값에서 실패한다. 이번 두 제품 repo는 전체 병합이라 영향을 받지 않았다(두 동기화 기록 확인) |
| 심각도·우선순위 | Low · P3 — 문서 한 행. 이번 소비자는 영향 없음 |
| 통제·증거 | M1 · E1 |
| 확실성과 남은 가정 | 경로 대조로 확정 |
| 결정의 근거 | 적용 제외 — 기록 오류를 바로잡는 문제라 선택 비교가 필요하지 않다 |
| 이해 비용 | 소비자가 커밋을 하나씩 열어 봐야 실제 경로를 안다 |
| 최소 개선 방향 | 경로를 `src/adapters/browser-files/`, `src/adapters/cache-storage/`, `src/application/ports/browser-file-storage/shared.ts`로 고친다. "관측의 `outcome`에 `DISMISSED` 추가"로 쓰고, cache 부분은 service-worker-pwa recipe에 해당한다고 적는다 |
| 비용·부작용 | 문서 한 행 |
| 완료 기준 | 행의 경로가 행의 커밋이 바꾼 `src/` 경로를 모두 포함하고, 그 밖의 경로를 포함하지 않는다 |
| 검증 방법 | `git show --name-only <행의 커밋>`과 대조. 반복된다면 CHANGELOG 행의 경로와 커밋 변경 경로를 대조하는 검사를 검토한다(영역 14) |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 02-04 이 영역 설계 문서의 줄 번호 참조가 다시 밀렸다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(문서 불일치) |
| 관련 관점 | 9, 21 |
| 근거 | FOLLOW-UP 02-09의 `client-cache-and-storage.md:94` → `server-state-scope-runtime.ts:148`은 아직 빈 줄을 가리킨다(실제 `activateNextGeneration` 호출은 `:154`). 02-03 수정(`c8e4794`)이 넣은 참조도 이후 커밋으로 1줄씩 밀렸다. `browser-file-and-origin-storage.md:368` `download-delivery-adapter.ts:385-391` → 실제 `:386-393`, `:370` `server-state-scope-runtime.ts:19` → 실제 `:20`, `:371` `runtime-adapters.ts:410-416` → 실제 `:411-417`. `client-cache-and-storage.md:79-81`은 브라우저 증거가 "Chromium/Firefox만"이라 적지만 WebKit도 통과한다(0.2절 21/21, `CHANGELOG.md:77`). 두 문서는 `verify:documentation` 대상이 아니다(`scripts/verify-documentation-readiness.ts:19-20`) |
| 발생 조건 | 참조된 파일 위쪽에 줄이 추가될 때마다 |
| 영향 | 문서를 따라간 사람이 엉뚱한 줄을 본다. 한 줄 차이라 오해는 작다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M1 · E1 |
| 확실성과 남은 가정 | 대조로 확정 |
| 결정의 근거 | 적용 제외 — 문서 사실 오류 |
| 이해 비용 | 참조마다 주변을 다시 찾아야 한다 |
| 최소 개선 방향 | 줄 번호 대신 심볼 이름(`createBrowserFileRuntime`의 `dispose`, `ScopeResetParticipant`)으로 가리킨다. 줄 번호를 남긴다면 문서를 수정한 커밋을 함께 적는다. WebKit 문장을 고친다 |
| 비용·부작용 | 문서 몇 줄 |
| 완료 기준 | 두 문서의 `path:line` 참조가 현재 코드와 맞거나 심볼 참조로 바뀐다 |
| 검증 방법 | 참조 목록을 현재 코드와 대조 |
| 담당·기한·상태 | 미정 · 미정 · FOLLOW-UP 02-09 이어받음 |
### 02-05 bounded download에서 lease를 만든 뒤 handoff가 실패하면 lease를 돌려주는 규칙을 테스트가 고정하지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험(테스트 공백) |
| 관련 관점 | 10, 6, 14 |
| 근거 | `boundedObjectUrlHandoff`는 lease를 만든 뒤(`download-delivery-adapter.ts:827`) handoff가 던지거나 abort가 확인되면 catch에서 `lease?.release()`로 돌려준다(`:853-854`). 이 한 줄을 지운 변이가 download·runtime 테스트 28개를 모두 통과했다(M10). `createAnchorDownloadHost`는 `document.body.append`를 부르고(`:65`), 다운스트림은 host를 직접 넘길 수 있다(`:112`) |
| 발생 조건 | 리팩터링으로 그 줄이 빠진 뒤, host가 던진다(`body`가 없는 문서, 사용자 host의 오류) |
| 영향 | 실패마다 lease가 하나씩 남아 16번째부터 preview·download가 `LIMIT_EXCEEDED`가 된다. 지난 02-01과 같은 종류의 누수다 |
| 심각도·우선순위 | Low · P3 — 현재 코드는 맞다 |
| 통제·증거 | M2 · E3(변이 생존) |
| 확실성과 남은 가정 | 도달 경로는 host 예외뿐이다. lease 생성과 abort 검사 사이에는 await가 없다 |
| 결정의 근거 | 적용 제외 — 테스트 한 개를 더하는 문제 |
| 이해 비용 | 없음 |
| 최소 개선 방향 | `handoff`가 던지는 host로 `BOUNDED_OBJECT_URL` 전달을 부르고 `activeLeaseCount`가 0으로 돌아오는지 단언한다 |
| 비용·부작용 | 테스트 1개 |
| 완료 기준 | M10 변이가 실패한다 |
| 검증 방법 | 같은 변이 재실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 02-06 cross-context-invalidation kernel 예외가 실제 쓰임(타입 2개)보다 넓다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 2, 21, 22, 5, 26 |
| 근거 | adapter 간 예외는 `cross-context-invalidation/index.ts` 전체를 모든 adapter에 연다(`.dependency-cruiser.json:249-250`). 이 barrel은 런타임 팩토리 두 개도 내보낸다(`src/adapters/cross-context-invalidation/index.ts:1-24`). 지금 이 예외를 쓰는 곳은 query-cache의 `import type` 한 곳뿐이다(`tanstack-cache-coordinator.ts:16-19`, 쓰는 멤버는 `subscribe`·`publish`·`close` `:48`, `:195`, `:280`). E-4 P1: realtime에서 런타임 팩토리를 import해도 게이트가 통과한다. E-4 P2: 타입을 contracts로 옮기고 예외를 지워도 게이트·타입 검사·테스트가 통과한다. 규칙 주석에는 담당은 있고 재검토 조건이 없다(`.dependency-cruiser.json:242`). `layers.md:54-56`은 모든 예외 주석에 재검토 조건을 둔다고 적는다 |
| 발생 조건 | 두 번째 adapter가 transport를 직접 만들 때 |
| 영향 | 조립(bootstrap)이 아닌 곳에서 같은 채널 이름의 transport 인스턴스가 생길 수 있다. 세대 교체 때 닫히지 않는 인스턴스가 생긴다. 지금은 그런 코드가 없다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M3(규칙 강제) · E3(E-4) |
| 확실성과 남은 가정 | 12-07 때 소유자가 이것을 kernel 예외로 정했다(`docs/reviews/2026-09-25-maturity-review/12-guardrails-ci.md:177`). 그 결정의 근거 기록은 찾지 못했다 |
| 결정의 근거 | 4.3절. 확인한 사실: 타입만 쓴다. 기록된 의도: "Any adapter may import it"(`layers.md:47-49`). 리뷰어 추론: 런타임 공유를 의도했다는 요구는 현재 코드에 없다 |
| 이해 비용 | "kernel"이라는 말이 공용 primitive(`platform/`)와 concrete transport를 함께 가리켜, 새 공용 코드를 어디 둘지 판단이 흐려진다 |
| 최소 개선 방향 | E-4 P2와 같이 채널 타입을 `src/contracts/cache-invalidation.ts`로 옮기고 예외를 지운다. `layers.md:47-49`와 규칙 주석을 고친다. 유지하기로 하면 규칙 주석에 재검토 조건을 적는다 |
| 대안 비교 | 4.3절 (가)~(다) |
| 단순화의 보존 조건 | query-cache가 `subscribe`·`publish`·`close`와 delivery의 `ordering`·`transport`를 그대로 쓴다. bootstrap 조립 코드가 바뀌지 않는다. 세대마다 새 transport가 만들어지고 이전 것이 닫힌다 |
| 비용·부작용 | 3파일 + 문서 2곳. 계약 타입 하나가 는다 |
| 재검토 조건 | 4.3절 7 |
| 완료 기준 | `pathNot`에 `cross-context-invalidation/index.ts`가 없고, E-4 P1 같은 import가 `check:architecture`에서 실패한다. 또는 유지 결정과 재검토 조건이 규칙 주석에 있다 |
| 검증 방법 | `check:architecture`, `check:types`, `tests/unit/{tanstack-cache-coordinator,query-cache,cross-tab-invalidation}.test.ts`, P1 probe |
| 담당·기한·상태 | 결정 필요 · 승인자: 템플릿 소유자(frontend-platform) · 신규 |
## 6. FOLLOW-UP 재확인과 지난 발견 회귀 확인
### 6.1 FOLLOW-UP(2026-09-25 라운드)의 이 영역 항목
| FOLLOW-UP 항목 | 현재 상태 | 근거 |
|---|---|---|
| P3 02-09 — 문서 줄 번호 참조(`server-state-scope-runtime.ts:148`)가 `:154`로 밀림, `verify:documentation` 대상 아님 | **유효** | `client-cache-and-storage.md:94`가 아직 `:148`이다. 같은 종류의 drift가 3곳 더 생겼다 → 02-04 |
FOLLOW-UP의 다른 항목(예산, flaky 테스트, 06-08 `assets/` 등)은 이 영역 코드가 아니다.
### 6.2 지난 02 발견의 회귀 확인(E-3)
닫힌 발견은 회귀가 있을 때만 다시 적는다. 수정한 규칙에 변이를 넣어 현재 테스트가 잡는지 봤다.
| 변이 | 지난 ID | 결과 |
|---|---|---|
| M01 preview가 resolve 뒤 abort를 다시 보지 않음 | 02-01 | 검출 |
| M02 preview 소진을 재시도 불가로 | 02-04 | 검출 |
| M03 download 소진을 일반 한도 초과로 | 02-04 | 검출 |
| M04 `inspect().verified` 항상 `true` | 02-05 | 검출 |
| M05 `inspect()`의 판정 불가를 `true`로 | 02-05 | **생존** → 02-02 |
| M06 저장 창 닫기를 성공 관측으로 | 02-06 | 검출 |
| M07 조회당 `keys()` 2회 | 02-07 | 검출 |
| M08 stage 요청 `credentials: "include"` | 02-02 | 검출 |
| M09 preview 단독 dispose에서 lease 미반환 | — | 생존(runtime 조립에서는 download dispose가 같은 registry를 비워 동등) |
| M10 bounded download catch의 `lease?.release()` 삭제 | — | **생존** → 02-05 |
| M11 cross-tab STALE 검사 삭제 | 02-08(5) 인접 | 검출 |
| M12 `storageArea` 검사 삭제 | — | 검출 |
| M13 pointer 목록 길이 검사 삭제 | — | 생존(규칙을 고정하는 테스트 없음 → 02-01 완료 기준) |
| M14 activate가 이전 pointer 실패를 무시 | — | 생존(같은 이유 → 02-01) |
| M15 browser-managed handoff의 다른 origin 거부 삭제 | 02-08(1) | 검출 |
| M16 vault 누적 보관 바이트 상한 삭제 | 02-08(2) | 검출 |
| M17 preview Blob을 검증된 타입으로 다시 만들지 않음 | 02-08(3) | 검출 |
| M18 native picker의 user activation 검사 삭제 | 02-08(4) | 검출 |
| M19 처음 보는 source의 seq>1을 GAP으로 보지 않음 | 02-08(5) | 검출 |
02-03(dispose 안내)과 02-09(문서)는 문서 수정이다. 02-03 안내 문장은 코드와 맞지만 새로 넣은 줄 번호가 밀렸다(02-04).
## 7. 미검증 목록
| 항목 | 왜 확인하지 못했나 | 확인하려면 |
|---|---|---|
| 다른 탭에서 계정이 바뀐 뒤 이 탭이 받은 무효화 hint가 이전 사용자 세대 캐시에 새 세션 응답을 채우는지 | 탭 간 세션 변경 감지는 auth 영역이고, 조립된 2탭 E2E가 없다(`client-cache-and-storage.md:79-80`도 없음을 인정) | 탭 A 로그아웃·B 로그인 → 탭 B mutation → 탭 A 상태를 보는 2탭 E2E |
| Safari에서 blob URL 30초 grace가 충분한지, runtime dispose 직후 handoff가 살아남는지 | 실제 다운로드 완료는 Playwright가 보지 않는다(이번 실행은 handoff까지) | WebKit 실기에서 큰 Blob 다운로드 후 revoke 시점 비교 |
| Chrome `showSaveFilePicker`가 확정 시 빈 파일을 먼저 만드는지 | 사용자 조작이 필요하다 | Chromium 실기 실험 |
| 02-01 상태에서 쌓인 캐시가 origin 한도에 닿을 때 IndexedDB·OPFS 쓰기에 주는 영향 | 한도까지 채우는 실험을 하지 않았다 | 작은 quota 프로필에서 release를 반복 stage하며 다른 저장소의 `QUOTA_EXCEEDED` 관찰 |
| `inspect()`의 실제 소요 시간(02-02) | 소비자가 없고 측정 목표가 없다 | 후보·entry 크기별 측정 |
| 이 영역의 관측이 실제 제품 telemetry로 이어지는지 | file·cache observer를 조립한 코드가 repo·제품 repo 어디에도 없다 | recipe를 조립한 제품에서 확인 |
@@ -0,0 +1,364 @@
# 03 — HTTP·서버 상태·인증·진단 성숙도 리뷰
> 검토일: 2026-09-29 · 기준: `main` / `af3d8e6` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`(워킹트리 판)
> 경로: `src/adapters/http/`, `src/adapters/browser-rpc/`, `src/adapters/query-cache/`, `src/adapters/auth/`, `src/adapters/diagnostics/`, `src/adapters/telemetry/`, 관련 포트와 테스트
> 깊게 본 관점: 5, 6, 8, 12, 15, 17, 22 · 추가로 읽은 절: 29.2, 29.3
> 영역 판정(35.8): **조건부 사용 가능.** 조회·인증 세대·자격증명 경계·전송 상한은 그대로 복제해도 된다. 결과 불명 쓰기 샘플은 03-01을 고치기 전까지 "처리 중" 409를 돌려주는 백엔드(짝 백엔드 템플릿의 기본값)와 함께 복제하지 않는다. API가 다른 origin이면 배포 전에 preflight를 확인한다(03-02).
## 0. 머리말 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 | `clean-architecture-frontend-template`, `main` / `af3d8e6`. 미커밋은 리뷰 가이드 문서 2개뿐이고 코드는 커밋과 같다 |
| 목적과 실행 구성 | 프론트엔드 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음. 인증 `demo`/`external`. 기본 설정의 API는 다른 origin이다(`config/runtime/production.json:3`) |
| 읽은 코드 | 영역 6개 폴더. 흐름 추적을 위해 `src/bootstrap/runtime-adapters.ts`, `src/presentation/adapters/query/application-query.ts`(mutation), `server-state-generation-provider.tsx`, `src/presentation/forms/use-app-form.ts`, `src/presentation/components/async-surface.tsx`, `src/contracts/{errors,external-contract-runtime,mutation-intent,query-keys}.ts`, `src/platform/telemetry/trace-context.ts`, reference feature(`contracts/`, `presentation/`) |
| 읽은 문서 | `CHANGELOG.md` 0.2.0 [계약] 행, `docs/architecture/backend-api-and-server-state-contract.md` §5·§6·16.1, `docs/operations/api-contract-and-server-state-recovery.md` 1·5.2·6.3절, `docs/architecture/starter-experience.md` 인증 절, `docs/architecture/decisions/VD-07-*.md`, `VD-04-*.md`, `docs/runbooks/FE-RB-003.md`, 지난 라운드 03 문서·README 11절·FOLLOW-UP |
| 다운스트림 증거(읽기만) | `../tech-log-frontend`·`../memento-frontend` 브랜치 `chore/template-sync-v0.2.0`의 동기화 기록, `config/runtime/*.json`, tech-log `bff-session-owner.ts`·계약 분류기. 짝 백엔드 `../clean-architecture-backend-template`·`../tech-log-backend`의 멱등·CORS 코드 |
| 실행한 테스트 | `node scripts/run-vitest.ts run` 영역 대상 34개 경로(unit 17, integration 11, component 5, `tests/features/reference-feature`) → **50 파일 / 569 테스트 통과** |
| flaky 재현 | `http-execution-v3-live-authority.test.ts` 단독 20회 순차(부하 8~11) → 20/20 통과. 12개 동시 × 4회(부하 19~30) → 48회 중 1회 실패. 원인은 03-05 |
| 격리 실험(worktree, 끝나고 삭제) | 변이 7개(아래 표). 결정적 재현 테스트 3개: 마감 창(03-05), 키 없는 재전송(03-03), 504 → 409 처리 중 → 재저장(03-01). 실험 파일은 scratchpad `review-2026-09-29/03/experiments/`에 남겼다 |
| 브라우저 실험 | Playwright 1.62, chromium·firefox·webkit. 다른 origin API가 `Access-Control-Allow-Headers`에서 `x-correlation-id`를 빼면 어떻게 되는지 확인(03-02) |
| 확인하지 못한 범위 | 두 제품의 실제 운영 CORS 값, 실제 백엔드와의 통합, 여러 탭, 앱 전체를 브라우저에 띄운 CORS 거절 화면, Browser RPC 실제 provider, 성능 측정. 7절에 이유를 적었다 |
| 이전 리뷰와 비교 | 지난 03-01~03-08은 닫혔다. 회귀는 찾지 못했다. 지난 결과는 증거로 쓰지 않았고 아래 판정은 이번 실행·읽기 결과다 |
변이 실험(관점 10):
| 변이 | 결과 |
|---|---|
| M1 결과 불명 뒤 같은 입력에도 새 intent 생성(`application-query.ts:537-543`) | 검출 — 4건(`application-mutation-admission`, `reference-page`, `reference-production-vertical`) |
| M2 `x-correlation-id` 요청 헤더 제거(`http-execution-v3.ts:819`) | 검출 — 1건(`http-execution-v3.test.ts` request correlation) |
| M3 바인딩이 서버 반사 id를 `requestId`로 넘기지 않음(`feature-http-binding.ts:309-312`) | 검출 — 5건 |
| M4 `SUBJECT_MISSING` 진단 제거(`server-state-scope-runtime.ts:114`) | 검출 — 3건 |
| M5 subject 없는 인증 상태를 "같은 identity"로 취급(닫힘 → 열림) | 검출 — 4건 |
| M6 UNKNOWN 동안 identity lease를 잡지 않음(`application-query.ts:605-608`) | **생존** — 569건 전부 통과(03-06) |
| M7 재전송 때 이전 UNKNOWN admission을 정리하지 않음(`application-query.ts:523-528`) | 검출 — 4건 |
## 1. 결론
- **조회·세대·자격증명 경계는 여전히 튼튼하다.** 변이 M2~M5·M7이 모두 검출됐고, 영역 테스트 569건이 통과한다.
- **같은 키 재전송(지난 03-01의 수정)이 "처리 중" 응답 하나로 풀린다(03-01, High).** 짝 백엔드 템플릿은 처리 중인 같은 키 요청에 `409 IDEMPOTENT_IN_FLIGHT`를 준다. reference 분류기는 모든 409를 `NOT_APPLIED`로 판정한다. 그러면 화면이 "충돌"로 바뀌고, 다음 저장은 새 키로 나간다. 격리 재현에서 키가 `[K, K, K′]`였다.
- **`x-correlation-id`는 교차 origin 배포의 숨은 전제다(03-02).** 백엔드가 헤더를 허용하지 않으면 V3 요청 전부가 "네트워크 오류"로 끝난다. 쓰기는 모두 "결과 불명"이 된다. 통제는 문서 3곳뿐이고, 두 다운스트림 동기화 기록은 이 항목을 백엔드 작업으로 올리지 않았다.
- **재전송이 키 없는 명령에도 열려 있다(03-03).** 결과 불명 쓰기에는 문의 식별자가 보이지 않는다(03-04).
- **`readSubject` 필수화는 안전하고 소음도 작다.** subject가 없으면 닫힘 방향으로 동작한다(M5 검출). 경고는 fence마다 1건이고 기본 sink가 없어 브라우저 메모리에만 남는다. 이행 절차는 CHANGELOG와 `starter-experience.md`에 있다. README 업데이트 절에는 따로 없다.
- **FOLLOW-UP 3절 live-authority 간헐 실패의 원인을 찾았다(03-05).** 마감이 최종 불변식 검사 직전에 끝나면 시간 초과가 "입력 거절"로 바뀐다. 테스트가 실제 시간 5ms 마감을 써서 부하에서 이 창에 걸린다.
## 2. 대표 흐름 (체크리스트 2절)
### 2.1 정상 흐름 — reference 목록 조회
```text
route search
-> useReferenceFeature / bindQuery(scope) use-reference-feature.ts:116-
-> FeatureHttpBinding -> contractOperations.execute runtime-adapters.ts:534-575
-> V3 execute http-execution-v3.ts:472-1090
정책: 인증 프로필 확인 651-657, scope 확인 660-662, 입력 검증 672-692,
자격증명 716-798, 헤더(+x-correlation-id) 802-826, 재시도 상한 828-832
외부 I/O: fetch 905-965, 상한 있는 본문 읽기 998-1026
실패: SAFE는 전송 실패·재시도 상태에서 최대 min(계약, 설정, 2)회 975-991, 1031-1056
-> observation 1건 590-620 -> diagnostics 1건, 실패면 api.request.failed 1건
runtime-adapters.ts:233-306
-> 세대별 QueryClient 캐시 server-state-generation-provider.tsx:43-45
```
- 상태 변화: 캐시만 바뀐다. TanStack 재시도는 꺼져 있어 재시도는 V3 한 곳이다.
- 결과: 로그아웃·계정 전환 중 도착한 응답은 세대 확인으로 버려진다(`http-execution-v3.ts:849-855`, `server-state-scope-runtime.ts:99-185`).
### 2.2 피해가 큰 흐름 — 결과 불명 쓰기와 같은 키 재전송
```text
폼 저장 use-app-form.ts:299-316
-> mutation.submit application-query.ts:409-674
입력 intern -> identity 428-430
같은 identity의 UNKNOWN admission 찾기 504-508
intent 생성(키 = randomUUID) 또는 재사용 537-543
-> V3 POST, Idempotency-Key http-execution-v3.ts:809-811
-> 504 / 마감 초과 -> MAYBE_APPLIED http-effect-certainty.ts:36-49
-> admission UNKNOWN + identity lease application-query.ts:601-613
-> 화면 "변경 결과를 확인할 수 없습니다"
[변경됨으로 확인] [같은 요청으로 다시 보내기] [목록을 새로 불러와 확인]
reference-resource-form-page.tsx:141-172
-> 재전송 -> 같은 intent -> 같은 키 application-query.ts:736-747
-> 백엔드 멱등 처리(재생) backend-api-and-server-state-contract.md §6
```
실패 가지:
- 재전송에 서버가 "처리 중" 409로 답한다 → `NOT_APPLIED` → 키 결합이 풀린다 → 다음 저장은 새 키(03-01).
- 키 없는 명령 → 키 없이 다시 실행(03-03).
- 세대 fence(로그아웃·계정 전환·subject 없는 owner의 재알림) → UNKNOWN admission 폐기(`application-query.ts:818-831`) → 새 키. 런북 6.3-7에 한계로 적혀 있다.
- CORS preflight 거절 → 모든 쓰기가 `MAYBE_APPLIED`(03-02).
- 어느 가지에서도 화면에 문의 식별자가 없다(03-04).
### 2.3 변경 흐름 — 다운스트림이 v0.2.0을 받는다
```text
외부 owner(__CA_FRONTEND_AUTH_OWNER__)
-> 메서드 8개 검사 runtime-adapters.ts:135-160
readSubject 없음 -> createUnavailableSessionAdapter -> integration-failed
external-session-adapter.ts:157-170
readSubject() === null (인증 상태)
-> identity null -> 알림마다 fence + SUBJECT_MISSING warn
server-state-scope-runtime.ts:99-115, 218-249
-> 메모리 diagnostics(기본 sink 없음) runtime-adapters.ts:322
백엔드 쪽 [계약]: x-correlation-id CORS 허용(03-02), 같은 키 재생(U-5, 03-01)
```
- tech-log: owner가 상태가 바뀔 때만 알린다(`bff-session-owner.ts:48-52`, `readSubject: () => null` 127행). 로그인·로그아웃은 원래도 fence가 일어나므로 추가 비용은 없다. 경고는 로그인마다 1건이다.
- memento: 외부 owner가 없다. `AUTH_MODE=external` 운영 설정은 이전부터 `integration-failed`이고 이번 변경으로 달라지지 않았다.
## 3. 28개 관점 판정표 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 굵은 번호는 깊게 본 관점이다.
| 번호 | 관점 | 판정 | 이유·근거 |
|---|---|---|---|
| 1 | 코드 성숙도 | P | effect 확실성 lattice(`http-effect-certainty.ts:36-73`)와 intent 검증(`http-execution-v3.ts:378-436`)은 일관된다. 마감이 최종 불변식 검사 직전에 끝나면 시간 초과가 요청 계약 위반이 된다(03-05) |
| 2 | 구조적 성숙도 | > | 경계 검사는 12 영역. 오케스트레이터 `check:architecture` PASS |
| 3 | 변경 용이성 | P | 명령 추가는 계약 + 바인딩으로 끝난다. 새 명령이 키 없는 명령이어도 재전송 연결이 그대로 동작한다(03-03) |
| 4 | 인지 부하 | P | V3 `execute()`가 한 함수 약 620줄(`http-execution-v3.ts:472-1090`)이지만 39.7 기준으로 한 곳에 둘 이유가 있다. 결과 불명 쓰기 규칙은 분류기·mutation 코디네이터·폼·폼 페이지·AsyncSurface 다섯 곳에 나뉘어, 409 한 줄이 키 보호를 푼다는 사실을 한 곳에서 알 수 없다(03-01) |
| **5** | 위험 가시성 | P | 결과 union이 실패 종류와 effect를 타입으로 드러낸다(`http-execution-v3.ts:126-182`). 재전송이 안전한 조건(키가 있음)은 훅 계약에 없다(`application-query.ts:229-234`, 03-03). 교차 origin CORS 전제는 설정·코드에서 보이지 않는다(03-02) |
| **6** | 실패 성숙도 | P | 마감 하나, 재시도 권한 하나, `MAYBE_APPLIED` 자동 재전송 금지가 유지된다(M1·M7 검출). 504 뒤 같은 키 재전송은 E2(`reference-production-vertical.test.tsx:123-167`). "처리 중" 409 뒤 키 보호가 풀린다(03-01, 재현). 키 없는 명령도 재전송된다(03-03) |
| 7 | 운영 성숙도 | P | 텔레메트리 라벨은 닫혀 있고 build/release가 찍히며(`telemetry-collector.ts:91-94`) 본문은 60KiB 아래로 나뉜다(58-84). diagnostics는 기본 sink가 없어(`runtime-adapters.ts:322`) `SUBJECT_MISSING`·`correlation_id`가 운영자에게 가지 않는다. FE-RB-003이 CORS를 원인 후보로 두지 않는다(03-02) |
| **8** | 디버깅 가능성 | P | 요청마다 `x-correlation-id`를 보내고(`http-execution-v3.ts:817-826`, M2 검출) 서버 반사값을 `requestId`로 싣는다(`feature-http-binding.ts:297-318`, M3 검출). 결과 불명 쓰기에는 문의 식별자가 없다(03-04). CORS 거절은 JS에서 일반 네트워크 오류와 구분되지 않는다(E3, 03-02). 마감 창 오분류(03-05) |
| 9 | 유지보수 성숙도 | P | 런북 상태표가 코드 위치를 가리킨다(`api-contract-and-server-state-recovery.md:20-35`). 백엔드 계약 §5의 허용 헤더 목록이 코드의 `TRANSPORT_OWNED_HEADERS`(`http-contract-bridge.ts:114-122`)와 따로 관리되고 `traceparent`가 빠져 있다(03-02) |
| 10 | 테스트 성숙도 | P | 대상 569건 통과. 변이 7개 중 6개 검출, 1개 생존(03-06). live-authority 파일은 부하에서 1/48 실패(03-05). "처리 중" 응답, 키 없는 재전송, 엄격한 CORS를 다루는 테스트가 없다 |
| 11 | 데이터 성숙도 | - | 이 영역은 영속 데이터를 쓰지 않는다. 메모리 캐시와 intent만 있다. cursor·conditional runtime은 설치된 operation이 쓰지 않는다(런북 상태표 31-32행) |
| **12** | 동시성 성숙도 | P | 세대 fence가 늦은 응답을 버린다(scope-fence 테스트 통과, M5 검출). 같은 세대에서 같은 입력은 같은 intent다. 첫 요청이 아직 처리 중일 때 같은 키 재전송이 `NOT_APPLIED`로 닫혀, 다음 저장이 다른 작업으로 식별된다(03-01). 새로고침·로그아웃·다른 탭은 새 키다(런북 6.3-7에 적힌 한계) |
| 13 | 확장성 | > | extreme-scale은 11 영역 |
| 14 | 성능 성숙도 | O | 본문·JSON 구조·재시도·텔레메트리 배치 상한이 계약값이고 해당 테스트가 통과한다(E1·E2). 이번 라운드에 부하 측정은 하지 않았다 |
| **15** | 보안 성숙도 | O | 자격증명 헤더는 프로필이 정한다(`http-contract-bridge.ts:58-106`). 요청은 `redirect:"error"`, `no-referrer`, `no-store`(`http-execution-v3.ts:905-916`). subject를 못 대면 닫힘 방향이다(`server-state-scope-runtime.ts:218-237`, M5 검출). 서버 반사 correlation 값은 문법 검사 뒤에만 쓴다(`http-execution-v3.ts:1618-1631`). 알림 없는 계정 전환은 owner 계약 밖이다 |
| 16 | 의존성 성숙도 | > | 13 영역 |
| **17** | API / Contract | P | 0.2.0 변경은 [계약] 행으로 알린다(`CHANGELOG.md:24-27`, `:43`). 공개 포트를 단계 없이 필수로 바꿨다(4절 B). "처리 중" 응답의 status·분류가 계약에 없다(03-01). `commandRecovery.mode`는 실행 코드가 여전히 읽지 않는다(03-03). 교차 origin CORS 요구는 문서 통제뿐이다(03-02) |
| 18 | 배포 성숙도 | > | 13 영역. 03-02는 배포 절차에도 걸린다 |
| 19 | 설정 성숙도 | P | `REQUEST_TIMEOUT_MS`는 상한으로만 쓴다(`http-execution-v3.ts:450-456`). 기본 설정의 API가 다른 origin인데 그에 따른 CORS 요구를 확인하는 설정·검사가 없다(03-02) |
| 20 | 개발자 경험 | > | 14 영역 |
| 21 | Guardrail 성숙도 | P | owner 메서드 누락은 시작 때 막힌다(`runtime-adapters.ts:135-160`). KEYED 명령은 recovery descriptor가 필수다(`external-contract-runtime.ts:492-494`). 재전송은 descriptor를 읽지 않고(03-03), CORS 전제는 검사하지 않는다(03-02) |
| **22** | 추상화 성숙도 | P | `FeatureHttpBinding`은 전송 정책을 숨기고 좁다. V3 실행기의 단일 조율부는 유지가 맞다(4절 판단). `useApplicationMutation`은 모든 명령에 `resendUnknownEffect`를 주면서 안전 조건을 내보내지 않는다(03-03). 분류기 추상화는 "처리 중"을 표현할 수 있지만(`MAYBE_APPLIED`) 샘플과 계약이 그렇게 쓰지 않는다(03-01) |
| 23 | 일관성 | O | 전송별 KEYED 재시도·`Retry-After`·timeout 의미가 한 표에 있다(`backend-api-and-server-state-contract.md:600-611`) |
| 24 | 네이밍 / 의미 | P | `resendUnknownEffect` 주석은 "keyed command carries the same key"(`application-query.ts:229-234`)인데 키 없는 명령에도 동작한다. `IDEMPOTENCY_REPLAY`라는 mode 이름과 달리 실행 경로가 mode를 보지 않는다(03-03) |
| 25 | 조직 확장성 | > | 14 영역 |
| 26 | Ownership | P | owner 책임(`starter-experience.md:48-76`)과 백엔드 CORS·멱등 책임(`backend-api-and-server-state-contract.md:251-300`)이 문서에 있다. 두 다운스트림 기록은 subject·같은 키는 백엔드 질문으로 올렸지만 CORS 헤더는 올리지 않았다(03-02) |
| 27 | 삭제 가능성 | > | 09·14 영역. 오케스트레이터 `test:sample-removal` PASS |
| 28 | 회복 가능성 | P | 결과 불명 쓰기는 같은 세대 안에서 같은 키로 복구된다(E2). "처리 중" 409 뒤와 새로고침·fence 뒤에는 새 키다(03-01, 런북 6.3-7) |
X(미충족)는 없다. 6·8·12·17·28은 지난 라운드의 결함이 닫혔지만 이번 라운드 발견 때문에 P다.
## 4. 설계 선택 설명 (41절)
`[사실]`은 코드·실행으로 확인한 것, `[기록]`은 커밋·문서에 적힌 의도, `[추론]`은 리뷰어의 해석이다.
### A. 모든 V3 요청에 `x-correlation-id`를 항상 붙인다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 사용자 문의 한 건을 서버 로그 한 건과 잇는다. `[기록]` 지난 03-03, `CHANGELOG.md:24` |
| 2. 지킬 성질 | 논리 실행당 id 하나, 재시도가 공유, telemetry에 넣지 않음, id 생성 실패가 요청을 막지 않음 |
| 3. 현재 보장 | `[사실]` `http-execution-v3.ts:817-826`(생성 실패는 삼킴), projector가 diagnostics에만 넣음(`runtime-adapters.ts:250-253`), M2·M3 검출. 짝 백엔드는 들어온 `X-Correlation-Id`를 MDC에 싣는다(`tech-log-backend .../RequestLoggingFilter.java:24-41`). 보장하지 않음: 교차 origin에서 백엔드 CORS 허용 |
| 4. 대안 | (a) 현 상태 + 문서 (b) 현 상태 + 배포 전 preflight 점검 (c) 설정·프로필 스위치로 끌 수 있게 (d) 같은 origin BFF를 기본으로 권장 |
| 5. 비교 | (a) 비용 0. 누락하면 전면 실패. (b) 명령 한 줄·런북 한 줄. 자동화하면 CI가 API에 닿아야 한다. (c) 설정 표면이 늘고, 끄면 03-03의 목적을 잃는다. 긴급 우회 수단은 된다. (d) 인프라 결정이라 템플릿 범위 밖 |
| 6. 현재 조건에서 | `[추론]` 헤더 자체는 유지가 맞다. bearer 프로필의 `Authorization`이 이미 preflight를 만들어서, 헤더 하나를 더 허용하는 비용이 작다. 빠진 것은 누락을 배포 전에 드러내는 수단이다(03-02의 최소안 = (b)의 문서판) |
| 7. 재검토 조건 | 같은 origin 배포가 기본이 될 때, 조직 표준이 `X-Request-Id`로 바뀔 때, preflight 없는 simple request가 필요한 성능 요구가 생길 때 |
### B. `readSubject`를 필수로 하고, subject가 없으면 알림마다 fence한다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 같은 사용자의 토큰 갱신에는 캐시를 지키고, 계정 전환에는 반드시 비운다. `[기록]` `c6300e9` 커밋 메시지 |
| 2. 지킬 성질 | 이전 사용자의 서버 상태가 새 세션에 보이지 않는다(15). 같은 (상태, subject) 알림은 fence하지 않는다 |
| 3. 현재 보장 | `[사실]` 메서드 누락은 `integration-failed`(`runtime-adapters.ts:135-160`). 인증 상태에서 subject가 null·빈 값이면 identity를 null로 두고 매번 fence + 경고(`server-state-scope-runtime.ts:99-115`, `218-249`). M4·M5 검출. 보장하지 않음: owner가 알리지 않는 계정 전환(포트 계약 밖) |
| 4. 대안 | (a) 현재: 필수 메서드 (b) 선택 메서드, 없으면 null과 같게 처리 (c) 선택 → 경고 → 필수의 두 릴리스 이행 |
| 5. 비교 | (a) 이행을 빠뜨리면 인증 경로 전체가 닫힌다. 요란하지만 데이터는 안전하다. (b) 같은 안전성, 이행 비용 0. 대신 누락이 "갱신마다 캐시 삭제"라는 조용한 비용으로 남고, 경고는 메모리에만 있어 아무도 못 본다. (c) 안전하지만 두 릴리스에 걸친 관리 비용 |
| 6. 현재 조건에서 | `[사실]` 두 다운스트림은 이미 이행했다(tech-log는 `null` 반환, memento는 owner 없음). `[추론]` 되돌리면 또 하나의 계약 변경이 된다. **현 상태 유지.** subject 없는 경로는 닫힘 방향이라 안전하다. tech-log처럼 상태 변화 때만 알리는 owner에서는 추가 fence가 없고, 경고는 로그인마다 메모리에 1건이라 소음이 되지 않는다. 경고가 "원래도 일어날 fence"에도 찍힌다는 점은 문서 설명(`starter-experience.md:64-69`)과 일치한다 |
| 7. 재검토 조건 | 제품이 diagnostics sink를 붙여 경고가 운영 로그로 나갈 때(그때는 상태가 바뀐 fence에서는 경고를 생략하는 편이 신호가 선명하다). 다음에 공개 포트를 필수로 바꿀 때 (c)를 쓸지 정한다(FOLLOW-UP 2절) |
### C. 결과 불명 쓰기의 키를 세대 안 메모리에 두고, 사용자가 누를 때만 다시 보낸다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 응답을 잃은 쓰기를 다시 보낼 때 서버가 같은 작업으로 알아보게 한다. `[기록]` 지난 03-01, 런북 6.3-4 |
| 2. 지킬 성질 | 같은 논리 요청은 같은 키. 입력이 바뀌면 새 키. 자동 재전송 없음. 이전 세대의 intent는 새 세대로 넘기지 않음 |
| 3. 현재 보장 | `[사실]` `application-query.ts:502-545`, `601-613`, `736-747`. 504 → 재전송 E2(`reference-production-vertical.test.tsx:123-167`). M1·M7 검출, M6 생존. 보장하지 않음: 새로고침·fence·다른 탭(런북 6.3-7), "처리 중" 응답 뒤(03-01), 키 없는 명령(03-03) |
| 4. 대안 | (a) 현재 (b) intent를 sessionStorage에 두어 새로고침 뒤에도 유지 (c) 백오프 자동 재전송 (d) inspect operation으로 조회한 뒤 결정 |
| 5. 비교 | (b) 사용자 범위·만료·정리 비용이 생기고 다른 계정으로 새는 경로를 막아야 한다. (c) 사용자 모르게 반복되고 서버 멱등이 확인돼야 한다(U-5 미확인). (d) 백엔드 조회 엔드포인트가 필요하다 |
| 6. 현재 조건에서 | `[추론]` 백엔드 멱등 계약이 확인되지 않았고 조회 엔드포인트도 없다. (a)가 가장 작고 한계가 런북에 적혀 있다. 유지하되, 키 결합이 서버의 "처리 중" 답에 풀리지 않게 하는 보강이 필요하다(03-01) |
| 7. 재검토 조건 | 백엔드가 status·inspect 엔드포인트를 주면 (d). 새로고침 뒤 중복이 실제로 관측되면 (b) |
V3 `execute()`의 크기(약 620줄)는 39.7로 따로 봤다. 마감·재시도·취소·effect 누적이 한 요청의 같은 상태를 공유하고, 순서가 정확성에 영향을 준다. 순수 판정은 이미 `http-retry-lifecycle.ts`·`http-effect-certainty.ts`로 빠져 있다. 더 나누면 호출자가 순서를 외워야 하므로 **현 상태 유지**가 맞다. 03-05는 이 조율부 안의 분기 하나를 고치는 문제다.
## 5. 발견 사항 (36.3)
| ID | 심각도 | 우선순위 | 성격 | 관련 관점 | 제목 |
|---|---|---|---|---|---|
| 03-01 | High | P1 | 확인된 결함 | 6, 12, 17, 28, 5, 4 | 같은 키 재전송이 "처리 중" 409를 받으면 샘플 분류기가 `NOT_APPLIED`로 닫아 키 보호가 풀린다 |
| 03-02 | Medium | P2 | 구조적 위험 | 17, 19, 8, 6, 26, 21 | `x-correlation-id` CORS 허용이 교차 origin 배포의 전제인데 문서 통제뿐이다 |
| 03-03 | Medium | P2 | 구조적 위험 | 6, 5, 22, 24, 17, 21 | 결과 불명 재전송이 키 없는 명령에도 열려 있다 |
| 03-04 | Medium | P2 | 확인된 결함 | 8, 7, 6 | 결과 불명 쓰기에 문의 식별자가 없다 |
| 03-05 | Low | P2 | 확인된 결함 | 6, 8, 10, 1 | 마감이 최종 불변식 검사 직전에 끝나면 시간 초과가 "입력 거절"이 된다 |
| 03-06 | Low | P3 | 개선 제안 | 10, 6 | UNKNOWN 동안 identity lease를 잡는 코드를 검증하는 테스트가 없다 |
### 03-01 같은 키 재전송이 "처리 중" 409를 받으면 샘플 분류기가 `NOT_APPLIED`로 닫아 키 보호가 풀린다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 6, 12, 17, 28, 5, 4 |
| 근거 | ① reference 생성 분류기는 모든 409를 `NOT_APPLIED`로 판정한다(`src/features/reference-feature/contracts/reference-feature-contract-contribution.ts:37-51`). ② 템플릿 백엔드 계약은 409를 "idempotency fingerprint, domain revision 또는 semantic conflict"로 쓰고(`docs/architecture/backend-api-and-server-state-contract.md:211`), 같은 키의 동시 재전송은 "bounded `IN_PROGRESS` 결과"라고만 적어 status를 정하지 않는다(`:298-300`). ③ 짝 백엔드 템플릿은 처리 중인 같은 키 요청에 `409 IDEMPOTENT_IN_FLIGHT`(retryable=false, "client polls")를 준다(`../clean-architecture-backend-template/src/shared-contract/.../OperationalError.java:47`, 같은 계열 `../tech-log-backend/.../GlobalExceptionHandler.java:190-198`). ④ 재전송을 시작할 때 이전 UNKNOWN admission을 먼저 정리한다(`src/presentation/adapters/query/application-query.ts:523-528`). 재전송 결과가 `NOT_APPLIED`면 새 admission도 정리하고 conflict를 켠다(`:583-589`). ⑤ 폼은 CONFLICT에서 결과 불명 기록을 지우고(`src/presentation/forms/use-app-form.ts:227-230`), 화면은 "충돌을 해결한 뒤 다시 제출할 수 있습니다."를 보이며 저장 버튼을 다시 연다(`reference-resource-form-page.tsx:53-54`, `:120-121`, `:175`). ⑥ 다시 저장하면 UNKNOWN admission이 없어 새 intent·새 키를 만든다(`application-query.ts:504-508`, `:537-543`). **재현(격리 worktree):** 수직 테스트 harness에 MSW로 504 → 409(`IDEMPOTENT_IN_FLIGHT`) → 201을 주고 저장 → 재전송 → 저장을 눌렀다. `Idempotency-Key`가 `[K, K, K′]`였고, 409 뒤 화면에 충돌 문구가 떴다(`review-2026-09-29/03/experiments/zz-review03-in-flight-409.test.tsx`). 다운스트림 tech-log의 분류기는 4xx 전체를 `NOT_APPLIED`로 판정한다(`tech-log-frontend` `src/features/tech-log/contracts/tech-log-studio-contract-contribution.ts:144-146`) |
| 발생 조건 | 첫 쓰기의 응답을 잃었는데(게이트웨이 504, 클라이언트 마감) 서버는 아직 처리 중이다. 사용자가 "같은 요청으로 다시 보내기"를 누르거나 같은 입력으로 다시 저장한다. 느린 서버 때문에 시간 초과가 난 경우라면 흔한 순서다 |
| 영향 | 화면이 "충돌"로 안내해 사용자가 다시 제출하게 한다. 그 제출은 새 키라 서버가 막지 못한다. 첫 요청이 끝나면 같은 리소스가 두 번 생긴다. 사용자는 마지막 성공만 본다. 지난 라운드 03-01(High)과 같은 피해다. 복제 범위는 샘플 분류기와 폼 흐름을 복사한 모든 KEYED 명령이다 |
| 심각도·우선순위 | High · P1 — 35.2의 "결과 불명 작업의 무방비 재실행"이다. 짝 백엔드의 기본 응답과 템플릿 샘플의 기본 판정만으로 생기는 경로다. 실제 중복 피해를 관측하지는 않아 P0는 아니다 |
| 통제·증거 | M1(런북 6.3-4 "UNKNOWN에 새 key 금지"). 코드 통제는 분류기 정확성에 달려 있다 · E2(격리 재현) + E1(백엔드 코드 읽기) |
| 확실성과 남은 가정 | 프론트 경로는 재현으로 확정했다. in-flight가 409라는 것은 짝 백엔드 코드로 확인했다(실행은 안 함). tech-log 제품 폼이 이 순서를 허용하는지는 실행하지 않았다(동기화 기록 372-378행은 "같은 입력 재시도가 원래 키"라고 적는다) |
| 결정의 근거 | `[사실]` 분류기는 기능 패키지 몫이고(`reference-feature-contract-contribution.ts:33-36` 주석), 플랫폼은 분류 결과를 그대로 믿는다. `[추론]` 03-01 수정 전에는 같은 키가 서버에 다시 가는 경로가 없어서 "409 → NOT_APPLIED"가 안전했다. 같은 키 재전송이 생기면서 409의 뜻이 하나 늘었고, 샘플·계약이 따라오지 않았다 |
| 이해 비용 | 명령을 추가하는 사람은 분류기 한 줄(409)과 mutation 코디네이터·폼의 정리 규칙을 함께 알아야 키가 유지되는지 판단할 수 있다. 이 관계를 적은 곳이 없다 |
| 최소 개선 방향 | ① 백엔드 계약 §6에 "처리 중" 응답을 409 + 코드(짝 백엔드와 같은 `IDEMPOTENT_IN_FLIGHT`)로 고정하고, 분류 규칙 "같은 키가 처리 중이면 `MAYBE_APPLIED`"를 적는다. ② reference 분류기가 그 코드를 `MAYBE_APPLIED`로 판정한다. ③ (플랫폼 방어) 같은 intent로 보낸 재전송이 `NOT_APPLIED`를 받아도 canonical 입력과 intent의 결합은 `APPLIED_CONFIRMED` 전까지 풀지 않는다 |
| 대안 비교 | ①+②만: 문서 한 절과 분류기 한 줄. 모든 패키지가 분류기를 맞게 써야 한다(tech-log는 이미 4xx 전체를 `NOT_APPLIED`로 쓴다). ①+②+③: 분류기가 틀려도 키가 유지된다. 대가로 같은 입력의 진짜 거절(예: 422)은 계속 같은 키로만 나가고, 사용자가 입력을 바꿔야 새 요청이 된다. 이는 "입력이 바뀌면 새 키" 규칙과 같다. 현상 유지는 지난 03-01의 피해를 다시 연다 |
| 단순화의 보존 조건 | 입력이 바뀌면 새 키. 자동 재전송 없음. fence 뒤 이전 세대 intent를 넘기지 않음. UNKNOWN head FIFO(`application-query.ts:855-865`) |
| 비용·부작용 | ③은 admission 수명이 길어진다(`MUTATION_COORDINATOR_BOUNDS.activeIntentsTotal` 안). in-flight일 때 화면 문구는 "충돌"이 아니라 "아직 처리 중"이어야 한다(08 영역과 겹침) |
| 재검토 조건 | 백엔드가 in-flight에 409가 아닌 status를 쓰거나, inspect 엔드포인트가 생기면 분류 대신 조회로 바꾼다 |
| 완료 기준 | 504 → 409(in-flight) → 다시 저장 순서에서 세 요청이 모두 같은 `Idempotency-Key`를 쓰고, 409 뒤 화면이 결과 불명 상태를 유지한다 |
| 검증 방법 | 재현 테스트를 `tests/features/reference-feature/`에 넣고 기대값을 `[K, K, K]`로 둔다. ③을 넣으면 분류기가 409를 `NOT_APPLIED`로 두어도 같은 결과인지 따로 단언한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 지난 03-01의 수정(`dfb1b9e`)에서 생긴 새 경로. 지난 03-01 자체의 회귀는 아니다(504 → 재전송 테스트는 통과) |
### 03-02 `x-correlation-id` CORS 허용이 교차 origin 배포의 전제인데 문서 통제뿐이다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 17, 19, 8, 6, 26, 21 |
| 근거 | V3는 모든 논리 실행에 `x-correlation-id`를 붙이고(`src/adapters/http/http-execution-v3.ts:817-826`) 끄는 설정이 없다(`runtime-adapters.ts:489-533`). 기본 설정의 API는 다른 origin이다(`config/runtime/production.json:3`, `local.json`은 `http://localhost:8080/`). 요구는 문서 세 곳에만 있다(`CHANGELOG.md:24`, `backend-api-and-server-state-contract.md:251-258`, `api-contract-and-server-state-recovery.md:184-191`). 백엔드 계약 목록에는 추적을 켠 실행이 보내는 `traceparent`(`http-contract-bridge.ts:114-122`, `http-execution-v3.ts:814-816`)가 없다. 네트워크 실패 런북 `docs/runbooks/FE-RB-003.md`는 CORS를 원인 후보로 적지 않는다. **브라우저 실험(3엔진):** Allow-Headers에서 이 헤더를 빼면 서버에는 OPTIONS만 오고 POST는 오지 않았다. JS는 원인 없는 TypeError만 받았다(chromium "Failed to fetch", firefox "NetworkError when attempting to fetch resource.", webkit "Load failed"). 원인은 개발자 도구 콘솔에만 나왔다. 헤더를 허용하면 POST가 id를 싣고 도착했다. V3는 fetch 거절을 전송 뒤(`DISPATCHED`)로 기록해(`http-execution-v3.ts:951-965`) 명령은 `MAYBE_APPLIED`(`http-effect-certainty.ts:36-49`), 조회는 재시도 뒤 `NETWORK_FAILURE`(`http-execution-v3.ts:975-995`) → "네트워크에 연결할 수 없습니다."(`src/presentation/i18n/catalog.ts:154`)가 된다. **다운스트림:** tech-log 동기화 기록은 "correlation ids"를 받은 변경 목록(59행)에만 적고, 제품 질문 5개(517-541행)에 CORS가 없다. memento 기록에는 언급이 없다. tech-log-backend의 운영 허용 헤더는 환경 변수라 repo에서 값을 알 수 없다(`application.yml:539`) |
| 발생 조건 | API가 다른 origin이고, 백엔드 CORS가 헤더를 목록으로 허용하면서 `x-correlation-id`를 빠뜨린다 |
| 영향 | 그 origin으로 가는 V3 요청이 전부 실패한다. 쓰기는 모두 "변경 결과를 확인할 수 없습니다"가 되고 재전송도 같은 이유로 실패한다. 서버가 쓰기를 받지 않으므로 데이터 피해는 없다(실험). 운영자는 `api.request.failed`의 `NETWORK_FAILURE` 급증만 본다. diagnostics의 `correlation_id`는 서버에 도착하지 않은 값이다 |
| 심각도·우선순위 | Medium · P2 — 전면 실패지만 첫 요청에서 바로 드러나고, 데이터 피해가 없고, 정적 프론트 롤백이나 백엔드 설정 한 줄로 복구된다. 다운스트림이 교차 origin으로 v0.2.0을 처음 배포하기 전에는 그 제품의 출시 전 확인 항목이다 |
| 통제·증거 | M1(문서 3곳) · E3(브라우저 3엔진) + E1(코드·다운스트림 기록) |
| 확실성과 남은 가정 | 기전은 실험으로 확정했다. 두 제품의 실제 운영 CORS 값은 확인하지 못했다 |
| 결정의 근거 | 4절 A. 헤더를 항상 보내는 선택은 유지할 근거가 있다. 빠진 것은 누락을 배포 전에 드러내는 수단이다 |
| 이해 비용 | 제품 배포 담당자가 CHANGELOG [계약] 행을 읽고 백엔드 팀에 전해야 한다. 보내는 헤더 목록은 코드(`TRANSPORT_OWNED_HEADERS` + 인증 프로필 헤더)와 문서에 따로 있다 |
| 최소 개선 방향 | ① FE-RB-003 첫 분류에 "배포 직후 모든 요청이 `NETWORK_FAILURE`면 브라우저 콘솔의 CORS 메시지와 preflight `Access-Control-Allow-Headers`를 본다"를 넣는다. ② README 업데이트 절이나 배포 절차에 실행 가능한 점검 한 줄을 둔다: `curl -si -X OPTIONS -H 'Origin: <앱 origin>' -H 'Access-Control-Request-Method: POST' -H 'Access-Control-Request-Headers: authorization,content-type,idempotency-key,x-correlation-id' <API_BASE_URL>api/...`. ③ 백엔드 계약 §5 목록에 `traceparent`(추적을 켠 경우)를 넣는다 |
| 대안 비교 | 4절 A 표. 설정 스위치는 설정 표면을 늘리고 끄면 문의 식별자를 잃는다. staging smoke 스크립트는 자동으로 잡지만 CI가 API에 닿아야 한다(U-4와 함께 할 때 추가). 최소안은 문서·절차만 바꾼다 |
| 단순화의 보존 조건 | 논리 실행당 id 하나, 재시도가 공유, telemetry에 넣지 않음, id 생성 실패가 요청을 막지 않음(`http-execution-v3.ts:819-825`) |
| 비용·부작용 | 문서 3곳 수정 |
| 재검토 조건 | 같은 origin BFF가 기본이 되거나, 조직 표준 헤더가 바뀌거나, preflight를 없애야 하는 성능 요구가 생기면 |
| 완료 기준 | 배포 절차에 preflight 점검이 있고, FE-RB-003이 CORS를 첫 후보로 안내하고, 백엔드 계약 목록이 코드가 보내는 헤더와 같다 |
| 검증 방법 | 문서 리뷰. 실험 스크립트(`review-2026-09-29/03/experiments/cors-preflight-exp.mjs`)의 거절·허용 서버에 ②의 명령을 보내 결과가 갈리는지 본다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 지난 03-03 수정의 "비용·부작용"(CORS 허용 헤더 필요)이 실제 통제로 이어졌는지 본 항목 |
### 03-03 결과 불명 재전송이 키 없는 명령에도 열려 있다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 6, 5, 22, 24, 17, 21 |
| 근거 | `resendUnknownEffect`는 head가 UNKNOWN이고 intent가 있는지만 본다(`src/presentation/adapters/query/application-query.ts:736-747`). `requiresIdempotencyKey`가 false면 intent에 키가 없다(`:537-543`). 계약은 NEVER 명령을 recovery descriptor 없이 허용한다(`src/contracts/external-contract-runtime.ts:476-494`). `commandRecovery.mode`는 설치 검사와 예제 화면 표시(`src/presentation/examples/platform-overview-page.tsx:272-274`) 외에 읽는 곳이 없다(grep). AsyncSurface는 핸들러만 주면 버튼을 보인다(`async-surface.tsx:201-206`). 문서는 재전송을 "같은 `Idempotency-Key`"로 설명하고(`api-contract-and-server-state-recovery.md:254-257`, `VD-04-native-form-facade.md:37-40`), FE-RB-003은 "never retry an unkeyed mutation"이라 적는다. **실험:** `requiresIdempotencyKey: false`인 bound mutation에서 `MAYBE_APPLIED` 뒤 `resendUnknownEffect()`가 execute를 한 번 더 불렀고, 두 번째 intent에도 키가 없었다(`review-2026-09-29/03/experiments/zz-review03-keyless-resend.test.tsx`) |
| 발생 조건 | 다운스트림이 NEVER(키 없음) 또는 INSPECT_OPERATION 명령의 폼에 reference 폼처럼 `onResendUnknownEffect`를 연결한다 |
| 영향 | 응답을 잃은 키 없는 쓰기가 다시 실행된다. 첫 요청이 적용됐다면 중복 부작용이 생긴다. 템플릿의 유일한 쓰기 샘플은 KEYED라 지금은 해당 없다. tech-log에는 NEVER 명령이 있지만(`tech-log-management-contract-contribution.ts:143`) 재전송 버튼을 연결하지 않았다 |
| 심각도·우선순위 | Medium · P2 — 피해는 중복 쓰기지만 템플릿과 두 다운스트림에 도달 경로가 아직 없다. 폼을 한 번 복사하면 생긴다 |
| 통제·증거 | M1(런북·FE-RB-003 문장) / 훅 수준 M0 · E2(격리 실험) |
| 확실성과 남은 가정 | 훅 동작은 실험으로 확정. 다운스트림 도달은 없다 |
| 결정의 근거 | 적용 제외 — "키 없는 명령은 재전송하지 않는다"는 규칙이 이미 런북에 있다. mode까지 반영할지만 아래에서 비교한다 |
| 이해 비용 | 기능 작성자는 계약의 `retrySemantics`와 화면의 버튼 연결을 스스로 맞춰야 한다 |
| 최소 개선 방향 | head intent에 `idempotencyKey`가 없으면 `resendUnknownEffect`가 `null`을 돌려주고, 컨트롤러가 `canResendUnknownEffect`를 내보내 AsyncSurface가 버튼을 숨긴다 |
| 대안 비교 | 키 유무만 본다: 조건 1개와 플래그 1개. INSPECT 모드는 가리지 못한다. mode를 bound mutation에 싣는다: 바인딩 경로가 늘지만 INSPECT 명령을 조회로 보낼 자리가 생긴다. INSPECT 구현이 아직 없으므로 키 유무 검사로 충분하다 |
| 단순화의 보존 조건 | KEYED 재전송은 같은 키(기존 테스트 4건) |
| 비용·부작용 | 공개 컨트롤러 필드 1개 |
| 재검토 조건 | INSPECT_OPERATION 구현이 생기면 mode 기반으로 바꾼다 |
| 완료 기준 | 키 없는 UNKNOWN head에서 `resendUnknownEffect`가 `null`이고 버튼이 없다. KEYED 재전송 테스트는 그대로 통과한다 |
| 검증 방법 | 실험 테스트의 기대를 "execute 1회"로 바꿔 넣는다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 지난 03-01의 "선언된 descriptor를 실행 코드가 읽지 않는다"가 mode에 대해서는 여전히 사실이다 |
### 03-04 결과 불명 쓰기에 문의 식별자가 없다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 8, 7, 6 |
| 근거 | 바인딩은 서버가 돌려준 `x-correlation-id`만 `requestId`로 싣는다(`src/adapters/http/feature-http-binding.ts:297-318`). `TRANSPORT_FAILURE`·`CANCELLED`에는 metadata가 없어 `requestId`가 비어 있다(`:407-416`). 실행기는 보낸 id를 알지만(`http-execution-v3.ts:589`, `826`) observation에만 넣고(`:597`, `613`), observation은 기본 sink가 없는 메모리 diagnostics로 간다(`runtime-adapters.ts:243-255`, `322`). 결과 불명 화면은 문의 식별자를 그리지 않는다(`src/presentation/components/async-surface.tsx:172-208`. 종료 오류는 `146-165`에서 그린다). 폼의 `MAYBE_APPLIED` 분기도 실패를 넘기지 않는다(`use-app-form.ts:221-224`). 교차 origin에서는 반사값도 `Access-Control-Expose-Headers`가 있어야 읽힌다(`backend-api-and-server-state-contract.md:256-257`) |
| 발생 조건 | 쓰기가 `MAYBE_APPLIED`로 끝난다: 클라이언트 마감, 연결 끊김, 반사 헤더 없는 504 |
| 영향 | 사용자가 "저장됐는지" 물을 때 줄 식별자가 없다. 요청에는 id가 실려 서버 로그에 있는데도 지원 담당은 시각·사용자로 찾아야 한다. 결과 불명 쓰기는 문의가 가장 필요한 경우다 |
| 심각도·우선순위 | Medium · P2 — 35.2의 "주요 진단 정보 부족". FOLLOW-UP 4절 03-03 행(P3)의 범위를 넓혀 올린다. 반사 헤더가 없을 때만이 아니라, 보낸 id를 알고 있는 전송 실패와 결과 불명 화면 전체가 해당된다 |
| 통제·증거 | M2(반사값 경로, M3 검출) / M0(전송 실패, 결과 불명 화면) · E1 |
| 확실성과 남은 가정 | 경로는 확정. 게이트웨이가 504에 id를 반사하는지는 배포마다 다르다 |
| 결정의 근거 | 적용 제외 — 이미 정한 계약(문의 식별자 → 서버 기록)을 빠진 경로에 적용하는 문제다 |
| 이해 비용 | 운영자는 어느 실패에 식별자가 붙고 어느 실패에 안 붙는지 코드를 읽어야 안다 |
| 최소 개선 방향 | ① 실행 결과에 보낸 요청 id를 싣고(metadata 없는 결과에 선택 필드), 반사값이 없으면 바인딩이 그 값을 `requestId`로 쓴다. ② 결과 불명 상태가 실패의 `requestId`를 들고 있다가 AsyncSurface indicator 분기에서 `template.supportReference`로 보인다(08 영역과 겹침) |
| 대안 비교 | 적용 제외 — 기존 계약을 따르는 단순 보강이다 |
| 단순화의 보존 조건 | telemetry에는 id를 넣지 않는다(VD-07 5-1) |
| 비용·부작용 | 공개 결과 타입에 선택 필드 1개. 서버가 id를 바꿔 쓰면 두 값이 다를 수 있어 문구는 "요청 ID"로 둔다 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 마감 초과 쓰기에서 화면의 식별자가 요청에 보낸 `x-correlation-id`와 같다 |
| 검증 방법 | 수직 테스트: MSW가 응답을 마감보다 늦게 준다 → 화면 식별자 = 요청 헤더 값 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | FOLLOW-UP 4절 03-03 행의 확대 |
### 03-05 마감이 최종 불변식 검사 직전에 끝나면 시간 초과가 "입력 거절"이 된다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 6, 8, 10, 1 |
| 근거 | 시도마다 `budget = remaining()`을 확인한 뒤(`src/adapters/http/http-execution-v3.ts:884-890`) 같은 동기 구간에서 `checkFinalInvariants`가 `remaining()`을 다시 읽는다(`:918-928`). 두 번째 값이 0 이하면 `DEADLINE_EXPIRED`다(`http-contract-bridge.ts:407`). 실행기는 `SCOPE_FENCED`가 아닌 실패를 모두 `FINAL_REQUEST_INVARIANT_FAILED`로 바꾼다(`http-execution-v3.ts:929-941`). 바인딩은 이를 `VALIDATION_REJECTED`(재시도 불가, 행동 없음)로 바꾼다(`feature-http-binding.ts:468-471`, `src/contracts/errors.ts:77`). 화면 문구는 "서버가 입력값을 받아들이지 않았습니다."다(`catalog.ts:185`). **결정적 재현:** 시계를 두 읽기 사이에서 마감 뒤로 옮기면 fetch 0회, 결과 `CONTRACT_VIOLATION`/`FINAL_REQUEST_INVARIANT_FAILED`(`review-2026-09-29/03/experiments/zz-review03-deadline-window.test.ts`). **부하 재현:** `tests/integration/http-execution-v3-live-authority.test.ts`를 12개 동시 × 4회(부하 평균 19~30) 돌리자 1회 실패했다. 실패한 테스트는 "observes a late native rejection"(`:563-604`)이고 메시지는 `expected 'CONTRACT_VIOLATION' to be 'TRANSPORT_FAILURE'`다. 이 테스트는 실제 시간 5ms 마감을 쓴다 |
| 발생 조건 | 남은 시간이 두 동기 읽기 사이에 0이 된다. lease 대기나 백오프가 마감 직전에 끝나거나 메인 스레드가 멈출 때다. 드물다 |
| 영향 | 시간 초과가 "입력 거절"로 보이고 다시 시도 버튼이 없다. `api.request.failed`의 `error_kind`가 `FINAL_REQUEST_INVARIANT_FAILED`가 되어 운영자는 클라이언트 결함으로 읽는다. CI를 켜면 테스트가 무작위로 실패한다(FOLLOW-UP 3절) |
| 심각도·우선순위 | Low · P2 — 창이 좁고 데이터 피해가 없다. 수정이 분기 하나이고 CI 활성화(U-1)를 막는 flaky의 원인이라 P2로 둔다 |
| 통제·증거 | M2 · E2(결정적 재현) + E3(부하 재현) |
| 확실성과 남은 가정 | 확정. 실제 사용자 환경의 발생 빈도는 모른다 |
| 결정의 근거 | 적용 제외 — 분류 누락이다 |
| 이해 비용 | 운영자가 `FINAL_REQUEST_INVARIANT_FAILED`를 보면 요청 조립 결함을 찾아 코드를 읽게 된다 |
| 최소 개선 방향 | `checkFinalInvariants`의 `DEADLINE_EXPIRED`를 `SCOPE_FENCED`처럼 따로 받아 `abandonedTransportFailure("TIMEOUT")`로 끝낸다. live-authority의 실제 시간 5~20ms 마감 테스트는 `monotonicNow`·`sleep` 주입으로 바꾼다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 다른 불변식 실패는 그대로 `FINAL_REQUEST_INVARIANT_FAILED` |
| 비용·부작용 | 분기 1개, 테스트 수정 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 두 읽기 사이 마감 경과가 `TRANSPORT_FAILURE`/`TIMEOUT`이다. live-authority 파일이 같은 부하 실행에서 실패 0이다 |
| 검증 방법 | 결정적 재현 테스트를 넣는다. 12개 동시 × 4회 부하 실행을 반복한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | FOLLOW-UP 3절 "재현 조건을 찾는다"의 답 |
### 03-06 UNKNOWN 동안 identity lease를 잡는 코드를 검증하는 테스트가 없다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 10, 6 |
| 근거 | 결과 불명이 되면 입력 identity lease를 잡는다(`src/presentation/adapters/query/application-query.ts:601-608`). 이 코드를 지워도 영역 테스트 569건이 모두 통과했다(변이 M6). lease가 없으면 행의 참조 수가 0이 되고, 등록부가 4,096개·4MiB를 넘을 때 오래된 행부터 지워진다(`src/contracts/query-keys.ts:198-232`). 그 뒤 같은 입력은 새 token → 새 intent·새 키가 된다(`application-query.ts:428-430`, `504-508`) |
| 발생 조건 | 결과 불명 쓰기 뒤 같은 세대에서 4,096개가 넘는 다른 입력이 intern된다(긴 세션, 많은 필터 조합) |
| 영향 | 지금은 코드가 막는다. 이 줄이 사라져도 테스트가 잡지 못한다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M2(구현) / 검출 없음 · E2(변이 생존) |
| 확실성과 남은 가정 | 확정 |
| 결정의 근거 | 적용 제외 — 테스트 추가 문제다 |
| 이해 비용 | 적용 제외 |
| 최소 개선 방향 | `maxEntries`가 작은 등록부로 scope를 만들고, UNKNOWN 뒤 다른 입력으로 등록부를 채운 다음 같은 입력 저장이 같은 키인지 단언하는 컴포넌트 테스트 1건 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 테스트 1건 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 변이 M6이 그 테스트로 검출된다 |
| 검증 방법 | 변이 M6 재실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
## 6. FOLLOW-UP 재확인
| FOLLOW-UP 항목 | 결과 | 현재 근거 |
|---|---|---|
| 2절 P2 `readSubject` 필수화 — README 업데이트 절에 이행 절차 한 줄, 단계 정책 결정 | **유효(일부 해소)** | 이행 절차는 `docs/architecture/starter-experience.md:72-76`과 `CHANGELOG.md:43`에 있다. README 업데이트 절(`README.md:330-346`)은 "[계약] 행이 요구하는 백엔드·배포 변경을 적용한다"는 일반 규칙만 있고 이 한 줄은 없다. "선택 → 경고 → 필수" 단계 정책은 결정 기록이 없다. 두 다운스트림은 이행을 마쳤다(4절 B) |
| 3절 P2 `http-execution-v3-live-authority` 간헐 실패 | **유효 — 원인 확인** | 03-05. 부하에서 1/48 재현, 결정적 재현 성공. 제품 코드의 분류 누락과 실제 시간 5ms 마감 테스트가 겹친 결과다 |
| 4절 P3 03-03 "서버가 correlation 헤더를 돌려주지 않으면 `requestId`가 비어 있다" | **유효 — 범위를 넓혀 03-04로 올림** | `feature-http-binding.ts:297-318`, `async-surface.tsx:172-208` |
| 6절 U-5 백엔드 멱등 키 계약 | **판단 불가(사용자 몫)** | 짝 백엔드 코드에서 재생, 본문 불일치 422, 처리 중 409를 읽었다(실행 안 함). 템플릿 문서는 불일치를 409로 적는다(`backend-api-and-server-state-contract.md:298`). 처리 중 409는 03-01로 이어진다 |
이 영역에 해당하는 나머지 FOLLOW-UP 항목은 없다(07-03은 07 영역, 06-05·06-08은 06 영역).
## 7. 미검증 목록
| 무엇을 | 왜 확인하지 못했나 | 무엇이 있으면 확인할 수 있나 |
|---|---|---|
| 두 제품의 운영 CORS 허용 헤더 | tech-log-backend는 환경 변수(`APP_SECURITY_CORS_ALLOWED_HEADERS`)라 값이 repo에 없다. memento 백엔드는 README만 있다 | 배포 환경 설정 또는 staging에 대한 preflight 요청 |
| 03-01이 tech-log 운영 폼에서 실제로 일어나는지 | 제품 repo는 읽기만 했고 제품 테스트를 돌리지 않았다 | tech-log 브랜치에서 504 → 409 → 재저장 시나리오 테스트 |
| 백엔드 멱등 계약 전체(U-5) | 짝 백엔드는 코드만 읽었다. 보관 기간·동시 재전송 처리를 실행하지 않았다 | 백엔드 통합 환경 |
| 앱 전체를 브라우저에 띄운 상태의 CORS 거절 화면 | 실험은 fetch 수준만 했다. 화면 문구는 코드로만 확인했다 | 교차 origin 실제 서버를 둔 e2e(현재 e2e는 `page.route`로 API를 가로챈다) |
| 여러 탭의 결과 불명 쓰기 | intent가 탭 메모리에만 있다는 것은 코드로 확인했다. 두 탭 시나리오는 돌리지 않았다 | 두 컨텍스트 e2e |
| Browser RPC 실제 provider | 기본 조합에 들어 있지 않다(확장 지점) | Connect/gRPC-Web 통합 |
| 게이트웨이 리다이렉트형 세션 만료 | 쿠키 프로필을 쓰는 설정이 템플릿에 없다(지난 라운드와 같음) | `SAME_ORIGIN_COOKIE` 프로필 조합과 302 로그인 응답 |
| 성능 | 이번 라운드에 측정하지 않았다 | 13·11 영역의 측정 |
@@ -0,0 +1,334 @@
# 04 realtime 어댑터 성숙도 리뷰
> 검토일: 2026-09-29 · 기준: `main` / `af3d8e6` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 깊게 본 관점: 6, 7, 12, 13, 14, 17
## 0. 머리말 (36.1)
| 항목 | 기록 |
| --- | --- |
| 영역 | realtime reference runtime: SSE·WebSocket 연결, reconnect coordinator, stream coordinator, event codec·consumer, bounded polling, live↔poll handoff |
| 경로 | `src/adapters/realtime/` 16파일 9,790줄, `tests/unit/realtime/` 16파일 9,914줄. 연결 지점: `src/contracts/realtime-streams.ts`, `src/application/ports/realtime/shared.ts`, `config/recipes/frontend-capability-recipes.json:29-74` |
| 기준 커밋·작업 상태 | `af3d8e6`. 워킹트리 변경은 리뷰 가이드 문서 2개뿐이고 코드는 `af3d8e6`과 같다 |
| 전제 (0.1) | 템플릿. realtime은 `RECIPE_AVAILABLE` / `AVAILABLE_NOT_COMPOSED`이고 production 조합이 없다(`frontend-capability-recipes.json:30-32`, `:59`). 조합 코드(attempt·session bridge, 환경 신호, 닫기)는 채택 프로젝트 몫이다. 브라우저 SPA, 탭마다 연결 1개(설계 5.6) |
| 읽은 코드 | `reconnect-coordinator.ts`, `reconnect-policy.ts`, `sse/fetch-sse-connection.ts` 전부. `event-codec.ts`, `event-consumer.ts`, `stream-coordinator.ts`, `websocket/websocket-connection.ts`, `polling/bounded-poll-coordinator.ts`, `result.ts`, `sse/sse-parser.ts`는 지난 리뷰 뒤 바뀐 부분과 이번 판정에 필요한 부분(`git diff 4626b73 af3d8e6`) |
| 읽은 테스트 | `realtime-reconnect-coordinator.test.ts` 전부, `event-consumer.test.ts:224-400`, `fetch-sse-connection.test.ts`의 04-05·04-06 절, `websocket-connection.test.ts:1150-1175` |
| 읽은 문서(주장) | `CHANGELOG.md:50`, 설계 `realtime-events-web-push-and-bounded-polling.md` 5.3~5.6·6.3~6.4·11·13.1·15.2~15.4절, `decisions/VD-28-…md:252-275`, `optional-adapter-recipes.md:171-188`, 지난 리뷰 `2026-09-25-maturity-review/04-adapters-realtime.md`, `README.md` 11절, `FOLLOW-UP.md` |
| 소비자 증거 | `../tech-log-frontend`, `../memento-frontend`의 `chore/template-sync-v0.2.0`: 둘 다 realtime 32파일을 그대로 싣고 조합하지 않는다(`AVAILABLE_NOT_COMPOSED`, 예산 40,900). 동기화 기록에 realtime 충돌·수정은 없다 |
| 실행한 테스트 | 분리 worktree에서 `node scripts/run-vitest.ts run tests/unit/realtime/` → **14 files, 221 passed** |
| 스크래치 실험 | E1~E11. worktree `tests/unit/realtime/`에 넣고 돌린 뒤 뺐다. 파일은 `scratchpad/review-2026-09-29/04/zz-review04-exp.test.ts`(E1~E9), `zz-review04-exp2.test.ts`(E10·E11). 정책은 실제 값에 가깝게 두었다(base 1s, max delay 30s, 10회, 5분, stable 30s). 가짜 clock·fetch·socket을 썼다 |
| 변이 실험 | 18건(`mutate.py`, `mutate2.py`, 결과 `mutation-results*.txt`). **18건 모두 검출.** M14 하나는 실패 메시지 없이 테스트 프로세스가 멈추는 방식으로만 드러났다 |
| 가드레일 | worktree에서 `node scripts/check-realtime-boundaries.ts` → PASS. `node scripts/check-realtime-boundary-fixtures.ts` → PASS(규칙 2건 거절). 지난 리뷰의 세 번째 규칙은 `7f2a1607`에서 dependency-cruiser 그래프 규칙으로 옮겨졌다 |
| 번들 측정 | `scripts/lib/optional-recipe-bundle.ts`의 `measureOptionalRecipeBundle`을 직접 불렀다(`zz-measure.ts`). `af3d8e6`: **40,886 / 40,900 gzip bytes, 여유 14바이트**. lane D 전 `8ffb04e` 39,903 → lane D `46417e3` 40,605 → lane F `96cf513` 40,886 |
| 수정 후보 시험 | 04-01의 최소 수정(2줄)을 worktree에 넣고 E10·E11과 기존 reconnect 테스트 36건을 돌렸다. E10·E11은 재시도하고 끝났고 기존 36건은 모두 통과했다. 시험 뒤 되돌렸다 |
| 확인하지 못한 범위 | `test:realtime-removal`: worktree의 `node_modules`가 메인 링크라 pnpm 실행이 위험하다(오케스트레이터 경고, 06 영역도 같은 이유로 중단). 실제 브라우저·실제 SSE/WS 서버·프록시, 여러 클라이언트 재연결 분포, 브라우저 파서 성능. 7절에 적었다 |
| 이전 리뷰와 비교 | 2026-09-25 04-01~04-08은 모두 닫혔고 회귀는 없다(6.2절). 이번 High(04-01)는 지난 04-01과 다른 경로다. 해당 코드는 `6c52cdb9`(2026-07-30)부터 있었다 |
**영역 판정 (35.8)**
- codec·stream coordinator·WebSocket 연결·polling·handoff: **지정 범위에서 사용 가능.** 입력 검증, 자원 상한, 순서·중복·gap 처리, 늦은 콜백 fence가 유지되고 변이로 검출된다.
- reconnect coordinator + WebSocket: **조건부 사용 가능.** 지난 04-01(오래 열린 연결의 재연결 중단)은 고쳐졌다. 채택 조건은 heartbeat ACK를 `markValidHeartbeatOrEvent`로 넘기는 것이다. hidden 탭에서 heartbeat를 멈추면 예산이 초기화되지 않는다(04-04).
- reconnect coordinator + SSE: **해당 용도의 사용 보류.** 브라우저가 online인 채로 서버가 내려가거나 스트림이 끊기면 재연결도 종료도 없이 멈춘다(04-01, High). 2줄 수정이다. SSE를 coordinator에 잇는 세션 bridge도 없다(04-02).
## 1. 결론
- **04-01 (High):** SSE는 fetch 거절과 읽기 중 네트워크 오류를 모두 `OFFLINE`으로 보고한다. reconnect coordinator는 `OFFLINE` 실패 뒤 새 `online` 이벤트가 올 때까지 기다린다. 브라우저는 네트워크 상태가 바뀌지 않으면 `online` 이벤트를 보내지 않는다. 그래서 서버 다운·배포 중 연결 reset에서 run이 `RUNNING`으로 영원히 멈춘다. 실험에서 20분 동안 시도 1회, 재시도 예약 0회, 종료 결과 없음이었다. 관측 이벤트도 `ATTEMPT_STARTED` 하나뿐이다.
- **04-02 (Medium):** 템플릿이 주는 SSE↔reconnect 도구는 연결 전 실패만 다룬다(`readSseForReconnect`). 열린 SSE 세션을 attempt·session으로 나누고, EOF·`NO_RECONNECT`·`RECOVERY_COMMITTED`를 재연결 결과로 옮기는 규칙은 코드·문서 어디에도 없다. 열린 SSE 세션이 coordinator를 지나는 테스트도 없다. 04-01이 숨어 있던 곳이 여기다.
- **Low 3건:** SSE `retry:` 값 처리 규칙이 설계 두 곳과 코드에서 달라 서버가 더 긴 대기를 요구하면 오히려 더 빨리 재연결한다(04-03). hidden 탭에서 heartbeat를 멈춘 조용한 WS는 예산을 새로 받지 못한다(04-04). CHANGELOG의 [계약] 문장이 실제 초기화 조건보다 넓게 말한다(04-05).
- **확인된 강점:** 지난 04-01~04-08의 수정은 코드와 실험으로 확인했다. 오래 열린 연결의 offline 깜빡임, 같은 틱 안의 offline/online, `waitClosed` 예외, 12번 연속 긴 세션 모두 재연결했다(E1·E1b·E2·E3). 변이 18건을 모두 테스트가 잡았다.
- **FOLLOW-UP:** realtime 레시피 번들 예산은 여유가 14바이트다. 04-01 수정을 포함해 realtime을 한 줄만 고쳐도 예산을 다시 올려야 할 가능성이 높다.
## 2. 대표 흐름 (체크리스트 2절)
### 2.1 정상 흐름 — 조용한 WebSocket 구독이 서버 재시작 뒤 재연결한다
```text
입력 조합 코드가 coordinator.run() 호출
정책 attempt(context) → createWebSocketConnection(observe=HEARTBEAT_ACK→context.markValidHeartbeatOrEvent)
(reconnect-coordinator.ts:640-699, websocket-connection.ts:375-378)
상태 WELCOME → SESSION_OPENED(:877-878). heartbeat ACK마다 validSignalObserved=true(:685-687)
외부I/O 6분 동안 이벤트 없이 heartbeat만 오감
실패 서버 재시작 close 1012 → RESTART → PROVIDER_UNAVAILABLE retryable(websocket-connection.ts:1811-1817)
세션 종료 시 "유효 신호 + 30초 이상 유지"면 retriesUsed=0, budgetStartedAt=종료 시각(reconnect-coordinator.ts:886-900)
결과 full jitter 대기 뒤 새 소켓으로 재연결(테스트 realtime-reconnect-coordinator.test.ts:1830-1913, 변이 M1·M6 검출)
```
같은 흐름에서 네트워크가 1초 끊기면 세션은 offline 경로로 끝난다. 예산은 같은 규칙으로 초기화된다. online 복귀 시 elapsed 예산을 다시 시작한다(`:550-559`). E1·E1b·E2에서 확인했다.
### 2.2 피해가 큰 흐름 — SSE 스트림 중 서버가 연결을 끊는다 (04-01)
```text
입력 열린 SSE 세션. 브라우저 네트워크는 정상(navigator.onLine=true, 이벤트 없음)
외부I/O 백엔드 재시작·프록시 upstream 종료로 청크 종료 없이 연결이 끊김 → reader.read() reject
실패 fetch-sse-connection.ts:396-400 → OFFLINE(RECEIVE, retryable:true)
서버 다운으로 연결 거절이면 fetch reject → :213-218 → OFFLINE(CONNECT)
정책 coordinator가 OFFLINE 실패를 받으면 requireOnline()(reconnect-coordinator.ts:798, :994-998)
→ requiredOnlineVersion = 현재+1(:424-429)
상태 다음 루프에서 waitOnline()(:455-479)이 새 online 이벤트만 기다린다. 타이머 없음
결과 run은 RUNNING으로 남는다. 재시도 0회, 종료 결과 없음, RETRY_SCHEDULED·RUN_ENDED 관측 없음(E10·E11)
stream freshness는 마지막 값(CURRENT)을 유지한다. 조합 코드는 fallback으로 넘어갈 신호를 받지 못한다
```
### 2.3 변경 흐름 — 백엔드가 기존 stream에 이벤트 종류를 추가한다
```text
입력 새 백엔드가 registry에 없는 eventType을 보냄. 이전 번들 탭이 열려 있음
정책 codec: stream을 찾은 뒤 eventType 조회 실패 → PROTOCOL_MISMATCH / operation REGISTRY(event-codec.ts:170-176)
실패 객체와 stream을 WeakMap에 기록(:72-106)
상태 consumer가 해당 stream을 invalidate → freshness UNKNOWN(event-consumer.ts:87-91, stream-coordinator.ts:998-1001)
외부I/O SSE는 읽기를 끝낸다. WS는 receipt.error에 같은 실패를 담아 닫는다(websocket-connection.ts:1060-1072, :1379-1384)
실패 retryable:false → reconnect coordinator는 그대로 반환
결과 조합 코드가 operation REGISTRY를 보고 reload를 유도한다(설계 13.1, :1921-1926)
테스트: event-codec.test.ts:70-78, event-consumer.test.ts:318-400(변이 M7·M8·M9·M15 검출). WS 경로 테스트는 없다
```
템플릿 쪽에서 이벤트 종류를 추가하려면 registry 항목, payload schema codec, mapper binding을 함께 맞춰야 한다. 생성 시 서로 대조해 어긋나면 거절한다(`src/contracts/realtime-streams.ts:313-321`).
## 3. 28개 관점 판정표 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가
| 번호 | 관점 | 판정 | 근거·잔여 위험 |
| --- | --- | --- | --- |
| 1 | 코드 성숙도 | O | 상태 기계(IDLE/RUNNING/DRAINING/CLOSED)와 terminal·idempotent close가 유지된다. 221건 통과 |
| 2 | 구조적 성숙도 | O | kernel(`platform/`)과 ports·contracts만 import한다. `check:architecture` PASS(오케스트레이터) |
| 3 | 변경 용이성 | P | 이벤트 종류 추가는 registry·schema·mapper를 생성 시 대조한다. SSE를 조합하려면 bridge를 직접 써야 한다(04-02) |
| 4 | 인지 부하 | P | `runLoop`가 약 670줄이다(`reconnect-coordinator.ts:360-1031`). 조합 코드는 markValid 출처, classifyClosed, hint 통로, OFFLINE 의미를 알아야 한다 |
| 5 | 위험 가시성 | P | `isCurrent`·markValid·환경 신호 책임은 타입 주석에 적혔다(`:58-63`, `:106-113`, `:175-181`). OFFLINE 실패가 "online 이벤트 대기"라는 의미는 코드 안쪽(`:798`)에만 있다(04-01) |
| 6 | 실패 성숙도 | **X** | 지난 04-01은 해소됐다(E1~E3, M1·M2·M3 검출). 새 결함: SSE 네트워크 오류가 OFFLINE이 되어 run이 무기한 멈춘다(04-01, E10·E11). 서버 hint 상한 처리도 값에 따라 뒤집힌다(04-03, E9) |
| 7 | 운영 성숙도 | P | reconnect·poll에 닫힌 관측 어휘가 생겼다(`:128-152`, 변이 M12 검출). online 대기 상태는 관측도 결과도 없다(E10: `ATTEMPT_STARTED`만 1건) |
| 8 | 디버깅 가능성 | P | operation `REGISTRY`로 구버전 클라이언트를 구분한다. `getState()`는 연결 중과 online 대기를 모두 `RUNNING`으로 보여 준다(04-01) |
| 9 | 유지보수 성숙도 | P | VD-28·설계 5.3이 코드와 맞다(`VD-28-…md:258-271`). CHANGELOG [계약] 문장이 넓다(04-05). 설계 문서의 줄 번호 참조는 지금은 맞지만 검사 대상이 아니다 |
| 10 | 테스트 성숙도 | P | 221건 통과, 변이 18/18 검출. 열린 SSE 세션이 coordinator를 지나는 테스트가 없다. 04-01 수정 후보(2줄)를 넣어도 기존 36건이 모두 통과한다. 즉 이 동작을 고정한 테스트가 없다 |
| 11 | 데이터 성숙도 | O | cursor는 effect 성공 뒤에만 전진하고 메모리에만 있다. 이번 라운드에 바뀐 곳 없음(E1) |
| 12 | 동시성 성숙도 | O | 한 번에 run 1개(`:363-364`), recovery single-flight(`stream-coordinator.ts:665`), 중단 뒤 늦게 온 세션 닫기(`:1615-1621`), scope·generation fence. 변이 C1·C2·C3 모두 검출. 탭별 연결과 hidden 닫기는 설계상 조합 코드 몫이다(설계 5.6) |
| 13 | 확장성 | P | 구독 32, 큐 256건/4MiB, dedupe 2,048건 등 상한은 그대로다(설계 11절). 레시피 번들 여유 14바이트(측정). 서버 재시작 뒤 여러 클라이언트 재연결 분포는 측정하지 않았다 |
| 14 | 성능 성숙도 | P | 1MB 단일 chunk를 256KB씩 나눠 넣는다(`fetch-sse-connection.ts:423-446`, 변이 M10 검출). 번들 40,886/40,900. 브라우저 파서 성능은 미측정 |
| 15 | 보안 성숙도 | O | 고정 same-origin HTTPS/WSS, URL에 credential 없음, 401/403 즉시 종료(`fetch-sse-connection.ts:583-588`). 이번 라운드 변경 없음(E1) |
| 16 | 의존성 성숙도 | O | 외부 패키지 없음. native API는 facade로 주입. boundary 검사 PASS |
| 17 | API/Contract 성숙도 | P | REGISTRY 실패 계약은 구현·테스트됐다(SSE 경로). OFFLINE 의미가 "네트워크 오류 전반"과 "online 이벤트 대기"로 갈린다(04-01). SSE `retry:` 상한 규칙이 설계 5.3과 6.3에서 다르다(04-03). consumer의 `invalidate`는 선택 의존성이라 빠져도 타입이 통과한다(`event-consumer.ts:67-68`) |
| 18 | 배포 성숙도 | P | 새 이벤트 종류가 구버전 탭에서 REGISTRY로 드러난다. 백엔드 배포가 SSE 연결을 reset하면 멈춘다(04-01) |
| 19 | 설정 성숙도 | P | 정책은 생성 시 검증하고 상한은 낮추기만 한다(`reconnect-policy.ts:43-67`). 파서의 `maxRetryMs`(60s)와 정책 `maxDelayMs`가 따로 놀아 04-03이 생긴다 |
| 20 | 개발자 경험 | P | WS는 테스트 안에 조합 예시가 있다. SSE는 세션 bridge 예시가 없다(04-02) |
| 21 | Guardrail 성숙도 | O | `check-realtime-boundaries`·fixture PASS. CI 게이트에 등록(`config/ci/gates.json:364-370`, `:526-527`). 조합 금지 규칙은 그래프 규칙으로 옮겨졌다(12 영역) |
| 22 | 추상화 성숙도 | P | attempt/session 경계가 transport를 잘 숨긴다. SSE는 한 번의 `read()`가 연결과 수신을 모두 해서 이 경계에 맞추는 부품이 없다(04-02) |
| 23 | 일관성 | P | 같은 네트워크 오류가 WS에서는 PROVIDER_UNAVAILABLE, SSE에서는 OFFLINE이다(04-01). 상한 넘은 hint가 헤더면 종료, SSE `retry:`면 무시다(04-03) |
| 24 | 네이밍/의미 | P | `OFFLINE`이 SSE에서는 "기기 offline"이 아닌 "요청이 네트워크 단계에서 실패"를 뜻한다(04-01) |
| 25 | 조직 확장성 | - | 작성자 1인. registry에 `owner` 필드가 필수인 것만 확인 |
| 26 | Ownership | - | 제품 조합이 없다. recipe `owner: project-owner-required`(`frontend-capability-recipes.json:68`) |
| 27 | 삭제 가능성 | ? | `test:realtime-removal`은 worktree에서 pnpm이 필요해 돌리지 않았다. CI 게이트에는 있다(`gates.json:526-527`) |
| 28 | 회복 가능성 | P | gap·cursor 만료 → snapshot 복구는 유지. WS·offline 깜빡임 재연결은 해소. SSE 네트워크 오류 뒤 스스로 회복하지 못한다(04-01) |
## 4. 설계 선택 설명 (41절)
### 4.1 재시도 예산은 "유효 신호 + 안정 유지"를 모두 채운 세션이 끝날 때만 초기화하고, offline 뒤에는 elapsed만 다시 시작한다
1. **무엇이 필요한가:** 오래 건강했던 연결이 끊기면 다시 붙어야 한다. 곧바로 끊기는 서버에는 재연결 폭주를 만들지 않아야 한다.
2. **지킬 성질:** 시도 횟수와 경과 시간은 연속 실패 구간에만 쌓인다. 열리자마자 끊기는 연결은 예산을 새로 받지 못한다.
3. **현재 보장:** 세션이 어떤 방식으로 끝나든 한 곳에서 판정한다(`reconnect-coordinator.ts:886-900`). 판정 함수는 두 조건을 모두 요구한다(`reconnect-policy.ts:137-149`). offline 대기 뒤에는 `budgetStartedAt`만 다시 잡고 `retriesUsed`는 둔다(`:550-559`). 변이 M1~M4가 모두 검출됐다. **보장하지 않는 것:** 유효 신호를 조합 코드가 넘겨야 한다. 넘기지 않거나 heartbeat를 멈춘 조용한 세션은 예산을 새로 받지 못한다(E6, E7 → 04-04). 30초보다 짧은 세션이 offline으로 10번 끊기면 run이 끝난다(E5, 시도 11회 뒤 `OFFLINE retryable:true`).
4. **대안:** (a) 세션이 열리기만 하면 초기화. (b) 안정 유지 시간만 요구. (c) 유효 신호만 요구. (d) 현재 방식.
5. **비교:** (a)는 열리자마자 닫는 서버에 영구 재연결을 만든다. (b)는 이벤트 없이 열려만 있는 반쯤 죽은 연결도 보상한다. (c)는 comment 하나 보내고 끊는 서버에 예산을 계속 준다. (d)는 조합 코드가 신호를 넘겨야 하는 비용이 있다.
6. **현재 조건에서의 이유:** 기록된 의도는 `reconnect-policy.ts:131-136` 주석과 VD-28 7절(`:258-260`)에 있다. 확인한 코드도 그 의도대로 동작한다. 리뷰어 판단으로는 유지가 맞다.
7. **재검토 조건:** hidden 탭에서 연결을 유지하는 제품이 생기면 heartbeat 정지와 예산 규칙을 함께 다시 본다(04-04). 짧은 세션이 반복되는 모바일 환경의 실제 종료율이 측정되면 `stableOpenMs`와 시도 상한을 다시 본다.
### 4.2 `OFFLINE` 실패는 새 `online` 이벤트를 기다린다 (04-01의 뿌리)
1. **무엇이 필요한가:** 기기가 실제로 offline이면 타이머로 헛된 재시도를 하지 않는다.
2. **지킬 성질:** 어떤 실패 뒤에도 run은 재연결하거나, 정해진 예산 안에서 끝나야 한다. 무기한 대기는 조합 코드가 fallback을 고를 기회를 없앤다(설계 5.3 "budget을 소진하면 … fallback").
3. **현재 보장:** 환경이 offline을 알린 경우는 맞게 동작한다(E1·E8). **보장하지 않는 것:** transport가 스스로 `OFFLINE`을 보고하면 환경이 online이어도 새 online 이벤트를 요구한다(`:798`, `:994-998`). SSE는 모든 fetch·reader 거절을 OFFLINE으로 보고한다(`fetch-sse-connection.ts:213-218`, `:396-400`). 설계 13.1은 `OFFLINE`을 "network hint/attempt failure → online hint 뒤 bounded check"로 적는다(`:1889`). 같은 설계 5.3은 "`navigator.onLine`은 실제 backend reachability authority가 아니다"라고 적는다(`:780`). 두 문장이 어긋난다.
4. **대안:** (a) 현상 유지. (b) coordinator에서 환경이 offline일 때만 online 이벤트를 요구한다. (c) SSE가 fetch·reader 거절을 `PROVIDER_UNAVAILABLE` retryable로 보고한다(WS의 NETWORK_LOST와 같게). (d) online 대기에 상한 시간을 둔다.
5. **비교:** (a)는 멈춤이 남는다. (b)는 2줄이고 모든 transport에 적용된다. 수정 후보 시험에서 기존 36건이 모두 통과했다. 환경 이벤트보다 먼저 transport가 실패를 보면 한두 번 헛시도가 생기지만 시도 상한 안이다. (c)는 SSE만 고치고 실패 어휘 의미를 바꾼다. 13.1 표도 고쳐야 한다. (d)는 새 상수와 상태가 늘어난다.
6. **현재 조건에서의 판단:** 작성 의도는 기록에 없다. 현재 조건에서 (a)를 유지할 근거는 찾지 못했다. (b)를 권한다.
7. **재검토 조건:** 실제 reachability 확인(예: 가벼운 health 요청)을 환경 신호로 쓰게 되면 (d)나 별도 대기 상태를 다시 비교한다.
### 4.3 서버 hint가 상한을 넘으면 낮춰 자르지 않고 run을 끝낸다
1. **무엇이 필요한가:** 과부하인 서버가 늦게 오라고 하면 그보다 먼저 가지 않는다.
2. **지킬 성질:** 서버가 요구한 시각보다 먼저 재시도하지 않는다(설계 5.3 `:761-766`).
3. **현재 보장:** 헤더 `Retry-After`는 지킨다. 상한(60s) 안이면 대기하고, 넘으면 transport가 `retryable:false`로 끝낸다(`fetch-sse-connection.ts:592-614`). coordinator는 정책 `maxDelayMs`를 넘는 hint를 받으면 끝낸다(`reconnect-coordinator.ts:1509-1514`). 변이 M5 검출. **보장하지 않는 것:** SSE `retry:` 필드는 파서가 60초를 넘으면 버린다(`sse-parser.ts:330-341`). 그러면 hint가 없는 것으로 보고 로컬 지터(0.5초)로 재연결한다. 60초 이하이면서 정책 `maxDelayMs`를 넘으면 모든 끊김이 즉시 종료된다(E9, 04-03).
4. **대안:** (a) 현상 유지. (b) 상한을 넘는 hint를 상한으로 자른다. (c) SSE `retry:`도 상한을 넘으면 transport가 종료로 보고한다(헤더와 같게). (d) SSE `retry:`는 "기본 재연결 간격"으로만 쓰고 not-before로 쓰지 않는다.
5. **비교:** (b)는 서버 요구보다 먼저 재시도한다. 설계가 금지한다. (c)는 규칙이 하나가 되고 코드는 몇 줄이다. 대신 과도한 `retry:` 값이 SSE 재연결을 끈다. (d)는 표준 SSE 의미에 가깝지만 5.3 문장을 바꿔야 한다.
6. **현재 조건에서의 판단:** 헤더 hint를 종료로 처리하는 것은 유지할 근거가 있다. 과부하 신호이고 설계에 기록돼 있다. `retry:` 필드는 설계 5.3과 6.3(`:1031-1032`)이 다른 규칙을 말한다. 둘 중 하나로 정해야 한다.
7. **재검토 조건:** 채택 서버가 `retry:`를 60초 넘게 보내거나, 정책 `maxDelayMs`를 서버 `retry:`보다 작게 잡는 경우가 생기면 바로 정한다.
## 5. 발견 사항 (36.3)
### 04-01 SSE 네트워크 오류가 `OFFLINE`이 되어, 브라우저가 online이면 reconnect run이 재시도도 종료도 없이 멈춘다
| 필드 | 내용 |
| --- | --- |
| 성격 | 확인된 결함 |
| 관련 관점 | 6, 28, 18, 7, 8, 17, 23, 24, 5, 10 |
| 근거 | ① SSE는 fetch 거절을 `OFFLINE(CONNECT, retryable)`로(`src/adapters/realtime/sse/fetch-sse-connection.ts:213-218`), 읽기 중 reader 거절을 `OFFLINE(RECEIVE, retryable)`로 보고한다(`:396-400`). 중단(abort)이 아닌 모든 네트워크 오류가 여기로 온다. ② coordinator는 attempt 실패(`reconnect-coordinator.ts:798`)와 세션 종료 분류(`:994-998`)에서 kind가 `OFFLINE`이면 `requireOnline()`을 부른다. 이 함수는 현재보다 큰 online 버전을 요구한다(`:424-429`). ③ 다음 루프에서 `waitOnline()`(`:455-479`)은 abort나 새 online 이벤트만 기다린다. 타이머가 없다. ④ WebSocket은 같은 상황을 `NETWORK_LOST → PROVIDER_UNAVAILABLE retryable`로 보고한다(`websocket-connection.ts:1811-1817`). 이 경로는 정상 백오프를 탄다. **실험**(`zz-review04-exp2.test.ts`, 브라우저 online 유지·이벤트 없음): E10 연결 전 fetch 거절 → 20분 동안 시도 1회, `getState()` `RUNNING`, 종료 결과 없음, 관측은 `ATTEMPT_STARTED` 하나. online 이벤트를 한 번 보내자 그제야 2번째 시도를 했다. E11 40초 열린 스트림에서 reader가 거절 → 20분 동안 시도 1회, `RUNNING` |
| 발생 조건 | SSE를 reconnect coordinator에 조합했을 때. 기기 네트워크는 정상인데 요청이 네트워크 단계에서 실패하는 경우다. 서버 다운(연결 거절), 배포·재시작 중 프록시가 청크 종료 없이 연결을 끊는 경우, DNS·TLS 오류, CORS 설정 오류가 여기에 해당한다 |
| 영향 | 그 탭의 realtime이 조용히 멈춘다. run이 끝나지 않으므로 조합 코드는 polling fallback이나 stale 표시로 넘어갈 신호를 받지 못한다(설계 5.3 "budget 소진 → fallback"을 우회한다). stream freshness는 마지막 값(보통 `CURRENT`)이다. 사용자 네트워크가 바뀌거나 조합 코드가 `close()` 후 새 run을 만들 때까지 이어진다. reference runtime이라 SSE를 고른 다운스트림에 그대로 복제된다 |
| 심각도·우선순위 | High · P1. 설계가 지원한다고 적은 장애(설계 6.4 "deploy/drain 중 reconnect", 15.3 "server restart")에서 핵심 기능이 멈추고 탐지 신호도 없다. production 조합 전이라 P0는 아니다. SSE realtime 도입 전에 풀어야 할 차단 항목이다 |
| 통제·증거 | M0(transport OFFLINE + 환경 online 경로에 종료 수단 없음) · E2(스크래치 실험, 가짜 fetch) |
| 확실성과 남은 가정 | 코드 경로와 실험으로 확인했다. 실제 브라우저가 이 오류들을 `TypeError` 거절로 주는지는 표준 fetch 동작으로 판단했고 실제 브라우저·서버로 재현하지는 않았다. 조합 코드가 visibility 변화 때마다 `close()`→새 run을 한다면 멈춤이 그 시점에 풀린다. 그런 배선은 저장소에 없다 |
| 결정의 근거 | 4.2절. 현재 선택을 유지할 근거는 찾지 못했다. 설계 13.1(`:1889`)과 5.3(`:780`)이 어긋난다 |
| 이해 비용 | 조합 코드 작성자는 SSE의 `OFFLINE`이 "기기 offline"이 아니라는 점과, coordinator가 그 kind에 특별한 대기를 건다는 점을 둘 다 알아야 한다. 두 사실은 서로 다른 파일의 안쪽 줄에 있다 |
| 최소 개선 방향 | coordinator의 두 곳에서 환경이 offline일 때만 online 이벤트를 요구한다. `if (kind === "OFFLINE" && !online) requireOnline();`. 환경이 online이면 일반 retryable 실패처럼 시도·시간 예산 안에서 백오프한다. 설계 13.1의 `OFFLINE` 행에 "환경이 online이면 bounded retry"를 적는다 |
| 대안 비교 | 4.2절 표. SSE에서 거절을 `PROVIDER_UNAVAILABLE`로 바꾸는 (c)도 가능하다. 다만 SSE만 고치고 실패 어휘 의미가 바뀐다. online 대기에 상한 시간을 두는 (d)는 상태가 늘어난다 |
| 단순화의 보존 조건 | 환경이 offline일 때 타이머 재시도를 하지 않는 동작(기존 테스트 `realtime-reconnect-coordinator.test.ts:400-435`, `:437-467`, E8)을 유지한다 |
| 비용·부작용 | 2줄. 환경 이벤트보다 먼저 transport가 실패를 보면 헛시도가 한두 번 생긴다. 시도 상한(10회) 안이다. 레시피 번들 여유가 14바이트라 예산을 다시 올려야 할 수 있다(6절) |
| 재검토 조건 | 4.2절 7번 |
| 완료 기준 | E10·E11과 같은 조건에서 run이 재시도하거나, 예산을 소진해 `RUN_ENDED(EXHAUSTED)`로 끝난다. 환경 offline 경로의 기존 동작은 그대로다 |
| 검증 방법 | `realtime-reconnect-coordinator.test.ts`에 "브라우저 online인 채 fetch 거절", "열린 스트림 reader 거절" 두 케이스를 ManualClock으로 추가한다. `:798`의 조건을 되돌리는 변이가 실패해야 한다. 수정 후보를 넣은 시험에서 E10은 `RETRY_SCHEDULED:OFFLINE` 뒤 두 번째 시도를 했다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 지난 04-01(예산 초기화)과 다른 경로다. 지난 라운드 실험은 환경 이벤트로 offline을 만들어 이 경로를 지나지 않았다 |
### 04-02 SSE를 reconnect coordinator에 잇는 세션 bridge가 없고, 열린 SSE 세션이 coordinator를 지나는 테스트가 없다
| 필드 | 내용 |
| --- | --- |
| 성격 | 구조적 위험 |
| 관련 관점 | 20, 22, 10, 17, 4, 3 |
| 근거 | coordinator는 attempt가 열린 세션(`waitClosed`, `classifyClosed`, `close`)을 돌려주길 요구한다(`reconnect-coordinator.ts:94-104`, `:159-169`). WebSocket은 `connect()`와 `waitClosed()`가 나뉘어 있어 그대로 맞는다(테스트 `realtime-reconnect-coordinator.test.ts:1772-1803`). SSE는 한 번의 `read()`가 연결과 수신을 모두 한다(`fetch-sse-connection.ts:77-83`). 템플릿이 주는 도구는 `readSseForReconnect` 하나다(`:487-506`). 이 함수는 read 전체를 기다린 뒤 실패에 hint를 붙일 뿐이다. 그래서 조합 코드는 다음을 직접 써야 한다. `onOpen`에서 attempt를 끝내고 read를 세션으로 넘기기, recovery barrier(`waitForRecoveryBarrierConfirmation`, `establishedRecoveryBarrier`) 연결, `onComment`→markValid, 종료 결과 매핑. 종료 결과 중 `EOF`는 `ok:true`다(`:38-47`). 이를 그대로 넘기면 coordinator는 run을 성공(`COMPLETED`)으로 끝낸다(`reconnect-coordinator.ts:976-979`). EventSource처럼 재연결하려면 retryable 실패로 바꾸고 `retryHintMs`를 hint로 옮겨야 한다. 이 규칙은 설계 6.3 상태 표(`:1039-1050`)에도 없다. 저장소의 SSE↔coordinator 테스트 4건(묶음 2개)은 모두 "Only connect failures are exercised here"다(`realtime-reconnect-coordinator.test.ts:1931`, `:1995`) |
| 발생 조건 | 다운스트림이 SSE realtime을 조합할 때 |
| 영향 | 채택자마다 가장 실수하기 쉬운 부분을 따로 만든다. EOF를 성공으로 매핑하면 서버의 정상 종료 뒤 재연결하지 않는다. 04-01 같은 결함이 템플릿 테스트에 드러나지 않는다. 이번 04-01은 리뷰어가 bridge를 직접 써 보고서야 재현됐다 |
| 심각도·우선순위 | Medium · P2. 결함 자체는 조합 코드에서 생기지만, 템플릿이 "fetch-stream SSE"와 "bounded reconnect ownership"을 제공 범위로 적는다(`frontend-capability-recipes.json:33-36`) |
| 통제·증거 | M1(연결 전 실패 bridge만) · E1(코드 읽기), E2(04-01 재현에 쓴 bridge) |
| 확실성과 남은 가정 | 코드와 테스트 목록으로 확인했다. 채택자가 실제로 EOF를 성공으로 매핑하는지는 조합 코드가 없어 미확인이다 |
| 결정의 근거 | 확인한 사실: WS에는 연결·종료 분리 API가 있고 SSE에는 없다. 기록된 의도: `onOpen` 주석이 "A reconnect bridge can hold this gate…"라고 bridge를 전제한다(`fetch-sse-connection.ts:58-62`). 리뷰어 추론: bridge를 전제한 설계인데 부품만 빠졌다 |
| 이해 비용 | 채택자는 coordinator의 결과 모양, SSE 종료 결과 3종, barrier 증명 규칙, hint 통로를 모두 읽어야 한다. 대략 `reconnect-coordinator.ts` 앞 200줄과 `fetch-sse-connection.ts` 전체다 |
| 최소 개선 방향 | `sse/`에 `connectSseForReconnect(connection, input, context)` 같은 함수를 하나 둔다. attempt 결과(열린 세션 또는 연결 전 실패+hint)와 `classifyClosed`(EOF→retryable+`retryHintMs`, `NO_RECONNECT`→성공 종료, `RECOVERY_COMMITTED`→`RECOVERY_RECONNECT`, 실패→그대로+hint)를 만든다. 열린 세션의 EOF·reader 거절·`retry:`를 coordinator까지 지나는 테스트를 붙인다 |
| 대안 비교 | (a) 현상 유지 + 설계 6.3에 매핑 표만 추가: 코드 0줄. 채택자가 여전히 직접 쓴다. (b) bridge 함수 1개(제안): 수십 줄, 번들 예산 인상 필요. 매핑 규칙이 한 곳에 모이고 테스트로 고정된다. (c) SSE 연결을 WS처럼 `connect()`/`waitClosed()`로 나누기: API가 일관되지만 기존 `read()` 소비자와 테스트를 모두 바꾼다 |
| 단순화의 보존 조건 | `read()`의 기존 계약(연결 전 실패, 종료 결과, `onOpen` 게이트)은 바꾸지 않는다 |
| 비용·부작용 | bridge 수십 줄과 테스트. 번들 예산을 올려야 한다 |
| 재검토 조건 | 템플릿이 SSE를 기본 transport에서 빼거나, 제품 조합이 하나 생겨 그 코드가 사실상 기준이 되면 다시 판단한다 |
| 완료 기준 | 채택자가 attempt·classifyClosed를 직접 쓰지 않고 SSE를 조합할 수 있다. EOF 뒤 재연결, `retry:` hint, `NO_RECONNECT` 종료, recovery barrier가 coordinator를 지나는 테스트로 고정된다 |
| 검증 방법 | 새 테스트 + "EOF를 성공으로 매핑" 변이가 실패하는지 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 지난 04-02("Retry-After가 실패 결과에 안 실림")의 수정이 연결 전 실패만 다뤘다. 지난 README 20번 관점 "조합 예시가 테스트 안에만 있다"의 SSE 부분이 남았다 |
### 04-03 SSE `retry:` 값 처리 규칙이 설계 5.3·6.3과 코드에서 달라, 서버가 더 긴 대기를 요구하면 오히려 더 빨리 재연결한다
| 필드 | 내용 |
| --- | --- |
| 성격 | 확인된 결함 |
| 관련 관점 | 6, 17, 19, 23 |
| 근거 | 파서는 `retry:` 값이 `maxRetryMs`(60,000)를 넘으면 버린다(`sse/sse-parser.ts:330-341`, 테스트 `sse-parser.test.ts:105-110`이 99,999를 버리는 동작을 고정). `readSseForReconnect`는 받은 마지막 `retry:` 값을 이후 모든 실패의 not-before로 붙인다(`fetch-sse-connection.ts:296-301`, `:497-505`). coordinator는 hint가 정책 `maxDelayMs`를 넘으면 끝낸다(`reconnect-coordinator.ts:1509-1514`). 실험 E9(정책 max delay 30s, 스트림이 `retry:`를 보낸 뒤 idle timeout): `retry: 45000` → fetch 1회, 재시도 없이 `IDLE_TIMEOUT`으로 종료. `retry: 90000` → 0.5초 뒤 재연결. 설계 5.3(`:761-766`)은 SSE `retry`도 not-before이고 상한을 넘으면 종료라고 적는다. 설계 6.3(`:1031-1032`)은 상한을 통과한 경우에만 hint로 쓴다고 적는다 |
| 발생 조건 | 서버가 `retry:`를 60초보다 크게 보내거나, 정책 `maxDelayMs`보다 크게 보낼 때 |
| 영향 | 60초 초과: 서버가 요구한 시각보다 먼저 재연결한다(5.3 위반). 정책 상한 초과: `retry:`는 보통 스트림 시작에 한 번 오는 기본값이라 그 뒤 모든 끊김(offline 포함)이 재시도 없이 끝난다. 시도 상한이 있어 폭주는 없다 |
| 심각도·우선순위 | Low · P3. 흔한 `retry:` 값(수 초)에서는 나타나지 않는다 |
| 통제·증거 | M1(설계 두 곳이 서로 다름) · E2(E9) |
| 확실성과 남은 가정 | 코드와 실험으로 확인. 채택 서버의 실제 `retry:` 값은 모른다 |
| 결정의 근거 | 4.3절. 헤더 hint의 종료 처리는 유지할 근거가 있다. `retry:` 필드 규칙은 설계 안에서 먼저 하나로 정해야 한다 |
| 이해 비용 | 파서 상한, 정책 상한, bridge의 hint 전파, coordinator의 종료 조건을 네 파일에서 맞춰 읽어야 결과를 예측할 수 있다 |
| 최소 개선 방향 | 규칙을 하나로 정한다. (c) 상한 초과 `retry:`는 헤더처럼 종료로 보고하거나, (d) `retry:`를 not-before가 아닌 기본 간격으로만 쓴다. 정한 쪽에 맞춰 5.3·6.3 문장과 파서 테스트를 고친다 |
| 대안 비교 | 4.3절 4·5번 |
| 단순화의 보존 조건 | 헤더 `Retry-After`의 현재 동작(M5로 검출됨)은 바꾸지 않는다 |
| 비용·부작용 | 몇 줄과 테스트 1~2건 |
| 재검토 조건 | 4.3절 7번 |
| 완료 기준 | `retry:` 값을 키울수록 재연결이 늦어지거나 종료된다(단조). 설계 5.3·6.3이 같은 규칙을 말한다 |
| 검증 방법 | E9와 같은 두 값 케이스를 테스트로 추가한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 04-04 hidden 탭에서 heartbeat를 멈춘 조용한 WebSocket은 예산을 새로 받지 못해, 그 사이 서버가 재시작하면 재시도 없이 끝난다
| 필드 | 내용 |
| --- | --- |
| 성격 | 구조적 위험 |
| 관련 관점 | 6, 28, 20, 5 |
| 근거 | WS는 `heartbeatEligible()`가 false면 heartbeat를 보내지 않는다(`websocket-connection.ts:1083-1088`). 테스트는 이 훅을 "visibility provider"로 쓴다(`websocket-connection.test.ts:1156-1159`). 설계 6.4는 hidden 상태에서 watchdog을 멈추라고 권한다(`:1053-1056`). heartbeat가 없으면 `HEARTBEAT_ACK` 관측이 없고, 조용한 stream은 유효 신호가 없다. 예산 초기화에는 유효 신호가 필요하다(`reconnect-policy.ts:143-148`). 실험 E7: `heartbeatEligible: () => false`로 6분 동안 이벤트 없음 → 1012 → ACK 0건, 소켓 1개, `PROVIDER_UNAVAILABLE retryable:true`로 종료. `heartbeatEligible` 자체에는 주석이 없다(`:177`) |
| 발생 조건 | 조합 코드가 hidden 탭 연결을 닫지 않고 heartbeat만 멈추며, 이벤트가 드문 stream이 `maxElapsedMs`보다 오래 hidden인 채 서버가 재시작할 때 |
| 영향 | 그 탭의 realtime이 끝난다. 결과가 돌아오므로 조합 코드가 visible 복귀 때 새 run을 만들면 회복된다(설계 5.4 visible 행) |
| 심각도·우선순위 | Low · P3. 설계는 hidden 연결을 grace 뒤 닫으라고 권한다(5.4). 그 권고를 따르면 나타나지 않는다 |
| 통제·증거 | M1 · E2(E7) |
| 확실성과 남은 가정 | 실험으로 확인. 채택자가 hidden 연결을 유지하는지는 조합 코드가 없어 미확인이다 |
| 결정의 근거 | 적용 제외 — 4.1절의 규칙은 유지하고, 그 규칙이 heartbeat 정지와 만날 때의 결과를 드러내는 문제다 |
| 이해 비용 | `heartbeatEligible`, markValid, 예산 규칙을 세 파일에서 이어 읽어야 알 수 있다 |
| 최소 개선 방향 | `heartbeatEligible` 주석과 설계 5.3 예산 문단에 "heartbeat를 멈춘 동안은 예산을 새로 받지 못한다. hidden 연결은 닫거나 visible 복귀 때 새 run을 만든다"를 적는다 |
| 대안 비교 | 적용 제외 — 문서 보강만 제안한다 |
| 단순화의 보존 조건 | 적용 제외 — 동작을 바꾸지 않는다 |
| 비용·부작용 | 주석 몇 줄 |
| 재검토 조건 | 적용 제외 — 4.1절 7번과 같다 |
| 완료 기준 | 채택자가 `heartbeatEligible` 옆 주석만 보고 결과를 안다 |
| 검증 방법 | 문서 리뷰 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 지난 04-01 (c)(조용한 WS)의 남은 조건 |
### 04-05 CHANGELOG [계약] 문장이 실제 예산 초기화 조건보다 넓게 말한다
| 필드 | 내용 |
| --- | --- |
| 성격 | 확인된 결함(문서) |
| 관련 관점 | 9, 17 |
| 근거 | `CHANGELOG.md:50`은 "세션이 끝날 때마다 재시도 예산을 초기화하고 offline 동안 멈춘다"고 적는다. 코드는 유효 신호와 안정 유지를 모두 채운 세션만 초기화한다(`reconnect-coordinator.ts:886-900`, E6: 조용한 세션은 초기화 안 됨). offline은 멈춤(누적 보존)이 아니라 online 복귀 시 elapsed를 처음부터 다시 시작한다(`:557-559`). 설계 5.3(`:766-783`)과 VD-28(`:258-265`)은 정확하다 |
| 발생 조건 | 채택자가 CHANGELOG로 업그레이드 영향을 판단할 때 |
| 영향 | 조용한 stream도 초기화된다고 오해해 markValid 배선을 빠뜨릴 수 있다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M1 · E1 |
| 확실성과 남은 가정 | 확인됨 |
| 결정의 근거 | 적용 제외 — 선택 비교가 필요한 문제가 아님 |
| 이해 비용 | 문장 하나 |
| 최소 개선 방향 | "유효 heartbeat·event를 받고 안정 유지 시간을 넘긴 세션이 끝나면 초기화한다. offline 동안의 시간은 elapsed 예산에 넣지 않는다"로 고친다 |
| 대안 비교 | 적용 제외 — 문장 교정 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 없음 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | CHANGELOG, 설계 5.3, VD-28이 같은 조건을 말한다 |
| 검증 방법 | 문서 리뷰 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 지난 04-01·04-08 수정 때 CHANGELOG 요약만 따로 쓰였다 |
## 6. FOLLOW-UP 재확인
### 6.1 `FOLLOW-UP.md` 중 이 영역 항목
| 항목 | 결과 | 근거 |
| --- | --- | --- |
| 1절 P2 레시피 번들 예산 인상(realtime 40,000 → 40,900, `2c5e268`) | **유효** | 측정 40,886 / 40,900, 여유 14바이트. 늘어난 983바이트 중 lane D(realtime 수정)가 702, lane F(web-push)가 281이다. realtime 부분만 떼면 30,160 → 30,858이다. 원인은 지난 라운드 04-01~04-07 수정(관측 훅, bridge, chunk 분할, invalidate)이다. 측정은 tree-shaking을 끄므로 모든 코드가 그대로 잡힌다(`scripts/lib/optional-recipe-bundle.ts:61-64`, `:131-134`). 이번 라운드의 04-01·04-02를 고치면 다시 넘을 가능성이 높다. 줄일 대상은 이번에 찾지 않았다 |
FOLLOW-UP의 나머지 항목(초기 JS 예산, flaky 테스트 등)은 이 영역 밖이다. realtime은 production 번들에 들어가지 않는다.
### 6.2 지난 04 발견의 회귀 확인
| 지난 ID | 현재 | 근거 |
| --- | --- | --- |
| 04-01 오래 열린 연결의 재연결 중단 | 해소 | E1(10분 뒤 1초 offline → 재연결), E1b(같은 틱 offline/online), E2(1분 세션 12번 연속 → 시도 13회, 계속 RUNNING), E3(`waitClosed` 예외), 기존 테스트 `:1830-1913`. 변이 M1·M2·M3·M6 검출 |
| 04-02 SSE Retry-After 유실 | 해소(연결 전 실패 한정) | `readSseForReconnect`(`fetch-sse-connection.ts:487-506`), 변이 M5 검출. 열린 세션 부분은 04-02(이번)로 이어짐 |
| 04-03 모르는 이벤트 종류 | 해소 | `PROTOCOL_MISMATCH/REGISTRY`, freshness `UNKNOWN`. 변이 M7·M8·M9·M15 검출. WS 경로 테스트는 없다 |
| 04-04 hidden·logout·kill switch 책임 | 해소(문서) | `realtime-streams.ts:74-79`, `reconnect-coordinator.ts:106-113`, `:175-181`, 설계 5.4 머리 문단 |
| 04-05 256KB 초과 chunk | 해소 | `fetch-sse-connection.ts:423-446`, 변이 M10 검출 |
| 04-06 SSE idle timeout 테스트 | 해소 | 변이 M11 검출(테스트 2건 실패) |
| 04-07 관측 지점 | 해소 | `RealtimeReconnectObservation`, `BoundedPollObservation`. 변이 M12 검출. online 대기 중 관측이 없는 점은 04-01(이번)에 포함 |
| 04-08 VD-28·설계 5.3 불일치 | 해소 | `VD-28-…md:258-271`과 코드 일치. CHANGELOG 요약은 04-05(이번) |
### 6.3 변이 실험 목록
| ID | 변이 | 결과 |
| --- | --- | --- |
| M1 | 세션 종료 시 예산 초기화 제거 | 검출(4건 실패) |
| M2 | offline 뒤 elapsed 재시작 제거 | 검출(1건) |
| M3 | offline로 끝난 세션은 초기화 안 함 | 검출(1건) |
| M4 | 초기화 조건 `&&` → `||` | 검출(2건) |
| M5 | SSE bridge가 hint를 버림 | 검출(2건) |
| M6 | WS `HEARTBEAT_ACK` 관측 제거 | 검출(1건) |
| M7 | 모르는 이벤트 종류를 다시 `MALFORMED_EVENT` | 검출(2건) |
| M8 | consumer가 invalidate 안 함 | 검출(1건) |
| M9 | `invalidate` 무동작 | 검출(1건) |
| M10 | SSE chunk 분할 제거 | 검출(1건) |
| M11 | SSE `IDLE_TIMEOUT` retryable:false | 검출(2건) |
| M12 | `EXHAUSTED`를 `TERMINAL`로 보고 | 검출(1건) |
| M13 | EOF의 `retryHintMs` 기록 제거 | 검출(1건) |
| M14 | offline 대기 건너뛰기 | 검출(테스트 프로세스가 멈춤, 실패 요약 없음) |
| M15 | codec이 실패 stream을 기록 안 함 | 검출(2건) |
| C1 | recovery single-flight 제거 | 검출(1건) |
| C2 | run 동시 실행 허용 | 검출(2건) |
| C3 | 중단 뒤 늦게 온 세션 안 닫음 | 검출(4건) |
M1 변이에서도 실패 요약이 나온 뒤 vitest 프로세스가 끝나지 않았다. 실패한 테스트가 남긴 대기 때문으로 보인다. 원인은 이 영역 밖(10 영역)이라 여기서는 적기만 한다.
## 7. 미검증 목록
| 항목 | 확인하지 못한 이유 | 확인하려면 |
| --- | --- | --- |
| 04-01이 실제 브라우저·서버에서 같은 모양으로 나타나는지(fetch·reader 거절이 `TypeError`인지, `online` 이벤트가 오지 않는지) | 실제 스트리밍 서버와 브라우저 실행 없음 | 로컬 SSE 서버를 띄우고 Playwright에서 서버 프로세스를 죽였다 살리는 시나리오(설계 15.3 "server restart") |
| `test:realtime-removal` | pnpm이 필요하고, worktree의 `node_modules`가 메인 링크라 pnpm 실행이 메인 설치를 지울 위험이 있다(오케스트레이터 경고) | CI 또는 메인 트리에서 단독 실행 |
| 서버 재시작 직후 여러 클라이언트의 재연결 분포 | 부하 실험 없음. full jitter 공식은 코드와 단위 테스트로만 확인 | N개 클라이언트 시뮬레이션으로 초당 재연결 수 측정 |
| hidden 탭 타이머 throttling, bfcache 복귀, freeze | 브라우저 실행 없음 | Playwright에서 visibility·bfcache 시나리오 |
| 브라우저에서 SSE 파서·chunk 분할 성능 | Node 실험도 이번에는 다시 돌리지 않음 | 실제 브라우저 performance 측정 |
| WS 경로의 REGISTRY 실패 전달 | 코드로는 receipt에 같은 실패가 실린다(`websocket-connection.ts:1379-1384`). 테스트·실험은 SSE만 | `websocket-connection.test.ts`에 모르는 이벤트 종류 케이스 추가 |
| 레시피 번들을 줄일 수 있는 부분 | 증가 원인만 나눴고 줄일 대상은 찾지 않음 | lane D 추가분 702바이트의 파일별 측정 |
@@ -0,0 +1,464 @@
# 05 저장소·adapter kernel 성숙도 리뷰
> 검토일: 2026-09-29 · 기준: `main` / `af3d8e6` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`(워킹트리 수정본), 실행 순서는 `TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md`
> 영역: `src/adapters/storage/`(Web Storage, `indexeddb/`, `opfs/`), `src/adapters/platform/`(adapter kernel), `src/adapters/browser-file-storage/`, `src/application/ports/browser-file-storage/`, 관련 테스트
> 깊게 본 관점: 1, 11, 12, 22, 27, 28
> 영역 판정(35.8): **조건부 사용 가능.** kernel과 Web Storage 어댑터는 지정 범위에서 쓸 수 있다. IndexedDB 런타임은 개인 데이터 dataset에도 쓸 수 있다. 다만 릴리스 롤백 중 계정 삭제는 데이터가 남는다(05-05). OPFS 런타임은 "계정 삭제 뒤 기기에 바이트가 남지 않는다"를 요구하는 제품이라면 05-01·05-02를 고친 뒤 조합한다.
## 0. 머리말 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 | `clean-architecture-frontend-template`, `main` / `af3d8e6`(태그 `v0.2.0` + docs 커밋 1개). 코드는 `af3d8e6`과 같다. 미커밋은 리뷰 가이드 문서 2개뿐이다 |
| 목적·실행 구성 | 템플릿 reference runtime. 브라우저 SPA + 정적 호스팅 + Service Worker. 여러 탭 동시 실행을 지원한다. SSR은 없다 |
| 조합 상태 | IndexedDB·OPFS 런타임은 `AVAILABLE_NOT_COMPOSED`다(`config/recipes/frontend-capability-recipes.json:76-102`). repo bootstrap은 조합하지 않는다. 제품 repo 2개(`tech-log-frontend`, `memento-frontend`, 둘 다 `chore/template-sync-v0.2.0`)도 소스만 복사했고 조합하지 않았다. 아래 결함은 **다운스트림이 이 런타임을 조합할 때** 복제된다. 심각도는 그 조합을 기준으로 매겼다 |
| 규모·운영 목표 | 없다. 13·14번은 미검증으로 둔다 |
| 읽은 코드 | kernel 전 파일(`platform/*.ts` 10개), `browser-file-storage/result.ts`·`storage-manager-adapter.ts`, IndexedDB 런타임(`indexeddb-runtime.ts`, `-maintenance`, `-governance`, `-records`), OPFS(`opfs-byte-store-adapter.ts`, `opfs-worker-runtime.ts`, `indexeddb-opfs-journal.ts`, `opfs-policy.ts`, `opfs-prepared-object.ts`), port 3개(`indexeddb-port.ts`, `opfs-ports.ts`, `shared.ts` 일부), `tests/helpers/memory-indexeddb.ts` 헤더, 05-0x 테스트, `recipes/frontend-capabilities/browser-file-storage-contracts.ts`·`-fakes.ts`의 durable object 부분, `.dependency-cruiser.json:241-251`, `docs/architecture/layers.md:38-52`, `docs/operations/browser-file-storage-recovery.md`의 05-0x 관련 절 |
| 주장으로만 읽은 것 | `CHANGELOG.md` 0.2.0 [보안]·[계약] 행, 지난 리뷰 `2026-09-25-maturity-review/05-*.md`, `FOLLOW-UP.md`, `tasks/todo.md:83` |
| 실행한 명령 | 모두 분리 worktree(`scratchpad/review-2026-09-29/05/wt`, `af3d8e6`)에서 했다. 메인 워킹트리에는 이 문서만 썼다.<br>① `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` → **101/101 통과**<br>② `... indexeddb-runtime.test.ts indexeddb-maintenance.test.ts indexeddb-connection.test.ts` → **86/86 통과**<br>③ `node scripts/check-optional-recipes.ts` → `offline-indexeddb:36891/36900`, `realtime:40886/40900`, `file-transfer:55623/55700`<br>④ `node scripts/check-architecture.ts`(교차 import 2건 주입) → **2건 모두 `adapters-do-not-know-other-concrete-adapters`로 검출**<br>⑤ `node scripts/test-browser-file-storage-runtime-removal.ts` → 1회차 **실패**(`tests/component/router.test.tsx` "reaches the platform overview…", load average 약 21에서 기본 1초 `waitFor` 초과), 2회차 **PASS**(7개 기본 검사, 런타임 의존 테스트 55개 제거). **주의:** 처음에는 `corepack pnpm run test:browser-file-storage-removal`로 시작했고, pnpm이 symlink된 `node_modules`를 지우려다 no-TTY 가드(`ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY`)로 멈췄다. 메인 `node_modules`는 그대로다(항목 수·`.pnpm` 확인). 그 뒤 스크립트를 `node`로 직접 돌렸다. 드릴은 fixture 안에서 pnpm을 부른다(설치 검사 끔). 오케스트레이터의 2026-09-29 지시에 따라 이 드릴은 worktree에서 다시 돌리지 않는다. 이 결과를 증거로 받을지는 오케스트레이터가 정한다<br>⑥ Playwright(`indexeddb-runtime.spec.ts`, `opfs-runtime.spec.ts`, chromium·firefox, 별도 포트 4195) → **16/16 통과**. 두 엔진 모두 `inspectBrowserOpfsSupport`가 `available: true`여서 OPFS spec이 조기 반환 없이 실제로 돌았다 |
| 변이 실험 | 수정을 되돌리는 변이 7개를 넣고 해당 테스트를 돌렸다. **7개 모두 검출됐다.**<br>M1 reconcile이 transaction lock을 무시 → 05-01 테스트 2개 실패. M2 빈 receipt를 JSON으로 파싱 → 05-02 테스트 2개 실패. M3 reconcile이 첫 실패 row에서 멈춤 → 1개 실패. M4 purge의 chunk sweep 제거 → 05-04 테스트 2개 실패. M5 전체 DB 삭제 경로 제거 → 05-03 테스트 3개 실패. M6 `VersionError`를 다시 `MIGRATION_FAILED`로 → 05-06 테스트 1개 실패. M7 admission 중 versionchange 핸들러 제거 → 05-13 테스트 1개 실패.<br>예산 변이: reconcile 보고 뒤에 관측 이벤트 7줄 추가 → `offline-indexeddb (36909 > 36900 gzip bytes)`로 **게이트 실패**. `result.ts` `mapIndexedDbException`에 `case "TimeoutError":` 한 줄 추가 → 통과했지만 레시피 예산 3개가 함께 움직였다 |
| 재현 실험 | 실제 adapter·worker·journal 코드에 메모리 FS와 메모리 IndexedDB를 붙이고, Web Locks는 Node 24 내장 `navigator.locks`를 썼다. 파일: `scratchpad/review-2026-09-29/05/experiments/review05-*.appended.ts`(worktree 삭제 전 보관).<br>X1a·X1b·X1c(05-01 후속 단계), X2(purge vs 같은 객체 덮어쓰기), X3·X4·X5(손상 journal 행·receipt), I1~I4(IndexedDB purge 경계) |
| 확인하지 못한 범위 | WebKit 실행, 실제 quota 초과와 실제 저장소 손상, 2 GiB 객체 검증 시간, v0.1.0 탭과 v0.2.0 탭 공존, X2·X3를 실제 브라우저에서 재현, IndexedDB만 제거하는 드릴(7절) |
| 이전 리뷰와 비교 | 지난 발견 05-01~05-14는 모두 "해결"로 기록돼 있다. 현재 코드에서 다시 확인했고 회귀는 없다(6.2절). 새 발견은 수정 범위 밖에 남은 같은 계열의 빈틈이다 |
## 1. 요약
- **05-01(OPFS reconcile vs 진행 중 put)과 05-02(첫 receipt quota 실패 뒤 GC 정지)는 고쳐졌다.**
- 05-01: 테스트가 보는 PREPARING 단계 외에 FILES_READY(commit 대기)와 COMMITTED(finalize 대기) 단계에서도 다른 탭 reconcile이 row를 건너뛴다(X1a·X1b). 같은 탭 reconcile도 건너뛴다(X1c). 실제 브라우저 2탭 spec이 chromium·firefox에서 통과했다.
- 05-02: 0바이트 receipt는 없는 것으로 보고, reconcile은 실패 row를 세고 GC까지 간다. 두 수정 모두 되돌리면 테스트가 잡는다(M1~M3).
- **CHANGELOG 0.2.0 [보안]·[계약] 주장은 정상 경로에서 사실이다.** 손상된 budget·binding 행 때문에 열리지 않는 IndexedDB dataset은 승인된 LOGOUT·ACCOUNT_DELETION에서 통째로 지워진다(I4, Playwright). OPFS purge는 남은 chunk를 grace 없이 지운다. 미래 스키마는 `INCOMPATIBLE`/`ONLINE_ONLY`다.
- **그러나 삭제 보장에 빈틈이 셋 남았다.**
- OPFS journal의 목록 조회는 손상 행 하나에 전체가 실패한다. 그 partition의 계정 삭제 purge는 객체를 하나도 못 지우고, authority 전체의 reconcile·GC도 멈춘다(05-01, X3·X4·X5). IndexedDB 쪽에서 고친 "손상 한 건이 정리 전체를 막는" 패턴이 OPFS journal에는 남았다.
- 다른 탭이 같은 객체를 덮어쓰는 중에 purge가 돌면 그 객체를 건너뛴다. 그런데도 `moreObjectsAvailable: false`, `chunkSweep: "COMPLETED"`로 보고한다(05-02, X2).
- IndexedDB 전체 삭제 경로는 open 실패 코드 두 개에서만 열린다. 릴리스 롤백 중(`INCOMPATIBLE`)이나 migration 실패 중 계정 삭제는 데이터를 남긴다(05-05, I1).
- **kernel은 정책 저장소가 되지 않았다.** `platform/` 파일 집합은 지난 리뷰와 같다. 이번 라운드에 kernel로 들어간 것은 IndexedDB 예외표 하나이고, 브라우저 데이터 번들 안에서만 쓰인다. 현 상태 유지가 맞다(4.3절). 대신 kernel로 올릴 만한 canonical JSON이 3벌로 갈라져 있다(05-07). kernel 범위 문서가 실제보다 좁다(05-08).
- **같은 이름의 port가 두 벌이다.** `recipes/frontend-capabilities/browser-file-storage-contracts.ts`의 `DurableObjectStorePort`·`DurableObjectMaintenancePort`는 2026-07-30 이후 바뀌지 않았고 src port와 계약이 다르다. catalog는 그 fake를 이 런타임의 fake로 안내한다(05-03).
- **offline-indexeddb 레시피 예산 여유는 9바이트다.** 이 영역에 진단 코드 7줄만 넣어도 게이트가 실패한다(05-04).
## 2. 대표 흐름
### 2.1 정상 흐름 — OPFS put 하나와 다른 탭의 reconcile
```
tab A put ──► per-transaction Web Lock 획득 (adapter:219, :1026-1047)
│ │
│ ├─► journal.begin: PREPARING row + budget 예약 (journal:288-503)
│ ├─► worker BEGIN_PUT: origin 전역 lease 획득 (worker:365-399)
│ ├─► APPEND_CHUNK: chunk 쓰기 → receipt 갱신 (worker:422-478)
│ ├─► FINISH_PUT: manifest·FILES_READY receipt → lease 해제 (worker:480-556)
│ ├─► journal.markFilesReady → commitPut (journal:505-577)
│ ├─► worker FINALIZE_PUT: 이전 세대·staging 삭제 (worker:918-965)
│ └─► journal.complete: row 삭제 (journal:579-615)
└──► lock 해제 → 성공 보고
tab B reconcile ──► listIncomplete → 각 row lock을 ifAvailable로 시도 (adapter:630-648)
├─ 못 잡음 → skippedLiveTransactions += 1
└─ 잡음 → 같은 page를 다시 읽고 정리 (adapter:649-679) → orphan GC
```
- 입력: objectId, expectedGeneration, ByteSource.
- 정책: objectId 문법(`opfs-policy.ts:163-172`), media type, 크기, budget(`journal:457-465`).
- 상태 변화: journal row PREPARING → FILES_READY → COMMITTED → 삭제. committed object row와 chunk reference가 commit 트랜잭션에서 함께 바뀐다(`journal:872-1024`).
- 외부 I/O: OPFS 파일, IndexedDB journal, Web Locks.
- 실패: 보상 실패면 put 자기 코드 + recovery `RECONCILE`(`adapter:1064-1087`). commit 뒤 finalize 실패는 성공이 아니라 실패로 보고하고 row를 reconcile에 남긴다(`adapter:318-330`).
- 결과: 성공이면 open이 같은 바이트를 읽는다. 확인: 단위 테스트, X1a·X1b·X1c, Playwright 05-01 spec(chromium·firefox).
### 2.2 피해가 큰 흐름 — 승인된 ACCOUNT_DELETION purge
```
composition ──► IDB enforceLifecycleBatch(ACCOUNT_DELETION)
├─ 정책 허용? (runtime:2005-2033) → authority proof (runtime:2046-2077)
├─ 연결 없음 → open 시도 (runtime:2574-2579)
│ ├─ POLICY_REJECTED / CORRUPT_DATA → deleteDatabase (runtime:2580-2611) → datasetDeleted
│ ├─ MIGRATION_FAILED / UNSUPPORTED(INCOMPATIBLE) → 그 실패를 그대로 반환 (데이터 남음, 05-05)
│ └─ 성공 → 행 단위 purge (runtime:2281-2503)
──► OPFS enforcePolicies(ACCOUNT_DELETION)
├─ request + consume authority (adapter:886-995)
├─ listCommittedObjects page → objects.remove 각각 (adapter:785-848)
│ ├─ CONFLICT / NOT_FOUND → 건너뜀 (adapter:820-823) ← 05-02
│ └─ 손상 row → 목록 전체 CORRUPT_DATA (journal:785-794) ← 05-01
└─ 남은 객체 없음으로 판단되면 grace 없는 chunk sweep (adapter:849-873)
```
- 입력: action, maxRows/maxObjects, 시간 예산.
- 정책: dataset의 `accountDeletionAction`이 `PURGE_PARTITION`이어야 한다. 삭제마다 composition 승인이 필요하다.
- 상태 변화: IDB 행 또는 DB 전체 삭제. OPFS 객체 디렉터리 삭제, journal object row·chunk reference 갱신, chunk 파일 삭제.
- 실패: 손상 governance(IDB)는 DB 삭제로 끝난다. 손상 journal row(OPFS)는 purge 전체 실패로 끝나고 바이트가 남는다(X3). 동시 덮어쓰기는 건너뛰고 완료로 보고된다(X2).
- 결과: 정상 경로에서는 partition 파일 0개(05-04 테스트). 위 두 경우에는 개인 바이트가 남는다.
### 2.3 변경·삭제 흐름 — IndexedDB `schemaVersion`을 올리는 새 release
```
새 release 탭(v2) open ──► upgrade: 추가만 하는 DDL + binding 확인 (runtime:693-717, governance:167-222)
구 release 탭(v1) 연결 ──► versionchange → kernel이 닫음 (connection:483-489)
구 release 탭 재open ──► VersionError → UNSUPPORTED / ONLINE_ONLY, status INCOMPATIBLE (runtime:662-675, :767-775)
구 release 탭 read/CAS/purge ──► UNSUPPORTED (runtime:865-867)
```
- admission이 도는 동안 온 versionchange도 이제 연결을 닫는다(`connection:430-439`, 05-13). M7로 되돌리면 테스트가 잡는다.
- 롤백 배포(모든 탭이 v1)라면 모든 purge가 `UNSUPPORTED`로 끝난다. v2를 다시 배포할 때까지 계정 삭제 데이터가 남는다(05-05).
- 번들 삭제: `test-browser-file-storage-runtime-removal.ts`가 ports·browser-files·browser-transfer·cache-storage·storage/indexeddb·storage/opfs를 함께 지우고 타입·lint·아키텍처·test:all·build·레시피·CI 계약을 돈다. 2회차 PASS. 1회차 실패는 부하 중 component 테스트의 1초 대기 초과였다(영역 10·11 소관).
## 3. 28개 관점 판정표 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가
| 번호 | 관점 | 판정 | 통제(목표/확인) | 증거 | 이유·잔여 위험 |
|---|---|---|---|---|---|
| **1** | 코드 성숙도 | O | M2 / M2 | E2(101+86 통과), E2 변이 M1~M7 | CAS·revision·generation·fencing 규칙이 put·remove·CAS·reconcile 경로에서 지켜진다(`adapter:204-216`, `journal:395-407`). 05-01 수정이 세 단계에서 유지된다(X1a·b·c). 보고값의 정확성 문제는 11·24에서 센다(05-02) |
| 2 | 구조적 성숙도 | O | M3 / M3 | E3(교차 import 2건 주입 → 2건 검출) | kernel 예외 밖 교차 import 0건(`grep` 전수). 같은 `storage` 그룹 안 indexeddb↔opfs import는 규칙이 보지 않는다. 지금은 0건이다(05-11 해소) |
| 3 | 변경 용이성 | P | M3 / M3 | E3(예산 측정·변이) | 진단 7줄 추가가 레시피 예산 게이트에 막힌다(05-04). 제품이 OPFS 이름을 adapter 소스에서 고쳐 들고 다닌다(05-10) |
| 4 | 인지 부하 | P | — | E1 | 파일 4개가 1.7k~2.6k줄이다(`indexeddb-runtime.ts` 2641줄). journal `begin`은 요청 콜백이 7단 중첩된다(`indexeddb-opfs-journal.ts:301-500`). 대신 05-0x 수정 주석이 "왜"를 가까이 적는다(`adapter:630-633`, `worker:1303-1308`) |
| 5 | 위험 가시성 | P | M1 / M1 | E1 | port 주석이 origin 전역 쓰기 직렬화(`opfs-ports.ts:79-84`), 교체된 세대의 stream `NOT_FOUND`(`:87-95`), `INCOMPATIBLE`(`indexeddb-port.ts:46-52`)을 드러낸다. `chunkSweep`(`opfs-ports.ts:136-141`)과 `datasetDeleted`(`indexeddb-port.ts:154-160`) 설명은 실제 동작과 다르다(05-02, 05-05) |
| 6 | 실패 성숙도 | P | M2 / M2 | E2 | "건너뛰고 세고 보고한다"가 retention sweep·receipt prune·reconcile 루프에 적용됐다. journal 목록 조회는 여전히 손상 행 하나에 전체가 실패한다(05-01) |
| 7 | 운영 성숙도 | P | M1 / M1 | E1 | safe bucket 관측(`observe`)과 연결점만 있다. 조합이 없어 알림 경로는 없다(0.1 전제상 비대상) |
| 8 | 디버깅 가능성 | P | M2 / M2 | E2 | receipt 손상이 `CORRUPT_DATA`로, 미래 스키마가 `INCOMPATIBLE`로 바로잡혔다. reconcile 보고에 `skippedLiveTransactions`·`failedTransactions`가 있다. purge 보고에는 건너뛴 객체 수가 없다(05-02) |
| 9 | 유지보수 성숙도 | P | M2 / M2 | E1 | IndexedDB 예외표가 1벌이 됐다(`result.ts:110-171`, 05-11 해소). canonical JSON 3벌·`sameScope` 2벌(05-07), kernel 범위 문서가 낡았다(05-08) |
| 10 | 테스트 성숙도 | P | M3 / M3 | E2(변이 7/7 검출), E3(Playwright 16/16) | 메모리 IndexedDB가 DB 이름 분리·트랜잭션 직렬화·비활성 요청 예외를 흉내 내고, 흉내 내지 않는 것을 헤더에 적는다(`memory-indexeddb.ts:849-876`). 빈틈: purge vs 동시 덮어쓰기, 손상 journal 행, binding 손상 행(FOLLOW-UP), recipe fake가 다른 계약을 구현(05-03) |
| **11** | 데이터 성숙도 | P | M3 / M2 | E2(X2·X3·I1·I4), E3(Playwright 05-03·05-06) | 손상 governance의 DB 삭제와 미래 스키마 처리는 실제 브라우저에서 확인했다. OPFS purge는 손상 행에 막히고(05-01), 동시 덮어쓰기에서 완료로 잘못 보고한다(05-02). 롤백·migration 실패 중 계정 삭제는 데이터를 남긴다(05-05) |
| **12** | 동시성 성숙도 | P | M3 / M3 | E2(X1a·b·c, M1), E3(Playwright 05-01 chromium·firefox) | 05-01 수정이 후속 단계에서도 유지된다. 잔여: purge와 같은 객체 쓰기의 경합(05-02), lock 이름이 다른 release 탭 공존(미검증), idle bound와 lock wait 관계 미검사(05-09) |
| 13 | 확장성 | ? | — | E1 | 규모 목표가 없다. 코드에는 배치 상한(500행/30초, 스캔 5000행, reconcile 100행/5초)만 있다 |
| 14 | 성능 성숙도 | ? | — | E1 | 2 GiB 객체 검증 시간, dedup 재쓰기 비용을 측정하지 않았다. 번들 크기는 05-04 |
| 15 | 보안 성숙도 | P | M2 / M2 | E2 | opaque DB·경로 이름(`governance:71-83`, `worker:1636-1643`), 관측에서 key·값 제외, 삭제마다 승인. 계정 삭제 뒤 잔존 경로 셋(05-01·05-02·05-05). 두 런타임의 승인 계약이 다르다(05-06) |
| 16 | 의존성 성숙도 | - | — | — | 이 영역은 외부 패키지 없이 브라우저 API만 쓴다 |
| 17 | API / Contract | P | M2 / M2 | E1 | port 변경은 추가만 했고 CHANGELOG [보안]·[계약]에 있다(`CHANGELOG.md:30`, `:42`). 같은 이름의 recipe port가 다른 계약이다(05-03). 주석과 코드가 다른 곳 둘(05-02·05-05) |
| 18 | 배포 성숙도 | P | M2 / M2 | E3(Playwright 05-06) | N-1 탭이 `INCOMPATIBLE`/`ONLINE_ONLY`로 닫힌다. transaction lock이 없는 v0.1.0 탭과 공존하면 그 탭의 put은 보호받지 못한다(미검증, 7절) |
| 19 | 설정 성숙도 | P | M3 / M2 | E1, 실행(`resolveOpfsRuntimePolicy`) | objectId 문법 확장 거절(05-10 해소). `putIdleTimeoutMs < mutationLockWaitTimeoutMs`는 검사하지 않는다(05-09). journal DB 접두사를 설정으로 바꿀 수 없다(05-10) |
| 20 | 개발자 경험 | > | — | — | 영역 14 |
| 21 | Guardrail 성숙도 | P | M3 / M3 | E3(아키텍처 주입, 제거 드릴, 예산 변이) | 세 게이트 모두 동작한다. 예산 게이트는 여유 9바이트라 신호보다 마찰이 크다(05-04). 제거 드릴은 부하 중 타이밍 테스트 하나로 한 번 실패했다 |
| **22** | 추상화 성숙도 | P | M2 / M2 | E3(주입), E1 | kernel은 메커니즘만 갖고 정책·실패 코드는 호출자 `translate`에 둔다(`indexeddb-connection.ts:19-24`, `:42-80`). 현 상태 유지가 맞다(4.3절). 갈라진 중복(05-07), 낡은 범위 문서(05-08), 같은 이름 recipe port(05-03), 두 승인 계약(05-06) |
| 23 | 일관성 | P | M1 / M1 | E1 | 승인 proof 정규식이 `{16,128}`(`indexeddb-runtime.ts:97`)와 `{16,512}`(`opfs-byte-store-adapter.ts:1785`)로 다르다. 비유한 수 처리가 canonical JSON마다 다르다(05-06, 05-07) |
| 24 | 네이밍 / 의미 | P | M1 / M1 | E2(X2) | `chunkSweep: "COMPLETED"`는 "partition이 비었다"로 읽히지만 객체가 남을 수 있다(05-02). `datasetDeleted` 설명의 적용 범위가 코드와 다르다(05-05) |
| 25 | 조직 확장성 | ? | — | E0 | 팀이 하나다. dataset별 opaque scope와 kernel 공유 구조만 준비돼 있다 |
| 26 | Ownership | ? | — | E0 | runbook owner 칸을 조합 branch가 채운다. 조합이 없어 확인할 대상이 없다 |
| **27** | 삭제 가능성 | P | M3 / M3 | E3(제거 드릴 2회차 PASS, 실행 조건은 0절 ⑤ 주의) | 번들 코드 제거는 검증된다. 기기 데이터 삭제는 IDB 쪽이 확인됐다. OPFS는 손상 행·동시 쓰기에서 바이트가 남는다(05-01·05-02). IndexedDB만 제거하는 경우는 드릴 밖이고 그 사실이 주석에 있다(`storage/index.ts:1-10`) |
| **28** | 회복 가능성 | P | M2 / M2 | E2(M2·M3, X4·X5) | 흔한 원인(quota로 남은 빈 receipt)의 영구 정지는 풀렸다. 손상 journal 행이나 읽을 수 없는 receipt는 authority 전체 reconcile·GC를 멈춘다. runbook은 row 수동 삭제와 DB 삭제를 금지하므로 승인된 탈출 경로가 없다(05-01) |
적용 항목 26개(16 제외, 20은 영역 14): 충족 2(1, 2), 부분 충족 20, 미충족 0, 미검증 4(13, 14, 25, 26).
## 4. 설계 선택 설명 (41)
각 항목에서 **[사실]**은 현재 코드·실행 결과, **[기록]**은 코드 주석·문서에 적힌 의도, **[추론]**은 리뷰어의 해석이다.
### 4.1 OPFS 동시성: origin 전역 lease + transaction별 Web Lock (05-01, D-3)
1. **필요:** 같은 origin의 여러 탭이 같은 OPFS root와 journal을 쓴다. 앱 시작 때 reconcile을 돌리는 조합이 흔하다. **[사실]** journal DB는 authority 단위이고 `listIncomplete`는 scope로 거르지 않는다(`journal:685-741`).
2. **지킬 성질:** 성공으로 보고한 put은 읽혀야 한다. reconcile은 주인이 사라진 row만 정리해야 한다. GC는 참조 중이거나 staging 중인 chunk를 지우면 안 된다. 탭이 죽으면 잠금이 풀려야 한다.
3. **현재 보장:** **[사실]** worker는 BEGIN~FINISH 동안 origin 전역 lease를 쥔다(`worker:365-399`, `:545-548`). page는 journal `begin` 전부터 반환까지 transaction별 Web Lock을 쥔다(`adapter:219-364`, `:1003-1047`). reconcile은 row lock을 `ifAvailable`로 잡고, 잡은 뒤 page를 다시 읽는다(`adapter:630-682`). **[사실]** X1a(commit 대기)·X1b(finalize 대기)·X1c(같은 탭)에서 row를 건너뛰고 put이 읽혔다. M1 변이는 테스트 2개가 잡았다. Playwright 05-01 spec이 chromium·firefox에서 통과했다. **보장하지 않는 것:** lock 이름은 `policy.mutationLockName`에서 나온다(`adapter:1012`). release마다 이 값이 다르거나 v0.1.0 탭(transaction lock 없음)과 섞이면 보호가 없다. 쓰기 처리량은 origin 전체에서 하나다.
4. **대안:** (a) 시작한 지 N분 지난 row만 정리한다. (b) journal에서 fencing token을 CAS로 넘겨받고 heartbeat로 주인 생존을 본다. (c) reconcile도 origin lease 아래서만 돈다. (d) 객체별 lock.
5. **비교:** (a)는 시계에 기대고 느린 put을 죽은 put과 구분하지 못한다. 성질 1을 깨뜨릴 수 있다. (b)는 heartbeat 주기와 만료 판단이 새로 생긴다. (c)는 lease가 FINISH에서 풀리므로 FILES_READY~complete 구간을 막지 못한다. 막으려면 origin 직렬화가 commit까지 길어진다. (d)는 chunk가 객체 사이에서 dedup되므로 GC 경합을 막지 못한다.
6. **현재 조건에서의 선택 이유:** **[추론]** Web Locks는 탭이 죽으면 브라우저가 풀어 준다. 그래서 크래시 복구에 시계도 heartbeat도 필요 없다. 비용은 lock 이름 규칙 하나와 reconcile의 재조회 한 번이다. **[기록]** "The lock stays origin-wide so GC and dedup keep seeing one writer; only the wait is bounded"(`worker:1355-1359`), `tasks/todo.md:83`.
7. **재검토 조건:** Web Locks가 없는 realm이 같은 journal을 써야 할 때. release마다 lock 이름을 바꾸는 운영이 생길 때. 여러 탭의 동시 업로드 처리량이 요구될 때(D-3 재검토).
**판단:** 유지한다. 다만 lock 이름이 release 사이에 같아야 한다는 조건을 `opfs-policy.ts`의 `mutationLockName` 설명에 적으면 다음 수정자가 알 수 있다(작은 보강, 발견으로 세지 않음).
### 4.2 승인된 purge에서 DB 전체를 지우는 조건 (05-03)
1. **필요:** LOGOUT·ACCOUNT_DELETION 뒤 기기에 개인 데이터가 남으면 안 된다. 행 단위 purge는 open(admission)이 성공해야 돈다.
2. **지킬 성질:** 승인 없이 지우지 않는다. 다른 partition을 건드리지 않는다. 정상 경로에서 다른 탭의 연결을 끊지 않는다. 결과를 사실대로 보고한다.
3. **현재 보장:** **[사실]** 승인(`runtime:2526-2527`) 뒤 연결이 없으면 open을 시도하고, `POLICY_REJECTED`·`CORRUPT_DATA`일 때만 `deleteDatabase`를 부른다(`runtime:2574-2611`). DB 이름은 partition 토큰 셋에서만 만든다(`governance:71-83`). **[사실]** budget 손상(테스트·Playwright)과 binding 손상(I4) 모두 `datasetDeleted: true`로 끝났다. **보장하지 않는 것:** `MIGRATION_FAILED`·`UNSUPPORTED`(I1)에서는 지우지 않는다. `else` 분기라 SESSION_END에도 적용된다(I2). OPFS에는 같은 경로가 없다(05-01).
4. **대안:** (a) 현상 유지. (b) 승인된 LOGOUT·ACCOUNT_DELETION이면 `BLOCKED`를 뺀 모든 open 실패에서 지운다. (c) purge를 항상 DB 삭제로 한다. (d) admission을 건너뛰고 읽을 수 있는 행만 지우는 open 모드.
5. **비교:** (b)는 롤백 창과 migration 실패에서도 개인 데이터를 지운다. 대신 `EXPORT_THEN_PURGE` dataset에서 export하지 못한 데이터도 지운다. 그 판단은 authority가 해야 한다. (c)는 단순하다. 하지만 정상 경로에서도 다른 탭의 연결을 versionchange로 끊고, governance 행을 다시 만들어야 한다. (d)는 손상됐을 수 있는 DB를 여는 두 번째 open 경로가 생긴다.
6. **선택 이유:** **[기록]** "A LOGOUT or ACCOUNT_DELETION purge must not depend on the dataset passing admission"(`runtime:2566-2573`), runbook "runtime이 스스로 DB를 지우는 경우는 하나뿐이다"(`browser-file-storage-recovery.md:275-289`). **[추론]** 정상 경로는 행 단위로 두고, 영영 열리지 않는 경우만 전체 삭제로 보내는 선택은 타당하다. 제외한 두 코드의 이유는 기록에 없다.
7. **재검토 조건:** 릴리스 롤백 절차를 문서로 정할 때. `EXPORT_THEN_PURGE` dataset이 실제로 조합될 때. OPFS 쪽에 같은 경로를 만들 때.
**판단:** 선택은 유지하되 적용 범위를 정하고 문서를 맞춘다(05-05).
### 4.3 kernel 경계: 메커니즘만 공유하고 정책은 호출자에 둔다
1. **필요:** **[기록]** IndexedDB 사용처 4곳이 open·blocked·upgrade·늦은 연결 처리를 손으로 복제했다(`indexeddb-connection.ts:1-10`). abort 경쟁·Retry-After 파싱·JSON 멤버 스캔도 여러 그룹에 필요하다.
2. **지킬 성질:** kernel은 DB 이름·스키마·실패 코드표·관측 형태를 모른다. adapter는 kernel 밖의 다른 adapter를 import하지 않는다.
3. **현재 보장:** **[사실]** `platform/` 파일 10개는 `4626b73`과 같다(`git ls-tree`). 이번 라운드의 kernel 변화는 `result.ts`에 IndexedDB 예외표가 들어온 것(+81줄)과 05-13 핸들러(+16줄)뿐이다. `translate` 콜백이 실패 코드를 호출자에 둔다(`indexeddb-connection.ts:42-80`). 교차 import 주입 2건이 검출됐다. 소비자: `abortable-operation.ts`는 7개 그룹 21개 파일, `result.ts`는 4개 그룹 30개 파일, IndexedDB kernel은 storage와 browser-transfer 체크포인트(`grep`). **보장하지 않는 것:** `result.ts`의 두 예외표는 정책(복구 힌트)이다. 다만 둘 다 browser-file-storage 번들 안에서만 쓰이고 번들과 함께 지워진다. kernel 편입 기준은 한 파일 머리말에만 있다(05-08).
4. **대안:** (a) 현상 유지. (b) IndexedDB kernel을 `storage` 그룹 안으로 내린다. (c) 예외표를 각 adapter로 되돌린다. (d) kernel을 별도 패키지로 뺀다.
5. **비교:** (b)는 browser-transfer 체크포인트가 storage를 import할 수 없어 복제가 다시 생긴다. (c)는 05-11에서 두 표의 차이가 이미 결함이었다. (d)는 강제력이 커지지만 이행 비용이 템플릿 규모에 비해 크다.
6. **선택 이유:** **[추론]** 현재 조건에서 유지가 맞다. kernel에 쌓인 것은 상태 기계와 파서이고, 업무 정책은 없다. 감수하는 비용은 파급 범위다. `result.ts`에 `case` 한 줄을 더하는 변이가 레시피 예산 3개(file-transfer 55623→55626, offline-indexeddb 36891→36893, service-worker-pwa 9662→9668)를 함께 움직였다(05-04).
7. **재검토 조건:** 재시도 값·관측 이벤트 형태 같은 도메인 판단이 kernel로 들어오려 할 때. 한 그룹만 쓰는 코드가 kernel에 들어올 때. kernel 변경이 레시피 예산을 반복해서 깰 때.
**판단:** 현 상태 유지. 문서 보강(05-08)과 canonical JSON 통합(05-07)만 권한다.
## 5. 발견 사항 (36.3)
| ID | 심각도 | 우선 | 성격 | 관련 관점 | 제목 |
|---|---|---|---|---|---|
| 05-01 | Medium | P2 | 확인된 결함 | 11, 28, 15, 6, 27 | OPFS journal·staging의 손상 한 건이 그 partition의 계정 삭제 purge와 authority 전체의 reconcile·GC를 멈춘다 |
| 05-02 | Medium | P2 | 확인된 결함 | 11, 12, 15, 24, 5, 8 | purge가 지우지 못한 객체를 건너뛰고도 `chunkSweep: "COMPLETED"`로 보고한다 |
| 05-03 | Medium | P2 | 확인된 결함 | 22, 23, 17, 10, 9 | recipe의 같은 이름 port·fake가 src port와 다른 계약으로 갈라져 있다 |
| 05-04 | Low | P2 | 구조적 위험 | 3, 21, 14 | offline-indexeddb 레시피 예산 여유 9바이트: 이 영역의 다음 수정이 게이트에 막힌다 |
| 05-05 | Low | P3 | 확인된 결함 | 11, 15, 17, 24 | IndexedDB 전체 삭제 경로의 적용 범위가 port·runbook 설명과 다르다 |
| 05-06 | Low | P3 | 개선 제안 | 22, 23, 15 | 한 레시피의 두 런타임이 삭제 승인 계약을 다르게 요구한다 |
| 05-07 | Low | P3 | 개선 제안 | 22, 9, 23 | kernel로 올릴 canonical JSON이 3벌로 갈라져 있다 |
| 05-08 | Low | P3 | 확인된 결함 | 22, 9, 2 | kernel 범위 설명이 실제보다 좁고 편입 기준이 한 파일에만 있다 |
| 05-09 | Low | P3 | 확인된 결함 | 19, 12 | `putIdleTimeoutMs < mutationLockWaitTimeoutMs`가 주석에만 있다 |
| 05-10 | Low | P3 | 개선 제안 | 19, 3 | OPFS journal DB 이름 접두사를 설정으로 바꿀 수 없어 제품이 소스를 고친다 |
### 05-01 OPFS journal·staging의 손상 한 건이 그 partition의 계정 삭제 purge와 authority 전체의 reconcile·GC를 멈춘다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (재현) |
| 관련 관점 | 11, 28, 15, 6, 27 |
| 근거 | ① `listCommittedObjects`는 손상 행 하나에 `context.fail(corrupt)`로 목록 전체를 실패시킨다(`indexeddb-opfs-journal.ts:785-794`). purge는 그 실패를 그대로 반환한다(`opfs-byte-store-adapter.ts:797-799`).<br>② `listIncomplete`도 같다(`indexeddb-opfs-journal.ts:714-723`). reconcile은 row를 하나도 보지 못하고 GC 전에 반환한다(`adapter:592-595`).<br>③ `isChunkReferenced`도 손상 참조 행에 실패하고, GC·sweep은 그 자리에서 멈춘다(`journal:849-855`, `adapter:1264-1266`, `:867`).<br>④ 비어 있지 않은 읽을 수 없는 receipt는 staging을 "unsafe"로 만들어 GC를 영구히 `STAGING_STATE_UNREADABLE`로 둔다(`worker:1130-1135`, `:893-903`).<br>⑤ 재현(메모리 FS·IndexedDB, Node Web Locks):<br>X3 — 객체 2개 중 하나의 object row를 손상 → `enforcePolicies(ACCOUNT_DELETION)` = `CORRUPT_DATA/READ_ONLY`, partition 파일 4개(정상 객체 포함)가 그대로, 정상 객체 `object_secret_1`을 여전히 읽을 수 있었다.<br>X4 — 손상 journal row 1개 → `reconcile` = `CORRUPT_DATA`, orphan chunk 남음.<br>X5 — 내용이 깨진 receipt → reconcile 2회 모두 `failedTransactions: 1`, `orphanGcStatus: "STAGING_STATE_UNREADABLE"`, 같은 id 재시도 `CONFLICT` |
| 발생 조건 | journal의 object·journal·chunk reference 행 하나가 validator를 통과하지 못할 때(저장소 손상, 또는 새 release가 row 모양을 바꿨는데 구 탭이 읽을 때). receipt 파일 내용이 깨졌을 때. 원자적 쓰기 때문에 정상 동작에서는 생기지 않는다 |
| 영향 | ① 계정 삭제·로그아웃 purge가 그 partition의 **정상 객체까지** 하나도 지우지 못한다. 개인 바이트가 기기에 남는다. ② journal DB는 authority 단위라 손상 행 하나가 authority의 모든 partition에서 reconcile·GC를 멈춘다. quota가 회수되지 않는다. ③ runbook은 journal row 수동 삭제와 journal DB·OPFS root 삭제를 금지한다(`browser-file-storage-recovery.md:37-40`). 승인된 탈출 경로가 없다. IndexedDB 런타임에는 같은 상황의 출구(05-03 전체 삭제)가 생겼지만 OPFS에는 없다 |
| 심각도·우선순위 | Medium · P2. 손상이 있어야 생기고 피해는 기기 한 대다. 하지만 계정 삭제 계약이 걸렸고, 한번 생기면 스스로 풀리지 않는다. 지난 리뷰의 같은 계열 IndexedDB 결함(05-03)과 같은 등급이다. 개인 파일을 다루는 OPFS 조합 전에 고친다 |
| 통제·증거 | "승인된 purge는 손상이 있어도 끝난다" 규칙: M0 확인(목록 실패 뒤 진행할 코드 경로가 없음) · E2(X3·X4·X5). 실제 브라우저 손상은 미검증 |
| 확실성과 남은 가정 | 경로는 코드와 재현으로 확인했다. 실제 기기에서 journal 행이 손상되는 빈도는 모른다. X5의 "내용이 깨진 receipt"는 원자적 쓰기에서는 저장소 손상으로만 생긴다고 본다 |
| 결정의 근거 | [기록] 손상 데이터는 자동 삭제하지 않는다(runbook "corrupted user-authored row 자동 삭제 0", `worker:894` "Keep unreadable staging in place so orphan GC fails closed"). [추론] fail-closed 자체는 맞다. 문제는 범위다. 행 하나가 목록 전체와 authority 전체를 막는다. 05-02·05-05에서 이미 "건너뛰고 세고 보고한다"로 바꾼 것과 같은 판단이 journal 목록에는 적용되지 않았다 |
| 이해 비용 | 운영자는 `CORRUPT_DATA/READ_ONLY`만 본다. 어느 행인지, 어느 partition이 막혔는지 보고가 없다. 다운스트림은 journal 코드를 읽어야 원인을 안다 |
| 최소 개선 방향 | ① `listCommittedObjects`·`listIncomplete`는 손상 행을 건너뛰고 세어 보고한다(행은 지우지 않는다). ② 승인된 LOGOUT·ACCOUNT_DELETION에 한해, 손상 때문에 purge를 끝낼 수 없으면 그 partition 디렉터리(`authorities/<a>/<ns>/<p>`)를 mutation lease 안에서 통째로 지우고 journal의 그 partition 행을 정리한다. 05-03의 IndexedDB 경로와 같은 승인 조건을 쓴다 |
| 대안 비교 | (a) 현상 유지: 손상 시 삭제 계약이 영구히 깨진다. (b) ①만: reconcile·GC와 정상 객체 purge는 계속된다. 손상 행의 바이트는 남는다. (c) ①+②: 계정 삭제가 끝난다. partition 디렉터리 삭제는 진행 중인 같은 partition put과 경합하므로 lease 안에서 해야 한다. (d) journal DB 전체 삭제: authority의 다른 partition까지 지우므로 부적합 |
| 단순화의 보존 조건 | 손상 행을 자동 수정·삭제하지 않는다(승인된 partition purge 제외). 다른 partition의 행·파일을 건드리지 않는다. 건너뛴 행은 관측으로 보고한다 |
| 비용·부작용 | 목록 API 결과에 "건너뛴 행 수"가 늘어난다(추가만). partition 전체 삭제 경로는 새 위험 경로이므로 승인과 lease 조건을 테스트로 고정해야 한다 |
| 재검토 조건 | journal row 모양을 release 사이에 바꾸는 변경이 생기면(구 탭이 새 행을 손상으로 볼 수 있다) 우선순위를 올린다 |
| 완료 기준 | object row 하나를 손상시킨 partition에서 승인된 ACCOUNT_DELETION이 partition 파일 0개로 끝난다. 손상 journal row 하나가 있어도 reconcile이 나머지 row와 GC를 진행하고 손상 1건을 보고한다 |
| 검증 방법 | X3·X4를 단위 테스트로 옮긴다(`experiments/review05-opfs.appended.ts`). 가능하면 Playwright OPFS spec에 X3을 추가한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 05-02 purge가 지우지 못한 객체를 건너뛰고도 `chunkSweep: "COMPLETED"`로 보고한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (재현) |
| 관련 관점 | 11, 12, 15, 24, 5, 8 |
| 근거 | ① purge는 `remove`가 `CONFLICT`·`NOT_FOUND`면 그 객체를 건너뛴다(`opfs-byte-store-adapter.ts:820-823`). 다시 목록을 읽지 않는다.<br>② chunk sweep 조건은 "남은 객체가 없다"가 아니라 `!moreObjectsAvailable && !deadlineReached && !aborted`다(`adapter:855-861`).<br>③ port 주석은 "once every object is removed"라고 적고, "Chunk bytes are gone only when it is `COMPLETED`"라고 약속한다(`opfs-ports.ts:136-141`). runbook도 "`chunkSweep`이 `COMPLETED`여야 bytes가 지워진 것이다"라고 적는다(`browser-file-storage-recovery.md:431-435`).<br>④ 재현 X2: 탭 W가 `object_secret_1`을 덮어쓰는 동안 탭 P가 `ACCOUNT_DELETION` purge → 보고 `{inspectedObjects: 1, removedObjects: 0, moreObjectsAvailable: false, chunkSweep: "COMPLETED"}`. purge 뒤 partition에 manifest와 chunk가 남았고, 객체(gen 2)를 그대로 읽을 수 있었다. 두 번째 purge가 지웠다 |
| 발생 조건 | purge가 도는 동안 다른 탭(같은 사용자의 다른 탭 등)이 같은 객체에 put·remove를 진행 중일 때. 그 put이 진행 중이면 journal의 logical key unique 제약으로, 이미 commit됐으면 세대 불일치로 purge의 `remove`가 `CONFLICT`가 된다(`journal:487-494`, `adapter:480-489`) |
| 영향 | 계정 삭제 뒤 개인 파일이 남는데, 보고는 완료로 읽힌다. `inspectedObjects - removedObjects`로 짐작할 수는 있지만 port·runbook 어디에도 그 신호가 적혀 있지 않다. 호출자는 재시도할 이유를 모른다 |
| 심각도·우선순위 | Medium · P2. 경합 조건이 필요하지만 로그아웃은 여러 탭이 열린 상태에서 흔하게 일어난다. 피해가 개인정보 잔존이고, 거짓 완료 보고라 발견이 늦다 |
| 통제·증거 | "purge 완료 보고는 partition이 비었을 때만" 규칙: M1(주석·runbook에만 있음) · E2(X2) |
| 확실성과 남은 가정 | 코드 경로와 재현이 일치한다. 실제 브라우저 재현은 하지 않았다. 같은 조건은 remove의 `NOT_FOUND` 뒤 다른 탭이 같은 id를 새로 만드는 순서에서도 생길 수 있다(코드로만 판단) |
| 결정의 근거 | 적용 제외 — 문서화된 계약과 구현이 다른 단순 결함이다. purge가 point-in-time이라는 성질 자체(끝난 뒤 새로 쓴 객체는 남는다)는 IndexedDB purge와 같아서 문제로 보지 않는다. 문제는 **본 객체를 못 지우고도** 완료로 보고하는 것이다 |
| 이해 비용 | 조합 코드 작성자가 port 주석을 믿으면 재시도 루프를 만들지 않는다 |
| 최소 개선 방향 | 건너뛴 객체가 있으면 `moreObjectsAvailable: true`로 보고하고 chunk sweep을 하지 않는다(`chunkSweep` 생략). 또는 `skippedObjects` 수를 보고에 추가하고 주석·runbook의 완료 조건을 "`skippedObjects === 0` 그리고 `chunkSweep === COMPLETED`"로 고친다 |
| 대안 비교 | 적용 제외 — 기대 계약(주석)이 이미 있다. 두 방향 모두 추가만 하는 변경이다 |
| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다 |
| 비용·부작용 | 작다. purge를 한 번 더 부르는 경우가 늘어난다 |
| 재검토 조건 | 적용 제외 — 선택을 바꾸는 판단이 아니다 |
| 완료 기준 | X2 순서에서 purge 보고가 미완료를 드러내고, 같은 purge를 다시 부르면 partition 파일 0개로 끝난다 |
| 검증 방법 | X2를 `opfs-worker-runtime.test.ts`의 05-04 describe에 추가한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 05-03 recipe의 같은 이름 port·fake가 src port와 다른 계약으로 갈라져 있다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (갈라진 중복 복사본) |
| 관련 관점 | 22, 23, 17, 10, 9 |
| 근거 | ① `recipes/frontend-capabilities/browser-file-storage-contracts.ts`는 `DurableObjectStorePort`(`:590-622`), `DurableObjectMaintenancePort`(`:632-639`), `StorageDurabilityPort`, `FilePickerPort` 등을 src port와 **같은 이름**으로 다시 정의한다. 마지막 변경은 `6c52cdb9`(2026-07-30)이다.<br>② 계약이 다르다. recipe `put`은 `id`·`declaredByteLength`·`dataClass`를 받고, `open(id)`이고, `reconcile({timeBudgetMs, maxEntries, cursor})`는 `{resumedCount, purgedCount, quarantinedCount}`를 돌려준다. src는 `open(request)`, `reconcile({budgetMs, maxTransactions})` → `OpfsReconciliationReport`, `enforcePolicies`가 있다(`opfs-ports.ts:77-193`).<br>③ 의미도 반대다. recipe 보고는 resume·quarantine을 세지만, 런타임은 PREPARING을 resume하지 않고 FILES_READY 검증 실패를 quarantine하지 않는다(05-09 수정, `browser-file-storage-recovery.md:418-427`).<br>④ catalog의 offline-indexeddb 행은 src `sourceRoots`와 함께 `port: "... DurableObjectStorePort / DurableObjectMaintenancePort ..."`, `fake: "... MemoryDurableObjectStore ..."`를 적는다(`config/recipes/frontend-capability-recipes.json:85-107`). 그 fake는 recipe 계약을 구현한다(`browser-file-storage-fakes.ts:1691-1692`) |
| 발생 조건 | 다운스트림이 catalog를 보고 이 런타임의 fake를 고를 때. 런타임 port를 바꿀 때(recipe 쪽은 따라오지 않는다) |
| 영향 | ① 05-01~05-14의 port 변경(`skippedLiveTransactions`, `chunkSweep`, `INCOMPATIBLE` 등)이 recipe 쪽에 하나도 반영되지 않았다. "정책 중복으로 변경 누락이 반복됨"(35.2 Medium 예시)의 실제 사례다. ② 같은 이름이라 import 경로를 봐야 어느 계약인지 안다. ③ recipe fake로 쓴 기능 테스트는 실제 런타임에 없는 resume·quarantine을 전제한다 |
| 심각도·우선순위 | Medium · P2. 런타임 피해는 없다. 타입이 달라 섞으면 컴파일에서 드러난다. 하지만 템플릿이 "이 런타임의 fake"로 안내하는 대상이 다른 계약이다 |
| 통제·증거 | "catalog가 가리키는 fake는 src port를 구현한다" 규칙: M0 확인(둘을 잇는 검사 없음) · E1 |
| 확실성과 남은 가정 | 파일과 git 이력으로 확인했다. recipe 계약이 "제품이 복사해 좁혀 쓰는 설계 초안"이라는 의도(`browser-file-storage-contracts.ts:7-13`)는 기록돼 있다. 그 의도와 catalog 안내가 어긋난다. browser-files 쪽 port(영역 02)와 레시피 문서(영역 14)에도 같은 원인이 걸린다. 오케스트레이터가 합칠 수 있다 |
| 결정의 근거 | [기록] recipe 계약은 런타임보다 먼저(7월) 만든 심층 설계다(`docs/architecture/optional-adapter-recipes.md:22-24`). [추론] src 런타임이 생긴 뒤 두 벌을 맞추는 담당이나 검사가 없어 갈라졌다 |
| 이해 비용 | 조합 작성자는 같은 이름 interface 두 개를 비교해야 한다. 런타임 port를 고치는 사람은 recipe 복사본의 존재를 모른다 |
| 최소 개선 방향 | 런타임이 있는 port는 recipe 쪽 정의를 지우고 src port를 re-export한다. recipe fake(`MemoryDurableObjectStore` 등)는 src port를 구현하게 고치거나, catalog의 `fake` 칸에서 뺀다 |
| 대안 비교 | (a) 현상 유지: 변경 누락이 계속된다. (b) 이름만 바꿔 recipe 쪽을 `*Sketch`로 표시: 싸지만 중복 유지비는 남는다. (c) src port로 통합: 한 벌만 남는다. recipe fake를 고치는 비용이 든다. (d) 두 벌을 비교하는 타입 테스트: 차이를 잡지만 두 벌을 유지한다. (c)를 권한다 |
| 단순화의 보존 조건 | recipe 계약이 보장하던 "File·IDBDatabase 같은 브라우저 객체를 노출하지 않는다"는 src port도 지킨다(확인함: `indexeddb-port.ts:178-181`). recipe 계약 테스트(`tests/recipes/browser-file-storage-contracts.test.ts`)는 src port 기준으로 옮긴다 |
| 비용·부작용 | recipe 파일 수정과 테스트 이동. 제품 repo가 recipe 계약을 import했다면 깨진다(두 제품 모두 확인 안 함) |
| 재검토 조건 | recipe가 런타임 없는 순수 설계로만 남는다면 이름을 구분하는 (b)로 충분하다 |
| 완료 기준 | `recipes/`와 `src/application/ports/`에 같은 이름의 서로 다른 interface가 없다. catalog `fake` 칸의 클래스가 src port를 `implements`한다 |
| 검증 방법 | `check:types:recipes`, 이름 충돌을 찾는 `grep`, recipe 계약 테스트 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 05-04 offline-indexeddb 레시피 예산 여유 9바이트: 이 영역의 다음 수정이 게이트에 막힌다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 (측정·변이로 확인) |
| 관련 관점 | 3, 21, 14 |
| 근거 | ① 측정: `offline-indexeddb:36891/36900`, `realtime:40886/40900`, `file-transfer:55623/55700`(`node scripts/check-optional-recipes.ts`).<br>② 변이: reconcile에 관측 이벤트 7줄 추가 → `REFERENCE_RUNTIME_BUNDLE_BUDGET_EXCEEDED: offline-indexeddb (36909 > 36900)`.<br>③ 예산 이력은 측정값을 따라 올리기만 했다: 8000 → 36000(`6c52cdb9`) → 36900(`6fe4aa9e`). 예산 근거 문서는 "측정값을 100바이트 단위로 올림"뿐이다(FOLLOW-UP 1절).<br>④ 레시피 측정은 `sourceRoots` 전체와 그 import를 묶는다(`scripts/lib/optional-recipe-bundle.ts:65-100`). kernel(`platform/`, `result.ts`)도 들어간다 |
| 발생 조건 | 이 영역이나 kernel에 코드를 조금이라도 더할 때. 05-01·05-02를 고칠 때도 해당한다 |
| 영향 | 결함 수정이 "예산 인상" 커밋을 함께 요구한다. 예산이 목표가 아니라 직전 측정값이라 커진 이유를 묻는 신호가 되지 못한다. kernel 한 줄이 레시피 예산 여러 개를 함께 움직인다. `result.ts`에 `case` 한 줄을 더하는 변이가 예산 3개를 함께 바꿨다(4.3절) |
| 심각도·우선순위 | Low · P2. 사용자 피해는 없다. 다음 수정 작업을 막는다 |
| 통제·증거 | M3(게이트는 동작) · E3(측정·변이) |
| 확실성과 남은 가정 | 측정은 이 호스트의 Vite·esbuild 버전 기준이다. 번들 예산 정책 자체는 영역 13 소관이라 겹칠 수 있다 |
| 결정의 근거 | 적용 제외 — 예산 수치를 어떻게 정할지는 영역 13·FOLLOW-UP의 결정이다. 여기서는 이 영역의 변경 비용만 기록한다 |
| 이해 비용 | 수정자는 레시피 측정 방식과 kernel 포함 여부를 알아야 실패 원인을 이해한다 |
| 최소 개선 방향 | 05-01·05-02 수정과 같은 커밋에서 예산을 정하되, 목표치와 근거(예: "OPFS·IDB 런타임 전체 gzip 40KB 이하")를 catalog 옆에 적는다 |
| 대안 비교 | (a) 수정마다 100바이트 인상(현상): 게이트가 증가를 막지 못한다. (b) 목표치로 한 번 정함: 근거 문서가 필요하다. (c) 레시피 예산에서 kernel을 뺌: kernel 증가를 놓친다 |
| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다 |
| 비용·부작용 | 문서 한 줄과 수치 결정 |
| 재검토 조건 | 레시피가 실제로 조합되어 초기 번들에 들어갈 때 |
| 완료 기준 | 예산에 근거가 적혀 있고, 05-01·05-02 수정 뒤에도 게이트가 통과한다 |
| 검증 방법 | `node scripts/check-optional-recipes.ts` |
| 담당·기한·상태 | 미정 · 미정 · FOLLOW-UP P2 이월 |
### 05-05 IndexedDB 전체 삭제 경로의 적용 범위가 port·runbook 설명과 다르다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (문서·코드 불일치 + 범위 공백, 재현) |
| 관련 관점 | 11, 15, 17, 24 |
| 근거 | ① 코드: `RETENTION_SWEEP`이 아닌 모든 action이 `deleteUnadmittedDataset`을 거친다(`indexeddb-runtime.ts:2554-2558`). SESSION_END도 포함된다.<br>② 삭제 조건은 open 실패 코드가 `POLICY_REJECTED`·`CORRUPT_DATA`일 때뿐이다(`:2580-2587`).<br>③ 설명: port는 "authorized LOGOUT or ACCOUNT_DELETION"만 적는다(`indexeddb-port.ts:154-160`). 코드 주석(`:2566-2573`)과 runbook(`browser-file-storage-recovery.md:278-281`)도 같다.<br>④ 재현 I2: SESSION retention dataset, budget 손상 → `SESSION_END` = `datasetDeleted: true`.<br>⑤ 재현 I1: v1 DB에 개인 행, v2 runtime의 migration 실패 → `ACCOUNT_DELETION` = `MIGRATION_FAILED/READ_ONLY`, `deleteDatabase` 호출 0회, 행 남음.<br>⑥ 코드: 롤백 배포로 모든 탭이 이전 bundle이면 open이 `UNSUPPORTED`(`:662-675`)라 purge가 같은 답으로 끝난다 |
| 발생 조건 | I2는 SESSION dataset의 governance 손상. I1은 기기에서 migration이 실패하거나, 새 release가 DB를 올린 뒤 이전 release로 롤백했을 때의 계정 삭제 |
| 영향 | SESSION_END 쪽은 동작이 오히려 안전하다. 설명만 틀렸다. 롤백·migration 실패 쪽은 계정 삭제 뒤 개인 데이터가 다음 배포까지 남는다. `deleteDatabase`는 버전과 무관하게 지울 수 있으므로 구 bundle에서도 막을 이유가 기술적으로는 없다 |
| 심각도·우선순위 | Low · P3. 롤백과 migration 실패는 드물고, 그 자체가 사고 절차를 탄다 |
| 통제·증거 | M1(설명이 코드와 다름) · E2(I1·I2) |
| 확실성과 남은 가정 | 두 코드를 뺀 의도는 기록에 없다. `EXPORT_THEN_PURGE` dataset에서 export 실패 데이터를 지우는 판단은 authority 몫이라고 본다 |
| 결정의 근거 | 4.2절 |
| 이해 비용 | runbook을 보는 운영자는 롤백 중 계정 삭제가 왜 `UNSUPPORTED`로 끝나는지 찾을 곳이 없다 |
| 최소 개선 방향 | 적용 action을 정한다(SESSION_END 포함 여부). 승인된 LOGOUT·ACCOUNT_DELETION에서 `MIGRATION_FAILED`·`UNSUPPORTED`도 삭제할지 정한다. 결정에 맞게 코드 조건, port 주석, runbook 조건을 한 번에 고친다 |
| 대안 비교 | 4.2절 (a)~(d) |
| 단순화의 보존 조건 | 승인 없이는 지우지 않는다. 다른 partition을 건드리지 않는다. 정상 governance에서는 행 단위 purge만 한다(현 테스트 `indexeddb-runtime.test.ts:1580-1613`) |
| 비용·부작용 | 범위를 넓히면 롤백 중 export 못 한 데이터가 지워질 수 있다. authority 구현 지침에 적어야 한다 |
| 재검토 조건 | 릴리스 롤백 절차가 정해질 때 |
| 완료 기준 | port 주석·runbook·코드의 적용 action과 open 실패 코드 목록이 같다. I1·I2가 결정한 결과를 내는 테스트가 있다 |
| 검증 방법 | I1·I2를 단위 테스트로 옮긴다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 05-06 한 레시피의 두 런타임이 삭제 승인 계약을 다르게 요구한다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 22, 23, 15 |
| 근거 | ① IndexedDB: 콜백 하나(`authorizeLifecycle`)가 `{authorized, proofToken}`을 돌려준다. 런타임은 형식(`/^[A-Za-z0-9_-]{16,128}$/`)만 보고 버린다(`indexeddb-runtime.ts:97`, `:2046-2077`). port 주석은 "short-lived"라고 하지만 만료 시각이 없다(`indexeddb-port.ts:170-176`).<br>② OPFS: 콜백 둘(`requestMaintenanceAuthority`, `consumeMaintenanceAuthority`)이 필요하다. proof 형식은 `{16,512}`이고 `expiresAtEpochMs`가 5분 이하여야 하며, consume으로 재사용을 막는다(`opfs-byte-store-adapter.ts:886-995`, `:1785-1786`).<br>③ 타입 위치도 다르다. IDB는 port(`indexeddb-port.ts:163-176`), OPFS는 adapter(`opfs-byte-store-adapter.ts:49-84`)에 있다 |
| 발생 조건 | 같은 LOGOUT 이벤트에서 두 런타임을 함께 조합할 때 |
| 영향 | 조합 작성자는 같은 승인을 두 방식으로 구현한다. IDB의 "short-lived"는 런타임이 확인할 수 없는 약속이다. 두 런타임 모두 proof를 스스로 요청하고 바로 버리므로, 형식 검사가 보안에 더하는 것은 없다(추론) |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M1 · E1 |
| 확실성과 남은 가정 | 두 계약을 다르게 둔 이유는 기록에서 찾지 못했다. OPFS의 consume은 "composition consumer owns atomic replay prevention across runtimes"(`adapter:983-984`)라고만 적혀 있다 |
| 결정의 근거 | [사실] 위 근거. [추론] OPFS 쪽이 나중에 더 엄격하게 설계됐고 IDB 쪽은 따라가지 않았다 |
| 이해 비용 | 승인 경로 둘, 정규식 둘, 타입 위치 둘을 따로 읽어야 한다 |
| 최소 개선 방향 | 하나의 승인 계약을 port(`shared.ts`)에 두고 두 런타임이 같이 쓴다 |
| 대안 비교 | (a) 현상 유지: 차이를 문서화만 한다. (b) IDB를 OPFS 방식(request+consume+만료)으로 올린다: 조합 비용이 늘지만 약속과 검사가 일치한다. (c) 둘 다 boolean 승인으로 줄인다: proof 형식 검사가 주던 것이 없다면 가장 단순하다. 다만 서버가 발급한 일회용 proof를 composition이 검증하는 설계라면 proof 전달이 필요하다. 그 요구가 확인되지 않아 (b)와 (c) 중 결정은 조건부다 |
| 단순화의 보존 조건 | 삭제마다 composition 승인을 거친다. proof를 호출자·로그·관측에 노출하지 않는다. 승인 실패는 삭제 0건이다 |
| 비용·부작용 | port 계약 변경이다. 조합한 다운스트림은 승인 콜백을 고쳐야 한다(현재 조합 0건) |
| 재검토 조건 | 서버 발급 proof를 실제로 쓰는 조합이 생길 때 |
| 완료 기준 | 두 런타임이 같은 승인 타입과 같은 proof 검사를 쓴다 |
| 검증 방법 | 두 런타임의 승인 거절 테스트가 같은 입력에서 같은 결과를 낸다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 05-07 kernel로 올릴 canonical JSON이 3벌로 갈라져 있다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 22, 9, 23 |
| 근거 | ① `opfs-prepared-object.ts:138-163` `stableJson` — 비유한 수·`undefined`를 throw한다(05-10에서 일부러 그렇게 바꿨다. 주석: "two different values never compare equal").<br>② `cache-storage/public-cache-codec.ts:632-652` `stableJson` — 같은 구조지만 `NaN`을 `"null"`로 쓴다.<br>③ `realtime/event-codec.ts:414-438` `canonicalJson` — 같은 구조, `NaN` → `"null"`. 이 값은 이벤트 fingerprint 해시에 들어간다(`:216`).<br>④ OPFS 폴더 안 `sameScope`도 두 벌이다(`indexeddb-opfs-journal.ts:1303-1313`, `opfs-worker-runtime.ts:1657-1667`). 내용은 같다 |
| 발생 조건 | canonical JSON 규칙을 한 곳에서 고칠 때 |
| 영향 | 지금은 ②·③의 입력이 `JSON.parse` 결과라 `NaN`이 올 수 없다. 도달하는 결함은 없다. 하지만 05-10이 OPFS에서 고친 판단이 다른 두 벌에는 없다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | 적용 제외(규칙 없음) · E1 |
| 확실성과 남은 가정 | 코드로 확인했다. ②는 영역 02, ③은 영역 04 코드다 |
| 결정의 근거 | [기록] kernel에는 이미 공유 파서가 있다(`platform/json-member-scanner.ts`, Q-6.4-8). [추론] canonical 직렬화도 같은 성격의 메커니즘이다 |
| 이해 비용 | 세 곳 중 하나만 고치면 fingerprint나 비교 결과가 영역마다 달라진다 |
| 최소 개선 방향 | ①을 `src/adapters/platform/`으로 옮기고 ②·③이 쓴다(폴더 단위 kernel이라 새 예외가 필요 없다). `sameScope`는 OPFS 폴더 안 한 파일로 합친다 |
| 대안 비교 | (a) 현상 유지: 차이가 커질 수 있다. (b) 통합: realtime fingerprint가 `NaN`에서 throw하게 된다. 입력이 JSON이라 실제 변화는 없다 |
| 단순화의 보존 조건 | realtime fingerprint 값이 지금과 같아야 한다(키 정렬·구분자 동일). OPFS는 비유한 수를 계속 거절한다 |
| 비용·부작용 | 작다. 레시피 예산 3개가 조금 움직인다(05-04) |
| 재검토 조건 | 비교 대상에 JSON 밖 값(Date, BigInt)이 들어올 때 |
| 완료 기준 | `src/adapters`에 canonical JSON 구현이 하나다 |
| 검증 방법 | 기존 fingerprint·manifest 비교 테스트 통과 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 05-08 kernel 범위 설명이 실제보다 좁고 편입 기준이 한 파일에만 있다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (문서 불일치) |
| 관련 관점 | 22, 9, 2 |
| 근거 | ① `docs/architecture/layers.md:42-45`와 `.dependency-cruiser.json:242` 주석은 `platform/**`을 "clock, abort primitive, capacity guard", `result.ts`를 "browser-data result helpers"라고 적는다.<br>② 실제 `platform/`에는 IndexedDB connection·transaction 상태 기계, Retry-After 파서, JSON 멤버 스캐너, lifecycle 런타임, mutation intent factory가 있다. `result.ts`에는 예외→실패 표 두 개가 있다(`result.ts:43-96`, `:110-171`).<br>③ "kernel이 가지면 안 되는 것" 목록은 `indexeddb-connection.ts:19-24`에만 있다. `.dependency-cruiser.json:242`는 "a new shared primitive goes into src/adapters/platform/"라고만 한다 |
| 발생 조건 | 새 공유 코드를 kernel에 넣을지 판단할 때 |
| 영향 | 문서만 읽으면 kernel이 세 가지 작은 도구라고 오해한다. 무엇을 넣으면 안 되는지는 한 파일을 열어야 안다. 지금까지는 그 파일의 기준이 지켜졌다(4.3절) |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M1(문서가 틀림) · E1 |
| 확실성과 남은 가정 | 문서와 파일 목록을 대조했다 |
| 결정의 근거 | 적용 제외 — 문서를 사실에 맞추는 단순 수정이다 |
| 이해 비용 | kernel 파일 10개와 `result.ts`를 모두 열어야 범위를 안다 |
| 최소 개선 방향 | `layers.md` kernel 절에 실제 파일 목록 대신 **편입 기준**을 적는다: 둘 이상의 그룹이 쓰는 메커니즘, 이름·스키마·실패 코드·관측 형태 같은 정책은 호출자가 소유. 규칙 주석은 그 절을 가리킨다 |
| 대안 비교 | 적용 제외 — 선택을 바꾸지 않는다 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 문서 두 곳 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 문서의 kernel 설명이 현재 파일과 맞고, 편입 기준이 문서에 있다 |
| 검증 방법 | 수동 대조. `verify:documentation` 범위 밖이다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 05-09 `putIdleTimeoutMs < mutationLockWaitTimeoutMs`가 주석에만 있다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 19, 12 |
| 근거 | ① 주석: "Keep it below `mutationLockWaitTimeoutMs` so a queued writer outlasts it"(`opfs-policy.ts:23-29`).<br>② 검사는 각 값의 범위(1초~60분)만 본다(`opfs-policy.ts:102-107`).<br>③ 실행: `resolveOpfsRuntimePolicy({putIdleTimeoutMs: 3_600_000, mutationLockWaitTimeoutMs: 1_000})`가 거절 없이 받아들여졌다 |
| 발생 조건 | 다운스트림이 두 값 중 하나만 조정할 때 |
| 영향 | source가 멈춘 put이 lock을 풀기 전에 다른 탭의 모든 쓰기·GC가 `BLOCKED`로 먼저 실패한다. 05-07 수정의 효과가 사라진다 |
| 심각도·우선순위 | Low · P3. 기본값(2분 < 10분)에서는 생기지 않는다 |
| 통제·증거 | M1 · E1 + 실행 |
| 확실성과 남은 가정 | 정책 검사 코드와 실행으로 확인했다 |
| 결정의 근거 | 적용 제외 — 주석에 적힌 규칙을 검사로 옮기는 단순 수정이다 |
| 이해 비용 | 설정 작성자가 두 값의 관계를 주석에서만 알 수 있다 |
| 최소 개선 방향 | `assertOpfsRuntimePolicy`에 `putIdleTimeoutMs < mutationLockWaitTimeoutMs`를 추가한다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 한 줄 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 위 조합이 정책 생성에서 거절된다 |
| 검증 방법 | 정책 단위 테스트 1개 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 05-10 OPFS journal DB 이름 접두사를 설정으로 바꿀 수 없어 제품이 소스를 고친다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 (제품 repo 증거) |
| 관련 관점 | 19, 3 |
| 근거 | ① OPFS root·lock 이름은 정책으로 바꿀 수 있다(`opfs-policy.ts:59-60`, `resolveOpfsRuntimePolicy`). journal DB 이름은 `ca-frontend-opfs-metadata-v1:` 접두사가 고정이고, `databaseName`을 넘겨도 기대값과 같아야 한다(`indexeddb-opfs-journal.ts:125-132`, `:156-163`). IndexedDB dataset 이름도 `ca-idb-v1:` 고정이다(`indexeddb-governance.ts:83`).<br>② `memento-frontend`(`chore/template-sync-v0.2.0`)는 `opfs-policy.ts` 기본값 두 개와 journal 접두사를 소스에서 `memento-...`으로 고쳐 들고 다닌다(`git diff af3d8e6 chore/template-sync-v0.2.0 -- src/adapters/storage/opfs/`, 2파일 3줄). `ca-idb-v1`은 그대로 뒀다 |
| 발생 조건 | 제품이 물리 이름에서 템플릿 이름을 빼고 싶을 때 |
| 영향 | 제품이 adapter 소스를 고치므로 템플릿 동기화 때 같은 줄이 바뀌면 충돌한다. 이번 동기화에서는 충돌하지 않았다. 배포 뒤 이름을 바꾸면 기존 데이터가 고아가 된다(제품 책임) |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M1 · E1(제품 diff) |
| 확실성과 남은 가정 | 제품이 이름을 바꾼 이유는 전체 rename 커밋(`c7caeef`)뿐이다. 조합하지 않은 코드라 정책 주입 대신 기본값을 고친 것으로 보인다(추론) |
| 결정의 근거 | [추론] 물리 이름을 템플릿 브랜드로 고정한 것은 의도라기보다 초기값이다. 기록은 찾지 못했다 |
| 이해 비용 | 제품 담당자는 이름 세 개가 어디서 오는지 파일 세 곳을 봐야 한다 |
| 최소 개선 방향 | 물리 이름 접두사 하나를 정책 값으로 받아 root·lock·journal·IDB 이름을 모두 거기서 만든다. 또는 "이름을 바꾸지 말라, 배포 뒤 바꾸면 데이터가 고아가 된다"를 README 업데이트 절에 적는다 |
| 대안 비교 | (a) 현상 유지 + 문서: 가장 싸다. (b) 접두사 정책화: 제품이 소스를 고칠 이유가 없어진다. 대신 정책 값이 release 사이에 바뀌면 안 된다는 조건이 새로 생긴다 |
| 단순화의 보존 조건 | 이름은 opaque 토큰만으로 만든다는 규칙(`governance:71-83`)을 유지한다 |
| 비용·부작용 | (b)는 기본값을 바꾸지 않으면 기존 데이터에 영향이 없다 |
| 재검토 조건 | 제품이 실제로 런타임을 조합할 때 |
| 완료 기준 | 제품이 adapter 소스를 고치지 않고 이름을 정할 수 있거나, 바꾸지 말라는 안내가 있다 |
| 검증 방법 | 다음 템플릿 동기화 기록에서 이 파일들의 제품 diff 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
## 6. FOLLOW-UP과 지난 발견 재확인
### 6.1 FOLLOW-UP (2026-09-28) 중 이 영역 항목
| FOLLOW-UP 항목 | 결과 | 근거 |
|---|---|---|
| 1절 P2 레시피 번들 예산: offline-indexeddb 36,891/36,900 | **유효** | 현재 측정값이 같다. 7줄 변이로 게이트가 실패한다 → 05-04 |
| 4절 P3 05-10: 넓힌 id 정책은 생성 시점에 못 막고 BEGIN_PUT에서 `INVALID_INPUT` | **유효** (의도된 설계) | 표본 검사(`opfs-policy.ts:130-160`)와 쓰기 때 문법 재검사(`:163-172`, `worker:332`). 동작은 FOLLOW-UP 설명과 같다 |
| 4절 P3 05-03 테스트: 손상된 budget 행만 테스트, binding 행은 없음 | **유효** | `tests/unit/indexeddb-runtime.test.ts:1485-1542`, Playwright `indexeddb-runtime.spec.ts:1081`은 budget만 손상시킨다. 동작 자체는 I4로 확인했다: binding 손상도 `POLICY_REJECTED` → `datasetDeleted: true` |
### 6.2 지난 발견 05-01~05-14 (회귀 확인)
| ID | 결과 | 근거 |
|---|---|---|
| 05-01 | 해소 | X1a·X1b·X1c, M1, Playwright chromium·firefox |
| 05-02 | 해소 | M2·M3. 손상 receipt(비어 있지 않음)는 범위 밖 → 새 05-01 |
| 05-03 | 해소 | M5, I4, Playwright. 적용 범위 문제 → 새 05-05 |
| 05-04 | 해소 | M4. 완료 신호 문제 → 새 05-02 |
| 05-05 | 해소 | 테스트 `indexeddb-runtime.test.ts:1616-1678`, prune 실패 코드 `CORRUPT_DATA`(`indexeddb-maintenance.ts:149-155`) |
| 05-06 | 해소 | M6, Playwright. journal도 `UNSUPPORTED`(`indexeddb-opfs-journal.ts:1691-1702`) |
| 05-07 | 해소 | 테스트 `opfs-worker-runtime.test.ts:2402-2446`. 설정 관계 검사 누락 → 새 05-09 |
| 05-08 | 해소 | fake 헤더(`memory-indexeddb.ts:849-876`), `memory-indexeddb-fidelity.test.ts` |
| 05-09 | 해소 | `EFFECT_UNKNOWN`이 storage 코드·runbook에 없다(`grep`). runbook 7절이 삭제·rollback만 적는다 |
| 05-10 | 해소 | 위 6.1 |
| 05-11 | 해소 | `storage/opfs` → `storage/indexeddb` import 0건. IndexedDB 표 1벌(`result.ts:110-171`) |
| 05-12 | 해소 | kernel 밖 `oncomplete` 0건(`grep`), `governance:229-271`이 kernel 트랜잭션을 쓴다 |
| 05-13 | 해소 | M7 |
| 05-14 | 해소 | port 주석(`opfs-ports.ts:87-95`) |
## 7. 미검증 목록
| 항목 | 이유 | 확인에 필요한 것 |
|---|---|---|
| WebKit에서 05-01·05-03·05-06 spec | 이번에는 chromium·firefox만 돌렸다 | `playwright.capabilities.config.ts`의 webkit project 실행 |
| X2(purge vs 같은 객체 덮어쓰기)·X3(손상 object row)의 실제 브라우저 재현 | 메모리 FS·IndexedDB와 Node Web Locks로만 재현했다 | Playwright OPFS spec에 두 탭 시나리오 추가 |
| v0.1.0 탭과 v0.2.0 탭 공존 | v0.1.0 put은 transaction lock을 잡지 않으므로 v0.2.0 reconcile이 그 row를 정리할 수 있다(코드 판단). 두 release를 동시에 띄우는 환경이 없었다 | 두 빌드를 다른 탭에 띄우는 e2e |
| release마다 `mutationLockName`이 다른 경우 | 설정값 조합이라 재현하지 않았다 | 정책만 다른 두 런타임을 한 root에서 돌리는 단위 테스트 |
| 실제 quota 초과, 실제 저장소 손상 | 브라우저 quota를 제어할 환경이 없다 | quota를 줄인 프로필 또는 대용량 채우기 |
| 2 GiB 객체 검증이 60초 RPC 안에 끝나는지 | 성능 측정 환경이 없다 | 저사양 기기 측정 |
| IndexedDB만 제거하는 드릴 | 드릴은 번들 전체만 지운다(`storage/index.ts:1-10`이 명시) | 드릴 변형 |
| 제거 드릴 1회차 실패의 원인 | 2회차 통과로 타이밍으로 판단했다. 같은 테스트의 기본 1초 대기는 영역 10·11 소관이다 | 부하를 준 상태에서 `tests/component/router.test.tsx` 반복 실행 |
| 제품 repo가 recipe 계약(05-03)을 import하는지 | 이번에는 조합 여부만 확인했다 | 두 제품의 `recipes/` import 검색 |
@@ -0,0 +1,358 @@
# 06 Service Worker / Web Push 성숙도 리뷰
> 검토일: 2026-09-29 · 기준: `main` / `af3d8e6` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 깊게 본 관점: 7, 12, 15, 18, 19, 28
## 0. 머리말 (36.1)
| 항목 | 기록 |
| --- | --- |
| 영역 | Service Worker(이하 SW) 정적 자산 캐시·활성화·제거, Web Push 구독·수신·클릭, SW 빌드 |
| 경로 | `src/adapters/service-worker/`(7파일), `src/adapters/web-push/`(12파일), `vite.service-worker.config.ts`, `scripts/lib/service-worker-build-input.ts`, `scripts/generate-service-worker-assets.ts`, `scripts/lib/self-unregistering-service-worker.ts`, `tsconfig.service-worker.json` |
| 기준 커밋·작업 상태 | `af3d8e6`. 워킹트리 변경은 리뷰 가이드 문서 2개뿐이고 코드는 `af3d8e6`과 같다 |
| 전제 (0.1) | 템플릿. SW 기본값은 `null`(`src/features/installed-runtime-capabilities.ts:39`). Web Push는 빌드 단계에서 거절한다(`scripts/lib/service-worker-build-input.ts:162-166`). 브라우저 SPA + 정적 호스팅 + SW. 여러 탭과 하위 경로 배포(`VITE_ROUTER_BASE_PATH`)는 지원 범위다(`vite.config.ts:26-33`) |
| 읽은 코드 | 범위 안 파일 전부. 연결 확인: `scripts/build-frontend.ts`, `scripts/generate-runtime-config.ts`, `scripts/generate-build-manifest.ts`, `scripts/check-release-admission.ts`, `src/contracts/deployment-admission.ts`, `scripts/verify-hosting-headers.ts`, `scripts/lib/hosting-probe.ts`, `config/hosting/cache-policy.json`, `src/contracts/service-worker.ts`, `src/contracts/web-push.ts`, `src/application/ports/out/web-push-control.ts`, `src/bootstrap/{register-service-worker,optional-runtime-host,create-runtime-composition}.ts`, `vite.config.ts`, `scripts/lib/optional-recipe-bundle.ts`, Vite 8.1.5의 `prepareOutDir`·`copyDir` |
| 읽은 테스트 | `tests/e2e/service-worker-update.spec.ts`, `tests/e2e/service-worker-recovery.spec.ts`, `tests/e2e/support/service-worker-builds.ts`, `tests/unit/web-push-subscription-adapter.test.ts`(06-02·06-06 절), `tests/unit/sub-path-deployment.test.ts` |
| 읽은 문서(주장) | `CHANGELOG.md:48-49`, `docs/architecture/optional-adapter-recipes.md` 3절, `config/recipes/frontend-capability-recipes.json`(`service-worker-pwa`), `docs/operations/release-cache-rollback.md` SW 절, `docs/operations/browser-file-storage-recovery.md` 8절, `docs/architecture/realtime-events-web-push-and-bounded-polling.md:1314-1370`, 설계 문서 `…closed-deep-design.md:327`, `:3398-3418`, `:3781-3850`, `:5897` |
| 소비자 증거 | `../memento-frontend` `chore/template-sync-v0.2.0`: 동기화 기록과 `git diff af3d8e6 chore/template-sync-v0.2.0`(SW 관련 4파일). `../tech-log-frontend` 같은 브랜치: SW `null` 유지 확인 |
| 실행한 테스트 | 분리 worktree에서 `node scripts/run-vitest.ts run` + 이 영역 단위 10파일 → **10 files, 153 passed** |
| 실행한 e2e | 분리 worktree, 별도 Playwright 설정(webServer 없음), `service-worker-update.spec.ts` + `service-worker-recovery.spec.ts` → chromium **6 passed**, webkit **6 passed**, firefox **3 passed / 3 skipped**(격리 표기된 Playwright Firefox 제약) |
| 변이 실험 | ① Web Lock 우회 → 06-02 테스트 3개 실패. ② kill switch 분기 무력화 + `revokeForeign`의 같은 세대 검사 제거 → 4개 실패. ③ 선택을 `ACTIVE`로 바꾼 트리에서 SW update spec → `beforeAll` 오류로 5개 모두 실패·미실행(06-04) |
| 빌드 실험 | ① SW `ACTIVE` + `APP_PROFILE=production` 빌드 → `dist/config.json`이 local 문서로 바뀜, release admission 거절(06-01). ② SW `ACTIVE` + `VITE_ROUTER_BASE_PATH=/app/` → manifest URL이 `/assets/…`(06-02). ③ `publicDir: false` 한 줄 추가 → 같은 production + `/app/` 빌드의 config가 맞고 admission 통과 |
| 브라우저 실험 | ④ `/app/` 빌드를 Chromium으로 열기: 그대로면 `/release-manifest.json` 404로 부팅 실패(06-01). config만 고치면 앱은 뜨고 워커 설치가 `/assets/…` 404로 실패(06-02). ⑤ 워커 등록 뒤 스크립트를 404로 바꾸고 `update()`와 새 navigation: Chromium·WebKit·Firefox 모두 등록과 active 워커 유지(06-06) |
| 확인하지 못한 범위 | `test:realtime-removal`(시작했으나 worktree의 링크된 `node_modules`에 pnpm이 설치를 시도해 안전을 위해 중단), 실제 CDN 캐시 동작, 실제 푸시 서비스·VAPID 흐름, 얼어 있는 탭의 Web Lock 보유, 여러 창 활성화(앱이 아닌 창) 실제 브라우저. 7절에 적었다 |
| 이전 리뷰와 비교 | 2026-09-25 06-01~06-10은 모두 닫혔다. 이번에 코드와 변이로 다시 본 것: 06-01(`service-worker-runtime.ts:283` `"data" in`, WebIDL 모양 fake `tests/unit/web-push-worker-runtime.test.ts:110-120`), 06-02·06-04·06-06(변이로 검출 확인), 06-03(e2e 3엔진 중 2엔진 통과), 06-07·06-08·06-09(코드 확인). 회귀는 없다 |
**영역 판정 (35.8)**
- 기본 구성(SW `null`, Web Push 미선택): 이 영역의 결함이 나타나지 않는다. 지정 범위에서 사용 가능.
- SW `ACTIVE`: **해당 용도의 사용 보류.** SW를 켜면 local이 아닌 모든 빌드의 런타임 설정이 local 문서로 바뀐다(06-01, High). 한 줄 수정이다. 하위 경로 배포에서는 워커가 설치되지 않는다(06-02).
- Web Push: **조건부 사용 가능.** 지난 라운드의 실제 브라우저 결함 2건(클릭 무시, 탭 경합)은 해소됐고 변이로 검출된다. 서버의 짧은 association TTL·send-time 인가와 `revokeForeign` 호출 규칙이 채택 조건이다.
## 1. 결론
- **06-01 (High):** SW 빌드는 Vite를 한 번 더 돈다. 이 두 번째 빌드가 `public/`을 다시 복사해서 프로필로 만든 `dist/config.json`을 `public/config.json`(local 프로필)으로 덮어쓴다. production 빌드가 `APP_ENV: local`, `AUTH_MODE: demo`, `API_BASE_URL: http://localhost:8080/`을 싣고 성공한다. release admission이 이를 거절해서 배포 피해는 막히지만, SW를 켠 제품은 릴리스를 만들 수 없다. 하위 경로 빌드는 부팅하지 못한다. memento는 이미 같은 결함을 만나 `publicDir: false`로 막았다.
- **06-02 (Medium):** SW 사전 캐시 목록은 router base path를 모른다. `/app/`에 배포하면 워커가 `/assets/…`를 받으려다 404로 설치를 포기한다.
- **06-03 (Medium):** 레시피 catalog는 "오프라인 셸 요구"를 SW 레시피의 설치 조건으로 적는다. 코드와 설계는 오프라인 셸을 금지하고, 제품이 켤 확장 지점도 없다. memento는 템플릿 파일 3개를 고쳤다.
- **06-04 (Medium):** SW e2e 도우미는 선택이 `null`인 줄을 찾아 바꾼다. SW를 켠 제품에서는 update·recovery spec이 준비 단계에서 모두 멈춘다.
- **06-05 (Medium):** 설계는 `service-worker.js`의 `Cache-Control: no-cache`를 호스팅 설정에 맡겼다. 호스팅 정책 파일과 live probe에는 그 항목이 없다.
- **06-06 (Low):** 제거 2·3단계는 `service-worker.js`를 내보내지 않는다. 부팅을 막는 워커는 1단계 기간에 오지 않은 사용자에게 남는다.
- 확인된 강점:
1. 설치 무결성: 개수·크기 상한, 상태·타입·바이트 수·sha256 검증, 전부 성공해야 캐시를 쓴다(`service-worker-static-assets.ts:119-208`, `:269-349`). `credentials: "omit"`, `redirect: "error"`로 받는다(`:280-285`).
2. 새 배포 뒤 옛 탭: 이전 릴리스 캐시에서 옛 청크를 준다. 이번에 chromium·webkit e2e로 다시 확인했다(`service-worker-update.spec.ts:222-264`).
3. 비상 해제: `REMOVE_REGISTRATION`이 자기 해제 워커를 내보낸다(`scripts/build-frontend.ts:72-77`). 페이지가 부팅하지 못하는 워커를 브라우저 update만으로 걷어낸다. chromium·webkit e2e 통과(`service-worker-recovery.spec.ts:75-151`).
4. 탭 경합: enable·reconcile·revoke를 origin 단위 Web Lock으로 직렬화한다(`push-subscription-adapter.ts:467-506`). 우회 변이를 넣으면 테스트 3개가 실패한다.
5. 다중 방어: 06-01이 만든 잘못된 설정을 release admission(`src/contracts/deployment-admission.ts:64-110`)이 거절했다. 설정 결함이 production으로 가는 경로를 다른 게이트가 막는 것을 실제로 확인했다.
## 2. 대표 흐름 (체크리스트 2절)
### 2.1 정상 흐름 — SW를 켠 앱의 첫 방문과 다음 방문 (루트 배포)
```text
사용자 첫 방문 /
→ [정책] resolveRuntimeCapabilities: serviceWorker ACTIVE
첫 React effect 뒤 optional.startAfterMount() (optional-runtime-host.ts:97-120)
→ [상태] container.register(/service-worker.js, {type: module, updateViaCache: none})
(service-worker-page-controller.ts:157-161)
→ [외부 I/O] 워커 install: manifest 자산 28개(이번 빌드)를 no-store·omit·redirect:error로 받음
→ 크기·타입·sha256 검증 → ca-static-v1-<digest16>에 저장 (service-worker-static-assets.ts:154-208)
→ [실패] 하나라도 틀리면 이번에 만든 후보 캐시만 지우고 install 거절
→ 페이지 start() = FAILED(INSTALL_FAILED) → telemetry service-worker.start.failed 1건
(optional-runtime-host.ts:105-120)
→ [결과] 성공이면 RELOAD_TO_ENABLE (clients.claim 없음, page-controller.ts:206-211)
다음 navigation부터 해시 GET만 cache-first, navigation·config·API는 가로채지 않음
(service-worker-static-assets.ts:45-59)
```
증거: e2e `installs the static asset set …` 2개(3엔진 통과), `serves A's removed chunk …`(chromium·webkit 통과).
### 2.2 피해가 큰 흐름 — SW를 켠 production 빌드 (06-01)
```text
APP_PROFILE=production VITE_BUILD_ID=rev node scripts/build-frontend.ts
→ [3] Vite 앱 빌드: public/ 복사 → dist/config.json = local 문서
→ [4] generate-runtime-config: dist/config.json = production 문서 (generate-runtime-config.ts:38-86)
→ [5] 자산 목록 생성 (config.json 제외)
→ [6] SW Vite 빌드: 설정 로드 시 dist/config.json(production) 읽고 APP_ENV 검사 통과
→ 출력 준비 단계에서 public/ 다시 복사 → dist/config.json = local 문서
(vite.service-worker.config.ts:51-55, :69-82;
vite node.js:32813-32815)
→ [7] generate-build-manifest: local 문서에 BUILD_ID·RELEASE_ID만 다시 찍어 저장 (:58-60, :76-77, :123-127)
→ [결과] 빌드 성공. dist/config.json = APP_ENV local · AUTH_MODE demo · API http://localhost:8080/
→ [게이트] check:release-admission(RELEASE_TARGET=production) → 거절 4건
→ [게이트 없이 배포] demo 인증·loopback API 설정이 사용자에게 감
→ [하위 경로] RELEASE_MANIFEST_URL이 /release-manifest.json으로 되돌아가 부팅 실패
```
### 2.3 변경 흐름 — 제품이 오프라인 탐색 셸을 켠다 (06-03, 06-04)
```text
제품 요구: 오프라인에서도 앱 셸이 열려야 함
→ 레시피 catalog: service-worker-pwa trigger = "a measured offline-shell requirement"
(frontend-capability-recipes.json:140)
→ 템플릿 정책: navigation → NETWORK_ONLY, index.html은 사전 캐시에서 제외, 해시 이름만
(static-assets.ts:47, generate-service-worker-assets.ts:33-39, :56)
→ 확장 지점: 없음. handler는 3종으로 닫혀 있고 엔트리는 runtime.intercepts 하나만 부름
(service-worker-entry.ts:94-111, service-worker-build-input.ts:148-161)
→ 실제 변경(memento): service-worker-lifecycle.ts +44줄(isShellNavigation, intercepts 첫 줄),
generate-service-worker-assets.ts(index.html·사진 11개 포함), vite.service-worker.config.ts
→ 검증: 템플릿 SW e2e 도우미가 null 선택 줄을 못 찾아 멈춤, 사전 캐시 기대값도 다름 (06-04)
→ 결과: 템플릿 동기화마다 같은 파일에서 충돌. "HTML과 자산은 같은 릴리스" 보호 조건의 재증명이 제품 몫
```
제거 흐름(`ACTIVE → REMOVE_REGISTRATION → PURGE_OWNED_RESOURCES → null`)은 06-06에서 다룬다.
## 3. 28개 관점 판정표 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가
| 번호 | 관점 | 판정 | 목표·확인 통제 | 증거 | 이유·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | P | M2 / M2 | E1·E2 | 런타임 검증은 exact하다. 빌드 설정이 앱 산출물을 바꾸고(06-01), 사전 캐시 URL이 base를 잃는다(06-02) |
| 2 | 구조적 성숙도 | O | M3 / M3 | E1 | worker realm과 page realm을 tsconfig로 나눈다(`tsconfig.service-worker.json:8-17`). 엔트리는 web-push를 import하지 않는다(`service-worker-entry.ts:144-158`). 전체 의존성 게이트는 영역 12 |
| 3 | 변경 용이성 | P | M1 / M1 | E1 | 오프라인 셸·WEB_PUSH 조립 모두 템플릿 파일 수정이 필요하다(06-03, `service-worker-entry.ts:144-158`) |
| 4 | 인지 부하 | P | - | E1 | 계약 주석은 충실하다. page controller 642줄, lifecycle 736줄, push adapter 1203줄. 오프라인 셸 주장이 catalog·레시피·설계 3곳에서 다르다(06-03) |
| 5 | 위험 가시성 | P | M1 / M1 | E1 | `build-frontend.ts:31-37`은 3단계의 `public/` 복사만 설명하고 6단계의 같은 복사는 적지 않는다(06-01) |
| 6 | 실패 성숙도 | P | M2 / M2 | E1·E2 | install 실패 11종, drain 시간 초과와 명시 거절을 구분한다(06-07 해소). 워커의 거절 코드는 페이지에 오지 않아 `INSTALL_FAILED`만 남는다(06-02 조사 중 확인) |
| 7 | 운영 성숙도 **(깊게)** | P | M2 / M2(시작 실패만) | E1·E2 | 시작 실패는 `service-worker.start.failed`로 남는다(`optional-runtime-host.ts:105-120`, `tests/component/runtime-composition-service-worker-telemetry.test.ts`). 업데이트 설치 실패, `observe`, `health()`는 연결되지 않았다(FOLLOW-UP 06-05 유효: `src`에서 `.health()` 호출 0건, composition이 `observe`·`blockers`를 넘기지 않음). 06-02의 설치 실패는 이 이벤트로만 보이고 원인은 워커 안에 남는다 |
| 8 | 디버깅 가능성 | P | M2 / M1 | E1 | `observe` hook과 reason 코드는 있으나 조립되지 않는다(7번과 같은 원인) |
| 9 | 유지보수 성숙도 | P | M1 / M1 | E1 | `void SERVICE_WORKER_BOUNDS.retainedPreviousCaches`(`service-worker-lifecycle.ts:169`)는 여전히 아무 일도 하지 않는다. 운영 문서는 코드 경로를 가리키도록 고쳐졌다 |
| 10 | 테스트 성숙도 | P | M3 / M3(기본 구성) | E2·E3 | 단위 153 통과, 변이 3종 모두 검출, SW e2e 3엔진 확인. SW를 켠 비 local 빌드(06-01)·하위 경로(06-02) 테스트가 없고, SW를 켠 트리에서는 e2e가 멈춘다(06-04) |
| 11 | 데이터 성숙도 | O | M2 / M2 | E1 | 캐시는 `credentials: "omit"`으로 받은 해시 공개 자산만 담는다. 소유 캐시 이름은 exact 비교(`src/contracts/service-worker.ts` `isOwnedStaticCacheName`). push fence에 계정 ID와 endpoint가 없다 |
| 12 | 동시성 성숙도 **(깊게)** | P | M3 / M3 | E2 | 탭 사이 enable·reconcile·revoke는 Web Lock으로 직렬화되고 변이로 검출된다(`push-subscription-adapter.ts:494-499`, 테스트 `:976-1172`). SW 활성화는 single-flight·nonce·source 동일성 검사. 남은 것: 응답하지 않는 창 하나가 활성화를 막는다(`service-worker-lifecycle.ts:344-347` `includeUncontrolled: true`, 안전한 쪽 실패). `revokeForeign`은 호출자가 최신 세션 authority를 넘긴다는 규칙에 기댄다(`web-push-control.ts:29-38`, M1). lock 대기 자체에는 상한이 없고 호출자 signal에 기댄다(추론, 4.3절) |
| 13 | 확장성 | P | M2 / M2 | E1 | 256개·5 MiB 상한을 빌드에서 막는다(`generate-service-worker-assets.ts:60-86`). 이번 production 빌드는 28개. 기능 증가에 따른 도달 시점은 미측정 |
| 14 | 성능 성숙도 | O | M2 / M2 | E1·E2 | fetch 리스너는 `PWA_STATIC_ASSETS`일 때만 등록되고 `/assets/` 아래 해시 GET만 가로챈다(06-08 해소, `service-worker-runtime.test.ts:1985-1996`). `assets/` 하드코딩은 FOLLOW-UP 06-08로 남음 |
| 15 | 보안 성숙도 **(깊게)** | P | M3 / M2~M3 | E1·E2·E3 | payload를 신뢰하지 않고, 클릭 URL은 same-origin만 연다. 클릭 facade는 WebIDL 모양으로 고쳐졌다(`web-push/service-worker-runtime.ts:283`). 06-01은 demo 인증 설정을 production 산출물에 넣지만 admission이 거절했다(실행 확인). `revokeForeign`은 증명 없이 fence를 넘기므로 오래된 세션 탭이 부르면 현재 계정 연결을 끊는다(문서화, 끊는 방향이라 노출은 없음) |
| 16 | 의존성 성숙도 | P | - | E3 | 런타임 외부 패키지는 없다. SW 빌드가 Vite 8.1.5에서 `inlineDynamicImports option is deprecated` 경고를 낸다(빌드 로그). "출력 1파일" 규칙(`…closed-deep-design.md:3400-3405`)을 확인하는 테스트는 파일 존재만 본다(`service-worker-update.spec.ts:266-271`) |
| 17 | API / Contract 성숙도 | P | M2 / M2 | E1 | SW 메시지 V1 exact, push 포트는 `revokeForeign` 추가만(파괴적 변경 없음). SW handler 계약에 오프라인 셸이 없는데 catalog는 이 용도를 약속한다(06-03) |
| 18 | 배포 성숙도 **(깊게)** | P | M3 / M2 | E3 | 옛 탭 청크 fallback과 업데이트 핸드셰이크는 e2e로 확인했다. SW를 켜면 릴리스 산출물의 설정이 틀리고(06-01), 워커 스크립트의 CDN 캐시 정책은 선언·검사되지 않는다(06-05) |
| 19 | 설정 성숙도 **(깊게)** | X | M3 / M1 | E3 | SW를 켜는 순간 프로필 설정·`RUNTIME_*` 주입·base path 재작성이 모두 local 문서로 되돌아간다(06-01). 06-10의 APP_ENV 검사(`service-worker-build-input.ts:179-183`)는 덮어쓰기 전 입력만 본다. 사전 캐시 URL과 SW의 runtime config URL 기본값이 base를 무시한다(06-02, `vite.service-worker.config.ts:94-96`) |
| 20 | 개발자 경험 | P | M1 / M1 | E1·E3 | SW 켜기 체크리스트가 있다(`optional-adapter-recipes.md:109-131`). 활성화 UI·observe는 `create-runtime-composition.ts`를 직접 고쳐야 한다. SW를 켜면 템플릿 e2e가 멈춘다(06-04) |
| 21 | Guardrail 성숙도 | P | M3 / M3(일부) | E2·E3 | build-input 거절, hosting 검사의 워커 파일 검사, release admission은 동작한다. SW 빌드가 dist를 바꾸지 않는지(06-01)와 워커 스크립트 헤더(06-05)는 검사하지 않는다 |
| 22 | 추상화 성숙도 | O | M2 / M2 | E1·E2 | 구조적 facade로 워커 없이 테스트한다. fake가 WebIDL 모양을 따르도록 고쳐져 06-01(2026-09-25) 같은 차이를 가리지 않는다(`web-push-worker-runtime.test.ts:110-120`) |
| 23 | 일관성 | P | - | E1 | 같은 repo의 두 번째 Vite 빌드(`scripts/lib/optional-recipe-bundle.ts:117`, `:127`)는 `publicDir: false`·`copyPublicDir: false`인데 SW 빌드만 없다(06-01). `validateActiveFence` 두 벌(`push-event-adapter.ts:196`, `notification-click-adapter.ts:353`)은 operation 이름만 다르고 갈라지지 않았다 |
| 24 | 네이밍 / 의미 | P | - | E1 | 06-07로 시간 초과가 `CLIENT_DRAIN_TIMEOUT`으로 분리됐다. `retainedPreviousCaches` 상수는 읽히지 않고 "이전 1개"는 코드에 고정돼 있다(9번과 같은 항목) |
| 25 | 조직 확장성 | - | - | - | 적용 제외: 1인 관리 전제(0.1). 구조적 준비는 다른 영역 |
| 26 | Ownership 성숙도 | P | M1 / M1 | E1 | 운영 문서가 코드 경로를 가리킨다(`release-cache-rollback.md:79-109`, `browser-file-storage-recovery.md` 8절). 제거 1단계의 유지 기간이 없다(06-06) |
| 27 | 삭제 가능성 | ? | M3 / 미확인 | E1 | 엔트리가 web-push를 import하지 않아 파일 삭제로 뺄 수 있다고 주장한다. `test:realtime-removal`은 이번에 끝까지 돌리지 못했다(7절) |
| 28 | 회복 가능성 **(깊게)** | P | M3 / M3(페이지·워커) | E2·E3 | 런타임 kill switch는 변이로 검출되고(06-04 해소), 부팅을 막는 워커는 자기 해제 워커로 걷어낸다(e2e chromium·webkit). 그 경로는 CDN이 `service-worker.js`를 캐시하지 않는다는 전제에 기대는데 검사가 없다(06-05). 제거 2·3단계에서 비상 경로가 사라진다(06-06, 404 등록 유지 3엔진 확인) |
집계: 적용 27개 중 O 5 · P 20 · X 1 · ? 1, 적용 제외 1.
## 4. 설계 선택 설명 (41절)
### 4.1 오프라인 셸 없이 해시 파일만 캐시한다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 새 배포 뒤 옛 탭이 청크를 잃지 않는 것, 캐시된 바이트가 빌드 산출물과 같은 것. 오프라인 셸은 catalog의 설치 조건에 있지만(`frontend-capability-recipes.json:140`) 설계는 비지원이다(`…closed-deep-design.md:327`) |
| 2. 지킬 성질 | HTML과 자산이 같은 릴리스에서 온다. 새 배포 뒤 HTML은 항상 새것이다. 인증 응답은 캐시하지 않는다(`:3842-3850`) |
| 3. 현재 보장 | navigation은 `NETWORK_ONLY`(`service-worker-static-assets.ts:47`), `index.html` 제외(`generate-service-worker-assets.ts:33-39`), install 시 sha256 검증. 오프라인 부팅은 보장하지 않는다 |
| 4. 대안 | (a) 현상 유지 (b) 비지원 유지 + catalog·레시피 정정 + 졸업 경로 문서 (c) 선택 handler `OFFLINE_NAVIGATION_SHELL`: navigation은 네트워크 먼저, 실패 시 **현재 릴리스 캐시의** `index.html` (d) 워커 런타임에 일반 interceptor 배열 |
| 5. 비교 | (a) 비용 0, 주장 모순과 제품의 템플릿 파일 수정이 남음. (b) 문서 수정만, 제품 수정 비용은 그대로지만 예측 가능. (c) 조합 1개 추가(30.2)·e2e 1개·설계 금지 목록 수정. 현재 릴리스 캐시의 HTML만 쓰면 "같은 릴리스" 성질을 지킨다. (d) 동기 `intercepts` 결정을 여러 hook이 나눠 가져 순서·충돌 규칙이 새로 생긴다. 가장 비쌈 |
| 6. 현재 조건의 선택 | 기본값(오프라인 셸 없음)은 유지가 타당하다. 소비자 2개 중 1개만 필요하다. 다만 (a)는 catalog 주장과 코드가 반대라 받아들일 수 없고 최소 (b)가 필요하다(06-03) |
| 7. 재검토 조건 | 두 번째 소비자가 오프라인 셸을 요구하거나, memento의 lifecycle 수정이 다음 동기화에서 다시 충돌하면 (c)를 비교한다 |
- 확인한 사실: 코드의 분류 규칙, memento diff(템플릿 파일 3개 수정).
- 기록된 의도: 설계 문서의 "baseline has no offline shell", "installability/offline document is a separate product capability".
- 리뷰어의 추론: (c)가 "같은 릴리스" 성질을 지킨다는 판단. memento 구현이 이 성질을 지키는지는 이 리뷰 범위 밖이다.
### 4.2 SW를 두 번째 Vite 빌드로 만든다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 워커가 앱 빌드의 해시 자산 목록을 컴파일 시점에 가진다(`scripts/build-frontend.ts:10-13`, 설계 "the worker never fetches one"). |
| 2. 지킬 성질 | 워커 출력은 `dist/service-worker.js` 하나다. 두 번째 빌드는 앱 산출물을 바꾸지 않는다(암묵적 성질, 어디에도 적혀 있지 않음) |
| 3. 현재 보장 | 입력 1개, `emptyOutDir: false`, `inlineDynamicImports`(`vite.service-worker.config.ts:69-82`). 앱 산출물 불변은 보장하지 않는다. `public/` 복사가 `dist/config.json`을 바꾼다(06-01) |
| 4. 대안 | (a) 현상 유지 + `publicDir: false` (b) 앱 빌드 plugin의 `closeBundle`에서 워커를 만든다 (c) Vite `build()`를 `configFile: false`로 호출(`optional-recipe-bundle.ts:112-130`과 같은 방식) (d) 워커가 런타임에 목록을 받는다 |
| 5. 비교 | (a) 한 줄, 단계가 나뉘어 실패 지점이 분명하고 e2e가 실제 스크립트를 탄다. (b) 빌드 1회로 줄지만 앱 빌드 설정에 워커 지식이 섞인다. (c) 기본값이 명시적이지만 스크립트 한 개 추가. (d) 설계가 금지한다(목록 위조·신선도 문제) |
| 6. 현재 조건의 선택 | two-pass 유지가 타당하다. 다만 성질 2를 설정(`publicDir: false`)과 테스트로 고정해야 한다 |
| 7. 재검토 조건 | Vite가 `inlineDynamicImports`를 없애거나(이미 경고), 워커가 여러 청크를 필요로 하면 (b)·(c)를 다시 비교한다 |
- 확인한 사실: Vite 8.1.5 `prepareOutDir`의 복사, 빌드 재현.
- 기록된 의도: `build-frontend.ts:31-37` 주석은 `public/` 복사를 알고 4단계를 3단계 뒤에 뒀다. 6단계의 복사는 기록에 없다.
- 리뷰어의 추론: 성질 2는 작성자가 전제했지만 적지 않은 규칙으로 본다.
### 4.3 탭 사이 Web Push 제어를 Web Lock으로 직렬화하고, 계정 전환은 증명 없는 `revokeForeign`으로 푼다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 여러 탭이 native 구독 1개와 origin fence 1개를 공유한다. 로그아웃 없이 계정이 바뀌면 새 세션은 이전 authority를 모른다 |
| 2. 지킬 성질 | `PUSH_READY`를 보고한 탭이 있으면 native 구독과 서버 연결이 살아 있다. 이전 계정의 push가 새 계정에 계속 표시되지 않는다(최종 방어는 서버 send-time 인가) |
| 3. 현재 보장 | `exclusive`가 `navigator.locks.request("web-push-control")` 안에서 mutation을 돌린다(`push-subscription-adapter.ts:467-506`). 우회 변이 → 3개 실패. `revokeForeign`은 같은 `fenceGeneration`이면 건드리지 않는다(`:410-447`). 검사 제거 변이 → 2개 실패. 보장하지 않는 것: lock 대기 자체의 상한(호출자 signal에 기댐), 오래된 세션 탭의 호출(포트 문서가 금지, `web-push-control.ts:29-38`) |
| 4. 대안 | (a) CAS 실패 뒤 fence를 다시 읽어 수렴 (b) Web Lock(현재) (c) BroadcastChannel 리더 선출 (d) 서버 상태만 신뢰 |
| 5. 비교 | (a) lock 없이 되지만 보상 분기마다 수렴 규칙이 필요하다. 지난 리뷰 재현 순서 2개를 각각 따로 막아야 한다. (b) 브라우저 기본 기능 하나로 두 순서가 사라진다. 없으면 `PUSH_UNSUPPORTED`로 닫는다. (c) 리더 교체 중 경합이 다시 생긴다. (d) native 구독이 브라우저에만 있어 불가능 |
| 6. 현재 조건의 선택 | (b)가 타당하다. `revokeForeign`의 무증명은 `fenceGeneration`이 순서 없는 문자열(`src/contracts/web-push.ts` `PushAuthoritySnapshot`)이라 순서 검사를 할 수 없는 현재 계약에서 가장 작은 수단이다. 잘못 부르면 연결을 끊는 쪽이라 노출은 없다 |
| 7. 재검토 조건 | 서버가 순서 있는 세대 값을 주면 `revokeForeign`에 "저장된 세대 < 다음 세대" 검사를 넣는다. lock 대기 중 멈춤이 관측되면 `exclusive`에 대기 상한을 둔다 |
- 확인한 사실: 변이 결과, 포트 문서.
- 기록된 의도: `realtime-events-web-push-and-bounded-polling.md:1319-1328`, `:1348-1366`.
- 리뷰어의 추론: 얼어 있는 탭이 lock을 쥔 채 멈출 수 있는지는 브라우저 정책에 달렸다. 재현하지 않았다.
## 5. 발견 사항 (36.3)
### 06-01 SW를 켜면 두 번째 Vite 빌드가 `public/`을 다시 복사해 프로필의 `dist/config.json`을 local 문서로 덮어씀
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 19, 18, 15, 10, 21, 23 |
| 근거 | `vite.service-worker.config.ts:69-82`에 `publicDir`·`build.copyPublicDir` 설정이 없다. Vite 8.1.5는 `emptyOutDir: false`여도 출력 준비 단계에서 `public/`을 `fs.copyFileSync`로 덮어쓴다(`node_modules/vite/dist/node/chunks/node.js:32813-32815`, `:2426-2434`). 6단계 SW 빌드는 설정 로드 때 `dist/config.json`(production)을 읽어 06-10 검사를 통과한 뒤(`:51-55`, `service-worker-build-input.ts:179-183`) 같은 파일을 `public/config.json`으로 덮는다. 7단계는 그 문서에 식별자만 다시 찍고 저장한다(`scripts/generate-build-manifest.ts:58-60`, `:76-77`, `:123-127`). **재현 1**(worktree, SW `ACTIVE`, `APP_PROFILE=production VITE_BUILD_ID=rev-prod-1`): 빌드 exit 0, 결과 `APP_ENV: local`, `AUTH_MODE: demo`, `API_BASE_URL: http://localhost:8080/`, `TELEMETRY_ENABLED: false`, 식별자만 `rev-prod-1`. `RELEASE_TARGET=production node scripts/check-release-admission.ts` → 거절 4건(APP_ENV, AUTH_MODE, API http, localhost). **재현 2**(`VITE_ROUTER_BASE_PATH=/app/`, local): `generate-runtime-config.ts:59-67`이 만든 `/app/release-manifest.json`이 `/release-manifest.json`으로 되돌아간다. Chromium에서 `/app/`을 열면 `404 /release-manifest.json` 뒤 "애플리케이션을 시작할 수 없습니다." **변이**: `publicDir: false` 한 줄을 넣으면 같은 production + `/app/` 빌드가 `APP_ENV: production`, `/app/release-manifest.json`을 유지하고 admission이 ADMITTED. 같은 repo의 다른 두 번째 빌드는 이미 끈다(`scripts/lib/optional-recipe-bundle.ts:117`, `:127`). 소비자: memento는 SW `ACTIVE`로 이 결함을 만나 `publicDir: false`를 유지했고 "latent template defect"로 기록했다(`docs/operations/template-sync-2026-09-29.md` Service Worker 절, follow-up 2) |
| 발생 조건 | SW `ACTIVE` + local이 아닌 프로필, 또는 `VITE_ROUTER_BASE_PATH`, 또는 `RUNTIME_API_BASE_URL`·`RUNTIME_TELEMETRY_ENDPOINT` 주입 |
| 영향 | development·staging·production 산출물이 모두 local 설정을 싣는다. admission이 돌면 배포가 거절되는데 메시지("artifact declares local")로는 SW와 연결하기 어렵다. admission 없이 배포하면(템플릿 CI는 아직 Gitea runner에서 돈 적이 없다, U-1) demo 인증·loopback API 설정이 사용자에게 간다. 하위 경로 배포는 프로필과 관계없이 부팅하지 못한다 |
| 심각도·우선순위 | High · P1. SW `ACTIVE`는 레시피가 안내하는 지원 옵션이다(`optional-adapter-recipes.md:112-113`). 켜는 순간 모든 비 local 릴리스가 불가능하거나 틀린다. 기본 구성(`null`)에는 영향이 없다 |
| 통제·증거 | 빌드 단계 M0(두 번째 빌드가 dist를 바꾸지 않게 하는 장치 없음), 사후 admission M3 · E3(빌드·admission·Chromium) + 소비자 기록 |
| 확실성과 남은 가정 | 확인. Vite 8.1.5 기준이다 |
| 결정의 근거 | 적용 제외 — 두 번째 빌드가 `public/`을 복사할 이유가 없고 같은 repo의 다른 두 번째 빌드가 이미 끈다. two-pass 자체는 4.2절에서 유지가 타당하다고 봤다 |
| 이해 비용 | `build-frontend.ts:31-37`이 3단계 복사만 설명해서, 6단계도 같은 복사를 한다는 사실은 Vite 내부를 읽어야 안다 |
| 최소 개선 방향 | `vite.service-worker.config.ts`에 `publicDir: false`. `build-frontend.ts` 6단계 주석에 "public 복사 없음" 한 줄 |
| 대안 비교 | 적용 제외 — 명백한 계약 위반의 단순 수정이다 |
| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다 |
| 비용·부작용 | 한 줄. 워커 빌드는 `public/` 파일을 쓰지 않는다 |
| 재검토 조건 | 적용 제외 — 선택을 바꾸는 판단이 아니다 |
| 완료 기준 | SW `ACTIVE` + `APP_PROFILE=production` + `VITE_ROUTER_BASE_PATH=/app/` 빌드 뒤 `dist/config.json`이 `generateRuntimeConfig("production", env)` 결과와 같다 |
| 검증 방법 | SW를 켠 빌드(e2e 도우미나 fixture)를 production 프로필로 돌려 `dist/config.json`을 대조하는 테스트 1개. `publicDir: false`를 지우는 변이로 실패하는지 본다. FOLLOW-UP 06-10(P3, SW Vite 설정 입력 테스트 없음)도 이 테스트로 닫힌다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 2026-09-25 06-10(설정 출처)에서 놓쳤다. 06-10의 완료 기준(워커가 프로필 값을 씀)은 충족되지만 페이지 설정은 틀린다. 회귀가 아니라 처음부터 있던 결함이다(`4626b73`의 빌드 순서도 같음) |
### 06-02 SW 사전 캐시 목록이 router base path를 무시해 하위 경로 배포에서 워커 설치가 항상 실패함
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 19, 18, 1, 10, 7 |
| 근거 | generator가 URL을 `/${relative}`로 만든다(`scripts/generate-service-worker-assets.ts:66`). base를 읽지 않는다. 워커는 manifest URL을 scope 기준으로 풀지만 root-relative라 base가 사라진다(`service-worker-lifecycle.ts:67-88`). 앱은 `/app/assets/…`를 요청한다(`vite.config.ts:64-67` `base`). **재현**(worktree, SW `ACTIVE`, `VITE_ROUTER_BASE_PATH=/app/`, 06-01 영향을 빼려고 config의 manifest URL만 `/app/…`로 고침, 서버는 `/app/` 아래만 서빙): Chromium에서 앱은 부팅하고 `/app/service-worker.js`를 받는다. 워커 install이 `/assets/application-provider-….js` 등 base 없는 경로를 요청해 404 → install 거절 → `getRegistration()` undefined, owned cache 0개. 같은 설정 안에서 06-08 fallback은 base를 따른다(`service-worker-static-assets.ts:66-78`). SW 빌드의 runtime config URL 기본값도 base를 무시한다(`vite.service-worker.config.ts:94-96`, 페이지는 `/app/config.json`, `tests/unit/sub-path-deployment.test.ts:23-31`). `vite.config.ts:26-33`은 "하위 경로 배포가 일관되거나 빌드에서 실패한다"고 주장한다. 하위 경로 SW 테스트는 없다 |
| 발생 조건 | SW `ACTIVE` + `VITE_ROUTER_BASE_PATH`가 `/`가 아님. 06-01을 고친 뒤에 드러난다 |
| 영향 | 워커가 설치되지 않는다. 앱은 네트워크로 정상 동작한다(안전한 쪽 실패). 옛 탭 청크 보존 등 SW의 이점이 전부 없다. 페이지에는 `service-worker.start.failed`(`INSTALL_FAILED`)만 남고 원인(`STATUS_INVALID`)은 워커 안에 있다 |
| 심각도·우선순위 | Medium · P2. 피해가 기능 부재로 한정된다 |
| 통제·증거 | M0(base와 manifest URL 일치 검사 없음) · E3(Chromium 1회) |
| 확실성과 남은 가정 | WebKit·Firefox는 돌리지 않았다. 같은 URL 해석이라 결과가 같다고 추론한다 |
| 결정의 근거 | 적용 제외 — "하위 경로 일관성"이 이미 정해진 계약이다 |
| 이해 비용 | 하위 경로 값을 읽는 곳이 `vite.config.ts`, `generate-runtime-config.ts`, `expectedServiceWorkerUrls`, 06-08 fallback 네 곳인데 generator와 SW 빌드는 빠졌다 |
| 최소 개선 방향 | generator가 `VITE_ROUTER_BASE_PATH`를 URL 앞에 붙인다(root-relative라 `isCanonicalStaticAssetUrl`을 그대로 통과). SW 빌드의 runtime config URL은 `getBuildConfig`(`src/contracts/env.ts`)로 계산한다 |
| 대안 비교 | 적용 제외 — 워커 쪽에서 scope 상대로 푸는 방법도 있지만 계약 차이는 없고 generator 수정이 워커를 바꾸지 않아 더 작다 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 수 줄. manifest digest가 base마다 달라진다(의도된 결과) |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | `/app/` 빌드의 manifest URL이 모두 `/app/assets/`로 시작하고, e2e 도우미를 base 옵션으로 돌린 첫 설치가 `RELOAD_TO_ENABLE`이다 |
| 검증 방법 | `collectStaticAssets` 단위 테스트 1개 + e2e 도우미에 base 옵션 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음. 06-09(클릭 fallback base)와 같은 부류다 |
### 06-03 레시피는 오프라인 셸을 SW 설치 조건으로 적지만, SW 계약은 이를 금지하고 제품이 켤 확장 지점도 없음
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험(주장과 코드 불일치 포함) |
| 관련 관점 | 17, 3, 20, 5, 4 (30.3, 30.7) |
| 근거 | catalog: `"trigger": "Installability, a measured offline-shell requirement, …"`(`config/recipes/frontend-capability-recipes.json:140`), failureKinds에 `offline-fallback`. 레시피 문서: "install/offline shell"(`optional-adapter-recipes.md:94`). 코드: navigation `NETWORK_ONLY`(`service-worker-static-assets.ts:47`), `intercepts()`는 두 분류만(`service-worker-lifecycle.ts:272-278`), `index.html` 제외·해시 이름만(`generate-service-worker-assets.ts:33-39`, `:56`). 설계: 오프라인 셸 비지원(`…closed-deep-design.md:327`, `:3842-3850`), 금지 목록 "cache index.html navigation fallback"(`:5897`). 확장 지점: handler 3종 고정(`service-worker-build-input.ts:148-161`), 엔트리는 `runtime.intercepts` 하나만 부른다(`service-worker-entry.ts:94-111`). 소비자: memento는 `service-worker-lifecycle.ts`(+44줄, `isShellNavigation`과 `intercepts` 첫 줄), `generate-service-worker-assets.ts`(`index.html`·사진 11개), `vite.service-worker.config.ts`를 고쳤다(`git diff af3d8e6 chore/template-sync-v0.2.0`) |
| 발생 조건 | 제품이 설치형 PWA나 오프라인 탐색을 요구한다 |
| 영향 | 제품이 템플릿 소유 파일의 동기 가로채기 결정을 고친다. 이후 동기화마다 같은 파일에서 충돌한다(memento는 이번 동기화에서 실제로 충돌을 풀었다). 템플릿이 금지한 동작을 템플릿 검증 없이 넣으므로 "HTML과 자산은 같은 릴리스" 성질(`:3847-3849`)을 제품이 다시 증명해야 한다. catalog를 보고 온 사용자는 코드가 이를 금지한다는 것을 뒤늦게 안다 |
| 심각도·우선순위 | Medium · P2. 기능 결함이 아니라 도입·업데이트 비용과 주장 불일치다 |
| 통제·증거 | 설계 문서 M1, catalog는 반대 주장 · E1(코드) + 소비자 diff |
| 확실성과 남은 가정 | 소비자 한 곳의 사례다. tech-log는 SW `null`이다 |
| 결정의 근거 | 4.1절. 확인한 사실: 분류 규칙과 memento diff. 기록된 의도: 설계의 비지원 명시. 추론: 선택 handler가 "같은 릴리스" 성질을 지킬 수 있다 |
| 이해 비용 | 제품 개발자는 catalog·레시피 문서·설계 문서의 서로 다른 주장을 읽고, 엔트리 → lifecycle → static-assets → generator 4파일을 따라가야 오프라인 셸을 넣을 곳을 안다 |
| 최소 개선 방향 | catalog와 레시피 문서의 "offline shell"을 설계와 맞춘다. 비지원을 적고, 졸업 경로(제품이 넘겨받는 파일, 바꿔야 할 e2e와 기대값)를 둔다. 선택 handler는 재검토 조건이 오면 한다 |
| 대안 비교 | 4.1절 표: 현상 유지(주장 모순 남음) / 문서 정정 + 졸업 경로(최소) / 선택 handler `OFFLINE_NAVIGATION_SHELL`(조합 1개·e2e 1개) / 일반 interceptor hook(순서·충돌 규칙이 새로 생겨 가장 비쌈) |
| 단순화의 보존 조건 | 기본 구성에서 navigation은 network-only, `index.html`은 기본 manifest에 없다. handler를 추가한다면 현재 릴리스 캐시의 HTML만 쓰고 이전 릴리스 HTML은 쓰지 않는다 |
| 비용·부작용 | 문서 정정은 작다. handler는 설계 금지 목록 수정과 조합 검증 책임(30.2)이 생긴다 |
| 재검토 조건 | 두 번째 소비자가 오프라인 셸을 요구하거나, memento의 lifecycle 수정이 다음 동기화에서 다시 충돌하면 handler를 비교한다 |
| 완료 기준 | catalog·레시피·설계의 오프라인 셸 주장이 같다. 제품이 템플릿 파일을 고치지 않고 켜는 경로가 있거나, 없다는 사실과 졸업 절차가 문서에 있다 |
| 검증 방법 | 세 문서 대조. handler를 고르면 오프라인 navigation e2e와 "이전 릴리스 HTML 비사용" 단위 테스트 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 06-04 SW e2e 도우미가 선택 `null` 줄을 문자열로 바꿔서, SW를 켠 제품에서는 update·recovery spec이 모두 멈춤
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 10, 20, 21 (30.4) |
| 근거 | 도우미는 `const SERVICE_WORKER: InstalledServiceWorkerSelection \| null = null;`을 찾아 바꾸고(`tests/e2e/support/service-worker-builds.ts:125-129`), 정확히 한 번 없으면 throw한다(`:83-93`). recovery spec은 그 결과 문자열을 다시 찾는다(`service-worker-recovery.spec.ts:42-49`). install spec은 캐시 경로가 `dist/assets` 전체와 같아야 한다고 본다(`service-worker-update.spec.ts:86-90`, `:124`). **변이**: worktree에서 선택을 `ACTIVE`로 바꾸고 update spec을 돌렸더니 `beforeAll`에서 `Expected exactly one "const SERVICE_WORKER: … = null;"`로 5개 모두 실패·미실행. `builds`가 undefined라 temp 폴더(`ca-sw-builds-*`)도 남는다. 소비자: memento e2e의 새 템플릿 spec 실패 3 / 미실행 4 중 SW spec 2개를 "후속"으로 남겼다 |
| 발생 조건 | 다운스트림이 SW를 켠다. 이 spec이 실제로 필요한 유일한 상황이다 |
| 영향 | 업데이트 핸드셰이크·옛 청크 fallback·자기 해제 복구의 브라우저 증거(18, 28)가 SW를 쓰는 제품에서만 사라진다. 제품은 템플릿 테스트를 고치거나 격리해야 한다 |
| 심각도·우선순위 | Medium · P2 |
| 통제·증거 | 템플릿 기본 상태 M3, SW를 켠 제품 M0 · E3(변이 실행) |
| 확실성과 남은 가정 | 확인 |
| 결정의 근거 | 적용 제외 — 도우미 입력 방식의 결함이다 |
| 이해 비용 | 제품 개발자가 도우미의 문자열 치환 두 단계를 읽어야 실패 원인을 안다 |
| 최소 개선 방향 | 도우미가 현재 `SERVICE_WORKER` 선언 전체를 값과 무관하게 찾아 `ACTIVE_SELECTION`으로 바꾼다. install spec의 기대값은 그 빌드가 만든 `.generated/frontend-runtime/service-worker-assets.ts` 목록과 비교한다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 도우미 수 줄. 06-03의 사전 캐시 확장과 함께 보면 기대값 비교가 자연스럽다 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 선택이 `ACTIVE`인 트리와 `null`인 트리에서 두 spec이 모두 통과한다 |
| 검증 방법 | 위 변이를 다시 적용해 통과하는지 본다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음. FOLLOW-UP P3("route chunk를 바꾸는 변경"을 도우미 옵션으로)와 같은 도우미다 |
### 06-05 설계가 호스팅 설정에 맡긴 `service-worker.js`의 `no-cache`가 호스팅 정책 파일과 live probe에 없음
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(설정 누락) + 구조적 위험(복구 경로) |
| 관련 관점 | 18, 28, 19, 21 |
| 근거 | 설계: `service-worker.js Cache-Control = no-cache` … "Static delivery configuration owns this requirement"(`…closed-deep-design.md:3411-3418`). 레시피 6단계도 같다(`optional-adapter-recipes.md:130-131`). 정적 전달 설정 `config/hosting/cache-policy.json`에는 index·config·release manifest·`/assets/*`만 있다. live probe도 이 네 곳만 요청한다(`scripts/verify-hosting-headers.ts:120-125`). SW 관련 검사는 dist에 파일이 있는지뿐이다(`scripts/lib/hosting-probe.ts:37-58`). 등록은 `updateViaCache: "none"`이라 브라우저 HTTP 캐시는 우회한다(`service-worker-page-controller.ts:157-161`). CDN·프록시 캐시는 우회하지 못한다(표준 동작, 추론) |
| 발생 조건 | SW `ACTIVE`(또는 `REMOVE_REGISTRATION`) + CDN이 루트 `.js`에 긴 TTL을 준다(예: `*.js`를 immutable로 묶는 규칙) |
| 영향 | 새 워커와 자기 해제 워커가 edge TTL 동안 사용자에게 가지 않는다. 롤백과 비상 해제가 늦어지고 게이트는 이를 알리지 않는다 |
| 심각도·우선순위 | Medium · P2. 발생은 호스팅 설정에 달렸지만, 막히는 것이 페이지 없는 유일한 복구 경로다 |
| 통제·증거 | M1(문서만) · E1 |
| 확실성과 남은 가정 | 실제 CDN에서 재현하지 않았다 |
| 결정의 근거 | 적용 제외 — 설계가 이미 요구와 책임 위치를 정했다 |
| 이해 비용 | 운영자는 cache-policy.json이 전체 정적 전달 정책이라고 믿기 쉽다 |
| 최소 개선 방향 | cache-policy.json에 `serviceWorker` 항목(`/service-worker.js`, `no-cache`, `text/javascript`)을 둔다. 선택이 `ACTIVE`·`REMOVE_REGISTRATION`일 때 live probe가 요청한다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 설정 1항목, probe 조건 1개. SW `null` 구성에는 추가 요청이 없다 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | SW를 켠 구성에서 fixture의 `service-worker.js` Cache-Control을 틀리게 바꾸면 `verify:hosting-headers`가 FAIL |
| 검증 방법 | fixture 변이 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 2026-09-25 판정표 19번에 "Cache-Control 미검사"로 적혔지만 발견 항목이 아니어서 닫히지 않았다 |
### 06-06 제거 2·3단계는 `service-worker.js`를 내보내지 않아, 부팅을 막는 워커가 1단계 기간에 오지 않은 사용자에게 남음
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 28, 18, 26 |
| 근거 | 자기 해제 워커는 `REMOVE_REGISTRATION`에서만 쓴다(`scripts/build-frontend.ts:72-77`). hosting 검사는 `PURGE_OWNED_RESOURCES`·`null`에서 워커 파일이 있으면 실패시킨다(`scripts/lib/hosting-probe.ts:43-45`). **실험**: 워커 등록 뒤 스크립트를 404로 바꾸고 `update()`와 새 navigation → Chromium·WebKit·Firefox 모두 update는 TypeError로 거절되고 등록과 active 워커가 남는다. 운영 문서는 세 단계 순서만 적고 1단계 유지 기간을 적지 않는다(`docs/operations/release-cache-rollback.md:99-109`) |
| 발생 조건 | 부팅을 막는 워커 → `REMOVE_REGISTRATION` 배포 → 그 기간에 방문하지 않은 사용자가 `PURGE_OWNED_RESOURCES` 이후에 방문 |
| 영향 | 페이지가 부팅하지 않아 페이지 쪽 해제도 못 한다. 사용자가 사이트 데이터를 지우기 전까지 복구되지 않는다 |
| 심각도·우선순위 | Low · P3. 이미 드문 비상 상황 중 일부 사용자다 |
| 통제·증거 | M1 · E3(404 등록 유지, 3엔진) |
| 확실성과 남은 가정 | 사용자 방문 분포는 제품마다 다르다 |
| 결정의 근거 | 적용 제외 — 절차 누락이다 |
| 이해 비용 | 운영자는 "1단계를 언제 끝내도 되는가"를 코드와 브라우저 동작에서 추론해야 한다 |
| 최소 개선 방향 | 운영 문서에 "부팅을 막는 워커였다면 1단계를 사용자 최대 미방문 기간만큼 유지" 한 줄. 또는 2단계도 자기 해제 워커를 내보내고 hosting 허용 목록을 맞춘다 |
| 대안 비교 | 적용 제외 — 두 방법 모두 작고, 문서 한 줄이 먼저다 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 문서 한 줄. 코드로 가면 빌드 분기 1개와 hosting 검사 수정 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 운영 문서에 유지 기간 조건이 있다. 또는 2단계 dist에 자기 해제 워커가 있고 hosting 검사가 통과한다 |
| 검증 방법 | 문서 대조. 코드로 가면 `service-worker-recovery.spec.ts`에 "B 대신 PURGE 빌드" 사례 추가 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 2026-09-25 미검증 목록의 "404일 때 등록 유지"를 이번에 3엔진에서 확인했다 |
## 6. FOLLOW-UP 재확인 (`2026-09-25-maturity-review/FOLLOW-UP.md`)
| 항목 | 결과 | 현재 근거 |
|---|---|---|
| P2 06-05: 업데이트 설치 실패·`observe`·`health()` 미연결 | 유효 | `watchForUpdates`는 `installed`만 알린다(`service-worker-page-controller.ts:328-349`). `src`에 `.health()` 호출 0건. `create-runtime-composition.ts`는 `telemetry`만 넘기고 `observe`·`blockers`는 넘기지 않는다 |
| P2 06-08: fallback이 `assets/`를 하드코딩 | 유효 | `service-worker-static-assets.ts:66` `BUILD_ASSET_DIRECTORY = "assets/"`. `vite.config.ts`는 `build.assetsDir`를 정하지 않는다 |
| P3 06-10: SW Vite 설정의 `dist/config.json` 읽기에 단위 테스트 없음 | 유효 | 테스트는 `resolveServiceWorkerBuildInput`만 본다. 이 빈틈 때문에 06-01이 보이지 않았다. 06-01의 검증 테스트가 함께 닫는다 |
| P3 `service-worker-update.spec.ts`의 route chunk 변경용 export 덧붙이기 | 유효 | `service-worker-update.spec.ts:38-57`(`CHANGED_ROUTE_SOURCE`에 export 추가). 도우미 옵션으로 올리지 않았다. 06-04와 같은 도우미다 |
## 7. 미검증 목록
| 항목 | 이유 | 확인하려면 |
|---|---|---|
| `test:realtime-removal`(web-push 삭제 가능성, 27) | worktree에서 `pnpm`이 링크된 `node_modules`에 설치를 시도했다(`ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY`). 메인 `node_modules`를 지울 위험이 있어 재시도를 중단했다 | 오케스트레이터 게이트나 CI에서 실행 |
| 06-02의 WebKit·Firefox | Chromium 한 번만 돌렸다 | 도우미에 base 옵션을 넣고 3엔진 실행 |
| 06-05의 실제 CDN 동작 | CDN 환경 없음 | staging CDN에서 `service-worker.js` 응답 헤더 확인 |
| 얼어 있는 탭이 Web Lock을 쥔 경우(4.3) | 브라우저 정책 의존, 재현 환경 없음 | 두 탭 중 하나를 `Page.setWebLifecycleState(frozen)`으로 얼린 채 enable 중 revoke |
| 여러 창 활성화(앱이 아닌 창, 06-07 잔여) | 실제 브라우저 두 창 시나리오를 돌리지 않았다 | e2e 도우미로 두 번째 page를 `/config.json`에 두고 `requestActivation()` |
| Web Push end-to-end(실제 푸시 서비스, VAPID, 클릭) | 푸시 서버 없음. WEB_PUSH는 빌드에서 거절된다 | 로컬 web-push 서버와 제품 조립 브랜치 |
| memento의 lifecycle 변경이 "같은 릴리스" 성질을 지키는지 | 소비자 코드는 리뷰 범위 밖 | 제품 리뷰에서 확인 |
| Firefox의 SW 제어(update·recovery spec) | Playwright Firefox 제약으로 격리됨(`quarantine … expires=2027-03-31`) | 수동 확인 또는 Playwright 업데이트 뒤 재실행 |
@@ -0,0 +1,393 @@
# 07 contracts (공유 어휘·외부 계약) — 성숙도 리뷰
> 검토일: 2026-09-29 · 기준: `main` / `af3d8e6` (코드 변경 없음, 리뷰 가이드 문서 2개만 미커밋) · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 영역 판정(35.8): **조건부 사용 가능** — 외부 입력 검증(런타임 설정·릴리스 매니페스트·exact decode)과 런타임 설정 스키마 기준선(FE-GATE-014)은 그대로 써도 된다. 레지스트리 호환성 게이트(`check:registries`)의 증거 절차는 믿고 복제하면 안 된다. 한 번 남긴 증거가 뒤의 다른 변경까지 통과시키고(07-01), 추가 성격의 변경을 breaking으로 막고(07-02), 기능 라우트 하나에도 템플릿 governance 파일 수정을 요구한다(07-03). 두 다운스트림 모두 이 절차에서 비용을 냈다(07-04).
## 1. 머리말
### 1.1 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 | `clean-architecture-frontend-template`, `main` / `af3d8e6`, 2026-09-29 |
| 목적·실행 구성 | 프론트엔드 템플릿. 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음 |
| 영역 경로 | `src/contracts/`(41파일, 8.7k줄), `schemas/`(5파일), `config/contracts/`(4파일), `config/compatibility/`, `tests/contract/`, `tests/runtime-schema/`. 이 영역을 실행하는 스크립트 `scripts/check-registries.ts`, `scripts/lib/registry-compatibility.ts`, `scripts/check-compatibility.ts`, `scripts/update-registry-baseline.ts`, `vite.config.ts`의 `VITE_*` 검사 |
| 깊게 본 관점 | 1, 3, 17, 19, 22, 23, 24 (+39.5) |
| 읽은 가이드 절 | 0, 1, 3, 17, 19, 22~24, 29, 30, 32, 34~36, 39, 41 |
| 줄 단위로 읽은 코드 | `compatibility.ts`, `env.ts`, `zod.ts`, `errors.ts`(1~232행), `release-artifacts.ts`(1~215행), `external-contract-runtime.ts`(55~110행), `boundary-mapper.ts`(1~30행), `routes.ts`(1~25행), `scripts/lib/registry-compatibility.ts` 전체, `scripts/check-registries.ts`(1~200, 515~722행), `scripts/check-compatibility.ts`, `scripts/update-registry-baseline.ts`, `config/contracts/registry-governance.json`의 FE-REG-ROUTE·FE-REG-ENV 블록, `registry-change-evidence.json`, `tests/unit/http-operation-v2-v3-parity.test.ts`, `tests/unit/second-api-feature-registries.test.ts`(1~40행), `tests/fixtures/registry/compatibility/semantic-diff.json`. 흐름 추적용: `src/bootstrap/load-runtime-config.ts:94-175`, `src/bootstrap/runtime-config-schema.ts:1-100`, `scripts/check-architecture.ts:330-520, 918-940`, `vite.config.ts:1-60`, `docs/contracts/compatibility.md`, `docs/operations/ci-quality-gates.md:60-70`, `docs/architecture/starter-experience.md:120-150` |
| 다운스트림 증거 | `../tech-log-frontend` 브랜치 `chore/template-sync-v0.2.0`(`42d1ae1f`)을 `git archive`로 scratchpad에 풀어 실행했다. `../memento-frontend` 브랜치 `chore/template-sync-v0.2.0`(`d3810a0`)는 `git diff af3d8e6 <branch>`와 동기화 기록만 읽었다. 두 repo의 브랜치·워킹트리는 바꾸지 않았다 |
| 이전 리뷰와 비교 | `docs/reviews/2026-09-25-maturity-review/07-contracts.md`의 07-01~07-07과 FOLLOW-UP의 07-03·07-07을 현재 코드에서 다시 확인했다(6절). 이전 실행 결과는 증거로 쓰지 않았다 |
### 1.2 실행한 명령과 실험
템플릿 실험은 모두 격리 worktree(`<scratchpad>/review-2026-09-29/07/wt`, `af3d8e6`, 메인 `node_modules` 심볼릭 링크)에서 했다. 끝난 뒤 worktree를 지웠다.
| ID | 무엇 | 결과 |
|---|---|---|
| R1 | `node scripts/check-registries.ts` (변경 없음) | `11 registries PASS; compatibility=breaking`. 현재 diff는 3건: breaking 2건(`FE-REG-ENV:VITE_BUILD_ID:defaultValue:field-type-changed`, `FE-REG-ROUTE:REFERENCE_RESOURCE_DETAIL:path:field-changed`, 둘 다 증거 있음), additive 1건. 증거 파일 15건 중 **13건은 현재 diff의 어떤 변경과도 맞지 않는다** |
| R2 | tech-log 브랜치를 풀어 `check-registries.ts` 실행 | 구조 오류 5건(TechLog 스키마 id 미등록, `has unknown value` 3건 포함) + `breaking change missing evidence` 6건: `TECH_LOG_RELEASES`의 `navigationLabel`·`navigationOrder` `field-type-changed`, `TECH_LOG_STUDIO_{DOCUMENTS,PUBLICATIONS}`의 `searchSchema` `field-type-changed`와 `searchCodec` `field-changed` |
| X1 | `EXAMPLES_AUTH.navigationLabel` "인증 연동" → "인증 예시" | PASS. `behavior-change` |
| X2 | `EXAMPLES_AUTH.navigationLabel`·`navigationOrder` → `null` (메뉴에서 숨김) | **FAIL.** `navigationLabel:field-type-changed`, `navigationOrder:field-type-changed` 2건이 breaking 증거 누락 |
| X3 | `REFERENCE_RESOURCE_DETAIL.path` → `/examples/reference-resources/entries/:resourceId` (08-13 증거가 설명하는 `/items/`와 다른 값) | **PASS.** 같은 `changeId`의 기존 증거가 새 변경을 덮었다 |
| X4 | governance FE-REG-ROUTE `allowedValues.loadingSurface`에 값 1개 추가 | **FAIL.** `FE-REG-ROUTE:$contract:allowedValues:contract-field-changed` breaking 증거 누락 |
| X5 | 참조 기능의 `REFERENCE_RESOURCE_STATUS.loadingSurface`를 기능 전용 새 값으로 | **FAIL.** `has unknown value reference-resource-archive` |
| Z1 | `src/presentation/routes/platform-route-codecs.ts`의 `z` import를 `"zod/v4"`로 바꾸고 `corepack pnpm check:architecture` | **PASS.** 같은 곳을 `"zod"`로 바꾸면 `zod-is-reached-through-contracts-zod` 위반으로 실패 |
| Z2 | `corepack pnpm build` 뒤 `tests/e2e/production-csp.spec.ts`를 chromium 1개 프로젝트, 별도 포트(4297) 설정으로 실행. (가) 변경 없음, (나) Z1 변이, (다) `src/bootstrap/initialize-color-scheme.ts` 맨 위에 `zod/v4` object schema와 모듈 수준 `safeParse` 추가 | 세 경우 모두 통과(CSP 위반 0). `dist`를 보면 `a({jitless:!0})`가 zod 코드 바로 뒤, 같은 청크(`reference-feature-runtime-descriptor-*.js`)에 있다 |
| V1 | `VITE_FEATURE_FLAG_URL=… corepack pnpm build` | 빌드 실패: `Undeclared VITE_* build variables: VITE_FEATURE_FLAG_URL. Declare them in ENV_REGISTRY (src/contracts/env.ts) or unset them` |
| V2 | `ENV_REGISTRY`의 runtime 행과 `z.toJSONSchema(runtimeConfigV2ArtifactSchema, {io:"input"})` 비교 스크립트 | 불일치 5곳, 스키마에만 있는 키 2개(07-05) |
| M1 | 변이: `createFailure`의 "효과가 있었을 수 있으면 `retryable=false`" 규칙 제거(`errors.ts:166-169`) | killed (`error-classification.test.ts` 1건 실패). 지난 라운드 M1 survived → 해소 |
| M4 | 변이: `isValidReleaseManifestUrl`의 origin·pathname 재확인 제거(`release-artifacts.ts:44`) | killed (4건 실패) |
| M6 | 변이: exact decode의 non-enumerable 거부 제거(`exact-snapshot.ts:104`) | killed (2건 실패) |
| G1 | `git show --stat 17d617a`, `git log -- scripts/lib/registry-compatibility.ts` | 07-02·13-10 커밋은 `scripts/check-compatibility.ts`·`config/compatibility/`만 바꿨다. 레지스트리 분류기 파일은 최초 커밋 이후 바뀐 적 없다(07-07) |
| D1 | 두 제품의 템플릿 대비 diff | tech-log: 런타임 설정 키 2개를 `env.ts`·`release-artifacts.ts`·`runtime-config-schema.ts` 세 파일에 손으로 적었다. memento: `registry-change-evidence.json`에 10건 추가, 그중 7건이 같은 문장("never deployed")의 `FE-REG-STORAGE:*:physicalKey` |
오케스트레이터가 이미 돌린 게이트(`test:contract` 15/15, `test:runtime-schema` 56/56, `check:architecture` PASS 등)는 다시 돌리지 않았다. 변이 실험에서 필요한 테스트 파일만 돌렸다.
R1·R2·X1~X5·V2·M1·M4·M6은 `node scripts/…`와 `node scripts/run-vitest.ts`로 직접 돌렸다. Z1·Z2·V1은 worktree에서 `corepack pnpm run`/`exec`로 돌렸다(`pnpm_config_verify_deps_before_run=false`로 설치 검사를 끔). 실험 뒤 메인 `node_modules`의 직접 의존성 35개가 모두 해석되는 것을 확인했다.
### 1.3 오케스트레이터 검증 후보의 결과
- **"tech-log는 0.2.0 분류기 때문에 라우트 변경 6건이 막혀 있다."** 부분만 맞다. 0.2.0에서 바뀐 분류기는 런타임 설정 스키마용 `classifyObjectSchemaChange`다(G1). 레지스트리 분류기 `diffRegistrySnapshots`는 바뀌지 않았다. tech-log 기록도 동기화 전 `8210d48`에서 같은 출력이 났다고 적는다. 6건 중 4건(`searchSchema`, `searchCodec`)은 governance가 스스로 breaking 필드로 선언한 변경이다. 나머지 2건(`navigationLabel`, `navigationOrder`)은 분류기의 과잉 판정이다(07-02). 증거 절차의 이해 가능성은 07-04에 적었다.
- **`src/contracts/zod.ts` 강제.** 규칙은 정확히 `"zod"`라는 이름만 막는다. `"zod/v4"`는 통과한다(Z1). 다만 현재 번들에서는 CSP 위반이 재현되지 않았다(Z2). 07-06.
- **`ENV_REGISTRY`.** `VITE_*` 추가 경로는 분명하다. 선언하지 않으면 빌드가 이유와 고칠 파일을 말하며 멈춘다(V1, `tests/unit/build-environment-bundle.test.ts:83`이 고정). 런타임 설정 키는 다르다. 같은 사실이 세 파일에 있고 이미 어긋나 있다(07-05).
- **39.5 (같은 사실의 반복).** 5.1절 표에 사본마다 불일치 검출이 있는지 정리했다.
### 1.4 확인하지 못한 범위
- `browser-rpc.ts`, `realtime-streams.ts`, `query-keys.ts`, `server-state.ts`, `service-worker*.ts`, `web-worker.ts`, `web-push.ts`, `cache-invalidation.ts`, `query-invalidation.ts`는 이번에 줄 단위로 읽지 않았다. 지난 라운드 결과를 증거로 쓰지 않고 판정표에서 해당 부분을 `?` 또는 범위 밖으로 둔다.
- memento에서 `check:registries`를 직접 돌리지 않았다. 동기화 기록(`PASS, compatibility=breaking`)과 diff만 읽었다.
- CSP 검사는 chromium 한 엔진에서만 했다. tech-log처럼 `manualChunks`를 바꾼 제품에서 `zod.ts`가 zod와 같은 청크에 남는지는 빌드하지 않았다.
## 2. 대표 흐름
### 2.1 정상 흐름 — 런타임 설정을 읽어 부팅한다
```text
입력 dist/config.json (배포자가 쓰는 문서)
→ 정책 getBuildConfig()가 설정 URL을 정한다 src/contracts/env.ts:131-147
→ I/O 크기 제한 있는 JSON 읽기 src/bootstrap/load-runtime-config.ts:100-114
→ 정책 비밀처럼 보이는 키 이름 거부 src/contracts/env.ts:85-117, load-runtime-config.ts:118-125
→ 정책 CONFIG_SCHEMA_VERSION으로 파서 하나만 고른다 src/bootstrap/runtime-config-schema.ts:75-98
→ 정책 zod strict 스키마 + 불변식(HTTPS, demo는 local만) src/contracts/release-artifacts.ts:91-149, 169-177
→ 정책 HTML의 buildId와 설정의 BUILD_ID 일치 load-runtime-config.ts:152-167
→ 상태 검증된 스냅샷을 freeze해서 반환 load-runtime-config.ts:170-176
실패 BootConfigError(CONFIG_SECRET_NAME_REJECTED / CONFIG_SCHEMA_INVALID / CONFIG_BUILD_MISMATCH).
invalidKeys는 키 이름만, 개수 제한(load-runtime-config.ts:136-142)
결과 부트 오류 화면. 모르는 키·타입 오류는 fail-closed
```
이 흐름은 잘 막혀 있다. 모르는 키는 `.strict()`가 거부한다. 스키마 변경은 FE-GATE-014가 커밋된 기준선과 비교한다(`scripts/check-compatibility.ts:28-51`). 변이 M4가 killed였다.
### 2.2 피해가 큰 흐름 — 공개 계약(라우트 경로)을 깨는 변경이 게이트를 지난다
```text
입력 기능 계약의 route path 변경 (북마크·외부 링크가 의존하는 URL)
→ 조립 생성기 → ROUTE_REGISTRY scripts/generate-product-feature-index.ts
→ 투영 레지스트리 스냅샷 scripts/check-registries.ts:489-519
→ 비교 승인된 기준선과 diff (fail-closed) scripts/lib/registry-compatibility.ts:96-279
→ 정책 breaking이면 changeId로 증거 조회, 5개 필드 비었는지만 확인 registry-compatibility.ts:300-336
→ 결과 PASS / FAIL
실패 증거 행은 changeId(registry:row:field:kind)만 가진다. 값(before/after)을 모른다.
기준선을 다시 찍지 않는 한, 같은 row·field의 두 번째 다른 변경도 기존 증거로 통과한다(X3)
결과 예전 URL이 404가 되는데 새 이행 계획·롤백 계획 없이 머지된다
```
### 2.3 변경 흐름 — 다운스트림이 기능 라우트와 설정 키를 추가한다
```text
[라우트] 기능 계약에 route + routeRuntime + 스키마 등록 (기능 디렉터리 안)
→ check:registries: 새 search schema id·loading surface 이름이 governance allowedValues에 없음
→ "has unknown value" (X5, tech-log R2)
→ 템플릿 소유 config/contracts/registry-governance.json:42-60을 고친다
→ check:registries: $contract:allowedValues 변경 = breaking (X4)
→ 증거 5필드를 쓰거나(memento) 기준선을 재승인하거나(update:registry-baseline) 그대로 둔다(tech-log)
→ 다음 동기화에서 governance·baseline·evidence JSON을 손으로 3-way merge (tech-log 기록)
[VITE_*] .env에 VITE_X → 빌드 실패, 메시지가 env.ts를 가리킴(V1) → ENV_REGISTRY에 행 추가(additive, 증거 불필요) → 끝
[런타임 설정 키] ENV_REGISTRY 행 + release-artifacts.ts의 zod 필드 + runtime-config-schema.ts의 타입과 정규화
+ FE-GATE-014 기준선 갱신. 템플릿 소유 파일 3개(tech-log D1). ENV_REGISTRY 행은 아무도 대조하지 않는다(07-05)
```
기능 디렉터리만 고치면 된다는 문서의 약속(`docs/architecture/starter-experience.md:145-147`)은 API만 가진 기능에서만 맞다. 그 약속을 고정하는 테스트도 `routes: {}`인 기능만 쓴다(`tests/unit/second-api-feature-registries.test.ts:11-15, 38`).
## 3. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가
| 번호 | 관점 | 판정 | 통제 (목표 / 확인) | 증거 | 이유·잔여 위험 |
|---|---|---|---|---|---|
| **1** | 코드 성숙도 | O | M4 / M4 | E2 (M1·M4·M6 killed) | 외부 JSON은 strict 파서나 exact decode를 거친다(2.1). 효과를 모르는 쓰기는 `retryable=false`가 되고 `createFailure`·`withFailureEffect` 양쪽을 테스트가 고정한다(`errors.ts:156-221`, M1). `invokeValidator`는 결과 읽기까지 try 안에 있다(`external-contract-runtime.ts:72-101`) |
| 2 | 구조적 성숙도 | O | M3 / M3 | E2 (오케스트레이터 `check:architecture` PASS) | contracts → application·presentation·bootstrap·adapters 금지 규칙이 있다(`.dependency-cruiser.json` `contracts-do-not-know-*`) |
| **3** | 변경 용이성 | P | M3 / M1 | E2 (X4, X5, R2, D1) | `VITE_*` 추가는 1파일, 오류 종류 추가는 문구 누락까지 테스트가 잡는다(`tests/unit/i18n-contract.test.ts:42`). 기능 라우트 추가는 템플릿 governance 수정 + breaking 증거가 필요하다(07-03, 07-02). 런타임 설정 키는 템플릿 파일 3개를 고친다(07-05, 확장 지점은 09-02) |
| 4 | 인지 부하 | P | M1 / M1 | E1 | 레지스트리 변경 하나에 changeId 문법, 증거 5필드, "증거 vs 재승인" 선택, governance의 allowedValues·references·breakingFields를 알아야 한다(07-04) |
| 5 | 위험 가시성 | P | M2 / M2 | E2 (R1) | 상한·효과 확실성은 타입과 상수로 드러난다. 그러나 템플릿의 정상 상태 출력이 `PASS; compatibility=breaking`이다. 어느 breaking이 어떤 증거로 덮였는지, 그 증거가 지금 변경을 설명하는지 출력에 없다(07-01) |
| 6 | 실패 성숙도 | O | M3 / M3 | E1·E2 | 설정·매니페스트는 fail-closed로 부트 오류 화면에 간다(2.1). 오류 코드는 `ERROR_REGISTRY`로 닫혀 있다 |
| 7 | 운영 성숙도 | > | - | - | 영역 03·13 |
| 8 | 디버깅 가능성 | P | M2 / M2 | E2 (V1, R2) | `VITE_*` 누락 메시지는 고칠 파일을 말한다. `breaking change missing evidence: <changeId>`는 어느 파일에 무엇을 써야 하는지, 재승인이 대안인지 말하지 않는다(07-04) |
| 9 | 유지보수 성숙도 | P | M2 / M1 | E1 (R1) | 증거 15건 중 13건이 현재 변경과 무관한 이력이다(07-01). 폐기 별칭은 표시만 있고 새 import를 막는 lint가 없다(FOLLOW-UP 07-07). `docs/contracts/compatibility.md`의 줄 번호(`release-artifacts.ts:163-171` 등)가 실제(169-177)와 어긋난다 |
| 10 | 테스트 성숙도 | P | M3 / M3 | E2 (M1·M4·M6 killed, X1~X5) | 입력 경계 변이는 모두 잡힌다. 레지스트리 분류기 fixture에 "확장(widening)", "nullable 전환", "다른 값에 같은 증거" 사례가 없다(`tests/fixtures/registry/compatibility/semantic-diff.json`: 7개 사례 모두 좁히기·순서·추가·삭제). V2/V3 일치 테스트는 V2 행이 없어도 통과한다(FOLLOW-UP 07-03) |
| 11 | 데이터 성숙도 | > | - | - | 저장 키 계약의 실행은 영역 05. 이 영역에서는 키 버전·`migration: "discard"`만 확인 |
| 12 | 동시성 성숙도 | - | - | - | contracts는 순수 선언과 파서다 |
| 13 | 확장성 | P | M2 / M1 | E2 (X5, R2) | 기능이 늘수록 governance의 중앙 allowlist와 증거 파일이 함께 커진다(07-03, 07-01). 규모 실측은 영역 11 |
| 14 | 성능 성숙도 | - | - | - | 상한이 정해진 계산만 한다 |
| 15 | 보안 성숙도 | P | M4 / M3 | E2 (V1, Z1) · E3 (Z2) | 선언하지 않은 `VITE_*`는 빌드를 멈춘다. 비밀처럼 보이는 설정 키는 부팅이 거부한다. zod facade 규칙은 subpath import를 놓친다. 지금 번들에서는 CSP 위반이 재현되지 않았다(07-06) |
| 16 | 의존성 성숙도 | > | - | - | 영역 13 |
| **17** | API / Contract 성숙도 | P | M3 / M3(과잉·누락 검출 둘 다) | E2 (R1, X1~X4) · E3 (R2, D1 다운스트림) | 런타임 설정은 이전 reader 기준선과 비교한다(FE-GATE-014, 경계별 표 `docs/contracts/compatibility.md:14-32`). 레지스트리 게이트는 breaking을 증거 없이 통과시키는 경로가 있고(07-01), 추가 성격 변경을 breaking으로 막는다(07-02). 다운스트림 절차가 문서화돼 있지 않다(07-04). HTTP 응답 DTO 형태의 호환성은 외부 계약 패키지 책임으로 두고 이 게이트 밖이다 |
| 18 | 배포 성숙도 | > | - | - | 영역 13. FE-GATE-014 기준선 갱신은 "reader 먼저 배포" 절차를 문서에 둔다(`docs/contracts/compatibility.md:58-64`) |
| **19** | 설정 성숙도 | P | M3 / M2 | E2 (V1, V2) | build 변수: 선언 목록·기본값 일치 테스트·명확한 오류(`vite.config.ts:13-24`, `tests/unit/deployment-admission.test.ts:211-224`). 런타임 설정 키: `ENV_REGISTRY`가 zod 스키마와 다른 기본값·필수 여부를 적고 있고 대조하는 곳이 없다(07-05) |
| 20 | 개발자 경험 | P | M2 / M1 | E3 (D1, R2) | memento는 "배포한 적 없음" 증거 7건을 복사해 썼다. tech-log는 두 번의 동기화 동안 게이트를 빨간 채로 뒀다(07-04). 기능 추가 문서가 governance 수정을 부정한다(07-03) |
| 21 | Guardrail 성숙도 | P | M3 / M3(부분) | E2 (X2~X5, Z1) | 레지스트리 게이트의 누락 검출(07-01)과 과잉 검출(07-02), zod 규칙의 subpath 누락(07-06), V2/V3 일치 테스트의 빈 집합 통과(FOLLOW-UP) |
| **22** | 추상화 성숙도 | P | M2 / M2 | E2 (X4, X5) | 선언형 governance(`requiredFields`·`fieldTypes`·`references`·`breakingFields`)는 레지스트리 11개를 한 검사기로 다룬다. 유지할 가치가 있다(4.1). 그러나 `allowedValues`의 스키마 id 목록은 `references` 검사와 같은 사실의 세 번째 사본이다. `loadingSurface` 목록은 `data-surface` 속성(`app-router.tsx:78`) 말고 읽는 곳이 없는데 닫혀 있다(07-03). `consumers`는 파일에 문자열이 있는지만 본다(`check-registries.ts:554-567`, 예: FE-REG-ENV의 `APP_ENV`는 타입 필드 이름으로 충족) |
| **23** | 일관성 | P | M2 / M1 | E2 (X1·X2) | 같은 필드의 변경이 값에 따라 등급이 갈린다: 라벨 바꾸기는 behavior-change, 라벨 숨기기는 breaking(07-02). 기준선 4종의 갱신 절차가 다르다: CI 계약·레지스트리·의존성은 `*_OWNER`·`*_REASON`을 요구하고, 런타임 설정 스키마 기준선은 `--update-baseline`만 받는다(`scripts/check-compatibility.ts:29-33`). `MappingResult` 두 모양은 D-15 결정으로 유지(문서화됨) |
| **24** | 네이밍 / 의미 성숙도 | P | M2 / M1 | E1 (G1) | `field-type-changed`가 선언된 `string|null` 안의 null 전환까지 부른다(07-02). CHANGELOG 0.2.0의 "레지스트리 호환성 분류기" 행이 다른 분류기를 가리킨다(07-07). `ENV_REGISTRY`는 환경 변수가 아닌 런타임 설정 문서 키까지 담는다(07-05) |
| 25 | 조직 확장성 | P | M2 / M1 | E3 (D1) | 기능 팀마다 같은 governance JSON의 allowlist와 같은 evidence JSON을 고친다. memento는 evidence를 "양쪽 합집합"으로 병합했다(동기화 기록 236행) |
| 26 | Ownership 성숙도 | P | M2 / M1 | E1 | 증거·승인에는 owner가 있다. 오래된 증거를 정리할 책임과 절차가 없다(07-01). 폐기 별칭은 "다음 minor에 제거, owner frontend-platform"(`errors.ts:139-141`) |
| 27 | 삭제 가능성 | > | - | - | 영역 14. 행 삭제는 행마다 breaking 증거가 필요하다는 점만 기록(tech-log는 참조 기능 제거에 13건) |
| 28 | 회복 가능성 | - | - | - | contracts는 복구 절차를 소유하지 않는다 |
X(미충족)인 관점은 없다.
## 4. 설계 선택 설명 (41절)
### 4.1 레지스트리 호환성 게이트: 승인된 기준선 + fail-closed diff + changeId별 증거
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 라우트·API·스키마·설정·저장 키·오류·텔레메트리 등 레지스트리 11개의 공개 계약 변경을 리뷰 단계에서 식별한다. 깨지는 변경이면 이행 정보(버전, 이행, 호환 기간, 롤백, 담당)를 남긴다 |
| 2. 지킬 성질 | (a) breaking 변경은 그 변경을 설명하는 증거 없이 통과하지 않는다. (b) 모르는 변경은 breaking으로 본다. (c) breaking이 아닌 변경은 증거 없이 통과한다 |
| 3. 현재 보장 | 확인한 사실: 승인 파일의 digest·owner로 기준선을 고정한다(`registry-compatibility.ts:281-298`). 순서 차이는 변경으로 세지 않는다(`:35-56`). 분류 규칙이 없는 변경은 breaking이다. 증거는 changeId마다 5필드가 비어 있지 않은지만 본다(`:300-336`). **보장하지 않는 것:** 증거와 값의 연결(07-01, X3), 선언된 nullable 타입과 allowlist 확장의 인식(07-02, X2·X4), 재승인할 때의 증거 요구(07-04) |
| 4. 현실적인 대안 | (A) 현 상태. (B) 현 구조에 세 가지를 더한다: 증거 행에 `after` 값을 적고 비교, 현재 diff와 맞지 않는 증거 행은 실패, nullable 전환·allowlist 확장은 선언을 보고 분류. (C) 증거 파일을 없애고 재승인(owner·reason)만 둔다. (D) 게이트를 없애고 PR 리뷰에 맡긴다 |
| 5. 대안의 비용 | (A) 비용 0. 누락·과잉 둘 다 남는다. (B) 스크립트 수십 줄과 fixture 몇 개. 증거 행에 값이 들어가 파일이 조금 길어진다. (C) 가장 단순하다. 그러나 이행·롤백 기록이 "reason" 한 줄로 줄고, 무엇이 breaking인지 리뷰어가 diff에서 직접 찾아야 한다. (D) 데이터 피해는 없지만 공개 URL·API 경로 변경이 조용히 들어간다 |
| 6. 현재 조건에서의 선택 | fail-closed 기준선 비교는 유지할 근거가 있다: 기록된 의도(`registry-compatibility.ts:92-95` 주석, `docs/operations/ci-quality-gates.md:67`)와 현재 동작이 맞고, 레지스트리가 11개라 손으로 하는 리뷰보다 싸다. 부족한 것은 증거의 연결과 분류의 정확도다. 확인한 조건에서는 (B)가 가장 작은 보강이다. "증거를 changeId만으로 묶은 이유"는 기록이 없다(미확인) |
| 7. 재검토 조건 | 레지스트리 스냅샷을 외부 소비자(백엔드, 다른 앱)가 읽게 되면 breaking 정의를 그 소비자 기준으로 다시 정한다. 다운스트림이 증거 대신 재승인만 쓰는 것이 계속 관찰되면 (C)로 줄이는 것을 다시 비교한다 |
### 4.2 zod를 `src/contracts/zod.ts` 한 곳으로만 가져오게 하는 규칙
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 운영 CSP(`unsafe-eval` 없음) 아래에서 zod의 `new Function("")` 시험이 `securitypolicyviolation`을 만들지 않게 한다 |
| 2. 지킬 성질 | 어떤 object schema도 `jitless` 설정 전에 만들어지지 않는다 |
| 3. 현재 보장 | 확인한 사실: `zod.ts:12`가 `z.config({ jitless: true })`를 부른다. zod 4.4.3은 jitless면 시험을 건너뛴다(`node_modules/zod/v4/core/util.js:145-150`). 규칙은 외부 모듈 이름을 import 문자열 그대로 비교한다(`scripts/check-architecture.ts:360-365`, 규칙 `^zod$` `.dependency-cruiser.json:59-70`). 실제 브라우저 검사가 있다(`tests/e2e/production-csp.spec.ts`). **보장하지 않는 것:** `"zod/v4"` 같은 subpath(Z1). 현재 번들은 `zod.ts` 본문을 zod 코드 바로 뒤, 같은 청크에 둔다(Z2). 그래서 규칙이 뚫려도 지금은 위반이 나지 않는다. 이 배치는 번들러의 선택이지 계약이 아니다 |
| 4. 현실적인 대안 | (A) 현 상태. (B) 규칙을 `^zod(/|$)`로 넓힌다. (C) 엔트리(`main.tsx`)에서 `globalThis.__zod_globalConfig`를 미리 만든다. (D) CSP에 `unsafe-eval` 허용. (E) `zod/mini`로 전환(JIT가 없어 시험 자체가 없다) |
| 5. 대안의 비용 | (B) 정규식 한 줄 + fixture 1개. (C) import 순서에 기대지 않지만 zod 내부 전역 이름에 의존한다. (D) 보안 약화라 제외. (E) API가 달라 모든 스키마 코드를 바꾼다 |
| 6. 선택 | 기록된 의도(`zod.ts:3-11` "the dependency, not import order … puts this first")와 맞는 것은 현 구조다. (B)로 빈틈만 막는다 |
| 7. 재검토 조건 | zod가 jitless를 기본으로 하거나 시험을 없애면 facade와 규칙을 지운다. 다운스트림이 `manualChunks`로 zod를 다른 청크에 떼면 e2e가 유일한 실측이다 |
### 4.3 `ENV_REGISTRY`를 zod 런타임 설정 스키마와 따로 손으로 둔다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | (a) 번들에 들어갈 수 있는 `VITE_*` 이름을 닫힌 목록으로 둔다(13-06). (b) 설정 키의 공개 범위(`public`, `public-sensitive`)와 필수 여부를 적는다 |
| 2. 지킬 성질 | 선언하지 않은 `VITE_*`는 빌드가 멈춘다. 레지스트리의 기본값·필수 여부는 실제 적용되는 값과 같다 |
| 3. 현재 보장 | build 행: `vite.config.ts:13-24`가 키 목록을 쓰고, `deployment-admission.test.ts:211-224`가 기본값을 `getBuildConfig`와 대조한다. **runtime 행: 읽는 실행 코드가 없다.** `phase`·`classification`·`required`는 governance 검사만 읽는다(grep). zod 스키마(`release-artifacts.ts:137-149`)와 다섯 곳이 다르다(V2) |
| 4. 현실적인 대안 | (A) 현 상태. (B) runtime 행을 zod 스키마와 대조하는 테스트 1개(build 행 테스트와 같은 모양). (C) runtime 행을 zod 스키마에서 생성. (D) runtime 행 삭제 |
| 5. 대안의 비용 | (B) 테스트 1개, 지금 틀린 값 5곳 수정. (C) 생성 코드와 FE-REG-ENV 기준선 재승인. (D) 행 11개 삭제가 각각 breaking 증거를 요구한다(07-01·07-04의 절차 비용이 그대로 나온다) |
| 6. 선택 | build 행은 현 상태 유지가 맞다: 실제 빌드 검사가 쓰고 불일치 검사가 있다. runtime 행은 (B)가 가장 작다 |
| 7. 재검토 조건 | `classification`을 실제로 읽는 코드(예: 텔레메트리 비식별, 설정 진단 출력)가 생기면 (C)로 옮겨 사본을 없앤다 |
## 5. 발견 사항 (36.3)
### 5.1 같은 사실의 사본과 불일치 검출 (39.5)
| 사실 | 사본 | 실제 소비자 | 불일치 검출 |
|---|---|---|---|
| 라우트의 스키마 id | 라우트 행, FE-REG-SCHEMA 행, governance `allowedValues` | 라우터·코덱 | 행 ↔ SCHEMA: `references` 검사. allowedValues: 새 사본이 늘 때마다 손으로 추가(07-03) |
| loading surface 이름 | 라우트 행, governance `allowedValues` | `data-surface` 속성뿐 | 닫힌 목록 자체가 검사. 보호하는 실행 동작 없음(07-03) |
| 런타임 설정 키·기본값·필수 | `ENV_REGISTRY` runtime 행, zod 필드, `RuntimeConfig` 타입과 V1 정규화 | zod와 타입 | zod ↔ 타입: 컴파일러. `ENV_REGISTRY` ↔ zod: **없음**, 이미 불일치(07-05) |
| build 변수 기본값 | `ENV_REGISTRY` build 행, `getBuildConfig` | `getBuildConfig` | 테스트 있음(`deployment-admission.test.ts:211-224`) |
| 런타임 설정 스키마 | zod, `config/compatibility/runtime-config.schema.baseline.json` | 부팅 파서 | 의도된 기준선 비교(FE-GATE-014) |
| 산출물 JSON Schema | zod, `schemas/artifacts/*.json` | CI·릴리스 스크립트 | 생성 + `check:artifact-schemas --check` |
| HTTP operation | V2 행(governance 대상), V3 descriptor(실행) | V3 | 일치 테스트 있음. 빈 V2 집합·V3 전용 operation·스키마 id는 안 본다(FOLLOW-UP 07-03) |
| breaking 변경의 설명 | 증거 행(changeId만) | `check:registries` | changeId 존재만. 값 연결 없음(07-01) |
| 오류 문구 키 | `ERROR_REGISTRY`(kind에서 생성), 카탈로그 ko·en | 화면 | 테스트 있음(`i18n-contract.test.ts:42`) |
### 07-01 breaking 증거가 값과 묶이지 않아, 같은 row·field의 다음 변경을 새 증거 없이 통과시킨다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (가드레일 누락 검출) |
| 관련 관점 | 17, 21, 10, 5, 9, 26 |
| 근거 | 증거 조회 키는 `registryId:rowName:field:kind`뿐이다(`scripts/lib/registry-compatibility.ts:83-90`, `:305-313`). 값(`before`·`after`)은 diff에 있지만(`:268-269`) 증거와 비교하지 않는다. 증거 검사는 5개 필드가 빈 문자열이 아닌지만 본다(`:317-330`). **실험 X3:** `REFERENCE_RESOURCE_DETAIL.path`를 08-13 증거가 설명하는 `/items/:resourceId`가 아닌 `/entries/:resourceId`로 바꿨다. `check-registries`는 `11 registries PASS`였다. **R1:** 증거 파일 15건 중 13건은 현재 diff의 어떤 changeId와도 맞지 않는다(예: `FE-REG-ERROR:QUERY_CACHE_FAILURE:telemetryEvent:field-changed`, 07-04 이후 그 필드는 없다). 오래된 행을 찾는 검사가 없다 |
| 발생 조건 | breaking 변경을 "재승인 대신 증거로 유지"한 뒤(`docs/operations/ci-quality-gates.md:67`가 안내하는 방식), 같은 row·field를 다시 바꿀 때. 오래된 행은 같은 이름의 row가 다시 생겼다가 바뀌거나 지워질 때 |
| 영향 | 공개 URL·API 경로·저장 키 같은 breaking 변경이 이행·롤백 계획 없이 게이트를 통과한다. 증거 문장은 이전 변경을 설명하므로 리뷰어도 오해한다. 템플릿의 현재 기준선이 바로 이 상태다(REFERENCE_RESOURCE_DETAIL) |
| 심각도·우선순위 | Medium · P2 — 코드 변경은 PR 리뷰를 거치므로 게이트가 유일한 방어는 아니다. 그러나 "breaking은 증거가 필요하다"는 게이트의 약속이 조용히 깨지고, 증거 파일은 두 다운스트림에 그대로 복제됐다 |
| 통제·증거 | 목표 M3 / 확인 M3(부분: 첫 변경만) · E2 (X3, R1) |
| 확실성과 남은 가정 | 재현했다. 다운스트림에서 실제로 두 번째 변경이 들어간 사례는 찾지 않았다 |
| 결정의 근거 | 확인한 사실: 위 근거. 기록된 의도: 재승인하지 않고 증거로 유지하는 경로를 문서가 안내한다(`ci-quality-gates.md:67`). 값과 묶지 않은 이유는 기록이 없다. 리뷰어 추론: 증거 행이 "이 변경"이 아니라 "이 칸의 모든 변경"을 허가하는 것은 의도와 다르다 |
| 이해 비용 | 리뷰어는 PASS를 보고 증거 파일을 열어 changeId를 찾고, 그 문장이 지금 diff를 설명하는지 직접 비교해야 한다. 출력(`compatibility=breaking`)은 이 비교를 돕지 않는다 |
| 최소 개선 방향 | (1) 증거 행에 `after`(canonical JSON)를 필수로 두고, diff의 `after`와 다르면 "증거가 다른 값을 설명함"으로 실패한다. (2) 현재 diff와 맞지 않는 증거 행이 있으면 실패하거나 목록으로 출력한다. (3) `update:registry-baseline`이 새 기준선으로 설명이 끝난 증거 행을 지운다 |
| 대안 비교 | 4.1절. (C) 증거를 없애고 재승인만 두면 이 결함은 사라지지만 이행·롤백 기록도 사라진다 |
| 단순화의 보존 조건 | 모르는 변경은 계속 breaking이다. 증거 5필드 요구는 유지한다 |
| 비용·부작용 | 스크립트 수십 줄. 기존 증거 2건에 `after` 추가, 오래된 13건 정리(삭제 또는 이력 파일로 이동). 두 다운스트림도 한 번 정리해야 한다 |
| 재검토 조건 | 4.1의 7번 |
| 완료 기준 | X3을 다시 하면 실패한다. 증거 파일에 현재 diff와 무관한 행이 있으면 실패한다 |
| 검증 방법 | `tests/fixtures/registry/compatibility/semantic-diff.json`에 "같은 changeId, 다른 after" 사례와 "오래된 증거" 사례 추가 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 07-02 레지스트리 분류기가 추가 성격의 변경(nullable 전환, allowlist 확장)을 breaking으로 막고, governance의 `breakingFields` 선언을 건너뛴다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (과잉 검출) |
| 관련 관점 | 17, 23, 24, 21, 20, 3 |
| 근거 | 값의 JS 타입이 다르면 `breakingFields`를 보기 전에 breaking이다(`scripts/lib/registry-compatibility.ts:237-239`). `null`과 문자열은 타입이 다르다(`:77-81`). governance는 이 필드들을 `string|null`로 선언하고(`config/contracts/registry-governance.json:38-39`) breaking 필드에서 뺐다(`:84-91`). contract 필드는 어떤 변경이든 breaking이다(`:157-172`). allowlist에 값을 더하는 것도 마찬가지다. **실험:** X1 라벨 이름 변경 → behavior-change, PASS. X2 같은 라벨을 `null`로(메뉴에서 숨김) → breaking 2건. X4 `loadingSurface` 허용값 1개 추가 → breaking. fixture에는 좁히기 사례만 있다(`semantic-diff.json`의 `registry-contract-narrowing`, `field-type-narrowing`). **실제 피해:** 템플릿 스스로 `VITE_BUILD_ID.defaultValue` null → `"local-build"`에 증거를 썼고, 그 증거는 "the value itself did not change"라고 적는다(`config/contracts/registry-change-evidence.json:109-115`). tech-log의 6건 중 2건이 이것이다(R2). memento는 allowlist 확장에 "The new allowed values are additive"라고 적은 breaking 증거를 썼다(D1) |
| 발생 조건 | nullable 필드(`navigationLabel`, `navigationOrder`, `paramsSchema`, `searchSchema`, API `timeoutMs`, 저장 `ttl`, ENV `defaultValue`)를 null ↔ 값으로 바꿀 때. governance의 allowlist에 값을 더할 때(새 기능 라우트마다, 07-03) |
| 영향 | 증거 5필드에 쓸 내용이 없는 변경에 "마이그레이션", "롤백"을 지어서 쓰게 한다. 그러면 증거 문장의 신호가 약해진다. 쓰지 않는 팀은 게이트를 빨간 채로 둔다(tech-log). 둘 다 07-01의 누락보다 더 흔하게 게이트를 무력하게 만든다 |
| 심각도·우선순위 | Medium · P2 — 데이터 피해는 없다. 흔한 변경마다 비용을 반복해서 만들고, 템플릿·두 다운스트림 모두에서 발생했다 |
| 통제·증거 | 목표 M3 / 확인 M3(과잉) · E2 (X1, X2, X4) · E3 (다운스트림 R2, D1) |
| 확실성과 남은 가정 | 재현했다. `searchSchema` null → 값은 이 수정 뒤에도 breaking이다(`breakingFields`에 있음). 그 선언이 맞는지는 제품 판단이다 |
| 결정의 근거 | 확인한 사실: fail-closed 기본값은 유지할 가치가 있다(4.1). 리뷰어 추론: 선언된 타입 안의 변화와 allowlist 확장은 "모르는 변경"이 아니라 governance가 이미 설명한 변경이다. 이 둘까지 fail-closed로 묶을 근거는 기록에 없다 |
| 이해 비용 | 기능 작성자는 라벨 이름 바꾸기와 숨기기의 등급이 왜 다른지 분류기 코드를 읽어야 안다 |
| 최소 개선 방향 | (1) 한쪽이 `null`이고 다른 쪽이 선언된 `fieldTypes`에 맞으면 `field-changed`로 보고 `breakingFields`로 등급을 정한다. (2) `$contract.allowedValues`가 필드별로 이전 값을 모두 포함하면 additive, 하나라도 빠지면 breaking. 나머지 contract 변경은 지금처럼 breaking. (3) 두 사례를 fixture에 추가한다 |
| 대안 비교 | (A) 현 상태 + "이런 변경은 재승인하라"는 문서: 코드 변경 없음, 대신 재승인이 증거를 대체하는 길을 더 넓힌다(07-04). (B) 위 개선: 분류 두 줄 + fixture. (C) nullable 필드를 모두 `breakingFields`에서 판단하도록 규칙 전체를 바꿈: 범위가 넓고 다른 레지스트리 영향을 다시 봐야 한다 |
| 단순화의 보존 조건 | 타입이 선언과 다른 변경, allowlist 축소, 모르는 contract 키 변경은 계속 breaking |
| 비용·부작용 | 스크립트 몇 줄, fixture 2개. 템플릿의 `VITE_BUILD_ID` 증거 행은 필요 없어진다 |
| 재검토 조건 | nullable 필드의 null이 "기능 꺼짐" 같은 의미를 갖게 되면 그 필드를 `breakingFields`에 넣는다 |
| 완료 기준 | X2·X4가 PASS(behavior-change / additive)다. `field-type-narrowing`, `registry-contract-narrowing` fixture는 계속 breaking이다 |
| 검증 방법 | 위 실험 재실행, `check:registries:compatibility-fixtures` |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 07-03 기능 라우트 하나를 추가해도 템플릿 소유 governance의 중앙 allowlist를 고쳐야 한다 — 문서는 고칠 필요가 없다고 한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (문서 약속과 실제 절차의 불일치) |
| 관련 관점 | 3, 20, 22, 25, 13, 30.3, 39.5 |
| 근거 | FE-REG-ROUTE governance가 `paramsSchema`·`searchSchema`·`loadingSurface`를 참조 기능 값까지 열거한 닫힌 목록으로 둔다(`config/contracts/registry-governance.json:42-60`). 검사기는 목록 밖 값을 `has unknown value`로 거부한다(`scripts/check-registries.ts:483`). 스키마 id는 이미 `references`가 FE-REG-SCHEMA와 대조한다(`registry-governance.json:61-77`). 그래서 allowlist는 같은 사실의 세 번째 사본이다. `loadingSurface`는 실행 코드에서 `data-surface` 속성으로만 쓰인다(`src/presentation/routes/app-router.tsx:78`). 문서는 "the registry governance file do not change"라고 적는다(`docs/architecture/starter-experience.md:145-147`). 이 약속을 고정하는 테스트는 라우트가 없는 기능만 쓴다(`tests/unit/second-api-feature-registries.test.ts:11-15, 38`). **실험 X5:** 참조 기능 라우트의 `loadingSurface`를 기능 전용 새 이름으로 → 실패. **다운스트림:** tech-log `has unknown value` 3건(R2), memento는 allowlist를 고치고 breaking 증거를 썼다(D1) |
| 발생 조건 | 새 기능이 자기 params/search 스키마나 자기 로딩 화면 이름을 가진 라우트를 추가할 때. 화면이 있는 기능은 대부분 해당한다 |
| 영향 | 기능 추가가 템플릿 파일 수정 + breaking 증거(07-02) 또는 재승인을 요구한다. 모든 기능 팀이 같은 JSON 목록을 고치므로 병합 충돌 지점이 된다. 템플릿 동기화 때마다 이 목록을 손으로 합친다 |
| 심각도·우선순위 | Medium · P2 — 기능 실패는 없다. 그러나 템플릿의 핵심 약속(기능 디렉터리만 고친다)을 대표 과제에서 깨고, 두 다운스트림 모두에서 발생했다 |
| 통제·증거 | 목표 M3(기능 로컬 추가를 테스트로 고정) / 확인 M0(라우트 있는 기능은 검증 안 됨, 문서는 반대로 적음) · E2 (X4, X5) · E3 (R2, D1) |
| 확실성과 남은 가정 | 확인했다. `errorSurface` allowlist는 라우터가 의미로 읽으므로(`app-router.tsx:116, 350`) 닫힌 목록이 맞다. 이 발견에서 뺀다 |
| 결정의 근거 | 확인한 사실: 위 근거. 기록된 의도: 없음. 참조 기능이 유일한 기능이던 때의 값이 남은 것으로 보인다(추론). 리뷰어 추론: 스키마 id 목록은 `references`로 충분하고, `loadingSurface`는 보호할 실행 동작이 없다 |
| 이해 비용 | 기능 작성자는 실패 메시지를 보고 governance JSON의 구조, allowlist가 contract의 일부라 breaking이라는 사실, 증거·재승인 절차까지 알아야 한다 |
| 최소 개선 방향 | (1) `paramsSchema`·`searchSchema`를 FE-REG-ROUTE `allowedValues`에서 뺀다(`references`가 남는다). (2) `loadingSurface`는 allowlist 대신 이름 형식만 본다(예: `fieldTypes`의 `string` + 정규식), 또는 목록을 없앤다. (3) 두 번째 기능 테스트에 search 스키마와 전용 loading surface를 가진 라우트 1개를 넣어 "governance 무수정"을 고정한다. (4) 문서가 이 테스트를 가리키게 한다 |
| 대안 비교 | (A) 현 상태 + 문서를 "allowlist를 고치고 증거를 쓴다"로 정정: 코드 비용 0, 기능마다 비용 반복. (B) 위 개선: governance 두 줄 삭제 + 테스트 확장. (C) 기능 계약이 자기 allowlist 값을 기여하게 하는 확장 메커니즘: 유연하지만 새 등록 규약이 하나 더 생긴다(39.10) |
| 단순화의 보존 조건 | 라우트가 등록되지 않은 스키마 id를 쓰면 계속 실패한다(`references`). `errorSurface`·`access`는 닫힌 목록을 유지한다 |
| 비용·부작용 | allowlist 축소는 contract 변경이라 템플릿 기준선을 한 번 재승인한다. 두 다운스트림은 다음 동기화에서 자기 allowlist 추가분을 지운다 |
| 재검토 조건 | `loadingSurface`가 로딩 컴포넌트 선택 같은 실행 의미를 갖게 되면 닫힌 목록을 다시 둔다(그때는 기능이 값을 기여하는 방식과 비교) |
| 완료 기준 | 자기 스키마·로딩 화면 이름을 가진 라우트를 기능 디렉터리만 고쳐 추가해도 `check:registries`가 PASS다 |
| 검증 방법 | 확장한 `second-api-feature-registries.test.ts`, X5 재실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 07-04 다운스트림이 breaking 증거를 남기는 절차가 안내되지 않고, 템플릿의 기준선·증거가 제품의 이력처럼 복제된다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 (다운스트림에서 비용 발생 확인) |
| 관련 관점 | 20, 17, 8, 26, 25, 30.3, 30.4 |
| 근거 | **안내:** 실패 메시지는 `breaking change missing evidence: <changeId>`뿐이다(`scripts/lib/registry-compatibility.ts:314`). 어느 파일, 어떤 5필드, 재승인이라는 대안을 말하지 않는다. 절차는 `docs/operations/ci-quality-gates.md:67` 표의 한 칸에만 있다. 계약 문서(`docs/contracts/compatibility.md`)는 레지스트리 증거를 다루지 않는다. **두 길의 차이:** `update:registry-baseline`은 `REGISTRY_BASELINE_OWNER`·`_REASON`만 요구하고, 그 순간의 breaking 변경에 증거를 요구하지 않는다(`scripts/update-registry-baseline.ts:10-18, 26-43`). 언제 어느 길을 쓰는지 기준이 없다. **첫 도입:** 템플릿의 `registry-baseline.json`·`approval.json`·`registry-change-evidence.json`은 템플릿 자신의 릴리스 이력이다. 제품이 복사한 뒤 처음 하는 이름 변경도 "템플릿 기준선 대비 breaking"이 된다. 기준선을 제품 것으로 다시 찍으라는 안내는 없다(docs grep). **세분도:** 증거는 changeId 하나에 행 하나라, 한 결정이 row 7개를 바꾸면 같은 문장을 7번 쓴다. **다운스트림:** memento는 저장 네임스페이스 변경에 "This repository had never been deployed … no origin holds data" 증거 7건을 복사해 썼다(D1, 동기화 기록 258행). tech-log는 두 번의 동기화 동안 게이트를 빨간 채로 두었고, 이번에는 두 승인 기준선을 row 단위로 3-way merge했다(동기화 기록 290-293행). 그 결과 `test:sample-removal`과 `second-api-feature-registries` 테스트도 같은 원인으로 막혔다(같은 기록 475-476행) |
| 발생 조건 | 템플릿을 복사한 직후 첫 커스터마이즈, 여러 row에 걸친 한 번의 결정, 템플릿 동기화 |
| 영향 | 증거가 의식(ritual)이 된다. "배포한 적 없음"을 롤백·이행 칸에 적는 문서가 쌓인다. 쓰지 않는 팀은 게이트를 끈 것과 같은 상태로 지낸다. 동기화마다 승인된 스냅샷을 손으로 병합한다 |
| 심각도·우선순위 | Medium · P2 — 데이터 피해는 없다. 두 다운스트림 모두에서 반복 비용과 게이트 무력화가 관찰됐다 |
| 통제·증거 | 목표 M2(절차 문서 + 안내하는 오류) / 확인 M1(표 한 칸) · E1 · E3 (두 다운스트림의 diff와 기록) |
| 확실성과 남은 가정 | 다운스트림 파일과 기록으로 확인했다. 두 팀이 절차를 몰라서인지, 알고도 비용 때문에 미뤘는지는 기록만으로 가를 수 없다 |
| 결정의 근거 | 확인한 사실: 위 근거. 기록된 의도: `ci-quality-gates.md:67`의 두 갈래 안내. 리뷰어 추론: 템플릿 저장소의 기준선·증거는 템플릿 제품의 이력이지 다운스트림의 이력이 아니다(30.3 "생성·복사 후 수정 권한") |
| 이해 비용 | 제품 개발자는 changeId 문법, 증거 5필드의 뜻, 재승인과의 차이, 동기화 때 어느 쪽 기준선을 남길지를 코드와 기록에서 찾아야 한다 |
| 최소 개선 방향 | (1) `docs/contracts/compatibility.md`에 "레지스트리 변경" 절: 증거와 재승인을 언제 쓰는지, 첫 도입 때 기준선을 제품 것으로 한 번 재승인하는 단계, 동기화 때 이 세 파일은 제품 소유라는 규칙. (2) 실패 메시지에 파일 경로·5필드·재승인 명령을 한 줄로 붙인다. (3) 증거 행이 `changeIds` 목록을 받게 해 한 결정에 행 하나로 쓴다 |
| 대안 비교 | (A) 현 상태. (B) 위 개선: 문서 1절 + 메시지 + 스크립트 몇 줄. (C) 기준선·증거를 템플릿 파일에서 빼고 첫 실행에 제품이 생성하게 함: 동기화 충돌은 사라지지만 템플릿 자신의 게이트 설정이 더 복잡해진다 |
| 단순화의 보존 조건 | breaking 변경은 계속 증거나 owner·reason이 남는 재승인 없이 통과하지 않는다 |
| 비용·부작용 | 문서 1절, 메시지 1줄, `changeIds` 지원 몇 줄 |
| 재검토 조건 | 07-01·07-02가 고쳐진 뒤에도 다운스트림이 증거 대신 재승인만 쓰면 4.1의 (C)를 다시 비교한다 |
| 완료 기준 | 처음 보는 사람이 실패 메시지와 문서만으로 증거를 쓰거나 재승인할 수 있다. 한 결정은 증거 행 하나로 기록된다 |
| 검증 방법 | 메시지 스냅샷 테스트, `changeIds` fixture. 다음 다운스트림 동기화 기록에서 증거 행 수·재승인 이유 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 07-05 `ENV_REGISTRY`의 런타임 설정 행이 zod 스키마와 따로 적혀 있고, 이미 기본값·필수 여부가 다르다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (선언과 실행의 불일치, 검출 없음) |
| 관련 관점 | 19, 23, 24, 9, 3, 39.5 |
| 근거 | runtime 행(`src/contracts/env.ts:50-62`)을 읽는 실행 코드는 없다. `phase`·`classification`·`required`는 governance 검사와 기준선만 읽는다(grep: `src`·`scripts`에 소비자 없음). 실제 설정 계약은 zod다(`src/contracts/release-artifacts.ts:137-149, 169-177`). **실험 V2(입력 기준 JSON Schema와 비교):** `TELEMETRY_ENABLED` 레지스트리 기본값 `false` / 스키마는 필수·기본값 없음. `AUTH_MODE` 기본값 `"external"` / 스키마는 필수·기본값 없음. `RELEASE_MANIFEST_URL` 필수 / 스키마는 선택·기본값 있음. `CAPABILITY_OVERRIDES`·`FEATURE_OVERRIDES` 기본값 `null` / 스키마는 객체 기본값. `BUILD_ID`·`RELEASE_ID`는 스키마에만 있다. **다운스트림(D1):** tech-log는 설정 키 2개를 `env.ts`, `release-artifacts.ts`, `runtime-config-schema.ts`(타입·V1 정규화)에 따로 적었다. 기본값 `"MOCK"`이 세 번 나온다 |
| 발생 조건 | 누가 `ENV_REGISTRY`를 설정 키 목록으로 믿을 때(이름이 그렇게 읽힌다). 설정 키를 추가·변경할 때 |
| 영향 | 프로필 파일에서 `AUTH_MODE`를 빼도 된다고 읽으면 빌드가 실패한다(fail-closed라 피해는 작다). FE-REG-ENV 게이트는 실행되지 않는 `required`를 바꿀 때 breaking 증거를 요구하고, 실제 스키마 변경은 따로 FE-GATE-014가 본다. 같은 사실을 두 게이트가 두 사본으로 감시한다 |
| 심각도·우선순위 | Low · P3 — 실제 설정은 zod가 fail-closed로 지킨다. 오해와 이중 관리 비용이 남는다 |
| 통제·증거 | 목표 M3 / 확인 M0(runtime 행 ↔ zod 대조 없음). build 행은 M3(`deployment-admission.test.ts:211-224`) · E2 (V2) |
| 확실성과 남은 가정 | 불일치는 실행으로 확인했다. 제품 설정 키를 넣을 확장 지점 문제는 영역 09의 09-02가 다룬다. 여기서는 사본 불일치만 센다 |
| 결정의 근거 | 4.3절 |
| 이해 비용 | 설정 키 하나에 네 곳을 맞춘다. 그중 하나는 아무도 대조하지 않는다 |
| 최소 개선 방향 | `deployment-admission.test.ts`의 build 기본값 테스트 옆에 runtime 행 테스트 1개: 키 집합, 필수 여부, 기본값을 `z.toJSONSchema(runtimeConfigV2ArtifactSchema, { io: "input" })`와 대조. 지금 틀린 5곳과 빠진 2개 키를 맞춘다 |
| 대안 비교 | 4.3절 (B)~(D). (D) 삭제는 07-01·07-04 때문에 행 11개의 breaking 증거가 필요해 지금은 가장 비싸다 |
| 단순화의 보존 조건 | `VITE_*` 선언 검사와 build 기본값 테스트는 그대로 둔다 |
| 비용·부작용 | 테스트 1개, 레지스트리 값 수정(FE-REG-ENV 기준선 재승인 1회) |
| 재검토 조건 | 4.3의 7번 |
| 완료 기준 | runtime 행과 zod가 다르면 테스트가 실패한다 |
| 검증 방법 | 새 테스트 실행. `AUTH_MODE` 기본값을 다시 `"external"`로 둔 변이로 실패 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 07-06 zod facade 규칙이 정확히 `"zod"`만 막아서 `"zod/v4"` import가 검사를 통과한다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 (가드레일 빈틈 확인, 피해는 재현 안 됨) |
| 관련 관점 | 15, 21, 10 |
| 근거 | 규칙 `to.path`가 `^zod$`다(`.dependency-cruiser.json:67-69`). 검사기는 외부 모듈의 대상을 import 문자열 그대로 둔다(`scripts/check-architecture.ts:360-365`). zod 4.4.3은 `./v4`, `./v4/core`, `./mini`, `./v3` 등을 export한다. `zod/v4`는 `zod`와 같은 classic 구현이고 JIT object schema를 만든다(`node_modules/zod/v4/classic/schemas.js:737`). **Z1:** `"zod/v4"` import는 `check:architecture` PASS. 회귀 fixture는 `"zod"`만 시험한다(`check-architecture.ts:924-938`). **Z2:** 현재 번들은 `zod.ts`의 설정 호출을 zod 코드 바로 뒤 같은 청크에 두어, 두 위치의 변이 모두 CSP 위반이 나지 않았다. 같은 모양의 규칙: `icon-vendor-is-facade-only`의 `^lucide-react$`(영역 08·12 판단) |
| 발생 조건 | 다운스트림이 zod v4 문서를 따라 `import { z } from "zod/v4"`를 쓰고, 번들러가 그 모듈을 `zod.ts`보다 먼저 평가하는 청크 배치를 만들 때(예: `manualChunks` 변경) |
| 영향 | 운영에서 부팅마다 CSP 위반 보고가 난다(13-08이 고친 증상). 기능 동작은 같다(zod가 거부를 잡는다) |
| 심각도·우선순위 | Low · P3 — 현재 번들에서 재현되지 않았고, e2e가 실제 위반을 잡는다 |
| 통제·증거 | 목표 M3 / 확인 M3(부분: 정확한 이름만) · E2 (Z1) · E3 (Z2, chromium만) |
| 확실성과 남은 가정 | 규칙 빈틈은 확인했다. 위반이 나는 청크 배치는 만들지 못했다 |
| 결정의 근거 | 4.2절. 적용 제외 — 선택은 유지하고 정규식만 고친다 |
| 이해 비용 | 적음 |
| 최소 개선 방향 | `to.path`를 `^zod(/|$)`로 바꾸고, `"zod/v4"`를 import하는 fixture 1개를 `check-architecture.ts` 회귀 목록에 추가 |
| 대안 비교 | 적용 제외 — 기대 계약(모든 zod 접근은 facade 경유)이 이미 정해져 있다 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 정규식 1줄, fixture 1개 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | Z1이 `zod-is-reached-through-contracts-zod` 위반으로 실패한다 |
| 검증 방법 | Z1 재실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 07-07 CHANGELOG 0.2.0의 [계약] 행이 바뀌지 않은 레지스트리 분류기와 경로를 가리킨다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (문서) |
| 관련 관점 | 24, 9, 17, 30.4 |
| 근거 | `CHANGELOG.md:45`는 "레지스트리 호환성 분류기가 모르는 스키마 변경을 breaking으로 본다"고 적고 영향 경로를 `src/contracts/compatibility.ts`, `scripts/check-registries.ts`, `config/contracts/`로 든다. 커밋 `17d617a`가 바꾼 것은 `classifyObjectSchemaChange`(런타임 설정 스키마)와 `scripts/check-compatibility.ts`, `config/compatibility/`다(G1). 레지스트리 분류기 `scripts/lib/registry-compatibility.ts`는 최초 커밋 이후 바뀐 적이 없다 |
| 발생 조건 | 다운스트림이 CHANGELOG로 동기화 영향을 판단할 때(CHANGELOG 3행이 그 용도라고 적는다) |
| 영향 | 제품 팀과 리뷰어가 레지스트리 게이트의 기존 실패를 이 변경 탓으로 돌린다. 실제로 이번 라운드 검증 후보도 그렇게 적혔다. 반대로 FE-GATE-014 기준선(`config/compatibility/runtime-config.schema.baseline.json`)을 갱신해야 한다는 사실은 이 행에서 찾기 어렵다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M1 · E1 (G1) |
| 확실성과 남은 가정 | 확인했다 |
| 결정의 근거 | 적용 제외 — 선택 비교가 필요 없는 문서 오류다 |
| 이해 비용 | 적음 |
| 최소 개선 방향 | 행을 "런타임 설정 스키마 분류기가 … FE-GATE-014가 커밋된 기준선과 비교한다"로 고치고 경로를 `scripts/check-compatibility.ts`, `config/compatibility/`로 바꾼다. "레지스트리 분류기는 바뀌지 않았다"를 한 줄 덧붙인다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 문서 1행 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 행의 경로가 `git show --stat 17d617a`와 맞다 |
| 검증 방법 | G1 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
## 6. FOLLOW-UP 재확인
| 항목 | 결과 | 근거 |
|---|---|---|
| P2 07-03 — V2 행이 없어도 V2/V3 일치 테스트가 통과하고, V3에만 있는 operation을 보지 않는다 | **유효** | `tests/unit/http-operation-v2-v3-parity.test.ts:26-54`는 V2 행에서 V3를 찾는 한 방향 루프다. V2 행 수가 0이어도 단언이 없다. 추가로, FE-REG-API의 breaking 필드인 `requestSchema`·`responseSchema`(`registry-governance.json:199` 블록)는 비교 목록에 없다. V3 validator의 스키마 id를 바꿔도 이 테스트와 governance 모두 모른다(코드 읽기, E1) |
| P3 07-07 — `no-deprecated` lint를 켜지 않았다 | **유효** | `eslint.config.ts`에 `deprecated` 규칙 없음(grep). 폐기 별칭 사용처: `ApiFailure` 8파일, `MappingResult`(boundary-mapper) 6파일. 주석의 제거 조건은 "다음 minor"(`errors.ts:139-141`, `boundary-mapper.ts:20-22`) |
지난 라운드에 닫힌 이 영역 발견의 회귀 확인:
| ID | 결과 | 근거 |
|---|---|---|
| 07-01 오류 문구 누락 | 회귀 없음 | `tests/unit/i18n-contract.test.ts:42`가 `ERROR_REGISTRY` 전체를 두 카탈로그와 대조 |
| 07-02 분류기 "none" | 회귀 없음 (런타임 설정 분류기 기준) | `compatibility.ts:110-144` fail-closed. 레지스트리 분류기의 과잉 판정은 이번 07-02로 따로 적었다 |
| 07-04 읽지 않는 오류 레지스트리 필드 | 회귀 없음 | 필드 4개만 남음(`errors.ts:22-27`). M1 killed |
| 07-05 diagnostics fixture | 회귀 없음 | 위반마다 `@ts-expect-error`(`tests/fixtures/typecheck/invalid-diagnostics-port.ts:10, 16, 19`) |
| 07-06 `invokeValidator` | 회귀 없음 | 결과 읽기가 try 안(`external-contract-runtime.ts:76-101`) |
## 7. 미검증 목록
| 무엇 | 왜 못 했나 | 무엇이 있으면 확인할 수 있나 |
|---|---|---|
| `zod/v4` 우회가 실제 CSP 위반으로 이어지는 청크 배치 | 두 위치의 변이 모두 같은 청크 배치라 재현되지 않았다. 제품 빌드(tech-log `manualChunks`)는 하지 않았다 | tech-log 브랜치를 풀어 `zod/v4` 변이로 빌드하고 CSP spec 실행 |
| firefox·webkit에서의 CSP spec | chromium만 돌렸다(동시 실행 중인 다른 영역과 포트·부하 충돌 회피) | 세 엔진 프로젝트로 Z2 재실행 |
| 07-01의 두 번째 변경이 다운스트림에서 실제로 들어간 사례 | 두 제품의 git 이력을 changeId별로 추적하지 않았다 | 두 제품에서 증거 행별로 `git log -S '<changeId>'`와 해당 row 값 이력 대조 |
| 07-04의 원인(절차를 몰랐는지, 비용 때문에 미뤘는지) | 동기화 기록만으로는 가를 수 없다 | 제품 담당자 확인 |
| memento의 `check:registries` 현재 출력 | 직접 실행하지 않고 기록(`PASS, compatibility=breaking`)을 읽었다 | memento 브랜치를 풀어 실행 |
| 줄 단위로 읽지 않은 contracts 파일(`browser-rpc.ts`, `realtime-streams.ts`, `query-keys.ts`, `server-state.ts`, `service-worker*.ts`, `web-worker.ts`, `web-push.ts`, `cache-invalidation.ts`, `query-invalidation.ts`) | 이번 라운드 깊게 볼 관점(레지스트리·설정·계약 절차)에 시간을 썼다 | 해당 파일의 경계 검증식 읽기와 변이 실험 |
| HTTP 응답 DTO 형태의 구·신 버전 공존 | 게이트가 다루지 않는 범위다(외부 계약 패키지 책임). 브라우저 공존 실험은 하지 않았다 | 구 번들 탭에 필드가 바뀐 응답을 주는 Playwright 시나리오 |
@@ -0,0 +1,412 @@
# 08 presentation 성숙도 리뷰
> 검토일: 2026-09-29 · 기준: `main` / `af3d8e6` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`(워킹트리 판)
> 깊게 본 관점: 4, 5, 8, 14, 15, 23, 24 · 추가로 읽은 절: 29, 32(특히 32.1, 32.3), 34~36, 39, 41
## 0. 머리말
### 0.1 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 | `clean-architecture-frontend-template`, `main` / `af3d8e6`. 워킹트리의 미커밋 변경은 리뷰 가이드 문서 2개뿐이다. 코드는 커밋과 같다 |
| 목적·실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음 |
| 영역 경로 | `src/presentation/`(routes, layouts, pages, forms, design-system, i18n, boundaries, components, adapters/query), 샘플 화면 `src/features/reference-feature/presentation/`, 관련 component·e2e 테스트, `scripts/check-i18n.ts`, `config/hosting/security-headers.json` |
| 읽은 코드 | `src/presentation/` 중 routes 전부, forms 전부, components 전부, boundaries 전부, i18n 전부, `layouts/app-shell.tsx`, `providers/session-provider.tsx`, `security/safe-text.tsx`, `styles/theme.css`, `adapters/query/application-query.ts`(폼·재전송 경로 440~770행). 샘플 화면 8파일과 `reference-message-catalog.ts`, `reference-feature-contract.ts`. 연결 확인용으로 `src/contracts/errors.ts`, `src/contracts/routes.ts`, `src/platform/errors/*.tsx`, `src/features/installed-feature-messages.ts`, `src/application/create-application.ts:55-85`, `src/application/ports/auth-session-port.ts` |
| 읽은 문서 | VD-06, `docs/security/browser-boundary.md`, `docs/architecture/optional-adapter-recipes.md` 4절, `docs/architecture/routing-pages-and-patterns.md`, `docs/architecture/starter-experience.md`, `docs/styling/design-system-platform.md`, `CHANGELOG.md` 0.2.0, 지난 리뷰 `08-presentation.md`·`README.md` 11절·`FOLLOW-UP.md` |
| 제품 증거 | `../memento-frontend`, `../tech-log-frontend`의 `chore/template-sync-v0.2.0`을 `git show`·`git archive`로만 읽었다. 동기화 기록 `docs/operations/template-sync-2026-09-29.md` 두 개 |
| 이전 리뷰와 비교 | 지난 08-01~08-13은 현재 코드에서 다시 확인했다(6절). 지난 실행 결과는 증거로 쓰지 않았다 |
### 0.2 실행한 명령과 실험
실험은 분리 worktree(`git worktree add --detach … af3d8e6`, 메인 `node_modules` 링크)에서 했고, 끝난 뒤 지웠다. 빌드는 `corepack pnpm build` 대신 `node scripts/build-frontend.ts`로 직접 돌렸다. 처음 한 번 `corepack pnpm build`를 부르자 pnpm이 링크된 `node_modules`를 다시 설치하려다 `ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY`로 멈췄다. 아무것도 지우지 않았고, 메인 `node_modules`는 그대로다. Playwright는 다른 에이전트와 겹치지 않게 전용 설정(chromium 한 개, 포트 4291, `npx vite preview`)으로 돌렸다.
| ID | 명령·실험 | 결과 |
|---|---|---|
| R1 | `node scripts/run-vitest.ts run` form-foundation, async-surface, route-status-surfaces, router, chunk-recovery-boundary, render-boundary, locale-platform, page-header-focus, context-route-gateway, pagination, app-shell, reference-page | 12 files / 113 tests 통과 |
| R2 | 빌드 후 Playwright chromium: scroll-restoration, reference-form, reference-save, reference-route, production-csp, i18n | 18/18 통과 |
| R3 | `node scripts/generate-supply-chain.ts && node scripts/check-bundle.ts` | PASS, 초기 JS 203,481 / 204,800 gzip bytes |
| E1 | 변이: 샘플 목록 화면에 한글 주석 한 줄만 추가 → `node scripts/check-i18n.ts` | **실패**(`hardcoded common user-facing locale literal`) |
| E1b | 변이: 같은 파일에 영어 JSX 문구 `<p>Nothing selected yet</p>` 추가 | **통과**(214 keys PASS) |
| E2 | memento 브랜치를 `git archive`로 scratchpad에 풀고 템플릿의 `scripts/check-i18n.ts` 실행 | 21 files 실패(`memento-demo-model.ts`, stories 파일 포함) |
| E3 | 변이: 샘플 기능 catalog에서 `en-US`를 지우고 `tsc -p tsconfig.app.json` | `src/presentation/i18n/catalog.ts(400,6): error TS7053` |
| E4 | probe: `formatMessage("ko-KR", "reference.list.resultCount")`와 `{ count: 1 }`를 넣은 호출을 타입 검사·실행 | 파라미터 없는 호출은 **통과**하고 실행 시 "요청한 문구를 표시할 수 없습니다."를 반환. 파라미터를 넣은 호출은 **TS2345** |
| E5 | component probe: `requestId`가 있는 같은 실패를 `AsyncSurface`와 `FormFailureStatus`에 넣음 | 조회 화면은 `req-123` 표시, 폼 화면은 표시 안 함 |
| E6 | 브라우저 probe(chromium): 목록 500·저장 500에 `x-correlation-id`를 붙여 응답, `Access-Control-Expose-Headers` 유무 비교. 저장 응답 유실(`connectionreset`) 뒤 "같은 요청으로 다시 보내기" | 목록: expose 없으면 지원 참조 없음, 있으면 "지원 참조: corr-list-500". 저장 500: expose와 무관하게 결과 불명 화면에 식별자 없음. 재전송: 두 요청의 `Idempotency-Key`가 같고 "저장했습니다." |
| E7 | component probe: context 라우트 모듈이 청크 오류가 아닌 `ReferenceError`로 실패 | 화면은 "지원 참조: build-x"(incident 없음). `ui.render.failed` 진단 0건 |
| E8 | 변이: 샘플 catalog에서 `route.REFERENCE_RESOURCE_LIST.title`·`.navigation`을 두 locale 모두 삭제 → `check-i18n`, `tsc`, 관련 테스트 20 files | 전부 통과(변이 생존) |
| E9 | 변이: `theme.css` 첫 줄에 jsdelivr Pretendard `@import` 추가 → 빌드 → `production-csp.spec.ts` | 실패. `style-src-elem https://cdn.jsdelivr.net/…` 위반 검출 |
| E10 | 변이: 샘플 상세 화면에 `dangerouslySetInnerHTML` 추가 → `npx eslint` | `FE-OC-019` 오류로 검출 |
| E11 | component probe: `AppRouter basename="/app"`, URL `/app/fixture/items?x=1#results`에서 "로그인 시작" | `beginSignIn("/fixture/items?x=1#results")`. base path가 빠진다 |
### 0.3 확인하지 못한 범위
- Playwright는 chromium만 돌렸다. firefox·webkit, visual, storybook은 돌리지 않았다.
- 실제 스크린리더와 수동 접근성 검토. 기록 10건이 여전히 `pending-manual-review`다(U-2).
- 실제 외부 세션 owner. 두 제품 모두 `returnTo`로 리다이렉트하는 owner가 없다.
- 운영 호스팅이 실제로 보내는 CSP. e2e는 preview 응답에 헤더를 붙여 흉내 낸다.
- HTTP 상태 → 실패 종류·effect 분류(영역 03). 7절에 이 전제에 걸린 시나리오를 적었다.
## 1. 결론
- **조회·폼·결과 불명 흐름은 CHANGELOG 주장대로 동작한다.** 폼 저장 실패는 재로그인·권한 없음·나중에 재시도·사용 불가로 나뉜다(R1, R2의 429 재시도). 응답을 잃은 저장은 같은 멱등 키로 다시 보낸다(E6). 뒤로 가기 스크롤과 해시 이동도 브라우저에서 확인했다(R2).
- **i18n은 "한국어 + 영어"를 전제로 고정돼 있어, 두 제품이 모두 막혔다.** 제품이 지원 locale을 선언할 곳이 없다(08-01). `check:i18n`은 "파일에 한글이 있는가"만 본다. 그래서 주석은 걸고 영어 문구는 놓친다(08-02). memento에서는 merge 단계 게이트 FE-GATE-010에 속한 `check:i18n`이 실패하고, tech-log는 검사 스크립트를 고쳐 썼다.
- **기능 문구의 보간 파라미터가 타입 계약에 없다(08-03).** 타입 있는 `message()`가 틀린 호출을 통과시키고 맞는 호출을 거절한다. 샘플은 타입 없는 resolver로 우회하고, tech-log는 템플릿 파일에 11개 키를 넣었다.
- **지원 참조는 조회·라우트·청크 실패에만 붙었다.** 폼 저장 실패와 결과 불명 화면에는 식별자가 없다(08-04). context 라우트 모듈이 청크 오류가 아닌 이유로 실패하면 진단 이벤트도 남지 않는다(08-05).
- 운영 CSP는 외부 폰트를 제대로 막고 e2e가 이를 잡는다(E9). 다만 폰트·전역 스타일을 넣는 자리와 방법이 문서에 없다(08-07).
- 판정표에 X(미충족)는 없다. High 이상 발견은 없다.
## 2. 대표 흐름 (체크리스트 2절)
### 2.1 정상 흐름 — 보호 목록 진입과 언어 전환
| 단계 | 내용 | 위치 |
|---|---|---|
| 입력 | URL `/examples/reference-resources?limit=20` | — |
| 정책 | context 라우트 경로 선언 → (생성 인덱스) → 기능의 `context-routes.ts` → gateway가 leaf 하나를 고른다. 보호 라우트는 세션이 없으면 로그인 안내를 보인다 | `src/contexts/reference-context/context-module.ts:9`, `src/features/reference-feature/context-routes.ts:6-19`, `src/presentation/routes/app-router.tsx:435-528`, `:231-290` |
| 상태 변화 | route codec이 search를 파싱한다. 조회 결과는 세션 세대별 QueryClient에 들어간다 | `app-router.tsx:347-348`, `src/features/reference-feature/presentation/use-reference-feature.ts:116-147` |
| 외부 I/O | `GET /api/reference-resources` | `use-reference-feature.ts:133-134` |
| 실패 | 500 → `TerminalErrorSurface` + "다시 시도". `x-correlation-id`를 CORS로 노출하면 "지원 참조"가 붙는다(E6). 권한·인증·없음은 디자인 시스템의 `AccessSurface` 계열로 그린다 | `src/presentation/components/async-surface.tsx:138-168` |
| 결과 | 결과 수는 success·empty일 때만 보인다. 언어를 바꾸면 `<html lang/dir>`과 catalog 문구가 바뀐다 | `reference-resource-page.tsx:46-55`, `src/presentation/layouts/app-shell.tsx:93-107`, `src/presentation/i18n/locale-provider.tsx:89-92` |
관찰: ko-KR 화면의 h1은 코드에 박힌 영어 "Reference feature"다(`reference-resource-page.tsx:25`). 문서 제목은 catalog의 "Reference resources"라서 둘이 다르다(08-06). 필터 문구 `limit 20`과 목록의 접근성 이름 `Reference resources`도 코드에 박혀 있다(`:37`, `:62`). `check:i18n`은 이것을 보지 못한다(08-02).
### 2.2 피해가 큰 흐름 — 응답을 잃은 저장
| 단계 | 내용 | 위치 |
|---|---|---|
| 입력 | 폼 제출 | `src/features/reference-feature/presentation/reference-resource-form-page.tsx:58-68` |
| 정책 | zod 검증 → 제출 하나를 검증부터 결과까지 묶는다(`pendingRef`). 결과를 모르는 제출이 남아 있으면 새 제출을 막는다 | `src/presentation/forms/use-app-form.ts:299-313` |
| 상태 변화 | mutation admission을 만들고 intent·멱등 키를 붙인다. 같은 canonical 입력의 결과 불명 admission이 있으면 그 intent를 다시 쓴다 | `src/presentation/adapters/query/application-query.ts:502-545` |
| 외부 I/O | `POST /api/reference-resources` + `Idempotency-Key` | — |
| 실패 | 연결 끊김·500 → `MAYBE_APPLIED` → admission `UNKNOWN` → 폼 `effect-unknown`. 화면은 "변경됨으로 확인", "같은 요청으로 다시 보내기", "목록을 새로 불러와 확인"을 준다 | `application-query.ts:601-613`, `use-app-form.ts:221-224`, `reference-resource-form-page.tsx:146-171` |
| 결과 | 재전송은 원래 입력과 같은 키로 나가고 성공하면 "저장했습니다."(E6: 키 두 개가 같음) | `application-query.ts:736-748`, `use-app-form.ts:321-344` |
빈틈: 이 화면에는 문의 식별자가 없다. 서버 500에 `x-correlation-id`를 노출해도 마찬가지다(08-04). 재로그인이 필요한 결과 불명은 확인하지 못했다(7절).
### 2.3 변경 흐름 — 제품이 기능 화면을 얹는다
같은 과제를 두 제품이 실제로 했다. 템플릿 소유 presentation 파일을 얼마나 고쳤는지 `af3d8e6`과 제품 브랜치의 diff 줄 수(`<`·`>` 줄 합)로 쟀다.
| 제품이 한 일 | 필요한 수정 | memento | tech-log | 관련 |
|---|---|---|---|---|
| 한국어 전용 화면 | catalog에 en-US를 만들거나 검사를 고침 | `check:i18n` 실패 21 files(E2), 미해결 | `scripts/check-i18n.ts` 30줄 | 08-01, 08-02 |
| 보간이 있는 기능 문구 | 플랫폼 `MessageParameters`에 키 추가 | 0 | `message-contract.ts` 13줄(키 11개) | 08-03 |
| 제품 폰트 | `theme.css` 또는 `main.tsx`에 import | `theme.css` +2(jsdelivr CDN → 운영 CSP 차단) | `main.tsx` 7줄(npm 패키지 자기 호스팅) | 08-07 |
| 제품 셸·레이아웃 | `app-router.tsx` 수정 | 145줄 | 574줄 | > 09-03 |
결과: 두 제품 모두 템플릿 소유 파일을 고쳤다. 템플릿이 이 파일들을 바꾸면 동기화마다 손 병합이 생긴다(memento 기록은 라우터 충돌을 "the substantive one"이라고 적었다).
## 3. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 굵은 번호가 깊게 본 관점이다.
| 번호 | 관점 | 판정 | 목표·확인 통제 | 증거 | 이유·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | P | M4 / M4(폼 결과 상태·AsyncState가 닫힌 union) | E2 | 폼 결과는 `FormResultState` union이다(`form-contracts.ts:16-26`). 타입 있는 `message()`가 파라미터 누락을 허용한다(08-03). 샘플은 search를 `as ReferenceListFilters`로 단언한다(`use-reference-feature.ts:120`) |
| 2 | 구조적 성숙도 | O | M3 / M3 | E3 | presentation 레이어 규칙은 ESLint가 강제한다. `check:architecture` 통과(오케스트레이터). FE-OC-019 변이가 검출됐다(E10) |
| 3 | 변경 용이성 | P | M3 / M1~M3 | E3 | 오류 종류 추가는 `tests/unit/i18n-contract.test.ts:41`이 잡는다. locale 추가·제거(08-01), 기능 문구 파라미터(08-03), 라우트 제목(08-06)은 템플릿 파일 수정이나 수동 맞춤이 필요하다 |
| **4** | 인지 부하 | P | — | E1 | 3.1 참고. 지난 라운드의 막힘 4개 중 2개가 줄었다. 새로 라우트 제목 세 곳(08-06), 파라미터 문구의 우회 경로(08-03)가 생겼다 |
| **5** | 위험 가시성 | P | M2 / M2 | E3 | 결과 불명 화면은 확인 경로와 "NOT_APPLIED는 근거가 필요"를 prop 주석으로 드러낸다(`async-surface.tsx:118-121`). `resendUnknown`도 같은 키 재사용을 적는다(`use-app-form.ts:315-320`). 반면 `message()`는 파라미터 누락을 조용히 대체 문구로 바꾼다(E4, 08-03). `beginSignIn(returnTo)`의 경로 의미는 계약에 없다(08-08) |
| 6 | 실패 성숙도 | P | M2 / M2 | E3 | 폼 실패 5종 분리(R1, R2 429 재시도), 결과 불명 재전송 같은 키(E6). context 라우트 모듈의 비청크 실패는 기록 없이 화면만 바뀐다(08-05) |
| 7 | 운영 성숙도 | > | — | — | 영역 09·13 |
| **8** | 디버깅 가능성 | P | M3 / M3(조회·라우트·청크), M0(폼·결과 불명·context 경계) | E3 | 라우트 렌더 실패·청크 실패는 화면의 `build:incident`와 진단 `correlation_id`가 같다(`tests/component/render-boundary.test.tsx:73-77`, `chunk-recovery-boundary.test.tsx:163-167`). 조회 실패는 서버가 헤더를 노출하면 `requestId`를 보인다(E6). 폼 저장 실패·결과 불명 화면은 식별자가 없다(E5, E6, 08-04). context·feature 경계와 비청크 모듈 실패는 진단이 없다(E7, 08-05) |
| 9 | 유지보수 성숙도 | P | — | E1 | locale 목록이 네 곳에 있다(08-01). 라우트 제목이 세 곳에 있다(08-06) |
| 10 | 테스트 성숙도 | P | M3 / M3 일부 | E3 | 검출된 변이: FE-OC-019(E10), CDN 폰트(E9), 한글 literal. 살아남은 변이: 라우트 문구 삭제(E8), 영어 문구(E1b). 폼·결과 불명의 지원 참조, context 비청크 실패 보고는 테스트가 없다. en-US 브라우저 검사는 목록·폼만 본다(FOLLOW-UP 08-04) |
| 11 | 데이터 성숙도 | - | — | E2 | presentation은 저장을 소유하지 않는다. 폼 값은 URL·storage에 남지 않는다(`form-foundation.test.tsx:239`) |
| 12 | 동시성 성숙도 | O | M3 / M3(화면 쪽) | E3 | 중복 제출 차단(`use-app-form.ts:302-305`), 결과 불명 뒤 같은 키(E6), 세션 세대 fence. application-query 내부 경쟁은 영역 03. 재로그인+결과 불명 조합은 미검증(7절) |
| 13 | 확장성 | > | — | — | 영역 09·11. 문구 catalog가 설치 기능 수만큼 초기 청크에 쌓이는 점은 14번에 적었다 |
| **14** | 성능 성숙도 | P | M3 / M3(예산 게이트) | E2 | 페이지 14개가 lazy 청크다(빌드 출력). `check:bundle` PASS, 여유 1,319 bytes(R3). 초기 청크 `design-system-*.js`(66 KB gzip)에 디자인 시스템 barrel 전체, 라우터, 모든 locale의 플랫폼·기능 문구가 들어 있다(빌드 청크에서 문구 문자열 확인). 샘플 기능 catalog 하나의 소스 gzip이 약 1.6 KB로, 남은 여유보다 크다(소스 기준 추정). FOLLOW-UP P1과 연결된다 |
| **15** | 보안 성숙도 | P | M3 / M3 | E3 | raw HTML은 ESLint가 막는다(E10). 운영 CSP로 부팅·이동하는 e2e가 통과하고(R2), CDN 스타일 주입을 잡는다(E9). 폰트·스타일을 CSP에 맞게 넣는 안내가 없다(08-07). 로그인 복귀 경로 의미가 계약에 없다(08-08). 서버 인가는 범위 밖 |
| 16 | 의존성 성숙도 | > | — | — | 영역 13 |
| 17 | API / Contract 성숙도 | P | M3 / M2 | E3 | route codec 파싱 뒤에만 입력을 쓴다(`app-router.tsx:347-348`). 기능 문구 파라미터 계약이 없다(08-03). `returnTo`가 라우터 기준인지 문서 경로인지 정하지 않았다(08-08) |
| 18 | 배포 성숙도 | O | M3 / M3(화면 쪽) | E2 | 라우트 청크·context 모듈 청크 실패가 reload-once 복구로 간다(`context-route-gateway.test.tsx:98`, R1). 구 탭 e2e는 이번에 돌리지 않았다 |
| 19 | 설정 성숙도 | P | M2 / M2 | E3 | `routerBasePath`는 링크에 반영된다(`route-status-surfaces.test.tsx:140`). 로그인 복귀 주소에는 반영되지 않는다(E11, 08-08). 제품이 locale을 설정할 수 없다(08-01) |
| 20 | 개발자 경험 | P | — | E3 | 2.3의 표. 두 제품이 i18n·폰트·라우터 때문에 템플릿 파일을 고쳤다 |
| 21 | Guardrail 성숙도 | P | M3 / M3(FE-OC-019, CSP e2e), M1(i18n 정밀도, 라우트 문구) | E3 | `check:i18n`의 거짓 양성·거짓 음성(E1, E1b, 08-02). 라우트 문구 누락 무검출(E8, 08-06) |
| 22 | 추상화 성숙도 | O | — | E1 | `FormFailureStatus`가 `TerminalErrorSurface`를 재사용하고, 조회 실패가 `AccessSurface` 계열을 쓴다(`async-surface.tsx:138-155`). 페이지 템플릿은 데이터를 가져오지 않고 슬롯만 가진다. `application-query.ts` 925줄의 bound/legacy 겸용은 학습 비용이 크다(관찰) |
| **23** | 일관성 | P | — | E3 | 같은 실패 화면인데 조회는 식별자를 보이고 폼은 보이지 않는다(E5, 08-04). 라우트 제목 세 곳이 서로 다르다(08-06). ko-KR 화면에 영어 문구가 섞인다(08-02). 샘플 상세의 날짜는 VD-06 결정 6의 UTC 기본값으로 보인다(`reference-resource-detail-page.tsx:37-39`). 기록된 결정이라 발견으로 올리지 않았다 |
| **24** | 네이밍 / 의미 성숙도 | P | — | E3 | `check:i18n`의 실패 문구 "hardcoded common user-facing locale literal"과 주석 "must take its words from the catalog"가 실제 규칙(한글 유무)보다 넓다(08-02). 샘플 지원 안내가 고정 문자열 `REFERENCE-STATUS-DEMO`를 "지원 참조"로 보인다(08-04). `FormResultState`의 `retry-later`는 `retryAfterMs`를 쓰지 않고 버튼이 바로 다시 보낸다(`reference-resource-form-page.tsx:140-143`, 관찰). `MessageKey` 타입이 파라미터까지 보장하는 것처럼 보인다(08-03) |
| 25 | 조직 확장성 | P | — | E1 | 기능 문구 catalog는 기능마다 나뉜다. 파라미터 타입(`MessageParameters`)과 locale 목록은 중앙 파일이라 여러 팀이 같은 파일을 고친다(08-01, 08-03) |
| 26 | Ownership 성숙도 | ? | — | E1 | 수동 접근성 기록 10건이 모두 `pending-manual-review`다(`artifacts/tests/a11y-manual/`). 서명 검토는 release 게이트 FE-GATE-028이고 사용자 몫(U-2)이다 |
| 27 | 삭제 가능성 | > | — | — | 영역 09. 제거 검증이 `check:i18n`을 건너뛰는 FOLLOW-UP 09-07은 09가 유효로 확인했다 |
| 28 | 회복 가능성 | O | M2 / M2 | E2 | 라우트 렌더 실패·청크 실패·context 모듈 실패 화면에 "한 번 새로고침"이 있다(`app-router.tsx:108-114`, `chunk-recovery-boundary.tsx:137-140`) |
### 3.1 대표 과제 (관점 4)
지난 라운드와 같은 과제를 다시 했다. "목록 화면이 어느 API를 호출하고, 실패하면 어떤 화면을 보여 주는가."
```text
URL /examples/reference-resources
→ context 경로: src/contexts/reference-context/context-module.ts:9 (grep으로 찾음)
→ 기능 라우트: src/features/reference-feature/context-routes.ts (파일 이름 규약으로 찾음)
두 파일을 잇는 것은 생성 인덱스(src/.generated/, git 밖)다 ← 규약을 알아야 함
→ 페이지: reference-feature-runtime.ts의 lazy import
installed-feature-runtimes.tsx의 ROUTE_RUNTIME에는 기능 항목이 비어 있다.
descriptor 주석이 이유(boot-safe)를 적는다 ← 줄어든 막힘
→ 호출: use-reference-feature.ts:133 → application input → HTTP gateway
→ 실패: AppFailure.kind → ERROR_REGISTRY 행 → error.* 문구
registry와 catalog의 연결은 i18n-contract 테스트가 지킨다 ← 해소된 막힘
→ AsyncSurface → TerminalErrorSurface 또는 AccessSurface
버튼은 registry action과 페이지의 onAction이 둘 다 있어야 보인다 ← 그대로
```
- 줄어든 막힘: 기능 라우트가 기능 폴더의 `context-routes.ts`에 있다. 문구 키 규칙은 테스트가 지킨다.
- 그대로인 막힘: 생성 인덱스 규약, 버튼 표시 조건 두 곳(`async-surface.tsx:96`, `use-reference-failure-action.ts:44-49`).
- 새 막힘: 목록 제목을 바꾸려면 계약·catalog·페이지 세 곳을 봐야 한다(08-06). `{count}` 문구는 타입 있는 `message()`로 쓸 수 없어 주석(`reference-resource-page.tsx:47-49`)을 읽어야 우회 경로를 안다(08-03).
## 4. 설계 선택 설명 (41절)
### 4.1 지원 locale 집합과 catalog parity를 플랫폼 코드에 고정한다 → 변경 권고(08-01)
1. **무엇이 필요한가.** 템플릿은 i18n 동작(pseudo 확장, RTL)을 스스로 검증해야 한다. 제품은 실제로 지원할 locale만 선언하고 그 locale의 문구만 쓰고 싶다. memento는 한국어 전용이다(동기화 기록의 open question 1).
2. **지킬 성질.** 선언한 모든 locale에서 모든 키가 있다. 사용자 선택지에는 선언한 locale만 나온다. 누락은 안전한 대체 문구로 끝난다.
3. **현재 보장.** 확인한 사실: locale은 `SUPPORTED_LOCALES`(`src/presentation/i18n/message-contract.ts:8-13`), `MESSAGE_CATALOGS`(`catalog.ts:403-407`), 셸 선택지(`app-shell.tsx:97-102`), `normalizeLocale` 분기(`message-contract.ts:44-53`), `catalogKeys` 인자 타입(`:129-133`)에 따로 적혀 있다. `EN_MESSAGES`는 모든 키를 갖도록 `satisfies`로 강제된다(`catalog.ts:396`, `:401`). 기능 catalog에서 en-US를 빼면 타입 검사가 실패한다(E3). 셸은 개발용 `Pseudo`, `RTL smoke`를 운영 화면에도 보인다. 보장하지 않는 것: 제품이 locale 집합을 줄이거나 바꾸는 방법.
기록된 의도: VD-06 결정 2(한국어 canonical + 영어·RTL catalog parity), 결정 5(en-XA·ar-EG는 제품 번역이 아님).
4. **대안.** (A) 현 상태. (B) locale 선언을 한 곳에 둔다. 예: `src/presentation/i18n/locales.ts`의 `PRODUCT_LOCALES`와 `DEV_LOCALES`. 나머지 네 곳과 `check:i18n`이 이 목록에서 파생된다. parity는 선언한 locale에만 강제한다. (C) i18n 라이브러리 도입.
5. **비용.** (A) 한 언어 제품은 가짜 영어 문구를 만들거나 템플릿 파일을 고친다. (B) 파일 4~5개와 타입 파생, i18n e2e를 선언에 맞춰 조건화한다. 템플릿 자체의 선언은 지금과 같게 둔다. (C) VD-06 재검토 조건(세 개 이상의 승인 locale 등)이 없다. 번들과 학습 비용만 는다.
6. **판단.** (B). 확인한 조건에서 두 제품 중 하나가 한국어 전용이고, 템플릿의 parity 성질은 "선언한 locale 안에서"로 좁혀도 그대로 지킬 수 있다.
7. **재검토 조건.** 서버 locale 협상, 세 개 이상 실제 locale, 번역 추출 workflow가 생기면 (C)를 다시 비교한다(VD-06 재검토 조건).
### 4.2 폼 저장 실패의 분기 순서와 결과 불명 화면의 두 행동 → 현 상태 유지
1. **무엇이 필요한가.** 모든 다운스트림 폼이 `useAppForm`을 쓴다. 저장 실패마다 사용자가 할 수 있는 행동이 달라야 한다(32.2).
2. **지킬 성질.** 입력 오류만 ErrorSummary에 간다. 재로그인이 필요하면 다른 판단보다 먼저 알린다. 결과를 모르는 저장은 자동으로도, 새 키로도 다시 보내지 않는다.
3. **현재 보장.** 확인한 사실: `applyOutcome`이 422 → reauth → MAYBE_APPLIED → APPLIED_CONFIRMED → CONFLICT → FORBIDDEN·retry → 나머지 순서로 나눈다(`use-app-form.ts:198-248`). 결과 불명 화면은 "변경됨으로 확인"과 "같은 요청으로 다시 보내기"만 준다. "변경되지 않음"은 근거가 없어서 빠졌다(`async-surface.tsx:118-121`). 재전송은 같은 intent·키를 쓴다(E6). 테스트: `form-foundation.test.tsx:150-236`, `reference-page.test.tsx:425`, `:481-534`. 보장하지 않는 것: 재로그인이 결과 불명을 가릴 때의 처리(7절).
기록된 의도: 코드 주석 D-1, D-2, F-10.
4. **대안.** (A) 현 상태. (B) 실패마다 `TerminalErrorSurface` 하나로 통일하고 action만 바꾼다. (C) "변경되지 않음" 선택지를 되살린다.
5. **비용.** (B)는 입력 오류의 필드 연결과 포커스 이동을 잃는다. (C)는 지난 08-03의 결함(근거 없는 판정 뒤 새 키)을 되살린다.
6. **판단.** 현 상태 유지. 분기 순서와 이유가 한 함수와 짧은 주석에 모여 있어 국소적으로 읽힌다(39.3).
7. **재검토 조건.** 서버가 결과 조회(inspect) operation을 제공하면 "변경되지 않음"을 근거와 함께 다시 넣는다. 재로그인+결과 불명 조합이 실제로 생기는 것이 확인되면 분기 순서를 다시 본다.
### 4.3 `check:i18n`이 파일 전체에서 한글을 찾는다 → 변경 권고(08-02)
1. **무엇이 필요한가.** 화면 문구가 catalog를 거치게 해서 번역 누락을 막는다. 32.3은 버튼·오류·empty·loading·알림·접근성 이름을 범위로 든다.
2. **지킬 성질.** 사용자에게 보이는 문구와 접근성 이름이 catalog에서 온다. 주석·테스트 데이터는 대상이 아니다.
3. **현재 보장.** 확인한 사실: 정규식 `/[가-힣]/`를 파일 전체에 적용한다(`scripts/check-i18n.ts:12`, `:95-99`). 한글 주석 한 줄에 실패하고(E1), 영어 JSX 문구는 통과한다(E1b). 샘플에 영어 문구가 이미 있다(`reference-resource-page.tsx:25`, `:37`, `:62`, `reference-resource-detail-page.tsx:24-36`, `reference-resource-form-page.tsx:80`). 기록된 의도: VD-06 검증 절은 "화면 코드의 한국어 literal"이라고 정확히 적는다. 스크립트 주석(`check-i18n.ts:55-57`)과 실패 문구는 "catalog에서 문구를 가져와야 한다"로 더 넓게 말한다.
4. **대안.** (A) 현 상태. (B) 이미 쓰는 ESLint `no-restricted-syntax`에 선택자를 더한다. 예: presentation 파일에서 공백이 아닌 `JSXText`, `aria-label`·`title`·`alt`·`placeholder` 속성의 문자열 literal. 주석은 AST에 없어 자연히 빠진다. (C) tech-log처럼 "행동·상태 문구"만 정규식으로 고르는 제품 정책(`tech-log-frontend:scripts/lib/tech-log-i18n-policy.ts`).
5. **비용.** (A) 두 제품이 각각 막히거나 스크립트를 고쳤다. (B) 새 의존성이 없다. 구두점·고유명사 같은 예외를 어떻게 허용할지 정해야 하고, 샘플의 영어 문구를 catalog로 옮겨야 한다. (C) 한국어 문장 목록에 기대 영어를 못 잡고, 템플릿 기본값으로 쓰기에 규칙이 제품 특화다.
6. **판단.** (B). 기존 도구로 주석 거짓 양성과 영어·접근성 이름 거짓 음성을 함께 없앤다. 한 언어 제품에서 이 규칙을 끌지는 4.1의 선언에 맡긴다.
7. **재검토 조건.** 번역 추출 도구를 도입하면 그 도구의 추출 규칙으로 대체한다.
## 5. 발견 사항 (36.3)
### 08-01 제품이 지원 locale을 선언할 곳이 없어, 한 언어 제품은 가짜 번역을 만들거나 템플릿 파일을 고쳐야 한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 3, 19, 20, 23, 25, 14 |
| 근거 | locale 집합이 다섯 곳에 따로 있다: `src/presentation/i18n/message-contract.ts:8-13`(`SUPPORTED_LOCALES`), `:44-53`(`normalizeLocale`), `:129-133`(`catalogKeys`), `src/presentation/i18n/catalog.ts:403-407`(`MESSAGE_CATALOGS`), `src/presentation/layouts/app-shell.tsx:97-102`(셸 선택지). `EN_MESSAGES`는 모든 키를 가지도록 `satisfies Record<MessageKey, string>`로 강제된다(`catalog.ts:401`). E3: 샘플 기능 catalog에서 en-US를 빼자 `catalog.ts(400,6): error TS7053`. 셸은 개발용 `Pseudo`·`RTL smoke`를 모든 사용자에게 보인다(`app-shell.tsx:100-101`, `catalog.ts:37-38`). 제품 증거: memento는 한국어 전용이라 문구를 JSX에 두었고, merge 단계 게이트 FE-GATE-010에 속한 `check:i18n`이 실패한다(E2, 동기화 기록 "Introduced and escalated"와 open question 1) |
| 발생 조건 | 제품이 ko-KR 한 언어만 지원할 때. 또는 en-US 대신 다른 locale을 원할 때 |
| 영향 | 한 언어 제품은 (1) 쓸 일 없는 영어 문구를 키마다 만들거나, (2) 템플릿 소유 파일 다섯 곳을 고치거나, (3) merge 게이트가 실패한 채로 둔다. 모든 locale 문구가 초기 청크에 들어가므로 쓰지 않는 locale도 번들 비용이 된다(14번). 운영 사용자에게 개발용 locale이 보인다 |
| 심각도·우선순위 | Medium · P1 — 데이터·보안 피해는 없다. 다만 실제 제품 하나에서 템플릿 계약 때문에 merge 단계 검사가 실패하고, 두 번째 한국어 전용 제품도 같은 길을 간다 |
| 통제·증거 | 선언 수단 M0 · E3(E2, E3) |
| 확실성과 남은 가정 | 확인. memento가 영어 문구를 쓰지 않기로 할지는 제품 결정이다(미정) |
| 결정의 근거 | 4.1절. 확인한 사실은 위 근거. 기록된 의도는 VD-06 결정 2·5. 리뷰어 추론: VD-06은 한 언어 제품을 고려하지 않았다 |
| 이해 비용 | locale을 바꾸려는 제품 개발자가 파일 다섯 곳과 `check:i18n`, e2e `i18n.spec.ts`를 함께 맞춰야 한다 |
| 최소 개선 방향 | locale 선언 파일 하나를 두고(예: `PRODUCT_LOCALES`, `DEV_LOCALES`) 다섯 곳이 여기서 파생되게 한다. parity는 선언한 locale에만 강제한다. 셸 선택지는 `DEV_LOCALES`를 개발 빌드에서만 보인다. `check:i18n`은 선언한 locale이 하나면 문구 literal 규칙을 끄는 대신 그 결정을 산출물(`artifacts/quality/i18n.json`)에 남긴다 |
| 대안 비교 | 4.1절 (A)~(C) |
| 단순화의 보존 조건 | 템플릿 자신의 선언은 ko-KR·en-US·en-XA·ar-EG 그대로다. 기존 parity 테스트와 타입 fixture(`check:types:fixture:i18n-key`, `:i18n-params`)는 그대로 통과한다. 누락 키의 대체 문구 동작은 바뀌지 않는다 |
| 비용·부작용 | 파일 4~5개, 타입 파생, i18n e2e의 조건화. 복사한 제품은 선언 파일 하나를 새로 채워야 한다(CHANGELOG [계약]) |
| 재검토 조건 | 서버 locale 협상이나 번역 추출 workflow가 생길 때 |
| 완료 기준 | ko-KR만 선언한 fixture에서 en-US catalog 없이 `check:types`와 `check:i18n`이 통과한다. 템플릿 기본 선언에서는 지금과 같은 검사가 돈다. 운영 빌드 셸에 `Pseudo`·`RTL smoke`가 없다 |
| 검증 방법 | 한 locale 선언 fixture 타입 검사, 셸 선택지 component 테스트, E2 재실행(memento가 선언을 바꾼 뒤) |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 없음(신규) |
### 08-02 `check:i18n`이 "파일에 한글이 있는가"만 봐서, 주석은 걸고 영어 문구·접근성 이름은 놓친다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 21, 23, 24, 10, 20 |
| 근거 | 규칙은 `/[가-힣]/`를 파일 전체 문자열에 적용한다(`scripts/check-i18n.ts:12`, `:95-99`). E1: 한글 주석 한 줄만 넣어도 실패. E1b: 영어 JSX 문구를 넣어도 통과. 샘플 화면의 영어 literal이 이미 통과 중이다: h1 `"Reference feature"`(`reference-resource-page.tsx:25`), `limit {filters.limit}`(`:37`), 목록 접근성 이름 `aria-label="Reference resources"`(`:62`), 상세의 `"DetailPage"`·`"Reference detail"`·`Resource ID`·`Created`(`reference-resource-detail-page.tsx:24-36`), 폼 eyebrow `"FormPage"`(`reference-resource-form-page.tsx:80`). 실패 문구 "hardcoded common user-facing locale literal"과 주석 "must take its words from the catalog"(`check-i18n.ts:55-57`)는 실제 규칙보다 넓다. fixture는 한글 literal 양성 사례만 있다(`tests/fixtures/i18n/forbidden/`). E2: memento의 걸린 21개 파일에는 데모 데이터(`memento-demo-model.ts`)와 stories 파일이 들어 있다. 제품 증거: tech-log는 "comment와 literal을 구분하지 못한다"는 이유로 스크립트를 고쳤다(tech-log 동기화 기록 open 4, `scripts/check-i18n.ts` 30줄 diff) |
| 발생 조건 | 기능 화면 파일에 한글 주석·데이터가 있을 때(거짓 양성). 영어로 문구를 박을 때(거짓 음성) |
| 영향 | ko-KR 사용자에게 영어 제목·필터 문구·스크린리더 이름이 섞인다. 이 샘플을 복사한 제품은 같은 패턴을 검출 없이 퍼뜨린다. 반대로 한국어 주석을 쓰는 팀은 게이트를 끄거나 스크립트를 고친다. 지난 08-04의 완료 기준("en-US 화면에 한국어가 없다")은 통과했지만, 검사 범위가 "catalog 사용"이 아니라 "한글 유무"다 |
| 심각도·우선순위 | Medium · P2 — 문구 누락과 게이트 불신이 반복되지만 기능은 동작한다 |
| 통제·증거 | 한글 literal M3 / 영어·접근성 이름 M0 / 주석 구분 M0 · E3(E1, E1b, E2) |
| 확실성과 남은 가정 | 확인. 어떤 영어 문자열을 허용할지(고유명사, 구두점)는 정해야 한다 |
| 결정의 근거 | 4.3절. 기록된 의도(VD-06 검증 절)는 "한국어 literal"로 좁다. 스크립트 주석·실패 문구는 "catalog 사용"으로 넓다. 리뷰어 추론: 템플릿이 막고 싶은 것은 후자다 |
| 이해 비용 | 게이트가 실패하면 개발자가 주석인지 문구인지 파일을 열어 찾아야 한다. 실패 메시지에 줄 번호가 없다 |
| 최소 개선 방향 | 문구 literal 검사를 ESLint `no-restricted-syntax` 선택자로 옮긴다(`JSXText`, 접근성·표시 속성의 문자열 literal). `check:i18n`에는 catalog parity와 raw backend 메시지 검사만 남긴다. 샘플의 영어 literal을 catalog로 옮긴다. fixture에 "주석만 있는 파일은 통과"와 "영어 JSX 문구는 실패"를 더한다 |
| 대안 비교 | 4.3절 (A)~(C) |
| 단순화의 보존 조건 | 한글 JSX 문구, `dangerouslySetInnerHTML`, `{failure.message}` 렌더링은 지금처럼 실패한다. `examples` 제외는 유지한다 |
| 비용·부작용 | 샘플 문구 약 10개 이동. 선택자 허용 목록을 관리해야 한다 |
| 재검토 조건 | 번역 추출 도구를 도입할 때 |
| 완료 기준 | E1 변이(한글 주석)는 통과하고 E1b 변이(영어 JSX 문구)는 실패한다. ko-KR 샘플 화면의 main 영역에 catalog 밖 영어 문구가 없다 |
| 검증 방법 | E1·E1b 변이 재실행, 새 fixture 2개, `reference-form.spec.ts`에 ko-KR 검사 추가 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 없음(신규) |
### 08-03 기능 문구의 보간 파라미터가 타입 계약에 없어, `message()`가 틀린 호출은 통과시키고 맞는 호출은 거절한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 3, 5, 17, 21, 22, 23, 25 |
| 근거 | 파라미터 타입은 플랫폼 파일의 닫힌 목록 `MessageParameters`(`src/presentation/i18n/message-contract.ts:17-26`)에만 있다. 목록에 없는 키는 `[parameters?: never]`가 된다(`:32-35`). 기능 catalog의 `"reference.list.resultCount": "총 {count}개 항목"`은 목록에 없다. E4: `formatMessage("ko-KR", "reference.list.resultCount")`는 타입 검사를 통과하고 실행하면 "요청한 문구를 표시할 수 없습니다."를 돌려준다. `{ count: 1 }`을 넣으면 TS2345로 거절된다. 샘플은 타입 없는 `resolveMessage`로 우회하고 이유를 주석에 적었다(`reference-resource-page.tsx:47-53`). 제품 증거: tech-log는 `techLog.notice.*` 11개 키를 템플릿 `message-contract.ts`에 넣었다(diff 13줄) |
| 발생 조건 | 기능이 `{name}` 같은 보간이 있는 문구를 추가할 때 |
| 영향 | 기능 작성자는 (1) 타입 없는 resolver를 쓰거나(키 오타·파라미터 누락 검출을 잃는다), (2) 템플릿 소유 파일을 고친다(동기화마다 병합). 타입 있는 호출이 파라미터를 빠뜨리면 화면에 대체 문구가 조용히 뜬다 |
| 심각도·우선순위 | Medium · P2 — 화면 오류는 대체 문구로 끝난다. 모든 기능이 부딪히는 경로이고 타입 안전을 우회하게 만든다 |
| 통제·증거 | 플랫폼 키 M4(타입 fixture) / 기능 키 M0 · E3(E4) |
| 확실성과 남은 가정 | 확인 |
| 결정의 근거 | 확인한 사실은 위 근거. 기록된 의도: VD-06 결정 3("보간이 필요한 key는 `MessageParameters`에 선언"). 기능 catalog가 설치 모듈에서 합쳐지는 구조(`src/features/installed-feature-messages.ts:32-62`)는 결정 3 뒤에 생겼다. 리뷰어 추론: 결정 3이 기능 catalog를 고려하지 않았다 |
| 이해 비용 | 기능 작성자가 `{count}` 문구 하나를 쓰려고 플랫폼 i18n 타입과 샘플 주석을 읽어야 한다 |
| 최소 개선 방향 | catalog가 `as const`라 문자열 literal 타입에서 placeholder 이름을 뽑을 수 있다. `MessageArguments<Key>`를 "catalog 문자열의 `{이름}`에서 파생"으로 바꾸면 플랫폼·기능 키가 같은 규칙을 쓴다. 값 타입을 좁히고 싶은 키만 `MessageParameters`로 덮어쓴다 |
| 대안 비교 | (A) 현 상태: 비용 0, 위 영향이 남는다. (B) placeholder에서 파생: 새 개념이 없고 기능이 템플릿 파일을 고치지 않는다. 값 타입은 `string \| number`로 넓어진다. 템플릿 리터럴 타입 재귀로 타입 검사 시간이 조금 는다. (C) 기능 모듈이 `messageParameters` 타입을 선언하고 설치 조립이 교집합을 만든다(`installed-feature-messages.ts`의 `UnionToIntersection`과 같은 방식): 값 타입을 정확히 쓸 수 있지만 catalog와 파라미터 선언을 따로 맞춰야 한다. (B)가 가장 작다 |
| 단순화의 보존 조건 | 기존 타입 fixture(`check:types:fixture:i18n-params`)가 잘못된 파라미터를 계속 거절한다. 누락 보간의 실행 시 대체 동작은 그대로다 |
| 비용·부작용 | 타입 몇 줄과 fixture 1개. tech-log가 넣은 11개 키는 파생으로 대체된다 |
| 재검토 조건 | ICU 복수형·select처럼 placeholder만으로 표현하지 못하는 문구가 생길 때(VD-06 재검토 조건) |
| 완료 기준 | E4의 두 호출 결과가 뒤집힌다: 파라미터 없는 호출은 타입 오류, `{ count: 1 }` 호출은 통과. 샘플이 타입 있는 `message()`로 결과 수를 그린다 |
| 검증 방법 | 기능 키 타입 fixture 추가, E4 재실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 없음(신규) |
### 08-04 폼 저장 실패와 결과 불명 화면에 문의 식별자가 없고, 샘플 지원 안내는 고정 문자열을 보여 준다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 8, 23, 24, 6 |
| 근거 | 조회 실패는 `supportReference={state.failure.requestId}`를 넘긴다(`src/presentation/components/async-surface.tsx:146-152`, `:165`). 폼의 `FormFailureStatus`는 `userMessageKey`·`action`·`description`만 넘긴다(`src/presentation/forms/form-components.tsx:95-106`). 결과 불명 화면은 `AsyncSurface`의 indicator 분기라 실패 객체가 없다(`async-surface.tsx:170-207`). 폼도 결과 불명일 때 실패를 보관하지 않는다(`use-app-form.ts:221-224`). E5: 같은 `requestId`가 조회 화면에만 보였다. E6: 저장 500에 `x-correlation-id`와 `Access-Control-Expose-Headers`를 붙여도 결과 불명 화면에 식별자가 없었다. 같은 조건의 목록 500은 "지원 참조: corr-list-500"을 보였다. 샘플의 contact-support 행동은 요청 식별자를 버리고 고정 경로로 이동한다(`use-reference-failure-action.ts:7`, `:33-35`). 그 화면은 `supportReference="REFERENCE-STATUS-DEMO"`를 "지원 참조"로 보인다(`reference-resource-status-page.tsx:23`) |
| 발생 조건 | 저장이 5xx·연결 끊김으로 실패할 때. 저장 실패의 action이 contact-support일 때 |
| 영향 | 사용자가 가장 문의하고 싶은 경우(결과를 모르는 저장)에 줄 식별자가 없다. 진단 이벤트에는 `correlation_id`가 남지만(VD-07 결정 4) 사용자 신고와 이을 수 없다. 샘플을 복사한 제품의 모든 폼이 같다. "지원 참조: REFERENCE-STATUS-DEMO"는 식별자처럼 보여 오히려 잘못 전달된다 |
| 심각도·우선순위 | Medium · P2 — 가이드 35.2의 "주요 진단 정보 부족" |
| 통제·증거 | 조회 M3 / 폼·결과 불명 M0 · E3(E5, E6) |
| 확실성과 남은 가정 | 확인. 서버가 헤더를 노출하지 않으면 조회 화면도 식별자가 없다(FOLLOW-UP 03-03, 6절) |
| 결정의 근거 | 적용 제외 — 지난 08-07의 계약("실패 화면에 지원 참조를 보인다")이 이미 정해져 있고 적용 범위만 빠졌다 |
| 이해 비용 | 폼을 만드는 개발자가 조회와 폼의 실패 화면이 다르게 동작한다는 것을 코드를 읽어야 안다 |
| 최소 개선 방향 | `FormFailureStatus`가 `supportReference={failure.requestId}`를 넘긴다. 폼은 결과 불명일 때도 실패를 보관하고, 결과 불명 화면에 식별자를 보인다. 샘플 contact-support 이동은 식별자를 state로 넘기고, 상태 페이지는 받은 값만 보인다(없으면 줄을 숨긴다) |
| 대안 비교 | 적용 제외 — 기대 계약이 고정돼 있다 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 컴포넌트 2개와 샘플 2파일, 테스트 3개 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | E5의 폼 쪽 단언이 뒤집힌다. E6 저장 500(expose 있음)에서 "지원 참조: corr-save-500"이 보인다. 상태 페이지에 고정 문자열이 없다 |
| 검증 방법 | `form-foundation.test.tsx`에 requestId 단언, `reference-save.spec.ts`에 결과 불명 식별자 단언 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 없음(신규) |
### 08-05 context 라우트 모듈의 비청크 실패와 feature·context 경계의 실패가 진단을 남기지 않고, 화면에는 build id만 보인다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 8, 6, 10, 28 |
| 근거 | `ContextRouteGateway`는 라우트 모듈 로드가 청크 오류가 아닌 이유로 실패하면 `RouteFailureSurface supportReference={buildId}`만 그린다(`src/presentation/routes/app-router.tsx:478-496`). 진단 호출이 없다. 같은 파일의 `ContextErrorBoundary`·`FeatureErrorBoundary`에는 `onError`를 넘기지 않는다(`:466-472`, `:519-525`). 두 경계는 `onError`를 받을 수 있다(`src/platform/errors/scoped-error-boundary.tsx:20`, `:35-43`). `APP_SHELL`의 `errorElement`도 같다(`app-router.tsx:569`). 반면 라우트 안쪽 경계는 incident id를 만들어 보고한다(`:383-391`, `src/presentation/boundaries/render-error-boundary.tsx:38-55`). E7: context 모듈이 `ReferenceError`로 실패하자 화면은 "지원 참조: build-x", `ui.render.failed` 기록은 0건이었다. 이 경로의 테스트는 없다(`tests/component/context-route-gateway.test.tsx`는 청크 실패만 본다) |
| 발생 조건 | 배포 뒤 context 라우트 모듈이 평가 중 throw할 때(중복 키로 `composeUniqueRecord`가 throw, 잘못된 import 등). 라우트 안쪽 경계 밖(예: `RouteLifecycle`, `RouteSurface`의 경계 이전 코드)에서 렌더 오류가 날 때 |
| 영향 | bounded context 하나의 화면 전체가 실패 화면이 되는데 진단 이벤트가 없다. 운영자는 신고를 받기 전에는 알 수 없고, 신고의 build id만으로는 사건을 찾을 수 없다. 지난 09-03(부트 모듈 평가 실패)과 같은 종류의 실패가 context 수준에 남았다 |
| 심각도·우선순위 | Medium · P2 — 발생 가능성은 낮지만 영향 범위가 context 전체이고 탐지 수단이 없다 |
| 통제·증거 | M0 · E3(E7) |
| 확실성과 남은 가정 | 확인. 운영에서 이런 실패가 얼마나 나는지는 모른다 |
| 결정의 근거 | 적용 제외 — 라우트 경계에 이미 있는 보고 계약을 같은 파일의 다른 경계에 적용하지 않은 누락이다 |
| 이해 비용 | 필요한 범위만: `app-router.tsx`의 경계 네 곳 중 두 곳만 보고한다는 사실을 파일을 끝까지 읽어야 안다 |
| 최소 개선 방향 | 비청크 실패 분기와 세 경계의 fallback을 `RenderErrorBoundary`처럼 incident id를 만들고 `diagnostics.reportRenderFailure`를 부르는 형태로 바꾼다. 가장 작은 방법은 이 세 곳도 `RouteBoundary`(incident 함수형 fallback)를 쓰는 것이다 |
| 대안 비교 | 적용 제외 — 기대 계약이 고정돼 있다 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | `app-router.tsx` 수십 줄, component 테스트 1~2개 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | E7 probe에서 화면의 지원 참조가 `build-x:<incident>`이고, 같은 incident의 `ui.render.failed`가 1건 기록된다 |
| 검증 방법 | `context-route-gateway.test.tsx`에 비청크 실패 케이스 추가 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 없음(신규) |
### 08-06 라우트 제목이 계약·catalog·페이지 세 곳에 따로 있고, 샘플에서도 서로 다르며, catalog에서 빠져도 아무 검사도 실패하지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 23, 24, 21, 4, 10 |
| 근거 | 목록 라우트 하나의 제목: 계약 `title: "Reference feature"`, `navigationLabel: "Reference feature"`(`src/features/reference-feature/contracts/reference-feature-contract.ts:85-86`). catalog `route.REFERENCE_RESOURCE_LIST.title: "Reference resources"`(`reference-message-catalog.ts:4`, `:49`). 페이지 h1 literal `"Reference feature"`(`reference-resource-page.tsx:25`). 문서 제목은 catalog, h1은 literal, 탐색은 catalog의 navigation을 쓴다(`app-router.tsx:173-178`, `app-shell.tsx:189`). 계약의 `title`·`navigationLabel` 문자열은 e2e·성능 스크립트의 기대값(`tests/e2e/accessibility.spec.ts:47`, `old-tab-chunk-recovery.spec.ts:93`, `scripts/test-performance.ts:47`)과 "탐색에 넣을지" 판정에만 쓰인다. 플랫폼 `NOT_FOUND`도 계약 "페이지를 찾을 수 없음"과 catalog "페이지를 찾을 수 없습니다."가 다르다(`src/contracts/routes.ts:94`, `catalog.ts:55`). E8: catalog에서 목록 라우트의 title·navigation을 지워도 `check:i18n`, `tsc`, 관련 테스트 20 files/90 tests가 모두 통과했다. 이 키는 `` resolve(`route.${id}.title`) ``처럼 문자열로 조립돼 타입 검사를 받지 않는다 |
| 발생 조건 | 기능 라우트를 추가·이름 변경할 때 |
| 영향 | 탐색 링크와 문서 제목에 "요청한 문구를 표시할 수 없습니다."가 조용히 뜰 수 있다. 같은 화면의 탭 제목과 h1이 다르다. 제목을 바꾸는 사람이 세 곳을 모두 찾아야 한다 |
| 심각도·우선순위 | Low · P3 — 표시 문제다 |
| 통제·증거 | M0 · E3(E8) |
| 확실성과 남은 가정 | 확인 |
| 결정의 근거 | 확인한 사실은 위 근거. 기록된 의도: `starter-experience.md:34`("Navigation labels and order come from `ROUTE_REGISTRY`"). 실제 표시 문구는 catalog에서 온다. 리뷰어 추론: 계약의 제목 문자열은 catalog 이전의 흔적이고 지금은 테스트 기대값으로만 남았다(39.5의 "어느 도구도 읽지 않는 선언"에 가깝다) |
| 이해 비용 | 대표 과제에서 제목 하나를 바꾸려면 계약·catalog 두 locale·페이지를 열어야 했다(3.1) |
| 최소 개선 방향 | (1) 등록된 모든 라우트에 `route.<id>.title`(탐색 라우트는 `.navigation`도)이 모든 locale에 있는지 단위 테스트로 검사한다. (2) 페이지 h1은 `route.<id>.title`을 쓰거나 페이지 전용 키를 쓰되 literal은 없앤다. (3) 계약의 `title`은 지우거나 "테스트 기대값 전용"이라고 이름을 바꾼다 |
| 대안 비교 | (A) 현 상태. (B) 위 (1)만: 테스트 하나로 누락은 막고 중복은 남는다. (C) (1)~(3): 한 곳으로 모으고 e2e는 catalog에서 기대값을 읽는다(`accessibility.spec.ts`가 이미 그렇게 한다). (B)를 먼저, (C)는 계약 변경이라 CHANGELOG [계약]이 필요하다 |
| 단순화의 보존 조건 | `navigationLabel: null`로 탐색에서 빼는 기능은 유지한다. 성능 스크립트의 대상 링크 선택이 계속 동작한다 |
| 비용·부작용 | 테스트 1개. (C)는 계약 필드 변경과 제품 이행 안내 |
| 재검토 조건 | 라우트 제목을 서버에서 받게 되면 |
| 완료 기준 | E8 변이가 테스트 실패로 잡힌다. ko-KR 샘플 목록의 h1과 문서 제목이 같은 문구다 |
| 검증 방법 | E8 재실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 없음(신규) |
### 08-07 폰트·전역 스타일을 넣을 제품 쪽 자리와 운영 CSP에 맞는 방법이 안내돼 있지 않다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 15, 19, 20 |
| 근거 | 운영 CSP는 `style-src 'self'; font-src 'self'`다(`config/hosting/security-headers.json:4`). CSP를 넓히는 안내는 선택 기능 세 가지(다른 origin realtime, blob 미리보기, 이미지 CDN)만 있다(`docs/architecture/optional-adapter-recipes.md:155-165`, `docs/security/browser-boundary.md:18-20`). 폰트·전역 스타일에 대한 안내는 `docs/`·README 어디에도 없다(grep `font-src`, `@font-face`, `self-host`: 0건). 기본 토큰은 싣지 않는 `Inter`를 가리킨다(`src/presentation/design-system/tokens/semantic.css:33`). 전역 스타일 진입점은 템플릿 소유 `theme.css`(`src/presentation/styles/theme.css:1-10`)와 `main.tsx`뿐이다. 제품 증거: memento는 `theme.css`에 jsdelivr `@import`를 넣었고 운영 CSP에서 막혔다(동기화 기록 open question 2). tech-log는 npm 폰트 패키지를 `main.tsx`에서 import해 same-origin으로 번들했다(diff 7줄). E9: 같은 `@import`를 넣자 `production-csp.spec.ts`가 `style-src-elem` 위반으로 실패했다. 즉 검출은 된다 |
| 발생 조건 | 제품이 폰트나 전역 스타일시트를 추가할 때 |
| 영향 | 제품이 CDN 경로를 고르면 운영에서 폰트 없이 렌더된다. 검출은 e2e(FE-GATE-008)에서야 된다. 두 제품 모두 템플릿 소유 파일을 고쳐 동기화 충돌 지점이 하나 늘었다 |
| 심각도·우선순위 | Low · P2 — 보안 통제는 제대로 동작한다. 문서 몇 줄과 파일 하나로 두 제품의 반복 비용을 줄인다 |
| 통제·증거 | 차단 M4(CSP) · 검출 M3(e2e, E9) · 안내 M0 · E3 |
| 확실성과 남은 가정 | 확인 |
| 결정의 근거 | 확인한 사실은 위 근거. 기록된 의도: CSP에 `unsafe-inline`이 없는 것은 의도다(`browser-boundary.md:8-10`). 리뷰어 추론: 폰트는 "선택 기능"이 아니라 거의 모든 제품이 하는 일이라 안내 대상에서 빠졌다 |
| 이해 비용 | 제품 개발자가 CSP 파일, e2e, Vite 자산 처리 방식을 함께 알아야 올바른 방법을 고른다 |
| 최소 개선 방향 | (1) 제품 스타일 진입 파일을 하나 둔다(예: `src/presentation/styles/product.css`를 `theme.css` 끝에서 import하고 템플릿은 비워 둔다). (2) `docs/styling/`에 "폰트는 npm 패키지나 `src/assets`로 자기 호스팅한다. CDN을 쓰려면 `style-src`·`font-src`를 넓히고 보안 결정을 기록한다"를 적는다. (3) 토큰의 `Inter`는 시스템 글꼴 스택으로 바꾸거나 "제품이 교체"라고 적는다 |
| 대안 비교 | (A) 현 상태. (B) 위 (1)~(3). (C) 빌드 시점에 외부 URL `@import`를 거절하는 정적 검사: e2e보다 이르지만 새 검사 비용이 든다. (B)로 충분하다. e2e가 이미 검출한다 |
| 단순화의 보존 조건 | CSP 기본값은 바꾸지 않는다 |
| 비용·부작용 | 빈 CSS 파일 1개, 문서 한 절 |
| 재검토 조건 | 운영 CSP를 배포 환경별로 생성하게 되면(`browser-boundary.md:21-26`) |
| 완료 기준 | 문서에 폰트 추가 절차가 있고, 제품이 `theme.css`·`main.tsx`를 고치지 않고 폰트를 넣을 수 있다 |
| 검증 방법 | 예제 폰트를 `product.css`로 넣은 브랜치에서 `production-csp.spec.ts` 통과 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 없음(신규) |
### 08-08 로그인 복귀 주소가 라우터 기준 경로라 base path 배포에서 앱 밖을 가리킬 수 있고, 포트 계약에 그 의미가 없다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 17, 19, 24, 5 |
| 근거 | 셸과 보호 라우트의 로그인 버튼은 `useLocation()`의 `pathname+search+hash`를 넘긴다(`src/presentation/providers/session-provider.tsx:70-81`). 샘플 실패 행동도 같다(`use-reference-failure-action.ts:23`). `useLocation()`은 router basename을 뺀 경로다. E11: `basename="/app"`에서 `beginSignIn("/fixture/items?x=1#results")`가 불렸다. 포트 계약 `beginSignIn(returnTo?: string)`에는 이 값이 라우터 기준인지 문서 경로인지 적혀 있지 않다(`src/application/ports/auth-session-port.ts:22`, `docs/architecture/frontend-ports-adapters-and-boundaries.md:500`). 외부 owner는 `routerBasePath`를 받지 않는다(`src/adapters/auth/external-session-adapter.ts:66`). 앱 안의 링크는 basename을 지킨다(`route-status-surfaces.test.tsx:140`) |
| 발생 조건 | `routerBasePath`가 `/`가 아닌 배포에서, 외부 owner가 `returnTo`를 그대로 리다이렉트 주소로 쓸 때 |
| 영향 | 로그인 뒤 `/fixture/items`처럼 앱 밖 경로로 돌아가 호스트의 404나 다른 앱을 본다 |
| 심각도·우선순위 | Low · P3 — 두 제품 모두 아직 `returnTo`를 쓰는 owner가 없다. 계약 한 줄로 막을 수 있다 |
| 통제·증거 | M0 · E3(E11). owner 동작은 미확인 |
| 확실성과 남은 가정 | 라우터 쪽 값은 확인했다. 실제 owner가 이 값을 어떻게 쓰는지는 repo 밖이다 |
| 결정의 근거 | 확인한 사실은 위 근거. 기록된 의도: 없음. 리뷰어 추론: base path 지원(19번)과 인증 seam이 따로 만들어졌다 |
| 이해 비용 | owner를 구현하는 사람이 presentation 코드를 읽어야 값의 의미를 안다 |
| 최소 개선 방향 | presentation이 문서 경로를 넘긴다(`useHref(location)` 또는 router의 `createHref`). 포트 주석에 "같은 origin의 문서 경로(basename 포함). owner는 open redirect를 막기 위해 같은 origin만 허용한다"를 적는다 |
| 대안 비교 | (A) 현 상태. (B) 문서 경로로 바꾸고 계약에 적는다: owner가 그대로 쓸 수 있다. (C) 라우터 기준으로 두고 계약에 적은 뒤 owner에 `routerBasePath`를 넘긴다: owner마다 조립 코드가 는다. (B)가 작다 |
| 단순화의 보존 조건 | 해시·search 보존(`route-status-surfaces.test.tsx`의 기존 단언)은 유지한다 |
| 비용·부작용 | 호출부 2곳, 테스트 기대값 변경. 이미 라우터 기준 값을 가정한 owner가 있으면 [계약] 변경이다 |
| 재검토 조건 | 로그인 복귀를 서버(BFF)가 전적으로 정하게 되면 |
| 완료 기준 | E11에서 `beginSignIn("/app/fixture/items?x=1#results")` |
| 검증 방법 | basename 케이스 component 테스트 추가 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 없음(신규) |
### 5.1 다른 영역으로 넘긴 것
- **제품 셸·레이아웃 자리가 없다.** 두 제품이 `app-router.tsx`를 고쳤다(145줄, 574줄). 09-03이 이미 적었다. presentation 쪽 추가 근거: 라우팅 문서는 "nested layout이 필요하면 contract에 parent ID를 두고 registry gate에서 검사한다"고 약속한다(`docs/architecture/routing-pages-and-patterns.md:210-212`). `RouteDefinition`에는 parent 필드가 없다(`src/contracts/routes.ts:1-13`). 문서의 확장 경로가 구현되지 않았다.
- **디자인 시스템 primitive 수정.** memento는 `unstyled` prop을 더했고(`core.tsx` 57줄), tech-log는 `Pagination`·`StatusPage` 옵션을 더했다(168줄, 115줄). 문서는 `className`을 escape hatch로 정하고 제품 전용 조합을 primitive에 넣지 말라고 한다(`docs/styling/design-system-platform.md:298`, `:105-107`). 템플릿 결함으로 보지 않았다. 제품이 템플릿 barrel에 자기 컴포넌트를 넣은 것(memento `design-system/index.ts`)은 동기화 비용으로만 기록한다.
## 6. FOLLOW-UP 재확인
| 항목 | 현재 코드에서 확인한 것 | 결과 |
|---|---|---|
| 4절 P3 08-04: en-US 브라우저 검사가 목록·폼만 본다 | en-US 검사는 목록과 폼 두 화면뿐이다(`tests/e2e/reference-form.spec.ts:55-80`). 검사 방식도 "한글이 없다"라 영어 literal은 보지 않는다(08-02) | 유효 |
| 4절 P3 08-07: 화면의 요청 ID와 진단 이벤트가 같은지 확인하지 않는다 | 라우트·청크 incident는 화면과 `correlation_id`를 같은 테스트에서 비교한다(`render-boundary.test.tsx:73-77`, `chunk-recovery-boundary.test.tsx:163-167`). HTTP 요청 ID는 화면 테스트가 합성한 `requestId`를 쓰고(`async-surface.test.tsx:144-151`), 진단 쪽은 HTTP 통합 테스트가 따로 본다(`tests/integration/http-diagnostics.test.ts:88`, `:120`). 한 흐름으로 잇는 테스트는 없다 | 유효(HTTP 요청 ID 쪽) |
| 4절 P3 03-03(영역 03, 화면에 보임): 서버가 헤더를 돌려주지 않으면 `requestId`가 빈다 | E6: CORS `Access-Control-Expose-Headers`가 없으면 목록 500 화면에 지원 참조가 없다. 문서는 expose가 필요하다고 적는다(`docs/operations/api-contract-and-server-state-recovery.md:184-188`). 클라이언트가 보낸 ID로 대체하지는 않는다 | 유효 |
| 1절 P1 초기 JS 예산 | R3: 203,481 / 204,800(여유 1,319 bytes). 초기 청크에 모든 locale 문구와 디자인 시스템 전체가 있다(14번) | 유효 |
| 6절 U-2 수동 접근성 10건 | `artifacts/tests/a11y-manual/*.md` 10건 모두 `pending-manual-review` | 유효(사용자 몫) |
| 지난 08-01~08-13(닫힌 발견) | 08-01 폼 실패 분리(R1, R2), 08-02 문구 누락(`i18n-contract.test.ts:41`), 08-03 같은 키 재전송(E6), 08-05 상태별 axe(R2), 08-08 스크롤·해시(R2), 08-09 결과 수(`reference-resource-page.tsx:50`), 08-10 언어 전환 재번역(`use-app-form.ts:62-83`), 08-11 접근 화면 통합(`async-surface.tsx:214-225`), 08-12 수정키 클릭(`navigation.tsx:273-281`), 08-13 `items/` 경로(`reference-feature-contract.ts:92`). 08-04는 한글 기준으로만 닫혔다(08-02). 08-07은 세 화면 밖에 빈 곳이 있다(08-04, 08-05). 08-06은 게이트를 FE-GATE-028로 옮겼고 기록은 여전히 pending이다 | 회귀 없음. 범위 밖 빈 곳은 새 발견으로 적음 |
## 7. 미검증 목록
| 무엇 | 왜 못 했나 | 무엇이 있으면 확인할 수 있나 |
|---|---|---|
| 재로그인이 필요한 결과 불명 저장 | 폼은 reauth를 결과 불명보다 먼저 처리하고(`use-app-form.ts:215-224`), 화면은 `form.failure`가 있으면 결과 불명 표시를 숨긴다(`reference-resource-form-page.tsx:137-146`). 로그인 뒤 scope가 바뀌면 결과 불명 기록과 입력이 사라져, 같은 내용을 다시 저장하면 새 키로 나갈 수 있다. 어떤 HTTP 응답 조합이 `AUTH_REQUIRED`+`MAYBE_APPLIED`를 만드는지는 영역 03의 분류에 달려 있다 | 영역 03의 effect 분류표, 해당 응답을 만드는 브라우저 probe |
| firefox·webkit에서 이번 presentation spec | 시간과 호스트 공유 때문에 chromium만 돌렸다 | `playwright.config.ts`의 세 엔진 실행 |
| 실제 스크린리더 발표 | 도구 없음. `LoadingSurface`는 `aria-busy="true"`와 `aria-live="polite"`를 같이 쓴다(`async-surface.tsx:22-28`). 로딩이 끝나면 영역이 사라져 "불러오는 중"이 발표되지 않을 수 있다 | NVDA·VoiceOver 수동 검토(U-2) |
| visual·storybook | 이번 범위에서 돌리지 않았다 | `test:visual`, `test:storybook` |
| 외부 owner의 `returnTo` 처리 | 템플릿·제품 모두 실제 리다이렉트 owner가 없다 | OIDC·BFF owner 구현 |
| 운영 호스팅의 실제 CSP 응답 | e2e는 preview 응답에 헤더를 붙인다 | `verify-hosting-headers`를 실제 배포에 실행(영역 13) |
| 초기 청크에서 문구 catalog가 차지하는 정확한 바이트 | 소스 gzip으로만 추정했다(플랫폼 약 6.4 KB, 샘플 기능 약 1.6 KB) | 번들 분석기로 `design-system-*.js` 모듈별 크기 측정 |
@@ -0,0 +1,350 @@
# 09 애플리케이션 코어·기능·조립 — 성숙도 리뷰
> 검토일: 2026-09-29 · 기준: `main` / `af3d8e6` (코드 변경 없음, 리뷰 가이드 문서 2개만 미커밋) · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 영역 판정(35.8): **조건부 사용 가능** — 템플릿의 틀(`AppShell` 아래 context, `http`·`telemetry` capability, 세션 기반 자격증명) 안에 들어가는 기능은 기능 디렉터리만 고쳐 설치할 수 있다. 제품이 홈(`/`)·자기 레이아웃·추가 capability·세션 밖 자격증명을 필요로 하면 템플릿 소유 파일을 고쳐야 하고, 다음 동기화에서 같은 파일이 다시 충돌한다(09-02, 09-03). `ANONYMOUS` 인증 프로필로 공개 API를 부르는 용도는 09-01 해결 전 사용 보류.
## 1. 머리말
### 1.1 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 | `clean-architecture-frontend-template`, `main` / `af3d8e6`, 2026-09-29 |
| 목적·실행 구성 | 프론트엔드 템플릿. 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음 |
| 영역 경로 | `src/application/`(3.6k줄), `src/features/`(2.9k줄), `src/bootstrap/`(2.2k줄), `src/platform/`(2.6k줄), `src/apps/`, `src/contexts/`, `scripts/generate-product-feature-index.ts`, `src/presentation/routes/app-router.tsx`의 조립 부분(`createRegisteredRoutes`, `ContextRouteGateway`) |
| 깊게 본 관점 | 2, 3, 4, 9, 13, 22, 25, 27 |
| 추가로 읽은 가이드 절 | 0, 2~4, 9, 13, 22, 25, 27, 29, 30(특히 30.3, 30.4, 30.7), 32(특히 32.4), 34~36, 39(특히 39.4, 39.6), 41 |
| 읽은 코드 | `src/features/` 최상위 조립 파일 전부(`feature-module.ts`, `feature-adapter-contribution.ts`, `installed-*` 8개), `local-draft-feature/NOT_INSTALLED`, `src/bootstrap/runtime-adapters.ts` 전체, `main.tsx`, `src/apps/*`, `src/contexts/*`, `src/platform/routing/context-route-module.ts`, `src/platform/cardinality/compose-unique-record.ts`, 생성기 전체, `app-router.tsx`의 1~72행·400~601행. 연결 확인용으로 `src/contracts/rest-profiles.ts`, `src/contracts/routes.ts`, `src/contracts/product-features.ts`, `src/adapters/http/http-execution-v3.ts`(자격증명 처리 부분), `src/adapters/http/http-contract-bridge.ts:66-96`, `.dependency-cruiser.json` 규칙 목록, `scripts/test-sample-removal.ts`, `docs/architecture/starter-experience.md` |
| 다운스트림 증거 | `../memento-frontend` 브랜치 `chore/template-sync-v0.2.0`(`d3810a0`, 템플릿과 이력 공유), `../tech-log-frontend` 브랜치 `chore/template-sync-v0.2.0`(`42d1ae1f`, 패치 이식). 두 제품의 `docs/operations/template-sync-2026-09-29.md`. `git diff af3d8e6 <branch> -- <path>`로 템플릿 대비 제품 변경만 읽었다. 브랜치는 바꾸지 않았다 |
| 이전 리뷰와 비교 | `docs/reviews/2026-09-25-maturity-review/09-app-core.md`의 09-01~09-12를 현재 코드에서 다시 확인했다(7절). 이전 실행 결과는 증거로 쓰지 않았다 |
### 1.2 실행한 명령과 실험
모두 격리 worktree(`<scratchpad>/review-2026-09-29/09/wt`, `af3d8e6`, 메인 `node_modules` 심볼릭 링크)에서 했다. 끝난 뒤 worktree를 지웠다.
| ID | 무엇 | 결과 |
|---|---|---|
| R1 | `node scripts/run-vitest.ts run tests/features tests/contract/reusable-capability/feature-adapter-composition.test.ts tests/unit/{product-features,two-feature-install-typecheck,product-feature-selection-build,runtime-adapters,feature-override-diagnostics,installed-feature-messages,product-index-entrypoints}.test.ts` | **27 files / 123 tests 통과** |
| E1 | 템플릿 fixture의 `ANONYMOUS` 프로필 operation(`tests/helpers/external-contract-fixture.ts`의 `TEST_LIST_ENTITIES`)을 설치한 상태로 실제 `createRuntimeAdapters`를 만들고, 기능이 받는 `http` capability로 실행했다. `installed-contract-contributions.ts`와 `installed-feature-adapters.ts`만 `vi.mock`으로 바꿨다 | 로그아웃: `UNAUTHENTICATED`, fetch 0회. 로그인(demo): `AUTH_INTEGRATION_FAILURE` / `CREDENTIAL_HEADER_NOT_ALLOWED`, fetch 0회 |
| E2 | 픽스처 기능(`home-feature`, context 경로 `*`)을 추가하고 생성기를 돌린 뒤 `ROUTE_REGISTRY`를 import했다. (가) 라우트 id `APP_HOME`, (나) 라우트 id `PRODUCT_HOME`·경로 `/` | (가) 모듈 평가 시 `TypeError: Duplicate route registry key: APP_HOME`. (나) 오류 없음, `/`에 라우트 2개(`APP_HOME`=platform, `PRODUCT_HOME`=home-feature) |
| E2b | `app-router.tsx:530-575`와 같은 모양(`APP_SHELL` 아래 index `APP_HOME` + context `*`)을 `react-router-dom`의 `matchRoutes`로 확인 | `/` → `APP_SHELL > APP_HOME`. 기능의 `/` 라우트는 조용히 가려진다 |
| E3 | 변이: `installed-feature-contracts.ts`에 `NOT_INSTALLED` 디렉터리(`local-draft-feature`)의 모듈을 직접 import하고, 그 값으로 만든 라우트를 `ROUTE_REGISTRY`에 끼워 넣었다. 그 뒤 `product-features.test.ts`, `feature-installation-surface.test.ts`, `installed-feature-messages.test.ts`, `corepack pnpm check:architecture` 실행 | 테스트 3 files / 19 tests 통과, `check:architecture` 통과. **변이가 살아남았다** |
| D1 | 두 제품에서 템플릿 대비 수정한 파일 목록(`git diff --name-status af3d8e6 <branch>`의 `M`)과 교집합 | memento 73개, tech-log 125개, 둘 다 고친 파일 32개(그중 `src/` 7개). 6절 |
| D2 | 조립 파일의 템플릿 변경 빈도: `git log --oneline ebea300..af3d8e6 -- <path>` | `runtime-adapters.ts` 15커밋, `app-router.tsx` 11커밋, `installed-feature-contracts.ts` 3커밋 등. 6절 |
### 1.3 확인하지 못한 범위
- 실제 브라우저에서 09-01의 공개 화면 실패. 코드 경로와 E1(vitest)로 확인했다. tech-log 기록은 "공개 사이트가 모든 화면에서 최종 오류 화면을 보였고 네트워크 로그에 요청이 없었다"고 적는다(제품 `src/bootstrap/runtime-adapters.ts:588-596` 주석). 이것은 주장이다.
- 외부 인증 owner(`AUTH_MODE=external`)로 로그인한 상태의 `ANONYMOUS` 호출. owner에게 인증 프로필이 전달되지 않는다는 것은 코드로 확인했다(`runtime-adapters.ts:513-520`). 실행하지 않았다.
- 제안한 확장 지점(4절)을 실제로 만들었을 때 두 제품의 다음 동기화 충돌이 줄어드는지. 설계 제안이며 검증하지 않았다.
- 다음 동기화의 충돌 수. 6절의 목록은 현재 diff와 템플릿 변경 빈도로 낸 추정이다.
## 2. 대표 흐름
### 2.1 정상 흐름 — 기능 하나를 설치해 첫 화면까지
```
feature-module.ts 선언 → 생성기 → src/.generated/* → installed-* 투영
→ main.tsx 동적 import → createRuntimeAdapters(capability 조립)
→ AppRouter(AppShell 아래 context gateway) → 기능 라우트 렌더
```
| 단계 | 내용 | 위치 |
|---|---|---|
| 입력 | 기능은 `FEATURE_MODULE_ID`, `FEATURE_CONTEXT_ID` 리터럴과 `FEATURE_MODULE`을 낸다. context는 경로·예산을 낸다 | `src/features/reference-feature/feature-module.ts`, `src/contexts/reference-context/context-module.ts:7-10` |
| 정책 | 생성기가 앱 → context → 기능 순서로 소유를 확인하고, 예산·중복 id·`VITE_PRODUCT_FEATURES` 선택을 적용한다. `feature-module.ts`도 `NOT_INSTALLED`도 없는 디렉터리는 실패한다 | `scripts/generate-product-feature-index.ts:187-239`, `:262-297` |
| 상태 변화 | 조립 카탈로그가 생성 인덱스를 투영한다. 키 중복은 `composeUniqueRecord`가 막는다 | `src/features/installed-feature-contracts.ts:23-39`, `src/platform/cardinality/compose-unique-record.ts:16-18` |
| 외부 I/O | 부트가 설정·매니페스트를 읽고 capability 객체(`http`, `telemetry`)를 만든다. 기능은 선언한 `needs`만 받는다 | `src/bootstrap/runtime-adapters.ts:592-598`, `src/features/feature-adapter-contribution.ts:177-190` |
| 실패 | 조립 검증 실패는 모듈 평가 시 throw한다. `main.tsx`가 앱 그래프를 동적 import해서 부트 실패 화면으로 받는다 | `src/bootstrap/main.tsx:14-17`, `src/bootstrap/render-boot-failure.tsx:25-28` |
| 결과 | 라우터가 모든 context를 `AppShell` 아래에 붙이고, gateway가 context 라우트 모듈을 늦게 읽어 leaf 라우트 하나를 렌더한다 | `src/presentation/routes/app-router.tsx:530-575`, `:435-527` |
### 2.2 피해가 큰 흐름 — 기능의 HTTP 호출과 자격증명
```
기능 → http capability(contractOperations) → V3 executor
→ attachCredentials(runtime-adapters) → 세션 상태 → credentialPatch
→ admitCredentialHeaders(프로필 허용 헤더) → fetch
```
| 단계 | 내용 | 위치 |
|---|---|---|
| 입력 | operation 계약이 `authProfileId`를 가진다. `auth: "none"`이면 `ANONYMOUS` 프로필이어야 한다 | `src/contracts/rest-profiles.ts:68-74`, `:297` |
| 정책 | executor는 모든 operation에서 `attachCredentials`를 부른다. 조립 루트의 구현은 프로필을 보지 않고 세션만 본다 | `src/adapters/http/http-execution-v3.ts:719`, `src/bootstrap/runtime-adapters.ts:501-531` |
| 상태 변화 | 없음(전송 전 판단) | — |
| 외부 I/O | 헤더가 프로필 허용 목록을 벗어나면 fetch 0회로 끝난다 | `src/adapters/http/http-contract-bridge.ts:80-85` |
| 실패 | `ANONYMOUS` 호출이 로그아웃이면 `UNAUTHENTICATED`, 로그인이면 `CREDENTIAL_HEADER_NOT_ALLOWED`(E1) | 09-01 |
| 결과 | 공개 API가 어느 세션 상태에서도 나가지 않는다. 방향은 fail-closed라 정보 노출은 없다 | — |
### 2.3 변경·삭제 흐름 — 제품이 템플릿을 받아 기능을 얹고 다시 동기화
```
제품이 기능 추가 → 틀에 안 맞는 부분(홈·레이아웃·capability·자격증명)을 템플릿 파일에 직접 수정
→ 템플릿이 같은 파일을 계속 수정(runtime-adapters.ts 15커밋)
→ 다음 동기화에서 3-way 충돌(memento 25경로, tech-log 67경로) → 손으로 병합
→ 템플릿 테스트를 제품 내용으로 다시 겨눔
```
| 단계 | 내용 | 위치 |
|---|---|---|
| 입력 | 템플릿 문서는 "중앙 카탈로그(`installed-*`)는 바뀌지 않는다", `runtime-adapters.ts`는 `indexedDb`일 때만 고친다고 적는다 | `docs/architecture/starter-experience.md:143-147` |
| 정책 | memento는 `feature-module.ts`로 설치했지만 홈·셸·capability·자격증명을 위해 템플릿 파일 4개를 고쳤다. tech-log는 제품 도메인을 `NOT_INSTALLED`로 표시하고 조립 파일 5개·부트 파일 4개·라우터를 고쳤다 | 6절, 09-02~09-04 |
| 상태 변화 | 두 제품 모두 `runtime-adapters.ts`, `app-router.tsx`, `installed-feature-contracts.ts`를 템플릿과 다르게 가진다 | D1 |
| 외부 I/O | 없음 | — |
| 실패 | 병합 누락은 타입·테스트가 일부만 잡는다. 제품이 조립 파일에 직접 끼운 값은 어떤 검사도 잡지 않는다(E3) | 09-04 |
| 결과 | 템플릿 수정(보안·계약 포함)이 들어오는 파일이 제품이 가장 많이 고친 파일과 겹친다. 제품이 고친 템플릿 테스트 파일은 memento 31개, tech-log 34개다(이 영역 원인 외 것도 포함) | 6절 |
기능 제거는 `test:sample-removal -- --feature=<id>`로 생성기 설치 기능에는 일반화돼 있다(`scripts/test-sample-removal.ts:29-38`). 생성기 밖에서 조립한 도메인에는 제거 경로가 없다(09-04).
## 3. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가
| 번호 | 관점 | 판정 | 근거·잔여 위험 |
|---|---|---|---|
| 1 | 코드 성숙도 | O | local-draft 쓰기 경로가 도메인 팩터리를 거친다(`local-draft-api.ts:60-73`). 조립 검증(중복 id·needs·예산)이 모듈 평가 시 throw한다 |
| 2 | 구조적 성숙도 | P | 템플릿 자체의 부트스트랩은 `installed-*`만 import한다. 그러나 `src/bootstrap`·`src/features/installed-*`가 기능 내부(`src/features/<x>/…`)를 직접 import하는 것을 막는 규칙이 없다(`.dependency-cruiser.json` 규칙 목록). E3: `NOT_INSTALLED` 디렉터리 직접 import가 `check:architecture`를 통과했다. tech-log 부트스트랩은 실제로 `features/tech-log/adapters/http/*`를 직접 import한다(제품 `runtime-adapters.ts` 38-42행) |
| 3 | 변경 용이성 | X (실제 제품 기능 추가 기준) | 템플릿 fixture 기능은 기능 디렉터리만 고쳐 설치된다(R1의 `two-feature-install-typecheck.test.ts` 통과). 실제 제품 2개는 둘 다 템플릿 소유 조립 파일을 고쳤다. 홈 교체·레이아웃·capability 추가·세션 밖 자격증명·제품 설정 키를 표현할 계약이 없다(09-02, 09-03). E2: 기능의 `/` 라우트는 오류 없이 가려진다 |
| 4 | 인지 부하 | P | 기능 작성자는 리터럴 선언 3종과 `defineFeatureModule` 추론만 알면 된다(39.4 기준 충족). 반면 `NOT_INSTALLED`가 세 가지 뜻으로 쓰인다(09-04). 틀 밖 요구는 제품마다 숨은 규약을 만든다: memento의 형식 없는 `ownsShell` 필드와 `APP_HOME` 허용 목록, tech-log의 `NOT_INSTALLED`="직접 조립" |
| 5 | 위험 가시성 | P | `needs` 누락은 기능 id와 capability 이름으로 실패한다(`feature-adapter-contribution.ts:186-189`). 자격증명 결정은 `attachCredentials` 안에 숨어 있고, 인증 프로필 차원을 보지 않는다는 사실이 호출부에서 보이지 않는다(09-01) |
| 6 | 실패 성숙도 | P | 모듈 평가 실패도 부트 실패 화면으로 간다(`main.tsx:14-17`). `ANONYMOUS` 호출은 안전한 방향으로 실패하지만 기능이 전혀 동작하지 않는다(09-01) |
| 7 | 운영 성숙도 | P | 모르는 `FEATURE_OVERRIDES` 키를 진단으로 남긴다(`runtime-adapters.ts:462-471`). 부트 실패는 설정 전이라 수집기로 갈 수 없다(설계 한계). SLO는 템플릿 범위 밖 |
| 8 | 디버깅 가능성 | P | 조립 오류는 키·기능·파일 이름을 담는다(`compose-unique-record.ts:17`, 생성기 `:291-293`). 기능 라우트가 `/`에서 가려지는 경우는 아무 신호가 없다(E2b). `ANONYMOUS` 실패 이유 `CREDENTIAL_HEADER_NOT_ALLOWED`는 원인(프로필 무시)과 멀다 |
| 9 | 유지보수 성숙도 | P | 이전 라운드 09-01~09-12는 코드에서 해소 확인(7절). 템플릿이 가장 자주 바꾸는 조립 파일(`runtime-adapters.ts` 15커밋, `app-router.tsx` 11커밋)을 두 제품도 고쳐, 동기화마다 손 병합이 반복된다(6절, D1·D2) |
| 10 | 테스트 성숙도 | P | 기능 2개 typecheck, 선택 빌드, needs 누락 테스트가 있고 통과한다(R1). 실제 조립 루트로 `ANONYMOUS` operation을 실행하는 테스트가 없다(09-01). "모든 카탈로그가 매니페스트를 참조" 테스트는 import 존재만 보고 직접 끼워 넣기를 놓친다(E3, `tests/unit/product-features.test.ts:175-208`) |
| 11 | 데이터 성숙도 | P | local-draft ABA는 주석으로만 막는다(`local-draft.ts:2-11`, FOLLOW-UP 09-08). 샘플 범위라 영향이 작다 |
| 12 | 동시성 성숙도 | > | 세대 fence·scope 판단은 03 영역(`adapters/query-cache`). 이 영역의 `attachCredentials`는 scope를 전송 전후 두 번 확인한다(`runtime-adapters.ts:502-504`, `:521-523`) |
| 13 | 확장성 | P | 기능 수 축: 2개 설치 typecheck 게이트(R1), context·app 예산(생성기 `:199-223`)이 있다. 설치 기능의 계약·메시지·런타임 설명자는 초기 그래프에 eager로 들어가고, 초기 JS 여유는 약 1.3KB다(FOLLOW-UP P1, 13 영역에서 측정). 제품 수 축: 제품 2개가 같은 조립 파일을 고친다(09-02, 09-03) |
| 14 | 성능 성숙도 | > | 번들 예산은 13 영역 |
| 15 | 보안 성숙도 | P | demo 인증 차단·외부 owner fail-closed는 유지된다. 자격증명 정책을 넓힐 방법이 조립 루트 closure 수정뿐이라, 제품이 fail-closed 코드를 손으로 병합한다(09-02). tech-log 주석은 그 수정 중 무한 재귀 결함을 한 번 냈다고 적는다(제품 `runtime-adapters.ts:496-530` 주석) |
| 16 | 의존성 성숙도 | - | 이 영역 고유 의존성 없음 |
| 17 | API / Contract 성숙도 | P | 템플릿이 설치한 `ANONYMOUS` 프로필 계약을 조립 루트가 지키지 않는다(09-01, E1). 기능 계약·컨텍스트 선언은 생성기와 조립 검증으로 강제된다 |
| 18 | 배포 성숙도 | > | 13 영역 |
| 19 | 설정 성숙도 | P | `VITE_PRODUCT_FEATURES`는 생성기 한 곳에서 적용된다(생성기 `:181-239`). 제품 전용 런타임 설정 키를 넣을 자리가 없어 tech-log는 템플릿 스키마(`src/bootstrap/runtime-config-schema.ts`, `src/contracts/release-artifacts.ts`)를 고쳤다(09-02) |
| 20 | 개발자 경험 | P | 기능 추가 안내가 실제 생성기 규칙과 맞는다(`starter-experience.md:112-147`). 그러나 "기능 디렉터리 밖에서 바꾸는 파일" 표가 실제 제품 경험과 다르다(09-02, 09-03) |
| 21 | Guardrail 성숙도 | P | 표시 없는 기능 디렉터리, needs 누락, 키 중복, 예산 초과는 막힌다. 조립 파일·부트스트랩에 기능 내부를 직접 끼우는 경로는 어떤 검사도 막지 않는다(E3, 09-04) |
| 22 | 추상화 성숙도 | P | `FeatureModule` 제네릭 6개는 호출부에서 추론된다. 기능 2개에서도 동작한다. `FeatureIndexedDbRepositories`는 확장 가능한 interface인데 `FeaturePlatformCapabilities`는 닫힌 type alias다(`feature-adapter-contribution.ts:14`, `:46-51`). 런타임 설명자는 `unknown`이라 제품이 붙인 필드(`ownsShell`)가 형식 없이 라우터로 흘러간다(09-03) |
| 23 | 일관성 | P | 위 22의 interface/alias 불일치. 플랫폼 라우트는 기능 소유가 아니라는 불변식이 테스트에만 있고(`product-features.test.ts:212-222`), memento는 그 테스트를 고쳐 `APP_HOME`을 기능 소유로 바꿨다 |
| 24 | 네이밍 / 의미 성숙도 | P | `NOT_INSTALLED`가 (1) 생성기 표시 파일, (2) 런타임 상태 "선언됐지만 선택 안 됨"(`src/contracts/product-features.ts:32`, `:122`), (3) tech-log의 "직접 조립"으로 쓰인다(09-04). 두 제품 모두 앱 id `template-app`과 `TEMPLATE_APP_MODULE`을 그대로 쓴다(두 기록의 follow-up) |
| 25 | 조직 확장성 | X (구조 + 실제 다운스트림 증거) | 팀은 하나지만 제품이 2개다. 두 제품이 같은 템플릿 파일 7개(`src/` 기준)를 고쳤고, 그중 조립 파일 3개는 확장 지점이 없어서 고쳤다(6절). 기능 팀이 플랫폼 소유 파일을 고치지 않고는 홈·레이아웃·capability를 바꿀 수 없다 |
| 26 | Ownership 성숙도 | > | 파일별 템플릿/제품 소유 표(30.3)는 14 영역 문서 범위. 이 영역에서는 소유가 섞인 파일 하나를 09-05로 적었다 |
| 27 | 삭제 가능성 | P | 생성기 설치 기능은 `--feature=<id>`로 제거를 검증한다. 제거 검증은 lint·`check:i18n`·e2e를 건너뛴다(`scripts/test-sample-removal.ts:415-428`, FOLLOW-UP 09-07). 생성기 밖에서 조립한 도메인은 제거 경로가 없다(09-04) |
| 28 | 회복 가능성 | P | 부트 실패 화면에 재시도가 있다(`boot-error-shell.tsx:24-38`). reload 반복은 TTL guard가 막는다(`release-mismatch-recovery.ts:60-90`). 부트 실패 후 자동 회복은 의도적으로 없다 |
집계(이 영역에서 판정한 23개): 충족 1 · 부분 충족 20 · 미충족 2(3, 25) · 미검증 0. 적용 제외 1(16), 다른 영역 4(12, 14, 18, 26).
## 4. 설계 선택 설명 (41절)
### 4.1 조립 카탈로그(`installed-*`)를 생성 인덱스의 투영으로만 둔다
1. **무엇이 필요한가.** 기능이 늘어도 중앙 파일을 고치지 않아야 한다. 기능 선택(`VITE_PRODUCT_FEATURES`)과 킬스위치가 모든 소비자에게 같게 적용돼야 한다.
2. **지킬 성질.** 설치된 기능 집합은 생성 인덱스 하나에서 나온다. 키 중복은 부트 전에 실패한다.
3. **현재 보장.**
- 확인한 사실: 카탈로그 5개가 `INSTALLED_PRODUCT_FEATURE_*`만 투영한다(`installed-feature-contracts.ts:23-96`, `installed-feature-adapters.ts:11-47`). 생성기가 선택을 적용한다. 테스트가 매니페스트 import를 확인한다(`product-features.test.ts:175-208`).
- 보장하지 않는 것: 매니페스트 **외의** 값을 카탈로그에 끼우는 것(E3). 틀 밖 요구(홈 교체, 직접 조립 도메인)를 표현하는 방법.
- 기록된 의도: "Adding a feature changes its descriptor and the generated index, not this composer"(`installed-feature-adapters.ts:25-29`), "The central catalogs … do not change"(`starter-experience.md:145-147`).
4. **대안.** (A) 현 상태. (B) 템플릿이 빈 채로 내보내는 제품 소유 파일(예: `src/features/product-composition.ts`) 하나를 카탈로그가 매니페스트와 함께 읽는다. 템플릿은 그 파일을 절대 고치지 않는다. (C) 모든 제품 도메인이 `feature-module.ts`로 들어오게 틀(레이아웃·capability)을 넓힌다(4.2, 4.3).
5. **비용 비교.** (A) 추가 비용 0. 실제 제품은 카탈로그를 고쳐 충돌을 떠안는다(tech-log 5개, memento 1개). (B) 파일 1개 + 가드 테스트 1개. 직접 조립 도메인은 여전히 선택·킬스위치 밖이지만, 그 사실이 파일 이름으로 드러나고 템플릿 파일 충돌이 사라진다. (C) 가장 깨끗하지만 4.2·4.3 작업이 먼저 필요하다. 기존 제품의 이행 비용이 크다(tech-log follow-up 6: 라우터 전체 이동).
6. **현재 조건에서의 판단.** 투영 구조 자체는 유지할 근거가 있다. 기능 2개 이상과 선택 빌드가 테스트로 고정돼 있다(R1). 부족한 것은 틀 밖 요구의 자리다. 단기에는 (B)의 가드 테스트만으로도 조용한 splice를 드러낼 수 있다. 목표는 (C)다.
7. **재검토 조건.** 4.2·4.3 확장 지점이 생겨 두 제품이 모두 `feature-module.ts`로 옮기면 (B)의 제품 소유 파일은 지운다.
### 4.2 `createRuntimeAdapters` 한 함수가 capability 객체와 자격증명 정책을 만든다
1. **무엇이 필요한가.** 기능은 선언한 capability만 받는다. 자격증명은 전송 직전에 scope·세션을 확인하고 실패하면 fetch 0회로 닫힌다.
2. **지킬 성질.** 세션이 없으면 인증 요청을 익명으로 낮추지 않는다. scope가 바뀌는 중에는 보내지 않는다. 프로필이 허용한 헤더만 나간다.
3. **현재 보장.**
- 확인한 사실: capability 객체는 `http`·`telemetry` 두 개다(`runtime-adapters.ts:592-595`). 타입은 `FeaturePlatformCapabilities`라는 닫힌 alias다(`feature-adapter-contribution.ts:46-51`). `attachCredentials`는 scope → 세션 상태 → `credentialPatch` 순서로 판단하고 프로필을 보지 않는다(`runtime-adapters.ts:501-531`). owner에게는 origin·method·operationId만 전달된다(`:513-520`).
- 보장하지 않는 것: `ANONYMOUS` 프로필(09-01). 제품의 추가 capability·세션 밖 자격증명(CSRF 쿠키, BFF)·제품 설정 키.
- 기록된 의도: `indexedDb`는 opt-in이라 제품이 이 객체에 추가한다(`runtime-adapters.ts:586-591`, `starter-experience.md:143`). "The provider is a composition capability; feature use cases never import it"(`feature-adapter-contribution.ts:10-13`).
4. **대안.** (A) 현 상태: 제품이 closure를 고친다. (B) 제품 소유 확장 파일(예: `src/bootstrap/product-composition.ts`, 템플릿은 빈 구현)을 두고, `FeaturePlatformCapabilities`를 `FeatureIndexedDbRepositories`처럼 확장 가능한 interface로 바꾼다. `attachCredentials`는 (1) `ANONYMOUS`면 빈 헤더로 READY, (2) 제품이 프로필 id로 등록한 자격증명 제공자가 있으면 그것, (3) 나머지는 지금의 세션 경로로 나눈다. (C) 기능 계약 기여가 인증 프로필과 자격증명 제공자를 함께 가져온다.
5. **비용 비교.** (A) 템플릿 비용 0. 두 제품이 같은 closure를 고쳤다(memento +61줄, tech-log +118줄). 이 파일은 템플릿이 가장 자주 바꾸는 파일이다(D2 15커밋). fail-closed 코드를 손으로 병합한다. (B) 템플릿 수십 줄 + 분기 테스트. scope·세션 fence는 템플릿에 남고, 제품 코드는 판정만 제공한다. 제품 제공자가 fence를 우회하지 못하게 호출 순서를 템플릿이 쥔다. (C) 가장 유연하지만 인증 정책이 기능마다 흩어져 보안 리뷰 범위가 넓어진다.
6. **현재 조건에서의 판단.** 한 함수에서 fence 순서를 쥐는 것은 옳다(39.7: 같은 요청의 상태를 조율해야 한다). 바꿀 것은 확장 방법이다. (B)가 fence 소유를 유지하면서 제품 수정 지점을 템플릿 밖으로 옮긴다.
7. **재검토 조건.** 제품이 요청별 자격증명(예: 테넌트 전환)처럼 fence 순서 자체를 바꿔야 하면 (B)의 제공자 계약을 다시 본다. 제품이 1개로 줄면 (A)의 비용이 작아진다.
### 4.3 모든 context를 `AppShell` 아래에 두고 플랫폼이 홈을 가진다
1. **무엇이 필요한가.** 라우트 경계·청크 복구·not-found 처리를 한 곳에서 준다. 플랫폼 화면(브랜드 링크, not-found 링크)은 기능 없이도 완결돼야 한다.
2. **지킬 성질.** 모르는 URL은 `NOT_FOUND`로 간다. context 라우트는 늦게 읽힌다. 기능을 꺼도 플랫폼 탐색이 사라지지 않는다(`product-features.test.ts:216-219` 주석).
3. **현재 보장.**
- 확인한 사실: 라우터는 `APP_SHELL` 하나 아래에 플랫폼 라우트와 context gateway를 둔다(`app-router.tsx:530-575`). gateway는 context 라우트 중 leaf 하나만 렌더하고, 경로 없는 레이아웃 라우트의 `Component`는 쓰지 않는다(`:500-527`). `APP_HOME`은 플랫폼 소유다(`src/contracts/routes.ts:20-32`). 같은 id는 throw, 다른 id의 `/`는 가려진다(E2, E2b).
- 보장하지 않는 것: 기능/컨텍스트가 자기 레이아웃을 가지는 것, 제품 홈.
- 기록된 의도: "shell, providers, boundaries … remain reusable", "replaceable at the page level"(`starter-experience.md:1-6`, 실행 순서도 `:18`).
4. **대안.** (A) 현 상태. (B) context 선언에 레이아웃을 둔다(예: `context-routes.ts`가 선택적으로 레이아웃 컴포넌트를 내보내고, 라우터는 그런 context를 자기 레이아웃 아래 등록 경로별 자식으로 붙인다). 플랫폼은 "기능이 대신할 수 있는 라우트 id" 목록(`APP_HOME`)을 선언하고, 소유 기능은 최대 하나로 제한한다. memento 브리지가 이 모양이다(제품 `app-router.tsx:548-640`, `installed-feature-contracts.ts:26-61`). (C) `AppShell` 자체를 제품 소유 파일 하나로 교체 가능하게 한다.
5. **비용 비교.** (A) 비용 0. memento는 라우터 +145줄·카탈로그 +32줄 브리지를 가진다. tech-log는 라우터를 통째로 바꿨고 context gateway를 붙이지 않아 생성기 설치 기능을 쓸 수 없다(제품 `app-router.tsx`에 `ContextRouteGateway` 0회, follow-up 7). (B) 템플릿 라우터 수십~백 줄 + gateway·not-found·레이아웃 청크 실패 테스트. 설명자 필드를 형식 있는 계약으로 올린다. 기능을 끈 경우 `/`를 무엇으로 보일지 결정이 필요하다(memento는 현재 `DisabledFeatureSurface`가 된다). (C) 단순하지만 레이아웃 그룹이 둘인 tech-log(PUBLIC/STUDIO)를 표현하지 못한다.
6. **현재 조건에서의 판단.** 단일 셸은 템플릿 데모에는 맞다. 실제 제품 2개가 모두 이 가정을 깼다. (B)가 두 제품의 요구를 모두 담는 가장 작은 공통 형태다. 근거는 memento 브리지가 이미 템플릿 경계·청크 복구를 유지하며 동작한다는 기록(26개 시각 비교 통과, 주장)이다.
7. **재검토 조건.** 세 번째 제품이 레이아웃 외의 라우터 변형(예: 중첩 탭 라우팅)을 요구하면 (B)의 선언 형태를 다시 본다.
## 5. 발견 사항 (36.3)
### 09-01 조립 루트의 자격증명 판단이 인증 프로필을 보지 않아 `ANONYMOUS` operation이 절대 전송되지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 17, 6, 5, 10, 3, 30.5 (HTTP 실행 쪽은 03 영역과 겹침) |
| 근거 | 템플릿은 `ANONYMOUS` 프로필을 설치하고(`src/contracts/rest-profiles.ts:68-74`), `auth: "none"` operation은 이 프로필이어야 한다(`:297`). executor는 모든 operation에서 `attachCredentials`를 부른다(`src/adapters/http/http-execution-v3.ts:719`). 조립 루트 구현은 세션이 `authenticated`가 아니면 `UNAUTHENTICATED`를 돌려준다(`src/bootstrap/runtime-adapters.ts:509-511`). 로그인 상태면 세션의 `authorization` 패치를 그대로 주고, 프로필 허용 목록이 비어 있어 거절된다(`src/adapters/http/http-contract-bridge.ts:80-85`). owner에게 프로필 id가 전달되지 않아 owner가 바로잡을 수도 없다(`runtime-adapters.ts:513-520`). **E1**: 로그아웃 `UNAUTHENTICATED`·fetch 0회, 로그인 `AUTH_INTEGRATION_FAILURE`/`CREDENTIAL_HEADER_NOT_ALLOWED`·fetch 0회. 기존 테스트는 테스트용 `attachCredentials`를 쓰므로(`tests/integration/http-execution-v3-auth-profile.test.ts:115-222`) 조립 루트를 거치지 않는다 |
| 다운스트림 증거 | tech-log가 제품에서 같은 결함을 만나 고쳤다: "falling through below refused every public read before it left the browser. The public site rendered its terminal error surface on every screen"(제품 `src/bootstrap/runtime-adapters.ts:588-598`). memento는 BFF 프로필 id를 세션 확인 앞에서 분기해 피했다(제품 `runtime-adapters.ts:530-545`) |
| 발생 조건 | 제품이 공개 API(`auth: "none"`) operation을 V3 경로로 설치 |
| 영향 | 해당 기능은 어느 세션 상태에서도 요청을 보내지 못한다. 방향은 fail-closed라 정보 노출은 없다. 실패 이유가 "허용되지 않은 자격증명 헤더"라 원인을 찾기 어렵다 |
| 심각도·우선순위 | High · P1 — 템플릿이 지원한다고 설치한 프로필이 기본 조립에서 동작하지 않는다. 공개 화면은 흔한 요구다. 실제 제품 1곳이 모든 공개 화면 실패로 만났다 |
| 통제·증거 | 목표 M3(조립 루트 경유 테스트) / 확인 M0 · E2(E1 실험) + 다운스트림 기록(E0) |
| 확실성과 남은 가정 | 로그아웃·demo 로그인은 재현했다. 외부 owner 로그인은 코드 경로로만 확인했다. 브라우저 화면은 보지 않았다 |
| 결정의 근거 | 적용 제외 — 프로필 계약을 조립 루트가 지키지 않는 구현 결함이다. 확장 구조 선택은 09-02에서 다룬다 |
| 이해 비용 | 원인을 찾으려면 executor·bridge·조립 루트 세 파일을 함께 읽어야 한다 |
| 최소 개선 방향 | `attachCredentials` 첫 판단으로, operation의 프로필 transport가 `ANONYMOUS`면 세션을 보지 않고 `{ kind: "READY", headers: {} }`를 돌려준다(scope fence는 그대로 먼저 확인). tech-log 제품 수정과 같은 모양이다 |
| 대안 비교 | 적용 제외 — 계약이 이미 정해져 있다(`rest-profiles.ts:159-168`: 익명 프로필은 자격증명을 가질 수 없다) |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 몇 줄. 로그인 상태에서 익명 호출에 토큰이 붙지 않는 것이 의도된 결과다 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 실제 `createRuntimeAdapters`로 `ANONYMOUS` operation을 로그아웃·로그인 상태에서 실행하면 fetch 1회, 자격증명 헤더 없음 |
| 검증 방법 | `tests/unit/runtime-adapters.test.ts`에 E1과 같은 케이스(fixture contribution 설치) 추가. 수정 전 코드에서 실패하는지 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 09-02 제품 capability·자격증명·제품 설정을 넣을 확장 지점이 없어, 두 제품 모두 `runtime-adapters.ts`를 직접 고친다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험(다운스트림 diff로 발생 확인) |
| 관련 관점 | 3, 9, 25, 22, 15, 19, 20, 13, 30.3, 30.4, 30.7 |
| 근거 | capability 타입은 닫힌 alias다(`src/features/feature-adapter-contribution.ts:46-51`). 반면 IndexedDB 저장소는 확장 가능한 interface다(`:14`). capability 객체와 자격증명 판단은 637줄 `createRuntimeAdapters` 안 closure다(`src/bootstrap/runtime-adapters.ts:501-531`, `:592-598`). 문서는 이 파일을 `indexedDb`일 때만 고친다고 적는다(`docs/architecture/starter-experience.md:143`). **memento**(`d3810a0`): `FeaturePlatformCapabilities`에 `offsetUpload`·`runtime` 추가(제품 `feature-adapter-contribution.ts:49-55`), `attachCredentials`에 프로필 id 분기(제품 `runtime-adapters.ts:530-545`), capability 객체 확장(`:649-655`), 제품 전송 어댑터를 템플릿 `src/adapters/http/`와 배럴에 추가, `rest-profiles.ts`에 프로필 2개·헤더 이름 1개 추가. **tech-log**(`42d1ae1f`): CSRF 제공자와 전방 참조 stub(제품 `runtime-adapters.ts:531-560`), 자격증명 분기(`:582-598`), capability 확장(`:706-710`), 부트 전에 BFF owner 설치(제품 `create-runtime-composition.ts:47`), 제품 설정 키(제품 `runtime-config-schema.ts:58`, `:156`). 템플릿은 같은 기간 이 파일을 15커밋 고쳤다(D2) |
| 발생 조건 | 제품이 `http`·`telemetry`·`indexedDb` 외 capability, 세션 owner 밖 자격증명(쿠키 CSRF·BFF), 제품 런타임 설정 키 중 하나라도 필요 |
| 영향 | 템플릿 수정(보안·계약 포함, 예: `readSubject` 필수화, 03-03 correlation, 09-05)이 들어오는 파일을 제품이 가장 많이 고친 상태다. 매 동기화에 fail-closed 코드를 손으로 병합한다. tech-log는 이 closure를 고치다 무한 재귀 결함(C1)을 한 번 냈다고 기록한다(제품 `runtime-adapters.ts:496-530` 주석) |
| 심각도·우선순위 | Medium · P1 — 템플릿 자체의 기능 실패는 아니다. 그러나 두 제품 모두에서 발생했고, 템플릿 패치 전파(30.4)라는 핵심 약속을 매번 손 병합으로 만든다. 제품을 더 늘리기 전에 해결할 항목이다 |
| 통제·증거 | 목표 M2(제품 소유 확장 파일 + 가드) / 확인 M0 · E3(실제 다운스트림 diff 2건, D1·D2) |
| 확실성과 남은 가정 | 두 제품의 수정은 diff로 확인했다. "다음 동기화에서도 충돌한다"는 템플릿 변경 빈도로 낸 추정이다 |
| 결정의 근거 | 확인한 사실: 위 근거. 기록된 의도: `indexedDb`만 opt-in으로 제품이 추가(`runtime-adapters.ts:586-591`). 리뷰어 추론: fence 순서를 한 함수가 쥐는 것은 맞지만(39.7), 제품 확장 방법이 그 함수의 수정뿐인 것은 30.3("사용자가 실제로 바꾸는 정책은 안정된 수정 지점으로 제공")에 어긋난다 |
| 이해 비용 | 제품 개발자는 capability 하나를 추가하려고 조립 루트 전체(스코프 fence, 세션, 텔레메트리 수명)를 읽어야 한다. 동기화 담당자는 양쪽 변경을 줄 단위로 맞춘다 |
| 최소 개선 방향 | 4.2의 (B). (1) `FeaturePlatformCapabilities`를 확장 가능한 interface로 바꾼다. (2) 템플릿이 빈 구현으로 내보내는 제품 소유 파일 하나(예: `src/bootstrap/product-composition.ts`)가 추가 capability와 "프로필 id → 자격증명 제공자"를 돌려준다. (3) `attachCredentials`는 fence → `ANONYMOUS`(09-01) → 등록 제공자 → 세션 순서를 템플릿이 쥔다. (4) 제품 설정 키는 제품 소유 zod 조각을 strict 스키마에 합치는 방식으로 연다 |
| 대안 비교 | 4.2절. (A) 현 상태: 템플릿 비용 0, 제품당 동기화 비용 반복. (C) 기능 기여가 인증 제공자를 가져옴: 유연하지만 인증 정책이 기능마다 흩어진다 |
| 단순화의 보존 조건 | 인증 요청을 익명으로 낮추지 않는다. scope 전환 중에는 보내지 않는다. 프로필 허용 헤더만 나간다. 제품 제공자가 예외를 던지면 `CREDENTIAL_OWNER_FAILED`로 닫힌다 |
| 비용·부작용 | 템플릿 수십 줄 + 분기 테스트. 두 제품은 한 번 이행해야 한다(제품 코드를 새 파일로 옮김) |
| 재검토 조건 | 제품이 fence 순서 자체를 바꿔야 하는 요구(요청별 테넌트 전환 등)가 생기면 제공자 계약을 다시 본다 |
| 완료 기준 | 두 제품의 현재 요구(offsetUpload, runtime 값, BFF 쿠키 XSRF, Studio CSRF, 제품 설정 키)를 템플릿 파일 수정 없이 표현할 수 있다. 템플릿 픽스처 제품이 그 경로를 한 번 쓴다 |
| 검증 방법 | 픽스처 제품 파일로 capability 1개·프로필 제공자 1개를 추가하고 `check:types`·`runtime-adapters` 테스트 통과. 제공자가 fence 전에 호출되지 않는지 순서 테스트 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 09-03 라우터 조립이 `AppShell` 한 틀과 플랫폼 홈을 고정해, 기능이 `/`나 자기 레이아웃을 가질 수 없다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험(다운스트림 diff로 발생 확인) + 확인된 결함(기능의 `/` 라우트가 조용히 가려짐) |
| 관련 관점 | 3, 2, 22, 25, 8, 23, 27, 32.4, 30.3 |
| 근거 | (a) 홈: `APP_HOME`은 플랫폼 소유다(`src/contracts/routes.ts:20-32`). 같은 id를 기능이 선언하면 `composeUniqueRecord`가 throw한다(`src/platform/cardinality/compose-unique-record.ts:16-18`, E2(가)). 다른 id로 `/`를 선언하면 오류 없이 두 라우트가 공존하고, 라우터는 플랫폼 index를 고른다(E2(나), E2b). 경로 중복 검사는 어디에도 없다. (b) 레이아웃: 라우터는 모든 context를 `APP_SHELL` 아래에 붙인다(`src/presentation/routes/app-router.tsx:530-575`). gateway는 leaf만 렌더하고 context 라우트 모듈의 레이아웃 `Component`를 쓰지 않는다(`:500-527`). 기능 런타임 설명자는 `unknown`이라 레이아웃 선언 계약이 없다(`src/features/feature-module.ts:34-38`, `:63-70`). **memento**: `APP_HOME` 허용 목록(제품 `installed-feature-contracts.ts:26-61`), 설명자의 형식 없는 `ownsShell` 필드와 라우터 브리지(제품 `app-router.tsx:548-640`, `memento-feature-runtime-descriptor.ts`), 템플릿 테스트 2개 수정. **tech-log**: 라우터를 PUBLIC/STUDIO 그룹 라우터로 교체했고 `ContextRouteGateway`를 붙이지 않는다(제품 `app-router.tsx`에서 0회, 기록 follow-up 7) |
| 발생 조건 | 제품 홈이 기능 화면이거나, 기능 화면이 `AppShell`이 아닌 자기 레이아웃을 쓴다. 두 제품 모두 해당 |
| 영향 | (1) 제품마다 템플릿 라우터·조립 카탈로그에 브리지를 넣고 동기화마다 병합한다(`app-router.tsx` 11커밋). (2) tech-log에서는 템플릿의 기능 설치 경로(context gateway)가 꺼져 생성기 설치 기능을 쓸 수 없다. (3) memento는 `APP_HOME`을 기능 소유로 바꿔 "기능을 꺼도 플랫폼 탐색은 남는다"는 템플릿 불변식을 제품에서 깼다(제품 `product-features.test.ts` 수정). (4) 기능이 다른 id로 `/`를 선언한 실수는 아무 신호 없이 화면에서 사라진다 |
| 심각도·우선순위 | Medium · P1 — 템플릿 자체의 기능 실패는 아니다. 두 제품 모두에서 발생했고, 한 제품에서는 템플릿의 주 확장 모델을 끄는 결과가 됐다 |
| 통제·증거 | 목표 M3(선언 + 조립 검증) / 확인 홈 교체 M0, 경로 충돌 M0, 레이아웃 M0 · E2(E2·E2b) + E3(다운스트림 diff 2건) |
| 확실성과 남은 가정 | 조립·매칭 동작은 실험으로 확인했다. memento 브리지가 브라우저에서 동작한다는 것은 제품 기록의 주장(시각 비교 26개 통과)이다 |
| 결정의 근거 | 확인한 사실: 위 근거. 기록된 의도: 셸·경계는 재사용, 페이지 수준에서 교체(`starter-experience.md:1-6`). 리뷰어 추론: "페이지 교체"로는 홈 소유와 레이아웃을 표현하지 못한다. 두 제품이 같은 두 요구를 냈다 |
| 이해 비용 | 제품 개발자는 라우터 내부(gateway 매칭, 플랫폼 index 우선순위)를 알아야 브리지를 만들 수 있다. memento 브리지는 약 100줄의 새 규약이다 |
| 최소 개선 방향 | 4.3의 (B). (1) 플랫폼이 "기능이 대신할 수 있는 라우트 id" 목록(`APP_HOME`)을 선언하고, 소유 기능은 최대 하나, 소유 기능이 꺼지면 플랫폼 홈으로 돌아간다. (2) context가 선택적 레이아웃을 선언하면(예: `context-routes.ts`의 레이아웃 export 또는 context 선언 리터럴) 라우터가 그 context를 자기 레이아웃 아래 등록 경로별 자식으로 붙인다. 모르는 URL은 여전히 `AppShell`의 `NOT_FOUND`로 간다. (3) 조립 시 라우트 경로 중복을 검사한다 |
| 대안 비교 | 4.3절. (A) 현 상태: 제품마다 브리지. (C) `AppShell` 통째 교체: 레이아웃 그룹이 둘인 제품을 못 담는다 |
| 단순화의 보존 조건 | context 라우트는 늦게 읽힌다. gateway의 경계·청크 복구·not-found 처리가 레이아웃 context에도 적용된다. 플랫폼 라우트는 기능을 꺼도 남는다 |
| 비용·부작용 | 라우터 수십~백 줄, 테스트(레이아웃 청크 실패, not-found 통과, 홈 소유 기능 비활성화). 레이아웃 청크가 페이지 청크보다 먼저 한 번 더 내려온다(memento 기록: 약 17KB) |
| 재검토 조건 | 세 번째 제품이 레이아웃 외 라우터 변형을 요구하면 선언 형태를 다시 본다 |
| 완료 기준 | memento의 두 브리지와 tech-log의 PUBLIC/STUDIO 구성을 템플릿 라우터 수정 없이 선언으로 표현할 수 있다. 다른 id의 `/` 중복은 조립 단계에서 실패한다 |
| 검증 방법 | 픽스처 context 2개(자기 레이아웃, `APP_HOME` 대체)를 설치한 컴포넌트 테스트. 경로 중복 픽스처가 부트 전에 실패하는지 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 09-04 생성기 밖에서 조립하는 제품 도메인의 공식 경로가 없고, `NOT_INSTALLED` 표시와 조립 파일 직접 수정을 아무 검사도 구분하지 못한다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 2, 21, 24, 27, 4, 9, 30.7 |
| 근거 | 생성기는 `NOT_INSTALLED` 파일의 **존재만** 본다. 내용은 읽지 않는다. `feature-module.ts`가 있으면 표시를 무시하고 설치한다(`scripts/generate-product-feature-index.ts:283-294`). 같은 이름이 런타임 상태 "선언됐지만 선택 안 됨"으로도 쓰인다(`src/contracts/product-features.ts:32`, `:122`). 표시한 디렉터리는 선언되지 않으므로 그 상태로 보고되는 일이 없다. 조립 파일·부트스트랩이 기능 내부를 import하는 것을 막는 의존성 규칙이 없다(`.dependency-cruiser.json`). "모든 카탈로그가 매니페스트를 참조" 테스트는 import 존재만 본다(`tests/unit/product-features.test.ts:175-208`). 설치 표면 테스트는 `REFERENCE_*` 이름만 본다(`tests/features/feature-installation-surface.test.ts:3-6`). **E3**: `NOT_INSTALLED` 디렉터리에서 값을 가져와 `ROUTE_REGISTRY`에 끼운 변이가 테스트 19개와 `check:architecture`를 모두 통과했다. **tech-log**: TechLog에 `NOT_INSTALLED`를 두고 "설치 안 됨이 아니라 직접 조립"이라고 적었다(제품 `src/features/tech-log/NOT_INSTALLED`). 조립 파일 5개를 고치고(예: 제품 `installed-feature-adapters.ts:59`), 템플릿 테스트 3개를 TechLog 예외로 고쳤다(`product-feature-selection-build.test.ts`, `installed-feature-messages.test.ts`, `product-features.test.ts`) |
| 발생 조건 | 제품 도메인이 템플릿 틀(09-02, 09-03)에 안 맞아 생성기 밖에서 조립 |
| 영향 | 그 도메인은 `VITE_PRODUCT_FEATURES`, `FEATURE_OVERRIDES`, 플랫폼 개요의 기능 목록, `test:sample-removal`의 적용을 받지 않는다. 이 사실이 코드 경계가 아니라 표시 파일의 자연어 설명에만 남는다. 누군가 실수로 조립 파일에 기능을 직접 끼워도 같은 이유로 검출되지 않는다 |
| 심각도·우선순위 | Medium · P2 — 원인의 큰 부분은 09-02·09-03이다. 이 항목은 "우회 경로의 이름과 검출"만 다룬다. 두 원인이 해결되면 필요성이 줄어든다 |
| 통제·증거 | 목표 M3(직접 조립 검출) / 확인 M0 · E2(E3 변이) + E3(tech-log diff) |
| 확실성과 남은 가정 | 변이 생존은 재현했다. `check:registries`·`test:sample-removal`에서 잡히는지는 돌리지 않았다(라우트 레지스트리 경로라 잡히지 않을 것으로 추론) |
| 결정의 근거 | 확인한 사실: 위 근거. 기록된 의도: 표시는 "not a product feature"인 아키텍처 샘플용(`src/features/local-draft-feature/NOT_INSTALLED`, `starter-experience.md:104-106`의 "the one intentional example"). 리뷰어 추론: 제품이 졸업(30.7)할 공식 경로가 없어 샘플용 표시가 우회로로 쓰였다 |
| 이해 비용 | 새 담당자는 `NOT_INSTALLED`를 볼 때마다 파일 내용과 조립 파일을 함께 읽어야 뜻을 안다 |
| 최소 개선 방향 | (1) 조립 파일(`src/features/installed-*`)과 `src/bootstrap/`가 `src/features/<x>/`를 직접 import하지 못하게 의존성 규칙을 추가하고, 허용할 곳은 4.1의 제품 소유 조립 파일 하나로 둔다. (2) 표시 이름을 뜻대로 나눈다(예: 샘플은 `NOT_A_FEATURE`, 직접 조립은 제품 소유 조립 파일에 선언). (3) `feature-module.ts`와 표시가 함께 있으면 생성기가 실패한다 |
| 대안 비교 | 4.1절. (A) 현 상태. (B) 제품 소유 조립 파일 + 가드. (C) 모든 도메인을 `feature-module.ts`로(09-02·09-03 선행) |
| 단순화의 보존 조건 | 생성기 설치 기능의 선택·킬스위치·제거 검증은 그대로다. 표시 없는 디렉터리는 계속 실패한다 |
| 비용·부작용 | 규칙 1개, 생성기 몇 줄, tech-log 이행(조립 코드를 제품 소유 파일로 옮김) |
| 재검토 조건 | 모든 제품 도메인이 `feature-module.ts`로 옮겨지면 제품 소유 조립 파일과 그 예외 규칙을 지운다 |
| 완료 기준 | E3 변이가 `check:architecture`에서 실패한다. 직접 조립 도메인이 파일 경계로 드러난다 |
| 검증 방법 | E3 변이를 다시 적용해 실패 확인. 표시 + `feature-module.ts` 동시 존재 픽스처로 생성기 실패 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 09-05 제품이 고치도록 설계한 선택 파일에 템플릿 상태 설명이 같은 블록으로 섞여 있다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 9, 25, 30.3 |
| 근거 | `installed-runtime-capabilities.ts`는 "Adding an entry here is what installs a capability"라며 제품 수정 지점으로 설계됐다(`src/features/installed-runtime-capabilities.ts:15-20`). 같은 블록의 주석이 "Current template state"를 설명하고(`:22-33`), 바로 아래 상수가 제품 선택이다(`:35-41`). memento는 상수와 주석을 함께 고쳤다(SW `ACTIVE`) |
| 발생 조건 | 템플릿이 선택 설명 주석이나 기본값을 고침 |
| 영향 | 제품이 의도대로 쓴 파일인데도 동기화에서 주석 충돌이 난다. 영향은 작다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | 목표 M1 / 확인 M1 · E3(memento diff) |
| 확실성과 남은 가정 | 이번 동기화에서 이 파일은 템플릿 변경이 0이라 실제 충돌은 없었다 |
| 결정의 근거 | 적용 제외 — 파일 배치의 작은 정리다 |
| 이해 비용 | 작다 |
| 최소 개선 방향 | 템플릿 상태 설명을 문서(`optional-adapter-recipes.md`)로 옮기고, 파일에는 "이 상수는 제품이 소유한다" 한 줄만 둔다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 주석 이동 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 제품이 상수만 바꿔도 되고 템플릿 설명 변경과 줄이 겹치지 않는다 |
| 검증 방법 | 문서 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
## 6. 다음 동기화에서 충돌이 반복될 파일 (25, 9)
기준: `af3d8e6` 대비 제품이 고친 파일(D1)과 `ebea300..af3d8e6`에서 템플릿이 고친 횟수(D2). 이번 동기화에서 실제 충돌 경로는 memento 25개, tech-log 67개였다(두 기록의 "Conflicts" 절).
| 파일 | 고친 제품 | 제품이 고친 이유 | 템플릿 변경(커밋) | 원인 발견 |
|---|---|---|---|---|
| `src/bootstrap/runtime-adapters.ts` | 둘 다 | 제품 capability(`offsetUpload`, `runtime`, `studioSource`, `csrf`), 프로필별 자격증명(BFF 쿠키 XSRF, Studio CSRF), `ANONYMOUS` 우회 | 15 | 09-01, 09-02 |
| `src/presentation/routes/app-router.tsx` | 둘 다 | memento 셸 브리지, tech-log PUBLIC/STUDIO 라우터 전체 교체 | 11 | 09-03 |
| `src/features/installed-feature-contracts.ts` | 둘 다 | memento `APP_HOME` 허용 목록, tech-log 라우트·스키마 직접 조립 | 3 | 09-03, 09-04 |
| `src/contracts/rest-profiles.ts` | 둘 다 | 제품 인증 프로필·자격증명 헤더 이름 추가 | 3 | 09-02 (레지스트리 자체는 07 영역) |
| `src/features/feature-adapter-contribution.ts` | memento | 닫힌 `FeaturePlatformCapabilities`에 capability 추가 | 3 | 09-02 |
| `src/features/installed-{feature-adapters,contract-contributions,feature-messages}.ts`, `installed-feature-runtimes.tsx` | tech-log | 생성기 밖 도메인을 직접 조립 | 1~3 | 09-04 |
| `src/bootstrap/create-runtime-composition.ts` | tech-log | 번들 안에서 BFF 세션 owner 설치 | 1 | 09-02 |
| `src/bootstrap/runtime-config-schema.ts` (+ `src/contracts/release-artifacts.ts`) | tech-log | 제품 런타임 설정 키 | 1 (+3) | 09-02 |
| `src/features/installed-runtime-capabilities.ts` | memento | 설계된 수정 지점(SW `ACTIVE`). 템플릿 설명 주석과 제품 상수가 한 블록에 있다 | 0 | 09-05 |
| `src/bootstrap/main.tsx` | tech-log | 제품 폰트·스타일시트 import | 2 | > 08 영역(스타일 등록 지점) |
| `src/application/view-models/async-state.ts` | tech-log | `data: null`을 데이터로 취급하도록 의미 변경 | 0 | 발견 아님(제품 선택). 다만 템플릿 수정 시 조용히 갈라진다 |
| 템플릿 테스트: `tests/unit/product-features.test.ts`, `product-feature-selection-build.test.ts`, `installed-feature-messages.test.ts`, `tests/component/router.test.tsx`, `product-feature-switch.test.tsx`, `runtime-application.test.tsx` | 둘 다(일부) | 템플릿 홈·라우트 id·"모든 기능은 생성 인덱스에서"를 고정한 테스트를 제품 내용으로 다시 겨눔 | 2~6 | 09-03, 09-04 (테스트 설계는 10 영역) |
반복 원인은 셋이다.
1. 틀 밖 요구(홈, 레이아웃, capability, 자격증명, 제품 설정)를 표현할 제품 소유 자리가 없다. 제품은 템플릿이 가장 자주 바꾸는 파일에 코드를 넣는다.
2. 한 파일에 템플릿 설명과 제품 선택이 섞여 있다(`installed-runtime-capabilities.ts`).
3. 템플릿 테스트가 템플릿 콘텐츠(홈 h1, `EXAMPLES_*` 라우트 id)를 기대값으로 쓴다. 제품은 테스트를 고쳐야 게이트를 통과한다.
## 7. FOLLOW-UP 재확인
`docs/reviews/2026-09-25-maturity-review/FOLLOW-UP.md` 중 이 영역에 걸린 항목과, 이전 라운드 09-01~09-12의 회귀 여부다.
| 항목 | 현재 코드 | 결과 |
|---|---|---|
| FOLLOW-UP 4절 P3 09-07: 기능 제거 검증이 lint·`check:i18n`·e2e를 건너뜀 | 제거 검증 항목은 typecheck·architecture·registries·test:all·coverage·test-evidence-source·check:ci·home-smoke·build뿐이다(`scripts/test-sample-removal.ts:415-428`) | 유효 |
| FOLLOW-UP 4절 P3 09-08: local-draft ABA를 주석으로 닫음 | 주석만 있고 코드 강제는 없다(`src/features/local-draft-feature/domain/local-draft.ts:2-11`) | 유효(리뷰가 허용한 대안 그대로) |
| FOLLOW-UP 2절 P2 `readSubject` 필수화 이행 안내를 README 업데이트 절에 한 줄 | `starter-experience.md:69-74`에 Migration 문단, `CHANGELOG.md:43`에 [계약] 행이 있다. README "Updating a copied project"(`README.md:315-356`)에는 없다. tech-log는 CHANGELOG로 이 변경을 찾아 제품 owner에 `readSubject`를 추가했다(기록 "Fixes the transplant required") | 유효(README 한 줄 없음). 문서 쪽 판정은 14 영역 |
| FOLLOW-UP 1절 P1 초기 JS 예산 | 설치 기능의 계약·메시지·설명자가 eager로 초기 그래프에 들어가는 구조는 그대로다(`installed-*`가 생성 인덱스를 정적 import) | 판단 불가 — 수치는 13 영역에서 측정 |
| FOLLOW-UP 3절 P1 `tests/component/runtime-application.test.tsx` 부하 flaky | memento 기록도 같은 파일이 부하 중 한 번 실패했고 대기 시간을 5초로 늘렸다고 적는다. 템플릿 파일은 바뀌지 않았다 | 판단 불가 — 10 영역 |
| 이전 09-01 기능 2개 설치 시 타입 실패 | `tests/unit/two-feature-install-typecheck.test.ts` 통과(R1) | 해소 |
| 이전 09-02 `VITE_PRODUCT_FEATURES` 소비자별 불일치 | 생성기가 선택을 적용(`generate-product-feature-index.ts:181-239`), `product-feature-selection-build.test.ts` 통과(R1) | 해소 |
| 이전 09-03·09-04 부트 실패 경로 | `main.tsx:14-17` 동적 import, `render-boot-failure.tsx:25-28` `BOOT_UNEXPECTED_FAILURE` | 해소 |
| 이전 09-05 `needs` 미검사 | `feature-adapter-contribution.ts:177-190`, `feature-adapter-composition.test.ts` 통과(R1). 단, `indexedDb` 추가 방법은 여전히 `runtime-adapters.ts` 수정이다(09-02로 이어 적음) | 해소 |
| 이전 09-06 local-draft 도메인 규칙 미적용 | `local-draft-api.ts:69-73` | 해소 |
| 이전 09-07 중앙 정책 파일·제거 일반화 | 생성기 표시 규칙(`:262-297`), 레지스트리 거버넌스 glob(`config/contracts/registry-governance.json:195-198`, `:235-238`), `--feature=`(`test-sample-removal.ts:29-38`). 템플릿 fixture 기준 완료 기준은 충족한다. 실제 제품 2개는 조립 파일을 여전히 고쳤다(09-02~09-04로 이어 적음) | 해소(템플릿 fixture 기준) |
| 이전 09-09 override 오타 무진단 | `runtime-adapters.ts:462-471` | 해소 |
| 이전 09-10 부트 실패 재시도 | `boot-error-shell.tsx:24-38` | 해소 |
| 이전 09-11 `tests/features` 최상위 테스트 미실행 | `test:coverage`가 `tests/features` 전체를 포함(`package.json:81`) | 해소 |
| 이전 09-12 local-draft fixture 복사본 | `tests/contract/consumer-experience/fixtures/` 없음 | 해소 |
## 8. 미검증 목록
| 항목 | 이유 | 확인하려면 |
|---|---|---|
| 09-01의 실제 브라우저 화면과 외부 owner 로그인 경로 | vitest로 조립 루트만 실행했다 | `ANONYMOUS` operation을 가진 픽스처 기능으로 빌드해 Playwright로 로그아웃·로그인 상태 확인 |
| 09-02·09-03 제안이 실제 동기화 충돌을 줄이는지 | 설계 제안이다 | 확장 지점을 만든 뒤 두 제품 브랜치에 한 번 이식하고, 템플릿 파일 diff가 0이 되는지 확인 |
| 다음 동기화의 충돌 수 | 미래 사건이다 | 다음 동기화 기록의 충돌 경로 수를 이번(25, 67)과 비교 |
| E3 변이가 `check:registries`·`test:sample-removal`에서 잡히는지 | 무거운 검사라 돌리지 않았다 | 같은 변이로 두 명령 실행 |
| 기능 수에 따른 초기 JS·부트 시간 | 13 영역 측정 범위 | `config/scale/feature-shape-growth.json` 갱신 측정 |
| memento 셸 브리지의 브라우저 동작 | 제품 기록(시각 비교 26개 통과)만 있다 | memento 브랜치에서 legacy parity 스위트 실행 |
@@ -0,0 +1,345 @@
# 10 테스트 — 빠른 계층 성숙도 리뷰 (2026-09-29)
> 기준: `main` / `af3d8e6` (태그 `v0.2.0` + docs 커밋 1개) · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` · 체크리스트: `docs/reviews/TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md`
> 영역 판정(35.8): **조건부 사용 가능**. 개발 장비와 4코어 러너 조건에서는 빠른 계층이 믿을 만하다. 2코어 러너에서는 머지 게이트가 코드와 무관하게 떨어진다(10-01). CI를 켜기(U-1) 전에 10-01을 고친다.
## 요약
- **검출력은 좋아졌다.** 변이 12종 중 11종을 테스트가 잡았다. 지난 라운드에서 살아남던 7종(01-04, 02-02, 02-08, 04-06, 06-04, 07-04, 07-05)과 10-03(M1b)이 모두 이제 잡힌다. 새로 넣은 고위험 변이 4종 중 3종도 잡혔다. 살아남은 1종은 상위 계층이 같은 검사를 다시 하는 방어선이다(10-04).
- **부하 의존 테스트를 재현했다(10-01, Medium, P1).** 2코어로 묶고 worker 4개로 돌리면 FOLLOW-UP 3절의 세 테스트가 모두 실패했다(5회 중 3회, 회당 1건). `router.test.tsx`(3회 중 1회)와 `extreme-scale-registry.test.ts`(FE-GATE-005 재현 1회 중 1회)도 새로 실패했다. 원인은 셋이다. 지연 로딩 화면을 1초 기본값으로 기다린다. 자식 프로세스 기동 시간을 실제 시계 마감(350ms~3s)에 포함한다. 머지 게이트 안에 절대 시간 예산(1,500ms)이 있다.
- **`http-execution-v3-live-authority`의 실패는 환경 탓이 아니다(10-03, Low, P2).** 실행기가 마감 시각을 두 번 읽는다. 그 사이에 마감이 지나면 시간 초과가 `CONTRACT_VIOLATION`(`FINAL_REQUEST_INVARIANT_FAILED`)으로 보고되고, 화면에는 재시도 없는 `VALIDATION_REJECTED`로 간다. 주입한 시계로 결정적으로 재현했다. 테스트의 마감을 늘려 "고치면" 결함을 숨긴다.
- **플랫폼 테스트가 제품이 바꿀 콘텐츠를 대상으로 쓴다(10-02, Medium, P2).** 경계·라우터 테스트는 스타터 화면(`/`, `/examples/states`, `/examples/ui`)에 묶여 있다. 두 제품이 이번 동기화에서 이 테스트들을 옮기거나 고쳤다(tech-log 7파일, memento 9개 이상). 참조 샘플을 지우면 HTTP 실패 시나리오 카탈로그, 그 증거 게이트, 타입 음성 fixture 8개가 함께 지워진다.
- 게이트 소속(12-04 수정)은 지켜지고 있다. 테스트 파일 327개 중 321개가 게이트 명령에 속하고, 6개는 `config/ci/ungated-tests.json`에 있다. 깨끗한 체크아웃에서 빠른 계층이 통과한다(10-01 지난 수정 유지).
## 0. 머리말 (36.1)
| 항목 | 기록 |
|---|---|
| 영역·경로 | `tests/unit`(173파일 약 68k줄), `tests/component`(35파일 6.6k줄), `tests/integration`(13파일 4.6k줄), `tests/contract`(3), `tests/runtime-schema`(3), `tests/features`(20), `tests/platform`(29), `tests/recipes`(3), `tests/helpers`(8), `tests/mocks`(5), `tests/support`(1), `vitest.config.ts`, `tests/setup.ts`, `scripts/run-vitest.ts` |
| 커밋·상태 | `main` `af3d8e6`. 코드는 이 커밋과 같다. 주 워킹트리에서 쓴 파일은 이 문서 하나다 |
| 전제 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. 빠른 계층은 Vitest 4.1.10, Node 24.14.0. 스타터 화면은 "페이지 단위로 교체 가능"하다고 선언돼 있다(`docs/architecture/starter-experience.md:3-6`). 참조 샘플은 제거 가능하다고 선언돼 있다(`README.md:85`, `:205-209`) |
| 읽은 코드·설정 | `vitest.config.ts`, `tests/setup.ts`, `scripts/run-vitest.ts` 전체. `scripts/lib/ungated-tests.ts` 전체, `config/ci/ungated-tests.json`, `config/ci/gates.json`의 테스트 명령, `package.json` 테스트 스크립트. FOLLOW-UP 3절 테스트 4개 파일 전체와 그 대상 코드(`src/adapters/http/http-execution-v3.ts:440-945`, `http-contract-bridge.ts:344-410`, `feature-http-binding.ts:405-475`, `scripts/lib/provider-guardian-client.ts`, `provider-guardian-protocol.ts:80-95`). `scripts/test-sample-removal.ts:1-300`. 스타터 화면을 쓰는 component 테스트 8개. `tests/helpers/fixture-feature.tsx` |
| 읽은 문서(주장으로만) | `docs/testing/taxonomy.md`, `docs/testing/frontend-platform-testing-strategy.md` 16.5절, `docs/architecture/starter-experience.md`, 지난 리뷰 `10-*.md`·README 11절·FOLLOW-UP |
| 실행한 명령 | 분리 worktree(`git worktree add --detach .../10/wt af3d8e6`, 메인 `node_modules` 심볼릭 링크)에서 `node scripts/run-vitest.ts`와 `node_modules/.bin/tsc`만 썼다. pnpm은 쓰지 않았다. 메인 `node_modules`는 그대로다(`.modules.yaml`·`.pnpm/lock.yaml` 수정 시각 16:26, 작업 시작 전) |
| 실험 | P1 부하 재현(`taskset`으로 CPU 제한, 아래 표). P2 변이 12종(`vitest related <파일> --run`, 07-05는 `tsc -p`). P3 마감 경계 탐침(주입 시계). P4 참조 샘플 테스트 유무에 따른 HTTP 모듈 커버리지 비교. P5 게이트 소속 전수 대조. 실험 파일은 scratchpad `review-2026-09-29/10/`에 있다. worktree는 끝난 뒤 지웠다 |
| 제품 repo 증거 | `../tech-log-frontend`, `../memento-frontend`의 `chore/template-sync-v0.2.0`을 `git show`로만 읽었다 |
| 확인하지 못한 범위 | 실제 Gitea 러너(U-1), 1코어·저메모리 러너, jsdom과 실제 브라우저 차이(11 영역), 모듈별 테스트의 세부 검출력(01~09 영역) |
| 지난 리뷰와 비교 | 지난 결과는 증거로 쓰지 않았다. 10-01~10-07의 수정은 현재 코드와 실행으로 다시 확인했다(6절) |
부하 재현 조건(P1). 호스트는 22코어다. 다른 영역 에이전트가 함께 돌아 부하 평균이 8~23이었다. CPU 제한은 `taskset`으로 걸었다. 다른 에이전트에 부하를 더하지 않으려고 부하 발생기는 쓰지 않았다.
| 실험 | 조건 | 결과 |
|---|---|---|
| 기준 | 대상 5파일(75개), 제한 없음 / 4·2·1코어 | 모두 통과. 파일이 적으면 코어를 줄여도 경쟁이 생기지 않는다 |
| A | `tests/component`, 2코어, `--maxWorkers=4` × 3회 | 1회 실패: `router.test.tsx` 2개("플랫폼 구성", "UI 구성요소" heading 못 찾음) |
| B | `tests/component tests/features tests/integration`, 2코어, `--maxWorkers=4` × 5회 | 3회 실패, 회당 1개: `http-execution-v3-live-authority`(TRANSPORT_FAILURE 대신 CONTRACT_VIOLATION), `provider-guardian-transaction`("deadline guardian READY timed out"), `runtime-application`("Clean Architecture Frontend" heading 못 찾음) |
| C1 | FE-GATE-005 `test:coverage`의 Vitest 단계와 같은 경로·`--coverage --maxWorkers=4`, 4코어 | 277파일 3,164개 통과, 111s |
| C2 | C1과 같음, 2코어 | 1개 실패: `extreme-scale-registry.test.ts` "expected 1531.2 to be less than 1500". 169s |
변이 실험(P2). 원본은 실험마다 복원했다.
| ID | 규칙(출처) | 바꾼 곳 | 결과 | 잡은 테스트 |
|---|---|---|---|---|
| A | 부분 업로드 멱등 키 고정(01-04) | `upload-byte-source.ts:301` 뒤에 `String(Math.random())` 추가 | 잡힘(2) | `resumable-upload-runtime-recovery.test.ts` |
| C | Cache Storage 익명 요청(02-02) | `public-cache-response-validation.ts:232` `omit`→`include` | 잡힘(1) | `public-response-cache.test.ts` |
| D | 교차 출처 handoff 거부(02-08) | `download-input-validation.ts:346` 조건 제거 | 잡힘(1) | `browser-file-download.test.ts` |
| E | SSE idle timeout 재시도 가능(04-06) | `fetch-sse-connection.ts:394` `true`→`false` | 잡힘(2) | `realtime/fetch-sse-connection.test.ts` |
| F | 런타임 kill switch unregister(06-04) | `service-worker-page-controller.ts:117` 분기 끔 | 잡힘(2) | `service-worker-runtime.test.ts` |
| G | 결과 불명 실패는 재시도 불가(07-04) | `errors.ts:167` `MAYBE_APPLIED` 조건 제거 | 잡힘(1 / 817) | `error-classification.test.ts` |
| H | 진단 fixture 위반별 고정(07-05) | `telemetry-port.ts:7` `eventName: string` | 잡힘 | `tsc -p tests/fixtures/typecheck/tsconfig.diagnostics-port.json` → TS2578, exit 1(게이트는 pass 기대) |
| I | V3 실행기가 계약의 재시도 의미를 씀(10-03 M1b) | `http-execution-v3.ts:976` `"SAFE"` 고정 | 잡힘(1 / 631) | `http-execution-v3.test.ts` "does not replay a dispatched KEYED send even with budget left" |
| J | 결과 불명 재전송은 같은 키(03-01, 신규) | `application-query.ts:538` `replayed?.intent ??` 제거 | 잡힘(4) | `application-mutation-admission.test.tsx` 2, `reference-page.test.tsx` 1, `reference-production-vertical.test.tsx` 1 |
| K | 오래된 scope의 성공 응답 폐기(§10.8, 신규) | `http-execution-v3.ts:1377` 검사 끔 | **살아남음(0 / 631, 84파일)** | 없음 — 10-04 |
| L | 자격 증명 소유자 장애는 로그아웃 사유가 아님(LIVE-01, 신규) | `http-execution-v3.ts:770` UNAVAILABLE → `unauthenticated` | 잡힘(1) | `http-execution-v3-live-authority.test.ts` |
| N | 로컬 초기화는 캐시를 비움(로그아웃, 신규) | `tanstack-cache-coordinator.ts:257` `clear()` 제거 | 잡힘(2) | `tanstack-cache-coordinator.test.ts` |
## 1. 대표 흐름 (체크리스트 2절)
### 1.1 정상 흐름 — 개발자가 파일 하나를 돌리고, CI가 계층 전체를 돌린다
```text
node scripts/run-vitest.ts run <file>
→ Node 24.11 이상 확인, NODE_ENV=test, npm 전역 설정 제거 (scripts/run-vitest.ts:5-49)
→ src/.generated 생성 (scripts/run-vitest.ts:51-61)
→ vitest.config.ts: tests/**/*.test.{ts,tsx}만 수집, tests/system은 이름을 줄 때만 (vitest.config.ts:10-37)
→ tests/setup.ts: afterEach에서 cleanup + useRealTimers (tests/setup.ts:5-11)
→ 테스트 실행 (testTimeout 10s, retry 0)
→ 실패: 종료 코드 1, junit 파일(artifacts/tests/*.xml)
→ CI: run-ci-gate가 FE-GATE-004~007 명령을 차례로 실행 (config/ci/gates.json)
```
- 입력: 파일 경로 또는 계층 디렉터리.
- 정책: 수집 범위, 시간 제한, mock 초기화(`restoreMocks`·`clearMocks`·`mockReset`).
- 상태 변화: `src/.generated/`, `artifacts/tests/`.
- 외부 I/O: 없음(MSW 서버는 처리되지 않은 요청을 실패로 만든다, `tests/mocks/server.ts:8`).
- 실패: 테스트 실패는 그대로 드러난다. 재시도로 숨기지 않는다.
- 결과: 새 worktree에서 이 경로가 그대로 동작했다(P1·P2 전부 이 경로).
### 1.2 피해가 큰 흐름 — 작은 CI 러너에서 머지 게이트가 무작위로 떨어진다
```text
PR → FE-GATE-005: test:coverage (V8 계측, --maxWorkers=4)
→ 2 vCPU 러너: worker 4개가 CPU 2개를 나눠 씀
→ (a) lazy route가 1초 안에 안 뜸 → "Unable to find role=heading"
(b) guardian 자식 프로세스가 350ms 안에 안 뜸 → guardian이 만료된 guard를 거부 → "READY timed out"
(c) 1M 조회가 1,500ms를 넘음 → "expected 1531 to be less than 1500"
(d) 5ms 마감이 두 번의 시계 읽기 사이에 지나감 → CONTRACT_VIOLATION
→ 게이트 실패 → 머지 차단
```
- 입력: 코드 변경과 무관하다.
- 정책: 테스트가 실행 속도를 가정한다. 재시도는 없다(좋은 선택이다).
- 결과: (a)~(c)는 거짓 실패다. 실패 문구가 "화면에 제목이 없다", "READY 시간 초과"라서 원인이 속도라는 것을 가린다. (d)는 진짜 결함을 드문 조건에서만 드러낸다(10-03). 팀이 "다시 돌리면 된다"를 배우면 (d) 같은 진짜 신호도 무시된다.
- 파일: `tests/component/runtime-application.test.tsx:64-68`, `tests/component/router.test.tsx:74-79`, `:100-106`, `tests/integration/provider-guardian-transaction.test.ts:704`, `:727-730`, `:619-653`, `tests/platform/cardinality/extreme-scale-registry.test.ts:20`, `:78`, `tests/integration/http-execution-v3-live-authority.test.ts:357-380`.
### 1.3 변경·삭제 흐름 — 제품이 홈 화면을 바꾸고 참조 샘플을 지운다
```text
제품이 "/" 와 /examples/* 를 자기 화면으로 교체
→ 플랫폼 경계 테스트가 템플릿 화면을 기다림
(runtime-application: h1 "Clean Architecture Frontend", chunk-recovery·render-boundary: /examples/states,
router: 홈의 "플랫폼 구성 보기" 링크, route-status-surfaces: 홈 h1)
→ 테스트 실패 → 제품이 테스트를 자기 화면으로 옮김 (tech-log 7파일, memento 9개 이상)
→ 다음 템플릿 동기화 때 같은 파일이 다시 충돌
제품이 참조 샘플 제거 (scripts/test-sample-removal.ts의 절차)
→ SAMPLE_EXTRAS가 플랫폼 검사도 함께 지움:
tests/integration/http-scenario-catalog.test.ts + tests/mocks (HTTP 실패 시나리오 19개 × 3)
test:http-scenario-evidence (FE-GATE-007의 명령)
tests/component/product-feature-switch.test.tsx
타입 음성 fixture 8개와 check:types:fixture:* 8개 (FE-GATE-003)
→ test:sample-removal은 통과 → 제품은 플랫폼 검사가 줄었다는 것을 모름
```
- 파일: `scripts/test-sample-removal.ts:47-96`, `:154-172`(보존 확인 목록), `tests/fixtures/typecheck/invalid-http-wire-mapper.ts:1-2`.
- 제품 기록: `memento-frontend` `docs/operations/template-sync-2026-09-29.md:262`, `:297-301`, `tech-log-frontend` 같은 파일 `:72-78`, `:292-312`.
## 2. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 굵은 번호가 깊게 본 관점이다.
| 번호 | 관점 | 판정 | 적용·통제(목표/확인)·증거 | 근거와 잔여 위험 |
|---|---|---|---|---|
| 1 | 코드 성숙도 | > | 01~09 | 이 영역에서 찾은 실행기 결함은 10-03에 적고 03 영역과 공유한다 |
| 2 | 구조적 성숙도 | > | 12 | — |
| 3 | 변경 용이성 | P | 적용 · M2/M2 · E2 | 테스트 추가는 쉽다(`create-test-application.ts`, `fixture-feature.tsx`). 스타터 화면을 바꾸면 플랫폼 테스트를 옮겨야 한다(10-02) |
| 4 | 인지 부하 | P | 적용 · M2/M2 · E1 | `docs/testing/taxonomy.md`가 계층·파일 하나 실행법을 정확히 적는다. `test:all`과 CI가 돌리는 집합이 다르다(10-05) |
| 5 | 위험 가시성 | P | 적용 · M1/M1 · E1 | guardian 테스트는 watchdog이 프로토콜 마감이 아니라고 적는다(`provider-guardian-transaction.test.ts:21-34`). 같은 파일의 lease 마감(350ms~3s)이 기동 시간을 포함한다는 사실은 적지 않는다(10-01) |
| 6 | 실패 성숙도 | P | 적용 · M3/M3 · E2 | 실패 경로 변이 11/12 검출. 마감 경계에서 시간 초과가 계약 위반으로 분류된다(10-03) |
| 7 | 운영 성숙도 | - | 테스트 계층 밖 | — |
| 8 | 디버깅 가능성 | P | 적용 · M2/M2 · E3 | 부하 실패 문구가 원인(느림)을 가린다: "Unable to find role", "READY timed out"(10-01). 두 번째 같은 종류 guardian은 거부 대신 5초 뒤 "READY timed out"으로 끝난다(`provider-guardian-client.ts:22`, 탐침 5,035ms) |
| 9 | 유지보수 성숙도 | P | 적용 · M1/M1 · E1 | 문서와 구성이 대체로 맞다. `test:platform`만 `--no-file-parallelism`인 이유가 없다(`package.json:141`). CI(`test:coverage`)는 같은 파일을 병렬로 돌리고 두 번 모두 통과했다 |
| **10** | **테스트 성숙도** | **P** | 적용 · 목표 M3 / 확인 M3 · E2(변이)·E3(부하) | 변이 12종 중 11종 검출, 지난 생존 7종 + M1b 전부 검출(0절 표). 깨끗한 체크아웃 통과(worktree에 `artifacts/release` 없음, C1 통과). 재시도 0(`vitest.config.ts`에 `retry` 없음). 남은 것: 부하 의존(10-01), 제품 콘텐츠에 묶인 플랫폼 테스트(10-02), §10.8 미고정(10-04). 한 규칙을 테스트 1개가 잡는 경우가 많다(G, I, L). 그 테스트가 사라지면 보호도 사라진다 |
| 11 | 데이터 성숙도 | > | 05 | IndexedDB 대역은 05 영역 |
| **12** | **동시성 성숙도** | **P** | 적용(테스트 격리·실행 경쟁) · M3/M2 · E3 | 테스트 사이 상태 격리는 좋다: `restoreMocks`·`mockReset`(`vitest.config.ts:20-22`), 전역 `useRealTimers`(`tests/setup.ts:5-11`). 병렬 실행 C1·C2에서 순서 의존 실패는 없었다. CPU 경쟁에서는 실제 시계에 기대는 테스트 4개가 실패한다(10-01). `vi.stubGlobal`을 되돌리지 않는 파일이 1개 있다(`tests/component/boot-unexpected-failure.test.tsx:25`, 설정에 `unstubGlobals` 없음, 영향은 같은 파일 안) |
| 13 | 확장성 | > | 11 | — |
| 14 | 성능 성숙도 | P | 적용(테스트 실행 시간) · M2/M2 · E3 | FE-GATE-005 Vitest 단계: 4코어 111s, 2코어 169s. 머지 게이트 안의 절대 시간 예산이 2코어에서 넘는다(10-01) |
| 15 | 보안 성숙도 | > | 02·03 | 변이 C·D·L은 잡혔다 |
| 16 | 의존성 성숙도 | > | 13 | — |
| 17 | API / Contract | P | 적용(계약 테스트) · M3/M3 · E2 | contract·runtime-schema 게이트 통과(오케스트레이터). V2/V3 일치 테스트는 V2 행이 0개여도 통과한다(`tests/unit/http-operation-v2-v3-parity.test.ts:31`, FOLLOW-UP 07-03 유효). 실행기 §10.8 미고정(10-04) |
| 18 | 배포 성숙도 | > | 11·13 | — |
| 19 | 설정 성숙도 | P | 적용(러너 설정) · M3/M2 · E2 | `include`·`exclude`·Node 확인·생성기 연결은 맞다(10-05 지난 수정 유지). 비동기 대기 기본값(1초)을 전역에서 정하지 않아 파일마다 다르다(10-01) |
| **20** | **개발자 경험** | **P** | 적용 · M2/M2 · E2 | 새 worktree에서 파일 하나 실행과 계층 실행이 문서대로 된다(`docs/testing/taxonomy.md` "To run one test file"). `test:all`("normal product-development loop")은 CI가 돌리는 6파일을 빠뜨린다(10-05). 제품 동기화 때 플랫폼 테스트 이식 비용(10-02). CI를 켜면 거짓 실패 조사 비용(10-01) |
| **21** | **Guardrail 성숙도** | **P** | 적용 · M3/M3 · E2 | 게이트 소속 검사: 비-fixture 테스트 327개 = Vitest 수집 293 + system 3 + Playwright spec 31. 게이트 경로 밖은 6개이고 전부 `ungated-tests.json`에 있다(`scripts/lib/ungated-tests.ts` 재계산). 빠른 계층에 skip·only·todo 없음. 변이 H로 07-05 수정 확인. 남은 것: 샘플 제거가 플랫폼 검사 10개를 함께 지운다(10-02). `tests/scale/tsc-diagnostics-parser.test.ts`는 CPU와 무관한 순수 파서 테스트인데, 제외 이유는 6개 공통 문구("CPU 모델에서만 시간을 비교")다 |
| 22 | 추상화 성숙도 | P | 적용(테스트 도우미) · M2/M2 · E1 | `fixture-feature.tsx`가 샘플 대신 쓸 테스트 전용 기능을 준다. 이 방식이 기능 라우트에만 적용되고, 플랫폼 화면·HTTP 시나리오·타입 fixture에는 적용되지 않았다(10-02) |
| 23 | 일관성 | P | 적용 · M2/M1 · E1 | 지연 로딩 대기 시간 지정이 세 방식이다: 호출마다 `{ timeout: 5000 }`(router 3곳), 파일 단위 `configure`(`reference-page.test.tsx:137-139`), 지정 없음(runtime-application, render-boundary 등 6파일) |
| 24 | 네이밍 / 의미 | O | 적용 · M1/M1 · E1 | 실패한 테스트 이름이 깨진 규칙을 말한다(변이 표의 테스트 이름). taxonomy가 `tests/unit`의 짧은 자식 프로세스 테스트를 허용 범위로 적는다 |
| 25 | 조직 확장성 | - | 작성자 1인 | — |
| 26 | Ownership | P | 부분 적용 · M2/M1 · E1 | 커버리지 모듈에는 owner가 있다(`config/testing/risk-coverage.json`). `ungated-tests.json` 항목에는 담당·재검토 시점이 없다 |
| **27** | **삭제 가능성** | **P** | 적용 · M3/M2 · E2 | `test:sample-removal`은 통과하고 플랫폼 테스트 4개의 보존을 확인한다(`scripts/test-sample-removal.ts:159-164`). 그러나 샘플 제거가 플랫폼 검사 일부를 지우고, 스타터 화면 교체는 플랫폼 테스트를 깨뜨린다(10-02) |
| 28 | 회복 가능성 | - | 테스트 계층 밖 | — |
집계(적용 22개 기준, `>`·`-` 제외): 충족 1(24) · 부분 충족 14 · 미충족 0 · 미검증 0.
## 3. 설계 선택 설명 (41절)
### 3.1 비동기 화면 대기 시간 — Testing Library 기본 1초를 두고 필요한 곳만 늘린다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | component·feature 테스트가 지연 로딩 route와 Suspense 표시를 기다려야 한다. React는 Suspense 표시를 최대 300ms 묶는다(`reference-page.test.tsx:131-136` 주석). CI 러너 속도는 정해져 있지 않다(목표 없음, U-1) |
| 2. 지킬 성질 | 진짜 멈춤은 빨리 실패해야 한다. 느림은 실패가 아니어야 한다. 실패 문구가 원인을 가리키면 좋다 |
| 3. 현재 보장 | [확인한 사실] 전역 설정이 없다(`tests/setup.ts:1-11`). 테스트 시간 제한은 10초다(`vitest.config.ts:23`). 10-02 수정은 `reference-page.test.tsx` 한 파일만 5초로 올렸다(`:137-139`). router는 호출 3곳만 5초다. runtime-application은 1초 그대로다. [보장하지 않음] 지연 로딩을 기다리는 나머지 호출. 실험 A·B에서 실패했다 |
| 4. 대안 | ⓐ 현 상태(호출·파일 단위) ⓑ `tests/setup.ts`에서 `configure({ asyncUtilTimeout })` 전역 지정 ⓒ route 청크를 `beforeAll`에서 미리 import ⓓ route 준비 신호(예: 첫 heading의 focus)를 기다리는 도우미 |
| 5. 비용 비교 | ⓐ 파일마다 따로 알아야 하고, 새 테스트는 1초로 시작한다(다운스트림 복제). ⓑ 한 줄이다. 모든 `findBy`가 길어져 "없어야 할 요소" 확인이 느려지지만, 부재 확인은 `queryBy`로 한다. 진짜 멈춤은 10초 테스트 제한이 잡는다. ⓒ 부하와 무관해지지만 lazy 경계 자체를 덜 검사한다. ⓓ 가장 정확하지만 새 도우미가 생긴다 |
| 6. 현재 조건에서의 선택 | [추론] ⓑ가 가장 작은 비용으로 원인을 한 곳에서 없앤다. 전략 문서는 "timeout만 계속 늘리지 않는다"고 쓴다(`frontend-platform-testing-strategy.md` 16.5). 이 경우는 CI 속도에 맞춘 증가가 아니라, 1초 기본값이 이 앱의 지연 로딩 비용(최소 300ms 묶음 + 청크 변환)과 맞지 않는 문제다. 테스트 제한(10초)이 멈춤 검출을 맡으므로 보호는 유지된다 |
| 7. 재검토 조건 | 지연 로딩을 쓰지 않게 되거나, route 준비 신호가 공개 계약이 되면 ⓓ로 바꾼다. 느린 러너에서 5초도 넘으면 그 테스트의 작업량을 본다 |
### 3.2 플랫폼 테스트의 대상 — 스타터 화면·참조 샘플을 그대로 쓴다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 경계(chunk 복구, render 경계), 라우터 수명주기, HTTP 실패 시나리오, 기능 등록 타입 규칙을 실제 화면·계약으로 검증해야 한다 |
| 2. 지킬 성질 | 제품이 스타터 화면을 바꾸거나 샘플을 지워도 플랫폼 검사는 그대로 남아야 한다. 템플릿 동기화가 이 테스트에서 충돌하지 않아야 한다 |
| 3. 현재 보장 | [확인한 사실] 기능 라우트는 이미 테스트 전용 기능을 쓴다(`tests/helpers/fixture-feature.tsx:7-20`, `router.test.tsx:15-24`). 플랫폼 화면 테스트는 스타터 화면을 쓴다(`chunk-recovery-boundary.test.tsx:20`, `:148`, `render-boundary.test.tsx:20`, `:58`, `runtime-application.test.tsx:61-68`, `route-status-surfaces.test.tsx:59-67`). HTTP 시나리오·타입 fixture는 샘플 계약을 쓴다(`http-scenario-catalog.test.ts:15`, `invalid-http-wire-mapper.ts:2`). [기록된 의도] 스타터 화면은 "페이지 단위로 교체 가능"하다(`starter-experience.md:3-6`). 샘플 제거 스크립트는 플랫폼 커버리지가 조용히 사라지는 것을 막으려고 4개 파일 보존을 확인한다(`test-sample-removal.ts:154-164`) |
| 4. 대안 | ⓐ 현 상태 ⓑ 플랫폼 화면 테스트도 `fixture-feature.tsx`처럼 테스트 전용 라우트·페이지를 mock으로 설치 ⓒ HTTP 시나리오와 타입 fixture를 `tests/helpers/external-contract-fixture.ts`의 테스트 계약으로 옮김 ⓓ 제품용 "이식 가이드"만 추가 |
| 5. 비용 비교 | ⓐ 템플릿 안에서는 실제 화면을 검사한다는 장점이 있다. 제품마다 이식 비용이 반복되고, 샘플 제거 때 검사가 줄어든다. ⓑ·ⓒ 테스트 전용 fixture 유지비가 생긴다. 스타터 화면 자체의 회귀는 e2e·visual이 맡아야 한다. ⓓ 비용은 작지만 제거 때 검사가 줄어드는 문제는 그대로다 |
| 6. 현재 조건에서의 선택 | [추론] 템플릿의 사용자는 거의 항상 `/`를 바꾼다(두 제품 모두 바꿨다). 이미 있는 ⓑ의 방식을 넓히는 쪽이 계약("페이지 교체 가능", "샘플 제거 가능")과 맞는다 |
| 7. 재검토 조건 | 스타터 화면을 템플릿의 고정 제품 화면으로 선언하면 ⓐ가 맞다. 그때는 README에서 "교체 가능"을 지운다 |
### 3.3 게이트 소속 검사 — 패키지 스크립트의 경로 접두사로 계산한다 (현 상태 유지)
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 테스트 파일이 어떤 CI 게이트에서도 돌지 않는 상태를 막는다(지난 12-04) |
| 2. 지킬 성질 | 새 테스트 파일은 게이트에 속하거나 이유와 함께 제외 목록에 있어야 한다. 게이트가 돌리게 된 파일이 제외 목록에 남으면 안 된다 |
| 3. 현재 보장 | [확인한 사실] `scripts/lib/ungated-tests.ts`가 게이트 명령에서 닿는 스크립트의 Vitest 경로, scale tier, Playwright `testDir`를 모은다. 파일이 그 경로 아래면 소속으로 본다. 현재 327개 전부 맞다(P5). [보장하지 않음] 파일이 경로 아래 있어도 러너가 수집하지 않으면(예: `tests/unit/x.spec.ts`, Playwright `testIgnore`) 소속으로 센다. 지금은 그런 파일이 없다 |
| 4. 대안 | ⓐ 현 상태 ⓑ 게이트마다 `vitest list --filesOnly`·`playwright test --list`로 실제 수집 목록을 대조 |
| 5. 비용 비교 | ⓐ 정적이고 빠르다. 위 틈이 있다. ⓑ 정확하지만 check:ci가 러너를 띄워야 해서 느려지고 브라우저 설치가 필요하다 |
| 6. 선택 | [추론] 지금은 ⓐ가 맞다. 틈은 이름 규칙 위반이 있어야 생기고, `vitest.config.ts`의 `include`가 `.spec`을 이미 거른다. 복잡도를 늘릴 근거가 없다 |
| 7. 재검토 조건 | `testIgnore`·`testMatch`가 늘거나, 테스트 파일 이름 규칙이 바뀌면 ⓑ를 다시 본다 |
## 4. 발견 사항 (36.3)
### 10-01 빠른 계층 머지 게이트에 실행 속도에 기대는 테스트가 남아 있다 — 2코어 러너에서 거짓 실패
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(조건부 재현) |
| 관련 관점 | 10, 12, 14, 20, 21, 8 |
| 근거 | 실험 A·B·C2(0절). 원인은 테스트마다 다르다. ① **지연 로딩을 1초 기본값으로 기다린다.** `runtime-application.test.tsx:64-68`(홈 h1), `router.test.tsx:74-79`(클릭 뒤 두 번째 lazy 화면을 기본 `waitFor`로), `:100-106`. 전역 설정이 없다(`tests/setup.ts:1-11`). 부하에서 이 테스트들이 0.9~3.5s 걸렸다. ② **자식 프로세스 기동 시간을 실제 시계 마감에 넣는다.** `provider-guardian-transaction.test.ts:704`는 spawn 직후 `Date.now() + 350`을 마감으로 보낸다. guardian은 받은 시점에 마감이 지났으면 guard를 거부한다(`scripts/lib/provider-guardian-protocol.ts:88`). 그러면 READY가 오지 않아 5초 watchdog이 "READY timed out"으로 끝난다. 같은 구조가 `:222`, `:327`, `:355`, `:671`, `:881`(2~3초)에 있다. `:727-730`은 lease 2초 중 1초를 잠든다. `:619-653`은 두 번째 guardian의 5초 응답 제한(`provider-guardian-client.ts:22`)을 그대로 기다려서, 10초 테스트 제한 중 5초를 쓴다(부하에서 5.35~5.81s). `PROCESS_HEAVY_TIMEOUT_MS`(30s)는 한 테스트에만 붙어 있다(`:717`). ③ **머지 게이트 안의 절대 시간 예산.** `extreme-scale-registry.test.ts:20` `MAX_LOOKUP_MS = 1_500`이 V8 계측 아래 `test:coverage`(FE-GATE-005)에서 돈다. 2코어에서 1,531ms로 실패했다. 이 파일은 scale tier(`run-scale-profile.ts:87`)에도 있다. ④ `http-execution-v3-live-authority`는 테스트 문제가 아니다(10-03) |
| 발생 조건 | CPU가 worker 수보다 적을 때. `test:coverage`는 `--maxWorkers=4`로 고정이라 2 vCPU 러너에서 항상 이 조건이다. 개발 장비에서 여러 작업을 함께 돌릴 때도 같다 |
| 영향 | CI를 켜면(U-1) 코드와 무관하게 머지가 막힌다. 실험 B 기준 실행 5번 중 3번 실패했다. 실패 문구가 원인을 가려 UI·프로세스 결함처럼 보인다. 재시도가 없으므로 팀은 수동 재실행을 배우고, 10-03 같은 진짜 신호도 함께 무시하게 된다. 두 제품도 같은 실패를 겪었다(memento `template-sync-2026-09-29.md:297-301`) |
| 심각도·우선순위 | Medium · P1 — 제품 피해는 없다. 게이트 신뢰를 깎고 조사 비용을 반복시킨다. FOLLOW-UP이 CI를 켜기 전 처리로 정했다 |
| 통제·증거 | 통제: 전략 문서의 flaky 정책(M1, `frontend-platform-testing-strategy.md` 16.5), 재시도 0(M2). 속도 의존을 막는 장치는 없다(M0) · 증거: E3(CPU 제한 실험, 조건 기록) |
| 확실성과 남은 가정 | 네 원인은 코드와 실패 문구로 확인했다. 실제 Gitea 러너의 코어 수와 실패율은 모른다(U-1) |
| 결정의 근거 | 3.1절. [확인한 사실] 10-02 지난 수정은 파일 하나에만 적용됐다. [추론] 원인이 테스트 도구 기본값이라 전역 한 곳에서 고치는 편이 맞다 |
| 이해 비용 | 새 component 테스트 작성자는 lazy 화면을 기다릴 때 5초를 직접 줘야 한다는 것을 알 방법이 없다. guardian 테스트 수정자는 lease 마감이 기동 시간을 포함한다는 것을 코드에서 추론해야 한다 |
| 최소 개선 방향 | ① `tests/setup.ts`에 `configure({ asyncUtilTimeout: 5_000 })`. 그 뒤 파일·호출 단위 override를 지운다. ② guardian 테스트는 guard를 보내기 전에 자식이 입력을 읽을 준비가 됐다는 신호를 기다린다(이미 있는 `guardian-spawned` 표식 방식, `:814-818`). 5초 대기를 쓰는 `:619` 테스트에 `PROCESS_HEAVY_TIMEOUT_MS`를 붙인다. ③ 절대 시간 예산은 scale tier에만 두고 `test:coverage` 대상에서 뺀다. 머지 게이트에는 증가율(`MAX_COMPOSE_GROWTH_RATIO`처럼 CPU와 무관한 비율)만 남긴다 |
| 대안 비교 | 3.1절. ③은 예산을 올리는 방법도 있다. 그러면 1코어 러너에서 같은 문제가 다시 생긴다 |
| 단순화의 보존 조건 | 진짜 멈춤은 여전히 10초(또는 30초) 테스트 제한에서 실패한다. guardian의 "만료된 guard 거부" 규칙은 별도 테스트로 계속 고정한다(마감을 과거로 보내는 경우) |
| 비용·부작용 | 수십 줄. `findBy`의 부재 대기가 길어지는 테스트가 있으면 `queryBy`로 바꿔야 한다 |
| 재검토 조건 | CI 러너 사양이 정해지면 실험 B·C2를 그 사양으로 다시 돈다 |
| 완료 기준 | 2코어·`--maxWorkers=4`로 `tests/component tests/features tests/integration`을 20회, `test:coverage`의 Vitest 단계를 5회 돌려 실패 0 |
| 검증 방법 | `taskset -c 0-1 node scripts/run-vitest.ts run tests/component tests/features tests/integration --maxWorkers=4`를 반복하고 실패를 센다 |
| 담당·기한·상태 | 미정 · U-1 전 · 신규(FOLLOW-UP 3절 P1 2건 + 새 2건) |
### 10-02 플랫폼 테스트가 제품이 바꾸거나 지울 콘텐츠(스타터 화면, 참조 샘플)를 대상으로 쓴다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(스타터 화면 교체 — 두 제품에서 발생) + 구조적 위험(샘플 제거 — 아직 발생 전) |
| 관련 관점 | 27, 20, 10, 21, 3, 22, 30.5, 30.7 |
| 근거 | **스타터 화면.** 플랫폼 경계 테스트가 템플릿 화면에 묶여 있다: `chunk-recovery-boundary.test.tsx:20`(`state-gallery-page.tsx` mock), `:148`, `:177`(`/examples/states`), `render-boundary.test.tsx:20`, `:58`, `runtime-application.test.tsx:61-68`(`/`의 h1 "Clean Architecture Frontend"), `router.test.tsx:60-80`(홈의 "플랫폼 구성 보기" 링크), `:96-117`, `:213-233`, `route-status-surfaces.test.tsx:59-67`, `:170-187`, `app-shell.test.tsx:70`. 문서는 스타터 화면을 "페이지 단위로 교체 가능"이라고 선언한다(`starter-experience.md:3-6`). 제품 기록: tech-log는 템플릿 화면을 지운 뒤 플랫폼 테스트 7파일을 자기 라우트로 옮겼고 3파일은 가져오지 않았다(`tech-log-frontend` `template-sync-2026-09-29.md:72-78`, `:292-312`). memento는 `/`와 앱 이름을 가정한 테스트 9파일 이상을 고쳤다(`memento-frontend` 같은 파일 `:262`). **참조 샘플.** 제거 절차의 `SAMPLE_EXTRAS`가 플랫폼 검사를 함께 지운다(`scripts/test-sample-removal.ts:47-96`): HTTP 실패 시나리오 카탈로그와 `tests/mocks`, `test:http-scenario-evidence`(FE-GATE-007 명령), 기능 스위치 테스트, 플랫폼 API(`defineFeatureHttpOperation`, `createFeatureHttpBinding`, `defineFeatureAdapterContribution`)의 타입 음성 fixture 8개와 FE-GATE-003 명령 8개. 이 fixture들은 샘플 계약을 import한다(예: `invalid-http-wire-mapper.ts:1-2`). 실험 P4: 실행기 관련 테스트 84파일에서 샘플에 묶인 15파일을 빼면 `feature-http-binding.ts` 분기 78.7→62.3%, `http-contract-bridge.ts` 71.1→59.5%, `bounded-body-reader.ts` 71.7→60.4%로 준다. 단, 이 비교는 모듈을 직접 import하는 테스트를 넣지 않았다. 전체 스위트에서는 커버리지 하한(`risk-coverage.json`)이 샘플 제거 뒤에도 통과한다(오케스트레이터 `test:sample-removal` PASS) |
| 발생 조건 | 제품이 `/`나 `/examples/*`를 바꿀 때(두 제품 모두 해당). 제품이 문서대로 참조 샘플을 지울 때 |
| 영향 | 스타터 화면: 동기화마다 플랫폼 테스트 수정·이식 비용이 생기고, 다음 동기화 때 같은 파일이 다시 충돌한다. 이식하지 않고 지우면(tech-log가 3파일을 가져오지 않음) 그 경계 검사가 제품에서 사라진다. 샘플: 제거 게이트는 통과하므로 제품은 HTTP 실패 시나리오 증거와 플랫폼 타입 규칙 검사가 없어졌다는 것을 모른다. 두 제품 모두 아직 샘플 디렉터리를 남겨 두었다(tech-log는 `NOT_INSTALLED`로 두고 삭제 여부를 미결로 남김, `template-sync-2026-09-29.md:122-133`) |
| 심각도·우선순위 | Medium · P2 — 제품 피해는 없다. 복사한 모든 제품에서 반복되는 비용이고, 선언된 제거 경로에서 가드레일이 조용히 준다 |
| 통제·증거 | 통제: 기능 라우트는 테스트 전용 기능으로 분리됨(M2), 샘플 제거 시 플랫폼 테스트 4개 보존 확인과 커버리지 하한(M3). 스타터 화면 분리는 M0 · 증거: E1(코드), E2(커버리지 비교), 제품 동기화 기록 2건 |
| 확실성과 남은 가정 | 스타터 화면 결합은 두 제품의 실제 수정 기록으로 확인했다. 샘플 제거로 사라지는 검사 목록은 스크립트에서 확인했다. 같은 규칙을 다른 테스트가 얼마나 대신 지키는지는 모듈별로 확인하지 않았다 |
| 결정의 근거 | 3.2절 |
| 이해 비용 | 제품 개발자는 어떤 템플릿 테스트가 "플랫폼 규칙"이고 어떤 것이 "스타터 화면 검사"인지 파일 이름으로 알 수 없다. 샘플 제거 시 무엇이 함께 사라지는지는 스크립트 상수를 읽어야 안다 |
| 최소 개선 방향 | ① 플랫폼 화면 테스트를 `fixture-feature.tsx`와 같은 방식의 테스트 전용 라우트·페이지로 옮긴다. 스타터 화면 자체의 검사는 이름에 드러나는 별도 파일(예: `starter-*.test.tsx`)로 모아 제품이 통째로 지울 수 있게 한다. ② HTTP 시나리오 카탈로그와 타입 음성 fixture를 `tests/helpers/external-contract-fixture.ts`의 테스트 계약으로 옮겨 `SAMPLE_EXTRAS`에서 뺀다. ③ 그 전까지는 README 제거 절에 "함께 사라지는 플랫폼 검사" 목록을 적는다 |
| 대안 비교 | 3.2절 |
| 단순화의 보존 조건 | 옮긴 뒤에도 chunk 복구·render 경계·라우터 수명주기·HTTP 시나리오 19×3·타입 음성 규칙 8개가 같은 게이트에서 돈다. 스타터 화면 회귀는 e2e·visual이 계속 본다 |
| 비용·부작용 | 테스트 fixture 몇 개와 파일 이동. 제품은 다음 동기화 때 한 번 더 충돌을 푼다 |
| 재검토 조건 | 스타터 화면을 교체 불가 제품 화면으로 선언하면 ①은 필요 없다 |
| 완료 기준 | 템플릿 복사본에서 `src/presentation/pages/home-page.tsx`와 `src/presentation/examples/*`를 다른 화면으로 바꾸고 `starter-*` 테스트만 지웠을 때 나머지 component 테스트가 통과한다. `test:sample-removal` 뒤에도 HTTP 시나리오 증거와 타입 음성 fixture가 게이트에 남는다 |
| 검증 방법 | 위 두 조작을 worktree에서 한 뒤 `test:component`, FE-GATE-003·007 명령 실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 10-03 실행기가 마감 시각을 두 번 읽어, 그 사이에 마감이 지나면 시간 초과를 "요청 계약 위반"으로 보고한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 6, 12, 5, 8, 10, 24 |
| 근거 | `src/adapters/http/http-execution-v3.ts:884-889`이 남은 시간을 읽고 0 이하면 `TIMEOUT`을 돌려준다. 이어서 타이머·헤더를 만든 뒤 `:918-927`의 `checkFinalInvariants`가 남은 시간을 다시 읽는다. 여기서 0 이하면 `DEADLINE_EXPIRED`(`http-contract-bridge.ts:407`)가 나오고, 실행기는 `SCOPE_FENCED`가 아닌 모든 불변식 실패를 `FINAL_REQUEST_INVARIANT_FAILED` 계약 위반으로 바꾼다(`:929-941`). 화면 계층은 이것을 `VALIDATION_REJECTED`로 옮긴다(`feature-http-binding.ts:467-471`). `VALIDATION_REJECTED`는 재시도 불가·행동 없음이고 `REQUEST_TIMEOUT`은 재시도 가능·"retry"다(`src/contracts/errors.ts:43`, `:77`). 탐침 P3: 시계를 주입해(`monotonicNow`) k번째 읽기 뒤에 마감을 넘기게 하면 k=6·7에서 `CONTRACT_VIOLATION / FINAL_REQUEST_INVARIANT_FAILED`, 나머지 k에서 `TRANSPORT_FAILURE / TIMEOUT`이 나온다. 부하 실험 B에서 `http-execution-v3-live-authority.test.ts:357-380`(마감 5ms)이 같은 결과로 실패했다 |
| 발생 조건 | 요청 직전 두 시계 읽기 사이에 메인 스레드가 멈춰 마감이 지날 때. 재시도·대기로 남은 시간이 적을 때 가능성이 커진다(느린 기기, GC, 백그라운드 탭) |
| 영향 | 요청은 보내지지 않는다(`NOT_STARTED`). 데이터 피해는 없다. 사용자는 일시적 시간 초과에 "재시도" 대신 입력 거부 계열 결과를 받는다. 진단은 계약 위반으로 집계돼 조사 방향을 틀리게 만든다. FOLLOW-UP은 이 테스트를 "재현 조건을 찾는다"로 환경 탓에 두었다. 테스트 마감을 늘려 안정화하면 이 결함의 유일한 신호가 사라진다 |
| 심각도·우선순위 | Low · P2 — 드물고 피해가 작다. 우선순위는 10-01 수정 때 이 테스트를 잘못 고치지 않도록 먼저 정한다 |
| 통제·증거 | 구현 M2(두 검사 모두 있음), 분류 규칙 결정적 테스트 없음(M0) · E2(주입 시계 탐침)·E3(부하 재현) |
| 확실성과 남은 가정 | 경로와 매핑은 확인했다. 실제 사용자 기기에서의 빈도는 모른다 |
| 결정의 근거 | 적용 제외 — 기대 계약(마감 경과는 `TIMEOUT`)이 이미 정해져 있어 선택 비교가 필요 없다 |
| 이해 비용 | `checkFinalInvariants`가 마감도 검사한다는 사실을 호출부의 매핑 코드에서 알 수 없다 |
| 최소 개선 방향 | `:929-941`에서 `DEADLINE_EXPIRED`를 `abandonedTransportFailure("TIMEOUT")`으로 매핑한다(`SCOPE_FENCED`처럼 별도 분기). 주입 시계로 k=6·7 경우를 고정하는 단위 테스트를 추가한다. live-authority 테스트는 그대로 둔다 |
| 대안 비교 | 적용 제외 — 명백한 분류 오류를 바로잡는 수정이다 |
| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다 |
| 비용·부작용 | 몇 줄 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 탐침 P3의 모든 k에서 `TRANSPORT_FAILURE / TIMEOUT`이 나온다. 실험 B 20회에서 live-authority 실패 0 |
| 검증 방법 | 주입 시계 단위 테스트, 실험 B 반복 |
| 담당·기한·상태 | 미정 · 미정 · 신규(03 영역 코드. 03 영역과 공유) |
### 10-04 실행기의 "오래된 scope의 성공 응답은 버린다"(§10.8) 마지막 검사를 어떤 테스트도 고정하지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험(검출 공백) |
| 관련 관점 | 10, 12, 17, 15 |
| 근거 | 변이 K: `http-execution-v3.ts:1376-1382`의 검사를 꺼도 관련 84파일 631개가 모두 통과했다. 기존 scope 테스트는 fetch 안에서 scope를 바꾸면서 lifetime signal도 abort한다(`tests/unit/http-execution-v3.test.ts:532-572`). 그래서 본문 읽기가 abort 경로로 끝나 이 검사까지 오지 않는다. 조회 경로에서는 `application-query.ts:112`가 실행 뒤 scope를 다시 확인하므로, 지금 조립된 화면에서 다른 세션의 데이터가 캐시에 들어가지는 않는다 |
| 발생 조건 | 본문을 다 읽은 직후, 검증·매핑이 도는 동안 scope가 바뀌고 signal abort가 아직 반영되지 않았을 때. 실행기를 `application-query` 밖에서 직접 쓰는 기능·레시피 |
| 영향 | 실행기 리팩터링에서 이 검사가 빠져도 빠른 테스트가 모른다. 상위 계층의 재검사가 막아 주는 동안에는 사용자 피해가 없다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | 구현 M2(두 계층에 검사), 실행기 단위 검출 M0 · E2(변이) |
| 확실성과 남은 가정 | 미검출은 확인했다. `application-query` 밖의 실제 호출자가 있는지는 01~09 영역 몫이다 |
| 결정의 근거 | 적용 제외 — 계약(§10.8)은 코드 주석에 이미 있고, 테스트 누락만의 문제다 |
| 이해 비용 | 작다 |
| 최소 개선 방향 | `isCurrent`가 본문 읽기 완료 뒤에만 false가 되는(signal은 abort하지 않는) 테스트 하나를 추가한다. 기대 결과는 `CONTRACT_VIOLATION / SCOPE_FENCED` |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 테스트 1개 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 변이 K를 넣으면 새 테스트가 실패한다 |
| 검증 방법 | 변이 K 적용 후 `node scripts/run-vitest.ts related src/adapters/http/http-execution-v3.ts --run` |
| 담당·기한·상태 | 미정 · 미정 · 신규(03 영역과 공유) |
### 10-05 `test:all`("일상 개발 루프")이 CI가 돌리는 빠른 테스트 6파일을 빠뜨린다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 20, 4, 21 |
| 근거 | `test:coverage`(FE-GATE-005)는 `tests/features`, `tests/scripts`, `tests/scale/browser-soak.contract.test.ts`를 돌린다(`package.json:81`). `test:all`은 `tests/features/reference-feature`만 돌리고 나머지는 없다(`package.json:83`). 실험 C2 파일 목록과 대조한 결과 빠진 파일: `tests/features/feature-installation-surface.test.ts`, `feature-module.test.ts`, `product-features-scale.test.ts`, `tests/scale/browser-soak.contract.test.ts`, `tests/scripts/generate-product-feature-index.test.ts`, `verify-extreme-scale.test.ts`. taxonomy는 `test:all`을 "the normal product-development loop"라고 쓴다(`docs/testing/taxonomy.md:19-25`). `test:platform`은 `--no-file-parallelism`이고 CI는 같은 파일을 병렬로 돌린다(이유 기록 없음, `package.json:141`) |
| 발생 조건 | 개발자가 기능 모듈 선언·생성기를 바꾸고 `test:all`만 돌릴 때 |
| 영향 | 로컬에서 초록이고 CI에서 빨강이다. 기능 설치 표면·생성기 규칙은 기능 추가 때 자주 바뀌는 곳이다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M1(문서) · E2(실행 목록 대조) |
| 확실성과 남은 가정 | 확인했다 |
| 결정의 근거 | 적용 제외 — 스크립트 경로 누락이다 |
| 이해 비용 | 개발자가 두 스크립트의 경로 목록을 직접 비교해야 안다 |
| 최소 개선 방향 | `test:all`의 `test:reference-feature`를 `tests/features` 전체로 넓히고 `tests/scripts`를 더한다. 또는 taxonomy에 "CI와 같은 집합은 `test:coverage`"라고 적는다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 한 줄. `test:all`이 몇 초 길어진다 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | `test:all`이 돌리는 파일 집합이 `test:coverage`의 Vitest 파일 집합을 포함한다 |
| 검증 방법 | 두 명령의 `vitest list --filesOnly` 결과 비교 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
## 5. 지난 라운드 수정의 현재 상태
| 지난 ID | 현재 | 근거 |
|---|---|---|
| 10-01 깨끗한 체크아웃 실패 | 유지됨 | 새 worktree(`artifacts/release` 없음)에서 C1·C2의 `tests/unit` 전부 통과 |
| 10-02 reference-page 첫 대기 | 부분 — 같은 원인이 다른 파일에 남음 | 10-01 발견 |
| 10-03 V3 재시도 의미 | 유지됨 | 변이 I 검출 |
| 10-04 커버리지 게이트 | 유지됨 | `http-contract-bridge.ts`·`http-retry-lifecycle.ts`가 하한 목록에 있음(`risk-coverage.json`) |
| 10-05 파일 하나 실행 | 유지됨 | taxonomy 명령이 새 worktree에서 동작, `include`가 `.spec`을 거름(수집 293 = 비-spec·비-system 전부) |
| 10-06 fake timer 복원 | 유지됨 | `tests/setup.ts:8-10` |
| 10-07 테스트 문서 | 유지됨 | taxonomy의 `test:all` 구성·파일 하나 실행법·자식 프로세스 분류가 현재와 같다 |
| 12-04 게이트 밖 테스트 | 유지됨 | P5 전수 대조. 제외 이유 중 `tsc-diagnostics-parser.test.ts`만 사실과 다름(2절 21) |
## 6. FOLLOW-UP 재확인
| FOLLOW-UP 항목 | 결과 | 근거 |
|---|---|---|
| 3절 P1 `provider-guardian-transaction` | 유효 | 실험 B에서 재현. 원인은 실제 시계 마감(350ms)에 자식 기동 시간이 들어가는 것과 5초 고정 대기(10-01 ②) |
| 3절 P1 `runtime-application` | 유효 | 실험 B에서 재현. 1초 기본 대기(10-01 ①). 이 테스트는 스타터 홈에도 묶여 있다(10-02) |
| 3절 P2 `http-execution-v3-live-authority` | 유효 — 원인이 바뀜 | 실험 B에서 재현. 테스트 환경 문제가 아니라 실행기의 분류 결함(10-03). "재현 조건"은 마감 5ms + 두 시계 읽기 사이의 지연 |
| 3절 P2 reference-page 나머지 대기 | 판단 불가 | 부하 실행 7회(B 5회, C 2회)에서 실패 없음. 첫 테스트가 부하에서 1.7~2.4s로 5초 설정 안이다 |
| 3절 P3 `tests/system/ci-runner/ci-artifact-contract.test.ts` | 다른 영역(11) | — |
| 4절 P2 07-03 V2/V3 일치 테스트 | 유효 | V2 행이 0개면 반복문이 돌지 않아 통과한다(`http-operation-v2-v3-parity.test.ts:31`). V3에만 있는 operation도 보지 않는다 |
| 4절 01-11·05-03·06-10·08-04·08-07 테스트 빈틈 | 다른 영역(01·05·06·08·11) | — |
| 5절 P3 fixture의 pnpm 설치 검사 끔(F-4, F-12) | 유효 | `scripts/lib/fixture-node-modules.ts:40-42`. fixture가 공유 `node_modules`를 링크로 쓰는 구조 그대로. 이번 리뷰 중 오케스트레이터가 같은 위험(링크된 `node_modules`에서 pnpm 실행)을 경고했다 |
| 5절 P3 00-03 남은 임시 폴더 | 해소(테스트 쪽) | 이 영역의 실행(전체 빠른 계층 2회 포함) 뒤 새 `repository-inventory-*`·`sw-assets-*`가 생기지 않았다. `/tmp`에 있는 324개는 모두 2026-09-29 14:3x~15:3x에 생긴 것이고, 누가 만들었는지(다른 실행·중단된 실행)는 확인하지 못했다 |
## 7. 미검증 목록
| 항목 | 이유 | 확인하려면 |
|---|---|---|
| 실제 CI 러너에서의 실패율 | CI가 이 repo에서 돌지 않음(U-1). 러너 사양이 정해지지 않음 | U-1 뒤 FE-GATE-005~007을 20회 돌리고 실패를 센다 |
| 1코어·저메모리 조건 | 다른 에이전트와 호스트를 공유해 부하 발생기를 쓰지 않음 | 전용 호스트에서 `taskset -c 0` + `--maxWorkers=4` |
| 샘플 제거 뒤 사라지는 규칙을 다른 테스트가 얼마나 대신 지키는지 | 모듈별 변이는 01~09 영역 몫. P4는 관련 테스트 집합만 비교함 | 샘플 제거 fixture에서 HTTP 모듈 변이 실험 |
| 스타터 화면을 바꾼 복사본에서 실패하는 테스트의 전체 목록 | 제품 기록 2건으로 대신함 | 10-02 완료 기준의 조작을 worktree에서 실행 |
| `test:platform`의 `--no-file-parallelism`이 필요한 이유 | 기록 없음. 병렬 실행 2회는 통과 | `tests/platform` 병렬 20회 |
| `test:sample-removal`·`check:v8-coverage-counter-semantics` 직접 실행 | worktree에서 pnpm을 쓰지 않기로 함(오케스트레이터 지시). 오케스트레이터 실행 결과(PASS)를 따름 | 메인 트리에서 오케스트레이터가 실행 |
@@ -0,0 +1,417 @@
# 영역 11 — 테스트: 브라우저·릴리스·규모
> 검토일: 2026-09-29 · 기준: `main` / `af3d8e6` (워킹트리 미커밋 변경은 리뷰 가이드 문서 2개뿐, 코드는 `af3d8e6`과 같다) · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`, 실행 순서: `TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md`
> 경로: `tests/e2e`, `tests/browser-capabilities`, `tests/visual`, `tests/storybook`, `tests/release`, `tests/scale`, `tests/system`, `tests/architecture`, `tests/scripts`, `playwright*.config.ts` 5개, `scripts/scale/`, `scripts/drill-runbook.ts`. 판정에 필요해서 함께 읽은 것: `scripts/test-performance.ts`, `scripts/lib/lab-performance.ts`, `scripts/lib/performance-budgets.ts`, `scripts/lib/promotion-readiness.ts`, `scripts/contracts/release-artifacts.ts`(drill 판정 부분), `scripts/check-test-evidence.ts`(skip·only 검사), `scripts/verify-exact-promotion-bundle.ts`, `scripts/run-and-validate-provider.ts`(bwrap 부분), `config/ci/gates.json`, `.gitea/workflows/quality-gates.yml`, `config/scale/*`, `config/performance/budgets.json`, `docs/operations/{ci-quality-gates,release-cache-rollback,performance-evidence}.md`, `docs/architecture/optional-adapter-recipes.md`(SW 켜기 절), 제품 repo 2개의 동기화 기록.
> 깊게 본 관점: 10, 13, 14, 18, 28.
> 영역 판정(35.8): **조건부 사용 가능.** 브라우저 테스트(엄격 fixture, 재시도 0, 두 빌드 공존·구 탭 복구·깨진 SW 복구)는 템플릿 기본 구성에서 참고 구현으로 써도 된다. 다음은 그대로 쓰지 않는다. `test:system`이 들어 있는 merge 게이트 FE-GATE-013은 main에서 항상 실패한다(11-01). 운영 drill 게이트는 PASS에 도달할 입력이 없다(11-02). SW e2e는 SW를 켠 제품에서 준비 단계부터 실패한다(11-03). lab 성능 게이트는 부하가 있는 러너에서 판정이 뒤집힌다(11-04).
## 0. 결론
- **merge 게이트 FE-GATE-013(security)이 main에서 결정적으로 실패한다.** `tests/system`의 기대 문자열이 13-04 수정 뒤 바뀐 출력과 다르다. 지난 라운드 검증과 이번 오케스트레이터 게이트 목록 모두 `test:system`을 돌리지 않았다(11-01).
- **지난 11-01(거짓 PASS)은 해소됐다.** `dist/assets/*.js`를 지우면 FE-RB-002·005가 FAIL(exit 1)이고, 나머지는 UNVERIFIED(exit 3)다. 대신 5개 drill 모두 어떤 입력으로도 PASS할 수 없다. production 단계와 그 뒤의 field 단계(FE-GATE-018)는 템플릿 그대로는 끝까지 갈 수 없다(11-02).
- **SW e2e 두 spec은 "SW 꺼짐(null 선택) + 해시 파일만 캐시"를 소스 문자열 치환과 단언으로 가정한다.** 문서의 SW 켜기 1단계만 적용해도 두 spec이 준비 단계에서 실패한다(재현). memento-frontend가 같은 이유로 이 spec을 빨간 채로 미뤘다(11-03).
- **규모 증거는 과장 없이 범위를 적는다.** 실제 모양 기능으로 쟀고 "검증/비검증/조건"을 나눴다. 다만 기준선이 현재 코드와 달라졌고(기능당 초기 JS 2.9KB → 3.2KB) 어느 커밋을 쟀는지 기록이 없다(11-05). pr tier는 FE-GATE-005에서 돌고 CPU 경합에서도 10/10 통과했다.
- **lab 성능은 5회 중앙값으로 바뀌었지만 판정은 여전히 뒤집힌다.** 같은 빌드를 5번 돌려 PASS 2 / FAIL 3이었다(loadavg 16~22/22스레드)(11-04).
- **지난 11-02·11-06·11-08은 해소됐다.** a11y 변이는 두 라우트에서 5/5 검출, 스키마 위반 목 응답은 spec 단언이 잡는다. 4개 Playwright 설정 모두 `forbidOnly: true`다.
## 1. 범위와 방법 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 | `clean-architecture-frontend-template` 영역 11 |
| 커밋·상태·시점 | `main` / `af3d8e6`, 2026-09-29. 실험은 분리 worktree(`scratchpad/review-2026-09-29/11/wt`)와, `tests/system`만 `.git`이 디렉터리인 로컬 clone(`…/11/clone`)에서 했다. 둘 다 끝난 뒤 지웠다 |
| 실행 환경 | Node v24.14.0, Playwright 1.62.0, Intel Core Ultra 7 155H(22 스레드). 다른 영역 에이전트가 동시에 돌아 loadavg 2~42 |
| 목적·실행 형태 | 템플릿(참고 구현). 브라우저 SPA + 정적 호스팅 + 선택형 Service Worker. SSR 없음 |
| 규모·운영 목표 | 선언 상한만 있다(`CONTEXT_MAX_FEATURES = 200`, `APP_MAX_CONTEXTS = 20`). 성능 예산은 `config/performance/budgets.json`. RPO/RTO 없음 |
| 확인하지 못한 범위 | Firefox·WebKit(지시에 따라 chromium만), e2e 전체, storybook spec, browser soak, main/nightly/release scale tier(기준선 CPU 필요), CI 러너 결과(U-1) |
| 이전 리뷰와 비교 | 2026-09-25 영역 11 문서의 발견 8건을 현재 코드로 다시 확인했다(6절). 지난 결과는 증거로 쓰지 않았다 |
실행 목록. worktree는 원본 `node_modules`를 심볼릭 링크했다. 스크립트는 `node scripts/…`로 직접 불렀다. Playwright는 포트 충돌을 피하려고 포트만 바꾼 설정 사본(4411~4414, `--strictPort`)을 worktree 안에 두고 chromium만 돌렸다.
| 명령·실험 | 결과 |
|---|---|
| `node scripts/run-vitest.ts run tests/release tests/architecture tests/scripts tests/scale tests/unit/{runbook-drill,lab-performance,feature-shape-growth}.test.ts` | 28파일 165개 통과 |
| `node scripts/generate-product-feature-index.ts && node scripts/build-frontend.ts` | 성공(local 프로필, SW 없음) |
| `node scripts/drill-runbook.ts FE-RB-001..005` (완전한 dist) | 5개 모두 `UNVERIFIED`, exit 3 |
| 같은 명령, `dist/assets/*.js` 전부 삭제 | FE-RB-002·005 `FAIL` exit 1. 001·003·004 `UNVERIFIED` exit 3(자산을 읽지 않는 drill) |
| lazy chunk 1개만 삭제 | FE-RB-002 `FAIL` |
| 엔트리 JS를 0바이트로 | FE-RB-002·005 `UNVERIFIED`, 메시지 "no local check failed"(파일 존재만 본다) |
| 변이: FE-RB-001·002의 관측 불가 항목 2개를 `assertion(…, "PASS")`로 | `tests/unit/runbook-drill.test.ts` 9/9 통과. record에 `product root mount: PASS` 기록(11-08) |
| `node scripts/scale/run-scale-profile.ts pr` | PASSED 4단계. 추적 중인 로그 3개가 바뀌고 새 로그 1개 생김(11-09) |
| `run-composition-scale.ts --profiles=S0,S1,S2` 10회, `taskset -c 2`로 busy loop 3개와 CPU 1개 공유 | 10/10 PASS |
| Playwright chromium: `service-worker-update`, `service-worker-recovery`, `old-tab-chunk-recovery`, `boot-module-failure` | 8/8 통과 |
| 전제 변경: `installed-runtime-capabilities.ts`의 SW 선택을 `ACTIVE`로(문서의 SW 켜기 1단계) | SW spec 6개 중 2 failed, 4 did not run. `/tmp/ca-sw-builds-*` 2개(각 18MB) 남음(11-03, 11-07) |
| a11y 변이: `/examples/states`에 alt 없는 `img`·이름 없는 `button`, 보호 라우트 상세에 이름 없는 `button`. `--repeat-each=5` | 5/5, 5/5 검출 |
| `reference-route`, `reference-save`, `reference-form`, `production-csp` chromium | 14/14 통과 |
| 변이: reference-route 목 응답을 `[{ wrong: true }]`로 | spec 단언 `getByText('Browser reference')`에서 실패 |
| visual(`platform.visual.spec.ts`) chromium | 5/5 통과. 상태 화면 기준 이미지는 본문을 담고 있다 |
| browser-capabilities chromium, 포트 4414 | 20 통과 / 1 실패(`resumable-upload` CORS, 포트 하드코딩) |
| `node scripts/test-performance.ts` 5번(각 5회 측정) | PASS 2 / FAIL 3(11-04) |
| `node scripts/scale/measure-feature-shape-growth.ts --sizes=0,25 --repeats=1` | 0개: 716,418 inst, 초기 203,481 B, lazy 23,572 B. 25개: 3,616,223 / 284,609 / 149,766(11-05) |
| `tests/system` (worktree) | 17 failed / 95 passed. 15건은 bwrap `Can't mkdir …/.git: Not a directory`(worktree는 `.git`이 파일) |
| `tests/system` (clone, `.git` 디렉터리, 전제 검사 PASS) | 2 failed / 110 passed. 단독 재실행과 기대 문자열 수정 실험 → 11-01, 11-06 |
주의: `test-performance.ts`는 안에서 `corepack pnpm preview`를 띄운다. 오케스트레이터의 경고(worktree에서 pnpm 금지) 전에 `pnpm_config_verify_deps_before_run=false`로 5번 실행했다. 실행 뒤 원본 `node_modules`가 그대로인 것을 확인했고, 경고 뒤에는 pnpm을 부르는 명령을 돌리지 않았다.
## 2. 대표 흐름 (체크리스트 2절)
### 2.1 정상 흐름 — merge 게이트 FE-GATE-008의 저장 E2E
```
PR 커밋
→ playwright.config.ts: forbidOnly(:5), retries 없음(기본 0), webServer가 build+preview(:17-22)
→ dist 재빌드, 새 브라우저 context
→ reference-save.spec.ts: API는 page.route로 목(:21-35), 저장·429 뒤 재시도(:47-99)
→ 실패: strict fixture가 console/pageerror/requestfailed를 모아 테스트 끝에 실패(tests/support/browser/strict-browser-test.ts:27-58)
의도한 실패만 좁은 정규식으로 허용(reference-save.spec.ts:67-70)
→ 결과: junit(artifacts/tests/e2e/results.xml) → 게이트 증거. forbidOnly 누락은 check-test-evidence가 잡음(scripts/check-test-evidence.ts:384-393)
```
이 흐름은 chromium에서 끝까지 확인했다(14/14, 스키마 변이 검출).
### 2.2 피해가 큰 흐름 — 운영 승격 drill
```
workflow_dispatch stage=production
→ promotion job의 archive를 SHA로 대조해 추출(.gitea/workflows/quality-gates.yml:399-405)
→ production_gate 매트릭스 FE-GATE-021~025(:381-387), 각 drill에 --release-root(config/ci/gates.json:484-494, :530-573), expect "pass"
→ drill: 추출한 release의 dist/release-manifest.json, config.json, .vite/manifest.json 읽기(scripts/drill-runbook.ts:88-108, :145-166)
→ 외부 I/O 없음(브라우저·provider·live API 없음)
→ 실패: 자산 누락·tuple 불일치 → FAIL exit 1 / 관측 못 한 항목 → UNVERIFIED exit 3(:458-475)
→ 결과: 모든 실행에서 production_gate 실패 → field_gate는 needs 때문에 건너뜀(:416-418) → PROD_PROMOTION_READY·FIELD_SLO_READY 거짓(scripts/lib/promotion-readiness.ts:56-58)
```
로컬 판정은 정직하다. PASS로 가는 입력이 없다는 점이 11-02다.
### 2.3 변경 흐름 — 다운스트림이 Service Worker를 켠다
```
docs/architecture/optional-adapter-recipes.md:112-113 "SERVICE_WORKER를 ACTIVE로"
→ src/features/installed-runtime-capabilities.ts:39 수정
→ FE-GATE-008 e2e: service-worker-*.spec.ts beforeAll → prepareServiceWorkerBuilds
→ repo를 /tmp로 복사(tests/e2e/support/service-worker-builds.ts:118-124)
→ "= null;" 문자열을 정확히 1회 찾아 치환(:125-129) → 없음 → 예외(:89-91)
→ 결과: 2 failed / 4 did not run, 임시 복사본은 지우지 않음
```
재현했고, memento-frontend 동기화 기록에도 같은 결과가 있다(11-03).
## 3. 28개 관점 판정표 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가.
| 번호 | 관점 | 판정 | 이유와 근거 |
|---|---|---|---|
| 1 | 코드 성숙도 | > | src 담당 영역 |
| 2 | 구조적 성숙도 | > | 12 |
| 3 | 변경 용이성 | P | 테스트 기대값을 레지스트리에서 읽는다(`tests/e2e/accessibility.spec.ts:24`, `old-tab-chunk-recovery.spec.ts:22-23`). SW harness는 소스 문자열에 묶여 있어 기본값을 바꾸면 깨진다(11-03) |
| 4 | 인지 부하 | P | 어느 테스트가 어느 게이트에서 도는지는 `config/ci/gates.json`과 `ungated-*.json`에서 찾을 수 있다. SW spec의 전제 4개는 코드를 거꾸로 읽어야 안다(11-03) |
| 5 | 위험 가시성 | P | drill record가 관측하지 못한 항목과 필요한 증거를 적는다(`scripts/drill-runbook.ts:136-139`). PASS 경로가 없다는 사실(11-02)과 SW spec 전제(11-03)는 드러나지 않는다 |
| 6 | 실패 성숙도 | O | 브라우저에서 429 뒤 재시도(`reference-save.spec.ts:72-99`), 스키마 위반 표시(변이로 확인), 깨진 SW 해제(`service-worker-recovery.spec.ts:75-151`), 청크 누락 뒤 1회 reload(`old-tab-chunk-recovery.spec.ts:79-127`)를 실제로 돌린다. chromium 통과 |
| 7 | 운영 성숙도 | P | drill이 거짓 PASS를 내지 않는다(자산 삭제 → FAIL 재현). production·field 단계는 PASS할 수 없다(11-02) |
| 8 | 디버깅 가능성 | P | trace `retain-on-failure`, UNVERIFIED 메시지가 빠진 항목을 나열한다(`drill-runbook.ts:462-474`). strict fixture는 `pageerror`의 이름만 남긴다(`strict-browser-test.ts:36-37`). 엔트리 JS가 0바이트여도 drill은 "no local check failed"라고 쓴다(재현) |
| 9 | 유지보수 성숙도 | P | 현재 코드와 다른 규모 기준선(11-05), 커밋된 실행 로그(11-09), 두 벌로 갈라진 helper(11-07) |
| 10 | 테스트 성숙도 (깊게) | P | 강점: 모든 Playwright 설정에 `forbidOnly: true`(`playwright*.config.ts:5`), `retries` 없음, 엄격 fixture. a11y 변이 5/5·5/5, 스키마 변이 검출, drill 자산 삭제 FAIL(모두 이번 실행). 약점: FE-GATE-013의 `test:system`이 main에서 항상 실패(11-01, E3), 부하 레이스(11-06), 죽은 가드 테스트(11-08), SW를 켠 제품에서 SW spec이 준비 단계 실패(11-03) |
| 11 | 데이터 성숙도 | - | 이 영역에 데이터 이관·보관 경로가 없다 |
| 12 | 동시성 성숙도 | O | 두 페이지로 BroadcastChannel·IndexedDB versionchange 등을 확인하는 capability 테스트가 chromium에서 통과(20/21, 실패 1건은 포트 하드코딩). Firefox·WebKit은 이번에 돌리지 않음 |
| 13 | 확장성 (깊게) | P | pr tier가 FE-GATE-005에서 돈다(`config/ci/gates.json:217-218`, `scripts/scale/run-scale-profile.ts:14-19`). CPU 1개를 busy loop 3개와 나눠도 S0~S2 성장 검사 10/10 통과. 실제 모양 기능으로 재고 검증·비검증을 나눴다(`config/scale/feature-shape-ceilings.json:8-40`). 선언 상한은 "검증된 용량이 아니다"라고 적었다(`:8`). 기준선이 현재 코드와 다르고 커밋 기록이 없다(11-05) |
| 14 | 성능 성숙도 (깊게) | P | lab: 5회 cold 중앙값, 조건 기록, `--strictPort`, 서빙 빌드 확인(`scripts/lib/lab-performance.ts:36-111`, `scripts/test-performance.ts:54`, `:182`, `:193`). 같은 빌드에서 PASS 2 / FAIL 3(11-04). 재측정한 초기 JS 여유는 1,319 B다(204,800 − 203,481) |
| 15 | 보안 성숙도 | > | 13(`tests/system`의 샌드박스·아카이브 검증). 11-01만 이 영역에서 다룬다 |
| 16 | 의존성 성숙도 | O | `@playwright/test` 1.62.0, `@axe-core/playwright` 4.12.1 고정(`package.json:164`, `:170`). CI가 3엔진을 설치한다(`quality-gates.yml:69`) |
| 17 | API / Contract | > | 07 |
| 18 | 배포 성숙도 (깊게) | P | SW 없는 기본 구성의 구 탭 청크 복구(`old-tab-chunk-recovery.spec.ts:79-127`)와 SW 켠 A→B 업데이트·이전 캐시 응답(`service-worker-update.spec.ts:222-262`)이 chromium에서 통과. SW를 켠 제품에서는 이 spec이 돌지 않는다(11-03). 자산 보존·전환은 provider 몫이고 drill로 PASS를 기록할 수 없다(11-02). Firefox SW는 quarantine(만료 2027-03-31) |
| 19 | 설정 성숙도 | P | lab 포트는 환경변수 + `--strictPort`. `tests/browser-capabilities/resumable-upload.spec.ts:7`에 4174가 박혀 있다(다른 포트에서 CORS 실패 재현) |
| 20 | 개발자 경험 | P | spec 하나도 전체 빌드를 한다(`playwright.config.ts:17-22`). git worktree에서는 `test:system` 15건이 bwrap `.git` 오류로 실패한다(`scripts/run-and-validate-provider.ts:271-276`, 영역 13). worktree에서 pnpm 스크립트는 공유 `node_modules`를 건드릴 위험이 있다(FOLLOW-UP 5절 F-4 계열) |
| 21 | Guardrail 성숙도 | P | `forbidOnly` 누락 검사와 quarantine 만료 검사가 있다(`scripts/check-test-evidence.ts:294-304`, `:384-393`). merge 게이트 하나가 main에서 빨간 것을 어느 장치도 알리지 않았다(11-01). quarantine 주석 하나가 같은 파일의 모든 skip을 허용한다(`:293-304`) |
| 22 | 추상화 성숙도 | P | 두 빌드 준비 helper가 두 벌이다(11-07). 나머지 테스트 helper는 얇다 |
| 23 | 일관성 | P | 공용 strict fixture를 쓰고, 예외(`service-worker-recovery.spec.ts:87-90`)는 이유가 주석에 있다. helper 두 벌의 제외 목록·실패 정리가 다르다(11-07) |
| 24 | 네이밍 / 의미 | P | drill 문구는 정직해졌다("not observed locally; needs …"). 테스트 이름 "keeps no constant recovery verdict"는 실제 검사보다 넓다(11-08). `CONTEXT_MAX_FEATURES`를 "direct-feature budget"이라 부르지만 검증 용량이 아니다(`src/contexts/reference-context/context-module.ts:4`). FE-RB-001·003·004 record에는 `--release-root` release의 releaseId가 적히지만, 검사 대상은 그 release가 아니라 체크아웃한 소스의 정책이다(`drill-runbook.ts:168-193`, `:244-314`, `:405-414`) |
| 25 | 조직 확장성 | > | 14 |
| 26 | Ownership 성숙도 | P | quarantine에 owner·expires, 기준선에 승인자가 있다. 라운드 검증에서 FE-GATE-013 결과를 아무도 보지 않았다(11-01) |
| 27 | 삭제 가능성 | P | 샘플 제거가 샘플 e2e 3개를 함께 지운다(`scripts/test-sample-removal.ts:52-54`). 제거 뒤 e2e는 돌지 않는다(FOLLOW-UP 09-07). 커밋된 로그를 다운스트림이 매번 지운다(11-09) |
| 28 | 회복 가능성 (깊게) | P | 깨진 SW를 `REMOVE_REGISTRATION` release로 해제하는 흐름이 chromium에서 통과. drill은 자산 누락을 FAIL로 잡는다(재현). provider 전환 뒤 smoke를 증거로 넣을 방법이 없다(11-02). 이전 release 재검증(`verify:promotion --archived`)의 system test가 main에서 실패한다(11-01) |
집계(적용 22개): 충족 3(6, 12, 16) · 부분 충족 18 · 미충족 0 · 미검증 0 · 적용 제외 1(11) · 다른 영역 6.
미충족이 없는 이유: 각 관점의 핵심 통제는 동작한다. 남은 결함은 특정 게이트·구성에 한정된다. 다만 11-01은 merge 게이트 하나를 통째로 빨갛게 만든다. 오케스트레이터가 종합 판정에서 21번을 미충족으로 볼 근거는 충분하다.
## 4. 설계 선택 설명 (41절)
### 4.1 drill 판정: 로컬에서 관측한 것만 PASS/FAIL, 나머지와 provider 범위는 항상 UNVERIFIED
1. **무엇이 필요한가:** 운영 승격 전에 런북 5개의 복구 수단이 동작한다는 증거. 소비자는 CI `production_gate`와 롤백하는 운영 담당자다.
2. **지킬 성질:** 관측하지 않은 것을 PASS로 적지 않는다. 로컬에서 확인할 수 있는 결함(자산 누락, tuple 불일치)은 FAIL로 끝낸다.
3. **현재 보장:** 3상태와 결합 규칙(`scripts/contracts/release-artifacts.ts:736-743`). record 스키마가 result와 개별 판정의 일치를 강제한다(`:771-787`). 자산 누락 FAIL을 재현했다. **보장하지 않는 것:** provider 전환, smoke, live traffic. 파일 내용 무결성(0바이트 엔트리는 UNVERIFIED). PASS 도달.
4. **대안:** (a) 현상 유지. (b) 외부 증거 파일을 받는 입력(hosting 헤더의 live 모드와 같은 방식). (c) 로컬 흉내: 두 release 디렉터리 + active pointer + 브라우저 smoke(지난 11-01의 제안 2). (d) production·field 단계를 기본으로 끄고 켤 조건을 문서화.
5. **대안별 비용:** (a) 비용 0, 정직, 단계가 항상 빨갛다. (b) 스키마·검증 코드가 늘고 증거 위조 방지(서명·run id 연결)가 필요하다. 대신 PASS가 가능하고 다운스트림 구현이 한 형식으로 모인다. `scripts/lib/provider-evidence.ts`의 서명 검증을 재사용할 수 있다. (c) 템플릿 안에서 절반을 검증하지만 production job에 브라우저가 필요하고 provider 특성은 여전히 모른다. (d) 가장 싸지만 게이트가 문서로 물러난다.
6. **현재 조건에서의 판단:** 기록된 의도(D-14, `SPEC.md:58`)는 "거짓 PASS 제거"와 "운영 승격은 provider 증거를 요구"다. (a)는 앞의 것을 달성했다. 뒤의 것은 증거를 넣을 입구가 없어 구현되지 않았다. 리뷰어 추론: (a)는 중간 상태로는 맞다. 하지만 넘을 방법이 없는 게이트를 기본값으로 복제하는 비용이 크다. (b)나 (d)로 끝을 맺어야 한다(11-02).
7. **재검토 조건:** 공식 지원 호스팅 provider가 정해지면 (c)를 넘어 실제 전환 drill이 가능하다. CI(U-1)가 켜지고 production 단계를 실제로 쓰는 다운스트림이 생기면 (b)가 우선이다.
### 4.2 두 빌드 브라우저 harness: repo를 임시 폴더에 복사하고 소스 문자열을 치환해 두 번 빌드
1. **무엇이 필요한가:** 신·구 빌드 공존(구 탭, SW 업데이트, 깨진 SW 복구)을 실제 브라우저와 실제 production build로 확인한다. 작업 트리와 e2e 서버가 쓰는 `dist`는 건드리지 않는다.
2. **지킬 성질:** 제품의 빌드 스크립트를 그대로 쓴다(`service-worker-update.spec.ts:264-271`). 두 빌드가 실제로 다르다(`:239`, `old-tab-chunk-recovery.spec.ts:88-89`). 치환이 조용히 무효가 되지 않는다.
3. **현재 보장:** `replaceOnce`가 정확히 1회 일치를 요구한다(`tests/e2e/support/service-worker-builds.ts:83-93`). 그래서 조용한 무효 치환은 없다. **보장하지 않는 것:** 소스가 다른 모양(이미 ACTIVE, 수정된 fetch 처리)이면 준비 단계에서 실패한다. SW 쪽 helper는 실패 시 복사본을 지우지 않는다.
4. **대안:** (a) 현상 유지. (b) helper가 현재 선택을 읽고 필요한 치환만 한다(이미 ACTIVE면 건너뜀). 캐시 단언은 빌드가 만든 SW 자산 목록과 비교한다. (c) 빌드 입력(환경변수·define)으로 변형을 주입한다. (d) 제품별 fixture 설정 파일을 둔다.
5. **대안별 비용:** (a) 단순하지만 템플릿 기본값에서만 동작한다. (b) 수십 줄. 전제 1·2가 풀리고 3·4(fetch 한 줄, host 함수 선언)는 남는다. (c) 제품 코드에 테스트용 입구가 생긴다. "설정 문자열로 경로를 만들지 않는다"는 정적 선택 원칙(`src/features/installed-runtime-capabilities.ts:18-20`)과 부딪힌다. (d) 개념이 하나 늘어난다.
6. **현재 조건에서의 판단:** 정적 선택 원칙(기록된 의도)을 지키려면 소스를 편집하는 방식이 맞다. 문제는 방식이 아니라, 전제를 적지 않고 템플릿 기본값만 가정한 것이다. (b)와 전제 주석으로 충분하다(11-03, 리뷰어 추론).
7. **재검토 조건:** 다운스트림 두 곳 이상이 같은 spec을 고쳐 쓰게 되면 (d)를 검토한다. 템플릿의 SW 기본값이 ACTIVE로 바뀌면 전제 1이 뒤집힌다.
### 4.3 lab 성능 게이트: 절대 예산, 5회 cold 중앙값, CPU 4배·네트워크 제한, 페이지 안의 시계
1. **무엇이 필요한가:** 릴리스 후보가 LCP·CLS·route 전환 예산을 넘지 않는다는 판정(FE-GATE-026).
2. **지킬 성질:** 같은 빌드면 같은 판정. 측정 대상이 그 빌드. 측정 조건 기록.
3. **현재 보장:** 대상 빌드 확인, 포트 충돌 거부, 조건과 모든 표본 기록, 중앙값 판정. **보장하지 않는 것:** 러너 부하에 따른 판정 안정(PASS 2 / FAIL 3 재현). INP 자체. 클릭의 Event Timing 길이(`clickEventDurationMs`, 이번 중앙값 48ms)는 기록만 하고 판정하지 않는다. 판정하는 interaction에는 lazy chunk 다운로드가 들어간다(`docs/operations/performance-evidence.md:52-55`에 적혀 있음).
4. **대안:** (a) 현상 유지. (b) 측정 전 부하 가드: 기준을 넘으면 UNVERIFIED(exit 3). (c) 같은 job에서 기준 빌드와 A/B로 재고 차이로 판정. (d) 반복 수를 9~15회로. (e) lab은 참고용으로 내리고 field가 판정.
5. **대안별 비용:** (b) 코드 몇 줄. drill·hosting과 같은 3상태 패턴이다. 부하가 높으면 결과가 없다. (c) 시간 2배, 러너 속도 차이를 상쇄한다. (d) 분산은 줄지만 모든 표본이 함께 느려지는 부하 편향은 못 없앤다. 이번 두 번째 실행은 표본 5개가 모두 195ms 이상이었다. (e) field 단계는 11-02 때문에 CI에서 닿지 않아 지금은 대체가 안 된다.
6. **현재 조건에서의 판단:** 러너 조건은 미정이다(U-1). (b)가 가장 작고 정직하다(리뷰어 추론).
7. **재검토 조건:** 전용·고정 러너가 생기면 (a)를 유지할 수 있다. 기준 빌드 산출물을 캐시할 수 있으면 (c)가 낫다.
## 5. 발견 사항 (36.3)
심각도 분포: Critical 0 · High 1 · Medium 3 · Low 5.
### 11-01 `tests/system`의 기대 문자열이 13-04 뒤의 출력과 달라, merge 게이트 FE-GATE-013(security)이 main에서 항상 실패한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 10, 21, 26, 9 (+30.8) |
| 근거 | `scripts/verify-exact-promotion-bundle.ts:78`은 `Exact promotion bundle verification (${freshness}): PASS`를 출력한다(`839205c`, 13-04에서 바뀜). `tests/system/ci-runner/ci-artifact-contract.test.ts:1259`는 `"Exact promotion bundle verification: PASS"`를 기대한다. `test:system`은 FE-GATE-013의 명령이다(`config/ci/gates.json:232-233`, `:1987-1990`). FE-GATE-013은 `MERGE_READY`에 있다(`scripts/lib/promotion-readiness.ts:14`). CI merge 매트릭스에도 있다(`.gitea/workflows/quality-gates.yml:54`). **실행:** `.git`이 디렉터리인 clone(af3d8e6)에서 `check-system-test-prerequisites` PASS, `run-vitest run tests/system` → 2 failed / 110 passed. 이 케이스는 매번 실패했다. 기대값을 `(current)`가 들어간 문자열로 바꾸면 통과했다. 지난 라운드 검증 기록(`2026-09-25-maturity-review/README.md` 11절)과 이번 오케스트레이터 게이트 목록 모두 `test:system`이 없다 |
| 발생 조건 | FE-GATE-013을 실행하는 모든 CI 실행(PR·main), 로컬 `test:system` |
| 영향 | CI를 켜면(U-1) 모든 PR이 security 게이트에서 막힌다. 팀은 이 게이트를 무시하거나 끄게 된다. 그러면 샌드박스·아카이브 검증의 실제 회귀가 같은 빨간 결과에 섞여 보이지 않는다. 제품 repo 2곳도 이 커밋을 받았고, 두 동기화 기록의 게이트 표에 `test:system`이 없다 |
| 심각도·우선순위 | High · P1 — 지원하는 CI 조건에서 merge 게이트 하나가 결정적으로 실패한다. CI를 켜기 전에 고쳐야 한다. 수정은 한 줄이다. 지난 라운드는 같은 성격의 10-01("피해가 개발·CI 비용에 한정, 수정 비용 작음")을 Medium으로 조정했다. 일관성을 맞추려면 오케스트레이터가 조정할 수 있다 |
| 통제·증거 | 목표 M3 / 확인 M3(검사는 있음), 다만 라운드 검증이 결과를 보지 않아 실제 효과는 없었다 · E3 |
| 확실성과 남은 가정 | 결정적 실패다. 같은 파일의 cgroup 테스트 실패는 다른 원인이다(11-06). CI 러너가 systemd·bwrap·cgroup v2 전제를 만족하는지는 U-1 범위다 |
| 결정의 근거 | 적용 제외 — 기대 문자열 한 줄이 출력 변경을 따라가지 못한 단순 결함이다 |
| 이해 비용 | 적용 제외 — 지역 결함 |
| 최소 개선 방향 | 기대값을 `Exact promotion bundle verification (current): PASS`로 바꾼다. `--archived` 경로 케이스를 하나 더한다. 라운드 검증 목록(오케스트레이터 게이트 표)에 `test:system`을 넣는다 |
| 대안 비교 | 적용 제외 — 계약 위반을 바로잡는 단순 수정 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 없음 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 전제를 갖춘 호스트에서 `test:system`이 이 케이스로 실패하지 않는다. 다음 라운드 게이트 기록에 `test:system` 결과가 있다 |
| 검증 방법 | clone에서 `node scripts/run-vitest.ts run tests/system/ci-runner/ci-artifact-contract.test.ts -t 'downstream CLI'` |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 11-02 운영 drill은 어떤 입력으로도 PASS할 수 없어, production 단계와 field 단계가 구조적으로 막혀 있다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 7, 18, 28, 21, 5 (+30.8) |
| 근거 | FE-RB-002~005는 `providerVerificationRequired: true`가 상수다(`scripts/drill-runbook.ts:240`, `:270`, `:312`, `:353`). 이 값이 true면 결과는 무조건 UNVERIFIED다(`scripts/contracts/release-artifacts.ts:741`). FE-RB-001은 관측 불가 항목 3개와 `negativeFixtureFailedAsExpected: "UNVERIFIED"`가 무조건이다(`drill-runbook.ts:179-190`). drill은 runbook id와 `--release-root`만 읽는다(`:437-450`). provider 증거를 넣는 인자·환경변수·파일이 없다. 대조: hosting 헤더 게이트는 `HOSTING_BASE_URL` live 모드로 PASS할 수 있다(`docs/operations/release-cache-rollback.md:57-62`). CI는 FE-GATE-021~025를 `expect: "pass"`로 돌리고(`config/ci/gates.json:484-494`, `:530-573`), `field_gate`는 `needs: production_gate`다(`.gitea/workflows/quality-gates.yml:416-418`). 단위 테스트가 "PASS가 아니다"를 고정한다(`tests/unit/runbook-drill.test.ts:100-104`). 문서는 "the production stage stays open. That is the intended result"(`docs/operations/ci-quality-gates.md:331-333`), "It ends UNVERIFIED until the provider switch and smoke are recorded"(`release-cache-rollback.md:38-39`)라고 적는다. 기록 위치와 형식은 어디에도 없다. **실행:** 완전한 빌드에서 5개 모두 exit 3 |
| 발생 조건 | stage `production`·`field`로 workflow를 돌릴 때마다 |
| 영향 | 템플릿 그대로는 `PROD_PROMOTION_READY`와 `FIELD_SLO_READY`가 참이 될 수 없다(`promotion-readiness.ts:56-58`). FE-GATE-018은 CI에서 한 번도 실행되지 않는다. 다운스트림은 (a) 빨간 단계를 무시하거나, (b) 각자 입력 경로를 만들거나, (c) 단계를 끈다. (a)는 게이트 무시를 습관으로 만든다. (b)는 제품마다 형식이 갈라진다. 지난 11-01의 거짓 PASS는 사라졌다. 이 발견은 그 반대편의 빈칸이다 |
| 심각도·우선순위 | Medium · P2 — 데이터·보안 피해는 없다. 운영 단계 게이트 전체가 쓸 수 없는 상태로 복제된다 |
| 통제·증거 | 목표 M3 / 확인 M2(로컬 판정은 정직, PASS 경로 없음) · E2(단위 테스트) + E3(drill 실행) |
| 확실성과 남은 가정 | PASS가 불가능하다는 것은 코드로 확정이다. "production 단계는 열린 채로 둔다"는 기록된 의도다. 증거 형식을 템플릿이 정해야 하는지는 판단의 문제다. 리뷰어 추론: 형식만이라도 템플릿이 정해야 다운스트림 구현이 갈라지지 않는다 |
| 결정의 근거 | 4.1절. 확인한 사실(상수·결합 규칙), 기록된 의도(D-14, `SPEC.md:58`), 추론(형식 부재의 비용)을 나눠 적었다 |
| 이해 비용 | production 단계를 켜려는 운영 담당자가 drill 소스, record 스키마, workflow, promotion formula 네 곳을 읽고 PASS 경로가 없다는 것을 스스로 알아내야 한다 |
| 최소 개선 방향 | drill에 외부 증거 입력 하나를 둔다. 예: `--provider-evidence <record.json>`(releaseId, 전환 시각, smoke 결과, run id 또는 서명). 스키마를 통과하고 releaseId가 맞으면 해당 관측 불가 항목을 PASS/FAIL로 바꾼다. 또는 production·field 단계를 기본으로 끄고, 켤 때 필요한 것을 문서의 체크리스트로 둔다 |
| 대안 비교 | 4.1절 (a)~(d). (b) 외부 증거는 PASS를 가능하게 하지만 검증 코드가 는다. (d) 단계 끄기는 가장 싸지만 게이트가 문서로 물러난다 |
| 단순화의 보존 조건 | 로컬에서 관측하지 못한 항목을 PASS로 적지 않는다(D-14). 자산 누락은 계속 FAIL이다 |
| 비용·부작용 | 입력 스키마·검증·테스트. 운영 담당자의 증거 생성 절차 |
| 재검토 조건 | 공식 지원 호스팅 provider가 정해지면 drill이 전환·smoke를 직접 할 수 있다 |
| 완료 기준 | 유효한 provider 증거를 주면 FE-RB-005가 PASS다. releaseId가 다르거나 만료된 증거는 PASS가 아니다. 또는 production·field 단계가 기본 꺼짐으로 문서화되고, `field_gate`가 도달할 수 없는 선행 조건에 묶이지 않는다 |
| 검증 방법 | 단위 테스트에 증거 있음·없음·불일치 3케이스 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 11-03 SW e2e 두 spec의 전제가 소스 문자열 치환과 단언 안에 숨어 있어, 문서대로 SW를 켜기만 해도 준비 단계에서 실패하고 무엇을 고칠지 알려 주지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 10, 3, 5, 18, 28, 20 (+30.5) |
| 근거 | 전제는 네 개다. ① 선택 줄이 정확히 `const SERVICE_WORKER: InstalledServiceWorkerSelection \| null = null;`이다(`tests/e2e/support/service-worker-builds.ts:125-129`, 없으면 `:89-91`에서 예외). ② 캐시는 `dist/assets/*` 전부이고 그 밖은 없다(`service-worker-update.spec.ts:86-90`, `:124`). `PWA_STATIC_ASSETS` 기본 목록과 Vite 기본 `assets/` 폴더를 가정한다(FOLLOW-UP 06-08과 같은 가정). ③ SW fetch 처리의 한 줄(`service-worker-recovery.spec.ts:35-39`). ④ `createServiceWorkerRuntimeHost` 선언 문자열(`service-worker-builds.ts:130-136`). spec 머리 주석은 ①을 설명하지만(`service-worker-update.spec.ts:15-24`), 제품이 이미 ACTIVE일 때 어떻게 되는지와 ②~④는 전제로 적지 않는다. SW 켜기 체크리스트(`docs/architecture/optional-adapter-recipes.md:109-131`)와 선택 SSOT 주석(`src/features/installed-runtime-capabilities.ts:29-30`)은 이 spec을 언급하지 않는다. **실행:** worktree에서 체크리스트 1단계(선택을 `ACTIVE`로)만 적용 → chromium에서 SW spec 6개 중 2 failed, 4 did not run. 메시지는 `Expected exactly one "const SERVICE_WORKER: … = null;" in /tmp/ca-sw-builds-…/src/features/installed-runtime-capabilities.ts.`였다. **다운스트림:** memento-frontend `chore/template-sync-v0.2.0:docs/operations/template-sync-2026-09-29.md` "Introduced and escalated"에 두 spec이 "switches the template's null worker selection on by source replacement and expects the hashed-only asset set" 때문에 실패했다고 적혀 있다. 제품은 worker를 ACTIVE로 내보내고 `index.html`과 사진을 미리 캐시한다. e2e는 67 passed / 3 failed / 4 did not run이고, 후속 5번 "Adapt the template's Service Worker e2e specs to the product's PWA asset set"으로 미뤘다 |
| 발생 조건 | 다운스트림이 SW를 켜거나, 선택 줄 모양을 바꾸거나, 사전 캐시 목록을 넓히거나, fetch 처리를 고칠 때 |
| 영향 | SW를 켠 제품에서, SW 업데이트·구 자산 응답·kill switch를 실제 브라우저로 확인하는 유일한 spec이 빨갛게 된다. 제품은 이 spec을 quarantine하거나 지우기 쉽다. 그러면 보호가 템플릿(SW 꺼짐)에서만 돌고, SW가 실제로 켜진 곳에서 빠진다 |
| 심각도·우선순위 | Medium · P2 — 피해는 테스트 보호 상실이다. 제품 repo 한 곳에서 이미 일어났다 |
| 통제·증거 | 목표 M3 / 확인 M2(템플릿 기본 구성에서만 M3) · E3(재현 + 다운스트림 기록) |
| 확실성과 남은 가정 | ①은 재현했다. ②는 memento 기록과 코드 읽기로 확인했고 재현하지 않았다. ③·④는 코드 읽기다 |
| 결정의 근거 | 4.2절. 소스 편집 방식은 정적 선택 원칙(기록된 의도)에 맞다. 문제는 전제를 적지 않은 것이다(추론) |
| 이해 비용 | SW를 켠 제품 개발자가 spec 2개, helper 1개, SW 자산 생성기, SW 엔트리의 정확한 문자열을 읽고 전제 4개를 거꾸로 찾아야 한다. memento는 이를 "PWA가 무엇을 증명해야 하는지 결정이 필요"로 미뤘다 |
| 최소 개선 방향 | (1) helper가 현재 선택을 읽고, 이미 `ACTIVE`면 치환을 건너뛴다. (2) 캐시 단언을 `dist/assets` 목록 대신 빌드가 만든 SW 자산 목록(`.generated/frontend-runtime/service-worker-assets.ts`, `scripts/generate-service-worker-assets.ts:27`)과 비교한다. (3) 두 spec 머리에 "전제와 바꿀 곳" 3~4줄. (4) SW 켜기 체크리스트에 "e2e 두 spec이 제품 구성에서 도는지 확인" 한 줄 |
| 대안 비교 | 4.2절 (a)~(d). 빌드 입력 주입(c)은 정적 선택 원칙과 부딪혀 제외한다 |
| 단순화의 보존 조건 | A→B 업데이트, 서버에서 지운 구 청크를 이전 캐시가 응답, 깨진 worker를 `REMOVE_REGISTRATION`이 해제하는 것을 실제 브라우저로 확인하는 성질은 그대로 둔다 |
| 비용·부작용 | helper 수십 줄, 단언 1개 변경 |
| 재검토 조건 | 템플릿의 SW 기본값이 ACTIVE로 바뀌면 전제 ①이 뒤집힌다 |
| 완료 기준 | 선택을 ACTIVE로 바꾼 사본에서 두 spec이 준비 단계를 통과한다. 사전 캐시에 `index.html`을 더한 사본에서 캐시 단언이 생성된 목록 기준으로 통과한다 |
| 검증 방법 | 위 두 변이를 worktree에서 chromium으로 실행한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 11-04 lab 성능 게이트(FE-GATE-026)는 중앙값 판정도 같은 빌드에서 뒤집힌다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 14, 10, 21, 18 |
| 근거 | 5회 cold 측정의 중앙값으로 판정한다(`scripts/lib/lab-performance.ts:36`, `scripts/test-performance.ts:189-198`). CPU 4배 감속·네트워크 제한을 건다(`:91-98`). interaction은 클릭부터 대상 heading이 DOM에 들어올 때까지이고 lazy chunk 다운로드가 들어간다(`:119-146`). loadavg는 기록만 하고(`:188-191`, `:209`) 판정에 쓰지 않는다(`scripts/lib/performance-budgets.ts:35-64`). 예산은 interaction 200ms, LCP 2,500ms다(`config/performance/budgets.json:7-11`). 문서는 i5-10400F에서 "중앙값 판정은 두 번 모두 통과였다"고 적는다(`docs/operations/performance-evidence.md:60-65`). **실행**(같은 빌드, Core Ultra 7 155H 22스레드, loadavg 16~22): 5번 실행해 PASS 2 / FAIL 3. interaction 중앙값 173~364ms(표본 149~440ms), LCP 중앙값 2,224~2,728ms. 실패 3번 중 2번은 LCP도 예산을 넘었다 |
| 발생 조건 | 공유 러너, 다른 작업과 겹친 러너, 느린 CPU |
| 영향 | 릴리스 게이트 판정이 코드가 아니라 러너 상태로 바뀐다. 다시 돌려 통과시키면 숨은 재시도가 된다. 반대로 실제 회귀가 "러너 탓"으로 넘어간다. 지난 11-07의 완료 기준("뒤집힐 때 분산이 증거에 남는다")은 충족하지만, 게이트는 여전히 뒤집힌다 |
| 심각도·우선순위 | Medium · P2 — 사용자 피해는 없다. 릴리스 판정의 신뢰도 문제다. CI 러너 조건(U-1)을 모른다 |
| 통제·증거 | 목표 M3 / 확인 M2 · E3 |
| 확실성과 남은 가정 | 부하가 있는 호스트에서만 확인했다. 조용한 러너에서 판정이 안정적인지는 미확인이다. 다른 에이전트 부하가 실제 CI보다 클 수 있다 |
| 결정의 근거 | 4.3절 |
| 이해 비용 | 실패를 본 사람이 `lab.json`의 `context.runner.loadAverage`와 표본을 직접 해석해 "러너 탓인지"를 판단해야 한다 |
| 최소 개선 방향 | 측정 전 `loadavg[0] / logicalCpus`가 기준(예: 0.5)을 넘으면 `UNVERIFIED`(exit 3)로 끝낸다. drill·hosting과 같은 3상태 패턴이다 |
| 대안 비교 | 4.3절 (a)~(e). 반복 수 늘리기(d)는 모든 표본이 함께 느려지는 경우를 못 막는다 |
| 단순화의 보존 조건 | 측정 조건 기록, `--strictPort`, 서빙 빌드 확인은 그대로 둔다 |
| 비용·부작용 | 부하 기준 값을 정해야 한다. 부하가 높으면 결과가 없어 재실행이 필요하다 |
| 재검토 조건 | 전용 러너 라벨이 생기면 부하 가드는 필요 없어질 수 있다 |
| 완료 기준 | 같은 빌드를 부하 조건을 바꿔 10회 돌렸을 때 PASS·FAIL이 뒤집히지 않는다. 기준을 넘은 실행은 UNVERIFIED로 남는다 |
| 검증 방법 | CPU 부하를 준 상태와 조용한 상태에서 각 5회 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 11-05 기능 규모 기준선이 현재 코드와 달라졌는데, 측정 기록에 소스 커밋이 없어 알 수 없다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 13, 14, 9, 24 |
| 근거 | 기준선 `config/scale/feature-shape-growth.json`은 2026-09-27T04:03Z(13:03 KST)에 쟀다. 결과에 커밋·입력 트리 해시가 없다(`scripts/scale/measure-feature-shape-growth.ts:232-248`). 테스트는 모양만 본다(`tests/unit/feature-shape-growth.test.ts:62-99`). 측정 뒤 lane H 병합(`2b2cabb`, 13:19 KST, 08-04 문구 catalog 포함)과 08-13(`d7b81c6`)이 reference 기능을 바꿨다. **재측정**(af3d8e6, `--sizes=0,25 --repeats=1`): 기능 0개 초기 JS 203,481 B(기준선 200,001 B). 25개 284,609 B → 기능당 약 3,245 B(기준선 2,907 B, +12%). lazy는 기능당 약 5,048 B(기준선 6,800 B, −26%). instantiations는 기능당 115,992(기준선 114,680, 차이 작음). `config/scale/feature-shape-ceilings.json:24-26`은 "about 2.9 KB gzip per feature", "exceeded after a few more reference-shaped features"라고 적는다. 현재 여유는 204,800 − 203,481 = 1,319 B다. reference 모양 기능 하나면 넘는다 |
| 발생 조건 | 기준선 측정 뒤 기능 모양이나 부트 로딩이 바뀌는 변경 |
| 영향 | 다운스트림이 "기능당 2.9KB, 몇 개 더 가능"으로 계획한다. 실제로는 첫 기능에서 `check:bundle`이 실패한다. FOLLOW-UP P1과 같은 결론인데, 규모 문서의 표현이 이를 흐린다. 기준선이 어느 코드를 쟀는지 모르니 다음 측정과 비교할 수 없다 |
| 심각도·우선순위 | Low · P2 — 수치 차이는 10~30%이고 결론(초기 JS가 먼저 한계)은 같다. 규모가 이 템플릿의 선언된 목표 축이라 P2다 |
| 통제·증거 | 목표 M3 / 확인 M1(기준선 존재, 어긋남 검출 없음) · E3 |
| 확실성과 남은 가정 | 1회 재측정이다. 바이트와 instantiation 수는 결정적이라 반복하지 않았다. 시간 값은 비교하지 않았다 |
| 결정의 근거 | 적용 제외 — 기록 필드 누락과 오래된 수치의 단순 결함이다 |
| 이해 비용 | 기준선을 읽는 사람이 측정 시점의 코드를 git 이력과 시각으로 추정해야 한다 |
| 최소 개선 방향 | 측정 결과에 `git rev-parse HEAD`를 넣는다. 기준선을 현재 코드로 다시 잰다. ceilings의 "a few more"를 수치 대신 "`check:bundle` 여유 ÷ 기능당 증가"로 적는다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 필드 1개, 재측정 수 분(100개 포함 시 더 김) |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 기준선에 소스 커밋이 있다. 그 커밋에서 다시 재면 바이트 수가 같다 |
| 검증 방법 | 기준선 커밋에서 `--sizes=0,25 --repeats=1`로 재측정해 비교한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 11-06 `tests/system`의 cgroup 테스트는 부하가 있으면 이미 끝난 프로세스를 조회하다 실패한다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 10, 8 |
| 근거 | `tests/system/ci-runner/ci-artifact-contract.test.ts:749-790`. provider는 1.5초 뒤 끝난다(`:759`). `systemctl show`와 cgroup 파일 읽기 뒤에 `showProcessArguments(execution.child.pid)`를 부른다(`:790`). 이 함수는 `/proc`에서 못 읽으면 `ps`를 부르고, 실패하면 예외를 던진다(`:1860-1871`). 같은 파일은 이런 레이스를 알고 샘플러(`recordProviderProcessTree`)를 두었지만(`:1875-1900`), 이 단언은 샘플이 아니라 지금 시점 조회다. **실행:** clone, loadavg 13~20에서 3/3 실패(`ps failed:`, 각 15~17초) |
| 발생 조건 | 러너 부하 |
| 영향 | 11-01을 고쳐도 FE-GATE-013이 부하에서 무작위로 빨갛다. FOLLOW-UP 3절 P3(같은 파일의 시간 초과)와 같은 계열이다 |
| 심각도·우선순위 | Low · P2 — 테스트만의 문제다. CI를 켜기 전에 처리한다 |
| 통제·증거 | M2 · E3(부하 조건). 조용한 호스트 결과는 미확인 |
| 확실성과 남은 가정 | 부하와의 관계는 추론이다. 조용한 호스트에서 통과하는지 확인하지 못했다 |
| 결정의 근거 | 적용 제외 — 테스트 레이스의 단순 결함이다 |
| 이해 비용 | 적용 제외 |
| 최소 개선 방향 | 이 단언을 이미 있는 `recordProviderProcessTree` 샘플(프로세스가 살아 있던 동안의 argv)에 대해 한다 |
| 대안 비교·보존 조건·재검토 | 적용 제외 |
| 비용·부작용 | 수 줄 |
| 완료 기준 | loadavg 20 부근에서 5회 연속 통과 |
| 검증 방법 | `-t 'aggregate cgroup'`로 부하를 준 상태에서 5회 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 11-07 두 빌드 준비 helper가 두 벌로 갈라져, SW 쪽은 준비에 실패하면 임시 복사본을 남긴다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 9, 23, 22, 20 |
| 근거 | `tests/e2e/support/service-worker-builds.ts`와 `tests/e2e/support/fixture-builds.ts`가 같은 일(repo 복사 → `node_modules` 링크 → 문자열 치환 → 두 번 빌드)을 따로 한다. `replaceOnce`(`service-worker-builds.ts:83-93`)와 `editOnce`(`fixture-builds.ts:40-50`)가 같다. `run`도 같다(`:95-106`, `:52-63`). 갈라진 곳: SW 쪽 제외 목록에 `.tmp`가 없다(`:39-47` 대 `:18-27`). fixture 쪽은 실패하면 복사본을 지우고(`:69-90`), SW 쪽은 지우지 않는다(`:113-146`). **실행:** 11-03 실험에서 준비가 실패하자 `/tmp/ca-sw-builds-*` 2개(각 18MB)가 남았다 |
| 발생 조건 | 한쪽만 고치는 변경, SW spec 준비 실패 |
| 영향 | 한쪽 수정이 다른 쪽에 반영되지 않는다. 실패한 실행마다 /tmp에 repo 복사본이 쌓인다(FOLLOW-UP 00-03과 같은 종류) |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M2 · E3 |
| 확실성과 남은 가정 | 누수는 재현했다. `.tmp` 차이의 실제 영향(개발자 `.tmp`에 Node 설치가 있으면 복사량이 는다)은 추론이다 |
| 결정의 근거 | 현재 선택은 "SW 전용 helper"와 "일반 helper"의 병존이다. 기록된 이유는 없다. SW helper가 먼저 생겼고(R3-6) 일반 helper가 나중에 11-05에서 생겼다(추론, 파일 주석 기준) |
| 이해 비용 | 두 빌드 spec을 새로 쓰는 사람이 어느 helper를 쓸지, 왜 둘인지 알 수 없다 |
| 최소 개선 방향 | SW helper가 `prepareFixtureBuilds`를 쓰고, SW 선택·probe 치환만 `edit`로 넘긴다. `startBuildServer`는 공용 파일로 옮긴다 |
| 대안 비교 | 현상 유지: 파일 2개, 갈라짐 계속. 통합: 새 개념 없이 중복 약 60줄이 준다. 통합이 더 작다 |
| 단순화의 보존 조건 | 작업 트리·`dist`를 건드리지 않는다. 빌드 ID 주입, `beforeBuild`가 빌드 직전에 돌고 다음 빌드까지 남는 순서 |
| 비용·부작용 | SW spec 2개와 old-tab·boot spec의 import 수정 |
| 재검토 조건 | 두 helper가 서로 다른 복사 규칙을 가져야 하는 이유가 생기면 다시 나눈다 |
| 완료 기준 | 두 빌드 준비 코드가 한 곳에 있다. 준비 실패 뒤 /tmp에 남는 것이 없다 |
| 검증 방법 | 11-03의 ACTIVE 변이로 준비를 실패시키고 /tmp를 확인한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 11-08 drill의 "상수 판정 금지" 테스트가 옛 모양(`true`)만 찾아, 상수 `"PASS"`를 통과시킨다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 10, 21, 24, 28 |
| 근거 | `tests/unit/runbook-drill.test.ts:123-128`은 `assertion(…, true)`, `Asserted: true`, `injectedMountFailure = true` 정규식만 검사한다. 판정 타입은 이제 `"PASS" \| "FAIL" \| "UNVERIFIED"`라서 `true`는 타입 검사가 이미 막는다(`scripts/drill-runbook.ts:31-35`). **변이:** FE-RB-001 "product root mount"와 FE-RB-002 "critical route smoke"를 `assertion(…, "PASS")`로 바꿔도 9/9 통과했다. FE-RB-001 record에 `product root mount: PASS`가 남았다. drill 전체 결과는 다른 UNVERIFIED 때문에 여전히 UNVERIFIED였다 |
| 발생 조건 | 관측하지 않은 항목을 상수 PASS로 바꾸는 변경 |
| 영향 | 증거 record에 관측하지 않은 PASS 항목이 들어가도 테스트가 모른다. D-14의 "코드에 상수 판정을 두지 않는다"를 지키는 검출 장치가 사실상 없다. 행동 테스트가 일부를 대신 잡는다: FE-RB-001의 UNVERIFIED 항목을 전부 PASS로 바꾸면 `:100-104`가 잡는다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | 목표 M3 / 확인 M2 · E3(변이) |
| 확실성과 남은 가정 | 변이 결과로 확정이다 |
| 결정의 근거 | 적용 제외 — 검사 대상이 타입 변경을 따라가지 못한 단순 결함이다 |
| 이해 비용 | 적용 제외 |
| 최소 개선 방향 | 정규식을 `assertion\([^)]*,\s*"PASS"\s*\)`와 `Asserted:\s*"PASS"`로 바꾼다. 더 나은 방법은 PASS를 내는 항목마다 음성 입력 케이스를 두는 것이다(자산 누락 케이스처럼) |
| 대안 비교·보존 조건·재검토 | 적용 제외 |
| 비용·부작용 | 수 줄 |
| 완료 기준 | 위 변이가 테스트에서 실패한다 |
| 검증 방법 | 같은 변이를 다시 넣고 `node_modules/.bin/vitest run tests/unit/runbook-drill.test.ts` |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 11-09 규모 tier 실행 로그가 커밋돼 있어, merge 게이트를 로컬에서 돌리면 추적 파일이 바뀌고 커밋된 로그는 현재 tier와 다르다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 9, 20, 27 (+30.5) |
| 근거 | `git ls-files artifacts`: `artifacts/scale/{pr,main,nightly,release}` 35개, `artifacts/quality/extreme-scale-gates` 24개, `artifacts/phase5` 4개가 커밋돼 있다. `scripts/scale/run-scale-profile.ts:20-21`이 `artifacts/scale/<tier>/<step>.log`를 쓴다. `.gitignore:11-14`는 json·xml·txt만 무시한다. **실행:** `run-scale-profile.ts pr`(FE-GATE-005의 `check:scale:pr`) 한 번에 추적 로그 3개가 바뀌고 `composition-s0-s2.log`가 새로 생겼다. 커밋된 pr 로그는 이 단계를 넣기 전(지난 11-03 수정 전)의 것이다. **다운스트림:** 두 제품 모두 이 63개를 "아무도 읽지 않는 템플릿 기계의 기록"으로 지웠다(memento 기록 "What was deliberately not kept", tech-log 기록 66행) |
| 발생 조건 | 로컬에서 `check:scale:*`·`verify:extreme-scale` 실행, 템플릿 동기화 |
| 영향 | 게이트를 돌리면 git status가 더러워진다. 커밋된 로그가 현재 tier 구성·기계와 다른 증거처럼 보인다. 동기화할 때마다 다운스트림이 지워야 한다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M1 · E3 |
| 확실성과 남은 가정 | 이 로그를 읽는 코드가 없다는 것은 두 제품 기록의 확인 결과다. 이번에 따로 grep하지는 않았다 |
| 결정의 근거 | 적용 제외 — 산출물 관리의 단순 누락이다 |
| 이해 비용 | 적용 제외 |
| 최소 개선 방향 | 이 로그들을 지우고 `.gitignore`에 `artifacts/**/*.log`를 넣는다. 필요한 요약은 `docs/reviews/2026-09-23-extreme-scale-acceptance.md`에 있다 |
| 대안 비교·보존 조건·재검토 | 적용 제외 |
| 비용·부작용 | 파일 63개 삭제 |
| 완료 기준 | `git ls-files 'artifacts/**/*.log'`가 비어 있다. `check:scale:pr` 뒤 git status가 깨끗하다 |
| 검증 방법 | 위 명령 2개 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
## 6. FOLLOW-UP 재확인
### 6.1 지난 라운드(2026-09-25) 영역 11 발견
| 지난 ID | 내용 | 현재 | 근거 |
|---|---|---|---|
| 11-01 | drill 거짓 PASS | 해소 | `dist/assets/*.js` 삭제 → FE-RB-002·005 FAIL(재현). 대신 PASS 경로 부재(새 11-02), 죽은 가드(새 11-08) |
| 11-02 | axe·visual이 로딩 화면 검사 | 해소 | h1 대기(`accessibility.spec.ts:33-49`, `platform.visual.spec.ts:8-10`). 변이 5/5·5/5. 상태 화면 기준 이미지에 본문이 있다 |
| 11-03 | 규모 게이트 CPU 결합·CI 없음 | 해소 | pr tier가 FE-GATE-005에 있다. CPU 경합에서 10/10 |
| 11-04 | stub 기능 규모 증거 | 해소(범위 표기), 수치는 낡음 | 실제 모양 기능 측정과 검증·비검증 표. 현재 코드와 차이(새 11-05) |
| 11-05 | 기본 구성 구 탭 복구 미확인 | 해소 | `old-tab-chunk-recovery.spec.ts` chromium 통과. release 테스트 이름·주석을 fixture 계약으로 낮췄다(`old-asset-reachability.test.ts:5-12`) |
| 11-06 | 핵심 흐름 E2E가 약함 | 해소 | 스키마 변이가 spec 단언에서 실패. 저장 성공·429 재시도 E2E |
| 11-07 | lab 1회 측정·포트·시계 | 해소(완료 기준 충족), 판정은 여전히 뒤집힘 | 5회 중앙값·strictPort·페이지 시계. PASS 2 / FAIL 3(새 11-04) |
| 11-08 | `test.only`·quarantine 만료 | 해소 | 4개 설정 `forbidOnly`, 만료일 검사(`check-test-evidence.ts:302-304`). 주석 하나가 파일 전체 skip을 허용하는 점은 남았다(완료 기준 밖) |
### 6.2 `FOLLOW-UP.md` 중 이 영역 항목
| FOLLOW-UP 항목 | 결과 | 근거 |
|---|---|---|
| 5절 P2 `resumable-upload.spec.ts:7` 포트 하드코딩 | 유효 | 포트 4414로 돌리면 `requestfailed:POST:/uploads/create:net::ERR_FAILED`로 1건 실패(재현) |
| 5절 P3 SW 업데이트 spec의 route chunk 변경을 helper 옵션으로 | 유효 | 여전히 spec 안에서 not-found 페이지에 export를 덧붙인다(`service-worker-update.spec.ts:38-56`) |
| 5절 P3 fixture의 pnpm 설치 검사 끔(F-4) | 유효 | `scripts/lib/fixture-node-modules.ts:40-42` 그대로. 오늘 오케스트레이터가 worktree에서 pnpm이 공유 `node_modules`를 지우려 한 사례를 알렸다 |
| 5절 P3 00-03 남은 임시 폴더 | 판단 불가 | `/tmp`의 `repository-inventory-*`·`sw-assets-*` 324개가 모두 2026-09-29 생성이다(22개·5개씩 묶음). 두 테스트 모두 `afterEach`로 지운다. 어느 실행이 정리 없이 끝났는지 구분하지 못했다(영역 10). 이번 실험의 SW helper 누수는 11-07 |
| 3절 P3 `ci-artifact-contract.test.ts` 시간 초과 | 유효(형태가 바뀜) | 지금은 결정적 문자열 실패(11-01)와 부하 레이스(11-06)다. worktree 실행(loadavg 42)에서 30초 시간 초과도 1건 났다 |
| 4절 P2 06-08 `assets/` 하드코딩 | 유효(영역 06) | SW spec의 `hashedAssets`도 같은 가정이다(`service-worker-update.spec.ts:86-90`). 11-03에 포함 |
| 4절 P3 08-04 en-US 브라우저 검사가 목록·폼만 | 유효(영역 08) | `reference-form.spec.ts:55-81`은 목록과 폼만 본다 |
| 4절 P3 09-07 제거 검증이 e2e를 건너뜀 | 유효(영역 14) | 샘플 제거가 e2e 3개를 지우지만(`scripts/test-sample-removal.ts:52-54`) 제거 뒤 e2e는 돌지 않는다 |
| 1절 P1 초기 JS 예산 | 유효(영역 13) | 재측정: 기능 0개 초기 JS 203,481 B, 여유 1,319 B, reference 모양 기능당 약 3,245 B |
## 7. 미검증 목록
| 무엇 | 왜 확인하지 못했나 | 무엇이 있으면 확인할 수 있나 |
|---|---|---|
| Firefox·WebKit 실행 | 지시에 따라 chromium만 돌렸다 | 3엔진 `test:e2e`, `test:browser-capabilities` 1회 |
| e2e 전체, a11y 전체 태그, storybook spec | 필요한 spec만 돌렸다 | 조용한 호스트에서 `test:e2e`, `test:a11y`, `test:storybook` |
| CI 러너 결과(FE-GATE-008·013·026) | Gitea runner가 없다(U-1) | 같은 커밋의 CI 실행 기록 |
| lab 성능의 조용한 호스트 값 | 다른 에이전트 부하(16~22) | 부하 없는 기계에서 10회 |
| cgroup 테스트의 조용한 호스트 결과(11-06) | 같은 이유 | 부하 없는 기계에서 5회 |
| SW 전제 ②(해시 파일만 캐시)의 재현 | memento 기록과 코드 읽기로만 확인 | 사전 캐시에 `index.html`을 더한 사본에서 SW update spec 실행 |
| SW를 켠 구성의 `publicDir`(memento 후속 2) | 영역 06·13. 두 빌드 harness가 local 프로필로만 빌드해 `public/config.json`과 `dist/config.json`이 같을 수 있어 이 결함을 못 잡을 가능성이 있다(추론) | ACTIVE + 다른 배포 프로필로 두 빌드 후 `dist/config.json` 비교 |
| browser soak, main/nightly/release scale tier | 기준선 CPU(i5-10400F)와 긴 시간이 필요 | 기준선 기계에서 `check:scale:nightly` |
| 200개(한 context 가득)·400개 기능 측정 | 수 GB 메모리와 긴 시간 | 전용 기계에서 `measure-feature-shape-growth.ts --sizes=200` |
| provider 전환 실제 리허설 | repo 밖 | 스테이징 호스팅과 전환 절차 |
| git worktree에서 `test:system` 15건 실패의 처리 | bwrap `.git` 파일 문제로 확인했지만 영역 13 코드(`scripts/run-and-validate-provider.ts:271-276`)다 | 영역 13에서 판단 |
@@ -0,0 +1,351 @@
# 12 — 가드레일·CI 성숙도 리뷰
> 검토일: 2026-09-29 · 기준: `main` / `af3d8e6` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`, `docs/reviews/TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md`
> 영역 판정(35.8): **조건부 사용 가능** — 로컬 게이트의 직접 경계 검사와 CI 계약 검사는 변이를 모두 잡았다. 다만 머지 시점 강제는 템플릿과 두 제품 repo 어디에도 없다(U-1). 새 N+1 게이트와 i18n 게이트는 다운스트림에서 오탐을 내고 실제 위반은 놓친다. 제품이 쓰기 전에 12-01·12-02를 고치거나 예외 절차를 문서로 정해야 한다.
## 0. 머리말
### 0.1 결론
- **지난 라운드 12번 발견 12건은 회귀가 없다.** 고친 규칙마다 변이를 넣었고 모두 실패했다.
- 생성기가 첫 게이트만 그리게 되돌리면 `check:ci`가 `FE-GATE-027`을 잡는다(지난 12-02).
- 게이트 밖 테스트 파일과 검사 스크립트를 새로 넣으면 `check:ci`가 잡는다(지난 12-04).
- feature 루트 재수출, `import.meta.glob`, 서브배럴, design-system deep import가 모두 `check:architecture`에서 실패한다(지난 12-03, 12-06, 12-07, 12-08).
- **`check:request-fanout`은 요청 사이의 의존을 보지 않는다(12-01, Medium).**
- "transport 이름의 변수에 대한 호출이 반복 구문 안에 글자로 있는가"만 본다.
- 그래서 tech-log의 커서 페이지네이션(최대 50페이지)을 N+1로 거부했다. 제품 repo의 merge 게이트 FE-GATE-010·005가 빨간 채로 남았다.
- 반대로 helper로 뺀 행별 호출, 이름이 다른 receiver, `useQueries` 행별 조회는 통과한다. 12개 probe 중 정상 4개를 모두 거부했고, 실제 N+1 8개 중 7개를 통과시켰다.
- 빠져나갈 길은 문서에 없는 같은 줄 주석뿐이다. 실패 메시지는 이유도 탈출 경로도 알려 주지 않는다.
- **`check:i18n`의 "하드코딩 문구" 검사는 "파일 안에 한글 문자가 있는가"다(12-02, Medium).** 한글 주석 한 줄이면 실패하고, 영어 하드코딩 문구는 통과한다. 로케일 정책을 바꿀 설정이 없어서 tech-log는 스크립트를 고쳤고 memento는 게이트를 빨간 채로 두었다.
- **feature 안의 layer 폴더 밖 폴더(`contracts/`, 새 이름)는 규칙이 없다(12-03, Medium).** feature presentation이 자기 `contracts/`나 `hooks/`의 재수출로 `src/adapters/http`에 닿아도 그래프·lint·tsc가 모두 통과한다. 규칙 주석은 "feature 안에서는 `adapters/`만 `src/adapters`에 닿는다"고 적는다.
- **CI 계약 크기가 기준선 파일 밖에 테스트 상수로 한 번 더 있다(12-04, Medium).** 문서 절차대로 게이트를 바꾸면 `check:ci`는 통과하고 `test:unit`이 실패한다. 제거 게이트는 이 테스트를 지운 뒤에 통과를 증명한다.
- Low 3건: 실행하지 않는 `dependency-cruiser` 의존성(12-05), Vitest 폴더의 `*.spec.ts`를 "게이트 안"으로 세는 목록 검사(12-06), 예외 목록에 담당·재검토 시점이 없음(12-07).
- **머지 시점 강제는 여전히 없다.** 2026-09-29 Gitea API로 다시 확인했다. 템플릿, tech-log, memento 모두 `has_actions: false`이고 main HEAD 상태가 0개다. repo 쪽은 고쳤고 README가 이 사실을 밝힌다. 남은 것은 사용자 몫 U-1이다.
### 0.2 리뷰 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 | `clean-architecture-frontend-template`, 영역 12 |
| 커밋·작업 상태 | `main` / `af3d8e6`. 미커밋 변경은 리뷰 가이드 문서 2개뿐이다 |
| 목적과 실행 구성 | 템플릿. 브라우저 SPA + 정적 호스팅 + SW. CI는 Gitea Actions용 생성 workflow |
| 읽은 코드·설정 | `scripts/check-request-fanout.ts` 전체, `scripts/check-i18n.ts` 전체, `scripts/check-ci-contract.ts` 전체, `scripts/lib/ungated-tests.ts`·`ungated-scripts.ts` 전체, `scripts/update-ci-contract-baseline.ts`, `scripts/contracts/ci-gates.ts:440-545`, `scripts/generate-ci-workflow.ts:190-210`·`:367-385`, `scripts/check-architecture.ts` 앞부분·`:105-270`, `scripts/lib/architecture-violation-message.ts`, `.dependency-cruiser.json` 전 규칙, `eslint.config.ts:1-110`, `tsconfig*.json`, `config/ci/*.json` 전체, `.gitea/workflows/quality-gates.yml` 트리거·권한·action 고정, `package.json` 검사 스크립트, `vitest.config.ts` |
| 읽은 문서(주장) | `docs/operations/ci-quality-gates.md:1-145`, `README.md:286-340`, `docs/operations/api-contract-and-server-state-recovery.md:31`, `src/platform/traffic/request-fanout.ts`, `tests/features/reference-feature/reference-request-fanout.test.ts` |
| 제품 repo 증거 | `../tech-log-frontend`, `../memento-frontend`의 `chore/template-sync-v0.2.0`. 동기화 기록 `docs/operations/template-sync-2026-09-29.md`, `git show`·`git diff af3d8e6 <branch>`로 가드레일 파일 차이 확인. 두 repo 모두 읽기만 했다 |
| 실행한 명령 | `node scripts/check-request-fanout.ts`(74파일 PASS)·`--fixture`(PASS) · `node scripts/check-remediation-ledger.ts`(exit 1, 4건) · Gitea API 읽기 7회(아래 12-01 FOLLOW-UP 절) |
| 실험 | worktree(`scratchpad/review-2026-09-29/12/wt`, 끝나고 삭제)에서 경계 probe 9종, CI 계약 변이 4종, i18n probe 2종, scale·system 테스트 단독 실행. `findRequestFanout` 직접 호출 probe 12종(scratchpad 스크립트). worktree에서는 `corepack pnpm`을 부르지 않았다. 스크립트는 `node scripts/<file>.ts`로 돌렸고, `check-architecture.ts`가 부르는 `pnpm exec eslint`는 `node_modules/.bin/eslint`를 직접 실행하는 shim으로 대신했다. 예외: `ci-artifact-contract.test.ts`는 테스트 자신의 임시 fixture에서 `corepack pnpm build:release-candidate`를 부른다(설치 검사 끔, `scripts/lib/fixture-node-modules.ts`). 실행 뒤 메인 `node_modules`와 pnpm 상태 파일이 그대로인 것을 확인했다 |
| 확인하지 못한 범위 | 7절 |
## 1. 검사의 실제 효용 — 다운스트림 동기화에서 무엇이 걸렸나 (21절, 39.5)
두 제품 repo가 `af3d8e6`을 받을 때 가드레일이 실제로 무엇을 잡았는지 정리한다. 게이트 통과 여부가 아니라 "진짜 문제를 잡았는가"를 본다.
| 검사 | 제품 | 무엇을 잡았나 | 판정 |
|---|---|---|---|
| `check:adapter-inventory` | memento | 제품 파일 `src/adapters/http/offset-upload.ts`가 인벤토리에 없고 abort listener를 손으로 짝지었다 | 진짜 문제. 공용 abort primitive를 쓰지 않은 중복을 잡았다 |
| risk coverage(FE-GATE-005) | memento | `http-contract-bridge.ts`의 제품 추가분(`If-Match` 투영)에 테스트가 없었다 | 진짜 문제. 제품이 테스트 14개를 추가했다 |
| `check:ci`의 게이트 밖 스크립트 검사 | memento, tech-log | 제품 스크립트 4개·1개가 게이트에 없었다 | 진짜 누락. 이유를 적어 목록에 올렸다 |
| `check:request-fanout` | tech-log | 커서 페이지네이션(`collect-catalog.ts:30`) | **오탐**(12-01). FE-GATE-010·005가 빨간 채로 남았다 |
| `check:i18n` | memento / tech-log(이전 동기화) | 한국어 전용 제품의 한국어 문구 21파일 / 한글 주석 | 정책 불일치와 오탐(12-02). 한쪽은 빨간 채, 한쪽은 스크립트를 고쳤다 |
| `check:remediation-ledger` | tech-log | 템플릿의 옛 원장 문구 | 템플릿 쪽 기록 문제. 두 repo 모두 게이트 밖이라 머지에는 영향 없다 |
- 정리: 인벤토리·커버리지·게이트 목록 검사는 제품 코드에서 실제 결함을 찾았다.
- 반대로 이름·문자 기반 휴리스틱 두 개(fanout, i18n)는 올바른 코드를 막았다. 막힌 뒤 선택지가 "스크립트 수정" 또는 "게이트를 빨간 채로 두기"뿐이었다.
## 2. 대표 흐름 (체크리스트 2절)
### 2.1 정상 흐름 — 개발자가 로컬에서 FE-GATE-010을 돌린다
1. **입력:** `corepack pnpm ci:gate -- FE-GATE-010`(`package.json:119`).
2. **정책:** `scripts/run-ci-gate.ts`가 `config/ci/gates.json:1909-1934`의 명령 21개를 순서대로 돈다. 각 명령의 기대값(`pass`/`fail`)은 `scripts/lib/ci-step-result.ts`가 판정한다.
3. **상태 변화:** `check:architecture`가 생성 인덱스(`src/.generated/`)를 만들고 import 그래프를 그린다(376 모듈, 1,176 간선). 규칙은 `.dependency-cruiser.json`에서 읽는다.
4. **외부 I/O:** 없음. 파일 읽기와 `artifacts/quality/*` 쓰기뿐이다.
5. **실패:** 위반은 `Architecture violation [규칙]: a -> b (import "…")`와 규칙 `comment`(이유·가야 할 곳)로 나온다(`scripts/lib/architecture-violation-message.ts:6-17`).
6. **결과:** `artifacts/quality/gates/FE-GATE-010.txt` 로그와 증거 파일. 한 번 도는 데 `check:architecture`만 약 14초 걸렸다(worktree, 부하 있음).
### 2.2 피해가 큰 흐름 — 경계 우회가 머지까지 가는 경로
1. **입력:** feature presentation에서 `src/adapters/http`를 직접 import하면 그래프와 lint가 막는다.
2. **우회:** 같은 feature의 `contracts/`나 새 폴더(`hooks/`)에 `export * from "../../../adapters/http/index.ts"`를 두고 presentation이 그것을 import한다.
3. **정책:** `feature-presentation-does-not-know-outbound-adapters`(`.dependency-cruiser.json:118`)는 직접 간선만 본다. `contracts/`·`hooks/` → `src/adapters` 간선에는 규칙이 없다(12-03).
4. **검출:** `check:architecture` exit 0, ESLint exit 0, `tsc -p tsconfig.app.json` exit 0(실험 Q10·Q11).
5. **외부 I/O:** 머지를 막을 CI가 없다. `has_actions: false`, 상태 0개(U-1).
6. **결과:** 우회가 main에 들어가고, 다운스트림은 그 main을 복사한다.
### 2.3 변경 흐름 — 다운스트림이 게이트에 명령 하나를 추가한다
1. **입력:** `config/ci/gates.json`의 FE-GATE-010에 명령을 추가한다.
2. **정책:** `check:ci`가 기준선 불일치로 실패하고, 갱신 명령을 알려 준다(`scripts/contracts/ci-gates.ts:517-545`).
3. **상태 변화:** 문서 절차(`docs/operations/ci-quality-gates.md:19-27`)대로 `update:ci-contract-baseline` → `generate:ci-workflow` → `check:ci` PASS.
4. **실패:** 그런데 `test:unit`(FE-GATE-005)이 `tests/unit/ci-workflow-generation.test.ts:187-205`의 개수 단언에서 실패한다(실험 M5). 문서에는 이 단계가 없다(12-04).
5. **동기화:** 템플릿을 다시 받을 때 `gates.json`을 id별로 합치고, 기준선·테스트 개수를 다시 계산한다. tech-log는 기준선 `27/101/106/141/5`와 테스트 개수 119를 새로 계산했다. memento는 `gates.json`을 바꾸지 않아 비용이 없었다.
6. **결과:** 절차를 알면 한 번에 끝난다. 모르면 게이트를 바꿀 때마다 테스트 실패를 따로 찾아 고친다.
## 3. 28개 관점 판정표 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 굵은 번호가 이번에 깊게 본 관점이다.
| 번호 | 관점 | 판정 | 근거 |
|---|---|---|---|
| 1 | 코드 성숙도 | - | 이 영역에 도메인 규칙이 없다 |
| **2** | 구조적 성숙도 | P | 직접 간선 규칙은 M3로 동작한다. probe Q4a·Q5·Q6·Q7이 모두 실패했다(E3). feature 안의 layer 폴더 밖 폴더는 규칙이 없어 재수출 우회가 통과한다(12-03, `.dependency-cruiser.json:96-139`, `:290-300`). TS `paths`·Vite alias는 없다 |
| 3 | 변경 용이성 | P | 게이트 하나를 바꾸면 `gates.json`·기준선·workflow·테스트 개수 4곳이 움직인다(12-04). 기준선과 workflow는 명령으로 갱신된다 |
| 4 | 인지 부하 | P | CI 메타 층이 여전히 크다: `gates.json` 2,940줄, `ci-gates.ts` 1,287, `package-script-graph.ts` 1,025, `ci-artifact-validator.ts` 742, `generate-ci-workflow.ts` 530. workflow는 470줄이다. 지난 12-10의 삭제 방향은 반영됐고 새로 늘지는 않았다 |
| 5 | 위험 가시성 | P | 규칙 주석이 강제하지 않는 범위를 강제한다고 적는다(12-03). fanout·i18n 실패 메시지에 이유가 없다(12-01, 12-02) |
| 6 | 실패 성숙도 | - | 런타임 실패 처리가 없는 영역이다. 검사기의 fail-closed 동작은 21에서 본다 |
| 7 | 운영 성숙도 | > | 영역 13(릴리스·운영 게이트) |
| 8 | 디버깅 가능성 | P | 그래프 위반은 규칙 이유까지 출력한다(지난 12-11 해소, probe 출력 확인). fanout은 `FAIL 파일:줄 호출 inside 구문`만, i18n은 파일 이름만 출력한다(12-01, 12-02) |
| 9 | 유지보수 성숙도 | P | 실행하지 않는 `dependency-cruiser` 의존성(12-05), 같은 개수의 두 사본(12-04), 게이트 밖에서 빨간 원장 검사(FOLLOW-UP) |
| 10 | 테스트 성숙도 | P | 음성 fixture와 목록 검사가 변이를 잡았다(E3). Vitest 폴더의 `*.spec.ts`는 "게이트 안"으로 세지만 돌지 않는다(12-06). fanout fixture에 페이지네이션·helper 추출 사례가 없다(12-01) |
| 11 | 데이터 성숙도 | - | 이 영역에 저장 데이터가 없다 |
| 12 | 동시성 성숙도 | - | 해당 없음 |
| 13 | 확장성 | > | 영역 09·11(기능 수 축) |
| 14 | 성능 성숙도 | ? | CI 소요 시간을 잴 runner가 없다. 로컬 `check:architecture` 약 14초만 확인했다 |
| 15 | 보안 성숙도 | O | workflow 범위만 본다. `permissions: contents: read`(`quality-gates.yml:23-24`), action 33개 전부 40자 SHA 고정, `--frozen-lockfile --ignore-scripts`, `persist-credentials: false`, `pull_request_target` 없음(E1). 공급망 전체는 영역 13 |
| **16** | 의존성 성숙도 | P | lint·타입 도구가 exact pin이고 `minimumReleaseAgeExclude`에 이유·담당·재검토가 있다(`pnpm-workspace.yaml:9-13`). 실행하지 않는 `dependency-cruiser@18.1.0`과 직접 의존 18개가 남아 있다(12-05, `package.json:182`) |
| 17 | API / Contract | P | "모든 게이트 id가 run step에 있다"를 검사한다(`generate-ci-workflow.ts:367-385`, 변이 M1로 확인). 계약 크기가 두 곳에 있다(12-04) |
| 18 | 배포 성숙도 | > | 영역 13. 지난 12-02(FE-GATE-027 누락)는 변이로 회귀 없음을 확인했다 |
| 19 | 설정 성숙도 | P | 검사 정책(i18n 필수 로케일, 검사 폴더, 문자 판정)이 설정이 아니라 스크립트 코드에 있다(12-02) |
| 20 | 개발자 경험 | P | 그래프·lint 메시지는 해결 방향을 준다. fanout은 탈출 경로가 스크립트 머리 주석에만 있다(12-01). 게이트 변경 절차 문서가 테스트 갱신을 빠뜨린다(12-04) |
| **21** | Guardrail 성숙도 | X (머지 시점) / P (로컬) | **머지 시점:** 세 repo 모두 Actions가 꺼져 있고 상태가 0개다(2026-09-29 API, U-1). **로컬:** 직접 경계·CI 계약·게이트 목록 검사는 M3이고 변이 7종을 모두 잡았다(E3). 새 휴리스틱 게이트 둘은 오탐·미탐이 크고(12-01, 12-02), feature 폴더 우회가 열려 있다(12-03) |
| 22 | 추상화 성숙도 | P | CI 기준선 파일은 유지할 근거가 있다(4.2절). fanout·i18n은 정책보다 좁은 대리 규칙이다(4.1절) |
| 23 | 일관성 | P | 지난 12-11의 "규칙 이유 출력" 관례를 새 게이트 둘이 따르지 않는다. 예외 목록마다 메타데이터 모양이 다르다(12-07) |
| 24 | 네이밍 / 의미 | P | "hardcoded user-facing locale literal"이 실제로는 "한글 문자 포함"이다(12-02). 규칙 주석의 "only its adapters/ folder"가 사실과 다르다(12-03) |
| **25** | 조직 확장성 | P (구조만) | 팀이 하나라 실제 검증은 미확인이다. 다운스트림 기록: tech-log는 가드레일 파일 8개(+558줄), memento는 6개(+393줄)를 템플릿과 다르게 들고 있다(`git diff --stat af3d8e6 <branch>`). 제품 정책을 표현할 설정이 없어 템플릿 소유 스크립트를 고친다(12-02). `gates.json` 한 파일이 동기화 충돌 지점이다(4.2절) |
| **26** | Ownership | P | 경계 예외 주석과 `pnpm-workspace.yaml` 예외에는 담당·재검토 조건이 있다(지난 12-07 해소). `ungated-*.json` 항목과 fanout 주석에는 담당·재검토 시점이 없다(12-07). 게이트에 담당 필드가 없다(`gates.json` gate 키: id·name·commandIds·artifact·retention). 원장 검사는 빨간 채로 결정자가 없다(FOLLOW-UP) |
| 27 | 삭제 가능성 | P | 제거 게이트 4개가 CI 테스트를 지운 뒤에 통과를 증명한다(12-04). 샘플 제거 자체는 영역 14 |
| 28 | 회복 가능성 | - | 이 영역에 복구 경로가 없다 |
## 4. 설계 선택 설명 (41절)
### 4.1 N+1 소스 게이트를 글자 위치로 판정하는 선택
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | feature·application 코드가 컬렉션 행마다 요청을 보내지 않게 한다. 정책은 "N개 행을 읽는 비용은 한 페이지 또는 bulk 요청 수로 제한된다"이다(`src/platform/traffic/request-fanout.ts:1-5`). 쓰는 사람은 기능 작성자와 다운스트림이다 |
| 2. 지킬 성질 | 요청 수가 행 수에 비례하지 않는다. 페이지 단위 요청(최대 `ceil(N/100)+1`)은 허용된다. 템플릿 자신의 테스트가 커서 루프를 "never one per row"라고 정의한다(`tests/features/reference-feature/reference-request-fanout.test.ts:35-52`) |
| 3. 현재 보장 | 같은 파일 안에서 transport 이름(`http`, `client`, `gateway`, `api`, `*Gateway` 등)의 receiver 호출이 반복 구문이나 `map`·`forEach` 등의 콜백 안에 글자로 있으면 거부한다(`scripts/check-request-fanout.ts:23-42`, `:97-111`). 중첩 함수 선언은 반복 문맥을 지운다(`:102-104`). **보장하지 않는 것:** 반복 횟수가 행 수와 무관한지, 요청 사이에 의존이 있는지, helper·다른 이름·구조 분해를 거친 호출 |
| 4. 대안 | (a) 현 규칙 + 같은 줄 `fanout-reviewed:` 주석. (b) 데이터 흐름 규칙: 반복 요소가 요청 인자로 흘러가는지 본다. (c) 규칙은 두고, feature가 쓸 페이지네이션 경로를 제공한다: feature `adapters/`에서 `createCursorPaginationRuntime`(`src/adapters/query-cache/cursor-pagination-runtime.ts:49`)을 조립하게 안내한다. (d) 소스 게이트를 없애고 런타임 요청 예산과 테스트에만 맡긴다 |
| 5. 대안별 비용 | (a) 코드 비용 0. 정상 루프마다 사람이 주석을 달아야 하고, 주석 수를 세는 곳이 없다. (b) 정확도는 오르지만 자체 AST 데이터 흐름 분석기가 된다(21절 비용 기준 위배). 파일을 넘는 helper는 여전히 못 본다. (c) 커서 루프가 검사 밖(`src/adapters`)으로 가고 snapshot 변경·반복 cursor·상한·abort 검사를 함께 얻는다. 비용은 `CursorPage` 모양(`items`, `nextCursor`, `hasMore`, `snapshotToken`)으로 바꾸는 매핑과 문서 한 단락이다. 규칙상 feature `adapters/` → `src/adapters/query-cache/index.ts`는 허용된다(`.dependency-cruiser.json:140`은 최상위 `application` 등만 막는다. reference-feature adapters가 이미 `http` 배럴을 import한다). (d) 실행된 경로만 본다. 행별 요청이 테스트에 없으면 못 잡는다 |
| 6. 현재 조건에서의 선택 | **(a)는 유지하되 (c)의 안내를 붙인다.** 실패 메시지가 두 탈출 경로를 알려 주고, 허용 fixture로 "주석이 달린 커서 페이지네이션"을 고정한다. 억제된 호출 수를 출력한다. (b)는 비용 대비 효과가 작다. 리뷰어 추론이며 작성 당시 의도 기록은 없다 |
| 7. 재검토 조건 | 억제 주석이 여러 제품에서 반복되면 (b)나 "반복 요소가 인자에 쓰일 때만 거부"하는 좁은 규칙을 다시 비교한다. 실제 N+1이 게이트를 통과해 문제가 되면 (d)의 런타임 예산 연결을 먼저 본다 |
### 4.2 CI 계약 크기를 기준선 파일로 승인하는 선택
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 게이트·명령·산출물이 의도 없이 늘거나 줄지 않게 하고, 바뀌면 리뷰에서 보이게 한다(D-13, `scripts/contracts/ci-gates.ts:454-460`) |
| 2. 지킬 성질 | `gates.json` 모양이 바뀌면 `check:ci`가 실패한다. 갱신은 담당·이유와 함께 명령 하나로 끝난다 |
| 3. 현재 보장 | `assertCiContractBaseline`(`ci-gates.ts:517-545`)이 개수 5개와 게이트 모양 SHA-256을 비교한다. 불일치 메시지가 갱신 명령을 알려 준다. **보장하지 않는 것:** 테스트 상수(`tests/unit/ci-workflow-generation.test.ts:196-204`)가 같은 사실을 따로 고정한다(12-04) |
| 4. 대안 | (a) 기준선을 없애고 `gates.json` diff만 리뷰한다. (b) 현 상태(기준선 + 테스트 상수). (c) 기준선만 둔다. 테스트는 기준선 파일을 읽고, 테스트에만 있는 측정값 3개(job 수, `expect: fail` 명령 수, 증거 참조 수)는 기준선에 넣는다 |
| 5. 대안별 비용 | (a) 가장 단순하다. 동기화 때 파생값 충돌도 없다. 대신 2,940줄 JSON diff에서 게이트 삭제를 놓치기 쉽고, 제거 스크립트가 "무엇을 줄였는지"를 기록할 곳이 없다. (b) 한 사실이 세 곳에 있다. 이번 수정 라운드에서만 테스트 개수를 4개 커밋이 따로 고쳤다(`15a946f`, `fa3de53`, `710436b`, `7f889a6`). (c) 원본(`gates.json`)과 승인된 요약(기준선) 두 곳만 남는다. 39.5절 기준으로 기준선이 이미 "독립 선언과 실제 대조"를 한다 |
| 6. 현재 조건에서의 선택 | **기준선 파일은 유지한다. 테스트 사본만 걷어 낸다((c)).** 다운스트림 증거: memento는 `gates.json`을 바꾸지 않아 기준선이 템플릿과 같았고 비용이 없었다. tech-log는 합친 뒤 명령 하나로 다시 계산했고 기록에 "recomputed, not chosen"으로 남겼다. 비용은 감당할 만하다 |
| 7. 재검토 조건 | 제품이 `gates.json`을 템플릿과 따로 자주 바꿔 동기화마다 충돌이 반복되면(tech-log는 이미 +276줄), 제품 게이트를 별도 파일로 분리하는 안과 (a)를 다시 비교한다 |
### 4.3 경계 규칙을 폴더 이름별 직접 간선으로 적는 선택
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | presentation(공용·feature)이 concrete adapter(http 등)를 모르게 한다 |
| 2. 지킬 성질 | presentation이 import할 수 있는 모듈은 concrete adapter를 재수출하지 않는다 |
| 3. 현재 보장 | 간선 하나씩 규칙에 맞춘다(`scripts/check-architecture.ts:698`). 지난 12-03 수정은 중간 경유지(feature 루트 파일, `contexts`, `apps`)에서 `src/adapters`로 가는 간선을 막았다(`.dependency-cruiser.json:290-313`). feature 안은 `domain`·`application`·`presentation`(금지)과 `adapters`(허용)만 규칙이 있다. **보장하지 않는 것:** 그 밖의 폴더(`contracts/`, 새 이름)는 제약이 없다(12-03) |
| 4. 대안 | (a) 현 상태. (b) feature 안에서 `src/adapters`로 가는 간선은 `adapters/`에서만 허용하도록 규칙 하나를 허용 목록 방식으로 뒤집는다. (c) 도달 가능성 규칙: presentation에서 출발해 `src/adapters`에 닿는 경로를 금지한다 |
| 5. 대안별 비용 | (a) 우회가 CI를 통과한다. (b) 규칙 1개 교체와 fixture 1개. 새 폴더 이름도 자동으로 막힌다. 현재 템플릿 간선 1,176개 중 이 규칙에 걸리는 것은 0개다(`artifacts/quality/dependency-report.json` 계산). 두 제품 repo에서도 해당 import를 찾지 못했다(`git grep`). (c) 가장 정확하다. 그러나 지금은 설치 레지스트리(`src/features/installed-*`) 조립 경로로 presentation 다수가 합법적으로 adapter에 닿는다(지난 12-03 측정 45/55). 조립이 bootstrap으로 옮겨지기 전에는 예외 목록이 커진다 |
| 6. 현재 조건에서의 선택 | **(b).** 비용이 가장 작고, 주석이 이미 약속한 성질("feature 안에서는 `adapters/`만")을 코드로 만든다 |
| 7. 재검토 조건 | 설치 조립이 bootstrap으로 옮겨지면 (c)로 바꿔 폴더별 규칙 여러 개를 하나로 줄인다(`generic-presentation-does-not-compose-the-product`의 재검토 조건과 같은 시점) |
### 4.4 선언·실행·검증 반복 점검 (39.5)
| 대상 | 원본 | 실제 소비자 | 불일치 검출 | 판단 |
|---|---|---|---|---|
| CI 계약 크기 | `gates.json` | `check:ci`(기준선 비교), 단위 테스트(상수 비교) | 둘 다 검출 | 기준선이 독립 선언 역할을 한다. 테스트 상수는 중복 유지 비용이다(12-04) |
| 게이트 밖 테스트·스크립트 | `ungated-*.json` 항목 | `check:ci` | 게이트가 이제 돌리면 "stale"로 실패 | 독립 선언과 실제 게이트 그래프를 대조한다. 유지할 가치가 있다 |
| 규칙 주석의 범위 설명 | `.dependency-cruiser.json` `comment` | 사람, 위반 메시지 | 없음 | 주석이 규칙보다 넓게 약속한다(12-03) |
| ESLint `layerPatterns` | `eslint.config.ts:9-37` | 편집기·`lint` | 없음 | "편집기 보조, 기준은 그래프"라고 적혀 있다. 부분집합임을 밝혔으므로 유지 가능하다 |
## 5. 발견 사항 (36.3)
### 12-01 `check:request-fanout`이 요청 사이의 의존과 반복 횟수를 보지 않는다 — 제한된 커서 페이지네이션을 거부하고, helper를 거친 행별 요청은 통과시킨다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 21, 10, 5, 8, 20, 24, 26, 14 |
| 근거 | **규칙:** `scripts/check-request-fanout.ts:23`(receiver 이름 정규식), `:24-41`(반복 구문·메서드), `:97-111`(문맥 전파와 같은 줄 주석 판정). 반복 횟수나 인자의 출처는 보지 않는다. **실험(`findRequestFanout` 직접 호출, 12종):** 거부됨 — 커서 `for`(tech-log 모양), 커서 `do…while`, 3회 재시도 `for`, 고정 2개 배열의 `.map`. 통과됨 — `ids.map((id) => loadOne(gateway, id))`, `ids.map(one)`, `studio.getItem(id)`, 구조 분해 `get(id)`, 별칭 `g.get(id)`, `Array.from(ids, …)`, `useQueries`의 `queryFn: () => gateway.get(id)`. 거부된 실제 N+1은 `for await` 하나뿐이다. **다운스트림:** tech-log `src/features/tech-log/application/collect-catalog.ts:29-37`은 100건 페이지를 최대 50번, 앞 응답의 cursor로 이어 읽는다. 게이트가 `:30`을 거부했다. 동기화 기록은 `check:request-fanout`(FE-GATE-010)과 `tests/architecture/request-fanout.test.ts`(`test:coverage`, FE-GATE-005)가 빨간 채라고 적고 제품 소유자에게 결정을 넘겼다(tech-log 기록 "Open questions" 1). **탈출 경로:** 같은 줄 `// fanout-reviewed: <이유>`만 인정한다(`:109`). 위 줄에 달면 인정하지 않는다(실험). 이 관례는 스크립트 머리 주석(`:18-19`)에만 있고 `docs/`에는 없다. 실패 메시지는 `FAIL 파일:줄 호출 inside 구문`뿐이다(`:173-175`). 억제된 호출 수는 출력하지 않는다. **fixture:** 허용 fixture는 bulk 1회 조회 하나다(`tests/fixtures/architecture/request-fanout/allowed/bulk-read.ts`). 페이지네이션·재시도 허용 사례와 helper 추출 금지 사례가 없다. **페이지네이션 경로:** 템플릿의 `createCursorPaginationRuntime`은 검사 범위 밖(`src/adapters`)이지만 "runtime만 있다, 쓰는 operation이 없다"(`docs/operations/api-contract-and-server-state-recovery.md:31`). 게이트도 문서도 기능이 이것을 쓰도록 안내하지 않는다 |
| 발생 조건 | feature·application 코드에 제한된 반복 요청(커서 페이지네이션, 재시도, 고정 개수)을 쓸 때 → 오탐. 행별 요청을 helper·다른 이름·`useQueries`로 쓸 때 → 미탐 |
| 영향 | 오탐: 올바른 코드가 merge 게이트 2개를 빨갛게 만든다. 작성자는 스크립트를 읽어야 주석 관례를 안다. 미탐: `docs/reviews/2026-09-23-extreme-scale-acceptance.md` 9번이 "N+1 없음"의 근거로 이 게이트를 든다. 흔한 N+1 모양이 통과하므로 그 주장보다 보호 범위가 좁다 |
| 심각도·우선순위 | Medium · P2 — 데이터·보안 피해는 없다. 한 줄 주석으로 풀린다. 다만 실제 제품에서 merge 게이트를 막았고, 보호한다고 기록된 N+1 대부분을 놓친다 |
| 통제·증거 | 목표 M3 / 확인 M3(fixture 모양 3종만), 일반 N+1에는 M1 · E3(probe 12종) + 다운스트림 기록 |
| 확실성과 남은 가정 | 규칙 동작은 실행으로 확정했다. 두 제품 repo 코드에 helper를 거친 실제 N+1이 있는지는 찾지 않았다 |
| 결정의 근거 | 4.1절. 확인한 사실: 규칙 동작과 템플릿 자신의 "커서 루프는 N+1이 아니다" 테스트. 기록된 의도: 스크립트 머리 주석의 "reviewed exception". 추론: 주석 탈출구는 드문 예외를 가정했다 |
| 이해 비용 | 게이트에 걸린 기능 작성자가 `scripts/check-request-fanout.ts`를 열어 머리 주석을 읽어야 한다. tech-log 동기화 담당은 여기서 멈추고 결정을 넘겼다 |
| 최소 개선 방향 | (1) 실패 메시지에 이유와 두 탈출 경로(feature `adapters/`에서 `createCursorPaginationRuntime` 조립 / 같은 줄 `fanout-reviewed:`)를 적는다. (2) 허용 fixture에 "주석이 달린 커서 페이지네이션"을 추가한다. (3) 결과 줄에 억제된 호출 수와 위치를 출력한다. (4) 머리 주석과 `docs/operations/ci-quality-gates.md`에 미탐 범위(파일 내 글자 위치·이름 기반)를 적는다 |
| 대안 비교 | 4.1절 |
| 단순화의 보존 조건 | 금지 fixture 3종은 계속 거부된다. 억제에는 이유 문구가 계속 필요하다 |
| 비용·부작용 | 수십 줄과 fixture 1개. 규칙 자체는 바뀌지 않는다 |
| 재검토 조건 | 4.1절 7번 |
| 완료 기준 | tech-log 모양 코드를 넣으면 메시지만 보고 두 해결 방법을 안다. 허용 fixture에 주석 달린 커서 루프가 있다. 게이트 출력에 억제 수가 보인다 |
| 검증 방법 | `tests/architecture/request-fanout.test.ts`에 메시지·억제 수 단언과 페이지네이션 fixture를 추가한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 12-02 `check:i18n`의 "하드코딩 문구" 검사가 "파일에 한글 문자가 있는가"다 — 한글 주석은 실패, 영어 하드코딩은 통과하고, 제품이 정책을 바꿀 설정이 없다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 21, 24, 19, 25, 20, 8, 30.3 |
| 근거 | `scripts/check-i18n.ts:12` `koreanLiteral = /[가-힣]/`. `:95-98`은 파일 전체 텍스트에 이 정규식을 적용하고 "hardcoded common user-facing locale literal"로 보고한다. 주석과 문자열을 구분하지 않는다. **실험:** feature presentation에 `// 이 컴포넌트는 목록의 빈 상태를 그린다.` 한 줄만 있는 파일 → 실패. `<h1>Hard-coded English title</h1>` 파일 → 통과. 필수 로케일은 `ko-KR`·`en-US` 고정이다(`:32-52`). 검사 폴더는 코드 상수다(`:59-68`). **다운스트림:** tech-log는 이전 동기화에서 "주석과 문구를 구분하지 못한다"를 기록했고, 이번에 스크립트를 고쳐 자기 feature를 빼고 문자열·JSX 텍스트만 읽는 별도 정책(`scripts/lib/tech-log-i18n-policy.ts`)을 붙였다(`git diff af3d8e6 chore/template-sync-v0.2.0 -- scripts/check-i18n.ts`, +30줄). memento는 한국어 전용 제품이라 21파일이 걸렸고, 영어 문구가 없어 FE-GATE-010을 빨간 채로 두고 제품 소유자에게 넘겼다(memento 기록 "Introduced and escalated") |
| 발생 조건 | 한국어로 주석을 쓰는 제품. 한 언어만 지원하는 제품. 영어 문구를 하드코딩한 화면 |
| 영향 | 올바른 코드가 merge 게이트를 막는다. 제품은 템플릿 소유 스크립트를 고치고, 그 차이는 다음 동기화마다 충돌 지점이 된다. 영어 하드코딩은 검사 이름과 달리 잡히지 않는다 |
| 심각도·우선순위 | Medium · P2 — 두 제품 모두 비용을 치렀다. 데이터·보안 피해는 없다 |
| 통제·증거 | 목표 M3 / 확인 M2(한글 문구만) · E3(probe 2종) + 다운스트림 기록 |
| 확실성과 남은 가정 | 동작은 확정했다. 화면 문구의 번역 완성도 자체는 영역 08에서 본다 |
| 결정의 근거 | 확인한 사실: 템플릿 기본 로케일이 `ko-KR`이라 한글 검출은 "catalog를 거치지 않은 기본 로케일 문구"의 대리 지표로 동작한다. 기록된 의도: `:53-58` 주석 "Screen code … must take its words from the catalog". 추론: 템플릿 코드의 주석이 영어라 주석 오탐이 템플릿 안에서는 드러나지 않았다 |
| 이해 비용 | 제품 작성자가 실패 원인을 알려면 스크립트의 정규식을 읽어야 한다. 메시지에 줄 번호가 없다 |
| 최소 개선 방향 | (1) 파일 전체 대신 문자열 리터럴·템플릿 문자열·JSX 텍스트만 검사한다. Babel 파서가 이미 의존성에 있고(`@babel/core`), tech-log가 같은 방식을 구현했다. (2) 필수 로케일과 검사 대상 문자를 설정(예: `config/i18n` 또는 catalog 선언)에서 읽는다. (3) 메시지에 줄과 해결 방향(catalog 키)을 적는다 |
| 대안 비교 | 현 상태 유지: 코드 0줄, 두 제품이 계속 포크한다. 주석만 제거하는 전처리: 수 줄, 영어 미탐은 남는다. AST 리터럴 검사 + 로케일 설정: 수십 줄, 제품이 스크립트를 고치지 않아도 된다. 로케일 설정만 추가: memento는 풀리지만 tech-log 주석 문제는 남는다. 리터럴 검사와 설정을 함께 하는 것이 두 제품의 실제 문제를 모두 푼다 |
| 단순화의 보존 조건 | `tests/fixtures/i18n/forbidden` 음성 fixture가 계속 실패한다. `rawFailureRender`, `dangerouslySetInnerHTML` 검사는 그대로 둔다 |
| 비용·부작용 | 수십 줄. 영어 문구 검출을 켜면 템플릿 `examples` 밖의 영어 문구가 새로 걸릴 수 있다(개수 미확인) |
| 재검토 조건 | 템플릿이 세 번째 로케일을 기본으로 들이거나, 제품 두 곳 중 하나라도 로케일 정책을 템플릿과 다르게 확정할 때 |
| 완료 기준 | 한글 주석만 있는 파일은 통과하고, 영어·한글 하드코딩 문구는 줄 번호와 함께 실패한다. 한 언어 제품이 스크립트 수정 없이 설정으로 게이트를 통과한다 |
| 검증 방법 | i18n fixture에 주석 전용 파일(허용)과 영어 문구 파일(금지)을 추가한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 12-03 feature 안의 layer 폴더 밖 폴더는 경계 규칙이 없다 — feature presentation이 `contracts/`·`hooks/` 재수출로 `src/adapters/http`에 닿아도 모든 검사가 통과한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 2, 21, 5, 24, 10 |
| 근거 | feature 규칙은 `domain`(`.dependency-cruiser.json:96`), `application`(`:107`), `presentation`(`:118`), `adapters`(`:129`) 네 폴더만 출발지로 적는다. `feature-and-app-roots-do-not-reach-adapters`(`:290-300`)는 feature 루트 파일, `contexts`, `apps`만 막는다. 이 규칙의 주석은 "Inside a feature, only its adapters/ folder reaches src/adapters"라고 적는다. **실험(worktree):** Q10 — `src/features/reference-feature/contracts/probe-reexport.ts`가 `src/adapters/http/index.ts`를 재수출하고 같은 feature presentation이 이를 import → `check:architecture` exit 0, ESLint exit 0, `tsc -p tsconfig.app.json` exit 0. Q11 — 새 폴더 `hooks/`로 같은 구성 → 그래프·ESLint exit 0. Q1·Q3 — 공용 presentation·`src/application` → feature `adapters/` 재수출 → 그래프는 통과, ESLint는 경로 문자열에 `adapters`가 있어 막았다. 같은 구성을 `contracts/`로 바꾸면 ESLint도 통과했다 |
| 발생 조건 | lint가 presentation의 직접 import를 막을 때 개발자가 feature의 `contracts/`나 새 폴더에 재수출을 두는 경우 |
| 영향 | "presentation은 concrete adapter를 모른다"(`presentation-does-not-fetch-directly`, `:163`)가 CI 통과 상태로 깨진다. 템플릿 규칙이므로 다운스트림도 같은 틈을 갖는다 |
| 심각도·우선순위 | Medium · P2 — 지난 12-03과 같은 종류다. 데이터·보안 피해로 바로 이어지지는 않는다 |
| 통제·증거 | 목표 M3 / 확인 M3(네 폴더만), 그 밖 M0 · E3 |
| 확실성과 남은 가정 | 우회는 실행으로 확인했다. 현재 템플릿과 두 제품 repo에는 이런 간선이 없다(그래프 계산, `git grep`) |
| 결정의 근거 | 4.3절 |
| 이해 비용 | 규칙을 믿는 사람은 주석대로 막힌다고 생각한다. 실제 범위를 알려면 규칙 30개의 출발지 정규식을 모두 읽어야 한다 |
| 최소 개선 방향 | 규칙 하나를 허용 목록 방식으로 바꾼다: 출발지 `^src/features/[^/]+/(?!adapters/)` → 도착지 `^src/adapters/` 금지. 기존 루트 파일 규칙과 예외(`feature-adapter-contribution.ts`)는 그대로 둔다 |
| 대안 비교 | 4.3절 |
| 단순화의 보존 조건 | feature `adapters/` → adapter 배럴 간선은 계속 허용된다. 기존 28개 그래프 fixture가 통과한다 |
| 비용·부작용 | 정규식 1줄과 그래프 fixture 1개. 현재 위반 0건 |
| 재검토 조건 | 4.3절 7번 |
| 완료 기준 | Q10·Q11 probe가 `check:architecture`에서 실패한다. 규칙 주석과 동작이 같다 |
| 검증 방법 | `tests/fixtures/architecture/dependency-graph/`에 feature `contracts/` 재수출 fixture를 추가한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 12-04 CI 계약 크기가 기준선 파일과 테스트 상수 두 곳에 있고, 문서의 갱신 절차는 테스트 쪽을 빠뜨린다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 3, 9, 20, 27, 25, 17, 30.4 |
| 근거 | 기준선: `config/ci/contract-baseline.json`(명령 98, 참조 103, 산출물 109 등). 같은 값이 `tests/unit/ci-workflow-generation.test.ts:196-204`에 상수로 있다. 테스트에는 기준선에 없는 값 3개(job 9, `expect: fail` 명령 30, 증거 참조 87)도 있다. 운영 문서의 절차(`docs/operations/ci-quality-gates.md:19-27`)와 "새 프로젝트가 다시 찍을 기준선" 표(`:60-66`)에는 이 테스트가 없다. 내부 작업 문서에만 "테스트 개수 갱신" 단계가 있다(`tasks/handoff.md:74`, `tasks/lanes/LANE-BRIEF.md:77`). **실험 M5(worktree):** FE-GATE-010에 명령 1개 추가 → 문서 절차(기준선 갱신 → workflow 생성 → `check:ci`) → `check:ci` PASS → `tests/unit/ci-workflow-generation.test.ts` 1개 실패("preserves the reviewed baseline"). **제거 게이트:** 네 제거 스크립트가 fixture에서 이 테스트와 스냅샷을 지운 뒤에 검증한다(`scripts/test-sample-removal.ts:214-221`, `test-browser-file-storage-runtime-removal.ts:114-126`, `test-realtime-runtime-removal.ts:105-111`, `test-optional-recipe-removal.ts:33-34`). **이력:** 이번 수정 라운드에서 이 상수를 4개 커밋이 따로 고쳤다(`git blame -L 196,204`). **다운스트림:** tech-log가 기준선과 함께 이 테스트의 증거 참조 수(120/87 → 119)를 다시 계산했다 |
| 발생 조건 | 게이트·명령·산출물을 추가하거나 지울 때. 템플릿 동기화에서 양쪽이 `gates.json`을 바꿨을 때 |
| 영향 | 문서대로 하면 merge 게이트 FE-GATE-005가 실패한다. 제거 게이트는 실제 다운스트림이 겪을 단계를 건너뛰고 "제거 가능"을 증명한다. 지난 14-02가 없애려던 "템플릿 자신의 모양에 고정된 계약"이 테스트 쪽에 남았다 |
| 심각도·우선순위 | Medium · P2 — 실패 메시지(기대값 차이)는 분명하고 고치기 쉽다. 게이트를 바꿀 때마다 반복된다 |
| 통제·증거 | 해당 없음(중복 유지 비용) · E3(변이 M5) + 다운스트림 기록 |
| 확실성과 남은 가정 | 확정. 전체 workflow 스냅샷은 명령 추가만으로는 바뀌지 않았다. 게이트·job을 바꾸면 스냅샷도 갱신해야 한다(추론) |
| 결정의 근거 | 4.2절 |
| 이해 비용 | 게이트를 바꾸는 사람이 `check:ci` 통과 뒤 `test:unit` 실패를 따로 만나고, 테스트의 상수 7개를 손으로 맞춘다 |
| 최소 개선 방향 | 테스트가 기준선 파일을 읽어 비교하게 한다. 테스트에만 있는 측정값 3개는 `measureCiContractBaseline`에 넣어 기준선 한 곳에서 관리한다. 그러면 제거 스크립트가 이 테스트를 지우지 않아도 된다 |
| 대안 비교 | 4.2절 |
| 단순화의 보존 조건 | 게이트 id 목록 단언(`:191-195`)과 FE-GATE-015·020 모양 단언은 독립 기대값이므로 남긴다 |
| 비용·부작용 | 수십 줄. 기준선 파일에 필드 3개가 늘고, 다운스트림은 한 번 다시 찍는다 |
| 재검토 조건 | 4.2절 7번 |
| 완료 기준 | 문서 절차만 따라 게이트를 바꾸면 `check:ci`와 `test:unit`이 모두 통과한다. 제거 스크립트가 이 테스트를 지우지 않는다 |
| 검증 방법 | 실험 M5를 다시 돌린다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 12-05 실행하지 않는 `dependency-cruiser`가 의존성에 남아 있다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 16, 9, 27, 24 |
| 근거 | `package.json:182` `"dependency-cruiser": "18.1.0"`. 지난 12-05 수정(D-11) 뒤로 이 도구를 실행하거나 import하는 코드가 없다(`git grep`: `scripts/check-architecture.ts:115-117` 주석과 "depcruise를 쓰지 않는다" 단언 `tests/unit/architecture-report.test.ts:66`뿐). lockfile의 직접 의존은 18개다(acorn 계열 5, `enhanced-resolve`, `tsconfig-paths-webpack-plugin`, `prompts`, `is-installed-globally`, `watskeburt` 등). 의존성 기준선(`config/security/dependency-baseline.json:3558`)에 올라가 승인·SBOM 대상이 된다 |
| 발생 조건 | 항상. 설치할 때마다 |
| 영향 | 쓰지 않는 코드가 설치·공급망 검토 범위에 남는다. 규칙 파일 이름과 함께 "dependency-cruiser가 검사한다"는 오해를 계속 만든다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M0(사용하지 않는 의존성을 잡는 검사 없음) · E1 |
| 확실성과 남은 가정 | 사용하지 않음은 확정. 제거 시 lockfile에서 함께 빠지는 전이 패키지 수는 세지 않았다 |
| 결정의 근거 | 적용 제외 — 도구를 끄기로 이미 결정했고(D-11) 패키지 제거만 빠졌다 |
| 이해 비용 | 새 사람이 `.dependency-cruiser.json`과 이 의존성을 보고 depcruise 명령을 찾는다 |
| 최소 개선 방향 | `package.json`에서 빼고 lockfile·의존성 기준선을 갱신한다(`update:dependency-baseline`) |
| 대안 비교 | 적용 제외 — 선택지가 "빼기"뿐이다 |
| 단순화의 보존 조건 | `check:architecture`는 이 패키지를 쓰지 않으므로 영향이 없다 |
| 비용·부작용 | 기준선 재승인 1회(사용자 몫 F-11과 함께 처리 가능) |
| 재검토 조건 | 적용 제외 — 되돌릴 조건은 "dependency-cruiser가 TS 7을 지원해 다시 쓰기로 할 때"뿐이다 |
| 완료 기준 | `package.json`과 lockfile에 `dependency-cruiser`가 없다 |
| 검증 방법 | `git grep dependency-cruiser -- package.json pnpm-lock.yaml` 결과 없음, `check:architecture` 통과 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 12-06 게이트 밖 테스트 검사가 폴더 이름으로 판정해, Vitest 폴더의 `*.spec.ts`를 "게이트 안"으로 센다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 21, 10 |
| 근거 | `scripts/lib/ungated-tests.ts:18`은 `*.test.ts`와 `*.spec.ts`를 모두 테스트 파일로 센다. `:94-95`는 파일 경로가 게이트 경로(`tests/unit` 등)로 시작하면 "게이트 안"으로 본다. Vitest는 `tests/**/*.test.{ts,tsx}`만 실행한다(`vitest.config.ts:25`). **실험:** `tests/unit/probe-never-runs.spec.ts`(실패하는 단언) → `check-ci-contract.ts` PASS, `run-vitest.ts run <그 파일>` → "No test files found" |
| 발생 조건 | Playwright 습관으로 Vitest 폴더에 `.spec.ts`를 만들 때. 현재 템플릿·두 제품 repo에는 없다 |
| 영향 | 테스트가 아무 데서도 돌지 않는데 목록 검사는 통과한다. 지난 12-04가 막으려던 "조용히 게이트 밖" 상태의 한 경로다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M3(폴더 기준) · E3 |
| 확실성과 남은 가정 | 확정. Playwright `testIgnore`로 빠지는 파일도 같은 방식으로 "게이트 안"으로 셀 수 있다(추론, 미실험) |
| 결정의 근거 | 적용 제외 — 기존 검사의 판정 조건 누락이다 |
| 이해 비용 | 작다 |
| 최소 개선 방향 | Vitest 경로에 속한 파일은 `vitest.config.ts`의 `include` 패턴(`.test.`)도 맞아야 "게이트 안"으로 본다. 아니면 이유 없이 실패시킨다 |
| 대안 비교 | 적용 제외 — 판정 조건 한 줄 보강이다 |
| 단순화의 보존 조건 | 기존 stale 판정과 이유 필수 규칙을 유지한다 |
| 비용·부작용 | 수 줄과 단위 테스트 1개 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 위 probe에서 `check:ci`가 실패한다 |
| 검증 방법 | `tests/unit/ungated-tests.test.ts`(또는 해당 단위 테스트)에 `.spec.ts` 사례를 추가한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 12-07 게이트 예외 목록에 이유는 있지만 담당과 재검토 시점이 없다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 26, 21, 23 |
| 근거 | `config/ci/ungated-tests.json`(6개)과 `ungated-scripts.json`(17개)의 스키마는 `path`/`script`와 `reason`뿐이다(`scripts/lib/ungated-tests.ts:20-32`, `ungated-scripts.ts:125-137`). `reason`은 공백이 아닌 1자 이상이면 된다. 재검토 장치는 "게이트가 이제 돌리면 stale로 실패"(`ungated-tests.ts:102-106`) 하나다. fanout 억제 주석은 이유 문구만 요구하고 목록이 없다(12-01). 반면 `contract-baseline.json`에는 `owner`가 있고, 경계 규칙 주석과 `pnpm-workspace.yaml` 예외에는 담당·재검토 조건이 있다. **실제 예:** `check:remediation-ledger`는 이유("history record … wiring it into a gate first needs …")만 있고, 리뷰 전부터 빨간 상태가 결정자 없이 이어진다. 게이트 밖 scale 테스트 6개의 마지막 기록은 2026-09-24다(`artifacts/scale/main/`). 이번에 6개를 한 번에 돌리자 23개 중 22개가 통과했다. 실패 1건(`telemetry-storm`)은 부하 평균 약 33에서 난 시간 초과였고, 단독 재실행에서 통과했다 |
| 발생 조건 | 예외가 쌓이거나, 예외의 전제(기준 CPU, 원장)가 바뀔 때 |
| 영향 | 누가 언제 다시 볼지 정해지지 않아 예외가 영구화된다. 다운스트림은 자기 예외와 템플릿 예외를 구분하기 어렵다 |
| 심각도·우선순위 | Low · P3 — 이유 문구는 구체적이고 대체 명령까지 적혀 있다. 1인 관리 템플릿이라 담당 필드의 효과는 제한적이다(26절 적용 범위) |
| 통제·증거 | M2(이유 필수, stale 검출) · E1 |
| 확실성과 남은 가정 | 확정 |
| 결정의 근거 | 현 형식의 근거: 이유 필수 + stale 자동 검출로 "게이트에 들어오면 목록에서 빠진다"는 가장 흔한 재검토를 자동화했다. 빠진 것은 "게이트에 못 들어온 채 오래된 것"이다 |
| 이해 비용 | 작다 |
| 최소 개선 방향 | 두 목록 스키마에 선택 필드 `owner`와 `revisit`(조건 문구 또는 날짜)을 추가한다. 템플릿 항목에는 `frontend-platform`을 적는다. 강제 만료 검사는 만들지 않는다 |
| 대안 비교 | 현 상태 유지: 비용 0, 원장 사례처럼 결정자가 없다. 선택 필드 추가: 수 줄, 다운스트림이 자기 항목을 구분한다. 만료 날짜 강제: 날짜가 지나면 게이트가 무작위로 빨개지는 비용이 크다. 선택 필드가 비용 대비 낫다 |
| 단순화의 보존 조건 | `reason` 필수와 stale 검출은 유지한다 |
| 비용·부작용 | 스키마 2줄, 항목 23개에 한 번 값 채우기 |
| 재검토 조건 | 템플릿 담당이 둘 이상이 되거나, 다운스트림 항목이 템플릿 항목보다 많아질 때 |
| 완료 기준 | 모든 항목에 담당이 있고, 재검토 조건이 이유 문구와 분리돼 있다 |
| 검증 방법 | 스키마 단위 테스트 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
## 6. FOLLOW-UP 재확인
| 출처 | 항목 | 결과 | 현재 근거 |
|---|---|---|---|
| FOLLOW-UP 1절 P2 | `check:remediation-ledger` 실패 | **유효 — 결정 필요** | `node scripts/check-remediation-ledger.ts` exit 1, 4건(TR-02·TR-03·TR-04 마커 없음, file-transfer 예산 55,700 문구 없음). `config/ci/ungated-scripts.json:17`에 이유와 함께 있다. tech-log도 같은 4건으로 빨갛고 "템플릿의 결정"으로 넘겼다. 필요한 결정: 원장을 현재 코드에 맞출지, 역사 기록으로 보고 검사·스크립트·목록 항목을 지울지. 목록의 이유 문구("history record run by hand, not a current contract")는 삭제 쪽을 가리킨다. 새 발견으로 세지 않는다 |
| FOLLOW-UP 4절 P3 | 12-12 `noUnusedParameters` 미적용 | 유효 | `tsconfig.base.json`에 `noUnusedLocals`만 있다 |
| FOLLOW-UP 4절 P3 | 07-07 `no-deprecated` lint 미적용 | 유효 | `eslint.config.ts`에 해당 규칙이 없다 |
| FOLLOW-UP 3절 P3 | `tests/system/ci-runner/ci-artifact-contract.test.ts` 시간 초과 | 유효 — 기록 정정 필요 | FOLLOW-UP은 "공통 게이트 밖"이라 적었지만 `test:system`은 merge 게이트 FE-GATE-013의 명령이다(`gates.json` FE-GATE-013, `package.json:52`). 이번에 부하 평균 약 30에서 한 번 돌렸을 때 10초 제한 테스트 8개가 시간 초과했다. 조용한 환경 재실행은 하지 않았다. 테스트 자체는 영역 11 |
| FOLLOW-UP 6절 | U-1 Actions·runner·required check | 유효 | Gitea API(2026-09-29): 템플릿 `has_actions: false`, `default_branch: main`. `af3d8e6`·`f753669`·`f1002fd`의 `/status`가 모두 `total_count: 0`. tech-log·memento도 `has_actions: false`, main HEAD 상태 0개. `/branch_protections` 401, `/actions/tasks` 403(토큰 필요). workflow push 트리거는 `[main, develop]`이다(`.gitea/workflows/quality-gates.yml:4-7`). 원격 `develop`은 `ebea300`에 멈춰 있다. README가 "상태 없음은 통과가 아니다, 머지 전 로컬 13개 게이트"를 밝힌다(`README.md:296-305`) |
| FOLLOW-UP 6절 | U-3 태그 `v0.2.0` push | 해소 | 원격에 `refs/tags/v0.2.0` → `f753669`가 있다. 영역 밖이라 참고로만 적는다 |
| FOLLOW-UP 4절 P2 | 13-03 production 단계가 runner에서 돈 적 없음 | 유효 | U-1과 같은 원인. 영역 13 |
| 지난 12-01~12-12 | 회귀 확인 | 회귀 없음 | 변이 M1(12-02), M2·M3(12-04), probe Q4a(12-03), Q5(12-06), Q6(12-07), Q7(12-08) 모두 실패. `config/architecture/layers.json` 삭제 확인(12-09, `3e1c421`). 그래프 위반 메시지에 규칙 이유 출력(12-11). `noUnusedLocals` 적용(12-12). 12-03·12-05의 잔여는 새 발견 12-03·12-05로 적었다 |
## 7. 미검증 목록
- **branch protection·Actions 실행 이력.** API가 401·403을 준다. 저장소 관리자 토큰으로 `/branch_protections`, `/actions/tasks`를 읽으면 확인할 수 있다.
- **생성된 workflow가 실제 Gitea runner에서 도는지, CI 소요 시간.** 세 repo 모두 Actions가 꺼져 있다. runner 1대와 PR 1건의 실행 기록이 필요하다.
- **fanout 미탐이 제품 코드에 실제로 있는지.** 두 제품 repo에서 helper·`useQueries`를 거친 행별 요청을 찾지 않았다. `src/features/**`에서 `Promise.all(… .map(` 호출을 따라가면 확인할 수 있다.
- **12-02 개선 뒤 영어 하드코딩이 템플릿에 몇 건 걸리는지.** 리터럴 검사를 켠 변이 실행이 필요하다.
- **`tests/system` 전체와 `ci-artifact-contract.test.ts`의 조용한 환경 결과.** 동시에 13개 에이전트가 돌아 부하가 높았다. 부하 없는 단독 실행이 필요하다(영역 11).
- **12-05 제거 시 빠지는 전이 패키지 수.** `pnpm remove` 결과 lockfile diff가 필요하다(이 리뷰는 설치 명령을 쓰지 않는다).
- **제거 게이트(`test:*-removal`)에서 12-04 개선안이 통과하는지.** 제거 스크립트는 fixture에서 `pnpm`을 부른다. worktree의 `node_modules`가 메인 링크라 돌리지 않았다.
- **전체 `lint`·`check:types`.** 오케스트레이터 결과(모두 PASS)를 따랐다. 이 영역에서는 probe 파일에 대해서만 ESLint·`tsc -p tsconfig.app.json`을 돌렸다.
@@ -0,0 +1,413 @@
# 13. 빌드·릴리스·설정·공급망 성숙도 리뷰
> 검토일: 2026-09-29 · 기준: `main` / `af3d8e6`(태그 `v0.2.0` + docs 커밋 1개) · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 영역 판정(35.8): **조건부 사용 가능.** 기본 구성(SW `null`, 루트 경로, 셸 환경변수로 빌드 변수 전달)의 빌드·설정·승인 흐름은 그대로 써도 된다. SW `ACTIVE`로 staging·production 릴리스를 하려면 13-01을 먼저 고친다. `.env*` 파일로 빌드 변수를 바꾸는 사용은 13-02를 고치기 전까지 피한다.
## 1. 머리말
| 항목 | 기록 |
|---|---|
| 영역 | 13 — 빌드·릴리스·설정·공급망 |
| 경로 | `scripts/build-frontend.ts`, `scripts/generate-runtime-config.ts`, `scripts/generate-build-manifest.ts`, `scripts/check-release-admission.ts`, `scripts/generate-supply-chain.ts`, `scripts/verify-exact-promotion-bundle.ts`, `scripts/verify-hosting-headers.ts`, `scripts/check-bundle.ts`, `scripts/check-browser-security.ts`, `scripts/lib/{supply-chain,classify-vite-bundle,hosting-probe,dist-permissions,secret-scan}.ts`, `vite.config.ts`, `vite.service-worker.config.ts`(빌드 두 번째 단계만), `config/{release,hosting,runtime,security,performance}`, `package.json`, `pnpm-lock.yaml`, `pnpm-workspace.yaml`, `.npmrc`, `.env.example`, `.gitea/workflows/quality-gates.yml`의 immutable_build·promotion·production_gate job |
| 기준 커밋·상태 | `af3d8e6`. 워킹트리 미커밋은 리뷰 가이드 문서 2개뿐이다. 모든 실험은 분리 worktree(`scratchpad/review-2026-09-29/13/wt`, `af3d8e6`)에서 했고 끝난 뒤 지웠다. |
| 전제 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + SW. SSR 없음. 운영 규모 목표 없음. 초기 JS 예산(`config/performance/budgets.json`)만 수치 목표가 있다. |
| 읽은 범위 | 위 경로 전체. 주장 자료로 `README.md:25-66`, `README.md:315-353`, `CHANGELOG.md` 0.2.0, `docs/security/browser-boundary.md`, `docs/architecture/optional-adapter-recipes.md` 9단계, `docs/operations/release-cache-rollback.md`. 지난 리뷰 `2026-09-25-maturity-review/13-*.md`, `README.md` 11절, `FOLLOW-UP.md`. 제품 기록 2개(`tech-log-frontend`, `memento-frontend`의 `chore/template-sync-v0.2.0:docs/operations/template-sync-2026-09-29.md`)와 두 제품의 `vite.config.ts`, `vite.service-worker.config.ts`, `config/hosting/security-headers.json`, `tests/unit/build-environment-bundle.test.ts`를 `git show`로 읽었다. |
| 실행한 테스트 | worktree에서 `node scripts/run-vitest.ts run tests/unit/{archived-promotion,build-environment-bundle,build-environment,bundle-classification,deployment-admission,dist-permissions,hosting-probe,promotion-readiness,release-artifacts,sub-path-deployment,supply-chain,vite-module-inventory}.test.ts tests/release tests/platform/release tests/runtime-schema/runtime-config.test.ts` → **19 files, 200 tests 통과** |
| 실험(모두 worktree) | ① `VITE_BUILD_ID`만 바꿔 두 번 빌드한 뒤 청크 이름 비교 ② `manualChunks`에 route 청크 이름을 붙이는 변이 → 번들 테스트·build manifest ③ route 페이지가 build id를 읽는 변이 → 번들 테스트 ④ SW `ACTIVE` + `APP_PROFILE=production` 빌드 → `dist/config.json`, admission, `verify-release` ⑤ SW `ACTIVE` + `VITE_ROUTER_BASE_PATH=/app/` 빌드 ⑥ `.env.production.local`에만 `VITE_ROUTER_BASE_PATH`·`VITE_BUILD_ID`를 둔 빌드 → `verify-release` ⑦ `build:app-only` 경로를 `APP_PROFILE=production`으로 실행 ⑧ `security-headers.json`에 CDN을 더한 뒤 `verify-hosting-headers` ⑨ `check-bundle.ts`, `check-optional-recipes.ts --require-dist` ⑩ `APP_PROFILE`·`RELEASE_TARGET` 불일치 admission ⑪ `VITE_BUILD_ID` 없는 staging·production 설정 생성 ⑫ `no-whole-import-meta-env` lint 변이(4가지 형태) ⑬ `build.rolldownOptions`를 추가하는 변이 ⑭ scratch 폴더에서 pnpm 11 `engineStrict` 강제 여부 ⑮ `pnpm list --json --depth Infinity`로 production 폐포와 SBOM scope 비교 |
| 확인하지 못한 범위 | 7절. 요약: 실제 호스팅·CDN, Gitea workflow 실행(U-1), 외부 provider, Playwright(`production-csp.spec.ts` 포함)는 이번에 돌리지 않았다. 다른 영역 에이전트가 같은 포트(4173)를 쓸 수 있어서다. |
### 1.1 CHANGELOG 0.2.0 [보안]·[계약] 재확인
| 항목 | 결과 | 근거 |
|---|---|---|
| `VITE_*`는 키로만 읽는다(13-06) | 확인 | `src/contracts/env.ts:131-137`. 선언 안 된 `VITE_PAYMENT_KEY`는 빌드를 멈춘다(`vite.config.ts:13-24`, 번들 테스트 2번째 케이스 통과). lint 변이 ⑫에서 전체 참조·캐스팅·computed·구조분해 4건을 모두 잡았다(`eslint.config.ts:900-944`). |
| 설정·매니페스트 URL이 `VITE_ROUTER_BASE_PATH`를 따른다(13-07) | 부분 | 앱 번들과 `dist/config.json`은 따른다(`src/contracts/env.ts:143-144`, `scripts/generate-runtime-config.ts:57-67`, `tests/unit/sub-path-deployment.test.ts`). SW 빌드와 호스팅 probe는 따르지 않는다(13-06). 값을 `.env*` 파일로 주면 base가 번들에만 들어간다(13-02). SW `ACTIVE`면 rebasing이 덮어써진다(13-01). |
| staging·production은 `VITE_BUILD_ID` 필수(13-15) | 확인 | 실험 ⑪: `config/runtime/staging.json: a staging build requires VITE_BUILD_ID`, 빈 값도 거절(`scripts/generate-runtime-config.ts:70-72`). README 변수 표에는 이 조건이 없다(13-09). |
| `RELEASE_TARGET`≠`APP_PROFILE`이면 승인 거절(12-02, 13-01) | 확인 | 실험 ⑩: exit 1(`scripts/check-release-admission.ts:45-55`). workflow의 immutable_build가 FE-GATE-027을 실행한다(`.gitea/workflows/quality-gates.yml:128-144`). |
| `engineStrict`·`saveExact`를 `pnpm-workspace.yaml`로(13-09) | 확인 | 실험 ⑭: `engines.node "<1.0.0"`에서 install exit 1. `pnpm config get engine-strict` → `true`. 회귀를 막는 검사는 없다(13-08). |
## 2. 대표 흐름
### 2.1 정상 흐름 — production 빌드와 승인
```
APP_PROFILE=production VITE_BUILD_ID=… RELEASE_ID=… RUNTIME_API_BASE_URL=… pnpm build
→ generate-product-feature-index
→ build-frontend.ts
1 dist 정리 → 2 contract set
→ 3 vite build (vite.config.ts: 선언 안 된 VITE_* 거절, base = process.env.VITE_ROUTER_BASE_PATH,
public/ 전체를 dist/로 복사 → dist/config.json = 로컬 프로필)
→ 4 generate-runtime-config (config/runtime/production.json → dist/config.json 덮어쓰기,
RUNTIME_* 두 값만 대체, manifest URL을 base로 rebase, VITE_BUILD_ID 필수)
→ 5·6 SW (기본 null이면 건너뜀)
→ 7 generate-build-manifest (dist/config.json을 읽고 BUILD_ID·RELEASE_ID를 넣어 다시 씀, release manifest)
→ 8 makeDistFilesPublic (0600 → 읽기 허용)
→ APP_PROFILE=production RELEASE_TARGET=production pnpm check:release-admission
(프로필≠대상 거절 → APP_ENV·AUTH_MODE·https·loopback/사설 호스트 규칙 → artifacts/release/deployment-admission.json)
```
- 입력: 셸 환경변수, `config/runtime/<profile>.json`.
- 정책: 런타임 스키마 한 벌(`runtimeConfigV2ArtifactSchema`), 공개 대상 규칙(`src/contracts/deployment-admission.ts:34-37`, `:75-`).
- 상태 변화: `dist/` 전체, `artifacts/release/deployment-admission.json`.
- 실패: 각 단계가 0이 아닌 코드면 즉시 중단(`scripts/build-frontend.ts:43-52`). admission은 fail-closed.
- 결과: 로컬에서 실험 ⑩·⑪로 확인했다. 이 흐름의 정확성은 **"4단계가 3단계의 public 복사를 덮어쓰고, 그 뒤에는 아무도 dist/config.json을 다시 덮어쓰지 않는다"는 단계 순서**에 기대고 있다. 끝에서 이 사실을 확인하는 검사는 없다(13-01).
### 2.2 피해가 큰 흐름 — SW `ACTIVE`로 운영 릴리스
```
installed-runtime-capabilities.ts: SERVICE_WORKER = { mode: "ACTIVE", … }
APP_PROFILE=production … pnpm build
→ 3 vite build → 4 generate-runtime-config (production 프로필)
→ 5 generate-service-worker-assets
→ 6 vite build --config vite.service-worker.config.ts
설정 로드 시 dist/config.json(production)을 읽어 SW에 manifest URL을 넣는다(:53-55)
emptyOutDir:false, publicDir 기본값 → public/config.json을 dist/로 다시 복사 ← 여기서 로컬 프로필로 돌아간다
→ 7 generate-build-manifest: 로컬 프로필에 BUILD_ID=rel-prod-1만 덮어씀
→ exit 0, verify-release PASS
→ check:release-admission (RELEASE_TARGET=production)
refused: APP_ENV local, AUTH_MODE demo, http:, localhost
```
- 외부 I/O: 없음(로컬 빌드).
- 결과: 실험 ④에서 그대로 재현했다. CI(FE-GATE-027)를 거치면 릴리스가 막힌다. admission을 거치지 않는 배포라면 demo 인증 + `http://localhost:8080/` 설정이 운영에 나간다. 제품 memento는 같은 결함을 `publicDir: false`로 막았다(제품 기록 204행, 345행).
### 2.3 변경 흐름 — 다운스트림이 청크 설정을 바꾼다
```
vite.config.ts manualChunks에 route 청크 이름 추가 (tech-log 방식)
→ rolldown 청크 경계·이름이 바뀐다
→ generate-build-manifest: entry.name === route moduleId 로 route 청크를 찾는다
이름이 "route-home-page"가 되면 "Missing built route chunk: APP_HOME" (실험 ②, build exit 1)
→ tests/unit/build-environment-bundle.test.ts: "design-system-*" 청크가 정확히 1개라고 가정
이름이 사라지면 "expected [] to have a length of 1" (실험 ②)
route 페이지가 build id를 읽어 route 청크가 매 빌드 바뀌어도 통과 (실험 ③)
```
- 결과: 청크 이름이 계약처럼 쓰이지만 어디에도 선언돼 있지 않다(13-03). tech-log는 이 테스트를 자기 청크 이름(`render-boot-failure-*`)으로 바꿨고 여전히 실패 중이다(제품 기록 470행).
## 3. 28개 관점 판정표
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. **굵은 번호**는 이번 영역의 깊게 볼 관점이다.
| 번호 | 관점 | 판정 | 이유·근거 |
|---|---|---|---|
| 1 | 코드 성숙도 | > | `src/` 규칙은 각 영역 |
| 2 | 구조적 성숙도 | > | 영역 12 |
| 3 | 변경 용이성 | P | 프로필 추가는 `config/runtime/<name>.json`과 `DEPLOYMENT_TARGETS`면 된다. 청크 설정(13-03)과 CSP(13-04)를 바꾸면 선언되지 않은 곳이 함께 깨진다. |
| 4 | 인지 부하 | P | 빌드 8단계가 한 주석에 정리돼 있다(`scripts/build-frontend.ts:10-38`). 두 번째 Vite 단계가 `public/`을 다시 복사한다는 사실은 어디에도 없다(13-01). |
| 5 | 위험 가시성 | P | hosting fixture 모드가 이제 `UNVERIFIED`(exit 3)로 드러난다(`scripts/verify-hosting-headers.ts:231-236`). SW 빌드가 설정을 되돌린 경우 admission 오류는 "artifact declares local"만 말하고 원인을 가리키지 않는다(13-01). |
| 6 | 실패 성숙도 | O | 이 범위(빌드 단계 실패 처리)에서 각 단계 비정상 종료 시 즉시 중단(`scripts/build-frontend.ts:43-52`), 프로필 `APP_ENV` 불일치 throw(`scripts/generate-runtime-config.ts:48-52`). |
| 7 | 운영 성숙도 | > | telemetry는 영역 03 |
| 8 | 디버깅 가능성 | P | build id·release id가 config·manifest·admission 기록에 남는다. "Missing built route chunk" 메시지는 원인(청크 이름 = moduleId 규약)을 말하지 않는다(13-03). |
| 9 | 유지보수 성숙도 | P | CSP 문자열이 4벌이다(13-04). 청크 설정이 폐기 예정 키에 있다(13-07). |
| 10 | 테스트 성숙도 | P | 대상 테스트 200개 통과(E2). 빌드 테스트가 local 프로필·SW null·루트 base·셸 변수만 본다(13-01, 13-02, 13-06). 해시 안정성 테스트가 청크 이름에 묶여 있다(13-03). |
| 11 | 데이터 성숙도 | > | 브라우저 저장소 영역 |
| 12 | 동시성 성숙도 | > | 탭·저장소 영역 |
| 13 | 확장성 | > | extreme-scale(영역 11) |
| 14 | 성능 성숙도 | P | 실험 ⑨: 초기 JS **203,481 / 204,800** gzip bytes, 여유 1,319 B. `config/scale/feature-shape-growth.json`에서 기능 모양 1개 ≈ +2,980 B(25개 추가 시 200,001 → 274,493). 실험 ①: build id만 바꿔도 초기 JS 중 index·boot·render-boot-failure 3개 청크(약 96 KB gzip, react-dom 포함)가 매 빌드 바뀐다. |
| **15** | 보안 성숙도 | P | `VITE_*` 선언 강제(E3, `vite.config.ts:13-24`)와 lint(E3)는 충족. 운영 CSP를 넓히는 경로에 안내·내용 검사가 없다(13-04, E3). `connect-src 'self' https:`는 문서화된 한계(`docs/security/browser-boundary.md:21-25`). secret scan 규칙은 여전히 4개(`scripts/lib/secret-scan.ts:20-31`)지만 13-06 수정으로 번들 유입 경로 자체가 막혀 위험이 줄었다. |
| **16** | 의존성 성숙도 | P | lockfile 561행 모두 sha512, tarball·git 0개. `engineStrict` 동작 확인(실험 ⑭). SBOM이 `scheduler@0.27.0`을 development로 적는다(13-05, E3). 청크 설정이 폐기 별칭에 있다(13-07). 설치 정책 회귀 검사 없음(13-08). `build-frontend.ts:62`, `:71`은 여전히 `npx vite`를 쓴다. |
| 17 | API / Contract 성숙도 | > | 설정 스키마 호환은 영역 07 |
| **18** | 배포 성숙도 | P | drill이 승격 release를 입력으로 받는다(`config/ci/gates.json` `drill-runbook` 인자 `--release-root .release/promoted-release`). 보관 release 재검증 모드가 있다(`scripts/verify-exact-promotion-bundle.ts:58-60`, `tests/unit/archived-promotion.test.ts` 통과). SW `ACTIVE`의 공개 대상 릴리스가 막힌다(13-01). production_gate의 FE-GATE-019는 `build`를 다시 돌려 로컬 dist의 source map·SW를 본다(`gates.json` FE-GATE-019 `commandIds: [build, verify-hosting-headers]`). 같은 커밋이라 결과 차이는 작다. 실제 호스팅 미검증. |
| **19** | 설정 성숙도 | X | 기본 경로는 스키마 한 벌·프로필 정본·공개 대상 규칙으로 잘 막혀 있다. 그러나 문서가 약속한 두 규칙이 지원 입력에서 깨진다. "dist/config.json은 선택한 프로필이다"가 SW `ACTIVE`와 `build:app-only`에서 깨진다(13-01, E3). "하위 경로 배포는 일관되거나 빌드에서 실패한다"(`vite.config.ts:26-34`)가 `.env*` 파일 입력에서 깨진다(13-02, E3). |
| 20 | 개발자 경험 | P | README에 변수 표와 production 빌드 예시가 있다(`README.md:38-66`). `.env.example:11`의 "`.env.local`로 복사해 덮어쓰라"는 안내가 13-02를 부른다. 필수 조건 누락(13-09). |
| **21** | Guardrail 성숙도 | P | admission fail-closed(E3), 선언 안 된 `VITE_*` 거절(E2), lint 규칙(E3). 빌드 마지막에 dist/config.json을 확인하는 검사가 없다(13-01). 해시 안정성 검사가 대리 지표다(13-03). CSP 내용·설치 정책 검사가 없다(13-04, 13-08). |
| 22 | 추상화 성숙도 | > | 영역 09·12 |
| 23 | 일관성 | P | 기본 설정 URL을 두 곳에서 다르게 계산한다(13-06). 빌드 변수를 읽는 출처가 `loadEnv`와 `process.env`로 갈린다(13-02). `npx`와 `corepack pnpm` 혼용. |
| 24 | 네이밍 / 의미 성숙도 | P | `build:app-only`라는 이름이 "프로필을 무시하고 로컬 설정을 싣는다"는 사실을 드러내지 않는다(13-01). 테스트 이름 "keeps the values the app reads and nothing else" 안에 청크 해시 검사가 섞여 있다(13-03). |
| 25 | 조직 확장성 | - | 1인 관리 전제 |
| **26** | Ownership 성숙도 | P | 템플릿 결함 분류 규칙이 README에 있다(`README.md:348-353`). 이 규칙은 "선택 기능을 켜야 재현되는 템플릿 결함"을 제품 몫으로 분류하게 만든다. 이번 동기화의 제품 상향 보고 2건은 제품 문서에만 있다(13-10). 의존성 기준선 승인은 환경변수 자기 기재다(`scripts/update-dependency-baseline.ts:6-13`). |
| 27 | 삭제 가능성 | > | 영역 14(FE-GATE-020) |
| 28 | 회복 가능성 | P | 보관 release 재검증 모드와 drill `--release-root`가 생겼다(E2). `--archived`는 workflow에 없고 runbook 수동 절차뿐이다(`docs/operations/release-cache-rollback.md:30`). 실제 provider·호스팅 복구는 미검증(U-1). |
## 4. 설계 선택 설명 (41절)
### 4.1 런타임 설정을 빌드 단계 순서로 만든다 — "public 복사 → 프로필로 덮어쓰기"
1. **무엇이 필요한가.** `pnpm dev`는 `public/config.json`을 바로 서빙해야 한다. 배포 빌드는 선택한 환경의 설정을 실어야 한다.
2. **지킬 성질.** 배포 산출물의 `dist/config.json`은 `APP_PROFILE`의 프로필(+ `RUNTIME_*` 두 값, build identity)과 같아야 한다.
3. **현재 보장.** `build-frontend.ts`의 4단계가 3단계(Vite의 `public/` 복사)를 덮어쓴다(확인한 사실, `scripts/build-frontend.ts:31-37` 주석에도 적힘). admission이 공개 대상에서 `APP_ENV`를 대조한다(확인한 사실). **보장하지 않는 것:** 4단계 뒤에 다시 `public/`을 복사하는 경로(SW 두 번째 Vite 단계), 4단계를 건너뛰는 경로(`build:app-only`). 빌드 끝에서 성질을 확인하는 곳이 없다.
4. **대안.** (a) 현상 유지. (b) SW 설정에 `publicDir: false`만 추가. (c) 모든 경로가 거치는 마지막 단계(`generate-build-manifest.ts`)에서 `APP_ENV === (APP_PROFILE ?? "local")`을 확인. (d) `public/config.json`을 없애고 dev 서버가 프로필을 서빙.
5. **비교.** (b)는 한 줄이고 알려진 경로만 막는다. (c)는 한 곳에서 두 경로를 모두 잡고 다음에 생길 경로도 잡는다. 비용은 몇 줄이다. (d)는 dev 서버 미들웨어가 필요하다. memento는 dev 프로필 미들웨어를 이미 두고 있다(제품 기록 214행). 변경 폭이 크다.
6. **현재 조건에서의 판단(리뷰어 추론).** (b)+(c)가 가장 작은 변경으로 성질을 되찾는다. 현 구조(복사 후 덮어쓰기)는 유지해도 된다. 확인 한 줄이 빠진 것이 문제다.
7. **재검토 조건.** 빌드 단계가 더 늘거나, dev 서버가 프로필을 직접 서빙해야 할 요구(예: 여러 로컬 프로필)가 생기면 (d)를 다시 본다.
`APP_PROFILE`과 `RELEASE_TARGET`을 두 변수로 둔 선택도 같은 흐름에 있다. 빌드 입력과 승인 대상을 따로 선언하고 서로 대조한다. 한 변수로 합치면 "무엇을 빌드했는가"와 "어디에 올리려는가"를 따로 적는 이중 확인이 사라진다. 두 값이 repo 단위 변수 하나씩이라 환경을 바꿀 때 둘 다 바꿔야 한다는 비용이 남는다. 현재 조건에서는 유지가 맞다(리뷰어 추론). 환경별 변수(Gitea environment)가 생기면 다시 본다.
### 4.2 빌드 식별값을 JS 번들에 넣고, 청크 분할은 자동에 맡긴다
1. **무엇이 필요한가.** 부팅 시 JS와 `config.json`·release manifest가 같은 release인지 대조해야 한다(`src/bootstrap/load-runtime-config.ts:152-167`, `CONFIG_BUILD_MISMATCH`). 그러려면 JS가 자기 build id를 알아야 한다.
2. **지킬 성질.** build id만 바뀐 두 빌드에서 route 청크와 공용 UI 코드는 해시가 같아야 한다(09-03의 기록된 의도: `src/bootstrap/main.tsx:10-12`, `vite.config.ts:74-76`). 브라우저·SW 캐시를 release마다 버리지 않기 위해서다.
3. **현재 보장.** `getBuildConfig`가 키별로 읽어 build id 문자열을 `env.ts`가 들어간 청크에만 넣는다. preload helper를 따로 떼어 entry를 가볍게 한다(확인한 사실). 템플릿의 현재 청크 그래프에서는 `env.ts`가 `render-boot-failure` 청크(react-dom 포함, 약 58 KB gzip)에 들어가고, 이 청크는 entry와 boot만 import한다. 그래서 route 청크와 `design-system` 청크는 안정적이다(실험 ①). **보장하지 않는 것:** 어느 청크가 build id를 품을지는 rolldown의 자동 분할이 정한다. 설정이나 import 그래프가 조금 바뀌면 달라진다(실험 ②·③, tech-log). 검증은 청크 이름 하나만 본다(13-03).
4. **대안.** (a) 현상 유지. (b) 테스트를 "route 청크(Vite manifest의 `isDynamicEntry`)와 그 정적 import는 build id만 바뀐 두 빌드에서 파일명이 같다"로 바꾼다. (c) build identity를 `manualChunks`로 전용 청크에 격리한다. 이 경우 importer의 해시는 여전히 연쇄로 바뀐다. (d) build id를 JS 밖(HTML `meta` 등, HTML은 `no-cache`)에서 읽는다.
5. **비교.** (b)는 성질 자체를 검사하고 청크 이름과 무관하다. 비용은 테스트 수정뿐이다. (c)는 연쇄 변경을 막지 못해 효과가 작다. (d)는 JS를 release 간 바이트 동일하게 만들 수 있다. 대신 오래된 탭·SW 캐시가 HTML과 JS를 다른 release에서 받는 조합을 다시 따져야 하고, 부팅 대조 로직(`checkReleaseCoherence`)의 입력이 바뀐다.
6. **현재 조건에서의 판단(리뷰어 추론).** 성질 검사를 (b)로 바꾸는 것이 먼저다. 식별값 위치를 옮기는 (d)는 측정된 캐시 비용이 생긴 뒤에 검토해도 된다. 현재 매 빌드 약 96 KB gzip이 바뀌는 비용은 기록된 목표가 없어 결함으로 보지 않았다.
7. **재검토 조건.** 재방문 사용자의 전송량·SW 설치 비용 목표가 생기거나, 다운스트림이 route 청크 이름을 필수로 쓰게 되면(tech-log) 다시 본다.
### 4.3 모든 환경에 CSP 파일 하나를 둔다
1. **필요.** 운영 응답 헤더의 기준값 한 벌. 로컬 e2e(`tests/e2e/production-csp.spec.ts`)와 호스팅 live 검사(`scripts/verify-hosting-headers.ts`)가 같은 값을 읽는다.
2. **지킬 성질.** 인라인 스크립트·`eval` 없이 부팅한다. 선언과 실제 응답 헤더가 같다.
3. **현재 보장.** e2e가 선언 헤더를 붙여 두 화면을 열고 위반 0건을 확인한다(코드 확인, 이번에 실행하지 않음). live 모드는 선언과 응답을 문자열로 비교한다. **보장하지 않는 것:** 다운스트림이 CSP를 넓힐 때 무엇을 바꿔야 하는지(폰트·스타일), 넓힌 값이 안전한지(`'unsafe-inline'`, `*`)는 아무도 보지 않는다. `connect-src`를 API·telemetry origin으로 좁히는 것은 배포 단계 생성기가 필요하다고 문서가 스스로 적는다.
4. **대안.** (a) 현상 유지. (b) 파일 하나를 유지하되 금지 키워드 검사와 "넓히는 법" 문서를 더한다. (c) 프로필별 CSP를 배포 시 생성한다.
5. **비교.** (b)는 작고 기본값의 강도를 유지한다. (c)는 `connect-src`를 좁힐 수 있지만 provider adapter와 생성기가 필요하다.
6. **판단(리뷰어 추론).** 템플릿이 호스팅을 정하지 않은 현재 조건에서는 (b)가 맞다.
7. **재검토.** 호스팅 provider adapter가 템플릿에 들어오거나, 환경마다 API origin이 달라 `connect-src`를 좁혀야 하는 요구가 생기면 (c)를 본다.
## 5. 발견 사항
### 13-01 SW `ACTIVE` 빌드와 `build:app-only`가 선택한 프로필 대신 로컬 설정을 `dist/config.json`에 싣는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 19, 18, 21, 10, 5 (+30.2) — SW 빌드 설정은 영역 06과 겹친다 |
| 근거 | `vite.service-worker.config.ts:69-82`는 `emptyOutDir: false`이고 `publicDir`를 끄지 않는다. Vite는 두 번째 빌드에서도 `public/`을 `dist/`로 복사한다. 그래서 4단계(`scripts/generate-runtime-config.ts`)가 쓴 프로필 문서를 `public/config.json`(로컬 프로필)이 덮는다. 7단계 `scripts/generate-build-manifest.ts:58-60`, `:76-77`, `:124-128`은 그 파일을 읽어 `BUILD_ID`·`RELEASE_ID`만 바꿔 다시 쓴다. 실험 ④: SW `ACTIVE` + `APP_PROFILE=production` + `VITE_BUILD_ID=rel-prod-1` 빌드 exit 0 → `dist/config.json`이 `APP_ENV=local, AUTH_MODE=demo, API_BASE_URL=http://localhost:8080/, BUILD_ID=rel-prod-1`. `verify-release` PASS. admission(`RELEASE_TARGET=production`)만 4개 위반으로 거절. 실험 ⑤: SW `ACTIVE` + `/app/`이면 로컬 빌드에서도 `RELEASE_MANIFEST_URL`이 `/app/release-manifest.json`에서 `/release-manifest.json`으로 되돌아간다(13-07 rebasing이 사라짐). 실험 ⑦: `build:app-only`(`package.json:125`)는 4단계와 권한 단계를 건너뛴다. `APP_PROFILE=production`으로 돌려도 `local demo` 설정과 mode 0600 파일 3개가 나온다. SW e2e 도우미는 `APP_PROFILE` 없이(로컬) 빌드한다(`tests/e2e/support/service-worker-builds.ts`의 `run`). 로컬 프로필은 `public/config.json`과 내용이 같아 결함이 드러나지 않는다. 제품 memento 기록 204행·345행: 같은 결함을 `publicDir: false`로 막고 "템플릿의 잠재 결함"으로 올렸다. |
| 발생 조건 | SW를 `ACTIVE`로 선택하고 local이 아닌 프로필이나 하위 경로로 빌드할 때. 또는 `build:app-only`를 배포 빌드로 쓸 때 |
| 영향 | 문서의 절차(빌드 → admission)를 따르면 staging·production 릴리스가 항상 거절된다. 오류는 "artifact declares local"이라서 원인을 찾기 어렵다. admission을 거치지 않는 배포라면 운영에 demo 인증 + localhost API가 나가 전면 장애가 난다. 하위 경로 배포면 부팅 시 manifest 404. |
| 심각도·우선순위 | Medium · P1 — 기본 구성(SW null)에는 영향이 없다. 문서화된 경로에서는 fail-closed로 막혀 조용한 피해는 없다. 대신 지원하는 선택 기능의 운영 릴리스를 막는 차단 항목이고, 실제 제품이 이미 부딪혔다. admission 없이 배포하는 사용이라면 High로 올린다. |
| 통제·증거 | 프로필 규칙 M2(4단계 구현) / 빌드 끝 확인 M0 / 공개 대상 승인 M3 · E3(실험 ④⑤⑦) |
| 확실성과 남은 가정 | 산출물을 직접 확인했다. 브라우저 부팅은 하지 않았다. |
| 결정의 근거 | 4.1절. 현재 구조(복사 후 덮어쓰기)는 유지하고, 빠진 확인을 더한다. 확인한 사실: 두 경로의 결과. 기록된 의도: `scripts/build-frontend.ts:31-37`. 추론: 마지막 공통 단계에서 확인하면 새 경로도 잡힌다. |
| 이해 비용 | SW를 켜는 제품 작성자가 Vite의 `publicDir` 기본 동작과 빌드 단계 순서를 알아야 원인을 찾는다. |
| 최소 개선 방향 | (1) `vite.service-worker.config.ts`에 `publicDir: false`. (2) 두 경로가 모두 거치는 `scripts/generate-build-manifest.ts`에서 `dist/config.json`의 `APP_ENV`가 `APP_PROFILE ?? "local"`과 다르면 실패시킨다. (3) `build:app-only`를 없애거나 4단계·권한 단계를 포함하게 한다. |
| 대안 비교 | 4.1절 (b)만 하면 `build:app-only`와 다음 경로가 남는다. (c)만 하면 SW 빌드가 실패로 바뀌지만 원인 수정은 여전히 필요하다. 둘 다 하는 것이 가장 작다. |
| 단순화의 보존 조건 | `pnpm dev`가 `public/config.json`을 그대로 쓰는 동작, 06-10(SW 설정이 프로필 문서를 읽음), 13-02(권한) 유지 |
| 비용·부작용 | 작다. SW의 `public/` 자산(예: 아이콘)을 두 번째 단계가 복사하던 효과는 첫 단계가 이미 하므로 잃지 않는다. |
| 재검토 조건 | 빌드 단계가 3개 이상 더 늘면 단계 대신 "산출물 검증 목록" 방식으로 바꾼다. |
| 완료 기준 | SW `ACTIVE` + `APP_PROFILE=production` 빌드의 `dist/config.json`이 production 프로필이다. `APP_PROFILE=production pnpm build:app-only`가 실패하거나 production 설정을 낸다. |
| 검증 방법 | 빌드 테스트 한 개: 임시 복사본에서 SW `ACTIVE`로 바꾸고(`service-worker-builds.ts`의 `replaceOnce` 재사용) `APP_PROFILE=staging`으로 빌드 → `APP_ENV === "staging"` 확인. `generate-build-manifest`에 불일치 fixture 단위 테스트. |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 13-02 빌드 변수를 `.env*` 파일로 주면 번들과 빌드 스크립트가 서로 다른 값을 쓴다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 19, 23, 21, 18, 20 |
| 근거 | Vite는 `.env`, `.env.local`, `.env.[mode]`, `.env.[mode].local`을 읽어 `import.meta.env`에 넣는다. `vite.config.ts:14`도 이를 알고 `loadEnv`로 미선언 변수를 거른다. 그런데 같은 파일의 base 결정과 설정 URL 검사는 `process.env`만 읽는다(`vite.config.ts:64-65`). 빌드 스크립트도 `process.env`만 읽는다: `scripts/generate-runtime-config.ts:59`, `:70-73`, `scripts/generate-build-manifest.ts:36-38`, `vite.service-worker.config.ts:57-58`, `:94-96`. 실험 ⑥: `.env.production.local`에 `VITE_ROUTER_BASE_PATH=/app/`, `VITE_BUILD_ID=env-file-id`를 두고 `node scripts/build-frontend.ts` → exit 0. 번들은 router base `/app/`, build id `env-file-id`. `index.html`은 `src="/assets/…"`(base `/`). `dist/config.json`은 `BUILD_ID=local-build`, `RELEASE_MANIFEST_URL=/release-manifest.json`. release manifest `buildId=local-build`. build id만 파일에 둔 두 번째 실행에서도 `verify-release` PASS. 부팅 시 `load-runtime-config.ts:152-167`이 JS build id와 config `BUILD_ID`를 대조하므로 `CONFIG_BUILD_MISMATCH`가 난다(코드 읽기). `.env.example:11`은 "`.env.local`로 복사해 덮어쓰라"고 안내하고, `:20-21`은 이 값이 "router, SW scope, Vite asset base를 함께 정한다"고 적는다. |
| 발생 조건 | 개발자나 제품이 `VITE_ROUTER_BASE_PATH`, `VITE_RUNTIME_CONFIG_URL`, `VITE_BUILD_ID`를 셸이 아닌 `.env*` 파일에 두고 빌드할 때. `.env.example`을 그대로 복사하면 값이 기본값과 같아 문제가 없다. 값을 바꾸는 순간 생긴다. CI는 셸 변수를 쓰므로 영향이 없다. |
| 영향 | 빌드와 `verify-release`는 통과하고 부팅이 실패한다(설정 404 또는 build 불일치). 13-07이 약속한 "하위 경로 배포는 일관되거나 빌드에서 실패한다"(`vite.config.ts:26-34`)가 이 입력에서는 성립하지 않는다. `.env.local`에 `VITE_RUNTIME_CONFIG_URL=/config.json`이 남아 있으면 셸로 base를 `/app/`로 줘도 `assertRuntimeConfigUnderBase`가 파일 값을 보지 못한다. |
| 심각도·우선순위 | Medium · P2 — 문서가 권하는 입력 방식에서 조용히 깨진 산출물이 나온다. CI 경로는 영향이 없고 첫 부팅에서 드러난다. |
| 통제·증거 | 선언 여부 M3(파일 포함) / 값 일관성 M0 · E3(실험 ⑥) |
| 확실성과 남은 가정 | 산출물을 직접 확인했다. 브라우저 부팅은 하지 않았다(부팅 실패는 코드 읽기). |
| 결정의 근거 | 적용 제외 — 한 값을 두 출처에서 읽는 구현 결함이다. |
| 이해 비용 | 빌드 변수가 어디서 읽히는지 파일 5개를 봐야 안다. |
| 최소 개선 방향 | 빌드 식별·경로 변수의 출처를 하나로 만든다. 가장 작은 방법: `vite.config.ts`에서 `loadEnv(mode, cwd, "VITE_")` 결과가 `VITE_BUILD_ID`·`VITE_ROUTER_BASE_PATH`·`VITE_RUNTIME_CONFIG_URL`에 대해 `process.env`와 다르면 빌드를 멈춘다("이 변수는 셸로만 준다"). `.env.example`에서 세 변수를 빼거나 "셸 전용"으로 적는다. |
| 대안 비교 | 모든 스크립트가 `loadEnv`를 쓰게 하는 방법도 있다. 스크립트 5곳을 바꿔야 하고 mode 개념을 node 스크립트까지 끌고 온다. 거절 한 곳이 더 작다. |
| 단순화의 보존 조건 | 미선언 `VITE_*` 거절(13-06) 유지 |
| 비용·부작용 | 작다. 파일로 build id를 주던 로컬 습관이 있다면 셸로 옮겨야 한다. |
| 재검토 조건 | 빌드 변수가 더 늘어 셸 전용 규칙이 불편해지면 `build-frontend.ts`가 한 번 `loadEnv`해서 모든 단계에 넘기는 방식을 본다. |
| 완료 기준 | 실험 ⑥이 빌드 단계에서 실패한다. |
| 검증 방법 | `tests/unit/build-environment-bundle.test.ts`에 임시 outDir 옆 `.env.production.local` 케이스 추가(또는 `vite.config.ts` 함수 단위 테스트) |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 13-03 청크 이름이 계약처럼 쓰이지만 선언돼 있지 않다 — 해시 안정성 테스트와 route 청크 매핑
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 10, 21, 14, 3, 8 (+30.3, 30.7) |
| 근거 | (1) `tests/unit/build-environment-bundle.test.ts:68-76`은 이름이 `design-system-`으로 시작하는 청크가 정확히 1개이고 두 빌드에서 같기를 기대한다. 이 이름은 rolldown이 자동으로 붙인다. 실험 ②: route 페이지에 청크 이름을 붙이는 `manualChunks`(tech-log 방식) → build id만 바뀐 두 빌드에서 route 청크는 모두 같았다(성질 유지). 그러나 `design-system` 청크가 사라져(`route-auth-example-page`에 합쳐짐) 테스트가 "expected [] to have a length of 1"로 실패했다. 실험 ③: `not-found-page.tsx`가 `getBuildConfig().buildId`를 읽게 하자 `not-found-page` 청크 해시가 빌드마다 바뀌었다(성질 위반). 테스트는 통과했다. (2) `scripts/generate-build-manifest.ts:61-72`는 Vite manifest의 `entry.name === runtime.moduleId`로 route 청크를 찾는다. `name`은 청크 이름이다. 실험 ②에서 build가 "Missing built route chunk: APP_HOME"로 exit 1. 청크 이름이 moduleId와 같아야 한다는 규약은 문서·주석에 없다(grep). (3) 제품 기록: tech-log는 테스트를 자기 청크(`render-boot-failure-*`)로 바꿨고 여전히 실패한다(기록 470행, 509행). tech-log `vite.config.ts:59-60` 주석은 표를 빠뜨리면 "Missing built route chunk"로 멈춘다고 적는다. |
| 발생 조건 | 다운스트림이 `manualChunks`·페이지 파일명·import 그래프를 바꿀 때 |
| 영향 | 올바른 변경인데 `test:unit`(필수 게이트)이 빨갛다. 반대로 route 청크가 release마다 바뀌는 회귀는 통과한다. 빌드 실패 메시지가 원인을 말하지 않는다. tech-log는 현재 원인을 고치지 못해 실패를 안고 있다. |
| 심각도·우선순위 | Medium · P2 — 정확성 피해는 없다. 청크를 조정하는 모든 다운스트림에서 게이트 비용을 반복해서 만든다. |
| 통제·증거 | 해시 안정성 M3(대리 지표) / route 매핑 M3(fail-closed, 설명 없음) · E3(실험 ①②③) + 제품 기록 |
| 확실성과 남은 가정 | 두 방향의 변이로 확인했다. tech-log 트리를 직접 빌드하지는 않았다(의존성이 달라 템플릿 `node_modules`로 빌드할 수 없음). |
| 결정의 근거 | 4.2절. 확인한 사실: 템플릿 그래프에서는 성질이 지켜진다. 기록된 의도: `src/bootstrap/main.tsx:10-12`. 추론: 검사 대상을 이름에서 성질로 바꾸면 유지비가 준다. |
| 이해 비용 | 청크 설정을 바꾸는 제품 작성자가 rolldown 자동 명명 규칙과 두 소비자를 알아내야 한다. |
| 최소 개선 방향 | (1) 테스트: 두 빌드의 Vite manifest에서 `isDynamicEntry` route 청크와 그 정적 import 폐포의 파일명이 같은지 본다. 이름 가정을 없앤다. (2) `generate-build-manifest.ts`: route 청크를 청크 이름이 아니라 manifest의 소스 경로(키 또는 `src`)로 찾는다. 안 되면 오류 메시지에 "청크 이름이 moduleId와 같아야 한다"를 적는다. |
| 대안 비교 | 이름을 설정 상수로 선언하는 방법도 있다. 여전히 rolldown 자동 명명에 기대므로 소스 경로 매칭보다 약하다. |
| 단순화의 보존 조건 | 템플릿 기본 그래프에서 route·design-system 청크가 build id에 따라 바뀌지 않는다는 현재 성질 |
| 비용·부작용 | 작다. 테스트 1개와 매칭 함수 1개 |
| 재검토 조건 | Vite/rolldown이 manifest 형식(`name`, `src`, `isDynamicEntry`)을 바꾸면 다시 본다. |
| 완료 기준 | 실험 ②에서 테스트·빌드가 통과하고, 실험 ③에서 테스트가 실패한다. |
| 검증 방법 | 위 두 변이를 fixture로 테스트에 넣는다. |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 13-04 운영 CSP를 넓히는 경로에 안내와 내용 검사가 없고, 같은 문자열을 4곳에서 고쳐야 한다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 15, 21, 9, 20 (+30.2) |
| 근거 | `config/hosting/security-headers.json:4`는 `style-src 'self'`, `font-src 'self'`다. 넓히는 법은 `docs/architecture/optional-adapter-recipes.md:157-165`에 realtime `wss:`, `blob:`, 이미지 CDN만 있다. 외부 폰트·스타일 안내는 없다(docs grep `font-src|style-src` 0건). CSP 내용을 검사하는 코드가 없다: `scripts/check-browser-security.ts`는 lint fixture와 source map만 본다. `unsafe-inline`·`unsafe-eval`을 찾는 검사는 repo에 없다(grep: `src/contracts/zod.ts:6` 주석뿐). `verify-hosting-headers`는 선언과 응답이 문자열로 같은지만 본다. 선언 CSP는 `config/hosting/response-headers.fixture.json`에 3번 더 복사돼 있다. 실험 ⑧: 선언에 CDN을 더하자 fixture 모드가 `FAIL`(index·runtimeConfig·releaseManifest의 `content-security-policy`)이 됐다. 이 파일을 고치라는 문서는 없다(grep). 제품 기록: memento는 `production-csp.spec.ts`에서 Pretendard CDN 폰트가 막혔고 "CSP를 넓힐지 자체 호스팅할지"를 제품 결정으로 남겼다(memento 기록 326행, 334행). tech-log는 `@fontsource`·`pretendard` 패키지로 자체 호스팅해 부딪히지 않았다. |
| 발생 조건 | 제품이 외부 폰트·스타일·다른 origin 리소스를 쓰려고 CSP를 바꿀 때 |
| 영향 | e2e가 막힘을 알려 주지만 해결 방법은 제품이 찾아야 한다. 넓힐 때 `'unsafe-inline'`이나 `https:` 같은 넓은 값을 넣어도 모든 게이트가 통과한다. 로컬 fixture 검사는 사본 3개를 맞출 때까지 실패한다. |
| 심각도·우선순위 | Low · P2 — 기본값은 안전하고 e2e가 차단을 잡는다. 제품마다 같은 조사를 반복하고, 넓히는 순간 보호 장치가 없다. |
| 통제·증거 | 기본 CSP 강도 M3(e2e, 코드 확인) / 확장 안내 M1(일부) / 내용 검사 M0 · E3(실험 ⑧) + 제품 기록. e2e는 이번에 실행하지 않았다. |
| 확실성과 남은 가정 | 브라우저에서 CDN 폰트 차단을 직접 재현하지 않았다(memento 기록에 의존). |
| 결정의 근거 | 4.3절 |
| 이해 비용 | CSP를 바꾸는 사람이 선언 파일, fixture 3곳, e2e 방문 화면, 문서 9단계를 스스로 찾아야 한다. |
| 최소 개선 방향 | (1) `browser-boundary.md`에 "외부 폰트·스타일: 자체 호스팅 권장, 불가하면 `style-src`·`font-src`에 정확한 origin"을 적는다. (2) `check:browser-security`가 `security-headers.json`을 읽어 `'unsafe-inline'`, `'unsafe-eval'`, `*`, `script-src`의 scheme-only 값을 거절한다. (3) fixture가 CSP를 복사하지 않고 선언 파일에서 읽게 한다. |
| 대안 비교 | 4.3절 (b)와 (c) |
| 단순화의 보존 조건 | fixture 모드가 `UNVERIFIED`로 끝나는 동작(13-05 수정) 유지 |
| 비용·부작용 | 작다. 금지 목록 예외가 필요한 제품은 명시적 예외를 둬야 한다. |
| 재검토 조건 | 호스팅 provider adapter가 들어오면 CSP 생성기를 검토한다. |
| 완료 기준 | 선언에 `'unsafe-inline'`을 넣으면 `check:browser-security`가 실패한다. CDN을 더할 때 선언 파일 한 곳만 고치면 된다. |
| 검증 방법 | 금지 값 fixture 1개, fixture 모드 재실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 13-05 SBOM이 `pnpm list`의 `deduped` 노드를 따라가지 않아 번들되는 전이 의존성을 development로 적는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 16, 24 |
| 근거 | `scripts/lib/supply-chain.ts:195-267`의 `visit`는 각 노드의 `dependencies`만 따라간다. 실험 ⑮: `pnpm list --json --depth Infinity`에서 production 루트의 `react-dom`은 `deduped: true`이고 자식이 없다. 하위 트리는 dev 경로(`@storybook/react-vite → … → @storybook/react-dom-shim → react-dom`)에만 출력된다. 그래서 `scheduler@0.27.0`이 `ca:scope: development`로 기록된다(`artifacts/release/sbom.cdx.json`, `config/security/dependency-baseline.json:5761-5768`). deduped 노드를 풀어 계산한 production 폐포는 11개, SBOM production은 10개이고 차이는 `scheduler`뿐이다. `react-dom` 클라이언트가 scheduler를 번들에 포함한다. FOLLOW-UP은 이를 F-11 "분류와 기준선 재승인"(사용자 몫)으로 넘겼다. 원인은 코드다. |
| 발생 조건 | production 패키지의 전이 의존성이 dev 경로에서 먼저 출력될 때. 제품이 의존성을 늘리면 늘어날 수 있다. |
| 영향 | SBOM·기준선이 배포물에 든 패키지를 개발용으로 적는다. 취약점 분류·감사에서 우선순위를 낮출 수 있다. 코드 수정 없이 기준선을 재승인하면 틀린 분류를 승인하게 된다. |
| 심각도·우선순위 | Low · P2 — 현재 1개. F-11 재승인 전에 고쳐야 재승인이 의미를 가진다. |
| 통제·증거 | M2(분류 구현, deduped 누락) · E3 |
| 확실성과 남은 가정 | pnpm 11.17.0 출력으로 확인했다. |
| 결정의 근거 | 적용 제외 — 입력 형식을 덜 처리한 구현 결함이다. |
| 이해 비용 | 분류가 틀린 이유를 찾으려면 pnpm JSON 형식을 알아야 한다. |
| 최소 개선 방향 | 먼저 모든 비-deduped 노드에서 `name@version → 자식` 표를 만들고, 그 표로 production 루트부터 폐포를 계산한다. |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 작다. 기준선 digest가 바뀌므로 재승인이 한 번 필요하다(F-11과 합친다). |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | SBOM에서 `scheduler@0.27.0`이 production이다. |
| 검증 방법 | deduped production 노드를 가진 fixture로 `tests/unit/supply-chain.test.ts`에 케이스 추가 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 13-06 하위 경로 배포에서 base를 따르지 않는 소비자 두 곳이 남았다(13-07 잔여)
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 23, 19, 18 |
| 근거 | 앱은 기본 설정 URL을 `${routerBasePath}config.json`으로 만든다(`src/contracts/env.ts:143-144`). SW 빌드는 `process.env.VITE_RUNTIME_CONFIG_URL ?? "/config.json"`이다(`vite.service-worker.config.ts:94-96`). 실험 ⑤: `/app/` 빌드의 `service-worker.js`에 `runtimeConfigUrl:"/config.json"`. 앱은 `/app/config.json`을 요청한다. 현재 `classifyFetch`(`src/adapters/service-worker/service-worker-static-assets.ts:45-58`)에서 이 요청은 `NETWORK_PASSTHROUGH`가 되어 가로채지 않으므로 동작 차이는 없다(코드 읽기). 호스팅 live probe는 `/`, `/config.json`, `/release-manifest.json`을 루트 절대 경로로 요청한다(`scripts/verify-hosting-headers.ts:120-122`). `HOSTING_BASE_URL=https://host/app/`이어도 `https://host/config.json`을 본다. |
| 발생 조건 | 하위 경로 배포 |
| 영향 | SW: 분류 규칙이 바뀌면(예: 설정 요청을 명시적으로 막는 규칙) 조용히 틀린다. probe: 하위 경로 배포에서 FE-GATE-019가 404로 실패하거나, 같은 호스트 루트의 다른 앱 헤더를 보고 통과한다. |
| 심각도·우선순위 | Low · P3 — 하위 경로 배포에서만, 현재 SW 동작 차이 없음 |
| 통제·증거 | M2(앱·설정) / M0(SW·probe) · E3(SW) + E1(probe) |
| 확실성과 남은 가정 | probe는 실제 호스트 없이 코드로만 확인했다. |
| 결정의 근거 | 적용 제외 — 같은 기본값을 두 곳에서 다르게 계산한 복사본이다. |
| 이해 비용 | 작다. |
| 최소 개선 방향 | SW 설정이 `getBuildConfig(process.env).runtimeConfigUrl`을 쓴다. probe는 경로를 `HOSTING_BASE_URL` 기준 상대 경로(`config.json`)로 요청한다. |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 작다. |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | `/app/` 빌드의 SW에 `/app/config.json`이 들어간다. probe가 `HOSTING_BASE_URL` 아래 경로를 요청한다. |
| 검증 방법 | `tests/unit/sub-path-deployment.test.ts`에 SW 입력·probe URL 케이스 추가 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 13-07 청크 설정이 Vite 8의 폐기 예정 별칭(`build.rollupOptions`)에 있어, `rolldownOptions`를 더하면 조용히 무시된다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 16, 23, 9 |
| 근거 | 템플릿은 `vite.config.ts:72-80`에서 `build.rollupOptions.output.manualChunks`로 preload helper를 분리한다. Vite 8.1.5는 `build.rolldownOptions ??= build.rollupOptions`로 처리한다(`node_modules/.pnpm/vite@8.1.5…/dist/node/chunks/node.js:2753`). 사용자 설정에 두 키가 모두 있으면 경고 없이 `rolldownOptions`만 쓴다(경고는 plugin과 `optimizeDeps` 경로에만 있다: `:2754`, `:36209`). 실험 ⑬: `build.rolldownOptions: { output: { minify: true } }`만 더하자 `preload-helper` 청크가 사라졌다(0개). 이러면 09-03이 막은 문제(entry가 helper를 품어 모든 lazy 청크가 매 빌드 바뀜)가 돌아온다. tech-log는 이를 알아채고 두 설정을 `rolldownOptions` 하나로 합쳤다(tech-log `vite.config.ts:134-147`, 기록 224-227행). |
| 발생 조건 | 제품이 Vite 8 문서대로 `rolldownOptions`에 자기 설정을 더할 때 |
| 영향 | 템플릿 청크 정책이 경고 없이 꺼진다. 13-03의 테스트가 이 경우는 실패로 잡을 가능성이 높지만(성질 위반), 원인 설명은 없다. |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M1 · E3 |
| 확실성과 남은 가정 | 경고가 없는 것은 `--logLevel warn`으로 확인했다. |
| 결정의 근거 | 적용 제외 — 키 이름 이전이다. |
| 이해 비용 | 작다. |
| 최소 개선 방향 | `rollupOptions`를 `rolldownOptions`로 바꾼다. `vite.service-worker.config.ts:74`도 같이 바꾼다. |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | preload helper 분리 동작 |
| 비용·부작용 | 없음 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 두 설정 파일에 `rollupOptions`가 없다. |
| 검증 방법 | 빌드 후 `preload-helper-*.js` 존재 확인(기존 번들 테스트) |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 13-08 pnpm 설치 정책이 파일에만 있고, 되돌림과 암묵 기본값을 잡는 검사가 없다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 16, 21, 26 |
| 근거 | `pnpm-workspace.yaml:1-18`에 `engineStrict`, `saveExact`, `allowBuilds`, `minimumReleaseAgeExclude`가 있다. 이 값을 확인하는 스크립트·테스트는 없다(grep: `allowBuilds`는 `scripts/lib/package-script-graph.ts` 주석뿐). `minimumReleaseAge`는 파일에 없고 pnpm 11 기본값(1440분)에 기댄다. `pnpm config get minimum-release-age` → `undefined`. pnpm 11 공식 릴리스 노트에 따르면 기본 `minimumReleaseAgeStrict`는 `false`이고, 이 모드에서 pnpm은 조건을 못 맞추면 `minimumReleaseAgeExclude`에 항목을 자동으로 더한다(pnpm 11.0·11.4 릴리스 노트, E0). 템플릿 주석(`:9-13`)은 예외마다 owner와 재검토 조건을 요구하지만, 자동 추가된 항목에는 그런 기록이 없다. |
| 발생 조건 | 누군가 설정을 지우거나, 개발자가 `pnpm add`·`update`로 하루 안 된 버전을 받을 때 |
| 영향 | 13-09에서 고친 설정이 다시 사라져도 모른다. 공개 경과 기간 보호가 리뷰 없이 우회될 수 있다. CI는 `--frozen-lockfile`이라 설치 시점 영향은 로컬에 한정된다. |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M2(설정) / 검출 M0 · E3(`engineStrict` 동작, 실험 ⑭) + E0(pnpm 문서, 자동 추가 동작은 실행 확인 못 함) |
| 확실성과 남은 가정 | 자동 추가 동작은 새 패키지 공개가 필요해 재현하지 않았다. |
| 결정의 근거 | 적용 제외 — 설정 고정과 회귀 검사 누락이다. |
| 이해 비용 | 작다. |
| 최소 개선 방향 | `minimumReleaseAge: 1440`, `minimumReleaseAgeStrict: true`를 명시한다. `check:ci` 또는 단위 테스트 하나가 이 키들과 `engineStrict`·`saveExact`의 존재, 예외 항목이 정확한 버전 형식인지를 확인한다. |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | strict 모드에서는 새 버전 설치 시 확인 절차가 한 번 더 생긴다. |
| 재검토 조건 | pnpm 메이저 버전이 바뀔 때 |
| 완료 기준 | 키를 하나 지우면 검사가 실패한다. |
| 검증 방법 | 단위 테스트 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 13-09 README 변수 표가 staging·production의 `VITE_BUILD_ID` 필수 조건을 적지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 20, 19 |
| 근거 | `README.md:46`은 기본값을 `local-build`로만 적는다. 코드는 staging·production에서 값이 없으면 실패한다(`scripts/generate-runtime-config.ts:70-72`, 실험 ⑪). `.env.example:13-15`도 "developer build falls back"만 적는다. `verify:documentation`은 변수 이름만 대조한다. |
| 발생 조건 | README만 보고 staging 빌드를 할 때 |
| 영향 | 빌드가 명확한 오류로 멈춘다. 피해는 시간뿐이다. |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M1 · E1 |
| 확실성과 남은 가정 | 정적 확인 |
| 결정의 근거 | 적용 제외 — 문서 누락 |
| 이해 비용 | 작다 |
| 최소 개선 방향 | 표의 기본값 칸에 "local·development만. staging·production은 필수"를 적는다. |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 없음 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | README 표가 코드 조건과 같다. |
| 검증 방법 | 문서 검토 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 13-10 "선택 기능을 켜야 재현되는 템플릿 결함"의 책임이 정해져 있지 않다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 26 (+30.4) |
| 근거 | `README.md:348-353`: "수정하지 않은 `.template-origin` 체크아웃에서 재현되면 템플릿 결함, 제품 변경이 있어야 재현되면 제품 몫". 이번 동기화에서 두 제품이 올린 템플릿 문제는 둘 다 "지원하는 선택·설정을 바꿔야 재현"된다: memento의 SW `publicDir`(13-01, SW `ACTIVE` 선택 필요), tech-log의 번들 테스트(13-03, 청크 설정 변경 필요). 규칙을 글자대로 적용하면 둘 다 제품 몫이 된다. 두 건은 제품 문서에만 있고 템플릿 저장소 이슈에는 없다(Gitea API 읽기, 2026-09-29 기준 이슈·PR 3건, 모두 무관). 동기화가 같은 날이라 보고 지연일 수 있다. |
| 발생 조건 | 제품이 선택 기능·지원 설정에서 템플릿 결함을 만날 때 |
| 영향 | 제품마다 같은 결함을 따로 고친다(memento는 이미 고쳤고 tech-log는 SW를 켜면 같은 일을 겪는다). 템플릿의 잠재 결함이 남는다. |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M1 · E1 + 제품 기록 |
| 확실성과 남은 가정 | 제품이 앞으로 보고할지는 모른다. |
| 결정의 근거 | 규칙을 넓히면 템플릿이 모든 선택 조합을 책임지는 것처럼 보일 수 있다. 30.2절처럼 "기본 지원·선택 지원·실험·비지원" 중 선택 지원 기능은 템플릿 책임에 넣는 것이 가장 작은 변경이다(리뷰어 추론). |
| 이해 비용 | 작다 |
| 최소 개선 방향 | README 결함 절에 "수정하지 않은 체크아웃에서 **문서화된 선택 기능·설정만 바꿔** 재현되면 템플릿 결함"을 한 줄 더한다. |
| 대안 비교 | 현상 유지: 제품 기록에만 남고 템플릿에 모이지 않는다. |
| 단순화의 보존 조건 | 제품 고유 변경은 제품 책임으로 남긴다. |
| 비용·부작용 | 템플릿 유지보수 요청이 늘 수 있다. |
| 재검토 조건 | 제품이 3개 이상으로 늘거나 선택 기능 수가 늘면 선택 기능별 지원 상태 표를 둔다. |
| 완료 기준 | README 규칙이 선택 기능 재현을 명시한다. |
| 검증 방법 | 문서 검토 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
## 6. FOLLOW-UP 재확인
| FOLLOW-UP 항목 | 결과 | 현재 근거 |
|---|---|---|
| P1 초기 JS 예산 여유 약 1.3KB | **유효** | 실험 ⑨: 203,481 / 204,800(여유 1,319 B). `config/scale/feature-shape-growth.json` 기준 기능 모양 1개 ≈ +2,980 B. 다음 기능 하나가 게이트를 넘는다. 두 제품은 이번 동기화에서 `check:bundle`을 기록하지 않았다. |
| P2 레시피 번들 예산 인상 | **유효** | 실험 ⑨: file-transfer 55,623/55,700(여유 77), offline-indexeddb 36,891/36,900(여유 9), realtime 40,886/40,900(여유 14) |
| P2 13-03 운영 단계는 archive SHA만 대조 | **유효** | production_gate는 `verify-ci-candidate-archive.ts`(SHA·추출)만 한다(`.gitea/workflows/quality-gates.yml:404-405`). `--archived` 재검증은 workflow에 없고 runbook 수동 절차다(`docs/operations/release-cache-rollback.md:30`). |
| P3 06-10 SW 설정의 `dist/config.json` 읽기에 단위 테스트 없음 | **유효** | 테스트는 여전히 없다. 같은 두 번째 단계가 그 파일을 다시 덮어쓰는 결함이 있다(13-01). |
| P3 fixture pnpm 설치 검사 끔(F-4, F-12) | **유효** | `scripts/lib/fixture-node-modules.ts:41` `pnpm_config_verify_deps_before_run: "false"`. 영역 10·11과 겹친다. |
| F-11 SBOM `scheduler@0.27.0` 분류(사용자 몫) | **유효, 원인 재분류** | 여전히 development. 원인은 분류 코드다(13-05). 코드 수정 뒤 재승인해야 한다. |
| P2 `check:remediation-ledger` | 판단 불가 | 영역 12 소관. 오케스트레이터 게이트 결과에서 알려진 실패로 유지됨 |
## 7. 미검증 목록
| 항목 | 이유 | 확인하려면 |
|---|---|---|
| `production-csp.spec.ts`와 외부 폰트 차단 | Playwright를 돌리지 않았다. 다른 에이전트와 포트 4173이 겹칠 수 있다. | 포트를 바꾼 설정으로 chromium 실행, CSS에 외부 `@import`를 넣은 변이 |
| SW `ACTIVE` production 산출물의 실제 부팅 실패 | 브라우저 부팅 안 함(산출물만 확인) | SW e2e 도우미를 `APP_PROFILE=staging`으로 확장 |
| `.env*` 입력 산출물의 `CONFIG_BUILD_MISMATCH` | 코드 읽기만 | 실험 ⑥ dist를 preview로 띄워 부팅 |
| 실제 호스팅·CDN 헤더, 하위 경로 live probe | provider 미정 | 정적 서버에 `/app/`으로 배포 후 `HOSTING_BASE_URL` 지정 |
| Gitea workflow 실행(FE-GATE-027, production_gate) | U-1(Actions 꺼짐) | runner와 repo 변수 |
| 외부 vulnerability·provenance provider, `--archived` 실제 서명 번들 | provider 키 없음 | staging smoke(U-4) |
| pnpm `minimumReleaseAgeStrict: false`의 자동 예외 추가 | 새 패키지 공개가 필요 | 사설 registry에서 방금 공개한 버전 설치 |
| tech-log 트리에서 13-03 성질 측정 | 제품 의존성이 템플릿 `node_modules`와 달라 빌드 불가, 제품 `node_modules`에 쓰기 금지 | 제품 repo에서 직접 두 번 빌드 |
| 여러 runner 사이 빌드 재현성 | 단일 호스트 | 다른 runner 이미지에서 digest 비교 |
@@ -0,0 +1,328 @@
# 14 — 템플릿 제품성·문서·DX·업데이트 전파
> 검토일: 2026-09-29 · 기준: `main` / `af3d8e6`(태그 `v0.2.0` = `f753669` + docs 커밋 1개) · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`(워킹트리 판)
> 영역 판정(35.8): **조건부 사용 가능.** 복사해서 시작하는 용도와 태그 단위 동기화는 두 제품에서 실제로 동작했다(E3). 다만 동기화마다 같은 파일에서 충돌하고, 템플릿 자신의 기록을 제품이 매번 골라내며, CHANGELOG가 제품이 할 일을 일부 빠뜨린다(14-01~14-04).
## 1. 머리말 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 | `clean-architecture-frontend-template`, `main` `af3d8e6`. 미커밋 변경은 리뷰 가이드 2개뿐이다(코드와 무관) |
| 목적·실행 구성 | 복사해서 시작하고 Git으로 원본 수정을 받아 가는 프론트엔드 템플릿. 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음 |
| 소비자 | `../tech-log-frontend`(이력 비공유, 기준점 명시 3-way 병합), `../memento-frontend`(이력 공유, `git merge`). 둘 다 2026-09-29에 `ebea300` → `af3d8e6`(359커밋)을 받았다. 브랜치 `chore/template-sync-v0.2.0` |
| 읽은 것 | `README.md` 전체, `CHANGELOG.md` 전체, `docs/README.md`, `docs/architecture/starter-experience.md`, `docs/operations/ci-quality-gates.md` 1~75행, `docs/contracts/compatibility.md` 앞부분, `docs/architecture/optional-adapter-recipes.md` 3절 끝, `docs/superpowers/specs/2026-09-20-memento-frontend-template-bootstrap-design.md` 0~2절, `scripts/test-sample-removal.ts` 전체, `scripts/lib/removal-fixture.ts` 1~240행, `scripts/verify-extreme-scale.ts`·`scripts/scale/run-scale-profile.ts`의 기록 부분, `tests/unit/deletable-history-documents.test.ts`, `.gitignore`, `recipes/frontend-capabilities/index.ts`, `CLAUDE.md`, `SPEC.md`·`tasks/` 목록. 두 제품의 `docs/operations/template-sync-2026-09-29.md` 전체, tech-log `template-sync-2026-09-21.md` 목차와 충돌 절, 두 제품의 `.gitignore`·`config/runtime/*.json`·기준점 파일 |
| 실행한 것 | ① 두 제품을 scratchpad에 `git clone --no-checkout`하고 템플릿 `main`을 fetch했다(제품 repo 자체는 읽기만 함). ② 충돌 재현: `git merge-tree --write-tree --merge-base=ebea300 --name-only 8210d48 af3d8e6`(tech-log) → 67경로, `git merge-tree --write-tree --name-only 42eaf45 af3d8e6`(memento) → 25경로, `git merge-tree --write-tree --merge-base=5434760 --name-only afde2b1^ ebea300`(tech-log 09-21) → 23경로. ③ 템플릿 변경 분류: `git diff --numstat ebea300 af3d8e6`. ④ worktree(`af3d8e6`)에서 `node scripts/generate-product-feature-index.ts` 후 `node scripts/scale/run-scale-profile.ts pr`(= `check:scale:pr`, FE-GATE-005가 돌림) → PASS, 뒤이어 `git status --short`. worktree는 지웠다. ⑤ `git grep`으로 로그·기록 파일을 읽는 코드 탐색. ⑥ Gitea API 읽기: 템플릿 repo 설정, 이슈 목록, 태그 |
| 확인하지 못한 것 | 깨끗한 환경에서 템플릿 자체의 `install --frozen-lockfile` → `dev`(공유 node_modules 보호). 제품의 운영 CORS 설정 값(배포 변수라 repo에 없음). Playwright 계열. 나머지 제거 스크립트 3개(`test:optional-recipe-removal` 등)의 이번 커밋 실행 |
| 이전 리뷰와 비교 | 2026-09-25 14영역 발견 8건은 모두 닫혔다(11절). 이번 라운드의 새 증거는 두 제품의 실제 동기화다. 지난 결과는 증거로 쓰지 않았다 |
## 2. 대표 흐름
### 2.1 정상 흐름 — 문서만 보고 기능 하나를 설치한다
```text
feature-module.ts / context-routes.ts / context-module.ts 작성
-> 생성기 규칙 검사 (리터럴 export, 소속 context, 예산)
-> src/.generated/ 재생성, installed-* 가 인덱스를 투영
-> 라우터가 context 경계로 lazy mount
```
- 입력: `docs/architecture/starter-experience.md:112-147` "Adding a feature".
- 정책: `scripts/generate-product-feature-index.ts`. 선언이 없거나 예산을 넘으면 파일 이름을 대며 실패한다(`starter-experience.md:99-110`).
- 상태 변화: `src/.generated/`(git-ignored). 중앙 catalog는 고치지 않는다(`starter-experience.md:145-147`).
- 외부 I/O: 없음.
- 실패: 선언 누락·예산 초과·모르는 `VITE_PRODUCT_FEATURES`에서 첫 빌드 단계가 멈춘다.
- 결과(E3): memento가 이 절차로 `memento-web`을 설치했다(memento `template-sync-2026-09-29.md:168-186`). 단, 제품이 `/`와 셸을 가지는 부분은 이 절차 밖이라 템플릿 파일 두 곳에 다리를 놓았다(14-03).
### 2.2 피해가 큰 흐름 — 템플릿의 [계약] 변경이 제품 운영까지 전파된다
```text
템플릿 커밋 -> CHANGELOG [계약] 행 -> 제품 동기화 -> 제품·백엔드·배포 조치 -> 배포
```
- `x-correlation-id`: 모든 V3 실행이 헤더를 붙인다(`src/adapters/http/http-execution-v3.ts:817-826`). 다른 origin API는 GET도 preflight 대상이 된다. 행은 `CHANGELOG.md:24`에 있다.
- 실패: 백엔드 CORS가 헤더를 허용하지 않으면 V3 요청이 preflight에서 거절된다.
- 결과(E3): 두 제품의 `API_BASE_URL`은 앱과 다른 origin이다(`config/runtime/*.json`). 그런데 두 동기화 기록 어디에도 이 행의 조치나 질문이 없다. 같은 방식으로 전달된 `readSubject` 필수화(`CHANGELOG.md:43` → `starter-experience.md:54-76`)는 tech-log가 찾아서 고쳤다(tech-log 기록 316-328행). 차이는 14-04에서 다룬다.
### 2.3 변경·삭제 흐름 — 태그까지 따라잡고, 템플릿 기록을 빼고, 샘플 삭제를 판단한다
```text
새 태그 -> (문서) cherry-pick 1건 / (실제) 359커밋 범위 병합
-> 충돌 67 / 25 -> 파생 기준선 재계산 -> 템플릿 기록 삭제 -> 게이트 기준선과 비교
-> 실패 시 backup ref 로 되돌림
```
- 정책: `README.md:315-353`. 실제로 쓴 절차는 README에 없다(14-02).
- 상태 변화: tech-log는 템플릿 경로 127개를, memento는 70개를 가져오지 않았다. 둘 다 작업 기록을 따로 조사해 골라냈다(14-01).
- 샘플: `README.md:205-209`는 샘플 삭제를 안내한다. 두 제품 모두 지우지 않았다. tech-log는 "다음 동기화가 깨끗하게 병합되도록" `NOT_INSTALLED`로만 뒀다(tech-log 기록 122-125행). 삭제의 동기화 비용은 템플릿의 이력 문서에만 적혀 있다(14-03).
- 되돌림: 두 제품 모두 `backup/main-before-template-af3d8e6`를 먼저 만들었다. README는 이 단계를 안내하지 않는다.
## 3. 28개 관점 판정표 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가.
| 번호 | 관점 | 판정 | 통제·증거 | 근거와 잔여 위험 |
|---|---|---|---|---|
| 1 | 코드 성숙도 | > | - | 01~13 영역 |
| 2 | 구조적 성숙도 | > | - | 09, 12 영역 |
| 3 | 변경 용이성 | P | M1 · E3 | 동기화 변경 비용: 8개 경로가 세 번 연속 충돌했다(34절 표, 14-03). 기능 추가 경로 자체는 E3로 동작 |
| 4 | 인지 부하 | P | M1 · E1 | `docs/README.md`가 현재 계약·목표 설계·이력을 나눈다. 문서는 136개 약 69.7k줄로 늘었다. 동기화에 필요한 지식(파생 기준선 재계산, 제외 목록)은 템플릿 문서 밖에 있다(14-02) |
| 5 | 위험 가시성 | > | - | 코드 수준은 다른 영역. 소비자에게 위험을 알리는 CHANGELOG는 17·26에서 본다 |
| 6 | 실패 성숙도 | > | - | 다른 영역 |
| 7 | 운영 성숙도 | > | - | 11, 13 영역 |
| 8 | 디버깅 가능성 | O | M3 · E1 | 제거 JUnit이 실패 수와 검사별 원인을 쓴다(`scripts/lib/removal-fixture.ts:218-236`). 지난 14-08 해소 |
| 9 | 유지보수 성숙도 | P | M1 · E3 | **깊게 봄.** 태그·CHANGELOG·색인이 생겼다. "제품이 고치는 템플릿 파일은 영구 충돌 지점"이라는 판단이 지워도 되는 이력 문서에만 있다(`docs/superpowers/specs/2026-09-20-memento-…:35,37,56`, 14-03). 현재 계약 문서에 코드와 다른 문장이 있다(`ci-quality-gates.md:69`, 14-05). `docs/README.md:72`의 "라운드가 쓰는 중" 사유는 만료됐다(14-01) |
| 10 | 테스트 성숙도 | P | M3 · E2(오케스트레이터) | 샘플 제거 13개 검사 PASS. lint·`check:i18n`·e2e는 검사하지 않는다(`scripts/test-sample-removal.ts:413-428`, FOLLOW-UP 09-07). 지울 수 있는 기록 검사는 `artifacts/`를 보지 않는다(`tests/unit/deletable-history-documents.test.ts:25-31`) |
| 11 | 데이터 성숙도 | - | - | 이 영역에 데이터 경계가 없다 |
| 12 | 동시성 성숙도 | - | - | 이 영역에 동시 실행 경로가 없다 |
| 13 | 확장성 | > | - | 11 영역 |
| 14 | 성능 성숙도 | > | - | 13 영역 |
| 15 | 보안 성숙도 | > | - | 다른 영역. CHANGELOG의 [보안] 행은 경로·커밋이 붙어 있다 |
| 16 | 의존성 성숙도 | P | M2 · E3 | 제품 입장에서 템플릿은 의존성이다. 태그 `v0.2.0`이 원격에도 있다(Gitea API tags → `f753669`). 기준점 기록 형식이 두 제품에서 다르다(14-02) |
| 17 | API / Contract 성숙도 | P | M1 · E3 | 템플릿→제품 계약 채널은 CHANGELOG [계약]이다. 게이트를 좁힌 변경 5종이 [계약] 표시 없이 들어가 제품 게이트를 깨뜨렸다. 저장소 밖 조치에 담당·확인이 없다(14-04). 공개 포트를 필수로 바꾸는 단계 정책이 없다(FOLLOW-UP 2절) |
| 18 | 배포 성숙도 | > | - | 13 영역 |
| 19 | 설정 성숙도 | P | M3 · E1 | README 변수 표는 `verify:documentation`이 검사한다(`README.md:50-51`). 기준선 표의 `FEATURE_OVERRIDES` 설명이 코드와 다르다(14-05) |
| 20 | 개발자 경험 | P | M1~M3 · E3 | **깊게 봄.** 과제 1·3·4는 문서로 가능하다(4는 memento E3). 과제 5 샘플 제거는 스크립트의 편집 약 12종을 손으로 따라 해야 하고 동기화 비용 설명이 없다. 과제 6 문제 해결 문서는 없다. "업데이트" 과제는 README 절차와 실제가 다르다(14-02) |
| 21 | Guardrail 성숙도 | P | M3(목록 안) / M0(목록 밖) · E3 | 지울 기록 5종은 읽는 코드가 없음을 테스트가 막는다. 추적 중인 실행 로그 63개는 README의 "생성 증거는 무시된다"(`README.md:309-310`)와 달리 추적되고, merge 게이트가 다시 쓴다(14-01, 실험) |
| 22 | 추상화 성숙도 | > | - | 09 영역 |
| 23 | 일관성 | P | M1 · E3 | 두 제품이 기준점 형식(`.template-origin` / `template.lock.json`), CHANGELOG·`docs/reviews` 처리에서 서로 다르게 판단했다. 템플릿이 정하지 않았기 때문이다(14-01, 14-02) |
| 24 | 네이밍 / 의미 성숙도 | P | M1 · E3 | `NOT_INSTALLED`는 "빌드에 없음"이다(`README.md:117`). tech-log는 생성기 밖에서 조립하는 자기 도메인 기능에 이 표식을 붙였다(`src/features/tech-log/NOT_INSTALLED`). 생성기에 "직접 조립" 상태가 없어서다. 표식 설계는 09 영역으로 넘긴다 |
| 25 | 조직 확장성 | P | M1 · E3 | 소비자 2개가 같은 템플릿 파일 17개에서 충돌했다. 소비자가 늘면 같은 비용이 곱해진다(14-03) |
| 26 | Ownership 성숙도 | P | M1 · E3 | **깊게 봄.** 결함 분류 규칙(`README.md:348-353`)은 tech-log가 실제로 썼다(수정 없는 `af3d8e6` export에서 재현, tech-log 기록 473행). 하지만 템플릿 이슈는 0건이고, 제품이 찾은 템플릿 결함 후보가 템플릿에 돌아오지 않는다(14-06). CHANGELOG에 조치 담당 칸이 없다(14-04) |
| 27 | 삭제 가능성 | P | M3 · E2(템플릿) / E3(제품) | **깊게 봄.** 템플릿의 샘플 제거 게이트는 통과한다. 제품은 삭제 대신 유지를 골랐다. 삭제한 파일이 동기화마다 충돌하기 때문이다(tech-log 09-29의 삭제 관련 충돌 18개(수정/삭제 17, 이름변경/삭제 1)가 모두 제품이 지운 샘플·예시 화면). README는 이 비용을 적지 않는다(14-03). 두 제품의 FE-GATE-020은 제품 사정으로 red다(tech-log registry 결함, memento 커버리지) |
| 28 | 회복 가능성 | > | - | 다른 영역. 동기화 되돌림은 30.4에서 본다 |
### 3.1 30절 템플릿 기준 판정
| 절 | 판정 | 근거 |
|---|---|---|
| 30.1 최소 구성과 안전한 기본값 | P | `public/config.json`은 demo 인증·텔레메트리 꺼짐이다. demo는 local/development 밖에서 파싱 단계에서 거절된다(`src/contracts/release-artifacts.ts:103-107`). staging·production 승인은 external 인증을 요구한다(`src/contracts/deployment-admission.ts:77-80`). 템플릿 자체의 깨끗한 환경 실행은 이번에 확인하지 못했다. memento는 파생 트리에서 `install --frozen-lockfile`을 깨끗한 worktree로 실행했다(memento 기록 37-39행) |
| 30.2 옵션 조합 | P | 기본/선택/실험/비지원 표와 상태 어휘 대응표가 있다(`README.md:94-124`). 조합의 검증 범위는 적혀 있지 않다. memento는 SW를 `ACTIVE`로 켠 첫 소비자로서 템플릿이 돌리지 않는 조합에서 결함 후보를 찾았다(memento 기록 202-207행, 14-06) |
| 30.3 생성·복사 후 수정 권한 | P | 생성 파일은 표시되고 drift가 검사된다(`.gitea/workflows/quality-gates.yml:1`, `src/.generated/`). 템플릿 자신의 기록과 복사 대상의 구분은 일부만 있다(14-01). 제품이 고치게 되는 템플릿 파일의 목록이 없다(14-03) |
| 30.4 버전과 업데이트 전파 | P | **E3.** 태그·CHANGELOG·업데이트 절·결함 분류 규칙이 있고, 두 제품이 수정 보존·충돌 설명·게이트 비교·되돌림 ref까지 갖춰 동기화했다. 문서 절차가 실제와 다르고(14-02), 같은 파일이 매번 충돌하며(14-03), CHANGELOG가 제품 조치를 일부 빠뜨린다(14-04). 측정은 34절 표 |
| 30.5 샘플 코드의 대표성 | P | 샘플은 목록·상세·폼·상태와 실패 분류를 보여 주고, 플랫폼 테스트는 테스트 전용 기능을 쓴다. 템플릿 테스트 일부가 템플릿 화면(`/`, `/examples/*`)에 묶여 있어 tech-log는 7개, memento는 9개 파일을 제품 화면으로 옮겼다(tech-log 기록 292-312행, memento 262행). 이 테스트는 다음 동기화의 충돌 후보다 |
| 30.6 도입·유지 비용 | P | package script 142개, CI 게이트 27개(명령 98개), 문서 약 69.7k줄. 동기화 비용은 34절 표: 충돌 67/25, 가져오지 않은 경로 127/70, 템플릿 때문에 새로 red가 된 게이트·테스트 5종/4종 |
| 30.7 템플릿에서 졸업할 수 있는가 | P | tech-log는 자기 도메인을 생성기 밖에서 조립하고, memento는 템플릿 파일에 다리 두 개를 두고, 둘 다 계속 동기화한다. 졸업은 가능하다. 대가는 템플릿 파일 안의 제품 코드와 그 충돌이다(14-03). 확장 지점 자체는 09 영역 |
| 30.8 배포 판단에 필요한 최소 증거 | P | "패치 전달"은 이번에 E3가 생겼다(두 소비자). "기본 패턴 복제"는 memento-web이 문서 절차로 설치됐지만 같은 소유자다(작성자 외 조건 미충족, U-4). "새 프로젝트 시작"의 깨끗한 환경 증거는 템플릿 자체로는 없다. "선택 기능 분리"는 템플릿에서 PASS, 제품에서는 제품 사정으로 red |
### 3.2 34절 측정 — 소비자 패치 적용의 수정·충돌
충돌 수는 scratchpad clone에서 `git merge-tree`로 다시 계산했다. 나머지는 각 제품 기록과 `git diff`에서 셌다.
| 측정 | tech-log 09-29 | memento 09-29 | tech-log 09-21 |
|---|---|---|---|
| 템플릿 범위 | `ebea300` → `af3d8e6`, 359커밋 | 같음 | `5434760` → `ebea300` |
| 반영 방식 | 이력 비공유. `git merge-recursive ebea300 -- HEAD template/main` | 이력 공유. `git merge --no-ff upstream/main` | 이력 비공유 |
| 기준점 기록 | `template.lock.json`(revision, tree, materialization) | `.template-origin` 한 줄 | `template.lock.json` |
| 템플릿 변경 파일 | 824 (+68,835 / −13,207) | 824 | - |
| 그중 템플릿 작업 기록 | 105 (13%, +13,681줄): `artifacts` 63, `docs/reviews` 35, `SPEC/CLAUDE/tasks` 7 | 같음 | - |
| 양쪽이 바꾼 파일 | 90 | 50 | - |
| 충돌 경로 | **67** (내용 49, 수정/삭제 17, 이름변경/삭제 1). 기록과 같음 | **25**. 기록과 같음 | 23 (기록은 19) |
| 가져오지 않은 템플릿 경로 | 127 | 병합 뒤 70개 삭제 | - |
| 동기화 뒤 템플릿 변경 824개 중 템플릿과 다른 경로 | 213 | 125 | - |
| 템플릿 때문에 새로 red | `check:request-fanout`(FE-GATE-010·005), `build-environment-bundle`, `second-api-feature-registries`, `test:sample-removal`(더 이른 단계), `check:remediation-ledger` | `check:i18n`, `production-csp` e2e, SW e2e 2개 | - |
| 되돌림 경로 | `backup/main-before-template-af3d8e6` | 같음 | `backup/main-before-template-ebea300` |
같은 경로가 반복해서 충돌했다.
- 09-29에 두 제품이 모두 충돌한 경로: 17개.
- 세 번의 동기화에서 모두 충돌한 경로: 8개. `package.json`, `README.md`, `src/bootstrap/runtime-adapters.ts`, `src/features/installed-contract-contributions.ts`, `src/features/installed-feature-adapters.ts`, `src/features/installed-feature-runtimes.tsx`, `src/presentation/pages/home-page.tsx`, `src/presentation/routes/app-router.tsx`.
측정의 한계: 두 동기화 모두 에이전트가 수행했고, 사람 작업 시간은 기록에 없다. 충돌 수는 병합 전략과 rename 탐지 설정에 따라 조금 달라진다(09-21 기록 19 vs 재현 23).
## 4. 설계 선택 설명 (41절)
### 4.1 템플릿을 "저장소 복사 + Git으로 수정 받기"로 전달한다
1. **무엇이 필요한가.** 제품이 빌드·CI·게이트·문서까지 자기 코드로 가진다. 그러면서 템플릿의 보안·계약 수정을 계속 받는다.
2. **지킬 성질.** 제품의 수정이 보존된다. 받은 수정이 어느 템플릿 버전에서 왔는지 안다. 잘못되면 되돌린다.
3. **현재 보장.** 태그(`v0.2.0`, 원격에도 있음), CHANGELOG, `README.md:315-353` 업데이트 절, 결함 분류 규칙. 두 제품이 수정 보존·충돌 기록·게이트 비교·backup ref로 동기화를 끝냈다(E3). 보장하지 않는 것: 범위 반영 절차, 제품 수정 지점 목록, 기준점 형식 통일(14-02, 14-03).
4. **대안.** (a) 현 상태. (b) 코드 생성기(`create-*` CLI와 재생성). (c) 플랫폼 커널(`src/adapters`, `src/platform`, `src/contracts`)을 패키지로 분리하고 앱 셸만 복사. (d) (a)+(c) 혼합.
5. **비교.**
- (b)는 재생성할 때 사용자 수정을 어떻게 보존할지가 새 문제가 된다. CI 계약·게이트 스크립트가 코드 모양에 묶여 있어 생성 대상의 경계를 긋기 어렵다.
- (c)는 업데이트가 버전 올리기로 끝난다. 대신 공개 API 호환 관리(semver, deprecation)가 필요하다. 두 제품이 템플릿 파일을 고친 이유는 셸·홈·조립의 확장 지점이 없어서였다. 패키지로 가면 그 수정이 아예 막힌다. 게이트 스크립트를 패키지로 옮기기도 어렵다.
- (a)는 제품이 무엇이든 고칠 수 있다. 비용은 충돌로 나타난다(67/25).
6. **현재 조건에서의 선택.** 소비자 2개, 템플릿과 제품의 소유자가 같고, 템플릿이 빠르게 바뀐다(9일에 359커밋). 이 조건에서는 (a)를 유지할 근거가 있다. 비용은 절차 문서화(14-02)와 제품 수정 지점 축소(14-03)로 줄인다.
- 기록된 의도: `docs/superpowers/specs/2026-09-20-memento-frontend-template-bootstrap-design.md:16,30-31`가 "upstream 추적"을 고르고 1회성 스냅샷과 동기화 스크립트 안을 기각했다. 이 문서는 지워도 되는 이력 폴더에 있다.
7. **재검토 조건.** 소비자가 늘거나 소유자가 달라질 때. 확장 지점을 만든 뒤에도 같은 파일 충돌이 줄지 않을 때. 이때 (c) 커널 패키지 분리를 다시 비교한다.
### 4.2 템플릿 자신의 작업 기록을 같은 저장소에 둔다
1. **무엇이 필요한가.** 템플릿 유지자가 리뷰·계획·실행 증거를 코드와 함께 관리한다. 이 repo의 `CLAUDE.md`는 리뷰 결과를 `docs/reviews/`에 쓰도록 요구한다.
2. **지킬 성질.** 제품이 복사·동기화할 때 템플릿의 기록을 자기 계약으로 오해하지 않는다. 게이트가 읽는 파일(`docs/reviews/adapters/INVENTORY.md` 등, `docs/README.md:40-46`)은 남는다.
3. **현재 보장.** `README.md:192-209` 목록과 `tests/unit/deletable-history-documents.test.ts`(목록 5종을 읽는 코드가 없음, M3). `docs/README.md`의 3구분. 보장하지 않는 것: 실행 로그·coverage 결과·CHANGELOG의 처리, 루트의 `SPEC.md`·`tasks/`(14-01).
4. **대안.** (A) 현 상태 + README 목록 보강. (B) 생성 로그 추적 중단 + 작업 기록을 이력 폴더 한 곳으로 모음. (C) 작업 기록을 별도 브랜치나 저장소로 옮김.
5. **비교.**
- (A)는 가장 싸다. 제품은 동기화마다 계속 골라내 지운다. 이력을 공유하는 제품은 템플릿이 그 파일을 고칠 때마다 수정/삭제 충돌을 받는다.
- (B)는 동기화 때 경로 하나만 빼면 된다. 이력 폴더를 옮기는 한 번의 비용(링크, `review-ledger.json` 같은 참조)이 든다.
- (C)는 흐름이 완전히 끊긴다. 대신 리뷰 문서와 해당 커밋을 한 저장소에서 대조하는 편의를 잃는다. 이 repo의 리뷰 절차와도 맞지 않는다.
6. **선택.** (B). 로그 추적은 `.gitignore`·README 규칙과 어긋난 한 번의 커밋(`6f6c48e`)이라 되돌리는 비용이 작다. `SPEC.md`·`tasks/`를 루트에 둔 사유(`docs/README.md:72` "라운드가 쓰는 중")는 끝났다.
7. **재검토 조건.** 템플릿을 생성기나 패키지로 배포하게 되면 복사 대상을 도구가 정하므로 다시 본다.
## 5. 발견 사항 (36.3)
### 14-01 템플릿의 실행 로그와 작업 기록이 복사·동기화 대상에 섞여 있다. 실행 로그는 merge 게이트가 다시 쓴다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 30.3, 9, 20, 21, 23, 27 |
| 근거 | **실행 로그 63개가 추적된다.** `artifacts/phase5/*.log` 4, `artifacts/quality/extreme-scale-gates/*.log` 24, `artifacts/scale/{pr,main,nightly,release}/*.log` 35. 모두 `6f6c48e`(2026-09-24)에서 한 번 들어왔다. `.gitignore:11-20`은 `artifacts/`의 json·xml·txt·sarif만 무시하고 `.log`는 무시하지 않는다. `README.md:309-310`은 "generated evidence is ignored by Git"이라고 적는다. 쓰는 곳은 `scripts/scale/run-scale-profile.ts:143,153`, `scripts/verify-extreme-scale.ts:157,228`이다. 읽는 코드·테스트·설정은 없다. 참조는 이력 문서 `docs/reviews/2026-09-23-extreme-scale-acceptance.md:59` 하나다. **실험:** worktree에서 `check:scale:pr`(FE-GATE-005가 돌리는 명령, `config/ci/gates.json:217-218`)을 실행했다. PASS 뒤 `git status`에 추적 파일 3개 수정(`artifacts/scale/pr/{architecture-topology,scale-units,traffic-budgets}.log`)과 새 파일 1개(`composition-s0-s2.log`)가 생겼다. 추적 중인 `composition-s0-s1.log`는 지금 단계 이름과 맞지 않는 옛 결과다. **그 밖의 추적 산출물:** `artifacts/tests/coverage-gateway/**` 10개(커버리지 실행 결과, JS 3개 포함), `artifacts/local-preview/*.png` 3개. 둘 다 읽는 곳이 없다(`git grep`). **작업 기록:** `SPEC.md`, `tasks/`, `CLAUDE.md`는 `README.md:198-203` 목록에 있다. 하지만 루트에 그대로 있고, `docs/README.md:72`의 사유("이 라운드가 쓰는 중")는 만료됐다. 목록에 없는 것: 위 로그·coverage·preview, 그리고 제품의 CHANGELOG 경로를 차지하는 `CHANGELOG.md`. **E3:** 템플릿 변경 824개 중 105개(13%)가 작업 기록이었다(3.2절). 두 제품 모두 로그 63개와 `SPEC.md`·`tasks/`·`CLAUDE.md`를 따로 조사해서 지웠다(tech-log 기록 62-74행, memento 기록 87-102행, memento는 `git grep phase5`로 확인). CHANGELOG와 `docs/reviews`는 판단이 갈렸다(tech-log 제외, memento 유지). tech-log는 09-21 동기화에서도 coverage-gateway를 "실수로 커밋된 실행 결과"로 뺐고(09-21 기록 60행), memento는 아직 갖고 있다(memento 기록 354-355행) |
| 발생 조건 | 복사할 때, 동기화할 때마다. merge 게이트를 로컬에서 돌릴 때(`README.md:297-308`이 권장) |
| 영향 | 동기화마다 같은 조사와 삭제를 반복한다. 이력을 공유하는 제품은 템플릿이 이 파일을 다시 고칠 때 수정/삭제 충돌을 받는다. merge 게이트를 돌리면 작업 트리가 더러워져 옛 로그가 커밋에 섞이기 쉽다. 제품이 로그를 지운 뒤에는 같은 게이트가 무시되지 않는 새 로그를 만든다(두 제품 `.gitignore`에도 `*.log`가 없다). 템플릿의 리뷰 지시(`CLAUDE.md`)가 제품 루트에 남으면 제품의 에이전트가 "이 repo는 템플릿이다"라는 틀린 전제로 일한다. 데이터·보안 피해는 없다 |
| 심각도·우선순위 | Medium · P2 — 소비자 수 × 동기화 횟수만큼 반복되는 비용이다. 동작 결함은 아니다 |
| 통제·증거 | 목표 M3(지울 목록 + 읽는 코드 없음 검사). 확인: 목록 5종은 M3, 로그·coverage·CHANGELOG는 M0 · E3(worktree 실험, 두 제품 기록) |
| 확실성과 남은 가정 | 로그를 읽는 코드가 없다는 것은 `git grep`과 두 제품의 독립 조사가 일치한다. `copyReleaseEvidenceTree`(`scripts/lib/removal-fixture.ts:50-56`)가 `artifacts/`를 fixture로 복사하지만 로그를 읽지는 않는다 |
| 결정의 근거 | 확인된 사실: 로그는 `6f6c48e` 한 번만 커밋됐다. 기록된 의도: `.gitignore`와 `README.md:309-310`은 생성 증거를 추적하지 않는다는 규칙을 적는다. 로그를 추적하기로 한 기록은 찾지 못했다. 리뷰어의 추론: 규칙에서 벗어난 한 번의 커밋이다. 비교는 4.2절 |
| 이해 비용 | 제품 담당자가 동기화마다 템플릿 변경에서 "템플릿 자신의 기록"을 골라낸다. 근거는 `git grep`과 스크립트 읽기로 직접 찾아야 한다 |
| 최소 개선 방향 | ① `artifacts/**/*.log`와 `artifacts/tests/coverage-gateway/`를 `.gitignore`에 넣고 추적을 끊는다. 쓰는 곳 없는 `artifacts/local-preview/`도 지운다. ② `SPEC.md`·`tasks/`를 `docs/` 아래 이력 폴더 한 곳으로 옮긴다. ③ README 목록에 `CHANGELOG.md`(제품은 템플릿 repo의 CHANGELOG를 참조)와 `CLAUDE.md`(복사 뒤 교체)의 처리를 적는다. ④ `deletable-history-documents.test.ts`가 추적 중인 `artifacts/**/*.log`가 없는지도 확인하게 한다 |
| 대안 비교 | 4.2절: (A) 목록 보강만 / (B) 추적 중단 + 이력 폴더 통합 / (C) 별도 저장소. (B) 권장 |
| 단순화의 보존 조건 | 게이트가 읽는 파일(`docs/README.md:40-46`의 표, `artifacts/tests/a11y-manual/*.md`)은 옮기거나 지우지 않는다 |
| 비용·부작용 | 삭제 1커밋, 이동 시 참조 경로 수정. `CLAUDE.md`는 이 repo 작업에 필요하므로 남기고 목록에만 둔다 |
| 재검토 조건 | 템플릿 배포 방식이 생성기·패키지로 바뀔 때 |
| 완료 기준 | `git ls-files artifacts`에 `.gitkeep`과 게이트가 읽는 증거만 남는다. 새 worktree에서 `check:scale:pr` 뒤 `git status --short`가 비어 있다. README 목록에 복사 뒤 지울 경로가 빠짐없이 있다 |
| 검증 방법 | 새 worktree에서 `corepack pnpm check:scale:pr` → `git status --short`. 확장한 `deletable-history-documents.test.ts` |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 14-02 README의 업데이트 절차가 실제 동기화(태그까지 범위 반영)를 다루지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 30.4, 20, 9, 16, 23 |
| 근거 | `README.md:315-353`은 수정 1건을 `cherry-pick -x`로 가져오고, 안 되면 `git diff`를 손으로 적용하라고 한다. "태그까지 따라잡으면 `.template-origin`을 갱신하라"(`:344-346`)고 하지만 따라잡는 방법은 없다. **실제로는 두 제품 모두 359커밋을 한 번에 받았다.** tech-log는 이력을 공유하지 않아 `git merge-recursive ebea300 -- HEAD template/main`으로 기준점을 지정한 3-way 병합을 했다(tech-log 기록 27-30행). memento는 이력을 공유해 `git merge --no-ff upstream/main`을 했다(memento 기록 31-33행). 충돌 67/25는 다시 계산해도 같았다. 두 제품은 README에 없는 단계를 각자 똑같이 만들었다: 되돌림 ref(`backup/main-before-template-af3d8e6`), 깨끗한 worktree에서 동기화 전 게이트 기준선(tech-log 32-51행, memento 35-64행), 제외 목록, 충돌 원칙("keep the template's mechanism, keep the product's content, never invent a third state", tech-log 82-84행, memento 4-8행), 파생 기준선 재계산(tech-log 272-290행: CI 계약 기준선·registry 승인 digest·runtime-config schema baseline. memento 80행: CI 계약 기준선). `docs/operations/ci-quality-gates.md:61-71`은 새 프로젝트가 초기화할 기준선을 적지만, 동기화 뒤 digest를 텍스트로 병합하지 말고 다시 계산하라는 말은 없다. 기준점 기록도 갈렸다: memento `.template-origin` 한 줄(`af3d8e6 2026-09-29`), tech-log `template.lock.json`(`sourceRevision`, `sourceTree`, `materialization`). tech-log는 README 형식보다 자기 형식이 "더 많은 것을 말한다"며 유지했다(tech-log 기록 264-266행). 템플릿은 두 형식 모두 읽지 않는다 |
| 발생 조건 | 제품이 태그 하나 이상을 따라잡을 때. 이력을 공유하지 않는 제품은 기준점을 틀리게 주면 이미 받은 변경을 다시 적용하거나 빠뜨린다 |
| 영향 | 동기화마다 절차를 새로 설계한다. 두 제품이 같은 절차를 따로 만들었다. 기준점이 한 줄 태그만 있으면 이력 비공유 제품이 정확한 3-way 기준을 복원하기 어렵다. 파생 기준선(`gateShapeSha256`, `registrySnapshotDigest`)을 텍스트로 병합하면 어느 쪽 값도 아닌 digest가 남는다 |
| 심각도·우선순위 | Medium · P2 — 모든 동기화에 드는 비용이다. 두 제품은 결국 올바르게 끝냈다 |
| 통제·증거 | M1(1건 반영만 문서화) · E3(두 제품 기록, `git merge-tree` 재현) |
| 확실성과 남은 가정 | 절차 부재는 README 전문으로 확인했다. 두 제품 모두 같은 소유자의 에이전트가 수행했으므로, 다른 팀이 같은 품질로 해낼지는 모른다 |
| 결정의 근거 | 확인된 사실: 두 제품의 실제 경로는 범위 병합이다. 기록된 의도: memento 부트스트랩 설계(`docs/superpowers/specs/2026-09-20-memento-…:16`)가 "upstream 추적 병합"을 택했다. 그 결정이 README 절에는 반영되지 않았다. 기준점 형식은 설계 선택이다. 한 줄 형식은 사람이 읽기 쉽다. JSON 형식은 기계 검사와 tree 대조가 가능하다. 둘 다 전체 커밋 SHA를 담으면 3-way 기준으로 충분하다 |
| 이해 비용 | 동기화 담당자가 Git 병합 전략, 파생 기준선의 계산 방식, 템플릿 기록 구분을 스스로 알아내야 한다 |
| 최소 개선 방향 | README "Updating a copied project"에 "태그까지 따라잡기" 절을 둔다. ① 되돌림 ref. ② 깨끗한 worktree에서 동기화 전 merge 게이트 기준선. ③ 이력 공유: `git merge <tag>`. 비공유: `git merge-recursive <기록된 기준점> -- HEAD <tag>`. ④ 제외 목록(14-01). ⑤ 파생 기준선은 `update:ci-contract-baseline`, `update:registry-baseline`, `check-compatibility.ts --update-baseline`으로 다시 계산하고 손으로 병합하지 않는다. ⑥ 충돌 원칙 한 줄. ⑦ CHANGELOG [계약] 행 점검(14-04). ⑧ 기준선과 게이트 비교. ⑨ 기준점 기록. 기준점 형식은 하나로 정하고 전체 커밋 SHA를 담는다. 두 제품 기록이 같은 목차(시작 상태 / 가져온 것 / 가져오지 않은 것 / 충돌 / 이행 수정 / 게이트 / 후속 / 질문)를 이미 쓰므로 그 목차를 기록 양식으로 싣는다 |
| 대안 비교 | (a) 현 상태: 비용 없음, 매번 재설계. (b) 문서 절 추가: 작은 비용, 절차가 한 곳에 모인다. (c) 동기화 스크립트 제공: 재현성은 높지만 병합 전략·충돌 해결은 자동화할 수 없고 유지비가 든다. memento 부트스트랩 설계도 스크립트안을 기각했다. (b) 권장 |
| 단순화의 보존 조건 | 1건 cherry-pick 절차와 결함 분류 규칙은 그대로 둔다 |
| 비용·부작용 | README 한 절. 기준점 형식을 바꾸면 tech-log나 memento 중 한쪽이 이행한다 |
| 재검토 조건 | 소비자가 늘어 동기화를 자동화할 가치가 생길 때 (c)를 다시 본다 |
| 완료 기준 | README 절차만 보고 이력 공유·비공유 제품 각각의 다음 동기화를 수행할 수 있다. 기준점 형식이 하나다 |
| 검증 방법 | 다음 템플릿 태그에서 두 제품 중 하나가 README 절차만으로 동기화하고, 기록에 README 밖 단계가 없음을 확인한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 14-03 제품이 고치게 되는 템플릿 파일과 그 이유가 문서에 없어, 같은 파일이 동기화마다 충돌한다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 30.3, 30.4, 30.7, 3, 9, 25, 27 |
| 근거 | **반복 충돌.** 8개 경로가 세 번의 동기화(tech-log 09-21·09-29, memento 09-29)에서 모두 충돌했다(3.2절). 09-29에는 두 제품이 17개 경로에서 함께 충돌했다: 위 8개 + `src/features/installed-feature-contracts.ts`, `config/contracts/registry-change-evidence.json`, `config/contracts/registry-governance.json`, `scripts/check-design-system.ts`, `vite.config.ts`, `tests/e2e/accessibility.spec.ts`, `tests/visual/platform.visual.spec.ts`와 PNG 2개. **문서가 다루지 않는 수정 이유.** `starter-experience.md:136-147`은 기능 추가 때 `installed-*`를 고치지 않는다고 적는다. 기능 추가에는 맞다. 두 제품은 다른 이유로 이 파일을 고쳤다. memento는 `/`와 셸을 제품이 가진다: `installed-feature-contracts.ts`의 `APP_HOME` 교체 다리, `app-router.tsx`의 `ownsShell` 다리(memento 기록 108-166행). tech-log는 자기 도메인을 생성기 밖에서 조립한다: composer 5개에 직접 추가하고 `NOT_INSTALLED` 표식을 붙였다(tech-log 기록 94-104, 135-155행). `starter-experience.md:3-6`은 "page level에서 교체 가능"이라고만 한다. 템플릿 스크립트의 고정 목록도 수정 지점이다: `scripts/lib/removal-fixture.ts:25-39` `REMOVAL_FIXTURE_COPY_TARGETS`(memento가 Playwright 설정 2개를 추가, memento 기록 261행), `scripts/test-sample-removal.ts`(tech-log 두 번 연속 충돌), `scripts/check-design-system.ts`(두 제품 모두 제품 규칙 추가). 템플릿 화면에 묶인 템플릿 테스트도 수정 지점이다(30.5, `tests/component/router.test.tsx`는 tech-log에서 두 번 연속 충돌). **템플릿은 원리를 안다.** `docs/superpowers/specs/2026-09-20-memento-frontend-template-bootstrap-design.md:37,56`: "파생 프로젝트가 고치는 파일은 upstream 머지의 영구 충돌 지점이 된다". 그래서 식별자를 `package.json` name에서 파생하도록 바꿨다(`ebea300`). 같은 문서 `:35`: "삭제한 파일은 upstream 머지마다 충돌한다". 이 판단은 지워도 되는 이력 폴더에만 있다. 현재 계약인 `README.md:205-209`는 샘플 삭제를 안내하면서 이 비용을 적지 않는다. 두 제품 모두 샘플을 지우지 않았다. tech-log 09-29의 삭제 관련 충돌 18개(수정/삭제 17, 이름변경/삭제 1)는 모두 제품이 지운 샘플·예시 화면이다(`git merge-tree` 결과) |
| 발생 조건 | 제품이 홈·셸·라우터를 자기 것으로 바꾸거나, 생성기 밖에서 조립하거나, 템플릿 스크립트에 제품 규칙을 넣거나, 샘플·예시 화면을 지울 때. 그 뒤 템플릿이 같은 파일을 바꿀 때마다 |
| 영향 | 동기화마다 같은 파일에서 충돌을 푼다. 제품 코드가 템플릿 파일 안에 남아(memento 후속 1, tech-log 후속 6·7) 다음 동기화도 같은 충돌을 예약한다. 샘플 삭제를 안내대로 하면 동기화 비용이 늘고, 하지 않으면 쓰지 않는 샘플을 계속 들고 간다. 소비자가 늘면 비용이 곱해진다 |
| 심각도·우선순위 | Medium · P2 — 반복되는 유지 비용이다. 실패는 충돌로 드러나므로 조용한 결함은 아니다 |
| 통제·증거 | M0(수정 지점 목록 없음). 기능 추가 경로만 M1(`starter-experience.md:136-147`) · E3(세 번의 동기화 재현) |
| 확실성과 남은 가정 | 충돌 경로는 `git merge-tree`로 재현했다. 확장 지점이 생기면 몇 개가 사라질지는 09 영역의 판단에 달렸다 |
| 결정의 근거 | 확인된 사실: 8개 경로가 매번 충돌한다. 기록된 의도: 템플릿은 영구 충돌 지점을 줄이는 원리를 알고 한 번 적용했다(`ebea300`). 리뷰어의 추론: 그 원리가 현재 계약 문서로 옮겨지지 않아 나머지 파일에 적용되지 않았다 |
| 이해 비용 | 동기화 담당자가 충돌마다 "이 수정이 제품 고유인가, 템플릿에 요청할 확장 지점인가"를 새로 판단한다. 판단 근거가 두 제품 기록에 흩어져 있다 |
| 최소 개선 방향 | ① README 업데이트 절에 "제품이 고치게 되는 템플릿 파일" 표를 둔다: 파일, 제품이 고치는 이유(홈·셸 교체, 직접 조립, 제품 규칙), 충돌 때 원칙, 대신 요청할 확장 지점. ② `README.md:205-209`에 샘플 삭제의 동기화 비용과 대안(`NOT_INSTALLED`로 두기)을 적는다. ③ 영구 충돌 원리("제품 값은 제품 소유 파일에서 읽는다")를 이력 문서에서 `docs/architecture/`의 현재 계약으로 옮긴다. ④ 표의 8개 경로부터 제품 값을 제품 파일로 빼는 작업은 09 영역의 확장 지점 발견과 함께 다룬다 |
| 대안 비교 | (A) 문서만(표 + 샘플 삭제 비용): 비용이 작다. 충돌 수는 그대로다. (B) 문서 + 제품 값을 제품 소유 파일로 빼기(`ebea300` 방식, 예: `check-design-system`의 제품 규칙과 removal fixture 복사 목록을 설정에서 읽기, 홈·셸 확장 지점): 충돌이 준다. 템플릿 변경 비용이 크고 확장 지점 설계는 09 영역이다. (C) 기계 판독 소유 목록 + 검사: 새 도구와 유지비가 든다. 소비자 2개 규모에 과하다. (A) 먼저, (B)는 8개 경로부터 단계적으로 |
| 단순화의 보존 조건 | 기능 추가 때 중앙 catalog를 고치지 않는 현재 규칙(`starter-experience.md:145-147`)을 유지한다 |
| 비용·부작용 | (A)는 문서 한 표. 표가 낡지 않게 동기화 기록의 충돌 목록으로 갱신한다 |
| 재검토 조건 | 다음 동기화에서 표 밖의 경로가 두 제품 모두에서 충돌하면 표를 고친다. 확장 지점이 생긴 경로는 표에서 뺀다 |
| 완료 기준 | README에 표가 있고, 샘플 삭제 안내에 비용이 적혀 있다. 다음 동기화의 공통 충돌 경로가 모두 표에 있다 |
| 검증 방법 | 다음 태그에서 두 제품에 `git merge-tree`를 돌려 공통 충돌 경로를 표와 대조한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규. 확장 지점 자체는 09 영역 발견과 합칠 수 있다 |
### 14-04 CHANGELOG의 [계약] 표시가 제품 게이트를 깨는 변경을 빠뜨리고, 저장소 밖 조치에 담당과 확인 방법이 없다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 30.4, 17, 26, 9, 21 |
| 근거 | 정의는 `CHANGELOG.md:8`: "[계약] 백엔드, 배포 설정, CI, 또는 기능 코드가 함께 바뀌어야 하는 변경(헤더, 변수, 게이트, 공개 포트)". **(가) 게이트를 좁혀 제품을 깨뜨린 변경이 [계약]이 아니다.** ① 08-04 `check:i18n`이 `src/features/*/presentation`까지 검사(`411619c`) — `CHANGELOG.md:67`에 표시 없이 있다. memento는 21파일 408행이 red가 됐다(memento 기록 325행). ② F-5 `public/config.json` = local 프로필(`edf44a2`) — CHANGELOG에 없다. tech-log가 키 2개를 추가했다(tech-log 기록 345-352행). ③ 12-04 검증 package script는 게이트에 있거나 `config/ci/ungated-scripts.json`에 이유가 있어야 한다(`15a946f`) — `CHANGELOG.md:37`은 테스트 파일만 적는다. memento 4항목, tech-log 1항목. ④ 10-04 파일별 커버리지 하한(`d68e25a`, `config/testing/risk-coverage.json:182-189`) — `CHANGELOG.md:71` 표시 없음. memento가 테스트 파일 1개(케이스 14개)를 추가했다. ⑤ F-3·09-07 `second-api-feature-registries` 테스트(`606c191`) — `CHANGELOG.md:69` 표시 없음. tech-log에서 red. ⑥ 0.1.0 절(`CHANGELOG.md:80-88`)은 `ebea300..4626b73` 158커밋 중 보안 3건만 적는다. 기능·context·app 생성기와 `check:request-fanout`이 이 구간(`6f6c48e`)에 들어왔다. tech-log FE-GATE-010·005가 `check:request-fanout`으로 red다(tech-log 기록 469행). **(나) 저장소 밖 조치에 담당·확인 칸이 없다.** 표의 열은 표시·변경·영향 경로·커밋이고, 영향 경로는 템플릿 파일만 적는다. `CHANGELOG.md:24`(CORS의 `x-correlation-id`), `:25`(같은 멱등 키 재전송), `:27`(422 problem body 형식), `:28`(텔레메트리 수집기의 `build_id`·60KiB 분할)은 백엔드·게이트웨이·수집기가 할 일이다. 누가 하는지, 어떻게 확인하는지가 없다. 모든 V3 실행이 이 헤더를 보낸다(`src/adapters/http/http-execution-v3.ts:817-826`). 두 제품의 `API_BASE_URL`은 다른 origin이다(`config/runtime/local.json` `http://localhost:8080/`, staging·production `https://api.*.example.com/`). 두 제품 기록 모두 CORS 행에 대한 조치나 질문이 없다. 반면 멱등 키는 tech-log가 질문으로 남겼다(tech-log 기록 531-534행). tech-log 백엔드의 허용 헤더는 배포 변수(`APP_SECURITY_CORS_ALLOWED_HEADERS`)라 값을 확인하지 못했다 |
| 발생 조건 | 템플릿이 게이트 범위를 넓히거나 새 게이트를 추가할 때. 저장소 밖 조치가 필요한 [계약]을 제품이 동기화할 때 |
| 영향 | 제품은 게이트를 돌려 보고서야 해야 할 일을 안다. 두 제품이 템플릿 때문에 새로 red가 된 게이트·테스트는 5종·4종이다(3.2절). 저장소 밖 조치는 기록에서 빠질 수 있다. 제품이 다른 origin API로 배포하고 CORS가 `x-correlation-id`를 허용하지 않으면 V3 요청이 preflight에서 모두 거절된다. 이 경우는 High에 해당하지만 발생 여부는 확인하지 못했다 |
| 심각도·우선순위 | Medium · P2 — (가)는 게이트가 크게 실패하므로 조용하지 않다. (나)의 CORS 경로는 운영 조건이 확인되면 High로 올린다 |
| 통제·증거 | M1(표시 규칙은 있으나 적용이 빠짐) · E3(두 제품 기록, 커밋 대조) |
| 확실성과 남은 가정 | (가)의 누락은 커밋과 CHANGELOG 행을 대조해 확인했다. (나)의 운영 영향은 제품의 실제 배포 origin과 CORS 값에 달렸고, 둘 다 repo에 없다 |
| 결정의 근거 | 적용 제외 — 이미 정한 분류 규칙(`CHANGELOG.md:8`)을 행에 맞게 적용하고 칸을 하나 더하는 일이라 선택 비교가 필요하지 않다 |
| 이해 비용 | 동기화 담당자가 CHANGELOG의 "그 밖의 수정"까지 모두 읽고, 제품 게이트를 돌려 차이를 찾는다 |
| 최소 개선 방향 | ① 판정 규칙을 한 줄 더한다: "제품 코드를 고치지 않으면 제품의 게이트·빌드·런타임이 실패할 수 있는 변경은 [계약]". 게이트 범위를 넓힌 변경을 포함한다. ② [계약] 표에 "제품이 할 일 / 담당(프론트·백엔드·배포) / 확인 방법" 칸을 둔다. 예: CORS 행은 "API 게이트웨이의 `Access-Control-Allow-Headers`에 추가 / 백엔드·배포 / 다른 origin에서 V3 GET이 preflight를 통과". ③ 0.2.0의 ①~⑤를 [계약]으로 옮기고, 0.1.0 절에 생성기 토폴로지와 `check:request-fanout` 행을 더한다 |
| 대안 비교 | 적용 제외 — 규칙 보정과 칸 추가 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 릴리스마다 행 몇 개. 표가 넓어진다 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 다음 동기화 기록의 "템플릿 때문에 새로 red" 항목이 모두 CHANGELOG [계약] 행과 연결된다. 저장소 밖 조치 행마다 담당과 확인 방법이 있다 |
| 검증 방법 | 태그 전 `git log <이전 태그>..HEAD -- config/ci config/testing scripts/check-*.ts`로 게이트 변경을 뽑아 [계약] 행과 대조한다. 다음 동기화 기록과 대조한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 14-05 기준선 표가 `FEATURE_OVERRIDES`의 남은 키를 "조용히 무시된다"고 적지만, 코드는 경고한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 9, 19, 24 |
| 근거 | `docs/operations/ci-quality-gates.md:69` "없음. 남은 키는 조용히 무시된다(리뷰 09-09)". 코드: 배포 승인이 경고를 쓴다(`scripts/check-release-admission.ts:84-94`). 부트가 `feature.override.unknown` 진단을 남긴다(`src/bootstrap/runtime-adapters.ts:462-470`). `CHANGELOG.md:58`도 09-09가 진단을 남긴다고 적는다 |
| 발생 조건 | 제품이 기능을 지우고 문서를 보고 프로필을 정리할 때 |
| 영향 | 남은 키를 찾을 수 있는 신호(승인 경고, 부트 진단)를 문서 독자가 모른다. tech-log는 이 경고를 알고 키를 지웠다(tech-log 기록 130-133행) |
| 심각도·우선순위 | Low · P3 — 한 칸의 문서 불일치 |
| 통제·증거 | M1(틀린 설명) · E1 |
| 확실성과 남은 가정 | 없음 |
| 결정의 근거 | 적용 제외 — 문서를 코드에 맞추는 수정 |
| 이해 비용 | 작다 |
| 최소 개선 방향 | 검사 위치 칸을 "`check:release-admission` 경고, 부트 진단 `feature.override.unknown`"으로 고친다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 없음 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 표의 문장이 두 코드 위치를 가리킨다 |
| 검증 방법 | 문서 대조. 이 문서는 `verify:documentation` 대상이 아니다(FOLLOW-UP 14-07) |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 14-06 제품이 찾은 템플릿 결함 후보가 템플릿으로 돌아오지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 26, 30.4, 9 |
| 근거 | 분류 규칙과 신고 위치는 `README.md:348-353`에 있다. tech-log는 이 규칙대로 `check:remediation-ledger` 실패를 수정 없는 `af3d8e6` export에서 재현했다(tech-log 기록 473행). 그러나 템플릿 이슈는 0건이다(Gitea API `issues?state=all` → `[]`, `has_issues: true`). 템플릿 repo에서 두 제품의 발견을 적은 곳도 없다(`git grep -i 'tech-log\|memento'`는 2026-09-20 부트스트랩 설계만 찾는다). 제품 기록에 남은 템플릿 후보: memento 후속 2(`vite.service-worker.config.ts`에 `publicDir` 설정이 없어 `ACTIVE` worker 빌드가 `public/config.json`을 `dist/config.json` 위에 복사한다는 잠재 결함, memento 기록 202-207·345-346행), memento 후속 1(홈·셸 확장 지점 제안), memento의 SW e2e가 `null` worker를 가정(327행), tech-log 확대 표(`check:request-fanout`의 커서 페이지네이션 판정, `build-environment-bundle`의 청크 가정, 462-473행), tech-log 후속 7(context gateway 미장착) |
| 발생 조건 | 제품이 템플릿 결함이나 확장 지점 부족을 찾았을 때 |
| 영향 | 템플릿에서 고쳐지지 않으면 같은 조건의 다음 소비자가 같은 결함을 다시 찾는다. `publicDir` 후보가 사실이면, SW를 `ACTIVE`로 켠 운영 빌드의 `dist/config.json`이 local 프로필로 바뀐다. 배포 승인(FE-GATE-027)이 `APP_ENV` 불일치로 막을 가능성이 높지만 확인하지 못했다 |
| 심각도·우선순위 | Low · P3 — 전달 경로의 문제다. 후보 결함 자체의 심각도는 해당 영역이 정한다 |
| 통제·증거 | M1(신고 규칙) / 전달 단계 M0 · E3(제품 기록, Gitea API) |
| 확실성과 남은 가정 | 템플릿 소유자와 제품 소유자가 같아서 기록 밖에서 전달했을 수 있다. repo와 이슈에는 흔적이 없다 |
| 결정의 근거 | 적용 제외 — 이미 정한 신고 절차에 전달 단계를 잇는 일이다 |
| 이해 비용 | 템플릿 유지자가 소비자 repo의 동기화 기록을 직접 읽어야 결함을 안다 |
| 최소 개선 방향 | 14-02의 기록 양식에 "템플릿으로 보낼 것" 절을 두고, README 업데이트 절의 마지막 단계로 "그 절의 항목을 템플릿 이슈나 템플릿 FOLLOW-UP으로 옮긴다"를 둔다. 이번 두 기록의 후보는 이번 리뷰가 해당 영역(06, 09, 12, 13)으로 넘긴다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 동기화마다 이슈 몇 개 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 두 제품 기록의 템플릿 후보가 템플릿 이슈나 FOLLOW-UP에 있고, 각각 처리 상태가 있다 |
| 검증 방법 | 다음 동기화 뒤 Gitea 이슈 목록과 제품 기록 대조 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
## 6. FOLLOW-UP 재확인
| FOLLOW-UP 항목 | 결과 | 현재 근거 |
|---|---|---|
| 2절 P2 `readSubject` 필수화: README 업데이트 절에 이행 한 줄, 단계적 도입 정책 결정 | 유효 | README에 없다(`README.md:315-353`). 이행 설명은 `starter-experience.md:72-76`에 있고 `CHANGELOG.md:43`이 그 문서를 가리킨다. tech-log는 이 경로로 이행했다(E3, tech-log 기록 316-328행). 그래서 README 한 줄의 효과는 작다. 남은 핵심은 "선택 → 경고 → 필수" 단계 정책이 어디에도 없다는 것이다(`docs/contracts/compatibility.md`는 런타임 산출물만 다룬다) |
| 4절 P3 14-07 `verify:documentation` 검사 범위가 좁다 | 유효 | 범위 밖에서 현재 계약 문서의 drift 1건을 새로 찾았다(14-05) |
| 4절 P3 09-07 기능 제거 검증이 lint·`check:i18n`·e2e를 건너뜀 | 유효 | 검사 목록 `scripts/test-sample-removal.ts:413-428`에 셋 다 없다. memento에서 `check:i18n`이 기능 presentation 때문에 red가 된 것처럼, 이 검사들이 제품의 기능 제거에서 실패할 수 있다 |
| 1절 P2 `check:remediation-ledger` 실패 | 유효(12 영역 소관) | 다운스트림 영향이 E3로 생겼다. tech-log는 동기화 전 PASS, 동기화 뒤 FAIL이며 템플릿 원인으로 확대했다(tech-log 기록 418·473행) |
| 6절 U-3 태그 `v0.2.0` push | 해소 | Gitea API tags: `v0.2.0` → `f753669` |
| 6절 U-4 작성자 외 기능 추가 기록 | 판단 불가 | memento가 문서 절차로 `memento-web`을 설치했다(E3). 같은 소유자라 "작성자 외" 조건은 충족하지 않는다 |
| 14-04 후속(버전·CHANGELOG) | 해소 | 태그, `CHANGELOG.md`, `README.md:315-353`이 있다. 실사용에서 드러난 빈틈은 새 발견 14-02, 14-04 |
| 14-05 후속(문서 색인) | 해소 | `docs/README.md`가 3묶음으로 나눈다. `:72`의 만료된 사유는 14-01에 포함했다 |
| 14-01 샘플 제거 게이트 | 해소 | 오케스트레이터 실행 `test:sample-removal` PASS(13개 검사) |
| 14-02 CI 계약 고정 | 해소 | `config/ci/contract-baseline.json` + `update:ci-contract-baseline`. 두 제품이 이 명령으로 기준선을 다시 계산했다(E3) |
| 14-03 기능 추가 안내 | 해소 | `starter-experience.md:86-147`. memento가 이 절차로 설치했다(E3) |
| 14-06 지원 범위 표 | 해소 | `README.md:94-124` |
| 14-08 제거 JUnit | 해소 | `scripts/lib/removal-fixture.ts:218-236`, `mkdtemp` `:172-175` |
## 7. 미검증 목록
| 항목 | 이유 | 확인하려면 |
|---|---|---|
| 두 제품의 운영 API가 `x-correlation-id` preflight를 허용하는지 | 허용 헤더가 배포 변수이고 값이 repo에 없다. 두 제품의 staging·production URL은 `example.com` 자리표시자다 | 실제 배포 origin과 API 게이트웨이 CORS 설정 확인. 다른 origin에서 V3 GET preflight 실행 |
| memento가 보고한 `vite.service-worker.config.ts` `publicDir` 잠재 결함 | SW `ACTIVE` 빌드가 필요하다. 06·13 영역 소관 | worktree에서 worker selection을 `ACTIVE`로 바꾸고 `APP_PROFILE=staging`으로 빌드한 뒤 `dist/config.json` 확인 |
| 템플릿 자체의 깨끗한 환경 `install --frozen-lockfile` → `dev` | 공유 `node_modules`를 보호하려고 생략 | 새 clone이나 컨테이너에서 README 명령만 실행 |
| 나머지 제거 스크립트 3개의 이번 커밋 결과 | 전체 묶음 실행 금지(공통 지시) | 단독 환경에서 `test:optional-recipe-removal`, `test:browser-file-storage-removal`, `test:realtime-removal` |
| 작성자 외 사람이 README 절차만으로 동기화할 수 있는지 | 두 동기화 모두 같은 소유자의 에이전트가 했다 | 14-02 개선 뒤 다른 사람에게 다음 태그 동기화를 맡기고 막힌 곳을 기록 |
| 사람 기준 동기화 시간 | 두 기록에 시간이 없다 | 다음 동기화에서 단계별 소요 시간 기록 |
@@ -0,0 +1,389 @@
# 템플릿 성숙도 리뷰 — 전체 종합 (2026-09-29)
> 검토일: 2026-09-29 · 기준: `main` / `af3d8e6`(태그 `v0.2.0` + docs 커밋 1개). 워킹트리에는 리뷰 가이드 문서 2개의 미커밋 변경만 있다. 코드는 `af3d8e6`과 같다.
>
> 기준 문서: [`TEMPLATE-MATURITY-REVIEW-GUIDE.md`](../TEMPLATE-MATURITY-REVIEW-GUIDE.md)(2026-09-28 보강판), [`TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md`](../TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md)
>
> 범위: repo 전체를 지난 리뷰와 같은 14개 영역으로 나눴다. 영역별 리뷰 에이전트가 병렬로 읽었고, 이 문서는 그 결과를 오케스트레이터가 모은 것이다. 이번 라운드는 템플릿을 실제 제품 두 곳(`tech-log-frontend`, `memento-frontend`)에 적용한 기록을 증거로 함께 썼다.
>
> 이 리뷰에서 코드는 수정하지 않았다.
## 1. 사용 결정 (36.5-1)
전체 판정: **조건부 사용 가능.** 샘플을 두고 조회 화면 위주로 시작하고, 인증이 필요한 API만 쓰고, Service Worker·realtime을 켜지 않는 용도에 한한다.
지난 라운드의 차단 항목은 모두 풀렸다. 새로 막힌 곳은 대부분 "기본 구성 밖으로 한 걸음 나가는 순간"이다. 공개 API를 쓰거나, SW를 켜거나, 한 언어만 쓰거나, 제품 홈을 두는 경우다.
| 용도 | 결정 | 막는 항목 |
|---|---|---|
| 샘플을 두고 기능 1개로 시작, 인증이 필요한 조회 위주 | 조건부 사용 가능 | 없음. 쓰기를 복제하면 아래 행 참고 |
| 공개(`ANONYMOUS`) API를 쓰는 제품 | 사용 보류 | 09-01 |
| 쓰기(command) 샘플을 "결과 불명 처리" 예제로 복제 | 사용 보류 | 03-01, 03-03 |
| API가 다른 origin에 있는 배포 | 조건부 사용 가능 | 03-02(백엔드 CORS가 `x-correlation-id`를 허용하는지 먼저 확인) |
| Service Worker를 `ACTIVE`로 켜서 릴리스 | 사용 보류 | 06-01, 06-04 |
| 하위 경로(`/app/`) 배포 | 사용 보류 | 06-02, 13-02, 13-06, 08-08 |
| opt-in realtime(SSE)을 운영에 조립 | 사용 보류 | 04-01, 04-02 |
| opt-in OPFS·Cache Storage를 계정 삭제 보장에 사용 | 조건부 사용 가능 | 05-01, 05-02, 02-01 |
| 한 언어만 쓰는 제품 | 조건부 사용 가능 | 08-01, 08-02(템플릿 파일을 고쳐야 게이트가 통과) |
| 제품 홈·제품 레이아웃·제품 capability가 필요한 제품 | 조건부 사용 가능 | 09-02, 09-03, 14-03(템플릿 소유 파일을 고치게 되고, 동기화마다 충돌) |
| 이 repo의 CI를 머지 차단 장치로 믿기 | 사용 보류 | U-1(Actions 꺼짐), 11-01, 10-01 |
opt-in 런타임(realtime, OPFS, Cache Storage, Web Push, browser-transfer)은 기본 구성에 조립돼 있지 않다. 그래서 이 런타임들의 결함은 **기능을 켜는 다운스트림에서만** 나타난다. 두 제품이 이번에 겪은 문제 중 06-01(memento)과 09-01(tech-log)이 이 경우다. 두 제품은 각자 제품 쪽에서 막아 두었다.
## 2. 차단 항목 (P1)
같은 결함이 두 영역에서 나온 것은 하나로 합쳤다(9.3절). 심각도는 가이드 35.2절 기준이다. High 4건은 모두 오케스트레이터가 코드에서 다시 확인했다(9.2절).
**실제 사용자·데이터 피해로 이어지는 것**
| ID | 심각도 | 내용 | 재확인 |
|---|---|---|---|
| [09-01](09-app-core.md) | High | 공개 API(`ANONYMOUS` 인증 프로필)를 부르는 요청이 로그인 여부와 관계없이 전송되지 않는다. 조립 루트의 `attachCredentials`가 요청의 인증 프로필을 보지 않고 세션 상태만 본다. 로그아웃이면 `UNAUTHENTICATED`, 로그인이면 허용되지 않은 헤더로 거절된다. tech-log는 공개 화면 전체가 오류 화면이 되어 제품 쪽에서 고쳤다. | 코드 확인 + 에이전트 변이 실험(fetch 0회) |
| [03-01](03-adapters-http-state.md) | High | 결과 불명 쓰기를 같은 멱등 키로 다시 보냈을 때 서버가 "같은 키 처리 중" 409를 주면, 샘플 분류기가 모든 409를 `NOT_APPLIED`로 판정한다. 화면은 "충돌"로 바뀌고 다음 저장은 새 키로 나간다. 첫 요청이 끝나면 같은 리소스가 두 번 생긴다. 짝 백엔드 템플릿은 실제로 이 상황에 409(`IDEMPOTENT_IN_FLIGHT`)를 준다. | 코드 확인 + 에이전트 재현(키 `[K, K, K′]`) |
| [04-01](04-adapters-realtime.md) | High | SSE 연결 중 서버가 죽거나 연결이 끊기면 SSE 어댑터가 이를 `OFFLINE`으로 보고한다. 재연결 코드는 "새 online 이벤트"를 기다린다. 브라우저 네트워크는 정상이라 그 이벤트가 오지 않는다. 그래서 재시도도 종료도 없이 영원히 멈춘다. 에이전트가 시험한 2줄 수정은 기존 재연결 테스트 36건을 모두 통과했다. 이 동작을 막는 테스트가 없다는 뜻이다. | 코드 확인 + 에이전트 재현(가짜 시계·fetch). 실제 브라우저·SSE 서버는 미검증 |
| [06-01](06-adapters-service-worker-push.md) (= 13-01) | High | SW를 `ACTIVE`로 켜면 SW용 두 번째 Vite 빌드가 `public/`을 다시 복사한다. 그러면 프로필로 만든 `dist/config.json`이 `public/config.json`(local, demo, `localhost:8080`)으로 덮어써진다. 빌드와 `verify-release`는 통과한다. release admission만 거절한다. 결과적으로 SW를 켠 제품은 릴리스를 만들 수 없다. `/app/` 빌드는 부팅하지 못한다. memento는 `publicDir: false`로 막아 두었다. | 코드 확인 + 에이전트 재현(빌드·admission·브라우저 부팅) |
**템플릿을 제품에 적용할 때 매번 드는 비용**
| ID | 심각도 | 내용 |
|---|---|---|
| [09-02](09-app-core.md) | Medium | 제품 capability, 세션 밖 자격증명(CSRF 쿠키·BFF), 제품 런타임 설정을 넣을 자리가 없다. 두 제품 모두 `src/bootstrap/runtime-adapters.ts`를 직접 고쳤다(memento +61줄, tech-log +118줄). 템플릿도 같은 기간에 이 파일을 15커밋 고쳤다. |
| [09-03](09-app-core.md) | Medium | 라우터가 `AppShell` 한 틀과 플랫폼 `APP_HOME`을 고정한다. 기능이 `APP_HOME`을 선언하면 조립에서 throw한다. 다른 id로 `/`를 선언하면 오류 없이 플랫폼 홈에 가려진다. memento는 라우터와 조립 카탈로그에 우회 코드를 넣었다. tech-log는 라우터를 통째로 바꿨다. |
| [08-01](08-presentation.md) | Medium | 제품이 지원 locale을 선언할 곳이 없다. 목록이 다섯 곳에 고정돼 있고 en-US가 필수다. 한 언어 제품은 가짜 번역을 만들거나 템플릿 파일을 고쳐야 한다. |
**검증 장치가 믿을 수 없게 동작하는 것**
| ID | 심각도 | 내용 | 재확인 |
|---|---|---|---|
| [11-01](11-tests-browser-release-scale.md) | Medium(조정) | merge 게이트 FE-GATE-013(security)의 첫 명령 `test:system`이 main에서 항상 실패한다. 13-04 수정(`839205c`) 뒤로 스크립트는 `…verification (current): PASS`를 출력하는데, 테스트는 옛 문자열 `…verification: PASS`를 기대한다. | 메인 repo에서 `test:system` 실행 → 2 failed / 110 passed. 그중 1건이 이것이다 |
| [10-01](10-tests-fast-layers.md) | Medium | 빠른 계층의 머지 게이트에 실행 속도에 기대는 테스트가 남아 있다. 2코어 조건에서 FOLLOW-UP 3절의 테스트 3개와 `router.test.tsx`, `extreme-scale-registry.test.ts`가 거짓으로 실패했다. | 에이전트 재현(`taskset` 2코어) |
## 3. 확인된 강점 (36.5-2)
- **지난 라운드의 수정이 유지되고 회귀가 없다.** 14개 영역 모두 지난 발견의 수정을 현재 코드에서 다시 확인했다. 수정을 되돌리는 변이도 테스트가 잡았다.
- 04: 18/18, 10: 11/12, 01: 12/13, 05: M1~M7 전부, 06: 전부
- 02: 수정한 규칙 12개 전부
- 지난번에 살아남던 변이 7종(01-04, 02-02, 02-08, 04-06, 06-04, 07-04, 07-05)도 이제 잡힌다(10).
- **게이트 결과가 좋아졌다.** 13개 게이트 중 12개가 통과했다(9.1절). 지난 라운드에 빨간색이던 `test:sample-removal`도 통과했다.
- 테스트 파일 327개 중 321개가 게이트에 속한다. 나머지 6개는 이유와 함께 제외 목록에 있다(10).
- 깨끗한 체크아웃에서도 빠른 계층이 통과한다(10).
- **다중 방어가 실제로 동작했다.** 06-01이 만든 잘못된 설정을 release admission이 거절했다(06, 13). 설정 결함이 production으로 가는 경로를 다른 게이트가 막는 것을 확인했다.
- **결과 불명 쓰기의 기본 경로가 동작한다.** 응답을 잃은 저장은 같은 멱등 키로 다시 보낸다. 브라우저에서 키가 같은 것을 확인했다(08). 폼 실패는 재로그인·권한 없음·나중에 재시도로 나뉜다(08). 남은 빈틈은 409 한 경우다(03-01).
- **`readSubject` 필수화는 안전하다.** subject가 없으면 닫힘 방향으로 동작하고, 경고 소음도 작다(03). 현 상태 유지가 맞다.
- **캐시·저장소 격리가 여러 겹이다.**
- 사용자 응답이 공개 캐시에 들어가는 경로를 막는다(02).
- 캐시 교체는 검증 뒤에만 성공을 말한다(02).
- SW 설치는 개수·크기·해시를 모두 검증한다(06).
- **kernel(`src/adapters/platform/`)에 정책이 쌓이지 않았다.** 파일 집합이 지난 리뷰와 같다. 교차 import를 넣으면 `check:architecture`가 잡는다(05). 현 상태 유지가 맞다.
- **realtime 재연결 수정이 여러 조건에서 동작한다.** 오래 열린 연결의 offline 깜빡임, 같은 틱의 offline/online, 12번 연속 세션에서 모두 재연결했다(04). 남은 빈틈은 SSE 서버 다운 한 경우다(04-01).
## 4. 반복되는 원인 (36.5-4)
고유 발견 89건은 다섯 원인으로 모인다. 고칠 때 원인 단위로 보는 편이 싸다.
1. **제품이 템플릿 소유 파일을 고쳐야 한다(확장 지점 부족).** 이번 라운드의 가장 큰 발견이다.
- 제품의 흔한 요구에 넣을 자리가 없다. 홈 라우트·레이아웃(09-03), 제품 capability·자격증명(09-02), 생성기 밖 조립(09-04), 지원 locale(08-01), 문구 파라미터(08-03), 오프라인 셸(06-03), 라우트 추가 시 governance 수정(07-03), journal DB 이름(05-10), 폰트·CSP(08-07, 13-04)가 여기 해당한다.
- 검사도 제품 정책으로 바꿀 수 없다(08-02).
- 플랫폼 테스트가 제품이 지울 화면에 묶여 있다(10-02).
- 이 문제는 두 제품의 동기화 비용으로 드러났다. 충돌은 tech-log 67경로, memento 25경로였다. 8개 경로는 세 번의 동기화에서 모두 충돌했다(14-03).
2. **선언과 실제 동작이 다르다.**
- 포트 표와 recovery가 다르다(01-01).
- CHANGELOG 행이 틀렸다(02-03, 04-05, 07-07). 게이트를 좁힌 변경을 [계약]으로 표시하지 않았다(14-04).
- 문서가 코드와 다르다(05-08, 07-03, 13-09, 14-05). 레시피 설명이 SW 계약과 다르다(06-03).
3. **실패를 한 단계에서 잘못 분류해 복구 경로가 닫힌다.**
- 409(처리 중)를 "적용 안 됨"으로 본다(03-01).
- 서버 다운을 "offline"으로 본다(04-01).
- 시간 초과를 "입력 거절"로 본다(03-05).
- 재시도 가능한 실패에 "할 일 없음"을 붙인다(01-01).
- 건너뛴 purge를 "완료"로 보고한다(05-02).
- High 4건 중 2건이 여기다.
4. **게이트가 실제 위험을 놓치거나 거짓으로 실패한다.**
- 항상 실패하는 merge 게이트(11-01), 부하 의존 테스트(10-01, 11-06), 판정이 뒤집히는 성능 게이트(11-04)가 있다.
- 어떤 입력으로도 통과할 수 없는 drill이 있다(11-02).
- 오탐과 미탐이 함께 있는 fanout 검사(12-01), 한글만 보는 i18n 검사(08-02), feature 폴더 우회(12-03)가 있다.
- 레지스트리 분류기가 과잉 판정과 과소 판정을 함께 한다(07-01, 07-02). zod facade 우회도 있다(07-06).
- 이 게이트들은 CI가 꺼져 있어(U-1) 아직 아무것도 막지 않는다. CI를 켜면 곧바로 드러난다.
5. **opt-in 경로는 켜 봐야 드러난다.**
- SW `ACTIVE`(06-01, 06-02, 06-04, 06-05), 하위 경로(13-02, 13-06, 08-08), SSE(04-01, 04-02)가 여기 해당한다.
- 템플릿 자신의 게이트는 기본 구성(SW `null`, 루트 경로)만 돌린다.
- 선택 기능을 켜야 재현되는 결함을 누가 맡는지도 정해져 있지 않다(13-10).
## 5. 결정이 필요한 것
| 항목 | 선택지 | 권고 | 승인자 |
|---|---|---|---|
| 확장 지점의 범위 (4절 원인 1) | (가) 템플릿이 확장 지점을 연다. (나) 제품이 템플릿 파일을 고치는 것을 공식 경로로 두고, 고칠 파일과 병합 방법을 문서화한다(14-03) | 세 번 모두 충돌한 파일부터 (가)를 적용한다. 예: 제품 홈·레이아웃(09-03), 제품 capability·자격증명(09-02), 지원 locale(08-01). 나머지는 (나)로 둔다. 효과는 다음 동기화의 충돌 수로 잰다 | 템플릿 소유자 |
| 03-01 수정 위치 | (가) 프론트 분류기가 problem code로 409를 나눈다(처리 중이면 결과 불명 유지). (나) 백엔드 계약 §6에 "처리 중" 응답 status를 정한다 | 둘 다 한다. 프론트는 모르는 409를 `MAYBE_APPLIED`로 본다 | 템플릿 소유자, 백엔드 템플릿 소유자 |
| 03-02 `x-correlation-id` | (가) 필수를 유지하고, 배포 체크리스트와 CORS 거절 진단을 추가한다. (나) 설정으로 끌 수 있게 한다 | (가). 동기화 기록 양식에 "백엔드 작업" 칸을 둔다(14-04) | 템플릿 소유자 |
| 12-01 fanout 검사 | (가) 규칙을 유지하고, 실패 메시지에 예외 방법을 적고, 커서 페이지네이션 허용 fixture를 추가한다. (나) 요청 사이 의존을 분석하도록 규칙을 고친다 | (가). 미탐 7종은 별도 개선으로 둔다 | 템플릿 소유자 |
| `check:remediation-ledger` (FOLLOW-UP P2) | 원장을 현재 코드에 맞춘다 / 검사를 없앤다 | 지난 라운드와 같은 결정이 남아 있다. tech-log도 같은 이유로 실패한다 | 템플릿 소유자 |
| 02-06 cross-context kernel 예외 | 타입 2개를 `src/contracts/`로 옮기고 파일 단위 예외를 지운다 / 유지한다 | 옮기는 실험이 모든 게이트를 통과했다(02). 12-07 때 정한 사항이라 재결정이 필요하다 | 템플릿 소유자 |
| 전체 리뷰 게이트 목록 (9.4절) | 루트 `CLAUDE.md` 2단계 목록에 `test:system`을 추가한다 | 추가한다. 이번 11-01은 이 목록 밖에서 나왔다 | 템플릿 소유자 |
## 6. 미검증 (36.5-5)
| 무엇 | 왜 | 확인하려면 |
|---|---|---|
| CI 러너에서의 실제 결과(FE-GATE-005~008·013·026·027, production 단계) | 세 repo 모두 Actions가 꺼져 있다(U-1). branch protection은 토큰 없이는 읽을 수 없다(401/403) | runner 1대와 PR 1건의 실행 기록 |
| 04-01을 실제 브라우저·SSE 서버에서 재현 | 가짜 시계·fetch로만 재현했다 | 로컬 SSE 서버를 띄우고 Playwright로 서버를 재시작 |
| 두 제품의 운영 CORS가 `x-correlation-id`를 허용하는지 | 허용 헤더가 배포 변수라 repo에 값이 없다. staging·production URL이 자리표시자다 | staging에 preflight 요청 |
| Firefox·WebKit | 대부분 영역이 chromium만 돌렸다. 01·02·06은 3엔진을 돌렸다 | 3엔진 `test:e2e`, `test:browser-capabilities` |
| 실제 호스팅·CDN 헤더, 하위 경로 live probe | provider가 정해지지 않았다 | 정적 서버에 `/app/`으로 배포한 뒤 `HOSTING_BASE_URL` 지정 |
| 여러 탭 시나리오(같은 uploadKey, purge와 덮어쓰기, 결과 불명 쓰기, 계정 전환 뒤 무효화 hint) | 단위 대역과 Node Web Locks로만 재현했다 | 두 컨텍스트 Playwright e2e |
| 실제 quota 초과·저장소 손상, 2 GiB 객체 검증 시간 | 제어할 환경이 없다 | quota를 줄인 프로필, 저사양 기기 측정 |
| 스크린리더 발표, 수동 접근성 서명(U-2) | 도구 없음 | NVDA·VoiceOver 검토 |
| 확장 지점 제안(09-02·09-03)이 실제로 동기화 충돌을 줄이는지 | 설계 제안이다 | 구현 뒤 두 제품에 한 번 이식하고, 템플릿 파일 diff가 0이 되는지 본다 |
| 작성자 외 사람이 README 절차만으로 동기화할 수 있는지 | 두 동기화 모두 같은 소유자의 에이전트가 했다 | 14-02 개선 뒤 다른 사람에게 다음 태그 동기화를 맡긴다 |
| 조용한 호스트에서 lab 성능(11-04)과 cgroup 테스트(11-06) | 13개 에이전트가 동시에 돌아 부하 평균이 16~36이었다 | 부하 없는 기계에서 5~10회 |
## 7. 개선 순서 (36.5-6)
사용자 계획은 "템플릿을 먼저 고치고 두 제품에 다시 반영한다"이다. 그 순서에 맞춘다.
| 단계 | 항목 | 이유 | 최소 변경 | 완료 기준 |
|---|---|---|---|---|
| 1 | 09-01, 03-01, 04-01, 06-01, 11-01 | High와 P1이고 수정이 작다. 09-01과 06-01은 제품이 이미 제품 쪽에서 막아 두었다. 템플릿이 고치면 다음 동기화에서 제품 패치를 지울 수 있다 | 각 영역 문서의 최소 개선 방향 | 각 문서의 완료 기준. 04-01은 막는 테스트를 함께 넣는다 |
| 2 | 09-02, 09-03, 09-04, 08-01, 08-02, 08-03, 07-03, 06-03, 10-02, 14-03 | 제품에 다시 반영하기 **전에** 해야 효과가 있다. 확장 지점 없이 다시 반영하면 같은 파일에서 또 충돌한다 | 5절 첫 행 결정 뒤, 충돌이 반복된 파일부터 | 두 제품의 다음 동기화에서 이 파일들의 충돌이 사라진다 |
| 3 | 두 제품에 재반영 | 1·2단계 결과를 받는다 | 지난 동기화 기록(`docs/operations/template-sync-2026-09-29.md`)의 방식 그대로 | 제품 쪽 우회 패치(tech-log 09-01, memento 06-01·09-03)를 지우고도 게이트가 통과한다 |
| 4 | 10-01, 11-06, 11-04, 12-04, 12-01, U-1 | CI를 켜기 전에 해야 한다. 켜는 순간 무작위로 머지를 막는다 | 각 문서 | 2코어 러너에서 빠른 계층을 20회 돌려 실패 0 |
| 5 | 14-01, 14-02, 14-04, 03-02, 07-04 | 다음 동기화의 비용과 백엔드 누락을 줄인다 | 업데이트 절차와 CHANGELOG 양식 | 다음 동기화 기록에 백엔드 작업 칸이 채워진다 |
| 6 | 05-01, 05-02, 02-01, 06-02, 06-04, 06-05, 13-02, 04-02, 01-01 | opt-in 런타임을 조립하기 전에 고친다 | 각 문서 | 각 문서 |
## 8. 재검토 조건 (36.5-7)
- 2단계의 확장 지점을 만든 뒤, 두 제품의 다음 동기화에서 충돌 경로 수를 이번(67, 25)과 비교한다.
- CI(U-1)를 켠 뒤에는 4절 원인 4의 게이트들을 실제 러너 결과로 다시 판정한다.
- SW·realtime·OPFS를 실제로 조립하는 제품이 생기면 해당 영역을 그 제품 기준으로 다시 본다.
- 백엔드 템플릿의 멱등·에러 계약이 바뀌면 03-01·03-03을 다시 본다.
- 템플릿이 locale 목록이나 i18n 검사를 바꾸면 08-01·08-02를 다시 본다.
- 초기 JS 예산 여유(현재 1,319 bytes, 기능 하나당 약 +3KB)를 넘는 기능이 들어오면 13·14번 관점을 다시 본다.
## 9. 리뷰 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 | `clean-architecture-frontend-template`, `main` / `af3d8e6`. 미커밋 변경은 리뷰 가이드 문서 2개와 이 리뷰의 산출물뿐이다 |
| 목적과 지원 실행 구성 | 프론트엔드 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + SW. SSR은 없다 |
| 필수 요구·규모·운영 목표 | 기능 수 증가 축만 목표가 있다. 요청량·SLO 목표는 없어서 연결점만 평가했다 |
| 읽은 범위 | `src/` 전체, `tests/` 전체(unit은 표본), `scripts/`, `config/`, `.gitea/`, `docs/`, `recipes/`, 루트 설정 |
| 제품 증거 | `tech-log-frontend`·`memento-frontend`의 `chore/template-sync-v0.2.0` 브랜치와 `docs/operations/template-sync-2026-09-29.md`(tech-log는 `-09-21.md`도). 읽기만 했다. 짝 백엔드 `clean-architecture-backend-template`은 03-01 근거로만 읽었다 |
| 수행한 테스트·실험 | 9.1절 게이트. 각 영역에서 대상 테스트 실행, 분리 worktree에서 변이·결함 주입, scratchpad 재현 스크립트. 01·02·06은 Playwright 3엔진, 05는 chromium·firefox, 나머지는 chromium만 |
| 확인하지 못한 범위 | 6절 |
| 이전 리뷰와 비교 | `2026-09-25-maturity-review`의 발견과 `FOLLOW-UP.md`를 현재 코드에서 다시 확인했다. 이전 실행 결과는 증거로 쓰지 않았다 |
### 9.1 게이트 실행 결과 (오케스트레이터, `af3d8e6`)
| 게이트 | 결과 |
|---|---|
| `check:architecture` | 통과 |
| `check:types` | 통과 |
| `lint` | 통과 |
| `check:adapter-inventory` | 통과 — 145파일 |
| `check:ci` | 통과 — 27 gates |
| `verify:documentation` | `PASS_SCOPED` |
| `test:unit` | 통과 — 164파일, 2349개 |
| `test:component` | 통과 — 34파일, 211개 |
| `test:integration` | 통과 — 13파일, 155개 |
| `test:contract` | 통과 — 3파일, 15개 |
| `test:runtime-schema` | 통과 — 3파일, 56개 |
| `test:sample-removal` | 통과 — 13 checks |
| `test:system` | **실패** — 2 failed / 110 passed. 1건은 11-01(기대 문자열). 1건은 11-06(부하 중 cgroup 레이스) |
| `test:realtime-removal` | 통과 — 7 base checks, runtime 의존 테스트 24개 제거 |
| `test:browser-file-storage-removal` | 통과 — 7 base checks, runtime 의존 테스트 53개 제거 |
| `test:optional-recipe-removal` | 통과 — 6 base checks |
| `check:remediation-ledger` | **실패** — 알려진 실패(FOLLOW-UP P2). `config/ci/ungated-scripts.json`에 이유와 함께 있다 |
`test:system`과 제거 드릴 3개는 루트 `CLAUDE.md`의 게이트 목록에 없다. 영역 에이전트가 11-01을 찾은 뒤, 그리고 worktree에서 돌리지 못한 영역이 있어서 오케스트레이터가 메인 repo에서 추가로 돌렸다.
### 9.2 오케스트레이터 재확인 (High 전부)
| ID | 방법 | 결과 |
|---|---|---|
| 09-01 | `http-execution-v3.ts:719-728`은 모든 operation에서 `attachCredentials`를 부르고 `authProfileId`를 넘긴다. `runtime-adapters.ts:501-531`은 `authProfileId`를 보지 않고 세션 상태만 본다(비로그인 → `UNAUTHENTICATED` `:509-511`). 로그인 상태면 세션 헤더를 붙이는데, `ANONYMOUS` 프로필은 허용 헤더가 0개다(`rest-profiles.ts:159-168`) | 확인 — 두 상태 모두 전송 전에 끝난다. 에이전트 변이 실험(fetch 0회)과 일치 |
| 06-01 (= 13-01) | `scripts/build-frontend.ts:65`이 프로필로 `dist/config.json`을 쓴 뒤 `:71`에서 SW용 `vite build`를 돌린다. `vite.service-worker.config.ts:69-82`에는 `publicDir`·`copyPublicDir` 설정이 없고 `emptyOutDir: false`다. Vite 기본값은 `public/`을 출력 폴더로 복사한다. `public/config.json`은 `APP_ENV: local`, `AUTH_MODE: demo`, `http://localhost:8080/`이다 | 확인 — 두 에이전트의 재현(빌드 exit 0, admission 거절 4건, `/app/` 부팅 실패)과 일치. 심각도는 06의 High를 따른다. 13은 admission이 막는다는 이유로 Medium을 줬지만, SW를 켠 제품이 릴리스를 만들 수 없다는 것 자체가 지원 구성의 중요한 기능 실패다(35.2) |
| 03-01 | `reference-feature-contract-contribution.ts:37-51`은 problem 종류와 관계없이 409를 `NOT_APPLIED`로 본다. `application-query.ts:583-589`는 `NOT_APPLIED`면 admission을 정리하고 conflict를 세운다. `use-app-form.ts:227-230`은 CONFLICT에서 `unknownSubmissionRef`를 비워 다음 저장이 새 제출(새 키)이 된다. 짝 백엔드 템플릿은 같은 키 처리 중에 `IDEMPOTENT_IN_FLIGHT` 409를 준다(`clean-architecture-backend-template/.../OperationalError.java:47`) | 확인 — 504 → 같은 키 재전송 → 409(처리 중) → 사용자가 다시 저장하면 새 키. 에이전트의 MSW 재현(키 `[K, K, K′]`)과 일치 |
| 04-01 | `fetch-sse-connection.ts:213-218`·`:396-400`은 fetch·reader 거절(서버 다운, 연결 reset)을 `OFFLINE`으로 보고한다. `reconnect-coordinator.ts:798`·`:994-998`은 `OFFLINE`이면 `requireOnline()`을 부르고, `:424-429`는 "지금보다 새로운 online 이벤트"를 요구한다. `:438-445`만 이 요구를 푼다. 브라우저가 계속 online이면 새 이벤트가 없어 `waitOnline`(`:455-479`)이 abort 전까지 끝나지 않는다 | 확인 — 에이전트의 가짜 clock·fetch 재현(20분 동안 시도 1회, 결과 없음)과 일치. 실제 브라우저·SSE 서버 재현은 하지 않았다 |
| 11-01 | `verify-exact-promotion-bundle.ts:78`은 항상 `(${freshness})`를 넣어 `Exact promotion bundle verification (current): PASS`를 출력한다. `ci-artifact-contract.test.ts:1259`는 `Exact promotion bundle verification: PASS`를 기대한다. `gates.json`에서 `test-system`은 FE-GATE-013의 첫 명령이다 | 확인(코드). 메인 repo `test:system` 실행 결과는 9.1절 |
### 9.3 중복 병합과 심각도 조정
같은 결함을 두 영역이 따로 적은 6쌍을 하나로 합쳤다. 앞의 ID를 대표로 쓴다. 뒤의 ID는 영역 문서에 남아 있지만 집계에서 뺐다.
| 대표 | 합친 것 | 이유 |
|---|---|---|
| 06-01 | 13-01 | 같은 원인(`vite.service-worker.config.ts`의 `publicDir` 누락). 13-01은 `build:app-only`도 같은 결과를 낸다는 근거를 더한다 |
| 08-02 | 12-02 | 같은 원인(`scripts/check-i18n.ts:12`의 한글 정규식) |
| 03-05 | 10-03 | 같은 원인(실행기가 마감을 두 번 읽음). FOLLOW-UP 3절 live-authority 간헐 실패의 원인이다 |
| 03-04 | 08-04 | 같은 결함(문의 식별자가 사용자까지 오지 않음). 03-04는 전송 쪽, 08-04는 화면 쪽 근거다 |
| 06-04 | 11-03 | 같은 원인(SW e2e 도우미의 `null` 문자열 치환) |
| 14-01 | 11-09 | 같은 결함(추적되는 실행 로그를 merge 게이트가 다시 씀) |
심각도 조정은 두 건이다.
- **06-01은 High를 유지한다.** 13-01은 release admission이 막는다는 이유로 Medium을 줬다. 그러나 SW를 켠 제품은 릴리스를 만들 수 없다. 지원 구성에서 중요한 기능이 실패하는 것이다(35.2).
- **11-01은 High에서 Medium으로 내렸다. P1은 유지한다.** 지난 라운드는 같은 성격의 10-01(새 clone에서 테스트 실패)을 같은 이유로 Medium으로 내렸다. 지금은 CI가 꺼져 있어 막히는 머지가 없고, 수정은 문자열 하나다. 다만 CI를 켜기 전에 반드시 고친다.
영역 07이 오케스트레이터의 전제 하나를 바로잡았다. "tech-log의 라우트 변경 6건이 0.2.0 분류기 때문에 막혔다"는 부분만 맞다. 0.2.0이 바꾼 것은 런타임 설정 스키마 분류기다. 레지스트리 분류기는 처음 만든 뒤로 바뀌지 않았다. 6건 중 4건은 governance가 선언한 breaking 필드이고, 2건이 07-02의 과잉 판정이다.
### 9.4 리뷰 절차에서 확인한 것
- **전체 리뷰 게이트 목록에 `test:system`이 없다.** 이 명령은 merge 게이트 FE-GATE-013의 첫 명령이다. 지난 라운드와 이번 라운드 모두 오케스트레이터가 돌리지 않았고, 11-01은 그 사이에 들어왔다. 루트 `CLAUDE.md` 2단계 목록에 추가할 것을 권한다(5절).
- **worktree에서 pnpm 스크립트를 돌리면 위험하다.** 영역 에이전트는 worktree의 `node_modules`를 메인 설치에 심볼릭 링크했다. 이 상태에서 `corepack pnpm <script>`를 부르면 pnpm이 링크를 통해 설치·삭제를 시도한다(`ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY`). 이번에는 no-TTY 가드가 막았고, 메인 `node_modules`는 그대로인 것을 여러 번 확인했다. 다음 리뷰에서는 worktree에서 `node`·`vitest`를 직접 부르고, pnpm이 필요한 드릴은 오케스트레이터가 메인 repo에서 돌린다.
- **13개 에이전트가 동시에 돌아 부하 평균이 16~36이었다.** 부하 의존 발견(10-01, 11-04, 11-06)은 이 조건에서 재현됐다. 조용한 호스트 결과는 6절 미검증에 있다.
### 9.5 영역 분할 (다음 리뷰에서 재사용)
| 번호 | 영역 | 경로 | 깊게 본 관점 | 문서 |
|---|---|---|---|---|
| 01 | browser-transfer | `src/adapters/browser-transfer/`, 포트 | 1, 5, 6, 12, 14, 17, 28 | [01](01-adapters-browser-transfer.md) |
| 02 | browser-files / cache / cross-context | `src/adapters/browser-files/`, `cache-storage/`, `cross-context-invalidation/` | 1, 5, 6, 11, 12, 15, 24 | [02](02-adapters-browser-files-cache.md) |
| 03 | HTTP·서버 상태·인증·진단 | `src/adapters/http/`, `browser-rpc/`, `query-cache/`, `auth/`, `diagnostics/`, `telemetry/` | 5, 6, 8, 12, 15, 17, 22 | [03](03-adapters-http-state.md) |
| 04 | realtime | `src/adapters/realtime/` | 6, 7, 12, 13, 14, 17 | [04](04-adapters-realtime.md) |
| 05 | 저장소·adapter kernel | `src/adapters/storage/`, `platform/`, `browser-file-storage/` | 1, 11, 12, 22, 27, 28 | [05](05-adapters-storage-kernel.md) |
| 06 | Service Worker / Web Push | `src/adapters/service-worker/`, `web-push/`, SW 빌드 설정 | 7, 12, 15, 18, 19, 28 | [06](06-adapters-service-worker-push.md) |
| 07 | contracts | `src/contracts/`, `schemas/`, `config/contracts/` | 1, 3, 17, 19, 22, 23, 24 | [07](07-contracts.md) |
| 08 | presentation | `src/presentation/` | 4, 5, 8, 14, 15, 23, 24 | [08](08-presentation.md) |
| 09 | 애플리케이션 코어·기능·조립 | `src/application/`, `features/`, `bootstrap/`, `platform/`, `apps/`, `contexts/` | 2, 3, 4, 9, 13, 22, 25, 27 | [09](09-app-core.md) |
| 10 | 테스트 — 빠른 계층 | `tests/unit`, `component`, `integration`, `contract`, `runtime-schema`, `features`, `platform`, `recipes`, `helpers`, `mocks`, `support` | 10, 12, 20, 21 | [10](10-tests-fast-layers.md) |
| 11 | 테스트 — 브라우저·릴리스·규모 | `tests/e2e`, `browser-capabilities`, `visual`, `storybook`, `release`, `scale`, `system`, `architecture`, `scripts` | 10, 13, 14, 18, 28 | [11](11-tests-browser-release-scale.md) |
| 12 | 가드레일·CI | 검사 스크립트, `.gitea/`, `config/ci`, `config/architecture`, lint·tsconfig·depcruise 설정 | 2, 16, 21, 25, 26 | [12](12-guardrails-ci.md) |
| 13 | 빌드·릴리스·설정·공급망 | 빌드·릴리스·보안 스크립트, `vite.config.ts`, `config/release·hosting·runtime·security`, `package.json`, lockfile | 15, 16, 18, 19, 26 | [13](13-build-release-supply-chain.md) |
| 14 | 템플릿 제품성·문서·DX·업데이트 전파 | `README.md`, `CHANGELOG.md`, `docs/`, `recipes/`, 제거 스크립트, 루트 추적 파일 | 9, 20, 26, 27, 30절 전체 | [14](14-template-product-docs.md) |
28개 관점은 모두 최소 한 영역에서 "깊게 본 관점"으로 배정했다. 각 영역은 28개 전부에 판정 기호와 한 줄 이유를 적었다. 영역마다 중요한 설계 선택 1~3개에 41절의 일곱 질문을 적용했다.
## 10. 28개 관점 판정 (36.2)
영역별 판정 기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가.
종합 판정은 영역 판정을 평균하지 않는다. 한 영역이라도 미충족이면 그 이유를 적는다(35.7절).
| 번호 | 관점 | 영역 01~14 | 종합 판정 | 근거와 잔여 위험 |
|---|---|---|---|---|
| 1 | 코드 성숙도 | O P P O O P O P O > > - > > | 부분 충족 | 입력 경계와 상태 전이는 강하다(01·04·05·07 O). recovery가 포트 표와 다르다(01-01). 정책을 바꾼 배포 뒤 캐시가 영구히 멈춘다(02-01). 건너뛴 purge를 완료로 보고한다(05-02). |
| 2 | 구조적 성숙도 | O P > O O O O O P > > P > > | 부분 충족 | 직접 import 위반은 `check:architecture`가 잡는다(05의 교차 import 2건 검출). feature 안의 다른 폴더를 거치면 우회된다(12-03). 생성기 밖 조립 경로가 없다(09-04). kernel 예외가 쓰임보다 넓다(02-06). |
| 3 | 변경 용이성 | O O P P P P P P X P P P P P | 미충족 | 제품의 흔한 요구(홈·레이아웃, 제품 capability, 지원 locale, 라우트 추가)에 템플릿 소유 파일을 고쳐야 한다(09-02, 09-03, 08-01, 07-03). 두 제품의 동기화 충돌이 67·25경로였다. |
| 4 | 인지 부하 | P P P P P P P P P P P P P P | 부분 충족 | 조립에 factory 6개와 같은 뜻의 값 여러 곳이 필요하다(01). locale 목록 다섯 곳(08-01), 라우트 제목 세 곳(08-06). 문서에 없는 한 줄 예외 규약(12-01). |
| 5 | 위험 가시성 | P P P P P P P P P P P P P > | 부분 충족 | 호출자가 결정에 쓰는 정보가 계약과 다르거나 없다. recovery(01-01), CORS 거절 원인(03-02), `inspect()` 비용(02-02), purge 결과(05-02). |
| 6 | 실패 성숙도 | P P P X P P O P P P O - O > | 미충족 (opt-in realtime) | SSE가 서버 다운 뒤 재시도도 종료도 없이 멈춘다(04-01). 처리 중 409가 키 보호를 푼다(03-01). 마감 경계에서 시간 초과가 입력 거절이 된다(03-05). 재시도 계층은 하나로 정리돼 있다. |
| 7 | 운영 성숙도 | O P P P P P > > P - P > > > | 부분 충족 | 관측 연결점은 있지만 sink는 다운스트림 몫이다. 운영 drill은 어떤 입력으로도 PASS할 수 없다(11-02). SLO는 템플릿 범위 밖이다. |
| 8 | 디버깅 가능성 | P P P P P P P P P P P P P O | 부분 충족 | 결과 불명·저장 실패 화면에 문의 식별자가 없다(03-04). 라우트 모듈 실패가 진단을 남기지 않는다(08-05). CORS 거절은 원인 없는 TypeError로만 보인다(03-02). |
| 9 | 유지보수 성숙도 | P P P P P P P P P P P P P P | 부분 충족 | CHANGELOG와 문서가 코드와 어긋난 곳이 여럿이다(02-03, 04-05, 07-07, 14-04, 14-05, 05-08). 갈라진 사본이 있다(05-03, 05-07, 11-07). |
| 10 | 테스트 성숙도 | P P P P P P P P P P P P P P | 부분 충족 | 변이 검출률이 높다(04 18/18, 10 11/12, 01 12/13). 부하 의존 테스트(10-01), 제품이 지울 화면에 묶인 플랫폼 테스트(10-02), 막는 테스트가 없는 규칙(04-01, 03-06, 10-04)이 남았다. |
| 11 | 데이터 성숙도 | P P - O P O > - P > - - > - | 부분 충족 | 계정 삭제 purge에 빈틈이 셋이다. 손상 행 하나가 purge 전체를 막고(05-01), 다른 탭과 겹치면 건너뛰며(05-02), 롤백·migration 실패 중에는 데이터가 남는다(05-05). |
| 12 | 동시성 성숙도 | O O P O P P - O > P O - > - | 부분 충족 | 인증 세대 fence와 탭 사이 Web Lock은 동작한다(03, 06). purge와 다른 탭의 덮어쓰기가 경합한다(05-02). |
| 13 | 확장성 | P O > P ? P P > P > P > > > | 부분 충족 | 기능 수 축: 기능 하나가 초기 JS를 약 3KB 늘리는데 예산 여유는 1,319 bytes다(13, FOLLOW-UP P1). 규모 기준선이 현재 코드와 다르고 측정 커밋 기록이 없다(11-05). |
| 14 | 성능 성숙도 | P P O P ? O - P > P P ? P > | 부분 충족 | 예산 여유가 초기 JS 1,319 B, 레시피 77·14·9 B다. lab 성능 게이트는 같은 빌드에서 판정이 뒤집힌다(11-04). |
| 15 | 보안 성숙도 | O O O O P P P P P > > O P > | 부분 충족 | CSP, 자격증명 헤더, 캐시 격리, demo 차단은 충족한다. 계정 삭제 뒤 데이터가 남는 경로(05-01), `zod/v4` facade 우회(07-06)가 있다. |
| 16 | 의존성 성숙도 | O - > O - P > > - > O P P P | 부분 충족 | lockfile·설치 정책은 동작한다. 실행하지 않는 `dependency-cruiser`가 남았다(12-05). SBOM이 deduped 노드를 development로 적는다(13-05). 설치 정책 회귀를 잡는 검사가 없다(13-08). |
| 17 | API / Contract | P P P P P P P P P P > P > P | 부분 충족 | recovery 표 불일치(01-01), `ANONYMOUS` 요청 불가(09-01), 레지스트리 분류기의 과잉·과소 판정(07-01, 07-02), 문구 파라미터가 타입에 없음(08-03). |
| 18 | 배포 성숙도 | O P > P P P > O > > P > P > | 부분 충족 | SW를 켜면 릴리스를 만들 수 없다(06-01). 하위 경로에서 SW 설치가 실패한다(06-02). `service-worker.js`의 `no-cache`가 호스팅 정책에 없다(06-05). |
| 19 | 설정 성숙도 | P P P P P X P P P P P P X P | 미충족 (SW `ACTIVE`·`.env` 입력·하위 경로 빌드) | SW `ACTIVE` 빌드가 local 설정을 싣는다(06-01). `.env*`로 준 빌드 변수를 번들과 스크립트가 다르게 읽는다(13-02). 하위 경로 소비자가 base를 따르지 않는다(06-02, 13-06). |
| 20 | 개발자 경험 | P > > P > P P P P P P P P P | 부분 충족 | 업데이트 절차가 실제 동기화를 다루지 않는다(14-02). breaking 증거를 남기는 절차가 없다(07-04). 한 줄 예외 규약이 문서에 없다(12-01). |
| 21 | Guardrail 성숙도 | P P P O P P P P P P P X P P | 미충족 (머지 시점) | 세 repo 모두 CI가 꺼져 있다(U-1). CI를 켜면 FE-GATE-013이 항상 실패하고(11-01), 빠른 계층이 부하에서 거짓으로 실패한다(10-01). 로컬 검사는 부분 충족이다. fanout 오탐·미탐(12-01), 한글만 보는 i18n(08-02), feature 폴더 우회(12-03). |
| 22 | 추상화 성숙도 | O P P P P O P O P P P P > > | 부분 충족 | kernel은 현 상태 유지가 맞다(05). 제품이 넣을 확장 지점이 부족하다(09-02, 09-03). recipe port 사본이 갈라졌다(05-03). |
| 23 | 일관성 | P P O P P P P P P P P P P P | 부분 충족 | 같은 정보를 여러 곳에 적는다. CSP 네 곳(13-04), 라우트 제목 세 곳(08-06), CI 수치 두 곳(12-04), canonical JSON 세 벌(05-07). |
| 24 | 네이밍 / 의미 | P P P P P P P P P O P P P P | 부분 충족 | `NOT_INSTALLED`가 세 가지 뜻으로 쓰인다(09-04). 건너뛴 purge를 `COMPLETED`로 보고한다(05-02). `check:i18n`의 이름과 실제 검사가 다르다(08-02). |
| 25 | 조직 확장성 | - - > - ? - P P X - > P - P | 미충족 | 두 제품이 같은 템플릿 소유 파일을 고치고, 동기화마다 같은 곳에서 충돌한다. 8개 경로가 세 번의 동기화에서 모두 충돌했다(09-02, 09-03, 14-03). |
| 26 | Ownership | P > P - ? P P ? > P P P P P | 부분 충족 | 제품이 찾은 템플릿 결함 후보가 템플릿으로 돌아오지 않는다(14-06). 예외 목록에 담당·재검토 시점이 없다(12-07). 선택 기능 결함의 책임이 정해져 있지 않다(13-10). |
| 27 | 삭제 가능성 | P O > ? P ? > > P P P P > P | 부분 충족 | 샘플 제거와 레시피 제거 드릴은 통과한다(9.1절). file-transfer 어댑터만 지우면 게이트 3개가 실패한다(01-04). 샘플을 지우면 플랫폼 검사도 함께 지워진다(10-02). |
| 28 | 회복 가능성 | P X P P P P - O P - P - P > | 미충족 (opt-in cache-storage) | 정책을 바꾼 배포 뒤 Cache Storage가 영구히 멈추고 배포마다 캐시가 쌓인다(02-01). SW 제거 2·3단계가 일부 사용자에게 워커를 남긴다(06-06). drill은 복구를 판정하지 못한다(11-02). |
집계(적용 28개 기준): 충족 0 · 부분 충족 22 · 미충족 6(3, 6, 19, 21, 25, 28) · 미검증 0 · 적용 제외 0.
미충족 6개 중 6, 19, 28은 판정 칸에 적은 범위(opt-in 런타임, SW `ACTIVE`·하위 경로 빌드)에서만 미충족이다. 21은 머지 시점(CI)에서만 미충족이다.
## 11. 발견 색인
고유 발견 89건(영역 문서의 95건에서 9.3절의 중복 6건을 뺐다): High 4 · Medium 38 · Low 47. 우선순위는 P1 9 · P2 40 · P3 40. 성격은 확인된 결함 54 · 구조적 위험 26 · 개선 제안 9다.
심각도, 우선순위, ID 순서로 정렬했다.
| ID | 심각도 | 우선 | 성격 | 관련 관점 | 내용 | 비고 |
|---|---|---|---|---|---|---|
| [03-01](03-adapters-http-state.md) | High | P1 | 확인된 결함 | 6, 12, 17, 28, 5, 4 | 같은 키 재전송이 "처리 중" 409를 받으면 샘플 분류기가 `NOT_APPLIED`로 닫아 키 보호가 풀린다 | |
| [04-01](04-adapters-realtime.md) | High | P1 | 확인된 결함 | 6, 28, 18, 7, 8, 17, 23, 24, 5, 10 | SSE 네트워크 오류가 `OFFLINE`이 되어, 브라우저가 online이면 reconnect run이 재시도도 종료도 없이 멈춘다 | |
| [06-01](06-adapters-service-worker-push.md) | High | P1 | 확인된 결함 | 19, 18, 15, 10, 21, 23 | SW를 켜면 두 번째 Vite 빌드가 `public/`을 다시 복사해 프로필의 `dist/config.json`을 local 문서로 덮어씀 | 같은 결함: [13-01](13-build-release-supply-chain.md) |
| [09-01](09-app-core.md) | High | P1 | 확인된 결함 | 17, 6, 5, 10, 3, 30.5 (HTTP 실행 쪽은 03 영역과 겹침) | 조립 루트의 자격증명 판단이 인증 프로필을 보지 않아 `ANONYMOUS` operation이 절대 전송되지 않는다 | |
| [08-01](08-presentation.md) | Medium | P1 | 확인된 결함 | 3, 19, 20, 23, 25, 14 | 제품이 지원 locale을 선언할 곳이 없어, 한 언어 제품은 가짜 번역을 만들거나 템플릿 파일을 고쳐야 한다 | |
| [09-02](09-app-core.md) | Medium | P1 | 구조적 위험 | 3, 9, 25, 22, 15, 19, 20, 13, 30.3, 30.4, 30.7 | 제품 capability·자격증명·제품 설정을 넣을 확장 지점이 없어, 두 제품 모두 `runtime-adapters.ts`를 직접 고친다 | |
| [09-03](09-app-core.md) | Medium | P1 | 구조적 위험 | 3, 2, 22, 25, 8, 23, 27, 32.4, 30.3 | 라우터 조립이 `AppShell` 한 틀과 플랫폼 홈을 고정해, 기능이 `/`나 자기 레이아웃을 가질 수 없다 | |
| [10-01](10-tests-fast-layers.md) | Medium | P1 | 확인된 결함 | 10, 12, 14, 20, 21, 8 | 빠른 계층 머지 게이트에 실행 속도에 기대는 테스트가 남아 있다 — 2코어 러너에서 거짓 실패 | |
| [11-01](11-tests-browser-release-scale.md) | Medium | P1 | 확인된 결함 | 10, 21, 26, 9 (+30.8) | `tests/system`의 기대 문자열이 13-04 뒤의 출력과 달라, merge 게이트 FE-GATE-013(security)이 main에서 항상 실패한다 | 심각도 High → Medium 조정(8.3) |
| [01-01](01-adapters-browser-transfer.md) | Medium | P2 | 확인된 결함 | 17, 5, 6, 8, 23, 24 | `upload()` 실패의 recovery가 6개 경로에서 포트 표와 다른 행동을 가리킨다 | |
| [02-01](02-adapters-browser-files-cache.md) | Medium | P2 | 확인된 결함 | 28, 11, 18, 6, 19, 5, 24, 1 | Cache Storage pointer를 현재 정책으로 검증해, 정책을 바꾼 배포나 손상 뒤에는 조회·활성화·정리가 영구히 멈춘다 | |
| [03-02](03-adapters-http-state.md) | Medium | P2 | 구조적 위험 | 17, 19, 8, 6, 26, 21 | `x-correlation-id` CORS 허용이 교차 origin 배포의 전제인데 문서 통제뿐이다 | |
| [03-03](03-adapters-http-state.md) | Medium | P2 | 구조적 위험 | 6, 5, 22, 24, 17, 21 | 결과 불명 재전송이 키 없는 명령에도 열려 있다 | |
| [03-04](03-adapters-http-state.md) | Medium | P2 | 확인된 결함 | 8, 7, 6 | 결과 불명 쓰기에 문의 식별자가 없다 | 같은 결함: [08-04](08-presentation.md) |
| [04-02](04-adapters-realtime.md) | Medium | P2 | 구조적 위험 | 20, 22, 10, 17, 4, 3 | SSE를 reconnect coordinator에 잇는 세션 bridge가 없고, 열린 SSE 세션이 coordinator를 지나는 테스트가 없다 | |
| [05-01](05-adapters-storage-kernel.md) | Medium | P2 | 확인된 결함 | 11, 28, 15, 6, 27 | OPFS journal·staging의 손상 한 건이 그 partition의 계정 삭제 purge와 authority 전체의 reconcile·GC를 멈춘다 | |
| [05-02](05-adapters-storage-kernel.md) | Medium | P2 | 확인된 결함 | 11, 12, 15, 24, 5, 8 | purge가 지우지 못한 객체를 건너뛰고도 `chunkSweep: "COMPLETED"`로 보고한다 | |
| [05-03](05-adapters-storage-kernel.md) | Medium | P2 | 확인된 결함 | 22, 23, 17, 10, 9 | recipe의 같은 이름 port·fake가 src port와 다른 계약으로 갈라져 있다 | |
| [06-02](06-adapters-service-worker-push.md) | Medium | P2 | 확인된 결함 | 19, 18, 1, 10, 7 | SW 사전 캐시 목록이 router base path를 무시해 하위 경로 배포에서 워커 설치가 항상 실패함 | |
| [06-03](06-adapters-service-worker-push.md) | Medium | P2 | 구조적 위험 | 17, 3, 20, 5, 4 (30.3, 30.7) | 레시피는 오프라인 셸을 SW 설치 조건으로 적지만, SW 계약은 이를 금지하고 제품이 켤 확장 지점도 없음 | |
| [06-04](06-adapters-service-worker-push.md) | Medium | P2 | 확인된 결함 | 10, 20, 21 (30.4) | SW e2e 도우미가 선택 `null` 줄을 문자열로 바꿔서, SW를 켠 제품에서는 update·recovery spec이 모두 멈춤 | 같은 결함: [11-03](11-tests-browser-release-scale.md) |
| [06-05](06-adapters-service-worker-push.md) | Medium | P2 | 확인된 결함 | 18, 28, 19, 21 | 설계가 호스팅 설정에 맡긴 `service-worker.js`의 `no-cache`가 호스팅 정책 파일과 live probe에 없음 | |
| [07-01](07-contracts.md) | Medium | P2 | 확인된 결함 | 17, 21, 10, 5, 9, 26 | breaking 증거가 값과 묶이지 않아, 같은 row·field의 다음 변경을 새 증거 없이 통과시킨다 | |
| [07-02](07-contracts.md) | Medium | P2 | 확인된 결함 | 17, 23, 24, 21, 20, 3 | 레지스트리 분류기가 추가 성격의 변경(nullable 전환, allowlist 확장)을 breaking으로 막고, governance의 `breakingFields` 선언을 건너뛴다 | |
| [07-03](07-contracts.md) | Medium | P2 | 확인된 결함 | 3, 20, 22, 25, 13, 30.3, 39.5 | 기능 라우트 하나를 추가해도 템플릿 소유 governance의 중앙 allowlist를 고쳐야 한다 — 문서는 고칠 필요가 없다고 한다 | |
| [07-04](07-contracts.md) | Medium | P2 | 구조적 위험 | 20, 17, 8, 26, 25, 30.3, 30.4 | 다운스트림이 breaking 증거를 남기는 절차가 안내되지 않고, 템플릿의 기준선·증거가 제품의 이력처럼 복제된다 | |
| [08-02](08-presentation.md) | Medium | P2 | 확인된 결함 | 21, 23, 24, 10, 20 | `check:i18n`이 "파일에 한글이 있는가"만 봐서, 주석은 걸고 영어 문구·접근성 이름은 놓친다 | 같은 결함: [12-02](12-guardrails-ci.md) |
| [08-03](08-presentation.md) | Medium | P2 | 확인된 결함 | 3, 5, 17, 21, 22, 23, 25 | 기능 문구의 보간 파라미터가 타입 계약에 없어, `message()`가 틀린 호출은 통과시키고 맞는 호출은 거절한다 | |
| [08-05](08-presentation.md) | Medium | P2 | 확인된 결함 | 8, 6, 10, 28 | context 라우트 모듈의 비청크 실패와 feature·context 경계의 실패가 진단을 남기지 않고, 화면에는 build id만 보인다 | |
| [09-04](09-app-core.md) | Medium | P2 | 구조적 위험 | 2, 21, 24, 27, 4, 9, 30.7 | 생성기 밖에서 조립하는 제품 도메인의 공식 경로가 없고, `NOT_INSTALLED` 표시와 조립 파일 직접 수정을 아무 검사도 구분하지 못한다 | |
| [10-02](10-tests-fast-layers.md) | Medium | P2 | 확인된 결함 | 27, 20, 10, 21, 3, 22, 30.5, 30.7 | 플랫폼 테스트가 제품이 바꾸거나 지울 콘텐츠(스타터 화면, 참조 샘플)를 대상으로 쓴다 | |
| [11-02](11-tests-browser-release-scale.md) | Medium | P2 | 구조적 위험 | 7, 18, 28, 21, 5 (+30.8) | 운영 drill은 어떤 입력으로도 PASS할 수 없어, production 단계와 field 단계가 구조적으로 막혀 있다 | |
| [11-04](11-tests-browser-release-scale.md) | Medium | P2 | 구조적 위험 | 14, 10, 21, 18 | lab 성능 게이트(FE-GATE-026)는 중앙값 판정도 같은 빌드에서 뒤집힌다 | |
| [12-01](12-guardrails-ci.md) | Medium | P2 | 확인된 결함 | 21, 10, 5, 8, 20, 24, 26, 14 | `check:request-fanout`이 요청 사이의 의존과 반복 횟수를 보지 않는다 — 제한된 커서 페이지네이션을 거부하고, helper를 거친 행별 요청은 통과시킨다 | |
| [12-03](12-guardrails-ci.md) | Medium | P2 | 확인된 결함 | 2, 21, 5, 24, 10 | feature 안의 layer 폴더 밖 폴더는 경계 규칙이 없다 — feature presentation이 `contracts/`·`hooks/` 재수출로 `src/adapters/http`에 닿아도 모든 검사가 통과한다 | |
| [12-04](12-guardrails-ci.md) | Medium | P2 | 확인된 결함 | 3, 9, 20, 27, 25, 17, 30.4 | CI 계약 크기가 기준선 파일과 테스트 상수 두 곳에 있고, 문서의 갱신 절차는 테스트 쪽을 빠뜨린다 | |
| [13-02](13-build-release-supply-chain.md) | Medium | P2 | 확인된 결함 | 19, 23, 21, 18, 20 | 빌드 변수를 `.env*` 파일로 주면 번들과 빌드 스크립트가 서로 다른 값을 쓴다 | |
| [13-03](13-build-release-supply-chain.md) | Medium | P2 | 확인된 결함 | 10, 21, 14, 3, 8 (+30.3, 30.7) | 청크 이름이 계약처럼 쓰이지만 선언돼 있지 않다 — 해시 안정성 테스트와 route 청크 매핑 | |
| [14-01](14-template-product-docs.md) | Medium | P2 | 확인된 결함 | 30.3, 9, 20, 21, 23, 27 | 템플릿의 실행 로그와 작업 기록이 복사·동기화 대상에 섞여 있다. 실행 로그는 merge 게이트가 다시 쓴다 | 같은 결함: [11-09](11-tests-browser-release-scale.md) |
| [14-02](14-template-product-docs.md) | Medium | P2 | 확인된 결함 | 30.4, 20, 9, 16, 23 | README의 업데이트 절차가 실제 동기화(태그까지 범위 반영)를 다루지 않는다 | |
| [14-03](14-template-product-docs.md) | Medium | P2 | 구조적 위험 | 30.3, 30.4, 30.7, 3, 9, 25, 27 | 제품이 고치게 되는 템플릿 파일과 그 이유가 문서에 없어, 같은 파일이 동기화마다 충돌한다 | |
| [14-04](14-template-product-docs.md) | Medium | P2 | 확인된 결함 | 30.4, 17, 26, 9, 21 | CHANGELOG의 [계약] 표시가 제품 게이트를 깨는 변경을 빠뜨리고, 저장소 밖 조치에 담당과 확인 방법이 없다 | |
| [03-05](03-adapters-http-state.md) | Low | P2 | 확인된 결함 | 6, 8, 10, 1 | 마감이 최종 불변식 검사 직전에 끝나면 시간 초과가 "입력 거절"이 된다 | 같은 결함: [10-03](10-tests-fast-layers.md) |
| [05-04](05-adapters-storage-kernel.md) | Low | P2 | 구조적 위험 | 3, 21, 14 | offline-indexeddb 레시피 예산 여유 9바이트: 이 영역의 다음 수정이 게이트에 막힌다 | |
| [08-07](08-presentation.md) | Low | P2 | 개선 제안 | 15, 19, 20 | 폰트·전역 스타일을 넣을 제품 쪽 자리와 운영 CSP에 맞는 방법이 안내돼 있지 않다 | |
| [11-05](11-tests-browser-release-scale.md) | Low | P2 | 확인된 결함 | 13, 14, 9, 24 | 기능 규모 기준선이 현재 코드와 달라졌는데, 측정 기록에 소스 커밋이 없어 알 수 없다 | |
| [11-06](11-tests-browser-release-scale.md) | Low | P2 | 구조적 위험 | 10, 8 | `tests/system`의 cgroup 테스트는 부하가 있으면 이미 끝난 프로세스를 조회하다 실패한다 | |
| [13-04](13-build-release-supply-chain.md) | Low | P2 | 구조적 위험 | 15, 21, 9, 20 (+30.2) | 운영 CSP를 넓히는 경로에 안내와 내용 검사가 없고, 같은 문자열을 4곳에서 고쳐야 한다 | |
| [13-05](13-build-release-supply-chain.md) | Low | P2 | 확인된 결함 | 16, 24 | SBOM이 `pnpm list`의 `deduped` 노드를 따라가지 않아 번들되는 전이 의존성을 development로 적는다 | |
| [01-02](01-adapters-browser-transfer.md) | Low | P3 | 확인된 결함 | 28, 6, 11, 23 | complete가 반영된 뒤 재조정 경로에서 checkpoint 삭제가 실패하면 resourceId를 버린다 | |
| [01-03](01-adapters-browser-transfer.md) | Low | P3 | 확인된 결함 | 19, 5, 14, 20 | 느린 업링크 설정이 runtime 정책과 presigned 실행기에 따로 있고, 문서는 한쪽만 바꾸라고 한다 | |
| [01-04](01-adapters-browser-transfer.md) | Low | P3 | 구조적 위험 | 27, 21, 20 (+30.4, 30.7) | file-transfer 어댑터만 지우면 게이트 3개가 실패한다 — 가드레일이 이 영역 파일 이름에 고정돼 있다 | |
| [01-05](01-adapters-browser-transfer.md) | Low | P3 | 구조적 위험 | 17, 5, 24 | `abort()` 실패의 recovery에는 호출자 행동 표가 없다 | |
| [02-02](02-adapters-browser-files-cache.md) | Low | P3 | 구조적 위험 | 5, 14, 24, 10 | `inspect()`의 비용·취소·판정 불가가 포트 계약에 드러나지 않는다 | |
| [02-03](02-adapters-browser-files-cache.md) | Low | P3 | 확인된 결함 | 17, 9 (+30.4 업데이트 전파) | CHANGELOG 0.2.0의 browser-files [계약] 행이 실제 변경 경로·대상과 다르다 | |
| [02-04](02-adapters-browser-files-cache.md) | Low | P3 | 확인된 결함 | 9, 21 | 이 영역 설계 문서의 줄 번호 참조가 다시 밀렸다 | |
| [02-05](02-adapters-browser-files-cache.md) | Low | P3 | 구조적 위험 | 10, 6, 14 | bounded download에서 lease를 만든 뒤 handoff가 실패하면 lease를 돌려주는 규칙을 테스트가 고정하지 않는다 | |
| [02-06](02-adapters-browser-files-cache.md) | Low | P3 | 개선 제안 | 2, 21, 22, 5, 26 | cross-context-invalidation kernel 예외가 실제 쓰임(타입 2개)보다 넓다 | |
| [03-06](03-adapters-http-state.md) | Low | P3 | 개선 제안 | 10, 6 | UNKNOWN 동안 identity lease를 잡는 코드를 검증하는 테스트가 없다 | |
| [04-03](04-adapters-realtime.md) | Low | P3 | 확인된 결함 | 6, 17, 19, 23 | SSE `retry:` 값 처리 규칙이 설계 5.3·6.3과 코드에서 달라, 서버가 더 긴 대기를 요구하면 오히려 더 빨리 재연결한다 | |
| [04-04](04-adapters-realtime.md) | Low | P3 | 구조적 위험 | 6, 28, 20, 5 | hidden 탭에서 heartbeat를 멈춘 조용한 WebSocket은 예산을 새로 받지 못해, 그 사이 서버가 재시작하면 재시도 없이 끝난다 | |
| [04-05](04-adapters-realtime.md) | Low | P3 | 확인된 결함 | 9, 17 | CHANGELOG [계약] 문장이 실제 예산 초기화 조건보다 넓게 말한다 | |
| [05-05](05-adapters-storage-kernel.md) | Low | P3 | 확인된 결함 | 11, 15, 17, 24 | IndexedDB 전체 삭제 경로의 적용 범위가 port·runbook 설명과 다르다 | |
| [05-06](05-adapters-storage-kernel.md) | Low | P3 | 개선 제안 | 22, 23, 15 | 한 레시피의 두 런타임이 삭제 승인 계약을 다르게 요구한다 | |
| [05-07](05-adapters-storage-kernel.md) | Low | P3 | 개선 제안 | 22, 9, 23 | kernel로 올릴 canonical JSON이 3벌로 갈라져 있다 | |
| [05-08](05-adapters-storage-kernel.md) | Low | P3 | 확인된 결함 | 22, 9, 2 | kernel 범위 설명이 실제보다 좁고 편입 기준이 한 파일에만 있다 | |
| [05-09](05-adapters-storage-kernel.md) | Low | P3 | 확인된 결함 | 19, 12 | `putIdleTimeoutMs < mutationLockWaitTimeoutMs`가 주석에만 있다 | |
| [05-10](05-adapters-storage-kernel.md) | Low | P3 | 개선 제안 | 19, 3 | OPFS journal DB 이름 접두사를 설정으로 바꿀 수 없어 제품이 소스를 고친다 | |
| [06-06](06-adapters-service-worker-push.md) | Low | P3 | 구조적 위험 | 28, 18, 26 | 제거 2·3단계는 `service-worker.js`를 내보내지 않아, 부팅을 막는 워커가 1단계 기간에 오지 않은 사용자에게 남음 | |
| [07-05](07-contracts.md) | Low | P3 | 확인된 결함 | 19, 23, 24, 9, 3, 39.5 | `ENV_REGISTRY`의 런타임 설정 행이 zod 스키마와 따로 적혀 있고, 이미 기본값·필수 여부가 다르다 | |
| [07-06](07-contracts.md) | Low | P3 | 구조적 위험 | 15, 21, 10 | zod facade 규칙이 정확히 `"zod"`만 막아서 `"zod/v4"` import가 검사를 통과한다 | |
| [07-07](07-contracts.md) | Low | P3 | 확인된 결함 | 24, 9, 17, 30.4 | CHANGELOG 0.2.0의 [계약] 행이 바뀌지 않은 레지스트리 분류기와 경로를 가리킨다 | |
| [08-06](08-presentation.md) | Low | P3 | 확인된 결함 | 23, 24, 21, 4, 10 | 라우트 제목이 계약·catalog·페이지 세 곳에 따로 있고, 샘플에서도 서로 다르며, catalog에서 빠져도 아무 검사도 실패하지 않는다 | |
| [08-08](08-presentation.md) | Low | P3 | 구조적 위험 | 17, 19, 24, 5 | 로그인 복귀 주소가 라우터 기준 경로라 base path 배포에서 앱 밖을 가리킬 수 있고, 포트 계약에 그 의미가 없다 | |
| [09-05](09-app-core.md) | Low | P3 | 개선 제안 | 9, 25, 30.3 | 제품이 고치도록 설계한 선택 파일에 템플릿 상태 설명이 같은 블록으로 섞여 있다 | |
| [10-04](10-tests-fast-layers.md) | Low | P3 | 구조적 위험 | 10, 12, 17, 15 | 실행기의 "오래된 scope의 성공 응답은 버린다"(§10.8) 마지막 검사를 어떤 테스트도 고정하지 않는다 | |
| [10-05](10-tests-fast-layers.md) | Low | P3 | 확인된 결함 | 20, 4, 21 | `test:all`("일상 개발 루프")이 CI가 돌리는 빠른 테스트 6파일을 빠뜨린다 | |
| [11-07](11-tests-browser-release-scale.md) | Low | P3 | 확인된 결함 | 9, 23, 22, 20 | 두 빌드 준비 helper가 두 벌로 갈라져, SW 쪽은 준비에 실패하면 임시 복사본을 남긴다 | |
| [11-08](11-tests-browser-release-scale.md) | Low | P3 | 확인된 결함 | 10, 21, 24, 28 | drill의 "상수 판정 금지" 테스트가 옛 모양(`true`)만 찾아, 상수 `"PASS"`를 통과시킨다 | |
| [12-05](12-guardrails-ci.md) | Low | P3 | 확인된 결함 | 16, 9, 27, 24 | 실행하지 않는 `dependency-cruiser`가 의존성에 남아 있다 | |
| [12-06](12-guardrails-ci.md) | Low | P3 | 확인된 결함 | 21, 10 | 게이트 밖 테스트 검사가 폴더 이름으로 판정해, Vitest 폴더의 `*.spec.ts`를 "게이트 안"으로 센다 | |
| [12-07](12-guardrails-ci.md) | Low | P3 | 개선 제안 | 26, 21, 23 | 게이트 예외 목록에 이유는 있지만 담당과 재검토 시점이 없다 | |
| [13-06](13-build-release-supply-chain.md) | Low | P3 | 확인된 결함 | 23, 19, 18 | 하위 경로 배포에서 base를 따르지 않는 소비자 두 곳이 남았다(13-07 잔여) | |
| [13-07](13-build-release-supply-chain.md) | Low | P3 | 구조적 위험 | 16, 23, 9 | 청크 설정이 Vite 8의 폐기 예정 별칭(`build.rollupOptions`)에 있어, `rolldownOptions`를 더하면 조용히 무시된다 | |
| [13-08](13-build-release-supply-chain.md) | Low | P3 | 구조적 위험 | 16, 21, 26 | pnpm 설치 정책이 파일에만 있고, 되돌림과 암묵 기본값을 잡는 검사가 없다 | |
| [13-09](13-build-release-supply-chain.md) | Low | P3 | 확인된 결함 | 20, 19 | README 변수 표가 staging·production의 `VITE_BUILD_ID` 필수 조건을 적지 않는다 | |
| [13-10](13-build-release-supply-chain.md) | Low | P3 | 개선 제안 | 26 (+30.4) | "선택 기능을 켜야 재현되는 템플릿 결함"의 책임이 정해져 있지 않다 | |
| [14-05](14-template-product-docs.md) | Low | P3 | 확인된 결함 | 9, 19, 24 | 기준선 표가 `FEATURE_OVERRIDES`의 남은 키를 "조용히 무시된다"고 적지만, 코드는 경고한다 | |
| [14-06](14-template-product-docs.md) | Low | P3 | 구조적 위험 | 26, 30.4, 9 | 제품이 찾은 템플릿 결함 후보가 템플릿으로 돌아오지 않는다 | |
@@ -0,0 +1,123 @@
# Template 프로젝트 성숙도 리뷰 — 실행 체크리스트
이 문서는 `TEMPLATE-MATURITY-REVIEW-GUIDE.md`의 **실행용 요약본**이다. 상세 판정 근거와 예외는 정본 가이드를 따른다. 체크리스트 자체를 별도 점수 체계로 사용하지 않는다.
## 1. 리뷰 시작 전에 고정
- 대상 저장소, 브랜치·커밋, 작업 트리 상태, 확인 시점
- 템플릿/프로젝트의 사용 목적과 지원 실행 형태
- 필수 요구, 데이터·권한 범위, 의존 시스템
- 규모 목표와 운영 목표가 있는지 여부
- 지원 기능·선택 기능·의도적 비지원 범위
- 템플릿 책임과 사용 프로젝트 책임
- 이번에 읽을 코드·설정·테스트 범위와 확인하지 못할 범위
목표가 없는 항목은 임의로 만들지 않는다. 목표가 없어서 판단할 수 없으면 `미검증` 또는 `판단 보류`로 남긴다.
## 2. 대표 경로를 먼저 따라간다
전체 파일을 균등하게 훑기 전에 실제 사용 흐름과 고위험 흐름을 선택한다.
- 정상 사용자 흐름 1개 이상
- 실패 시 피해가 큰 흐름 1개 이상
- 기능 추가·변경·삭제 흐름 1개 이상
- 필요하면 배포·복구·동시성·인증 경계 흐름
각 흐름에서 입력 → 정책 → 상태 변화 → 외부 I/O → 실패 → 사용자/운영 결과를 연결한다.
## 3. 28개 관점은 적용되는 것만 판정
- 적용 여부와 이유를 먼저 적는다.
- 목표 통제와 현재 통제를 분리한다.
- 근거 수준(E0~E4)과 통제 수준(M0~M4)을 혼동하지 않는다.
- 하나의 결함이 여러 관점에 걸리면 Finding은 하나로 두고 관련 관점만 연결한다.
- `미검증`을 완료율에서 빼지 않는다.
## 4. 먼저 찾을 고위험 문제
- 데이터 손상·권한 우회·민감정보 노출
- 결과 불명 쓰기와 잘못된 재시도·멱등성
- 동시성 경쟁·중복 처리·오래된 작업자의 쓰기
- 무제한 큐·병렬성·응답·메모리·재시도
- 배포·마이그레이션·복구 중 중간 상태
- CI/Guardrail이 있다고 문서에는 적혀 있지만 실제로 실행되지 않는 경우
## 5. 코드 품질은 “줄 수”보다 이해 부담과 보호 장치로 본다
대표 과제를 수행하면서 기록한다.
- 어디서 시작했는가?
- 반드시 알아야 하는 개념은 무엇인가?
- 이름과 실제 책임이 달라 다시 탐색한 곳은 어디인가?
- 숨은 등록 순서·전역 상태·문자열 키·설정 규약이 있는가?
- 중요한 위험과 실패 의미를 가까운 코드·타입·계약에서 찾을 수 있는가?
- 같은 사실을 annotation·descriptor·config·실행 코드에 반복한다면 각각 독립적인 역할과 불일치 검출이 있는가?
## 6. 추상화는 유지·내부화·통합·분리·제거 중에서 판단
각 추상화에 묻는다.
- 없으면 어떤 중복 지식·외부 결합·테스트 어려움이 생기는가?
- 호출자는 성공·실패·비용·수명주기를 추상화만 보고 이해할 수 있는가?
- 일반 사용자가 플랫폼 내부 개념까지 알아야 하는가?
- 더 작은 구조로 바꿨을 때 보호하던 계약을 그대로 유지할 수 있는가?
- 복잡하지만 현재 요구와 위험에 비해 정당하다면 **현 상태 유지**도 유효한 결론이다.
## 7. 중요한 설계 선택에는 Decision Explanation Test 적용
모든 한 줄에 적용하지 않는다. 객체 ownership, 공개 계약, 트랜잭션, 인가, retry/idempotency, cache, concurrency, module composition, template architecture처럼 계약·실패·유지비에 영향을 주는 선택에 적용한다.
1. 무엇이 필요한가?
2. 반드시 지킬 성질은 무엇인가?
3. 현재 코드는 어떻게 보장하는가? 무엇은 보장하지 않는가?
4. 현실적인 대안은 무엇인가?
5. 각 대안의 정확성·복잡성·성능·실패 특성·변경/운영 비용은?
6. 확인한 현재 조건에서는 왜 이 선택인가?
7. 어떤 요구·측정·규모·의존 계약이 바뀌면 선택도 달라지는가?
작성 당시 의도가 기록에 없으면 만들어내지 않는다. `작성자가 이렇게 생각했다`가 아니라 `현재 조건에서 이 선택을 유지할 근거는 ...`이라고 구분한다.
## 8. Finding 작성
필수:
- ID·제목
- 성격: 확인된 결함 / 구조적 위험 / 미검증 / 개선 제안
- 관련 관점
- 현재 근거와 발생 조건
- 영향
- 심각도와 우선순위
- 확실한 사실과 남은 가정
- 최소 개선 방향
- 비용·부작용
- 완료 기준
- 검증 방법
설계 선택·구조 변경이면 추가:
- 현재 제약과 보호할 규칙
- 이해 비용
- 현실적인 대안과 차이
- 단순화 후 보존해야 할 계약
- 재검토 조건
단순 구현 결함이면 위 설계 선택 필드는 `적용 제외` 가능하다. 빈칸 대신 적용 제외 이유를 한 문장으로 남긴다.
## 9. 제안보다 검증을 우선
- 구조적 위험은 가능한 경우 작은 변경·변이 실험으로 실제 검출 여부를 확인한다.
- 실제 DB·브라우저·CI·외부 의존성 동작이 필요한 주장은 가능한 환경에서 해당 수준까지 검증한다.
- 실행하지 못한 브라우저·CI·부하·복구 조건은 정적 근거만으로 검증 완료라고 쓰지 않는다.
- 문서의 “구현 완료” 표시는 증거가 아니라 주장으로 취급한다.
## 10. 리뷰 종료 전 확인
- 현재 사용 가능한 범위와 보류 범위를 구분했는가?
- 차단 항목과 미검증 목록이 따로 있는가?
- 가장 중요한 Finding의 재현·검출 근거가 있는가?
- 단순화 제안이 기존 안전장치를 잃지 않는가?
- 중요한 기술 선택에 대해 `요구 → invariant → 현재 구현 → 대안 → trade-off → 선택 이유 → 재검토 조건`을 설명할 수 있는가?
- 수정하지 않는 것이 최선인 구조도 그렇게 기록했는가?
- 구현자가 “무엇을 바꾸면 끝나는지”와 “어떻게 다시 검증하는지”를 알 수 있는가?
충분한 근거가 모이면 리뷰를 끝낸다. 기준을 채우기 위해 새 프레임워크·불필요한 문서·장식성 메타데이터·중복 테스트를 추가하지 않는다.
+627 -5
View File
@@ -1,13 +1,14 @@
# Template 프로젝트 성숙도 리뷰 가이드
# Template 프로젝트 성숙도 리뷰 가이드 — 상세 보강판
작성일: 2026-09-25
수정일: 2026-09-28 — 설계 의도·코드 표현력과 설계 선택 설명 검증 기준 보강
대상: Backend Template, Frontend Template, Platform Template 및 이를 사용하는 프로젝트
기반 문서: 첨부된 `TEMPLATE-MATURITY-REVIEW-GUIDE(1).md`
목적: 코드의 정확성, 변경 비용, 위험의 가시성, 운영·복구 능력을 근거로 판단하는 리뷰 기준서
이 문서는 원문의 **28개 관점과 번호를 유지**하면서 각 관점을 실제로 검토하고 판정하는 방법을 보강한 통합본이다. 원문 뒤에 체크리스트만 덧붙이지 않고, 과도하게 단정한 기준은 본문에서 바로잡았다.
실제 프로젝트의 코드는 이번 작업에서 검사하지 않았다. 아래 코드·시나리오·수치는 설명용이며, 사용 중인 템플릿에서 발견된 결함이나 측정 결과를 뜻하지 않는다. 참고한 공식 자료는 문서 끝에 정리했다. 평가 방식과 완료 기준은 이 가이드의 제안이며 공인 인증 체계가 아니다.
사용 중인 Backend·Frontend 템플릿의 현재 코드는 이 가이드 보강 작업에서 검사하지 않았다. 아래 코드·시나리오·수치는 설명용이며, 해당 템플릿에서 발견된 결함이나 측정 결과를 뜻하지 않는다. 2026-09-28에 추가한 오픈소스 사례는 GitHub 원문을 확인했으며 확인 범위와 한계를 40절에 적었다. 근거 자료는 38절에 정리했다. 평가 방식과 완료 기준은 이 가이드의 제안이며 공인 인증 체계가 아니다.
## 먼저 읽을 부분
@@ -20,6 +21,12 @@
- 심각도·성숙도·증거 수준·완료 판정: 35절
- 그대로 사용할 수 있는 리뷰 결과 양식: 36절
- 원문에서 교정한 내용과 근거 자료: 37~38절
- 설계 의도·코드 표현력과 안전한 단순화: 39절
- 인용된 오픈소스에서 확인한 사실과 비교의 한계: 40절
- 기초 코드부터 시스템 설계까지 선택의 이유를 설명하는 공통 검토 방식: 41절
- 실제 리뷰 실행 순서만 빠르게 적용할 때: 동봉된 `TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md`
2026-09-28 보강은 평가 항목을 추가하는 대신 기존 관점을 연결한다. 39절은 4·5·9·10·21·22·24번을 연결해 **“중요한 동작과 선택 이유를 이해하는 데 필요한 부담이 줄었으며, 기존의 보호 장치는 유지되는가?”**를 묻는다. 41절은 모든 관점에 적용하는 설명 방식이다. **“현재 조건에서 왜 이 선택이 타당하며, 무엇을 보장하지 못하고, 어떤 조건이면 선택이 달라지는가?”**까지 근거를 들어 답할 수 있어야 한다.
## 0. 숙련된 리뷰어가 가장 먼저 확인하는 것
@@ -52,6 +59,8 @@
합의된 목표가 없으면 “대규모 운영 준비 완료” 같은 판정은 보류한다. 그 대신 무엇까지 확인했고 어떤 전제가 비어 있는지 적는다.
기술 선택에 대한 후속 질문에는 41절의 공통 질문을 적용한다. 요구와 규칙, 현재 구현, 현실적인 대안, 비용, 선택 이유, 재검토 조건을 연결한다. 모든 선택에 긴 문서를 요구하는 것은 아니며, 현재 코드의 효과와 작성 당시의 의도는 구분한다.
### 0.2 템플릿 자체와 사용 프로젝트의 책임
| 항목 | 템플릿이 제공할 책임 | 사용 프로젝트가 결정·검증할 책임 |
@@ -167,6 +176,8 @@ TypeScript `paths`는 경로 해석을 돕는 설정이다. 그 자체를 접근
**측정 주의:** “5분 안에 못 찾으면 실패”, “파일 5개 이하면 우수” 같은 기준을 보편적으로 적용하지 않는다. 동일한 과제와 비슷한 숙련도의 사람을 기준으로 전후를 비교한다. [S1]
**설계 의도 확인:** 독자가 입력·출력·상태·부작용뿐 아니라, 중요한 분기를 지우거나 순서를 바꾸면 왜 문제가 되는지도 가까운 코드와 계약에서 설명할 수 있는지 본다. 단순 위임 뒤의 전역 규약을 계속 추적해야 한다면 파일이 짧아져도 인지 부하는 줄지 않는다. 역할별 필수 개념과 국소적 이해의 검토 방법은 39절을 따른다.
## 5. 위험 가시성 — Risk Visibility
### 판단할 것
@@ -191,6 +202,8 @@ TypeScript `paths`는 경로 해석을 돕는 설정이다. 그 자체를 접근
**개선 완료 기준:** 중요한 호출의 시간·상태·실패 계약을 가까운 위치에서 찾을 수 있고, 구현과 테스트가 그 계약을 뒷받침한다. 29절에 Backend와 Frontend 예시를 상세히 제시한다.
**가시성과 중복 선언:** 같은 위험을 어노테이션·descriptor·실행 코드에 반복해서 적는다면 각각 누가 읽고 무엇을 보장하는지 확인한다. 실행에 쓰는 정책, 독립적인 검증 기준, 단순 설명을 구분한다. 선언과 실행의 불일치를 검출할 수 없는 장식성 메타데이터는 별도의 유지 비용이다. 구체적인 판정은 39.5절을 따른다.
## 6. 실패 성숙도 — Failure Maturity
### 판단할 것
@@ -277,6 +290,8 @@ TypeScript `paths`는 경로 해석을 돕는 설정이다. 그 자체를 접근
**판정 주의:** 코드가 비슷하다고 공통화하면 서로 다른 정책의 변경 시점까지 묶일 수 있다. 반대로 같은 권한·정산 규칙이 복제되어 따로 바뀌는 것은 중복 지식의 위험이다. 무엇을 함께 바꿔야 하는지를 기준으로 판단한다.
**의사결정의 유지보수:** 현재 제약과 선택 이유를 Git 이력에서 매번 발굴해야 하는지도 본다. 과거 리뷰 번호만 남긴 주석은 이해를 돕기 어렵다. 반면 버그의 재발 조건이나 호환성 제약을 설명하는 주석과 원본 이슈·명세 링크는 유지할 이유가 있다. 주석의 수나 이력 링크의 유무로 품질을 판정하지 않는다.
## 10. 테스트 성숙도 — Test Maturity
### 판단할 것
@@ -306,6 +321,8 @@ TypeScript `paths`는 경로 해석을 돕는 설정이다. 그 자체를 접근
**판정 주의:** 같은 기능을 단위·통합·E2E에서 다룬다고 무조건 중복은 아니다. 각 계층이 서로 다른 실패를 잡는다면 가치가 있다. 반대로 같은 구현 세부사항만 반복 검증하면 유지 비용만 늘어난다. [S1]
**설계 결정을 보호하는 테스트:** 중요한 분기나 경계를 단순화한다면 그 결정이 막던 실패를 검증한다. 예를 들어 완료된 요청의 정리가 새 요청의 핸들을 지우지 않는지 확인한다. private helper 이름·정확한 호출 순서 같은 구현 세부사항을 그대로 고정하지 않고, 보호할 상태와 외부 동작을 검증한다.
## 11. 데이터 성숙도 — Data Maturity
### 판단할 것
@@ -547,6 +564,8 @@ HTTP API뿐 아니라 모듈 공개 타입, 이벤트, 설정, CLI, 생성 코
**비용 기준:** 저위험 스타일 선호 때문에 복잡한 자체 검사기를 만들지 않는다. 표준 도구로 잡을 수 있는 규칙은 표준 도구에 맡기고, 사업 규칙은 코드와 의미 있는 테스트에 둔다. 빌드 스크립트에 모든 정책을 몰아넣는 것도 인지 부하를 높인다.
**검사의 실제 효용:** 규칙을 위해 새 annotation이나 registry를 추가했다면 그것을 읽는 검사와 실제로 검출하는 위반 사례를 제시한다. 검사 통과만을 위해 같은 정보를 여러 곳에 적는 비용도 리뷰한다. 독립적인 요구 조건을 선언해 구현과 대조하는 검사는 가치가 있으므로 “중복 정보”라는 이유만으로 제거하지 않는다.
## 22. 추상화 성숙도 — Abstraction Maturity
### 판단할 것
@@ -567,6 +586,8 @@ HTTP API뿐 아니라 모듈 공개 타입, 이벤트, 설정, CLI, 생성 코
**판정 주의:** 인터페이스 하나가 외부 네트워크·권한·저장 경계를 드러낸다면 구현체가 하나여도 충분한 이유가 된다. 반대로 구현체가 여러 개라는 사실만으로 잘된 추상화가 되지는 않는다. 상이한 실패 의미를 억지로 같은 성공 타입에 맞추고 있지 않은지 본다. [S1]
**추가 완료 기준:** 추상화를 하나 줄이는 제안에는 실제 호출부의 변화, 없어지는 필수 개념, 유지해야 할 타입·실패·권한 계약을 붙인다. 제네릭 수를 줄이기 위해 `any`·강제 단언·느슨한 옵션 객체를 늘리거나, helper를 제거한 뒤 같은 정책을 여러 호출자가 구현한다면 개선으로 보지 않는다. 삭제 여부를 판단하는 질문은 39.6절에 정리했다.
## 23. 일관성 — Consistency
### 판단할 것
@@ -612,6 +633,8 @@ HTTP API뿐 아니라 모듈 공개 타입, 이벤트, 설정, CLI, 생성 코
**판정 주의:** `execute()`, `handle()` 자체가 나쁜 이름은 아니다. `CancelReservationHandler.handle()`처럼 타입이 의미를 충분히 제공할 수 있다. 이름을 길게 만드는 것보다 호출 문맥까지 읽고 판단한다.
**이름이 담을 수 없는 이유:** 이름과 타입은 동작·규칙을 표현하고, 짧은 주석은 예상 밖의 제약과 인과관계를 설명한다. 대안 비교가 길어지면 설계 기록으로 옮기고 코드 가까이에는 현재 선택의 이유와 링크를 남긴다. 모든 선택 이유를 클래스명이나 generic hierarchy로 표현하려 하지 않는다.
## 25. 조직 확장성 — Organizational Scalability
### 판단할 것
@@ -1044,6 +1067,16 @@ README·설계 문서는 **주장과 의도를 찾는 자료**다. 실제 동작
“좋다/나쁘다” 대신 어떤 용도에서 지금 사용할 수 있고, 무엇을 고쳐야 하며, 어떤 주장은 검증이 필요한지 적는다. 범위가 제한된 합격도 유효한 결과다.
### 34.10 안전성과 코드 이해를 함께 재검토한다
리팩터링 결과에서는 중요한 보호 장치가 유지됐는지와 사용·수정 과정의 부담이 줄었는지를 함께 확인한다. 대표 과제를 그대로 다시 수행해 필수 개념, 수동 동기화 지점, 실행 흐름의 이동, 오류 원인 파악이 어떻게 바뀌었는지 기록한다. 줄 수 감소만으로 완료 처리하지 않는다.
### 34.11 대표적인 선택을 후속 질문으로 검토한다
핵심 계약에 영향을 주거나 대안이 논쟁이 되는 선택을 골라 “왜 이 방식인가?”, “더 단순한 방식으로 바꾸면 무엇이 달라지는가?”, “어떤 조건이면 결론이 바뀌는가?”를 묻는다. 41절에 따라 코드·계약·검증 근거를 연결하고, 근거가 없으면 설명을 만들어 채우지 않는다.
개발자를 시험하거나 기술 지식을 과시하기 위한 절차가 아니다. 유지할 이유가 있는 코드, 실제 결함, 설명 부족, 미확인 요구를 구분해 다음 수정자가 판단할 수 있게 한다. 모든 줄에 질문표를 작성하거나 별도 CI 검사를 추가하지 않는다.
### 비교에 유용한 측정 항목
| 측정 | 활용 | 오해하지 말 것 |
@@ -1171,6 +1204,8 @@ README·설계 문서는 **주장과 의도를 찾는 자료**다. 실제 동작
기본 보고는 **관점별 목표 대비 상태, 도입·출시 차단 항목, 미검증 목록**으로 한다. 28개 관점의 단순 평균으로 인증 우회나 복구 불가를 상쇄하지 않는다.
통제 수준이 높다는 이유로 코드 이해까지 우수하다고 추론하지 않는다. “핵심 규칙은 M4로 강제되지만 일반 기능 작성자가 여러 등록 규약을 알아야 한다”는 판정도 가능하다. 이 경우 4번 인지 부하·22번 추상화의 개선이 남는다. 39·41절의 질문을 별도 점수로 중복 집계하지 않는다.
진행률이 필요하면 먼저 독립적으로 검증 가능한 세부 기준을 고정한다. 적용 항목 중 충족·부분 충족·미충족·미검증 수를 각각 보고하고, 적용 제외는 사유와 함께 분리한다. 미검증 항목을 분모에서 빼서 완료율을 높이지 않는다.
점수를 꼭 사용한다면 가중치·배점·합격 조건·미검증 처리·차단 규칙을 사전에 합의한다. 기준이 바뀌면 이전 점수와 직접 비교하지 않는다. 서로 목적이 다른 Backend와 Frontend 템플릿의 단일 점수 경쟁은 피한다.
@@ -1240,6 +1275,8 @@ README·설계 문서는 **주장과 의도를 찾는 자료**다. 실제 동작
### 36.3 발견 사항 양식
아래 필드는 모든 발견 사항을 장황한 설계 문서로 만들기 위한 것이 아니다. **단순한 구현 결함, 오탈자, 누락된 null 검사, 실행되어야 할 gate의 단순 누락처럼 선택 비교가 실질적으로 필요하지 않은 항목에는 설계 선택 관련 필드를 `적용 제외`로 둘 수 있다.** 그때는 왜 적용 제외인지 한 문장으로 적는다. 반대로 구조 변경·추상화·기술 선택·정책 변경처럼 여러 타당한 선택지가 있는 항목은 41절을 적용해 현재 선택과 대안을 비교한다.
| 필드 | 작성할 내용 |
| --- | --- |
| ID·제목 | 다른 항목과 구분되는 ID와 구체적인 문제 |
@@ -1250,13 +1287,20 @@ README·설계 문서는 **주장과 의도를 찾는 자료**다. 실제 동작
| 영향 | 어떤 사용자·데이터·자원·소비자에 무엇이 발생하는가? |
| 심각도·우선순위 | 등급과 해당 판단의 이유 |
| 확실성과 남은 가정 | 직접 확인한 사실과 추론의 경계 |
| 최소 개선 방향 | 위험을 줄이는 가장 작은 변경과 비교할 대안 |
| 결정의 근거 | **설계 선택·구조 변경과 관련된 경우** 현재 제약·보호할 규칙·선택 이유를 적고, 확인된 사실·기록된 의도·리뷰어의 추론을 구분한다. 단순 결함이면 `적용 제외 — 선택 비교가 필요한 문제가 아님`처럼 적을 수 있다. |
| 이해 비용 | 누가 어떤 과제를 하며, 무엇을 읽고 수동으로 맞춰야 하는가? 단순 지역 결함이면 필요한 범위만 기록한다. |
| 최소 개선 방향 | 위험을 줄이는 가장 작은 변경. 설계 선택이면 비교할 대안을 함께 적는다. |
| 대안 비교 | **여러 타당한 선택지가 있는 경우** 현상 유지·더 단순한 대안·다른 접근의 차이를 비교한다. 명백한 계약 위반을 바로잡는 단순 수정이면 적용 제외할 수 있다. |
| 단순화의 보존 조건 | 제거·통합·비공개화처럼 단순화를 제안할 때 지켜야 할 동작·타입·실패·진단 계약. 단순 결함 수정이면 적용 제외할 수 있다. |
| 비용·부작용 | 추가 복잡성·운영 책임·호환성·이행 비용 |
| 재검토 조건 | **현재 선택을 유지하거나 새 선택으로 바꾸는 판단이 있는 경우** 어떤 요구·규모·측정 결과·의존 계약 변화가 결론을 바꾸는지 적는다. 단순 결함 수정이면 적용 제외할 수 있다. |
| 완료 기준 | 구현자가 끝났는지 판단할 관찰 가능한 조건 |
| 검증 방법 | 그 위험을 직접 다루는 테스트·실험·정적 검사 |
| 담당·기한·상태 | 실제 조치 책임과 진행 상태 |
| 재검증 결과 | 변경 버전·실행 결과·잔여 위험 |
`적용 제외`는 빈칸을 허용한다는 뜻이 아니다. **왜 선택 비교가 필요하지 않은지 짧게 남겨야 한다.** 예를 들어 `CI workflow에서 필수 gate ID 한 개가 단순 누락됨 — 기대 계약이 이미 고정되어 있어 대안 비교 적용 제외`처럼 기록한다. 반대로 “복잡해 보여서 단순화한다”, “다른 라이브러리로 바꾼다”, “추상화를 합친다”처럼 선택을 바꾸는 제안은 단순 결함으로 축소하지 않고 41절의 비교를 수행한다.
### 36.4 부정확한 리뷰와 실행 가능한 리뷰의 차이
다음은 작성 방식의 예시다. 실제 저장소에서 발견한 문제를 뜻하지 않는다.
@@ -1279,6 +1323,9 @@ README·설계 문서는 **주장과 의도를 찾는 자료**다. 실제 동작
6. **개선 순서:** 먼저 고칠 이유, 최소 변경, 비용, 완료 기준은 무엇인가?
7. **재검토 조건:** 규모·버전·의존성·인증·배포 방식이 어떻게 바뀌면 다시 봐야 하는가?
설계 선택의 상세 설명이 필요한 경우 41.10절의 답변 양식을 사용한다. 이미 코드·공개 계약·기존 기록에 있는 설명은 연결해서 쓰며, 모든 발견 사항에 같은 내용을 중복 작성하지 않는다.
실제 리뷰를 수행할 때는 동봉된 `TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md`를 실행 순서로 사용하고, 상세 판단이 필요한 지점에서 이 기준서의 해당 절로 돌아온다.
## 37. 원문에서 보강·교정한 주요 내용
원문의 범위는 넓고 유용하다. 다음은 실제 리뷰에 적용할 때 오해를 줄이기 위해 바꾼 지점이다.
@@ -1305,7 +1352,7 @@ README·설계 문서는 **주장과 의도를 찾는 자료**다. 실제 동작
## 38. 참고한 공식 자료와 사용 범위
확인일: 2026-09-25. 아래 자료는 각각의 원칙을 확인하는 근거다. 이 문서의 28개 분류, 평가표, 예시 시나리오 전체가 해당 기관의 공식 기준이라는 뜻은 아니다.
기존 원칙 자료 S1~S10 확인일: 2026-09-25. 추가 코드·문서 자료 S11~S24 확인일: 2026-09-28. S3·S10은 41절 보강 때 다시 확인했다. 아래 자료는 각각의 원칙과 사례를 확인하는 근거다. 이 문서의 28개 분류, 평가표, 예시 시나리오 전체가 해당 기관의 공식 기준이라는 뜻은 아니다.
| 표기 | 자료 | 이 문서에서 참고한 내용 |
| --- | --- | --- |
@@ -1319,5 +1366,580 @@ README·설계 문서는 **주장과 의도를 찾는 자료**다. 실제 동작
| S8 | [SLSA v1.2 — Provenance](https://slsa.dev/spec/v1.2/provenance) | 산출물의 출처와 생성 과정을 추적하는 검증 가능한 정보 |
| S9 | [OWASP ASVS 5.0 — General Data Protection](https://cornucopia.owasp.org/taxonomy/asvs-5.0/14-data-protection/02-general-data-protection) | 민감정보 전송·캐시·수집·보호 정책의 확인 |
| S10 | [AWS Well-Architected — Make mutating operations idempotent](https://docs.aws.amazon.com/wellarchitected/latest/reliability-pillar/rel_prevent_interaction_failure_idempotent.html) | 작업 식별·중복 억제·상태 추적·원자성·보관 기간의 검토 |
| S11 | [TanStack Query — React Quick Start](https://github.com/TanStack/query/blob/2e1ad64b525f6ff2034f169ab9c2f48f82f17296/docs/framework/react/quick-start.md) | 입문 문서에서 강조하는 Query·Mutation·Invalidation |
| S12 | [TanStack Query — query.ts](https://github.com/TanStack/query/blob/2e1ad64b525f6ff2034f169ab9c2f48f82f17296/packages/query-core/src/query.ts) | 내부 타입·상태·Action·retryer 위임과 완료 후 참조 정리 |
| S13 | [Spring Framework — TransactionTemplate.java](https://github.com/spring-projects/spring-framework/blob/93ff61fb1ff9b30654d5b44f488887ce100974f1/spring-tx/src/main/java/org/springframework/transaction/support/TransactionTemplate.java) | callback 실행·transaction manager 위임·rollback 실패 처리 |
| S14 | [Spring Security — AuthenticationManager.java](https://github.com/spring-projects/spring-security/blob/c09729200b15acac8ac53bd7f30646d4e81cfb36/core/src/main/java/org/springframework/security/authentication/AuthenticationManager.java) | 단일 메서드 계약에 담긴 성공·실패 의미와 조건부 상태 검사 |
| S15 | [Debezium — README](https://github.com/debezium/debezium/blob/main/README.md) | 공통 모듈과 DB 특화 모듈의 기능·성능 차이를 설명하는 범위 |
| S16 | [React Router — README](https://github.com/remix-run/react-router/blob/main/README.md) | framework 또는 library로 사용하는 범위의 구분 |
| S17 | [Java SE 21 — List](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/List.html#copyOf(java.util.Collection)) | `copyOf`의 수정 불가·후속 원본 변경과의 분리·null 제한·요소 가변성·반환 객체 재사용 가능성 |
| S18 | [Java SE 21 — Collections.unmodifiableList](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Collections.html#unmodifiableList(java.util.List)) | 원본 목록을 읽는 수정 불가능한 view의 계약 |
| S19 | [Java SE 21 — ArrayList](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/ArrayList.html) | 컬렉션을 받는 생성자와 목록 변경 연산 |
| S20 | [Java Language Specification 21 — §4.12.4 final Variables](https://docs.oracle.com/javase/specs/jls/se21/html/jls-4.html#jls-4.12.4) | 참조 재대입 제한과 참조 대상의 가변성 구분 |
| S21 | [Jakarta Persistence 3.2 — §2.1·§2.2](https://jakarta.ee/specifications/persistence/3.2/jakarta-persistence-spec-3.2) | Entity의 non-final 요구, 영속 필드·컬렉션의 접근 계약 |
| S22 | [AWS Prescriptive Guidance — Transactional outbox pattern](https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/transactional-outbox.html) | 로컬 DB 변경과 발행 의도의 원자적 기록, 중복 전달·순서·후속 처리의 고려 사항 |
| S23 | [RFC 9110 — §9.2.1·§9.2.2·§10.2.3](https://www.rfc-editor.org/rfc/rfc9110.html) | HTTP의 safe·idempotent 의미, 비멱등 요청의 자동 재시도 조건, Retry-After |
| S24 | [Microsoft Azure Architecture Center — Cache-Aside](https://learn.microsoft.com/en-us/azure/architecture/patterns/cache-aside) | 캐시 적용 조건·만료·무효화·데이터 원본과의 정합성 한계 |
리뷰에서 최종적으로 남겨야 할 것은 “고급 패턴을 많이 썼다”는 평가가 아니다. **어떤 규칙을 어디서 지키고, 무엇을 변경하면 어디까지 영향이 가며, 어떤 실패를 확인했고, 무엇이 아직 미검증인지**를 다른 사람이 같은 근거로 판단할 수 있어야 한다.
## 39. 설계 의도와 코드 표현력 — 보호 장치를 유지하며 이해 부담 줄이기
이 절은 4번 인지 부하, 5번 위험 가시성, 9번 유지보수, 10번 테스트, 21번 Guardrail, 22번 추상화, 24번 의미 표현을 함께 검토하는 방법이다. 새로운 상위 성숙도 항목이나 점수를 추가하지 않는다.
리뷰에서 묻는 것은 **“왜 이 코드가 이런 모양이어야 하는지 다음 수정자가 설명할 수 있는가?”**다. 안전장치가 많다는 사실과 코드가 잘 읽힌다는 사실은 각각 확인해야 한다.
### 39.1 “고민과 결정이 드러나는 코드”의 의미
개발 당시의 모든 고민이 코드에 남을 필요는 없다. 다음 수정에 영향을 주는 제약과 결정은 현재 코드에서 찾을 수 있어야 한다.
| 확인할 것 | 독자가 설명할 수 있어야 할 내용 |
| --- | --- |
| 해결할 문제 | 어떤 상황에서 어떤 잘못된 동작을 막는가? |
| 보호할 규칙 | 어떤 입력·실패·경쟁에서도 무엇을 유지해야 하는가? |
| 선택한 경계 | 왜 이 객체·함수·타입·트랜잭션이 이 일을 맡는가? |
| 선택 이유 | 더 단순해 보이는 대안을 쓰면 어떤 요구가 깨지는가? |
| 감수한 비용 | 이 선택이 만드는 지연·중복·메모리·학습 비용은 무엇인가? |
| 재검토 조건 | 어떤 요구나 환경이 바뀌면 이 선택을 다시 보아야 하는가? |
예를 들어 완료된 비동기 작업의 핸들을 지우는 코드에서는 “핸들을 비운다”는 동작만 읽혀서는 부족할 수 있다. 오래 살아 있는 객체가 완료 결과를 계속 참조하지 않게 하려는 이유와, 새 작업이 시작됐다면 그 핸들은 보존해야 한다는 규칙을 확인할 수 있어야 한다.
이 정도 이유가 코드의 조건·상태 소유권·짧은 주석·실패 테스트에서 드러나면 설계의 판단이 남아 있는 것이다. 새 인터페이스나 정책 객체를 추가해야만 의도를 표현할 수 있는 것은 아니다.
이유의 타당성을 검토하는 공통 질문과 후속 답변 예시는 41절에 정리했다. 설득력 있는 설명만으로 현재 구현이 그 이유를 충족한다고 판정하지 않는다.
### 39.2 결정의 이유를 어디에 남길 것인가
| 내용 | 우선 둘 위치 | 남길 정보 |
| --- | --- | --- |
| 업무 행위와 경계 | 함수·객체 이름과 호출 순서 | 무엇을 언제 수행하는가? |
| 허용 상태와 결과 | 타입·생성/변경 API·계약 | 어떤 상태와 실패를 구분하는가? |
| 예상 밖의 분기·순서 | 해당 코드 가까이의 짧은 주석 | 이 조건을 없애거나 순서를 바꾸면 왜 문제가 되는가? |
| 중요한 재발 조건 | 동작을 검증하는 테스트 | 어떤 입력·경쟁에서 어떤 결과를 지켜야 하는가? |
| 여러 대안과 비용 비교 | 설계 결정 기록(ADR) 또는 기존 설계 문서 | 선택 근거·포기한 대안·한계·재검토 조건 |
| 변경 과정과 상세 토론 | Git 이력·PR·이슈 | 누가 언제 무엇을 시도하고 바꿨는가? |
한 줄의 조건식만으로 모든 선택 이유를 증명할 수는 없다. 코드가 동작과 규칙을 표현하고, 가까운 설명이 독자의 잘못된 추론을 막으며, 긴 비교는 별도 기록으로 이어지면 된다.
설계 기록을 남기기 위해 모든 helper에 문서를 만들 필요는 없다. 대안을 다시 검토할 가능성이 높거나 선택의 비용이 큰 결정에 집중한다.
“history는 Git에 있다”는 말은 변경 과정을 코드 주석에 길게 복사하지 말라는 취지로 사용한다. **현재도 유효한 선택 이유까지 Git 이력으로 밀어내지 않는다.**
### 39.3 국소적 이해 — 필요한 범위에서 행동을 예측할 수 있는가
국소적 이해는 파일 하나만 읽고 시스템 전체를 이해한다는 뜻이 아니다. 대표 과제의 진입점과 공개 계약, 필요한 정책을 읽으면 해당 동작을 예측할 수 있어야 한다는 뜻이다.
다음 과제를 하나 골라 작성자의 구두 설명 없이 따라간다.
> “이 요청을 취소하면 어떤 처리가 중단되고, 어떤 데이터와 외부 부작용이 남는가?”
읽은 파일 수와 함께 다음을 기록한다.
- 이름과 타입만으로 알 수 있었던 것
- 반드시 구현 안쪽까지 들어가야 했던 것과 이유
- 전역 registry·설정 우선순위·호출 순서를 암기해야 했던 것
- 다른 곳의 정보를 수동으로 맞춰야 했던 것
- 실패 결과와 자원 정리의 소유자를 찾을 수 있었는지
**좋은 신호:** 구현은 여러 파일이어도 공개 계약이 안정되어 불필요한 내부 지식을 요구하지 않는다.
**나쁜 신호:** 함수는 짧아졌지만 의미 없는 전달 계층을 계속 넘나들며, 중요한 실패 의미는 전역 실행 정책을 읽어야만 알 수 있다.
“파일 2~3개면 합격” 같은 절대 기준을 만들지 않는다. 이전과 같은 과제를 다시 수행해 뜻밖의 이동과 숨은 전제가 줄었는지 비교한다. 설정·보안 정책을 모든 호출부에 복사해 넣는 것도 해결책이 아니다.
### 39.4 내부 복잡성과 사용자가 알아야 할 개념을 분리한다
템플릿에서는 누가 코드를 읽고 바꾸는지에 따라 필요한 지식이 다르다.
| 역할 | 주로 알아야 할 것 | 자동으로 떠안기지 않을 것 |
| --- | --- | --- |
| 제품 기능 작성자 | 기능의 입력·출력·경로·상태·필요 capability | 플랫폼의 모든 타입 조합·설치 registry 내부 |
| 앱을 조립하는 사람 | 기능 설치·환경별 구현·충돌·필수 의존성 | 각 기능의 내부 상태 전이 |
| 플랫폼 유지보수자 | capability 검증·타입 추론·수명·교체 경계 | 모든 제품 기능의 업무 정책 |
예를 들어 `FeatureModule`에 제네릭 축이 여섯 개 있다는 사실만으로 복잡하다고 판정하지 않는다. 다음을 실제 호출부에서 확인한다.
1. 기능 작성자가 여섯 타입을 직접 고르고 연결해야 하는가, 입력으로부터 추론되는가?
2. 각 축은 다른 잘못된 조합을 막는가, 같은 정보를 여러 형태로 전달하는가?
3. 기본 기능을 만들 때도 고급 확장 규칙을 모두 알아야 하는가?
4. 오류가 났을 때 부족한 입력과 해결 위치가 보이는가, 거대한 내부 타입만 나오는가?
5. 공개하지 않아도 될 구현 타입을 사용자 계약으로 노출했는가?
`EmptyFeatureContract`, `AnyFeatureModule`, capability 관련 타입 등이 내부에서 정확성을 지키는 데 쓰이고 사용자에게 추론된다면 유지할 근거가 있다. 반대로 일반 기능 하나를 만들기 위해 모두 이해·작성해야 한다면 노출 범위를 줄일 후보가 된다.
**완료 기준:** 같은 기능을 작성할 때 필요한 결정과 수동 연결이 줄며, 잘못된 capability·계약 조합은 이전과 같은 단계 또는 더 이른 단계에 이해 가능한 오류로 검출된다.
제네릭 여섯 개를 거대한 설정 객체 하나로 감싸거나, 또 하나의 등록 DSL을 도입하는 것만으로 개선됐다고 보지 않는다. 실제 사용자의 작업을 기준으로 비교한다.
### 39.5 선언·실행·검증이 같은 정보를 반복하는가
다음은 전달받은 평가에서 제시한 형태를 설명용으로 축약한 것이다. 현재 프로젝트의 실제 실행 방식은 확인하지 않았다.
```java
@UseCaseCapability(transactionMode = WRITE)
public Result execute(Command command) {
return tx.inWrite(() -> perform(command));
}
```
겉모습만 보면 두 곳에서 쓰기 트랜잭션을 말한다. 그러나 무엇이 원본 정책이며 각각 누가 읽는지에 따라 판단은 달라진다.
| 상황 | 판단 |
| --- | --- |
| annotation을 런타임이 소비해 실제 경계를 구성한다. | 실행 경로와 중첩·충돌을 확인한다. 단순 설명 메타데이터로 취급하지 않는다. |
| annotation은 독립적인 허용 조건이고 검사가 실제 실행과 대조한다. | 검출하는 위반 사례와 검사 한계가 분명하면 가치가 있다. |
| 한쪽은 다른 쪽에서 생성되거나 추론되며 사람이 두 곳을 맞추지 않는다. | 생성·추론의 원본과 검증 범위를 확인한다. |
| 어느 도구도 읽지 않고 개발자가 두 곳을 항상 맞춰야 한다. | 중복 유지 비용이다. 삭제·통합·계약 설명으로 대체할 후보가 된다. |
| 검사도 선언값만 다시 읽고 실제 동작은 확인하지 않는다. | 검사 통과를 선언·실행 일치의 증거로 사용할 수 없다. |
**확인할 네 가지:** 정보의 원본, 실제 소비자, 불일치 시 검출 지점, 그 검사가 놓치는 실행 경로다.
독립적인 기대값과 실제 구현을 비교하는 것은 유용한 중복이다. 테스트의 기대값까지 구현에서 그대로 생성하면 독립적인 검증을 잃을 수 있다. 따라서 “한 사실은 한 번만 적는다”는 원칙을 기계적으로 적용하지 않는다.
`@RequiresPermission`처럼 권한에 관련된 annotation은 실제 인가를 수행할 수 있다. 선언처럼 보인다는 이유로 제거하지 않고 interceptor·필터·검증기의 실제 사용을 확인한다. 제거 제안에는 동등한 권한 통제가 어디에 남는지 적는다.
### 39.6 추상화의 필요성을 입증하는 질문
삭제 후보마다 다음 정보를 간단히 적는다. 프로젝트 전체에 새로운 registry나 자동화 시스템을 만들 필요는 없다. 실제로 논쟁이 있는 몇 개만 검토한다.
| 질문 | 확인할 증거 |
| --- | --- |
| 누가 사용하는가? | 실제 호출부와 사용자의 역할 |
| 무엇을 대신 책임지는가? | 실패·수명·권한·변경 경계와 계약 |
| 없으면 무엇이 깨지거나 반복되는가? | 도달 가능한 실패 또는 호출자에 복제될 정책 |
| 어떤 차이를 표현하는가? | 실제 구현·설정·소비자의 차이 |
| 왜 지금 필요한가? | 현재 요구 또는 명시된 지원 범위 |
| 사용자가 지불하는 비용은 무엇인가? | 필수 개념·등록·타입 지정·탐색·오류 해석 |
| 더 작은 수단으로 충분한가? | 함수·모듈 비공개화·기본값·기존 라이브러리·부분 중복과의 비교 |
판정은 유지, 내부로 감추기, 합치기, 나누기, 제거 중에서 고른다. 모든 복잡성 문제의 답이 제거는 아니다.
**단일 소비자도 충분한 이유가 될 수 있다.** 외부 결제 호출, 단일 DB 구현, 인가 경계를 격리하는 포트는 소비자가 하나여도 의미가 있다. 두 번째 소비자 유무는 재사용 가능성의 증거 중 하나다.
**함께 바뀌는 이유를 본다.** 변경 이력에서 자주 같이 수정됐다는 사실만으로 공통화하지 않는다. 대규모 포맷 수정이나 일괄 마이그레이션으로 함께 바뀌었을 수도 있다. 같은 정책 때문에 함께 바뀌는지, 차이가 생겼을 때 예외 인자가 계속 늘어나는지를 확인한다.
**코드 경제성은 줄 수의 최소화가 아니다.** 같은 계약을 제공하는 데 필요한 개념·수동 연결·변경 지점과 유지 비용을 줄이는 것이다. 조금의 중복이 서로 다른 정책을 독립적으로 이해하게 한다면 허용할 수 있다.
### 39.7 큰 실행기를 나눌 때는 상태와 정책의 소유권을 본다
HTTP 실행기에 deadline, retry, auth, cancellation, idempotency, 응답 크기 제한, schema 검증, 관측이 모여 있다고 해서 전부 분리해야 하는 것은 아니다. 같은 요청의 시간·시도 횟수·취소 상태를 조율해야 하므로 함께 판단할 부분이 있다.
| 확인 질문 | 유지·분리 판단에 주는 정보 |
| --- | --- |
| 같은 상태와 수명을 공유하는가? | 같은 상태 전이를 소유하는 핵심 조율부가 필요한가? |
| 정책을 바꿀 때 함께 바뀌어야 하는가? | 독립적인 변화 이유가 섞였는가? |
| 순서가 정확성에 영향을 주는가? | 분리하면 호출자가 순서를 외워야 하는가? |
| 외부 I/O 없이 판단할 수 있는가? | 순수한 판정 함수로 좁힐 수 있는가? |
| 오류·취소·정리의 책임이 이어지는가? | 분리 뒤 누가 최종 상태와 자원을 책임지는가? |
| 테스트가 어느 경계를 검증하는가? | 의미 있는 경계인가, 같은 상태를 나눠 숨긴 것인가? |
예를 들어 재시도 가능 여부를 계산하는 함수는 분리할 수 있어도, 전체 deadline에서 남은 시간을 계산하고 실제 재시도를 예약하는 주체는 일관된 상태를 알아야 한다. 취소와 재시도를 서로 모르는 실행기로 옮기면 정합성을 오히려 해칠 수 있다.
분리한다면 정상 흐름과 중요한 실패 분기를 조율부에서 읽을 수 있게 하고, 별도 함수가 맡는 판단을 이름과 계약으로 설명한다. 여러 개의 `*Policy`, `*Context`, `*Descriptor`로 파일만 나눈 뒤 더 많은 규약을 요구하는 구조는 개선으로 판정하지 않는다.
**완료 기준:** 독립적인 정책 변경의 영향 범위가 줄고, 요청의 시간·취소·시도·자원 정리 순서를 여전히 설명할 수 있다. 파일 길이는 결과로 기록할 수 있지만 합격 조건으로 고정하지 않는다.
### 39.8 주석·조건·테스트가 하나의 결정을 설명하는 예
다음은 설명용 TypeScript 축약 예시다. 생략한 타입·주변 구현을 포함하는 제품 코드나 그대로 실행할 완성 예제가 아니다.
결정의 이유를 알기 어려운 형태:
```typescript
finally {
// Q-6.9-7 반영
releaseAttempt(attempt);
}
```
독자는 리뷰 문서에서 번호를 찾고, helper 구현을 열고, 어떤 상태를 보호하는지 다시 추론해야 한다. helper가 실제 책임을 캡슐화한다면 유지할 수 있지만 주석은 그 책임을 설명하지 못한다.
선택 이유가 가까이 드러나는 형태:
```typescript
finally {
// 완료된 작업의 결과를 계속 붙잡지 않도록 참조를 해제한다.
// 그사이 새 작업이 시작됐다면 새 작업의 핸들은 유지한다.
if (activeAttempt === attempt) {
activeAttempt = undefined;
}
}
```
여기서 조건은 어떤 핸들을 지울 수 있는지 제한하고, 주석은 참조 해제와 소유권 검사의 이유를 설명한다. 이 형태가 실제 제품의 상태 소유권에 맞는지는 별도로 확인해야 한다.
중요한 경쟁을 검증하는 예시는 다음과 같다.
1. 작업 A를 시작한다.
2. A의 정리 전에 작업 B가 현재 작업이 되도록 한다.
3. A의 정리를 실행한다.
4. B가 여전히 현재 작업인지 확인한다.
테스트는 private 필드명이나 helper의 모양을 고정하기보다, B의 취소·조회·진행 관리가 계속 올바르게 동작하는지를 확인한다.
같은 원칙으로 owner signal에서 listener를 떼는 코드에는 “리뷰 지적 반영”보다 **owner가 더 오래 살아도 완료된 작업을 listener가 계속 참조하지 않게 한다는 이유**를 남긴다. 실제로 어떤 참조가 객체 수명을 늘리는지는 구현에서 확인한다.
**이슈·명세 링크는 삭제 대상이 아니다.** 브라우저 버그, 프로토콜 규칙, 보안 제약, 호환성 우회처럼 원본 근거가 중요한 경우 짧은 설명 뒤에 링크나 식별자를 남긴다. “Spec §10”만 있고 현재 코드와의 관계가 설명되지 않는 상태를 개선한다.
### 39.9 단순화 전후에 지켜야 할 조건
줄 수나 공개 타입이 줄어들었더라도 다음 계약을 잃으면 단순화에 성공한 것이 아니다. 변경한 경계에 관련된 항목만 선정해 검증한다.
| 보존할 성질 | 확인할 회귀 |
| --- | --- |
| 중요한 상태 구분 | 결과 불명·거부·일시 실패를 같은 값으로 합치지 않았는가? |
| 타입 안전성 | 잘못된 기능 조합을 `any`·단언·느슨한 옵션으로 허용하지 않았는가? |
| 권한·데이터 범위 | 내부화하거나 공통화한 상태가 사용자·테넌트 사이에 섞이지 않는가? |
| 부작용 계약 | 시간 제한·재시도·취소·멱등성 의미가 유지되는가? |
| 자원 수명 | listener·timer·연결·완료 결과를 적절한 주체가 정리하는가? |
| 진단 가능성 | 오류의 원인·작업 식별·적용 정책을 찾을 수 있는가? |
| 변경 경계 | 없앤 helper의 정책을 여러 호출자가 각자 구현하게 되지 않았는가? |
| 사용·오류 설명 | 정상 과제는 쉬워졌지만 실패 시 내부 전체를 알아야 하는 구조가 되지 않았는가? |
제네릭이나 schema 경계를 바꿨다면 대표적인 금지 조합이 여전히 검출되는지 확인한다. 수명주기를 바꿨다면 취소·경쟁·정리 조건을 확인한다. 설명 주석만 고쳤다면 실행 동작이 바뀌지 않았는지와 사실이 맞는지를 확인한다.
이 검토 때문에 모든 변경에 대규모 테스트를 요구하지 않는다. 줄이려는 복잡성이 무엇을 보호했는지 파악하고, 그 보호가 사라질 구체적인 위험을 검증한다.
### 39.10 리뷰 결과를 리팩터링 작업으로 바꾸는 방법
대상 하나마다 다음 내용을 기록한다.
> 대표 과제와 사용자 → 현재 알아야 할 개념 → 보호할 규칙 → 불필요한 부담의 근거 → 비교한 작은 대안 → 유지할 계약 → 확인할 결과
예를 들어 “capability 관련 타입이 많으니 삭제”라는 지시는 부족하다. 다음처럼 작성한다.
> 일반 기능 작성자가 실제로 지정하는 타입·등록값을 확인한다. 입력으로 추론할 수 있는 정보와 플랫폼 내부에서만 필요한 타입을 분리한다. 선언하지 않은 capability 사용과 host 제공 누락의 검출을 유지하면서, 기능 작성 시 필요한 수동 연결을 줄인다. 기존 구현이 이미 이 조건을 만족하면 변경하지 않는다.
다음 질문에도 답해야 한다.
- 분리·통합·삭제 외에 이름이나 주석을 고치는 것으로 충분한가?
- 기존 라이브러리가 맡을 수 있는 책임을 자체 framework로 다시 만들었는가?
- 단순화를 위해 추가한 facade가 실제 사용 계약을 좁혔는가, 전달 계층만 하나 늘렸는가?
- 바꾼 뒤 같은 대표 과제를 수행하면 무엇이 실제로 쉬워지는가?
이 기준은 “초보·중급·고수”라는 등급을 부여하기 위한 것이 아니다. 리뷰어의 취향을 검증 가능한 변경 제안으로 바꾸기 위한 것이다.
## 40. 오픈소스 비교에서 확인한 사실과 평가의 한계
이 절은 전달받은 비교 글을 그대로 채택하지 않고, 확인한 코드와 문서에서 어떤 원칙을 가져올 수 있는지 정리한다. 오픈소스의 인지도나 규모가 모든 설계 선택의 정답을 보장하는 것은 아니다.
### 40.1 확인된 내용과 가이드에 적용할 해석
| 대상 | 원문에서 확인한 내용 | 이 가이드의 해석과 한계 |
| --- | --- | --- |
| TanStack Query 입문 문서 | Query·Mutation·Invalidation을 핵심 입문 개념으로 제시한다. [S11] | 입문 경로를 좁힌 사례다. 사용자가 항상 세 개만 알면 충분하다는 증거는 아니다. |
| TanStack Query 내부 | `Query`에 여러 제네릭·상태가 있으며 `Action`과 `retryer` 등을 사용한다. 완료 후 참조를 정리하는 코드와 이유 설명도 있다. [S12] | 내부 타입 수와 일반 사용자에게 노출되는 필수 개념 수를 구분한다. |
| Spring TransactionTemplate | callback 수행과 transaction manager 위임이 보인다. rollback 실패 종류에 따라 원래 예외를 연결하거나 로그에 남기는 처리도 있다. [S13] | 의미 있는 책임을 한곳에서 읽는 사례다. 하위 manager와 기반 클래스의 복잡성까지 파일 길이에 포함된 것은 아니다. |
| Spring AuthenticationManager | 단일 인증 메서드에 반환·예외 계약을 설명한다. disabled·locked 검사는 해당 상태를 확인할 수 있는 경우라는 조건이 붙는다. [S14] | 짧은 API도 정밀한 계약이 필요하다. 인터페이스만 읽고 모든 구현이 계약을 지킨다고 결론내릴 수는 없다. |
| Debezium README | 여러 DB에 적용하는 모듈과 특정 DB 기능을 활용하는 모듈의 차이를 설명한다. [S15] | 공통화에 따른 제약을 읽을 수 있다. README만으로 전체 구현의 응집도나 변경 비용을 판정하지 않는다. |
| React Router README | framework 또는 library로 사용할 수 있다고 설명한다. [S16] | 사용 범위의 차이를 확인했다. 핵심 상태 머신의 응집도·파일 길이·flag별 테스트 범위는 이 README로 입증하지 못한다. |
TanStack Query의 완료 처리에서는 결과 참조가 남는 이유를 주석으로 설명하고, 현재 `retryer`가 정리 대상과 같은지 확인한 뒤 참조를 해제한다. 이 조건이 다른 작업의 핸들을 지우지 않도록 제한한다는 해석은 코드에서 도출한 것이다. 39.8절의 예시는 이와 같은 판단을 설명하기 위해 별도로 작성했다. [S12]
실행 테스트나 저장소 전체 리뷰를 수행한 것은 아니다. 이 사례들은 특정한 설계 판단을 읽는 근거로만 사용한다.
### 40.2 확인한 버전
| 자료 | 확인 기준 |
| --- | --- |
| S11·S12 TanStack Query | 커밋 `2e1ad64b525f6ff2034f169ab9c2f48f82f17296`; `query.ts` 파일 blob `fad5c2067a1e1bb3b8d644abc76267b59f6a5e28` |
| S13 Spring Framework | 커밋 `93ff61fb1ff9b30654d5b44f488887ce100974f1`; 파일 blob `475994bd3136da0030fb0482bdab0057b822a061` |
| S14 Spring Security | 커밋 `c09729200b15acac8ac53bd7f30646d4e81cfb36`; 파일 blob `b95d8c4f0789cb647273657b6e8913fc328e95c6` |
| S15 Debezium README | 2026-09-28 조회한 main 파일 blob `6bb1276d5f7a898980cc8623646555e59a86aaab` |
| S16 React Router README | 2026-09-28 조회한 main 파일 blob `8e1210841f3febba5009b0a1f7c3e33ce1d051f1` |
blob은 파일 내용의 식별자이며 저장소 커밋과 다르다. S15·S16의 main 링크는 이후 내용이 바뀔 수 있다.
### 40.3 그대로 받아들이지 않을 평가
- **“현재 두 템플릿의 아키텍처·안전성은 매우 강하다.”** 현재 코드·검사·실행 결과를 확인한 뒤 부여할 평가다. 복잡하고 정교해 보인다는 사실만으로 안전성이 입증되지는 않는다.
- **“제네릭 여섯 개, 타입 여러 개이므로 사용자가 알아야 할 개념이 많다.”** 실제 작성 지점·추론·오류 경험과 사용자 역할을 확인해야 한다.
- **“리뷰·명세 번호가 없는 코드가 더 성숙하다.”** 현재 제약과 원본 근거의 연결이 유용하다면 남긴다. 설명 없이 번호만 있는 상태가 문제다.
- **“고수 코드는 줄 수와 추상화가 적다.”** 비교 대상의 책임 범위와 위임한 하위 구현을 맞추지 않으면 성립하지 않는 평가다.
- **“두 번째 소비자가 없는 추상화는 삭제한다.”** 재사용 외에 경계·정확성·테스트 대역을 위한 이유가 있을 수 있다.
- **“일단 안전성이 완성됐으니 다음은 취향만 다듬으면 된다.”** 단순화 중에 보호 장치가 약해질 수 있다. 정확성과 이해 비용을 함께 확인한다.
전달받은 글에 등장하는 `FeatureModule`, `feature-adapter-contribution.ts`, `http-execution-v3.ts`, `CreateWorkLogUseCase`의 구체적인 상태와 파일 길이·변경 수·브랜치·커밋은 이번 가이드 보강에서 재확인하지 않았다. 코드 리뷰를 시작할 때 최신 상태와 적용 범위를 고정한다. 이를 현재 프로젝트의 확정된 결함이나 등급으로 기록하지 않는다.
### 40.4 비교할 때 책임 범위부터 맞춘다
비교 단위를 “파일 하나 대 파일 하나”로 고정하지 않는다. 같은 사용자 과제와 실패 책임을 수행하는 코드 범위를 비교한다.
| 먼저 맞출 조건 | 확인할 질문 |
| --- | --- |
| 사용자 역할 | 라이브러리 사용자와 내부 유지보수자를 섞어 비교하지 않았는가? |
| 책임 범위 | 한쪽이 직접 처리하고 다른 쪽이 아래로 위임한 책임은 무엇인가? |
| 지원 조건 | 버전 호환·실행 환경·취소·재시도·데이터 범위가 같은가? |
| 관찰 과제 | 정상 사용·변경·오류 해결 중 무엇을 비교하는가? |
| 보호할 성질 | 같은 위험을 통제한 상태에서 비교하는가? |
좋은 비교는 “저쪽에는 이 타입이 없으니 삭제하자”에서 끝나지 않는다. **“저쪽은 이 책임을 어디에서 해결하며, 우리도 그 방법을 적용하면 어떤 계약과 비용이 달라지는가?”**까지 확인한다.
리뷰 결과에는 남겨야 할 복잡성과 없앨 수 있는 부담을 함께 적는다. 다른 사람이 코드와 근거를 읽고 같은 결정을 검토할 수 있을 때, 설계 의도가 코드에 드러난다고 평가할 수 있다.
## 41. 설계 선택 설명 검증 — Decision Explanation Test
리뷰 후 “왜 여기서 이 방법을 썼는가?”라는 질문에 **요구와 코드 근거, 현실적인 대안, 감수한 비용, 선택이 달라질 조건**을 연결해 답할 수 있는지 확인한다. 설명을 잘하는 능력만 평가하는 절차가 아니다. 설명한 성질을 현재 코드가 실제로 보장하는지까지 검토한다.
39절은 선택 이유를 코드와 주변 기록에 어떻게 드러낼지 다뤘다. 이 절은 그 이유가 타당한지 판단하고, 후속 질문에 답하는 공통 방식이다. 언어 기능부터 분산 처리·템플릿 구조까지 적용하되 새로운 성숙도 점수나 필수 문서 체계를 만들지 않는다.
아래 사례의 요구조건과 답변은 설명용 가정이다. 실제 프로젝트의 요구, 선택 이력, 동작을 확인했다는 뜻이 아니다. 기술 계약은 38절의 자료와 연결하고, 해당 계약에서 도출한 설계 판단은 이 가이드의 제안으로 제시한다.
### 41.1 어떤 선택에 적용할 것인가
계약·실패·유지보수 비용에 영향을 주는 대표적인 선택에 적용한다.
- 가변 상태를 공유하거나 복사하는 지점
- 객체가 생성·변경될 때 지켜야 하는 업무 규칙
- 공개 API의 입력·결과·오류·호환성 계약
- 트랜잭션, 인가, 외부 부작용, 취소·재시도 경계
- 캐시·동시성·배포·복구 방식
- 모듈·플러그인·기능 조립·템플릿 업데이트 구조
- 단순화 과정에서 제거하려는 보호 장치나 추상화
명백한 지역 계산까지 대안표를 만들지는 않는다. `Math.max(a, b)`처럼 의미가 충분히 드러나면 코드로 설명을 마칠 수 있다. 다만 같은 계산이라도 금액 상한이나 권한 범위를 결정한다면 주변 계약을 확인한다. 설명의 깊이는 문법의 난이도보다 영향 범위와 오해했을 때의 피해에 맞춘다.
### 41.2 일곱 가지 공통 질문
| 질문 | 답변에 포함할 내용 |
| --- | --- |
| 1. 무엇이 필요한가? | 사용자·호출자, 현재 지원 환경, 정확성·성능·운영 요구, 확인되지 않은 전제 |
| 2. 반드시 지킬 성질은 무엇인가? | 어떤 입력·순서·부분 실패에서도 유지해야 할 규칙과 책임 주체 |
| 3. 현재 코드는 어떻게 보장하는가? | 실제 파일·심볼·실행 경계·타입·제약·검증 근거와 보장하지 않는 범위 |
| 4. 현실적인 대안은 무엇인가? | 현상 유지, 기능을 추가하지 않기, 더 작은 수단, 현재 요구에 맞는 다른 접근 |
| 5. 대안마다 무엇을 얻고 지불하는가? | 정확성, 이해 부담, 성능, 실패 특성, 변경·이행 비용, 운영 책임 중 관련 항목 |
| 6. 현재 조건에서 왜 이 선택인가? | 요구를 충족하는 후보 사이에서 선택한 이유와 받아들인 제한 |
| 7. 어떤 조건이면 선택이 달라지는가? | 새 요구, 의존 계약 변화, 측정 결과, 규모·팀·배포 변화와 다시 비교할 대안 |
필수 계약을 위반하는 대안은 비용이 낮다는 이유만으로 동등한 후보가 되지 않는다. 반대로 현재 요구에 없는 가상 미래를 위해 복잡한 선택을 자동으로 정당화하지 않는다.
대안을 많이 나열하는 것도 목표가 아니다. 실제 판단을 바꿀 수 있는 후보와 가장 단순한 후보를 비교한다. 대안이 사실상 하나뿐인 경우에는 그 제약을 설명하면 된다. 상충하는 요구를 동시에 만족할 수 없다면 무엇을 완화해야 하는지 드러낸다.
“가장 좋은 방법”이라는 표현에는 비교 범위가 필요하다. 측정하지 않은 성능 우위나 모든 대안을 검토했다는 주장을 피하고, **“확인한 조건과 비교한 후보에서는 이 선택이 타당하다”**고 설명한다.
### 41.3 확인한 사실·기록된 의도·추론을 구분한다
현재 코드가 어떤 효과를 낸다는 사실만으로 작성자가 그 효과를 의도했다고 단정할 수는 없다.
| 구분 | 근거 | 적절한 답변 |
| --- | --- | --- |
| 현재 동작·계약 | 코드·명세·실행 결과 | “이 생성자는 입력 목록의 후속 변경이 저장된 목록에 반영되지 않도록 합니다.” |
| 기록된 결정 | 현재 코드와 연결되는 ADR·PR·이슈·주석 | “당시 기록에는 외부 변경으로 규칙이 깨지는 문제를 막기 위한 선택이라고 설명돼 있습니다.” |
| 현재 조건에서의 해석 | 확인한 요구와 코드 효과의 비교 | “선택 이력은 없지만, 생성 후 목록 고정이 요구라면 이 구현은 그 요구와 맞습니다.” |
| 미확인 | 요구·호출부·의존 계약·측정 부재 | “내부에서 목록을 변경해야 하는지는 확인하지 못해 최종 선택은 조건부입니다.” |
과거 결정 기록도 현재 코드와 다르면 그대로 답에 사용하지 않는다. 작성자의 동기는 미확인이어도 현재 선택의 효과와 타당성은 분석할 수 있다.
리뷰어는 현재 구현을 방어하기 위해 요구를 만들어내지 않는다. 요구가 없으면 필요한 확인을 좁히고, 그동안 가능한 조건별 판단을 제시한다. 성능 수치, 장애 경험, 두 번째 소비자, 운영 규모를 근거 없이 보충하지 않는다.
**말로 설명할 수 있는 것과 코드에 표현되어 있는 것도 다르다.** 작성자만 아는 전제가 긴 구두 설명에만 존재한다면 4번 인지 부하·9번 유지보수의 개선 후보다. 다음 수정자가 필요한 근거를 코드·계약·짧은 설명·연결된 기록에서 찾을 수 있어야 한다.
### 41.4 다섯 범위에서 같은 질문을 적용한다
다음은 개발자의 등급이나 성숙도 단계가 아니라 서로 다른 검토 범위다. 작은 언어 선택이 시스템 계약에 영향을 줄 수 있고, 플랫폼 구조가 지역 코드의 이해 부담을 늘릴 수도 있다.
| 범위 | 대표 대상 | 중심 질문 | 관련 범위로 이어지는 질문 |
| --- | --- | --- | --- |
| 1. 언어·자료구조 | null, Optional, record, equals/hashCode, 예외, 방어적 복사 | 허용하는 값·상태는 무엇이며, 누가 변경할 수 있는가? | 가변 요소·키가 외부로 노출되거나 동시 접근되면 계약이 유지되는가? |
| 2. 객체·도메인 | Entity, Value Object, Aggregate, Factory, 상태 전이 | 업무 규칙을 누가 생성·변경 경계에서 지키는가? | 재구성·역직렬화·동시 갱신이 그 경계를 우회하는가? |
| 3. 애플리케이션·아키텍처 | UseCase, Port, Adapter, Repository, Transaction, Event, 인가 | 어떤 변화와 실패를 이 경계가 격리하는가? | 경계 밖 부작용과 안쪽 상태가 어긋나면 누가 복구하는가? |
| 4. 분산 처리·운영 | 재시도, 멱등성, 캐시, 락, 전달, 마이그레이션, 배포 | 부분 실패와 동시 실행에서도 어떤 계약을 유지하는가? | 결과 불명·중복·구버전 공존을 관찰하고 수습할 수 있는가? |
| 5. 시스템·플랫폼 | 모듈 구성, 플러그인, 기능 조립, CI, 팀 책임, 템플릿 진화 | 사용자가 알아야 할 개념과 변경 범위를 통제하는가? | 사용 프로젝트에 수정이 전파되고, 지원하지 않는 조합이 드러나는가? |
넓은 시야는 모든 리뷰에서 다섯 범위를 전부 조사한다는 뜻이 아니다. **현재 선택의 보장이 어디까지 유효하며, 다음 경계에서 무엇이 추가로 필요한지** 아는 것이다.
예를 들어 결제 요청 객체의 목록을 불변으로 만들면 그 객체의 상태 변경을 제한할 수 있다. 그것만으로 중복 요청의 결제 실행까지 막지는 못한다. 같은 업무 작업을 식별하는 계약과 서버의 중복 처리 방식을 별도로 확인해야 한다.
반대로 단일 객체 내부의 변경 문제를 해결하는 데 분산 락·이벤트 플랫폼부터 제안하는 것도 범위를 잘못 잡은 판단이다.
### 41.5 언어·자료구조 예시 — 왜 List.copyOf인가
다음 코드만으로는 요구를 확정할 수 없다.
```java
class Sample {
private final List<String> values;
Sample(List<String> values) {
this.values = values;
}
}
```
`final`은 필드에 다른 참조를 대입하지 못하게 한다. 참조 대상 목록의 변경까지 막지는 않는다. 호출자가 같은 가변 목록을 가지고 있다면 생성 이후에도 그 내용을 바꿀 수 있다. 이것이 이 예시에서 확인할 **가변 객체의 공유 참조, 즉 mutable aliasing**이다. [S20]
먼저 다음을 확인한다.
- 생성 이후 목록의 항목·순서가 고정되어야 하는가?
- 클래스 내부에서 추가·삭제·교체해야 하는가?
- 호출자와 변경을 공유하는 것이 의도된 계약인가?
- null 입력·null 요소를 허용하는가?
- 요소 자체도 가변인가? 반환 경로를 통해 내부 상태를 바꿀 수 있는가?
- 입력 크기와 복사 빈도가 실제 비용인가? 입력을 읽는 동안 동시 변경이 가능한가?
**대안 비교**
| 선택 | 원본 목록의 후속 변경 | 보관한 목록 변경 | 적합한 조건과 한계 |
| --- | --- | --- | --- |
| `this.values = values` | 공유한다. | 입력 구현에 달려 있다. | 공유가 의도되거나 별도 소유권 계약이 보장될 때 가능하다. 다른 참조의 변경을 이 코드가 제한하지는 않는다. |
| `Collections.unmodifiableList(values)` | view에 반영된다. | view를 통한 수정은 거부한다. | 읽기 전용 접근을 제공하면서 소유자의 변경은 보여줘야 할 때 적합하다. 스냅샷은 아니다. [S18] |
| `new ArrayList<>(values)` | 목록 상태를 분리한다. | 클래스 안에서 변경할 수 있다. | 내부 변경이 필요한 객체에 맞는다. 내부 목록을 그대로 반환하면 다시 외부 변경을 허용한다. [S19] |
| `List.copyOf(values)` | 반환 목록에 반영되지 않는다. | 추가·삭제·요소 교체를 거부한다. | 목록 구성을 고정할 때 맞는다. null 입력·요소를 거부하며, 요소 객체까지 복제하지는 않는다. [S17] |
네 선택 모두 같은 목적의 우열 관계는 아니다. 실시간 view와 고정된 스냅샷은 서로 다른 계약이다. `Collections.unmodifiableList(new ArrayList<>(values))`도 복사본을 외부에 따로 노출하지 않으면 목록 상태를 분리하는 선택이다. null 허용·지원 Java 버전 등 관련 조건이 있을 때 비교한다.
**조건을 붙인 답변 예시**
> 이 객체는 생성 이후 저장된 목록 구성이 바뀌지 않아야 한다고 가정했습니다. 참조를 그대로 보관하면 호출자가 항목을 추가·삭제·교체할 수 있고, 원본을 감싼 읽기 전용 view도 그 변경을 보여줍니다. 내부 변경 역시 필요 없고 null을 허용하지 않는 계약이어서, 이 조건에서는 `List.copyOf`가 적합합니다. 내부 추가·삭제가 필요해지면 방어적 가변 복사와 변경 메서드의 규칙을 다시 검토하겠습니다.
여기서 “소유권을 가져온다”는 표현은 주의해서 쓴다. Java에서 이 호출이 원본에 대한 호출자의 권한을 회수하는 것은 아니다. **저장할 목록 상태를 원본의 후속 변경과 분리하는 것**이다.
**보장 범위를 넘겨 설명하지 않을 것**
- `List<OrderLine>`의 요소가 가변이라면 요소 상태의 공유는 남는다. 객체 전체의 불변성이 요구되면 요소의 소유권·불변 모델·필요한 복사 범위도 검토한다. 원래 예시의 `String`과 가변 도메인 객체를 동일하게 취급하지 않는다. [S17]
- `List.copyOf`가 언제나 새 목록을 할당한다고 가정하지 않는다. 구현은 적합한 수정 불가능 목록을 재사용할 수 있다. 비용은 실제 입력 구현·크기·호출 빈도를 기준으로 판단한다. [S17]
- 복사 호출 자체를 동시 변경 중인 입력의 일관된 스냅샷 보장으로 해석하지 않는다. 필요한 일관성은 입력 자료구조와 동기화 계약에서 별도로 확인한다.
- 가변 목록을 반환할 때 view를 줄지 스냅샷을 줄지도 계약이다. `unmodifiableList(internal)`은 내부의 후속 변경을 보여주며, 목록을 복사해 반환하는 방식은 복사 시점의 구성을 제공한다. 요소 가변성은 어느 쪽에서도 따로 살핀다.
**JPA Entity에는 그대로 적용하지 않는다.** 영속 컬렉션의 변경·관계 동기화·provider 접근 방식을 확인한다. Jakarta Persistence 3.2는 Entity의 영속 인스턴스 변수가 non-final이어야 한다고 규정하므로, `@OneToMany private final List<...>` 자체도 이식 가능한 명세 준수 예제로 볼 수 없다. 특정 provider에서 돌아간다는 사실과 표준 계약을 구분한다. 불변 목록을 사용했을 때의 구체적인 실패 여부는 provider 버전·매핑·persist/merge/관계 변경 경로로 확인한다. [S21]
검증이 필요한 변경이라면 JDK 구현을 다시 테스트하기보다 **우리 객체의 계약**을 확인한다. 생성 후 호출자의 입력 변경이 업무 결과를 바꾸는지, 공개 변경 메서드가 규칙을 지키는지, 반환한 값으로 내부 상태를 우회 변경할 수 있는지 중 변경과 관련된 시나리오를 고른다.
### 41.6 트랜잭션·분산 처리 예시 — 왜 Outbox인가
다음은 일반적인 로컬 DB 트랜잭션과 별개의 외부 API를 사용하는 설명용 코드다. 외부 서비스가 같은 분산 트랜잭션에 참여한다는 전제는 두지 않는다.
```java
tx.inWrite(() -> {
repository.save(order);
externalApi.charge();
});
```
호출 순서만 읽어서는 원자성을 설명할 수 없다. 외부 호출 성공 후 DB commit이 실패하거나, 외부에서 처리했지만 응답이 유실될 수 있다. 트랜잭션 블록 안에 있다는 이유만으로 외부 결제가 DB rollback과 함께 취소되지는 않는다.
먼저 확정해야 할 것은 “주문을 접수할 때 결제 완료가 필수인가?”, “결제 대기 상태를 허용하는가?”, “결과 불명을 조회·대사할 방법이 있는가?”다. 이 답이 대안의 적합성을 바꾼다.
| 선택 | 해결하는 부분 | 남는 문제와 비용 |
| --- | --- | --- |
| DB 트랜잭션 안에서 외부 호출 | 한 실행 흐름에서 결과를 받아 분기한다. | 일반적인 외부 API와 로컬 DB의 공동 원자성은 없다. 외부 지연 중 DB 자원·획득한 락을 오래 보유할 수 있다. |
| 로컬 commit 후 직접 호출 | 외부 대기 시간을 DB 트랜잭션 밖으로 옮긴다. | commit 직후 중단되면 호출 누락이 생길 수 있다. 별도의 지속 가능한 작업·복구 수단이 필요할 수 있다. |
| 로컬 상태와 Outbox 레코드를 함께 기록 | DB 변경과 후속 전달 의도를 같은 로컬 트랜잭션에 남긴다. | 전달 지연·중복, relay 운영, 후속 처리 결과 반영을 다뤄야 한다. [S22] |
| 예약 후 확정, 또는 Saga·보상 절차 | 여러 단계의 업무 상태와 복구 경로를 명시한다. | 외부 API의 지원 계약, 만료·보상 실패·결과 불명 처리가 필요하다. 보상은 과거 효과를 완전히 없애는 rollback과 같지 않다. |
이 대안들은 모두 상호 배타적이지 않다. Outbox로 Saga의 명령·이벤트를 전달할 수도 있다. 패턴 하나가 다른 모든 책임을 대신한다고 비교하지 않는다.
**조건을 붙인 답변 예시**
> 이 흐름에서는 주문을 결제 대기 상태로 접수할 수 있고, 접수한 주문의 결제 작업 의도가 프로세스 중단 때문에 사라지지 않아야 한다고 가정했습니다. commit 후 즉시 호출만 하는 방식에는 그 사이의 중단 구간이 남습니다. 따라서 주문과 작업 의도를 같은 DB 트랜잭션에 기록하는 Outbox를 선택할 수 있습니다. 다만 외부 결제까지 원자적으로 완료되거나 정확히 한 번만 실행된다는 보장은 아닙니다. 중복 실행 방지, 결과 조회·대사, 전달 지연과 적체 처리 책임이 함께 필요합니다. [S22][S10]
위 설명을 실제 프로젝트에 적용하려면 같은 트랜잭션·DB에 기록되는지와 relay의 읽기·전송·완료 처리 경계를 확인한다. 전송 성공 뒤 완료 표시 전에 중단되는 경우도 살핀다. `outbox.append()` 호출 하나가 있다는 사실로 전체 계약을 충족했다고 판단하지 않는다.
요청 응답 전에 결제 확정이 반드시 필요해지면 비동기 접수만으로는 요구가 충족되지 않는다. 그렇다고 외부 호출을 DB 트랜잭션 안으로 옮기면 해결된다고 결론내리지 않는다. 동기 응답 계약과 외부 작업 식별·복구 프로토콜을 함께 다시 설계한다.
업무 상태만으로 누락된 후속 작업을 확실히 재구성할 수 있고 그 지연·중복·비용이 허용된다면, 별도 Outbox 대신 그 상태를 이용하는 지속 가능한 작업 방식도 비교할 수 있다. 핵심은 패턴 이름보다 **중단 뒤 어떤 근거로 무엇을 복구하는가**다.
### 41.7 성능·운영 예시 — 왜 캐시인가
캐시는 측정된 문제와 허용할 데이터 계약을 먼저 설명해야 한다.
| 후보 | 비교할 조건 |
| --- | --- |
| 캐시 없이 유지 | 현재 목표를 충족하는지, 추가 상태·장애 지점을 만들 이익이 있는지 |
| 쿼리·인덱스·조회량 개선 | 중복 요청·N+1·불필요한 데이터 읽기가 비용의 원인인지 |
| 프로세스 내부 캐시 | 인스턴스별 데이터 차이·메모리 사용·재시작을 허용하는지 |
| 공유 캐시 | 여러 인스턴스의 재사용 이익이 네트워크 지연·의존 장애·운영 비용보다 큰지 |
| CDN 등 전달 경로의 캐시 | 응답의 공개 범위·개인화·캐시 키·무효화 계약이 맞는지 |
| 사전 계산·별도 조회 모델 | 읽기 비용을 줄이는 대신 갱신 지연·재구축·저장 비용을 감당할 수 있는지 |
단일 조회가 1ms라는 사실만으로 캐시가 불필요하다고 결론내리지 않는다. 요청 빈도·전체 DB 비용·혼잡 시 지연·목표를 함께 본다. 반대로 인스턴스가 다섯 개라는 이유만으로 Redis가 필요한 것도 아니다.
공유 캐시도 원본 DB와의 강한 정합성을 자동으로 제공하지 않는다. cache-aside에서는 갱신·무효화·재적재 사이의 경쟁과 오래된 값의 노출을 설계해야 한다. 허용할 오래된 값의 범위, 캐시 키의 사용자·테넌트 구분, 캐시 장애 때 원본이 감당할 부하를 확인한다. [S24]
**조건을 붙인 답변 예시**
> 같은 조회의 반복 비용이 목표를 넘고, 이 데이터에는 합의된 범위의 오래된 값을 허용한다고 가정했습니다. 여러 인스턴스가 같은 결과를 반복 계산하므로 공유 캐시를 비교할 이유가 있습니다. 다만 적중률과 전체 지연의 개선을 확인하고, 무효화 경쟁·장애 시 원본 부하·운영 비용을 포함해 선택해야 합니다. 강한 정합성이 필수로 바뀌거나 실제 재사용 이익이 작다면 캐시 제거 또는 다른 조회 방식도 다시 비교하겠습니다.
“트래픽이 늘면 재검토”보다 “목표 지연을 넘는 원인이 반복 조회인지, 캐시 적중 이익이 비용을 상쇄하는지 확인되면 재검토”가 더 유효한 조건이다. 합의하지 않은 숫자를 일반적인 합격선으로 만들지 않는다.
### 41.8 경계·추상화 예시 — 구현체가 하나인데 왜 Interface인가
`UserRepository`가 하나의 JPA 구현만 가져도 애플리케이션이 의존할 계약과 영속 구현을 분리할 이유는 있을 수 있다. 구현체 수보다 **실제로 무엇을 격리하는지** 확인한다.
- 애플리케이션에 필요한 업무 계약을 정의하는가?
- 반환 타입·예외·지연 로딩·트랜잭션 전제가 구현 기술을 그대로 노출하는가?
- 실제 변경을 격리하거나 필요한 테스트 대역을 제공하는가?
- 중복 선언·매핑·탐색 비용에 비해 이득이 있는가?
**조건을 붙인 답변 예시**
> 이 인터페이스는 구현체 교체 가능성을 막연히 대비하기보다, 애플리케이션이 사용할 저장 계약을 영속 기술과 분리하기 위한 경계로 해석할 수 있습니다. 그 해석이 맞으려면 호출부가 JPA의 타입·예외·세션 수명에 계속 의존하는지도 확인해야 합니다. 실제 격리 가치가 없고 같은 호출을 전달하는 선언만 늘어난다면 경계를 좁히거나 제거하는 대안이 있습니다.
순수한 `NameFormatter`라도 구현 교체·정책 주입 계약이 실제로 필요하면 인터페이스가 의미 있을 수 있다. 반대로 그런 경계가 없으면 함수나 구체 클래스만으로 충분할 수 있다. “외부 I/O가 없으니 무조건 삭제”와 “아키텍처 패턴이니 무조건 유지” 모두 근거가 부족하다.
### 41.9 실패·운영 예시 — 왜 이 재시도 정책인가
`retry(3)`에서는 먼저 최초 시도를 포함한 총 세 번인지, 최초 이후 재시도 세 번인지 확인한다. 횟수 외에도 다시 수행해도 되는 작업인지, 실패 원인이 회복 가능한지, 응답을 기다릴 시간이 남았는지가 중요하다.
| 확인할 조건 | 판단에 미치는 영향 |
| --- | --- |
| 실제 작업 의미 | GET·POST라는 이름만으로 사용자 정의 API의 모든 부작용을 추정하지 않는다. HTTP의 표준 의미와 실제 서버 계약을 함께 확인한다. [S23] |
| 실패·결과 불명 | 응답을 못 받았다는 사실과 서버에서 적용하지 않았다는 사실을 구분한다. |
| 멱등 처리 계약 | 헤더 존재뿐 아니라 서버의 키 범위·유효 기간·입력 일치·동시 요청 처리·결과 재현을 확인한다. [S10] |
| 실패 원인 | 일시 장애와 잘못된 입력·권한·영구 실패를 구분한다. 다시 호출해도 나아지지 않는 실패는 반복하지 않는다. |
| 시간·횟수·부하 | 전체 deadline, 요청별 timeout, 상한, 간격, jitter, 여러 계층의 중복 재시도를 함께 본다. [S3] |
| 서버의 대기 안내 | 적용되는 Retry-After와 남은 시간 예산을 함께 판단한다. 기다릴 여유가 없으면 현재 요청 안의 재시도를 종료한다. [S23] |
| 취소·요청 재생 | 취소 이후 예약이 남는지, body 등을 같은 의미로 다시 보낼 수 있는지 확인한다. |
**조건을 붙인 답변 예시**
> 이 작업은 서버가 동일 업무 키에 대해 중복 효과를 억제하고, 같은 입력의 결과를 다시 확인할 수 있다는 전제에서만 재시도합니다. 일시 실패에는 정한 시간·횟수 예산 안에서 간격을 두되, 결제 응답이 유실된 경우를 곧바로 결제 실패로 바꾸지는 않습니다. 키가 만료됐거나 중복 방지 계약을 확인할 수 없으면 새 키로 다시 결제하는 대신 상태 조회·대사 경로를 검토합니다.
멱등키를 붙이는 것과 안전한 재시도가 같은 말은 아니다. key와 업무 효과를 따로 저장해 중간에 중단될 수 있다면 보호가 깨질 수 있다. 외부 제공자의 멱등 계약과 로컬 처리의 보장 범위를 연결해서 확인한다. [S10]
전송 재시도와 업무 재시작도 구분한다. 일정 시간 뒤 업무를 다시 시도해야 한다면 호출 스택 안의 재시도 횟수를 늘리는 대신, 지속 가능한 작업 상태와 재개 정책이 필요한지 검토한다. 이것도 현재 요구가 있을 때의 대안이다.
### 41.10 설명의 깊이와 후속 답변 양식
| 선택의 영향 | 보통 충분한 표현 위치 | 설명할 핵심 |
| --- | --- | --- |
| 지역적이고 명백한 계산 | 이름·표현식·작은 함수 | 입력과 결과 |
| 객체의 상태·소유권 | 타입·생성자·변경/반환 API, 필요한 짧은 주석 | 변경 권한, 공유 참조, 보호할 규칙 |
| 공개 API·모듈 계약 | 계약 문서와 필요한 경계 검증 | 허용 입력·결과·오류·호환성 |
| 트랜잭션·재시도·인가 | 실행 경계, 중요한 실패 검증, 짧은 근거 | 부분 실패·우회·동시성·남는 책임 |
| 여러 팀·프로젝트에 영향을 주는 구조 | 기존 설계 기록 또는 ADR와 코드 연결 | 후보 비교, 비용, 이행·철회·재검토 조건 |
표는 새로운 문서의 필수 목록이 아니다. 기존 자료로 충분하면 연결해서 사용한다. 모든 메서드에 annotation이나 결정 ID를 붙이지 않고, 같은 설명을 코드·문서·표에 반복해 수동으로 맞추게 만들지 않는다.
후속 질문에는 먼저 결론을 짧게 답한 뒤 필요한 근거를 펼친다. 다음 양식은 긴 설명이 필요한 경우에 쓰며 항목 수를 채우기 위해 내용을 늘리지 않는다.
> **판단:** 현재의 [확인된 조건]에서는 [선택 유지/변경/조건부 판단]가 타당합니다.
> **보호할 성질:** [누가 어떤 상황에서도 무엇을 지켜야 하는가].
> **현재 근거:** [코드·계약·기록·검증]에서 [보장]을 확인했습니다. [남은 범위]는 확인하지 못했습니다.
> **대안과 차이:** [단순한 대안]은 [장점]이 있지만 [필수 요구 미충족 또는 추가 비용]이 있습니다.
> **감수한 비용과 한계:** 현재 선택에는 [비용]이 남으며 [보장하지 않는 것]은 별도 책임입니다.
> **재검토 조건:** [구체적인 요구·측정·계약 변화]가 생기면 [대안]을 다시 비교합니다.
작성 이력 없이 선택 이유를 설명할 때는 “작성자가 이렇게 생각했다” 대신 **“현재 조건에서 이 선택을 유지할 근거는 다음과 같다”**고 말한다. 리뷰 과정에서 새로 정한 결정이라면 새 결정이라는 사실을 남긴다.
대안의 장점도 공정하게 설명한다. `unmodifiableList`는 스냅샷에는 부족하지만 live view가 필요한 계약에는 적합하다. 어떤 대안도 통과할 수 없도록 현재 구현에 유리한 요구를 뒤늦게 만드는 설명은 검증으로 인정하지 않는다.
### 41.11 통과 여부와 리뷰를 끝내는 기준
중요한 선택 하나를 놓고 다음 후속 질문을 해본다.
1. 가장 단순한 대안으로 바꾸면 구체적으로 무엇이 달라지는가?
2. 그 문제가 발생하는 입력·순서·실패 조건 또는 변경 과제는 무엇인가?
3. 지금 구현에서 그 문제를 막는 경계는 어디인가?
4. 무엇은 여전히 보장하지 못하며, 누가 그 책임을 갖는가?
5. 어떤 조건이나 증거가 나오면 지금 결론을 바꾸겠는가?
| 검토 결과 | 처리 |
| --- | --- |
| 요구·현재 구현·대안 비교가 맞고 제한이 허용된다. | 선택을 유지할 수 있다. 수정하지 않는 것도 유효한 결과다. |
| 선택은 타당하지만 중요한 이유가 작성자의 설명에만 있다. | 이름·계약·가까운 주석·기존 기록 연결 중 가장 작은 보강을 한다. |
| 이유는 타당하지만 현재 구현이 그 보장을 하지 못한다. | 설명 개선으로 닫지 않고 구현·검증의 문제로 기록한다. |
| 현재 코드가 맞을 수 있지만 핵심 요구나 계약을 모른다. | 미확인 전제와 필요한 확인을 남긴다. 결함이나 합격으로 단정하지 않는다. |
| 같은 요구를 더 적은 비용으로 충족하는 대안의 근거가 있다. | 이행 비용과 보호할 계약을 포함해 변경을 제안한다. |
리뷰어에게 필요한 것은 모든 기술의 대안을 즉시 암기해 말하는 능력이 아니다. 모르는 계약을 식별하고, 해당 버전의 1차 자료와 실제 코드·실험으로 확인한 뒤 판단을 갱신하는 능력이다.
대표 선택의 판단에 충분한 근거가 모였으면 검토를 마친다. 선택 이유를 설명하기 위해 새 프레임워크·대규모 문서 체계·관성적인 테스트를 추가하지 않는다. **다음 수정자가 같은 근거로 선택을 유지하거나 바꿀 수 있으면 이 검토의 목적을 달성한 것이다.**