diff --git a/CHANGELOG.md b/CHANGELOG.md index 75646dad..4691937d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,77 @@ - **[계약]** 백엔드, 배포 설정, CI, 또는 기능 코드가 함께 바뀌어야 하는 변경이다(헤더, 변수, 게이트, 공개 포트). - 표시가 없으면 템플릿 안에서 끝나는 수정이다. - 괄호 안 ID는 리뷰 발견 ID다. `MMDD/NN-MM`으로 적는다. `MMDD`는 리뷰 폴더 `docs/reviews/YYYY-MM-DD-maturity-review/`의 월일이고, 근거와 재현 조건은 그 폴더의 영역 문서에 있다. 복사한 프로젝트가 README대로 `docs/reviews/`를 지웠다면 이 폴더와 `PRODUCT.md`는 원본 템플릿 repo에서 찾는다. 라운드마다 `NN-MM`을 새로 매기므로 같은 `14-02`라도 라운드가 다르면 다른 결함이다. `F-N`은 그 라운드 `FOLLOW-UP.md`의 ID다. 리뷰 README의 절은 `MMDD README N.N`으로 적고 다시 돌린 항목은 그 뒤에 `X2`처럼 번호를 붙인다. 영역 문서가 따로 매긴 ID는 `MMDD NN 영역 P-NN-NN`, 짝 백엔드 리뷰의 ID는 `백엔드 리뷰 MMDD/NN-MM`으로 적는다. `tests/unit/changelog-review-ids.test.ts`가 라운드 없는 ID와 이 꼴을 벗어난 참조를 막는다. -- 0.2.0의 커밋 해시는 브랜치 `fix/maturity-review-2026-09-25`에서 만들었고, `main`에서도 같은 해시로 찾을 수 있다(2026-11-03에 52개 모두 확인). 그 뒤 절은 절 머리에 범위(기준 커밋과 브랜치)를 적고, 그 절의 해시는 모두 그 범위에 있다. 0.2.0의 커밋 제목은 라운드 없이 ID만 적었다(`git log --grep '03-03'`). +- 0.2.0의 커밋 해시는 브랜치 `fix/maturity-review-2026-09-25`에서 만들었고, `main`에서도 같은 해시로 찾을 수 있다(2026-11-03에 52개 모두 확인). 그 뒤 절은 절 머리에 범위(기준 커밋과 브랜치)를 적고, 그 절의 해시는 모두 그 범위에 있다. 통합에서 해시를 다시 쓴 뒤(fixup 접기, rebase)에는 절의 해시와 범위 커밋 본문의 해시를 `git merge-base --is-ancestor <해시> <브랜치 끝>`으로 하나씩 대조하고, 결과를 그 라운드 리뷰 README의 조치 절에 적는다. 1105 통합은 이 대조를 하지 않아, 올린 커밋 `287dc6f`의 본문이 다시 짓기 전 해시 둘을 가리킨다. 맞는 해시는 그 라운드 리뷰 README의 D7 행에 있다 (1106/14-02, 1105 README 16.2). 0.2.0의 커밋 제목은 라운드 없이 ID만 적었다(`git log --grep '03-03'`). + +## 미출시 — `bbde570` → 브랜치 `fix/maturity-review-2026-11-06` + +2026-11-06 성숙도 리뷰(`docs/reviews/2026-11-06-maturity-review/`) 조치다. 범위는 아래 절의 끝 `bbde570`(PR B, PR #7)부터 브랜치 `fix/maturity-review-2026-11-06`의 끝까지다. 리뷰 기록 커밋 `302d3a5` 위에 조치 브랜치 9개를 합치고, 합친 빌드로 초기 JS 기록을 다시 적었다(`5cfc3a6`). 기준점 `bbde570`을 빼면 이 절의 해시는 모두 이 범위에 있다. PR B는 아직 `main`에 없다. 아래 절을 아직 받지 않은 프로젝트는 아래 절부터 받는다. + +아래 절은 그 범위 끝(`bbde570`)의 상태다. 아래 절이 지금 값으로 적은 것을 이 범위가 바꾼 경우, 아래 절은 그대로 두고 이 절에 적었다. 예외는 처음부터 틀리게 적은 문장이다. 아래 절 "먼저 할 일" 1~3단계의 대상·바뀌는 값·증상(1106/14-01)과 2단계의 descriptor 없는 쓰기·테스트 fixture 길(1106/09-01)은 아래 절에서 바로 고쳤다. 아래 절을 이미 읽었으면 그 세 단계를 다시 읽는다. + +### 먼저 할 일 (BREAKING) + +아래 절의 "먼저 할 일"을 마친 뒤 순서대로 한다. 단계 끝의 괄호는 아래 표의 근거 행이다. 두 다운스트림 코드에 적용해 게이트를 돌려 보지는 않았다(알려진 제한). + +#### 옮기는 법 + +1. **HTTP 스키마 행에 `direction`·`unknownFieldPolicy`를 적는다.** descriptor의 입력·응답·실패 검증기로 쓰이는 스키마의 FE-REG-SCHEMA 행이 둘 중 하나를 빼면 `tests/unit/schema-metadata-policy.test.ts`(`test:unit`)가 `row states no direction, used as <방향>`이나 `row states no unknownFieldPolicy, validator <탐침 결과>`로 실패한다. 행이 아예 없으면 같은 메시지와 `no FE-REG-SCHEMA row`가 나온다. 라우트에만 쓰는 행은 그대로 둬도 된다. 객체가 아닌 본문의 검증기(`responseBody: "NONE"` 출력의 `z.undefined()` 등)는 탐침이 정책을 판정할 수 없어 `direction`만 요구한다. memento-web이 2026-11-03 조치 절 "옮기는 법" 5단계로 더하는 43행도 두 칸을 적는다 (1106/07-02) +2. **`src/presentation/i18n/catalog.ts`를 고친 제품은 `form.resendLater`를 한국어·영어 두 catalog에 더한다.** 결과 불명 요청을 같은 키로 다시 보낸 시도가 쓰기 전에 거절되면(짝 백엔드 표의 400 `VALIDATION_FAILED`·`IDEMPOTENCY_KEY_INVALID`는 빼고) 폼이 이 문구를 보인다. 키가 없으면 그 자리에 `common.unavailable` 문구가 나오고, 한 언어에만 있으면 `check:i18n`이 실패한다 (1106/03-01) +3. **디자인 토큰 CSS를 고친 제품은 `src/presentation/design-system/tokens/component.css`의 `--dialog-backdrop-weight`·`--dialog-backdrop`·`--dialog-backdrop-on-surface`를 가져온다.** `primitives.css`의 `.ui-dialog::backdrop`과 `:root:has(.ui-dialog[open])`이 이 토큰을 읽는다. 빠지면 modal 가림막이 투명해지고, 그것을 잡는 검사는 없다. memento는 이 파일을 고쳤다 (1106/08-03) +4. **IDEMPOTENT로 선언한 쓰기가 두 번 적용해도 결과가 같은지 확인한다.** `...commandMutationIdentity()`로 받은 정책은 이제 `resendSafe`를 싣는다. 그래서 IDEMPOTENT 쓰기는 결과 불명 뒤 재전송 버튼이 그려지고, 같은 입력 저장이 `UNKNOWN_EFFECT_PENDING`으로 거절되지 않는다. 백엔드가 중복을 막지 못하는 쓰기를 IDEMPOTENT로 적었다면 사용자가 다시 보내 같은 항목이 둘 생길 수 있다(매뉴얼 02 결정표 3절). memento-web의 IDEMPOTENT 쓰기는 아래 절 2단계로 옮기면 여기에 든다. `commandMutationIdentity` 결과를 `toEqual`로 비교하던 테스트는 `resendSafe`를 더한다 (1106/03-03) +5. **CI 계약 기준선을 자기 값으로 다시 기록한 제품은 받은 뒤 다시 기록한다.** FE-GATE-027의 명령 순서가 바뀌어 `gateShapeSha256`이 바뀌었다. `CI_CONTRACT_BASELINE_OWNER=<팀> CI_CONTRACT_BASELINE_REASON=<이유> corepack pnpm update:ci-contract-baseline`. 다시 기록하지 않으면 `check:ci`가 기준선 차이로 실패한다 (1106/13-01) +6. **bounded poll 조합 코드가 있는 제품만: `createBoundedPollCoordinator`가 descriptor 타입을 따라간다.** 타입 인자 없이 부르면 `operation`에서 `Operation`을 추론하고, `execute`의 `input.operation`이 그 descriptor 타입이 된다. 실행기 호출의 입력이 descriptor 입력 타입과 맞지 않으면 `check:types`가 실패한다. `outcome.value`를 겹치지 않는 타입으로 단언하던 코드도 실패할 수 있다. 입력을 맞춘다. 옛 타입으로 두려면 `createBoundedPollCoordinator`으로 적는다. `Value`만 적은 호출은 전과 같다. 두 다운스트림의 지금 코드(2026-11-06에 읽음)는 이 함수를 부르지 않는다 (1106/04-02) + +#### 옮긴 뒤 확인 + +1. 로컬 merge 게이트 14개를 돈다. 이 절 때문에 먼저 볼 것: `test:unit`(1단계), `check:i18n`(2단계), `check:ci`(5단계), `check:types`(6단계), `test:a11y`(FE-GATE-009. 한 자원을 읽는 상세 라우트에 실패 화면 기록이 없으면 `a11y.json not written:`으로 실패한다), `check:bundle`(셸에 `RUN_OUTPUT_ROOT`가 있으면 멈춘다. 지우고 돈다). +2. 제품 기능 제거 드릴(`test:sample-removal -- --feature=`)은 본문에 그 기능 ID를 적힌 그대로 한 이름으로 적은 Playwright spec을 잔여로 센다. `-`가 없는 한 단어 ID는 spec 본문에서 찾지 않는다. +3. 시각 골든: `base.css`·`primitives.css`를 받은 제품은 열린 modal을 찍은 자기 골든을 다시 찍는다(`corepack pnpm test:visual:update`). 새 시각 검사 `tests/visual/scrollbar-gutter.visual.spec.ts`는 템플릿 셸의 메뉴 버튼과 `/not-found`를 쓴다. 셸을 바꾼 제품은 그 spec을 자기 셸에 맞춘다. 제품 셸에서는 돌려 보지 않았다. +4. 배포가 있는 제품: `/service-worker.js`를 redirect 뒤에 주는 호스트는 FE-GATE-019가 FAIL이다. 그런 호스트에서는 지금도 워커 등록·업데이트·kill switch가 실패한다. +5. 초기 JS 기록(`config/scale/feature-shape-ceilings.json`)이 충돌하면 `node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write`를 다시 돌려 푼다. + +### 보안·계약 변경 + +| 표시 | 변경 | 영향 경로 | 커밋 | +|---|---|---|---| +| [계약] | FE-GATE-027이 `scan:dependency-advisories`를 `check:release-admission`보다 먼저 돈다. 공개 대상 승인이 거절된 run에도 advisory 기록(`artifacts/security/dependency-advisories.json`)이 생긴다. FE-GATE-015가 실패하면 FE-GATE-027이 돌지 않아 기록이 없다. 승인 판정과 gate 결과는 그대로이고, 거절되는 run은 scan 시간(상한 120초)만큼 늦게 끝난다. 생성 workflow는 그대로다. gate 모양 기준선 `gateShapeSha256`을 다시 기록했다. 위 "먼저 할 일" 5단계 (1106/13-01) | `config/ci/gates.json`, `config/ci/contract-baseline.json`, `scripts/scan-dependency-advisories.ts`, `docs/operations/ci-quality-gates.md` | `c5ab7a3` | +| [계약] | FE-GATE-019 live probe가 `/service-worker.js`를 같은 origin 안 redirect 뒤에 준 호스트를 FAIL로 본다(`serviceWorker` surface의 `redirect` 행, `response.redirected`나 `opaqueredirect`). 브라우저는 워커 스크립트를 redirect mode "error"로 받는다. `index`·`appRoute`의 redirect는 전처럼 받는다. 위 "옮긴 뒤 확인" 4 (1106/06-01) | `scripts/lib/hosting-probe.ts`, `docs/operations/release-cache-rollback.md`, `docs/operations/browser-file-storage-recovery.md` | `2a78169` | +| [계약] | `check:bundle`의 `generate-supply-chain.ts`·`check-bundle.ts`가 `RUN_OUTPUT_ROOT`가 비어 있지 않고 `.`도 아니면 변수 값과 이유를 적고 exit 1로 멈춘다. 빌드는 그 경로 아래에 쓰는데 두 스크립트는 checkout의 `dist`·`artifacts/`를 읽어서, 예산을 넘는 새 빌드 대신 이전 빌드로 PASS했다. `ci:gate -- FE-GATE-012`도 check-bundle 단계에서 멈춘다 (1106/12-02) | `scripts/lib/run-isolation.ts`, `scripts/check-bundle.ts`, `scripts/generate-supply-chain.ts`, `docs/testing/frontend-platform-testing-strategy.md` | `68fde02` | +| [계약] | `test:a11y`(FE-GATE-009)의 report(`scripts/write-a11y-report.ts`)가 설치된 descriptor로 한 자원을 읽는 라우트를 찾는다. 로그인이 필요한 라우트의 `paramsSchema`가, 경로 파라미터가 있고 빈 목록을 거부하는 GET의 입력 스키마인 경우다. 그 라우트에 실패 화면 기록(`artifacts/tests/a11y-data-state/`)이 없으면 `a11y.json not written:`으로 실패하고 `a11y.json`을 쓰지 않는다. 접근성 spec의 라우트 test는 시작할 때 자기 기록을 지운다. `paramsSchema`가 GET 입력과 다른 상세 라우트는 전처럼 기록만으로 정해진다. 그 GET을 부르지 않는 페이지의 라우트(하위 항목 작성 폼 등)가 GET 입력 스키마를 `paramsSchema`로 쓰면 이 검사가 실패한다. 그 라우트에 자기 `paramsSchema`를 따로 둔다 (1106/11-01) | `scripts/lib/a11y-data-state.ts`, `scripts/write-a11y-report.ts`, `tests/e2e/accessibility.spec.ts` | `9c4cddc`, `95141f1` | +| [계약] | `tests/unit/schema-metadata-policy.test.ts`가 descriptor의 입력·응답·실패 검증기로 쓰인 스키마 행이 `direction`·`unknownFieldPolicy`를 적지 않으면 실패한다. 전에는 건너뛰어서, 응답 DTO를 strict로 바꿔도 `check:registries`와 `test:unit` 어느 쪽도 보지 않았다. 템플릿 HTTP 행과 생성기가 쓰는 행은 이미 두 칸을 적는다. 탐침이 객체에 닿지 못하는 검증기(객체가 아닌 본문)는 `direction`만 요구한다. 위 "먼저 할 일" 1단계 (1106/07-02) | `tests/unit/schema-metadata-policy.test.ts`, `docs/manual/01-add-a-feature.md`, `docs/manual/reference/errors.md` | `e7b1b01`, `efe11f1` | +| [계약] | 제품 기능 제거 드릴의 `tests` 잔여에, 본문이 기능 ID나 폴더 이름을 적힌 그대로(대소문자 구분) 한 이름(앞뒤가 `[A-Za-z0-9_-]`가 아님)으로 적은 Playwright spec(`*.spec.[cm]?[jt]sx?`)이 든다. `-`가 든 이름만 찾는다. `messages`·`status` 같은 한 단어 ID는 템플릿 spec이 평범한 단어로 쓰므로 찾지 않는다. vitest는 spec을 돌지 않아 `test:all`도 잡지 못했다. vitest 테스트 본문은 전처럼 보지 않는다. 매뉴얼 01 11단계와 `errors.md`의 판정 문장을 고쳤다 (1106/16-01) | `scripts/lib/feature-residue.ts`, `docs/manual/` | `af3344b`, `eb03dab` | +| [계약] | KEYED 결과 불명 요청을 같은 키로 다시 보낸 시도가 쓰기 전 거절(429, 401, 403, 503 `RATE_LIMIT_*`, 422 `IDEMPOTENT_REQUEST_MISMATCH`, 기능이 선언한 code)이나 보내기 전 실패(`NOT_STARTED`)로 끝나면, 훅이 결과 불명과 intent·키를 남긴다. 전에는 그 판정을 논리 요청 전체의 판정으로 써서 다음 저장이 새 키로 나갔다. 실패는 그대로 돌려주고, `Retry-After`는 다음 재전송의 대기 시각이 되고, 낙관적 층은 되돌리지 않고 불확실로 둔다. 폼은 결과 불명 화면(확인·다시 보내기)을 그대로 두고 `form.resendLater` 문구로 feedback에 포커스를 옮긴다. 같은 요청이 매번 받는 거절은 첫 요청도 거절됐다는 뜻이라 결과 불명을 풀고, 폼은 필드 오류를 보이고 저장을 다시 받는다. 짝 백엔드 표의 code만 그렇게 읽는다. 지금은 400 `VALIDATION_FAILED`(필드 목록이 있든 없든)와 400 `IDEMPOTENCY_KEY_INVALID`다(`isRefusedOnEveryAttempt`). 기능의 `mapProblem`이 정한 kind(`VALIDATION_REJECTED`)는 보지 않는다. 기능 code는 상태 규칙일 수 있다. 그래서 백엔드의 `VALIDATION_FAILED`는 요청 내용만 보는 검사여야 한다(계약 문서 6.1절). 처음 보낸 요청의 `NOT_APPLIED`와 재전송의 성공은 전처럼 정리한다. 메인 세션 결정 D10과 그 보충 둘이다. 위 "먼저 할 일" 2단계 (1106/03-01) | `src/presentation/adapters/query/application-query.ts`, `src/presentation/forms/use-app-form.ts`, `src/contracts/errors.ts`, `src/presentation/i18n/catalog.ts`, `docs/operations/api-contract-and-server-state-recovery.md`, `docs/architecture/backend-api-and-server-state-contract.md` | `2568587`, `80e7f1d`, `b41990c`, `6142cc8` | +| [계약] | `commandMutationIdentity`가 `resendSafe`(`retrySemantics`가 `KEYED`나 `IDEMPOTENT`)도 돌려주고, `BoundMutation`에 선택 칸 `resendSafe?`가 생겼다(추가만). 결과 불명 뒤 재전송 버튼과 같은 입력 재제출 거절(아래 절 0929/03-03 행)이 키 유무 대신 "키가 있거나 `resendSafe`"를 본다. 그래서 IDEMPOTENT 쓰기도 다시 보낼 수 있다. 그 재전송도 위 1106/03-01 행의 규칙을 따른다. 기능 분류기가 적용 안 됨으로 읽는 404·412 같은 code는 첫 요청이 이미 적용됐을 때 흔한 답이라 결과 불명을 남기고, 짝 백엔드 표의 두 400만 푼다. 칸이 없는 손 정책과 NEVER는 전과 같다. 위 "먼저 할 일" 4단계 (1106/03-03) | `src/contracts/server-state.ts`, `src/presentation/adapters/query/application-query.ts`, `src/application/view-models/async-state.ts`, `docs/manual/` | `815ea58`, `80e7f1d`, `b41990c` | +| [계약] **BREAKING** | `createBoundedPollCoordinator`와 `BoundedPollCoordinatorDependencies`에 타입 인자 `Operation extends BoundedPollOperation = BoundedPollOperation`이 생겼다. `operation`과 `execute`의 `input.operation`이 그 타입이라, 실행기 호출이 기능 descriptor의 입력·출력 타입으로 검사된다. 런타임 동작은 같다. realtime 설계 9.2절에 V3 실행기 결과 kind마다 poll 결과(kind, retryable, `retryAfterMs`)를 적은 표가 생겼다. 표대로 조합하면 401·403은 요청 한 번으로 lease를 끝낸다. 표는 조합 코드가 따를 규칙이고 강제하지 않는다. 위 "먼저 할 일" 6단계 (1106/04-02) | `src/adapters/realtime/polling/bounded-poll-coordinator.ts`, `src/application/policies/bounded-polling.ts`, `docs/architecture/realtime-events-web-push-and-bounded-polling.md` | `6f06e77` | +| [계약] | `PublicResponseCacheAdminPort.activateRelease`의 옵션에 `replaceUnreadablePointer?: boolean`이 생겼다(추가만). `true`면 active pointer 본문을 읽지 못한 이유와 상관없이, 손상 pointer처럼 검증된 후보로 rollback 목록 없이 덮어쓴다. 기본값은 전처럼 멈춤이다. 켜면 일시 오류에서도 rollback 목록을 잃고, 다음 cleanup이 새 활성 release 밖의 owned release cache를 모두 지운다. 언제 쓰는지는 운영 문서에 있다 (1106/02-01) | `src/application/ports/browser-file-storage/cache-storage-ports.ts`, `src/adapters/cache-storage/public-response-cache-adapter.ts`, `docs/operations/client-cache-and-storage-recovery.md`, `docs/architecture/browser-file-and-origin-storage.md` | `4cef2a2` | +| [계약] | 열린 modal의 가림막이 스크롤바 자리(`scrollbar-gutter: stable`, 1105/15-05)까지 덮는다. modal이 열린 동안 `:root:has(.ui-dialog[open])`이 root 배경을 가림막을 페이지 바탕에 겹친 불투명 색(`--dialog-backdrop-on-surface`)으로 바꾸고, `body`가 페이지 바탕(`--color-surface`)을 직접 칠한다. `component.css`에 토큰 셋(`--dialog-backdrop-weight` 55%, `--dialog-backdrop`, `--dialog-backdrop-on-surface`)이 생겼다. 새 시각 검사 `tests/visual/scrollbar-gutter.visual.spec.ts`가 스크롤바를 숨기지 않은 Chromium에서 그 자리 색을 본다. compact 골든 1장(`app-shell-compact-pseudo-drawer`)을 다시 찍었다. header 띠는 남는다(디자인 시스템 문서 8.2절). 위 "먼저 할 일" 3단계 (1106/08-03) | `src/presentation/design-system/tokens/component.css`, `src/presentation/styles/theme/base.css`, `src/presentation/styles/theme/primitives.css`, `tests/visual/` | `7625dc4` | +| [계약] | 초기 JS 기록(`initialJavascript`)을 이 범위를 합친 빌드로 다시 적었다. 204,111 → 204,193 B, 초기 파일 27개 그대로, 기능 하나 768 → 751 B, 새 context 218 → 245 B다. 예산 `initialJsGzipBytes`는 206,848 B 그대로다(결정 D9). 폭의 근거(드릴 측정값에 기능 하나의 상한 1 KiB를 더해 KiB로 올림)와 되돌림 규칙(재검토 조건마다 드릴을 다시 재고 204,800 B 이하이면 같은 규칙으로 내린다)을 운영 문서에 적었다. 사용자가 이 결정을 뒤집을 수 있다. 합친 뒤 여유는 템플릿 2,655 B, 생성 기능 둘을 더한 FE-GATE-020 드릴(205,541 B, CI env) 1,307 B다 (1106/15-01) | `config/scale/feature-shape-ceilings.json`, `docs/operations/performance-evidence.md` | `1eaa644`, `5cfc3a6` | + +### 그 밖의 수정 + +- 폼·화면: `useAppForm`의 `settleApplied`는 제출한 값이 없으면(저장 중에 떠났다 다시 마운트한 폼) 결과를 성공으로 보이고, 포커스를 잃었으면 feedback 자리로 옮긴다. 화면의 값과 기준값은 그대로 둔다. 그 값은 보낸 적이 없어서, 입력이 남아 있으면 이탈 확인도 남는다. 참조 작성 폼은 자기가 시작하지 않은 저장이 끝나면 "목록을 새로 불러와 확인" 링크를 둔다 (1106/08-01, `fbaaaee`, `145be2d`). 생성 기능 작성 페이지(`create:feature --with-create`)는 마운트된 동안만 저장 뒤 상세로, "변경됨으로 확인" 뒤 목록으로 옮긴다. 이미 생성한 기능은 바뀌지 않는다. 그 `-create-page.tsx`에는 `scripts/create-feature-write-slice.ts`의 `mounted` ref를 손으로 옮긴다 (1106/08-02, `116cbf3`) +- HTTP: Fileserver 업로드의 202 `REJECTED` 실패(`FILE_REJECTED`)가 성공 Envelope의 `meta.traceId`를 `traceId`로 싣는다. 거절 이유는 여전히 없다(알려진 제한) (1106/01-01, `7395c78`) +- realtime: reconnect coordinator는 던지는 `attempt`·`waitClosed`를 전처럼 `PROVIDER_UNAVAILABLE`(retryable)로 재시도하고, 던지는 `classifyClosed`·`confirmTransportBarrier`는 `PROTOCOL_MISMATCH`로 끝낸다. 이 규칙을 타입 주석과 realtime 설계 13.1절에 적고 테스트로 고정했다. endpoint 같은 설정 검사는 `attempt` 밖, 조합 코드가 transport를 만들 때 한다. 동작은 같다 (1106/04-01, `0438c3f`) +- 계약 문서: 6.1절의 rate-limit 503 뒤 IDEMPOTENT 쓰기는 `retryBudget` 안에서 `Retry-After`(5초 이하) 뒤 다시 보낸다고 적었다. 아래 절 1105/03-02 행과 코드는 이미 그렇다. 통합 테스트가 그 경로를 고정한다 (1106/03-02, `8156d85`). 4.1절의 bulk 엔드포인트는 `responseEnvelope: "NONE" as const`로 별도 계약 기여에 둔다. 전에는 "`responseEnvelope`를 빼고"라 적어, 따르면 `check:types`나 조립이 실패했다 (1106/07-01, 1106/16-02, `c6c86dc`) +- 문서: 저장소 설계 문서와 VD-13이 registry 키 목록 대신 `STORAGE_REGISTRY`를 가리킨다 (1106/05-01, `02a761f`). 매뉴얼 01 7단계의 descriptor 없는 쓰기와 테스트 fixture의 operation ID 길(아래 절 "먼저 할 일" 2단계도) (1106/09-01, `06357e9`). 아래 절 "먼저 할 일" 1~3단계의 대상·바뀌는 값·증상 (1106/14-01, `2f0f2bb`). 성능 문서의 초기 파일 상한 문장이 템플릿 파일 수를 기록에서 읽는다 (1103/15-02, `43ed03d`) +- CHANGELOG·리뷰 기록: 머리말에 해시를 다시 쓴 뒤의 해시 대조 단계. D7 커밋 본문의 다시 짓기 전 해시 둘은 2026-11-05 리뷰 README의 D7 행에 맞는 해시로 적었다 (1106/14-02, 1105 README 16.2, `ddc6353`) +- 테스트: Service Worker marker 읽기 상한 test가 상한 5초를 1 ms라도 넘기면 실패한다. 전에는 20초까지 통과했다 (1106/06-02, `1f4b929`). run 격리의 capabilities 설정 검사 8개를 `tests/unit/playwright-capabilities-run-isolation.test.ts`로 옮겼고, browser-file-storage 제거 드릴이 그 설정과 이 파일을 이름으로 함께 지운다. 그 런타임을 손으로 지운 제품은 이 파일도 지운다. 빌드 입력 목록 검사는 측정 스크립트를 그 소유 기능이 설치돼 있을 때 읽는다 (1106/10-01, `a135fa8`). 제거 드릴의 문서 테스트 목록에는 문서를 읽는 테스트만 둔다. 아래 절 1105/03-01 행이 적은 `tests/unit/backend-contract-pin.test.ts`의 6.1절 대조는 `tests/unit/backend-contract-pin-document.test.ts`로 옮겼고, pin 테스트의 나머지 14건은 모든 드릴에서 돈다. `feature-tracked-files.test.ts`의 문서 무관 1건은 `feature-tracked-file-rewrites.test.ts`로 옮겼다. 목록 검사는 주석이 아닌 코드의 문자열을 본다 (1106/12-01, 1106/10-02, `b8535f8`) + +### 알려진 제한 + +이 절의 범위 끝에서 사실인 것만 적었다. 아래 절의 알려진 제한 중 이 범위가 바꾼 것과 새로 생긴 것만 적고, 나머지는 아래 절 그대로다. + +- 다운스트림 이행: 위 안내를 두 제품 코드에 적용해 게이트를 돌려 보지 않았다. +- 백엔드로 넘김: Fileserver는 검증기가 거절한 업로드(REJECT)를 202 `REJECTED` 성공 답으로 주고, 판정 code(`FILE_TOO_LARGE`, 제품 검증기 code 등)는 파일 레코드의 `lastErrorCode`에만 적는다. 그래서 화면은 이유별 문구를 고를 수 없다. 요청은 둘 중 하나다. REJECT를 422 실패 Envelope(`error.code` = 판정 code, `retryable: false`)로 답하거나, 202 답에 판정 code 칸을 더한다. 앞의 것이면 프론트의 기존 422 경로가 code와 `traceId`를 싣고 `NOT_APPLIED`로 읽으며, 그때 `FILE_REJECTED` 분기를 지운다 (1106/01-01). +- 일부: 실행 격리. `check:bundle`은 이제 `RUN_OUTPUT_ROOT`가 있으면 멈춘다. 같은 모양일 수 있는 `check:app-build-input:bundle`, `check:optional-recipes --require-dist`, release candidate 조립은 보지 않았다 (1105/12-04, 1106/12-02). +- 일부: poll 조합 코드가 `input.operation`을 무시하고 다른 descriptor를 넘기는 것은 여전히 막지 않는다. 이제 `input.operation`이 descriptor 타입을 가져 그 길을 쓰기가 더 쉽다. 9.2절 표는 규칙이고, 템플릿은 poll `execute` 기본 구현을 주지 않는다 (1103/04-01, 1106/04-02). +- 일부: reconnect `attempt` 안에서 연결을 만드는 조합 코드는 설정 오류가 여전히 서버 장애로 보인다. 규칙만 적었다 (1106/04-01). +- 일부: 결과 불명 재전송이 rate limit에 막힌 동안 결과 불명 화면이 남고, 다시 보내기는 `Retry-After`(상한 5초)를 기다린다. 폼 밖에서 부른 같은 입력 재저장이 `NOT_APPLIED`로 끝나면 훅은 키를 지키지만 폼은 retry-later를 보인다. 기능이 선언한 결정적 거절(생성 기능의 400 `_INVALID`)과 problem details를 읽는 기능의 422 입력 검증(참조 기능은 모든 422를 필드 오류로 읽는다)은 어느 쪽인지 알 수 없어 재전송 뒤에도 결과 불명으로 남는다. 출구는 결과 불명 화면의 확인이다 (1106/03-01). +- 일부: 기능 제거 드릴은 route ID나 URL만 적은 spec과 한 단어 기능 ID만 적은 spec을 잡지 못하고, 다운스트림 spec이 다른 이유로 `-`가 든 기능 ID를 한 이름으로 적으면 거짓 양성이 난다. 부분 문자열 검색의 거짓 양성과 dist 빌드 잔여 검사는 그대로다 (1106/16-01, 1105/16-04). +- 일부: `:has()`를 모르는 브라우저(Firefox 121 미만 등)는 전처럼 가림막 옆에 띠가 남는다. 오른쪽 drawer, RTL, Firefox, WebKit은 보지 않았다 (1106/08-03). +- 일부: Cache Storage release marker 본문이 계속 읽히지 않으면 stage가 marker를 다시 쓰지 않는다. `replaceUnreadablePointer`는 active pointer만 푼다 (1105/02-02, 1106/02-01). +- 일부: 초기 JS 예산의 폭과 되돌림 규칙은 문서에만 있다. 예산 값을 규칙 밖으로 바꿔도 실패하는 테스트는 없다 (1106/15-01). +- 일부: CHANGELOG·커밋 본문의 해시 대조는 사람이 하는 단계다(머리말) (1106/14-02). ## 미출시 — `409d72e` → 브랜치 `fix/maturity-review-2026-11-05-b` @@ -21,9 +91,9 @@ #### 옮기는 법 -1. **HTTP descriptor마다 `responseEnvelope`를 적는다.** `InstalledHttpContract`의 필수 칸이 됐다. 감싸지 않는 백엔드(memento-web, TechLog)는 `"NONE" as const`, 짝 백엔드 Envelope는 `"ENVELOPE_V1" as const`다. 빠뜨리면 그 descriptor의 `satisfies InstalledHttpContract<...>`에서 `check:types`가 실패한다. 런타임 동작은 같다 (1103/16-01) -2. **뮤테이션 정책의 operation ID를 손으로 적지 않는다.** `BoundMutation.operationId`는 brand 타입 `MutationOperationId`다. `operationId: ""`와 `requiresIdempotencyKey`를 `...commandMutationIdentity()`로 바꾼다. 문자열로 적으면 `check:types`가 실패한다 (1103/16-05) -3. **`refusedBeforeWrite`에서 플랫폼 code를 뺀다.** 계약 문서 6.1절이 "쓰기 뒤 가능"으로 둔 code(`PLATFORM_CODES_POSSIBLY_AFTER_WRITE`: `BAD_PARAMETER`, `MAPPING_FAILED`, `DB_*` 8개, `LOCK_ACQUISITION_TIMEOUT`, Fileserver code)를 적으면 계약 조립이 거절해 부팅이 멈춘다. 그 code의 실패는 결과 불명으로 남는다 (1105/03-01) +1. **HTTP descriptor마다 `responseEnvelope`를 적는다.** `InstalledHttpContract`의 필수 칸이 됐다. 감싸지 않는 백엔드(memento-web)는 `"NONE" as const`, 짝 백엔드 Envelope는 `"ENVELOPE_V1" as const`다. TechLog 백엔드는 Envelope로 감싸지만 출력 검증기(`envelopeData`)가 Envelope를 직접 벗기므로 `"NONE"`이다. `"ENVELOPE_V1"`로 바꾸면 실행기가 한 번 벗긴 `data`를 검증기가 다시 벗기려다 모든 응답이 실패한다. 빠뜨리면 그 descriptor의 `satisfies InstalledHttpContract<...>`에서 `check:types`가 실패한다. 두 제품의 descriptor helper처럼 `as`로 단언한 descriptor는 빠뜨려도 `check:types`가 잡지 않는다(타입 규칙으로 읽은 추론, 돌려 보지 않았다). 그런 descriptor는 직접 찾아 적는다. 빠진 값은 조립이 `NONE`으로 읽어 런타임 동작은 같다 (1103/16-01) +2. **뮤테이션 정책의 operation ID를 손으로 적지 않는다.** `BoundMutation.operationId`는 brand 타입 `MutationOperationId`다. `operationId: ""`와 `requiresIdempotencyKey`를 `...commandMutationIdentity()`로 바꾼다. 문자열로 적으면 `check:types`가 실패한다. 이 함수는 `requiresIdempotencyKey`를 descriptor의 `retrySemantics`가 `KEYED`일 때만 `true`로 다시 계산한다. 손으로 적은 값이 descriptor와 다른 정책은 동작이 바뀌고, `check:types`는 이것을 잡지 않는다. 예: tech-log 관리 쓰기는 정책이 `true`, descriptor가 `NEVER`라 `false`가 되고, 키가 없으면 던지는 자기 가드 때문에 저장마다 `TypeError`다(지금도 실행기가 키를 실은 `NEVER` 요청을 `UNEXPECTED_IDEMPOTENCY_KEY`로 거절하는 모양이다. 코드로 읽은 추론이다). 바꾸기 전에 정책마다 손으로 적은 값과 descriptor의 `retrySemantics`를 맞춰 본다. V3 descriptor가 없는 쓰기(Fileserver 업로드처럼 `execute`가 HTTP 실행기를 거치지 않는 것)는 descriptor 모양 객체를 넘긴다: `...commandMutationIdentity({ contract: { operationId: "", method: "POST", retrySemantics: "KEYED" } })`. 멱등 키가 필요 없으면 `"NEVER"`다. 대조할 descriptor가 없으니 이 ID의 오타는 어느 검사도 잡지 않는다. 테스트 fixture는 `tests/helpers/mutation-operation-id.ts`의 `testMutationOperationId("")`를 쓴다. 문자열 ID는 `check:types:test`에서 실패한다. 매뉴얼 01 7단계 (1103/16-05) +3. **`refusedBeforeWrite`에서 플랫폼 code를 뺀다.** 계약 문서 6.1절이 "쓰기 뒤 가능"으로 둔 code(`PLATFORM_CODES_POSSIBLY_AFTER_WRITE`: `BAD_PARAMETER`, `MAPPING_FAILED`, `DB_*` 8개, `LOCK_ACQUISITION_TIMEOUT`, Fileserver code)를 적으면 그 기능 실행부를 적재할 때 계약 조립이 거절한다. 부팅은 기능의 계약 기여를 조립하지 않으므로 앱은 뜨고, 그 기능 라우트에 처음 들어갈 때와 플랫폼 구성 화면에서 실패한다. CI에서는 모든 기능 실행부를 조립하는 `test:unit`과 `check:registries`가 먼저 잡는다. 그 code의 실패는 결과 불명으로 남는다 (1105/03-01) 4. **bounded poll의 `execute`는 실패를 던지지 않고 결과로 돌려준다.** 던지면(lease 자신의 abort 제외) 재시도 없이 `PROTOCOL_MISMATCH`(retryable 아님)로 lease가 끝난다. 네트워크 실패를 throw로 내던 `execute`는 retryable `PROVIDER_UNAVAILABLE` 결과로 바꾼다. 실행기에는 클로저의 descriptor 대신 `input.operation`(생성 때 검사한 descriptor)을 넘긴다 (1105/04-02, 1103/04-01) 5. **`artifacts/tests/a11y.json`을 읽는 도구는 schemaVersion 2를 읽는다.** `scope`는 실패 화면으로만 본 라우트를 빼고, 그 라우트는 새 `notChecked` 배열에 `{ routeId, reason }`으로 들어간다. 설치된 라우트 전체는 둘을 합친 것이다 (1103/11-01) 6. **제품 scope participant의 `label`은 소문자 kebab-case 48자 이하로 쓴다.** 아니면 조립이 `TypeError`로 멈춘다 (1105/02-01) @@ -34,7 +104,7 @@ #### 옮긴 뒤 확인 -1. 로컬 merge 게이트 14개를 돈다. 이 절 때문에 먼저 볼 것: `check:types`(1·2단계), 앱을 조립하는 `test:unit`·`test:component`(3·6단계), `check:ci`(9단계), `check:architecture`(10단계), `check:registries`(응답 스키마 행을 `REJECT_UNKNOWN`으로 좁힌 변경은 이제 breaking). +1. 로컬 merge 게이트 14개를 돈다. 이 절 때문에 먼저 볼 것: `check:types`(1·2단계), 모든 기능 실행부를 조립하는 `test:unit`·`check:registries`(3단계), 앱을 조립하는 `test:unit`·`test:component`(6단계), `check:ci`(9단계), `check:architecture`(10단계), `check:registries`(응답 스키마 행을 `REJECT_UNKNOWN`으로 좁힌 변경은 이제 breaking). 2. 한 checkout에서 브라우저 테스트 실행 두 개를 함께 돌리려면 실행마다 `TEST_RUN_ID`를 다르게 준다. 게이트(`ci:gate`)와 증거 검사는 기본 경로만 읽으므로 한 checkout에서 하나씩 돈다. 3. 배포가 있는 제품: 자산을 redirect로 주는 호스트는 FE-GATE-019가 FAIL이다. diff --git a/config/ci/contract-baseline.json b/config/ci/contract-baseline.json index b05954bf..7e1243d0 100644 --- a/config/ci/contract-baseline.json +++ b/config/ci/contract-baseline.json @@ -1,11 +1,11 @@ { "schemaVersion": 1, "owner": "DongHyeonka", - "reason": "1105/12-01: FE-GATE-013 hostRequirements are part of the reviewed gate shape", + "reason": "1106/13-01: FE-GATE-027 runs the advisory scan before the release admission", "gates": 27, "commands": 100, "commandReferences": 104, "artifacts": 110, "stages": 5, - "gateShapeSha256": "7bebafe65d528be6a59d4bb70edd2cad99455b2b49087e4a46b83d77bfd163de" + "gateShapeSha256": "7f6f3d975c62c022d6a6f8b5f39562f73de9ca0f22aa3d086ac28959e50fa93e" } diff --git a/config/ci/gates.json b/config/ci/gates.json index 31175c46..500fca74 100644 --- a/config/ci/gates.json +++ b/config/ci/gates.json @@ -2209,8 +2209,8 @@ "id": "FE-GATE-027", "name": "release-admission", "commandIds": [ - "check-release-admission", - "scan-dependency-advisories" + "scan-dependency-advisories", + "check-release-admission" ], "logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-027-txt", "evidenceArtifactIds": [ diff --git a/config/scale/feature-shape-ceilings.json b/config/scale/feature-shape-ceilings.json index dd92556a..853db542 100644 --- a/config/scale/feature-shape-ceilings.json +++ b/config/scale/feature-shape-ceilings.json @@ -39,9 +39,9 @@ } ], "initialJavascript": { - "gzipBytes": 204111, + "gzipBytes": 204193, "files": 27, - "perFeatureGzipBytes": 768, - "perContextGzipBytes": 218 + "perFeatureGzipBytes": 751, + "perContextGzipBytes": 245 } } diff --git a/docs/accessibility/manual-checklist.md b/docs/accessibility/manual-checklist.md index 2e4158db..61425334 100644 --- a/docs/accessibility/manual-checklist.md +++ b/docs/accessibility/manual-checklist.md @@ -74,7 +74,10 @@ What the automated run scans: no alert box is on screen, so a list page is scanned in its empty state. A read of one resource (a detail page) has no generic answer: that route is scanned in its failure state and the run records an `a11y-data-state` - annotation. + annotation. `a11y.json` lists it under `notChecked`. When a protected + route's `paramsSchema` is the input of such a read, the report expects that + record from the descriptors alone and fails without it + (`scripts/write-a11y-report.ts`). - The reference sample's list in its success, empty and error states, its detail, its form with submit errors and its status page, each after that state is on screen (`tests/e2e/reference-form.spec.ts`, removed with the diff --git a/docs/architecture/backend-api-and-server-state-contract.md b/docs/architecture/backend-api-and-server-state-contract.md index 200015ea..f6131c85 100644 --- a/docs/architecture/backend-api-and-server-state-contract.md +++ b/docs/architecture/backend-api-and-server-state-contract.md @@ -203,8 +203,12 @@ Envelope의 모양과 키 존재 규칙은 짝 백엔드 템플릿 문서가 정 `page`는 버리고 응답은 그대로 읽는다. 목록 화면의 전체 수는 `page.total`이다. 배열 길이는 첫 페이지 크기(기본 20)일 뿐이다. - bulk 응답(`results`, `BATCH_PARTIAL_FAILURE`)은 지원하지 않는다. 성공 status의 - `results` Envelope는 `ENVELOPE_MISMATCH`다. bulk 엔드포인트를 붙이려면 - `responseEnvelope`를 빼고 기능 스키마가 본문 전체를 읽는다. + `results` Envelope는 `ENVELOPE_MISMATCH`다. bulk 엔드포인트를 붙이려면 그 + operation을 `responseEnvelope: "NONE" as const`로 적고 별도 계약 기여에 둔다(한 + 기여의 operation은 같은 값을 적는다. 기능 하나가 기여 둘을 낼 수 있다, + `tests/unit/external-contract-runtime.test.ts` "lets one feature read two backends + through two contributions"). 기능 스키마가 본문 전체를 읽고 `classifyProblem`이 + 적용 여부를 정한다. ### 4.2 Status와 error @@ -334,13 +338,20 @@ mutation이 400·409·422로 실패하면 프론트는 그 요청이 적용됐 `IDEMPOTENCY_RECOVERY_REQUIRED`, §4의 503 `REQUEST_TIMEOUT`이다. 실행기가 자동으로 다시 보내는 것은 KEYED 명령의 503 `IDEMPOTENCY_UNAVAILABLE`뿐이다. 나머지는 결과 불명 화면에서 사용자가 같은 키로 다시 보낸다. +- 같은 키 재전송이 400 `VALIDATION_FAILED`로 거절되면 첫 요청도 거절된 것으로 보고 결과 + 불명을 풀므로(1106/03-01, `src/contracts/errors.ts` `isRefusedOnEveryAttempt`), + `VALIDATION_FAILED`는 요청 내용만 보는 검사여야 하고, 시각이나 데이터베이스를 읽는 + 규칙은 기능이 선언한 code로 내며 그 code는 결과 불명을 풀지 않는다. - §4의 503 `RATE_LIMIT_UNAVAILABLE`(rate-limit 저장소 응답 없음, `Retry-After` 있음)과 503 `RATE_LIMIT_INCOMPATIBLE`(rate-limit 제공자가 계약과 맞지 않음)은 status와 code가 함께 맞으면 기능 분류기와 상관없이 `NOT_APPLIED`다(1105/03-02, `backend-envelope.ts` `REFUSED_BEFORE_WRITE`). 백엔드 `RateLimitInterceptor.java`의 `preHandle`이 컨트롤러 전에 `false`를 돌려주며 낸다. `45d2a478`의 main 소스에서 이 두 code를 내는 곳은 그 두 - 줄뿐이다. 자동 재전송은 없다(KEYED도 같다). 남은 위험(추론, 실행 확인 안 함): Spring MVC는 - 비동기 처리(`Callable`·`DeferredResult`)가 끝난 뒤의 ASYNC 재디스패치에서도 interceptor의 + 줄뿐이다. KEYED·NEVER는 자동 재전송이 없다. IDEMPOTENT 쓰기는 `retryBudget` 안에서 + `Retry-After`(5초 이하) 뒤 다시 보낸다. 실행기는 status로 판단하므로 백엔드가 + `retryable: false`로 보내는 `RATE_LIMIT_INCOMPATIBLE`도 다시 보낸다 + (`tests/integration/http-execution-v3-envelope.test.ts`, 1106/03-02). + 남은 위험(추론, 실행 확인 안 함): Spring MVC는 비동기 처리(`Callable`·`DeferredResult`)가 끝난 뒤의 ASYNC 재디스패치에서도 interceptor의 `preHandle`을 다시 부른다. 그 interceptor는 dispatcher 종류를 보지 않으므로 비동기 쓰기 컨트롤러라면 이 503(그리고 429)이 쓰기 뒤에도 나올 수 있다. `45d2a478`에는 Envelope을 돌려주는 비동기 쓰기 컨트롤러가 없다(web-advanced 스트리밍과 fileserver 전송뿐). @@ -389,7 +400,7 @@ mutation이 400·409·422로 실패하면 프론트는 그 요청이 적용됐 - 위 표에서 "쓰기 뒤 가능"인 플랫폼 code(`BAD_PARAMETER`, `MAPPING_FAILED`, `DB_*` 8개, `LOCK_ACQUISITION_TIMEOUT`, fileserver code)도 적을 수 없다(1105/03-01). 계약 조립이 거절하고 실행기도 무시한다. 목록은 `src/contracts/external-contract-runtime.ts`의 - `PLATFORM_CODES_POSSIBLY_AFTER_WRITE`이고, `tests/unit/backend-contract-pin.test.ts`가 + `PLATFORM_CODES_POSSIBLY_AFTER_WRITE`이고, `tests/unit/backend-contract-pin-document.test.ts`가 이 표의 "쓰기 뒤 가능" 행과 대조한다. 참조 도메인 code와 web-advanced patch code는 엔드포인트가 단계를 정하므로 그 엔드포인트를 확인한 기능 작성자가 적을 수 있다. 이 표에 "쓰기 뒤 가능" 플랫폼 code를 더하면 그 목록도 같은 변경에서 고친다. diff --git a/docs/architecture/browser-file-and-origin-storage.md b/docs/architecture/browser-file-and-origin-storage.md index 3ff7c1f3..8a8e7846 100644 --- a/docs/architecture/browser-file-and-origin-storage.md +++ b/docs/architecture/browser-file-and-origin-storage.md @@ -1016,6 +1016,16 @@ rollback 목록 없이 덮어쓴다. pointer 읽기의 일시 오류는 activati cleanup이 무엇을 지울지 볼 수 있다. 일시 오류에서는 inspect도 실패한다 (2026-11-03 02-05). +pointer entry는 있는데 저장된 본문이 다시 쓰기 전까지 계속 읽히지 않으면(blob +손실 등) 일시 오류와 구별되지 않는다. 조회, activation, cleanup, inspect가 모두 +같은 실패(`UNAVAILABLE`/`RETRY` 등)를 계속 돌려준다. pointer를 쓰는 곳은 +activation 하나라서 기다려도 돌아오지 않는다. 이때 운영자는 +`activateRelease(releaseRegistryId, manifestDigestHex, { replaceUnreadablePointer: true })`로 +검증된 후보를 활성화한다. 손상 pointer와 같이 rollback 목록 없이 덮어쓴다. 그 뒤 +cleanup은 새 활성 release 밖의 owned release cache를 모두 지운다. 옵션이 없으면 +지금처럼 멈춘다. 일시 오류 한 번으로 rollback 목록을 잃지 않기 위해서다 +(1106/02-01). + 현재 `cleanupOwned()`와 `inspect()`는 위 ownership/integrity 경계를 지키지만 cache count에 대한 cursor, per-invocation max count와 deadline은 제공하지 않는다. 따라서 cache 수에 비례한 unbounded maintenance를 production boot path에 diff --git a/docs/architecture/client-cache-and-storage.md b/docs/architecture/client-cache-and-storage.md index 8e7143d6..95922e0e 100644 --- a/docs/architecture/client-cache-and-storage.md +++ b/docs/architecture/client-cache-and-storage.md @@ -47,9 +47,11 @@ generation마다 `QueryClient`를 만들고, query retry를 끄며, 30초 `stale `src/bootstrap/runtime-application.tsx`가 이 client를 실제 provider tree에 조립한다. -현재 `src/contracts/storage-keys.ts`에는 `COLOR_SCHEME`, -`CHUNK_RELOAD_GUARD`, 금지된 `AUTH_TOKEN`과 비활성 -`QUERY_PERSISTENCE`가 등록되어 있다. +등록된 Web Storage 키의 정본은 `src/contracts/storage-keys.ts`의 +`STORAGE_REGISTRY`다. 이 문서는 행 목록을 옮겨 적지 않는다. 옮겨 적은 목록은 +행이 늘 때 따라오지 않았다(1106/05-01). StoragePort(`getStorageDefinition`)는 +`classification: "sensitive-forbidden"` 행과 `backend: "external"` 행을 거절하고 +나머지 행만 읽고 쓴다. `src/adapters/storage/browser-storage-codec.ts`와 `browser-storage-adapter.ts`는 closed JSON codec, 기본 16,384-byte 상한, schema envelope, TTL과 동일 envelope를 쓰는 memory fallback을 제공한다. @@ -132,7 +134,7 @@ blocked/versionchange를 다루는 reference runtime이 있다. 이 설계는 | --- | --- | --- | --- | --- | | memory QueryClient | `COMPOSED` | server-state generation별 생성(session identity 변경 시 FENCED 뒤 새 client), global stale/gc/retry default | per-query policy | `DESIGNED_NOT_IMPLEMENTED` | | application query bridge | `COMPOSED` | AbortSignal, stale error, optimistic rollback/conflict surface | old-generation query/mutation callback 폐기 | `DESIGNED_NOT_IMPLEMENTED` | -| Web Storage | `COMPOSED` | 두 key, strict v1 envelope/codec, lazy TTL, global 16 KiB cap | per-key cap, HIT/MISS, durability, v2 scope, migration, sweep/logout | `DESIGNED_NOT_IMPLEMENTED` | +| Web Storage | `COMPOSED` | `STORAGE_REGISTRY`의 StoragePort 행, strict v1 envelope/codec, lazy TTL, global 16 KiB cap | per-key cap, HIT/MISS, durability, v2 scope, migration, sweep/logout | `DESIGNED_NOT_IMPLEMENTED` | | cross-tab invalidation | `COMPOSED` | release epoch(FNV-1a digest), versioned hint, duplicate/gap, BC→localStorage, registry pulse key, storageArea 동일성 검사, generation별 transport | composite scope epoch, durable ledger hook | `DESIGNED_NOT_IMPLEMENTED` | | generic IndexedDB | `AVAILABLE_NOT_COMPOSED` | reusable repository/maintenance runtime | product dataset schema/codec/query/policy composition | product selection `NOT_SELECTED` | | query persistence facade | `DESIGNED_NOT_IMPLEMENTED` | 없음, registry가 disabled 강제 | stable per-query record, bounded restore, namespace epoch/CAS | `DESIGNED_NOT_IMPLEMENTED` | @@ -1403,8 +1405,7 @@ invalidate-only runtime은 installed query contract가 실제로 소비하므로 | capability | 기본 | | --- | --- | | TanStack memory QueryClient | `COMPOSED` | -| 등록된 COLOR_SCHEME localStorage | `COMPOSED` | -| 등록된 CHUNK_RELOAD_GUARD sessionStorage | `COMPOSED` | +| `STORAGE_REGISTRY`의 StoragePort 행(`localStorage`·`sessionStorage`) | `COMPOSED` | | generic IndexedDB repository/maintenance reference | `AVAILABLE_NOT_COMPOSED` | | IndexedDB query persistence facade | `DESIGNED_NOT_IMPLEMENTED` | | product query persistence | `NOT_SELECTED` | diff --git a/docs/architecture/decisions/VD-13-client-cache-scope-and-persistence.md b/docs/architecture/decisions/VD-13-client-cache-scope-and-persistence.md index 571fbd94..b7c79db4 100644 --- a/docs/architecture/decisions/VD-13-client-cache-scope-and-persistence.md +++ b/docs/architecture/decisions/VD-13-client-cache-scope-and-persistence.md @@ -63,7 +63,7 @@ runtime의 구현 상태고, 후자는 제품 capability 선택 상태다. 하 | capability | 현재 상태 | 현재 보장 | | --- | --- | --- | | TanStack Query memory runtime | `COMPOSED` | runtime별 QueryClient, finite inactive GC, retry owner, query AbortSignal | -| registered Web Storage | `COMPOSED` | `COLOR_SCHEME`, `CHUNK_RELOAD_GUARD`만 strict codec/envelope로 사용 | +| registered Web Storage | `COMPOSED` | `STORAGE_REGISTRY`의 StoragePort 행만 strict codec/envelope로 사용. 행 목록은 `src/contracts/storage-keys.ts`가 정본이다 | | invalidate-only cross-tab runtime | `COMPOSED` | versioned topic, BroadcastChannel 우선, localStorage pulse fallback | | generic IndexedDB repository/maintenance runtime | `AVAILABLE_NOT_COMPOSED` | CAS, idempotency, transaction complete, policy binding, bounded lifecycle/migration | | session/account-scoped QueryClient lifecycle | `DESIGNED_NOT_IMPLEMENTED` | 없음; 현재 cache epoch는 release ID만 포함 | @@ -392,8 +392,10 @@ type WebStorageDefinition = Readonly<{ | 한 sweep에서 검사할 key | 16 | | 한 read에서 migration step | 2 | -현재 두 key는 각각 더 좁은 codec을 유지한다. `COLOR_SCHEME`은 public -origin-shared preference이고 `CHUNK_RELOAD_GUARD`는 tab session control이다. +현재 StoragePort 행은 행마다 더 좁은 `valueCodec`(`color-scheme-v1`, +`opaque-string-v1`)을 유지한다. `localStorage` 행은 public origin-shared +preference이고 `sessionStorage` 행은 tab session control이다. 행 목록은 +`src/contracts/storage-keys.ts`의 `STORAGE_REGISTRY`가 정본이다. server response, credential, signed URL, File/Blob, large draft와 queue를 Web Storage에 넣지 않는다. 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 dd8d6398..a546b31c 100644 --- a/docs/architecture/realtime-events-web-push-and-bounded-polling.md +++ b/docs/architecture/realtime-events-web-push-and-bounded-polling.md @@ -1677,6 +1677,35 @@ attempt마다 요청이 최대 3번이다. `execute`는 서버·네트워크 실 command/mutation, GraphQL subscription, Connect/gRPC-Web server stream과 arbitrary status URL은 poll하지 않는다. TanStack Query retry도 `false`여야 한다. +coordinator는 받은 descriptor의 타입도 `input.operation`에 그대로 싣는다 +(`createBoundedPollCoordinator`, `Operation`은 `operation`에서 +추론, 1106/04-02). 그래서 `execute` 안의 `executor.execute(input.operation, …)`는 +기능 descriptor의 입력·출력 타입으로 검사된다. `Value`만 직접 적으면 `Operation`이 +`BoundedPollOperation`으로 돌아가 입력과 출력이 `unknown`이 된다. 둘 다 적거나 +추론에 맡긴다. + +`execute`는 실행기 결과를 아래 표대로 poll attempt 결과로 바꾼다(1106/04-02). +poll이 재시도하는 kind는 `retryable: true`인 `CONNECT_TIMEOUT`·`RATE_LIMITED`· +`PROVIDER_UNAVAILABLE`뿐이고, `retryAfterMs`는 뒤 둘만 읽는다. + +| V3 결과 `kind` | poll attempt 결과 | +| --- | --- | +| `SUCCESS` | `ok: true`, `kind: "VALUE"`, `value`, terminal 판정에 쓸 `state`. 결과에 본문 크기가 없으므로 `responseBytes`는 `0`을 둔다. 본문 상한은 실행기가 `frontend.responseByteLimit`으로 지킨다(넘으면 `CONTRACT_VIOLATION`). 그래서 poll descriptor의 `responseByteLimit`을 lease `maxResponseBytes` 이하로 둔다 | +| `PROBLEM` | `metadata.status`가 5xx·`408`·`425`이면 `PROVIDER_UNAVAILABLE`, `retryable: true`, `retryAfterMs`는 `metadata.retryAfterMs`. 그 밖의 status는 다시 보내도 같은 답이라 `PROTOCOL_MISMATCH`, `retryable: false`. 9.4의 reset 계약이 있는 `409`·`410`만 `CURSOR_EXPIRED`, `retryable: false` | +| `UNAUTHENTICATED` | `AUTH_REQUIRED`, `retryable: false`. lease가 끝나고, session owner가 회복한 뒤 새 lease를 연다(9.3) | +| `FORBIDDEN` | `FORBIDDEN`, `retryable: false` | +| `RATE_LIMITED` | `RATE_LIMITED`, `retryable: true`, `retryAfterMs`는 결과의 `retryAfterMs` | +| `CONTRACT_VIOLATION` | `metadata.status`가 5xx·`408`·`425`이면 쓸 수 있는 problem 본문 없이 온 서버 장애라 `PROBLEM`의 장애 행과 같다. 그 밖(입력 거절 `INPUT_INVALID`, 응답 schema·크기 위반)은 `PROTOCOL_MISMATCH`, `retryable: false` | +| `TRANSPORT_FAILURE` | `failure.kind`가 `TIMEOUT`이면 `CONNECT_TIMEOUT`, `retryable: true`. `ABORTED_BY_CALLER`면 `ABORTED`, `ABORTED_BY_SCOPE`면 `SCOPE_FENCED`, 둘 다 `retryable: false`. 나머지(`NETWORK_FAILURE` 등)는 `PROVIDER_UNAVAILABLE`, `retryable: true`. 실행기가 끝낸 transport 실패의 `failure.retryable`은 모두 `false`라 옮기지 않는다 | +| `CANCELLED` | `ABORTED`, `retryable: false` | +| `AUTH_INTEGRATION_FAILURE` | `reason`이 `CREDENTIAL_OWNER_UNAVAILABLE`이면 `PROVIDER_UNAVAILABLE`, `retryable: true`. 그 밖은 구성 결함이라 `PROTOCOL_MISMATCH`, `retryable: false`. 어느 쪽도 로그아웃 경로로 보내지 않는다 | + +실패 결과의 `operation`은 모두 `"POLL"`이다. `retryAfterMs`는 값이 있을 때만 +칸을 둔다. 값이 `undefined`인 칸은 모양이 틀린 결과라 lease가 `PROTOCOL_MISMATCH`로 +끝난다. lease 상태 검사가 결과 해석보다 먼저라, 그사이 hidden·offline·scope +변경·close가 있었으면 표와 상관없이 그 kind로 끝난다. 이 표를 따르는 조합 예는 +`tests/unit/realtime/bounded-poll-coordinator.test.ts`의 `pollAttemptResult`다. + 한 lease는 다음 조건 중 먼저 발생하는 시점에 종료한다. - terminal state @@ -1963,8 +1992,8 @@ credential을 보호할 수 있다고 주장하지 않는다. | `AUTH_REQUIRED` | session expired/recovery 실패 | sign-in UX | | `FORBIDDEN` | stream/resource 거절 | retry 없음 | | `RATE_LIMITED` | connection/request/provider limit | bounded server hint | -| `PROVIDER_UNAVAILABLE` | backend/push/hosting unavailable. 환경은 online인데 서버·프록시에 닿지 않은 것(SSE fetch·reader 거절, WebSocket `error`)도 이 kind다(1103/04-04, `retryable: true`). poll은 `execute`가 돌려준 결과의 kind를 쓴다. V3 실행기는 fetch 거절을 던지지 않고 `NETWORK_FAILURE` 결과로 돌려주므로, `execute`가 그 결과를 이 kind로 바꾼다. stream coordinator의 recovery deadline 초과(operation `RECOVER`)와 close drain deadline 초과(operation `CLOSE`)도 이 kind다(`retryable: false`). live↔Poll handoff coordinator의 checkpoint deadline 초과(operation `RECOVER`)와 close drain deadline 초과(operation `CLOSE`)도 이 kind다(`retryable: true`) | bounded retry 또는 degraded. stream coordinator 마감은 재연결로 풀리지 않는다: task가 settle할 때까지 `DRAINING`을 유지한다. settle 뒤 recovery 마감은 다음 event가 recovery부터 하고, close 마감은 `CLOSED`가 된다. handoff checkpoint 마감은 그 전환을 fail-close하므로 새 handoff만 돌 수 있다. handoff close 마감 뒤에는 writer·checkpoint task가 settle하면 다시 부른 `close()`가 성공한다 | -| `PROTOCOL_MISMATCH` | version/subprotocol/content type. poll `execute`가 던지거나 모양이 틀린 결과를 돌려준 것도 이 kind다. 조합 코드 결함이라 서버 장애로 재시도하지 않는다(1105/04-02, `retryable: false`) | terminal/rollout rollback | +| `PROVIDER_UNAVAILABLE` | backend/push/hosting unavailable. 환경은 online인데 서버·프록시에 닿지 않은 것(SSE fetch·reader 거절, WebSocket `error`)도 이 kind다(1103/04-04, `retryable: true`). poll은 `execute`가 돌려준 결과의 kind를 쓴다. V3 실행기는 fetch 거절을 던지지 않고 `NETWORK_FAILURE` 결과로 돌려주므로, `execute`가 그 결과를 이 kind로 바꾼다(V3 결과별 대응은 9.2 표). reconnect coordinator는 조합 코드의 `attempt`·`waitClosed`가 던지거나 거절해도 이 kind로 보고 backoff로 재시도한다(operation `CONNECT`·`RECEIVE`, `retryable: true`, 1106/04-01). 연결 실패를 던지는 라이브러리를 감싼 transport도 회복하게 하려는 규칙이다. 그래서 endpoint 같은 설정 검사는 `attempt` 밖, 조합 코드가 bridge를 만들 때 한다. SSE·WebSocket 연결 생성은 틀린 endpoint에 `TypeError`를 던지고, `attempt` 안이면 그 오류가 서버 장애처럼 예산 끝까지 재시도된다. stream coordinator의 recovery deadline 초과(operation `RECOVER`)와 close drain deadline 초과(operation `CLOSE`)도 이 kind다(`retryable: false`). live↔Poll handoff coordinator의 checkpoint deadline 초과(operation `RECOVER`)와 close drain deadline 초과(operation `CLOSE`)도 이 kind다(`retryable: true`) | bounded retry 또는 degraded. stream coordinator 마감은 재연결로 풀리지 않는다: task가 settle할 때까지 `DRAINING`을 유지한다. settle 뒤 recovery 마감은 다음 event가 recovery부터 하고, close 마감은 `CLOSED`가 된다. handoff checkpoint 마감은 그 전환을 fail-close하므로 새 handoff만 돌 수 있다. handoff close 마감 뒤에는 writer·checkpoint task가 settle하면 다시 부른 `close()`가 성공한다 | +| `PROTOCOL_MISMATCH` | version/subprotocol/content type. poll `execute`가 던지거나 모양이 틀린 결과를 돌려준 것도 이 kind다. 조합 코드 결함이라 서버 장애로 재시도하지 않는다(1105/04-02, `retryable: false`). reconnect coordinator에서는 `classifyClosed`(operation `CONNECT`)나 `confirmTransportBarrier`(operation `RECOVER`)가 던진 것이 이 kind다. reconnect `attempt`·`waitClosed`의 던짐은 `PROVIDER_UNAVAILABLE`이다(1106/04-01). poll `execute`는 던지지 않는 V3 실행기를 감싸고, `attempt`는 던질 수 있는 연결 API를 감싸기 때문이다 | terminal/rollout rollback | | `MALFORMED_EVENT` | state-bearing syntax/schema/exact-key 실패 | cursor 미진행, freshness `UNKNOWN`, close + registered recovery | | `MAPPING_CONTRACT_VIOLATION` | validated DTO의 registered mapper 실패 | effect/cache/cursor write 0, close + registered recovery | | `EVENT_CONFLICT` | 같은 ID/sequence가 다른 event를 가리킴 | terminal protocol conflict + resync/rollback | diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index 17121c2a..34d9bff8 100644 --- a/docs/manual/01-add-a-feature.md +++ b/docs/manual/01-add-a-feature.md @@ -269,6 +269,7 @@ DTO와 problem details(`type`·`title`·`status`)를 감싸지 않고 보내는 - `boundary`: descriptor의 입력·응답·실패 검증기와 라우트의 `paramsSchema`·`searchSchema`에서 쓰인 자리로 정해진다. 다르면 `: row <적은 값>, used as <맞는 값>`으로 실패한다. 쓰이는데 행이 없으면 `: no FE-REG-SCHEMA row`. - `direction`: 입력은 `REQUEST`, 응답·실패는 `RESPONSE`. - `unknownFieldPolicy`: zod가 모르는 키를 거부하면(`.strict()`) `REJECT_UNKNOWN`, 버리면(`.strip()`) `STRIP_UNKNOWN`. +- descriptor의 입력·응답·실패 검증기로 쓰인 스키마의 행은 `direction`·`unknownFieldPolicy`를 빼지 않는다. 빼면 `row states no direction` 또는 `row states no unknownFieldPolicy`로 실패한다(1106/07-02). 칸이 없으면 응답 DTO를 `.strict()`로 바꿔도 행이 바뀌지 않아 `check:registries`가 breaking으로 보지 못한다. 라우트에만 쓰이는 행은 두 칸이 없어도 된다. 모르는 필드를 볼 객체가 없는 검증기(`responseBody: "NONE"` 출력의 `z.undefined()`, 문자열·null 본문)는 `direction`만 본다. - 이 테스트는 설치된 기능을 읽는다. 기능을 더한 상태에서 `test:unit`을 돌릴 때 잡힌다. 예: 공지 기능의 검색값 GET과 경로 파라미터 GET. 입력에 관한 칸과 응답 모양 줄만 적었다. @@ -431,6 +432,8 @@ projectRequest: (input) => Object.freeze({ - 이 spec은 등록된 모든 라우트를 열어 axe로 검사한다. 경로 파라미터는 이름과 상관없이 모두 `a11y-1`로 바꾼다. 파라미터 스키마가 이 값을 거부하면 기능 페이지 대신 잘못된 경로 화면을 검사하므로, id 스키마는 짧은 영문·숫자 문자열을 받게 둔다. - API 요청은 설치된 descriptor에서 method와 `pathTemplate`으로 찾아 답한다. 목록 조회에는 빈 목록을 그 operation의 모양(`responseEnvelope: "ENVELOPE_V1"`이면 Envelope)으로 답한다. 그 뒤 경고 상자(`role="alert"`)가 없는지 본다. 그래서 목록 페이지는 빈 상태로 검사된다. - 한 자원을 읽는 조회(경로 파라미터가 있고 빈 목록을 받지 않는 GET)에는 빈 목록 말고 답할 것이 없다. 그래서 상세 페이지는 실패 상태로 그려지고, 테스트 결과에 `a11y-data-state` annotation이 남는다. + - `a11y.json`은 그 라우트를 통과(`scope`)가 아니라 `notChecked`에 적는다. report(`scripts/write-a11y-report.ts`)는 라우트의 `paramsSchema`가 그런 GET의 입력 스키마이면 descriptor만 보고 그 라우트를 `notChecked`로 기대한다. spec이 기록을 남기지 않으면 `a11y.json not written:`으로 실패한다(1106/11-01). 생성 명령의 상세 라우트는 GET과 같은 `Params`를 쓰므로 이 규칙에 든다. + - 그 GET을 부르지 않는 페이지의 라우트(예: 상세 아래의 하위 항목 작성 폼 `/things/:thingId/parts/new`)는 상세 GET의 입력 스키마를 `paramsSchema`로 쓰지 않는다. 같은 스키마를 쓰면 report가 기록을 기대하는데 spec은 한 자원 응답을 보지 못해 기록을 남기지 않으므로 실패한다. 그 라우트에 자기 `paramsSchema`(예: `ThingPartCreateParams`)를 따로 둔다. - 설치된 GET이 아닌 요청을 그리기 전에 보내면 spec이 실패한다(`requests no installed list or single-resource read answers`). - spec은 h1이 보일 때까지 기다린다. 그래서 상세 페이지는 데이터가 없을 때도 h1을 그린다. 예: `heading={{ title: notice?.title ?? message("notice.detail.titlePending") }}`처럼 데이터가 없으면 고정 제목("공지")을 쓴다. - 기능이 앱 홈(`/`)을 대신하려면 route ID `APP_HOME`을 쓴다. `docs/architecture/starter-experience.md`의 "Product home and layouts" 절을 본다. @@ -473,8 +476,10 @@ projectRequest: (input) => Object.freeze({ - 형식: `qinv.` + 소문자·숫자 26자. `scripts/create-feature.ts`의 `randomTopicSuffix`가 쓰는 방식이다. - `measureResult`에서 `JSON.stringify`를 쓰지 않는다. 문자열 바이트와 항목당 고정 크기로 어림한다(생성된 `measureItems` 참고). - 뮤테이션 정책의 operation ID와 `requiresIdempotencyKey`는 `commandMutationIdentity(_CONTRACT)`(`src/contracts/server-state.ts`)로 descriptor에서 받는다. 손으로 적지 않는다. - - 실행기는 intent의 operation ID가 descriptor와 다르면 보내기 전에 거부한다. 손으로 적은 ID에 오타가 있으면 저장이 항상 실패하고, 화면은 "요청을 처리할 수 없습니다"다. + - 실행기는 intent의 operation ID가 descriptor와 다르면 보내기 전에 거부한다. 문자열 ID는 그보다 먼저 `check:types`가 막는다(③). 그래서 저장 때 거부되는 것은 `commandMutationIdentity`에 손으로 만든 객체를 넘긴 오타뿐이다. 그때는 저장이 항상 실패하고, 화면은 "요청을 처리할 수 없습니다"다. - `requiresIdempotencyKey`는 `retrySemantics`가 `KEYED`일 때만 참이다. + - V3 HTTP descriptor가 없는 쓰기(Fileserver 업로드처럼 `execute`가 HTTP 실행기를 거치지 않는 것)는 descriptor 모양 객체를 넘긴다: `...commandMutationIdentity({ contract: { operationId: "", method: "POST", retrySemantics: "KEYED" } })`. intent가 멱등 키를 실어야 하면(Fileserver 업로드에 `idempotencyKey`를 넘길 때) `retrySemantics`는 `"KEYED"`, 아니면 `"NEVER"`다. 이 ID를 대조할 descriptor가 없으므로 ID는 intent의 이름일 뿐이고, 오타는 어느 검사도 잡지 않는다(③). + - 테스트에서 descriptor 없이 정책을 만들 때는 `tests/helpers/mutation-operation-id.ts`의 `testMutationOperationId("")`를 쓴다. 이 helper는 operation ID만 돌려주므로 `requiresIdempotencyKey`는 따로 적는다. 문자열을 그대로 적으면 `check:types:test`가 실패한다. - 쓰기 정책은 `duplicatePolicy: "REJECT_WHILE_ACTIVE"`, `invalidate: [topic]`을 쓴다. ```ts @@ -497,7 +502,7 @@ projectRequest: (input) => Object.freeze({ - topic·namespace·edge를 더하기만 하면 레지스트리 기준선은 바뀌지 않는다(additive). 9단계에서 할 일이 없다. - 뮤테이션 정책의 operation ID를 `commandMutationIdentity`로 받으면 descriptor 상수 이름의 오타는 `check:types`가 막는다. 쓰기 descriptor 대신 GET descriptor를 넘기면 바인딩 때 `commandMutationIdentity: is a GET; a mutation binds a write operation`으로 throw한다. - 뮤테이션 정책에 operation ID를 문자열로 직접 적으면 `check:types`가 실패한다. `BoundMutation.operationId`는 `MutationOperationId`이고, 이 값은 `commandMutationIdentity`만 만든다. 오류는 그 문자열을 `MutationOperationId`에 넣을 수 없다고 말한다. -- **못 잡음**: `commandMutationIdentity`에 descriptor 상수 대신 손으로 만든 객체(`{ contract: { operationId: "…", … } }`)를 넘기는 것. 그 오타는 저장할 때 실행기가 보내기 전에 거부한다(`MISSING_IDEMPOTENCY_KEY` 위반). +- **못 잡음**: `commandMutationIdentity`에 descriptor 상수 대신 손으로 만든 객체(`{ contract: { operationId: "…", … } }`)를 넘기는 것. descriptor가 있는 쓰기면 그 오타는 저장할 때 실행기가 보내기 전에 거부한다(`MISSING_IDEMPOTENCY_KEY` 위반). descriptor가 없는 쓰기(②의 Fileserver 업로드 등)는 대조할 곳이 없어 오타가 그대로 intent 이름이 된다. - `bindQuery`의 `owner`·`operationId`, 뮤테이션 정책의 `owner`는 적지 않는다. 읽는 곳이 없어 `@deprecated` 선택 칸이 됐고, 다음 릴리스에서 지운다. 요청 기록의 operation ID는 descriptor의 것이다. - **못 잡음**: `definitionId` 중복. 유일성 검사가 없다. @@ -512,7 +517,7 @@ projectRequest: (input) => Object.freeze({ ① **정할 것** - 페이지 템플릿. [02 결정표 6절](02-decision-tables.md#6-페이지-템플릿) -- 쓰기가 있으면 결과 불명 화면. `AsyncSurface`의 `onReconcileUnknownEffect`(확인), `onResendUnknownEffect`(같은 키로 다시 보내기). 다시 보내기 버튼은 키가 있는 요청(`KEYED`)에만 그려진다. `NEVER` 쓰기는 확인만 남는다. 폼 밖에서 `mutation.submit`을 부르는 화면도 `NEVER` 쓰기의 같은 입력을 다시 보낼 수 없다. 훅이 `DUPLICATE_IN_FLIGHT`(code `UNKNOWN_EFFECT_PENDING`)로 거절한다. `AsyncSurface`에 손으로 만든 상태를 넘기면 재전송 버튼은 그려지지 않는다(코디네이터의 `state`를 넘긴다). +- 쓰기가 있으면 결과 불명 화면. `AsyncSurface`의 `onReconcileUnknownEffect`(확인), `onResendUnknownEffect`(같은 키로 다시 보내기). 다시 보내기 버튼은 다시 보내도 되는 요청(`KEYED`, `IDEMPOTENT`. 뮤테이션 정책의 `resendSafe`)에만 그려진다. `NEVER` 쓰기는 확인만 남는다. 폼 밖에서 `mutation.submit`을 부르는 화면도 `NEVER` 쓰기의 같은 입력을 다시 보낼 수 없다. 훅이 `DUPLICATE_IN_FLIGHT`(code `UNKNOWN_EFFECT_PENDING`)로 거절한다. `AsyncSurface`에 손으로 만든 상태를 넘기면 재전송 버튼은 그려지지 않는다(코디네이터의 `state`를 넘긴다). - 폼이면 서버 필드 오류를 받을 필드(`useAppForm`의 `allowedServerFields`). 짝 백엔드는 필드 검증 거절을 400 `VALIDATION_FAILED`와 `details[{field, code}]`로 보낸다(422가 아니다). 공유 MSW 시나리오에는 짝 백엔드가 보내지 않는 `validation-422`만 있고, Envelope operation에서 그 답은 결과 불명이다. 짝 백엔드 모양의 필드 오류 테스트는 생성된 작성 폼 테스트(`-create-page.test.tsx`)처럼 400 본문을 손으로 적는다. ② **기준** @@ -656,10 +661,12 @@ corepack pnpm test:sample-removal -- --feature=invoice-feature ③ **잡는 검사 / 못 잡는 것** -- 남은 파일이 지운 기능을 가리키면 실패한다. `src`는 기능 ID나 폴더 이름을 담은 파일, `tests`는 이름에 기능 ID가 있거나 기능 폴더에서 import하는 파일이다. +- 남은 파일이 지운 기능을 가리키면 실패한다. `src`는 기능 ID나 폴더 이름을 담은 파일, `tests`는 이름에 기능 ID가 있거나 기능 폴더에서 import하는 파일, 그리고 본문에 `-`가 든 기능 ID나 폴더 이름을 한 이름으로 적은 Playwright spec(`*.spec.ts`)이다. - 메시지: ` removal failed:` 다음 줄 `fixture-id-residue: residue: ` - 템플릿 테스트가 예시 ID(`invoice-feature` 등)를 데이터로 쓰는 것은 잔여로 세지 않는다(1105/16-04). 그래서 매뉴얼 예시 이름으로 만든 기능도 이 단계를 통과한다. -- **못 잡음**: 기능을 가리키지 않는 폴더 밖 파일. 예: route ID만 적은 e2e spec, `artifacts/tests/a11y-manual/.md`. `tests` 안에서 기능 ID를 글자로만 적은 테스트도 잔여로 세지 않는다. 그 테스트가 지운 기능에 기대면 같은 드릴의 `test:all`이 실패한다. 드릴은 `src`와 `tests`만 찾고, a11y 기록은 남아도 검사가 실패하지 않는다. + - spec 본문은 이름 단위로 찾는다(1106/16-01). 적힌 그대로(대소문자 구분) 찾고, 앞뒤에 `[A-Za-z0-9_-]`가 붙으면 다른 이름이다. `test.describe("invoice-feature", …)`는 잔여이고, `product-feature`를 지울 때 `generate-product-feature-index.ts`처럼 더 긴 이름 안에 든 것은 잔여가 아니다. spec은 `test:all`(vitest)도 드릴의 다른 단계도 돌리지 않으므로 이 검사가 아니면 다음 CI의 브라우저 게이트에서야 실패한다. + - `-`가 없는 한 단어 ID·폴더 이름(`messages`, `status`)은 spec 본문에서 찾지 않는다. 템플릿 spec이 그 단어를 평범하게 쓰므로(`status: 200`, `getByRole("status")`) 찾으면 템플릿 spec이 잔여로 나온다. +- **못 잡음**: 기능을 가리키지 않는 폴더 밖 파일. 예: route ID나 URL만 적은 e2e spec, 한 단어 ID만 본문에 적은 spec, `artifacts/tests/a11y-manual/.md`. 기능 전용 spec은 [03 문서](03-outside-feature-folder.md)의 목록대로 손으로 지운다. vitest 테스트(`*.test.ts`) 안에서 기능 ID를 글자로만 적은 것도 잔여로 세지 않는다. 그 테스트가 지운 기능에 기대면 같은 드릴의 `test:all`이 실패한다. 드릴은 `src`와 `tests`만 찾고, a11y 기록은 남아도 검사가 실패하지 않는다. ④ **쓸 스킬**: `documentation-and-adrs`, `deprecation-and-migration` diff --git a/docs/manual/02-decision-tables.md b/docs/manual/02-decision-tables.md index a63a822e..10e5d217 100644 --- a/docs/manual/02-decision-tables.md +++ b/docs/manual/02-decision-tables.md @@ -89,7 +89,8 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기 | 서버 보장 | 멱등 키(`Idempotency-Key` 헤더)로 같은 요청의 중복 적용을 막는다 | 같은 요청을 여러 번 적용해도 결과가 같다 (키 없이) | 중복을 막지 못한다 | | 자동 재시도 | 실제로 보내기 전까지만. 보낸 뒤 결과를 모르면 결과 불명(4절)으로 넘긴다. 예외: 짝 백엔드가 503 `IDEMPOTENCY_UNAVAILABLE`(실행 전 거절)로 답하면 `retryBudget` 안에서 같은 키로 다시 보낸다 | 된다 | 하지 않는다 | | descriptor | `commandRecovery: { mode: "IDEMPOTENCY_REPLAY", operationIdentityField }` 필수. 짝 백엔드는 `retryBudget: 1`(아래 표), 참조 기능은 `0` | — | `retryBudget: 0` 필수 | -| 뮤테이션 정책 | `...commandMutationIdentity(_CONTRACT)`가 `requiresIdempotencyKey: true`를 준다 | 같은 함수가 `false`를 준다 | 같은 함수가 `false`를 준다 | +| 뮤테이션 정책 | `...commandMutationIdentity(_CONTRACT)`가 `requiresIdempotencyKey: true`, `resendSafe: true`를 준다 | 같은 함수가 `requiresIdempotencyKey: false`, `resendSafe: true`를 준다 | 같은 함수가 둘 다 `false`로 준다 | +| 결과 불명 뒤 | "같은 요청으로 다시 보내기"와 같은 입력 저장이 같은 키로 간다 | 다시 보내기와 같은 입력 저장이 키 없이 간다(1106/03-03) | 확인만 남는다. 같은 입력 저장은 보내지 않는다 | - 멱등 키: 서버가 "같은 쓰기 요청"을 알아보게 하는 값이다. - 결과를 모를 때 새 키로 다시 보내면 안 된다. 서버는 새 키를 다른 요청으로 보고 막지 못한다. @@ -324,7 +325,7 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기 - 멱등성 응답(`IDEMPOTENT_*`, `IDEMPOTENCY_*`)과 V3 표에 있는 web 공통 응답은 V3 실행기와 같은 표(`backend-envelope.ts`, 4절)로 판정한다. 400 `IDEMPOTENCY_KEY_INVALID`·422 `IDEMPOTENT_REQUEST_MISMATCH`는 `NOT_APPLIED`, 409 `IDEMPOTENT_IN_FLIGHT`·503 `IDEMPOTENCY_UNAVAILABLE`·503 `IDEMPOTENCY_COMPLETION_UNKNOWN`·500 `IDEMPOTENCY_RECOVERY_REQUIRED`는 `MAYBE_APPLIED`다. - `APPLIED_CONFIRMED`: 서버는 만들었다고 답했지만 응답을 읽지 못했다. 다시 올리지 않는다. - `code`는 백엔드 code 그대로다(`FILE_TOO_LARGE`, `UNSUPPORTED_MEDIA_TYPE`, `MALWARE_DETECTED` …). 백엔드가 code를 주지 않는 거절은 client가 이름을 붙인다(`FILE_REJECTED`, `FILE_EMPTY`, `FILE_NOT_READABLE`). 화면 문구는 기능이 code로 고른다. -- 실패 Envelope의 `meta.traceId`는 실패의 `traceId`로 온다. V3 실행기와 같다. 지원 담당이 서버 로그에서 그 요청을 찾을 때 쓴다. +- 실패 Envelope의 `meta.traceId`는 실패의 `traceId`로 온다. V3 실행기와 같다. 지원 담당이 서버 로그에서 그 요청을 찾을 때 쓴다. 202 `REJECTED`의 `FILE_REJECTED`도 성공 Envelope의 `meta.traceId`를 싣는다. 이 응답에는 거절 이유가 없다. 짝 백엔드는 검증기 code를 파일 레코드에만 적는다. 그래서 화면은 이유별 문구를 고를 수 없다. - client는 스스로 다시 보내지 않는다. `retryable: true`이고 `retryAfterMs`가 있으면 그만큼 기다린 뒤 기능이 다시 부른다. 서버가 상한(`maxRetryAfterMs`, 기본 30초)보다 길게 기다리라고 하면 `retryable: false`다. - `MAYBE_APPLIED`는 언제나 `retryable: false`다. 백엔드가 Envelope에 `retryable: true`와 `Retry-After`를 붙여도(504 `TRANSFER_TIMEOUT`) 기능이 자동으로 다시 부르지 않는다. 아래 주의대로 먼저 확인한다. diff --git a/docs/manual/reference/create-feature.md b/docs/manual/reference/create-feature.md index e052d8c7..eec50049 100644 --- a/docs/manual/reference/create-feature.md +++ b/docs/manual/reference/create-feature.md @@ -66,7 +66,7 @@ corepack pnpm create:feature [--context ] [--with-create [--key - `presentation/use--create.ts`: 작성 뮤테이션 정책(`commandMutationIdentity`) - `presentation/-form.ts`: 폼 스키마. 이름 길이는 요청 스키마의 상수(`_NAME_MAX_LENGTH` = 백엔드 `NAME_MAX_LENGTH` 100)를 쓴다 - `presentation/-detail-page.tsx`: `DetailPage` -- `presentation/-create-page.tsx`: `FormPage`. 저장하면 상세를 연다. 결과 불명이면 `AsyncSurface`를 보인다 +- `presentation/-create-page.tsx`: `FormPage`. 저장하면 상세를 연다. 저장 중에 화면을 떠났으면 옮기지 않는다. 결과 불명이면 `AsyncSurface`를 보인다 `domain/`은 만들지 않는다. 업무 규칙이 생기면 사람이 만든다. @@ -76,7 +76,7 @@ corepack pnpm create:feature [--context ] [--with-create [--key - `-feature-input.test.ts`: input 단위 테스트 - `-list-page.test.tsx`: 라우터를 거치는 페이지 테스트(목록, `meta.page.total`, 빈 목록, 실패 후 다시 시도) - `-http-gateway.test.ts`: 짝 백엔드 본문을 손으로 적은 gateway 테스트. 하네스의 재시도 상한은 앱 기본값 2다 -- `-create-page.test.tsx`(`--with-create`): 201 저장 뒤 상세, 400 `_INVALID` 필드 오류와 다시 저장, 응답을 잃은 저장(`NEVER`는 다시 보내기 없음, `KEYED`는 같은 키로 다시 보내기) +- `-create-page.test.tsx`(`--with-create`): 201 저장 뒤 상세, 400 `_INVALID` 필드 오류와 다시 저장, 응답을 잃은 저장(`NEVER`는 다시 보내기 없음, `KEYED`는 같은 키로 다시 보내기), 저장 중 목록으로 간 뒤 끝난 저장(목록에 머문다) 기능 폴더 밖: diff --git a/docs/manual/reference/errors.md b/docs/manual/reference/errors.md index 8f4a9af9..3595a75f 100644 --- a/docs/manual/reference/errors.md +++ b/docs/manual/reference/errors.md @@ -86,6 +86,7 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010 | `duplicate operation: ` (계약 조립 오류의 `reason`) | operation ID 중복 | `contracts/-contract-contribution.ts`. 접두어를 붙인다 | | `FE-REG-API..requestSchema references unknown FE-REG-SCHEMA.schemaId=` | descriptor의 입력 스키마 ID가 스키마 메타데이터에 없다 (`responseSchema`, `problemSchema`도 같은 꼴. 실패 본문 행은 `boundary: "api-problem"`) | `contracts/-schema-metadata.ts` | | `: row , used as ` (`tests/unit/schema-metadata-policy.test.ts`) | 스키마 메타 행의 `boundary`가 그 스키마가 쓰인 자리와 다르다. `no FE-REG-SCHEMA row`는 쓰이는데 행이 없다 | `contracts/-schema-metadata.ts` | +| ` : row states no direction, used as ` 또는 `row states no unknownFieldPolicy, validator ` (`tests/unit/schema-metadata-policy.test.ts`) | descriptor가 쓰는 스키마의 행이 `direction`·`unknownFieldPolicy`를 적지 않았다(1106/07-02) | `contracts/-schema-metadata.ts`에 두 칸을 적는다. 값은 쓰인 자리와 검증기가 정한다. 객체가 아닌 본문의 검증기(`z.undefined()` 등)는 `direction`만 요구한다 | | `Unregistered route codec: ` | URL 함수가 기능 codec을 `buildRouteUrl`에 넘기지 않았다 | `presentation/-routes.ts` | | `contract package is declared, but no loaded contribution pins it` | 계약 `contractPackages`에 적은 패키지를 계약 기여가 쓰지 않는다 | `contracts/-contract-contribution.ts`의 `source` | | ` contributes contract package , which no installed feature declares in contracts.contractPackages` | 계약 기여의 신원과 계약 선언의 신원이 다르다 | 둘 다 `_CONTRACT_PACKAGE` 하나를 쓰게 한다 | @@ -177,6 +178,7 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010 |---|---|---| | `artifacts/tests/a11y-manual/ has no record for route IDs: ` (`verify:documentation`) | 라우트의 a11y 기록 파일이 없다 | 기존 pending 기록을 복사해 제목과 `Route ID`를 바꾼다 | | `Manual accessibility record format is invalid:` 다음 `artifacts/tests/a11y-manual/.md: missing record` (FE-GATE-009) | 같은 원인 | 같은 곳 | +| `a11y.json not written:` 다음 `a11y: reads one resource () but has no failure-state record in artifacts/tests/a11y-data-state` (`test:a11y`, FE-GATE-009) | 라우트의 `paramsSchema`가 한 자원을 읽는 GET의 입력인데, 접근성 spec이 그 라우트를 실패 화면으로만 봤다는 기록이 없다(1106/11-01). spec이 기록 호출을 놓쳤거나, 그 라우트의 페이지가 그 GET을 부르지 않아 spec이 실패 화면을 보지 않았다. 앞의 경우 그대로면 `a11y.json`이 그 라우트를 통과로 센다 | 페이지가 그 GET을 부르면 `tests/e2e/accessibility.spec.ts`의 기록 호출(`recordA11yDataState`)을 본다. 이때 기능 파일은 고치지 않는다. 페이지가 그 GET을 부르지 않으면(예: `/things/:thingId/parts/new` 같은 하위 항목 작성 폼이 상세 GET과 같은 `ThingParams`를 쓴다) 그 라우트에 자기 `paramsSchema`를 따로 둔다. 기능의 라우트 계약과 `contracts/-schema-metadata.ts`를 고친다 | | `Manual accessibility evidence is incomplete:` 다음 `: ` (FE-GATE-028) | 서명하지 않은 기록 | [03 문서](../03-outside-feature-folder.md#수동-접근성-검토-서명) | | `release IDs do not match` (FE-GATE-028) | 라우트마다 다른 릴리스로 검토했다 | 같은 릴리스 후보로 다시 검토한다 | | ` names paths that do not exist: ` (`verify:documentation`) | 문서가 없는 경로를 적었다 | 그 문서 | @@ -196,6 +198,6 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010 | 메시지 | 원인 | 고칠 곳 | |---|---|---| -| ` removal failed:` 다음 `fixture-id-residue: residue: ` (`test:sample-removal`) | 기능을 지운 뒤에도 그 기능을 가리키는 파일이 남았다. `src`는 기능 ID나 폴더 이름을 담은 파일, `tests`는 이름이 기능 ID를 담거나 기능 폴더(`src/features//`, `tests/features//`)에서 import하는 파일이다 | 그 파일을 기능 폴더 안으로 옮기거나, 기능을 가리키지 않게 한다. 목록에 템플릿 파일이 나오면 템플릿 결함이다. 그 파일을 고치지 말고 템플릿에 알린다 | +| ` removal failed:` 다음 `fixture-id-residue: residue: ` (`test:sample-removal`) | 기능을 지운 뒤에도 그 기능을 가리키는 파일이 남았다. `src`는 기능 ID나 폴더 이름을 담은 파일, `tests`는 이름이 기능 ID를 담거나 기능 폴더(`src/features//`, `tests/features//`)에서 import하는 파일, 본문에 `-`가 든 기능 ID나 폴더 이름을 적힌 그대로 한 이름으로 적은 Playwright spec(`*.spec.ts`)이다 | 그 파일을 기능 폴더 안으로 옮기거나, 기능을 가리키지 않게 한다. 지운 기능 전용 spec이면 지운다. 목록에 템플릿 파일이 나오면 템플릿 결함이다. 그 파일을 고치지 말고 템플릿에 알린다 | | `No installed feature declares FEATURE_MODULE_ID ""` | `--feature=`에 없는 기능 ID | 명령 인자 | | `feature scaffold failed:` 다음 `: ` (`test:feature-scaffold`) | 생성한 기능이 게이트 하나를 통과하지 못했다 | `scripts/create-feature.ts`의 템플릿. 제품 팀이 아니라 템플릿을 고칠 일이다 | diff --git a/docs/operations/api-contract-and-server-state-recovery.md b/docs/operations/api-contract-and-server-state-recovery.md index ba60984a..74e0ed3e 100644 --- a/docs/operations/api-contract-and-server-state-recovery.md +++ b/docs/operations/api-contract-and-server-state-recovery.md @@ -256,12 +256,23 @@ diagnostics에만 남고 `api.request.failed`에는 세지 않는다(03-07). 그 다시 보내기"는 그 intent와 같은 `Idempotency-Key`로 보낸다. 입력이 바뀌면 새 key다. 자동 재전송은 없다(`src/presentation/adapters/query/application-query.ts` `submit`·`resendUnknownEffect`, 화면 `src/presentation/components/async-surface.tsx`). + 다시 보낸 요청이 쓰기 전에 거절되거나(429, 401, 403, 503 `RATE_LIMIT_*`, 422 + `IDEMPOTENT_REQUEST_MISMATCH`, 기능이 선언한 code) 보내지 못하면(`NOT_STARTED`) 그 + 시도만 적용되지 않은 것이다. 결과 불명과 key는 그대로다. 폼은 "잠시 뒤 같은 요청으로 + 다시 보내 주세요"와 결과 불명 화면(확인, 다시 보내기)을 보이고 저장을 받지 않는다. + 401은 다시 로그인 안내가 먼저다. 예외는 같은 요청이 매번 받는 거절이다. 짝 백엔드 표의 + 400 `VALIDATION_FAILED`(필드 목록이 있든 없든)와 400 `IDEMPOTENCY_KEY_INVALID`만 첫 + 요청도 거절됐다는 뜻으로 읽어 결과 불명을 풀고, 폼은 필드 오류를 보이고 저장을 다시 + 받는다. 기능의 `mapProblem`이 정한 kind(`VALIDATION_REJECTED`)는 보지 않는다. 기능 + code는 상태 규칙일 수 있다(1106/03-01, `src/contracts/errors.ts` + `isRefusedOnEveryAttempt`). 키가 없는 command(`NEVER`)는 서버가 두 번째 요청을 가려내지 못하므로 재전송 버튼을 그리지 않는다(`canResendUnknownEffect`, 0929/03-03). 같은 canonical input의 재저장도 보내지 않는다. 훅의 `submit`이 `NOT_STARTED` `DUPLICATE_IN_FLIGHT`(code `UNKNOWN_EFFECT_PENDING`)를 돌려주고, 결과 불명 요청이 확인될 때까지 그대로다. 폼 밖에서 `submit`을 부르는 화면도 같다. 화면은 상태에 `unknownEffectResendable: true`가 - 있을 때만 재전송 버튼을 그린다. + 있을 때만 재전송 버튼을 그린다. `IDEMPOTENT` command는 키가 없어도 두 번 적용한 + 결과가 같아서 재전송과 같은 입력 재저장을 보낸다(정책 `resendSafe`, 1106/03-03). 5. backend status/receipt로 `COMMITTED`면 cache reconcile/invalidate한다. 화면의 "변경됨으로 확인"이 이 경로다. 6. `NOT_APPLIED`가 증명된 경우만 정책에 따라 retry한다. 화면은 근거 없는 diff --git a/docs/operations/browser-file-storage-recovery.md b/docs/operations/browser-file-storage-recovery.md index dd758100..5815615d 100644 --- a/docs/operations/browser-file-storage-recovery.md +++ b/docs/operations/browser-file-storage-recovery.md @@ -611,10 +611,11 @@ Service Worker를 별도 선택한 조합에서만 추가. 워커의 fetch 가 `skipWaiting()`하고, 활성화 때 `registration.unregister()`한다. fetch handler가 없어서 그동안의 요청은 모두 네트워크로 간다. 다음 load부터는 제어받지 않는다. 브라우저 확인: `tests/e2e/service-worker-recovery.spec.ts`. -- 이 경로가 동작하려면 `service-worker.js`를 `Cache-Control: no-cache`로 서빙해야 - 한다. 워커를 싣는 빌드(`ACTIVE`·`REMOVE_REGISTRATION`)에서는 - `verify:hosting-headers` live 모드가 `/service-worker.js`를 요청해 이 헤더를 - 확인하고, 다르면 FAIL이다(`config/hosting/cache-policy.json` `serviceWorker`, +- 이 경로가 동작하려면 `service-worker.js`를 `Cache-Control: no-cache`로, redirect + 없이 서빙해야 한다. 브라우저는 워커 스크립트의 redirect를 같은 origin 안이라도 + 거절한다. 워커를 싣는 빌드(`ACTIVE`·`REMOVE_REGISTRATION`)에서는 + `verify:hosting-headers` live 모드가 `/service-worker.js`를 요청해 이 헤더와 + redirect를 확인하고, 다르면 FAIL이다(`config/hosting/cache-policy.json` `serviceWorker`, `scripts/verify-hosting-headers.ts`). fixture 모드는 선언끼리만 대조하므로 `UNVERIFIED`다. 하위 경로 base URL은 live probe가 아직 받지 않는다 (`scripts/lib/hosting-probe.ts` `classifyLiveHostingBaseUrl`, 리뷰 0929/13-06). diff --git a/docs/operations/ci-quality-gates.md b/docs/operations/ci-quality-gates.md index 7a34e9ab..ebb83275 100644 --- a/docs/operations/ci-quality-gates.md +++ b/docs/operations/ci-quality-gates.md @@ -168,7 +168,11 @@ Producer는 게시 전에 manifest가 선언한 exact member set과 각 byte dig 검증하고 archive SHA-256을 job output으로 고정한다. 같은 job은 마지막 단계에서 FE-GATE-015·027의 gate log와 evidence, `scan:dependency-advisories` 기록을 후보와 다른 이름(`immutable-gate-evidence--`)으로 성공·실패와 상관없이 -올린다(1105/13-01). `ci:gate`는 명령 출력을 gate log에만 쓰고 콘솔에는 한 줄만 +올린다(1105/13-01). 올라가는 것은 그 run에 생긴 파일이다. `ci:gate`는 처음 실패한 +명령에서 멈추므로 FE-GATE-027은 막지 않는 advisory 검사를 승인보다 먼저 돌린다. +그래서 승인이 거절된 run에도 advisory 기록이 있다(1106/13-01). FE-GATE-015가 +실패하면 FE-GATE-027이 돌지 않으므로 그 run에는 FE-GATE-027의 log와 advisory +기록이 없다. `ci:gate`는 명령 출력을 gate log에만 쓰고 콘솔에는 한 줄만 남기므로, release 단계의 실패 이유는 이 산출물에서 읽는다. 후보 archive의 member set은 그대로다. Vulnerability/provenance provider job은 같은 archive를 각각 내려받아 output SHA-256과 exact member set을 @@ -528,7 +532,8 @@ Repository variables required by higher tiers: job runs FE-GATE-015 and then FE-GATE-027, and FE-GATE-027 refuses the candidate when `APP_PROFILE` is set and differs from `RELEASE_TARGET`. Both are repository-wide variables, so set them together for each release. - FE-GATE-027 then runs `scan:dependency-advisories` (1103/13-03). It applies + FE-GATE-027 runs `scan:dependency-advisories` first and the admission after + it (1103/13-03, 1106/13-01). It applies `config/security/vulnerability-policy.json` and its exceptions to the registry's advisory report for the lockfile (pnpm's audit command with `--json`) and writes the result to the gate log @@ -540,7 +545,11 @@ Repository variables required by higher tiers: The job console shows only one PASS/FAIL line per gate, so the immutable_build job uploads both gates' logs and evidence and this record as the run artifact `immutable-gate-evidence--`, whether the job - passed or failed (1105/13-01). Read why FE-GATE-015 or FE-GATE-027 failed, + passed or failed (1105/13-01). It holds the files the run produced. `ci:gate` + stops at the first command that fails, and the scan runs before the + admission, so a run whose admission was refused still has the advisory + record. When FE-GATE-015 fails, FE-GATE-027 does not run, and the run has + neither its log nor the record. Read why FE-GATE-015 or FE-GATE-027 failed, and the advisory status, there. `renovate.json` opens security update PRs once a Renovate runner is attached; a dependency update re-approves the dependency baseline in the same change diff --git a/docs/operations/client-cache-and-storage-recovery.md b/docs/operations/client-cache-and-storage-recovery.md index 5780b9c5..b768b139 100644 --- a/docs/operations/client-cache-and-storage-recovery.md +++ b/docs/operations/client-cache-and-storage-recovery.md @@ -27,6 +27,12 @@ session/account Query lifecycle, strict query policy와 Web Storage v2 lifecycle 않는다. 두 operation은 Cache Storage와 mutation lock만 요구하고 실패 시 recovery는 `RETRY`다. `stageRelease`만 fetcher를 요구하며 recovery는 `ONLINE_ONLY`다. +- active pointer 본문을 계속 읽지 못하면 조회, `activateRelease`, + `cleanupOwned`, `inspect`가 모두 같은 실패를 계속 돌려준다. 다시 시도해도 + 돌아오지 않는다. pointer를 쓰는 곳은 activation 하나다. 이때 + `activateRelease(id, digest, { replaceUnreadablePointer: true })`로 검증된 + release를 활성화한다. rollback 목록은 잃고, 다음 cleanup이 다른 owned release + cache를 지운다. 옵션 없는 activation은 일시 오류에서 멈춘다(1106/02-01). - variant를 사용하는 policy(`allowedVaryHeaderNames` 비어 있지 않음)는 반드시 `allowedResponseHeaderNames`에 `vary`를 포함해야 한다. 아니면 composition이 `TypeError`로 즉시 실패한다. 저장된 variant가 같은 key로 충돌하는 상태를 만들지 diff --git a/docs/operations/performance-evidence.md b/docs/operations/performance-evidence.md index 081b6f40..c1c6b1de 100644 --- a/docs/operations/performance-evidence.md +++ b/docs/operations/performance-evidence.md @@ -51,6 +51,17 @@ Performance evidence is deliberately split by measurement context: 넘을 때, 또는 1103/13-03(zod 갱신, 약 7 KB)을 정할 때. 그때 03-01·02-01의 런타임 검사를 빌드 시점으로 옮기는 것부터 본다. 이 상향은 13-03을 정하지 않는다. 결정 기록은 `docs/reviews/2026-11-05-maturity-review/README.md` 16절이다. + - 폭의 근거(1106/15-01, 결정 D9): 예산은 드릴 측정값에 기능 하나의 상한 + (`perFeatureGzipBytes` 상한 1 KiB)을 더해 KiB 단위로 올림한 값이다. 드릴은 + CI env에서 205,465 B였다(2026-11-06, `bbde570`, FE-GATE-020). 205,465 + + 1,024 = 206,489 B를 올림하면 202 KiB = 206,848 B다. 그래서 드릴 위의 여유 + 1,383 B는 기능 하나(1,024 B)와 올림(359 B)이다. 이 규칙에 템플릿 자신이 더 + 쓸 몫은 없다. 템플릿 변경이 이 여유를 쓰면 그만큼 기능 몫이 준다. + - 되돌림 규칙: 위 "다시 볼 때"마다 드릴을 다시 잰다. 드릴 측정값이 204,800 B + 이하이면 같은 규칙(드릴 + 1 KiB를 KiB 단위로 올림)으로 예산을 내린다. 그때 + 규칙의 값은 201 KiB 이하다. + - D9(206,848 B를 그대로 둔다)는 메인 세션이 2026-11-06에 정했다. 사용자가 뒤집을 + 수 있다. 결정 기록은 `docs/reviews/2026-11-06-maturity-review/README.md`다. - 기능 실행부(`feature-runtime.ts`)는 라우트에 들어갈 때 받는 lazy chunk다. lazy chunk 예산은 파일마다 120 KiB(`lazyChunkGzipBytes`)다. @@ -126,7 +137,8 @@ lab 측정(`scripts/test-performance.ts`, FE-GATE-026)은 local 프로필 build Playwright 기본값은 스크롤바를 숨겨서, 첫 화면에 세로 스크롤바가 생기며 header가 밀리는 shift를 lab이 보지 못했다. 화면 쪽은 `:root`의 `scrollbar-gutter: stable`이 그 자리를 처음부터 잡는다. 다른 Playwright 게이트 - (시각 골든 포함)는 여전히 스크롤바를 숨긴다. + (시각 골든 포함)는 여전히 스크롤바를 숨긴다. 예외는 그 자리를 modal 가림막이 + 덮는지 보는 `tests/visual/scrollbar-gutter.visual.spec.ts` 하나다(1106/08-03). - preview 서버는 자기 프로세스 그룹으로 띄우고 끝날 때 그룹 전체를 멈춘다. `corepack`에만 신호를 보내던 때는 vite가 포트를 계속 잡고 있었다. @@ -206,8 +218,10 @@ the example can never serve as production evidence. - HTTP/2에서는 (나)도 Fast 3G 85 ms, Fast 4G 22 ms 차이다(위 둘째 표). 그래서 템플릿은 HTTP/2 이상으로 서빙한다고 본다. 초기 파일 수는 -`config/performance/budgets.json`의 `initialJsFiles`가 막는다(1103/15-05). 상한은 -템플릿 그대로의 수(26)에 6을 더한 32다. 기능의 지연 페이지가 셸과 같은 구성요소 +`config/performance/budgets.json`의 `initialJsFiles`가 막는다(1103/15-05). 상한 32는 +정할 때 템플릿 그대로의 수에 6칸을 더한 값이다. 지금 템플릿 그대로의 수는 이 문서에 +적지 않는다. 위 기록 `config/scale/feature-shape-ceilings.json`의 +`initialJavascript.files`가 정본이고, 남은 칸은 32에서 그 값을 뺀 것이다. 기능의 지연 페이지가 셸과 같은 구성요소 (`Button`, `SearchField` 등)를 쓰면 그 구성요소가 별도 공유 청크로 떨어져 초기 파일이 하나 는다(1103 X2 #4). 상한을 현재 수와 같게 두면 그런 기능 하나로 게이트가 실패한다. HTTP/2에서 파일 하나는 거의 비용이 없다(위 표). 32를 넘으면 상한을 올리기 diff --git a/docs/operations/release-cache-rollback.md b/docs/operations/release-cache-rollback.md index b6211a37..5d782079 100644 --- a/docs/operations/release-cache-rollback.md +++ b/docs/operations/release-cache-rollback.md @@ -71,9 +71,12 @@ It also requests `appRoute` (`/__probe/deep-link`, a path no build has a file for): the host must answer 200 with the same `index.html` (the same entry script) and the HTML headers, so a host without the SPA fallback fails (review 1101/13-04). When the build ships a worker it requests -`/service-worker.js` and expects `no-cache`. The surfaces and their headers are -declared in `config/hosting/cache-policy.json`. For each cacheable extension the -release has under `assets/` (`.css`, `.js`, `.woff2` and the rest of +`/service-worker.js` and expects `no-cache` and no redirect at all, not even +one inside the origin: browsers fetch the worker script with redirect mode +`error`, so registration, every update check and the `REMOVE_REGISTRATION` +kill switch fail behind one (review 1106/06-01). The surfaces and their +headers are declared in `config/hosting/cache-policy.json`. For each cacheable +extension the release has under `assets/` (`.css`, `.js`, `.woff2` and the rest of `CACHEABLE_ASSET_CONTENT_TYPES`) it requests the first such file and expects exactly that type (`hashedAsset.css` and so on). The worker's install refuses the whole release when one precached asset has another type, while a page diff --git a/docs/reviews/2026-11-05-maturity-review/README.md b/docs/reviews/2026-11-05-maturity-review/README.md index bf17e563..ed3ef994 100644 --- a/docs/reviews/2026-11-05-maturity-review/README.md +++ b/docs/reviews/2026-11-05-maturity-review/README.md @@ -537,7 +537,7 @@ CLAUDE.md 목록, local env(CI 값 없음): | D4 | (가) 러너 요구에 비특권 user namespace를 적고, 사전 점검이 `bwrap --unshare-net`을 실제로 돌린다(PR A `9655958`, 기준선 `67082cc`) | 메인 세션 지시. 러너 요구는 요구 목록·gate 정의·workflow 주석 셋에 적는다 | (나) 샌드박스 방식 변경 | 러너가 namespace를 허용하지 않게 바뀔 때 | | D5 | 제품 gate를 release `needs`에 묶는다(`92d5019`) | 제품 merge 검사가 실패한 run에서 release를 멈춘다 | 문서로 제한 명시 | — | | D6 | 실행별 출력 디렉터리 + 빈 포트(`ddbda4d`, `f4d5761`, `0e72c0c`, `510e2bb`) | 메인 세션 지시와 완료 기준(한 checkout 두 e2e 동시 실행) | "한 checkout 한 실행"을 문서로 명시 | 게이트·증거 검사도 run ID를 읽게 할 때 | -| D7 | 초기 JS 예산 `initialJsGzipBytes`를 204,800 → 206,848 B(202 KiB)로 올린다(`287dc6f`). 메인 세션 결정, 2026-11-06 | 아래 「D7 근거」 | 줄이기. 리뷰 라운드 중간의 설계 변경이라 다음 라운드 숫자를 흐린다. 청크를 합치는 것만으로는 663 B를 채우지 못한다 | 예산을 다시 넘을 때, 또는 1103/13-03(zod 갱신, 약 7 KB)을 정할 때. 그때 03-01·02-01의 런타임 검사를 빌드 시점으로 옮기는 것부터 본다. 이 상향은 13-03을 정하지 않는다 | +| D7 | 초기 JS 예산 `initialJsGzipBytes`를 204,800 → 206,848 B(202 KiB)로 올린다(`287dc6f`). 메인 세션 결정, 2026-11-06. `287dc6f` 본문의 "늘어난 곳"이 03-01·08-03에 적은 해시 둘은 통합에서 다시 짓기 전 해시라 PR B 이력(`bbde570`)에서 닿지 않는다. 이 이력의 해시는 03-01 `5c0b37e`, 08-03 `f849d78`이다(아래 「D7 근거」와 같다). 올린 이력이라 본문은 고치지 않는다(1106/14-02) | 아래 「D7 근거」 | 줄이기. 리뷰 라운드 중간의 설계 변경이라 다음 라운드 숫자를 흐린다. 청크를 합치는 것만으로는 663 B를 채우지 못한다 | 예산을 다시 넘을 때, 또는 1103/13-03(zod 갱신, 약 7 KB)을 정할 때. 그때 03-01·02-01의 런타임 검사를 빌드 시점으로 옮기는 것부터 본다. 이 상향은 13-03을 정하지 않는다 | D7 근거: diff --git a/docs/reviews/2026-11-06-maturity-review/01-adapters-browser-transfer.md b/docs/reviews/2026-11-06-maturity-review/01-adapters-browser-transfer.md new file mode 100644 index 00000000..fddb42e1 --- /dev/null +++ b/docs/reviews/2026-11-06-maturity-review/01-adapters-browser-transfer.md @@ -0,0 +1,189 @@ +# 영역 01 — adapters: browser-transfer + +> 검토일 2026-11-06 · 기준 `bbde570`(`bbde570796b0a648bae65c2c0568fca860a3ba4e`, PR B 끝, 브랜치 `docs/maturity-review-2026-11-06`) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 경로: `src/adapters/browser-transfer/`(배럴 `index.ts`, `presigned/`, `resumable-upload/`, `image-cdn/`), 포트 `src/application/ports/browser-transfer/`, Fileserver 업로드 client `src/adapters/http/fileserver-upload.ts`와 그 통합 테스트 +> 짝 백엔드: `clean-architecture-backend-template` `45d2a478`(읽기만, `git show 45d2a478:`. `config/contracts/backend-contract-pin.json:5`의 pin. 지난 라운드와 같은 커밋) +> 깊게 본 관점: 6, 10, 17, 21, 23, 26, 28 +> 영역 판정(35.8): presigned 실행기·vault는 **지정 범위에서 사용 가능**. resumable upload runtime은 **조건부 사용 가능**(제품 backend가 `PRESIGNED_MULTIPART_V1` BFF를 직접 만들 때). 짝 백엔드와 함께 파일 업로드를 출시하는 용도는 **조건부 사용 가능**(Fileserver client. 조건: 재개 없음, 파일 전체를 메모리에 읽음, `MAYBE_APPLIED` 뒤 다시 보내면 파일이 둘 생길 수 있음(백엔드가 키를 읽지 않음. 504 `TRANSFER_TIMEOUT`도 여기 든다), Fileserver 자신의 code 표는 pin 대조 밖, 실제 짝 백엔드로 올려 본 적 없음). image CDN runtime은 **지정 범위에서 사용 가능**(reference runtime 범위). + +ID 표기: 이번 라운드 새 발견은 `01-01`부터 쓴다. 라운드 밖에서는 `1106/01-01`이다. 지난 라운드는 `1105/01-01`(2026-11-05), 그 전은 `1103/…`, `1101/…`, `0929/…`다. + +## 0. 결론 + +- **1105 네 건 중 셋은 고쳐졌다.** 1105/01-01(202 `REJECTED`, 빈 파일)과 1105/01-03(`traceId`)은 완료 기준을 코드와 `bbde570` 게이트 실행으로 확인했다. 1105/01-04는 변이 셋(FS4'·FS5·FS8)이 각각 기대한 테스트에서 기대한 이유로 실패했다(배치 01-R1·01-R3·01-R4, 6절). +- **1105/01-02는 일부다(§16.4는 "고침").** 위험한 줄(504 `TRANSFER_TIMEOUT` → `NOT_APPLIED`)은 빠졌다. 되넣으면 테스트 2건이 실패한다(01-R2). 멱등성·web 공통 code는 V3 표 하나로 판정하고 pin 답 표 9행으로 대조한다. 남은 것: Fileserver 자신의 code 표와 Fileserver 계약은 여전히 pin 대조 밖이다(수정이 07-01로 미뤘고 07-01은 넣지 않았다). 커밋 `471b001` 본문의 백엔드 요청 (b)는 "interrupt 확인"이라는 방법으로는 그 보장을 주지 못한다. +- **1103/01-01은 일부 그대로다.** 프론트 몫은 끝났다. 백엔드에 넘긴 두 가지(백엔드 매뉴얼의 짝 안내, `docs/fileserver/http-contract.md:10`의 202 state 목록)는 백엔드 `45d2a478` 코드와 맞게 적혀 있다. 실제 짝 백엔드로 올려 보지 않았다. +- **수정을 백엔드 코드와 다시 대조했다.** 202 `REJECTED` 본문의 `size`·`sha256`·`etag`는 검증 전에 레코드에 적히고 거절 전이가 지우지 않는다. 그래서 client schema를 통과해 `FILE_REJECTED`에 닿는다(2.1절). 503 `RATE_LIMIT_*`가 `NOT_APPLIED`로 바뀐 것도 백엔드 interceptor 위치와 맞다. +- **새 발견 1건, Low·P3 개선 제안(01-01).** 수정이 만든 실패 `FILE_REJECTED`에는 서버 기록과 이을 값이 없다. 성공 Envelope의 `meta.traceId`를 읽지 않고, 백엔드 답에는 거절 이유가 없다. +- **이 영역 수정이 검사를 약하게 만든 곳은 없다.** 테스트 diff는 추가 20건과 기대값 재정의 1행(503 `IDEMPOTENCY_UNAVAILABLE`, 더 보수적인 쪽)이다. 코드에서 손 목록 `MAYBE_APPLIED_CODES`를 V3 판정으로 바꿨지만, 전에 `MAYBE_APPLIED`였던 code는 모두 그대로다(2.2절). +- **오래된 이월 4건(1101/01-03, 0929/01-03, 0929/01-04, 0929/01-05)과 FOLLOW-UP은 남음이다.** `src/adapters/browser-transfer/`와 포트는 `8a44226..bbde570`에서 한 줄도 바뀌지 않았다. README §16.6에는 이 영역 이월이 없다. +- 실행: 내가 직접 돌린 것은 없다. 증거는 `bbde570` CI env 게이트 로그와 snapshot, 그리고 오케스트레이터가 돌린 배치 4건(01-R1~R4)이다. 넷 모두 rc=1이고, 실패한 테스트와 이유가 요청한 기대와 같다. 넷 모두 `restore=clean`이다. + +## 1. 범위 (36.1) + +| 항목 | 기록 | +| --- | --- | +| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`. `src/adapters/browser-transfer/` 27파일 12,919줄, 포트 `src/application/ports/browser-transfer/` 5파일 821줄(둘 다 `8a44226`과 같다). client `src/adapters/http/fileserver-upload.ts` 802줄(지난 735줄), 통합 테스트 `tests/integration/fileserver-upload.test.ts` 752줄(지난 557줄) | +| 커밋·작업 상태·확인 시점 | `bbde570`. 노트북 worktree에서 읽기만 했다. `8a44226..bbde570`의 이 영역 커밋: `6608fef`(1105/01-01, 1103/01-01), `471b001`(1105/01-02), `8b92f45`(1105/01-03), `f2f7dc4`(1105/01-04). 합친 뒤 영향: `c6c37f3`(1105/03-02)가 V3 표에 503 `RATE_LIMIT_*`를 더해 client 판정에도 들어왔다. browser-transfer 어댑터·포트·단위 테스트·브라우저 spec 변경 0 | +| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. file-transfer 레시피는 `productionComposition: false`. Fileserver client는 http adapter 배럴 export이고 제품이 capability로 넘긴다(`docs/manual/02-decision-tables.md:338-395`) | +| 필수 요구와 규모·운영 목표 | 사용자 목표: 짝 백엔드 템플릿과 함께 서비스를 빨리 출시한다. 업로드 크기·실패율 목표는 없다. 백엔드 기본 상한과 프론트 기본 정책값을 사실상의 목표로 보았다(지난 라운드와 같다) | +| 읽은 코드·구성 범위 | 전부: `fileserver-upload.ts`, 그 통합 테스트, `git diff 8a44226..bbde570`의 client·테스트·매뉴얼·계약 문서 diff, 커밋 본문 4개. 필요한 부분: `backend-envelope.ts:97-390`, `src/contracts/errors.ts:176-216`, `src/adapters/platform/abortable-operation.ts:90-160`, `config/contracts/backend-contract-pin.json`, `config/contracts/backend-idempotency-answers.json`, `scripts/check-backend-contract-drift.ts`(Fileserver 언급 0), 매뉴얼 `:278-410`, 계약 문서 `:325`, `:360-375`, CHANGELOG `:63`, `:89-103`. 이월 항목 자리(`runtime-policy.ts`, `resumable-upload-runtime.ts:239-246`, `:1045-1049`, `fetch-json-transport.ts:155-168`, `scripts/check-adapter-inventory.ts:135-146`, 포트 `resumable-upload.ts:101-133`). **짝 백엔드**(`45d2a478`, `git show`): `FileUploadController.java:185`, `:196`, `UploadedFileResponse.java:11-29`, `FileView.java`, `FileDescriptor.java`, `FileRecord.java:21-77`, `FileRecordMutation.java:9-40`, `:97-105`, `FinalizeUploadApplicationUseCase.java:129-344`, `:383-423`, 검증기 넷(`LengthVerifier.java:30-37`, `Sha256Verifier`, `FilenamePolicyVerifier`, `MediaTypeVerifier`), `FileserverVerificationConfiguration.java:44-57`, `BlockingTransferExecutor.java` 전체, `FileserverErrorCode.java:45-56`, `UploadFileApplicationUseCase.java:27-79`, `AtomicMoveContentPublisher.java:45-120`, `EnvelopeBodyAdvice.java:88`, `RateLimitWebConfig.java:61-62`, `docs/fileserver/http-contract.md:1-30`, `docs/manual/`(Fileserver 언급 검색) | +| 읽은 문서(주장) | 지난 영역 문서 전체, README §15·§16, 커밋 본문 4개, CHANGELOG 알려진 제한(`:89-103`) | +| 수행한 테스트·실험 | **실행 환경 = desktop 로그와 snapshot + 배치 요청.** 내가 돌린 것은 없다. 쓴 증거(모두 `bbde570`, CI env, 2026-11-06 03:24~03:56): `desktop:/tmp/claude-gates/bbde570-ci/gate-artifacts/FE-GATE-007.txt:9`(`fileserver-upload.test.ts` 68건 통과), `FE-GATE-005.txt`(이 영역 단위 15파일 통과, `:93`~`:290`), `FE-GATE-010` architecture PASS, `FE-GATE-012.txt:88`(file-transfer 레시피 56,130/57,800 gzip B), `FE-GATE-020` removability PASS, junit `r5/snap/merge/artifacts/tests/integration.xml`(03:48, fileserver 68건·실패 0·skip 0). 배치 4건(오케스트레이터, local env, 2026-11-06 04:23, `desktop:/tmp/claude-gates/r5/batch/out/R5-01-R1.log`~`R4.log`): 변이 하나씩, `node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts`, 끝마다 checkout 복원(6절) | +| 실험 조건 | 게이트는 node vitest + MSW다. 출하 client를 그대로 만들고 백엔드 응답은 흉내 냈다. 실제 백엔드·브라우저·네트워크는 쓰지 않았다 | +| 확인하지 못한 범위·이유 | 짝 백엔드를 띄운 업로드(백엔드는 읽기만). 배포 구성에서 성공 본문이 Envelope로 감싸지는지(정적 확인만). `TRANSFER_TIMEOUT` 뒤 늦게 `READY`가 되는 경쟁(재현 안 함). 실제 브라우저에서 Fileserver client(spec 없음). resumable 경로의 실패 뒤 재개·두 탭 경쟁을 브라우저에서(spec은 정상 경로뿐) | +| 이전 리뷰와 비교 가능한 범위 | 지난 라운드의 XA~XF, 변이 14건, 330건 실행은 증거로 쓰지 않았다. README §16.1의 "133개 항목 기대와 일치"도 주장으로만 읽었다. 01-R1·R3·R4는 지난 FS4·FS5·FS8과 같은 자리다. FS4는 `TRANSFER_TIMEOUT`이 목록에서 빠져 `ATOMIC_PUBLISH_UNSUPPORTED`만 뺀다(FS4'). 되넣는 쪽은 01-R2(FS4r)다 | + +## 2. 지난 발견 재확인 + +센 대상은 ID가 있는 발견 9건이다: 1105/01-01~01-04(README §15), 1103/01-01(§16.5), 지난 영역 문서 2절의 남음 4건(§16.6에는 없다). 결과: **고쳐짐 3 · 일부 2 · 남음 4 · 재발 0 · 틀린 발견 0.** FOLLOW-UP과 함께 볼 것은 따로 적었다. 지난 라운드에 고쳐진 5건은 재발 여부만 보았다. + +| 지난 ID | 내용 | 상태 | 근거 | +| --- | --- | --- | --- | +| 1105/01-01 (Medium·P2) | 202 `REJECTED`를 `SCHEMA_MISMATCH`로 읽고, 매뉴얼은 202를 "검사 중"으로 적는다 | **고쳐짐** | 완료 기준 셋을 확인했다. ① schema가 `REJECTED`를 받고(`fileserver-upload.ts:236`) 202 `REJECTED`는 `VALIDATION_REJECTED`·`FILE_REJECTED`·`NOT_APPLIED` 실패다(`:681-689`). 빈 파일은 보내지 않고 `FILE_EMPTY`·`NOT_STARTED`다(선언 0 `:475`, 읽은 뒤 0 `:535`). ② 테스트가 202 `VERIFYING`(`fileserver-upload.test.ts:198`), `QUARANTINED`(`:206`), `REJECTED`(`:215-238`)를 각각 본다. 201 `REJECTED`는 여전히 `SCHEMA_MISMATCH`(`:313`), 빈 파일 두 행(`:679-680`). FE-GATE-007과 junit에서 모두 통과했다. ③ 매뉴얼이 `QUARANTINED`의 뜻과 끝나지 않는 대기를 적는다(`02-decision-tables.md:315-319`, `:407`). 백엔드 대조는 2.1절. 실제 백엔드로 올려 보지 않았다(1103/01-01에 남김). 남은 진단 빈틈은 새 01-01 | +| 1105/01-02 (Medium·P2) | 504 `TRANSFER_TIMEOUT`을 `NOT_APPLIED`·5초 뒤 재시도로 주고, 효과 표가 V3 표·계약 문서와 갈라졌고 pin 밖이다 | **일부 · 백엔드로 넘김**(§16.4는 "고침 · 백엔드로 넘김") | **고친 것.** `TRANSFER_TIMEOUT`이 `NOT_APPLIED_5XX_CODES`에서 빠졌다(`fileserver-upload.ts:194-199`, 이유 `:188-192`). 5xx 기본값 `MAYBE_APPLIED`이고 `createFailure`가 `retryable:false`·`contact-support`로 만든다(`errors.ts:186-189`, `:209-214`). 멱등성 접두 code와 V3 표 행은 `envelopeFailureEffect`로 판정한다(`sharedAnswerEffect` `:207-221`, 호출 `:767`). 테스트: 표 행(`fileserver-upload.test.ts:385`), 전용 테스트(`:456-476`), pin 답 표 9행이 client와 V3가 같은지 본다(`:508-537`, junit 9건 통과). Fileserver 4xx를 `NOT_APPLIED`로 보는 이유는 계약 문서 6.1 한 곳에 있고(`backend-api-and-server-state-contract.md:360-375`), client 주석(`:184-186`)과 매뉴얼(`:409`)이 그곳을 가리킨다. SHA 표기는 pin으로 맞췄다(`:38-42`, `:117-121`, 매뉴얼 `:331`). 완료 기준 ①②는 맞다. ③ "FS4가 실패를 만든다"도 맞다: `TRANSFER_TIMEOUT`을 목록에 되넣은 01-R2에서 504 표 행(effect `NOT_APPLIED`, retryable `true`)과 전용 테스트(action `retry`)가 실패했다(`R5-01-R2.log`, 2건 실패·66건 통과). **남은 것.** (가) pin 밖: 지난 최소 개선 ④의 "pin 대조 대상에 `docs/fileserver/http-contract.md` 추가"를 커밋 `471b001`이 07-01로 미뤘다. 07-01(`daf3474`, `f600e6b`)은 web 계약 §2·§4만 옮겼다. `scripts/check-backend-contract-drift.ts`에 Fileserver 언급이 0이고, pin의 `frontend.readers`는 `backend-envelope.ts` 하나다(`backend-contract-pin.json:44`). 그래서 `NOT_APPLIED_5XX_CODES`(`:194-199`)와 202 state 해석은 사람이 읽은 표 그대로다. CHANGELOG도 이 부분을 "일부"로 적는다(`CHANGELOG.md:103`). (나) 백엔드 요청의 정확성: repo 안 문구는 목표로 적혀 정확하다("`ambiguous` 표시를 주거나 504가 'READY 없음'을 보장", `CHANGELOG.md:100`, README §16.4). 커밋 `471b001` 본문의 방법 (b) "작업 스레드가 게시 rename과 READY 커밋 전에 interrupt를 확인"은 그 보장을 주지 못한다. 대기 스레드는 작업 단계를 보지 않고 시간이 되면 `cancel(true)` 뒤 504를 낸다(백엔드 `BlockingTransferExecutor.java:72-79`). 작업 스레드가 확인을 지난 직후에 시간이 끝나면 504 뒤 `READY`가 그대로 생긴다. 보장하려면 대기 스레드가 "게시 단계에 들어갔다"는 표시를 보고 그때는 모호한 결과로 답하거나 끝까지 기다려야 한다. 이 본문의 재검토 조건("백엔드가 (b)를 고르면 이 줄을 되돌린다")을 글자대로 따르면 좁아진 창으로 원래 결함이 돌아온다. (다) 백엔드 몫: `ambiguous` 표시 또는 보장, `Idempotency-Key`(백엔드 `UploadFileApplicationUseCase.java:40` `NOT_IDEMPOTENT`) | +| 1105/01-03 (Low·P3) | 실패 Envelope의 `traceId`를 버린다 | **고쳐짐** | `envelopeFailure`가 Envelope 전체를 받아 `traceId`를 싣는다(`fileserver-upload.ts:701-708`, `:735-737`). 테스트: Envelope 실패 표 18행 모두 `traceId: "trace-1"`을 본다(`fileserver-upload.test.ts:403`). 없을 때는 키가 없다(`:409-420`). 매뉴얼 `:327`. 완료 기준("Envelope 실패 결과에 `traceId`가 있다")을 맞춘다. 성공 Envelope에서 만든 실패는 범위 밖이었다(새 01-01) | +| 1105/01-04 (Low·P3) | 5xx 두 code, 바이트 비례 deadline, 읽기 전 크기 거절을 테스트가 고정하지 않는다 | **고쳐짐** | 테스트 셋이 더해졌다: 503 `ATOMIC_PUBLISH_UNSUPPORTED` → `NOT_APPLIED` 행(`fileserver-upload.test.ts:376`), 가짜 `setTimeout`과 `monotonicNow: () => 0`으로 1.5초 뒤 답이 성공하고 credential deadline이 `1_000 + 18 × 1_000`인지 본다(`:580-625`), 선언 크기 초과에서 `stream()`이 불리지 않는다(`:693-705`). deadline은 전역 `setTimeout`을 부를 때 읽으므로 가짜 timer가 실제 경로를 탄다(`abortable-operation.ts:98-100`). 완료 기준("FS4·FS5·FS8이 각각 한 건 이상 실패를 만든다")을 배치로 확인했다. FS4'(01-R1)는 503 `ATOMIC_PUBLISH_UNSUPPORTED` 행이 effect `MAYBE_APPLIED`를 받아 실패했다. FS5(01-R3)는 deadline 테스트가 `{ ok: true }` 대신 `REQUEST_TIMEOUT`·`TIMEOUT`을 받아 실패했다. FS8(01-R4)은 "without reading a byte"가 code `FILE_NOT_READABLE`을 받아 실패했다. 각각 1건 실패·67건 통과이고 다른 테스트는 흔들리지 않았다(6절). FS8의 표 행 "a declared size above maxFileBytes"는 읽는 중 상한 검사로 여전히 통과한다. 그래서 새 전용 테스트가 이 규칙을 지키는 유일한 테스트다 | +| 1103/01-01 (High·P1) | 두 템플릿을 짝으로 쓰면 파일 업로드가 연결되지 않는다 | **일부 · 백엔드로 넘김**(§16.5와 같다) | 프론트 몫: client와 문서 넷은 지난 라운드 그대로다. 이번에 202 state 해석이 백엔드 코드와 맞게 됐다(1105/01-01). MSW 설명도 문서가 아니라 백엔드 코드 기준이다(`fileserver-upload.test.ts:17-35`). 완료 기준의 "두 매뉴얼" 중 백엔드 쪽이 없다: 백엔드 `docs/manual/`의 Fileserver 언급은 모듈 목록 한 칸뿐이다(`45d2a478:docs/manual/03-placement.md:30`). 백엔드 계약은 여전히 `202 VERIFYING`만 적는다(`45d2a478:docs/fileserver/http-contract.md:10`). 넘긴 요청(`CHANGELOG.md:101`, README §16.5)은 이 두 파일을 정확히 가리킨다. 덧붙이면 좋은 것: 추가할 state(`QUARANTINED`·`REJECTED`), 같은 문제가 있는 `POST /v1/files:raw` 행(`:11` "`201`, `202`"), 202 `REJECTED`에 이유가 없다는 점(새 01-01). 검증 방법 2단계(짝 백엔드를 띄운 업로드)는 하지 않았다 | +| 1101/01-03 (Low·P3) | 메모리 상한 식의 copyFactor가 설정값이다 | 남음 | `runtime-policy.ts:12`, `:68`, `:101-107`. 바뀌지 않았다 | +| 0929/01-03 (Low·P3) | 느린 업링크 기본값이 runtime 정책과 실행기에 따로 있다 | 남음 | `resumable-upload-runtime.ts:1045-1049`, `presigned-transfer-executor.ts:141-142`. client도 같은 값을 글자로 복사한다(`fileserver-upload.ts:164-165`) | +| 0929/01-04 (Low·P3) | file-transfer 어댑터만 지우면 게이트가 실패한다 | 남음(정적) | `scripts/check-adapter-inventory.ts:139-144`가 이 영역 4파일을 이름으로 고정한다. 바뀌지 않았다 | +| 0929/01-05 (Low·P3) | `abort()` 실패 recovery에는 행동 표가 없다 | 남음 | 표는 `upload()`에만 있다(`src/application/ports/browser-transfer/resumable-upload.ts:105-127`). 닫힌 runtime의 `abort()`는 `RESUME`이다(`resumable-upload-runtime.ts:241-245`) | +| FOLLOW-UP: `maxPartCount` 바이트 검사가 transport에 넘길 때만 | — | 남음 | `fetch-json-transport.ts:157-167` | +| FOLLOW-UP: 업로드 PUT에 idle 제한 없음 | — | 남음(문서화된 선택) | 바뀌지 않았다 | +| FOLLOW-UP: probe 재사용 테스트가 공개 이미지만 씀 | — | 남음 | `tests/unit/image-cdn-runtime.test.ts:196`, `:311`, `:383`이 `publicAsset()` | +| 1103/01-02 함께 볼 것: object store CORS의 `Retry-After` expose가 handoff 문서에 없다 | — | 남음 | `server-file-capability-infrastructure.md:1666-1673`은 receipt 헤더만 적는다 | +| 1103 D3: `issuePartCapability` 포트 주석 한 줄 | — | 안 함(결정 권고, 발견 아님) | `resumable-upload.ts:212-217`에 없다 | +| 재발 확인: 1103/01-02, 1103/01-03, 1101/01-02, 0929/01-02, spec `PAGE_ORIGIN` | 지난 라운드 고쳐짐 | 고쳐짐 유지 | 코드·테스트 diff 0. 관련 테스트(`resumable-upload-runtime-recovery.test.ts` 46건, `resumable-upload-fetch-transport.test.ts` 34건)가 FE-GATE-005에서 통과했다(`FE-GATE-005.txt:117`, `:164`). 지난 변이 재실행은 하지 않았다. `PAGE_ORIGIN`은 설정에서 읽는다(`tests/browser-capabilities/resumable-upload.spec.ts:8-10`) | + +### 2.1 1105 수정을 짝 백엔드 `45d2a478` 코드와 대조 + +| 항목 | 짝 백엔드(코드) | 프론트 client(`bbde570`) | 판정 | +| --- | --- | --- | --- | +| 202 `REJECTED` 본문 | 업로드는 동기 검증이다(`FileUploadController.java:185`). `READY`가 아니면 202(`:196`). 검증 전에 `uploaded(committedOffset, serverDigest)`로 크기·digest를 적는다(`FinalizeUploadApplicationUseCase.java:258`). 거절 전이는 `failure(verdict.code())`라 code만 쓴다(`:322`). mutation은 "적힌 칸만 쓴다"(`FileRecordMutation.java:12`). 본문은 `size=actualSize`, `sha256`, `etag="\"\""`, 확인 전 `mediaType=application/octet-stream`(`FileRecord.java:66-77`, `UploadedFileResponse.java:20-29`) | schema가 64자리 hex `sha256`, 1자 이상 `etag`, `size == 보낸 바이트`를 본 뒤 `REJECTED`를 실패로 바꾼다(`fileserver-upload.ts:233-244`, `:672-689`) | 맞다. 비어 있지 않은 거절(예: `LengthVerifier`의 `FILE_TOO_LARGE`, `Sha256Verifier`의 `DIGEST_MALFORMED`, 제품 검증기)이 `FILE_REJECTED`에 닿는다. `sha256`이 비면(`orElse("")`, `FileRecord.java:74`) schema가 막지만 이 경로에서는 늘 채워진다 | +| 빈 파일 | 기본 사슬 첫 검증기가 0바이트를 `REJECT("EMPTY_CONTENT")`(`LengthVerifier.java:35-36`, 사슬 `FileserverVerificationConfiguration.java:48-56`) | 보내기 전 `FILE_EMPTY`(`:474-475`, `:535`) | 맞다. 제품이 사슬을 바꿔 빈 파일을 받게 하면 client를 바꿔야 한다(커밋 `6608fef` 위험 칸. 끄는 설정은 없다) | +| 504 `TRANSFER_TIMEOUT` | 대기 스레드가 `await-seconds` 뒤 `cancel(true)`·504·retryable(`BlockingTransferExecutor.java:62-79`, `FileserverErrorCode.java:55`). READY 커밋 실패는 `AMBIGUOUS_COMPLETION`(`FinalizeUploadApplicationUseCase.java:411-420`) | `MAYBE_APPLIED`, `retryable:false`, `contact-support`. `retryAfterMs: 5000`은 실패에 남는다(`:731`, `errors.ts:198-200`) | 효과는 맞다. 남는 `retryAfterMs`는 매뉴얼이 "자동으로 다시 부르지 않는다"로 정리한다(`02-decision-tables.md:329`). 관점 23에 남김 | +| 남은 `NOT_APPLIED` 5xx 넷 | `PARTIAL_WRITE`(`:49`)는 길이 검사, `ATOMIC_PUBLISH_UNSUPPORTED`(`:53`)는 move 거절(`AtomicMoveContentPublisher.java:51-56`), 게시 뒤 실패는 `AmbiguousCompletionException`(`:89-95`, `:113-120`) | `:194-199` | 맞다(지난 라운드 대조와 같은 커밋) | +| 503 `RATE_LIMIT_*` | interceptor가 모든 경로에 걸리고(`RateLimitWebConfig.java:61-62`) `preHandle`에서 답한다 | V3 표 행이라 `NOT_APPLIED`(`sharedAnswerEffect`, pin 답 표 행 `RATE_LIMIT_UNAVAILABLE`·`RATE_LIMIT_INCOMPATIBLE` 통과) | 맞다. 이 판정 변화는 `471b001`이 아니라 합친 뒤 `c6c37f3`(1105/03-02)에서 들어왔다. 매뉴얼 `:324`와 계약 문서 `:367-369`는 "V3 표에 있는 답"이라고만 적고, 예로 든 code에 이 둘은 없다 | +| 성공 Envelope `meta` | `Envelope.ok(body, ResponseMetaFactory.fromMdc())`(`EnvelopeBodyAdvice.java:88`). `traceId`는 성공·실패 공통(`docs/web/http-contract.md:53`) | `readSuccessEnvelope`가 `data`·`page`만 돌려준다(`backend-envelope.ts:97-117`) | `FILE_REJECTED`에 `traceId`가 없다(새 01-01) | + +### 2.2 수정이 검사를 약하게 만들었는가 + +`git diff 8a44226..bbde570 -- src/adapters/http/fileserver-upload.ts tests/integration/fileserver-upload.test.ts`를 읽었다. + +- 테스트는 +201/−6이다. 지운 6줄은 머리 주석 5줄과 표 1행이다. 지운 단언, 넓힌 허용 목록·정규식, 새 skip, 늘린 시간 제한은 없다. 새 deadline 테스트는 가짜 timer를 쓴다. 실제 시간에 기대는 테스트를 대신한 것이 아니라 더한 것이다(기존 시간 초과 테스트는 그대로다). +- 바뀐 기대값 1행: 503 `IDEMPOTENCY_UNAVAILABLE`이 `NOT_APPLIED`·`retryable:true`에서 `MAYBE_APPLIED`·`retryable:false`로 바뀌었다(`fileserver-upload.test.ts:379`). 지난 01-02 개선 ②(V3 판정을 그대로 쓴다)와 매뉴얼 4절에 맞춘 재정의다. 더 보수적인 쪽이다. 약화가 아니다. +- 코드: 손 목록 `MAYBE_APPLIED_CODES`(넷)를 `AMBIGUOUS_COMPLETION` 비교 하나와 `sharedAnswerEffect`로 바꿨다(`fileserver-upload.ts:207-221`, `:766-767`). 전에 status와 상관없이 `MAYBE_APPLIED`였던 `IDEMPOTENT_IN_FLIGHT`·`IDEMPOTENCY_COMPLETION_UNKNOWN`·`IDEMPOTENCY_RECOVERY_REQUIRED`는 지금도 어떤 status에서나 `MAYBE_APPLIED`다. 표의 status와 맞으면 V3 표가, 아니면 400·409·422 규칙이나 `?? "MAYBE_APPLIED"`(`:220`)가 그렇게 준다. `NOT_APPLIED`로 바뀐 것은 503 `RATE_LIMIT_*` 둘이고 근거는 2.1절이다. +- pin 답 표 테스트(`:508-537`)는 client 결과를 client가 부르는 같은 함수(`envelopeFailureEffect`)와 비교한다. 그래서 V3 표 자체의 옳음은 보지 않는다. 그것은 `tests/unit/backend-contract-pin.test.ts`가 본다(영역 07). 이 테스트가 보는 것은 행마다 client가 V3 판정을 쓰는가이다. 그 목적에는 맞다. +- `?? "MAYBE_APPLIED"` 기본값(`:220`)을 지나는 테스트 행은 없다. pin 표의 9행은 모두 V3 표가 판정한다. 판정을 바꾸지 않는 안전 기본값이라 발견으로 세지 않았다(관점 10에 남김). + +## 3. 이번 발견 (36.3) + +새 발견 1건: Low 1 / P3 1 / 개선 제안 1. High 이상 0, P1 0. + +### 01-01 202 `REJECTED` 실패(`FILE_REJECTED`)에 서버 기록과 이을 값이 없다 — 성공 Envelope의 `meta.traceId`를 읽지 않고, 백엔드 답에는 거절 이유가 없다 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 개선 제안(적힌 계약 위반은 없다. 1103/03-06·1105/01-03 규칙은 실패 Envelope만 말한다). 1105/01-01 수정이 새 실패 종류를 만들면서 생겼다 | +| 관련 관점 | 8, 7, 23, 17, 26 | +| 근거 | **프론트.** 202 `REJECTED`는 `failure("VALIDATION_REJECTED", "FILE_REJECTED", { httpStatus, effect })`로 끝난다(`src/adapters/http/fileserver-upload.ts:681-689`). `failure()`에는 `traceId`가 없다(`:787-800`). `readSuccessEnvelope`는 `data`와 `page`만 돌려주고 `meta.traceId`를 버린다(`src/adapters/http/backend-envelope.ts:97-117`). 같은 client의 Envelope 실패는 싣는다(`fileserver-upload.ts:737`). `fileId`는 1105/01-01 권고대로 싣지 않는다. 테스트는 `traceId`를 보지 않는다(`tests/integration/fileserver-upload.test.ts:215-238`, MSW는 `meta.traceId: "trace-1"`을 보낸다 `:40`, `:89`). 커밋 `8b92f45` 본문이 이 한계를 "V3도 같다"며 적었다. 매뉴얼은 실패 Envelope만 말한다(`docs/manual/02-decision-tables.md:327`). **백엔드.** 성공 Envelope `meta`에도 `traceId`가 있다(`45d2a478:EnvelopeBodyAdvice.java:88`, `docs/web/http-contract.md:53`). 거절 이유는 레코드의 `lastErrorCode`에만 쓰고(`FinalizeUploadApplicationUseCase.java:322`) 응답 7필드에는 없다(`UploadedFileResponse.java:11-29`) | +| 발생 조건 | 빈 파일은 이제 보내기 전에 막힌다. 남은 경우: 제품 검증기가 악성 아닌 이유로 REJECT, servlet 상한을 Fileserver 상한보다 크게 둔 배포의 `FILE_TOO_LARGE`, `DIGEST_MALFORMED` | +| 영향 | 사용자는 "파일이 거절됐다"만 본다. 이유별 문구를 고를 수 없다. 지원 담당은 그 실패를 서버 로그나 `REJECTED` 레코드와 잇지 못한다. 동작·데이터 피해는 없다 | +| 심각도·우선순위 | Low · P3 — 진단 편의. 1105/01-03(Low·P3)과 같은 급이다 | +| 통제·증거 | 이 경로의 trace 전달: M0(경로를 확인했고 싣는 코드가 없다) · E1(두 repo 코드) | +| 확실성과 남은 가정 | 코드로 확정했다. 실제 배포 응답에 `meta.traceId`가 들어 있는지는 백엔드 문서·코드로만 확인했다 | +| 결정의 근거 | [확인한 사실] V3 실행기에는 정상 성공 Envelope을 업무 실패로 바꾸는 경로가 없다. 성공 Envelope에서 나는 실패는 schema 불일치뿐이다. Fileserver client만 정상 답(202 `REJECTED`)을 실패로 바꾼다. [기록된 의도] `8b92f45` "Envelope 실패에만 싣는다". [리뷰어 추론] "V3도 같다"는 schema 불일치에는 맞지만 이 경우에는 맞지 않는다. 서버가 정상으로 답했고 trace 값이 손에 있다 | +| 이해 비용 | 지원 담당이 "왜 거절됐나"에 답하려면 업로드 시각·사용자로 서버 로그를 뒤져야 한다 | +| 최소 개선 방향 | ① `readSuccessEnvelope`가 `readFailureEnvelope`처럼 `traceId`를 함께 돌려주고, `FILE_REJECTED` 실패가 싣는다 ② 백엔드 요청 목록(`CHANGELOG.md:100-101` 줄)에 "202 `REJECTED` 응답에 검증 code를 싣거나 422로 답한다"를 더한다 | +| 대안 비교 | (가) ①만 — 프론트만으로 끝나고 지원 연결이 생긴다. (나) ①+② — 사용자 문구도 이유별로 고를 수 있다. (다) 현상 유지 + 매뉴얼에 "`FILE_REJECTED`는 서버 로그와 잇지 못한다"를 적는다. (나)를 권한다. 프론트 몫은 ①이다 | +| 단순화의 보존 조건 | 적용 제외 — 값을 더하는 변경이다 | +| 비용·부작용 | `readSuccessEnvelope` 반환에 선택 칸 하나, 테스트 단언 하나. V3 호출자는 새 칸을 무시해도 된다 | +| 재검토 조건 | 백엔드가 REJECT를 실패 Envelope로 답하게 바꾸면 ①은 01-03 경로가 덮는다 | +| 완료 기준 | 202 `REJECTED` 결과에 응답의 `traceId`가 있다. 테스트가 본다. 백엔드 요청 목록에 이유 code가 있다 | +| 검증 방법 | 통합 테스트 202 `REJECTED` 행에 `traceId` 단언 | +| 담당·기한·상태 | 미정 · 미정 · 신규(1105/01-01 수정이 만든 빈틈) | + +## 4. 28개 관점 판정 (36.2) + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 굵은 번호가 깊게 본 관점이다. 통제는 "목표 / 확인"이다. + +| 번호 | 관점 | 판정 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +| --- | --- | --- | --- | --- | --- | +| 1 | 코드 성숙도 | O | M3 / M3 | E2(FE-GATE-005·007) | checkpoint 상태 전이·CAS는 그대로다. client는 입력 검사, 바이트 상한, 빈 파일 거절, deadline 하나, 고정된 결과 객체를 갖는다(`fileserver-upload.ts:410-556`) | +| 2 | 구조적 성숙도 | O | M4 / M4 | E1, FE-GATE-010 PASS | client의 새 import는 같은 http adapter의 `backend-envelope.ts`뿐이다(`fileserver-upload.ts:17-26`). adapter 사이 새 예외 없음 | +| 3 | 변경 용이성 | O | M3 / M3 | E2 | 공통 code 판정이 V3 표 하나로 모였다. 백엔드가 공통 code를 더하면 V3 표 한 곳을 고치면 된다 | +| 4 | 인지 부하 | P | M2 / M2 | E1 | 나아졌다: 공통 code는 한 표다. 남은 것: Fileserver 판정은 client 표·계약 문서 6.1 설명·매뉴얼 세 곳을 함께 읽어야 한다. `maxRetryAfterMs`가 factory 셋에 있다 | +| **5** | 위험 가시성 | P | M2 / M2 | E1 | 504 근거, 빈 파일 가정, 멱등 키, pin 밖 상태가 client 주석·매뉴얼·CHANGELOG에 적혔다(`fileserver-upload.ts:177-192`, `02-decision-tables.md:319`, `:331-335`, `CHANGELOG.md:100-103`). 남은 것: 커밋 본문의 백엔드 방법 (b)가 보장을 주지 못한다(1105/01-02) | +| **6** | 실패 성숙도 | P | M3 / M3 | E2 | 202 `REJECTED`와 `TRANSFER_TIMEOUT`이 고쳐졌다. 남은 것: 헤더 없는 part 단계 429는 `retryable:true`, control plane은 `false`(지난 라운드와 같다). 504 뒤 늦은 `READY`는 백엔드 결정 | +| 7 | 운영 성숙도 | P | M2 / M2 | E1 | client에는 관측 지점이 없고 실패 값만 돌려준다. Envelope 실패는 `traceId`를 싣는다. `FILE_REJECTED`는 싣지 않는다(01-01) | +| 8 | 디버깅 가능성 | P | M2 / M2 | E2 | 1105/01-03 고쳐짐. 남은 것: `FILE_REJECTED`의 trace·이유(01-01), `abort()` recovery의 뜻(0929/01-05) | +| 9 | 유지보수 성숙도 | P | M2 / M2 | E1 | 갈라진 사본은 늘지 않았다. 같은 사본: `isAbortSignal` 둘, media type 정규식 셋, 업링크 기본값 셋(0929/01-03). 새로 같은 정규식 `/^IDEMPOTEN(?:T\|CY)_/` 두 벌(`fileserver-upload.ts:214`, `backend-envelope.ts:335`, 지금은 같다) | +| **10** | 테스트 성숙도 | P | M3 / M3 | E2(68건, 변이 4/4 검출) | 202 state 셋, 빈 파일, 504, `traceId`, pin 답 표 9행, deadline, 읽기 전 거절을 본다. 변이 FS4'·FS4r·FS5·FS8이 모두 기대한 테스트에서 실패했다(01-R1~R4). 지난 라운드의 생존 셋(FS4·FS5·FS8)이 이번에 모두 잡혔다. 남은 것: `?? "MAYBE_APPLIED"` 기본값을 지나는 행 없음. MSW는 백엔드 코드에서 읽었지만 실제 백엔드가 아니다. client의 브라우저 실행 없음 | +| 11 | 데이터 성숙도 | O | M3 / M3 | E2 | 바뀌지 않았다. 계정 partition, checkpoint allowlist, 재조정 resourceId 유지 | +| 12 | 동시성 성숙도 | P | M3 / M3(탭 하나) | E2 | 바뀌지 않았다. 두 탭 같은 uploadKey 경쟁은 단위 테스트(메모리 lock)뿐이다 | +| 13 | 확장성 | P | M2 / M2 | E1 | 바뀌지 않았다. 발급 요청 `2N+4`, `maxPartCount` 검사는 transport에 넘길 때만. client는 요청 하나에 파일 전체 | +| 14 | 성능 성숙도 | P | M3 / M2 | E2 | copyFactor 설정값(1101/01-03). client는 크기 선언이 없으면 파일의 약 2배를 쓴다(문서화). file-transfer 레시피 56,130/57,800 gzip B(`FE-GATE-012.txt:88`, 지난 라운드 미검증이 닫힘) | +| 15 | 보안 성숙도 | O | M4 / M3 | E2 | 전송 규칙(`credentials`, 증명 헤더 허용, `redirect:"error"`, `no-referrer`, `no-store`, 응답 상한, 이름 escape)은 바뀌지 않았고 테스트가 통과했다 | +| 16 | 의존성 성숙도 | O | M2 / M2 | E1 | 새 패키지 없음. 테스트가 `zod`를 직접 import한다(`fileserver-upload.test.ts:7`). lint 통과 | +| **17** | API / Contract 성숙도 | P | M3 / M2~M3 | E1, E2 | 공통 code는 pin 답 표로 M3이 됐다. 남은 것: Fileserver code 표·202 state 해석은 pin 대조 밖 M2(1105/01-02), 백엔드 계약 문서는 202 `VERIFYING`만 적는다(1103/01-01, 백엔드 몫), `abort()` 표 없음(0929/01-05) | +| 18 | 배포 성숙도 | O | M3 / M3 | E2 | 바뀌지 않았다 | +| 19 | 설정 성숙도 | P | M2 / M2 | E1 | 남은 것: 업링크 기본값 세 곳, copyFactor. 빈 파일 거절은 백엔드 기본 사슬을 가정하고 끄는 설정이 없다(문서화) | +| 20 | 개발자 경험 | P | M2 / M2 | E1 | 매뉴얼 7절이 202 state 셋, `FILE_EMPTY`, 504, 공통 code, `traceId`를 적는다(`02-decision-tables.md:313-335`). 남은 것: 백엔드 매뉴얼 안내 없음, tus client 없음 | +| **21** | Guardrail 성숙도 | P | M3 / M2~M3 | E2 | pin 답 표 행마다 client와 V3를 대조한다(M3). 남은 것: Fileserver 계약은 drift 검사 밖(`check-backend-contract-drift.ts` Fileserver 0, pin `readers` 하나), 게이트가 이 영역 파일 이름을 고정(0929/01-04) | +| 22 | 추상화 성숙도 | O | M3 / M3 | E1 | client는 의존성을 받는 factory다. 새 포트 없음. FE-GATE-020 PASS | +| **23** | 일관성 | P | M2 / M2 | E1, E2 | 공통 code는 client와 V3가 같다. 남은 것: 헤더 없는 429(part `true` / control plane `false`), 닫힌 runtime의 `upload()` `NONE` / `abort()` `RESUME`, `TRANSFER_TIMEOUT` 실패에 `retryable:false`와 `retryAfterMs:5000`이 함께 남음(409 `IDEMPOTENT_IN_FLIGHT`에서는 같은 칸이 "같은 키로 기다렸다 다시"의 뜻이다. 매뉴얼 `:329`가 구분한다), `traceId`가 Envelope 실패에만(01-01) | +| 24 | 네이밍 / 의미 성숙도 | P | M2 / M2 | E1 | `REJECTED`가 이제 `FILE_REJECTED`로 나온다. 남은 것: 같은 이름 `maxRetryAfterMs` 셋, `abort()`의 `RESUME` 뜻 | +| 25 | 조직 확장성 | - | - | - | 적용 제외: 팀 1인 | +| **26** | Ownership 성숙도 | P | M1 / M1 | E1 | 백엔드 요청이 CHANGELOG 알려진 제한 두 줄로 남았다(`CHANGELOG.md:100-101`). 남은 것: 백엔드 쪽 담당·기록 자리가 없다. Fileserver 계약 대조의 주인이 없다(pin은 web 계약만). 커밋 본문의 방법 (b)가 부정확하다 | +| 27 | 삭제 가능성 | P | M3 / 레시피 단위 M0 | E2(FE-GATE-020 PASS) | client는 browser-file-storage·file-transfer 레시피 제거 드릴 뒤에도 남는다. 어댑터만 지우면 게이트가 실패한다(0929/01-04) | +| **28** | 회복 가능성 | P | M3 / M3(주 경로) | E2 | 504 뒤 자동 재전송 권고가 없어졌다. 남은 것: 재개 없음(문서화), `MAYBE_APPLIED` 뒤 재전송은 백엔드가 키를 읽지 않아 중복 가능(문서화), 504 뒤 늦은 `READY`는 백엔드 결정 | + +충족 O 8 · 부분 충족 P 19 · 미충족 X 0 · 미검증 ? 0 · 적용 제외 1. 지난 라운드와 같은 분포다. 10은 변이 검출이 4/4가 됐지만, 실제 백엔드·브라우저 실행이 없어 P로 둔다. + +## 5. 미검증 + +| 범위 | 이유 | 확인 방법 | +| --- | --- | --- | +| 짝 백엔드를 띄운 업로드(201, 202 `QUARANTINED`·`REJECTED`, 413 두 code, 실패 Envelope, 성공 `meta.traceId`) | 백엔드는 읽기만 한다 | 백엔드 기본 구성 + 프론트 client로 파일 넷(정상, 이름·타입 불일치, 상한 초과, 제품 검증기 거절)을 올린다 | +| 배포 구성에서 Fileserver 성공 본문이 Envelope로 감싸지는지 | 정적 확인뿐(`EnvelopeBodyAdvice.java:88`) | 위 실행에서 응답 원문 | +| `TRANSFER_TIMEOUT` 뒤 작업이 늦게 `READY`가 되는 경쟁 | 재현 안 함 | 백엔드 `await-seconds`를 1초로, 검증기에 지연을 넣고 업로드 | +| client를 실제 브라우저에서(`Uint8Array` 본문, 비ASCII 파일 이름, CORS preflight) | spec 없음 | capability spec 하나 | +| resumable 경로의 실패 뒤 재개·두 탭 경쟁을 실제 브라우저에서 | 브라우저 spec은 정상 경로뿐 | 실패 주입 spec | + +## 6. 실행 기록 + +내가 직접 돌린 명령은 없다. 노트북에서는 읽기만 했다(`git show`, `git diff`, `git grep`, `git apply --check`). desktop에서는 `/tmp/claude-gates/` 아래 파일만 읽었다. 변이 실행은 오케스트레이터가 배치로 돌렸다(아래). + +쓴 게이트 출력(`bbde570`, CI env, 2026-11-06 03:24~03:56, `desktop:/tmp/claude-gates/bbde570-ci/`): + +| 출처 | 결과 | 쓰인 곳 | +| --- | --- | --- | +| `FE-GATE-007.log`, `gate-artifacts/FE-GATE-007.txt:9` | integration PASS. `tests/integration/fileserver-upload.test.ts` 68건 ✓ | 1105/01-01·01-02·01-03 고쳐진 동작 | +| `r5/snap/merge/artifacts/tests/integration.xml`(03:48) | fileserver 스위트 68건, 실패 0, skip 0. 새 테스트 이름(202 `QUARANTINED`·`REJECTED`, 201 `REJECTED`, `ATOMIC_PUBLISH_UNSUPPORTED`, `TRANSFER_TIMEOUT` 둘, `traceId` 없음, pin 답 표 9행, deadline, 빈 파일 둘, 읽기 전 거절) 모두 있다 | 2절 | +| `gate-artifacts/FE-GATE-005.txt` | unit PASS. 이 영역 단위 15파일 ✓(`:93`~`:290`) | 재발 확인 | +| `FE-GATE-010.log` | architecture PASS | 관점 2 | +| `gate-artifacts/FE-GATE-012.txt:88` | file-transfer 56,130/57,800 gzip B | 관점 14 | +| `FE-GATE-020.log` | removability PASS | 관점 22, 27 | + +배치 요청은 `scratchpad/r5/requests/01.md`에 있다. 패치는 `requests/01-R1.patch`~`01-R4.patch`이고, 모두 `git apply --check`를 통과했다. + +- 실행: 오케스트레이터가 `bbde570`에서 한 항목씩 돌렸다. 2026-11-06 04:23, local env, 부하 2.66~2.88. +- 로그: `desktop:/tmp/claude-gates/r5/batch/out/R5-01-R1.log`~`R5-01-R4.log`(읽기만). 네 로그 모두 머리에 `head bbde570796b0…`, 끝에 `rc=1 restore=clean`이 있다. +- 명령: 넷 모두 `node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts`다. +- 변이 없는 실행은 따로 돌리지 않았다. FE-GATE-007(CI env, 68건 통과)로 대신한다. + +| ID | 변이 | 기대 | rc | 결과 | +| --- | --- | --- | --- | --- | +| 01-R1 | FS4': `NOT_APPLIED_5XX_CODES`에서 `ATOMIC_PUBLISH_UNSUPPORTED` 줄 삭제(`fileserver-upload.ts:196`) | 1건 실패: 503 `ATOMIC_PUBLISH_UNSUPPORTED` 행이 `MAYBE_APPLIED`를 받음 | 1 | **기대대로.** 1 failed · 67 passed. "503 'ATOMIC_PUBLISH_UNSUPPORTED' → 'SERVER_FAILURE', 'NOT_APPLIED', retryable false"에서 기대 `effect: "NOT_APPLIED"`, 받은 값 `"MAYBE_APPLIED"`(`fileserver-upload.test.ts:393`) | +| 01-R2 | FS4r: 같은 목록에 `TRANSFER_TIMEOUT` 되넣음 | 2건 실패: 504 표 행과 전용 테스트가 `NOT_APPLIED`를 받음 | 1 | **기대대로.** 2 failed · 66 passed. 표 행 "504 'TRANSFER_TIMEOUT' → …"에서 받은 값 `effect: "NOT_APPLIED"`, `retryable: true`(`:393`). 전용 테스트 "504 TRANSFER_TIMEOUT is an unknown result …"에서 받은 값 `action: "retry"`, `effect: "NOT_APPLIED"`, `retryable: true`(`:466`) | +| 01-R3 | FS5: deadline 식의 바이트 비례 몫에 0을 곱함(`:253-257`) | 1건 실패: deadline 테스트가 `REQUEST_TIMEOUT` 또는 `deadlineAtMonotonicMs` 1000을 받음 | 1 | **기대대로.** 1 failed · 67 passed. "adds the file's transfer allowance to the base deadline"이 `{ ok: true, value: … }` 대신 `{ ok: false, kind: "REQUEST_TIMEOUT", code: "TIMEOUT", effect: "MAYBE_APPLIED" }`를 받았다(`:615`). 첫 단언에서 멈춰 credential deadline 단언까지는 가지 않았다 | +| 01-R4 | FS8: `declared > maxFileBytes` 읽기 전 거절 블록 삭제(`:467-470`) | 1건 실패: "without reading a byte"가 `FILE_NOT_READABLE`·`stream` 호출을 받음 | 1 | **기대대로.** 1 failed · 67 passed. "refuses a declared size above maxFileBytes without reading a byte"에서 기대 code `FILE_TOO_LARGE`, 받은 값 `FILE_NOT_READABLE`(`:700`). 표 행 "a declared size above maxFileBytes"는 통과했다(요청의 예상대로) | + +변이마다 실패한 테스트는 요청이 이름 댄 것뿐이었고, 나머지 66~67건은 통과했다. 그래서 네 변이 모두 검사가 동작한다는 증거다(BRIEF 2.4 기준). + +## 7. 새 발견 요약 + +| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line | +| --- | --- | --- | --- | --- | +| 01-01 | Low·P3 | 개선 제안 | 202 `REJECTED` 실패(`FILE_REJECTED`)에 성공 Envelope의 `traceId`가 없고, 백엔드 답에는 거절 이유가 없어 서버 기록과 잇지 못한다 | `src/adapters/http/fileserver-upload.ts:681-689`, `:787-800`; `src/adapters/http/backend-envelope.ts:97-117`; 백엔드 `UploadedFileResponse.java:11-29` | diff --git a/docs/reviews/2026-11-06-maturity-review/02-adapters-browser-files-cache.md b/docs/reviews/2026-11-06-maturity-review/02-adapters-browser-files-cache.md new file mode 100644 index 00000000..7764ac01 --- /dev/null +++ b/docs/reviews/2026-11-06-maturity-review/02-adapters-browser-files-cache.md @@ -0,0 +1,177 @@ +# 영역 02 — adapters: browser-files · cache-storage · cross-context-invalidation + +> 검토일 2026-11-06 · 기준 `bbde570` · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 경로 `src/adapters/browser-files/`, `src/adapters/cache-storage/`, `src/adapters/cross-context-invalidation/`. 함께 본 것: 포트 `src/application/ports/browser-file-storage/cache-storage-ports.ts`, 레시피 `recipes/frontend-capabilities/browser-file-session-capability.ts`, 조립 `src/bootstrap/runtime-adapters.ts`·`product-composition-contract.ts`, scope `src/adapters/query-cache/server-state-scope-runtime.ts`, 진단 계약 `src/contracts/diagnostics.ts`·`scripts/check-diagnostics.ts` +> 깊게 본 관점 6, 8, 10, 11, 17, 18, 24, 28 +> 이번 라운드 렌즈: 1105 수정 4건과 이월 수정 2건이 완료 기준까지 갔는가. 수정이 검사를 약하게 하거나 새 결함을 만들었는가 +> 영역 판정(35.8): cross-context-invalidation **지정 범위에서 사용 가능** · cache-storage **조건부 사용 가능** · browser-files **조건부 사용 가능** · 이 영역 제거 드릴(FE-GATE-020) **통과**(0절) + +ID 표기: 이번 라운드 새 발견은 `02-01`부터 쓴다. 지난 라운드(2026-11-05) 발견은 `1105/02-01`, 그 전은 `1103/…`, `1101/…`, `0929/…`로 쓴다. + +실행 증거의 출처: 리뷰어는 laptop과 desktop 어디에서도 아무것도 돌리지 않았다(BRIEF 2절). 게이트 결과는 오케스트레이터의 CI env 실행(`desktop:/tmp/claude-gates/bbde570-ci/`, 2026-11-06 03:24~03:56)과 그 snapshot(`desktop:/tmp/claude-gates/r5/snap/merge/`)을 인용한다. 변이 8개와 실험 1개는 요청 `02-R1`~`02-R9`로 넘겼다. 오케스트레이터가 2026-11-06 04:32에 `bbde570`에서 하나씩 돌렸고, 항목마다 checkout을 깨끗하게 되돌렸다(로그 `desktop:/tmp/claude-gates/r5/batch/out/R5-02-R1.log`~`R5-02-R9.log`). 9개 모두 기대와 맞았다(6.2절). + +## 0. 결론 + +- **1105 새 발견 4건 중 3건은 고쳐졌고 1건은 일부다.** 02-01(`f738348`)·02-03(`d31c7d6`)·02-04(`56c0bd0`)는 완료 기준의 코드와 테스트가 있다. 그 테스트가 `bbde570`에서 통과한다(FE-GATE-005·007). 고친 규칙을 바꾼 변이 6개가 모두 그 테스트에서 기대한 이유로 실패했다(02-R2~R5, 02-R8, 02-R9). +- **1105/02-02는 일부다.** asset entry는 이제 같은 manifest stage가 다시 쓴다. 완료 기준 시나리오(E-1a·E-1c) 테스트가 통과한다(`tests/unit/public-response-cache-repair.test.ts:482-509`, `:634-654`). 그런데 같은 후보 cache의 **release marker** 본문이 계속 읽히지 않으면 여전히 돌아올 길이 없다. stage가 marker 읽기 실패에서 멈추기 때문이다(`src/adapters/cache-storage/public-response-cache-adapter.ts:463-468`). rollback 대상은 되돌릴 수 없고, 활성 release는 모든 asset 조회가 실패한다. 설계 문서와 포트 주석은 "rollback 대상과 서비스 중 release도 다시 stage로 돌아온다"고 넓게 적는다. 실험 02-R1 X1·X2가 확인했다. rollback 대상은 activate, 같은 manifest stage(fetch 0), cleanup(삭제 0), 다시 activate가 모두 `UNAVAILABLE`/`RETRY`이고 marker는 한 번도 다시 쓰이지 않는다. 활성 release는 두 asset 조회와 재stage가 모두 실패하고, 새 release를 배포해야 조회가 돌아온다. +- **02-04의 "`INTEGRITY_FAILED` 제거는 동등 변이" 주장은 맞다.** 판정을 쓰는 곳은 셋이다(stage `:482-507`, activation `:682-712`, inspect `:913-925`). `INTEGRITY_FAILED`가 목록 밖으로 가면 판정이 `UNREADABLE`이 된다. stage는 둘 다 다시 쓴다. activation은 둘 다 `{INTEGRITY_FAILED, CACHE_ACTIVATE, retryable:false, REHYDRATE}`를 준다. inspect는 둘 다 `verified:false`다. 다른 것은 바깥 결과 객체의 freeze 여부 하나다. 포트로는 보이지 않는다(2절). +- **02-01이 계약에 더한 진단 키 `scope_participant`는 맞게 들어갔다.** 분류는 `topology`이고 값 정책 `isScopeParticipantLabel`이 붙었다. `operation_id`와 같은 방식이다(`src/contracts/diagnostics.ts:77`, `:96`, `:114`, `:125`). 제품 label은 조립이 `TypeError`로 거르고(`src/bootstrap/runtime-adapters.ts:713-722`), runtime이 기록 전에 한 번 더 거른다(`server-state-scope-runtime.ts:308`). telemetry 허용 목록에는 없다. 그래서 진단 밖으로 나가지 않는다. `check:diagnostics`가 키마다 분류를 요구한다(`scripts/check-diagnostics.ts:54-58`). 남은 것은 작다. label이 겹쳐도 막지 않는다. 값 정책만 지우는 변이는 잡는 테스트가 없지만, 호출부가 먼저 거르므로 동작은 같다. +- **이월 5건:** 1101/02-04는 고쳐졌다(N38 변이가 새 테스트에서 실패한다, 02-R7). 0929/02-02는 일부다(M05 변이가 새 테스트에서 실패한다, 02-R6. `signal`과 판정 불가 칸은 결정 대기). 1101/02-02는 일부 그대로다(코드 변화 0줄, 결정 대기). 0929/02-06은 남음이다(결정 대기). 0929/02-03(CHANGELOG 0.2.0 행)은 남음이다. 이 항목은 README 16.6절 목록에서 빠졌다. +- **새 발견 1건(Low·P3):** 02-01. control cache의 active pointer 본문이 계속 읽히지 않으면 activation·cleanup·inspect·조회가 모두 멈춘다. adapter API 안에서는 돌아올 길이 없다. 0929/02-01은 손상 pointer(`CORRUPT_DATA`)만 풀었고, 1105/02-02는 asset entry만 풀었다. 수정이 만든 결함은 아니다. 이전 라운드가 보고하지 않았다. 실험 02-R1 X3이 확인했다. 새 release stage만 성공하고, 그 activate·cleanup·inspect·조회·현재 release activate는 모두 `UNAVAILABLE`/`RETRY`이며 pointer는 한 번도 다시 쓰이지 않는다. +- **검사를 약하게 한 수정은 찾지 못했다.** `git diff 8a44226..bbde570`에서 이 영역 테스트의 지운 단언은 1103/02-02 테스트의 "다시 stage는 fetch 0으로 실패" 하나다(`public-response-cache-repair.test.ts:180-242`). 1105/02-02가 바꾸기로 한 동작이다. 반대 방향 단언(fetch 2, 다음 activate 성공)으로 바뀌었다. 추가된 skip·only·timeout은 0건이다. 번들 예산은 그대로다(`config/recipes/frontend-capability-recipes.json:149`, `:198` 변경 없음). + +| ID | 심각도·우선순위 | 한 줄 | +| --- | --- | --- | +| 02-01 | Low · P3 | active pointer 본문이 계속 읽히지 않으면 Cache Storage 관리가 모두 멈추고 API 안에서 돌아올 길이 없다 | + +**영역 판정 (35.8)** + +- cross-context-invalidation(기본 조립): **지정 범위에서 사용 가능.** `8a44226` 뒤 소스 변경이 없다(`git diff --stat` 0줄). 세 라운드 살아남은 N38(host `storageArea` 비교)에 테스트가 생겼다(`tests/unit/cross-tab-invalidation.test.ts:392`). 실제 BroadcastChannel·localStorage 경로가 3엔진에서 통과한다(snapshot `browser-capabilities/results.xml`, `cross-context-invalidation.spec.ts` 2건 × 3, 실패 0). +- cache-storage(service-worker-pwa 레시피, 미조립): **조건부 사용 가능.** 지난 조건 하나가 풀렸다. 계속 읽히지 않는 asset entry는 이제 같은 manifest stage 한 번으로 돌아온다. 남은 조건은 둘이다. 정적 release 조합에만 쓴다. release marker나 active pointer의 본문이 계속 `UNAVAILABLE`/`NOT_READABLE`이면 그 cache(marker면 그 release cache, pointer면 control cache)를 지우고 다시 배포하는 절차를 제품이 정한다(1105/02-02 남은 부분, 02-01). +- browser-files(file-transfer 레시피, 미조립): **조건부 사용 가능.** 지난 조건 "제품 closer는 던지지 않게 쓴다"가 풀렸다. 던지면 이제 그 label로 진단이 남는다. 새 조건은 label을 소문자 kebab-case 토큰으로 쓰는 것이다(어기면 부팅에서 `TypeError`, 문서에 있음). 남은 조건은 download 정책의 media type과 확장자 짝을 제품이 직접 검토하는 것이다(`1101/02-02`). +- 템플릿 CI의 FE-GATE-020: **통과.** CI env 실행 rc=0, 1,237초(`bbde570-ci/summary.txt`). junit `browser-file-storage-runtime-removal.xml` 7/7(03:43), `optional-recipe-removal.xml` 6/6(03:41), 모두 `failures="0"`. 실제 Gitea 러너에서는 돌리지 않았다. + +## 1. 범위 (36.1) + +| 항목 | 기록 | +| --- | --- | +| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` 영역 02: `src/adapters/browser-files/` 10파일 4,840줄, `src/adapters/cache-storage/` 5파일 2,365줄, `src/adapters/cross-context-invalidation/` 3파일 1,062줄. 그리고 scope participant 경로(조립·scope runtime)와 그것이 더한 진단 계약 키 | +| 커밋·작업 상태·확인 시점 | `bbde570`(laptop worktree, HEAD = 기준, 브랜치 `docs/maturity-review-2026-11-06`). 2026-11-06. 지난 기준 `8a44226` 뒤 이 영역을 바꾼 커밋: `f738348`(1105/02-01), `8e9fb1f`(1105/02-02), `d31c7d6`(1105/02-03), `56c0bd0`(1105/02-04), `11a0fd0`(1101/02-04), `f2a4f32`(0929/02-02). `src/adapters/browser-files/`·`cross-context-invalidation/`의 소스 변경은 0줄이다 | +| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker, SSR 없음. cross-context는 기본 조립이다. cache-storage는 service-worker-pwa, browser-files는 file-transfer 레시피의 `AVAILABLE_NOT_COMPOSED` runtime이다. 공개 경계는 배럴 세 개다 | +| 필수 요구와 규모·운영 목표 | 규모·운영 목표는 없다. 코드의 상한 값을 사실상의 목표로 본다(지난 라운드와 같다) | +| 읽은 코드·구성 범위 | 이 영역의 `8a44226..bbde570` 차이 전체. cache adapter의 조회·stage·activation·cleanup·inspect·`verifyReleaseCandidate`·`readMarker`·`readActivePointer` 전체, `public-cache-response-validation.ts`·`public-cache-codec.ts`의 실패 변환, `browser-file-storage/result.ts:17-96`. `server-state-scope-runtime.ts` 전체, `runtime-adapters.ts:430-460`·`:700-740`, `diagnostics.ts` 전체, `scripts/check-diagnostics.ts` 전체, 바뀐 테스트 5파일 | +| 읽은 설정·문서(주장) | `docs/architecture/browser-file-and-origin-storage.md:370-384`·`:450-457`·`:966-985`·`:996-1017`, `docs/manual/03-outside-feature-folder.md:117-124`, 포트 주석 `cache-storage-ports.ts:42-74`, `CHANGELOG.md:29`·`:68`·`:418`, 각 수정 커밋 본문, 2026-11-05 README 15·16절과 영역 문서 | +| 수행한 테스트·실험 | ① 오케스트레이터 CI env 실행(`bbde570`): FE-GATE-001~012·020 rc=0, FE-GATE-013 rc=1(host user namespace, 이 영역과 무관). ② snapshot junit(03:24 뒤 파일만): `coverage.xml`·`unit.xml`·`optional-recipes.xml`·`browser-capabilities/results.xml`·제거 드릴 2개. ③ 배치 `02-R1`(실험 3건, rc=0, 3건 모두 예측과 같음), `02-R2`~`02-R9`(변이 8개, 모두 rc=1, 기대한 테스트에서 기대한 이유로 실패). 오케스트레이터 실행, local env, 2026-11-06 04:32 | +| 확인하지 못한 범위·이유 | 실제 브라우저에서 Cache Storage 본문 읽기 실패가 지속되는지. 레시피를 조립한 실제 화면. 실제 Gitea 러너. 02-01의 초기 JS +251 B(측정은 수정 세션 몫, 5절) | +| 이전 리뷰와 비교 가능한 범위 | 변이 F0202-cor·-pol·-lim·-notreadable, M05, N38은 지난 라운드와 같은 규칙을 같은 방식으로 바꾼다. 지난 라운드 실행 결과(02-R1, E-1~E-3)는 현재 증거로 쓰지 않았다 | + +## 2. 지난 발견 재확인 + +| 지난 ID | 내용 | 상태 | 근거 | +| --- | --- | --- | --- | +| `1105/02-01` | 제품 scope participant가 실패하면 scope가 진단 없이 `FAILED`로 멈추고 `label`은 쓰이지 않는다 | **고쳐짐** | 완료 기준 ① "던지는 제품 closer 뒤 그 `label`이 담긴 기록 하나": 실제 `createRuntimeAdapters`와 실제 진단 adapter로 `{operation:"SCOPE_RESET", reason:"PARTICIPANT_FAILED", error_kind:"ERROR", scope_participant:"broken-closer"}` 한 건을 `toEqual`로 고정한다. 재시도마다 한 건 더 남는 것도 본다(`tests/unit/runtime-adapters-product-scope-participants.test.ts:160-197`). ② "template participant 실패도 기록": 같은 기록 함수가 모든 participant에 쓰인다(`src/adapters/query-cache/server-state-scope-runtime.ts:176-183`, `:294-314`). template participant도 같은 목록에 있다(`runtime-adapters.ts:440-446`, `:453-461`). scope runtime 테스트가 participant 실패·cache reset 실패·세대 활성화 실패를 각각 고정한다(`server-state-scope-runtime.test.ts:132`, `:171`, `:239`). 두 파일이 `bbde570`에서 통과한다(FE-GATE-005 `:91`, `:126`). 형식 밖 label은 부팅에서 거절된다(`runtime-adapters.ts:713-722`, 테스트 `:199`). 문서: 설계 `browser-file-and-origin-storage.md:379-382`, 매뉴얼 `03-outside-feature-folder.md:122-123`, CHANGELOG 먼저 할 일 6단계(`CHANGELOG.md:29`)와 [계약] 행(`:68`). 진단 키 판단은 0절. 1103/02-01의 "하나가 실패해도 나머지를 부르고 READY로 가지 않는다"는 그대로다(`runtime-adapters-product-scope-participants.test.ts:137-158`). 남은 작은 것: label 중복을 막지 않는다(제품이 `conditional-validators`를 써도 통과). CHANGELOG [계약] 행에 BREAKING 표시가 없다(먼저 할 일에는 있다. 영역 14에 넘긴다). 변이 02-R9(진단에서 `scope_participant`를 지움)가 두 테스트에서 그 칸이 빠져 실패했다(`runtime-adapters-product-scope-participants.test.ts:183`, `server-state-scope-runtime.test.ts:166`) | +| `1105/02-02` | 계속 읽히지 않는 캐시 본문은 다시 stage해도 고쳐지지 않고 rollback 대상은 회복 길이 없다 | **일부** | 고쳐진 것: 판정 `UNREADABLE`이 생겼다. stage는 이것도 모든 asset을 다시 받아 덮어쓴다(`public-response-cache-adapter.ts:1099-1104`, `:1167-1170`, `:500-507`). activation은 code를 그대로 두고 recovery만 `REHYDRATE`로 준다(`:695-705`). 완료 기준 "E-1a·E-1c에서 같은 manifest stage가 후보를 고치고 다음 activate(rollback 포함)가 성공": 테스트가 있다(`public-response-cache-repair.test.ts:482-509` E-1a·E-1b, `:634-654` E-1c, `:656-686` E-1d). 25건 통과(FE-GATE-005 `:118`). **남은 것: release marker.** marker는 같은 후보 cache 안의 entry다. stage는 이미 있는 후보의 marker 읽기가 `CORRUPT_DATA` 밖의 실패면 바로 실패를 돌려준다(`:463-468`, STO-RR-04). 그래서 marker 본문이 계속 읽히지 않으면 다시 stage해도 marker를 다시 쓰지 않는다. activation도 marker 실패를 `RETRY`로 돌려준다(`:666-668`). 조회는 활성 release의 모든 asset에서 marker를 읽다 실패한다(`:286-297`). cleanup은 pointer가 가리키는 cache를 지우지 않는다(`:826-845`). 결과는 지난 E-1과 같은 모양이다. 새 후보는 cleanup 뒤 다시 stage해야 하고, rollback 대상은 되돌릴 수 없고, 활성 release는 새 release를 배포해야 돌아온다. STO-RR-04 주석이 막으려던 것은 삭제다(`:464-466`). 이미 있는 후보는 실패해도 지우지 않는다(`:585-587`). 그래서 1105/02-02의 "덮어쓰기는 삭제가 아니다" 논리가 marker에도 그대로 맞는데 적용하지 않았다. 문서가 범위를 넓게 적는다. 설계 문서는 "rollback 대상 release와 서비스 중인 release도 같다"고 적는다(`browser-file-and-origin-storage.md:979-982`). 포트 주석은 "a failed body read or lookup"을 "staging the same manifest again rewrites either"로 적는다(`cache-storage-ports.ts:66-69`). 그런데 `cache.match` 자체의 실패는 stage가 다시 쓰지 않는다(`:492-499`, 설계 문서 `:983-984`는 이것을 맞게 적는다). 실험 02-R1 X1(rollback 대상 marker)·X2(활성 release marker)가 이 경로를 그대로 보였다(6.2절). 심각도는 원래대로 Low·P3다 | +| `1105/02-03` | 세션 레시피 주석이 매뉴얼이 막는 보강 방식을 가리키고 capability 전달은 테스트 밖이다 | **고쳐짐** | 완료 기준 ① 주석이 매뉴얼과 같은 파일을 가리킨다: `recipes/frontend-capabilities/browser-file-session-capability.ts:21-33`이 `src/features/product-capabilities.ts`의 `ProductFeaturePlatformCapabilities`를 예로 들고 `declare module`을 쓰지 말라고 적는다. 매뉴얼 `03-outside-feature-folder.md:118-119`와 같다. ② 레시피 테스트가 capability를 기능까지 넘긴다: 조립이 `capabilities: { files }`를 돌려주고(`tests/recipes/browser-file-session-capability.test.ts:149`), 템플릿이 기능 loader에 넘긴 객체를 기록해(`:156-171`) 그 객체의 `files.current()`로 모든 동작을 돈다(`:230-239`, `:258-309`). FE-GATE-007 `:103` 통과. `needs`로 고르는 마지막 단계는 기존 테스트가 본다(`tests/contract/reusable-capability/feature-adapter-composition.test.ts:166`). 변이 02-R8(조립에서 `...product.capabilities`를 지움)이 `Features did not receive the files capability`로 실패했다(`:238`) | +| `1105/02-04` | 1103/02-02의 손상 code 목록 경계를 테스트가 고정하지 않는다 | **고쳐짐** | 표 테스트 6행이 생겼다(`public-response-cache-repair.test.ts:541-597`). 행마다 activate의 code와 `REHYDRATE`, 다음 stage의 fetch 2, 그 뒤 activate 성공을 본다. 정적 대조: `CORRUPT_DATA`를 빼면 `DataError` 행의 activate code가 `CORRUPT_DATA`가 된다. `POLICY_REJECTED`·`LIMIT_EXCEEDED`도 같다(`UNREADABLE`이 원래 code를 돌려준다, `:695-705`). `NOT_READABLE`을 더하면 그 행과 E-1b 행이 `INTEGRITY_FAILED`를 받는다. 완료 기준의 F0202-int는 이제 동등 변이다. 근거: `INTEGRITY_FAILED`는 `failureForCode`가 `{INTEGRITY_FAILED, retryable:false, REHYDRATE}`로 만든다(`public-cache-codec.ts:592-595`). 목록 밖이면 판정이 `UNREADABLE`이고 activation이 그것을 `CACHE_ACTIVATE`로 옮긴다(`:698-704`, `:1213-1221`). 목록 안이면 `browserDataFailure("INTEGRITY_FAILED","CACHE_ACTIVATE",{recovery:"REHYDRATE"})`다(`:706-711`, `result.ts:17-31`). 두 결과의 칸과 값이 같다. stage(`:489-507`)와 inspect(`:923`)는 두 판정을 같게 다룬다. 다른 것은 바깥 결과 객체의 freeze 여부뿐이다. 이 동등은 1105/02-02의 `UNREADABLE` 다시 쓰기에 기대고 있다. 그 동작이 바뀌면 표의 첫 행이 다시 이 경계를 잡는다. 변이 검출: 02-R2·R3·R4는 해당 행이 activate code `CORRUPT_DATA`·`POLICY_REJECTED`·`LIMIT_EXCEEDED`를 받아 실패했다(`:586`). 02-R5는 `NotReadableError` 두 행(E-1b와 표)이 `INTEGRITY_FAILED`를 받아 실패했다(`:502`, `:586`). 완료 기준의 다섯 변이 중 동등 변이 하나를 뺀 넷이 모두 검출된다 | +| `1101/02-04` | 보호 규칙 7개가 변이에서 살아남는다(남은 것 ② N38 host `storageArea` 비교) | **고쳐짐** | 테스트 "takes a storage pulse only from the localStorage object it captured"(`tests/unit/cross-tab-invalidation.test.ts:392-481`)가 BroadcastChannel 없는 host 둘로 storage pulse만 쓴다. sessionStorage 이벤트와 모양만 같은 다른 객체의 이벤트는 받지 않고, 캡처한 localStorage 이벤트는 한 번 받는다. 비교 코드는 그대로다(`src/adapters/cross-context-invalidation/browser-cross-context-host.ts:289-295`). N38(항상 `EXPECTED_LOCAL_STORAGE`)이면 sessionStorage 이벤트가 전달되어 `not.toHaveBeenCalled()`가 실패해야 한다. 19건 통과(FE-GATE-005 `:228`). 변이 02-R7이 이 테스트에서 실패했다. sessionStorage 이벤트와 모양만 같은 객체의 이벤트, 2건이 전달됐다(`:471`). 같은 파일의 core 단위 테스트 "rejects storage pulses from another or unknown storage area"는 변이에서도 통과했다. 그래서 N38을 잡는 것은 이 host 테스트 하나다. 나머지 ①·③~⑦은 지난 라운드에 검출됐고 이번 diff에서 그 코드가 바뀌지 않았다 | +| `0929/02-02` | `inspect()`의 비용·취소·판정 불가가 포트 계약에 없다 | **일부** | 고쳐진 것: 포트 주석이 비용(cache 수 × entry 수, cursor·deadline·signal 없음)과 `verified`의 뜻을 적는다(`cache-storage-ports.ts:55-70`). 테스트가 본문을 못 읽는 후보와 `cache.match`가 던지는 후보를 `verified:false`로 고정한다(`public-response-cache-repair.test.ts:599-632`). M05(판정 불가를 `verified:true`로)가 이 테스트에서 실패했다. r2·r3가 `true`로 나왔다(`:631`, 02-R6). 남은 것: `inspect()`에 signal이 없다(`cache-storage-ports.ts:107`, adapter가 `undefined`를 넘긴다 `:913-919`). 판정 불가와 손상은 여전히 같은 `false`다. README 16.6절도 이 둘을 결정 대기로 적는다. 포트 주석 한 문장이 다시 stage 범위를 넓게 적는 것은 1105/02-02 행에 적었다 | +| `1101/02-02` | download 정책 `safeExtension`이 금지 목록·media type을 보지 않는다 | **일부** (변화 없음, 결정 대기) | `src/adapters/browser-files/`의 변경이 0줄이다. 금지 확장자 거절은 그대로다(`browser-file-policy-registry.ts:448-456`). media type과 확장자 짝은 여전히 보지 않는다. 설계 문서가 한계로 적는다(`browser-file-and-origin-storage.md:453-457`). README 16.6절 "결정 대기"와 같다 | +| `0929/02-06` | cross-context kernel 예외가 쓰임보다 넓다 | **남음** (결정 대기) | 예외가 배럴 전체를 연다(`.dependency-cruiser.json:261`). adapter 쪽 사용은 여전히 query-cache의 `import type` 하나다(`src/adapters/query-cache/tanstack-cache-coordinator.ts:18-21`). repo `CLAUDE.md`가 이 예외를 kernel로 열거한다. 새 파일 단위 예외는 제안하지 않는다 | +| `0929/02-03` | CHANGELOG 0.2.0 browser-files [계약] 행의 경로·대상이 틀렸다 | **남음** | 행이 `CHANGELOG.md:418`로 옮겨졌을 뿐 내용이 같다. browser-files 포트의 영향 경로가 `src/adapters/browser-file-storage/`다. 실제 adapter는 `src/adapters/browser-files/`다. Cache Storage를 "browser-files recipe"로 적는다. 지난 영역 문서 2절은 이것을 "남음"으로 적었는데 README 16.6절 목록에는 없다(색인 누락) | + +지난 라운드에 고쳐짐으로 닫은 1103 발견 6건은 다시 열리지 않았다. +- 1103/02-01: 순서·나머지 호출·READY 막음 테스트가 그대로다(`runtime-adapters-product-scope-participants.test.ts:117-158`). 레시피 테스트가 통과한다(FE-GATE-007 `:103`). +- 1103/02-02: activation은 본문 읽기 실패를 손상으로 보고하지 않는다(`public-response-cache-adapter.ts:695-705`). 테스트가 code `UNAVAILABLE`을 본다(`public-response-cache-repair.test.ts:216-222`). 바뀐 것은 recovery(`RETRY` → `REHYDRATE`)와 stage 동작이다. 1105/02-02가 정한 변경이다. +- 1103/02-03: L6·L7 테스트가 그대로다(`public-response-cache-repair.test.ts:869`, `:891`). L1·L4·L5 쪽은 소스와 테스트 모두 바뀌지 않았다. +- 1103/02-04·02-05: 그 코드가 바뀌지 않았다(`browser-files/` 0줄, `public-response-cache-adapter.ts:928-940`). +- 1103/02-06: FE-GATE-020 rc=0(0절). + +## 3. 이번 발견 (36.3) + +새 발견 1건. 심각도 Low 1. 우선순위 P3 1. 성격 구조적 위험 1. 수정이 만든 결함은 아니다. 지난 라운드들이 보고하지 않은 기존 경로다. + +### 02-01 active pointer 본문이 계속 읽히지 않으면 activation·cleanup·inspect·조회가 모두 멈추고, adapter API 안에서는 돌아올 길이 없다 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 구조적 위험(회복 공백) | +| 관련 관점 | 28, 6, 18, 24, 11 | +| 근거 | ① active pointer를 쓰는 곳은 activation 하나다(`src/adapters/cache-storage/public-response-cache-adapter.ts:757-763`). ② activation은 이전 pointer를 먼저 읽고, `CORRUPT_DATA` 밖의 실패면 멈춘다(`:714-730`). 주석이 이것을 의도로 적는다. "A transient read failure still stops activation"(`:718-721`). ③ pointer 본문 읽기 실패는 `CORRUPT_DATA`가 아니다. `readActivePointer`가 예외를 `exceptionFailure`로 바꾼다(`:1041-1064`). `TypeError`는 `UNAVAILABLE`/`RETRY`, `NotReadableError`는 `NOT_READABLE`/`REOPEN`이다(`public-cache-codec.ts:566-583`, `src/adapters/browser-file-storage/result.ts:49-96`). ④ 같은 실패에서 cleanup(`:813-819`), inspect(`:885-893`), 조회(`:246-254`)도 멈춘다. stage만 pointer를 읽지 않는다. ⑤ 설계 문서는 이 경우를 "일시 오류"로만 적는다(`docs/architecture/browser-file-and-origin-storage.md:1013-1017`). 테스트도 일시 오류만 본다. 오류를 걸었다가 원래 `match`로 되돌린다(`tests/unit/public-response-cache-repair.test.ts:953-975`). ⑥ 0929/02-01은 손상 pointer(`CORRUPT_DATA`)만 다음 activation이 덮어쓰게 했다(`:722-733`). 1105/02-02는 같은 "일시와 지속을 가를 수 없음" 문제를 asset entry에서 "다시 stage가 덮어쓴다"로 풀었다. pointer는 stage가 쓰지 않으므로 그 수정 밖이다. ⑦ 실험 02-R1 X3(rc=0, 예측과 같음): pointer 본문이 다시 쓰기 전까지 읽히지 않게 한 뒤 새 adapter로 본다. 조회 `UNAVAILABLE`/`RETRY`. 새 release r2 stage `ok fetched=2`. r2 activate 두 번, cleanup, inspect, 현재 release r1 activate 모두 `UNAVAILABLE`/`RETRY`. pointer 다시 쓰기 0회, 끝까지 읽히지 않음 | +| 발생 조건 | control cache(`control`)의 active pointer entry 본문이 다시 쓰기 전까지 계속 읽히지 않는다(디스크의 blob 손실 등). entry 자체는 있고 `cache.match`는 응답을 준다 | +| 영향 | 그 origin의 Cache Storage 관리가 멈춘다. 새 release는 stage되지만 activate되지 않는다. cleanup이 멈춰 owned cache가 쌓인다. inspect도 같은 실패라 운영자가 상태를 볼 수 없다. 조회는 모두 `UNAVAILABLE`/`RETRY`다. 제품 SW가 네트워크로 넘기면 사용자 피해는 오프라인 사용을 잃는 것이다. 돌아오는 길은 adapter 밖에서 control cache를 지우는 것(사이트 데이터 삭제, devtools, 제품 코드의 `caches.delete`)뿐이다. 안내 `RETRY`는 지켜지지 않는다. 데이터 노출과 삭제는 없다 | +| 심각도·우선순위 | Low · P3 — 1105/02-02와 같은 등급이다. 데이터는 지켜지고 온라인 경로는 산다. 지속되는 본문 읽기 실패가 실제 브라우저에서 생기는지 모른다. 레시피가 미조립이다. 영향 범위는 asset 하나보다 넓다(관리 전체). 그래도 사용자 데이터 손실이 없어 Medium으로 올리지 않는다 | +| 통제·증거 | 일시 오류에서 멈추는 규칙 M3(`public-response-cache-repair.test.ts:953-975`) · 지속 실패 회복 M0(pointer를 다시 쓸 길이 없음) · E1, E2(02-R1 X3, 메모리 fake에 오류 주입) | +| 확실성과 남은 가정 | 코드 경로는 정적으로 확인했고 실험 X3이 같은 결과를 냈다. 실제 Chrome·Firefox·Safari에서 Cache Storage 본문 읽기 실패가 지속되는지, 어떤 오류 이름으로 오는지는 확인하지 못했다. 일시 오류만 있다면 이 항목은 결함이 아니다(1105/02-02와 같은 가정) | +| 결정의 근거 | 확인한 사실: 일시 오류에서 activation을 멈추는 것은 기록된 의도다(`:718-721`, 설계 문서 `:1013-1014`). 그 의도는 일시 오류 하나로 rollback 목록을 잃지 않는 것이다. 리뷰어 추론: 일시와 지속을 가를 수 없을 때 "멈춤"만 있으면 지속 실패에서 끝나지 않는다. entry에서는 다시 쓰기가 같은 바이트라 비용이 없었다. pointer는 다시 쓰면 rollback 목록을 잃는다. 그래서 1105/02-02의 답을 그대로 옮길 수 없고 선택이 필요하다 | +| 이해 비용 | 운영자는 `UNAVAILABLE`/`RETRY`만 본다. 다시 해도 같고, inspect도 같은 실패다. 원인이 pointer라는 것을 알려면 adapter 코드를 읽어야 한다 | +| 최소 개선 방향 | (가)와 (나) 중 하나. (가) 설계 문서와 포트 주석에 "pointer 읽기가 계속 실패하면 control cache를 지우고 다시 activate한다. rollback 목록은 잃는다"를 적는다. (나) 운영자가 고르는 길을 둔다. activation에 선택 옵션(예: 읽을 수 없는 pointer를 손상처럼 덮어씀)을 더한다. 0929/02-01의 `CORRUPT_DATA` 경로를 그대로 쓴다 | +| 대안 비교 | (가) 문서만: 0줄 코드. 제품이 adapter 밖 코드로 control cache를 지워야 한다. (나) 명시 옵션: 분기 하나와 테스트 1~2개. 기본 동작은 그대로라 일시 오류 테스트가 지켜진다. 운영자가 rollback 목록 손실을 알고 고른다. (다) 연속 N회 실패를 손상으로 본다: 실패 횟수를 저장해야 해서 크다. 일시 오류가 길게 이어지면 rollback 목록을 잃는다. (나)가 가장 작은 코드 해결이다. 1105/02-02 남은 부분(marker)과 같이 고치면 "control record를 다시 쓰는 길"을 한 번에 정할 수 있다 | +| 단순화의 보존 조건 | 일시 오류 하나로 rollback 목록을 지우지 않는다(`:953-975`). 검증한 후보만 활성화한다. 손상 pointer는 지금처럼 다음 activation이 덮어쓴다(`public-response-cache-repair.test.ts:779`) | +| 비용·부작용 | (나)는 수십 줄. service-worker-pwa 번들 여유가 306 B다(FE-GATE-012 `:88`, 9,794 / 10,100 gzip B). 포트에 선택 칸이 하나 생기면 [계약] CHANGELOG 행이 필요하다 | +| 재검토 조건 | 실제 브라우저에서 지속되는 본문 읽기 실패가 관찰되지 않으면 (가)로 닫는다. Service Worker drain 조합을 조립할 때 rollback 정책과 같이 본다 | +| 완료 기준 | X3 시나리오에서 문서에 적힌 절차나 API로 pointer를 되살리고, 다음 activate가 성공한다. 일시 오류 테스트(`:953-975`)는 그대로 통과한다 | +| 검증 방법 | 02-R1의 X3 테스트(배치 패치 `scratchpad/r5/requests/02-R1-control-unreadable.diff`가 만든 `tests/unit/zz-r5-02-control-unreadable.test.ts`)를 `public-response-cache-repair.test.ts`의 0929/02-01 묶음으로 옮겨 기대를 바꾼다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +## 4. 28개 관점 판정 (36.2) + +판정 기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 굵은 번호는 깊게 본 관점이다. + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +| --- | --- | --- | --- | --- | --- | +| 1 | 코드 성숙도 | 적용 — "검증 뒤에만 성공", 판정 분류 | M2 / M2 | E1, E2(FE-GATE-005) | P — asset entry의 지속 실패가 다시 stage로 풀렸다(1105/02-02). release marker(1105/02-02 남은 부분)와 active pointer(02-01)는 같은 실패에서 다시 쓰지 않는다 | +| 2 | 구조적 성숙도 | 적용 — 배럴 경계, kernel 예외 | M3 / M3 | E2(FE-GATE-010 PASS) | P — 레시피는 배럴과 조립 계약만 import한다(`browser-file-session-capability.ts:1-2`). cross-context 예외가 배럴 전체를 연다(`0929/02-06`, 결정 대기) | +| 3 | 변경 용이성 | 적용 — 수명 연결, 정책 추가 | M2 / M2 | E1, E2 | O — 제품 파일만 고쳐 file runtime을 세션에 묶는다. label 형식이 문서에 적혀 있다(`03-outside-feature-folder.md:122`) | +| 4 | 인지 부하 | 적용 — 큰 파일, 판정 종류 | — / — | E1 | P — `public-response-cache-adapter.ts`가 1,241줄이다. 판정이 넷이 됐다(`:1095-1106`). `REPAIRABLE`과 `UNREADABLE`은 이제 activation code 하나만 다르다. 그 차이의 이유는 주석을 읽어야 안다. 레시피 주석은 매뉴얼과 맞다(1105/02-03) | +| **5** | 위험 가시성 | 적용 — 실패 의미, 세션 수명 | M1~M2 / M2 | E1, E2 | P — 제품 closer 실패가 label과 함께 보인다(1105/02-01). pointer가 계속 읽히지 않으면 inspect도 실패해 상태가 보이지 않는다(02-01) | +| **6** | 실패 성숙도 | 적용 — 손상·일시·지속 실패 구분 | M2 / M2 | E1, E2(02-R1) | P — entry는 일시·지속 모두 다시 stage로 끝난다. marker·pointer는 지속 실패가 일시 오류로 분류돼 끝나지 않는다(1105/02-02 남은 부분, 02-01). 중단 분기(`:1168`)는 테스트가 없다. 바뀌어도 activation의 recovery 칸만 달라진다 | +| 7 | 운영 성숙도 | 적용 — 관측 연결 | M2 / M3 | E1, E2 | P — scope reset 실패가 단계마다 진단에 남고 테스트가 고정한다(1105/02-01). file·cache observer는 여전히 레시피 조립 몫이다 | +| **8** | 디버깅 가능성 | 적용 — reason·operation·label | M2 / M2 | E1, E2 | P — 실패한 participant의 label이 남는다(고쳐짐). inspect 실패 operation이 여전히 `CACHE_LOOKUP`이다(`:942`). pointer 지속 실패는 원인을 가리키는 신호가 없다(02-01) | +| 9 | 유지보수 성숙도 | 적용 — 문서·CHANGELOG 정합 | M1 / M1 | E1 | P — 레시피 주석이 고쳐졌다. 설계 문서·포트 주석이 다시 stage 범위를 넓게 적는다(1105/02-02 남은 부분). CHANGELOG 0.2.0 행이 그대로 틀렸다(`0929/02-03`) | +| **10** | 테스트 성숙도 | 적용 — 수정 테스트, 변이 | M3 / M3 | E2(이 영역 unit 13파일·recipe 1파일 통과), E2(변이 8개 모두 검출, 02-R2~R9) | P — 지난 생존 변이(F0202-cor·-pol·-lim·-notreadable, M05, N38)마다 그것을 겨냥한 테스트가 생겼고, 그 변이가 모두 그 테스트에서 실패한다. 수정 커밋의 테스트도 같다(capability 전달, scope label). F0202-int는 동등 변이다(2절). marker·pointer 지속 실패는 테스트가 없다. `scope_participant` 값 정책만 지우는 변이는 잡히지 않지만 호출부가 먼저 걸러 동작이 같다 | +| **11** | 데이터 성숙도 | 적용 — pointer·marker·캐시 entry | M2 / M2 | E1, E2 | P — 손상 marker는 다시 stage로 고친다(`:891`). 계속 읽히지 않는 marker와 pointer는 고칠 길이 adapter 밖뿐이다(1105/02-02 남은 부분, 02-01) | +| 12 | 동시성 성숙도 | 적용 — async 경쟁, 탭 간 순서 | M3 / M3 | E1, E2 | O — 이 영역의 경쟁 코드는 바뀌지 않았다. 재시도마다 scope 진단이 남는 것도 순서대로 고정됐다(`runtime-adapters-product-scope-participants.test.ts:190-196`) | +| 13 | 확장성 | 적용 — 상한 값 | M2 / M2 | E1 | O — 상한 값 변경 없음. 부하 목표 없음 | +| 14 | 성능 성숙도 | 적용 — 레시피 번들, 초기 JS | M2 / M2 | E2(FE-GATE-012 `:76`, `:88`) | P — service-worker-pwa 9,794 / 10,100(여유 306 B, 지난 342 B에서 36 B 줄었다), file-transfer 56,130 / 57,800 gzip B. 초기 JS 204,158 / 206,848(D7로 올린 예산, 오케스트레이터 결정). 02-01이 초기 JS에 +251 B를 더했다는 것은 수정 세션의 측정이다(5절). `inspect()`·`cleanupOwned()`에 cursor·deadline이 없다(`0929/02-02`) | +| **15** | 보안 성숙도 | 적용 — 세션 경계, 위험 확장자, 저장 영역 | M2~M3 / M2~M3 | E1, E2 | P — 진단 label은 소스가 정한 형식 토큰만 실리고 telemetry로 나가지 않는다. host `storageArea` 비교에 테스트가 생겼다(1101/02-04). media type 짝은 보지 않는다(`1101/02-02`) | +| 16 | 의존성 성숙도 | 적용 제외 — 세 폴더의 외부 패키지 import 0건(grep) | — | E1 | - | +| **17** | API / Contract 성숙도 | 적용 — 포트·진단·제품 확장 계약 | M2 / M2 | E1, E2 | P — `scope_participant` 키가 분류·값 정책·CHANGELOG 행과 함께 생겼다(0절). label 형식 축소가 먼저 할 일에 있다(`CHANGELOG.md:29`). 포트 `verified`의 뜻이 적혔다. 포트 주석이 lookup 실패도 다시 stage가 고친다고 적는다(`cache-storage-ports.ts:66-69`, 1105/02-02 남은 부분). label 중복은 계약에 없다 | +| **18** | 배포 성숙도 | 적용 — 배포·rollback, 게이트 | M2 / M2 | E2(FE-GATE-020 rc=0) | P — 제거 드릴 게이트가 통과한다. 계속 읽히지 않는 marker가 있는 rollback 대상은 되돌릴 수 없다(1105/02-02 남은 부분). pointer가 계속 읽히지 않으면 어떤 release도 activate되지 않는다(02-01) | +| 19 | 설정 성숙도 | 적용 — 정책 조합 검증 | M3 / M3 | E1, E2 | P — 위험 `safeExtension`과 형식 밖 scope label이 조립 때 `TypeError`다. media type 짝은 통과한다(`1101/02-02`) | +| 20 | 개발자 경험 | > 영역 14 — 레시피 주석 수정(1105/02-03)은 이 영역에서 확인했다 | — | — | > | +| 21 | Guardrail 성숙도 | 적용 — 제거 드릴, kernel 예외, 진단 분류 | M3 / M3 | E2(FE-GATE-020, FE-GATE-010) | P — 제거 드릴이 통과한다. 새 진단 키가 분류 없이 들어오면 `check:diagnostics`와 `observability-cardinality.test.ts:15-18`이 막는다. 문서를 읽는 테스트 제외 목록은 손으로 관리한다(`scripts/lib/removal-fixture.ts`, 지난 라운드와 같다) | +| 22 | 추상화 성숙도 | 적용 — participant 목록, 세션 getter | — / — | E1 | P — `participants`가 배열과 함수를 둘 다 받는다(`server-state-scope-runtime.ts:51-57`). 제품 closer가 나중에 들어오는 것을 wrapper 없이 푼다. 판정 union이 넷이다(4번) | +| 23 | 일관성 | 적용 — 실패 분류 | — / — | E1 | P — stage가 entry 본문 읽기 실패는 다시 쓰고 marker 본문 읽기 실패는 멈춘다(`:463-468` 대 `:500-507`). `QUOTA_EXCEEDED`의 recovery가 `READ_ONLY`와 `ONLINE_ONLY`로 갈린다(`result.ts:80-85`, `public-cache-codec.ts:597-603`, 지난 라운드와 같다) | +| **24** | 네이밍 / 의미 성숙도 | 적용 — 실패 이름이 약속하는 것 | M2 / M2 | E1 | P — entry 실패의 `REHYDRATE`는 이제 지켜진다. marker·pointer 지속 실패의 `RETRY`는 지켜지지 않는다. `verified:false`가 판정 불가를 합친다(`0929/02-02`). "kebab-case"라는 이름에 비해 정규식이 `a-`·`a--b`도 받는다(`diagnostics.ts:147-149`, 영향 없음) | +| 25 | 조직 확장성 | 적용 제외 — 1인 관리 | — | — | - | +| 26 | Ownership 성숙도 | > 영역 12 | — | — | > | +| 27 | 삭제 가능성 | 적용 — 제거 드릴 | M3 / M3 | E2(FE-GATE-020 rc=0, junit 2개 failures 0) | O — browser-files·cache-storage·포트·레시피를 지운 fixture에서 검사가 모두 통과한다. 실제 Gitea 러너는 미실행 | +| **28** | 회복 가능성 | 적용 — 손상·지속 실패 회복 | M2 / M2 | E1, E2(02-R1) | P — 계속 읽히지 않는 asset entry는 다시 stage로 돌아온다(1105/02-02 완료 기준). release marker와 active pointer는 돌아오지 못한다(1105/02-02 남은 부분, 02-01) | + +집계(이 영역에서 판정한 24개): O 4(3, 12, 13, 27) · P 20 · X 0 · ? 0. 적용 제외 2(16, 25) · 다른 영역 2(20, 26). 지난 라운드 대비: 판정 기호는 같다. 7번 확인 통제가 M1 → M3로 올라갔다(1105/02-01). 5·8번의 원인이 02-01(1105)에서 02-01(1106)로 바뀌었다. 6·11·18·28번의 원인이 "asset entry"에서 "marker·pointer"로 좁아졌다. + +## 5. 미검증 + +| 항목 | 왜 확인하지 못했나 | 확인하려면 | +| --- | --- | --- | +| 실제 브라우저에서 Cache Storage 본문 읽기 실패가 지속되는지, 어떤 오류 이름으로 오는지(1105/02-02 남은 부분과 02-01의 발생 가능성) | 실기에서 blob 손실을 만들지 않았다. 02-R1은 메모리 fake에 오류를 주입했다 | 브라우저별 프로필에서 cache entry의 blob 파일을 지운 뒤 `response.body` 읽기 결과를 본다 | +| 02-01(1105)이 초기 JS에 더한 +251 B | 수정 세션의 커밋별 측정이다(README 16.2절 D7). 리뷰어는 커밋별로 재지 않았다. `bbde570` 전체는 204,158 B로 예산 안이다(FE-GATE-012 `:76`) | 부모 커밋과 `f738348`의 `--initial-baseline` 비교 | +| `FAILED` scope가 화면에서 어떻게 보이는지 | 영역 08·09 몫 | `FAILED` 주입 뒤 화면 상태 확인 | +| 레시피를 조립한 실제 화면에서 로그아웃 뒤 파일·download가 닫히는지 | 조립 코드가 없다. 레시피 테스트는 jsdom이다 | file-transfer 레시피를 조립한 제품 E2E | +| FE-GATE-020이 실제 Gitea 러너에서 같은 결과인지 | 러너가 없다 | 러너의 merge job | + +## 6. 실행 기록 + +### 6.1 오케스트레이터 게이트 결과(인용, `bbde570`, CI env) + +| 출처 | 결과 | +| --- | --- | +| `bbde570-ci/summary.txt` | FE-GATE-001~012·020 rc=0, FE-GATE-013 rc=1(host). FE-GATE-020 1,237초 | +| `gate-artifacts/FE-GATE-005.txt` | `:91` `server-state-scope-runtime.test.ts` 18건, `:118` `public-response-cache-repair.test.ts` 25건, `:126` `runtime-adapters-product-scope-participants.test.ts` 4건, `:228` `cross-tab-invalidation.test.ts` 19건 통과. 전체 `:312` 208파일, `:781` 332파일 통과 | +| `gate-artifacts/FE-GATE-007.txt` | `:103` `tests/recipes/browser-file-session-capability.test.ts` 1건 통과 | +| `gate-artifacts/FE-GATE-012.txt` | `:76` 초기 JS 204,158 / 206,848 gzip B, 27 / 32 파일. `:88` file-transfer 56,130 / 57,800, service-worker-pwa 9,794 / 10,100 | +| snapshot junit(03:24 뒤) | `coverage.xml` 4,085건 실패 0(이 영역 unit 13파일 포함), `optional-recipes.xml`(03:48), `browser-capabilities/results.xml` 69건 실패 0(이 영역 spec 7건 × 3엔진), `browser-file-storage-runtime-removal.xml` 7/7, `optional-recipe-removal.xml` 6/6 | + +### 6.2 배치 02-R1~R9 (오케스트레이터 실행) + +요청 파일: `scratchpad/r5/requests/02.md`. 패치는 `scratchpad/r5/requests/02-R*.diff`이고, 모두 laptop에서 `git apply --check`로 `bbde570`에 적용되는 것을 확인했다. 변이 없는 대조 실행은 6.1절의 게이트 로그로 대신한다. 실행: 2026-11-06 04:32, `bbde570`, env local, 항목마다 checkout 복원(`restore=clean`). 로그 `desktop:/tmp/claude-gates/r5/batch/out/R5-02-R.log`. + +| ID | 명령 | 변이 | 기대 | rc · 결과 | +| --- | --- | --- | --- | --- | +| 02-R1 | `node scripts/run-vitest.ts run tests/unit/zz-r5-02-control-unreadable.test.ts` | 테스트 파일 추가(소스 그대로) | X1·X2·X3 pass(예측이 맞음) | rc=0, 3/3 pass. 출력 `R5-02-OBS`: X1 `{activate1:UNAVAILABLE/RETRY, stage:"UNAVAILABLE/RETRY fetched=0", cleanup:"ok deleted=0", activate2:UNAVAILABLE/RETRY, stillUnreadable:true, markerRewrites:0}`. X2 `{lookupFirst·lookupSecond:UNAVAILABLE/RETRY, restage:"UNAVAILABLE/RETRY fetched=0", lookupAfterRestage:UNAVAILABLE/RETRY, stageNext:"ok fetched=2", activateNext:ok, lookupAfterNext:hit}`. X3 `{lookup:UNAVAILABLE/RETRY, stageNext:"ok fetched=2", activateNext1·cleanup·inspect·activateNext2·activateCurrent:UNAVAILABLE/RETRY, stillUnreadable:true, pointerRewrites:0}` | +| 02-R2 | `… run tests/unit/public-response-cache-repair.test.ts` | `REPAIRABLE_READ_CODES`에서 `CORRUPT_DATA` 뺌 | `DataError` 행 FAIL | rc=1, 1/25 FAIL. "… a body that fails as corrupt data …" code `CORRUPT_DATA` ≠ `INTEGRITY_FAILED`(`:586`). 기대와 같음 | +| 02-R3 | 같음 | `POLICY_REJECTED` 뺌 | 정책 밖 헤더 행 FAIL | rc=1, 1/25 FAIL. "… a header outside the policy …" code `POLICY_REJECTED`(`:586`). 기대와 같음 | +| 02-R4 | 같음 | `LIMIT_EXCEEDED` 뺌 | 길이 초과 행 FAIL | rc=1, 1/25 FAIL. "… a declared length over the entry limit …" code `LIMIT_EXCEEDED`(`:586`). 기대와 같음 | +| 02-R5 | 같음 | `NOT_READABLE` 더함 | `NotReadableError` 행 2건 FAIL | rc=1, 2/25 FAIL. E-1b 행(`:502`)과 표 행(`:586`)이 `NOT_READABLE` 대신 `INTEGRITY_FAILED`. 기대와 같음 | +| 02-R6 | 같음 | inspect `verified`를 `kind !== "REPAIRABLE"`로(M05) | "lists a candidate it could not read as unverified" FAIL | rc=1, 1/25 FAIL. `{r1:true, r2:true, r3:true}` ≠ `{r1:true, r2:false, r3:false}`(`:631`). 기대와 같음 | +| 02-R7 | `… run tests/unit/cross-tab-invalidation.test.ts` | host가 늘 `EXPECTED_LOCAL_STORAGE`(N38) | "takes a storage pulse only from the localStorage object it captured" FAIL | rc=1, 1/19 FAIL. 구독자가 2회 불렸다(`:471`). core 테스트 "rejects storage pulses from another or unknown storage area"는 통과. 기대와 같음 | +| 02-R8 | `… run tests/recipes/browser-file-session-capability.test.ts` | 조립에서 `...product.capabilities` 지움 | `Features did not receive the files capability` FAIL | rc=1, 1/1 FAIL, 그 메시지(`:238`). 기대와 같음 | +| 02-R9 | `… run tests/unit/runtime-adapters-product-scope-participants.test.ts tests/unit/server-state-scope-runtime.test.ts` | 진단에서 `scope_participant` 지움 | 2건 FAIL | rc=1, 2/22 FAIL. 두 기록에서 `scope_participant` 칸이 빠짐(`runtime-adapters-product-scope-participants.test.ts:183`, `server-state-scope-runtime.test.ts:166`). 기대와 같음 | + +F0202-int(`INTEGRITY_FAILED` 뺌)는 요청하지 않았다. 동등 변이라 살아남는 것이 맞고, 살아남는 결과는 동등을 증명하지 않는다. 동등은 2절에서 코드로 보였다. + +## 7. 새 발견 요약 + +| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line | +| --- | --- | --- | --- | --- | +| 02-01 | Low · P3 | 구조적 위험 | active pointer 본문이 계속 읽히지 않으면 activation·cleanup·inspect·조회가 모두 멈추고 API 안에서 돌아올 길이 없다 | `src/adapters/cache-storage/public-response-cache-adapter.ts:714-730`, `:813-819`, `:885-893`, `:246-254`, `:1041-1064` | diff --git a/docs/reviews/2026-11-06-maturity-review/03-adapters-http-state.md b/docs/reviews/2026-11-06-maturity-review/03-adapters-http-state.md new file mode 100644 index 00000000..1e1074a3 --- /dev/null +++ b/docs/reviews/2026-11-06-maturity-review/03-adapters-http-state.md @@ -0,0 +1,209 @@ +# 영역 03 — HTTP·서버 상태·인증·진단 + +> 검토일 2026-11-06 · 기준 `bbde570`(PR B 끝, 브랜치 `fix/maturity-review-2026-11-05-b`) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 경로 `src/adapters/http/`(`fileserver-upload.ts`는 01 영역), `src/adapters/browser-rpc/`, `src/adapters/query-cache/`, `src/adapters/auth/`, `src/adapters/diagnostics/`, `src/adapters/telemetry/`. 흐름 확인: `src/contracts/external-contract-runtime.ts`, `src/contracts/server-state.ts`, `src/presentation/adapters/query/application-query.ts`, `src/presentation/forms/use-app-form.ts`, `src/presentation/components/async-surface.tsx`, `src/application/view-models/async-state.ts`, `scripts/create-feature-write-slice.ts`, `config/contracts/`, 계약 문서 4.1·6·6.1, 런북 6.3, CHANGELOG 미출시 절. 짝 백엔드 `45d2a478`(pin)의 `docs/web/http-contract.md` §2·§4, `RateLimitInterceptor.java`, `RateLimitTransportError.java`, `OperationalError.java`, `FileserverErrorCode.java`, `WebAdvancedError.java` +> 깊게 본 관점 5, 6, 10, 12, 17, 21, 23, 28 +> 렌즈: BREAKING 1105/03-01(커밋 footer와 CHANGELOG 안내를 코드와 대조), 1105/03-02와 합친 커밋 `45c9c4d`의 통합 수정, 0929/03-03, 1103/03-01 남은 부분. 1105/03-02가 `NOT_APPLIED`로 바꾼 답이 결과 불명 재전송 경로에서 무엇을 하는지 +> **영역 판정(35.8): 조건부 사용 가능.** 짝 백엔드 쓰기 폼은 쓸 수 있다. 조건은 셋이다. (1) KEYED 쓰기에서 rate limit을 켜면, 결과 불명 뒤 같은 키 재전송이 429나 503 `RATE_LIMIT_*`로 거절될 때 화면의 "다시 시도"가 새 키로 보낸다. 첫 요청이 적용됐으면 같은 항목이 둘 생긴다(새 03-01, 03-R1에서 재현). (2) `refusedBeforeWrite`에는 쓰기 전에만 나온다고 확인한 업무 code만 적는다(플랫폼 code는 이제 조립이 막는다). (3) IDEMPOTENT 쓰기는 결과 불명 뒤 NEVER처럼 "변경됨으로 확인"만 남는다(새 03-03). bulk 응답은 지원하지 않는다(1103/03-02). + +ID 표기: `03-NN`은 이번(2026-11-06) 라운드 발견이다. 지난 라운드는 `1105/03-NN`, 그 전은 `1103/03-NN`, `1101/03-NN`, `0929/03-NN`이다. 다른 영역의 이번 라운드 발견은 `1106/NN-MM`으로 적는다. + +**실행 상태.** 이 영역은 아무것도 돌리지 않았다. 증거는 메인 세션이 `bbde570`에서 CI env로 돌린 게이트 로그(`desktop:/tmp/claude-gates/bbde570-ci/`)다. FE-GATE-005(test:unit 208 files / 3,056 tests, coverage 332 / 4,085), FE-GATE-006(component 41 / 278), FE-GATE-007(integration 11 / 212), FE-GATE-020(생성 기능 드릴 포함)이 모두 rc=0이다. 변이와 실험은 요청 파일 `scratchpad/r5/requests/03.md`의 03-R1~R7로 냈다. 오케스트레이터가 `bbde570`에서 하나씩 돌렸고 항목마다 checkout이 깨끗하게 돌아왔다(`restore=clean`). 로그는 `desktop:/tmp/claude-gates/r5/batch/out/R5-03-R1.log`~`R5-03-R7.log`다. 실험 1건은 결함을 재현했다. 변이 6건은 모두 기대한 테스트에서 실패했다(6절). + +## 0. 결론 + +- **BREAKING 1105/03-01은 커밋 footer대로 동작한다(고쳐짐).** 조립이 6.1절의 "쓰기 뒤 가능" 플랫폼 code 20개 선언을 거절한다(`src/contracts/external-contract-runtime.ts:638-663`, `:691-695`). 이 검사는 `composeContractContributions` → `assertHttpContract` → `assertRefusedBeforeWrite` 순으로 모든 쓰기에 닿는다(`:1084`, `:571`). 조립 없이 부른 실행기도 그 code를 무시한다(`src/adapters/http/backend-envelope.ts:328-339`). 목록은 계약 문서 6.1절 표와 양방향으로 대조된다(`tests/unit/backend-contract-pin.test.ts:263-302`). CHANGELOG "먼저 할 일" 3단계와 [계약] 행(`CHANGELOG.md:26`, `:60`)의 문장이 코드와 같다. 조립 검사, 실행기 fail-close, 6.1절 대조를 하나씩 깨는 변이 셋이 모두 검출됐다(03-R4 4건, R5 5건, R6 1건 실패). +- **1105/03-02와 합친 커밋 `45c9c4d`의 통합 수정은 맞다(고쳐짐).** 네 곳이 같은 사실을 적는다. 답 표의 §4 503 세 행(`config/contracts/backend-idempotency-answers.json:51-71`), pin의 빈 `notCopied`(`config/contracts/backend-contract-pin.json:50`), 프론트 거절 표의 두 행(`backend-envelope.ts:177-181`), 계약 문서 4.1(`docs/architecture/backend-api-and-server-state-contract.md:168-183`)이다. 백엔드 `45d2a478`의 §4 표와 `RateLimitInterceptor.preHandle`(`:31-65`)이 두 code를 컨트롤러 전에 503으로 낸다. 프론트 표의 두 행을 지운 변이를 단위·pin·통합 테스트 7건이 잡았다(03-R7). +- **0929/03-03은 고쳐졌다.** 훅이 키 없는 결과 불명과 같은 입력의 `submit`을 보내지 않는다(`application-query.ts:569-583`). 화면은 `unknownEffectResendable === true`일 때만 재전송 버튼을 그린다(`async-surface.tsx:227-229`). 두 가드를 하나씩 되돌린 변이가 각각 1건씩 검출됐다(03-R2, R3). +- **나머지 이월:** 1103/03-01 일부(거절 문구 자리는 생겼다. 500 `IDEMPOTENCY_RECOVERY_REQUIRED` 뒤 재전송 버튼은 결정 대기). 1103/03-02·1103/03-07 일부(결정 대기). 1101/03-04·0929/03-02 남음. 이 둘은 지난 README §16.6에 행이 없다. +- **새 발견 3건: Medium·P2 1, Low·P3 2.** 03-01: KEYED 결과 불명의 같은 키 재전송이 쓰기 전 거절이나 보내기 전 실패로 끝나면 훅이 결과 불명과 키를 버린다. 생성 KEYED 폼은 그때 "다시 시도"로 새 키를 보낸다. 1105/03-02가 503 `RATE_LIMIT_*`를 이 길에 더했다(429·401은 전부터). 실험 03-R1이 훅과 실제 실행기·폼 모두에서 `keys=["key-1","key-1","key-2"]`를 보였다. 03-02: 계약 6.1절은 rate-limit 503에 "자동 재전송은 없다"고 적지만 IDEMPOTENT 쓰기는 `retryBudget` 안에서 다시 보낸다. 03-03: 0929/03-03의 두 가드가 키 유무로만 갈라서, IDEMPOTENT 쓰기도 결과 불명 뒤 재전송과 같은 입력 재제출이 막힌다. +- **고친 커밋이 이 영역의 검사를 약하게 만든 곳은 찾지 못했다.** 지운 단언, 새 skip, 시간 상한 상향이 없다(2절 끝). 제거 fixture의 문서 테스트 목록에 pin 테스트가 들어간 것은 12 영역이 1106/12-01로 셌다. + +## 1. 범위 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`. 짝 백엔드 `clean-architecture-backend-template`은 `git show 45d2a478:`로 읽기만 했다 | +| 커밋·작업 상태·확인 시점 | 프론트 `bbde570`(laptop worktree, HEAD = 기준, 추적 파일 변경 없음). 백엔드 pin `45d2a478`. 백엔드 HEAD는 pin 뒤 두 커밋(`3d73b6f1`, `6e992970`)이다. 그 두 커밋은 6.1절이 인용한 파일 중 `GlobalExceptionHandler.java`의 로그 줄과 `IdempotencyExecutor.java`의 주석만 바꿨다(`git diff 45d2a478 HEAD`). 단계 판정은 바뀌지 않는다. 2026-11-06 | +| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음. 두 템플릿을 짝으로 써서 빨리 출시하는 것이 목표다 | +| 필수 요구와 규모·운영 목표 | 짝 백엔드 `http-contract.md` §2(멱등성 응답: 결과 불명은 "새 키 금지", `:89`, `:112`)·§4(web 전용 code), 프론트 계약 문서 4.1·6·6.1, 런북 6.3(`docs/operations/api-contract-and-server-state-recovery.md:248-271`), 매뉴얼 `02-decision-tables.md` 3·4절. 수치 운영 목표는 없다 | +| 읽은 코드·구성 범위 | 줄 단위: `backend-envelope.ts` 전부, `external-contract-runtime.ts` 155~175·455~700·840~1090, `http-execution-v3.ts` 900~920·1040~1160·1620~1800, `http-retry-lifecycle.ts` 1~75, `application-query.ts` 360~370·520~900, `use-app-form.ts` 전부, `async-surface.tsx` 120~235, `server-state.ts` 290~320, `create-feature-write-slice.ts` 225~320·640~745, 계약 문서 161~230·269~412, CHANGELOG 14~108, 매뉴얼 02 80~200, 런북 6.3, `config/contracts/` 세 JSON, `scripts/lib/backend-contract-excerpt.ts`, `scripts/lib/removal-fixture.ts` 40~90. 테스트: `backend-contract-pin.test.ts` 전부, `backend-envelope.test.ts`·`external-contract-runtime.test.ts`·`http-execution-v3-envelope.test.ts`·`form-foundation.test.tsx`·`application-mutation-admission.test.tsx`·`async-surface.test.tsx`의 바뀐 부분. 커밋: `5c0b37e`, `c6c37f3`, `683ccfb`, `12d97d7`, 합친 커밋 `45c9c4d`(두 부모와의 diff). `git diff 8a44226..bbde570`의 영역·흐름 16파일(+630/−96). `browser-rpc`·`auth`·`diagnostics`·`telemetry`는 `8a44226` 뒤 변경이 없다. `query-cache`는 1105/02-01의 `server-state-scope-runtime.ts` 변경뿐이다(02 영역) | +| 수행한 테스트·실험 | 실행 환경 = desktop. 이 영역이 직접 돌린 것은 없다. 인용한 게이트: FE-GATE-005·006·007·020(CI env, rc=0, `bbde570-ci/summary.txt`). 배치 03-R1(실험), 03-R2~R7(변이). 오케스트레이터가 local env로 하나씩 돌렸고 7건 모두 `restore=clean`(`r5/batch/out/R5-03-R*.log`). 결과는 6절 | +| 확인하지 못한 범위·이유 | 5절 | +| 이전 리뷰와 비교 가능한 범위 | `8a44226..bbde570`의 영역 커밋(`git log --oneline 8a44226..bbde570 -- <경로>`). 지난 실행 결과는 증거로 쓰지 않았다 | + +## 2. 지난 발견 재확인 + +대상: 지난 README §15의 03 행 둘(1105/03-01, 03-02), §16.5의 03 행 넷(1103/03-01, 03-02, 03-07, 0929/03-03), 지난 03 문서 2절이 "남음"으로 둔 이월 둘(1101/03-04, 0929/03-02). §16.6에는 03 행이 없다. §16.4·§16.5의 "고침"은 주장으로만 보고 지난 03 문서 3절의 완료 기준으로 다시 판정했다. + +| 지난 ID | 내용 | 상태 | 근거 | +|---|---|---|---| +| 1105/03-01 Low·P3 | `refusedBeforeWrite`가 6.1절의 "쓰기 뒤 가능" 플랫폼 code도 받는다 | **고쳐짐** (변이 3개 검출: 03-R4 4건, R5 5건, R6 1건) | 완료 기준 "X2의 계약이 조립에서 6.1절을 이유로 거절된다"를 코드와 테스트로 확인했다. ① 목록: `PLATFORM_CODES_POSSIBLY_AFTER_WRITE` 20개(`external-contract-runtime.ts:627-663`). 6.1절 표의 "쓰기 뒤 가능" 행(`backend-api-and-server-state-contract.md:319-325`)에서 참조 도메인 6개와 web-advanced patch 2개를 뺀 것과 같다. 백엔드 `45d2a478`의 400·409·422 플랫폼 code를 enum에서 모두 셌다(`OperationalError.java:15-85`, `WebTransportError.java:18-24`, `FileserverErrorCode.java:26-44`, `WebAdvancedError.java:23-41`). 400·409·422인 플랫폼 code 중 6.1절에 없는 것은 없다. ② 조립 거절: `assertRefusedBeforeWrite`가 멱등성 접두사 다음에 그 목록을 본다(`:665-699`, 문구 `:693`). 모든 쓰기 operation에서 불린다(`:571`). 스냅숏한 목록을 검사하고 설치한다(`:846`, `:867-895`, `:1084`). ③ 실행기 fail-close: `declaredBeforeWrite`가 그 목록을 뺀다(`backend-envelope.ts:328-339`). ④ 테스트: X2의 네 code가 6.1절 이유로 거절된다(`tests/unit/external-contract-runtime.test.ts:286-296`). 선언해도 다섯 code가 `MAYBE_APPLIED`다(`tests/unit/backend-envelope.test.ts:117-129`). 목록과 6.1절 표를 양방향 대조한다(`backend-contract-pin.test.ts:263-302`). 세 파일 모두 FE-GATE-005에서 통과(47·37·15건). **BREAKING 안내:** 커밋 footer는 "`composeContractContributions`가 거절한다. 그 code를 목록에서 지운다. 그 실패는 결과 불명으로 남는다"이다(`5c0b37e`). 코드가 그렇다. CHANGELOG 3단계(`CHANGELOG.md:26`)와 [계약] 행(`:60`)도 같은 목록과 같은 결과를 적는다. 매뉴얼 02 4절(`docs/manual/02-decision-tables.md:185`)과 오류 표(`docs/manual/reference/errors.md:106`)가 같은 거절 문구를 적는다. 남은 것: 업무 code의 잘못된 선언은 설계상 기능 작성자의 판단이다(커밋 "위험·한계") | +| 1105/03-02 Low·P3 | 백엔드 §4의 rate-limit 503 두 code가 답 표 밖이라 생성 쓰기에서 결과 불명이 된다 | **고쳐짐** (변이 검출 03-R7: 7건). 이 수정이 새 03-01의 길을 넓히고 새 03-02를 만들었다 | 완료 기준 "503 `RATE_LIMIT_UNAVAILABLE`이 분류기와 상관없이 `NOT_APPLIED`/retry-later"를 확인했다. 분류기가 `MAYBE_APPLIED`인 create에서 두 code가 `SERVER_FAILURE`·`NOT_APPLIED`다(`tests/integration/http-execution-v3-envelope.test.ts:707-726`, FE-GATE-007 통과). kind `SERVER_FAILURE`는 action `retry`라(`src/contracts/errors.ts:85`) 폼은 `retry-later`다(`use-app-form.ts:305-314`). **합친 커밋 `45c9c4d` 확인:** 07-01 브랜치 부모(`45c9c4d^2`)의 pin은 두 code를 `notCopied`에 두었다. 합친 트리에서는 비었다(`backend-contract-pin.json:50`). 답 표는 두 행을 `refusedBeforeWrite: true`, `sameKeyResend: false`로 둔다(`backend-idempotency-answers.json:58-71`). 프론트 표는 status 503과 함께 둔다(`backend-envelope.ts:177-181`). 계약 4.1은 "§4의 503 셋을 옮겼다", "`notCopied`는 지금은 없다"로 고쳐졌다(`backend-api-and-server-state-contract.md:168-183`). 매뉴얼 02는 두 code를 `NOT_APPLIED` 줄에 적는다(`02-decision-tables.md:176`). 사본 §4 네 행(`config/contracts/backend-http-contract-excerpt.json:28-33`)이 백엔드 `45d2a478:docs/web/http-contract.md:188-193`과 같다. `answerTableProblems`가 사본 행마다 답 표나 `notCopied` 중 정확히 한 곳을 요구한다(`scripts/lib/backend-contract-excerpt.ts:116-160`, 테스트 `backend-contract-pin.test.ts:165-179`). 백엔드 사실: `preHandle`이 `false`를 돌려주며 쓰고(`RateLimitInterceptor.java:55-65`), status는 둘 다 503이다(`RateLimitTransportError.java:29-32`). main 소스에서 두 code를 내는 곳은 그 두 줄뿐이다. 비동기 재디스패치 위험은 계약 6.1에 적었고 백엔드로 넘겼다(`backend-api-and-server-state-contract.md:342-346`). 작은 잔여: pin 테스트 머리 주석이 아직 "§4's async timeout"만 적는다(`backend-contract-pin.test.ts:20`). 결함으로 세지 않는다 | +| 1103/03-01 (= 1103/08-01) High·P1 → 남은 부분 Medium·P2 | 업무 규칙 거절이 결과 불명이 된다. 남은 부분: 거절 이유가 안 보인다, KEYED에서 500 `IDEMPOTENCY_RECOVERY_REQUIRED` 뒤 재전송 버튼이 남는다 | **일부** (결정 대기) | 고쳐진 것: 폼이 `refusalMessages`로 `NOT_APPLIED` 실패의 code에 기능 문구와 필드를 붙인다(`use-app-form.ts:30-38`, `:50-59`, `:251-271`, `:472-487`). 결과 불명은 code와 상관없이 그대로다(`:482`). 테스트 `form-foundation.test.tsx:1005-1101`(FE-GATE-006 통과, 34건). 남은 것: 같은 키 재전송이 500 `IDEMPOTENCY_RECOVERY_REQUIRED`를 받으면 `MAYBE_APPLIED`라 결과 불명이 다시 서고 버튼이 남는다(`backend-envelope.ts:271-276`, `application-query.ts:684-698`). 백엔드 §2가 그 답에 "같은 키 재전송은 안전하다"고 적어(`45d2a478:docs/web/http-contract.md:113`) 거두는 것도 선택지 하나다. 고르는 사람은 프론트 템플릿 담당이다(`12d97d7` 본문, `CHANGELOG.md:94`). 폼 쪽 판정은 08 영역이 본다 | +| 1103/03-02 Medium·P2 | Envelope 읽기가 `meta.page`를 버리고 bulk `results`를 거절한다 | **일부** (bulk 지원 여부 결정 대기) | `meta.page`는 지난 라운드대로다(`backend-envelope.ts:22-36`, `:49`). bulk는 계약 4.1이 "지원하지 않는다"로 적는다(`backend-api-and-server-state-contract.md:205-207`). 그 문장의 "`responseEnvelope`를 빼고" 안내가 1103/16-01 BREAKING 뒤 맞지 않는 것은 07 영역의 1106/07-01이다 | +| 1103/03-07 Low·P3 | 두 생성기가 만드는 operation이 맞지 않는다 | **일부** (결정 대기 D3) | 백엔드 생성기 컨트롤러는 pin과 HEAD 모두 `POST`와 `GET /{id}`만 만든다(`45d2a478`·`HEAD`의 `__Feature__Controller.java.tmpl:49`, `:63`). 프론트 생성 목록이 405를 받는다고 주석이 적는다(`scripts/create-feature.ts:766-771`) | +| 0929/03-03 High·P1 → 남은 부분 Medium·P2 | 키 없는 결과 불명 쓰기를 같은 입력으로 다시 보낸다(훅 직접 호출), 손으로 만든 상태가 버튼을 그린다 | **고쳐짐** (변이 2개 검출: 03-R2, R3 각 1건) | 지난 문서의 최소 개선 둘이 들어왔다. ① 훅의 `submit`이 같은 입력의 결과 불명 admission에 키가 없으면 보내지 않고 `NOT_STARTED` `DUPLICATE_IN_FLIGHT`(code `UNKNOWN_EFFECT_PENDING`)를 돌려준다(`application-query.ts:564-583`). admission을 만들기 전이라 결과 불명 상태와 identity lease는 그대로다. 테스트: 같은 입력은 `execute` 1회, 상태는 결과 불명 그대로(`tests/component/application-mutation-admission.test.tsx:563-583`). 다른 입력은 보낸다(`:585-594`). ② 화면은 `=== true`일 때만 버튼을 그린다(`async-surface.tsx:227-229`). 플래그 없는 상태는 버튼이 없다(`tests/component/async-surface.test.tsx:128-143`). 기존 테스트 하나는 입력에 `isUnknownEffectResendable: true`를 더했고 단언은 그대로다(`:63-75`). 두 파일 모두 FE-GATE-006 통과(19·35건). 런북 6.3-4가 키 없는 재저장을 적는다(`api-contract-and-server-state-recovery.md:259-264`). 생성 NEVER 페이지 테스트 "keeps a create whose response was lost unknown and offers no resend"는 FE-GATE-020에서 통과했다(`gate-artifacts/FE-GATE-020.txt` 2188행). 가드가 키 유무로만 가르는 데서 생긴 IDEMPOTENT 쪽 부작용은 새 03-03이다 | +| 1101/03-04 Low·P3 | 효과 판정과 화면 분류가 두 함수로 나뉜다 | **남음** (문서화) | `envelopeFailureEffect`(`backend-envelope.ts:352-363`)와 `envelopeFailureReading`(`:390-410`)이 그대로다. 지난 README §16.6에 이 행이 없다 | +| 0929/03-02 Medium·P2 | `x-correlation-id` CORS 허용이 문서 통제뿐이다 | **남음** | 계약 §5의 문장뿐이다(`backend-api-and-server-state-contract.md:257-267`). `8a44226` 뒤 바뀐 것이 없다. 지난 README §16.6에 이 행이 없다 | + +지난 라운드에 고쳐짐으로 판정한 03 항목(1103/03-03·03-04·03-05·03-06·03-08, 1101/03-03·03-06, 0929/03-06)은 이번 범위에서 다시 열리지 않았다. 쓰기 `SAFE` 거절(`external-contract-runtime.ts:575-582`), 5xx 넷의 `MAYBE_APPLIED`(`backend-envelope.ts:256-281`), `effect_certainty`(`src/bootstrap/runtime-adapters.ts:213`), 실패 `traceId`(`http-execution-v3.ts:1716-1721`), descriptor에서 받는 operation ID(`server-state.ts:294-313`, 1103/16-05로 brand 타입), UNKNOWN 동안 identity lease(`application-query.ts:689-693`)가 그대로 있고 해당 테스트가 게이트에서 통과했다. + +**고친 커밋이 검사를 약하게 만들었는가(관점 10·21).** `git diff 8a44226..bbde570`의 영역 테스트 11파일을 봤다(+835/−21). 지운 줄 21개는 셋이다. ① operation ID 문자열 → `testMutationOperationId(...)`(1103/16-05의 brand 타입). 값은 같다. ② `form-foundation.test.tsx`의 선언 목록 `["WORKLOG_INVALID"]` → `["WORKLOG_INVALID", "POSTER_ALREADY_EXISTS"]`(넓힌 것). ③ pin 스키마의 `tables`에 `backendExcerpt`가 더해졌다(1105/07-01). 새 `.skip`·`.todo`·`skipIf`·시간 상한 상향은 없다(`git diff ... | grep`). `async-surface.test.tsx:63-75`의 입력 변경은 의도한 동작 변경에 맞춘 것이고 버튼 단언은 그대로다. 제거 fixture가 문서를 읽는 테스트를 파일째 빼는 목록에 pin 테스트가 들어간 것(`scripts/lib/removal-fixture.ts:70-82`)은 검사 범위를 줄였다. 12 영역이 1106/12-01로 셌다. 여기서는 세지 않는다. **이 영역에서 약해진 검사는 찾지 못했다.** + +## 3. 이번 발견 (36.3) + +새 발견 3건: Medium 1 · Low 2 / P2 1 · P3 2 / 확인된 결함 2 · 개선 제안 1. High 이상과 P1은 없다. + +| ID | 심각도 | 우선순위 | 성격 | 관련 관점 | 제목 | +|---|---|---|---|---|---| +| 03-01 | Medium | P2 | 확인된 결함 | 6, 12, 28, 17, 10, 5 | KEYED 결과 불명의 같은 키 재전송이 쓰기 전 거절(429·503 `RATE_LIMIT_*`)이나 보내기 전 실패로 끝나면 훅이 결과 불명과 키를 버린다. 다음 저장은 새 키다 | +| 03-02 | Low | P3 | 확인된 결함 | 17, 23, 10, 5 | 계약 6.1절은 rate-limit 503에 "자동 재전송은 없다"고 적지만 IDEMPOTENT 쓰기는 `retryBudget` 안에서 다시 보낸다. 그 경로의 테스트가 없다 | +| 03-03 | Low | P3 | 개선 제안 | 28, 23, 22, 24, 12 | 0929/03-03의 두 가드가 키 유무로만 갈라서, IDEMPOTENT 쓰기도 결과 불명 뒤 재전송 버튼과 같은 입력 재제출이 막힌다 | + +### 03-01 KEYED 결과 불명의 같은 키 재전송이 쓰기 전 거절이나 보내기 전 실패로 끝나면 훅이 결과 불명과 키를 버린다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(코드 확인 + 실험 03-R1 재현) | +| 관련 관점 | 6, 12, 28, 17, 10, 5 | +| 근거 | **훅.** 같은 키 재전송(`resendUnknownEffect`)과 같은 입력 재저장은 같은 `submit`으로 간다(`application-query.ts:822-826`). `submit`은 결과 불명 admission을 찾으면 보내기 전에 그것을 정리한다(`:564-567`, `:599-604`). 새 admission이 그 intent와 키를 그대로 쓴다(`:613-615`). 결과가 `MAYBE_APPLIED`면 새 admission이 다시 UNKNOWN이 되어 키가 남는다(`:684-698`). 그러나 `NOT_APPLIED`나 `NOT_STARTED`면 그냥 정리한다(`:667-672`). 이번 시도의 판정을 그 논리 요청 전체의 판정으로 쓴다. 실행기는 한 실행 안의 시도들에 대해서는 "앞 시도보다 낮게 보고하지 않는다"를 지킨다(`http-execution-v3.ts:589-618`, `:1143-1155`). 훅의 재전송은 새 실행이라 그 규칙 밖이다. **쓰기 전 거절이 재전송에 오는 길.** (a) 503 `RATE_LIMIT_UNAVAILABLE`·`RATE_LIMIT_INCOMPATIBLE`: 1105/03-02 뒤 표가 `NOT_APPLIED`로 정한다(`backend-envelope.ts:177-181`, `:357`). KEYED는 이 답에 자동 재전송이 없다(`tests/integration/http-execution-v3-envelope.test.ts:956-970`). 백엔드는 이 503을 멱등성 executor보다 앞인 interceptor에서 낸다(`RateLimitInterceptor.java:31-42`, 모든 경로 `RateLimitWebConfig.java:61-62`). 그래서 첫 요청이 적용됐어도 같은 키 재전송이 이 답을 받을 수 있다. (b) 429·401·403: 생성 쓰기의 `classifyStatus`가 `NOT_APPLIED`다(`scripts/create-feature-write-slice.ts:305-309`). 1105/03-02 전부터 있던 길이다. 401은 세션이 만료된 뒤 재전송할 때 온다. (c) 보내기 전 거절(`NOT_STARTED`). 실행기에서 이 값은 보내기 전 검사에서만 나온다. scope fence, intent·입력 검사, 자격 증명 확인 실패다(`http-execution-v3.ts:752-869`). 오프라인 검사는 없다. **폼과 생성 페이지.** 폼은 `action: "retry"`인 실패에서 보관한 제출을 지우고 `retry-later`가 된다(`use-app-form.ts:305-314`). 그 뒤에는 저장이 열린다(`:386`). 생성 페이지는 `retry-later`의 실패 상태에 "다시 시도"를 달고 그것이 `form.submitForm()`이다(`create-feature-write-slice.ts:716-719`). 결과 불명이 풀렸으므로 훅은 새 intent와 새 키를 만든다(`application-query.ts:613-619`). **계약.** 백엔드 §2는 처리 중 409와 503 `IDEMPOTENCY_COMPLETION_UNKNOWN`에 "새 키 금지"를 적는다(`45d2a478:docs/web/http-contract.md:89`, `:112`). 런북 6.3-4도 "`UNKNOWN` effect에 새 key를 생성해 retry하지 않는다"고 적는다(`api-contract-and-server-state-recovery.md:254`). 이 길을 보는 테스트는 없다. 재전송 테스트는 모두 `MAYBE_APPLIED`나 성공으로 끝난다(`application-mutation-admission.test.tsx:451-650`, `tests/component/application-query.test.tsx`에도 없음). **실험 03-R1**(`R5-03-R1.log`, 5/5 통과). 훅에서 첫 요청을 결과 불명으로 만들고, 같은 키로 재전송한 뒤, 같은 입력으로 다시 저장했다. 재전송 결과가 503 `RATE_LIMIT_UNAVAILABLE`(X1), 429(X2), `NOT_STARTED`(X3)이면 셋 다 재전송 뒤 `indicator=null`, `canResend=false`이고 `keys=["key-1","key-1","key-2"]`다. 대조 X4(재전송도 `MAYBE_APPLIED`)는 `indicator="mutation-effect-unknown"`이고 `keys=["key-1","key-1","key-1"]`다. X5는 실제 실행기·바인딩·폼을 쓴 KEYED Envelope create다. 첫 저장의 답을 잃으면 `effect-unknown`이다. 재전송이 503 `RATE_LIMIT_UNAVAILABLE`을 받으면 `retry-later`가 되고 결과 불명 표시가 사라진다. 다시 저장하면 `success`로 끝난다. fetch는 3회, 키는 `["key-1","key-1","key-2"]`다 | +| 발생 조건 | KEYED 쓰기(`create:feature --with-create --keyed`, 백엔드 create도 KEYED). 첫 요청의 답이 사라지거나 결과 불명 답(503 `IDEMPOTENCY_COMPLETION_UNKNOWN` 등)이 온다. 사용자가 재전송했는데 그 시점에 rate limit이 429를 주거나, rate-limit 저장소가 응답하지 않거나(503), 세션이 만료돼 401이 온다. 사용자가 "다시 시도"나 저장을 누른다. rate limit은 백엔드 기본이 꺼져 있다(`45d2a478:src/sample-portfolio/src/main/resources/application.yml:176`). 멱등성 저장소와 rate limit을 모두 Redis로 쓰는 구성(`RedisIdempotencyStoreAdapter.java`)에서는 Redis 장애 하나가 `COMPLETION_UNKNOWN`(첫 요청은 실행됐다)과 재전송의 503 `RATE_LIMIT_UNAVAILABLE`을 함께 만든다(추론, 실행 확인 안 함) | +| 영향 | 첫 요청이 적용됐으면 같은 항목이 둘 생긴다. 화면은 결과 불명 대신 "잠시 뒤 다시 시도"를 보이므로 사용자는 확인 없이 다시 보낸다. 가이드 35.2의 High 예시(결과 불명 작업의 무방비 재실행)와 같은 모양이다 | +| 심각도·우선순위 | Medium · P2 — 피해는 중복 생성이지만 조건이 겹쳐야 한다. 현실적인 계기는 opt-in rate limit(429, 503 `RATE_LIMIT_*`)이나 만료된 세션(401)이다. KEYED도 opt-in이다. 답을 잃은 뒤 재전송하는 그 시점에 이 거절이 와야 한다. 0929/03-03(High)은 저장을 한 번 더 누르는 것만으로 닿았다. 그보다 훨씬 드물다. 템플릿 기본(NEVER, rate limit 꺼짐)은 닿지 않는다. 다만 템플릿 자신의 생성 KEYED 페이지가 이 길을 연다. 오케스트레이터도 코드를 다시 읽고 같은 등급으로 봤다. 03-R1에서 다른 길은 나오지 않았다 | +| 통제·증거 | 재전송 결과를 그 논리 요청의 앞선 결과와 합치는 통제: M0(훅 `:667-672`에 없음, 경로 확인) · E1(코드), E2(실험 03-R1) | +| 확실성과 남은 가정 | 훅·폼의 분기는 코드와 실험으로 확정이다. 생성 페이지의 "다시 시도" 연결은 코드로 확인했다(실험 X5는 그 버튼 대신 Submit을 눌렀다). 실제 백엔드에서 재전송이 rate-limit 거절을 받는 빈도는 확인하지 않았다. 0929/03-03의 같은 입력 가드는 키 없는 intent만 막으므로 이 길과 상관없다 | +| 결정의 근거 | `[사실]` 훅 주석은 재전송이 "이제 결과를 갖는다"고 적는다(`application-query.ts:600-601`). `[사실]` 런북 6.3-6은 "`NOT_APPLIED`가 증명된 경우만 retry"라고 적는다(`api-contract-and-server-state-recovery.md:267-268`). 재전송의 `NOT_APPLIED`는 그 시도만 증명한다. `[추론]` 1105/03-02의 최소 개선(지난 03 문서 3절)과 그 커밋은 KEYED 자동 재전송만 봤고, 사용자가 일으키는 재전송의 결과는 보지 않았다 | +| 이해 비용 | KEYED 화면을 만드는 사람은 "재전송이 적용 안 됨으로 끝나면 결과 불명이 풀린다"를 코드에서만 알 수 있다. 매뉴얼과 런북은 반대로 적는다("결과를 모를 때 새 키로 다시 보내면 안 된다", `docs/manual/02-decision-tables.md:95`, 런북 6.3-4) | +| 최소 개선 방향 | 훅에서, 결과 불명 intent를 다시 쓴 시도가 `NOT_APPLIED`나 `NOT_STARTED`로 끝나면 admission을 UNKNOWN으로 되돌리고 그 intent를 남긴다. 실패는 그대로 돌려준다. 그러면 폼은 `retry-later`를 보이더라도 다음 저장이 같은 키로 간다. 폼은 `unknownSubmissionRef`를 지우지 않거나, 훅 상태(`mutation-effect-unknown`)를 보고 저장을 막는다 | +| 대안 비교 | (a) 훅에서 되돌리기(위): 한 곳, 모든 화면에 적용. (b) 표에서 rate-limit 503을 다시 `MAYBE_APPLIED`로: 503의 길만 막고 429·401·`NOT_STARTED`는 남는다. 1105/03-02의 이득(NEVER 생성 쓰기의 거짓 결과 불명 제거)도 잃는다. (c) 생성 페이지의 "다시 시도"를 결과 불명 뒤에는 `resendUnknown`으로 잇기: 생성 기능만 고친다. (a)는 한 곳만 고치고 모든 화면을 덮는다 | +| 단순화의 보존 조건 | 처음 보내는 요청의 `NOT_APPLIED`는 지금처럼 정리된다(다음 저장은 새 키, 1103/03-01). 재전송이 성공·`APPLIED_CONFIRMED`면 지금처럼 정리된다. KEYED 503 `IDEMPOTENCY_UNAVAILABLE` 자동 재전송은 그대로다 | +| 비용·부작용 | 훅 분기 몇 줄과 테스트 둘(훅, 폼). 재전송이 429로 막힌 동안 결과 불명 화면이 남는다. 그때 화면에 "잠시 뒤 같은 요청으로 다시 보내기"를 보여야 한다(문구 하나) | +| 재검토 조건 | 백엔드가 rate limit을 멱등성 판정 뒤로 옮기거나, 같은 키 요청을 rate limit에서 빼면 (a)의 503 부분은 필요 없다. 429·`NOT_STARTED`는 남는다 | +| 완료 기준 | 03-R1 X1~X3에서 재전송 뒤 상태가 `mutation-effect-unknown`이고 `keys`가 `["key-1","key-1","key-1"]`이다. X5에서 세 번째 요청의 키가 `key-1`이거나 세 번째 요청이 나가지 않는다 | +| 검증 방법 | `application-mutation-admission.test.tsx`의 "unknown-effect replay (D-1)" 묶음에 `it.each` 1건(재전송 결과 `NOT_APPLIED`·`NOT_STARTED`). `form-foundation.test.tsx`의 KEYED Envelope 폼에 1건(답 유실 → 재전송 503 `RATE_LIMIT_UNAVAILABLE` → 저장 → 키) | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 재검증 결과 | `bbde570`, 03-R1: X1~X3·X5에서 결함이 재현됐다(위 근거). 수정 뒤 같은 실험의 X1~X3·X5 키가 모두 `key-1`이어야 한다 | + +### 03-02 계약 6.1절은 rate-limit 503에 "자동 재전송은 없다"고 적지만 IDEMPOTENT 쓰기는 `retryBudget` 안에서 다시 보낸다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(문서와 코드 불일치) | +| 관련 관점 | 17, 23, 10, 5 | +| 근거 | 계약 6.1절: "자동 재전송은 없다(KEYED도 같다)"(`backend-api-and-server-state-contract.md:342`). 코드: 표가 `NOT_APPLIED`로 정하면(`backend-envelope.ts:177-181`) `retryHint`는 503의 재시도 status 여부다(`http-execution-v3.ts:1786`, `http-retry-lifecycle.ts:4-6`). 실행기는 `NOT_APPLIED`이고 `SAFE`·`IDEMPOTENT`면 `retryBudget` 안에서 다시 보낸다(`http-execution-v3.ts:1116-1138`, `http-retry-lifecycle.ts:32-34`). 쓰기의 `IDEMPOTENT`는 조립이 받고 `retryBudget > 0`도 막지 않는다(`external-contract-runtime.ts:575-582`, `:610-615`). CHANGELOG와 커밋은 코드와 같다. "IDEMPOTENT 쓰기는 `retryBudget` 안에서 다시 보낸다"(`CHANGELOG.md:61`, `c6c37f3` 본문 "위험·한계"). 503 `RATE_LIMIT_INCOMPATIBLE`은 백엔드가 `retryable: false`로 보내지만(`RateLimitTransportError.java:9`) 실행기는 status로 판단해 다시 보낸다(같은 본문). 이 경로를 보는 테스트가 없다. 통합 테스트는 KEYED의 무재전송만 본다(`http-execution-v3-envelope.test.ts:956-970`) | +| 발생 조건 | 손으로 쓴 IDEMPOTENT Envelope 쓰기(PUT·DELETE)에 `retryBudget`을 1 이상 준다. 템플릿 안에는 IDEMPOTENT 쓰기가 없다(생성 쓰기는 NEVER·KEYED, `create-feature-write-slice.ts:25`) | +| 영향 | 6.1절을 읽은 작성자는 이 503에서 요청이 한 번만 나간다고 본다. 실제로는 `Retry-After`(5초 이하, `http-retry-lifecycle.ts:54-67`) 뒤 한 번 더 나간다. 쓰기 전 거절이라 중복은 없다. `INCOMPATIBLE`은 같은 답을 한 번 더 받는다 | +| 심각도·우선순위 | Low · P3 — 문서 한 줄의 불일치. 데이터 피해 없음 | +| 통제·증거 | 6.1절 문장과 실행기 동작을 맞추는 통제: M0(문서와 코드를 대조하는 검사 없음, 테스트 없음) · E1(코드·문서 대조) | +| 확실성과 남은 가정 | 코드 경로는 확정이다. 실행으로 재현하지 않았다(E1) | +| 결정의 근거 | 적용 제외 — 문서가 코드와 CHANGELOG를 따라가면 되는 문제다 | +| 이해 비용 | IDEMPOTENT 쓰기 작성자가 계약 문서, CHANGELOG, 실행기 셋을 맞춰 읽어야 안다 | +| 최소 개선 방향 | 6.1절 문장을 "KEYED·NEVER는 자동 재전송이 없다. IDEMPOTENT 쓰기는 `retryBudget` 안에서 `Retry-After` 뒤 다시 보낸다"로 고친다. `INCOMPATIBLE`을 다시 보내지 않으려면 표에 "재시도 안 함"을 싣는다(선택) | +| 대안 비교 | 적용 제외 — 문서 정정이다. `INCOMPATIBLE` 재시도를 막는 것은 별도 선택이다 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 문서 1줄, 통합 테스트 1건(IDEMPOTENT PUT, `retryBudget: 1`, 503 → 200, fetch 2회) | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | 6.1절과 `CHANGELOG.md:61`이 같은 동작을 적고, 그 동작을 테스트 하나가 고정한다 | +| 검증 방법 | `http-execution-v3-envelope.test.ts`에 IDEMPOTENT 1건 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 03-03 0929/03-03의 두 가드가 키 유무로만 갈라서, IDEMPOTENT 쓰기도 결과 불명 뒤 재전송과 같은 입력 재제출이 막힌다 + +| 필드 | 내용 | +|---|---| +| 성격 | 개선 제안 | +| 관련 관점 | 28, 23, 22, 24, 12 | +| 근거 | 뮤테이션 정책은 키 여부만 받는다. `commandMutationIdentity`가 `requiresIdempotencyKey: retrySemantics === "KEYED"`를 준다(`src/contracts/server-state.ts:309-312`). IDEMPOTENT 쓰기의 intent에는 키가 없다(`src/adapters/platform/browser-mutation-intent-factory.ts:38`). 재전송 버튼은 키가 있을 때만이다(`application-query.ts:853-867`, `async-surface.tsx:227-229`). 0929/03-03 수정(`683ccfb`)으로 같은 입력 재제출도 키가 없으면 거절된다(`application-query.ts:574-583`). 그 테스트가 쓰는 `keyed: false`가 IDEMPOTENT 정책과 같은 입력이다(`application-mutation-admission.test.tsx:563-583`, FE-GATE-006 통과). 그러나 매뉴얼은 IDEMPOTENT를 "같은 요청을 여러 번 적용해도 결과가 같다", 자동 재시도 "된다"로 적는다(`docs/manual/02-decision-tables.md:87-90`). 실행기도 IDEMPOTENT 쓰기를 보낸 뒤에도 다시 보낸다(`http-retry-lifecycle.ts:32-34`). 문서는 가드를 NEVER로만 설명한다(`docs/manual/01-add-a-feature.md:515`, 런북 `api-contract-and-server-state-recovery.md:259`, `CHANGELOG.md:66` "키 없는(`NEVER`)") | +| 발생 조건 | IDEMPOTENT 쓰기(손으로 쓴 PUT·DELETE)의 답이 사라지거나 `MAYBE_APPLIED` 답이 와서 재시도 예산이 끝난다 | +| 영향 | 다시 보내도 안전한 요청인데 화면에 재전송이 없고, 같은 입력 저장은 `UNKNOWN_EFFECT_PENDING`으로 거절된다. 출구는 "변경됨으로 확인"(사실을 모르는 확인)이나 새로고침이다. 확인은 캐시를 새로 읽으므로 데이터 피해는 없다 | +| 심각도·우선순위 | Low · P3 — 회복 경로가 불편하고 문구가 사실과 다르다. 안전 쪽으로 실패한다. 템플릿 안에는 소비자가 없다(다운스트림 확장 지점) | +| 통제·증거 | 키 기준 가드: M3(테스트가 고정, 03-R2·R3에서 검출) / "재전송이 안전한가"로 가르는 규칙: M0(정책에 그 값이 없다) · E1(코드), E2(FE-GATE-006의 `keyed: false` 테스트가 IDEMPOTENT 정책과 같은 입력으로 통과) | +| 확실성과 남은 가정 | 코드로 확정이다. 다운스트림에 IDEMPOTENT 쓰기가 있는지는 보지 않았다 | +| 결정의 근거 | `[사실]` 가드의 이유는 "키 없이는 서버가 두 번째 요청을 가려내지 못한다"이다(`application-query.ts:569-573`). IDEMPOTENT는 가려낼 필요가 없는 경우다. `[추론]` 정책이 `retrySemantics`를 싣지 않아 훅이 NEVER와 IDEMPOTENT를 가를 수 없다 | +| 이해 비용 | IDEMPOTENT를 고른 작성자는 결과 불명 화면이 NEVER와 같다는 것을 코드에서만 안다 | +| 최소 개선 방향 | `commandMutationIdentity`가 "같은 요청 재전송이 안전함"(KEYED 또는 IDEMPOTENT)을 함께 준다. 가드 둘(`canResend`, 같은 입력 거절)이 키 대신 그 값을 본다. 또는 현상을 유지하고 문서 셋에 "IDEMPOTENT도 NEVER처럼 다룬다"를 적는다 | +| 대안 비교 | (a) 정책에 재전송 안전 여부 추가: 정책 타입 칸 하나, 가드 두 줄. (b) 문서만: 비용 0, 회복 경로는 그대로 불편. (c) IDEMPOTENT에도 키를 붙인다: 백엔드가 키를 읽지 않으면 의미가 없다 | +| 단순화의 보존 조건 | NEVER의 재전송 금지와 같은 입력 거절은 그대로다 | +| 비용·부작용 | (a)면 `BoundMutation`에 선택 칸 하나(추가만) | +| 재검토 조건 | 템플릿이나 다운스트림에 IDEMPOTENT 쓰기가 생길 때 | +| 완료 기준 | IDEMPOTENT 정책의 결과 불명에서 재전송 버튼이 그려지고, 같은 입력 저장이 보내진다. NEVER는 지금처럼 막힌다 | +| 검증 방법 | `application-mutation-admission.test.tsx`에 IDEMPOTENT 정책 1건 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +**다른 영역에 넘기는 관찰(세지 않음).** +- 14 영역: CHANGELOG의 0929/03-03 행은 "손으로 만든 결과 불명 상태를 넘기던 화면은 버튼이 사라진다"고 적지만(`CHANGELOG.md:66`) BREAKING 표시와 "먼저 할 일" 단계가 없다. 그런 화면은 타입 오류도 테스트 실패도 없이 버튼을 잃는다. 고치는 법은 코디네이터의 `state`를 넘기는 것이다(`683ccfb` 본문). +- 01 영역: Fileserver client도 V3 표로 503 `RATE_LIMIT_*`를 `NOT_APPLIED`로 읽는다(01 문서). 03-01과 같은 재전송 정리 문제가 업로드 재시도 경로에 있는지는 01이 본다. + +## 4. 28개 관점 판정 (36.2) + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역. 굵은 번호는 깊게 본 관점이다. + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +|---|---|---|---|---|---| +| 1 | 코드 성숙도 | 적용 | M2 / M2 | E1 | P — 백엔드 판정은 `backend-envelope.ts` 한 곳, 플랫폼 code 목록은 조립 검사가 쓰는 `external-contract-runtime.ts`에 있다(`:627-663`). 둘을 테스트가 묶는다. 훅이 재전송 결과를 논리 요청의 결과로 쓴다(03-01) | +| 2 | 구조적 성숙도 | 다른 영역 | — | 게이트 | > 12·16 영역. FE-GATE-010 rc=0 | +| 3 | 변경 용이성 | 적용 | M3 / M3 | E2(03-R6) | P — 6.1절 표에 플랫폼 행을 더하면 목록도 고쳐야 하고 pin 테스트가 알린다(`backend-contract-pin.test.ts:293-302`, 03-R6에서 `DB_R05_PROBE` 행을 잡음) | +| 4 | 인지 부하 | 적용 | M1 / M1 | E1 | P — 판정 순서(표 → 선언 → 분류기 → 폼)와 재전송 결과 처리(03-01)를 알아야 한다 | +| **5** | 위험 가시성 | 적용 | M3 / M3 | E1 | P — 플랫폼 code를 선언하면 6.1절을 이유로 부팅이 멈춘다(1105/03-01). 재전송이 거절되면 결과 불명이 조용히 풀린다(03-01) | +| **6** | 실패 성숙도 | 적용 | M4 / M3 | E2(게이트, 변이 6개 검출, 실험 03-R1) | P — 플랫폼 code 선언 거절, rate-limit 503 판정, 키 없는 재제출 거절이 들어왔다. 남은 것: KEYED 재전송의 쓰기 전 거절 뒤 새 키(03-01) | +| 7 | 운영 성숙도 | 적용 | M2 / M2 | E2 | P — `effect_certainty`·`reason` 진단은 그대로다. 진단 sink는 메모리 버퍼뿐이다 | +| 8 | 디버깅 가능성 | 적용 | M2 / M2 | E2 | O — 조립 거절 문구가 code와 6.1절을 적는다(`external-contract-runtime.ts:693`) | +| 9 | 유지보수 성숙도 | 적용 | M3 / M3 | E2 | P — 답 표 9행이 사본·프론트 표와 양방향으로 묶인다. 백엔드 HEAD가 pin보다 두 커밋 앞이지만 6.1절 판정은 같다(1절). 사본과 백엔드 문서의 일치는 게이트 밖이다(07 영역) | +| **10** | 테스트 성숙도 | 적용 | M3 / M3 | E2(03-R2~R7) | P — 수정마다 테스트가 있고 게이트에서 통과한다. 규칙을 깨는 변이 6개가 모두 기대한 테스트에서 실패했다(03-R2~R7, 합 19건). 빈틈: 재전송이 `NOT_APPLIED`·`NOT_STARTED`로 끝나는 경우(03-01, 실험 03-R1이 그 동작을 보였다), IDEMPOTENT 쓰기의 rate-limit 503 재시도(03-02) | +| 11 | 데이터 성숙도 | 적용 제외 | — | — | - 영속 데이터 없음. 메모리 캐시와 intent뿐이다 | +| **12** | 동시성 성숙도 | 적용 | M3 / M2 | E2 | P — 키 없는 같은 입력 재제출은 훅이 막는다(0929/03-03 고쳐짐). 한 논리 요청의 여러 시도 사이에서 확실성을 합치지 않는다(03-01) | +| 13 | 확장성 | 다른 영역 | — | — | > 11·15 영역 | +| 14 | 성능 성숙도 | 다른 영역 | — | — | > 15 영역. 1105/03-01 검사가 초기 JS를 327 B 늘렸다(지난 README §16.2 D7) | +| 15 | 보안 성숙도 | 적용 | M4 / M3 | E2 | O — 쿠키 쓰기 CSRF 조립 검사, `redirect: "error"` 등 그대로. 0929/03-02는 19번 | +| 16 | 의존성 성숙도 | 다른 영역 | — | — | > 13 영역 | +| **17** | API / Contract | 적용 | M3 / M3 | E2 | P — §2 답 전부와 §4 503 셋을 읽는다. 6.1절 문장 하나가 코드와 다르다(03-02). 03-01의 길에서 §2 "새 키 금지"를 어긴다. bulk 미지원(1103/03-02) | +| 18 | 배포 성숙도 | 다른 영역 | — | — | > 13 영역 | +| 19 | 설정 성숙도 | 적용 | M2 / M1 | E1 | P — 교차 origin 헤더 허용은 문서뿐이다(0929/03-02) | +| 20 | 개발자 경험 | 적용 | M3 / M2 | E2 | P — 조립 거절 문구가 고치는 법을 적는다(오류 표 `errors.md:106`). 백엔드 목록 GET이 없다(1103/03-07) | +| **21** | Guardrail 성숙도 | 적용 | M4 / M4 | E2(03-R4~R6) | O — 조립이 쓰기 `SAFE`, 읽기 `KEYED`·`NEVER`, 멱등성 code, 6.1절 "쓰기 뒤 가능" 플랫폼 code, Envelope 없는 목록을 거절한다. 업무 code 선언은 설계상 작성자 판단이다 | +| 22 | 추상화 성숙도 | 적용 | M2 / M2 | E1 | P — kind와 effect가 두 함수에서 정해진다(1101/03-04). 정책이 키 여부만 실어 훅이 NEVER와 IDEMPOTENT를 가를 수 없다(03-03) | +| **23** | 일관성 | 적용 | M2 / M2 | E1 | P — 실행기는 IDEMPOTENT 쓰기를 다시 보내지만 훅은 NEVER처럼 막는다(03-03). 6.1절과 CHANGELOG가 rate-limit 503 재시도를 다르게 적는다(03-02) | +| 24 | 네이밍 / 의미 | 적용 | M1 / M1 | E1 | P — NEVER·IDEMPOTENT 결과 불명의 출구가 "변경됨으로 확인" 하나다(03-03) | +| 25 | 조직 확장성 | 다른 영역 | — | — | > 14 영역 | +| 26 | Ownership | 적용 | M2 / M2 | E1 | P — pin이 담당과 대조 날짜를 적는다(`backend-contract-pin.json:51-52`). 백엔드로 넘긴 rate-limit 비동기 재디스패치 요청은 백엔드 담당 몫이다 | +| 27 | 삭제 가능성 | 적용 | M3 / M2 | E1 | O — 소비자 0인 `projectCertaintyToUi`는 배럴 밖이다(결함 아님, 지난 판정 그대로) | +| **28** | 회복 가능성 | 적용 | M3 / M2 | E2 | P — 선언한 업무 거절 뒤 고쳐서 저장한다. KEYED 결과 불명의 재전송이 쓰기 전 거절로 끝나면 회복 경로가 새 키로 바뀐다(03-01). IDEMPOTENT 결과 불명은 확인이나 새로고침뿐이다(03-03) | + +X(미충족)는 없다. + +## 5. 미검증 + +| 무엇을 | 왜 확인하지 못했나 | 무엇이 있으면 확인할 수 있나 | +|---|---|---| +| 03-01에서 생성 KEYED 페이지의 "다시 시도" 버튼을 실제로 눌렀을 때 | 03-R1 X5는 손으로 만든 폼에서 Submit을 눌렀다. 생성 페이지의 버튼 연결(`create-feature-write-slice.ts:716-719`)은 코드로만 봤다 | `create:feature x --with-create --keyed` 뒤 생성 페이지 테스트에 같은 시나리오 1건 | +| 03-02의 IDEMPOTENT 재시도 | 실행으로 재현하지 않았다(E1) | IDEMPOTENT PUT 통합 테스트 1건 | +| 짝 백엔드와의 실제 통합(rate limit 켠 상태에서 재전송) | 백엔드는 읽기만 했다 | 백엔드를 rate limit·KEYED create로 띄우고 Redis를 멈춰 재전송 | +| Spring MVC가 ASYNC 재디스패치에서 `preHandle`을 다시 부르는지 | 코드 실행 없이 문서·추론만 있다(계약 6.1 `:342-346`) | 백엔드 비동기 쓰기 컨트롤러로 실험(백엔드 몫) | +| 다운스트림(tech-log·memento)에 KEYED·IDEMPOTENT 쓰기나 손으로 만든 `AsyncState`가 있는지 | 다운스트림 repo를 읽지 않았다 | 두 repo에서 `retrySemantics`, `AsyncSurface` grep | +| `browser-rpc`·`auth`·`diagnostics`·`telemetry`의 세부 동작 | `8a44226` 뒤 변경이 없다. 게이트 통과만 확인했다 | 지난 라운드 변이를 다시 돌리기 | + +## 6. 실행 기록 + +| 이름 | 명령 | 변이 | rc | 결과 | +|---|---|---|---|---| +| 게이트(인용, 대조군) | FE-GATE-005·006·007·020, CI env, 메인 세션 2026-11-06 03:24~03:56 | — | 0 | `bbde570-ci/summary.txt`. 대상 파일 통과: `external-contract-runtime` 47, `backend-envelope` 37, `backend-contract-pin` 15, `create-feature` 46, `backend-contract-drift` 9(FE-GATE-005), `application-mutation-admission` 19, `async-surface` 35, `form-foundation` 34, `application-query` 28(FE-GATE-006), `http-execution-v3-envelope` 60, `http-execution-v3-observability` 11(FE-GATE-007). FE-GATE-020의 생성 기능 테스트 "shows the backend's refusal of the name on the field and saves again", "keeps a create whose response was lost unknown and offers no resend" 통과(`gate-artifacts/FE-GATE-020.txt` 1993행, 2187~2188행) | +| 03-R1 | `node scripts/run-vitest.ts run tests/component/r05-03-experiments.test.tsx` · local | `03-patches/03-R1-experiments.diff`(실험 파일 추가만) | vitest-rc=0 | 5/5 통과. X1 503 `RATE_LIMIT_UNAVAILABLE`, X2 429, X3 `NOT_STARTED`: 재전송 뒤 `indicator=null`, `canResend=false`, `keys=["key-1","key-1","key-2"]`. X4(대조, 재전송 `MAYBE_APPLIED`): `indicator="mutation-effect-unknown"`, `keys=["key-1","key-1","key-1"]`. X5(폼·실제 실행기): `effect-unknown`(fetch 1) → `retry-later`, 결과 불명 표시 없음(fetch 2) → `success`(fetch 3), `keys=["key-1","key-1","key-2"]`. 기대와 같다. 결함 재현 | +| 03-R2 | `... run tests/component/application-mutation-admission.test.tsx` · local | `03-patches/03-R2.diff`(키 없는 재제출 가드 삭제) | vitest-rc=1 | 1 failed / 18 passed: "refuses to send a keyless unknown request again for the same input"(`expected { ok: true, value: 'keyless-input' } to match object { ok: false, ... }`). 기대와 같다 | +| 03-R3 | `... run tests/component/async-surface.test.tsx` · local | `03-patches/03-R3.diff`(`=== true` → `!== false`) | vitest-rc=1 | 1 failed / 34 passed: "draws no resend for an unknown state that does not say it can be resent". 기대와 같다 | +| 03-R4 | `... run tests/unit/external-contract-runtime.test.ts` · local | `03-patches/03-R4.diff`(조립의 플랫폼 code 검사 삭제) | vitest-rc=1 | 4 failed / 43 passed: "refuses to declare the platform code `BAD_PARAMETER`·`MAPPING_FAILED`·`DB_UNIQUE_VIOLATION`·`LOCK_ACQUISITION_TIMEOUT` ..."(`Expected contract composition to fail.`). 기대와 같다 | +| 03-R5 | `... run tests/unit/backend-envelope.test.ts` · local | `03-patches/03-R5.diff`(실행기 fail-close 줄 삭제) | vitest-rc=1 | 5 failed / 32 passed: "keeps a declared platform code 400 `BAD_PARAMETER` / 400 `MAPPING_FAILED` / 409 `DB_UNIQUE_VIOLATION` / 409 `LOCK_ACQUISITION_TIMEOUT` / 422 `INTEGRITY_MISMATCH` maybe applied"(`expected 'NOT_APPLIED' to be 'MAYBE_APPLIED'`). 기대와 같다 | +| 03-R6 | `... run tests/unit/backend-contract-pin.test.ts` · local | `03-patches/03-R6.diff`(6.1절 표에 "쓰기 뒤 가능" 플랫폼 행 추가) | vitest-rc=1 | 1 failed / 14 passed: "are the 6.1 table's possibly-after-write codes outside the feature-decided rows", diff `- "DB_R05_PROBE"`. 기대와 같다 | +| 03-R7 | `... run tests/unit/backend-envelope.test.ts tests/unit/backend-contract-pin.test.ts tests/integration/http-execution-v3-envelope.test.ts` · local | `03-patches/03-R7.diff`(거절 표의 rate-limit 두 행 삭제) | vitest-rc=1 | 7 failed / 105 passed (112): 단위 "reads the edge's 503 %s as refused before the write" 2, pin "reads the backend's 503 `RATE_LIMIT_UNAVAILABLE`/`RATE_LIMIT_INCOMPATIBLE` as its table says" 2, 통합 "reads the edge's 503 %s as not applied, whatever the package says" 2, 통합 KEYED "does not resend the edge's 503 `RATE_LIMIT_UNAVAILABLE` on its own" 1(`effect` `MAYBE_APPLIED`). 요청서는 6건을 기대했다. 마지막 1건은 요청서가 그 묶음의 분류기를 `NOT_APPLIED`로 잘못 읽은 것이다. 실제로는 `CREATE_CONTRACT`를 쓰고 그 분류기는 `MAYBE_APPLIED`다(`http-execution-v3-envelope.test.ts:142`, `:860-863`). 그래서 더 많이 잡혔다. 같은 규칙을 보는 테스트다 | + +패치 경로의 앞부분은 `/tmp/claude-1000/-home-donghyeon-workspace-desktop-server-git-clean-architecture-frontend-template--claude-worktrees-happy-easley-233d07/5b935f37-0052-476e-bf8e-dcb9a2640c1a/scratchpad/r5/requests/`다. 모두 노트북에서 `git apply --check`로 `bbde570`에 적용됨을 확인했다. 배치는 오케스트레이터가 local env로 하나씩 돌렸다. 로그는 `desktop:/tmp/claude-gates/r5/batch/out/R5-03-R1.log`~`R5-03-R7.log`다. 명령 끝의 `echo`로 항목 rc는 모두 0이다. 판정은 로그의 `vitest-rc=` 줄로 했다. 7건 모두 `restore=clean`. 변이 6개는 모두 검출됐다(합 19건 실패). 대조군(변이 없는 실행)은 위 게이트 로그로 갈음했다. + +## 7. 새 발견 요약 + +| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line | +|---|---|---|---|---| +| 03-01 | Medium·P2 | 확인된 결함 | KEYED 결과 불명의 같은 키 재전송이 429·503 `RATE_LIMIT_*`·보내기 전 실패로 끝나면 훅이 결과 불명과 키를 버리고, 생성 폼의 "다시 시도"가 새 키로 보낸다 | `src/presentation/adapters/query/application-query.ts:599-604`, `:667-672`; `src/presentation/forms/use-app-form.ts:305-314`; `scripts/create-feature-write-slice.ts:716-719`; `src/adapters/http/backend-envelope.ts:177-181` | +| 03-02 | Low·P3 | 확인된 결함 | 계약 6.1절은 rate-limit 503에 "자동 재전송 없음"이라 적지만 IDEMPOTENT 쓰기는 `retryBudget` 안에서 다시 보낸다. 테스트 없음 | `docs/architecture/backend-api-and-server-state-contract.md:342`; `src/adapters/http/http-execution-v3.ts:1116-1138`, `:1786`; `CHANGELOG.md:61` | +| 03-03 | Low·P3 | 개선 제안 | 키 유무로만 가르는 가드 둘 때문에 IDEMPOTENT 쓰기도 결과 불명 뒤 재전송·같은 입력 재제출이 막힌다 | `src/presentation/adapters/query/application-query.ts:574-583`, `:853-867`; `src/contracts/server-state.ts:309-312` | + +이월로 남은 것: 1103/03-01 일부(결정 대기), 1103/03-02 일부(결정 대기), 1103/03-07 일부(결정 대기), 1101/03-04 남음, 0929/03-02 남음. diff --git a/docs/reviews/2026-11-06-maturity-review/04-adapters-realtime.md b/docs/reviews/2026-11-06-maturity-review/04-adapters-realtime.md new file mode 100644 index 00000000..7438fe65 --- /dev/null +++ b/docs/reviews/2026-11-06-maturity-review/04-adapters-realtime.md @@ -0,0 +1,194 @@ +# 04 realtime 어댑터 성숙도 리뷰 + +> 검토일: 2026-11-06 · 기준: `bbde570` (PR B 끝, `fix/maturity-review-2026-11-05-b`) · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 경로: `src/adapters/realtime/`, `src/contracts/realtime-streams.ts`, `src/application/policies/bounded-polling.ts`, 설계 `docs/architecture/realtime-events-web-push-and-bounded-polling.md`, `VD-28`. 짝 백엔드 pin `45d2a478`(이 범위에서 바뀌지 않음, 읽기만) +> 깊게 본 관점: 6, 8, 10, 17, 21, 23 +> 렌즈: ① 1105 조치(`bde7fa4`, `05330e3`, `27e3dec`, `05880d1`, `1e576ef`)가 완료 기준까지 갔나 ② BREAKING `05330e3`의 코드가 커밋 footer와 CHANGELOG 안내(11-03 절 행 포함)와 맞나 ③ 조치가 검사를 약하게 하거나 새 결함을 만들었나 + +ID 표기: 이번 라운드 발견은 `04-01`부터 쓴다. 라운드 밖에서는 `1106/04-NN`이다. 지난 라운드는 `1105/04-NN`, 그 전은 `1103/04-NN`, `1101/04-NN`, `0929/04-NN`이다. + +**이 문서의 실행 증거.** 이 리뷰어는 아무것도 실행하지 않았다. 실행 증거는 오케스트레이터의 `bbde570` 게이트 로그(CI env)와 snapshot이다. 실험 두 건(04-R1, 04-R2)을 요청했다. 오케스트레이터가 desktop에서 하나씩 돌렸다(2026-11-06 04:32, env local, 부하 4.05·4.21, 항목마다 `bbde570`으로 되돌림 `restore=clean`). 로그: `desktop:/tmp/claude-gates/r5/batch/out/R5-04-R1.log`, `R5-04-R2.log`. + +**영역 판정 (35.8)** + +| 범위 | 판정 | 이유 | +| --- | --- | --- | +| codec·stream coordinator·WebSocket 연결·live↔Poll handoff·reconnect coordinator | 지정 범위에서 사용 가능 | 이 범위 src는 `8a44226..bbde570`에서 바뀌지 않았다. realtime 단위 테스트 14파일 272건이 게이트에서 통과했다(FE-GATE-005). 0929/04-01 규칙을 다시 막는 테스트 둘이 생겼고, 변이 MR1을 그 둘이 잡는다(1105/04-01, 04-R1) | +| reconnect coordinator + SSE | 조건부 사용 가능 | 조합 코드가 SSE session bridge와 EOF 분류를 직접 정해야 한다(0929/04-02). `retry:` 상한 규칙은 결정 대기다(0929/04-03). bridge가 던지면(설정 오류 포함) 서버 장애로 재시도된다(새 04-01, 04-R2) | +| bounded polling + V3 HTTP 실행기 | 조건부 사용 가능 | coordinator가 생성 때 검사한 descriptor를 `execute`에 넘긴다(1103/04-01). 던지는 `execute`는 이제 `PROTOCOL_MISMATCH`로 바로 끝난다(1105/04-02). 조건 둘: `execute`가 `input.operation`을 실행기에 넘기고, V3 결과 9종을 poll 결과로 직접 바꾼다. 대응표는 없다(새 04-02) | +| 짝 백엔드 템플릿과 realtime push를 그대로 연결 | 해당 용도의 사용 보류 | 바뀐 것이 없다. pin `45d2a478`이 그대로라 설계 0.1절 대응표가 유효하다. 길 선택은 제품 결정이다 | + +## 0. 결론 + +- 1105 새 발견 셋이 완료 기준까지 고쳐졌다. **1105/04-02**: 던지는 `execute`는 재시도 없이 `PROTOCOL_MISMATCH`(retryable 아님)로 끝난다(`bounded-poll-coordinator.ts:336-347`, `:395-399`). 정확 비교 테스트 셋이 게이트에서 통과했다(`bounded-poll-coordinator.test.ts:911-987`). **1105/04-03**: VD-28과 설계 3절이 V3 descriptor 규칙을 적는다. V2 칸 `git grep`은 0건이다. **1105/04-01**: 조합 transport의 `OFFLINE` 테스트 둘이 생겼다(`realtime-reconnect-coordinator.test.ts:2206`, `:2246`). 완료 기준인 변이 MR1을 다시 돌렸다. 그 두 건만 "expected 1 to be 3"으로 실패하고 나머지 270건은 통과했다(04-R1). +- **1103/04-01은 고쳐짐으로 본다.** README §16.6은 "일부"라 적는다. `27e3dec`가 생성 때 검사한 바로 그 객체를 `input.operation`으로 넘긴다(`bounded-poll-coordinator.ts:149-150`, `:322-328`). 그 객체가 매번 간다는 테스트가 통과했다(`:1208`). 원래 완료 기준("`retryBudget > 0` 거절, 같은 조합에서 poll 3회 = 요청 3회")은 지난 라운드부터 충족이다. 조합 코드가 `input.operation`을 무시하는 틈은 완료 기준 밖의 잔여 위험이다. 타입 주석·설계 9.2·CHANGELOG 알려진 제한이 적는다. +- **BREAKING `05330e3`의 코드는 footer와 CHANGELOG 안내와 맞는다.** 1105 절 "먼저 할 일" 4단계(`CHANGELOG.md:27`)와 [계약] 행(`:67`), 11-03 절 행(`:298`, `1e576ef`)이 같은 규칙을 적는다. 더 정확히 하면 던진 뒤에도 lease 상태 검사가 먼저 돈다(`bounded-poll-coordinator.ts:368-393`). 그사이 offline·hidden·scope 변경·close·시간 예산 소진이 있었으면 그 kind로 끝난다. footer의 "abort로 생긴 것 제외"와 같은 방향이라 불일치는 아니다. +- 검사를 약하게 한 조치는 없다(2.1절). `05330e3`이 지운 테스트는 동작 변경을 따른 것이고, 새 기대값은 호출 횟수·결과·관측 전체를 정확 비교한다. +- 새 발견 2건. **04-01**: reconnect coordinator는 던지는 `attempt`를 서버 장애(`PROVIDER_UNAVAILABLE`)로 재시도한다(`reconnect-coordinator.ts:766-774`). `05330e3` 뒤 poll은 같은 던짐을 조합 결함으로 끝낸다. repo의 SSE bridge 예는 `attempt` 안에서 연결을 만든다. 그래서 endpoint 설정 오류가 서버 장애와 예산 소진으로 보인다. 실험 04-R2에서 `http://` endpoint는 fetch 0회, attempt 3회, `PROVIDER_UNAVAILABLE`(EXHAUSTED)로 끝났다. **04-02**: 권하는 `input.operation`은 `InstalledHttpContract`이라 실행기 호출의 입력·출력 타입이 사라진다. V3 결과 9종 → poll 결과 대응표도 없다. repo의 유일한 V3 조합 예(테스트)는 SUCCESS 외 전부를 retryable `PROVIDER_UNAVAILABLE`로 바꾼다. +- 이월 둘(0929/04-02 SSE bridge·EOF, 0929/04-03 `retry:` 범위)은 남음이다. 결정 대기이고 코드 diff가 0줄이다. +- 이번 새 발견: **Low 2**, 모두 P3. High 이상·P1은 없다. + +## 1. 범위 (36.1) + +| 항목 | 기록 | +| --- | --- | +| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`. 짝 백엔드 `clean-architecture-backend-template`은 pin `45d2a478`(`config/contracts/backend-contract-pin.json:5`)이고 이 범위에서 그 줄은 바뀌지 않았다. 백엔드는 읽지 않았다(대응표 결론이 바뀔 입력이 없음) | +| 커밋·작업 상태·확인 시점 | `bbde570`. laptop worktree(HEAD = 기준)에서 읽기만 했다. 2026-11-06 04:00~ | +| 목적과 지원 실행 구성 | 템플릿. realtime은 `RECIPE_AVAILABLE`·`AVAILABLE_NOT_COMPOSED`다(snapshot `optional-recipes.json`의 `productionComposition: false`). 조합 코드(bridge, 환경 신호, poll `execute`)는 채택 프로젝트 몫이다. 브라우저 SPA, 탭마다 연결 1개 | +| 필수 요구와 규모·운영 목표 | 합의된 SLO 없음. 설계 11절 상한표와 13.1 실패 어휘를 기준으로 봤다 | +| 읽은 코드·구성 범위 | `8a44226..bbde570`에서 영역을 바꾼 커밋 전부: `bde7fa4`(조합 transport `OFFLINE` 테스트), `05330e3`(던지는 execute), `27e3dec`(`input.operation`), `05880d1`(VD-28·설계 3절), `1e576ef`(CHANGELOG 11-03 절 행), 합친 커밋 `57c34ea`. 전부 읽음: `bounded-poll-coordinator.ts`, `bounded-polling.ts`, 위 커밋의 diff와 테스트 변경. 필요한 부분: `reconnect-coordinator.ts`(`attempt`·`waitClosed`·`classifyClosed` 던짐 처리, `requireOnline`, 두 retry 분기), `result.ts`(`raceRealtimeTask`), `http-execution-v3.ts`(`execute` 시그니처, 결과 union, 재시도 상한, 바깥 catch, 입력 거절), `external-contract-runtime.ts`(`InstalledHttpContract`), `fetch-sse-connection.ts`(생성 검사, 거절 결과, `readSseForReconnect`), `websocket-connection.ts`(생성 검사), `sse-parser.ts`(`retry:`) | +| 읽은 문서(주장) | 설계 0.1·3·5.3·6.3·9.2·13.1절, VD-28 1절·poll 절, CHANGELOG 1105 절("먼저 할 일" 4단계, [계약] 행, 알려진 제한)과 11-03 절("먼저 할 일" 6단계, realtime 행 둘), 커밋 본문 다섯, 지난 라운드 영역 문서와 README §13·§15·§16 | +| 수행한 테스트·실험 | 직접 실행 없음. 배치 요청 둘을 오케스트레이터가 desktop에서 돌렸다(6절). 04-R1(변이 MR1, 1105/04-01 완료 기준) rc=1, 기대대로 검출. 04-R2(던지는 reconnect `attempt` 실험, 새 04-01) rc=0, 기대 값 그대로. 인용한 게이트(`desktop:/tmp/claude-gates/bbde570-ci/`, CI env, 2026-11-06 03:24~03:56): `summary.txt` FE-GATE-001~012·020 rc=0, 013 rc=1(영역 밖). `gate-artifacts/FE-GATE-005.txt` test:unit 208파일 3,056건 통과, 그중 realtime 14파일 272건. `FE-GATE-010.txt` check:realtime-boundaries PASS, fixture PASS(2 forbidden rules), optional recipes realtime 40,826 / 42,200 gzip B. `FE-GATE-020.txt` "Realtime runtime removal: PASS (7 base checks, 24 runtime-dependent tests removed by import graph)". snapshot(`r5/snap/merge/`, `MTIMES.txt`로 이번 실행 파일만): `artifacts/quality/realtime-boundaries.json` violations 0(03:53), `artifacts/tests/realtime-runtime-removal.xml` tests 7 failures 0(03:45). `r5/snap/verify-documentation.{local,no-sibling}.txt` 둘 다 `PASS_SCOPED` | +| 확인하지 못한 범위·이유 | 실제 브라우저·SSE/WS 서버·프록시(환경 없음). 짝 백엔드 실행(읽기만). 04-02 ①의 타입 추론은 `tsc`를 돌리지 않고 시그니처로 판단했다(실행 금지). `05330e3`·`27e3dec`를 되돌리는 변이는 요청하지 않았다. 새 테스트가 호출 횟수·결과를 정확 비교하므로 정적 근거로 충분하다고 봤다(최소 요청). 0929/04-03은 코드가 그대로라 실험하지 않았다 | +| 이전 리뷰와 비교 가능한 범위 | 1105 새 발견 3건, README §16.6의 이 영역 이월 3건을 지금 코드로 다시 판정했다(2절). 지난 라운드에 고쳐짐으로 닫은 7건은 이 범위 diff가 건드렸는지만 봤다. 지난 라운드와 조치 라운드의 실행 결과(04-R1~R4, 커밋 본문의 RED·변이)는 증거로 쓰지 않았다 | + +## 2. 지난 발견 재확인 + +| 지난 ID | 내용 | 상태 | 근거 | +| --- | --- | --- | --- | +| 1105/04-01 (Low·P3) | 서버 끊김 kind 변경 뒤 0929/04-01 회귀 테스트가 transport `OFFLINE` 경로를 지나지 않는다 | **고쳐짐** | `bde7fa4`. 환경은 계속 online이고 조합 transport가 `OFFLINE`을 내는 테스트 둘이 생겼다. attempt가 `OFFLINE`/`CONNECT`/retryable로 실패 → 3회, backoff `[50, 100]`, `OFFLINE` retryable로 끝, 관측 순서 고정(`realtime-reconnect-coordinator.test.ts:2206-2244`). 세션이 `OFFLINE`/`RECEIVE`로 닫힘 → 3회, `RETRY_SCHEDULED:OFFLINE` 2번(`:2246-2286`). 두 테스트 모두 `expect(attempts).toBe(3)`이다. MR1(두 retry 분기 뒤 `requireOnline()`, `reconnect-coordinator.ts:800-807`, `:995-1002`)을 넣으면 첫 attempt 뒤 online 이벤트를 기다린다. `advanceUntil`은 10초 뒤 끝난다(`:1805-1814`). 변이 없이 게이트에서 통과했다(FE-GATE-005, reconnect 46건 = 지난 44 + 2). **04-R1(MR1):** realtime 14파일 중 1파일, 272건 중 2건 실패, 270건 통과. 실패는 새 두 테스트뿐이고 둘 다 `AssertionError: expected 1 to be 3`(`:2230`, `:2278`)이다. 완료 기준("변이 MR1이 realtime 테스트에서 실패")을 충족한다 | +| 1105/04-02 (Low·P3) | poll `execute`의 던짐을 서버 장애로 보고 재시도해 조합 결함이 서버 장애·예산 소진으로 보인다 | **고쳐짐** | `05330e3`(BREAKING), `1e576ef`. 리뷰 선택지 (b)를 골랐다. `REJECTED`이면 lease가 abort된 경우만 `ABORTED` 결과, 아니면 `null`이다(`bounded-poll-coordinator.ts:336-347`). `null`은 모양이 틀린 결과와 같은 길로 `PROTOCOL_MISMATCH`(`retryable` 기본 false, `:855-860`)가 된다(`:395-399`). 타입 주석(`:105-110`), 설계 9.2(`realtime-events-…md:1674-1675`)와 13.1 두 행(`:1966`, `:1967`)이 같은 규칙을 적는다. 테스트: 비동기 거절·동기 던짐 둘 다 execute 1회, 결과 `PROTOCOL_MISMATCH`/`POLL`/false, 관측 `[LEASE_STARTED, LEASE_STOPPED:PROTOCOL_MISMATCH]`, 상태 `IDLE`(`bounded-poll-coordinator.test.ts:911-960`). 호출자 abort로 생긴 거절은 `ABORTED`(`:962-987`). 게이트 통과(bounded-poll-coordinator 24건). 옛 동작(3회 재시도, `POLL_BUDGET_EXHAUSTED`)이면 `toHaveBeenCalledTimes(1)`과 결과 비교가 실패한다(정적). V3 실행기는 바깥 catch로 모든 내부 실패를 `NETWORK_FAILURE` 결과로 돌려준다(`http-execution-v3.ts:1169-1173`). 그래서 권하는 조합에서 던짐은 조합 코드 결함이다. 완료 기준("던지는 execute의 결과로 조합 결함과 서버 장애를 구분")을 충족한다. 남은 것: 원인 예외는 여전히 남지 않는다(닫힌 관측 어휘). 조합 코드가 `execute` 안에서 기록해야 한다 | +| 1105/04-03 (Low·P3) | VD-28·설계 3절이 지운 V2 poll 예산·`REST QUERY`로 poll 규칙을 적는다 | **고쳐짐** | `05880d1`. VD-28 1절 끝이 "V3 contract executor가 실행하는 V3 REST descriptor 하나다(GET·HEAD, SAFE·IDEMPOTENT, `frontend.retryBudget: 0`, 상세 설계 9.2)"다(`VD-28-…md:117-120`). poll 절이 descriptor 조건과 `retryBudget` 0 거절을 적는다(`:442-446`). 설계 3절도 같은 말이고 ETag가 V3 실행기에 아직 없다고 적는다(`realtime-events-…md:365-372`). 완료 기준 `git grep -n "authRecoveryCount\|maxCumulativeSleepMs" bbde570 -- docs/architecture/decisions/VD-28*` 0건. `REST \`QUERY\``·`replay-safe`도 두 문서에서 0건이다 | +| 1103/04-01 (Medium·P2) | bounded polling 계약이 V2 자기 선언이라 V3 실행기 재시도를 막지 못한다 | **고쳐짐** (README §16.6은 "일부") | 완료 기준("`retryBudget > 0` descriptor는 조립 때 거절, 실험 P 조합에서 poll 3회 = 요청 3회")은 `a65df74`부터 충족이고 지금도 같다. 생성 검사 `frontend.retryBudget !== 0`(`bounded-polling.ts:129`), 실행기 재시도 상한 `min(policy.retryBudget, maxRetryAttempts, 2)`(`http-execution-v3.ts:911-915`). 테스트 "refuses the default read descriptor"(`bounded-poll-coordinator.test.ts:1171`), "sends one request per poll attempt"(`:1178`, 요청 수 = `maxAttempts`)가 게이트에서 통과했다. **`27e3dec`가 지난 라운드의 남은 틈을 좁혔다.** coordinator가 생성 때 한 번 잡은 객체(`:149-150`)를 모든 `execute`에 `input.operation`으로 넘긴다(`:322-328`). 테스트의 V3 조합도 클로저 대신 그것을 쓴다(`bounded-poll-coordinator.test.ts:1147-1152`). 매 호출이 같은 객체라는 테스트가 있다(`:1208-1248`, `toBe(pollOnly)`). **잔여 위험:** 조합 코드가 `input.operation`을 무시하고 다른 행을 넘기면 attempt마다 요청이 최대 3번이다. 타입 주석(`bounded-poll-coordinator.ts:113-118`), 설계 9.2(`realtime-events-…md:1671-1674`), CHANGELOG 알려진 제한(`CHANGELOG.md:103`)이 적는다. 실행기 타입이 `adapters/http`에 있어 coordinator가 직접 부를 수 없다는 커밋의 판단(adapter 사이 import 금지)은 맞다. 이 잔여는 원래 완료 기준 밖이라 "일부"가 아니라 고쳐짐 + 잔여 위험으로 둔다. `input.operation`의 타입 문제는 따로 새 04-02로 적었다 | +| 0929/04-02 (Medium·P2) | SSE↔reconnect 세션 bridge 부재, EOF 분류 미정 | **남음** (결정 대기, README §16.6) | `git diff 8a44226..bbde570 -- src/adapters/realtime/sse src/adapters/realtime/reconnect-coordinator.ts` 0줄. 도구는 여전히 `readSseForReconnect` 하나다(`fetch-sse-connection.ts:498-513`). 테스트 안의 bridge가 `200` 뒤 EOF를 `PROTOCOL_MISMATCH`/`RECEIVE`/false로 끝낸다(`realtime-reconnect-coordinator.test.ts:1791-1798`). 두 SSE 묶음은 여전히 "Only connect failures are exercised here"다(`:2001`, `:2065`). 설계 6.3 상태표는 `204`만 정한다(`realtime-events-…md:1087-1088`) | +| 0929/04-03 (Low·P3) | SSE `retry:` 처리 규칙이 설계 5.3·6.3과 코드에서 다르다 | **남음** (결정 대기, README §16.6) | `sse-parser.ts:330-341` 그대로다(`maxRetryMs`를 넘는 값은 버림). 5.3은 not-before이고 상한을 넘으면 종료라 적는다(`realtime-events-…md:803-807`). 6.3은 "ceiling을 통과한 경우 다음 delay hint로만"이다(`:1079-1080`). 두 절과 코드가 여전히 다른 말을 한다 | +| 1103/04-02·04-03·04-04·04-05·04-06, 0929/04-04, 1101/04-03 | 지난 라운드에 고쳐짐 | 유지 | 이 범위 src diff는 `bounded-poll-coordinator.ts`, `bounded-polling.ts` 둘뿐이고 테스트 diff는 추가와 poll 기대값 변경뿐이다(2.1절). snapshot 바인딩 표(`realtime-stream-registry.test.ts`, 30건), WS 초당 상한(`websocket-connection.test.ts`, 24건)이 게이트에서 통과했다. 1103/04-02 대응표의 입력인 pin commit이 그대로다. 다시 판정하지 않았다 | + +### 2.1 조치가 검사를 약하게 만들었는가 (`git diff 8a44226..bbde570`) + +| 커밋 | 테스트·검사 변경 | 판정 | +| --- | --- | --- | +| `bde7fa4` | `realtime-reconnect-coordinator.test.ts`에 87줄, 테스트 2건만 더했다 | 강해짐. 정확 비교(`toBe(3)`, `toEqual`)다. 변이 MR1을 두 건이 잡는다(04-R1) | +| `05330e3` | "retries a throwing executor as PROVIDER_UNAVAILABLE"(옛 `:906-948`)을 지우고 `it.each` 2건 + abort 보존 1건을 더했다 | 약해지지 않음. 지운 기대값은 바뀐 동작이었다. 새 기대값은 호출 횟수·결과·관측 전체·상태를 본다. 결과로 온 `PROVIDER_UNAVAILABLE`의 재시도는 다른 두 테스트가 계속 본다(`:1178`, `:1208`, 둘 다 호출·요청 수 = `maxAttempts`) | +| `27e3dec` | V3 조합 테스트가 클로저 descriptor 대신 `input.operation`을 쓴다. 테스트 1건 추가 | 약해지지 않음. 실행기가 `retryBudget`을 읽는 경로는 같은 객체(`retryBudget: 0`)로 계속 지난다 | +| `05880d1`, `1e576ef` | 문서만 | 해당 없음 | + +skip·only·시간 상한·허용 목록 변경은 영역 diff에 없다(`git diff … | grep` 0건). + +한 가지 기록(결함 아님): `bounded-poll-coordinator.ts:344-346`의 `controller.signal.aborted ? realtimeFailure("ABORTED", …) : null`에서 `ABORTED` 갈래는 결과에 닿지 않는다. lease의 controller를 abort하는 곳은 `stop()`(먼저 `stopKind`를 정함, `:209-213`)과 `close()`(상태 `CLOSED`, `:584-589`), `CLOCK_FAILED` 분기(그 자리에서 반환)뿐이다. 그래서 abort된 뒤에는 `:368-381`의 `currentFailure`가 항상 먼저 반환한다. 동등 분기다. 테스트 "keeps ABORTED"(`:962`)는 그 갈래를 지우는 변이를 잡지 못하지만, 동작이 같으므로 문제가 아니다(정적, E1). + +### 2.2 BREAKING `05330e3` — 코드와 안내 대조 + +| 주장(출처) | 코드 | 판정 | +| --- | --- | --- | +| footer: "`execute`가 던지면(abort로 생긴 것 제외) 재시도 없이 PROTOCOL_MISMATCH(retryable: false)로 lease가 끝난다" | `:336-347` → `:395-399` → `pollFailure("PROTOCOL_MISMATCH")`, retryable 기본 false(`:855-860`). abort된 경우는 `:368-381`이 abort 이유(`ABORTED`·`OFFLINE`·`POLL_BUDGET_EXHAUSTED`·`CLOSED`)로 끝낸다 | 맞음. 덧붙이면 abort가 없어도 던진 사이 환경이 바뀌면(hidden·offline·scope) 그 kind, 시계가 깨지면 `PROVIDER_UNAVAILABLE`, 시간 예산이 끝나면 `POLL_BUDGET_EXHAUSTED`다(`:368-393`). 모두 lease 검사가 결과 해석보다 먼저라는 기존 규칙이다 | +| footer: "전에는 PROVIDER_UNAVAILABLE로 maxAttempts까지 재시도했다" | `git show 8a44226:src/adapters/realtime/polling/bounded-poll-coordinator.ts`의 `REJECTED` 분기(`:322-328`) | 맞음 | +| footer·CHANGELOG 4단계: "네트워크 실패를 throw로 내던 `execute`는 retryable `PROVIDER_UNAVAILABLE` 결과로 바꾼다" | 그 결과는 `parseAttemptResult`를 지나(`:640-678`) 재시도된다(`:405-432`, 재시도 kind `:135-139`) | 맞음. 테스트 `:1208`이 정확히 그 결과로 `maxAttempts`번 부른다 | +| CHANGELOG 1105 절 4단계(`CHANGELOG.md:27`)·[계약] 행(`:67`): "lease 자신의 abort 제외", "`input.operation`이 실린다(추가만)" | `execute` 입력에 칸을 더했을 뿐 기존 `execute`는 그대로 돈다. check:types 통과(FE-GATE-003) | 맞음 | +| CHANGELOG 11-03 절 행(`:298`, `1e576ef`): "poll은 이 범위 끝에서 던지는 execute를 lease 안에서 다시 시도했다. 위 절에서 다시 바뀌어 … `PROTOCOL_MISMATCH`로 끝난다(1105/04-02)" | 위와 같음 | 맞음. 절마다 범위 끝 사실을 적는 규칙(`:7`)과도 맞다. 11-03 절 "먼저 할 일" 6단계(`:202`)의 "SSE·poll이 서버에 닿지 못한 실패는 `PROVIDER_UNAVAILABLE`"은 주석이 없다. 그러나 1105 절 머리가 "아래 절의 먼저 할 일을 마친 뒤"라 적고(`:20`) 4단계가 덮는다. 권하는 V3 조합에서는 그 문장이 지금도 사실이다(`NETWORK_FAILURE` 결과 → `PROVIDER_UNAVAILABLE`, 13.1 `:1966`) | +| `changelog-review-ids` 테스트 | FE-GATE-005에서 2건 통과 | 맞음 | + +## 3. 이번 발견 (36.3) + +이번 발견 2건: **Low 2** · **P3 2** · 구조적 위험 1, 개선 제안 1. + +### 04-01 reconnect coordinator는 던지는 `attempt`를 서버 장애로 재시도한다. `05330e3` 뒤 poll은 같은 던짐을 조합 결함으로 끝내, 두 coordinator가 반대로 읽는다 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 구조적 위험(진단 의미 불일치. `05330e3`이 poll만 바꿔 생김) | +| 관련 관점 | 23, 8, 24, 5, 6 | +| 근거 | ① reconnect: `attempt`가 던지면 `providerRetry`로 `PROVIDER_UNAVAILABLE`/`CONNECT`/retryable을 만들고 다시 시도한다(`reconnect-coordinator.ts:766-774`, `:1569-1584`). 열린 세션의 `waitClosed`가 던져도 같다(`:954-961`). `classifyClosed`가 던지면 `PROTOCOL_MISMATCH`로 끝낸다(`:963-978`). ② poll: 같은 던짐을 재시도 없이 `PROTOCOL_MISMATCH`로 끝낸다(`bounded-poll-coordinator.ts:336-347`, `:395-399`). 13.1 `PROTOCOL_MISMATCH` 행이 이것을 "조합 코드 결함"이라 적는다(`realtime-events-…md:1967`). ③ reconnect `attempt` 타입(`reconnect-coordinator.ts:167-176`)과 13.1 `PROVIDER_UNAVAILABLE` 행(`:1966`)은 던진 `attempt`가 어떻게 되는지 말하지 않는다. 5.3은 `waitClosed` throw가 예산 초기화 경로에 든다고만 적는다(`:811-813`). 차이는 커밋 `05330e3` 본문의 "위험·한계"에만 있다("이번 범위 밖"). ④ 템플릿 transport는 연결 실패를 던지지 않고 결과로 돌려준다(SSE fetch 거절 `fetch-sse-connection.ts:217-225`, reader 거절 `:402-407`, WS `error` `websocket-connection.ts:443`). 던지는 곳은 생성 때 설정 검사다. SSE endpoint가 same-origin HTTPS가 아니면(`fetch-sse-connection.ts:112-118`, `:515-536`), WS endpoint·barrier가 틀리면(`websocket-connection.ts:260-275`) `TypeError`다. ⑤ repo의 SSE bridge 예("The smallest SSE bridge design 6.3 leaves to composition", `realtime-reconnect-coordinator.test.ts:1758-1803`)는 `attempt` 안에서 연결을 만든다(`:1764-1770`). 그 모양에서 endpoint 설정 오류는 attempt마다 던진다. ⑥ **실험 04-R2**(rc=0): 같은 모양(`attempt` 안에서 `createFetchSseConnection` → `readSseForReconnect`)에 `http://app.example.test/events`를 넣고 환경은 계속 online. 결과: fetch 0회, attempt 3회, 세 번 모두 `TypeError: SSE endpoint must be fixed same-origin HTTPS.`, backoff `[50, 100]`, 결과 `PROVIDER_UNAVAILABLE`/`CONNECT`/retryable true, 관측 `ATTEMPT_STARTED`, `RETRY_SCHEDULED:PROVIDER_UNAVAILABLE` × 2, `RUN_ENDED:PROVIDER_UNAVAILABLE:EXHAUSTED`. 요청을 한 번도 보내지 않은 설정 오류가 서버 장애·예산 소진으로 끝났다. 같은 던짐은 poll에서 execute 1회, `PROTOCOL_MISMATCH`다(`bounded-poll-coordinator.test.ts:911-960`, 게이트 통과) | +| 발생 조건 | 조합 코드의 `attempt`(SSE bridge, 직접 쓴 STOMP transport 등)가 결과를 만들다 던질 때. 설정 오류, 매핑 오류, 잘못된 필드 접근 | +| 영향 | 결함이 바로 드러나지 않는다. reconnect 예산(`maxAttempts`·`maxElapsedMs`) 동안 backoff로 다시 시도하고 `PROVIDER_UNAVAILABLE`(EXHAUSTED)로 끝난다. 화면과 관측은 "서비스 이용 불가"로 본다. 원인 예외는 남지 않는다. 같은 조합자가 poll에서는 같은 종류의 결함을 `PROTOCOL_MISMATCH`로 본다. 데이터 손상은 없고 요청 수는 예산 안이다. 설정 오류면 네트워크 요청도 없다 | +| 심각도·우선순위 | Low · P3. 진단을 늦추는 문제이고 상한이 있다. 1105/04-02와 같은 등급이다 | +| 통제·증거 | 규칙 M2(구현) · 명시 없음(타입 주석·13.1에 없음) · E1 + E2(04-R2) | +| 확실성과 남은 가정 | 분기는 코드로, 설정 오류의 결과는 04-R2로 확인했다. 매핑 오류 같은 다른 던짐도 같은 분기를 지난다(정적). 조합 transport가 브라우저·라이브러리 API의 던짐을 그대로 올리는 경우(예: STOMP client가 연결 실패를 던짐)에는 지금 동작이 회복에 유리하다. 그래서 동작 자체가 틀렸다고 보지 않는다. 문제는 규칙이 적혀 있지 않고 poll과 반대라는 것이다 | +| 결정의 근거 | 확인한 사실: 두 coordinator 모두 조합 코드가 준 함수를 감싼다. poll의 `execute`는 던지지 않는 V3 실행기를 감싸고, reconnect의 `attempt`는 던질 수 있는 연결 API를 감쌀 수 있다. 기록된 의도: `05330e3` 본문 "그쪽 attempt는 브라우저 연결 API를 감싸는 자리라 이번 범위 밖". 리뷰어 추론: 템플릿 transport는 연결 실패를 결과로 돌려주므로, 템플릿 transport만 쓰는 bridge에서 던짐은 조합 결함이다. 41절: (a) 현상 유지 (b) reconnect도 던짐을 `PROTOCOL_MISMATCH`로 끝냄 (c) 동작은 두고 `attempt`·`waitClosed` 타입 주석과 13.1에 "던짐은 transport 실패로 재시도된다. 연결 생성(설정 검사)은 `attempt` 밖에서 한다"를 적고, 테스트 bridge도 연결을 밖에서 만들게 바꿈 | +| 이해 비용 | 조합자가 run이 끝난 이유를 보려면 coordinator 코드를 읽어야 던짐이 섞였는지 안다. poll을 먼저 쓴 사람은 반대를 기대한다 | +| 최소 개선 방향 | (c). 주석 두 곳 + 13.1 한 구절 + 테스트 bridge에서 연결 생성을 `attempt` 밖으로 | +| 대안 비교 | (a) 비용 0, 진단이 늦고 두 경계가 다르게 읽힌다. (b) 조합 결함이 첫 attempt에서 드러난다. 던지는 라이브러리를 감싼 transport는 첫 연결 실패에서 run이 끝나므로, 조합 코드가 던짐을 결과로 바꿔야 한다([계약] BREAKING). (c) 동작이 같고 설정 오류는 생성 때 한 번 드러난다. 매핑 오류 같은 나머지 던짐은 여전히 재시도된다 | +| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아님 | +| 비용·부작용 | (c) 문서·테스트만. (b)는 공개 동작 변경 | +| 재검토 조건 | 템플릿이 SSE bridge(0929/04-02)나 STOMP transport를 제공하게 되면, 그 transport가 던지는지에 따라 (b)를 다시 본다 | +| 완료 기준 | 조합자가 타입 주석이나 13.1만 보고 던지는 `attempt`·`waitClosed`가 어떻게 끝나는지 안다. repo의 bridge 예에서 endpoint 설정 오류가 run 시작 전에 드러난다 | +| 검증 방법 | 문서 리뷰. 04-R2 실험 파일을 고친 bridge 모양으로 다시 돌려 attempt 0회(생성 때 throw)를 본다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 재검증 결과 | 신규 — 해당 없음 | + +### 04-02 poll `execute`를 V3 실행기에 잇는 자리에 타입과 결과 대응이 없다. 권하는 `input.operation` 경로는 입력·출력 타입을 잃는다 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 개선 제안 | +| 관련 관점 | 20, 22, 17, 3 | +| 근거 | ① `input.operation`의 타입은 `BoundedPollOperation` = `InstalledHttpContract`이다(`bounded-polling.ts:41-45`, `bounded-poll-coordinator.ts:119`). coordinator는 `Value`만 제네릭이다(`:97`, `:145-147`). 실행기는 `execute(operation: InstalledHttpContract, input: Input, …)`이다(`http-execution-v3.ts:551-555`). 그래서 `executor.execute(input.operation, x, …)`에서 `Input`은 `unknown`이 되어 `x`는 무엇이든 통과하고, `outcome.value`도 `unknown`이다(시그니처로 한 정적 판단, `tsc` 미실행). 클로저에 둔 기능 descriptor는 두 타입을 지킨다. 타입을 지키려는 조합 코드는 1103/04-01 잔여 위험인 클로저 경로를 쓸 이유가 생긴다. 테스트도 `{ limit: 20 }`을 타입 검사 없이 넘긴다(`bounded-poll-coordinator.test.ts:1148-1152`). 입력이 틀리면 실행기는 런타임에 `CONTRACT_VIOLATION`(`INPUT_INVALID`)을 돌려준다(`http-execution-v3.ts:774-777`, `:1839-1851`). ② `05330e3` 뒤 `execute`는 모든 결과를 poll 결과로 바꿔야 한다(`bounded-poll-coordinator.ts:105-110`). V3 결과는 9종이다(`http-execution-v3.ts:165-235`: `SUCCESS`, `PROBLEM`, `UNAUTHENTICATED`, `FORBIDDEN`, `RATE_LIMITED`, `CONTRACT_VIOLATION`, `TRANSPORT_FAILURE`, `CANCELLED`, `AUTH_INTEGRATION_FAILURE`). poll이 재시도하는 kind는 `CONNECT_TIMEOUT`·`RATE_LIMITED`·`PROVIDER_UNAVAILABLE`이고 `retryAfterMs`는 뒤 둘만 읽는다(`bounded-poll-coordinator.ts:135-143`). 대응을 적은 곳은 13.1의 한 구절(`NETWORK_FAILURE` → `PROVIDER_UNAVAILABLE`, `realtime-events-…md:1966`)뿐이다. VD-28은 "`304`, auth, cursor reset, `429/503 Retry-After`를 closed mapping"이라 적는다(`VD-28-…md:450`). 설계 9.2는 "authorization required/forbidden"에서 lease가 끝난다고 적는다(`realtime-events-…md:1690`). ③ repo의 유일한 V3 조합 예는 SUCCESS가 아닌 모든 결과를 retryable `PROVIDER_UNAVAILABLE`로 바꾼다(`bounded-poll-coordinator.test.ts:1153-1165`). 503 재시도를 세는 테스트에는 맞지만, 이 예를 옮기면 401·403·입력 거절도 서버 장애로 `maxAttempts`번 다시 요청된다 | +| 발생 조건 | 조합 코드가 설계 9.2와 테스트 예를 보고 poll `execute`를 쓸 때 | +| 영향 | 입력 모양 오류가 `check:types`를 지나 런타임 `CONTRACT_VIOLATION`이 된다. 대응을 예대로 쓰면 그 결과와 401·403이 lease 안에서 재시도되고 `POLL_BUDGET_EXHAUSTED`로 끝난다. 설계 9.2의 "auth에서 종료"와 다르다. 요청 수는 lease 상한 안이다. 데이터 손상은 없다 | +| 심각도·우선순위 | Low · P3. 조합 코드 작성 편의와 진단 문제이고 상한이 있다 | +| 통제·증거 | 대응 규칙 M1 일부(13.1 한 구절, VD-28 목표) · 타입 연결 M0(입력·출력 타입을 잇는 수단 없음) · E1 | +| 확실성과 남은 가정 | 시그니처와 테스트 코드로 확인했다. TypeScript 추론 결과는 컴파일로 확인하지 않았다. 조합 코드가 실제로 테스트 예를 옮길지는 추론이다 | +| 결정의 근거 | 확인한 사실: realtime 어댑터는 `adapters/http`의 실행기·결과 타입을 import할 수 없다(adapter 사이 import 금지, `27e3dec` 본문). 그래서 대응 함수를 realtime 안에 둘 수 없다. 기록된 의도: 조합 코드가 `execute`를 쓴다(설계 9.2). 리뷰어 추론: 타입은 realtime 안에서 제네릭 하나로 이을 수 있고, 대응은 문서 표로 줄 수 있다. 41절: (a) 현상 유지 (b) `createBoundedPollCoordinator`로 `operation`과 `input.operation`을 `Operation`으로 둔다 (c) 9.2에 V3 결과 9종 → poll 결과(kind·retryable·`retryAfterMs`) 표를 둔다 (d) 대응 함수를 bootstrap이나 recipe에 둔다 | +| 이해 비용 | 조합자가 V3 결과 union과 poll 재시도 kind를 둘 다 읽고 맞춰야 한다. 타입을 지킬지 `input.operation`을 쓸지 골라야 한다 | +| 최소 개선 방향 | (b) + (c). 타입 매개변수 하나와 표 하나 | +| 대안 비교 | (a) 비용 0, 클로저 경로가 계속 유리하다. (b) 런타임 동작이 같고 기본값이 있어 기존 호출이 그대로다. (c) 문서만, 테스트 예와 함께 고치면 옮겨 쓰는 실수가 준다. (d) 대응을 한 곳에 묶지만 레시피 번들과 제거 드릴의 범위가 바뀐다 | +| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아님 | +| 비용·부작용 | (b) 타입만, 공개 타입이 넓어진다(호환). (c) 문서 표 1개 | +| 재검토 조건 | 템플릿이 poll `execute` 기본 구현(V3 실행기 래퍼)을 제공하게 되면 그 구현이 표를 대신한다 | +| 완료 기준 | `input.operation`을 실행기에 넘긴 호출에서 입력이 기능 descriptor의 `Input`으로 검사된다. 9.2나 13.1에서 V3 결과마다 poll 결과를 찾을 수 있다 | +| 검증 방법 | check:types에 걸리는 타입 테스트(틀린 입력에 `@ts-expect-error`). 문서 리뷰 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 재검증 결과 | 신규 — 해당 없음 | + +## 4. 28개 관점 판정 (36.2) + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역 판정을 따름 + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +| --- | --- | --- | --- | --- | --- | +| 1 | 코드 성숙도 | 적용 | M2 / M2 | E2 FE-GATE-005 realtime 14파일 272건 통과 | O. 바뀐 코드는 poll `REJECTED` 분기와 입력 칸 하나다. 상태 기계·terminal close는 그대로다. `ABORTED` 갈래는 동등 분기다(2.1절) | +| 2 | 구조적 성숙도 | 적용 | M4 / M4 일부 | E2 FE-GATE-010(check:architecture 419 modules, check:realtime-boundaries PASS, fixture 2 forbidden rules), snapshot `realtime-boundaries.json` violations 0 | O. `27e3dec`가 adapter 사이 import를 만들지 않으려 실행기를 받지 않았다 | +| 3 | 변경 용이성 | 적용 | M2 / M2 | E1 | P. poll 조립은 descriptor 하나다. `execute` 대응과 SSE bridge는 직접 쓴다(04-02, 0929/04-02) | +| 4 | 인지 부하 | 적용 | M1 / M1 | E1 | P. VD-28·설계 3절이 지금 규칙과 맞다(1105/04-03). `runLoop` 크기는 그대로다. 같은 종류의 던짐을 두 coordinator가 반대로 읽는다(04-01) | +| 5 | 위험 가시성 | 적용 | M1 / M1 | E1 | P. poll 잔여 틈은 타입 주석·9.2·CHANGELOG 알려진 제한에 있다. reconnect 던짐 규칙은 커밋 본문에만 있다(04-01) | +| 6 | 실패 성숙도 | 적용(깊게) | M3 / M3 일부 | E1·E2(게이트, 04-R1, 04-R2) | P. poll 던짐이 조합 결함으로 분류된다(1105/04-02). reconnect 던짐 분류(04-01), EOF 미정(0929/04-02), `retry:` 규칙(0929/04-03) | +| 7 | 운영 성숙도 | 적용 | M2 / M2 | E1 | P. poll 결과로 조합 결함과 서버 장애를 구분한다. reconnect는 못 한다(04-01) | +| 8 | 디버깅 가능성 | 적용(깊게) | M2 / M1 | E1·E2 | P. 던짐의 원인 예외는 두 coordinator 모두 남기지 않는다(닫힌 관측 어휘, 조합 코드가 기록). 04-01 | +| 9 | 유지보수 성숙도 | 적용 | M1 / M1 | E1 | P. VD-28 옛 어휘가 사라졌다. CHANGELOG 두 절이 같은 규칙을 적는다(2.2절). 설계 5.3의 코드 줄 번호가 조금 어긋난다(예: `fetch-sse-connection.ts:488-506` → 지금 `:498-513`, `realtime-events-…md:847`) | +| 10 | 테스트 성숙도 | 적용(깊게) | M3 / M3 일부 | E2 게이트, 변이 1건(MR1 검출, 04-R1) | P. 1105/04-01 공백에 테스트가 생겼고 MR1을 잡는다. 1105/04-02·1103/04-01 테스트는 정확 비교다. 던지는 reconnect `attempt`를 서버 장애로 보는 동작을 고정한 테스트는 없다(04-R2는 실험) | +| 11 | 데이터 성숙도 | 적용 | M2 / M2 | E1 | O. cursor는 effect 성공 뒤에만 전진한다. 이번 커밋이 바꾸지 않았다 | +| 12 | 동시성 성숙도 | 적용 | M3 / M3 | E2 | O. run 1개, `DRAINING`·generation fence 그대로. `27e3dec`는 생성 때 객체를 잡아 나중 변경에 흔들리지 않는다(`:149`) | +| 13 | 확장성 | 적용 | M3 / M3 | E1·E2 | P. 같은 descriptor면 poll 1 attempt = 요청 1번이다. 조합 코드가 다른 행을 넘기면 3배(1103/04-01 잔여) | +| 14 | 성능 성숙도 | 적용 | M2 / M2 | E2 FE-GATE-010 optional recipes realtime 40,826 / 42,200 gzip B(여유 1,374, 지난 라운드 40,811) | P. 예산 안이다. production 번들에는 들어가지 않는다. 브라우저 실행 성능은 미측정 | +| 15 | 보안 성숙도 | 적용 | M4 / M4 | E1 | O. 고정 same-origin endpoint(`fetch-sse-connection.ts:515-536`), URL credential 없음. 바뀐 곳 없음 | +| 16 | 의존성 성숙도 | 적용 | M3 / M3 | E1 | O. 외부 패키지 없음 | +| 17 | API / Contract 성숙도 | 적용(깊게) | M3 / M3 일부 | E1·E2 | P. BREAKING 안내가 코드와 맞는다(2.2절). `input.operation`은 타입을 잃고 V3 결과 대응표가 없다(04-02) | +| 18 | 배포 성숙도 | 적용 | M2 / M1 | E1 | P. 백엔드 배포의 SSE EOF를 재연결할지 미정(0929/04-02) | +| 19 | 설정 성숙도 | 적용 | M2 / M2 | E1 | P. `MAX_RETRY_ATTEMPTS`가 poll에 걸리지 않는다(`http-execution-v3.ts:911-915`). 파서 `maxRetryMs`와 정책 `maxDelayMs`는 따로 논다(0929/04-03). SSE·WS 설정 오류가 `attempt` 안에서 나면 서버 장애로 보인다(04-01) | +| 20 | 개발자 경험 | 적용 | M2 / M2 | E1 | P. V3 결과 → poll 결과 표가 없다(04-02). SSE bridge 예는 테스트 안에만 있다 | +| 21 | Guardrail 성숙도 | 적용 | M3 / M3 일부 | E2 FE-GATE-010·020, 04-R1 | P. poll 생성 검사는 경계에서 거절한다. 0929/04-01 규칙 회귀를 다시 검출한다(04-R1, M3). 던지는 reconnect `attempt` 규칙은 검사도 명시도 없다(04-01) | +| 22 | 추상화 성숙도 | 적용 | M2 / M2 | E1 | P. poll 계약·실행기가 같은 descriptor로 이어지고 그 객체가 `execute`에 온다. 타입은 이어지지 않는다(04-02) | +| 23 | 일관성 | 적용(깊게) | M2 / M2 | E1 | P. 조합 함수의 던짐을 poll은 `PROTOCOL_MISMATCH`, reconnect는 `PROVIDER_UNAVAILABLE` 재시도로 읽는다(04-01). `APPLY_FAILED`의 `retryable`이 handoff는 true, stream은 false인 것은 그대로다 | +| 24 | 네이밍 / 의미 성숙도 | 적용 | M1 / M1 | E1 | P. poll의 `PROVIDER_UNAVAILABLE`에서 조합 결함이 빠졌다. reconnect의 `PROVIDER_UNAVAILABLE`에는 남는다(04-01) | +| 25 | 조직 확장성 | 적용 제외 — 작성자 1인 | - | - | - | +| 26 | Ownership 성숙도 | 적용 제외 — 제품 조합 없음 | - | - | -. 짝 백엔드 push 경로와 0929/04-02·04-03의 결정자는 사용자다 | +| 27 | 삭제 가능성 | 적용 | M3 / M3 | E2 FE-GATE-020(CI env) "Realtime runtime removal: PASS (7 base checks …)", snapshot `realtime-runtime-removal.xml` tests 7 failures 0 | O | +| 28 | 회복 가능성 | 적용 | M3 / M3 일부 | E1·E2 | P. 서버 끊김 뒤 재연결로 회복한다. 조합 transport `OFFLINE` 경로에 테스트가 생겼다. EOF 뒤 회복은 조합 코드 몫(0929/04-02) | + +## 5. 미검증 + +| 항목 | 왜 확인하지 못했나 | 확인하려면 | +| --- | --- | --- | +| 04-02 ①의 TypeScript 추론 | `tsc` 실행 금지. 시그니처로 판단 | `@ts-expect-error`를 붙인 타입 테스트 한 파일로 check:types | +| `05330e3`·`27e3dec`를 되돌리는 변이 | 새 기대값이 호출 횟수·결과를 정확 비교해 정적 근거로 충분하다고 봤다(최소 요청) | 필요하면 다음 라운드에서 한 번씩 | +| 실제 브라우저·SSE/WS 서버·프록시, 짝 백엔드 실행 | 환경 없음, 백엔드는 읽기만 | 설계 15.3의 로컬 서버 + 브라우저 실행 | +| 0929/04-03의 현재 동작 | 코드가 그대로라 실험하지 않았다 | 0929 실험 E9 재실행 | +| 브라우저에서의 realtime 실행 성능 | 측정 환경 없음. 번들 크기만 게이트에서 봤다 | lab 측정 | + +## 6. 실행 기록 + +이 리뷰어는 아무것도 실행하지 않았다. 배치 항목은 요청 파일 `scratchpad/r5/requests/04.md`에 있다. 패치는 laptop worktree(`bbde570`)에서 `git apply --check`만 했다. 오케스트레이터가 desktop `/home/donghyeon/workspace/clean-architecture-frontend-template`에서 한 번씩 돌렸다(2026-11-06 04:32, env local, head `bbde570`, 항목마다 `restore=clean`). 로그: `desktop:/tmp/claude-gates/r5/batch/out/R5-04-R1.log`, `R5-04-R2.log`. + +| 이름 | 명령 | 변이 | rc | 결과 | 부하 | +| --- | --- | --- | --- | --- | --- | +| 04-R1 (MR1) | `node scripts/run-vitest.ts run tests/unit/realtime/ --reporter=default` | `scratchpad/r5/requests/04-R1-mr1.patch`: `reconnect-coordinator.ts:806`, `:1001` 뒤에 `if (… .kind === "OFFLINE") requireOnline();` | 1 | **검출.** 14파일 중 1파일, 272건 중 2건 실패, 270건 통과. 실패: "retries a composer transport's OFFLINE attempt failure while the browser stays online"(`realtime-reconnect-coordinator.test.ts:2230`), "reconnects after a composer session closes with OFFLINE while the browser stays online"(`:2278`), 둘 다 `AssertionError: expected 1 to be 3`. 기대와 같다. 변이 없는 대조: FE-GATE-005 realtime 14파일 272건 통과 | 4.05 | +| 04-R2 | `node scripts/run-vitest.ts run tests/unit/zz-review04/ --reporter=default` | `scratchpad/r5/requests/04-R2-reconnect-throw.patch`: 실험 파일 `tests/unit/zz-review04/zz-review04-1106.test.ts` 추가만(src 변경 없음) | 0 | 1건 통과. 출력 `{"attempts":3,"fetchCalls":0,"thrown":["TypeError: SSE endpoint must be fixed same-origin HTTPS." × 3],"sleepCalls":[50,100],"result":{"ok":false,"error":{"kind":"PROVIDER_UNAVAILABLE","operation":"CONNECT","retryable":true}},"observed":["ATTEMPT_STARTED","RETRY_SCHEDULED:PROVIDER_UNAVAILABLE","ATTEMPT_STARTED","RETRY_SCHEDULED:PROVIDER_UNAVAILABLE","ATTEMPT_STARTED","RUN_ENDED:PROVIDER_UNAVAILABLE:EXHAUSTED"]}`. 기대와 같다 | 4.21 | + +인용한 오케스트레이터 결과(직접 실행 아님, `desktop:/tmp/claude-gates/bbde570-ci/`, CI env): FE-GATE-001~012·020 rc=0, FE-GATE-013 rc=1(user namespace 전제, 영역 밖). FE-GATE-005 test:unit 208파일 3,056건(realtime 14파일 272건: bounded-poll-coordinator 24, realtime-reconnect-coordinator 46, bounded-polling-policy 11, realtime-stream-registry 30, websocket-connection 24, fetch-sse-connection 27, stream-coordinator 38, live-poll-handoff-coordinator 16, sse-parser 14, result 12, event-codec 8, websocket-protocol 8, event-consumer 7, realtime-reconnect-policy 7), `changelog-review-ids` 2건. FE-GATE-010 check:realtime-boundaries PASS, `:fixture` PASS, optional recipes realtime 40,826 / 42,200 gzip B. FE-GATE-020 realtime removal PASS. snapshot `realtime-boundaries.json` violations 0, `realtime-runtime-removal.xml` 7 checks 0 failures. `r5/snap/verify-documentation.local.txt`·`.no-sibling.txt` `PASS_SCOPED`. + +## 7. 새 발견 요약 + +| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line | +| --- | --- | --- | --- | --- | +| 04-01 | Low·P3 | 구조적 위험 | reconnect coordinator는 던지는 `attempt`·`waitClosed`를 서버 장애로 재시도한다. `05330e3` 뒤 poll은 같은 던짐을 `PROTOCOL_MISMATCH`로 끝내고, 규칙은 어디에도 적혀 있지 않다. repo bridge 모양에서 endpoint 설정 오류가 fetch 0회로 3번 재시도되고 `PROVIDER_UNAVAILABLE`(EXHAUSTED)로 끝난다(04-R2) | `src/adapters/realtime/reconnect-coordinator.ts:766-774`, `:954-961`; `tests/unit/realtime/realtime-reconnect-coordinator.test.ts:1764-1770` | +| 04-02 | Low·P3 | 개선 제안 | 권하는 `input.operation`은 `InstalledHttpContract`이라 실행기 호출의 입력·출력 타입이 사라진다. V3 결과 9종 → poll 결과 대응표가 없고, 유일한 예는 SUCCESS 외 전부를 retryable `PROVIDER_UNAVAILABLE`로 바꾼다 | `src/application/policies/bounded-polling.ts:41-45`, `src/adapters/realtime/polling/bounded-poll-coordinator.ts:119`; `tests/unit/realtime/bounded-poll-coordinator.test.ts:1153-1165` | diff --git a/docs/reviews/2026-11-06-maturity-review/05-adapters-storage-kernel.md b/docs/reviews/2026-11-06-maturity-review/05-adapters-storage-kernel.md new file mode 100644 index 00000000..527b7e73 --- /dev/null +++ b/docs/reviews/2026-11-06-maturity-review/05-adapters-storage-kernel.md @@ -0,0 +1,241 @@ +# 영역 05 — 저장소·adapter kernel + +> 검토일 2026-11-06 · 기준 `bbde570`(`bbde570796b0a648bae65c2c0568fca860a3ba4e`, PR B 끝. 노트북 worktree에서 읽기만 했다. 작업 트리에는 무시하기로 한 미추적 `AGENTS.md`만 있다) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 경로: `src/adapters/storage/`(Web Storage, `indexeddb/`, `opfs/`), `src/adapters/platform/`(adapter kernel), `src/adapters/browser-file-storage/`, `src/contracts/storage-keys.ts`. 판정에 필요해서 함께 읽은 것: `src/application/ports/browser-file-storage/opfs-ports.ts`·`shared.ts`, `recipes/frontend-capabilities/browser-file-storage-fakes.ts`(OPFS fake), `recipes/session-owners/oidc-pkce-session-owner.ts`, `config/contracts/registry-governance.json` FE-REG-STORAGE, `scripts/check-registries.ts`(orphan 검사), `scripts/test-optional-recipe-removal.ts`, `tests/unit/opfs-worker-runtime.test.ts`·`storage-registry.test.ts`·`second-api-feature-registries.test.ts`, `tests/recipes/oidc-pkce-session-owner.test.ts`·`browser-file-storage-contracts.test.ts`, `tests/browser-capabilities/opfs-runtime.spec.ts`, `docs/operations/browser-file-storage-recovery.md` §0·§7, `docs/architecture/client-cache-and-storage.md` 0절, `CHANGELOG.md` 미출시 절 +> 깊게 본 관점: 11, 12, 10, 21, 17, 28 +> 이번 렌즈: 1103/05-01 잔여와 1105/05-01 수정이 완료 기준을 채웠는가, 수정이 검사를 약하게 했는가(특히 `orphanExemptRows`), 수정이 새 결함을 만들었는가 +> 영역 판정(35.8): **조건부 사용 가능.** kernel과 Web Storage 어댑터는 기본 구성에서 쓸 수 있다. **OPFS 개인 파일 저장은 지난 라운드 "사용 보류"에서 "조건부 사용 가능"으로 올린다.** 승인된 LOGOUT·ACCOUNT_DELETION이 객체를 끝까지 돌면 이제 늘 partition을 지운다. 그래서 다른 탭이 저장 중인 새 파일과 키를 잃은 멈춘 put의 bytes가 남지 않는다. 메모리 런타임 50/50, 실제 Chromium·Firefox 24/24에서 그 직후 파일 0·`NOT_FOUND`였다(05-R1·05-R2). 다른 탭의 reconcile과 partition 삭제가 겹쳐도 bytes가 남지 않았다(05-R1 Y3, 2/2). 조건: 모든 승인 purge가 다른 탭의 진행 중 put을 기다린다(상한 10분, 넘으면 retryable `BLOCKED`). WebKit에서는 기본 정책이 OPFS 런타임을 거절한다. 손상 chunk reference 행 하나가 reconcile을 멈추는 것(0929/05-01 ③)은 그대로다. + +ID 표기: 이번 라운드 새 발견은 `05-NN`(밖에서는 `1106/05-NN`). 지난 라운드(2026-11-05)는 `1105/05-NN`, 그 전은 `1103/05-NN`, `1101/05-NN`, `0929/05-NN`이다. 배치 요청은 `05-R1`~`05-R4`다(요청 파일 `scratchpad/r5/requests/05.md`). + +## 0. 결론 + +- **이 영역은 `8a44226..bbde570` 사이 수정 커밋 2개로 바뀌었다.** `23662fb`(1103/05-01 잔여)와 `dc7c95b`(1105/05-01)다. src 쪽 영역 diff는 4파일 +81/−59줄이다(`opfs-byte-store-adapter.ts`, `opfs-ports.ts`, `storage-keys.ts`, 영역 02의 `cache-storage-ports.ts`). kernel(`src/adapters/platform/`), `browser-file-storage/`, Web Storage 어댑터·codec, IndexedDB 런타임, OPFS journal·worker는 한 줄도 바뀌지 않았다(`git diff --stat` 출력 없음). +- **1103/05-01은 고쳐졌다(완료 기준 확인).** 객체를 끝까지 돈 purge는 chunk sweep을 하지 않고 늘 partition 삭제로 끝난다(`opfs-byte-store-adapter.ts:900`, `:926-929`). 그 삭제는 exclusive partition lock을 쥐고 진행 중인 put을 기다린 뒤 디렉터리(staging 포함)와 행을 지운다(`:931-946`). 지난 라운드 실험 Y1a·Y1b·Y2가 저장소 테스트가 되었고 `bbde570`에서 통과한다(FE-GATE-005, `opfs-worker-runtime.test.ts` 89건). 완료 기준의 반복 조건도 확인했다: + - 05-R1(메모리): Y1b 객체 0·1·2·3·8개 각 10회 → **50/50** `partitionDeleted: true`, `chunkSweep: null`, 파일 0, `NOT_FOUND`. 다음 reconcile 뒤에도 50/50 파일 0·`NOT_FOUND`. Y1a도 같다. + - 05-R2(실제 Chromium·Firefox): 객체 0·1·3·8개 × 3회 × 2엔진 → **24/24** `partitionDeleted: true`, 파일 0, `NOT_FOUND`. 지난 라운드는 객체 3·8개에서 6/6 `OPENED`였다. + - 05-R3: 수정을 되돌리면 이 수정이 더하거나 바꾼 테스트 8건이 실패한다(객체 3·8개 Y1b, Y1a, Y2 포함). 새 테스트 중 되돌린 코드에서도 통과하는 것은 객체 1개 Y1b와 예산 호출 테스트뿐이다. 이 둘은 2026-11-03 수정으로도 통과하는 순서다. +- **reconcile과 partition 삭제의 겹침(2026-11-03부터 미검증)도 bytes를 남기지 않았다(05-R1 Y3).** reconcile은 partition lock을 쥐지 않는다(`opfs-byte-store-adapter.ts:637-690`). 그래서 다른 탭의 roll-forward 중간에 삭제가 끼었다. `commitPut` 전에 끼면 reconcile이 `failedTransactions: 1`로 끝났다. 뒤에 끼면 `committedTransactions: 1`로 끝났다. 두 경우 모두 파일 0, 객체 `NOT_FOUND`, journal 행 없음이었다. 뒤의 경우 reconcile report는 "commit 1"이라 적지만 그 객체는 이미 지워졌다. 그 순간에는 사실이라 결함으로 세지 않는다. +- **1105/05-01은 고쳐졌다.** recipe 키가 registry 행 `AUTH_REDIRECT_TRANSACTION`의 `physicalKey`다(`oidc-pkce-session-owner.ts:51-52`, `storage-keys.ts:146-157`). 그래서 `APP_NAMESPACE`를 바꾸면 이 키도 바뀐다(`storage-keys.ts:1`, `:205`). 다만 이 키를 다시 글자로 적는 회귀는 테스트가 잡지 못한다. 지금 namespace에서는 두 문자열이 같기 때문이다(`oidc-pkce-session-owner.test.ts:197-204`). +- **`orphanExemptRows`에 `AUTH_REDIRECT_TRANSACTION`을 더한 것은 템플릿 게이트를 약하게 하지 않는다(05-R4로 확인).** orphan 검사는 `src`와 `tests`의 글자를 찾는다(`check-registries.ts:621-658`, `registry-governance.json:375`). `tests` 두 파일이 이 이름을 쓴다(`storage-registry.test.ts:208`, `oidc-pkce-session-owner.test.ts:200`). 예외를 빼고 돌려도 템플릿의 `check:registries`는 `11 registries PASS`였다. 예외가 실제로 바꾸는 것은 `src`만 복사해 검사하는 테스트 하나다(`second-api-feature-registries.test.ts:201-212`). 예외를 빼면 그 테스트만 `FE-REG-STORAGE.AUTH_REDIRECT_TRANSACTION has no executable consumer`로 실패했다. **다만 커밋이 적은 이유는 반만 맞다.** `QUERY_PERSISTENCE`(`disabled`)·`AUTH_TOKEN`(`forbidden`)은 "쓰는 곳이 없어야 하는" 선언 행이다. 이 행은 recipe가 실제로 쓰는 `external` 키다. 비교할 행은 `CACHE_INVALIDATION_PULSE`이고, 그 행은 src에 사용처가 있어 예외가 아니다. 버린 대안의 이유("레시피를 지운 사본에서 사용처가 사라진다")도 맞지 않는다. 그 사본에도 `tests/unit/storage-registry.test.ts`가 남는다(`test-optional-recipe-removal.ts:38-41`). 피해가 없어 새 발견으로 세지 않는다(2절, 4절 21번). +- **수정이 검사를 약하게 한 곳은 없다.** 테스트에서 지운 단언은 모두 더 강한 형태로 바뀌었다. 객체 1개 X1 → 1·3·8개(`opfs-worker-runtime.test.ts:2320`), `chunkSweep: "COMPLETED"` 기대 → `partitionDeleted: true` + `chunkSweep` 없음 + 파일 0(`:2256-2268`, `:2301-2308`, `:2679-2685`). 브라우저 X1은 0개 → 0·3개다(`opfs-runtime.spec.ts:337`). skip·timeout·임계값 변경은 없다. +- **새 발견은 1건이다. Low 1. High 이상과 P1은 없다.** 05-01: 저장소 설계 문서가 registry 행을 8개 중 4개만 "현재 등록되어 있다"고 적는다(`docs/architecture/client-cache-and-storage.md:50-52`). +- **kernel 경계는 그대로다.** `src/adapters` 안에서 바뀐 import는 `contracts` 두 줄뿐이다(영역 02·03 파일). `.dependency-cruiser.json`의 kernel 규칙은 바뀌지 않았다(바뀐 것은 `feature-and-app-roots-do-not-reach-adapters` 하나). FE-GATE-010의 `check:architecture`·`check:adapter-inventory`·boundaries(34건 거절) PASS. +- **README §16.6은 이 영역의 열린 이월 6건(0929/05-01·05-05·05-06·05-07·05-10, 1101/05-06)을 적지 않았다.** 이번 조치에서 손대지 않았고 코드도 그대로다(2절). + +## 1. 범위 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` 영역 05 | +| 커밋·작업 상태·확인 시점 | `bbde570`, 2026-11-06. 노트북 worktree(HEAD = 기준)에서 읽기만 했다. 실행은 desktop(같은 커밋)에서 오케스트레이터 배치로만 했다(04:32~04:33, 항목마다 checkout 복원 clean) | +| 목적과 지원 실행 구성 | 템플릿(참고 구현). 브라우저 SPA + 정적 호스팅 + Service Worker. 여러 탭 동시 실행. SSR 없음 | +| 조합 상태 | 기본 bootstrap이 조립하는 것은 Web Storage 어댑터와 kernel의 mutation intent factory·lifecycle runtime이다(지난 라운드와 같음, `runtime-adapters.ts`의 영역 관련 줄은 바뀌지 않음). IndexedDB·OPFS·StorageManager 런타임은 `AVAILABLE_NOT_COMPOSED` 레시피다. OIDC PKCE session owner도 레시피다 | +| 필수 요구와 규모·운영 목표 | 규모·운영 목표는 없다(13·14번 미검증). 데이터 요구: OPFS 정책 예시가 `PERSONAL`·`PURGE_PARTITION`이다. port 계약 "For these two reasons the partition's bytes are gone exactly when this is set"(`opfs-ports.ts:171-183`)을 이 영역의 필수 계약으로 본다. Web Storage 키는 registry가 만든다는 규칙(`docs/contracts/compatibility.md:31`)도 본다 | +| 읽은 코드·구성 범위 | `8a44226..bbde570`의 영역 diff 전부(`23662fb`, `dc7c95b`). `enforcePolicies` 전체(`opfs-byte-store-adapter.ts:730-966`), put 흐름의 lock 순서(`:177-240`, `:1109-1183`), reconcile의 lock과 FILES_READY 경로(`:637-690`, `:1250-1305`), worker `finalizePut`(`opfs-worker-runtime.ts:951-998`), journal `begin`의 세대 검사(`indexeddb-opfs-journal.ts:385-405`), 정책 검사(`shared.ts:222-296`), `check-registries.ts` orphan 검사(`:361-393`, `:621-658`), recipe 제거 드릴(`test-optional-recipe-removal.ts:29-90`), 지난 발견이 가리킨 위치 전부 | +| 주장으로만 읽은 것 | 커밋 본문 2개, README §16.3·§16.4·§16.5·§16.6, `CHANGELOG.md:30`, `:72-73`, runbook §0·§7, `docs/architecture/client-cache-and-storage.md`, 매뉴얼 `04-paired-backend-session.md:47` | +| 수행한 테스트·실험 | 노트북: 정적 읽기, `git diff`·`git grep`. 게이트 증거는 desktop에 이미 있는 것을 읽었다: `bbde570-ci/summary.txt`와 gate 로그 FE-GATE-005·007·008·010·012·020(모두 2026-11-06 03:24~03:56, CI env). 오케스트레이터 배치(local env): 05-R1 실험(메모리, Y1a·Y1b 50회·Y3 2경우), 05-R2 실험(Chromium·Firefox, 24회), 05-R3 변이(수정 되돌림), 05-R4 변이(orphan 예외 제거). 6.3절 | +| 확인하지 못한 범위·이유 | N-1 탭(`23662fb` 전 adapter) 공존, WebKit의 OPFS 런타임(기본 정책이 지원을 거절해 spec이 일찍 끝남, `opfs-runtime.spec.ts:352`), 0929/05-05·05-06·05-07·05-10·1101/05-06의 재현(파일이 바뀌지 않아 정적 확인만) | +| 이전 리뷰와 비교 가능한 범위 | 지난 라운드 영역 문서의 발견 14건(2절 13건 + 새 05-01)을 이 커밋의 코드와 이 커밋의 gate 로그로 다시 판정했다. 지난 라운드의 실행 결과(Y1·Y2, 05-R2, 변이 15개)와 조치 라운드의 RED 실행은 증거로 쓰지 않았다 | + +## 2. 지난 발견 재확인 + +상태: **고쳐짐**(완료 기준을 코드와 실행으로 확인) / **일부**(남은 것을 적음) / **남음** / **재발** / **틀린 발견**. 심각도는 지난 판정이다. 완료 기준은 2026-11-05 영역 문서 2.1절·3절이다. + +| 지난 ID | 내용 | 상태 | 근거 | +|---|---|---|---| +| 1105/05-01 | OIDC PKCE recipe가 Web Storage 키를 registry 밖에서 글자로 만들어 `APP_NAMESPACE`를 바꾸면 갈라진다 (Low·P3) | 고쳐짐 | 완료 기준 세 조건: ① recipe 키가 registry 행에서 온다. `OIDC_PKCE_TRANSACTION_KEY = STORAGE_REGISTRY.AUTH_REDIRECT_TRANSACTION.physicalKey`(`oidc-pkce-session-owner.ts:51-52`). 쓰기·읽기·지우기가 모두 이 상수다(`:191`, `:474`, `:551`, `:571`). ② registry에 `external` 행이 있다(`storage-keys.ts:146-157`). `defineStorageKey`가 `buildPhysicalKey`로 키를 만든다(`:191-197`). StoragePort는 거절한다(`:218-220`, 테스트 `storage-registry.test.ts:203-239`). ③ `APP_NAMESPACE`를 바꾸면 같이 바뀐다(`storage-keys.ts:1`, `:205`, 코드 읽기). 테스트 `oidc-pkce-session-owner.test.ts:197-204`가 저장된 키 = registry 키를 본다. FE-GATE-007(32건)·FE-GATE-005 통과. 매뉴얼 복사 규칙(`../../src/` → `../`)이 새 import에도 맞는다(`04-paired-backend-session.md:47`). CHANGELOG [계약] 행이 있다(`CHANGELOG.md:72`). **남는 약점(결함으로 세지 않음)**: recipe를 다시 `"ca-frontend:auth:v1:oidc-pkce-transaction"`로 되돌려도 이 테스트는 통과한다. 지금 namespace에서 두 문자열이 같다. 지난 라운드 문서의 검증 방법이 이 약점을 가졌다. `orphanExemptRows` 판정은 아래 2.1절 | +| 1103/05-01 | 승인된 LOGOUT·ACCOUNT_DELETION이 journal 행을 한 순간만 세서, 세기 전에 끝난 새 객체 put(①)과 키를 잃은 행(②)의 bytes를 남긴 채 `COMPLETED`를 보고한다 (Medium·P2, OPFS 개인 파일 제품 P1) | **고쳐짐** (완료 기준을 코드·게이트·05-R1·05-R2로 확인, 통제는 05-R3으로 M3) | **코드**: `walkFinished = !moreObjectsAvailable && !deadlineReached`(`opfs-byte-store-adapter.ts:900`). 끝까지 돈 purge는 journal을 세지 않고(`:908`) 바로 partition 삭제로 간다(`:926-929`). chunk sweep 경로는 지워졌다(`git show 23662fb`). 삭제는 exclusive partition lock 안에서 디렉터리와 행을 지운다(`:931-946`). put·delete는 `begin`부터 끝까지 같은 lock을 shared로 쥔다(`:1127`). 그래서 ①의 put은 삭제 전에 끝나고 삭제가 그 결과를 지운다. ②의 staging은 partition 디렉터리 안에 있어 함께 지워진다. 끝까지 못 돈 호출(예산·CONFLICT)은 전과 같이 세고, 행이 있으면 바로 삭제하고, 없으면 `moreObjectsAvailable: true`다(`:908-916`, `:950-955`). port 문장이 코드와 맞다(`opfs-ports.ts:171-183`). `chunkSweep`은 `@deprecated`이고 아무도 채우지 않는다(`:154-165`, `git grep chunkSweep`에 src 생산 코드 0). fake도 늘 `partitionDeleted`다(`browser-file-storage-fakes.ts:1927-1942`). runbook이 새 동작을 적는다(`browser-file-storage-recovery.md:454-473`, `:510-518`). CHANGELOG [계약] 행(`CHANGELOG.md:73`).
**실행(`bbde570`, 게이트)**: 완료 기준의 시나리오가 저장소 테스트가 되었다. Y1b 객체 1·3·8개(`opfs-worker-runtime.test.ts:2320-2357`, 파일 0 `:2354`, `NOT_FOUND` `:2355`), Y1a(`:2362-2409`), Y2(`:2559-2626`, purge 두 번과 reconcile 사이마다 파일 0), 예산에 걸린 호출(`:2414-2474`). FE-GATE-005에서 89건 모두 통과(`FE-GATE-005.txt:80`, `:436`). 브라우저 X1이 객체 0·3개로 늘었다(`opfs-runtime.spec.ts:337-447`). FE-GATE-008에서 Chromium·Firefox 통과(`FE-GATE-008.txt:261`, `:265`, `:284`, `:292`). WebKit은 지원 판정에서 `return`한다(`:352`).
**완료 기준과의 차이**: 기준은 "Y1b 각 10회, 05-R2 Chromium 객체 0·1·3·8개"와 "그 직후와 다음 reconcile 뒤 파일 0·`NOT_FOUND`"(1103 기준)다. 저장소 테스트는 Y1b를 1회씩, reconcile 없이 돈다. 브라우저 spec은 객체 1·8개가 없고 파일 수를 보지 않는다. 새 코드에서는 끝까지 돈 purge의 결과가 put이 언제 끝났는지에 따라 갈리지 않는다(늘 삭제). 그래서 반복의 의미는 작다. 그래도 기준대로 배치로 돌렸다.
**배치(6.3절)**: 05-R1 Y1b 객체 0·1·2·3·8개 각 10회 → 50/50 `{partitionDeleted: true, chunkSweep: null, more: false, late: "NOT_FOUND", files: 0}`, reconcile 뒤에도 50/50 `NOT_FOUND`·0. Y1a → report `{inspectedObjects: 1, removedObjects: 1, moreObjectsAvailable: false, partitionDeleted: true}`, 파일 `[]`, reconcile 뒤에도 `[]`·`NOT_FOUND`. 05-R2 Chromium·Firefox 객체 0·1·3·8개 × 3회 → 24/24 `partitionDeleted: true`, `files: 0`, `opened: "NOT_FOUND"`(지난 라운드 객체 3·8개 6/6 `OPENED`). 05-R3 수정을 되돌리면 `opfs-worker-runtime.test.ts` 8건 실패, 모두 report에 `partitionDeleted: true`가 없다는 이유다.
**README §16.5 "고침"과 같은 판정이다** | +| 0929/05-01 | journal·staging 손상 한 건이 계정 삭제 purge와 reconcile·GC를 멈춘다 (Medium·P2) | **일부** (README §16.6에 없음) | ①·②는 지난 라운드와 같다. **③은 그대로다**: 손상 chunk reference 행은 `isChunkReferenced`가 `CORRUPT_DATA`로 실패한다(`indexeddb-opfs-journal.ts:855-862`). GC가 그 실패를 그대로 돌려준다(`opfs-byte-store-adapter.ts:1396-1401`). reconcile은 앞에서 처리한 결과를 버리고 실패한다(`:702`). 바뀐 것: purge는 이제 sweep을 하지 않으므로 ③이 purge를 건드리지 않는다. 지난 라운드에도 purge 쪽은 partition 삭제로 빠져나갔다 | +| 1101/05-06 | Web Storage 어댑터·codec 분기 5개를 테스트가 잡지 못한다 (Low·P3) | **일부** (README §16.6에 없음) | W2(TTL 모양 검사, `browser-storage-adapter.ts:123`), W5(`__proto__` 등 키 거절, `browser-storage-codec.ts:204`), W6(accessor 거절, `:205-206`)를 보는 테스트가 여전히 없다. codec을 직접 부르는 테스트 0개(`git grep browser-storage-codec -- tests` 출력 없음). 두 파일과 Web Storage 테스트는 `8a44226` 뒤 바뀌지 않았다. `storage-registry.test.ts`에 더해진 테스트는 1105/05-01의 것이다. 정적 판단(E1). 지난 라운드 변이 결과는 다시 쓰지 않았다 | +| 0929/05-05 | IndexedDB 전체 삭제 경로가 롤백 중 계정 삭제에 쓰이지 않는다 (Low·P3) | 남음 (README §16.6에 없음) | 전체 삭제 조건이 `POLICY_REJECTED`·`CORRUPT_DATA`뿐이다(`indexeddb-runtime.ts:2580-2586`). N-1 탭은 `VersionError`를 `INCOMPATIBLE`로 바꾼다(`:663-672`). 파일 변경 없음 | +| 0929/05-06 | 두 런타임이 삭제 승인 계약을 다르게 요구 (Low·P3) | 남음 (README §16.6에 없음) | proof 정규식 `{16,128}`(`indexeddb-runtime.ts:97`) 대 `{16,512}`(`opfs-byte-store-adapter.ts:1930`) | +| 0929/05-07 | canonical JSON 3벌, `sameScope` 2벌 (Low·P3) | 남음 (README §16.6에 없음) | `stableJson` `opfs-prepared-object.ts:138`, `public-cache-codec.ts:637`, `canonicalJson` `realtime/event-codec.ts:414`. `sameScope` `indexeddb-opfs-journal.ts:1428`, `opfs-worker-runtime.ts:1690`. `hasPartitionKey`(`indexeddb-opfs-journal.ts:980`)도 그대로 | +| 0929/05-10 | OPFS journal DB 접두사를 바꿀 수 없다 (Low·P3) | 남음 (README §16.6에 없음) | `indexeddb-opfs-journal.ts:131` `ca-frontend-opfs-metadata-v1:`, `indexeddb-governance.ts:83` `ca-idb-v1:` | +| 1103/05-02 | partition lock 기다림이 abort를 무시하고 상한이 없다 (Low·P3) | 고쳐짐 유지 | put·remove가 signal을 넘긴다(`opfs-byte-store-adapter.ts:225`, `:500`). `withPartitionLock`의 abort·상한(`:1148-1183`) 그대로. 테스트 `opfs-worker-runtime.test.ts:3101`, `:3149` 통과(FE-GATE-005) | +| 1103/05-03 | 키 없는 손상 행이 `DEGRADED`를 영원히 남긴다 (Low·P3) | 고쳐짐 유지 | `DEGRADED`는 지울 수 있는 손상 행이 있을 때만(`opfs-byte-store-adapter.ts:715-717`). runbook이 새 동작에 맞게 고쳐졌다: 그 행의 staging은 이제 partition 삭제가 지운다(`browser-file-storage-recovery.md:45-55`). 테스트 `opfs-worker-runtime.test.ts:2823` 통과 | +| 1103/05-04 | recipe fake의 reconcile이 런타임과 다르다 (Low·P2) | 고쳐짐 유지 | parity 테스트가 그대로이고 purge 기대값도 런타임과 같다(`browser-file-storage-contracts.test.ts:941-958`). FE-GATE-007 13건 통과 | +| 1101/05-04 | kernel 폴더의 bootstrap 전용 파일 2개가 폴더 예외를 받는다 (Low·P3) | 고쳐짐 유지 | `layers.md`의 kernel 절은 바뀌지 않았다(바뀐 줄은 다른 규칙 행 하나, `git diff`). 남는 위험은 4절 22번 | +| 0929/05-08 | kernel 범위 설명이 실제보다 좁다 (Low·P3) | 고쳐짐 유지 | `ls src/adapters/platform` 10개 파일 그대로, 문서 그대로 | +| 0929/05-09 | `putIdleTimeoutMs < mutationLockWaitTimeoutMs`가 주석에만 있다 (Low·P3) | 고쳐짐 유지 | `opfs-policy.ts:112` 그대로(파일 변경 없음) | + +README §16.6에 없는 6건(0929/05-01·05-05·05-06·05-07·05-10, 1101/05-06)은 지난 영역 문서 2절에서 "일부"·"남음"이었다. §16.6은 "영역 문서 2절 '남음'"을 모은다고 적지만 이 영역 것은 빠졌다. 상태 판정이 갈린 것은 아니다. 조치 대상 목록에서 빠진 것이다. + +### 2.1 `orphanExemptRows`에 `AUTH_REDIRECT_TRANSACTION`을 더한 것 (`dc7c95b`, README §16.3) + +| 질문 | 판정 | 근거 | +|---|---|---| +| 검사를 약하게 했나 | **템플릿 게이트 결과는 바꾸지 않는다(05-R4로 확인).** 새 발견으로 세지 않는다 | orphan 검사는 행의 `logicalName`이 `consumerDirectories`(`src`, `tests`) 파일 글자 안에 있는지만 본다(`check-registries.ts:621-658`, `registry-governance.json:375`). 주석과 테스트도 사용처로 센다. 이 이름은 `tests/unit/storage-registry.test.ts:208`, `:224-237`과 `tests/recipes/oidc-pkce-session-owner.test.ts:200-203`에 있다. 05-R4: 예외를 빼도 `check:registries`는 `Registry governance: 11 registries PASS; compatibility=additive`, rc=0이었다. 예외가 실제로 바꾸는 실행은 `src`만 복사하는 `second-api-feature-registries.test.ts`다(`:201-212`가 `src`, `config/contracts`, `schemas/artifacts`, 스크립트 하나만 복사). 예외를 빼면 그 테스트 1건만 stderr `FE-REG-STORAGE.AUTH_REDIRECT_TRANSACTION has no executable consumer for logicalName=AUTH_REDIRECT_TRANSACTION`로 실패했다(`:246`). 같은 파일의 다른 1건은 통과했다. 이 행은 `dc7c95b` 전에는 없었으므로, 전에 검사받던 행이 검사를 잃은 것도 아니다 | +| 예외 이유가 맞나 | **반만 맞다** | 커밋 본문: "`AUTH_TOKEN`처럼 사용처 없이 선언만 하는 행이다". 그러나 기존 예외 둘은 `sensitive-forbidden` 행이다. `QUERY_PERSISTENCE`는 `backend: "disabled"`(`storage-keys.ts:95-106`), `AUTH_TOKEN`은 `backend: "forbidden"`(`:124-135`)이다. "이 저장은 하지 않는다"는 선언이라 쓰는 곳이 없는 것이 맞는 상태다. `AUTH_REDIRECT_TRANSACTION`은 `external`·`opaque-cache` 행이고 recipe가 실제로 쓴다(`oidc-pkce-session-owner.ts:551`). 같은 모양의 행은 `CACHE_INVALIDATION_PULSE`(`:112-123`)이고, 그 행은 src 사용처(`browser-cross-context-host.ts:37`)가 있어 예외가 아니다. 즉 이 예외는 "쓰는 곳이 검사 폴더 밖(`recipes/`)에 있다"는 새 종류다. 버린 대안(consumer 폴더에 `recipes` 추가)의 이유 "레시피를 지운 사본(FE-GATE-020)에서 다시 사용처가 사라진다"도 맞지 않는다. 그 드릴은 `recipes`와 `tests/recipes`만 지운다(`test-optional-recipe-removal.ts:38-41`). `tests/unit/storage-registry.test.ts`가 남아 이름을 계속 쓴다. 막힌 것은 `src`만 복사하는 테스트 하나다. CHANGELOG의 이유("사용처가 지울 수 있는 레시피뿐이라", `CHANGELOG.md:72`)는 사실이다 | +| 남는 위험 | 작다 | 예외는 이유 칸 없이 영구다(JSON에 이유를 둘 자리가 없다). 레시피와 그 registry 테스트 줄까지 지운 다운스트림에서는 쓰이지 않는 행이 신호 없이 남는다. StoragePort가 이 키를 거절하고 아무도 쓰지 않으므로 데이터 피해는 없다. orphan 검사의 약한 곳은 이 예외가 아니라 검사 방식(글자 찾기, 테스트·주석 포함)이다. 이것은 registry 검사 전체의 성질이라 영역 07·12에서 본다(4절 21번) | + +## 3. 이번 발견 (36.3) + +새 발견 1건: Low 1 · P3 1 · 확인된 결함 1. Critical·High·Medium 0, P0·P1·P2 0. 구조적 위험·미검증·개선 제안은 새로 세지 않았다(미검증은 5절). 05-R1 Y3(reconcile과 partition 삭제의 겹침)은 bytes를 남기지 않아 새 발견이 아니다. + +| ID | 심각도 | 우선 | 성격 | 관련 관점 | 제목 | +|---|---|---|---|---|---| +| 05-01 | Low | P3 | 확인된 결함 | 9, 4, 15, 23, 5 | 저장소 설계 문서가 registry 행 8개 중 4개만 "현재 등록되어 있다"고 적는다 | + +### 05-01 저장소 설계 문서가 registry 행 8개 중 4개만 "현재 등록되어 있다"고 적는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 (문서와 코드 불일치, 정적 확인). 영역 14(문서)와 겹칠 수 있다. 같은 결함이면 하나로 합친다 | +| 관련 관점 | 9, 4, 15, 23, 5 | +| 근거 | ① 문서: "현재 `src/contracts/storage-keys.ts`에는 `COLOR_SCHEME`, `CHUNK_RELOAD_GUARD`, 금지된 `AUTH_TOKEN`과 비활성 `QUERY_PERSISTENCE`가 등록되어 있다"(`docs/architecture/client-cache-and-storage.md:50-52`). 기본 조립 표도 Web Storage를 그 둘만 적는다(`:1406-1407`). 결정 기록 VD-13도 "`COLOR_SCHEME`, `CHUNK_RELOAD_GUARD`만"이라 적는다(`docs/architecture/decisions/VD-13-client-cache-scope-and-persistence.md:66`).
② 코드: registry는 8행이다. `COLOR_SCHEME`, `LOCALE`, `CHUNK_RELOAD_GUARD`, `RELEASE_MISMATCH_RECOVERY`, `QUERY_PERSISTENCE`, `CACHE_INVALIDATION_PULSE`, `AUTH_TOKEN`, `AUTH_REDIRECT_TRANSACTION`(`storage-keys.ts:41-157`). `LOCALE`·`RELEASE_MISMATCH_RECOVERY`는 기본 조립에서 쓰인다(`create-application.ts:54-60`, `boot-release-recovery.ts:16`).
③ 이 문서는 그 뒤로도 고쳐졌다. `e98a980d`(1101/05-01 pulse 키)가 같은 문서의 `:82-85`만 고쳤다. `dc7c95b`(1105/05-01)는 행을 더했지만 이 문서를 고치지 않았다. 문서 머리의 기준일은 2026-07-28이다(`:12`). 그러나 "현재"라는 문장과 이후의 부분 수정이 섞여, 읽는 사람은 지금 목록으로 읽는다.
④ `verify:documentation`은 이 문장을 보지 않는다(줄 번호 참조가 아님) | +| 발생 조건 | 다운스트림이 이 문서로 앱의 Web Storage 키 목록을 정할 때. 예: 개인정보 점검, 로그아웃 때 지울 키 목록, 새 키 이름 충돌 확인 | +| 영향 | 목록이 절반이다. 기본 조립에서 쓰는 `LOCALE`·`RELEASE_MISMATCH_RECOVERY`와 외부 소유 키 둘(`pulse`, PKCE transaction)이 빠진다. 1105/05-01이 "registry가 앱의 Web Storage 키 목록"이 되게 고쳤는데, 그 목록을 설명하는 문서는 따라오지 않았다. 코드 동작에는 영향이 없다 | +| 심각도·우선순위 | Low · P3. 문서 불일치다. 정본은 `storage-keys.ts`이고 계약 표가 그쪽을 가리킨다(`docs/contracts/compatibility.md:31`) | +| 통제·증거 | "문서의 registry 목록이 코드와 같다" 규칙: **M0 확인**(이 문장을 보는 검사 없음) · E1 | +| 확실성과 남은 가정 | 문장과 코드는 파일로 확인했다. 다운스트림이 이 문서를 목록으로 쓰는지는 모른다 | +| 결정의 근거 | 적용 제외 — 문서를 코드에 맞추는 단순 수정이다 | +| 이해 비용 | 문서를 읽는 사람은 Web Storage 키가 넷이라고 믿는다. 실제 목록을 알려면 `storage-keys.ts`를 열어야 한다 | +| 최소 개선 방향 | `:50-52`의 목록을 지우고 "등록된 키는 `src/contracts/storage-keys.ts`의 `STORAGE_REGISTRY`가 정본이다"로 바꾼다. 목록을 문서에 두지 않으면 다시 갈라지지 않는다. `:1406-1407` 표와 VD-13 `:66`에는 기준일을 붙이거나 같은 문장으로 바꾼다 | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 문서 세 곳 몇 줄 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | 저장소 설계 문서와 VD-13에 registry 행을 나열한 "현재" 문장이 없거나, 있으면 8행 모두를 적는다 | +| 검증 방법 | `git grep -n 'COLOR_SCHEME' -- docs/architecture`로 남은 목록 문장을 찾는다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 재검증 결과 | 적용 제외 — 신규 | + +## 4. 28개 관점 판정 (36.2) + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가 + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +|---|---|---|---|---|---| +| 1 | 코드 성숙도 | 적용 | M3 / M3 | E2(FE-GATE-005 89건, 05-R1·05-R3) | P — purge 완료 판단이 "끝까지 돌았으면 삭제"로 단순해졌다(`opfs-byte-store-adapter.ts:900`, `:926-929`). 손상 chunk reference 행이 reconcile을 멈춘다(0929/05-01 ③) | +| 2 | 구조적 성숙도 | 적용 | M3 / M3 | E2(FE-GATE-010) | O — kernel 규칙 그대로. `src/adapters` 안 새 import는 `contracts`뿐. `check:architecture`·`check:adapter-inventory`·boundaries 34건 거절 PASS | +| 3 | 변경 용이성 | 적용 | M2 / M2 | E1, E2(FE-GATE-012) | P — `chunkSweep`을 지우지 않고 `@deprecated`로 남겨 읽는 코드가 깨지지 않는다(`opfs-ports.ts:154-165`). offline-indexeddb 레시피 37,644 / 38,500 gzip B(지난 37,714, −70 B) | +| 4 | 인지 부하 | 적용 | — | E1 | P — sweep 경로가 빠져 purge가 짧아졌다(−21줄). 판단 플래그는 여섯 개다(`walkFinished` 추가, `chunkSweep` 제거). 큰 파일 넷(1,880~2,641줄) 그대로. 설계 문서의 registry 목록이 절반이다(05-01) | +| 5 | 위험 가시성 | 적용 | M1 / M1 | E1 | P — port·runbook이 새 동작과 한계(모든 승인 purge가 다른 탭 put을 기다림)를 적는다(`browser-file-storage-recovery.md:510-518`). README §16.6이 이 영역의 열린 이월 6건을 빠뜨렸다 | +| 6 | 실패 성숙도 | 적용 | M3 / M3 | E2 | P — lock 기다림 취소·상한 유지(1103/05-02). 손상 chunk reference 행(0929/05-01 ③) | +| 7 | 운영 성숙도 | 적용 | M1 / M1 | E1 | P — 키 없는 행의 bytes는 이제 partition 삭제가 지운다. 행 자체는 count로만 남는다(05-03 설계). 선택형 런타임은 조합이 없어 경보 경로가 없다 | +| 8 | 디버깅 가능성 | 적용 | M2 / M2 | E1, E2 | O — purge report가 `partitionDeleted`와 `moreObjectsAvailable` 중 정확히 하나를 갖는다(`:950-955`). `removedObjects`가 삭제 전에 지운 객체만 센다는 것을 runbook이 적는다(`:492`) | +| 9 | 유지보수 성숙도 | 적용 | M2 / M1 | E1 | P — canonical JSON 3벌·`sameScope` 2벌(0929/05-07), 설계 문서 목록(05-01) | +| **10** | 테스트 성숙도 | 적용 | M3 / M3 | E2(FE-GATE-005·007·008, 05-R3·05-R4) | P — 지난 실험 Y1a·Y1b·Y2와 예산 호출이 저장소 테스트가 됐다. 브라우저 X1이 객체 0·3개. 수정을 되돌리면 8건이 실패한다(05-R3). 실패는 모두 report 단언에서 난다. 파일 0 단언은 그 뒤에 있어 이번 변이로는 따로 확인되지 않았다. Web Storage W2·W5·W6 테스트 없음(1101/05-06). recipe 키 테스트는 글자 회귀를 못 잡는다(1105/05-01 덧붙임). WebKit OPFS spec은 지원 판정에서 `return`해 통과로 센다(`opfs-runtime.spec.ts:352`) | +| **11** | 데이터 성숙도 | 적용 | M3 / M3 | E2(05-R1 50/50), E3(05-R2 Chromium·Firefox 24/24, FE-GATE-008) | P — **"승인된 계정 삭제가 완료를 보고하면 partition bytes 0" 규칙을 이제 지킨다**(1103/05-01). 다른 탭의 reconcile과 겹쳐도 지킨다(05-R1 Y3 2/2). IndexedDB 롤백 중 계정 삭제는 실패로 끝난다(0929/05-05) | +| **12** | 동시성 성숙도 | 적용 | M3 / M3 | E2(05-R1), E3(05-R2) | P — 끝까지 돈 purge가 exclusive partition lock으로 진행 중 put을 기다린 뒤 지운다(Y1b 50/50, 브라우저 24/24). reconcile은 partition lock을 쥐지 않는다(`:637-690`). 그래서 삭제와 겹친다. 그래도 bytes는 남지 않았다(Y3 `commitPut` 전·후 2/2. 지워진 행에 `commitPut`이 실패하고, `finalizePut`은 없는 디렉터리를 만들지 않는다 `opfs-worker-runtime.ts:965-995`). 저장소 테스트에 Y3 순서는 없다. N-1 탭 공존 미검증 | +| 13 | 확장성 | 적용 | — | E1 | ? — 규모 목표가 없다. partition 삭제는 예산이 없고, 이제 모든 완료 purge가 거친다 | +| 14 | 성능 성숙도 | 적용 | — | E2(FE-GATE-012) | ? — 목표가 없다. 승인 purge가 다른 탭의 진행 중 put을 최대 `mutationLockWaitTimeoutMs`(기본 10분)까지 기다린다(runbook `:517-518`) | +| 15 | 보안 성숙도 | 적용 | M2 / M2 | E2, E3 | P — 기본 구성은 Web Storage에 개인 데이터를 두지 않는다. PKCE transaction 키는 registry 행이 되었고 StoragePort가 거절한다. OPFS 계정 삭제 뒤 개인 파일이 남던 경로가 닫혔다. 승인 정규식 두 벌(0929/05-06) | +| 16 | 의존성 성숙도 | 적용 제외 | — | — | - — 외부 패키지 없이 브라우저 API만 쓴다 | +| **17** | API / Contract 성숙도 | 적용 | M2 / M2 | E2 | P — port 문장이 코드와 맞다(`opfs-ports.ts:171-183`). CHANGELOG [계약] 두 행(`:72-73`). 관찰(결함으로 세지 않음): recipe fake의 purge는 `budgetMs`·`maxObjects`를 흉내 내지 않고 늘 한 번에 끝난다(`browser-file-storage-fakes.ts:1906-1942`). fake로 테스트하는 다운스트림은 "`moreObjectsAvailable`이면 다시 부른다" 경로를 보지 못한다. 0929/05-06 | +| 18 | 배포 성숙도 | 적용 | M2 / M1 | E1 | P — `23662fb` 전 release 탭은 여전히 sweep으로 끝난다. 롤아웃 중 그 탭이 purge하면 이번에 닫은 틈이 그 탭에서 열린다(미검증). IndexedDB N-1 계정 삭제 실패(0929/05-05) | +| 19 | 설정 성숙도 | 적용 | M3 / M3 | E1 | P — timeout 관계 검사 유지(0929/05-09). 접두사 고정(0929/05-10) | +| 20 | 개발자 경험 | 다른 영역 | — | — | > — 영역 14 | +| **21** | Guardrail 성숙도 | 적용 | M3 / M2 | E2(FE-GATE-010·012·020, 05-R4) | P — 수정이 검사를 약하게 한 곳은 없다(0절). `orphanExemptRows` 추가는 템플릿 게이트 결과를 바꾸지 않는다(2.1절, 05-R4: 예외를 빼도 `check:registries` PASS). registry orphan 검사는 글자 찾기라 테스트·주석도 사용처로 센다(`check-registries.ts:621-658`, `AUTH_TOKEN`은 src 주석 `product-composition-contract.ts:54`에서 걸림) — registry 검사 전체의 성질이라 영역 07·12 몫. recipe 키가 registry에서 오는지 보는 검사는 테스트 하나이고 글자 회귀를 못 잡는다 | +| **22** | 추상화 성숙도 | 적용 | M2 / M2 | E1, E2 | P — kernel 문서가 실제와 맞다. 남은 위험: 폴더 예외라 adapter가 bootstrap 전용 kernel 파일 둘을 import해도 규칙이 막지 않는다(1101/05-04 잔여). 중복 helper(0929/05-07) | +| 23 | 일관성 | 적용 | M1 / M1 | E1 | P — 승인 정규식 두 벌(0929/05-06). `orphanExemptRows`에 성격이 다른 행이 섞였다(2.1절). 문서 목록(05-01) | +| 24 | 네이밍 / 의미 성숙도 | 적용 | M1 / M1 | E2 | O — 완료 신호가 `partitionDeleted` 하나가 되었다. `chunkSweep`은 늘 비어 있는 호환용 칸이라고 port가 적는다(`opfs-ports.ts:154-165`) | +| 25 | 조직 확장성 | 적용 | — | E0 | ? — 팀이 하나다 | +| 26 | Ownership 성숙도 | 적용 | — | E0 | ? — 선택형 런타임 조합이 없어 runbook 담당을 확인할 대상이 없다 | +| **27** | 삭제 가능성 | 적용 | M3 / M3 | E2(FE-GATE-020) | P — 레시피 제거·browser-file-storage 제거 드릴 PASS(`FE-GATE-020.txt:10400`, `:11291`). 기기 데이터 삭제는 OPFS 정상 경로의 틈이 닫혔다(05-R1·R2). 키 없는 journal 행은 남는다(05-03 설계, bytes 없음) | +| **28** | 회복 가능성 | 적용 | M2 / M2 | E2 | P — 키가 읽히는 손상 행과 키 없는 행의 bytes를 승인 purge가 partition째 지운다(Y2 테스트 `:2559`). 손상 chunk reference가 reconcile을 막는다(0929/05-01 ③) | + +적용 항목 26개(16 제외, 20은 영역 14): 충족 3(2, 8, 24), 부분 충족 19, 미충족 0, 미검증 4(13, 14, 25, 26). 지난 라운드의 11번 미충족 세부 규칙("계정 삭제 뒤 bytes 0")은 충족으로 바꿨다(05-R1·05-R2). + +## 5. 미검증 + +| 항목 | 이유 | 확인에 필요한 것 | +|---|---|---| +| reconcile과 partition 삭제의 겹침, `commitPut` 앞·뒤 말고 다른 지점 | 05-R1 Y3는 `commitPut` 앞·뒤 두 지점만 멈췄다. `verifyObject`·`finalizePut` 도중(worker origin lease 안)은 돌리지 않았다. 저장소 테스트에도 이 순서가 없다 | Y3 블록을 `tests/unit/opfs-worker-runtime.test.ts`로 옮기고 worker 단계 hook을 더함 | +| 05-R2의 파일 수 0의 뜻 | 세는 함수는 partition 디렉터리가 없으면 0을 돌려준다. 파일이 있을 때 세는지 대조 실행이 없다. report `partitionDeleted`와 `NOT_FOUND`가 같은 결론이다 | 삭제 전에 한 번 세는 대조 | +| N-1 탭(`23662fb` 전 adapter)과의 공존 | 실행하지 않음. 옛 탭은 sweep으로 끝나 이번 틈이 그 탭에서 남는다 | 이전 커밋 adapter와 현재 adapter를 같은 메모리 루트로 묶은 테스트 | +| WebKit의 OPFS 런타임 동작 | 기본 정책에서 지원 판정이 거절해 spec이 일찍 끝난다(`opfs-runtime.spec.ts:352`) | 정책을 바꾼 WebKit 실행 또는 지원 범위 문서화 | +| 0929/05-05·05-06·05-07·05-10, 1101/05-06 | 파일이 바뀌지 않아 정적 확인만 함 | 지난 라운드 재현·변이를 테스트로 옮김 | + +## 6. 실행 기록 + +### 6.1 노트북 정적 확인 + +| 명령 | 결과 | +|---|---| +| `git diff --stat 8a44226..bbde570 -- src/adapters/storage src/adapters/platform src/adapters/browser-file-storage src/contracts/storage-keys.ts src/application/ports/browser-file-storage` | 4파일 +81/−59. `opfs-byte-store-adapter.ts`(73줄), `opfs-ports.ts`(31), `storage-keys.ts`(22), `cache-storage-ports.ts`(14, 영역 02) | +| `git diff 8a44226..bbde570 -- src/adapters \| grep import` | 바뀐 import는 `contracts/external-contract-runtime.ts`, `contracts/diagnostics.ts` 두 곳(영역 02·03 파일). adapter 간 import 변화 0 | +| `git diff 8a44226..bbde570 -- .dependency-cruiser.json` | `feature-and-app-roots-do-not-reach-adapters` 하나만 바뀜. kernel 규칙 그대로 | +| `git diff 8a44226..bbde570 -- <영역 테스트 7파일> \| grep '^-'` | 지운 단언은 모두 더 강한 형태로 다시 있음(0절). skip·timeout 변경 0 | +| `git grep chunkSweep` | src 생산 코드에서 값을 채우는 곳 0. port 타입(`opfs-ports.ts:165`)과 테스트의 "없음" 단언만 | +| `git grep -n 'AUTH_REDIRECT_TRANSACTION' -- src tests` | src에는 registry 정의뿐. tests 두 파일에 있음(2.1절) | + +### 6.2 desktop 게이트 로그(같은 커밋, CI env, 인용) + +| 출처 | 결과 | +|---|---| +| `bbde570-ci/summary.txt` | FE-GATE-001~012, 020 rc=0. FE-GATE-013 rc=1(user namespace 없음, 이 영역과 무관) | +| `gate-artifacts/FE-GATE-005.txt` | unit 208파일 3,056건 통과(`:312-313`). 이 영역: `opfs-worker-runtime` 89(`:80`), `indexeddb-opfs-journal` 18, `opfs-byte-store` 24, `storage-registry` 27, `browser-storage-policy` 8, `indexeddb-runtime` 31, `second-api-feature-registries` 2 모두 ✓ | +| `gate-artifacts/FE-GATE-007.txt` | `oidc-pkce-session-owner` 32(`:99`), `browser-file-storage-contracts` 13(`:101`) ✓ | +| `gate-artifacts/FE-GATE-008.txt` | capability 69건 통과(`:315`). `opfs-runtime.spec.ts` 05-01 객체 0·3개가 Chromium(`:261`, `:265`)·Firefox(`:284`, `:292`)·WebKit(`:304`, `:310`, 지원 판정에서 `return`) 통과. `Browser capability evidence: PASS (23 cases x 3 engines, zero skipped)`(`:322`) | +| `gate-artifacts/FE-GATE-010.txt` | `check:architecture` PASS(`:2-6`), boundaries 34건 거절 PASS(`:76`), `check:registries` `11 registries PASS; compatibility=additive`(`:106`), `check:adapter-inventory` PASS(`:153`) | +| `gate-artifacts/FE-GATE-012.txt` | `offline-indexeddb:37644/38500` PASS(`:88`) | +| `gate-artifacts/FE-GATE-020.txt` | optional recipe removal PASS(`:10400`), browser file/storage runtime removal PASS(`:11291`) | + +### 6.3 desktop 배치 (오케스트레이터, `bbde570`, local env) + +요청 파일: `scratchpad/r5/requests/05.md`. 패치는 같은 폴더의 `05-R1.patch`~`05-R4.patch`다. 로그: `desktop:/tmp/claude-gates/r5/batch/out/R5-05-R1.log`~`R5-05-R4.log`. 항목마다 checkout을 복원했다(`restore=clean`). 대조 실행은 요청하지 않았다. 변이 없는 같은 파일이 `bbde570`에서 통과한 기록이 6.2절에 있다. + +| ID | 명령 | 변이 | rc | 결과 | 시간·부하 | +|---|---|---|---|---|---| +| 05-R1 | `node scripts/run-vitest.ts run tests/unit/opfs-worker-runtime.test.ts` | 테스트 끝에 실험 블록(Y1a + reconcile, Y1b 객체 0·1·2·3·8개 각 10회 + reconcile, Y3 reconcile을 `commitPut` 앞·뒤에 멈춤) | 0 | 97/97 통과(원래 89 + 실험 8). `R5OUT` 8줄. Y1a·Y1b 51회 모두 `partitionDeleted: true`, 파일 0, `NOT_FOUND`, reconcile 뒤에도 같음. Y3 두 경우 모두 purge `partitionDeleted: true`, reconcile 재개 뒤 파일 0·`NOT_FOUND`·행 없음 | 3.25초, 부하 4.21 | +| 05-R2 | `corepack pnpm exec playwright test --config playwright.capabilities.config.ts tests/browser-capabilities/opfs-runtime.spec.ts --project=chromium --project=firefox -g "R5-05" --reporter=list` | spec 끝에 브라우저 Y1(객체 0·1·3·8개 × 3회, 파일 수 포함) | 0 | 2/2 통과(Chromium 6.6초, Firefox 20.8초). `R5OUT browserY1-run` 24줄 모두 `put: true`, `partitionDeleted: true`, `moreObjectsAvailable: false`, `files: 0`, `opened: "NOT_FOUND"`(객체 수마다 6줄) | 23.1초, 부하 3.95 | +| 05-R3 | `node scripts/run-vitest.ts run tests/unit/opfs-worker-runtime.test.ts tests/recipes/browser-file-storage-contracts.test.ts` | adapter를 `8a44226` 내용으로 되돌림 | 1 | **검출.** `opfs-worker-runtime` 89건 중 8건 실패, recipe contracts 13건 통과(94/102). 실패: "removes the chunks of a LOGOUT-/ACCOUNT_DELETION-purged partition…" 2, "finishes a purge that walked more than one journal page", "waits for a put…(3 committed objects)"·"(8 committed objects)", "takes a new object another tab's put settles…", "leaves no bytes of a stopped put whose journal row lost its partition key", "reports a purge that skipped a changing object as unfinished". 이유는 모두 report에 `partitionDeleted: true`가 없음(`:2258`, `:2299`, `:2345`, `:2398`, `:2610`, `:2677`). "(1 committed objects)"와 "continues a purge the object budget stopped…"는 통과(기대대로) | 부하 3.57 | +| 05-R4 | `corepack pnpm check:registries; echo REGISTRIES_RC=$?; node scripts/run-vitest.ts run tests/unit/second-api-feature-registries.test.ts; echo SECOND_API_RC=$?` | `orphanExemptRows`에서 `AUTH_REDIRECT_TRANSACTION` 제거 | 0(echo로 끝남) | `Registry governance: 11 registries PASS; compatibility=additive`, `REGISTRIES_RC=0`. `second-api-feature-registries` 2건 중 1건 실패: "passes check-registries without edits outside the feature and its context"가 stderr `FE-REG-STORAGE.AUTH_REDIRECT_TRANSACTION has no executable consumer for logicalName=AUTH_REDIRECT_TRANSACTION`(`:246`). `SECOND_API_RC=1` | 1.28초, 부하 3.57 | + +**05-R1 `R5OUT` 줄** (`R5-05-R1.log`. 긴 칸은 줄였다. Y1b는 각 배열의 첫 원소이고, 10개 원소가 모두 같다): + +``` +R5OUT Y1a {"put":{"ok":true,"value":{"objectId":"object_late_0001","generation":1,"…":"…"}},"report":{"ok":true,"value":{"inspectedObjects":1,"removedObjects":1,"releasedBytes":3,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"openedAfterPurge":"NOT_FOUND","filesAfterPurge":[],"reconcile":{"ok":true,"value":{"inspectedTransactions":0,"failedTransactions":0,"corruptTransactions":0}},"openedAfterReconcile":"NOT_FOUND","filesAfterReconcile":[]} (긴 칸 줄임) +R5OUT Y1b n=0 [{"put":true,"removed":0,"partitionDeleted":true,"chunkSweep":null,"more":false,"late":"NOT_FOUND","files":0,"reconcileOk":true,"lateAfterReconcile":"NOT_FOUND","filesAfterReconcile":0}, …] (10개 원소, 모두 같음) +R5OUT Y1b n=1 [{"put":true,"removed":1,"partitionDeleted":true,"chunkSweep":null,"more":false,"late":"NOT_FOUND","files":0,"reconcileOk":true,"lateAfterReconcile":"NOT_FOUND","filesAfterReconcile":0}, …] (10개 원소, 모두 같음) +R5OUT Y1b n=2 [{"put":true,"removed":2,"partitionDeleted":true,"chunkSweep":null,"more":false,"late":"NOT_FOUND","files":0,"reconcileOk":true,"lateAfterReconcile":"NOT_FOUND","filesAfterReconcile":0}, …] (10개 원소, 모두 같음) +R5OUT Y1b n=3 [{"put":true,"removed":3,"partitionDeleted":true,"chunkSweep":null,"more":false,"late":"NOT_FOUND","files":0,"reconcileOk":true,"lateAfterReconcile":"NOT_FOUND","filesAfterReconcile":0}, …] (10개 원소, 모두 같음) +R5OUT Y1b n=8 [{"put":true,"removed":8,"partitionDeleted":true,"chunkSweep":null,"more":false,"late":"NOT_FOUND","files":0,"reconcileOk":true,"lateAfterReconcile":"NOT_FOUND","filesAfterReconcile":0}, …] (10개 원소, 모두 같음) +R5OUT Y3 {"pauseAt":"beforeCommit","putFailed":"UNAVAILABLE","rowPhaseBefore":"FILES_READY","reachedOrSettled":"PARKED","filesBeforePurge":"<5 files: staging receipt, chunk 2, manifest 2>","report":{"ok":true,"value":{"inspectedObjects":1,"removedObjects":1,"releasedBytes":3,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"filesAfterPurge":[],"reconciled":{"ok":true,"value":{"inspectedTransactions":1,"committedTransactions":0,"cleanedTransactions":0,"failedTransactions":1}},"filesAfterReconcile":[],"opened":"NOT_FOUND","rowAfter":null,"nextReconcile":{"ok":true,"value":{"inspectedTransactions":0,"failedTransactions":0}},"filesAfterNextReconcile":[],"openedAfterNextReconcile":"NOT_FOUND"} (긴 칸 줄임) +R5OUT Y3 {"pauseAt":"afterCommit","putFailed":"UNAVAILABLE","rowPhaseBefore":"FILES_READY","reachedOrSettled":"PARKED","filesBeforePurge":"<5 files: staging receipt, chunk 2, manifest 2>","report":{"ok":true,"value":{"inspectedObjects":2,"removedObjects":1,"releasedBytes":3,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"filesAfterPurge":[],"reconciled":{"ok":true,"value":{"inspectedTransactions":1,"committedTransactions":1,"cleanedTransactions":1,"failedTransactions":0}},"filesAfterReconcile":[],"opened":"NOT_FOUND","rowAfter":null,"nextReconcile":{"ok":true,"value":{"inspectedTransactions":0,"failedTransactions":0}},"filesAfterNextReconcile":[],"openedAfterNextReconcile":"NOT_FOUND"} (긴 칸 줄임) +``` + +**05-R2 `R5OUT` 줄** (`R5-05-R2.log`, 두 엔진이 동시에 돌아 줄이 섞였다. 엔진 표시는 없다. 객체 수마다 6줄 = 2엔진 × 3회): + +``` +R5OUT browserY1-run {"count":0,"run":0,"put":true,"report":{"ok":true,"value":{"inspectedObjects":0,"removedObjects":0,"releasedBytes":0,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"} +R5OUT browserY1-run {"count":0,"run":1,"put":true,"report":{"ok":true,"value":{"inspectedObjects":0,"removedObjects":0,"releasedBytes":0,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"} +R5OUT browserY1-run {"count":0,"run":2,"put":true,"report":{"ok":true,"value":{"inspectedObjects":0,"removedObjects":0,"releasedBytes":0,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"} +R5OUT browserY1-run {"count":1,"run":0,"put":true,"report":{"ok":true,"value":{"inspectedObjects":1,"removedObjects":1,"releasedBytes":1,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"} +R5OUT browserY1-run {"count":1,"run":1,"put":true,"report":{"ok":true,"value":{"inspectedObjects":1,"removedObjects":1,"releasedBytes":1,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"} +R5OUT browserY1-run {"count":0,"run":0,"put":true,"report":{"ok":true,"value":{"inspectedObjects":0,"removedObjects":0,"releasedBytes":0,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"} +R5OUT browserY1-run {"count":1,"run":2,"put":true,"report":{"ok":true,"value":{"inspectedObjects":1,"removedObjects":1,"releasedBytes":1,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"} +R5OUT browserY1-run {"count":3,"run":0,"put":true,"report":{"ok":true,"value":{"inspectedObjects":3,"removedObjects":3,"releasedBytes":3,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"} +R5OUT browserY1-run {"count":0,"run":1,"put":true,"report":{"ok":true,"value":{"inspectedObjects":0,"removedObjects":0,"releasedBytes":0,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"} +R5OUT browserY1-run {"count":3,"run":1,"put":true,"report":{"ok":true,"value":{"inspectedObjects":3,"removedObjects":3,"releasedBytes":3,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"} +R5OUT browserY1-run {"count":3,"run":2,"put":true,"report":{"ok":true,"value":{"inspectedObjects":3,"removedObjects":3,"releasedBytes":3,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"} +R5OUT browserY1-run {"count":0,"run":2,"put":true,"report":{"ok":true,"value":{"inspectedObjects":0,"removedObjects":0,"releasedBytes":0,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"} +R5OUT browserY1-run {"count":8,"run":0,"put":true,"report":{"ok":true,"value":{"inspectedObjects":8,"removedObjects":8,"releasedBytes":8,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"} +R5OUT browserY1-run {"count":8,"run":1,"put":true,"report":{"ok":true,"value":{"inspectedObjects":8,"removedObjects":8,"releasedBytes":8,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"} +R5OUT browserY1-run {"count":1,"run":0,"put":true,"report":{"ok":true,"value":{"inspectedObjects":1,"removedObjects":1,"releasedBytes":1,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"} +R5OUT browserY1-run {"count":8,"run":2,"put":true,"report":{"ok":true,"value":{"inspectedObjects":8,"removedObjects":8,"releasedBytes":8,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"} +R5OUT browserY1-run {"count":1,"run":1,"put":true,"report":{"ok":true,"value":{"inspectedObjects":1,"removedObjects":1,"releasedBytes":1,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"} +R5OUT browserY1-run {"count":1,"run":2,"put":true,"report":{"ok":true,"value":{"inspectedObjects":1,"removedObjects":1,"releasedBytes":1,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"} +R5OUT browserY1-run {"count":3,"run":0,"put":true,"report":{"ok":true,"value":{"inspectedObjects":3,"removedObjects":3,"releasedBytes":3,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"} +R5OUT browserY1-run {"count":3,"run":1,"put":true,"report":{"ok":true,"value":{"inspectedObjects":3,"removedObjects":3,"releasedBytes":3,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"} +R5OUT browserY1-run {"count":3,"run":2,"put":true,"report":{"ok":true,"value":{"inspectedObjects":3,"removedObjects":3,"releasedBytes":3,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"} +R5OUT browserY1-run {"count":8,"run":0,"put":true,"report":{"ok":true,"value":{"inspectedObjects":8,"removedObjects":8,"releasedBytes":8,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"} +R5OUT browserY1-run {"count":8,"run":1,"put":true,"report":{"ok":true,"value":{"inspectedObjects":8,"removedObjects":8,"releasedBytes":8,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"} +R5OUT browserY1-run {"count":8,"run":2,"put":true,"report":{"ok":true,"value":{"inspectedObjects":8,"removedObjects":8,"releasedBytes":8,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"} +``` + +판정에 쓴 것: + +- Y1a·Y1b·05-R2가 1103/05-01 완료 기준(2026-11-05 2.1절)을 채운다. 지난 라운드의 같은 실험은 객체 3·8개에서 메모리 20/20 `COMPLETED` + 파일 읽힘, Chromium 6/6 `OPENED`였다. +- Y3 `afterCommit`에서 purge의 `inspectedObjects`는 2, `removedObjects`는 1이다. [추론] reconcile이 commit한 객체의 remove가 아직 끝나지 않은 그 행 때문에 실패했고, 그래서 끝까지 못 돈 호출의 세기(2026-11-03 경로)가 partition 삭제로 보냈다. report의 `moreObjectsAvailable: false`·`partitionDeleted: true`와 맞는다. 그 뒤 재개된 reconcile은 `committedTransactions: 1, cleanedTransactions: 1`을 보고했지만 객체는 `NOT_FOUND`다. 그 commit은 삭제 전에 일어난 일이라 report가 틀린 것은 아니다. +- 05-R2의 `files: 0`은 partition 디렉터리가 없어서 나온 값일 수 있다(세는 함수가 그 경우 0을 돌려준다). 대조가 없으므로 판정은 `partitionDeleted`와 `NOT_FOUND`로 했다(5절). + +## 7. 새 발견 요약 + +| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line | +|---|---|---|---|---| +| 05-01 | Low · P3 | 확인된 결함 | 저장소 설계 문서가 registry 행 8개 중 4개만 "현재 등록되어 있다"고 적는다 | `docs/architecture/client-cache-and-storage.md:50-52`, `:1406-1407`; `docs/architecture/decisions/VD-13-client-cache-scope-and-persistence.md:66`; `src/contracts/storage-keys.ts:41-157` | + +이월 중 열린 것: 0929/05-01 일부(③), 1101/05-06 일부(W2·W5·W6), 0929/05-05·05-06·05-07·05-10 남음. 1103/05-01·1105/05-01은 고쳐짐(05-R1·05-R2·05-R3·05-R4). diff --git a/docs/reviews/2026-11-06-maturity-review/06-adapters-service-worker-push.md b/docs/reviews/2026-11-06-maturity-review/06-adapters-service-worker-push.md new file mode 100644 index 00000000..192b6107 --- /dev/null +++ b/docs/reviews/2026-11-06-maturity-review/06-adapters-service-worker-push.md @@ -0,0 +1,200 @@ +# 영역 06 — adapters: service worker, push + +> 검토일 2026-11-06 · 기준 `bbde570` (PR B 끝, `fix/maturity-review-2026-11-05-b`) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 경로: `src/adapters/service-worker/`, `src/adapters/web-push/`, `vite.service-worker.config.ts`, `tsconfig.service-worker.json`, `scripts/build-frontend.ts`(SW 부분), `scripts/generate-service-worker-assets.ts`, `scripts/lib/{service-worker-build-input,self-unregistering-service-worker,hosting-probe}.ts`, `scripts/verify-hosting-headers.ts`, `config/hosting/*.json`. 1103/09-05의 SW 쪽을 보려고 `src/bootstrap/{create-runtime-composition,optional-runtime-host,register-service-worker,product-composition-contract,runtime-adapters}.ts`도 읽었다 +> 깊게 본 관점: 10, 18, 21, 28 (그다음 7, 20) +> 렌즈: 1105 수정 3건과 1103/09-05가 완료 기준을 채우는가 / 이 영역 경로를 건드린 수정이 검사를 약하게 했는가 / 호스팅 probe가 브라우저의 워커 조건을 따라가는가 +> 영역 판정(35.8): 기본 구성(SW `null`) **지정 범위에서 사용 가능** · SW `ACTIVE` **조건부 사용 가능** · Web Push **조건부 사용 가능** (0절) + +ID 표기: 이번 라운드의 새 발견은 `06-01`부터 쓴다. 라운드 밖에서는 `1106/06-NN`이다. 지난 라운드(2026-11-05)는 `1105/06-NN`, 그 전은 `1103/`, `1101/`, `0929/`, `0925/`다. + +실행 방식: 이 리뷰는 아무것도 실행하지 않았다(BRIEF 2절). 근거는 이 커밋의 코드, desktop의 merge 단계 게이트 로그(`/tmp/claude-gates/bbde570-ci/`, CI env, 2026-11-06 03:24~03:56), 그 실행의 산출물 snapshot(`/tmp/claude-gates/r5/snap/merge/`), 오케스트레이터 공유 실행(`/tmp/claude-gates/r5/snap/`)이다. 실험 4건은 요청 파일 `scratchpad/r5/requests/06.md`로 냈다(`06-R1`~`06-R4`). 오케스트레이터가 desktop에서 하나씩 돌렸다(2026-11-06 04:23~04:24, 항목마다 `bbde570`로 되돌림, 4건 모두 restore clean). 로그는 `desktop:/tmp/claude-gates/r5/batch/out/R5-06-Rk.log`다. 06-R1은 오케스트레이터 실수(중복 runner를 중간에 죽임)로 두 번 돌았고, 로그는 깨끗한 재실행 것이다. 4건 모두 기대와 같았다(6절). + +## 0. 결론 + +| 구성 | 결정 | 조건·이유 | +| --- | --- | --- | +| 기본(SW `null`, Web Push 미선택) | 지정 범위에서 사용 가능 | 이 영역 런타임이 돌지 않는다. 빌드 로그가 `service worker mode null: skipping worker build`다(`r5/snap/build.txt:68`). 선택은 제품 소유 `src/features/product-capabilities.ts:34`의 `null`이다 | +| SW `ACTIVE` | 조건부 사용 가능 | (1) 활성화 화면(`onUpdateWaiting`·`requestActivation()`·`onReloadRequired`)을 잇는 제품 소유 자리가 없다. 붙이려면 템플릿 파일을 고친다(1103/09-05 일부, 0925/06-05 일부). (2) 업데이트 설치 실패는 신호가 없다(0925/06-05). (3) 호스팅이 `/service-worker.js`를 redirect하지 않는지 손으로 확인한다. probe는 같은 origin redirect를 통과시킨다(새 06-01). (4) `build.assetsDir`를 기본값으로 둔다(0925/06-08). (5) 하위 경로 호스팅 게이트는 13 영역 `0929/13-06`이다 | +| Web Push | 조건부 사용 가능 | 이 커밋에서 web-push 코드는 바뀌지 않았다. 서버의 짧은 TTL·send-time 인가 조건은 그대로다 | + +- **1105 발견 3건: 고쳐짐 2, 일부 1.** + - 06-01 고쳐짐. 수집기가 `BUILD_ASSET_DIRECTORY` 아래만 본다. 새 테스트가 루트 아이콘을 넣은 dist에서 manifest를 `/assets/` 두 줄로 정확히 단언하고, FE-GATE-005에서 통과했다. + - 06-02 일부. redirect FAIL과 live 분기 함수 테스트는 들어왔다. live 분기 함수에서 자산 probe를 빼는 변이를 테스트 1건이 잡는다(06-R2). 워커 없는 빌드에서 probe 범위는 결정 대기다. 그 범위는 이제 redirect까지 넓어졌다. + - 06-03 고쳐짐. 옛 탭 route test가 FE-GATE-008(CI env)에서 chromium·webkit 모두 통과했다. 워커가 직전 캐시로 답하지 않게 바꾸면 두 엔진 모두 실패한다(06-R1). 실패 이유는 `sameDocument: false`와 허용 밖 fixture 줄이다. +- **1103/09-05(SW 쪽) 일부.** blockers·observe는 제품 소유 `composeProduct`에서 잇는다. 실제 조립을 돌리는 component 테스트가 통과한다. 활성화 화면 자리는 없다. e2e 도우미는 여전히 템플릿 파일 `register-service-worker.ts`를 사본에서 고쳐 host에 닿는다. +- **그 밖의 이월 10건**: 0925/06-05는 남음 → 일부(observe 자리가 생김). 1101 R4는 고쳐짐(그 test가 8 ms). 나머지 8건은 남음. 0925/06-08은 남음이지만 영향 범위가 넓어졌다. 06-01 수정으로 사전 캐시 수집기도 같은 하드코딩 상수를 읽는다. +- **새 발견 2건, 모두 Low·P3. High·P1은 없다.** + - 06-01: live probe가 `/service-worker.js`의 같은 origin redirect를 통과시킨다. 브라우저는 워커 스크립트의 redirect를 모두 거절한다. 그래서 FE-GATE-019 PASS인데 등록·업데이트·`REMOVE_REGISTRATION` kill switch가 실패할 수 있다. + - 06-02: 1101/10-07 수정(`ce191be`)이 marker 읽기 시간 상한 test의 실효 상한을 10초(실제 시간)에서 20초(가짜 시간)로 넓혔다. 상한을 15초로 올린 변이에서 64건이 모두 통과했다(06-R3, 생존). 10 영역과 같은 결함이면 한 건으로 합친다. +- **약해진 검사**: 06-02 하나다. 그 밖에 이 영역 경로의 `git diff 8a44226..bbde570`에서 단언 삭제, 정규식·허용 목록 완화, 상한 상향은 찾지 못했다. `hosting-probe.test.ts`의 `platform-examples-feature` → `fixture-feature`는 기능 ID 이름 바꿈이다(14-01). 06-03 수정이 Firefox skip 하나를 더했다(`service-worker-update.spec.ts:306`). 기존 격리와 같은 이유·만료일을 쓴다. skip을 지우자 그 test는 격리 주석이 적은 이유로 실패했다(06-R4: `requestActivation()` → `NO_WAITING_WORKER`). 그래서 이 skip은 제품 결함을 가리지 않는다. +- **Firefox 격리(`expires=2027-03-31`)**: Playwright는 그대로 `1.62.0`이다(`package.json:170`). FE-GATE-008에서 Firefox는 4건 skip이다(`FE-GATE-008.txt:144`, `:154-156`). 이번에 다시 돌린 것은 새 skip 1건(06-R4)이다. 나머지 3건은 지난 라운드 06-R11 뒤로 spec·워커·Playwright가 바뀌지 않았다. 그 결과는 현재 증거로 쓰지 않았다. + +## 1. 범위 (36.1) + +| 항목 | 기록 | +| --- | --- | +| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` (템플릿, reference implementation) | +| 커밋·작업 상태·확인 시점 | `bbde570`, laptop worktree(HEAD = 기준, 추적 파일 변경 없음, 무시한 untracked `AGENTS.md`), 2026-11-06 04시. `git log 8a44226..bbde570 -- <영역 경로와 SW 조립 파일>` 9커밋: `1c7c614`(1105/06-01), `4d6f254`(1105/06-02), `aaa782b`(1105/06-03), `fdc1db9`(1103/09-05), `ce191be`(1101/10-07), `f4d5761`(1105/12-04 실행 격리), `332bfee`(문서 검사), 합친 커밋 2개. 이 영역 런타임 코드에서 바뀐 곳은 `service-worker-static-assets.ts`(상수 import)와 `src/contracts/service-worker.ts`(상수 추가) 두 파일이다. web-push 코드는 바뀌지 않았다 | +| 목적과 지원 실행 구성 | 브라우저 SPA + 정적 호스팅 + Service Worker. SW 선택 기본값 `null`(`product-capabilities.ts:34`). 템플릿 `installed-runtime-capabilities.ts`는 검사·투영만 한다. Web Push는 `NOT_SELECTED`이고 빌드가 `WEB_PUSH` handler를 거절한다(`scripts/lib/service-worker-build-input.ts`) | +| 필수 요구와 규모·운영 목표 | 합의된 SLO·업데이트 전파 목표는 없다. 사전 캐시 상한 256개·5 MiB(`src/contracts/service-worker.ts:13-16`) | +| 읽은 코드·구성 범위 | 경로 머리의 파일 전부와 수정 커밋 9개의 diff. 연결: `src/contracts/{service-worker,service-worker-static-manifest}.ts`, `src/bootstrap/*`(위 다섯 파일), `tests/e2e/service-worker-{update,recovery}.spec.ts`, `tests/e2e/support/service-worker-builds.ts`, `tests/support/browser/strict-browser-test.ts`, `tests/unit/{service-worker-runtime,service-worker-web-push-remediation,hosting-probe,service-worker-build-output}.test.ts`, `tests/component/runtime-composition-service-worker-product-wiring.test.ts` | +| 읽은 문서(주장) | `docs/operations/release-cache-rollback.md:60-99`, `:168-185`, `docs/operations/browser-file-storage-recovery.md:595-656`, `docs/architecture/optional-adapter-recipes.md:112`, `:127-174`, `docs/manual/03-outside-feature-folder.md:150-186`, 지난 라운드 README §15·§16, 수정 커밋 본문. 모두 주장으로 읽었다 | +| 실행 환경 | desktop 기존 증거만 읽었다. CI env merge 단계(`bbde570-ci/summary.txt`): FE-GATE-001~012·020 rc=0, 013 rc=1(이 영역 밖, 12-01). 이 영역이 쓴 것: FE-GATE-005(`gate-artifacts/FE-GATE-005.txt`, `test:unit` 208파일 3,056건 통과, `service-worker-runtime` 64·`hosting-probe` 39·`service-worker-web-push-remediation` 11·`service-worker-build-output` 7·`web-push-worker-runtime` 26, component `runtime-composition-service-worker-product-wiring` 1), FE-GATE-008(`gate-artifacts/FE-GATE-008.txt`, `test:e2e` 222 통과·4 skip, SW spec 줄 `:72-76`, `:86`, `:102`, `:120-121`, `:144-157`, `:206-231`), FE-GATE-020(`realtime-runtime-removal.xml` tests=7 failures=0, 2026-11-06 03:45). snapshot `merge/artifacts/tests/unit.xml`(03:46)의 test별 시간. 오케스트레이터 공유 실행: `verify-documentation.{local,no-sibling}.txt` 모두 `PASS_SCOPED`, `build.txt`. 요청 배치 06-R1~06-R4: local env, `r5/batch/out/R5-06-Rk.log`(6절). FE-GATE-019(release 단계)는 이번 실행에 없다. snapshot의 `hosting-headers.json`은 2026-11-05 20:09자라 쓰지 않았다 | +| 수행한 테스트·실험 | 이 리뷰는 직접 실행하지 않았다. 오케스트레이터 배치 4건(6절): e2e 워커 변이 1(06-R1), 단위 변이 2(06-R2, 06-R3), Firefox skip 해제 1(06-R4). 4건 모두 기대와 같았다 | +| 확인하지 못한 범위·이유 | 5절. 실제 CDN·푸시 서비스, live 모드 probe, 브라우저의 워커 스크립트 redirect 거절(일반 지식, 이 저장소에서 돌리지 않음), 하위 경로 브라우저 재확인 | +| 이전 리뷰와 비교 가능한 범위 | 지난 라운드 문서(`docs/reviews/2026-11-05-maturity-review/06-adapters-service-worker-push.md`)의 새 발견 3건, 2절 "남음" 이월 전부, README §16.5의 1103/09-05(SW 쪽)를 다시 봤다. §16.6에는 이 영역 행이 없다. 지난 실행 결과(06-R1~R11)는 현재 증거로 쓰지 않았다 | + +## 2. 지난 발견 재확인 + +상태: **고쳐짐** = 완료 기준을 이 커밋에서 확인 · **일부** = 남은 것을 적음 · **남음** = 코드 그대로 · **재발** · **틀린 발견**. + +| 지난 ID | 내용 | 상태 | 근거 (`bbde570`) | +| --- | --- | --- | --- | +| 1105/06-01 | 사전 캐시 수집이 `assets/` 밖 public 파일(`apple-touch-icon.png` 등)을 해시 자산으로 넣음 | **고쳐짐** | 수집기가 `BUILD_ASSET_DIRECTORY` 아래가 아닌 파일을 건너뛴다(`scripts/generate-service-worker-assets.ts:73-75`). 상수는 계약 모듈 한 곳이다(`src/contracts/service-worker.ts:118-126`). fallback(`service-worker-static-assets.ts:67-77`)과 probe(`scripts/lib/hosting-probe.ts:297`)도 같은 상수를 읽는다. 테스트(`tests/unit/service-worker-web-push-remediation.test.ts:133-157`)는 루트에 `apple-touch-icon.png`·`android-chrome-192x192.png`·`safari-pinned-tab.svg`·`icons/maskable-512x512.png`를 둔 dist에서 manifest URL이 `/assets/` 두 개와 **정확히 같다**고 단언한다. FE-GATE-005에서 그 파일 11건이 통과했다(`FE-GATE-005.txt:167`). 되돌리면 루트 아이콘이 목록에 들어가 `toEqual`이 깨진다(정적 확인). 레시피 문서도 맞다(`optional-adapter-recipes.md:166-171`). 완료 기준 충족. 남은 가정: `public/assets/`에 둔 파일은 Vite가 이름 그대로 `dist/assets/`에 복사하므로 여전히 이름만으로 해시 자산이 된다. 템플릿 `public/`에는 `config.json`·`release-manifest.json`뿐이라 지금은 해당이 없다(5절) | +| 1105/06-02 | 확장자별 MIME probe가 redirect 뒤 200을 통과시키고, 워커 없는 빌드에도 돌고, live 호출 줄을 테스트가 지키지 않음 | **일부** | ① redirect: 기본 fetcher가 `redirect: "manual"`이다(`hosting-probe.ts:291`). `response.redirected`이거나 `opaqueredirect`이면 `observed: "redirected"`로 FAIL이다(`:312-317`, `:326-329`). 3xx는 `HTTP 3xx`로 FAIL이다. 테스트가 둘 다 단언하고(`tests/unit/hosting-probe.test.ts:381-400`) FE-GATE-005에서 통과했다(39건, `FE-GATE-005.txt:76`). ③ live 분기: 스크립트는 `probeLiveHosting` 하나만 부른다(`scripts/verify-hosting-headers.ts:113-118`). 그 함수가 release surface와 자산 probe를 묶는다(`hosting-probe.ts:342-357`). 테스트가 fetcher 대역으로 그 함수를 돌려 CSS `text/plain` 한 줄만 FAIL인지 본다(`hosting-probe.test.ts:414-451`). **06-R2**: 그 함수에서 자산 probe 결과 줄(`hosting-probe.ts:354`)을 지우자 이 테스트 1건만 실패했다(`expected [] to deeply equal [ 'hashedAsset.css content-type' ]`, `:443`). 나머지 38건은 통과했다. 지난 라운드 06-R2와 같은 자리의 변이가 이제 잡힌다. 완료 기준 둘째 충족. 스크립트 쪽 호출을 빼면 `responses`가 비어 cache-control 행이 모두 FAIL이라 실행 중에 드러난다(`verify-hosting-headers.ts:137-148`, 정적 확인). 스크립트가 `distFiles` 대신 빈 목록을 넘기는 실수는 아무 검사도 잡지 않는다. 자산 probe는 표본이 0개면 행을 하나도 내지 않는다(`hosting-probe.ts:293-302`). ② 워커 없는 빌드: 동작은 그대로이고 의도를 주석과 문서에 적었다(`hosting-probe.ts:283-287`, `release-cache-rollback.md:81-86`). 범위를 좁힐지는 결정 대기다(README §16.4). 수정 뒤 이 범위가 넓어졌다. 워커 없는 제품도 같은 origin redirect로 FAIL하고, 그 이유 문구는 "the worker's install fetch refuses a redirected asset"이다(`hosting-probe.ts:327`). 문서는 워커 없는 빌드의 이유로 `nosniff`만 적는다. §16.4와 같은 판정이다 | +| 1105/06-03 | SW 제어 아래에서 route chunk를 import하는 browser 검사가 없음 | **고쳐짐** | 새 test(`tests/e2e/service-worker-update.spec.ts:302-350`)는 B가 제어하는 A 탭에서 client navigation으로 지워진 route를 연다. 단언은 넷이다. not-found 화면(`:332-334`), 같은 문서(전역 표시와 entry script, `:335-343`), 그 chunk의 Resource Timing 항목(`:339-341`), navigation 뒤 서버 요청에 그 chunk가 없음(`:344-346`). strict fixture의 teardown 검사도 돈다. FE-GATE-008(CI env)에서 chromium·webkit 모두 통과했다(`FE-GATE-008.txt:120`, `:230`). Firefox는 skip이다(`:156`). 완료 기준 첫째("제어 아래 route import를 reload 없이 단언") 충족. **06-R1**(`service-worker-lifecycle.ts:296`의 직전 캐시 응답을 `return null`로): 새 test가 chromium·webkit 모두 실패했다. 두 엔진 모두 `{ sameDocument: false, chunkRequested: false }`였다(`:342`). chunk 복구가 페이지를 B로 reload했다는 뜻이다. strict fixture도 허용 밖 줄 셋을 냈다. chromium은 console 404, `requestfailed:GET:/assets/not-found-page-DIgPLsYZ.js:net::ERR_ABORTED`, "Failed to fetch dynamically imported module"이다. webkit은 console 404, 같은 chunk의 "Load request cancelled", "Importing a module script failed."다. 기존 "serves A's removed chunk" test도 두 엔진 모두 `status 404 ≠ 200`으로 실패했다. 완료 기준 둘째 충족. WebKit 경로도 같은 워커 분기를 지난다는 것이 확인됐다(수정 커밋 `aaa782b`이 남긴 미확인). 덧붙여: Resource Timing 단언은 navigation 전 항목과 뒤 항목을 나누지 않는다. 앱에 route prefetch가 없어서(`git grep -i prefetch -- src` 0건) 지금은 문제가 아니다. 실제 판별은 서버 요청 단언과 같은 문서 단언이 한다 | +| 1103/09-05 (SW 쪽, 09 영역과 공유) | SW를 켜고 잇는 일이 제품 확장 지점 밖에 있음 | **일부** | 고쳐진 것: `ProductComposition.serviceWorker?: { blockers?, observe? }`가 생겼다(`src/bootstrap/product-composition-contract.ts:127-139`, `:166`). `createRuntimeAdapters`가 이 칸을 싣고(`runtime-adapters.ts:779`) 템플릿 조립이 그대로 넘긴다(`create-runtime-composition.ts:34`, `:47`, `:61`, `:95-115`). 던지는 observe는 조립이 삼킨다(`:105-111`). component 테스트가 실제 `createRuntimeComposition`을 돌려 observe 기록과 `BLOCKED_DIRTY_CLIENT`를 단언하고(`tests/component/runtime-composition-service-worker-product-wiring.test.ts:133-161`) FE-GATE-005에서 통과했다(`FE-GATE-005.txt:682`). 매뉴얼이 예시를 준다(`docs/manual/03-outside-feature-folder.md:169-182`). 남은 것: 활성화 화면과 reload 안내를 이을 제품 소유 자리가 없다. `onUpdateWaiting`·`requestActivation`·`onReloadRequired`를 읽는 곳은 어댑터·계약·host 밖에 없다(`git grep`). `composition.optional`은 `runtime-application.tsx:22`의 `startAfterMount()`만 쓴다. e2e 도우미는 사본의 템플릿 파일 `register-service-worker.ts`를 감싸 host에 닿는다(`tests/e2e/support/service-worker-builds.ts:36-40`, `:89-109`). 레시피 표는 "update/rollback UX 없음"을 SW 금지 조건으로 둔다(`optional-adapter-recipes.md:112`). 그래서 규칙대로 SW를 켜는 제품은 템플릿 파일을 고친다. 레시피가 이를 적는다(`:127-129`). 완료 기준("제품 소유 파일만 고쳐 켜고 템플릿 파일 diff 0")은 blockers까지는 충족, 활성화 화면은 미충족. §16.5와 같은 판정이다 | +| 0925/06-05 | 업데이트 설치 실패·`observe`·`health()` 미연결 | **일부** (지난 라운드 남음) | 고쳐진 것: `observe`는 제품이 잇는다(위 1103/09-05). 남은 것: `watchForUpdates`는 `installed`만 알린다. 업데이트 워커가 `redundant`가 되거나 주기 검사가 실패해도 observe·telemetry가 없다(`service-worker-page-controller.ts:328-349`, `:359-361`의 `.catch(() => {})`). `OptionalRuntimeHost.health()`를 `src`에서 읽는 곳이 없다(`optional-runtime-host.ts:174`, `git grep`). 첫 시작 실패만 `service-worker.start.failed`로 남는다(`optional-runtime-host.ts:129-135`). 레시피가 이를 적는다(`optional-adapter-recipes.md:141-147`) | +| 0925/06-08 | 이전 빌드 fallback이 `assets/`를 하드코딩 | **남음** (영향 범위 넓어짐) | 하드코딩 자리가 상수 하나로 모였다(`src/contracts/service-worker.ts:126`). 그러나 Vite 설정의 `build.assetsDir`와 잇는 곳이 없다. `vite.config.ts`는 그 값을 정하지 않고, 상수와 같은지 보는 검사도 없다(`git grep assetsDir` 결과는 주석과 리뷰 문서뿐). 호스팅 정책 `/assets/*`(`config/hosting/cache-policy.json:26`)와 e2e 도우미의 `dist/assets` 읽기(`service-worker-update.spec.ts:102-106`)는 따로 적은 문자열이다. 1105/06-01 수정 뒤에는 수집기도 이 상수를 읽는다. 그래서 제품이 `assetsDir`를 바꾸면 fallback·probe에 더해 사전 캐시도 오류 없이 빈다. 빈 manifest는 decoder가 받는다(`service-worker-static-manifest.ts:136-142`, 최소 개수 없음). 수정 커밋이 이 한계를 적었다(`1c7c614` 본문 "0925/06-08은 그대로 남는다"). 원인과 고칠 곳이 같아서 새 발견으로 세지 않았다. 그런 제품에서는 FE-GATE-008의 SW spec이 `dist/assets` ENOENT나 `assets.length > 0` 단언(`service-worker-update.spec.ts:145-148`)으로 실패할 것이다(정적 추론, 원인 이름은 없다) | +| 0925 P3 | route chunk 변경용 export 덧붙이기를 도우미 옵션으로 | **남음** | `service-worker-update.spec.ts:54-72` 그대로 | +| 1101/06-03 | PAGE_HELLO·UPDATE_READY·reload guard가 흔적만 남음 | **남음** | 파서가 두 kind를 받는다(`service-worker-protocol.ts:16`, `:18`). `reloadGuardBytes`·`reloadGuardTtlMs`(`src/contracts/service-worker.ts:27-28`)를 읽는 곳이 없다 | +| 1101/06-05 | 릴리스마다 사전 캐시 전체를 `no-store`로 다시 받음 | **남음** | `service-worker-static-assets.ts:279-284`. 이전 캐시 재사용 없음(`:220-262`) | +| 1101 R1 | `retainedPreviousCaches`를 `void`로만 참조 | **남음** | `service-worker-lifecycle.ts:169` | +| 1101 R2 | `validateActiveFence` 두 벌 | **남음** | `web-push/inbound/push-event-adapter.ts:196`, `notification-click-adapter.ts:356` | +| 1101 R3 | `SYNC_WAKE_OBSERVED`만 프로토콜 버전을 숫자로 씀 | **남음** | `service-worker-entry.ts:170`(`protocolVersion: 1`). 다른 메시지는 `SERVICE_WORKER_PROTOCOL_VERSION`을 쓴다(`service-worker-protocol.ts:108`, `:134`) | +| 1101 R4 | `bounds a stream that never produces a chunk`가 5초를 실제로 기다림 | **고쳐짐** | `ce191be`(1101/10-07)가 가짜 시계로 바꿨다(`service-worker-runtime.test.ts:2006-2041`). snapshot `unit.xml`(03:46)에서 그 test가 0.008초, 파일 64건이 0.32초다(지난 라운드 5,221 ms). 이 수정이 실효 상한을 넓힌 것은 새 **06-02**로 셌다 | + +집계(13건): 고쳐짐 3(1105/06-01, 1105/06-03, 1101 R4) · 일부 3(1105/06-02, 1103/09-05, 0925/06-05) · 남음 7 · 재발 0 · 틀린 발견 0. README §16과 다른 판정: 0925/06-05를 "남음"에서 "일부"로 올렸다(§16.6에 행이 없음). 나머지는 §16.4·§16.5와 같다. 1105/06-03의 "고침"은 06-R1로 확인했다. + +## 3. 이번 발견 (36.3) + +새 발견 2건. 심각도: Critical 0 · High 0 · Medium 0 · Low 2. 우선순위: P0 0 · P1 0 · P2 0 · P3 2. 성격: 확인된 결함 1 · 구조적 위험 1 · 미검증 0 · 개선 제안 0. + +### 06-01 live probe가 `/service-worker.js`의 같은 origin redirect를 통과시킨다. 브라우저는 워커 스크립트 redirect를 모두 거절한다 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 구조적 위험 | +| 관련 관점 | 18, 21, 28, 5 | +| 근거 | 워커를 싣는 빌드에서 live 모드는 `serviceWorker` surface(`/service-worker.js`)를 요청한다(`config/hosting/cache-policy.json:41-47`, `scripts/verify-hosting-headers.ts:84-88`). 이 요청은 `probeLiveRelease`의 기본 fetcher `redirect: "follow"`로 간다(`scripts/lib/hosting-probe.ts:135`). `probeLiveHosting`은 `transport.fetcher`가 없으면 이 기본값을 쓴다(`:349`, 스크립트는 fetcher를 넘기지 않는다, `verify-hosting-headers.ts:114-116`). 행은 최종 응답의 `http-status`와 `final-origin`뿐이다(`hosting-probe.ts:142-157`). `response.redirected`는 보지 않는다. 그래서 같은 origin 안의 redirect 뒤 200·`no-cache`·JS MIME이면 모든 행이 PASS다. 운영 문서도 "Each required surface must return HTTP 200 without leaving that origin"이라고 적는다(`docs/operations/release-cache-rollback.md:66-67`). 한편 Service Worker 명세의 Update 알고리즘은 스크립트 요청의 redirect mode를 `"error"`로 둔다(일반 지식, 이 저장소에서 돌리지 않음). Chromium은 "The script resource is behind a redirect, which is disallowed"로 등록을 거절한다. 1105/06-02의 자산 probe는 같은 이유로 redirect를 FAIL로 바꿨는데(`hosting-probe.ts:312-329`), 워커 스크립트 surface에는 그 규칙이 없다. 테스트에도 워커 스크립트 redirect 사례가 없다(`tests/unit/hosting-probe.test.ts`의 `serviceWorker` 사례는 선택·`no-cache`만 본다) | +| 발생 조건 | SW `ACTIVE` 또는 `REMOVE_REGISTRATION` 제품. 호스트가 `/service-worker.js`를 같은 origin 안에서 redirect한다. 예: 버전 경로로 보내는 CDN 규칙, object storage 웹사이트의 redirect 규칙, 경로 정규화 규칙 | +| 영향 | FE-GATE-019가 PASS다. 그러나 첫 등록은 `register()` 거절로 `service-worker.start.failed`만 남는다. 이미 설치된 브라우저는 update 검사가 실패해 옛 워커에 머문다. 가장 나쁜 경우는 kill switch다. `REMOVE_REGISTRATION`은 브라우저 update 검사가 새 `service-worker.js`를 받는 것에 기댄다(`docs/operations/browser-file-storage-recovery.md:605-613`). redirect가 있으면 자기 해제 워커가 설치되지 않아, 부팅을 막는 워커를 걷어내지 못한다. 데이터 손상은 없다 | +| 심각도·우선순위 | Low · P3. 드문 호스팅 구성이고, 1105/06-02 ①과 같은 무게다. kill switch가 막히는 점은 28번에 적었다 | +| 통제·증거 | "probe PASS면 호스팅 때문에 워커 등록·업데이트가 실패하지 않는다" 규칙: `no-cache`는 M2(live 코드, 테스트는 fixture 쪽), redirect는 M0 · E1 | +| 확실성과 남은 가정 | probe가 redirect를 보지 않는 것은 코드로 확정된다. 브라우저 거절은 명세와 Chromium 오류 문구에 기댄 일반 지식이다. 이 저장소에서 redirect 호스트로 등록을 돌려 보지 않았다. WebKit·Firefox 동작도 확인하지 않았다 | +| 결정의 근거 | 기록된 의도: 수정 커밋 `4d6f254`은 자산 probe만 고쳤다. 리뷰 1105/06-02도 자산만 다뤘고 "다른 surface는 `final-origin`을 본다"고 적었다. 리뷰어 추론: 다른 surface는 페이지가 받는 문서라 redirect가 허용되지만, 워커 스크립트는 브라우저가 redirect를 금지하는 유일한 surface다 | +| 이해 비용 | 운영자는 FE-GATE-019 PASS를 "kill switch가 동작한다"로 읽는다. 실제 범위는 probe의 fetch 옵션과 SW 명세를 같이 알아야 안다 | +| 최소 개선 방향 | `serviceWorker` surface에 redirect 행을 더한다. 자산 probe처럼 `response.redirected` 또는 `opaqueredirect`·3xx면 FAIL로 본다. 가장 작게는 `probe()`가 `response.redirected`를 결과에 싣고, `serviceWorker` surface에서만 그것을 FAIL로 판정한다. 운영 문서 `:66-67`에 "워커 스크립트는 redirect 없이"를 더한다 | +| 대안 비교 | (a) `serviceWorker` surface만 redirect FAIL. (b) 모든 surface에서 redirect FAIL. `index`·`appRoute`의 정상 redirect(예: 끝 슬래시 정규화)까지 막는다. (c) 문서에만 적음. (a)가 가장 작고 브라우저 규칙과 같다 | +| 단순화의 보존 조건 | 다른 surface의 `final-origin` 규칙, 자산 probe의 redirect 규칙(`hosting-probe.ts:312-329`)은 그대로 둔다 | +| 비용·부작용 | 수 줄과 테스트 1건. 워커 스크립트를 redirect하던 호스트는 이제 FE-GATE-019에서 FAIL이다. 그런 호스트는 지금도 워커가 동작하지 않는다 | +| 재검토 조건 | 브라우저가 워커 스크립트 redirect를 허용하게 바뀌면(명세 변경) 이 행을 지운다 | +| 완료 기준 | `/service-worker.js`에 `redirected: true`인 200을 주는 fetcher 대역에서 `probeLiveHosting`이 `serviceWorker` FAIL 행을 낸다 | +| 검증 방법 | `hosting-probe.test.ts`의 "live hosting probe" describe에 워커 스크립트 redirect 사례 1건. 브라우저 쪽은 e2e 도우미 서버가 `/service-worker.js`를 302로 주게 하고 `start()` 결과를 본다(선택) | +| 담당·기한·상태 | 템플릿 소유자(13 영역 호스팅 검사와 공동) · 미정 · 열림 | +| 재검증 결과 | 해당 없음(이번 라운드 발견) | + +### 06-02 1101/10-07 수정이 marker 읽기 시간 상한 test의 실효 상한을 10초에서 20초로 넓혔다 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 확인된 결함 (약해진 검사, 06-R3에서 변이 생존) | +| 관련 관점 | 10, 21 | +| 근거 | 런타임 상한은 `ACTIVATION_MARKER_READ_DEADLINE_MS = 5_000`이다(`src/adapters/service-worker/service-worker-lifecycle.ts:558`). 모듈 안 상수라 테스트가 import하지 못한다. 수정 전 test는 실제 시계로 `onActivate()`를 기다렸고 test 상한이 `10_000`이었다(`git show 8a44226:tests/unit/service-worker-runtime.test.ts`, 그 test 끝 `}, 10_000);`). 그래서 상한이 10초 이상이면 시간 초과로 실패했다. 수정 뒤 test는 가짜 시계로 5초씩 **최대 4번** 넘긴다(`tests/unit/service-worker-runtime.test.ts:2029-2034`). 그래서 상한이 20초 이하면 통과한다. 이 fixture에서 marker 읽기는 한 번뿐이다. 캐시 목록이 현재 캐시 하나라서(`:1951-1953`) `highestMarkedCache`는 읽지 않고(`service-worker-lifecycle.ts:207-208`), 현재 캐시 marker 하나만 읽는다(`:160`). 4번 반복은 이 test에 필요 없다. 같은 파일의 다른 가짜 시계 test는 계약 상수(`SERVICE_WORKER_BOUNDS.installDeadlineMs`, `clientDrainMs`)만큼 정확히 넘긴다(`service-worker-runtime.test.ts:984`, `:1615`). **06-R3**: 상한을 `15_000`으로 올린 변이에서 `service-worker-runtime.test.ts` 64건이 모두 통과했다(rc=0, 파일 104 ms). 변이가 살아남았다. 수정 전 test는 같은 변이에서 실제로 15초를 기다리므로 10초 test 상한에서 실패했을 것이다(정적 확인, 실행하지 않음) | +| 발생 조건 | 누군가 marker 읽기 상한을 10~20초로 올린다. 예: 느린 저장소를 이유로 30초 drain과 맞추려 할 때 | +| 영향 | `activate`가 marker 하나에 최대 20초 묶여도 단위 테스트가 통과한다. 그동안 새 워커의 활성화와 옛 캐시 정리가 늦어진다. 지금 코드에는 결함이 없다 | +| 심각도·우선순위 | Low · P3. 미래 회귀를 못 잡는 폭이 10초 넓어진 정도다 | +| 통제·증거 | "marker 읽기는 5초 안에 끝난다" 규칙: M2(코드) / 테스트는 "20초 안에 끝난다"만 검출 · E1 + E2(06-R3) | +| 확실성과 남은 가정 | 반복 횟수와 fixture의 읽기 횟수는 코드로 확정된다. 15초 변이 생존은 실행으로 확인했다. 수정 전 test가 그 변이를 잡았다는 것은 코드로 본 추론이다 | +| 결정의 근거 | 기록된 의도(`ce191be` 본문): 상한을 의존성으로 받게 하는 안은 "운영 코드에 테스트용 손잡이"라 버렸다. 리뷰어 추론: 손잡이 없이도 상수를 `SERVICE_WORKER_BOUNDS`로 옮기면 다른 test처럼 정확히 그만큼 넘길 수 있다. 이 상수만 계약 밖에 있다 | +| 이해 비용 | test를 읽는 사람은 "One read deadline per marker probe"를 보고 4번이 필요하다고 믿는다. 실제로는 한 번이다 | +| 최소 개선 방향 | (가) 반복 없이 `advanceTimersByTimeAsync(5_000)` 한 번 뒤 `settled`를 단언한다. (나) 상수를 `SERVICE_WORKER_BOUNDS`로 옮기고 그 값만큼 넘긴다. 상한을 1 ms만 올려도 test가 실패한다 | +| 대안 비교 | (가)는 한 줄이고 숫자가 test에 중복된다. (나)는 계약 상수 하나가 늘고 중복이 없다. 현상 유지는 10~20초 회귀를 못 잡는다. (나)가 같은 파일의 다른 test와 맞는다 | +| 단순화의 보존 조건 | 가짜 시계로 빠르게 도는 것(1101 R4 해결)과 `cancels >= 1` 단언을 유지한다 | +| 비용·부작용 | 수 줄. (나)는 계약 모듈 변경이라 워커·페이지 두 realm 타입 검사를 다시 돈다 | +| 재검토 조건 | fixture가 marker를 여러 번 읽게 바뀌면 그 횟수만큼 정확히 넘긴다 | +| 완료 기준 | 상한을 5,001 ms로 올리는 변이에서 이 test가 실패한다 | +| 검증 방법 | 06-R3와 같은 실행(상한 값만 5,001로 바꿈). 무변이에서는 통과한다 | +| 담당·기한·상태 | 템플릿 소유자(10 영역 1101/10-07과 공동. 같은 결함으로 세면 한 건으로 합친다) · 미정 · 열림 | +| 재검증 결과 | 해당 없음(이번 라운드 발견) | + +## 4. 28개 관점 판정 (36.2) + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 통제는 "목표 / 확인"이다. + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +| --- | --- | --- | --- | --- | --- | +| 1 | 코드 성숙도 | 적용 | M2 / M2 | E1·E2 | P. 사전 캐시가 `assets/`만 받는다(1105/06-01 고쳐짐). 자산 probe가 redirect를 거절한다. 워커 스크립트 surface만 redirect를 본다(06-01) | +| 2 | 구조적 성숙도 | 적용 | M3 / M3 | E1·E2 | O. worker·page realm을 tsconfig로 나눈다. FE-GATE-003 PASS. FE-GATE-020의 제거 사본에서도 `tsc --project tsconfig.service-worker.json`이 돈다(`FE-GATE-020.txt:3098`) | +| 3 | 변경 용이성 | 적용 | M2 / M1~M2 | E1·E2 | P. SW 켜기·blockers·observe는 제품 소유 파일로 된다(1103/09-05 일부). 활성화 화면은 템플릿 파일을 고친다 | +| 4 | 인지 부하 | 적용 | - | E1 | P. 쓰지 않는 kind·상수가 남았다(1101/06-03). lifecycle 736줄, page controller 642줄, subscription adapter 1,203줄 그대로 | +| 5 | 위험 가시성 | 적용 | M1 / M1 | E1 | P. 레시피·운영 문서가 사전 캐시 범위와 자산 redirect를 맞게 적는다(`optional-adapter-recipes.md:166-171`, `release-cache-rollback.md:81-86`). 워커 스크립트는 "origin을 떠나지 않으면 된다"로 적혀 있다(06-01) | +| 6 | 실패 성숙도 | 적용 | M2 / M2 | E1·E2 | P. install 거절 11종을 구분한다. 업데이트 설치 실패는 페이지에 오지 않는다(0925/06-05) | +| 7 | 운영 성숙도 | 적용 | M2 / M1~M2 | E1·E2 | P. 시작 실패는 telemetry로, page controller 관측은 제품 observe로 닿는다. 업데이트 실패·`health()`는 미연결(0925/06-05). probe PASS가 워커 등록 성공을 다 뜻하지 않는다(06-01) | +| 8 | 디버깅 가능성 | 적용 | M2 / M2 | E1·E2 | P. observe가 제품 파일에서 닿는다(`product-composition-contract.ts:134-138`, component 테스트 통과). registry 거절 메시지는 여전히 이유를 말하지 않는다(`notification-registry.ts:53`) | +| 9 | 유지보수 성숙도 | 적용 | M1 / M1 | E1 | P. 읽히지 않는 상수·kind(1101/06-03), `validateActiveFence` 두 벌(R2), 폐기 예정 `inlineDynamicImports`(`vite.service-worker.config.ts:87`) | +| 10 | 테스트 성숙도 **(깊게)** | 적용 | M3 / M3(일부) | E2(CI env)·E3(06-R1) | P. 새 테스트가 이 커밋에서 통과한다: 수집기 루트 아이콘, 자산 redirect, live 분기 함수, 옛 탭 route(chromium·webkit), 제품 SW 조립(component). 수정이 노린 변이를 잡는다: 워커 fallback 끊기는 두 엔진 4건 실패(06-R1), live 분기의 자산 probe 삭제는 1건 실패(06-R2). marker 상한 test는 15초 변이를 통과시킨다(06-02, 06-R3). 새 Firefox skip은 격리 이유로 실패한다(06-R4) | +| 11 | 데이터 성숙도 | 적용 | M2 / M2 | E1·E2 | O. 캐시는 `credentials: "omit"`으로 받은 해시 공개 자산만 담는다(`service-worker-static-assets.ts:279-284`). 이제 `assets/` 밖 파일은 들어가지 않는다. push fence에 계정 ID·endpoint가 없다. 코드 변경 없음 | +| 12 | 동시성 성숙도 | 적용 | M3 / M3 | E2 | O. nonce·drain 테스트가 FE-GATE-005에서 통과한다. 이 영역 동시성 코드는 바뀌지 않았다. 지난 라운드 변이 결과는 다시 쓰지 않았다 | +| 13 | 확장성 | 적용 | M2 / M2 | E1 | P. 256개·5 MiB 상한을 빌드가 막는다. waiting 기간 캐시 누적은 문서화만 했다(1103/06-04) | +| 14 | 성능 성숙도 | 적용 | M2 / M2 | E1·E2 | P. 릴리스마다 사전 캐시 전체를 다시 받는다(1101/06-05). 단위 테스트 파일은 5.2초에서 0.32초가 됐다(1101 R4) | +| 15 | 보안 성숙도 | 적용 | M3 / M3 | E2 | O. registry 경로 정규화, install fetch의 `credentials`·`redirect` 테스트가 통과한다. 코드 변경 없음 | +| 16 | 의존성 성숙도 | 적용 | - | E1 | P. 런타임 외부 패키지 없음. `inlineDynamicImports` 그대로 | +| 17 | API / Contract 성숙도 | 적용 | M2 / M2 | E1·E2 | P. `ProductComposition.serviceWorker`는 선택 칸이라 기존 제품 파일이 그대로 통과한다. 처리하지 않는 kind를 받는다(1101/06-03) | +| 18 | 배포 성숙도 **(깊게)** | 적용 | M3 / M2~M3 | E1·E2 | P. 사전 캐시 범위가 호스팅 정책과 맞는다. 자산 redirect·live 분기가 테스트된다. 남은 것: 워커 스크립트 redirect(06-01), 워커 없는 빌드의 probe 범위(1105/06-02 결정 대기), `assetsDir` 상수(0925/06-08), 하위 경로 게이트(13 영역 0929/13-06). FE-GATE-019는 이번에 돌지 않았다 | +| 19 | 설정 성숙도 | 적용 | M3 / M2 | E1 | P. 선택은 제품 소유 파일 하나다. 자산 디렉터리는 Vite 설정과 이어지지 않은 상수다(0925/06-08) | +| 20 | 개발자 경험 | 적용 | M1 / M1 | E1 | P. 매뉴얼이 `composeProduct`의 `serviceWorker` 예시를 준다(`03-outside-feature-folder.md:169-182`). 활성화 화면은 템플릿 파일을 고친다고 적는다(`:184`) | +| 21 | Guardrail 성숙도 **(깊게)** | 적용 | M3 / M3(일부) | E2·E3 | P. live 분기가 함수 테스트를 얻었고 변이를 잡는다(1105/06-02 ③, 06-R2). 옛 탭 route를 결과로 단언하고 워커 결함을 두 엔진에서 잡는다(1105/06-03, 06-R1). preload 허용은 그대로지만 이제 이 test가 결과로 대신 본다. marker 상한 test가 약해졌다(06-02, 06-R3). 워커 스크립트 redirect는 게이트 밖이다(06-01) | +| 22 | 추상화 성숙도 | 적용 | M2 / M2 | E1·E2 | O. 구조적 facade로 워커 없이 테스트한다. 제품 SW 조립 테스트는 실제 조립 경로를 돈다 | +| 23 | 일관성 | 적용 | - | E1 | P. "사전 캐시 = `assets/`"가 코드 세 곳에서 한 상수다. 호스팅 정책 `/assets/*`(`cache-policy.json:26`)는 따로 적은 문자열이다. redirect 규칙이 자산(거절)과 워커 스크립트(통과)에서 다르다(06-01) | +| 24 | 네이밍 / 의미 | 적용 | - | E1 | P. `retainedPreviousCaches`는 읽히지 않는다(R1). test 주석 "One read deadline per marker probe"가 반복 4번을 설명하지만 이 fixture는 한 번 읽는다(06-02와 같은 결함, 따로 세지 않음) | +| 25 | 조직 확장성 | 적용 제외 | - | - | -. 1인 관리 전제(0.1) | +| 26 | Ownership 성숙도 | 적용 | M1 / M1 | E1 | O. 레시피가 템플릿이 가진 것과 제품이 붙일 것(4·5)을 나눠 적는다(`optional-adapter-recipes.md:127-129`). 지난 라운드의 틀린 문장(1105/06-01)이 고쳐졌다 | +| 27 | 삭제 가능성 | 적용 | M3 / M3 | E3 | O. web-push·realtime을 지운 fixture에서 7 check가 모두 통과한다(`realtime-runtime-removal.xml` tests=7 failures=0, 2026-11-06 03:45, FE-GATE-020 CI env) | +| 28 | 회복 가능성 **(깊게)** | 적용 | M3 / M2~M3 | E1·E2·E3 | P. kill switch와 자기 해제 워커, 제거 단계 유지 기간이 있다. 옛 탭 route test가 생겼고, 워커가 직전 캐시로 답하지 못하면 두 엔진에서 실패한다(1105/06-03, 06-R1). kill switch는 워커 스크립트가 redirect 없이 서빙된다는 전제를 probe가 보지 않는다(06-01). `null` 릴리스 뒤 옛 워커를 걷어내는 장치는 없고 문서로 운영한다 | + +집계: 적용 27개 중 O 7(2, 11, 12, 15, 22, 26, 27) · P 20 · X 0 · ? 0, 적용 제외 1. 지난 라운드 대비 26번이 P에서 O로 올라왔다. + +## 5. 미검증 + +| 항목 | 이유 | 확인하려면 | +| --- | --- | --- | +| Firefox 격리 나머지 3건(update 2, recovery 1) | 이번 배치는 새 skip 1건만 풀었다(06-R4). 나머지는 지난 라운드 06-R11 뒤로 spec·워커·Playwright가 바뀌지 않았다 | Playwright를 올릴 때 06-R4처럼 skip을 풀고 firefox로 두 spec 실행 | +| 06-R1의 다른 워커 결함 종류 | 배치는 직전 캐시 응답 끊기 한 종류다 | MIME이 틀린 캐시 응답, 다른 build의 chunk 바이트를 주는 변이 | +| 06-01 브라우저의 워커 스크립트 redirect 거절 | 명세·Chromium 오류 문구에 기댄 일반 지식이다. 이 저장소에서 돌리지 않았다. WebKit·Firefox는 모른다 | e2e 도우미 서버가 `/service-worker.js`를 302로 주게 하고 첫 `start()` 결과와 `REMOVE_REGISTRATION` 해제를 본다 | +| live 모드 probe 전체(FE-GATE-019) | release 단계 게이트라 이번 실행에 없다. live 모드는 저장소 안에서 돌 수 없다 | staging 호스트로 `HOSTING_BASE_URL` live probe | +| `public/assets/` 파일의 사전 캐시(1105/06-01 남은 가정) | 템플릿 `public/`에 그런 파일이 없다 | 수집기 단위 테스트에 `public/assets/` 사례. 더 정확한 방법은 Vite manifest(`vite.config.ts:212` `manifest: true`)의 산출 목록을 쓰는 것이다 | +| `assetsDir`를 바꾼 제품의 증상(0925/06-08) | 정적 추론만 했다 | 사본에서 `build.assetsDir: "static"`으로 빌드하고 manifest·FE-GATE-008 결과 확인 | +| Web Push end-to-end(실제 푸시 서비스, VAPID) | 푸시 서버 없음. `WEB_PUSH`는 빌드에서 거절된다 | 로컬 web-push 서버와 제품 조립 브랜치 | +| 하위 경로(`/app/`) 브라우저 설치 재확인 | 이 영역 SW 런타임 코드는 상수 하나만 바뀌었다. 다시 돌리지 않았다 | 지난 1103 L1과 같은 실험 | +| 얼어 있는 탭이 Web Lock을 쥔 경우, A 워커 아래 B 부팅 지연 | 재현 환경 없음 | `Page.setWebLifecycleState(frozen)`, resource timing 비교 | + +## 6. 실행 기록 + +이 리뷰는 laptop·desktop 어디에서도 명령을 실행하지 않았다. 읽은 증거(모두 `bbde570`, CI env, 2026-11-06 03:24~03:56): + +| 증거 | 위치 | 이 문서에서 쓴 내용 | +| --- | --- | --- | +| 게이트 요약 | `desktop:/tmp/claude-gates/bbde570-ci/summary.txt` | FE-GATE-001~012·020 rc=0, 013 rc=1 | +| FE-GATE-005 | `bbde570-ci/gate-artifacts/FE-GATE-005.txt` | 이 영역 단위 파일 통과 줄(`:28`, `:76`, `:119`, `:155`, `:167`), component `:682`, 전체 3,056건 통과(`:313`) | +| FE-GATE-008 | `bbde570-ci/gate-artifacts/FE-GATE-008.txt` | SW spec test별 결과(chromium `:72-121`, firefox `:144-157`, webkit `:206-231`), 222 통과·4 skip(`:233-234`) | +| FE-GATE-020 | `bbde570-ci/gate-artifacts/FE-GATE-020.txt`, `r5/snap/merge/artifacts/tests/realtime-runtime-removal.xml` | 7 check 통과, `tsc --project tsconfig.service-worker.json`(`:3098`) | +| unit junit | `r5/snap/merge/artifacts/tests/unit.xml`(03:46) | `bounds a stream …` 0.008초, `service-worker-runtime` 64건 0.32초, `hosting-probe` 39건 | +| 공유 실행 | `r5/snap/verify-documentation.{local,no-sibling}.txt`, `r5/snap/build.txt` | 둘 다 `PASS_SCOPED`, 기본 빌드는 워커 빌드를 건너뜀(`build.txt:68`) | + +요청한 배치(요청 `scratchpad/r5/requests/06.md`, 패치 `06-Rk.diff`, 모두 laptop `bbde570`에서 `git apply --check` 통과). 오케스트레이터가 desktop checkout에서 항목마다 `bbde570`로 되돌린 뒤 패치를 적용해 돌렸다(local env, 2026-11-06 04:23~04:24, 부하 2.5~2.9). 4건 모두 restore clean. 로그 `desktop:/tmp/claude-gates/r5/batch/out/R5-06-Rk.log`, 요약 `r5/batch/summary.txt`. 무변이 대조는 게이트가 대신한다: 06-R1·R4는 `FE-GATE-008.txt:102`, `:120`, `:156`, `:229-230`, 06-R2·R3는 `FE-GATE-005.txt:76`, `:119`. 06-R1은 오케스트레이터의 중복 runner 사고로 두 번 돌았고, 위 로그는 깨끗한 재실행 것이다. + +| ID | 명령 | 변이 | rc · 시간 | 결과 | +| --- | --- | --- | --- | --- | +| 06-R1 | `corepack pnpm exec playwright test tests/e2e/service-worker-update.spec.ts --project=chromium --project=webkit --grep "removed"` | `service-worker-lifecycle.ts:296` 직전 캐시 응답을 `return null` | 1 · 30초 | **기대대로** 4건 FAIL. "serves A's removed chunk"는 두 엔진 모두 `status 404 ≠ 200`(`:279`)과 console 404. "opens A's removed route"는 두 엔진 모두 `{ sameDocument: false, chunkRequested: false }`(`:342`)와 허용 밖 fixture 줄 셋(console 404, chunk `requestfailed`, dynamic import 실패) | +| 06-R2 | `node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts` | `hosting-probe.ts:354` `probeLiveHosting`에서 자산 probe 결과 삭제 | 1 · 1초 | **기대대로** 1건 FAIL, 38건 통과. "live hosting probe (1105/06-02) > checks every built asset type besides the release surfaces"가 `expected [] to deeply equal [ 'hashedAsset.css content-type' ]`(`hosting-probe.test.ts:443`) | +| 06-R3 | `node scripts/run-vitest.ts run tests/unit/service-worker-runtime.test.ts` | `service-worker-lifecycle.ts:558` 상한 5_000 → 15_000 | 0 · 1초 | **기대대로** 64건 모두 통과(파일 104 ms). 변이 생존 → 06-02 확정 | +| 06-R4 | `corepack pnpm exec playwright test tests/e2e/service-worker-update.spec.ts --project=firefox --grep "opens A's removed route"` | 새 test의 Firefox skip 삭제(`:306`) | 1 · 13초 | **기대대로** 1건 FAIL. `updateFromAToB`에서 `requestActivation()`이 `{ kind: "NO_WAITING_WORKER" }`(`:214`). 격리 주석(`:174-181`)이 적은 Playwright Firefox의 워커 제어 문제다. skip 유지가 맞다 | + +## 7. 새 발견 요약 + +| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line | +| --- | --- | --- | --- | --- | +| 06-01 | Low · P3 | 구조적 위험 | live probe가 `/service-worker.js`의 같은 origin redirect를 통과시킨다. 브라우저는 워커 스크립트 redirect를 거절해 등록·업데이트·`REMOVE_REGISTRATION`이 실패할 수 있다 | `scripts/lib/hosting-probe.ts:135`, `:142-157`; `docs/operations/release-cache-rollback.md:66-67` | +| 06-02 | Low · P3 | 확인된 결함 (약해진 검사, 06-R3 생존) | 1101/10-07 수정이 marker 읽기 상한 test의 실효 상한을 10초에서 20초로 넓혔다 | `tests/unit/service-worker-runtime.test.ts:2029-2034`; `src/adapters/service-worker/service-worker-lifecycle.ts:558` | diff --git a/docs/reviews/2026-11-06-maturity-review/07-contracts.md b/docs/reviews/2026-11-06-maturity-review/07-contracts.md new file mode 100644 index 00000000..4f1e966c --- /dev/null +++ b/docs/reviews/2026-11-06-maturity-review/07-contracts.md @@ -0,0 +1,163 @@ +# 영역 07 — contracts (공유 어휘·외부 계약) + +> 검토일 2026-11-06 · 기준 `bbde570` (PR B 끝, 브랜치 `fix/maturity-review-2026-11-05-b`) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 경로: `src/contracts/`(44파일, 9,329줄), `schemas/`(5파일), `config/contracts/`(7파일. 새 파일 `backend-http-contract-excerpt.json`). 함께 본 곳: `scripts/check-backend-contract-drift.ts`, `scripts/lib/backend-contract-excerpt.ts`, `scripts/lib/registry-compatibility.ts`, `scripts/check-registries.ts`, `scripts/lib/removal-fixture.ts` +> 깊게 본 관점: 17, 21, 10, 20, 23 +> 렌즈: 1105/07-01·07-02·09-03, 1103/07-04, 1103/16-01(BREAKING `56272e8`), 통합 커밋 `45c9c4d`의 pin 수정, 1105/03-01 테스트가 들어간 문서 테스트 제외 목록 +> 영역 판정(35.8): **조건부 사용 가능.** 외부 계약 조립기, FE-REG-API 투영, 응답 스키마 축소 등급, 짝 백엔드 답 표와 사본 대조는 그대로 써도 된다. 조건은 둘이다. (1) 짝 백엔드를 받을 때마다 `check:backend-contract-drift --backend `를 돌린다. 사본과 실제 백엔드 문서의 대조는 여전히 게이트 밖이다(1105/07-01의 설계 한계, D6). (2) 스키마 메타 행을 손으로 쓸 때 `direction`·`unknownFieldPolicy`를 빼지 않는다. 빼면 응답 DTO를 strict로 바꿔도 아무 검사도 보지 않는다(07-02). + +ID 표기: 이 문서의 `07-NN`은 2026-11-06 라운드 ID다. 지난 라운드(2026-11-05)는 `1105/07-NN`, 그 전은 `1103/07-NN`이다. 다른 영역 ID도 같은 꼴로 적는다. + +## 0. 결론 + +- **지난 라운드 영역 07 발견 3건(1105/07-01, 1105/07-02, 1103/07-04)과 지시로 다시 본 2건(1105/09-03, 1103/16-01)이 모두 고쳐졌다.** README §16과 판정이 같다. 1105/07-02의 완료 기준은 배치 07-R1로 확인했다. 지난 라운드와 같은 strict 패치에서 `check:registries`가 `response-reader-narrowed` 증거 누락 2줄로 실패했다(registries-rc=1). +- **1105/07-01:** 답 표가 이제 pin 커밋의 백엔드 표 사본과 행마다 대조된다(`tests/unit/backend-contract-pin.test.ts:165-179`). 사본 17줄이 백엔드 `45d2a478:docs/web/http-contract.md:86-91, 109-113, 188-193`과 글자까지 같다(리뷰어가 노트북에서 대조). drift 스크립트는 checkout이 없으면 rc=2로 끝나고(`scripts/check-backend-contract-drift.ts:96-110`), 매뉴얼에 있다(`docs/manual/01-add-a-feature.md:228`). desktop 옆 백엔드 checkout으로 돌린 drift는 rc=0이다. 백엔드 HEAD `3d73b6f`는 pin 뒤지만 문서와 scaffold 파일 6개가 그대로다(배치 07-R3). 지난 라운드의 "desktop에서 비교 불가(rc=2)"는 풀렸다. 사본과 실제 백엔드의 대조가 게이트 밖인 것은 D6의 설계 한계라 다시 세지 않는다. +- **통합 수정 `45c9c4d`는 맞다.** pin의 `notCopied`가 비었고(`config/contracts/backend-contract-pin.json:50`), 사본 §4의 네 행이 답 표에 모두 있다(`IDEMPOTENCY_KEY_INVALID`는 §2 행이 덮는다). 프론트 거절 표의 `RATE_LIMIT_*` 둘도 답 표가 받친다(`src/adapters/http/backend-envelope.ts:180-181`). `notCopied`가 비어도 옮기지 않은 행은 "neither in the answer table nor in the pin's notCopied"로 실패한다(`scripts/lib/backend-contract-excerpt.ts:135-151`). 배치 07-R2: 사본 §4에 429 행 하나를 더하자 "copies the answers from the backend table rows at the pin" 1건만 `§4 429 RATE_LIMIT_EXCEEDED is neither in the answer table nor in the pin's notCopied`로 실패했다(14건 통과, vitest-rc=1). +- **BREAKING 1103/16-01은 코드·CHANGELOG·생성기·repo 안 descriptor가 모두 맞는다.** `responseEnvelope`가 타입의 필수 칸이고(`src/contracts/external-contract-runtime.ts:239`), 생성기 세 descriptor와 참조 기능 셋이 값을 적는다. `@ts-expect-error`(`tests/unit/external-contract-runtime.test.ts:396`)가 FE-GATE-003에서 쓰였으니 타입이 줄을 요구한다. 다만 계약 문서 한 줄이 아직 "bulk는 `responseEnvelope`를 빼라"고 적는다. 빼면 `check:types`가, 같은 기여에 `"NONE"`을 적으면 조립이 실패한다(새 07-01, Low). +- **1105/03-01 테스트를 문서 테스트 제외 목록에 넣은 것은 드릴에 필요한 검사를 빼지 않았다.** 빠진 곳은 문서를 복사하지 않는 capability 드릴 셋뿐이다. 그 드릴들이 지우는 파일은 pin 테스트가 보는 파일과 겹치지 않는다. pin 테스트는 `test:unit`과, 문서를 복사하는 참조 기능 제거·생성 기능 드릴에서 그대로 돈다(FE-GATE-020 로그에서 8번 통과). 파일 단위 제외라 문서를 읽지 않는 14건도 같이 빠지지만, 그 14건이 보는 것은 세 드릴이 건드리지 않는다. +- **새 발견 07-02:** FE-REG-SCHEMA 행의 `direction`·`unknownFieldPolicy`는 선택 칸이다. 적지 않은 행은 정책 테스트가 건너뛴다. 그래서 1105/07-02 수정(값이 좁혀지면 breaking)이 닿지 않는 경로가 남는다(Low). +- **이번 수정들이 영역 07의 검사를 약하게 만든 곳은 찾지 못했다.** `git diff 8a44226..bbde570`의 영역 파일에서 지운 단언은 없다. 넓어진 목록은 둘이다. 문서 테스트 제외 목록(위 판단)과 FE-REG-STORAGE `orphanExemptRows`의 `AUTH_REDIRECT_TRANSACTION`(`config/contracts/registry-governance.json:376`, 1105/05-01, 영역 05 몫. 행 하나만 더했고 이유가 1105 README §16.3에 있다)이다. +- High 이상과 P1은 없다. 새 발견 2건(Low 2, P3 2). + +## 1. 범위 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`, 영역 07 | +| 커밋·작업 상태·확인 시점 | `bbde570`. 노트북 worktree(HEAD = 기준, 브랜치 `docs/maturity-review-2026-11-06`)에서 읽기만 했다. 미커밋 변경은 추적 안 되는 `AGENTS.md`뿐이다(무시). 2026-11-06 | +| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음. 짝 백엔드 템플릿과 함께 빨리 출시하는 것이 목표 | +| 필수 요구와 규모·운영 목표 | 합의된 규모·운영 목표 없음. 짝 백엔드 응답 기준은 pin 커밋 `45d2a478`의 `docs/web/http-contract.md`(노트북 backend checkout에서 `git show`로만 읽음) | +| 읽은 코드·구성 범위 | 줄 단위: `config/contracts/backend-contract-pin.json`·`backend-idempotency-answers.json`·`backend-http-contract-excerpt.json` 전체, `scripts/lib/backend-contract-excerpt.ts` 전체, `scripts/check-backend-contract-drift.ts` 전체, `tests/unit/backend-contract-pin.test.ts` 전체, `tests/unit/backend-contract-drift.test.ts` 전체, `src/contracts/external-contract-runtime.ts:120-310, 510-530, 620-720`, `src/contracts/env.ts` diff, `src/bootstrap/load-runtime-config.ts:120-155`, `scripts/lib/registry-compatibility.ts:140-165, 300-390`, `scripts/check-registries.ts:150-170`, `tests/unit/schema-metadata-policy.test.ts` 전체, `scripts/lib/removal-fixture.ts:40-170`, 세 capability 제거 드릴 스크립트의 삭제 목록, `src/adapters/http/backend-envelope.ts:130-270`. `git diff 8a44226..bbde570 -- src/contracts config/contracts schemas` 전체와 영역 테스트 diff. 함께 읽은 곳: 생성기의 descriptor·스키마 메타 문자열(`scripts/create-feature.ts:700-840`, `scripts/create-feature-write-slice.ts:205-350`), 참조 기능 contribution | +| 읽은 문서(주장) | `CHANGELOG.md:14-77`(미출시 절의 먼저 할 일·계약 표), `docs/architecture/backend-api-and-server-state-contract.md:161-208`(4.1절), `docs/manual/01-add-a-feature.md:205-305, 535-552`, `docs/manual/reference/errors.md:104-110, 156`, `docs/contracts/compatibility.md:18-37`, `config/ci/ungated-scripts.json:4-7`, 커밋 본문 `daf3474`·`3b62ccd`·`bfd9d50`·`2e1acb1`·`56272e8`·`f600e6b`·`5c0b37e`·`c6c37f3`·`45c9c4d`, 지난 라운드 07 문서, README §15·§16 | +| 수행한 테스트·실험 | 리뷰어는 아무것도 실행하지 않았다(노트북 금지, desktop은 읽기만). 쓴 증거: `desktop:/tmp/claude-gates/bbde570-ci/summary.txt`(CI env, 2026-11-06 03:24-03:56) FE-GATE-001~012·020 rc=0, 013 rc=1(영역 12 몫). 전체 로그 `gate-artifacts/FE-GATE-004.txt`(runtime-schema 60건), `FE-GATE-005.txt`(test:unit 208파일 3,056건, coverage 332파일 4,085건), `FE-GATE-010.txt`(`check:registries` `11 registries PASS; compatibility=additive`), `FE-GATE-020.txt`(제거·생성 드릴). FE-GATE-001~003은 한 줄 로그만 있다(`FE-GATE-003 typecheck: PASS`). 오케스트레이터 공유 실행 `desktop:/tmp/claude-gates/r5/snap/verify-documentation.local.txt`(PASS_SCOPED). 노트북에서 읽기 대조 둘: 사본 17줄 ↔ 백엔드 `45d2a478` 문서(diff 같음), 요청 패치 둘의 `git apply --check`. 오케스트레이터 배치 07-R1~R3(local env, 2026-11-06 04:23, load 2.92, 항목마다 restore clean, 로그 `desktop:/tmp/claude-gates/r5/batch/out/R5-07-R*.log`, 6절) | +| 확인하지 못한 범위·이유 | 짝 백엔드를 실제로 띄워 답을 받지 않았다. 다운스트림 두 repo의 descriptor가 `satisfies`인지 `as`인지 보지 않았다(BREAKING 1단계가 그들에게 실제로 실패를 내는지). `browser-rpc.ts`, `service-worker*.ts`, `web-push.ts`, `query-keys.ts`, `deployment-admission.ts`는 다시 읽지 않았다. 이번 diff가 없거나 영역 07 발견과 무관하다(`service-worker.ts`는 1105/06-01의 상수 하나, `diagnostics.ts`·`server-state.ts`·`storage-keys.ts`는 02-01·1103/16-05·05-01의 추가만, diff로 확인) | +| 이전 리뷰와 비교 가능한 범위 | 지난 07-R1 패치를 그대로 다시 돌렸다(07-R1. 지난 라운드는 PASS `behavior-change`, 이번은 rc=1 breaking). 지난 D6f(desktop drift rc=2)는 07-R3로 다시 돌렸다(rc=0). D6g는 수정 커밋의 drift 단위 테스트가 가짜 백엔드로 돈다(FE-GATE-005, 9건 통과). 지난 실행 결과는 증거로 쓰지 않았다 | + +## 2. 지난 발견 재확인 + +지난 라운드 영역 07 발견은 1105 새 발견 2건(README §15)과 1103 이월 1건(§16.5)이다. §16.6에 영역 07 행은 없다. 지시로 다른 영역 발견 2건(1105/09-03, 1103/16-01)도 다시 봤다. + +| 지난 ID | 내용 | 상태 | 근거 (`bbde570`) | +|---|---|---|---| +| 1105/07-01 | 답 표 JSON이 pin한 백엔드 문서와 같은지 아무 검사도 보지 않고, 백엔드 변경은 게이트 밖 스크립트만 알린다(desktop rc=2, worktree skipped rc=0, 매뉴얼에 없음) | **고쳐짐** | 완료 기준 셋. (1) 답 표와 pin 문서의 어긋남, pin 문서에만 있는 행: drift가 pin 커밋 문서의 표로 `answerTableProblems`를 돌린다(`scripts/check-backend-contract-drift.ts:147-150`). 사본이 pin 문서와 다르면 줄 단위로 찍는다(`:144-146`). pin 뒤 표 행이 바뀌면 찍는다(`:153-168`). drift 단위 테스트가 status 오타, 사본 오타, 옮기지도 적지도 않은 행, D6g를 가짜 백엔드로 돈다(`tests/unit/backend-contract-drift.test.ts:235-286`, FE-GATE-005 9건 통과). (2) checkout이 없으면 rc=2 "not compared"(`:96-110`, 테스트 `:288-293`). 기본 경로는 main checkout 옆이라 linked worktree도 같은 백엔드를 찾는다(`:76-90`). (3) 매뉴얼 01에 언제 무엇을 돌리는지 있다(`docs/manual/01-add-a-feature.md:227-229`). 더해서 게이트 쪽: 답 표를 pin 커밋 표의 사본과 행마다 대조한다(`tests/unit/backend-contract-pin.test.ts:165-179`, FE-GATE-005). 사본 17줄은 `45d2a478:docs/web/http-contract.md:86-91, 109-113, 188-193`과 같다(리뷰어 대조, 1절). pin의 `sectionsCompared` §4 범위 문제는 §4 네 행을 모두 옮겨 풀렸다. 남은 것(다시 세지 않음): 사본 ↔ 실제 백엔드는 게이트 밖이다(D6, `config/ci/ungated-scripts.json:5-6`). §1은 사본에 없고 사람이 읽는다(아래 4절 24번). 실행: 07-R2(사본에만 있는 행 → pin 테스트 1건 실패), 07-R3(desktop drift rc=0, 백엔드 HEAD `3d73b6f`, "docs/web/http-contract.md and 6 scaffold sources unchanged") | +| 1105/07-02 | 응답 스키마를 행과 함께 strict로 좁히는 변경이 FE-REG-SCHEMA에서 behavior-change로 통과한다 | **고쳐짐** | 분류기가 `direction: "RESPONSE"` 행의 `unknownFieldPolicy`가 `REJECT_UNKNOWN`으로 바뀌면 `response-reader-narrowed` breaking으로 본다(`scripts/lib/registry-compatibility.ts:149-161, 368-370`). 넓히는 쪽과 REQUEST 행은 behavior-change다. 단위 테스트 네 방향 + 증거 요구 1건(`tests/unit/registry-compatibility.test.ts:132-184`, FE-GATE-005 28건 통과). 기준선 응답 행에 `direction`이 있어 규칙이 실제 행에 닿는다(`config/contracts/registry-baseline.json:647-655`). 매뉴얼·호환 문서·CHANGELOG가 같다(`docs/manual/01-add-a-feature.md:550`, `docs/contracts/compatibility.md:33-36`, `CHANGELOG.md:37, 64`). 완료 기준(지난 07-R1 패치에서 실패)은 수정 커밋이 "실패해야 한다"로만 적었다. 배치 07-R1에서 `breaking change missing evidence: FE-REG-SCHEMA:ReferenceResourceListPayload:unknownFieldPolicy:response-reader-narrowed`와 `...:ReferenceResourcePayload:...` 2줄로 registries-rc=1이었다. 변이 없는 대조는 FE-GATE-010(`compatibility=additive` PASS)이다. 행이 두 칸을 적지 않는 경로는 이 수정 범위 밖이라 새 07-02로 적었다 | +| 1103/07-04 | 제품 설정 키의 금지 이름 검사가 부팅 때만 돈다(남은 것: 부팅 오류에 키 이름이 없다) | **고쳐짐** | `assertSafeConfigNames`가 `UnsafeConfigNameError`를 던지고 `key`에 점 경로를 싣는다(`src/contracts/env.ts:125-170`). 로더가 그 경로를 `SAFE_KEY_PATTERN`으로 거른 뒤 `invalidKeys`에 넣는다(`src/bootstrap/load-runtime-config.ts:126-137`). 오류 화면이 `invalidKeys`를 "잘못된 설정 키"로 보인다(`src/presentation/boundaries/boot-error-shell.tsx:65-68`). 테스트 4건: 최상위 키, `CAPABILITY_OVERRIDES.AUTH_TOKEN`, `FEATURE_OVERRIDES.alpha.CLIENT_SECRET`, 안전하지 않은 이름은 뺌, 값은 어디에도 없음(`tests/runtime-schema/runtime-config.test.ts:297-334`, FE-GATE-004 42건 통과). 매뉴얼이 같다(`docs/manual/03-outside-feature-folder.md:113`). 한계(결함 아님): 경로가 64자를 넘으면(긴 feature id) 키 이름이 빠지고 code만 남는다. 스키마 실패의 키와 같은 규칙이다(`load-runtime-config.ts:43, 153`) | +| 1105/09-03 (영역 09, 지시로 재판정) | 계약 조립 오류의 원인이 `check:registries` 출력에 두 번 나온다 | **고쳐짐** | `loadErrorText`가 message에 reason이 이미 있으면 붙이지 않는다(`scripts/check-registries.ts:160-168`). 완료 기준("실제 오류 클래스로 원인이 한 번")대로 테스트가 진짜 `ContractContributionError`를 던지는 source로 `check:registries`를 돌리고 원인 문자열이 한 번만 나오는지 본다(`tests/unit/registry-governance.test.ts:656-711`, `:707`의 `toHaveLength(2)`, FE-GATE-005 통과). `errors.md`의 출력 형식 줄이 실제와 같다(`docs/manual/reference/errors.md:156`). 한계: message 첫 줄만 보므로 여러 줄 reason은 다시 붙는다(커밋 본문). 지금 reason은 한 줄이다 | +| 1103/16-01 (영역 16, 지시로 재판정) | Envelope를 operation마다 선언하고, 빠뜨려도 게이트와 MSW 시나리오 테스트가 통과한다(남은 것: 읽기만 있는 기여에서 줄을 모두 빼면 통과) | **고쳐짐** | 완료 기준("줄을 지우면 `check:types` 실패"). 타입이 필수 칸이다(`src/contracts/external-contract-runtime.ts:239`, 주석 `:230-238`). `@ts-expect-error`가 줄 없는 descriptor 선언에 있고(`tests/unit/external-contract-runtime.test.ts:394-405`), FE-GATE-003(check:types:test 포함)이 통과했으니 그 지시문이 쓰였다. 즉 타입이 줄을 요구한다. repo 안 descriptor: 생성기 셋(`scripts/create-feature.ts:800`, `scripts/create-feature-write-slice.ts:275, 329`, 모두 `satisfies InstalledHttpContract`), 참조 기능 셋(`src/features/reference-feature/contracts/reference-feature-contract-contribution.ts:91, 146, 197`), 테스트 fixture와 `scripts/drill-runbook.ts:290`이 값을 적는다. HTTP descriptor가 있는 기능은 참조 기능뿐이다. 생성 테스트가 세 줄을 센다(`tests/unit/create-feature.test.ts:251`). BREAKING 꼬리말·CHANGELOG 먼저 할 일 1·계약 표가 코드와 같다(`CHANGELOG.md:24, 59`). 런타임은 빠진 값을 전처럼 `NONE`으로 읽는다(`external-contract-runtime.ts:520-524, 715-716`, `src/contracts/api-operations.ts:84`). 기준선 FE-REG-API 행은 그대로다. FE-GATE-010의 `compatibility=additive`에서 바뀐 것은 `FE-REG-STORAGE:AUTH_REDIRECT_TRANSACTION:*:added` 하나뿐이다(`desktop:/tmp/claude-gates/r5/snap/merge/artifacts/quality/registries.json:7-15`, 03:54 산출물). 남은 문서 한 줄은 새 07-01로 적었다 | + +틀린 발견으로 판정한 것은 없다. README §16과 다르게 판정한 것도 없다. + +## 3. 이번 발견 (36.3) + +새 발견 2건. 심각도 Low 2. 우선순위 P3 2. 성격 확인된 결함 1, 구조적 위험 1. High 이상과 P1은 없다. 남은 지난 발견은 없다. + +### 07-01 계약 문서가 bulk 엔드포인트에 "`responseEnvelope`를 빼라"고 적는다. 빼면 `check:types`가, 같은 기여에 `"NONE"`을 적으면 계약 조립이 실패한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 (문서와 코드가 다르다. 정적 확인) | +| 관련 관점 | 20, 9, 23, 17 | +| 근거 | 계약 문서 4.1절 끝 줄: "bulk 엔드포인트를 붙이려면 `responseEnvelope`를 빼고 기능 스키마가 본문 전체를 읽는다"(`docs/architecture/backend-api-and-server-state-contract.md:205-207`). 코드: 칸은 필수다(`src/contracts/external-contract-runtime.ts:239`). 같은 기여 안에서 값이 다르면 조립이 거절한다(`:709-720`). 같은 문서의 바로 위 줄은 "이 칸은 필수라 빠뜨리면 `check:types`가 실패한다"고 적는다(`:196-198`). 매뉴얼은 "줄은 빼지 않는다"(`docs/manual/01-add-a-feature.md:214`), errors.md는 빠진 줄의 tsc 오류를 적는다(`docs/manual/reference/errors.md:109`). 이력: 그 줄은 `49a0986`(2026-11-04 20:46)이 썼다. 같은 날 22:56 `3f7e10c`(기여 하나에 응답 모양 하나)부터 맞지 않았다. `56272e8`(BREAKING)은 같은 절의 위 줄을 고쳤지만 이 줄을 남겼다. `git grep`으로 `responseEnvelope`를 빼라는 문장은 이 줄 하나다 | +| 발생 조건 | 짝 백엔드의 bulk(`results`, `BATCH_PARTIAL_FAILURE`) 엔드포인트를 Envelope 기능(생성 기능)에 붙이려고 이 문서를 따를 때 | +| 영향 | 런타임 피해는 없다. 줄을 빼면 `check:types`가 그 descriptor에서 실패한다. `"NONE"`을 적으면 조립이 `responseEnvelope NONE, but ... reads ENVELOPE_V1; ... split the contribution per backend`로 거절해 부팅과 `check:registries`가 실패한다. 오류 메시지가 "기여를 나눈다"를 말해 길은 찾을 수 있다. 같은 백엔드인데 기여를 나눠야 한다는 것은 어느 문서에도 없다. 조립은 한 기능의 기여 둘을 받는다(`tests/unit/external-contract-runtime.test.ts:377-384`, `src/features/feature-module.ts:65`) | +| 심각도·우선순위 | Low · P3 — 문서 한 줄이다. 잘못 따르면 게이트가 바로 막는다 | +| 통제·증거 | 목표 M1(안내가 타입·조립 규칙과 같다) / 확인: 이 줄은 틀림. 잘못된 시도는 타입(M4)과 조립(M4)이 막는다 · E1 | +| 확실성과 남은 가정 | 문서 문장과 타입·조립 코드를 읽어 확정했다. bulk operation을 `"NONE"` 별도 기여로 붙여 실제로 돌려 보지는 않았다 | +| 결정의 근거 | 적용 제외 — BREAKING 수정이 문서 한 줄을 놓친 단순 불일치다 | +| 이해 비용 | bulk를 붙이는 사람이 실패 두 번을 겪고 조립 오류 문구에서 방법을 읽어야 한다 | +| 최소 개선 방향 | 그 줄을 "bulk operation은 `responseEnvelope: "NONE" as const`로 적고 별도 계약 기여에 둔다. 기능 스키마가 본문 전체를 읽고 `classifyProblem`이 적용 여부를 정한다"로 고친다 | +| 대안 비교 | 적용 제외 — 바른 방법은 이미 코드와 테스트(`:377-384`)가 정한다 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 문서 한 줄 | +| 재검토 조건 | 1103/03-02(bulk 지원 여부) 결정 대기가 "지원"으로 정해지면 이 줄을 그 방법으로 바꾼다 | +| 완료 기준 | 계약 문서에 `responseEnvelope`를 빼라는 문장이 없다(`git grep`). 문서가 말하는 방법이 타입 검사와 조립을 통과한다 | +| 검증 방법 | `git grep -n 'responseEnvelope.\{0,4\}를 빼' -- docs ':!docs/reviews'` 0건. 원하면 `tests/unit/external-contract-runtime.test.ts:377-384`과 같은 꼴로 bulk 기여 하나를 조립 | +| 담당·기한·상태 | 미정 · 미정 · 신규 (1103/16-01 수정 뒤 남은 문서) | +| 재검증 결과 | 미실시 | + +### 07-02 스키마 메타 행이 `direction`·`unknownFieldPolicy`를 적지 않으면 정책 테스트가 건너뛰어, 응답 DTO를 strict로 바꿔도 아무 검사도 보지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 (정적 확인. 지금 템플릿 행과 생성기가 만드는 행은 두 칸을 모두 적는다) | +| 관련 관점 | 17, 21, 10, 20 | +| 근거 | 두 칸은 타입에서 선택이다(`src/contracts/schema-registry.ts:17-18`). FE-REG-SCHEMA 필수 칸은 `schemaId`·`boundary`·`owner`·`runtime`뿐이다(`config/contracts/registry-governance.json:263`). 1103/07-03 정책 테스트는 행이 값을 적지 않으면 그 자리를 건너뛴다: 방향 `declared === undefined`(`tests/unit/schema-metadata-policy.test.ts:130`), 정책 `if (declared === undefined) return []`(`:157`). 1105/07-02 수정은 행의 값이 `REJECT_UNKNOWN`으로 바뀔 때만 등급을 매긴다(`scripts/lib/registry-compatibility.ts:149-161`). 그래서 손으로 쓴 기능이 HTTP 응답 행에 두 칸 없이 들어오면(행 추가 = additive), 뒤에 응답 DTO를 `.strict()`로 바꿔도 행이 바뀌지 않아 `check:registries`에는 변화가 없고 정책 테스트는 건너뛴다. 이미 적힌 칸을 지우는 것은 `field-removed` breaking이라 잡힌다(`registry-compatibility.ts:342-344`). 생성기는 두 칸을 늘 쓴다(`scripts/create-feature.ts:723-742`, `scripts/create-feature-write-slice.ts:212-221`). 매뉴얼은 "손으로 적지만 test가 실제 쓰임과 대조한다"고만 적고, 적지 않은 경우를 말하지 않는다(`docs/manual/01-add-a-feature.md:267-271`) | +| 발생 조건 | 기능 작성자가 생성기 없이 스키마 메타 행을 쓰며 두 칸을 빼고, 나중에 응답 DTO를 strict로 바꿀 때 | +| 영향 | 1105/07-02와 같다. 백엔드가 응답에 필드 하나를 더하면 그 API가 `SCHEMA_MISMATCH`로 실패한다. 1105/07-02 때와 달리 스냅샷 diff에도 아무것도 남지 않는다 | +| 심각도·우선순위 | Low · P3 — 생성기와 참조 기능은 두 칸을 적는다. 손으로 쓴 행에서 두 칸을 빼야 생긴다. 피해는 백엔드가 필드를 더한 뒤에 난다 | +| 통제·증거 | 목표 M3(HTTP 응답 경계를 좁히는 변경은 breaking이거나 테스트가 실패) / 확인: 두 칸을 적은 행 M3(1105/07-02), 적지 않은 행 M0 · E1 | +| 확실성과 남은 가정 | 코드로 확정했다. 실행하지 않았다(두 칸 없는 행을 기준선에 넣어야 해서 변이가 크다). 다운스트림 두 repo의 스키마 메타 행이 두 칸을 적는지는 보지 않았다 | +| 결정의 근거 | 기록된 결정: 1103/07-03 테스트는 "행이 적은 값"을 검증기와 대조하도록 만들어졌다(테스트 주석 `:11-24`). 적지 않은 행을 어떻게 볼지는 적혀 있지 않다. 리뷰어 판단: route 전용 행(`none`, `NotFoundSplat`)은 두 칸이 없어도 된다. HTTP 자리에 쓰인 스키마는 두 칸이 있어야 1105/07-02 규칙이 닿는다 | +| 이해 비용 | 적음. 생성기를 쓰면 생기지 않는다 | +| 최소 개선 방향 | (A) 정책 테스트에서 HTTP 자리(`slots`)에 쓰인 스키마의 행이 두 칸을 적지 않으면 실패로 센다(`:130`, `:157`의 `undefined` 분기). (B) governance가 `api-*` 경계 행에 두 칸을 필수로 둔다 | +| 대안 비교 | (A) 테스트 두 줄. 템플릿 HTTP 행은 이미 두 칸을 적어 통과한다. 기준선·governance는 그대로다. (B) 경계별 필수 칸 규칙이 governance에 없어 분류기 변경과 기준선 재승인이 필요하다. (C) 현 상태: 생성기를 쓰는 한 생기지 않는다. 손으로 쓴 행만 위험 | +| 단순화의 보존 조건 | 적용 제외 — 검사 추가다 | +| 비용·부작용 | (A) 다운스트림이 두 칸 없는 HTTP 행을 가졌다면 동기화 때 `test:unit`이 실패한다. 행에 두 칸을 적으면 된다 | +| 재검토 조건 | 검증기가 정책을 스스로 보고하게 되면(지난 라운드 07-02의 재검토 조건) 행 칸 대신 그 값을 쓴다 | +| 완료 기준 | 참조 응답 행에서 `direction`·`unknownFieldPolicy`를 지운 트리에서 `tests/unit/schema-metadata-policy.test.ts`가 실패한다 | +| 검증 방법 | 위 변이로 정책 테스트 1파일 | +| 담당·기한·상태 | 미정 · 미정 · 신규 (1103/07-03·1105/07-02 수정이 닿지 않는 경로) | +| 재검증 결과 | 미실시 | + +## 4. 28개 관점 판정 (36.2) + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가 + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +|---|---|---|---|---|---| +| **1** | 코드 성숙도 | 적용. 조립기가 계약 규칙의 유일한 입구다 | M4 / M4 | E2(FE-GATE-005 `external-contract-runtime.test.ts` 47건) | O — 읽기 `SAFE`·`IDEMPOTENT`, 쓰기 `SAFE` 금지, 기여당 응답 모양 하나에 더해 6.1절의 "쓰기 뒤 가능" 플랫폼 code 20개를 `refusedBeforeWrite`에 적지 못한다(`external-contract-runtime.ts:638-662, 691-695`). 목록은 6.1절 표와 양방향 대조된다(`backend-contract-pin.test.ts:293-302`) | +| 2 | 구조적 성숙도 | 적용 | M3 / M3 | E2(FE-GATE-010 `check:architecture` 통과) | O — 6.1 목록을 adapters가 아니라 contracts에 둔 이유가 커밋에 있다(조립 검사는 adapters를 import할 수 없다, `5c0b37e`) | +| **3** | 변경 용이성 | 적용. API 하나 추가·변경, pin 올리기 | M3 / M3 | E2 | O — pin을 올리는 순서가 명령 하나(`--write-excerpt`)와 매뉴얼 두 줄로 정해졌다(`docs/manual/01-add-a-feature.md:228-229`). 백엔드 생성기 템플릿 파일도 pin에 있다(`backend-contract-pin.json:8-39`, 1105/16-02) | +| 4 | 인지 부하 | 적용 | M1 / M1 | E1 | O — pin·답 표·사본·drift의 역할이 한 주석에 있다(`scripts/lib/backend-contract-excerpt.ts:1-11`) | +| 5 | 위험 가시성 | 적용 | M2 / M3 | E2 | O — 응답 경계를 좁히는 변경이 breaking 증거를 요구한다(1105/07-02). drift의 "비교 못 함"이 rc=2로 드러난다 | +| 6 | 실패 성숙도 | 적용 | M3 / M3 | E2 | O — 조립 실패 원인이 `check:registries`에 한 번 나온다(1105/09-03) | +| 7 | 운영 성숙도 | 다른 영역 | - | - | > 영역 03·13 | +| 8 | 디버깅 가능성 | 적용 | M2 / M2 | E2(FE-GATE-004, 005) | O — 부팅 `CONFIG_SECRET_NAME_REJECTED`가 키 경로를 싣는다(1103/07-04). drift와 pin 테스트가 어긋난 행을 문장으로 말한다 | +| 9 | 유지보수 성숙도 | 적용 | M2 / M1 | E1 | P — 통합 때 생긴 pin·문서 어긋남은 `45c9c4d`이 고쳤다. 계약 문서 bulk 줄이 BREAKING 뒤에도 남았다(07-01) | +| **10** | 테스트 성숙도 | 적용 | M3 / M3 | E2(FE-GATE-005, 07-R1·R2 변이 둘 다 기대한 이유로 실패) | P — 새 테스트: drift 9건(가짜 백엔드 git repo), pin 15건, 분류기 5건, 조립 원인 1건, 부팅 키 4건. `answerTableProblems`의 "copied and notCopied"·"stale notCopied" 두 분기는 어느 테스트도 돌지 않는다(5절). 정책 테스트가 두 칸 없는 행을 건너뛴다(07-02) | +| 11 | 데이터 성숙도 | 다른 영역 | - | - | > 영역 05 | +| 12 | 동시성 성숙도 | 적용 제외. 계약은 순수 선언과 검사다 | - | - | - | +| 13 | 확장성 | 적용 | M2 / M2 | E2(FE-GATE-020 생성 드릴) | O — 생성 기능이 `responseEnvelope`와 스키마 메타 두 칸을 적고 게이트를 통과한다 | +| 14 | 성능 성숙도 | 다른 영역 | - | - | > 영역 15. 6.1 code 검사가 초기 JS +327 B(README §16.2 D7). 조립 때 한 번 돈다 | +| **15** | 보안 성숙도 | 적용 | M4 / M4 | E2(FE-GATE-005 `rest-profile-contract`·`env-registry-coverage`) | O — 이번 diff는 CSRF·zod facade·금지 설정 키 검사를 바꾸지 않았다. 부팅 오류가 키 이름만 싣고 값은 싣지 않는다(`runtime-config.test.ts:331`) | +| 16 | 의존성 성숙도 | 다른 영역 | - | - | > 영역 13 | +| **17** | API / Contract 성숙도 | 적용 | M3 / M3(부분) | E2(FE-GATE-005·010, 07-R1·R2), E3(07-R3 실제 백엔드 checkout), E1(사본 ↔ 백엔드 대조) | P — 답 표 ↔ 사본 ↔ 프론트 표가 게이트에서 잠겼다(1105/07-01, 07-R2). 응답 축소가 breaking이다(1105/07-02, 07-R1). 사본 ↔ 실제 백엔드는 게이트 밖이고(D6), desktop에서 돌리면 일치한다(07-R3). 두 칸 없는 응답 행은 빈틈이다(07-02). bulk 안내가 틀렸다(07-01) | +| 18 | 배포 성숙도 | 다른 영역 | - | - | > 영역 13 | +| **19** | 설정 성숙도 | 적용 | M3 / M3 | E2(FE-GATE-004·005) | O — 금지 키가 `test:unit`에서 잡히고 부팅 오류가 그 키를 말한다(1103/07-04 고쳐짐) | +| **20** | 개발자 경험 | 적용 | M2 / M2 | E1 | P — drift가 매뉴얼에 있고 worktree에서도 같은 백엔드를 찾는다. bulk 안내가 두 번 실패하는 길로 보낸다(07-01) | +| **21** | Guardrail 성숙도 | 적용 | M3 / M3(부분) | E2 | P — breaking 칸, 참조, 조립 규칙, 새 `response-reader-narrowed`가 동작한다. 검사를 약하게 한 수정은 없다(0절). 백엔드 변경 검출은 게이트 밖이다(설계). 두 칸 없는 행(07-02) | +| 22 | 추상화 성숙도 | 적용 | M2 / M2 | E1 | O — 표 읽기가 한 파일(`backend-contract-excerpt.ts`)에서 테스트와 drift에 같이 쓰인다 | +| **23** | 일관성 | 적용 | M2 / M2 | E1 | P — FE-REG-API와 FE-REG-SCHEMA의 경계 축소 등급이 맞춰졌다(1105/07-02). 계약 문서 한 줄이 타입·조립과 다르다(07-01). Browser RPC는 여전히 `KEYED_COMMAND`·`NON_REPLAYABLE`이다(`src/contracts/browser-rpc.ts:51-52`, 지난 라운드와 같음, 세지 않음) | +| 24 | 네이밍 / 의미 성숙도 | 적용 | M2 / M2 | E1 | P — pin의 `sectionsCompared`는 `["1","2","4"]`인데 사본은 §2·§4만 담는다(`backend-contract-pin.json:7`, 사본 `:8-35`). §1(Envelope 키 규칙)은 code·status 행이 없어 사람이 읽고, pin 뒤 변경은 문서 전체 diff가 알린다(`check-backend-contract-drift.ts:154-158`). 계약 문서 4.1이 §1을 정본으로 적어(`backend-api-and-server-state-contract.md:166-167`) 뜻은 맞다. 발견으로 세지 않는다 | +| 25 | 조직 확장성 | 적용 | M2 / M2 | E2(`second-api-feature-registries`, FE-GATE-005) | O — 기능 팀이 governance·기준선을 고치지 않고 API를 더한다 | +| 26 | Ownership 성숙도 | 적용 | M2 / M2 | E1 | O — pin에 `owner`·`comparedOn`이 있고, 매뉴얼이 "짝 백엔드를 새로 받을 때마다" 돌린다고 정했다(`docs/manual/01-add-a-feature.md:228`) | +| 27 | 삭제 가능성 | 적용 | M3 / M3 | E2(FE-GATE-020 rc=0) | O — 문서 테스트 제외 목록(`scripts/lib/removal-fixture.ts:70-81`)의 pin 테스트는 capability 드릴 셋에서만 빠진다(`:84-90`). 세 드릴이 지우는 경로(`scripts/test-realtime-runtime-removal.ts:24-34`, `scripts/test-browser-file-storage-runtime-removal.ts:29-47`, `scripts/test-optional-recipe-removal.ts:38-42`)는 pin 테스트가 읽는 `backend-envelope.ts`·`external-contract-runtime.ts`·`config/contracts/*`와 겹치지 않는다. 문서를 복사하는 참조 기능 제거·생성 드릴에서는 pin 테스트가 돈다(FE-GATE-020 로그 8회 통과, 모두 capability 드릴 앞). 제외 목록이 그 파일이 문서를 읽는지 확인한다(`tests/unit/removal-fixture.test.ts:155-163`). 개선 여지(세지 않음): 6.1 대조 하나만 다른 파일로 떼면 나머지 14건도 capability 드릴에서 돈다 | +| 28 | 회복 가능성 | 적용 제외. 계약은 복구 절차를 소유하지 않는다 | - | - | - | + +X(미충족)인 관점은 없다. + +## 5. 미검증 + +- 07-R1 패치로는 `check:registries`만 돌렸다. 그 패치에서 vitest·component·e2e는 돌리지 않았다(지난 라운드에 돌렸고 모두 통과했다. 이번 판정에는 쓰지 않는다). +- 07-R2는 사본에 행을 더한 경우만 봤다. 답 표에서 행을 지운 경우는 같은 분기(`backend-contract-excerpt.ts:146-149`)라 따로 돌리지 않았다. +- `answerTableProblems`의 "both copied and listed in notCopied"(`backend-contract-excerpt.ts:142-145`)와 "notCopied ... is not a row"(`:152-158`) 분기는 어떤 테스트도 돌지 않는다. 앞 분기는 통합 때 실제로 실패를 냈다(`45c9c4d` 본문). 코드는 맞게 읽힌다. +- 07-02 경로는 실행하지 않았다(두 칸 없는 행을 기준선에 넣는 변이가 크다). +- BREAKING 1단계가 다운스트림 descriptor에서 실제로 `check:types` 실패를 내는지: descriptor를 `satisfies`·주석 타입이 아니라 `as`로 쓰면 줄이 없어도 통과한다(TypeScript `as`는 빠진 칸을 허용한다). 그래도 런타임은 전과 같이 `NONE`이라 피해는 없다. 두 다운스트림 코드는 읽지 않았다. +- 실제 짝 백엔드를 띄워 §2·§4 답을 받아 보지 않았다. + +## 6. 실행 기록 + +리뷰어는 아무것도 실행하지 않았다. 게이트 결과는 오케스트레이터 로그(`desktop:/tmp/claude-gates/bbde570-ci/`, CI env)를 읽었다. 배치 요청은 `scratchpad/r5/requests/07.md`에 있다. 오케스트레이터가 `bbde570`에서 항목마다 하나씩 돌렸다(local env, 2026-11-06 04:23:23~25, load 2.92). 세 항목 모두 끝난 뒤 `restore=clean`이다. 로그는 `desktop:/tmp/claude-gates/r5/batch/out/R5-07-R1.log`~`R3.log`다. 명령 끝이 `echo`라 항목 rc는 0이고, 판정은 `*-rc=` 줄로 했다. + +| 요청 | 발견 | 명령 · env | 변이 | rc | 결과 | +|---|---|---|---|---|---| +| 07-R1 | 1105/07-02 완료 기준 | `corepack pnpm -s check:registries` · local | `requests/07-R1-strict-response.diff`(응답 DTO `.strict()` + 응답 행 둘 `REJECT_UNKNOWN`, 지난 라운드와 같은 패치) | registries-rc=1 | **잡힘(기대대로).** `Registry governance failed:` 다음에 `breaking change missing evidence: FE-REG-SCHEMA:ReferenceResourceListPayload:unknownFieldPolicy:response-reader-narrowed`와 `...:ReferenceResourcePayload:unknownFieldPolicy:response-reader-narrowed` 2줄. 대조는 FE-GATE-010(`11 registries PASS; compatibility=additive`) | +| 07-R2 | 1105/07-01 · `45c9c4d` | `node scripts/run-vitest.ts run tests/unit/backend-contract-pin.test.ts` · local | `requests/07-R2-uncopied-row.diff`(사본 §4에 `RATE_LIMIT_EXCEEDED` 429 행 추가) | vitest-rc=1 | **잡힘(기대대로).** 15건 중 "copies the answers from the backend table rows at the pin" 1건만 실패, 14건 통과. 받은 값 `["§4 429 RATE_LIMIT_EXCEEDED is neither in the answer table nor in the pin's notCopied"]`(`backend-contract-pin.test.ts:178`). 대조는 FE-GATE-005(15건 통과) | +| 07-R3 | 1105/07-01 (b) | `corepack pnpm -s check:backend-contract-drift` · local | - | drift-rc=0 | `Backend contract drift: HEAD 3d73b6f1ba82 is past the pin 45d2a478b800, docs/web/http-contract.md and 6 scaffold sources unchanged; the excerpt and the answer table match it`. 옆 checkout HEAD `3d73b6f1ba82404eeed763cabd0e688c91a44c9b`(노트북 backend checkout과 같은 커밋) | + +## 7. 새 발견 요약 + +| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line | +|---|---|---|---|---| +| 07-01 | Low · P3 | 확인된 결함 | 계약 문서가 bulk 엔드포인트에 "`responseEnvelope`를 빼라"고 적는다. 빼면 `check:types`가, 같은 기여에 `"NONE"`을 적으면 조립이 실패한다(1103/16-01 BREAKING 뒤 남은 줄) | `docs/architecture/backend-api-and-server-state-contract.md:205-207`, `src/contracts/external-contract-runtime.ts:239, 709-720` | +| 07-02 | Low · P3 | 구조적 위험 | 스키마 메타 행이 `direction`·`unknownFieldPolicy`를 적지 않으면 정책 테스트가 건너뛰어, 응답 DTO를 strict로 바꿔도 `check:registries`·`test:unit` 어느 쪽도 보지 않는다 | `tests/unit/schema-metadata-policy.test.ts:130, 157`, `config/contracts/registry-governance.json:263`, `src/contracts/schema-registry.ts:17-18` | diff --git a/docs/reviews/2026-11-06-maturity-review/08-presentation.md b/docs/reviews/2026-11-06-maturity-review/08-presentation.md new file mode 100644 index 00000000..a8bd17d5 --- /dev/null +++ b/docs/reviews/2026-11-06-maturity-review/08-presentation.md @@ -0,0 +1,237 @@ +# 영역 08 — presentation + +> 검토일 2026-11-06 · 기준 `bbde570`(PR B `fix/maturity-review-2026-11-05-b` 끝, PR #7) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 경로 `src/presentation/`. 연결 확인: 참조 기능 폼 페이지(`src/features/reference-feature/presentation/`), 생성기 쓰기 슬라이스 템플릿(`scripts/create-feature-write-slice.ts`), 시각 골든(`tests/visual/__snapshots__/`), 빌드 산출의 `navigation-policy` 청크 +> 깊게 본 관점 1, 6, 10, 14, 23, 24, 28 +> 렌즈: 1105 조치 다섯(08-01~08-04, 1103/03-01 폼 쪽)의 완료 기준, 08-03이 더한 초기 파일, 15-05 `scrollbar-gutter`의 화면 쪽 영향, 화면을 떠났다가 돌아온 폼 +> **영역 판정(35.8): 조건부 사용 가능.** 셸, 디자인 시스템, 읽기 화면, 필드 검증 400을 받는 폼, `refusedBeforeWrite`를 선언한 쓰기 폼은 쓸 수 있다. 선언한 거절은 이제 기능 문구(`refusalMessages`)로 보일 수 있다. 조건은 지난 라운드와 같다. 기능이 업무 거절 code를 모두 선언해야 한다. 선언하지 않은 code는 지금도 막다른 길이다(2절 1103/03-01). 새로 본 것: 저장 중에 화면을 떠난 경우의 결과 표시가 비어 있다(08-01, 08-02). 일반 스크롤바 데스크톱에서 열린 drawer·모달 가림막이 오른쪽 15 px를 덮지 않는다(08-03). + +## 0. 결론 + +- **1105 새 발견 4건(08-01~08-04)은 완료 기준까지 고쳐졌다.** 근거는 `bbde570` merge 단계 로그다. 08-01의 e2e 3건이 chromium·firefox·webkit에서 통과했다(FE-GATE-008). 08-02의 생성 기능 테스트가 NEVER·KEYED 두 드릴에서 통과했다(FE-GATE-020). 08-03·08-04의 테스트가 FE-GATE-005에서 통과했다. 08-01·08-03·08-04 수정을 되돌린 변이 셋은 모두 그 테스트에서 기대한 이유로 실패했다(08-R3~08-R5). +- **1103/03-01 폼 쪽은 일부다.** 고쳐진 것: 기능이 거절 code에 자기 문구와 필드를 붙일 자리(`refusalMessages`)가 생겼다(`use-app-form.ts:50-59`, `:251-271`). 그 장치를 끄는 변이는 테스트 두 행으로 잡혔다(08-R6). 남은 것 셋: (1) 선언하지 않은 code는 거절 문구 없이 결과 불명이고, "변경됨으로 확인"이 저장되지 않은 요청을 "저장했습니다."로 바꿀 수 있다. 1103 완료 기준의 둘째 문장이 그대로 미충족이다. (2) KEYED 재전송이 `500 IDEMPOTENCY_RECOVERY_REQUIRED`를 받아도 재전송 버튼이 남는다(결정 대기). (3) 선언한 409를 필드 오류로 바꾸는 코드가 VD-04 결정 5("409는 validation으로 바꾸지 않는다")와 이제 직접 어긋난다. README §16.5는 (2)만 적었다. +- **08-03이 더한 `navigation-policy` 청크는 사용자에게 보이는 효과가 없고, 그 자체로 결함이 아니다.** 0.37 kB(gzip) 파일 하나다. boot 청크의 정적 import라 boot의 다른 의존 22개와 같은 병렬 묶음에서 받는다. 새 요청 단계(waterfall)를 만들지 않는다. 예산은 영역 15 소관이다. +- **15-05 `scrollbar-gutter: stable`: 빈 15 px 띠 자체는 받아들일 만하다. 하지만 열린 drawer·모달의 가림막이 그 띠를 덮지 않는다.** 새 compact 골든에서 가림막은 x 0~375 px에서 끝나고, 375~390 px가 어둡게 덮이지 않은 밝은 세로 띠로 남는다. 옛 골든은 390 px까지 덮었다. 넓은 골든에서는 header의 흰 띠가 1425 px에서 끝난다. 스크롤바를 보이게 띄운 Chromium에서도 스크롤되지 않는 홈(1440 px)의 header는 1425 px에서 끝났다(08-R2). 새 발견 08-03(Low·P3)이다. +- **새 발견 3건, 모두 Low·P3.** 다시 마운트한 참조 폼이 자기가 시작하지 않은 저장의 끝을 보이지 않는다(08-01). 생성 기능 작성 폼이 저장 중에 떠난 사용자를 저장이 끝나면 상세 화면으로 옮긴다(08-02). gutter 띠를 가림막과 header가 칠하지 않는다(08-03). 08-01은 jsdom probe(08-R1), 08-02의 라우터 동작은 최소 probe(08-R7)로 실행해 확인했다. +- **약해진 검사는 없다**(2.1절). 시각 골든 5장을 다시 찍은 것은 의도한 폭 변경 때문이다. 다만 새 골든이 08-03의 띠를 그대로 고정했다. +- 이 영역 이월: 0929/08-01(locale 목록)과 0929/08-08(로그인 복귀 주소)은 남음이다. README §16.6에는 두 항목이 없다. + +## 1. 범위 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` | +| 커밋·작업 상태·확인 시점 | `bbde570`(PR B 끝, PR A `a793b83` 위, main `409d72e` 위). 노트북 worktree `happy-easley-233d07`(HEAD = 기준, 브랜치 `docs/maturity-review-2026-11-06`)에서 읽기만 했다. 미추적 `AGENTS.md`는 무시했다. 2026-11-06 | +| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음. 짝 백엔드 pin `45d2a478`(`config/contracts/backend-contract-pin.json`) | +| 필수 요구와 규모·운영 목표 | `PRODUCT.md`: WCAG 2.2 AA, 한국어 기본 + 영어. 짝 백엔드 Envelope 계약. 화면 규모 목표 없음 | +| 읽은 코드·구성 범위 | `src/presentation/forms/use-app-form.ts` 전부, `form-components.tsx`(31-128행), `templates/page-templates.tsx`(60-95행), `components/async-surface.tsx`(120-240행), `adapters/query/application-query.ts`(336-460, 560-900행), `pages/home-page.tsx`, `layouts/app-shell.tsx`(190-205행), `routes/navigation-policy.ts`, `examples/platform-overview-page.tsx`(60-80, 430-485행), `styles/theme/base.css`, `primitives.css`(400-445행), `shell.css`(40-60행), `design-system/primitives/dialog.tsx`·`drawer.tsx`, `i18n/message-contract.ts`·`catalog.ts` 일부. 연결: `reference-resource-form-page.tsx` 전부, `create-feature-write-slice.ts`(615-930행), `use-dirty-navigation-guard.tsx`, `backend-envelope.ts`(140-340행), `docs/manual/02-decision-tables.md`(115-190행), VD-04. 시각 골든 5장 중 2장(`app-shell-compact-pseudo-drawer`, `app-shell-wide-light`)과 그 부모 커밋 `e02f252^`의 같은 두 장을 이미지로 비교했다. `git diff 8a44226..bbde570 -- src/presentation src/features/reference-feature/presentation scripts/create-feature-write-slice.ts tests/component tests/features tests/e2e tests/visual tests/unit/create-feature.test.ts` | +| 수행한 테스트·실험 | 직접 실행 0건. 오케스트레이터 배치 7건(08-R1~08-R7, 6절, 2026-11-06 04:33~04:34, 모두 `restore=clean`): probe 3건(08-R1 jsdom, 08-R2 Playwright Chromium 스크롤바 보이게, 08-R7 jsdom), 변이 4건(08-R3~08-R6). 게이트와 산출은 desktop 기록을 읽었다(아래) | +| 확인하지 못한 범위·이유 | 5절 | +| 이전 리뷰와 비교 가능한 범위 | `2026-11-05-maturity-review/08-presentation.md`의 08-01~08-04와 그 문서 2절의 이월 항목, README §15·§16.4~§16.6. README §16은 주장으로만 읽었다. 지난 실행 결과는 증거로 쓰지 않았다 | + +실행 환경 기록(모두 `bbde570`, desktop 읽기만): + +- merge 단계, CI env(`desktop:/tmp/claude-gates/bbde570-ci/summary.txt`, 03:24~03:56): FE-GATE-001~012·020 rc=0, FE-GATE-013 rc=1(전제 조건, 영역 12·13 소관). +- 이 영역 근거로 쓴 줄: + - FE-GATE-008(`gate-artifacts/FE-GATE-008.txt`): e2e 222 통과, 4 skipped(firefox SW 4건, 영역 06·11). `reference-save.spec.ts` 8건 × 3엔진 통과. 그중 1105/08-01 새 3건은 `:136`, `:200`, `:216`. 시각 6건 통과(새 골든). + - FE-GATE-005(`gate-artifacts/FE-GATE-005.txt`): `reference-page.test.tsx` 27(`:409`), `form-foundation.test.tsx` 34(`:432`), `example-pages.test.tsx` 4(`:469`), `starter-pages` 2, `async-surface` 35, `product-feature-switch` 4, `application-mutation-admission` 19, `layout-landmarks` 4, `create-feature.test.ts` 46, `navigation-policy.test.ts` 4, `lab-performance.test.ts` 9 모두 ✓. 전체 332 files 통과. + - FE-GATE-020(`gate-artifacts/FE-GATE-020.txt`): 생성 기능 테스트 "opens the list after the user confirms a create whose response was lost"가 test:sample-removal(NEVER, `:2189`)과 test:feature-scaffold(KEYED, `:4917`)에서 통과. + - FE-GATE-012: 초기 JS 204,158 / 206,848 gzip B, 27 / 32 파일, PASS. +- 오케스트레이터 공유 실행(`desktop:/tmp/claude-gates/r5/snap/`): `build.txt`(청크 목록, `navigation-policy-BlaVRSY7.js` 0.56 kB / gzip 0.37 kB), `base/dist/`(`index.html`, `.vite/manifest.json`), `lab.txt`(PASS, LCP 2032 ms, `/` CLS 0, 상호작용 151 ms, 기능 라우트 402 ms), `verify-documentation.*.txt`(둘 다 PASS_SCOPED). + +## 2. 지난 발견 재확인 + +줄 번호는 `bbde570` 기준이다. 08-Rk는 6절의 배치 요청 ID다. + +| 지난 ID | 내용 | 상태 | 근거 | +|---|---|---|---| +| 1105/08-01 | 실패 상태의 복구 버튼을 키보드로 누르면 일이 끝난 뒤 포커스가 `body`로 떨어진다 | 고쳐짐 | 폼의 포커스 effect가 직전에 그린 결과를 기억한다(`use-app-form.ts:123-135`). 결과가 상태 결과나 `effect-unknown`에서 `success`로 바뀌었고 포커스를 잃었으면(`:489-493`) feedback 자리로 옮긴다. 완료 기준(1105 08-R2의 세 경우에서 일이 끝난 뒤 포커스가 feedback 자리 안)을 e2e가 본다: `reference-save.spec.ts:136`(다시 시도), `:200`(확인), `:216`(재전송, 같은 키). 셋 다 3엔진 통과(FE-GATE-008). jsdom 3행은 `reference-page.test.tsx:550`. 처음 저장이 그냥 성공할 때는 옮기지 않는다(`previous`가 `idle`). 되돌리는 변이(08-R3, `recovered` 항상 false)는 jsdom 세 행이 `toHaveFocus`로 실패했다(3 failed / 24 passed). 다시 마운트한 폼의 확인 경로는 결과가 `success`가 되지 않아 이 장치가 걸리지 않는다. 원인이 다르다(`settleApplied`가 다시 마운트를 모름). 그래서 새 발견 08-01로 적었다 | +| 1105/08-02 | 생성 기능 폼이 "변경됨으로 확인" 뒤 아무것도 보이지 않고 입력을 비운다 | 고쳐짐 | 확인 뒤 `settleApplied` → 목록으로 이동한다(`create-feature-write-slice.ts:724-731`). 생성 기능 테스트 한 행(`:916`)이 목록 제목과 항목, POST 1회를 본다. 두 드릴에서 통과(FE-GATE-020 `:2189`, `:4917`). 완료 기준("확인 문구가 보이거나 목록 화면")을 충족한다. 남은 위험: 짝 백엔드 생성기에는 목록 GET이 아직 없다. 실제 짝 백엔드에서는 이동한 목록이 405를 받는다(커밋 `90c489c` 본문). 이것은 1103/03-07(결정 대기)에 속한다. 새로 세지 않는다 | +| 1105/08-03 | 홈 시작 링크가 런타임에 꺼진 기능의 라우트를 가리킨다 | 고쳐짐 | 셸과 홈이 같은 함수 `activeNavigationRoutes`를 쓴다(`navigation-policy.ts:14-21`, `app-shell.tsx:196`, `home-page.tsx:25-29`). 렌더 때 읽는다. 테스트가 기능을 끈 홈의 시작 링크에 그 기능 라우트가 없고, 셸 탐색 앞 3개와 같은지 본다(`example-pages.test.tsx:60`, FE-GATE-005 통과). 1103/09-04의 보존 조건(홈이 기능 라우트를 이름으로 부르지 않음)은 그대로다. 되돌리는 변이(08-R4, 홈만 기능 켜짐을 보지 않음)는 그 행이 `expected true to be false`로 실패했다(1 failed / 3 passed). 초기 파일 +1은 3.0절 | +| 1105/08-04 | 다른 저장이 진행 중일 때 저장 버튼이 켜져 있지만 눌러도 반응이 없다 | 고쳐짐 | `otherSaveRunning`(코디네이터는 `mutation-pending`, 이 폼은 저장 중 아님)일 때 저장 버튼을 끄고(`reference-resource-form-page.tsx:60-61`, `:134`) feedback에 "변경 사항을 저장하고 있습니다."를 그린다(`:188-191`). 생성기 템플릿도 같다(`create-feature-write-slice.ts:669`, `:708`, `:737-738`). 이 폼 자신의 저장 중에는 끄지 않는다(1103/08-02 보존). 완료 기준(다시 마운트한 폼이 진행 문구를 보이거나 버튼이 꺼짐)을 `reference-page.test.tsx:592`가 본다(FE-GATE-005 통과). 생성기는 문자열만 본다(`create-feature.test.ts`). 되돌리는 변이(08-R5, `\|\| otherSaveRunning` 제거)는 그 행이 `toBeDisabled`로 실패했다(1 failed / 26 passed). 그 저장이 끝난 **뒤** 아무것도 보이지 않는 것은 새 발견 08-01이다 | +| 1103/03-01 (= 1103/08-01, 폼 쪽) | 짝 백엔드의 업무 규칙 거절 뒤 거절 이유가 안 보이고 값을 고쳐 다시 저장할 수 없다 | **일부** | **고쳐진 것.** 선언한 code의 다시 저장은 지난 라운드에 고쳐졌다. 이번에 `refusalMessages`가 생겼다. code별로 기능 catalog 키와 필드를 적으면, 적용 안 됨(`NOT_APPLIED`)으로 끝난 실패를 필드 오류(필드가 없으면 오류 요약)와 `validation-error`로 보인다(`use-app-form.ts:50-59`, `:251-271`, `:477-487`). 키 타입 `ParameterlessMessageKey`는 설치된 기능 catalog를 포함한다(`catalog.ts:1`, `message-contract.ts:47-49`). 재로그인이 먼저이고, 자기 키만 읽는다(`Object.hasOwn`). 테스트 셋(`form-foundation.test.tsx:1008`, `:1046`, `:1079`) FE-GATE-005 통과. 매뉴얼 02 4절(`02-decision-tables.md:187`). 끄는 변이(08-R6)는 `:1008`, `:1046` 두 행이 실패했고 `:1079`는 통과했다(2 failed / 32 passed). **남은 것 (1) 선언하지 않은 code.** 1103 완료 기준은 "쓰기 전으로 확인되지 않은 code는 결과 불명이지만 거절 code의 문구가 보이고, 저장되지 않은 요청을 '저장했습니다'로 바꾸는 버튼이 없다"였다. 지금은 결과 불명이면 기능 문구를 보지 않는다(`refusalFor`의 `NOT_APPLIED` 조건, `:482`). 화면은 "변경 결과를 확인할 수 없습니다." + "변경됨으로 확인"이다. 확인하면 `settleApplied`가 "저장했습니다."로 바꾼다(`reference-resource-form-page.tsx:162-166`, `:184-185`). 테스트도 이 동작을 고정한다(`form-foundation.test.tsx:1079`). 커밋 `12d97d7` 본문은 이것을 "완료 기준의 설계"라고 적었지만 1103 완료 기준 문장과 다르다. **(2) KEYED 재전송.** `canResend`는 응답 원인을 보지 않는다(`application-query.ts:858-867`). 백엔드 표 주석은 `IDEMPOTENCY_RECOVERY_REQUIRED`를 "스스로 다시 보내지 않는다, 사용자가 데이터를 확인한다"로 적는다(`backend-envelope.ts:271-276`). README §16.5의 결정 대기 항목이다. **(3) 문서.** VD-04 결정 5는 "409 conflict는 validation으로 바꾸지 않는다"다(`VD-04-native-form-facade.md:26`). `refusalMessages`는 선언한 409(kind `CONFLICT`)를 `validation-error`로 바꾼다(`form-foundation.test.tsx:1046`이 409 행). 지난 라운드의 "문서끼리 갈림"이 이제 코드와 결정 기록의 어긋남이다. VD-04는 `8a44226..bbde570`에서 바뀌지 않았다. 남은 부분의 심각도는 지난 라운드대로 Medium·P2다((1)이 저장되지 않은 입력을 "저장했습니다."로 보이게 할 수 있다). 판정 규칙(어떤 code가 결과 불명인가)은 영역 03 소관이다 | +| 0929/03-03 (화면 쪽, 판정은 영역 03) | 결과 불명 화면의 재전송이 키 없는 쓰기에도 열린다 | 고쳐짐(유지) | 화면은 이제 코디네이터가 `true`라고 할 때만 재전송을 그린다(`async-surface.tsx:229`, 지난 라운드는 `!== false`). 손으로 만든 상태에는 재전송이 없다(`async-surface.test.tsx:130`). 훅도 키 없는 같은 입력의 재제출을 보내지 않는다(`application-query.ts:569-583`, `application-mutation-admission.test.tsx:563`). KEYED 재전송은 그대로 보인다(FE-GATE-008 `reference-save.spec.ts:216` 3엔진, 같은 키) | +| 1103/08-02~08-05 | 저장 뒤 포커스, 문구 표 `Object.prototype`, 라우트 모양 키, 422 불일치 | 고쳐짐(재발 없음) | 08-02: `use-app-form.ts:112-116`, `:285-321`, `page-templates.tsx:73-82`, FE-GATE-008 "keeps keyboard focus in the failure status"·"…in the unknown-result status" 3엔진 통과. 08-03: `form-contracts.ts:77` `Object.hasOwn`. 08-04: `deployable-app-module.ts:120-121`. 08-05: `backend-envelope.ts:219-235`. `form-contracts.ts`·`deployable-app-module.ts`·`page-templates.tsx`는 `8a44226..bbde570`에서 바뀌지 않았다. `backend-envelope.ts`는 03-01·03-02 줄만, `use-app-form.ts`는 1105/08-01과 `refusalMessages` 코드만 더해졌다 | +| 0929/08-01 | 제품이 지원 locale을 선언할 곳이 없다 | 남음 | `message-contract.ts:8-13` 고정 목록, `app-shell.tsx:85-86` 선택지에 `en-XA`·`ar-EG`. 이 기간에 바뀌지 않았다. README §16.6 목록에 없다 | +| 0929/08-08 | 로그인 복귀 주소가 라우터 기준 경로다 | 남음 | `session-provider.tsx:99` `beginSignIn(pathname + search + hash)`, `use-reference-failure-action.ts:27`. basename은 `app-router.tsx:739`. `beginSignIn(returnTo?)`(`auth-session-port.ts:38`)은 기준을 적지 않는다. README §16.6 목록에 없다 | +| 0929/08-06, 0929/08-07 | 라우트 제목 세 곳, 제품 폰트 자리 | 판정 안 함 | 지난 라운드와 같이 렌즈 밖이다. 08-06은 1103/16-06(결정 대기, 영역 16)과 겹친다 | +| 1103 3.6절 관찰 셋 | 지원 참조가 재전송마다 바뀜, `role="status"` 안의 버튼, 레이아웃 `
` 미검사 | 그대로(발견 아님) | `use-app-form.ts:453-456`, `async-surface.tsx:197-239`, `layout-landmarks.test.tsx`에 `tabIndex` 단언 0건 | + +### 2.1 수정이 검사를 약하게 했는가 + +`git diff 8a44226..bbde570`로 이 영역에 닿은 수정 커밋(`4f3c10b`, `90c489c`, `f849d78`, `f2b8ba7`, `12d97d7`, `683ccfb`, `138c195`, `e02f252`, `48c1ab7`)과 대상 테스트의 삭제 줄(`^-`)을 모두 봤다. **약해진 검사는 없다.** + +| 바뀐 검사 | 판단 | +|---|---| +| `reference-page.test.tsx`, `reference-save.spec.ts`, `create-feature.test.ts`, `starter-pages`, `product-feature-switch`, `navigation-policy.test.ts` | 더하기만 했다(삭제 줄 0) | +| `form-foundation.test.tsx` 선언 목록에 `POSTER_ALREADY_EXISTS`를 더함(`:117`) | 이 목록을 쓰는 기존 행 중 이 code를 쓰는 것은 없다. 선언하지 않은 code 행(`:1079` 등)은 선언 없는 operation을 쓴다. 약해지지 않았다. 삭제 줄 `operationId: "FORM_CREATE_ENTITY"`는 `48c1ab7`(operation ID 타입 검사)의 이름 바꿈이다 | +| `async-surface.test.tsx`의 재전송 행에 `isUnknownEffectResendable: true`를 더함 | 화면 조건이 `!== false` → `=== true`로 좁아져서 필요해졌다. 반대 경우는 새 행(`:130`)이 본다. 넓어졌다 | +| `starter-platform-overview-page.test.tsx` 실패 상태 단언: 화면 전체 문구 → "빌드" 칸의 "확인하지 못했습니다." | 같은 강도다. 대기 문구가 없다는 단언도 남았다. 문구 자체에 대한 관찰은 3.5절 | +| `example-pages.test.tsx` import 줄 | `within`을 더한 것뿐이다 | +| 시각 골든 5장 다시 찍음(`e02f252`) | 의도한 폭 변경(내용 1040 → 1025 px) 때문이다. 약해진 것은 아니다. 다만 새 compact 골든은 가림막이 덮지 않는 띠를 정답으로 고정했다(08-03) | + +## 3. 이번 발견 (36.3) + +**새 발견 3건.** 심각도: Low 3(Critical·High·Medium 0). 우선순위: P3 3. 성격: 확인된 결함 3. 08-01은 코드 + jsdom probe(08-R1), 08-02는 템플릿 코드 + 라우터 동작 probe(08-R7), 08-03은 게이트 산출(골든) + 스크롤바를 보이게 띄운 Chromium probe(08-R2)로 확인했다. + +공통: 담당·기한·상태는 `미정 · 미정 · 신규`, 재검증 결과는 `없음(신규)`이다. + +### 3.0 오케스트레이터가 물은 화면 쪽 두 가지 + +**(가) 08-03 수정이 더한 `navigation-policy` 청크.** + +- 무엇인가. `activeNavigationRoutes`(`navigation-policy.ts:14-21`)를 boot 쪽(`app-shell.tsx:196`)과 홈 라우트 청크(`home-page.tsx:25`)가 함께 import한다. 그래서 Rollup이 그 모듈을 공유 청크로 뗐다. 크기는 0.56 kB, gzip 0.37 kB다(`r5/snap/build.txt`). 내용은 `installed-feature-contracts` 청크를 import하는 함수 세 개다. +- 언제 받는가. `index.html`은 entry `index-*.js`와 `preload-helper`만 부른다. boot는 entry의 dynamic import이고, manifest에서 boot의 정적 import 목록에 이 청크가 있다(`base/dist/.vite/manifest.json`의 `src/bootstrap/boot.tsx` → `_navigation-policy-BlaVRSY7.js`, 의존 23개 중 하나). Vite preload helper는 dynamic import의 의존을 한 번에 병렬로 받는다. 그래서 이 파일은 boot의 다른 의존과 같은 묶음에서 받는다. 홈 청크가 이 파일을 다시 import할 때는 이미 받아 둔 상태다. +- 사용자에게 보이는 효과. 새 요청 단계(waterfall)는 없다. 같은 묶음에 0.37 kB 요청 하나가 늘었다. HTTP/2 정적 호스팅에서 체감할 크기가 아니다. lab(`r5/snap/lab.txt`)은 `bbde570`에서 PASS이고 LCP 2032 ms다. 이 파일 하나의 몫은 따로 재지 않았다(5절). +- 판정. 그 자체로 결함이 아니다. 셸과 홈이 한 함수를 쓰게 한 것이 08-03 수정의 핵심이고, 공유 청크는 그 결과다. 남는 것은 바이트 비용(+293 B, README §16.2 D7)이다. 그것은 영역 15가 예산으로 본다. + +**(나) 15-05 `scrollbar-gutter: stable`(`base.css:6-11`).** + +- 빈 15 px 띠 자체. 이 띠는 root 배경(`base.css:4` `var(--color-surface)`)으로 칠해진다. 그래서 대부분의 화면에서 오른쪽 여백처럼 읽힌다. 내용은 7.5 px 왼쪽으로 치우친다. 첫 화면에서 header 오른쪽이 15 px 밀리던 것(1105/15-05)을 없애는 대가로는 받아들일 만하다. overlay 스크롤바(휴대폰, macOS 기본)에서는 띠가 없다. +- 다만 앱이 그리는 것 중 이 띠를 칠하는 것이 없다. 가장 눈에 띄는 것은 모달 가림막이다. 새 compact 골든(`app-shell-compact-pseudo-drawer-chromium-visual-linux.png`, 390 × 1377)에서 drawer가 열린 위쪽 844 px의 가림막은 x 375 px에서 끝난다. 375~390 px는 덮이지 않은 밝은 세로 띠다. 부모 커밋의 골든(`e02f252^`, 390 × 1297)은 390 px까지 덮었다. 넓은 골든(`app-shell-wide-light…png`, 1440 × 900)에서는 header의 흰 띠와 그림자가 약 1425 px에서 끝나고, 그 오른쪽은 회색이다. 옛 골든은 1440 px까지였다. 스크롤바를 보이게 띄운 Chromium에서도 같다. 스크롤되지 않는 홈의 header 끝이 1425 px, 404 화면(390 px)은 375 px였다(08-R2). 이것이 새 발견 08-03이다. + +### 08-01 다시 마운트한 참조 폼은 자기가 시작하지 않은 저장이 끝난 것을 보이지 않는다. "변경됨으로 확인"을 눌러도 결과 문구가 없고 포커스가 `body`로 간다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(코드 + jsdom 실행 08-R1) | +| 관련 관점 | 28, 24, 1, 6, 10, 22 | +| 근거 | 1105/08-04 수정 뒤 템플릿은 "저장 중에 화면을 떠났다가 같은 세션에서 돌아온 폼"을 지원 경로로 다룬다(`reference-resource-form-page.tsx:56-61` 주석, 테스트 `reference-page.test.tsx:592`). 저장 결과는 폼 인스턴스가 들고 있다(`use-app-form.ts:108-111`의 `result`·`unknownSubmissionRef`). 다시 마운트한 폼에는 둘 다 없다. 경로 둘이 비어 있다. **(1) 그 저장이 결과 불명으로 끝나고 사용자가 확인한다.** 다시 마운트한 폼에도 코디네이터의 결과 불명 화면과 "변경됨으로 확인"이 보인다(`:157-170`). 누르면 `reconcileUnknownEffect(...).then(form.settleApplied)`다(`:162-166`). `settleApplied`는 제출한 값이 없으면 아무것도 하지 않는다(`use-app-form.ts:231-235`). 같은 훅의 재전송은 다시 마운트를 따로 처리한다("After a remount the form no longer holds the submitted values", `:407-408`). 확인은 그렇지 않다. 그래서 결과가 `idle`로 남고 feedback은 `null`이다(`reference-resource-form-page.tsx:147-193`). 확인하는 동안(`RECONCILING`)에는 1105/08-04의 가지가 "변경 사항을 저장하고 있습니다."를 보인다(`:188-191`). 확인 중인데 저장 중이라고 말한다. 눌렀던 버튼이 빠지므로 포커스는 `body`로 간다. 1105/08-01의 포커스 복구는 결과가 `success`일 때만 걸린다(`use-app-form.ts:127-130`). "목록 새로 보기" 링크도 함께 사라진다(`:171-182`). **(2) 그 저장이 성공하거나 적용 안 됨으로 끝난다.** 코디네이터 표시가 `mutation-pending` → 없음으로 바뀌면 진행 문구만 사라진다. 다시 마운트한 폼의 결과는 `idle`이라 어느 가지에도 들지 않는다(`:184-193`). 400·429 같은 실패도 같다. 그 실패를 받은 폼 인스턴스는 이미 없다. 테스트 `reference-page.test.tsx:592`는 진행 문구가 사라지는 것까지 단언하고, 그 뒤 아무것도 보이지 않는 것은 보지 않는다. 생성기 템플릿은 (1)에서 목록으로 이동하므로 해당 없다(`create-feature-write-slice.ts:724-731`). (2)는 08-02와 얽힌다. **실행(08-R1, 실제 `AppRouter`·코디네이터, `createResource`만 주입).** 저장을 걸어 둔 채 "목록으로 돌아가기" → 다시 작성 화면. A(그 저장이 결과 불명): 다시 마운트한 폼에 "변경 결과를 확인할 수 없습니다." + "변경됨으로 확인" + "같은 요청으로 다시 보내기" + "목록을 새로 불러와 확인"이 보이고 저장은 꺼져 있다. 키보드로 확인한 뒤에는 feedback 자리가 없고(`(no feedback area)`), "저장했습니다."가 없고, 포커스는 `BODY`다. 같은 이름을 다시 입력해 저장하면 `createResource`가 두 번째로 불린다(`{"name":"First item"}` × 2). B(그 저장이 성공): 진행 중에는 "변경 사항을 저장하고 있습니다."와 꺼진 저장 버튼, 끝난 뒤에는 feedback 자리가 없고 "저장했습니다."도 없다 | +| 발생 조건 | 참조 폼에서 저장을 누르고 끝나기 전에 떠났다가(저장 중에는 이탈 확인이 꺼짐, `:62`) 같은 세션에서 돌아온다. (1)은 그 저장이 결과 불명이고 사용자가 확인할 때, (2)는 그 저장이 돌아온 화면에서 끝날 때 | +| 영향 | (1) 사용자는 확인이 받아들여졌는지 화면에서 알 수 없다. 키보드 사용자는 포커스를 잃는다. (2) 저장이 됐는지, 실패했는지 알 수 없다. 사용자가 같은 항목을 다시 입력해 저장하면 새 키의 새 생성이 나간다. 앞의 저장이 됐다면 중복이다. 목록에서 보이고 지울 수 있다 | +| 심각도·우선순위 | Low · P3 — 드문 경로다. 데이터는 잃지 않고, 중복은 사용자가 다시 입력할 때만 생긴다 | +| 확실성과 남은 가정 | jsdom 실행으로 확인했다(E2, 08-R1 2 passed). 브라우저 3엔진에서는 돌리지 않았다. 실패(400·429)로 끝나는 (2)는 코드 읽기다 | +| 결정의 근거 | 적용 제외 — 같은 훅의 재전송에 있는 다시 마운트 처리가 확인 쪽에 빠진 누락과, 결과를 폼 인스턴스만 들고 있는 데서 온 빈칸이다 | +| 이해 비용 | 페이지 작성자는 폼 결과(`useAppForm`)와 코디네이터 상태(`useApplicationMutation`)를 손으로 합쳐 feedback 가지를 만든다. 다시 마운트한 경우는 두 쪽 어느 문서에도 없다 | +| 최소 개선 방향 | (1) `settleApplied`가 제출한 값이 없을 때도 결과를 `success`로 둔다(값은 지금 값). 재전송과 같게 한다. 그러면 1105/08-01의 포커스 복구도 걸린다. (2) 코디네이터가 마지막으로 끝난 시도의 결과(성공·적용 안 됨)를 채널에 남기고, 다시 마운트한 폼이 그것을 보인다. 또는 진행 문구 자리에 "목록에서 저장 여부 확인" 링크를 둔다 | +| 대안 비교 | (2)는 선택이 있다. 채널에 결과를 남기면 정확하지만 코디네이터 계약이 넓어진다. 링크만 두면 작지만 결과를 말하지 않는다. 지난 라운드 3.5절의 (B)(`useAppForm`이 코디네이터 상태를 받아 결과를 하나로 낸다)가 두 경로를 함께 줄인다 | +| 단순화의 보존 조건 | 처음 저장이 그냥 성공할 때 포커스를 옮기지 않는다. 이 폼 자신의 저장 중에는 저장 버튼을 끄지 않는다(1103/08-02). 키 없는 결과 불명에 재전송 없음(0929/03-03) | +| 비용·부작용 | (1)은 몇 줄과 테스트 한 행. (2)는 코디네이터 상태 칸 하나와 페이지 가지 하나 | +| 재검토 조건 | 코디네이터가 시도 결과를 보존하는 계약을 갖게 될 때 | +| 완료 기준 | 08-R1의 A에서 확인 뒤 "저장했습니다."가 보이고 포커스가 feedback 자리 안이다. B에서 그 저장의 결과(또는 목록 확인 안내)가 보인다 | +| 검증 방법 | 08-R1 probe의 두 행을 `reference-page.test.tsx`에 넣는다 | + +### 08-02 생성 기능 작성 폼은 사용자가 저장 중에 화면을 떠나도, 저장이 끝나면 앱을 그 항목의 상세 화면으로 옮긴다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(템플릿 코드 + 라우터 동작 실행 08-R7) | +| 관련 관점 | 1, 23, 28, 10, 20 | +| 근거 | 생성기 템플릿의 작성 폼은 `submit`이 저장을 기다린 뒤 `openSaved(outcome)`을 부른다(`create-feature-write-slice.ts:649-655`). `openSaved`는 성공이면 `navigate(상세)`다(`:636-647`). 그 사이에 화면이 남아 있는지 보지 않는다. 저장 중에는 이탈 확인이 꺼져 있어(`useDirtyNavigationGuard(form.dirty && !form.pending)`, `:670`) 사용자는 저장 중에 다른 화면으로 갈 수 있다. 1105/08-04 수정은 그렇게 떠났다가 돌아온 폼을 지원 경로로 다룬다(`:666-669` 주석). 참조 폼은 저장 성공 때 이동하지 않고 "저장했습니다."를 보인다(`reference-resource-form-page.tsx:184-185`). 그래서 이 문제는 생성기에만 있다. 생성 기능 테스트는 저장 중 이탈을 돌리지 않는다(`:749-930`의 행 목록). 이 앱은 데이터 라우터(`createBrowserRouter`, `app-router.tsx:749`)다. **실행(08-R7).** 같은 순서(저장을 기다린 뒤 `navigate(상세)`)의 최소 페이지를 이 repo의 react-router 7.18.1 데이터 라우터(`createMemoryRouter`)에 올렸다. 저장을 건 뒤 다른 라우트로 가고 저장을 끝내면, 위치가 `/items/created`가 된다(`08-R7 after=/items/created`). 언마운트된 화면의 `navigate`도 앱을 옮긴다 | +| 발생 조건 | 생성 기능에서 저장을 누르고 끝나기 전에 목록이나 다른 기능 화면으로 간다. 저장이 성공한다. 다시 돌아온 작성 폼(1105/08-04 경로)에 입력이 있으면 `useBlocker`(`use-dirty-navigation-guard.tsx:9`)가 이 이동을 막고 이탈 확인 창을 띄운다 | +| 영향 | 사용자가 요청하지 않은 화면 이동이 생긴다. 다른 기능에서 작업 중이면 그 화면을 떠난다. 다시 돌아온 작성 폼에서 입력 중이면 이유 없는 이탈 확인 창이 뜬다. 데이터는 잃지 않는다(이탈 확인이 입력을 지킨다) | +| 심각도·우선순위 | Low · P3 — 저장 중에 떠나는 드문 경로다. 이동한 화면은 방금 만든 항목이라 혼란은 짧다 | +| 확실성과 남은 가정 | 템플릿 문자열(E1)과 라우터 동작 실행(E2, 08-R7)으로 확인했다. 생성한 기능 자체로는 돌리지 않았다. `createBrowserRouter`와 `createMemoryRouter`는 같은 `useNavigate` 경로를 쓴다고 보았다(추론). 다시 돌아온 작성 폼에서 이탈 확인 창이 뜨는 것은 코드 읽기다. 파일이 `scripts/`라 영역 16과 겹칠 수 있다. 합칠 때 하나로 센다 | +| 결정의 근거 | 적용 제외 — 저장 뒤 이동이 "사용자가 아직 그 화면에 있다"는 전제를 확인하지 않은 누락이다 | +| 이해 비용 | 필요한 범위만 | +| 최소 개선 방향 | 이동 전에 이 화면이 아직 마운트되어 있는지(또는 현재 위치가 작성 라우트인지) 본다. 떠난 뒤 끝난 저장은 08-01 (2)처럼 결과를 남기는 쪽으로 보인다 | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 작성 폼에 남아 있는 사용자는 저장 뒤 상세로 간다. 확인 뒤 목록으로 간다(1105/08-02) | +| 비용·부작용 | 템플릿 몇 줄, 생성 기능 테스트 한 행 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | 생성 기능 테스트에서 저장 중에 목록으로 간 뒤 저장이 끝나도 위치가 목록이다 | +| 검증 방법 | `renderCreatePageTest`(`create-feature-write-slice.ts:749-`)에 한 행. `test:feature-scaffold`·`test:sample-removal`이 생성 결과로 돈다 | + +### 08-03 `scrollbar-gutter: stable`이 잡은 오른쪽 15 px 띠를 앱이 칠하지 않는다. 열린 drawer·모달의 가림막이 그 띠를 덮지 않고, 짧은 화면에서 header 띠가 15 px 앞에서 끝난다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(게이트 산출의 골든 + 스크롤바를 보이게 띄운 Chromium 실험 08-R2) | +| 관련 관점 | 1, 23, 10, 5 | +| 근거 | `:root`에 `scrollbar-gutter: stable`이 있다(`base.css:6-11`, 1105/15-05 수정 `e02f252`). 문서가 스크롤되지 않아도 오른쪽에 스크롤바 폭(15 px)이 늘 잡힌다. 그 자리는 root 배경(`base.css:4`)으로만 칠해진다. 고정 위치 요소와 top layer의 `::backdrop`은 viewport 기준이라 그 띠 안쪽에서 끝난다. drawer는 `showModal()` dialog이고(`dialog.tsx:61`, `drawer.tsx:22-33`) 가림막은 `.ui-dialog::backdrop`이다(`primitives.css:416-419`). header는 본문 안의 sticky 띠다(`shell.css:45-57`). **골든.** 새 compact 골든(390 px 창, drawer 열림)에서 가림막은 x 375 px에서 끝나고 375~390 px에 덮이지 않은 밝은 띠가 위에서 844 px까지 남는다. 부모 커밋 골든은 끝까지 덮었다. 넓은 골든(1440 px)에서는 header의 흰 띠가 약 1425 px에서 끝난다(3.0절 (나)). 이 골든을 찍는 Chromium은 `--hide-scrollbars`인데도 gutter를 잡는다(`e02f252` 본문). 그래서 골든 속 띠는 늘 비어 있다. **실험(08-R2, `--hide-scrollbars`를 뺀 Chromium).** 홈 1440 × 900: 스크롤되지 않고(`scrolls:false`) header 오른쪽 끝이 1425 px다(창 1440 px). 404 화면 390 × 844 + drawer: 스크롤되지 않고 header 끝이 375 px다. 띠 안(x 385)의 hit test는 dialog가 아니다(`null`). 홈 390 × 844 + drawer: 스크롤되므로 스크롤바가 띠를 채운다(`clientWidth` 375). x 370은 dialog, x 385는 스크롤바(`null`)다. 커밋 본문은 "열린 drawer의 가림막은 gutter를 덮지 않는다"를 위험으로 적었다. 제품이 읽는 문서(CHANGELOG `:81`, `performance-evidence.md:125-129`)에는 내용 폭 15 px만 있고 가림막·header 이야기는 없다 | +| 발생 조건 | 일반(overlay가 아닌) 스크롤바 브라우저(Windows·Linux의 Chrome·Edge 기본, macOS에서 마우스 연결 시)에서 문서가 창보다 짧을 때. 그때 띠는 비어 있다. 문서가 스크롤되면 그 자리에 스크롤바가 그려지고 가림막이 스크롤바를 덮지 않는 것은 전과 같다. 휴대폰(overlay)은 해당 없다. 오른쪽에 붙는 drawer(`ui-drawer--end`, `primitives.css:434-436`, RTL의 start 포함)는 창 끝과 drawer 사이에 15 px 틈이 생길 수 있다(미확인) | +| 영향 | 모달·drawer가 열렸을 때 오른쪽 끝에 흐리게 덮이지 않은 밝은 띠가 남는다. header 띠가 창 끝까지 가지 않는다. 기능 영향은 없다. 시각 계약(골든)이 이 모습을 정답으로 고정해서 다음 변경도 이 띠를 기준으로 잰다. compact 골든은 실제 휴대폰보다 15 px 좁은 배치를 그린다(`e02f252` 본문도 적음) | +| 심각도·우선순위 | Low · P3 — 보기 문제이고 짧은 화면·일반 스크롤바에서만 보인다 | +| 확실성과 남은 가정 | 빈 띠와 header가 앞에서 끝나는 것은 스크롤바를 보이게 띄운 Chromium 실험으로 확인했다(E3, 08-R2). 가림막이 띠를 칠하지 않는 것은 골든 이미지로 확인했다(E2, FE-GATE-008 시각 6건이 새 골든으로 통과). 08-R2의 hit test(`null`)는 이것과 맞지만, 띠 자리가 원래 hit test를 받지 않을 수 있어 칠함의 증거로는 쓰지 않는다. probe 스크린샷은 받지 못했다. Firefox·WebKit은 보지 않았다 | +| 결정의 근거 | 15-05의 선택(첫 화면 15 px shift 대신 상시 gutter)은 커밋 본문에 근거가 있다. 그 선택 자체는 유지할 만하다(3.0절). 이 항목은 그 선택이 만든 빈칸을 앱이 메우지 않은 것이다. 확인된 사실: 골든 두 장의 차이, CSS 위치. 리뷰어 추론: 일반 스크롤바 브라우저에서 골든과 같은 모습 | +| 이해 비용 | 제품 작성자는 CHANGELOG만 보면 폭 15 px 변화만 안다. 모달 가림막이 띠를 덮지 않는다는 것은 커밋 본문에만 있다 | +| 최소 개선 방향 | 가림막이 창 전체를 덮게 한다(예: `.ui-dialog::backdrop`의 폭을 창 폭으로). 일반 스크롤바 Chromium에서 확인한다. header 띠는 받아들이고 디자인 문서에 적거나, root 배경을 header와 맞추는 것을 검토한다 | +| 대안 비교 | (가) 지금대로 두고 문서에 적는다: 비용 0, 띠는 남는다. (나) 가림막만 넓힌다: 작고 가장 눈에 띄는 것을 없앤다. 스크롤되는 화면에서 가림막이 스크롤바 위로 그려지는지는 확인이 필요하다. (다) `scrollbar-gutter`를 거두고 첫 화면 shift를 다른 방법(로딩 화면 높이)으로 없앤다: 15-05를 다시 여는 큰 변경이다. (라) `html { overflow-y: scroll }`: 커밋이 버린 대안. 빈 스크롤바 트랙이 늘 그려지고 가림막 문제는 같다 | +| 단순화의 보존 조건 | 첫 화면 header shift 0(lab `/` CLS 0, `lab.txt`). `:root` `scrollbar-gutter` 단위 테스트(`lab-performance.test.ts:132`) | +| 비용·부작용 | (나)는 CSS 몇 줄과 골든 1장 다시 찍기 | +| 재검토 조건 | 브라우저 기본이 overlay 스크롤바로 바뀌거나, 시각 게이트가 스크롤바를 보이게 찍게 될 때 | +| 완료 기준 | drawer를 연 compact 골든에서 가림막이 390 px까지 덮는다. 스크롤바를 보이게 띄운 Chromium의 스크롤되지 않는 화면에서도 같다 | +| 검증 방법 | 시각 골든 다시 찍기. 08-R2 probe를 스크롤바가 보이는 시각 테스트(스크린샷 비교)로 남긴다. hit test는 띠 자리에서 늘 `null`일 수 있어 기준으로 쓰지 않는다 | + +### 3.5 발견으로 올리지 않은 관찰 + +- **플랫폼 구성 화면의 실패 문구(15-01 수정의 화면 쪽).** 릴리스 정보를 읽지 못하면 전에는 "상태: 런타임 정보를 확인하지 못했습니다." 한 칸이었다. 지금은 "빌드: 확인하지 못했습니다."와 "릴리스: —", "설정 스키마: — / —", "계약 집합 다이제스트: — / —"다(`platform-overview-page.tsx:69-78`, `:475-482`). 칸 수를 맞춰 자리를 지키려는 수정(15-01)이다. 읽는 사람은 "빌드만 확인하지 못했다"로 읽을 수 있다. 예제 화면이고 정보를 숨기지 않아 결함으로 보지 않았다. +- **`refusalMessages`에 적고 `refusedBeforeWrite`에 적지 않은 code.** 그 문구는 보이지 않고 결과 불명이 된다(`use-app-form.ts:482`, 테스트 `form-foundation.test.tsx:1079`가 이것을 고정). 안전한 쪽으로 닫힌다. 둘을 맞추는 검사는 없다. 매뉴얼은 둘을 같은 절에 적었다(`02-decision-tables.md:180-187`). +- **오류 요약만으로 보이는 거절.** `refusalMessages`에 필드가 없으면 오류 요약(`role="alert"`)에만 보이고 포커스는 저장 버튼에 남는다(`use-app-form.ts:262-269`). 클라이언트 검증의 폼 오류와 같은 동작이다. +- **띠가 비어 있을 때 `documentElement.clientWidth`.** 08-R2에서 스크롤되지 않는 화면은 `clientWidth`가 창 폭(1440, 390)이었다. 실제 배치 폭은 1425, 375다(header 끝). 스크롤되는 화면은 375였다. `src/`에 `clientWidth`·`innerWidth`를 쓰는 코드는 없어 지금은 영향이 없다(`git grep` 0건). 이 때문에 08-R2의 "띠 왼쪽" hit test 지점이 띠 안에 떨어져 probe 3건 중 2건이 가설 단언에서 실패했다(6절). +- **포커스를 받는 feedback 자리에 역할·이름이 없다**(`page-templates.tsx:73-82`). 1105/08-01 수정으로 이 자리가 포커스를 받는 경우가 늘었다. 지난 라운드 관찰 그대로, 미검증(5절). +- **반복 원인.** 이번 08-01·08-02와 지난 라운드 08-01·08-02·08-04는 같은 자리에서 났다. 저장 결과는 폼 인스턴스(`useAppForm`)가 들고, 진행·결과 불명은 코디네이터가 든다. 페이지가 둘을 손으로 합치고, 참조 폼과 생성기가 그 합치기를 따로 복사한다. 이번 수정 넷은 각 가지를 메웠지만 이 구조는 그대로다(`12d97d7` 본문도 (B)를 미뤘다고 적음). + +## 4. 28개 관점 판정 (36.2) + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역. 굵은 번호가 깊게 본 관점이다. + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +|---|---|---|---|---|---| +| **1** | 코드 성숙도 | 적용 | M3 / M3 | E2 | P — 1105 08-01~08-04 고쳐짐(완료 기준, 게이트 통과). 새로: 다시 마운트한 폼의 결과 표시 빈칸(08-01), 떠난 뒤의 상세 이동(08-02), gutter 띠(08-03) | +| 2 | 구조적 성숙도 | 적용 | M3 / M3 | E2 | O — FE-GATE-010 통과. 셸과 홈의 "켜진 탐색 라우트"가 한 함수다(`navigation-policy.ts:14-21`). presentation이 HTTP를 직접 모른다 | +| 3 | 변경 용이성 | 적용 | M3 / M1 | E1 | P — locale 목록이 셸에 박혀 있다(0929/08-01 남음) | +| 4 | 인지 부하 | 적용 | — | E1 | P — 거절 뒤 화면을 알려면 `refusedBeforeWrite` → status별 kind → `refusalMessages` → 폼 분기 → 페이지 feedback 가지를 읽는다. 매뉴얼 02 4절이 이제 `refusalMessages`까지 적는다(`:187`). 다시 마운트한 폼의 경로는 어디에도 없다(08-01) | +| 5 | 위험 가시성 | 적용 | M2 / M1 | E1 | P — gutter가 가림막을 덮지 않는다는 위험이 커밋 본문에만 있다(08-03). 선언하지 않은 code가 "저장했습니다."가 될 수 있다는 것은 매뉴얼에 있다(`02-decision-tables.md:180`) | +| **6** | 실패 성숙도 | 적용 | M3 / M3 | E2 | P — 선언한 거절은 기능 문구로 보이고 다시 저장된다(`form-foundation.test.tsx:1008`). 선언하지 않은 code와 `RECOVERY_REQUIRED` 뒤 재전송은 막다른 길이다(1103/03-01 남음). 떠난 사이 끝난 저장의 실패가 사라진다(08-01) | +| 7 | 운영 성숙도 | > | — | — | 영역 09·13 | +| 8 | 디버깅 가능성 | 적용 | M3 / M3 | E2 | P — 상태 실패와 결과 불명에 지원 참조가 있다. `refusalMessages`로 보인 거절은 `validation-error`라 지원 참조가 없다(`use-app-form.ts:453-456`). 고칠 수 있는 입력이라 문제로 보지 않는다 | +| 9 | 유지보수 성숙도 | 적용 | — | E1 | P — `application-query.ts` 1,026줄(지난 1,004줄), `use-app-form.ts` 516줄. LEGACY 분기 그대로 | +| **10** | 테스트 성숙도 | 적용 | M3 / M3 | E2 | P — 1105 수정 넷과 `refusalMessages`에 테스트가 붙었다. 되돌리는 변이 넷이 모두 기대한 테스트에서 기대한 이유로 실패했다(08-R3~08-R6). 다시 마운트한 폼의 끝(08-01), 저장 중 이탈(08-02)을 보는 테스트가 없다. 시각 게이트는 스크롤바를 숨긴 채 gutter 띠를 정답으로 고정했다(08-03) | +| 11 | 데이터 성숙도 | - | — | — | presentation은 저장을 소유하지 않는다 | +| 12 | 동시성 성숙도 | 적용 | M3 / M3 | E2 | O — 다른 저장이 진행 중이면 저장 버튼이 꺼지고 진행 문구가 보인다(1105/08-04). 키 없는 같은 입력 재제출은 훅이 막는다(`application-query.ts:569-583`). 중복 제출은 폼이 막는다(`use-app-form.ts:385-386`) | +| 13 | 확장성 | > | — | — | 영역 09·15·16 | +| **14** | 성능 성숙도 | 적용 | M3 / M3 | E2 | O — FE-GATE-012 PASS(204,158 / 206,848 B, 27 / 32 파일). lab PASS, `/` CLS 0(일반 스크롤바, `lab.txt`). 08-03 공유 청크는 같은 병렬 묶음이라 새 단계가 없다(3.0절). 예산 판단은 영역 15 | +| 15 | 보안 성숙도 | 적용 | M3 / M3 | E2 | P — 백엔드 message를 그리지 않는다. `refusalMessages`는 기능 catalog 키만 받고 자기 키만 읽는다(`use-app-form.ts:484`). 로그인 복귀 주소(0929/08-08) 남음 | +| 16 | 의존성 성숙도 | > | — | — | 영역 13 | +| 17 | API / Contract 성숙도 | 적용 | M3 / M2 | E1 | P — `refusalMessages`가 선언한 409를 필드 오류로 바꿔 VD-04 결정 5와 어긋난다(1103/03-01 남음 (3)) | +| 18 | 배포 성숙도 | 적용 | M3 / M2 | E1 | O — 08-03 청크는 boot 의존이라 청크 복구 경계(라우트 쪽)와 상관없이 boot와 함께 받는다. SW 캐시 대상 목록은 영역 06 | +| 19 | 설정 성숙도 | 적용 | M2 / M1 | E1 | P — 0929/08-01 남음 | +| 20 | 개발자 경험 | 적용 | — | E2 | P — 기능 거절 문구 자리가 생겼다(`refusalMessages`, 매뉴얼). 생성기 작성 폼이 저장 중 이탈을 고려하지 않는다(08-02) | +| 21 | Guardrail 성숙도 | 적용 | M3 / M3 | E2 | O — 키 없는 재전송을 화면(`=== true`)과 훅이 둘 다 막는다. `refusalMessages`는 결과 불명에 쓰이지 않는다(안전한 쪽). `refusalMessages`와 `refusedBeforeWrite`를 맞추는 검사는 없다(3.5절, 안전한 쪽으로 닫힘) | +| 22 | 추상화 성숙도 | 적용 | — | E1 | P — 저장 결과가 폼 인스턴스에만 있고 페이지가 코디네이터 상태와 손으로 합친다. 지난 라운드 08-01·08-02·08-04에 이어 이번 08-01·08-02도 같은 자리에서 났다(3.5절) | +| **23** | 일관성 | 적용 | — | E2 | P — 셸과 홈이 같은 탐색 목록을 쓴다(고쳐짐). 참조 폼은 저장 뒤 이동하지 않고 생성 폼은 떠난 뒤에도 이동한다(08-02). 재전송은 다시 마운트를 처리하고 확인은 하지 않는다(08-01) | +| **24** | 네이밍 / 의미 성숙도 | 적용 | — | E1 | P — 다시 마운트한 폼에서 확인 중에 "변경 사항을 저장하고 있습니다."(08-01). 선언하지 않은 거절이 "저장했습니다."가 될 수 있다(1103/03-01 남음). 플랫폼 구성 화면 실패가 "빌드" 칸 값으로 보인다(3.5절) | +| 25 | 조직 확장성 | 적용 | — | E1 | P — 기능 거절 문구는 이제 기능 catalog에 둔다. 필드 문구 표(`form-contracts.ts`)와 locale 목록은 여전히 템플릿 파일이다 | +| 26 | Ownership 성숙도 | 적용 | — | E1 | ? — 수동 접근성 기록 10건이 모두 `pending-manual-review`다(`artifacts/tests/a11y-manual/*.md`) | +| 27 | 삭제 가능성 | > | — | — | 영역 09·16. 홈 시작 링크 테스트는 예제 기능 테스트 폴더에 있어 기능과 함께 지워진다(`example-pages.test.tsx:57-60`) | +| **28** | 회복 가능성 | 적용 | M3 / M2 | E2 | P — 복구 버튼 뒤 포커스가 feedback 자리로 간다(3엔진). 다시 마운트한 폼의 확인은 결과도 포커스도 남기지 않는다(08-01). 선언하지 않은 거절은 거짓 성공 버튼과 끝나지 않는 재전송이 남는다(1103/03-01 남음) | + +## 5. 미검증 + +- **08-01·08-02의 브라우저 실행.** 08-01은 jsdom(08-R1), 08-02는 최소 페이지의 jsdom(08-R7)만 돌렸다. 생성한 기능으로 저장 중 이탈을 돌리지 않았다. +- **08-03의 가림막 칠함(스크롤바 보임).** 08-R2의 스크린샷을 받지 못했다. 가림막이 띠를 칠하지 않는 것은 `--hide-scrollbars` 골든으로만 봤다. 띠 자리의 hit test `null`은 칠함의 증거가 아니다. +- **실제 스크린 리더.** 포커스를 받는 feedback 자리(역할·이름 없음)와 그 안의 `role="status"`가 겹쳐 두 번 읽히는지 확인하지 않았다. 수동 접근성 기록 10건은 모두 `pending-manual-review`다. +- **일반 스크롤바의 Firefox·WebKit, RTL drawer.** 08-03은 Chromium 골든과 08-R2(Chromium)만 본다. RTL에서 오른쪽에 붙는 drawer와 창 끝 사이 틈은 확인하지 않았다. +- **생성기로 만든 기능.** 생성 명령을 직접 돌리지 않았다. FE-GATE-020 로그로 생성 테스트 통과만 읽었다. 08-02는 템플릿 문자열을 읽었다. +- **짝 백엔드.** 실제로 띄우지 않았다. 1105/08-02 뒤 목록 405(1103/03-07)는 커밋 본문의 주장이다. +- **08-03 청크의 시간 몫.** lab은 전체만 잰다. 이 파일 하나의 몫을 재지 않았다. +- **영역 밖 게이트 실패.** FE-GATE-013 rc=1(전제 조건). 이 영역 판정에 쓰지 않았다. + +## 6. 실행 기록 + +리뷰어가 직접 돌린 실행은 0건이다. 노트북에서는 읽기와 `git show`·`git diff`·`git log`·`git grep`, 그리고 상태를 바꾸지 않는 `git apply --check`(요청 패치 확인)만 했다. 부모 커밋 골든 두 장은 `git show e02f252^:<경로>`로 scratchpad에 꺼내 이미지로 읽었다. desktop에서는 `/tmp/claude-gates/` 아래 파일을 `cat`·`grep`·`ls`·`sed`로 읽었다. **규칙에서 벗어난 것 하나:** `base/dist/.vite/manifest.json`에서 `navigation-policy` 청크를 import하는 항목을 찾으려고 desktop에서 `python3 -c`로 그 JSON을 읽기 전용으로 한 번 파싱했다. 파일을 쓰거나 checkout에 닿지 않았다. + +요청 파일: `scratchpad/r5/requests/08.md`, 패치: 같은 폴더의 `08-R*.diff`. 모두 깨끗한 `bbde570`에 `git apply --check`로 붙는다. 아래는 오케스트레이터가 한 배치로 하나씩 돌린 결과다(`desktop:/tmp/claude-gates/r5/batch/out/R5-08-R*.log`, 2026-11-06 04:33~04:34, 부하 2.4~3.5, env local). 매 항목 뒤 checkout을 되돌렸고 모두 `restore=clean`이다. + +| ID | 명령 | 변이 | rc·시간 | 결과 | +|---|---|---|---|---| +| 08-R1 | `node scripts/run-vitest.ts run tests/features/reference-feature/probe-08-r5-remount.test.tsx` | probe 파일 추가 | 0 · 3초 | 2 passed. 가설대로다. A2 `{"feedback":"(no feedback area)","saved":false,"active":"BODY"}`, A3 `creates=2`, B2 `{"feedback":"(no feedback area)","saved":false}`. 관찰은 08-01 근거 칸. stderr 한 줄은 probe가 `pushState`로 돌아올 때의 react-router 경고다(repo 테스트 `reference-page.test.tsx:592`와 같은 방식) | +| 08-R2 | `corepack pnpm exec playwright test tests/e2e/probe-08-r5-gutter.spec.ts --project=chromium --reporter=list` | probe spec 추가(`--hide-scrollbars` 뺌) | 1 · 8초(빌드 제외) | 1 passed / 2 failed. 측정값: wide-home `{"innerWidth":1440,"clientWidth":1440,"scrolls":false,"headerRight":1425,"hitInGutter":null,"hitLeftOfGutter":null}`; compact-drawer-not-found `{"innerWidth":390,"clientWidth":390,"scrolls":false,"headerRight":375,"hitInGutter":null,"hitLeftOfGutter":null}`; compact-drawer-home `{"clientWidth":375,"scrolls":true,"headerRight":375,"hitInGutter":null,"hitLeftOfGutter":"DIALOG.ui-dialog"}`. 실패 둘은 probe 설계 탓이다. 띠가 비어 있으면 `clientWidth`가 창 폭이라 `clientWidth < innerWidth` 단언과 "띠 왼쪽"(x = clientWidth − 5) 지점이 틀렸다. header 끝(1425, 375)이 띠를 보여 준다. 스크린샷은 복사되지 않았다 | +| 08-R3 | `node scripts/run-vitest.ts run tests/features/reference-feature/reference-page.test.tsx` | `use-app-form.ts:128` `recovered` 항상 false | 1 · 20초 | 기대대로. 3 failed / 24 passed: "keeps focus in the feedback after '변경됨으로 확인' / '같은 요청으로 다시 보내기' / '다시 시도' from the keyboard", `expect(element).toHaveFocus()` | +| 08-R4 | `node scripts/run-vitest.ts run tests/features/platform-examples-feature/example-pages.test.tsx` | `home-page.tsx:26` 기능 켜짐을 보지 않음 | 1 · 1초 | 기대대로. 1 failed / 3 passed: "leaves this feature's screens out of the home page's starter links when it is switched off", `expected true to be false` | +| 08-R5 | `node scripts/run-vitest.ts run tests/features/reference-feature/reference-page.test.tsx` | `reference-resource-form-page.tsx:134` `\|\| otherSaveRunning` 제거 | 1 · 5초 | 기대대로. 1 failed / 26 passed: "says a save is running and keeps the save off after coming back during a save", `expect(element).toBeDisabled()` | +| 08-R6 | `node scripts/run-vitest.ts run tests/component/form-foundation.test.tsx` | `use-app-form.ts:484` 기능 문구를 찾지 않음 | 1 · 12초 | 기대대로. 2 failed / 32 passed: "shows the feature's words for a declared refusal on its field and saves again", "shows a declared refusal without a field in the error summary", `expect(element).toHaveTextContent()`(결과가 `validation-error`가 아님). "keeps an undeclared refusal unknown …"는 통과 | +| 08-R7 | `node scripts/run-vitest.ts run tests/component/probe-08-r5-navigate-after-unmount.test.tsx` | probe 파일 추가 | 0 · 1초 | 1 passed, `08-R7 after=/items/created`. 가설대로다 | + +변이 없는 대조는 게이트 출력이다: `reference-page.test.tsx`·`form-foundation.test.tsx`·`example-pages.test.tsx`는 FE-GATE-005(`FE-GATE-005.txt:409`, `:432`, `:469`) 통과. 변이 넷 모두 변이 없는 실행은 통과, 변이 실행은 기대한 테스트가 기대한 이유로 실패했다. + +## 7. 새 발견 요약 + +| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line | +|---|---|---|---|---| +| 08-01 | Low · P3 | 확인된 결함(jsdom 실행 08-R1) | 다시 마운트한 참조 폼이 자기가 시작하지 않은 저장의 끝을 보이지 않는다. "변경됨으로 확인" 뒤 결과 문구가 없고 포커스가 `body`다 | `src/presentation/forms/use-app-form.ts:231-235` vs `:402-408`; `src/features/reference-feature/presentation/reference-resource-form-page.tsx:147-193` | +| 08-02 | Low · P3 | 확인된 결함(템플릿 코드 + 라우터 동작 08-R7) | 생성 기능 작성 폼이 저장 중에 떠난 사용자를 저장이 끝나면 상세 화면으로 옮긴다 | `scripts/create-feature-write-slice.ts:636-655` | +| 08-03 | Low · P3 | 확인된 결함(골든 + 08-R2) | `scrollbar-gutter: stable`의 15 px 띠를 drawer·모달 가림막과 header가 칠하지 않는다. 새 골든이 이 띠를 고정했다 | `src/presentation/styles/theme/base.css:6-11`, `primitives.css:416-419`, `shell.css:45-57`; `tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/app-shell-compact-pseudo-drawer-chromium-visual-linux.png` | + +이월(새로 세지 않음): 1103/03-01(= 1103/08-01) 폼 쪽 일부(Medium·P2), 0929/08-01 남음, 0929/08-08 남음. diff --git a/docs/reviews/2026-11-06-maturity-review/09-app-core.md b/docs/reviews/2026-11-06-maturity-review/09-app-core.md new file mode 100644 index 00000000..690ad6e7 --- /dev/null +++ b/docs/reviews/2026-11-06-maturity-review/09-app-core.md @@ -0,0 +1,162 @@ +# 영역 09 — 애플리케이션 코어·기능·조립 + +> 검토일 2026-11-06 · 기준 `bbde570`(PR B 끝, `fix/maturity-review-2026-11-05-b`) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 경로: `src/application/`, `src/features/`, `src/bootstrap/`, `src/platform/`, `src/apps/`, `src/contexts/`. 판정에 필요한 만큼 `recipes/session-owners/`, `tests/unit/product-extension-typecheck.test.ts`, `scripts/check-registries.ts`, `src/contracts/server-state.ts`(1103/16-05), `src/adapters/query-cache/server-state-scope-runtime.ts`(1105/02-01 조립 쪽), `CHANGELOG.md` 첫 절, `docs/manual/{01,02,03,04}*.md`도 읽었다. +> 깊게 본 관점: 3, 10, 17, 20, 21, 25 +> 렌즈: 1105 수정 셋(09-01·09-02·09-03)과 1103 이월 셋(09-03·09-04·09-05)이 완료 기준까지 갔는가. 그 수정이 검사를 약하게 하거나 다른 결함을 만들었는가. 1103/16-05 BREAKING(`48c1ab7`)의 코드가 커밋 꼬리말·CHANGELOG 안내와 같은가. 1105/02-01이 바꾼 제품 scope participant 조립이 맞는가. +> 영역 판정(35.8): **조건부 사용 가능.** 지난 라운드의 이 영역 결함 셋(09-01·09-02·09-03)은 코드와 테스트로 닫혔다. 1103/16-05도 닫혔다. 조건은 셋이다. (1) 짝 백엔드 실제 연동은 아무도 확인하지 않았다. realm public client와 Redis 모드 로그인 엔드포인트는 제품 몫이다(1103/09-03 일부, 백엔드로 넘김). (2) 플랫폼 구성 화면은 끌 수 없고, 예제 기능을 빼면 브라우저 spec 8개를 고친다(1103/09-04, 결정 대기). SW 활성화 화면을 이을 제품 소유 자리가 없다(1103/09-05 일부). (3) 쿠키 세션 제품은 `onCredentialRejected` 한 줄을 직접 잇는다. 빠뜨리면 막는 검사가 없다(`CHANGELOG.md:107`). + +## 0. 결론 + +- 지난 라운드 이 영역 발견: 1105 셋은 고쳐짐 3(09-01, 09-02, 09-03). 1103 이월 셋은 일부 3(09-03, 09-04, 09-05). 이 영역에 요청된 1103/16-05는 고쳐짐. 0925 이월 둘은 일부 1(FOLLOW-UP 09-07), 남음 1(FOLLOW-UP 09-08, 허용한 대안). 재발·틀린 발견은 없다. README §16과 다르게 본 것은 없다(1103/09-03의 §16.5 "백엔드로 넘김"은 남은 것이 백엔드 쪽이라는 뜻이라 "일부"로 적었다). +- 1105/09-01: 탐침이 제품 파일을 옆 이름으로 옮기고 그 위에 덧붙인다(`tests/unit/product-extension-typecheck.test.ts:267-281`). "제품 capability를 기능에 주는 다운스트림"을 먼저 만들고 탐침을 올리는 케이스가 생겼다(`:313-323`). FE-GATE-005(CI env)에서 2 tests 통과, FE-GATE-020의 제거·생성 드릴 사본 8번에서도 통과. 수정 전처럼 제품 capability를 버리게 하면 새 케이스만 `TS2741 … 'typecheckProbeDownstreamSettings' is missing`으로 실패한다(09-R1). +- 1105/09-02: `ProductCompositionContext.notifySessionUnauthenticated()`(`src/bootstrap/product-composition-contract.ts:100`, 조립 `src/bootstrap/runtime-adapters.ts:705`)와 recipe handler(`recipes/session-owners/cookie-session-owner.ts:217-225`)가 생겼다. 매뉴얼 04 4.3 연결 그대로 쿠키 읽기·쓰기 401 뒤 세션 `unauthenticated`, 이전 scope not current를 조립 루트 테스트가 본다(`tests/recipes/session-owners-runtime.test.ts:416-436`, FE-GATE-007 통과). 조립 루트의 알림을 빈 함수로 바꾸면 그 두 테스트가 `expected 'authenticated' to be 'unauthenticated'`로 실패한다(09-R2). +- 1103/16-05: `BoundMutation.operationId`가 brand 타입 `MutationOperationId`다(`src/contracts/server-state.ts:276-278`, `:319`). 손으로 적은 문자열은 `check:types:test`에서 실패한다(`tests/unit/command-mutation-identity.test.ts:49-52`의 `@ts-expect-error`, FE-GATE-003 PASS). 코드는 커밋 꼬리말·CHANGELOG 2단계와 같다. +- 새 발견 09-01: 16-05 이행 안내가 HTTP descriptor 없는 뮤테이션(Fileserver 업로드 같은)과 테스트 fixture의 길을 말하지 않는다. 그 길은 매뉴얼이 "못 잡음"이라 적은 손 객체뿐이다. 매뉴얼 01 안에서도 두 줄이 서로 다르다(`:476` "저장할 때 실패" vs `:499` "check:types 실패"). Low·P3. +- 1105/02-01 조립: 제품 closer가 각자 order 10 participant가 되고, label이 형식에 맞지 않으면 조립이 `TypeError`로 멈춘다(`runtime-adapters.ts:713-722`). "하나가 실패해도 나머지를 닫는다"는 그대로다(`tests/unit/runtime-adapters-product-scope-participants.test.ts:139`). 발견 없음. +- 1103/09-05의 고친 부분(SW blockers·observe를 `composeProduct`로)도 변이로 지켜진다. 조립이 그 칸을 넘기지 않게 하면 연결 테스트가 실패한다(09-R3). +- 검사 약화: 영역 테스트 diff에 지운 단언·skip·시간 상한 증가는 없다(3절 머리). 약화로 센 것은 없다. +- 새 발견: Low 1. P3 1. 확인된 결함 1. + +## 1. 범위 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` | +| 커밋·작업 상태·확인 시점 | `bbde570796b0a648bae65c2c0568fca860a3ba4e`. 노트북 worktree(HEAD = 기준, 추적 파일 변경 없음, untracked `AGENTS.md`는 무시)에서 읽기만 했다. 2026-11-06 04시 | +| 목적과 지원 실행 구성 | 프론트엔드 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음. 짝 백엔드 `clean-architecture-backend-template` pin `45d2a478`(`config/contracts/backend-contract-pin.json`, `git show :`로 읽기만) | +| 필수 요구와 규모·운영 목표 | 두 템플릿을 짝으로 빨리 출시. 다운스트림(tech-log, memento)이 템플릿을 동기화한다. 정량 운영 목표 없음 | +| 읽은 코드·구성 범위 | `git log 8a44226..bbde570`의 영역 커밋 20개 본문(`397664e`, `0007699`, `bfd9d50`, `fdc1db9`, `f738348`, `48c1ab7`, `00b12b3`, `2e1acb1` 외 합친 커밋). `git diff 8a44226..bbde570`의 영역 소스 12파일 전부. `src/bootstrap/{runtime-adapters,product-composition-contract,product-composition,create-runtime-composition,optional-runtime-host,boot,render-boot-failure}.ts*`, `src/features/product-capabilities.ts`, `src/contracts/{product-contracts,server-state,diagnostics}.ts`, `src/adapters/query-cache/server-state-scope-runtime.ts`(02-01 부분), `src/presentation/adapters/query/application-query.ts:336-370`, `recipes/session-owners/cookie-session-owner.ts`, `scripts/check-registries.ts:155-168`. 테스트: `tests/unit/{product-extension-typecheck,command-mutation-identity,runtime-adapters-product-scope-participants,registry-governance}.test.ts`, `tests/recipes/{session-owners-runtime,cookie-session-owner}.test.ts`, `tests/component/runtime-composition-service-worker-product-wiring.test.ts`, `tests/helpers/mutation-operation-id.ts`. 문서: `CHANGELOG.md:14-108`, `docs/manual/01-add-a-feature.md:470-505`, `02-decision-tables.md:230-240`, `:280-400`, `03-outside-feature-folder.md:120-165`, `04-paired-backend-session.md:180-260`. 다운스트림 둘(`memento-frontend` `d3810a0`, `tech-log-frontend` `7a4e201a`, 둘 다 v0.2.0 동기화 브랜치)은 앱 id와 뮤테이션 정책 모양만 grep으로 봤다 | +| 수행한 테스트·실험 | 직접 실행 없음(노트북·desktop 모두). 증거는 desktop `bbde570` merge 단계 로그(`/tmp/claude-gates/bbde570-ci/`, CI env, 03:24~03:56): FE-GATE-003·005·006·007·020 rc=0. 공유 snapshot `r5/snap/`의 `verify-documentation.*.txt`. 변이 3개(09-R1, 09-R2, 09-R3)는 오케스트레이터 배치가 04:23에 돌렸다(`desktop:/tmp/claude-gates/r5/batch/out/R5-09-R*.log`, 6절) | +| 확인하지 못한 범위·이유 | 5절 | +| 이전 리뷰와 비교 가능한 범위 | `docs/reviews/2026-11-05-maturity-review/09-app-core.md` 2절·3절 전부, README §15의 09 행, §16.4·§16.5의 09 행과 1103/16-05. §16은 주장으로만 읽었다. 각 항목을 지난 영역 문서 3절의 완료 기준과 현재 코드·게이트 로그로 다시 판정했다(2절) | + +## 2. 지난 발견 재확인 + +| 지난 ID | 내용 | 상태 | 근거 | +|---|---|---|---| +| 1105/09-01 | 제품 확장 타입 검사 탐침이 제품 소유 파일 둘을 덮어써, 기능이 제품 capability를 쓰는 다운스트림에서 FE-GATE-005가 실패한다 | **고쳐짐** | 탐침이 `product-contracts.ts`·`product-composition.ts`를 `-product-*.ts`로 옮긴다(`tests/unit/product-extension-typecheck.test.ts:267-271`). 새 파일은 옮긴 모듈을 `export *`로 다시 내보내고(`:98`, `:130`), 설정 필드·env 행·`composeProduct` 결과와 그 `capabilities`를 펼친 뒤 탐침 것만 더한다(`:100-113`, `:132-142`). 완료 기준 "09-probe-downstream 상태에서 탐침 통과 + 출하 상태에서 통과": "제품 capability를 기능에 주는 다운스트림"을 같은 함수로 먼저 만들고 탐침을 올리는 케이스(`:313-323`)와 출하 상태 케이스(`:305-311`)가 있다. FE-GATE-005(CI env) `product-extension-typecheck.test.ts (2 tests)` 통과(`gate-artifacts/FE-GATE-005.txt:172`, coverage 실행 `:374`). FE-GATE-020의 제거·생성 드릴 사본 8번에서도 2 tests 통과(`FE-GATE-020.txt:209`, `:578`, `:1740` 등). 예약 이름 검사는 기능·context 폴더와 옮길 파일 이름까지 본다(`:259-266`). **09-R1**: 탐침의 `...product.capabilities`를 지우면(수정 전 덮어쓰기와 같은 결과) 1 failed / 1 passed다. 실패는 "passes when a product feature needs a product capability"이고 `tsconfig.app.json` 출력이 `runtime-adapters.ts(736,5): error TS2741: Property 'typecheckProbeDownstreamSettings' is missing`이다(사본의 `createInstalledFeatureLoaders` 호출, 저장소 `src/bootstrap/runtime-adapters.ts:735-736`). 출하 상태 케이스는 통과했다. 새 케이스가 지난 결함을 잡는다. 남은 가정(완료 기준 밖): 탐침 context가 소유 앱을 `template-app`으로 고정한다(`:216`). 두 다운스트림 모두 `APP_MODULE_ID = "template-app"`이라(`memento-frontend/src/apps/template-app/app-module.ts:6`, tech-log 같은 줄) 지금은 해당 없다 | +| 1105/09-02 | Redis session 모드를 recipe·매뉴얼대로 이으면 서버 401이 세션 owner에 닿지 않는다 | **고쳐짐** | 조립 루트가 제품 context에 `notifySessionUnauthenticated: () => authSession.onUnauthenticated()`를 준다(`src/bootstrap/runtime-adapters.ts:705`, 계약 `src/bootstrap/product-composition-contract.ts:91-100`). recipe의 `createSessionCookieRejectionHandler`는 `SESSION_COOKIE_*` 프로필의 401만 넘긴다(`recipes/session-owners/cookie-session-owner.ts:217-225`). 그래서 1103/09-01의 "세션과 무관한 provider 401은 로그아웃시키지 않는다"는 그대로다(`tests/recipes/cookie-session-owner.test.ts`의 `PARTNER_API_TOKEN` 케이스, 호출 2회). 완료 기준 "매뉴얼 04 4.3대로 이은 조립 루트에서 쿠키 읽기·쓰기 401 → 세션 `unauthenticated`, 이전 scope not current": `tests/recipes/session-owners-runtime.test.ts:416-436`이 그 연결(`:95`)로 본다. FE-GATE-007 `session-owners-runtime.test.ts (6 tests)` 통과(`FE-GATE-007.txt:104`). **09-R2**: 조립 루트의 `notifySessionUnauthenticated`(`runtime-adapters.ts:705`)를 빈 함수로 바꾸면 2 failed / 4 passed다. 실패는 "signs out when the server answers a cookie read with 401"과 "… write with 401"이고, 둘 다 `:434`에서 `expected 'authenticated' to be 'unauthenticated'`다. 템플릿 쪽 연결을 테스트가 지킨다. 매뉴얼 04 흐름도·예시·설명(`docs/manual/04-paired-backend-session.md:188`, `:191`, `:249`, `:256-257`), 매뉴얼 02 5절(`docs/manual/02-decision-tables.md:238`)과 7절 업로드 예시(`:375`), recipe 주석(`cookie-session-owner.ts:33-44`, `:181-187`)이 이제 같은 말을 한다. 남은 것(완료 기준 밖, 기록된 한계): 제품이 이 한 줄을 빼면 막는 검사가 없다(`CHANGELOG.md:107`) | +| 1105/09-03 | 계약 조립 오류의 원인이 `check:registries` 출력에 두 번 나온다 | **고쳐짐** | `loadErrorText`가 message에 reason이 이미 있으면 붙이지 않는다(`scripts/check-registries.ts:160-168`). 새 테스트가 실제 `ContractContributionError`를 던지는 source로 `check:registries`를 돌려 원인이 한 번(`split` 길이 2)이고 `(reason:`이 없음을 본다(`tests/unit/registry-governance.test.ts:656-711`). reason이 message에 없는 오류의 옛 테스트(`:546`)는 남았다. FE-GATE-005 "names a ContractContributionError's reason once" 통과(`FE-GATE-005.txt` registry-governance 12 tests). 매뉴얼 출력 형식 줄도 고쳤다(`docs/manual/reference/errors.md:156`) | +| 1103/09-03 | 짝 백엔드 인증 방식에 맞는 세션 owner가 없다 | **일부** (남은 것은 백엔드로 넘김) | ③ 쿠키 모드 401은 1105/09-02로 고쳐졌다. ① 실제 Keycloak 로그인·Redis 쓰기 1회는 이번에도 아무도 하지 않았다(README §16.5). ② pin 커밋 realm의 client는 여전히 confidential `ca-skeleton-api` 하나다(`git show 45d2a478:infra/keycloak/realms/ca-skeleton-realm.json`의 `"clientId": "ca-skeleton-api"`, `"publicClient": false`, 59·62행). Redis 모드 로그인·세션 조회 엔드포인트도 제품 몫으로 적혀 있다(`docs/manual/04-paired-backend-session.md:23`, `:195-201`) | +| 1103/09-04 | 플랫폼 예제 화면 4개를 끌 자리가 없다 | **일부** (결정 대기 D2, 이번 범위 변경 없음) | ① `EXAMPLES_PLATFORM`은 플랫폼 레지스트리에 그대로다(`src/contracts/routes.ts:33-45`). 수기 접근성 기록은 `Status: pending-manual-review`다(`artifacts/tests/a11y-manual/EXAMPLES_PLATFORM.md:3`). ② 지울 수 있는 예제 라우트(`/examples/{ui,states,auth}`)를 자기 페이지로 쓰는 브라우저 spec은 `8a44226`과 같은 8개다(`tests/e2e/{accessibility,design-system-interactions,old-tab-chunk-recovery,responsive,scroll-restoration,typography,ui-gallery}.spec.ts`, `tests/visual/platform.visual.spec.ts`, `git grep -lE "examples/(ui\|states\|auth)\|EXAMPLES_(UI\|STATES\|AUTH)"`). 바뀐 것은 문서뿐이다(`docs/architecture/starter-experience.md:104-118`, 1105/14-01) | +| 1103/09-05 | SW 등 선택 런타임을 켜는 일이 제품 확장 지점 밖에 있다 | **일부** | 고친 것: `ProductComposition.serviceWorker?: { blockers?, observe? }`(`product-composition-contract.ts:127-139`, `:166`)를 조립이 bundle에 싣고(`runtime-adapters.ts:779`) 템플릿 조립이 optional host에 넘긴다(`src/bootstrap/create-runtime-composition.ts:47`, `:61`, `:95-115`). 제품 `observe`의 throw는 조립이 삼킨다(`:104-110`). 던지는 blocker는 page controller가 막는 쪽으로 본다(`src/adapters/service-worker/service-worker-page-controller.ts:75-85`). 실제 조립을 지나는 테스트(`tests/component/runtime-composition-service-worker-product-wiring.test.ts:134-161`, FE-GATE-006 통과 `FE-GATE-006.txt:68`). **09-R3**: `create-runtime-composition.ts:61`(`...serviceWorkerWiring(productServiceWorker)`)을 지우면 그 1건이 `:147`에서 `expected [] to deeply equal [ { event: 'register', … } ]`로 실패한다. 매뉴얼 03·레시피가 새 자리를 가리킨다(`docs/architecture/optional-adapter-recipes.md:151`). 남은 것: ① 활성화 화면(`onUpdateWaiting`·`requestActivation()`, `src/contracts/service-worker.ts:177`, `:190`)을 쓰는 곳이 `src/` 어디에도 없다. 제품 소유 자리도 없다. ② realtime·Web Worker·오프라인 선택은 여전히 "Connect a runtime in src/bootstrap/optional-runtime-host.ts"로 거절된다(`src/bootstrap/optional-runtime-host.ts:55-65`) | +| (영역 16) 1103/16-05 — 이 영역 요청 | 뮤테이션 정책 `operationId`가 자유 문자열이다 | **고쳐짐** (이 수정이 새 09-01을 만들었다) | 완료 기준(1103 영역 16 문서) "E-2의 오타가 `check:types`에서 실패하거나, 실패 문구가 operation ID 불일치를 말한다"의 앞쪽을 채운다. `MutationOperationId = string & { readonly [MUTATION_OPERATION_ID]: true }`(`src/contracts/server-state.ts:268-278`). 이 값을 만드는 곳은 `commandMutationIdentity`뿐이다(`:294-313`). `BoundMutation.operationId`가 그 타입이다(`:319`). 공개 `useApplicationMutation` overload는 `BoundMutation`만 받는다(`src/presentation/adapters/query/application-query.ts:336-338`). `@ts-expect-error` 한 줄이 손 문자열 거절을 고정한다(`tests/unit/command-mutation-identity.test.ts:49-52`). `tsconfig.test.json`이 `tests/**/*.ts`를 포함하고 FE-GATE-003 typecheck PASS(`bbde570-ci/FE-GATE-003.log`)이므로 그 줄은 실제로 오류를 만난다. 커밋 꼬리말(`48c1ab7` "BREAKING CHANGE")과 CHANGELOG 2단계(`CHANGELOG.md:25`)·표 행(`:65`)이 말하는 코드 변경과 같다. 참조 기능(`src/features/reference-feature/presentation/use-reference-feature.ts:60`)과 쓰기 slice 생성기(`scripts/create-feature-write-slice.ts:511`)는 이미 `commandMutationIdentity`를 펼친다. FE-GATE-020 생성 드릴 통과. 템플릿 테스트의 손 ID 20곳은 `testMutationOperationId`(`tests/helpers/mutation-operation-id.ts:11-15`)로 바꿨고 단언은 그대로다. 위반 이름(`MISSING_IDEMPOTENCY_KEY`)을 나누는 안은 버렸다(커밋 본문, 기준이 "또는"이라 남은 것으로 세지 않는다). 안내의 빈칸은 새 09-01 | +| (영역 02) 1105/02-01 — 조립 쪽만 | 제품 scope closer가 던지면 진단 없이 `FAILED`로 멈춘다 | **조립 쪽 발견 없음** (발견 자체의 판정은 영역 02) | 제품 closer를 wrapper 하나로 감싸지 않고 각자 order 10 participant로 넘긴다(`src/bootstrap/runtime-adapters.ts:440-464`). scope는 reset마다 목록 함수를 읽고 order로 정렬한다(`server-state-scope-runtime.ts:156-170`, `orderParticipants`). 정렬은 안정 정렬이라 제품 순서가 유지된다. 하나가 던져도 나머지를 부르고 `FAILED`에 둔다(테스트 `runtime-adapters-product-scope-participants.test.ts:139`, `closed = ["after"]`). 실패마다 `scope_participant: