From 412b3d1f1e04c40d6023bfe82d0a9fc5a47648f1 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 21:05:08 +0900 Subject: [PATCH 001/185] docs: add the maturity review guide and the 2026-09-25 full review CLAUDE.md makes the guide the standing review standard for this repo. The review folder holds 14 area reports and the summary with the 28-perspective table and the finding index. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 26 + .../01-adapters-browser-transfer.md | 340 +++++ .../02-adapters-browser-files-cache.md | 295 ++++ .../03-adapters-http-state.md | 248 +++ .../04-adapters-realtime.md | 281 ++++ .../05-adapters-storage-kernel.md | 383 +++++ .../06-adapters-service-worker-push.md | 299 ++++ .../07-contracts.md | 292 ++++ .../08-presentation.md | 364 +++++ .../2026-09-25-maturity-review/09-app-core.md | 313 ++++ .../10-tests-fast-layers.md | 234 +++ .../11-tests-browser-release-scale.md | 251 ++++ .../12-guardrails-ci.md | 325 ++++ .../13-build-release-supply-chain.md | 399 +++++ .../14-template-product-docs.md | 266 ++++ .../2026-09-25-maturity-review/README.md | 394 +++++ .../reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md | 1323 +++++++++++++++++ 17 files changed, 6033 insertions(+) create mode 100644 CLAUDE.md create mode 100644 docs/reviews/2026-09-25-maturity-review/01-adapters-browser-transfer.md create mode 100644 docs/reviews/2026-09-25-maturity-review/02-adapters-browser-files-cache.md create mode 100644 docs/reviews/2026-09-25-maturity-review/03-adapters-http-state.md create mode 100644 docs/reviews/2026-09-25-maturity-review/04-adapters-realtime.md create mode 100644 docs/reviews/2026-09-25-maturity-review/05-adapters-storage-kernel.md create mode 100644 docs/reviews/2026-09-25-maturity-review/06-adapters-service-worker-push.md create mode 100644 docs/reviews/2026-09-25-maturity-review/07-contracts.md create mode 100644 docs/reviews/2026-09-25-maturity-review/08-presentation.md create mode 100644 docs/reviews/2026-09-25-maturity-review/09-app-core.md create mode 100644 docs/reviews/2026-09-25-maturity-review/10-tests-fast-layers.md create mode 100644 docs/reviews/2026-09-25-maturity-review/11-tests-browser-release-scale.md create mode 100644 docs/reviews/2026-09-25-maturity-review/12-guardrails-ci.md create mode 100644 docs/reviews/2026-09-25-maturity-review/13-build-release-supply-chain.md create mode 100644 docs/reviews/2026-09-25-maturity-review/14-template-product-docs.md create mode 100644 docs/reviews/2026-09-25-maturity-review/README.md create mode 100644 docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..6c9a9ac2 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,26 @@ +# CLAUDE.md + +## 리뷰 기준 (모든 리뷰에 적용) + +이 repo를 리뷰할 때는 전체 리뷰든 모듈·PR·diff 리뷰든 [`docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`](docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md)를 기준으로 한다. + +- 발견 사항은 가이드의 28개 관점 번호로 분류한다. 결함 하나는 항목 하나로 적고 관련 관점 번호를 모두 붙인다(0.3절). 같은 결함을 여러 번 세지 않는다. +- 성격(확인된 결함 / 구조적 위험 / 미검증 / 개선 제안), 심각도(Critical~Low), 우선순위(P0~P3), 통제 수준(M0~M4), 증거(E0~E4)를 따로 적는다(35절). 확인하지 못한 것은 M0가 아니라 `미확인`이다. +- 발견 사항은 36.3절 양식, 최종 요약은 36.5절 양식, 관점별 판정은 36.2절 표를 쓴다. +- README와 설계 문서는 주장이다. 근거는 현재 커밋의 코드·설정·실행 결과에서 찾는다(34.1절). 이전 리뷰의 실행 결과를 현재 증거로 재사용하지 않는다. +- 리뷰에서는 코드를 고치지 않는다. 고치는 작업은 리뷰 문서를 근거로 별도로 진행한다. + +### 이 repo의 리뷰 전제 + +- 이 repo는 템플릿(reference implementation)이다. repo 안에 소비자가 없는 코드와 빈 레지스트리는 다운스트림용 확장 지점이지 죽은 코드가 아니다. 다만 갈라진 중복 복사본은 문제로 본다. +- adapter 배럴(`src/adapters/*/index.ts`)이 공개 경계다. +- adapter끼리 import할 수 있는 예외는 `.dependency-cruiser.json`의 kernel 예외(`src/adapters/platform/` 폴더 전체, `browser-file-storage/result.ts`, `cross-context-invalidation/index.ts`)뿐이다. 새 파일 단위 예외를 제안하지 않는다. +- 실행 형태는 브라우저 SPA + 정적 호스팅 + Service Worker다. SSR은 없다. + +### 전체 리뷰 절차 + +1. 기준 커밋과 가이드 0.1절 전제 표를 먼저 고정한다. +2. 게이트를 직접 실행하고 결과를 기록한다: `check:architecture`, `check:types`, `lint`, `test:unit`, `test:component`, `test:integration`, `test:contract`, `test:runtime-schema`, `verify:documentation`, `check:adapter-inventory`, `check:ci`. +3. 영역별로 서브에이전트를 병렬로 띄운다. 영역 분할은 가장 최근 `docs/reviews/*-maturity-review/README.md`의 영역 표를 재사용한다. +4. 각 에이전트는 `docs/reviews/-maturity-review/NN-<영역>.md`에 결과를 쓴다. +5. 오케스트레이터는 High 이상 발견을 코드에서 직접 재확인한 뒤 같은 폴더의 `README.md`에 범위(36.1), 28개 관점 판정표(36.2), 최종 요약(36.5), 발견 색인을 쓴다. diff --git a/docs/reviews/2026-09-25-maturity-review/01-adapters-browser-transfer.md b/docs/reviews/2026-09-25-maturity-review/01-adapters-browser-transfer.md new file mode 100644 index 00000000..fd8786d6 --- /dev/null +++ b/docs/reviews/2026-09-25-maturity-review/01-adapters-browser-transfer.md @@ -0,0 +1,340 @@ +# browser-transfer 성숙도 리뷰 + +> 검토일: 2026-09-25 · 기준: `main` / `4626b73` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 범위: `src/adapters/browser-transfer/` 전체 27파일 약 12.4k줄(`resumable-upload/` 13, `presigned/` 6, `image-cdn/` 7, 배럴 1), 이 영역이 구현하는 port `src/application/ports/browser-transfer/*`(766줄), 영역 단위 테스트 14파일 +> 영역 판정(35.8): **조건부 사용 가능** — 기본 production 구성에는 조립돼 있지 않다(`AVAILABLE_NOT_COMPOSED`). 다운스트림이 조립할 때 01-01~01-05의 조건을 관리해야 한다. + +## 1. 결론 + +- **막혀 있는 것.** presigned capability는 URL이 아닌 1회용 식별 handle이고 HTTPS·redirect 금지·자격증명 제외·경로 이중 인코딩 차단이 걸려 있다. 재시도는 runtime 한 계층에만 있다. dispose·fail-fast·ABORT_PENDING·complete 결과 불명 조정이 구현돼 있고 테스트가 잡는다. 직전 리뷰 6.1-1~6.1-11은 모두 현재 코드에 반영돼 있다. +- **고칠 것(Medium, P2).** object store PUT이 401/403을 돌려주거나 실행기가 capability 만료를 판정하면 capability를 다시 받지 않는다. 그 대신 `upload()` 전체가 `PERMISSION_DENIED`/`EXPIRED_RESOURCE`, `retryable:false`로 끝난다. 설계 문서 3.2·4.2절과 반대다(01-01). +- **결과 불명(29.2).** complete 응답을 잃으면 `UNAVAILABLE/RESUME` 실패가 되고 checkpoint는 남는다. 같은 파일로 `upload()`를 다시 부르면 서버 상태로 조정된다. 하지만 그 밖에는 상태를 볼 방법이 없다. `abort()`를 부르면 `ALREADY_COMPLETED`만 돌려받고, resourceId와 checkpoint를 함께 잃는다(01-02). +- **검증 공백.** 이 조정을 받치는 규칙은 "재시도·재개 때 같은 idempotency key를 쓴다"이다. 그런데 이 규칙을 고정한 테스트가 없다. key를 시도마다 바꾸는 변형을 넣어도 168개 테스트가 모두 통과했다(01-04). +- **시간 제한이 바이트 수와 무관하다.** part 전송 한 번의 제한 시간은 기본 30초, part 크기는 기본 5MiB다. 업링크가 약 1.4Mbit/s보다 느리면 업로드가 전혀 진행되지 않는다. download는 본문 전체에 deadline이 하나뿐이다(01-03). 또 호출자가 실패의 `recovery` 값만 보고 할 일을 고를 수 없다(01-05). +- **미검증.** 실제 브라우저 스펙 3개(Playwright), 실제 object store·BFF의 403/재발급/complete 소요 시간, part 버퍼 메모리 실측은 확인하지 않았다. + +## 2. 범위와 방법 (36.1) + +| 항목 | 기록 | +| --- | --- | +| 대상 | `src/adapters/browser-transfer/**`, `src/application/ports/browser-transfer/**`, 영역을 쓰는 kernel(`src/adapters/platform/abortable-operation.ts`, `indexeddb-connection.ts`) | +| 커밋·상태 | `main` `4626b73`. 주 워킹트리에서 수정한 파일 없음 | +| 읽은 코드 | resumable-upload 13파일 전부(runtime·정책·검증·checkpoint store·lock·취소 채널·HTTP control plane·fetch 전송·part 실행기), presigned 6파일 전부, image-cdn은 runtime·probe 요지·정책 상한·README | +| 읽은 문서(주장으로만 사용) | `docs/architecture/presigned-transfer-and-image-cdn.md`, `server-file-capability-infrastructure.md` 8·10절, `browser-data-capability-completion-ledger.md` 4.4, `SPEC.md`, `tasks/todo.md`, 직전 리뷰 6.1 | +| 실행한 테스트 | `node scripts/run-vitest.ts run` + 영역 단위 테스트 14파일(image-cdn 3, presigned 4, resumable 6, 취소 채널 1) → **14 files / 199 tests 통과** | +| 실험(분리 worktree) | `git worktree add --detach /01/wt HEAD`로 분리했다. 끝난 뒤 제거했다. 사용한 파일: 실험 테스트 `zz-area01-experiments.test.ts`(scratchpad 보관), 변형 스크립트 `mutate.sh` | +| 실험 X1 | 첫 PUT만 403과 같은 실패(`PERMISSION_DENIED, retryable:false, REISSUE_CAPABILITY`)를 내고 둘째는 성공하는 실행기를 붙였다. 결과: `upload()` → `{code:PERMISSION_DENIED, operation:UPLOAD_PART, retryable:false, recovery:REISSUE_CAPABILITY}`. PUT 1회, 발급 1회 | +| 실험 X2 | complete가 서버에는 반영되지만 응답은 timeout과 같은 실패를 낸다. 결과: `upload()` → `UNAVAILABLE/UPLOAD_COMPLETE/retryable:true/RESUME`. 이어서 `abort()` → `{state:"ALREADY_COMPLETED"}`, checkpoint 0행 | +| 실험 X3 | 기본 attempt 제한 30초 조건에서 PUT에 42초(5MiB를 1Mbit/s로 보내는 시간)가 걸리게 했다. 결과: PUT 4번 시작, `UNAVAILABLE/UPLOAD_PART/retryable:true/RESUME` | +| 변형 검출 | 아래 표. 대상은 resumable·presigned 테스트 11파일 168개 | +| SHA-256 대조 | `presigned/incremental-sha256.ts`와 `node:crypto`를 0~299바이트, 블록 경계, 1MiB+1 입력으로 대조했다. 무작위 chunk 분할을 포함해 1,830건 비교, 불일치 0건 | +| 확인하지 못한 범위 | Playwright 스펙(`tests/browser-capabilities/resumable-upload.spec.ts`, `presigned-streaming.spec.ts`, `image-cdn.spec.ts`): 브라우저 실행이 필요하다. `test:browser-file-storage-removal`: `.tmp`에 fixture를 만들고 pnpm을 실행하는 무거운 스크립트라 동시 작업 중에 돌리지 않았다. `check:architecture`·`check:types`: 오케스트레이터 담당 | +| 직전 리뷰와 비교 | 6.1-1~11을 현재 코드에서 다시 확인했다. 모두 반영돼 있다(아래 표) | + +**변형 검출 결과** (코드 한 곳을 일부러 틀리게 바꾸고 테스트가 실패하는지 본 것) + +| ID | 바꾼 것 | 결과 | +| --- | --- | --- | +| M1 | PART/COMPLETE/ABORT idempotency key에 호출마다 난수 추가 (`upload-byte-source.ts:301`) | **168 통과 — 검출 못 함** | +| M6 | complete key를 재시도 시도마다 바꿈 (`resumable-upload-runtime.ts:1070`) | **168 통과 — 검출 못 함** | +| M7 | create key를 재시도 시도마다 바꿈 (`resumable-upload-runtime.ts:649`) | **168 통과 — 검출 못 함** | +| M2 | worker 실패 시 형제 abort 제거 (`:772`) | 1 실패 — 검출 | +| M3 | abort에서 `ABORT_PENDING` 기록 생략 (`:1135`) | 1 실패 — 검출 | +| M4 | status `QUARANTINED` 조정 제거 (`:560`) | 1 실패 — 검출 | +| M5 | provider 실패 재시도 금지 (`:1397`) | 2 실패 — 검출 | + +**직전 리뷰 6.1 재확인**: 6.1-1 `drain = null` 재시도(`resumable-upload-runtime.ts:294-302`), 6.1-2 `SAFE_TRANSFER_ID`가 `SAFE_OPAQUE_ID`의 상위 집합(`checkpoint-schema.ts:15-22`), 6.1-3 `partSize×maxConcurrency×copyFactor` 검증과 기본 동시성 1(`runtime-policy.ts:52-55, 89-92`), 6.1-4 `LIMIT_EXCEEDED`(`resumable-upload-runtime.ts:341-348`), 6.1-5 fail-fast(`:758-773`), 6.1-6 `removeUnreadable`(`:1115-1129`), 6.1-7 fit 제한(`image-cdn-policy.ts:492-495`), 6.1-8 `imageOrientation:"none"`(`browser-image-probe.ts:60`), 6.1-9 `presigned/http-common.ts` 통합·엄격 Content-Length·kernel attempt, 6.1-10 runtime 2298→1629줄, 6.1-11 vault snapshot만 읽음(`presigned-capability-vault.ts:278-287`). 모두 반영. + +### 2.1 대표 호출 추적 — complete 응답을 잃은 경우 (29.2) + +```text +upload(request) + → 파일 전체 읽기 + part별 SHA-256 (manifest) resumable-upload-runtime.ts:349 + → checkpoint 읽기 → getStatus(ACTIVE) → 빠진 part PUT :371, :394, :406 + → complete(같은 COMPLETE key) ── 서버 반영, 응답 유실(30초 timeout) + → 같은 key로 최대 3번 더 → 모두 timeout :1059-1074 + ← { UNAVAILABLE, UPLOAD_COMPLETE, retryable:true, RESUME } checkpoint(ACTIVE, 모든 part 수락) 남음 + +경로 A: 같은 파일로 upload() 다시 → 파일 전체 재해시 → getStatus = QUARANTINED + → checkpoint 삭제 → { QUARANTINED, resourceId, replayed:true } :560-577 +경로 B: 사용자가 취소 → abort() → ABORT_PENDING 기록 → 서버 abort = ALREADY_COMPLETED + → checkpoint 삭제 → { state: ALREADY_COMPLETED } (resourceId 없음) :1204-1216 +``` + +경로 A는 동작하고 테스트도 있다(`tests/unit/resumable-upload-runtime.test.ts:990`). 경로 B는 실험 X2로 확인했다. + +### 2.2 29.4 문장 — `ResumableUploadRuntime.upload()` + +> 이 호출은 **서버 control plane**에 upload session을 만들고(요청 binding에서 유도한 고정 `CREATE` key), part마다 **object store**에 presigned PUT으로 bytes를 쓰고, complete로 서버에 `QUARANTINED` 자원을 만든다. 그리고 **브라우저 IndexedDB**(계정 partition DB)에 checkpoint 행을 쓰고, 성공하면 지운다. +> **기다리는 시간**: 호출 전체 deadline은 없고 caller signal이 유일한 상한이다. 외부 호출 한 번은 `providerAttemptTimeoutMs`(기본 30초) 안에 끝나야 한다. fetch 전송 자체도 30초, presigned 실행기는 composition이 준 `timeoutMs`를 쓴다. 같은 uploadKey의 Web Lock 대기에는 상한이 없다. +> **재시도**: runtime 한 계층에서만, `retryable:true` 실패에 대해 최대 `maxRetries`(기본 3)번 한다. 간격은 250ms~5s 지수 backoff에 jitter를 섞고, 30초 이하의 `Retry-After`를 따른다. 재시도에는 같은 idempotency key를 쓴다. PUT의 401/403과 실행기의 만료 판정은 재시도하지 않는다(01-01). +> **동시 실행**: 같은 uploadKey는 Web Lock으로 한 번에 하나만 실행하고, checkpoint는 revision 비교(CAS)로 갱신한다. 다른 탭에서 abort하면 BroadcastChannel로 진행 중 작업을 끊는다. +> **응답을 잃으면**: `UNAVAILABLE/RESUME` 실패를 반환한다. 모든 part가 수락된 ACTIVE checkpoint가 남는다. +> **확인·조정**: 같은 파일로 `upload()`를 다시 부르는 방법뿐이다. 그러면 전체 파일을 다시 해시한 뒤 `getStatus`로 조정한다. 파일 없이 상태를 조회하는 API는 없다. `abort()`는 resourceId 없이 `ALREADY_COMPLETED`를 준다(01-02). + +## 3. 확인된 강점 + +1. **presigned capability가 새지 않는다.** 등록 객체를 한 번만 복사해 검증한다. handle은 WeakMap identity로 관리하고, 1회 claim 뒤 consume한다. HTTPS만 허용하고 ambient 자격증명 헤더를 금지한다(`presigned-capability-vault.ts:167-330`). 데이터 요청은 `credentials:"omit"`, `redirect:"error"`, `no-referrer`, 응답 URL 정확 일치를 쓴다(`presigned-transfer-executor.ts:343-363, 1011-1021`). 경로 퍼센트 인코딩 재해석도 막는다(`presigned-capability-http-provider.ts:991-1036`). checkpoint에는 정확한 key 목록만 저장할 수 있어 URL·자격증명이 들어갈 수 없다(`checkpoint-schema.ts:29-143`, 테스트 `resumable-upload-checkpoint.test.ts:295`). +2. **재시도 중첩이 없다.** fetch 전송(`fetch-json-transport.ts:144-276`), 발급 provider, presigned 실행기는 재시도하지 않는다. 재시도는 runtime의 `callWithRetry`/`uploadPartWithRetry`만 하며 상한·jitter·`Retry-After` 상한이 있다(`resumable-upload-runtime.ts:1235-1404`). idempotency key는 요청 binding과 session·part에서 결정적으로 만들어진다(`upload-byte-source.ts:289-326`). +3. **결과 불명인 complete·abort를 버리지 않는다.** 모든 part가 수락된 checkpoint를 남기고, 다음 호출에서 서버 상태로 조정한다(`resumable-upload-runtime.ts:560-577`). abort는 먼저 `ABORT_PENDING`을 기록하고, 서버 확인 뒤에만 지운다(`:1135-1151`). 둘 다 테스트가 있고 변형 M3·M4를 잡았다. +4. **수명과 동시성.** worker 하나가 실패하면 형제를 즉시 끊는다(`:758-773`, M2 검출). receipt 저장은 한 줄로 직렬화하고 revision CAS를 쓴다(`:708-750`). `dispose()`는 wrapper뿐 아니라 실제 provider 작업까지 기다리고, 시간 초과로 실패하면 나중에 다시 부를 수 있다(`:279-332`, 테스트 `resumable-upload-runtime-teardown.test.ts:191`). +5. **메모리 상한을 시작 전에 검사한다.** `partSize × maxConcurrency × copyFactor ≤ maxInFlightBytes`(`runtime-policy.ts:89-92`)를 본다. JSON 응답·발급 응답·업로드 응답 본문을 hard cap 안에서 읽는다(`fetch-json-transport.ts:413-517`, `presigned-capability-http-provider.ts:761-813`, `presigned-transfer-executor.ts:876-933`). download chunk는 `hardMaxChunkBytes`로 다시 자르고, 직접 구현한 SHA-256으로 스트리밍 검증한다(대조 1,830건 일치). +6. **계정 범위와 삭제.** checkpoint DB 이름은 opaque scope token 3개를 길이 접두어로 묶고, 열 때 governance 행으로 scope를 대조한다(`indexeddb-checkpoint-store.ts:172-182, 565-599`). `deletePartition()`은 연결을 닫고 삭제를 보낸다. 삭제 요청이 막히면 성공인 척하지 않고 `PENDING/UNKNOWN`으로 보고한다(`:457-507`). + +## 4. 발견 사항 (36.3) + +### 01-01 object store PUT의 401/403과 실행기의 만료 판정이 capability 재발급 없이 `upload()` 전체 실패로 끝난다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(설계 문서의 계약과 구현 불일치) | +| 관련 관점 | 6, 5, 17, 24 | +| 근거 | PUT 응답 401/403은 `PERMISSION_DENIED, retryable:false, recovery:REISSUE_CAPABILITY`가 된다(`presigned/http-common.ts:141-143`). 실행기가 잔여 수명 부족을 판정하면 `EXPIRED_RESOURCE, retryable:false`다(`presigned-transfer-executor.ts:990-996`). part 실행기는 이 값을 그대로 넘긴다(`resumable-upload/presigned-upload-part-executor.ts:105`). runtime은 `retryable`만 보고 바로 반환한다(`resumable-upload-runtime.ts:1017-1020`). 같은 루프는 시도마다 capability를 새로 발급한다(`:938-954`). 따라서 재시도만 허용하면 재발급이 된다. 지금은 runtime이 스스로 만료를 판정한 경우만 재발급한다(`:968-980`). 문서는 반대로 말한다. `presigned-transfer-and-image-cdn.md:167` "만료/403은 … control plane의 새 capability 발급으로 복구한다", `:263` "만료/authorization failure는 최대 정책 범위 안에서 capability를 재발급한다". 실험 X1에서 재현했다 | +| 발생 조건 | presigned URL이 표기된 만료보다 먼저 무효가 되는 경우(서명에 쓴 임시 자격증명 만료 — 문서 3.1이 인정). 기기 시계와 object store 시계가 다른 경우. 실행기 `minimumRemainingLifetimeMs`가 runtime `capabilityRefreshSkewMs`(기본 5초)보다 큰 조합. 두 값은 서로 검사하지 않는다 | +| 영향 | part 하나의 일시적 403으로 파일 업로드가 끝난다. 호출자는 "권한 없음"으로 읽히는 코드를 `retryable:false`로 받아 자동 재개하지 않는다. checkpoint는 남으므로 `upload()`를 다시 부르면 이어진다. 데이터 손상은 없다 | +| 심각도·우선순위 | Medium · P2 — 흔한 운영 조건에서 사용자 흐름이 끊기지만 재호출로 복구되고 데이터 피해는 없다. 조립하는 다운스트림에 그대로 복제된다 | +| 통제·증거 | M1(문서만 있고 구현이 반대) · E2(실험 X1). 관련 테스트 없음 | +| 확실성과 남은 가정 | 코드 경로와 실험으로 확인했다. 실제 S3/GCS가 어떤 조건에서 403을 내는지는 이 repo 밖이다 | +| 최소 개선 방향 | `uploadPartWithRetry`에서 PUT 단계의 `recovery === "REISSUE_CAPABILITY"` 실패(401/403/만료)를 `maxRetries` 안에서 재시도 대상으로 본다. 다음 시도가 새 capability를 받는다. BFF 발급 단계의 401/403은 지금처럼 멈춘다 | +| 비용·부작용 | 몇 줄. 진짜 권한 박탈이면 발급 요청이 최대 `maxRetries`번 더 나간다(상한 있음) | +| 완료 기준 | 첫 PUT 403, 둘째 성공이면 `upload()`가 성공하고 발급이 2회 일어난다. 발급 endpoint의 403은 재시도 없이 실패한다 | +| 검증 방법 | 실험 X1을 단위 테스트로 옮긴다. 실제 `createPresignedTransferExecutor`에 403을 주는 fetch fake를 붙인 조합으로 한 번 더 확인한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 01-02 완료됐거나 완료 여부를 모르는 업로드가 일반 실패로 보고되고, resourceId를 되찾는 길이 "같은 파일로 `upload()` 재실행"뿐이다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험(한 경로는 확인된 결함) | +| 관련 관점 | 6, 5, 17, 28, 11 | +| 근거 | ① complete 응답 유실: 전송 timeout은 `UNAVAILABLE, retryable:true, RESUME`이다(`fetch-json-transport.ts:586-593`). runtime은 같은 key로 재시도한 뒤 그대로 반환한다(`resumable-upload-runtime.ts:1059-1074`). 실패 타입에는 "결과 불명" 값이 없다(`application/ports/browser-file-storage/shared.ts:8-27, 67-80`). 문서 실패표도 네트워크 오류와 합친다(`presigned-transfer-and-image-cdn.md:632`). ② **확인된 결함**: 서버가 resourceId를 이미 돌려줬는데도 로컬 checkpoint 삭제가 실패하면 실패를 반환하고 resourceId를 버린다(`resumable-upload-runtime.ts:1098-1103`). complete 직후 caller signal이 abort되면 삭제가 `ABORTED`로 끝나 같은 결과가 된다. ③ `abort()`는 서버가 `ALREADY_COMPLETED`를 주면 checkpoint를 지우고 state만 반환한다(`:1204-1216`). 반환 타입 `UploadAbortOutcome`에 resourceId가 없다(`application/ports/browser-transfer/resumable-upload.ts:93-95`). 실험 X2로 확인했다. ④ port에 상태 조회 메서드가 없다(`resumable-upload.ts:97-105`). 조정은 `upload()`가 파일 전체를 다시 읽고 해시한 뒤(`resumable-upload-runtime.ts:349-359`) `getStatus`로만 한다. ⑤ 서버 complete가 30초를 넘기는 경우를 표현할 수단이 없다. status 계약에 "완료 중" 상태가 없다(`resumable-upload.ts:138-150`). 서버 문서가 정의한 `OPERATION_IN_PROGRESS`(`server-file-capability-infrastructure.md:897, 1125`)에도 wire 표현과 클라이언트 처리가 없다. 409로 오면 `CONFLICT, retryable:false`가 된다(`fetch-json-transport.ts:534-536`) | +| 발생 조건 | 큰 파일의 complete가 30초를 넘김(서버가 최종 길이·digest를 검증). 모바일에서 연결이 끊김. complete 직후 사용자 취소(signal abort와 `abort()`를 함께 부르는 흔한 취소 구현). IndexedDB 일시 실패 | +| 영향 | 앱은 실패를 보여 준다. 다시 시도하면 파일 전체를 재해시한 뒤 `replayed:true`로 성공한다(5GiB면 수 분). 취소하면 서버에는 `QUARANTINED` 자원이 남고, 클라이언트는 그 ID를 알 방법이 없다. 업무 레코드에 연결되지 않은 고아 자원이 생긴다. 같은 파일을 다시 올리면 서버 idempotency 보관 기간에 따라 중복 자원이 생길 수 있다 | +| 심각도·우선순위 | Medium · P2 — 부작용 중복 실행은 같은 key로 막혀 있어 High 조건(무방비 재실행)은 아니다. 피해는 고아 자원과 거짓 실패 표시다 | +| 통제·증거 | 재개 경로 M2 · E2(테스트 `resumable-upload-runtime.test.ts:990`). 손실 경로 M0(통제 없음 확인) · E2(실험 X2) | +| 확실성과 남은 가정 | ②·③은 코드와 실험으로 확정했다. ⑤의 서버 응답 코드는 서버 구현에 달려 있어 미확인이다 | +| 최소 개선 방향 | (1) complete가 성공한 뒤의 로컬 정리 실패는 성공으로 반환하고, 정리는 다음 호출에 맡긴다. (2) abort 결과가 `ALREADY_COMPLETED`이면 checkpoint를 지우기 전에 `getStatus`로 resourceId를 읽어 함께 반환한다. (3) 서버 계약에 complete 진행 중 상태(status 값 또는 retryable 응답 코드)를 정한다. (4) 선택: 파일 없이 uploadKey로 상태를 확인하는 port 메서드를 추가한다(비파괴 추가) | +| 비용·부작용 | (1)(2)는 작다. (3)은 서버와 wire 변경이라 버전 관리가 필요하다. (4)는 port 추가 | +| 완료 기준 | X2 시나리오에서 `abort()` 결과로 resourceId를 알 수 있다. complete 성공 뒤 삭제 실패를 주입하면 `upload()`가 성공을 반환한다 | +| 검증 방법 | X2와 "complete 성공 + remove 실패" 주입 테스트. 실제 서버 conformance는 control-plane fake로 in-progress 응답을 흉내 낸다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 01-03 전송 시간 제한이 바이트 수나 진행과 무관한 고정 값이다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 6, 14, 19 | +| 근거 | 기본 part 5MiB, `providerAttemptTimeoutMs` 30초다(`runtime-policy.ts:49, 64`). PUT 한 번(실행기 해시 포함)이 이 deadline 하나에 들어간다(`resumable-upload-runtime.ts:983-1001, 1308-1311`). 정책 검증은 part 크기와 제한 시간의 관계를 보지 않는다(`runtime-policy.ts:75-121`). 허용 최대치(64MiB part, 120초)끼리 짝지으면 4.5Mbit/s가 필요하다. 시간 초과 뒤 다음 시도는 같은 part를 처음부터 다시 보낸다. 실험 X3: PUT 4번 시작 후 `UNAVAILABLE/retryable:true`. download는 stream 시작부터 본문 끝까지 deadline이 하나이고, 진행이 있어도 연장되지 않는다(`presigned-transfer-executor.ts:543, 636-642`). 같은 `timeoutMs`를 PUT part와 전체 download가 함께 쓴다(`:60-78`) | +| 발생 조건 | 업링크가 약 1.4Mbit/s(5MiB/30초)보다 느림: 혼잡한 모바일, 약전계. download는 파일 크기를 `timeoutMs`로 나눈 속도보다 느린 경우 | +| 영향 | 업로드가 첫 미완료 part에서 멈춰 끝나지 않는다. `upload()`를 부를 때마다 part를 4번 보내고 버린다(기본 20MiB 낭비). `retryable:true`라 앱이 자동 재시도하면 이것이 반복된다. download는 큰 파일이 거의 끝날 무렵 실패할 수 있다 | +| 심각도·우선순위 | Medium · P2 — 해당 네트워크의 사용자에게는 기능이 동작하지 않는다. 기본값이 그대로 복제된다 | +| 통제·증거 | 처리량을 고려한 제한 M0(없음 확인) · E2(실험 X3) | +| 확실성과 남은 가정 | 산술과 실험으로 확인했다. 실제 사용자 업링크 분포는 미확인이다 | +| 최소 개선 방향 | attempt 제한을 "기본 시간 + part 바이트 / 최저 처리량"으로 계산하거나, 진행이 멈췄을 때만 끊는 idle timeout을 둔다. download는 idle 제한과 전체 상한을 분리한다. 정책 문서에 필요한 최저 처리량을 적는다 | +| 비용·부작용 | 작음~중간. idle timeout은 kernel(`src/adapters/platform/abortable-operation.ts`)에 없어서 kernel 확장이 필요하다 | +| 완료 기준 | 1Mbit/s 모의 환경에서 5MiB part가 성공한다. 진행이 멈춘 연결은 idle 제한 안에 끊긴다 | +| 검증 방법 | fake timer로 X3을 재현하는 테스트. download는 느린 chunk 스트림 fake | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 01-04 결과 불명 재시도의 핵심 규칙(같은 idempotency key 재사용)을 어떤 테스트도 고정하지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(테스트 검출력) | +| 관련 관점 | 10, 6, 21 | +| 근거 | 변형 M1·M6·M7은 key를 호출마다 또는 시도마다 바꾸는 변형이다. resumable·presigned 11파일 168개 테스트가 모두 통과했다. 같은 조건에서 M2~M5는 잡혔다. key 관련 단언은 "새 session이면 key가 다르다"뿐이다(`tests/unit/resumable-upload-runtime.test.ts:441-444`). 다른 공백도 있다. PUT 403 경로(01-01) 테스트가 없다. runtime에 실제 provider·vault·실행기를 붙인 단위 테스트가 없다(단위 테스트는 fake harness `resumable-upload-runtime-fixture.ts`, 실제 조합은 Playwright 정상 경로 1개 `tests/browser-capabilities/resumable-upload.spec.ts:42`). 직접 구현한 SHA-256의 표준 벡터는 "abc" 1개다(`tests/unit/presigned-transfer.test.ts:31-35`). 나머지 기대값은 검사 대상 함수로 직접 계산한다(`tests/unit/presigned-transfer-fixture.ts:16` 등). 구현 자체는 대조 1,830건에서 맞았다 | +| 발생 조건 | key 유도를 리팩터링할 때(시도 번호 포함, 요청마다 UUID 등) | +| 영향 | 게이트를 통과한 채 "결과 불명 쓰기를 새 식별자로 재실행"(가이드 6절 위험 신호)이 들어갈 수 있다. 그러면 서버에 session·complete가 중복된다. 템플릿이라 다운스트림이 그대로 가져간다 | +| 심각도·우선순위 | Medium · P2 — 현재 코드는 옳다. 다만 회귀가 나면 High급 피해 경로가 열리는데 검출 수단이 없다 | +| 통제·증거 | 구현 M2, 자동 검출 없음 · E2(변형 실행) | +| 확실성과 남은 가정 | 변형 실행으로 확정했다. Playwright 스펙이 key를 단언하는지는 읽은 범위에서 없었다 | +| 최소 개선 방향 | 테스트 3개를 추가한다. (a) complete 첫 시도 timeout, 둘째 성공 → 두 호출의 key가 같다. (b) 첫 `upload()`에서 complete 응답 유실 → 둘째 `upload()`의 complete key가 같다(재개해도 유지). (c) part 재시도 사이 발급 key가 같다. 01-01 테스트도 추가한다. SHA-256은 2블록 NIST 벡터와 `node:crypto` 대조를 추가한다 | +| 비용·부작용 | 작음 | +| 완료 기준 | M1·M6·M7 변형이 각각 테스트 하나 이상을 실패시킨다 | +| 검증 방법 | `scratchpad/01/mutate.sh`와 같은 방식으로 변형을 다시 실행한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 01-05 실패의 `recovery` 값이 호출자가 할 수 있는 행동과 1:1로 이어지지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 5, 17, 24, 8 | +| 근거 | port에는 `upload()`와 `abort()`뿐이다(`resumable-upload.ts:97-105`). 그런데 `upload()`는 할 일이 서로 다른 여러 경우에 `RECONCILE`을 돌려준다. ABORT_PENDING이면 `abort()`를 불러야 한다(`resumable-upload-runtime.ts:388-392`). IndexedDB CAS 충돌이면 `upload()`를 다시 부르면 된다(`indexeddb-checkpoint-store.ts:372-381`). 서버 상태와 manifest가 다르면(`INTEGRITY_FAILED`) `abort()` 후 재시작해야 한다(`upload-response-validation.ts:96-115`). 읽을 수 없는 행(`CORRUPT_DATA`)이면 `abort()`를 불러야 한다(`indexeddb-checkpoint-store.ts:336-341`). 앞의 둘은 실패값이 완전히 같다: `{CONFLICT, UPLOAD_RECONCILE, retryable:false, RECONCILE}`. `REISSUE_CAPABILITY`는 호출자가 직접 할 수 없는 동작인데 `retryable:false`와 함께 온다(01-01). 서버가 정책 상한보다 긴 session을 주면 `EXPIRED_RESOURCE/RESTART`인데(`upload-response-validation.ts:229-240`, 테스트 `resumable-upload-runtime-contract.test.ts:254`), 재시작해도 같은 응답이 온다. recovery→행동 표는 문서에 없다(`presigned-transfer-and-image-cdn.md:619-632`는 code 기준 표) | +| 발생 조건 | abort가 서버 확인 전에 실패해 ABORT_PENDING이 남음. 다른 문맥이 checkpoint를 먼저 씀. 서버 응답과 정책 불일치 | +| 영향 | 다운스트림 UI는 recovery를 보고 버튼을 고르게 된다. ABORT_PENDING에서 "다시 시도"를 누르면 같은 실패가 반복된다. 반대로 `CONFLICT`에 `abort()`를 붙이면 CAS 충돌 상황에서 정상 진행 중인 업로드를 서버에서 중단시킬 수 있다 | +| 심각도·우선순위 | Medium · P2 — 막다른 UX와 잘못된 조치로 이어질 수 있다. 데이터 손상은 없다 | +| 통제·증거 | M1 부분(개별 주석) · E1 | +| 확실성과 남은 가정 | 정적 확인. 실제 CAS 충돌 빈도는 Web Lock 때문에 낮을 것으로 보이며 미측정 | +| 최소 개선 방향 | port 주석에 `upload()` 실패의 recovery→행동 표를 둔다(`upload()` 다시 / `abort()` 필요 / 다른 파일 또는 키 / 없음). ABORT_PENDING 실패는 operation을 `UPLOAD_ABORT`로 바꿔 구분한다(공유 enum 변경 없음). session 수명 초과는 `RESTART` 대신 재시작으로 풀리지 않는 값으로 둔다 | +| 비용·부작용 | 작음. recovery 값이 바뀌므로 기존 테스트 기대값이 바뀐다 | +| 완료 기준 | `upload()`의 실패 경로마다 recovery가 port에서 실행할 수 있는 행동 하나에 대응한다. ABORT_PENDING과 CAS 충돌의 실패값이 다르다 | +| 검증 방법 | 실패 경로별 표 테스트(each) | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 01-06 서버가 준 만료 시각을 기기 시계로 여유 없이 비교한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 6, 17, 19, 23 | +| 근거 | session: `expiresAt - now > maxSessionLifetimeMs`이면 `EXPIRED_RESOURCE/RESTART`이고, 재개 중이면 `INTEGRITY_FAILED`다(`upload-response-validation.ts:96-115, 229-240`). capability: `remaining > maxCapabilityTtlMs`이면 `POLICY_REJECTED`, `< minimumRemainingLifetimeMs`이면 `EXPIRED_RESOURCE`이고 둘 다 `retryable:false`다(`presigned-capability-http-provider.ts:532-550`). runtime(`upload-response-validation.ts:60-68`)과 실행기(`presigned-transfer-executor.ts:976-997`)도 같다. 같은 영역의 image-cdn은 `maxClockSkewMs`를 둔다(`image-cdn-policy.ts:55, 143`; `image-cdn-runtime.ts:305-307`) | +| 발생 조건 | 서버의 session·capability 수명이 클라이언트 상한과 같거나 가깝고 기기 시계가 서버보다 늦은 경우. 또는 기기 시계가 capability 수명보다 더 빠른 경우. 기본 `maxSessionLifetimeMs`는 24시간이라, 서버가 24시간 session을 주면 시계가 조금만 늦어도 걸린다. 브라우저 스펙의 조립값(5분 session, 10분 상한)에는 여유가 있다 | +| 영향 | 해당 기기에서는 업로드가 매번 실패한다. 오류가 `EXPIRED_RESOURCE/RESTART`나 `POLICY_REJECTED`라 시계 문제로 보이지 않는다 | +| 심각도·우선순위 | Low · P2 — 설정 여유에 달린 좁은 조건이다. 하지만 걸리면 그 사용자는 업로드를 못 하고 진단도 어렵다 | +| 통제·증거 | 시계 오차 허용 M0 · E1 | +| 확실성과 남은 가정 | 비교식은 확인했다. 실제 서버 수명 설정은 다운스트림에 달려 있다 | +| 최소 개선 방향 | upload·presigned 정책에 `maxClockSkewMs`를 두고 상한·하한 비교에 반영한다(image-cdn과 같은 이름). 문서에 "서버 수명 < 클라이언트 상한 − skew" 조건을 적는다 | +| 비용·부작용 | 작음 | +| 완료 기준 | 기기 시계 ±skew 안에서 session·capability가 거절되지 않는다 | +| 검증 방법 | `now`를 주입해 ±skew 경계 테스트 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 01-07 발급됐지만 쓰지 못한 upload capability를 vault에서 회수하지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 12, 14, 22 | +| 근거 | vault는 `consume()`에서만 항목을 지우고, 만료 항목은 다음 `register()` 때만 정리한다(`presigned-capability-vault.ts:138-147, 277-287, 348-360`). `revoke()`(`:362-365`)를 부르는 곳이 src에 없다. runtime은 capability를 제네릭으로 다뤄 되돌릴 수 없고, 늦게 도착한 값을 처리할 `compensate`도 넘기지 않는다(`resumable-upload-runtime.ts:1325`). 쓰지 못한 capability가 생기는 경로는 넷이다. runtime 응답 검증 실패(`upload-response-validation.ts:45-74`), part 실행기 사전 검사 실패(`presigned-upload-part-executor.ts:55-81`), 실행기 digest 도중 abort·timeout(claim 전, `presigned-transfer-executor.ts:305-331`), fail-fast로 중단된 형제 worker | +| 발생 조건 | 위 실패가 반복되고 capability 수명이 긴 경우 | +| 영향 | 쓰지 못한 항목이 만료 전까지 `maxActiveCapabilities` 자리를 차지한다(브라우저 스펙 조립값은 8). 자리가 차면 발급이 `LIMIT_EXCEEDED`(`retryable:false`)로 실패한다. 이 코드는 파일 크기 초과처럼 읽힌다. 서버가 같은 key에 같은 receipt를 다시 주면 `CONFLICT`로 막히지만, 서버 문서가 발급을 매번 새 작업으로 규정하므로(`server-file-capability-infrastructure.md:1030`) 가능성은 낮다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M0(회수 경로 없음) · E1 | +| 확실성과 남은 가정 | 경로는 확인했다. 실제로 자리가 차는 빈도는 미측정이다 | +| 최소 개선 방향 | presigned 실행기 `put()`이 capability를 resolve한 뒤에는 어떤 경로로 끝나든 `finally`에서 vault 항목을 정리하게 한다. runtime 검증 실패분은 만료까지 두는 것을 문서화한다 | +| 비용·부작용 | 작음 | +| 완료 기준 | `put()`이 어느 경로로 끝나도 vault 항목 수가 원래대로 돌아온다 | +| 검증 방법 | digest abort·사전 검사 실패를 주입하고 vault 크기를 비교한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 01-08 재개할 때 저장된 session을 현재 정책으로 다시 검사해, 정책을 낮춘 배포 뒤 기존 업로드가 막힌다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 18, 3, 11 | +| 근거 | 재개 때 status를 검증하는 코드가 `validateSession`을 부른다(`upload-response-validation.ts:96-115`). 이 함수는 `session.maxConcurrency > policy.maxConcurrency`(`:219-221`)이거나 수명이 정책 상한을 넘으면(`:229-240`) `INTEGRITY_FAILED/RECONCILE`을 낸다. worker 수는 이미 `min(policy, session)`이라(`resumable-upload-runtime.ts:776-780`) 거절할 이유가 없다. 이 repo의 R-1.3 수정이 기본 `maxConcurrency`를 1로 낮춘 것이 바로 이 조건이다 | +| 발생 조건 | 다운스트림이 `maxConcurrency`나 `maxSessionLifetimeMs`를 낮춘 빌드를 배포하고, 이전 빌드에서 시작한 checkpoint를 session 수명(기본 상한 24h) 안에 재개할 때 | +| 영향 | 그 uploadKey는 `abort()`하기 전까지 매번 `INTEGRITY_FAILED`가 난다. 사용자는 이미 올린 part를 버리고 처음부터 다시 올려야 한다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M0 · E1 | +| 확실성과 남은 가정 | 경로는 확인했다. 실제 배포 이력은 없다(조립되지 않음) | +| 최소 개선 방향 | 재개 경로에서는 저장된 checkpoint 값과 일치하는지만 보고, 정책 상한 검사는 새 session을 만들 때만 한다 | +| 비용·부작용 | 작음 | +| 완료 기준 | 정책을 3→1로 낮춘 runtime이 동시성 3으로 만든 checkpoint를 재개한다 | +| 검증 방법 | 두 runtime(정책 다름)이 checkpoint store 하나를 공유하는 테스트 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 01-09 part 수 상한과 control-plane 요청·응답 바이트 상한을 서로 검사하지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 19, 13, 14 | +| 근거 | 정책은 part를 10,000개까지 허용한다(`runtime-policy.ts:35, 80-81`). fetch 전송의 요청 상한은 기본 1MiB이고, 넘으면 `LIMIT_EXCEEDED, retryable:false`다(`fetch-json-transport.ts:62, 169-188`). 실제 JSON으로 complete 요청 크기를 계산했다: 1,024 part ≈ 199KB, 5,400 part ≈ 1.06MB(1MiB 초과), 10,000 part ≈ 1.96MB. 응답 상한 기본 2MiB도 10k part status에 가깝다. 두 값은 서로 다른 factory에 들어가 교차 검증이 없다 | +| 발생 조건 | 기본값(최대 1,024 part)에서는 생기지 않는다. `maxFileBytes`를 키워 part가 약 5,300개를 넘는 설정 | +| 영향 | 모든 part를 올린 뒤 complete에서 영구 실패한다(재개해도 같다). 큰 파일일수록 늦게 드러난다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M0 · E1(크기 계산) | +| 확실성과 남은 가정 | 요청 크기는 receipt token 32자 기준. token이 길면 더 빨리 넘는다 | +| 최소 개선 방향 | 조립 helper나 문서에서 `maxPartCount`와 전송 `maxRequestBytes`·`maxResponseBytes`를 함께 검사한다. 또는 정책 해석 시 필요한 요청 크기를 계산해 알린다 | +| 비용·부작용 | 작음 | +| 완료 기준 | part 수 상한에 맞지 않는 전송 상한 조합이 조립 시점에 거절된다 | +| 검증 방법 | 조합 검증 단위 테스트 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 01-10 `UPLOAD_PART` 관측이 두 계층에서 같은 이름으로 기록되고, 문서가 말한 retry·part bucket은 없다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(문서와 구현 불일치, 중복 집계) | +| 관련 관점 | 7, 8 | +| 근거 | 실행기는 PUT 시도마다(`presigned-transfer-executor.ts:435-442`), runtime은 part 최종 결과마다(`resumable-upload-runtime.ts:808-813, 871-876`) `UPLOAD_PART`를 기록한다. 같은 observer를 넘기면 성공 part 하나가 SUCCEEDED 2건이 된다. 재시도 한 번 뒤 성공하면 FAILED 1건과 SUCCEEDED 2건이 된다. `observeTransferResult`(`presigned/http-common.ts:208-221`)는 retry·duration·count bucket을 넣지 않는다. 문서 `presigned-transfer-and-image-cdn.md:634`는 part·retry bucket을 기록한다고 적는다 | +| 발생 조건 | 실행기와 runtime에 같은 observer를 줄 때(자연스러운 조립) | +| 영향 | 실패율과 건수가 부풀려진다. 재시도 증폭을 관측할 수 없다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M1(문서) · E1 | +| 확실성과 남은 가정 | 정적 확인. 실제 수집 파이프라인은 다른 영역 | +| 최소 개선 방향 | 실행기 기록은 `PRESIGNED_TRANSFER`로 두고 `UPLOAD_PART`는 runtime만 기록한다. 최종 결과에 시도 수 `countBucket`을 넣는다 | +| 비용·부작용 | 작음. 관측 이름이 바뀐다 | +| 완료 기준 | 재시도 1회 뒤 성공한 part가 `UPLOAD_PART` 1건(시도 수 bucket 포함)으로 기록된다 | +| 검증 방법 | observer 기록 단언 테스트 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 01-11 이미지 `resolve()`가 `PRIMARY_REQUIRED` preset이면 호출마다 원본 후보 전체를 내려받아 decode하며, 동시 실행 상한과 결과 재사용이 없다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 14, 5 | +| 근거 | `resolve()`는 호출마다 probe를 실행한다(`image-cdn-runtime.ts:544-614`). 동시 상한은 서명 검증에만 있다(`:338-347`). probe(`browser-image-probe.ts`)에도 상한이 없다. private 응답은 `no-store`가 필수라(`browser-image-probe.ts:322-325`) ``가 같은 URL을 한 번 더 받는다. private asset은 `PRIMARY_REQUIRED`가 강제된다(`image-cdn-runtime.ts:511-518`). port 주석(`application/ports/browser-transfer/image-cdn.ts:167-180`)에는 이 네트워크·decode 비용이 적혀 있지 않다 | +| 발생 조건 | private 이미지가 많은 목록 화면. 재렌더링 때마다 `resolve()` 호출 | +| 영향 | 메모리를 동시 probe 수 × (encoded + decoded 상한)만큼 쓴다(README 예시 기준 이미지당 약 4.5MiB, 구현 상한은 최대 80MiB). 전송량은 2배가 된다 | +| 심각도·우선순위 | Low · P3 — 비용 문제이고 안전 문제는 아니다 | +| 통제·증거 | M0 · E1 | +| 확실성과 남은 가정 | 코드로 확인했다. 실제 화면 부하는 미측정 | +| 최소 개선 방향 | probe에 서명 검증과 같은 방식의 동시 상한을 두고, port 주석에 비용을 적는다. 같은 asset+preset 결과를 capability 만료까지 재사용한다 | +| 비용·부작용 | 작음~중간 | +| 완료 기준 | 동시 probe 수가 상한을 넘지 않고, 같은 요청을 반복하면 네트워크를 다시 쓰지 않는다 | +| 검증 방법 | probe fake로 동시 호출 수 단언 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +## 5. 28개 관점 판정 (36.2) + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +|---|---|---|---|---|---| +| 1 | 코드 성숙도 | 적용 — checkpoint·session 상태 전이 | 목표 M3 / 확인 M3: exact-key decoder, revision CAS, `ACTIVE→ABORT_PENDING→삭제` | E2(199 테스트, M3·M4 검출) | 충족 | +| 2 | 구조적 성숙도 | 적용 — 배럴·port·kernel import | 목표 M3 / 확인 M2: 배럴 3개, adapter 간 import는 kernel(`platform/`, `browser-file-storage/result.ts`)만 | E1(import 목록). `check:architecture`는 오케스트레이터 | 충족(게이트 결과 제외) | +| 3 | 변경 용이성 | 적용 — 정책 변경의 전파 | M2: runtime을 검증·snapshot·정책 모듈로 분리 | E1 | 부분 충족 — 정책을 낮추면 기존 checkpoint가 막힌다(01-08) | +| 4 | 인지 부하 | 적용 | M2: 파일 분리, 주석에 요구 ID | E1 | 부분 충족 — 실패→행동 매핑을 코드 전체에서 찾아야 한다(01-05) | +| 5 | 위험 가시성 | 적용 — 29.4 문장 작성 | M1~M2 | E2 | 부분 충족 — 결과 불명 표현 없음(01-02), recovery 모호(01-05), resolve 비용 미표시(01-11) | +| 6 | 실패 성숙도 | 적용 — 중점 | M2~M3: 재시도 단일 계층·상한·jitter·고정 key, 결과 불명 checkpoint | E2(X1~X3, M2~M5) | 부분 충족 — 01-01, 01-02, 01-03, 01-06 | +| 7 | 운영 성숙도 | 적용(연결점만) | M1: observer seam, 안전 bucket | E1 | 부분 충족 — 중복 집계, retry bucket 없음(01-10) | +| 8 | 디버깅 가능성 | 적용 | M2: 닫힌 code·operation·recovery 분류, 민감정보 미기록 | E1 | 부분 충족 — 같은 실패값이 다른 원인(01-05). 상관 ID는 설계상 제외 | +| 9 | 유지보수 성숙도 | 적용 | M2: 직전 리뷰 11건 반영, HTTP helper 통합 | E1 | 부분 충족 — 작은 갈라진 복사본이 남음(`isAbortSignal`이 `checkpoint-schema.ts:195`는 duck typing, `http-common.ts:186`은 brand 검사. `MEDIA_TYPE` 길이 규칙 2종) | +| 10 | 테스트 성숙도 | 적용 — 중점 | 목표 M3 / 확인: 주요 분기 일부만 M3 | E2(199 통과, 변형 7종 중 3종 생존) | 부분 충족 — 01-04 | +| 11 | 데이터 성숙도 | 적용 — checkpoint 수명·범위·삭제 | M2~M4: 저장 key allowlist, 계정 partition 결속, 성공·abort·terminal 때 삭제, partition 삭제는 PENDING/UNKNOWN 정직 보고 | E2(checkpoint 테스트 14개) | 부분 충족 — TTL·inventory 없음(문서 4.4가 미구현으로 선언, 결함 아님). 완료된 자원과의 연결을 잃는 경로(01-02). lock·BroadcastChannel 이름은 계정으로 나뉘지 않음(uploadKey 충돌 시에만 영향) | +| 12 | 동시성 성숙도 | 적용 — 중점 | M3: Web Lock, revision CAS, receipt 직렬화, fail-fast, dispose가 실제 작업까지 대기 | E2(M2 검출, teardown 테스트) | 충족 — 잔여: vault 미회수(01-07). `close()`만 쓰면 drain이 시간 초과된 뒤 store를 닫을 주체가 없다(`resumable-upload-runtime.ts:266-270, 294-302`) | +| 13 | 확장성 | 부분 적용 — part 수 증가 | M1 | E1 | 부분 충족 — 01-09 | +| 14 | 성능 성숙도 | 적용 — 중점(in-flight 바이트) | M3: 시작 전 in-flight 검사, 본문 hard cap | E1. copyFactor 4는 추정이고 실측 없음 | 부분 충족 — 01-03, 01-11. part당 SHA-256을 3번 계산한다(manifest, runtime, 실행기) | +| 15 | 보안 성숙도 | 적용 | M4: vault identity, HTTPS·redirect·credential·header 금지, checkpoint allowlist | E2(presigned 테스트 4파일) | 충족 — 인가는 서버 책임(문서 3.1) | +| 16 | 의존성 성숙도 | 적용(제한) — 외부 패키지 없음 | M2: WebCrypto와 직접 구현한 SHA-256 | E2(대조 1,830건) | 충족 — 자체 암호 코드 유지 비용은 01-04 테스트로 보완 필요 | +| 17 | API / Contract 성숙도 | 적용 — 중점(presigned 서버 계약) | M3: strict exact-key decode, protocol literal, `singleUse:true` 강제 | E2 | 부분 충족 — complete 진행 중 표현 없음(01-02), recovery 의미(01-05), 시계 오차(01-06), BFF 429의 `Retry-After` 미반영(`http-common.ts:135-167`) | +| 18 | 배포 성숙도 | 적용 — 구버전 checkpoint 공존 | M2: `schemaVersion:1` 고정, 모르는 schema는 abort로 제거 | E2 | 부분 충족 — 정책 변경 skew(01-08) | +| 19 | 설정 성숙도 | 적용 | M3: 정책·레지스트리를 조립 시점에 검증(TypeError) | E2 | 부분 충족 — factory 사이의 값(timeout, 최소 잔여 수명 vs refresh skew, part 수 vs 요청 상한)을 서로 검사하지 않음(01-01, 01-03, 01-09) | +| 20 | 개발자 경험 | 적용 | M1: image-cdn README 예제. upload 조립 예는 Playwright 스펙에만 | E1 | 부분 충족 — resumable upload 조립 예제 문서 없음 | +| 21 | Guardrail 성숙도 | 부분 적용 | M3: 조립 시 정책·레지스트리 거절. 경계 검사는 다른 영역 | E1 | 부분 충족 — idempotency 규칙 자동 검출 없음(01-04) | +| 22 | 추상화 성숙도 | 적용 — 중점(abort kernel 등) | M3: runtime attempt·fetch 전송·presigned scope·image가 모두 `createAbortableOperation` 사용(6.1-9 해결) | E2 | 부분 충족 — 제네릭 Capability 탓에 미사용 capability를 회수할 수 없음(01-07). 실패 타입이 결과 불명을 숨김(01-02). `startDrain`은 kernel이 아닌 직접 타이머 | +| 23 | 일관성 | 적용 | M2 | E1 | 부분 충족 — 시계 오차 처리가 image-cdn에만 있음(01-06). `Retry-After`는 control 전송에만 있음 | +| 24 | 네이밍 / 의미 성숙도 | 적용 | M2 | E1 | 부분 충족 — `RESTART`로 풀리지 않는 실패, `REISSUE_CAPABILITY`+`retryable:false`(01-05) | +| 25 | 조직 확장성 | 구조적 준비만 평가(팀 1인) | port와 adapter가 분리됨 | E1 | 적용 제외 — 실제 검증 대상 아님 | +| 26 | Ownership 성숙도 | 부분 적용 | M1: 서버 책임을 `server-file-capability-infrastructure.md`에 기술 | E0 | 부분 충족 — 클라이언트·서버 계약 공백(01-02 ⑤)의 결정 주체가 없음 | +| 27 | 삭제 가능성 | 적용 | M3 주장: `scripts/test-browser-file-storage-runtime-removal.ts`가 이 폴더를 지우고 게이트 실행 | E0(미실행) | 미검증 | +| 28 | 회복 가능성 | 적용 — 중점(중단 후 재개·정리) | M2~M3: checkpoint 재개, 서버 상태 조정, ABORT_PENDING, 읽을 수 없는 행 제거 | E2 | 부분 충족 — 완료 자원과의 연결을 잃는 경로(01-02), 전진 불가 재시도(01-03). 버려진 checkpoint 정리는 선언된 미구현 | + +## 6. 미검증 목록 + +| 항목 | 이유 | 확인하려면 | +|---|---|---| +| 실제 브라우저 동작(Web Locks, IndexedDB, BroadcastChannel, fetch 스트림) | Playwright 스펙 3개를 실행하지 않음 | `test:browser-capabilities`로 `resumable-upload.spec.ts`, `presigned-streaming.spec.ts`, `image-cdn.spec.ts` 실행 | +| 두 탭의 동시 업로드·abort | 단위 테스트는 메모리 fake 채널·lock만 사용 | 실제 브라우저 두 page에서 같은 uploadKey로 upload/abort | +| object store·BFF 실제 계약: PUT 403 발생 조건, 같은 key 재발급 시 receipt, complete 소요 시간, `OPERATION_IN_PROGRESS` wire 표현 | repo 밖 시스템 | provider conformance 테스트(서버 문서 10.2 retry matrix 기준) | +| part 버퍼 실제 메모리(copyFactor 4 추정) | 측정 환경 없음 | 브라우저 메모리 프로파일로 동시성 N, part 5MiB일 때 최대 사용량 측정 | +| 저속 업링크의 실제 영향 | 실험은 fake timer | 네트워크 throttling(1Mbit/s)으로 실제 업로드 | +| Web Locks 미지원 브라우저 처리 | 문서가 "unsupported lock decision"을 미결정으로 선언 | 지원 브라우저 결정 또는 fallback 설계 | +| 삭제 가능성 | `test:browser-file-storage-removal`은 `.tmp`에 fixture를 만들고 pnpm을 실행해 동시 작업 중 실행하지 않음 | 단독 환경에서 실행 | +| 아키텍처·타입 게이트 | 오케스트레이터 담당 | `check:architecture`, `check:types` 결과 참조 | +| logout 시 checkpoint partition 삭제 연결 | 조립 코드가 repo에 없음(`AVAILABLE_NOT_COMPOSED`) | 다운스트림 조립에서 dispose → `deletePartition` 순서 검증 | diff --git a/docs/reviews/2026-09-25-maturity-review/02-adapters-browser-files-cache.md b/docs/reviews/2026-09-25-maturity-review/02-adapters-browser-files-cache.md new file mode 100644 index 00000000..4207cd1e --- /dev/null +++ b/docs/reviews/2026-09-25-maturity-review/02-adapters-browser-files-cache.md @@ -0,0 +1,295 @@ +# browser-files / cache-storage / cross-context-invalidation 성숙도 리뷰 + +> 검토일: 2026-09-25 · 기준: `main` / `4626b73` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 범위: `src/adapters/browser-files/` (10파일, 약 4.8k줄), `src/adapters/cache-storage/` (5파일, 약 2.3k줄), `src/adapters/cross-context-invalidation/` (3파일, 약 1.1k줄). 합계 약 8.1k줄. 이 영역을 검증하는 unit 테스트 11개 파일(약 6.6k줄)과 browser-capabilities spec 4개. +> 영역 판정(35.8): **조건부 사용 가능** + +## 1. 결론 + +- cross-context-invalidation은 기본 조립 경로(`src/bootstrap/runtime-adapters.ts:346`)에 들어가 있고, 직전 리뷰의 순서·fallback 결함(6.2-2, 6.2-3, 6.2-9)은 현재 코드에서 고쳐져 있다. 여러 탭의 중복·역순·BroadcastChannel 미지원은 그대로 써도 된다. +- browser-files는 기본 번들 밖의 opt-in runtime이다. 도입 전에 고칠 것은 **preview를 만든 직후 호출자가 abort하면 object URL lease가 새는 문제(02-01)** 하나다. lease 한도(기본 16)를 preview와 download가 같이 쓰므로, 16개가 새면 그 탭에서는 preview와 소형 download가 모두 `LIMIT_EXCEEDED`로 실패한다. Node에서 실제 adapter 코드로 재현했다. +- cache-storage는 요청을 익명(`credentials: "omit"`, `mode: "same-origin"`)으로 보내고 private·cookie 계열 응답을 거부한다. 그래서 로그아웃·사용자 전환 때 Cache Storage를 지울 필요가 없다. 다만 **이 익명 요청 규칙을 고정하는 테스트가 없다(02-02)**. 두 줄을 지워도 테스트가 전부 통과한다. +- 변이 22개를 넣어 테스트 검출력을 확인했다. 11개는 테스트가 잡았고, 4개는 다른 검사가 막아 결과가 같았다. 나머지 6개 규칙은 테스트가 잡지 못했다(02-02, 02-08). +- 미검증: 실제 브라우저 3종에서의 동작(Playwright spec 실행 불가), Safari의 30초 object URL grace 충분성, 다른 탭에서 계정이 바뀐 뒤 이 탭이 받는 무효화 hint의 영향(auth 영역 의존). + +## 2. 범위와 방법 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 | `clean-architecture-frontend-template`, 영역 02 | +| 커밋·상태 | `main` / `4626b73`. 미커밋은 `CLAUDE.md`, 가이드 문서뿐 | +| 지원 구성 | 브라우저 SPA. cross-context-invalidation은 `COMPOSED`, browser-files·cache-storage는 `AVAILABLE_NOT_COMPOSED`(recipe, `config/recipes/frontend-capability-recipes.json:128`, `:176`) | +| 읽은 코드 | 위 3개 폴더 전체, 관련 port(`src/application/ports/browser-file-storage/{shared,file,cache-storage-ports}.ts`), kernel(`src/adapters/browser-file-storage/result.ts`, `src/adapters/platform/abortable-operation.ts`), wire 계약(`src/contracts/cache-invalidation.ts`), 조립·소비 코드(`src/bootstrap/runtime-adapters.ts`, `src/bootstrap/server-state-generation-store.ts`, `src/adapters/query-cache/tanstack-cache-coordinator.ts`) | +| 읽은 문서(주장) | `docs/architecture/browser-file-and-origin-storage.md` 1·3·5·8절, `docs/architecture/client-cache-and-storage.md` 0절, recipe catalog | +| 실행한 테스트 | `node scripts/run-vitest.ts run` 로 영역 unit 11개 파일 → **11 files, 121 tests 통과** | +| 실험 1 | `scratchpad/02/preview-abort.ts`: 실제 `BrowserFileVault`·`BrowserTransientPreview`에 가짜 URL API를 주입. `create()` 직후 같은 turn에 abort를 16번 → 16번 모두 `ok:true` lease 반환, `activeLeaseCount 16`, revoke 0회. 17번째와 abort 없는 새 요청 모두 `LIMIT_EXCEEDED` | +| 실험 2 | `scratchpad/02/shared-registry.ts`: `createBrowserFileRuntime`으로 `BOUNDED_OBJECT_URL` 다운로드 17번(30초 grace 타이머 미발화 상태) → 16번 `BROWSER_HANDOFF`, 17번째 `LIMIT_EXCEEDED` | +| 실험 3 | 분리 worktree에서 규칙 하나씩 제거하는 변이 22개 → 결과는 02-02, 02-08과 관점 10 행에 적었다. worktree는 삭제했다 | +| 확인 못 한 것 | `test:browser-capabilities`(Playwright, dev 서버 필요, 지시서상 실행 범위 밖). `artifacts/tests/browser-capabilities/results.xml`(2026-09-24, webkit 17건 통과)은 이전 실행이라 증거로 쓰지 않았다. `check:architecture`·`lint` 등 전체 게이트는 오케스트레이터 담당 | + +### 2.1 직전 리뷰(6.2) 항목 재확인 + +현재 코드에서 다시 확인했다. 고쳐진 항목은 아래 발견에 다시 올리지 않았다. + +| 직전 ID | 현재 상태 | 근거 | +|---|---|---| +| 6.2-1 bounded open 실패 시 reject | 해결 | `download-delivery-adapter.ts:745-756` try 안에서 호출, `:859-862` finally에서 close. 테스트 `browser-file-download.test.ts:781` | +| 6.2-2 watermark TTL 삭제 | 해결 | `browser-cross-context-invalidation.ts:156-158` TTL 없음, `:556-560` prune은 seenEvents만. 테스트 `cross-tab-invalidation.test.ts:525` | +| 6.2-3 fallback 탭 수신 중단 | 해결 | `:188-190`, `:340-364` 발행 실패 뒤에도 채널 유지. 열기 실패는 `DEGRADED_STORAGE_FALLBACK`(`:284-286`) | +| 6.2-4 picker bind | 해결 | `browser-file-picker.ts:430-431`, `download-delivery-adapter.ts:234-235` `bind(undefined)` | +| 6.2-5 Vary/content-type | 해결 | `public-cache-response-validation.ts:186`, `public-cache-policy.ts:142` | +| 6.2-6 조회 비용 | **일부 남음** → 02-07 | marker 메모·Map 탐색은 적용. `keys()` 2회와 본문 복사 4회는 남음 | +| 6.2-7 abort race | 해결 | kernel `createAbortableOperation` 사용(`download-delivery-adapter.ts:276`, `:600-608`, `:916-928`, `browser-file-vault.ts:515`) | +| 6.2-8 focus fallback | 해결 | `browser-file-picker.ts:107`, `:339-341` | +| 6.2-9 host 조용한 비활성 | 해결 | `browser-cross-context-host.ts:45-51`, `:68-91` | +| 6.2-10 파일명 O(n²) | 해결 | `file-policy.ts:418-430` 단일 패스 | +| 6.2-11 큰 파일 분리 | 해결(분리됨) | codec 656줄·검증 239줄·입력 검증 367줄로 분리. 본 파일은 여전히 각 1.1k줄대 | +| 6.2-12 중복 정규식 | 대부분 해결 | `file-policy.ts:49-55`로 통합. `public-cache-policy.ts:191`의 `positiveSafeInteger` 한 벌은 남음(의미 동일, 발견으로 올리지 않음) | + +### 2.2 32절 시나리오 추적 (이 영역 관점) + +**로그아웃 중 응답 도착** + +```text +세션 변경 → server-state scope reset → activateNext() + → 이전 coordinator.dispose() → crossContext.close() (tanstack-cache-coordinator.ts:276-280) + → 새 generation: 새 QueryClient + 새 crossContext(새 sourceId·sourceEpoch) + (server-state-generation-store.ts:50-57, runtime-adapters.ts:343-383) +``` + +- cross-context: 닫힌 인스턴스에 늦게 도착한 메시지는 `closed` 검사에서 버린다(`browser-cross-context-invalidation.ts:445`, `:458`). 이전 세대 탭 ID로 보낸 이벤트는 새 세대에서 새 source로 보인다. 테스트 `cross-tab-invalidation.test.ts:809`. **이전 세션 응답이 다음 세대 상태로 들어가는 경로는 이 영역에서 찾지 못했다.** +- cache-storage: stage 중 로그아웃돼도 요청이 익명이라 사용자 응답이 저장되지 않는다(`public-cache-response-validation.ts:227-238`, `:54-66`). 단 이 규칙은 테스트가 고정하지 않는다(02-02). +- browser-files: runtime이 세션을 모른다. 진행 중 download는 호출자가 abort하지 않으면 로그아웃 뒤에도 끝까지 저장된다. vault의 File 참조와 preview object URL은 runtime dispose 전까지 남는다(02-03). + +**사용자·테넌트 전환** + +- Cache Storage: 저장 대상이 익명 공개 응답뿐이라 사용자별 분리가 필요 없다. 캐시 키에 `authorization`·`cookie` 요청 헤더를 넣을 수 없다(`public-cache-codec.ts:254-278`). +- cross-context: wire 이벤트에 사용자·세션 scope가 없다. 문서가 "session/account epoch는 미구현, 같은 release의 stale hint 용도로 한정"이라고 선언한다(`docs/architecture/client-cache-and-storage.md:85-88`). 다른 탭에서 계정이 바뀐 뒤 이 탭이 hint를 받아 refetch하면, 이 탭의 이전 사용자 세대 캐시에 새 쿠키 응답이 들어갈 수 있다. 원인은 탭 간 세션 변경 감지(auth 영역)이고 hint는 그 시점을 앞당길 뿐이다. 비지원이 선언돼 있어 결함으로 세지 않고 6절 미검증에 적었다. +- browser-files: 02-03과 같다. + +## 3. 확인된 강점 + +1. **캐시에 사용자 데이터가 들어갈 경로를 여러 겹으로 막는다.** 요청은 `credentials: "omit"`, `mode: "same-origin"`, `redirect: "error"`(`public-cache-response-validation.ts:227-238`). 응답은 `private`/`no-store`/`no-cache`, `Set-Cookie`, `WWW-Authenticate`, `Vary: Cookie|Authorization|*`면 거부한다(`:54-66`, `:187-193`). 요청 헤더에서 `authorization`·`cookie`·`range`를 금지하고(`public-cache-codec.ts:254-259`), query는 allowlist만 받는다(`:231-245`). 본문은 manifest의 SHA-256·길이·Content-Type과 정확히 맞아야 한다(`public-cache-response-validation.ts:71-96`). +2. **파일 이름·MIME을 신뢰하지 않는다.** 저장 파일 확장자는 정책의 `safeExtension`만 붙고, 이름 안의 실행 확장자는 `_exe`처럼 무력화하며, bidi 제어 문자·경로·Windows 예약어를 제거한다(`file-policy.ts:310-376`). preview의 MIME은 `File.type`이 아니라 헤더 바이트로 찾은 signature에서 오고, 그 타입으로 새 Blob을 만든다(`object-url-lease.ts:263-285`). SVG·HTML·XML·PDF는 정책으로도 풀 수 없다(`:173-180`, `:204-213`). +3. **사용자 취소·abort·권한 거부를 Result에서 구분한다.** picker 취소는 `DISMISSED` 성공, 호출자 abort는 `ABORTED`, user activation 없음·`NotAllowedError`·`SecurityError`는 `PERMISSION_DENIED`다(`browser-file-picker.ts:249-254`, `:526-546`, `download-delivery-adapter.ts:529-575`, `result.ts:54-66`). 이미 close된 저장은 늦은 abort로 실패 처리하지 않는다(`download-delivery-adapter.ts:667-669`). +4. **자원 상한이 조립 시점에 검증되고 호출자는 낮추기만 한다.** 선택 개수·파일·누적 바이트, 보관 참조 32개, object URL 16개·합계, 전송·버퍼 바이트(`create-browser-file-runtime.ts:199-242`, `browser-file-policy-registry.ts:492-507`). 캐시는 entry 16 MiB·release 128 MiB·500개·control JSON 2 MiB(`public-cache-policy.ts:43-82`, `public-cache-codec.ts:291-357`). +5. **여러 탭의 중복·역순·전송 수단 실패를 명시적으로 처리한다.** eventId 중복 제거, source별 watermark로 역순 폐기, 끊기면 `GAP`으로 전체 무효화, 자기 echo 폐기(`browser-cross-context-invalidation.ts:469-514`). storage 이벤트는 캡처한 localStorage 객체와 동일성으로만 받는다(`:197-201`, `browser-cross-context-host.ts:286-296`). 두 수단이 모두 없으면 부팅을 막지 않고 `DEGRADED_LOCAL_ONLY`로 진단을 남긴다(`:377-396`, `runtime-adapters.ts:358-373`). +6. **캐시 교체가 부분 실패에도 서비스 중 release를 지운다.** 새로 만든 candidate만 실패 시 삭제하고, 기존 candidate는 교체본 검증 전 지우지 않는다(`public-response-cache-adapter.ts:445-490`, `:563-571`). abort 뒤에는 asset·marker 쓰기를 막는다(`:414-430`). + +## 4. 발견 사항 (36.3) + +### 02-01 preview를 만든 직후 abort하면 object URL lease가 반환되고 다시 회수되지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 6, 12, 14, 23, 5 | +| 근거 | `object-url-lease.ts:235-236`에서만 abort를 보고, `:250` `await resolveVerifiedFile(...)` 뒤에는 dispose만 확인한다(`:258-262`). 그 뒤 `:285`에서 lease를 만들고 성공으로 반환한다. 같은 runtime의 vault는 await 뒤 abort를 다시 보고(`browser-file-vault.ts:355-359`, `:469-470`), download는 늦게 온 자원을 kernel race로 닫는다(`download-delivery-adapter.ts:916-928`). 실험 1: `create()` 호출 직후 같은 turn에 abort → `ok:true` lease, 16번 반복 뒤 `activeLeaseCount 16`, revoke 0회, 17번째와 abort 없는 새 요청 모두 `LIMIT_EXCEEDED` | +| 발생 조건 | 호출자가 `create()`를 부른 같은 task 안에서 abort한다. React StrictMode 개발 모드의 effect 두 번 실행(effect → cleanup → effect)에서 매번 일어난다. 운영에서는 같은 task에서 요청을 교체·취소하는 코드에서 일어난다 | +| 영향 | 호출자는 abort된 결과를 버리므로 lease를 release하지 않는다. lease는 runtime dispose까지 남는다. 한도(기본 16개, `create-browser-file-runtime.ts:219-220`)를 preview와 download가 같은 registry로 쓰므로(`:109-120`, `:151-168`) 한도가 차면 그 탭에서 preview와 `BOUNDED_OBJECT_URL` download가 모두 `LIMIT_EXCEEDED`로 실패한다. 새는 동안 사용자 파일 Blob도 메모리에 남는다 | +| 심각도·우선순위 | Medium · P2 — 탭 하나의 기능 실패이고 dispose·새로고침으로 회복된다. runtime은 기본 번들 밖(opt-in)이지만 preview를 조립하는 다운스트림에는 그대로 복제된다 | +| 통제·증거 | M1(문서 3.5절 "unmount에서 한 번 revoke"는 호출자 책임으로만 적힘) · E2(Node 재현 실험) | +| 확실성과 남은 가정 | 코드 경로와 재현 결과는 확정. 실제 React 화면에서의 발생 빈도는 호출 코드에 달려 있다(현재 repo 안 소비자 없음) | +| 최소 개선 방향 | `:257` 이후와 `:285` 직전에 `abortedResult(input.signal, "PREVIEW")`를 다시 확인해 `ABORTED`를 반환한다. lease 생성 후 반환 전에 abort가 확인되면 `lease.release()`를 부른다 | +| 비용·부작용 | 몇 줄. 기존 성공 경로 동작은 같다 | +| 완료 기준 | `create()` 직후 같은 turn에 abort하면 `ABORTED`가 오고 `activeLeaseCount`가 늘지 않는다 | +| 검증 방법 | `tests/unit/browser-file-content.test.ts`에 실험 1과 같은 테스트 추가 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 02-02 Cache Storage의 익명 요청 규칙을 테스트가 고정하지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험(테스트 공백) | +| 관련 관점 | 10, 11, 15 | +| 근거 | stage 요청은 `createNativeRequest`(`public-cache-response-validation.ts:223-238`)가 `credentials: "omit"`, `mode: "same-origin"`으로 만든다. unit 3개 파일과 browser spec 어디에도 `credentials`·`mode` 검증이 없다(grep 0건). 변이 실험: `credentials`를 `"include"`로 바꿔도, 두 줄을 모두 지워도 캐시 테스트 34개가 전부 통과했다 | +| 발생 조건 | 누군가 두 줄을 지우거나 기본값으로 되돌린다. `Request`의 기본 `credentials`는 `"same-origin"`이라, 같은 origin asset 요청에 쿠키가 실린다 | +| 영향 | 서버가 인증된 응답에 `Cache-Control: private`을 빠뜨리면 사용자별 응답이 origin 공용 Cache Storage에 저장되고 로그아웃 뒤에도 남는다. 이 adapter는 로그아웃 purge 경로가 없으므로(설계상 불필요) 이 두 줄이 사용자 분리의 유일한 전제다 | +| 심각도·우선순위 | Low · P2 — 현재 코드는 맞다. 회귀가 조용히 들어올 수 있고, 들어오면 데이터 분리가 깨진다 | +| 통제·증거 | M2(구현) · E1, 검출은 M0 확인(변이 실험) | +| 확실성과 남은 가정 | 실제 누출은 서버 헤더에 달려 있다 | +| 최소 개선 방향 | stage 테스트에서 fetcher가 받은 `Request`의 `credentials === "omit"`, `mode === "same-origin"`, `redirect === "error"`를 단언한다 | +| 비용·부작용 | 테스트 몇 줄 | +| 완료 기준 | 위 변이가 테스트에서 실패한다 | +| 검증 방법 | 같은 변이를 다시 넣어 실패 확인 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 02-03 browser-file runtime이 인증 scope와 연결되지 않고, 연결 방법도 문서에 없다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 11, 15, 5 | +| 근거 | runtime은 세션을 모르는 feature factory다(`create-browser-file-runtime.ts:89-92`, dispose `:177-186`). 선택 정책의 `classification: PERSONAL/CONFIDENTIAL`은 검증만 하고 동작에 쓰지 않는다(`file-policy.ts:15`, `:112-117`, `browser-file-policy-registry.ts:357`). recipe lifecycle(`config/recipes/frontend-capability-recipes.json:195`)과 문서 3.5절(`docs/architecture/browser-file-and-origin-storage.md:347-356`)은 release·unmount·feature dispose만 말하고 로그아웃·계정 전환은 말하지 않는다. 세션 변경 시 자원을 닫는 연결점(`runtime-adapters.ts:394-400` `participants`)은 있지만 이 runtime을 거기에 붙이라는 안내가 없다 | +| 발생 조건 | 다운스트림이 runtime을 앱 수명(세대 전환보다 바깥)에 만들고, 사용자 A가 파일을 고르거나 preview·download 중에 로그아웃한 뒤 같은 탭에서 B가 로그인한다 | +| 영향 | A가 고른 File 참조(기본 보관 상한 = 전송 상한), preview object URL, 진행 중 download가 B의 세션까지 남는다. 참조는 추측 불가능한 난수라 B가 port로 꺼낼 경로는 확인하지 못했다. 같은 기기 안의 잔존·메모리 문제다 | +| 심각도·우선순위 | Low · P3 — 직접 노출 경로 없음, 같은 기기·같은 탭 한정 | +| 통제·증거 | M0(scope 연결 규칙 부재 확인) · E1 | +| 확실성과 남은 가정 | 실제 영향은 다운스트림이 runtime을 어디서 만들지에 달려 있다 | +| 최소 개선 방향 | 문서 3.5절과 recipe에 "세션·계정 변경 시 runtime.dispose()(또는 scope participant 등록)"를 한 줄 추가한다. 코드 변경은 필요 없다 | +| 비용·부작용 | 문서 수정 | +| 완료 기준 | recipe lifecycle과 문서에 로그아웃 처리가 명시된다 | +| 검증 방법 | 문서 확인 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 02-04 object URL 한도를 preview와 download가 공유하고, 30초 대기 중 초과하면 재시도 불가로 보고한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 6, 14, 22 | +| 근거 | 한 registry를 preview와 download에 같이 넘긴다(`create-browser-file-runtime.ts:109-120`, `:151-168`, 기본 16개 `:219-220`). download lease는 handoff 뒤 30초 유지된다(`download-delivery-adapter.ts:148`, `:835-838`). 한도 초과는 `FileTooLargeError` → `LIMIT_EXCEEDED`(`object-url-lease.ts:97-110`, `download-delivery-adapter.ts:1034-1035`)이고 기본값이 `retryable:false`, `recovery:"NONE"`이다(`result.ts:28-29`). 실험 2: 30초 안 17번째 다운로드가 `LIMIT_EXCEEDED` | +| 발생 조건 | 30초 안에 소형 다운로드를 16번 넘게 하거나(일괄 내보내기), 다운로드 여러 번 직후 preview를 연다 | +| 영향 | 시간이 지나면 풀리는 상태를 "재시도 불가"로 알려, 화면이 잘못된 안내를 한다. download 폭주가 preview를 막는다 | +| 심각도·우선순위 | Low · P3 — 설정으로 한도를 올릴 수 있고 30초 뒤 회복된다 | +| 통제·증거 | M2(상한 구현) · E2(Node 재현 실험) | +| 확실성과 남은 가정 | 기본값 기준. 실제 사용 패턴은 다운스트림 몫 | +| 최소 개선 방향 | lease 한도 초과만 `retryable:true, recovery:"RETRY"`로 보고한다. 필요하면 preview와 download 한도를 나눈다 | +| 비용·부작용 | 실패 코드의 retry 의미 변경 | +| 완료 기준 | 한도 초과 결과가 재시도 가능으로 보고된다 | +| 검증 방법 | 실험 2를 unit 테스트로 옮겨 `retryable` 확인 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 02-05 `inspect()`가 marker만 읽고 candidate를 `verified: true`로 보고한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(보장 범위 과장) | +| 관련 관점 | 24, 5, 8 | +| 근거 | `public-response-cache-adapter.ts:857-875`는 marker JSON과 그 안의 digest만 확인하고 모든 candidate에 `verified: true`를 넣는다. 같은 파일의 원칙 주석은 "marker는 staging이 끝났다는 주장일 뿐, entry가 남아 있다는 증거가 아니다"라고 적고 stage·activate에서는 entry를 다시 검증한다(`:471-481`, `:665-684`). port 타입은 `verified: boolean`이지만(`cache-storage-ports.ts:46-50`) 실제 값은 항상 `true`다 | +| 발생 조건 | 브라우저가 candidate의 entry 일부를 지웠거나 손상됐는데 marker는 남아 있다 | +| 영향 | `inspect()`로 롤백 대상이나 상태를 판단하는 운영자·조립 코드가 쓸 수 없는 candidate를 검증됨으로 본다. activate가 다시 검증하므로 잘못 활성화되지는 않는다 | +| 심각도·우선순위 | Low · P3 — 진단 정보 오류, 실제 활성화는 막힌다 | +| 통제·증거 | M1 · E1 | +| 확실성과 남은 가정 | 코드로 확정. 현재 소비자 없음 | +| 최소 개선 방향 | 필드를 `markerValid`처럼 실제 보장으로 바꾸거나, entry 재검증 결과(`verifyReleaseCandidate`)를 반영한다 | +| 비용·부작용 | 재검증을 넣으면 inspect 비용이 entry 수에 비례해 는다. 이름만 바꾸면 port 타입 변경 | +| 완료 기준 | entry가 없는 candidate가 검증됨으로 보고되지 않는다 | +| 검증 방법 | entry 하나를 지운 뒤 `inspect()` 결과 확인하는 테스트 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 02-06 다운로드 취소와 browser handoff 성공이 관측 기록에서 똑같이 보인다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(진단 정보 손실) | +| 관련 관점 | 8, 6 | +| 근거 | file observer가 `DISMISSED`를 `SUCCEEDED`로 바꾼다(`file-observer.ts:32-33`). `BROWSER_MANAGED` 성공은 바이트 수가 없어 byteBucket이 빠진다(`download-delivery-adapter.ts:470-478`, 기본 `bytes = null` `:1097`). 저장 대화상자 취소도 byteBucket 없이 기록된다(`:535-541`, `:557-562`). 두 경우 모두 `{operation: "DOWNLOAD", outcome: "SUCCEEDED"}` 한 가지로 남는다 | +| 발생 조건 | 기본 동작 | +| 영향 | 저장 대화상자 취소율과 handoff 성공률을 관측으로 나눌 수 없다. 문서는 취소를 error telemetry로 남기지 말라고 하지만(`browser-file-and-origin-storage.md` 3.2절), 성공으로 합치라는 뜻은 아니다 | +| 심각도·우선순위 | Low · P3 — Result는 구분된다. 관측만 문제 | +| 통제·증거 | M2 · E1 | +| 확실성과 남은 가정 | 코드로 확정 | +| 최소 개선 방향 | `BrowserDataObservation.outcome`에 `DISMISSED`를 추가하거나, 취소는 관측하지 않는다 | +| 비용·부작용 | 관측 타입 변경(공용 port) | +| 완료 기준 | 두 경우가 서로 다른 관측으로 남는다 | +| 검증 방법 | observer 기록을 비교하는 unit 테스트 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 02-07 캐시 조회 한 번의 비용이 여전히 크다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 14 | +| 근거 | `matchActiveExact` 한 번에 `caches.keys()` 2번(`readActivePointer` `public-response-cache-adapter.ts:992`, `:260`), active pointer JSON 읽기·파싱, 본문 전체 읽기(`:338-344`), 본문 SHA-256, 본문 복사 4번(읽기 버퍼, digest 입력 `Uint8Array.from` `:180-186`, `byteSourceFrom` 저장 `:1011`, stream마다 `:1019`)이 일어난다. entry 상한은 16 MiB라 조회 한 번에 최대 약 64 MiB를 할당한다 | +| 발생 조건 | Service Worker처럼 요청마다 조회하는 소비자를 붙일 때 | +| 영향 | 페이지 로드 한 번에 asset 수 × 본문 크기 × 4의 할당과 GC 부담 | +| 심각도·우선순위 | Low · P3 — 현재 소비자 없음(`AVAILABLE_NOT_COMPOSED`). 문서가 "static asset handler에서 재사용"을 목표로 적어 도입 시 비용이 된다 | +| 통제·증거 | M1 · E1(측정 안 함) | +| 확실성과 남은 가정 | 복사 횟수는 코드로 확정. 실제 지연·메모리는 미측정 | +| 최소 개선 방향 | `byteSourceFrom`이 읽은 버퍼를 그대로 쓰고(복사 2번 제거), `readActivePointer`가 받은 이름 목록을 재사용한다 | +| 비용·부작용 | 반환 버퍼를 호출자가 수정할 수 있게 되므로 stream에서 한 번만 복사하거나 freeze 규칙을 문서화 | +| 완료 기준 | 조회당 `keys()` 1번, 본문 복사 2번 이하 | +| 검증 방법 | 가짜 CacheStorage의 `keys` 호출 수를 세는 테스트 | +| 담당·기한·상태 | 미정 · 미정 · 부분 해결 | +| 직전 리뷰 | 6.2-6 일부 미해결(marker 메모·Map은 해결) | + +### 02-08 보안·자원 규칙 5개가 다른 조건에 가려 테스트에서 검출되지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험(테스트 공백) | +| 관련 관점 | 10, 15, 12 | +| 근거 | 변이 실험에서 아래 규칙을 지워도 관련 테스트가 전부 통과했다. (1) browser-managed download의 다른 origin 거부 `download-input-validation.ts:346` — 유일한 테스트 `browser-file-download.test.ts:294-323`이 다른 origin과 query를 한 URL에 같이 넣어 query 검사가 대신 막는다. (2) vault 누적 보관 바이트 상한 `browser-file-vault.ts:713-718` — `browser-file-content.test.ts:685-713`이 참조 개수 상한 1을 같이 걸어 개수 검사가 먼저 막는다. (3) preview Blob을 검증된 타입으로 다시 만드는 규칙 `object-url-lease.ts:280-285`. (4) native picker의 user activation 검사 `browser-file-picker.ts:249-254`. (5) 처음 보는 source의 첫 이벤트 seq>1을 `GAP`으로 보는 규칙 `browser-cross-context-invalidation.ts:509` | +| 발생 조건 | 리팩터링으로 해당 줄이 빠진다 | +| 영향 | (1)은 서버가 준 href가 다른 origin이어도 handoff하게 되고, (5)는 탭이 놓친 이벤트를 한 topic 무효화로만 처리하게 된다. 나머지는 방어 규칙 약화 | +| 심각도·우선순위 | Low · P3 — 현재 코드는 맞다 | +| 통제·증거 | M2 · 검출 M0 확인(변이 실험) | +| 확실성과 남은 가정 | 같은 실험에서 결과가 같았던 변이 4개(redirect 검사, Vary cookie, forbidden query, eventId 중복 제거)는 다른 검사가 대신 막아 공백으로 세지 않았다 | +| 최소 개선 방향 | 규칙마다 그 규칙만 걸리는 입력으로 테스트 하나씩 추가한다(예: query 없는 다른 origin href, 참조 상한은 넉넉하고 바이트만 넘는 선택) | +| 비용·부작용 | 테스트 5개 | +| 완료 기준 | 위 5개 변이가 각각 테스트에서 실패한다 | +| 검증 방법 | 같은 변이 재실행 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 02-09 cross-tab 무효화 설계 문서가 현재 구현보다 뒤처져 있다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(문서 불일치) | +| 관련 관점 | 9, 17 | +| 근거 | `docs/architecture/client-cache-and-storage.md:82-84`는 "pulse key가 storage registry 밖 상수, storageArea 미검증"이라 적지만 코드는 registry key(`browser-cross-context-host.ts:36-37`)와 storageArea 동일성 검사(`browser-cross-context-invalidation.ts:197-201`)를 쓴다. `:85`의 epoch 형식 `release.`는 현재 FNV-1a 해시(`browser-cross-context-host.ts:45-51`)다. `:86`은 "scope 전환 시 새 QueryClient 생성 미구현"이라 적지만 `server-state-generation-store.ts:50-57`이 세대마다 새로 만든다. `:119` 표도 "registered pulse, storageArea"를 미구현으로 둔다. 문서 마지막 수정 2026-08-01, host 코드 마지막 수정 2026-09-24 | +| 발생 조건 | 다운스트림이 문서로 지원 범위를 판단할 때 | +| 영향 | 이미 있는 기능을 다시 구현하거나, 반대로 남은 미구현(session/account epoch)을 구분하기 어렵다 | +| 심각도·우선순위 | Low · P3 — 실제보다 적게 주장하는 방향이라 위험은 작다 | +| 통제·증거 | M1 · E1 | +| 확실성과 남은 가정 | 코드와 문서 대조로 확정 | +| 최소 개선 방향 | 해당 문단과 표 한 행을 현재 코드에 맞춘다 | +| 비용·부작용 | 문서 수정 | +| 완료 기준 | 문서의 현재 상태 설명이 코드와 일치한다 | +| 검증 방법 | `verify:documentation` 범위에 포함되는지 확인 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +## 5. 28개 관점 판정 (36.2) + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +|---|---|---|---|---|---| +| 1 | 코드 성숙도 | 적용 | 목표 M2 / 확인 M2 — 정책 깊은 snapshot, 닫힌 실패 코드, 조립 시 상한 검증 | E1, E2 | 부분 충족 — preview abort 계약 위반(02-01) | +| 2 | 구조적 성숙도 | 적용 | M3 목표 — adapter 간 import는 kernel(`browser-file-storage/result.ts`, `platform/abortable-operation.ts`)만, 외부는 port·contracts | E1(import 전수 확인) | 충족 — 게이트 실행은 오케스트레이터 | +| 3 | 변경 용이성 | 적용 | M2 — 새 파일 정책은 composition의 profile 추가, 새 topic은 registry 추가 | E1 | 충족 | +| 4 | 인지 부하 | 적용 | — | E1 | 부분 충족 — 본 파일 2개가 각 1.1k줄대, 주석에 리뷰 ID(Q-6.2-x, STO-RR-05, TR-RR-04)가 많아 규칙보다 이력을 먼저 읽게 된다 | +| 5 | 위험 가시성 | 적용 | M1~M2 — `BROWSER_HANDOFF`/`SAVED`, `integrity: NOT_PROVIDED`, 닫힌 recovery 어휘 | E1 | 부분 충족 — 02-01(abort 계약 불명), 02-05 | +| 6 | 실패 성숙도 | 적용 | M2 — 취소·abort·권한 거부를 Result에서 구분, 늦은 자원 보상 | E1, E2 | 부분 충족 — 02-04(재시도 의미), 02-06(관측). picker는 cancel·focus가 모두 안 오는 엔진에서 signal이 없으면 `BLOCKED`로 남을 수 있음(현 지원 엔진에서는 미확인) | +| 7 | 운영 성숙도 | 적용(연결점) | M2 — file·cache·cross-context observer, cross-context는 bootstrap이 diagnostics로 연결(`runtime-adapters.ts:358-373`) | E1 | 부분 충족 — file·cache observer는 recipe 조립 몫 | +| 8 | 디버깅 가능성 | 적용 | M2 — 개인정보 없는 닫힌 관측(파일명·URL·키 미포함) | E1 | 부분 충족 — 02-05, 02-06 | +| 9 | 유지보수 성숙도 | 적용 | M1 | E1 | 부분 충족 — 02-09 문서 불일치 | +| 10 | 테스트 성숙도 | 적용 | M3 목표 | E2(121 통과), 변이 22개: 검출 11, 동등 4, 미검출 규칙 6 | 부분 충족 — 02-02, 02-08. 실제 브라우저 spec은 미실행 | +| 11 | 데이터 성숙도 | 적용 | M2 — Cache Storage는 익명 공개 응답만, 로그아웃 purge 불필요 | E1 | 부분 충족 — 규칙 테스트 없음(02-02), file runtime scope 미연결(02-03) | +| 12 | 동시성 성숙도 | 적용 | M3 — 탭 간 중복·역순·gap, 캐시 변경은 Web Lock, picker별 pending | E2(cross-tab 17개 테스트) | 부분 충족 — 02-01(같은 turn abort 경쟁). stage 후 activate 전 cleanup이 candidate를 지우는 창은 설계상 허용·문서화됨(`browser-file-and-origin-storage.md` 8.3절) | +| 13 | 확장성 | 적용(구조) | M2 — source 256·dedupe 1024 LRU, profile ≤128, entry ≤500 | E1 | 충족 — 부하 측정 없음 | +| 14 | 성능 성숙도 | 적용 | M2 — 모든 바이트·개수 상한 | E1, E2 | 부분 충족 — 02-07, 02-04. `BOUNDED_OBJECT_URL`은 chunk 복사+Blob 생성으로 최대 약 2×`maxBufferedBytes`가 잠시 필요(문서 식의 copy factor에 값이 없음) | +| 15 | 보안 성숙도 | 적용 | M2 — 파일명 무력화, MIME은 signature 기준, active content 금지, 불투명 참조, canonical handoff URL, 캐시 익명 요청 | E1, 변이 실험 | 부분 충족 — 규칙 일부가 테스트로 고정되지 않음(02-02, 02-08). download 정책의 `safeExtension`·`mediaType` 위험값(`.html`, `text/html`)은 composition 신뢰로 허용(문서화된 선택) | +| 16 | 의존성 성숙도 | 적용 제외 — 세 폴더 모두 외부 패키지 import 없음(브라우저 API와 repo 내부 모듈만) | — | E1 | 적용 제외 | +| 17 | API / Contract 성숙도 | 적용 | M2 — port 타입, wire protocol version·크기·TTL·epoch 검사 | E1, E2 | 부분 충족 — 02-05, 02-09. `DownloadOutcome` 타입에 의미 주석이 없어 설계 문서를 봐야 함 | +| 18 | 배포 성숙도 | 적용 | M2 — release별 cacheEpoch, 캐시 release stage/activate/이전 release 보존 | E1 | 부분 충족 — release가 다른 탭끼리는 무효화 hint가 오가지 않음(설계상 선언, focus refetch가 완화) | +| 19 | 설정 성숙도 | 적용 | M3 — 잘못된 상한·정책은 조립 시 TypeError | E2 | 충족 | +| 20 | 개발자 경험 | 다른 영역 — 전체 DX는 오케스트레이터/문서 영역 | — | — | 적용 제외 | +| 21 | Guardrail 성숙도 | 적용 | eslint·dependency-cruiser·`check:optional-recipes` 대상에 포함(`eslint.config.ts:521-524`, `:684-687`) | E0(이번에 실행 안 함) | 미검증 — 게이트 결과는 오케스트레이터 | +| 22 | 추상화 성숙도 | 적용 | — | E1 | 부분 충족 — 네이티브 API를 조립 시 bind·snapshot하는 facade는 목적이 분명함. lease registry 공유가 preview와 download의 한도를 묶음(02-04) | +| 23 | 일관성 | 적용 | — | E1 | 부분 충족 — preview만 await 뒤 abort를 다시 보지 않음(02-01). cache 관측(`PublicCacheSafeObservation`, bucket `1B_1MiB`)과 file 관측(`BrowserDataObservation`, bucket `LT1MIB`)의 어휘가 다름 | +| 24 | 네이밍 / 의미 | 적용 | — | E1 | 부분 충족 — `deliver`의 결과 `BROWSER_HANDOFF`/`SAVED`, `matchActiveExact`, `cleanupOwned`는 보장과 맞음. `inspect().verified`만 과장(02-05) | +| 25 | 조직 확장성 | 적용 제외 — 1인 관리. 구조적 준비만: feature별 정책 reference, topic registry | — | E1 | 적용 제외 | +| 26 | Ownership | 다른 영역 — recipe owner는 `project-owner-required` | — | E1 | 적용 제외 | +| 27 | 삭제 가능성 | 적용 | M3 목표 — topic 0개면 host가 브라우저 기능을 조회조차 안 함(`browser-cross-context-host.ts:62`), recipe 제거 스크립트 존재 | E1 | 미검증 — `test:browser-file-storage-removal`·`check:optional-recipes` 미실행 | +| 28 | 회복 가능성 | 적용 | M2 — 캐시 이전 release 보존·재활성화, `REHYDRATE` 복구 코드, GAP 시 전체 무효화 | E1, E2 | 부분 충족 — 실제 브라우저 eviction 뒤 복구는 미확인 | + +## 6. 미검증 목록 + +| 항목 | 확인하려면 | +|---|---| +| 실제 Chromium·Firefox·WebKit에서 picker·download·Cache API·BroadcastChannel/storage fallback 동작 | `test:browser-capabilities`를 현재 커밋에서 3개 엔진으로 실행하고 결과 보존 | +| Safari에서 blob URL 다운로드 30초 grace가 충분한지, runtime dispose 직후 handoff가 살아남는지 | WebKit 실제 다운로드 실험 | +| 다른 탭에서 계정이 바뀐 뒤 이 탭이 받는 무효화 hint가 이전 사용자 세대 캐시에 새 세션 응답을 채우는지 | auth 영역의 탭 간 세션 변경 감지 여부 확인 후 2탭 E2E(탭 A 로그아웃·B 로그인 → 탭 B mutation → 탭 A 상태 확인) | +| picker의 `cancel`·window `focus`가 모두 오지 않는 엔진 존재 여부(있다면 signal 없는 `select()`가 `BLOCKED`로 남음) | 지원 브라우저 목록 확정 후 실기기 확인 | +| Chrome `showSaveFilePicker`가 확정 시 빈 파일을 먼저 만드는지(이후 source 실패 시 0바이트 파일 잔존) | Chromium 실기 실험 | +| 캐시 조회 비용(02-07)의 실제 지연·메모리 | SW 소비자를 붙인 뒤 asset 수·크기별 측정 | +| 삭제 가능성·guardrail 게이트 | `check:optional-recipes`, `test:browser-file-storage-removal`, `check:architecture` 실행(오케스트레이터) | diff --git a/docs/reviews/2026-09-25-maturity-review/03-adapters-http-state.md b/docs/reviews/2026-09-25-maturity-review/03-adapters-http-state.md new file mode 100644 index 00000000..1a01d4b7 --- /dev/null +++ b/docs/reviews/2026-09-25-maturity-review/03-adapters-http-state.md @@ -0,0 +1,248 @@ +# HTTP·서버 상태·인증·진단 성숙도 리뷰 + +> 검토일: 2026-09-25 · 기준: `main` / `4626b73` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 범위: `src/adapters/http/`(4.6k줄), `src/adapters/browser-rpc/`(2.0k줄), `src/adapters/query-cache/`(1.1k줄), `src/adapters/auth/`(0.2k줄), `src/adapters/diagnostics/`(0.1k줄), `src/adapters/telemetry/`(0.5k줄) — 약 8.5k줄. 흐름 추적을 위해 조합 루트(`src/bootstrap/runtime-adapters.ts`, `server-state-generation-store.ts`), reference feature의 HTTP 경로, `presentation/adapters/query/application-query.ts`의 mutation 경로를 함께 읽었다. +> 영역 판정(35.8): **조건부 사용 가능** — 조회(query)·로그아웃·인증 세대·전송 상한은 그대로 복제해도 된다. 쓰기(command) 샘플은 03-01을 고치기 전까지 "결과 불명 쓰기의 처리 방식" 예제로 복제하지 않는다. + +## 1. 결론 + +- **조회 경로는 튼튼하다.** V3 실행기는 전체 마감 하나, 재시도 권한 하나, 응답 본문 상한, 인증 세대 확인(전송 전·응답 후)을 모두 갖췄다. 로그아웃 중 도착한 응답은 버려지고, 세대마다 QueryClient를 새로 만든다. 핵심 규칙 4개에 일부러 결함을 넣었을 때 테스트가 모두 잡았다. +- **결과 불명인 쓰기의 복구가 비어 있다(03-01, High).** 계약은 `commandRecovery: IDEMPOTENCY_REPLAY`(같은 키로 다시 보내기)를 선언하지만 실행하는 코드가 없다. 화면은 사용자에게 "변경됨/변경되지 않음"을 **추측**하게 하고, 다시 저장하면 **새 멱등 키**가 만들어진다. 504 같은 응답 유실 뒤에 중복 생성이 가능하다. 설계 문서(§8.8~8.9)와 runbook(6.3-4)이 금지한 동작이다. +- **명령의 401/403/429가 무조건 "결과 불명"이 된다(03-02).** 세션 만료 중 저장하면 "재로그인" 대신 "지원 문의"가 뜨고, 429는 03-01의 추측 화면으로 이어진다. +- **문의 식별자가 서버 기록까지 이어지지 않는다(03-03).** V3는 응답의 `x-correlation-id`를 읽고 버린다. 기본 요청에는 요청 식별자 헤더도 없다. V2에는 있던 연결이 권장 경로(V3)에서 끊겼다. +- 나머지: V3로는 422 필드 오류가 폼까지 가지 못한다(03-04). 텔레메트리 배치 크기가 브라우저 keepalive 한도(64KiB)와 맞지 않는다(03-05, 3개 엔진에서 거절 재현). +- 미검증: 실제 백엔드의 멱등 키 보관·충돌 처리, 외부 auth owner의 갱신 동작, 여러 탭 동시 로그아웃, 게이트웨이 리다이렉트형 세션 만료. + +## 2. 범위와 방법 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 | `clean-architecture-frontend-template`, `main` / `4626b73`. 미커밋은 `CLAUDE.md`, 리뷰 가이드뿐 | +| 목적과 실행 구성 | 프론트엔드 템플릿. 브라우저 SPA, SSR 없음. 인증 `demo`/`external`. 여러 탭 지원 | +| 읽은 코드 | 범위 6개 폴더 전체. 추가로 `src/bootstrap/runtime-adapters.ts`, `src/bootstrap/server-state-generation-store.ts`, `src/contracts/errors.ts`, `src/contracts/external-contract-runtime.ts`(계약 검증부), `src/platform/telemetry/trace-context.ts`, `src/adapters/platform/browser-mutation-intent-factory.ts`, reference feature(`contracts/`, `adapters/`, `application/`, `presentation/`), `src/presentation/adapters/query/application-query.ts`(mutation 부분), `src/presentation/forms/{form-contracts,use-app-form}.ts`, `src/presentation/components/async-surface.tsx` | +| 읽은 문서 | `docs/operations/api-contract-and-server-state-recovery.md`, `docs/architecture/starter-experience.md`(외부 owner), `docs/architecture/decisions/VD-07-*.md`, 설계서 `2026-07-30-...-closed-deep-design.md` §4.4, §8.3~8.10 | +| 실행한 테스트 | `node scripts/run-vitest.ts run` 로 영역 테스트 45개 파일(unit: http·bridge·retry·scope·coordinator·telemetry·auth·cursor·conditional·body-reader·query-cache·diagnostics·browser-rpc·runtime-adapters, integration: `http-*`·`auth-recovery`·`legacy-http-credential-authority`, contract: `feature-http-binding`, `tests/features/reference-feature`) → **45 passed / 480 tests passed** | +| 결함 주입 실험 | 분리 worktree에서 7개 변형 → 결과는 아래 표. 실험 후 worktree 삭제 | +| 브라우저 실험 | Playwright(chromium·firefox·webkit)로 로컬 서버에 `telemetry-collector.ts`와 같은 옵션(`keepalive:true`, JSON POST)을 보냄 → 60KB 성공, 70KB는 **세 엔진 모두 거절**, 40KB 두 개 동시 전송은 chromium·firefox에서 둘 다, webkit에서 하나 거절 | +| 측정 | `api.request.failed` 이벤트 1건 직렬화 288B, 100건 배치 28.9KB(`projectTelemetryEvent` 실제 출력) | +| 확인하지 못한 범위 | 실제 백엔드·외부 auth owner·RPC provider와의 통합, 여러 탭 동시 시나리오, 브라우저에서 앱 전체를 띄운 E2E(다른 영역 담당) | +| 이전 리뷰와 비교 | `2026-09-24-src-full-review.md` 6.3-1~12를 현재 코드에서 다시 확인했다. 모두 고쳐졌다(아래) | + +결함 주입 결과(관점 10): + +| 변형 | 결과 | +|---|---| +| M1 응답 검증 뒤 scope 확인 제거(`http-execution-v3.ts:1341`) | 통과(생존). 같은 경우를 lifetime signal 경로(`:992`)가 먼저 잡는 중복 방어라 실제 위험은 아님 | +| M2 `MAYBE_APPLIED` 응답도 재전송 허용(`:999`) | 검출 — `http-execution-v3.test.ts` | +| M3 요청 전 미인증에도 `onUnauthenticated` 호출(`runtime-adapters.ts:543`) | 검출 — `reference-runtime-composition.test.ts` | +| M4 같은 (상태, 주체) 알림에도 fence(`server-state-scope-runtime.ts:102`) | 검출 — 3건 | +| M5 경로 값 `.`/`..` 검사 제거(`http-contract-bridge.ts:203`) | 검출 — 2건 | +| M6 KEYED를 전송 후에도 재시도(`http-retry-lifecycle.ts:27`) | 실행기 테스트는 생존, 순수 함수 단위 테스트(`http-retry-lifecycle.test.ts`)만 검출 | +| M7 응답 `x-correlation-id` 수집 제거(`http-execution-v3.ts:1590`) | 생존 — 소비자가 없어 아무것도 깨지지 않음(03-03 근거) | + +직전 리뷰(6.3) 재확인: 6.3-1(`http-contract-bridge.ts:200-208`, `request-builder.ts:73-86`), 6.3-2(`server-state-scope-runtime.ts:96-108`, `runtime-adapters.ts:543`, `external-session-adapter.ts:122-128`), 6.3-3(`feature-http-binding.ts:378-397`), 6.3-4(`http-contract-bridge.ts:58`, `:393-399`), 6.3-5(`feature-http-binding.ts:300-333`), 6.3-6(`http-execution-v3.ts:603-619`), 6.3-7(`:995-1037`), 6.3-8(`tanstack-cache-coordinator.ts:79-92`), 6.3-9(`browser-rpc-runtime.ts:303-309`, `:357-371`), 6.3-10(`telemetry-collector.ts:77-105`), 6.3-11(`client.ts:340-344`), 6.3-12(`cursor-pagination-runtime.ts:112-126`, `conditional-validator-store.ts:139-151`) 모두 수정 확인. 6.3-4의 잔여로 auth 어댑터의 자체 검증(`external-session-adapter.ts:31-56`, CR/LF만 검사)이 bridge와 규칙이 다르게 남아 있지만, bridge가 전송 전에 최종 판정하므로 결과는 안전하다. 별도 항목으로 올리지 않는다. + +## 3. 확인된 강점 + +1. **대기 전체를 하나의 마감과 하나의 재시도 권한이 관리한다.** 자격증명 조회, 동시성 lease, fetch, 본문 읽기, 백오프가 모두 같은 lifetime signal과 경쟁한다(`http-execution-v3.ts:519-564`, `:713-723`, `:922-926`, `:967-989`). 재시도 상한은 `min(계약 retryBudget, MAX_RETRY_ATTEMPTS, 하드 상한 2)`이다(`:792-796`). TanStack의 query·mutation 재시도는 꺼져 있어 중첩 재시도가 없다(`tanstack-query-cache.ts:12-19`). `Retry-After`는 5초를 넘으면 기다리지 않고, 기다릴 때도 jitter를 더해 동시 재시도를 흩는다(`http-retry-lifecycle.ts:54-66`). `REQUEST_TIMEOUT_MS`는 계약 마감을 줄일 수만 있다(`http-execution-v3.ts:428-433`). +2. **인증 세대(로그인 상태가 바뀌기 전후를 구분하는 클라이언트 내부 번호)가 실제로 늦은 응답을 막는다.** (상태, 주체)가 바뀔 때만 세대를 올리고, 진행 중 요청을 abort하고, QueryClient를 통째로 새로 만든다(`server-state-scope-runtime.ts:96-179`, `server-state-generation-store.ts:50-58`). V3는 전송 직전과 응답 검증 뒤에 세대를 다시 확인한다(`http-execution-v3.ts:813-819`, `:882-906`, `:1341-1346`). 서버 401만 세션 판정으로 넘긴다(`runtime-adapters.ts:540-545`). 빠른 필터 변경은 필터별 query key로 분리돼 늦은 응답이 현재 화면을 덮지 않는다. +3. **쓰기 결과의 확실성을 타입으로 나눈다.** 전송 시점부터 `MAYBE_APPLIED`로 올라가고 내려가지 않는다(`http-effect-certainty.ts:36-73`, `http-execution-v3.ts:916-921`). `MAYBE_APPLIED` 응답은 자동 재전송하지 않는다(`:995-1003`). `createFailure`는 `MAYBE_APPLIED`면 `retryable:false`로 바꾼다(`contracts/errors.ts:292-296`). +4. **자격증명 경계가 좁다.** 설치된 auth profile이 `credentials` 모드와 허용·필수 헤더를 정한다. 값은 ByteString으로 검사하고 `new Headers()`로 미리 만들어 본다(`http-contract-bridge.ts:58-106`, `:344-410`). 요청은 `redirect:"error"`, `referrerPolicy:"no-referrer"`, `cache:"no-store"`로 나간다(`http-execution-v3.ts:869-880`). 브라우저 HTTP 캐시에 사용자 응답이 남지 않는다. 토큰 보관은 외부 owner 책임이고(`docs/architecture/starter-experience.md:52-68`), demo는 비밀이 아닌 고정 marker를 쓴다(`external-session-adapter.ts:106`). +5. **텔레메트리 라벨은 값 종류가 끝없이 늘어나지 않는다.** 속성은 닫힌 allowlist와 값 문법을 통과해야 한다(`contracts/telemetry.ts:4-13`, `:110-132`). HTTP projector는 route/operation ID와 버킷만 보낸다(`runtime-adapters.ts:233-240`). 수집기 전송은 타임아웃·`credentials:"omit"`·전송률 제한을 공유한다(`telemetry-collector.ts:48-105`). +6. **응답 본문을 순서대로 제한한다.** 선언 길이 → 스트림 누적 바이트 → JSON 구조 예산 → 스키마 검증 순이다(`bounded-body-reader.ts:57-110`, `http-execution-v3.ts:1230-1338`). 오류 본문은 64KiB로 따로 제한한다(`:1474-1478`). + +## 4. 발견 사항 (36.3) + +### 03-01 결과 불명인 KEYED 쓰기: 선언된 "같은 키 재전송" 복구가 없고, 사용자 추측 뒤 새 멱등 키로 다시 보낸다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 6, 12, 17, 24, 28, 5 | +| 근거 | ① reference 생성 계약이 `retrySemantics:"KEYED"`, `commandRecovery:{mode:"IDEMPOTENCY_REPLAY", operationIdentityField:"idempotencyKey"}`를 선언한다(`src/features/reference-feature/contracts/reference-feature-contract-contribution.ts:169-176`). ② 이 descriptor는 설치 때 존재 여부만 검사되고(`src/contracts/external-contract-runtime.ts:473-485`) 실행 코드가 읽는 곳이 없다(grep: 그 외 소비처는 예제 화면 표시 `src/presentation/examples/platform-overview-page.tsx:272`뿐). ③ `MAYBE_APPLIED`가 되면 화면은 "변경 결과를 확인할 수 없습니다" + "변경됨으로 확인 / 변경되지 않음으로 확인" 버튼만 준다(`src/presentation/components/async-surface.tsx:155-167`, `src/presentation/i18n/catalog.ts:14-15`, `:60`). 사용자가 서버 상태를 확인할 수단은 없다. ④ "변경되지 않음"을 누르면 폼 값이 그대로 남고(`src/presentation/forms/use-app-form.ts:170-176`) 다시 저장하면 `submit`마다 새 intent를 만든다(`src/presentation/adapters/query/application-query.ts:509-514`). 키는 매번 `randomUUID()`다(`src/adapters/platform/browser-mutation-intent-factory.ts:36-40`). ⑤ 설계서는 "같은 submit의 transport retry/reconcile에는 동일 intent/key, form value가 변경되면 새 intent"(`docs/architecture/2026-07-30-...-closed-deep-design.md:1707-1708`)와 "recovery descriptor 확인 → inspect → no effect일 때만 사용자 재시도"(`:1714-1724`)를 요구하고, runbook은 "`UNKNOWN` effect에 새 key를 생성해 retry하지 않는다"(`docs/operations/api-contract-and-server-state-recovery.md:228`)고 적는다 | +| 발생 조건 | 생성 요청이 서버에 도착한 뒤 응답을 잃는다: 게이트웨이 504(빈 본문), 네트워크 끊김, 전체 마감 초과(`http-execution-v3.ts:1479-1491`, `:916-921`). 사용자가 "변경되지 않음"을 누르고 같은 값으로 다시 저장한다. 03-02의 401/403/429도 같은 화면으로 들어온다 | +| 영향 | 첫 요청이 실제로 반영됐으면 서버에 같은 리소스가 두 번 생긴다. 서버가 멱등 키를 지원해도 키가 달라 막을 수 없다. 반대로 "변경됨"을 잘못 고르면 사용자의 입력이 저장된 것으로 처리돼 사라진다(`use-app-form.ts:164-168`). 탐지가 어렵다(사용자는 성공한 줄 안다). | +| 심각도·우선순위 | High · P1 — 지원하는 장애 조건(응답 유실)에서 쓰기 중복이 가능하고, 가이드 35.2의 "결과 불명 작업의 무방비 재실행"에 해당한다. 유일한 쓰기 샘플이라 다운스트림의 모든 KEYED 명령에 그대로 복제된다. 즉시 피해가 난 증거는 없으므로 P0는 아니다 | +| 통제·증거 | M1(설계서·runbook에 규칙 명시, 구현 없음) · E1(정적 확인. 이 경로를 재현하는 테스트는 없다) | +| 확실성과 남은 가정 | 코드 경로는 확정. 실제 중복 생성 여부는 백엔드가 키 없이 같은 입력을 두 번 받아들이는지에 달려 있다(도메인 유일성 제약이 있으면 409로 끝난다) | +| 최소 개선 방향 | ① `UNKNOWN` 상태의 admission이 가진 intent를 보관하고, 같은 입력으로 다시 저장하면 **그 intent(같은 `Idempotency-Key`)로** 보낸다. 이것이 `IDEMPOTENCY_REPLAY`의 최소 구현이다. ② `INSPECT_OPERATION` descriptor가 없으면 "변경되지 않음으로 확인" 버튼을 없애거나 "같은 요청으로 다시 보내기"로 바꾼다. 대안: 목록 재조회로 사용자가 확인하게 하는 링크(서버 조회 없이 추측하게 두는 것보다 낫다) | +| 비용·부작용 | presentation mutation 코디네이터와 intent 수명 변경(영역 08과 겹침). 서버 멱등 키 보관 기간보다 늦은 재전송은 여전히 중복될 수 있어 그 한계를 문서에 적어야 한다 | +| 완료 기준 | `MAYBE_APPLIED` 뒤 같은 입력의 재전송이 첫 요청과 같은 `Idempotency-Key`를 보낸다. 입력이 바뀌면 새 키. 근거 없는 "변경되지 않음" 확정 경로가 없다 | +| 검증 방법 | 모의 서버: 첫 POST에 504 빈 본문 → 화면에서 재시도 → 두 요청의 `Idempotency-Key` 헤더가 같은지 단언하는 통합 테스트 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음(6.7-1은 키 공백 문제로 별개) | + +### 03-02 명령의 401/403/429가 패키지 분류기를 거치지 않고 `MAYBE_APPLIED`로 고정돼, 세션 만료 저장이 "지원 문의"로 끝난다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(설계 원칙과 사용자 행동 계약의 충돌) | +| 관련 관점 | 6, 15, 17, 5 | +| 근거 | 401·403·429는 `admitProblem`/`classifyProblemEffect`에 가기 전에 처리되고 명령이면 `certaintyForAbandonedAttempt("RESPONSE_HEADERS")` = `MAYBE_APPLIED`가 된다(`src/adapters/http/http-execution-v3.ts:1147-1180`). 패키지 분류기(`CommandEffectDescriptor.classifyProblem`)는 이 세 상태를 볼 기회가 없다. 바인딩은 `AUTH_REQUIRED`에 이 effect를 실어 보내고(`feature-http-binding.ts:341-344`), `createFailure`는 `MAYBE_APPLIED`면 action을 `contact-support`로 덮는다(`contracts/errors.ts:315-320`). 테스트 카탈로그가 이 값을 고정한다(`tests/mocks/scenarios/catalog.ts`의 `unauthenticated-401`·`forbidden-403`·`rate-limited-429` 명령 기대값 `MAYBE_APPLIED`) | +| 발생 조건 | 저장 중 토큰 만료(401), 권한 회수(403), 요청 제한(429) | +| 영향 | 32절 "세션 만료" 시나리오의 다음 행동이 "재로그인"이 아니라 "지원 문의"다. 외부 owner가 같은 주체로 조용히 갱신하면(세대 fence 없음) 401이 03-01의 추측 화면으로 들어간다. 429는 거의 항상 "처리 안 됨"인데도 사용자에게 추측을 요구한다. 데이터 손상은 없고 사용자 행동이 틀어진다 | +| 심각도·우선순위 | Medium · P2 — 흔한 조건(세션 만료)에서 안내가 틀리고 03-01의 발생 빈도를 키운다. 보수적 기본값 자체는 설계 원칙(`http-effect-certainty.ts:9-11`)이라 High로 올리지 않는다 | +| 통제·증거 | M2(의도된 구현) · E2(카탈로그 테스트 통과) | +| 확실성과 남은 가정 | 경로 확정. 실제 서버가 401/403/429에서 쓰기를 반영하지 않는다는 점은 서버 계약에 달려 있어, 그 판단을 패키지 분류기에 맡기자는 것이 제안의 요지다 | +| 최소 개선 방향 | `CommandEffectDescriptor`에 본문 없는 상태용 분류(예: `classifyStatus(status)`)를 선택적으로 추가해 401/403/429도 패키지가 판정하게 한다. 없으면 지금처럼 `MAYBE_APPLIED`. 별도로 `AUTH_REQUIRED`는 effect와 무관하게 `reauth`를 먼저 안내한다 | +| 비용·부작용 | 계약 타입 1개 필드 추가, 카탈로그 기대값 조정 | +| 완료 기준 | reference 생성 계약이 401/429를 `NOT_APPLIED`로 선언하면 화면이 재로그인/재시도를 안내하고 unknown 화면이 뜨지 않는다 | +| 검증 방법 | 시나리오 카탈로그의 명령 401/429 기대값 변경 + mutation 화면 컴포넌트 테스트 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 03-03 권장 경로(V3)에서 문의 식별자 → 서버 기록 연결이 끊겼다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 8, 7 | +| 근거 | V3는 응답의 `x-correlation-id`를 `metadata.correlationReference`로 읽지만(`http-execution-v3.ts:1583-1595`) 이 값을 쓰는 곳이 src 전체에 없다(grep: 정의 `:75`와 대입 `:1591`뿐). 바인딩의 `failure()`는 `requestId`를 넘기지 않고(`feature-http-binding.ts:437-450`), projector도 diagnostics에 correlation을 넣지 않는다(`runtime-adapters.ts:233-250`). VD-07은 diagnostics에 correlation ID를 허용한다(`docs/architecture/decisions/VD-07-diagnostics-and-telemetry-exporter.md` 결정 4). 요청 쪽도 비어 있다: `x-correlation-id`/`traceparent`는 `context.execution.trace`가 있을 때만 붙는데(`http-execution-v3.ts:786-790`) 운영 코드에서 trace를 가진 ExecutionContext를 만드는 곳이 없다(`createExecutionContext` 호출은 실행기 내부 `:461-475`뿐, trace 없음). 결과적으로 `AppFailure.requestId`(`contracts/errors.ts:254`)는 V3에서 항상 비고, "지원 문의" 화면은 고정 문자열 `REFERENCE-STATUS-DEMO`를 보여 준다(`reference-resource-status-page.tsx`). V2는 매 요청 `X-Correlation-ID`를 보내고 `requestId`를 채운다(`client.ts:599-602`, `:1008`). 결함 주입 M7(수집 제거)이 어떤 테스트도 깨지 않았다 | +| 발생 조건 | V3로 실행된 모든 요청의 실패 문의 | +| 영향 | 사용자 문의나 프론트 오류 한 건을 서버 로그의 요청 한 건과 이을 수 없다. 원인 좁히기가 시각·경로 추정에 의존한다 | +| 심각도·우선순위 | Medium · P2 — 가이드 35.2 Medium의 "주요 진단 정보 부족". 기본 경로라 모든 다운스트림에 복제된다 | +| 통제·증거 | M0(V3 경로의 연결 수단 없음) · E1 + E2(M7 생존) | +| 확실성과 남은 가정 | 확정. 서버가 `x-correlation-id`를 돌려주는지는 백엔드 계약에 달렸다 | +| 최소 개선 방향 | ① 바인딩에서 `metadata.correlationReference`를 `requestId`로 넘긴다. ② 논리 실행마다 요청 식별자 하나를 만들어 `x-correlation-id`로 보낸다(암묵 ExecutionContext의 `interactionId`는 지금 상수 `"implicit-operation"`이라 그대로 쓰면 안 된다). ③ projector diagnostics에 `correlation_id`를 넣는다(telemetry에는 넣지 않는다) | +| 비용·부작용 | 헤더 1개 추가로 CORS 허용 헤더에 `x-correlation-id`가 필요하다 | +| 완료 기준 | V3 실패의 `AppFailure.requestId`가 서버 응답 헤더 값과 같다. 매 요청에 요청 식별자가 있다 | +| 검증 방법 | 모의 서버가 `x-correlation-id`를 돌려주는 실패 시나리오에서 바인딩 결과·diagnostics 기록을 단언 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 03-04 V3로는 서버 422 필드 오류가 폼까지 가지 못한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 17, 3, 22 | +| 근거 | 기능의 문제 매핑 타입이 `{ kind, code }`뿐이다(`feature-http-binding.ts:73-76`). 바인딩은 `validationIssues`를 채우지 않는다(`:327-340`, `:437-450`). reference 문제 스키마는 `type/title/status/code` 외를 버린다(`reference-schemas.ts:41-48`). 폼은 `validationIssues`가 비면 일반 문구만 낸다(`presentation/forms/form-contracts.ts:63-67`). 그런데 reference 폼은 서버 필드 매핑(`allowedServerFields: ["name","note"]`, `reference-resource-form-page.tsx:40`)과 "422 정책을 실행합니다"(`:76`)를 보여 준다. 필드 매핑 테스트는 `createFailure`로 issues를 직접 만든 실패를 넣어서 V3를 거치지 않는다(`tests/component/form-foundation.test.tsx:118-124`) | +| 발생 조건 | 서버가 422에 필드별 오류를 돌려줄 때 | +| 영향 | 사용자는 어느 필드가 틀렸는지 모른다. 다운스트림은 샘플이 동작한다고 믿고 복제한 뒤 바인딩 계약을 따로 넓혀야 한다 | +| 심각도·우선순위 | Medium · P2 — 데이터 피해는 없지만 모든 폼 기능에서 반복 비용이 생기고, 샘플의 주장과 실제 동작이 다르다 | +| 통제·증거 | M0 · E1 | +| 확실성과 남은 가정 | 확정 | +| 최소 개선 방향 | `FeatureHttpProblemMapping`에 선택 필드 `validationIssues`를 추가하고 바인딩이 `projectValidationIssues`로 한정해 넘긴다. reference 문제 스키마에 상한 있는 `issues`를 추가한다 | +| 비용·부작용 | 공개 타입 1개 확장(기존 기능은 영향 없음) | +| 완료 기준 | 모의 서버 422(필드 오류 포함) → V3 → 바인딩 → 폼에서 해당 필드 오류 표시 | +| 검증 방법 | reference feature 통합 테스트 1건 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 03-05 텔레메트리 배치 크기가 브라우저 keepalive 한도(64KiB)와 맞지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 7, 14 | +| 근거 | 수집기는 모든 POST에 `keepalive:true`를 붙인다(`src/adapters/telemetry/telemetry-collector.ts:88-96`). Fetch 표준은 진행 중인 keepalive 요청 본문 합이 64KiB를 넘으면 네트워크 오류로 끝낸다. 반면 기능 텔레메트리 예산은 버퍼 256KiB·배치 50건이고(`src/platform/telemetry/telemetry-pipeline.ts:56-65`), 이벤트 하나는 키 64개·문자열 256자까지 허용한다(`redact-telemetry.ts:16-22`). 애플리케이션 큐는 한 번에 최대 100건을 보낸다(`best-effort-telemetry.ts:79`, `:203`). `pagehide`에는 두 큐가 동시에 보낸다(`:224-226`, `feature-telemetry.ts:104-106`). 실험: 70KB 단일 POST는 chromium·firefox·webkit 모두 거절, 40KB 두 개 동시 전송은 chromium·firefox에서 둘 다 거절. `api.request.failed` 100건 배치는 28.9KB라 기본 샘플만으로는 한도에 닿지 않는다 | +| 발생 조건 | 기능 이벤트 페이로드가 평균 약 1.3KB를 넘거나, 페이지 이탈 때 두 큐의 합이 64KiB를 넘을 때 | +| 영향 | 배치 전체가 `sink-failure`로 버려진다. 장애로 이벤트가 몰릴 때 가장 크게 잃는다. 버린 수는 집계된다(`best-effort-telemetry.ts:112-141`) | +| 심각도·우선순위 | Medium · P3 — 관측 손실이지만 기본 샘플에서는 발생하지 않는다 | +| 통제·증거 | M0(64KiB 기준의 크기 제한 없음) · E3(실험실 브라우저 3종) | +| 확실성과 남은 가정 | 거절 동작은 재현했다. 실제 기능 페이로드 크기는 다운스트림에 달렸다 | +| 최소 개선 방향 | 수집기에서 직렬화한 본문을 약 60KiB 이하로 나눠 보내거나, `keepalive`는 `pagehide` flush에만 쓰고 그 배치만 제한한다 | +| 비용·부작용 | 수집기 함수 하나 수정 | +| 완료 기준 | 64KiB를 넘는 큐가 여러 POST로 나뉘어 모두 전달된다 | +| 검증 방법 | 단위 테스트: 70KB 분량 이벤트 → 각 POST 본문이 한도 이하인지 단언 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 03-06 "KEYED" 재시도 규칙과 `REQUEST_TIMEOUT_MS`의 의미가 전송마다 다르다 + +| 필드 | 내용 | +|---|---| +| 성격 | 개선 제안 | +| 관련 관점 | 23, 6, 19, 4 | +| 근거 | V3는 KEYED 명령을 전송 후 자동 재시도하지 않는다(`http-retry-lifecycle.ts:21-34`). V2는 keyed를 타임아웃·5xx 뒤 같은 키로 다시 보낸다(`retry-policy.ts:38-60`, `client.ts:263-306`). Browser RPC도 `KEYED_COMMAND`를 같은 키로 재시도한다(`browser-rpc-runtime.ts:1513-1527`). `Retry-After` 상한도 V3 5초·V2 30초·RPC 프로필값으로 다르다. `REQUEST_TIMEOUT_MS`는 V3에서 상한(`runtime-adapters.ts:469`), V2에서 기본값이라 오퍼레이션이 더 길게 잡을 수 있다(`client.ts:154`, `:212`) | +| 발생 조건 | 오퍼레이션을 V2↔V3↔RPC로 옮기거나, 같은 설정으로 두 경로를 함께 쓸 때 | +| 영향 | 같은 이름의 정책이 중복 쓰기 동작을 조용히 바꾼다. 읽는 사람이 세 규칙을 따로 기억해야 한다 | +| 심각도·우선순위 | Low · P3 — V2는 기본 구성에서 조합되지 않고(`createRuntimeHttpClient` 호출처 없음) 각 규칙은 따로 보면 방어 가능하다 | +| 통제·증거 | M1(각 파일 주석) · E1 | +| 확실성과 남은 가정 | 확정 | +| 최소 개선 방향 | 전송별 KEYED 재시도·Retry-After·타임아웃 의미를 한 표로 문서화하고, V2 `timeoutMs` 옵션 설명에 "상한 아님"을 적는다 | +| 비용·부작용 | 문서 변경 | +| 완료 기준 | 한 곳에서 세 전송의 규칙을 비교할 수 있다 | +| 검증 방법 | 문서 리뷰 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 03-07 요청 전에 거절된 미인증(전송 0회)이 `api.request.failed`로 집계된다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 7 | +| 근거 | 자격증명이 없으면 fetch 없이 `UNAUTHENTICATED`(metadata 없음)가 된다(`http-execution-v3.ts:740-743`). `isTerminalNonAbortFailure`는 이 경우를 걸러내지 않아 `api.request.failed`를 보낸다(`runtime-adapters.ts:279-294`). 같은 파일은 이 결과를 "세션 판정이 아니다"라며 로그아웃 알림에서는 제외한다(`:540-545`) | +| 발생 조건 | 로그아웃·`recovery-pending` 상태에서 인증 필요 쿼리가 실행될 때 | +| 영향 | API 실패율 지표가 클라이언트 상태만으로 오른다. 증상 기반 알림이 오탐한다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M2 · E1 | +| 확실성과 남은 가정 | 집계 경로는 확정. 실제 빈도는 route 정책이 인증 전 쿼리를 막는 범위에 달렸다 | +| 최소 개선 방향 | `outcome === "UNAUTHENTICATED" && status === undefined`를 텔레메트리에서 제외(diagnostics는 유지) | +| 비용·부작용 | 조건 1줄 | +| 완료 기준 | 전송 0회 미인증은 diagnostics 1건, telemetry 0건 | +| 검증 방법 | `http-execution-v3-observability.test.ts`에 케이스 추가 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 03-08 HTTP 복구 runbook이 현재 코드보다 오래됐다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(문서) | +| 관련 관점 | 9, 26, 7 | +| 근거 | `docs/operations/api-contract-and-server-state-recovery.md`(기준일 2026-07-28)는 "auth fail-close/final invariant", "total logical deadline와 bounded response decoder"를 아직 `DESIGNED_NOT_IMPLEMENTED`라고 적고(`:16-21`), "external auth integration이 unavailable이어도 unchanged request가 전송될 수 있다"고 적는다(`:145`). 현재 V3는 전체 마감(`http-execution-v3.ts:458-484`), 본문 상한(`bounded-body-reader.ts`), 자격증명 없음·owner 장애 시 전송 0회(`http-execution-v3.ts:740-749`, `runtime-adapters.ts:479-484`)를 구현했다 | +| 발생 조건 | 장애 대응자가 runbook을 따를 때 | +| 영향 | 이미 있는 통제를 없는 것으로 보고 우회 조치를 하거나, 코드와 다른 전제로 원인을 찾는다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M1 · E1 | +| 확실성과 남은 가정 | 확정 | +| 최소 개선 방향 | 1절 상태 목록과 5.1·6.0절을 V3 기준으로 갱신한다. 6.3절 규칙은 03-01 수정 뒤 구현 위치를 연결한다 | +| 비용·부작용 | 문서 변경 | +| 완료 기준 | runbook의 "구현 안 됨" 목록이 코드와 일치 | +| 검증 방법 | 문서 리뷰 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +## 5. 28개 관점 판정 (36.2) + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +|---|---|---|---|---|---| +| 1 | 코드 성숙도 | 적용 — effect 확실성·intent 검증이 도메인 규칙 | M2 / M2(lattice는 단조 증가만) | E2 | 충족 — 확실성 규칙은 생성·재시도 경로에서 일관 | +| 2 | 구조적 성숙도 | 적용 — 배럴 공개 경계, 기능은 바인딩만 봄 | M3 / M3(의존성 검사는 영역 밖) | E1 | 충족 — 기능이 전송 정책을 설정할 수 없음(`feature-http-binding.ts:78-108`). 경계 검사는 다른 영역 | +| 3 | 변경 용이성 | 적용 — 오퍼레이션 추가·필터 추가 경로 | M2 / M2 | E1 | 부분 충족 — 오퍼레이션 추가는 계약+바인딩으로 예측 가능. 422 필드 전달은 공개 타입 확장 필요(03-04) | +| 4 | 인지 부하 | 적용 | — / — | E1 | 부분 충족 — `execute()` 약 600줄, V2·V3·RPC 세 재시도 어휘(03-06) | +| 5 | 위험 가시성 | 적용 — 29.4 문장을 채울 수 있는가 | M2 / M2 | E1 | 부분 충족 — 마감·재시도·상한은 계약 `frontend` 블록에 보임. 결과 불명 뒤 무엇이 일어나는지는 호출부에서 안 보이고 선언과 다름(03-01) | +| 6 | 실패 성숙도 | 적용 — 중점 | M3 / M3(조회), M1(결과 불명 쓰기) | E2 | 부분 충족 — timeout·재시도 대상·중첩 재시도·Retry-After는 충족. 결과 불명 쓰기 복구 미충족(03-01, 03-02) | +| 7 | 운영 성숙도 | 적용 — 라벨 cardinality, 수집 실패 격리 | M4 / M4(라벨 문법), M0(배치 크기) | E2·E3 | 부분 충족 — 라벨은 닫힘. keepalive 손실(03-05), 전송 0회 집계(03-07). diagnostics는 기본 sink 없이 메모리 100건(VD-07 결정대로) | +| 8 | 디버깅 가능성 | 적용 — 요청 식별자·원인 보존·민감정보 | M2 / M0(V3 식별자) | E1·E2 | 미충족 — 민감정보 제외와 오류 종류 보존은 충족. 문의 식별자 연결 끊김(03-03) | +| 9 | 유지보수 성숙도 | 적용 | M1 / M1 | E1 | 부분 충족 — V2 legacy 유지 이유는 문서화됨. runbook이 오래됨(03-08) | +| 10 | 테스트 성숙도 | 적용 — 영역 테스트 검출력 | M3 / M3 | E2 | 부분 충족 — 480건 통과, 결함 주입 7건 중 4건 검출·1건 중복 방어·1건 단위만 검출·1건 생존. 결과 불명 재전송 키, 422 전달, 배치 크기, correlation 테스트 없음 | +| 11 | 데이터 성숙도 | 부분 적용 — cursor 일관성만 | M3 / M3 | E2 | 충족 — snapshot 변경·cursor 반복·상한 검출(`cursor-pagination-runtime.ts:98-141`). 저장소 데이터는 다른 영역 | +| 12 | 동시성 성숙도 | 적용 — 늦은 응답·로그아웃 중 응답·중복 클릭 | M3 / M3 | E2 | 부분 충족 — 세대 fence·필터별 key·같은 탭 중복 클릭 차단 충족. 결과 불명 뒤 재전송이 같은 작업으로 식별되지 않음(03-01). 여러 탭 미검증 | +| 13 | 확장성 | 다른 영역 — 기능 수 증가는 extreme-scale 리뷰 | — | — | 적용 제외 | +| 14 | 성능 성숙도 | 적용 — 본문·구조·동시성 상한 | M3 / M3 | E2 | 충족 — 상한 전부 계약값. 텔레메트리 배치 크기만 예외(03-05) | +| 15 | 보안 성숙도 | 적용 — 토큰 보관·갱신·폐기, 로그아웃 후 캐시 | M3 / M3 | E2 | 충족 — 자격증명 헤더 경계, profile 소유 credentials, no-store, 세대별 QueryClient. 토큰은 외부 owner 소유로 문서화. 세션 만료 안내는 03-02 | +| 16 | 의존성 성숙도 | 다른 영역 | — | — | 적용 제외 | +| 17 | API / Contract 성숙도 | 적용 — 오류 envelope·런타임 스키마 | M3 / M3 | E2 | 부분 충족 — 성공·문제 본문 모두 런타임 검증. 선언된 recovery descriptor 미사용(03-01), 401/403/429 분류 불가(03-02), 422 필드 전달 불가(03-04) | +| 18 | 배포 성숙도 | 다른 영역 — release·SW | — | — | 적용 제외 | +| 19 | 설정 성숙도 | 적용 — `REQUEST_TIMEOUT_MS`, `MAX_RETRY_ATTEMPTS` | M3 / M3 | E2 | 부분 충족 — V3는 상한으로만 적용(`runtime-adapters.ts:462-470`, 테스트 있음). V2와 의미 다름(03-06) | +| 20 | 개발자 경험 | 다른 영역 | — | — | 적용 제외 | +| 21 | Guardrail 성숙도 | 적용 — 계약 설치 검증 | M3 / M3 | E2 | 부분 충족 — KEYED에 recovery descriptor가 없으면 설치 거부. 그러나 descriptor 내용은 어떤 실행에도 쓰이지 않아 가드가 형식만 지킴(03-01) | +| 22 | 추상화 성숙도 | 적용 — FeatureHttpBinding | — / M2 | E1 | 부분 충족 — 전송·재시도를 잘 숨김. 문제 매핑 타입이 너무 좁음(03-04) | +| 23 | 일관성 | 적용 | — / M1 | E1 | 부분 충족 — KEYED 의미 불일치(03-06) | +| 24 | 네이밍 / 의미 | 적용 | — / M1 | E1 | 부분 충족 — `IDEMPOTENCY_REPLAY`, `reconcileUnknownEffect`가 이름만큼의 동작(재전송·조회)을 하지 않음(03-01) | +| 25 | 조직 확장성 | 구조적 준비만 — 사용자 1인 | — / M2 | E1 | 충족(구조) — 기능은 계약+매퍼만 기여, 전송 정책은 공통 | +| 26 | Ownership | 적용 — 외부 auth owner 책임 | M1 / M1 | E0·E1 | 부분 충족 — owner 계약 문서 있음(`starter-experience.md:52-68`). `notifyUnauthenticated` 뒤 owner가 할 일과 요청 재실행 없음은 설계서에만 있음. runbook 오래됨(03-08) | +| 27 | 삭제 가능성 | 부분 적용 — V2·RPC·텔레메트리는 선택 | — / 미확인 | E1 | 미검증 — V2는 기본 조합에서 호출처가 없음. 제거 실험은 하지 않음 | +| 28 | 회복 가능성 | 적용 — 결과 불명 쓰기의 조정 | M2 / M1 | E1 | 미충족 — 조정 수단이 사용자 추측뿐이고 재전송이 새 키(03-01) | + +## 6. 미검증 목록 + +- **백엔드 멱등 계약:** 같은 키·다른 입력 거절, 키 보관 기간, 진행 중 같은 키의 409 여부. 03-01의 실제 피해 범위를 정한다. 백엔드 계약 문서나 통합 환경이 필요하다. +- **외부 auth owner 동작:** `notifyUnauthenticated` 뒤 갱신·상태 알림 순서, `readSubject` 구현 여부. 실제 owner 구현이나 계약 테스트가 필요하다. +- **여러 탭:** 한 탭 로그아웃이 다른 탭의 세대를 바꾸는지, 두 탭에서 같은 생성을 보낼 때 키가 다른 문제. 외부 owner와 cross-context 영역(02)과 함께 봐야 한다. +- **게이트웨이 리다이렉트형 세션 만료:** 쿠키 profile(`SAME_ORIGIN_COOKIE`)에서 게이트웨이가 302로 로그인 페이지를 돌려주면 `redirect:"error"` 때문에 네트워크 실패로 분류되고 SAFE 조회는 재시도된다. 기본 profile은 bearer라 해당 없지만, 쿠키 profile을 쓰는 다운스트림에서 "재로그인" 안내가 나오는지 확인이 필요하다. +- **Browser RPC 실제 provider:** 스트림 정리·재시도는 단위 테스트로만 확인했다. 생성된 Connect/gRPC-Web 클라이언트와의 통합이 필요하다. +- **실제 브라우저에서 앱 전체 흐름:** 로그아웃 중 응답 도착, 세션 만료 저장, 결과 불명 화면을 E2E로 확인하지 않았다(E2E 영역 담당). diff --git a/docs/reviews/2026-09-25-maturity-review/04-adapters-realtime.md b/docs/reviews/2026-09-25-maturity-review/04-adapters-realtime.md new file mode 100644 index 00000000..0d6791af --- /dev/null +++ b/docs/reviews/2026-09-25-maturity-review/04-adapters-realtime.md @@ -0,0 +1,281 @@ +# 04 realtime 어댑터 성숙도 리뷰 + +> 검토일: 2026-09-25 · 기준: `main` / `4626b73` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 범위: `src/adapters/realtime/` 16개 파일 9,577줄(SSE·WebSocket·polling·reconnect·stream coordinator·codec). 이 영역을 검증하는 `tests/unit/realtime/` 16개 파일 9,283줄. 계약(`src/contracts/realtime-streams.ts`, `realtime-events.ts`)과 설계 문서는 판정에 필요한 부분만 참조했다. +> 영역 판정(35.8): **조건부 사용 가능** — codec·stream coordinator·SSE 파서·polling·handoff는 building block으로 쓸 수 있다. reconnect coordinator를 단일 재연결 소유자로 두는 실시간 연결의 운영 도입은 04-01을 고치기 전에는 보류한다. 이 runtime은 production에 조합되지 않은 상태(`AVAILABLE_NOT_COMPOSED`)다. + +## 1. 결론 + +- 신뢰할 수 없는 입력 검증, 모든 큐·버퍼·빈도의 상한, 순서·중복·gap 처리, 늦은 콜백 fence는 단단하다. 직전 리뷰 6.4의 1~11번은 현재 코드에서 고쳐진 것을 확인했다. 예외는 6.4-7이다. 재시도 예산 초기화가 일부 경로에만 들어갔다. +- **막아야 할 것 (04-01, High):** 오래 열린 연결은 첫 끊김 뒤 재연결하지 않는다. 실험에서 10분 정상 연결 뒤 1초 offline이 생기면 run이 `OFFLINE retryable:true`로 끝났고 재시도는 0회였다. 이벤트 없이 heartbeat만 오가던 WS가 6분 뒤 서버 재시작(1012)을 받아도 같았다. 원인은 elapsed 예산이 run 시작 시각에 고정된 것이다. 이 예산을 초기화하는 경로가 offline·throw 경로에는 없다. +- **고칠 것 (04-02, 04-03, Medium):** SSE 429/503의 Retry-After는 실패 결과에 실리지 않는다. 저장소의 SSE↔reconnect 배선처럼 결과를 그대로 넘기면, 서버가 30초 기다리라고 해도 0.5초·1초 뒤 재시도한다. 등록되지 않은 이벤트 타입이 오면 연결은 `MALFORMED_EVENT`로 끝난다. 그런데 stream coordinator의 freshness는 `CURRENT`로 남는다. 설계 13.1 위반이다. 오래 열린 탭에 "구버전 클라이언트"라는 신호도 가지 않는다. +- **테스트:** 209건이 통과했다. 변이 8건 중 6건을 잡았다. SSE idle timeout(heartbeat 감시)에는 테스트가 없다(04-06). 04-01~04-03의 시나리오도 테스트가 없다. +- **미검증:** 실제 SSE/WS 서버와 실제 브라우저는 확인하지 못했다. 청크 크기, hidden 탭 타이머, bfcache가 여기 해당한다. 부하 상태의 재연결 분포와 realtime 제거 게이트(`test:realtime-removal`)도 미검증이다. + +## 2. 범위와 방법 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 | `src/adapters/realtime/` 16개 파일 전체를 읽었다. 연결 지점도 필요한 만큼 읽었다: `src/contracts/realtime-streams.ts`(레지스트리·상한), `src/application/ports/realtime/event-authority.ts`(observation 타입), `src/application/policies/bounded-polling.ts`(상한), `scripts/lib/realtime-boundaries.ts` | +| 설계 문서 | `docs/architecture/realtime-events-web-push-and-bounded-polling.md` 0·4·5·6·7·12·13·14·16·19·20절, `decisions/VD-28-…md` 재연결 부분, `optional-adapter-recipes.md` Realtime 절. 주장으로만 읽었다 | +| 실행한 테스트 | `node scripts/run-vitest.ts run tests/unit/realtime/`: 14 files, **209 passed** | +| 스크래치 실험 | `scratchpad/04/`의 `exp-blip.ts`, `exp-reconnect.ts`, `exp-ws-quiet.ts`, `exp-429.ts`, `exp-unknown.ts`, `bench-parser.ts`. Node 24 type stripping으로 `src`를 직접 import하고 가짜 clock·fetch·socket을 썼다 | +| 변이 실험 | 분리 worktree에서 8건을 넣고 해당 테스트 파일만 돌렸다. **6건 검출.** M1 예산 초기화 제거, M2 jitter 제거, M3 effect 뒤 scope fence 제거, M4 1013→RESTART, M5 gap 검사 제거, M6 WS inbound 큐 상한 제거. **2건 생존.** M7 SSE `IDLE_TIMEOUT`을 retryable:false로 바꾼 것(→ 04-06). M8 accept 시점 scope 검사 제거(processEvent가 다시 검사하므로 의미 있는 공백 아님). worktree는 지웠다 | +| 가드레일 | worktree에서 `check-realtime-boundaries.ts`(artifact는 scratchpad): PASS. `check-realtime-boundary-fixtures.ts`: PASS(forbidden 규칙 3건 거절) | +| 확인하지 못한 범위 | `test:realtime-removal`. fixture 복사본에서 타입체크·lint·`test:all`·build를 모두 돌리는 스크립트라, 13개 에이전트가 동시에 도는 중에는 생략했다. 실제 스트리밍 서버와 브라우저도 확인하지 못했다(설계 20절의 해당 항목도 미체크). `check:architecture`·`check:types`는 오케스트레이터가 돌린다. `src/adapters/web-push`는 이 영역 밖이다 | + +### 직전 리뷰 6.4 재확인 (현재 코드 기준) + +| 직전 ID | 현재 상태 | 근거 | +|---|---|---| +| 6.4-1 DRAINING 중 recovery | 고쳐짐 | `stream-coordinator.ts:695-700` | +| 6.4-2 hint 없는 retryable 실패도 재연결 | 고쳐짐 | `reconnect-coordinator.ts:1523-1534`, 통합 테스트 `realtime-reconnect-coordinator.test.ts:1566-1691` | +| 6.4-3 barrier NONE recovery 종료 | 고쳐짐 | `event-consumer.ts:181-188` | +| 6.4-4 SSE 파서 성능 | 고쳐짐 | 250KB chunk 중앙값 2.4~3.4ms(Node 24, `bench-parser.ts`). 브라우저는 미측정 | +| 6.4-5 chunk당 item 상한 | 고쳐짐 | `sse/fetch-sse-connection.ts:418-431` drain. 바이트 상한은 남음 → 04-05 | +| 6.4-6 dedupe | 고쳐짐 | `stream-coordinator.ts:603-613`, `:1070-1082`, `event-codec.ts:369-387` | +| 6.4-7 재시도 예산 초기화 | **일부만** | 분류 경로 `reconnect-coordinator.ts:905-916`, `:935-945`에만 적용됨 → 04-01 | +| 6.4-8 복사본 통합 | 고쳐짐 | `result.ts:97-135`, `:238-294` 한 벌. polling도 같은 헬퍼 사용 | +| 6.4-9 `endAttempt`, `_recovery` | 고쳐짐 | `reconnect-coordinator.ts:596-607`. `_recovery`는 남아 있지 않음. `run()`은 여전히 약 665줄(`:306-971`) | +| 6.4-10 probe 버퍼 상한 | 고쳐짐 | `live-poll-handoff-coordinator.ts:258-289` | +| 6.4-11 사소 항목 | 고쳐짐 | poll throw → OFFLINE retryable(`polling/bounded-poll-coordinator.ts:288-293`, `:354-359`) 등 | + +### 32절 시나리오를 realtime 구독 관점에서 따라간 결과 + +**화면 이동·언마운트** + +```text +unmount → 조합 코드가 signal.abort() 또는 close() 호출 + → reconnect: stop → phase abort → session.close → finally에서 listener 해제 (reconnect-coordinator.ts:361-368, :954-970) + → WS: terminate → listener 4종 해제, heartbeat·unsubscribe 타이머 abort, 큐 비움 (websocket/websocket-connection.ts:1326-1390) + → SSE: controller abort + reader cancel(2초 상한) (sse/fetch-sse-connection.ts:455-466, :591-602) + → poll: stop(ABORTED) → 대기 abort, visibility/online 구독 해제 (polling/bounded-poll-coordinator.ts:160-186, :490-500) + → stream coordinator.close(): fence + 남은 작업 drain(5초) (stream-coordinator.ts:1003-1025) +``` + +각 조각은 스스로 정리된다. 늦게 끝나는 작업은 `DRAINING`으로 추적한 뒤 닫는다. + +남는 것은 두 가지다. + +- 논리 구독 refcount가 런타임에 없다. refcount는 "마지막 consumer가 사라지면 unsubscribe"하는 장치다. 이 부분은 조합 코드 몫이다(04-04). +- `close()`는 terminal이다. React StrictMode의 mount→cleanup→mount에서는 마운트마다 새 인스턴스를 만들어야 한다. + +**로그아웃 중 응답 도착** + +```text +scope.isCurrent() = false + → 이벤트 도착: accept/processEvent에서 fence → SCOPE_FENCED drop, effect 0 (stream-coordinator.ts:302-305, :400-403) + → 진행 중 effect: isCurrent 컨텍스트로 commit 거부, 끝난 뒤 재확인 (:504-511, :570-573) — 변이 M3 검출 + → 진행 중 snapshot recovery: 완료 뒤 scope 확인 → fence (:763-766) + → poll 응답: attempt 뒤 isCurrent 확인, onValue에 isCurrent 전달 (polling/bounded-poll-coordinator.ts:315-328, :408-413) + → 연결 자체: 다음 경계(이벤트 또는 close)까지 열린 채 유지 (EXP2) → 04-04 +``` + +이전 사용자의 응답이 다음 세션 상태에 들어가지 않는 것은 확인했다. 연결을 닫는 일은 조합 코드가 `close()`를 불러야 일어난다. + +## 3. 확인된 강점 + +1. **신뢰할 수 없는 프레임을 정해진 순서로 처리한다.** 순서는 바이트 상한 → JSON 중복 키 검사 → `JSON.parse` → 정확한 키 집합 → registry의 stream/type 조회 → payload 스키마 → mapper → freeze다. 근거는 `event-codec.ts:101-201`이다. WS 제어 프레임도 같은 방식이다(`websocket/websocket-protocol.ts:172-200`). 테스트는 `event-codec.test.ts`, `websocket-protocol.test.ts`다. +2. **자원 상한이 모든 곳에 있고, 호출자가 올릴 수 없다.** 이벤트는 64KB, 큐는 256건/4MB, dedupe는 2,048건/4MB/10분이다(`src/contracts/realtime-streams.ts:29-38`). WS 한도는 서버가 광고해도 줄이기만 한다(`websocket/websocket-connection.ts:198-214`, `:1620-1653`, `:1655-1693`). SSE 파서는 `sse/sse-parser.ts:7-14`, 재연결은 `reconnect-policy.ts:3-10`, polling은 `bounded-polling.ts:1-5`에 상한이 있다. 장시간 연결에서 메모리가 무한히 늘어나는 경로는 찾지 못했다. +3. **순서·중복·gap·epoch를 처리한다.** 같은 ID에 다른 내용이 오면 conflict로 복구한다. sequence가 건너뛰면 gap으로 snapshot 복구한다. 과거 sequence는 drop한다. 근거는 `stream-coordinator.ts:419-477`이다. cursor는 effect 성공 뒤에만 전진한다(`:588-595`). WS 재구독 때는 `nextExpectedSequence`와 cursor를 대조한다(`websocket/websocket-connection.ts:821-858`). 변이 M5가 검출됐다. +4. **늦은 콜백 fence가 있다.** scope와 generation을 accept·effect 전후·recovery 전후·poll 전후에 확인한다(32절 추적 참조). effect에는 `isCurrent`를 넘겨 commit 직전 확인을 강제한다. 변이 M3이 검출됐다. +5. **재연결 폭주를 억제한다.** full jitter를 쓴다. server not-before hint는 낮춰 잘라 내지 않고 넘으면 종료한다(`reconnect-policy.ts:73-114`). 시도 10회·5분·최대 60초가 상한이다. 힌트 없는 WS `OVERLOADED`(1013)는 종료한다(`websocket/websocket-connection.ts:1814-1819`). 예산 초기화에는 "유효 신호 + 안정 유지" 두 조건이 모두 필요하다(`reconnect-policy.ts:137-149`). 변이 M1·M2·M4가 검출됐다. +6. **인증과 엔드포인트를 좁게 둔다.** 엔드포인트는 고정 same-origin HTTPS/WSS다. URL에 query·credential이 없다(`sse/fetch-sse-connection.ts:471-491`, `websocket/websocket-connection.ts:1584-1614`). 401/403은 재시도 없이 종료하므로 인증 재시도 폭주가 없다(`sse/fetch-sse-connection.ts:545-550`). native `WebSocket`/`EventSource`는 이 폴더 밖에서 금지되고, 가드레일이 PASS했다. + +## 4. 발견 사항 (36.3) + +### 04-01 오래 열린 연결은 첫 끊김(offline 깜빡임, 조용한 WS의 서버 재시작) 뒤 재연결하지 않고 끝난다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 6, 12, 18, 28, 10, 5 | +| 근거 | 원인은 두 가지다. ① 재시도 elapsed 예산의 시작점 `budgetStartedAt`이 run 시작 시각이다(`reconnect-coordinator.ts:347`). 이 값을 초기화하는 곳은 서버 close를 분류하는 두 경로(`:905-916`, `:935-945`)뿐이다. offline으로 끊긴 경로(`:824-862`)와 `waitClosed`가 throw한 경로(`:863-870`)는 초기화 없이 `offlineRetry`/`providerRetry`만 만든다. 그러면 다음 루프의 `canRetry`가 남은 예산을 0으로 본다. online을 기다리지도 않고 `retry.terminalResult`를 반환한다(`:482-495`). offline 대기 시간도 같은 예산에서 빠진다(`:496-513`). ② 초기화 조건인 `markValidHeartbeatOrEvent`(`:620-622`)를 WS에서는 이벤트가 올 때만 부를 수 있다. HEARTBEAT_ACK는 연결 안에서 소비되고(`websocket/websocket-connection.ts:360-376`) 관측 종류에도 없다(`:70-79`). 실험 조건: base 1s, max elapsed 5분, stable 30s. 결과는 셋이다. (a) 10분 정상 연결 뒤 1초 offline → `{kind:"OFFLINE",retryable:true}`로 종료, 재시도 0회(`exp-blip.ts`). 같은 조건에서 서버 close를 받은 경우는 재연결했다. (b) 시작 직후 6분 offline → online 복귀 시 시도 0회로 종료(`exp-reconnect.ts`). (c) 이벤트 없이 heartbeat ACK만 정상인 WS가 6분 뒤 1012를 받음 → `PROVIDER_UNAVAILABLE retryable:true`로 종료, 소켓 1개(`exp-ws-quiet.ts`) | +| 발생 조건 | 연결이 `maxElapsedMs`(상한 5분)보다 오래 유지된 뒤 끊길 때다. 네트워크가 잠깐 끊기는 경우(Wi-Fi 전환, 노트북 절전 복귀)와, 이벤트가 드문 WS 구독에서 서버가 재시작하는 경우다. 실사용 세션 대부분이 해당한다 | +| 영향 | realtime이 조용히 멈추고 화면은 오래된 데이터를 보여 준다. 결과가 `retryable:true`라 조합 코드가 다시 run할 수는 있다. 하지만 예산 소진(멈춰야 함)과 이 경우(재연결해야 함)의 결과 모양이 같아 구분할 수 없다. 다시 run하는 바깥 루프를 만들면 설계가 금지한 두 번째 재시도 루프가 된다. reference runtime이라 이 recipe를 채택하는 다운스트림에 그대로 복제된다 | +| 심각도·우선순위 | High · P1. 설계 5.4가 지원한다고 적은 장애(offline→online, 서버 재시작)에서 핵심 기능이 멈춘다. production에 조합되기 전이라 P0는 아니다. realtime 도입 전에 풀어야 할 차단 항목이다 | +| 통제·증거 | M2(분류 경로에만 구현) · E2(스크래치 실험) | +| 확실성과 남은 가정 | 코드 경로와 실험으로 확인했다. 조합 코드가 WS `CONNECTED` 관측 시점에 markValid를 부르면 (c)는 피할 수 있다. 그런 안내는 코드와 문서에 없다 | +| 최소 개선 방향 | (1) 세션이 열린 뒤 끝나는 모든 경로(offline·throw 포함)에서 `isReconnectAttemptResetEligible`를 적용한다. 한 헬퍼로 모으면 된다. (2) elapsed 예산은 연속 실패가 시작된 시각부터 잰다. offline 대기 중에는 멈춘다. online 복귀 시 `budgetStartedAt = now`로 두고 시도 횟수 상한은 유지한다. (3) WS에 heartbeat ACK 관측을 추가한다. 예: `observe({kind:"HEARTBEAT_ACK"})` | +| 비용·부작용 | 수십 줄이다. `maxAttempts`는 그대로라 무한 재시도는 생기지 않는다 | +| 완료 기준 | (a)(b)(c) 모두 재연결 시도가 1회 이상 일어난다. 예산을 실제로 소진했을 때만 terminal이 된다 | +| 검증 방법 | `realtime-reconnect-coordinator.test.ts`에 (a)(b)(c)를 ManualClock으로 추가한다. 현재 offline 테스트(`:400-435`)는 시작 시 짧은 offline만 본다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 6.4-7(Q-6.4-7)의 수정이 분류 경로에만 들어감. 이번에 새로 찾은 경로 | + +### 04-02 SSE 429/503의 Retry-After가 실패 결과에 실리지 않아, 기본 배선에서는 서버가 요구한 시각보다 먼저 재연결한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 6, 5, 22, 23, 10 | +| 근거 | `sse/fetch-sse-connection.ts:554-575`는 Retry-After가 유효하면 `onRetryHint` 콜백(`:73`)으로만 알린다. 반환하는 실패에는 `retryable:true`만 남는다. reconnect coordinator는 hint를 attempt 결과의 `serverNotBeforeMs`로만 받는다(`reconnect-coordinator.ts:44-51`, `:725-731`). 저장소의 유일한 SSE↔reconnect 배선(`realtime-reconnect-coordinator.test.ts:1643-1690`)도 `read` 결과를 그대로 넘긴다. 실험(`exp-429.ts`, 429 + `Retry-After: 30` 두 번): 이 배선에서는 재연결 대기가 **500ms, 1000ms**였다. `onRetryHint`로 받아 결과에 넣으면 30000ms, 30000ms였다. polling은 같은 정보를 실패 값 안에 싣는다(`polling/bounded-poll-coordinator.ts:28-30`) | +| 발생 조건 | 서버나 게이트웨이가 과부하·점검·rate limit 때문에 SSE 연결에 429/503 + Retry-After를 줄 때 | +| 영향 | 모든 탭이 서버가 정한 시각보다 먼저 재연결한다. 첫 시도는 [0, base) 안에 몰린다. 시도 상한(10회·5분)이 있어 무한 폭주는 아니다. 하지만 과부하를 풀려는 서버 신호를 무시해 회복을 늦춘다. 설계 5.3의 "server not-before보다 먼저 재시도하지 않는다"를 기본 배선이 어긴다 | +| 심각도·우선순위 | Medium · P2. 증폭 폭이 시도 상한으로 제한된다. 04-01과 같은 경로를 고칠 때 같이 고치면 싸다 | +| 통제·증거 | M1(설계 문서만) · E2(스크래치 실험) | +| 확실성과 남은 가정 | 콜백을 직접 이어 붙이는 조합 코드는 영향이 없다. 그런 배선 예시는 저장소 어디에도 없다 | +| 최소 개선 방향 | SSE 실패 결과에 `retryAfterMs`를 싣는다. SSE 모듈에서 reconnect 결과로 옮기는 작은 bridge 함수를 export한다. EOF의 `retryHintMs`(`:405-411`)와 같은 통로로 합친다 | +| 비용·부작용 | 공개 타입에 선택 필드를 추가한다. 기존 소비자와 호환된다 | +| 완료 기준 | 429/503 + Retry-After가 bridge를 거치면 재연결 대기가 hint 이상이다. hint가 상한을 넘으면 지금처럼 종료한다 | +| 검증 방법 | 통합 테스트 `:1643` 옆에 429 + Retry-After 케이스를 추가하고 `clock.sleepCalls`로 대기를 확인한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 04-03 등록되지 않은 이벤트 타입이 오면 연결은 MALFORMED_EVENT로 끝나고, stream freshness는 CURRENT로 남는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(설계 13.1 계약 위반). 오래 열린 탭에 대해서는 구조적 위험 | +| 관련 관점 | 17, 18, 8, 10 | +| 근거 | codec은 registry에 없는 `eventType`을 `MALFORMED_EVENT`로 거절한다(`event-codec.ts:145-151`). 스키마 오류와 같은 코드다. consumer는 이 실패를 stream coordinator에 알리지 않고 그대로 반환한다(`event-consumer.ts:85-88`). SSE는 읽기를 끝낸다(`sse/fetch-sse-connection.ts:350-352`). WS는 PROTOCOL_MISMATCH로 닫는다(`websocket/websocket-connection.ts:1038-1039`, `:1574-1578`). 둘 다 retryable:false다. 실험(`exp-unknown.ts`): 이벤트 1·2를 적용한 뒤 새 타입의 이벤트 3을 보냈다. SSE는 `MALFORMED_EVENT retryable:false`로 끝났고, coordinator `inspect()`는 `freshness:"CURRENT"`였다. 설계 13.1(`realtime-events-web-push-and-bounded-polling.md:1829`, `:1850-1851`)은 MALFORMED_EVENT에서 freshness를 `UNKNOWN`으로 두라고 적는다. unknown type을 버린 뒤 CURRENT를 유지하지 말라고도 적는다. 테스트는 현재 동작을 고정한다(`event-codec.test.ts:70-77`) | +| 발생 조건 | 백엔드가 기존 stream에 이벤트 타입을 추가해 배포했는데 이전 프론트 번들을 쓰는 탭이 열려 있을 때. 보통 "추가만 한 호환 변경"으로 취급하는 배포다 | +| 영향 | 오래 열린 탭의 realtime이 재시도 없이 멈춘다. freshness 축만 보는 화면은 CURRENT를 표시한다. 실패 코드가 데이터 손상과 같다. 그래서 조합 코드는 "새로고침하면 해결되는 구버전"과 "서버 버그"를 구분하지 못한다. 설계 5.5가 요구하는 N/N-1 또는 reload 정책을 걸 신호도 없다 | +| 심각도·우선순위 | Medium · P2. 연결 상태 축을 함께 쓰는 조합(설계 5.1)이라면 화면이 STALE로 보일 수 있어 피해가 줄어든다. 샘플 패턴으로 복제되는 범위다 | +| 통제·증거 | fail-closed는 M2. freshness 계약은 구현이 없다(M0) · E2 | +| 확실성과 남은 가정 | 코드와 실험으로 확인했다. 조합 코드가 transport 종료를 freshness에 반영할지는, 조합 코드가 없어 미확인이다 | +| 최소 개선 방향 | (1) 등록되지 않은 이벤트 타입을 별도 사유로 구분한다. 관측 reason이나 failure kind를 추가하는 방식이다. (2) decode 실패를 해당 stream의 freshness `UNKNOWN`으로 반영하는 경로를 둔다. (3) "추가된 이벤트 타입" 호환 규칙을 설계에 한 줄로 고정한다. 예: reload 유도, 또는 non-state-bearing이면 무시 | +| 비용·부작용 | failure vocabulary를 추가하면 ports 계약이 바뀐다 | +| 완료 기준 | 새 타입 이벤트를 받은 뒤 `inspect().freshness`가 CURRENT가 아니다. 조합 코드가 받은 실패만으로 "구버전 클라이언트"를 판별할 수 있다 | +| 검증 방법 | `event-consumer.test.ts`의 SSE+consumer+coordinator 통합 묶음에 등록되지 않은 타입 케이스를 추가한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 04-04 hidden 탭 닫기·로그아웃 시 닫기·kill switch를 강제하는 코드가 없고, `isCurrent`는 루프 경계에서만 확인한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 12, 15, 5, 14, 20 | +| 근거 | registry는 `hiddenPolicy`·`killSwitchId`·`fallback`을 필수 필드로 검증한다(`src/contracts/realtime-streams.ts:85`, `:357`). 그런데 `src/` 어디에서도 읽지 않는다(grep). reconnect coordinator가 받는 환경 신호는 online뿐이다(`reconnect-coordinator.ts:103-106`). SSE 연결에는 visibility 입력이 없다. `isCurrent`는 루프 경계에서만 호출된다(`:349-355`). 실험(`exp-reconnect.ts` EXP2): 열린 세션에서 `isCurrent`를 false로 바꾸고 10분을 보냈다. run은 RUNNING 그대로였고 `session.close`는 0회였다. `close()`를 불러야 닫혔다. 설계 5.5의 `maxConnectionAge`(`…md:851-854`)는 registry에 필드가 없다. polling만 visibility를 직접 듣는다(`polling/bounded-poll-coordinator.ts:172-186`) | +| 발생 조건 | 다운스트림이 설계 5.4~5.6에 적힌 "기본 동작"을 런타임이 해 준다고 믿고 조합할 때 | +| 영향 | hidden 탭도 연결을 유지해 탭 수만큼 연결이 생긴다. HTTP/1.1이면 fetch-SSE 6개로 같은 origin의 다른 요청이 막힐 수 있다. 설계 6.4가 HTTP/2를 hosting 증거로 요구하는 이유다. 로그아웃 뒤에도 조용한 stream의 연결은 서버가 끊거나 다음 이벤트가 올 때까지 남는다. 이벤트 적용은 fence로 막히므로 화면 데이터가 섞이지는 않는다(변이 M3 검출) | +| 심각도·우선순위 | Low · P3. `optional-adapter-recipes.md:141-144`가 visibility·logout 처리를 채택자의 필수 검증으로 적어 두었다. 다만 필수 registry 필드가 런타임 강제처럼 읽힌다 | +| 통제·증거 | M1 · E2 | +| 확실성과 남은 가정 | 조합 코드가 없어 실제 피해는 조합 방식에 달렸다 | +| 최소 개선 방향 | 세 곳에 적는다. registry 필드 주석과 설계 5.4~5.6에는 "reference runtime은 강제하지 않는다, 조합 코드 책임"을 적는다. `isCurrent` 타입 주석에는 "경계에서만 확인한다, 로그아웃 시 `close()`가 필요하다"를 적는다. 필요하면 reconnect 환경에 scope·visibility 구독을 추가한다 | +| 비용·부작용 | 문서만 고치면 몇 줄이다 | +| 완료 기준 | 채택자가 코드 옆 주석만 보고 닫기 책임이 자기에게 있다는 것을 안다 | +| 검증 방법 | 문서 리뷰. 구독을 추가한다면 "scope 변경 → session.close" 테스트 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 04-05 SSE reader가 256KB를 넘는 chunk를 한 번에 주면, 이벤트 크기와 상관없이 EVENT_TOO_LARGE로 끝난다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 14, 6 | +| 근거 | 파서는 chunk가 `maxChunkBytes`(256KB, `sse/sse-parser.ts:11`)를 넘으면 실패한다(`:99`). 연결은 reader chunk를 자르지 않고 그대로 넣는다(`sse/fetch-sse-connection.ts:418-431`). 결과는 retryable:false다. 파서에는 이미 한 입력을 나눠 처리하는 `drain()`(`sse-parser.ts:54-59`, `:106`)이 있다 | +| 발생 조건 | 브라우저가 쌓인 바이트를 큰 chunk로 넘길 때다. 메인 스레드가 오래 막힌 뒤나 재연결 직후 replay가 몰릴 때 생길 수 있다. chunk 크기는 서버의 이벤트 크기가 아니라 브라우저와 네트워크가 정한다. 실제 크기는 측정하지 못했다 | +| 영향 | 정상 크기의 이벤트만 받는데도 realtime이 멈춘다 | +| 심각도·우선순위 | Low · P3. 발생 빈도를 모른다. 수정은 몇 줄이다 | +| 통제·증거 | M0(chunk 분할 없음) · E1 | +| 확실성과 남은 가정 | 브라우저별 fetch body chunk 상한은 미확인 | +| 최소 개선 방향 | `fetch-sse-connection.ts`에서 chunk를 `maxChunkBytes` 단위로 `subarray`해 push/drain한다 | +| 비용·부작용 | 없음 | +| 완료 기준 | 1MB 단일 chunk에 정상 이벤트가 여러 개 들어 있어도 전부 전달된다 | +| 검증 방법 | `fetch-sse-connection.test.ts`에 1MB 단일 chunk 케이스를 추가한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 6.4-5 관련. item 상한은 고쳐졌고 바이트 상한 문제가 남음 | + +### 04-06 SSE idle timeout(heartbeat 감시)에 테스트가 없다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(테스트 공백) | +| 관련 관점 | 10, 6 | +| 근거 | `sse/fetch-sse-connection.ts:386-390`의 `IDLE_TIMEOUT` 경로를 검사하는 테스트가 없다. `tests/unit/realtime/`에서 `IDLE_TIMEOUT`을 찾으면 reconnect 테스트의 가짜 결과 한 곳만 나온다. 변이 M7(retryable을 false로 바꿈)은 `fetch-sse-connection.test.ts` 24건을 모두 통과했다. 같은 실험에서 M1~M6은 모두 검출됐다 | +| 발생 조건 | idle 타이머, comment 처리, retryable 값을 바꾸는 변경이 들어올 때 | +| 영향 | SSE에서 반쯤 끊긴 연결(NAT 만료, 절전 복귀)을 감지하는 유일한 장치다. 여기가 회귀하면 SSE가 조용히 멈추거나 재연결하지 않는다 | +| 심각도·우선순위 | Low · P2. 현재 코드는 맞다(E1). 회귀를 막는 장치가 없다는 문제다 | +| 통제·증거 | M2 · E2(변이 실험) | +| 확실성과 남은 가정 | 확인됨 | +| 최소 개선 방향 | ManualClock으로 테스트 2건을 추가한다. 하나는 idle 경과 → `IDLE_TIMEOUT retryable:true`와 reader cancel 확인이다. 다른 하나는 comment가 타이머를 연장하는지 확인이다 | +| 비용·부작용 | 없음 | +| 완료 기준 | M7 변이가 실패한다 | +| 검증 방법 | 변이 재실행 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 04-07 재연결·폴링·SSE 연결에 관측 지점이 없어 설계 14.1의 connect/poll 진단 이벤트를 낼 곳이 없다 + +| 필드 | 내용 | +|---|---| +| 성격 | 개선 제안 | +| 관련 관점 | 7, 8 | +| 근거 | stream coordinator(`stream-coordinator.ts:74`, `:1115`)와 WS(`websocket/websocket-connection.ts:1481`)에는 닫힌 어휘의 `observe`가 있다. reconnect coordinator(`reconnect-coordinator.ts:121-143`), polling(`polling/bounded-poll-coordinator.ts:86-102`), SSE(`sse/fetch-sse-connection.ts:83-94`)에는 없다. 설계 14.1·14.2(`…md:1873-1930`)는 `realtime_connect_attempted`, 재연결 시도·대기·소진 비율, `bounded_poll_*`를 요구한다. 예산 소진과 04-01 종료는 결과 모양도 같다 | +| 발생 조건 | 운영에서 재연결 폭주나 소진을 보려 할 때 | +| 영향 | 클라이언트 쪽에서 재연결 시도·대기·종료 이유를 셀 수 없다. attempt를 감싸면 시도 수는 셀 수 있다. 대기 시간과 "소진인지 terminal인지"는 알 수 없다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M0(해당 지점) · E1 | +| 확실성과 남은 가정 | 확인됨 | +| 최소 개선 방향 | reconnect·poll coordinator에 `observe?` 의존성을 추가한다. 낼 값은 attempt 시작·종료(closed kind), 대기 bucket, 종료 이유(EXHAUSTED/TERMINAL/ABORTED)다 | +| 비용·부작용 | sink 실패가 제어 흐름에 영향을 주지 않게 try/catch한다. stream coordinator와 같은 방식이다 | +| 완료 기준 | 14.1의 connect·poll 이벤트를 조합 코드가 추가 래핑 없이 만들 수 있다 | +| 검증 방법 | 관측 호출 순서를 확인하는 단위 테스트 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 04-08 VD-28과 설계 5.3이 현재 재연결 규칙과 다르다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(문서) | +| 관련 관점 | 9, 5, 24 | +| 근거 | 설계 5.3(`realtime-events-web-push-and-bounded-polling.md:779-782`)과 VD-28(`decisions/VD-28-…md:265-266`)은 "rate/provider 실패는 server hint가 있을 때만 재시도하고, 없으면 terminal"이라고 적는다. 코드는 R-4.2 이후 retryable이면 hint 없이도 재시도한다. hint가 필요한지는 transport가 정한다(`reconnect-coordinator.ts:1523-1534`). 이 코드는 같은 설계 문서의 6.3·7.4 표(502/504, RESTART는 bounded 재시도)와는 맞는다. 또 VD-28:258은 attempt 초기화 조건을 "stable-open **또는** valid signal"로 적는다. 코드와 설계 5.3은 "**둘 다**"다(`reconnect-policy.ts:131-149`) | +| 발생 조건 | 채택자가 결정 문서(VD-28)를 기준으로 조합 코드를 짤 때 | +| 영향 | 조합 코드가 hint 없는 502를 terminal로 바꾸거나, 초기화 조건을 느슨하게 다시 구현할 수 있다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M1(문서 불일치) · E1 | +| 확실성과 남은 가정 | 확인됨 | +| 최소 개선 방향 | 두 문서의 해당 줄을 코드 기준으로 고친다 | +| 비용·부작용 | 없음 | +| 완료 기준 | 5.3, 6.3, 7.4, VD-28이 같은 규칙을 말한다 | +| 검증 방법 | 문서 리뷰 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 6.4-2, 6.4-7 수정 때 문서가 같이 바뀌지 않음 | + +## 5. 28개 관점 판정 (36.2) + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +|---|---|---|---|---|---| +| 1 | 코드 성숙도 | 적용. 상태 전이(stream OPEN/DRAINING/CLOSED, reconnect IDLE/RUNNING/DRAINING/CLOSED)와 입력 불변식 | M3 / M3 | E2 | 충족. 정확한 키 검증과 terminal·idempotent close | +| 2 | 구조적 성숙도 | 적용. ports/contracts와 kernel(`platform/`)만 import | M3 / M3(boundary 검사) | E2 | 충족. `check:architecture`는 오케스트레이터 몫 | +| 3 | 변경 용이성 | 적용. 이벤트 타입을 추가하는 변경 | M2 / M1 | E2 | 부분 충족. 백엔드가 타입을 추가하면 이전 탭이 멈춤(04-03) | +| 4 | 인지 부하 | 적용. 조합 배선 계약(markValid, classifyClosed, hint) | M2 / M1 | E1 | 부분 충족. `run()` 약 665줄(`reconnect-coordinator.ts:306-971`). 배선 규칙이 코드 곳곳에 흩어져 04-01·04-02가 생김 | +| 5 | 위험 가시성 | 적용 | M2 / M1 | E2 | 부분 충족. hint가 콜백으로만 전달됨(04-02). `isCurrent`는 폴링 방식(04-04) | +| 6 | 실패 성숙도 | 적용(중점) | M3 / M2 | E2 | **미충족.** full jitter·상한·hint 하한은 좋다. 장시간 연결 뒤 재연결이 안 됨(04-01). Retry-After가 유실됨(04-02). WS 프로토콜에는 재시도 hint 필드가 없어 `OVERLOADED`는 항상 종료다. 폭주는 막지만 과부하가 끝나도 클라이언트가 스스로 복귀하지 않는다 | +| 7 | 운영 성숙도 | 적용(중점) | M2 / M1 | E1 | 부분 충족. stream과 WS에만 관측이 있음(04-07) | +| 8 | 디버깅 가능성 | 적용 | M2 / M2 | E1 | 부분 충족. 닫힌 failure 어휘가 있고 raw 사유는 노출하지 않는다. unknown type과 손상 데이터를 구분하지 못함(04-03) | +| 9 | 유지보수 성숙도 | 적용 | M2 / M1 | E1 | 부분 충족. 직전 리뷰 수정은 반영됐다. 결정 문서가 코드와 어긋남(04-08) | +| 10 | 테스트 성숙도 | 적용 | M3 / M3(일부) | E2 | 부분 충족. 209건 통과, 변이 6/8 검출. SSE idle 감시가 공백(04-06). 04-01~03 시나리오에 테스트 없음 | +| 11 | 데이터 성숙도 | 적용. cursor와 checkpoint 의미 | M3 / M3 | E2 | 충족. cursor는 effect 뒤에 전진하고 메모리에만 있다. 영속 저장은 없다 | +| 12 | 동시성 성숙도 | 적용(중점). 순서·중복·gap·여러 탭 | M3 / M3 | E2 | 부분 충족. 순서·중복·gap·단일 recovery는 충족. 탭별 연결은 설계상 의도지만 hidden 닫기를 강제하는 코드가 없음(04-04). 장시간 연결 뒤 재연결(04-01) | +| 13 | 확장성 | 적용. 구조 상한만 확인 가능(요청량 목표 없음) | 미정 / M2 | E1 | 미검증. 구독 32개, stream별 큐 상한은 있음. 부하는 측정 안 함 | +| 14 | 성능 성숙도 | 적용(중점) | M3 / M3 | E2 | 부분 충족. 메모리 상한이 모두 있고 파서는 250KB에 약 3ms. chunk가 256KB를 넘으면 종료(04-05) | +| 15 | 보안 성숙도 | 적용(중점) | M3 / M3 | E2 | 충족(영역 범위). 고정 same-origin, URL에 credential 없음, 401/403 즉시 종료, 로그아웃 뒤 적용 fence. 잔여: 로그아웃 시 연결 닫기는 조합 코드 책임(04-04) | +| 16 | 의존성 성숙도 | 적용 | M2 / M2 | E1 | 충족. 외부 패키지 없음. native API는 facade로 주입 | +| 17 | API/Contract 성숙도 | 적용(중점) | M3 / M2 | E2 | 부분 충족. envelope 정확 키, protocol literal, 레지스트리 스키마. unknown type 처리가 설계와 다름(04-03) | +| 18 | 배포 성숙도 | 적용(중점). 새 배포 뒤 오래 열린 탭 | M2 / M1 | E2 | 부분 충족. 서버 재시작 재연결은 R-4.2로 해결. 이벤트 타입 추가(04-03)와 조용한 WS(04-01)는 남음. N/N-1 정책 없음 | +| 19 | 설정 성숙도 | 적용 | M3 / M3 | E2 | 충족. 정책은 생성 시 검증하고, 상한은 낮추기만 허용 | +| 20 | 개발자 경험 | 적용 | M2 / M1 | E1 | 부분 충족. 조합 예시가 테스트 안에만 있다. 채택자가 배선을 직접 추론해야 함(04-02, 04-04) | +| 21 | Guardrail 성숙도 | 적용 | M3 / M3 | E2 | 충족. realtime-boundaries 검사와 fixture PASS. native API와 미선택 composition을 차단 | +| 22 | 추상화 성숙도 | 적용 | M2 / M2 | E1 | 부분 충족. session·attempt 추상화는 transport를 잘 숨긴다. hint 통로가 transport마다 다름(04-02) | +| 23 | 일관성 | 적용 | M2 / M2 | E1 | 부분 충족. abort·snapshot 헬퍼는 한 벌로 합쳐짐. retry hint는 polling이 in-band, SSE가 콜백 | +| 24 | 네이밍/의미 | 적용 | M2 / M2 | E1 | 부분 충족. `markValidHeartbeatOrEvent`에 넘길 WS heartbeat 신호가 없음(04-01). unknown type을 `MALFORMED_EVENT`로 부름(04-03) | +| 25 | 조직 확장성 | 적용 제외. 작성자 1인, 구조적 준비만 평가 | — | E1 | 적용 제외. registry에 `owner` 필드가 필수로 있음 | +| 26 | Ownership | 적용 제외. 제품 조합(RT-05)이 선택되지 않음 | — | E0 | 적용 제외. recipe `owner: project-owner-required` | +| 27 | 삭제 가능성 | 적용 | M3 / 미확인 | E0 | 미검증. `test:realtime-removal` 게이트는 있으나 이번에 돌리지 않음 | +| 28 | 회복 가능성 | 적용. snapshot 복구와 재연결 | M3 / M2 | E2 | 부분 충족. gap·cursor 만료 → snapshot 복구는 충족. 끊김 뒤 스스로 복구하지 못하는 경로가 있음(04-01) | + +## 6. 미검증 목록 + +| 항목 | 판단하지 못한 이유 | 확인하려면 | +|---|---|---| +| 실제 브라우저의 fetch body chunk 크기(04-05), hidden 탭 타이머 throttling, bfcache 복귀, freeze | 브라우저 실행 없음 | Playwright에서 로컬 SSE 서버로 대량 replay·hidden·bfcache 시나리오 실행 | +| 실제 SSE/WS 서버와의 연결, 프록시 idle 종료, HTTP/1.1 연결 수 한계 | 로컬 스트리밍 서버 없음(설계 20절 미체크) | 로컬 서버와 nginx/ALB 설정으로 E3 실험 | +| 여러 클라이언트 재연결 분포(서버 재시작 직후 폭주 크기) | 부하 실험 없음. jitter 공식은 단위 테스트와 코드로만 확인 | N개 클라이언트 시뮬레이션으로 초당 재연결 수 측정 | +| realtime 제거 게이트(`test:realtime-removal`) | 전체 타입체크·lint·test·build를 fixture에서 돌려 비용이 커서 생략 | CI 또는 단독 실행 | +| 조합 코드가 transport 종료를 freshness에 반영하는지(04-03), 로그아웃 시 `close()`를 부르는지(04-04) | production 조합과 예시가 없음 | RT-05 조합 코드가 생기면 재검토 | +| SSE 파서 성능의 브라우저 수치 | Node 24 벤치만 실행 | 실제 브라우저 performance 측정 | diff --git a/docs/reviews/2026-09-25-maturity-review/05-adapters-storage-kernel.md b/docs/reviews/2026-09-25-maturity-review/05-adapters-storage-kernel.md new file mode 100644 index 00000000..5a2db6f9 --- /dev/null +++ b/docs/reviews/2026-09-25-maturity-review/05-adapters-storage-kernel.md @@ -0,0 +1,383 @@ +# 브라우저 저장소와 adapter kernel 성숙도 리뷰 + +> 검토일: 2026-09-25 · 기준: `main` / `4626b73` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 범위: `src/adapters/storage/`(Web Storage, `indexeddb/`, `opfs/`), `src/adapters/platform/`(adapter kernel), `src/adapters/browser-file-storage/` — 약 14.9k줄. 이 영역을 검증하는 테스트(`tests/unit/indexeddb-*.test.ts`, `opfs-*.test.ts`, `abortable-operation.test.ts`, `storage-*.test.ts`, `browser-storage-policy.test.ts`, `tests/helpers/memory-indexeddb.ts`, `tests/browser-capabilities/indexeddb-runtime.spec.ts`·`opfs-runtime.spec.ts`)와 `docs/operations/*recovery*.md` 중 이 영역 부분. +> 영역 판정(35.8): **조건부 사용 가능** — adapter kernel과 Web Storage 어댑터는 지정 범위에서 사용 가능. IndexedDB 런타임은 "사용자 데이터 삭제 보장"을 요구하지 않는 dataset에 한해 사용 가능(05-03, 05-05 전제). OPFS 런타임은 05-01·05-02를 고치기 전에는 제품에 조합하지 않는다. + +전제: IndexedDB·OPFS 런타임은 `AVAILABLE_NOT_COMPOSED`다. repo의 bootstrap은 이 두 런타임을 조합하지 않는다(`src/bootstrap/runtime-adapters.ts`는 Web Storage와 kernel만 import). 따라서 아래 결함은 현재 배포 앱에서 발생하지 않고, **다운스트림이 이 reference runtime을 조합할 때** 복제된다. 심각도는 그 조합을 기준으로 매겼다. + +## 1. 결론 + +- **adapter kernel은 지정 범위에서 쓸 수 있다.** IndexedDB open/transaction의 "한 번만 결론 내기", 늦게 도착한 연결 닫기, 결론 뒤 도착한 upgrade 중단이 한 곳에 있고 단위 테스트와 실제 브라우저 2탭 테스트가 있다. kernel 예외 규칙도 지켜진다. 위반 import 2건을 일부러 넣어 보니 `check:architecture`가 둘 다 잡았다. +- **OPFS 런타임은 조합 전에 막아야 할 결함이 2건 있다.** + - 05-01: 다른 탭이나 같은 탭에서 `reconcile()`이 돌면 진행 중인 put의 파일을 지운다. 그런데 put은 성공으로 보고되고, 덮어쓰기라면 이전 버전까지 사라진다. + - 05-02: put의 첫 receipt 쓰기가 quota 초과나 크래시로 실패하면 빈 `receipt.json`이 남는다. 그 뒤로 authority 전체의 reconcile과 GC가 영구히 멈춘다. + - 둘 다 재현 스크립트로 확인했다. +- **"손상된 행 하나가 정리 작업 전체를 멈추는" 패턴이 여러 곳에 남아 있다.** 직전 리뷰 6.5-4는 IndexedDB 파티션 purge의 행 단위 검증만 고쳤다. 다음 경로는 그대로다. + - open 단계의 governance 행 손상(05-03) + - 만료 sweep과 receipt prune(05-05) + - OPFS reconcile 루프(05-02) +- **사용자 데이터 삭제 보장이 부분적이다.** + - IndexedDB: LOGOUT/ACCOUNT_DELETION purge는 open이 성공해야만 돌고, dataset 전체를 지우는 경로가 port에 없다(05-03). + - OPFS: purge 뒤에도 chunk 바이트가 디스크에 남는다(05-04). +- **신·구 버전 탭 공존.** 설계 문서의 `future-schema`/`INCOMPATIBLE` 상태는 코드에 없다. 이전 버전 탭은 `MIGRATION_FAILED`/`READ_ONLY`를 받지만 실제로는 읽기도 못 한다(05-06). +- **미검증:** 실제 브라우저에서의 다중 탭 OPFS 경합, 실제 quota 초과, 2 GiB 객체 검증 시간은 확인하지 못했다. 게다가 단위 테스트 대역이 바로 이 동작을 숨긴다(05-08). + +## 2. 범위와 방법 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 | `clean-architecture-frontend-template`, `main` / `4626b73`. 미커밋은 `CLAUDE.md`와 가이드 문서뿐 | +| 목적·실행 구성 | 템플릿 reference runtime의 저장소·kernel 성숙도. 브라우저 SPA, 여러 탭 동시 실행 지원, SSR 없음 | +| 읽은 코드 | kernel 전 파일(`indexeddb-connection.ts`, `indexeddb-transaction.ts`, `abortable-operation.ts`, `browser-lifecycle.ts`, `retry-after.ts`, `bounded-capacity.ts`, 배럴), IndexedDB 런타임 전 파일(runtime, maintenance, governance, records, migrations, failure, types), Web Storage 어댑터·코덱·`src/contracts/storage-keys.ts`, `browser-file-storage/`(storage-manager, result), 관련 port(`src/application/ports/browser-file-storage/*`), `.dependency-cruiser.json`, `scripts/test-browser-file-storage-runtime-removal.ts`와 `scripts/lib/removal-fixture.ts`, `config/ci/gates.json`의 FE-GATE-008/020 | +| OPFS 하위 범위 | 보조 에이전트가 OPFS 7개 파일과 테스트를 읽고 재현했다. High 2건(05-01, 05-02)과 05-04는 이 리뷰어가 재현 스크립트를 다시 실행하고 해당 코드 줄을 직접 읽어 확인했다. 그 밖의 OPFS 항목은 보조 에이전트가 읽은 결과에 코드 확인을 일부 더한 것이다 | +| 문서 | `docs/operations/browser-file-storage-recovery.md`, `docs/operations/client-cache-and-storage-recovery.md`, `docs/architecture/browser-file-and-origin-storage.md` §6·§7·§11, VD-11, VD-15 | +| 실행한 테스트 | `node scripts/run-vitest.ts run` 대상 8파일(indexeddb-connection/transaction/runtime/maintenance, abortable-operation, storage-manager-adapter, browser-storage-policy, storage-registry) → **167/167 통과**. 보조 에이전트가 실행한 OPFS 3파일(opfs-worker-runtime 48, opfs-byte-store 22, indexeddb-opfs-journal 13) → **83/83 통과** | +| 재현 실험 | scratchpad `05/`에서 `node --experimental-transform-types`로 실행. repo 소스를 import만 하고 repo에는 쓰지 않았다.
① `idb-experiments.ts`: 결과가 E1~E4로 05-03, 05-06, 05-05의 근거다.
② `fake-fidelity.ts`: 메모리 IndexedDB와 실제 IndexedDB의 차이 5가지(05-08).
③ `opfs/reconcile-vs-live-put.ts`, `quota-receipt.ts`, `logout-remnant.ts`: 05-01, 05-02, 05-04 | +| 가드레일 실험 | `git worktree`로 분리한 사본에서 adapter 간 금지 import 2건을 넣고 `scripts/check-architecture.ts`를 실행했다. 두 건 모두 `adapters-do-not-know-other-concrete-adapters` 위반으로 검출됐다. worktree는 `git worktree remove --force`로 지웠다 | +| 확인하지 못한 범위 | ① Playwright `test:browser-capabilities`: 3엔진 브라우저 설치와 dev 서버가 필요하고 CI FE-GATE-008이 담당하므로 실행하지 않았다. 스펙은 읽었다.
② `test:browser-file-storage-removal`: repo 사본에서 test:all과 build를 전부 다시 돌리는 작업이라 브리프 범위 밖이다. 스크립트만 읽었다.
③ 실제 Web Locks, 실제 OPFS quota, 파일 핸들 무효화 | +| 직전 리뷰 비교 | 2026-09-24 리뷰 6.5절 1~10을 현재 코드에서 다시 확인했다. 결과는 아래 표와 같다 | + +직전 리뷰 6.5 재확인: + +| ID | 현재 상태 | 근거 | +|---|---|---| +| 6.5-1 OPFS GC 커서 | 해결. 한계는 코드에 표시돼 있다 | `opfs-byte-store-adapter.ts:1097-1110` digest 커서 페이징. 호출마다 가장 작은 digest부터 다시 시작한다는 한계가 `ponytail:` 주석으로 적혀 있다 | +| 6.5-2 dedup 재사용 청크 보호 | 해결 | worker `opfs-worker-runtime.ts:1240-1256`이 재사용 청크의 mtime을 갱신한다. 다만 청크 전체를 다시 쓰므로 임시 quota를 쓰고, 이 쓰기가 `QUOTA_EXCEEDED`로 실패할 수 있다 | +| 6.5-3 lock 대기와 RPC 타임아웃 | 해결 | lock 대기 상한이 별도 값이다(`opfs-policy.ts:58`, 10분). 넘으면 `BLOCKED`. 멈춘 put이 lock을 쥐는 문제는 05-07에 따로 적었다 | +| 6.5-4 파티션 purge가 손상 행에 막힘 | **부분 해결** | 행 단위는 고쳐졌다(`indexeddb-runtime.ts:2229-2451`, 테스트 `indexeddb-runtime.test.ts:1246`). open 단계 손상과 만료 sweep은 그대로다 → 05-03, 05-05 | +| 6.5-5 prepared-object 검증기 | **부분 해결** | `opfs-prepared-object.ts`로 합쳐졌고 저장된 객체는 자기 chunk 크기로 검증한다. `stableJson` 2벌, objectId 정규식 하드코딩이 남아 있다 → 05-10 | +| 6.5-6 openObject 이중 읽기 | 해결 | 보조 에이전트 확인(client `:343-355`, worker `:717`, `:773-778`) | +| 6.5-7 IndexedDB 저장 행 검증기 중복 | 해결 | runtime·maintenance·governance가 `indexeddb-records.ts`를 import한다. binding 검증의 수제 트랜잭션은 남아 있다 → 05-12 | +| 6.5-8 삭제 후 revision 재시작 | 문서화 | `indexeddb-port.ts` `IndexedDbWriteReceipt` 주석(D-13), `opfs-ports.ts:29-35` | +| 6.5-9 보상 실패 시 원래 코드 유지 | 코드는 해결, runbook은 미갱신 | adapter `:917-947`. `browser-file-storage-recovery.md:17-21`은 예전 코드를 적고 있다 → 05-09 | +| 6.5-10 kernel 계약 구멍 2개 | 해결 | `indexeddb-transaction.ts:269-280`, `indexeddb-connection.ts:337-341`. 테스트는 `indexeddb-connection.test.ts:472-530` | + +## 3. 확인된 강점 + +1. **IndexedDB 상태 기계가 kernel 한 곳에 있다.** open, versionchange, blocked, 트랜잭션 결론을 한 곳에서 처리한다. + - 결론은 한 번만 난다. 늦게 온 연결은 닫는다(`src/adapters/platform/indexeddb-connection.ts:273-277`, `:420-425`). + - open이 이미 결론 난 뒤 시작된 upgrade는 중단한다(`:337-341`). + - versionchange가 오면 연결을 바로 닫고 캐시 핸들을 버린다(`:473-486`). + - 성공 뒤에 온 실패가 이긴다(`indexeddb-transaction.ts:269-280`). + - 실제 브라우저 2탭 versionchange·blocked 테스트가 있다(`tests/browser-capabilities/indexeddb-runtime.spec.ts:920`, `:972`). 이 테스트는 CI FE-GATE-008에서 Chromium·Firefox·WebKit으로 돈다(`config/ci/gates.json:1836-1845`). +2. **IndexedDB CAS의 저장 규칙이 한 트랜잭션 안에서 지켜진다.** 한 readwrite 트랜잭션이 다음을 함께 처리한다. + - record, retention sidecar, dataset budget, idempotency receipt 갱신 + - revision CAS와 같은 키 재실행 판정(`indexeddb-runtime.ts:1488-1731`) + - commit이 실패하면 전부 되돌린다(테스트 `indexeddb-runtime.test.ts:346`). 여러 탭의 동시 쓰기는 IndexedDB가 트랜잭션을 순서대로 실행하므로 막힌다. +3. **스키마·데이터 migration 절차가 안전한 순서를 지킨다.** + - DDL은 추가만 허용한다(`indexeddb-migrations.ts`). + - codec migration은 변환을 트랜잭션 밖에서 한다. + - 쓸 때 revision과 codec version을 다시 확인하고, checkpoint를 CAS로 갱신한다(`indexeddb-maintenance.ts:746-985`). + - 이전 버전 writer가 다 빠졌다는 확인 없이는 시작하지 않는다(`:1006-1027`). +4. **사용자별 저장소가 이름으로 분리된다.** DB 이름은 opaque token 3개에서만 만든다(`indexeddb-governance.ts:67-80`). 저장된 scope·policy binding을 upgrade, open, maintenance 때마다 확인한다(`:163-322`). 관측 이벤트에는 key, 값, 계정이 들어가지 않는다(`indexeddb-types.ts` `IndexedDbObservation`). +5. **Web Storage는 신·구 버전 탭이 서로의 값을 지우지 않는다.** + - 물리 키에 `schemaVersion`이 들어간다(`src/contracts/storage-keys.ts:165-171`). 그래서 스키마를 올리면 다른 키를 쓰게 된다. + - 코덱은 accessor, 이상한 prototype, 크기 초과를 저장 전에 거절한다(`browser-storage-codec.ts:126-231`). + - 제거 대상은 해당 물리 키 하나뿐이다(`browser-storage-adapter.ts:84-101`). +6. **kernel 예외 범위가 지켜지고, 위반하면 자동으로 걸린다.** + - `src/adapters/**`의 그룹 간 import 대상은 전부 `platform/`, `browser-file-storage/result.ts`, `cross-context-invalidation/index.ts` 중 하나다(전수 확인). + - 위반 2건을 넣은 실험에서 `check:architecture`가 둘 다 검출했다. + - 런타임 제거 드릴이 CI FE-GATE-020에서 돈다(`config/ci/gates.json:2072-2080`). + +## 4. 발견 사항 (36.3) + +### 05-01 OPFS reconcile이 진행 중인 put의 파일을 지우고, put은 성공으로 보고된다 +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 (재현) | +| 관련 관점 | 12, 1, 6, 11, 28 | +| 근거 | ① reconcile은 미완료 journal 행을 모두 가져오고, 행 주인이 아직 살아 있는지 보지 않는다(`indexeddb-opfs-journal.ts:688-728`, `opfs-byte-store-adapter.ts:566`).
② `PREPARING` 행이면 `cleanupTransaction`을 부른 뒤, 행에 적힌 주인의 `fencingToken`으로 rollback한다(`opfs-byte-store-adapter.ts:957-976`). 주인의 토큰을 그대로 쓰므로 fence가 주인을 막지 못한다.
③ worker cleanup은 mutation lock을 기다린다. lock은 FINISH_PUT이 끝나면 풀린다(`opfs-worker-runtime.ts:543-546`). 그 직후 cleanup이 receipt에 적힌 generation과 manifest를 지운다(`:890-918`).
④ journal rollback은 `FILES_READY` 행도 받아들인다(`indexeddb-opfs-journal.ts:641-647`).
⑤ 재현 결과(`scratchpad/05/opfs/reconcile-vs-live-put.ts`, 실제 adapter·worker·journal에 메모리 FS와 FIFO 배타 lock을 붙임): 첫 put은 `tab A put: ok gen 1` → `tab B reconcile: CONFLICT` → `open: INTEGRITY_FAILED`. 덮어쓰기도 `ok gen 2` 뒤 `INTEGRITY_FAILED`였고, gen 1도 사라졌다 | +| 발생 조건 | 탭 B(또는 같은 탭)의 `maintenance.reconcile()`이 탭 A의 put이 진행되는 동안 실행된다. 앱 시작 때 reconcile을 돌리는 흔한 조합에서 두 번째 탭을 열기만 해도 생긴다. runbook도 운영자에게 reconcile 실행을 안내한다(`browser-file-storage-recovery.md:25`) | +| 영향 | 성공으로 보고된 쓰기가 사라진다. 덮어쓰기라면 이전 버전도 사라진다. 설계 문서의 "committed row는 partial file을 가리키지 않는다"(§7.2)가 깨진다 | +| 심각도·우선순위 | High · P1. 지원 범위인 여러 탭 실행에서 사용자 데이터가 조용히 사라진다. repo에서는 조합되지 않았지만 OPFS를 조합하는 순간 모든 다운스트림에 복제되므로, 조합 전에 막아야 한다 | +| 통제·증거 | M1(설계 문서의 약속만 있음) · E2(메모리 FS 재현). 실제 브라우저는 미검증 | +| 확실성과 남은 가정 | 경쟁 순서는 코드로 확인했다. 실제 Web Locks가 FIFO라는 가정은 재현 스크립트와 같다. 실제 브라우저에서의 타이밍은 미검증이다 | +| 최소 개선 방향 | reconcile이 살아 있는 put의 행을 건드리지 못하게 한다. 방법은 ① 트랜잭션별 Web Lock을 begin부터 complete까지 잡고, reconcile은 `ifAvailable`로 잠기지 않은 행만 처리한다. ② 또는 물리 삭제 전에 journal에서 fencing token을 CAS로 넘겨받는다(소유권 이전). 비교 대안인 "시작 후 N분 지난 행만" 방식은 시계에 의존하므로 보조 수단으로만 쓴다 | +| 비용·부작용 | 트랜잭션별 lock 이름 규칙이 추가된다. 탭이 비정상 종료되면 lock이 자동으로 풀리므로 복구 경로는 유지된다 | +| 완료 기준 | 두 런타임이 같은 root와 journal을 공유하는 상태에서 put과 reconcile을 겹쳐 실행해도 ① put이 성공이면 `open`이 성공하고 ② reconcile은 해당 행을 건너뛴다 | +| 검증 방법 | 재현 스크립트를 단위 테스트로 옮긴다(실제 journal + 배타 lock 대역). 실제 브라우저 2탭 스펙을 추가한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음(6.5-2의 GC 경합과는 다른 경로) | + +### 05-02 첫 receipt 쓰기가 실패하면 빈 `receipt.json`이 남아 authority 전체의 reconcile과 GC가 영구히 멈춘다 +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 (재현) | +| 관련 관점 | 6, 28, 11, 14 | +| 근거 | ① `writeJsonAtomic`은 `getFileHandle({create:true})`로 빈 파일을 먼저 만든 뒤 쓴다(`opfs-worker-runtime.ts:1292-1303`).
② `beginPut`에서 첫 `writeReceipt`가 실패하면 lease만 풀고 빈 receipt는 남긴다(`:398-417`).
③ 보상 cleanup이 그 파일을 파싱하다 `CORRUPT_DATA`를 던진다(`:1306-1315`). 코드는 "읽을 수 없는 staging은 남긴다"는 방침에 따라 파일을 지우지 않는다(`:893-903`).
④ reconcile 루프는 첫 실패에서 바로 반환하므로 GC 단계까지 가지 못한다(`opfs-byte-store-adapter.ts:600-613`).
⑤ 재현 결과(`quota-receipt.ts`): put `QUOTA_EXCEEDED/RECONCILE` → reconcile을 반복해도 매번 `CORRUPT_DATA` → 같은 id로 다시 put하면 `CONFLICT/NONE` → 다른 id의 put은 성공하지만 reconcile은 계속 `CORRUPT_DATA` | +| 발생 조건 | origin이 quota에 닿은 상태에서 put을 시작할 때(첫 쓰기가 가장 먼저 실패한다), 또는 파일 생성과 쓰기 사이에 탭이 크래시할 때 | +| 영향 | ① 해당 objectId가 영구히 막힌다. ② GC가 돌지 않아 quota가 회수되지 않는다. 문제를 일으킨 quota 부족이 스스로 풀리지 않는다. ③ `listIncomplete`에는 scope 필터가 없어 같은 authority의 모든 partition에서 reconcile이 멈춘다. ④ runbook은 journal 행 수동 삭제를 금지하므로(`browser-file-storage-recovery.md:28`) 승인된 탈출 경로가 없다 | +| 심각도·우선순위 | High · P1. 복구 경로가 없는 정지이고, 복구가 가장 필요한 상황(quota 부족)에서 생긴다. OPFS 조합 전 차단 항목이다 | +| 통제·증거 | M0(이 경로를 처리하는 코드가 없음) · E2(메모리 FS 재현) | +| 확실성과 남은 가정 | 실제 OPFS에서 `getFileHandle({create:true})`가 빈 파일을 바로 만들고, 쓰기에 실패하면 swap 파일만 버린다는 가정을 두었다. 이는 표준 동작이다. 실제 브라우저에서 quota를 재현하지는 않았다 | +| 최소 개선 방향 | ① 0바이트 receipt는 "receipt 없음"으로 처리한다. ② reconcile 루프는 실패한 행을 건너뛰고 세고 계속 진행한 뒤 GC까지 간다. 05-05와 같은 방식이다 | +| 비용·부작용 | 작다. 건너뛴 행은 관측 이벤트로 보고해야 조용히 묻히지 않는다 | +| 완료 기준 | 첫 쓰기에서 quota 실패를 주입한 뒤 ① reconcile이 그 행을 정리하거나 건너뛰고 ② GC까지 실행되고 ③ 같은 id의 재시도가 성공한다 | +| 검증 방법 | worker 단위 테스트에 "빈 receipt 파일" 픽스처를 추가하고, adapter 테스트에 "행 하나 실패 + 나머지 정상"을 추가한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 05-03 IndexedDB LOGOUT/ACCOUNT_DELETION purge는 open이 성공해야만 돌고, dataset을 지우는 경로가 없다 +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 (재현) | +| 관련 관점 | 11, 15, 28, 27 | +| 근거 | ① `enforceLifecycleBatch`는 `runTransaction`을 거치고, `runTransaction`은 캐시된 연결(`connection.current()`)이 없으면 바로 `UNAVAILABLE`을 반환한다(`indexeddb-runtime.ts:823-836`, `:2453-2510`).
② open의 admission이 governance binding과 budget 행을 검증한다. budget 행 모양이 틀리거나 `usedBytes > hardBudgetBytes`이면 `CORRUPT`로 보고 `POLICY_REJECTED`로 open을 거절한다(`indexeddb-governance.ts:278-289`, `indexeddb-runtime.ts:696-728`, `:599-609`).
③ port에는 dataset 삭제(`deleteDatabase`) 연산이 없다(`indexeddb-port.ts` `IndexedDbRepositoryPort`). kernel에 `deleteIndexedDbDatabase`가 있지만 이 런타임은 쓰지 않는다.
④ 재현 결과(E1): budget 행을 손상시킨 뒤 새 런타임의 open → `POLICY_REJECTED`, `ACCOUNT_DELETION` → `UNAVAILABLE/REOPEN`, 개인 record가 그대로 남았다 | +| 발생 조건 | governance 행(binding 또는 budget)이 손상됐을 때. 다음 경우도 같은 결과가 된다(일시적): 정책 값이 바뀐 새 release, 이전 버전 탭(05-06), blocked upgrade | +| 영향 | 계정 삭제나 로그아웃 뒤에도 그 기기에 개인 데이터가 남는다. 행 손상은 R-5.4로 고쳤지만 같은 종류의 손상이 한 단계 앞(open)에서 여전히 purge를 막는다 | +| 심각도·우선순위 | Medium · P2. 손상이 있어야 생기고 피해는 기기 한 대로 한정된다. 다만 계정 삭제 계약이 걸린 경로이고 다운스트림에 복제된다. PERSONAL/CONFIDENTIAL dataset을 조합하기 전에 고친다 | +| 통제·증거 | M2(행 단위만 구현) · E2(메모리 IndexedDB 재현) | +| 확실성과 남은 가정 | 경로는 코드와 재현으로 확인했다. 실제 기기에서 governance 행이 손상되는 빈도는 모른다 | +| 최소 개선 방향 | LOGOUT/ACCOUNT_DELETION에 한해, open(admission)이 `POLICY_REJECTED`/`CORRUPT`로 실패하면 authority 승인을 받은 뒤 `deleteIndexedDbDatabase`로 dataset DB 전체를 지우는 경로를 둔다. runbook의 "DB 전체 삭제는 data owner 승인 action" 원칙은 `authorizeLifecycle` proof로 충족한다. 같은 연산이 capability 제거 시 기기 데이터 정리(관점 27)에도 쓰인다 | +| 비용·부작용 | port에 메서드가 하나 는다(추가만 하는 변경). blocked 상태의 삭제는 결과를 알 수 없으므로(kernel `BLOCKED_DEADLINE`) 결과 계약을 정해야 한다 | +| 완료 기준 | budget/binding 행이 손상된 DB에서 ACCOUNT_DELETION이 dataset을 완전히 지우고 `COMPLETE`를 반환한다 | +| 검증 방법 | E1 시나리오를 단위 테스트로 만든다. 메모리 대역은 `deleteDatabase`가 없으므로 대역에 추가해야 한다. 실제 브라우저 스펙에도 넣는다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 6.5-4 부분 해결 | + +### 05-04 OPFS LOGOUT/ACCOUNT_DELETION purge 뒤에도 파일 바이트가 디스크에 남는다 +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 (재현) | +| 관련 관점 | 11, 15, 24, 27 | +| 근거 | ① purge의 remove는 객체 디렉터리만 지운다(`opfs-byte-store-adapter.ts:500-505`, `opfs-worker-runtime.ts:799-810`).
② chunk는 GC만 지우고, GC는 쓴 지 24시간 지난 청크만 지운다(`opfs-byte-store-adapter.ts:1088-1091`, `opfs-policy.ts:61`).
③ 재현 결과(`logout-remnant.ts`): purge가 `removedObjects 1, releasedBytes 5`를 보고한 직후에 reconcile을 돌려도 `chunks/sha256/…bin => SECRT`가 남아 있었다 | +| 발생 조건 | 모든 LOGOUT/ACCOUNT_DELETION purge. 로그아웃한 사용자의 scope로는 다시 런타임을 열지 않을 수 있으므로 GC가 영영 돌지 않을 수 있다 | +| 영향 | 공용 기기에서 로그아웃하거나 계정을 삭제한 사용자의 파일 내용이 남는다. `removedObjects`/`releasedBytes`라는 보고가 실제 삭제 범위를 과장한다. journal의 scope binding 행도 남는다 | +| 심각도·우선순위 | Medium · P2. 개인정보 잔존이지만 같은 origin 접근이 있어야 읽을 수 있다. 개인 파일을 다루는 조합 전에 고친다 | +| 통제·증거 | M1 · E2 | +| 확실성과 남은 가정 | 청크 경로가 partition별이라 partition 디렉터리를 통째로 지워도 다른 사용자 데이터에 영향이 없다는 점은 보조 에이전트가 경로 구성(`scopeRootPath`)으로 확인했다 | +| 최소 개선 방향 | purge가 끝나면 mutation lock 안에서 `authorities///

` partition 디렉터리를 통째로 지운다. 또는 해당 purge에 한해 grace 없이 GC를 돌린다 | +| 비용·부작용 | 작다. 같은 partition의 진행 중 put과 경합하므로 lock 안에서 해야 한다 | +| 완료 기준 | purge `COMPLETE` 직후 해당 partition 경로에 파일이 0개 | +| 검증 방법 | `logout-remnant.ts`를 테스트로 만든다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 05-05 만료 정리(RETENTION_SWEEP, receipt prune)가 손상 행 하나에 영구히 멈추고, receipt가 쌓여 결국 모든 쓰기가 실패한다 +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 (재현) | +| 관련 관점 | 6, 11, 28, 8 | +| 근거 | ① RETENTION_SWEEP은 sidecar가 손상됐거나 budget이 삭제 바이트를 감당하지 못하면 배치 전체를 `CORRUPT_DATA`로 중단한다(`indexeddb-runtime.ts:2132-2148`, `:2179-2185`). 다음 호출도 인덱스의 같은 첫 행부터 다시 시작한다.
② `pruneExpiredReceipts`도 손상 receipt 하나나 `receiptCount < 1`이면 중단한다(`indexeddb-maintenance.ts:1185-1193`, `:1210-1216`).
③ CAS는 `receiptCount > maxIdempotencyReceipts`이면 `LIMIT_EXCEEDED`를 반환한다(`indexeddb-runtime.ts:1584-1607`).
④ 재현 결과: E3 손상 sidecar 1개 → sweep 3회 모두 `CORRUPT_DATA`, 만료된 정상 행 a·b·c가 그대로 남음. E4 손상 receipt 1개 → prune `MIGRATION_FAILED/INDEXEDDB_MIGRATE`, 이후 CAS 한 번 성공 뒤 `LIMIT_EXCEEDED` | +| 발생 조건 | 만료 인덱스 범위 안에 손상 행이 하나 있을 때. budget 값이 어긋났을 때도 같다 | +| 영향 | ① TTL 정책이 끝난 데이터가 기기에 계속 남는다. 읽기와 query는 만료 행을 숨기므로 화면에서는 보이지 않는다. ② receipt가 정리되지 않아 상한에 닿으면 그 dataset의 모든 쓰기가 영구히 `LIMIT_EXCEEDED`가 된다. ③ receipt 손상이 `MIGRATION_FAILED`로 보고돼 운영자를 migration 절차로 잘못 보낸다 | +| 심각도·우선순위 | Medium · P2. 손상이 있어야 생기지만 한번 생기면 스스로 풀리지 않고, 쓰기 기능이 결국 멈춘다 | +| 통제·증거 | M2 · E2 | +| 확실성과 남은 가정 | 손상 행에서 멈추는 것 자체는 의도된 fail-closed로 보인다(`indexeddb-runtime.test.ts:1038`이 고정). 문제는 그 뒤의 정상 행까지 막는 범위다. runbook의 "손상된 user-authored 행 자동 삭제 0" 원칙과 충돌하지 않게 고칠 수 있다 | +| 최소 개선 방향 | 손상 행은 지우지 않고 건너뛴다(개수를 세고 `CORRUPT_DATA` 관측으로 보고한다). 커서는 다음 행으로 진행한다. R-5.4가 파티션 purge에서 쓴 방식과 같다. prune의 실패 코드는 `CORRUPT_DATA`로 바로잡는다 | +| 비용·부작용 | budget 값이 조금 어긋나도 진행하게 되므로, 어긋난 값은 파티션 purge의 0 리셋처럼 다른 경로에서 바로잡아야 한다 | +| 완료 기준 | 손상 행 1개와 만료된 정상 행 N개가 있을 때 sweep·prune이 정상 행 N개를 지우고 손상 1건을 보고한다 | +| 검증 방법 | E3·E4 시나리오를 단위 테스트로 만든다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 6.5-4와 같은 계열. 이번에 새로 확인 | + +### 05-06 이전 버전 탭이 새 스키마(future schema)를 만나면 `MIGRATION_FAILED/READ_ONLY`를 받지만, 실제로는 읽기도 못 한다 +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 (문서 계약과 코드 불일치, 재현) | +| 관련 관점 | 11, 18, 5, 17, 28 | +| 근거 | ① runtime은 항상 자기 `schemaVersion`으로 open한다(`indexeddb-runtime.ts:649-653`). DB가 더 높은 버전이면 `VersionError`가 나고, 이것이 `MIGRATION_FAILED`, recovery `READ_ONLY`로 바뀐다(`indexeddb-failure.ts:36-44`).
② 상태 타입에 future-schema 상태가 없다(`indexeddb-port.ts:23-49`).
③ 읽기도 캐시된 연결이 필요하므로 `UNAVAILABLE/REOPEN`이 된다(`indexeddb-runtime.ts:835-836`).
④ 재현 결과(E2): v2 탭이 upgrade한 뒤 v1 런타임에서 open → `MIGRATION_FAILED/INDEXEDDB_OPEN/READ_ONLY`, 상태 `CLOSED/NOT_OPENED`, read → `UNAVAILABLE/REOPEN`.
⑤ 문서는 다르게 약속한다: `browser-file-and-origin-storage.md:563-580`(`future-schema -> read-only|online-only`), VD-15 `:713`(`INCOMPATIBLE`), `browser-file-storage-recovery.md:173`, `:190`.
⑥ OPFS journal도 v1만 알고 다른 버전은 모두 거절한다(`indexeddb-opfs-journal.ts:207-212`). 동작은 같다 | +| 발생 조건 | 롤링 배포 중에 새 탭이 스키마를 올리고 옛 탭이 열려 있을 때. rollback bundle이 future schema를 만날 때 | +| 영향 | ① 데이터 손상은 없다. 파괴적 쓰기 없이 fail-closed로 끝난다. ② 하지만 "새로고침이 필요하다"는 상황이 "migration 실패"로 보고돼 runbook §5(migration/corruption 사고)로 잘못 안내된다. ③ `READ_ONLY` 안내는 따를 수 없다 | +| 심각도·우선순위 | Medium · P2. 안전성은 유지되지만 흔한 공존 상황의 진단과 UX를 잘못 이끈다. 다운스트림이 이 코드를 보고 화면 분기를 만든다 | +| 통제·증거 | M1(문서만) · E2 | +| 확실성과 남은 가정 | 메모리 대역의 `VersionError` 경로는 실제 IndexedDB 동작과 같다. 실제 브라우저 스펙에는 이 경우가 없다 | +| 최소 개선 방향 | open에서 `VersionError`(또는 `oldVersion > schemaVersion`)를 별도로 분류해, 예를 들어 `code: "UNSUPPORTED"` 또는 새 코드, `recovery: "ONLINE_ONLY"`, 상태 `INCOMPATIBLE`로 드러낸다. 문서를 코드에 맞추는 선택도 가능하다. 그 경우 "N-1은 online-only로만 동작"이라고 적고 `READ_ONLY` 안내를 없앤다 | +| 비용·부작용 | 코드를 추가하면 port 계약을 바꾸는 변경이 된다(추가만). 문서만 고치면 비용이 거의 없다 | +| 완료 기준 | E2 시나리오에서 이전 버전 탭이 문서에 적힌 상태와 recovery를 받는다 | +| 검증 방법 | 단위 테스트 1개와 실제 브라우저 2탭 스펙(v2 upgrade 뒤 v1 재open) | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 05-07 source가 멈춘 put 하나가 origin 전역 OPFS mutation lock을 무기한 쥔다 +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 6, 12, 14, 22, 5 | +| 근거 | ① lock은 BEGIN_PUT에서 잡고(`opfs-worker-runtime.ts:368`) FINISH/FAIL/ABORT에서만 푼다.
② page 쪽 `rechunk`는 source 스트림을 기다리는 시간에 상한이 없다(`opfs-worker-client.ts:276-281`).
③ lock 이름은 origin 전체가 공유한다(`opfs-policy.ts:53`). 다른 쪽 대기 상한은 10분이다(`:58`).
④ reconcile 예산(5초)은 lock 대기를 세지 않는다. 기한 확인은 항목 사이에서만 한다(adapter `:604`, `:1120`)(보조 에이전트) | +| 발생 조건 | put의 source가 멈추고(네트워크 스트림 정지 등) 호출자가 signal을 넘기지 않았을 때 | +| 영향 | 모든 탭의 put, delete, finalize, GC가 10분 뒤 `BLOCKED`로 실패한다. 5초로 잡은 reconcile이 10분 걸릴 수 있다. 이 전역 직렬화는 port 계약에 드러나 있지 않다 | +| 심각도·우선순위 | Medium · P2. 탭을 닫으면 풀리므로 영구적이지 않다. D-3 결정으로 lock 범위를 좁히지 않기로 했으므로 남은 수단은 시간 상한뿐이다 | +| 통제·증거 | M1 · E1(기존 테스트 `stalledSource`가 lock 유지를 보여 준다고 보조 에이전트가 보고) | +| 확실성과 남은 가정 | 실제 브라우저에서 확인하지 않았다 | +| 최소 개선 방향 | worker의 active put에 idle timeout을 둔다(마지막 APPEND 이후 N초가 지나면 fail하고 lock을 푼다). port 주석에 "OPFS 쓰기는 origin 전체에서 한 번에 하나"를 적는다 | +| 비용·부작용 | 느린 source가 정상적으로 오래 걸리는 경우와 구분할 값이 필요하다 | +| 완료 기준 | source를 멈춘 put이 정해진 시간 안에 실패하고, 다른 탭의 put이 곧바로 진행된다 | +| 검증 방법 | 배타 lock 대역을 쓰는 worker 테스트 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 6.5-3의 남은 부분(타임아웃 분리는 해결, 무기한 점유는 남음) | + +### 05-08 테스트 대역이 여러 탭·트랜잭션 수명·quota 동작을 숨겨, 05-01·05-02 같은 결함을 잡지 못한다 +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 (재현으로 차이 확인) | +| 관련 관점 | 10, 12 | +| 근거 | `tests/helpers/memory-indexeddb.ts`와 실제 IndexedDB의 차이를 실험으로 확인했다(`fake-fidelity.ts`).
(a) 겹친 readwrite 트랜잭션 2개가 각자 스냅샷을 복제하고 store를 통째로 덮어쓴다(`:320-322`, `:486-490`). 카운터가 2가 아니라 1이 된다. 실제로는 순서대로 실행된다.
(b) macrotask 뒤에 낸 요청이 `TransactionInactiveError` 없이 받아들여지고 commit된다. 실제로는 예외가 난다.
(c) 배열 keyPath 인덱스를 primary key로 정렬한다(`:611-614`). 키 비교도 `String`/JSON으로 한다(`:118-147`).
(d) DB 이름을 무시한다(`:744-745`). 그래서 user-B DB가 user-A 행을 본다. 테스트가 이를 우회하려고 이름별 라우팅 factory를 따로 만들었다(`indexeddb-runtime.test.ts:1268-1272`).
(e) 더 높은 버전으로 open해도 기존 연결에 versionchange가 오지 않는다(수동 `triggerVersionChange`만 있음).
(f) upgrade 트랜잭션을 동기로 끝내므로, upgrade 안에서 비동기로 난 abort(binding 불일치)가 되돌려지지 않는다(`:939-964`).
OPFS 쪽(보조 에이전트): byte-store 테스트의 가짜 journal은 fence와 phase를 무시한다(`opfs-byte-store.test.ts:126-245`). 대부분의 worker 테스트는 배타성이 없는 `immediateLeases`를 쓴다. 메모리 FS에는 quota가 없다. 공유 root에서 두 런타임을 돌리는 테스트가 없다 | +| 발생 조건 | 이 대역으로 동시성, upgrade, 인덱스 정렬, quota를 검증하려 할 때 | +| 영향 | ① 이 영역의 High 결함 2건이 통과하는 테스트 옆에 숨어 있었다. ② 대역은 `tests/helpers/`에 있어 다운스트림이 그대로 복사해 쓰는데, 헤더 주석(`:723-727`)은 "transaction-level commit/rollback과 upgrade blocking을 모델링한다"고만 말하고 위 차이는 밝히지 않는다. 실제 브라우저 스펙(CI FE-GATE-008)이 일부를 보완하지만 2탭 CAS 경합, upgrade 중 binding abort, 복합 인덱스, OPFS 다중 탭은 다루지 않는다 | +| 심각도·우선순위 | Medium · P2. 테스트가 주는 확신이 과장된다. 제품 피해는 간접적이다 | +| 통제·증거 | M2 · E2(실험) | +| 확실성과 남은 가정 | 차이 (a)~(e)는 실험으로, (f)는 코드로 확인했다 | +| 최소 개선 방향 | ① 대역 헤더에 모델링하지 않는 의미를 적는다(가장 싸다). ② 가능하면 대역이 DB 이름 분리, 트랜잭션 직렬화, 비활성 요청 예외를 흉내 내게 한다. ③ OPFS는 배타 lock 대역과 공유 root 2런타임 테스트 1개를 추가한다. 이 테스트가 05-01을 잡는다. 실제 브라우저 2탭 OPFS 스펙 추가도 검토한다 | +| 비용·부작용 | 대역을 고치면 기존 테스트 일부가 드러나는 결함 때문에 실패할 수 있다(의도된 결과) | +| 완료 기준 | 위 (a)·(b)·(d) 실험이 대역에서 실제 IndexedDB와 같은 결과를 내거나, 헤더에 명시된 비지원 항목이 된다. 05-01·05-02 회귀 테스트가 존재한다 | +| 검증 방법 | `fake-fidelity.ts`를 대역 자체의 테스트로 옮긴다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 6.5-3 "immediateLeases가 경합을 보지 않음"과 같은 계열. 미해결 | + +### 05-09 OPFS recovery runbook이 현재 코드와 다르다 +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 (문서 불일치) | +| 관련 관점 | 28, 9, 17 | +| 근거 | ① `browser-file-storage-recovery.md:17-21`은 보상 실패를 `OBJECT_RECONCILE`/`CONFLICT`(recovery `RETRY`)로 보고한다고 적었다. 코드는 put 자신의 코드를 유지하고 `OBJECT_WRITE`, recovery `RECONCILE`을 쓴다(`opfs-byte-store-adapter.ts:933-946`, Q-6.5-9에서 바뀜).
② `:26`의 `EFFECT_UNKNOWN`은 worker가 보내지 않는다. client 파서도 거절하므로(`opfs-worker-client.ts:652-658`) adapter 분기 `:936`, `:964`는 실행되지 않는다.
③ `:374-375`는 `PREPARING`은 resume, `FILES_READY` 검증 실패는 quarantine이라고 적었다. 코드는 둘 다 삭제만 한다(`opfs-byte-store-adapter.ts:957-1012`) | +| 발생 조건 | 운영자가 runbook대로 신호를 찾거나 복구를 기대할 때 | +| 영향 | 운영자가 나오지 않는 코드를 찾고, 존재하지 않는 quarantine/resume을 기대한다. 삭제되는 데이터는 commit 전 staging뿐이라 데이터 피해는 제한적이다 | +| 심각도·우선순위 | Low · P2. 문서 불일치지만 복구 절차 문서라서, 도입 전에 맞춘다 | +| 통제·증거 | M1 · E1 | +| 확실성과 남은 가정 | 코드와 문서 줄을 대조했다 | +| 최소 개선 방향 | runbook의 STO-01 절과 §7 recovery를 현재 코드에 맞춘다. `EFFECT_UNKNOWN`은 port에서 없애거나 worker가 실제로 보내게 한다 | +| 비용·부작용 | 작다 | +| 완료 기준 | runbook의 코드·phase별 동작이 adapter와 일치하고, 죽은 분기가 없다 | +| 검증 방법 | `verify:documentation` 범위에 이 표를 넣을 수 있는지 검토. 최소한 수동 대조 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 6.5-9 후속(문서 미갱신) | + +### 05-10 prepared-object 검증 통합이 덜 끝났다: objectId 정규식 하드코딩, `stableJson` 2벌 +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 (조건부) | +| 관련 관점 | 9, 19, 23 | +| 근거 | ① 정책의 `isObjectIdAllowed`는 바꿀 수 있다(`opfs-policy.ts:29`, `:65`). 그런데 `isPreparedObject`는 `/^[A-Za-z0-9_-]{8,128}$/`을 하드코딩했다(`opfs-prepared-object.ts:8`, `:55-56`). 정책을 넓히면 BEGIN_PUT은 통과하고 FINISH_PUT은 `CORRUPT_DATA`로 실패한다.
② `stableJson`이 두 벌이고 NaN 처리가 다르다(`opfs-worker-runtime.ts:1723-1734`는 throw, `indexeddb-opfs-journal.ts:1611-1619`는 `"null"`).
③ `sameScope`, SHA-256·generation id 정규식도 여러 곳에 중복돼 있다(보조 에이전트) | +| 발생 조건 | 다운스트림이 objectId 규칙을 넓힐 때(예: 더 긴 id). NaN은 정책 검증 때문에 현재 도달하지 않는다 | +| 영향 | 설정 하나를 바꾸면 모든 put이 마지막 단계에서 실패하고 journal 행이 남는다 | +| 심각도·우선순위 | Low · P3. 기본 설정에서는 생기지 않는다 | +| 통제·증거 | M2 · E1 | +| 확실성과 남은 가정 | 코드로 확인했다. 실행 재현은 하지 않았다 | +| 최소 개선 방향 | `isPreparedObject`가 objectId 문법을 policy에서 받거나, policy의 허용 범위를 prepared-object 문법 안으로 제한(검증)한다. `stableJson`은 한 벌만 남긴다 | +| 비용·부작용 | 작다 | +| 완료 기준 | 넓힌 objectId 정책으로 put이 끝까지 성공하거나, 정책 생성 시점에 거절된다 | +| 검증 방법 | 정책 확장 단위 테스트 1개 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 6.5-5 부분 해결 | + +### 05-11 IndexedDB 예외 매핑 표가 두 벌이고, OPFS가 IndexedDB 폴더에 묶여 "각자 독립 제거 가능" 주장이 사실과 다르다 +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 (주석 주장 불일치) + 개선 제안 | +| 관련 관점 | 9, 27, 2, 23 | +| 근거 | ① IndexedDB 예외 매핑 표가 두 벌이다: `storage/indexeddb/indexeddb-failure.ts:22-72`(runtime, maintenance, OPFS journal이 사용)와 `browser-file-storage/result.ts:43-90`(checkpoint store 등이 사용). 결과가 다르다. `QuotaExceededError`의 retryable 값, `NotFoundError`, `TransactionInactiveError`, `ConstraintError` recovery가 서로 다르다. runtime 주석(`indexeddb-runtime.ts:553-557`)은 "통합은 별도 변경"이라고만 적었고 제거 조건과 담당이 없다.
② OPFS journal이 `../indexeddb/indexeddb-failure.ts`를 import한다(`indexeddb-opfs-journal.ts:34`). 같은 `storage` 그룹이라 규칙상 허용된다.
③ `.dependency-cruiser.json:207` 주석은 "storage/indexeddb와 storage/opfs가 각자 독립적으로 제거 가능"하다고 하고, `storage/index.ts:5-7`은 제거 스크립트가 "그 두 폴더만 삭제"한다고 한다. 실제 스크립트는 10개 경로를 한꺼번에 지운다(`scripts/test-browser-file-storage-runtime-removal.ts:23-34`). IndexedDB만 제거하는 경우는 검증되지 않고, 그렇게 하면 OPFS 빌드가 깨진다 | +| 발생 조건 | 다운스트림이 IndexedDB 런타임만 제거하거나, 두 매핑 표 중 하나만 고칠 때 | +| 영향 | 부분 제거가 실패한다. 같은 브라우저 예외에 대해 IndexedDB를 쓰는 두 어댑터가 다른 재시도 판단을 내린다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M1 · E1 | +| 확실성과 남은 가정 | import와 스크립트 경로 목록으로 확인했다 | +| 최소 개선 방향 | `mapIndexedDbException`을 kernel 예외 파일인 `browser-file-storage/result.ts`로 옮기고 `mapBrowserDataException`과 차이를 정리한다. 두 주석은 실제 드릴 범위("browser-file-storage 번들 전체를 함께 제거")에 맞게 고친다. 새 파일 단위 예외는 필요 없다 | +| 비용·부작용 | 매핑을 합치면 checkpoint store 등의 실패 코드가 바뀔 수 있어 테스트 갱신이 필요하다 | +| 완료 기준 | `storage/opfs/`에서 `storage/indexeddb/`로 가는 import가 0개. 주석이 드릴 범위와 일치 | +| 검증 방법 | import 그래프 확인. 원하면 IndexedDB만 제거하는 드릴 변형 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 05-12 binding 검증이 kernel 밖에서 트랜잭션 상태 기계를 손으로 다시 구현한다 +| 필드 | 내용 | +|---|---| +| 성격 | 개선 제안 | +| 관련 관점 | 9, 22 | +| 근거 | `verifyIndexedDbDatasetBinding`이 `oncomplete`/`onabort`/`onerror`와 caller abort를 직접 연결한다(`indexeddb-governance.ts:223-322`). `src/adapters`에서 kernel 밖에 `oncomplete`를 쓰는 곳은 여기 하나뿐이다. kernel의 CP-4 처리(abort가 throw하면 abort 주장을 철회, `indexeddb-transaction.ts:218-230`)가 이 복사본에는 없다 | +| 발생 조건 | kernel 트랜잭션 의미를 바꿀 때 이 복사본이 따라가지 않는다 | +| 영향 | 지금은 읽기 전용 검증이라 잘못된 결론의 피해가 작다. 다섯 번째 복사본이 다시 갈라질 여지가 있다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M2 · E1 | +| 확실성과 남은 가정 | grep과 코드로 확인했다 | +| 최소 개선 방향 | `runIndexedDbTransaction` + `onIndexedDbRequest`로 바꾼다 | +| 비용·부작용 | 작다. 동작을 고정하는 테스트가 있다(`indexeddb-runtime.test.ts:842`) | +| 완료 기준 | `src/adapters`에서 kernel 밖 `oncomplete` 사용 0곳 | +| 검증 방법 | 기존 binding 테스트 통과 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 6.5-7 후속 | + +### 05-13 IndexedDB 연결의 versionchange 핸들러가 비동기 admission이 끝난 뒤에야 설치된다 +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 12, 22 | +| 근거 | ① `onsuccess` 뒤 `admit`이 비동기로 binding 검증 트랜잭션을 돈다(`indexeddb-connection.ts:420-445`, `indexeddb-runtime.ts:696-728`).
② `onversionchange`는 open이 결론 난 뒤 `adopt`에서만 설치된다(`indexeddb-connection.ts:491-505`, `:473-486`). 그 사이 다른 탭이 upgrade를 요청하면 이 연결은 닫히지 않고, 상대는 blocked 기한(기본 10초)까지 기다리다 `BLOCKED`로 실패한다.
③ maintenance는 admit 안에서 먼저 핸들러를 설치한다(`indexeddb-maintenance.ts:429`). runtime만 이 창이 열려 있다 | +| 발생 조건 | 탭 A의 open admission(트랜잭션 1개, 수 ms)과 탭 B의 upgrade 요청이 겹칠 때 | +| 영향 | 탭 B의 upgrade가 한 번 실패한다. 재시도하면 이번에는 핸들러가 있어 풀린다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M2 · E1 | +| 확실성과 남은 가정 | 코드 순서로 판단했다. 재현하지 않았다 | +| 최소 개선 방향 | kernel `openIndexedDbDatabase`가 `onsuccess` 직후, admission 전에 임시 versionchange 핸들러(닫고 `CLOSED`로 결론)를 설치한다 | +| 비용·부작용 | 작다 | +| 완료 기준 | admission 중 versionchange가 와도 연결이 닫히고 open이 실패로 끝난다 | +| 검증 방법 | 대역에서 admission 중 `triggerVersionChange` | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 05-14 OPFS GC의 유예 기간을 "참조가 끊긴 시각"이 아니라 "쓴 시각"으로 센다 +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 (보조 에이전트 보고, 코드 일부 확인) | +| 관련 관점 | 12, 11 | +| 근거 | GC 후보는 mtime이 24시간 지난 청크다(`opfs-byte-store-adapter.ts:1088-1091`). 청크 읽기는 lock 없이 한다(worker `:767`, 보조 에이전트). 세대 N+1이 commit되면 N의 오래된 청크는 곧바로 삭제 대상이 된다 | +| 발생 조건 | 세대 N을 스트림으로 읽는 도중 N+1 commit과 reconcile GC가 끼어들 때 | +| 영향 | 읽기 스트림이 중간에 `NOT_FOUND`로 끊긴다. 재시도하면 새 세대를 읽으므로 데이터 손실은 없다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M1 · E1 | +| 확실성과 남은 가정 | 재현하지 않았다 | +| 최소 개선 방향 | 참조가 끊길 때 청크 mtime을 갱신하거나, 읽기 중인 세대를 GC가 알 수 있게 한다. 또는 port 주석에 "읽기 중 교체되면 NOT_FOUND 가능"을 적는다 | +| 비용·부작용 | 작다 | +| 완료 기준 | 선택한 방향에 맞는 테스트 또는 계약 주석 | +| 검증 방법 | worker 테스트 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +## 5. 28개 관점 판정 (36.2) + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +|---|---|---|---|---|---| +| 1 | 코드 성숙도 | 적용. 저장 규칙(CAS, revision, 재실행 판정, budget) | 목표 M2 / 확인 M2 | E2(167+83 통과), E2 재현 | 부분 충족 — 05-01(성공한 put 뒤 파일 삭제) | +| 2 | 구조적 성숙도 | 적용. kernel 예외 범위 | 목표 M3 / 확인 M3 | E3(worktree에 위반 2건 주입 → `check:architecture` 검출) | 충족 — 잔여: 같은 그룹 안 런타임 간 결합은 규칙이 보지 않는다(05-11). 참고: `depcruise` 자체는 TS 7에서 0 modules를 검사하고, 실제 판정은 스크립트 자체 그래프가 한다(다른 영역 — 가드레일) | +| 3 | 변경 용이성 | 적용. 정책·설정 변경 | M1 | E1 | 부분 충족 — dataset 정책 값(budget, TTL)을 바꾸면 binding 불일치로 기존 DB가 잠기고, 이행 경로는 문서상 "forward fix"뿐이다. objectId 정책 확장이 깨진다(05-10) | +| 4 | 인지 부하 | 적용 | — | E1 | 부분 충족 — kernel 덕분에 상태 기계는 한 곳에 있다. `indexeddb-runtime.ts`(2539줄)의 CAS는 여전히 콜백이 10단 넘게 중첩된다(`:1498-1729`) | +| 5 | 위험 가시성 | 적용 | M1 | E1 | 부분 충족 — D-13과 실패 분류는 port에 드러나 있다. origin 전역 OPFS 직렬화(05-07)와 future schema 의미(05-06)는 드러나 있지 않다 | +| 6 | 실패 성숙도 | 적용 | M2 | E2 | 부분 충족 — 손상 한 건이 정리 작업 전체를 멈추는 패턴(05-02, 05-05). quota는 `QUOTA_EXCEEDED`로 매핑되고 rollback된다(E2) | +| 7 | 운영 성숙도 | 적용(연결점만) | M1 | E1 | 부분 충족 — `observe` 연결점과 safe bucket 이벤트가 있다. 조합이 없어 실제 알림 경로는 없다(0.1 전제상 비대상) | +| 8 | 디버깅 가능성 | 적용 | M2 | E2 | 부분 충족 — 실패 코드가 닫혀 있고 원문을 노출하지 않는다. `MIGRATION_FAILED`가 receipt 손상(05-05)과 future schema(05-06)에 잘못 쓰인다 | +| 9 | 유지보수 성숙도 | 적용. 4벌 → kernel 통합 뒤 남은 중복 | M2 | E1 | 부분 충족 — 예외 매핑 2벌(05-11), 수제 트랜잭션 1곳(05-12), OPFS `stableJson` 등(05-10) | +| 10 | 테스트 성숙도 | 적용 | M3 | E2(250개 통과), CI FE-GATE-008 3엔진 | 부분 충족 — 대역이 동시성, upgrade, quota 의미를 숨기고 High 2건을 못 잡았다(05-08) | +| 11 | 데이터 성숙도 | 적용(핵심) | M2 | E2 | 부분 충족 — 추가만 하는 DDL, 경계가 있는 codec migration, 사용자별 DB 분리는 좋다. 삭제 보장(05-03, 05-04, 05-05)과 future schema(05-06)가 남았다 | +| 12 | 동시성 성숙도 | 적용(핵심, 여러 탭) | M2 | E2 재현, 실제 브라우저 2탭 IDB 스펙 | **미충족** — 05-01(High, 재현). 그 밖에 05-07, 05-13, 05-14 | +| 13 | 확장성 | 부분 적용. 데이터량 | M2(배치 500행/30초, query 스캔 5000행 상한) | E1 | 미검증 — 규모 목표가 없고 측정하지 않았다 | +| 14 | 성능 성숙도 | 부분 적용 | M2 | E1 | 미검증 — 2 GiB verify가 60초 RPC 안에 끝나는지, dedup이 청크를 다시 쓰는 비용 | +| 15 | 보안 성숙도 | 적용. 사용자 데이터 분리·잔존 | M2 | E2 | 부분 충족 — opaque 이름, 관측 이벤트에서 민감정보 제거, lifecycle proof는 좋다. 로그아웃 뒤 잔존(05-03, 05-04) | +| 16 | 의존성 성숙도 | 적용 제외 — 이 영역은 외부 패키지 없이 브라우저 API만 쓴다 | — | — | 적용 제외 | +| 17 | API / Contract | 적용. port 계약 | M2 | E1 | 부분 충족 — 닫힌 실패 분류, D-13 명시. `EFFECT_UNKNOWN`은 선언만 있고 쓰이지 않는다(05-09). future schema 코드(05-06) | +| 18 | 배포 성숙도 | 적용. 신·구 탭 공존 | M2 | E2 | 부분 충족 — Web Storage 키에 버전이 들어가고 IDB versionchange를 처리한다. N-1이 future schema를 만나면 잘못 분류된다(05-06). OPFS lock 이름·root가 설정값이라 release마다 다르면 탭끼리 배제가 깨진다(보조 에이전트, 검사 없음) | +| 19 | 설정 성숙도 | 적용 | M2(생성 시 assert) | E1 | 부분 충족 — 정책 검증은 강하다. objectId 정책과 검증기가 서로 맞지 않는다(05-10) | +| 20 | 개발자 경험 | 다른 영역 — 문서·온보딩 | — | — | 적용 제외(이 영역) | +| 21 | Guardrail 성숙도 | 적용. kernel 규칙, 제거 드릴, 번들 inventory | M3 | E3(위반 주입 실험), CI 게이트 정의 확인 | 충족 — 제거 드릴 자체는 실행하지 않았다(미검증 목록) | +| 22 | 추상화 성숙도 | 적용. kernel이 숨기는 것과 드러내는 것 | M2 | E1 | 부분 충족 — kernel은 메커니즘만 갖고 정책·실패 코드는 호출자에 남긴다(`indexeddb-connection.ts:19-24`). 좋은 경계다. 숨기지 말아야 할 것이 숨어 있다: OPFS 전역 lock(05-07), admission 중 versionchange 공백(05-13) | +| 23 | 일관성 | 적용 | M1 | E1 | 부분 충족 — 같은 예외가 두 어댑터에서 다른 답을 낸다(05-11) | +| 24 | 네이밍 / 의미 | 적용 | M1 | E2 | 부분 충족 — OPFS purge의 `removedObjects`/`releasedBytes`가 실제 삭제 범위를 과장한다(05-04) | +| 25 | 조직 확장성 | 적용(구조적 준비만) | — | E0 | 미검증 — dataset별 opaque scope와 kernel 공유 구조는 준비돼 있다. 팀이 하나라 실제 검증은 불가 | +| 26 | Ownership | 적용(템플릿 칸만) | M1 | E0 | 미검증 — runbook이 owner·연락처 칸을 비워 두고 설치 branch가 채우게 한다 | +| 27 | 삭제 가능성 | 적용 | M3(코드 제거 드릴 FE-GATE-020) | E1(스크립트 읽음, 미실행) | 부분 충족 — 번들 전체 제거는 검증된다. IndexedDB만 제거하는 경우는 불가(05-11). 기기에 남은 데이터를 정리하는 API가 없다(05-03). OPFS는 purge 뒤에도 바이트가 남는다(05-04) | +| 28 | 회복 가능성 | 적용(핵심) | M1 | E2 | **미충족** — 05-02는 승인된 복구 경로가 없다. runbook과 코드가 다르다(05-09, 05-06). dataset 삭제 경로가 없다(05-03) | + +적용 항목 26개 기준: 충족 2(2, 21), 부분 충족 18, 미충족 2(12, 28), 미검증 4(13, 14, 25, 26). 적용 제외 2(16, 20). + +## 6. 미검증 목록 + +| 항목 | 이유 | 확인에 필요한 것 | +|---|---|---| +| 05-01·05-02가 실제 브라우저에서 나는지 | 재현은 메모리 FS와 FIFO lock 대역으로 했다 | Playwright 2탭 OPFS 스펙(공유 root, 실제 Web Locks). quota는 `navigator.storage` 제한 환경이나 대용량 채우기로 재현 | +| 실제 IndexedDB의 2탭 CAS 경합, upgrade 중 binding 불일치 abort | 메모리 대역이 이 의미를 모델링하지 않고(05-08), 실제 브라우저 스펙에도 없다 | `indexeddb-runtime.spec.ts`에 케이스 추가 | +| `test:browser-capabilities` 현재 결과 | 3엔진 브라우저와 dev 서버가 필요하고 CI FE-GATE-008이 담당 | 오케스트레이터나 CI의 최신 JUnit | +| `test:browser-file-storage-removal` 현재 결과 | repo 사본에서 test:all과 build를 전부 다시 도는 작업이라 브리프 범위 밖 | CI FE-GATE-020 증거 | +| 2 GiB 객체 verify가 60초 RPC 안에 끝나는지 | 성능 측정 환경 없음 | 저사양 기기 측정 | +| dedup이 청크를 다시 쓸 때 다른 탭의 열린 File이 `NotReadableError`를 내는지, swap 파일이 quota에 잡히는지 | 브라우저별 동작 | 실제 브라우저 실험 | +| STO-01 이전(v1) 쓰기만 하는 옛 탭과의 공존 | 재현 환경 없음 | 두 release를 띄운 2탭 실험 | +| OPFS 판정 중 05-07·05-10·05-14의 세부 | 보조 에이전트가 읽은 결과이고 이 리뷰어가 재현하지 않았다 | 해당 단위 테스트 추가 시 확인 | diff --git a/docs/reviews/2026-09-25-maturity-review/06-adapters-service-worker-push.md b/docs/reviews/2026-09-25-maturity-review/06-adapters-service-worker-push.md new file mode 100644 index 00000000..af661c83 --- /dev/null +++ b/docs/reviews/2026-09-25-maturity-review/06-adapters-service-worker-push.md @@ -0,0 +1,299 @@ +# Service Worker / Web Push 성숙도 리뷰 + +> 검토일: 2026-09-25 · 기준: `main` / `4626b73` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 범위: `src/adapters/service-worker/` (7파일, 약 2.4k줄), `src/adapters/web-push/` (12파일, 약 3.7k줄), `vite.service-worker.config.ts`, `tsconfig.service-worker.json`, 이 영역의 테스트(`tests/unit/service-worker-*`, `tests/unit/web-push-*` 9파일 약 5.0k줄, `tests/e2e/service-worker-update.spec.ts`, `tests/helpers/fake-push-control-repository.ts`) +> 영역 판정(35.8): **조건부 사용 가능** — Service Worker 정적 자산(`PWA_STATIC_ASSETS`)에 한한다. **Web Push는 해당 용도의 사용 보류**(06-01, 06-02). + +## 1. 결론 + +- 기본 구성에서는 Service Worker(이하 SW)가 꺼져 있다(`src/features/installed-runtime-capabilities.ts:40`, `null`). Web Push는 빌드 단계에서 거부된다(`scripts/lib/service-worker-build-input.ts:58-62`). 그래서 아래 결함은 SW를 켜거나 Web Push를 조립한 다운스트림에서만 나타난다. +- SW 정적 자산 경로는 튼튼하다. 설치할 때 sha256·바이트 수·타입을 검증하고, 전부 성공해야만 쓴다. 해시 이름 GET만 가로채고, 이전 릴리스 캐시 1개를 남긴다. 32절 "새 배포 후 기존 탭" 시나리오는 활성화 전후 모두 옛 청크를 캐시나 네트워크에서 받는다(2.1절). 직전 리뷰 6.6-1~12는 코드와 테스트에 반영돼 있음을 현재 코드에서 다시 확인했다. +- Web Push에는 실제 브라우저에서 드러나는 결함이 2개 있다. **06-01**: 알림 클릭 핸들러가 실제 `Notification` 객체를 거부해서 모든 클릭이 무시된다. Chromium·Firefox·WebKit에서 `data`가 own property가 아님을 확인했고, 단위 재현 테스트도 실패했다. **06-02**: 두 탭에서 enable과 reconcile이 겹치면 한 탭은 `PUSH_READY`를 보고하는데, 탭들이 공유하는 native 구독과 서버 연결은 지워진다. 두 가지 실행 순서 모두 단위 테스트로 재현했다. +- 잘못 배포된 SW를 끄는 경로(28)는 페이지가 부팅해야만 동작한다. 운영 문서는 코드에 없는 "network-only kill switch"를 안내한다(06-03). 런타임 kill switch 분기를 무력화해도 관련 테스트 82개가 모두 통과한다(06-04). +- SW를 켜도 관측(observe)·차단기(blockers)·업데이트 알림이 조립되지 않는다. 그래서 설치 실패와 활성화 결과가 어디에도 보이지 않는다(06-05). +- 미검증: 여러 탭(얼어 있는 탭, 앱이 아닌 창)이 있을 때 실제 브라우저에서의 활성화, 롤백 릴리스 재설치, `service-worker.js`가 404를 줄 때 엔진별 등록 유지 여부. e2e 스펙은 이번에 실행하지 않았다. + +## 2. 범위와 방법 (36.1) + +| 항목 | 기록 | +| --- | --- | +| 대상 | `clean-architecture-frontend-template`, `main` / `4626b73`, 미커밋은 `CLAUDE.md`·가이드 문서뿐 | +| 목적과 실행 구성 | 템플릿. SW는 opt-in(`null` 기본), Web Push는 `NOT_SELECTED`·빌드 거부. 여러 탭은 지원 범위 | +| 읽은 코드 | 범위 전체 파일 전부. 연결 확인용: `src/contracts/service-worker.ts`, `src/contracts/web-push.ts`, `src/contracts/runtime-capabilities.ts:90-135`, `src/bootstrap/{register-service-worker,optional-runtime-host,create-runtime-composition}.ts`, `src/bootstrap/runtime-application.tsx`, `src/application/ports/out/web-push-control.ts`, `scripts/build-frontend.ts`, `scripts/generate-service-worker-assets.ts`, `scripts/generate-runtime-config.ts`, `scripts/lib/{service-worker-build-input,hosting-probe}.ts` | +| 읽은 문서(주장) | `docs/operations/release-cache-rollback.md`, `docs/operations/browser-file-storage-recovery.md` §8, `docs/operations/adapter-remediation-ledger.md`(SW/WP 행), `docs/architecture/realtime-events-web-push-and-bounded-polling.md` §5.5·§8, 설계 문서 §17.2~17.4·§24.10, `docs/architecture/optional-adapter-recipes.md` | +| 실행한 테스트 | `node scripts/run-vitest.ts run` + SW·web-push 단위 10파일 → **10 files, 126 tests passed** | +| 실험 1 (브라우저 속성) | Playwright로 Chromium·Firefox·WebKit에서 `Notification.prototype.data`가 getter인지, 인스턴스에 own `data`가 있는지 확인 → 세 엔진 모두 getter이고 `Object.hasOwn(n,"data") === false`, own key 0개 (06-01) | +| 실험 2 (분리 worktree, 삭제 완료) | ① WebIDL 형태 알림으로 click 재현 → 실패. own property 검사를 `"data" in` 으로 바꾸면 `close`/`waitUntil` 호출 확인 (06-01). ② 두 탭 push 경합 두 가지 순서 → 둘 다 실패 (06-02). ③ `disabledCleanup` 분기 무력화 변이 → 관련 5파일 82개 테스트 통과 (06-04). 재현 파일: 스크래치패드 `06/zz-review06-probe.test.ts` | +| 실험 3 | `classifyFetch`를 node로 실행해 API·다운로드 URL 분류 확인 (06-08) | +| 확인하지 못한 범위 | e2e `service-worker-update.spec.ts`(지시서상 vitest만 허용), 실제 푸시 서비스·VAPID 흐름, 여러 탭·롤백 브라우저 실험, `scripts/test-realtime-runtime-removal.ts` | +| 직전 리뷰 비교 | 6.6-1~6.6-12 반영 확인. 6.6-2 시나리오 중 "얼린 백그라운드 탭" 부분은 남음(06-07). 6.6-7 수정 분기가 새 경합 원인이 됨(06-02 순서 2) | + +### 2.1 32절 "새 배포 후 기존 탭 사용" 추적 + +전제: SW `ACTIVE` + `PWA_STATIC_ASSETS`, 릴리스 N → N+1. 호스팅은 N+1의 `/assets/`만 서빙한다고 가정한다(e2e도 같은 가정). + +```text +탭 A(빌드 N, 워커 N 제어) ── 배포 N+1 ──▶ 서버: index.html · service-worker.js · assets = N+1 + ├─ 탭 A의 N 청크 요청 → 워커 N: N manifest에 있음 → 현재 캐시 hit (lifecycle.ts:295-315) + ├─ 브라우저 update 검사(내비게이션, 6시간 update()) → 워커 N+1 설치(자산 검증·캐시) → waiting + │ (page-controller.ts:157-161, 351-363) + ├─ 새 탭 B(빌드 N+1) → N+1 청크: N manifest에 없음 + 해시 이름 + │ → PREVIOUS_RELEASE_FALLBACK → N-1 캐시 miss → 네트워크 (static-assets.ts:53-56, entry.ts:106-109) + ├─ [템플릿 그대로] 아무도 requestActivation()을 부르지 않음 + │ → 모든 탭이 닫힐 때까지 워커 N 유지 → 옛 탭도 계속 동작 (안전) + └─ [다운스트림이 활성화 UI를 붙인 경우] requestActivation → 모든 창 drain → skipWaiting + → 워커 N+1이 탭 A 제어 → 탭 A의 N 청크: marker로 찾은 N 캐시 hit (lifecycle.ts:226-246) + → ACTIVATED_RELOAD_REQUIRED 전 탭 통지 → 템플릿에는 구독자 없음 (page-controller.ts:293-299) + → 다음 배포 N+2 활성화 때 N 캐시 삭제(이전 캐시 1개만 보존) + → 탭 A가 아직 N이면 네트워크 → 404 → presentation 청크 복구(영역 08 범위) +롤백 N+1 → N: service-worker.js = N → 같은 digest 캐시에 재설치(기존 캐시 안 지움, static-assets.ts:159) + → waiting → 위와 같은 활성화 조건 +``` + +정리하면 옛 청크는 현재 워커 캐시 → (활성화 뒤) 이전 릴리스 캐시 → 네트워크 순서로 찾는다. 이 경로가 끊기는 곳은 두 군데다. 첫째, 활성화가 두 번 이상 지나간 탭이다. 둘째, 첫 방문이라 SW 제어를 받지 않는 탭이다(`RELOAD_TO_ENABLE`, `page-controller.ts:206-211`). 두 경우 모두 청크 오류 복구(다른 영역)가 받는다. 이 영역에 남는 문제는 두 가지다. 탭 하나 때문에 활성화가 거절되는 것(06-07)과, 활성화·reload UI가 조립되지 않은 것(06-05)이다. + +## 3. 확인된 강점 + +1. **설치 무결성과 사용자 데이터 차단.** 자산 수·크기 상한을 둔다(`service-worker-static-assets.ts:111-139`). 상태·타입·바이트 수·sha256을 모두 검증한다(`:291-325`). 전부 성공해야 캐시를 쓰고, 설치 기한과 늦게 끝난 작업의 정리도 있다(`:146-200`). 자산은 `credentials: "omit"`으로 받는다(`:272-277`). 그래서 인증된 응답이 SW 캐시에 들어갈 경로가 없다. +2. **가로채기 범위가 좁고 동기적으로 정해진다.** fetch 리스너는 `PWA_STATIC_ASSETS`일 때만 등록된다(`service-worker-entry.ts:94-111`). navigation, config, release manifest는 가로채지 않는다. 그래서 새 배포 뒤 HTML은 항상 새것이다. 등록은 `updateViaCache: "none"`을 쓴다(`service-worker-page-controller.ts:157-161`). `onFetch`의 저장소 예외는 모두 네트워크 폴백으로 끝난다(`service-worker-lifecycle.ts:296-307`). +3. **활성화는 핸드셰이크로만 일어난다.** install에서 `skipWaiting()`을 부르지 않고, `clients.claim()`도 없다(`service-worker-entry.ts:82-90`). nonce와 source 객체 동일성으로 응답을 짝짓는다(`service-worker-page-controller.ts:410-448`). `skipWaiting()` 실패는 거절로 처리한다(`service-worker-lifecycle.ts:357-362`). 다른 빌드 탭의 drain은 page와 worker를 함께 돌리는 seam 테스트로 확인된다(`tests/unit/service-worker-runtime.test.ts:1436`). +4. **남의 캐시와 등록을 지우지 않는다.** 캐시 이름은 정확히 일치해야 소유로 본다(`src/contracts/service-worker.ts:123-128`). 활성화 때 현재 캐시와 이전 1개를 남기고 오래된 것부터 지운다(`service-worker-lifecycle.ts:150-197`). 등록 소유권도 scope와 script가 정확히 일치해야 인정한다(`service-worker-removal.ts:33-63`). 제거는 `ACTIVE → REMOVE_REGISTRATION → PURGE_OWNED_RESOURCES → null` 단계로 진행하고 테스트도 있다(`tests/unit/service-worker-runtime.test.ts:348-460`). +5. **push payload를 신뢰하지 않는다.** 제목·본문·URL을 payload에서 받지 않고, 레지스트리에 고정된 문구만 쓴다(`inbound/push-event-adapter.ts:125-164`). payload는 exact key, 중복 JSON 멤버 거부, 3 KiB 상한, 만료·시계 차이를 검사한다(`push-codec.ts:45-125`). 클릭 경로는 레지스트리 path를 쓰고, same-origin이면서 계정 정보·해시가 없는 URL만 연다(`inbound/notification-click-adapter.ts:176-183`, `:382-394`, `notification-registry.ts:106-122`). +6. **로그아웃 해지 순서와 권한 상태를 구분한다.** 로그아웃은 fence를 먼저 회전해 REVOKED로 만들고, 그다음 backend revoke, native unsubscribe, 알림 정리 순서로 진행한다(`push-subscription-adapter.ts:391-466`). 6.6-7도 반영됐다. REVOKED나 UNASSOCIATED 상태에서 서버가 ABSENT를 돌려주면 등록하지 않고 해지한다(`:346-369`, 테스트 `web-push-subscription-adapter.test.ts:838-944`). 권한 결과는 `PUSH_DENIED` / `PUSH_PERMISSION_REQUIRED` / `PERMISSION_DISMISSED` / `PUSH_UNSUPPORTED` / `REGISTRATION_NOT_ACTIVE`로 나눠 보고한다(`:164-230`, `:527-543`). + +## 4. 발견 사항 + +### 06-01 알림 클릭 핸들러가 실제 브라우저의 `Notification`을 거부해 모든 클릭이 무시됨 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 1, 10, 15, 22 | +| 근거 | `src/adapters/web-push/service-worker-runtime.ts:268-281`의 `notificationClickEventFacade`가 `Object.hasOwn(value.notification, "data")`(`:276`)를 요구한다. WebIDL 속성은 인스턴스가 아니라 `Notification.prototype`의 getter다. Playwright로 Chromium·Firefox·WebKit에서 확인했다. 세 엔진 모두 `Notification.prototype`에 `data` getter가 있고, `Object.hasOwn(new Notification(...), "data") === false`, 인스턴스 own key는 0개다. 분리 worktree에서 prototype getter로 `data`를 노출하는 알림으로 `notificationclick`을 보냈더니 `close()`와 `waitUntil()`이 한 번도 불리지 않았다(테스트 실패). 검사를 `"data" in notification`으로 바꾸자 둘 다 호출됐다. 기존 테스트는 모두 own `data`를 가진 plain object를 쓴다(`tests/unit/web-push-worker-runtime.test.ts:282, 338, 383, 444, 707, 795, 821, 860, 908`). | +| 발생 조건 | WEB_PUSH를 조립한 워커에서 사용자가 알림을 클릭한다. 모든 엔진에서 일어난다. | +| 영향 | 클릭이 아무 동작도 하지 않는다. 알림이 닫히지 않고, 앱 창이 열리거나 포커스되지 않는다. Q-6.6-11의 "앱 루트 열기" fallback과 클릭 URL 검증도 실행되지 않는다. `web_push_click_dispatched` 관측 이벤트도 남지 않아 운영에서 발견하기 어렵다. | +| 심각도·우선순위 | Medium · P1. 현재 빌드는 WEB_PUSH를 거부하므로(`scripts/lib/service-worker-build-input.ts:58-62`) 기본 구성에는 영향이 없다. 하지만 조립하는 순간 클릭 기능이 100% 실패하고 테스트는 통과한다. 그래서 Web Push 채택 전에 반드시 고쳐야 한다. | +| 통제·증거 | M2(검사는 구현됐지만 조건이 틀림) · E2(단위 재현) + E3(3개 엔진 속성 확인) | +| 확실성과 남은 가정 | `NotificationEvent.notification`이 `Notification` 인스턴스라는 것은 스펙상 사실이다. 실제 푸시 수신부터 클릭까지의 end-to-end는 실행하지 않았다(푸시 서버 없음). | +| 최소 개선 방향 | own property 검사를 `"data" in value.notification`으로 바꾼다. 같은 파일의 `pushEventFacade`, `windowClientFacade`는 이미 prototype을 거쳐 접근하므로 문제없다. | +| 비용·부작용 | 한 줄 변경이다. `data`가 맞지 않는 객체는 여전히 `decodeNotificationClickData`에서 거부된다. | +| 완료 기준 | 테스트 fake가 실제 WebIDL 형태(prototype accessor)를 따르고, 그 fake로 클릭 테스트가 통과한다. | +| 검증 방법 | 단위 테스트는 class 기반 fake로 만든다. 브라우저 테스트는 SW 안에서 `registration.showNotification()` 뒤 `getNotifications()`로 얻은 실제 `Notification`을 click facade에 넣는 방식으로 짠다. | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음. 6.6-11 수정은 이 검사 뒤에 있어 실제 브라우저에서는 도달하지 않는다. | + +### 06-02 두 탭에서 enable/reconcile이 겹치면 공유 native 구독과 서버 연결이 지워지고 한 탭은 `PUSH_READY`를 보고함 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 12, 6, 10, 15 | +| 근거 | native 구독은 SW 등록당 하나라서 모든 탭이 공유한다. fence 레코드도 origin에 하나다(revision CAS). 그런데 코드는 CAS 패배와 "UNASSOCIATED인데 native가 있음"을 둘 다 자기가 남긴 잔여물로 보고 정리한다. **순서 1**: 탭 1이 enable 중이고 서버는 이미 탭 1의 등록을 commit했다. 두 탭 모두 rev 1로 prepare한다. 탭 2가 reconcile에서 ACTIVE commit을 받아 먼저 activate한다(rev 1→2). 탭 1의 activate는 `STALE_REVISION`이 되고, `activateCommit`의 보상(`push-subscription-adapter.ts:734-735`, `compensate` `:741-759`)이 서버 연결을 revoke하고 공유 native를 `unsubscribe()`한다. 재현 결과는 `enabled: PUSH_UNAVAILABLE(LOCAL_FENCE_UNSAFE)`, `reconciled: PUSH_READY`, fence `ACTIVE association_01`, `unsubscribe` 1회, 서버 연결 없음이다. **순서 2**: 탭 1의 register가 진행 중이라 서버는 아직 ABSENT다. 탭 2의 reconcile이 fence UNASSOCIATED + native 있음 + ABSENT를 보고 R-6.7 분기(`:346-369`)에서 native를 해지한다. 그 뒤 탭 1의 register가 끝나 ACTIVE로 commit된다. 재현 결과는 `reconciled: BACKEND_ASSOCIATION_MISSING`, `enabled: PUSH_READY`, `unsubscribe` 1회다. 두 순서 모두 fake repository(`tests/helpers/fake-push-control-repository.ts`)와 공유 fake native로 분리 worktree에서 재현했다. 기존 테스트에 탭 간 경합 사례는 없다. | +| 발생 조건 | 같은 브라우저 프로필의 두 탭 이상에서, 한 탭이 enable하는 동안 다른 탭이 부팅하며 reconcile한다. 또는 세션 복원으로 여러 탭이 동시에 부팅하면서 fence 전이가 필요한 경우(크래시 뒤 복구)다. 여러 탭은 지원 범위다(0.1). | +| 영향 | 사용자는 "켜짐"을 보지만 푸시가 오지 않는다. 다음 inspect나 reconcile에서야 `NATIVE_SUBSCRIPTION_MISSING`으로 드러나고, 다시 켜려면 사용자가 enable을 다시 해야 한다. 데이터 노출 경로는 없다. | +| 심각도·우선순위 | Medium · P2. 보안 피해는 없고 기능이 조용히 꺼진다. 특정 순서가 필요하고, 다음 조회에서 드러나 재활성화로 복구된다. | +| 통제·증거 | M2(CAS는 있지만 보상 범위가 과함) · E2(fake 단위 재현, 실제 브라우저 탭 경합은 미재현) | +| 확실성과 남은 가정 | 실행 순서는 테스트에서 게이트로 고정했다. 실제 발생 빈도는 네트워크 지연에 달려 있어 측정하지 않았다. | +| 최소 개선 방향 | 가장 작은 수단은 브라우저 기본 기능인 Web Locks다. `navigator.locks.request("web-push-control", …)`로 enable·reconcile·revoke를 origin 단위로 직렬화하면 두 순서가 모두 사라진다. 대안으로, 보상 전에 fence를 다시 읽어 같은 association이 ACTIVE로 commit돼 있으면 성공으로 수렴하게 할 수 있다. 또 native `unsubscribe`는 이 호출이 새로 만든 구독(`created`)일 때만 하도록 제한한다. | +| 비용·부작용 | Web Locks를 지원하지 않는 환경(구형 Safari)에서의 fallback 정책을 정해야 한다. 직렬화로 부팅 reconcile이 조금 늦어질 수 있다. | +| 완료 기준 | 두 탭 fake(같은 repository, 같은 native)로 두 순서를 모두 돌렸을 때, `PUSH_READY`를 보고한 탭이 있으면 native 구독과 서버 연결이 살아 있다. | +| 검증 방법 | 위 재현 테스트 2개를 repo 테스트로 옮긴다. | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음. 순서 2는 6.6-7 수정 분기가 원인이다. | + +### 06-03 잘못된 SW를 끄는 경로가 페이지 부팅에 의존하고, 운영 문서는 코드에 없는 kill switch를 안내함 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(문서와 코드 불일치) + 구조적 위험(워커 쪽 차단 경로 없음) | +| 관련 관점 | 28, 18, 9, 5, 26 | +| 근거 | 코드에 있는 끄는 경로는 둘이고, 둘 다 페이지 코드다. ① 런타임 설정 `CAPABILITY_OVERRIDES.SERVICE_WORKER: "DISABLED"` → `serviceWorkerDisabledCleanup`(`src/contracts/runtime-capabilities.ts:124-133`) → unregister(`service-worker-page-controller.ts:117-126`). ② `REMOVE_REGISTRATION` 릴리스(`:135-143`). 둘 다 config·release manifest·contract set 검증과 첫 React effect가 끝난 뒤에 실행된다(`src/bootstrap/optional-runtime-host.ts:97-98`, `src/bootstrap/runtime-application.tsx:21-23`). 워커 쪽 출구는 없다. install에서 `skipWaiting()`을 부르지 않고(`service-worker-entry.ts:82-85`), 워커는 런타임 설정을 읽지 않는다(`:35-80`이 전부 빌드 상수). `REMOVE_REGISTRATION`·`PURGE`·`null` 모드는 `service-worker.js`를 아예 만들지 않는다(`scripts/build-frontend.ts:58-67`). 그래서 브라우저 update 검사가 받을 대체 워커가 없다. 문서 불일치는 세 곳이다. `docs/operations/browser-file-storage-recovery.md:406`은 "waiting/client-drain controller는 아직 없다"고 적었지만 실제로는 `service-worker-page-controller.ts:365-478`에 있다. `:454-455`는 "fetch interception을 network-only kill switch로 전환", "new worker activation 중지"를 조치로 안내하지만 그런 스위치는 코드에 없다. `docs/operations/release-cache-rollback.md`에는 SW 롤백 단계가 없다(롤백 워커가 waiting에 머무는 조건, 실제로 쓸 수 있는 `SERVICE_WORKER: DISABLED`, 설계 문서 `…closed-deep-design.md:3411`의 `service-worker.js` `no-cache` 요구). `verify:hosting-headers`는 worker 파일이 있는지만 본다(`scripts/lib/hosting-probe.ts:10-27`). | +| 발생 조건 | SW `ACTIVE`로 운영하던 중 워커 결함 때문에 페이지가 부팅하지 못하는 경우(예: 다운스트림이 fetch·push 핸들러를 고친 경우). 또는 장애 대응 중 운영자가 문서를 따라 kill switch를 찾는 경우. | +| 영향 | 페이지가 부팅하는 한 `SERVICE_WORKER: DISABLED`로 재빌드 없이 unregister할 수 있다. 이 부분은 잘 돼 있다. 하지만 부팅을 막는 워커는 사용자가 모든 탭을 닫을 때까지 남는다. `REMOVE_REGISTRATION` 릴리스는 교체 워커를 만들지 않으므로 이 경우를 해결하지 못한다. 장애 중 운영자는 없는 스위치를 찾느라 시간을 쓴다. | +| 심각도·우선순위 | Medium · P2. 템플릿 워커의 fetch 경로는 방어적이다(`onFetch` 예외를 모두 null로 바꾸고 네트워크로 넘김, `service-worker-lifecycle.ts:296-307`). 템플릿 그대로일 때 부팅을 막는 경로는 찾지 못했다. 피해는 다운스트림이 워커를 고친 경우와 장애 대응 시간에 한정된다. | +| 통제·증거 | 페이지 쪽 M2 / 워커 쪽 M0 · E1 | +| 확실성과 남은 가정 | `service-worker.js`가 404일 때 엔진이 기존 등록을 유지하는지는 확인하지 않았다(스펙상 update 실패, 등록 유지로 읽힘). | +| 최소 개선 방향 | ① `browser-file-storage-recovery.md` §8을 코드에 맞게 고친다. 없는 스위치를 지우고, `CAPABILITY_OVERRIDES.SERVICE_WORKER=DISABLED`의 절차와 효과(다음 부팅 때 unregister, 캐시는 유지)를 적는다. ② 부팅을 막는 워커용 비상 경로를 하나 정한다. 예: install에서 `skipWaiting()`, activate에서 소유 캐시 삭제와 `registration.unregister()`를 하는 "자기 해제 워커"를 같은 URL에 산출하는 빌드 모드를 만들고, `REMOVE_REGISTRATION`도 이 워커를 내보내게 한다. ③ `release-cache-rollback.md`에 SW 선택 시의 롤백 단계를 추가한다. | +| 비용·부작용 | 문서 수정은 작다. 자기 해제 워커는 빌드 모드 1개와 e2e 1개가 필요하다. | +| 완료 기준 | 운영 문서의 모든 조치가 실제 코드 경로를 가리킨다. 부팅 불가 워커 시나리오를 e2e로 한 번 복구해 본다. | +| 검증 방법 | 두 빌드 e2e 헬퍼(`tests/e2e/support/service-worker-builds.ts`)로 "fetch가 실패하는 워커 A → 자기 해제 워커 B" 복구를 확인한다. | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 06-04 런타임 kill switch(`SERVICE_WORKER: DISABLED` → unregister) 분기가 어떤 테스트로도 검증되지 않음 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(검출력 공백) | +| 관련 관점 | 10, 28, 21 | +| 근거 | `service-worker-page-controller.ts:117-126`. 분리 worktree에서 이 분기 첫 줄에 `return DISABLED`를 넣어 unregister를 막았다. 그 상태로 `service-worker-runtime`, `optional-runtime-host`, `runtime-adapters`, `runtime-capability-snapshot`, `service-worker-web-push-remediation` 5파일 82개 테스트를 돌렸더니 모두 통과했다. 테스트는 `disabledCleanup: false`만 쓴다(`tests/unit/service-worker-runtime.test.ts:95`, `:1423`, `tests/unit/optional-runtime-host.test.ts:14`). `REMOVE_REGISTRATION` 모드는 테스트가 있다(`service-worker-runtime.test.ts:380-460`). | +| 발생 조건 | 이 분기나 `resolveRuntimeCapabilities`의 `serviceWorkerDisabledCleanup` 계산이 회귀하는 경우. | +| 영향 | 설정만으로 SW를 끄는 유일한 경로가 깨져도 CI가 모른다. 장애 때 설정을 바꿔도 등록이 남는다. | +| 심각도·우선순위 | Medium · P2. 복구 수단의 회귀를 검출하지 못한다. 기본 구성(SW off)에는 영향이 없다. | +| 통제·증거 | 구현 M2 / 검출 M0 · E2(변이 실험) | +| 확실성과 남은 가정 | 변이 1개로 확인했다. e2e에도 이 경로는 없다. | +| 최소 개선 방향 | controller 단위 테스트 1개를 추가한다. `disabledCleanup: true`일 때 `register` 0회, `getRegistration` 1회, 소유 등록이면 `unregister` 1회이고 결과는 `DISABLED`여야 한다. 소유가 아니면 `unregister` 0회이고 `INCOMPATIBLE`이어야 한다. `resolveRuntimeCapabilities`가 `serviceWorkerDisabledCleanup: true`를 계산하는지도 한 줄로 단언한다. | +| 비용·부작용 | 테스트 30줄 안팎이다. | +| 완료 기준 | 위 변이를 넣으면 테스트가 실패한다. | +| 검증 방법 | 같은 변이를 다시 적용해 실패하는지 본다. | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 06-05 SW를 켜도 관측·차단기·업데이트 알림이 조립되지 않아 설치 실패와 활성화 결과가 보이지 않음 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 7, 8, 18, 20, 19 | +| 근거 | `src/bootstrap/create-runtime-composition.ts:43-54`는 `observe`와 `blockers`를 넘기지 않는다. `optional-runtime-host.ts:148`의 `health()`는 repo 어디에서도 읽지 않는다. `onUpdateWaiting`·`onReloadRequired`·`requestActivation`을 쓰는 앱 코드가 없고, presentation에서 host에 접근할 방법도 없다. e2e 헬퍼는 이를 우회하려고 임시 복사본의 소스를 고친다(`tests/e2e/support/service-worker-builds.ts:31-35`, `:61-81`). 업데이트 설치가 실패하면 관측 이벤트도 남지 않는다(`watchForUpdates`는 installed만 알림, `service-worker-page-controller.ts:328-349`). SW를 켜는 방법은 `installed-runtime-capabilities.ts:28-29`의 한 줄("two-pass build")뿐이다. `docs/architecture/optional-adapter-recipes.md:94`는 "update/rollback UX가 없으면 설치하지 말 것"이라고 적었지만, 무엇을 붙여야 하는지(관측, blockers, 활성화 UI, reload 처리)는 없다. | +| 발생 조건 | 다운스트림이 SW 선택을 `ACTIVE`로 바꾼다. | +| 영향 | 첫 설치 실패(`INSTALL_FAILED`, 예: CDN이 content-type을 다르게 보냄)와 업데이트 설치 실패가 텔레메트리와 UI 어디에도 남지 않는다. blockers가 없어서, 다운스트림이 활성화 UI만 붙이면 편집 중인 탭도 drain에 동의한다. 기능 자체는 안전하게 실패한다. 활성화 요청이 없으면 모든 탭이 닫힐 때 교체된다. | +| 심각도·우선순위 | Medium · P2. 35.2의 "주요 진단 정보 부족"에 해당한다. 기본 구성에는 영향이 없다. | +| 통제·증거 | M1(계약에 hook이 있음) · E1 | +| 확실성과 남은 가정 | UI를 템플릿이 제공할지는 소유자 결정이다. 관측 연결의 부재는 코드로 확인했다. | +| 최소 개선 방향 | composition에서 `observe`를 텔레메트리 포트에 연결하고, `health()`를 기존 runtime capability snapshot에 싣는다. recipe 문서에 SW 켜기 체크리스트(관측, blockers, 활성화 UI, reload 처리)를 둔다. UI 자체는 다운스트림 몫으로 남겨도 된다. | +| 비용·부작용 | 연결 코드 수십 줄이다. 이벤트 이름과 수집 정책을 정해야 한다. | +| 완료 기준 | `ACTIVE`로 켠 구성에서 설치 실패가 텔레메트리 이벤트 1건으로 남는 테스트가 있다. | +| 검증 방법 | `createOptionalRuntimeHost` 단위 테스트에서 fake host의 설치 실패를 주입한다. | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 6.6-3의 hook 추가는 반영됨. 앱 쪽 조립은 이번에 새로 제기한다. | + +### 06-06 로그아웃 없이 계정이 바뀌면 새 계정이 push fence를 넘길 방법이 없음 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 15, 17, 11 | +| 근거 | fence `prepare`는 저장된 authority와 다르면 `STALE_AUTHORITY`로 실패한다(`push-association-fence-store.ts:205-214`). `enable`과 `reconcile`은 이 실패를 그대로 반환한다(`push-subscription-adapter.ts:232-237`, `:298-303`). fence를 넘기는 유일한 API인 `revoke`는 저장된 authority와 정확히 같은 `previousAuthority`를 요구한다(`:402-410`). 그런데 포트(`src/application/ports/out/web-push-control.ts:7-30`)에는 저장된 authority를 읽는 방법이 없다. 설계 문서(`realtime-events-web-push-and-bounded-polling.md:1292-1316`)는 정상 로그아웃 순서만 정의한다. 테스트도 정상 rotate만 다룬다. | +| 발생 조건 | Web Push를 조립한 구성에서, 세션 만료·쿠키 삭제·로그아웃 중 크래시 등으로 revoke 없이 계정이 A에서 B로 바뀐다. | +| 영향 | B의 enable과 reconcile이 계속 `STALE_AUTHORITY`로 실패하고, inspect는 `SESSION_AUTHORITY_CHANGED`를 반환한다. fence는 A의 ACTIVE로 남아서 워커가 A 연결의 push를 계속 표시한다. 이를 막는 것은 서버의 send-time 인가와 짧은 TTL뿐이다(설계 `:1300-1316`). 알림 문구는 계정 중립이고 클릭 뒤 조회는 B 세션으로 재인가되므로, 데이터 노출 경로는 찾지 못했다. | +| 심각도·우선순위 | Medium · P2. 막다른 상태가 되고 이전 계정의 알림이 계속 표시된다. 기능 조립이 전제다. | +| 통제·증거 | M1(정상 경로만 명시) · E1 | +| 확실성과 남은 가정 | 다운스트림 세션 소유자가 이전 authority를 따로 보관한다면 우회할 수 있다. 하지만 그 책임이 포트에도 문서에도 적혀 있지 않다. | +| 최소 개선 방향 | 포트에 저장된 authority와 무관하게 fence를 회전해 REVOKED로 만들고 captured association을 revoke하는 명시적 연산을 추가한다(예: `revokeForeign({ nextAuthority })`). 서버 TTL과 send-time 인가를 채택 완료 기준으로 문서에 둔다. | +| 비용·부작용 | 포트에 연산 1개가 추가된다(추가만, 파괴적 변경 없음). | +| 완료 기준 | A의 ACTIVE fence가 남은 상태에서 B가 한 번의 호출로 fence REVOKED, 연결 revoke, 새 opt-in 가능 상태가 되는 테스트가 있다. | +| 검증 방법 | `web-push-subscription-adapter.test.ts`에 A→B 비정상 전환 사례를 추가한다. | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 06-07 응답하지 않는 창 하나가 활성화를 막고, 그 시간 초과가 "dirty 탭"으로 보고됨 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(실패 분류) + 구조적 위험(활성화 가용성) | +| 관련 관점 | 12, 6, 24, 18 | +| 근거 | 워커는 `includeUncontrolled: true`로 scope 안의 모든 창을 drain 대상으로 잡는다(`service-worker-lifecycle.ts:341-348`). 응답은 page controller의 message listener만 보낸다(`service-worker-page-controller.ts:267-291`). 응답하지 않는 창은 네 종류다. 앱이 아닌 문서(예: `/config.json`을 연 탭), `start()`가 register를 기다리는 중인 탭(`registration`이 null이라 source 검사 실패, `:277-279`, `:310-320`), stop된 탭, 브라우저가 얼린 백그라운드 탭이다. 워커의 30초 시간 초과(`lifecycle.ts:403-407`)와 `skipWaiting()` 실패(`:357-362`)는 모두 `ACTIVATE_REJECTED`로 통지된다(`:350`, `:360`). 요청 탭은 이를 `BLOCKED_DIRTY_CLIENT`로 바꾼다(`page-controller.ts:441-452`). 페이지 자신의 `CLIENT_DRAIN_TIMEOUT`(`:457-460`)은 워커가 35초 동안 아무 답도 없을 때만 나오므로, 워커가 살아 있으면 도달하지 않는다. | +| 발생 조건 | 다운스트림이 활성화 UI를 붙였고, 위 네 종류의 창 중 하나라도 열려 있다. | +| 영향 | 사용자는 "저장하지 않은 변경이 있는 탭"이라는 잘못된 이유를 보고, 그런 탭을 찾지 못한다. 교체는 모든 탭이 닫힐 때로 미뤄진다(안전한 쪽으로 실패). | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M2 · E1 | +| 확실성과 남은 가정 | 얼린 탭의 메시지 보류는 브라우저 동작이다. 실제 브라우저 재현은 하지 않았다. | +| 최소 개선 방향 | 워커가 거절 이유(명시 거절 / 시간 초과 / commit 실패)를 구분해 보내고, 페이지는 이를 `CLIENT_DRAIN_TIMEOUT`·`FAILED`로 매핑한다. 워커 교체의 영향을 받지 않는 제어 밖 창을 drain 대상에서 뺄지 검토한다. | +| 비용·부작용 | 프로토콜 메시지에 필드나 kind가 1개 추가된다(V1 호환 확인 필요, SW-10과 연결). | +| 완료 기준 | 응답 없는 창 1개가 있는 seam 테스트에서 결과가 `CLIENT_DRAIN_TIMEOUT`이다. | +| 검증 방법 | `tests/unit/service-worker-runtime.test.ts`의 `activationSeam`에 listener 없는 client를 추가한다. | +| 담당·기한·상태 | 미정 · 미정 · 일부 미해결 | +| 직전 리뷰 | 6.6-2 시나리오 중 "얼린 백그라운드 탭" 부분이 미해결이다(R-6.2는 빌드 필터만 고침). 6.6-10b의 여유분 추가로 페이지 시간 초과가 사실상 도달 불가가 됐다. | + +### 06-08 해시 파일명 판별이 same-origin API·다운로드 GET까지 가로챔 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(주석과 동작 불일치) | +| 관련 관점 | 5, 14, 24 | +| 근거 | `HASHED_STATIC_ASSET_NAME = /-[A-Za-z0-9_-]{8,}\.[a-z0-9]+$/`(`src/contracts/service-worker.ts:110`)을 same-origin 경로 전체에 적용한다(`service-worker-static-assets.ts:54-56`, `:60-70`). node로 `classifyFetch`를 실행했더니 `/api/v1/user-profiles.json`, `/api/reports/monthly-summary2026.csv`, `/media/onboarding-video-final.mp4`, `/downloads/release-notes-20260925.pdf`가 모두 `PREVIOUS_RELEASE_FALLBACK`으로 분류됐다. 반면 주석은 "API calls … left to the browser untouched"라고 적었다(`service-worker-entry.ts:102-105`, `service-worker-lifecycle.ts:263-268`). | +| 발생 조건 | SW `ACTIVE` + same-origin API/BFF 또는 다운로드 경로에 `-영숫자8자 이상.확장자` 형태 이름이 있다. | +| 영향 | 이런 GET마다 워커 기동, `caches.keys()`, 이전 캐시 marker 읽기(`lifecycle.ts:232-235`, `:200-219`)를 거친 뒤 `fetch(request)`로 다시 보낸다. 이전 캐시에는 검증된 자산만 있어서 잘못된 응답이 나갈 경로는 없다. 지연이 늘고, "SW는 API를 건드리지 않는다"는 가정이 깨진다. | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M2 · E2(node 실행) | +| 확실성과 남은 가정 | 지연 크기는 측정하지 않았다. | +| 최소 개선 방향 | fallback을 빌드 자산 디렉터리(`/assets/`) 아래로 한정한다. 또는 이전 캐시에 실제로 있는 URL만 가로챈다. | +| 비용·부작용 | 조건 1개 추가다. base path 배포를 고려해야 한다. | +| 완료 기준 | 위 URL 4개가 `NETWORK_PASSTHROUGH`로 분류되는 단위 테스트가 있다. | +| 검증 방법 | `classifyFetch` 표 테스트를 추가한다. | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | Q-6.6-6b 결정("해시 파일명")의 구현 범위 문제. 새 항목이다. | + +### 06-09 거절된 알림 클릭의 fallback이 router base path를 무시하고 origin 루트를 엶 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 19, 15, 3 | +| 근거 | `inbound/notification-click-adapter.ts:269`가 `${origin}/`을 연다. SW scope와 앱은 `routerBasePath`에 있다(`service-worker-page-controller.ts:54-57`, `service-worker-removal.ts:65-76`). 설계 문서도 `/`로 적었다. | +| 발생 조건 | base path 배포(예: `/app/`)에서 만료되거나 fence가 맞지 않는 클릭이 들어온다. 06-01이 고쳐진 뒤에만 도달한다. | +| 영향 | 앱 밖 페이지(다른 앱이나 404)가 열린다. | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M2 · E1 | +| 확실성과 남은 가정 | 정적 확인이다. | +| 최소 개선 방향 | click adapter에 앱 루트 URL을 주입한다(워커에서는 `registration.scope`를 쓸 수 있다). | +| 비용·부작용 | 의존성 1개 추가 | +| 완료 기준 | base path가 `/app/`일 때 거절된 클릭이 `/app/`을 여는 테스트가 있다. | +| 검증 방법 | `web-push-worker-runtime.test.ts` "a rejected click opens the app root"에 사례를 추가한다. | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 6.6-11 수정의 부수 문제 | + +### 06-10 SW 빌드가 배포 프로필이 아니라 로컬 `public/config.json`에서 release manifest URL을 읽음 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험(설정 출처 불일치) | +| 관련 관점 | 19, 9 | +| 근거 | `vite.service-worker.config.ts:51-53`이 `public/config.json`을 읽는다. 반면 배포용 설정은 `scripts/build-frontend.ts:55-56` → `scripts/generate-runtime-config.ts:26`이 만드는 `dist/config.json`이다. 지금은 4개 프로필의 `RELEASE_MANIFEST_URL`이 같고(`config/runtime/*.json`) 덮어쓰기 대상도 아니라서(`generate-runtime-config.ts:32-35`) 결과가 같다. 또 `build-frontend.ts:25-28` 주석은 "Service Worker hashes the emitted config.json"이라고 적었지만, generator는 `config.json`을 제외한다(`scripts/generate-service-worker-assets.ts:33-39`). | +| 발생 조건 | 어떤 프로필이 다른 `RELEASE_MANIFEST_URL`을 쓰기 시작한다. | +| 영향 | 워커의 NETWORK_ONLY 판정 대상이 어긋난다. 다만 해시 이름이 아니면 어차피 가로채지 않아 실제 차이는 작다. | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M2 · E1 | +| 확실성과 남은 가정 | 현재 영향은 없다. | +| 최소 개선 방향 | `dist/config.json`을 읽거나, `resolveServiceWorkerBuildInput`에서 두 값이 일치하는지 검사한다. 주석도 고친다. | +| 비용·부작용 | 수 줄 | +| 완료 기준 | 프로필과 `public/config.json`의 값이 다르면 빌드가 실패하거나 프로필 값을 쓴다. | +| 검증 방법 | `tests/unit/service-worker-build-input.test.ts`에 사례를 추가한다. | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +## 5. 28개 관점 판정 (36.2) + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +|---|---|---|---|---|---| +| 1 | 코드 성숙도 | 적용 | M2 / M2 | E1·E2 | 부분 충족: 메시지·payload·manifest 검증은 exact. 클릭 facade가 실제 이벤트를 거부함(06-01) | +| 2 | 구조적 성숙도 | 적용: worker/page realm 분리 | M3 / M3 | E1 | 충족: `tsconfig.service-worker.json`이 page realm 파일을 제외하고, entry는 web-push를 import하지 않음(`service-worker-entry.ts:144-158`). 전체 의존성 게이트는 영역 01 | +| 3 | 변경 용이성 | 적용: WEB_PUSH 조립 | M1 / M1 | E1 | 부분 충족: 조립 절차가 entry 주석에만 있고 build-input이 거부함. base path 누락(06-09) | +| 4 | 인지 부하 | 적용 | 해당 없음 | E1 | 부분 충족: 계약 주석은 충실. 활성화 규약이 page·worker 두 파일(630·724줄)에 나뉘고 subscription adapter가 1115줄 | +| 5 | 위험 가시성 | 적용 | M2 / M2 | E1 | 부분 충족: 결과 타입은 명확. "API는 건드리지 않음"(06-08), 없는 kill switch 문서(06-03) | +| 6 | 실패 성숙도 | 적용: 구독 실패·권한 거부 구분 | M2 / M2 | E1·E2 | 부분 충족: 권한 거부·dismiss·미지원·등록 비활성을 구분하고, 설치 실패 코드는 11종. 활성화 시간 초과가 dirty로 보고됨(06-07). register 재시도마다 새 멱등 키를 씀(`push-subscription-adapter.ts:680`), 서버 upsert가 전제 | +| 7 | 운영 성숙도 | 적용 | M2 / M1 | E1 | 미충족: observe·health 미연결(06-05) | +| 8 | 디버깅 가능성 | 적용 | M2 / M1 | E1 | 부분 충족: 관측 hook과 reason 코드는 풍부하지만 조립되지 않음(06-05) | +| 9 | 유지보수 성숙도 | 적용 | M1 / M1 | E1 | 부분 충족: 운영 문서가 현재 코드와 다름(06-03). `void SERVICE_WORKER_BOUNDS.retainedPreviousCaches`(`service-worker-lifecycle.ts:167`)는 여전히 아무 일도 하지 않음. 빌드 주석 불일치(06-10) | +| 10 | 테스트 성숙도 | 적용 | M3 / M3(부분) | E2(126 pass) | 부분 충족: 경계·경합 단위 테스트가 많음. fake가 WebIDL 형태와 달라 06-01을 못 잡음, kill switch 변이 생존(06-04), 탭 간 push 경합 없음(06-02), e2e는 단일 탭 업데이트·fallback만 다룸 | +| 11 | 데이터 성숙도 | 적용: SW 캐시 사용자 범위·삭제 | M2 / M2 | E1 | 충족: 캐시는 `credentials: "omit"`으로 받은 해시 공개 자산만 담고, 현재+이전 1개를 보존하며, PURGE는 소유 캐시만 지움. push fence에는 계정 ID와 endpoint가 없음(`contracts/web-push.ts:45-57`). 로그아웃 뒤 OS 알림 잔존은 문서화됨 | +| 12 | 동시성 성숙도 | 적용: 여러 탭·SW 메시지 | M2 / M2 | E2 | 미충족: push 탭 간 경합(06-02). SW 활성화는 single-flight·nonce·source 검증으로 양호, 응답 없는 창 문제 있음(06-07) | +| 13 | 확장성 | 적용: 자산 수 증가 | M2 / M2 | E1 | 부분 충족: 256개·5 MiB 상한을 넘으면 빌드에서 거부(`generate-service-worker-assets.ts:60-86`). 기능 증가 시 도달 시점은 미측정 | +| 14 | 성능 성숙도 | 적용 | M2 / M2 | E1·E2 | 부분 충족: fetch 리스너는 조건부로 등록되고 해시 GET만 가로챔. 과대 가로채기(06-08), miss마다 marker를 읽음 | +| 15 | 보안 성숙도 | 적용: payload 신뢰, 구독-사용자 연결, 해지, 클릭 URL | M2 / M2 | E1·E2 | 부분 충족: payload, 클릭 URL, 로그아웃 순서, R-6.7은 양호. 비정상 계정 전환 시 막다른 상태(06-06) | +| 16 | 의존성 성숙도 | 적용 제외: 이 영역에 런타임 외부 패키지가 없음(빌드 도구는 영역 외) | 해당 없음 | 해당 없음 | 적용 제외 | +| 17 | API / Contract | 적용: SW 메시지 V1, push 포트 | M2 / M2 | E1 | 부분 충족: exact key와 버전 불일치 시 fail-closed. V2 이행은 SW-10으로 미룸(`adapter-remediation-ledger.md:151`). push 포트에 저장 authority 조회가 없음(06-06) | +| 18 | 배포 성숙도 | 적용: 32절 추적(2.1절) | M2 / M2 | E1(e2e 미실행) | 부분 충족: 옛 청크는 현재 캐시→이전 캐시→네트워크 순서로 찾음. 활성화·reload UI 미조립(06-05), 응답 없는 창(06-07) | +| 19 | 설정 성숙도 | 적용: SW 관련 설정 검증 | M3 / M3 | E2 | 부분 충족: build-input이 모르는 handler·중복·WEB_PUSH·stale identity를 빌드에서 거부(`service-worker-build-input.ts:36-80`). 설정 출처 불일치(06-10), `service-worker.js` Cache-Control 미검사(06-03) | +| 20 | 개발자 경험 | 적용: SW 켜기 | M1 / M1 | E1 | 부분 충족: `ACTIVE`로 바꾸는 한 줄 외에 조립 안내가 없음(06-05) | +| 21 | Guardrail 성숙도 | 적용 | M3 / M3 | E1·E2 | 부분 충족: build-input 거부, hosting-probe의 worker 파일 검사, tsconfig realm 분리는 동작. kill switch 회귀는 검출하지 못함(06-04) | +| 22 | 추상화 성숙도 | 적용: structural facade | M2 / M2 | E1·E2 | 부분 충족: facade 덕분에 테스트할 수 있지만, 실제 WebIDL과의 차이를 가림(06-01) | +| 23 | 일관성 | 적용 | 해당 없음 | E1 | 부분 충족: `validateActiveFence` 두 벌(`push-event-adapter.ts:196-214`, `notification-click-adapter.ts:343-367`), abort race helper 두 벌(`service-worker-static-assets.ts:365-380`, `notification-click-adapter.ts:66-81`). 현재 동작 차이는 없음 | +| 24 | 네이밍 / 의미 | 적용 | 해당 없음 | E1 | 부분 충족: `CLIENT_DRAINED`는 "지금 차단기가 없음"만 뜻하고 입장을 닫지 않음. `BLOCKED_DIRTY_CLIENT`에 시간 초과가 섞임(06-07) | +| 25 | 조직 확장성 | 적용 제외: 0.1 전제(1인 관리), 구조적 준비는 다른 영역 | 해당 없음 | 해당 없음 | 적용 제외 | +| 26 | Ownership | 적용: SW 장애 대응 | M1 / M1 | E0 | 미검증: quarantine owner(`frontend-platform`) 표기는 있으나 SW 장애 대응 절차가 코드와 맞지 않음(06-03) | +| 27 | 삭제 가능성 | 적용 | M3 / M3 | E1·E2 | 부분 충족: 단계적 제거 모드를 구현하고 테스트함. web-push는 entry import가 없어 파일 삭제로 제거 가능하다고 주장함. 삭제 스크립트는 미실행 | +| 28 | 회복 가능성 | 적용: kill switch·unregister·롤백 | 페이지 M2 / 워커 M0 | E1·E2 | 미충족: 워커 쪽 비상 경로 없음, 문서 불일치(06-03), 런타임 kill switch 검증 없음(06-04) | + +## 6. 미검증 목록 + +| 항목 | 이유 | 확인하려면 | +|---|---|---| +| e2e `tests/e2e/service-worker-update.spec.ts` | 지시서상 vitest만 실행 가능. 두 빌드 업데이트와 이전 캐시 fallback의 브라우저 증거를 이번에 새로 얻지 않음 | 오케스트레이터 게이트나 CI에서 Playwright 실행 | +| 여러 탭 활성화(다른 빌드, 얼린 탭, 앱이 아닌 창) | 실제 브라우저 필요(06-07) | e2e 헬퍼로 두 번째 page를 열고, 하나는 `/config.json`에 둔 채 `requestActivation()` | +| 롤백 N+1 → N 재설치와 활성화, `REMOVE_REGISTRATION` 뒤 404 update 시 등록 유지 | 여러 릴리스 호스팅 필요(06-03) | e2e 서버에서 dist-b → dist-a 순서로 서빙하고, worker 파일 없는 dist도 서빙 | +| Web Push end-to-end(실제 푸시 서비스, VAPID, 클릭) | 푸시 서버 없음. 06-01은 속성 확인과 단위 재현, 06-02는 fake 단위 재현까지만 함 | 로컬 web-push 서버와 Chromium으로 push → 클릭 | +| web-push 삭제 가능성 | `scripts/test-realtime-runtime-removal.ts` 미실행 | 스크립트를 읽고 격리 환경에서 실행 | +| `check:types`(service-worker 프로젝트), `check:architecture` | 전체 게이트는 오케스트레이터 담당 | 게이트 결과 참조 | +| 자산 상한(256개·5 MiB) 도달 시점 | 기능 수 증가 실험 없음 | extreme-scale fixture 빌드에서 `service worker assets:` 출력 확인 | diff --git a/docs/reviews/2026-09-25-maturity-review/07-contracts.md b/docs/reviews/2026-09-25-maturity-review/07-contracts.md new file mode 100644 index 00000000..bd7f04fc --- /dev/null +++ b/docs/reviews/2026-09-25-maturity-review/07-contracts.md @@ -0,0 +1,292 @@ +# contracts (공유 어휘·외부 계약) 성숙도 리뷰 + +> 검토일: 2026-09-25 · 기준: `main` / `4626b73` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 범위: `src/contracts/` 40파일 약 8.7k줄, `schemas/`, `config/contracts/` 4파일, `config/compatibility/fixtures.json`, `docs/contracts/compatibility.md`, 이 영역을 검증하는 테스트(`tests/unit` 계약·매퍼·경계 관련, `tests/runtime-schema`, `tests/contract`, `tests/fixtures/typecheck`의 계약 관련 negative fixture) +> 영역 판정(35.8): **조건부 사용 가능** — 외부 입력 검증과 레지스트리 조립은 그대로 써도 된다. 다만 (1) 오류 종류의 화면 문구 연결, (2) "필드 추가는 안전"이라는 호환성 규칙과 FE-GATE-014, (3) 참조 기능의 V2/V3 이중 선언은 다운스트림이 믿고 복제하면 안 된다. 사용 조건은 1절 참조. + +## 1. 결론 + +- **외부 입력 경계는 막혀 있다.** 런타임 설정·릴리스 매니페스트·realtime envelope·HTTP 응답은 zod 또는 exact decode로 검증하고, 실패하면 fail-closed(모르면 거부)로 끝난다. 직전 리뷰 6.7-1~6.7-12는 모두 반영됐다. 그중 6건(6.7-1·2·3·4·5·10)은 코드를 되돌리는 변이 실험에서 테스트가 실패하는 것까지 확인했다. +- **고쳐야 할 것 1 — 오류 문구가 비어 있다 (07-01).** `ERROR_REGISTRY` 38종 중 22종은 문구 카탈로그에 키가 없다. 조회 실패 화면에 "요청한 문구를 표시할 수 없습니다."가 나온다. 해당 종류는 `SCHEMA_MISMATCH`, `CONFLICT`, `VALIDATION_REJECTED` 등이다. 이 연결을 검사하는 테스트·타입·거버넌스가 없다. +- **고쳐야 할 것 2 — 호환성 규칙이 실제 파서 동작과 다르다 (07-02).** 문서와 분류기는 선택 필드 추가를 "additive(안전)"로 본다. 그런데 설정 V2, HTTP V2 envelope, realtime envelope는 모르는 키를 거부한다. 타입·enum·nullable 변경은 분류기가 `"none"`으로 답한다. CI의 `config-compatibility` 게이트(FE-GATE-014)는 손으로 쓴 fixture 8개로 분류기 자체만 검사하고, 실제 스키마는 보지 않는다. +- **고쳐야 할 것 3 — 같은 HTTP 오퍼레이션이 두 벌이다 (07-03).** 참조 기능은 오퍼레이션 3개를 V2 행과 V3 descriptor로 각각 선언한다. 계약 거버넌스(FE-REG-API)는 실행되지 않는 V2 벌만 감시한다. V3의 path·응답 상한을 바꿔도 `check-registries`는 PASS다. +- **나머지는 Low다.** 연결되지 않은 레지스트리 필드(07-04), 위반 3개 중 1개만 고정하는 negative fixture(07-05), `invokeValidator`의 "절대 throw하지 않음" 약속의 구멍(07-06), 폐기 표시 부재(07-07). +- **미검증:** 실제 브라우저에서 구버전 탭과 신버전 서버·설정이 공존하는 시나리오는 실행하지 않았다. 파서 단위 실행으로만 확인했다. browser-rpc의 미등록 gRPC 코드가 command의 효과 확실성(effect certainty)에 주는 영향은 영역 03 범위다. + +## 2. 범위와 방법 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 | `clean-architecture-frontend-template` `main` `4626b73`. 워킹트리는 리뷰 문서만 미커밋이다 | +| 목적·실행 구성 | 프론트엔드 템플릿. 브라우저 SPA와 정적 호스팅, 여러 탭 동시 실행을 지원한다. SSR은 없다 | +| 읽은 코드 | `src/contracts/` 전부. 핵심 파일(`errors.ts`, `external-contract-runtime.ts`, `compatibility.ts`, `schema-registry.ts`, `boundary-mapper.ts`, `api-operations.ts`, `rest-profiles.ts`, `release-artifacts.ts`, `contract-set.ts`, `release-tokens.ts`, `realtime-events.ts`, `realtime-streams.ts`, `telemetry.ts`, `diagnostics.ts`, `mutation-intent.ts`, `env.ts`, `exact-snapshot.ts`, `read-only-registry.ts`, `storage-keys.ts`, `offline-command.ts`)는 줄 단위로 읽었다. 나머지는 export 목록과 경계 처리만 읽었다. 추적을 위해 영역 밖 소비자도 일부 읽었다: `adapters/http/client.ts`, `adapters/http/schema-registry.ts`, `adapters/http/feature-http-binding.ts`, `adapters/realtime/event-codec.ts`, `adapters/browser-rpc/browser-rpc-runtime.ts`, `presentation/i18n/*`, `presentation/components/async-surface.tsx`, 참조 기능 계약, `scripts/check-registries.ts`, `scripts/lib/registry-compatibility.ts`, `scripts/check-compatibility.ts`, `scripts/lib/ci-step-result.ts`, `config/ci/gates.json` | +| 실행한 테스트 | `node scripts/run-vitest.ts run` 로 계약 관련 20파일 실행 → **244/244 통과**. 여기에 `tests/runtime-schema` 전체가 포함된다. `tests/contract`와 참조 기능 계약 테스트 7파일 → **33/33 통과**. negative fixture 8개(`failure-kind`, `result-narrowing`, `http-operation-id`, `http-wire-mapper`, `diagnostics-port`, `reference-operation`, `http-route-id`, `http-operation-input`)를 `tsc -p`로 실행했고, 모두 의도한 줄에서 의도한 오류 코드가 났다 | +| 실험 | scratchpad의 분리 worktree(`git worktree add --detach`)에서 변이 16건을 넣고 관련 테스트를 돌렸다(아래 표). 실험 후 worktree는 제거했다. repo 원본에서는 노드 스크립트로 파서·분류기·문구 해석을 직접 호출했다 | +| 확인하지 못한 범위 | 전체 게이트(`check:types`, `check:architecture`, `test:unit` 전체)는 오케스트레이터 몫이라 실행하지 않았다. `browser-rpc.ts`(947줄) 내부 검증식, `query-keys.ts`, `server-state.ts`, `service-worker*.ts`, `web-worker.ts`, `runtime-capabilities.ts`, `product-features.ts`는 줄 단위로 읽지 않았다. 실제 브라우저·서버 공존 실험은 하지 않았다 | +| 직전 리뷰와 비교 | 6.7-1~12를 현재 코드에서 다시 확인했다. 6.7-8(검증기 프로토콜·`MappingResult` 두 모양)은 소유자 결정 D-15에 따라 별칭으로 남아 있고, 이 리뷰에서 결함으로 다시 세지 않았다(관점 23에만 기록) | + +### 2.1 변이 실험 결과 (관점 10·21) + +"변이 실험"은 규칙 하나를 일부러 망가뜨린 뒤 테스트가 실패하는지 보는 방법이다. 실패하면 테스트가 그 규칙을 지키고 있다는 뜻이다(killed). 통과하면 그 규칙은 테스트가 지키지 않는다는 뜻이다(survived). + +| ID | 망가뜨린 규칙 | 결과 | +|---|---|---| +| M1 | `createFailure`: `effect: MAYBE_APPLIED`면 `retryable=false` (`errors.ts:292-296`) | **survived** (19파일 279건 통과). 07-04 참조 | +| M1b | `withFailureEffect`: MAYBE_APPLIED면 `retryable=false` | killed (4건 실패) | +| M3 | 멱등 키 문법을 수정 전으로 되돌림 (6.7-1) | killed | +| M4 | 매니페스트 URL의 origin·pathname 재확인 제거 (6.7-3) | killed (4건) | +| M6 | exact decode의 non-enumerable 거부 제거 | killed (3건) | +| M7 | 검증 이슈 상한 50 → 5000 | killed | +| M8 | `FEATURE_OVERRIDES` 키 금지어 면제 제거 (6.7-2) | killed | +| M9 | REST V2 COMMAND+GET 거부 제거 (6.7-4) | killed (4건) | +| M10 | `isVersionCompatible`의 minor 비교 제거(항상 호환) | **survived** (10파일 77건 통과). 런타임 minor가 더 낮은 경우를 검사하는 테스트가 없다 | +| M11 | 텔레메트리 `operation_id`를 대문자 전용 문법으로 되돌림 (6.7-5) | killed (3건) | +| M12 | realtime 타임스탬프의 달력 검사 제거 | killed (2건) | +| M13 | V3 조립의 "retryBudget>0 + NEVER" 모순 거부 제거 | survived. 실행기가 `http-retry-lifecycle.ts:25`에서 NEVER를 다시 막으므로 실제 영향은 작다 | +| M14 | contract-set 패키지별 digest 비교 제거 | survived. 뒤이은 집합 digest 비교가 같은 불일치를 잡으므로 동작이 같다(equivalent mutation) | +| M16 | `kindForStatus` 409 → CONFLICT 제거 | killed (2건) | +| M18 | 스키마 레지스트리 이슈 상한 투영 제거 | killed | +| M19 | 배포 승인에서 `.internal` 호스트 거부 제거 (6.7-10) | killed | + +결과: 16건 중 12건 killed. survived 4건 중 의미가 있는 것은 M1과 M10이다. M13은 실행기에 이중 방어가 있고, M14는 동작이 같은 변이다. + +### 2.2 직접 호출로 확인한 동작 + +```text +config as-is PASS +config + NEW_OPTIONAL_KEY REJECT unrecognized_keys +config CONFIG_SCHEMA_VERSION "2.1" REJECT invalid_union +config CAPABILITY_OVERRIDES { NEW_CAP } REJECT unrecognized_keys +isVersionCompatible("2.0", "2.1") true +classify(선택 필드 추가) additive +classify(id: string → number) none +classify(enum [A,B] → [A]) none +classify(string → string|null) none +HTTP V2 envelope + links success=false +HTTP V2 failure envelope + error.target success=false +resolveMessage(ko, error.schema_mismatch) 요청한 문구를 표시할 수 없습니다. +invokeValidator(issues: 5) TypeError 발생 +invokeValidator(success: "no") VALID +``` + +### 2.3 변경 시나리오 추적: 오류 코드 하나 추가 (관점 3) + +**A. 서버가 새 오류 코드를 보낸다 (프론트 코드는 그대로).** 예: 403 응답에 `error.code: "QUOTA_EXHAUSTED"`. + +```text +서버 응답 + → HTTP V2: envelope 검증(strict) → kind = kindForStatus(403) = FORBIDDEN, code는 정규식을 통과하면 보존 + (client.ts:995-1016). envelope의 error 객체에 모르는 필드가 하나라도 있으면 + envelope 검증 실패 → code = "HTTP_FAILURE"로 대체 + → HTTP V3: 401/403/429는 PROBLEM 매핑 전에 고정 분류(feature-http-binding.ts:341-356) → 서버 code 버림 + 그 밖의 상태는 기능의 mapProblem 결과, 없으면 kindForStatus + code "CONTRACT_PROBLEM" + → browser-rpc: transport 오류 코드 어휘가 닫혀 있음(browser-rpc.ts:76-93). 등록되지 않은 코드는 + 프로토콜 위반 → API_CONTRACT_MISMATCH("API 계약 버전이 현재 화면과 일치하지 않습니다") + → 화면: kind 단위 문구만 있음. code는 표시하지 않음 + → 관측: telemetry·diagnostics에는 error_kind만 남음. 서버 code는 남지 않음(telemetry.ts:4-21) +``` + +구버전 소비자는 새 코드를 "견딘다". 기존 kind로 안전하게 떨어진다. 대신 의미가 뭉개지고, 관측으로도 새 코드가 늘었는지 알 수 없다. RPC만 예외다. VD-27 설계표에 있는 `UNKNOWN`, `OUT_OF_RANGE`도 어휘에 없어서 계약 위반으로 분류된다. + +**B. 그 코드를 별도 문구·행동으로 보여 준다 (새 FailureKind 추가).** + +| # | 파일 | 바꾸는 정책 | 빠뜨리면 검출? | +|---|---|---|---| +| 1 | `src/contracts/errors.ts` ERROR_REGISTRY 행 | 기본 재시도 여부, action, severity, telemetryEvent (4개. 뒤 2개는 소비자 없음, 07-04) | kind 오타는 타입이 잡음 | +| 2 | `src/presentation/i18n/catalog.ts` ko-KR·en-US | 화면 문구 2개 | **검출 안 됨** — 대체 문구가 나감 (07-01) | +| 3 | 매핑 1곳: V3는 기능의 `mapProblem`, V2는 hook이 없어 `src/adapters/http/client.ts`, RPC는 `browser-rpc-runtime.ts:1543` | 서버 code → kind 매핑 | 검출 안 됨 | +| 4 | `tests/unit/error-classification.test.ts:14` | 고정 개수 38 | 테스트 실패로 드러남 | +| - | 레지스트리 거버넌스 | 행 추가 = additive, 증거 불필요 | 해당 없음 | +| - | 텔레메트리 | `error_kind` 정규식이 새 값 자동 허용 | 해당 없음 | + +합계: 코드 3~4파일, 정책 4~5개, 함께 배포할 단위 1개. `FailureKind`를 망라하는 `Record`가 없어서 컴파일러가 빠진 곳을 알려 주지 않는다. 기능 전용 오류라도 플랫폼 공용 `ERROR_REGISTRY`와 공용 카탈로그를 고쳐야 한다. 그래서 기능 팀 사이의 공동 변경 지점이 된다(관점 25). + +## 3. 확인된 강점 + +1. **설정·매니페스트를 엄격하게 거부한다.** 모르는 키는 `.strict()`가 막는다. HTTPS, 자격 증명 없는 URL, demo 인증은 local에서만 허용하는 규칙, 같은 origin 경로 조건을 한 곳에서 강제한다(`src/contracts/release-artifacts.ts:91-171`). 비밀처럼 보이는 설정 이름은 거부한다(`src/contracts/env.ts:73-110`). M4·M8 변이를 테스트가 잡았다. +2. **조립 시점 입력은 한 번만 읽고 스냅샷한다.** exact decode가 `exact-snapshot.ts:74-123` 하나로 모였다. accessor, non-enumerable, 커스텀 prototype, symbol 키를 거부한다. `external-contract-runtime.ts:579-626`, `rest-profiles.ts:118-204`, `realtime-streams.ts:540`, `browser-rpc.ts:388-414`가 이 구현을 쓴다. M6 변이를 테스트가 잡았다. +3. **결과를 모르는 쓰기를 재시도 대상에서 뺀다.** `MAYBE_APPLIED`면 `retryable=false`, `action=contact-support`가 된다(`errors.ts:282-341`). `withFailureEffect` 쪽은 테스트가 고정한다(M1b killed). +4. **모르는 값을 안전하게 처리하는 곳이 여러 군데 있다.** + - 응답 DTO는 모르는 필드를 버린다(`.strip()`, `features/reference-feature/contracts/reference-schemas.ts:29-48`). + - 모르는 검증 코드는 일반 문구로 바뀐다(`presentation/forms/form-contracts.ts:42-50`). + - 저장소에 모르는 값이 있으면 거부한다. 저장소 키에는 버전이 붙어 있다(`storage-keys.ts:128-201`). + - 모르는 기능 ID의 override는 무시한다(`release-artifacts.ts:65-80`). + - 모르는 오프라인 상태에서는 어떤 전이도 허용하지 않는다(`offline-command.ts:100-107`). +5. **레지스트리의 깨지는 변경에는 증거를 요구한다.** `scripts/lib/registry-compatibility.ts:303-336`이 breaking 변경마다 versionBump, migration, compatibilityWindow, rollback, owner가 비어 있지 않은지 검사한다. 실제 증거 파일은 `config/contracts/registry-change-evidence.json`이다. +6. **realtime 시퀀스·시각을 엄격하게 검사한다.** 시퀀스는 BigInt로 uint64 상한을 확인한다. 타임스탬프는 윤년·말일까지 확인한다(`realtime-events.ts:120-184`). M12 변이를 테스트가 잡았다. 직접 호출에서도 `2026-02-29`가 거부됐다. + +## 4. 발견 사항 (36.3) + +### 07-01 오류 종류 22개에 화면 문구가 없어 "요청한 문구를 표시할 수 없습니다"가 표시된다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 3, 8, 17, 20, 21, 23 | +| 근거 | `src/contracts/errors.ts:52`가 키를 `error.${kind.toLowerCase()}`로 만든다. 카탈로그(`src/presentation/i18n/catalog.ts:130-145` ko, `:288-303` en)에는 그중 16개만 있다. 직접 호출 결과 22종의 키가 ko·en 모두에 없다: REQUEST_ABORTED, CONTENT_TYPE_MISMATCH, MALFORMED_JSON, RESPONSE_BODY_LIMIT, ENVELOPE_MISMATCH, SCHEMA_MISMATCH, MAPPING_CONTRACT_VIOLATION, RESULT_LIMIT_EXCEEDED, SCOPE_GENERATION_CHANGED, IDENTITY_INTERN_LIMIT_EXCEEDED, DUPLICATE_IN_FLIGHT, PAGINATION_CONTRACT_VIOLATION, CONFLICT, VALIDATION_REJECTED, UNKNOWN_CLIENT_FAILURE, BOOT_CONFIG_FAILURE, RELEASE_MANIFEST_FAILURE, DEPLOY_MISMATCH, STORAGE_UNAVAILABLE, STORAGE_QUOTA_EXCEEDED, TELEMETRY_FAILURE, QUERY_CACHE_FAILURE. `resolveMessage`는 없는 키를 `common.unavailable`로 대체한다(`presentation/i18n/message-contract.ts:75-79`). 데이터 없이 실패한 조회는 `terminal-error`가 되어(`application/view-models/async-state.ts:90-94`) 이 문구를 그대로 제목으로 보여 준다(`presentation/components/async-surface.tsx:83`). 막는 장치도 없다. `ErrorDefinition.userMessageKey`는 `string`이다(`errors.ts:35`). `errorMessage(messageKey: string)`도 타입 키를 요구하지 않는다(`components/error-copy.ts:3`). `check-i18n`은 로케일끼리 키가 같은지만 본다(`scripts/check-i18n.ts:32-52`). FE-REG-ERROR의 `references`는 비어 있다(`config/contracts/registry-governance.json:339` 항목) | +| 발생 조건 | 조회가 데이터 없이 실패하고 kind가 위 22종 중 하나일 때. 예: 서버 DTO 변경으로 `SCHEMA_MISMATCH`, 409 `CONFLICT`, 422 `VALIDATION_REJECTED`, 그 밖의 4xx `UNKNOWN_CLIENT_FAILURE` | +| 영향 | 사용자는 "요청한 문구를 표시할 수 없습니다" + "지원 정보 확인" 버튼을 본다. 무엇이 잘못됐는지 알 수 없고, 문구 자체가 번역 누락처럼 보인다. 새 kind를 추가하는 다운스트림도 같은 방식으로 문구를 빠뜨리고, 아무 검사도 실패하지 않는다 | +| 심각도·우선순위 | Medium · P2 — 데이터·보안 피해는 없다. 하지만 흔한 실패(계약 불일치·충돌·검증 거부)의 사용자 안내가 틀리고, 샘플과 기본값으로 복제된다 | +| 통제·증거 | M0(연결 검사 부재 확인) · E2(직접 호출 실행) | +| 확실성과 남은 가정 | 누락 22종은 확인했다. 부팅 계열(BOOT_CONFIG_FAILURE 등)이 별도 부트 화면을 쓰는지는 확인하지 않았다. 그래도 조회 경로의 누락만으로 결함은 성립한다 | +| 최소 개선 방향 | (1) 누락 22개 키를 ko·en에 추가한다. 비슷한 종류는 같은 문구를 써도 된다. (2) `tests/unit`에 테스트 하나를 둔다: 모든 `ERROR_REGISTRY` 행의 `userMessageKey`가 `KO_MESSAGES`와 `EN_MESSAGES`에 있는지. 테스트는 계층 규칙과 무관하게 양쪽을 import할 수 있다 | +| 비용·부작용 | 문구 22쌍과 테스트 1개. 동작 변경은 없다 | +| 완료 기준 | 38종 모두 전용 문구로 해석된다. 키 하나를 지우면 테스트가 실패한다 | +| 검증 방법 | 새 테스트 실행. 카탈로그에서 키 하나를 지운 변이로 테스트 실패 확인 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 07-02 호환성 규칙·분류기·FE-GATE-014가 "필드 추가는 안전"이라 하지만 실제 reader 여러 곳이 모르는 필드를 거부한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 17, 24, 21, 10, 18, 19 | +| 근거 | **규칙:** `docs/contracts/compatibility.md:6`은 "additive changes preserve current required fields"라고만 적는다. 이 규칙은 reader가 모르는 필드를 거부하는 경계를 구분하지 않는다. **분류기:** `classifyObjectSchemaChange`(`src/contracts/compatibility.ts:236-254`)는 속성 존재 여부와 required만 본다. 타입 변경(string→number), enum 축소, nullable 변경은 모두 `"none"`이다(2.2 실행 결과). **게이트:** FE-GATE-014는 이름이 `config-compatibility`다(`config/ci/gates.json:1989`). 그런데 실행하는 `scripts/check-compatibility.ts:24-34`는 `config/compatibility/fixtures.json`에 손으로 쓴 before/after 8쌍을 분류기에 넣어 보는 자가 검사다. 실제 설정·API 스키마의 이전/현재 버전은 읽지 않는다. **실제 reader:** ① 런타임 설정 V2는 `.strict()`이고 `CONFIG_SCHEMA_VERSION`이 `z.literal("2.0")`이다(`release-artifacts.ts:163-171`). 선택 키 하나를 추가하거나 버전을 "2.1"로 올리면 거부된다. `isVersionCompatible("2.0","2.1")`은 true라고 답하지만, 이 minor 호환 규칙은 설정 V2에서는 도달하지 않는다. ② `CAPABILITY_OVERRIDES`는 모르는 capability를 거부한다(`release-artifacts.ts:50-63`). 반면 `FEATURE_OVERRIDES`는 "공유 설정 문서가 여러 빌드를 덮을 수 있게" 모르는 ID를 무시한다(`:65-80`). ③ HTTP V2 성공·실패 envelope은 `.strict()`다(`adapters/http/schema-registry.ts:12-34`). `links`나 `error.target`만 추가해도 검증에 실패한다. ④ realtime envelope은 exact-key로 검사하고, 모르는 eventType을 MALFORMED_EVENT로 처리한다(`adapters/realtime/event-codec.ts:126,149`). 그러면 연결을 닫고 복구를 시작한다. ⑤ RPC transport 오류 코드는 닫힌 어휘이고, 모르는 코드는 계약 위반이 된다(2.3). ③④는 설계 문서의 `REJECT_UNKNOWN`(control envelope) 방침과 일치한다. 문제는 호환성 규칙·분류기·게이트가 이 방침을 반영하지 않는다는 점이다 | +| 발생 조건 | 다운스트림이 문서와 게이트를 믿고 다음 변경을 "additive"로 배포할 때: 설정에 선택 키나 capability 추가(여러 빌드가 공유 설정을 쓰는 경우), 서버 envelope에 필드 추가, 새 realtime eventType을 서버가 먼저 배포. 여러 탭과 롤백은 지원 범위이므로 구버전 reader가 실제로 남아 있다 | +| 영향 | 설정: 구 빌드가 부팅에 실패한다(`BOOT_CONFIG_FAILURE`). envelope: 구 탭의 V2 호출이 모두 `ENVELOPE_MISMATCH`가 된다. realtime: 구 탭의 스트림이 이벤트마다 닫히고 복구를 반복한다. 타입·enum 변경은 게이트가 "none"이라 리뷰에서도 놓친다. 모두 fail-closed라 데이터 손상은 없다 | +| 심각도·우선순위 | Medium · P2 — 게이트 이름과 분류 결과가 실제보다 강한 보장을 약속해서, 배포 순서 판단을 틀리게 만든다. 템플릿의 호환성 문서와 게이트는 그대로 복제된다 | +| 통제·증거 | M1(문서 규칙만 있음. 게이트는 분류기 자가 검사) · E2(파서·분류기 직접 실행) | +| 확실성과 남은 가정 | 파서 동작은 실행으로 확인했다. 실제 브라우저에서 구 탭과 신 서버가 공존하는 실험은 하지 않았다. 설정 공유 운영은 코드 주석(`release-artifacts.ts:71-73`)이 지원한다고 적은 시나리오다 | +| 최소 개선 방향 | (1) `docs/contracts/compatibility.md`에 경계별 표를 넣는다. `REJECT_UNKNOWN` 경계(설정, V2 envelope, realtime envelope, RPC 오류 어휘)에서는 필드 추가도 breaking이고, reader를 먼저 배포해야 한다. (2) 분류기는 모르는 변경(타입·enum·nullable)을 `"none"` 대신 `"breaking"`으로 답한다(fail-closed). 아니면 이름을 `classifyRequiredPropertyChange`로 줄인다. (3) FE-GATE-014는 실제 스키마(예: 빌드가 만드는 `dist/runtime-config.schema.json`)를 커밋된 기준본과 비교한다. 그게 과하면 게이트 이름을 `compatibility-classifier-selftest`로 바꾼다. (4) `CAPABILITY_OVERRIDES`의 모르는 키 처리를 `FEATURE_OVERRIDES`와 맞추거나, 다른 이유를 적는다. (5) `compatibility.test.ts`에 "런타임 minor가 더 낮으면 비호환" 케이스를 추가한다(M10 survived) | +| 비용·부작용 | (1)(4)(5)는 작다. (2)는 분류기 결과가 보수적으로 바뀌므로 fixture를 갱신해야 한다. (3)은 기준본 파일과 갱신 절차가 하나 더 생긴다 | +| 완료 기준 | 문서가 경계별 규칙을 적고 있다. 타입 변경 fixture가 `breaking`으로 분류된다. 게이트가 실제 스키마를 읽거나 이름이 실제 동작과 맞다 | +| 검증 방법 | 분류기에 타입·enum 변경 fixture 추가. 설정 스키마에 선택 키를 추가한 변이로 게이트 결과 확인. M10 재실행 시 killed | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 07-03 참조 기능이 같은 HTTP 오퍼레이션을 V2·V3 두 벌로 선언하고, 거버넌스는 실행되지 않는 V2 벌만 본다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 (갈라진 중복 복사본) | +| 관련 관점 | 3, 9, 17, 20, 21, 22, 23 | +| 근거 | V2 행: `src/features/reference-feature/contracts/reference-feature-contract.ts:155-238`(`defineRestOperation` 3개). V3 descriptor: `reference-feature-contract-contribution.ts:103-140` 등 3개. method, path, 성공 상태, 응답 상한, 재생 정책, auth profile을 양쪽에 따로 적는다. 실행되는 것은 V3다(`adapters/http/index.ts:37-45`가 "V2 legacy, 레지스트리를 비워서 출하"라고 적는다. gateway도 V3를 쓴다). V2 벌이 쓰이는 곳은 세 군데다. FE-REG-API 거버넌스(`registry-governance.json:143`, exportName `API_OPERATIONS`), 스키마·매퍼·프로필 바인딩 검사(`features/installed-feature-contracts.ts:40-44,77`), realtime snapshot 바인딩(`realtime-streams.ts:451-470`은 V2 QUERY 행을 요구한다). V3 조립(`features/installed-contract-contributions.ts:15`)과 V2 행이 일치하는지 비교하는 코드·테스트는 없다(`reference-contract.test.ts:112-132`는 V2 키 목록만 본다). **실험:** worktree에서 V3의 `pathTemplate`을 `/api/v9/items/{resourceId}`로, `responseByteLimit`을 32 KiB → 8 MiB로 바꿨다. `node scripts/check-registries.ts`는 `11 registries PASS`였다. 실패한 것은 참조 기능용 시나리오 카탈로그 통합 테스트 하나뿐이었다(`tests/integration/http-scenario-catalog.test.ts`, 동작 기반) | +| 발생 조건 | 다운스트림이 참조 기능을 복제해 오퍼레이션을 추가·변경할 때. 특히 V3만 고치고 V2를 두는 경우 | +| 영향 | 거버넌스가 "breaking 변경에는 증거 필요"를 강제하는 대상이 실제로 실행되지 않는 복사본이다. 실행되는 계약의 path·상한·재시도 변경은 증거 없이 통과한다. 반대로 V2만 바꾸면 증거를 요구받지만 동작은 바뀌지 않는다. 다운스트림 기능은 오퍼레이션마다 두 형식을 배워야 하고, 참조 기능 같은 시나리오 카탈로그가 없으면 불일치를 잡을 장치가 없다 | +| 심각도·우선순위 | Medium · P2 — 데이터 피해는 없다. 하지만 공유 계약 변경 관리가 착시가 되고, 기능마다 변경 누락이 반복될 구조다. 소유자 결정("갈라진 중복 복사본은 문제")에 해당한다 | +| 통제·증거 | M0(두 벌 일치 검사 부재) · E2(worktree 변이 실험) | +| 확실성과 남은 가정 | 참조 기능 기준으로 확인했다. V2 클라이언트를 실제로 주입해 쓰는 다운스트림이 있는지는 알 수 없다 | +| 최소 개선 방향 | 둘 중 하나를 고른다. (a) V2 행을 V3 descriptor에서 생성해 한 벌로 만든다(method/path/상태/상한/auth 복사). (b) 당장은 테스트 하나를 추가한다. 같은 operationId의 V2 행과 V3 descriptor에서 method, path, 성공 상태, 응답 상한, auth profile, 재생 정책이 일치하는지 본다. 장기적으로는 FE-REG-API가 조립된 V3 레지스트리를 감시하게 옮긴다 | +| 비용·부작용 | (b)는 테스트 1개. (a)와 거버넌스 이전은 기준본(baseline) 재승인과 change evidence가 필요하다 | +| 완료 기준 | V3 path나 상한을 바꾸면 거버넌스 또는 일치 테스트가 실패한다 | +| 검증 방법 | 위 실험을 다시 실행해 `check-registries` 또는 일치 테스트가 실패하는지 확인 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 (6.7-8의 "두 모양"과 같은 계열이지만 대상이 다르다) | + +### 07-04 ERROR_REGISTRY의 severity·redaction·telemetryEvent와 AppFailure.retryable은 읽는 곳이 없는데 정책처럼 관리된다 + +| 필드 | 내용 | +|---|---| +| 성격 | 개선 제안 (이름·필드가 실제 보장을 과장) | +| 관련 관점 | 22, 24, 7, 10 | +| 근거 | `errors.ts:31-39`의 7개 필드 중 `severity`, `redaction`, `telemetryEvent`를 읽는 코드는 `src`에 없다(grep 결과 0건). 실제 텔레메트리는 `bootstrap/runtime-adapters.ts:256`과 `adapters/http/client.ts:246`이 `"api.request.failed"`를 직접 적어 보낸다. 그런데도 FE-REG-ERROR는 `telemetryEvent`를 breakingField로 둔다(`registry-governance.json` FE-REG-ERROR `breakingFields`). 과거에 이 필드를 바꿀 때 rollback 계획까지 적은 증거가 남아 있다(`registry-change-evidence.json:101`). `redaction` 목록도 실제로는 쓰이지 않는다. 실제 필드 제거는 `createFailure`의 허용 목록 복사가 한다. `AppFailure.retryable`도 presentation·application·query-cache에서 읽는 곳이 없다(grep 0건). 그래서 `createFailure(…, {effect:"MAYBE_APPLIED"})`의 `retryable=false` 규칙을 망가뜨려도 테스트가 통과한다(M1 survived) | +| 발생 조건 | 다운스트림이 새 kind에 `telemetryEvent: "payment.failed"` 같은 값을 적거나 `redaction`에 필드를 추가하고, 그대로 동작한다고 믿을 때. 또는 `failure.retryable`로 자동 재시도를 만들 때 | +| 영향 | 기대한 이벤트가 나가지 않는다. 비식별 처리도 바뀌지 않는다. 거버넌스는 효과 없는 필드 변경에 증거를 요구한다. `retryable`을 쓰기 시작하면, 테스트되지 않은 규칙에 기대게 된다 | +| 심각도·우선순위 | Low · P3 — 지금은 동작 결함이 없다. 오해로 생길 비용만 있다 | +| 통제·증거 | M0(연결 부재) · E1(grep) + E2(M1 변이) | +| 확실성과 남은 가정 | 영역 밖(`src/platform/telemetry`)은 필드 이름만 grep했다. 같은 이름의 `severity`는 텔레메트리 이벤트의 필드이지 ERROR_REGISTRY 필드가 아니다 | +| 최소 개선 방향 | 연결하거나 지운다. 연결하지 않을 필드는 행에서 빼고 governance의 `breakingFields`에서도 뺀다. `retryable`을 공개 계약으로 남긴다면 `createFailure`의 effect 규칙 테스트 1개를 추가한다 | +| 비용·부작용 | 필드 제거는 레지스트리 스냅샷 변경이라 change evidence가 필요하다 | +| 완료 기준 | ERROR_REGISTRY의 모든 필드에 읽는 곳이 있거나 필드가 없다. M1이 killed가 된다 | +| 검증 방법 | grep으로 소비자 확인, M1 재실행 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 07-05 diagnostics negative fixture는 위반 3개 중 1개만 고정해서 나머지 2개가 풀려도 게이트가 통과한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 (가드레일 검출력) | +| 관련 관점 | 21, 10 | +| 근거 | `tests/fixtures/typecheck/invalid-diagnostics-port.ts:7-11`에 위반이 3개 있다. 잘못된 `level`, 잘못된 `eventId`, 잘못된 텔레메트리 이벤트 이름이다. 게이트는 종료 코드 1과 출력 안의 문자열 `"UNKNOWN_DIAGNOSTIC_EVENT"`만 확인한다(`config/ci/gates.json` `check-types-fixture-diagnostics`, `scripts/lib/ci-step-result.ts:66-72`). **실험:** worktree에서 `TelemetryPort.emit`의 인자를 `string`으로 넓혔다(`application/ports/telemetry-port.ts`). tsc는 여전히 exit 1이었고, 판정 함수 `classifyGateStepResult`는 `EXPECTED_FAILURE`를 돌려줬다. 텔레메트리 이벤트 이름 계약이 풀린 것을 검출하지 못한다. `level` 쪽도 같은 구조다. 다른 fixture들은 TS 오류 코드만 고정한다(예: `"error TS2322:"`). 지금은 fixture마다 위반이 하나라 문제없다 | +| 발생 조건 | 텔레메트리 포트나 진단 level 타입이 넓어지는 변경 | +| 영향 | 미등록 텔레메트리 이벤트 이름이 컴파일을 통과한다. 런타임 투영(`telemetry.ts:153-158`)에서 조용히 버려진다 | +| 심각도·우선순위 | Low · P3 — 런타임 투영이 한 번 더 막는다. 검출 수단이 약해진 것뿐이다 | +| 통제·증거 | M3(부분: 3개 중 1개) · E2(변이 실험) | +| 확실성과 남은 가정 | 확인됨 | +| 최소 개선 방향 | TypeScript의 기본 기능인 `// @ts-expect-error`를 위반마다 붙이고, fixture가 오류 없이 컴파일되는 것을 게이트 조건으로 삼는다. 위반이 풀리면 TS2578("쓰이지 않은 @ts-expect-error")로 실패한다. 위반 하나마다 별도로 검출되고, 기대 진단 문자열 관리가 필요 없다. 최소한 이 fixture는 3개로 나눈다 | +| 비용·부작용 | fixture 수정과 gates.json의 expect 변경 | +| 완료 기준 | 3개 위반 각각을 풀었을 때 게이트가 실패한다 | +| 검증 방법 | 위 실험을 세 위반에 각각 반복 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 07-06 `invokeValidator`의 "native throw로 새지 않는다" 약속에 구멍이 있다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 1, 24, 6 | +| 근거 | 주석(`external-contract-runtime.ts:61-65`)은 검증기 호출이 native throw로 새지 않는다고 약속한다. 그런데 try 밖에서 `[...(result.issues ?? [])]`를 펼친다(`:89`). 직접 호출 결과 `{success:false, issues:5}`와 `{success:false, issues:{}}`는 TypeError를 던졌다. `result.success`는 truthy 여부만 보므로(`:84`) `{success:"no"}`가 VALID가 된다. 호출처는 V3 실행기의 입력·출력·problem 검증 3곳이다(`adapters/http/http-execution-v3.ts:646,1318,1541`) | +| 발생 조건 | 기능이나 외부 패키지가 zod 래퍼가 아닌 직접 만든 검증기를 넣고, 그 검증기가 형식에 맞지 않는 결과를 돌려줄 때. 참조 구현(`zodValidator`)은 항상 배열을 돌려준다 | +| 영향 | 약속된 `VALIDATOR_RUNTIME_FAILURE` 대신 예외가 실행기 밖으로 나가거나, 검증되지 않은 `data`가 VALID로 통과한다 | +| 심각도·우선순위 | Low · P3 — 검증기는 빌드에 포함되는 코드라 원격 입력으로는 도달하지 않는다 | +| 통제·증거 | M2(try/catch는 있으나 불완전) · E2(직접 호출) | +| 확실성과 남은 가정 | 예외가 실행기의 바깥 catch에서 어떤 결과가 되는지는 영역 03에서 확인할 일이다 | +| 최소 개선 방향 | `result.success === true`, `Array.isArray(result.issues)` 검사를 넣고, 아니면 `THROWN`을 돌려준다. 해당 테스트 2건 추가 | +| 비용·부작용 | 몇 줄 | +| 완료 기준 | 위 세 입력이 모두 `THROWN`이 된다 | +| 검증 방법 | 단위 테스트 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 07-07 호환 별칭·V1 reader에 폐기 표시와 제거 조건이 코드에 없다 + +| 필드 | 내용 | +|---|---| +| 성격 | 개선 제안 | +| 관련 관점 | 17, 9, 26, 27 | +| 근거 | `src/contracts`에 `@deprecated`가 0건이다. 호환 별칭은 주석으로만 표시된다: `ApiFailure`(`errors.ts:264-269`, 8파일 사용), `boundary-mapper.ts:17-18`의 `MappingResult`(7파일 사용), `read-only-registry.ts:64-65` 재수출. V1 설정·매니페스트 reader(`release-artifacts.ts:154-161,191-198`)의 보존 기간은 change evidence에 "one release"라고만 적혀 있다(`registry-change-evidence.json`의 `FE-REG-ENV:API_CONTRACT_VERSION` 항목, 2026-09-24 도입). 코드에는 제거 조건·담당·확인 방법이 없다 | +| 발생 조건 | 시간이 지나 제거 시점을 판단할 때, 또는 새 코드가 별칭을 계속 import할 때 | +| 영향 | 신규 코드가 옛 이름을 계속 쓴다. 보존 기간이 지났는지 알 방법이 없어서 호환 코드가 영구화된다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M1(evidence JSON 문장) · E1 | +| 확실성과 남은 가정 | "one release"는 도입된 지 하루라 아직 지나지 않았다 | +| 최소 개선 방향 | 별칭과 V1 reader에 `/** @deprecated <대체> — <제거 조건/릴리스> */`를 단다. 이미 쓰는 typescript-eslint에 `no-deprecated` 규칙이 있는지 확인해 새 import를 막는다 | +| 비용·부작용 | 주석 몇 줄. 규칙을 켜면 기존 사용처 경고가 생긴다 | +| 완료 기준 | 별칭마다 대체와 제거 조건이 적혀 있다 | +| 검증 방법 | grep, lint | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 6.7-8과 관련 (D-15로 별칭 유지는 결정됨. 폐기 표시는 결정 범위 밖) | + +## 5. 28개 관점 판정 (36.2) + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +|---|---|---|---|---|---| +| 1 | 코드 성숙도 | 적용 — 외부 JSON 런타임 검증 | 목표 M4 · 확인 M3 | E2(runtime-schema·계약 테스트 통과, M4/M8 killed) | 부분 충족 — 설정·매니페스트·envelope·realtime은 파서를 거친다. `invokeValidator` 구멍(07-06). `AppFailure`는 브랜드 없는 타입이라 리터럴로 만들 수 있다(지금 `src`에 그런 우회는 없음) | +| 2 | 구조적 성숙도 | 적용 | M3 | E1(`.dependency-cruiser.json`의 contracts→application/features/presentation/bootstrap/adapters 금지 규칙, `src/contracts`의 상향 import 0건) | 충족 — 전체 `check:architecture` 실행은 오케스트레이터 몫 | +| 3 | 변경 용이성 | 적용 | M1 | E1(2.3 추적) | 부분 충족 — 오류 코드 추가는 3~4파일, 정책 4~5개. 문구 누락은 검출되지 않는다(07-01). HTTP 오퍼레이션 두 벌(07-03) | +| 4 | 인지 부하 | 적용 | M1 | E1 | 부분 충족 — HTTP 계약 2세대(V2/V3), 매핑 결과 2모양, 검증기 프로토콜 2개, 거버넌스 JSON 4개. 주석마다 §·VD-·Q-·R- 참조가 많아 추적 비용이 크다 | +| 5 | 위험 가시성 | 적용 | M2 | E1 | 충족 — `HTTP_EXECUTION_CEILINGS`, `REALTIME_HARD_LIMITS`, `BROWSER_RPC_HARD_LIMITS` 등 상한이 계약에 드러난다. 효과 확실성(`FailureEffectCertainty`)도 타입으로 드러난다 | +| 6 | 실패 성숙도 | 적용 | M3 | E2(M1b killed, M1 survived) | 부분 충족 — MAYBE_APPLIED 처리는 있다. `createFailure` 경로는 테스트가 없다(07-04). 새 오류 코드는 kind 단위로 안전하게 떨어진다 | +| 7 | 운영 성숙도 | 부분 적용 — 관측 어휘 | M1 | E1 | 부분 충족 — telemetry에는 `error_kind`만 남고 서버 code는 남지 않는다. `telemetryEvent` 필드는 효과가 없다(07-04). 관측 파이프라인은 다른 영역 | +| 8 | 디버깅 가능성 | 부분 적용 | M2 | E1 | 부분 충족 — `AppFailure`는 requestId·traceId·code를 보존한다. 관측으로 나가는 것은 kind뿐이다. 수집 경로는 다른 영역(03·09) | +| 9 | 유지보수 성숙도 | 적용 | M1 | E1 | 부분 충족 — 별칭 폐기 표시가 없다(07-07). 두 벌 선언(07-03) | +| 10 | 테스트 성숙도 | 적용 | M3 | E2(244+33 통과, 변이 16건 중 12 killed) | 부분 충족 — 직전 리뷰 수정분은 테스트가 잡는다. M1·M10 survived. 구버전 소비자/신버전 제공자 조합 테스트는 없다 | +| 11 | 데이터 성숙도 | 부분 적용 — 저장소 키 계약 | M4 | E1 | 충족(이 영역 범위) — 키 버전화와 `migration: "discard"`만 허용하고, 모르는 값은 거부한다(`storage-keys.ts`). 저장 구현은 영역 05 | +| 12 | 동시성 성숙도 | 적용 제외 — contracts는 순수 함수. 조립 시점 재읽기 방지(스냅샷 1회 읽기)는 관점 1에 기록 | - | - | 적용 제외 | +| 13 | 확장성 | 부분 적용 | M2 | E1 | 부분 충족 — 레지스트리 상한(예: RPC 오퍼레이션 512, realtime 스트림 128)이 있다. 기능 전용 오류도 중앙 `ERROR_REGISTRY`로 모인다. 규모 실험은 다른 영역 | +| 14 | 성능 성숙도 | 적용 제외 — 계약 코드는 상한이 정해진 작업만 한다. 측정 대상 아님 | - | - | 적용 제외 | +| 15 | 보안 성숙도 | 적용 — 설정 비밀 이름, 배포 승인, 자격 증명 헤더 | M3 | E2(M8·M19 killed) | 충족 — 6.7-2·6.7-10 수정 확인. 텔레메트리는 속성 허용 목록으로 제한한다 | +| 16 | 의존성 성숙도 | 부분 적용 | M1 | E1 | 부분 충족 — contracts가 zod에 직접 의존한다(`release-artifacts.ts`, `contract-set.ts`). 판단은 다른 영역 | +| 17 | API / Contract 성숙도 | 적용 — 중점 | 목표 M3 · 확인 M1~M2 | E2 | 부분 충족 — 누락·빈 값·모르는 값을 안전하게 처리하는 곳이 많다(강점 4). 호환성 규칙·게이트가 strict 경계를 반영하지 않는다(07-02). 폐기 절차가 코드에 없다(07-07). 구·신 버전 공존 검증이 없다 | +| 18 | 배포 성숙도 | 다른 영역 — release. 이 영역 관련분만 기록 | M1 | E2 | 부분 충족 — 설정 V2가 엄격해서 빌드 간 설정 공유 시 additive 변경에도 부팅이 막힌다(07-02) | +| 19 | 설정 성숙도 | 부분 적용 | M3 | E2 | 부분 충족 — 스키마, 불변식, 금지 이름을 검증한다. `CAPABILITY_OVERRIDES`와 `FEATURE_OVERRIDES`의 모르는 키 처리가 다르다(07-02) | +| 20 | 개발자 경험 | 부분 적용 | M1 | E1 | 부분 충족 — 오퍼레이션 하나에 두 형식을 써야 한다(07-03). 문구 누락은 조용히 대체 문구로 나간다(07-01) | +| 21 | Guardrail 성숙도 | 적용 — negative fixture | M3 | E2(fixture 8개 실행, 변이 실험) | 부분 충족 — fixture는 의도한 위반을 잡는다. diagnostics fixture는 3개 중 1개만 고정한다(07-05). 문구 연결(07-01), V2/V3 일치(07-03)를 잡는 장치가 없다. FE-GATE-014는 자가 검사다(07-02) | +| 22 | 추상화 성숙도 | 적용 — 레지스트리·거버넌스 | M2 | E1·E2 | 부분 충족 — exact-snapshot으로 모은 것은 효과가 확인된다(M6 killed). 레지스트리 거버넌스는 효과 없는 필드(07-04)와 실행되지 않는 복사본(07-03)도 감시한다. module augmentation은 contracts 밖(영역 09) | +| 23 | 일관성 | 적용 | M2 | E1 | 부분 충족 — `AppFailure.code` 문법이 경로마다 다르다(V2 `^[A-Z0-9_]{1,64}$`, V3 problem code는 120자 자유 문자열, RPC는 `RPC_*`). 진단 `outcome` 값은 소문자·대문자 어휘가 섞여 있다(`diagnostics.ts:94-97`). `MappingResult` 두 모양은 D-15로 유지된다. `validBoundedString`은 "공백만 아님 + 바이트 상한"만 본다 | +| 24 | 네이밍 / 의미 성숙도 | 적용 — 중점 | M1 | E2 | 미충족 — 이름이 보장을 과장한다. `config-compatibility` 게이트와 `classifyObjectSchemaChange`(07-02), "never escapes as a native throw"(07-06), `telemetryEvent`·`redaction`(07-04). `safeValidationIssues`의 "safe"는 크기 제한이지 문자 정제가 아니다(코드 80자, 경로 120자 자유 문자열) | +| 25 | 조직 확장성 | 구조적 준비만 평가(작성자 1인) | M1 | E1 | 미검증 — 기능 전용 오류도 중앙 레지스트리와 공용 카탈로그를 고쳐야 한다(2.3). 레지스트리마다 owner 문자열은 있다 | +| 26 | Ownership 성숙도 | 부분 적용 | M1 | E1 | 부분 충족 — governance·evidence에 owner가 있다. 호환 코드 제거 담당은 없다(07-07) | +| 27 | 삭제 가능성 | 다른 영역 — 기능 제거 | - | E1 | 다른 영역 — 참조 기능 제거 시 V2·V3 두 곳을 지워야 한다는 점만 기록(07-03) | +| 28 | 회복 가능성 | 적용 제외 — contracts는 복구 절차를 소유하지 않음 | - | - | 적용 제외 | + +## 6. 미검증 목록 + +- **구 탭 + 신 서버·설정 공존.** strict reader가 실제 배포 순서에서 부팅 실패나 재연결 반복으로 이어지는지는 파서 단위로만 확인했다. 확인하려면 Playwright에서 구 번들이 열린 탭에 envelope 필드와 설정 키가 추가된 응답을 주는 시나리오가 필요하다. +- **browser-rpc 미등록 오류 코드와 command 효과.** 코드가 프로토콜 위반으로 분류될 때 command의 `effect`(MAYBE_APPLIED 여부)가 어떻게 되는지 확인하지 않았다. 영역 03에서 transport 오류 경로 테스트로 확인해야 한다. +- **부팅 오류 화면의 문구.** `BOOT_CONFIG_FAILURE` 등 부팅 계열이 `TerminalErrorSurface` 대신 별도 부트 화면 문구를 쓰는지 확인하지 않았다(07-01의 부팅 계열 영향 범위). +- **줄 단위로 읽지 않은 파일.** `browser-rpc.ts` 내부 검증식, `query-keys.ts`, `server-state.ts`, `service-worker*.ts`, `web-worker.ts`, `runtime-capabilities.ts`, `product-features.ts`. +- **전체 게이트.** `check:types`, `check:architecture`, `test:unit` 전체, `verify:compatibility`를 이 리뷰에서 직접 실행하지 않았다(오케스트레이터 몫). diff --git a/docs/reviews/2026-09-25-maturity-review/08-presentation.md b/docs/reviews/2026-09-25-maturity-review/08-presentation.md new file mode 100644 index 00000000..c93416d3 --- /dev/null +++ b/docs/reviews/2026-09-25-maturity-review/08-presentation.md @@ -0,0 +1,364 @@ +# presentation 성숙도 리뷰 + +> 검토일: 2026-09-25 · 기준: `main` / `4626b73` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 범위: `src/presentation/` 72파일(TS/TSX 약 8.1k줄, CSS 약 1.6k줄). 시나리오 추적용으로 샘플 화면 `src/features/reference-feature/presentation/`(8파일, 약 580줄)도 읽었다. 문서 `docs/accessibility/manual-checklist.md`, `docs/styling/*`, `docs/architecture/routing-pages-and-patterns.md`, 테스트 `tests/component/`, `tests/features/reference-feature/reference-page.test.tsx`, `tests/e2e/`(화면 관련), `tests/visual/`, `tests/storybook/` +> 영역 판정(35.8): **조건부 사용 가능** + +## 1. 결론 + +- **조회 화면 패턴은 그대로 써도 된다.** 목록·상세는 loading·success·empty·error·idle을 구분한다. 조회 실패는 종류에 따라 "로그인"(현재 URL로 복귀), "안전한 화면으로 이동", "다시 시도" 버튼을 따로 준다. 이전 세션의 응답과 과거 필터의 응답이 현재 화면을 덮지 않는다. 테스트도 이 동작을 막고 있다. +- **폼 저장 실패 처리는 고쳐야 한다(08-01).** 모든 폼이 쓰는 `useAppForm`이 세션 만료(401)·권한 없음(403)·요청 과다(429)를 전부 "입력 내용을 확인해 주세요 / 잠시 후 다시 시도해 주세요" 하나로 보여 준다. 로그인 버튼도 없다. 같은 실패가 목록 조회에서는 "로그인" 버튼으로 나온다. +- **결과 불명 저장(08-03)은 판단 근거 없이 사용자에게 "적용됨/안 됨"을 고르게 한다.** "안 됨"을 고른 뒤 같은 값으로 다시 저장하면 새 멱등 키로 나간다. 정본 설계 문서는 같은 키를 쓰라고 한다. +- **오류 종류 38개 중 22개에 사용자 문구가 없다(08-02).** 이때 오류 제목으로 "요청한 문구를 표시할 수 없습니다."가 뜬다. 샘플 화면 문구는 언어 전환 대상이 아니다(08-04). 두 문제 모두 `check:i18n`이 잡지 못한다. +- **접근성은 자동 스캔 증거만 있다. 그마저 범위가 좁다.** axe는 보호 라우트 4개에서 실제 화면이 아니라 로그인 안내 화면을 검사한다(08-05). 사람이 한 수동 검토는 0/10건이다. 그래서 merge 게이트 FE-GATE-009의 수동 검토 단계가 현재 상태로는 통과할 수 없다(08-06). +- 직전 리뷰 6.8의 1~9, 11~13은 코드에서 고쳐진 것을 다시 확인했다. 6.8-10(상태 화면 통합)만 일부가 남았다(08-11). + +## 2. 범위와 방법 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상·커밋 | `main` / `4626b73`. 미커밋 파일(`CLAUDE.md`, 가이드)은 판정 기준으로만 읽었다 | +| 목적·실행 구성 | 템플릿 SPA. SSR 없음. 판정 전제는 공통 지시서 2절을 따랐다 | +| 읽은 코드 | `src/presentation/` 전 파일(routes, boundaries, layouts, providers, adapters/query, forms, templates, design-system, i18n, pages, examples). 샘플 화면 전체. 연결 확인용으로 `src/contracts/errors.ts`, `src/application/view-models/async-state.ts`, `src/adapters/platform/browser-mutation-intent-factory.ts`, `src/bootstrap/runtime-application.tsx`, `eslint.config.ts`, `scripts/check-i18n.ts`, `config/ci/gates.json`의 FE-GATE-009 | +| 실행한 테스트(원본 트리) | `node scripts/run-vitest.ts run` 대상 14파일: router, async-surface, form-foundation, route-status-surfaces, locale-platform, app-shell, chunk-recovery-boundary → 59/59 통과. reference-page, application-query-scope-fence, application-mutation-scope-fence, context-route-gateway, pagination, tooltip, page-templates → 32/32 통과 | +| 실험(분리 worktree, 종료 후 제거) | ① probe 테스트 2파일: 폼 실패 kind별 화면, 로케일 전환 뒤 오류 문구, registry↔catalog 누락, 목록 실패 시 status, 결과 불명 뒤 재제출 멱등 키 → 결과는 각 발견 항목에 적었다. ② 결함 주입: `ChunkRecoveryBoundary`의 `key` 제거 → chunk-recovery 테스트 실패(검출됨). `isInitialLoading`을 `query.isPending`으로 되돌림 → application-query-bridge 테스트 실패(검출됨). `TextField`의 `aria-describedby` 제거 → component 테스트 1건 실패(검출됨). feature 화면에 `dangerouslySetInnerHTML` 추가 → ESLint FE-OC-019가 검출함. `check:i18n`은 통과함(검사 범위 밖). ③ `check:i18n` → PASS(145 keys). 이때 한국어 literal이 있는 화면 파일 9개가 그대로 있었다. ④ `verify-a11y-manual.ts` → 실패("evidence is incomplete") | +| 확인하지 못한 범위 | Playwright E2E·visual·storybook 실행(브라우저와 포트를 다른 에이전트와 공유), 실제 스크린리더, 번들 크기 재측정(`dist/`는 9/24 빌드이고 새 빌드는 공유 경로에 쓴다), HTTP 상태→FailureKind 분류(영역 03) | +| 직전 리뷰 비교 | 6.8-1~9, 11~13: 코드에서 수정 확인. 대부분 회귀 테스트도 있다(예: `router.test.tsx:109`, `:141`, `chunk-recovery-boundary.test.tsx:144`, `app-shell.test.tsx:81`, `context-route-gateway.test.tsx:72`). 6.8-10은 일부 미해결 → 08-11 | + +### 2.1 32절 시나리오 추적 + +| 시나리오 | 따라간 경로 | 결과 | +|---|---|---| +| 목록 최초 진입 | URL → `ContextRouteGateway` → `ProtectedRoute` → Suspense(`RouteLoadingSurface`) → `ReferenceResourcePage` → `useApplicationQuery` → `AsyncSurface` | 상태 구분됨(`async-state.ts:90-102`, `reference-page.test.tsx:163`). 실패 중에도 결과 수 status가 "결과 확인 중"으로 남는다(08-09). 문구가 없는 오류 종류가 22개다(08-02) | +| 상세 URL 직접 접속 | 생성 파일 `src/.generated/product-context-index.ts` → `context-routes.ts` → lazy 상세 페이지. `DetailPage key={resourceId}` | 동작함(컴포넌트 테스트). ID가 `new`/`status`면 충돌한다(08-13). SPA fallback은 배포 영역 | +| 빠른 필터 변경 | URL search → zod codec → `bindQuery`가 필터마다 다른 key token 부여 → abort signal 전달 | 과거 응답이 최신 화면을 덮지 않는다(key 분리). 샘플에 필터 UI가 없어 URL을 직접 바꿔야 재현된다 | +| 화면 이동·언마운트 | queryFn이 signal을 쓰므로 관찰자가 0이면 TanStack이 취소한다. gateway의 `active` 플래그, Popover·Menu·Toast 리스너 정리 | 작업·리스너가 쌓이지 않는다(정적 확인). 뒤로 가기 스크롤 복원은 없다(08-08) | +| 로그아웃 중 응답 도착 | 실행 전후 `scope.isCurrent()` 확인(`application-query.ts:101-121`), `QueryClientProvider key={generation}` | 이전 세션 응답을 버린다(scope-fence 테스트 통과) | +| 저장 버튼 중복 클릭 | 버튼 disabled, `submitForm`의 `pendingRef`(`use-app-form.ts:257-271`), `REJECT_WHILE_ACTIVE`(`application-query.ts:458-469`), 멱등 키 | 화면 쪽 중복 방지 충족. 결과 불명 뒤 재제출은 새 키를 쓴다(08-03) | +| 낙관적 갱신 실패 | `optimistic-layer-runtime.ts` layer rollback, 서버 갱신 시 base 재계산(`:50-62`) | 구현과 테스트가 있다(`application-mutation-optimistic-cache.test.tsx`). 샘플 화면은 이 패턴을 쓰지 않는다 | +| 세션 만료 | 조회: `AUTH_REQUIRED` → "로그인" → `beginSignIn(returnTo)`. 저장: 08-01. subject가 바뀌면 scope fence가 앱 트리를 다시 마운트한다 | 조회는 충족. 저장은 미충족. 작성 중인 폼 값은 확인 없이 사라진다(데이터 폐기 정책으로 보이지만 문서에서 확인하지 못함) | +| 다국어 전환 | `PreferenceProviders`가 fence 밖에 있다(`runtime-application.tsx:32-56`). `lang/dir` 동기화. 로케일이 바뀌면 제목만 갱신한다 | 셸과 공통 상태 문구는 전환된다. 샘플 화면 문구(08-04)와 표시 중인 폼 오류(08-10)는 전환되지 않는다 | +| 키보드·보조기술 | 라우트 이동 시 main → h1 포커스(`app-router.tsx:166-180`, `page-header.tsx:16-27`). Dialog 포커스 복귀(`core.tsx:363-412`). ErrorSummary와 첫 오류 필드 포커스. `aria-describedby`/`aria-invalid`(`core.tsx:154-241`) | 구현·테스트 있음. 결함 주입도 검출된다. 실제 스크린리더 확인은 0건(08-06). axe 범위가 좁다(08-05) | + +### 2.2 대표 과제(관점 4): "목록 화면이 어느 API를 호출하고 실패하면 어떤 화면을 보여 주는가" + +작성자 설명 없이 코드만으로 끝까지 찾을 수 있었다. 막힌 곳은 네 군데다. + +```text +URL /examples/reference-resources + → route 정의: reference-feature-contract.ts:78 (grep으로 바로 찾음) + → 페이지 컴포넌트: installed-feature-runtimes.tsx의 ROUTE_RUNTIME에는 feature 항목이 비어 있음 ({}) ← 막힘 1 + 실제 경로: src/.generated/product-context-index.ts(생성 파일, git에 없음) → context-routes.ts → reference-feature-runtime.ts → lazy page ← 막힘 2 + → 호출: use-reference-feature.ts:121 → input.listResources → reference-feature-api.ts → reference-http-gateway.ts + operationId LIST_REFERENCE_RESOURCES → contract path /api/reference-resources (contract.ts:158) + → 실패: AppFailure.kind → ERROR_REGISTRY 행(action) → 문구 키는 `error.${kind.toLowerCase()}` 문자열 규칙(errors.ts:52) ← 막힘 3 + → catalog에 없으면 조용히 대체 문구 + → AsyncSurface → TerminalErrorSurface. 버튼은 registry action과 페이지가 넘긴 onAction이 둘 다 있어야 보임 + (use-reference-failure-action.ts가 reauth/navigate/contact-support만 처리, retry는 onRetry) ← 막힘 4 +``` + +- 막힘 1·2: feature 화면은 boot용 descriptor(`reference-feature-runtime-descriptor.ts:17-21`, 빈 runtime)와 실행용 runtime이 나뉘어 있다. 연결 고리가 생성 파일이라 clean checkout에서는 파일 검색으로 찾을 수 없다. `app-router.tsx`도 platform 경로(`ROUTE_RUNTIME`)와 context 경로(`runtimeOverride`) 두 갈래를 모두 알아야 읽힌다. +- 막힘 3: 실패 종류와 화면 문구가 타입으로 연결되지 않는다. 그래서 문구 누락(08-02)을 코드 탐색으로는 알아채기 어렵다. +- 막힘 4: 버튼이 안 보일 때 원인이 registry 쪽인지 페이지 쪽인지 두 파일을 함께 봐야 한다. +- 어느 HTTP 상태가 어느 kind가 되는지는 `feature-http-binding.ts:345`와 `http-execution-v3.ts:1158` 두 곳에 있다(영역 03). + +## 3. 확인된 강점 + +1. **비동기 상태 모델이 화면 오류를 줄인다.** `AsyncState`는 base 상태와 overlay가 서로 배타적이다(`async-state.ts:19-61`, `:83-125`). `AsyncSurface`가 상태별 화면을 고정한다(`async-surface.tsx:104-176`). 조회 실패는 action에 따라 로그인(현재 URL·hash로 복귀)·이동·재시도로 갈린다(`use-reference-failure-action.ts:14-50`). 권한 없음·인증 실패·로그인 시작 실패는 `reference-page.test.tsx:211-293`이 막는다. 비활성 쿼리는 로딩이 아니라 idle이다(`application-query.ts:182`, 결함 주입으로 검출 확인). +2. **세션 경계와 응답 경쟁을 화면 쪽에서 막는다.** 요청 전후 scope 확인(`application-query.ts:101-121`), generation마다 다른 QueryClient, fence 밖의 로케일·테마, router dispose(`app-router.tsx:545-551`)가 있다. 과거 세션·과거 필터의 응답이 현재 화면에 들어가지 않는다. +3. **중복 제출과 결과 불명의 자동 재전송을 막는다.** 제출 하나를 검증부터 결과까지 묶는다(`use-app-form.ts:257-271`). effect가 없는 실패는 `MAYBE_APPLIED`로 본다(`application-query.ts:720-731`). 결과 불명이면 재제출을 막는다(`reference-resource-form-page.tsx:44-47`, `form-foundation.test.tsx:162`). +4. **접근성 기본 동작이 구현돼 있고, 테스트가 회귀를 잡는다.** 라우트 포커스, native `

`와 세대 번호로 하는 포커스 복귀, 필드 오류 연결, ErrorSummary가 있다. `aria-describedby` 제거 주입이 실제로 실패로 잡혔다. +5. **XSS 경로가 막혀 있다.** `dangerouslySetInnerHTML`은 모든 소스에서 ESLint로 금지된다(`eslint.config.ts:394-409`). feature 화면에 넣어 보자 검출됐다. React 19.2는 `javascript:` URL을 차단한다. 백엔드 메시지 렌더링은 `check:i18n`이 검사한다. CSP는 `script-src 'self'`다(`config/hosting/security-headers.json:4`). +6. **화면은 경로별로 lazy 로딩된다.** platform 화면(`route-runtime.tsx:25-47`), feature 화면(`reference-feature-runtime.ts:8-25`), context 라우트 모듈(생성 index의 동적 import)이 모두 분리돼 있다. 청크 실패 복구는 라우트별로 초기화된다(`app-router.tsx:338-339`, `:440-449`). + +## 4. 발견 사항 (36.3) + +### 08-01 폼 저장 실패가 세션 만료·권한 없음·요청 과다까지 "입력 확인 / 잠시 후 다시 시도" 하나로 합쳐짐 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 6, 5, 10, 23 | +| 근거 | `src/presentation/forms/use-app-form.ts:212-239`: `VALIDATION_REJECTED`, `MAYBE_APPLIED`, `APPLIED_CONFIRMED`, `CONFLICT` 외 모든 실패가 `form.unavailable`이 된다. `form-contracts.ts:16-22`의 `FormResultState`에는 재로그인·권한 없음 상태가 없다. 이 문구는 `ErrorSummary`에 들어가고 제목은 항상 "입력 내용을 확인해 주세요."다(`form-components.tsx:55`). probe: reference 폼에 `AUTH_REQUIRED`(401, NOT_APPLIED)를 돌려주자 alert="입력 내용을 확인해 주세요.저장하지 못했습니다. 잠시 후 다시 시도해 주세요."였고 로그인 버튼이 없었다(셸은 "로그아웃"을 표시). `FORBIDDEN`, `RATE_LIMITED`, `DUPLICATE_IN_FLIGHT`도 결과가 같았다 | +| 발생 조건 | 저장 요청이 401/403/429 등으로 거절될 때. 특히 토큰이 만료된 뒤 저장할 때 | +| 영향 | 사용자는 입력을 고치거나 재시도하지만 결과가 바뀌지 않는다. 403인데 "잠시 후 다시 시도"로 안내한다. 같은 실패가 목록 조회에서는 "로그인" 버튼으로 나와 화면 응답이 서로 다르다. 입력값은 남으므로 데이터 손실은 없다 | +| 심각도·우선순위 | Medium · P1 — 피해는 잘못된 안내로 끝난다. 하지만 `useAppForm`은 다운스트림 폼 전부가 쓰는 기본 훅이라 복제 범위가 가장 넓고, 고치는 비용은 작다 | +| 통제·증거 | M0(폼 경로에 구분 수단 없음) · E2(probe 테스트) | +| 확실성과 남은 가정 | 폼 쪽 동작은 확인했다. HTTP 어댑터가 401 저장 실패를 NOT_APPLIED로 분류한다는 전제는 영역 03에서 확인해야 한다 | +| 최소 개선 방향 | `FormResultState`에 `reauth-required`·`forbidden`·`retry-later`를 추가하고 `failure.action` 기준으로 분기한다. 이 결과들은 ErrorSummary가 아니라 폼 상태 영역에 보여 준다. ErrorSummary 제목은 입력 오류일 때만 쓴다. reauth면 `beginSignIn(returnTo)` 버튼을 준다. 대안으로 폼 feedback 슬롯에서 `TerminalErrorSurface`를 재사용할 수 있다 | +| 비용·부작용 | 폼 결과 상태가 늘어 샘플과 문서를 고쳐야 한다. 로그인 후 scope fence 재마운트로 폼 값이 사라지므로, 로그인 버튼 앞에 그 사실을 알려야 한다 | +| 완료 기준 | 401·403·429 저장 실패에서 서로 다른 문구와 행동(로그인/이동/재시도)이 나온다. "입력 내용을 확인해 주세요" 제목은 나오지 않는다 | +| 검증 방법 | `form-foundation.test.tsx`와 `reference-page.test.tsx`에 kind별 `it.each` 추가 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 08-02 오류 종류 38개 중 22개에 문구가 없어 "요청한 문구를 표시할 수 없습니다."가 오류 제목으로 나옴 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 6, 3, 21, 23, 24 | +| 근거 | 문구 키는 문자열 규칙으로 만든다: `src/contracts/errors.ts:52` `error.${kind.toLowerCase()}`. catalog에는 `error.*` 키가 16개뿐이다(`src/presentation/i18n/catalog.ts:130-145`). 없는 키는 `message-contract.ts:75-79`에서 `common.unavailable`로 바뀐다. probe로 누락 22개를 확인했다: CONFLICT, SCHEMA_MISMATCH, MALFORMED_JSON, CONTENT_TYPE_MISMATCH, ENVELOPE_MISMATCH, RESPONSE_BODY_LIMIT, MAPPING_CONTRACT_VIOLATION, RESULT_LIMIT_EXCEEDED, PAGINATION_CONTRACT_VIOLATION, QUERY_CACHE_FAILURE, UNKNOWN_CLIENT_FAILURE, SCOPE_GENERATION_CHANGED, IDENTITY_INTERN_LIMIT_EXCEEDED, DUPLICATE_IN_FLIGHT, VALIDATION_REJECTED 등. 목록 조회에 `SCHEMA_MISMATCH`를 주자 alert="요청한 문구를 표시할 수 없습니다. / 지원 정보 확인"이 나왔다. `check:i18n`(`scripts/check-i18n.ts:32-53`)은 locale 간 키가 같은지만 보고, registry와 catalog가 이어지는지는 보지 않는다(실행 결과 PASS) | +| 발생 조건 | 서버 응답 형식 불일치, 조회 중 409, 결과 상한 초과, 클라이언트 매핑 실패 등 | +| 영향 | 사용자는 "문구 누락" 안내를 오류 설명으로 읽는다. 문의할 때 무엇이 실패했는지 말할 수 없다. 새 FailureKind를 추가해도 어떤 검사도 실패하지 않아 같은 누락이 반복된다 | +| 심각도·우선순위 | Medium · P2 — 화면이 멈추지 않고 행동 버튼도 나온다. 다만 22개 종류에 걸쳐 있고 검출 수단이 없다 | +| 통제·증거 | M1(VD-06 결정 8에 원칙만 있음) · E2(probe) | +| 확실성과 남은 가정 | 누락은 확인했다. 일부 kind(TELEMETRY_FAILURE 등)는 화면에 오지 않을 수 있다. 어떤 kind가 화면에 오는지 정하는 일도 수정 범위에 들어간다 | +| 최소 개선 방향 | 화면에 올 수 있는 kind에 ko/en 문구를 추가한다. 테스트로 "`ERROR_REGISTRY`의 모든 `userMessageKey`가 catalog에 있거나 명시적 제외 목록에 있음"을 검사한다. 타입 제약으로 강제하는 방법도 있다 | +| 비용·부작용 | 문구 최대 22개 × 2 locale, 테스트 1개 | +| 완료 기준 | 누락 키가 0개이거나 제외 목록과 정확히 같다. 새 kind를 추가하면 테스트가 실패한다 | +| 검증 방법 | 단위 테스트 + 문구 하나를 지우는 결함 주입 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 08-03 결과 불명 저장을 확인 수단 없이 사용자가 판정하게 하고, "안 됨" 뒤 재제출은 새 멱등 키로 나감 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(정본 설계와 불일치) | +| 관련 관점 | 6, 12, 5, 17 | +| 근거 | 결과 불명 화면은 "변경됨으로 확인 / 변경되지 않음으로 확인" 두 버튼뿐이다(`async-surface.tsx:156-170`). 샘플 폼은 이 화면을 그대로 쓰고, 목록·상세 확인 링크가 없다(`reference-resource-form-page.tsx:129-141`). 제출할 때마다 intent를 새로 만든다(`application-query.ts:508-515`). 브라우저 factory는 create할 때마다 새 UUID 멱등 키를 준다(`src/adapters/platform/browser-mutation-intent-factory.ts:36-40`). probe: `MAYBE_APPLIED` → "변경되지 않음으로 확인" → 같은 값 재제출에서 키가 `key-1`, `key-2`로 달랐다. 정본 설계는 `docs/architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md:1707-1708`("같은 submit의 retry/reconcile에는 동일 intent/key, form value가 변경되면 새 intent")과 `:1721-1723`(inspect로 no effect를 확인한 뒤에만 사용자 재시도 허용)이다 | +| 발생 조건 | 저장 요청을 보낸 뒤 타임아웃·연결 끊김(`MAYBE_APPLIED`) → 사용자가 "변경되지 않음" 선택 → 같은 값으로 다시 저장 | +| 영향 | 첫 요청이 실제로 적용됐다면 서버는 두 요청을 다른 작업으로 보고 중복 생성한다. 사용자는 판단할 근거가 없다. 샘플은 create라 항목이 중복된다. 다운스트림이 주문·결제 폼에 복제하면 피해가 커진다 | +| 심각도·우선순위 | Medium · P2 — 사용자가 명시적으로 "안 됨"을 골라야 발생하고 자동 재전송은 막혀 있다. 하지만 기본 샘플의 결과 불명 처리가 근거 없는 선택으로 끝난다 | +| 통제·증거 | 자동 재전송 차단 M2 / 재제출 키 동일성 M0 · E2(probe) | +| 확실성과 남은 가정 | 클라이언트 동작은 확인했다. 서버가 멱등 키로 중복을 막는다는 계약은 repo 밖이다 | +| 최소 개선 방향 | ① 결과 불명 화면에 확인 행동을 넣는다: 목록·상세 재조회 링크, 또는 feature에 inspect operation이 있으면 조회. ② NOT_APPLIED 확인 뒤 같은 canonical input으로 재제출하면 이전 intent/key를 재사용하고, 값이 바뀌면 새 key를 만든다. admission에 이미 intent가 있다(`application-query.ts:514`) | +| 비용·부작용 | intent 보관 수명을 정해야 한다. inspect 계약은 feature마다 다르다 | +| 완료 기준 | 같은 값 재제출에 같은 멱등 키가 나간다. 결과 불명 화면에서 적용 여부를 확인할 경로가 있다 | +| 검증 방법 | `reference-page.test.tsx`에 키 비교 케이스 추가 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 08-04 샘플 화면 문구가 catalog 없이 코드에 박혀 있어 언어 전환이 적용되지 않음 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 23, 21, 20 | +| 근거 | `reference-resource-page.tsx:18-40`("새 항목 만들기", "새로고침", "총 N개 항목", "결과 확인 중"), `reference-resource-form-page.tsx:24-27`, `:64-70`, `:106-126`, `:143-145`, `reference-resource-detail-page.tsx:24-58`, `reference-resource-status-page.tsx:9-22`. feature catalog는 라우트 제목만 넣고, ko-KR 값도 영어다(`reference-message-catalog.ts:2-11`). 그래서 한국어 모드에서 제목은 영어, 본문은 한국어다. `check:i18n`은 공통 디렉터리 7개만 검사한다(`scripts/check-i18n.ts:55-63`). 한국어 literal이 있는 화면 파일 9개(feature 4, pages 1, examples 4)가 있어도 PASS였다. VD-06(`:69`)은 검사 범위를 "common UI"로 선언한다 | +| 발생 조건 | en-US로 바꾼 뒤 reference 화면에 들어갈 때 | +| 영향 | 버튼·결과 수·저장 완료 문구가 한국어로 남는다. 샘플을 복사하면 기능 화면마다 literal이 퍼지고, 나중에 번역할 때 전부 다시 찾아야 한다. feature가 자기 문구를 catalog에 넣는 방법(`installed-feature-messages.ts`)이 있는데 샘플이 그 방법을 보여 주지 않는다 | +| 심각도·우선순위 | Medium · P2 — 기능이 고장 나지는 않는다. 다만 복제되는 샘플이 반복 변경 비용을 만든다 | +| 통제·증거 | 공통 UI M3 / feature 화면 M1 · E2(`check:i18n` 실행, grep) | +| 확실성과 남은 가정 | 확인. 샘플 문구를 번역하지 않기로 한 결정이 있는지는 찾지 못했다 | +| 최소 개선 방향 | 샘플 문구를 `reference-message-catalog.ts`로 옮기고 message key로 렌더한다. `check:i18n` 범위에 `src/features/*/presentation`과 `src/presentation/pages`를 넣는다(examples는 명시적으로 제외해도 된다) | +| 비용·부작용 | 문구 약 30개, 검사 범위 확장 | +| 완료 기준 | en-US에서 reference 화면에 한국어 literal이 없다. `check:i18n`이 feature 화면 literal을 검출한다 | +| 검증 방법 | `check:i18n:fixture`에 feature 화면 사례를 추가하고, e2e i18n에 reference 화면 1개를 추가 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 08-05 axe 스캔이 보호 라우트 4개에서 실제 화면 대신 로그인 안내 화면만 검사함 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(검증 공백) | +| 관련 관점 | 10, 21 | +| 근거 | `tests/e2e/accessibility.spec.ts:5-22`는 라우트마다 `page.goto` 직후 axe를 돌린다. demo 세션의 기본값은 unauthenticated다(`tests/e2e/reference-route.spec.ts:22-24`에서 "세션이 필요합니다."를 확인). 그래서 REFERENCE_RESOURCE_LIST/DETAIL/FORM/STATUS는 같은 `ProtectedRoute` StatusPage를 네 번 검사한다. 로딩·오류·빈 상태, ErrorSummary가 뜬 폼, 결과 불명 화면도 검사하지 않는다(열린 다이얼로그 1건만 `:47-58`). visual 5건에도 reference 화면이 없다(`tests/visual/platform.visual.spec.ts`) | +| 발생 조건 | 항상 | +| 영향 | 목록·폼 화면의 접근성 회귀가 axe 게이트를 통과한다. "10개 라우트 통과"라는 결과가 실제 검사 범위보다 넓게 읽힌다 | +| 심각도·우선순위 | Medium · P2 | +| 통제·증거 | 공개 화면 M3 / 보호 화면 M0 · E1(테스트 코드 정독. Playwright는 실행하지 않음) | +| 확실성과 남은 가정 | 테스트 코드와 demo 기본 세션으로 확인했다 | +| 최소 개선 방향 | 보호 라우트는 "로그인 시작"을 누른 뒤 검사한다. `page.route`로 목록 성공·빈 결과·오류를 각각 응답해 상태별로 검사한다. 폼 제출 오류 상태도 검사한다 | +| 비용·부작용 | E2E 실행 시간이 늘어난다(3엔진) | +| 완료 기준 | 보호 라우트를 검사하기 전에 heading이 라우트 제목인지 assert한다. 상태별 검사가 있다 | +| 검증 방법 | heading assert로 검사 대상을 고정한 뒤 a11y spec 실행 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 08-06 수동 접근성 검토 기록 10건이 모두 pending이라 merge 게이트 FE-GATE-009가 통과할 수 없음 + +| 필드 | 내용 | +|---|---| +| 성격 | 미검증 | +| 관련 관점 | 10, 21, 26 | +| 근거 | `artifacts/tests/a11y-manual/*.md` 10개가 모두 `Status: pending-manual-review`다. worktree에서 `node scripts/verify-a11y-manual.ts`를 돌리자 "Manual accessibility evidence is incomplete"로 실패했다. `config/ci/gates.json`에서 FE-GATE-009는 `review-a11y-manual`(expect pass)을 포함하고, merge 단계 게이트다. `docs/accessibility/manual-checklist.md`는 axe 통과가 WCAG 준수가 아니라고 스스로 적는다 | +| 발생 조건 | 모든 PR의 merge 게이트 | +| 영향 | 키보드·스크린리더·포커스 복귀를 사람이 확인한 증거가 0건이다. CI에서 FE-GATE-009가 항상 실패하거나, 그 실패를 무시하는 운영이 굳어진다. 둘 중 어느 쪽인지는 확인하지 못했다 | +| 심각도·우선순위 | Medium · P2 — 문서는 한계를 정직하게 적었지만, 게이트 설계와 현재 상태가 서로 맞지 않는다 | +| 통제·증거 | M1 · E2(스크립트 실행) | +| 확실성과 남은 가정 | 스크립트 실패는 확인했다. CI가 이 게이트를 실제로 돌려 실패했는지는 CI 로그가 없어 확인하지 못했다(CI 영역) | +| 최소 개선 방향 | 릴리스 후보 하나로 10개 라우트 수동 검토를 한 번 수행한다. 또는 `review:a11y-manual`을 release 단계로 옮기고, merge 단계에는 기록 형식 검사만 둔다 | +| 비용·부작용 | 사람이 약 10개 화면을 검토해야 한다 | +| 완료 기준 | 서명된 기록 10건이 있거나, 게이트 단계를 조정하고 문서에 반영했다 | +| 검증 방법 | `pnpm review:a11y-manual` 통과 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 08-07 실패 화면이 문의 식별자를 보여 주지 않고, 라우트 렌더 실패 화면에는 다음 행동이 없음 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 8, 24, 28 | +| 근거 | `app-router.tsx:92-108` `RouteFailureSurface`: StatusPage에 `supportReference`도 action도 없다. 그런데 문구는 "문제가 계속되면 운영 지원 참조 정보를 확인하세요"다(`catalog.ts:77-78`). 청크 실패 화면(`chunk-recovery-boundary.tsx:115-121`)도 "지원 참조 정보를 확인해 주세요"(`catalog.ts:99-100`)라고 하지만 reason은 `data-` 속성에만 있다. 문서 `routing-pages-and-patterns.md:280`은 "안전한 support surface와 trace/build ID를 표시한다"고 한다. `TerminalErrorSurface`(`async-surface.tsx:60-89`)는 `AppFailure.requestId/traceId`를 쓰지 않는다. 샘플의 contact-support 행동은 고정 문자열 `REFERENCE-STATUS-DEMO` 페이지로 이동한다(`use-reference-failure-action.ts:33-35`, `reference-resource-status-page.tsx:22`). `reportRenderFailure`는 void라 화면에 돌려줄 ID가 없다(`application-api.ts:62`). 부트 실패 화면만 build·release·지원 참조를 보여 준다(`boot-error-shell.tsx`) | +| 발생 조건 | 라우트 렌더 오류, 청크 복구 실패, contact-support 성격의 조회 실패 | +| 영향 | 사용자가 문의할 때 줄 식별자가 없다. 운영자는 신고를 서버 requestId·빌드와 연결할 수 없다. 렌더 실패 화면은 URL이 바뀌기 전까지 풀리지 않는데 재시도 버튼이 없다(registry의 RENDER_FAILURE action은 reload-once다) | +| 심각도·우선순위 | Medium · P2 — 가이드 35.2의 "주요 진단 정보 부족"에 해당 | +| 통제·증거 | 문서 M1 / 구현 M0 · E1 | +| 확실성과 남은 가정 | 확인. 진단 이벤트에 상관관계 ID를 만드는 쪽은 영역 09·텔레메트리 소관이다 | +| 최소 개선 방향 | `RouteFailureSurface`와 `ChunkRecoverySurface`에 buildId와 짧은 incident ID를 `supportReference`로 표시하고, 같은 값을 진단 이벤트에 기록한다. `TerminalErrorSurface`는 requestId가 있으면 표시한다. contact-support로 이동할 때 식별자를 넘긴다. 렌더 실패 화면에 "한 번 새로고침" 버튼을 둔다 | +| 비용·부작용 | 진단 포트가 ID를 반환하도록 바뀐다(application 포트 변경) | +| 완료 기준 | 세 화면에 지원 참조 문자열이 보이고, 같은 값이 진단 이벤트에 있다 | +| 검증 방법 | render-boundary, chunk-recovery, async-surface 컴포넌트 테스트에 assert 추가 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 08-08 뒤로 가기에서 스크롤을 복원하지 않고 해시 대상도 무시함(문서 계약과 다름) + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 24, 10 | +| 근거 | `app-router.tsx:166-180`은 pathname/search가 바뀔 때마다 `window.scrollTo(0,0)`을 하고, 이동 종류(POP)를 보지 않는다. src 전체에 `ScrollRestoration`·`history.scrollRestoration`이 없다. `PageHeader`도 h1에 `focus()`(preventScroll 없음)를 한다. 문서는 `routing-pages-and-patterns.md:82`(Data Mode를 고른 이유에 scroll restoration 포함), `:292`(back/forward는 저장한 scroll 복원), `:294`(hash target 처리)다. jsdom에서는 scroll을 건너뛰고(`app-router.tsx:170`) 관련 테스트도 없다 | +| 발생 조건 | 긴 목록 → 상세 → 뒤로 가기. `/page#section` 링크 | +| 영향 | 목록에서 보던 위치를 잃는다. 해시 링크가 맨 위로 간다. 데이터 영향은 없다 | +| 심각도·우선순위 | Low · P2 — 편의 문제다. 다만 문서가 약속한 동작이고 모든 목록 화면에 복제된다 | +| 통제·증거 | M1(문서만) · E1 | +| 확실성과 남은 가정 | 코드에서 확인했다. 브라우저 자동 복원이 effect보다 먼저 일어나도 effect가 다시 맨 위로 보낸다 | +| 최소 개선 방향 | AppShell에 ``을 두고, `RouteLifecycle`의 scrollTo는 PUSH/REPLACE일 때만 실행한다. 해시가 있으면 대상으로 이동하고 포커스한다 | +| 비용·부작용 | h1 포커스와 스크롤 복원의 순서를 맞춰야 한다(`focus({preventScroll:true})`) | +| 완료 기준 | 브라우저에서 list → detail → back 시 이전 scrollY가 복원된다 | +| 검증 방법 | Playwright e2e 1건(jsdom에서는 불가) | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 08-09 목록 조회가 실패해도 결과 수 영역(role=status)이 "결과 확인 중"으로 남음 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 1, 23 | +| 근거 | `reference-resource-page.tsx:38-40` `query.data ? ... : "결과 확인 중"`. `CollectionPage`는 이 값을 `role="status"`로 렌더한다(`page-templates.tsx:119-123`). probe: `SERVER_FAILURE`일 때 alert="요청을 완료하지 못했습니다. 다시 시도"와 status="결과 확인 중"이 함께 나왔다. idle 상태에서도 같다 | +| 발생 조건 | 목록 조회 실패 또는 비활성 | +| 영향 | 화면과 보조기술에 "확인 중"과 "실패"가 동시에 전달된다. 샘플이 `state.base`가 아니라 `data` 유무로 상태를 판단하는 패턴을 퍼뜨린다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M0 · E2(probe) | +| 확실성과 남은 가정 | 확인 | +| 최소 개선 방향 | 결과 수는 `query.state.base`가 success/empty일 때만 보여 준다 | +| 비용·부작용 | 한 줄 수정 | +| 완료 기준 | 실패·로딩·idle에서 결과 수 status가 없다 | +| 검증 방법 | `reference-page.test.tsx`에 실패 시 status 텍스트 assert | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 08-10 언어를 바꿔도 이미 표시된 폼 오류 문구는 이전 언어로 남음 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 23 | +| 근거 | `use-app-form.ts:185-197`, `:214-222`, `:231-237`이 번역을 끝낸 문자열을 state에 저장한다. probe: 검증 오류 뒤 en-US로 바꾸자 "Review the entered information. Name: 입력값이 너무 짧습니다."가 나왔다 | +| 발생 조건 | 오류가 표시된 상태에서 언어 전환 | +| 영향 | 제목은 영어, 필드 오류는 한국어로 섞인다. 다시 제출해야 갱신된다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M0 · E2(probe) | +| 확실성과 남은 가정 | 확인 | +| 최소 개선 방향 | 오류를 message key(또는 issue code)로 저장하고 렌더할 때 번역한다 | +| 비용·부작용 | `FieldErrors` 타입이 바뀌어 `ErrorSummary`·`TextField` 호출부를 함께 고쳐야 한다 | +| 완료 기준 | 언어 전환 즉시 표시 중인 오류 문구가 바뀐다 | +| 검증 방법 | `locale-platform.test.tsx`에 케이스 추가 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 08-11 같은 인증 필요·권한 없음·없음 상태를 그리는 화면이 세 벌 있음 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 23, 9, 22 | +| 근거 | 세 벌은 다음과 같다. ① 라우트 수준 StatusPage(`app-router.tsx:213-272`, `route.auth.*` 문구). ② 조회 실패 `TerminalErrorSurface`(`async-surface.tsx:60-89`, `error.*`). ③ 디자인 시스템 `AuthRequiredSurface`/`ForbiddenSurface`/`NotFoundSurface`/`AccessSurface`(`state-surfaces.tsx`, `common-patterns.tsx:126-139`, `access.*`). 같은 403이 샘플에서는 "이 작업을 수행할 권한이 없습니다.", 갤러리와 visual snapshot에서는 "403 · 권한 없음 / 접근할 수 없습니다."로 나온다. `state-surfaces-light.png`는 실제 흐름에서 쓰지 않는 쪽을 고정하고 있다. Q-6.8-10은 라우트 수준만 StatusPage로 통합했다 | +| 발생 조건 | 다운스트림이 권한·인증 화면을 만들 때 | +| 영향 | 어느 것을 쓸지 매번 골라야 한다. 문구·디자인을 바꾸려면 세 곳을 고쳐야 한다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M0 · E1 | +| 확실성과 남은 가정 | 확인 | +| 최소 개선 방향 | `AsyncSurface`의 AUTH_REQUIRED/FORBIDDEN/NOT_FOUND 분기를 `AccessSurface`로 렌더한다. 또는 `state-surfaces`를 공개 barrel에서 빼고 한 가지만 권장한다 | +| 비용·부작용 | visual baseline 갱신 | +| 완료 기준 | 같은 실패 종류가 조회·갤러리에서 같은 컴포넌트와 문구로 나온다 | +| 검증 방법 | async-surface 테스트, visual 갱신 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 6.8-10 일부 미해결 | + +### 08-12 Pagination 페이지 링크가 Ctrl/Cmd/Shift 클릭까지 막아 새 탭 열기가 안 됨 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 24 | +| 근거 | `navigation.tsx:268-273`은 onClick에서 조건 없이 `preventDefault()`를 한다. 주석은 "href is for open-in-new-tab"이다. React Router `Link`는 사용자 onClick 뒤 `defaultPrevented`면 자체 처리도 건너뛴다(react-router 7.18.1 `handleClick`). 가운데 버튼(auxclick)은 열린다 | +| 발생 조건 | 수정키를 누른 채 페이지 번호 클릭 | +| 영향 | 새 탭 대신 현재 탭에서 페이지가 바뀐다. 주석과 동작이 다르다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M0 · E1 | +| 확실성과 남은 가정 | 확인 | +| 최소 개선 방향 | `button !== 0`이거나 수정키가 눌렸으면 return한 뒤 `preventDefault` | +| 비용·부작용 | 없음 | +| 완료 기준 | Ctrl 클릭에서 `onChange`가 호출되지 않는다 | +| 검증 방법 | `pagination.test.tsx`에 케이스 추가 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 08-13 상세 경로 `:resourceId`가 정적 경로 `new`·`status`와 겹쳐 그 ID의 항목을 열 수 없음 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 17, 1 | +| 근거 | `reference-feature-contract.ts:91`, `:104`, `:117`. ID 스키마는 1~120자 임의 문자열이다(`reference-schemas.ts:24-27`). React Router는 정적 세그먼트를 우선한다. 목록 링크는 `reference-resource-page.tsx:51`에 있다 | +| 발생 조건 | 서버 ID가 `new` 또는 `status`인 항목 | +| 영향 | 목록에서 누르면 생성 폼이나 상태 화면이 열린다. UUID 형태의 ID면 일어나지 않는다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M0 · E1 | +| 확실성과 남은 가정 | 라우팅 규칙으로 확인했다. 실제 서버 ID 형식은 repo 밖이다 | +| 최소 개선 방향 | 상세 경로를 `/…/items/:resourceId`처럼 분리하거나, ID 스키마에서 예약어를 거부한다 | +| 비용·부작용 | URL 변경 | +| 완료 기준 | ID `new`인 항목의 링크가 상세 화면을 연다 | +| 검증 방법 | 라우터 컴포넌트 테스트 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +## 5. 28개 관점 판정 (36.2) + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +|---|---|---|---|---|---| +| 1 | 코드 성숙도 | 적용 — 화면 상태 모델 | 목표 M4 / 확인 M4(`AsyncState` 타입으로 불가능한 조합 차단) | E2 | 부분 충족 — 샘플이 `data` 유무로 상태를 판단(08-09), 경로 충돌(08-13) | +| 2 | 구조적 성숙도 | 적용 — presentation 경계 | 목표 M3 / 확인 M3(ESLint로 adapters·bootstrap·ports/out import 금지, tanstack은 `adapters/query`만 허용, templates는 application 금지) | E1 | 충족 — 영역 안에서 위반 없음 | +| 3 | 변경 용이성 | 적용 — 오류 종류·라우트 추가 | 목표 M3 / 확인 M1 | E2 | 부분 충족 — 오류 종류를 추가해도 문구 누락이 검출되지 않음(08-02) | +| 4 | 인지 부하 | 적용 — 대표 과제 수행(2.2) | — | E1 | 부분 충족 — 생성 파일 경유, descriptor와 runtime 분리, 문자열 규칙 키, 버튼 표시 조건 두 곳 | +| 5 | 위험 가시성 | 적용 — 실패·결과 불명 표시 | 목표 M2 / 확인 M2 | E2 | 부분 충족 — 결과 불명은 드러나지만 확인 경로가 없음(08-03) | +| 6 | 실패 성숙도 | 적용 — 32.2 실패 구분 | 목표 M2 / 조회 M2, 폼 M0 | E2 | 부분 충족 — 폼 실패 합침(08-01), 문구 누락(08-02), 결과 불명(08-03) | +| 7 | 운영 성숙도 | 다른 영역 — 텔레메트리(09). presentation은 route·render 이벤트만 보낸다 | — | — | 적용 제외 | +| 8 | 디버깅 가능성 | 적용 — 화면의 문의 식별자 | 목표 M2 / 확인 M0(부트 화면 제외) | E1 | 미충족 — 08-07 | +| 9 | 유지보수 성숙도 | 적용 | — | E1 | 부분 충족 — 상태 화면 세 벌(08-11), 문서와 구현 불일치(08-07, 08-08) | +| 10 | 테스트 성숙도 | 적용 — 컴포넌트·E2E·visual 검출력 | 목표 M3 / 확인 M3(주입 4건 모두 검출) | E2 | 부분 충족 — 폼 인증·권한 실패, 스크롤, 보호 화면 axe(08-05), 샘플 i18n, visual에 샘플 화면 없음 | +| 11 | 데이터 성숙도 | 적용 제외 — presentation은 저장을 소유하지 않는다. 폼 값은 URL·storage에 남기지 않는다(`form-foundation.test.tsx:140`) | — | E2 | 적용 제외 | +| 12 | 동시성 성숙도 | 적용 — 응답 순서·중복 제출·세션 전환 | 목표 M3 / 확인 M3 | E2 | 부분 충족 — 결과 불명 뒤 새 멱등 키(08-03). 여러 탭은 영역 02 | +| 13 | 확장성 | 다른 영역 — 기능 수 증가(extreme-scale 문서, 영역 09) | — | — | 적용 제외 | +| 14 | 성능 성숙도 | 적용 — 경로별 lazy | 목표 M3 / 확인 M2(정적) | E1 | 부분 충족 — lazy 분리는 확인. 번들 수치는 미검증(`check:bundle` 미실행) | +| 15 | 보안 성숙도 | 적용 — XSS·외부 URL·클라이언트 가드 | 목표 M3 / 확인 M3(ESLint FE-OC-019 주입 검출, React 19 `javascript:` 차단, CSP) | E2 | 충족 — 클라이언트 가드가 UX용이라는 선언과 서버 403 표시 테스트도 있다 | +| 16 | 의존성 성숙도 | 다른 영역 | — | — | 적용 제외 | +| 17 | API / Contract 성숙도 | 적용 — route codec·URL 계약 | 목표 M3 / 확인 M3(zod parse 뒤에만 사용, canonical redirect, loop guard) | E2 | 부분 충족 — 08-13, 정본과 다른 intent/key 수명(08-03) | +| 18 | 배포 성숙도 | 일부 적용 — 청크 실패 복구 | 목표 M3 / 확인 M3 | E2 | 충족(화면 쪽) — 6.8-1/2/7 수정과 테스트 확인. 릴리스 전환은 다른 영역 | +| 19 | 설정 성숙도 | 일부 적용 — `routerBasePath` | 목표 M2 / 확인 M2(router `Link` 사용) | E2 | 충족 — `design-system-links.test.tsx` | +| 20 | 개발자 경험 | 적용 — 샘플·템플릿 사용성 | — | E1 | 부분 충족 — 샘플이 i18n·실패 분기 방법을 보여 주지 않음(08-01, 08-04) | +| 21 | Guardrail 성숙도 | 적용 | 목표 M3 / 확인 M3(레이어·HTML) / M1(i18n 범위, 문구 누락, 수동 a11y) | E2 | 부분 충족 — 08-02, 08-04, 08-05, 08-06 | +| 22 | 추상화 성숙도 | 적용 — AsyncSurface·templates·useApplicationMutation | — | E1 | 충족 — 템플릿이 데이터를 가져오지 않고 슬롯만 가진다. `application-query.ts` 875줄의 bound/legacy 겸용은 학습 비용이 크다(관찰만 기록) | +| 23 | 일관성 | 적용 | — | E2 | 부분 충족 — 08-04, 08-10, 08-11. 같은 실패의 조회·폼 응답이 다름(08-01) | +| 24 | 네이밍 / 의미 성숙도 | 적용 | — | E1 | 부분 충족 — 문구·문서가 약속한 동작을 구현하지 않음(08-07, 08-08, 08-12) | +| 25 | 조직 확장성 | 구조적 준비만 평가 — feature별 catalog·route 기여 지점은 있다 | — | E1 | 적용 제외(1인 관리 전제) | +| 26 | Ownership 성숙도 | 일부 — 수동 a11y 검토 책임자 없음 | — | E2 | 미검증 — 08-06 | +| 27 | 삭제 가능성 | 다른 영역 — reference feature 제거(영역 09) | — | — | 적용 제외 | +| 28 | 회복 가능성 | 적용 — 화면 오류 복구 | 목표 M2 / 확인 M2 | E2 | 부분 충족 — 청크 실패는 reload 버튼 있음. 렌더 실패는 URL 변경 전까지 행동이 없음(08-07) | + +## 6. 미검증 목록 + +- **실제 스크린리더 발표.** 새로 마운트되는 `aria-live` 영역(LoadingSurface, EmptySurface)이 발표되는지, 라우트 이동 발표가 중복되는지, TextArea 글자 수 ``이 입력마다 발표되는지 확인하지 않았다. → NVDA/VoiceOver 수동 검토(08-06과 함께) +- **Playwright E2E·visual·storybook.** 브라우저와 포트를 공유하는 환경이라 실행하지 않았다. 08-05, 08-08은 코드 정독 근거다. → `test:e2e`, `test:a11y`, `test:visual` 실행 +- **번들 크기.** 경로별 lazy 분리는 정적으로 확인했다. `dist/`는 9/24 빌드이고, 새 빌드는 공유 경로에 쓰기 때문에 재측정하지 않았다. → `check:bundle` +- **HTTP 상태 → FailureKind·effect 분류.** 08-01과 08-03은 어댑터가 401/403을 NOT_APPLIED로, 타임아웃을 MAYBE_APPLIED로 분류한다는 전제 위에 있다. → 영역 03 +- **세션 만료 시 폼 초안 폐기.** scope fence 재마운트로 작성 중 값이 확인 없이 사라진다. 의도된 데이터 폐기 정책인지 문서에서 찾지 못했다 +- **FE-GATE-009의 실제 CI 결과.** 로그가 없다. → CI 영역 +- **상세 URL 직접 접속의 정적 호스팅 fallback.** → 배포 영역 diff --git a/docs/reviews/2026-09-25-maturity-review/09-app-core.md b/docs/reviews/2026-09-25-maturity-review/09-app-core.md new file mode 100644 index 00000000..70ee8fee --- /dev/null +++ b/docs/reviews/2026-09-25-maturity-review/09-app-core.md @@ -0,0 +1,313 @@ +# 애플리케이션 코어·기능·조립 성숙도 리뷰 + +> 검토일: 2026-09-25 · 기준: `main` / `4626b73` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 범위: `src/application/`(3.5k줄), `src/features/`(2.8k줄), `src/bootstrap/`(2.1k줄), `src/platform/`(2.6k줄), `src/apps/`, `src/contexts/`(각 0.05k줄). 약 10.9k줄. 생성기 `scripts/generate-product-feature-index.ts`, 제거 검증 `scripts/test-sample-removal.ts`, 이 영역을 검증하는 `tests/features/`, `tests/platform/`, `tests/unit/`의 application·bootstrap 관련 테스트, `tests/runtime-schema/runtime-config.test.ts` +> 영역 판정(35.8): **조건부 사용 가능** — 기능 1개(reference-feature를 교체하는 방식) 범위에서 사용 가능. 기능을 2개 이상 설치하는 용도는 09-01 해결 전 사용 보류. `VITE_PRODUCT_FEATURES`로 기능을 빼는 배포는 09-02 해결 전 사용 보류. + +## 1. 결론 + +- **기능을 하나 더 설치하면 중앙 조립 파일 3곳이 타입 검사에서 깨진다(09-01, High).** 격리 worktree에서 local-draft 기능에 `feature-module.ts`만 추가하자 `installed-feature-adapters.ts`, `installed-feature-runtimes.tsx`, `installed-feature-contracts.ts`에서 tsc 오류 8건이 났다. "기능을 추가해도 이 composer는 바뀌지 않는다"는 주석(`src/features/installed-feature-adapters.ts:17-18`)은 기능이 1개일 때만 맞다. TS 규모 게이트는 실제 composer를 거치지 않는 합성 fixture로 측정한다. +- **부트 실패 경로가 원인을 잃는다.** 모듈 평가 단계의 throw(예: `VITE_PRODUCT_FEATURES` 오타)는 `boot()`의 try 밖에서 나서 정적 셸이 "불러오는 중"으로 멈춘다(09-03). 설정·매니페스트 외 오류는 `BOOT_CONFIG_FAILURE`로 잘못 표시되고 오류 객체는 콘솔·수집기 어디에도 남지 않는다(09-04). +- **`VITE_PRODUCT_FEATURES`는 소비자마다 다르게 적용된다(09-02).** 브라우저 번들은 이 값을 적용하지만 Node 빌드 스크립트(계약 세트 생성)와 라우터의 context 인덱스는 무시한다. 오타는 빌드를 통과하고 브라우저에서만 터진다. +- **IndexedDB 기능 경로는 조립까지 이어지지 않는다(09-05, 09-06).** 부트스트랩은 `http`·`telemetry`만 제공해서 IndexedDB를 쓰는 기능을 설치하면 부트가 `TypeError`로 실패한다. local-draft 샘플은 도메인 규칙(`createLocalDraft`)을 어느 쓰기 경로에서도 호출하지 않는다. +- **잘 막혀 있는 것:** 직전 리뷰 6.9-1~6.9-12는 현재 코드에서 모두 고쳐진 것을 확인했다. `AUTH_MODE=demo`는 스키마·프로필 생성·release admission 세 단계에서 staging/production 진입이 막힌다. 설정 문서는 strict 스키마로 오타 최상위 키를 거부하고, 부트 JSON은 크기·시간·타입 상한 안에서 읽는다. +- **미검증:** `test:sample-removal` 전체 실행, 부트 실패 경로의 실제 브라우저 동작, `check:architecture` 위반 주입(이 환경에서 pnpm 의존성 검사가 막혀 실행하지 못함). + +## 2. 범위와 방법 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 | `clean-architecture-frontend-template`, `main` / `4626b73`, 2026-09-25 | +| 목적·실행 구성 | 프론트엔드 템플릿. 브라우저 SPA, 정적 호스팅, SSR 없음. 여러 탭 지원 | +| 읽은 코드 | 범위 내 파일 전부. 부트 경로(`main.tsx` → `create-runtime-composition.ts` → `composition-root.ts` → `runtime-adapters.ts`), 설정·매니페스트 로더, 기능 설치 표면(`installed-*`), 두 샘플 기능 전체, `platform/release`·`platform/telemetry`·`platform/execution`. 연결 확인용으로 `src/contracts/{release-artifacts,product-features,deployment-admission,contract-set}.ts`, `src/presentation/routes/app-router.tsx`(context 라우팅 부분), `src/adapters/diagnostics/bounded-diagnostics.ts`, `src/adapters/http/http-execution-v3.ts`(intent 검증 부분) | +| 읽은 설정·스크립트 | `.dependency-cruiser.json`, `config/runtime/*.json`, `public/config.json`, `config/contracts/registry-governance.json`, `config/testing/risk-coverage.json`·`test-evidence.json`, `config/ci/gates.json`(스크립트 목록), `package.json` scripts, `scripts/{generate-product-feature-index,test-sample-removal,generate-runtime-config,check-release-admission,build-frontend,generate-contract-set}.ts`, `scripts/scale/collect-tsc-diagnostics.ts` | +| 실행한 테스트 | `node scripts/run-vitest.ts run tests/features tests/platform tests/runtime-schema/runtime-config.test.ts` + `tests/unit/`의 14개 파일(runtime-adapters, chunk-recovery(-runtime), application-boundary, product-features, installed-feature-messages, optional-runtime-host, read-bounded-boot-json, product-index-entrypoints, runtime-capability-snapshot, color-scheme, compatibility, release-coherence) → **62 files / 397 tests 통과** | +| 실험 1 (격리 worktree) | `src/features/local-draft-feature/`에 `feature-module.ts`·`context-routes.ts` 추가 → 생성기 실행 → `tsc -p tsconfig.app.json`: **3개 파일 8건 오류**. 같은 상태에서 `tests/unit/runtime-adapters.test.ts`: **15건 중 12건 실패**, 모두 `TypeError: Cannot read properties of undefined (reading 'get')`. 실험 후 worktree 삭제 | +| 실험 2 | `VITE_PRODUCT_FEATURES=none node -e "import('./src/features/installed-product-manifest.ts')…"` → Node에서는 `["reference-feature"]`, 계약 기여 1건 그대로 | +| 실험 3 | `VITE_PRODUCT_FEATURES=reference-featrue node scripts/run-vitest.ts run tests/unit/runtime-adapters.test.ts` → 모듈 import 시점에 `installed-product-manifest.ts:43`에서 throw, 테스트 0건 실행 | +| 실험 4 | `tests/features/` 최상위 3개 파일 단독 실행 → 4건 통과. 이 파일들을 실행하는 package script·CI 게이트는 없음 | +| 확인하지 못한 것 | `test:sample-removal`(복제본에서 typecheck·전체 테스트·coverage·build를 돌리는 무거운 스크립트라 읽기로 대신함). `check:architecture` 위반 주입(worktree에서 `pnpm`의 의존성 상태 검사가 install을 시도하다 중단됨. 공유 `node_modules/.pnpm-workspace-state-v1.json`이 다른 에이전트의 `/tmp/security-followup-producer-*` 경로로 반복 갱신되는 중이었다). 부트 실패 경로의 실제 브라우저 동작(정적 추적과 vitest import 실험으로 대신함) | +| 직전 리뷰와 비교 | 6.9-1(reload 무한 반복), 6.9-5(킬스위치), 6.9-6(featureId 중복), 6.9-7(listener), 6.9-8(boot shell), 6.9-9(reload guard 통합), 6.9-10(safe error), 6.9-12(구조 정리)는 현재 코드를 읽어 고쳐진 것을 확인했다. 6.9-2·6.9-3·6.9-11(텔레메트리)은 수정 코드를 읽었고 해당 테스트가 통과했다. 6.9-8은 고쳐졌지만 모듈 평가 단계 실패가 남는다(09-03) | + +## 3. 확인된 강점 + +1. **개발용 인증이 공개 환경에 못 들어간다.** 세 단계가 따로 막는다. 브라우저 스키마는 `APP_ENV`가 local/development가 아니면 `AUTH_MODE: demo`를 거부한다(`src/contracts/release-artifacts.ts:103-109`). 프로필 생성은 `APP_ENV`와 빌드 대상이 다르면 멈춘다(`scripts/generate-runtime-config.ts:47-51`). release admission(FE-GATE-027)은 staging/production에 demo·placeholder ID·비 HTTPS를 거부한다(`src/contracts/deployment-admission.ts:69-107`). 외부 인증 owner가 없으면 세션이 fail-closed다(`src/bootstrap/runtime-adapters.ts:304-309`). +2. **설정 문서 검증이 엄격하다.** 최상위 키 오타는 `.strict()`로 거부된다(`src/contracts/release-artifacts.ts:160-171`, 테스트 `tests/runtime-schema/runtime-config.test.ts:75`). 선택 기능 설정은 필요할 때만 요구한다(`TELEMETRY_ENDPOINT`는 `TELEMETRY_ENABLED`일 때만, `release-artifacts.ts:96-102`). 부트 JSON은 5초·64KB/1MB·`redirect: "error"`·fatal UTF-8 안에서 읽는다(`src/bootstrap/read-bounded-boot-json.ts:17-28`, `:85-131`). +3. **부트스트랩은 기능의 공개 표면만 조합한다(32.4).** `src/bootstrap/`의 기능 import는 `features/installed-*` 6개 파일뿐이다. 기능끼리 import는 `.dependency-cruiser.json`의 `features-do-not-import-other-features`가 막는다. 킬스위치로 끈 기능은 입력 자체가 만들어지지 않는다(`src/features/installed-feature-adapters.ts:26-37`, 테스트 `tests/unit/runtime-adapters.test.ts:284`). +4. **reload 반복이 구조적으로 막혀 있다.** boot mismatch와 chunk 실패가 같은 guard를 쓰고, 키와 무관하게 TTL 안 두 번째 reload를 거부하며, 마커가 실제로 저장된 경우에만 reload를 허용한다(`src/platform/release/release-mismatch-recovery.ts:114-165`). 마커는 탭별 sessionStorage다(`src/contracts/storage-keys.ts:61-69`). +5. **reference-feature의 쓰기 경로가 경계에서 검증된다.** create 명령은 HTTP 계약의 `inputValidator`(zod, trim·1..120자)를 통과해야 나가고(`src/features/reference-feature/contracts/reference-feature-contract-contribution.ts:158-161`), KEYED 명령은 intent가 없으면 전송 전에 거부된다(`src/adapters/http/http-execution-v3.ts:375-378`). 재시도 예산 0과 결과 불명 처리가 계약에 적혀 있다(`reference-feature-contract-contribution.ts:37-47`, `:190-203`). + +## 4. 발견 사항 (36.3) + +### 09-01 기능을 2개 이상 설치하면 중앙 조립 파일이 타입 검사에 실패한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 3, 13, 20, 21, 22, 25, 10 | +| 근거 | 중앙 조립 파일이 설치 모듈 배열의 **유니언 원소**에 `flatMap`을 호출한다: `src/features/installed-feature-adapters.ts:8-10`, `src/features/installed-feature-runtimes.tsx:6-8`. 라우트 레지스트리는 `typeof PLATFORM_ROUTE_REGISTRY & InstalledFeatureContract["routes"]`로 캐스트한다(`src/features/installed-feature-contracts.ts:21-27`). 기능이 1개면 유니언이 아니라서 통과한다. **실험 1**: local-draft에 `feature-module.ts`만 추가하자 tsc 오류 8건(`installed-feature-adapters.ts:9,13,33`, `installed-feature-runtimes.tsx:7,14,24`, `installed-feature-contracts.ts:97,113`). TS 규모 게이트는 `installed-*`를 거치지 않는 합성 모듈을 컴파일한다(`scripts/scale/collect-tsc-diagnostics.ts:70-104`). `tests/contract/reusable-capability/feature-adapter-composition.test.ts`는 2개 기여를 런타임 함수로만 합친다 | +| 발생 조건 | 다운스트림이 기능을 하나 더 추가하거나, reference-feature를 남긴 채 첫 제품 기능을 추가 | +| 영향 | `check:types:app`(CI 필수 게이트)이 실패해서 머지할 수 없다. 해결하려면 중앙 composer의 제네릭 타입을 고쳐야 한다. 설계가 없애려던 "중앙 파일 수정"이 모든 다운스트림에서 첫 기능 추가 때 생긴다. `vite build`는 타입 검사를 안 하므로 런타임 동작 자체는 별개다 | +| 심각도·우선순위 | High · P1 — 템플릿의 주 사용 경로(기능 추가)가 필수 게이트에서 막힌다. 샘플을 복사한 모든 다운스트림에 복제된다. 선언된 규모 목표(context당 200 기능, app당 20 context)와 정면으로 어긋난다 | +| 통제·증거 | 목표 M3(다기능 typecheck fixture) / 확인 M0 · E3(격리 worktree 컴파일 실험) | +| 확실성과 남은 가정 | 오류 8건은 직접 재현했다. 두 번째 기능의 모양을 reference와 똑같이 맞추면 일부 오류가 줄 수는 있지만, featureId 리터럴이 다르면 `flatMap` 추론 실패는 남는다(오류 메시지가 첫 유니언 원소로 `U`를 고정함을 보여 준다) | +| 최소 개선 방향 | `flatMap` 대신 원소 타입을 넓힌 명시 루프(`const contributions: ContributionShape[] = []`)로 모으고, 라우트 레지스트리는 유니언의 교집합이 아니라 `UnionToIntersection` 또는 `Record`으로 넓힌다. 기능 2개(모양이 다른) 설치 상태를 컴파일하는 typecheck fixture를 FE-GATE-003에 추가한다 | +| 비용·부작용 | 좁은 리터럴 타입 일부를 잃을 수 있다(`ROUTE_REGISTRY` 키 자동완성 등). fixture 1개와 CI 스크립트 1줄 추가 | +| 완료 기준 | reference-feature + 모양이 다른 두 번째 기능(예: local-draft)을 설치한 상태에서 `check:types:app` 통과 | +| 검증 방법 | 새 typecheck fixture가 CI에서 실행되고, composer를 원래대로 되돌리면 그 fixture가 실패하는지 확인 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 09-02 `VITE_PRODUCT_FEATURES`가 번들·빌드 스크립트·라우터에서 다르게 적용된다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(오타 경로·Node 무시) + 구조적 위험(계약 세트 불일치) | +| 관련 관점 | 19, 17, 18, 21, 24, 6 | +| 근거 | 선택값을 `import.meta.env`에서 모듈 평가 시점에 읽는다(`src/features/installed-product-manifest.ts:22-46`). Node에는 `import.meta.env`가 없어서 무시된다. **실험 2**: `VITE_PRODUCT_FEATURES=none`에서도 Node는 `["reference-feature"]`. 계약 세트 생성(`scripts/generate-contract-set.ts:10`)은 Node에서 전체 집합으로 매니페스트를 만들고, 브라우저는 좁힌 집합으로 검증한다(`src/bootstrap/load-release-manifest.ts:296-301`, `src/contracts/contract-set.ts:89-93`). 라우터는 선택을 거치지 않은 생성 context 인덱스를 쓴다(`src/apps/template-app.ts:10-14` → `src/presentation/routes/app-router.tsx:505`). "모든 registry가 선택을 따른다" 테스트는 `src/features/installed-*`만 검사한다(`tests/unit/product-features.test.ts:175-209`). **실험 3**: 오타는 import 시점 throw. 주석도 서로 다르다: `src/contracts/env.ts:59-61`은 "번들에 안 들어간다", `src/contracts/product-features.ts:10-13`은 "번들을 줄이지 않는다" | +| 발생 조건 | 배포 빌드에서 `VITE_PRODUCT_FEATURES`를 설정 | +| 영향 | (a) 오타 → 빌드·Node 검증은 통과하고 모든 사용자의 브라우저에서 부트가 멈춘다(09-03 경로). (b) 제외한 기능에 외부 계약 패키지가 있으면 매니페스트에는 들어가고 브라우저 기대값에는 없어서 매 부트가 `CONTRACT_SET_PACKAGE_UNEXPECTED`로 실패한다. (c) 제외한 기능의 URL은 context 라우트로 매칭된 뒤 `getRoute`에서 "Unregistered route" 오류 화면으로 간다(`app-router.tsx:308`, 정적 추적) | +| 심각도·우선순위 | Medium · P2 — 지금 저장소에서는 옵션을 안 쓰고 reference-feature가 TEMPLATE_FIXTURE라 (b)가 발동하지 않는다. 이 옵션을 쓰는 배포에는 P1 | +| 통제·증거 | 목표 M3 / 확인 M1(주석·단위 테스트만) · E2(실험 2·3) | +| 확실성과 남은 가정 | (a)·Node 무시는 재현했다. (b)는 코드 경로로 확정했지만 외부 패키지를 가진 기능이 없어 실행하지 못했다. (c)는 정적 추적만 했다 | +| 최소 개선 방향 | 선택을 빌드 입력 하나로 만든다. 생성기(`generate-product-feature-index.ts`)가 `VITE_PRODUCT_FEATURES`를 읽어 선택된 기능만 생성 인덱스에 넣으면, 번들·Node 스크립트·context 인덱스가 같은 집합을 보고 오타는 생성 단계에서 실패한다. 대안: Node 스크립트가 `process.env`로 같은 선택을 적용하고 build 첫 단계에서 값을 검증 | +| 비용·부작용 | 생성기 변경과 생성기 테스트 추가. 선택을 바꾸면 재생성이 필요해진다(이미 모든 진입점이 생성기를 먼저 돈다) | +| 완료 기준 | 잘못된 값은 `pnpm build` 첫 단계에서 실패한다. `VITE_PRODUCT_FEATURES=none` 빌드의 `contractSet`·생성 context 인덱스·번들에 제외 기능이 없다 | +| 검증 방법 | 생성기 단위 테스트 + 선택값을 준 빌드에서 매니페스트·dist 문자열 검사 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 09-03 모듈 평가 단계에서 실패하면 부트 셸이 "불러오는 중"으로 멈춘다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 6, 8, 7 | +| 근거 | try/catch는 `boot()` 함수 안만 감싼다(`src/bootstrap/main.tsx:24-52`). 정적 import 그래프에서 모듈 최상위 코드가 throw하면 `main.tsx` 본문이 실행되지 않는다. 최상위 throw 지점: `installed-product-manifest.ts:43`(선택값), `installed-feature-messages.ts:39-41`(메시지 키 중복), `installed-feature-contracts.ts:21-82`(라우트·operation·schema 조합 검증), `installed-feature-runtimes.tsx:10-28`, `installed-contract-contributions.ts:15`. 정적 셸에는 타임아웃·`error` 핸들러가 없다(`index.html:10-22`). 실험 3으로 import 시점 throw를 확인했다 | +| 발생 조건 | 잘못된 `VITE_PRODUCT_FEATURES`, 기능 간 메시지 키·라우트 ID 중복, 조합 검증 실패가 있는 빌드가 배포됨 | +| 영향 | 모든 사용자가 `aria-busy` 로딩 표시만 무기한 본다. `BootErrorShell`·부트 진단 기록·release mismatch 자동 복구가 모두 건너뛰어진다. 원인은 브라우저 콘솔의 uncaught 오류뿐이다 | +| 심각도·우선순위 | Medium · P2 — 결정적 빌드 결함이라 배포 전 브라우저 스모크로 잡힐 수 있다. 다만 production 전용 빌드 변수(09-02)는 CI e2e 빌드와 다를 수 있다 | +| 통제·증거 | 목표 M2 / 확인 M0 · E2(import 실험) + E1(정적 추적) | +| 확실성과 남은 가정 | ES 모듈 평가 순서상 확정이다. 실제 브라우저 화면은 실행하지 않았다 | +| 최소 개선 방향 | `main.tsx`가 앱 그래프를 `await import("./create-runtime-composition.ts")`로 불러와 모듈 평가 실패도 같은 catch로 받게 한다. 또는 `index.html`에 작은 인라인 `error`/타임아웃 처리를 둔다 | +| 비용·부작용 | 동적 import 한 번이 추가된다(첫 로드에 청크 하나). 인라인 스크립트는 CSP 해시 관리가 필요하다 | +| 완료 기준 | 모듈 최상위 throw를 넣은 빌드에서 `BootErrorShell`이 뜬다 | +| 검증 방법 | 잘못된 `VITE_PRODUCT_FEATURES`로 빌드한 fixture를 Playwright로 열어 오류 화면 확인 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 6.9-8 후속 — 정적 셸은 추가됐으나 모듈 평가 실패 경로가 남음 | + +### 09-04 설정·매니페스트 외 부트 오류가 `BOOT_CONFIG_FAILURE`로 표시되고 원인이 버려진다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 8, 6, 7, 24 | +| 근거 | 알 수 없는 오류는 `safe = { supportReference: "boot:unknown" }`만 넘긴다(`src/bootstrap/main.tsx:38-41`). `BootErrorShell`의 기본값이 `kind="BOOT_CONFIG_FAILURE"`, `code="BOOT_FAILED"`라서 설정 문제로 표시된다(`src/presentation/boundaries/boot-error-shell.tsx:12-19`). 오류 객체는 콘솔에 찍지 않고, `recordBootFailure`는 모듈 메모리에만 저장한다(`src/adapters/diagnostics/bounded-diagnostics.ts:80-106`, `getLastBootEvidence`를 부르는 src 코드 없음). 스키마 실패 시 어느 키가 틀렸는지(issue path)도 버린다(`src/bootstrap/load-runtime-config.ts:117-131`). **실험 1**에서 기능 조립 실패가 `TypeError`로 나는 것을 확인했다. 이 오류는 브라우저에서 이 경로로 간다 | +| 발생 조건 | 조립 단계 버그(09-05 같은 capability 누락, 기능 입력 생성 throw), 설정 파일 수기 편집 오류 | +| 영향 | 개발자·운영자가 "설정 실패"로 오진한다. 스택·메시지가 없어서 브레이크포인트 없이는 원인을 찾을 수 없다. 부트 실패율은 어떤 수집기에도 도달하지 않는다(설정 전이라 endpoint가 없음) | +| 심각도·우선순위 | Medium · P2 — 데이터 피해는 없고 진단 비용이 모든 다운스트림에 반복된다 | +| 통제·증거 | 목표 M2 / 확인 M1 · E1 | +| 확실성과 남은 가정 | 코드 경로로 확정. 브라우저 확장 오류 리포터가 따로 있으면 일부 보완될 수 있다 | +| 최소 개선 방향 | 알 수 없는 오류에는 `kind: "BOOT_UNEXPECTED_FAILURE"`와 build ID를 넣는다. 개발 빌드에서는 `console.error(error)`를 남긴다. 스키마 실패의 issue path 목록(키 이름만, 값 제외)을 safe 필드에 싣는다 | +| 비용·부작용 | 키 이름 노출은 값이 아니므로 비밀 노출 위험이 낮다. i18n 문구 1~2개 추가 | +| 완료 기준 | 조립 단계 `TypeError`가 `BOOT_UNEXPECTED_FAILURE`로 표시되고, 개발 콘솔에 원 오류가 남는다. 오타 키 설정은 틀린 키 이름을 보여 준다 | +| 검증 방법 | `createRuntimeComposition`에 throw를 주입하는 컴포넌트 테스트, 잘못된 config.json으로 Playwright 부트 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음(6.9-10은 값 누출 방향이었고 고쳐짐) | + +### 09-05 IndexedDB capability가 부트스트랩에 없고, `needs`가 런타임에서 검사되지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 2, 3, 5, 22, 20, 30.5 | +| 근거 | 부트스트랩이 기능에 주는 capability는 `http`, `telemetry` 둘뿐이다(`src/bootstrap/runtime-adapters.ts:560-566`). 타입은 `indexedDb`를 선언한다(`src/features/feature-adapter-contribution.ts:46-51`). 조합 함수는 기여의 `needs`를 실제 context와 대조하지 않는다(`feature-adapter-contribution.ts:161-190`). **실험 1**: local-draft 설치 시 `runtime-adapters.test.ts` 12/15 실패, `TypeError: Cannot read properties of undefined (reading 'get')`(`create-local-draft-feature-input.ts:29`). IndexedDB 저장소 조립(codec·migration·storage policy·scope token)의 유일한 예시는 브라우저 테스트 안에 있다(`tests/browser-capabilities/local-draft-composition.spec.ts:44-150`). 문서는 이 경로를 "두 번째 실행 가능한 contribution 모양"으로 소개한다(`docs/architecture/frontend-application-foundation.md:125-138`) | +| 발생 조건 | 다운스트림이 local-draft를 본떠 IndexedDB 기능을 설치 | +| 영향 | 부트가 실패하고 09-04 때문에 "설정 실패"로 보인다. 타입 검사는 09-01 때문에 `unknown`으로 무너져 누락을 잡지 못한다. 다운스트림은 production 조립 코드를 테스트 파일에서 옮겨 와 중앙 `runtime-adapters.ts`를 고쳐야 한다 | +| 심각도·우선순위 | Medium · P2 — 문서화된 선택 경로가 부트 실패로 끝나지만, 기본 구성(reference만 설치)에는 영향이 없다 | +| 통제·증거 | 목표 M3(타입) + M2(런타임 검사) / 확인 M1 · E3(실험 1) | +| 확실성과 남은 가정 | 재현했다. 09-01이 고쳐지면 타입 검사가 누락을 잡을 가능성이 높지만 확인하지 않았다 | +| 최소 개선 방향 | `composeFeatureAdapterInputs`가 `needs`의 각 capability가 context에 있는지 확인하고, 없으면 `feature needs indexedDb, which the host did not provide`로 throw한다. IndexedDB provider 조립을 opt-in recipe(`recipes/`)나 `runtime-adapters.ts`의 주석 처리된 슬롯으로 제공한다 | +| 비용·부작용 | 런타임 검사 몇 줄. recipe는 codec·migration 결정을 다운스트림에 남겨야 한다 | +| 완료 기준 | capability를 안 준 채 local-draft를 설치하면 기능 ID와 빠진 capability 이름이 담긴 오류가 난다. 문서의 조립 예시가 src 또는 recipes에 있다 | +| 검증 방법 | `feature-adapter-composition.test.ts`에 capability 누락 케이스 추가 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 09-06 local-draft 샘플의 도메인 규칙이 쓰기 경로에서 적용되지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 1, 10, 24, 30.5 | +| 근거 | 규칙(trim, 빈 ID·제목 금지, 제목 160자·본문 100,000자 상한)은 `createLocalDraft`에 있다(`src/features/local-draft-feature/domain/local-draft.ts:7-21`). 이 함수는 src·tests 어디서도 호출되지 않는다. `saveDraft`는 `LocalDraft` 모양의 객체를 그대로 저장소에 넘긴다(`application/local-draft-api.ts:61-64` → `adapters/local-draft-indexeddb-store.ts:54-61`). `LocalDraft`는 브랜드 없는 plain 타입이라 리터럴 객체로 만들 수 있다(`local-draft.ts:1-5`) | +| 발생 조건 | 호출자가 `createLocalDraft`를 거치지 않고 `{ draftId, title, body }`를 만들어 저장 | +| 영향 | 빈 제목, 공백 ID, 상한 초과 본문이 IndexedDB에 저장된다. 이 샘플을 IndexedDB 기능 패턴으로 복사한 다운스트림은 "도메인 규칙이 있다"고 믿지만 실제로는 UI 검증에만 의존한다(1절 위험 신호) | +| 심각도·우선순위 | Medium · P2 — 로컬 데이터 한정이지만 샘플로 복제되는 패턴이다 | +| 통제·증거 | 목표 M2 / 확인 M0(규칙 코드는 있으나 적용 경로 없음) · E1 | +| 확실성과 남은 가정 | 코드 경로로 확정. 저장소 codec이 검증할 수는 있으나 codec은 src에 없다(테스트 codec은 타입만 확인) | +| 최소 개선 방향 | `saveDraft`에서 `createLocalDraft(command.draft)`를 호출하고 실패를 `VALIDATION_REJECTED` Result로 돌려준다. 또는 `LocalDraft`를 브랜드 타입으로 만들어 팩터리만 만들 수 있게 한다 | +| 비용·부작용 | 몇 줄. throw를 Result로 바꾸는 매핑 필요 | +| 완료 기준 | 빈 제목·상한 초과 draft 저장이 저장소 호출 없이 거부된다 | +| 검증 방법 | local-draft API 단위 테스트(경계값: 160/161자, 공백 ID) | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 09-07 기능 추가·제거가 중앙 정책 파일 여러 곳을 요구하고, 제거 검증은 샘플 전용·일부 게이트만 돈다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 3, 27, 4, 20, 25, 21 | +| 근거 | **제거**(`scripts/test-sample-removal.ts`가 하는 일): 디렉터리 4개(`src/features/reference-feature`, `tests/features/reference-feature`, `src/contexts/reference-context`, `tests/mocks`) + 개별 테스트 4개 + typecheck fixture 16개 삭제(`:41-67`), 생성 인덱스 재생성(`:131`), runtime 프로필 4개(`:138-161`), `risk-coverage.json`의 목록 4개·baseline 숫자(`:163-188`), `test-evidence.json`(`:190-216`), `registry-governance.json`(`:218-252`), `package.json` 스크립트 12개(`:254-275`), CI 계약·workflow 재생성(`:276-285`). 즉 중앙 정책 파일 8종 이상. 이후 실행하는 게이트는 typecheck·architecture·registry 구조(`--no-baseline`)·test:all·coverage·evidence source·check:ci·home smoke·build뿐이다(`:302-335`). `lint`, baseline 포함 `check:registries`, `check:i18n`, e2e는 돌지 않는다. residue 검사는 `src`·`tests`만 본다(`:287-300`). **추가**: API operation·schema가 있는 새 기능은 `registry-governance.json`의 FE-REG-API·FE-REG-SCHEMA `consumerDirectories`에 디렉터리를 넣어야 `check:registries`가 통과한다(`scripts/check-registries.ts:548-583`, 현재 reference 디렉터리만 등록). 생성기는 `feature-module.ts`가 없는 기능 디렉터리를 경고 없이 건너뛴다(`scripts/generate-product-feature-index.ts:249-256`, local-draft가 실제로 이렇게 빠져 있다). 새 기능 recipe 문서는 이 파일들을 언급하지 않는다(`docs/architecture/frontend-ports-adapters-and-boundaries.md:1040-1120`). reference README의 설치 지점 이름도 실제와 다르다(`src/features/reference-feature/README.md:48`은 `REFERENCE_FEATURE_RUNTIME_CONTRIBUTION`, 실제 모듈은 `REFERENCE_FEATURE_RUNTIME_DESCRIPTOR`) | +| 발생 조건 | 다운스트림이 기능을 추가하거나 reference가 아닌 기능을 제거 | +| 영향 | 기능마다 공유 JSON 파일을 함께 수정해서 여러 팀이면 충돌이 반복된다. reference가 아닌 기능 제거는 스크립트가 없어 수동 절차를 재구성해야 한다. 파일 이름 오타는 기능이 조용히 빠지는 것으로 끝난다 | +| 심각도·우선순위 | Medium · P2 — 변경 비용이 기능마다 반복된다. 안전 문제는 아니다 | +| 통제·증거 | 목표 M3(추가·제거 절차 문서 + 일반화된 검증) / 확인 샘플 제거 M3(스크립트), 일반 기능 M1 · E1(`test:sample-removal` 미실행) | +| 확실성과 남은 가정 | 목록은 스크립트·설정을 읽어 확정. registry baseline 승인이 추가에도 필요한지는 확인하지 않았다 | +| 최소 개선 방향 | (1) 생성기가 `src/features/*/`에 `feature-module.ts`가 없으면 명시적 opt-out 표시(예: `NOT_INSTALLED.md`)가 없는 한 실패. (2) `consumerDirectories`를 기능 디렉터리 glob(`src/features/*/adapters`)으로 바꿔 기능별 등록을 없앤다. (3) recipe 문서에 "추가 시 바꾸는 파일" 표를 둔다. (4) 제거 스크립트가 기능 ID를 인자로 받게 한다 | +| 비용·부작용 | glob은 검출 범위를 넓혀 오탐이 늘 수 있다. 제거 스크립트 일반화는 중간 규모 작업 | +| 완료 기준 | 새 기능 추가 시 기능 디렉터리 밖에서 바꾸는 파일이 생성 인덱스(자동)와 선택적 runtime 프로필뿐이다. 이름 오타가 생성 단계에서 실패한다 | +| 검증 방법 | 두 번째 샘플 기능을 추가하는 fixture에서 `check:registries`·`check:types`·생성기가 추가 수정 없이 통과 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 09-08 local-draft가 삭제 후 재생성 시 revision 재사용(ABA)을 막지 않아 다른 탭의 오래된 저장이 새 초안을 덮는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 12, 11, 1 | +| 근거 | 포트 계약이 경고한다: `remove`는 tombstone 없이 지우고 다음 생성은 revision 1부터 시작하므로, 삭제 전 revision N을 쥔 작성자가 재생성된 레코드를 덮을 수 있다. 호출자가 소유한 값과 짝지으라고 권한다(`src/application/ports/browser-file-storage/indexeddb-port.ts:72-80`). local-draft는 `expectedRevision`만 쓴다(`src/features/local-draft-feature/adapters/local-draft-indexeddb-store.ts:55-61`, `application/local-draft-api.ts:10-20`) | +| 발생 조건 | 같은 `draftId`를 재사용하는 설계(예: 화면당 고정 ID). 탭 A가 revision 1을 쥔 상태에서 탭 B가 삭제 후 같은 ID로 새로 저장하고, 탭 A가 저장 | +| 영향 | 탭 B의 새 초안이 탭 A의 오래된 내용으로 조용히 덮인다. 일반 경쟁(둘 다 revision 1에서 저장)은 CAS가 `CONFLICT`로 막는다 | +| 심각도·우선순위 | Low · P2 — 조건이 좁고 로컬 초안 한 건이지만, 샘플이 포트 경고를 따르지 않는 모습으로 복제된다 | +| 통제·증거 | 목표 M2 / 확인 M1(포트 문서) · E1 | +| 확실성과 남은 가정 | 포트 문서와 코드로 확정. draftId를 초안마다 새로 만들면 발생하지 않는다. 실제 IndexedDB로 재현하지 않았다 | +| 최소 개선 방향 | `LocalDraft`에 생성 시 만든 `createdAt` 또는 무작위 `generation` 값을 넣고 저장 시 함께 비교하거나, 샘플 주석에 "draftId는 초안마다 새로 만든다"는 전제를 적는다 | +| 비용·부작용 | 필드 1개 추가와 비교 로직. 주석만 두면 비용 없음 | +| 완료 기준 | 삭제·재생성 후 오래된 revision 저장이 `CONFLICT`가 된다(또는 전제가 샘플에 명시됨) | +| 검증 방법 | fake repository로 삭제→재생성→오래된 저장 순서 테스트 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 09-09 `FEATURE_OVERRIDES` 키 오타가 진단 없이 무시되어 킬스위치가 조용히 작동하지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 개선 제안 | +| 관련 관점 | 19, 7, 8 | +| 근거 | 설치되지 않은 ID는 의도적으로 "inert"다(`src/contracts/release-artifacts.ts:65-80`). `resolveProductFeatures`는 모르는 키를 무시하고(`src/contracts/product-features.ts:110-129`) 부트스트랩도 경고를 남기지 않는다(`src/bootstrap/runtime-adapters.ts:437-444`). 설정 변경은 새 부트부터 적용된다(`src/bootstrap/load-runtime-config.ts:152-153`) | +| 발생 조건 | 장애 중 운영자가 `"reference-featrue": "DISABLED"`처럼 오타로 기능을 끔 | +| 영향 | 기능이 계속 ACTIVE다. 운영자는 platform overview 화면을 봐야만 알 수 있다 | +| 심각도·우선순위 | Low · P2 — "여러 빌드가 한 문서를 공유한다"는 명시된 이유가 있어 검출 범위는 선언돼 있다. 다만 긴급 조치 도구의 조용한 실패다 | +| 통제·증거 | 목표 M2 / 확인 M1 · E1 | +| 확실성과 남은 가정 | 코드로 확정 | +| 최소 개선 방향 | 부트 시 이 빌드가 모르는 override 키마다 `feature.override.unknown` 진단을 1회 기록한다. release admission이 대상 빌드의 compiled ID와 대조해 경고한다 | +| 비용·부작용 | 진단 이벤트 1종. 공유 문서 운영과 충돌하지 않는다 | +| 완료 기준 | 오타 키가 진단·admission 기록에 나타난다 | +| 검증 방법 | runtime-adapters 단위 테스트에 모르는 키 케이스 추가 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 09-10 부트 실패 화면에 다시 시도 동작이 없고 설정·매니페스트는 한 번만 요청한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 개선 제안 | +| 관련 관점 | 6, 28, 32.2 | +| 근거 | `BootErrorShell`은 제목·코드·지원 참조만 보여 주고 행동이 없다(`src/presentation/boundaries/boot-error-shell.tsx:20-53`, 문구 `src/presentation/i18n/catalog.ts:146-152`). 부트 JSON 읽기는 1회 시도다(`src/bootstrap/read-bounded-boot-json.ts:82-96`). 자동 reload는 release mismatch만 대상이다(`src/bootstrap/boot-release-recovery.ts:18-26`) | +| 발생 조건 | 일시적 네트워크 오류로 `CONFIG_FETCH_FAILED`·`CONFIG_TIMEOUT` | +| 영향 | 사용자는 `BOOT_CONFIG_FAILURE / CONFIG_TIMEOUT` 코드만 보고 새로고침하라는 안내를 받지 못한다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | 목표 M2 / 확인 M1 · E1 | +| 확실성과 남은 가정 | 코드로 확정. UX 결정일 수 있다 | +| 최소 개선 방향 | 네트워크 계열 코드일 때 "다시 시도" 버튼(`location.reload()`)과 안내 문구를 둔다. 자동 재시도는 두지 않는다(reload 반복 방지 규칙 유지) | +| 비용·부작용 | 문구 2개·버튼 1개 | +| 완료 기준 | FETCH/TIMEOUT 실패 화면에 다시 시도 버튼이 있다 | +| 검증 방법 | `render-boundary.test.tsx`에 케이스 추가 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 09-11 `tests/features/` 최상위 테스트 3개가 어떤 스크립트·CI 게이트에서도 실행되지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 10, 21 | +| 근거 | `test:reference-feature`는 `tests/features/reference-feature`만(`package.json:79`), `test:coverage`도 같은 하위 폴더만 포함한다(`package.json:81`). `tests/features/feature-installation-surface.test.ts`, `feature-module.test.ts`, `product-features-scale.test.ts`는 어느 스크립트에도 없다(`config/ci/gates.json` 스크립트 목록 확인). 단독 실행 시 4건 통과(실험 4). `defineFeatureModule`의 id 불일치 throw(`src/features/feature-module.ts:75-79`)를 검사하는 테스트는 없다. 참고로 `tests/architecture/`도 `test:platform`·`check:topology`·`check:observability`에서만 돌고 이 셋은 CI 게이트에 없다(다른 영역 확인 필요) | +| 발생 조건 | 해당 테스트가 지키는 규칙(중앙 파일에 reference 전용 import 금지 등)을 어기는 변경 | +| 영향 | 회귀가 CI에서 검출되지 않는다 | +| 심각도·우선순위 | Low · P3 — 같은 규칙 일부를 `tests/unit/product-features.test.ts`가 CI에서 다룬다 | +| 통제·증거 | 목표 M3 / 확인 M1 · E2(단독 실행) | +| 확실성과 남은 가정 | 스크립트·게이트 목록으로 확정 | +| 최소 개선 방향 | `test:reference-feature`·`test:coverage`의 경로를 `tests/features`로 넓히거나 세 파일을 `tests/unit`으로 옮긴다. id 불일치 케이스를 추가한다 | +| 비용·부작용 | 스크립트 1~2줄. `test-sample-removal.ts:271-272`의 경로 치환도 함께 수정 | +| 완료 기준 | 세 파일이 CI 게이트에서 실행된다 | +| 검증 방법 | CI 로그 또는 junit 결과에서 파일 확인 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 09-12 local-draft의 테스트 fixture 복사본이 src와 갈라졌고, 경계 테스트는 복사본을 검사한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 9, 10, 23 | +| 근거 | `tests/contract/consumer-experience/fixtures/local-draft-feature.ts`는 저장소 실패를 `BrowserDataResult`로 그대로 돌려주고, src 버전은 `AppFailure`로 변환한다(`src/features/local-draft-feature/adapters/local-draft-indexeddb-store.ts:19-43`). "기능 코드에 native IndexedDB가 없다" 테스트는 fixture 파일을 읽는다(`tests/contract/consumer-experience/indexeddb-local-draft.test.ts:136-160`). 문서의 측정값(LOC 97, import 1)도 fixture 기준이다(`docs/architecture/capability-consumer-experience.md:60-100`) | +| 발생 조건 | src local-draft가 바뀌거나 금지 API를 쓰게 됨 | +| 영향 | 문서·테스트가 말하는 대상과 실제 샘플이 다르다. 소유자 전제상 "갈라진 중복 복사본" | +| 심각도·우선순위 | Low · P3 — native IDB 전역 사용은 ESLint 경계 검사가 따로 막는다(`scripts/check-browser-file-storage-boundaries.ts`) | +| 통제·증거 | 목표 M3 / 확인 M1 · E1 | +| 확실성과 남은 가정 | 파일 비교로 확정 | +| 최소 개선 방향 | fixture를 지우고 테스트가 src의 local-draft를 import·검사하게 한다 | +| 비용·부작용 | 테스트 기대값이 `AppFailure` 기준으로 바뀐다 | +| 완료 기준 | local-draft 구현이 한 벌이다 | +| 검증 방법 | `grep`으로 중복 정의 0건, 테스트 통과 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +## 5. 28개 관점 판정 (36.2) + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +|---|---|---|---|---|---| +| 1 | 코드 성숙도 | 적용 — 두 샘플의 생성·변경 경로 | M2 / reference M3(계약 검증기+KEYED 거부), local-draft M0 | E1, E2 | 부분 충족 — local-draft 도메인 규칙 미적용(09-06). reference는 조회 모델이라 상태 전이가 없음 | +| 2 | 구조적 성숙도 | 적용 | M3 / M2 — bootstrap이 `installed-*`만 import하는 것은 지켜지나 이를 강제하는 규칙은 없음 | E1 | 부분 충족 — 32.4 준수. bootstrap→기능 내부 import 금지 규칙 부재, capability 공급이 계약과 불일치(09-05) | +| 3 | 변경 용이성 | 적용 — 기능 추가·제거 추적 | M3 / M0(2개째 기능 추가 시 게이트 실패) | E3 | 미충족 — 09-01, 09-07 | +| 4 | 인지 부하 | 적용 | M1 / M1 | E1 | 부분 충족 — 생성기 파일명 규약, 모듈 augmentation 2종, `consumerDirectories` 등 숨은 전제(09-07). README 이름 불일치 | +| 5 | 위험 가시성 | 적용 | M2 / M2 | E1 | 부분 충족 — HTTP 계약에 deadline·재시도·트래픽이 드러남. `needs` 선언은 있으나 런타임 확인 없음(09-05) | +| 6 | 실패 성숙도 | 적용 — 부트 실패 | M2 / M1 | E1, E2 | 부분 충족 — reload 반복 차단은 좋음. 모듈 평가 실패 무한 로딩(09-03), 재시도 동작 없음(09-10) | +| 7 | 운영 성숙도 | 부분 적용 — SLO는 템플릿 범위 밖 | M1 / M1 | E1 | 부분 충족 — 부트 실패가 수집기에 도달하지 않음(09-04). 킬스위치 오타 무진단(09-09) | +| 8 | 디버깅 가능성 | 적용 | M2 / M1 | E1 | 미충족 — 알 수 없는 부트 오류 원인 폐기·오분류(09-04) | +| 9 | 유지보수 성숙도 | 적용 | M2 / M2 | E1 | 부분 충족 — 직전 리뷰의 중복(reload guard, 텔레메트리 전송)은 합쳐짐. local-draft fixture 복사본(09-12), 주석 불일치(`env.ts:59-61`) | +| 10 | 테스트 성숙도 | 적용 — 이 영역 테스트 검출력 | M3 / M2 | E2(62 files/397 tests 통과) | 부분 충족 — 킬스위치·reload·demo 거부는 테스트가 분기를 직접 고정. 다기능 typecheck 없음(09-01), 고아 테스트(09-11), 부트 실패 e2e 없음, staging+demo 거부 케이스 없음 | +| 11 | 데이터 성숙도 | 부분 적용 — 로컬 IndexedDB 샘플만 | M2 / M1 | E1 | 부분 충족 — local-draft ABA(09-08). 보관·로그아웃 정책은 src 샘플에 없고 테스트에만 있음 | +| 12 | 동시성 성숙도 | 적용 — 여러 탭 | M2 / M2 | E1 | 부분 충족 — reload 마커는 탭별 sessionStorage, CAS로 일반 경쟁 차단. 삭제 후 재생성 ABA(09-08) | +| 13 | 확장성 | 적용 — 기능 수 증가 축 | M3 / M0 | E3 | 미충족 — 실제 composer는 기능 2개에서 타입 실패. TS 규모 게이트가 합성 fixture로 실제 조립을 우회(09-01). 부트 비용은 기능당 계약·스키마·메시지 eager, 페이지 lazy(측정 안 함) | +| 14 | 성능 성숙도 | 다른 영역 — 번들·성능 | — | 미확인 | 미검증 — 부트는 설정(≤5s)→매니페스트(≤5s) 순차. 실제 시간 측정 안 함 | +| 15 | 보안 성숙도 | 적용 — demo 인증, route policy | M3 / M3 | E1, E2 | 부분 충족 — demo는 세 단계에서 공개 환경 차단. route policy는 UX용이고 서버 인가가 기준이라는 전제와 일치(자격 증명 부착은 fail-closed). 배포 경로가 admission을 건너뛰면 막을 수단 없음(배포 영역) | +| 16 | 의존성 성숙도 | 다른 영역 | — | — | 적용 제외 — 이 영역 고유 의존성 없음 | +| 17 | API / Contract 성숙도 | 적용 — 설정·매니페스트·기능 계약 | M3 / M2 | E1, E2 | 부분 충족 — 계약 세트 기대값이 Node와 브라우저에서 다름(09-02) | +| 18 | 배포 성숙도 | 부분 적용 | M3 / M2 | E1 | 부분 충족 — rolling mismatch 1회 reload. 빌드 선택값 불일치(09-02) | +| 19 | 설정 성숙도 | 적용 — `public/config.json` | M3 / M3(최상위 키), M1(override 키) | E2 | 부분 충족 — strict 스키마·조합 검증·선택 기능 비요구는 좋음. override 오타 무진단(09-09), 스키마 실패 위치 미표시(09-04), 빌드 변수 검증 시점(09-02) | +| 20 | 개발자 경험 | 적용 — 기능 추가 | M2 / M1 | E3 | 미충족 — 첫 추가 기능에서 타입 게이트 실패, 조립 오류가 설정 실패로 보임(09-01, 09-04, 09-05) | +| 21 | Guardrail 성숙도 | 적용 | M3 / M2 | E1 | 부분 충족 — 기능 간 import·계층 규칙은 강제. 생성기의 조용한 skip, 다기능 typecheck 부재, 고아 테스트(09-07, 09-01, 09-11) | +| 22 | 추상화 성숙도 | 적용 — `FeatureModule` 제네릭·contribution | M2 / M1 | E3 | 미충족 — 6개 타입 파라미터와 유니언 추론에 기대는 조립이 2개째 기능에서 무너짐(09-01) | +| 23 | 일관성 | 적용 | M2 / M2 | E1 | 부분 충족 — reference는 mapper에서 도메인 팩터리를 쓰고 local-draft는 안 씀. 주석·README 불일치 | +| 24 | 네이밍 / 의미 성숙도 | 적용 | M2 / M1 | E1 | 부분 충족 — `LocalDraft`가 검증된 값처럼 보임(09-06). `INSTALLED_*`·`EXPECTED_CONTRACT_SET_PACKAGES`가 실행 환경마다 다른 값(09-02). 알 수 없는 오류가 `BOOT_CONFIG_FAILURE`(09-04) | +| 25 | 조직 확장성 | 구조적 준비만 평가(전제) | M2 / M1 | E1 | 부분 충족 — 기능마다 공유 JSON 수정 필요(09-07) | +| 26 | Ownership 성숙도 | 다른 영역 | — | — | 적용 제외 — 기능 owner 필드는 있음(`reference-mapper.ts:114`), 운영 책임은 문서 영역 | +| 27 | 삭제 가능성 | 적용 — sample removal | M3 / M3(reference 한정), M1(일반 기능) | E1(스크립트 읽기, 미실행) | 부분 충족 — 제거 스크립트가 중앙 파일 8종을 정리하고 residue를 검사. 일반 기능용 절차 없음, 일부 게이트만 실행(09-07) | +| 28 | 회복 가능성 | 부분 적용 — 부트·청크 복구 | M2 / M2 | E1, E2 | 부분 충족 — reload-once와 fail-closed 마커. 부트 실패 후 사용자 복구 동작 없음(09-10) | + +## 6. 미검증 목록 + +| 항목 | 이유 | 확인하려면 | +|---|---|---| +| `test:sample-removal` 전체 통과 여부 | 복제본에서 typecheck·test:all·coverage·build를 돌려 오래 걸리고, 공유 워킹트리에 `.tmp/`를 만든다 | 격리 환경에서 `corepack pnpm test:sample-removal` 실행, junit `artifacts/tests/sample-removal.xml` 확인 | +| bootstrap → 기능 내부 import를 넣었을 때 `check:architecture` 결과 | worktree에서 pnpm 의존성 검사가 install을 시도하다 중단됨(공유 `node_modules` 상태 파일이 다른 에이전트 경로로 바뀌어 있음). 규칙 파일상 막는 규칙은 없음 | 정상 pnpm 환경에서 위반 import 1줄 주입 후 `check:architecture` | +| 모듈 평가 실패·알 수 없는 부트 오류의 실제 브라우저 화면(09-03, 09-04) | 브라우저 실행 안 함 | 잘못된 `VITE_PRODUCT_FEATURES`로 빌드 후 Playwright로 열기 | +| 제외 기능 URL의 화면(09-02 (c)) | 정적 추적만 함 | `VITE_PRODUCT_FEATURES=none` 빌드에서 `/examples/reference-resources` 접속 | +| 외부 계약 패키지를 가진 기능 + 선택값 조합의 `CONTRACT_SET_PACKAGE_UNEXPECTED`(09-02 (b)) | 저장소에 외부 패키지를 가진 기능이 없음 | EXTERNAL_PACKAGE 기여를 가진 fixture 기능 2개로 빌드·부트 | +| 부트 시간과 기능 수에 따른 부트 비용 | 성능 측정 범위 밖 | 기능 N개 fixture로 부트 시간·번들 측정(성능 영역) | +| 두 탭 local-draft ABA의 실제 IndexedDB 재현(09-08) | 포트 문서와 코드로 판단 | 브라우저 두 컨텍스트로 삭제→재생성→오래된 저장 | diff --git a/docs/reviews/2026-09-25-maturity-review/10-tests-fast-layers.md b/docs/reviews/2026-09-25-maturity-review/10-tests-fast-layers.md new file mode 100644 index 00000000..9ae14fe4 --- /dev/null +++ b/docs/reviews/2026-09-25-maturity-review/10-tests-fast-layers.md @@ -0,0 +1,234 @@ +# 테스트 체계: 빠른 계층(Node/jsdom) 성숙도 리뷰 + +> 검토일: 2026-09-25 · 기준: `main` / `4626b73` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 범위: `tests/unit/`(140파일, 60,361줄 — 표본), `tests/component/`(5,812줄), `tests/integration/`(4,481줄), `tests/contract/`(716줄), `tests/runtime-schema/`(629줄), `tests/features/`(1,956줄), `tests/platform/`(2,786줄), `tests/recipes/`(963줄), `tests/helpers/`·`tests/mocks/`·`tests/support/`·`tests/fixtures/`(약 3,300줄), `tests/setup.ts`, `vitest.config.ts`, `scripts/run-vitest.ts`, `config/testing/*.json`, `scripts/check-test-evidence.ts`, `scripts/check-risk-coverage.ts`와 `scripts/lib/risk-coverage.ts`, `docs/testing/*` — 합계 약 81k줄 +> 영역 판정(35.8): **조건부 사용 가능** — 조건: 10-01을 고치기 전에는 깨끗한 체크아웃(새 clone, CI 러너)에서 `test:unit`·`test:all`이 통과하지 않는다. IndexedDB 테스트 대역의 한계(05-08)를 알고 쓴다. + +## 1. 결론 + +- **빠른 테스트의 검출력은 표본 규칙에서 높다.** 고위험 규칙 8개를 일부러 바꿔 보는 실험(변이 실험)에서 7개를 테스트가 잡았다. 직전 리뷰 수정(6.3-1 `..` 경로, 6.7-1 멱등 키, Q-6.9-9 reload guard, Q-6.3-11 401 복구)의 회귀 테스트도 모두 동작했다. 순서를 섞어 3회 돌렸을 때 순서 의존 실패는 없었다. +- **깨끗한 체크아웃에서 `test:unit`이 실패한다(10-01, High).** `tests/unit/removal-fixture.test.ts:125`가 gitignore된 `artifacts/release/*` 같은 로컬 생성물이 있어야 통과한다. 작업 트리에는 그 파일이 있어서 통과하고, 새 worktree에서는 매번 실패한다. FE-GATE-005 CI job은 이 파일을 만들지 않는다. +- **샘플 기능 테스트 하나가 부하에서 흔들린다(10-02).** `reference-page.test.tsx:138`의 첫 `findByRole`은 기본 1초 안에 lazy route를 불러와야 하는데, 혼자 돌려도 804ms가 걸린다. 66~81개 파일을 함께 돌린 실행 중 6회 실패했다. 실패 메시지는 "heading을 못 찾음"이라 시간 초과라는 원인을 가린다. +- **V3 HTTP 실행기의 재시도 의미 연결은 테스트가 없다(10-03).** 실행기가 계약의 `retrySemantics`를 무시하도록 바꿔도 관련 75개 파일이 모두 통과했다. 규칙은 순수 함수 단위 테스트에만 고정돼 있고, fixture의 KEYED 명령은 항상 `retryBudget: 0`이다. +- **커버리지 게이트는 17개 모듈의 현재값 ratchet(되돌아가지 못하게 현재 수치로 고정한 하한)과 전체 평균이다(10-04).** 문서의 위험별 목표(HTTP adapter 90% 이상 등)와 "19개 모듈·80개 threshold" 주장과 다르다. live V3 재시도 모듈은 빠지고 legacy V2 모듈이 들어가 있다. +- 미검증: main 트리 전체 `test:unit`·`test:coverage` 결과와 실제 커버리지 수치는 오케스트레이터 실행에 맡겼다. CI가 이 repo에서 돌지 않아(12-01) CI 러너 조건의 실행 시간·flaky는 보지 못했다. + +## 2. 범위와 방법 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 | `clean-architecture-frontend-template`, `main` / `4626b73`, 미커밋 `CLAUDE.md`·가이드 문서만 있음 | +| 목적·실행 구성 | 템플릿. 빠른 계층은 Vitest 4.1.10, 기본 Node 환경, component 테스트는 파일별 `@vitest-environment jsdom`(31/31) | +| 읽은 설정·도구 | `vitest.config.ts` 전체, `scripts/run-vitest.ts` 전체, `tests/setup.ts`, `config/testing/risk-coverage.json`·`test-evidence.json`, `scripts/check-test-evidence.ts` 전체, `scripts/check-risk-coverage.ts`와 `scripts/lib/risk-coverage.ts`의 평가부(`:315-331`, `:708-901`), `package.json` 테스트 스크립트, `config/ci/gates.json`의 게이트→명령 대응, `.gitea/workflows/quality-gates.yml` merge job | +| 읽은 테스트 자산 | `tests/helpers/memory-indexeddb.ts` 전체, `create-test-application.ts`, `runtime-capabilities-stub.ts`, `tests/mocks/server.ts`·`scenarios/catalog.ts` 앞부분, `tests/support/runtime/determinism.ts`, 표본 테스트 약 20개(http-execution-v3, service-worker-runtime, reference-page, app-shell, removal-fixture, risk-coverage, v8-coverage-counter-semantics, indexeddb-local-draft, http-scenario-catalog 등) | +| 전 범위 grep | fake timer·전역 stub 복원, skip 변형, retry 설정, mock 호출 순서 단언, snapshot, 실제 시간 대기, 자식 프로세스 사용, MSW 사용처 | +| main 트리 실행 | `node scripts/run-vitest.ts run tests/component` → 31파일 182개 통과, 7.0s · `run tests/integration` → 12파일 151개 통과, 11.9s · 프로세스를 띄우는 unit 7파일 → 476개 통과, 4.2s | +| worktree 실험 | `git worktree add --detach /10/wt HEAD` + `node_modules` 심볼릭 링크(= 새 clone과 같은 상태). ① 생성 전 `vitest run tests/component/router.test.tsx` → import 해석 실패 ② `vitest list` → 292파일 수집 ③ 순서 섞기: 비-unit 94파일 × seed 2개 전부 통과(15.5s/18.1s), unit 140파일 seed 7 → 139 통과·1 실패(10.2s) ④ `removal-fixture.test.ts` 단독 → 같은 실패 ⑤ 변이 8건을 `vitest related <파일> --run`(Playwright·system spec 제외)으로 실행 ⑥ `reference-page.test.tsx` 단독 3회·스위트 4회·묶음 실행 약 10회 ⑦ IndexedDB 대역 탐침 5건 ⑧ `check-test-evidence.ts --source-root`로 skip 검사 탐침. 끝난 뒤 worktree 제거 | +| 확인하지 못한 범위 | main 트리 전체 `test:unit`·`test:coverage`(오케스트레이터 몫), 실제 커버리지 수치, CI 러너 조건, unit 140개 중 표본 밖 파일의 모듈별 검출력(01~09 영역) | +| 이전 리뷰와 비교 | 직전 리뷰는 `src/`만 봤다. 5.2(연결 지점 테스트 부재)는 realtime에서 개선됨을 확인했다(`realtime-reconnect-coordinator.test.ts:32-39`가 실제 WS/SSE 연결을 씀). HTTP V3 재시도 연결에는 남아 있다(10-03) | + +변이 실험 결과(원본은 실험 후 복원): + +| ID | 바꾼 곳 | 결과 | 잡은 테스트 | +|---|---|---|---| +| M1 | `src/adapters/http/http-retry-lifecycle.ts:26-27` KEYED도 dispatch 뒤 재시도 허용 | 잡힘 | `tests/unit/http-retry-lifecycle.test.ts` 1개 | +| M1b | `src/adapters/http/http-execution-v3.ts:940` `canRetryTransport(contract.retrySemantics, …)` → `canRetryTransport("SAFE", …)` | **통과(미검출)** | 없음(75파일 547개 통과) | +| M2 | `src/adapters/http/retry-policy.ts:62` idempotency `none`도 재시도 | 잡힘 | unit `retry-policy` 2개, integration(MSW) `http-client` 6개 | +| M3 | `src/platform/release/release-mismatch-recovery.ts` reload guard를 키별로 되돌림(Q-6.9-9 이전) | 잡힘 | platform 2개, `tests/release` 1개, unit `chunk-recovery` 1개 | +| M4 | `src/adapters/http/http-contract-bridge.ts:204` `..` 검사 제거(6.3-1 되돌림) | 잡힘 | `http-contract-bridge.test.ts` "rejects the dot segment \"..\"" | +| M5 | `src/contracts/mutation-intent.ts` 멱등 키에 공백 허용 | 잡힘 | `legacy-and-optional-network-remediation.test.ts` 1개 | +| M6 | `src/adapters/http/client.ts:344` `recoveryUsed = true` 제거 | 잡힘 | integration(MSW) `auth-recovery` "stops after a second 401" | +| M7 | `http-execution-v3.ts:784` `Idempotency-Key` 헤더 제거 | 잡힘 | unit `http-execution-v3`, features `reference-runtime-composition`, scale `network-flap` | + +## 3. 확인된 강점 + +1. **회귀 테스트가 실제 규칙을 고정한다.** 위 표에서 변이 8건 중 7건이 잡혔다. 실패한 테스트 이름이 깨진 규칙을 그대로 말한다(예: "rejects the dot segment \"..\" instead of letting URL resolution move the target"). 가짜 fetch도 실제 `Response` 객체를 돌려준다(`tests/unit/http-execution-v3.test.ts:164`, `:187`). +2. **테스트 사이에 상태가 새지 않는다.** `vitest.config.ts:13-15`가 `restoreMocks`·`clearMocks`·`mockReset`을 켠다. `tests/setup.ts:5-7`이 RTL `cleanup`을 돈다. fake timer를 쓰는 7개 파일은 모두 `useRealTimers`로 되돌린다. `stubGlobal`을 쓰는 2개 파일은 `unstubAllGlobals`로 되돌린다. 순서를 섞은 3회 실행에서 순서 의존 실패는 없었다. +3. **flaky를 재시도로 숨기지 않는다.** `vitest.config.ts`에 `retry`가 없다(기본 0). CI는 `CI: "true"`를 준다(`.gitea/workflows/quality-gates.yml:27`). 그래서 Vitest가 `.only`를 거부한다(`allowOnly` 기본값이 CI에서 false). +4. **HTTP 실패 시나리오가 "선언 = 실행 = 관측"으로 묶여 있다.** `tests/integration/http-scenario-catalog.test.ts:388-389`가 시나리오마다 실제 실행 결과를 기대값과 비교하고 실패 메시지에 `executionId`를 넣는다. `scripts/check-test-evidence.ts:230-270`이 선언 ID와 실행 ID의 누락·추가·digest·관측값 불일치를 거부한다. MSW 서버는 처리되지 않은 요청을 실패로 만든다(`tests/mocks/server.ts:8`). +5. **빠르다.** 22코어·부하 평균 5~14에서 unit 140파일 10.2s, component 31파일 7.0s, integration 12파일 11.9s, 나머지 94파일 15~18s였다. +6. **mock 호출 순서를 베낀 테스트가 드물다.** `toHaveBeenNthCalledWith` 2건, `mock.calls` 전체 비교 9건이 전부다. 모두 전달된 값·열린 창·읽은 페이지 같은 관찰 가능한 결과를 본다(예: `tests/unit/cursor-pagination-runtime.test.ts:85`). snapshot 단언은 1건이다. Given/When/Then 표기를 세는 검사는 없다(관점 23). + +## 4. 발견 사항 (36.3) + +다른 영역과 겹치는 항목은 새 ID를 만들지 않고 아래 증거만 보탠다. + +- **05-08 보강(IndexedDB 대역):** 탐침으로 두 가지를 더 확인했다. 숫자 키 `1`과 문자열 키 `"1"`이 한 행으로 합쳐진다(`tests/helpers/memory-indexeddb.ts:118-126`, `String(key)`). `delete(IDBKeyRange)`는 오류 없이 아무것도 지우지 않는다(`:550`, `get`도 `:520`). 겹친 readwrite 트랜잭션의 쓰기 유실, macrotask 뒤 요청 수용, 배열 keyPath 인덱스 오정렬은 05-08과 같은 결과였다. 도움말 주석(`:724`)은 모델링하지 않는 의미를 적지 않는다. +- **11-08 보강(skip 검사):** `scripts/check-test-evidence.ts:288`의 정규식은 `.skip(`·`.fixme(`만 본다. `it.skipIf(true)`, `it.todo`, 테스트 안의 `ctx.skip()`은 quarantine 주석 없이 통과했다(탐침 exit 0). 현재 `it.skipIf(isReducedCiContractRun())`가 3곳에 있다(`tests/unit/task3-selective-integration.test.ts:182`, `:196`, `tests/unit/supply-chain.test.ts:543`). 모두 removal-fixture 모드 전용이라 지금은 정당하다. +- **12-04·09-11 보강(어느 명령에도 속하지 않는 테스트):** 12-04 목록 밖으로 `tests/scale/browser-soak.contract.test.ts`는 `check:scale:*` 프로필에도 없다(`scripts/scale/run-scale-profile.ts:32-110`). `tests/scripts/verify-extreme-scale.test.ts`는 어떤 스크립트에도 없다. + +### 10-01 깨끗한 체크아웃에서 `test:unit`이 실패한다 — 테스트가 gitignore된 로컬 생성물에 의존 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 10, 20, 21, 30.8 | +| 근거 | `tests/unit/removal-fixture.test.ts:113-125`는 `RELEASE_CANDIDATE_EVIDENCE_PATHS` 중 현재 작업 디렉터리에 실제로 있는 `artifacts/…` 파일을 세고 `expect(preserved).toBeGreaterThan(0)`를 요구한다. 이 파일들(`artifacts/release/*.json`, `artifacts/security/*.json`, `artifacts/performance/bundle.json` 등)은 `.gitignore:11`(`artifacts/**/*.json`)로 추적되지 않는다. 새 worktree에서 이 파일 단독 실행 → `AssertionError: expected 0 to be greater than 0`(5 통과·1 실패). unit 전체(shuffle) → 139/140 통과, 이 파일만 실패. main 트리는 누가 릴리스 체인을 돌려 둔 파일이 있어서 통과한다. CI merge job FE-GATE-005(`.gitea/workflows/quality-gates.yml:47`, `:55-71`)는 checkout → install → `ci:gate`만 하고 산출물을 받지 않는다. FE-GATE-005 명령은 `test:unit`·`test:contract`·`test:coverage`다 | +| 발생 조건 | 릴리스 체인(`build:release-candidate` 등)을 한 번도 돌리지 않은 체크아웃. 새 clone, CI 러너, 다운스트림 복사본이 모두 해당한다 | +| 영향 | `test:unit`, `test:all`(README가 안내하는 기본 개발 루프), `test:coverage`가 실패한다. FE-GATE-005가 켜진 러너에서는 매번 빨간불이다. 새 사용자는 첫 실행에서 실패를 보고, 팀은 빨간불을 무시하는 습관을 배운다 | +| 심각도·우선순위 | High · P1 — 30.8절 "깨끗한 환경의 설치·실행·기본 테스트"와 merge 게이트를 깨뜨린다. 복사한 모든 프로젝트에 그대로 간다. 사용자·데이터 피해는 없어서 Critical이 아니다(14-01과 같은 기준) | +| 통제·증거 | M0(생성물 의존을 막는 장치 없음) · E2(깨끗한 worktree 실행) | +| 확실성과 남은 가정 | 실패 재현은 확실하다. 이 repo는 CI가 돌지 않아(12-01) 실제 CI 실패 기록은 없다 | +| 최소 개선 방향 | 테스트 대상이 "복사 시 보존"이므로 `process.cwd()` 대신 임시 폴더에 가짜 증거 파일을 만들고 `copyReleaseEvidenceTree(tempRoot, target)`로 검사한다. 또는 `tests/setup.ts`나 lint로 빠른 계층이 `artifacts/`·`dist/`를 읽지 못하게 한다 | +| 비용·부작용 | 테스트 수정 몇 줄. 보존 검사 의미는 유지된다 | +| 완료 기준 | 깨끗한 worktree(`git worktree add` + install)에서 `test:unit`이 통과한다. 빠른 계층 테스트가 추적되지 않는 파일을 읽지 않는다 | +| 검증 방법 | 새 worktree에서 `node scripts/run-vitest.ts run tests/unit` 실행 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 6.0(깨끗한 체크아웃 게이트 실패)과 같은 종류. 6.0의 생성 파일 문제는 `scripts/run-vitest.ts:51-60`로 고쳐졌고, 이 건은 새로 확인됨 | + +### 10-02 샘플 기능 페이지 테스트가 부하에서 흔들리고, 실패 메시지가 시간 초과를 가린다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(조건부 재현) | +| 관련 관점 | 10, 8, 14, 30.5 | +| 근거 | `tests/features/reference-feature/reference-page.test.tsx:137-138`이 첫 렌더 직후 `findByRole("heading", …)`를 기본 제한 시간(1,000ms, Testing Library 기본값)으로 기다린다. 이 테스트는 파일의 첫 테스트라 lazy route 청크를 불러오는 비용을 혼자 낸다. 단독 실행에서 804ms가 걸렸다(여유 약 20%). 관련 테스트 묶음(66~81파일 병렬, 부하 평균 5~14) 약 10회 실행 중 6회 `TestingLibraryElementError: Unable to find role="heading"`으로 실패했다. 단독 3/3, 자기 스위트(`tests/features/reference-feature`) 4/4는 통과했다. 저장소 어디에도 `asyncUtilTimeout` 설정이 없다 | +| 발생 조건 | CPU가 바쁠 때. 여러 디렉터리를 함께 돌리는 `test:coverage`(V8 계측 + `--maxWorkers=4`), `vitest related`, 느린 CI 러너 | +| 영향 | merge 게이트가 코드 변경과 무관하게 가끔 실패한다. 메시지가 "화면에 제목이 없다"라서 UI 결함처럼 보인다. 이 파일은 복제용 샘플이라 같은 패턴이 다운스트림 기능 테스트로 퍼진다 | +| 심각도·우선순위 | Medium · P2 — 제품 피해는 없지만 게이트 신뢰와 조사 비용을 반복해서 깎는다 | +| 통제·증거 | M0 · E2(반복 실행, 조건 기록) | +| 확실성과 남은 가정 | 원인(첫 lazy import가 1초 기본값에 가까움)은 측정으로 확인했다. CI 조건에서의 실패율은 미확인이다 | +| 최소 개선 방향 | 첫 대기에 route 준비 신호를 기다리거나(`await screen.findByRole(…, {}, { timeout: 5_000 })`), `tests/setup.ts`에서 `configure({ asyncUtilTimeout })`를 테스트 타임아웃과 맞춘다. lazy 모듈을 `beforeAll`에서 미리 import하는 방법도 있다 | +| 비용·부작용 | 한두 줄. 전역 timeout을 늘리면 진짜 멈춤을 늦게 발견하므로 첫 렌더 대기에만 적용하는 편이 낫다 | +| 완료 기준 | 부하 조건(예: 비-unit 디렉터리 전체 + unit 동시 실행) 20회에서 실패 0 | +| 검증 방법 | `vitest related src/adapters/http/http-retry-lifecycle.ts --run`을 반복 실행하고 실패 수를 센다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 10-03 V3 HTTP 실행기가 계약의 재시도 의미를 쓰는지 검증하는 테스트가 없다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(검출 공백) | +| 관련 관점 | 10, 6, 17, 21 | +| 근거 | 변이 M1b: `src/adapters/http/http-execution-v3.ts:940`에서 `contract.retrySemantics` 대신 `"SAFE"`를 넘겨도 관련 75파일 547개 테스트가 통과했다. 같은 규칙의 순수 함수(`http-retry-lifecycle.ts:21-30`)를 바꾼 M1은 unit 1개만 잡았다. 테스트 fixture의 KEYED 명령은 `retryBudget: 0`이다(`tests/helpers/external-contract-fixture.ts:173`, `:194`). 샘플 계약도 0이다(`src/features/reference-feature/contracts/reference-feature-contract-contribution.ts:195`). 그래서 "KEYED + 예산 > 0 + dispatch 뒤 전송 실패" 경로는 어떤 테스트에서도 실행되지 않는다. 계약 검증은 NEVER + 예산 > 0만 막는다(`src/contracts/external-contract-runtime.ts:489-494`). 테스트 전략 문서는 이 위험을 P0로 두고 "unit policy + MSW integration"으로 막는다고 쓴다(`docs/testing/frontend-platform-testing-strategy.md` 3절 표) | +| 발생 조건 | 실행기 리팩터링에서 재시도 판단 인자가 바뀌거나 빠질 때. 다운스트림이 KEYED 명령에 `retryBudget` 1~2를 줄 때 | +| 영향 | dispatch된 KEYED 명령이 자동 재전송돼도 빠른 테스트가 모른다. 같은 멱등 키로 가므로 서버가 키를 지원하면 피해는 제한되지만, 문서가 약속한 "dispatch 뒤에는 재전송 대신 조정" 계약이 조용히 깨진다 | +| 심각도·우선순위 | Medium · P2 — 전략 문서 스스로 P0로 분류한 규칙인데 연결 계층 검증이 없다. 실제 피해는 서버 멱등 처리 여부에 달려 있다 | +| 통제·증거 | M3(순수 함수 단위) / 실행기 연결은 M0 · E2(변이 실험) | +| 확실성과 남은 가정 | 미검출은 확인했다. 모듈 세부 규칙 차이는 03-06이 다룬다 | +| 최소 개선 방향 | `http-execution-v3.test.ts`에 KEYED·`retryBudget: 2` 계약으로 "dispatch 전 실패는 재시도, dispatch 뒤 실패는 fetch 1회 + `MAYBE_APPLIED`" 두 테스트를 추가한다 | +| 비용·부작용 | 테스트 2개. 기존 fixture 재사용 | +| 완료 기준 | M1b 변이를 넣으면 새 테스트가 실패한다 | +| 검증 방법 | M1b를 다시 적용하고 `vitest related src/adapters/http/http-execution-v3.ts --run` | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 5.2(연결 지점 테스트 부재)의 패턴이 HTTP V3 재시도 연결에 남아 있음 | + +### 10-04 커버리지 게이트가 문서의 위험별 목표가 아니라 17개 모듈의 현재값 하한이고, live 재시도 모듈이 빠져 있다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 10, 21, 9 | +| 근거 | `scripts/lib/risk-coverage.ts:804-871`이 막는 것: 전체 평균(lines 75·statements 73·functions 80·branches 68, `config/testing/risk-coverage.json:5-10`), `criticalModules` 17개의 모듈별 하한, 커버리지 표에서 빠진 모듈, 카운터가 0인 모듈. 모듈별 하한은 현재값 근처다(branches: `service-worker-lifecycle.ts` 43, `http-execution-v3.ts` 52, `read-bounded-boot-json.ts` 57, `browser-storage-adapter.ts` 60). 전략 문서는 "retry/error/auth/chunk policy — 모든 결정 분기", "HTTP/storage/telemetry adapter — 90% 이상"을 목표로 적고(`docs/testing/frontend-platform-testing-strategy.md:957-958`), "19개 high-risk module에 80개 scoped threshold"라고 쓴다(`:158`). 실제는 17개·모듈별 68개(+전체 4개). 목록에는 legacy V2 `retry-policy.ts`가 있고, live V3 재시도 규칙 `http-retry-lifecycle.ts`(10-03), `http-contract-bridge.ts`(6.3-1), realtime `reconnect-coordinator.ts`, `indexeddb-runtime.ts`, `push-subscription-adapter.ts`(직전 리뷰 상위 결함 모듈)는 없다 | +| 발생 조건 | 목록 밖 고위험 모듈의 테스트가 줄거나 분기가 늘 때. 전체 평균만 유지되면 통과한다 | +| 영향 | 문서를 믿은 다운스트림이 고위험 모듈이 90% 이상으로 막혀 있다고 오해한다. 커버리지는 보조 신호라 직접 피해는 작다 | +| 심각도·우선순위 | Low · P3 — 1차 방어는 테스트 자체이고 10-03처럼 개별로 보완할 수 있다 | +| 통제·증거 | M3(17개 모듈) / 문서 목표는 M1 · E1(정적 확인, 실제 커버리지 수치 미확인) | +| 확실성과 남은 가정 | 정책 파일과 평가 코드는 확인했다. 현재 커버리지 실제값은 `test:coverage`를 돌리지 않아 모른다 | +| 최소 개선 방향 | 문서 2.3·14.2절을 "현재값 ratchet + 올릴 목표"로 고쳐 쓴다. `highRiskPaths`에 live 경로(`http-retry-lifecycle.ts`, `http-contract-bridge.ts`)와 직전 리뷰 결함 모듈을 넣고 현재값으로 하한을 둔다 | +| 비용·부작용 | JSON 몇 줄. 목록이 늘면 ratchet 갱신 부담이 조금 는다 | +| 완료 기준 | 문서 수치가 정책 파일과 같다. live 재시도·경로 규칙 모듈이 목록에 있다 | +| 검증 방법 | `check:coverage:fixture`와 `test:coverage` | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 10-05 테스트 파일 하나를 돌리는 방법이 문서에 없고, 문서에 적힌 명령은 새 체크아웃에서 실패한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 20, 19 | +| 근거 | 동작하는 방법(`node scripts/run-vitest.ts run `)은 어디에도 적혀 있지 않다(14 영역 2.1절 표와 같은 관찰). 운영 ledger는 `corepack pnpm exec vitest run `을 쓴다(`docs/operations/adapter-remediation-ledger.md:75-97`). 이 명령은 생성기를 거치지 않는다. 새 worktree에서 `vitest run tests/component/router.test.tsx` → `Failed to resolve import "../.generated/product-feature-index.ts"`. `pnpm test:unit -- `은 줄어들지 않는다. 스크립트가 이미 `tests/unit`을 넘기므로 `vitest list tests/unit tests/unit/retry-policy.test.ts` → 140파일. `vitest.config.ts`에 `include`가 없어 인자 없는 `vitest run`은 Playwright spec 25개와 host 전제 system 테스트 3개까지 모은다(`vitest list` → 292파일) | +| 발생 조건 | 새 clone 직후 파일 하나를 돌릴 때, 경로 없이 `vitest`를 돌릴 때 | +| 영향 | 첫 실행에서 모듈 해석 오류를 보고 원인(생성기)을 스스로 찾아야 한다. Node 버전 검사도 건너뛴다 | +| 심각도·우선순위 | Low · P3 — 한 번 `pnpm dev`나 다른 스크립트를 돌리면 사라진다 | +| 통제·증거 | M0 · E2 | +| 확실성과 남은 가정 | 재현했다 | +| 최소 개선 방향 | `docs/testing/taxonomy.md`에 "파일 하나: `node scripts/run-vitest.ts run `" 한 줄을 넣는다. `vitest.config.ts`에 `include: ["tests/**/*.test.{ts,tsx}"]`와 `tests/system/**` 제외를 둔다 | +| 비용·부작용 | 몇 줄. `tests/system`은 `test:system`이 경로로 지정하므로 영향 없음을 확인해야 한다 | +| 완료 기준 | 새 clone에서 문서의 한 줄 명령으로 파일 하나가 돈다. 인자 없는 `vitest list`에 `.spec.ts`가 없다 | +| 검증 방법 | 새 worktree에서 문서 명령 실행, `vitest list --filesOnly` | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 10-06 fake timer 복원이 일부 테스트 본문 끝에만 있어, 단언이 실패하면 같은 파일의 다음 테스트로 새어 실패가 연쇄된다 + +| 필드 | 내용 | +|---|---| +| 성격 | 개선 제안 | +| 관련 관점 | 10, 8, 23 | +| 근거 | `finally`나 `afterEach` 없이 본문 끝에서 `vi.useRealTimers()`를 부르는 곳이 5곳이다: `tests/unit/service-worker-runtime.test.ts:854-886`, `:890-921`, `tests/unit/system-clock.test.ts:7-16`, `tests/unit/http-execution-v3.test.ts:633-655`, `tests/component/design-system-platform.test.tsx:262-288`. 같은 파일의 다른 테스트는 `try/finally`를 쓴다(`service-worker-runtime.test.ts:1013-1058`). 전역 복원은 없다(`tests/setup.ts:5-7`) | +| 발생 조건 | 위 테스트 중 하나의 중간 단언이 실패할 때 | +| 영향 | 뒤 테스트들이 fake timer 아래에서 멈추거나 timeout으로 실패해, 실제 실패 하나가 여러 개처럼 보인다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M2(대부분 파일) · E1 | +| 확실성과 남은 가정 | 정적 확인. 연쇄 실패를 실제로 만들어 보지는 않았다 | +| 최소 개선 방향 | `tests/setup.ts`의 `afterEach`에 `vi.useRealTimers()` 한 줄을 추가한다 | +| 비용·부작용 | 한 줄 | +| 완료 기준 | 전역 `afterEach`에서 실제 타이머로 돌아간다 | +| 검증 방법 | 위 테스트 하나에 실패 단언을 넣고 같은 파일의 다음 테스트가 통과하는지 본다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 10-07 테스트 문서가 현재 구성과 다르다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(문서) | +| 관련 관점 | 9, 20, 24 | +| 근거 | ① 전략 문서는 "clock/random/scheduler/storage helper와 … 비결정적 우회를 차단한다"고 쓴다(`docs/testing/frontend-platform-testing-strategy.md:145-146`). `tests/support/runtime/determinism.ts`를 import하는 파일은 0개다. 그 안의 `createControlledScheduler().clearTimeout`은 아무것도 취소하지 않는 `vi.fn()`이다(`:33`). ② 공통 scenario ID 표(`:713-735`)의 `auth-recover-once`·`auth-persistent-401`·`server-terminal-500`은 catalog에 없다. catalog에는 `unauthenticated-401`·`response-too-large`·`server-terminal-503`이 있다(`tests/mocks/scenarios/catalog.ts:17-37`). ③ taxonomy는 `test:all` 구성을 runtime-schema~recipe로 설명한다(`docs/testing/taxonomy.md:19-22`). 실제로는 `test:platform`과 `check:release-coherence`도 돈다(`package.json:83`). ④ taxonomy는 자식 프로세스를 띄우는 테스트를 `tests/integration`에 두라고 한다(`docs/testing/taxonomy.md:65-70`). 실제 `tests/unit`에는 Node·Vitest·CI 러너를 띄우는 파일이 7개 있다(예: `tests/unit/risk-coverage.test.ts:28-33`이 30초 예산을 따로 둔다). 측정상 7파일 4.2s라 속도 피해는 작다 | +| 발생 조건 | 문서를 보고 helper를 찾거나 시나리오를 추가할 때 | +| 영향 | 없는 보호를 있다고 믿는다. 새 기능 작성자가 없는 scenario ID로 계획을 세운다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M1 · E1 | +| 확실성과 남은 가정 | 정적 확인 | +| 최소 개선 방향 | 쓰지 않는 `determinism.ts`는 지우거나 문서 문장을 고친다. scenario 표를 catalog에서 복사한다. taxonomy의 `test:all` 설명과 분류 규칙을 현재 상태로 맞춘다 | +| 비용·부작용 | 문서 수정 | +| 완료 기준 | 위 네 문장이 코드와 같다 | +| 검증 방법 | 문서 대조 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +## 5. 28개 관점 판정 (36.2) + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +|---|---|---|---|---|---| +| 1 | 코드 성숙도 | 다른 영역 — 모듈 규칙은 01~09 | — | — | 적용 제외 | +| 2 | 구조적 성숙도 | 다른 영역 — 경계 검사는 12 | — | — | 적용 제외 | +| 3 | 변경 용이성 | 적용 — 테스트 추가·변경 비용 | M2 / M2 | E1 | 충족 — `create-test-application.ts`가 운영 `createApplication`을 재사용하고, 시나리오 증거는 owner별 contribution이다(`config/testing/test-evidence.json`) | +| 4 | 인지 부하 | 적용 — 테스트 탐색 | M2 / M2 | E1 | 부분 충족 — 실패 테스트 이름이 규칙을 말한다. unit 60k줄에 제품·도구 테스트가 섞여 있다(도구 대상 27파일 8.8k줄) | +| 5 | 위험 가시성 | 적용 — 테스트 대역의 한계 표시 | M1 / M1 | E2 | 부분 충족 — IndexedDB 대역이 모델링하지 않는 의미를 적지 않는다(05-08) | +| 6 | 실패 성숙도 | 적용 — 실패 경로 테스트 | M3 / M3 | E2 | 부분 충족 — 19개 HTTP 실패 시나리오 × 3 operation 실행 증거. V3 재시도 연결 공백(10-03) | +| 7 | 운영 성숙도 | 적용 제외 — 테스트 계층 밖 | — | — | 적용 제외 | +| 8 | 디버깅 가능성 | 적용 — 실패 메시지 | M2 / M2 | E2 | 부분 충족 — `it.each` 191건, `executionId` 메시지. 부하 flaky 메시지가 원인을 가림(10-02), fake timer 연쇄 실패 가능(10-06) | +| 9 | 유지보수 성숙도 | 적용 — 테스트 문서·자산 | M1 / M1 | E1 | 부분 충족 — 문서 불일치(10-07), 커버리지 문서 수치(10-04) | +| 10 | 테스트 성숙도 | 적용 — 이 영역의 중심 | M3 / M3 | E2 | 부분 충족 — 변이 7/8 검출, 순서 의존 없음, 재시도로 숨김 없음. 깨끗한 체크아웃 실패(10-01), flaky(10-02), 연결 공백(10-03) | +| 11 | 데이터 성숙도 | 적용(테스트 대역 범위만) | M2 / M1 | E2 | 부분 충족 — IndexedDB 대역의 키·범위 삭제 의미가 다름(05-08 보강) | +| 12 | 동시성 성숙도 | 적용 — 테스트 간 격리·대역의 동시성 | M3 / M3 | E2 | 부분 충족 — 순서 섞기 3회 통과. 대역은 겹친 트랜잭션에서 쓰기를 잃는다(05-08) | +| 13 | 확장성 | 다른 영역 — 11 | — | — | 적용 제외 | +| 14 | 성능 성숙도 | 적용 — 테스트 실행 시간 | M2 / M2 | E2 | 충족(개발 장비 기준) — unit 10s·component 7s·integration 12s. CI 러너 시간은 미검증. merge CI는 `test:unit` 뒤 `test:coverage`가 같은 테스트를 다시 돈다 | +| 15 | 보안 성숙도 | 다른 영역 | — | — | 적용 제외 | +| 16 | 의존성 성숙도 | 다른 영역 — 13 | — | — | 적용 제외 | +| 17 | API / Contract 성숙도 | 부분 적용 — 계약 테스트 계층 | M3 / M3 | E2 | 부분 충족 — runtime-schema·contract 테스트와 scenario 증거 있음. 실행기 연결 공백(10-03) | +| 18 | 배포 성숙도 | 다른 영역 — 11·13 | — | — | 적용 제외 | +| 19 | 설정 성숙도 | 적용 — 테스트 러너 설정 | M2 / M2 | E2 | 부분 충족 — `run-vitest.ts`가 Node 버전·NODE_ENV·생성기를 고정한다. `include` 없음(10-05) | +| 20 | 개발자 경험 | 적용 — 테스트 실행 경로 | M2 / M1 | E2 | 미충족 — 새 clone에서 `test:unit` 실패(10-01), 파일 하나 실행 방법 미문서(10-05) | +| 21 | Guardrail 성숙도 | 적용 — 테스트 증거·커버리지 게이트 | M3 / M2 | E2 | 부분 충족 — scenario receipt 검사는 강함. skip 검사 우회(11-08 보강), 커버리지 범위(10-04), 명령에 속하지 않는 테스트(12-04) | +| 22 | 추상화 성숙도 | 적용 — 테스트 대역·검사 도구 | M2 / M2 | E1 | 부분 충족 — IndexedDB 대역이 차이를 숨김(05-08). risk-coverage 도구 약 1.5k줄은 비용 대비 효과 검토 대상(12-10) | +| 23 | 일관성 | 적용 — 테스트 작성 방식 | M2 / M2 | E1 | 부분 충족 — GWT 표기를 품질로 세지 않음. fake timer 복원 방식이 파일마다 다름(10-06) | +| 24 | 네이밍 / 의미 성숙도 | 적용 — 테스트 계층 이름 | M1 / M1 | E1 | 부분 충족 — `tests/unit`에 프로세스를 띄우는 테스트가 있음(10-07 ④) | +| 25 | 조직 확장성 | 적용 제외 — 작성자 1인, 구조적 준비만 | — | — | 적용 제외 | +| 26 | Ownership 성숙도 | 부분 적용 — quarantine·커버리지 owner | M2 / M1 | E2 | 부분 충족 — 커버리지 모듈에 owner가 있음. quarantine 만료를 검사하지 않음(11-08) | +| 27 | 삭제 가능성 | 다른 영역 — 14 | — | — | 적용 제외 | +| 28 | 회복 가능성 | 적용 제외 — 테스트 계층 밖 | — | — | 적용 제외 | + +## 6. 미검증 목록 + +| 항목 | 이유 | 확인하려면 | +|---|---|---| +| main 트리 전체 `test:unit`·`test:coverage` 결과, 실제 커버리지 수치 | 공유 작업 트리에서 전체 게이트 실행 금지 | 오케스트레이터 실행 결과. 단, main 트리 `test:unit` 통과는 로컬 `artifacts/` 때문일 수 있다(10-01) | +| CI 러너에서의 시간·flaky(특히 10-02) | 이 repo에서 CI가 돌지 않음(12-01) | CI를 켜고 `test:coverage`를 20회 반복 | +| unit 140파일 중 표본 밖 파일의 검출력 | 범위 분담(모듈별은 01~09) | 영역별 변이 실험 | +| jsdom 에뮬레이션(`tests/component/app-shell.test.tsx:17-57`의 modal dialog)과 실제 브라우저 차이 | 브라우저 테스트는 11 영역 | 11 영역의 E2E·capability 결과 대조 | +| MSW scenario 19개의 개별 구현이 실제 서버 의미와 맞는지 | 카탈로그 앞부분만 읽음 | `tests/mocks/scenarios/catalog.ts` 전체와 백엔드 계약 대조 | diff --git a/docs/reviews/2026-09-25-maturity-review/11-tests-browser-release-scale.md b/docs/reviews/2026-09-25-maturity-review/11-tests-browser-release-scale.md new file mode 100644 index 00000000..adea4770 --- /dev/null +++ b/docs/reviews/2026-09-25-maturity-review/11-tests-browser-release-scale.md @@ -0,0 +1,251 @@ +# 테스트 체계(브라우저·릴리스·규모·시스템) 성숙도 리뷰 + +> 검토일: 2026-09-25 · 기준: `main` / `4626b73` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 범위: `tests/e2e/`(976줄), `tests/browser-capabilities/`(3,903줄), `tests/visual/`(54줄 + 기준 이미지 5장), `tests/storybook/`(24줄), `tests/release/`(608줄), `tests/scale/`(2,099줄), `tests/system/`(2,747줄, 훑어봄), `tests/architecture/`(431줄), `tests/scripts/`(232줄), `playwright*.config.ts` 5개(184줄), `config/scale/`, `config/performance/`, 문서 5개(`docs/testing/taxonomy.md`, `docs/operations/performance-evidence.md`, `docs/reviews/2026-09-23-extreme-scale-*.md`, `docs/reviews/2026-09-23-release-coherence-baseline.md`). 판정을 위해 함께 읽은 스크립트: `scripts/drill-runbook.ts`, `scripts/test-performance.ts`, `scripts/scale/*`(일부), `scripts/verify-extreme-scale.ts`, `scripts/verify-browser-capability-evidence.ts`, `scripts/check-test-evidence.ts`(일부), `config/ci/gates.json`(명령·게이트), `.gitea/workflows/quality-gates.yml`. +> 영역 판정(35.8): **조건부 사용 가능** — 브라우저 capability 테스트, Service Worker 두 빌드 업데이트 테스트, 부트 정합성 테스트는 참고 구현으로 복제해도 된다. 런북 drill(11-01)을 복구 증거로, 라우트 a11y·visual 대기 방식(11-02)을 검사 패턴으로, 규모 기준선(11-03)을 CI 게이트로, lab 성능 1회 측정(11-07)을 릴리스 판정으로 그대로 쓰는 것은 보류한다. + +## 1. 결론 + +- **운영 승격 게이트의 런북 drill 5개는 복구를 하지 않는다.** 단언 일부가 상수 `true`다. 격리 worktree에서 `dist/assets/*.js`를 전부 지워 앱이 부팅할 수 없게 만들어도 5개 모두 PASS였다(11-01). `PROD_PROMOTION_READY`가 이 PASS에 의존한다. +- **라우트별 axe 검사가 lazy route의 로딩 화면을 검사할 때가 있다.** 같은 빌드에 넣은 a11y 위반을 한 번은 24/24 잡고, 다음엔 Chromium에서 0/3, 1/5만 잡았다. 상태 화면 visual 기준 이미지는 아예 로딩 화면이다(11-02). +- **규모 증거는 생성기 지역성·알고리즘 복잡도·요청 증폭 상한을 보여 준다.** 이름만 다른 stub 기능으로 만든 증거라서, 선언된 앱당 상한(컨텍스트 20 × 기능 200)의 실제 타입 검사·빌드 비용은 측정되지 않았다(11-04). 규모 회귀 게이트는 기준선을 만든 CPU 한 종류에서만 통과할 수 있고, "CI execution tiers"라는 설명과 달리 어느 CI job에도 없다(11-03). +- **flaky를 재시도로 숨기지는 않는다.** Playwright 설정 5개 모두 `retries`가 없고(기본 0), 공용 fixture가 콘솔 오류·페이지 오류·요청 실패를 실패로 만든다. 다만 `test.only` 차단은 capability 설정에만 있다(11-08). +- **핵심 흐름 E2E는 "보호 화면이 열린다"까지만 본다.** 목록 응답을 스키마 위반으로 바꿔도 E2E가 통과했다. 저장 성공·실패 후 재시도 브라우저 테스트가 없다(11-06). lab 성능 게이트는 1회 측정이고 상호작용 지표에 Playwright 왕복 시간이 들어간다(11-07). +- **미검증:** CI 러너에서의 실제 결과, e2e·capability 전체 실행, browser soak, `test:system`. + +## 2. 범위와 방법 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 | `clean-architecture-frontend-template`, 영역 11(테스트 체계: 브라우저·릴리스·규모·시스템) | +| 커밋·상태·시점 | `main` / `4626b73`, 2026-09-25. 코드 변경 실험은 모두 `scratchpad/11/wt` 분리 worktree에서 했고, 끝난 뒤 `git worktree remove --force`로 지웠다 | +| 실행 환경 | Node v24.14.0, pnpm 11.17.0, Playwright 1.62.0(chromium-1234, firefox-1538, webkit-2336), Intel Core Ultra 7 155H(22 스레드). 실행 중 loadavg 17~28(다른 영역 에이전트 동시 실행) | +| 읽은 코드·설정 | 머리말 범위 전체. `tests/system/`은 테스트 이름과 대표 3파일 앞부분만 읽었다(CI 러너·공급망 영역 12·13과 겹침) | +| 실행한 테스트·실험 | 아래 표 | +| 확인하지 못한 범위 | e2e 전체·a11y 전체·browser-capabilities 전체·storybook spec, `test:system`(systemd·bwrap·cgroup v2 필요), `check:scale:nightly` browser soak, `service-worker-update.spec.ts`(두 번 빌드), CI 실행 이력(권한 없음) | +| 이전 리뷰와 비교 | 직전 리뷰(2026-09-24)는 `tests/` 대부분을 범위 밖으로 뒀다. 관련 항목 6.9-1(부트 reload 반복)·6.6-1(실제 브라우저 SW 업데이트 테스트 요구)은 현재 코드에서 다시 확인했다 | + +실행 목록(모두 분리 worktree, 원본 `node_modules` 심볼릭 링크. pnpm의 deps 검사가 설치를 시도하므로 `pnpm_config_verify_deps_before_run=false`로 끄고 `node`/`npx`로 직접 실행): + +| 명령·실험 | 결과 | +|---|---| +| `node scripts/run-vitest.ts run tests/release tests/architecture tests/scripts` | 11파일 58개 통과 | +| `node scripts/run-vitest.ts run tests/scale` | 14파일 83개 통과 | +| `node scripts/generate-product-feature-index.ts && node scripts/build-frontend.ts` | 빌드 성공(local profile, SW 없음) | +| `playwright test --config playwright.visual.config.ts`(포트만 4391로, 서버는 `vite preview`) | 5/5 통과 | +| `playwright test tests/e2e/reference-route.spec.ts` 3엔진 | 3/3 통과 | +| 변이: reference-route 목 응답을 503으로 | spec 단언은 통과, strict fixture의 콘솔 오류 검사로만 실패 | +| 변이: reference-route 목 응답을 스키마 위반 200으로 | **통과**. 화면은 오류 문구 표시 | +| 프로브: 라우트별로 spec과 같은 순서(goto → `main` 표시 → axe) | `/`, `/examples/ui`, `/examples/states`, `/examples/platform`에서 axe 검사 노드 74~79개, h1 0개. h1을 기다리면 106/374/182/351개 | +| 변이: `state-gallery-page.tsx`에 alt 없는 `img`와 이름 없는 `button` 추가 후 `accessibility.spec.ts` 반복 | 1차 3엔진×8회 24/24 검출 → 2차 Chromium 0/3 → 3차 Chromium 1/5, Firefox 5/5, WebKit 5/5 | +| `node scripts/drill-runbook.ts FE-RB-001..005` | 5개 PASS | +| 같은 명령, `dist/assets/*.js` 전부 삭제 후 | **5개 PASS**. FE-RB-002 record의 복구 단언 4개 모두 `passed: true` | +| `node scripts/scale/check-scale-baseline.ts` | exit 1, `INCOMPLETE`(compiler 16축·absolute 28·growth 8 통과, CPU가 달라 timing 0) | +| `node scripts/test-performance.ts` 6회(포트만 4394, `--strictPort`) | 6회 모두 FAIL. interaction 326~1103ms, LCP 1820~2740ms, CLS 0~0.0043 | + +## 3. 확인된 강점 + +- **flaky가 재시도로 숨지 않는다.** `playwright*.config.ts` 5개 모두 `retries`가 없다(기본 0). 공용 fixture가 console error/warning, `pageerror`, `requestfailed`를 모아 테스트 끝에 실패시킨다(`tests/support/browser/strict-browser-test.ts:15-43`). 11-06 변이에서 503을 잡은 것도 이 fixture다. +- **브라우저 capability 테스트는 3엔진에서 같은 케이스가 실제로 돌았는지 확인한다.** 증거 검사가 junit의 failures·errors·skipped가 0인지, 엔진별 케이스 집합이 Chromium과 같은지 본다(`scripts/verify-browser-capability-evidence.ts:11`, `:53`). 여러 탭 동작도 실제 브라우저 두 페이지로 확인한다(`tests/browser-capabilities/cross-context-invalidation.spec.ts:160`, `:223`, `tests/browser-capabilities/indexeddb-runtime.spec.ts:920`, `:972`). +- **신·구 빌드 공존을 실제 브라우저에서 확인한다(SW 구성).** 운영 빌드 A·B를 만들어 A에서 B로 업데이트한 뒤, 서버에서 지운 A의 route 청크를 이전 캐시가 응답하는지 본다(`tests/e2e/service-worker-update.spec.ts:207-247`). 직전 리뷰 6.6-1이 요구한 형태다. Firefox 제외는 owner·만료일이 있는 quarantine으로 표시돼 있다(`:148`). +- **부트 정합성 테스트는 실제 loader와 복구 정책을 쓴다.** `loadRuntimeConfig`, `loadReleaseManifest`, `releaseMismatchKey`, `createReleaseMismatchRecovery`를 그대로 호출한다(`tests/release/release-fixture.ts:4-8`, `:184-223`). 직전 리뷰 **6.9-1(번갈아 바뀌는 mismatch 키로 reload 반복)은 해결됐다.** 두 종류의 mismatch가 번갈아 와도 reload는 1회다(`tests/release/mixed-replica.test.ts:105-117`, `tests/release/release-matrix.test.ts:236-250`). +- **규모 증거가 "통과"를 과장하지 않게 만든 장치가 있다.** 건너뛴 단계가 있으면 tier가 `incomplete`로 끝난다(`scripts/scale/run-scale-profile.ts:157`, `:185`). CPU가 다르면 timing을 비교하지 않고 통과로 치지 않는다(`scripts/scale/scale-baseline.ts:202`, `:357`). 기준선에 CPU·Node·TypeScript 버전·승인자가 있다(`config/scale/benchmark-baseline.json:3-10`). 요청 증폭 테스트는 실제 V3 executor로 1만 interaction을 돌린다(`tests/scale/traffic/synthetic-traffic.ts:41-92`). soak은 heap 표본 전에 GC를 강제한다(`scripts/scale/browser-soak.ts:456`). +- **아키텍처 테스트에 음성 fixture가 있다.** request-fanout 금지 fixture 3개 거부(`tests/architecture/request-fanout.test.ts:37-44`), 다른 앱 기능이 섞인 번들 거부(`tests/architecture/app-build-input.test.ts:56` 이후), vendor SDK 규칙의 정규식 의미 확인(`tests/architecture/observability-boundaries.test.ts:166-185`). + +## 4. 발견 사항 (36.3) + +### 11-01 런북 drill이 복구를 하지 않고, 일부 단언이 상수 `true`라서 앱이 깨진 빌드에서도 PASS한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 28, 7, 10, 21, 24 | +| 근거 | `scripts/drill-runbook.ts`: FE-RB-001 `:118-120` `injectedMountFailure = true`라서 `negativeFixtureFailedAsExpected`가 항상 true. "product root mount" 근거는 runtime schema parse 성공(`:126`). FE-RB-002 "entry and lazy assets reachable"·"critical route smoke"는 `dist/index.html`·`dist/.vite/manifest.json` 파일 존재 확인(`:162-166`, `:173`, `:180`). FE-RB-003 `triggerAsserted: true`(`:199`), "failure rate at baseline" `true`(`:202`). FE-RB-004 "product flow unaffected" `true`(`:241`). FE-RB-005 `triggerAsserted: true`(`:271`), "critical smoke" `true`(`:276`). FE-RB-005 명세는 "이전 불변 tuple 선택 → 호환성 확인 → 원자적 전환 → smoke"인데(`config/runbooks/runbooks.json` FE-RB-005 `containment`), drill은 현재 `dist`의 tuple 정합성과 고정된 음성 tuple 하나만 본다. `providerVerificationRequired: true`는 record에만 남고 읽는 곳이 없다. `PROD_PROMOTION_READY`는 FE-GATE-016·021~025의 PASS만 본다(`scripts/lib/promotion-readiness.ts:27-34`, `:50-51`). FE-GATE-016과 FE-GATE-025는 같은 `drill:runbook -- FE-RB-005`를 실행한다(`config/ci/gates.json` `drill-runbook`). 문서는 "positive fixture 통과와 의도적 negative fixture 거부가 있어야 검증된 통제"라고 적는다(`docs/testing/taxonomy.md:80-82`). **실행:** 분리 worktree에서 빌드 후 5개 PASS. `dist/assets/*.js`를 전부 지운 뒤에도 5개 PASS, FE-RB-002 record의 복구 단언 4개 모두 `passed: true` | +| 발생 조건 | `workflow_dispatch` stage `production`/`field`에서 production gate job 실행(`.gitea/workflows/quality-gates.yml:370-384`) | +| 영향 | 운영 승격 단계가 복구 능력을 확인하지 않고 통과한다. 다운스트림은 "drill PASS"를 복구 연습 증거로 받아들인다. 같은 drill이 두 게이트 ID로 두 번 세어진다 | +| 심각도·우선순위 | Medium · P1 — 사용자 데이터 피해는 없다. 하지만 운영 승격 게이트가 거짓 PASS를 내는 구조가 템플릿 기본값으로 복제된다. "운영 승격 준비"를 주장하기 전에 고쳐야 한다 | +| 통제·증거 | 목표 M3 / 확인 M1(런북 문서만 유효) · E3(worktree 실험) | +| 확실성과 남은 가정 | 정적 확인과 실행이 일치한다. provider(호스팅)는 repo 밖이라 실제 전환 리허설을 템플릿이 전부 할 수 없다는 점은 인정한다. 문제는 할 수 없는 부분을 PASS로 적는 것이다. 영역 13(릴리스 스크립트)과 겹칠 수 있다 | +| 최소 개선 방향 | (1) 상수 `true` 단언을 없앤다. 로컬에서 확인할 수 없는 단언은 `UNVERIFIED`로 적고, 하나라도 있으면 gate 결과를 `UNVERIFIED`로 낸다(`GateResult`에 이미 `UNVERIFIED`가 있다, `promotion-readiness.ts:39`). (2) 로컬에서 가능한 부분은 실제로 한다: 두 release 디렉터리와 active pointer를 로컬 정적 서버로 흉내 내고, 전환 후 Playwright smoke(부트 1회·route 1개)를 돌린다. (3) FE-GATE-016/025 중복을 정리한다. 대안: drill 이름을 "사전 조건 검사"로 바꾸고 승격 공식에서 뺀다 | +| 비용·부작용 | 로컬 smoke 추가 시 브라우저 설치가 production gate job에 필요하다. `UNVERIFIED`로 바꾸면 현재 `PROD_PROMOTION_READY`가 false가 된다(의도된 결과) | +| 완료 기준 | JS 자산이 없는 `dist`에서 FE-RB-002·FE-RB-005가 실패한다. provider 없이 실행하면 PASS가 아니라 UNVERIFIED가 나온다. 코드에 상수 `true` 복구 단언이 없다 | +| 검증 방법 | 위 실험(자산 삭제 후 drill 실행)을 다시 한다. drill 단위 테스트에 "깨진 dist → 실패" 케이스를 추가한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 11-02 라우트별 axe 검사와 상태 화면 visual 검사가 lazy route의 로딩 화면을 검사한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 10, 21, 9 (가이드 32.3 접근성) | +| 근거 | `tests/e2e/accessibility.spec.ts:12-16`은 goto → `main` 표시 확인 → axe 순서다. `main`은 앱 셸이 먼저 그리고, route 청크가 오기 전에는 로딩 화면("화면을 준비하고 있습니다.")이 들어 있다. **프로브:** 같은 순서로 실행하면 `/`, `/examples/ui`, `/examples/states`, `/examples/platform` 모두 axe 검사 노드 74~79개, 검사한 h1 0개. h1을 기다린 뒤에는 106/374/182/351개. **변이:** 상태 화면에 alt 없는 `img`와 이름 없는 `button`을 넣고 같은 빌드로 spec을 반복했다. 1차 24/24 검출, 2차 Chromium 0/3, 3차 Chromium 1/5·Firefox 5/5·WebKit 5/5. 보호 라우트 4개(`/examples/reference-resources*`)는 로그인하지 않아 "세션이 필요합니다" 화면만 검사한다. **visual:** `tests/visual/platform.visual.spec.ts:35-43`은 기다리지 않고 `main`을 찍는다. 기준 이미지 `tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/state-surfaces-light-chromium-visual-linux.png`(1040×1028)가 로딩 화면 자체다. 실행 결과 5/5 통과 | +| 발생 조건 | 라우트 청크가 axe 실행 전에 도착하지 않을 때. 러너 부하·엔진에 따라 달라진다 | +| 영향 | a11y 게이트(FE-GATE-009)가 페이지 본문 위반을 실행마다 다르게 잡는다. 거짓 통과가 나거나, 관계없는 PR에서 갑자기 실패한다. reference feature 목록·상세·폼은 자동 axe 대상이 아니다. visual의 상태 화면 계약은 비어 있다. 다운스트림은 이 패턴을 자기 라우트에 그대로 복제한다 | +| 심각도·우선순위 | Medium · P2 — 보안·데이터 피해는 없다. 접근성 회귀 검출이 우연에 맡겨지고 샘플로 복제된다 | +| 통제·증거 | 목표 M3 / 확인 M2(검사는 있으나 대상이 불안정) · E3 | +| 확실성과 남은 가정 | 변이 검출률이 실행마다 바뀐 것을 직접 확인했다. CI 러너에서의 검출률은 미확인 | +| 최소 개선 방향 | axe·스크린샷 전에 `await expect(page.getByRole("heading", { level: 1 })).toBeVisible()`처럼 route 본문이 그려졌음을 확인한다. 보호 라우트는 데모 로그인 뒤 검사하는 케이스를 추가한다. 상태 화면 기준 이미지를 다시 만든다 | +| 비용·부작용 | 한 줄 대기 추가. 기준 이미지 1장 재생성 | +| 완료 기준 | 같은 변이를 넣으면 3엔진에서 10/10 검출한다. 상태 화면 기준 이미지에 제목과 상태 표면이 보인다 | +| 검증 방법 | 위 변이 실험을 `--repeat-each=10`으로 반복한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 11-03 규모 회귀 게이트는 기준선을 만든 CPU에서만 통과할 수 있고, "CI tier"라는 설명과 달리 어느 CI job에도 없다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 13, 14, 21, 24 | +| 근거 | `scripts/scale/run-scale-profile.ts:6-13`은 pr/main/nightly/release를 "CI execution tiers"라고 설명한다. workflow에는 schedule 트리거가 없고(`.gitea/workflows/quality-gates.yml:4-21`), `config/ci/gates.json` 명령 목록에 `check:scale:*`·`check:scale:baseline`·`verify:extreme-scale`이 없다. 기준선 비교는 CPU 모델이 다르면 timing을 비교하지 않고 `incomplete`로 끝나며 exit 1이다(`scripts/scale/scale-baseline.ts:202`, `:357`). 기준선 CPU는 `i5-10400F`(`config/scale/benchmark-baseline.json:7`). **실행:** 이 호스트(Core Ultra 7 155H)에서 `check-scale-baseline.ts` → exit 1 `INCOMPLETE`(CPU와 무관한 compiler 16축·absolute 28·growth 8은 모두 통과). 그래서 `baseline-regression` 단계를 포함한 main·nightly·release tier(`run-scale-profile.ts:58-76`, `:78`, `:96`)는 다른 기계와 CI 러너에서 항상 실패한다. 수락 문서의 "24/24 PASS"는 컨테이너 1회 실행 기록이다(`docs/reviews/2026-09-23-extreme-scale-acceptance.md:27-37`) | +| 발생 조건 | 조합 경로의 복잡도 회귀, 요청·telemetry 증폭 회귀 등 규모 속성을 깨는 변경 | +| 영향 | 규모 속성 회귀를 자동으로 잡는 경로가 없다. 다운스트림은 기준선을 자기 기계에서 재승인하기 전에는 이 게이트를 쓸 수 없다 | +| 심각도·우선순위 | Medium · P2 — 규모가 이 템플릿의 선언된 목표 축인데, 그 회귀 검출이 수동 1회 기록에 머문다 | +| 통제·증거 | 목표 M3 / 확인 M1(스크립트와 기록만) · E3 | +| 확실성과 남은 가정 | 일반적인 "CI에 연결되지 않은 테스트" 문제는 12-04와 같은 원인이다. 여기서는 규모 게이트 고유의 기계 결합 문제만 적는다. **12-04 보정:** `tests/architecture`와 `tests/release`는 FE-GATE-020의 제거 fixture 안에서 `test:all`(→ `test:platform`, `check:release-coherence`)로 간접 실행된다(`scripts/test-sample-removal.ts:321`, `scripts/test-realtime-runtime-removal.ts:122`, `scripts/test-optional-recipe-removal.ts:68`, `scripts/test-browser-file-storage-runtime-removal.ts:139`). 전혀 실행되지 않는 것은 `tests/scale/`, `tests/scripts/`, scale tier 스크립트다 | +| 최소 개선 방향 | (1) CPU와 무관한 축(compiler count, growth shape, 요청 증폭 비율)만으로 된 tier를 PR 게이트에 넣는다. 이 축들은 지금도 다른 CPU에서 통과한다. (2) timing 비교는 기준선과 같은 러너 라벨에서만 도는 별도 job으로 나누고, 기준선 재승인을 러너 기준으로 한다. (3) `run-scale-profile.ts` 설명의 "CI" 표현을 실제와 맞춘다 | +| 비용·부작용 | PR 게이트 시간 증가(PR tier는 이 호스트에서 수 초~수십 초 규모). timing job에는 고정 러너가 필요하다 | +| 완료 기준 | PR에서 CPU 무관 scale tier가 실행되고 증거가 남는다. 다른 CPU에서도 exit 0이며 timing은 advisory로 기록된다 | +| 검증 방법 | 기준선과 다른 CPU에서 PR tier를 실행해 exit 0을 확인한다. 조합 workload에 이차 누적을 일부러 넣으면 PR tier가 실패하는지 본다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 (관련: 12-04) | + +### 11-04 규모 증거는 이름만 다른 stub 기능으로 만든 것이라, 선언된 앱당 상한(20 × 200)의 실제 비용은 측정되지 않았다 + +| 필드 | 내용 | +|---|---| +| 성격 | 미검증 | +| 관련 관점 | 13, 14 (가이드 13절 "과장 방지", 30.6) | +| 근거 | 디스크 fixture 기능은 파일 3개에 `PAGE = "-page"` 문자열뿐이다(`tests/scale/filesystem-topology.ts:24-37`). App A는 100개(`:15`). tsc fixture는 React·zod·플랫폼 계약을 import하지 않는 독립 모듈이다(`scripts/scale/collect-tsc-diagnostics.ts:74-97`). 기준선에서 실제 앱(기능 1개) instantiations는 699,730, toy 기능 400개는 33,998이다(`config/scale/benchmark-baseline.json:100-125`). S3/S4(10만·100만)는 개수만 저장하는 in-memory 모델(`tests/scale/synthetic-topology.ts:43-49`)과 분할 산술(`tests/architecture/topology-cardinality.test.ts:72-99`)이다. 선언된 상한: `CONTEXT_MAX_FEATURES = 200`(`src/contexts/reference-context/context-module.ts:9`), `APP_MAX_CONTEXTS = 20`(`src/apps/template-app/app-module.ts:6`) → 앱당 4,000 | +| 발생 조건 | 다운스트림이 한 앱에 실제 기능을 수백 개 이상 넣을 때 | +| 영향 | **증명하는 것:** 생성기가 선택한 앱의 선언만 읽는다(지역성). 조합·조회 알고리즘이 선형이다. 요청 증폭에 상한이 있다. **증명하지 않는 것:** 실제 기능 모양으로 한 앱의 기능이 늘 때 타입 검사·빌드·번들·테스트 시간, route 수, 메모리. 상한 값이 "검증된 수용 범위"로 읽힐 수 있다. 실제 비용의 중심(기능 1개 앱이 이미 70만 instantiation)은 측정 밖이다 | +| 심각도·우선순위 | Medium · P2 — 이 repo의 규모 목표가 기능 수 축이다. 측정한 축과 조건이 문서에 분리돼 있지 않다 | +| 통제·증거 | 목표 M3 / 확인 M1(상한 선언과 상한 초과 거부만 M3) · E2 | +| 확실성과 남은 가정 | 수락 문서는 "전역 증가에도 한 앱은 변하지 않는다"를 주장하며, 그 주장 자체는 증거와 맞다. 앱 내부 증가 비용은 주장하지 않았지만 상한 값의 근거도 적혀 있지 않다 | +| 최소 개선 방향 | reference feature를 복제한 실제 모양의 기능(이름·ID만 바꾼 것) 25/100/400개로 앱 1개를 만들어 `tsc --extendedDiagnostics`, `vite build` 시간, 초기·lazy 청크 크기를 측정하고 기준선에 넣는다. 수락 문서에 "검증한 증가 축 / 조건 / 검증하지 않은 축" 표를 둔다 | +| 비용·부작용 | fixture 생성기 1개와 측정 시간(수 분). 기준선 재승인 | +| 완료 기준 | 실제 모양 기능의 로컬 증가 측정이 기준선에 있고, 상한 값의 근거 범위가 문서에 적혀 있다 | +| 검증 방법 | 측정을 두 번 돌려 증가 곡선과 분산을 기록한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 11-05 release 테스트의 "구 자산 도달성"은 테스트 fixture 자신을 검사하고, 기본 구성의 구 탭 청크 복구는 실제 브라우저에서 확인되지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 18, 10, 24 | +| 근거 | `tests/release/old-asset-reachability.test.ts:1-3`은 `release-fixture.ts`만 import한다. 테스트 4개 모두 테스트 코드인 `createReleaseFixture().fetch`(`tests/release/release-fixture.ts:87-160`)의 동작을 확인한다. 제품 코드나 배포 스크립트는 호출하지 않고, 읽는 설정은 `config/hosting/cache-policy.json`뿐이다. 수락 문서 17행은 "old-asset reachability를 검증한다"고 적는다(`docs/reviews/2026-09-23-extreme-scale-acceptance.md:23`). 기본 구성은 `serviceWorker: null`이다. 이때 구 탭 → 청크 404 → `ChunkRecoveryBoundary` → 1회 reload 흐름은 실제 브라우저에서 오류 문구 분류만 확인하고(`tests/browser-capabilities/chunk-load-error.spec.ts:7-29`), 나머지는 jsdom 컴포넌트 테스트다. 실제 두 빌드 공존 테스트는 SW ACTIVE 구성에만 있다(`tests/e2e/service-worker-update.spec.ts:207-247`). 자산 보존은 repo 밖 provider 책임이다(`docs/operations/release-cache-rollback.md:3-7`) | +| 발생 조건 | 기본 구성으로 배포한 뒤, 이전 빌드를 연 탭이 lazy route로 이동할 때 | +| 영향 | 문서 주장보다 증거가 좁다. 가이드 32절의 "새 배포 후 기존 탭" 시나리오가 기본 구성에서 실제 브라우저로 끝까지 돈 적이 없다. 청크 오류 문구나 reload 동작이 브라우저마다 달라도 jsdom 테스트는 통과한다 | +| 심각도·우선순위 | Low · P2 — 부트 정합성(fail-closed)은 실제 loader로 확인된다. 남은 것은 기본 구성의 복구 흐름과 문서 표현이다 | +| 통제·증거 | 목표 M3 / 확인 M2(부트 정합성 M3, 구 탭 복구 M2) · E2 | +| 확실성과 남은 가정 | 컴포넌트 테스트(`tests/component/chunk-recovery-boundary.test.tsx`)는 이 영역 밖이라 내용 확인은 이름·일부 줄만 했다 | +| 최소 개선 방향 | old-asset 테스트를 "fixture 계약"으로 이름을 낮추거나 지운다. SW 없이 빌드 A·B를 번갈아 제공하는 Playwright 테스트를 1개 추가한다(`tests/e2e/support/service-worker-builds.ts` 재사용): A 탭에서 B 배포 후 A 전용 청크가 404이면 1회 reload 뒤 B로 부팅하고, 두 번째 실패에서는 reload하지 않는다 | +| 비용·부작용 | 두 번 빌드하는 테스트 1개(SW 테스트와 빌드 공유 가능) | +| 완료 기준 | 기본 구성의 구 탭 복구가 3엔진 실제 브라우저에서 한 번 이상 끝까지 확인된다. 문서 17행이 실제 증거 범위와 맞다 | +| 검증 방법 | 새 spec에서 reload 가드를 일부러 끄면 실패하는지 확인한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 11-06 핵심 사용자 흐름 E2E가 "보호 화면이 열린다"까지만 확인한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 10, 6 (가이드 30.5 샘플 대표성) | +| 근거 | `tests/e2e/reference-route.spec.ts:21-31`은 제목과 "인증됨"만 확인하고, 목 데이터 "Browser reference"가 화면에 나오는지 보지 않는다. **변이:** 목 응답을 스키마 위반 200(`[{ wrong: true }]`)으로 바꿔도 통과했고 화면은 오류 문구를 보였다. 503으로 바꾸면 spec 단언이 아니라 공용 fixture의 콘솔 오류 검사(`tests/support/browser/strict-browser-test.ts:41`)로만 실패했다. `tests/e2e/reference-form.spec.ts:12-50`은 검증 실패·취소 확인·320px만 본다. 저장 성공, 실패 후 재시도, 로그아웃, 세션 만료 브라우저 테스트는 없다. 같은 흐름의 로직은 jsdom 컴포넌트 테스트에 있다(`tests/features/reference-feature/reference-page.test.tsx:163-446`) | +| 발생 조건 | 운영 빌드에서만 생기는 연결 오류(매퍼, base URL, codec 번들링 등)로 목록·저장이 항상 오류가 되는 변경 | +| 영향 | 그런 변경이 E2E를 통과한다. 템플릿의 샘플 E2E가 약한 단언 패턴을 가르친다 | +| 심각도·우선순위 | Low · P2 — 흐름 로직은 컴포넌트 테스트가 다루고, HTTP 오류는 공용 fixture가 잡는다. 남는 것은 운영 빌드 전용 결함의 검출이다 | +| 통제·증거 | 목표 M3 / 확인 M2 · E3 | +| 확실성과 남은 가정 | 변이 결과는 직접 확인했다 | +| 최소 개선 방향 | reference-route에 `getByText("Browser reference")` 단언을 추가한다. 저장 성공(POST 목 → 목록 또는 상세로 이동)과 실패 → 재시도 E2E를 1개씩 추가한다 | +| 비용·부작용 | spec 2개, 3엔진에서 수 초 | +| 완료 기준 | 위 두 변이(스키마 위반 200, 503)에서 spec 단언이 실패한다. 저장 성공과 재시도가 브라우저에서 한 번씩 돈다 | +| 검증 방법 | 같은 변이 실험을 다시 한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 11-07 lab 성능 게이트가 1회 측정이고, 상호작용 지표에 Playwright 왕복 시간이 들어가며, 측정 대상 서버를 확인하지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 14, 10, 24 | +| 근거 | `scripts/test-performance.ts:55-101`은 브라우저를 한 번 실행해 한 번 잰다. 반복·중앙값이 없다. `namedInteractionMs`는 Node의 `performance.now()`로 잰 `click()` + `heading.waitFor()` 시간이다(`:92-101`). CDP 왕복과 lazy 청크 다운로드(200KB/s)가 포함된다. 이 값을 INP와 같은 200ms 예산과 비교한다(`config/performance/budgets.json:10`). 기록에는 브라우저 버전·Node·플랫폼·네트워크·CPU 감속 배율·캐시 상태가 있지만 CPU 모델·코어 수·호스트 부하가 없다(`:108-124`). 4배 감속의 기준 기계를 알 수 없다. 서버는 `pnpm preview --port 4173`이고 `--strictPort`가 없다(`:27-32`). 4173이 이미 쓰이면 vite는 다른 포트로 뜨고, 스크립트는 4173에 떠 있는 다른 서버를 잰다. 빌드 식별값은 응답이 아니라 로컬 `dist/release-manifest.json`에서 읽는다(`:48-50`). **실행**(포트만 바꿈, loadavg 17~28/22스레드): 6회 모두 FAIL. interaction 326~1103ms, LCP 1820~2740ms. 같은 빌드에서 interaction이 3.4배 흔들렸다 | +| 발생 조건 | 러너 부하 변동, 공유 러너, 포트 충돌 | +| 영향 | 릴리스 게이트(FE-GATE-026) 판정이 러너 상태에 따라 뒤집힌다. 사람이 다시 돌려 통과시키면 숨은 재시도가 된다. 지표 이름("interaction")과 실제 측정 내용이 다르다 | +| 심각도·우선순위 | Medium · P2 — 릴리스 판정 게이트다. 사용자 피해는 없지만 판정 신뢰도가 낮다 | +| 통제·증거 | 목표 M3 / 확인 M2 · E3(부하 높은 호스트) | +| 확실성과 남은 가정 | 이 호스트는 다른 에이전트가 동시에 돌던 중이라 실제보다 느렸을 수 있다. 조용한 CI 러너에서 통과하는지는 미확인이다. 분산이 크다는 점과 기록 항목 누락은 부하와 무관하다 | +| 최소 개선 방향 | 5~9회 반복해 중앙값과 분산을 기록한다. 상호작용은 페이지 안 `PerformanceObserver`의 event entry(INP 근사)나 페이지 내부 시계로 잰다. CPU 모델·코어 수·loadavg를 기록한다. `--strictPort`를 쓰고 응답 HTML의 build-id를 확인한다 | +| 비용·부작용 | 게이트 시간이 수십 초 늘어난다 | +| 완료 기준 | 같은 빌드를 10회 돌려 판정이 뒤집히지 않거나, 뒤집힐 때 분산이 증거에 남는다. 다른 서버가 4173에 있으면 실패한다 | +| 검증 방법 | 반복 측정 결과의 분산 비교. 4173에 다른 서버를 띄운 상태에서 실행 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 11-08 Playwright에 `test.only` 차단과 quarantine 만료 검사가 없다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 21, 10, 26 | +| 근거 | `forbidOnly: true`는 `playwright.capabilities.config.ts:5`에만 있다. `playwright.config.ts`, `playwright.visual.config.ts`, `playwright.storybook.config.ts`에는 없다(Playwright 기본값 false). ESLint에 focused test 규칙이 없다. skip 검사는 파일 안에 quarantine 주석 형식이 하나라도 있는지만 본다(`scripts/check-test-evidence.ts:288-294`). `expires` 날짜가 지났는지 확인하지 않고, 주석 하나가 같은 파일의 모든 skip을 허용한다 | +| 발생 조건 | `test.only`가 섞인 커밋, 만료된 quarantine | +| 영향 | e2e·a11y·visual 게이트가 테스트 하나만 돌고 통과한다. 만료된 quarantine이 계속 통과한다 | +| 심각도·우선순위 | Low · P3 — 실수 한 번이 필요하고, 리뷰로도 잡을 수 있다 | +| 통제·증거 | 목표 M3 / 확인 M2(capability만 M3) · E1 | +| 확실성과 남은 가정 | 정적 확인. 실행하지 않았다 | +| 최소 개선 방향 | 모든 Playwright 설정에 `forbidOnly: true`. quarantine `expires`를 오늘 날짜와 비교하고, skip 호출마다 바로 위 줄 quarantine을 요구한다 | +| 비용·부작용 | 설정 3줄, 검사 수 줄 | +| 완료 기준 | `test.only`를 넣으면 e2e가 실패한다. 지난 날짜 quarantine이 실패한다 | +| 검증 방법 | 음성 fixture(`tests/fixtures/test-evidence/forbidden`)에 두 경우를 추가한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +## 5. 28개 관점 판정 (36.2) + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +|---|---|---|---|---|---| +| 1 | 코드 성숙도 | 다른 영역 — src 담당 영역 | — | — | 적용 제외 | +| 2 | 구조적 성숙도 | 다른 영역 — 12 | — | — | 적용 제외 | +| 3 | 변경 용이성 | 적용 — 테스트가 기능 추가·삭제를 따라가는가 | M2 / M2 | E1: 기대값을 설치된 레지스트리에서 읽음(`tests/e2e/platform-overview.spec.ts:5-9`, `accessibility.spec.ts:5-8`) | 충족 | +| 4 | 인지 부하 | 적용 — "어느 테스트가 어디서 도는가" | M1 / M1 | E1: `docs/testing/taxonomy.md`가 위치 규칙 제공 | 부분 충족 — `tests/architecture`·`tests/release`는 제거 fixture 안에서만 CI 실행, scale tier는 CI 없음(11-03, 12-04) | +| 5 | 위험 가시성 | 다른 영역 — src 담당 영역 | — | — | 적용 제외 | +| 6 | 실패 성숙도 | 적용 — 실패 주입 테스트 | M3 / M3(단위), M2(브라우저) | E2: scale traffic이 실제 executor로 전면·반복 장애 증폭 상한 확인 | 부분 충족 — 브라우저 수준 실패 복귀 없음(11-06) | +| 7 | 운영 성숙도 | 적용 — production drill 게이트 | M3 / M1 | E3 | 미충족 — 11-01 | +| 8 | 디버깅 가능성 | 적용 — 테스트 실패 진단 | M2 / M2 | E1: trace·screenshot `retain-on-failure`, junit, 게이트 로그 | 부분 충족 — 공용 fixture가 `pageerror`를 이름만 기록(`strict-browser-test.ts:27`)해 메시지가 빠진다 | +| 9 | 유지보수 성숙도 | 적용 — 기준 이미지·기준선 관리 | M2 / M2 | E1: 기준선 재승인에 owner·reason 요구 | 부분 충족 — visual 기준 이미지 1장이 로딩 화면(11-02) | +| 10 | 테스트 성숙도 | 적용(중점) | M3 / M2 | E3 | 부분 충족 — retry 0과 strict fixture는 좋다. 11-02, 11-05, 11-06, 11-08. `tests/scale/composition-scale.test.ts:47-48`의 재측정 1회는 의도가 주석에 있다 | +| 11 | 데이터 성숙도 | 적용 제외 — 이 영역에 데이터 이관·보관 경로 없음(IndexedDB capability 테스트 자체는 02 영역 대상) | — | — | 적용 제외 | +| 12 | 동시성 성숙도 | 적용 — 여러 탭 | M3 / M3(어댑터) | E1(이번에 실행 안 함) | 충족(어댑터 범위) — 실제 두 페이지로 BroadcastChannel·storage event·IDB versionchange 확인. 앱 전체 여러 탭 E2E는 없음 | +| 13 | 확장성 | 적용(중점) | M3 / M1 | E3 | 부분 충족 — 지역성·선형성·증폭 상한은 증거 있음. 앱 내부 증가는 미측정(11-04), 회귀 게이트는 기계 결합·CI 없음(11-03) | +| 14 | 성능 성숙도 | 적용(중점) | M3 / M2 | E3 | 부분 충족 — scale 기준선은 조건 기록 양호. lab 게이트는 1회 측정·조건 누락(11-07). field는 입력이 없으면 설계상 `FAIL_UNVERIFIED`(`performance-evidence.md:13-22`) | +| 15 | 보안 성숙도 | 다른 영역 — 12·13 (`tests/system`은 CI 러너·공급망 검증) | — | — | 적용 제외 | +| 16 | 의존성 성숙도 | 적용 — 브라우저 엔진 고정 | M2 / M2 | E2: Playwright 1.62.0 고정, CI가 3엔진 설치(`quality-gates.yml:67-69`) | 충족 | +| 17 | API / Contract | 다른 영역 — 03 | — | — | 적용 제외 | +| 18 | 배포 성숙도 | 적용(중점) — 신·구 버전 공존 | M3 / M2 | E2 | 부분 충족 — 부트 정합성은 실제 loader(M3), SW 구성 공존은 실제 브라우저. 기본 구성 구 탭 복구·자산 보존은 fixture·jsdom 수준(11-05) | +| 19 | 설정 성숙도 | 적용 — 테스트 서버 설정 | M2 / M2 | E1 | 부분 충족 — 포트 고정, `reuseExistingServer: false`, lab 성능은 `--strictPort` 없음(11-07) | +| 20 | 개발자 경험 | 적용 — 테스트 하나 실행 | M2 / M2 | E3 | 부분 충족 — spec 하나도 매번 전체 빌드(`playwright.config.ts:17-18`). 비TTY에서 `corepack pnpm build`가 deps 검사로 install을 시도하다 중단됨(관찰). `verify-extreme-scale.ts:204`만 이를 끈다(14 영역과 겹침) | +| 21 | Guardrail 성숙도 | 적용(중점) | M3 / M2 | E3 | 부분 충족 — 아키텍처 음성 fixture·capability 증거 검사는 실제 위반을 잡는다. 11-02, 11-08, 12-04 | +| 22 | 추상화 성숙도 | 적용 제외 — 테스트 헬퍼가 얇고 판정할 추상화 없음 | — | — | 적용 제외 | +| 23 | 일관성 | 적용 — 공용 fixture 사용 | M2 / M2 | E1: 한 곳(`chunk-load-error.spec.ts`)만 기본 `test`를 쓰며 오류를 일부러 내는 이유가 주석에 있음 | 충족 | +| 24 | 네이밍 / 의미 | 적용 — 게이트·지표 이름 | M1 / M1 | E1 | 미충족 — "drill"(11-01), INP 예산과 비교되는 "interaction"(11-07), "CI execution tiers"(11-03), "old-asset reachability"(11-05) | +| 25 | 조직 확장성 | 다른 영역 — 14 (1인 관리, 구조적 준비만) | — | — | 적용 제외 | +| 26 | Ownership | 적용 — quarantine·기준선 책임 | M2 / M2 | E1: quarantine에 owner·expires, 기준선에 승인자 | 부분 충족 — 만료일 미검사(11-08) | +| 27 | 삭제 가능성 | 다른 영역 — 14 (제거 fixture) | — | — | 적용 제외 | +| 28 | 회복 가능성 | 적용(중점) — runbook drill | M3 / M1 | E3 | 미충족 — drill이 복구를 하지 않고 상수 `true` 단언으로 PASS(11-01) | + +## 6. 미검증 목록 + +- **CI 러너에서의 실제 결과.** 게이트 실행 이력을 볼 권한이 없다. 11-02의 검출률과 11-07의 통과 여부는 CI 러너에서 다시 재야 한다. 필요한 것: 같은 커밋에서 FE-GATE-008/009/026 반복 실행 기록. +- **e2e·a11y·browser-capabilities·storybook 전체 실행.** spec 1개(reference-route)와 a11y 1개 케이스, visual만 실행했다. 필요한 것: 조용한 호스트에서 `test:e2e`, `test:a11y`, `test:browser-capabilities`, `test:storybook` 1회씩. +- **`service-worker-update.spec.ts`.** 빌드를 두 번 해야 해서 실행하지 않았다. 강점 3은 코드 읽기(E1) 기준이다. +- **browser soak(`check:scale:nightly`).** 120초 Chromium 1개 탭 조건이다. 더 긴 세션, Firefox·WebKit, 실제 API 성공 경로 soak은 없다. 필요한 것: 30분 이상 soak 1회와 heap 곡선. +- **`test:system`.** systemd·bubblewrap·cgroup v2 호스트가 필요하다. 이번 호스트에서 전제 확인을 하지 않았다. +- **lab 성능의 조용한 환경 값.** 이번 6회 측정은 부하가 높은 호스트에서 했다. 필요한 것: 부하 없는 기계에서 10회 반복. +- **field Web Vitals.** 개인정보 승인·표본 기준이 정해지지 않아 설계상 `FAIL_UNVERIFIED`다. 결함이 아니라 미정 상태다. +- **`tests/component/chunk-recovery-boundary.test.tsx`의 내용.** 11-05 판단에 필요한 부분만 이름 수준으로 확인했다(다른 영역 범위). diff --git a/docs/reviews/2026-09-25-maturity-review/12-guardrails-ci.md b/docs/reviews/2026-09-25-maturity-review/12-guardrails-ci.md new file mode 100644 index 00000000..473bbc8c --- /dev/null +++ b/docs/reviews/2026-09-25-maturity-review/12-guardrails-ci.md @@ -0,0 +1,325 @@ +# 가드레일·CI 성숙도 리뷰 + +> 검토일: 2026-09-25 · 기준: `main` / `4626b73` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 범위: `scripts/check-*.ts`(29개, 5.5k줄), `scripts/check-architecture.ts`(1.1k), `scripts/run-ci-gate.ts`, `scripts/generate-ci-workflow.ts`, `scripts/contracts/ci-gates.ts`, `scripts/lib/`의 CI·검사 관련 파일, `.gitea/workflows/quality-gates.yml`(460), `config/ci/gates.json`(2.9k), `config/architecture/`, `config/testing/`, `config/schemas/`, `.dependency-cruiser.json`, `eslint.config.ts`(868), `tsconfig*.json`, `package.json` 검사 스크립트. `scripts/` 전체 규모(141파일·31.7k줄)는 비용 평가에만 사용했다. 빌드·릴리스·공급망 스크립트 자체는 영역 13. +> 영역 판정(35.8): **조건부 사용 가능** — 로컬 `check:architecture`는 직접 import 위반을 실제로 막는다. 다만 이 repo의 CI는 호스트에서 꺼져 있어 머지를 막지 않고, 생성된 workflow는 release-admission 게이트를 실행하지 않는다. 릴리스 파이프라인 용도로는 12-02를 고치기 전까지 사용 보류. + +## 1. 결론 + +- **머지를 막는 장치가 없다.** Gitea 저장소 설정이 `has_actions: false`다. `main` HEAD와 PR #2의 커밋에 CI 상태가 하나도 없고, PR #2는 그대로 머지됐다. 27개 게이트는 작성자가 로컬에서 돌릴 때만 동작한다(12-01). +- **생성된 workflow가 FE-GATE-027(release-admission)을 실행하지 않는다.** 생성기가 matrix가 아닌 job에서 첫 게이트만 실행한다. 그래서 `APP_PROFILE`이 비어 로컬·demo 인증으로 빌드된 후보도 promotion까지 간다(12-02). +- **직접 import 위반은 막힌다.** worktree에서 위반 17건을 넣어 보았다. presentation→adapter 직접 import, type-only, 동적 `import()`, 다른 adapter 내부·배럴, 커널을 거친 우회, 배럴 건너뛰기가 모두 `check:architecture`에서 실패했다. 뚫린 것은 네 경로다. 경계 밖 모듈을 거친 재수출, `import.meta.glob`, 2단계 `index.ts`, cross-context-invalidation 예외다(12-03, 12-06, 12-07). +- **CI에 연결되지 않은 검사가 많다.** 테스트 14파일(architecture·release·scripts·features 최상위)과 `check:adapter-inventory` 등 검사 스크립트 10여 개는 어떤 게이트도 실행하지 않는다. 지금은 통과하지만 깨져도 알 수 없다(12-04). +- **유지 비용이 크다.** workflow YAML 460줄을 만들고 검증하는 데 6.4k줄을 쓴다. 그런데도 12-02 버그가 계약 검사 1.2k줄과 스냅샷 테스트를 그대로 통과했다. dependency-cruiser는 매번 실행되지만 0개 모듈을 검사한다(12-05, 12-10). +- 미검증: 호스트의 branch protection 설정(API가 401을 반환), 실제 Gitea runner에서 workflow가 도는지, CI 소요 시간. + +## 2. 범위와 방법 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상·커밋 | `main` / `4626b73`. 미커밋은 `CLAUDE.md`, 가이드 문서뿐 | +| 읽은 코드·설정 | 위 범위 전체. `check-architecture.ts`, `run-ci-gate.ts`, `check-ci-contract.ts`, `ci-step-result.ts`, `promotion-readiness.ts`, `generate-ci-workflow.ts` 해당부, `ci-gates.ts` 소유권 검사부, `check-design-system.ts`, `check-i18n.ts`, `realtime-boundaries.ts` 정규식부, `check-adapter-inventory.ts` 앞부분. 문서는 `docs/architecture/layers.md`, `VD-01`, `VD-05`, `docs/operations/ci-quality-gates.md` 관련 절, README 검증·CI 절 | +| 실험 | worktree(`scratchpad/12/wt`, 끝나고 삭제)에서 위반 probe 20파일을 넣었다. 그 뒤 `check-architecture.ts`(pnpm exec 대체 shim 사용), 파일별 `eslint`, `check-design-system.ts`를 실행했다. 결과는 12-03 표에 있다 | +| 실행한 명령 | 기준선 `check-architecture.ts` → PASS(373 모듈, 1159 간선, 그래프 회귀 검사 16개, 금지 fixture 9개 거부) · `depcruise --info`와 리포트 → 검사 모듈 0개 · `tsc -p tsconfig.web-worker.json --listFilesOnly` → 0파일 · `tsc -p tests/fixtures/typecheck/tsconfig.image-cdn-resolve-signal.json` → 기대대로 TS2741 · `node scripts/run-vitest.ts run tests/unit/ci-workflow-generation.test.ts tests/unit/ci-step-result.test.ts` → 414/414 통과 · CI 밖 테스트 `tests/architecture tests/release tests/scripts tests/features/{feature-installation-surface,feature-module,product-features-scale}.test.ts` → 14파일 62개 통과 · Gitea 공개 API 읽기(`/repos/…`, `/commits//status`, `/pulls/2`) | +| 확인 못 한 것 | branch protection·Actions 실행 이력(토큰 필요, 401). 전체 게이트(오케스트레이터 담당). `tests/scale`(무거움). CI 소요 시간 | +| 참고 | worktree에서 `corepack pnpm check:architecture`를 실행하면 pnpm 11의 의존성 점검이 `pnpm install`을 시도한다. purge 확인 단계에서 중단됐고 원본 `node_modules`는 바뀌지 않았다. 그래서 이후에는 pnpm 없이 실행했다 | +| 직전 리뷰 | 6.0(깨끗한 체크아웃에서 게이트 실패)은 모든 스크립트에 생성 단계를 붙여 고쳐졌다. 재발은 없다. 다만 그 결함이 main에 머지된 원인(CI 미실행)은 12-01로 남아 있다. 6.7-12(contracts→presentation/bootstrap 규칙)는 `.dependency-cruiser.json`에 추가된 것을 확인했다 | + +## 3. 확인된 강점 + +- **import 그래프가 실패 쪽으로 닫혀 있다.** 다음 경우는 모두 게이트 실패다. 해석 안 되는 import, 파싱 실패, 문자열이 아닌 `import()`·`require()`, 로컬 JS 확장자 specifier, 지원하지 않는 규칙 모양(`reachable` 등). 근거: `scripts/check-architecture.ts:462-510`, `:799-815`. 회귀 fixture 16개가 매 실행마다 검출력을 다시 확인한다(`:821` 이후). 실험에서 직접 위반 13건을 모두 잡았다. +- **음성 fixture는 "정해진 방식으로 실패"해야 통과한다.** 종료 코드와 진단 ID가 둘 다 맞아야 한다(`scripts/lib/ci-step-result.ts:37-80`). 검사기가 다른 이유로 죽으면 통과로 치지 않는다. 타입 fixture 22개, i18n·diagnostics·design-system·registry fixture가 이 방식이다. +- **workflow와 설정이 어긋나면 잡는다.** `check:ci`가 FE-GATE-010 안에서 workflow를 다시 생성해 비교한다. action은 전체 SHA로 고정한다(`scripts/contracts/ci-gates.ts` action 검사). 설치는 `--frozen-lockfile --ignore-scripts`이고, `permissions: contents: read`, `persist-credentials: false`다. +- **TypeScript `paths`를 경계로 쓰지 않는다([S4]).** 어느 tsconfig에도 `paths`가 없고 Vite alias도 없다. alias를 새로 넣으면 그래프가 unresolved로 실패한다. 경로 설정이 조용히 경계를 우회할 수 없다. +- **도구 선택 이유가 기록돼 있다.** TS 7 + ESLint 10 때문에 typescript-eslint와 jsx-a11y를 쓸 수 없다. `VD-01`에 그 이유와 교체 조건이 있다. 버전은 전부 exact pin이고 `.nvmrc`·`packageManager`도 고정돼 있다. `src`·`scripts`에 `eslint-disable`·`@ts-ignore`가 없다. + +## 4. 발견 사항 (36.3) + +### 12-01 이 repo에서 CI가 실행되지 않아 게이트가 머지를 막지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 21, 10, 26, 9 | +| 근거 | Gitea API `GET /repos/donghyeon.kang/clean-architecture-frontend-template` → `has_actions: false`, `default_branch: main`. `4626b73`(main HEAD), `38020da`·`d7fc464`(PR #2 커밋)의 `/status`가 모두 `total_count: 0`. PR #2는 `merged: true`. 문서는 required check 설정을 repo 밖 책임으로 두고(`docs/operations/ci-quality-gates.md:379-381`), 전환 전에 staging smoke가 필요하다고 한다(`:201-203`). README는 "No gate is downgraded to a warning"라고 쓴다(`README.md:176`). 추가로 push 트리거가 `develop`뿐이다(`.gitea/workflows/quality-gates.yml:5-6`). 실제 통합 브랜치는 `main`이고 `origin/develop`은 9/20에 멈춰 있다 | +| 발생 조건 | 모든 PR·push. Actions를 켜도 `main`에 직접 push하거나 머지한 결과는 트리거되지 않는다 | +| 영향 | 게이트가 깨진 상태로 main에 들어갈 수 있다. 다운스트림은 그 main을 복사한다. 실제 전례가 있다. 직전 리뷰 6.0(깨끗한 체크아웃에서 architecture·types·unit·component 전부 실패)이 main에 머지돼 있었다 | +| 심각도·우선순위 | High · P1 — 템플릿의 핵심 주장(27개 게이트가 머지를 막음)이 원본에서 실현되지 않는다. 깨진 기본값이 복제된 전례가 있다 | +| 통제·증거 | 목표 M4(required check) / 확인 M1(문서만) · E3(호스트 공개 API 관찰) | +| 확실성과 남은 가정 | Actions 비활성과 상태 0개는 직접 확인했다. branch protection은 401이라 보지 못했다. 과거에 Actions가 켜져 있었는지는 모른다 | +| 최소 개선 방향 | (1) 저장소 Actions와 runner를 켜고 merge 게이트 13개를 required check로 지정한다. (2) push 트리거에 `main`을 추가한다(`gates.json` → 재생성). 호스트 설정이 당장 어렵다면 README에 "이 repo는 CI를 실행하지 않는다, 머지 전 로컬 명령은 X"를 명시하는 것이 최소선이다 | +| 비용·부작용 | runner 1대. merge 게이트 13개가 각자 설치하므로 PR당 시간 비용이 생긴다(미측정) | +| 완료 기준 | 게이트 하나를 일부러 깨뜨린 PR이 머지 불가로 표시되고, `main` push에도 상태가 붙는다 | +| 검증 방법 | 실패 PR 1건과 통과 PR 1건의 상태 API 결과를 남긴다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 6.0의 재발 방지 조건. 6.0 증상 자체는 해결됨 | + +### 12-02 생성된 workflow가 FE-GATE-027(release-admission)을 실행하지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 21, 18, 15, 17 | +| 근거 | `config/ci/gates.json:2365-2368`: `immutable_build`는 `["FE-GATE-015","FE-GATE-027"]`를 가진다. `scripts/generate-ci-workflow.ts:200`는 matrix가 아닌 job에서 `job.gateIds[0]`만 실행한다. 결과 workflow `.gitea/workflows/quality-gates.yml:143-144`는 `ci:gate -- FE-GATE-015`만 실행하고, 파일 어디에도 `FE-GATE-027`이 없다. 계약 검사는 "소유"만 보고 "실행"은 보지 않는다(`scripts/contracts/ci-gates.ts:851-853`, `:856-875`). 스냅샷 테스트가 이 결과를 고정한다(`tests/unit/ci-workflow-generation.test.ts`, 414개 통과). `promotion-readiness.ts:23-25`는 027 없이는 RELEASE_READY가 아니라고 하지만, 이 공식은 계약 자기검사에만 쓰인다 | +| 발생 조건 | 태그나 `workflow_dispatch`로 release 이상을 실행할 때. `APP_PROFILE` 변수가 비면 `scripts/generate-runtime-config.ts:72`가 `local` 프로필(AUTH_MODE demo, loopback API)로 빌드한다 | +| 영향 | 로컬·demo 인증 후보가 promotion job까지 통과해 "검증된" 산출물로 올라간다. 이 게이트가 막으려던 경우(`scripts/check-release-admission.ts:13-24`)가 그대로 열려 있다 | +| 심각도·우선순위 | High · P1 — 릴리스 용도의 차단 항목이다. merge 게이트에는 영향이 없다. 지금은 12-01 때문에 CI 자체가 돌지 않아 실제 노출은 없다 | +| 통제·증거 | 목표 M3 / 확인 M1(계약에 명시, 실행 없음) · E2(생성 테스트 통과로 현재 출력 확인) + E1 | +| 확실성과 남은 가정 | 정적으로 확정했다. 실제 promotion 이후의 배포 단계는 repo 밖이다 | +| 최소 개선 방향 | 생성기가 non-matrix job의 `gateIds` 전부를 순서대로 실행하게 한다. 또는 `immutable_build`에 027 전용 step을 추가한다. 계약 검사에 "모든 gate id가 생성된 workflow의 run step에 나타난다"를 넣는다 | +| 비용·부작용 | 스냅샷 1개 갱신. 027은 `RELEASE_TARGET` 미선언 시 실패하므로 release 변수 설정이 필요하다 | +| 완료 기준 | workflow에 `ci:gate -- FE-GATE-027` 실행이 있고, 계약 검사가 그 줄을 지운 변형을 거부한다 | +| 검증 방법 | 생성 테스트에 "gate id 누락" 음성 변형을 추가한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 12-03 경계 규칙은 직접 간선만 본다 — 경계 밖 모듈을 거친 재수출이 통과한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 21, 2, 10 | +| 근거 | 아래 실험 표. `findArchitectureViolations`(`scripts/check-architecture.ts:707`)는 간선 하나씩만 규칙에 맞춘다. 전이 도달(`reachable`)은 지원하지 않는다(`:799-815`). presentation이 `src/features//*.ts`(하위 폴더 밖 파일), `src/contexts/**`, `src/apps/**`를 import하는 것을 막는 규칙이 없다. 그 모듈들이 `src/adapters`를 재수출하는 것을 막는 규칙도 없다. 현재 코드에서도 presentation 55개 모듈 중 45개가 adapter에 전이로 닿는다. 경로 예시: `presentation/i18n/catalog.ts → features/installed-feature-messages.ts → .generated/product-feature-index.ts → reference-feature/feature-module.ts → reference-feature/adapters/… → adapters/http/index.ts`. 이 경로는 `.dependency-cruiser.json:190`의 동결 예외를 통과한다 | +| 발생 조건 | lint가 presentation의 직접 import를 막을 때 개발자가 feature 루트·context·app 파일에 `export * from ".../adapters/…"`를 추가하는 경우 | +| 영향 | "presentation은 concrete adapter를 모른다"는 규칙이 CI 통과 상태로 깨진다. adapter 코드가 presentation 테스트와 번들에 딸려 들어간다. 템플릿 규칙이므로 다운스트림도 같은 구멍을 갖는다 | +| 심각도·우선순위 | Medium · P2 — 데이터·보안 피해로 바로 이어지지는 않는다. 경계 위반이 조용히 쌓이는 경로다 | +| 통제·증거 | 목표 M3 / 확인 M3(직접 간선만) · E3(worktree 실험) | +| 확실성과 남은 가정 | 우회 통과는 실행으로 확인했다. 현재의 전이 도달이 의도된 것인지는 동결 예외의 해소 계획(assembly를 bootstrap으로 옮김)에 달려 있다 | +| 최소 개선 방향 | 규칙 두 개를 추가한다. (a) `src/features/*/`의 하위 폴더 밖 파일·`src/contexts`·`src/apps`에서 `src/adapters`로 가는 간선을 금지한다(feature 조립 파일은 명시 목록으로). (b) presentation → `src/apps`·`src/contexts` 금지(현재 `app-router.tsx`는 목록 예외). 전이 검사를 넣고 싶다면 기존 그래프로 presentation→adapters 도달 여부만 계산하는 규칙 1개로 충분하다 | +| 비용·부작용 | 규칙 2개 + fixture 2개. 동결 예외와 겹치는 파일을 목록에 올려야 한다 | +| 완료 기준 | 아래 P4a·P4b probe가 `check:architecture`에서 실패한다 | +| 검증 방법 | `tests/fixtures/architecture/dependency-graph/cross-boundary`에 재수출 fixture를 추가한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음(직전 리뷰는 직접 import만 확인) | + +실험 결과(21절 우회 경로). 각 probe는 새 파일 하나 또는 둘이다. + +| probe | 내용 | `check:architecture` | ESLint | +|---|---|---|---| +| P1 | `presentation/pages` → `adapters/http/index.ts` | 실패(3개 규칙) | 실패 | +| P1b | 같은 경로 `import type` | 실패 | 실패 | +| P1c | 동적 `import("../../adapters/telemetry/index.ts")` | 실패 | **통과** | +| P1d | `import.meta.glob("../../adapters/telemetry/*.ts")` | **통과** | **통과** | +| P1e | feature presentation → `adapters/telemetry` | 실패 | **통과**(lint는 http·storage·auth만 금지) | +| P2 / P2b | `adapters/http` → `realtime/event-codec.ts` / `realtime/index.ts`(상대 경로) | 실패 | 통과 | +| P2c | `adapters/platform`(커널) → `http/index.ts` | 실패 | 통과 | +| P3 / P3c | bootstrap·feature adapter → adapter 내부 파일(배럴 건너뜀) | 실패 | 통과 | +| P3b | `adapters/http/internals/index.ts` 신설 후 bootstrap에서 import | **통과** | 통과 | +| P4a | feature 루트 파일이 `adapters/telemetry` 재수출 → presentation이 import | **통과** | **통과** | +| P4b | `contexts/reference-context`가 재수출 → presentation이 import | **통과** | **통과** | +| P4c | `presentation/adapters/query`가 `query-cache` 재수출 | 실패 | 통과 | +| P5 | `adapters/http`·`web-push` → `cross-context-invalidation/index.ts` | **통과** | 통과 | +| P6 / P6b | `presentation/pages` / feature presentation → `design-system/primitives/core.tsx` (`check-design-system`) | **통과** / 실패 | — | + +### 12-04 CI에 연결되지 않은 테스트와 검사가 있고, 그런 누락을 찾는 장치가 없다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 10, 21, 26 | +| 근거 | `gates.json`의 91개 명령(합성 스크립트 포함)에서 닿지 않는 것들이 있다. 테스트 디렉터리: `tests/architecture`(6), `tests/release`(3), `tests/scripts`(2), `tests/features/*.test.ts` 최상위(3), `tests/scale`(14). `test:coverage`는 `tests/platform`까지만 포함한다(`package.json` `test:coverage`). 스크립트: `check:adapter-inventory`, `check:remediation-ledger`, `check:release-coherence`, `check:topology`, `check:traffic`, `check:observability`, `check:request-fanout`, `check:app-build-input`, `check:types:fixture:image-resolve-signal`(음성 fixture) 등. 이 중 일부는 CI 밖 `verify:extreme-scale`만 실행한다(`scripts/verify-extreme-scale.ts:28-45`). `validatePackageScriptGraph`는 `check:ci`의 스크립트 그래프만 본다(`scripts/check-ci-contract.ts:58`). `CLAUDE.md:23`은 `check:adapter-inventory`를 게이트로 나열한다 | +| 발생 조건 | 이 테스트나 검사가 깨지는 변경. 예: 배포 호환 테스트 `tests/release/old-asset-reachability.test.ts`, 경계 테스트 `tests/architecture/observability-boundaries.test.ts`, INVENTORY 불일치 | +| 영향 | 로컬에서 따로 돌리지 않으면 아무도 모른다. 지금은 14파일 62개가 모두 통과한다(실행 확인). 잃는 것은 앞으로의 검출력이다 | +| 심각도·우선순위 | Medium · P2 | +| 통제·증거 | 목표 M3 / 확인 M1 · E2(현재 통과) + E1(CI 미연결) | +| 확실성과 남은 가정 | `tests/scale` 일부는 비용 때문에 의도적으로 뺐을 수 있다. 그 의도는 어디에도 적혀 있지 않다 | +| 최소 개선 방향 | (1) `tests/architecture`, `tests/release`, `tests/scripts`, `tests/features/*.test.ts`를 기존 게이트 명령(`test:unit` 또는 `test:coverage` 경로 목록)에 추가하고, `check:adapter-inventory`와 image fixture를 FE-GATE-010·003에 추가한다. (2) `check-ci-contract`에 "`tests/` 아래 테스트 파일은 어떤 게이트 명령의 경로에 속하거나 명시된 제외 목록(이유 포함)에 있어야 한다"는 검사를 추가한다 | +| 비용·부작용 | 게이트 시간 소폭 증가. 제외 목록 관리 | +| 완료 기준 | CI 밖 테스트·검사 목록이 비어 있거나, 남은 항목마다 이유가 적혀 있다 | +| 검증 방법 | 새 테스트 디렉터리를 임시로 만들면 계약 검사가 실패한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 12-05 dependency-cruiser가 0개 모듈을 검사하고 통과한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 16, 21, 24 | +| 근거 | `depcruise --info` 결과, TypeScript 트랜스파일러는 `>=2 <7`만 지원하고(설치 7.0.2) babel은 `<8`만 지원한다(설치 8). `check:architecture`가 남기는 `artifacts/quality/dependency-report.json`의 `summary.totalCruised: 0`, `modules: []`. 코드는 이 사실을 주석으로 인정한다(`scripts/check-architecture.ts:114-115`). 그런데 모듈 수가 0이어도 실패하지 않는다. 문서는 여전히 dependency-cruiser가 검사한다고 쓴다(`docs/architecture/decisions/VD-01-typescript-lint-tooling.md` 검증 절 "ESLint와 dependency-cruiser는 TS/TSX architecture fixture를 검사한다", `docs/architecture/typescript-state-and-data-flow.md:55`, `docs/architecture/frontend-platform-capability-review.md:68`) | +| 발생 조건 | 항상 | +| 영향 | 실제 규칙 적용은 자체 그래프가 한다. 그래서 지금 규칙이 빠지지는 않는다. 다만 리포트와 문서가 "표준 도구가 검사했다"는 잘못된 증거를 만든다. 자체 그래프를 걷어내거나 고장 나도 dependency-cruiser가 받쳐 줄 거라고 오해하기 쉽다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M1 · E2(실행 확인) | +| 확실성과 남은 가정 | 확정 | +| 최소 개선 방향 | 둘 중 하나. dependency-cruiser 실행을 빼고 설정 파일 이름을 규칙 파일로 바꾼다(예: `config/architecture/import-rules.json`). 아니면 `totalCruised === 0`이면 실패하게 하고 TS 7 지원 전까지는 실행을 끈다. 문서 3곳을 고친다 | +| 비용·부작용 | 파일 이름을 바꾸면 문서 참조를 갱신해야 한다 | +| 완료 기준 | 리포트나 문서에 "dependency-cruiser가 검사"라는 주장이 없거나, 실제로 모듈 수가 0보다 크다 | +| 검증 방법 | `dependency-report.json` 확인 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 12-06 `import.meta.glob`은 import로 인식되지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 21, 2 | +| 근거 | `visitSyntaxNode`(`scripts/check-architecture.ts:462-510`)는 import/export 선언, `import()`, `require()`, TS import type만 수집한다. probe P1d가 그래프와 ESLint를 모두 통과했다. `tsconfig.app.json`에 `vite/client` 타입이 있어 타입 검사도 통과한다 | +| 발생 조건 | presentation 등에서 `import.meta.glob("../../adapters/…")`를 쓰는 경우. 현재 `src`에는 사용처가 없다 | +| 영향 | 이 경로로 adapter 모듈을 번들에 끌어와도 어떤 검사도 모른다 | +| 심각도·우선순위 | Low · P3 — 실수로 쓰기보다 의도적으로 우회할 때 쓰는 형태다 | +| 통제·증거 | M0(이 경로에 대해) · E3 | +| 확실성과 남은 가정 | 확정 | +| 최소 개선 방향 | `import.meta.glob` 호출을 발견하면 parse failure로 거부한다(현재 비문자열 `import()`를 다루는 방식과 같다). 쓸 곳이 생기면 그때 패턴을 간선으로 확장한다 | +| 비용·부작용 | 10줄 내외와 fixture 1개 | +| 완료 기준 | P1d가 실패한다 | +| 검증 방법 | `dependency-graph/unresolved` fixture에 추가 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 12-07 경계 예외가 적힌 이유보다 넓고, 담당·재검토 시점이 없다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 21, 26, 5 | +| 근거 | (1) 배럴 규칙이 모든 adapter 그룹의 2단계 `index.ts`를 공개 배럴로 인정한다(`.dependency-cruiser.json:215`). 적힌 이유는 `storage/indexeddb`·`storage/opfs` 두 곳뿐이다(`docs/architecture/layers.md:64-69`). probe P3b(`http/internals/index.ts`)가 통과했다. (2) `cross-context-invalidation/index.ts` 예외는 모든 adapter에 적용된다(`.dependency-cruiser.json:202`). 그런데 `layers.md:39-44`와 규칙 주석은 "query-cache의 두 타입만, 동결됨, 새 간선은 게이트 실패"라고 쓴다. probe P5(http·web-push → cci)가 통과했다. 소유자 결정상 이것은 kernel 예외이므로 문서 쪽이 틀렸다. (3) `presentation/adapters/query`는 주석 없이 `presentation-does-not-know-adapters`에서 통째로 빠진다(`.dependency-cruiser.json:27`). (4) `pnpm-workspace.yaml:4-8`의 `minimumReleaseAgeExclude`(eslint·playwright)에 이유·만료 조건이 없다. 네 예외 모두 담당자와 재검토 시점이 없다 | +| 발생 조건 | 누군가 새 서브배럴이나 cci 간선을 추가할 때 | +| 영향 | 문서를 믿는 사람은 막힐 거라고 생각하지만 실제로는 통과한다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M1 · E3 | +| 확실성과 남은 가정 | (1)은 모든 그룹에 서브배럴을 열어 두려는 의도일 수도 있다. 그렇다면 문서만 고치면 된다 | +| 최소 개선 방향 | (1) 도착 정규식을 `^src/adapters/storage/(indexeddb|opfs)/index\.ts$`로 좁힌다. (2) 새 파일 단위 예외는 제안하지 않는다. `layers.md`와 규칙 주석을 "모든 adapter가 쓸 수 있는 kernel 예외"로 고친다. (3)·(4)에는 한 줄 이유를 단다. 예외마다 `comment`에 담당과 재검토 조건을 적는 관례를 둔다 | +| 비용·부작용 | 정규식 1줄, 문서 몇 줄 | +| 완료 기준 | P3b가 실패하거나 문서가 "모든 그룹 허용"으로 맞춰진다. `layers.md`에 "동결" 주장이 남지 않는다 | +| 검증 방법 | barrel fixture에 서브배럴 거부 케이스를 추가한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 12-08 design-system 검사기가 presentation 내부의 deep import를 보지 못한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 21, 23 | +| 근거 | `VD-05`: "제품 코드는 `presentation/design-system/index`만 import한다". 검사는 specifier 문자열에 `presentation/design-system/`이 들어 있을 때만 잡는다(`scripts/check-design-system.ts:110-115`). presentation 안의 `../design-system/primitives/core.tsx`는 이 문자열이 없어 통과한다(P6). 현재 `src/presentation/templates/page-templates.tsx:8-9`와 `src/presentation/components/ui/*.ts` 6개 파일이 이 형태로 import하고, 게이트는 PASS다. fixture는 `../../../../src/presentation/design-system/…` 모양 하나뿐이다 | +| 발생 조건 | presentation 파일에서 design-system 내부를 상대 경로로 import할 때 | +| 영향 | 공개 API를 거치지 않은 사용이 늘어나도 검사는 통과를 보고한다. `components/ui`가 의도된 facade라면 그 사실이 규칙에 없다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M2(일부 경로) · E3 | +| 확실성과 남은 가정 | `components/ui`·`templates`가 허용 대상인지는 문서에 없다 | +| 최소 개선 방향 | 이 규칙을 정규식 검사기에서 빼고 import 그래프 규칙 1개로 옮긴다. 경로 해석이 끝난 상태에서 `^src/presentation/design-system/(?!index\.ts$)`로 가는 간선을 금지하고, 허용 facade는 `pathNot`에 명시한다 | +| 비용·부작용 | 정규식 5줄을 지우고 규칙 1개를 추가한다 | +| 완료 기준 | P6이 실패하거나 허용 facade 목록이 규칙에 명시된다 | +| 검증 방법 | 그래프 fixture 1개 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 12-09 레이어 규칙 사본이 세 개이고 하나는 아무도 읽지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 23, 9, 4 | +| 근거 | `config/architecture/layers.json`은 어떤 스크립트나 테스트도 읽지 않는다(`grep` 결과는 설계 문서 2곳뿐). 내용도 낡았다. contracts·features·platform·apps·contexts가 없고, adapters가 `src/adapters` 전체를 import할 수 있다고 적혀 있다. 이는 실제 규칙(`adapters-do-not-know-other-concrete-adapters`)과 반대다. ESLint `layerPatterns`(`eslint.config.ts:9-34`, `:751-761`)와 `.dependency-cruiser.json`도 범위가 다르다. 예: feature presentation에 대해 lint는 http·storage·auth만 금지하고, 그래프는 `src/adapters` 전체를 금지한다 | +| 발생 조건 | 규칙을 바꿀 때 어느 파일이 기준인지 헷갈린다 | +| 영향 | 소유자가 문제로 보는 "갈라진 중복 복사본"이다. 지금 CI에서 강제되는 것은 그래프 쪽이므로 규칙이 빠지지는 않는다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M1 · E1 | +| 확실성과 남은 가정 | 확정 | +| 최소 개선 방향 | `layers.json`을 지운다(또는 그래프 규칙에서 생성한다). ESLint `no-restricted-imports`는 "편집기에서 빨리 보여 주는 보조"라고 주석을 달고, 기준은 `.dependency-cruiser.json` 하나로 둔다 | +| 비용·부작용 | 파일 1개 삭제, 문서 2곳 링크 수정 | +| 완료 기준 | 레이어 규칙의 기준 파일이 하나다 | +| 검증 방법 | `grep -r layers.json` | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 12-10 가드레일·CI 코드의 유지 비용이 검출력에 비해 크다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 21, 9, 4, 22, 3, 30.6 | +| 근거 | `scripts/`는 141파일·31.7k줄이고, `check-*` 29개가 5.5k줄이다. workflow 460줄을 만들고 검증하는 데 `gates.json` 2,895 + `ci-gates.ts` 1,229 + `generate-ci-workflow.ts` 498 + `package-script-graph.ts` 994(셸 토크나이저) + `ci-artifact-validator.ts` 742 = 약 6.4k줄을 쓴다. 이 층을 거쳤는데도 12-02(게이트 누락)가 통과했고, 414개 테스트가 누락된 출력을 스냅샷으로 고정했다. 정규식 검사기는 그래프가 이미 강제하는 규칙을 한 번 더 구현한다. `check-design-system.ts:102`(lucide)는 `.dependency-cruiser.json:44` `icon-vendor-is-facade-only`와 겹치고, `scripts/lib/realtime-boundaries.ts:21`(realtime import)은 `presentation-does-not-fetch-directly`와 겹친다. 정규식 쪽이 더 약하다(12-08). 반대로 자체 import 그래프(약 0.9k줄)는 TS 7에서 dependency-cruiser가 동작하지 않아(`VD-01`) 필요한 비용이고, fixture로 자기검증까지 한다 | +| 발생 조건 | 게이트를 하나 추가하거나 바꿀 때: `package.json` + `gates.json` 명령·게이트·아티팩트·스키마 + 재생성 + 스냅샷 갱신 | +| 영향 | 작성자 1인 체제에서 다운스트림 팀이 이 메타 시스템을 떠안는다(30.6). 복잡도가 검출력을 보장하지 않는다는 사례가 이미 있다(12-02) | +| 심각도·우선순위 | Medium · P2 | +| 통제·증거 | 해당 없음 · E1(규모 측정) + E2(12-02 누락이 테스트를 통과) | +| 확실성과 남은 가정 | 비용은 줄 수로 잰 대리 지표다. 실제 변경 시간은 측정하지 않았다 | +| 최소 개선 방향 | 새 시스템을 만들지 말고 줄인다. (1) import 관련 정규식 규칙(icon vendor, realtime import, design-system deep import)을 그래프 규칙으로 옮기고 정규식을 지운다. (2) workflow 계약 검사의 핵심 불변식을 "모든 게이트 id가 run step에 있다" 하나로 먼저 세운다. (3) `package-script-graph.ts`의 셸 파싱이 막는 위험(install lifecycle)이 `--ignore-scripts`와 `allowBuilds`로 이미 막혀 있는지 확인하고, 그렇다면 축소한다 | +| 비용·부작용 | 삭제 위주. 검사 범위가 줄지 않았는지 기존 음성 fixture로 확인해야 한다 | +| 완료 기준 | 같은 규칙을 두 도구가 따로 구현하는 곳이 없다. CI 메타 층에 "실행 누락" 음성 fixture가 있다 | +| 검증 방법 | 기존 음성 fixture 전체 재실행 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 12-11 검사 실패 메시지에 이유와 해결 방향이 없다 + +| 필드 | 내용 | +|---|---| +| 성격 | 개선 제안 | +| 관련 관점 | 20, 8 | +| 근거 | ESLint `no-restricted-imports` 패턴에 `message`가 없다(`eslint.config.ts:36-38`). 출력은 "`'../../adapters/http/index.ts' import is restricted from being used by a pattern`"뿐이다. 그래프는 "`Architecture violation [rule]: a -> b`"로 파일 쌍과 규칙 이름만 출력하고 줄 번호가 없다(`scripts/check-architecture.ts:204`). 규칙 대부분에 `comment`(이유)가 이미 있지만 출력하지 않는다 | +| 발생 조건 | 위반이 났을 때 | +| 영향 | 왜 막혔고 어디로 가야 하는지(배럴, port, bootstrap)를 `.dependency-cruiser.json`을 열어 찾아야 한다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | — · E3(probe 출력) | +| 확실성과 남은 가정 | 확정 | +| 최소 개선 방향 | 위반 출력에 규칙 `comment` 첫 문장과 specifier를 붙인다. ESLint 패턴을 `{ group, message }` 형태로 바꾼다 | +| 비용·부작용 | 수십 줄 | +| 완료 기준 | probe P1 출력만 보고 수정 위치를 알 수 있다 | +| 검증 방법 | 금지 fixture 출력 확인 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 12-12 unused 변수·import를 아무 도구도 잡지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 16, 9, 21 | +| 근거 | `VD-01` 결정 3은 "unused 진단은 `tsc`가 소유한다"며 TS 파일의 `no-unused-vars`를 끈다(`eslint.config.ts:465`, `:484`, `:507`). 그런데 `tsconfig.base.json`에 `noUnusedLocals`·`noUnusedParameters`가 없다 | +| 발생 조건 | 쓰지 않는 import·변수가 생길 때 | +| 영향 | 죽은 import가 남는다. 경계 그래프는 import가 쓰이는지 여부와 상관없이 간선으로 보므로 경계 판정에는 영향이 없다. 가독성과 삭제 용이성(27)이 약해진다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M0(결정과 구현 불일치) · E1 | +| 확실성과 남은 가정 | 옵션을 켰을 때 기존 코드에서 몇 건이 나오는지는 세지 않았다 | +| 최소 개선 방향 | `tsconfig.base.json`에 `noUnusedLocals: true`(필요하면 `noUnusedParameters`도)를 켜고, 나온 건을 정리한다 | +| 비용·부작용 | 한 번 정리하는 비용 | +| 완료 기준 | 결정 문서와 설정이 일치한다 | +| 검증 방법 | `check:types` | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +## 5. 28개 관점 판정 (36.2) + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +|---|---|---|---|---|---| +| 1 | 코드 성숙도 | 다른 영역 — 도메인 규칙 영역 | — | — | 적용 제외 | +| 2 | 구조적 성숙도 | 적용 — import 경계 강제 | M3 / M3(직접 간선) | E3 probe 20개 | 부분 충족 — 재수출·glob 우회(12-03, 12-06). `paths` 오용 없음 | +| 3 | 변경 용이성 | 적용 — 게이트 추가 비용 | M2 / M2 | E1 | 부분 충족 — 게이트 하나에 4곳 수정(12-10) | +| 4 | 인지 부하 | 적용 — 검사 코드 규모 | — | E1 | 부분 충족 — 31.7k줄, 규칙 사본 3개(12-09, 12-10) | +| 5 | 위험 가시성 | 부분 — 예외 범위 표시 | M1 / M1 | E3 | 부분 충족 — 예외가 문서보다 넓음(12-07) | +| 6 | 실패 성숙도 | 다른 영역 — 런타임 실패 처리 | — | — | 적용 제외 | +| 7 | 운영 성숙도 | 다른 영역 — 13(릴리스·운영) | — | — | 적용 제외 | +| 8 | 디버깅 가능성 | 적용 — 게이트 로그 | M2 / M2 | E3 | 부분 충족 — 로그는 artifact로 남지만 위반 메시지에 줄·이유가 없음(12-11) | +| 9 | 유지보수 성숙도 | 적용 | — | E1·E2 | 부분 충족 — 메타 CI 비용, 문서와 도구 불일치(12-05, 12-10) | +| 10 | 테스트 성숙도 | 적용 — 검사기 자기검증·CI 연결 | M3 / M2 | E2 | 부분 충족 — 음성 fixture는 강함. CI 밖 테스트 14파일(12-04) | +| 11 | 데이터 성숙도 | 적용 제외 — 이 영역에 데이터 없음 | — | — | 적용 제외 | +| 12 | 동시성 성숙도 | 적용 제외 | — | — | 적용 제외 | +| 13 | 확장성 | 다른 영역 — extreme-scale 문서·영역 | — | — | 적용 제외 | +| 14 | 성능 성숙도 | 부분 — CI 시간 비용 | — | 미확인 | 미검증 — CI 소요 시간 미측정 | +| 15 | 보안 성숙도 | 부분 — CI 권한·릴리스 입장 | M3 / M2 | E1 | 부분 충족 — `contents: read`, SHA 고정. release-admission 미실행(12-02) | +| 16 | 의존성 성숙도 | 적용 — lint·타입 도구 | M2 / M2 | E2 | 부분 충족 — exact pin·frozen lockfile·ADR 있음. depcruise 무동작(12-05), unused 진단 공백(12-12), 예외 이유 없음(12-07) | +| 17 | API / Contract | 부분 — gates.json 계약 | M3 / M2 | E2 | 부분 충족 — 소유와 실행을 구분하지 않음(12-02) | +| 18 | 배포 성숙도 | 다른 영역 — 13. 단 12-02가 영향 | — | E1 | 적용 제외(12-02 참조) | +| 19 | 설정 성숙도 | 다른 영역 — 13·19 | — | — | 적용 제외 | +| 20 | 개발자 경험 | 적용 — 실패 메시지 | M2 / M1 | E3 | 부분 충족 — 12-11 | +| 21 | Guardrail 성숙도 | 핵심 | M4(required) / M1(머지), M3(로컬 import) | E3 | 미충족 — 머지 차단 없음(12-01), 게이트 누락(12-02). 로컬 import 검사는 강함 | +| 22 | 추상화 성숙도 | 적용 — CI 메타 층 | — | E2 | 부분 충족 — 12-10 | +| 23 | 일관성 | 적용 — 규칙 사본 | M2 / M1 | E1 | 부분 충족 — 12-09, 12-08 | +| 24 | 네이밍 / 의미 | 부분 — `.dependency-cruiser.json`이 실제 강제 도구를 가림 | — | E2 | 부분 충족 — 12-05 | +| 25 | 조직 확장성 | 구조적 준비만 평가(1인 관리) | — | E1 | 미검증 — `gates.json` 단일 2.9k줄 파일이 충돌 지점이 될 수 있음 | +| 26 | Ownership | 적용 — 예외·게이트 담당 | M1 / M1 | E1 | 부분 충족 — risk-coverage에는 owner가 있음. 경계 예외에는 담당·재검토가 없음(12-07) | +| 27 | 삭제 가능성 | 다른 영역 — FE-GATE-020 removability | — | — | 적용 제외 | +| 28 | 회복 가능성 | 적용 제외 | — | — | 적용 제외 | + +## 6. 미검증 목록 + +- **branch protection·required check 설정.** Gitea API가 401을 반환했다. 확인하려면 저장소 관리자 토큰으로 `/branch_protections`를 조회한다. +- **생성된 workflow가 실제 Gitea runner에서 도는지.** Actions가 꺼져 있어 실행 이력이 없다. patched artifact action, `gitea.run_attempt`, `RUNNER_IMAGE_DIGEST` 등이 대상이다. 문서(`ci-quality-gates.md:201`)가 요구하는 staging smoke 1회가 필요하다. +- **CI 소요 시간과 비용.** merge 게이트 13개가 각자 설치하고 빌드한다. 1회 실행 기록이 있어야 판단할 수 있다. +- **`tests/scale` 14파일의 현재 상태.** 무거워서 실행하지 않았다. +- **전체 게이트.** `lint`, `check:types`, `test:*`는 오케스트레이터가 실행한다. 이 문서는 `check-architecture.ts` 단독 실행과 대상 테스트 파일 실행 결과만 사용했다. +- **12-12에서 `noUnusedLocals`를 켰을 때 기존 코드의 위반 수.** diff --git a/docs/reviews/2026-09-25-maturity-review/13-build-release-supply-chain.md b/docs/reviews/2026-09-25-maturity-review/13-build-release-supply-chain.md new file mode 100644 index 00000000..c1b7fbc6 --- /dev/null +++ b/docs/reviews/2026-09-25-maturity-review/13-build-release-supply-chain.md @@ -0,0 +1,399 @@ +# 빌드·릴리스·배포·설정·공급망·보안 설정 성숙도 리뷰 + +> 검토일: 2026-09-25 · 기준: `main` / `4626b73` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 범위: 빌드·릴리스·공급망·보안·호스팅 스크립트(`scripts/build-frontend.ts`, `scripts/generate-*`, `scripts/verify-*`, `scripts/security-scan.ts`, `scripts/check-{browser-security,bundle,release-admission,compatibility}.ts`, `scripts/drill-runbook.ts`, 승격·provider 관련 `scripts/lib/*` — 약 8.8k줄), `vite.config.ts`, `config/{release,hosting,runtime,security,compatibility,runbooks}/`(약 7.5k줄, 대부분 `dependency-baseline.json`), `package.json`, `pnpm-lock.yaml`, `pnpm-workspace.yaml`, `.npmrc`, `.nvmrc`, `public/`, `.env.example`, `index.html`, 문서 `docs/security/*`, `docs/operations/*`, `docs/runbooks/*`, `docs/architecture/static-delivery.md`(약 3.1k줄). 릴리스 흐름을 따라가기 위해 `.gitea/workflows/quality-gates.yml`과 `config/ci/gates.json`의 해당 job도 읽었다. +> 영역 판정(35.8): **조건부 사용 가능** — 빌드, 런타임 설정 스키마, 로컬 릴리스 증거 생성은 그대로 써도 된다. 이 repo의 CI를 운영 승격·롤백 판단에 그대로 믿고 쓰는 것은 13-01, 13-03, 13-04, 13-05를 고치거나 사용 프로젝트가 보완하기 전까지 보류한다. + +## 1. 결론 + +- **운영 환경 승인 게이트(FE-GATE-027)가 등록만 되어 있고 실행되지 않는다(13-01).** CI 생성기가 비-matrix job에서 첫 번째 gate만 실행한다. 원장은 이 항목(OPS-02)을 `FIXED`로 적고 있다. 그래서 repo 변수 `APP_PROFILE` 하나가 잘못되면 다른 환경용 설정을 담은 산출물이 그대로 "승격"된다. +- **검증한 산출물과 배포 산출물의 연결은 immutable_build → provider → promotion 구간에서만 강하다.** 운영 단계 runbook·롤백 drill은 새 checkout에서 local 프로필로 다시 빌드한 결과를 보고, 일부 판정은 상수 `true`다. build 없이 돌려도 롤백 drill이 PASS한다(13-03). 이전 release를 재검증하는 도구는 provider 증거 유효기간 2시간 때문에 오래된 release를 거절한다(13-04). hosting 헤더 게이트는 배포 전에 돌고, `HOSTING_BASE_URL`이 없으면 자기 선언 사본과 비교해 PASS한다(13-05). +- **배포 즉시 장애로 이어지는 결함 1건:** `dist/config.json`, `dist/release-manifest.json`이 mode `0600`으로 만들어지고 release tar에 그대로 들어간다. 웹 서버가 파일 소유자와 다른 사용자로 돌면 부트가 403으로 실패한다(13-02). +- **번들 비밀값 경로 1건:** `import.meta.env` 전체 객체 참조 때문에 코드가 쓰지 않는 `VITE_*` 빌드 환경변수까지 공개 번들에 들어간다. `sk_live_…` 형태 값을 넣어 빌드해도 secret scan은 PASS였다(13-06). +- 런타임 설정은 빌드와 브라우저가 같은 zod 스키마를 쓰고, demo 인증·비 HTTPS endpoint를 staging/production에서 거부한다. lockfile 무결성, CI 설치 스크립트 차단, action SHA 고정도 실제로 걸려 있다. 이 부분은 강점이다. +- 미검증: 실제 호스팅 provider(헤더, 포인터 전환, 이전 자산 보존), Gitea에서의 workflow 전체 실행, 외부 vulnerability·provenance provider, 운영 CSP 아래 브라우저 동작. + +## 2. 범위와 방법 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 | `clean-architecture-frontend-template`, 영역 13 | +| 커밋·상태 | `main` / `4626b73`. 미커밋은 `CLAUDE.md`, 가이드 문서뿐 | +| 지원 구성 | 정적 호스팅 SPA. 불변 release + active pointer(문서상). Service Worker·realtime·web worker는 기본 `null`/`NOT_SELECTED`(`src/features/installed-runtime-capabilities.ts:35-41`) | +| 규모·운영 목표 | 없음(전제). provider 복구 목표는 `TBD`(`docs/runbooks/FE-RB-005.md`) | +| 읽은 코드·설정 | 범위 표의 스크립트 전체, `src/contracts/{deployment-admission,release-artifacts,env,telemetry}.ts`, `src/bootstrap/runtime-config-schema.ts`, CI workflow·`config/ci/gates.json`의 job/gate/command 정의, `scripts/generate-ci-workflow.ts` 렌더링 부분 | +| 읽은 문서(주장) | `docs/security/supply-chain.md`, `browser-boundary.md`, `docs/operations/{release-cache-rollback,ci-quality-gates,performance-evidence}.md`, `docs/runbooks/FE-RB-00{1..5}.md`, `docs/architecture/static-delivery.md`, README 설정·릴리스 절 | +| 실행한 테스트 | worktree에서 `node scripts/run-vitest.ts run tests/unit/{deployment-admission,hosting-probe,runbook-contract,promotion-readiness,build-environment}.test.ts tests/release tests/platform/release tests/runtime-schema/runtime-config.test.ts` → **12 files, 120 tests 통과** | +| 실험(모두 `scratchpad/13/wt` 분리 worktree) | ① build 없이 `drill-runbook.ts FE-RB-001..005` → 001·003·004·005 PASS, 002만 FAIL ② `APP_PROFILE` 없이 build → `APP_ENV=local, AUTH_MODE=demo, API=http://localhost:8080/` ③ `APP_PROFILE=production` build 후 `RELEASE_TARGET=production/staging/local/""`로 admission → production만 ADMITTED ④ dist와 CI와 같은 tar 옵션으로 만든 archive의 권한 목록 ⑤ `generate-supply-chain.ts` → LOCAL PASS(561개), `promotion=FAIL_UNVERIFIED` ⑥ `check-bundle.ts` → 초기 JS 196,623 / 204,800 gzip bytes ⑦ 참조하지 않는 `VITE_*` 변수·가짜 토큰을 넣고 build + `security-scan.ts` ⑧ `VITE_ROUTER_BASE_PATH=/app/` build ⑨ strict 설정 스키마에 키 추가 ⑩ scratch 폴더에서 pnpm 11의 `.npmrc` `engine-strict` 적용 여부 | +| 확인 못 한 것 | 실제 호스팅·CDN(provider 미선정), Gitea workflow 실행, `test:system`·외부 provider(bwrap/systemd 필요), e2e·lab performance(Playwright), SW `ACTIVE` 2-pass build, 여러 runner 사이 재현성 | +| 이전 리뷰와 비교 | 직전 리뷰(`2026-09-24-src-full-review.md`)는 `src/`만 봤고 이 영역은 범위 밖이었다(`:825-826`). 관련 항목만 아래 2.1에 적는다 | + +### 2.1 직전 리뷰 관련 항목 재확인 + +| 직전 ID | 현재 상태 | 근거 | +|---|---|---| +| 6.0 깨끗한 체크아웃에서 생성 파일 없음 | 해결 | `package.json:12-13`, `:18` 등 `dev`·`build`·`check:*`가 `generate-product-feature-index.ts`를 먼저 실행. worktree 새 체크아웃에서 build 성공 | +| 6.9-1, 6.9-9 reload 가드 | 이 영역 밖(다른 영역) | `src/platform/release/release-mismatch-recovery.ts:7-12`에 세션·TTL 기반 단일 guard가 보임. 상세 판정은 해당 영역에 맡긴다 | + +## 3. 확인된 강점 + +1. **런타임 설정 스키마가 한 벌이다.** 빌드 단계(`scripts/generate-runtime-config.ts`)와 브라우저(`src/bootstrap/runtime-config-schema.ts:19`)가 같은 `runtimeConfigV2ArtifactSchema`(`src/contracts/release-artifacts.ts:163-171`)를 쓴다. `.strict()`라 모르는 키(비밀값 이름 포함)는 거부된다. staging/production에서 demo 인증(`:103-108`)과 비 HTTPS endpoint(`:13-20`)를 거부한다. 배포 시 덮어쓸 수 있는 값은 `API_BASE_URL`, `TELEMETRY_ENDPOINT` 두 개로 제한된다(`scripts/generate-runtime-config.ts:32-35`). 실험 ③에서 production 산출물을 staging·local로 승인하려 하면 거부됐다. +2. **immutable 후보의 식별값 연결이 촘촘하다.** immutable_build가 dist와 증거를 결정적 tar(`.gitea/workflows/quality-gates.yml:149`)로 묶고, archive SHA-256을 job output으로 넘긴다. provider job과 promotion은 그 digest, run id, nonce, 서명 키 fingerprint를 다시 확인한다(`scripts/lib/promotion-stager.ts:83-205`). CI의 `VITE_COMMIT_SHA`는 checkout HEAD와 같아야 한다(`scripts/lib/build-environment.ts:64-85`, `scripts/run-ci-gate.ts:67-99`). +3. **설치 경계가 실제로 막혀 있다.** 모든 job이 `pnpm install --frozen-lockfile --ignore-scripts`(`quality-gates.yml:63-66` 외)를 쓴다. lockfile 561행 모두 sha512 integrity가 있고 tarball/git 의존성은 없다. action은 전부 40자 commit SHA로 고정, `permissions: contents: read`, `persist-credentials: false`(`quality-gates.yml:23-24`, `:57-59`). 빌드 스크립트 허용은 `esbuild`, `msw` 두 개뿐이다(`pnpm-workspace.yaml:1-3`). +4. **캐시 정책이 선언되고 모델로 검증된다.** HTML `no-cache`, config·manifest `no-store`, 해시 자산 `immutable`(`config/hosting/cache-policy.json`), 공개 source map 금지(`vite.config.ts:32`, `scripts/check-browser-security.ts:35-45`). 새 release 활성화 뒤에도 이전 해시 자산이 남아야 한다는 규칙을 in-memory 호스팅 모델로 테스트한다(`tests/release/old-asset-reachability.test.ts:6-43`). SW 선택이 없으면 dist에 SW가 없어야 한다는 검사도 있다(`scripts/verify-hosting-headers.ts:188-193`). +5. **release 일관성 검사가 넓다.** `scripts/verify-release.ts:115-191`이 release manifest ↔ runtime config ↔ Vite manifest hash ↔ route chunk 파일 존재 ↔ build manifest를 모두 대조한다. 같은 체크아웃 2회 빌드 digest 비교(`scripts/verify-reproducible-build.ts:42-56`)도 있다. +6. **admission 규칙 자체는 잘 설계되어 있다.** placeholder build id, loopback·사설·CGNAT·IPv6 ULA 호스트, telemetry endpoint 누락을 모두 거부한다(`src/contracts/deployment-admission.ts:64-191`, 테스트 `tests/unit/deployment-admission.test.ts`). 문제는 이 규칙이 CI에서 실행되지 않는다는 점이다(13-01). + +## 4. 발견 사항 (36.3) + +### 13-01 운영 환경 승인 게이트(FE-GATE-027)가 CI에서 실행되지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 18, 19, 21, 26 (+30.1) | +| 근거 | `config/ci/gates.json:2357-2368` immutable_build의 gateIds는 `FE-GATE-015`, `FE-GATE-027` 두 개다. 그러나 `scripts/generate-ci-workflow.ts:200`은 비-matrix job에서 `job.gateIds[0]`만 렌더링한다. 결과 workflow(`.gitea/workflows/quality-gates.yml:143-144`)는 `ci:gate -- FE-GATE-015`만 실행한다. 다른 job에도 027은 없다. `scripts/run-ci-gate.ts`는 호출당 gate 하나만 돈다. 승인 기록 `artifacts/release/deployment-admission.json`은 후보 archive 멤버(`quality-gates.yml:149-196`)에도, promotion 검증에도 없다. `scripts/lib/promotion-readiness.ts:18-26`의 RELEASE_READY 공식에는 027이 있지만 이 함수는 `check-ci-contract.ts`의 자기 검사에서만 쓰인다. 원장 `docs/operations/adapter-remediation-ledger.md:482`는 OPS-02를 `FIXED`로 적는다. 실험 ②: `APP_PROFILE` 없이 `build` → `dist/config.json`이 `APP_ENV=local, AUTH_MODE=demo, API_BASE_URL=http://localhost:8080/`(기본값 `scripts/generate-runtime-config.ts:72`) | +| 발생 조건 | tag push나 release dispatch 때 repo 변수 `vars.APP_PROFILE`(`quality-gates.yml:130`)이 의도한 대상과 다를 때. 변수가 환경별이 아니라 repo 단위 하나라서 staging 릴리스 뒤 값을 되돌리지 않으면 바로 발생한다. 빈 값이면 빌드가 실패하므로 막힌다 | +| 영향 | 다른 환경의 API·telemetry endpoint나 인증 모드를 담은 산출물이 "승격" 상태가 된다. staging endpoint는 조용히 동작할 수도 있다(운영 사용자 요청이 staging 백엔드로 감). local 프로필이면 demo 인증 + localhost API로 전면 장애. 서버 인가 경계는 영향 없음 | +| 심각도·우선순위 | Medium · P1 — 운영자 설정 실수 한 번이면 발생하고, 막으려고 만든 게이트가 원장에 해결로 적혀 있어 아무도 다시 보지 않는다. CI를 복사한 모든 사용 프로젝트에 같은 빈칸이 복제된다 | +| 통제·증거 | 규칙 M2(구현·단위 테스트) / CI 강제 M0 · E1(생성기·workflow 정적 확인) + E3(로컬 build·admission 실험) | +| 확실성과 남은 가정 | 생성기 코드와 생성된 workflow를 직접 확인했다. Gitea에서 실행하지는 않았다 | +| 최소 개선 방향 | 생성기가 비-matrix job의 gateIds를 모두 순서대로 실행하게 한다(또는 FE-GATE-015 명령 목록 끝에 `check-release-admission`을 넣는다). 승인 기록을 archive 멤버와 promotion 재검증에 포함한다. `APP_PROFILE`과 `RELEASE_TARGET`이 다르면 실패시킨다. `docs/operations/ci-quality-gates.md:293-305` 변수 목록에 두 변수를 추가한다 | +| 비용·부작용 | 작다. archive 멤버를 늘리면 archive 스키마·verifier 목록도 바뀐다 | +| 완료 기준 | `APP_PROFILE=staging`, `RELEASE_TARGET=production`인 release 실행에서 immutable_build가 실패한다. 생성된 workflow에 027 실행이 보인다 | +| 검증 방법 | `check:ci`에 "job이 소유한 gate는 workflow에서 실행된다" 검사와 negative fixture 추가. worktree에서 `APP_PROFILE=staging` build 후 `RELEASE_TARGET=production node scripts/check-release-admission.ts`가 실패하는지 확인 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음(범위 밖) | + +### 13-02 공개 dist 파일 3개가 mode 0600으로 만들어져 웹 서버가 읽지 못할 수 있다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 18, 28 (+30.1) | +| 근거 | `scripts/lib/validated-json-artifact.ts:86-92`가 임시 파일을 `0o600`으로 열고 rename한다. `scripts/generate-build-manifest.ts:124-137`이 이 writer로 `dist/config.json`, `dist/release-manifest.json`, `dist/runtime-config.schema.json`을 쓴다. 실험 ④: 다른 dist 파일은 `-rw-rw-r--`, 이 세 파일만 `-rw-------`. CI와 같은 옵션(`tar … --owner=0 --group=0`, `quality-gates.yml:149`)으로 묶으면 `-rw------- 0/0 dist/config.json`으로 권한이 보존된다 | +| 발생 조건 | dist나 promoted archive를 파일 소유자와 다른 OS 사용자로 도는 웹 서버에 올릴 때. 예: Docker `COPY dist /usr/share/nginx/html`(nginx worker 사용자), root로 풀고 Apache·nginx로 서빙. 객체 스토리지 업로드처럼 파일 권한을 무시하는 호스팅은 영향 없음 | +| 영향 | `/config.json`, `/release-manifest.json`이 403 → 모든 부트가 `BOOT_CONFIG_FAILURE`(FE-RB-001). 검증을 모두 통과한 바로 그 산출물이 실패한다 | +| 심각도·우선순위 | Medium · P2 — 첫 배포에서 바로 드러나고 수정이 쉽다. 호스팅이 정해지지 않아 영향받는 사용 프로젝트 비율은 알 수 없다 | +| 통제·증거 | M0(공개 파일 권한 규칙 없음) · E3(로컬 build·tar 실험) | +| 확실성과 남은 가정 | 권한은 직접 확인했다. 실제 nginx 컨테이너에서 403을 재현하지는 않았다 | +| 최소 개선 방향 | dist 공개 파일은 일반 writer(0644)로 쓰거나 build 마지막에 권한을 맞춘다. `artifacts/` 증거 파일만 0600을 유지한다 | +| 비용·부작용 | 한 줄 수준. private 증거 규칙과 섞이지 않게 writer를 나눈다 | +| 완료 기준 | build 후 `find dist -type f ! -perm -o=r` 결과가 비어 있다 | +| 검증 방법 | `verify-release.ts`에 권한 검사 추가, 또는 build 테스트에서 위 명령 확인 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 13-03 운영 단계 runbook·롤백 게이트가 이름과 다른 것을 검사한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 28, 10, 18, 21, 24 | +| 근거 | production_gate(`quality-gates.yml:369-397`)는 새 checkout, frozen install, `ci:gate`만 한다. 후보·승격 archive를 받지 않고 `APP_PROFILE`도 없어 local 프로필로 다시 빌드한다. FE-GATE-016과 FE-GATE-025는 같은 명령(`build` + `drill:runbook -- FE-RB-005`)이다(`config/ci/gates.json` gates). `scripts/drill-runbook.ts:66-71`은 `dist/`가 없으면 `public/`의 placeholder를 읽는다. 상수 판정: `:199` `triggerAsserted: true`, `:202` "failure rate at baseline" `true`, `:241` "product flow unaffected" `true`, `:271` rollback `triggerAsserted: true`, `:276` "critical smoke" `true`. `:118-130`은 `injectedMountFailure = true` 상수라 negative fixture가 항상 통과하고, "product root mount"와 "no repeated boot error"는 같은 스키마 파싱 결과 하나다. 실험 ①: build 없이 FE-RB-005가 PASS, 기록은 `releaseId: "local-release"`, "critical smoke" `passed: true` | +| 발생 조건 | 항상. production dispatch마다 이 게이트가 돈다 | +| 영향 | `PROD_PROMOTION_READY`가 "승격한 release를 되돌릴 수 있다"가 아니라 "몇 개 함수가 기대값을 돌려준다"를 뜻한다. PASS 기록이 운영 준비 증거로 남아 사용 프로젝트가 롤백 훈련을 했다고 믿게 된다 | +| 심각도·우선순위 | Medium · P2 — 실제 롤백을 막지는 않는다. stdout에 "provider verification still required"가 찍혀 완전히 숨기지는 않는다. 그래도 증거 기록은 PASS다 | +| 통제·증거 | M1(runbook 문서) · E3(build 없는 drill 실행) | +| 확실성과 남은 가정 | 직접 실행해 확인했다 | +| 최소 개선 방향 | 상수 `true`를 없애고 측정하지 못한 항목은 `UNVERIFIED`로 기록한다. `providerVerificationRequired`가 참이면 전체 결과를 `PASS`가 아닌 별도 상태로 둔다. `public/` fallback을 없앤다. drill이 승격 archive와 이전 release archive 경로를 입력으로 받게 한다. 016/025 중복을 정리한다. 이름을 "runbook 논리 검사"처럼 실제 범위에 맞춘다 | +| 비용·부작용 | 중간. 증거 스키마와 promotion 공식이 바뀐다 | +| 완료 기준 | dist 없이 FE-RB-005가 실패한다. 기록에 상수 판정이 없다. production_gate가 승격 archive를 내려받아 검사한다 | +| 검증 방법 | drill 단위 테스트에 "build 없음 → FAIL", "provider 미검증 → PASS 아님" 케이스 추가 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 13-04 이전 release를 재검증할 수단이 없어 문서의 롤백 절차를 그대로 실행할 수 없다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 28, 18, 16 | +| 근거 | provider 증거 유효기간 상한이 2시간이다(`scripts/lib/provider-evidence.ts:12`). 재검증 때 `expires <= now`면 만료로 실패한다(`:485`). `scripts/verify-exact-promotion-bundle.ts:58-73`은 `nowEpochMs`를 넘기지 않아 현재 시각으로 검사한다. 문서는 모든 하위 소비자가 archive와 서명 증거를 다시 검증해야 한다고 한다(`docs/security/supply-chain.md:257-260`). 롤백 runbook은 이전 불변 release의 tuple을 검증하라고 하고(`docs/runbooks/FE-RB-005.md`), 옛 커밋 재빌드는 금지한다(`docs/operations/release-cache-rollback.md:9-13`). drill의 롤백 검증 함수는 경로를 코드 옵션으로만 받고 CLI 인자가 없다(`scripts/drill-runbook.ts:292-318`, `:320-331`) | +| 발생 조건 | 승격 후 2시간이 지난 release를 배포하거나 그 release로 롤백할 때(다음 날 배포, 지난주 release로 롤백 등) | +| 영향 | 문서가 요구하는 "배포 전 재검증"을 repo 도구로 통과할 수 없다. 사고 중에는 검증을 건너뛰거나 롤백이 늦어진다. 신선도 검사는 새 승격에는 맞지만 보관된 release의 재확인에는 맞지 않는다 | +| 심각도·우선순위 | Medium · P2 — 롤백 자체는 provider에서 포인터를 바꾸면 되지만, 문서가 정한 안전 확인이 불가능하다 | +| 통제·증거 | M0(보관 release 재검증 경로 없음) · E1 | +| 확실성과 남은 가정 | 코드로 확인했다. 실제 서명된 bundle로 실행하지는 않았다(provider 키 없음) | +| 최소 개선 방향 | `verify:promotion`에 보관 모드를 둔다. 서명·digest·멤버 검사는 유지하고, 신선도는 "승격 시점 기록(`promotion-verification.json`의 `verifiedAt`)이 당시 유효 창 안이었는가"로 바꾼다. drill에 archive 경로 인자를 추가한다. 문서에 롤백 시 실행할 명령을 적는다 | +| 비용·부작용 | 중간. 보관 모드가 재사용 공격 방어를 약하게 만들지 않게, 새 승격에는 쓰지 못하도록 분리해야 한다 | +| 완료 기준 | 3시간 전에 승격된 fixture bundle이 보관 모드에서 PASS, 변조 bundle은 FAIL | +| 검증 방법 | `nowEpochMs`를 주입한 단위 테스트 2개 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 13-05 hosting 헤더 게이트가 배포 전에 돌고, 배포·전환·자산 보존 단계는 repo에 없다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 18, 15, 21, 28 | +| 근거 | `HOSTING_BASE_URL`이 없으면 `scripts/verify-hosting-headers.ts:133-139`가 선언을 그 사본인 `config/hosting/response-headers.fixture.json`과 비교하고 exit 0으로 끝난다(`:205`는 `providerVerificationRequired`만 표시). `mode: "live"`를 요구하는 소비자가 없다(grep). 그런데 문서는 운영 승격에 live가 필요하다고 한다(`docs/operations/release-cache-rollback.md:29-33`). FE-GATE-019는 release_gate(`quality-gates.yml:80-118`)에서 immutable_build·promotion보다 먼저 돌고, workflow에는 배포 job이 없다. 그래서 live 모드는 이전 배포를 새 로컬 빌드의 첫 `.js` 이름(`verify-hosting-headers.ts:76-85`)으로 찌른다. 확인 경로는 `/`, `/config.json`, `/release-manifest.json`, JS 1개뿐이다. deep link, 없는 자산의 404, CSS는 보지 않는다. `docs/architecture/static-delivery.md:15-33`은 CI가 업로드·도달성 확인·포인터 전환·smoke를 한다고 그리지만 workflow에는 없다. 이전 해시 자산 보존 기간(rolling window)은 테스트 모델에만 있고(`tests/release/release-fixture.ts:91`, `:132`) 운영 문서에 최소 기간이 없다 | +| 발생 조건 | `HOSTING_BASE_URL`을 설정하지 않았거나, 설정했더라도 새 release가 아직 배포되지 않은 모든 release 실행 | +| 영향 | CSP·HSTS·cache-control 오설정이나 SPA fallback이 없는 호스팅이 게이트를 통과한다. live 모드는 새 release를 보지 못하고, 첫 JS 이름이 바뀌면 404로 실패한다. 사용 프로젝트는 배포·smoke가 이 repo에 있다고 오해할 수 있다. 이전 자산 삭제 시점이 provider 구현마다 달라진다(오래 열린 탭은 reload-once 복구에 의존) | +| 심각도·우선순위 | Medium · P2 — 게이트가 거짓 PASS를 내지만, 실제 배포 경로가 repo 밖이라 피해는 사용 프로젝트 구현에 달려 있다 | +| 통제·증거 | 헤더 선언 M1, fixture 비교 M3(자기 사본), 배포 후 확인 M0 · E1 | +| 확실성과 남은 가정 | workflow 순서와 코드로 확인했다. live 모드는 대상 호스트가 없어 실행하지 않았다 | +| 최소 개선 방향 | fixture 모드 결과를 PASS가 아닌 `UNVERIFIED`로 바꾸고 promotion이 live를 요구하게 한다. 헤더 검사를 배포 후 단계(별도 post-deploy job 또는 문서화된 provider 단계)로 옮기고 승격 release의 자산 이름으로 확인한다. deep link, 없는 자산(404이며 `text/html`이 아님), CSS를 추가한다. 문서에 "업로드·포인터 전환·전환 후 smoke는 사용 프로젝트 provider adapter 책임"과 이전 자산 최소 보존 기간을 적는다 | +| 비용·부작용 | 중간. post-deploy 단계는 호스팅 선택 뒤에만 완성된다 | +| 완료 기준 | `HOSTING_BASE_URL` 없이 FE-GATE-019가 PASS하지 않는다. live 확인이 승격 release의 해시 자산을 요청한다 | +| 검증 방법 | 로컬 정적 서버에 헤더를 일부러 빼고 live 모드 실행 → 실패 확인 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 13-06 쓰지 않는 `VITE_*` 빌드 변수까지 공개 번들에 들어가고, secret scan은 이를 잡지 못한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 15, 16, 14 | +| 근거 | `src/contracts/env.ts:123`(기본 인자 `import.meta.env`)과 `src/features/installed-product-manifest.ts:24-28`(`import.meta`를 캐스팅해 `.env` 전체 접근)이 env 객체 전체를 참조한다. Vite는 이 경우 모든 `VITE_*` 값을 객체 리터럴로 넣는다. 실험 ⑦: `VITE_PROBE_UNREFERENCED=probe-value-13`으로 build → `index-*.js`, `design-system-*.js`에 문자열이 있다. `VITE_PAYMENT_KEY=sk_live_…`, `VITE_SENTRY_AUTH_TOKEN=sntrys_…`로 build → 둘 다 번들에 있고 `node scripts/security-scan.ts` → "PASS (1355 files)". 탐지 규칙은 4개(PEM RSA/EC/PKCS8, `AKIA…`, `gh?_…`, `client_secret|password|private_key` 대입)뿐이다(`scripts/lib/secret-scan.ts:20-31`). 부작용: build id가 `design-system` chunk(66 KB gzip)에 들어가 release마다 이 chunk 해시가 바뀐다 | +| 발생 조건 | 빌드 환경(CI 변수, 개발자 셸, `.env.local`)에 `VITE_` 접두어 비밀값이 있을 때. 코드에서 참조하지 않아도 들어간다 | +| 영향 | 비밀값이 공개된다. 게이트는 PASS를 낸다 | +| 심각도·우선순위 | Medium · P2 — 전제는 `VITE_`에 비밀을 넣는 실수다(`.env.example:1-4`가 경고한다). 다만 참조하지 않은 값까지 싣는 범위는 이 템플릿 코드가 넓혔고, 탐지도 안 된다 | +| 통제·증거 | M1(문서 경고), 탐지 M3(4개 형식만) · E3 | +| 확실성과 남은 가정 | 직접 build해 확인했다 | +| 최소 개선 방향 | `import.meta.env.VITE_BUILD_ID`처럼 키마다 직접 참조한다(Vite가 개별로 치환). 전체 객체 참조를 lint로 금지한다. build 스크립트에서 허용 목록 밖 `VITE_*` 변수가 있으면 실패시킨다. 탐지 규칙은 표준 규칙 세트 사용을 검토한다 | +| 비용·부작용 | 작다. 규칙을 넓히면 오탐 allowlist 관리가 늘어난다 | +| 완료 기준 | 실험 ⑦을 반복했을 때 probe 문자열이 dist에 없다. design-system chunk 해시가 build id에 따라 바뀌지 않는다 | +| 검증 방법 | build 테스트: 임의 `VITE_*` 변수를 넣고 dist grep | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 13-07 하위 경로 배포에서 config·manifest URL이 base를 따르지 않아 부트가 실패한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 19, 18, 23 | +| 근거 | `vite.config.ts:7-15`는 "하위 경로 배포가 일관되거나 build에서 실패한다"고 적는다. 하지만 runtime config URL 기본값은 `/config.json`(`src/contracts/env.ts:46`, `:128`)이고, 프로필의 `RELEASE_MANIFEST_URL`은 `/release-manifest.json`이다(`config/runtime/*.json`). 배포 시 덮어쓸 수 있는 값은 API·telemetry뿐이다(`scripts/generate-runtime-config.ts:32-35`). 실험 ⑧: `VITE_ROUTER_BASE_PATH=/app/` build 성공 → `index.html`은 `/app/assets/…`, 번들의 config URL은 `/config.json`, `dist/config.json`의 manifest URL은 `/release-manifest.json`. hosting 확인 경로도 루트 고정(`scripts/verify-hosting-headers.ts:80-85`) | +| 발생 조건 | `/app/`처럼 하위 경로에 배포하고 `VITE_RUNTIME_CONFIG_URL`과 프로필 파일을 따로 고치지 않았을 때 | +| 영향 | build와 게이트는 통과하고, 부트에서 config 404로 전면 실패 | +| 심각도·우선순위 | Low · P2 — 하위 경로 배포에만 해당하고 첫 배포에서 바로 드러나며 우회가 있다. 그러나 `.env.example:20-22`가 지원 기능으로 안내한다 | +| 통제·증거 | M1 · E3 | +| 확실성과 남은 가정 | 산출물을 직접 확인했다. 브라우저 부트는 실행하지 않았다 | +| 최소 개선 방향 | 두 URL 기본값을 base에서 만든다(`${base}config.json`). 또는 base가 `/`가 아닌데 두 값이 base로 시작하지 않으면 build를 실패시킨다 | +| 비용·부작용 | 작다 | +| 완료 기준 | `/app/` build에서 두 URL이 `/app/`로 시작하거나 build가 실패한다 | +| 검증 방법 | runtime-config 생성 테스트에 base 케이스 추가 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 13-08 선언된 CSP가 브라우저에서 한 번도 적용되지 않고, opt-in 기능을 막는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 15, 10 (+30.2) | +| 근거 | CSP는 `config/hosting/security-headers.json:4`에 선언만 있다. e2e는 `vite preview`로 돌고(`playwright.config.ts:16-20`) 헤더를 붙이지 않는다. CSP를 붙이는 테스트는 없다(grep). 문서는 빌드 산출물이 CSP와 호환된다고 한다(`docs/security/browser-boundary.md:7-10`). `connect-src 'self' https:`는 다른 origin의 `wss:`를 허용하지 않는다(CSP3 scheme 비교 규칙: `https:`는 `https`만 맞음). realtime은 `wss://`을 만든다(`src/adapters/realtime/websocket/websocket-connection.ts:1609`). `img-src 'self' data:`에는 preview lease가 쓰는 `blob:`이 없다(`src/adapters/browser-files/object-url-lease.ts:111`, `:286`). 기본 구성은 이 기능들이 꺼져 있어 영향이 없다(`src/features/installed-runtime-capabilities.ts:35-41`). 기본 `index.html` 산출물에는 inline script·style이 없다(실험 산출물 확인) | +| 발생 조건 | 사용 프로젝트가 realtime(다른 origin), 파일 preview, 이미지 CDN recipe를 켜고 이 CSP를 그대로 배포할 때 | +| 영향 | 로컬·e2e에서는 되고 운영 CSP에서만 막힌다. 반대로 `connect-src https:`는 XSS가 나면 임의 HTTPS로 데이터를 보낼 수 있게 둔다 | +| 심각도·우선순위 | Low · P2 — 기본 구성은 문제없다. 기능을 켤 때 반드시 부딪히는 함정이다 | +| 통제·증거 | M1 · E1(`wss` 판정은 명세 기준, 브라우저 실행 미확인) | +| 확실성과 남은 가정 | 브라우저에서 CSP 위반을 재현하지 않았다 | +| 최소 개선 방향 | e2e 한 벌을 `security-headers.json` 헤더를 붙이는 정적 서버로 돌리고 `securitypolicyviolation` 0건을 확인한다. recipe 문서에 필요한 CSP 추가분을 적는다. `connect-src`를 runtime config의 API·telemetry origin으로 좁히는 방안을 검토한다 | +| 비용·부작용 | 중간. 헤더를 붙이는 정적 서버가 필요하다(`scripts/serve-static.ts` 확장 가능) | +| 완료 기준 | 운영 CSP 아래 smoke가 통과하고 위반 이벤트가 0건 | +| 검증 방법 | Playwright에서 위반 이벤트 수집 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 13-09 `.npmrc`의 `engine-strict`, `save-exact`가 pnpm 11에서 무시된다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 16, 19, 20 | +| 근거 | `.npmrc:1-2`. `corepack pnpm config list`에 두 값이 없다. 실험 ⑩: scratch 폴더에서 `engines.node: "<1.0.0"` + `.npmrc engine-strict=true` → install 성공. 같은 조건에 `pnpm-workspace.yaml`의 `engineStrict: true` → 엔진 오류로 실패 | +| 발생 조건 | 개발자가 로컬에서 install하거나 의존성을 추가할 때 | +| 영향 | `engines.node >=24.11 <25`가 설치 때 강제되지 않는다. 새 의존성이 `^` 범위로 저장된다. CI는 `.nvmrc`와 frozen lockfile로 막혀 영향이 작다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | 설정이 있다고 믿지만 실제 M0 · E3 | +| 확실성과 남은 가정 | pnpm 11.17.0에서 확인했다 | +| 최소 개선 방향 | `pnpm-workspace.yaml`에 `engineStrict: true`, `saveExact: true`로 옮기고 `.npmrc`에서 지운다 | +| 비용·부작용 | 없음 | +| 완료 기준 | 지원 범위 밖 Node로 install이 실패한다 | +| 검증 방법 | 실험 ⑩ 반복 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 13-10 config 호환성 게이트는 분류기 자기 검사이고, strict reader에서 "additive" 변경이 깨진다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 17, 19, 24 | +| 근거 | FE-GATE-014(`verify:compatibility`)는 `config/compatibility/fixtures.json`의 예제 스키마만 분류한다(`scripts/check-compatibility.ts:23-34`). 이전 release의 실제 스키마와 비교하지 않는다. 예제는 선택 키 추가를 "additive"(호환)로 본다. 그런데 실제 reader는 `.strict()`다(`src/contracts/release-artifacts.ts:50-57`, `:163-171`). 실험 ⑨: production 프로필에 키 하나를 더하면 `unrecognized_keys`로 거부된다. 호스팅 모델에서 `/config.json`은 활성 release의 것이 나간다(`tests/release/old-asset-reachability.test.ts:28-34`) | +| 발생 조건 | 이전 빌드가 새 config를 읽을 때. 예: SW `ACTIVE`에서 캐시된 app shell, 부트 중 포인터 전환 | +| 영향 | "호환"으로 분류된 설정 변경이 이전 빌드의 부트를 실패시킨다. 게이트 이름과 실제 검사가 다르다 | +| 심각도·우선순위 | Low · P3 — 기본 구성(SW 없음)에서는 노출이 작다 | +| 통제·증거 | M1 · E3 | +| 확실성과 남은 가정 | 이전 빌드가 새 config를 읽는 경로를 브라우저에서 재현하지 않았다 | +| 최소 개선 방향 | 게이트가 이전 release의 `runtime-config.schema.json`과 현재 스키마를 비교하게 한다. strict reader 기준으로 "키 추가 = 이전 reader에 breaking"으로 분류하거나, reader가 top-level 미지 키를 무시하는 정책을 명시한다 | +| 비용·부작용 | 중간. 이전 release 스키마를 보관해야 한다 | +| 완료 기준 | 키 추가 변경이 게이트에서 breaking으로 표시된다 | +| 검증 방법 | fixture에 strict reader 케이스 추가 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 13-11 API 실패 telemetry에 release·build 식별값이 없어 배포와 이상을 연결하기 어렵다 + +| 필드 | 내용 | +|---|---| +| 성격 | 개선 제안 | +| 관련 관점 | 7, 8, 18 | +| 근거 | `api.request.failed`의 필수·선택 속성에 `build_id`, `release_id`가 없다(`src/contracts/telemetry.ts:72-77`). `build_id`는 부트 실패·렌더 실패에만 있고 `release_id`는 어느 이벤트에도 필수가 아니다. collector body는 `{ events }`뿐이라 공통 envelope도 없다(`src/adapters/telemetry/telemetry-collector.ts:91`) | +| 발생 조건 | 배포 중 신·구 탭이 공존할 때 API 실패율을 release별로 나누려 할 때 | +| 영향 | FE-RB-003/005의 "새 release 때문인가" 판단에 필요한 연결이 없다 | +| 심각도·우선순위 | Low · P3 — 관측 영역과 겹칠 수 있다 | +| 통제·증거 | M1 · E1 | +| 확실성과 남은 가정 | 서버 쪽에서 요청 헤더로 release를 붙이는지는 확인하지 않았다 | +| 최소 개선 방향 | 모든 이벤트 공통 envelope에 `build_id`, `release_id`를 넣는다 | +| 비용·부작용 | 작다. 값 종류는 release 수만큼만 늘어난다 | +| 완료 기준 | 전송 body의 모든 이벤트에 두 값이 있다 | +| 검증 방법 | telemetry projection 단위 테스트 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 13-12 SBOM·provenance가 증명하는 범위가 문서에 정리되어 있지 않다 + +| 필드 | 내용 | +|---|---| +| 성격 | 개선 제안 | +| 관련 관점 | 16, 24 | +| 근거 | SBOM은 `pnpm list --depth Infinity` 설치 그래프다(`scripts/generate-supply-chain.ts:88-92`). 실험 ⑤: 561개 중 development 551, production 10. 번들에 실제로 들어간 패키지는 module inventory가 `node_modules` 경로를 `external:<파일명>`으로 바꿔 패키지 이름·버전이 남지 않는다(`scripts/lib/vite-module-inventory.ts`, 실험에서 패키지 0개 식별). local provenance는 빌드한 같은 프로세스가 만든 서명 없는 문서다(`builder.id: "local:…"`, `invocationId: "LOCAL_UNSIGNED"`, `generate-supply-chain.ts:252-280`). 그런데 `predicateType`은 SLSA provenance v1이다. 외부 provenance provider는 빌드 뒤 다른 job에서 오프라인으로 후보 digest에 서명한다(`docs/security/supply-chain.md:216-223`) | +| 발생 조건 | 사용 프로젝트나 감사자가 SBOM·provenance를 근거로 판단할 때 | +| 영향 | 아래 표의 "증명하지 못하는 것"을 증명된 것으로 오해할 수 있다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M2 · E3 | +| 확실성과 남은 가정 | 외부 provider 출력은 보지 못했다 | +| 최소 개선 방향 | 문서에 아래 표를 넣는다. module inventory에 패키지 이름·버전을 남겨 "배포물에 든 패키지" 목록을 만든다. local 문서에 "서명 없음, 자기 보고"를 표시한다 | +| 비용·부작용 | 작다 | +| 완료 기준 | 배포물에 든 패키지@버전 목록이 산출물로 나온다 | +| 검증 방법 | 목록과 SBOM production 항목 대조 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +| 산출물 | 증명하는 것 | 증명하지 못하는 것 | +|---|---|---| +| SBOM | lockfile에 고정된 설치 그래프와 각 패키지의 sha512 integrity, license | 배포물에 실제로 들어간 부분 집합, 취약점 없음 | +| local provenance | dist digest ↔ lockfile ↔ source set ↔ SBOM digest가 서로 맞음 | 빌드 과정이 변조되지 않았음(서명·격리 없음), 빌드한 주체 | +| 외부 provenance 서명 | 지정 키 보유자가 이 run·source revision·후보 digest를 보고 서명함 | 빌드 job 자체의 격리, provider가 성실히 검사했음(`supply-chain.md:244-248`도 이렇게 적음) | +| 외부 vulnerability 서명 | provider가 이 lockfile·dist에 대해 결과를 주장함 | 오프라인 DB의 최신성, 누락 없음 | + +### 13-13 공급망·승격 체계의 도입 비용이 크고 실제 환경에서 한 번도 돈 적이 없다 + +| 필드 | 내용 | +|---|---| +| 성격 | 미검증 | +| 관련 관점 | 16, 4, 9 (+30.6) | +| 근거 | 공급망·승격·provider 관련 스크립트가 약 8.9k줄이다. 승격까지 가려면 bwrap·prlimit·systemd-run, systemd user manager 254 이상, cgroup v2 위임(`docs/security/supply-chain.md:113-128`), 오프라인 데이터로 Ed25519 서명 보고서를 내는 provider 두 개(`:210-215`)가 필요하다. repo 안의 vulnerability 결과는 `UNCONFIGURED`/`FAIL_UNVERIFIED` placeholder다(`scripts/lib/local-policy-evidence.ts:42-53`). 문서는 staging Gitea에서 end-to-end smoke를 먼저 통과해야 required check로 쓸 수 있다고 한다(`docs/operations/ci-quality-gates.md:201-203`, `supply-chain.md:110-111`). 그 실행 기록은 없다. provider 없이 승격을 끄는 선택지는 문서에 없다. provider 신뢰 키 교체 절차도 없다 | +| 발생 조건 | 사용 프로젝트가 Gitea 외 CI나 일반 runner에서 이 파이프라인을 쓰려 할 때 | +| 영향 | 승격 단계까지 쓰려면 사용 프로젝트가 큰 인프라를 먼저 갖춰야 한다. 못 갖추면 승격이 항상 실패하고, 결국 파이프라인을 우회하게 된다 | +| 심각도·우선순위 | Low · P3 — 문서가 한계를 정직하게 적고 fail-closed로 동작한다 | +| 통제·증거 | M2 · E2(단위·fixture) / 실제 환경 미확인 | +| 확실성과 남은 가정 | `test:system`과 provider 실행은 하지 않았다 | +| 최소 개선 방향 | "provider 없는 구성"(local 증거까지만, 승격은 수동 승인)을 지원 구성으로 문서화한다. 신뢰 키 교체·폐기 절차를 적는다. staging smoke 결과를 기록한다 | +| 비용·부작용 | 문서 작업이 주다 | +| 완료 기준 | 최소 구성과 전체 구성이 각각 무엇을 보장하는지 문서에 있다 | +| 검증 방법 | 문서 검토, staging smoke 기록 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 13-14 초기 JS 예산의 96%를 템플릿 기본 화면이 쓰고, lab 측정은 1회다 + +| 필드 | 내용 | +|---|---| +| 성격 | 개선 제안 | +| 관련 관점 | 14 | +| 근거 | 실험 ⑥: 초기 JS 196,623 / 204,800 gzip bytes(`config/performance/budgets.json`). 초기 파일 9개 중 `index` 93.5 KB, `design-system` 65.6 KB, `preload-helper` 28.5 KB. CSS 8.5 KB는 합계에 없다(`scripts/check-bundle.ts:34-37`은 JS만 센다). 측정 조건(Node·pnpm·runner)은 기록된다(`scripts/generate-supply-chain.ts:309-321`). lab 측정(`scripts/test-performance.ts:57-100`)은 local 프로필 build를 `vite preview`로 띄워 1회 측정하고, 상호작용 시간은 Node의 `performance.now()`로 Playwright 클릭부터 heading 대기까지 잰다(Playwright 왕복 포함) | +| 발생 조건 | 사용 프로젝트가 첫 기능을 추가할 때 | +| 영향 | 약 8 KB 여유라 첫 기능 추가에서 예산이 깨질 가능성이 높다. 사용 프로젝트가 이유 없이 예산을 올리게 된다. lab 1회 측정은 흔들린다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M3 · E3(번들), lab은 미실행 | +| 확실성과 남은 가정 | gzip 수준은 Node 기본값이다. 호스팅 압축(brotli 등)과 다를 수 있다 | +| 최소 개선 방향 | 템플릿 기준선과 여유를 문서에 적는다. CSS 포함 여부를 명시한다. lab은 여러 번 측정해 중앙값을 쓴다 | +| 비용·부작용 | 작다. CI 시간이 조금 는다 | +| 완료 기준 | 예산 문서에 기준선·여유·측정 조건이 있다 | +| 검증 방법 | 문서 검토 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +### 13-15 런타임 설정의 정본 위치·배포 변수 설명이 문서와 다르고 사본이 두 벌이다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 19, 20, 9, 23 | +| 근거 | README는 런타임 설정이 `public/config.json`에 있다고 한다(`README.md:24`). 실제로 build는 이 파일을 `config/runtime/.json`으로 덮어쓴다(`scripts/build-frontend.ts:24-28`). `APP_PROFILE`, `RUNTIME_API_BASE_URL`, `RUNTIME_TELEMETRY_ENDPOINT`, `RELEASE_TARGET`은 README·docs 어디에도 없다(grep). `public/config.json`과 `config/runtime/local.json`은 같은 내용의 사본인데 동기화 검사가 없다. `ENV_REGISTRY`는 `VITE_BUILD_ID`를 필수로 적지만(`src/contracts/env.ts:43`) 코드는 `local-build`로 대체한다(`:125`). `build-frontend.ts:24-28` 주석은 SW가 config.json을 해시한다고 하지만 SW 자산 목록은 이를 뺀다(`scripts/generate-service-worker-assets.ts:36`) | +| 발생 조건 | 사용 프로젝트가 README를 보고 운영 설정을 `public/config.json`에 넣을 때 | +| 영향 | 수정이 build에서 조용히 사라진다. 배포 변수를 코드에서 찾아야 한다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M1 · E1 | +| 확실성과 남은 가정 | 정적 확인 | +| 최소 개선 방향 | README 설정 절을 프로필·배포 변수·우선순위(프로필 < `RUNTIME_*` 덮어쓰기 < build identity) 기준으로 고친다. `public/config.json`을 local 프로필에서 생성하거나 동기화 검사를 둔다 | +| 비용·부작용 | 작다 | +| 완료 기준 | 문서만 보고 production 산출물을 만들 수 있다 | +| 검증 방법 | `verify:documentation`에 변수 목록 대조 추가 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +## 5. 28개 관점 판정 (36.2) + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +|---|---|---|---|---|---| +| 1 | 코드 성숙도 | 다른 영역 — `src/` 규칙은 각 영역 | — | — | 적용 제외 | +| 2 | 구조적 성숙도 | 다른 영역 — 아키텍처 영역 | — | — | 적용 제외 | +| 3 | 변경 용이성 | 적용 — 새 프로필·환경 추가 경로 | M2 목표 / 프로필·`DEPLOYMENT_TARGETS`·`public` 사본·CI 변수를 함께 바꿔야 함 | E1 | 부분 충족 — 13-15 | +| 4 | 인지 부하 | 적용 — 릴리스 파이프라인 이해 비용 | 27 gate, 공급망 문서 한 문단이 수십 개 규칙 | E1 | 부분 충족 — 13-13 | +| 5 | 위험 가시성 | 적용 — gate 결과가 실제 확인 범위를 드러내는가 | drill·hosting이 "provider verification required"를 출력하지만 기록은 PASS | E3 | 부분 충족 — 13-03, 13-05 | +| 6 | 실패 성숙도 | 적용(좁게) — build 단계 실패 처리 | 각 단계 비정상 종료 시 즉시 중단(`build-frontend.ts:34-43`), 증거 쓰기 원자적 rename | E1 | 충족(이 범위) | +| 7 | 운영 성숙도 | 적용 — 배포 버전과 이상 연결 | 부트·렌더 실패에 build_id, API 실패에는 없음 | E1 | 부분 충족 — 13-11 | +| 8 | 디버깅 가능성 | 적용 — 운영 오류를 빌드와 소스로 연결 | commit·build id는 manifest에 있음. 공개 source map 금지는 맞지만 비공개 source map 보관 경로가 없어 압축된 stack trace를 풀 수단이 없다 | E1 | 부분 충족 | +| 9 | 유지보수 성숙도 | 적용 — 설정·문서 드리프트 | 죽은 `.npmrc` 설정, 낡은 README, 사본 두 벌 | E3 | 부분 충족 — 13-09, 13-15 | +| 10 | 테스트 성숙도 | 적용 — 릴리스 규칙의 검증 | admission·coherence·캐시 모델 단위 테스트는 좋음(E2). CSP·운영 헤더 브라우저 검증 없음, drill은 상수 판정 | E2·E3 | 부분 충족 — 13-03, 13-08 | +| 11 | 데이터 성숙도 | 다른 영역 — 브라우저 저장소 | — | — | 적용 제외 | +| 12 | 동시성 성숙도 | 다른 영역 — 탭·저장소 | — | — | 적용 제외 | +| 13 | 확장성 | 다른 영역 — extreme-scale 문서·영역 | — | — | 적용 제외 | +| 14 | 성능 성숙도 | 적용 — 번들 예산 측정 조건 | 예산 M3, 조건 기록 있음, 여유 4%, lab 1회 | E3 | 부분 충족 — 13-14 | +| 15 | 보안 성숙도 | 적용 — CSP·헤더·번들 비밀값 | 헤더 선언 M1, 설정 키 금지·strict M4, 번들 비밀값 탐지 좁음. 참고: `dist/.vite/manifest.json`도 공개 배포물에 포함됨(소스 경로 노출, 영향 작음) | E3 | 부분 충족 — 13-06, 13-08 | +| 16 | 의존성 성숙도 | 적용 — 잠금·설치 스크립트·SBOM·provenance | frozen lockfile + `--ignore-scripts` CI에서 M4, sha512 전부, vulnerability 검사는 외부 미구성, `.npmrc` 무시, build에서 `npx` 사용(`build-frontend.ts:53`, 설치 전에는 registry 조회 가능) | E3 | 부분 충족 — 13-09, 13-12, 13-13 | +| 17 | API / Contract 성숙도 | 적용(좁게) — 설정·manifest 스키마 | 버전 판별 스키마, V1 reader 유지. 호환 게이트는 예제만 | E3 | 부분 충족 — 13-10 | +| 18 | 배포 성숙도 | 적용 — 검증물=배포물, HTML·자산 전환, 롤백 | 후보 archive 연결 강함(E2). admission 미실행, hosting 배포 전 실행, 파일 권한, drill이 다른 빌드 확인, 자산 보존 기간 없음 | E3 | 미충족 — 13-01~13-05 | +| 19 | 설정 성숙도 | 적용 — 스키마·우선순위·기본값·검증 위치 | 스키마 단일·strict·환경별 규칙 M4. 기본 프로필 local, 하위 경로 URL, 우선순위 미문서화 | E3 | 부분 충족 — 13-01, 13-07, 13-15 | +| 20 | 개발자 경험 | 적용 — build·배포 시작 경로 | `pnpm build` 5초 내 성공(실험). 운영 build 방법이 문서에 없음 | E3 | 부분 충족 — 13-15 | +| 21 | Guardrail 성숙도 | 적용 — gate가 실제로 실행·검출하는가 | negative fixture 다수. gate 소유 검사가 실행 여부를 보지 않음 | E3 | 부분 충족 — 13-01, 13-05 | +| 22 | 추상화 성숙도 | 다른 영역 | — | — | 적용 제외 | +| 23 | 일관성 | 적용 — 도구·경로 규칙 | `npx`와 `corepack pnpm` 혼용, dist/config.json writer 두 개, 경로 규칙 불일치 | E1 | 부분 충족 — 13-07 | +| 24 | 네이밍 / 의미 성숙도 | 적용 — gate 이름이 보장 범위와 맞는가 | "rollback-drill", "critical smoke", "config-compatibility"가 실제보다 넓게 들림 | E3 | 부분 충족 — 13-03, 13-10 | +| 25 | 조직 확장성 | 적용 제외 — 1인 관리(전제) | 구조적 준비만: gate 레지스트리·owner 필드 있음 | E1 | 적용 제외 | +| 26 | Ownership 성숙도 | 적용 — 승인·예외 책임 | 취약점 예외는 다른 reviewer 필수. dependency baseline 승인은 환경변수로 자기 기재(`update-dependency-baseline.ts:6-13`). runbook escalation 역할은 있으나 실제 담당 없음 | E1 | 부분 충족 | +| 27 | 삭제 가능성 | 다른 영역 — FE-GATE-020 제거 테스트. 이 영역: 공급망 체계를 끄는 경로가 문서에 없음 | M0 | E1 | 부분 충족 — 13-13 | +| 28 | 회복 가능성 | 적용 — 롤백 절차 실행 가능성 | 절차 문서 M1, 이전 release 재검증 불가, drill은 상수 판정, 복구 목표 TBD | E3 | 미충족 — 13-03, 13-04 | + +### 5.1 33절 시나리오 적용 + +| 시나리오 | 적용 | 판정 | +|---|---|---| +| 새 환경 생성 | 부분 — CI 변수 목록 | `APP_PROFILE`·`RELEASE_TARGET` 누락(13-01). 호스팅은 provider 미정 | +| 인스턴스·노드 중단, 공통 의존성 장애, readiness·liveness, 자원 압박 | 적용 제외 — 정적 호스팅, 서버 프로세스 없음 | — | +| 백업·복구 | 적용 — 이전 release 보관과 복원 | 승격 artifact 보관 기간은 조직 결정으로 비움(`gates.json` retention `UNSUPPORTED_PENDING_ORGANIZATION_POLICY`). 이전 release 재검증 불가(13-04). 미충족 | +| 비밀값·인증서 교체 | 부분 — 프론트에는 런타임 비밀이 없음(설계상). provider 신뢰 키만 해당 | 키 교체·폐기 절차 없음(13-13). 미충족 | +| 공급망·배포 권한 | 적용 | 후보 digest·서명 연결 강함. 배포 단계와 그 권한은 repo 밖. 부분 충족 | +| 구성 차이 누적 | 적용 — 헤더·캐시 선언과 실제 | 배포 뒤 확인 없음(13-05). 미충족 | +| 기반 제거·이전 | 적용 제외 — 호스팅 자원이 repo에 없음 | — | + +## 6. 미검증 목록 + +| 항목 | 필요한 것 | +|---|---| +| 실제 호스팅에서 헤더·SPA fallback·포인터 전환·이전 자산 보존 | provider 선정 후 live `verify:hosting-headers`와 deep link·404 확인 | +| Gitea에서 workflow 전체 실행(특히 immutable_build, provider, promotion) | staging Gitea와 runner, repo 변수 | +| 외부 vulnerability·provenance provider와 `test:system` | bwrap·systemd 254+·cgroup v2 위임 runner, 서명 키 | +| 운영 CSP 아래 브라우저 동작, `wss:` 차단 여부 | 헤더를 붙이는 정적 서버 + Playwright | +| production 프로필 산출물의 브라우저 부트 | 외부 인증·API 대역(e2e는 local/demo만 확인) | +| mode 0600 파일의 실제 403 | nginx 컨테이너에서 dist 서빙 | +| SW `ACTIVE` 2-pass build와 config 호환 | capability 선택 변경 후 build·e2e | +| 여러 runner 사이 빌드 재현성 | 서로 다른 runner 이미지에서 digest 비교 | +| lab performance(FE-GATE-026) | Playwright Chromium 실행 | +| pnpm 11의 최소 공개 경과 기간 기본값 | pnpm 문서 확인(`minimumReleaseAgeExclude`가 이를 전제함) | diff --git a/docs/reviews/2026-09-25-maturity-review/14-template-product-docs.md b/docs/reviews/2026-09-25-maturity-review/14-template-product-docs.md new file mode 100644 index 00000000..5335c956 --- /dev/null +++ b/docs/reviews/2026-09-25-maturity-review/14-template-product-docs.md @@ -0,0 +1,266 @@ +# 템플릿 제품성·문서·개발자 경험 성숙도 리뷰 + +> 검토일: 2026-09-25 · 기준: `main` / `4626b73` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 범위: `README.md`(181줄), `docs/`(추적 파일 118개, 약 61,800줄 — 표본 대조), `recipes/`(3,681줄), `schemas/`(5개), `.storybook/`(2개), `SPEC.md`·`tasks/`(826줄), 제거 스크립트 4개(823줄)와 `scripts/lib/removal-fixture.ts`, 기능 설치 생성기 `scripts/generate-product-feature-index.ts`, CI 계약 `scripts/contracts/ci-gates.ts`(해당 부분) +> 영역 판정(35.8): **조건부 사용 가능** — 샘플을 유지한 채 시작하는 용도에 한정. "샘플을 지우고 자기 기능으로 시작"하는 용도는 14-01·14-02를 고치기 전까지 **사용 보류**. + +## 1. 결론 + +- **샘플 제거 게이트가 현재 main에서 실패한다(14-01, High).** `corepack pnpm test:sample-removal`(merge 단계 FE-GATE-020)을 실행한 결과 13개 검사 중 typecheck, unit-integration, coverage, home-smoke, fixture-id-residue 5개가 실패했다. 원인은 2026-09-24 수정 라운드(R-7.5, R-8.5, R-8.7, R-9.3, Q-6.8-10, Q-6.9-12)에서 추가된 플랫폼 테스트 6개가 샘플 기능을 직접 참조하는 것이다. README의 "샘플을 지워도 typecheck·test·build가 유지된다"는 주장은 지금 거짓이다. 이 템플릿을 복사한 프로젝트는 첫 PR부터 merge 게이트가 빨간 상태로 시작한다. +- **실제 프로젝트에서 샘플이나 선택 기능을 지우면 `check:ci`가 실패한다(14-02, Medium).** CI 계약이 "게이트 27개·명령 91개·참조 103개·산출물 109개"와 게이트 모양의 SHA-256 해시로 고정돼 있다. 제거 스크립트는 fixture 전용 완화 모드(`CI_CONTRACT_MODE=removal-fixture`)에서만 통과한다. 다운스트림이 이 기준선을 바꾸는 절차는 어디에도 문서화돼 있지 않다. +- **새 기능 추가 안내가 현재 설치 방식과 다르다(14-03, Medium).** 문서는 중앙 catalog 파일에 등록하라고 안내한다. 실제로는 `feature-module.ts`·`context-routes.ts`·context 선언을 두면 생성기가 기능을 찾아낸다. 이 규칙은 생성기 주석과 리뷰 폴더 안의 계획 문서에만 있다. +- **템플릿 버전 식별과 패치 전파 경로가 없다(14-04, Medium).** 태그, CHANGELOG, "원본 패치를 받는 방법" 문서가 없다. 최근 보안 수정(R-3.4, R-7.4, R-9.3)이 다운스트림에 전달될 경로도 없다. +- 문서는 이유·한계를 잘 설명하는 편이다. 다만 규모가 크고(약 62K줄), 현재 계약·목표 설계·작업 이력이 한 트리에 섞여 있으며, 최상위 지원 범위 표가 없다(14-05, 14-06). 수치·목록 drift도 여러 곳에 있다(14-07). +- 미검증: 깨끗한 환경에서 설치부터 실행까지, 나머지 제거 게이트 3개, 작성자 외 사용자의 기능 추가. + +## 2. 범위와 방법 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 | `clean-architecture-frontend-template`, `main` `4626b73`, 워킹트리 깨끗함(미추적 `CLAUDE.md`, 가이드 1개) | +| 목적·실행 구성 | 복사해서 시작점으로 쓰는 프론트엔드 템플릿. SPA + 정적 호스팅. SSR 없음 | +| 읽은 것 | README 전체, `docs/architecture`의 입구 문서(`starter-experience.md`, `overview.md`, `frontend-application-foundation.md`, `optional-adapter-recipes.md`, `capability-consumer-experience.md`, `browser-data-capability-completion-ledger.md` 앞부분, `frontend-platform-implementation-roadmap.md` 1~4절), `docs/testing/taxonomy.md`, `docs/operations/ci-quality-gates.md` 앞부분, `docs/contracts/compatibility.md`, `docs/styling/design-system-platform.md` 1·10절, `src/features/reference-feature/README.md`, 제거 스크립트 4개, `scripts/lib/removal-fixture.ts`, `scripts/lib/fixture-node-modules.ts`, 생성기, `scripts/contracts/ci-gates.ts` 430~620행, `scripts/verify-documentation-readiness.ts`, `scripts/update-registry-baseline.ts`, `config/recipes/frontend-capability-recipes.json`, `config/ci/gates.json`(구조), `.env.example`, `public/config.json`, `config/runtime/*.json` | +| 실행한 것 | ① `corepack pnpm test:sample-removal` — **실패(exit 1)**, 1분 49초. 스크립트를 먼저 읽고 `.tmp/reference-feature-removal-*`(gitignore, 종료 시 삭제)와 `artifacts/tests/sample-removal.xml`에만 쓰는 것을 확인한 뒤 실행했다. 실행 후 `git status`는 변화 없음. 로그: scratchpad `14/sample-removal.log`. ② CI 계약 파서 실험 — `config/ci/gates.json`을 메모리에서 바꿔 `parseCiGateContract`에 넣음(파일 쓰기 없음, scratchpad `14/ci-canonical-probe2.ts`). ③ README에 나오는 `pnpm "); + await write( + "dist/.vite/manifest.json", + JSON.stringify({ + "index.html": { file: "assets/index-a.js", isEntry: true, css: ["assets/index-a.css"], imports: ["_shared-b.js"] }, + "_shared-b.js": { file: "assets/shared-b.js" }, + "src/pages/lazy.tsx": { file: "assets/lazy-c.js", isDynamicEntry: true }, + }), + ); + await write("dist/assets/index-a.css", "body{}"); + if (!options.withoutJs) { + for (const file of ["assets/index-a.js", "assets/shared-b.js", "assets/lazy-c.js"]) { + await write(`dist/${file}`, "export {};"); + } + } + await write( + "dist/release-manifest.json", + JSON.stringify({ + schemaVersion: 2, + appVersion: "1.0.0", + buildId: "build-a", + commitSha: "abc1234", + configSchemaVersion: "2.0", + assetManifestHash: "assets-a", + releaseId: "release-a", + builtAt: "2026-08-01T00:00:00.000Z", + routeChunks: {}, + contractSet: { + setAlgorithm: "CA_CONTRACT_SET_V1", + setDigest: await computeContractSetDigest(contractPackages), + packages: [...contractPackages], + }, + }), + ); + await write( + "dist/config.json", + JSON.stringify({ + APP_ENV: "local", + API_BASE_URL: "http://localhost:8080/", + REQUEST_TIMEOUT_MS: 10_000, + MAX_RETRY_ATTEMPTS: 2, + TELEMETRY_ENABLED: false, + AUTH_MODE: "external", + CONFIG_SCHEMA_VERSION: "2.0", + RELEASE_MANIFEST_URL: "/release-manifest.json", + BUILD_ID: "build-a", + RELEASE_ID: "release-a", + CAPABILITY_OVERRIDES: { + REALTIME: "DEFAULT", + WEB_WORKER: "DEFAULT", + SERVICE_WORKER: "DEFAULT", + OFFLINE_COMMANDS: "DEFAULT", + }, + FEATURE_OVERRIDES: {}, + }), + ); + return root; +} + +describe("runbook drill verdicts", () => { + it.each(RUNBOOK_IDS)("%s on a complete local build is UNVERIFIED, not PASS", async (runbookId) => { + const record = await runRunbookDrill(runbookId, { root: await builtDist(), contractPackages }); + expect(record.result).toBe("UNVERIFIED"); + expect(record.recoveryAssertions.some(({ result }) => result === "FAIL")).toBe(false); + }); + + it.each(["FE-RB-002", "FE-RB-005"] as const)( + "%s fails when the build lost its JavaScript assets", + async (runbookId) => { + const record = await runRunbookDrill(runbookId, { + root: await builtDist({ withoutJs: true }), + contractPackages, + }); + expect(record.result).toBe("FAIL"); + }, + ); + + it("FE-RB-005 fails without a build instead of reading public/ placeholders", async () => { + await expect( + runRunbookDrill("FE-RB-005", { root: await builtDist({ withoutDist: true }), contractPackages }), + ).rejects.toThrow(/dist\/release-manifest\.json/u); + }); + + it("keeps no constant recovery verdict in the drill source", async () => { + const source = await readFile("scripts/drill-runbook.ts", "utf8"); + expect(source).not.toMatch(/assertion\([^;]*,\s*true\s*\)/u); + expect(source).not.toMatch(/Asserted:\s*true\b/u); + expect(source).not.toMatch(/injectedMountFailure\s*=\s*true/u); + }); +}); From 2afee67150c068aeadcc2a14d767fe2f2893020e Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 22:16:25 +0900 Subject: [PATCH 021/185] fix(http): let the package classify command 401/403/429 and keep re-login first (03-02) These statuses skipped the package classifier and always became MAYBE_APPLIED, so an expired session ended in "contact support" or the unknown-result screen. The descriptor gains optional classifyStatus, the reference create declares NOT_APPLIED, and AUTH_REQUIRED keeps reauth. Co-Authored-By: Claude Opus 5.5 --- ...igned-implementation-closed-deep-design.md | 3 + src/adapters/http/http-effect-certainty.ts | 22 ++++++ src/adapters/http/http-execution-v3.ts | 23 +++---- src/contracts/errors.ts | 12 +++- src/contracts/external-contract-runtime.ts | 12 ++++ ...reference-feature-contract-contribution.ts | 5 ++ .../reference-production-vertical.test.tsx | 42 +++++++++++ tests/mocks/scenarios/catalog.ts | 6 +- tests/unit/error-classification.test.ts | 14 ++++ tests/unit/http-execution-v3.test.ts | 69 +++++++++++++++++++ 10 files changed, 190 insertions(+), 18 deletions(-) diff --git a/docs/architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md b/docs/architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md index a7bec984..2112ff41 100644 --- a/docs/architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md +++ b/docs/architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md @@ -635,6 +635,7 @@ export interface CommandEffectDescriptor { status: number; problem: Problem; }>): "NOT_APPLIED" | "APPLIED_CONFIRMED" | "MAYBE_APPLIED"; + classifyStatus?(status: 401 | 403 | 429): "NOT_APPLIED" | "MAYBE_APPLIED"; } ``` @@ -647,6 +648,8 @@ export interface CommandEffectDescriptor { - frontend는 inspect request/response wire shape나 problem effect meaning을 작성하지 않는다; - `classifyProblem`은 package가 제공한 pure bounded classifier다; - classifier가 throw/unknown을 반환하면 effect는 fail-safe `MAYBE_APPLIED`이고 contract runtime failure를 기록한다; +- 401·403·429는 본문을 읽기 전에 판정하므로 `classifyProblem`을 거치지 않는다. package가 `classifyStatus`를 주면 그 판정을 쓰고, 없거나 `NOT_APPLIED` 외 값·throw면 전송 뒤 `MAYBE_APPLIED`다(`src/adapters/http/http-effect-certainty.ts` `classifyStatusEffect`); +- `AUTH_REQUIRED`는 effect가 `MAYBE_APPLIED`여도 action이 `reauth`다(`src/contracts/errors.ts` `unknownEffectAction`); - feature gateway가 package의 inspect operation을 application-safe outcome으로 mapping한다. ### 4.5 event contribution diff --git a/src/adapters/http/http-effect-certainty.ts b/src/adapters/http/http-effect-certainty.ts index d008b707..0ad44c28 100644 --- a/src/adapters/http/http-effect-certainty.ts +++ b/src/adapters/http/http-effect-certainty.ts @@ -128,6 +128,28 @@ export function classifyProblemEffect( }); } +/** + * D-2. A dispatched command answered 401, 403 or 429 is `MAYBE_APPLIED` unless + * the package classifies that status as `NOT_APPLIED`. Any other answer, or a + * throw, fails safe to `MAYBE_APPLIED`. + */ +export function classifyStatusEffect( + descriptor: CommandEffectDescriptor | null, + status: 401 | 403 | 429, + abandoned: MutationEffectCertainty, +): MutationEffectCertainty { + if (abandoned !== "MAYBE_APPLIED" || !descriptor?.classifyStatus) { + return abandoned; + } + try { + return descriptor.classifyStatus(status) === "NOT_APPLIED" + ? "NOT_APPLIED" + : "MAYBE_APPLIED"; + } catch { + return "MAYBE_APPLIED"; + } +} + /** §8.10. Certainty to UI intent. The copy itself is owned by the i18n catalog. */ export function projectCertaintyToUi( certainty: MutationEffectCertainty, diff --git a/src/adapters/http/http-execution-v3.ts b/src/adapters/http/http-execution-v3.ts index 47138898..42d8b5ae 100644 --- a/src/adapters/http/http-execution-v3.ts +++ b/src/adapters/http/http-execution-v3.ts @@ -36,6 +36,7 @@ import { import { certaintyForAbandonedAttempt, classifyProblemEffect, + classifyStatusEffect, joinMutationEffectCertainty, type MutationEffectCertainty, type PhysicalAttemptState, @@ -1142,25 +1143,24 @@ async function admitResponse( } const metadata = safeMetadata(response, retryAfterMs); + const statusEffect = (classified: 401 | 403 | 429) => + classifyStatusEffect( + contract.commandEffect, + classified, + certaintyForAbandonedAttempt(attemptState, isCommand), + ); if (!contract.acceptedStatuses.includes(status)) { if (status === 401) { await response.body?.cancel().catch(() => {}); return settled( - unauthenticated( - certaintyForAbandonedAttempt(attemptState, isCommand), - isCommand, - metadata, - ), + unauthenticated(statusEffect(401), isCommand, metadata), "UNAUTHENTICATED", ); } if (status === 403) { await response.body?.cancel().catch(() => {}); - return settled( - forbidden(certaintyForAbandonedAttempt(attemptState, isCommand), isCommand), - "FORBIDDEN", - ); + return settled(forbidden(statusEffect(403), isCommand), "FORBIDDEN"); } if (status === 429) { await response.body?.cancel().catch(() => {}); @@ -1168,10 +1168,7 @@ async function admitResponse( result: Object.freeze({ kind: "RATE_LIMITED" as const, ...(retryAfterMs === null ? {} : { retryAfterMs }), - effect: normalizeOptionalEffect( - certaintyForAbandonedAttempt(attemptState, isCommand), - isCommand, - ), + effect: normalizeOptionalEffect(statusEffect(429), isCommand), }), certainty: "RATE_LIMITED", retryHint: true, diff --git a/src/contracts/errors.ts b/src/contracts/errors.ts index 3fc3e571..86873b98 100644 --- a/src/contracts/errors.ts +++ b/src/contracts/errors.ts @@ -314,13 +314,21 @@ export function createFailure( userMessageKey: definition.userMessageKey, action: details.effect === "MAYBE_APPLIED" - ? "contact-support" + ? unknownEffectAction(definition.action) : details.effect === "APPLIED_CONFIRMED" ? "none" : definition.action, }); } +/** + * D-2. An unknown effect sends the user to support, except when the session + * itself is the problem: signing in again comes first either way. + */ +function unknownEffectAction(action: ErrorAction): ErrorAction { + return action === "reauth" ? "reauth" : "contact-support"; +} + /** * Adds controller-owned mutation effect knowledge without weakening the * fail-safe handling required for an unknown server-side outcome. @@ -333,7 +341,7 @@ export function withFailureEffect( ...failure, effect, ...(effect === "MAYBE_APPLIED" - ? { retryable: false as const, action: "contact-support" as const } + ? { retryable: false as const, action: unknownEffectAction(failure.action) } : effect === "APPLIED_CONFIRMED" ? { retryable: false as const, action: "none" as const } : {}), diff --git a/src/contracts/external-contract-runtime.ts b/src/contracts/external-contract-runtime.ts index 671eaa7b..ca930d11 100644 --- a/src/contracts/external-contract-runtime.ts +++ b/src/contracts/external-contract-runtime.ts @@ -123,6 +123,12 @@ export interface CommandEffectDescriptor { classifyProblem( input: Readonly<{ status: number; problem: Problem }>, ): CommandEffectClassification; + /** + * D-2. 401, 403 and 429 are admitted by status before any problem body is + * read. Declare `NOT_APPLIED` only when the server contract guarantees the + * command was rejected untouched. Without this, they stay `MAYBE_APPLIED`. + */ + classifyStatus?(status: 401 | 403 | 429): "NOT_APPLIED" | "MAYBE_APPLIED"; } export type HttpMethod = @@ -470,6 +476,12 @@ function assertHttpContract( if (typeof contract.commandEffect.classifyProblem !== "function") { fail(`${label}: command effect classifier is required`); } + if ( + contract.commandEffect.classifyStatus !== undefined && + typeof contract.commandEffect.classifyStatus !== "function" + ) { + fail(`${label}: command status classifier must be a function`); + } if (contract.retrySemantics === "KEYED" && !contract.commandRecovery) { fail(`${label}: KEYED commands require a recovery descriptor`); } diff --git a/src/features/reference-feature/contracts/reference-feature-contract-contribution.ts b/src/features/reference-feature/contracts/reference-feature-contract-contribution.ts index 48985218..0f38d803 100644 --- a/src/features/reference-feature/contracts/reference-feature-contract-contribution.ts +++ b/src/features/reference-feature/contracts/reference-feature-contract-contribution.ts @@ -44,6 +44,11 @@ const CREATE_EFFECT: CommandEffectDescriptor = Object.freeze({ } return "MAYBE_APPLIED"; }, + /** + * D-2. The reference backend rejects an unauthenticated, forbidden or + * rate-limited create before touching state. + */ + classifyStatus: () => "NOT_APPLIED" as const, }); export const LIST_REFERENCE_RESOURCES_CONTRACT = Object.freeze({ diff --git a/tests/features/reference-feature/reference-production-vertical.test.tsx b/tests/features/reference-feature/reference-production-vertical.test.tsx index 47a35f7b..e1a14a16 100644 --- a/tests/features/reference-feature/reference-production-vertical.test.tsx +++ b/tests/features/reference-feature/reference-production-vertical.test.tsx @@ -165,4 +165,46 @@ describe("reference feature production vertical path", () => { expect(idempotencyKeys[0]).toMatch(/^[\x21-\x7e]+$/u); expect(idempotencyKeys[1]).toBe(idempotencyKeys[0]); }); + + it.each([ + // The demo session treats a server 401 as signed out; the route guard + // then asks for sign-in and the form is gone. + [401, "세션이 필요합니다."], + [403, "저장하지 못했습니다. 잠시 후 다시 시도해 주세요."], + [429, "저장하지 못했습니다. 잠시 후 다시 시도해 주세요."], + ])( + "treats a create rejected with %i as not applied, not unknown", + async (status, guidance) => { + const user = userEvent.setup(); + mockApi.server.use( + http.post( + "https://api.test/api/reference-resources", + () => new HttpResponse(null, { status }), + ), + ); + const composition = await createRuntimeComposition({ + fetcher: absoluteFetch, + host: {}, + }); + window.history.pushState({}, "", "/examples/reference-resources/new"); + render(); + + await user.click( + await screen.findByRole("button", { name: "로그인 시작" }), + ); + await user.type( + await screen.findByRole("textbox", { name: /새 항목 이름/ }), + "Rejected", + ); + await user.click(screen.getByRole("button", { name: "저장" })); + + expect(await screen.findByText(guidance)).toBeVisible(); + expect( + screen.queryByText("변경 결과를 확인할 수 없습니다."), + ).not.toBeInTheDocument(); + expect( + screen.queryByRole("button", { name: "같은 요청으로 다시 보내기" }), + ).not.toBeInTheDocument(); + }, + ); }); diff --git a/tests/mocks/scenarios/catalog.ts b/tests/mocks/scenarios/catalog.ts index 3e8abaad..8ab7ba87 100644 --- a/tests/mocks/scenarios/catalog.ts +++ b/tests/mocks/scenarios/catalog.ts @@ -232,14 +232,14 @@ function expectationFor( case "unauthenticated-401": statuses = [401]; kind = "UNAUTHENTICATED"; - outcomeEffect = command ? "MAYBE_APPLIED" : "NOT_APPLICABLE"; + outcomeEffect = command ? "NOT_APPLIED" : "NOT_APPLICABLE"; observer = "UNAUTHENTICATED"; bodies = [attemptBody("CANCELLED_WITHOUT_READ", 0, 0)]; break; case "forbidden-403": statuses = [403]; kind = "FORBIDDEN"; - outcomeEffect = command ? "MAYBE_APPLIED" : "NOT_APPLICABLE"; + outcomeEffect = command ? "NOT_APPLIED" : "NOT_APPLICABLE"; observer = "FORBIDDEN"; bodies = [attemptBody("CANCELLED_WITHOUT_READ", 0, 0)]; break; @@ -289,7 +289,7 @@ function expectationFor( const attemptCount = command ? 1 : 3; statuses = Array.from({ length: attemptCount }, () => 429); kind = "RATE_LIMITED"; - outcomeEffect = command ? "MAYBE_APPLIED" : "NOT_APPLICABLE"; + outcomeEffect = command ? "NOT_APPLIED" : "NOT_APPLICABLE"; observer = "RATE_LIMITED"; retryReasons = command ? [] : ["HTTP_429", "HTTP_429"]; media = Array.from({ length: attemptCount }, () => "application/json"); diff --git a/tests/unit/error-classification.test.ts b/tests/unit/error-classification.test.ts index e13c2661..90ad93f0 100644 --- a/tests/unit/error-classification.test.ts +++ b/tests/unit/error-classification.test.ts @@ -5,6 +5,7 @@ import { createFailure, kindForStatus, normalizeUnknownFailure, + withFailureEffect, } from "../../src/contracts/errors.ts"; import { DIAGNOSTIC_EVENT_REGISTRY } from "../../src/contracts/diagnostics.ts"; import { TELEMETRY_REGISTRY } from "../../src/contracts/telemetry.ts"; @@ -51,6 +52,19 @@ describe("frontend failure classification", () => { expect(kindForStatus(status)).toBe(kind); }); + it("keeps re-login first for an auth failure whose effect is unknown (D-2)", () => { + expect( + createFailure("AUTH_REQUIRED", "CREATE", 0, { effect: "MAYBE_APPLIED" }), + ).toMatchObject({ action: "reauth", retryable: false }); + expect( + withFailureEffect(createFailure("AUTH_REQUIRED", "CREATE", 0), "MAYBE_APPLIED"), + ).toMatchObject({ action: "reauth", retryable: false }); + // Every other kind still sends an unknown effect to support. + expect( + createFailure("FORBIDDEN", "CREATE", 0, { effect: "MAYBE_APPLIED" }), + ).toMatchObject({ action: "contact-support" }); + }); + it("projects only allowlisted safe fields", () => { const untrustedDetails = { code: "TEMPORARY", diff --git a/tests/unit/http-execution-v3.test.ts b/tests/unit/http-execution-v3.test.ts index 660e68c0..44ba0012 100644 --- a/tests/unit/http-execution-v3.test.ts +++ b/tests/unit/http-execution-v3.test.ts @@ -992,6 +992,75 @@ describe("terminal owner classification at every wait", () => { ); }); +/** + * D-2 (03-02). 401, 403 and 429 are admitted before any problem body is read. + * The package may classify them by status; without a classifier, or when it + * misbehaves, a dispatched command stays MAYBE_APPLIED. + */ +describe("command status classification", () => { + function withStatusClassifier( + classifyStatus: ((status: 401 | 403 | 429) => unknown) | undefined, + ): InstalledHttpContract { + return { + ...createInstalled, + contract: { + ...createInstalled.contract, + commandEffect: { + ...createInstalled.contract.commandEffect!, + ...(classifyStatus === undefined ? {} : { classifyStatus }), + } as NonNullable, + }, + }; + } + + async function effectFor( + status: number, + contract: InstalledHttpContract, + ) { + const executor = createContractHttpExecutor({ + baseUrl: "https://api.example/", + maxRetryAttempts: 0, + attachCredentials: () => ({ kind: "READY", headers: {} }), + fetcher: vi.fn(async () => new Response(null, { status })), + }); + const outcome = await executor.execute( + contract, + { name: "created" }, + { routeId: ROUTE_ID, scope, intent: mutationIntent() }, + ); + return { kind: outcome.kind, effect: outcome.effect }; + } + + it.each([ + [401, "UNAUTHENTICATED"], + [403, "FORBIDDEN"], + [429, "RATE_LIMITED"], + ] as const)("uses the package classifier for %i", async (status, kind) => { + const classifyStatus = vi.fn(() => "NOT_APPLIED"); + await expect( + effectFor(status, withStatusClassifier(classifyStatus)), + ).resolves.toEqual({ kind, effect: "NOT_APPLIED" }); + expect(classifyStatus).toHaveBeenCalledWith(status); + }); + + const throwingClassifier = (): unknown => { + throw new Error("package defect"); + }; + const unknownAnswer = (): unknown => "APPLIED_CONFIRMED"; + + it.each([ + ["no classifier", undefined], + ["a throwing classifier", throwingClassifier], + ["an unknown answer", unknownAnswer], + ] as const)("keeps MAYBE_APPLIED for %s", async (_label, classifyStatus) => { + for (const status of [401, 403, 429]) { + await expect( + effectFor(status, withStatusClassifier(classifyStatus)), + ).resolves.toMatchObject({ effect: "MAYBE_APPLIED" }); + } + }); +}); + /** * Q-6.3-7. A retried command's final effect joins what earlier attempts already * established, and an answer that says the command may already be applied is From 5a6665a61fecabfa23716f199a90162480779517 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 22:16:56 +0900 Subject: [PATCH 022/185] fix(browser-transfer): scale transfer deadlines with bytes and add a download idle limit (01-03) A fixed 30 s attempt deadline never let a 5 MiB part finish below ~1.4 Mbit/s, and a download had one deadline for its whole body. PUT and download limits now add bytes / minTransferBytesPerSecond (default 64 KiB/s), and a stalled download ends at a per-chunk idle limit. Co-Authored-By: Claude Opus 5.5 --- .../presigned-transfer-and-image-cdn.md | 12 ++ .../browser-transfer/presigned/http-common.ts | 29 +++- .../presigned/presigned-transfer-executor.ts | 51 +++++- .../resumable-upload-runtime.ts | 15 +- .../resumable-upload/runtime-policy.ts | 9 ++ .../unit/presigned-transfer-download.test.ts | 152 ++++++++++++++++++ tests/unit/presigned-transfer-fixture.ts | 8 + .../resumable-upload-runtime-recovery.test.ts | 103 ++++++++++++ 8 files changed, 366 insertions(+), 13 deletions(-) diff --git a/docs/architecture/presigned-transfer-and-image-cdn.md b/docs/architecture/presigned-transfer-and-image-cdn.md index 6dc811ba..5513f8ea 100644 --- a/docs/architecture/presigned-transfer-and-image-cdn.md +++ b/docs/architecture/presigned-transfer-and-image-cdn.md @@ -264,6 +264,13 @@ session state 검사를 대체하지 않는다. object store PUT의 401/403/409/410과 실행기의 만료 판정(`REISSUE_CAPABILITY`)은 `maxRetries` 안에서 다음 시도가 새 capability로 다시 보낸다. BFF 발급 단계의 401/403은 재시도하지 않는다(`resumable-upload-runtime.ts` `uploadPartWithRetry`). +- part PUT 한 번의 제한 시간은 `providerAttemptTimeoutMs + part 바이트 / + minTransferBytesPerSecond`다. 기본값은 30초 + 5MiB ÷ 64KiB/s = 110초다 + (`runtime-policy.ts`). 즉 지원하는 최저 업링크는 기본 약 0.5Mbit/s이고, 이보다 + 느리면 정책의 `minTransferBytesPerSecond`를 낮춘다. fetch는 업로드 진행을 알려 + 주지 않으므로 PUT에는 idle 제한이 없고 이 크기 비례 제한이 멈춘 연결을 끊는다. + presigned 실행기도 `timeoutMs`에 같은 식의 바이트 몫을 더한다 + (`presigned-transfer-executor.ts`, `http-common.ts` `transferAllowanceMs`). - upload response의 opaque receipt/ETag를 whole-file digest로 해석하지 않는다. - PUT capability는 성공 status, receipt header와 `expectedResponseByteLength`를 묶는다. runtime은 exact `Content-Length`를 @@ -439,6 +446,11 @@ Streaming download는 server resource를 전체 `Blob`/`ArrayBuffer`로 material - abort/consumer early return에서 reader를 cancel하고 lock/capability lease를 해제한다. - byte source는 기본 one-shot이며 두 번째 stream 소비를 거절한다. +- 전체 제한과 idle 제한을 따로 둔다. 전체 제한은 `timeoutMs + byteLength / + minTransferBytesPerSecond`(기본 64KiB/s)라 느리지만 진행하는 큰 download는 + 끝까지 받는다. chunk 하나를 기다리는 시간은 `idleTimeoutMs`(기본 `timeoutMs`)가 + 상한이고, 진행이 멈추면 여기서 `UNAVAILABLE/REISSUE_CAPABILITY`로 끝난다 + (`presigned-transfer-executor.ts` `readChunk`, `http-common.ts` `readWithSignal`). File System Access save picker가 있으면 user activation 안에서 destination을 먼저 열고 stream을 쓴다. close와 integrity verification이 끝난 경우만 `SAVED`다. diff --git a/src/adapters/browser-transfer/presigned/http-common.ts b/src/adapters/browser-transfer/presigned/http-common.ts index 1db83099..885d6771 100644 --- a/src/adapters/browser-transfer/presigned/http-common.ts +++ b/src/adapters/browser-transfer/presigned/http-common.ts @@ -96,20 +96,43 @@ export function createAbortScope( }); } +/** + * 01-03. `idleTimeoutMs` bounds this one read, so a stream that stops making + * progress ends there with a `TimeoutError` while a slow one keeps going. + */ export async function readWithSignal( reader: ReadableStreamDefaultReader, signal: AbortSignal, + idleTimeoutMs?: number, + timers?: AbortTimerSnapshot, ): Promise> { if (signal.aborted) throw new DOMException("Aborted", "AbortError"); - const operation = createAbortableOperation({ signal }); + const operation = createAbortableOperation({ + signal, + timeoutMs: idleTimeoutMs, + setTimer: timers?.setTimer, + clearTimer: timers?.clearTimer, + }); const outcome = await operation.race(reader.read()); operation.close(); if (outcome.kind === "VALUE") return outcome.value; - throw outcome.kind === "REJECTED" - ? outcome.reason + if (outcome.kind === "REJECTED") throw outcome.reason; + throw outcome.terminal === "DEADLINE" + ? new DOMException("No progress", "TimeoutError") : new DOMException("Aborted", "AbortError"); } +/** + * 01-03. Time a transfer of `byteLength` needs at the slowest supported + * throughput, added to a fixed base deadline. + */ +export function transferAllowanceMs( + byteLength: number, + minTransferBytesPerSecond: number, +): number { + return Math.ceil((byteLength * 1000) / minTransferBytesPerSecond); +} + /** * A plain decimal `Content-Length`. `Number()` alone accepted `"5e0"`, * `"0x5"`, `"+5"` and `""`. An absent header is `null` unless the caller's diff --git a/src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts b/src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts index 4bcfdb1f..f71a98cd 100644 --- a/src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts +++ b/src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts @@ -43,6 +43,7 @@ import { readWithSignal, SCOPE_ENDED, statusFailure, + transferAllowanceMs, transferFailure, type PresignedAbortScope, } from "./http-common.ts"; @@ -64,7 +65,20 @@ export type PresignedTransferExecutorOptions = Readonly<{ hardMaxChunkBytes: number; hardMaxUploadResponseBytes: number; minimumRemainingLifetimeMs: number; + /** + * Base deadline of one PUT or one download. 01-03: the transfer's bytes at + * `minTransferBytesPerSecond` are added on top, so the limit grows with the + * payload instead of stranding a slow connection. + */ timeoutMs: number; + /** 01-03. Slowest supported throughput. Default 64 KiB/s (~0.5 Mbit/s). */ + minTransferBytesPerSecond?: number; + /** + * 01-03. Longest wait for the next download chunk. A stream that stops making + * progress ends here, well before the size-scaled overall deadline. Default: + * `timeoutMs`. + */ + idleTimeoutMs?: number; fetcher?: typeof fetch; now?: () => number; scheduler?: Scheduler; @@ -108,6 +122,12 @@ export function createPresignedTransferExecutor( options.minimumRemainingLifetimeMs, ); const timeoutMs = positiveSafeInteger(options.timeoutMs); + const minTransferBytesPerSecond = positiveSafeInteger( + options.minTransferBytesPerSecond ?? 64 * 1024, + ); + const idleTimeoutMs = positiveSafeInteger( + options.idleTimeoutMs ?? timeoutMs, + ); const fetcher = (options.fetcher ?? fetch).bind(globalThis); const now = options.now ?? Date.now; // X-AUDIT-02. The timer callables are captured once, bound to their @@ -197,10 +217,16 @@ export function createPresignedTransferExecutor( createScope: (consumerSignal?: AbortSignal) => createAbortScope( signal, - timeoutMs, + timeoutMs + + transferAllowanceMs( + capability.byteLength, + minTransferBytesPerSecond, + ), timers, consumerSignal, ), + readChunk: (reader, scopeSignal) => + readWithSignal(reader, scopeSignal, idleTimeoutMs, timers), recheckExpiry: () => validateExpiry(capability, minimumRemainingLifetimeMs, now()), binding, @@ -300,7 +326,12 @@ export function createPresignedTransferExecutor( // caller signal and the deadline like every other step. Computing it before // the scope existed meant an abort or a deadline could not reach it, and a // hash that never settled held the whole `put` open. - const scope = createAbortScope(request.signal, timeoutMs, timers); + const scope = createAbortScope( + request.signal, + timeoutMs + + transferAllowanceMs(bytes.byteLength, minTransferBytesPerSecond), + timers, + ); try { const digested = await scope.race( Promise.resolve().then(async () => await digestBytes(bytes)), @@ -456,6 +487,10 @@ function createDownloadSource(input: Readonly<{ consumerSignal?: AbortSignal, ) => PresignedAbortScope; recheckExpiry: () => BrowserDataResult; + readChunk: ( + reader: ReadableStreamDefaultReader, + signal: AbortSignal, + ) => Promise>; binding: PresignedCapabilityBinding; capability: PresignedDownloadCapability; externalSignal: AbortSignal; @@ -640,10 +675,7 @@ function createDownloadSource(input: Readonly<{ }); return; } - const result = await readWithSignal( - reader, - scope.signal, - ); + const result = await input.readChunk(reader, scope.signal); if (result.done) break; const chunk = result.value; if (!(chunk instanceof Uint8Array)) { @@ -716,13 +748,16 @@ function createDownloadSource(input: Readonly<{ return; } completed = true; - } catch { + } catch (error) { if ( input.externalSignal.aborted || consumerSignal.aborted ) { yield fail("ABORTED"); - } else if (scope.timedOut()) { + } else if ( + scope.timedOut() || + (error instanceof DOMException && error.name === "TimeoutError") + ) { yield fail("UNAVAILABLE", { retryable: true, recovery: "REISSUE_CAPABILITY", diff --git a/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts b/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts index 3167b0b8..df7f707f 100644 --- a/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts +++ b/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts @@ -28,7 +28,10 @@ import { combineAbortSignals, createAbortableOperation, } from "../../platform/abortable-operation.ts"; -import { observeTransferResult } from "../presigned/http-common.ts"; +import { + observeTransferResult, + transferAllowanceMs, +} from "../presigned/http-common.ts"; import { exactRecord, isAbortSignal, @@ -998,6 +1001,13 @@ async function uploadPartWithRetry( idempotencyKey: idempotencyKey.value, signal: attemptSignal, }), + // 01-03. The PUT carries the part's bytes, so its deadline grows with + // them; control-plane calls keep the fixed base deadline. + dependencies.policy.providerAttemptTimeoutMs + + transferAllowanceMs( + part.byteLength, + dependencies.policy.minTransferBytesPerSecond, + ), ); if (uploaded.ok) { if ( @@ -1359,6 +1369,7 @@ async function invokeProviderAttempt( action: ( attemptSignal: AbortSignal, ) => Promise>, + timeoutMs: number = dependencies.policy.providerAttemptTimeoutMs, ): Promise> { if (parentSignal.aborted) { return providerFailure("ABORTED", operation, false, "NONE"); @@ -1367,7 +1378,7 @@ async function invokeProviderAttempt( // abortable operation, not a second hand-written race. const attempt = createAbortableOperation({ signal: parentSignal, - timeoutMs: dependencies.policy.providerAttemptTimeoutMs, + timeoutMs, }); try { // TR-04. The raw promise enters the physical registry the moment the diff --git a/src/adapters/browser-transfer/resumable-upload/runtime-policy.ts b/src/adapters/browser-transfer/resumable-upload/runtime-policy.ts index 9ced011a..ef681ed6 100644 --- a/src/adapters/browser-transfer/resumable-upload/runtime-policy.ts +++ b/src/adapters/browser-transfer/resumable-upload/runtime-policy.ts @@ -18,6 +18,12 @@ export type ResumableUploadRuntimePolicy = Readonly<{ capabilityRefreshSkewMs: number; maxSessionLifetimeMs: number; providerAttemptTimeoutMs: number; + /** + * 01-03. The slowest uplink a part PUT must survive. Its attempt deadline is + * `providerAttemptTimeoutMs + partBytes / minTransferBytesPerSecond`, so a + * fixed deadline no longer strands a slow connection on its first part. + */ + minTransferBytesPerSecond: number; /** * TR-RR-06. The bound `dispose()` applies to its drain. A non-cooperative * mutation lock or provider would otherwise make teardown unbounded, so a @@ -62,6 +68,8 @@ const DEFAULT_POLICY: ResumableUploadRuntimePolicy = Object.freeze({ capabilityRefreshSkewMs: 5_000, maxSessionLifetimeMs: 24 * 60 * 60_000, providerAttemptTimeoutMs: 30_000, + // 64 KiB/s (about 0.5 Mbit/s): a 5 MiB part gets 30 s + 80 s. + minTransferBytesPerSecond: 64 * 1024, cleanupDeadlineMs: 10_000, }); @@ -111,6 +119,7 @@ export function resolveResumableUploadRuntimePolicy( !positiveSafeInteger(policy.providerAttemptTimeoutMs) || policy.providerAttemptTimeoutMs > ABSOLUTE_LIMITS.maxProviderAttemptTimeoutMs || + !positiveSafeInteger(policy.minTransferBytesPerSecond) || !positiveSafeInteger(policy.cleanupDeadlineMs) || policy.cleanupDeadlineMs > ABSOLUTE_LIMITS.maxProviderAttemptTimeoutMs * 2 || diff --git a/tests/unit/presigned-transfer-download.test.ts b/tests/unit/presigned-transfer-download.test.ts index 8b076541..38f7a331 100644 --- a/tests/unit/presigned-transfer-download.test.ts +++ b/tests/unit/presigned-transfer-download.test.ts @@ -713,3 +713,155 @@ describe("presigned download stream lifecycle", () => { }); }); + +describe("presigned transfer time limits (01-03)", () => { + async function openDownload( + bytes: Uint8Array, + pull: (controller: ReadableStreamDefaultController) => Promise | void, + options: Readonly<{ minTransferBytesPerSecond: number; idleTimeoutMs?: number }>, + ) { + const payload = downloadCapabilityPayload(bytes); + const fetcher = vi.fn(async (input: RequestInfo | URL) => + String(input) === CONTROL_ENDPOINT + ? jsonResponse(payload) + : downloadResponse(new ReadableStream({ pull }), payload), + ) as unknown as typeof fetch; + const harness = createHarness({ fetcher, ...options }); + const issued = await harness.provider.issueDownload({ + resourceId: "resource-1", + signal: new AbortController().signal, + }); + if (!issued.ok) throw new Error("issue failed"); + const opened = await harness.executor.downloadSources.open({ + resourceId: "resource-1", + capability: issued.value, + signal: new AbortController().signal, + }); + if (!opened.ok) throw new Error("open failed"); + return opened.value; + } + + it("keeps a slow but progressing download past the base deadline", async () => { + vi.useFakeTimers(); + try { + const bytes = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); + let offset = 0; + // Two bytes every 3 s: 12 s in total against a 5 s base deadline. + const source = await openDownload( + bytes, + async (controller) => { + await new Promise((resolve) => setTimeout(resolve, 3_000)); + controller.enqueue(bytes.slice(offset, offset + 2)); + offset += 2; + if (offset >= bytes.byteLength) controller.close(); + }, + { minTransferBytesPerSecond: 1 }, + ); + const pending = collect(source); + await vi.advanceTimersByTimeAsync(12_500); + const results = await pending; + + expect(results.every((result) => result.ok)).toBe(true); + expect(results).toHaveLength(4); + } finally { + vi.useRealTimers(); + } + }); + + it("ends a download whose stream stops making progress at the idle limit", async () => { + vi.useFakeTimers(); + try { + const bytes = new Uint8Array([1, 2, 3, 4]); + let pulls = 0; + const source = await openDownload( + bytes, + (controller) => { + pulls += 1; + if (pulls === 1) controller.enqueue(bytes.slice(0, 2)); + // Then the connection stalls: no more chunks, no close. + return pulls === 1 ? undefined : new Promise(() => {}); + }, + { minTransferBytesPerSecond: 1, idleTimeoutMs: 2_000 }, + ); + let settled = false; + const pending = collect(source).finally(() => { + settled = true; + }); + await vi.advanceTimersByTimeAsync(1_900); + expect(settled).toBe(false); + await vi.advanceTimersByTimeAsync(200); + expect(settled).toBe(true); + + expect((await pending).at(-1)).toMatchObject({ + ok: false, + error: { code: "UNAVAILABLE", recovery: "REISSUE_CAPABILITY" }, + }); + } finally { + vi.useRealTimers(); + } + }); + + it("extends a PUT deadline by the part's byte allowance", async () => { + vi.useFakeTimers(); + try { + const original = new Uint8Array(60).fill(7); + const checksum = sha256Hex(original); + const payload = uploadCapabilityPayload({ bytes: original, checksum }); + const fetcher = vi.fn(async (input: RequestInfo | URL) => { + if (String(input) === CONTROL_ENDPOINT) return jsonResponse(payload); + // 30 ms past the 5 s base deadline; 60 bytes at 1000 B/s allow 60 ms. + await new Promise((resolve) => setTimeout(resolve, 5_030)); + return responseWithUrl( + new Response(null, { + status: 200, + headers: { + [POLICY_HEADER]: "v1", + "Content-Length": "0", + ETag: "\"part-etag-slow\"", + }, + }), + String(payload.href), + ); + }) as unknown as typeof fetch; + const { provider, executor } = createHarness({ + fetcher, + minTransferBytesPerSecond: 1_000, + digestBytes: async (bytes) => sha256Hex(bytes), + }); + const issued = await provider.issueUploadPart({ + sessionId: UPLOAD_SESSION_ID, + requestBindingSha256: REQUEST_BINDING_SHA256, + uploadBindingSha256: "b".repeat(64), + partNumber: 1, + offset: 0, + byteLength: original.byteLength, + checksumSha256: checksum, + mediaType: "application/octet-stream", + idempotencyKey: "part-attempt-1", + signal: new AbortController().signal, + }); + if (!issued.ok) throw new Error("issue failed"); + const pending = executor.uploadParts.put({ + capability: issued.value, + sessionId: UPLOAD_SESSION_ID, + requestBindingSha256: REQUEST_BINDING_SHA256, + uploadBindingSha256: "b".repeat(64), + partNumber: 1, + offset: 0, + byteLength: original.byteLength, + checksumSha256: checksum, + idempotencyKey: "part-attempt-1", + bytes: original, + signal: new AbortController().signal, + }); + await vi.advanceTimersByTimeAsync(5_040); + + expect(await pending).toMatchObject({ + ok: true, + value: { receiptToken: "part-etag-slow" }, + }); + } finally { + vi.useRealTimers(); + } + }); +}); diff --git a/tests/unit/presigned-transfer-fixture.ts b/tests/unit/presigned-transfer-fixture.ts index 1fd63a81..5ebc87eb 100644 --- a/tests/unit/presigned-transfer-fixture.ts +++ b/tests/unit/presigned-transfer-fixture.ts @@ -158,6 +158,8 @@ export function createHarness(input: Readonly<{ now?: () => number; digestBytes?: PresignedTransferExecutorOptions["digestBytes"]; scheduler?: PresignedTransferExecutorOptions["scheduler"]; + minTransferBytesPerSecond?: number; + idleTimeoutMs?: number; observer?: Readonly<{ record(observation: BrowserDataObservation): void; }>; @@ -207,6 +209,12 @@ export function createHarness(input: Readonly<{ scheduler: input.scheduler, digestBytes: input.digestBytes, observer: input.observer, + ...(input.minTransferBytesPerSecond === undefined + ? {} + : { minTransferBytesPerSecond: input.minTransferBytesPerSecond }), + ...(input.idleTimeoutMs === undefined + ? {} + : { idleTimeoutMs: input.idleTimeoutMs }), }); return { provider, executor, vault }; } diff --git a/tests/unit/resumable-upload-runtime-recovery.test.ts b/tests/unit/resumable-upload-runtime-recovery.test.ts index 0461914a..d27e028a 100644 --- a/tests/unit/resumable-upload-runtime-recovery.test.ts +++ b/tests/unit/resumable-upload-runtime-recovery.test.ts @@ -599,3 +599,106 @@ describe("resumable upload completed-result reporting (01-02)", () => { expect(checkpoints.rows.size).toBe(0); }); }); + +describe("resumable upload part time limit (01-03)", () => { + const FIVE_MIB = 5 * 1024 * 1024; + + /** A part PUT that ends after `durationMs`, or never when it is null. */ + function timedExecutor( + harness: ReturnType, + durationMs: number | null, + ) { + let markStarted: () => void = () => {}; + const started = new Promise((resolve) => { + markStarted = resolve; + }); + let attempts = 0; + const executor: UploadPartExecutor = { + async uploadPart(input) { + attempts += 1; + markStarted(); + const finished = await new Promise((resolve) => { + const timer = + durationMs === null + ? undefined + : setTimeout(() => resolve(true), durationMs); + input.signal.addEventListener("abort", () => { + clearTimeout(timer); + resolve(false); + }); + }); + if (!finished) return browserDataFailure("ABORTED", "PRESIGNED_TRANSFER"); + const receipt = Object.freeze({ ...input.part, receiptToken: "etag-slow" }); + harness.accepted.set(input.part.partNumber, receipt); + return browserDataSuccess(receipt); + }, + }; + return { executor, started, attempts: () => attempts }; + } + + function defaultPolicyRuntime( + harness: ReturnType, + executor: UploadPartExecutor, + ) { + return createResumableUploadRuntime({ + controlPlane: harness.control, + partExecutor: executor, + checkpoints: new MemoryCheckpointStore(), + mutationLock: noContentionLock, + crypto, + // Default part size, attempt deadline and throughput floor. + policy: { capabilityRefreshSkewMs: 5, maxRetries: 0 }, + now: () => 1_000, + sleep: async () => {}, + }); + } + + it("lets a 5 MiB part finish at 1 Mbit/s under the default policy", async () => { + vi.useFakeTimers(); + try { + const harness = createControlHarness({ serverMaxConcurrency: 1 }); + // 5 MiB at 1 Mbit/s is about 42 s, past the 30 s base deadline. + const slow = timedExecutor(harness, 42_000); + const pending = defaultPolicyRuntime(harness, slow.executor).upload({ + ...request("upload_key_slow_uplink"), + source: rangeSource(new Uint8Array(FIVE_MIB)), + }); + await slow.started; + await vi.advanceTimersByTimeAsync(43_000); + + expect(await pending).toMatchObject({ ok: true }); + expect(slow.attempts()).toBe(1); + } finally { + vi.useRealTimers(); + } + }); + + it("ends a stalled 5 MiB part at the base deadline plus its byte allowance", async () => { + vi.useFakeTimers(); + try { + const harness = createControlHarness({ serverMaxConcurrency: 1 }); + const stalled = timedExecutor(harness, null); + let settled = false; + const pending = defaultPolicyRuntime(harness, stalled.executor) + .upload({ + ...request("upload_key_stalled_uplink"), + source: rangeSource(new Uint8Array(FIVE_MIB)), + }) + .finally(() => { + settled = true; + }); + await stalled.started; + // 30 s base + 5 MiB at the default 64 KiB/s floor (80 s). + await vi.advanceTimersByTimeAsync(109_000); + expect(settled).toBe(false); + await vi.advanceTimersByTimeAsync(2_000); + + expect(await pending).toMatchObject({ + ok: false, + error: { code: "UNAVAILABLE", operation: "UPLOAD_PART", retryable: true }, + }); + } finally { + vi.useRealTimers(); + } + }); +}); From 9cae587aea2ed385b637b9f75f8c407fe321939a Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 22:18:00 +0900 Subject: [PATCH 023/185] test(storage): make the memory IndexedDB fake serialize, expire and separate like a browser (05-08) The fake let overlapping readwrite transactions overwrite each other, took requests after the transaction's task ended and shared rows across database names, so adapter tests could pass on behavior no browser has. It now keeps one database per name, runs overlapping transactions in order, throws TransactionInactiveError for late requests, and its header lists what it still does not model. Co-Authored-By: Claude Opus 5.5 --- tests/helpers/memory-indexeddb.ts | 263 ++++++++++++++----- tests/unit/memory-indexeddb-fidelity.test.ts | 120 +++++++++ 2 files changed, 322 insertions(+), 61 deletions(-) create mode 100644 tests/unit/memory-indexeddb-fidelity.test.ts diff --git a/tests/helpers/memory-indexeddb.ts b/tests/helpers/memory-indexeddb.ts index 50238e7a..7eae6491 100644 --- a/tests/helpers/memory-indexeddb.ts +++ b/tests/helpers/memory-indexeddb.ts @@ -24,6 +24,27 @@ type StoreState = { indexes: Map; }; +/** One named database: its schema, rows and version. */ +type DatabaseState = { + stores: Map; + version: number; + latest: FakeDatabase | null; + /** Transactions that have not finished, in creation order. */ + transactions: FakeTransaction[]; +}; + +function storeOf(state: DatabaseState, name: string): StoreState { + const store = state.stores.get(name); + if (!store) { + throw new DOMException("Store does not exist.", "NotFoundError"); + } + return store; +} + +// The fake decides when a transaction's task has ended with a real macrotask, +// so a test that fakes timers cannot keep a transaction alive by accident. +const realSetTimeout = globalThis.setTimeout.bind(globalThis); + type FakeKeyRange = | Readonly<{ fakeKind: "ONLY"; @@ -221,23 +242,26 @@ class FakeDatabase { onversionchange: ((event: IDBVersionChangeEvent) => unknown) | null = null; onclose: ((event: Event) => unknown) | null = null; - constructor(private readonly owner: MemoryIndexedDbFactory) {} + constructor( + private readonly owner: MemoryIndexedDbFactory, + readonly state: DatabaseState, + ) {} get objectStoreNames(): DOMStringList { - return stringList(this.owner.storeNames()); + return stringList(this.state.stores.keys()); } createObjectStore( name: string, options?: IDBObjectStoreParameters, ): IDBObjectStore { - if (this.owner.hasStore(name)) { + if (this.state.stores.has(name)) { throw new DOMException("Store already exists.", "ConstraintError"); } if (typeof options?.keyPath !== "string") { throw new DOMException("The fake requires a string key path.", "DataError"); } - this.owner.createStore(name, { + this.state.stores.set(name, { keyPath: options.keyPath, autoIncrement: options.autoIncrement ?? false, data: new Map(), @@ -247,13 +271,13 @@ class FakeDatabase { } deleteObjectStore(name: string): void { - if (!this.owner.deleteStore(name)) { + if (!this.state.stores.delete(name)) { throw new DOMException("Store does not exist.", "NotFoundError"); } } schemaObjectStore(name: string): IDBObjectStore { - const state = this.owner.store(name); + const state = storeOf(this.state, name); return new FakeObjectStore(null, state) as unknown as IDBObjectStore; } @@ -261,7 +285,7 @@ class FakeDatabase { name: string, transaction: FakeUpgradeTransaction, ): IDBObjectStore { - const state = this.owner.store(name); + const state = storeOf(this.state, name); return new FakeObjectStore( null, state, @@ -278,7 +302,12 @@ class FakeDatabase { } const names = typeof storeNames === "string" ? [storeNames] : [...storeNames]; - const transaction = new FakeTransaction(this.owner, names, mode); + const transaction = new FakeTransaction( + this.owner, + this.state, + names, + mode, + ); this.owner.noteTransaction(transaction); return transaction as unknown as IDBTransaction; } @@ -307,19 +336,108 @@ class FakeTransaction { error: DOMException | null = null; readonly mode: IDBTransactionMode; private active = true; + /** + * Native "active" state: a request may be placed only in the task that + * created the transaction or while one of its request events (and the + * microtasks that event queued) is being handled. + */ + private accepting = true; + /** Held back until every earlier overlapping transaction finishes. */ + private started = false; + private readonly deferred: Array<() => void> = []; private completionQueued = false; private pending = 0; private readonly workingStores: Map; constructor( private readonly owner: MemoryIndexedDbFactory, + private readonly database: DatabaseState, private readonly names: readonly string[], mode: IDBTransactionMode, ) { this.mode = mode; this.workingStores = new Map( - names.map((name) => [name, cloneStore(owner.store(name))]), + names.map((name) => [name, cloneStore(storeOf(database, name))]), ); + database.transactions.push(this); + this.startIfUnblocked(); + this.deactivateAfterTask(); + } + + /** + * Native IndexedDB runs transactions with overlapping scopes in creation + * order unless both are readonly. A later one starts from the rows the + * earlier one committed. + */ + startIfUnblocked(): void { + if (this.started || !this.active) return; + const earlier = this.database.transactions.slice( + 0, + this.database.transactions.indexOf(this), + ); + if (earlier.some((transaction) => transaction.blocks(this))) return; + this.started = true; + for (const name of this.names) { + const fresh = cloneStore(storeOf(this.database, name)); + const working = this.workingStores.get(name)!; + working.data = fresh.data; + working.indexes = fresh.indexes; + } + for (const callback of this.deferred.splice(0)) { + this.owner.scheduleTransaction(callback, this.mode); + } + if (!this.accepting) this.commitIfIdle(); + } + + private blocks(later: FakeTransaction): boolean { + return ( + this.active && + (this.mode === "readwrite" || later.mode === "readwrite") && + this.names.some((name) => later.names.includes(name)) + ); + } + + private schedule(callback: () => void): void { + if (this.started) { + this.owner.scheduleTransaction(callback, this.mode); + } else { + this.deferred.push(callback); + } + } + + private deactivateAfterTask(): void { + realSetTimeout(() => { + this.accepting = false; + this.commitIfIdle(); + }, 0); + } + + /** A native transaction with no request left commits once inactive. */ + private commitIfIdle(): void { + if (this.started && this.pending === 0) this.queueCompletion(); + } + + private assertAccepting(): void { + if (!this.active || !this.accepting) { + throw new DOMException( + "The transaction is not active.", + "TransactionInactiveError", + ); + } + } + + private dispatch(handler: () => void): void { + this.accepting = true; + handler(); + this.deactivateAfterTask(); + } + + private finish(): void { + const index = this.database.transactions.indexOf(this); + if (index >= 0) this.database.transactions.splice(index, 1); + for (const transaction of [...this.database.transactions]) { + transaction.startIfUnblocked(); + } } objectStore(name: string): IDBObjectStore { @@ -341,22 +459,23 @@ class FakeTransaction { } request(operation: () => Value): IDBRequest { + this.assertAccepting(); const request = createRequest(); this.pending += 1; - this.owner.scheduleTransaction(() => { + this.schedule(() => { if (!this.active) return; try { request.result = structuredClone(operation()); - request.onsuccess?.(new Event("success")); + this.dispatch(() => request.onsuccess?.(new Event("success"))); } catch (error) { request.error = asException(error); - request.onerror?.(new Event("error")); + this.dispatch(() => request.onerror?.(new Event("error"))); this.abortWith(request.error); } if (!this.active) return; this.pending -= 1; this.queueCompletion(); - }, this.mode); + }); return request as unknown as IDBRequest; } @@ -368,12 +487,13 @@ class FakeTransaction { }>[], direction: IDBCursorDirection, ): IDBRequest { + this.assertAccepting(); const request = createRequest(); let position = 0; this.pending += 1; const emit = () => { - this.owner.scheduleTransaction(() => { + this.schedule(() => { if (!this.active) return; let continued = false; let eventReturned = false; @@ -445,12 +565,12 @@ class FakeTransaction { }, } as unknown as IDBCursorWithValue; } - request.onsuccess?.(new Event("success")); + this.dispatch(() => request.onsuccess?.(new Event("success"))); eventReturned = true; if (continued || !this.active) return; this.pending -= 1; this.queueCompletion(); - }, this.mode); + }); }; emit(); @@ -472,7 +592,7 @@ class FakeTransaction { return; } this.completionQueued = true; - this.owner.scheduleTransaction(() => { + this.schedule(() => { this.completionQueued = false; if (!this.active || this.pending !== 0) return; const commitFailure = @@ -485,18 +605,20 @@ class FakeTransaction { } if (this.mode === "readwrite") { for (const [name, state] of this.workingStores) { - this.owner.replaceStore(name, cloneStore(state)); + this.database.stores.set(name, cloneStore(state)); } } this.active = false; + this.finish(); this.oncomplete?.(new Event("complete")); - }, this.mode); + }); } private abortWith(error: DOMException): void { if (!this.active) return; this.active = false; this.error = error; + this.finish(); this.owner.scheduleLifecycle(() => { this.onerror?.(new Event("error")); this.onabort?.(new Event("abort")); @@ -721,14 +843,36 @@ class FakeIndex { } /** - * Minimal deterministic IndexedDB model for adapter contract tests. It models - * request ordering, transaction-level commit/rollback and upgrade blocking; - * it is not intended to polyfill IndexedDB for application code. + * Minimal deterministic IndexedDB model for adapter contract tests. It is not + * intended to polyfill IndexedDB for application code. + * + * Modeled like a browser: + * - request ordering and transaction-level commit/rollback; + * - one database per name (`open(name)`), so two names never share rows; + * - transactions with overlapping scopes run one after another unless both + * are readonly, and a later one sees what the earlier one committed; + * - a request placed after the transaction's task ended, outside a request + * event and its microtasks, throws `TransactionInactiveError`, and a + * transaction with nothing left to do commits on its own; + * - upgrade blocking, through `blockNextOpen`/`releaseBlockedOpen`. + * + * Not modeled (05-08) — use a browser capability spec for these: + * - key comparison is by `String`/JSON, and a compound (array) index key path + * is not read, so such an index orders by primary key; + * - opening a higher version does not fire `versionchange` on open + * connections, and `onblocked` fires only for `blockNextOpen`; tests drive + * `triggerVersionChange` by hand; + * - the upgrade transaction ends synchronously, so an abort requested from an + * asynchronous step inside `onupgradeneeded` is not rolled back; + * - quota: writes never fail for lack of space unless a test injects it with + * `failNextWriteCommit`. + * + * `seed`, `readRaw` and the lifecycle triggers act on the database opened + * most recently. */ export class MemoryIndexedDbFactory { - private stores = new Map(); - private databaseVersion = 0; - private latestDatabase = new FakeDatabase(this); + private readonly databases = new Map(); + private current: DatabaseState = this.databaseNamed(""); private blockedRequest: Readonly<{ request: MutableOpenRequest; targetVersion: number; @@ -741,8 +885,8 @@ export class MemoryIndexedDbFactory { lastTransaction: FakeTransaction | null = null; readonly factory: IDBFactory = { - open: (_name: string, version?: number) => - this.open(version ?? 1) as unknown as IDBOpenDBRequest, + open: (name: string, version?: number) => + this.open(name, version ?? 1) as unknown as IDBOpenDBRequest, cmp: compareKeys, } as IDBFactory; @@ -782,10 +926,12 @@ export class MemoryIndexedDbFactory { }) as unknown as IDBKeyRange, }; - open(version: number): MutableOpenRequest { - const database = new FakeDatabase(this); - database.version = this.databaseVersion; - this.latestDatabase = database; + open(name: string, version: number): MutableOpenRequest { + const state = this.databaseNamed(name); + const database = new FakeDatabase(this, state); + database.version = state.version; + state.latest = database; + this.current = state; const request: MutableOpenRequest = { ...createRequest(), result: database as unknown as IDBDatabase, @@ -802,7 +948,7 @@ export class MemoryIndexedDbFactory { database, }; request.onblocked?.({ - oldVersion: this.databaseVersion, + oldVersion: state.version, newVersion: version, } as IDBVersionChangeEvent); return; @@ -848,25 +994,25 @@ export class MemoryIndexedDbFactory { } triggerVersionChange(newVersion: number): void { - this.latestDatabase.fireVersionChange(newVersion); + this.current.latest?.fireVersionChange(newVersion); } triggerForcedClose(): void { - this.latestDatabase.fireForcedClose(); + this.current.latest?.fireForcedClose(); } isConnectionClosed(): boolean { - return this.latestDatabase.closed; + return this.current.latest?.closed ?? true; } seed(storeName: string, value: unknown): void { - const state = this.store(storeName); + const state = storeOf(this.current, storeName); const key = primaryKey(state, value); state.data.set(key, structuredClone(value)); } readRaw(storeName: string, key: string): unknown { - const value = this.store(storeName).data.get(key); + const value = storeOf(this.current, storeName).data.get(key); return value === undefined ? undefined : structuredClone(value); } @@ -896,39 +1042,34 @@ export class MemoryIndexedDbFactory { } storeNames(): Iterable { - return this.stores.keys(); + return this.current.stores.keys(); } hasStore(name: string): boolean { - return this.stores.has(name); + return this.current.stores.has(name); } - store(name: string): StoreState { - const state = this.stores.get(name); + private databaseNamed(name: string): DatabaseState { + let state = this.databases.get(name); if (!state) { - throw new DOMException("Store does not exist.", "NotFoundError"); + state = { + stores: new Map(), + version: 0, + latest: null, + transactions: [], + }; + this.databases.set(name, state); } return state; } - createStore(name: string, state: StoreState): void { - this.stores.set(name, state); - } - - replaceStore(name: string, state: StoreState): void { - this.stores.set(name, state); - } - - deleteStore(name: string): boolean { - return this.stores.delete(name); - } - private finishOpen( request: MutableOpenRequest, targetVersion: number, database: FakeDatabase, ): void { - if (targetVersion < this.databaseVersion) { + const state = database.state; + if (targetVersion < state.version) { request.error = new DOMException( "Requested version is older.", "VersionError", @@ -936,9 +1077,9 @@ export class MemoryIndexedDbFactory { request.onerror?.(new Event("error")); return; } - if (targetVersion > this.databaseVersion) { - const before = cloneStores(this.stores); - const oldVersion = this.databaseVersion; + if (targetVersion > state.version) { + const before = cloneStores(state.stores); + const oldVersion = state.version; const upgrade = new FakeUpgradeTransaction(database); request.transaction = upgrade as unknown as IDBTransaction; database.version = targetVersion; @@ -948,7 +1089,7 @@ export class MemoryIndexedDbFactory { } as IDBVersionChangeEvent); request.transaction = null; if (upgrade.aborted) { - this.stores = before; + state.stores = before; database.version = oldVersion; request.error = new DOMException( "Upgrade transaction aborted.", @@ -957,9 +1098,9 @@ export class MemoryIndexedDbFactory { request.onerror?.(new Event("error")); return; } - this.databaseVersion = targetVersion; + state.version = targetVersion; } - database.version = this.databaseVersion; + database.version = state.version; request.result = database as unknown as IDBDatabase; request.onsuccess?.(new Event("success")); } diff --git a/tests/unit/memory-indexeddb-fidelity.test.ts b/tests/unit/memory-indexeddb-fidelity.test.ts new file mode 100644 index 00000000..ad5dc91e --- /dev/null +++ b/tests/unit/memory-indexeddb-fidelity.test.ts @@ -0,0 +1,120 @@ +import { describe, expect, it } from "vitest"; + +import { MemoryIndexedDbFactory } from "../helpers/memory-indexeddb.ts"; + +/** + * 05-08. Where the fake used to part from native IndexedDB, each case pins + * the native result, so a test built on the fake cannot pass on a behavior no + * browser has. + */ + +function settle(request: IDBRequest): Promise { + return new Promise((resolve, reject) => { + request.onsuccess = () => resolve(request.result); + request.onerror = () => reject(request.error); + }); +} + +function outcome(transaction: IDBTransaction): Promise { + return new Promise((resolve) => { + transaction.oncomplete = () => resolve("complete"); + transaction.onabort = () => + resolve(`abort:${transaction.error?.name ?? "none"}`); + }); +} + +async function openWithStore( + memory: MemoryIndexedDbFactory, + name: string, +): Promise { + const request = memory.factory.open(name, 1); + request.onupgradeneeded = () => { + request.result.createObjectStore("s", { keyPath: "k" }); + }; + return await settle(request); +} + +describe("05-08 memory IndexedDB matches native semantics the adapters rely on", () => { + it("(a) runs overlapping readwrite transactions one after another", async () => { + const memory = new MemoryIndexedDbFactory(); + const database = await openWithStore(memory, "a"); + memory.seed("s", { k: "counter", n: 0 }); + const first = database.transaction(["s"], "readwrite"); + const second = database.transaction(["s"], "readwrite"); + const settled = [outcome(first), outcome(second)]; + for (const transaction of [first, second]) { + const read = transaction.objectStore("s").get("counter"); + read.onsuccess = () => { + const { n } = read.result as { n: number }; + transaction.objectStore("s").put({ k: "counter", n: n + 1 }); + }; + } + + expect(await Promise.all(settled)).toEqual(["complete", "complete"]); + expect(memory.readRaw("s", "counter")).toEqual({ k: "counter", n: 2 }); + }); + + it("(b) rejects a request placed after the transaction's task ended", async () => { + const memory = new MemoryIndexedDbFactory(); + const database = await openWithStore(memory, "b"); + const transaction = database.transaction(["s"], "readwrite"); + const settled = outcome(transaction); + await new Promise((resolve) => setTimeout(resolve, 5)); + + expect(() => + transaction.objectStore("s").put({ k: "late" }), + ).toThrow(expect.objectContaining({ name: "TransactionInactiveError" })); + // A transaction with no request left commits on its own. + expect(await settled).toBe("complete"); + expect(memory.readRaw("s", "late")).toBeUndefined(); + }); + + it("(b) keeps a transaction active for requests placed in a success callback's microtasks", async () => { + const memory = new MemoryIndexedDbFactory(); + const database = await openWithStore(memory, "b2"); + const transaction = database.transaction(["s"], "readwrite"); + const settled = outcome(transaction); + const read = transaction.objectStore("s").get("absent"); + read.onsuccess = () => { + void Promise.resolve().then(() => { + transaction.objectStore("s").put({ k: "chained" }); + }); + }; + + expect(await settled).toBe("complete"); + expect(memory.readRaw("s", "chained")).toEqual({ k: "chained" }); + }); + + it("(d) keeps databases of different names apart", async () => { + const memory = new MemoryIndexedDbFactory(); + const userA = await openWithStore(memory, "user-A"); + await settle( + userA.transaction(["s"], "readwrite").objectStore("s").put({ + k: "secret-of-A", + }), + ); + let upgraded = false; + const request = memory.factory.open("user-B", 1); + request.onupgradeneeded = () => { + upgraded = true; + request.result.createObjectStore("s", { keyPath: "k" }); + }; + const userB = await settle(request); + + expect(upgraded).toBe(true); + expect( + await settle( + userB.transaction(["s"], "readonly").objectStore("s").get( + "secret-of-A", + ), + ), + ).toBeUndefined(); + expect( + await settle( + userA.transaction(["s"], "readonly").objectStore("s").get( + "secret-of-A", + ), + ), + ).toEqual({ k: "secret-of-A" }); + }); +}); From 1b38659fce2246fd5c53e056c5691a688bfdeff2 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 22:22:15 +0900 Subject: [PATCH 024/185] fix(features): keep local-draft off the removable storage runtime (00-02) The two local-draft adapters imported the IndexedDB port that the browser file/storage removal deletes, so that removal gate failed. The feature now declares the repository slice it calls and receives it through the indexedDb capability; the runtime satisfies it structurally. Co-Authored-By: Claude Opus 5.5 --- .../create-local-draft-feature-input.ts | 13 +++-- .../adapters/local-draft-indexeddb-store.ts | 48 +++++++++++++++---- 2 files changed, 46 insertions(+), 15 deletions(-) diff --git a/src/features/local-draft-feature/adapters/create-local-draft-feature-input.ts b/src/features/local-draft-feature/adapters/create-local-draft-feature-input.ts index 93b62d1e..9b7461cc 100644 --- a/src/features/local-draft-feature/adapters/create-local-draft-feature-input.ts +++ b/src/features/local-draft-feature/adapters/create-local-draft-feature-input.ts @@ -1,6 +1,3 @@ -import type { - IndexedDbRepositoryPort, -} from "../../../application/ports/browser-file-storage/index.ts"; import { defineFeatureAdapterContribution, } from "../../feature-adapter-contribution.ts"; @@ -8,22 +5,24 @@ import type {} from "../../feature-adapter-contribution.ts"; import { createLocalDraftFeatureInput, } from "../application/local-draft-api.ts"; -import type { LocalDraft } from "../domain/local-draft.ts"; import { LOCAL_DRAFT_FEATURE_ID, LOCAL_DRAFT_REPOSITORY_ID, } from "../contracts/local-draft-contract.ts"; -import { createLocalDraftStore } from "./local-draft-indexeddb-store.ts"; +import { + createLocalDraftStore, + type LocalDraftRepository, +} from "./local-draft-indexeddb-store.ts"; declare module "../../feature-adapter-contribution.ts" { interface FeatureIndexedDbRepositories { - "local-draft": IndexedDbRepositoryPort; + "local-draft": LocalDraftRepository; } } export function createLocalDraftFeatureInstalledInput(context: Readonly<{ indexedDb: Readonly<{ - get(repositoryId: "local-draft"): IndexedDbRepositoryPort; + get(repositoryId: "local-draft"): LocalDraftRepository; }>; }>) { const repository = context.indexedDb.get(LOCAL_DRAFT_REPOSITORY_ID); diff --git a/src/features/local-draft-feature/adapters/local-draft-indexeddb-store.ts b/src/features/local-draft-feature/adapters/local-draft-indexeddb-store.ts index bc777beb..9f0fd0a9 100644 --- a/src/features/local-draft-feature/adapters/local-draft-indexeddb-store.ts +++ b/src/features/local-draft-feature/adapters/local-draft-indexeddb-store.ts @@ -1,7 +1,3 @@ -import type { - BrowserDataFailure, - IndexedDbRepositoryPort, -} from "../../../application/ports/browser-file-storage/index.ts"; import { createFailure, type AppFailure, @@ -16,7 +12,43 @@ import type { } from "../application/local-draft-api.ts"; import type { LocalDraft } from "../domain/local-draft.ts"; -function failureKind(failure: BrowserDataFailure): FailureKind { +type RepositoryFailure = Readonly<{ code: string }>; +type RepositoryResult = Result; + +/** + * 00-02. The part of the `indexedDb` capability this feature calls. The host + * hands in the reusable runtime (`IndexedDbRepositoryPort`), + * which satisfies this shape structurally (the recipe and the browser spec + * compile that assignment). Importing the port instead tied the feature to the + * browser storage runtime, which a product may remove. + */ +export type LocalDraftRepository = Readonly<{ + read( + key: string, + signal?: AbortSignal, + ): Promise< + RepositoryResult | null> + >; + compareAndSwap( + input: Readonly<{ + key: string; + value: LocalDraft; + expectedRevision: number | null; + idempotencyKey: string; + signal?: AbortSignal; + }>, + ): Promise>>; + remove( + input: Readonly<{ + key: string; + expectedRevision: number; + idempotencyKey: string; + signal?: AbortSignal; + }>, + ): Promise>; +}>; + +function failureKind(failure: RepositoryFailure): FailureKind { if (failure.code === "QUOTA_EXCEEDED") return "STORAGE_QUOTA_EXCEEDED"; if (failure.code === "CONFLICT") return "CONFLICT"; if (failure.code === "ABORTED") return "REQUEST_ABORTED"; @@ -24,7 +56,7 @@ function failureKind(failure: BrowserDataFailure): FailureKind { } function mapFailure( - failure: BrowserDataFailure, + failure: RepositoryFailure, operationId: string, ): AppFailure { return createFailure(failureKind(failure), operationId, 0, { @@ -33,7 +65,7 @@ function mapFailure( } function failed( - failure: BrowserDataFailure, + failure: RepositoryFailure, operationId: string, ): Result { return Object.freeze({ @@ -48,7 +80,7 @@ function failed( * cross this file. */ export function createLocalDraftStore( - repository: IndexedDbRepositoryPort, + repository: LocalDraftRepository, ): LocalDraftStore { return Object.freeze({ async save(command: SaveLocalDraftCommand, signal?: AbortSignal) { From 426b6b8eecd911abcbc51a90c07c5cecc4e07a79 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 22:22:27 +0900 Subject: [PATCH 025/185] fix(browser-transfer): map each upload() failure recovery to one caller action (01-05) ABORT_PENDING and a checkpoint CAS race returned the same failure, and some recoveries (REISSUE_CAPABILITY, RESTART for a replayed create) named actions the caller cannot take or that repeat the failure. The port now documents a five-value recovery table and upload() returns only those values. Co-Authored-By: Claude Opus 5.5 --- .../presigned-transfer-and-image-cdn.md | 12 ++ .../resumable-upload-runtime.ts | 58 ++++++- .../upload-response-validation.ts | 20 ++- .../browser-transfer/resumable-upload.ts | 19 ++ .../resumable-upload-runtime-contract.test.ts | 18 +- .../resumable-upload-runtime-recovery.test.ts | 163 ++++++++++++++++++ tests/unit/resumable-upload-runtime.test.ts | 4 +- 7 files changed, 269 insertions(+), 25 deletions(-) diff --git a/docs/architecture/presigned-transfer-and-image-cdn.md b/docs/architecture/presigned-transfer-and-image-cdn.md index 5513f8ea..d729f8e7 100644 --- a/docs/architecture/presigned-transfer-and-image-cdn.md +++ b/docs/architecture/presigned-transfer-and-image-cdn.md @@ -683,6 +683,18 @@ analytics는 제품 presentation이 소유한다. | network/429/모든 5xx | `UNAVAILABLE` | bounded retry/backoff | | complete 응답 유실·진행 중 | `UNAVAILABLE`(`UPLOAD_COMPLETE`, retryable) | 같은 파일로 `upload()` 재호출, 또는 `abort()`가 resourceId와 함께 `ALREADY_COMPLETED` 반환(4.3) | +`ResumableUploadPort.upload()` 실패의 `recovery`는 호출자가 할 행동 하나를 +가리킨다(`resumable-upload.ts` port 주석, `resumable-upload-runtime.ts` +`toUploadAction`). 이 다섯 값 밖의 값은 `upload()`에서 나오지 않는다. + +| recovery | 호출자 행동 | +| --- | --- | +| `RESUME` | 같은 파일·key로 `upload()`를 다시 부른다. `retryable:true`면 자동 재시도해도 된다. capability 재발급이 필요한 실패도 여기로 온다 | +| `RECONCILE` | `upload()`를 다시 부른다. 서버 상태를 먼저 읽는다(예: 다른 문맥이 checkpoint를 먼저 씀) | +| `RESTART` | `abort()` 뒤 `upload()`로 새 session을 연다. abort가 남아 있음(operation `UPLOAD_ABORT`), 읽을 수 없는 checkpoint 행, 서버 part가 파일과 다름 | +| `RESELECT` | 파일을 다시 고르거나, 다른 파일이면 새 key를 쓴다 | +| `NONE` | 이 요청으로 할 행동이 없다. 잘못된 입력, 상한·정책·권한 거절, 호출자 자신의 abort, 다시 불러도 같은 답이 오는 서버 응답(정책보다 긴 session 등) | + 관측성에는 operation, safe outcome, byte/part/candidate bucket, retry bucket과 failure code만 기록한다. capability ID, URL, query, asset/resource/session ID, file name, digest, raw ETag, receipt와 backend message는 log/diagnostics/telemetry에 diff --git a/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts b/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts index df7f707f..f6461efd 100644 --- a/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts +++ b/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts @@ -131,6 +131,15 @@ const RECOVERIES: ReadonlySet = new Set([ "RECONCILE", ]); +/** 01-05. The recoveries `ResumableUploadPort.upload()` documents. */ +const UPLOAD_ACTIONS: ReadonlySet = new Set([ + "RESUME", + "RECONCILE", + "RESTART", + "RESELECT", + "NONE", +]); + export function createResumableUploadRuntime( inputDependencies: ResumableUploadRuntimeDependencies, ): ResumableUploadRuntime { @@ -197,12 +206,14 @@ export function createResumableUploadRuntime( request.uploadKey, operationScope.signal, async () => - await executeUpload( - dependencies, - Object.freeze({ - ...request, - signal: operationScope.signal, - }), + toUploadAction( + await executeUpload( + dependencies, + Object.freeze({ + ...request, + signal: operationScope.signal, + }), + ), ), ); // Tracked until terminal settlement so dispose() can prove quiescence. @@ -375,7 +386,14 @@ async function executeUpload( request.uploadKey, request.signal, ); - if (!stored.ok) return remapResult(stored, "UPLOAD_RECONCILE"); + if (!stored.ok) { + // 01-05. A row this build cannot read is cleared only by `abort()`. + return stored.error.code === "CORRUPT_DATA" + ? browserDataFailure("CORRUPT_DATA", "UPLOAD_RECONCILE", { + recovery: "RESTART", + }) + : remapResult(stored, "UPLOAD_RECONCILE"); + } if ( stored.value && (!sameFingerprint( @@ -389,8 +407,10 @@ async function executeUpload( }); } if (stored.value?.state === "ABORT_PENDING") { - return browserDataFailure("CONFLICT", "UPLOAD_RECONCILE", { - recovery: "RECONCILE", + // 01-05. Only `abort()` finishes a pending abort; this must not look like + // a checkpoint write race, which `upload()` itself resolves. + return browserDataFailure("CONFLICT", "UPLOAD_ABORT", { + recovery: "RESTART", }); } @@ -1676,6 +1696,26 @@ function reportProgress( } } +/** + * 01-05. `upload()` failures carry only the recoveries the port documents as + * caller actions. Provider vocabulary the caller cannot act on itself (a + * capability to reissue, a request to retry) means "call `upload()` again"; + * anything else outside the table has no caller action. + */ +function toUploadAction( + result: BrowserDataResult, +): BrowserDataResult { + if (result.ok || UPLOAD_ACTIONS.has(result.error.recovery)) return result; + return browserDataFailure(result.error.code, result.error.operation, { + retryable: result.error.retryable, + recovery: + result.error.recovery === "REISSUE_CAPABILITY" || + result.error.recovery === "RETRY" + ? "RESUME" + : "NONE", + }); +} + function mapLockFailure( error: unknown, operation: BrowserDataOperation, diff --git a/src/adapters/browser-transfer/resumable-upload/upload-response-validation.ts b/src/adapters/browser-transfer/resumable-upload/upload-response-validation.ts index 8cd48536..39cc537a 100644 --- a/src/adapters/browser-transfer/resumable-upload/upload-response-validation.ts +++ b/src/adapters/browser-transfer/resumable-upload/upload-response-validation.ts @@ -110,7 +110,7 @@ export function validateStatus( return browserDataFailure( "INTEGRITY_FAILED", "UPLOAD_RECONCILE", - { recovery: "RECONCILE" }, + { recovery: "RESTART" }, ); } const receipts = validateServerReceipts( @@ -153,7 +153,7 @@ export function validateStatus( return browserDataFailure( "INTEGRITY_FAILED", "UPLOAD_RECONCILE", - { recovery: "RECONCILE" }, + { recovery: "RESTART" }, ); } return browserDataSuccess( @@ -177,7 +177,7 @@ export function validateStatus( value.requestBindingSha256 !== checkpoint.requestBindingSha256 ) { return browserDataFailure("INTEGRITY_FAILED", "UPLOAD_RECONCILE", { - recovery: "RECONCILE", + recovery: "RESTART", }); } return browserDataSuccess( @@ -221,18 +221,22 @@ export function validateSession( value.maxConcurrency > dependencies.policy.maxConcurrency || !Number.isSafeInteger(value.expiresAtEpochMs) ) { + // 01-05. A create is replayed under the same key, so neither calling + // `upload()` again nor restarting changes what the server answers. return browserDataFailure("INTEGRITY_FAILED", "UPLOAD_SESSION", { - recovery: "RECONCILE", + recovery: "NONE", }); } const now = safeNow(dependencies, "UPLOAD_SESSION"); if (!now.ok) return now; if ( requireActiveExpiry && - (value.expiresAtEpochMs <= now.value || - value.expiresAtEpochMs - now.value > - dependencies.policy.maxSessionLifetimeMs) + value.expiresAtEpochMs - now.value > + dependencies.policy.maxSessionLifetimeMs ) { + return browserDataFailure("POLICY_REJECTED", "UPLOAD_SESSION"); + } + if (requireActiveExpiry && value.expiresAtEpochMs <= now.value) { return browserDataFailure("EXPIRED_RESOURCE", "UPLOAD_SESSION", { recovery: "RESTART", }); @@ -266,7 +270,7 @@ function validateServerReceipts( !verifyPartAgainstManifest(receipt, manifest) ) { return browserDataFailure("INTEGRITY_FAILED", operation, { - recovery: "RECONCILE", + recovery: "RESTART", }); } previousPart = receipt.partNumber; diff --git a/src/application/ports/browser-transfer/resumable-upload.ts b/src/application/ports/browser-transfer/resumable-upload.ts index 9e9bf207..9310b323 100644 --- a/src/application/ports/browser-transfer/resumable-upload.ts +++ b/src/application/ports/browser-transfer/resumable-upload.ts @@ -101,6 +101,25 @@ export type UploadAbortOutcome = Readonly<{ }>; export interface ResumableUploadPort { + /** + * 01-05. A failure's `recovery` names exactly one caller action: + * + * | recovery | caller action | + * | ----------- | ---------------------------------------------------------- | + * | `RESUME` | Call `upload()` again with the same file and key. With | + * | | `retryable: true` it may be retried automatically. | + * | `RECONCILE` | Call `upload()` again; it reads the server state first. | + * | `RESTART` | Call `abort()`, then `upload()` for a fresh session: an | + * | | abort is pending (operation `UPLOAD_ABORT`), the stored | + * | | row is unreadable, or the server's parts disagree with the | + * | | file. | + * | `RESELECT` | Select the file again, or use a new key for another file. | + * | `NONE` | No action on this request: invalid input, a limit, a | + * | | policy or permission refusal, the caller's own abort, or | + * | | a server answer that a new call would only replay. | + * + * No other recovery value is returned from `upload()`. + */ upload( request: ResumableUploadRequest, ): Promise>; diff --git a/tests/unit/resumable-upload-runtime-contract.test.ts b/tests/unit/resumable-upload-runtime-contract.test.ts index 8d20d545..917f279b 100644 --- a/tests/unit/resumable-upload-runtime-contract.test.ts +++ b/tests/unit/resumable-upload-runtime-contract.test.ts @@ -238,7 +238,8 @@ describe("resumable upload runtime server response validation", () => { error: { code: "INTEGRITY_FAILED", operation: "UPLOAD_SESSION", - recovery: "RECONCILE", + // 01-05. The create key replays the same answer. + recovery: "NONE", }, }); }); @@ -251,7 +252,7 @@ describe("resumable upload runtime server response validation", () => { }); }); - it("restarts a session whose lifetime exceeds the policy ceiling", async () => { + it("refuses a session whose lifetime exceeds the policy ceiling", async () => { const harness = createControlHarness(); const create = harness.control.createSession.bind(harness.control); harness.control.createSession = async (input) => { @@ -265,10 +266,12 @@ describe("resumable upload runtime server response validation", () => { }; await expect(upload(dependencies(harness))).resolves.toMatchObject({ ok: false, + // 01-05. A restart gets the same session back, so there is no caller + // action; this is a server/policy mismatch. error: { - code: "EXPIRED_RESOURCE", + code: "POLICY_REJECTED", operation: "UPLOAD_SESSION", - recovery: "RESTART", + recovery: "NONE", }, }); }); @@ -285,10 +288,11 @@ describe("resumable upload runtime server response validation", () => { }); await expect(upload(dependencies(harness))).resolves.toMatchObject({ ok: false, + // 01-05. The caller's action for a capability refusal is upload(). error: { code: "CORRUPT_DATA", operation: "UPLOAD_PART", - recovery: "REISSUE_CAPABILITY", + recovery: "RESUME", }, }); }); @@ -307,7 +311,7 @@ describe("resumable upload runtime server response validation", () => { error: { code: "POLICY_REJECTED", operation: "UPLOAD_PART", - recovery: "REISSUE_CAPABILITY", + recovery: "RESUME", }, }); }); @@ -326,7 +330,7 @@ describe("resumable upload runtime server response validation", () => { error: { code: "INTEGRITY_FAILED", operation: "UPLOAD_RECONCILE", - recovery: "RECONCILE", + recovery: "RESTART", }, }); }); diff --git a/tests/unit/resumable-upload-runtime-recovery.test.ts b/tests/unit/resumable-upload-runtime-recovery.test.ts index d27e028a..66802b07 100644 --- a/tests/unit/resumable-upload-runtime-recovery.test.ts +++ b/tests/unit/resumable-upload-runtime-recovery.test.ts @@ -702,3 +702,166 @@ describe("resumable upload part time limit (01-03)", () => { } }); }); + +describe("upload() failure recovery maps to one caller action (01-05)", () => { + /** The port's recovery → action table (`ResumableUploadPort.upload`). */ + const UPLOAD_ACTIONS = new Set([ + "RESUME", + "RECONCILE", + "RESTART", + "RESELECT", + "NONE", + ]); + + function runtimeFor( + harness: ReturnType, + overrides: Partial< + Parameters>[0] + > = {}, + ) { + return createResumableUploadRuntime({ + controlPlane: harness.control, + partExecutor: executorFor(harness), + checkpoints: new MemoryCheckpointStore(), + mutationLock: noContentionLock, + crypto, + policy: runtimePolicy({ maxRetries: 0 }), + now: () => 1_000, + sleep: async () => {}, + ...overrides, + }); + } + + const scenarios = { + "an abort is still pending": async () => { + const harness = createControlHarness(); + harness.control.complete = async () => + browserDataFailure("UNAVAILABLE", "UPLOAD_COMPLETE", { + retryable: true, + recovery: "RESUME", + }); + harness.control.abort = async () => + browserDataFailure("UNAVAILABLE", "UPLOAD_ABORT", { + retryable: true, + recovery: "RESUME", + }); + const runtime = runtimeFor(harness); + const key = "upload_key_abort_pending"; + await runtime.upload(request(key)); + await runtime.abort({ uploadKey: key, signal: activeSignal }); + return await runtime.upload(request(key)); + }, + "another context wrote the checkpoint first": async () => { + const checkpoints = new MemoryCheckpointStore(); + checkpoints.compareAndSwap = async () => + browserDataFailure("CONFLICT", "UPLOAD_RECONCILE", { + recovery: "RECONCILE", + }); + return await runtimeFor(createControlHarness(), { checkpoints }).upload( + request("upload_key_cas_conflict"), + ); + }, + "the server status disagrees with the file": async () => + await runtimeFor( + createControlHarness({ + statusParts: (_session, accepted) => + [...accepted.values()].map((part) => ({ + ...part, + checksumSha256: "e".repeat(64), + })), + }), + ).upload(request("upload_key_status_mismatch")), + "the checkpoint row is unreadable": async () => { + const checkpoints = new MemoryCheckpointStore(); + checkpoints.read = async () => + browserDataFailure("CORRUPT_DATA", "UPLOAD_RECONCILE", { + recovery: "RECONCILE", + }); + return await runtimeFor(createControlHarness(), { checkpoints }).upload( + request("upload_key_unreadable"), + ); + }, + "the server session outlives the policy": async () => { + const harness = createControlHarness(); + const create = harness.control.createSession.bind(harness.control); + harness.control.createSession = async (input) => { + const created = await create(input); + return created.ok + ? browserDataSuccess({ + ...created.value, + expiresAtEpochMs: 1_000 + 20_000, + }) + : created; + }; + return await runtimeFor(harness).upload(request("upload_key_long_session")); + }, + "every PUT refuses the capability": async () => + await runtimeFor(createControlHarness(), { + partExecutor: { uploadPart: async () => putForbidden() }, + }).upload(request("upload_key_refused_put")), + "the key belongs to another file": async () => { + const checkpoints = new MemoryCheckpointStore(); + const harness = createControlHarness(); + harness.control.complete = async () => + browserDataFailure("UNAVAILABLE", "UPLOAD_COMPLETE", { + retryable: true, + recovery: "RESUME", + }); + const runtime = runtimeFor(harness, { checkpoints }); + const key = "upload_key_other_file"; + await runtime.upload(request(key)); + return await runtime.upload({ + ...request(key), + source: rangeSource(new Uint8Array([9, 9, 9, 9])), + }); + }, + } as const; + + it.each([ + ["an abort is still pending", "CONFLICT", "UPLOAD_ABORT", "RESTART"], + [ + "another context wrote the checkpoint first", + "CONFLICT", + "UPLOAD_RECONCILE", + "RECONCILE", + ], + [ + "the server status disagrees with the file", + "INTEGRITY_FAILED", + "UPLOAD_RECONCILE", + "RESTART", + ], + [ + "the checkpoint row is unreadable", + "CORRUPT_DATA", + "UPLOAD_RECONCILE", + "RESTART", + ], + [ + "the server session outlives the policy", + "POLICY_REJECTED", + "UPLOAD_SESSION", + "NONE", + ], + [ + "every PUT refuses the capability", + "PERMISSION_DENIED", + "UPLOAD_PART", + "RESUME", + ], + [ + "the key belongs to another file", + "STALE_RESULT", + "UPLOAD_RECONCILE", + "RESELECT", + ], + ] as const)("%s → %s/%s/%s", async (scenario, code, operation, recovery) => { + const result = await scenarios[scenario](); + + expect(result).toMatchObject({ + ok: false, + error: { code, operation, recovery }, + }); + if (!result.ok) expect(UPLOAD_ACTIONS.has(result.error.recovery)).toBe(true); + }); +}); diff --git a/tests/unit/resumable-upload-runtime.test.ts b/tests/unit/resumable-upload-runtime.test.ts index 015c9431..5ff8cbca 100644 --- a/tests/unit/resumable-upload-runtime.test.ts +++ b/tests/unit/resumable-upload-runtime.test.ts @@ -371,12 +371,14 @@ describe("production resumable upload runtime", () => { source: rangeSource(new Uint8Array([1, 2, 3, 4])), signal: activeSignal, }); + // 01-05. Calling upload() again reads the same server parts, so the way + // out is abort() and a fresh session. expect(result).toMatchObject({ ok: false, error: { code: "INTEGRITY_FAILED", operation: "UPLOAD_RECONCILE", - recovery: "RECONCILE", + recovery: "RESTART", }, }); expect(partExecutor.uploadPart).not.toHaveBeenCalled(); From 9894a70f04807b3ed0038f3e2ca916b69afbc4da Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 22:22:58 +0900 Subject: [PATCH 026/185] fix(forms): give sign-in, forbidden and retry-later save failures their own state (08-01) Every non-input save failure became "unavailable" under the "review the entered information" summary, with no sign-in button. useAppForm now reports reauth-required, forbidden and retry-later with the failure, and FormFailureStatus shows each one's copy and action outside ErrorSummary. Co-Authored-By: Claude Opus 5.5 --- .../decisions/VD-04-native-form-facade.md | 12 +++- .../typescript-state-and-data-flow.md | 2 + .../reference-resource-form-page.tsx | 14 +++- src/presentation/components/async-surface.tsx | 4 ++ src/presentation/design-system/index.ts | 1 + src/presentation/forms/form-components.tsx | 29 +++++++++ src/presentation/forms/form-contracts.ts | 4 ++ src/presentation/forms/use-app-form.ts | 26 ++++++++ src/presentation/i18n/catalog.ts | 4 ++ tests/component/form-foundation.test.tsx | 65 +++++++++++++++++++ .../reference-feature/reference-page.test.tsx | 55 ++++++++++++++++ .../reference-production-vertical.test.tsx | 5 +- 12 files changed, 217 insertions(+), 4 deletions(-) diff --git a/docs/architecture/decisions/VD-04-native-form-facade.md b/docs/architecture/decisions/VD-04-native-form-facade.md index 374fd20b..958581c6 100644 --- a/docs/architecture/decisions/VD-04-native-form-facade.md +++ b/docs/architecture/decisions/VD-04-native-form-facade.md @@ -18,7 +18,8 @@ field orchestration까지 플랫폼 기본값으로 고정하게 된다. 2. Zod presentation schema, application command mapper와 domain invariant는 서로 다른 소유물로 유지한다. 3. page와 feature는 `useAppForm`, `Form`, `FormField`, `ErrorSummary`, - `mapValidationFailureToFields`, `useDirtyNavigationGuard`만 사용한다. + `FormFailureStatus`, `mapValidationFailureToFields`, `useDirtyNavigationGuard`만 + 사용한다. 4. 422 details는 승인된 `path`와 `code`만 HTTP 경계에서 투영한다. backend message와 알 수 없는 field는 field에 전달하지 않고 안전한 form-level error로 이동한다. @@ -27,6 +28,15 @@ field orchestration까지 플랫폼 기본값으로 고정하게 된다. dirty 상태를 해제한다. 7. `StandardPage`, `CollectionPage`, `DetailPage`, `FormPage`, `StatusPage`는 layout과 state slot만 소유하며 application/query/HTTP를 import하지 않는다. +8. (2026-09-25, 08-01) 입력 오류가 아닌 저장 실패는 ErrorSummary에 넣지 않는다. + `useAppForm`은 `action: "reauth"`를 `reauth-required`, `FORBIDDEN`을 `forbidden`, + `action: "retry"`를 `retry-later`로 구분하고 그 실패를 `failure`로 낸다. 화면은 + `FormFailureStatus`로 문구와 행동(로그인·이동·다시 시도)을 보여 준다. 재로그인은 + 입력을 지운다는 안내를 버튼 앞에 둔다(`src/presentation/forms/use-app-form.ts`, + `form-components.tsx`). +9. (2026-09-25, 03-01) 결과 불명 저장은 사용자가 "변경되지 않음"을 판정하지 않는다. + `resendUnknown(mutation.resendUnknownEffect)`로 같은 intent·같은 + `Idempotency-Key`를 다시 보낸다(`src/presentation/adapters/query/application-query.ts`). ## React Hook Form 도입 조건 diff --git a/docs/architecture/typescript-state-and-data-flow.md b/docs/architecture/typescript-state-and-data-flow.md index 32fa998f..e0bb045a 100644 --- a/docs/architecture/typescript-state-and-data-flow.md +++ b/docs/architecture/typescript-state-and-data-flow.md @@ -597,6 +597,7 @@ Form 또는 TanStack Form adapter를 평가한다. - `Description` - `FieldError` - `ErrorSummary` +- `FormFailureStatus` (재로그인·권한 없음·잠시 후 재시도 저장 실패) - `useAppForm` - `mapValidationFailureToFields` - `useDirtyNavigationGuard` @@ -620,6 +621,7 @@ backend message와 알 수 없는 path는 field copy로 사용하지 않는다. 3. submitting 중 중복 제출 방지 4. 422 응답의 알려진 field만 표시하고 나머지는 form-level failure로 처리 5. 409 conflict는 validation error로 위장하지 않음 +5a. 401·403·429 같은 입력 외 실패는 ErrorSummary가 아니라 `FormFailureStatus`로 표시 6. 취소와 route 이탈 시 dirty policy 적용 7. form value → application command mapper를 별도 함수로 둠 8. browser autofill, IME composition, paste, password manager를 방해하지 않음 diff --git a/src/features/reference-feature/presentation/reference-resource-form-page.tsx b/src/features/reference-feature/presentation/reference-resource-form-page.tsx index d54e0eb1..80bec0f4 100644 --- a/src/features/reference-feature/presentation/reference-resource-form-page.tsx +++ b/src/features/reference-feature/presentation/reference-resource-form-page.tsx @@ -8,6 +8,7 @@ import { ErrorSummary, Form, FormActions, + FormFailureStatus, FormPage, FormField, useAppForm, @@ -21,6 +22,7 @@ import { toCreateReferenceCommand, type ReferenceResourceFormValues, } from "./reference-resource-form.ts"; +import { useReferenceFailureAction } from "./use-reference-failure-action.ts"; import { useReferenceCreate } from "./use-reference-feature.ts"; const FIELD_LABELS = Object.freeze({ @@ -44,6 +46,7 @@ export default function ReferenceResourceFormPage() { mapToCommand: toCreateReferenceCommand, submit, }); + const failureAction = useReferenceFailureAction(form.failure ?? undefined); const mutationEffectUnknown = mutation.state.indicator === "mutation-effect-unknown"; const mutationBlocked = @@ -129,7 +132,16 @@ export default function ReferenceResourceFormPage() { } feedback={ - mutationEffectUnknown ? ( + form.failure ? ( + void form.submitForm() + : failureAction + } + /> + ) : mutationEffectUnknown ? ( <> void; + /** Read before the action, inside the same alert. */ + description?: string; }>; export function TerminalErrorSurface({ userMessageKey, action, onAction, + description, }: TerminalErrorSurfaceProps) { const { locale, message } = useLocale(); const messageId = useId(); @@ -81,6 +84,7 @@ export function TerminalErrorSurface({ data-message-key={userMessageKey} >

{errorMessage(userMessageKey, locale)}

+ {description ?

{description}

: null} {action !== "none" && onAction && ( )} diff --git a/src/presentation/design-system/index.ts b/src/presentation/design-system/index.ts index 3467658e..5a519cf4 100644 --- a/src/presentation/design-system/index.ts +++ b/src/presentation/design-system/index.ts @@ -136,6 +136,7 @@ export { ErrorSummary, Form, FormActions, + FormFailureStatus, FormField, useAppForm, useDirtyNavigationGuard, diff --git a/src/presentation/forms/form-components.tsx b/src/presentation/forms/form-components.tsx index 16bc9b8e..f87d771f 100644 --- a/src/presentation/forms/form-components.tsx +++ b/src/presentation/forms/form-components.tsx @@ -1,5 +1,7 @@ import { useId, type FormHTMLAttributes, type ReactNode } from "react"; +import type { AppFailure } from "../../contracts/errors.ts"; +import { TerminalErrorSurface } from "../components/async-surface.tsx"; import { TextField } from "../components/ui/text-field.ts"; import { useLocale } from "../i18n/index.ts"; import type { @@ -78,6 +80,33 @@ export function ErrorSummary(props: Readonly<{ ); } +/** + * 08-01. A save that failed for a reason other than the input (sign-in, + * permission, retry later) is announced here with its own action, not in + * ErrorSummary. Pass `useAppForm().failure`. + */ +export function FormFailureStatus(props: Readonly<{ + failure: AppFailure | null; + onAction?: () => void; +}>) { + const { message } = useLocale(); + const { failure, onAction } = props; + if (!failure) return null; + return ( + + ); +} + export function FormActions(props: Readonly<{ children: ReactNode; sticky?: boolean; diff --git a/src/presentation/forms/form-contracts.ts b/src/presentation/forms/form-contracts.ts index cdc1581d..c432ef1b 100644 --- a/src/presentation/forms/form-contracts.ts +++ b/src/presentation/forms/form-contracts.ts @@ -19,6 +19,10 @@ export type FormResultState = | "validation-error" | "conflict" | "effect-unknown" + /** 08-01. Not input errors: shown by `FormFailureStatus`, never ErrorSummary. */ + | "reauth-required" + | "forbidden" + | "retry-later" | "unavailable"; export type MappedValidationFailure = Readonly<{ diff --git a/src/presentation/forms/use-app-form.ts b/src/presentation/forms/use-app-form.ts index a6b26482..5a4e00a8 100644 --- a/src/presentation/forms/use-app-form.ts +++ b/src/presentation/forms/use-app-form.ts @@ -9,6 +9,7 @@ import { } from "react"; import { flushSync } from "react-dom"; import type { ZodType, ZodIssue } from "zod"; +import type { AppFailure } from "../../contracts/errors.ts"; import { useLocale, type ParameterlessMessageKey, @@ -64,6 +65,7 @@ export function useAppForm< const [formErrors, setFormErrors] = useState([]); const [pending, setPending] = useState(false); const [result, setResult] = useState("idle"); + const [statusFailure, setStatusFailure] = useState(null); const pendingRef = useRef | null> | null>(null); const unknownSubmissionRef = useRef(null); @@ -192,6 +194,12 @@ export function useAppForm< setFormErrors(mapped.formErrors); setResult("validation-error"); focusFirstError(mapped.fieldErrors); + } else if (outcome.error.action === "reauth") { + // D-2. Signing in again comes first, whatever the effect. + unknownSubmissionRef.current = null; + setFormErrors([]); + setStatusFailure(outcome.error); + setResult("reauth-required"); } else if (outcome.error.effect === "MAYBE_APPLIED") { unknownSubmissionRef.current = submittedValues; setFormErrors([]); @@ -204,6 +212,16 @@ export function useAppForm< message("form.conflict"), ]); setResult("conflict"); + } else if ( + outcome.error.kind === "FORBIDDEN" || + outcome.error.action === "retry" + ) { + unknownSubmissionRef.current = null; + setFormErrors([]); + setStatusFailure(outcome.error); + setResult( + outcome.error.kind === "FORBIDDEN" ? "forbidden" : "retry-later", + ); } else { unknownSubmissionRef.current = null; setFormErrors([message("form.unavailable")]); @@ -317,6 +335,8 @@ export function useAppForm< formErrors, pending, result, + /** The save failure behind `reauth-required`, `forbidden` or `retry-later`. */ + failure: STATUS_RESULTS.has(result) ? statusFailure : null, field, fieldId, focusField, @@ -329,6 +349,12 @@ export function useAppForm< }); } +const STATUS_RESULTS: ReadonlySet = new Set([ + "reauth-required", + "forbidden", + "retry-later", +]); + function issuesToFieldErrors( issues: readonly ZodIssue[], allowedFields: readonly FieldName[], diff --git a/src/presentation/i18n/catalog.ts b/src/presentation/i18n/catalog.ts index 5fed1810..6ec1a18c 100644 --- a/src/presentation/i18n/catalog.ts +++ b/src/presentation/i18n/catalog.ts @@ -125,6 +125,8 @@ const PLATFORM_KO_MESSAGES = { "form.conflict": "다른 변경과 충돌했습니다. 입력은 유지되었으니 최신 상태를 확인해 주세요.", "form.unavailable": "저장하지 못했습니다. 잠시 후 다시 시도해 주세요.", + "form.reauthLosesInput": + "다시 로그인하면 이 화면에 입력한 내용은 사라집니다. 필요하면 먼저 복사해 두세요.", "form.remaining": "{count}자 남음", "toast.region": "알림", "error.network_unreachable": "네트워크에 연결할 수 없습니다.", @@ -283,6 +285,8 @@ const PLATFORM_EN_MESSAGES = { "form.conflict": "Another update conflicts with this change. Your input has been preserved.", "form.unavailable": "The change could not be saved. Try again shortly.", + "form.reauthLosesInput": + "Signing in again clears what you entered on this page. Copy it first if you need it.", "form.remaining": "{count} characters remaining", "toast.region": "Notifications", "error.network_unreachable": "The network is unavailable.", diff --git a/tests/component/form-foundation.test.tsx b/tests/component/form-foundation.test.tsx index 1711148d..a91113f8 100644 --- a/tests/component/form-foundation.test.tsx +++ b/tests/component/form-foundation.test.tsx @@ -13,6 +13,7 @@ import { DirtyNavigationDialog, ErrorSummary, Form, + FormFailureStatus, FormField, useAppForm, useDirtyNavigationGuard, @@ -34,6 +35,7 @@ function FormHarness(props: Readonly<{ | Readonly<{ ok: false; error: ReturnType }> >; resetOnSuccess?: boolean; + onFailureAction?(): void; }>) { const form = useAppForm({ schema, @@ -57,6 +59,14 @@ function FormHarness(props: Readonly<{ fieldId={form.fieldId} onFocusField={form.focusField} /> + void form.submitForm() + : props.onFailureAction + } + /> + + )}

{MESSAGES["boot.supportReference"].replace( "{reference}", diff --git a/src/presentation/i18n/boot-messages.ts b/src/presentation/i18n/boot-messages.ts index 269d7c08..b49b75dd 100644 --- a/src/presentation/i18n/boot-messages.ts +++ b/src/presentation/i18n/boot-messages.ts @@ -13,6 +13,8 @@ export const BOOT_MESSAGES = Object.freeze({ "boot.field.configSchema": "설정 스키마", "boot.field.release": "릴리스", "boot.field.invalidKeys": "잘못된 설정 키", + "boot.retry.hint": "네트워크 연결을 확인한 뒤 다시 시도해 주세요.", + "boot.retry.action": "다시 시도", "boot.supportReference": "지원 참조: {reference}", } as const), "en-US": Object.freeze({ @@ -23,6 +25,8 @@ export const BOOT_MESSAGES = Object.freeze({ "boot.field.configSchema": "Configuration schema", "boot.field.release": "Release", "boot.field.invalidKeys": "Invalid configuration keys", + "boot.retry.hint": "Check the network connection and try again.", + "boot.retry.action": "Try again", "boot.supportReference": "Support reference: {reference}", } as const), }); diff --git a/tests/component/render-boundary.test.tsx b/tests/component/render-boundary.test.tsx index 63208a00..812d520f 100644 --- a/tests/component/render-boundary.test.tsx +++ b/tests/component/render-boundary.test.tsx @@ -73,6 +73,39 @@ describe("render recovery boundaries", () => { expect(shell).not.toHaveTextContent("stack"); }); + it.each(["CONFIG_FETCH_FAILED", "CONFIG_TIMEOUT", "MANIFEST_FETCH_FAILED", "MANIFEST_TIMEOUT"])( + "offers a retry for the network failure %s (09-10)", + async (code) => { + const onRetry = vi.fn(); + const user = userEvent.setup(); + render( + , + ); + expect(screen.getByRole("alert")).toHaveTextContent( + "네트워크 연결을 확인한 뒤 다시 시도해 주세요.", + ); + await user.click(screen.getByRole("button", { name: "다시 시도" })); + expect(onRetry).toHaveBeenCalledTimes(1); + }, + ); + + it("offers no retry for a failure a reload cannot fix (09-10)", () => { + render( + {}} + />, + ); + expect(screen.queryByRole("button")).toBeNull(); + }); + it("allows a boundary reset action without reloading the page", async () => { let shouldThrow = true; function Recoverable() { From 070d4dbe9c548b16b838a73ca9d1334e7f6518dc Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 23:29:22 +0900 Subject: [PATCH 086/185] test(features): probe the one local-draft implementation (09-12) The consumer-experience probe ran and scanned a fixture copy of local-draft that had drifted from src. The copy is gone; the probe runs the src store and scans every local-draft source file, and the measured table now describes it. Co-Authored-By: Claude Opus 5.5 --- .../capability-consumer-experience.md | 38 ++++---- .../fixtures/local-draft-feature.ts | 97 ------------------- .../indexeddb-local-draft.test.ts | 69 +++++++------ 3 files changed, 59 insertions(+), 145 deletions(-) delete mode 100644 tests/contract/consumer-experience/fixtures/local-draft-feature.ts diff --git a/docs/architecture/capability-consumer-experience.md b/docs/architecture/capability-consumer-experience.md index f9f2e822..a214da6d 100644 --- a/docs/architecture/capability-consumer-experience.md +++ b/docs/architecture/capability-consumer-experience.md @@ -48,20 +48,19 @@ its business requirement. ## Scenario B — IndexedDB local draft -The original executable consumer probe remains at: +The executable consumer probe is: `tests/contract/consumer-experience/indexeddb-local-draft.test.ts` -with its isolated fixture: +It runs and reads the one Local Draft implementation under +`src/features/local-draft-feature`; the isolated fixture copy it used to probe +had drifted from `src` and was removed (09-12). -`tests/contract/consumer-experience/fixtures/local-draft-feature.ts` - -The architecture is now also exercised by a real vertical slice under: - -`src/features/local-draft-feature` - -It owns the Local Draft domain/application API and binds an -`IndexedDbRepositoryPort` in its feature adapter. The +The feature owns the Local Draft domain/application API and declares the slice +of the repository it calls (`LocalDraftRepository` in +`src/features/local-draft-feature/adapters/local-draft-indexeddb-store.ts`). The +host hands in an `IndexedDbRepositoryPort` through the +`indexedDb` capability; the port satisfies that slice structurally. The cross-capability composition contract lives at: `tests/contract/reusable-capability/feature-adapter-composition.test.ts` @@ -80,25 +79,24 @@ It runs against native browser IndexedDB. The test creates the platform save/find/remove through the feature API. The Local Draft feature still does not import the IndexedDB runtime or native browser API. -Measured probe result: +Measured on `src/features/local-draft-feature` (09-12): | Metric | Result | | --- | ---: | -| feature-owned fixture LOC | 97 | -| platform import statements | 1 | +| feature LOC (all `.ts` files) | 295 | +| import statements leaving the feature (`contracts/errors`, `contracts/result`, `application-api`, `feature-adapter-contribution`) | 7 | | native IndexedDB API references | 0 | | `src/adapters/storage/indexeddb/**` imports | 0 | -| runtime-internal IndexedDB types imported by feature | 0 | +| `src/application/ports/browser-file-storage/**` imports | 0 | -The feature depends only on the public application boundary: - -`src/application/ports/browser-file-storage/index.ts` - -and specifically `IndexedDbRepositoryPort`. +The feature does not import the storage runtime or its port, so removing the +browser file/storage runtime (`test:browser-file-storage-removal`) leaves it +compiling. The contract test rejects feature source that reaches for `globalThis.indexedDB`, `IDBFactory`, `IDBDatabase`, `IDBTransaction`, -`IDBObjectStore` or the concrete IndexedDB adapter directory. +`IDBObjectStore`, the concrete IndexedDB adapter directory or the +browser-file-storage port. ## What this does and does not prove diff --git a/tests/contract/consumer-experience/fixtures/local-draft-feature.ts b/tests/contract/consumer-experience/fixtures/local-draft-feature.ts deleted file mode 100644 index 5a78fed7..00000000 --- a/tests/contract/consumer-experience/fixtures/local-draft-feature.ts +++ /dev/null @@ -1,97 +0,0 @@ -import type { - BrowserDataResult, - IndexedDbRepositoryPort, -} from "../../../../src/application/ports/browser-file-storage/index.ts"; - -export type LocalDraft = Readonly<{ - draftId: string; - title: string; - body: string; -}>; - -export type SaveLocalDraftCommand = Readonly<{ - draft: LocalDraft; - expectedRevision: number | null; - idempotencyKey: string; -}>; - -export type RemoveLocalDraftCommand = Readonly<{ - draftId: string; - expectedRevision: number; - idempotencyKey: string; -}>; - -export type LocalDraftRecord = Readonly<{ - draft: LocalDraft; - revision: number; -}>; - -export interface LocalDraftStore { - save( - command: SaveLocalDraftCommand, - signal?: AbortSignal, - ): Promise>>; - find( - draftId: string, - signal?: AbortSignal, - ): Promise>; - remove( - command: RemoveLocalDraftCommand, - signal?: AbortSignal, - ): Promise>; -} - -/** - * Feature-owned binding over the technology-neutral IndexedDB application port. - * - * The feature knows its domain type and optimistic concurrency inputs. It does - * not know database names, stores, transactions, native IDB objects, codecs, - * migrations, quota handling or connection lifecycle. - */ -export function createLocalDraftStore( - repository: IndexedDbRepositoryPort, -): LocalDraftStore { - const store: LocalDraftStore = { - async save(command, signal) { - const result = await repository.compareAndSwap({ - key: command.draft.draftId, - value: command.draft, - expectedRevision: command.expectedRevision, - idempotencyKey: command.idempotencyKey, - signal, - }); - if (!result.ok) return result; - return Object.freeze({ - ok: true as const, - value: Object.freeze({ revision: result.value.revision }), - }); - }, - - async find(draftId, signal) { - const result = await repository.read(draftId, signal); - if (!result.ok) return result; - return Object.freeze({ - ok: true as const, - value: - result.value === null - ? null - : Object.freeze({ - draft: result.value.value, - revision: result.value.revision, - }), - }); - }, - - async remove(command, signal) { - const result = await repository.remove({ - key: command.draftId, - expectedRevision: command.expectedRevision, - idempotencyKey: command.idempotencyKey, - signal, - }); - if (!result.ok) return result; - return Object.freeze({ ok: true as const, value: undefined }); - }, - }; - return Object.freeze(store); -} diff --git a/tests/contract/consumer-experience/indexeddb-local-draft.test.ts b/tests/contract/consumer-experience/indexeddb-local-draft.test.ts index f25dfae9..d2dc3975 100644 --- a/tests/contract/consumer-experience/indexeddb-local-draft.test.ts +++ b/tests/contract/consumer-experience/indexeddb-local-draft.test.ts @@ -1,4 +1,5 @@ -import { readFile } from "node:fs/promises"; +import { readdir, readFile } from "node:fs/promises"; +import path from "node:path"; import { describe, expect, it } from "vitest"; @@ -6,10 +7,25 @@ import type { BrowserDataResult, IndexedDbRepositoryPort, } from "../../../src/application/ports/browser-file-storage/index.ts"; -import { - createLocalDraftStore, - type LocalDraft, -} from "./fixtures/local-draft-feature.ts"; +import { createLocalDraftStore } from "../../../src/features/local-draft-feature/adapters/local-draft-indexeddb-store.ts"; +import type { LocalDraft } from "../../../src/features/local-draft-feature/domain/local-draft.ts"; + +// 09-12. This probe used to exercise a copy of the feature under fixtures/, +// which had drifted from src (it returned raw storage failures). It now reads +// and runs the one implementation. +const FEATURE_ROOT = "src/features/local-draft-feature"; + +async function featureSources(directory: string): Promise { + const entries = await readdir(directory, { withFileTypes: true }); + const nested = await Promise.all( + entries.map((entry) => { + const target = path.join(directory, entry.name); + if (entry.isDirectory()) return featureSources(target); + return /\.tsx?$/u.test(entry.name) ? [target] : []; + }), + ); + return nested.flat(); +} function success(value: Value): BrowserDataResult { return Object.freeze({ ok: true as const, value }); @@ -133,29 +149,26 @@ describe("IndexedDB local-draft consumer experience", () => { }); }); - it("keeps native IndexedDB and runtime internals out of feature-owned code", async () => { - const source = await readFile( - new URL("./fixtures/local-draft-feature.ts", import.meta.url), - "utf8", - ); - - const importLines = source - .split("\n") - .filter((line) => line.startsWith("import ")); - expect(importLines).toHaveLength(1); - expect(source).toContain( - "src/application/ports/browser-file-storage/index.ts", - ); - - for (const forbidden of [ - "src/adapters/storage/indexeddb", - "globalThis.indexedDB", - "IDBFactory", - "IDBDatabase", - "IDBTransaction", - "IDBObjectStore", - ]) { - expect(source).not.toContain(forbidden); + it("keeps native IndexedDB and the storage runtime out of feature-owned code", async () => { + const files = await featureSources(FEATURE_ROOT); + expect(files.length).toBeGreaterThan(0); + for (const file of files) { + const source = await readFile(file, "utf8"); + for (const forbidden of [ + "adapters/storage/indexeddb", + "application/ports/browser-file-storage", + "globalThis.indexedDB", + "IDBFactory", + "IDBDatabase", + "IDBTransaction", + "IDBObjectStore", + ]) { + const importsOrUses = source + .split("\n") + .filter((line) => !/^\s*(?:\*|\/\/)/u.test(line)) + .some((line) => line.includes(forbidden)); + expect(importsOrUses, `${file} uses ${forbidden}`).toBe(false); + } } }); }); From 2a1591a2fec6dccef7665ed3bd14ba250341b4ee Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 23:32:40 +0900 Subject: [PATCH 087/185] test(features): link fixture node_modules through the shared helper (09-01, 09-02) check:adapter-inventory allows only linkFixtureNodeModules for fixture dependencies; a single directory symlink lets a pnpm purge in the fixture reach the repository's own node_modules. Co-Authored-By: Claude Opus 5.5 --- tests/unit/product-feature-selection-build.test.ts | 5 +++-- tests/unit/two-feature-install-typecheck.test.ts | 6 ++++-- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/tests/unit/product-feature-selection-build.test.ts b/tests/unit/product-feature-selection-build.test.ts index 966f8e5e..987efb1c 100644 --- a/tests/unit/product-feature-selection-build.test.ts +++ b/tests/unit/product-feature-selection-build.test.ts @@ -1,11 +1,12 @@ import { spawnSync } from "node:child_process"; -import { cp, mkdir, mkdtemp, readFile, rm, symlink } from "node:fs/promises"; +import { cp, mkdir, mkdtemp, readFile, rm } from "node:fs/promises"; import { tmpdir } from "node:os"; import path from "node:path"; import { pathToFileURL } from "node:url"; import { afterAll, describe, expect, it } from "vitest"; +import { linkFixtureNodeModules } from "../../scripts/lib/fixture-node-modules.ts"; import { filesBelow } from "../../scripts/lib/removal-fixture.ts"; import { ROUTE_FEATURE_OWNER } from "../../src/features/installed-feature-contracts.ts"; import { COMPILED_PRODUCT_FEATURE_IDS } from "../../src/features/installed-product-manifest.ts"; @@ -47,7 +48,7 @@ describe("VITE_PRODUCT_FEATURES=none build (09-02)", () => { await mkdir(path.dirname(path.join(root, input)), { recursive: true }); await cp(path.resolve(input), path.join(root, input), { recursive: true }); } - await symlink(path.resolve("node_modules"), path.join(root, "node_modules"), "dir"); + await linkFixtureNodeModules(root); const env = { ...process.env, VITE_PRODUCT_FEATURES: "none" }; const generated = spawnSync( diff --git a/tests/unit/two-feature-install-typecheck.test.ts b/tests/unit/two-feature-install-typecheck.test.ts index bc8bfaa7..756491d0 100644 --- a/tests/unit/two-feature-install-typecheck.test.ts +++ b/tests/unit/two-feature-install-typecheck.test.ts @@ -1,10 +1,12 @@ import { spawnSync } from "node:child_process"; -import { cp, mkdir, mkdtemp, readFile, rm, symlink, writeFile } from "node:fs/promises"; +import { cp, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; import path from "node:path"; import { afterAll, describe, expect, it } from "vitest"; +import { linkFixtureNodeModules } from "../../scripts/lib/fixture-node-modules.ts"; + /** * 09-01. The central composers (`src/features/installed-*`) are typed from the * generated feature index, so the repository's own typecheck only ever sees @@ -144,7 +146,7 @@ describe("installing a second feature (09-01)", () => { for (const config of ["tsconfig.base.json", "tsconfig.app.json"]) { await cp(path.resolve(config), path.join(root, config)); } - await symlink(path.resolve("node_modules"), path.join(root, "node_modules"), "dir"); + await linkFixtureNodeModules(root); const files: Readonly> = { "src/contexts/two-feature-context/context-module.ts": CONTEXT_MODULE, "src/features/routed-feature/feature-module.ts": ROUTED_FEATURE_MODULE, From b25c5999ef64b9da5ed19309b47221a775ebd886 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 23:34:57 +0900 Subject: [PATCH 088/185] test(security): run the CSP smoke on the strict browser fixture (13-08) check:test-evidence requires every e2e spec to use the strict fixture, which fails on the zod eval console error. The smoke now sets zod's global config jitless before page scripts run and requires zero violations; without that init script it fails on the known probe. Co-Authored-By: Claude Opus 5.5 --- docs/security/browser-boundary.md | 12 ++++++--- tests/e2e/production-csp.spec.ts | 41 +++++++++++-------------------- 2 files changed, 22 insertions(+), 31 deletions(-) diff --git a/docs/security/browser-boundary.md b/docs/security/browser-boundary.md index a267ed5b..b8fa092d 100644 --- a/docs/security/browser-boundary.md +++ b/docs/security/browser-boundary.md @@ -9,10 +9,14 @@ verification compares that declaration with live responses. CSP deliberately omits `unsafe-inline` and `unsafe-eval`; production code and built assets must remain compatible with that baseline. `tests/e2e/production-csp.spec.ts` (part of `test:e2e`, FE-GATE-008) serves the build with these headers and fails on a -`securitypolicyviolation` event (review 13-08). One violation is known and -listed in that spec: zod probes `Function("")` on its first object schema and -the policy refuses it. Parsing still works; the report is noise until zod is -configured `jitless` before the first schema is built. Features that are off by +`securitypolicyviolation` event or console error (review 13-08). One +violation is known: zod probes `Function("")` on its first object schema and +the policy refuses it. Parsing still works, but the default build reports the +violation on every boot until zod is configured `jitless` before the first +schema is built. `z.config` in the entry module is too late, because the +bundler evaluates the shared chunks that build schemas first. The smoke sets +zod's global config before page scripts run so it can catch every other +violation; the spec comment names when to remove that. Features that are off by default need CSP additions when a project selects them; see step 9 in [optional adapter recipes](../architecture/optional-adapter-recipes.md). `connect-src 'self' https:` lets script reach any HTTPS origin. Narrowing it to diff --git a/tests/e2e/production-csp.spec.ts b/tests/e2e/production-csp.spec.ts index ff396a4f..7ae22e49 100644 --- a/tests/e2e/production-csp.spec.ts +++ b/tests/e2e/production-csp.spec.ts @@ -1,11 +1,11 @@ import { readFileSync } from "node:fs"; -import { expect, test, type ConsoleMessage, type Page } from "@playwright/test"; +import { expect, test, type Page } from "../support/browser/strict-browser-test.ts"; // 13-08. The Content-Security-Policy in config/hosting/security-headers.json was // declared but never applied in a browser: `vite preview` sends no security // headers. This smoke serves the build with the production headers attached -// and fails on any securitypolicyviolation event outside KNOWN_VIOLATIONS. +// and fails on any securitypolicyviolation event or console error. const { headers: declaredHeaders } = JSON.parse( readFileSync("config/hosting/security-headers.json", "utf8"), ) as { headers: Record }; @@ -26,19 +26,15 @@ const securityHeaders = { * Known violation, not accepted behavior. Zod probes `Function("")` when it * builds its first object schema, to decide whether it may compile parsers. * The policy has no 'unsafe-eval', so the probe is refused (zod catches it and - * parses without compiling) and reported on every boot. `z.config({ jitless: - * true })` removes the probe, but it must run before the first schema is - * built, and the bundler evaluates the shared chunks that build schemas before - * the entry module body. Owner: frontend-platform. Remove this entry when zod - * is configured before any schema construction; the test then requires zero - * violations. + * parses without compiling) and reported on every boot of the default build. + * `z.config({ jitless: true })` removes the probe, but it must run before the + * first schema is built, and the bundler evaluates the shared chunks that + * build schemas before the entry module body. Until the app does that, this + * smoke sets zod's shared global config (`globalThis.__zod_globalConfig`, read + * by zod/v4/core when it loads) before any page script runs, so + * every other violation is still caught. Owner: frontend-platform. Remove the + * init script below when the app configures zod itself. */ -const KNOWN_VIOLATIONS = new Set(["script-src eval"]); - -function isKnownConsoleViolation(message: ConsoleMessage): boolean { - return /unsafe-eval|JavaScript eval|evaluate a string as JavaScript/u.test(message.text()); -} - test.beforeEach(async ({ page, baseURL }) => { const origin = new URL(baseURL ?? "http://127.0.0.1:4173").origin; await page.route( @@ -51,6 +47,9 @@ test.beforeEach(async ({ page, baseURL }) => { }); }, ); + await page.addInitScript(() => { + (globalThis as { __zod_globalConfig?: object }).__zod_globalConfig = { jitless: true }; + }); await page.addInitScript(() => { const violations: string[] = []; Object.defineProperty(window, "__cspViolations", { value: violations }); @@ -65,17 +64,6 @@ async function cspViolations(page: Page): Promise { } test("boots and changes route under the production security headers", async ({ page }) => { - const failures: string[] = []; - page.on("console", (message) => { - if (message.type() === "error" && !isKnownConsoleViolation(message)) { - failures.push(`console:${message.text()}`); - } - }); - page.on("pageerror", (error) => failures.push(`pageerror:${error.name}`)); - page.on("requestfailed", (request) => - failures.push(`requestfailed:${new URL(request.url()).pathname}:${request.failure()?.errorText ?? ""}`), - ); - const response = await page.goto("/"); expect(response?.headers()["content-security-policy"]).toBe( securityHeaders["Content-Security-Policy"], @@ -92,6 +80,5 @@ test("boots and changes route under the production security headers", async ({ p page.getByRole("heading", { level: 1, name: "화면 상태" }), ).toBeFocused(); - expect((await cspViolations(page)).filter((violation) => !KNOWN_VIOLATIONS.has(violation))).toEqual([]); - expect(failures).toEqual([]); + expect(await cspViolations(page)).toEqual([]); }); From 5810461256a3790dac8c5b86a7cdc40674737361 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 23:35:11 +0900 Subject: [PATCH 089/185] fix(docs): check README runtime variables in verify:documentation (13-15) The unit test read README.md, which removal fixtures do not copy, so test:sample-removal failed. verify:documentation now requires README to name every build and deploy variable the generator and admission read. Co-Authored-By: Claude Opus 5.5 --- README.md | 3 +++ scripts/contracts/release-artifacts.ts | 3 +++ scripts/verify-documentation-readiness.ts | 21 ++++++++++++++++++++ tests/unit/runtime-config-docs.test.ts | 24 ----------------------- 4 files changed, 27 insertions(+), 24 deletions(-) delete mode 100644 tests/unit/runtime-config-docs.test.ts diff --git a/README.md b/README.md index 086066cd..ba496cf9 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,9 @@ Build and deploy variables, lowest precedence first: | `RELEASE_ID` | `RELEASE_ID` in the runtime config and the release manifest | `local-release` | | `RELEASE_TARGET` | the environment FE-GATE-027 admits the build to; must equal `APP_PROFILE` | none; admission refuses without it | +`verify:documentation` fails if this table stops naming a variable the build or +admission reads (`scripts/verify-documentation-readiness.ts`). + Only the two `RUNTIME_*` values can differ from the reviewed profile. Anything else changes by editing the profile file. Staging and production reject demo auth and non-HTTPS endpoints. diff --git a/scripts/contracts/release-artifacts.ts b/scripts/contracts/release-artifacts.ts index 8a0bb629..883586f5 100644 --- a/scripts/contracts/release-artifacts.ts +++ b/scripts/contracts/release-artifacts.ts @@ -1391,6 +1391,8 @@ export const documentationReviewArtifactSchema = z .strict(), ).min(1), routeScopeDocumented: z.boolean(), + // 13-15: build and deploy variables README.md does not name. + missingRuntimeVariables: z.array(nonEmptyString), results: z.array( z .object({ @@ -1429,6 +1431,7 @@ export const documentationReviewArtifactSchema = z artifact.passed !== (artifact.reportDigestValid && artifact.routeScopeDocumented && + artifact.missingRuntimeVariables.length === 0 && artifact.results.every(({ passed }) => passed)) ) { context.addIssue({ code: "custom", path: ["passed"], message: "must agree with report digest, documented scope and review results" }); diff --git a/scripts/verify-documentation-readiness.ts b/scripts/verify-documentation-readiness.ts index 3dc72754..cf03bd7e 100644 --- a/scripts/verify-documentation-readiness.ts +++ b/scripts/verify-documentation-readiness.ts @@ -2,6 +2,7 @@ import { access, mkdir, readFile } from "node:fs/promises"; import { ROUTE_REGISTRY } from "../src/features/installed-feature-contracts.ts"; import { documentationReviewArtifactSchema } from "./contracts/release-artifacts.ts"; +import { RUNTIME_OVERRIDES } from "./generate-runtime-config.ts"; import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts"; /** @@ -96,9 +97,25 @@ for (const path of ROUTE_SCOPE_DOCUMENTS) { } const routeScopeDocumented = routeScope.every((entry) => entry.documented); +// 13-15. README is where a project learns how to build for production. It +// named none of the variables the build and admission read, so each one is +// required here, taken from the code that reads it where possible. +const RUNTIME_VARIABLES = Object.freeze([ + "APP_PROFILE", + "RELEASE_TARGET", + "VITE_BUILD_ID", + "RELEASE_ID", + ...Object.values(RUNTIME_OVERRIDES), +]); +const readme = await readFile("README.md", "utf8").catch(() => ""); +const missingRuntimeVariables = RUNTIME_VARIABLES.filter( + (variable) => !readme.includes(`\`${variable}\``), +); + const passed = reportDigestValid && routeScopeDocumented && + missingRuntimeVariables.length === 0 && results.length === 2 && results.every((result) => result.passed); await mkdir("artifacts/quality", { recursive: true }); @@ -115,11 +132,15 @@ await writeValidatedJsonArtifact({ reportDigestValid, routeScope, routeScopeDocumented, + missingRuntimeVariables, results, passed, }, }); if (!passed) { + if (missingRuntimeVariables.length > 0) { + process.stderr.write(`README.md does not name: ${missingRuntimeVariables.join(", ")}\n`); + } process.stderr.write( "Documentation readiness: FAIL_UNVERIFIED (canonical scoped-review evidence is incomplete)\n", ); diff --git a/tests/unit/runtime-config-docs.test.ts b/tests/unit/runtime-config-docs.test.ts deleted file mode 100644 index 318d84b1..00000000 --- a/tests/unit/runtime-config-docs.test.ts +++ /dev/null @@ -1,24 +0,0 @@ -import { readFileSync } from "node:fs"; - -import { describe, expect, it } from "vitest"; - -import { RUNTIME_OVERRIDES } from "../../scripts/generate-runtime-config.ts"; - -// 13-15. README said runtime settings live in public/config.json, which the -// build replaces with config/runtime/.json, and named none of the -// variables a production build needs. -describe("runtime configuration documentation", () => { - it("names every build and deploy variable in the README", () => { - const readme = readFileSync("README.md", "utf8"); - for (const variable of [ - "APP_PROFILE", - "RELEASE_TARGET", - "VITE_BUILD_ID", - "RELEASE_ID", - ...Object.values(RUNTIME_OVERRIDES), - ]) { - expect(readme, variable).toContain(`\`${variable}\``); - } - expect(readme).toContain("config/runtime/.json"); - }); -}); From 6fe4aa9e309e2aa19be0d237590bc8c26a1052bd Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 23:51:35 +0900 Subject: [PATCH 090/185] build(recipes): ratchet file-transfer and offline-indexeddb bundle budgets The budgets are size ratchets set about 100 bytes above the measured reference bundle. Measured on 926f448 and after the wave-1 lanes: file-transfer 54468 -> 55517 gzip bytes (01-01..01-11 add capability reissue, size-aware timeouts, probe limiting) and offline-indexeddb 35856 -> 36822 (05-01..05-14 add per-transaction locks, purge sweep and corrupt-row skipping). Same rounding rule: 55600 and 36900. Co-Authored-By: Claude Opus 5.5 --- config/recipes/frontend-capability-recipes.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/config/recipes/frontend-capability-recipes.json b/config/recipes/frontend-capability-recipes.json index d27a0244..16c13e8c 100644 --- a/config/recipes/frontend-capability-recipes.json +++ b/config/recipes/frontend-capability-recipes.json @@ -109,7 +109,7 @@ "lifecycleMethods": ["close", "cancel-via-AbortSignal", "enforce-bounded-lifecycle-batch", "prune-expired-receipts", "reconcile", "enforcePolicies-with-composition-authority"], "owner": "project-owner-required", "securityPrivacy": ["Classify every persisted field and binary namespace.", "Encrypting in the same client is not a credential protection boundary.", "Keep database schema and record codec versions separate.", "Derive the physical IndexedDB name only from registry-issued authority, namespace and partition tokens; readable namespace, business and account IDs are forbidden.", "Persist and revalidate an immutable scope plus full BrowserStoragePolicy binding during upgrade, post-open and maintenance; missing or mismatched existing bindings fail closed.", "Use the actual IndexedDB wire split: StoredRecord contains only key, codecVersion, revision and payload; writtenAtEpochMs, synchronization, measuredBytes and eligibleAtEpochMs belong to the retention sidecar, while idempotency receipts and governance binding/budget use separate stores.", "Include every store registered in lifecycleMetadataStores in bounded full-partition purge while retaining immutable governance identity.", "Measure conservative logical bytes through the codec and atomically enforce dataset usedBytes plus receiptCount with record, lifecycle and migration writes.", "Enforce TTL before sweep visibility, delete UNTIL_SYNCED only after explicit confirmation, and require a composition-authorized short-lived proof for every deleting IndexedDB lifecycle batch.", "Bound idempotency receipt retention to 31 days and configured count to the implementation ceiling of 1000000; bound migration to old-writer-drained batches no larger than 500 rows or 30000ms.", "Bind OPFS readable and physical scopes in both directions and use only /ca-frontend-opfs-v1/authorities//// for physical dataset layout.", "For OPFS LOGOUT, UNTIL_SYNCED and ACCOUNT_DELETION maintenance, composition must provide both requestMaintenanceAuthority and consumeMaintenanceAuthority; issue a fresh proof bound to the exact frozen reason, scope and policy for at most five minutes, then atomically consume it to reject replay.", "Never expose an OPFS authority proof through the application request, persistence, diagnostics or telemetry.", "Never place user file names or identifiers in OPFS paths or diagnostics."], - "bundleBudgetGzipBytes": 36000, + "bundleBudgetGzipBytes": 36900, "fallback": "Read-only or online-only query path; OPFS may degrade to a size-capped IndexedDB Blob only when the product policy approves it.", "removal": ["Stop writes and background migration.", "Reconcile or export unsynced data, then purge only governance-bound owned partitions and OPFS namespaces through authorized bounded lifecycle operations.", "Close all database, channel, worker and file handles.", "Remove repository composition and dependency."], "serverStatePolicy": "reference-or-command-only" @@ -195,7 +195,7 @@ "lifecycleMethods": ["release-file-ref", "release-or-dispose-preview-leases", "cancel-via-AbortSignal", "reconcile-or-explicitly-abort-upload", "close-checkpoint-store", "dispose-capability-and-image-runtime"], "owner": "project-owner-required", "securityPrivacy": ["Treat file name, extension, MIME and lastModified as untrusted metadata.", "Resolve only exact composition-issued file and image policy object identities; callers cannot raise byte, candidate, pixel, quality, format, lifetime or origin ceilings.", "Use opaque file references and verification receipts bound to an inspected immutable file snapshot and the exact registered profile; reject replay through another profile even when an inspection rule ID matches.", "Treat presigned URLs as bearer capabilities; bind exact method, resource or upload part, offset, length, media type, checksum, origin, path, query, headers and expiry in an in-memory identity vault.", "Use credentials omit, redirect error, no-referrer and no-store for direct data-plane fetch; never persist or observe URL, query, signed header, capability, file name or raw backend message, and never emit digest, raw ETag or receipt values to diagnostics or telemetry.", "A strict account-partitioned upload checkpoint may persist only the protocol-defined SHA-256 file fingerprint, per-part checksum and bounded opaque non-authorizing part receipt token required for server reconciliation; no bearer token or raw signed capability is allowed.", "Persist only strict non-authorizing upload checkpoints and reconcile them with server-authoritative status and re-hashed local parts before completion.", "Require a synchronous server-issued browser-managed download capability whose receipt exactly equals the caller's branded capability receipt and whose resource, media type, safe extension, maximum bytes, optional digest and expiry all match before handoff.", "Expose File, OPFS, Cache and transfer byte streams only as chunk-level closed Results; stop after the first failure, cancel native readers and never throw a raw native exception across the port.", "Accept Image CDN assets only through immutable allowlisted or signature-verified descriptors and registered preset identities; reject active formats, arbitrary transforms, pixel/decode-budget overflow and unsafe cache policy.", "Upload completion remains QUARANTINED until backend scan and promotion; client capability checks are not an authorization boundary.", "Active content preview requires isolation or download-only treatment."], - "bundleBudgetGzipBytes": 54600, + "bundleBudgetGzipBytes": 55600, "fallback": "Accessible native file input, same-origin authorized server upload/download and a single bounded server-selected image rendition; generated artifacts above the buffer budget move to server-side generation.", "removal": ["Stop new capability and upload-session issuance, then cancel active reads and transfers.", "Reconcile or explicitly abort active multipart sessions and let backend TTL cleanup remove ambiguous orphans.", "Remove non-secret checkpoints according to account and retention policy.", "Release file references, revoke preview object-URL leases and dispose file, capability and image runtimes.", "Remove transfer/image feature facades and composition, then prove browser-transfer sources are absent from the production module inventory."], "serverStatePolicy": "query-cache-metadata-only" From 4d17259037a9d31bcc48b68a1a9014f3af4d1355 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 23:53:29 +0900 Subject: [PATCH 091/185] chore: lower the hand-rolled abort ratchet to 13 Measured after the wave-1 lanes: the OPFS worker client now waits on the kernel abort primitive and the IndexedDB binding check runs in a kernel transaction (05-07, 05-12). Co-Authored-By: Claude Opus 5.5 --- scripts/check-adapter-inventory.ts | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/scripts/check-adapter-inventory.ts b/scripts/check-adapter-inventory.ts index e4067f25..0d477dbc 100644 --- a/scripts/check-adapter-inventory.ts +++ b/scripts/check-adapter-inventory.ts @@ -209,7 +209,10 @@ async function main(): Promise { // probe 대기가 커널 operation으로 옮겨갔다(R3-2). // 16 → 15: `browser-files/browser-file-picker.ts`의 native input 대기와 // system picker 대기가 커널 operation으로 옮겨갔다(R3-2). - const HAND_ROLLED_ABORT_CEILING = 15; + // 15 → 13: `storage/opfs/opfs-worker-client.ts`가 커널 abort primitive를 쓰고, + // `storage/indexeddb/indexeddb-governance.ts`의 binding 검증이 커널 + // 트랜잭션으로 옮겨갔다(05-07, 05-12). + const HAND_ROLLED_ABORT_CEILING = 13; const handRolledScan = spawnSync( "git", ["grep", "-l", 'addEventListener("abort"', "--", "src/adapters"], From c9be8d65e45a164fe5a4b11887e005eec8a0e46f Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 23:57:04 +0900 Subject: [PATCH 092/185] fix(browser-files): return ABORTED instead of a leaked preview lease after a same-turn abort (02-01) create() checked the signal only before resolving the file, so an abort in the same turn still produced a lease the caller never released. Each leak used one of the 16 object URL slots shared with downloads. Co-Authored-By: Claude Opus 5.5 --- .../browser-files/object-url-lease.ts | 4 ++ tests/unit/browser-file-content.test.ts | 64 +++++++++++++++++++ 2 files changed, 68 insertions(+) diff --git a/src/adapters/browser-files/object-url-lease.ts b/src/adapters/browser-files/object-url-lease.ts index c1d82060..fe7e24c4 100644 --- a/src/adapters/browser-files/object-url-lease.ts +++ b/src/adapters/browser-files/object-url-lease.ts @@ -260,6 +260,10 @@ export class BrowserTransientPreview implements TransientPreviewPort { browserDataFailure("UNAVAILABLE", "PREVIEW"), ); } + // 02-01. The caller may abort while the file resolves; a lease created + // after that would never be released because the caller drops the result. + const abortedWhileResolving = abortedResult(input.signal, "PREVIEW"); + if (abortedWhileResolving) return this.#observe(abortedWhileResolving); const mediaType = resolved.value.mediaType.trim().toLowerCase(); if ( !EXACT_MEDIA_TYPE.test(mediaType) || diff --git a/tests/unit/browser-file-content.test.ts b/tests/unit/browser-file-content.test.ts index e1f1e36c..ea59c774 100644 --- a/tests/unit/browser-file-content.test.ts +++ b/tests/unit/browser-file-content.test.ts @@ -83,6 +83,47 @@ function pngPolicies( }); } +async function verifiedPngPreview(leases: ObjectUrlLeaseRegistry) { + const policies = pngPolicies(); + const vault = new BrowserFileVault({ policies }); + const captured = vault.captureFiles( + [ + new File( + [new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])], + "preview.png", + { type: "image/png", lastModified: 1 }, + ), + ], + pngSelectionPolicy, + ); + if (!captured.ok || !captured.value[0]) throw new Error("capture"); + const ref = captured.value[0].ref; + const inspected = await vault.inspect({ + ref, + policy: pngPolicy, + signal: new AbortController().signal, + }); + if (!inspected.ok || !inspected.value.verificationReceipt) { + throw new Error("inspect"); + } + const verificationReceipt = inspected.value.verificationReceipt; + const preview = new BrowserTransientPreview({ + files: vault, + policies, + leases, + hardMaxPreviewBytes: 10, + }); + return { + preview, + request: (signal: AbortSignal) => ({ + ref, + verificationReceipt, + policy: pngPolicy, + signal, + }), + }; +} + describe("browser file content policy", () => { it("neutralizes path, bidi, device-name and executable filename tricks", () => { expect( @@ -570,6 +611,29 @@ describe("browser file content policy", () => { }); }); + it("returns ABORTED without a lease when the caller aborts right after create() (02-01)", async () => { + const revoked: string[] = []; + let urlSequence = 0; + const leases = new ObjectUrlLeaseRegistry({ + createObjectURL: () => `blob:aborted-${urlSequence++}`, + revokeObjectURL: (url) => revoked.push(url), + }); + const { preview, request } = await verifiedPngPreview(leases); + + const controller = new AbortController(); + // Same-turn abort: the effect cleanup of a React StrictMode double effect. + const pending = preview.create(request(controller.signal)); + controller.abort(); + + expect(await pending).toMatchObject({ + ok: false, + error: { code: "ABORTED", operation: "PREVIEW" }, + }); + expect(leases.activeLeaseCount).toBe(0); + expect(urlSequence).toBe(0); + expect(revoked).toEqual([]); + }); + it("cannot weaken the built-in active-content preview denylist", async () => { const htmlPolicy = browserFilePolicyReference( "active-content", From 8522cb525697cd2543754e8f9a90bfe226504c72 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 23:58:19 +0900 Subject: [PATCH 093/185] fix(web-push): accept WebIDL notifications whose data is a prototype getter (06-01) Real Notification objects expose `data` as a getter on the prototype, so the own-property check dropped every click. The runtime test now uses a class-based fake with the WebIDL shape. Co-Authored-By: Claude Opus 5.5 --- .../web-push/service-worker-runtime.ts | 4 ++- tests/unit/web-push-worker-runtime.test.ts | 26 ++++++++++++++++++- 2 files changed, 28 insertions(+), 2 deletions(-) diff --git a/src/adapters/web-push/service-worker-runtime.ts b/src/adapters/web-push/service-worker-runtime.ts index 4182c241..a339a0ac 100644 --- a/src/adapters/web-push/service-worker-runtime.ts +++ b/src/adapters/web-push/service-worker-runtime.ts @@ -273,7 +273,9 @@ function notificationClickEventFacade( typeof value.waitUntil !== "function" || !isRecord(value.notification) || typeof value.notification.close !== "function" || - !Object.hasOwn(value.notification, "data") + // 06-01. `data` is a WebIDL getter on `Notification.prototype`, never an + // own property, so the check must follow the prototype chain. + !("data" in value.notification) ) { return null; } diff --git a/tests/unit/web-push-worker-runtime.test.ts b/tests/unit/web-push-worker-runtime.test.ts index ff9c8f58..44672418 100644 --- a/tests/unit/web-push-worker-runtime.test.ts +++ b/tests/unit/web-push-worker-runtime.test.ts @@ -106,6 +106,25 @@ function manualScheduler(): Readonly<{ }; } +/** + * 06-01. WebIDL shape of a real `Notification`: `data` is a getter and + * `close` a method on the prototype, so the instance has no own keys + * (checked in Chromium, Firefox and WebKit). + */ +class WebIdlNotification { + readonly #data: unknown; + closed = 0; + constructor(data: unknown) { + this.#data = data; + } + get data(): unknown { + return this.#data; + } + close(): void { + this.closed += 1; + } +} + describe("Web Push worker runtime", () => { it("waits for strict hint handling and shows only registry-owned safe copy", async () => { const store = await activeFence(); @@ -703,13 +722,18 @@ describe("Web Push worker runtime", () => { "pushsubscriptionchange", ]); let clickWait: Promise | null = null; + const notification = new WebIdlNotification(clickData()); + expect(Object.keys(notification)).toEqual(["closed"]); + expect(Object.hasOwn(notification, "data")).toBe(false); listeners.get("notificationclick")?.({ - notification: { data: clickData(), close() {} }, + notification, waitUntil(task: Promise) { clickWait = task; }, }); + expect(clickWait).not.toBeNull(); await clickWait; + expect(notification.closed).toBe(1); let subscriptionWait: Promise | null = null; listeners.get("pushsubscriptionchange")?.({ waitUntil(task: Promise) { From bb70820db79e83918435dc39402c58c4c064f8a9 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 23:58:52 +0900 Subject: [PATCH 094/185] fix(i18n): give every error registry kind its own message (07-01, 08-02) 22 of 38 kinds had no copy, so a failed query showed "This message is unavailable." as its title. A unit test now requires every registry row's message key in both locales, so a new kind without copy fails. Co-Authored-By: Claude Opus 5.5 --- src/presentation/i18n/catalog.ts | 50 ++++++++++++++++++++++++++++++++ tests/unit/i18n-contract.test.ts | 13 +++++++++ 2 files changed, 63 insertions(+) diff --git a/src/presentation/i18n/catalog.ts b/src/presentation/i18n/catalog.ts index f5276223..05a65af0 100644 --- a/src/presentation/i18n/catalog.ts +++ b/src/presentation/i18n/catalog.ts @@ -146,6 +146,30 @@ const PLATFORM_KO_MESSAGES = { "error.asset_mismatch": "화면 자산 구성이 현재 릴리스와 일치하지 않습니다.", "error.render_failure": "화면을 표시하지 못했습니다.", "error.unknown_failure": "예상하지 못한 문제가 발생했습니다.", + "error.request_aborted": "요청이 취소되었습니다.", + "error.content_type_mismatch": "서버 응답 형식을 해석할 수 없습니다.", + "error.malformed_json": "서버 응답을 읽을 수 없습니다.", + "error.response_body_limit": "서버 응답이 허용된 크기를 넘었습니다.", + "error.envelope_mismatch": "서버 응답 구조가 예상과 다릅니다.", + "error.schema_mismatch": "서버 응답 데이터가 현재 화면과 맞지 않습니다.", + "error.mapping_contract_violation": + "서버 응답을 화면 데이터로 바꾸지 못했습니다.", + "error.result_limit_exceeded": "결과가 너무 많아 표시할 수 없습니다.", + "error.scope_generation_changed": "세션이 바뀌어 이전 요청을 중단했습니다.", + "error.identity_intern_limit_exceeded": + "처리할 항목이 너무 많습니다. 잠시 후 다시 시도해 주세요.", + "error.duplicate_in_flight": "같은 요청을 이미 처리하고 있습니다.", + "error.pagination_contract_violation": "페이지 정보를 확인할 수 없습니다.", + "error.conflict": "다른 변경과 충돌했습니다.", + "error.validation_rejected": "서버가 입력값을 받아들이지 않았습니다.", + "error.unknown_client_failure": "요청을 처리할 수 없습니다.", + "error.boot_config_failure": "실행 설정을 불러오지 못했습니다.", + "error.release_manifest_failure": "릴리스 정보를 불러오지 못했습니다.", + "error.deploy_mismatch": "배포 구성이 현재 화면과 일치하지 않습니다.", + "error.storage_unavailable": "브라우저 저장소를 사용할 수 없습니다.", + "error.storage_quota_exceeded": "브라우저 저장 공간이 부족합니다.", + "error.telemetry_failure": "진단 정보를 보내지 못했습니다.", + "error.query_cache_failure": "저장된 조회 결과를 사용할 수 없습니다.", ...BOOT_MESSAGES["ko-KR"], } as const; @@ -300,6 +324,32 @@ const PLATFORM_EN_MESSAGES = { "error.asset_mismatch": "The page assets do not match this release.", "error.render_failure": "The page could not be displayed.", "error.unknown_failure": "An unexpected problem occurred.", + "error.request_aborted": "The request was cancelled.", + "error.content_type_mismatch": "The server response format is not supported.", + "error.malformed_json": "The server response could not be read.", + "error.response_body_limit": "The server response exceeded the allowed size.", + "error.envelope_mismatch": "The server response structure is unexpected.", + "error.schema_mismatch": "The server response data does not match this page.", + "error.mapping_contract_violation": + "The server response could not be converted for this page.", + "error.result_limit_exceeded": "There are too many results to display.", + "error.scope_generation_changed": + "The session changed, so the earlier request was stopped.", + "error.identity_intern_limit_exceeded": + "There are too many items to process. Try again shortly.", + "error.duplicate_in_flight": "The same request is already in progress.", + "error.pagination_contract_violation": + "The page information could not be verified.", + "error.conflict": "The change conflicts with another update.", + "error.validation_rejected": "The server did not accept the entered values.", + "error.unknown_client_failure": "The request could not be processed.", + "error.boot_config_failure": "The runtime configuration could not be loaded.", + "error.release_manifest_failure": "The release information could not be loaded.", + "error.deploy_mismatch": "The deployment does not match this page.", + "error.storage_unavailable": "Browser storage is unavailable.", + "error.storage_quota_exceeded": "Browser storage is full.", + "error.telemetry_failure": "The diagnostic information could not be sent.", + "error.query_cache_failure": "The stored query results are unavailable.", ...BOOT_MESSAGES["en-US"], } as const satisfies Record; diff --git a/tests/unit/i18n-contract.test.ts b/tests/unit/i18n-contract.test.ts index 42513ebd..ebcaf9b0 100644 --- a/tests/unit/i18n-contract.test.ts +++ b/tests/unit/i18n-contract.test.ts @@ -1,5 +1,7 @@ import { describe, expect, it } from "vitest"; +import { ERROR_REGISTRY } from "../../src/contracts/errors.ts"; + import { catalogKeys, FORMAT_FALLBACK, @@ -34,6 +36,17 @@ describe("internationalization message contract", () => { expect(MESSAGE_CATALOGS["ar-EG"]).toBe(EN_MESSAGES); }); + // 07-01/08-02. A kind without copy renders "This message is unavailable." + // as the failure title, so every registry row must resolve in both locales. + it("gives every error registry kind its own message in every locale", () => { + const missing = Object.values(ERROR_REGISTRY).flatMap((definition) => + [KO_MESSAGES, EN_MESSAGES] + .filter((catalog) => !Object.hasOwn(catalog, definition.userMessageKey)) + .map(() => definition.userMessageKey), + ); + expect(missing).toEqual([]); + }); + it("formats typed parameters and expands the pseudo locale", () => { expect( formatMessage("en-US", "route.documentTitle", { From 9a56741357d1f4876a89cb5f1955291235fb4d85 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 23:59:53 +0900 Subject: [PATCH 095/185] test(cache-storage): pin the anonymous same-origin stage request (02-02) Cache Storage has no logout purge, so credentials omit and same-origin mode are what keep per-user responses out of it. Removing either line, switching credentials to include or dropping redirect error now fails this test. Co-Authored-By: Claude Opus 5.5 --- tests/unit/public-response-cache.test.ts | 48 ++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/tests/unit/public-response-cache.test.ts b/tests/unit/public-response-cache.test.ts index 30dd1df8..e0b2c0aa 100644 --- a/tests/unit/public-response-cache.test.ts +++ b/tests/unit/public-response-cache.test.ts @@ -112,6 +112,54 @@ describe("public response Cache Storage adapter", () => { expect(match.ok && match.value !== null).toBe(true); }); + it("stages with an anonymous same-origin request that fails on redirect (02-02)", async () => { + const policy = createDefaultPublicCachePolicy( + "https://assets.example.test", + ); + const bytes = new Uint8Array([5, 5, 5, 5]); + const asset: PublicCacheAsset = { + absoluteUrl: "https://assets.example.test/anonymous.js", + expectedByteLength: bytes.byteLength, + expectedContentType: "application/javascript", + integrity: { + algorithm: "SHA-256", + digestHex: await digestHex(bytes), + }, + }; + const requests: Request[] = []; + const adapter = createPublicResponseCacheAdapter({ + cacheStorage: new MemoryCacheStorage() as unknown as CacheStorage, + crypto: globalThis.crypto, + mutationLock: immediateLock, + policy, + fetcher: async (request) => { + requests.push(request); + return new Response(bytes, { + headers: { + "cache-control": "public, max-age=31536000, immutable", + "content-type": "application/javascript", + }, + }); + }, + }); + const manifest = await manifestFor("anonymous-release", [asset], policy); + + expect(await adapter.admin.stageRelease(manifest)).toMatchObject({ + ok: true, + }); + // The Cache Storage is origin-wide and has no logout purge, so a cookie + // on this request would let a per-user response outlive the session. + expect( + requests.map(({ credentials, mode, redirect }) => ({ + credentials, + mode, + redirect, + })), + ).toEqual([ + { credentials: "omit", mode: "same-origin", redirect: "error" }, + ]); + }); + it("restages an evicted entry even when the release marker remains", async () => { const policy = createDefaultPublicCachePolicy( "https://assets.example.test", From bcad7b0d12dbf04bce3d5aaaea9549161e16709b Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 26 Sep 2026 00:01:10 +0900 Subject: [PATCH 096/185] fix(realtime): reset the retry budget on every session end and pause it offline (04-01) A long healthy connection that ended offline or with a throwing waitClosed kept a spent elapsed budget and stopped with zero retries. Offline waits no longer spend the budget, and WebSocket HEARTBEAT_ACK is now observable so a quiet stream can earn a fresh budget. Co-Authored-By: Claude Opus 5.5 --- .../realtime/reconnect-coordinator.ts | 51 +++-- .../websocket/websocket-connection.ts | 4 + .../realtime-reconnect-coordinator.test.ts | 192 +++++++++++++++++- 3 files changed, 218 insertions(+), 29 deletions(-) diff --git a/src/adapters/realtime/reconnect-coordinator.ts b/src/adapters/realtime/reconnect-coordinator.ts index 708014dc..0c529a58 100644 --- a/src/adapters/realtime/reconnect-coordinator.ts +++ b/src/adapters/realtime/reconnect-coordinator.ts @@ -55,7 +55,9 @@ export type RealtimeReconnectAttemptContext = Readonly<{ pendingRecovery: RealtimeCommittedRecovery | null; isCurrent(): boolean; /** - * Call only after a protocol-valid heartbeat or event. + * Call only after a protocol-valid heartbeat or event: an applied event, + * an SSE `onComment`, or a WebSocket `HEARTBEAT_ACK` observation. A quiet + * stream that never calls it cannot earn a fresh retry budget. */ markValidHeartbeatOrEvent(): void; /** @@ -493,15 +495,16 @@ export function createRealtimeReconnectCoordinator( ) { return retry.terminalResult; } - if ( - (!online || requiredOnlineVersion !== null) && - !(await waitOnline()) - ) { + const offlineWait = !online || requiredOnlineVersion !== null; + if (offlineWait && !(await waitOnline())) { return failure(currentFailure() ?? "ABORTED"); } now = safeNow(clock); if (now === null) return retry.terminalResult; + // Offline time is not retry time. The elapsed budget restarts when + // the network returns; maxAttempts still bounds the loop. + if (offlineWait) budgetStartedAt = now; const delay = nextDelay( retry, retriesUsed, @@ -815,6 +818,21 @@ export function createRealtimeReconnectCoordinator( phase.controller.signal, ); const closeOffline = wentOffline(phase); + // Every way an opened session ends, including offline and a throwing + // waitClosed, can earn a fresh budget, not only a classified close. + const endedAt = safeNow(clock); + if ( + endedAt !== null && + isReconnectAttemptResetEligible({ + policy, + openedAtMs: openedAt, + nowMs: endedAt, + observedValidHeartbeatOrEvent: validSignalObserved, + }) + ) { + retriesUsed = 0; + budgetStartedAt = endedAt; + } const afterWaitClosed = currentFailure(); if (afterWaitClosed) { @@ -902,18 +920,6 @@ export function createRealtimeReconnectCoordinator( if (closedAt === null) { return classified.outcome.failure.result; } - if ( - isReconnectAttemptResetEligible({ - policy, - openedAtMs: openedAt, - nowMs: closedAt, - observedValidHeartbeatOrEvent: - validSignalObserved, - }) - ) { - retriesUsed = 0; - budgetStartedAt = closedAt; - } retry = captureRetry( classified.outcome.failure.result, classified.outcome.failure.result, @@ -932,17 +938,6 @@ export function createRealtimeReconnectCoordinator( if (closedAt === null) { return classified.directive.terminalFailure.result; } - if ( - isReconnectAttemptResetEligible({ - policy, - openedAtMs: openedAt, - nowMs: closedAt, - observedValidHeartbeatOrEvent: validSignalObserved, - }) - ) { - retriesUsed = 0; - budgetStartedAt = closedAt; - } pendingRecovery = classified.directive; retry = captureRetry( classified.directive.terminalFailure.result, diff --git a/src/adapters/realtime/websocket/websocket-connection.ts b/src/adapters/realtime/websocket/websocket-connection.ts index 6b270ac0..592b328e 100644 --- a/src/adapters/realtime/websocket/websocket-connection.ts +++ b/src/adapters/realtime/websocket/websocket-connection.ts @@ -71,6 +71,7 @@ export type WebSocketConnectionObservation = Readonly<{ kind: | "CONNECTED" | "SUBSCRIBED" + | "HEARTBEAT_ACK" | "FRAME_REJECTED" | "RECOVERY_REQUIRED" | "CLOSED"; @@ -372,6 +373,9 @@ export function createWebSocketConnection( if (decoded.value.nonce === retiredHeartbeat) { retiredHeartbeat = null; } + // A quiet stream's only liveness proof; composition can forward it to + // the reconnect coordinator's markValidHeartbeatOrEvent. + observe({ kind: "HEARTBEAT_ACK" }); return; } const queueLimits = effectiveLimits ?? ceilings; diff --git a/tests/unit/realtime/realtime-reconnect-coordinator.test.ts b/tests/unit/realtime/realtime-reconnect-coordinator.test.ts index 8e3fd832..268304c8 100644 --- a/tests/unit/realtime/realtime-reconnect-coordinator.test.ts +++ b/tests/unit/realtime/realtime-reconnect-coordinator.test.ts @@ -434,6 +434,105 @@ describe("realtime reconnect coordinator", () => { expect(result).toBe(terminal); }); + it("does not spend the elapsed budget while waiting offline", async () => { + const clock = new ManualClock(); + const environment = new MutableOnlineEnvironment(false); + const terminal = realtimeFailure( + "FORBIDDEN", + "CONNECT", + false, + ); + const attempt = vi.fn(() => failed(terminal)); + const coordinator = createRealtimeReconnectCoordinator({ + policy: policy(), + environment, + clock, + random: () => 0.5, + confirmTransportBarrier: confirmationSucceeded, + attempt, + }); + + const running = coordinator.run(); + await flush(); + // Offline for longer than maxElapsedMs before the first attempt. + clock.advance(6_000); + environment.emit(true); + await flushUntil(() => clock.sleepCalls.length === 1); + expect(clock.sleepCalls).toEqual([50]); + + clock.advance(50); + const result = await running; + expect(attempt).toHaveBeenCalledTimes(1); + expect(result).toBe(terminal); + }); + + it.each(["an offline blip", "a waitClosed throw"] as const)( + "reconnects after %s ends a healthy session older than the elapsed budget", + async (ending) => { + const clock = new ManualClock(); + const environment = new MutableOnlineEnvironment(true); + const closing = deferred>(); + const terminal = realtimeFailure( + "FORBIDDEN", + "CONNECT", + false, + ); + let attempts = 0; + const coordinator = createRealtimeReconnectCoordinator({ + policy: policy(), + environment, + clock, + random: () => 0.5, + confirmTransportBarrier: confirmationSucceeded, + attempt: (context: RealtimeReconnectAttemptContext) => { + attempts += 1; + if (attempts > 1) return failed(terminal); + context.markValidHeartbeatOrEvent(); + return opened>( + Object.freeze({ + classifyClosed: ( + receipt: RealtimeReconnectOutcome, + ) => receipt, + close: () => + closing.resolve( + failed( + realtimeFailure("OFFLINE", "RECEIVE", true), + ), + ), + waitClosed: () => + ending === "an offline blip" + ? closing.promise + : closing.promise.then(() => { + throw new Error("transport failed"); + }), + }), + ); + }, + }); + + const running = coordinator.run(); + await flushUntil(() => attempts === 1); + await flush(); + // Healthy for twice maxElapsedMs, then a one second outage. + clock.advance(10_000); + if (ending === "an offline blip") { + environment.emit(false); + await flush(); + clock.advance(1_000); + environment.emit(true); + } else { + closing.resolve(closedSuccessfully()); + } + await flushUntil(() => clock.sleepCalls.length === 1); + expect(clock.sleepCalls).toEqual([50]); + + clock.advance(50); + const result = await running; + expect(attempts).toBe(2); + expect(result).toBe(terminal); + }, + ); + it("resets a spent retry only after a valid signal and a stable open", async () => { const runScenario = async (markValid: boolean, openMs: number) => { const clock = new ManualClock(); @@ -1502,9 +1601,11 @@ class FakeWebSocket implements WebSocketFacade { string, Set<(event: unknown) => void> >(); + readonly sent: string[] = []; - send(): void { + send(data: string): void { if (this.readyState !== 1) throw new Error("not open"); + this.sent.push(data); } close(): void { @@ -1556,6 +1657,20 @@ class FakeWebSocket implements WebSocketFacade { this.emit("close", { code, reason: "" }); } + ackHeartbeats(): void { + for (const raw of this.sent.splice(0)) { + const frame = JSON.parse(raw) as { type: string; nonce: string }; + if (frame.type !== "HEARTBEAT") continue; + this.emit("message", { + data: JSON.stringify({ + type: "HEARTBEAT_ACK", + protocol: REALTIME_WEBSOCKET_PROTOCOL, + nonce: frame.nonce, + }), + }); + } + } + private emit(type: string, event: unknown): void { for (const listener of [...(this.listeners.get(type) ?? [])]) { listener(event); @@ -1639,6 +1754,81 @@ describe("transport failures through the reconnect coordinator", () => { }, ); + it("reconnects a quiet WebSocket whose heartbeats kept it healthy past the elapsed budget", async () => { + const clock = new ManualClock(); + const sockets: FakeWebSocket[] = []; + let nonce = 0; + const coordinator = createRealtimeReconnectCoordinator< + WebSocketClosedReceipt + >({ + policy: policy(), + environment: new MutableOnlineEnvironment(true), + clock, + random: () => 0.5, + confirmTransportBarrier: confirmationSucceeded, + attempt: async (context) => { + const connection = createWebSocketConnection({ + origin: "https://app.example.test", + endpointPath: "/_realtime/v1", + clock, + createNonce: () => `nonce.${++nonce}`, + createSocket: () => { + const socket = new FakeWebSocket(); + sockets.push(socket); + return socket; + }, + onEvent: async () => + realtimeSuccess(REALTIME_TRANSPORT_CONTINUE), + onRecoveryRequired: () => undefined, + observe: (observation) => { + if (observation.kind === "HEARTBEAT_ACK") { + context.markValidHeartbeatOrEvent(); + } + }, + }); + const connected = await connection.connect(context.signal); + if (!connected.ok) return failed(connected); + return opened( + Object.freeze({ + waitClosed: () => connection.waitClosed(), + classifyClosed: (receipt: WebSocketClosedReceipt) => + Object.freeze({ + result: Object.freeze({ + ok: false as const, + error: receipt.error, + }), + }), + close: () => connection.close(), + }), + ); + }, + }); + + const running = coordinator.run(); + await flushUntil(() => sockets.length === 1); + sockets[0]!.accept(); + await flush(); + // No events, only acknowledged heartbeats, for longer than maxElapsedMs. + for (let beat = 0; beat < 2; beat += 1) { + clock.advance(5_000); + await flush(); + sockets[0]!.ackHeartbeats(); + clock.advance(1_000); + await flush(); + } + sockets[0]!.nativeClose(1_012); + await flushUntil(() => clock.sleepCalls.includes(50)); + clock.advance(50); + await flushUntil(() => sockets.length === 2); + expect(sockets).toHaveLength(2); + + coordinator.close(); + await expect(running).resolves.toMatchObject({ + ok: false, + error: { kind: "CLOSED" }, + }); + }); + it.each([502, 504])( "reconnects SSE HTTP %i that carries no server hint", async (status) => { From c8e4794860287c90195460f8395cedefd2ea9163 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 26 Sep 2026 00:03:13 +0900 Subject: [PATCH 097/185] docs(browser-files): dispose the file runtime on logout or account switch (02-03) The runtime does not know the session, so File refs, preview leases and downloads of the previous user outlived a logout. Section 3.5 and the recipe lifecycle now say to dispose it, via a scope reset participant if needed. Co-Authored-By: Claude Opus 5.5 --- config/recipes/frontend-capability-recipes.json | 2 +- docs/architecture/browser-file-and-origin-storage.md | 8 ++++++++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/config/recipes/frontend-capability-recipes.json b/config/recipes/frontend-capability-recipes.json index 16c13e8c..935a73c8 100644 --- a/config/recipes/frontend-capability-recipes.json +++ b/config/recipes/frontend-capability-recipes.json @@ -192,7 +192,7 @@ "port": "FilePickerPort / FileContentPort / TransientPreviewPort / DownloadDeliveryPort / PresignedDownloadSourcePort / PresignedUploadPartPort / ResumableUploadPort / ImageCdnPresentationPort", "fake": "Memory file/preview/download adapters plus injected deterministic capability, upload-control-plane, part-executor and image-verifier test doubles", "failureKinds": ["dismissed", "permission-denied", "count-or-size-rejection", "type-or-signature-rejection", "file-changed", "abort", "integrity-failure", "partial-save", "expired-or-revoked-capability", "part-or-session-conflict", "checkpoint-conflict", "quarantined", "image-policy-rejection"], - "lifecycleMethods": ["release-file-ref", "release-or-dispose-preview-leases", "cancel-via-AbortSignal", "reconcile-or-explicitly-abort-upload", "close-checkpoint-store", "dispose-capability-and-image-runtime"], + "lifecycleMethods": ["release-file-ref", "release-or-dispose-preview-leases", "cancel-via-AbortSignal", "reconcile-or-explicitly-abort-upload", "close-checkpoint-store", "dispose-capability-and-image-runtime", "dispose-browser-file-runtime-on-logout-or-account-switch"], "owner": "project-owner-required", "securityPrivacy": ["Treat file name, extension, MIME and lastModified as untrusted metadata.", "Resolve only exact composition-issued file and image policy object identities; callers cannot raise byte, candidate, pixel, quality, format, lifetime or origin ceilings.", "Use opaque file references and verification receipts bound to an inspected immutable file snapshot and the exact registered profile; reject replay through another profile even when an inspection rule ID matches.", "Treat presigned URLs as bearer capabilities; bind exact method, resource or upload part, offset, length, media type, checksum, origin, path, query, headers and expiry in an in-memory identity vault.", "Use credentials omit, redirect error, no-referrer and no-store for direct data-plane fetch; never persist or observe URL, query, signed header, capability, file name or raw backend message, and never emit digest, raw ETag or receipt values to diagnostics or telemetry.", "A strict account-partitioned upload checkpoint may persist only the protocol-defined SHA-256 file fingerprint, per-part checksum and bounded opaque non-authorizing part receipt token required for server reconciliation; no bearer token or raw signed capability is allowed.", "Persist only strict non-authorizing upload checkpoints and reconcile them with server-authoritative status and re-hashed local parts before completion.", "Require a synchronous server-issued browser-managed download capability whose receipt exactly equals the caller's branded capability receipt and whose resource, media type, safe extension, maximum bytes, optional digest and expiry all match before handoff.", "Expose File, OPFS, Cache and transfer byte streams only as chunk-level closed Results; stop after the first failure, cancel native readers and never throw a raw native exception across the port.", "Accept Image CDN assets only through immutable allowlisted or signature-verified descriptors and registered preset identities; reject active formats, arbitrary transforms, pixel/decode-budget overflow and unsafe cache policy.", "Upload completion remains QUARANTINED until backend scan and promotion; client capability checks are not an authorization boundary.", "Active content preview requires isolation or download-only treatment."], "bundleBudgetGzipBytes": 55600, diff --git a/docs/architecture/browser-file-and-origin-storage.md b/docs/architecture/browser-file-and-origin-storage.md index 45e72674..8c8abe85 100644 --- a/docs/architecture/browser-file-and-origin-storage.md +++ b/docs/architecture/browser-file-and-origin-storage.md @@ -355,6 +355,14 @@ digest 또는 별도 검토된 streaming hash adapter를 사용한다. 모든 active lease를 즉시 revoke한다. - URL을 global state, IndexedDB, query cache, log, analytics에 보관하지 않는다. - Service Worker에서 object URL을 사용하지 않는다. +- 로그아웃·계정 전환에서는 runtime 전체를 dispose한다. browser file runtime은 + 세션을 모른다(`src/adapters/browser-files/create-browser-file-runtime.ts:93`). + `runtime.dispose()`(`:177-185`)가 이전 사용자가 고른 File 참조, preview lease, + 진행 중 download(`download-delivery-adapter.ts:385-391`)를 한 번에 닫는다. + runtime을 route·feature보다 오래 사는 곳에서 만들었다면 server-state scope + reset participant(`src/adapters/query-cache/server-state-scope-runtime.ts:19`, + 등록 예 `src/bootstrap/runtime-adapters.ts:410-416`)로 `dispose()`를 등록하고 + 다음 세대에서 새 runtime을 만든다. dispose한 runtime은 다시 쓸 수 없다. - SVG, HTML, untrusted PDF 같은 active content를 same-origin object URL iframe에 직접 preview하지 않는다. 별도 격리 origin 또는 안전한 decode/re-encode 결과, 아니면 attachment-only 정책을 사용한다. From 17d617ab7a5d34bb4d74985e5838e683729b95d8 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 26 Sep 2026 00:04:25 +0900 Subject: [PATCH 098/185] fix(contracts): classify unknown schema changes as breaking and gate the runtime config schema against a baseline (07-02, 13-10) The classifier called type, enum and nullable changes "none" and treated new keys under strict readers as additive; FE-GATE-014 only checked hand-written fixtures. It now fails closed and compares the committed baseline with the schema the build emits. The doc lists per-boundary reader rules. Co-Authored-By: Claude Opus 5.5 --- config/compatibility/fixtures.json | 110 +++++++------- .../runtime-config.schema.baseline.json | 140 ++++++++++++++++++ docs/contracts/compatibility.md | 57 ++++++- scripts/check-compatibility.ts | 81 ++++++---- scripts/contracts/release-artifacts.ts | 23 ++- src/contracts/compatibility.ts | 63 ++++++-- tests/unit/compatibility.test.ts | 77 ++++++++++ 7 files changed, 450 insertions(+), 101 deletions(-) create mode 100644 config/compatibility/runtime-config.schema.baseline.json diff --git a/config/compatibility/fixtures.json b/config/compatibility/fixtures.json index fbe5d0c3..37487e4f 100644 --- a/config/compatibility/fixtures.json +++ b/config/compatibility/fixtures.json @@ -1,63 +1,67 @@ { - "schemaVersion": 1, - "families": { - "api": { - "additive": { - "before": { "required": ["id"], "properties": { "id": {} } }, - "after": { - "required": ["id"], - "properties": { "id": {}, "displayName": {} } - } - }, - "breaking": { - "before": { "required": ["id"], "properties": { "id": {} } }, - "after": { - "required": ["id", "name"], - "properties": { "id": {}, "name": {} } - } + "schemaVersion": 2, + "cases": [ + { + "id": "tolerant-reader-optional-field", + "expected": "additive", + "before": { "required": ["id"], "properties": { "id": {} } }, + "after": { + "required": ["id"], + "properties": { "id": {}, "displayName": {} } } }, - "config": { - "additive": { - "before": { "required": ["APP_ENV"], "properties": { "APP_ENV": {} } }, - "after": { - "required": ["APP_ENV"], - "properties": { "APP_ENV": {}, "OPTIONAL_FLAG": {} } - } + { + "id": "strict-reader-optional-field", + "expected": "breaking", + "before": { + "required": ["APP_ENV"], + "properties": { "APP_ENV": {} }, + "additionalProperties": false }, - "breaking": { - "before": { "required": ["APP_ENV"], "properties": { "APP_ENV": {} } }, - "after": { - "required": ["APP_ENV", "NEW_REQUIRED"], - "properties": { "APP_ENV": {}, "NEW_REQUIRED": {} } - } + "after": { + "required": ["APP_ENV"], + "properties": { "APP_ENV": {}, "OPTIONAL_FLAG": {} }, + "additionalProperties": false } }, - "storage": { - "additive": { - "before": { "properties": { "theme": {} } }, - "after": { "properties": { "theme": {}, "contrast": {} } } - }, - "breaking": { - "before": { "properties": { "theme": {} } }, - "after": { "properties": {} } + { + "id": "required-field-added", + "expected": "breaking", + "before": { "required": ["buildId"], "properties": { "buildId": {} } }, + "after": { + "required": ["buildId", "assetManifestHash"], + "properties": { "buildId": {}, "assetManifestHash": {} } } }, - "release": { - "additive": { - "before": { "required": ["buildId"], "properties": { "buildId": {} } }, - "after": { - "required": ["buildId"], - "properties": { "buildId": {}, "builtAt": {} } - } - }, - "breaking": { - "before": { "required": ["buildId"], "properties": { "buildId": {} } }, - "after": { - "required": ["buildId", "assetManifestHash"], - "properties": { "buildId": {}, "assetManifestHash": {} } - } - } + { + "id": "field-removed", + "expected": "breaking", + "before": { "properties": { "theme": {} } }, + "after": { "properties": {} } + }, + { + "id": "type-changed", + "expected": "breaking", + "before": { "properties": { "id": { "type": "string" } } }, + "after": { "properties": { "id": { "type": "number" } } } + }, + { + "id": "enum-narrowed", + "expected": "breaking", + "before": { "properties": { "state": { "enum": ["A", "B"] } } }, + "after": { "properties": { "state": { "enum": ["A"] } } } + }, + { + "id": "nullable-added", + "expected": "breaking", + "before": { "properties": { "note": { "type": "string" } } }, + "after": { "properties": { "note": { "type": ["string", "null"] } } } + }, + { + "id": "unchanged", + "expected": "none", + "before": { "required": ["id"], "properties": { "id": { "type": "string" } } }, + "after": { "properties": { "id": { "type": "string" } }, "required": ["id"] } } - } + ] } diff --git a/config/compatibility/runtime-config.schema.baseline.json b/config/compatibility/runtime-config.schema.baseline.json new file mode 100644 index 00000000..046379ef --- /dev/null +++ b/config/compatibility/runtime-config.schema.baseline.json @@ -0,0 +1,140 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "APP_ENV": { + "type": "string", + "enum": [ + "local", + "development", + "staging", + "production" + ] + }, + "API_BASE_URL": { + "type": "string", + "format": "uri" + }, + "REQUEST_TIMEOUT_MS": { + "default": 10000, + "type": "integer", + "minimum": 100, + "maximum": 60000 + }, + "MAX_RETRY_ATTEMPTS": { + "default": 2, + "type": "integer", + "minimum": 0, + "maximum": 2 + }, + "TELEMETRY_ENABLED": { + "type": "boolean" + }, + "TELEMETRY_ENDPOINT": { + "type": "string", + "format": "uri" + }, + "AUTH_MODE": { + "type": "string", + "enum": [ + "external", + "demo" + ] + }, + "RELEASE_MANIFEST_URL": { + "default": "/release-manifest.json", + "type": "string", + "minLength": 1 + }, + "RELEASE_ID": { + "type": "string", + "minLength": 1 + }, + "BUILD_ID": { + "type": "string", + "minLength": 1 + }, + "CONFIG_SCHEMA_VERSION": { + "type": "string", + "const": "2.0" + }, + "CAPABILITY_OVERRIDES": { + "default": { + "REALTIME": "DEFAULT", + "WEB_WORKER": "DEFAULT", + "SERVICE_WORKER": "DEFAULT", + "OFFLINE_COMMANDS": "DEFAULT" + }, + "type": "object", + "properties": { + "REALTIME": { + "default": "DEFAULT", + "type": "string", + "enum": [ + "DEFAULT", + "DISABLED" + ] + }, + "WEB_WORKER": { + "default": "DEFAULT", + "type": "string", + "enum": [ + "DEFAULT", + "DISABLED" + ] + }, + "SERVICE_WORKER": { + "default": "DEFAULT", + "type": "string", + "enum": [ + "DEFAULT", + "DISABLED" + ] + }, + "OFFLINE_COMMANDS": { + "default": "DEFAULT", + "type": "string", + "enum": [ + "DEFAULT", + "DISABLED" + ] + } + }, + "required": [ + "REALTIME", + "WEB_WORKER", + "SERVICE_WORKER", + "OFFLINE_COMMANDS" + ], + "additionalProperties": false + }, + "FEATURE_OVERRIDES": { + "default": {}, + "type": "object", + "propertyNames": { + "type": "string", + "pattern": "^[a-z][a-z0-9-]{0,63}$" + }, + "additionalProperties": { + "type": "string", + "enum": [ + "DEFAULT", + "DISABLED" + ] + } + } + }, + "required": [ + "APP_ENV", + "API_BASE_URL", + "REQUEST_TIMEOUT_MS", + "MAX_RETRY_ATTEMPTS", + "TELEMETRY_ENABLED", + "AUTH_MODE", + "RELEASE_MANIFEST_URL", + "CONFIG_SCHEMA_VERSION", + "CAPABILITY_OVERRIDES", + "FEATURE_OVERRIDES" + ], + "additionalProperties": false +} diff --git a/docs/contracts/compatibility.md b/docs/contracts/compatibility.md index 1e3dbf56..46ec1b18 100644 --- a/docs/contracts/compatibility.md +++ b/docs/contracts/compatibility.md @@ -3,13 +3,66 @@ The blocking tuple is `(buildId, configSchemaVersion, apiContractVersion, assetManifestHash, releaseId)`. Versions are parsed numerically. -1. additive changes preserve current required fields -2. breaking changes require a major version bump +1. a change is additive only when it adds an optional field that every + reader of the previous version tolerates; see the boundary table below +2. breaking changes require a major version bump or a reader-first deployment 3. persisted cache is discarded unless an explicit tested migration exists 4. an incompatible config or API contract blocks product mount 5. rollback restores HTML, assets, runtime config, API compatibility, and release manifest as one coherent set +## Per-boundary rules + +Whether "add a field" is safe depends on the reader, not on the writer. Old +readers stay alive: several tabs, cached app shells and rollbacks are all +supported. At a `REJECT_UNKNOWN` boundary an added field is breaking, so the +reader that accepts it must ship before any writer sends it. + +| Boundary | Reader policy | Adding a field or value | Code | +|---|---|---|---| +| Runtime config V2 (`/config.json`) | strict object; `CONFIG_SCHEMA_VERSION` is the literal `"2.0"` | breaking | `src/contracts/release-artifacts.ts:163-171` | +| `CAPABILITY_OVERRIDES` | strict; unknown capability rejected | breaking | `src/contracts/release-artifacts.ts:50-63` | +| `FEATURE_OVERRIDES` | record; unknown feature id ignored | additive | `src/contracts/release-artifacts.ts:65-80` | +| Release manifest V2 | strict object | breaking | `src/contracts/release-artifacts.ts:200-208` | +| HTTP V2 success/failure envelope | strict object (`meta` strips) | breaking | `src/adapters/http/schema-registry.ts:12-34` | +| HTTP V3 response DTO (reference feature) | `.strip()` drops unknown fields | additive | `src/features/reference-feature/contracts/reference-schemas.ts:29-35` | +| Realtime envelope | exact key set; unknown `eventType` is `MALFORMED_EVENT` | breaking | `src/adapters/realtime/event-codec.ts:126,149` | +| Browser RPC transport error code | closed vocabulary; unknown code is a protocol violation | breaking | `src/adapters/browser-rpc/browser-rpc-runtime.ts:1473` | +| Persisted client storage | versioned key; incompatible value discarded | use a new key version | `src/contracts/storage-keys.ts:138-140` | + +`CAPABILITY_OVERRIDES` and `FEATURE_OVERRIDES` differ on purpose. Feature ids +vary per build because each downstream project installs its own features, and +one shared config document may cover several builds. The capability set is +fixed by the platform version, so an unknown capability means the config was +written for a newer platform; it is treated like any other strict config +addition. + +## Schema change classifier and FE-GATE-014 + +`classifyObjectSchemaChange` (`src/contracts/compatibility.ts:110`) answers +for a reader built against `before`. It is fail-closed: only a new property +under a reader without `additionalProperties: false` is `additive`. A removed +or changed property (type, enum, nullable, format, ...), a different required +set, or any other changed keyword is `breaking`. Nothing differs: `none`. + +FE-GATE-014 (`config-compatibility`, `corepack pnpm verify:compatibility`) +runs `scripts/check-compatibility.ts`. It does two things: + +1. Classifies the hand-written cases in `config/compatibility/fixtures.json` + and fails if any result differs from `expected`. +2. Compares the committed baseline + `config/compatibility/runtime-config.schema.baseline.json` with the current + runtime config schema, which is the same `z.toJSONSchema` output the build + writes to `dist/runtime-config.schema.json` + (`scripts/generate-build-manifest.ts`). A `breaking` result fails the gate. + +The baseline stands for the schema that readers of the previous release +accept. When a breaking config change is intended, deploy the reader first (or +bump the config major version), then run +`corepack pnpm verify:compatibility --update-baseline` and commit the new +baseline with the change. The result is recorded in +`artifacts/release/compatibility.json`. + The current `apiContractVersion` check proves release/config coherence, not provider conformance by itself. The target multi-protocol contract set binds REST/OpenAPI artifacts, GraphQL schema and persisted-operation manifests, diff --git a/scripts/check-compatibility.ts b/scripts/check-compatibility.ts index 32f3a9ba..686a03aa 100644 --- a/scripts/check-compatibility.ts +++ b/scripts/check-compatibility.ts @@ -1,53 +1,72 @@ -import { mkdir, readFile } from "node:fs/promises"; +import { mkdir, readFile, writeFile } from "node:fs/promises"; -import { classifyObjectSchemaChange } from "../src/contracts/compatibility.ts"; +import { z } from "zod"; + +import { + classifyObjectSchemaChange, + type ObjectSchemaShape, + type SchemaChangeClassification, +} from "../src/contracts/compatibility.ts"; +import { runtimeConfigV2ArtifactSchema } from "../src/contracts/release-artifacts.ts"; import { compatibilityFixturesArtifactSchema } from "./contracts/release-artifacts.ts"; import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts"; -type CompatibilitySchema = Readonly<{ - required?: readonly string[]; - properties?: Readonly>; -}>; - -type CompatibilityFixture = Readonly<{ - before: CompatibilitySchema; - after: CompatibilitySchema; -}>; +// FE-GATE-014 (07-02, 13-10). The committed baseline stands in for the schema +// the previous release's reader accepts; the current schema is exactly what +// the build writes to dist/runtime-config.schema.json. +const BASELINE_PATH = "config/compatibility/runtime-config.schema.baseline.json"; type CompatibilityFixtures = Readonly<{ - families: Readonly< - Record>> - >; + cases: readonly Readonly<{ + id: string; + expected: SchemaChangeClassification; + before: ObjectSchemaShape; + after: ObjectSchemaShape; + }>[]; }>; +const current = z.toJSONSchema(runtimeConfigV2ArtifactSchema); +if (process.argv.includes("--update-baseline")) { + await writeFile(BASELINE_PATH, `${JSON.stringify(current, null, 2)}\n`); + process.stdout.write(`Updated ${BASELINE_PATH}\n`); + process.exit(0); +} + const fixtures = JSON.parse( await readFile("config/compatibility/fixtures.json", "utf8"), ) as CompatibilityFixtures; -const results = []; +const results = fixtures.cases.map(({ id, expected, before, after }) => { + const actual = classifyObjectSchemaChange(before, after); + return { id, expected, actual, passed: actual === expected }; +}); -for (const [family, cases] of Object.entries(fixtures.families)) { - for (const expected of ["additive", "breaking"] as const) { - const fixture = cases[expected]; - const actual = classifyObjectSchemaChange(fixture.before, fixture.after); - results.push({ family, expected, actual, passed: actual === expected }); - } -} +const baselineClassification = classifyObjectSchemaChange( + JSON.parse(await readFile(BASELINE_PATH, "utf8")) as ObjectSchemaShape, + current as ObjectSchemaShape, +); +const baseline = { + path: BASELINE_PATH, + classification: baselineClassification, + passed: baselineClassification !== "breaking", +}; await mkdir("artifacts/release", { recursive: true }); await writeValidatedJsonArtifact({ path: "artifacts/release/compatibility.json", schema: compatibilityFixturesArtifactSchema, value: { - schemaVersion: 1, + schemaVersion: 2, generatedAt: new Date().toISOString(), rules: [ - "additive changes preserve required fields", - "breaking changes require version bump and migration, discard, fallback, or rollback", + "a change is additive only when it adds a property under a reader that tolerates unknown keys", + "type, enum, nullable, required-set and unmodelled changes are breaking (fail-closed)", + "adding a field at a strict (REJECT_UNKNOWN) boundary is breaking: deploy the reader first", "config and API major versions must match", "incompatible persisted cache is discarded by default", "rollback uses a coherent compatibility tuple", ], results, + baseline, }, }); @@ -55,4 +74,14 @@ if (results.some((result) => !result.passed)) { process.stderr.write("Compatibility fixture classification failed.\n"); process.exit(1); } -process.stdout.write("Compatibility fixtures: PASS\n"); +if (!baseline.passed) { + process.stderr.write( + `Runtime config schema change is breaking for readers of ${BASELINE_PATH}.\n` + + "Follow docs/contracts/compatibility.md (deploy readers first), then run\n" + + "`corepack pnpm verify:compatibility --update-baseline` and commit the baseline.\n", + ); + process.exit(1); +} +process.stdout.write( + `Compatibility fixtures: PASS; runtime config schema vs baseline: ${baseline.classification}\n`, +); diff --git a/scripts/contracts/release-artifacts.ts b/scripts/contracts/release-artifacts.ts index 51774877..b4fd743f 100644 --- a/scripts/contracts/release-artifacts.ts +++ b/scripts/contracts/release-artifacts.ts @@ -1338,32 +1338,41 @@ export const supplyChainProviderFixturesArtifactSchema = z } }); -const compatibilityClassificationSchema = z.enum(["additive", "breaking"]); +const compatibilityClassificationSchema = z.enum(["additive", "breaking", "none"]); export const compatibilityFixturesArtifactSchema = z .object({ - schemaVersion: z.literal(1), + schemaVersion: z.literal(2), generatedAt: timestamp, - rules: z.array(nonEmptyString).length(5), + rules: z.array(nonEmptyString).min(1), results: z.array( z .object({ - family: z.enum(["api", "config", "storage", "release"]), + id: nonEmptyString, expected: compatibilityClassificationSchema, actual: compatibilityClassificationSchema, passed: z.boolean(), }) .strict(), - ).length(8), + ).min(1), + baseline: z + .object({ + path: nonEmptyString, + classification: compatibilityClassificationSchema, + passed: z.boolean(), + }) + .strict(), }) .strict() .superRefine((artifact, context) => { - const keys = artifact.results.map(({ family, expected }) => `${family}\0${expected}`); - addUniqueStringIssues(keys, ["results"], context); + addUniqueStringIssues(artifact.results.map(({ id }) => id), ["results"], context); artifact.results.forEach((result, index) => { if (result.passed !== (result.actual === result.expected)) { context.addIssue({ code: "custom", path: ["results", index, "passed"], message: "must agree with expected and actual" }); } }); + if (artifact.baseline.passed !== (artifact.baseline.classification !== "breaking")) { + context.addIssue({ code: "custom", path: ["baseline", "passed"], message: "must fail exactly when the baseline change is breaking" }); + } }); export const documentationReviewArtifactSchema = z diff --git a/src/contracts/compatibility.ts b/src/contracts/compatibility.ts index 486a9548..4d0b42de 100644 --- a/src/contracts/compatibility.ts +++ b/src/contracts/compatibility.ts @@ -82,26 +82,63 @@ export function verifyCompatibilityTuple(input: Readonly<{ export type ObjectSchemaShape = Readonly<{ required?: readonly string[]; properties?: Readonly>; + additionalProperties?: unknown; }>; export type SchemaChangeClassification = "breaking" | "additive" | "none"; +function canonicalJson(value: unknown): string { + return JSON.stringify(value, (_key, item: unknown) => + item && typeof item === "object" && !Array.isArray(item) + ? Object.fromEntries( + Object.entries(item).sort(([left], [right]) => + left < right ? -1 : left > right ? 1 : 0, + ), + ) + : item, + ); +} + +/** + * Classifies an object schema change as seen by a reader built against + * `before` (07-02, 13-10). Fail-closed: the only "additive" change is a new + * property under a reader that tolerates unknown keys. Anything else that + * differs — removed or changed properties (type, enum, nullable, ...), a + * different required set, a new property under `additionalProperties: false`, + * or any other keyword — is "breaking". + */ export function classifyObjectSchemaChange( before: ObjectSchemaShape, after: ObjectSchemaShape, ): SchemaChangeClassification { - const beforeRequired = new Set(before.required ?? []); - const afterRequired = new Set(after.required ?? []); - const removedProperties = Object.keys(before.properties ?? {}).filter( - (key) => !(key in (after.properties ?? {})), + const { + properties: beforeProperties = {}, + required: beforeRequired = [], + ...beforeRest + } = before; + const { + properties: afterProperties = {}, + required: afterRequired = [], + ...afterRest + } = after; + if ( + canonicalJson(beforeRest) !== canonicalJson(afterRest) || + canonicalJson([...beforeRequired].sort()) !== + canonicalJson([...afterRequired].sort()) + ) { + return "breaking"; + } + for (const [key, schema] of Object.entries(beforeProperties)) { + if ( + !Object.hasOwn(afterProperties, key) || + canonicalJson(schema) !== canonicalJson(afterProperties[key]) + ) { + return "breaking"; + } + } + const added = Object.keys(afterProperties).filter( + (key) => !Object.hasOwn(beforeProperties, key), ); - const addedRequired = [...afterRequired].filter( - (key) => !beforeRequired.has(key), - ); - if (removedProperties.length > 0 || addedRequired.length > 0) return "breaking"; - - const addedProperties = Object.keys(after.properties ?? {}).filter( - (key) => !(key in (before.properties ?? {})), - ); - return addedProperties.length > 0 ? "additive" : "none"; + if (added.length === 0) return "none"; + return before.additionalProperties === false ? "breaking" : "additive"; } diff --git a/tests/unit/compatibility.test.ts b/tests/unit/compatibility.test.ts index bc0654e7..2666d5e0 100644 --- a/tests/unit/compatibility.test.ts +++ b/tests/unit/compatibility.test.ts @@ -1,4 +1,7 @@ +import { readFileSync } from "node:fs"; + import { describe, expect, it } from "vitest"; +import { z } from "zod"; import { classifyObjectSchemaChange, @@ -6,6 +9,7 @@ import { parseNumericVersion, verifyCompatibilityTuple, } from "../../src/contracts/compatibility.ts"; +import { runtimeConfigV2ArtifactSchema } from "../../src/contracts/release-artifacts.ts"; describe("contract compatibility", () => { it("uses numeric version parsing rather than lexical comparison", () => { @@ -15,6 +19,11 @@ describe("contract compatibility", () => { expect(isVersionCompatible("next", "1.0")).toBe(false); }); + it("rejects a runtime whose minor version is lower than the supported one", () => { + expect(isVersionCompatible("2.1", "2.0")).toBe(false); + expect(isVersionCompatible("2.1", "2.1")).toBe(true); + }); + it("distinguishes additive and breaking object changes", () => { const base = { required: ["id"], properties: { id: {} } }; expect( @@ -31,6 +40,74 @@ describe("contract compatibility", () => { ).toBe("breaking"); }); + it("classifies changes it cannot prove compatible as breaking", () => { + const base = { + required: ["id"], + properties: { + id: { type: "string" }, + state: { type: "string", enum: ["A", "B"] }, + note: { type: "string" }, + }, + }; + const withProperty = (key: string, schema: unknown) => ({ + ...base, + properties: { ...base.properties, [key]: schema }, + }); + expect(classifyObjectSchemaChange(base, base)).toBe("none"); + expect( + classifyObjectSchemaChange(base, withProperty("id", { type: "number" })), + ).toBe("breaking"); + expect( + classifyObjectSchemaChange( + base, + withProperty("state", { type: "string", enum: ["A"] }), + ), + ).toBe("breaking"); + expect( + classifyObjectSchemaChange( + base, + withProperty("note", { type: ["string", "null"] }), + ), + ).toBe("breaking"); + expect(classifyObjectSchemaChange(base, { ...base, required: [] })).toBe( + "breaking", + ); + expect( + classifyObjectSchemaChange(base, { ...base, additionalProperties: false }), + ).toBe("breaking"); + }); + + it("treats a property added under a reader that rejects unknown keys as breaking", () => { + const strict = { + required: ["id"], + properties: { id: {} }, + additionalProperties: false, + }; + expect( + classifyObjectSchemaChange(strict, { + ...strict, + properties: { id: {}, displayName: {} }, + }), + ).toBe("breaking"); + }); + + it("classifies an optional runtime config key as breaking against the committed baseline", () => { + const baseline = JSON.parse( + readFileSync("config/compatibility/runtime-config.schema.baseline.json", "utf8"), + ) as Record; + const current = z.toJSONSchema(runtimeConfigV2ArtifactSchema) as Record< + string, + unknown + > & { properties: Record }; + expect(classifyObjectSchemaChange(baseline, current)).toBe("none"); + expect( + classifyObjectSchemaChange(baseline, { + ...current, + properties: { ...current.properties, NEW_OPTIONAL_KEY: { type: "string" } }, + }), + ).toBe("breaking"); + }); + it("treats release ID mismatch as a warning when the blocking tuple is coherent", () => { const frontend = { buildId: "build-a", From edf44a2253fe487ae3573a48dd1fadf32f37794d Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 26 Sep 2026 00:05:06 +0900 Subject: [PATCH 099/185] fix(config): keep public/config.json equal to the local profile (F-5, 13-15) public/config.json is the copy dev serves and nothing compared it with config/runtime/local.json. A unit test now requires it to equal what a local build writes, and sample removal drops the feature override from it too. Co-Authored-By: Claude Opus 5.5 --- README.md | 4 ++-- scripts/test-sample-removal.ts | 22 ++++++++++------------ tests/unit/deployment-admission.test.ts | 7 +++++++ 3 files changed, 19 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index ba496cf9..afa71002 100644 --- a/README.md +++ b/README.md @@ -33,8 +33,8 @@ build` writes `dist/config.json` from the selected profile (`scripts/generate-runtime-config.ts`). `public/config.json` is only the local profile for `corepack pnpm dev`; the build replaces it, so settings put there never reach a deployment. Keep it equal to `config/runtime/local.json` plus -`BUILD_ID: local-build` and `RELEASE_ID: local-release`; nothing checks that -yet. +`BUILD_ID: local-build` and `RELEASE_ID: local-release`; +`tests/unit/deployment-admission.test.ts` fails when the two differ. Build and deploy variables, lowest precedence first: diff --git a/scripts/test-sample-removal.ts b/scripts/test-sample-removal.ts index 8113f6c1..55d6c10d 100644 --- a/scripts/test-sample-removal.ts +++ b/scripts/test-sample-removal.ts @@ -244,18 +244,16 @@ try { // Runtime profiles are product configuration. Once the feature is physically // removed, its override key must disappear too or the built config still - // advertises a source capability that no longer exists. - for (const profile of [ - "local", - "development", - "staging", - "production", - ] as const) { - const profilePath = path.join( - fixtureRoot, - "config/runtime", - `${profile}.json`, - ); + // advertises a source capability that no longer exists. public/config.json + // is the local profile `dev` serves and has to stay equal to it (F-5). + for (const configPath of [ + "config/runtime/local.json", + "config/runtime/development.json", + "config/runtime/staging.json", + "config/runtime/production.json", + "public/config.json", + ]) { + const profilePath = path.join(fixtureRoot, configPath); const runtimeConfig = JSON.parse( await readFile(profilePath, "utf8"), ) as { diff --git a/tests/unit/deployment-admission.test.ts b/tests/unit/deployment-admission.test.ts index 2d3c57cb..4cff7b37 100644 --- a/tests/unit/deployment-admission.test.ts +++ b/tests/unit/deployment-admission.test.ts @@ -204,6 +204,13 @@ describe("runtime config profiles", () => { ).toBeGreaterThan(0); }); + // F-5 (13-15). `corepack pnpm dev` serves public/config.json while every + // build writes the local profile instead, so the two copies must not drift. + it("keeps public/config.json equal to what a local build writes", async () => { + const served: unknown = JSON.parse(await readFile("public/config.json", "utf8")); + expect(served).toEqual(await generateRuntimeConfig("local", {})); + }); + // 13-01: the build profile and the admission target are two repository // variables. A staging profile left in place for a production release has to // stop the release, whatever the built document happens to say. From 02d3fdf546ed4b3b33f8a978e8a8cda17bc8240b Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 26 Sep 2026 00:06:14 +0900 Subject: [PATCH 100/185] fix(realtime): carry SSE Retry-After into the reconnect outcome (04-02) A 429/503 Retry-After reached only onRetryHint, so passing the read result to the reconnect coordinator retried before the server allowed. readSseForReconnect returns the hint as serverNotBeforeMs. Co-Authored-By: Claude Opus 5.5 --- .../realtime/sse/fetch-sse-connection.ts | 23 +++++++ src/adapters/realtime/sse/index.ts | 1 + .../realtime-reconnect-coordinator.test.ts | 66 +++++++++++++++++++ 3 files changed, 90 insertions(+) diff --git a/src/adapters/realtime/sse/fetch-sse-connection.ts b/src/adapters/realtime/sse/fetch-sse-connection.ts index 049a186b..f197c047 100644 --- a/src/adapters/realtime/sse/fetch-sse-connection.ts +++ b/src/adapters/realtime/sse/fetch-sse-connection.ts @@ -12,6 +12,7 @@ import { } from "../../../application/ports/realtime/event-authority.ts"; import { isRealtimeResumeCursor } from "../../../contracts/realtime-events.ts"; import { systemClock } from "../../platform/system-clock.ts"; +import type { RealtimeReconnectOutcome } from "../reconnect-coordinator.ts"; import { parseRetryAfterDelay } from "../reconnect-policy.ts"; import { isRealtimeResult, @@ -468,6 +469,28 @@ export function createFetchSseConnection( return Object.freeze({ read, close }); } +/** + * Bridges one read to the reconnect coordinator's outcome shape. A validated + * Retry-After (429/503) or SSE `retry:` hint reaches only `onRetryHint`, not + * the failure, so a plain `read` result lets the coordinator retry early. + */ +export async function readSseForReconnect( + connection: FetchSseConnection, + input: FetchSseReadInput, +): Promise> { + let serverNotBeforeMs: number | null = null; + const result = await connection.read({ + ...input, + onRetryHint(retryMs) { + serverNotBeforeMs = retryMs; + input.onRetryHint?.(retryMs); + }, + }); + return Object.freeze( + result.ok ? { result } : { result, serverNotBeforeMs }, + ); +} + function fixedEndpoint(endpoint: string, applicationOrigin: string): URL { let parsedEndpoint: URL; let parsedOrigin: URL; diff --git a/src/adapters/realtime/sse/index.ts b/src/adapters/realtime/sse/index.ts index 49cc802c..7608a3b8 100644 --- a/src/adapters/realtime/sse/index.ts +++ b/src/adapters/realtime/sse/index.ts @@ -1,5 +1,6 @@ export { createFetchSseConnection, + readSseForReconnect, SSE_CONTINUE, type FetchSseClosedOutcome, type FetchSseConnection, diff --git a/tests/unit/realtime/realtime-reconnect-coordinator.test.ts b/tests/unit/realtime/realtime-reconnect-coordinator.test.ts index 268304c8..5d9a06d4 100644 --- a/tests/unit/realtime/realtime-reconnect-coordinator.test.ts +++ b/tests/unit/realtime/realtime-reconnect-coordinator.test.ts @@ -30,6 +30,7 @@ import { } from "../../../src/adapters/realtime/result.ts"; import { createFetchSseConnection, + readSseForReconnect, SSE_CONTINUE, } from "../../../src/adapters/realtime/sse/fetch-sse-connection.ts"; import { @@ -1879,4 +1880,69 @@ describe("transport failures through the reconnect coordinator", () => { expect(fetcher).toHaveBeenCalledTimes(2); }, ); + + it.each([429, 503])( + "waits at least the SSE %i Retry-After through the reconnect bridge", + async (status) => { + const clock = new ManualClock(); + const fetcher = vi + .fn() + .mockResolvedValueOnce( + new Response(null, { + status, + headers: { "retry-after": "3" }, + }), + ) + .mockResolvedValueOnce( + new Response(null, { + status, + headers: { "retry-after": "10" }, + }), + ); + const coordinator = createRealtimeReconnectCoordinator({ + policy: policy({ maxDelayMs: 5_000, maxElapsedMs: 60_000 }), + environment: new MutableOnlineEnvironment(true), + clock, + random: () => 0.5, + confirmTransportBarrier: confirmationSucceeded, + attempt: async (context) => { + const read = await readSseForReconnect( + createFetchSseConnection({ + endpoint: "https://app.example.test/events", + applicationOrigin: "https://app.example.test", + recoveryMode: "CURSOR", + fetcher, + clock, + }), + { + resumeCursor: null, + signal: context.signal, + onEvent: () => realtimeSuccess(SSE_CONTINUE), + }, + ); + // Only connect failures are exercised here. + if (read.result.ok) { + return failed( + realtimeFailure("PROTOCOL_MISMATCH", "CONNECT", false), + ); + } + return read as RealtimeReconnectOutcome; + }, + }); + + // 10_000 is each read's connect timeout; 3_000 is the reconnect wait. + const running = coordinator.run(); + await flushUntil(() => clock.sleepCalls.length === 2); + expect(clock.sleepCalls).toEqual([10_000, 3_000]); + clock.advance(3_000); + + // A hint above the policy's maxDelayMs still ends the run. + await expect(running).resolves.toMatchObject({ + ok: false, + error: { operation: "CONNECT", retryable: true }, + }); + expect(fetcher).toHaveBeenCalledTimes(2); + expect(clock.sleepCalls).toEqual([10_000, 3_000, 10_000]); + }, + ); }); From e6c683eb4fe5849cb9676d4790caf19b3eaf65e9 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 26 Sep 2026 00:06:48 +0900 Subject: [PATCH 101/185] fix(web-push): serialize push control across tabs with a Web Lock (06-02) Tabs share one native subscription and one origin fence. enable, reconcile and revoke now run under the `web-push-control` Web Lock (D-4), and a compensation unsubscribes only a subscription its own call created. Co-Authored-By: Claude Opus 5.5 --- ...ime-events-web-push-and-bounded-polling.md | 10 + .../web-push/push-subscription-adapter.ts | 52 +++- .../web-push-subscription-adapter.test.ts | 223 +++++++++++++++++- 3 files changed, 271 insertions(+), 14 deletions(-) diff --git a/docs/architecture/realtime-events-web-push-and-bounded-polling.md b/docs/architecture/realtime-events-web-push-and-bounded-polling.md index fc581c94..bf5e5a31 100644 --- a/docs/architecture/realtime-events-web-push-and-bounded-polling.md +++ b/docs/architecture/realtime-events-web-push-and-bounded-polling.md @@ -1281,6 +1281,16 @@ user opt-in `matchAll()`이 signal을 따르지 않거나 `waitUntil()`이 동기 예외를 내도 늦은 `postMessage`를 허용하지 않고 degraded observation으로 닫는다. - re-subscribe가 실패하면 notification을 끄고 foreground fallback을 유지한다. +- 여러 tab은 native subscription(worker registration당 1개)과 origin의 fence + record를 공유한다. 그래서 `enable`·`reconcile`·`revoke`는 origin 단위 Web Lock + `web-push-control` 안에서 하나씩 실행한다. `inspect`는 읽기만 하므로 lock을 + 잡지 않는다. composition이 `navigator.locks`를 `lockManager`로 넘기고, Web + Locks가 없으면 `PUSH_UNSUPPORTED`로 보고한다 + (`src/adapters/web-push/push-subscription-adapter.ts`의 `exclusive`, + `supportReadiness`). activate 실패나 session binding 불일치의 보상은 backend + association을 revoke하지만 native `unsubscribe()`는 그 호출이 새로 만든 + subscription에만 한다. 이미 있던 subscription은 다른 tab의 association일 수 + 있다(`activateCommit`, 06-02). `associationEpoch`은 backend registration authority가 발급한다. `releaseEpoch`은 signed/verified release manifest에서 온다. backend registration diff --git a/src/adapters/web-push/push-subscription-adapter.ts b/src/adapters/web-push/push-subscription-adapter.ts index 418c2297..843a1f0c 100644 --- a/src/adapters/web-push/push-subscription-adapter.ts +++ b/src/adapters/web-push/push-subscription-adapter.ts @@ -88,6 +88,13 @@ export function createWebPushSubscriptionAdapter( backendOperationDeadlineMs?: number; scheduler?: TimeoutScheduler; observer?: WebPushObserver; + /** + * 06-02 (D-4). The composition passes `navigator.locks`. Every tab shares + * one native subscription and one origin fence, so enable, reconcile and + * revoke run under the origin-wide `web-push-control` lock. Without Web + * Locks the adapter reports `PUSH_UNSUPPORTED`. + */ + lockManager?: Pick; }>, ): WebPushControlPort { const decodedVapidPublicKey = decodeVapidPublicKey( @@ -119,6 +126,11 @@ export function createWebPushSubscriptionAdapter( } const idempotencyKeyFactory = dependencies.idempotencyKeyFactory ?? (() => globalThis.crypto.randomUUID()); + const lockManager = dependencies.lockManager; + const requestLock = + typeof lockManager?.request === "function" + ? lockManager.request.bind(lockManager) + : null; let closed = false; let busy = false; let lifecycleGeneration = 0; @@ -383,6 +395,7 @@ export function createWebPushSubscriptionAdapter( commit: reconciled.value, signal: operationSignal, generation, + created: false, }); }, ); @@ -507,15 +520,22 @@ export function createWebPushSubscriptionAdapter( const generation = lifecycleGeneration; const operation = createLinkedAbortController(signal); inFlight.add(operation); + const run = () => task(generation, operation.signal); try { try { - return await task(generation, operation.signal); + // 06-02 (D-4). Inspection only reads; mutations wait for other tabs. + return failureOperation === "SUBSCRIPTION_INSPECT" || !requestLock + ? await run() + : await requestLock( + WEB_PUSH_CONTROL_LOCK, + { signal: operation.signal }, + run, + ); } catch { - return webPushFailure( - "NATIVE_FAILURE", - failureOperation, - true, - ); + // An abort while waiting for the lock rejects the request. + return operation.signal.aborted + ? webPushFailure("ABORTED", failureOperation) + : webPushFailure("NATIVE_FAILURE", failureOperation, true); } } finally { operation.dispose(); @@ -525,7 +545,7 @@ export function createWebPushSubscriptionAdapter( } function supportReadiness(): WebPushReadiness | null { - if (!dependencies.secureContext) { + if (!dependencies.secureContext || !requestLock) { return readiness("PUSH_UNSUPPORTED"); } if (!dependencies.registration.active) { @@ -703,6 +723,7 @@ export function createWebPushSubscriptionAdapter( commit: registered.value, signal: input.signal, generation: input.generation, + created: input.created, }); } @@ -713,13 +734,17 @@ export function createWebPushSubscriptionAdapter( commit: WebPushRegistrationCommit; signal: AbortSignal | undefined; generation: number; + created: boolean; }>): Promise> { + // 06-02 (D-4). A subscription this call did not create may carry another + // tab's association, so compensation leaves it in place. + const createdSubscription = input.created ? input.subscription : null; if ( input.commit.sessionBindingEpoch !== input.authority.sessionBindingEpoch || stale(input.signal, input.generation) ) { - await compensate(input.subscription, input.commit.associationEpoch); + await compensate(createdSubscription, input.commit.associationEpoch); return webPushSuccess( unavailable("SESSION_AUTHORITY_CHANGED"), ); @@ -732,21 +757,23 @@ export function createWebPushSubscriptionAdapter( signal: input.signal, }); if (!activated.ok) { - await compensate(input.subscription, input.commit.associationEpoch); + await compensate(createdSubscription, input.commit.associationEpoch); return webPushSuccess(unavailable("LOCAL_FENCE_UNSAFE")); } return webPushSuccess(readiness("PUSH_READY")); } async function compensate( - subscription: WindowPushSubscriptionFacade, + createdSubscription: WindowPushSubscriptionFacade | null, associationEpoch: string, ): Promise { await withAbortableDeadline( async (signal) => { await Promise.allSettled([ boundedBackendRevoke(associationEpoch, signal), - safeUnsubscribe(subscription), + createdSubscription + ? safeUnsubscribe(createdSubscription) + : Promise.resolve(true), ]); return webPushSuccess(undefined); }, @@ -1007,6 +1034,9 @@ export function createWebPushSubscriptionAdapter( } } +/** 06-02 (D-4). Origin-wide Web Lock name shared by every tab. */ +const WEB_PUSH_CONTROL_LOCK = "web-push-control"; + function readiness( state: WebPushReadiness["state"], ): WebPushReadiness { diff --git a/tests/unit/web-push-subscription-adapter.test.ts b/tests/unit/web-push-subscription-adapter.test.ts index 1c01f76f..54db0040 100644 --- a/tests/unit/web-push-subscription-adapter.test.ts +++ b/tests/unit/web-push-subscription-adapter.test.ts @@ -153,6 +153,7 @@ describe("Web Push window subscription adapter", () => { fenceStore, gateway: gateway({ register }), vapidPublicKey, + lockManager: navigator.locks, now: () => now, idempotencyKeyFactory: () => "idempotency_01", }); @@ -207,6 +208,7 @@ describe("Web Push window subscription adapter", () => { fenceStore, gateway: gateway({ register }), vapidPublicKey, + lockManager: navigator.locks, now: () => now, }); @@ -224,7 +226,12 @@ describe("Web Push window subscription adapter", () => { expect(await fenceStore.read()).toEqual({ ok: true, value: null }); }); - it("compensates a stale backend session binding without activating local authority", async () => { + // 06-02 (D-4). Only a subscription this call created is unsubscribed; an + // existing one may belong to another tab's association. + it.each([ + { existing: true, unsubscribeCalls: 0 }, + { existing: false, unsubscribeCalls: 1 }, + ])("compensates a stale backend session binding without activating local authority (existing native: $existing)", async ({ existing, unsubscribeCalls }) => { const fenceStore = createPushAssociationFenceStore( createFakePushControlStoreDependencies(), ); @@ -241,7 +248,7 @@ describe("Web Push window subscription adapter", () => { registration: { active: true, pushManager: { - getSubscription: async () => native, + getSubscription: async () => (existing ? native : null), subscribe: async () => native, }, getNotifications: async () => [], @@ -256,6 +263,7 @@ describe("Web Push window subscription adapter", () => { revoke, }), vapidPublicKey, + lockManager: navigator.locks, now: () => now, idempotencyKeyFactory: () => "idempotency_01", }); @@ -276,7 +284,7 @@ describe("Web Push window subscription adapter", () => { associationEpoch: "association_stale", signal: expect.any(AbortSignal), }); - expect(unsubscribe).toHaveBeenCalledOnce(); + expect(unsubscribe).toHaveBeenCalledTimes(unsubscribeCalls); expect(await fenceStore.read()).toMatchObject({ ok: true, value: { @@ -346,6 +354,7 @@ describe("Web Push window subscription adapter", () => { fenceStore, gateway: gateway({ revoke }), vapidPublicKey, + lockManager: navigator.locks, now: () => now, }); @@ -417,6 +426,7 @@ describe("Web Push window subscription adapter", () => { fenceStore, gateway: gateway(), vapidPublicKey, + lockManager: navigator.locks, now: () => now, }); @@ -486,6 +496,7 @@ describe("Web Push window subscription adapter", () => { fenceStore, gateway: gateway({ revoke }), vapidPublicKey, + lockManager: navigator.locks, now: () => now, }); @@ -553,6 +564,7 @@ describe("Web Push window subscription adapter", () => { fenceStore, gateway: gateway({ revoke }), vapidPublicKey, + lockManager: navigator.locks, now: () => now, }); @@ -609,6 +621,7 @@ describe("Web Push window subscription adapter", () => { fenceStore, gateway: gateway({ revoke }), vapidPublicKey, + lockManager: navigator.locks, now: () => now, }); @@ -658,6 +671,7 @@ describe("Web Push window subscription adapter", () => { fenceStore, gateway: gateway(), vapidPublicKey, + lockManager: navigator.locks, nativeOperationDeadlineMs: 1, scheduler: clock.scheduler, }); @@ -694,6 +708,7 @@ describe("Web Push window subscription adapter", () => { fenceStore, gateway: gateway(), vapidPublicKey, + lockManager: navigator.locks, }); const inspection = adapter.inspect({ authority }); @@ -729,6 +744,7 @@ describe("Web Push window subscription adapter", () => { fenceStore, gateway: gateway(), vapidPublicKey, + lockManager: navigator.locks, }); for (let attempt = 0; attempt < 2; attempt += 1) { @@ -792,6 +808,7 @@ describe("Web Push window subscription adapter", () => { revoke, }), vapidPublicKey, + lockManager: navigator.locks, backendOperationDeadlineMs: 1, scheduler: clock.scheduler, idempotencyKeyFactory: () => "idempotency_01", @@ -862,6 +879,7 @@ describe("Web Push reconcile with a server ABSENT association (R-6.7)", () => { reconcile: async () => webPushSuccess({ state: "ABSENT" as const }), }), vapidPublicKey, + lockManager: navigator.locks, now: () => now, idempotencyKeyFactory: () => "idempotency_02", }); @@ -943,3 +961,202 @@ describe("Web Push reconcile with a server ABSENT association (R-6.7)", () => { }, ); }); + +/** + * 06-02 (D-4). The native subscription is one per service worker registration + * and the fence record one per origin, so every tab shares both. enable, + * reconcile and revoke hold the origin-wide `web-push-control` Web Lock + * (Node's `navigator.locks` here, shared by both adapters like two tabs), and + * a compensation unsubscribes only a subscription its own call created. + */ +describe("06-02 two tabs share one native subscription and one fence", () => { + function sharedTabs( + reconcileAnswer: ( + serverAssociation: string | null, + ) => Promise<"WAIT_FOR_REGISTER" | "NOW">, + lockManager: Pick | null = navigator.locks, + ) { + const dependencies = createFakePushControlStoreDependencies(); + const unsubscribe = vi.fn(async () => { + current = null; + return true; + }); + const native = subscription(unsubscribe); + let current: WindowPushSubscriptionFacade | null = null; + const server: { association: string | null } = { association: null }; + let releaseRegister!: () => void; + const registerGate = new Promise((resolve) => { + releaseRegister = resolve; + }); + let registerReached!: () => void; + const registerStarted = new Promise((resolve) => { + registerReached = resolve; + }); + const shared: WebPushRegistrationGateway = { + async register() { + registerReached(); + await registerGate; + server.association = "association_01"; + return webPushSuccess({ + associationEpoch: "association_01", + sessionBindingEpoch: "session_01", + }); + }, + async reconcile() { + if ((await reconcileAnswer(server.association)) === "WAIT_FOR_REGISTER") { + await registerGate; + } + return webPushSuccess( + server.association + ? { + state: "ACTIVE" as const, + associationEpoch: server.association, + sessionBindingEpoch: "session_01", + } + : { state: "ABSENT" as const }, + ); + }, + async revoke(input) { + if (server.association === input.associationEpoch) { + server.association = null; + } + return webPushSuccess({ state: "REVOKED" as const }); + }, + }; + function tab(activation: boolean) { + return createWebPushSubscriptionAdapter({ + secureContext: true, + userActivationIsActive: () => activation, + permission: { + permission: () => "granted", + requestPermission: async () => "granted", + }, + registration: { + active: true, + pushManager: { + getSubscription: async () => current, + subscribe: async () => { + current = native; + return native; + }, + }, + getNotifications: async () => [], + }, + fenceStore: createPushAssociationFenceStore(dependencies), + gateway: shared, + vapidPublicKey, + now: () => now, + ...(lockManager ? { lockManager } : {}), + }); + } + return { + tab, + server, + unsubscribe, + registerStarted, + releaseRegister: () => releaseRegister(), + nativeAlive: () => current === native, + fence: async () => + await createPushAssociationFenceStore(dependencies).read(), + }; + } + + async function raceEnableWithReconcile( + tabs: ReturnType, + ) { + const tab1 = tabs.tab(true); + const tab2 = tabs.tab(false); + const enabling = tab1.enable({ + authority, + signal: new AbortController().signal, + }); + // Tab 1 prepared the fence, subscribed and is waiting on register. + await tabs.registerStarted; + const reconciling = tab2.reconcile({ authority }); + await new Promise((resolve) => setTimeout(resolve, 0)); + tabs.releaseRegister(); + return await Promise.all([enabling, reconciling]); + } + + function expectReadyTabsStillReceive( + tabs: ReturnType, + results: readonly unknown[], + ) { + const ready = { ok: true, value: { state: "PUSH_READY" } }; + expect(results).toContainEqual(ready); + expect(tabs.unsubscribe).not.toHaveBeenCalled(); + expect(tabs.nativeAlive()).toBe(true); + expect(tabs.server.association).toBe("association_01"); + } + + it("keeps the shared state when the reconciling tab would win the fence CAS", async () => { + // Order 1: the server commits tab 1's register, tab 2 sees it first. + const tabs = sharedTabs(async () => "WAIT_FOR_REGISTER"); + const results = await raceEnableWithReconcile(tabs); + + expect(results).toEqual([ + { ok: true, value: { state: "PUSH_READY" } }, + { ok: true, value: { state: "PUSH_READY" } }, + ]); + expectReadyTabsStillReceive(tabs, results); + expect(await tabs.fence()).toMatchObject({ + ok: true, + value: { + control: { + association: { + state: "ACTIVE", + associationEpoch: "association_01", + }, + }, + }, + }); + }); + + it("keeps the shared state when a tab reconciles during another tab's unfinished opt-in", async () => { + // Order 2: the server still answers ABSENT while tab 1's register runs. + const tabs = sharedTabs(async () => "NOW"); + const results = await raceEnableWithReconcile(tabs); + + expect(results[0]).toEqual({ ok: true, value: { state: "PUSH_READY" } }); + expectReadyTabsStillReceive(tabs, results); + }); + + it("aborts a tab that is still waiting for another tab's lock", async () => { + const tabs = sharedTabs(async () => "NOW"); + const enabling = tabs.tab(true).enable({ + authority, + signal: new AbortController().signal, + }); + await tabs.registerStarted; + const waiting = new AbortController(); + const reconciling = tabs.tab(false).reconcile({ + authority, + signal: waiting.signal, + }); + await new Promise((resolve) => setTimeout(resolve, 0)); + waiting.abort(); + + expect(await reconciling).toMatchObject({ + ok: false, + error: { code: "ABORTED", operation: "SUBSCRIPTION_RECONCILE" }, + }); + tabs.releaseRegister(); + expect(await enabling).toEqual({ + ok: true, + value: { state: "PUSH_READY" }, + }); + expect(tabs.unsubscribe).not.toHaveBeenCalled(); + }); + + it("reports PUSH_UNSUPPORTED without side effects when Web Locks are missing", async () => { + const tabs = sharedTabs(async () => "NOW", null); + expect( + await tabs.tab(true).enable({ + authority, + signal: new AbortController().signal, + }), + ).toEqual({ ok: true, value: { state: "PUSH_UNSUPPORTED" } }); + expect(tabs.nativeAlive()).toBe(false); + expect(await tabs.fence()).toEqual({ ok: true, value: null }); + }); +}); From 1cb09e42100b2ebc80aaea30866a27a2b183c2b0 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 26 Sep 2026 00:07:49 +0900 Subject: [PATCH 102/185] docs(template): add a CHANGELOG and the copied-project update procedure (14-04) A copy had no way to learn that a fix shipped or which files to take. The CHANGELOG marks security and contract changes with their paths; README says where to record the origin commit, how to cherry-pick or diff a fix and who classifies a template defect. The v0.2.0 tag is added after integration. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 40 +++++++++++++++++++++++++++ 2 files changed, 118 insertions(+) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..60591828 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,78 @@ +# 변경 이력 + +이 템플릿을 복사해 쓰는 프로젝트가 원본의 수정을 골라 가져갈 때 보는 문서다. +가져오는 방법은 `README.md`의 "Updating a copied project" 절에 있다. + +- 버전은 git 태그 `vX.Y.Z`로 식별한다. 태그 사이의 변경을 여기 적는다. +- **[보안]** 복사한 프로젝트도 가져가야 하는 보안·개인정보 수정이다. +- **[계약]** 백엔드, 배포 설정, CI, 또는 기능 코드가 함께 바뀌어야 하는 변경이다(헤더, 변수, 게이트, 공개 포트). +- 표시가 없으면 템플릿 안에서 끝나는 수정이다. +- 괄호 안 ID는 리뷰 발견 ID다. 근거와 재현 조건은 해당 리뷰 문서에 있다. +- 커밋 해시는 브랜치 `fix/maturity-review-2026-09-25` 기준이다. 병합 방식에 따라 `main`에서는 해시가 다를 수 있으니 ID로 찾는다(`git log --grep '(03-03'`). + +## 0.2.0 — 진행 중 + +2026-09-25 성숙도 리뷰(`docs/reviews/2026-09-25-maturity-review/`) 수정 묶음이다. +기준은 `main` `4626b73`이다. 통합이 끝나면 태그 `v0.2.0`을 붙이고 이 절을 확정한다. +`package.json`의 `version`은 아직 `0.1.0`이다. + +### 보안·계약 변경 + +먼저 볼 항목이다. 복사한 프로젝트가 이 경로를 고쳤다면 충돌을 직접 풀어야 한다. + +| 표시 | 변경 | 영향 경로 | 커밋 | +|---|---|---|---| +| [계약] | 모든 V3 HTTP 요청이 논리 실행마다 `x-correlation-id` 헤더를 하나 보낸다. 다른 origin API는 preflight `Access-Control-Allow-Headers`에 이 헤더를 넣어야 요청이 나간다. 응답의 같은 헤더를 읽으려면 `Access-Control-Expose-Headers`에도 넣는다 (03-03) | `src/adapters/http/http-execution-v3.ts`, `src/adapters/http/feature-http-binding.ts`, `src/bootstrap/runtime-adapters.ts`, `docs/operations/api-contract-and-server-state-recovery.md` | `c5da3cf`, `f0a6495` | +| [계약] | 결과를 모르는 쓰기(응답 유실)를 다시 보낼 때 처음의 멱등 키를 그대로 쓴다. 백엔드는 같은 키의 재전송을 한 번만 적용해야 한다 (03-01, 08-03) | `src/presentation/adapters/query/application-query.ts`, `src/presentation/forms/use-app-form.ts`, `src/presentation/components/async-surface.tsx` | `dfb1b9e` | +| [계약] | 명령의 401/403/429를 기능 패키지가 분류할 수 있다(`classifyStatus`, 선택 필드). 재로그인이 먼저다 (03-02) | `src/adapters/http/http-effect-certainty.ts`, `src/adapters/http/http-execution-v3.ts`, `src/contracts/errors.ts`, `src/contracts/external-contract-runtime.ts` | `2afee67` | +| [계약] | 422 problem body의 필드 오류(`path`, `code`)를 폼까지 전달한다 (03-04) | `src/adapters/http/feature-http-binding.ts`, `src/features/reference-feature/contracts/reference-schemas.ts` | `479acd5` | +| [계약] | 텔레메트리 수집기 이벤트마다 `build_id`, `release_id`가 붙는다. 한 번에 보내는 본문은 60KiB 아래로 나뉜다 (13-11, 03-05) | `src/adapters/telemetry/telemetry-collector.ts`, `src/bootstrap/runtime-adapters.ts` | `43e47f4`, `e14c613` | +| [보안] | 번들이 읽지 않는 `VITE_*` 값까지 통째로 넣던 문제를 고쳤다. 값은 키로만 읽고, `ENV_REGISTRY`에 없는 `VITE_*` 이름은 빌드를 멈춘다 (13-06) | `src/contracts/env.ts`, `vite.config.ts`, `eslint.config.ts` | `2ec59ad` | +| [보안] | 로그아웃·계정 삭제 purge가 손상된 IndexedDB 때문에 열리지 않으면 그 파티션의 DB를 지운다. OPFS purge는 남은 chunk를 바로 지운다 (05-03, 05-04) | `src/adapters/platform/indexeddb-connection.ts`, `src/adapters/storage/indexeddb/indexeddb-runtime.ts`, `src/adapters/storage/opfs/opfs-byte-store-adapter.ts`, `src/application/ports/browser-file-storage/` | `3e37fbf`, `6ab564f` | +| [계약] | `RELEASE_TARGET`이 `APP_PROFILE`과 다르면 배포 승인이 거절된다 (12-02, 13-01) | `scripts/check-release-admission.ts`, `.gitea/workflows/quality-gates.yml` | `239b22a` | +| [계약] | 설정·매니페스트 URL이 `VITE_ROUTER_BASE_PATH`를 따른다. base 밖의 설정 URL은 빌드를 멈춘다 (13-07) | `scripts/generate-runtime-config.ts`, `src/contracts/env.ts`, `vite.config.ts` | `e215c84` | +| [계약] | `VITE_PRODUCT_FEATURES`는 생성기에서 적용되고, 모르는 기능 ID는 빌드를 멈춘다 (09-02) | `scripts/generate-product-feature-index.ts`, `src/contracts/product-features.ts` | `a8111f7` | +| [계약] | `src/features//`에 `feature-module.ts`도 `NOT_INSTALLED` 표식도 없으면 생성기가 실패한다. 기능 제거 검사는 `--feature=`를 받는다 (09-07, 14-03) | `scripts/generate-product-feature-index.ts`, `scripts/test-sample-removal.ts`, `config/contracts/registry-governance.json`, `docs/architecture/starter-experience.md` | `ad0e83c` | +| [계약] | 기능 루트·context·app 파일은 `src/adapters`를 import할 수 없다. presentation은 app·context를 import할 수 없다(`app-router.tsx` 예외) (12-03) | `scripts/check-architecture.ts`, `.dependency-cruiser.json`, `docs/architecture/layers.md` | `f8b6a36` | +| [계약] | CI 계약의 게이트 수·해시가 `config/ci/contract-baseline.json`으로 옮겨졌다. 게이트를 바꾸면 `update:ci-contract-baseline`로 갱신한다 (14-02) | `config/ci/contract-baseline.json`, `scripts/check-ci-contract.ts` | `0114b1e` | +| [계약] | 모든 테스트 파일은 어떤 게이트가 돌리거나 `config/ci/ungated-tests.json`에 이유가 있어야 한다 (12-04, 09-11, 11-03) | `config/ci/gates.json`, `config/ci/ungated-tests.json`, `scripts/lib/ungated-tests.ts` | `840de45`, `45ee231` | +| [계약] | 게이트 판정 변경: 서명된 수동 접근성 검토는 release 게이트 FE-GATE-028로, runbook drill은 관측하지 못한 단계를 `UNVERIFIED`(exit 3)로, FE-GATE-016은 폐지, FE-GATE-019는 배포 뒤 production 단계에서 돈다 (08-06, 11-01, 13-03, 13-05) | `config/ci/gates.json`, `.gitea/workflows/quality-gates.yml`, `scripts/drill-runbook.ts`, `docs/operations/ci-quality-gates.md` | `7298275`, `7f889a6`, `a263d8c` | +| [계약] | `engineStrict`, `saveExact`를 `pnpm-workspace.yaml`로 옮겼다. 지원하지 않는 Node에서 설치가 실패한다 (13-09) | `pnpm-workspace.yaml`, `.npmrc` | `a5dc851` | +| [계약] | 폼 저장 실패에 재로그인·권한 없음·나중에 재시도 상태가 따로 생겼다 (08-01) | `src/presentation/forms/form-contracts.ts`, `src/presentation/forms/use-app-form.ts`, `src/presentation/forms/form-components.tsx` | `9894a70` | +| [계약] | browser-transfer 포트: `upload()` 실패의 recovery 값이 다섯 개로 정리됐고, 완료된 업로드는 `resourceId`를 잃지 않는다. 시간 제한이 바이트 수에 비례한다 (01-01~01-11). file-transfer recipe를 쓰는 프로젝트만 해당 | `src/application/ports/browser-transfer/`, `src/adapters/browser-transfer/` | `648fe4e`, `7b2cefb`, `5a6665a`, `426b6b8` 외 | +| [계약] | IndexedDB·OPFS 포트: 미래 스키마는 `INCOMPATIBLE`, 빈 receipt는 없음으로 본다 (05-01~05-14). offline-indexeddb recipe를 쓰는 프로젝트만 해당 | `src/application/ports/browser-file-storage/`, `src/adapters/storage/` | `7f45afa`, `47cf040`, `8fc816e` 외 | + +### 그 밖의 수정 + +- 부트: 앱 모듈 평가 실패, 분류되지 않은 오류, 재시도 가능한 실패에 오류 화면을 보여 준다 (09-03, 09-04, 09-10). `src/bootstrap/`, `src/presentation/boundaries/boot-error-shell.tsx` +- 부트: `FEATURE_OVERRIDES`의 모르는 키를 진단으로 남긴다 (09-09). `src/bootstrap/runtime-adapters.ts`, `scripts/check-release-admission.ts` +- 빌드: `dist` 파일을 다른 사용자도 읽을 수 있게 한다 (13-02). `scripts/lib/dist-permissions.ts` +- 공급망: 번들에 들어간 패키지 목록과 각 증거의 범위를 남긴다. 승격된 릴리스를 나중에 다시 검증한다 (13-12, 13-04). `scripts/lib/vite-module-inventory.ts`, `scripts/verify-exact-promotion-bundle.ts` +- 아키텍처 검사: dependency-cruiser 실행을 멈추고 import graph 하나로 검사한다. 경계 예외를 좁히고, 위반 메시지에 이유와 갈 곳을 적는다 (12-05~12-11). `scripts/check-architecture.ts` +- 기능 조립: `needs` 검사, 기능 두 개 설치 시 타입 유지, local-draft 샘플 정리 (09-01, 09-05, 09-06, 09-08, 09-12, 00-02). `src/features/`, `src/bootstrap/runtime-adapters.ts` +- 테스트 보강: production CSP 아래 빌드 smoke, 멱등 키 재사용, IndexedDB fake, KEYED 재시도 (13-08, 01-04, 05-08, 10-03) +- 샘플 제거: `test:sample-removal`이 다시 통과한다. 플랫폼 테스트가 샘플 대신 테스트 전용 기능을 쓴다 (14-01, 14-08, 00-01, 10-01). `scripts/test-sample-removal.ts`, `scripts/lib/removal-fixture.ts` +- 문서: README에 런타임 프로필·배포 변수·우선순위를 적고 `verify:documentation`이 변수 목록을 검사한다 (13-15). 성능 예산, 공급망, 운영 runbook 문서를 코드에 맞췄다 (13-13, 13-14, 03-06, 03-08). + +### 진행 중 (아직 통합되지 않음) + +아래 레인은 별도 브랜치에서 작업 중이다. 통합되면 위 두 절로 옮긴다. + +- 레인 B — browser-files·Cache Storage (02-01~02-09) +- 레인 D — realtime (04-01~04-08) +- 레인 F — Service Worker·Web Push (06-01~06-10). 푸시 구독 해지와 SW 빌드 설정이 바뀐다 +- 레인 G — contracts 호환성 규칙과 FE-GATE-014 (07-02~07-07, 13-10) +- 레인 H — presentation 문구·접근성·라우트 (07-01, 08-02, 08-04, 08-05, 08-07~08-13, 11-02) +- 레인 J — 테스트 체계 (10-02, 10-04~10-07, 11-04~11-08) +- 레인 M — 이 변경 이력, 문서 색인(`docs/README.md`), README 지원 범위 표, `public/config.json` 동기화 검사 (14-04~14-06, 13-15 후속) +- 통합 뒤 — `noUnusedLocals`, 문서 수치 현행화 (12-12, 14-07) + +## 0.1.0 — `main` `4626b73` (2026-09-24) + +태그 없이 `main`에 병합된 첫 기준이다. 이보다 앞에서 복사한 프로젝트는 아래 보안 수정부터 확인한다. + +| 표시 | 변경 | 영향 경로 | 커밋 | +|---|---|---|---| +| [보안] | 자격증명 헤더 값은 제어 문자가 없는 ByteString만 받는다. 대소문자만 다른 헤더 이름은 거절한다 (R-3.4) | `src/adapters/http/http-contract-bridge.ts`, `src/adapters/auth/external-session-adapter.ts` | `5e62b7e` | +| [보안] | REST v2 COMMAND는 POST/PUT/PATCH/DELETE만 쓴다. GET으로 선언된 명령이 CSRF 보호 없이 나가던 문제다 (R-7.4) | `src/contracts/api-operations.ts` | `f26fd18` | +| [보안] | 텔레메트리 리댁션이 문자열 중간의 토큰, URL 비밀 파라미터, 이메일을 가린다 (R-9.3) | `src/platform/telemetry/redact-telemetry.ts` | `4e0745c` | diff --git a/README.md b/README.md index afa71002..b54c70aa 100644 --- a/README.md +++ b/README.md @@ -247,3 +247,43 @@ ignored by Git while `.gitkeep` files preserve the taxonomy. Operational details are in `docs/operations/`, with incident procedures in `docs/runbooks/`. + +## Updating a copied project + +Template versions are Git tags `vX.Y.Z`. [`CHANGELOG.md`](CHANGELOG.md) lists +the changes between tags, marks security fixes **[보안]** and contract changes +**[계약]** (backend, deployment, CI or feature code must change too), and names +the affected paths. + +Record where you started. Right after copying, commit a one-line +`.template-origin` file at the root of your project with the template tag (or +commit) you copied and the date, for example `v0.2.0 2026-09-26`. + +Take a template fix with Git. `cherry-pick` works even when your repository +does not share the template's history, because it merges against the picked +commit's parent: + +```bash +git remote add template