Merge pull request 'fix(review): 2026-11-06 리뷰를 기록하고 발견 25건을 고친다' (#8) from fix/maturity-review-2026-11-06 into main
This commit was merged in pull request #8.
This commit is contained in:
+75
-5
@@ -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(<descriptor>)`로 받은 정책은 이제 `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, BoundedPollOperation>`으로 적는다. `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>`)은 본문에 그 기능 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`)는 마운트된 동안만 저장 뒤 상세로, "변경됨으로 확인" 뒤 목록으로 옮긴다. 이미 생성한 기능은 바뀌지 않는다. 그 `<base>-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 `<FEATURE>_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: "<ID>"`와 `requiresIdempotencyKey`를 `...commandMutationIdentity(<descriptor>)`로 바꾼다. 문자열로 적으면 `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: "<ID>"`와 `requiresIdempotencyKey`를 `...commandMutationIdentity(<descriptor>)`로 바꾼다. 문자열로 적으면 `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: "<ID>", method: "POST", retrySemantics: "KEYED" } })`. 멱등 키가 필요 없으면 `"NEVER"`다. 대조할 descriptor가 없으니 이 ID의 오타는 어느 검사도 잡지 않는다. 테스트 fixture는 `tests/helpers/mutation-operation-id.ts`의 `testMutationOperationId("<ID>")`를 쓴다. 문자열 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이다.
|
||||
|
||||
|
||||
@@ -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"
|
||||
}
|
||||
|
||||
@@ -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": [
|
||||
|
||||
@@ -39,9 +39,9 @@
|
||||
}
|
||||
],
|
||||
"initialJavascript": {
|
||||
"gzipBytes": 204111,
|
||||
"gzipBytes": 204193,
|
||||
"files": 27,
|
||||
"perFeatureGzipBytes": 768,
|
||||
"perContextGzipBytes": 218
|
||||
"perFeatureGzipBytes": 751,
|
||||
"perContextGzipBytes": 245
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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를 더하면 그 목록도 같은 변경에서 고친다.
|
||||
|
||||
@@ -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에
|
||||
|
||||
@@ -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` |
|
||||
|
||||
@@ -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<Value> = 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에 넣지 않는다.
|
||||
|
||||
|
||||
@@ -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<Value, Operation>`, `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 |
|
||||
|
||||
@@ -269,6 +269,7 @@ DTO와 problem details(`type`·`title`·`status`)를 감싸지 않고 보내는
|
||||
- `boundary`: descriptor의 입력·응답·실패 검증기와 라우트의 `paramsSchema`·`searchSchema`에서 쓰인 자리로 정해진다. 다르면 `<schemaId>: row <적은 값>, used as <맞는 값>`으로 실패한다. 쓰이는데 행이 없으면 `<schemaId>: 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과 같은 `<Pascal>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(<OPERATION>_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: "<ID>", method: "POST", retrySemantics: "KEYED" } })`. intent가 멱등 키를 실어야 하면(Fileserver 업로드에 `idempotencyKey`를 넘길 때) `retrySemantics`는 `"KEYED"`, 아니면 `"NEVER"`다. 이 ID를 대조할 descriptor가 없으므로 ID는 intent의 이름일 뿐이고, 오타는 어느 검사도 잡지 않는다(③).
|
||||
- 테스트에서 descriptor 없이 정책을 만들 때는 `tests/helpers/mutation-operation-id.ts`의 `testMutationOperationId("<ID>")`를 쓴다. 이 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: <operationId> 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에서 그 답은 결과 불명이다. 짝 백엔드 모양의 필드 오류 테스트는 생성된 작성 폼 테스트(`<base>-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`)이다.
|
||||
- 메시지: `<id> removal failed:` 다음 줄 `fixture-id-residue: residue: <files>`
|
||||
- 템플릿 테스트가 예시 ID(`invoice-feature` 등)를 데이터로 쓰는 것은 잔여로 세지 않는다(1105/16-04). 그래서 매뉴얼 예시 이름으로 만든 기능도 이 단계를 통과한다.
|
||||
- **못 잡음**: 기능을 가리키지 않는 폴더 밖 파일. 예: route ID만 적은 e2e spec, `artifacts/tests/a11y-manual/<ROUTE_ID>.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/<ROUTE_ID>.md`. 기능 전용 spec은 [03 문서](03-outside-feature-folder.md)의 목록대로 손으로 지운다. vitest 테스트(`*.test.ts`) 안에서 기능 ID를 글자로만 적은 것도 잔여로 세지 않는다. 그 테스트가 지운 기능에 기대면 같은 드릴의 `test:all`이 실패한다. 드릴은 `src`와 `tests`만 찾고, a11y 기록은 남아도 검사가 실패하지 않는다.
|
||||
|
||||
④ **쓸 스킬**: `documentation-and-adrs`, `deprecation-and-migration`
|
||||
|
||||
|
||||
@@ -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(<OPERATION>_CONTRACT)`가 `requiresIdempotencyKey: true`를 준다 | 같은 함수가 `false`를 준다 | 같은 함수가 `false`를 준다 |
|
||||
| 뮤테이션 정책 | `...commandMutationIdentity(<OPERATION>_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`) 기능이 자동으로 다시 부르지 않는다. 아래 주의대로 먼저 확인한다.
|
||||
|
||||
|
||||
@@ -66,7 +66,7 @@ corepack pnpm create:feature <id> [--context <context id>] [--with-create [--key
|
||||
- `presentation/use-<base>-create.ts`: 작성 뮤테이션 정책(`commandMutationIdentity`)
|
||||
- `presentation/<base>-form.ts`: 폼 스키마. 이름 길이는 요청 스키마의 상수(`<BASE>_NAME_MAX_LENGTH` = 백엔드 `NAME_MAX_LENGTH` 100)를 쓴다
|
||||
- `presentation/<base>-detail-page.tsx`: `DetailPage`
|
||||
- `presentation/<base>-create-page.tsx`: `FormPage`. 저장하면 상세를 연다. 결과 불명이면 `AsyncSurface`를 보인다
|
||||
- `presentation/<base>-create-page.tsx`: `FormPage`. 저장하면 상세를 연다. 저장 중에 화면을 떠났으면 옮기지 않는다. 결과 불명이면 `AsyncSurface`를 보인다
|
||||
|
||||
`domain/`은 만들지 않는다. 업무 규칙이 생기면 사람이 만든다.
|
||||
|
||||
@@ -76,7 +76,7 @@ corepack pnpm create:feature <id> [--context <context id>] [--with-create [--key
|
||||
- `<base>-feature-input.test.ts`: input 단위 테스트
|
||||
- `<base>-list-page.test.tsx`: 라우터를 거치는 페이지 테스트(목록, `meta.page.total`, 빈 목록, 실패 후 다시 시도)
|
||||
- `<base>-http-gateway.test.ts`: 짝 백엔드 본문을 손으로 적은 gateway 테스트. 하네스의 재시도 상한은 앱 기본값 2다
|
||||
- `<base>-create-page.test.tsx`(`--with-create`): 201 저장 뒤 상세, 400 `<FEATURE>_INVALID` 필드 오류와 다시 저장, 응답을 잃은 저장(`NEVER`는 다시 보내기 없음, `KEYED`는 같은 키로 다시 보내기)
|
||||
- `<base>-create-page.test.tsx`(`--with-create`): 201 저장 뒤 상세, 400 `<FEATURE>_INVALID` 필드 오류와 다시 저장, 응답을 잃은 저장(`NEVER`는 다시 보내기 없음, `KEYED`는 같은 키로 다시 보내기), 저장 중 목록으로 간 뒤 끝난 저장(목록에 머문다)
|
||||
|
||||
기능 폴더 밖:
|
||||
|
||||
|
||||
@@ -86,6 +86,7 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010
|
||||
| `duplicate operation: <operationId>` (계약 조립 오류의 `reason`) | operation ID 중복 | `contracts/<base>-contract-contribution.ts`. 접두어를 붙인다 |
|
||||
| `FE-REG-API.<operationId>.requestSchema references unknown FE-REG-SCHEMA.schemaId=<id>` | descriptor의 입력 스키마 ID가 스키마 메타데이터에 없다 (`responseSchema`, `problemSchema`도 같은 꼴. 실패 본문 행은 `boundary: "api-problem"`) | `contracts/<base>-schema-metadata.ts` |
|
||||
| `<schemaId>: row <boundary>, used as <boundary>` (`tests/unit/schema-metadata-policy.test.ts`) | 스키마 메타 행의 `boundary`가 그 스키마가 쓰인 자리와 다르다. `no FE-REG-SCHEMA row`는 쓰이는데 행이 없다 | `contracts/<base>-schema-metadata.ts` |
|
||||
| `<operationId> <schemaId>: row states no direction, used as <direction>` 또는 `row states no unknownFieldPolicy, validator <policy>` (`tests/unit/schema-metadata-policy.test.ts`) | descriptor가 쓰는 스키마의 행이 `direction`·`unknownFieldPolicy`를 적지 않았다(1106/07-02) | `contracts/<base>-schema-metadata.ts`에 두 칸을 적는다. 값은 쓰인 자리와 검증기가 정한다. 객체가 아닌 본문의 검증기(`z.undefined()` 등)는 `direction`만 요구한다 |
|
||||
| `Unregistered route codec: <codecId>` | URL 함수가 기능 codec을 `buildRouteUrl`에 넘기지 않았다 | `presentation/<base>-routes.ts` |
|
||||
| `contract package <packageId> is declared, but no loaded contribution pins it` | 계약 `contractPackages`에 적은 패키지를 계약 기여가 쓰지 않는다 | `contracts/<base>-contract-contribution.ts`의 `source` |
|
||||
| `<id> contributes contract package <packageId>, which no installed feature declares in contracts.contractPackages` | 계약 기여의 신원과 계약 선언의 신원이 다르다 | 둘 다 `<BASE>_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: <ids>` (`verify:documentation`) | 라우트의 a11y 기록 파일이 없다 | 기존 pending 기록을 복사해 제목과 `Route ID`를 바꾼다 |
|
||||
| `Manual accessibility record format is invalid:` 다음 `artifacts/tests/a11y-manual/<ROUTE_ID>.md: missing record` (FE-GATE-009) | 같은 원인 | 같은 곳 |
|
||||
| `a11y.json not written:` 다음 `a11y: <ROUTE_ID> reads one resource (<operationId>) 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/<base>-schema-metadata.ts`를 고친다 |
|
||||
| `Manual accessibility evidence is incomplete:` 다음 `<ROUTE_ID>: <failures>` (FE-GATE-028) | 서명하지 않은 기록 | [03 문서](../03-outside-feature-folder.md#수동-접근성-검토-서명) |
|
||||
| `release IDs do not match` (FE-GATE-028) | 라우트마다 다른 릴리스로 검토했다 | 같은 릴리스 후보로 다시 검토한다 |
|
||||
| `<doc> names paths that do not exist: <paths>` (`verify:documentation`) | 문서가 없는 경로를 적었다 | 그 문서 |
|
||||
@@ -196,6 +198,6 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010
|
||||
|
||||
| 메시지 | 원인 | 고칠 곳 |
|
||||
|---|---|---|
|
||||
| `<id> removal failed:` 다음 `fixture-id-residue: residue: <files>` (`test:sample-removal`) | 기능을 지운 뒤에도 그 기능을 가리키는 파일이 남았다. `src`는 기능 ID나 폴더 이름을 담은 파일, `tests`는 이름이 기능 ID를 담거나 기능 폴더(`src/features/<id>/`, `tests/features/<id>/`)에서 import하는 파일이다 | 그 파일을 기능 폴더 안으로 옮기거나, 기능을 가리키지 않게 한다. 목록에 템플릿 파일이 나오면 템플릿 결함이다. 그 파일을 고치지 말고 템플릿에 알린다 |
|
||||
| `<id> removal failed:` 다음 `fixture-id-residue: residue: <files>` (`test:sample-removal`) | 기능을 지운 뒤에도 그 기능을 가리키는 파일이 남았다. `src`는 기능 ID나 폴더 이름을 담은 파일, `tests`는 이름이 기능 ID를 담거나 기능 폴더(`src/features/<id>/`, `tests/features/<id>/`)에서 import하는 파일, 본문에 `-`가 든 기능 ID나 폴더 이름을 적힌 그대로 한 이름으로 적은 Playwright spec(`*.spec.ts`)이다 | 그 파일을 기능 폴더 안으로 옮기거나, 기능을 가리키지 않게 한다. 지운 기능 전용 spec이면 지운다. 목록에 템플릿 파일이 나오면 템플릿 결함이다. 그 파일을 고치지 말고 템플릿에 알린다 |
|
||||
| `No installed feature declares FEATURE_MODULE_ID "<id>"` | `--feature=`에 없는 기능 ID | 명령 인자 |
|
||||
| `feature scaffold failed:` 다음 `<check>: <failure>` (`test:feature-scaffold`) | 생성한 기능이 게이트 하나를 통과하지 못했다 | `scripts/create-feature.ts`의 템플릿. 제품 팀이 아니라 템플릿을 고칠 일이다 |
|
||||
|
||||
@@ -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한다. 화면은 근거 없는
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -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-<run>-<attempt>`)으로 성공·실패와 상관없이
|
||||
올린다(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-<run>-<attempt>`, 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
|
||||
|
||||
@@ -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로 충돌하는 상태를 만들지
|
||||
|
||||
@@ -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를 넘으면 상한을 올리기
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 근거:
|
||||
|
||||
|
||||
@@ -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:<path>`. `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="\"<sha256>\""`, 확인 전 `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` |
|
||||
@@ -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(`<prefix>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<n>.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` |
|
||||
@@ -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:<path>`로 읽기만 했다 |
|
||||
| 커밋·작업 상태·확인 시점 | 프론트 `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 남음.
|
||||
@@ -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<unknown, unknown, unknown>`이라 실행기 호출의 입력·출력 타입이 사라진다. 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<unknown, unknown, unknown>`이다(`bounded-polling.ts:41-45`, `bounded-poll-coordinator.ts:119`). coordinator는 `Value`만 제네릭이다(`:97`, `:145-147`). 실행기는 `execute<Input, WireOutput, Problem>(operation: InstalledHttpContract<Input, WireOutput, Problem>, 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<Value, Operation extends BoundedPollOperation = BoundedPollOperation>`로 `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<unknown, unknown, unknown>`이라 실행기 호출의 입력·출력 타입이 사라진다. 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` |
|
||||
@@ -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`).<br>**실행(`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`).<br>**완료 기준과의 차이**: 기준은 "Y1b 각 10회, 05-R2 Chromium 객체 0·1·3·8개"와 "그 직후와 다음 reconcile 뒤 파일 0·`NOT_FOUND`"(1103 기준)다. 저장소 테스트는 Y1b를 1회씩, reconcile 없이 돈다. 브라우저 spec은 객체 1·8개가 없고 파일 수를 보지 않는다. 새 코드에서는 끝까지 돈 purge의 결과가 put이 언제 끝났는지에 따라 갈리지 않는다(늘 삭제). 그래서 반복의 의미는 작다. 그래도 기준대로 배치로 돌렸다.<br>**배치(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`가 없다는 이유다.<br>**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`).<br>② 코드: 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`).<br>③ 이 문서는 그 뒤로도 고쳐졌다. `e98a980d`(1101/05-01 pulse 키)가 같은 문서의 `:82-85`만 고쳤다. `dc7c95b`(1105/05-01)는 행을 더했지만 이 문서를 고치지 않았다. 문서 머리의 기준일은 2026-07-28이다(`:12`). 그러나 "현재"라는 문장과 이후의 부분 수정이 섞여, 읽는 사람은 지금 목록으로 읽는다.<br>④ `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).
|
||||
@@ -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` |
|
||||
@@ -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 <dir>`를 돌린다. 사본과 실제 백엔드 문서의 대조는 여전히 게이트 밖이다(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` |
|
||||
@@ -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"` 안의 버튼, 레이아웃 `<main tabIndex>` 미검사 | 그대로(발견 아님) | `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 남음.
|
||||
@@ -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 <pin>:<path>`로 읽기만) |
|
||||
| 필수 요구와 규모·운영 목표 | 두 템플릿을 짝으로 빨리 출시. 다운스트림(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`를 `<name>-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: <label>` 진단 1건(`:160-197`). 형식에 맞지 않는 label은 `TypeError`(`runtime-adapters.ts:713-722`, 테스트 `:199-203`). 이 throw는 부팅을 `BOOT_UNEXPECTED_FAILURE`로 멈추고, 개발 빌드는 원래 오류를 console에 보고한다(`src/bootstrap/render-boot-failure.tsx:19-20`). 메시지가 어느 label인지 말하지 않는 것은 작아서 발견으로 세지 않았다. CHANGELOG 6단계(`CHANGELOG.md:29`)가 BREAKING으로 적는다. FE-GATE-005 `runtime-adapters-product-scope-participants.test.ts (4 tests)` 통과 |
|
||||
| 0925 FOLLOW-UP 09-07 | 샘플 제거 드릴이 lint·`check:i18n`·e2e를 건너뜀 | **일부** (변경 없음) | lint, `verify:documentation`, `check:i18n`, `check:design-system`은 돈다(`scripts/test-sample-removal.ts:443-448`). 브라우저 테스트는 여전히 돌리지 않는다. 예제 기능 제거 드릴을 돌리는 게이트도 없다(`CHANGELOG.md:93`, 1105/14-01 일부). 위 1103/09-04 ②가 그 결과다 |
|
||||
| 0925 FOLLOW-UP 09-08 | local-draft ABA를 주석으로 닫음 | **남음(허용한 대안)** | `src/features/local-draft-feature/domain/local-draft.ts:2-11` 그대로. 폴더에 `NOT_A_FEATURE` 표시가 있어 기능이 아니다 |
|
||||
|
||||
지난 라운드에 고쳐짐으로 닫은 1103/09-01·09-02·09-06~09-11은 다시 세지 않는다. 그 경로의 파일 중 `src/features/feature-adapter-contribution.ts`, `src/presentation/providers/session-provider.tsx`, `src/application/ports/auth-session-port.ts`, `src/adapters/auth/`, `src/bootstrap/{load-release-manifest,runtime-config-schema}.ts`, `src/contracts/contract-set.ts`는 `8a44226`과 같다(`git diff --stat` 0). `reportServerUnauthenticated`(`runtime-adapters.ts:605-621`)도 본문이 같다.
|
||||
|
||||
## 3. 이번 발견 (36.3)
|
||||
|
||||
요약: Low 1. P3 1. 확인된 결함 1.
|
||||
|
||||
검사 약화 점검(브리프 4절): `git diff 8a44226..bbde570`의 영역 테스트를 봤다.
|
||||
|
||||
- `product-extension-typecheck.test.ts`: 옛 케이스의 파일 내용·tsc 3종·생성기 검사가 그대로다. 예약 이름 검사는 저장소 쪽에서 사본 쪽으로 옮겼고(사본은 저장소와 같다) 대상이 넷으로 늘었다. 케이스가 하나 늘었고 케이스별 시간 상한 120초는 그대로다(`:310`, `:322`).
|
||||
- 1103/16-05의 테스트 20곳: 지운 줄은 `operationId: "<ID>"` 뿐이고, 더한 줄은 같은 문자열을 `testMutationOperationId(...)`로 감싼 것이다(`48c1ab7`의 `tests/component` diff). helper는 `commandMutationIdentity`를 거쳐 런타임 값이 같다(`tests/helpers/mutation-operation-id.ts:11-15`). 단언은 바뀌지 않았다.
|
||||
- `runtime-adapters-product-scope-participants.test.ts`, `registry-governance.test.ts`, `server-state-scope-runtime.test.ts`, `session-owners-runtime.test.ts`, `cookie-session-owner.test.ts`: 더하기만 했다.
|
||||
- `runtime-adapters.test.ts`: 10-01 테스트를 더했고 지운 단언은 없다.
|
||||
- 영역 경로에 새 skip·only·todo·`it.fails`·시간 상한 증가는 없다.
|
||||
|
||||
약화로 센 것은 없다.
|
||||
|
||||
### 09-01 1103/16-05 이행 안내가 HTTP descriptor 없는 뮤테이션과 테스트의 길을 말하지 않고, 매뉴얼 01 안에서 두 줄이 다르다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함(이행 안내 빈칸·문서 불일치) |
|
||||
| 관련 관점 | 20, 17, 4, 9, 5 (30.4 업데이트 전파) |
|
||||
| 근거 | `MutationOperationId`를 만드는 곳은 `commandMutationIdentity` 하나다(`src/contracts/server-state.ts:268-278`, `:294-313`). 그 함수는 `{ contract: { operationId, method, retrySemantics } }` 모양만 받는다(`:295-301`). CHANGELOG 2단계는 "`operationId: "<ID>"`와 `requiresIdempotencyKey`를 `...commandMutationIdentity(<descriptor>)`로 바꾼다"만 적는다(`CHANGELOG.md:25`). 매뉴얼 01도 descriptor 상수 길만 적는다(`docs/manual/01-add-a-feature.md:475`, `:484`, `:498-499`). descriptor가 없는 뮤테이션은 손으로 만든 descriptor 모양 객체를 넘기는 수밖에 없다. 매뉴얼 01은 바로 그 길을 "**못 잡음**"으로 적는다(`:500`). 커밋 본문은 이 한계를 안다: "HTTP가 아닌 뮤테이션은 descriptor 모양 객체를 넘겨야 한다. 이 repo에는 그런 소비자가 없다"(`48c1ab7`). 이 문장은 CHANGELOG에도 매뉴얼에도 없다(`git grep -n "descriptor 모양\|HTTP가 아닌 뮤테이션" -- CHANGELOG.md docs src` 0건). 템플릿이 지원하는 경로 중 V3 descriptor가 없는 쓰기가 있다. Fileserver 업로드 client는 `upload(request)`만 있고 V3 `InstalledHttpContract`가 아니다(`src/adapters/http/fileserver-upload.ts:125-129`). 매뉴얼 02는 그 업로드에 `idempotencyKey`를 넘기라고 적는다(`docs/manual/02-decision-tables.md:290`, `:393`). 화면에서 그 키와 결과 불명 처리를 받는 길은 `useApplicationMutation`(`BoundMutation`만 받음, `src/presentation/adapters/query/application-query.ts:336-338`)이다. 테스트도 같다. 템플릿은 자기 테스트의 손 ID 20곳을 `tests/helpers/mutation-operation-id.ts`의 helper로 바꿨다. 그 helper도 손 객체 길이다(`:11-15`). CHANGELOG는 이 helper도, 테스트 fixture가 `check:types:test`에서 실패한다는 것도 말하지 않는다(`git grep -n "testMutationOperationId\|mutation-operation-id" -- CHANGELOG.md docs` 0건). 매뉴얼 01 안의 불일치: `:476`은 "손으로 적은 ID에 오타가 있으면 저장이 항상 실패하고, 화면은 '요청을 처리할 수 없습니다'다"라고 아직 적는다. `:499`는 "문자열로 직접 적으면 `check:types`가 실패한다"고 적는다. `:476`은 이 BREAKING 전의 동작이다 |
|
||||
| 발생 조건 | (가) 다운스트림이 이 절을 받는다. 그 제품에 V3 descriptor가 없는 `BoundMutation`(Fileserver 업로드, 로컬 쓰기, 자체 gateway 쓰기)이나 정책을 손으로 적은 테스트 fixture가 있다. (나) 기능 작성자가 매뉴얼 01 7단계를 읽는다 |
|
||||
| 영향 | (가) `check:types`가 `Type 'string' is not assignable to type 'MutationOperationId'`로 실패한다. 고칠 길을 찾으면 그 길이 매뉴얼의 "못 잡음"이다. 제품마다 helper를 따로 만들거나 `as MutationOperationId`로 우회한다. 우회는 brand의 목적을 지운다. 런타임 피해는 없다. (나) `:476`을 읽은 사람은 오타가 런타임에만 드러난다고 믿는다. 동작 피해는 없다 |
|
||||
| 심각도·우선순위 | Low · P3 — 타입 검사가 먼저 실패하므로 잘못된 동작이 배포되지 않는다. 이행 비용과 문서 신뢰만 깎는다 |
|
||||
| 통제·증거 | 목표 M1(이행 안내가 지원 경로를 모두 적는다) / 확인 M0(descriptor 없는 경로 안내 없음) · E1 |
|
||||
| 확실성과 남은 가정 | 코드와 문서로 확인했다. 실행하지 않았다. 두 다운스트림의 현재 동기화 지점(v0.2.0)에는 손 ID 정책이 있다(`memento-frontend/src/features/memento-web/presentation/hooks/use-memento.ts:149-152` 등 8곳, `tech-log-frontend/.../studio-asset-server-state.ts:140-153`의 `operationId: string` 매개변수 helper). 그중 V3 descriptor로 옮길 수 없는 것이 몇 개인지는 모른다. 1103 절의 V2 삭제 이행 뒤에 descriptor가 생길 수 있다(추론) |
|
||||
| 결정의 근거 | 확인한 사실: 위 근거. 기록된 의도: 커밋 본문이 descriptor 없는 뮤테이션과 손 객체의 한계를 "위험·한계"에 적었다. 버린 대안 (2) "설치된 operation ID의 union 타입"은 늦게 적재되는 계약 때문에 버렸다. 리뷰어 추론: brand 선택 자체는 맞다. descriptor 없는 쓰기에 공식 길이 없어서, 그 길이 "못 잡음"으로만 남았다 |
|
||||
| 이해 비용 | 업로드 화면을 만드는 기능 작성자와 동기화하는 다운스트림 담당이 커밋 본문까지 읽어야 길을 안다 |
|
||||
| 최소 개선 방향 | CHANGELOG 2단계와 매뉴얼 01에 한 줄씩: "V3 descriptor가 없는 뮤테이션(Fileserver 업로드 등)은 `commandMutationIdentity({ contract: { operationId, method, retrySemantics } })`로 받는다. 이 경우 오타는 잡지 못한다. 테스트 fixture는 `tests/helpers/mutation-operation-id.ts`를 쓴다." 매뉴얼 01 `:476`의 둘째 문장을 지우거나 "손 객체" 경우로 좁힌다. 더 나아가면 descriptor 없는 쓰기용 이름 있는 함수(`mutationIdentity({ operationId, method, retrySemantics })`)를 공개한다 |
|
||||
| 대안 비교 | (A) 문서 두 줄: 가장 작다. 손 객체가 공식 길이 된다. (B) 이름 있는 함수 공개: 의도가 코드에 보인다. 공개 API가 하나 는다. (C) Fileserver 업로드 client가 descriptor 모양 상수(`FILESERVER_UPLOAD_MUTATION`)를 내보낸다: 템플릿이 아는 유일한 non-V3 쓰기에서 오타 문제가 사라진다. 다른 non-V3 쓰기는 남는다 |
|
||||
| 단순화의 보존 조건 | 손 문자열은 계속 `check:types`에서 실패한다(`command-mutation-identity.test.ts:49-52`). GET descriptor는 계속 throw한다(`server-state.ts:303-307`) |
|
||||
| 비용·부작용 | (A) 문서 두세 줄. (B)·(C) 함수 하나와 테스트 하나 |
|
||||
| 재검토 조건 | 템플릿이 descriptor 없는 쓰기를 V3 descriptor로 모두 옮기거나, `BoundMutation`이 descriptor를 직접 받게 바뀌면 |
|
||||
| 완료 기준 | CHANGELOG 2단계와 매뉴얼 01이 descriptor 없는 뮤테이션과 테스트 fixture의 길을 적는다. 매뉴얼 01에 "손 문자열은 저장 때 실패" 문장이 남지 않는다 |
|
||||
| 검증 방법 | `git grep`으로 두 문서의 문장을 확인한다. (B)·(C)를 고르면 그 함수의 `@ts-expect-error` 한 줄과 런타임 값 테스트 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
| 재검증 결과 | 해당 없음(신규) |
|
||||
|
||||
## 4. 28개 관점 판정 (36.2)
|
||||
|
||||
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가
|
||||
|
||||
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | 코드 성숙도 | 적용 | 조립 불변식 M3 / M3 | E2(FE-GATE-005·007) | O — 401 주인 판정, 쿠키 모드 세션 알림, 자격증명 순서, needs 좁히기, participant label이 throw·테스트로 지켜진다. 남은 것은 연결을 빠뜨린 제품을 막는 검사가 없다는 것(21) |
|
||||
| 2 | 구조적 성숙도 | 적용 | 공개 경계 M3 / M3 | E1, FE-GATE-001~003 | P — 제품 소유 파일 셋에 SW 연결이 들어왔다(1103/09-05). SW 활성화 화면 자리와 realtime·worker·offline 런타임은 템플릿 파일이다(1103/09-05 일부). 플랫폼 구성 화면은 플랫폼 레지스트리다(1103/09-04 일부) |
|
||||
| 3 | 변경 용이성 | 적용 | 제품 변경 = 제품 파일만 M2 / M2 | E2(FE-GATE-005 탐침 2 tests) | P — 제품 capability를 기능에 줘도 템플릿 탐침이 통과한다(1105/09-01 고쳐짐). SW blockers·observe도 제품 파일이다. 예제 기능을 빼면 브라우저 spec 8개를 고친다(1103/09-04 ②) |
|
||||
| 4 | 인지 부하 | 적용 | 확장 위치 한 표 M1 / M1 | E1 | P — 쿠키 모드 401은 recipe·매뉴얼 04·02·CHANGELOG가 같은 말을 한다. 매뉴얼 01은 손 ID의 실패 시점을 두 가지로 말한다(09-01) |
|
||||
| 5 | 위험 가시성 | 적용 | 판단 규칙이 호출부에서 보임 M2 / M2 | E1 | P — 401 판정이 함수 하나와 계약 주석에 있다(`runtime-adapters.ts:598-621`, `product-composition-contract.ts:91-100`, `:148-157`). hook 누락 위험은 매뉴얼 04 `:191`과 CHANGELOG `:107`에 있다. descriptor 없는 뮤테이션의 한계는 커밋 본문에만 있다(09-01) |
|
||||
| 6 | 실패 성숙도 | 적용 | 안전한 기본 M2 / M2 | E2(FE-GATE-007) | P — 쿠키 세션 만료가 세션에 닿는다(1105/09-02). 제품이 hook을 빼면 만료를 모른다. 기본이 "알리지 않음"이라 fail-open 쪽이다(`CHANGELOG.md:107`, 기록된 선택) |
|
||||
| 7 | 운영 성숙도 | 적용 | 경계 실패 진단 M2 / M2 | E2(FE-GATE-005) | P — scope reset 실패가 participant label과 함께 진단에 남는다(1105/02-01). 제품 hook이 없을 때 provider 401이 버려지는 것은 진단에 남지 않는다(`runtime-adapters.ts:612-618`) |
|
||||
| 8 | 디버깅 가능성 | 적용 | 조립 오류가 원인을 말함 M3 / M3 | E2(`registry-governance.test.ts:656`) | O — 계약 조립 실패 원인이 한 번 나온다(1105/09-03). 탐침이 다운스트림에서 임시 경로 오류를 내지 않는다(1105/09-01). label `TypeError`가 어느 label인지 말하지 않는 것은 작다(2절) |
|
||||
| 9 | 유지보수 성숙도 | 적용 | 낡은 설명 정리 M1 / M1 | E1 | P — recipe 주석이 401 동작을 따라갔다. 매뉴얼 01 `:476`이 16-05 전 동작을 적는다(09-01). `src/application/result.ts` 폐기 재수출 그대로(> 16 영역 1101/16-05) |
|
||||
| 10 | 테스트 성숙도 | 적용 | 핵심 판단 M3 / M3 | E2(FE-GATE-003·005·006·007, CI env), E2(09-R1~R3 변이) | O — 1105 수정 셋과 1103/09-05·16-05에 각자 테스트가 있다. 다운스트림 상태(제품 capability)를 템플릿 테스트가 직접 만든다. 쿠키 모드 401을 조립 루트에서 본다. 수정 셋을 되돌린 변이 3개가 모두 기대한 테스트에서 기대한 이유로 실패했다(09-R1~R3). 테스트는 여전히 템플릿 출하 상태와 그 흉내만 본다(5절 다운스트림) |
|
||||
| 11 | 데이터 성숙도 | 적용(샘플 범위) | — / M1 | E1 | P — local-draft ABA는 주석으로만(0925 FOLLOW-UP 09-08, 허용한 대안). 이 영역에 데이터 손상 경로는 없다 |
|
||||
| 12 | 동시성 성숙도 | 적용(401·계정 전환) | 이전 scope의 401은 새 세션에 닿지 않음 M3 / M2 | E1(지난 라운드 09-R1은 이전 커밋 증거라 재사용하지 않는다) | P — 실행기의 admission 경쟁 처리 코드는 그대로다. 쿠키 경로도 같은 실행기 결과 뒤에 알린다(`runtime-adapters.ts:675-680`). 실행기 반환과 알림 사이 한 microtask의 전환은 여전히 아무도 재현하지 않았다(5절) |
|
||||
| 13 | 확장성 | 적용 | 기능·제품 수 축 M3 / M3 | E2(탐침 다운스트림 케이스) | O — 제품 수 축의 1105/09-01이 닫혔다. 탐침 context의 앱 id 고정은 지금 두 다운스트림에 해당하지 않는다(2절) |
|
||||
| 14 | 성능 성숙도 | > 15 영역 | — | — | > |
|
||||
| 15 | 보안 성숙도 | 적용 | fail-closed M3 / M3 | E2(FE-GATE-007) | O — ANONYMOUS는 세션을 묻지 않는다. 쿠키 handler는 `SESSION_COOKIE_*`만 세션에 넘겨 외부 토큰 401이 로그아웃시키지 않는다. OIDC recipe의 ID token 서명 미확인은 문서화된 선택이다(OIDC Core 3.1.3.7(6), 매뉴얼 04 `:173`) |
|
||||
| 16 | 의존성 성숙도 | 적용 제외 — 영역 고유 의존성 없음 | — | — | - |
|
||||
| 17 | API / Contract 성숙도 | 적용 | 공개 계약과 이행 안내가 같음 M3 / M2 | E1, FE-GATE-003 | P — `notifySessionUnauthenticated`, `serviceWorker`, label 형식, `MutationOperationId`가 CHANGELOG에 [계약]·BREAKING으로 있다(`CHANGELOG.md:25`, `:29-31`, `:65`, `:68-70`). descriptor 없는 뮤테이션의 이행 길이 없다(09-01) |
|
||||
| 18 | 배포 성숙도 | > 13 영역 | — | — | > — 플랫폼 구성 화면의 FE-GATE-028 서명 요구는 1103/09-04 일부 |
|
||||
| 19 | 설정 성숙도 | 적용 | 제품 키 strict 검증 M3 / M3 | E2(FE-GATE-005 탐침) | O — 탐침이 제품 설정 키를 지우지 않고 더한다(`product-extension-typecheck.test.ts:100-113`) |
|
||||
| 20 | 개발자 경험 | 적용 | 제품 파일 → 게이트 통과 M3 / M2 | E2(FE-GATE-005·020) | P — 제품 capability·SW 연결·쿠키 세션이 제품 파일만으로 된다. 16-05 이행에서 descriptor 없는 뮤테이션의 길이 없다(09-01). 쿠키 세션은 한 줄을 기억해야 한다 |
|
||||
| 21 | Guardrail 성숙도 | 적용 | 조립 실수 차단 M3 / M2 | E2 | P — 손 문자열 ID(타입), 틀린 label(조립 throw), 표시+선언 동시 존재, needs 밖 capability를 막는다. 쿠키 provider를 두고 `onCredentialRejected`를 빠뜨린 제품은 막지 않는다(`CHANGELOG.md:107`) |
|
||||
| 22 | 추상화 성숙도 | 적용 | 계약이 짧고 정확 M2 / M2 | E1 | O — `composeProduct`가 context로 세션에 알릴 수 있어 모듈 변수 연결이 사라졌다(1105/09-02). SW 연결은 선택 칸 하나다 |
|
||||
| 23 | 일관성 | 적용 | 같은 선택은 같은 장치 M2 / M2 | E1 | P — 예제 화면 셋은 기능 선택으로 뺀다. 플랫폼 구성 화면만 예외다(1103/09-04 ①) |
|
||||
| 24 | 네이밍 / 의미 성숙도 | 적용 | — / M2 | E1 | P — `TEMPLATE_APP_MODULE`이 선택된 아무 앱을 가리키는 것은 그대로다(`src/apps/template-app.ts:10`) |
|
||||
| 25 | 조직 확장성 | 적용 | 동기화 충돌 자리 분리 M2 / M2 | E2(탐침 다운스트림 케이스) | O — 템플릿 탐침이 다운스트림 제품 파일을 보존해 동기화 충돌 자리가 아니다(1105/09-01). SW를 켠 제품도 템플릿 파일을 되돌린다(`CHANGELOG.md:31`) |
|
||||
| 26 | Ownership 성숙도 | > 14 영역 | — | — | > |
|
||||
| 27 | 삭제 가능성 | 적용 | 기능·예제 제거 M3 / M2 | E1, FE-GATE-020 | P — 예제 셋은 기능으로 빠진다. 플랫폼 구성 화면은 빠지지 않는다. 브라우저 spec 8개를 제거 드릴이 보지 않고, 예제 제거 드릴은 게이트 밖이다(0925 FOLLOW-UP 09-07 일부, 1105/14-01) |
|
||||
| 28 | 회복 가능성 | 적용 | 세션·부트 회복 M2 / M2 | E2(FE-GATE-006 `session-recovery` 4 tests, FE-GATE-007) | O — 쿠키 세션 만료 뒤 세션이 `unauthenticated`가 되어 로그인으로 돌아간다(1105/09-02). `no-session` 뒤 로그인 버튼(1103/09-11) 그대로 |
|
||||
|
||||
집계(판정한 24개): 충족 9(1, 8, 10, 13, 15, 19, 22, 25, 28) · 부분 충족 15 · 미충족 0 · 미검증 0. 10은 배치 변이 결과(09-R1~R3)로 확정했다. 적용 제외 1(16), 다른 영역 3(14, 18, 26). 지난 라운드(충족 1)보다 늘어난 것은 1105/09-01·09-02가 닫혔기 때문이다. 12는 지난 라운드 실험을 현재 증거로 쓰지 않아 증거를 E1로 낮췄다.
|
||||
|
||||
## 5. 미검증
|
||||
|
||||
| 항목 | 이유 | 확인하려면 |
|
||||
|---|---|---|
|
||||
| 짝 백엔드에 실제로 붙인 로그인·401 | Keycloak·Redis·백엔드를 띄우지 않았다. pin realm에 public client가 없다 | 백엔드 local + Keycloak에 public client를 더하고 OIDC recipe로 `EXTERNAL_BEARER` 1회. Redis 모드에 세션 엔드포인트를 더하고 쿠키 owner로 쓰기 1회, 세션 삭제 뒤 401 1회 |
|
||||
| 다운스트림(tech-log, memento)에 이 절을 넣은 결과 | 두 제품은 v0.2.0 동기화 지점이다. 이 절과 아래 1103 절을 적용해 보지 않았다(`CHANGELOG.md:20`) | 동기화 브랜치에서 `check:types`(16-05 손 ID), `test:unit`(탐침) |
|
||||
| 실행기 반환과 401 알림 사이의 계정 전환 | 지난 라운드의 재현(admission 중 전환)은 이전 커밋 증거다. 반환 뒤 한 microtask 안의 전환은 아무도 만들지 않았다 | `contractHttp.execute`를 감싼 테스트에서 resolve 직전 subject를 바꾼다 |
|
||||
| 예제 기능을 뺀 제품의 브라우저 게이트 | 무거운 실행이다(FE-GATE-008). 정적으로 spec 8개를 셌다 | `VITE_PRODUCT_FEATURES`에서 예제 기능을 빼고 `test:e2e`·`test:visual` |
|
||||
| 앱 id를 바꾼 제품에서 탐침 | 해당 다운스트림이 없다 | 사본에서 `APP_MODULE_ID`를 바꾸고 `product-extension-typecheck.test.ts` |
|
||||
|
||||
## 6. 실행 기록
|
||||
|
||||
노트북과 desktop 어디서도 직접 실행하지 않았다. 아래 셋은 오케스트레이터 배치가 돌렸다. 요청 파일은 `scratchpad/r5/requests/09.md`, 변이 patch는 `09-R1.diff`~`09-R3.diff`다. 모두 `bbde570`에 `git apply --check`로 붙었다. 배치는 `bbde570`(`ref=bbde5707`, env local, 부하 2.8대)에서 한 항목씩 돌리고 항목마다 checkout을 되돌렸다(`restore=clean`). 로그는 `desktop:/tmp/claude-gates/r5/batch/out/R5-09-R{1,2,3}.log`다.
|
||||
|
||||
| ID | 명령 | 변이 | rc | 결과 |
|
||||
|---|---|---|---|---|
|
||||
| 09-R1 | `node scripts/run-vitest.ts run tests/unit/product-extension-typecheck.test.ts` · local | 탐침 `composeProduct`가 `...product.capabilities`를 펼치지 않음(`tests/unit/product-extension-typecheck.test.ts:138` 삭제) | 1 | 1 failed / 1 passed, 6.34 s. 실패는 "1105/09-01 … passes when a product feature needs a product capability"(`:320` → `:299`의 `expect(…).toBe("")`)이다. 출력은 `…/src/bootstrap/runtime-adapters.ts(736,5): error TS2741: Property 'typecheckProbeDownstreamSettings' is missing in type 'Readonly<{ typecheckProbeSettings: …; http: …; telemetry: TelemetryPipeline; }>' but required in type 'InstalledFeatureCapabilityContext'`다. "1103/09-02 … passes the app, node and test programs"는 통과했다. 기대와 같다. 대조군은 FE-GATE-005 `:172`(2 tests 통과) |
|
||||
| 09-R2 | `node scripts/run-vitest.ts run tests/recipes/session-owners-runtime.test.ts` · local | `src/bootstrap/runtime-adapters.ts:705`를 `notifySessionUnauthenticated: () => {}`로 | 1 | 2 failed / 4 passed, 3.14 s. "signs out when the server answers a cookie read with 401"과 "… cookie write with 401"이 `:434`에서 `AssertionError: expected 'authenticated' to be 'unauthenticated'`로 실패했다. OIDC 두 건과 쿠키 부팅·no-session 두 건은 통과했다. 기대와 같다. 대조군은 FE-GATE-007 `:104`(6 tests 통과) |
|
||||
| 09-R3 | `node scripts/run-vitest.ts run tests/component/runtime-composition-service-worker-product-wiring.test.ts` · local | `src/bootstrap/create-runtime-composition.ts:61` 삭제 | 1 | 1 failed, 1.29 s. "passes the product's blockers and observer to the page controller"가 `:147`에서 `expected [] to deeply equal [ { event: 'register', …(1) } ]`로 실패했다(`register`는 1회 불렸다, `:146` 통과). 기대와 같다. 대조군은 FE-GATE-006 `:68`(1 test 통과) |
|
||||
|
||||
세 변이 모두 "변이 없는 명령은 통과(게이트 로그), 변이는 기대한 테스트에서 기대한 이유로 실패"를 채운다. 1105/09-01·09-02와 1103/09-05의 고친 부분은 현재 커밋의 테스트가 지킨다.
|
||||
|
||||
인용한 게이트 결과(`desktop:/tmp/claude-gates/bbde570-ci/`, CI env, 2026-11-06 03:24~03:56):
|
||||
|
||||
- FE-GATE-003 typecheck PASS. 1103/16-05의 `@ts-expect-error`가 쓰였다는 증거다.
|
||||
- FE-GATE-005 rc=0. `test:unit` 208 files / 3,056 tests. 이 영역의 `product-extension-typecheck`(2), `runtime-adapters-product-scope-participants`(4), `runtime-adapters-auth-profile`(16), `runtime-adapters-credential-order`(10), `runtime-adapters`(22), `product-composition-fixture`(13), `product-session-owner-context`(12), `command-mutation-identity`(5), `registry-governance`(12)가 들어 있다.
|
||||
- FE-GATE-006 rc=0. `test:component` 41 files / 278 tests. `runtime-composition-service-worker-product-wiring`(1), `session-recovery`(4) 포함.
|
||||
- FE-GATE-007 rc=0. `test:recipes` 7 files / 80 tests. `session-owners-runtime`(6), `cookie-session-owner`(17), `oidc-pkce-session-owner`(32) 포함.
|
||||
- FE-GATE-020 rc=0(1,237 s). 제거·생성 드릴 사본에서 탐침 2 tests가 8번 통과.
|
||||
- FE-GATE-013 rc=1은 user namespace 전제 때문이고 이 영역 테스트를 돌리는 게이트가 아니다.
|
||||
- 모두 템플릿 출하 상태다. 다운스트림 상태는 탐침의 다운스트림 케이스와 recipe 런타임 테스트가 흉내 낸 범위까지만 본다.
|
||||
|
||||
## 7. 새 발견 요약
|
||||
|
||||
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|
||||
|---|---|---|---|---|
|
||||
| 09-01 | Low·P3 | 확인된 결함 | 1103/16-05 이행 안내가 HTTP descriptor 없는 뮤테이션(Fileserver 업로드 등)과 테스트 fixture의 길을 말하지 않고, 매뉴얼 01이 손 ID의 실패 시점을 두 가지로 적는다 | `CHANGELOG.md:25`; `docs/manual/01-add-a-feature.md:476`, `:499-500`; `src/contracts/server-state.ts:294-313`; `tests/helpers/mutation-operation-id.ts:11-15` |
|
||||
@@ -0,0 +1,248 @@
|
||||
# 영역 10 — 테스트: 빠른 계층
|
||||
|
||||
> 검토일 2026-11-06 · 기준 `bbde570`(`bbde570796b0a648bae65c2c0568fca860a3ba4e`, PR B 끝) · 지난 문서: `docs/reviews/2026-11-05-maturity-review/10-tests-fast-layers.md`(기준 `8a44226`)
|
||||
> 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
|
||||
> 경로: `tests/unit`, `tests/component`, `tests/integration`, `tests/contract`, `tests/runtime-schema`, `tests/features`, `tests/platform`, `tests/recipes`, `tests/helpers`, `tests/mocks`, `tests/support`(`tests/support/browser` 제외, 11 영역), `tests/scripts`. 설정: `vitest.config.ts`, `tests/setup.ts`, `scripts/run-vitest.ts`, `scripts/lib/no-skipped-tests-reporter.ts`, 제거 드릴이 테스트를 고르는 `scripts/lib/removal-fixture.ts`
|
||||
> 깊게 본 관점: 10 테스트, 21 Guardrail, 27 삭제 가능성, 14 성능(테스트 비용)
|
||||
> 렌즈: (1) 지난 발견의 완료 기준이 지금 코드에서 맞는가. (2) `8a44226..bbde570`의 테스트 변경, 특히 README §16.3의 통합 수정이 검사를 좁혔는가. (3) 커버리지 숫자가 지난 라운드와 어떻게 다른가.
|
||||
> 영역 판정(35.8): **지정 범위에서 사용 가능** — 템플릿 상태의 머지 게이트로 쓴다. 새 발견 둘은 드릴 사본과 파일 이름 변경에서만 닿는 검출 공백이다.
|
||||
|
||||
## 0. 결론
|
||||
|
||||
- **지난 발견 13건(제안 1105/10-03 제외): 고쳐짐 4 · 일부 1 · 남음 8 · 재발 0 · 틀린 발견 0.** 남음 8건 중 셋(1101/10-05·10-06·10-08)은 §16.6의 결정 대기다. 다섯은 ID 없는 작은 이월이다.
|
||||
- **네 라운드 살아남은 §10.8 마지막 검사(0929/10-04, 변이 L01)에 이제 테스트가 있다.** scope signal은 그대로 두고 `isCurrent`만 false로 바꾼다(`tests/unit/http-execution-v3.test.ts:574-620`). 그래서 앞 단계 abort가 먼저 답하지 않는다. 1105/10-02(interaction signal listener)와 1105/10-01(샘플 밖 플랫폼 규칙 테스트)도 고쳐졌다. 완료 기준의 변이 넷(H53, L02, R2b, L01)을 넣자 넷 모두 예상한 테스트가 예상한 이유로 실패했다(10-R1~10-R4, rc=1, restore clean). 무변이 통과는 FE-GATE-005 로그가 보인다.
|
||||
- **1101/10-07은 "고침"이 아니라 일부다(§16.6과 다르게 판정).** SW 5초 대기는 8 ms가 됐다(`unit.xml`). RPC 쪽은 느린 4개 중 1개만 고쳤다. 수정은 이미 30 ms이던 3개에 시계를 넣었다. 1초를 실제로 자는 3개(`browser-rpc-remediation.test.ts:389`, `:412`, `:588`)는 지금도 1.03~1.07 s다.
|
||||
- **README §16.3의 통합 수정 셋이 검사를 좁혔다.** 새 10-01: 두 테스트가 "대상 파일이 있으면"으로 검사를 정한다. browser-file-storage 드릴 사본에서 `playwright-run-isolation.test.ts`가 33개에서 25개로 줄었는데 skip 보고가 없다. 템플릿에서 파일 이름이 바뀌어도 같다. 새 10-02: 문서를 읽는 테스트 하나 때문에 `backend-contract-pin.test.ts`가 파일째 capability 드릴 셋에서 빠졌다. 문서와 무관한 14개(그중 10개는 `8a44226`에서 그 드릴들에서 돌았다)와 `feature-tracked-files.test.ts`의 1개가 그 드릴에서 돌지 않는다.
|
||||
- **나머지 diff에서는 약하게 만든 검사를 찾지 못했다.** 새 `skip`·`todo`·`only`는 없다. 기존 테스트의 시간 한도는 오르지 않았다. 바뀐 기대값은 수정이 동작을 바꾼 자리다(3.0절).
|
||||
- **새 발견 2건, 모두 Low·P3, 구조적 위험이다.**
|
||||
- **커버리지는 네 지표 모두 0.2%p 올랐다.** lines 86.31 → 86.51%, branches 80.92 → 81.15%. 위험 하한 72개는 값이 그대로이고 모두 통과다(418/418 모듈). 줄어든 파일 7개는 모두 그 파일의 코드나 타입이 바뀐 곳이다(6.2절 C1).
|
||||
- **비용 쪽 이월은 더 커졌다.** `tests/unit` 테스트 시간 합이 133.1 s → 175.7 s(CI env, +32%)다. `scripts`만 보는 파일과 import 없는 파일이 그중 76%다(지난 71%). 한 머지에 `tests/unit`이 13번 도는 것은 그대로다. FE-GATE-020은 1,156 s → 1,237 s다.
|
||||
|
||||
## 1. 범위 (36.1)
|
||||
|
||||
| 항목 | 기록 |
|
||||
|---|---|
|
||||
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`. 테스트 파일(unit.xml·coverage.xml 기준): `tests/unit` 208(지난 194), 커버리지 실행 332(316). 새 파일 15개는 모두 `tests/unit`이다(`git diff --name-status 8a44226 bbde570 -- tests`). 지운 테스트 파일은 없다 |
|
||||
| 커밋·작업 상태·확인 시점 | `bbde570`. 노트북 worktree(HEAD = 기준)에서 읽기만 했다. 실행은 오케스트레이터 배치가 desktop checkout에서 했다(2026-11-06 04:34, 항목마다 `head bbde5707…` 확인, 끝나면 `restore=clean`). 확인 2026-11-06 04:00~04:45 |
|
||||
| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. Vitest 4.1.12(FE-GATE-005 로그 머리) |
|
||||
| 필수 요구와 규모·운영 목표 | 빠른 계층은 머지 게이트다: FE-GATE-004(runtime-schema), 005(unit·contract·coverage·scale pr), 006(component), 007(integration·HTTP 시나리오·reference-feature·recipes), 020(제거·생성 드릴 안에서 다시). 러너 사양과 허용 실패율은 정해져 있지 않다(U-1) |
|
||||
| 읽은 코드·구성 범위 | `git diff 8a44226 bbde570`의 영역 경로 68파일(+5,267 / −271), 영역 경로를 건드린 72커밋. 지난 발견의 수정 커밋 `00b12b3`, `dae44f5`, `c842bac`, `7ead8d3`, `ce191be` 전체. 통합 수정 `f4d5761`, `0e72c0c`, `c9aa73f`, `5c0b37e`·`6d084cf`의 영역 쪽. 제거 드릴: `scripts/lib/removal-fixture.ts`, `scripts/test-sample-removal.ts`, `scripts/test-browser-file-storage-runtime-removal.ts`, `scripts/lib/removable-template-features.ts`. 변이 대상: `src/bootstrap/runtime-adapters.ts:284-319`, `:538`, `src/presentation/routes/navigation-policy.ts:29-43`, `src/adapters/http/http-execution-v3.ts:620-667`, `:1493-1499`, `src/adapters/browser-rpc/browser-rpc-runtime.ts:895-916` |
|
||||
| 읽은 문서(주장으로만) | 지난 영역 문서, 지난 README §15·§16, 0929·1101 영역 10 문서의 해당 발견, 수정 커밋 본문 |
|
||||
| 수행한 테스트·실험 | 직접 실행 없음. 증거는 desktop 로그와 snapshot이다: `desktop:/tmp/claude-gates/bbde570-ci/summary.txt`, `gate-artifacts/FE-GATE-004·005·006·007·020.txt`(merge 단계, CI env, 2026-11-06 03:24~03:56), `desktop:/tmp/claude-gates/r5/snap/merge/artifacts/tests/*.xml`·`coverage/coverage-summary.json`·`artifacts/quality/risk-coverage.json`(모두 03:46~03:48, MTIMES.txt 확인). 비교용 지난 값: `desktop:/tmp/claude-gates/r4/snap/artifacts/tests/{unit.xml,coverage.xml,coverage/coverage-summary.json}`, `artifacts/quality/risk-coverage.json`(2026-11-05 19:51~19:52, merge-48 FE-GATE-005). 변이 4건 **10-R1~10-R4**(`desktop:/tmp/claude-gates/r5/batch/out/R5-10-R1.log`~`R4.log`, local env, 모두 기대대로 실패). 노트북에서 로그 사본을 분류했다(6.2절) |
|
||||
| 확인하지 못한 범위·이유 | 실제 Gitea 러너(U-1). 샘플을 지운 사본에서 조립 루트 `:538`을 바꾸는 변이(비용, 5절). 브라우저 계층(11 영역) |
|
||||
| 이전 리뷰와 비교 가능한 범위 | 지난 실행 결과는 현재 증거로 쓰지 않았다. 숫자 비교(커버리지, 파일별 시간, 테스트 이름)는 같은 CI env의 merge 단계 산출물끼리 했다. 지난 문서의 J1(로컬 env)과는 env가 달라 J1을 지난 merge-48 unit.xml로 다시 셌다(6.2절) |
|
||||
|
||||
### 1.1 게이트 결과 (merge 단계, CI env, `bbde570`, 인용)
|
||||
|
||||
`summary.txt`: FE-GATE-004 rc=0(2 s), 005 rc=0(132 s), 006 rc=0(10 s), 007 rc=0(28 s), 020 rc=0(1,237 s).
|
||||
|
||||
- FE-GATE-004: `test:runtime-schema` 3파일 60개(`FE-GATE-004.txt`).
|
||||
- FE-GATE-005: `test:unit` 208파일 3,056개, Duration 28.45 s(setup 50.73 s, tests 175.74 s)(`FE-GATE-005.txt:312-315`). `test:contract` 3파일 24개. `test:coverage` 332파일 통과(`:781`), `All files 84.23 | 81.15 | 90.63 | 86.51`(`:791`), `Risk coverage: PASS (418/418 production modules, 72 thresholds)`(`:1297`).
|
||||
- FE-GATE-006: `test:component` 41파일 278개.
|
||||
- FE-GATE-007: `test:integration` 11파일 212개, `test:reference-feature` 18파일 101개, `test:recipes` 7파일 80개.
|
||||
- FE-GATE-020: 아래 드릴마다 `tests/unit`이 통과했다(파일 수): 샘플 제거 두 단계 204·204, 생성 기능 208, 생성 기능 제거 205, 선택 레시피 제거 201, browser-file-storage 제거 166, realtime 제거 180(`FE-GATE-020.txt:322`, `:1855`, `:4799`, `:6625`, `:10096`, `:10974`, `:11885`).
|
||||
- 어느 junit에도 `skipped`가 1 이상인 suite가 없다.
|
||||
|
||||
## 2. 지난 발견 재확인
|
||||
|
||||
| 지난 ID | 내용 | 상태 | 근거 |
|
||||
|---|---|---|---|
|
||||
| 1105/10-01 | 1103 수정이 더한 플랫폼 규칙 테스트 둘(`MAX_RETRY_ATTEMPTS` 전달, 복구 중 세션 대기)이 참조 샘플에 기대어, 샘플을 지우면 함께 사라진다 | **고쳐짐** | `00b12b3`. ① 실행기를 만드는 부분을 `createRuntimeContractHttpExecutor`로 뺐다(`src/bootstrap/runtime-adapters.ts:284-319`). 조립 루트는 이 함수로만 만든다(`:538`, `src` 안 `createContractHttpExecutor(` 호출은 `:305` 하나). 완료 기준의 H53 자리(옛 `:502` `maxRetryAttempts: config.MAX_RETRY_ATTEMPTS`)는 지금 `:307`이다. 테스트 계약으로 0·1·2 → 1·2·3번을 단언한다(`tests/unit/runtime-adapters.test.ts:505-595`). 10-R1(`:307` → 상수 2): "honours MAX_RETRY_ATTEMPTS 0 / 1" 2건이 "expected to be called 1 / 2 times, but got 3 times"로 실패, 22개 중 20개 통과. ② L02 자리(`navigation-policy.ts:40`)는 fixture 기능의 보호 라우트로 본다(`tests/unit/session-route-access.test.ts:13-23`, `:32-41`). 10-R2(`:40` → `show-sign-in`): "answers a recovery-pending session with { allowed: false, action: 'wait-for-session' }" 1건 실패, 6개 중 5개 통과. ③ 두 파일은 샘플 제거 드릴의 공통 테스트 목록에 있다(`scripts/test-sample-removal.ts:133-140`). 샘플을 지운 사본의 `test:unit`에서 실제로 돌았다: `runtime-adapters.test.ts` 22개, `session-route-access.test.ts` 6개(`FE-GATE-020.txt:133`, `:311`; 그 실행의 junit 경로가 `.tmp/reference-feature-removal-*/`, `:327`). 남은 것: 조립 루트의 한 단계(`:538`이 `config`를 그대로 넘김)는 샘플 사본에서 지키는 테스트가 없다. 수정 커밋이 한계로 적었고 지난 문서 ⓐ안이 남긴 범위라 발견으로 세지 않는다(5절) |
|
||||
| 1105/10-02 | interaction signal에 단 abort listener 정리는 지워도 모든 테스트가 통과한다 | **고쳐짐** | `dae44f5`. 같은 테스트가 `createExecutionContext`로 만든 interaction을 넘기고 그 `cancellation.signal`도 감시한다(`tests/unit/http-execution-v3.test.ts:812-867`). 끝나는 경우에 "interaction cancel"을 더했다(`:816`, `:852`). 10-R3(R2b, `http-execution-v3.ts:663` 삭제): "removes the listeners … after an answer / a caller abort / an interaction cancel" 3건이 `expected [] to deeply equal [ [Function forwardCallerToLifetime] ]`(`:865`)로 실패, 72개 중 69개 통과. 완료 기준 충족 |
|
||||
| 1105/10-03 | 판정 규칙의 변이 실험을 손으로 만든다(변이 도구 제안) | 제안 — 세지 않음 | BRIEF §7. 오케스트레이터가 기록한다 |
|
||||
| 0929/10-04 | §10.8 마지막 검사(오래된 scope의 성공 응답 버림) 미고정 | **고쳐짐** | `c842bac`. fetch 안에서 `isCurrent`만 false로 바꾸고 signal은 abort하지 않는다(`tests/unit/http-execution-v3.test.ts:574-620`). JSON 성공 경로에서 dispatch 뒤 scope를 보는 곳은 `http-execution-v3.ts:1494` 하나다(다른 `isCurrent` 자리 `:1344`, `:1399`는 빈 본문 경로, `:932`·`:1009`는 dispatch 전). 10-R4(L01, `:1494` → `false`): "discards a valid read / command success that arrives after its scope stopped being current" 2건이 `expected { kind: 'SUCCESS', … } to match object { kind: 'CONTRACT_VIOLATION', … }`(`:614-618`)로 실패, 72개 중 70개 통과. 0929 완료 기준("변이 K를 넣으면 새 테스트가 실패한다") 충족. 네 라운드 만에 닫혔다 |
|
||||
| 0929/10-05 | `test:all`이 CI 빠른 테스트 일부를 빠뜨림 | **고쳐짐** | `7ead8d3`. `test:all`이 `tests/features`, `tests/scripts`, `tests/scale/browser-soak.contract.test.ts`를 함께 돈다(`package.json:85`). `test:coverage`의 경로(`:83`) 중 `tests/release`·`tests/platform/release`는 `check:release-coherence`(`:153`)가, `tests/platform tests/architecture`는 `test:platform`(`:141`)이 돈다. `tests/unit/test-all-paths.test.ts:20-31`이 두 스크립트 그래프의 Vitest 경로를 비교한다. FE-GATE-005의 `test:unit`에서 통과했다 |
|
||||
| 1101/10-07 | 프로덕션 시간 상수를 실제 시계로 기다림(5개 테스트) | **일부** (§16.6 "고침"과 다름) | `ce191be`. SW: "bounds a stream that never produces a chunk"가 5.03 s → 8.2 ms(`unit.xml`, 지난 merge-48 unit.xml과 비교). 파일 시간 5.21 s → 0.32 s. RPC: 1101 문서는 1초를 자는 4개를 말한다(예 `:579`는 `d99301b`에서 "admits a second stream once waitClosed fulfils" 안이다). `8a44226` junit에서 1 s를 넘는 RPC 테스트는 "cancels the physical stream exactly once after a timeout" 1.03 s, "refuses a second stream while the first has not confirmed closure" 1.08 s, "admits a second stream once waitClosed fulfils" 1.07 s, "keeps the operation DRAINING when waitClosed never settles" 1.03 s다. 수정은 "keeps the operation DRAINING when waitClosed …" 4개에 `cappedClock`을 넘겼다(`browser-rpc-remediation.test.ts:544-566`). 그중 3개(rejects, throws, non-promise)는 이미 28~34 ms였다. 지금 `bbde570` junit: never settles 59 ms로 내려갔다. 나머지 셋은 1,033 ms, 1,068 ms, 1,068 ms다(`:389`, `:412`, `:588`, 시계를 넘기지 않음). 완료 기준("5개 테스트가 각각 100 ms 아래") 중 2개만 충족했다. 남은 부분 Low·P3 |
|
||||
| 1101/10-05 | `tests/unit`에 도구 테스트가 섞여 시간 대부분을 씀 | **남음(결정 대기)** — 커짐 | J1(6.2절, CI env): `scripts`만 59파일 100.1 s(57%), import 없음 17파일 32.5 s(19%). 합 76%(지난 merge-48: 51파일 54% + 14파일 17% = 71%). 늘어난 곳: `product-extension-typecheck.test.ts` 11.3 → 22.0 s(09-01이 두 번째 복사·tsc 테스트를 더함), `documentation-readiness.test.ts` 16.6 → 22.5 s, 새 파일 `template-feature-removal-documents.test.ts` 7.3 s, `run-output-root-build.test.ts` 6.9 s, `manual-paired-backend-settings.test.ts` 4.1 s. 저장소 사본을 만들고 tsc나 문서 검사를 도는 테스트가 셋 늘었다 |
|
||||
| 1101/10-06 | 머지 단계가 빠른 계층을 여러 번 돌림 | **남음(결정 대기)** | 다시 셌다(6.2절 D2). FE-GATE-005에서 2번, FE-GATE-020에서 11번(샘플 제거 4, 생성 기능 2, 생성 기능 제거 2, capability 드릴 3). 합 13번으로 지난과 같다. 0929/10-05 수정으로 드릴 안의 `test:all` 6번이 이제 `tests/features`·`tests/scripts`도 돈다(`7ead8d3` 본문이 적은 대로). FE-GATE-020 1,156 s(merge-48) → 1,237 s |
|
||||
| 1101/10-08 | `scopeSnapshot` 갈라진 복사본 | **남음(결정 대기)** | 공유 도우미 두 곳(`tests/helpers/traffic-test-kit.ts:13`, `tests/component/application-query-fixture.tsx:20`) 밖에 4개 파일이 각자 정의한다(`tests/features/reference-feature/reference-diagnostics.test.ts:7`, `tests/integration/http-execution-v3-auth-profile.test.ts:41`, `-live-authority.test.ts:23`, `-observability.test.ts:24`). `identities: Object.freeze({}) as never` 10곳. `deferred()` 7벌. 새 테스트는 공유 도우미를 썼다(`runtime-adapters.test.ts`의 `scopeSnapshot` import) |
|
||||
| (지난 2절) `test:platform`만 `--no-file-parallelism`, 이유 없음 | | **남음** | `package.json:141` |
|
||||
| (지난 2절) `--passWithNoTests` 3곳 | | **남음** | `package.json:50`, `:58`, `:81` |
|
||||
| (지난 R1) 전역 setup이 DOM 없는 unit에도 RTL을 읽음 | | **남음** | `tests/setup.ts:1-2`. unit setup 누적 50.73 s(CI env, `FE-GATE-005.txt:315`) |
|
||||
| (지난 R6) `typescript-tooling-smoke` 두 파일 | | **남음** | `tests/unit/typescript-tooling-smoke.test.ts`, `tests/component/typescript-tooling-smoke.test.tsx` |
|
||||
| (지난 2절 21) `tsc-diagnostics-parser.test.ts` 제외 사유 | | **남음 — 12 영역** | `config/ci/ungated-tests.json:25`. 파일이 바뀌지 않았다 |
|
||||
|
||||
1103 이월(§16.5)에는 이 영역 행이 없다. 1103/10-01~10-04는 지난 라운드에 모두 고쳐졌다. 틀린 발견으로 판정한 지난 항목은 없다. §16.4·§16.6과 다르게 판정한 것은 1101/10-07 하나다.
|
||||
|
||||
## 3. 이번 발견 (36.3)
|
||||
|
||||
새 발견 2건 — 심각도 Low 2 · 우선순위 P3 2 · 성격 구조적 위험 2. High 이상과 P1은 없다.
|
||||
|
||||
### 3.0 검사를 약하게 했는지 (`git diff 8a44226 bbde570 -- <영역 경로>`)
|
||||
|
||||
- 지운 테스트 파일은 없다.
|
||||
- 더한 줄에 `it.skip`·`todo`·`only`·`skipIf`·`runIf`·`context.skip()`가 없다(`git diff` 추가 줄 검색 0건).
|
||||
- `vitest.config.ts`(`:38` `allowOnly: false`, `:40` `restoreMocks`), `tests/setup.ts`, `scripts/run-vitest.ts:62-72`(skip reporter 추가), `scripts/lib/no-skipped-tests-reporter.ts`, `config/ci/ungated-tests.json`, `config/testing/risk-coverage.json`은 바뀌지 않았다(diff 비어 있음).
|
||||
- 커버리지 실행의 테스트 이름 중 지난 merge-48에 있고 지금 없는 것은 7개다. 모두 같은 파일에서 이름이 바뀌었거나 같은 규칙의 새 행으로 바뀌었다(6.2절 T1).
|
||||
- 조건부 정의·제외 목록을 찾으려고 더한 줄의 `existsSync`를 모두 봤다. 5파일이다. 셋(`manual-paired-backend-settings.test.ts`, `product-extension-typecheck.test.ts`, `template-feature-removal-documents.test.ts`)은 사본을 만들 때 없는 대상을 건너뛰는 데만 쓴다. 단언 대상은 줄지 않는다. 둘이 아래 10-01이다.
|
||||
|
||||
| 커밋 | 바뀐 것 | 판정 |
|
||||
|---|---|---|
|
||||
| `f4d5761`·`0e72c0c`(12-04에 접음) | capabilities 설정 검사 8개를 파일이 있을 때만 정의(`playwright-run-isolation.test.ts:27-44`, `:243-252`) | **약화 → 새 10-01** |
|
||||
| `c9aa73f`(15-03에 접음) | 목록 하나 검사의 소비자를 `existsSync`로 거름(`vite-build-inputs.test.ts:19-22`) | **약화 → 새 10-01** |
|
||||
| `5c0b37e`(03-01)·`6d084cf`(16-01)에 접음 | 문서 테스트 목록에 파일 둘을 통째로 더함(`removal-fixture.ts:73-76`). 목록 검사 정규식에 `docs\/`를 더함(`removal-fixture.test.ts:161`) | **약화 → 새 10-02** |
|
||||
| 14-01·14-02 | 같은 목록에 `template-feature-removal-documents.test.ts`, `manual-paired-backend-settings.test.ts`를 더함(`removal-fixture.ts:77-80`) | 약화 아님. 두 파일의 모든 테스트가 문서를 읽는다 |
|
||||
| `ce191be`(1101/10-07) | SW 테스트를 가짜 시계로. 5 s씩 최대 4번 넘긴다(`service-worker-runtime.test.ts:2006-2040`). 옛 테스트는 실제 시계와 10 s 제한이라 마감이 약 10 s를 넘으면 실패했다. 새 테스트는 마감 20 s까지 통과한다 | 약화로 세지 않음. 어느 쪽도 5,000 값을 고정하지 않았다. 10 s 상한은 테스트 제한에서 온 우연이다. "마감이 있다"는 규칙은 그대로 잡는다(마감이 없으면 `settled`가 false). 이 fixture는 마커를 한 번만 읽어서(현재 캐시 하나, `:1950-1953`) 반복 4는 필요 없다 |
|
||||
| `ce191be` | RPC "keeps the operation DRAINING …" 4개에 모든 대기를 30 ms로 자르는 시계를 넘김(`browser-rpc-remediation.test.ts:544-566`) | 약화 아님. 작업 자체 마감 25 ms(`:386-387`)는 그 아래다. DRAINING 단언은 시간과 무관하다. 다만 대상을 잘못 골랐다(2절 1101/10-07 일부) |
|
||||
| `46359a1`(15-02) | 기록 대조 허용 오차 1% → 256 B. 기대값: 201,500 B가 이제 실패(`feature-shape-growth.test.ts:168-199`) | 강화 |
|
||||
| `287dc6f`(D7) | 초기 JS 예산 200 → 202 KiB(`config/performance/budgets.json`). 테스트는 주석만 바뀜(`feature-shape-growth.test.ts:131`) | > 15 영역 몫 |
|
||||
| `6608fef`·`471b001`(01-01·01-02) | Fileserver 503 `IDEMPOTENCY_UNAVAILABLE` 기대: `NOT_APPLIED`·retryable true → `MAYBE_APPLIED`·false | 약화 아님. 수정이 판정을 더 조심스럽게 바꿨다 |
|
||||
| `05330e3`(04-02) | 던지는 poll `execute`: `PROVIDER_UNAVAILABLE` 재시도 → 즉시 `PROTOCOL_MISMATCH`(`bounded-poll-coordinator.test.ts:911-960`) | 약화 아님. 동작 변경. 동기·비동기 던짐 두 행으로 늘었다 |
|
||||
| `8e9fb1f`(02-02) | 읽히지 않는 캐시 본문: stage가 fetch 없이 실패 → 다시 받아 씀(`public-response-cache-repair.test.ts:180-233`) | 약화 아님. 동작 변경. 새 describe가 같은 규칙을 더 본다 |
|
||||
| `23662fb`(1103/05-01) | 계정 삭제 purge 기대: `chunkSweep: "COMPLETED"` → `partitionDeleted: true` + `chunkSweep` 없음 | 약화 아님. 단언이 늘었다 |
|
||||
| `92d5019`(13-02) | 템플릿 workflow 동일성 비교 전에 release `needs` 한 줄만 바꿔 비교(`product-ci-overlay.test.ts:148-152`) | 약화 아님. 바꾼 줄을 따로 단언하는 새 테스트가 있다 |
|
||||
| `48c1ab7`(1103/16-05) | 테스트의 `operationId` 문자열 → `testMutationOperationId()`(`tests/helpers/mutation-operation-id.ts`) | 약화 아님. 형 변환이 아니라 운영 함수 `commandMutationIdentity`로 만든다 |
|
||||
| `dc7c95b`(05-01) | FE-REG-STORAGE `orphanExemptRows`에 한 행 추가(`config/contracts/registry-governance.json:376`) | 판정 안 함. 05·07 영역 몫 |
|
||||
| 새 테스트의 시간 제한 | 120 s(`manual-paired-backend-settings`, `product-extension-typecheck`의 두 번째), 180 s(`run-output-root-build`), 60 s·120 s(`template-feature-removal-documents`) | 새 테스트의 것이다. 기존 한도를 올린 곳은 없다 |
|
||||
|
||||
### 10-01 제거 드릴을 통과시키려고 새 테스트 둘이 검사 대상을 "파일이 있으면"으로 정했다. 템플릿에서 파일 이름이 바뀌어도 검사가 조용히 빠지고, skip 차단은 이를 보지 못한다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 구조적 위험(검출 공백) |
|
||||
| 관련 관점 | 10, 21, 27, 23, 5, 24 |
|
||||
| 근거 | ① `tests/unit/playwright-run-isolation.test.ts:27-28`이 `HAS_CAPABILITIES = existsSync("playwright.capabilities.config.ts")`를 둔다. `installed()`(`:41-43`)가 이 값으로 capabilities를 목록에서 뺀다. 그래서 파일이 없으면 결과 폴더 2개(`:135-157`), dev cache 1개(`:175-183`), 포트 3개(`:204-231`), strictPort 1개(`:234-241`), 공유 포트 1개(`:245-252`)가 정의되지 않는다. `:243-244` 주석은 "skip이 아니라 정의하지 않는다. test:unit이 skip을 실패시킨다"고 적는다. ② 실행: browser-file-storage 드릴은 이 설정 파일을 지운다(`scripts/test-browser-file-storage-runtime-removal.ts:134`). 그 사본에서 이 파일은 25개로 통과했다(`FE-GATE-020.txt:10802`). 템플릿과 다른 드릴에서는 33개다(`:114`, `:9910`, `:11721`). 8개가 사라졌는데 skip 보고는 없다. 드릴 요약은 import 그래프로 지운 테스트만 센다(`:11291`, `test-browser-file-storage-runtime-removal.ts:200`). ③ `tests/unit/vite-build-inputs.test.ts:19-22`가 소비자 둘을 `existsSync`로 거른다. `:49-56`은 남은 소비자만 돈다. 개수 단언이 없어 둘 다 없으면 빈 반복으로 통과한다. 그중 측정 스크립트는 샘플과 함께 지우는 파일로 이미 등록돼 있다(`scripts/lib/removable-template-features.ts:37-39`). `tests/unit/product-feature-selection-build.test.ts`는 어느 제거 목록에도 없는 템플릿 파일인데 같은 조건을 받는다. ④ 같은 드릴들은 사본에서 돌 수 없는 테스트를 이름으로 지우는 방법을 이미 쓴다(`test-browser-file-storage-runtime-removal.ts:148-160`의 `ci-workflow-generation.test.ts`, `scripts/test-sample-removal.ts:218-225`). 두 테스트는 그 대신 템플릿에서도 도는 조건을 넣었다. ⑤ `:244`의 ID가 틀렸다. skip 차단은 1101/10-04다(`95e7d110`, `scripts/lib/no-skipped-tests-reporter.ts:8-17`). `0929/10-04`는 §10.8 마지막 검사 발견이다 |
|
||||
| 발생 조건 | 템플릿이나 제품에서 `playwright.capabilities.config.ts` 또는 `product-feature-selection-build.test.ts`의 이름·위치를 바꿀 때. 다른 참조(`package.json:61`, `scripts/check-test-evidence.ts:384-392`, `scripts/lib/removal-fixture.ts:31`)는 고치고 테스트의 문자열 상수만 놓치면 드러난다. 파일을 아예 지우면 다른 검사가 잡는다(`check-test-evidence.ts:390`의 `readFile`, `test:browser-capabilities`) |
|
||||
| 영향 | 12-04 수정의 완료 기준(한 checkout 두 실행)을 지키는 capability 서버 포트·출력 격리 검사 8개가 사라져도 `test:unit`이 rc=0이고 skip 보고도 없다. ③은 15-03의 "목록 하나" 검사가 이름이 바뀐 소비자를 보지 않아, 그 소비자에 사본 목록이 다시 생겨도 통과한다 |
|
||||
| 심각도·우선순위 | Low · P3 — 지금 템플릿에서는 33개, 2개 소비자가 모두 돈다. 닿는 경로는 이름 바꾸기뿐이다. 그러나 이 저장소가 skip을 막는 이유("남은 skip으로 그 테스트가 지키던 규칙이 조용히 사라진다", `no-skipped-tests-reporter.ts:8-12`)와 같은 결과를 만든다 |
|
||||
| 확실성과 남은 가정 | 사본에서 8개가 사라지는 것은 게이트 로그로 확인했다(E2). 이름 바꾸기 경로는 코드로 판단했다(E1). 이름을 바꾸는 실행은 하지 않았다 |
|
||||
| 결정의 근거 | [확인한 사실] 세 통합 수정은 드릴 사본에서 난 타입 오류·ENOENT를 고치려고 들어갔다(README §16.3, `c9aa73f` 본문). [추론] 조건을 "파일이 있는가"로 둔 것은 드릴 사본과 템플릿을 구분할 정보를 테스트가 읽지 않아서다. 그 정보는 이미 저장소에 있다: 드릴이 지우는 파일(`test-browser-file-storage-runtime-removal.ts:134`), 샘플과 함께 지우는 파일(`removable-template-features.ts:37-39`) |
|
||||
| 이해 비용 | 드릴 사본에서 실패하는 테스트를 맞추는 방법이 셋이다(드릴이 이름으로 지움, 문서 테스트 목록, 테스트 안의 `existsSync`). 고른 기준이 적혀 있지 않다. 테스트 수가 상태마다 다른 것은 로그 세 곳을 맞춰 봐야 안다 |
|
||||
| 최소 개선 방향 | ⓐ 조건을 소유자 상태로 바꾼다. capabilities 검사를 별도 파일(예: `tests/unit/playwright-capabilities-run-isolation.test.ts`)로 옮겨 정적 import를 되살리고, browser-file-storage 드릴이 그 파일을 `ci-workflow-generation.test.ts`처럼 이름으로 지운다. `vite-build-inputs`는 `removable-template-features.ts`로 샘플 설치 여부를 읽어, 설치돼 있으면 측정 스크립트가 있다고 단언하고 템플릿 테스트는 거르지 않는다. ⓑ 지금 구조를 두고, 조건이 거짓이면 드릴 사본인지(드릴이 넘기는 표시)를 단언한다. ⓒ 현 상태를 두고 주석 ID만 1101/10-04로 고친다 |
|
||||
| 대안 비교 | ⓐ 템플릿에서 이름을 바꾸면 import·ENOENT로 실패한다. 드릴은 지운 테스트를 자기 코드에 적는다. 파일 하나가 는다. ⓑ 파일은 그대로지만 드릴과 테스트 사이에 계약이 하나 는다. ⓒ 가장 싸지만 공백이 남는다. [추론] ⓐ를 고른다. 같은 드릴이 이미 쓰는 방식이라 방법이 하나로 준다 |
|
||||
| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다 |
|
||||
| 비용·부작용 | 파일 하나 이동, 드릴 `rm` 한 줄, 테스트 몇 줄 |
|
||||
| 재검토 조건 | capability 설치 여부를 읽는 공용 함수(설치 manifest)가 생기면 그것을 조건으로 쓴다 |
|
||||
| 완료 기준 | 템플릿 사본에서 `playwright.capabilities.config.ts`의 이름을 바꾸면(다른 참조는 고친 상태) `test:unit`이 실패한다. `product-feature-selection-build.test.ts`의 이름을 바꾸면 `vite-build-inputs.test.ts`가 실패한다. 세 capability 드릴과 샘플 제거 드릴은 그대로 통과한다 |
|
||||
| 검증 방법 | 위 두 이름 바꾸기 변이 + `test:browser-file-storage-removal`, `test:sample-removal` |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규(1105 통합 수정 `f4d5761`·`0e72c0c`, `c9aa73f`에서 생김) |
|
||||
|
||||
### 10-02 문서를 읽는 테스트 하나 때문에 파일이 통째로 capability 드릴 셋에서 빠져, 문서와 무관한 테스트 15개도 그 드릴에서 돌지 않는다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 구조적 위험(검출 공백, 제거 상태) |
|
||||
| 관련 관점 | 10, 21, 27, 17, 5 |
|
||||
| 근거 | ① `scripts/lib/removal-fixture.ts:70-81`의 파일은 문서를 복사하지 않는 사본에서 지워진다(`:84-90`, `:160-162`). 단위가 파일이다. 03-01 통합 수정이 `tests/unit/backend-contract-pin.test.ts`(`:73-74`)를, 16-01이 `tests/unit/feature-tracked-files.test.ts`(`:75-76`)를 더했다. ② `backend-contract-pin.test.ts`의 15개 중 문서를 읽는 것은 `:293-303` 하나다(`codesPossiblyAfterWrite`, `:263-275`가 계약 문서를 읽는다). 나머지 14개(`:150-253`)는 pin·답 표 JSON(`:115-140`)과 운영 판정 함수(`envelopeFailureEffect`, `invitesKeyedResend`, `src/adapters/http/backend-envelope.ts`)를 본다. 그중 10개는 `8a44226`에도 있었다(`git show 8a44226:tests/unit/backend-contract-pin.test.ts`의 `:90-140`). 그때 목록은 2파일이라 이 10개가 capability 드릴 셋에서 돌았다. `feature-tracked-files.test.ts`는 3개 중 `:25-30` 하나가 문서를 읽지 않는다. ③ 실행: 샘플 제거와 생성 기능 드릴에서는 `backend-contract-pin.test.ts`가 15개로 돈다(`FE-GATE-020.txt:285`, `:1797`, `:4726`, `:6565`). 선택 레시피·browser-file-storage·realtime 드릴의 unit 실행(`:9815-10096`, `:10731-10974`, `:11626-11885`)에는 목록 6파일이 하나도 없다. ④ 목록을 지키는 검사는 각 파일 본문에 `README.md|CHANGELOG.md|docs/`가 있는지만 본다(`tests/unit/removal-fixture.test.ts:155-163`). 이번에 `docs\/`가 더해졌다(`:161`). `backend-contract-pin.test.ts`는 주석 한 줄(`:259`)로 이 검사를 통과한다. 실제 문서 경로는 JSON에 있다(`config/contracts/backend-contract-pin.json:42`) |
|
||||
| 발생 조건 | capability를 지운 드릴이나 제품에서, 지운 코드가 Envelope 판정·pin이 쓰는 모듈에 닿을 때 |
|
||||
| 영향 | capability 제거 드릴이 증명한다는 "지운 뒤에도 코드가 빌드되고 테스트가 돈다"(`removal-fixture.ts:49-55`)의 범위가 좁아진다. 지금 세 capability는 이 테스트들이 보는 모듈에 닿지 않는다. 그래서 이번에 놓친 결함은 찾지 못했다 |
|
||||
| 심각도·우선순위 | Low · P3 — 템플릿의 `test:unit`과 샘플·생성 드릴은 15개를 모두 돈다. 빠진 범위는 capability 드릴 셋뿐이다 |
|
||||
| 확실성과 남은 가정 | 목록·실행 여부는 코드와 게이트 로그로 확인했다(E1·E2). 빠진 테스트가 capability 제거 뒤에 무엇을 잡았을지는 추론이다 |
|
||||
| 결정의 근거 | [확인한 사실] 목록 단위는 파일이다(`removal-fixture.ts:84-90`). §16.3은 "새 테스트 둘이 계약 문서와 매뉴얼을 읽는다"고만 적는다. [추론] 문서를 읽는 테스트를 기존 파일에 더한 것이 원인이다 |
|
||||
| 이해 비용 | 목록에 파일을 넣는 사람은 그 파일의 나머지 테스트도 드릴에서 빠진다는 것을 목록 주석(`:62-69`)에서 알 수 없다 |
|
||||
| 최소 개선 방향 | ⓐ 문서를 읽는 테스트를 따로 둔다. `backend-contract-pin.test.ts:255-303`을 새 파일(예: `backend-contract-pin-document.test.ts`)로 옮기고 목록에는 그 파일만 둔다. `feature-tracked-files.test.ts:25-30`은 목록 밖 파일로 옮긴다. ⓑ 목록 검사를 `readFile`·`readFileSync` 인자의 문서 경로로 좁혀 주석으로 통과하지 못하게 한다. ⓒ capability 드릴이 그 계약 문서 하나만 복사한다 |
|
||||
| 대안 비교 | ⓐ 원인을 없앤다. 파일이 둘 는다. ⓑ 검사만 정확해지고 빠지는 범위는 그대로다. ⓒ capability 드릴이 문서를 복사하지 않는 이유(`removal-fixture.ts:49-55`)와 어긋난다. [추론] ⓐ를 고르고 ⓑ를 함께 한다 |
|
||||
| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다 |
|
||||
| 비용·부작용 | 파일 분리 2건, 목록 2줄 교체, 정규식 하나 |
|
||||
| 재검토 조건 | capability 드릴이 문서를 복사하게 바뀌면 목록 자체가 필요 없다 |
|
||||
| 완료 기준 | 세 capability 드릴의 unit 실행에 문서를 읽지 않는 pin 테스트 14개가 나온다. 목록의 각 파일은 모든 테스트가 문서를 읽는다 |
|
||||
| 검증 방법 | FE-GATE-020 로그에서 세 드릴의 unit 목록 확인 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규(1105 통합 수정 `5c0b37e`(03-01), `6d084cf`(16-01)에서 생김) |
|
||||
|
||||
## 4. 28개 관점 판정 (36.2)
|
||||
|
||||
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역. 굵은 번호가 깊게 본 관점이다.
|
||||
|
||||
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | 코드 성숙도 | > 03·07 | — | — | 변이는 테스트 검출력을 보려는 것이다. `src/contracts/api-operations.ts:84`의 `?? "NONE"`가 1103/16-01 뒤 닿지 않는 분기가 된 것은 07 영역에 넘긴다(6.2절 C1) |
|
||||
| 2 | 구조적 성숙도 | > 16 | — | — | — |
|
||||
| 3 | 변경 용이성 | 적용 | M2 / M2 | E1 | **P** — 플랫폼 규칙을 샘플 없이 시험할 자리가 생겼다(`createRuntimeContractHttpExecutor`, fixture 기능 mock). 드릴에 맞추는 방법이 파일 존재 조건과 파일 단위 제외라, 이름 바꾸기와 테스트 추가가 검사를 함께 옮긴다(10-01, 10-02) |
|
||||
| 4 | 인지 부하 | 적용 | M2 / M2 | E1 | **P** — 한 unit 파일이 한 머지에서 몇 번, 어느 사본에서 도는지 알려면 `gates.json`, 드릴 다섯, 제외 목록, 테스트 안 조건을 맞춰야 한다(13번, 1101/10-06, 10-01) |
|
||||
| **5** | 위험 가시성 | 적용 | M2 / M2 | E2 | **P** — 드릴 요약은 import 그래프로 지운 테스트만 센다. 조건으로 사라진 8개와 목록으로 지운 6파일은 어디에도 안 나온다(10-01, 10-02) |
|
||||
| 6 | 실패 성숙도 | 적용 | M3 / M3 | E2(변이 10-R4) | **O** — §10.8 마지막 검사(0929/10-04)에 테스트가 생겨 L01이 2건으로 잡힌다. Envelope·scope 실패 경계가 모두 테스트에 걸린다 |
|
||||
| 7 | 운영 성숙도 | - | 테스트 계층 밖 | — | — |
|
||||
| 8 | 디버깅 가능성 | 적용 | M2 / M3 | E2 | **O** — 새 테스트 이름이 규칙을 그대로 말한다("discards a valid %s success that arrives after its scope stopped being current", "honours MAX_RETRY_ATTEMPTS %i …"). `vite-build-inputs`는 빠진 파일 이름과 고칠 곳을 메시지로 낸다(`:67-70`) |
|
||||
| 9 | 유지보수 성숙도 | 적용 | M2 / M1 | E1 | **P** — `scopeSnapshot` 4벌, `as never` scope 10곳, `deferred()` 7벌(1101/10-08). `--no-file-parallelism` 이유 없음 |
|
||||
| **10** | **테스트 성숙도** | 적용 | 목표 M3 / 확인 M3 | E1·E2(게이트, 변이 4종 10-R1~R4) | **P** — 지난 생존 변이 L01·R2b가 이제 잡힌다. 샘플 밖으로 옮긴 H53·L02도 잡힌다(4종 모두 기대한 테스트, 기대한 이유). 커버리지 네 지표 +0.2%p, 하한 72개 그대로. 남은 것: 드릴 사본의 검출 공백 둘(10-01, 10-02), 1초를 자는 RPC 테스트 3개(1101/10-07 일부) |
|
||||
| 11 | 데이터 성숙도 | > 05 | — | — | — |
|
||||
| 12 | 동시성 성숙도 | 적용(테스트 격리) | M3 / M3 | E2 | **O** — 격리 설정은 그대로다(`vitest.config.ts:40`, `tests/setup.ts`). listener 정리 테스트가 interaction signal까지 본다. 새 run isolation 테스트는 빈 포트를 쓴다(12 영역 몫). 실제 러너 사양은 미확인(U-1) |
|
||||
| 13 | 확장성 | > 11·15 | — | — | — |
|
||||
| **14** | **성능 성숙도** | 적용(테스트 실행 비용) | M2 / M1 | E2 | **P** — `tests/unit` 시간 합 133.1 → 175.7 s(+32%). 도구·자식 실행 테스트 76%(1101/10-05 커짐). 한 머지에 `tests/unit` 13번. FE-GATE-020 1,237 s. 1초를 자는 RPC 테스트 3개(1101/10-07 일부). setup 누적 50.73 s |
|
||||
| 15 | 보안 성숙도 | 적용(보안 규칙의 테스트) | M3 / M2 | E1·E2 | **O** — 쿠키 쓰기 CSRF 조립 행렬 테스트(`tests/unit/rest-profile-contract.test.ts`)는 바뀌지 않았고 통과한다. 이번 라운드에 변이로 다시 보지는 않았다 |
|
||||
| 16 | 의존성 성숙도 | > 13 | — | — | — |
|
||||
| 17 | API / Contract 성숙도 | 적용(계약 테스트) | M3 / M3 | E2 | **P** — pin 테스트가 15개로 늘었고 Envelope 판정을 답 표 행마다 본다. 그러나 capability 드릴 셋에서는 파일째 빠진다(10-02). FE-REG-API `authProfileId`(지난 H20)는 다시 보지 않았다(5절) |
|
||||
| 18 | 배포 성숙도 | > 13 | — | — | — |
|
||||
| 19 | 설정 성숙도 | 적용(러너·런타임 설정) | M3 / M3 | E1·E2(변이 10-R1) | **P** — `MAX_RETRY_ATTEMPTS`·`REQUEST_TIMEOUT_MS`가 샘플 없이 고정됐다(1105/10-01, H53 잡힘). `--passWithNoTests` 3곳 남음 |
|
||||
| **20** | 개발자 경험 | 적용 | M2 / M3 | E2 | **P** — `test:all`이 `test:coverage`의 Vitest 경로를 모두 돌고 테스트가 그 관계를 지킨다(0929/10-05). FE-GATE-020이 1,237 s다 |
|
||||
| **21** | **Guardrail 성숙도** | 적용 | M3 / M2 | E2 | **P** — skip·todo·only 차단은 그대로다. 통합 수정 셋이 검사를 skip 차단 밖에서 좁혔다: 조건부 정의(10-01), 파일 단위 제외와 주석으로 통과하는 목록 검사(10-02) |
|
||||
| 22 | 추상화 성숙도 | 적용(테스트 도우미) | M2 / M2 | E1 | **P** — 새 공유 도우미(`tests/helpers/mutation-operation-id.ts`)가 운영 함수로 ID를 만든다. scope fixture 복사본은 그대로다 |
|
||||
| 23 | 일관성 | 적용 | M2 / M2 | E1 | **P** — 드릴 사본에 테스트를 맞추는 방법이 셋으로 갈렸다(드릴이 이름으로 지움 `test-sample-removal.ts:218-225`, 문서 목록, 테스트 안 `existsSync`)(10-01). `deferred()` 7벌 |
|
||||
| 24 | 네이밍 / 의미 성숙도 | 적용 | M2 / M2 | E1 | **P** — 테스트 이름은 범위를 맞게 말한다. 코드 주석의 근거 ID가 틀린 곳이 있다(`playwright-run-isolation.test.ts:244`의 `0929/10-04`, 10-01 ⑤). 1101/10-07 수정 커밋은 느린 테스트를 잘못 짚었다 |
|
||||
| 25 | 조직 확장성 | - | 작성자 1인 | — | — |
|
||||
| 26 | Ownership 성숙도 | 부분 적용 | M2 / M1 | E1 | **P** — `ungated-tests.json` 항목에 담당·재검토 시점이 없다(12 영역) |
|
||||
| **27** | **삭제 가능성** | 적용 | M3 / M2 | E2 | **P** — 샘플을 지워도 플랫폼 규칙 테스트 둘이 남는다(1105/10-01, 로그로 확인). capability를 지우면 문서와 무관한 테스트 15개가 함께 빠지고(10-02), 조건부 8개가 말없이 사라진다(10-01) |
|
||||
| 28 | 회복 가능성 | - | 테스트 계층 밖 | — | — |
|
||||
|
||||
집계(적용 19개, `>`·`-` 제외): 충족 4(6, 8, 12, 15) · 부분 충족 15 · 미충족 0 · 미검증 0. 지난 라운드는 충족 4(8, 12, 15, 24) · 부분 충족 15였다. 6은 L01이 이제 잡혀 올렸다(10-R4). 24는 틀린 근거 ID 때문에 내렸다.
|
||||
|
||||
## 5. 미검증
|
||||
|
||||
| 항목 | 이유 | 확인하려면 |
|
||||
|---|---|---|
|
||||
| 샘플을 지운 사본에서 조립 루트 `runtime-adapters.ts:538`을 바꾸는 변이 | 사본 드릴 실행이 비싸다. 정적으로는 그 사본에서 이 한 단계를 지키는 테스트가 없다(템플릿에서는 `reference-runtime-composition.test.ts`가 지킨다). 수정 커밋 `00b12b3`이 한계로 적었다 | `test:sample-removal` 사본에서 `:538`을 `{ ...config, MAX_RETRY_ATTEMPTS: 2 }`로 바꾸고 `test:unit` |
|
||||
| 10-01의 이름 바꾸기 경로 | 실행하지 않았다(E1). 파일이 없는 상태의 결과는 드릴 로그로 봤다(E2) | 10-01 완료 기준의 실행 |
|
||||
| 1101/10-07 남은 RPC 3개에 같은 시계를 넘겨도 테스트 뜻이 그대로인지 | 코드만 봤다. 세 테스트는 닫힘 확인 대기와 두 번째 스트림 허용을 본다(`:389`, `:412`, `:588`) | 시계를 넘긴 뒤 같은 단언과 junit 시간 |
|
||||
| FE-REG-API `authProfileId`(지난 H20) | 이번에 다시 보지 않았다. 빠른 계층 fixture는 여전히 `ANONYMOUS`다(`tests/helpers/external-contract-fixture.ts`) | 다음 변이 묶음 |
|
||||
| 실제 CI 러너 실패율 | CI 꺼짐(U-1) | U-1 뒤 FE-GATE-005·020을 반복 |
|
||||
|
||||
## 6. 실행 기록
|
||||
|
||||
이 영역의 리뷰어는 직접 아무것도 실행하지 않았다. 요청은 `/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/10.md`, 패치는 같은 폴더 `10/`에 있다. 네 패치 모두 `bbde570` 작업 트리에 `git apply --check`로 맞는 것을 미리 확인했다(상태 변경 없음). 오케스트레이터 배치가 desktop checkout에서 한 항목씩 돌렸다(2026-11-06 04:34:30~04:34:35, local env, load 2.3). 각 로그 머리에 `head bbde570796b0…`, 끝에 `restore=clean`이 있다. 무변이 대조는 돌리지 않았다. 같은 명령의 무변이 통과는 `FE-GATE-005.txt`의 `test:unit`(208파일 3,056개, `runtime-adapters` 22개, `session-route-access` 6개, `http-execution-v3` 포함)이 보인다.
|
||||
|
||||
| ID | 명령 | 변이 | rc | 결과 |
|
||||
|---|---|---|---|---|
|
||||
| 10-R1 | `node scripts/run-vitest.ts run tests/unit/runtime-adapters.test.ts` | `runtime-adapters.ts:307` `maxRetryAttempts` → `2` | 1 | 22개 중 2 실패, 20 통과. 실패: "honours MAX_RETRY_ATTEMPTS 0 / 1 …" — `expected "vi.fn()" to be called 1 / 2 times, but got 3 times`. 기대와 같다 |
|
||||
| 10-R2 | `node scripts/run-vitest.ts run tests/unit/session-route-access.test.ts` | `navigation-policy.ts:40` → `show-sign-in` | 1 | 6개 중 1 실패, 5 통과. 실패: "answers a recovery-pending session with { allowed: false, action: 'wait-for-session' }" — deep equal 불일치. 기대와 같다 |
|
||||
| 10-R3 | `node scripts/run-vitest.ts run tests/unit/http-execution-v3.test.ts` | `http-execution-v3.ts:663` 삭제(R2b) | 1 | 72개 중 3 실패, 69 통과. 실패: "removes the listeners … after an answer / a caller abort / an interaction cancel" — `expected [] to deeply equal [ [Function forwardCallerToLifetime] ]`. 기대와 같다 |
|
||||
| 10-R4 | `node scripts/run-vitest.ts run tests/unit/http-execution-v3.test.ts` | `http-execution-v3.ts:1494` → `if (false)`(L01) | 1 | 72개 중 2 실패, 70 통과. 실패: "discards a valid read / command success that arrives after its scope stopped being current" — `expected { kind: 'SUCCESS', … } to match object { kind: 'CONTRACT_VIOLATION', … }`. 기대와 같다 |
|
||||
|
||||
로그: `desktop:/tmp/claude-gates/r5/batch/out/R5-10-R1.log`~`R5-10-R4.log`.
|
||||
|
||||
### 6.1 변이
|
||||
|
||||
| ID | 지키는 규칙(지난 ID) | 바꾼 곳(`bbde570`) | 결과 | 잡은 테스트 |
|
||||
|---|---|---|---|---|
|
||||
| 10-R1 | `MAX_RETRY_ATTEMPTS`가 실행기에 닿는다(1105/10-01, H53) | `src/bootstrap/runtime-adapters.ts:307` | 잡힘(2) | `tests/unit/runtime-adapters.test.ts:515-550` "honours MAX_RETRY_ATTEMPTS 0/1" |
|
||||
| 10-R2 | 복구 중 세션은 보호 라우트에서 기다린다(1105/10-01, L02) | `src/presentation/routes/navigation-policy.ts:40` | 잡힘(1) | `tests/unit/session-route-access.test.ts:32-41` "answers a recovery-pending session …" |
|
||||
| 10-R3 | interaction signal listener 정리(1105/10-02, R2b) | `src/adapters/http/http-execution-v3.ts:663` | 잡힘(3) | `tests/unit/http-execution-v3.test.ts:816-867` "removes the listeners …" |
|
||||
| 10-R4 | §10.8 오래된 scope의 성공 응답 버림(0929/10-04, L01) | `src/adapters/http/http-execution-v3.ts:1494` | 잡힘(2) | `tests/unit/http-execution-v3.test.ts:578-620` "discards a valid … success …" |
|
||||
|
||||
집계: 4종 모두 잡혔다. 지난 라운드에 살아남은 2종(L01, R2b)과 샘플 밖으로 옮긴 규칙 2종(H53, L02)이다. 1105/10-01의 두 테스트 파일은 샘플을 지운 사본에서도 돈다(`FE-GATE-020.txt:133`, `:311`). 테스트가 샘플 코드를 읽지 않으므로 그 사본에서도 같은 변이를 잡는다고 판단한다(사본에서 변이를 넣어 돌리지는 않았다, 5절).
|
||||
|
||||
### 6.2 그 밖의 분석 (노트북, desktop 산출물 사본)
|
||||
|
||||
| ID | 방법 | 결과 |
|
||||
|---|---|---|
|
||||
| J1 | `unit.xml`의 파일별 시간(208줄)을 파일의 import 대상(`src`/`scripts`/둘 다/없음)으로 분류해 합산. 같은 방법으로 지난 merge-48 `unit.xml`(194줄, `8a44226`의 파일 내용) | 지금 합 175.7 s: `src`만 117파일 19.7 s(11%), `scripts`만 59파일 100.1 s(57%), 둘 다 15파일 23.4 s(13%), 없음 17파일 32.5 s(19%). 지난 합 133.1 s: 117파일 18%, 51파일 54%, 12파일 11%, 14파일 17% |
|
||||
| D1 | `git diff 8a44226 bbde570 -- <영역 경로>`의 지운 `expect`·`it` 줄, 더한 skip·`existsSync`·시간 한도를 파일별로 대조 | 3.0절 표 |
|
||||
| D2 | `FE-GATE-005.txt`와 `FE-GATE-020.txt`에서 `tests/unit`을 포함한 Vitest 실행(파일 160개 이상)을 셈 | 13번(005: `:312`, `:781`. 020: `:322`, `:943`, `:1855`, `:2493`, `:4799`, `:5274`, `:6625`, `:7332`, `:10096`, `:10974`, `:11885`) |
|
||||
| S1 | FE-GATE-020의 드릴별 unit 실행 구간에서 목록 6파일, `playwright-run-isolation`, `session-route-access`, `runtime-adapters` 줄을 셈 | 샘플·생성 드릴 4구간: 목록 6파일 있음, pw 33개, sra 6개, ra 22개. capability 드릴 3구간: 목록 0파일, pw 33·25·33개 |
|
||||
| T1 | 커버리지 실행 junit의 테스트 이름(classname + name)을 지난 merge-48과 비교 | 지난 3,863개 → 지금 4,079개. 새 223개. 없어진 7개: `fileserver-upload` 503 `IDEMPOTENCY_UNAVAILABLE` 행(같은 행이 `MAYBE_APPLIED`로), `feature-shape-growth` "1% off"(→ "a few hundred bytes off"), `http-execution-v3` listener 2개(→ 3개), `opfs-worker-runtime` 늦은 put(→ 객체 수 1·3·8 세 행), `public-response-cache-repair` "retryable"(→ "unreadable"), `bounded-poll-coordinator` 던지는 executor(→ 두 행) |
|
||||
| C1 | `coverage-summary.json`과 `risk-coverage.json`을 지난 merge-48 것과 비교 | 아래 표 |
|
||||
|
||||
C1 커버리지 비교(두 값 모두 merge 단계 FE-GATE-005, CI env):
|
||||
|
||||
| 지표 | `8a44226` (merge-48) | `bbde570` | 차이 |
|
||||
|---|---|---|---|
|
||||
| lines | 86.31% (18,466 / 21,394) | 86.51% (18,567 / 21,461) | +0.20%p |
|
||||
| statements | 84.03% (19,303 / 22,971) | 84.23% (19,412 / 23,044) | +0.20%p |
|
||||
| functions | 90.44% (3,709 / 4,101) | 90.63% (3,737 / 4,123) | +0.19%p |
|
||||
| branches | 80.92% (15,291 / 18,896) | 81.15% (15,400 / 18,976) | +0.23%p |
|
||||
| 커버리지 실행 | 316파일 3,869개 | 332파일 4,085개 | +16파일 |
|
||||
| 위험 하한 | 418/418 모듈, 72개 PASS | 418/418 모듈, 72개 PASS | 하한 값 72개 모두 같음 |
|
||||
|
||||
- 합계 하한은 lines 75, statements 73, functions 80, branches 68이다(`risk-coverage.json` `results`). 여유는 모두 11%p 이상이다.
|
||||
- `config/testing/risk-coverage.json`은 바뀌지 않았다. `src` 파일 추가는 없어 모듈 수가 같다.
|
||||
- 얇은 여유는 지난과 같다: `src/adapters/storage/indexeddb/indexeddb-runtime.ts` lines 79.13(하한 79), branches 72.38(72).
|
||||
- 파일별로 줄어든 곳 7개. 모두 그 파일의 코드나 타입이 이번 범위에서 바뀌었다: `server-state-scope-runtime.ts` lines 97.97 → 96.42%(02-01이 13줄 더하고 2줄 안 닿음, 하한 85), `runtime-adapters.ts` 92.9 → 92.4%, `external-contract-runtime.ts` branches 83.6 → 83.4%, `load-runtime-config.ts` branches 87.0 → 86.2%, `app-shell.tsx` branches 83.3 → 81.2%, `service-worker-static-assets.ts` lines 85.5 → 85.4%, `api-operations.ts` branches 10/10 → 9/10.
|
||||
- `api-operations.ts`는 파일이 바뀌지 않았다. `:84` `contract.responseEnvelope ?? "NONE"`의 오른쪽이 지난 37번에서 0번이 됐다(lcov `BRDA:84,0,1`). 1103/16-01이 `responseEnvelope`를 필수로 만들어 닿지 않는 분기가 됐다. 테스트 약화가 아니다. 07 영역에 넘긴다.
|
||||
|
||||
## 7. 새 발견 요약
|
||||
|
||||
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|
||||
|---|---|---|---|---|
|
||||
| 10-01 | Low · P3 | 구조적 위험 | 통합 수정이 새 테스트 둘의 검사를 "대상 파일이 있으면"으로 정해, 드릴 사본에서 8개가 말없이 사라지고 템플릿에서 이름을 바꿔도 같다. skip 차단은 이를 보지 못하고 주석의 근거 ID도 틀렸다 | `tests/unit/playwright-run-isolation.test.ts:27-44`, `:243-252`; `tests/unit/vite-build-inputs.test.ts:19-22`, `:49-56` |
|
||||
| 10-02 | Low · P3 | 구조적 위험 | 문서를 읽는 테스트 하나 때문에 `backend-contract-pin.test.ts`·`feature-tracked-files.test.ts`가 파일째 capability 드릴 셋에서 빠져 문서와 무관한 15개도 돌지 않고, 목록 검사는 주석으로 통과한다 | `scripts/lib/removal-fixture.ts:70-81`; `tests/unit/backend-contract-pin.test.ts:150-253`, `:259`; `tests/unit/removal-fixture.test.ts:155-163` |
|
||||
|
||||
이월(새 발견으로 세지 않음): 1101/10-07(일부, RPC 3개), 1101/10-05(커짐)·10-06·10-08(결정 대기), `--no-file-parallelism`, `--passWithNoTests`, R1, R6, `tsc-diagnostics-parser` 제외(12 영역). 모두 Low.
|
||||
@@ -0,0 +1,236 @@
|
||||
# 영역 11 — 테스트: 브라우저·릴리스·규모
|
||||
|
||||
> 검토일 2026-11-06 · 기준 `bbde570`(`bbde570796b0a648bae65c2c0568fca860a3ba4e`, PR B 끝, 브랜치 `fix/maturity-review-2026-11-05-b`) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
|
||||
> 경로: `tests/e2e`, `tests/browser-capabilities`, `tests/visual`, `tests/storybook`, `tests/release`, `tests/scale`, `tests/system`, `tests/architecture`, `tests/scripts`, `tests/support/browser`, `playwright*.config.ts`. 판정에 필요해서 함께 읽은 것: `scripts/write-a11y-report.ts`, `scripts/lib/a11y-data-state.ts`, `scripts/contracts/release-artifacts.ts:833-869`, `scripts/lib/ci-artifact-validator.ts:205`, `scripts/check-system-test-prerequisites.ts`, `scripts/lib/provider-sandbox-namespaces.ts`, `scripts/run-and-validate-provider.ts:254-293`, `scripts/check-test-evidence.ts:280-305`, `scripts/run-ci-gate.ts:210-235`, `scripts/lib/run-isolation.ts:127-145`, `eslint.config.ts:930-943`, `.gitea/workflows/quality-gates.yml`(merge job·글꼴 단계), `config/ci/gates.json`(FE-GATE-008·009), `CHANGELOG.md:20-60`, `tests/unit/a11y-report.test.ts`
|
||||
> 깊게 본 관점: 10, 21, 5, 8, 18
|
||||
> 이번 라운드 확인 지시: (1) 1105/11-01(strict fixture 증명)과 merge 때의 lint 이름 변경 `use` → `provide`. (2) 1103/11-01 BREAKING(`757d1c7`, `a11y.json` schemaVersion 2): 코드와 BREAKING CHANGE footer·CHANGELOG 안내, FE-GATE-009가 남긴 `a11y.json`. (3) FE-GATE-008·009 로그의 수와 skip을 지난 라운드와 비교. (4) 1103/11-02~11-04와 README §16.5·§16.6의 이월 항목
|
||||
> 영역 판정(35.8): **조건부 사용 가능.** CI env merge 실행(`bbde570-ci`)에서 FE-GATE-008·009가 통과했다(e2e 222 통과·4 skip, capability 69, storybook 1, visual 6, a11y 60). 1105/11-01은 커밋된 test가 fixture의 실패 방향까지 고정한다(변이 셋이 세 엔진에서 모두 잡혔다, 11-R1). 1103/11-01은 `a11y.json`이 실패 화면 라우트를 `notChecked`로 적는다(CI env 산출물, 생성 기능 상태 11-R3). 다음은 그대로 믿지 않는다. (a) 그 분류를 지키는 test가 없고, 기록이 없는 라우트는 "검사함"으로 센다. 기록 호출 한 줄을 바꾸자 상세 라우트가 passed로 적혔고 명령은 모두 rc=0이었다(새 11-01, 11-R2). (b) `test:system`은 이 desktop에서 사전 점검이 이유와 함께 멈춘다. 그래서 1103/11-03·11-04의 완료 기준은 여전히 돌릴 수 없다. (c) CI 러너 위 실행은 없다(U-1)
|
||||
|
||||
ID 표기: 이번 라운드 새 발견은 `11-01`부터 쓴다. 라운드 밖에서는 `1106/11-01`이다. 지난 라운드는 `1105/11-NN`(2026-11-05), 그 전은 `1103/…`, `1101/…`, `0929/…`다. `11-Rk`는 `scratchpad/r5/requests/11.md`의 배치 실험이다(6절).
|
||||
|
||||
## 0. 결론
|
||||
|
||||
- **1105/11-01은 고쳐졌다.** fixture의 마지막 판정을 `browserFailureVerdict` fixture로 뺐다(`tests/support/browser/strict-browser-test.ts:27-33`, `:54-67`, `:95`). 증명 spec은 그 판정을 "기록을 받아 두는" 판정으로 바꾸고, teardown에서 기록 줄을 정확히 대조한다(`tests/e2e/preload-use.spec.ts:180-202`). 지난 완료 기준 셋을 커밋된 test가 본다. 기록을 버리면 `:209-216`이 실패한다(기대 1줄). 무시 정규식을 넓히면 `:234-252`가 실패한다(기대 4줄). 지연시킬 청크가 없으면 `:146-149`가 실패한다. 기본 판정이 test를 실패시키는지는 `test.fail()` test가 본다(`:259-267`). CI env FE-GATE-008에서 이 spec 6건이 세 엔진 모두 기대대로 끝났다. 변이 셋(기록 버림, 정규식 `/.*/u`, 기본 판정 무력화)을 함께 넣자 세 엔진에서 정확히 그 세 test가 각자 다른 메시지로 실패했다(9 failed, 9 passed, 11-R1).
|
||||
- **merge 때의 `use` → `provide` 이름 변경은 동작을 바꾸지 않는다.** `react-hooks/rules-of-hooks`는 `tests/support/browser/**`에서만 꺼져 있다(`eslint.config.ts:939-941`). 그래서 spec 파일의 fixture 콜백은 `use`라는 이름을 쓸 수 없다. 다른 spec 둘도 이미 `provide`다(`tests/e2e/boot-module-failure.spec.ts:47`, `tests/e2e/old-tab-chunk-recovery.spec.ts:153`). Playwright는 첫 인자의 구조 분해만 읽고 둘째 인자는 위치로 넘긴다. 실행 증거: 기록용 판정을 쓰는 `records a modulepreload the page never runs`가 세 엔진에서 통과했다. 이 test는 기본 판정이 돌면 자기 `preloadunused:` 한 줄로 실패한다. 그러니 바꾼 판정이 실제로 쓰였다. FE-GATE-002(lint)는 rc=0이다.
|
||||
- **1103/11-01은 고쳐졌다.** FE-GATE-009(CI env, 03:53)가 쓴 `a11y.json`은 schemaVersion 2다. `scope`에 9개 라우트, `notChecked`에 `REFERENCE_RESOURCE_DETAIL`과 이유가 있다. 게이트 로그에도 그 한 줄이 찍혔다. 코드는 BREAKING CHANGE footer, `CHANGELOG.md:28`(먼저 할 일 5단계), `:53`(표 행)과 같다. 템플릿 안 소비자는 `ci-artifact-validator` 하나이고 같은 schema를 쓴다. `create:feature sample-feature --with-create` 뒤에는 `SAMPLE_DETAIL`도 `notChecked`로 갔고 `SAMPLE_LIST`·`SAMPLE_CREATE`는 `scope`에 남았다(11-R3). 매뉴얼 주장(`docs/manual/reference/create-feature.md:98`)과 같다.
|
||||
- **새 11-01(Low·P3): `notChecked` 분류를 지키는 test가 없다.** 기록 파일이 없는 라우트는 "검사함"으로 센다(`scripts/lib/a11y-data-state.ts:50`, `:61`). unit test는 lib 함수만 보고, schema는 `scope`+`notChecked`=설치 라우트만 본다. `tests/e2e/accessibility.spec.ts:83`의 기록 호출 한 줄을 `null`로 바꾸자 라우트 test 10건이 통과하고 report도 rc=0이었다. `a11y.json`은 `REFERENCE_RESOURCE_DETAIL`을 포함한 10개 모두를 `scope`(passed)로, `notChecked: []`로 적었다(11-R2).
|
||||
- **FE-GATE-008·009 수(지난 라운드 merge-48과 비교).** e2e 205 → 226(+21: preload-use +9, reference-save +9, SW update +3). skip 3 → 4: 새 test `service-worker-update.spec.ts:302`가 같은 firefox quarantine으로 빠진다. capability 66 → 69(OPFS purge test가 두 경우로 나뉨), "23 cases x 3 engines, zero skipped". storybook 1, visual 6 그대로(골든 5장은 15-05에서 다시 찍음). test evidence 416 → 433 파일. 사라진 test는 없다(파일·엔진별 수 비교). 재시도·flaky 없음. FE-GATE-009는 60건, 이름이 같다.
|
||||
- **FE-GATE-013은 이제 사전 점검에서 이유와 함께 멈춘다(1105/12-01, 1105/11-02를 합친 것).** 사전 점검을 건너뛴 `test:system`(013-parts)은 114건 중 96 통과, 18 실패다. 18건의 이름은 지난 라운드와 같다. 6건은 여전히 bwrap 원인을 보여 주지 않는다. 1103/11-03·11-04의 완료 기준은 이 호스트에서 돌릴 수 없다.
|
||||
- **지난 발견 재판정(2절):** 고쳐짐 2(1105/11-01, 1103/11-01), 일부 4(1105/11-02는 영역 12의 12-01로 집계, 1103/11-02·11-03·11-04는 완료 기준 실행 남음), 남음 6(0929/11-02·11-04·11-05 잔여·11-07, FOLLOW-UP 2). 재발·틀린 발견 0. README §16.6은 이 영역 이월 중 0929/11-04만 적었고 0929/11-02·11-05·11-07과 FOLLOW-UP 둘은 빠졌다.
|
||||
- **검사를 약하게 만든 수정:** 새 결함으로 셀 것은 없다. 판정 override 자리가 하나 늘었고(노출은 `allowedBrowserFailure: /.*/`와 같다), `a11y.json` schema가 어떤 분할이든 받게 됐고(11-01에 포함), firefox skip이 하나 늘었다(기록된 quarantine). 3.3절 표.
|
||||
|
||||
## 1. 범위 (36.1)
|
||||
|
||||
| 항목 | 기록 |
|
||||
| --- | --- |
|
||||
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` 영역 11. `8a44226..bbde570`에서 이 영역 test·설정 경로 18파일이 바뀌었다(+609/−150). 함께 읽은 script 둘(`write-a11y-report.ts`, `check-system-test-prerequisites.ts`)을 더하면 20파일 +759/−194다. 골든 5장 교체 |
|
||||
| 커밋·작업 상태·확인 시점 | `bbde570`. 노트북 worktree(브랜치 `docs/maturity-review-2026-11-06`, HEAD = 기준)에서 읽기만 했다. 이 영역 수정 커밋: `e0255299`(1105/11-01), `757d1c73`(1103/11-01). 영역 밖이 이 경로를 건드린 것: `9655958b`(1105/12-01 사전 점검), `f4d5761a`·`0e72c0c1`(1105/12-04 실행 격리), `e02f252d`(1105/15-05 골든), `4f3c10bc`(1105/08-01 reference-save), `aaa782ba`(1105/06-03 SW update), `23662fb2`(1103/05-01 OPFS), `a37ebba3`(0929/12-03 architecture test). 합친 커밋 7개(`19d10538`, `7af80859`, `57c34ea6`, `d5a70b42`, `1a29d4aa`, `703a3355`, `b8d53c9a`) |
|
||||
| 목적과 지원 실행 구성 | 템플릿(참고 구현). 브라우저 SPA + 정적 호스팅 + 선택형 Service Worker. SSR 없음. 브라우저 테스트는 FE-GATE-008(e2e·capability·storybook·visual·test evidence)과 FE-GATE-009(`test:a11y`, 수동 기록 형식), 샌드박스 경계는 FE-GATE-013(`test:system`)이 merge 단계에서 돈다(`config/ci/gates.json:1893-1931`). CI에서는 gate마다 matrix job이 따로 돈다(`.gitea/workflows/quality-gates.yml:45-58`, `:75-82`) |
|
||||
| 필수 요구와 규모·운영 목표 | 사용자 목표: 두 템플릿을 짝으로 써서 서비스를 빨리 출시한다. merge 게이트는 1회 판정이라 코드와 무관한 실패가 없어야 한다. 규모·성능 목표는 영역 15 |
|
||||
| 실행 환경 | 이 영역의 실행 없음. 근거로 쓴 출력은 모두 `bbde570`이다. (1) merge 단계 CI env 실행 `desktop:/tmp/claude-gates/bbde570-ci/`(03:24 시작, load 0.98): `summary.txt` FE-GATE-001~012·020 rc=0, 013 rc=1. 게이트 로그 `gate-artifacts/FE-GATE-008.txt`(sha256 `8b852193…`), `FE-GATE-009.txt`(`82693359…`), `FE-GATE-013.txt`(`789acdcb…`). 사본: `scratchpad/r5/a11/FE-GATE-00{8,9}.bbde570.txt`, `FE-GATE-013.bbde570.txt`(sha256 같음). (2) FE-GATE-013의 사전 점검 뒤 명령: `desktop:/tmp/claude-gates/bbde570-013-parts/`(`system-vitest.log`, 사본 `scratchpad/r5/a11/system-vitest.bbde570.log`). (3) 그 실행의 산출물 snapshot `desktop:/tmp/claude-gates/r5/snap/merge/`(`MTIMES.txt`로 03:24 뒤 파일만 썼다: `artifacts/tests/a11y.json` 03:53, `artifacts/tests/a11y-data-state/REFERENCE_RESOURCE_DETAIL.json` 03:52, `artifacts/tests/unit.xml` 03:46). (4) 비교용 지난 라운드 로그: `desktop:/tmp/claude-gates/r4/snap/artifacts/quality/gates/FE-GATE-00{8,9}.txt`(merge-48, `8a44226`). 비교에만 쓰고 이번 판정 근거로 쓰지 않았다. (5) 배치 11-R1~R3: 오케스트레이터가 desktop checkout(`bbde570`)에서 local env로 하나씩 돌렸다(2026-11-06 04:34~04:36, load 2.2~3.7). 셋 모두 `restore=clean`. 로그 `desktop:/tmp/claude-gates/r5/batch/out/R5-11-R{1,2,3}.log`(사본 `scratchpad/r5/a11/`) |
|
||||
| 읽은 코드·구성 범위 | 전부: 위 커밋의 영역 diff, `strict-browser-test.ts`, `preload-use.spec.ts`, `accessibility.spec.ts`, `a11y-data-state.ts`, `write-a11y-report.ts`, `a11y-report.test.ts`, `check-system-test-prerequisites.ts`, `provider-sandbox-namespaces.ts`, `installed-api-answers.ts`. 필요한 부분: `release-artifacts.ts:833-869`, `ci-artifact-contract.test.ts:280-345`, `:459-465`, `run-and-validate-provider.ts:254-293`, `service-worker-update.spec.ts:40-80`, `:176-350`, `opfs-runtime.spec.ts:329-460`, `reference-save.spec.ts:80-237`, Playwright 설정 다섯 개, `check-test-evidence.ts:280-305`, `run-ci-gate.ts:210-235`, `CHANGELOG.md:20-60`, 매뉴얼·문서의 a11y 문장(`docs/manual/reference/create-feature.md:97-98`, `docs/manual/01-add-a-feature.md:433`, `docs/accessibility/manual-checklist.md:66-80`, `docs/testing/frontend-platform-testing-strategy.md:140-155`) |
|
||||
| 수행한 테스트·실험 | 직접 돌린 것은 없다. 배치 3건(11-R1~R3, 6절). 패치 둘은 노트북에서 `git apply --check`로 `bbde570`에 붙는 것을 확인했다. 3건 모두 기대와 같은 결과였다 |
|
||||
| 확인하지 못한 범위·이유 | `test:system` provider 묶음: desktop의 bwrap이 비특권 user namespace를 못 쓴다(FE-GATE-013 사전 점검 출력). 노트북은 실행 금지. 그래서 1103/11-03·11-04의 완료 기준과 `.git` 가림 변이를 확인할 길이 없다. 실제 Gitea 러너(U-1). 글꼴 없는 깨끗한 Ubuntu에서 FE-GATE-008(1103/11-02) |
|
||||
| 이전 리뷰와 비교 가능한 범위 | 지난 README §15의 영역 11 행 1건(1105/11-01), §11.3에서 12-01에 합친 1105/11-02, §16.5의 1103/11-01~11-04, §16.6의 0929/11-04, 지난 영역 문서 2절의 "남음"(0929/11-02·11-05 잔여·11-07, FOLLOW-UP 2). §16.4·§16.5의 "고침"은 주장으로 보고 지난 영역 문서 3절의 완료 기준과 대조했다. 지난 라운드 실행 결과는 수 비교에만 썼다 |
|
||||
|
||||
## 2. 지난 발견 재확인
|
||||
|
||||
상태: 고쳐짐(완료 기준 확인) / 일부(남은 것) / 남음 / 재발 / 틀린 발견. "일부(검증 남음)"은 코드 변경은 들어왔고 완료 기준 실행만 남은 경우다.
|
||||
|
||||
| 지난 ID | 내용 | 상태 | 근거 |
|
||||
|---|---|---|---|
|
||||
| 1105/11-01 | preload 검사 증명 spec이 tracker만 증명해서, strict fixture가 결과를 버려도 커밋된 test가 실패하지 않는다. 3번 test는 청크가 없으면 평범한 방문이 된다 | **고쳐짐** | 3.2절 (1). 완료 기준 셋(지난 문서 3.1 11-01): ① fixture가 기록을 버리면 실패 — `preload-use.spec.ts:204-217`이 기록 `^preloadunused:/assets/[^/]+\.js$` 한 줄을 요구한다(`:195-200`). ② 무시 정규식을 `/.*/`로 넓히면 실패 — `:219-253`이 warning 셋과 error 하나, 모두 네 줄을 순서대로 요구한다. 정규식을 넓히면 warning 셋이 사라져 한 줄만 남는다. ③ `parent`가 없으면 실패 — `:146-149`. 기본 판정의 실패 방향은 `:259-267`(`strictTest.fail()`). 변이 없는 실행: CI env FE-GATE-008에서 6건 × 3엔진이 기대대로 끝났다(`:259`는 세 엔진 모두 기대된 실패, 222 passed에 포함). 문서 주장(`docs/testing/frontend-platform-testing-strategy.md:151-154`)과 같다. 판정을 바꾸는 spec은 하나뿐이다(`git grep browserFailureVerdict`). **변이(11-R1, local env, 세 엔진):** ①②와 기본 판정 무력화를 함께 넣자 `:209`가 "what the strict fixture recorded" 기대 길이 1·받은 0, `:234`가 기대 4·받은 1, `:259`가 "Expected to fail, but passed."로 세 엔진 모두 실패했다(9 failed). tracker test 둘과 3번 test는 통과했다(9 passed). 지난 완료 기준 ①②를 커밋된 test가 실행으로 잡는다. ③은 단언 한 줄이라 정적으로 본다 |
|
||||
| 1105/11-02 | `test:system` 사전 점검이 bwrap을 시험하지 않아 PASS 뒤 18건 실패 | **일부**(README에서 1105/12-01로 합침, 집계는 영역 12) | 이 영역이 본 것: FE-GATE-013(CI env)이 사전 점검에서 bwrap 명령·stderr(`loopback: Failed RTM_NEWADDR`)·호스트 설정 셋·고치는 방법을 적고 멈춘다(`gate-artifacts/FE-GATE-013.txt`). 사전 점검은 provider와 같은 옵션 상수로 `/bin/true`를 띄운다(`scripts/check-system-test-prerequisites.ts:39-43`, `:90-95`, `scripts/lib/provider-sandbox-namespaces.ts:13-18`, `scripts/run-and-validate-provider.ts:257`). 완료 기준 앞 절반은 충족. 남은 것: 지원 호스트에서 PASS 뒤 114건 통과(이번에 확인할 호스트 없음). 지난 개선 방향의 "파일 대기 test가 provider stderr를 붙인다"는 들어오지 않았다. 사전 점검을 건너뛴 실행에서 6건은 여전히 `provider output did not reach expected content`(`tests/system/ci-runner/ci-artifact-contract.test.ts:1782`) 4건, `expected path did not appear`(`:1812`) 2건뿐이다(`system-vitest.bbde570.log`) |
|
||||
| 1103/11-01 (+12-03, 16-03 뒷부분) | 생성 기능 라우트를 접근성 e2e가 실패 화면으로 검사하고 `a11y.json`은 "passed" | **고쳐짐** | 3.2절 (2). 지난 문서의 남은 것은 상세 라우트와 `a11y.json`이었다. 이제 실패 화면 분기가 이유를 기록하고(`tests/e2e/accessibility.spec.ts:77-84`), report가 그 라우트를 `scope`에서 빼 `notChecked`에 넣는다(`scripts/write-a11y-report.ts:14-26`, `scripts/lib/a11y-data-state.ts:81-97`). CI env FE-GATE-009 산출물: `notChecked: [{ routeId: "REFERENCE_RESOURCE_DETAIL", reason: "scanned on its failure state only: GET_REFERENCE_RESOURCE reads one resource" }]`, `scope` 9개. 생성 기능 상태(11-R3, chromium): `create:feature sample-feature --with-create` 뒤 라우트 test 13건 통과, `notChecked`는 `REFERENCE_RESOURCE_DETAIL`과 `SAMPLE_DETAIL`("… SAMPLE_GET_ITEM reads one resource"), `scope`는 `SAMPLE_LIST`·`SAMPLE_CREATE`를 포함한 11개. 목록 라우트 쪽 코드는 `8a44226` 뒤 기록 호출 말고 바뀌지 않았다(`git diff 8a44226..bbde570 -- tests/e2e/accessibility.spec.ts tests/e2e/support/installed-api-answers.ts`). 남은 한계(기록된 선택): 상세 라우트의 화면 내용은 자동 검사 밖이고 수동 검토가 맡는다(`docs/manual/reference/create-feature.md:98`, `757d1c7` 본문의 버린 대안). 분류를 지키는 test가 없는 것은 새 11-01 |
|
||||
| 1103/11-02 | CI merge job이 시각 테스트 글꼴을 설치하지 않음 | **일부(검증 남음)** | workflow의 브라우저 단계 두 곳이 패키지 넷을 설치한다(`.gitea/workflows/quality-gates.yml:74`, `:113`). 목록은 한 곳이다(`scripts/lib/visual-test-fonts.ts:9-16`, `scripts/generate-ci-workflow.ts:290`, `tests/visual/fonts.setup.ts:23`). 글꼴이 있는 desktop에서 FE-GATE-008 `test:visual` 6/6(`visual fonts match the goldens` 포함). 남은 것: 글꼴 없는 깨끗한 Ubuntu 24.04에서 6/6(완료 기준 3번). root도 sudo도 없는 러너면 `$(command -v sudo || true) apt-get`이 실패한다. README §16.5 "실행 환경 대기"와 같은 뜻이다 |
|
||||
| 1103/11-03 | provider 테스트 10초 상한, 하나만 고르면 기반 fixture 빌드를 떠안음 | **일부(검증 남음)** | 코드는 지난 라운드 그대로다(`tests/system` diff 없음). 묶음 30초(`ci-artifact-contract.test.ts:461`), 기반 fixture `beforeAll` 180초(`:65-69`, `:462-464`), 개별 상한은 `:539` 40초 하나. 완료 기준(`-t 'kills descendants'` 단독 통과, loadavg 20+에서 5회)은 이 호스트에서 돌 수 없다. 사전 점검을 건너뛰어도 `kills descendants …` 두 건은 provider가 시작하지 못해 실패한다(`system-vitest.bbde570.log`) |
|
||||
| 1103/11-04 | worktree `.git` 파일 때문에 provider test 16개 실패 | **일부(검증 남음)** | 가림 코드 그대로(`scripts/run-and-validate-provider.ts:278-293`). 새 test 둘(`ci-artifact-contract.test.ts:771-802`)도 이 호스트에서 bwrap 오류로 실패한다(`hides repository metadata … directory / file`). 가림 삭제 변이는 아직 아무도 결론을 내지 못했다 |
|
||||
| 0929/11-02 | 운영 drill이 어떤 입력으로도 PASS가 될 수 없음 | 남음 | `scripts/drill-runbook.ts:245`, `:351`, `:393`, `:434`의 `providerVerificationRequired: true` 그대로. `main()`은 runbook ID와 `--release-root`만 받는다(`:519-526`). 이번 diff는 descriptor에 `responseEnvelope: "NONE"` 한 줄뿐이다(`:290`). README §16.6에 없다 |
|
||||
| 0929/11-04 | lab 성능 게이트 판정이 같은 빌드에서 뒤집힘 | 남음(영역 15) | `scripts/test-performance.ts`는 기능 라우트·직접 진입 CLS·스크롤바 때문에 +168줄 바뀌었다(`81701ad`, `138c195`, `e02f252`). 같은 빌드의 판정이 뒤집히는지 막는 변경은 아니다. 이번 공유 실행은 1회(5 runs 중앙값, `r5/snap/lab.txt` PASS)라 뒤집힘을 볼 수 없다. README §16.6 "남김" |
|
||||
| 0929/11-05 남은 것 | 규모 기준선이 지금 코드를 대표하는지 | 남음(미검증, 영역 15) | `config/scale/feature-shape-growth.json:3`, `:16`은 그대로 2026-11-01, 커밋 `373b27b` 측정이다. 이번에 다시 적은 것은 다른 파일(초기 JS 기록 `config/scale/feature-shape-ceilings.json:41-46`, `0fee3fe`)이다. README §16.6에 없다 |
|
||||
| 0929/11-07 | 빌드 helper 두 벌 | 남음 | 제외 목록은 이제 같다. 1105/12-04가 `service-worker-builds.ts`에 `.tmp`를 손으로 더했다(`tests/e2e/support/service-worker-builds.ts:58-69`, 주석 "fixture-builds.ts skips it too"; `tests/e2e/support/fixture-builds.ts:19-28`). `run`(`fixture-builds.ts:55`, `service-worker-builds.ts:177`)과 한 번 치환(`editOnce` `fixture-builds.ts:43`, `replaceOnce` `service-worker-builds.ts:111`)은 두 벌이다. 이번 수정도 두 곳을 같이 고쳐야 했다. 지난 판단대로 결함으로 올리지 않는다(리팩토링 후보). README §16.6에 없다 |
|
||||
| FOLLOW-UP | SW update spec의 route chunk 변경을 helper 옵션으로 | 남음(문서화된 전제) | 아직 spec의 `beforeBuild`에서 덧붙인다(`tests/e2e/service-worker-update.spec.ts:61-72`). 새 test(`:302`)도 이 변경에 기댄다(`removedRouteChunk` `:241-257`) |
|
||||
| FOLLOW-UP | Firefox SW quarantine | 남음(만료 2027-03-31) | 주석 `service-worker-update.spec.ts:181`, `service-worker-recovery.spec.ts:84`. 빠지는 test가 3 → 4개다(`:223`, `:263`, `:306`, recovery `:85`) |
|
||||
|
||||
지난 라운드에 고쳐짐으로 본 1103/11-05~11-10은 다시 열지 않았다. 재발 여부만 봤다. CI env FE-GATE-008에서 차단 업그레이드 test(`indexeddb-runtime.spec.ts:982`), compact smoke(`compact-smoke.spec.ts:12`), 파일·다운로드 test(`browser-files.spec.ts:14`, `:225`), preload 허용 spec(boot·old-tab·production-csp)이 세 엔진(compact는 chromium-compact) 모두 통과했다. "Execution context was destroyed"는 0건이다. 재발 없음.
|
||||
|
||||
## 3. 이번 발견 (36.3)
|
||||
|
||||
심각도 분포: Critical 0 · High 0 · Medium 0 · Low 1. 우선순위: P3 1. 성격: 구조적 위험 1.
|
||||
|
||||
### 3.1 발견
|
||||
|
||||
#### 11-01 `a11y.json`의 `notChecked` 분류를 지키는 test가 없고 기록이 없는 라우트를 "검사함"으로 세서, spec의 기록 호출 한 줄이 바뀌면 상세 라우트가 경고 없이 다시 passed로 세진다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 구조적 위험 |
|
||||
| 관련 관점 | 10, 21, 5 |
|
||||
| 근거 | **분류 경로:** 라우트 test는 실패 화면 분기에서만 기록 파일을 쓴다(`tests/e2e/accessibility.spec.ts:77-84`). 다른 두 분기는 기록을 지운다(`:76`, `:89`). report는 기록 파일이 있는 라우트만 `notChecked`로 옮긴다. 파일이 없으면 "검사함"이다(`scripts/lib/a11y-data-state.ts:50` 주석 "A route with none was checked", `:61` ENOENT면 `continue`, `:88-92`). **지키는 검사:** unit test 5건은 lib 함수를 임시 디렉터리로만 부른다(`tests/unit/a11y-report.test.ts:42-100`). spec과 이어지지 않는다. schema는 `scope`+`notChecked`가 설치 라우트와 같은지만 본다(`scripts/contracts/release-artifacts.ts:853-868`). 어느 라우트가 `notChecked`여야 하는지는 보지 않는다. `notChecked: []`도 받는다(unit test `:86-92`가 그 값을 통과로 단언한다). 생성된 `a11y.json`이나 기록 파일을 읽는 다른 test·검사는 없다(`git grep -n "REFERENCE_RESOURCE_DETAIL\|readA11yNotCheckedRoutes\|a11y-data-state" -- tests scripts`: 소비자는 `write-a11y-report.ts` 하나). 커밋 본문의 검증도 "`notChecked`에 `REFERENCE_RESOURCE_DETAIL`이 있어야 한다"를 실행 뒤 눈으로 본 것이다(`757d1c7` 본문 "검증"). **변이 실행(11-R2, local env, chromium):** `:83`의 `recordA11yDataState(definition.routeId, reason)`을 `null`로 바꿨다. 라우트 test 10건이 모두 통과했다(`playwright rc=0`). `write-a11y-report.ts`도 rc=0이었고 "not checked" 줄을 찍지 않았다. `a11y.json`은 `scope`에 `REFERENCE_RESOURCE_DETAIL`을 포함한 10개 전부, `notChecked: []`를 적었다. 같은 명령의 변이 없는 짝은 FE-GATE-009(CI env)이고 `notChecked`에 그 라우트가 있었다. 1103/11-01이 고친 거짓 주장이 한 줄로 돌아온다. **기록이 실행을 넘어 남는다:** 같은 실행 뒤 기록 디렉터리에 `INVOICE_DETAIL.json`(04:31)이 남아 있었다. 템플릿에 없는 라우트라, 앞선 다른 배치 항목이 만들었다가 checkout 복원으로 지워진 기능의 기록으로 보인다(추론). `artifacts/`의 JSON은 git이 무시하므로(`.gitignore:11`) 복원해도 남는다. report는 설치된 라우트 ID만 읽으므로(`a11y-data-state.ts:56-59`) 이번에는 해가 없었다. 같은 ID의 라우트가 다시 설치되고 그 test가 돌지 않으면 지난 기록이 그대로 쓰인다(커밋 본문이 적은 "지난 기록이 남는다") |
|
||||
| 발생 조건 | `accessibility.spec.ts`나 `a11y-data-state.ts`를 고치는 변경(분기 정리, 기록 호출 이동, 새 분기). 템플릿을 받은 제품이 자기 기능 응답에 맞게 spec을 고칠 때. 지금 코드에는 기록 없이 통과하는 분기가 없다(세 분기 모두 기록 호출이 있거나 test가 실패한다) |
|
||||
| 영향 | 자동 접근성 증거가 실패 화면으로만 본 라우트를 통과로 적는다. 사용자 피해는 없다. 상세 라우트의 화면 내용은 원래 수동 검토(FE-GATE-028)가 맡으므로 release 쪽 뒷받침은 남는다(`docs/manual/reference/create-feature.md:98`) |
|
||||
| 심각도·우선순위 | Low · P3 — 1105/11-01과 같은 종류(검사를 지키는 test가 없음)다. 그쪽은 모든 browser test가 쓰는 fixture라 P2였다. 이쪽은 증거 한 칸이고 수동 검토가 뒤를 받친다 |
|
||||
| 통제·증거 | 목표 M3(실패 화면 라우트가 `scope`에 들어가면 커밋된 검사가 실패) / 확인 M2(분류는 구현됐고 지금 맞게 동작한다. 지키는 test는 없다) · E3(11-R2 변이 실행 + 변이 없는 CI env FE-GATE-009 산출물) + E1(검사 목록) |
|
||||
| 확실성과 남은 가정 | 분류 경로와 검사 목록은 코드로 확정이다. `test:a11y` 경로(spec + report)가 변이를 놓친다는 것은 11-R2로 확정이다. 다른 게이트(unit의 `a11y-report.test.ts`, 증거 schema)도 놓친다는 것은 소비자 목록에서 온 추론이다(둘 다 spec을 읽지 않는다). 11-R2는 chromium 한 엔진이다. 분류는 엔진과 상관없는 코드다 |
|
||||
| 결정의 근거 | 이미 정한 분류를 지키는 test 보강이다. 다만 "기록 없음 = 검사함" 기본값을 뒤집을지는 작은 설계 선택이라 대안 비교에 적는다 |
|
||||
| 이해 비용 | spec을 고치는 사람은 기록 호출이 릴리스 증거를 정한다는 것을 `a11y-data-state.ts` 머리 주석(`:5-17`)에서만 알 수 있다. spec의 주석(`:78-80`)은 결과만 적는다 |
|
||||
| 최소 개선 방향 | (1) 설치된 descriptor로 "한 자원을 읽는 라우트" 목록을 계산하는 test를 둔다(`tests/e2e/support/installed-api-answers.ts:33-63`과 같은 규칙). 그 목록이 `test:a11y` 뒤 `a11y.json`의 `notChecked`와 같아야 한다. 템플릿에서는 `REFERENCE_RESOURCE_DETAIL` 하나다. (2) 라우트 test가 두 상태 모두 기록을 남기고, report는 이번 실행의 기록이 없는 설치 라우트가 있으면 실패한다 |
|
||||
| 대안 비교 | (가) 현상 유지: 비용 없음. 기록 호출 변경을 아무 검사도 못 본다. (나) (2)만: 기록 줄 삭제·skip·이른 return은 잡는다. reason을 `null`로 바꾸는 변경은 못 잡는다. 지난 실행의 "검사함" 기록을 실행마다 비워야 한다. (다) (1)만: 두 방향 변경을 모두 잡는다. 다만 test가 spec과 같은 규칙을 한 번 더 계산한다. (라) (1)+(2): 가장 넓다. 비용은 test 하나와 기록 형식 한 칸이다. 이 영역의 권고는 (다)부터다 |
|
||||
| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다 |
|
||||
| 비용·부작용 | test 1개. (2)를 고르면 기록 파일이 라우트 수만큼 생기고, 실행 경계(`TEST_RUN_ID`, 1105/12-04)를 정해야 한다 |
|
||||
| 재검토 조건 | 상세 라우트를 견본 응답으로 실제 검사하게 되면 `notChecked`가 빈다. 그때 이 test는 "`notChecked`가 비었다"로 바뀐다 |
|
||||
| 완료 기준 | 11-R2 변이(`accessibility.spec.ts:83`의 reason → `null`)를 넣으면 커밋된 검사(`test:a11y` 또는 FE-GATE-009의 다른 명령, 또는 unit test)가 실패한다. 기록 호출을 지워도 실패한다 |
|
||||
| 검증 방법 | 11-R2와 같은 변이, 기록 줄 삭제 변이로 `corepack pnpm test:a11y` |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
|
||||
### 3.2 영역 필수 확인
|
||||
|
||||
**(1) 1105/11-01 strict fixture 증명 (`e0255299`)과 `use` → `provide`**
|
||||
|
||||
구조(코드): page fixture는 기록을 모아 test 본문 뒤에 preload 결과를 더한다(`strict-browser-test.ts:68-91`). 그 목록을 `browserFailureVerdict.judge`에 넘긴다(`:95`). 기본 판정은 `allowedBrowserFailure`로 거른 뒤 빈 목록을 단언한다(`:54-67`). page fixture가 판정 fixture에 기대므로, 판정의 teardown은 page teardown 뒤에 돈다. 증명 spec의 `recordedTest`는 판정을 "받아 두기"로 바꾸고 teardown에서 대조한다(`preload-use.spec.ts:180-202`).
|
||||
|
||||
| 질문 | 판단 | 근거·상태 |
|
||||
|---|---|---|
|
||||
| (a) fixture가 preload 기록을 버리면 커밋된 test가 실패하는가 | 그렇다. 11-R1(M1): 세 엔진 모두 `:209`가 기대 길이 1·받은 0으로 실패 | `:204-217`이 `^preloadunused:\/assets\/[^/]+\.js$` 한 줄을 요구한다(`:195-200`의 `toHaveLength`와 `toMatch`). 기록을 버리면 0줄이다. 판정이 아예 불리지 않아도 `:194`의 `toBeDefined`가 잡는다 |
|
||||
| (b) WebKit 무시 정규식을 넓히면 실패하는가 | 그렇다. 11-R1(M2): 세 엔진 모두 `:234`가 기대 4·받은 1로 실패 | `:219-253`이 Chromium 문구, 뒤에 글자 붙은 WebKit 문구, 같은 문구의 `console.error`, 다른 warning, 네 줄을 순서대로 요구한다. WebKit 문구 그대로는 기록되지 않아야 한다. 정규식이 `/.*/`면 warning 셋이 빠져 1줄만 남는다. 정규식을 좁혀 WebKit 문구가 기록되면 다섯 줄이 되어 역시 실패한다 |
|
||||
| (c) 기본 판정이 test를 실패시키는지 고정하는가 | 그렇다. 11-R1(M3): 세 엔진 모두 `:259`가 "Expected to fail, but passed."로 실패 | `:259-267`은 `strictTest.fail()`로 console error 한 줄을 낸다. 기본 판정이 아무것도 실패시키지 않으면 "expected to fail"로 실패한다. 커밋 본문이 적은 한계: 이 test가 다른 이유로 실패해도 통과한다. 기록 쪽은 (a)(b)가 따로 본다 |
|
||||
| (d) 3번 test가 지연시킬 청크를 못 찾으면 실패하는가 | 그렇다(정적) | `:146-149` `expect(parent, …).toBeDefined()`. 남은 작은 빈틈: 지연 route가 실제로 걸렸는지는 단언하지 않는다(`:153-159`). 지금은 `parent`가 boot의 정적 closure 밖이고(`:128-142`) 앱에 미리 받기 코드가 없다(`git grep -i "prefetch\|requestIdleCallback" -- src` 0건). FE-GATE-008의 시간(chromium 4.5 s, firefox 4.7 s, webkit 7.2 s, 같은 화면을 지연 없이 여는 `:100` test는 0.7~3.4 s)이 지연이 걸렸다는 간접 증거다. 5절 |
|
||||
| (e) `use` → `provide` 이름 변경이 동작을 바꾸는가 | 바꾸지 않는다 | §16.3 "`e025529`에 접음"대로 최종 커밋에 이미 `provide`다(`git show e0255299:tests/e2e/preload-use.spec.ts`의 `:180-182`). lint 규칙은 `tests/support/browser/**`에서만 꺼져 있다(`eslint.config.ts:939-941`). 그래서 fixture 파일은 `use`(`strict-browser-test.ts:54`, `:68`), spec은 `provide`(`preload-use.spec.ts:182`, `boot-module-failure.spec.ts:47`, `old-tab-chunk-recovery.spec.ts:153`)다. Playwright는 fixture 함수의 첫 인자 구조 분해만 읽는다. 실행 증거: `recordedTest`의 preload test가 세 엔진에서 통과했다. 바꾼 판정이 쓰이지 않았다면 기본 판정이 그 `preloadunused:` 줄로 실패시켰을 것이다. FE-GATE-002(lint) rc=0 |
|
||||
| (f) 새 override 자리 | 기록 | 다른 spec도 `browserFailureVerdict`를 바꿔 strict 검사를 끌 수 있다. 지금 바꾸는 spec은 하나다(`git grep browserFailureVerdict`). 막는 검사는 없다(커밋 본문 "위험·한계"). `allowedBrowserFailure: /.*/`와 같은 노출이고, 그쪽에도 막는 검사가 없다. 결함으로 세지 않는다 |
|
||||
|
||||
**(2) 1103/11-01 BREAKING (`757d1c7`, `a11y.json` schemaVersion 2)**
|
||||
|
||||
| 질문 | 판단 | 근거·상태 |
|
||||
|---|---|---|
|
||||
| 코드가 BREAKING CHANGE footer와 같은가 | 같다 | footer: schemaVersion 2, 실패 화면으로만 본 라우트는 `scope`에서 빠져 `notChecked`의 `{ routeId, reason }`으로, 옛 도구는 둘을 합쳐 읽는다. 코드: 값을 만드는 곳 `a11y-data-state.ts:81-97`(`schemaVersion: 2`, `scope`는 설치 라우트에서 `notChecked`를 뺀 것). schema `release-artifacts.ts:840-869`(`z.literal(2)`, `notChecked`는 strict 객체 배열, 중복 금지, 설치 라우트만, `scope`는 레지스트리 순서의 나머지) |
|
||||
| CHANGELOG 안내와 같은가 | 같다 | 먼저 할 일 5단계(`CHANGELOG.md:28`)와 표 행(`:53`). 표 행의 "라우트 test가 자기 상태를 … 남긴다"는 정확히는 "실패 화면 라우트만 파일을 남기고 나머지는 지운다"다(`a11y-data-state.ts:38-41`). 틀린 말은 아니다 |
|
||||
| 템플릿 안 소비자 | 하나, 같이 바뀌었다 | `ci-artifact-validator.ts:205`가 같은 schema를 쓴다. FE-GATE-009의 증거가 그 하나다(`config/ci/gates.json:1920-1931`, `:1152-1159`). `tests/system/ci-runner/ci-artifact-contract.test.ts:316`의 `{ schemaVersion: 1, … }`은 "거절되어야 할 값" 예시라 그대로 맞다(칸이 모자라 원래도 거절된다) |
|
||||
| FE-GATE-009 산출물(CI env, `bbde570`) | 기대대로 | 게이트 로그: `60 passed (48.6s)`, `a11y: REFERENCE_RESOURCE_DETAIL not checked in its own state (scanned on its failure state only: GET_REFERENCE_RESOURCE reads one resource)`, 수동 기록 형식 `PASS (10 routes …)`. snapshot `artifacts/tests/a11y.json`(03:53, `generatedAt` `2026-11-05T18:53:04.086Z`): `scope` 9개(`APP_HOME` … `REFERENCE_RESOURCE_STATUS`), `notChecked` 1개, `automatedStatus: "passed"`. 기록 파일은 `REFERENCE_RESOURCE_DETAIL.json` 하나(03:52). `tests/unit/a11y-report.test.ts` 5건은 snapshot `unit.xml`(03:46)에서 통과 |
|
||||
| 생성 기능의 상세 라우트 | 매뉴얼대로 `notChecked`로 간다 | 분류 규칙은 기능과 상관없다(`installed-api-answers.ts:46-55`: 빈 목록을 거절하고 경로 파라미터가 있으면 한 자원 읽기). 생성기의 상세 라우트는 `session-required`다(`scripts/create-feature-write-slice.ts:130`). 11-R3(chromium): 생성 명령이 `SAMPLE_LIST`·`SAMPLE_DETAIL`·`SAMPLE_CREATE`를 만들었다. 라우트 test 13건 통과. report가 두 줄(`REFERENCE_RESOURCE_DETAIL`, `SAMPLE_DETAIL … SAMPLE_GET_ITEM reads one resource`)을 찍고 rc=0. `scope` 11개, `notChecked` 2개. 매뉴얼 주장(`create-feature.md:98`)과 같다 |
|
||||
| 문서 | 기록 | 매뉴얼 `create-feature.md:97-98`은 동작과 같다. `docs/accessibility/manual-checklist.md:74-76`과 `docs/manual/01-add-a-feature.md:433`은 annotation만 적고 `a11y.json`의 `notChecked`를 말하지 않는다. 틀리지는 않고 덜 적었다(영역 14 참고, 세지 않음) |
|
||||
| 고정 경로와 실행 격리 | 기록 | 기록 디렉터리(`a11y-data-state.ts:18`)와 `a11y.json`(`write-a11y-report.ts:11-16`)은 `TEST_RUN_ID`와 상관없이 기본 경로다. 1105/12-04가 적은 한계 "게이트와 증거 검사는 기본 경로만 읽는다"(`CHANGELOG.md:38`, `:106`)와 같다. 두 실행이 같은 라우트에 같은 판단을 쓰므로, 기능 선택이 다른 두 실행(12-04의 알려진 한계)이 아니면 해가 없다 |
|
||||
|
||||
**(3) FE-GATE-008·009 수 비교 (CI env, 지난 라운드 merge-48 `8a44226` ↔ 이번 `bbde570`)**
|
||||
|
||||
파일·엔진별 test 수를 두 로그에서 세어 비교했다(각 94행). 줄어든 행은 없다.
|
||||
|
||||
| 명령 | 지난 라운드 | 이번 | 차이와 이유 |
|
||||
|---|---|---|---|
|
||||
| `test:e2e` | 205건: 202 passed, 3 skipped, 1.8 m | 226건: 222 passed, 4 skipped, 2.1 m | preload-use 3 → 6 test(× 3엔진 +9, 1105/11-01), reference-save 5 → 8(+9, 1105/08-01), SW update 5 → 6(+3, 1105/06-03). `preload-use.spec.ts:259` 세 건은 `test.fail()`의 기대된 실패라 목록에 ✘로 나오고 passed로 센다 |
|
||||
| skip | firefox 3건 | firefox 4건 | `service-worker-recovery.spec.ts:79`, `service-worker-update.spec.ts:219`, `:259`, 새 `:302`. 모두 같은 quarantine(`:181`, 만료 2027-03-31) |
|
||||
| `test:browser-capabilities` | 66 passed | 69 passed(43.4 s) | OPFS purge test가 기존 객체 0개·3개 두 경우로 나뉨(`opfs-runtime.spec.ts:338`, 1103/05-01). 증거 검사 "22 → 23 cases x 3 engines, zero skipped" |
|
||||
| `test:storybook` | 1 | 1 | 같다 |
|
||||
| `test:visual` | 6 | 6(11.1 s) | 골든 5장을 다시 찍었다(`e02f252d`, 1105/15-05). 허용치는 그대로다(3.3절) |
|
||||
| `check:test-evidence:browser` | 416 파일 | 433 파일, baseline 5 | 금지 fixture 넷은 기대대로 실패(`EXPECTED_FAILURE`) |
|
||||
| `test:a11y`(FE-GATE-009) | 60 passed | 60 passed(48.6 s) | test 이름이 같다(줄 번호만 +1·+3). 새로 `notChecked` 한 줄 |
|
||||
| 재시도·flaky | 없음 | 없음 | "Execution context was destroyed" 0건 |
|
||||
|
||||
web server 포트는 실행마다 달랐다(e2e 36031, visual 44517, a11y 36037). 1105/12-04의 빈 포트 선택이 CI env에서 동작한다.
|
||||
|
||||
증거 읽기 주의: snapshot의 `artifacts/tests/e2e/results.xml`(03:53)은 `tests="60"`이다. FE-GATE-008의 226건이 아니라 뒤에 돈 FE-GATE-009(`test:a11y`, 같은 `playwright.config.ts` 출력 경로)의 결과다. 한 checkout에서 merge 단계를 차례로 돌리면 덮어쓴다. CI는 gate마다 job이 따로라 겹치지 않는다(`quality-gates.yml:45-58`, `:75-82`). `ci:gate`는 gate 직후 그 증거를 검증한다(`scripts/run-ci-gate.ts:216-225`). 그래서 결함으로 세지 않았다. 이 문서의 e2e 수는 게이트 로그에서 셌다.
|
||||
|
||||
**(4) FE-GATE-013**
|
||||
|
||||
- 게이트 로그(CI env, rc=1, 2 s): `test:system`의 사전 점검이 `this host does not allow unprivileged user and network namespaces …`로 멈춘다. bwrap 명령 전체, `exited 1`, stderr `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`, 호스트 설정 `kernel.apparmor_restrict_unprivileged_userns = 1, kernel.unprivileged_userns_clone = 1, user.max_user_namespaces = 113201`, 고치는 방법 셋, 러너 요구 문서를 적는다.
|
||||
- 사전 점검 뒤 명령(`bbde570-013-parts/summary.txt`): `system-vitest` rc=1(81 s), 나머지 7개 rc=0. `system-vitest.log`: 3파일 중 1 실패, `ci-artifact-contract.test.ts`의 `candidate archive and provider upload boundaries` 18건 실패. 12건은 `sandboxed external provider failed: … bwrap: loopback: Failed RTM_NEWADDR`, 4건은 `:1782`, 2건은 `:1812`의 파일 대기 시간 초과다. 이름은 지난 라운드 분류표(지난 문서 3.2 (3))의 18건과 같다. 코드 결함으로 볼 실패는 없다.
|
||||
- snapshot의 `artifacts/tests/system.xml`은 2026-11-05 20:00 파일이다. 이번 실행은 사전 점검에서 멈춰 junit을 쓰지 않았다. 쓰지 않았다.
|
||||
|
||||
### 3.3 수정이 검사를 약하게 했는가 (`git diff 8a44226..bbde570 -- <영역 경로>`)
|
||||
|
||||
| 변경 | 약해진 것 | 판단 |
|
||||
|---|---|---|
|
||||
| strict fixture의 마지막 판정을 `browserFailureVerdict`로 뺌(`e0255299`) | 어느 spec이든 판정을 바꿔 strict 검사를 끌 수 있다 | 바꾸는 spec은 증명 spec 하나다. 노출은 `allowedBrowserFailure: /.*/`와 같다. 커밋 본문이 적었다. 결함 아님(3.2 (1)(f)) |
|
||||
| `a11y.json` schema v1 → v2(`757d1c7`) | v1은 `scope` = 설치 라우트 전체를 강제했다. v2는 합이 설치 라우트이기만 하면 어떤 분할이든 받는다(`release-artifacts.ts:853-868`) | v1 규칙은 거짓 주장을 강제한 것이다. 분할은 spec의 기록이 정한다. 그 기록을 지키는 test가 없는 것은 11-01에 넣었다 |
|
||||
| SW update 새 test의 firefox skip(`aaa782ba`, `service-worker-update.spec.ts:306`) | 새 test가 firefox에서 돌지 않는다 | 다른 셋과 같은 이유·상수다(`:181-183`). 주인과 만료가 있다. 참고: `check-test-evidence.ts:292-304`는 파일 안에 quarantine 주석이 하나라도 있으면 그 파일의 모든 skip을 받는다. 그래서 새 skip은 새 기록 없이 들어왔다. 예전부터의 검사 동작이다(영역 12 몫, 세지 않음) |
|
||||
| 시각 골든 5장 재촬영(`e02f252d`, 1105/15-05) | 골든이 스크롤바 자리 15 px를 담는다. compact 골든은 overlay 스크롤바 휴대폰보다 15 px 좁다(지난 README §16.3) | `toHaveScreenshot` 허용치·mask는 그대로다(`playwright.visual.config.ts` diff는 경로·포트뿐). 기록된 한계. 결함 아님 |
|
||||
| Playwright 설정 다섯 개(1105/12-04) | — | 출력 경로·포트·`--strictPort`만 바뀌었다. dev 설정은 떠 있는 서버를 더는 쓰지 않는다(`reuseExistingServer: false`). 허용치·재시도·시간 상한 변경 없음. 더 엄격해졌다 |
|
||||
| SW 빌드 복사가 `.tmp`를 건너뜀(`service-worker-builds.ts:65`) | 복사본에 `.tmp`가 없다 | `.tmp`는 다른 실행의 출력이다. `fixture-builds.ts`는 이미 건너뛰었다. 결함 아님 |
|
||||
| OPFS purge test 두 경우로(`23662fb2`) | — | 단언이 늘었다(`removedObjects`). `waitForTimeout(250)`과 OPFS 없을 때 `return`(`opfs-runtime.spec.ts:352`, `:470`)은 예전부터다(5절). 결함 아님 |
|
||||
| reference-save 새 test 셋(`4f3c10bc`) | — | describe에 있던 허용(`reference-save.spec.ts:84-88`, `:161`)을 그대로 쓴다. 넓히지 않았다 |
|
||||
| 사전 점검 bwrap 시험(`9655958b`) | — | 더 엄격해졌다 |
|
||||
| 3번 preload test의 `parent` 단언(`e0255299`) | — | 더 엄격해졌다 |
|
||||
|
||||
이 영역 경로에서 늘린 시간 상한·허용치·예산은 없다(`git diff … | grep -n 'timeout\|retries\|threshold\|maxDiff'`: 옮겨진 줄과 새 test의 30 s 보임 대기 하나).
|
||||
|
||||
## 4. 28개 관점 판정 (36.2)
|
||||
|
||||
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가.
|
||||
|
||||
| 번호 | 관점 | 판정 | 목표·확인 통제 | 증거 | 이유·잔여 위험 |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | 코드 성숙도 | > | — | — | src는 영역 01~09 |
|
||||
| 2 | 구조적 성숙도 | > | — | — | 12·16 |
|
||||
| 3 | 변경 용이성 | P | M3 / M2 | E1 | 기능을 더해도 접근성 spec은 descriptor로 응답 모양과 `notChecked`를 정한다. 시각 골든은 기능 수와 무관하다. 생성 기능 설치 상태의 브라우저 게이트는 결정 대기(1105/16-03) |
|
||||
| 4 | 인지 부하 | P | M2 / M2 | E1 | fixture·증명 spec 주석이 판정 위치를 적는다(`strict-browser-test.ts:27-51`). `a11y.json` 분류 규칙은 `a11y-data-state.ts` 머리 주석에만 있다(11-01). 빌드 helper 두 벌(0929/11-07) |
|
||||
| 5 | 위험 가시성 | P | M3 / M2 | E3(FE-GATE-009 산출물, 11-R2·R3) | 실패 화면 라우트가 `notChecked`로 드러난다(1103/11-01). 그 분류는 기록이 없으면 "검사함"으로 기운다. 기록 한 줄을 바꾸면 증거가 다시 passed로 적힌다(11-01, 11-R2) |
|
||||
| 6 | 실패 성숙도 | O | M3 / M3 | E3(CI env 1회) | 부트 오류 화면, 구 탭 1회 reload, 429 재시도·불명 결과 저장과 포커스, 깨진 SW 해제, 이전 캐시 응답, 지워진 route를 B 워커 아래 같은 문서에서 열기가 FE-GATE-008에서 통과했다(SW 넷은 chromium·webkit, firefox quarantine) |
|
||||
| 7 | 운영 성숙도 | P | M3 / M1 | E1 | drill은 거짓 PASS를 내지 않지만 PASS 경로가 없다(0929/11-02) |
|
||||
| 8 | 디버깅 가능성 (깊게) | P | M3 / M3(사전 점검), M2(provider test) | E3·E1 | `test:system`이 호스트 원인과 고치는 방법을 적고 멈춘다(1105/12-01). preload·console 실패는 줄 단위로 찍힌다. 사전 점검을 넘긴 뒤 provider가 못 뜨면 6건은 여전히 원인 없이 시간 초과로만 보인다(1105/11-02 잔여) |
|
||||
| 9 | 유지보수 성숙도 | P | M2 / M2 | E1 | helper 제외 목록을 손으로 맞췄다(0929/11-07). 규모 기준선 재측정은 영역 15 |
|
||||
| 10 | 테스트 성숙도 (깊게) | P | M3 / M3(fixture 증명), M2(a11y 분류) | E3(CI env 게이트, 배치 변이 3건)·E1 | 강점: strict fixture의 기록과 판정을 커밋된 test가 양쪽 방향으로 고정한다(1105/11-01, 11-R1에서 변이 셋 모두 잡힘). 실패 화면 라우트를 증거에서 뺀다(생성 기능 상태 포함, 11-R3). e2e·capability가 21·3건 늘었고 사라진 test가 없다. 약점: `notChecked` 분류를 지키는 test 없음(11-01). provider 묶음은 이 호스트에서 확인 불가(1103/11-03·11-04) |
|
||||
| 11 | 데이터 성숙도 | - | — | — | 이 영역에 데이터 이관 경로가 없다 |
|
||||
| 12 | 동시성 성숙도 | P | M3 / M2 | E1 | 세 엔진이 같은 a11y 기록을 쓰므로 임시 파일 뒤 rename한다(`a11y-data-state.ts:44-47`). OPFS purge test는 `waitForTimeout(250)`으로 경쟁 경로를 노린다(5절) |
|
||||
| 13 | 확장성 | P | M3 / M2 | E3(11-R3)·E1 | 접근성 spec·시각 골든이 기능 추가에 손대지 않고 돈다. 생성 기능의 상세 라우트는 spec 수정 없이 `notChecked`로 간다(11-R3). 생성 기능 설치 상태의 게이트 실행은 결정 대기(1105/16-03) |
|
||||
| 14 | 성능 성숙도 | > | — | — | 15. 이 영역 관련: strict fixture의 page.route가 모든 browser test의 HTTP cache를 끈다(5절, 지난 라운드부터) |
|
||||
| 15 | 보안 성숙도 | > | — | — | 13. `.git` 가림의 실행 증거는 이 호스트에서 얻을 수 없다(1103/11-04) |
|
||||
| 16 | 의존성 성숙도 | P | M3 / M2 | E1 | 시각 글꼴 패키지를 CI가 설치한다. 깨끗한 러너 실행은 없다(1103/11-02). `test:system`의 호스트 요구가 적혔다(1105/12-01) |
|
||||
| 17 | API / Contract | > | — | — | 07. `a11y.json` schema 2는 CHANGELOG BREAKING으로 알렸다(3.2 (2)) |
|
||||
| 18 | 배포 성숙도 (깊게) | P | M3 / M3(브라우저), M1(drill) | E3(CI env 1회) | 구 탭 청크 복구(세 엔진), SW A→B 업데이트와 지워진 route(chromium·webkit), CI 식별값 빌드의 compact smoke가 CI env로 통과했다. drill로 provider 전환을 기록할 수 없다(0929/11-02). 실제 러너 미실행(U-1) |
|
||||
| 19 | 설정 성숙도 | P | M3 / M2 | E3·E1 | 포트를 실행마다 고르고 worker가 같은 값을 읽는다(`run-isolation.ts:127-145`, resumable spec 통과). a11y 증거는 기본 경로 고정(12-04 한계) |
|
||||
| 20 | 개발자 경험 (깊게) | P | M3 / M2 | E3·E1 | 지원 안 되는 호스트에서 사전 점검이 이유를 말한다(1105/12-01). 한 checkout에서 merge 단계를 차례로 돌리면 FE-GATE-009가 FE-GATE-008의 e2e junit·report를 덮는다(3.2 (3) 주의, 결함 아님) |
|
||||
| 21 | Guardrail 성숙도 (깊게) | P | M3 / M2 | E3(CI env) | merge 단계 CI env에서 FE-GATE-001~012·020 통과. 013은 사전 점검에서 호스트 원인으로 멈춘다. `forbidOnly`·quarantine 만료·mask 규칙 fixture가 기대대로 실패한다. strict fixture는 이제 자기 검사를 지키는 test가 있다. a11y 분류는 없다(11-01). quarantine 검사가 파일 단위다(3.3, 영역 12 몫) |
|
||||
| 22 | 추상화 성숙도 | P | M2 / M2 | E1 | 판정을 fixture 하나로 빼서 증명 spec이 바꿀 수 있다. helper 두 벌(0929/11-07) |
|
||||
| 23 | 일관성 | P | M2 / M2 | E1 | 모든 browser spec이 같은 strict fixture를 쓴다(`chunk-load-error.spec.ts` 하나만 맨 test). fixture 콜백 이름은 lint 범위 때문에 fixture 파일은 `use`, spec은 `provide`다 |
|
||||
| 24 | 네이밍 / 의미 | P | M2 / M2 | E1 | `automatedStatus: "passed"`는 이제 `scope`만 뜻한다. schema 주석이 적는다(`release-artifacts.ts:833-839`). 값 이름만 보면 전체 통과로 읽힌다 |
|
||||
| 25 | 조직 확장성 | > | — | — | 14 |
|
||||
| 26 | Ownership 성숙도 | P | M2 / M2 | E1 | quarantine에 owner·만료가 있다. `test:system` 러너 요구가 문서·gate 정의에 적혔다(1105/12-01) |
|
||||
| 27 | 삭제 가능성 | P | M2 / M2 | E1 | 참조 기능을 지우면 `REFERENCE_RESOURCE_DETAIL`도 레지스트리에서 빠지고 report는 설치 라우트만 읽는다(`write-a11y-report.ts:14`). 3번 preload test는 기능 실행부 모양이 바뀌면 이유를 적고 실패한다(커밋 본문의 알려진 비용) |
|
||||
| 28 | 회복 가능성 | P | M3 / M3(브라우저), M1(drill) | E3(CI env 1회) | 깨진 SW 해제와 구 탭 청크 복구가 통과했다. provider 전환 뒤 smoke를 drill 증거로 넣을 방법이 없다(0929/11-02) |
|
||||
|
||||
집계(적용 21개): 충족 1(6) · 부분 충족 20 · 미충족 0 · 미검증 0 · 적용 제외 1(11) · 다른 영역 6(1, 2, 14, 15, 17, 25).
|
||||
지난 라운드와 달라진 곳: 판정 기호는 같다. 8은 사전 점검이 원인을 말하게 되어 확인 통제가 M3로 올랐다(잔여는 provider test 6건). 10은 fixture 증명이 M3로 올랐고 a11y 분류가 새 약점이다. 5는 근거가 1103/11-01 잔여에서 11-01로 바뀌었다.
|
||||
|
||||
## 5. 미검증
|
||||
|
||||
| 무엇 | 왜 확인하지 못했나 | 무엇이 있으면 확인할 수 있나 |
|
||||
|---|---|---|
|
||||
| 11-01이 FE-GATE-009 전체(세 엔진)와 다른 게이트에서도 놓치는지 | 11-R2는 chromium 한 엔진의 `test:a11y` 경로만 돌렸다. unit test와 증거 schema가 spec을 읽지 않는다는 것은 코드로 봤다 | 같은 변이로 `ci:gate -- FE-GATE-009`와 `test:unit` |
|
||||
| 지난 실행의 a11y 기록이 다음 실행에 쓰이는 경우 | 11-R2 뒤 다른 항목의 `INVOICE_DETAIL.json`이 남아 있었다. 이번에는 설치되지 않은 라우트라 읽히지 않았다 | 같은 ID 라우트를 다시 설치하고 그 test를 건너뛴 실행 |
|
||||
| 1103/11-03·11-04의 완료 기준, `.git` 가림 변이 | desktop의 bwrap이 user namespace를 못 쓴다(FE-GATE-013 사전 점검). 노트북 실행 금지 | user namespace를 허용하는 호스트에서 `test:system`과 가림 삭제 변이 |
|
||||
| 1103/11-02 깨끗한 러너의 글꼴 단계 | U-1 | 글꼴 없는 Ubuntu 24.04 컨테이너나 러너 1대 |
|
||||
| 3번 preload test의 지연이 실제로 걸리는지 | 단언이 없다. 시간만 간접 증거다 | route handler가 불렸는지 flag로 단언 |
|
||||
| page.route가 끄는 HTTP cache의 영향 | 근거가 Playwright 문서뿐이다(지난 라운드부터). HTTP cache 동작을 단언하는 test는 없다 | cache 동작을 보는 test를 만들 때 fixture 밖에서 돌거나 fixture에 적는다 |
|
||||
| `opfs-runtime.spec.ts`의 OPFS 미지원 엔진 조용한 통과(`:352`, `:470` `return`) | 지난 라운드부터 있던 모양. FE-GATE-008에서 세 엔진 모두 2.6~6.2 s 걸려 실제로 돈 것으로 보인다(추론) | test가 지원 여부를 단언하거나 `test.skip`으로 이름을 남김 |
|
||||
| 엔진마다 a11y 분류가 다를 때 | 지금 상세 페이지는 엔진과 상관없이 같은 GET을 보낸다. 다르면 마지막에 쓴 엔진이 정한다(`a11y-data-state.ts:44-47`) | 엔진별 기록 또는 불일치 시 실패 |
|
||||
| 0929/11-04 lab 판정 뒤집힘 | 이번 공유 lab 실행은 1회다 | 같은 빌드 반복 실행(영역 15) |
|
||||
| CI 러너 위 FE-GATE-008·009·013 | U-1 | 러너 1대와 PR 1건 |
|
||||
|
||||
## 6. 실행 기록
|
||||
|
||||
이 영역이 직접 돌린 실행은 없다. desktop에서는 `/tmp/claude-gates/` 아래 파일을 읽기만 했다(`cat`, `grep`, `ls`, `sha256sum`).
|
||||
|
||||
배치 실험(요청 `scratchpad/r5/requests/11.md`, 패치 `scratchpad/r5/requests/11-R1.diff`, `11-R2.diff`, 결과 로그 `desktop:/tmp/claude-gates/r5/batch/out/R5-11-R{1,2,3}.log`, 사본 `scratchpad/r5/a11/R5-11-R{1,2,3}.log`). 패치 둘은 노트북 worktree에서 `git apply --check`로 `bbde570`에 붙는 것을 확인했다. 오케스트레이터가 desktop checkout(`bbde570`)에서 local env로 하나씩 돌렸고, 셋 모두 `restore=clean`이다. 3건 모두 기대와 같은 결과였다. 11-R2만 기대와 한 곳이 달랐다(아래).
|
||||
|
||||
| ID | 명령(요약) | 변이 | rc · 시간 | 결과 |
|
||||
|---|---|---|---|---|
|
||||
| 11-R1 | `playwright test tests/e2e/preload-use.spec.ts` 세 엔진 | `strict-browser-test.ts` M1 `:91` 기록 버림, M2 `:17` 정규식 `/.*/u`, M3 `:58-63` 기본 판정 expect 제거 | 1 · 27.2 s · 2.17 | 기대대로. 9 failed: 세 엔진 × `:209`("what the strict fixture recorded" Expected length 1, Received 0), `:234`(Expected 4, Received 1), `:259`("Expected to fail, but passed."). 9 passed: `:89`, `:100`, `:124` 세 엔진 |
|
||||
| 11-R2 | `accessibility.spec.ts` chromium `--grep '@a11y /'` 뒤 `write-a11y-report.ts`, `a11y.json` 출력 | `accessibility.spec.ts:83` reason → `null` | 0(`playwright rc=0`, `report rc=0`) · 20.3 s · 3.65 | 기대대로(놓침). 10 passed, "not checked" 줄 없음. `a11y.json` `scope` 10개(`REFERENCE_RESOURCE_DETAIL` 포함), `notChecked: []`. 기대와 다른 한 곳: 기록 디렉터리가 비지 않고 다른 항목의 `INVOICE_DETAIL.json`(04:31)이 남아 있었다. 설치되지 않은 라우트라 report가 읽지 않았다 |
|
||||
| 11-R3 | `create:feature sample-feature --with-create` 뒤 같은 명령 | 없음 | 0(`playwright rc=0`, `report rc=0`) · 25.5 s · 2.98 | 기대대로. 생성 명령 성공(라우트 `SAMPLE_LIST` `/sample`, `SAMPLE_DETAIL` `/sample/items/:sampleId`, `SAMPLE_CREATE` `/sample/new`). 13 passed. report 두 줄(`REFERENCE_RESOURCE_DETAIL`, `SAMPLE_DETAIL … SAMPLE_GET_ITEM reads one resource`). `scope` 11개(`SAMPLE_LIST`·`SAMPLE_CREATE` 포함), `notChecked` 2개 |
|
||||
|
||||
인용한 출력(이 영역이 돌린 것 아님):
|
||||
|
||||
| 출력 | 결과 |
|
||||
|---|---|
|
||||
| `bbde570-ci/summary.txt`(CI env, 03:24 시작, load 0.98) | FE-GATE-020 rc=0 1,237 s · 001 3 s · 002 18 s · 003 27 s · 004 2 s · 005 132 s · 006 10 s · 007 28 s · **008 rc=0 196 s** · **009 rc=0 51 s** · 010 63 s · 011 8 s · 012 6 s · **013 rc=1 2 s**. 끝에 checkout 복원 `clean=yes` |
|
||||
| FE-GATE-008 게이트 로그(`8b852193…`) | e2e 226건: 222 passed, 4 skipped(firefox SW quarantine), 2.1 m, 6 workers. capability 69 passed(43.4 s), "Browser capability evidence: PASS (23 cases x 3 engines, zero skipped)". storybook 1 passed. visual 6 passed. "Test evidence: PASS (433 files, 5 baselines …)". 금지 fixture 넷 `EXPECTED_FAILURE`. 재시도·flaky 없음 |
|
||||
| FE-GATE-009 게이트 로그(`82693359…`) | `test:a11y` 60 passed(48.6 s), `a11y: REFERENCE_RESOURCE_DETAIL not checked in its own state (…)`. `review:a11y-manual -- --format-only` PASS(10 routes) |
|
||||
| FE-GATE-013 게이트 로그(`789acdcb…`) | 사전 점검에서 멈춤(3.2 (4)) |
|
||||
| `bbde570-013-parts/summary.txt` | `system-vitest` rc=1 81 s(18 failed, 3.2 (4)), `verify:reproducible-build`·`build:release-candidate`·`verify:local-evidence`·`check:supply-chain:fixtures`·`check:supply-chain:provider-fixtures`·`check:security:fixtures`·`check:browser-security` rc=0 |
|
||||
| snapshot `r5/snap/merge/` | `artifacts/tests/a11y.json`(03:53), `a11y-data-state/REFERENCE_RESOURCE_DETAIL.json`(03:52), `unit.xml`(03:46, `a11y-report.test.ts` 5건 통과). `e2e/results.xml`(03:53)은 FE-GATE-009의 60건이다(3.2 (3) 주의). `system.xml`(2026-11-05 20:00)은 지난 파일이라 쓰지 않았다 |
|
||||
| 비교: `r4/snap/artifacts/quality/gates/FE-GATE-00{8,9}.txt`(merge-48, `8a44226`) | e2e 205(202 passed, 3 skipped), capability 66, storybook 1, visual 6, test evidence 416 파일, a11y 60 |
|
||||
|
||||
## 7. 새 발견 요약
|
||||
|
||||
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|
||||
|---|---|---|---|---|
|
||||
| 11-01 | Low·P3 | 구조적 위험 | `a11y.json`의 `notChecked` 분류를 지키는 test가 없고 기록이 없는 라우트를 "검사함"으로 세서, spec의 기록 호출 한 줄을 바꾸면 상세 라우트가 다시 passed로 세지고 `test:a11y` 경로는 rc=0이다(11-R2) | `tests/e2e/accessibility.spec.ts:77-84`, `scripts/lib/a11y-data-state.ts:50`, `:61`, `scripts/contracts/release-artifacts.ts:853-868`, `tests/unit/a11y-report.test.ts:86-92` |
|
||||
@@ -0,0 +1,197 @@
|
||||
# 영역 12 — 가드레일·CI
|
||||
|
||||
> 검토일 2026-11-06 · 기준 `bbde570` (PR B 끝, `fix/maturity-review-2026-11-05-b`) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
|
||||
> 경로: `scripts/check-*.ts`·`scripts/verify-*.ts`·`scripts/lib/`, `.gitea/workflows/`, `config/ci/`, `eslint.config.ts`, `tsconfig*.json`, `.dependency-cruiser.json`, `CLAUDE.md`. 함께 본 것: `config/performance/budgets.json`, `config/scale/feature-shape-ceilings.json`, `config/contracts/backend-contract-pin.json`, `scripts/lib/run-isolation.ts`와 Playwright 설정 다섯, `scripts/lib/removal-fixture.ts`, `scripts/lib/vite-build-inputs.ts`, README merge 게이트 절
|
||||
> 깊게 본 관점: 5, 10, 19, 21, 23
|
||||
> 렌즈: 1105/12-01~12-04의 완료 기준 · `8a44226..bbde570`에서 약해진 검사 · D7(초기 JS 예산 상향) 뒤에도 예산 검사가 실패하는가 · 통합 때 고친 목록 셋(제거 fixture 문서 테스트, vite 빌드 입력, CI 기준선)
|
||||
> 영역 판정(35.8): **조건부 사용 가능.** 지난 라운드 P1 하나(12-01)와 12-02는 고쳐졌다. 이 desktop에서 FE-GATE-013은 이제 첫 단계에서 이유와 고치는 법을 적고 멈춘다. 조건은 셋이다. (1) FE-GATE-013은 비특권 user namespace를 허용하는 호스트에서만 통과한다. 이 desktop은 허용하지 않는다. 어떻게 셀지는 사용자 결정이다. (2) `CLAUDE.md`의 리뷰 게이트 목록은 이 기준에서 그대로다(12-03, 고친 커밋은 PR #6에만 있다). (3) 게이트는 한 checkout에서 하나씩 돌린다. 실행 격리는 Playwright 실행까지다(12-04. 오케스트레이터 드릴에서 e2e 두 실행이 함께 통과했다).
|
||||
|
||||
ID 표기: 이 문서의 `12-NN`은 2026-11-06 라운드 ID다. 지난 라운드는 `1105/12-NN`, 그 전은 `1103/…`, `1101/…`, `0929/…`로 적는다.
|
||||
|
||||
## 0. 결론
|
||||
|
||||
- **1105/12-01은 고쳐졌다.** 사전 점검이 provider와 같은 namespace 옵션으로 `bwrap … /bin/true`를 띄운다(`scripts/check-system-test-prerequisites.ts:39-43`, `:90-95`). 이 desktop의 merge 실행에서 FE-GATE-013은 2초 만에 "this host does not allow unprivileged user and network namespaces"와 bwrap stderr, sysctl 값, 고치는 법 셋을 적고 멈췄다(`desktop:/tmp/claude-gates/bbde570-ci/gate-artifacts/FE-GATE-013.txt`). 러너 요구는 문서 셋, README, `gates.json`의 `hostRequirements`, workflow 주석에 있다. gate 모양 해시도 이 요구를 본다(`scripts/contracts/ci-gates.ts:508`, `:519`). 허용 호스트에서 PASS하는지는 가짜 호스트 단위 테스트뿐이다.
|
||||
- **FE-GATE-013은 이 호스트에서 실패한다. 있는 그대로 적는다.** 사전 점검 뒤 명령을 따로 돌린 결과: `tests/system` 114건 중 96건 통과, 18건 실패. 18건은 모두 `ci-artifact-contract.test.ts`의 provider 경계 테스트이고 오류 원문은 `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`다. 뒤 명령 7개는 모두 통과했다(`desktop:/tmp/claude-gates/bbde570-013-parts/summary.txt`). 어떻게 셀지는 사용자가 정한다.
|
||||
- **1105/12-02는 고쳐졌다.** 짝 백엔드 참조를 pin 커밋의 트리에서 찾는다(`scripts/verify-documentation-readiness.ts:245-285`). desktop 로컬 실행은 PASS_SCOPED이고 미확인 줄이 없다. 짝이 없는 실행은 PASS_SCOPED에 "17 reference(s) … not verified (… pinned at 45d2a478b800: no checkout …)"다. 세 경우(pin 뒤 HEAD, pin 없는 checkout, 저장소 이름 오타)는 stub git 저장소 단위 테스트가 본다.
|
||||
- **1105/12-03은 이 기준에서 남음이다.** `CLAUDE.md:23`이 그대로 명령 11개를 손으로 적는다. 고친 커밋 `e9d9c36`은 PR #6 브랜치(`claude/mystifying-carson-f61c35`)에만 있고 `CLAUDE.md`만 바꾼다. README의 14개 반복문(`README.md:343`)은 그 커밋 밖이다.
|
||||
- **D7 뒤에도 예산 검사는 예산을 넘는 빌드를 실패시킨다(12-R1).** entry를 약 3.5 KB 키운 빌드에서 `check:bundle`이 "initial JavaScript 210352 gzip bytes > budget 206848 (over by 3504)"로 rc=1이었다. `check:bundle`은 예산을 실행 때 `budgets.json`에서 읽고(`scripts/check-bundle.ts:30-32`), 자가 fixture도 `예산+1`로 만든다(`:56-97`). 드릴 사본도 같은 파일을 읽는다: FE-GATE-020에서 "initial JS 205465 / 206848"(`FE-GATE-020.txt:6206`). 함께 움직인 다른 한도는 없다. `initialJsFiles` 32, lazy chunk 122,880 B, lab 셋은 그대로다. 새로 생긴 것은 `featureRouteInteractionMs` 500 ms 하나다.
|
||||
- **새 발견 2건, 둘 다 Low·P3.** 12-01: 제거 fixture가 문서를 읽는 테스트를 파일째 빼서, capability 제거 드릴 사본 셋에서 `backend-contract-pin.test.ts`의 문서와 무관한 14건도 빠진다(검사 약화). 12-02: 1105/12-04 수정 뒤 빌드는 `RUN_OUTPUT_ROOT` 아래에 쓰는데, 빌드 뒤 검사(`generate-supply-chain.ts`, `check-bundle.ts`)는 루트를 읽는다. 그 변수를 셸에 두면 `check:bundle`이 이전 빌드로 판정한다. 12-R2에서 `.tmp/` 아래 빌드의 entry는 7,321 B, 루트는 1,065 B였는데 `check:bundle`은 루트 숫자 204,111 B로 PASS했다(같은 변이를 루트에 빌드하면 12-R1처럼 실패한다).
|
||||
- **0929/12-03은 일부로 본다(§16.6은 고침).** `support/` → `src/adapters/` 직접 간선은 이제 막힌다. `support/` → 자기 기능 `adapters/` → `src/adapters/`의 두 단계 경로에는 규칙이 없다. 12-R3에서 presentation이 `support/`를 거쳐 `createReferenceHttpGateway`를 다시 내보내도 `check:architecture`(421 modules)와 ESLint가 둘 다 통과했다.
|
||||
- **나머지 이월 6건은 남음이다.** 0929/12-01·12-04·12-05·12-06·12-07, 1101/12-03. 해당 파일이 바뀌지 않았다.
|
||||
|
||||
## 1. 범위 (36.1)
|
||||
|
||||
| 항목 | 기록 |
|
||||
|---|---|
|
||||
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`, 영역 12 |
|
||||
| 커밋·작업 상태·확인 시점 | `bbde570`. 노트북 worktree `happy-easley-233d07`(HEAD = 기준, 미추적 `AGENTS.md`만)에서 읽었다. 2026-11-06 |
|
||||
| 목적과 지원 실행 구성 | 템플릿. 브라우저 SPA + 정적 호스팅 + Service Worker. CI는 `config/ci/gates.json`에서 생성한 Gitea Actions workflow. merge job은 `runs-on: ubuntu-latest`(`.gitea/workflows/quality-gates.yml:39`) |
|
||||
| 필수 요구와 규모·운영 목표 | 짝 백엔드 템플릿과 함께 빨리 출시한다. CI 시간·실패율 목표는 없다 |
|
||||
| 읽은 코드·구성 범위 | 영역 커밋 전부: `9655958`, `67082cc`, `fc95672`, `a37ebba`, 12-04의 `ddbda4d`·`f4d5761`·`0e72c0c`·`510e2bb`, D7의 `0fee3fe`·`287dc6f`, 합친 커밋 `c3c595f`·`703a335`·`b8d53c9`. 전체로 읽은 파일: `check-system-test-prerequisites.ts`, `lib/provider-sandbox-namespaces.ts`, `lib/run-isolation.ts`, `lib/vite-build-inputs.ts`, `lib/feature-scaffold-drill.ts`, `check-bundle.ts`, `lib/performance-budgets.ts:1-80`, `playwright.config.ts`, `playwright.dev.config.ts`. 부분: `verify-documentation-readiness.ts:240-290`·`:370-530`, `lib/removal-fixture.ts:25-175`, `run-ci-gate.ts:30-70`·`:170-230`, `generate-supply-chain.ts:140-160`·`:300-330`, `build-frontend.ts:36-90`, `generate-build-manifest.ts:25-60`, `.dependency-cruiser.json` 전체 규칙, `contracts/ci-gates.ts:290-302`·`:500-522`, 단위 테스트 7파일(`system-test-prerequisites`, `ci-workflow-generation` 해당 절, `documentation-readiness:264-330`, `backend-contract-pin`, `removal-fixture:135-180`, `vite-build-inputs`, `playwright-run-isolation` 머리) |
|
||||
| 읽은 문서(주장) | `CLAUDE.md:23`, `README.md:330-367`, `docs/operations/ci-quality-gates.md:15-32`·`:180-238`, `docs/security/supply-chain.md:183-194`, `docs/testing/taxonomy.md:15`·`:64-71`, `docs/testing/frontend-platform-testing-strategy.md:996-1060`(13.6), `docs/operations/performance-evidence.md:1-55`, `docs/README.md:43-53`, 지난 라운드 12번 문서, 지난 README 14~16절, 커밋 본문 |
|
||||
| 게이트 결과 | **merge stage, CI env**(메인 세션, 2026-11-06 03:24~03:56, `desktop:/tmp/claude-gates/bbde570-ci/summary.txt`): FE-GATE-001~012·020 rc=0(020 1,237초, 008 196초), **FE-GATE-013 rc=1**(2초, 사전 점검에서 멈춤). FE-GATE-013의 뒤 명령(`bbde570-013-parts/`): `test:system`의 vitest 81초 rc=1(96/114), 나머지 7개 rc=0. **공유 실행**(오케스트레이터, 로컬 env, `desktop:/tmp/claude-gates/r5/snap/`): `verify-documentation.local.txt` PASS_SCOPED(미확인 줄 없음), `verify-documentation.no-sibling.txt` PASS_SCOPED + 17개 미확인, `build.txt` 성공, `lab.txt` PASS |
|
||||
| 수행한 테스트·실험 | **실행 환경 = desktop 로그와 snapshot.** 노트북에서는 읽기만 했다. 요청 3개를 오케스트레이터가 하나씩 돌렸다(`desktop:/tmp/claude-gates/r5/batch/out/R5-12-R1.log`~`R3.log`, 셋 다 `restore=clean`): `12-R1`(예산을 넘는 빌드에서 `check:bundle`), `12-R2`(`RUN_OUTPUT_ROOT`를 둔 `check:bundle`), `12-R3`(0929/12-03 두 단계 경로). 요청서 `scratchpad/r5/requests/12.md`. 12-04 완료 드릴은 오케스트레이터가 따로 돌렸다(`R5-01-1204-drill.log`). ssh로는 `/tmp/claude-gates/` 아래 로그만 읽었다 |
|
||||
| 확인하지 못한 범위·이유 | 실제 Gitea runner(Actions 꺼짐). user namespace를 허용하는 호스트의 사전 점검과 `test:system`. 12-04의 게이트 단위 동시 실행(드릴은 e2e 실행 단위였다). desktop 옆 백엔드 checkout의 HEAD(규칙상 `/tmp/claude-gates` 밖은 읽지 않는다) |
|
||||
| 이전 리뷰와 비교 가능한 범위 | `8a44226..bbde570`의 영역 커밋. 지난 실행 결과는 현재 증거로 다시 쓰지 않았다. 지난 12-R3 변이(`support/` → http 배럴)는 이번에 그래프 회귀 fixture로 들어왔다 |
|
||||
|
||||
## 2. 지난 발견 재확인
|
||||
|
||||
### 2.1 상태
|
||||
|
||||
| 지난 ID | 내용 | 상태 | 근거 |
|
||||
|---|---|---|---|
|
||||
| 1105/12-01 | FE-GATE-013의 user namespace 전제가 요구 목록·사전 점검에 없음 (Medium·P1) | **고쳐짐**(허용 호스트 PASS는 단위 테스트만) | **완료 기준 1절(이 desktop에서 exit 1, 제한을 이름으로):** 충족. FE-GATE-013 로그가 사전 점검 보고서로 끝난다. 원문: "this host does not allow unprivileged user and network namespaces …", "probe: /usr/bin/bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net --ro-bind / / -- /bin/true exited 1", "bwrap stderr: bwrap: loopback: Failed RTM_NEWADDR …", "host settings: kernel.apparmor_restrict_unprivileged_userns = 1, …", 고치는 법 셋(`FE-GATE-013.txt`, E3). 코드: 옵션 목록은 한 상수이고 provider와 점검이 같이 쓴다(`scripts/lib/provider-sandbox-namespaces.ts:13-18`, `scripts/run-and-validate-provider.ts:257`, `scripts/check-system-test-prerequisites.ts:39-43`). **2절(허용 호스트 PASS):** 가짜 호스트 단위 테스트뿐이다(`tests/unit/system-test-prerequisites.test.ts:46-55`, 5건 통과 `FE-GATE-005.txt:255`). 실제 허용 호스트는 없다(5절). **3절(요구 목록 세 곳):** `docs/operations/ci-quality-gates.md:198-238`, `docs/security/supply-chain.md:186-193`, `docs/testing/taxonomy.md:15`·`:64-71`. 더해서 README(`README.md:335-338`), `config/ci/gates.json:2040-2043`, workflow 주석(`.gitea/workflows/quality-gates.yml:37-38`). 요구를 지우거나 바꾸면 기준선이 실패한다(`scripts/contracts/ci-gates.ts:508`, `:519`, 테스트 `tests/unit/ci-workflow-generation.test.ts:582-602`, 435건 통과 `FE-GATE-005.txt:41`). **§16과 다른 점:** §16.2 D4는 "PR A `9655958`, 기준선 `67082cc`"라고 적는다. `67082cc`는 PR A 끝 `a793b83`의 조상이 아니다(`git merge-base --is-ancestor` 거짓). PR B의 `c3c595f`로 들어왔다. PR A만으로는 `hostRequirements`가 gate 모양 해시 밖이었다. 기록 오류이고 기준 상태는 맞다. **경계:** provider job 둘(`quality-gates.yml:225`, `:271`)에는 주석이 없다. 그 job의 러너 전제는 1101/13-03(영역 13)이다 |
|
||||
| 1105/12-02 | 문서 검사가 짝 백엔드를 pin이 아니라 옆 작업 트리에서 찾음 (Low·P2) | **고쳐짐** | 짝 목록과 커밋을 pin 파일에서 읽는다(`scripts/verify-documentation-readiness.ts:245-251`). 옆 checkout에 pin 커밋이 있으면 `git ls-tree -r -t <pin>`으로 찾는다(`:255-272`). 없으면 이유(HEAD, pin 12자)와 함께 미확인으로 남긴다(`:263-267`, `:521-527`). pin에 없는 저장소로 나가는 `../` 링크는 실패다(`:277`). **완료 기준:** (가) pin 없는 checkout → PASS + 미확인: 단위 테스트 "reports the references as not verified when the checkout does not have the pinned commit"(`tests/unit/documentation-readiness.test.ts:311-322`). desktop 옆 checkout은 이제 pin 커밋을 가진 것으로 보인다. 로컬 실행에 미확인 줄이 없다(`r5/snap/verify-documentation.local.txt`, 출력 조건 `:519-527`). (나) pin 뒤 HEAD → pin 트리와 같은 결과: 단위 테스트 `:279-309`(pin 뒤 커밋과 미커밋 파일이 `missingPaths`). (다) 저장소 이름 오타 → 실패: `:325-330`. 22건 통과(`FE-GATE-005.txt:180`). 짝 없는 실행: PASS_SCOPED + 17개 미확인, 이유에 pin을 적는다(`verify-documentation.no-sibling.txt`, E3) |
|
||||
| 1105/12-03 | `CLAUDE.md` 리뷰 게이트 목록이 merge stage와 다름 (Medium·P2) | **남음**(이 기준) | `CLAUDE.md:23`이 명령 11개를 그대로 적는다(`git log 8a44226..bbde570 -- CLAUDE.md` 0건). 고친 커밋 `e9d9c36`은 `claude/mystifying-carson-f61c35`(원격 `docs/improvement-manual`, PR #6)에만 있다. PR #6은 이 라운드 범위 밖이라 내용은 판정하지 않는다. 그 커밋의 변경 파일은 `CLAUDE.md`와 `docs/improvement/` 셋이다(`git show --stat`). 완료 기준의 "README도 손으로 나열하지 않는다"는 그 커밋 밖이다. `README.md:343`이 14개 ID를 손으로 적는다(지금은 merge stage와 같다). 이번 라운드는 오케스트레이터가 merge stage를 `ci:gate`로 따로 돌려 메웠다(BRIEF §1) |
|
||||
| 1105/12-04 | 한 checkout 두 실행이 고정 출력·포트로 부딪힘 (Medium·P2) | **오케스트레이터 판정.** 드릴: e2e 실행 단위 통과. 내 판단: 게이트 단위는 남음 | **된 것:** Playwright 설정 다섯이 `TEST_RUN_ID`로 결과·report·JUnit·서빙 빌드를 `.tmp/runs/<id>/`에 둔다(`playwright.config.ts:18-42`, `scripts/lib/run-isolation.ts:42-60`). 빌드 단계는 `RUN_OUTPUT_ROOT`를 읽는다(`scripts/build-frontend.ts:51`, `:66`, `scripts/generate-build-manifest.ts:31`, `vite.config.ts:184-188`). 서버는 빈 포트를 고르고 `--strictPort`, `reuseExistingServer: false`다(`run-isolation.ts:104-145`, `playwright.config.ts:19`, `:39-41`, `playwright.dev.config.ts:16`, `:32-34`). 생성 인덱스는 같으면 쓰지 않고 다르면 rename한다(`ddbda4d`). 단위 테스트 33건·11건 통과(`FE-GATE-005.txt:100`, `:242`). 문서: 테스트 전략 13.6절(`docs/testing/frontend-platform-testing-strategy.md:996-1060`), README(`README.md:362-367`). **안 된 것(코드로 본 것):** `ci:gate`와 증거 검사는 기본 경로만 읽는다. 그래서 게이트는 "한 checkout에 하나씩"으로 문서에만 정했다(`README.md:362-363`, M1). 1105 완료 기준은 게이트 단위("FE-GATE-008과 005, 또는 008 둘을 동시에")다. **오케스트레이터 드릴(`bbde570`, `R5-01-1204-drill.log`):** 한 checkout에서 `TEST_RUN_ID`를 다르게 준 e2e 두 실행을 함께 돌렸다. 부분 실행 19+19 통과, 전체 222+222 통과(각 4 skipped). "already used" 0줄, 포트(41159/46739, 33661/35167)와 출력 폴더가 달랐다. 부분 실행의 ✘ 1건은 실패를 기대하는 test다(`tests/e2e/preload-use.spec.ts:258-265`, `strictTest.fail()`). 그래서 e2e 실행 단위의 동시 실행은 확인됐다(E3). **내 판단:** 문언의 완료 기준(게이트 두 개를 동시에)은 이 드릴로 닫히지 않는다. 코드상 `ci:gate` 둘은 여전히 루트 `dist`와 `artifacts/`를 같이 쓴다. 저장소는 이것을 문서로 막았다(`README.md:362-363`, M1). 둘 다 적고 판정은 오케스트레이터에 둔다. **수정이 만든 결함:** 3절 12-02 |
|
||||
| 1103/12-05 | 문서 검사가 지운 심볼·1절 밖 문서를 안 봄 | **일부**(§16.5와 같다) | `e72fb6e`는 지난 라운드가 든 예 한 곳(테스트 전략 11.2절의 `auth-recovery.test.ts`)만 고쳤다. 지운 심볼 검사와 1절 밖 문서 검사는 결정 대기다(커밋 본문) |
|
||||
| 0929/12-03 | feature 안 layer 밖 폴더에 경계 규칙 없음 | **일부**(§16.6은 고침) | **고친 것:** `feature-and-app-roots-do-not-reach-adapters`의 from이 `src/features/` 전체에서 기능 `adapters/`와 `feature-adapter-contribution.ts`만 뺀다(`.dependency-cruiser.json:302-312`). 지난 12-R3 모양(`support/` → adapter 배럴)이 그래프 회귀 fixture가 됐다(`scripts/check-architecture.ts:823-840`). "31 regression checks PASS"(`FE-GATE-010.txt:4`, 지난 라운드 29). vitest 3건 통과(`tests/architecture/feature-adapter-reach.test.ts`, `FE-GATE-005.txt:766`). **남은 것:** 계층 밖 폴더에서 나가는 간선 중 `src/adapters/`만 막는다. 자기 기능 `adapters/`로 가는 간선은 막지 않는다. 그 규칙의 to는 `^src/adapters/`뿐이다(`.dependency-cruiser.json:309-311`). feature presentation → `support/`도 규칙이 없다(presentation의 금지 목록은 `src/adapters`, `src/bootstrap`, 기능 `adapters/`, `@tanstack`, `:118-127`). 그래서 presentation → `support/x.ts` → `../adapters/reference-http-gateway.ts` → `src/adapters/http/index.ts`의 간선 셋이 모두 규칙을 통과한다(E1). 같은 길로 `@tanstack`과 `src/bootstrap`에도 닿는다. 그래프는 간선 하나씩 본다(규칙 주석 `:303`). **실행(12-R3):** `support/gateway-reexport.ts`가 `../adapters/reference-http-gateway.ts`를 다시 내보내고 `presentation/r5-12-probe.ts`가 그것을 다시 내보내게 했다. `check:architecture` arch-rc=0("421 modules, 1301 dependencies", 무변이 419/1299 `FE-GATE-010.txt:3`, fixture 31 PASS), ESLint eslint-rc=0(`R5-12-R3.log`, E3). 결함 모양은 지난 12-R3과 같고 경로가 한 단계 길어졌을 뿐이다. 그래서 새 발견이 아니라 이 ID의 남은 부분으로 둔다 |
|
||||
| 0929/12-07 | 예외 목록에 담당·재검토 시점 없음 | **남음**(§16.6 결정 대기) | 스키마가 `script`(또는 `path`)와 `reason`뿐이다(`scripts/lib/ungated-scripts.ts:17-30`, `scripts/lib/ungated-tests.ts:20-34`). §16.6은 owner 값을 고르는 결정으로 적었다. 스키마는 그대로다 |
|
||||
| 0929/12-01 | `check:request-fanout`이 반복 횟수·요청 의존을 안 봄 | **남음** | 파일 커밋 0개. receiver 이름 정규식(`scripts/check-request-fanout.ts:23`), 같은 줄 `fanout-reviewed:`만 인정(`:109`) |
|
||||
| 0929/12-04 | CI 계약 크기가 기준선과 테스트 상수 두 곳 | **남음** | `config/ci/contract-baseline.json:6-8`(100/104/110)과 `tests/unit/ci-workflow-generation.test.ts:199-203`(100, 104, 110). 절차 문서에 테스트 갱신 단계가 없다(`docs/operations/ci-quality-gates.md:15-27`). `67082cc`는 해시만 바꿔 이 둘을 건드리지 않았다 |
|
||||
| 0929/12-05 | 실행하지 않는 `dependency-cruiser` 의존성 | **남음** | `package.json:182` `"dependency-cruiser": "18.1.0"`. 검사기는 자기 그래프를 쓴다 |
|
||||
| 0929/12-06 | Vitest 폴더의 `*.spec.ts`를 게이트 안으로 셈 | **남음** | `scripts/lib/ungated-tests.ts:18`(`test|spec`), `:94-95`(폴더 접두어). Vitest는 `*.test.*`만 돈다(`vitest.config.ts:45`) |
|
||||
| 1101/12-03 | 디자인 규칙이 정해진 파일·형식만 봄 | **남음** | `check-design-system.ts`, `lib/design-system-rules.ts` 커밋 0개 |
|
||||
|
||||
참고(§16.5·16.6 밖, 세지 않음): 1101 FOLLOW-UP `noUnusedParameters`는 그대로다(`tsconfig.base.json`, `tsconfig*.json` 커밋 0개). 1101 U-1(Actions 꺼짐)은 미확인이다(Gitea를 부르지 않았다). 1103/12-01의 보존 조건("셸 CSS를 바꾸면 시각 게이트가 여전히 실패")은 여전히 미검증이다(5절).
|
||||
|
||||
요약: 지난 라운드 영역 12의 1105 발견 4건, §16.5 1건, §16.6 7건을 봤다. 고쳐짐 2(1105/12-01·12-02), 일부 2(1103/12-05, 0929/12-03), 남음 7(1105/12-03, 0929/12-01·12-04·12-05·12-06·12-07, 1101/12-03), 재발 0, 틀린 발견 0, 오케스트레이터 판정 1(1105/12-04: e2e 실행 단위 드릴 통과, 게이트 단위는 남았다고 본다). §16과 다르게 본 것: 0929/12-03(고침 → 일부), 1105/12-01의 커밋 위치(`67082cc`는 PR B).
|
||||
|
||||
### 2.2 `8a44226` 이후 바뀐 검사의 약화 여부
|
||||
|
||||
| 바뀐 것 | 판정 | 근거 |
|
||||
|---|---|---|
|
||||
| 초기 JS 예산 `initialJsGzipBytes` 204,800 → 206,848 B(`287dc6f`, D7) | **결정된 상향. 약화로 세지 않는다** | 메인 세션 결정이고, 이유·버린 대안·재검토 조건이 커밋 본문과 `docs/operations/performance-evidence.md:44-53`, CHANGELOG(`CHANGELOG.md:56`)에 있다. 지난 라운드의 파일 상한 25 → 32와 같은 기준이다. **검사 자체는 그대로다:** 예산을 실행 때 읽고(`scripts/check-bundle.ts:30-32`), 비교는 `<=`(`scripts/lib/performance-budgets.ts:23-26`), 자가 fixture는 `예산+1`(`check-bundle.ts:56-97`). 두 파일은 이 범위에서 바뀌지 않았다. 생성 기능 드릴은 사본에서 merge stage를 돌고 `check:bundle`을 빼지 않는다(`scripts/lib/feature-scaffold-drill.ts:26-46`). 사본도 새 예산을 읽었다: "initial JS 205465 / 206848"(`FE-GATE-020.txt:6206`). 템플릿은 CI env에서 204,158 B(`FE-GATE-012.txt:76`). 여유: 템플릿 2,690 B, 드릴 1,383 B. 넘는 빌드의 실제 실패도 확인했다(12-R1: "initial JavaScript 210352 gzip bytes > budget 206848 (over by 3504)", bundle-rc=1). **함께 움직인 한도 없음:** `budgets.json` diff는 이 값과 새 `featureRouteInteractionMs`(500 ms, `81701ad`) 두 줄이다. `initialJsFiles` 32, `lazyChunkGzipBytes` 122,880, lab `lcpMs`·`cls`·`namedInteractionMs`, field 값은 그대로다. `feature-shape-ceilings.json`은 기록(`initialJavascript`)만 다시 적었다(`0fee3fe`). 기록 대조 허용치는 1% → 256 B로 오히려 좁아졌다(`scripts/scale/measure-feature-shape-growth.ts:227`) |
|
||||
| 제거 fixture 문서 테스트 목록 2 → 6(`5c0b37e`, `6d084cf`, 14-01·14-02 커밋, `scripts/lib/removal-fixture.ts:70-81`) | **약화 1건 → 새 발견 12-01** | 새로 넣은 넷 중 `backend-contract-pin.test.ts`는 `8a44226`에서 capability 드릴 사본에서도 돌던 파일이다(그때 목록은 2개, 그 파일은 문서를 읽지 않았다). 이제 문서를 읽는 test 1건 때문에 15건 전체가 빠진다. 나머지 셋은 새 테스트라 전에 돌던 것이 빠진 것은 아니다. 같은 모양이 `feature-tracked-files.test.ts`(문서 무관 1건)에도 있다 |
|
||||
| vite 빌드 입력 목록을 한 모듈로(`c9aa73f`), `run-isolation.ts` 추가(`b8d53c9`, `f4d5761`) | **약화 아님** | 목록은 `scripts/lib/vite-build-inputs.ts:11-21` 하나다. 테스트가 `vite.config.ts`의 상대 import 그래프를 따라가 빠진 파일을 이름으로 실패시킨다(`tests/unit/vite-build-inputs.test.ts:28-46`, `:58-71`, 2건 통과 `FE-GATE-005.txt:275`). 소비자를 `existsSync`로 거르는 것(`:19-22`)은 측정 스크립트를 지우는 샘플 제거 사본 때문이다. 템플릿에서는 둘 다 있고, 측정 스크립트가 없어지면 `feature-shape-growth.test.ts`가 import에서 실패한다 |
|
||||
| `playwright-run-isolation.test.ts`가 capability 설정이 있을 때만 그 설정을 본다(`f4d5761`, `0e72c0c`) | **약화 아님** | `HAS_CAPABILITIES`(`tests/unit/playwright-run-isolation.test.ts:27-42`, `:245`)는 그 설정을 지우는 `test:browser-file-storage-removal` 사본 때문이다. 템플릿에는 파일이 있어 33건이 돈다(`FE-GATE-005.txt:100`) |
|
||||
| gate 모양 해시에 `hostRequirements`(`67082cc`) | **강화** | 1105/12-01. 요구 한 줄을 지워도 기준선이 실패한다(`tests/unit/ci-workflow-generation.test.ts:582-602`) |
|
||||
| `feature-and-app-roots-do-not-reach-adapters` from 확대(`a37ebba`) | **강화** | 0929/12-03. 허용은 바뀌지 않고 금지만 늘었다. 저장소 위반 0(`FE-GATE-010.txt:3-4`) |
|
||||
| dev 설정 `reuseExistingServer: true` → `false`, 서버 넷 `--strictPort`(`0e72c0c`) | **강화** | 남의 서버를 검사하는 길이 막혔다(`playwright.dev.config.ts:32-34`) |
|
||||
| 문서 검사: 짝 checkout에 pin 커밋이 없으면 실패 대신 미확인(`fc95672`) | **약화 아님** | 1105/12-02가 권한 동작이다. 문서와 무관한 실패를 없앤다. 출력에 이유가 남는다(`verify-documentation-readiness.ts:263-267`, `:521-527`). 대신 저장소 이름 오타는 이제 실패한다 |
|
||||
| 문서 검사가 지운 템플릿 기능의 경로를 요구하지 않음(`332bfee`, `50b631e`) | **영역 14가 판정** | 기능의 `feature-module.ts`가 없을 때만이다(`scripts/lib/removable-template-features.ts`) |
|
||||
| `orphanExemptRows`에 `AUTH_REDIRECT_TRANSACTION`(`dc7c95b`) | **영역 05가 판정** | `config/contracts/registry-governance.json:376` |
|
||||
| 새 `skip`·`fixme`·`eslint-disable`·`@ts-ignore` | **영역 12 경로 0건** | `git diff 8a44226..bbde570 -- src scripts tests eslint.config.ts '*.config.ts'`의 추가 줄 검색. 나온 것은 `tests/e2e/service-worker-update.spec.ts`의 firefox skip(기존 줄의 이동과 새 test 1건, 영역 06)과 음성 타입 테스트의 `@ts-expect-error` 2건뿐이다 |
|
||||
|
||||
## 3. 이번 발견 (36.3)
|
||||
|
||||
새 발견 2건: Low 2 / P3 2 / 확인된 결함 1 · 구조적 위험 1. High 이상 없음. P1 없음.
|
||||
|
||||
### 3.1 발견 목록
|
||||
|
||||
| ID | 심각도·우선순위 | 성격 | 관련 관점 | 한 줄 |
|
||||
|---|---|---|---|---|
|
||||
| 12-01 | Low · P3 | 구조적 위험 | 10, 21, 27, 24 | 제거 fixture가 문서를 읽는 테스트를 파일째 빼서, capability 제거 드릴 사본 셋에서 `backend-contract-pin.test.ts`의 문서와 무관한 14건(짝 백엔드 답 표와 Envelope 판정 대조)도 빠진다 |
|
||||
| 12-02 | Low · P3 | 확인된 결함 | 21, 19, 5, 23, 20 | 1105/12-04 수정 뒤 빌드는 `RUN_OUTPUT_ROOT` 아래에 쓰고 빌드 뒤 검사는 루트를 읽어, 그 변수를 셸에 두면 `check:bundle`(FE-GATE-012)이 이전 빌드로 판정한다 |
|
||||
|
||||
### 12-01 제거 fixture가 문서를 읽는 테스트를 파일째 빼서, capability 제거 드릴 사본 셋에서 `backend-contract-pin.test.ts`의 문서와 무관한 14건도 빠진다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 구조적 위험(검사 약화. 빠진 것은 실행으로 확인했고, 그 때문에 놓칠 결함은 확인하지 않았다) |
|
||||
| 관련 관점 | 10, 21, 27, 24 |
|
||||
| 근거 | **목록:** 문서를 복사하지 않는 사본에서는 `REMOVAL_FIXTURE_DOCUMENT_TESTS`의 파일을 지운다(`scripts/lib/removal-fixture.ts:70-81`, `:84-90`, `:160-162`). capability 드릴 셋이 그 사본을 쓴다(`scripts/test-optional-recipe-removal.ts:31`, `scripts/test-browser-file-storage-runtime-removal.ts:69`, `scripts/test-realtime-runtime-removal.ts:54`). 통합 때 `tests/unit/backend-contract-pin.test.ts`를 목록에 넣었다(`5c0b37e`, §16.3). **그 파일:** 15건 중 문서를 읽는 것은 6.1절 표를 읽는 1건뿐이다(`tests/unit/backend-contract-pin.test.ts:263-275`, `:293-303`). 나머지 14건은 config 파일과 코드만 본다. pin 커밋(`:151`), 답 표 사본(`:165`), 생성기 사실(`:187`), 중복(`:211`), 답 행마다 `envelopeFailureEffect`·`invitesKeyedResend`가 표의 답을 내는지(`:219-232`), Envelope 표 행이 답 표에 있는지(`:234-253`)다. **이전:** `8a44226`의 목록은 2개였고 이 파일은 문서를 읽지 않았다. 그래서 capability 사본에서도 돌았다(`git show 8a44226:scripts/lib/removal-fixture.ts`, 같은 커밋의 테스트 파일, E1). **지금(실행):** FE-GATE-020 로그에서 이 파일은 샘플 제거와 생성 기능 드릴 안에서만 나온다(`FE-GATE-020.txt` 8회, 마지막 `:7225`). capability 드릴 셋(`:9803` 이후)에는 없다(E3). **가드:** 목록이 "문서를 읽는 테스트"인지 보는 테스트는 파일 글자에 `README.md|CHANGELOG.md|docs/`가 있는지만 본다(`tests/unit/removal-fixture.test.ts:161`). 이 파일은 주석 한 줄(`backend-contract-pin.test.ts:259`) 때문에 통과한다. 실제 읽기는 pin 값(`pin.frontend.contractDocument`)으로 한다. **같은 모양:** `tests/unit/feature-tracked-files.test.ts:25`(문서 무관 1건). 새 테스트라 전에 돌던 것이 빠진 것은 아니다 |
|
||||
| 발생 조건 | capability 하나(optional recipe, browser file storage, realtime)를 지운 사본이 짝 백엔드 답 표 대조를 깨뜨릴 때. 예: 제거가 `src/adapters/http/backend-envelope.ts`나 `config/contracts/`의 파일을 함께 바꾸는 경우 |
|
||||
| 영향 | 그 깨짐을 FE-GATE-020이 알리지 않는다. 템플릿 자신의 `test:unit`은 그 14건을 계속 돌린다(`FE-GATE-005.txt`). 지금 세 capability 제거는 그 파일들을 건드리지 않는다(추론). 그래서 지금 놓친 결함은 없다. 목록이 파일 단위라 문서를 읽는 test 하나를 어느 파일에 더하면 그 파일 전체가 드릴 사본에서 사라진다. 사람이 그것을 알아차릴 장치가 없다 |
|
||||
| 심각도·우선순위 | Low · P3 — 사용자 피해와 게이트 실패가 없다. 결과 불명 쓰기의 판정 대조라는 중요한 검사가 사본 셋에서 빠지지만, 같은 판정은 `tests/unit/backend-envelope.test.ts`가 사본에서도 본다(`git grep envelopeFailureEffect -- tests`). 지난 라운드의 "변이가 살아남는 테스트" 항목들(1105/06-02 등 Low·P3)과 같은 기준이다 |
|
||||
| 통제·증거 | 목표 M3(드릴 사본이 문서와 무관한 테스트를 모두 돈다) / 확인 M2(파일 단위 제외. 가드는 글자 검색) · E3(FE-GATE-020 로그) + E1 |
|
||||
| 확실성과 남은 가정 | 빠진 사실과 건수는 확정이다. 그 때문에 놓칠 실제 결함은 없다고 본다(추론). capability 제거가 pin 대조 대상 파일을 바꾸는 경로는 지금 없다 |
|
||||
| 결정의 근거 | 확인한 사실: 03-01의 새 test가 같은 파일에 들어갔고, 통합 때 ENOENT를 피하려고 파일째 뺐다(§16.3 `5c0b37e` 행). 추론: 통합 중의 가장 작은 수정을 골랐다. 그 test를 따로 떼는 것은 브랜치 범위 밖이었다 |
|
||||
| 이해 비용 | 드릴을 고치는 사람은 목록의 파일마다 문서를 읽는 test가 몇 건인지 직접 세어야 한다 |
|
||||
| 최소 개선 방향 | (1) 문서를 읽는 test를 자기 파일로 뗀다. 예: `codesPossiblyAfterWrite`와 그 describe를 `tests/unit/backend-contract-pin-document.test.ts`로 옮기고 목록에는 그 파일을 둔다. `feature-tracked-files.test.ts`도 같다. (2) 가드가 주석이 아니라 실제 읽기(`readFile*` 인자나 pin의 문서 경로)를 보게 한다 |
|
||||
| 대안 비교 | (a) 현 상태: 비용 0, 파일 단위로 계속 빠진다. (b) 위 (1): 파일 두 개를 나눈다. 사본이 문서 무관 test를 다 돈다. (c) 사본에 pin이 가리키는 문서 한 개만 복사: 문서 테스트가 늘 때마다 복사 목록이 늘고, capability 드릴이 "문서 없이"를 증명한다는 전제(`removal-fixture.ts:50-55`)가 흐려진다. (b)를 권한다 |
|
||||
| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다. 문서를 복사하는 드릴(샘플 제거, 생성 기능)의 동작은 그대로 둔다 |
|
||||
| 비용·부작용 | 테스트 파일 둘 분리와 목록 두 줄. 실행 시간 변화는 수십 ms |
|
||||
| 재검토 조건 | capability 드릴이 문서를 함께 복사하게 바뀌면 이 목록 자체가 필요 없다 |
|
||||
| 완료 기준 | capability 드릴 셋의 `test:unit` 출력에 `backend-contract-pin` 대조 14건이 다시 나온다. 문서를 읽는 test만 사본에서 빠진다. 가드가 주석만 있는 파일을 거절한다 |
|
||||
| 검증 방법 | FE-GATE-020 로그에서 `:9803` 이후 구간의 테스트 이름 검색. 가드 변이: 문서를 읽지 않고 주석에만 `docs/`가 있는 파일을 목록에 넣으면 `removal-fixture.test.ts`가 실패한다 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
|
||||
### 12-02 1105/12-04 수정 뒤 빌드는 `RUN_OUTPUT_ROOT` 아래에 쓰고 빌드 뒤 검사는 루트를 읽어, 그 변수를 셸에 두면 `check:bundle`이 이전 빌드로 판정한다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함(1105/12-04 수정 `f4d5761`이 만들었다. 문서가 금한 사용에서 거짓 통과를 실행으로 확인했다) |
|
||||
| 관련 관점 | 21, 19, 5, 23, 20 |
|
||||
| 근거 | **쓰는 쪽:** 빌드 단계 전부가 `RUN_OUTPUT_ROOT`를 읽는다. `dist`(`scripts/build-frontend.ts:51`, `vite.config.ts:184-188`), 생성 모듈(`build-frontend.ts:66`), build manifest(`scripts/generate-build-manifest.ts:31`). 값은 `.`이나 `.tmp/` 아래만 받는다(`scripts/lib/run-isolation.ts:63-75`). **읽는 쪽:** FE-GATE-012의 `check:bundle`은 `generate-supply-chain.ts`와 `check-bundle.ts`를 돈다(`package.json:115`). 둘 다 이 변수를 읽지 않는다. 루트 `artifacts/release/build-manifest.json`(`scripts/generate-supply-chain.ts:144`), 루트 `dist`(`:156`, `scripts/lib/release-candidate.ts:104`), 루트 `artifacts/performance/bundle.json`과 `dist/.vite/manifest.json`(`scripts/check-bundle.ts:24-29`)을 읽는다. **신선도 검사가 막지 못한다:** `ci:gate`는 명령 하나가 증거 파일을 새로 썼는지만 본다(`scripts/run-ci-gate.ts:41-56`, `:189-206`). FE-GATE-012의 증거 `bundle.json`은 `check:bundle`이 루트에 다시 쓴다(`generate-supply-chain.ts:325-329`, `check-bundle.ts:115-119`). 그래서 빌드가 다른 폴더에 썼어도 "freshly produced"가 된다. **문서:** "`RUN_OUTPUT_ROOT`는 직접 export하지 않는다"(`docs/testing/frontend-platform-testing-strategy.md:1035`, M1). 이를 막는 코드는 없다. 표(`:1026-1030`)는 이 변수를 "빌드 단계 전부"가 읽는다고만 적는다. **실행(12-R2, `R5-12-R2.log`):** 깨끗한 루트 빌드(root-build-rc=0) 뒤 entry를 키운 변이를 `RUN_OUTPUT_ROOT=.tmp/r5-12`로 빌드했다(run-build-rc=0). 같은 변수로 `check:bundle`을 돌리자 "Bundle budget: PASS (initial JS 204111 / 206848 gzip bytes, 27 / 32 files)", stale-bundle-rc=0. entry gzip 크기는 루트 `dist` 1,065 B, `.tmp/r5-12/dist` 7,321 B였다. 같은 변이를 루트에 빌드하면 "210352 … over by 3504"로 실패한다(12-R1). 그래서 이번 변경의 빌드는 예산을 3,504 B 넘는데 검사는 이전 빌드로 통과했다(E3) |
|
||||
| 발생 조건 | 개발자나 에이전트가 셸에 `RUN_OUTPUT_ROOT`를 둔 채(예: 빌드 결과를 따로 받아 보려고) `build`, `check:bundle`, 또는 `ci:gate -- FE-GATE-012`를 돌릴 때. 루트에 이전 빌드가 남아 있어야 한다. 없으면 `dist is missing`으로 실패한다(`release-candidate.ts:106-108`) |
|
||||
| 영향 | merge 게이트 하나가 이번 변경의 빌드가 아니라 이전 빌드의 크기로 통과한다. 예산을 넘는 변경이 로컬 게이트를 통과한 것으로 기록된다. CI는 이 변수를 두지 않아 영향이 없다(workflow env `quality-gates.yml:26-31`). `check:optional-recipes --require-dist`, `check:app-build-input:bundle`도 루트를 읽는 같은 모양일 수 있다(확인 안 함) |
|
||||
| 심각도·우선순위 | Low · P3 — 문서가 금한 사용이 필요하고 CI에는 영향이 없다. 다만 증거 신선도 검사가 막지 못하는 거짓 통과라 고치는 비용(몇 줄)에 비해 가치가 있다 |
|
||||
| 통제·증거 | 목표 M3(게이트가 쓰는 곳과 읽는 곳이 다르면 시작 전에 거절) / 확인 M1(문서 한 줄) · E3(12-R2, 대조군 12-R1) + E1 |
|
||||
| 확실성과 남은 가정 | `check:bundle`의 거짓 통과는 확정이다. `ci:gate -- FE-GATE-012` 전체로는 돌리지 않았다. 신선도 검사가 막지 못한다는 것은 코드 추적이다(위 근거). Playwright 설정은 web server에 늘 값을 넣으므로(`playwright.config.ts:37`) Playwright 경로에는 이 문제가 없다 |
|
||||
| 결정의 근거 | 확인한 사실: `f4d5761`은 "빌드 코드는 `TEST_RUN_ID`를 읽지 않는다"와 "게이트·증거 검사는 기본 경로만 읽는다"를 한계로 적었다(커밋 본문, 13.6절 한계). 그 한계를 `TEST_RUN_ID`로 게이트를 돌릴 때("not freshly produced"로 실패)만 따졌다. `RUN_OUTPUT_ROOT`를 직접 둔 경우는 적지 않았다. 추론: 빌드 출력 위치를 env로 바꿀 수 있게 하면서, 같은 빌드를 읽는 검사 쪽을 같은 변수에 묶지 않았다 |
|
||||
| 이해 비용 | 통과한 게이트 로그만 보고는 어느 빌드를 쟀는지 알 수 없다. `bundle.json`의 `outputs` 이름과 `.tmp/` 아래 빌드를 직접 비교해야 한다 |
|
||||
| 최소 개선 방향 | (1) `ci:gate`가 `RUN_OUTPUT_ROOT`나 `TEST_RUN_ID`가 있으면 이유를 적고 시작하지 않는다. (2) 또는 빌드 뒤 검사(`generate-supply-chain.ts`, `check-bundle.ts`, `release-candidate.ts`의 `collectDistOutputs`)가 `runOutputPath`로 같은 루트를 읽는다 |
|
||||
| 대안 비교 | (a) 현 상태 + 문서: 비용 0, 거짓 통과 가능. (b) 위 (1): 몇 줄. 게이트는 늘 기본 경로라는 지금 전제(`README.md:362-363`)와 맞다. (c) 위 (2): 게이트도 run 단위로 격리하는 방향(D6 재검토 조건)과 맞지만 증거 경로 54개 파일과 upload를 손봐야 한다(1105 §14 12-04 비용). (b)를 먼저 권한다 |
|
||||
| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다. Playwright 실행 격리와 빈 포트는 그대로 둔다 |
|
||||
| 비용·부작용 | (b)는 `run-ci-gate.ts` 몇 줄과 단위 테스트 1건. 디버깅으로 변수를 둔 사람은 게이트 전에 지워야 한다 |
|
||||
| 재검토 조건 | 게이트와 증거 검사가 run ID를 읽게 될 때(D6 재검토 조건) |
|
||||
| 완료 기준 | `RUN_OUTPUT_ROOT=.tmp/x corepack pnpm ci:gate -- FE-GATE-012`가 변수 이름을 적고 실패하거나, 같은 루트의 빌드를 잰다. 루트의 이전 빌드로 PASS하지 않는다 |
|
||||
| 검증 방법 | 12-R2와 같은 순서(깨끗한 루트 빌드 → 예산 초과 변이를 다른 루트에 빌드 → 검사) |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
|
||||
## 4. 28개 관점 판정 (36.2)
|
||||
|
||||
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 굵은 번호가 이번에 깊게 본 관점이다.
|
||||
|
||||
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | 코드 성숙도 | 적용 제외 — 이 영역에 도메인 규칙이 없다 | — | — | - |
|
||||
| 2 | 구조적 성숙도 | 적용 — 경계 강제 장치 | M3 / import 방향 M3(그래프 fixture 31), 계층 밖 폴더 → `src/adapters` 직접 M3, 계층 밖 폴더 → 기능 `adapters/` M0 | E2·E3 | P · 0929/12-03 일부. 두 단계 경로가 그래프·ESLint를 통과한다(12-R3) |
|
||||
| 3 | 변경 용이성 | 적용 | M3 / P | E2 | P · 러너 요구를 바꾸면 기준선을 다시 적는다(의도한 비용, `67082cc`). 게이트 계약 크기가 기준선과 테스트 상수 두 곳(0929/12-04) |
|
||||
| 4 | 인지 부하 | 적용 | — | E1 | P · `gates.json` 3,009줄, workflow 504줄. 실행 격리 변수 둘과 포트 변수 다섯이 한 절(13.6)과 한 모듈(`run-isolation.ts`)에 있다 |
|
||||
| **5** | 위험 가시성 | 적용 | M3 / P | E3 | P · FE-GATE-013이 이제 PASS 대신 이름으로 실패한다(1105/12-01). `CLAUDE.md` 목록은 여전히 merge 게이트 7개를 빼고 "통과"라 할 수 있다(1105/12-03). `RUN_OUTPUT_ROOT`를 두면 `check:bundle`이 이전 빌드로 통과한다(12-02, 12-R2) |
|
||||
| 6 | 실패 성숙도 | 적용 제외 — 런타임 실패 처리가 없는 영역 | — | — | - |
|
||||
| 7 | 운영 성숙도 | 다른 영역 | — | — | > 영역 13 |
|
||||
| 8 | 디버깅 가능성 | 적용 | M3 / P | E3 | P · 사전 점검이 원인·sysctl·고치는 법을 적는다(`FE-GATE-013.txt`). 문서 검사 미확인에 이유(pin, HEAD)를 적는다. 예산 실패가 초과량을 적는다. fanout 메시지는 그대로(0929/12-01) |
|
||||
| 9 | 유지보수 성숙도 | 적용 | — | E1 | P · 미사용 `dependency-cruiser`(0929/12-05). merge 게이트 손 목록 둘(1105/12-03). 문서 테스트 제외가 파일 단위(12-01) |
|
||||
| **10** | 테스트 성숙도 | 적용 | M3 / P | E2·E3 | P · 고친 검사마다 RED 테스트가 있다(2.1절). capability 드릴 사본에서 pin 대조 14건이 빠진다(12-01). 고아 `*.spec.ts` 판정(0929/12-06) |
|
||||
| 11 | 데이터 성숙도 | 적용 제외 | — | — | - |
|
||||
| 12 | 동시성 성숙도 | 일부 적용 — 한 checkout 두 실행(1105/12-04) | M2 / Playwright 실행 M3(단위 테스트·드릴), 게이트 M1(문서) | E2·E3 | P · e2e 두 실행이 한 checkout에서 함께 통과했다(오케스트레이터 드릴). 게이트 두 개는 여전히 함께 돌 수 없다. 다른 선택(`VITE_PRODUCT_FEATURES`)의 두 실행은 `src/.generated`를 서로 바꾼다(13.6절 한계) |
|
||||
| 13 | 확장성 | 일부 적용 | — | E3 | > 영역 15. 이 영역 몫: 예산 여유 템플릿 2,690 B, 생성 기능 둘 드릴 1,383 B(CI env, `FE-GATE-012.txt:76`, `FE-GATE-020.txt:6206`) |
|
||||
| 14 | 성능 성숙도 | 적용 | — | 로컬만 | ? · runner가 없다. desktop에서 FE-GATE-020 1,237초(job 상한 45분의 46%), 008 196초 |
|
||||
| 15 | 보안 성숙도 | 적용(workflow 범위) | M4 / M4 | E1 | O · workflow diff는 주석 2줄과 13-01·13-02 변경뿐이다. `permissions: contents: read`(`quality-gates.yml:23-24`) 그대로. provider sandbox 검증은 이 호스트에서 돌지 못한다(FE-GATE-013) |
|
||||
| 16 | 의존성 성숙도 | 적용 | M3 / P | E2·E3 | P · 문서 검사가 짝 백엔드 pin을 쓴다(1105/12-02 고쳐짐). 미사용 `dependency-cruiser@18.1.0`(0929/12-05) |
|
||||
| 17 | API / Contract | 적용 | M3 / P | E2 | P · pin 답 표와 Envelope 판정 대조는 템플릿 `test:unit`에서 돈다. capability 드릴 사본에서는 빠진다(12-01). 백엔드 drift는 영역 07 |
|
||||
| 18 | 배포 성숙도 | 다른 영역 | — | — | > 영역 13 |
|
||||
| **19** | 설정 성숙도 | 적용 | M3 / P | E3 | P · 러너 요구가 계약(`hostRequirements`)·workflow·문서 셋·기준선 해시에 있다(1105/12-01 고쳐짐). 셸의 `RUN_OUTPUT_ROOT`가 빌드 위치만 바꾸고 검사 위치는 그대로다(12-02) |
|
||||
| 20 | 개발자 경험 | 적용 | — | E3 | P · 이 desktop에서 FE-GATE-013이 첫 줄에서 고치는 법을 준다. `verify:documentation`이 짝 유무와 무관하게 통과한다. Playwright 두 실행이 한 checkout을 같이 쓴다. 게이트는 여전히 하나씩 |
|
||||
| **21** | Guardrail 성숙도 | 적용 | M3 / 로컬 P, 머지 시점 미확인 | E3 | P(로컬) · ?(머지 시점) · merge 14게이트 중 13개가 이 호스트에서 통과한다. 013은 호스트 조건으로 실패한다(사용자 결정). 남은 틈: 1105/12-03, 0929/12-03(일부), 12-01, 12-02, 0929/12-06 |
|
||||
| 22 | 추상화 성숙도 | 적용 | — | E1 | O · namespace 옵션은 provider와 점검이 한 상수를 쓴다. 실행 격리 규칙은 한 모듈이다. 빌드 입력 목록도 한 모듈이다 |
|
||||
| **23** | 일관성 | 적용 | — | E1 | P · merge 게이트 목록이 계약·README·`CLAUDE.md` 세 곳(1105/12-03). 문서 검사와 pin 테스트가 같은 pin을 본다(1105/12-02 고쳐짐). 빌드와 빌드 뒤 검사가 다른 루트를 읽을 수 있다(12-02) |
|
||||
| 24 | 네이밍 / 의미 | 적용 | — | E1 | P · "System test prerequisites: PASS"가 이 호스트에서 더는 나오지 않는다. `REMOVAL_FIXTURE_DOCUMENT_TESTS`의 주석은 "문서를 읽는 테스트"인데 문서와 무관한 test까지 뺀다(12-01) |
|
||||
| 25 | 조직 확장성 | 적용(팀 하나라 구조만) | — | E2 | P · 두 에이전트나 IDE가 Playwright를 함께 돌릴 수 있다. 게이트는 한 checkout에 하나씩이다 |
|
||||
| 26 | Ownership | 적용 | M1 / P | E1 | P · 예외 목록에 담당·재검토가 없다(0929/12-07, 결정 대기). 기준선 owner가 개인 이름이다(`config/ci/contract-baseline.json:3`) |
|
||||
| 27 | 삭제 가능성 | 적용 | M3 / P | E3 | P · 제거 드릴 다섯이 통과한다(FE-GATE-020 rc=0). capability 사본은 pin 대조를 돌지 않는다(12-01) |
|
||||
| 28 | 회복 가능성 | 적용 제외 — 이 영역에 복구 경로가 없다 | — | — | - |
|
||||
|
||||
## 5. 미검증
|
||||
|
||||
| 항목 | 이유 | 확인하려면 |
|
||||
|---|---|---|
|
||||
| user namespace를 허용하는 호스트에서 사전 점검 PASS와 `test:system` 114건 | 그런 호스트가 없다. 가짜 호스트 단위 테스트뿐이다 | bwrap AppArmor profile을 넣은 호스트나 다른 runner에서 1회 |
|
||||
| 1105/12-04 완료 기준의 문언(게이트 두 개 동시 실행) | 오케스트레이터 드릴은 e2e 실행 단위였다. 게이트 단위는 코드상 기본 경로를 같이 쓴다 | 한 checkout에서 `ci:gate -- FE-GATE-008`과 `ci:gate -- FE-GATE-005`를 함께 |
|
||||
| 12-02의 `ci:gate -- FE-GATE-012` 전체 | `check:bundle`만 돌렸다 | 12-R2 순서로 `RUN_OUTPUT_ROOT=… corepack pnpm ci:gate -- FE-GATE-012` |
|
||||
| 1105/12-02의 "짝 HEAD가 pin 뒤"를 실제 checkout에서 | desktop 옆 checkout의 HEAD를 읽지 않았다(`/tmp/claude-gates` 밖) | desktop에서 `git -C ../clean-architecture-backend-template rev-parse HEAD`와 로컬 실행 대조 |
|
||||
| 1103/12-01 보존 조건(셸 CSS 회귀가 시각 게이트에서 실패) | 지난 라운드 변이가 화면을 바꾸지 않았고 이번에 다시 요청하지 않았다 | 배경색이나 사이드바 너비를 바꾸고 기능 1개 상태에서 `test:visual` |
|
||||
| 실제 Gitea runner와 머지 시점 강제 | Actions 꺼짐(1101 U-1) | runner 1대와 PR 1건 |
|
||||
| 12-02 모양이 `check:optional-recipes --require-dist`, `check:app-build-input:bundle`에도 있는가 | 읽지 않았다 | 두 스크립트의 `dist` 읽기 경로 확인 |
|
||||
|
||||
## 6. 실행 기록
|
||||
|
||||
| ID | 명령 | 변이 | rc | 결과 |
|
||||
|---|---|---|---|---|
|
||||
| 12-R1 | `corepack pnpm -s build; corepack pnpm -s check:bundle` | `scratchpad/r5/12/12-inflate-entry.diff`(entry에 압축 안 되는 문자열 약 8,000자) | build-rc=0, bundle-rc=1 | **기대대로.** "initial JavaScript 210352 gzip bytes > budget 206848 (over by 3504)". 무변이 대조 `FE-GATE-012.txt:76`(204158 PASS). load 2.55, `restore=clean` |
|
||||
| 12-R2 | 변이를 빼고 루트 빌드 → 변이를 다시 넣고 `RUN_OUTPUT_ROOT=.tmp/r5-12` 빌드 → 같은 변수로 `check:bundle` | 12-R1과 같은 파일 | root-build-rc=0, run-build-rc=0, stale-bundle-rc=0 | **기대대로(후보 확인).** "Bundle budget: PASS (initial JS 204111 / 206848 …)". entry gzip: 루트 1,065 B, `.tmp/r5-12` 7,321 B. load 2.98, `restore=clean` |
|
||||
| 12-R3 | `corepack pnpm -s check:architecture; corepack pnpm -s exec eslint <두 파일>` | `scratchpad/r5/12/12-support-two-hop.diff`(`support/gateway-reexport.ts`, `presentation/r5-12-probe.ts`) | arch-rc=0, eslint-rc=0 | **빈틈 확인.** "421 modules, 1301 dependencies"(무변이 419/1299), fixture 31 PASS. load 2.82, `restore=clean` |
|
||||
| R5-01-1204-drill(오케스트레이터) | 한 checkout에서 `TEST_RUN_ID`가 다른 `playwright test` 두 개를 함께, 부분(2 spec)과 전체 | 없음 | a·b 모두 0 | 부분 19+19, 전체 222+222 통과(각 4 skipped). "already used" 0줄. 포트와 출력 폴더가 실행마다 달랐다. `restore=clean` |
|
||||
| ssh 읽기 | `cat`·`grep`: `bbde570-ci/summary.txt`, `FE-GATE-0NN.log`, `gate-artifacts/FE-GATE-005·010·012·013·020.txt`, `bbde570-013-parts/*`, `r5/snap/verify-documentation.*.txt`, `build.txt`, `lab.txt` | 없음 | 0 | 0절·2절 근거 |
|
||||
|
||||
배치 rc는 마지막 echo의 것이라 판정은 로그 안의 `*-rc=` 줄로 했다. 노트북에서 돌린 것은 읽기 명령뿐이다(`git show`, `git log`, `git diff`, `git grep`, `git merge-base --is-ancestor`, `git apply --check`로 패치 적용 가능 확인). 패치 둘은 `bbde570`에 깨끗이 적용된다.
|
||||
|
||||
## 7. 새 발견 요약
|
||||
|
||||
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|
||||
|---|---|---|---|---|
|
||||
| 12-01 | Low · P3 | 구조적 위험 | 제거 fixture가 문서 테스트를 파일째 빼서 capability 드릴 사본 셋에서 `backend-contract-pin.test.ts`의 문서 무관 14건도 빠진다 | `scripts/lib/removal-fixture.ts:70-81`, `tests/unit/backend-contract-pin.test.ts:219-253`, `tests/unit/removal-fixture.test.ts:161` |
|
||||
| 12-02 | Low · P3 | 확인된 결함 | 셸에 `RUN_OUTPUT_ROOT`가 있으면 빌드는 `.tmp/` 아래에 쓰고 `check:bundle`은 루트의 이전 빌드로 판정한다(12-R2: 예산 3,504 B 초과 빌드에서 PASS) | `scripts/build-frontend.ts:51`, `scripts/generate-supply-chain.ts:144`, `:156`, `scripts/check-bundle.ts:24-29`, `scripts/run-ci-gate.ts:189-206` |
|
||||
@@ -0,0 +1,186 @@
|
||||
# 영역 13 — 빌드·릴리스·설정·공급망
|
||||
|
||||
> 검토일 2026-11-06 · 기준 `bbde570`(PR B 끝, `fix/maturity-review-2026-11-05-b`) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
|
||||
> 경로: `scripts/build-frontend.ts`, `scripts/generate-{runtime-config,build-manifest,supply-chain}.ts`, `scripts/check-release-admission.ts`, `scripts/verify-hosting-headers.ts`, `scripts/scan-dependency-advisories.ts`, `scripts/lib/{hosting-probe,build-environment,supply-chain,local-policy-evidence,runtime-config-switches,dependency-advisories}.ts`, `scripts/run-and-validate-provider.ts`(호스트 전제 부분), `scripts/contracts/{ci-gates,product-ci-overlay}.ts`(release·배포 job 부분), `scripts/generate-ci-workflow.ts`(release·제품 job 렌더링), `scripts/run-ci-gate.ts`(로그·콘솔), `vite.config.ts`, `vite.service-worker.config.ts`, `package.json`, `pnpm-lock.yaml`, `pnpm-workspace.yaml`, `renovate.json`, `config/{hosting,security,runtime}/`, `config/ci/{gates,product-gates}.json`(release job), `.gitea/workflows/quality-gates.yml`(env, `release_gate`~`production_gate`), `src/contracts/{env,deployment-admission}.ts`
|
||||
> 깊게 본 관점: 8, 16, 18, 19, 21
|
||||
> 렌즈: 1105/13-01(`629c713`)·13-02(`92d5019`) 수정 결과와 검사 약화 여부 · 1103/13-03 결정 대기 상태 · FE-GATE-013의 test:system 뒤 명령 · 생성 workflow와 생성기 대조
|
||||
> 영역 판정(35.8): **조건부 사용 가능.** "빌드 → 공개 대상 승인 → 손으로 배포"는 그대로 써도 된다. 지난 라운드 새 발견 둘은 코드로 들어왔다. 제품 merge 검사는 이제 같은 run의 release를 막는다(1105/13-02 고쳐짐). release job은 gate 로그와 advisory 기록을 따로 올린다. 다만 실제 runner에서 그 산출물을 본 적은 없다(1105/13-01 일부, 실행 환경 대기). 운영 의존성 high advisory 2건은 결정 대기 그대로다(1103/13-03). provider 없이 슬롯까지 가는 길은 아직 없다. provider job은 FE-GATE-013과 같은 user namespace를 요구하지만, workflow의 그 job에는 요구도 사전 점검도 없다(1101/13-03). 이 영역 수정이 검사를 약하게 한 곳은 찾지 못했다.
|
||||
|
||||
ID 표기: 이 문서의 `13-NN`은 2026-11-06 라운드 ID다(라운드 밖에서는 `1106/13-NN`). 지난 라운드는 `1105/13-NN`, 그 전은 `1103/…`, `1101/…`, `0929/…`다.
|
||||
|
||||
## 0. 결론
|
||||
|
||||
- **1105/13-02는 고쳐졌다(E2).** 제품 overlay에 gate가 있으면 `release_gate`가 `[merge_gate, product_merge_gate]`를 기다린다(`scripts/generate-ci-workflow.ts:68-78`, `:92`, `:130`, `:182-184`). 뒤의 release job은 모두 `release_gate`를 거쳐 기다린다(`scripts/contracts/ci-gates.ts:942-947`). `check:ci`는 그 연결이 없는 workflow를 거절한다(`generate-ci-workflow.ts:511-520`). overlay가 비면 workflow 바이트가 같다. 이 수정은 `.gitea/workflows/quality-gates.yml`을 바꾸지 않았고, bbde570의 FE-GATE-010이 `CI workflow bytes: PASS`다. 실제 Gitea의 `needs` 처리는 확인하지 못했다.
|
||||
- **1105/13-01은 일부다. 실행 환경 대기다.** `immutable_build` 마지막 단계가 `if: always()`로 FE-GATE-015·027의 로그·evidence 6개와 advisory 기록을 올린다(`.gitea/workflows/quality-gates.yml:210-223`, `config/ci/gates.json:2512-2526`). 계약이 이 단계를 고정한다(`ci-gates.ts:961`, `:1159-1179`, `:1200-1219`). 단계를 빼거나, `always`를 빼거나, 경로를 빼거나, 순서를 바꾸면 계약이 거절한다. 이 5가지를 단위 테스트가 본다(`tests/unit/ci-workflow-generation.test.ts:1782-1865`). 그 테스트는 bbde570 CI env에서 통과했다. upload 대상 파일 쪽은 CI env에서 확인했다(13-R1, E3). FE-GATE-015가 실패하면 그 로그 하나가 새로 생기고 이유(`VITE_COMMIT_SHA does not identify the checked-out commit`)가 담긴다. FE-GATE-027이 거절되면 로그와 승인 기록이 새로 생기고 로그에 `release admission refused for production:`이 있다. 콘솔은 두 경우 모두 `FAIL` 한 줄이었다. 완료 기준의 나머지 절반은 "release 단계 run의 산출물"이다. runner가 없어 확인하지 못했다. 커밋 본문도 그렇게 적는다. README §16.4는 "고침"이라 했다. 이 문서는 일부로 본다.
|
||||
- **1103/13-03은 일부다. 결정 대기다.** `8a44226..bbde570`에서 `package.json`의 의존성 칸과 `pnpm-lock.yaml`은 바뀌지 않았다. 운영 high 2건(`react-router-dom@7.18.1`, `zod@4.4.3`)이 그대로다(`package.json:160-161`). 새 사실이 하나 있다. 초기 JS 예산이 206,848 B로 올라 여유가 2,690 B다(D7, FE-GATE-012). 그래서 문서가 react-router 갱신 비용으로 적은 약 470 B는 이제 예산 안이다. zod의 약 7 KB는 여전히 넘는다(`docs/operations/ci-quality-gates.md:564-565`). 2026-11-06 04:24 결과는 `POLICY_VIOLATION`이다. 운영 high 2건(GHSA-qwww `react-router@7.18.1`, GHSA-mrhx `zod@4.4.3`)과 개발 moderate 2건이다. 지난 라운드와 같다(13-R1 B, E3).
|
||||
- **새 발견은 1건이다. Low·P3다(13-01).** FE-GATE-027은 공개 대상 승인을 먼저 돌고 advisory 검사를 뒤에 돈다(`config/ci/gates.json:2212-2213`). `ci:gate`는 첫 실패에서 멈춘다(`scripts/run-ci-gate.ts:176-190`). 그래서 승인이 거절된 run에는 advisory 기록이 새로 생기지 않는다(13-R1 C, E3). 문서는 그 기록을 "성공·실패와 상관없이" 올린다고 적는다(`ci-quality-gates.md:169-173`, `:540-544`).
|
||||
- **이 영역 수정은 검사를 약하게 하지 않았다.** 2.4절. 테스트 단언 두 곳이 바뀌었다. 하나는 `uses:` 개수를 33에서 34로 올렸다. 다른 하나는 한 줄만 바꿔 비교한다. 둘 다 새 단계·새 연결을 반영한 것이고, 새 단언이 그 줄을 직접 본다. 초기 JS 예산 상향(D7)은 영역 15 몫이다. 12-04가 빌드 단계에 넣은 `RUN_OUTPUT_ROOT`는 release job env에 넣을 수 없다.
|
||||
- **FE-GATE-013의 test:system 뒤 명령 7개는 bbde570 CI env에서 모두 통과했다.** 후보 `c5760d69…`(105파일), `Supply chain: LOCAL PASS (562 dependencies); promotion=FAIL_UNVERIFIED`, secret scan PASS(1,660파일), reproducible build PASS다. FE-GATE-013 자체는 이제 사전 점검에서 2초 만에 멈춘다. 원인과 고치는 법을 적는다(12-01 수정, 영역 12).
|
||||
- **지난 이월 8건은 모두 남았다.** 0929/13-06만 일부다. 1101/13-03에는 새 사실이 있다. provider job도 bwrap namespace가 필요하다. 그런데 workflow의 provider job에는 요구 주석도 사전 점검도 없다. 이 desktop에서 provider를 돌리면 `sandbox reported: bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted` 한 줄로 끝난다(`bbde570-013-parts/system-vitest.log`).
|
||||
|
||||
## 1. 범위 (36.1)
|
||||
|
||||
| 항목 | 기록 |
|
||||
|---|---|
|
||||
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`, 영역 13 — 빌드·릴리스·설정·공급망 |
|
||||
| 커밋·작업 상태·확인 시점 | `bbde570`. 노트북 worktree `happy-easley-233d07`(HEAD = 기준, 추적 파일 변경 없음)에서 읽기만 했다. 실행 증거는 desktop의 기존 로그다. merge 단계 CI env 실행(`/tmp/claude-gates/bbde570-ci/`, 2026-11-06 03:24~03:56), FE-GATE-013의 뒤 명령(`/tmp/claude-gates/bbde570-013-parts/`, 03:54~03:56), 그 실행이 남긴 산출물 사본(`/tmp/claude-gates/r5/snap/merge/`, `MTIMES.txt`로 03:24 이후 파일만 썼다)이다. `gate-artifacts/FE-GATE-015.txt`·`027.txt`와 사본의 `dependency-advisories.json`·`deployment-admission.json`은 2026-11-05 20:09 파일이라 쓰지 않았다. 추가 실험은 배치 13-R1(2026-11-06 04:24, `restore=clean`) |
|
||||
| 목적과 지원 실행 구성 | 템플릿. 브라우저 SPA + 정적 호스팅 + Service Worker(기본 `null`). 사용자 목표: 짝 백엔드 템플릿과 빨리 출시하고 desktop 서버로 배포한다 |
|
||||
| 필수 요구와 규모·운영 목표 | 초기 JS 206,848 gzip B와 파일 32개(`config/performance/budgets.json:4-5`, D7로 204,800에서 올림). 서빙 전제는 h2와 압축(`config/hosting/cache-policy.json:4`, `:29`) |
|
||||
| 읽은 코드·구성 범위 | 머리의 경로 전체. `git diff 8a44226..bbde570`으로 이 영역 경로의 변경 30파일을 봤다. 수정 커밋 `629c713`, `92d5019`의 본문과 테스트. 주장 자료: `README.md`, `docs/operations/ci-quality-gates.md:163-205`, `:420-430`, `:531-565`, `CHANGELOG.md:32`, `:46`, `:48`, 지난 README §15·§16 |
|
||||
| 수행한 테스트·실험 | 이 리뷰가 직접 돌린 것은 없다. 위 로그를 읽었다. 배치 13-R1 하나를 오케스트레이터가 desktop checkout(`bbde570`, CI env)에서 돌렸다. 2026-11-06 04:24, 끝난 뒤 `restore=clean`. 내용은 1105/13-01 완료 기준의 파일 쪽, 지금 advisory 수, 새 13-01이다. 결과 `desktop:/tmp/claude-gates/r5/batch/out/R5-13-R1.log`. 6절 |
|
||||
| 확인하지 못한 범위·이유 | 실제 Gitea runner(upload 동작, `needs` 처리, 재실행), 채운 배포 슬롯, provider 실행, 실제 운영 호스트, advisory 도달 가능성. 5절 |
|
||||
| 이전 리뷰와 비교 가능한 범위 | `docs/reviews/2026-11-05-maturity-review/13-build-release-supply-chain.md`의 새 발견 2건, 그 문서 2.2절이 남음·일부로 둔 이월 8건, README §16.5의 1103/13-03. §16.6에는 영역 13 ID가 없다(이월 8건은 손대지 않았다는 뜻). `git log 8a44226..bbde570 -- <경로>`의 이 영역 수정 커밋은 `629c713`, `92d5019`다. 다른 영역 수정이 이 영역 파일을 건드린 커밋도 봤다(2.4절). 지난 실험 결과는 증거로 쓰지 않았다 |
|
||||
|
||||
### 1.1 게이트 결과 중 이 영역에 해당하는 것 (`bbde570`, CI env)
|
||||
|
||||
| 게이트 | 결과 | 이 영역에 주는 의미 |
|
||||
|---|---|---|
|
||||
| FE-GATE-005(`test:unit`) | rc=0, 208파일 3,056건 | 통과한 파일: `ci-workflow-generation` 435(지난 426), `hosting-probe` 39, `product-ci-overlay` 12(지난 11), `dependency-advisories` 5, `env-registry-coverage` 4, `build-environment` 4, `local-build-environment` 3, `build-environment-bundle` 2, `pnpm-install-policy` 2 |
|
||||
| FE-GATE-010 | rc=0 | `CI contract: 27 gates, strict v2 graph and generated workflow model PASS`, `CI workflow bytes: PASS`. 커밋된 workflow가 생성기 출력과 같다 |
|
||||
| FE-GATE-011 | rc=0 | 첫 줄 `derived SOURCE_DATE_EPOCH=1793901621 from HEAD`. 빌드와 Storybook 빌드 통과 |
|
||||
| FE-GATE-012 | rc=0 | `initial JS 204158 / 206848 gzip bytes, 27 / 32 files`. 여유 2,690 B |
|
||||
| FE-GATE-013 | rc=1, 2초 | 사전 점검이 멈췄다. `this host does not allow unprivileged user and network namespaces`, bwrap stderr, `kernel.apparmor_restrict_unprivileged_userns = 1`, 고치는 법 셋을 적는다. 12-01 수정(영역 12)이 동작한다 |
|
||||
| FE-GATE-013의 뒤 명령(`bbde570-013-parts/`) | test:system rc=1(96/114). 나머지 7개 rc=0 | test:system 실패 18건은 모두 `tests/system/ci-runner/ci-artifact-contract.test.ts`다. 메시지는 `sandboxed external provider failed: exit=1, signal=none; sandbox reported: bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`다. 나머지: `verify:reproducible-build` PASS(`6b69c08f…`), `build:release-candidate` 후보 `c5760d69…`(105파일)·공급망 `LOCAL PASS (562 dependencies); promotion=FAIL_UNVERIFIED`·secret scan PASS(1,660파일)·release coherence PASS, `verify:local-evidence` PASS, `check:supply-chain:fixtures` 9 PASS, `check:supply-chain:provider-fixtures` PASS, `check:security:fixtures`·`check:browser-security`는 거절 fixture를 잡았다 |
|
||||
| FE-GATE-008·020 | rc=0(196초·1,237초) | 테스트가 띄우는 로컬 빌드가 CI=true에서 통과한다(1103/11-08 수정 유지) |
|
||||
|
||||
## 2. 지난 발견 재확인
|
||||
|
||||
### 2.1 2026-11-05 라운드(이 영역) 새 발견
|
||||
|
||||
| 지난 ID | 내용 | 상태 | 근거 |
|
||||
|---|---|---|---|
|
||||
| 1105/13-01 | `immutable_build`가 FE-GATE-015·027의 gate 로그와 advisory 기록을 올리지 않는다 | **일부(실행 환경 대기)** · §16.4는 "고침" | **들어온 것.** `immutable_build`의 마지막 단계 "Upload immutable gate evidence"가 `if: always()`로 7개 경로를 올린다(`.gitea/workflows/quality-gates.yml:210-223`). 경로는 FE-GATE-015의 로그와 evidence 3개, FE-GATE-027의 로그와 evidence 1개, advisory 기록이다(`config/ci/gates.json:2516-2523`). 계약은 단계 종류에 upload 하나를 더했다(`scripts/contracts/ci-gates.ts:961`). 경로는 gate 등록에서 계산해 대조한다(`:1167-1179`). 이 upload가 `always`이고 마지막 단계여야 한다(`:1206-1219`). advisory 경로는 상수 하나로 모았고 scan 스크립트도 그 상수를 쓴다(`scripts/lib/dependency-advisories.ts:7`, `scripts/scan-dependency-advisories.ts:23`). 후보 archive 멤버(`:151-203`)와 후보 upload(`:204-209`, `always` 없음)는 그대로다. **검증.** 정상 단언 1건(`tests/unit/ci-workflow-generation.test.ts:1782-1823`)과 거절 5건(`:1825-1865`: 단계 없음, `always` 없음, advisory 기록 빠짐, FE-GATE-027 로그 빠짐, 후보 upload 앞)이 bbde570 CI env의 FE-GATE-005에서 통과했다. 거절 5건은 계약을 바꿔 이 규칙의 메시지로 실패하는지 본다. 그래서 규칙 자체의 변이 시험 역할을 한다(E2). 생성 workflow는 생성기와 같다(FE-GATE-010). **남은 것.** 완료 기준은 "release 단계 run의 산출물에 FE-GATE-015·027 로그와 advisory 기록이 있다"이다. 실제 runner에서 `stage=release`를 돌린 적이 없다(커밋 본문 "위험·한계"). 업로드 action(`ChristopherHX/gitea-upload-artifact@81f940d…`)이 여러 줄 `path`에서 없는 파일을 건너뛰는지도 확인하지 못했다. **파일 쪽 확인(13-R1, CI env, E3).** 각 단계 앞에 표시 파일을 두고 7개 경로 중 더 새로 생긴 것을 봤다. A(FE-GATE-015를 HEAD가 아닌 커밋 ID로): rc=1. 새 파일은 `FE-GATE-015.txt` 하나다. 그 내용은 `VITE_COMMIT_SHA does not identify the checked-out commit`이다. B(빌드 뒤 FE-GATE-027, local 대상): rc=0. `FE-GATE-027.txt`, `deployment-admission.json`, `dependency-advisories.json`이 새로 생겼다. C(FE-GATE-027, production 대상): rc=1. `FE-GATE-027.txt`, `deployment-admission.json`이 새로 생겼고 로그에 `release admission refused for production:`이 있다. 세 경우 모두 콘솔은 PASS·FAIL 한 줄이었다. 그래서 실패한 run에도 올릴 파일이 최소 하나 있고, 거기에 이유가 있다. 콘솔은 여전히 gate마다 한 줄이다(`scripts/run-ci-gate.ts:243-249`). 문서가 산출물에서 읽으라고 적어 받아들인다(`docs/operations/ci-quality-gates.md:169-173`). 같은 원리로 1103/11-02를 지난 라운드에 "일부"로 정정했다 |
|
||||
| 1105/13-02 | 제품 merge 검사가 실패해도 같은 run의 release·배포가 진행된다 | **고쳐짐** | **코드.** overlay에 gate가 있을 때만 `release_gate`의 `needs`에 `product_merge_gate`를 더한다(`scripts/generate-ci-workflow.ts:68-78`, `:92`, `:130`, `:182-184`). 뒤 job은 `release_gate`를 거쳐 기다린다. `immutable_build`는 `release_gate`를, provider는 `immutable_build`를, promotion·deployment는 그 둘을 기다린다(`scripts/contracts/ci-gates.ts:942-947`). `check:ci`가 부르는 `workflowGateExecutionFailures`는 제품 gate가 있는데 연결이 없으면 거절한다(`generate-ci-workflow.ts:511-520`). **조건 대조.** `product_merge_gate`의 `if:`는 merge 조건이다(`:148`). 그 조건은 release 조건이 참인 모든 경우에 참이다(tag push, dispatch `release`·`production`·`field`). 그래서 release가 도는 run에서는 제품 job도 돈다. 제품 job이 건너뛰어져 release가 같이 멈추는 경우는 없다. **완료 기준 확인.** "overlay에 gate 하나를 넣고 생성하면 release 쪽 job이 `product_merge_gate`를 기다린다"는 `tests/unit/product-ci-overlay.test.ts:163-189`가 본다. 연결이 없는 workflow를 `check:ci` 함수가 거절하는 것도 본다. bbde570 FE-GATE-005에서 통과했다(E2). "overlay를 비우면 workflow 바이트가 같다"는 둘로 확인했다. `92d5019`는 `.gitea/workflows/quality-gates.yml`을 바꾸지 않았다. `config/ci/product-gates.json:4`가 `"mergeGates": []`이고 FE-GATE-010이 `CI workflow bytes: PASS`다. 문서(`ci-quality-gates.md:424-430`)와 CHANGELOG "먼저 할 일" 9단계(`CHANGELOG.md:32`)가 바뀐 동작과 재생성 필요를 적는다. **남은 것.** Gitea가 `needs`와 암묵적 `success()`를 GitHub Actions처럼 처리하는지는 미확인이다(5절). 완료 기준에 들지 않는다 |
|
||||
|
||||
### 2.2 1103 이월(README §16.5)
|
||||
|
||||
| 지난 ID | 내용 | 상태 | 근거 |
|
||||
|---|---|---|---|
|
||||
| 1103/13-03 | 취약점 판정이 운영 승격 provider에만 있고, lockfile이 자체 정책을 어기는데 merge·release에서 모른다 | **일부(결정 대기)** · §16.5 "결정 대기"와 같다 | **지난 라운드에 고쳐진 것은 그대로다.** FE-GATE-027이 `scan:dependency-advisories`를 돈다(`config/ci/gates.json:2212-2213`). 판정은 승격과 같은 정책을 쓴다(`scripts/scan-dependency-advisories.ts:25-44`). 항상 exit 0이다. **남은 것.** (1) 운영 high 2건. `8a44226..bbde570`에서 `pnpm-lock.yaml`은 바뀌지 않았다. `package.json`의 의존성 칸도 그대로다(바뀐 곳은 `test:all` script 한 줄). 그래서 `react-router-dom@7.18.1`·`zod@4.4.3`(`package.json:160-161`, `pnpm-lock.yaml:2376`, `:2816`)이 그대로다. 결정 조건과 재확인 날짜(2026-12-04)가 문서에 있다(`docs/operations/ci-quality-gates.md:556-565`). 2026-11-06 04:24 FE-GATE-027 로그는 `POLICY_VIOLATION (production: critical 0, high 2, moderate 0, low 0; development: critical 0, high 0, moderate 2, low 0)`다. 경고 대상은 `GHSA-qwww-vcr4-c8h2:react-router@7.18.1:high`와 `GHSA-mrhx-c7xc-m3w5:zod@4.4.3:high`다(13-R1 B, E3). (2) 신호 가시성. 지난 라운드의 원인(1105/13-01)은 계약 수준에서 고쳐졌다. 실제 run 확인은 남았다(2.1절). 승인이 거절된 run에는 기록이 없다(새 13-01). (3) renovate는 runner가 없어 동작하지 않는다(`renovate.json:4`). **새 사실.** D7로 초기 JS 예산이 206,848 B가 됐다. bbde570의 여유는 2,690 B다(FE-GATE-012). 문서가 react-router 7.18.5의 비용으로 적은 약 470 B는 이 여유 안이다. 그러면 react-router를 막는 것은 "owner와 다른 reviewer" 규칙 하나다. zod 4.6.7의 약 7 KB는 여전히 예산을 넘는다(`ci-quality-gates.md:564-565`). D7 근거도 "이 상향은 13-03을 정하지 않는다"고 적는다(지난 README §16.2) |
|
||||
|
||||
### 2.3 그 밖의 이월(지난 영역 문서 2.2절의 남음·일부)
|
||||
|
||||
| 지난 ID | 내용 | 상태 | 근거 |
|
||||
|---|---|---|---|
|
||||
| 1101/13-03 | provider job의 호스트 전제와 workflow의 컨테이너 전제가 어긋나고 provider 없는 배포 경로가 없다 | **남음** | provider job은 `runs-on: ubuntu-latest`다(`.gitea/workflows/quality-gates.yml:228`, `:274`). 배포 슬롯은 promotion 뒤에만 돈다(`:391`, `scripts/contracts/ci-gates.ts:946-947`). provider 없이 배포하는 절은 문서에 없다. **새 사실.** provider는 bwrap namespace 옵션으로 뜬다(`scripts/run-and-validate-provider.ts:255-257`). 문서는 이 조건이 "provider job과 merge 게이트 FE-GATE-013 둘 다에 걸린다"고 적는다(`docs/operations/ci-quality-gates.md:198-205`). 그러나 workflow에서 요구 주석은 merge job에만 있다(`.gitea/workflows/quality-gates.yml:37-38`). 주석은 job이 도는 gate의 `hostRequirements`에서 나온다(`scripts/generate-ci-workflow.ts:245-253`). provider job에는 gate가 없어 주석이 없다. provider job 시작 점검은 `/usr/bin/bwrap`이 있는지만 본다(`run-and-validate-provider.ts:116-117`). bbde570 test:system에서 provider supervisor는 18건 모두 `sandbox reported: bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`로 끝났다(E3, `bbde570-013-parts/system-vitest.log`). 이 desktop에 runner를 붙이면 provider job이 같은 한 줄로 끝날 것으로 본다(추정, runner 미실행). 1105/12-01(영역 12)과 원인이 같다. 12-01은 FE-GATE-013 쪽을 고쳤고 provider job 쪽은 이 항목에 남는다 |
|
||||
| 0929/13-02 | `.env*` 파일로 준 빌드 변수를 번들과 스크립트가 다르게 읽는다 | **남음** | `vite.config.ts:19`의 `loadEnv`는 미선언 변수를 거절할 때만 쓴다. base와 설정 URL 검사는 `process.env`를 읽는다(`:193-194`). `scripts/generate-runtime-config.ts:77-78`, `scripts/generate-build-manifest.ts:42-46`, `vite.service-worker.config.ts:61-62`, `:68`도 `process.env`다. `.env.example:14`는 여전히 "`.env.local`로 복사해 덮어쓰라"고 적는다. 이번에 다시 재현하지는 않았다(E1) |
|
||||
| 0929/13-03 | 청크 이름이 선언 없이 계약처럼 쓰인다 | **남음**(Medium·P2로 보고됨, fail-closed) | route chunk를 `entry.name === runtime?.moduleId && entry.isDynamicEntry`로 찾고 없으면 빌드가 멈춘다(`scripts/generate-build-manifest.ts:70-78`) |
|
||||
| 0929/13-04(= R-3) | CSP가 여러 벌이고 내용 검사가 없다 | **남음** | 같은 CSP 문자열이 6곳에 있다: `config/hosting/security-headers.json:4`, `config/hosting/response-headers.fixture.json:7`, `:17`, `:27`, `:42`, `docs/operations/release-cache-rollback.md:121`. `scripts/check-browser-security.ts`에는 CSP 검사가 없다(grep 0건). live probe만 받은 헤더를 `security-headers.json`과 비교한다(`scripts/verify-hosting-headers.ts:174-186`). FE-GATE-019를 돌릴 때만 일어난다 |
|
||||
| 0929/13-05 | SBOM이 `deduped` 노드를 따라가지 않는다 | **남음** | `scripts/lib/supply-chain.ts`에 `deduped`가 0건이다. 기준선의 `scheduler`가 `scope: development`다(`config/security/dependency-baseline.json:5778-5781`). bbde570에서 새로 만든 inventory도 같다(사본 `artifacts/release/dependency-inventory.json:5778-5781`, 03:56). 실제로는 react-dom 청크에 묶여 실린다(`vite.config.ts:259`) |
|
||||
| 0929/13-06 | 하위 경로 배포에서 base를 따르지 않는 소비자가 있다 | **일부(남음)** | live probe가 루트가 아닌 URL을 거절한다(`scripts/lib/hosting-probe.ts:453-456`) |
|
||||
| 0929/13-10 | 선택 기능을 켜야 재현되는 템플릿 결함의 책임 | **남음** | "unmodified checkout" 문구가 그대로다(`README.md:421-426`) |
|
||||
| R-2 | 빌드 입력 기본값을 한 곳에서 정한다 | **남음** | 기본값이 다섯 곳에 흩어져 있다: `src/contracts/env.ts:54-55`(레지스트리), `:204-205`(`\|\|`), `scripts/generate-runtime-config.ts:77`(`\|\|`)·`:78`(`??`), `scripts/generate-build-manifest.ts:42-44`(`??`), `vite.service-worker.config.ts:61-62`(`??`) |
|
||||
|
||||
지난 라운드에 고쳐진 이 영역 발견의 재발도 봤다. 셈에 넣지 않는다.
|
||||
|
||||
| 지난 ID | 재발 | 근거 |
|
||||
|---|---|---|
|
||||
| 1103/13-01 | 없음 | `config.json` 비교(`scripts/lib/hosting-probe.ts:222-225`)와 슬롯 입력 규칙(`scripts/contracts/ci-gates.ts:1292`, `:1335`)이 그대로다. `hosting-probe` 39건 통과(FE-GATE-005) |
|
||||
| 1103/13-02 | 없음 | ALPN 판정(`hosting-probe.ts:236-252`), entry `Content-Encoding` 판정(`scripts/verify-hosting-headers.ts:165-168`), 선언(`config/hosting/cache-policy.json:4`, `:29`)이 그대로다. live 분기는 이제 `probeLiveHosting` 하나로 묶였다(`verify-hosting-headers.ts:113-118`, 1105/06-02 수정) |
|
||||
| 1103/13-04 | 없음 | `env-registry-coverage` 4건 통과(FE-GATE-005) |
|
||||
| 1103/13-05 | 없음 | 배포 단계 `secrets.*`는 deploy 단계 `env:`에만 렌더링된다(`scripts/generate-ci-workflow.ts:376-377`) |
|
||||
| 1103/11-08 | 없음 | `scripts/lib/build-environment.ts`는 이 범위에서 바뀌지 않았다. FE-GATE-008·020 CI env 통과 |
|
||||
|
||||
### 2.4 이 영역 파일을 바꾼 수정의 검사 약화 확인 (`git diff 8a44226..bbde570`)
|
||||
|
||||
| 커밋 | 바뀐 검사 | 판정 | 근거 |
|
||||
|---|---|---|---|
|
||||
| `629c713`(1105/13-01) | `ci-workflow-generation.test.ts`의 `actionUses` 개수 33 → 34 | 약화 아님 | upload 단계 하나가 늘었다. 개수는 여전히 정확히 비교한다. 계약 단계 목록도 upload 하나를 더 요구한다(`ci-gates.ts:961`). 새 규칙과 정상·거절 테스트 6건이 더해졌다 |
|
||||
| `92d5019`(1105/13-02) | `product-ci-overlay.test.ts`의 "템플릿 부분 바이트가 같다" 단언 | 약화 아님 | 비교 전에 정확히 한 줄(`needs: [merge_gate, product_merge_gate]` → `needs: merge_gate`)만 바꾼다(`:151`). 그 줄은 새 테스트가 직접 단언한다(`:163-189`). 실패 목록 단언에 새 메시지가 더해졌다 |
|
||||
| `9655958`·`67082cc`(1105/12-01) | gate 모양 digest가 `hostRequirements`를 본다. 기준선 재기록(`config/ci/contract-baseline.json`) | 약화 아님(영역 12) | gate·명령·artifact 수는 그대로다(27·100·104·110). digest만 바뀌었고 이유가 적혀 있다 |
|
||||
| `4d6f254`(1105/06-02) | 자산 MIME probe의 fetch가 `redirect: "follow"` → `"manual"`, redirect면 FAIL | 강화(영역 06) | `hosting-probe.ts:291`, `:308-330`. Node의 `manual`은 3xx를 그대로 돌려준다. 그때 관측값은 `redirected`가 아니라 `HTTP 30x`로 남지만 FAIL은 같다 |
|
||||
| `f4d5761`(1105/12-04) | 빌드 단계 경로가 `RUN_OUTPUT_ROOT` 아래로 갈 수 있다 | 약화 아님 | 값이 없으면 경로가 전과 같다(`scripts/lib/run-isolation.ts:63-83`). release job env와 workflow env는 계약과 바이트 비교가 고정한다. 지난 라운드에 job env 바인딩을 더하면 `check:ci`가 거절했다(1105 13-R03). 그래서 release 빌드에 이 값이 들어갈 길은 없다. 로컬에서 값을 export하고 `ci:gate FE-GATE-011`을 돌리면 evidence 신선도 검사가 실패한다(`scripts/run-ci-gate.ts:203` "command-generated evidence was not freshly produced", 정적 추론) |
|
||||
| `287dc6f`(D7) | 초기 JS 예산 204,800 → 206,848 B | 기록된 상향(영역 15) | 메인 세션 결정. 근거와 재검토 조건이 지난 README §16.2에 있다. 이 문서는 1103/13-03과의 관계만 적는다(2.2절) |
|
||||
| `81701ad`(1105/15-04), `7ead8d3`(0929/10-05) | lab 예산 칸 추가, `test:all` 경로 | 영역 15·10 | 이 영역 검사와 무관하다 |
|
||||
|
||||
## 3. 이번 발견 (36.3)
|
||||
|
||||
새 발견은 1건이다. Low 1. P3 1. 확인된 결함 1. High 이상과 P1은 없다.
|
||||
|
||||
### 13-01 FE-GATE-027의 공개 대상 승인이 거절되면 advisory 검사가 돌지 않아, 그 run의 증거에는 advisory 기록이 없다. 문서는 결과와 상관없이 올린다고 적는다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| ID·제목 | 13-01(라운드 밖: `1106/13-01`) — 위 제목 |
|
||||
| 성격 | 확인된 결함(문서와 동작의 차이). 1105/13-01 수정이 새로 쓴 문장이다 |
|
||||
| 관련 관점 | 5, 8, 23, 16 |
|
||||
| 근거 | **명령 순서.** FE-GATE-027은 `check-release-admission`을 먼저, `scan-dependency-advisories`를 뒤에 돈다(`config/ci/gates.json:2212-2213`). 1103/13-03 수정(`26ca2fd`)이 이 순서로 넣었다. **멈춤.** `ci:gate`는 기대와 다른 결과가 나온 첫 명령에서 `break`한다(`scripts/run-ci-gate.ts:176-190`). 승인 거절은 exit 1이다(`scripts/check-release-admission.ts:183-190`). FE-GATE-015가 실패하면 FE-GATE-027 단계 자체가 돌지 않는다(`.gitea/workflows/quality-gates.yml:147-150`, `always` 없음). **주장.** 문서는 같은 job이 "`scan:dependency-advisories` 기록을 … 성공·실패와 상관없이 올린다"고 적는다(`docs/operations/ci-quality-gates.md:169-173`). 영어 절도 "uploads … this record … whether the job passed or failed. Read why FE-GATE-015 or FE-GATE-027 failed, and the advisory status, there"라고 적는다(`:540-544`). 실제로 올라가는 것은 그 run에 생긴 파일뿐이다. **실행 확인(13-R1, CI env).** 같은 checkout에서 B(승인 통과)는 `dependency-advisories.json`을 새로 만들었다. C(production 대상 거절, rc=1)는 `FE-GATE-027.txt`와 `deployment-admission.json`만 새로 만들고 `dependency-advisories.json`은 만들지 않았다. C의 로그에는 `release admission refused for production:`만 있고 `Dependency advisories` 줄이 없다. 깨끗한 runner라면 이 파일은 아예 없다 |
|
||||
| 발생 조건 | release 단계 run에서 FE-GATE-015가 실패하거나 FE-GATE-027의 승인이 거절될 때. 예: `RELEASE_TARGET`이 비었거나 `APP_PROFILE`과 다를 때, production 대상에 예시 endpoint가 남았을 때 |
|
||||
| 영향 | 그 run의 산출물로는 advisory 상태를 알 수 없다. 거절 이유는 로그에 남는다. 승인을 고쳐 다시 돌리면 다음 run에 기록이 생긴다. 막지 않는 신호라 사용자 피해는 없다 |
|
||||
| 심각도·우선순위 | Low · P3. 제한된 문서 불일치이고 진단 정보 하나가 한 번 늦게 보인다(35.2 Low) |
|
||||
| 통제·증거 | 기록 생성 M2(승인 통과 때만) · E1(명령 순서와 `break`) + E3(13-R1 B·C, CI env) |
|
||||
| 확실성과 남은 가정 | 순서와 멈춤은 코드와 실행으로 확인했다. 실제 runner의 upload가 없는 파일을 건너뛰는지는 미확인이다(5절) |
|
||||
| 결정의 근거 | 확인한 사실: 승인은 막는 검사이고 advisory는 막지 않는 신호다(`scripts/scan-dependency-advisories.ts:18-21`). 기록된 의도: advisory 상태를 release 산출물에서 읽게 한다(`ci-quality-gates.md:540-544`). 리뷰어 추론: 막지 않는 신호를 막는 검사 뒤에 두면 막힌 run에서 신호가 사라진다. 앞에 두면 둘 다 남는다 |
|
||||
| 이해 비용 | 거절된 run의 산출물을 연 운영자는 advisory 기록이 왜 없는지 문서로 알 수 없다 |
|
||||
| 최소 개선 방향 | 둘 중 하나다. (a) 문서 두 곳을 "FE-GATE-027이 승인을 통과한 run에만 advisory 기록이 있다"로 고친다. (b) FE-GATE-027의 명령 순서를 scan → 승인으로 바꾼다. scan은 항상 exit 0이라 승인 판정은 그대로다 |
|
||||
| 대안 비교 | (a) 문서만 — 가장 싸다. 신호는 계속 한 run 늦는다. (b) 순서 바꿈 — 승인이 거절된 run에도 기록이 남는다. gate 모양 digest가 바뀌어 계약 기준선을 다시 적어야 한다(`config/ci/contract-baseline.json`). 승인 전에 `pnpm audit`이 돌아 실패 run이 최대 120초 늦어질 수 있다(`scan-dependency-advisories.ts:36`). (c) scan을 별도 always 단계로 뺀다 — 계약 단계 목록이 바뀐다. 리뷰어 추천은 (a)다. 신호의 가치가 작다 |
|
||||
| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다. 승인 판정과 후보 archive 멤버는 그대로 둔다 |
|
||||
| 비용·부작용 | (a) 문서 두 줄. (b) gates.json 두 줄, 기준선 재기록, 문서 |
|
||||
| 재검토 조건 | advisory를 막는 검사로 바꾸거나, `ci:gate`가 실패 뒤에도 막지 않는 명령을 돌게 바뀌면 다시 본다 |
|
||||
| 완료 기준 | 문서가 실제 동작과 같다. (b)를 고르면 승인이 거절된 run에서도 `artifacts/security/dependency-advisories.json`이 새로 생긴다 |
|
||||
| 검증 방법 | 13-R1 C와 같은 실행. (b)면 `ci:gate FE-GATE-027`을 `RELEASE_TARGET=production`과 로컬 빌드로 돌려 기록이 생기는지 본다 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
| 재검증 결과 | 해당 없음(신규) |
|
||||
|
||||
## 4. 28개 관점 판정 (36.2)
|
||||
|
||||
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역. **굵은 번호**는 이 영역이 깊게 본 관점이다.
|
||||
|
||||
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | 코드 성숙도 | > 영역 09·12 | — | — | > — 두 수정 모두 주석이 문제·선택·남은 한계를 적는다(`generate-ci-workflow.ts:68-78`, `ci-gates.ts:1200-1205`) |
|
||||
| 2 | 구조적 성숙도 | > 영역 12 | — | — | > |
|
||||
| 3 | 변경 용이성 | 적용 | M2 / M2 | E1·E2 | P — 제품이 템플릿 파일을 고치지 않고 배포 job과 release를 막는 검사를 넣는다(1105/13-02 고쳐짐). 빌드 입력 기본값은 다섯 곳이다(R-2) |
|
||||
| 4 | 인지 부하 | 적용 | M1 | E1 | P — release 실패 이유는 이름 있는 산출물 하나에서 읽는다고 문서가 적는다(`ci-quality-gates.md:540-544`). 콘솔은 한 줄이다 |
|
||||
| 5 | 위험 가시성 | 적용 | M3 / 일부 M2 | E2·E3 | P — advisory 기록이 release 산출물에 올라간다(계약 M3). 파일은 CI env에서 생긴다(13-R1 B). 실제 runner run은 미확인. 승인이 거절된 run에는 기록이 없다(13-01, 13-R1 C) |
|
||||
| 6 | 실패 성숙도 | 적용 | M3 | E2·E3 | O — 승인은 선언되지 않은 대상을 거절하고(`check-release-admission.ts:72-82`) 빌드 단계는 즉시 멈춘다. FE-GATE-013은 이제 사전 점검에서 이유와 함께 멈춘다(영역 12) |
|
||||
| 7 | 운영 성숙도 | 적용(일부) | M1 | E1·E3 | P — provider 없는 배포 경로가 없다. provider job의 namespace 요구가 그 job에 적혀 있지 않고 점검도 없다(1101/13-03, system-vitest 18건) |
|
||||
| **8** | 디버깅 가능성 | 적용 | M3 / runner 미확인 | E2·E3 | P — release job이 gate 로그를 always로 올린다(1105/13-01, 계약이 고정). 실패한 FE-GATE-015·027의 로그에 이유가 남는다(13-R1 A·C). 실제 runner 산출물은 미확인이다. provider job 실패는 bwrap 원문 한 줄이다(1101/13-03). TLS·전송 실패는 `error.name`만 남는다(`hosting-probe.ts:168`, `:242`, `:319`) |
|
||||
| 9 | 유지보수 성숙도 | 적용 | M2 | E1 | P — CSP 6벌(0929/13-04), 기본값 다섯 곳(R-2) |
|
||||
| 10 | 테스트 성숙도 | 적용 | M3 | E2 | P — 두 수정 모두 정상·거절 단언이 있고 bbde570에서 통과했다. 거절 단언이 규칙 메시지를 확인해 변이 시험 역할을 한다. 실제 runner·TLS·nginx를 쓰는 자동 시험은 없다 |
|
||||
| 11 | 데이터 성숙도 | > 저장소 영역 | — | — | > |
|
||||
| 12 | 동시성 성숙도 | > 탭·저장소 영역 | — | — | > |
|
||||
| 13 | 확장성 | > 영역 11·15 | — | — | > |
|
||||
| 14 | 성능 성숙도 | 적용(서빙 전제) | M3 | E2 | P — h2·압축 판정은 그대로다(재발 없음). 초기 JS 204,158 / 206,848 B, 27 / 32파일(FE-GATE-012). 예산 상향은 영역 15 |
|
||||
| 15 | 보안 성숙도 | 적용 | M3 / 일부 M0 | E1·E2 | P — 운영 high advisory 2건이 결정 대기다(1103/13-03). 슬롯 secret 위치·`config.json` 비교는 재발 없다 |
|
||||
| **16** | 의존성 성숙도 | 적용 | 판정 M3(승격) / 신호 M3(계약) / 갱신 M1 | E1·E3 | P — lockfile이 이 범위에서 그대로다. 2026-11-06 advisory는 운영 high 2·개발 moderate 2다(13-R1 B). 운영 2건, 동작하지 않는 renovate, SBOM `scheduler` 분류(0929/13-05), 승인 거절 run의 기록 누락(13-01)이 남았다. react-router 갱신은 이제 예산 안이다 |
|
||||
| 17 | API / Contract 성숙도 | 적용(설정 계약) | M3 | E2 | O — FE-REG-ENV 행과 스키마 대조가 유지된다(`env-registry-coverage` 4건) |
|
||||
| **18** | 배포 성숙도 | 적용 | M3 / 일부 M0 | E1·E2 | P — 제품 검사가 release·배포를 막는다(1105/13-02). provider 없이 슬롯에 갈 수 없다(1101/13-03). 하위 경로 배포는 PASS할 수 없다(0929/13-06). 실제 runner에서 job 그래프를 돌린 적이 없다 |
|
||||
| **19** | 설정 성숙도 | 적용 | M3 | E1 | P — `.env*` 입력 갈림(0929/13-02)과 기본값 갈림(R-2)이 남았다 |
|
||||
| 20 | 개발자 경험 | 적용 | M1 | E1 | P — CHANGELOG가 제품 gate가 있는 다운스트림의 재생성 단계를 적는다(`CHANGELOG.md:32`). runner 요구 고치는 법이 문서에 있다(`ci-quality-gates.md:198-235`) |
|
||||
| **21** | Guardrail 성숙도 | 적용 | M3·M4 | E2 | P — release job 증거 upload와 제품 gate → release 연결을 `check:ci`가 지킨다. 생성 workflow 바이트가 생성기와 같다(FE-GATE-010). 실제 runner 의미는 미확인이다 |
|
||||
| 22 | 추상화 성숙도 | > 영역 09·12 | — | — | > |
|
||||
| 23 | 일관성 | 적용 | M1 | E1 | P — 빌드 변수 출처(0929/13-02)와 기본값(R-2) 갈림, 문서와 동작 차이 하나(13-01) |
|
||||
| 24 | 네이밍 / 의미 성숙도 | 적용 | M1 | E1 | O — `product_merge_gate`가 이제 release도 막아 이름과 동작이 맞는다(지난 P의 원인 해소) |
|
||||
| 25 | 조직 확장성 | - 1인 관리 전제 | — | — | - |
|
||||
| 26 | Ownership 성숙도 | 적용 | M1 | E1 | P — advisory 결정에 owner와 다른 reviewer가 필요한데 1인 운영에는 없다(`ci-quality-gates.md:564-565`). 선택 기능 결함 분류(0929/13-10)가 남았다 |
|
||||
| 27 | 삭제 가능성 | > 영역 14 | — | — | > |
|
||||
| 28 | 회복 가능성 | 적용 | M2 | E1 | P — 비상 스위치만 바꾼 호스트는 probe를 통과하는 규칙이 그대로다(`runtime-config-switches.ts`). 슬롯 배포 뒤 FE-GATE-019가 실패해도 자동으로 되돌리지 않는다(프로젝트 몫) |
|
||||
|
||||
## 5. 미검증
|
||||
|
||||
| 항목 | 이유 | 확인하려면 |
|
||||
|---|---|---|
|
||||
| 실제 Gitea runner의 `immutable-gate-evidence` 산출물. 업로드 action이 여러 줄 `path`에서 없는 파일을 건너뛰고 `if-no-files-found: error`를 전체 0개일 때만 쓰는지 | runner 없음(Actions 꺼짐) | `stage=release` dispatch 1회, FE-GATE-027을 일부러 거절시킨 run 1회 |
|
||||
| Gitea가 `needs`와 암묵적 `success()`를 GitHub Actions처럼 처리하는지(1105/13-02) | runner 없음 | 제품 gate 하나를 실패시키고 `stage=release` 1회 |
|
||||
| 재실행 때 artifact 이름 충돌. merge·release·production gate의 upload 이름에는 `run_attempt`가 없다(`.gitea/workflows/quality-gates.yml:81`, `:120`, `:446`). immutable·provider·promotion 쪽은 있다 | runner 없음. action 버전의 동작을 모른다. 영역 12와 겹친다 | 실패한 run을 "다시 실행" 1회 |
|
||||
| desktop에 runner를 붙였을 때 provider job이 같은 bwrap 한 줄로 끝나는가(1101/13-03) | runner 미실행. 같은 오류는 test:system에서만 봤다 | host-mode runner에서 provider job 1회 |
|
||||
| `zod`·`react-router` advisory가 이 앱에서 실제로 닿는가 | 코드 경로를 끝까지 따라가지 않았다 | advisory 조건과 사용 지점 대조 |
|
||||
| `.env*` 입력 갈림(0929/13-02) 재현 | 코드가 그대로라 정적 확인만 했다. 실험은 desktop checkout에 무시되는 `.env.local`을 남길 위험이 있어 요청하지 않았다 | 별도 사본에서 `.env.production.local`에 `VITE_ROUTER_BASE_PATH=/app/`를 두고 빌드 |
|
||||
| `RUN_OUTPUT_ROOT`를 export한 채 `build:release-candidate`를 돌릴 때. 빌드는 `.tmp/…`에 쓰고 뒤 단계는 checkout의 `dist`를 읽는다 | CI에는 들어갈 수 없어 요청하지 않았다(2.4절). 로컬 오용만 해당한다 | 오래된 `dist`가 있는 checkout에서 한 번 돌려 fail-closed인지 본다 |
|
||||
|
||||
## 6. 실행 기록
|
||||
|
||||
이 리뷰는 desktop에서 직접 아무것도 돌리지 않았다. 1절의 기존 로그와 사본, 배치 결과를 `ssh desktop cat/grep/ls/sed`로 읽었다. 배치는 오케스트레이터가 desktop checkout에서 돌렸다(`ref=bbde5707`, `mode=plain`, `env=CIENV`, 부하 4.50). 끝난 뒤 `restore=clean`이다. 노트북에서는 git 읽기 명령과 파일 읽기만 썼다. 예외가 하나 있다. `config/ci/gates.json`의 gate별 명령 목록을 보려고 `python3 -I`로 JSON을 한 번 읽었다. 쓰기는 없었다. 브리프의 노트북 허용 목록 밖이라 적어 둔다.
|
||||
|
||||
| 이름 | 명령 · env | 변이 | rc | 결과 |
|
||||
|---|---|---|---|---|
|
||||
| 13-R1 | `bash 13-R1.sh`(스크립트 `scratchpad/r5/13/13-R1.sh`) · CIENV, 2026-11-06 04:24 | - | 0(스크립트). A rc=1, B build rc=0·gate rc=0, C rc=1 | 세 부분 모두 기대와 같다. **A** FE-GATE-015(`VITE_COMMIT_SHA`=0×40): 콘솔 `FE-GATE-015 release-coherence: FAIL`. 7개 경로 중 새 파일은 `FE-GATE-015.txt` 하나. 로그 `VITE_COMMIT_SHA does not identify the checked-out commit`. **B** FE-GATE-027(local): 콘솔 `PASS (release-coherence)`. 새 파일 `FE-GATE-027.txt`, `deployment-admission.json`, `dependency-advisories.json`. 로그 `local ADMITTED`, `POLICY_VIOLATION (production: … high 2 …; development: … moderate 2 …)`, `GHSA-qwww-vcr4-c8h2:react-router@7.18.1:high`, `GHSA-mrhx-c7xc-m3w5:zod@4.4.3:high`. **C** FE-GATE-027(production): 콘솔 FAIL 한 줄. 새 파일 `FE-GATE-027.txt`, `deployment-admission.json`. `dependency-advisories.json`은 새로 생기지 않았다. 로그 `release admission refused for production:`, `Dependency advisories` 줄 없음 |
|
||||
|
||||
요청 파일은 `scratchpad/r5/requests/13.md`, 결과는 `desktop:/tmp/claude-gates/r5/batch/out/R5-13-R1.log`다. 변이는 없다. 대조군이 필요한 판정은 없었다(세 부분 모두 같은 실행 안에서 비교했다).
|
||||
|
||||
## 7. 새 발견 요약
|
||||
|
||||
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|
||||
|---|---|---|---|---|
|
||||
| 13-01 | Low·P3 | 확인된 결함 | FE-GATE-027의 승인이 거절되면 advisory 검사가 돌지 않아 그 run의 증거에 advisory 기록이 없다. 문서는 결과와 상관없이 올린다고 적는다 | `config/ci/gates.json:2212-2213`, `scripts/run-ci-gate.ts:176-190`, `docs/operations/ci-quality-gates.md:169-173`, `:540-544` |
|
||||
@@ -0,0 +1,279 @@
|
||||
# 영역 14 — 템플릿 제품성·문서·DX·업데이트 전파
|
||||
|
||||
> 검토일 2026-11-06 · 기준 `bbde570` (PR B 끝, 노트북 worktree 브랜치 `docs/maturity-review-2026-11-06`) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
|
||||
>
|
||||
> 경로: `CHANGELOG.md`(특히 새 미출시 절 `:14-108`), `README.md`, `PRODUCT.md`, `docs/`(특히 `docs/manual/`, `docs/operations/performance-evidence.md`, `docs/architecture/starter-experience.md`), `recipes/`의 문서 주장, `scripts/verify-documentation-readiness.ts`, `scripts/lib/removable-template-features.ts`, `scripts/test-sample-removal.ts`, `scripts/lib/removal-fixture.ts`, 문서 테스트(`tests/unit/documentation-readiness.test.ts`, `template-feature-removal-documents.test.ts`, `manual-paired-backend-settings.test.ts`, `changelog-review-ids.test.ts`). `docs/reviews/`는 이력이라 판정하지 않았다. 2026-11-05 README §16은 코드와 대조할 주장으로만 읽었다.
|
||||
>
|
||||
> 깊게 본 관점: 9 유지보수, 17 API/Contract, 20 개발자 경험, 23 일관성, 26 Ownership, 27 삭제 가능성, 30절 전체
|
||||
>
|
||||
> 렌즈: ① 새 미출시 절(`409d72e` → PR B)의 해시가 `bbde570` 이력에 있고 이름 댄 변경을 가리키는가. ② BREAKING 다섯의 "먼저 할 일"·[계약] 행이 코드와 커밋 꼬리말과 같고, 두 다운스트림(memento `d3810a0`, tech-log `7a4e201a`)이 따라 하면 맞는 변경이 되는가. ③ 1105 영역 14 발견 셋과 이월 열 건이 완료 기준을 채웠는가. ④ 이 영역 수정이 검사를 약하게 했는가. ⑤ D7(초기 JS 예산 상향) 문서가 이유와 재검토 조건을 §16.2와 같게 적는가.
|
||||
>
|
||||
> 영역 판정(35.8): **새 프로젝트를 복사해 시작하는 용도는 지정 범위에서 사용 가능**으로 올렸다(지난 조건 1105/14-02가 고쳐졌다). **이 미출시 묶음을 다운스트림에 전파하는 용도는 조건부 사용 가능**이다. 해시 75개와 BREAKING 행 다섯은 모두 맞고, 다섯 단계를 따라 하면 두 제품 모두 맞는 변경이 된다. 조건은 셋이다. BREAKING 1~3단계 설명 셋이 코드·다운스트림 모양과 다르다(14-01). 안내를 다운스트림에 적용해 본 사람이 없다(1103/14-02 잔여). 예제 기능 제거 드릴은 이번 배치에서 통과했지만(14-R1) 게이트 밖이라, 다시 깨져도 아무도 모른다.
|
||||
>
|
||||
> ID 표기: 이 문서의 새 발견은 `14-01`부터다. 라운드 밖에서는 `1106/14-NN`이다. 지난 라운드는 `1105/14-NN`, 그 전은 `1103/`, `1101/`, `0929/`다.
|
||||
|
||||
## 0. 결론
|
||||
|
||||
핵심은 둘이다. CHANGELOG 새 절의 해시와 BREAKING 행은 이번에 처음부터 맞다. 남은 결함은 안내 문장 몇 개와 커밋 본문 해시 둘이고, 둘 다 동작을 바꾸지 않는다.
|
||||
|
||||
```text
|
||||
CHANGELOG 새 미출시 절 (409d72e → PR B, 비병합 79커밋)
|
||||
해시 75개: 모두 bbde570에서 닿고 409d72e에서는 안 닿는다 / Refs가 행의 ID와 75/75 같다
|
||||
인용 안 된 4커밋 = 리뷰 기록·CHANGELOG 커밋뿐 / ! 커밋 5개 = BREAKING 행 5개 = 먼저 할 일 1~5
|
||||
: 287dc6f(D7) 본문이 다시 쓰기 전 해시 ab0d4a1·7ce9bf1을 가리킨다 (14-02, 새)
|
||||
두 해시는 올리지 않은 로컬 fix/r1105-* 브랜치에만 있고, 원격 브랜치는 0개다
|
||||
|
||||
BREAKING 다섯 (먼저 할 일 1~5)
|
||||
커밋 꼬리말·코드·[계약] 행이 서로 같다. 두 제품이 따라 하면 맞는 변경이 된다
|
||||
: 1단계 "감싸지 않는 백엔드(memento-web, TechLog)" — TechLog는 Envelope다 (14-01 b)
|
||||
: 2단계 requiresIdempotencyKey를 retrySemantics에서 다시 계산한다는 말이 없다 (14-01 c)
|
||||
: 3단계 "부팅이 멈춘다" — 실제로는 그 기능 라우트에 처음 들어갈 때 실패한다 (14-01 a)
|
||||
|
||||
1105 영역 14 발견 셋: 모두 고쳐짐 (완료 기준을 변이·드릴로 확인)
|
||||
14-01 예제 기능 드릴 PASS (17 checks), 예외를 끄면 새 테스트 2건 실패 (14-R1, 14-R2)
|
||||
14-02 defaultValue를 지우면 새 테스트가 TS2322로 실패 (14-R4)
|
||||
14-03 참조 기능 파일 이름을 바꾸면 매뉴얼 두 줄로 verify:documentation 실패 (14-R3)
|
||||
: 예제 기능 드릴은 여전히 게이트 밖 (통제 잔여)
|
||||
|
||||
D7 문서: 이유·버린 대안·재검토 조건이 §16.2와 같다
|
||||
: performance-evidence.md:209-210 "템플릿 그대로의 수(26)" — 지금 27 (15 영역 1103/15-02로 넘김)
|
||||
```
|
||||
|
||||
- 새 발견 2건: Low 2(14-01, 14-02). High·P1은 없다.
|
||||
- 지난 발견 13건(1105 셋, 1103 이월 셋, 그 밖의 이월 일곱): 고쳐짐 7, 일부 4, 남음 2. 재발·틀린 발견은 이 영역 범위에서 없다.
|
||||
- §16과 다르게 본 것: 1105/14-01은 §16.4가 "일부"다. 완료 기준 셋을 모두 확인해서 **고쳐짐**으로 봤다(14-R1 드릴 PASS, 14-R2 변이, `PRODUCT.md:33`). "게이트가 드릴을 돌리지 않는다"는 완료 기준이 아니라 통제 수준 잔여로 4절 10·27번에 둔다. 0929/14-01은 §16.6이 "문서만 고쳤다"는 일부인데, 남은 것이 더 있다. 읽는 곳 없는 추적 산출물 13개가 남았다.
|
||||
- 수정이 검사를 약하게 한 곳은 찾지 못했다. 지운 템플릿 기능의 경로를 받는 새 예외(`scripts/verify-documentation-readiness.ts:190-208`)는 `feature-module.ts`가 없을 때만 열린다. 양쪽 방향을 테스트가 보고, 예외를 끄면 그 테스트가 실패한다(14-R2). `tests/unit/removal-fixture.test.ts:161`의 정규식이 `docs/`를 받게 넓어졌지만, 목록의 새 테스트가 `docs/`를 읽기 때문이다.
|
||||
- D7 상향 자체(예산 숫자)는 15 영역이 판정한다. 이 영역은 기록만 봤다.
|
||||
|
||||
지금 이해하면 되는 것:
|
||||
|
||||
1. 두 제품은 이 묶음을 받을 때 "먼저 할 일" 1~5를 그대로 따라 해도 된다. 1단계의 TechLog 설명과 3단계의 증상 설명만 틀리다.
|
||||
2. tech-log는 2단계를 할 때 관리(management) 뮤테이션의 `requiresIdempotencyKey`가 `true`에서 `false`로 바뀐다는 것을 알아야 한다. 그 경로는 지금도 템플릿 실행기와 맞지 않는다.
|
||||
3. 예제 기능을 지운 제품은 템플릿 문서를 고치지 않아도 문서 검사와 그 드릴을 통과한다(14-R1). 다만 그 드릴을 도는 게이트는 없다.
|
||||
|
||||
## 1. 범위 (36.1)
|
||||
|
||||
| 항목 | 기록 |
|
||||
|---|---|
|
||||
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`. 읽기만 한 저장소: `clean-architecture-backend-template`(pin `45d2a478`, `git cat-file`로만), `memento-frontend`(`d3810a0`), `tech-log-frontend`(`7a4e201a`). 두 다운스트림 HEAD는 지난 라운드와 같다 |
|
||||
| 커밋·작업 상태·확인 시점 | `bbde570`, 노트북 worktree(읽기만), 2026-11-06. desktop에서는 `/tmp/claude-gates/` 아래 파일만 읽었다 |
|
||||
| 목적과 지원 실행 구성 | 복사해서 시작하고 Git으로 원본 수정을 받아 가는 프론트엔드 템플릿. 짝 백엔드 템플릿과 함께 쓴다. 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음 |
|
||||
| 필수 요구와 규모·운영 목표 | 두 템플릿으로 서비스를 빨리 출시한다. 두 다운스트림이 범위 단위로 동기화한다(memento merge, tech-log 3-way). 문서 규모 목표는 없다 |
|
||||
| 지난 리뷰 뒤 바뀐 것 | `8a44226..bbde570` 비병합 79커밋, 병합 14커밋. 이 영역 경로를 고친 비병합 커밋 59개. `docs/` 문서 212개 98,440줄(지난 195개 93,445줄). 매뉴얼 2,278줄(지난 2,206줄). 리뷰 밖 문서·recipe diff 35파일 +747/−195줄. 새 파일: `scripts/lib/removable-template-features.ts`, `tests/unit/template-feature-removal-documents.test.ts`, `tests/unit/manual-paired-backend-settings.test.ts` |
|
||||
| 읽은 코드·구성 범위 | `CHANGELOG.md` 전체(`:1-455`), `README.md:218-240`, `:372-424`, `PRODUCT.md`, `docs/README.md`, `docs/manual/` diff 전체, `docs/manual/reference/errors.md` 새 행, `docs/operations/performance-evidence.md` 전체, `docs/operations/ci-quality-gates.md:60-72`, `starter-experience.md:95-120`. 코드: 위 스크립트·테스트 전체, `src/contracts/external-contract-runtime.ts:230-245`, `:610-720`, `src/contracts/server-state.ts:265-330`, `src/adapters/realtime/polling/bounded-poll-coordinator.ts:1-140`, `:320-400`, `src/adapters/http/http-execution-v3.ts:445-515`, `src/features/installed-contract-contributions.ts`, `installed-feature-runtime-registries.ts`, `installed-feature-adapters.ts:40-90`, `src/bootstrap/runtime-adapters.ts:590-740`, `src/bootstrap/product-composition-contract.ts:60-170`, `config/performance/budgets.json`, `config/scale/feature-shape-ceilings.json`. BREAKING 다섯 커밋(`56272e8`, `48c1ab7`, `5c0b37e`, `05330e3`, `757d1c7`)의 본문과 diff, `287dc6f`, `0fee3fe`, `832774f`, `f4be426`, `1e576ef`, `b834b8d`, `50b631e`, `332bfee`, `1dda18d`, `e6b2a4f`, `1ac336a`, `57e3586`, `1c4e57c`. 두 다운스트림의 뮤테이션 정책·HTTP descriptor 파일과 `git diff --name-status af3d8e6 HEAD -- src` |
|
||||
| 수행한 테스트·실험 | 정적: 해시 대조(E-1), 범위 커밋·꼬리말 대조(E-2), 커밋 본문 해시(E-3), BREAKING 다섯과 두 다운스트림 대조(E-4), 다운스트림 수정 파일 분류 대조(E-5), CHANGELOG 경로 존재(E-6), 매뉴얼 새 오류 문구(E-7), 백틱 밖 지울 수 있는 기능 경로(E-8). 배치 14-R1~14-R4(`scratchpad/r5/requests/14.md`). 오케스트레이터가 `bbde570`에서 하나씩 돌렸고 매번 checkout을 clean으로 되돌렸다. 로그 `desktop:/tmp/claude-gates/r5/batch/out/R5-14-R1.log`~`R4.log`. 네 건 모두 기대대로다(6절) |
|
||||
| 게이트 결과(같은 커밋, 다른 사람이 돌림) | `desktop:/tmp/claude-gates/bbde570-ci/summary.txt`(CI env): FE-GATE-001~012·020 rc=0, 013 rc=1(user namespace, 12 영역). FE-GATE-005 `test:unit` 208파일 3,056건 통과. 그 안에 `documentation-readiness.test.ts` 22건(`gate-artifacts/FE-GATE-005.txt:180`), `template-feature-removal-documents.test.ts` 4건(`:104`), `manual-paired-backend-settings.test.ts` 1건(`:94`), `changelog-review-ids.test.ts` 2건(`:293`), `env-registry-coverage.test.ts` 4건(`:280`), `hosting-probe.test.ts` 39건(`:76`). FE-GATE-020: 참조 기능을 지운 사본에서 "paths and scripts of removed template features not required: reference-feature" 뒤 `Documentation readiness: PASS_SCOPED`(`FE-GATE-020.txt:1539-1541`), `reference-feature removal: PASS (31 checks, no fixture IDs)`(`:3087`). 오케스트레이터 공유 실행: `verify-documentation.local.txt`(옆 백엔드 checkout 있음) `PASS_SCOPED`, `verify-documentation.no-sibling.txt` 17개 `not verified` 뒤 `PASS_SCOPED` |
|
||||
| 확인하지 못한 범위·이유 | 두 다운스트림에서 실제 병합 뒤 게이트(제품 repo는 읽기만), tech-log 관리 쓰기 경로의 실제 동작, 다운스트림 descriptor의 `as` 단언이 `responseEnvelope` 누락을 잡는지(타입 검사 미실행), 깨끗한 환경 `install → dev`, 매뉴얼만 보는 기능 추가 재실험(X2), 목표 설계 문서 본문 전체 |
|
||||
| 이전 리뷰와 비교 가능한 범위 | 1105 영역 14 발견 3건, §16.5의 1103 이월 3건(14-01, 14-02, 15-02의 CHANGELOG 부분), §16.6의 이월 7건을 이 커밋에서 다시 판정했다(2절). 지난 실행 결과는 증거로 쓰지 않았다 |
|
||||
|
||||
## 2. 지난 발견 재확인
|
||||
|
||||
| 지난 ID | 내용 | 상태 | 근거 (`bbde570`) |
|
||||
|---|---|---|---|
|
||||
| 1105/14-01 | CHANGELOG 6단계대로 예제 기능을 지우면 문서 검사(FE-GATE-005 포함)와 안내한 드릴이 실패하고, `PRODUCT.md`는 지울 수 없다고 적는다 | **고쳐짐** (통제 잔여: 드릴이 게이트 밖) | 고쳐진 것: ① 문서 검사가 지울 수 있는 템플릿 기능 목록(`scripts/lib/removable-template-features.ts:24-53`)을 읽는다. 그 기능의 `feature-module.ts`가 없으면 기능·테스트 폴더, context, 전용 파일, 전용 script를 요구하지 않는다(`scripts/verify-documentation-readiness.ts:190-208`, `:388`, `:395-398`). 설치된 동안은 그대로 본다. 목록에 없는 폴더는 실패한다. ② `tests/unit/template-feature-removal-documents.test.ts:86-115`가 기능마다 그 경로를 지운 사본에서 사본의 검사기를 돈다. 설치된 기능 아래 없는 경로와 목록에 없는 폴더는 실패하는 것도 본다. FE-GATE-005(CI env)에서 4건 통과(`FE-GATE-005.txt:104`). ③ `tests/unit/hosting-probe.test.ts:252`가 테스트 전용 ID `fixture-feature`를 쓴다. ④ `PRODUCT.md:33`이 예제 화면 3개를 같은 드릴로 지울 수 있다고 적는다. ⑤ `starter-experience.md:104-118`이 지우는 법과 검사 규칙을 적는다. 완료 기준 셋을 확인했다. (가) 세 폴더를 지운 사본의 문서 검사: 위 ②가 FE-GATE-005에서 통과(E2). 예외를 끄는 변이에서는 "passes in a copy without platform-examples-feature"가 `starter-experience.md names paths that do not exist: src/contexts/platform-examples-context, src/features/platform-examples-feature, tests/features/platform-examples-feature`로 실패했다(14-R2, E3). 지난 라운드 14-R1의 실패 문구와 같다. (나) 드릴: `test:sample-removal -- --feature=platform-examples-feature`가 `platform-examples-feature removal: PASS (17 checks, no fixture IDs)`, `drill-rc=0`이다(14-R1, E3). 그 안에서 타입 검사·lint·`verify:documentation`(“removed template features not required: platform-examples-feature” 뒤 `PASS_SCOPED`)·i18n·디자인 시스템·아키텍처·레지스트리·`test:all`·커버리지·빌드가 돌았다(`R5-14-R1.log:5-33`, `:2144`, `:2198-2199`). (다) `PRODUCT.md:33`이 코드와 같다(E1). 통제 잔여: 어느 게이트도 이 드릴을 돌리지 않는다(`CHANGELOG.md:93`, FE-GATE-020은 참조 기능만). 다음에 깨져도 알리는 것은 문서 쪽 unit 테스트뿐이다. 4절 10·27번에 둔다 |
|
||||
| 1105/14-02 | 매뉴얼 04 §3.2 설정 키 예시에 `defaultValue`가 없어 `check:types`·`test:unit`이 실패한다 | **고쳐짐** | `docs/manual/04-paired-backend-session.md:126-129` 두 행에 `defaultValue: null`. `tests/unit/manual-paired-backend-settings.test.ts:112-144`가 §3.2의 첫 ts 블록을 사본의 `product-contracts.ts` 옆에 그대로 넣고 `tsc --project tsconfig.app.json`(= `check:types:app`의 tsc, `package.json:30`)과 FE-REG-ENV 행 대조를 돈다. FE-GATE-005에서 통과(`FE-GATE-005.txt:94`). 완료 기준("그대로 옮긴 사본에서 `check:types:app`과 env-registry-coverage가 통과")을 채운다(E2). 테스트가 매뉴얼 블록을 실제로 읽는지도 봤다. 두 행에서 `defaultValue: null`을 지운 변이에서 그 테스트가 `src/contracts/env.ts(94,9): error TS2322 … Property 'defaultValue' is missing …`로 실패했다(14-R4, `R5-14-R4.log:17-19`, E3). 지난 라운드 14-R3의 실패와 같은 문구다. 작은 잔여: 행 대조는 `tests/unit/env-registry-coverage.test.ts:22-27`의 규칙을 테스트 안 문자열(`manual-paired-backend-settings.test.ts:64-89`)로 한 벌 더 가진다. 지금 두 규칙은 같다. 새 발견으로 세지 않는다 |
|
||||
| 1105/14-03 | 참조 기능 경로 26줄을 백틱에서 빼 문서 검사 밖으로 냈다 | **고쳐짐** | `1dda18d`가 README와 §1 문서 12개의 참조 기능 경로·`test:reference-feature`를 다시 백틱(또는 명령 한 줄)으로 적었다. `template-feature-removal-documents.test.ts:129-155`가 §1 문서에서 지울 수 있는 기능의 경로·script가 백틱·링크·셸 블록 밖에 나오면 실패한다. FE-GATE-005 통과. 완료 기준 뒤 절반("참조 기능을 지운 사본에서는 통과")은 FE-GATE-020이 본다(`FE-GATE-020.txt:1539-1541`, `:3087`, E2). 앞 절반("파일 이름을 바꾸면 매뉴얼 줄 때문에 실패")은 같은 테스트 파일 `:99-114`가 덧붙인 경로로 본다. 실제 이름 변경도 돌렸다. `src/features/reference-feature/adapters/reference-http-gateway.ts`의 이름을 바꾸자 `verify:documentation`이 `docs/manual/01-add-a-feature.md`와 `docs/architecture/backend-api-and-server-state-contract.md`의 그 경로로 `FAIL_UNVERIFIED`, `verify-rc=1`이었다(14-R3, `R5-14-R3.log:4-8`, E3). 지운 기능 예외를 끄면 참조 기능을 지운 사본에서 12개 문서가 실패한다(14-R2, `R5-14-R2.log:15-26`). 다시 백틱으로 적은 경로가 실제로 검사를 받는다는 뜻이다. 커밋이 적은 한계(언어 없는 펜스 안 명령 아닌 줄은 안 본다)를 대조했다. 지금 그런 줄에 지울 수 있는 기능 경로는 없다(E-8) |
|
||||
| 1103/14-01 | CHANGELOG 미출시 절이 기준 커밋과 맞지 않는다 | **고쳐짐** | 지난 잔여 셋: (a) 초기 파일 상한이 `CHANGELOG.md:207`, `:317` 모두 32다(`config/performance/budgets.json:5`). `:317`의 커밋이 `1b8cb12` 대신 `2fef27d`이고 그 커밋은 `752a61f..8a44226` 안에 있다. (b) 알려진 제한 머리가 "범위 끝 `8a44226`"이다(`:359`). (c) `verify:documentation`(FE-GATE-017)이 "merge 게이트 밖"에 있다(`:218-220`). 모두 `832774f`. `:207`, `:372`의 "여유 1,873 B"는 기록 값이라고 커밋 본문이 적는다 |
|
||||
| 1103/14-02 | BREAKING 이행 안내가 두 다운스트림의 실제 모양과 다르다 | **일부** | 고쳐진 것: "옮기기 전" 2단계(`CHANGELOG.md:133-139`)가 수를 적는다. memento 26개(수정 23, 추가 3), tech-log 40개(수정 38, 추가 2). 두 repo에서 `git diff --name-status af3d8e6 HEAD -- src`(기능·context 폴더 밖)를 다시 세니 같다(E-5). 추가·수정 파일은 모두 세 분류(제품 소유 자리 있음 `:137`, 없음 `:138`, 템플릿 결함 후보 `:139`) 중 하나에 이름이 있다. 남은 것: 완료 기준 "memento-web 모양에 안내를 그대로 적용하면 `check:registries`가 통과한다"는 실행하지 않았다(`:91`, `:108`). 자리 없는 파일을 템플릿에 들일지는 결정 대기다(`:99`) |
|
||||
| 1103/15-02 (CHANGELOG 부분) | CHANGELOG가 초기 파일 예산을 26으로 적는다 | **고쳐짐** | `CHANGELOG.md:207`, `:317`이 32다(`832774f`). 같은 ID의 문서 부분에 새로 어긋난 곳이 있다. `docs/operations/performance-evidence.md:209-210`이 "상한은 템플릿 그대로의 수(26)에 6을 더한 32"라고 적는데, 기록은 `files: 27`이다(`config/scale/feature-shape-ceilings.json:43`, `0fee3fe`. 08-03 `f849d78`이 초기 파일 하나를 더했다). 1103/15-02의 완료 기준 "문서·JSON에 서로 다른 기준선이 없다"를 다시 어긴다. 15 영역 소관이라 여기서 세지 않는다(2.3절) |
|
||||
| 1101/14-02 | 리뷰 ID 꼴이 섞인다 | **고쳐짐** | `b834b8d`: `CHANGELOG.md:11`이 네 꼴(`MMDD/NN-MM`, `MMDD README N.N`(+`X2`), `MMDD NN 영역 P-NN-NN`, `백엔드 리뷰 MMDD/NN-MM`)을 정한다. `tests/unit/changelog-review-ids.test.ts:36-49`가 괄호 안의 README·X·P·백엔드 참조를 그 꼴로 막는다. FE-GATE-005 통과(`:293`). 작은 잔여: 괄호 밖 참조와 그 네 낱말이 없는 참조는 보지 않는다. 지금 그런 참조는 찾지 못했다 |
|
||||
| 0929/14-01 | 실행 로그·작업 기록이 복사 대상에 섞인다 | **일부** | 고쳐진 것: `docs/README.md:91`이 루트 `SPEC.md`·`tasks/`의 이유를 끝난 라운드에 맞췄다(`1ac336a`). README 지울 목록에 둘이 있다(`README.md:228`). 추적 `.log` 0개. 남은 것: 완료 기준 "`git ls-files artifacts`에 `.gitkeep`과 게이트가 읽는 증거만 남는다"를 채우지 못한다. `artifacts/tests/coverage-gateway/` 10개(2026-09-18 `ec7f20e`, `reference-http-gateway.ts.html` 포함)와 `artifacts/local-preview/*.png` 3개(2026-07-30 `d3ef801`)가 추적된다. `scripts`·`config`·`tests`·`.gitea`·`package.json` 어디도 읽지 않고(`git grep` 0건), README 지울 목록(`README.md:224-230`)에도 없다 |
|
||||
| 0929/14-02 | README 업데이트 절차가 범위 반영을 다루지 않는다 | **일부** | 고쳐진 것: `README.md:396-404`가 범위를 받는 두 명령(`git merge --no-ff`, `git merge-recursive <range base> -- HEAD …`)을, `:406-408`이 기준점 기록을 적는다(`57e3586`). 남은 것: 명령은 실행하지 않았다(커밋 본문). 완료 기준 "기준점 형식이 하나다"는 그대로다(`.template-origin`과 `template.lock.json`, `:406-408`). 새 문장끼리 어긋난다: `:407`의 "(below)"가 가리키는 `.template-origin` 설명은 위(`:381-383`)에 있다. `:408`은 "범위를 받으면 범위 끝으로 옮긴다", `:418-419`는 "태그까지 따라잡으면 `.template-origin`을 고친다"다 |
|
||||
| 0929/14-03 | 제품이 고치는 템플릿 파일 목록이 없다 | **일부** | 두 제품의 수정 파일 분류는 이제 빠짐이 없다(1103/14-02 행). 완료 기준의 "README에 표"와 "다음 동기화의 공통 충돌 경로가 모두 표에 있다"는 그대로다. 목록은 CHANGELOG와 매뉴얼 03 C·D절에만 있고, 충돌 경로는 재지 않았다 |
|
||||
| 0929/14-05 | `FEATURE_OVERRIDES` 남은 키를 "조용히 무시"로 적는다 | **고쳐짐** | `docs/operations/ci-quality-gates.md:69`가 "실패하는 검사는 없다"와 경고 두 곳을 적는다(`1c4e57c`). 코드와 같다: `scripts/check-release-admission.ts:131-142`(`release admission warning: … the override does nothing`), `src/bootstrap/runtime-adapters.ts:513`·`src/contracts/diagnostics.ts:21`(`feature.override.unknown`, warn). 작은 잔여: 같은 칸의 "(리뷰 09-09)"에 라운드가 없다. CHANGELOG 밖이라 테스트가 보지 않는다 |
|
||||
| 0929/14-06 | 제품이 찾은 템플릿 결함 후보가 돌아오지 않는다 | **남음** (결정 대기) | 결정 대기로 적혀 있다(`CHANGELOG.md:99`). 첫 후보 하나가 상태와 함께 CHANGELOG에 처음 들어왔다(`:139`, "템플릿은 이것을 재현하지 않았다"). 받는 곳(이슈·FOLLOW-UP)은 정하지 않았다. `docs/manual/reference/errors.md`의 새 잔여 행은 "템플릿에 알린다"고만 적는다 |
|
||||
| 1101/14-07 | 문서 위치가 상태를 드러내지 않는다 | **남음** (결정 대기) | 결정 대기(`CHANGELOG.md:99`). `docs/README.md:35`는 계약 문서의 4.1·6·6.1절만 현재 계약이고 나머지는 목표 설계라고 적는다. §2(`docs/README.md:67-79`)는 그대로 섞여 있다 |
|
||||
|
||||
### 2.1 BREAKING 다섯 — 안내대로 하면 맞는 변경이 되는가 (렌즈 ②)
|
||||
|
||||
새 절 "먼저 할 일" 1~5가 `!` 커밋 다섯과 1:1이다. 각 행은 커밋 꼬리말·코드·[계약] 행·두 다운스트림의 실제 모양 순으로 대조했다(E-4).
|
||||
|
||||
| 단계 · 커밋 | 꼬리말·코드와 CHANGELOG | memento `d3810a0` | tech-log `7a4e201a` | 판정 |
|
||||
|---|---|---|---|---|
|
||||
| 1 `responseEnvelope` 필수 · `56272e8` (1103/16-01) | 꼬리말: 필수 칸, 없으면 `check:types` 실패, 감싸지 않으면 `NONE`·Envelope면 `ENVELOPE_V1`, 런타임 같음. 코드: `src/contracts/external-contract-runtime.ts:239` 필수, 조립은 빠진 값을 `NONE`으로 읽는다(`:715-716`). `CHANGELOG.md:24`, `:59`가 같은 말을 한다. 다른 점: `:24`가 "감싸지 않는 백엔드(memento-web, TechLog)"라고 적는다 | descriptor가 모두 `contract()` 한 함수에서 나온다(`memento-http-contract-contribution.ts:217-267`). 줄 하나(`responseEnvelope: "NONE" as const`)로 끝난다. 동작은 같다 | TechLog의 출력 검증기는 Envelope(`{ success, data, meta }`)를 스스로 벗긴다(`tech-log-studio-contract-contribution.ts:71-78` `envelopeData`). 그래서 `NONE`이 지금 동작을 지키는 값이다. `ENVELOPE_V1`로 적으면 실행기가 한 번 더 벗겨 `envelopeData`가 실패한다. 같은 CHANGELOG의 아래 절은 TechLog를 "Envelope 뼈대만 검사"로 적는다(`:142`) | **맞는 변경이 된다.** 설명 둘이 틀리다(14-01 b). "빠뜨리면 `satisfies`에서 `check:types` 실패"도 두 제품에는 해당하지 않을 것이다. 두 제품은 `as` 단언으로 descriptor 타입을 붙인다(memento `:267`, tech-log `tech-log-management-contract-contribution.ts:106`, `:166`, `tech-log-public-contract-contribution.ts:89`). 빠뜨려도 런타임은 `NONE`이라 피해는 없다(정적 추론, 타입 검사 미실행) |
|
||||
| 2 뮤테이션 operation ID brand · `48c1ab7` (1103/16-05) | 꼬리말: `operationId: "<ID>"`와 `requiresIdempotencyKey`를 `...commandMutationIdentity(<OPERATION>_CONTRACT)`로. 코드: `src/contracts/server-state.ts:276-278` brand, `:294-312`가 `requiresIdempotencyKey = retrySemantics === "KEYED"`를 돌려준다, `:319`. `CHANGELOG.md:25`, `:65`가 같다 | 손으로 적은 정책 8개(`use-memento.ts:150-289`). 8개 모두 손으로 적은 `requiresIdempotencyKey`가 descriptor의 `KEYED` 여부와 같다(`memento-http-contract-contribution.ts:371`, `:429`, `:525`, `:567`, `:608`은 KEYED·true, `UPDATE_MEMORY`·`UPDATE_ALBUM`은 기본 NEVER·false, `:511`은 IDEMPOTENT·false) | 정책을 만드는 함수가 operation ID를 문자열 인자로 받는다(`studio-asset-server-state.ts:139-170`, `studio-management-server-state.ts:193-226`). 그 함수가 descriptor를 받게 바꾸면 된다. 관리(management) 정책은 `requiresIdempotencyKey: true`를 손으로 적고(`:209`), 키가 없으면 던진다(`:216-218`). 그런데 관리 쓰기 descriptor는 모두 `NEVER`다(`tech-log-management-contract-contribution.ts:143`). 2단계대로 하면 값이 `false`가 되고, 자기 가드가 저장마다 `TypeError`를 던진다. `check:types`는 통과한다 | **memento: 맞는 변경, 동작 같음.** **tech-log: 템플릿 계약에는 맞는 변경이다.** 지금도 그 경로는 `NEVER` descriptor에 키를 실어 보내고(`http-management-gateway.ts:63`), 실행기는 그것을 `UNEXPECTED_IDEMPOTENCY_KEY`로 거절한다(`src/adapters/http/http-execution-v3.ts:508-512`, tech-log 사본 `:429`, 정적 추론). 그래서 동기화가 새로 깨는 것은 아니다. 다만 안내가 값이 다시 계산된다는 말을 하지 않는다(14-01 c) |
|
||||
| 3 `refusedBeforeWrite` 플랫폼 code · `5c0b37e` (1105/03-01) | 꼬리말: `PLATFORM_CODES_POSSIBLY_AFTER_WRITE`를 적으면 조립이 거절, 목록에서 지운다, 결과 불명으로 남는다. 코드: 목록 `external-contract-runtime.ts:638-660`(`BAD_PARAMETER`, `MAPPING_FAILED`, `DB_*` 8, `LOCK_ACQUISITION_TIMEOUT`, fileserver 9), 거절 `:691-695`, 실행기도 무시(`src/adapters/http/backend-envelope.ts:336`). 계약 문서 6.1 표와 같다(`backend-api-and-server-state-contract.md:319-325`). `CHANGELOG.md:26`, `:60`이 같다. 다른 점: `:26`이 "계약 조립이 거절해 부팅이 멈춘다"고 적는다 | `refusedBeforeWrite`는 `ENVELOPE_V1` operation에만 쓴다(`external-contract-runtime.ts:676-679`). memento는 `responseEnvelope`가 없다. `git grep refusedBeforeWrite` 0건. 할 일 없음 | 같다. 0건. 할 일 없음 | **맞는 변경이 된다.** 증상 설명이 틀리다(14-01 a). 브라우저는 부팅 때 빈 목록만 조립한다(`src/features/installed-contract-contributions.ts:94`). 기능 기여는 그 기능 실행부를 적재할 때 조립한다(`:96-111`, `src/features/installed-feature-adapters.ts:80`, `src/bootstrap/runtime-adapters.ts:735-739`). 그래서 앱은 뜨고, 그 기능 라우트에 처음 들어갈 때(또는 플랫폼 구성 화면, `platform-overview-page.tsx:680`) 실패한다. CI에서는 `loaded-feature-runtimes.ts`를 읽는 `test:unit`과 `check:registries`가 먼저 잡는다 |
|
||||
| 4 던지는 poll `execute` · `05330e3`, `27e3dec` (1105/04-02, 1103/04-01) | 꼬리말: 던지면(abort 제외) 재시도 없이 `PROTOCOL_MISMATCH`(retryable 아님), 네트워크 실패는 retryable `PROVIDER_UNAVAILABLE` 결과로. 코드: `bounded-poll-coordinator.ts:104-129`(결과로 돌려준다는 규칙과 `input.operation`), `:338-346`(던짐 → `null`), `:395-398`(`PROTOCOL_MISMATCH`). 결과 생성 함수 `realtimeFailure`는 배럴에 있다(`src/adapters/realtime/index.ts:38`). `CHANGELOG.md:27`, `:67`이 같다. 아래 절의 옛 행도 `1e576ef`이 고쳤다(`:298`, "위 절에서 다시 바뀌어") | `createBoundedPollCoordinator`는 템플릿 사본(`src/adapters/realtime/polling/`)과 템플릿 테스트에만 있다. 할 일 없음 | 같다. 할 일 없음 | **맞는 변경이 된다** |
|
||||
| 5 `a11y.json` schemaVersion 2 · `757d1c7` (1103/11-01) | 꼬리말: `scope`는 실패 화면으로만 본 라우트를 빼고, 그 라우트는 `notChecked`에 `{ routeId, reason }`. 코드: `scripts/contracts/release-artifacts.ts`(같은 커밋에서 바꿈, `:836` 근처). `CHANGELOG.md:28`, `:53`이 같다 | `a11y.json`을 읽는 것은 템플릿 파일(`scripts/write-a11y-report.ts`, `config/ci/gates.json`)뿐이다. 템플릿 것을 받으면 끝 | 같다 | **맞는 변경이 된다** |
|
||||
|
||||
정리: 다섯 단계 모두 행동은 맞다. 틀린 것은 설명 셋이다(14-01). "먼저 할 일" 6~10은 `!` 커밋이 아닌 수정에서 왔다. 행에는 **BREAKING** 표시가 없지만 단계 목록에는 있다. 안내가 실제로 쓰이는 곳은 단계 목록이라 문제로 보지 않았다. 표시 없이 생긴 필수 칸이 하나 있다. `ProductCompositionContext.notifySessionUnauthenticated()`(`src/bootstrap/product-composition-contract.ts:100`, `0007699`)다. context를 직접 만드는 제품 코드(테스트·fake)만 타입 검사에서 걸린다. 두 다운스트림과 템플릿 테스트 모두 그런 곳이 없다. 기록만 한다.
|
||||
|
||||
### 2.2 새 절의 해시 (렌즈 ①)
|
||||
|
||||
- 새 절(`CHANGELOG.md:14-108`)의 백틱 해시는 76개다. 기준점 `409d72e`를 빼면 75개다(E-1).
|
||||
- 75개 모두 `bbde570`에서 닿고, `409d72e`에서는 닿지 않는다.
|
||||
- PR A로 적은 셋(`9655958`, `629c713`, `397664e`, `:16`)은 `a793b83` 이력에 있다.
|
||||
- 각 커밋의 `Refs:` 꼬리말이 그 행의 리뷰 ID와 같다(75/75, E-2). 해시를 여러 번 다시 쓴 통합에서도 CHANGELOG는 마지막 해시로 맞춰졌다.
|
||||
- `409d72e..bbde570` 비병합 79커밋 중 인용되지 않은 것은 넷이다. 리뷰 기록(`e85c836`, `bbde570`)과 CHANGELOG 커밋(`a793b83`, `1c884e1`)이다.
|
||||
- `!` 커밋 다섯(`5c0b37e`, `56272e8`, `757d1c7`, `48c1ab7`, `05330e3`)이 **BREAKING** 행 다섯이고, 모두 `BREAKING CHANGE:` 꼬리말이 있다.
|
||||
- 범위 커밋 본문의 해시도 봤다(E-3). `287dc6f`(D7) 본문만 이 이력에 없는 해시 둘을 가리킨다(14-02).
|
||||
- CHANGELOG는 `verify:documentation` 밖이다(`scripts/verify-documentation-readiness.ts:165`, `docs/README.md:50-51`). 해시·경로는 사람이 대조한다. 새 절의 repo 경로는 생성 산출물(`artifacts/tests/a11y.json`)과 백엔드 문서(`docs/fileserver/http-contract.md`, `:101`, 백엔드 pin에 있음)를 빼면 모두 있다(E-6).
|
||||
|
||||
### 2.3 D7 문서 (렌즈 ⑤)
|
||||
|
||||
| 항목 | README §16.2 D7 | `CHANGELOG.md:56` | `docs/operations/performance-evidence.md:44-53` | 판정 |
|
||||
|---|---|---|---|---|
|
||||
| 값 | 204,800 → 206,848 B(`287dc6f`) | 같다 | 같다(`:6` 머리도 202 KiB) | 맞다. `config/performance/budgets.json:4` |
|
||||
| 이유 | 합친 빌드 204,111 B·27개(PR A 202,927 B·26개). 드릴이 기능 둘을 더해 205,463 B, 663 B 초과. 늘어난 곳 1,184 B(03-01 +327, 08-03 +293·파일 +1, 02-01 +251, 합칠 때 +148, 나머지 +165) | 1,184 B, 드릴(FE-GATE-020) 초과, 기록 204,111 B·27개 | 1,184 B, 663 B 초과, 03-01·08-03·02-01, 기록 커밋 `0fee3fe` | 맞다. 작은 차이: 두 문서 모두 08-03(홈 시작 링크의 `navigation-policy` 공유 청크)을 "검사·진단 코드"에 넣는다. §16.2는 따로 센다. performance-evidence는 파일 +1을 적지 않는다 |
|
||||
| 버린 대안 | 줄이기. 라운드 중간 설계 변경이라 다음 라운드 숫자를 흐린다. 청크를 합치는 것만으로는 663 B를 못 채운다 | 없음 | 런타임 검사를 빌드 시점으로 옮겨 줄이기. 같은 이유 | 맞다 |
|
||||
| 재검토 조건 | 예산을 다시 넘을 때, 1103/13-03을 정할 때. 그때 03-01·02-01 검사를 빌드 시점으로 옮기는 것부터. 13-03을 정하지 않는다 | performance-evidence를 가리킨다 | 같은 세 문장 | 맞다 |
|
||||
| 결정자 | 메인 세션, 2026-11-06 | 없음 | 없음. README 16절을 가리킨다 | 작다. `docs/reviews/`를 지운 사본에서는 결정자가 안 보인다 |
|
||||
| 같은 문서의 다른 숫자 | 초기 파일 26 → 27 | 27 | `:209-210` "템플릿 그대로의 수(26)에 6을 더한 32" | **틀리다.** 지금 27이고 여유는 5다. 1103/15-02 문서 부분이라 15 영역에 넘긴다 |
|
||||
| 문서 자기 규칙 | — | — | `:90` "예산을 올릴 때는 이 표의 기준선과 새 측정값, 이유를 같은 변경에 적는다". 표(`:58-70`)는 2026-11-01(`298201f`) 그대로 | 이유는 적었다. 출처별 표는 다시 재지 않았다. 작다 |
|
||||
|
||||
판정: CHANGELOG 행은 이유를 적고 재검토 조건은 performance-evidence를 가리킨다. performance-evidence는 이유·버린 대안·재검토 조건을 §16.2와 같게 적는다. **충족**, 작은 잔여 셋(08-03 분류, 결정자, 출처별 표). `:209-210`의 26은 15 영역 판정으로 넘긴다.
|
||||
|
||||
### 2.4 `verify:documentation` 출력
|
||||
|
||||
- 옆에 백엔드 checkout이 있는 실행: `Documentation readiness: PASS_SCOPED`. `not verified` 줄이 없다(`desktop:/tmp/claude-gates/r5/snap/verify-documentation.local.txt`).
|
||||
- 옆 checkout이 없는 실행: 짝 백엔드 참조 17개(경로 14개) `not verified` 뒤 `PASS_SCOPED`(`verify-documentation.no-sibling.txt`).
|
||||
- 지난 라운드는 로컬 실행이 rc=1이었다. 그때 백엔드 checkout이 pin이 아닌 `ef947e5`였다. 이제 검사기가 pin 커밋의 트리를 읽는다(`fc95672`, `CHANGELOG.md:50`). 그래서 checkout HEAD와 상관없이 같은 결과가 나온다. 이 부분 판정은 12 영역이다.
|
||||
|
||||
## 3. 이번 발견 (36.3)
|
||||
|
||||
수: Critical 0 · High 0 · Medium 0 · Low 2. P1 0 · P2 1 · P3 1. 확인된 결함 2.
|
||||
|
||||
### 14-01 새 미출시 절 BREAKING 1~3단계의 설명 셋이 코드·다운스트림 모양과 다르다 — 행동은 맞지만, 증상·대상·바뀌는 값을 틀리게 또는 빼고 적는다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 17, 23, 24, 20, 30.4 |
|
||||
| 근거 | **(a) 3단계 증상.** `CHANGELOG.md:26`은 플랫폼 code를 `refusedBeforeWrite`에 적으면 "계약 조립이 거절해 부팅이 멈춘다"고 적는다. 브라우저는 부팅 때 빈 기여 목록만 조립한다(`src/features/installed-contract-contributions.ts:93-94`). 기능의 계약 기여는 그 기능 실행부를 적재할 때 `install`이 조립한다(`:96-111`, `src/features/installed-feature-adapters.ts:80`, `src/bootstrap/runtime-adapters.ts:735-739`). 같은 CHANGELOG의 아래 절도 "계약 기여는 기능 실행부를 적재할 때 설치되고"라고 적는다(`:180`). 그래서 앱은 뜨고, 그 기능 라우트에 처음 들어갈 때와 플랫폼 구성 화면(`src/presentation/examples/platform-overview-page.tsx:680`)에서 실패한다. 6단계(`:29`)의 "조립이 `TypeError`로 멈춘다"는 부팅 조립(`runtime-adapters.ts:716-718`)이라 맞다. **(b) 1단계 대상.** `:24`는 "감싸지 않는 백엔드(memento-web, TechLog)는 `NONE`"이라고 적는다. TechLog의 출력 검증기는 `{ success: true, data, meta }`를 검사하고 `data`를 꺼낸다(tech-log `tech-log-studio-contract-contribution.ts:71-78`). 백엔드가 Envelope로 감싼다는 뜻이다. 아래 절은 TechLog를 "출력은 Envelope 뼈대만 검사"로 적는다(`:142`). 두 절이 같은 제품을 다르게 적는다. 같은 단계의 "빠뜨리면 그 descriptor의 `satisfies InstalledHttpContract<...>`에서 `check:types`가 실패한다"는 템플릿·생성 기능에는 맞다. 두 제품은 `as` 단언으로 descriptor 타입을 붙인다(memento `memento-http-contract-contribution.ts:267`, tech-log `tech-log-management-contract-contribution.ts:106`, `:166`). **(c) 2단계의 바뀌는 값.** `:25`는 `operationId`와 `requiresIdempotencyKey`를 `...commandMutationIdentity(<descriptor>)`로 바꾸라고 한다. 이 함수는 `requiresIdempotencyKey`를 `retrySemantics === "KEYED"`로 다시 계산한다(`src/contracts/server-state.ts:303-311`). 손으로 적은 값이 descriptor와 다른 정책은 값이 바뀐다. 안내는 그 말을 하지 않는다. 실제 사례: tech-log 관리 정책은 `true`를 적고(`studio-management-server-state.ts:209`) 키가 없으면 던진다(`:216-218`). 관리 쓰기 descriptor는 `NEVER`다(`tech-log-management-contract-contribution.ts:143`). 안내대로 하면 `false`가 되고, `check:types`는 통과하고, 저장마다 자기 가드가 던진다. memento 8개는 값이 같아 바뀌지 않는다(2.1절) |
|
||||
| 발생 조건 | 두 제품이 다음 동기화에서 새 절 "먼저 할 일"을 읽을 때. (a)는 운영자가 증상으로 원인을 찾을 때, (b)는 TechLog 담당이 `ENVELOPE_V1`이 맞는지 판단할 때, (c)는 tech-log가 관리 뮤테이션을 옮길 때 |
|
||||
| 영향 | 행동은 모두 맞아서 데이터 피해는 없다. (a) "부팅이 멈춘다"를 기대한 사람은 앱이 뜨는 것을 보고 다른 원인을 찾는다. CI에서는 `test:unit`·`check:registries`가 먼저 잡는다. (b) TechLog 백엔드가 Envelope인 것을 아는 사람이 "Envelope면 `ENVELOPE_V1`"을 따르면, 실행기가 한 번 벗긴 `data`를 TechLog 검증기가 다시 벗기려다 모든 응답이 실패한다. (c) tech-log 관리 쓰기는 지금도 실행기가 `UNEXPECTED_IDEMPOTENCY_KEY`로 거절하는 모양이다(`http-management-gateway.ts:63`, `src/adapters/http/http-execution-v3.ts:508-512`, 정적 추론). 그래서 동기화가 새로 깨는 것은 아니지만, 실패 이유가 실행기 위반에서 제품 `TypeError`로 바뀌고 안내는 그 이유를 주지 않는다 |
|
||||
| 심각도·우선순위 | Low · P2 — 지난 라운드 1105/14-02(매뉴얼 예시 한 줄이 게이트를 깸)와 같은 기준이다. 문서 몇 줄의 어긋남이고 동작 피해는 없다. 다만 두 제품이 다음 동기화에서 그대로 읽는 문단이라 P2다 |
|
||||
| 통제·증거 | 목표 M2(BREAKING 안내의 증상·대상 설명이 코드와 다운스트림 실제 모양과 같다). 확인: M1(사람이 쓰고 사람이 읽는다. CHANGELOG는 문서 검사 밖, `scripts/verify-documentation-readiness.ts:165`) · E1(코드·두 다운스트림 정적 대조). `as` 단언이 누락을 잡지 않는다는 것과 tech-log 관리 경로의 실제 거절은 실행하지 않은 추론이다 |
|
||||
| 확실성과 남은 가정 | (a)·(b)의 코드 사실과 (c)의 값 변화는 코드로 확인했다. tech-log 관리 쓰기가 지금 실행기에서 거절된다는 것은 코드 경로를 읽은 추론이다. 제품 쪽 다른 우회가 있는지는 실행하지 않았다 |
|
||||
| 결정의 근거 | 적용 제외 — 문서를 코드에 맞추는 일이다 |
|
||||
| 이해 비용 | 제품 개발자가 증상(앱이 뜸)과 안내(부팅이 멈춤)가 다를 때 계약 조립 시점을 코드에서 찾아야 한다. tech-log 담당은 `commandMutationIdentity` 본문을 읽어야 값이 바뀌는 것을 안다 |
|
||||
| 최소 개선 방향 | ① `:26`을 "그 기능 실행부를 적재할 때 조립이 거절한다. 라우트에 처음 들어갈 때 실패하고, CI에서는 `test:unit`과 `check:registries`가 잡는다"로 고친다. ② `:24`의 괄호를 "memento-web, 그리고 Envelope를 검증기에서 직접 벗기는 TechLog는 `NONE`"으로 고친다. ③ `:25` 끝에 "`requiresIdempotencyKey`는 descriptor의 `retrySemantics`가 `KEYED`일 때만 `true`다. 손으로 적은 값과 다르면 동작이 바뀐다(tech-log 관리 쓰기는 `NEVER`)"를 붙인다 |
|
||||
| 대안 비교 | 적용 제외 — 문장 정정이다 |
|
||||
| 단순화의 보존 조건 | 적용 제외 |
|
||||
| 비용·부작용 | 문장 세 곳 |
|
||||
| 재검토 조건 | 적용 제외 |
|
||||
| 완료 기준 | 세 문장이 코드와 같다. 같은 CHANGELOG 두 절이 TechLog 백엔드를 같은 모양으로 적는다 |
|
||||
| 검증 방법 | 문서 대조. (c)는 tech-log sync 브랜치에서 2단계 뒤 관리 저장 한 번 |
|
||||
| 담당·기한·상태 | 미정 · 다음 동기화 전 · 신규 |
|
||||
| 재검증 결과 | 미실시 |
|
||||
|
||||
### 14-02 D7 커밋 `287dc6f` 본문이 다시 쓰기 전 해시 둘을 가리킨다 — 통합에서 해시를 여러 번 다시 썼는데, CHANGELOG·커밋 본문의 해시를 대조하는 장치가 없다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 9, 24, 21, 30.4 |
|
||||
| 근거 | `git show 287dc6f` 본문의 "늘어난 곳"이 1105/03-01을 `ab0d4a1`, 1105/08-03을 `7ce9bf1`로 적는다. 두 객체는 이 노트북 저장소에 남아 있고 제목도 맞다. 오케스트레이터 설명대로 03-01·08-03을 마지막으로 다시 짓기 전의 해시다. 그러나 `bbde570`에서 닿지 않는다(`git merge-base --is-ancestor` 실패). 두 객체를 담은 것은 올리지 않은 로컬 브랜치뿐이다(`fix/r1105-docs`, `-sq2`, `-sq3`, `-v2`, `fix/r1105-http-forms-sq`). `git branch -r --contains`는 둘 다 0개다. `287dc6f` 자신은 `origin/fix/maturity-review-2026-11-05-b`에 있다. 그래서 원격에서 받은 clone에서는 두 해시를 열 수 없다. `bbde570` 이력의 같은 변경은 `5c0b37e`, `f849d78`이다. README §16.2와 `CHANGELOG.md:56`, `performance-evidence.md:48`은 올바른 해시를 쓴다. `409d72e..bbde570` 커밋 본문 전체에서 이 이력에 없는 이 repo 해시는 이 둘뿐이다(E-3. 나머지 두 개는 다른 repo의 `d3810a0`, `ef947e5`). CHANGELOG는 문서 검사 밖이다(`scripts/verify-documentation-readiness.ts:165`). 해시 대조는 리뷰가 손으로 한다. 이번 CHANGELOG는 75/75 맞았다(2.2절) |
|
||||
| 발생 조건 | 다운스트림이나 다음 리뷰가 D7의 근거를 `git show 287dc6f`로 따라갈 때. 새 clone에는 두 객체가 없다 |
|
||||
| 영향 | 근거 사슬 한 칸이 끊긴다. README §16.2에 같은 내용과 맞는 해시가 있어 피해는 작다. 이력은 이미 올라가 고칠 수 없다 |
|
||||
| 심각도·우선순위 | Low · P3 — 문서 한 칸의 어긋남이고 대체 기록이 있다 |
|
||||
| 통제·증거 | 목표 M3(통합 끝에 범위 안 CHANGELOG·커밋 본문 해시를 범위와 대조한다). 확인: M0(장치 없음) · E1(`git rev-parse`, `git merge-base`, `git branch -a/-r --contains`) |
|
||||
| 확실성과 남은 가정 | 직접 확인했다. 원격 브랜치 목록은 이 노트북이 마지막으로 받은 것이다. 로컬 `fix/r1105-*` 브랜치를 나중에 올리면 두 해시는 열린다. 그래도 PR B 이력에서 닿지 않는 것은 그대로다. PR B가 원격에서 다시 쓰이면 CHANGELOG 해시 75개도 다시 대조해야 한다 |
|
||||
| 결정의 근거 | 기록된 사실: §16.3이 브랜치 안 결함을 fixup으로 접었다고 적는다. 그때 해시가 바뀌었다. 오케스트레이터 설명: 이 본문은 마지막으로 다시 짓기 전에 썼다. 리뷰어 판단: 원인이 설명대로라도 결함은 남는다. 본문이 가리키는 커밋을 PR B 이력에서 찾을 수 없다 |
|
||||
| 이해 비용 | 근거를 따라가는 사람이 없는 해시를 만나 README §16을 따로 찾는다 |
|
||||
| 최소 개선 방향 | 이력은 고치지 않는다. 통합 절차(지금은 리뷰 README §16.1)에 "해시를 다시 쓴 뒤 범위 커밋 본문·CHANGELOG 새 절·README §16의 해시를 `git merge-base --is-ancestor`로 대조한다"는 한 단계를 둔다. 명령 한 줄이다 |
|
||||
| 대안 비교 | (a) 현 상태: 리뷰가 매번 손으로 센다. (b) 절차 한 단계: 싸다. 사람이 빼먹을 수 있다. (c) CHANGELOG 해시 테스트: 미출시 절 머리의 범위로 대조한다. 그러나 복사한 프로젝트에는 템플릿 이력이 없어 그쪽에서는 건너뛰어야 한다. (b) 권장, (c)는 해시 어긋남이 다시 나오면 |
|
||||
| 단순화의 보존 조건 | 적용 제외 |
|
||||
| 비용·부작용 | (b) 문서 한 줄. (c) 테스트 수십 줄과 이력 없는 사본의 건너뛰기 규칙 |
|
||||
| 재검토 조건 | 통합에서 fixup·rebase를 하지 않게 되면 이 위험은 줄어든다 |
|
||||
| 완료 기준 | 다음 통합 기록에 그 대조 결과가 있다 |
|
||||
| 검증 방법 | 범위 커밋 본문의 7~12자리 해시마다 `git merge-base --is-ancestor <hash> <end>` |
|
||||
| 담당·기한·상태 | 미정 · 다음 통합 · 신규 |
|
||||
| 재검증 결과 | 미실시 |
|
||||
|
||||
## 4. 28개 관점 판정 (36.2)
|
||||
|
||||
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역.
|
||||
|
||||
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | 코드 성숙도 | > 01~13 영역 | - | - | 이 영역은 문서·문서 검사·드릴 스크립트만 본다 |
|
||||
| 2 | 구조적 성숙도 | > 09·12 영역 | M3 / M3 | E2 | 입구 문서의 폴더·규칙 설명은 지난 라운드처럼 검사된다. FE-GATE-005 통과 |
|
||||
| 3 | 변경 용이성 | 적용 | M2 / M2 | E1 | P — 두 제품이 고친 템플릿 `src` 파일 26/40개가 모두 "자리 있음·없음·결함 후보"로 나뉘었다(1103/14-02 잔여 (a) 고쳐짐). 자리 없는 것을 들일지는 결정 대기다 |
|
||||
| 4 | 인지 부하 | 적용 | M1 / M1 | E1 | P — `docs/` 212개 98,440줄. CHANGELOG 455줄에 미출시 절이 둘이다. 제품은 아래 절 단계를 먼저 하고 위 절을 한다(`:20`). 두 절이 같은 제품 모양을 다르게 적는 곳이 있다(14-01 b) |
|
||||
| 5 | 위험 가시성 | 적용 | M2 / M2 | E1 | P — 알려진 제한 18줄은 각 항목의 상태(결정 대기·백엔드로 넘김·일부)를 적고, 다운스트림에 적용해 보지 않았다는 것도 적는다(`:91`). 3단계 증상 설명은 틀리다(14-01 a) |
|
||||
| 6 | 실패 성숙도 | > 다른 영역 | - | - | - |
|
||||
| 7 | 운영 성숙도 | > 11·13 영역 | - | - | - |
|
||||
| 8 | 디버깅 가능성 | 적용 | M3 / M3 | E2 | O — 문서 검사가 지운 기능을 출력에 적는다(`verify-documentation-readiness.ts:513-518`, `FE-GATE-020.txt:1539`). 매뉴얼 errors.md의 새 오류 문구 5개가 코드에 있다(E-7) |
|
||||
| 9 | 유지보수 성숙도 | **깊게 봄** | M3 / M2 | E1·E2 | P — 지난 라운드의 "브랜치끼리 문서에서 못 만남"(1105/14-01·14-03)을 목록 모듈 하나로 함께 풀었다. 남은 것: D7 커밋 본문 해시(14-02), performance-evidence의 손으로 적은 26(15 영역), 매뉴얼 04 테스트의 규칙 사본(작음) |
|
||||
| 10 | 테스트 성숙도 | 적용 | M3 / M3(문서), M0(예제 드릴의 회귀) | E2(FE-GATE-005), E3(14-R1~R4) | P — 문서 테스트 셋이 새로 생겼고 FE-GATE-005에서 돈다. 변이 셋(14-R2·R3·R4)에서 모두 기대한 이유로 실패해, 빈 통과가 아님을 확인했다. 예제 기능 제거 드릴은 이번에 통과했지만(14-R1) 게이트 밖이다(`CHANGELOG.md:93`). 다음에 깨지면 문서 쪽 unit 테스트만 알린다 |
|
||||
| 11 | 데이터 성숙도 | - 이 영역에 데이터 경계가 없다 | - | - | - |
|
||||
| 12 | 동시성 성숙도 | - 이 영역에 동시 실행 경로가 없다 | - | - | - |
|
||||
| 13 | 확장성 | > 11·15 영역 | - | - | - |
|
||||
| 14 | 성능 성숙도 | > 15 영역 | - | - | D7 기록만 봤다(2.3절) |
|
||||
| 15 | 보안 성숙도 | > 09 영역 | - | E1 | 매뉴얼 04 4.3의 쿠키 401 연결(`createSessionCookieRejectionHandler`)은 recipe 코드와 같다(`recipes/session-owners/cookie-session-owner.ts:217-222`) |
|
||||
| 16 | 의존성 성숙도 | 적용(제품에게 템플릿은 의존성) | M2 / M1 | E1 | P — 태그 `v0.2.0` 뒤 두 미출시 절이 태그 없이 쌓였다. 기준점 형식이 둘이다(0929/14-02) |
|
||||
| 17 | API / Contract 성숙도 | **깊게 봄** | M3 / M2 | E1 | P — 해시 75/75, BREAKING 행 5/5가 꼬리말·코드와 같다. 다섯 단계를 따라 하면 두 제품 모두 맞는 변경이 된다(2.1절). 설명 셋이 틀리다(14-01). 표시 없이 생긴 필수 칸 `notifySessionUnauthenticated`는 영향 받는 곳이 지금 없다 |
|
||||
| 18 | 배포 성숙도 | > 13 영역 | - | - | - |
|
||||
| 19 | 설정 성숙도 | 적용 | M3 / M3 | E2 | O — 매뉴얼 04 §3.2 예시를 테스트가 그대로 타입 검사한다(1105/14-02). `FEATURE_OVERRIDES` 문서가 코드와 같다(0929/14-05) |
|
||||
| 20 | 개발자 경험 | **깊게 봄** | M3 / M3 | E1·E2 | P — 매뉴얼 diff의 명령·경로는 문서 검사를 지나고(FE-GATE-005), 새 오류 문구는 코드에 있다. 매뉴얼만 보는 재실험(X2)은 이번에도 미실시 |
|
||||
| 21 | Guardrail 성숙도 | 적용 | M3 / M3(§1 문서), M0(CHANGELOG) | E2·E3 | P — 참조 기능 경로가 다시 검사된다. 파일 이름을 바꾸면 매뉴얼 두 줄로 실패한다(1105/14-03, 14-R3). 지운 기능의 예외는 조건부이고 양쪽 방향을 테스트하며, 예외를 끄면 그 테스트가 실패한다(14-R2). CHANGELOG는 일부러 문서 검사 밖이고(`verify-documentation-readiness.ts:165`), 해시를 대조하는 장치가 없다(14-02). 검사 약화는 찾지 못했다(0절) |
|
||||
| 22 | 추상화 성숙도 | > 09 영역 | - | - | - |
|
||||
| 23 | 일관성 | 적용 | M1 / M1 | E1 | P — 두 미출시 절이 TechLog 백엔드 모양을 다르게 적는다(14-01 b). README 기준점을 옮기는 시점이 두 문장이다(0929/14-02) |
|
||||
| 24 | 네이밍 / 의미 성숙도 | 적용 | M1 / M1 | E1 | P — "부팅이 멈춘다"(14-01 a). 커밋 본문의 옛 해시(14-02). 매뉴얼 04 머리의 "백엔드 `bbe944bd` 기준"(`04-paired-backend-session.md:10`)이 pin `45d2a478`과 다르다. 지난 라운드에 두 커밋 사이 인증 설정 변경이 0줄임을 확인했다. 그대로다 |
|
||||
| 25 | 조직 확장성 | 적용 | M2 / M1 | E1 | P — 다운스트림 모양을 템플릿 리뷰가 직접 읽어 안내를 맞춘다. 다운스트림 모양 fixture로 안내를 검증하는 장치는 없다(1103/14-02 대안 (B) 미실시) |
|
||||
| 26 | Ownership 성숙도 | **깊게 봄** | M1 / M1 | E1 | P — 다운스트림 결함 후보 하나가 상태와 함께 처음 기록됐다(`CHANGELOG.md:139`). 받는 곳은 결정 대기다(0929/14-06) |
|
||||
| 27 | 삭제 가능성 | **깊게 봄** | M3 / M3(참조), M3(예제 문서)·M0(예제 드릴 회귀) | E2(FE-GATE-020·005), E3(14-R1) | P — 참조 기능 삭제는 드릴과 문서 검사를 함께 통과한다(FE-GATE-020). 예제 기능 삭제도 이번에 드릴 17검사를 통과했다(14-R1). 예제 기능을 지운 사본의 문서 검사는 FE-GATE-005가 매번 보지만, 드릴 자체는 어느 게이트에도 없다. 읽는 곳 없는 추적 산출물 13개(0929/14-01) |
|
||||
| 28 | 회복 가능성 | > 다른 영역 | - | - | 동기화 되돌림(`git revert`, `README.md:419`)은 실행하지 않았다 |
|
||||
|
||||
### 4.1 30절 템플릿 기준
|
||||
|
||||
| 절 | 판정 | 근거 |
|
||||
|---|---|---|
|
||||
| 30.1 최소 구성과 안전한 기본값 | P | 지난 라운드와 같다. 깨끗한 환경 실행은 확인하지 못했다 |
|
||||
| 30.2 옵션 조합의 수와 검증 책임 | P | 지울 수 있는 템플릿 기능 둘을 한 목록이 관리한다(`removable-template-features.ts`). 두 드릴 모두 이 커밋에서 통과했다(FE-GATE-020, 14-R1). 게이트에서 도는 것은 참조 기능 하나다 |
|
||||
| 30.3 생성·복사 후 수정 권한 | P | 예제를 지운 제품도 템플릿 문서를 고치지 않아도 된다(1105/14-01). 제품 소유 자리가 없는 템플릿 수정은 결정 대기다(1103/14-02) |
|
||||
| 30.4 버전과 업데이트 전파 | P | 새 절의 해시·BREAKING 행이 범위와 맞다. 남은 것: 설명 셋(14-01), 커밋 본문 해시(14-02), 다운스트림 적용 실험 없음, 기준점 형식 둘 |
|
||||
| 30.5 샘플 코드의 대표성 | O | 매뉴얼이 가리키는 참조 기능 경로가 다시 검사된다(1105/14-03) |
|
||||
| 30.6 도입·유지 비용 | P | 문서 212개 98,440줄. 미출시 절 둘을 함께 받는다. FE-GATE-020 한 번 1,237초(`bbde570-ci/summary.txt`) |
|
||||
| 30.7 템플릿에서 졸업할 수 있는가 | P | 지난 라운드와 같다. 제품 자리가 없는 실행기 수정(memento `if-match`)이 제품을 템플릿 파일에 묶는다 |
|
||||
| 30.8 배포 판단에 필요한 최소 증거 | P | "패치 전달": 안내와 두 제품 실제 모양 대조 E1, 적용 실험 없음. "선택 기능 분리": 참조 기능 E2(FE-GATE-020), 예제 기능 E3(14-R1 드릴, 14-R2 변이) |
|
||||
|
||||
## 5. 미검증
|
||||
|
||||
| 항목 | 이유 | 확인하려면 |
|
||||
|---|---|---|
|
||||
| 두 다운스트림의 실제 병합 뒤 게이트 | 제품 repo는 읽기만 했다 | 제품 sync 브랜치에서 두 절을 받고 CHANGELOG만 보고 `check:types`·`check:registries`·`test:unit`까지 |
|
||||
| tech-log 관리 쓰기가 지금 실행기에서 거절되는지 | 코드 경로를 읽은 추론이다(14-01 c) | tech-log에서 관리 저장 한 번, 또는 `http-management-gateway` 단위 테스트 |
|
||||
| 두 제품의 `as` 단언이 `responseEnvelope` 누락을 잡는지 | 타입 검사를 돌리지 않았다 | 제품 사본에서 그 줄 없이 `check:types:app` |
|
||||
| 예제 기능 제거 드릴의 CI env 실행 | 14-R1은 local env다. 어느 게이트도 이 드릴을 돌리지 않는다 | `CI=true`와 workflow env로 같은 명령 1회, 또는 FE-GATE-020에 더하기 |
|
||||
| 매뉴얼만 보는 기능 추가(X2) | 지난 두 라운드도 하지 않았다 | 깨끗한 clone에서 매뉴얼만 보는 에이전트 1회 |
|
||||
| 04 §3.3·§4.3 코드 예시 컴파일 | §3.2만 테스트가 본다 | recipe를 `src/bootstrap/`에 복사하고 예시를 붙여 `check:types:app` |
|
||||
| 깨끗한 환경 `install --frozen-lockfile` → `dev` | 공유 `node_modules` | 새 clone이나 컨테이너에서 README 명령만 |
|
||||
| README 범위 동기화 두 명령(`README.md:402-403`) | 실행하지 않았다(커밋 본문도 같다) | scratch clone 두 개(이력 공유·비공유)에서 다음 범위를 받아 봄 |
|
||||
| 목표 설계 문서 본문 전체 | 약 3만 줄. 상태 줄과 검색 결과만 봤다 | `git grep -i -E 'v2|replay|mapper registry'` 후보를 코드와 대조 |
|
||||
|
||||
## 6. 실행 기록
|
||||
|
||||
정적 확인(노트북, 읽기만):
|
||||
|
||||
| ID | 무엇을 | 어떻게 | 결과 |
|
||||
|---|---|---|---|
|
||||
| E-1 | 새 절 해시 위치 | `CHANGELOG.md:14-108`의 백틱 해시 76개를 `git rev-parse`, `git merge-base --is-ancestor`로 `bbde570`·`409d72e`·`a793b83`와 대조 | 75개 모두 `bbde570`에서 닿고 `409d72e`에서 안 닿는다. 남은 하나는 기준점 `409d72e`. PR A 셋은 `a793b83` 이력에 있다 |
|
||||
| E-2 | 범위 커밋과 행 | `git log --no-merges 409d72e..bbde570`(79개)와 인용 해시 비교. 커밋마다 `Refs:`·`BREAKING CHANGE:` 꼬리말을 행의 ID와 대조 | 인용 75, 안 된 4(리뷰 기록·CHANGELOG 커밋). Refs 75/75 일치. `!` 커밋 5 = BREAKING 행 5, 모두 꼬리말 있음 |
|
||||
| E-3 | 범위 커밋 본문의 해시 | 79+14커밋 본문에서 7~12자리 16진 토큰을 뽑아 이 repo 객체인지, `bbde570`에서 닿는지 | `287dc6f`의 `ab0d4a1`, `7ce9bf1`만 이 이력에 없다(14-02). `d3810a0`·`ef947e5`는 다른 repo |
|
||||
| E-4 | BREAKING 다섯과 두 다운스트림 | 다섯 커밋의 diff·꼬리말, 위 코드 위치, 두 repo `HEAD`의 `refusedBeforeWrite`·`operationId: "`·`createBoundedPollCoordinator`·`a11y.json`·descriptor 생성 함수를 `git grep`·`git show` | 2.1절 표 |
|
||||
| E-5 | 두 제품이 고친 템플릿 파일 | 각 repo에서 `git diff --name-status af3d8e6 HEAD -- src`(제품 기능·context 폴더 제외), 파일 이름을 `CHANGELOG.md:130-140`과 대조 | memento A 3·M 23, tech-log A 2·M 38·D 17. CHANGELOG 수와 같다. 추가·수정 파일이 모두 세 분류 중 하나에 있다 |
|
||||
| E-6 | 새 절의 repo 경로 | 백틱 경로가 `src`·`scripts`·`config`·`tests`·`docs`·`recipes` 등으로 시작하면 존재 확인 | 생성 산출물 `artifacts/tests/a11y.json`, 자리표시자 둘, 백엔드 문서 `docs/fileserver/http-contract.md`(백엔드 pin에 있음)를 빼면 모두 있다 |
|
||||
| E-7 | 매뉴얼 새 오류 문구 | `docs/manual/reference/errors.md` diff의 새 5행 고정 부분을 `src`·`scripts`에서 `git grep -F` | 모두 있다(`external-contract-runtime.ts:691-695`, `:719`, `scripts/check-registries.ts:166`, `:414`, `scripts/test-sample-removal.ts:492`, `:523`) |
|
||||
| E-8 | 언어 없는 펜스 안 지울 수 있는 기능 경로 | README와 `docs/`(리뷰·superpowers 제외)에서 언어 없는 펜스 안의 `reference-feature`·`reference-context`·`platform-examples` 줄 | 0건 |
|
||||
|
||||
desktop 실행: 이 영역 리뷰어는 desktop에서 아무것도 돌리지 않았다. 읽은 것은 `/tmp/claude-gates/bbde570-ci/`(summary, FE-GATE-005·020 로그), `/tmp/claude-gates/r5/snap/`(verify-documentation 두 파일, lab.txt), 배치 로그 `/tmp/claude-gates/r5/batch/out/R5-14-R*.log`다. 실험은 배치로 요청했다(`scratchpad/r5/requests/14.md`). 오케스트레이터가 2026-11-06 04:36~04:39에 `bbde570`(head `bbde570796b0…`)에서 하나씩, local env로 돌렸다. 항목마다 checkout을 되돌렸고 복구는 모두 `restore=clean`이다. 표의 rc는 로그의 `drill-rc=`·`rc=`·`verify-rc=` 줄이다(항목 끝 `echo`의 rc는 늘 0).
|
||||
|
||||
| 요청 | 명령 | 변이 | 발견 | 결과 |
|
||||
|---|---|---|---|---|
|
||||
| 14-R1 | `corepack pnpm test:sample-removal -- --feature=platform-examples-feature` (local, load 2.76) | - | 1105/14-01 완료 기준 셋째 | `drill-rc=0`. `platform-examples-feature removal: PASS (17 checks, no fixture IDs)`(`R5-14-R1.log:2198`). 사본에서 `check:types`, lint, `verify:documentation`(지운 기능 `platform-examples-feature` 통지 뒤 `PASS_SCOPED`, `:19-21`), i18n, 디자인 시스템, 아키텍처, 레지스트리, `test:all`, 커버리지, 증거·CI 검사, 빌드가 돌았다(`:5-33`, `:895`, `:2124-2144`). 복구 clean |
|
||||
| 14-R2 | `node scripts/run-vitest.ts run tests/unit/template-feature-removal-documents.test.ts` (local) | `requests/14-R2.diff`(지운 기능 예외를 늘 빈 목록으로) | 1105/14-01·14-03 테스트가 빈 통과가 아닌지 | `rc=1`, 2 failed / 2 passed(`R5-14-R2.log:7-10`, `:68`). 실패 둘이 기대한 그 둘이다. "without reference-feature"는 12개 문서의 참조 기능 경로로(`:15-26`), "without platform-examples-feature"는 `starter-experience.md`의 세 경로로(`:46`) `FAIL_UNVERIFIED`. 나머지 둘은 통과. 대조군 `FE-GATE-005.txt:104` 4건 통과. 복구 clean |
|
||||
| 14-R3 | `corepack pnpm verify:documentation` (local) | `requests/14-R3.diff`(`reference-http-gateway.ts` 이름 변경 + import 한 줄) | 1105/14-03 완료 기준 앞 절반 | `verify-rc=1`. `docs/manual/01-add-a-feature.md`와 `docs/architecture/backend-api-and-server-state-contract.md`가 옛 경로를 적는다고 `FAIL_UNVERIFIED (failed: document references)`(`R5-14-R3.log:4-8`). 대조군 `verify-documentation.local.txt` `PASS_SCOPED`. 복구 clean |
|
||||
| 14-R4 | `node scripts/run-vitest.ts run tests/unit/manual-paired-backend-settings.test.ts` (local) | `requests/14-R4.diff`(매뉴얼 04 §3.2 두 행의 `defaultValue: null` 삭제) | 1105/14-02 테스트가 매뉴얼을 실제로 읽는지 | `rc=1`, 1 failed. typecheck 단언에서 `src/contracts/env.ts(94,9): error TS2322 … Property 'defaultValue' is missing …`(`R5-14-R4.log:17-19`). 대조군 `FE-GATE-005.txt:94` 통과. 복구 clean |
|
||||
|
||||
판정 규칙(변이는 대조군이 통과하고 변이가 기대한 이유로 실패해야 검사를 증명한다)을 세 변이 모두 채웠다.
|
||||
|
||||
요청하지 않은 것과 이유: 참조 기능 제거 드릴은 FE-GATE-020(CI env) 로그가 대신한다. `verify:documentation` 두 환경은 오케스트레이터 공유 실행이 있다. CHANGELOG 테스트 셋은 FE-GATE-005 로그가 있다. 두 다운스트림 실행은 제품 repo를 바꾸므로 하지 않았다.
|
||||
|
||||
## 7. 새 발견 요약
|
||||
|
||||
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|
||||
|---|---|---|---|---|
|
||||
| 14-01 | Low·P2 | 확인된 결함 | 새 절 BREAKING 1~3단계의 설명 셋이 코드·다운스트림과 다르다: 3단계 "부팅이 멈춘다"(실제는 기능 라우트 첫 진입), 1단계 TechLog를 "감싸지 않는 백엔드"로 적음, 2단계가 `requiresIdempotencyKey` 재계산을 말하지 않음 | `CHANGELOG.md:24-26`, `src/features/installed-contract-contributions.ts:93-111`, `src/contracts/server-state.ts:303-311`, tech-log `studio-management-server-state.ts:209`, `tech-log-management-contract-contribution.ts:143` |
|
||||
| 14-02 | Low·P3 | 확인된 결함 | D7 커밋 `287dc6f` 본문이 `bbde570` 이력에 없는 다시 쓰기 전 해시 `ab0d4a1`·`7ce9bf1`을 가리키고, CHANGELOG·커밋 본문 해시를 대조하는 장치가 없다 | `git show 287dc6f`, `scripts/verify-documentation-readiness.ts:165` |
|
||||
@@ -0,0 +1,179 @@
|
||||
# 영역 15 — 성능 실측·최적화
|
||||
|
||||
> 검토일 2026-11-06 · 기준 `bbde570`(PR B 끝, `fix/maturity-review-2026-11-05-b`) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
|
||||
> 경로: `config/performance/budgets.json`, `config/scale/feature-shape-ceilings.json`, `config/schemas/lab-performance.schema.json`, `scripts/check-bundle.ts`, `scripts/lib/{performance-budgets,lab-performance,vite-build-inputs}.ts`, `scripts/scale/measure-feature-shape-growth.ts`, `scripts/test-performance.ts`, `scripts/test-feature-scaffold.ts`(드릴의 기록 재작성 부분), `tests/unit/{feature-shape-growth,performance-budgets,lab-performance,vite-build-inputs,product-feature-selection-build}.test.ts`, `docs/operations/performance-evidence.md`, `vite.config.ts`, 15-01·15-05가 고친 `src/presentation/examples/platform-overview-page.tsx`·`src/presentation/styles/theme/base.css`, 시각 골든 5장(`tests/visual/__snapshots__/`), CHANGELOG 미출시 절의 성능 행
|
||||
> 깊게 본 관점: 21, 14, 10, 13
|
||||
> 렌즈: D7(초기 JS 예산 204,800 → 206,848 B)이 검사를 약하게 했나, 합칠 때 다시 쓴 기록(`0fee3fe`)이 빌드와 같은가, 1105/15-01~15-05와 이월 4건이 완료 기준까지 갔나
|
||||
> 영역 판정(35.8): **조건부 사용 가능.** 번들 게이트(FE-GATE-012, merge)와 생성 기능 드릴(FE-GATE-020)이 CI env에서 통과한다. lab(FE-GATE-026)은 오케스트레이터 로컬 실행에서 통과한다. 조건은 둘이다. (1) 템플릿 + 생성 기능 둘의 여유가 1,383 B다. 다음 템플릿 변경이 약 1.4 KB를 쓰면 드릴이 다시 넘는다. 그때 줄일지 올릴지 정한 규칙이 없다(새 15-01). (2) lab은 플랫폼 화면과 예제 기능 화면 하나만 잰다. `create:feature`가 만드는 화면은 모두 세션이 필요해서, 예제를 지운 제품에서는 기능 라우트를 하나도 재지 않고 통과한다(1105/15-04 일부).
|
||||
|
||||
## 0. 결론
|
||||
|
||||
- **D7은 검사를 약하게 했다. 다만 이유가 기록된 결정이고 사용자 영향은 작다.** 옛 예산이면 `bbde570`에서 FE-GATE-012는 642 B 남기고 통과하고, FE-GATE-020 드릴은 665 B 넘어 실패한다(CI env). 새 예산에서는 템플릿 여유 2,690 B, 드릴 여유 1,383 B다. 필요했던 폭은 665 B인데 2,048 B를 올렸다. 결정 기록은 올린 뒤 여유(2,737 B, 1,385 B)를 적지만, 왜 그만큼 남기는지와 다시 내릴 조건은 적지 않는다. 폭의 근거는 "202 KiB"라는 값뿐이다. 새 발견 15-01(Low·P3).
|
||||
- **D7이 건드리지 않은 것.** 기능 1 KiB·context 512 B 상한(`tests/unit/feature-shape-growth.test.ts:157-160`), 초기 파일 상한 32(`config/performance/budgets.json:5`), lazy 120 KiB(`:6`), lab LCP·CLS·200 ms(`:9-11`)는 그대로다. 기록 대조 허용치 256 B는 템플릿 여유(2,690 B)와 드릴 여유(1,383 B), 생성 기능 가장 작은 비용(새 context 기본 기능 328 B)보다 작다.
|
||||
- **합칠 때 다시 쓴 기록(`0fee3fe`)은 빌드와 맞는다.** 기록 204,111 B·27개(`config/scale/feature-shape-ceilings.json:61-66`). CI env 빌드는 204,158 B·27개(FE-GATE-012)로 47 B 차이다. FE-GATE-005의 기록 대조 테스트가 CI env에서 통과한다. 로컬 env에서 측정 스크립트를 다시 돌리면 네 값이 기록과 바이트까지 같다(15-R1). 그러니 `--initial-baseline --write`로 쓴 값이다.
|
||||
- **lab이 통과한다**(`r5/snap/lab.txt`, 로컬 env, 부하 0.70 → 0.73): LCP 2,032 ms, CLS 0, 상호작용 151 ms(150~153), 대상 화면 직접 진입 CLS 0(5회 모두 0), 기능 라우트 `EXAMPLES_UI` 402 ms(400~408) / 500 ms. 스크롤바를 보이게 띄운 실행이다.
|
||||
- **지난 발견 10건: 고쳐짐 5, 일부 2, 남음 2, 재발 1, 틀린 발견 0.** 1105/15-02·15-05는 배치로 완료 기준을 실행해 확인했다. 기록보다 +448 B 늘린 빌드에서 기록 대조가 실패했다(15-R2). 1280×720·1366×657과 지연 없음·lab 조건, 18회 모두 첫 화면 layout shift가 0건이다(15-R3). §16과 다르게 본 것은 셋이다. 1103/15-02는 "고침"이 아니라 재발이다(`performance-evidence.md:209-210`이 템플릿 초기 파일을 26개로 적는다. 지금 27개). 1101/15-01은 "남김"이 아니라 고쳐짐이다(완료 기준 충족, 여유 문제는 D7이 정했고 그 판단은 새 15-01). 1101/15-04는 "남김"이 아니라 일부다(SW 실제 대기는 `ce191be`가 없앴다).
|
||||
- **1105/15-04는 §16.4대로 일부이고, 남은 것이 하나 더 있다.** 요청 두 묶음(결정 대기) 말고도, 생성 기능 라우트는 모두 `session-required`라 lab 대상이 될 수 없다(`scripts/create-feature.ts:578`, `scripts/create-feature-write-slice.ts:130`).
|
||||
- **시각 골든 다시 찍기(`e02f252`)는 검사를 약하게 하지 않았다.** 옛·새 PNG를 열어 보니 내용은 같고 내용 폭만 1040 → 1025 px다. compact는 같은 내용이 15 px 좁아져 줄바꿈이 늘었다. FE-GATE-008에서 시각 6건이 통과한다.
|
||||
- 새 발견: Low 1. P3 1. 구조적 위험 1. High 이상과 P1은 없다. 배치 3건(15-R1~R3)은 모두 기대대로 나왔다. 15-R3의 `clientWidth` 기대 하나만 틀렸다(2절 15-05 행).
|
||||
|
||||
## 1. 범위 (36.1)
|
||||
|
||||
| 항목 | 기록 |
|
||||
|---|---|
|
||||
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` 영역 15(성능 실측·최적화) |
|
||||
| 커밋·작업 상태·확인 시점 | `bbde570796b0a648bae65c2c0568fca860a3ba4e`. 노트북 worktree(HEAD = 기준, 브랜치 `docs/maturity-review-2026-11-06`, untracked `AGENTS.md`는 무시)에서 읽기만 했다. 2026-11-06 04:05~. 이 문서 하나만 썼다 |
|
||||
| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음. 운영 서빙은 HTTP/2 이상이 전제다(`docs/operations/performance-evidence.md:208`) |
|
||||
| 필수 요구와 규모·운영 목표 | `config/performance/budgets.json:3-19`: 초기 JS 206,848 gzip B, 초기 JS 파일 32개, lazy 청크 파일당 122,880 B, lab LCP 2,500 ms·CLS 0.1·이름 붙은 상호작용 200 ms·기능 라우트 첫 진입 500 ms. 기능 하나 1 KiB·context 하나 512 B(`tests/unit/feature-shape-growth.test.ts:157-160`). 기록 대조 합계 256 B(`scripts/scale/measure-feature-shape-growth.ts:227`). field p75는 표본 기준 미정이라 설계대로 `FAIL_UNVERIFIED` |
|
||||
| 실행 환경 | 직접 실행 없음. desktop 기존 증거만 읽었다(모두 `bbde570`). (1) merge 단계 CI env 로그 `desktop:/tmp/claude-gates/bbde570-ci/`: `FE-GATE-005.txt`(unit·coverage), `FE-GATE-006.txt`, `FE-GATE-008.txt`(시각), `FE-GATE-012.txt`(번들), `FE-GATE-020.txt`(드릴). (2) 오케스트레이터 로컬 실행 `desktop:/tmp/claude-gates/r5/snap/`: `build.txt`, `lab.txt`, `base/performance/lab.json`(5회, `generatedAt` 2026-11-05T19:04:05Z). i5-10400F 12 CPU, Node v24.14.0, Chromium 151.0.7922.34. `base/performance/bundle.json`과 `merge/artifacts/performance/bundle.json`은 03:56에 FE-GATE-013 부분 실행의 `build:release-candidate`가 다시 쓴 것으로, `measurements`가 없어 쓰지 않았다. (3) 오케스트레이터 배치 15-R1~R3(`scratchpad/r5/requests/15.md`, 로그 `desktop:/tmp/claude-gates/r5/batch/out/R5-15-R*.log`, 같은 desktop, 부하 2.6~4.4) |
|
||||
| 읽은 코드·구성 범위 | 머리말 경로. `git log 8a44226..bbde570 -- <이 영역 경로>`의 커밋 10개: `c9aa73f`(15-03), `46359a1`(15-02), `e02f252`(15-05), `138c195`(15-01), `81701ad`(15-04), `f4d5761`(12-04, `vite.config.ts`), `b8d53c9`(합친 커밋, 빌드 입력 목록), `1dda18d`(문서 경로, 영역 14), `0fee3fe`(기록), `287dc6f`(D7). 2026-11-05 README §15·§16.2~16.6, 영역 15 문서, 2026-11-01·11-03 영역 15 문서의 해당 발견. `config/ci/gates.json`의 FE-GATE-005·012·020·026과 stage(`:2240-2272`) |
|
||||
| 수행한 테스트·실험 | 없음(규칙상 실행 금지). 게이트 로그와 스냅숏으로 판정했다. 시각 골든 5장은 `git show 8a44226:`·`bbde570:`로 꺼내 이미지로 비교했다. 완료 기준을 실행으로 봐야 하는 셋은 배치로 돌렸다: 기록 재측정(15-R1), 256 B 대조 변이(15-R2), 실제 스크롤바 첫 화면 shift(15-R3). 결과는 6절 |
|
||||
| 확인하지 못한 범위·이유 | 5절 |
|
||||
| 이전 리뷰와 비교 가능한 범위 | `docs/reviews/2026-11-05-maturity-review/15-performance.md`(기준 `8a44226`). 바이트는 결정적이라 비교한다. 다만 지난 라운드 바이트는 로컬 env, 이번 게이트 로그는 CI env라 build id만큼(수십 B) 다르다. lab 시간은 같은 호스트(i5-10400F)지만 부하가 다르다(지난 2~6, 이번 0.7) |
|
||||
|
||||
## 2. 지난 발견 재확인
|
||||
|
||||
README §16.4~16.6의 "고침"은 주장으로만 읽었다. 각 발견의 2026-11-05 영역 문서 3절(또는 그 이전 문서) 완료 기준과 `bbde570`의 코드·로그로 다시 판정했다.
|
||||
|
||||
| 지난 ID | 내용 | 상태 | 근거 |
|
||||
|---|---|---|---|
|
||||
| 1105/15-01 | lab 대상 화면이 그린 뒤 릴리스 칸을 늘려 21 px 민다. lab은 그 shift를 보지 못한다 | **고쳐짐** | 요약 전·실패 때도 같은 네 칸과 같은 hint 줄을 그린다(`src/presentation/examples/platform-overview-page.tsx:63-78`, `:439-484`). 컴포넌트 테스트가 요약 전후의 칸 이름·hint 유무가 같은지 본다(`tests/component/starter-platform-overview-page.test.tsx:252`, FE-GATE-006에서 11건 통과). lab이 run마다 대상 라우트를 직접 열어 CLS를 잰다(`scripts/test-performance.ts:230-242`). 판정은 `lab.cls`다(`scripts/lib/performance-budgets.ts:115`). `lab.json`의 `sampling.targetDeepLink.cls` 표본이 0·0·0·0·0이다. 완료 기준 둘(직접 열면 shift 0건, `lab.json`에 직접 진입 CLS가 있음)을 채운다. "0건"은 lab 조건에서 소수 넷째 자리 CLS 0으로 봤다(지난 shift는 0.0046이었다). 남은 위험(셈에 넣지 않음): 직접 진입 CLS 예산이 0.1이라 같은 크기의 shift가 다시 생겨도 lab은 통과하고 값만 남긴다(`138c195` 본문이 적음). 기능 라우트 클릭의 CLS는 재지만 버린다(`test-performance.ts:262-273`) |
|
||||
| 1105/15-02 | 기록 대조 허용 오차 1%(2,029 B)가 남은 여유보다 크다 | **고쳐짐** | 합계 허용치가 256 B 상수다(`scripts/scale/measure-feature-shape-growth.ts:219-227`, 판정 `:235-248`). 기능·context 10%, 파일 수 정확은 그대로다. 단위 테스트가 48 B·200 B 차이는 같음, 300 B 증가·1,500 B 차이는 다름으로 고정한다(`tests/unit/feature-shape-growth.test.ts:175-206`). FE-GATE-005(CI env)에서 7건 통과(`FE-GATE-005.txt:18`). 256 B는 지금 여유보다 작다: 템플릿 2,690 B, 드릴 1,383 B(CI env). CI 빌드와 기록의 차이는 47 B라 CI에서 실제 변경에 쓸 수 있는 폭은 약 209 B다. 완료 기준 "초기 JS를 300 B 늘린 템플릿 변경에서 기록을 다시 쓰기 전까지 `test:unit`이 실패한다"를 15-R2(CI env)가 확인했다. entry에 문자열을 넣어 빌드가 204,158 → 204,606 B(+448 B)가 되자 기록 대조 1건이 `gzipBytes: record 204111, build 204606`으로 실패했다(`feature-shape-growth.test.ts:165`). 기능·context 비용 단언(766 B·221 B)과 나머지 6건은 통과했다. 변이 없는 같은 명령은 `FE-GATE-005.txt:18`에서 통과한다 |
|
||||
| 1105/15-03 | 측정용 빌드 입력 목록이 두 파일에 있다 | **고쳐짐** | 목록은 `scripts/lib/vite-build-inputs.ts:11-21` 한 곳이다. 두 소비자가 import한다(`scripts/scale/measure-feature-shape-growth.ts:10`, `:104`, `tests/unit/product-feature-selection-build.test.ts:11`, `:39`). `git grep "const BUILD_INPUTS"`는 0곳이다(목록 이름은 `VITE_BUILD_INPUTS`). 새 테스트가 `vite.config.ts`의 상대 import 그래프가 목록 안에 있는지 본다(`tests/unit/vite-build-inputs.test.ts:58-71`). 합칠 때 `b8d53c9`가 12-04의 새 import(`vite.config.ts:9`)를 목록에 더했다(`vite-build-inputs.ts:19`). FE-GATE-005에서 `vite-build-inputs` 2건, `product-feature-selection-build` 1건, `feature-shape-growth` 7건 통과. **`c9aa73f`에 접은 변경은 약해진 검사가 아니다.** 소비자 목록을 있는 파일로 거르는 것(`vite-build-inputs.test.ts:19-22`)은 참조 기능을 지운 사본(FE-GATE-020)에서 측정 스크립트가 없기 때문이다. `8a44226`에는 이 테스트가 아예 없었다. 템플릿에서 측정 스크립트가 없어지면 `feature-shape-growth.test.ts`가 import에서 실패한다. 남은 틈(셈에 넣지 않음): 소비자 파일을 옮기면 (1)번 검사가 그 파일을 조용히 뺀다. 그래프는 정규식이라 동적 import·alias를 못 본다(커밋 본문이 적음) |
|
||||
| 1105/15-04 | lab은 플랫폼 화면 하나만 잰다. 기능 라우트 첫 진입은 어느 게이트도 재지 않는다 | **일부** | 고친 것: 설치된 기능이 가진 첫 공개 내비게이션 라우트를 고른다(`scripts/lib/lab-performance.ts:55-68`). run마다 같은 시계로 잰다(`scripts/test-performance.ts:262-273`). 예산 500 ms(`config/performance/budgets.json:12`), 판정(`scripts/lib/performance-budgets.ts:116-118`), 자가 검사 fixture(`test-performance.ts:381-393`). 단위 테스트가 커밋된 예산을 읽어 406 ms 통과·516 ms 실패를 고정한다(`tests/unit/performance-budgets.test.ts:106-136`). `lab.json`: `EXAMPLES_UI` 400·400·403·402·408, 중앙값 402 ms. 완료 기준(`lab.json`에 기능 라우트 시간과 표본)을 채운다. **남은 것 둘.** (1) 진입은 여전히 요청 두 묶음이다. 결정 대기(`docs/operations/performance-evidence.md:120-123`, `CHANGELOG.md:92`). (2) `create:feature`가 만드는 라우트는 목록·쓰기 모두 `session-required`다(`scripts/create-feature.ts:578`, `scripts/create-feature-write-slice.ts:130`). 공개 라우트는 예제 기능 `platform-examples-feature`뿐이고, 이 기능은 지울 수 있다(`scripts/lib/removable-template-features.ts:47-52`). 예제를 지운 제품에서는 `labFeatureRoute`가 null이고, lab은 `measured: false`로 남기고 통과한다(`performance-budgets.ts:117`). 15-04가 근거로 든 "다운스트림의 화면은 모두 기능 라우트다"가 그대로 남는다. `81701ad` 본문은 "생성 기능의 목록 라우트는 lab 대상이 되지 않는다"고 적었다. 문서(`performance-evidence.md:110-114`)는 그 결과(제품 화면을 재지 않음)를 말하지 않는다 |
|
||||
| 1105/15-05 | 홈 첫 렌더가 세로 스크롤바를 만들어 header를 15 px 민다. 게이트는 스크롤바를 숨겨 못 본다 | **고쳐짐** | `:root`에 `scrollbar-gutter: stable`(`src/presentation/styles/theme/base.css:6-11`). lab은 `--hide-scrollbars`를 빼고 띄운다(`scripts/lib/lab-performance.ts:33-35`, `scripts/test-performance.ts:255`). `lab.json`의 `context.browser.scrollbars`가 `"visible"`이고(`test-performance.ts:303-307`), 그 실행에서 `/` CLS가 5회 모두 0이다(1280×720, lab 조건). 단위 테스트가 실행 옵션과 CSS 줄을 본다(`tests/unit/lab-performance.test.ts:123-133`). 완료 기준은 1280×720과 1366×657, 지연 없음과 lab 조건이다. 15-R3(지난 라운드 15-R2와 같은 스크립트, 스크롤바 보임)에서 세 창 × 두 조건 × 3회 = 18회 모두 layout shift 0건이다. 지난 라운드 `8a44226`에서는 같은 스크립트로 1280×720·1366×657 12회 모두 shift 1건(0.00023·0.00022, header 세션 영역 15 px 이동)이었다. 내 요청의 기대 하나는 틀렸다. `document.documentElement.clientWidth`는 지금도 홈이 그려지는 프레임에 1280 → 1265, 1366 → 1351로 바뀐다(지연 없음 396~415 ms, lab 조건 2,023~2,041 ms). 1920×960은 1920 그대로다. 그래서 이 값은 실제 스크롤바가 생겼는지만 보여 주고, 비어 있는 gutter는 빼지 않는 것으로 보인다(추론, 따로 재지 않음). 스크롤바를 숨긴 시각 골든의 내용 폭이 1040 → 1025 px로 줄어든 것이 gutter가 처음부터 자리를 잡는다는 근거다. 판정은 layout shift 기록으로 했다. **합칠 때 다시 찍은 골든 5장(`e02f252`)**: 옛·새 PNG를 비교했다. 플랫폼 구성·상태 화면·갤러리는 같은 내용에 폭만 1040 → 1025 px, wide 셸은 같은 1440×900, compact는 390 px 안의 내용 폭이 15 px 줄어 줄바꿈이 늘고 높이가 1297 → 1377 px다. 다른 그림 변화는 보지 못했다. FE-GATE-008에서 시각 6건 통과. 남은 위험(셈에 넣지 않음): lab CLS 예산 0.1이라 0.0002 shift가 다시 생겨도 통과한다(`e02f252` 본문). compact 골든은 overlay 스크롤바를 쓰는 휴대폰보다 15 px 좁게 그린다. 열린 drawer의 가림막이 gutter 15 px를 덮지 않는다(골든에 보인다, `e02f252` 본문). 일반 스크롤바 브라우저에서 내용이 짧은 화면이면 그 자리가 어둡게 되지 않은 띠로 남는다(추론, 재지 않음) |
|
||||
| 1103/15-02 | 성능 기준선 숫자가 현재 빌드와 다르다 | **재발** | §16.5는 "고침(`832774f`)"이다. `832774f`는 11-03 CHANGELOG 절의 파일 상한(26 → 32)을 고쳤다. 그 절(`CHANGELOG.md:207`, `:317`)은 그 범위 끝(`8a44226`)의 값이라 지금 숫자와 달라도 세지 않는다. 그러나 살아 있는 문서 `docs/operations/performance-evidence.md:209-210`이 "상한은 템플릿 그대로의 수(26)에 6을 더한 32다"라고 적는다. 지금 템플릿은 27개다(기록 `config/scale/feature-shape-ceilings.json:63`, FE-GATE-012 `27 / 32 files`). `0fee3fe`가 기록을 27로 바꾸며 이 문장을 고치지 않았다. 지난 라운드가 "손으로 적었다(지금은 맞다)"고 적어 둔 바로 그 문장이다. 완료 기준 "문서·JSON에 서로 다른 기준선이 없다"를 다시 어긴다. 바이트 쪽(기록 한 곳, 256 B 대조)은 지켜진다 |
|
||||
| 1101/15-01 | 초기 JS 여유가 작고, 넘었는지 보는 검사가 release에서만 돈다 | **고쳐짐** | §16.6은 "남김(예산을 먼저 정해야 한다)"이다. 완료 기준 둘을 채운다. (1) 예산 + 1 B가 merge에서 실패한다: FE-GATE-012가 merge stage에 있다(`config/ci/gates.json:2257`). `check:bundle` 자가 fixture `initial-js-over-budget`(`scripts/check-bundle.ts:62`)와 `check-bundle-output.test.ts` 5건이 FE-GATE-005에서 통과한다. (2) 문서의 기준선·여유가 측정과 같다: 문서는 숫자 대신 기록을 가리키고(`performance-evidence.md:22-25`, `:42-43`), 기록은 CI 빌드와 47 B 차이다. 지난 라운드가 남겨 둔 "여유가 작다"는 D7이 예산을 정하며 답했다. 그 결정이 검사를 얼마나 약하게 했는지는 새 15-01에서 본다 |
|
||||
| 1101/15-03 | 예산이 CSS를 빼고, lazy는 파일 단위만 본다 | **남음** | `scripts/check-bundle.ts:38-47`은 초기 JS 파일만 더한다. 문서도 그렇게 적는다(`performance-evidence.md:83`). CSS `index-Dv15Src3.css` 8.81 kB gzip(vite 출력, `FE-GATE-012.txt`). 라우트 진입 하나의 lazy 합계를 보는 예산은 없다. 새 기능 라우트 예산(500 ms)은 시간 검사라 바이트 합을 대신하지 않는다 |
|
||||
| 1101/15-04 | 빠른 테스트 계층의 시간을 프로세스 생성과 실제 대기가 정한다 | **일부** | §16.6은 "남김"이다. SW 테스트의 실제 5초 대기는 `ce191be`(1101/10-07)가 가짜 시계로 바꿨다. `service-worker-runtime.test.ts` 64건이 320 ms다(`FE-GATE-005.txt:119`). 남은 것: `tests/setup.ts:1-2`가 여전히 모든 파일에 jest-dom·RTL을 싣는다. 자식 프로세스를 띄우는 파일이 unit에 남는다(`documentation-readiness` 22.5초, `product-extension-typecheck` 21.9초, `FE-GATE-005.txt:180`, `:172`). FE-GATE-005가 `test-unit`과 `test-coverage`를 둘 다 돈다(`config/ci/gates.json:1842-1848`). CI env unit: 208파일 3,056건 28.45초, setup 합 50.73초(`FE-GATE-005.txt:312-315`). coverage 실행 332파일 85.50초(`:781-784`) |
|
||||
| 0929/11-04 | lab 판정이 호스트 부하로 뒤집힌다 | **남음** | `scripts/test-performance.ts:244`, `:257`, `:275`, `:300`은 부하를 기록만 한다. 이번 lab은 부하 0.70 → 0.73에서 표본 범위가 3 ms(상호작용)·8 ms(기능 라우트)다. 노출은 넓어졌다. 새 기능 라우트 예산의 여유가 98 ms(24%)로, 기존 상호작용 예산의 여유 49 ms(25%)와 같은 크기의 판정이 하나 더 생겼다. `81701ad` 본문이 이 위험을 적었다. 2026-09-27 기록(부하 11~17)에서는 상호작용이 30~60% 늘었다(`performance-evidence.md:133-138`) |
|
||||
|
||||
### 2.1 D7 — 예산 상향이 무엇을 통과시키나
|
||||
|
||||
| 상태(`bbde570`, CI env) | 초기 JS gzip B | 파일 / 상한 | 옛 예산 204,800 | 새 예산 206,848 |
|
||||
|---|---:|---|---|---|
|
||||
| 템플릿 그대로(FE-GATE-012, `FE-GATE-012.txt`) | 204,158 | 27 / 32 | 통과, 여유 642 | 통과, 여유 2,690 |
|
||||
| 드릴: + `scaffold-feature`(새 context) + `scaffold-write-feature --with-create --keyed`(새 context)(`FE-GATE-020.txt:6206`, 기록 `:4414`) | 205,465 | 27 / 32 | **665 B 초과로 실패** | 통과, 여유 1,383 |
|
||||
| 드릴에서 `scaffold-feature`를 지운 뒤(제거 드릴의 기록, `FE-GATE-020.txt:6309`) | 205,137 | 27 / 32 | 337 B 초과 | 통과 |
|
||||
| 로컬 기록(`0fee3fe`, `feature-shape-ceilings.json:61-66`) | 204,111 | 27 / 32 | 여유 689 | 여유 2,737 |
|
||||
|
||||
- **통과시키는 것.** (1) PR B의 +1,184 B. 옛 예산이면 드릴이 실패한다. (2) 그 위에 템플릿이 1,383 B 더 늘어도 드릴이 통과하고, 2,690 B까지 FE-GATE-012가 통과한다. 옛 예산에서는 드릴이 이미 실패하고 템플릿 자체는 642 B였다.
|
||||
- **그래도 막는 것.** 템플릿 변경이 256 B를 넘게 늘리면 기록 대조가 `test:unit`(FE-GATE-005, merge)에서 실패한다. 다만 `--initial-baseline --write`로 기록을 다시 쓰면 풀린다. 이번 라운드가 그렇게 했다(`0fee3fe`). 그래서 기록은 diff에 흔적을 남기는 알림이지 멈춤이 아니다. 멈춤은 예산뿐이다.
|
||||
- **생성 기능 비용**(CI env, 위 표의 차): `--with-create --keyed` 기능(새 context) 979 B, 기본 기능(새 context) 328 B. 템플릿 여유 2,690 B에는 쓰기 기능 둘이 들어간다. D7의 "기능 셋이 들어간다"(README 2026-11-05 §16.2 `:556`)는 참조 모양 기능을 있는 context에 넣을 때(768 B × 3 = 2,304 B)만 맞다. 새 context마다 218 B를 더하면 둘이다.
|
||||
- **움직이지 않은 것.** 기능 1 KiB·context 512 B 상한(`feature-shape-growth.test.ts:157-160`), 파일 상한 32(`budgets.json:5`), lazy 122,880 B(`:6`), lab 2,500 ms·0.1·200 ms(`:9-11`). 기록의 `perContextGzipBytes`는 233 → 218 B, `files`는 26 → 27이다(정확 대조). 파일 상한의 남은 칸은 6 → 5다.
|
||||
- **256 B는 여전히 여유 아래다.** 템플릿 2,690 B, 드릴 1,383 B, 가장 싼 생성 기능 328 B, 참조 모양 기능 768 B 모두보다 작다.
|
||||
- **이유는 구체적이다.** 늘어난 1,184 B를 출처별로 적었고(README 2026-11-05 §16.2 `:548-553`), 합(327 + 293 + 251 + 148 + 165)이 기록 차(202,927 → 204,111)와 같다. 커밋마다 잰 값 자체는 다시 재지 않았다.
|
||||
- **올린 폭과 재검토 조건은 구체적이지 않다.** 필요한 폭(665 B)의 약 세 배를 올렸다. 폭의 근거는 "202 KiB"뿐이다(`performance-evidence.md:44-53`). 재검토 조건 "예산을 또 넘을 때"는 이번 상향을 만든 조건과 같다. 그때 줄일지 다시 올릴지는 "런타임 검사를 빌드 시점으로 옮기는 것부터 본다"로만 적혀 있다. 08-03 청크를 묶어 약 240 B를 되찾으면 예산을 내릴지도 적혀 있지 않다. 버린 대안의 240 B는 재지 않은 추정이다. 같은 라운드의 lab 기능 라우트 예산은 단위 테스트가 "지금 값 통과, 묶음 하나 더하면 실패"로 묶는데(`performance-budgets.test.ts:106-136`), 초기 JS 예산 값에는 그런 묶음이 없다(테스트의 `initialJsGzipBytes`는 fixture 값뿐, `tests/unit/bundle-artifact-contract.test.ts:30-40`). 새 발견 15-01.
|
||||
- **근거 추적.** `287dc6f` 본문은 03-01을 `ab0d4a1`, 08-03을 `7ce9bf1`로 적는다. 둘 다 `bbde570`에서 닿지 않는 커밋이다(fixup 전 해시). README §16.2는 닿는 `5c0b37e`·`f849d78`을 적는다. 문서(`performance-evidence.md:53`)는 README를 가리키므로 결정 기록은 따라갈 수 있다.
|
||||
|
||||
### 2.2 합칠 때 다시 쓴 기록(`0fee3fe`)
|
||||
|
||||
- 바뀐 것은 `initialJavascript` 네 값뿐이다: 202,927 → 204,111 B, 26 → 27개, 기능 768 그대로, context 233 → 218 B(`git show 0fee3fe`). 키 순서와 형식은 `writeInitialBaseline`이 쓰는 모양이다(`measure-feature-shape-growth.ts:334-342`).
|
||||
- 빌드와 맞는다: CI env 빌드 204,158 B·27개(FE-GATE-012)와 47 B 차이다. 지난 라운드가 적은 build id 차(6 B, 48 B)와 같은 크기다. FE-GATE-005(CI env)의 기록 대조 테스트가 통과한다(256 B, 파일 정확, 비용 10%).
|
||||
- 스크립트가 쓴 값이다. 15-R1(로컬 env, `--write` 없이)이 `{"gzipBytes":204111,"files":27,"perFeatureGzipBytes":768,"perContextGzipBytes":218}`를 냈다. 기록과 네 값 모두 바이트까지 같다. 기록은 로컬 env 값이고 CI env 빌드는 47 B 크다.
|
||||
- 드릴(`scripts/test-feature-scaffold.ts:71-94`)은 생성 기능을 더한 뒤 같은 스크립트로 기록을 다시 쓴다. 그래서 드릴 안에서는 256 B 대조가 시험되지 않는다(기록이 정의상 맞음). 드릴이 보는 것은 예산(FE-GATE-012)이다.
|
||||
|
||||
## 3. 이번 발견 (36.3)
|
||||
|
||||
새 발견 1건: Low 1. P3 1. 구조적 위험 1. High 이상과 P1은 없다.
|
||||
|
||||
### 15-01 초기 JS 예산 상향(D7)이 드릴 초과분(665 B)의 세 배를 올렸다. 올린 폭의 근거와 다시 내릴 조건이 없어, 다음 1.4 KB는 어느 merge 게이트도 멈추지 않는다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 구조적 위험(약해진 검사, 기록된 결정) |
|
||||
| 관련 관점 | 21, 14, 13, 5, 10 |
|
||||
| 근거 | `config/performance/budgets.json:4` 204,800 → 206,848 B(+2,048 B, `287dc6f`). CI env `bbde570`: FE-GATE-012 `initial JS 204158 / 206848 gzip bytes, 27 / 32 files`(`gate-artifacts/FE-GATE-012.txt`), FE-GATE-020 드릴 `initial JS 205465 / 206848`(`FE-GATE-020.txt:6206`). 옛 예산이면 드릴이 665 B 넘는다. 새 예산의 드릴 여유는 1,383 B다. 결정 기록은 올린 뒤 여유(템플릿 2,737 B, 드릴 1,385 B, 로컬 값)를 적지만 왜 그만큼 남기는지는 적지 않는다. 폭의 근거는 "202 KiB"라는 값뿐이다(`docs/operations/performance-evidence.md:44-53`, README 2026-11-05 §16.2 `:540-558`). 재검토 조건 "예산을 또 넘을 때"는 이번 상향의 조건과 같다. 다시 내릴 조건이 없다. 줄이기 대안의 240 B는 재지 않은 추정이다(`287dc6f` 본문). 같은 라운드의 lab 기능 라우트 예산은 단위 테스트가 커밋된 값을 읽어 묶는다(`tests/unit/performance-budgets.test.ts:106-136`). 초기 JS 예산 값을 묶는 테스트는 없다(`tests/unit/bundle-artifact-contract.test.ts:30-40`은 fixture 값). 기록 대조는 다시 쓰면 풀린다(`0fee3fe`). 커밋 본문의 해시 `ab0d4a1`·`7ce9bf1`은 `bbde570`에서 닿지 않는다 |
|
||||
| 발생 조건 | 템플릿 변경(또는 리뷰 조치 묶음)이 초기 JS를 1,383 B 안에서 늘리고 기록을 다시 쓸 때. 이번 라운드의 조치 묶음은 1,184 B를 늘렸다 |
|
||||
| 영향 | 그 폭은 어느 merge 게이트도 멈추지 않고 기록 diff만 남는다. 그 뒤에 넘으면 같은 결정을 다시 해야 하는데, 줄일지 올릴지 정한 규칙이 없다. 상한을 넘을 때마다 올린 것이 두 번째다(파일 상한 25 → 26 → 32, 바이트 200 → 202 KiB). 1101/15-01이 영향 칸에 "결국 예산을 근거 없이 올리기 쉽다"고 적은 경로다. 이번에는 이유가 적혀 있다. 사용자 영향은 작다. 2,048 B는 lab 조건(200 KB/s)에서 다운로드 약 10 ms다(계산, 재지 않음). lab LCP는 2,032 / 2,500 ms다 |
|
||||
| 심각도·우선순위 | Low · P3 — 결정이 기록돼 있고 사용자 피해가 거의 없다. 남는 것은 폭의 근거와 되돌림 규칙이다. 템플릿 예산을 그대로 복사한 제품은 merge로 함께 올라간다(CHANGELOG `:56`이 "그대로 두거나 같은 이유로 올린다"고 안내) |
|
||||
| 통제·증거 | 목표 M3(예산 값이 정한 여유 규칙에 묶여, 규칙 밖 상향이 테스트에서 걸림) / 확인 M1(문서의 이유·재검토 조건) · E2(FE-GATE-012·020 로그) + E1 |
|
||||
| 확실성과 남은 가정 | 바이트는 CI env 로그와 15-R1(로컬 기록과 같음)이다. 10 ms는 계산이다. 다음 라운드 조치가 다시 1.4 KB를 쓸지는 추론이다(이번 라운드 1,184 B) |
|
||||
| 결정의 근거 | 확인된 사실: 늘어난 1,184 B의 출처 표와 합이 맞는다. 기록된 의도: 라운드 중간의 설계 변경을 피하고, 13-03(zod 약 7 KB) 때 다시 본다. 리뷰어 추론: 665 B만 올렸으면 드릴 여유가 0이라 다음 변경 하나로 다시 넘는다. 여유가 필요했던 것은 맞다. 얼마가 필요한지가 적혀 있지 않다 |
|
||||
| 이해 비용 | 다음 담당자는 예산을 넘었을 때 "올린다"와 "줄인다" 중 무엇이 규칙인지 문서에서 알 수 없다. 남은 여유를 "템플릿이 더 쓸 몫"과 "다운스트림 기능 몫"으로 나눈 기록도 없다 |
|
||||
| 최소 개선 방향 | 예산을 "템플릿 기록 + 정한 여유"로 적는다. 예: 생성 기능 둘(드릴) + 템플릿 몫 N B. 그 수를 `performance-evidence.md`에 숫자로 둔다. 원하면 lab 기능 라우트 예산처럼 단위 테스트가 `budgets.json` 값과 기록의 차를 그 범위로 묶는다. 템플릿 몫을 다 쓰면 먼저 줄이는 것(08-03 청크 묶기, 런타임 검사 이동)을 재고, 줄여서 되찾은 만큼 예산을 내릴지도 적는다 |
|
||||
| 대안 비교 | (a) 현상 유지: 다음에 넘을 때 다시 결정한다. (b) 여유 규칙을 숫자로 적기(권장, 문서 몇 줄). (c) (b) + 테스트로 묶기: 올리려면 테스트도 바꿔야 해서 diff에 드러난다. 테스트 하나. (d) 예산을 드릴 + 256 B(약 205,721 B)로 되돌리기: 다음 템플릿 변경마다 넘는다. (e) 줄이기: 08-03 청크(약 240 B, 추정)와 런타임 검사 이동. 측정이 먼저다 |
|
||||
| 단순화의 보존 조건 | 드릴(생성 기능 둘)이 예산 안에 든다. 기록 대조 256 B. 초기 파일 상한 32 |
|
||||
| 비용·부작용 | (b)는 문서. (c)는 테스트 하나와, 예산을 바꿀 때 테스트 한 줄 |
|
||||
| 재검토 조건 | field p75 LCP 데이터가 생기면 예산 근거를 field로 옮긴다. 1103/13-03(zod)을 정할 때 |
|
||||
| 완료 기준 | 문서에 여유의 크기와 나눈 몫이 숫자로 있다. (c)를 고르면 `initialJsGzipBytes`를 그 범위 밖으로 올리는 변이에서 `test:unit`이 실패한다 |
|
||||
| 검증 방법 | (c): 예산 값 변이로 그 테스트를 돌린다 |
|
||||
| 담당·기한·상태 | 결정권자: 메인 세션(D7을 정함) · 미정 · 신규 |
|
||||
|
||||
## 4. 28개 관점 판정 (36.2)
|
||||
|
||||
표기: O 충족 / P 부분 충족 / X 미충족 / ? 미검증 / - 적용 제외 / > 다른 영역.
|
||||
|
||||
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | 코드 성숙도 | 일부 적용(성능 스크립트) | M2 / M2 | E1, E2 | **O** — 판정기(`performance-budgets.ts`)에 새 지표가 타입으로 들어갔다(`:66-89`). lab 자가 fixture에 기능 라우트 초과가 더해졌다(`test-performance.ts:381-393`). 이 영역 테스트가 FE-GATE-005에서 모두 통과한다 |
|
||||
| 2 | 구조적 성숙도 | 일부 적용(청크 구성) | M3 / M3 | E2 | **O** — 초기 파일 27개. 늘어난 하나는 08-03의 `navigation-policy` 공유 청크다(`0fee3fe` 본문). 생성 기능 둘을 더해도 27개 그대로다(FE-GATE-020) |
|
||||
| 3 | 변경 용이성 | 적용 | — / — | E1, E2 | **P** — 빌드 입력 목록이 한 곳이 됐다(1105/15-03). 생성 쓰기 기능 둘이 예산 수정 없이 들어간다. 셋째부터는 결정이 필요하다(2.1절) |
|
||||
| 4 | 인지 부하 | 적용 | M1 / M1 | E1 | **P** — 문서가 템플릿 초기 파일을 26개로 적는다(1103/15-02 재발). 예산을 넘을 때의 규칙이 없다(15-01). lab CLS 예산 0.1이 작은 shift를 값으로만 남긴다는 점을 알아야 0의 뜻을 안다 |
|
||||
| 5 | 위험 가시성 | 적용 | M3 / M2 | E2, E3 | **P** — lab이 직접 진입 CLS·기능 라우트·스크롤바를 남긴다. lab은 여전히 release 단계만이다(`config/ci/gates.json:2271`). 예제를 지운 제품에서는 기능 라우트가 `measured: false`로 통과한다(1105/15-04 일부) |
|
||||
| 6 | 실패 성숙도 | 다른 영역(06·09) | — | — | **>** |
|
||||
| 7 | 운영 성숙도 | 일부 적용 | M2 / M2 | E3 | **P** — `lab.json`에 스크롤바, 직접 진입, 기능 라우트 표본, 부하가 남는다. field는 설계대로 `FAIL_UNVERIFIED` |
|
||||
| 8 | 디버깅 가능성 | 적용 | M2 / M2 | E1, E2 | **O** — 기록 대조 실패가 잰 값과 고칠 명령을 말한다(`feature-shape-growth.test.ts:161-165`). lab 실패가 기능 라우트 표본을 말한다(`test-performance.ts:410-418`) |
|
||||
| 9 | 유지보수 성숙도 | 적용 | M3 / M2 | E1, E2 | **P** — 바이트 기록은 한 곳이고 256 B로 대조한다. 손으로 적은 파일 수(26)가 다시 낡았다(1103/15-02 재발) |
|
||||
| 10 | 테스트 성숙도 (깊게) | 적용 | M3 / M3 | E2 | **P** — FE-GATE-005(CI env): `feature-shape-growth` 7건, `check-bundle-output` 5건, `build-environment-bundle` 2건, `product-feature-selection-build` 1건, `lab-performance` 9건, `performance-budgets` 5건, `vite-build-inputs` 2건 통과. 시각 6건 통과(FE-GATE-008), 다시 찍은 골든은 gutter 폭만 다르다. 256 B 대조는 실제로 +448 B 늘린 빌드에서 실패한다(15-R2, 변이 실험 E3). 빠른 계층 시간은 일부만 줄었다(1101/15-04) |
|
||||
| 11 | 데이터 성숙도 | 적용 제외 | — | — | **-** 이 영역에 저장 데이터가 없다 |
|
||||
| 12 | 동시성 성숙도 | 다른 영역(03·05·12) | — | — | **>** 실행 격리 출력 경로(`vite.config.ts:173-189`)는 12-04, 오케스트레이터 몫 |
|
||||
| 13 | 확장성 (깊게) | 적용 | M3 / M3 | E2 | **P** — 생성 기능 비용(CI env): 쓰기 기능 979 B, 기본 기능 328 B(새 context). 드릴 뒤 여유 1,383 B. 여유는 결정으로 생겼고 규칙이 없다(15-01) |
|
||||
| 14 | 성능 성숙도 (깊게) | 적용 | M3 / 번들 M3(merge), lab M3(release) | E2, E3 | **P** — 번들 204,158 / 206,848 B. lab PASS: LCP 2,032 ms, CLS 0, 상호작용 151 ms, 직접 진입 CLS 0, 기능 라우트 402 / 500 ms. 진입 두 묶음 그대로(15-04). CSS·라우트 합 예산 없음(1101/15-03). field 미검증 |
|
||||
| 15 | 보안 성숙도 | 다른 영역(13) | — | — | **>** zod advisory 갱신(약 +7 KB, 1103/13-03)은 지금 여유 2,690 B로도 들어가지 않는다. D7은 이 결정을 하지 않는다 |
|
||||
| 16 | 의존성 성숙도 | 일부 적용 | M2 / M3 | E1 | **O** — react-router 운영 빌드 별칭은 그대로다(`vite.config.ts:156-171`) |
|
||||
| 17 | API / Contract 성숙도 | 다른 영역(07) | — | — | **>** |
|
||||
| 18 | 배포 성숙도 | 적용 | M3 / M3 | E2, E3 | **O** — FE-GATE-012 merge, FE-GATE-026 release. 이번 lab은 로컬 env 실행이다(CI env release 실행은 없음, 5절) |
|
||||
| 19 | 설정 성숙도 | 적용 | M2 / M2 | E1 | **O** — 예산은 `budgets.json` 한 곳, 기록은 `feature-shape-ceilings.json` 한 곳, 빌드 입력은 `vite-build-inputs.ts` 한 곳 |
|
||||
| 20 | 개발자 경험 (깊게) | 적용 | M2 / M2 | E1, E2 | **P** — 생성 명령이 기록 재작성을 안내하고 드릴이 그대로 따른다(`scripts/test-feature-scaffold.ts:71-94`). 문서의 파일 수가 틀렸다. 예산을 넘을 때 할 일이 정해져 있지 않다 |
|
||||
| 21 | Guardrail 성숙도 (깊게) | 적용 | M3 / M3(대조·lab), M1(예산 값) | E2 | **P** — 기록 대조가 1% → 256 B로 조여졌다. lab이 스크롤바·직접 진입·기능 라우트를 본다. 예산 자체는 넘자 올렸고 폭의 규칙이 없다(15-01) |
|
||||
| 22 | 추상화 성숙도 | 다른 영역(16) | — | — | **>** |
|
||||
| 23 | 일관성 | 일부 적용 | — | E1 | **P** — 빌드 입력 목록은 하나가 됐다. lab만 스크롤바를 보이게 띄우고 다른 Playwright 게이트는 숨긴다(문서가 적음, `performance-evidence.md:125-129`) |
|
||||
| 24 | 네이밍 / 의미 성숙도 | 일부 적용 | — | E2 | **P** — react-router 청크는 여전히 자동 이름(`chunk-3WDNQUW5`)이다. 문서는 청크 이름으로 판단하지 않는다고 적는다(`performance-evidence.md:57`) |
|
||||
| 25 | 조직 확장성 | 다른 영역(12·16) | — | — | **>** 기능 브랜치 둘이 기록 같은 줄에서 충돌하는 것은 1105/16-01(결정 대기, CHANGELOG `:97`) |
|
||||
| 26 | Ownership 성숙도 | 다른 영역(14) | — | — | **>** 예산 결정은 다운스트림 몫이라고 문서에 있다(`performance-evidence.md:17-20`) |
|
||||
| 27 | 삭제 가능성 | 다른 영역(14) | — | — | **>** 예제 기능을 지우면 lab 기능 라우트가 사라진다(1105/15-04 일부의 원인) |
|
||||
| 28 | 회복 가능성 | 다른 영역(06) | — | — | **>** |
|
||||
|
||||
## 5. 미검증
|
||||
|
||||
| 범위 | 이유 | 확인 방법 |
|
||||
|---|---|---|
|
||||
| `clientWidth`가 빈 stable gutter를 빼지 않는다는 해석 | 15-R3은 layout shift 0건과 폭 변화를 같이 보였다. 원인은 재지 않았다 | `getBoundingClientRect()`로 `main`·header 폭을 프레임마다 기록 |
|
||||
| gutter를 지운 변이에서 15-R3 스크립트가 shift를 다시 잡는지 | 지난 라운드 `8a44226`(gutter 없음)의 결과만 있다 | `base.css`의 `scrollbar-gutter` 줄을 지운 변이로 15-R3 재실행 |
|
||||
| 대상 화면 직접 진입 shift의 지연 없음·Fast 3G 조건 | lab은 lab 조건만 잰다. 구조 수정과 컴포넌트 테스트로 판단했다 | 지난 라운드 `r4-15-platform-shift.mjs` |
|
||||
| D7의 커밋별 증가량(327·293·251·148·165 B) | 주장으로만 읽었다. 합이 기록 차와 같은 것만 확인했다 | 커밋마다 `--initial-baseline` |
|
||||
| 08-03 청크를 묶어 되찾는 바이트(약 240 B 추정) | 누구도 재지 않았다 | `vite.config.ts` 청크 그룹 변이 + `check:bundle` |
|
||||
| CI env의 lab | FE-GATE-026은 release 단계라 merge 로그에 없다. `lab.txt`는 로컬 env다 | `CI=true` lab 1회 |
|
||||
| 세션이 필요한 기능 라우트의 첫 진입 시간 | lab에 세션이 없다 | demo 세션을 붙인 lab |
|
||||
| 시각 골든의 CI 러너 재현 | desktop에서만 통과를 봤다(영역 11) | CI 러너의 FE-GATE-008 |
|
||||
| drawer 가림막이 덮지 않는 gutter 띠 | 골든(스크롤바 숨김)에서만 봤다. 일반 스크롤바·짧은 화면은 재지 않았다 | 일반 스크롤바 Chromium에서 짧은 화면 + drawer 스크린숏 |
|
||||
| firefox·webkit의 lab 수치 | lab은 Chromium만이다 | — |
|
||||
| field CLS·INP | 입력이 없다(설계대로 `FAIL_UNVERIFIED`) | — |
|
||||
|
||||
## 6. 실행 기록
|
||||
|
||||
이 리뷰어는 아무것도 실행하지 않았다(규칙). 아래 셋은 오케스트레이터 배치가 돌렸다(요청 `scratchpad/r5/requests/15.md`, 2026-11-06 04:39~04:40, 한 번에 하나, 항목마다 checkout을 되돌림). 패치는 `scratchpad/r5/a15/`에 있고 `bbde570`에 `git apply --check`로 맞는 것을 확인했다. 로그는 `desktop:/tmp/claude-gates/r5/batch/out/R5-15-R{1,2,3}.log`다.
|
||||
|
||||
| ID | 명령 | 변이 | rc | 결과 |
|
||||
|---|---|---|---|---|
|
||||
| 15-R1 | `node scripts/scale/measure-feature-shape-growth.ts --initial-baseline` · local | - | 0 | `initial JavaScript: {"gzipBytes":204111,"files":27,"perFeatureGzipBytes":768,"perContextGzipBytes":218}`. 기록(`feature-shape-ceilings.json:61-66`)과 같다. 기대대로. 부하 4.36. `restore=clean` |
|
||||
| 15-R2 | `node scripts/run-vitest.ts run tests/unit/feature-shape-growth.test.ts` · CIENV | `15-R2.patch`(entry에 압축되지 않는 문자열, 측정상 +448 gzip B) | 1 | 7건 중 1건 실패: `bounds what one more feature and one more context add, and matches the record (15-01)`, `initialJavascript is stale (measured {"gzipBytes":204606,"files":27,"perFeatureGzipBytes":766,"perContextGzipBytes":221})`, `["gzipBytes: record 204111, build 204606"]`(`:165`). 나머지 6건 통과. 기대대로. 변이 없는 대조는 `FE-GATE-005.txt:18`(통과). 부하 4.17. `restore=clean` |
|
||||
| 15-R3 | `mkdir -p /tmp/claude-gates/r5/exp && corepack pnpm build && node scripts/r5-15-scrollbar.mjs 3 /tmp/claude-gates/r5/exp/15-R3-scrollbar.json` · local | `15-R3.patch`(측정 스크립트만 추가) | 0 | Chromium 151, 스크롤바 보임. 18회 모두 `shifts 0 CLS 0.00000`. 폭: 1280×720은 1280 → 1265(지연 없음 412~415 ms, lab 조건 2,023~2,041 ms), 1366×657은 1366 → 1351(396~402 ms, 2,024~2,026 ms), 1920×960은 1920 그대로. shift 0건은 기대대로다. "창마다 폭 하나"라는 기대는 틀렸다(2절 15-05 행). 상세 `desktop:/tmp/claude-gates/r5/exp/15-R3-scrollbar.json`. 부하 3.92 → 2.63. `restore=clean` |
|
||||
|
||||
판정에 쓴 기존 출력(모두 `bbde570`):
|
||||
|
||||
| 출력 | 쓴 값 |
|
||||
|---|---|
|
||||
| `bbde570-ci/gate-artifacts/FE-GATE-012.txt`(CI env) | `Bundle budget: PASS (initial JS 204158 / 206848 gzip bytes, 27 / 32 files)`. CSS 8.81 kB gzip |
|
||||
| `bbde570-ci/gate-artifacts/FE-GATE-020.txt`(CI env) | 드릴 `Bundle budget: PASS (initial JS 205465 / 206848 gzip bytes, 27 / 32 files)`(`:6206`). 드릴 기록 `{"gzipBytes":205465,"files":27,"perFeatureGzipBytes":765,"perContextGzipBytes":157}`(`:4414`). 제거 드릴 기록 `{"gzipBytes":205137,...}`(`:6309`). `feature scaffold: PASS (77 checks)` |
|
||||
| `bbde570-ci/gate-artifacts/FE-GATE-005.txt`(CI env) | 이 영역 unit 7파일 통과(1번째 실행 `:6`, `:18`, `:61`, `:71`, `:86`, `:256`, `:275`). unit 208파일 3,056건 28.45초, setup 50.73초(`:312-315`). coverage 332파일 85.50초(`:781-784`). SW runtime 64건 320 ms(`:119`) |
|
||||
| `bbde570-ci/gate-artifacts/FE-GATE-006.txt` | `starter-platform-overview-page.test.tsx` 11건 통과(`:15`) |
|
||||
| `bbde570-ci/gate-artifacts/FE-GATE-008.txt` | 시각 6건 통과(`:343-348`) |
|
||||
| `r5/snap/lab.txt`, `r5/snap/base/performance/lab.json`(로컬 env, 5회) | `Lab performance: PASS, median of 5 (LCP 2032ms, CLS 0, interaction 151ms [150-153], /examples/platform direct CLS 0 [0-0], feature route EXAMPLES_UI 402ms [400-408])`. 부하 0.70 → 0.73. `scrollbars: "visible"` |
|
||||
|
||||
## 7. 새 발견 요약
|
||||
|
||||
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|
||||
|---|---|---|---|---|
|
||||
| 15-01 | Low·P3 | 구조적 위험 | 초기 JS 예산 상향(D7)이 드릴 초과분 665 B의 세 배(2,048 B)를 올렸다. 폭의 근거와 다시 내릴 조건이 없어 다음 1,383 B는 어느 merge 게이트도 멈추지 않는다 | `config/performance/budgets.json:4`, `docs/operations/performance-evidence.md:44-53`, `tests/unit/performance-budgets.test.ts:106-136`(대조: 기능 라우트 예산은 묶임) |
|
||||
@@ -0,0 +1,205 @@
|
||||
# 영역 16 — 폴더 구조·리팩토링·기능 개발 패턴
|
||||
|
||||
> 검토일 2026-11-06 · 기준 `bbde570`(`fix/maturity-review-2026-11-05-b`, PR #7 끝) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
|
||||
> 경로: repo 구조 전체, `scripts/create-feature.ts`, `scripts/create-feature-write-slice.ts`, `scripts/test-feature-scaffold.ts`, `scripts/lib/feature-scaffold-drill.ts`, `scripts/test-sample-removal.ts`, `scripts/lib/feature-residue.ts`, `src/contracts/external-contract-runtime.ts`(descriptor 타입), `src/contracts/server-state.ts`(뮤테이션 ID), `config/contracts/backend-contract-pin.json`, `docs/manual/`, `docs/architecture/starter-experience.md`
|
||||
> 깊게 본 관점: 2, 3, 4, 9, 20, 21, 22, 23, 27
|
||||
> 렌즈: 기능 개발 경로를 처음부터 끝까지 따라간다. 생성(읽기 판, `--with-create` NEVER 판, `--with-create --keyed` 판) → 필수가 된 `responseEnvelope` → 기능과 함께 커밋하는 추적 파일 → 11단계 제품 기능 제거 드릴. 실행 증거는 오케스트레이터의 merge 단계 실행(`desktop:/tmp/claude-gates/bbde570-ci/`, CI env)과 이 영역의 배치 요청 16-R1~R4다.
|
||||
> 영역 판정(35.8): **조건부 사용 가능.** 생성 명령의 세 판이 모두 손 수정 없이 merge 명령을 돈다(FE-GATE-020 rc=0). 기능 작성자의 실수 자리 둘(응답 모양 줄 누락, 손으로 쓴 뮤테이션 ID)이 이제 `check:types`에서 막힌다. 조건은 넷이다. (1) 기능 ID가 템플릿 소스의 경로나 글자와 겹치면 11단계 제거 드릴이 템플릿 파일을 잔여로 잡는다. `product-feature`나 `-feature` 없는 짧은 ID(`search`, `profile`, `items`)를 고르지 않는다(1105/16-04 일부). (2) 기능 브랜치 둘은 dev manifest와 초기 JS 기록에서 충돌한다. 손으로 합치지 않고 03 A절의 명령을 다시 돌린다(1105/16-01, 충돌 제거는 결정 대기). (3) 템플릿 변경이 생성 기능의 브라우저 경로만 깨면 CI는 모른다(1105/16-03). (4) 기능을 지울 때 그 기능의 e2e spec은 손으로 지운다. 드릴은 spec 본문의 기능 ID를 더 이상 잔여로 세지 않는다(16-01).
|
||||
|
||||
## 0. 결론
|
||||
|
||||
- **지난 영역 발견 10건: 고쳐짐 5, 일부 2, 남음 3.** 고쳐짐: 1105/16-01, 16-02, 1103/16-01, 1103/16-05, 0929/12-03. 일부: 1105/16-04, 1103/16-06. 남음: 1105/16-03, 1101/16-05, 1101/16-06. 재발과 틀린 발견은 없다.
|
||||
- **§16과 다르게 본 것 둘.** 1105/16-01은 §16.4가 "일부"지만 완료 기준의 둘째 길(03 A절·정본 표가 두 파일과 충돌 처리 명령을 적는다)을 채웠다. 고쳐짐으로 본다. 충돌 자체는 남고 결정 대기다(`CHANGELOG.md:97`). 1105/16-04는 §16.4가 "고침"이지만 고친 것은 `tests` 쪽뿐이다. `src`는 여전히 대소문자 무시 부분 문자열 검색이다(`scripts/lib/feature-residue.ts:45-56`). 빌드 산출물 검사도 같은 넓은 패턴이다. 매뉴얼 예시 이름 `invoice-feature`의 쓰기 기능 제거는 이제 통과한다(16-R2 rc=0, `invoice-feature removal: PASS (17 checks, no fixture IDs)`). 그러나 `product-feature`는 실패한다(16-R3 rc=1). 잔여로 잡힌 것은 템플릿 `src` 13파일, `tests` 6파일, 빌드 파일 1개이고, 모두 템플릿 소유다. 지난 발견의 근거 ④가 이미 적은 부분이다. 그래서 일부로 본다.
|
||||
- **BREAKING 둘이 실수 자리를 타입으로 막는다.** `responseEnvelope`가 descriptor의 필수 칸이다(`src/contracts/external-contract-runtime.ts:239`). 뮤테이션 정책의 operation ID는 brand 타입 `MutationOperationId`이고 `commandMutationIdentity`만 만든다(`src/contracts/server-state.ts:276-278`, `:302`, `:319`). 두 테스트의 `@ts-expect-error`(`tests/unit/external-contract-runtime.test.ts:396`, `tests/unit/command-mutation-identity.test.ts:51`)가 쓰이지 않으면 `check:types:test`가 실패한다. merge 실행의 FE-GATE-003이 PASS이므로 두 타입 오류는 실제로 난다(E2). 생성기의 목록 GET 템플릿에서 줄을 뺀 변이(16-R1)를 돌렸다. 읽기만 있는 생성 기여였는데도 `check:types:app` rc=1이었다. 오류는 `invoice-contract-contribution.ts(69,4)` TS1360 `Property 'responseEnvelope' is missing ...`였다. 지난 라운드에 남았던 부분이 막혔다(E3).
|
||||
- **생성 경로 세 판이 모두 merge 명령을 돈다.** FE-GATE-020 rc=0(1,237초, CI env). 읽기 판과 KEYED 판: `feature scaffold: PASS (77 checks)`(FE-GATE-001~013의 merge 명령, `FE-GATE-003:check-types` 포함). NEVER 판: 참조 기능을 지운 사본에서 `scaffold-feature --with-create`를 만들고 같은 게이트를 돈다(`scripts/test-sample-removal.ts:499-510`, `reference-feature removal: PASS (31 checks, no fixture IDs)`). 생성 기능 제거: `scaffold-feature removal: PASS (17 checks, no fixture IDs)`. 다만 게이트가 지우는 것은 읽기 판 하나이고, 그 이름은 템플릿 파일에 없다. 게이트 밖에서 생성 쓰기 기능을 설치한 채 `test:a11y`를 돌렸다(16-R4 rc=0, 69건 통과). 생성 라우트 셋이 세 엔진에서 axe를 통과했다. 상세 라우트는 실패 화면으로만 검사해 `INVOICE_DETAIL not checked in its own state`로 따로 보고됐다. 다만 이 확인을 지키는 CI 장치는 여전히 없다(1105/16-03).
|
||||
- **추적 파일 둘의 문서가 맞다.** 03 A절 표(`docs/manual/03-outside-feature-folder.md:34-45`), 정본 표(`docs/architecture/starter-experience.md:223-224`), 01 1단계(`docs/manual/01-add-a-feature.md:106`, `:110`), 생성 출력(`scripts/create-feature.ts:1775-1778`)이 같은 두 파일과 다시 쓰는 명령을 말한다. `tests/unit/feature-tracked-files.test.ts`가 그 상수와 두 문서를 대조한다(FE-GATE-005 PASS).
|
||||
- **새 발견 2건, 모두 Low·P3.** 16-01: 1105/16-04를 고치면서 `tests`의 잔여 판정을 "파일 이름 또는 import"로 좁혔다. Playwright spec은 `test:all`이 돌지 않는데(`vitest.config.ts:45`), 매뉴얼은 "`test:all`이 실패한다"고 적는다(`docs/manual/01-add-a-feature.md:662`). 16-02: 계약 문서 4.1절의 bulk 안내가 아직 "`responseEnvelope`를 빼고"다(`docs/architecture/backend-api-and-server-state-contract.md:206-207`). 필수 칸과 한 기여 안 같은 값 규칙에 둘 다 어긋난다. 07 영역의 07-01과 같은 결함이다. 전체 집계에서는 07-01로 한 번만 센다.
|
||||
- **약해진 검사는 16-01 하나다.** 의도한 좁힘이고 커밋 본문(`b45d6a0`)과 매뉴얼이 적는다. 빈틈은 안전망으로 든 `test:all`이 Playwright spec을 돌지 않는다는 것이다. 그 밖에 이 영역 수정에서 지운 단언, 넓힌 예외, 새 skip은 찾지 못했다. 제거 드릴 사본의 문서 테스트 제외 4개 추가(`scripts/lib/removal-fixture.ts:73-80`)는 문서를 복사하지 않는 사본에서만 빠진다. 본 `test:unit`은 그대로 돈다. 초기 JS 예산 상향(`287dc6f`, D7)은 15 영역이 판정한다.
|
||||
|
||||
## 1. 범위 (36.1)
|
||||
|
||||
| 항목 | 기록 |
|
||||
|---|---|
|
||||
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` |
|
||||
| 커밋·작업 상태·확인 시점 | `bbde570`. 코드 읽기는 노트북 worktree(HEAD = 기준, 읽기만). 2026-11-06 04:00~ |
|
||||
| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음 |
|
||||
| 필수 요구와 규모·운영 목표 | 짝 백엔드(`clean-architecture-backend-template`, pin `45d2a478`, 읽기만)와 짝으로 쓴다. 생성 명령과 매뉴얼로 기능을 더하고, 템플릿 소유 파일을 손으로 고치지 않고, merge 게이트를 통과하고, 지울 때 제거 드릴이 통과한다. 기능 수 증가 외 정량 목표 없음 |
|
||||
| 읽은 코드·구성 범위 | `scripts/create-feature.ts`(1,837줄), `scripts/create-feature-write-slice.ts`(1,091줄), `scripts/test-feature-scaffold.ts`, `scripts/lib/feature-scaffold-drill.ts`, `scripts/test-sample-removal.ts`, `scripts/lib/feature-residue.ts`, `scripts/lib/removal-fixture.ts`, `scripts/lib/removable-template-features.ts`, `scripts/check-backend-contract-drift.ts`, `config/contracts/backend-contract-pin.json`, `.dependency-cruiser.json`(기능 규칙), `src/contracts/external-contract-runtime.ts`, `src/contracts/server-state.ts`, `tests/unit/{feature-tracked-files,feature-residue,command-mutation-identity,external-contract-runtime,backend-contract-pin,backend-contract-drift,create-feature}.test.ts`, `tests/helpers/mutation-operation-id.ts`, `docs/manual/01·03·reference/errors.md·reference/create-feature.md`, `docs/architecture/starter-experience.md` "Adding a feature", `docs/architecture/backend-api-and-server-state-contract.md` 4.1절, `CHANGELOG.md` 미출시 절, `vitest.config.ts`, `tsconfig.test.json`, `package.json` scripts. 백엔드 pin 커밋의 생성기 템플릿 여섯 파일 존재(`git -C <backend> cat-file -e 45d2a478:<path>`), pin과 백엔드 HEAD `3d73b6f1` 사이 그 파일과 `docs/web/http-contract.md`의 diff(없음). `git diff 8a44226..bbde570`의 이 영역 경로와 수정 커밋 `6d084cf`, `f600e6b`, `b45d6a0`, `56272e8`, `48c1ab7`, `a37ebba` 본문 |
|
||||
| 수행한 테스트·실험 | 실행 환경 = desktop 로그와 스냅숏. merge 단계 실행 `bbde570-ci`(CI env, 2026-11-06 03:24~03:56): `summary.txt`, `FE-GATE-NNN.log`, `gate-artifacts/FE-GATE-005·010·012·020.txt`. 스냅숏 `r5/snap/merge/artifacts/tests/feature-scaffold.xml`(03:40, 77건 실패 0). `r5/snap/verify-documentation.local.txt`·`.no-sibling.txt`(둘 다 `PASS_SCOPED`). 이 영역 요청은 오케스트레이터 배치 16-R1~R4다(04:24~04:32, 항목마다 restore clean, 로그 `r5/batch/out/R5-16-R1~R4.log`, 6절) |
|
||||
| 확인하지 못한 범위·이유 | 실제 Gitea 러너, FE-GATE-013의 `test:system`(이 호스트에 user namespace 없음, 12 영역), 두 기능 브랜치의 실제 `git merge`, 매뉴얼만 보는 사람·에이전트의 재실험, 실제 짝 백엔드 연결, 생성 기능 설치 상태의 FE-GATE-008(5절) |
|
||||
| 이전 리뷰와 비교 가능한 범위 | `docs/reviews/2026-11-05-maturity-review/16-structure-patterns.md`의 16-01~16-04, 같은 폴더 README §16.5의 1103/16-01·16-05·16-06, §16.6의 1101/16-05·16-06, 지난 영역 문서 2.2절의 0929/12-03. 지난 실행 결과(`16-mut`, 16-R1)는 증거로 쓰지 않았다 |
|
||||
|
||||
## 2. 지난 발견 재확인
|
||||
|
||||
README §16.4~16.6의 상태는 주장으로 보고, 각 발견의 지난 완료 기준을 `bbde570`의 코드와 실행 결과에 대어 다시 판정했다.
|
||||
|
||||
### 2.1 1105 영역 16 발견 (README §15)
|
||||
|
||||
| 지난 ID | 내용 | 상태 | 근거 (`bbde570`) |
|
||||
|---|---|---|---|
|
||||
| 1105/16-01 | 기능 하나를 더하면 추적 파일 둘이 바뀌고, 문서는 말하지 않으며, 기능 브랜치 둘이 같은 줄에서 충돌한다 | **고쳐짐**(완료 기준 둘째 길). §16.4는 "일부" | 완료 기준은 "추적 파일이 없다. **또는** 03 A절·정본 표가 두 파일과 충돌 처리 명령을 적는다"였다. 둘째를 채웠다. ① 03 A절 표가 두 파일, 누가 쓰나, 다시 쓰는 명령, 안 넣으면 무엇이 실패하나를 적는다(`docs/manual/03-outside-feature-folder.md:36-41`). 충돌 처리("아무 쪽이나 고른 뒤 명령을 다시 돌린다")는 `:43-44`다. ② 정본 표 두 행이 같은 명령과 "merge conflict"를 적는다(`docs/architecture/starter-experience.md:223-224`). ③ 01 1단계 흐름에 manifest 재작성 줄이 있다(`docs/manual/01-add-a-feature.md:106`, `:110`). ④ "기능을 지울 때"가 초기 JS 기록 재작성도 말한다(`03-outside-feature-folder.md:215`). ⑤ 생성 출력이 상수 `FEATURE_TRACKED_FILE_REWRITES`(`scripts/create-feature.ts:1703-1714`)로 충돌 줄을 쓴다(`:1777-1778`). FE-GATE-020 로그에 그 줄이 나온다(`gate-artifacts/FE-GATE-020.txt:1535-1537`). ⑥ `tests/unit/feature-tracked-files.test.ts:24-57`이 상수의 경로·명령이 03 A절과 정본 표에 있는지 본다. FE-GATE-005 PASS. 남은 것(완료 기준 밖): 충돌 자체. 대안 (b)·(d)는 결정 대기다(`CHANGELOG.md:97`). 참고: 참조 기능을 지운 다운스트림에서도 생성 출력의 충돌 목록이 없는 파일(`config/scale/feature-shape-ceilings.json`)을 든다(`create-feature.ts:1778`, 조건 없음). 3번 줄은 "있는 동안"이라고 조건을 단다(`:1775`). 해가 없어 세지 않는다 |
|
||||
| 1105/16-02 | 쓰기 slice가 백엔드 생성기 템플릿의 사실 넷을 옮겼는데 pin·drift 검사는 `http-contract.md`만 본다 | **고쳐짐** | pin에 `backend.scaffoldSources` 여섯 항목이 있다. 항목마다 백엔드 파일, 옮긴 사실, 옮긴 프론트 파일과 이름을 적는다(`config/contracts/backend-contract-pin.json:8-39`). drift 검사가 pin 뒤 HEAD에서 그 파일마다 diff를 보고, 바뀌면 다시 볼 프론트 위치를 말하며 1로 끝난다(`scripts/check-backend-contract-drift.ts:169-180`). 완료 기준("네 사실 중 하나가 바뀌면 drift 검사가 알린다")은 `tests/unit/backend-contract-drift.test.ts:314-331`이 가짜 백엔드의 `NAME_MAX_LENGTH = 120` 변경으로 본다(FE-GATE-005 PASS). `tests/unit/backend-contract-pin.test.ts:187-205`가 각 항목의 프론트 이름이 그 파일에 있는지 본다. 여섯 백엔드 경로는 pin 커밋에 모두 있고, pin과 백엔드 HEAD `3d73b6f1` 사이에 바뀌지 않았다(직접 확인). 남은 한계(설계): drift 검사는 게이트 밖이고 옆 checkout이 있을 때만 돈다(`CHANGELOG.md:105`). 참고: 문서 경로는 pin 커밋에 없으면 "비교 못 함"(rc=2)이지만(`check-backend-contract-drift.ts:119-122`), `scaffoldSources` 경로는 존재를 보지 않는다. 경로를 틀리게 적으면 그 항목은 늘 "바뀌지 않음"이다. 지금은 여섯 경로가 맞아 세지 않는다 |
|
||||
| 1105/16-03 | 생성 기능을 설치한 상태로 브라우저 merge 게이트를 도는 장치가 없다 | **남음**(결정 대기) | 드릴의 제외 목록이 그대로다(`scripts/lib/feature-scaffold-drill.ts:18-46`, `8a44226` 뒤 변경 없음). 생성 출력도 "브라우저 게이트 FE-GATE-008/009와 test:system 밖"이라고 적는다(`gate-artifacts/FE-GATE-020.txt:1530`). merge 실행의 FE-GATE-008(196초)·009(51초) PASS는 템플릿 원래 상태다. 그 사이 생성 라우트의 화면이 바뀌었다(`90c489c` 확인 뒤 목록 열기, `f2b8ba7` 다른 저장 진행 중 표시, `757d1c7` a11y.json schema 2). 지금 그 경로가 통과하는지는 16-R4로 따로 확인했다(CIENV, rc=0). `/invoice`, `/invoice/items/a11y-1`, `/invoice/new` × chromium·firefox·webkit이 모두 통과했고, 전체는 69건 통과(58.3초)였다. `INVOICE_DETAIL`은 `not checked in its own state (scanned on its failure state only ...)`로 보고됐다. 참조 기능 상세와 같은 처리다. 통과한다는 사실과 별개로, 이 통과를 지키는 CI 장치는 없다. §16.4의 결정 대기와 같다 |
|
||||
| 1105/16-04 | 제품 기능 제거 드릴의 잔여 검사가 템플릿 테스트의 글자를 잔여로 잡는다 | **일부**. §16.4는 "고침" | 고친 것: `tests`는 파일 이름에 ID가 있거나 기능 폴더에서 import하는 파일만 잔여다(`scripts/lib/feature-residue.ts:46-60`, 호출 `scripts/test-sample-removal.ts:428-431`). 저장소 자체를 `invoice-feature`로 훑으면 잔여 0이다(`tests/unit/feature-residue.test.ts:40-42`, FE-GATE-005 PASS). 안내도 "템플릿 파일이 나오면 고치지 말고 템플릿에 알린다"로 바뀌었다(`docs/manual/reference/errors.md:199`). 완료 기준 첫째는 충족했다. 16-R2(CIENV)에서 `create:feature invoice-feature --with-create --keyed` 뒤 `test:sample-removal -- --feature=invoice-feature`가 rc=0이었다. 결과는 `invoice-feature removal: PASS (17 checks, no fixture IDs)`, `Risk coverage: PASS (418/418 production modules, 72 thresholds)`였다. 완료 기준 둘째(`src`에 ID를 남기면 실패)는 단위 테스트가 본다(`feature-residue.test.ts:44-60`의 `src/contracts/leftover.ts`, E2). 남은 것: `src`는 여전히 기능 ID·폴더 이름의 대소문자 무시 부분 문자열을 경로와 본문 전체에서 찾는다(`feature-residue.ts:45`, `:53-56`). 지난 발견의 근거 ④("경계 없는 부분 문자열이라 짧은 ID는 더 많은 파일에 걸린다")가 적은 부분이고, 커밋 본문도 "이번 범위 밖"이라 적었다(`b45d6a0`). 예: ID `product-feature`(KEBAB 규칙 `scripts/create-feature.ts:110`에 맞고 예약 이름이 없다)는 템플릿 `src` 추적 파일 10개에 걸린다(`git grep -il`). 경로가 걸리는 2개(`src/contracts/product-features.ts`, `src/application/ports/product-features-port.ts`), 그 둘을 import하는 4개, 생성 색인 `../.generated/product-feature-index.ts`를 import하는 `src/features/installed-product-manifest.ts:5`, 글자로 걸리는 3개(`src/contracts/env.ts:82`의 스크립트 이름, `src/features/local-draft-feature/NOT_A_FEATURE:3`, `src/presentation/examples/platform-overview-page.tsx:654`의 `data-product-feature`)다. 드릴 사본에는 생성 색인 파일 자신도 있다. `tests`에서는 파일 이름 6개(`tests/unit/product-feature-selection-build.test.ts` 등)가 걸린다. `-feature` 없는 ID도 허용되는데(`create-feature.ts:137`), `search`는 `src` 38파일, `profile` 31, `items` 30, `account` 21, `home` 15파일에 걸린다(`git grep -il`). 16-R3(CIENV)에서 `product-feature`로 실행했다. `create:feature product-feature`는 통과했고, 11단계 드릴은 rc=1이었다. 실패는 잔여 검사 둘뿐이고 다른 검사는 모두 통과했다. ① `fixture-id-residue`: `src` 13파일. 위 10개에 생성 파일 `src/.generated/product-app.ts`, `product-context-index.ts`, `product-feature-index.ts`가 더해졌다. `tests` 6파일. ② `built-fixture-id-residue`: `dist/assets/platform-overview-page-*.js`. `data-product-feature` 속성이 빌드에 남아서다. 빌드 잔여 검사는 1105/16-04 수정 전의 넓은 패턴을 그대로 쓴다(`scripts/test-sample-removal.ts:113-116`, `:467-475`). 잡힌 20개는 모두 템플릿 소유다. 안내(`errors.md:199`)를 따르면 "템플릿에 알린다"에서 멈춘다 |
|
||||
|
||||
### 2.2 1103 이월 (README §16.5, 이 영역)
|
||||
|
||||
| 지난 ID | 내용 | 상태 | 근거 (`bbde570`) |
|
||||
|---|---|---|---|
|
||||
| 1103/16-01 | Envelope를 operation마다 선언하고, 빠뜨려도 게이트가 통과한다 | **고쳐짐** | `contract.responseEnvelope`가 필수 칸이다(`src/contracts/external-contract-runtime.ts:231-239`). 생성기의 세 descriptor는 모두 `satisfies InstalledHttpContract<...>`다(`scripts/create-feature.ts:820`, `scripts/create-feature-write-slice.ts:295`, `:349`). 그래서 줄을 빼면 그 자리에서 tsc가 실패한다. 읽기만 있는 기여에서 모두 빼는 경우(지난 라운드 남은 부분)도 같다. 증거는 둘이다. ① `tests/unit/external-contract-runtime.test.ts:394-404`의 `@ts-expect-error`가 merge 실행 FE-GATE-003 PASS에서 쓰였다(E2). ② 지난 검증 방법(E-1)을 생성 기능으로 다시 했다(16-R1, E3). 생성기의 목록 GET 템플릿에서 줄을 지우고(`requests/16-R1.diff`, `scripts/create-feature.ts:800`) `create:feature invoice-feature`를 돌렸다. 기여는 읽기 하나뿐이고 줄이 하나도 없었다. 생성은 통과했고 `check:types:app`은 rc=1이었다. 오류는 둘이다. `invoice-contract-contribution.ts(69,4)`의 TS1360 `does not satisfy ... Property 'responseEnvelope' is missing in type ...`, 그리고 `(83,11)`의 기여 배열 cast TS2352다. 변이 없는 대조는 FE-GATE-020 `FE-GATE-003:check-types` PASS다(같은 템플릿의 읽기 판 `scaffold-feature`). 완료 기준 둘째("매뉴얼 3단계와 예시에 이 줄이 있다"): `docs/manual/01-add-a-feature.md:213-216`, 예시 `:280`, `:290`, 감싸지 않는 백엔드 안내 `:240`, 오류표 `docs/manual/reference/errors.md:109`. 참조 기능 셋은 `"NONE"`을 적는다(`src/features/reference-feature/contracts/reference-feature-contract-contribution.ts:91`, `:146`, `:197`). CHANGELOG "먼저 할 일" 1이 이행을 적는다(`CHANGELOG.md:24`). 남은 것(설계, 매뉴얼 "못 잡음"): 모든 operation에 같은 틀린 값. 조립은 빠진 값을 여전히 `NONE`으로 읽는다(`external-contract-runtime.ts:715-716`). 같은 절의 bulk 안내가 낡았다: 새 16-02(= 07-01) |
|
||||
| 1103/16-05 | 뮤테이션 정책 `operationId`가 자유 문자열이다 | **고쳐짐** | `BoundMutation.operationId`가 `MutationOperationId`다(`src/contracts/server-state.ts:276-278`, `:319`). 이 값을 내는 곳은 `commandMutationIdentity` 하나다(`:302`, `:310`). 완료 기준("E-2의 오타가 `check:types`에서 실패")은 `tests/unit/command-mutation-identity.test.ts:49-60`의 `@ts-expect-error`가 FE-GATE-003 PASS에서 쓰인 것으로 본다(E2). 생성 쓰기 slice(`scripts/create-feature-write-slice.ts:511`)와 참조 기능(`src/features/reference-feature/presentation/use-reference-feature.ts:60`)이 helper를 펼친다. FE-GATE-020의 KEYED 판이 `FE-GATE-003:check-types`를 통과한다. 남은 것(매뉴얼 "못 잡음", `docs/manual/01-add-a-feature.md:499-500`): descriptor 대신 손으로 만든 객체를 helper에 넘기는 것. 그때 위반 이름은 여전히 `MISSING_IDEMPOTENCY_KEY`다 |
|
||||
| 1103/16-06 | 반드시 채우는 칸 중 아무도 읽지 않는 칸 | **일부**(지난 라운드와 같음, 결정 대기) | 쿼리 `owner`·`operationId`, 뮤테이션 `owner`는 `@deprecated` 선택 칸이다(`src/contracts/server-state.ts:178-184`, `:322`). 라우트 계약 `title`·`navigationLabel`은 화면이 읽지 않는데 생성기가 채운다(`scripts/create-feature.ts:582-583`, `scripts/create-feature-write-slice.ts:134-135`). 매뉴얼이 그렇게 적는다(`docs/manual/01-add-a-feature.md:409`) — M1. §16.5의 결정 대기와 같다 |
|
||||
|
||||
### 2.3 그 밖의 이월 (README §16.6, 지난 영역 문서 2.2절)
|
||||
|
||||
| 지난 ID | 내용 | 상태 | 근거 |
|
||||
|---|---|---|---|
|
||||
| 1101/16-05 (R-6, R-7) | 같은 개념이 두 폴더에 | **남음** | 오류 경계 두 벌(`src/presentation/boundaries/render-error-boundary.tsx`, `src/platform/errors/feature-error-boundary.tsx`), `TelemetryPort` 두 타입(`src/platform/telemetry/telemetry-port.ts:10`, `src/application/ports/telemetry-port.ts:5`), 폐기 재수출(`src/application/result.ts:9`). 이 경로들에 `8a44226..bbde570` 커밋이 없다. §16.6 "남김(작지 않음)"과 같다 |
|
||||
| 1101/16-06 (R-8) | 기능 `contracts/`가 와이어 계약·문구·뷰 타입을 함께 담는다 | **남음** | 생성기가 `contracts/<base>-mapper.ts`, `contracts/<base>-message-catalog.ts`를 쓴다(`docs/manual/reference/create-feature.md:50-53`, `gate-artifacts/FE-GATE-020.txt:1502`, `:1505`). §16.6과 같다 |
|
||||
| 0929/12-03 | 기능 안 계층 밖 폴더와 `contracts/`를 거친 어댑터 import에 규칙이 없다 | **고쳐짐**(대표 판정은 12 영역) | 규칙의 출발 경로가 "기능의 `adapters/` 밖 `src/features` 전체"다(`.dependency-cruiser.json:306-307`). `support/`·`contracts/`의 파일이 `src/adapters`를 import하면 위반이다. 그래프 회귀 fixture에 `support/` 재수출 거절이 들었다(`scripts/check-architecture.ts:823-831`). merge 실행 FE-GATE-010 `Architecture graph fixtures: 31 regression checks PASS`(지난 라운드 29). 파일 단위 예외는 기존 하나(`feature-adapter-contribution.ts`, type only) 그대로다. 생성 기능 둘이 설치된 드릴의 `FE-GATE-010:check-architecture`도 통과했다(`feature-scaffold.xml`) |
|
||||
|
||||
0929/08-06은 1103/16-06에 합쳐졌다(위 행). README §14.7의 `BUILD_INPUTS` 두 벌은 1105/15-03(15 영역)이다.
|
||||
|
||||
### 2.4 다른 영역 발견에 이 영역이 더한 증거
|
||||
|
||||
| 발견 | 이 영역이 더한 증거 |
|
||||
|---|---|
|
||||
| 1101/15-01 초기 JS 여유(15 영역) | merge 실행 FE-GATE-012: 템플릿 204,158 / 206,848 B, 27 / 32 파일(`gate-artifacts/FE-GATE-012.txt`). 같은 실행의 생성 드릴: 새 context의 기능 둘(읽기, KEYED)을 더한 뒤 205,465 B, 27 파일, `Bundle budget: PASS`(`FE-GATE-020.txt:6206`). 둘이 1,307 B, 하나 약 650 B다. 남은 여유는 1,383 B다. 같은 크기면 기능 넷째쯤에서 넘는다(추론. 기능 모양과 context 선택에 따라 다르다). 기록의 `perFeatureGzipBytes` 768 B는 참조 기능 사본의 값이다(`config/scale/feature-shape-ceilings.json:41-46`). 예산 상향(D7)의 판정은 15 영역이다 |
|
||||
| 1105/03-01 플랫폼 code의 `refusedBeforeWrite` 거절(03 영역) | 생성 쓰기 slice는 `<FEATURE>_INVALID` 하나만 적는다. 플랫폼 목록(`src/contracts/external-contract-runtime.ts:638-659`)과 겹치지 않는다. 기능 이름이 `bad-request`여도 `BAD_REQUEST_INVALID`라 겹치지 않는다. FE-GATE-020의 두 쓰기 판이 조립을 통과한다 |
|
||||
|
||||
## 3. 이번 발견 (36.3)
|
||||
|
||||
집계: Low 2 · P3 2 · 구조적 위험 1 · 확인된 결함 1. High 이상과 P1은 없다. 16-02는 07 영역 07-01과 같은 결함이다. 전체 집계에서는 07-01로 한 번만 세고, 이 영역에서는 같은 결함으로 적어 둔다. 그래서 이 영역에만 있는 새 발견은 16-01 하나다. 1105/16-04의 남은 부분은 옛 ID로 2.1절에 두고 세지 않았다.
|
||||
|
||||
| ID | 제목 | 성격 | 심각도·우선순위 | 관련 관점 |
|
||||
|---|---|---|---|---|
|
||||
| 16-01 | 제품 기능 제거 드릴이 `tests` 잔여를 "파일 이름·import"로 좁혔다. 안전망으로 든 `test:all`은 Playwright spec을 돌지 않아, spec 본문에 남은 기능 ID를 아무 검사도 잡지 않는다 | 구조적 위험 (검사 약화, 문서 불일치 포함) | Low · P3 | 21, 10, 27, 8 |
|
||||
| 16-02 (= 07-01) | 계약 문서 4.1절의 bulk 안내가 "`responseEnvelope`를 뺀다"로 남아, 필수 칸과 한 기여 안 같은 값 규칙에 어긋난다 | 확인된 결함 (문서 불일치) | Low · P3 | 23, 17, 4 |
|
||||
|
||||
### 16-01 제품 기능 제거 드릴의 `tests` 잔여 판정이 좁아졌는데, 안전망으로 든 `test:all`은 Playwright spec을 돌지 않는다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 구조적 위험 (1105/16-04 수정이 만든 검사 약화. 매뉴얼·주석의 틀린 문장 포함) |
|
||||
| 관련 관점 | 21, 10, 27, 8 |
|
||||
| 근거 | ① 전: 제품 기능의 잔여는 `src`·`tests` 모든 파일의 경로와 본문에서 기능 ID를 찾았다(`8a44226:scripts/test-sample-removal.ts:113-120`, `:417-425`). ② 지금: `tests`는 파일 이름에 ID가 있거나, `from`·`import(`·`import `·`mock(` 뒤 문자열이 `/features/<id>/`를 가리킬 때만 잔여다(`scripts/lib/feature-residue.ts:46-50`, `:57-60`). ③ 주석과 매뉴얼은 빠진 경우를 `test:all`이 잡는다고 적는다. "A test that still depends on the removed feature fails `test:all`"(`feature-residue.ts:18-20`). "그 테스트가 지운 기능에 기대면 같은 드릴의 `test:all`이 실패한다"(`docs/manual/01-add-a-feature.md:662`). 커밋 본문도 같다(`b45d6a0` "위험·한계"). ④ 그런데 `test:all`은 vitest 묶음이다(`package.json:85`). vitest는 `tests/**/*.test.{ts,tsx}`만 돈다(`vitest.config.ts:45`). `tests/e2e/*.spec.ts`는 돌지 않는다. 드릴의 다른 단계(타입·lint·아키텍처·레지스트리·커버리지·빌드, `scripts/test-sample-removal.ts:441-461`)도 spec을 실행하지 않는다. `check:types`는 spec을 컴파일하지만(`tsconfig.test.json:7-12`) URL만 쓰는 spec은 컴파일된다. ⑤ 그래서 기능 ID를 본문에만 담은 spec(예: `tests/e2e/invoice.spec.ts`에 `test.describe("invoice-feature", …)`와 `page.goto("/invoice")`)은 전에는 잔여였고 지금은 아무 검사도 잡지 않는다. 03 문서는 기능 전용 e2e spec을 손으로 지울 목록에 둔다(`docs/manual/03-outside-feature-folder.md:210`). 기능 ID를 파일 이름에 넣은 spec(`tests/e2e/invoice-feature.spec.ts`)은 여전히 잡는다(`tests/unit/feature-residue.test.ts:48`, `:56`) |
|
||||
| 발생 조건 | 다운스트림이 기능 전용 e2e spec(또는 visual·storybook spec)을 기능 ID가 아닌 이름으로 두고, 본문에 기능 ID를 적은 뒤 기능을 지울 때 |
|
||||
| 영향 | 11단계 드릴이 통과한다. 남은 spec은 지운 라우트를 열다가 다음 CI의 FE-GATE-008에서 실패한다. 사용자 피해는 없다. 원인은 실패한 spec이 말해 준다 |
|
||||
| 심각도·우선순위 | Low · P3 — 피해가 없고 merge 게이트가 결국 잡는다. 빠지는 범위도 좁다(본문에만 ID가 있는 비-vitest 파일). 다만 문서가 든 안전망이 그 경우를 덮지 않는다 |
|
||||
| 통제·증거 | 목표 M3(지운 기능을 가리키는 파일을 드릴이 잡는다). 확인 M3(파일 이름·import, 단위 테스트 `feature-residue.test.ts:44-60`) · 본문만 가리키는 비-vitest 파일은 M0 · 문서 M1(틀린 문장) · E1(코드 정적 확인) |
|
||||
| 확실성과 남은 가정 | 정규식, vitest include, `test:all` 구성은 코드로 확인했다. 실행으로 재현하지 않았다. 다운스트림이 spec 본문에 기능 ID를 얼마나 적는지는 모른다. 템플릿 자신의 e2e spec에는 기능 ID 글자가 없다(`git grep reference-feature tests/e2e` 0건) |
|
||||
| 결정의 근거 | 확인한 사실: 좁힌 이유는 템플릿 테스트가 예시 ID를 데이터로 쓰는 거짓 양성이다(1105/16-04). 커밋은 "제거 전 이미 걸리던 파일 제외"를 버렸다. `src/contracts`에 남긴 진짜 잔여도 제거 전부터 ID를 담으므로 같이 빠진다는 이유다(`b45d6a0`). 리뷰어 추론: 거짓 양성의 원인 파일은 모두 vitest 파일이다(`tests/unit/create-feature.test.ts` 등). 실행되지 않는 파일만 본문 검색을 남기면 거짓 양성 없이 빈틈이 닫힌다 |
|
||||
| 이해 비용 | 기능을 지우는 사람이 "드릴이 통과했으니 남은 것이 없다"고 믿는다. 03 손 목록의 e2e spec 줄을 따로 기억해야 한다 |
|
||||
| 최소 개선 방향 | 대안 (b) 또는 (a) |
|
||||
| 대안 비교 | (a) 문서만 고친다. 매뉴얼 01:662와 주석에 "Playwright spec은 `test:all`이 돌지 않는다. 본문에만 ID가 있는 spec은 손 목록(03:210)으로 지운다"를 적는다. 가장 싸다. (b) `tests` 중 vitest가 돌지 않는 파일(`*.spec.ts`, `tests/e2e/**`, `tests/visual/**`)에는 본문 검색을 남긴다. 템플릿 자신의 spec에는 기능 ID 글자가 없어 거짓 양성이 다시 나지 않는다. 드릴 수십 줄. (c) 현상 유지. (b) 권장 |
|
||||
| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다 |
|
||||
| 비용·부작용 | (b)는 `feature-residue.ts`에 조건 하나와 단위 테스트 한 건. 다운스트림 spec이 무관한 이유로 기능 ID 글자를 담으면 거짓 양성이 생길 수 있다 |
|
||||
| 재검토 조건 | 드릴이 브라우저 테스트를 돌게 되면 본문 검색이 필요 없어진다 |
|
||||
| 완료 기준 | 본문에만 기능 ID를 담은 `tests/e2e/<other>.spec.ts`를 남긴 변이에서 11단계 드릴이 실패한다. `invoice-feature` 제거(16-R2)는 계속 통과한다. 또는 매뉴얼 01:662와 주석이 이 경우를 "못 잡음"으로 맞게 적는다 |
|
||||
| 검증 방법 | `create:feature invoice-feature` 뒤 위 spec을 더하고 `test:sample-removal -- --feature=invoice-feature` |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
| 재검증 결과 | 해당 없음 |
|
||||
|
||||
### 16-02 (= 07-01) 계약 문서 4.1절의 bulk 안내가 "`responseEnvelope`를 뺀다"로 남았다 — 필수 칸과 한 기여 안 같은 값 규칙에 둘 다 어긋난다
|
||||
|
||||
07 영역이 같은 줄을 07-01로 적었다. 같은 결함이다. 오케스트레이터는 07-01로 한 번만 센다. 아래 표는 이 영역(1103/16-01 BREAKING의 문서 경로)에서 본 근거다.
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함 (문서 불일치). 07-01과 같은 결함 |
|
||||
| 관련 관점 | 23, 17, 4 |
|
||||
| 근거 | ① 문장: "bulk 엔드포인트를 붙이려면 `responseEnvelope`를 빼고 기능 스키마가 본문 전체를 읽는다"(`docs/architecture/backend-api-and-server-state-contract.md:205-207`, `49a0986`). ② 이 칸은 이제 필수다(`src/contracts/external-contract-runtime.ts:239`). 빼면 `check:types`가 실패한다. 같은 절 몇 줄 위가 그렇게 적는다(`:195-198`, `56272e8`이 고친 줄). 매뉴얼도 "줄은 빼지 않는다"고 적는다(`docs/manual/01-add-a-feature.md:214`, `:240`). ③ 빼는 대신 `"NONE"`을 적어도, 같은 기여의 다른 operation이 `ENVELOPE_V1`이면 조립이 거절한다(`external-contract-runtime.ts:715-716`의 비교, 오류표 `docs/manual/reference/errors.md:108`). bulk 엔드포인트는 짝 백엔드 것이라 보통 같은 패키지에 있다. 문장은 기여를 나누라고 말하지 않는다. ④ `56272e8`은 같은 4.1절을 고쳤지만 이 문장은 남겼다 |
|
||||
| 발생 조건 | 짝 백엔드의 bulk 엔드포인트를 붙이려고 이 문서를 따를 때 |
|
||||
| 영향 | 따르면 `check:types`가 실패하고, `"NONE"`으로 바꾸면 조립이 거절한다. 두 오류 모두 문구와 오류표가 원인을 말한다. 사용자 피해는 없다 |
|
||||
| 심각도·우선순위 | Low · P3 — 문서 한 문장이고, 따르면 바로 분명한 오류가 난다 |
|
||||
| 통제·증거 | 목표 M1(문서가 코드와 맞다). 확인 M1(틀린 문장) · E1 |
|
||||
| 확실성과 남은 가정 | 확정. bulk 엔드포인트를 실제로 붙여 보지 않았다 |
|
||||
| 결정의 근거 | 적용 제외 — 낡은 문장 한 줄을 고치는 문제다 |
|
||||
| 이해 비용 | 계약 문서를 정본으로 읽는 사람이 매뉴얼과 다른 안내를 받는다 |
|
||||
| 최소 개선 방향 | "bulk 엔드포인트는 `responseEnvelope: "NONE"`인 기여로 나누고, 기능 스키마가 Envelope 전체를 읽는다. 그러면 Envelope 실패 판정(6.1 표)을 그 operation에서 잃는다"로 고친다 |
|
||||
| 대안 비교 | 적용 제외 — 단순 결함 수정 |
|
||||
| 단순화의 보존 조건 | 적용 제외 |
|
||||
| 비용·부작용 | 문서 한 문장 |
|
||||
| 재검토 조건 | 적용 제외 |
|
||||
| 완료 기준 | 4.1절에 "`responseEnvelope`를 뺀다"는 안내가 없고, bulk 안내가 기여 나누기와 `"NONE"`을 말한다 |
|
||||
| 검증 방법 | `git grep -n "responseEnvelope\`를 빼" docs` 0건 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규(07-01과 같은 결함, 07-01로 센다) |
|
||||
| 재검증 결과 | 해당 없음 |
|
||||
|
||||
## 4. 28개 관점 판정 (36.2)
|
||||
|
||||
판정: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역.
|
||||
|
||||
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | 코드 성숙도 | > 07·09. 생성 기능은 도메인 규칙이 없어 `domain/`을 만들지 않는다 | — | E1 | > |
|
||||
| **2** | **구조적 성숙도** | 적용(깊게) | M4 / M3 | E2 | **P** — 기능 안 계층 밖 폴더와 `contracts/`를 거친 어댑터 접근을 그래프 규칙이 막는다(0929/12-03 고쳐짐, FE-GATE-010 fixture 31). 같은 개념 두 벌(1101/16-05)과 기능 `contracts/`의 세 역할(1101/16-06)은 남음 |
|
||||
| **3** | **변경 용이성** | 적용(깊게) | M4 / M4(부분) | E2 | **P** — 응답 모양 줄과 뮤테이션 ID가 descriptor에서 오고, 빠뜨리거나 손으로 쓰면 tsc가 막는다(1103/16-01·16-05 고쳐짐). 기능마다 다시 쓰는 추적 파일 둘은 문서와 검사가 있으나 브랜치 충돌은 남는다(1105/16-01 완료 기준 밖) |
|
||||
| **4** | **인지 부하** | 적용(깊게) | M1 / M1 | E1 | **P** — 생성 뒤 할 일(추적 파일, 충돌 처리)이 출력·01·03·정본 표에서 같다. 읽지 않는 라우트 `title`·`navigationLabel` 칸은 남는다(1103/16-06). 계약 문서의 bulk 안내가 매뉴얼과 다르다(16-02) |
|
||||
| 5 | 위험 가시성 | 적용 | M4 / M4 | E3 | P — 기여 전체에서 Envelope 줄이 빠져도 tsc 오류다. 생성 읽기 기여 변이에서 TS1360이 났다(16-R1). 모든 operation에 같은 틀린 값을 적는 경우는 매뉴얼에 "못 잡음"으로 적혀 있다 |
|
||||
| 6 | 실패 성숙도 | > 03·07 | — | E1 | > |
|
||||
| 7 | 운영 성숙도 | - 이 영역 밖 | — | — | - |
|
||||
| 8 | 디버깅 가능성 | 적용 | M2 / M2 | E1 | P — tsc 오류와 오류표(`errors.md:109`)가 Envelope 누락을 말한다. 제거 드릴 잔여의 안내가 "템플릿 파일이면 알린다"로 맞게 바뀌었다(`errors.md:199`). 손으로 만든 객체를 helper에 넘긴 ID 불일치는 여전히 `MISSING_IDEMPOTENCY_KEY`다. 16-01의 빈틈은 다음 CI의 e2e 실패로 드러난다 |
|
||||
| **9** | **유지보수 성숙도** | 적용(깊게) | M3 / M3(수동) | E2 | **P** — 백엔드 생성기 사실의 사본 여섯이 pin과 drift 검사에 묶였다(1105/16-02 고쳐짐. 검사는 게이트 밖). 1101/16-05의 두 벌은 그대로. 생성기 두 파일이 2,928줄로 늘었다(전 2,857). FE-GATE-020이 생성 결과를 merge 명령으로 돌아 drift를 잡는다 |
|
||||
| 10 | 테스트 성숙도 | 적용 | M3 / M3(부분) | E3 | P — 읽기·NEVER·KEYED 세 판이 merge 명령을 돈다(FE-GATE-020). 설치 상태의 브라우저 게이트는 CI가 돌지 않는다(1105/16-03). 이번 커밋에서는 손으로 돌려 통과했다(16-R4 `test:a11y` 69건). 제품 기능 제거 드릴의 `tests` 범위가 좁아졌다(16-01) |
|
||||
| 11 | 데이터 성숙도 | > 05 | — | — | > |
|
||||
| 12 | 동시성 성숙도 | > 03 | — | — | > |
|
||||
| 13 | 확장성 | 적용(기능 수 축) | M3 / M3 | E2 | P — 기능당 초기 JS를 기록과 상한으로 막는다. 생성 기능 둘을 더한 뒤 여유 1,383 B(FE-GATE-020). 같은 크기면 넷째쯤 예산 결정이 필요하다(추론, 15 영역) |
|
||||
| 14 | 성능 성숙도 | > 15 | — | E2 | > |
|
||||
| 15 | 보안 성숙도 | > 03·13 | — | — | > |
|
||||
| 16 | 의존성 성숙도 | > 12·13 | — | — | > |
|
||||
| 17 | API / Contract | 적용 | M4 / M4(부분) | E2 | P — `responseEnvelope` 필수, 한 기여 안 같은 값은 조립이 거절, 백엔드 생성기 사본은 pin(수동 검사). 계약 문서 bulk 안내가 낡았다(16-02) |
|
||||
| 18 | 배포 성숙도 | > 13 | — | — | > |
|
||||
| 19 | 설정 성숙도 | 적용(일부) | M1 / M1 | E1 | O — 지난 라운드와 같다(`docs/manual/02-decision-tables.md` 3절) |
|
||||
| 20 | 개발자 경험 | 적용 | M3 / M2 | E3 | P — 생성 명령 하나로 merge 명령을 통과한다. 매뉴얼 예시 이름의 쓰기 기능은 11단계도 통과한다(16-R2). 템플릿 소스와 겹치는 ID(`product-feature`, 짧은 ID)는 11단계가 템플릿 파일 20개를 잔여로 내며 실패한다(16-R3, 1105/16-04 일부). 0단계는 이런 이름을 경고하지 않는다 |
|
||||
| 21 | Guardrail 성숙도 | 적용 | M4 / M3(부분) | E2 | P — 새로 막는 것: Envelope 줄 누락(기여 전체 포함), 손으로 쓴 뮤테이션 ID, 기능 안 폴더 우회. 아직 통과하는 것: 같은 틀린 Envelope 값, 손으로 만든 객체로 helper 호출, 생성 기능의 브라우저 경로(1105/16-03), 본문만 기능 ID를 담은 spec(16-01). 거짓 양성: `src`·`dist` 쪽 잔여 검사(1105/16-04 일부, 16-R3) |
|
||||
| **22** | **추상화 성숙도** | 적용(깊게) | M4 / M4 | E2 | **P** — `MutationOperationId` brand는 런타임 값을 바꾸지 않는 작은 타입이다. 우회는 손으로 만든 객체와 명시 cast뿐이다. 읽지 않는 라우트 칸은 남았다(1103/16-06) |
|
||||
| **23** | **일관성** | 적용(깊게) | M1 / M1 | E1 | **P** — 추적 파일을 말하는 곳 넷이 같다(1105/16-01). 계약 문서 4.1절 한 문장이 필수 칸과 다르다(16-02) |
|
||||
| **24** | **네이밍 / 의미** | 적용(깊게) | M1 / M1 | E1 | **P** — 기능 ID를 고르는 규칙(0단계)이 템플릿 소스와 겹치는 이름을 경고하지 않는다(1105/16-04 일부). 1101/16-05의 같은 이름 두 타입 그대로 |
|
||||
| 25 | 조직 확장성 | 적용(구조 준비, 팀 1개) | M3 / M2 | E2 | P — 손으로 고치는 템플릿 파일은 없다. 기능 브랜치 둘의 충돌 자리 둘은 문서와 다시 쓰는 명령으로 푼다(1105/16-01). 실제 `git merge`는 재현하지 않았다 |
|
||||
| 26 | Ownership | > 14 | — | — | > |
|
||||
| **27** | **삭제 가능성** | 적용(깊게) | M3 / M2 | E3 | **P** — 생성 읽기 기능 제거가 merge 게이트에서 돈다(`scaffold-feature removal: PASS (17 checks)`). 예시 이름 쓰기 기능 제거도 통과한다(16-R2, 게이트 밖). 겹치는 이름은 거짓 양성이다(16-R3, `src`·`tests`·`dist` 세 검사 모두, 1105/16-04 일부). 본문에만 ID를 담은 spec은 놓친다(16-01). 폴더 밖 손 목록(03:202-215)이 초기 JS 기록까지 말한다 |
|
||||
| 28 | 회복 가능성 | > 06·02 | — | — | > |
|
||||
|
||||
집계(이 영역): O 1 · P 16 · X 0 · ? 0 · > 10 · - 1. 지난 라운드와 같은 분포다. 3·5·17·22의 확인 통제가 M3 → M4로 올랐다.
|
||||
|
||||
## 5. 미검증
|
||||
|
||||
| 항목 | 이유 | 확인 방법 |
|
||||
|---|---|---|
|
||||
| 생성 기능 설치 상태의 FE-GATE-008(e2e·capability·storybook·visual) | merge 게이트라 요청하지 않았다(BRIEF 4). 접근성 e2e만 16-R4로 봤다. 1105 조치가 생성 폼을 바꿨다(`90c489c`, `f2b8ba7`) | 생성 기능 브랜치에서 `ci:gate FE-GATE-008` |
|
||||
| 생성 KEYED 쓰기 기능의 제거를 merge 게이트가 도는지 | 게이트(FE-GATE-020)는 읽기 판만 지운다. 쓰기 판 제거는 16-R2로 한 번 확인했다 | — (관찰. 발견으로 세지 않는다) |
|
||||
| 1105/16-04 완료 기준 둘째의 드릴 실행(`src`에 ID를 남긴 변이) | 단위 테스트(`feature-residue.test.ts:44-60`)와 드릴 연결 코드(`scripts/test-sample-removal.ts:428-431`)로 판단했다. 요청하지 않았다 | `src/contracts/env.ts`에 `invoice-feature` 주석 한 줄을 넣고 16-R2 |
|
||||
| 두 기능 브랜치의 실제 `git merge` 충돌과 명령 재실행(1105/16-01) | git 상태를 바꾸는 실행을 하지 않았다 | 임시 clone에서 기능을 하나씩 더한 두 브랜치를 합치고 03 A절 명령을 돌린다 |
|
||||
| 16-01의 빈틈 실행 재현 | 코드로 확정했고 요청하지 않았다 | 16-01 검증 방법 |
|
||||
| 실제 Gitea 러너, 실제 짝 백엔드 연결, FE-GATE-013 `test:system` | 이 영역 밖이거나 환경이 없다(12 영역) | 러너에서 생성 기능 PR 하나 |
|
||||
| 매뉴얼만 보는 사람·에이전트의 재실험(X2 방식) | 이번에도 하지 않았다 | 매뉴얼만 보는 에이전트가 생성 기능을 실제 계약으로 바꾸고 막힘을 센다 |
|
||||
|
||||
## 6. 실행 기록
|
||||
|
||||
이 영역은 desktop에서 직접 아무것도 돌리지 않았다. 아래 항목은 요청 파일 `scratchpad/r5/requests/16.md`대로 오케스트레이터가 배치로 돌렸다. 기준 `bbde570`, 항목은 하나씩 돌렸고 끝날 때마다 checkout을 깨끗하게 되돌렸다(로그 끝 `restore=clean`). 로그는 `desktop:/tmp/claude-gates/r5/batch/out/R5-16-R1~R4.log`다. 네 항목 모두 기대와 맞았다.
|
||||
|
||||
| ID | 명령 | 변이 | rc | 결과 |
|
||||
|---|---|---|---|---|
|
||||
| 16-R1 | `corepack pnpm create:feature invoice-feature && corepack pnpm check:types:app` · local, 04:24 | `requests/16-R1.diff`(생성기 목록 GET 템플릿의 `responseEnvelope` 줄 삭제, `scripts/create-feature.ts:800`) | 1 | **기대와 같다.** create:feature는 통과했다(라우트 `INVOICE_LIST` 하나). `tsc --project tsconfig.app.json`은 실패했다. ① `invoice-contract-contribution.ts(69,4)`: TS1360 `does not satisfy the expected type 'InstalledHttpContract<...>'` / `Property 'responseEnvelope' is missing in type ...`. ② `(83,11)`: TS2352 기여 배열 cast, 같은 이유. 대조(변이 없음): FE-GATE-020 `FE-GATE-003:check-types` PASS |
|
||||
| 16-R2 | `corepack pnpm create:feature invoice-feature --with-create --keyed && corepack pnpm test:sample-removal -- --feature=invoice-feature` · CIENV, 04:24~04:27 | — | 0 | **기대와 같다.** `invoice-feature removal: PASS (17 checks, no fixture IDs)`. 그 안에서 `Risk coverage: PASS (418/418 production modules, 72 thresholds)`, `Test evidence: PASS (430 files ...)`, `CI contract: 27 gates ... PASS`가 나왔다. 로그의 stack trace는 오류 경계 component 테스트가 일부러 낸 것이다. 테스트는 통과했다 |
|
||||
| 16-R3 | `corepack pnpm create:feature product-feature && corepack pnpm test:sample-removal -- --feature=product-feature` · CIENV, 04:27~04:31 | — | 1 | **기대와 같다.** create:feature는 통과했다(`product-context`, `/product`). 드릴 실패는 잔여 검사 둘뿐이다. `fixture-id-residue`: `src/.generated/product-app.ts`, `src/.generated/product-context-index.ts`, `src/.generated/product-feature-index.ts`, `src/application/ports/in/application-api.ts`, `src/application/ports/out/application-output-ports.ts`, `src/application/ports/product-features-port.ts`, `src/bootstrap/runtime-adapters.ts`, `src/bootstrap/runtime-config-schema.ts`, `src/contracts/env.ts`, `src/contracts/product-features.ts`, `src/features/installed-product-manifest.ts`, `src/features/local-draft-feature/NOT_A_FEATURE`, `src/presentation/examples/platform-overview-page.tsx`, `tests/component/product-feature-switch.test.tsx`, `tests/features/product-features-scale.test.ts`, `tests/scripts/generate-product-feature-index.test.ts`, `tests/unit/product-feature-index-write.test.ts`, `tests/unit/product-feature-selection-build.test.ts`, `tests/unit/product-features.test.ts`. `built-fixture-id-residue`: `dist/assets/platform-overview-page-C26HW_up.js` |
|
||||
| 16-R4 | `corepack pnpm create:feature invoice-feature --with-create --keyed && corepack pnpm test:a11y` · CIENV, 04:31~04:32 | — | 0 | **기대와 같다.** `69 passed (58.3s)`. `/invoice`, `/invoice/items/a11y-1`, `/invoice/new`가 chromium·firefox·webkit에서 모두 `no critical or serious axe violations`였다. 보고: `a11y: INVOICE_DETAIL not checked in its own state (scanned on its failure state only: INVOICE_GET_ITEM reads one resource)`. 참조 기능의 `REFERENCE_RESOURCE_DETAIL`도 같은 줄이 나왔다. a11y.json 배열 자체는 로그에 없다. 이 보고 줄로 `notChecked`를 판단했다 |
|
||||
|
||||
인용한 실행(같은 커밋, 오케스트레이터):
|
||||
|
||||
| 출처 | 내용 |
|
||||
|---|---|
|
||||
| `bbde570-ci/summary.txt`(CI env, 03:24~03:56) | FE-GATE-020 rc=0 1,237초, FE-GATE-001~012 rc=0, FE-GATE-013 rc=1(전제 실패, 12 영역). `restored ... clean=yes` |
|
||||
| `bbde570-ci/gate-artifacts/FE-GATE-020.txt` | `reference-feature removal: PASS (31 checks, no fixture IDs)`(:3087, 안에 NEVER 판 `scaffold-feature --with-create` 생성 :1495와 게이트). `feature scaffold: PASS (77 checks)`(:7974), `scaffold-feature removal: PASS (17 checks, no fixture IDs)`(:7973). 초기 JS 기록 `{"gzipBytes":205465,"files":27,"perFeatureGzipBytes":765,"perContextGzipBytes":157}`, `Bundle budget: PASS (initial JS 205465 / 206848 gzip bytes, 27 / 32 files)`(:6206). 생성 출력의 충돌 처리 줄(:1535-1537) |
|
||||
| `r5/snap/merge/artifacts/tests/feature-scaffold.xml`(03:40) | 77건, 실패 0. `create-feature`, `create-feature-write`, `initial-javascript-record`, FE-GATE-001~013의 merge 명령, `feature-removal` |
|
||||
| `bbde570-ci/gate-artifacts/FE-GATE-005.txt` | `feature-residue.test.ts`(3), `feature-tracked-files.test.ts`(3), `command-mutation-identity.test.ts`(5), `external-contract-runtime.test.ts`(47), `backend-contract-pin.test.ts`(15), `backend-contract-drift.test.ts`(9) 통과 |
|
||||
| `bbde570-ci/FE-GATE-003.log`, `FE-GATE-010.log`, `gate-artifacts/FE-GATE-010.txt`, `FE-GATE-012.txt` | typecheck PASS, architecture PASS(`Architecture graph fixtures: 31 regression checks PASS`), `Bundle budget: PASS (initial JS 204158 / 206848 gzip bytes, 27 / 32 files)` |
|
||||
| `r5/snap/verify-documentation.local.txt`, `.no-sibling.txt` | 둘 다 `Documentation readiness: PASS_SCOPED` |
|
||||
|
||||
## 7. 새 발견 요약
|
||||
|
||||
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|
||||
|---|---|---|---|---|
|
||||
| 16-01 | Low · P3 | 구조적 위험 | 제품 기능 제거 드릴이 `tests` 잔여를 파일 이름·import로 좁혔고, 안전망으로 든 `test:all`은 Playwright spec을 돌지 않아 spec 본문의 기능 ID를 아무 검사도 잡지 않는다. 매뉴얼·주석이 "test:all이 잡는다"고 적는다 | `scripts/lib/feature-residue.ts:18-20, 57-60`, `docs/manual/01-add-a-feature.md:662`, `vitest.config.ts:45`, `package.json:85` |
|
||||
| 16-02 (= 07-01, 07-01로 센다) | Low · P3 | 확인된 결함 | 계약 문서 4.1절의 bulk 안내가 "`responseEnvelope`를 뺀다"로 남아 필수 칸·한 기여 안 같은 값 규칙과 어긋난다 | `docs/architecture/backend-api-and-server-state-contract.md:205-207`, `src/contracts/external-contract-runtime.ts:239` |
|
||||
@@ -0,0 +1,765 @@
|
||||
# 성숙도 리뷰 — 2026-11-06 (5라운드)
|
||||
|
||||
> 기준: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`. 대상: `bbde570`(PR B, PR #7 끝). 이 커밋은 2026-11-05 리뷰의 조치(그 README 16절)를 모두 담는다. 영역은 2026-11-05 리뷰의 16개를 그대로 썼다. 영역 에이전트는 노트북 worktree에서 코드를 읽었다. 실행은 desktop checkout 하나에서 했다. merge stage는 메인 세션의 실행을 증거로 썼고(11.1절), 그 밖의 실행은 오케스트레이터가 묶어서 한 번씩 돌렸다(11.4절). 이 문서는 오케스트레이터가 결과를 모은 것이다. 새 High·P1 후보 둘(03-01, 08-01)은 오케스트레이터가 코드를 직접 다시 읽었다. 리뷰 중 코드는 고치지 않았다.
|
||||
>
|
||||
> 메인 세션이 따로 물은 세 가지(D7 예산 상향이 검사를 약하게 했나, 16.3절 통합 수정, BREAKING 5건의 CHANGELOG 안내)의 답은 3절에 있다.
|
||||
>
|
||||
> 이 리뷰 뒤의 수정 라운드(결정 D9·D10, 발견별 상태, 확인)는 16절에 있다. 1~15절은 리뷰 때 그대로다.
|
||||
|
||||
## 0. 평가 전제 (가이드 0.1)
|
||||
|
||||
| 전제 | 기록 | 판정에 미치는 영향 |
|
||||
|---|---|---|
|
||||
| 사용 목적 | 프론트엔드 템플릿(reference implementation). 짝 백엔드 템플릿과 함께 써서 desktop 서버에 서비스를 빨리 출시하는 시작점(`PRODUCT.md`) | 다운스트림이 그대로 복제하는 기본값과 문서가 판정 대상이다 |
|
||||
| 사용자와 팀 | 작성자 1명 + AI 세션. 다운스트림 2개(tech-log, memento) | 템플릿 파일을 고쳐야 하는 지점은 동기화 비용이 된다 |
|
||||
| 지원 실행 형태 | 브라우저 SPA + 정적 호스팅 + 선택형 Service Worker. SSR 없음 | 서버 메모리 상태·다중 인스턴스 경쟁은 적용 제외. 탭 사이 경쟁은 적용 |
|
||||
| 데이터와 권한 | 세션(짝 백엔드 인증), 선택형 OPFS 개인 파일, 공개 캐시. 관리자·테넌트 기능 없음 | 로그아웃·계정 삭제 뒤 남는 데이터가 주된 피해 경로다 |
|
||||
| 규모 목표 | 기능 수 증가 축만 있다. 초기 JS 206,848 B(gzip, 1105 D7로 204,800 B에서 올림), 초기 파일 32개, 기능 모양 상한(`config/scale/feature-shape-ceilings.json`). 요청량·데이터량 목표 없음 | 성능은 lab 예산과 번들 예산으로만 판정한다 |
|
||||
| 의존 시스템 | 짝 백엔드(pin `45d2a478`, `config/contracts/backend-contract-pin.json`), 정적 호스팅(nginx 예시), Gitea Actions(꺼져 있음, U-1) | 짝 계약 어긋남과 러너 전제를 따로 본다 |
|
||||
| 운영 목표 | lab 예산(`config/performance/budgets.json`: 상호작용 200 ms, 기능 라우트 첫 진입 500 ms 등). RPO·RTO 없음 | 운영 복구 목표는 판정하지 않는다 |
|
||||
| 지원·비지원 | OPFS·realtime·SW·Web Push·업로드는 opt-in. bulk `results` 비지원(문서화). 실제 CI 러너 미가동 | 없는 기능을 결함으로 세지 않는다 |
|
||||
|
||||
## 1. 사용 결정 (36.5-1)
|
||||
|
||||
| 용도 | 결정 | 막는 항목 |
|
||||
|---|---|---|
|
||||
| 템플릿 상태 그대로 merge 게이트 통과 | 조건부 사용 가능 | 13/14 통과(CI env). FE-GATE-013은 비특권 user namespace를 허용하지 않는 호스트(이 desktop)에서 사전 점검이 제한을 이름으로 대며 실패한다(1105/12-01. 제한 없는 호스트에서 PASS하는지는 가짜 호스트 단위 테스트로만 봤다). 뒤 부분은 통과. 이 게이트를 멈춤 기준에서 어떻게 셀지는 사용자가 정한다 |
|
||||
| `create:feature`로 기능을 더하고 템플릿 CI로 머지 | 조건부 사용 가능 | 생성 세 판이 손 수정 없이 merge 명령을 지난다(FE-GATE-020 scaffold 77 check). 제품 기능 제거 드릴이 짧은·흔한 ID(`product-feature`)에서 템플릿 파일 20개를 잔여로 잡는다(1105/16-04 일부). spec 본문에만 남은 기능 ID는 잡지 않는다(16-01) |
|
||||
| 다운스트림(tech-log·memento)에 이 묶음 전파 | 조건부 사용 가능 | BREAKING 다섯 단계는 따라 하면 맞는 변경이 된다. 설명 셋(부팅 실패 시점, TechLog Envelope, `requiresIdempotencyKey` 재계산)이 틀렸다(14-01, Low·P2). 1103/16-05 안내가 descriptor 없는 뮤테이션의 길을 말하지 않는다(09-01) |
|
||||
| 짝 백엔드에 붙는 쓰기 폼(NEVER) | 사용 가능 | 거절 문구 자리가 있다. 선언하지 않은 code는 결과 불명으로 남는다(1103/03-01 일부) |
|
||||
| 짝 백엔드 KEYED 쓰기(`--keyed`) | 조건부 사용 가능 | 결과 불명 뒤 같은 키 재전송이 쓰기 전 거절(429·401·503 `RATE_LIMIT_*`)로 끝나면 다음 저장이 새 키로 나간다(03-01, Medium·P2. 03-R1 재현) |
|
||||
| 짝 백엔드와 파일 업로드 | 조건부 사용 가능 | 202 `REJECTED`·504 `TRANSFER_TIMEOUT` 판정은 들어왔다. 504 뒤 READY 보장은 백엔드 몫(1105/01-02 일부·백엔드로 넘김). 실제 짝 백엔드 업로드는 돌려 보지 않았다 |
|
||||
| 짝 백엔드 인증에 세션 붙이기 | 조건부 사용 가능 | 쿠키 세션 401 연결은 들어왔다(1105/09-02 고쳐짐). 실제 Keycloak·Redis 연동 미확인(1103/09-03) |
|
||||
| OPFS에 개인 파일 저장 | 조건부 사용 가능(지난 라운드 사용 보류에서 올림) | 계정 삭제 purge가 늦게 들어온 put과 reconcile 겹침까지 모두 지운다(05-R1 메모리 51/51, 05-R2 Chromium·Firefox 24/24). WebKit은 정책상 돌지 않아 미확인 |
|
||||
| release 단계(`RELEASE_READY`)까지 | 조건부 사용 가능 | lab 통과(상호작용 151 ms, 기능 라우트 402 ms). release job이 실패 때도 로그를 올린다(1105/13-01, runner 미가동이라 일부). 승인이 거절된 run에는 advisory 기록이 없다(13-01). advisory 2건은 결정 대기(1103/13-03) |
|
||||
| 배포 슬롯을 채워 자동 배포 | 조건부 사용 가능 | 제품 merge 검사가 실패하면 release를 멈춘다(1105/13-02 고쳐짐). live probe가 `/service-worker.js`의 같은 출처 redirect를 통과시킨다(06-01) |
|
||||
| 짝 백엔드 Envelope 조회 화면 | 사용 가능 | bulk `results`는 비지원(문서화). 계약 문서 4.1절의 bulk 안내가 필수 칸과 맞지 않는다(07-01) |
|
||||
| opt-in realtime(SSE·WS)·bounded polling | 조건부 사용 가능 | poll 던짐은 `PROTOCOL_MISMATCH`, reconnect 던짐은 서버 장애로 다르게 끝난다(04-01). 결정 대기 0929/04-02·04-03 |
|
||||
| SW `ACTIVE`·Web Push | 조건부 사용 가능 | 옛 탭의 지운 route·청크를 이전 캐시로 연다(06-R1). Firefox quarantine 아직 필요(06-R4) |
|
||||
| 셸·디자인 시스템·읽기 화면 | 사용 가능 | 08 영역 Low 3건(다시 마운트한 폼, 생성 폼 이동, gutter 띠) |
|
||||
|
||||
## 2. 차단 항목 (36.5-3)
|
||||
|
||||
### 2.1 새 High — 없음
|
||||
|
||||
### 2.2 새 P1 — 없음
|
||||
|
||||
### 2.3 이월 항목 중 남은 큰 것
|
||||
|
||||
| ID | 지난 등급 | 지금 | 남은 부분의 등급 |
|
||||
|---|---|---|---|
|
||||
| 1103/13-03 | Medium·P1 | 일부, 결정 대기(7절 D1) | Medium·P1 그대로. 운영 high advisory 2건(react-router 7.18.1, zod 4.4.3)이 13-R1 B에서 그대로 나온다 |
|
||||
| 1103/03-01 | High·P1 → Medium·P2 | 일부. 기능 거절 문구는 동작(08-R6) | Medium·P2. 선언하지 않은 code는 결과 불명 → "변경됨으로 확인"으로 거짓 성공. `refusalMessages`의 409 필드 오류가 VD-04 결정 5와 어긋난다(08 영역) |
|
||||
| 1105/01-02, 1103/01-01 | Medium·P2, High·P1 | 일부 · 백엔드로 넘김 | 504 뒤 READY 보장은 백엔드 요청 (b)로는 안 된다(01 영역). 실제 업로드 미검증 |
|
||||
| 1103/09-04, 1103/03-07, 1103/16-06, 1105/16-03 | — | 결정 대기 | 그대로 |
|
||||
| 1105/12-04 | Medium·P2 | 일부(14절) | 소유자 완료 기준(e2e 두 실행을 함께)은 통과했다. 리뷰 완료 기준(FE-GATE-008 둘 또는 008과 005를 `ci:gate`로 함께)은 아니다. 두 `ci:gate` 실행은 아직 같은 `dist`·`artifacts/`를 쓰고, 그 제한은 문서로만 적혀 있다(`README.md:362-363`) |
|
||||
|
||||
### 2.4 심각도 재확인
|
||||
|
||||
| ID | 영역 제안 | 최종 | 이유(오케스트레이터가 코드를 다시 읽음) |
|
||||
|---|---|---|---|
|
||||
| 03-01 | Medium·P2 | 그대로 | 결과 불명 쓰기의 재실행(가이드 35.2 High 예시)과 모양이 같다. 그러나 재전송이 `NOT_STARTED`가 되는 길은 전송 전 거절뿐이다(scope 변경, 검증, 자격 해석 실패. `http-execution-v3.ts:751-790`). 실행기에 offline 검사는 없다. 그래서 실제로 이 길을 여는 것은 opt-in rate limit(429·503 `RATE_LIMIT_*`, 백엔드 기본 꺼짐)이나 세션 만료(401)다. 저장을 한 번 더 누르면 되던 0929/03-03(High)보다 훨씬 드물다. 03-R1이 다른 길을 찾지 못했다 |
|
||||
| 08-01 | Low·P3 | 그대로 | 다시 마운트한 폼에서도 결과 불명 화면과 가드는 그대로다. 결과가 보이지 않을 뿐이다. 중복은 사용자가 같은 항목을 새로 입력할 때만 생기고, 그 시점에 결과 불명 상태가 아니다 |
|
||||
|
||||
## 3. 메인 세션이 물은 세 가지
|
||||
|
||||
### 3.1 D7 예산 상향이 검사를 약하게 했나
|
||||
|
||||
- **약하게 했다. 다만 결정한 만큼만이다.** `initialJsGzipBytes`만 204,800 → 206,848 B로 바뀌었다(`config/performance/budgets.json:4`). 기능 1 KiB·context 512 B 상한, 초기 파일 32개, lab 예산은 그대로다(15 영역).
|
||||
- 예산 검사는 여전히 동작한다. entry를 약 6 KB 늘리면 `check:bundle`이 "210352 > budget 206848 (over by 3504)"로 실패한다(12-R1).
|
||||
- 기록 대조도 동작한다. entry를 +448 B 늘리면 `feature-shape-growth.test.ts`가 "record 204111, build 204606"으로 실패한다(15-R2). 허용치 256 B는 두 여유(템플릿 2,690 B, 드릴 1,383 B, CI env)보다 작다.
|
||||
- 기록 `0fee3fe`은 측정 스크립트가 쓴 값과 바이트까지 같다(15-R1).
|
||||
- 남은 것(새 15-01, Low·P3): 필요한 폭(665 B)의 약 세 배를 올렸는데, 그 폭의 근거와 다시 내릴 조건이 결정 기록에 없다. 재검토 조건은 "다시 넘을 때 · 1103/13-03을 정할 때"뿐이다.
|
||||
|
||||
### 3.2 16.3절의 통합 수정
|
||||
|
||||
| 지난 16.3 위치 | 판정 | 근거 |
|
||||
|---|---|---|
|
||||
| `45c9c4d`(합친 커밋, pin `notCopied`) | 맞다 | 답 표·pin·`backend-envelope.ts`·계약 문서 4.1이 같다(03, 07). 사본에만 있는 행을 pin 테스트가 잡는다(07-R2). desktop의 옆 백엔드로 drift 실행도 rc=0(07-R3) |
|
||||
| `b8d53c9`(합친 커밋, vite 빌드 입력) | 맞다 | `vite-build-inputs.ts`가 `vite.config.ts`의 local import를 덮는다(15) |
|
||||
| 12-04 fixup `f4d5761`·`0e72c0c` | 새 결함을 만들었다 | capability 설정이 없는 사본에서 테스트가 조용히 줄어든다(33 → 25, 10-01). `RUN_OUTPUT_ROOT` 아래 빌드 뒤 검사가 루트를 읽는다(12-02, 12-04 수정 자체가 만든 것) |
|
||||
| 05-01 fixup `dc7c95b`(`orphanExemptRows`) | 약화 아님 | 예외를 빼도 템플릿 `check:registries`는 PASS다(05-R4). 커밋의 이유는 반만 맞다(다른 예외 둘은 쓰는 곳이 없어야 하는 행, 이 행은 recipe가 쓰는 `external` 키). 새 발견으로 세지 않았다 |
|
||||
| 1105/11-01 fixup(`use` → `provide`) | 맞다 | 동작은 같다(11) |
|
||||
| 15-05 fixup `e02f252`(골든 재생성) | 일부 | layout shift는 0건이다(15-R3, 18회). 비운 15 px 띠를 drawer·모달 가림막과 header가 덮지 않고, 새 골든이 그 모습을 고정했다(08-03) |
|
||||
| 15-03 fixup `c9aa73f`(있는 소비자만 본다) | 새 결함에 포함 | 10-01과 같은 모양 |
|
||||
| 03-01·16-01의 문서 테스트 목록 | 새 결함 | 파일 전체를 빼서 문서를 읽지 않는 테스트 14~15건이 capability 드릴 셋에서 빠진다. 목록 가드는 주석 한 줄로 통과한다(12-01 = 10-02) |
|
||||
| `0fee3fe`(초기 JS 기록) | 맞다. 다만 문서가 어긋남 | 기록은 맞다(15-R1). `performance-evidence.md:209-210`이 템플릿 초기 파일을 26개로 적는다(지금 27개, 1103/15-02 재발) |
|
||||
| `287dc6f`(D7 커밋) | 본문이 닿지 않는 해시를 가리킨다 | `ab0d4a1`·`7ce9bf1`은 재작성 전 해시다(14-02) |
|
||||
|
||||
### 3.3 BREAKING 5건의 CHANGELOG 안내
|
||||
|
||||
| 커밋 | 코드 = 꼬리말 = CHANGELOG 행동 | 틀린 설명 |
|
||||
|---|---|---|
|
||||
| `5c0b37e` 03-01 `refusedBeforeWrite` | 같다(03) | 3단계가 "부팅이 멈춘다"고 적는다. 실제로는 그 기능 라우트에 처음 들어갈 때 실패한다(14-01) |
|
||||
| `05330e3` 04-02 poll 던짐 → `PROTOCOL_MISMATCH` | 같다(04, 11-03 절 행 포함) | 없음 |
|
||||
| `48c1ab7` 1103/16-05 손 operation ID | 같다(09) | `requiresIdempotencyKey`를 `retrySemantics`에서 다시 계산한다는 말이 없다(14-01). descriptor 없는 뮤테이션의 길이 없다(09-01) |
|
||||
| `757d1c7` 1103/11-01 `a11y.json` schema 2 | 같다(11) | 없음. 다만 `notChecked` 분류를 지키는 test가 없다(11-01) |
|
||||
| `56272e8` 1103/16-01 `responseEnvelope` 필수 | 같다(07, 16-R1이 빠진 줄을 TS로 잡음) | 계약 문서 4.1절 bulk 안내가 "뺀다"로 남았다(07-01). 1단계의 TechLog 설명이 틀렸다(14-01) |
|
||||
|
||||
두 다운스트림 모두 행동을 그대로 따라 하면 맞는 변경이 된다(14 영역). 02 영역이 물은 진단 키 `scope_participant`(`CHANGELOG.md:68`)는 진단 계약에 키를 더한 것이라 BREAKING 표시가 필요 없다(오케스트레이터 확인, `src/contracts/diagnostics.ts:47`, `:96`, `:125`). 새 절의 해시 75개는 모두 `bbde570` 이력에 있고, 각 커밋의 `Refs`가 행의 ID와 75/75 같다.
|
||||
|
||||
## 4. 새 발견 건수 — 지난 라운드와 비교
|
||||
|
||||
| 라운드 | 기준 | 새 발견 | High | P1 | Medium | Low |
|
||||
|---|---|---|---|---|---|---|
|
||||
| 1105 | `8a44226` | 48 | 0 | 3 | 11 | 37 |
|
||||
| **1106** | `bbde570` | **25** | **0** | **0** | **1** | **24** |
|
||||
|
||||
- 우선순위: P2 2건(03-01, 14-01), P3 23건.
|
||||
- 성격: 확인된 결함 13, 구조적 위험 9, 개선 제안 3.
|
||||
- 합친 중복 2건(11.3절)은 한 번만 셌다. 영역 문서에 적힌 것은 27건이다.
|
||||
- 지난 조치가 만든 새 발견이 16건, 고치며 남긴 것이 2건이다(25건 중 18건, 목록은 15절 머리).
|
||||
|
||||
멈춤 기준(새 High 0, 새 P1 0, merge 게이트 14개 통과): High·P1은 0이다. merge 게이트는 13/14이고 FE-GATE-013은 호스트 제약으로 사전 점검에서 실패한다(11.1절). 이 게이트를 어떻게 셀지는 사용자가 정한다.
|
||||
|
||||
## 5. 확인된 강점 (36.5-2)
|
||||
|
||||
- 지난 라운드 P1 셋은 이 repo에서 확인할 수 있는 부분을 모두 고쳤다. 09-01은 탐침 변이로(09-R1), 12-01은 namespace를 만들어 보는 사전 점검으로, 13-01은 실패 run의 업로드 파일로(13-R1) 확인했다. 남은 것은 실행 환경 쪽이다(12-01: 제한 없는 호스트의 PASS, 13-01: 실제 release run의 산출물).
|
||||
- 수정을 되돌린 변이는 모두 해당 테스트에서 기대한 이유로 실패했다. 살아남기를 기대한 것(06-R3, 약해진 단언의 증거)은 살아남았다. 배치 65항목 중 예상과 다르게 나온 것은 셋이고, 판정을 바꾼 것은 없다: 08-R2(probe 단언 둘을 잘못 짰다. 측정값은 08-03을 뒷받침한다), 15-R3(`clientWidth`가 한 값일 거라는 예상만 틀렸다. shift는 0건), 03-R7(6건 실패 예상, 같은 규칙을 보는 테스트 1건이 더 실패). 네 라운드 동안 살아남던 L01(오래된 scope의 성공 응답)도 이제 잡힌다(10-R4).
|
||||
- OPFS purge가 늦은 put과 reconcile 겹침까지 지운다(05-R1·R2). 지난 라운드 사용 보류의 원인이 풀렸다.
|
||||
- 한 checkout에서 e2e 두 실행을 함께 돌려도 서로 지우지 않는다(14절).
|
||||
- CHANGELOG 새 절의 해시 75개가 모두 이력에 있고 `Refs`와 맞는다.
|
||||
|
||||
## 6. 반복되는 원인 (36.5-4)
|
||||
|
||||
| 원인 | 이번 예 | 지난 예 |
|
||||
|---|---|---|
|
||||
| 제거·격리 사본에서 테스트가 조용히 줄어든다. 줄어든 수를 보는 장치가 없다 | 10-01, 12-01 | 1103/02-06(문서 테스트 ENOENT) |
|
||||
| 고친 동작과 그 동작을 설명하는 문서가 따로 움직인다 | 03-02, 05-01, 07-01, 13-01, 14-01, 1103/15-02 재발 | 1105/04-03, 14-02 |
|
||||
| 화면 상태를 폼 인스턴스가 들고 있어, 다시 마운트하면 결과를 잃는다 | 08-01, 08-02 | 1105/08-01 |
|
||||
| 결과 불명 상태를 시도 하나의 판정으로 풀어 버린다 | 03-01 | 0929/03-03, 1103/03-01 |
|
||||
| 수정이 단언을 느슨하게 하거나 검사 범위를 좁힌다 | 06-02, 16-01 | 1105/15-02(허용 오차) |
|
||||
|
||||
## 7. 결정이 필요한 것
|
||||
|
||||
| 번호 | 결정 | 선택지 | 관련 | 결정할 사람 |
|
||||
|---|---|---|---|---|
|
||||
| D1 | 운영 advisory 2건(이월) | zod 갱신(+약 7 KB) / react-router 갱신 / 위험 수용과 재검토일 | 1103/13-03 | 프론트 소유자 + reviewer |
|
||||
| D2 | 플랫폼 구성 화면(이월) | 지난 7절 D2와 같다 | 1103/09-04 | 프론트 소유자 |
|
||||
| D3 | 백엔드 생성기 목록 GET(이월) | 지난 7절 D3과 같다 | 1103/03-07 | 두 repo 소유자 |
|
||||
| D8 | FE-GATE-013을 멈춤 기준에서 어떻게 셀지 | 호스트 제약 실패로 제외 / 다른 러너에서 통과할 때까지 미충족 | 11.1절, 1105/12-01 | 사용자(메인 세션이 묻는 중) |
|
||||
| D9 | D7의 폭과 되돌림 조건 | 지금 값 유지 + 근거 기록 / 필요한 폭으로 다시 / 되돌림 조건 추가 | 15-01 | 프론트 소유자 |
|
||||
| D10 | 결과 불명 KEYED 재전송이 쓰기 전 거절로 끝날 때 | 훅에서 결과 불명 유지(03 영역 안 a) / rate-limit 503을 다시 `MAYBE_APPLIED`로 / 생성 페이지만 고치기 | 03-01 | 프론트 템플릿 담당 |
|
||||
| D11 | 생성 기능 설치 상태의 브라우저 merge 게이트(이월) | 지난 16-03과 같다 | 1105/16-03 | 템플릿 담당 |
|
||||
|
||||
## 8. 미검증 (36.5-5)
|
||||
|
||||
| 항목 | 이유 |
|
||||
|---|---|
|
||||
| FE-GATE-013의 `tests/system` 18건 | 이 호스트가 비특권 user namespace를 막는다. 다른 러너에서 돌린 적이 없다 |
|
||||
| release 단계 run의 산출물(1105/13-01 완료 기준) | CI runner가 꺼져 있다(U-1) |
|
||||
| 실제 짝 백엔드 업로드·Keycloak·Redis 연동 | 백엔드를 띄워 보지 않았다 |
|
||||
| OPFS purge의 WebKit 동작, 이전 release 탭과의 공존 | WebKit 기본 정책이 OPFS 런타임을 거절한다. 공존은 돌리지 않았다 |
|
||||
| 05-R2의 "파일 0" | partition 디렉터리가 없어서 나온 값일 수 있다. 파일이 있을 때 세는 대조 실행이 없다 |
|
||||
| 06-01의 브라우저 동작(worker script redirect 거절) | 일반 지식이다. 이 repo에서 실행하지 않았다 |
|
||||
| 03-01의 실제 백엔드 빈도 | 재전송이 rate-limit 거절을 받는 빈도는 재지 않았다 |
|
||||
| 1103/11-02·11-03·11-04 완료 기준 | 글꼴 없는 깨끗한 러너, namespace를 허용하는 호스트가 필요하다 |
|
||||
|
||||
## 9. 개선 순서 (36.5-6)
|
||||
|
||||
1. 결정 D8·D9·D10을 받는다.
|
||||
2. Medium 03-01(D10에 따라).
|
||||
3. Low·P2 14-01(CHANGELOG 설명 셋. 다운스트림이 읽는 곳).
|
||||
4. 검사가 조용히 줄어드는 것들: 10-01, 12-01, 12-02, 16-01, 06-02.
|
||||
5. 문서 어긋남: 03-02, 05-01, 07-01, 13-01, 1103/15-02 재발, 14-02.
|
||||
6. 나머지 Low(01-01, 02-01, 03-03, 04-01, 04-02, 06-01, 07-02, 08-01~08-03, 09-01, 11-01, 15-01).
|
||||
|
||||
## 10. 재검토 조건 (36.5-7)
|
||||
|
||||
- 백엔드 pin(`45d2a478`)을 올릴 때: 07 영역의 사본 대조와 01 영역의 Fileserver 계약을 다시 본다.
|
||||
- FE-GATE-013을 다른 러너에서 돌릴 수 있게 될 때: 1103/11-02~11-04와 1105/12-01의 실행 부분.
|
||||
- 초기 JS가 다시 예산에 닿거나 1103/13-03을 정할 때: D7·15-01.
|
||||
- KEYED를 템플릿 기본으로 바꾸거나 rate limit을 기본으로 켤 때: 03-01의 심각도를 다시 본다(High 후보).
|
||||
|
||||
## 11. 리뷰 범위 (36.1)
|
||||
|
||||
| 항목 | 기록 |
|
||||
|---|---|
|
||||
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`. 짝 백엔드 `clean-architecture-backend-template`은 pin `45d2a478`의 트리를 `git show`로 읽기만 했다(노트북 작업 트리는 `3d73b6f1`로 움직였다) |
|
||||
| 커밋·작업 상태·확인 시점 | `bbde570`(PR B, PR #7 끝. PR A `a793b83` 위, main `409d72e` 위). 기록 브랜치 `docs/maturity-review-2026-11-06`은 `bbde570`에서 땄다. 2026-11-06 04:00~. 노트북 worktree는 이 커밋에서 깨끗했다(추적 안 된 `AGENTS.md` 하나는 리뷰와 무관). desktop checkout은 실행마다 원래 상태(`fix/maturity-review-2026-11-03` `8a44226`)로 되돌렸다 |
|
||||
| 제외 | PR #6(매뉴얼, `docs/improvement/`, 문서만, 별도 PR). 기준 커밋에 없다 |
|
||||
| 목적과 지원 실행 구성 | 0절 |
|
||||
| 필수 요구와 규모·운영 목표 | 0절 |
|
||||
| 읽은 코드·구성 범위 | `src/`, `tests/`, `scripts/`, `config/`, `.gitea/`, `docs/`, `recipes/`, 루트 설정(영역 표 11.2). 짝 백엔드는 pin 트리의 계약·생성기·인증 문서와 코드 일부 |
|
||||
| 수행한 테스트·실험 | 11.1절 게이트(메인 세션 실행)와 공유 실행 1회, 오케스트레이터의 12-04 완료 드릴, 영역 요청 배치(11.4절) |
|
||||
| 확인하지 못한 범위·이유 | 8절 |
|
||||
| 이전 리뷰와 비교 가능한 범위 | 2026-11-05 리뷰의 새 발견 48건(README 16.4절)과 1103 이월 22건(16.5절), 그 밖의 이월(16.6절). 이전 실행 결과는 증거로 쓰지 않았다 |
|
||||
|
||||
실행 환경: desktop, Ubuntu 24.04.4, kernel 7.0.0-38, Intel i5-10400F(12 스레드), 31 GB, Node v24.14.0, pnpm 11.17.0, Playwright 1.62.0.
|
||||
|
||||
### 11.1 게이트 실행 결과 (메인 세션, `bbde570`, desktop)
|
||||
|
||||
같은 커밋이라 메인 세션의 merge stage 실행을 게이트 증거로 쓴다.
|
||||
|
||||
- 실행: 2026-11-06 03:24~03:56, workflow env(`CI=true`, `VITE_COMMIT_SHA`, `VITE_BUILD_ID`, `RELEASE_ID`, `CI_RUNNER_IMAGE` digest 형식).
|
||||
- 출처: `desktop:/tmp/claude-gates/bbde570-ci/`(`summary.txt`, 게이트별 `FE-GATE-NNN.log`, 전체 로그 `gate-artifacts/FE-GATE-NNN.txt`). FE-GATE-013의 사전 점검 뒤 명령은 `desktop:/tmp/claude-gates/bbde570-013-parts/`(03:54~03:56).
|
||||
- 실행 뒤 작업 트리는 비어 있었다(`status-after.txt` 0 B, `restored ... clean=yes`).
|
||||
|
||||
| 게이트 | 결과 | 시간 |
|
||||
|---|---|---|
|
||||
| FE-GATE-020 | 통과(참조 기능·생성 기능 제거, 생성 기능 77 check, optional-recipe·browser-file-storage·realtime 제거 모두 PASS. 생성 기능 둘을 더한 빌드 초기 JS PASS) | 1,237초 |
|
||||
| FE-GATE-001 | 통과 | 3초 |
|
||||
| FE-GATE-002 | 통과(lint) | 18초 |
|
||||
| FE-GATE-003 | 통과(typecheck) | 27초 |
|
||||
| FE-GATE-004 | 통과(runtime-schema 60) | 2초 |
|
||||
| FE-GATE-005 | 통과(unit 3,056, contract 24, coverage 4,085) | 132초 |
|
||||
| FE-GATE-006 | 통과(component 278) | 10초 |
|
||||
| FE-GATE-007 | 통과(integration 212 외) | 28초 |
|
||||
| FE-GATE-008 | 통과(e2e 222·4 skip, capability 69, storybook 1, visual 6) | 196초 |
|
||||
| FE-GATE-009 | 통과(a11y 60. `REFERENCE_RESOURCE_DETAIL`은 실패 화면으로만 검사해 notChecked) | 51초 |
|
||||
| FE-GATE-010 | 통과(architecture, adapter inventory, CI contract) | 63초 |
|
||||
| FE-GATE-011 | 통과 | 8초 |
|
||||
| FE-GATE-012 | 통과(초기 JS 204,158 / 206,848 B, 27 / 32 파일) | 6초 |
|
||||
| FE-GATE-013 | **실패** — 사전 점검이 user namespace를 만들지 못한다(`bwrap: loopback: Failed RTM_NEWADDR`, 호스트 `kernel.apparmor_restrict_unprivileged_userns = 1`). 사전 점검 뒤 부분: `tests/system` 96/114(실패 18건 모두 같은 bwrap `RTM_NEWADDR`), 뒤 명령 7개(`verify:reproducible-build`, `build:release-candidate`, `verify:local-evidence`, 공급망 fixture 둘, 보안 fixture, `check:browser-security`) 모두 rc=0. 멈춤 기준에서 이 게이트를 어떻게 셀지는 사용자가 정한다 | 2초(사전 점검) + 81초(`tests/system`) |
|
||||
|
||||
CLAUDE.md 게이트 목록은 `verify:documentation`을 빼고 모두 merge stage 안에서 돈다(`check:architecture`·`check:adapter-inventory`·`check:ci`는 FE-GATE-010, `check:types` 003, `lint` 002, `test:unit`·`test:contract` 005, `test:component` 006, `test:integration` 007, `test:runtime-schema` 004). 그래서 따로 돌리지 않았다.
|
||||
|
||||
공유 실행(오케스트레이터, `bbde570`, local env, 2026-11-06 04:03, 잠금 안에서 1회, 48초. 출처 `desktop:/tmp/claude-gates/r5/snap/`):
|
||||
|
||||
| 명령 | 결과 |
|
||||
|---|---|
|
||||
| merge stage가 남긴 산출물 snapshot | `snap/merge/`(761 파일, `MTIMES.txt`). 03:24 전 날짜의 파일은 옛 실행이 남긴 것이라 쓰지 않았다 |
|
||||
| `verify:documentation`(FE-GATE-017, documentation stage) | `PASS_SCOPED`(desktop의 옆 백엔드 checkout 있음) |
|
||||
| 같은 명령, 옆 checkout 없는 임시 worktree | `PASS_SCOPED`(짝 repo 참조 17개 미검증. pin 트리를 읽을 checkout이 없다) |
|
||||
| `build` + `test:performance -- --runs=5` | PASS. 중앙값 LCP 2,032 ms, CLS 0, 상호작용 151 ms, `/examples/platform` 직접 진입 CLS 0, 기능 라우트 `EXAMPLES_UI` 402 ms(`snap/base/performance/lab.json`) |
|
||||
|
||||
### 11.2 영역 분할 (2026-11-05 README 11.2절 재사용)
|
||||
|
||||
| 번호 | 영역 | 문서 | 새 발견 |
|
||||
|---|---|---|---|
|
||||
| 01 | adapters: browser-transfer | [01-adapters-browser-transfer.md](01-adapters-browser-transfer.md) | 1 |
|
||||
| 02 | adapters: browser-files·cache·cross-context | [02-adapters-browser-files-cache.md](02-adapters-browser-files-cache.md) | 1 |
|
||||
| 03 | adapters: http·state | [03-adapters-http-state.md](03-adapters-http-state.md) | 3 |
|
||||
| 04 | adapters: realtime | [04-adapters-realtime.md](04-adapters-realtime.md) | 2 |
|
||||
| 05 | adapters: storage·kernel | [05-adapters-storage-kernel.md](05-adapters-storage-kernel.md) | 1 |
|
||||
| 06 | adapters: service worker·push | [06-adapters-service-worker-push.md](06-adapters-service-worker-push.md) | 2 |
|
||||
| 07 | contracts | [07-contracts.md](07-contracts.md) | 2 |
|
||||
| 08 | presentation | [08-presentation.md](08-presentation.md) | 3 |
|
||||
| 09 | app core·bootstrap·features | [09-app-core.md](09-app-core.md) | 1 |
|
||||
| 10 | tests: 빠른 계층 | [10-tests-fast-layers.md](10-tests-fast-layers.md) | 1 (10-02는 12-01로 합침) |
|
||||
| 11 | tests: 브라우저·릴리스·규모 | [11-tests-browser-release-scale.md](11-tests-browser-release-scale.md) | 1 |
|
||||
| 12 | guardrails·CI | [12-guardrails-ci.md](12-guardrails-ci.md) | 2 |
|
||||
| 13 | build·release·supply chain | [13-build-release-supply-chain.md](13-build-release-supply-chain.md) | 1 |
|
||||
| 14 | 템플릿·제품 문서 | [14-template-product-docs.md](14-template-product-docs.md) | 2 |
|
||||
| 15 | 성능 실측·최적화 | [15-performance.md](15-performance.md) | 1 |
|
||||
| 16 | 폴더 구조·리팩토링·기능 개발 패턴 | [16-structure-patterns.md](16-structure-patterns.md) | 1 (16-02는 07-01로 합침) |
|
||||
|
||||
### 11.3 합친 중복
|
||||
|
||||
| 대표 | 같은 결함 | 이유 |
|
||||
|---|---|---|
|
||||
| 12-01 | 10-02 | 같은 목록(`scripts/lib/removal-fixture.ts:70-81`)이 문서를 읽는 테스트를 파일째 뺀다. 12는 가드레일 쪽, 10은 빠진 테스트 수 쪽을 봤다 |
|
||||
| 07-01 | 16-02 | 같은 문서 줄(`docs/architecture/backend-api-and-server-state-contract.md:205-207`)의 bulk 안내 |
|
||||
|
||||
관련은 있지만 따로 센 것: 06-02(`ce191be`가 marker deadline 단언을 10 s → 20 s로 느슨하게 함)와 10 영역의 1101/10-07 일부 판정(실제로 1 s 기다리는 RPC 테스트 셋이 남음)은 같은 커밋에서 나왔지만 결함 위치가 다르다. 10-01(조건부 테스트 정의)과 12-02(`RUN_OUTPUT_ROOT` 빌드 뒤 루트를 읽는 검사)는 둘 다 12-04 수정에서 나왔지만 결함이 다르다.
|
||||
|
||||
### 11.4 실행 방식과 안전 사항
|
||||
|
||||
- merge stage는 메인 세션의 실행(11.1절)을 그대로 썼다. 오케스트레이터는 merge stage에 없는 명령과 리뷰어가 읽을 산출물만 잠금 안에서 한 번 돌렸다(공유 실행, 04:03, 48초).
|
||||
- 리뷰어는 desktop에서 아무것도 돌리지 않았다. `/tmp/claude-gates/` 아래 로그와 snapshot만 읽었다. 더 필요한 실험은 요청 파일에 적었다.
|
||||
- 오케스트레이터가 요청 65항목과 12-04 완료 드릴을 하나씩 돌렸다(`desktop:/tmp/claude-gates/r5/batch/`). 항목마다 공유 잠금(`/tmp/claude-gates/heavy.lock`)을 잡고, `bbde570`을 detached로 checkout하고, 변이를 적용하고, 끝나면 원래 브랜치로 되돌렸다(추적 파일 reset, 추적 안 된 파일 삭제, node_modules 유지). 67항목 모두 `restore=clean`이다. 끝에 `git status`는 비었고, 브랜치 `fix/maturity-review-2026-11-03`, head `8a44226`이다.
|
||||
- 같은 명령을 두 번 돌리지 않았다. 변이 없는 대조군은 게이트 로그로 갈음했다.
|
||||
- 되돌림은 git이 무시하는 파일을 지우지 않는다. 그래서 16-R4가 만든 `artifacts/tests/a11y-data-state/INVOICE_DETAIL.json`이 11-R2에 남아 있었다. 그 라우트는 설치되지 않아 보고서가 읽지 않았고 판정에 영향이 없다(11 영역 5절).
|
||||
- 리뷰어 둘(08, 13)이 규칙을 한 번씩 벗어났다. 둘 다 JSON 파일 하나를 `python3`로 읽기만 했다(08은 desktop의 manifest, 13은 노트북의 `config/ci/gates.json`). 쓴 파일은 없다. 각 문서 6절에 적혀 있다.
|
||||
|
||||
### 11.5 오케스트레이터 자신의 실수
|
||||
|
||||
- **배치 runner를 둘 띄웠다.** 첫 runner가 `./daemon.sh`로 떠 있어 `pgrep` 패턴에 걸리지 않았고, 하나를 더 띄웠다. 둘째 runner를 끄는 사이 그것이 잠금을 얻어 06-R1의 변이를 적용한 채로 죽었다. 그 뒤 항목들이 "checkout-not-clean"으로 건너뛰어졌다. 잠금 안에서 checkout을 되돌리고(남은 프로세스 없음 확인), 06-R1을 다시 돌렸다. 다른 항목은 건너뛴 뒤 다음 순회에서 깨끗한 상태로 돌았다. 06-R1의 로그는 다시 돈 것이다.
|
||||
- **brief에 skip 규칙 ID를 틀리게 적었다.** "0929/10-04"가 아니라 1101/10-04다(10 영역이 바로잡음). 같은 틀린 ID가 `tests/unit/playwright-run-isolation.test.ts:244` 주석에도 있다. 그 주석은 지난 수정 라운드에 오케스트레이터가 쓴 것이다.
|
||||
- **14-02의 원인은 오케스트레이터다.** D7 커밋 본문을 쓴 뒤 PR B를 다시 쌓아 03-01·08-03의 해시가 바뀌었는데, 커밋 본문은 고치지 않았다.
|
||||
|
||||
## 12. 28개 관점 판정 (36.2)
|
||||
|
||||
판정 기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 영역 순서는 01부터 16까지다. 종합 판정은 평균하지 않는다. 그 관점을 판정한 영역 중 가장 약한 판정을 쓴다. 한 영역이라도 X면 X다(35.7절). ?는 그 영역에 증거가 없다는 뜻이라, 다른 영역이 P를 준 관점에서는 종합을 바꾸지 않는다(지난 라운드와 같다). 이번에는 X를 준 영역이 없다. 각 영역의 목표·확인 통제와 증거는 영역 문서 4절에 있다. 근거 칸에서 ID 앞에 라운드가 없으면 이번 라운드의 새 발견이다.
|
||||
|
||||
| 번호 | 관점 | 영역 01~16 | 종합 | 종합 판정의 근거·잔여 위험 |
|
||||
|---|---|---|---|---|
|
||||
| 1 | 코드 성숙도 | `OPPOPPOPO>>->>O>` | P | P는 02·03·05·06·08. 지속 실패에서 release marker와 active pointer를 다시 쓰지 않는다(1105/02-02 남은 것, 02-01). 훅이 재전송 한 번의 결과를 논리 요청 전체의 결과로 쓴다(03-01). 다시 마운트한 폼과 생성 폼의 저장 뒤 처리(08-01, 08-02). 손상 chunk reference 행이 reconcile을 멈춘다(0929/05-01 ③) |
|
||||
| 2 | 구조적 성숙도 | `OP>OOOOOP>>P>>OP` | P | `check:architecture` 통과(FE-GATE-010). P는 02·09·12·16. 기능 안 계층 밖 폴더 → 자기 기능 `adapters/` → `src/adapters`의 두 단계 경로가 그래프·ESLint를 통과한다(0929/12-03 일부, 12-R3). SW 활성화 화면과 선택 런타임이 템플릿 파일이다(1103/09-05). cross-context 예외가 배럴 전체를 연다(0929/02-06). 같은 개념 두 벌(1101/16-05) |
|
||||
| 3 | 변경 용이성 | `OOPPPPOPPPPPPPPP` | P | 예제 기능을 빼면 브라우저 spec 8개를 고친다(1103/09-04). poll `execute`를 V3 실행기에 잇는 자리에 타입·대응표가 없다(04-02). 드릴에 맞춘 파일 존재 조건과 파일 단위 제외가 이름 바꾸기·테스트 추가와 함께 검사를 옮긴다(10-01, 12-01). 기능 브랜치 충돌은 결정 대기(1105/16-01). 빌드 입력 기본값 다섯 곳(R-2) |
|
||||
| 4 | 인지 부하 | `PPPPPPOPPPPPPPPP` | P | 같은 사실을 문서마다 다르게 적는다. 저장소 설계 문서의 registry 목록이 절반이다(05-01). 매뉴얼 01이 손 ID의 실패 시점을 두 가지로 적는다(09-01). 두 미출시 절이 TechLog 모양을 다르게 적는다(14-01 b). 계약 문서 bulk 안내(07-01). 두 coordinator가 같은 던짐을 반대로 읽는다(04-01) |
|
||||
| 5 | 위험 가시성 | `PPPPPPOPPPPPPPPP` | P | 결과 불명이 조용히 풀린다(03-01). 증거가 틀린 상태를 통과로 적는다: `a11y.json` 분류(11-01), `check:bundle` 이전 빌드(12-02), 거절된 run의 advisory 기록(13-01), 드릴 요약에 안 나오는 빠진 테스트(10-01, 12-01). 예제를 지운 제품은 lab 기능 라우트가 `measured: false`로 통과한다(1105/15-04). 위험이 커밋 본문에만 있다(08-03, 04-01) |
|
||||
| 6 | 실패 성숙도 | `PPPPPPOPPOO-O>>>` | P | KEYED 같은 키 재전송이 쓰기 전 거절로 끝나면 결과 불명이 풀리고 다음 저장이 새 키다(03-01, Medium·P2). 선언하지 않은 거절 code와 `IDEMPOTENCY_RECOVERY_REQUIRED` 뒤 재전송(1103/03-01). pointer 지속 실패를 일시 오류로 분류한다(02-01). reconnect가 던짐을 서버 장애로 재시도한다(04-01). SSE EOF·`retry:` 미정(0929/04-02·04-03) |
|
||||
| 7 | 운영 성숙도 | `PPPPPP>>P-P>P>P-` | P | `FILE_REJECTED`에 trace가 없다(01-01). 업데이트 설치 실패와 `health()`가 이어지지 않았다(0925/06-05 일부). reconnect는 조합 결함과 서버 장애를 가르지 못한다(04-01). drill에 PASS 경로가 없다(0929/11-02). provider job에 namespace 요구 주석·점검이 없다(1101/13-03) |
|
||||
| 8 | 디버깅 가능성 | `PPOPOPOPOOPPPOOP` | P | 나아진 것: 조립 오류 원인이 한 번 나온다(1105/09-03). 사전 점검이 호스트 원인을 말한다(1105/12-01). 남은 것: `FILE_REJECTED`의 trace·이유(01-01), pointer 지속 실패 신호 없음(02-01), 던짐의 원인 예외(04-01), 사전 점검을 넘긴 뒤 provider test 6건이 원인 없이 시간 초과(1105/12-01 남은 것, 11), TLS 실패는 `error.name`만(13) |
|
||||
| 9 | 유지보수 성숙도 | `PPPPPPPPPPPPPPPP` | P | 낡은 문서: 05-01, 07-01, 09-01(매뉴얼 01 `:476`), 1103/15-02 재발(`performance-evidence.md:209-210`의 26), 14-02(D7 커밋 본문의 옛 해시). 사본: canonical JSON 3벌(0929/05-07), `scopeSnapshot` 4벌(1101/10-08), CSP 6벌(0929/13-04) |
|
||||
| 10 | 테스트 성숙도 | `PPPPPPPPOPPPPPPP` | P | 지난 생존 변이가 거의 모두 잡힌다(01-R1~R4, 02-R2~R9, 03-R2~R7, 04-R1, 08-R3~R6, 09-R1~R3, 10-R1~R4, 11-R1, 15-R2). 남은 틈: 약해진 상한 test(06-02, 06-R3 생존), 드릴 사본의 검출 공백(10-01, 12-01), `notChecked` 분류(11-01), spec 본문 ID(16-01), 테스트 없는 경로(03-01·03-02·07-02·08-01·08-02), 골든이 gutter 띠를 고정(08-03), 예제 제거 드릴이 게이트 밖(1105/14-01 잔여) |
|
||||
| 11 | 데이터 성숙도 | `OP-OPO>-P>-->-->` | P | "승인된 계정 삭제 뒤 bytes 0" 규칙을 이제 지킨다(1103/05-01, 05-R1 50/50, 05-R2 24/24). P는 02·05·09. 계속 읽히지 않는 marker·pointer는 adapter 밖에서만 고친다(1105/02-02 남은 것, 02-01). IndexedDB 롤백 중 계정 삭제가 실패한다(0929/05-05). local-draft ABA는 주석뿐(0925 FOLLOW-UP 09-08) |
|
||||
| 12 | 동시성 성숙도 | `POPOPO-OPOPP>->>` | P | 한 논리 요청의 여러 시도 사이에서 확실성을 합치지 않는다(03-01). 게이트 두 개는 한 checkout에서 함께 돌 수 없다(1105/12-04 일부). reconcile이 partition lock을 쥐지 않는다(05, bytes는 남지 않았다). 두 탭 같은 uploadKey는 단위 테스트뿐(01). 이전 scope 401의 microtask 전환은 재현하지 않았다(09) |
|
||||
| 13 | 확장성 | `PO>P?PO>O>P>>>PP` | P | 생성 기능 둘을 더한 뒤 초기 JS 여유 1,383 B. 같은 크기면 넷째쯤 예산 결정이 필요하다(15-01, 16). 조합 코드가 다른 descriptor를 넘기면 attempt마다 요청이 최대 3번(1103/04-01 잔여 위험). 생성 기능을 설치한 상태의 브라우저 게이트가 없다(1105/16-03). 05는 규모 목표가 없어 ? |
|
||||
| 14 | 성능 성숙도 | `PP>P?P>O>P>?P>P>` | P | lab PASS: LCP 2,032 ms, CLS 0, 상호작용 151 ms, 기능 라우트 402 / 500 ms(로컬 env). 남은 것: 진입 요청 두 묶음(1105/15-04 결정 대기), CSS·라우트 합 예산 없음(1101/15-03), 릴리스마다 사전 캐시 전체 재다운로드(1101/06-05), `tests/unit` 133 → 176 s(1101/10-05). 05·12는 목표·runner가 없어 ? |
|
||||
| 15 | 보안 성숙도 | `OPOOPOOPOO>OP>>>` | P | 운영 high advisory 2건이 결정 대기다(1103/13-03). 승인 정규식 두 벌(0929/05-06), 로그인 복귀 주소(0929/08-08), download media type 짝(1101/02-02). OPFS 계정 삭제 뒤 개인 파일이 남던 경로는 닫혔다(1103/05-01) |
|
||||
| 16 | 의존성 성숙도 | `O->O-P>>->PPPPO>` | P | 1103/13-03. 승인이 거절된 run에는 advisory 기록이 없다(13-01). SBOM이 `deduped`를 따라가지 않는다(0929/13-05). 미사용 `dependency-cruiser`(0929/12-05). 깨끗한 러너의 글꼴 설치 미실행(1103/11-02). 기준점 형식 둘(0929/14-02) |
|
||||
| 17 | API / Contract 성숙도 | `PPPPPPPPPP>POP>P` | P | 답 표 ↔ 사본 ↔ 프론트 표가 게이트에서 잠겼다(1105/07-01). 남은 것: 6.1절 rate-limit 문장(03-02), 03-01이 백엔드 §2 "새 키 금지"를 어긴다, bulk 안내(07-01), 두 칸 없는 응답 행(07-02), poll `input.operation` 타입(04-02), BREAKING 이행 안내(14-01, 09-01), Fileserver 계약이 pin 밖(1105/01-02), `refusalMessages`와 VD-04 결정 5(1103/03-01) |
|
||||
| 18 | 배포 성숙도 | `OP>PPP>O>>P>P>O>` | P | 제품 gate가 release를 막는다(1105/13-02). 남은 것: 워커 스크립트 redirect(06-01), 워커 없는 빌드의 probe 범위(1105/06-02 결정 대기), `assetsDir` 상수(0925/06-08), marker·pointer 지속 실패로 rollback·activate 불가(1105/02-02, 02-01), provider 없는 배포 경로(1101/13-03), 하위 경로(0929/13-06), release run 산출물 미확인(1105/13-01) |
|
||||
| 19 | 설정 성숙도 | `PPPPPPOPOPPPPOOO` | P | 셸의 `RUN_OUTPUT_ROOT`가 빌드 위치만 바꾸고 검사 위치는 그대로다(12-02). `.env*` 입력 갈림(0929/13-02), 기본값 다섯 곳(R-2), `assetsDir` 상수(0925/06-08), locale 목록(0929/08-01), 교차 origin 헤더 허용이 문서뿐(0929/03-02) |
|
||||
| 20 | 개발자 경험 | `P>PP>PPPPPPPPPPP` | P | 안내대로 하면 실패하는 길: bulk(07-01), BREAKING 2단계(14-01 c, 09-01). 저장 중에 떠난 뒤 상세로 이동(08-02). V3 결과 → poll 결과 대응표 없음(04-02). 템플릿 소스와 겹치는 기능 ID로 제거 11단계 실패(1105/16-04 일부, 16-R3). 게이트는 한 checkout에 하나씩(1105/12-04), FE-GATE-020 1,237 s(10) |
|
||||
| 21 | Guardrail 성숙도 | `PPOPPPPOPPPPPPPP` | P | 영역은 모두 P다(03·08은 O). 지난 라운드 X(오케스트레이터 판정)의 두 원인은 닫혔다. FE-GATE-005 탐침은 1105/09-01로 고쳐졌다. FE-GATE-013은 이제 사전 점검에서 이유와 함께 멈춘다(1105/12-01). 다만 이 desktop에서 FE-GATE-013은 여전히 실패하고, 허용 호스트 PASS는 단위 테스트뿐이다. 12 영역은 머지 시점을 ?로 둔다. 남은 틈: 검사가 틀린 답을 낸다(12-02, 12-R2에서 예산 3,504 B 초과 빌드가 PASS). 검사가 좁아졌다(06-02, 10-01, 12-01, 16-01). 지키는 test가 없다(11-01). 예산 상향 폭의 규칙이 없다(15-01). 손 게이트 목록(1105/12-03), 두 단계 경로(0929/12-03), 게이트 밖 드릴(1105/14-01 잔여, 1105/16-03). 다시 X로 둘지는 오케스트레이터가 정한다 |
|
||||
| 22 | 추상화 성숙도 | `OPPPPOOPOPPO>>>P` | P | poll 계약과 실행기 사이 타입이 이어지지 않는다(04-02). 정책이 키 여부만 실어 훅이 NEVER와 IDEMPOTENT를 가르지 못한다(03-03). 저장 결과가 폼 인스턴스에만 있고 페이지가 코디네이터 상태와 손으로 합친다(08, 08-01·08-02의 반복 원인). 읽지 않는 라우트 칸(1103/16-06). kind·effect 두 함수(1101/03-04) |
|
||||
| 23 | 일관성 | `PPPPPPPPPPPPPPPP` | P | 같은 입력을 자리마다 다르게 다룬다. 던짐(poll `PROTOCOL_MISMATCH`, reconnect 재시도, 04-01), redirect(자산 거절, 워커 스크립트 통과, 06-01), IDEMPOTENT(실행기 재전송, 훅 차단, 03-03), 빌드 위치와 검사 위치(12-02), 참조 폼과 생성 폼의 저장 뒤 이동(08-02). 문서와 코드: 03-02, 07-01, 14-01 b. 드릴 맞춤 방법 셋(10-01) |
|
||||
| 24 | 네이밍 / 의미 성숙도 | `PPPPOPPPPPPPOPPP` | P | reconnect의 `PROVIDER_UNAVAILABLE`에 조합 결함이 남는다(04-01). 확인 중에 "변경 사항을 저장하고 있습니다."(08-01). "부팅이 멈춘다"(14-01 a). NEVER·IDEMPOTENT 결과 불명의 출구가 하나다(03-03). `REMOVAL_FIXTURE_DOCUMENT_TESTS` 이름과 동작(12-01), 틀린 근거 ID(10-01). `automatedStatus: "passed"`가 `scope`만 뜻한다(11) |
|
||||
| 25 | 조직 확장성 | `-->-?-OPO->P-P>P` | P | 기능 브랜치 둘의 충돌 자리를 문서와 명령으로 푼다. 충돌 자체는 결정 대기이고 실제 `git merge`는 재현하지 않았다(1105/16-01). 게이트는 한 checkout에 하나씩(1105/12-04). 필드 문구 표·locale 목록이 템플릿 파일이다(08). 다운스트림 모양 fixture가 없다(14). 1인 관리라 01·02·04·06·10·13은 적용 제외 |
|
||||
| 26 | Ownership 성숙도 | `P>P-?OO?>PPPPP>>` | P | Fileserver 계약 대조의 주인이 없다(1105/01-02). 예외 목록에 담당·재검토가 없다(0929/12-07 결정 대기). 다운스트림 결함 후보를 받는 곳이 없다(0929/14-06). owner와 다른 reviewer가 1인 운영에 없다(1103/13-03). 수동 접근성 기록 10건이 `pending-manual-review`다(08, ?). 05는 확인할 대상이 없어 ? |
|
||||
| 27 | 삭제 가능성 | `POOOPOO>PPPP>P>P` | P | 제거 드릴 다섯이 통과한다(FE-GATE-020 rc=0). 남은 것: capability 사본에서 pin 대조가 파일째 빠진다(12-01), 조건부 8개가 말없이 사라진다(10-01), spec 본문 ID를 놓친다(16-01), 겹치는 이름의 거짓 양성(1105/16-04 일부), 예제 제거 드릴이 게이트 밖(1105/14-01 잔여), 읽는 곳 없는 추적 산출물 13개(0929/14-01), 플랫폼 구성 화면은 빠지지 않는다(1103/09-04) |
|
||||
| 28 | 회복 가능성 | `PPPPPP-PO-P-P>>>` | P | active pointer·release marker가 계속 읽히지 않으면 adapter 안에서 돌아올 길이 없다(02-01, 1105/02-02). KEYED 결과 불명의 회복이 새 키로 바뀐다(03-01). IDEMPOTENT 결과 불명은 확인·새로고침뿐(03-03). 다시 마운트한 폼의 확인(08-01). 선언하지 않은 거절 뒤 거짓 성공 버튼(1103/03-01). kill switch의 서빙 전제를 probe가 보지 않는다(06-01). 손상 chunk reference가 reconcile을 막는다(0929/05-01 ③) |
|
||||
|
||||
합계: 충족 0 · 부분 충족 28 · 미충족 0 · 미확인 0 · 적용 제외 0. 지난 라운드는 부분 충족 27 · 미충족 1(21, 오케스트레이터 판정)이었다. 영역 판정 448칸은 O 80 · P 265 · ? 6 · - 25 · > 72다. ?는 05(13, 14, 25, 26), 08(26), 12(14)에 있다. 12는 21을 "P(로컬) · ?(머지 시점)"으로 적었고, 위 표에는 P로 넣었다.
|
||||
|
||||
## 13. 지난 발견 상태 (140건, `bbde570`)
|
||||
|
||||
대상은 넷이다.
|
||||
|
||||
- 1105 색인 48건(지난 §15). 1105/11-02는 지난 라운드에 1105/12-01로 합쳤으므로 12-01 행에서 센다.
|
||||
- 1103 이월 22건(지난 §16.5).
|
||||
- 그 밖의 이월 33건(지난 §16.6).
|
||||
- §16.6에 없지만 영역 문서 2절이 연 이월 37건(ID가 있는 것). ID가 없는 이월 10건은 표 끝에 따로 적는다.
|
||||
|
||||
"지난 §16 판정"은 지난 README §16.4·16.5·16.6의 칸이다. 상태는 고쳐짐(완료 기준을 이 커밋에서 확인) · 일부(남은 것을 적음) · 남음 · 재발 · 틀린 발견이다. 결정 대기·백엔드로 넘김·실행 환경 대기는 상태 뒤에 붙인다. **(판정 정정)**은 지금 상태가 §16의 칸과 다른 것이다. 두 영역이 같은 ID를 보면 한 행으로 적는다. 판정이 갈리면 행에 적고 약한 쪽을 쓴다. 근거는 링크한 영역 문서 2절에 있다.
|
||||
|
||||
재발 확인만 한 지난 고쳐짐 항목(각 영역 2절 끝)은 표에 넣지 않았다. 재발은 1103/15-02 하나다. 판정하지 않은 것(0929/08-06·08-07, 08 영역. 08-06은 16 영역이 1103/16-06에 합쳤다)과 영역이 세지 않은 참고(12 영역의 1101 FOLLOW-UP `noUnusedParameters`·1101 U-1·1103/12-01 보존 조건, 01 영역의 1103 D3)도 넣지 않았다.
|
||||
|
||||
### 13.1 건수
|
||||
|
||||
| 묶음 | 건수 | 고쳐짐 | 일부 | 남음 | 재발 | 틀린 발견 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| 1105 색인(§15) | 48 | 37 | 8 | 3 | 0 | 0 |
|
||||
| 1103 이월(§16.5) | 22 | 7 | 14 | 0 | 1 | 0 |
|
||||
| 그 밖의 이월(§16.6) | 33 | 7 | 8 | 18 | 0 | 0 |
|
||||
| §16.6에 없던 이월 | 37 | 1 | 5 | 31 | 0 | 0 |
|
||||
| 합계 | 140 | 52 | 35 | 52 | 1 | 0 |
|
||||
|
||||
- 결정 대기 22건: 1105/06-02·15-04·16-03, 1103/03-01·03-02·03-07·09-04·12-05·13-03·14-02·16-06, 0929/02-02·02-06·04-02·04-03·12-07·14-06, 1101/02-02·10-05·10-06·10-08·14-07.
|
||||
- 백엔드로 넘김 4건: 1105/01-02, 1105/03-02(고쳐짐), 1103/01-01, 1103/09-03.
|
||||
- 실행 환경 대기 5건: 1105/12-01, 1105/13-01, 1103/11-02·11-03·11-04.
|
||||
- 1105/12-04는 오케스트레이터가 일부로 판정했다(14절).
|
||||
- 1105/10-03(변이 도구 제안)은 조치하지 않아 남음으로 셌다. 10 영역은 세지 않고 오케스트레이터 몫으로 두었다.
|
||||
|
||||
### 13.2 §16과 다른 판정 (15건)
|
||||
|
||||
§16보다 약하게 본 것(9건):
|
||||
|
||||
- 1105/01-02: 고침 · 백엔드로 넘김 → 일부 · 백엔드로 넘김 (01)
|
||||
- 1105/02-02: 고침 → 일부 (02)
|
||||
- 1105/12-01: 고침(PR A) → 일부 · 실행 환경 대기 (11은 일부, 12는 고쳐짐. 약한 쪽)
|
||||
- 1105/12-04: 고침 → 일부 (12 영역 의견, 오케스트레이터 판정 14절)
|
||||
- 1105/13-01: 고침(PR A) → 일부 · 실행 환경 대기 (13)
|
||||
- 1105/16-04: 고침 → 일부 (16)
|
||||
- 1103/15-02: 고침 → 재발 (15. 14는 CHANGELOG 부분만 보고 고쳐짐)
|
||||
- 1101/10-07: 고침 → 일부 (10)
|
||||
- 0929/12-03: 고침 → 일부 (12는 일부, 16은 고쳐짐. 약한 쪽)
|
||||
|
||||
§16보다 강하게 본 것(5건):
|
||||
|
||||
- 1105/14-01: 일부 → 고쳐짐 (14)
|
||||
- 1105/16-01: 일부 → 고쳐짐 (16)
|
||||
- 1103/04-01: 일부 → 고쳐짐 (04. 남은 틈은 완료 기준 밖의 잔여 위험)
|
||||
- 1101/15-01: 남김 → 고쳐짐 (15)
|
||||
- 1101/15-04: 남김 → 일부 (15)
|
||||
|
||||
표기만 다른 것(1건):
|
||||
|
||||
- 1105/12-03: 매뉴얼 PR에 포함 → 남음 (12. 고친 커밋은 PR #6 브랜치에만 있다. §16.4도 PR B에는 없다고 적었다)
|
||||
|
||||
§16과 다르지 않지만 적어 둘 것:
|
||||
|
||||
- 1103/03-01은 §16.5대로 일부다. 08 영역이 §16.5에 없는 남은 것 둘을 더 적었다(선언하지 않은 code, VD-04 결정 5).
|
||||
- 1103/09-03의 §16.5 "백엔드로 넘김"을 09 영역은 "일부 · 백엔드로 넘김"으로 적었다. 남은 것이 백엔드 쪽이라는 같은 뜻이다.
|
||||
- 1105/12-01의 §16.2 D4가 PR A로 적은 기준선 `67082cc`는 PR B(`c3c595f`)로 들어왔다(12 영역). 기록 오류이고 지금 상태는 맞다.
|
||||
- 0925/06-05는 §16에 없다. 지난 영역 문서의 남음을 06 영역이 일부로 올렸다.
|
||||
|
||||
### 13.3 §16.6이 빠뜨린 열린 이월 (36건)
|
||||
|
||||
§16.6은 "영역 문서 2절 '남음'"을 모은다고 적었다. 아래는 영역 문서 2절이 열려 있다고 적었는데 §16.6에 없던 것이다. 지금도 모두 열려 있다(1101 R4만 고쳐짐이라 뺐다).
|
||||
|
||||
- 01 (4): 1101/01-03, 0929/01-03, 0929/01-04, 0929/01-05. FOLLOW-UP 셋과 1103/01-02 함께 볼 것 하나도 ID 없이 남았다.
|
||||
- 02 (1): 0929/02-03.
|
||||
- 03 (2): 1101/03-04, 0929/03-02.
|
||||
- 05 (6): 0929/05-01, 1101/05-06, 0929/05-05, 0929/05-06, 0929/05-07, 0929/05-10.
|
||||
- 06 (8): 0925/06-05, 0925/06-08, 0925 P3, 1101/06-03, 1101/06-05, 1101 R1, 1101 R2, 1101 R3.
|
||||
- 08 (2): 0929/08-01, 0929/08-08.
|
||||
- 09 (2): 0925 FOLLOW-UP 09-07, 0925 FOLLOW-UP 09-08.
|
||||
- 11 (3): 0929/11-02, 0929/11-05, 0929/11-07. FOLLOW-UP 둘도 있다(하나는 06의 0925 P3와 같은 항목).
|
||||
- 13 (8): 1101/13-03, 0929/13-02, 0929/13-03, 0929/13-04(= R-3), 0929/13-05, 0929/13-06, 0929/13-10, R-2.
|
||||
- 10: ID 없는 작은 이월 다섯(13.5절).
|
||||
|
||||
### 13.4 상태 표
|
||||
|
||||
| ID | 지난 §16 판정 | 지금 상태 | 근거·남은 것 | 판정한 영역 |
|
||||
|---|---|---|---|---|
|
||||
| [1105/01-01](01-adapters-browser-transfer.md) | 고침 | 고쳐짐 | 202 `REJECTED`가 `FILE_REJECTED`·`NOT_APPLIED`가 되고(`fileserver-upload.ts:681-689`), 빈 파일은 `FILE_EMPTY`다. 실제 백엔드 업로드는 하지 않았다. 남은 진단 빈틈은 새 01-01 | 01 |
|
||||
| [1105/01-02](01-adapters-browser-transfer.md) | 고침 · 백엔드로 넘김 | 일부 · 백엔드로 넘김 **(판정 정정)** | `TRANSFER_TIMEOUT`이 `NOT_APPLIED` 목록에서 빠졌다(`fileserver-upload.ts:194-199`, 01-R2 검출). 남은 것: Fileserver code 표와 202 state 해석이 pin 대조 밖이다(`check-backend-contract-drift.ts`에 Fileserver 0건). 커밋 `471b001` 본문의 백엔드 방법 (b)는 보장을 주지 못한다(`BlockingTransferExecutor.java:72-79`) | 01 |
|
||||
| [1105/01-03](01-adapters-browser-transfer.md) | 고침 | 고쳐짐 | Envelope 실패가 `traceId`를 싣는다(`fileserver-upload.ts:701-708`, 테스트 18행) | 01 |
|
||||
| [1105/01-04](01-adapters-browser-transfer.md) | 고침 | 고쳐짐 | FS4'·FS5·FS8 변이가 각각 기대한 테스트에서 실패했다(01-R1·R3·R4) | 01 |
|
||||
| [1105/02-01](02-adapters-browser-files-cache.md) | 고침 | 고쳐짐 | label 진단 한 건을 `toEqual`로 고정한다(`runtime-adapters-product-scope-participants.test.ts:160-197`), 02-R9 검출. 09 영역: 조립 쪽 발견 없음. 작은 잔여: label 중복을 막지 않는다 | 02, 09 |
|
||||
| [1105/02-02](02-adapters-browser-files-cache.md) | 고침 | 일부 **(판정 정정)** | asset entry는 다시 stage로 고친다. release marker 본문이 계속 읽히지 않으면 stage가 다시 쓰지 않고 rollback 대상이 돌아오지 못한다(`public-response-cache-adapter.ts:463-468`, 02-R1 X1·X2). 설계 문서와 포트 주석이 범위를 넓게 적는다(`cache-storage-ports.ts:66-69`) | 02 |
|
||||
| [1105/02-03](02-adapters-browser-files-cache.md) | 고침 | 고쳐짐 | 레시피 주석이 매뉴얼과 같은 파일을 가리킨다(`browser-file-session-capability.ts:21-33`), 02-R8 검출 | 02 |
|
||||
| [1105/02-04](02-adapters-browser-files-cache.md) | 고침 | 고쳐짐 | 표 테스트 6행(`public-response-cache-repair.test.ts:541-597`). 변이 넷 검출, `INTEGRITY_FAILED` 변이는 동등 변이 | 02 |
|
||||
| [1105/03-01](03-adapters-http-state.md) | 고침(BREAKING) | 고쳐짐 | 6.1절 "쓰기 뒤 가능" 플랫폼 code 20개를 조립이 거절한다(`external-contract-runtime.ts:638-663`), 03-R4~R6 검출 | 03 |
|
||||
| [1105/03-02](03-adapters-http-state.md) | 고침 · 백엔드로 넘김 | 고쳐짐 · 백엔드로 넘김 | 503 `RATE_LIMIT_*` 둘이 `NOT_APPLIED`다(`backend-envelope.ts:177-181`), 03-R7 검출. 이 수정이 새 03-01의 길을 넓히고 03-02를 만들었다 | 03 |
|
||||
| [1105/04-01](04-adapters-realtime.md) | 고침 | 고쳐짐 | 조합 transport `OFFLINE` 테스트 둘(`realtime-reconnect-coordinator.test.ts:2206`, `:2246`), MR1 검출(04-R1) | 04 |
|
||||
| [1105/04-02](04-adapters-realtime.md) | 고침(BREAKING) | 고쳐짐 | 던지는 `execute`가 재시도 없이 `PROTOCOL_MISMATCH`다(`bounded-poll-coordinator.ts:336-347`). reconnect가 반대로 읽는 것은 새 04-01 | 04 |
|
||||
| [1105/04-03](04-adapters-realtime.md) | 고침 | 고쳐짐 | VD-28·설계 3절이 V3 descriptor 규칙을 적는다(`VD-28-…md:117-120`). V2 칸 `git grep` 0건 | 04 |
|
||||
| [1105/05-01](05-adapters-storage-kernel.md) | 고침 | 고쳐짐 | recipe 키가 registry `physicalKey`다(`oidc-pkce-session-owner.ts:51-52`). 글자 회귀는 테스트가 못 잡는다. `orphanExemptRows` 추가는 게이트 결과를 바꾸지 않는다(05-R4) | 05 |
|
||||
| [1105/06-01](06-adapters-service-worker-push.md) | 고침 | 고쳐짐 | 수집기가 `BUILD_ASSET_DIRECTORY` 아래만 본다(`generate-service-worker-assets.ts:73-75`) | 06 |
|
||||
| [1105/06-02](06-adapters-service-worker-push.md) | 일부 | 일부 · 결정 대기 | redirect FAIL과 live 분기 함수 테스트가 들어왔다(06-R2 검출). 워커 없는 빌드의 probe 범위는 결정 대기이고, 이제 redirect까지 넓어졌다(`hosting-probe.ts:327`) | 06 |
|
||||
| [1105/06-03](06-adapters-service-worker-push.md) | 고침 | 고쳐짐 | 옛 탭 route test가 chromium·webkit에서 통과하고, 워커 fallback을 끊으면 두 엔진이 잡는다(06-R1) | 06 |
|
||||
| [1105/07-01](07-contracts.md) | 고침 | 고쳐짐 | 답 표를 pin 커밋 표 사본과 행마다 대조한다(`backend-contract-pin.test.ts:165-179`, 07-R2). desktop drift rc=0(07-R3). 사본 ↔ 실제 백엔드는 게이트 밖(D6) | 07 |
|
||||
| [1105/07-02](07-contracts.md) | 고침 | 고쳐짐 | 응답 행이 `REJECT_UNKNOWN`으로 좁혀지면 breaking이다(`registry-compatibility.ts:149-161`), 07-R1 registries-rc=1. 두 칸 없는 행은 새 07-02 | 07 |
|
||||
| [1105/08-01](08-presentation.md) | 고침 | 고쳐짐 | 복구 뒤 포커스가 feedback 자리로 간다(`use-app-form.ts:123-135`), e2e 3엔진, 08-R3 검출. 다시 마운트한 폼은 새 08-01 | 08 |
|
||||
| [1105/08-02](08-presentation.md) | 고침 | 고쳐짐 | 확인 뒤 목록으로 이동한다(`create-feature-write-slice.ts:724-731`). 짝 백엔드 목록 GET 없음은 1103/03-07 | 08 |
|
||||
| [1105/08-03](08-presentation.md) | 고침 | 고쳐짐 | 셸과 홈이 `activeNavigationRoutes` 하나를 쓴다(`navigation-policy.ts:14-21`), 08-R4 검출. 공유 청크는 새 요청 단계를 만들지 않는다 | 08 |
|
||||
| [1105/08-04](08-presentation.md) | 고침 | 고쳐짐 | 다른 저장 중 버튼을 끄고 진행 문구를 보인다(`reference-resource-form-page.tsx:60-61`), 08-R5 검출 | 08 |
|
||||
| [1105/09-01](09-app-core.md) | 고침(PR A) | 고쳐짐 | 탐침이 제품 파일을 옆 이름으로 옮겨 덧붙인다(`product-extension-typecheck.test.ts:267-281`), 09-R1 검출 | 09 |
|
||||
| [1105/09-02](09-app-core.md) | 고침 | 고쳐짐 | 조립 루트가 `notifySessionUnauthenticated`를 준다(`runtime-adapters.ts:705`), 09-R2 검출. 그 한 줄을 뺀 제품을 막는 검사는 없다(`CHANGELOG.md:107`) | 09 |
|
||||
| [1105/09-03](09-app-core.md) | 고침 | 고쳐짐 | 원인이 한 번 나온다(`check-registries.ts:160-168`, `registry-governance.test.ts:656-711`) | 07, 09 |
|
||||
| [1105/10-01](10-tests-fast-layers.md) | 고침 | 고쳐짐 | `createRuntimeContractHttpExecutor`로 뺐다(`runtime-adapters.ts:284-319`). H53·L02 검출(10-R1·R2), 샘플 제거 사본에서 돈다 | 10 |
|
||||
| [1105/10-02](10-tests-fast-layers.md) | 고침 | 고쳐짐 | interaction signal까지 감시한다(`http-execution-v3.test.ts:812-867`), R2b 검출(10-R3) | 10 |
|
||||
| [1105/10-03](10-tests-fast-layers.md) | 제안으로 남김 | 남음(제안) | 변이 도구를 들이지 않았다. 10 영역은 세지 않고 오케스트레이터 몫으로 두었다 | 10 |
|
||||
| [1105/11-01](11-tests-browser-release-scale.md) | 고침 | 고쳐짐 | 판정을 `browserFailureVerdict` fixture로 빼고 증명 spec이 기록 줄을 대조한다(`preload-use.spec.ts:180-202`). 변이 셋을 3엔진이 잡는다(11-R1) | 11 |
|
||||
| [1105/12-01](12-guardrails-ci.md) (+ 1105/11-02) | 고침(PR A) | 일부 · 실행 환경 대기 **(판정 정정)** | **영역이 갈렸다.** 12는 고쳐짐: 사전 점검이 `bwrap … /bin/true`를 띄워 이유와 함께 멈춘다(`check-system-test-prerequisites.ts:39-43`, `FE-GATE-013.txt`). 11은 일부: 허용 호스트 PASS는 가짜 호스트 단위 테스트뿐이고, provider test 6건은 여전히 원인 없이 시간 초과다(`ci-artifact-contract.test.ts:1782`, `:1812`). 약한 쪽을 쓴다 | 12, 11 |
|
||||
| [1105/12-02](12-guardrails-ci.md) | 고침 | 고쳐짐 | 짝 백엔드 참조를 pin 커밋 트리에서 찾는다(`verify-documentation-readiness.ts:245-285`) | 12 |
|
||||
| [1105/12-03](12-guardrails-ci.md) | 매뉴얼 PR에 포함(PR B 없음) | 남음 | `CLAUDE.md:23`이 그대로 명령 11개다. `e9d9c36`은 PR #6 브랜치에만 있다. `README.md:343`도 손 목록이다 | 12 |
|
||||
| [1105/12-04](12-guardrails-ci.md) | 고침 | 일부 **(판정 정정)** | e2e 두 실행은 한 checkout에서 함께 통과했다(오케스트레이터 드릴, 222+222). 완료 기준의 게이트 단위("FE-GATE-008 둘을 동시에")는 닫히지 않았다. `ci:gate`와 증거 검사가 루트 `dist`·`artifacts/`를 읽는다(`README.md:362-363`, M1). 수정이 새 12-02를 만들었다 | 12 |
|
||||
| [1105/13-01](13-build-release-supply-chain.md) | 고침(PR A) | 일부 · 실행 환경 대기 **(판정 정정)** | `if: always()` upload 단계와 계약이 들어왔다(`quality-gates.yml:210-223`, `ci-gates.ts:1159-1219`). 파일 쪽은 CI env로 확인했다(13-R1). release run의 산출물은 runner가 없어 미확인. 거절된 run의 advisory 기록 누락은 새 13-01 | 13 |
|
||||
| [1105/13-02](13-build-release-supply-chain.md) | 고침 | 고쳐짐 | `release_gate`가 `product_merge_gate`를 기다린다(`generate-ci-workflow.ts:68-78`). `check:ci`가 연결 없는 workflow를 거절한다. 실제 Gitea의 `needs` 처리는 미확인 | 13 |
|
||||
| [1105/14-01](14-template-product-docs.md) | 일부 | 고쳐짐 **(판정 정정)** | 완료 기준 셋을 확인했다. 문서 검사 예외(`verify-documentation-readiness.ts:190-208`, 14-R2), 드릴 PASS 17 checks(14-R1), `PRODUCT.md:33`. 드릴이 게이트 밖인 것은 통제 잔여 | 14 |
|
||||
| [1105/14-02](14-template-product-docs.md) | 고침 | 고쳐짐 | 매뉴얼 블록을 사본에서 tsc로 본다(`manual-paired-backend-settings.test.ts:112-144`), 14-R4 검출 | 14 |
|
||||
| [1105/14-03](14-template-product-docs.md) | 고침 | 고쳐짐 | 경로를 다시 백틱으로 적었다. 파일 이름을 바꾸면 `verify:documentation`이 실패한다(14-R3) | 14 |
|
||||
| [1105/15-01](15-performance.md) | 고침 | 고쳐짐 | 요약 전후에 같은 칸을 그린다(`platform-overview-page.tsx:63-78`). 직접 진입 CLS 표본 0 × 5 | 15 |
|
||||
| [1105/15-02](15-performance.md) | 고침 | 고쳐짐 | 허용치가 256 B다(`measure-feature-shape-growth.ts:219-227`). +448 B 빌드에서 대조가 실패했다(15-R2) | 15 |
|
||||
| [1105/15-03](15-performance.md) | 고침 | 고쳐짐 | 목록이 한 곳이다(`vite-build-inputs.ts:11-21`) | 15 |
|
||||
| [1105/15-04](15-performance.md) | 일부 | 일부 · 결정 대기 | lab이 기능 라우트를 500 ms로 잰다(402 ms). 진입 두 묶음은 결정 대기. 더 남은 것: 생성 라우트가 모두 `session-required`라 lab 대상이 못 된다(`create-feature.ts:578`) | 15 |
|
||||
| [1105/15-05](15-performance.md) | 고침 | 고쳐짐 | `scrollbar-gutter: stable`(`base.css:6-11`), 18회 모두 shift 0(15-R3). 가림막·header 띠는 새 08-03 | 15 |
|
||||
| [1105/16-01](16-structure-patterns.md) | 일부 | 고쳐짐 **(판정 정정)** | 완료 기준의 둘째 길을 채웠다. 03 A절과 정본 표가 두 파일과 충돌 처리 명령을 적고(`03-outside-feature-folder.md:36-44`), `feature-tracked-files.test.ts`가 대조한다. 충돌 자체는 결정 대기(`CHANGELOG.md:97`) | 16 |
|
||||
| [1105/16-02](16-structure-patterns.md) | 고침 | 고쳐짐 | pin `scaffoldSources` 여섯 항목(`backend-contract-pin.json:8-39`)을 drift가 본다. drift는 게이트 밖 | 16 |
|
||||
| [1105/16-03](16-structure-patterns.md) | 결정 대기 | 남음 · 결정 대기 | 드릴 제외 목록이 그대로다(`feature-scaffold-drill.ts:18-46`). 손으로 돌린 `test:a11y`는 69건 통과(16-R4). CI 장치는 없다 | 16 |
|
||||
| [1105/16-04](16-structure-patterns.md) | 고침 | 일부 **(판정 정정)** | `tests` 쪽은 고쳤다(`feature-residue.ts:46-60`, 16-R2 PASS). `src`·`dist`는 여전히 대소문자 무시 부분 문자열이다(`feature-residue.ts:45-56`). `product-feature`로 11단계 rc=1, 템플릿 파일 20개(16-R3). 좁힌 `tests` 판정의 빈틈은 새 16-01 | 16 |
|
||||
| [1103/01-01](01-adapters-browser-transfer.md) | 일부 · 백엔드로 넘김 | 일부 · 백엔드로 넘김 | 프론트 몫은 끝났다. 백엔드 매뉴얼에 안내가 없고(`45d2a478:docs/manual/03-placement.md:30`), 백엔드 계약은 202 `VERIFYING`만 적는다(`docs/fileserver/http-contract.md:10`). 짝 백엔드 업로드는 하지 않았다 | 01 |
|
||||
| [1103/03-01](03-adapters-http-state.md) | 일부(결정 대기) | 일부 · 결정 대기 | 거절 문구 자리 `refusalMessages`가 생겼다(`use-app-form.ts:50-59`, 08-R6). 남은 것: 500 `IDEMPOTENCY_RECOVERY_REQUIRED` 뒤 재전송 버튼(`backend-envelope.ts:271-276`). 08이 §16.5에 없는 둘을 더 적었다. 선언하지 않은 code가 "변경됨으로 확인"으로 "저장했습니다."가 된다. 선언한 409를 필드 오류로 바꿔 VD-04 결정 5와 어긋난다(`VD-04-native-form-facade.md:26`). Medium·P2 | 03, 08 |
|
||||
| [1103/03-02](03-adapters-http-state.md) | 결정 대기 | 일부 · 결정 대기 | `meta.page`는 읽는다. bulk `results` 미지원은 계약 4.1에 적혀 있다(`backend-api-and-server-state-contract.md:205-207`) | 03 |
|
||||
| [1103/03-07](03-adapters-http-state.md) | 결정 대기 | 일부 · 결정 대기 | 백엔드 생성기가 `POST`와 `GET /{id}`만 만든다(`__Feature__Controller.java.tmpl:49`, `:63`) | 03 |
|
||||
| [1103/05-01](05-adapters-storage-kernel.md) | 고침 | 고쳐짐 | 끝까지 돈 purge는 늘 partition 삭제다(`opfs-byte-store-adapter.ts:900`, `:926-929`). 05-R1 50/50, 05-R2 Chromium·Firefox 24/24, 되돌리면 8건 실패(05-R3) | 05 |
|
||||
| [1103/07-04](07-contracts.md) | 고침 | 고쳐짐 | 부팅 오류가 키 경로를 싣는다(`env.ts:125-170`, `load-runtime-config.ts:126-137`) | 07 |
|
||||
| [1103/09-03](09-app-core.md) | 백엔드로 넘김 | 일부 · 백엔드로 넘김 | 쿠키 모드 401은 1105/09-02로 고쳤다. 실제 Keycloak·Redis는 돌리지 않았고, pin realm에 public client가 없다(`ca-skeleton-realm.json` 59·62행) | 09 |
|
||||
| [1103/09-04](09-app-core.md) | 결정 대기 | 일부 · 결정 대기 | `EXAMPLES_PLATFORM`이 플랫폼 레지스트리에 있다(`routes.ts:33-45`). 예제 라우트를 쓰는 브라우저 spec 8개 그대로 | 09 |
|
||||
| [1103/09-05](09-app-core.md) | 일부 | 일부 | `ProductComposition.serviceWorker`로 blockers·observe를 잇는다(`product-composition-contract.ts:127-139`, 09-R3 검출). 활성화 화면 자리가 없다. realtime·worker·offline은 `optional-runtime-host.ts:55-65`에서 거절된다 | 06, 09 |
|
||||
| [1103/11-01](11-tests-browser-release-scale.md) | 고침(BREAKING) | 고쳐짐 | `a11y.json` schema 2에 `notChecked`가 있다(`write-a11y-report.ts:14-26`). 생성 기능 상세도 `notChecked`(11-R3). 분류를 지키는 test가 없는 것은 새 11-01 | 11 |
|
||||
| [1103/11-02](11-tests-browser-release-scale.md) | 실행 환경 대기 | 일부 · 실행 환경 대기 | workflow가 글꼴 넷을 설치한다(`quality-gates.yml:74`, `:113`). 깨끗한 Ubuntu 24.04에서 6/6은 돌리지 않았다 | 11 |
|
||||
| [1103/11-03](11-tests-browser-release-scale.md) | 실행 환경 대기 | 일부 · 실행 환경 대기 | 코드 그대로. 이 호스트에서는 provider가 뜨지 않아 `kills descendants` 단독 실행을 할 수 없다 | 11 |
|
||||
| [1103/11-04](11-tests-browser-release-scale.md) | 실행 환경 대기 | 일부 · 실행 환경 대기 | 가림 코드 그대로(`run-and-validate-provider.ts:278-293`). 새 test 둘도 bwrap 오류로 실패한다 | 11 |
|
||||
| [1103/12-05](12-guardrails-ci.md) | 일부 | 일부 · 결정 대기 | `e72fb6e`가 예 한 곳만 고쳤다. 지운 심볼과 1절 밖 문서 검사는 결정 대기 | 12 |
|
||||
| [1103/13-03](13-build-release-supply-chain.md) | 결정 대기 | 일부 · 결정 대기 | 운영 high 2건 그대로(`package.json:160-161`, 13-R1 B `POLICY_VIOLATION`). D7 뒤 react-router 갱신(약 470 B)은 예산 안, zod(약 7 KB)는 넘는다 | 13 |
|
||||
| [1103/14-01](14-template-product-docs.md) | 고침 | 고쳐짐 | 초기 파일 상한 32, 범위 끝 `8a44226`(`CHANGELOG.md:207`, `:317`, `:359`) | 14 |
|
||||
| [1103/14-02](14-template-product-docs.md) | 일부 | 일부 · 결정 대기 | "옮기기 전" 수가 두 repo와 같다(`CHANGELOG.md:133-139`). memento 모양에 적용한 `check:registries`는 돌리지 않았다. 자리 없는 파일은 결정 대기 | 14 |
|
||||
| [1103/15-02](15-performance.md) | 고침 | 재발 **(판정 정정)** | **영역이 갈렸다.** 14는 CHANGELOG 부분을 고쳐짐으로 봤다(`CHANGELOG.md:207`, `:317`이 32). 15는 재발: 살아 있는 문서 `performance-evidence.md:209-210`이 템플릿 초기 파일을 26으로 적는다. 지금은 27이다(`feature-shape-ceilings.json:63`). 약한 쪽을 쓴다 | 15, 14 |
|
||||
| [1103/16-01](16-structure-patterns.md) | 고침(BREAKING) | 고쳐짐 | `responseEnvelope`가 필수 칸이다(`external-contract-runtime.ts:239`). 읽기만 있는 생성 기여에서 줄을 빼도 TS1360(16-R1). bulk 안내 한 줄은 새 07-01 | 07, 16 |
|
||||
| [1103/16-05](16-structure-patterns.md) | 고침(BREAKING) | 고쳐짐 | brand 타입 `MutationOperationId`(`server-state.ts:276-278`). `@ts-expect-error`가 FE-GATE-003에서 쓰였다. 이행 안내의 빈칸은 새 09-01 | 09, 16 |
|
||||
| [1103/16-06](16-structure-patterns.md) | 결정 대기 | 일부 · 결정 대기 | 화면이 읽지 않는 라우트 `title`·`navigationLabel`을 생성기가 채운다(`create-feature.ts:582-583`). 0929/08-06을 여기에 합쳤다 | 16 |
|
||||
| [0929/03-03](03-adapters-http-state.md) | 고침 | 고쳐짐 | 훅이 키 없는 같은 입력을 보내지 않고(`application-query.ts:569-583`), 화면은 `=== true`일 때만 버튼을 그린다(`async-surface.tsx:227-229`). 03-R2·R3 검출. IDEMPOTENT까지 막는 부작용은 새 03-03 | 03, 08 |
|
||||
| [1101/02-04](02-adapters-browser-files-cache.md) | 고침 | 고쳐짐 | host `storageArea` 비교 테스트(`cross-tab-invalidation.test.ts:392-481`), N38 검출(02-R7) | 02 |
|
||||
| [0929/10-04](10-tests-fast-layers.md) | 고침 | 고쳐짐 | `isCurrent`만 false로 바꾸는 테스트(`http-execution-v3.test.ts:574-620`), L01 검출(10-R4). 네 라운드 만에 닫혔다 | 10 |
|
||||
| [0929/10-05](10-tests-fast-layers.md) | 고침 | 고쳐짐 | `test:all`이 `test:coverage`의 Vitest 경로를 모두 돈다(`package.json:85`, `test-all-paths.test.ts:20-31`) | 10 |
|
||||
| [1101/10-07](10-tests-fast-layers.md) | 고침 | 일부 **(판정 정정)** | SW 5초 대기는 8 ms가 됐다. RPC는 1초를 자는 3개가 여전히 1.03~1.07 s다(`browser-rpc-remediation.test.ts:389`, `:412`, `:588`). 수정이 이미 빠른 3개에 시계를 넣었다. 이 수정이 marker 상한을 넓힌 것은 새 06-02 | 10 |
|
||||
| [0929/12-03](12-guardrails-ci.md) | 고침 | 일부 **(판정 정정)** | **영역이 갈렸다.** 16은 고쳐짐: `support/`·`contracts/` → `src/adapters` 직접 간선이 막혔다(fixture 31). 12는 일부: 계층 밖 폴더 → 자기 기능 `adapters/` → `src/adapters`의 두 단계 경로가 `check:architecture`·ESLint를 통과한다(12-R3, `.dependency-cruiser.json:309-311`). 16도 대표 판정을 12에 두었다. 약한 쪽을 쓴다 | 12, 16 |
|
||||
| [1101/14-02](14-template-product-docs.md) | 고침 | 고쳐짐 | 리뷰 ID 네 꼴(`CHANGELOG.md:11`)을 `changelog-review-ids.test.ts:36-49`가 막는다 | 14 |
|
||||
| [0929/14-05](14-template-product-docs.md) | 고침 | 고쳐짐 | `ci-quality-gates.md:69`가 코드와 같다 | 14 |
|
||||
| [1103/04-01](04-adapters-realtime.md) | 일부 | 고쳐짐 **(판정 정정)** | 원래 완료 기준(`retryBudget > 0` 거절, poll 3회 = 요청 3회)을 채운다. `27e3dec`가 생성 때 잡은 객체를 `input.operation`으로 넘긴다(`bounded-poll-coordinator.ts:149-150`, `:322-328`). 조합 코드가 그것을 무시하면 3배가 되는 것은 잔여 위험(`CHANGELOG.md:103`) | 04 |
|
||||
| [0929/02-02](02-adapters-browser-files-cache.md) | 일부 | 일부 · 결정 대기 | 비용과 `verified`의 뜻이 포트 주석에 있다(`cache-storage-ports.ts:55-70`), M05 검출(02-R6). `inspect()`에 signal이 없고 판정 불가와 손상이 같은 `false`다 | 02 |
|
||||
| [0929/14-01](14-template-product-docs.md) | 일부 | 일부 | `SPEC.md`·`tasks/`의 이유를 맞췄다. 더 남은 것: 읽는 곳 없는 추적 산출물 13개(`artifacts/tests/coverage-gateway/` 10, `artifacts/local-preview/*.png` 3) | 14 |
|
||||
| [0929/14-02](14-template-product-docs.md) | 일부 | 일부 | 범위 반영 명령을 적었지만(`README.md:396-404`) 돌리지 않았다. 기준점 형식이 둘이고 `:407`·`:408`·`:418-419` 문장이 어긋난다 | 14 |
|
||||
| [0929/14-03](14-template-product-docs.md) | 일부 | 일부 | 두 제품의 수정 파일 분류는 빠짐이 없다. README 표와 충돌 경로 측정은 없다 | 14 |
|
||||
| [1101/02-02](02-adapters-browser-files-cache.md) | 결정 대기 | 일부 · 결정 대기 | `browser-files/` 변경 0줄. media type과 확장자 짝을 보지 않는다(`browser-file-policy-registry.ts:448-456`) | 02 |
|
||||
| [0929/02-06](02-adapters-browser-files-cache.md) | 결정 대기 | 남음 · 결정 대기 | 예외가 배럴 전체를 연다(`.dependency-cruiser.json:261`). 쓰는 것은 `import type` 하나 | 02 |
|
||||
| [0929/04-02](04-adapters-realtime.md) | 결정 대기 | 남음 · 결정 대기 | SSE 코드 diff 0줄. 도구는 `readSseForReconnect` 하나(`fetch-sse-connection.ts:498-513`), EOF 분류 미정 | 04 |
|
||||
| [0929/04-03](04-adapters-realtime.md) | 결정 대기 | 남음 · 결정 대기 | `sse-parser.ts:330-341` 그대로. 설계 5.3·6.3과 다르다 | 04 |
|
||||
| [0929/14-06](14-template-product-docs.md) | 결정 대기 | 남음 · 결정 대기 | 첫 결함 후보가 CHANGELOG에 들어왔다(`CHANGELOG.md:139`). 받는 곳은 정하지 않았다 | 14 |
|
||||
| [1101/14-07](14-template-product-docs.md) | 결정 대기 | 남음 · 결정 대기 | `docs/README.md:67-79`가 그대로 섞여 있다 | 14 |
|
||||
| [1101/10-05](10-tests-fast-layers.md) | 결정 대기 | 남음 · 결정 대기 | 커졌다. 도구·import 없는 파일이 `tests/unit` 시간의 76%(지난 71%), 합 133.1 → 175.7 s | 10 |
|
||||
| [1101/10-06](10-tests-fast-layers.md) | 결정 대기 | 남음 · 결정 대기 | 한 머지에 `tests/unit` 13번 그대로. FE-GATE-020 1,156 → 1,237 s | 10 |
|
||||
| [1101/10-08](10-tests-fast-layers.md) | 결정 대기 | 남음 · 결정 대기 | `scopeSnapshot` 4벌, `as never` 10곳, `deferred()` 7벌 | 10 |
|
||||
| [0929/12-07](12-guardrails-ci.md) | 결정 대기 | 남음 · 결정 대기 | 스키마가 `script`·`reason`뿐이다(`ungated-scripts.ts:17-30`) | 12 |
|
||||
| [0929/12-01](12-guardrails-ci.md) | 남김 | 남음 | `check-request-fanout.ts:23`, `:109` 그대로 | 12 |
|
||||
| [0929/12-04](12-guardrails-ci.md) | 남김 | 남음 | 기준선(`contract-baseline.json:6-8`)과 테스트 상수(`ci-workflow-generation.test.ts:199-203`) 두 곳 | 12 |
|
||||
| [0929/12-05](12-guardrails-ci.md) | 남김 | 남음 | `package.json:182`의 `dependency-cruiser`를 쓰지 않는다 | 12 |
|
||||
| [0929/12-06](12-guardrails-ci.md) | 남김 | 남음 | `ungated-tests.ts:18`, `:94-95`. Vitest는 `*.test.*`만 돈다 | 12 |
|
||||
| [1101/12-03](12-guardrails-ci.md) | 남김 | 남음 | 디자인 규칙 파일에 커밋 0개 | 12 |
|
||||
| [1101/15-01](15-performance.md) | 남김 | 고쳐짐 **(판정 정정)** | 완료 기준 둘을 채운다. FE-GATE-012가 merge에 있고 예산+1 fixture가 통과한다. 문서가 숫자 대신 기록을 가리킨다(`performance-evidence.md:22-25`). 여유 문제는 D7이 정했고 그 판단은 새 15-01 | 15 |
|
||||
| [1101/15-03](15-performance.md) | 남김 | 남음 | 초기 JS 파일만 더한다(`check-bundle.ts:38-47`). CSS 8.81 kB gzip, 라우트 lazy 합 예산 없음 | 15 |
|
||||
| [1101/15-04](15-performance.md) | 남김 | 일부 **(판정 정정)** | SW 5초 대기는 `ce191be`로 사라졌다(64건 320 ms). `tests/setup.ts:1-2`의 RTL 전역 로드와 자식 프로세스 테스트가 남았다 | 15 |
|
||||
| [0929/11-04](15-performance.md) | 남김 | 남음 | 부하는 기록만 한다(`test-performance.ts:244`). 기능 라우트 예산으로 같은 크기의 판정이 하나 늘었다 | 11, 15 |
|
||||
| [1101/16-05](16-structure-patterns.md) | 남김 | 남음 | 오류 경계 두 벌, `TelemetryPort` 두 타입, 폐기 재수출(`application/result.ts:9`) | 16 |
|
||||
| [1101/16-06](16-structure-patterns.md) | 남김 | 남음 | 생성기가 기능 `contracts/`에 mapper·문구를 쓴다(`create-feature.md:50-53`) | 16 |
|
||||
| [1101/01-03](01-adapters-browser-transfer.md) | §16.6에 없음 | 남음 | copyFactor가 설정값이다(`runtime-policy.ts:12`, `:68`) | 01 |
|
||||
| [0929/01-03](01-adapters-browser-transfer.md) | §16.6에 없음 | 남음 | 업링크 기본값이 세 곳이다(`resumable-upload-runtime.ts:1045-1049`, `fileserver-upload.ts:164-165`) | 01 |
|
||||
| [0929/01-04](01-adapters-browser-transfer.md) | §16.6에 없음 | 남음 | `check-adapter-inventory.ts:139-144`가 4파일을 이름으로 고정한다 | 01 |
|
||||
| [0929/01-05](01-adapters-browser-transfer.md) | §16.6에 없음 | 남음 | `abort()` recovery의 행동 표가 없다(`resumable-upload.ts:105-127`) | 01 |
|
||||
| [0929/02-03](02-adapters-browser-files-cache.md) | §16.6에 없음 | 남음 | CHANGELOG 0.2.0 browser-files [계약] 행의 경로가 틀리다(`CHANGELOG.md:418`) | 02 |
|
||||
| [1101/03-04](03-adapters-http-state.md) | §16.6에 없음 | 남음 | 효과 판정과 화면 분류가 두 함수다(`backend-envelope.ts:352-363`, `:390-410`) | 03 |
|
||||
| [0929/03-02](03-adapters-http-state.md) | §16.6에 없음 | 남음 | `x-correlation-id` CORS 허용이 문서뿐이다(`backend-api-and-server-state-contract.md:257-267`) | 03 |
|
||||
| [0929/05-01](05-adapters-storage-kernel.md) | §16.6에 없음 | 일부 | 손상 chunk reference 행이 reconcile을 멈춘다(③, `indexeddb-opfs-journal.ts:855-862`). purge는 이제 영향을 받지 않는다 | 05 |
|
||||
| [1101/05-06](05-adapters-storage-kernel.md) | §16.6에 없음 | 일부 | Web Storage W2·W5·W6를 보는 테스트가 없다(`browser-storage-codec.ts:204-206`) | 05 |
|
||||
| [0929/05-05](05-adapters-storage-kernel.md) | §16.6에 없음 | 남음 | 전체 삭제 조건이 `POLICY_REJECTED`·`CORRUPT_DATA`뿐이다(`indexeddb-runtime.ts:2580-2586`) | 05 |
|
||||
| [0929/05-06](05-adapters-storage-kernel.md) | §16.6에 없음 | 남음 | proof 정규식 `{16,128}`(`indexeddb-runtime.ts:97`) 대 `{16,512}`(`opfs-byte-store-adapter.ts:1930`) | 05 |
|
||||
| [0929/05-07](05-adapters-storage-kernel.md) | §16.6에 없음 | 남음 | canonical JSON 3벌, `sameScope` 2벌(`opfs-prepared-object.ts:138` 등) | 05 |
|
||||
| [0929/05-10](05-adapters-storage-kernel.md) | §16.6에 없음 | 남음 | journal DB 접두사를 바꿀 수 없다(`indexeddb-opfs-journal.ts:131`) | 05 |
|
||||
| [0925/06-05](06-adapters-service-worker-push.md) | §16.6에 없음(지난 영역 문서 남음) | 일부 | observe는 제품이 잇는다(1103/09-05). 업데이트 설치 실패와 `health()`는 이어지지 않았다(`service-worker-page-controller.ts:328-349`) | 06 |
|
||||
| [0925/06-08](06-adapters-service-worker-push.md) | §16.6에 없음 | 남음(영향 넓어짐) | `assets/`가 상수 하나(`src/contracts/service-worker.ts:126`)지만 Vite `build.assetsDir`와 이어지지 않는다. 1105/06-01 뒤 사전 캐시 수집기도 이 상수를 읽는다 | 06 |
|
||||
| [0925 P3](06-adapters-service-worker-push.md) | §16.6에 없음 | 남음 | SW update spec의 route chunk 변경을 helper 옵션으로(`service-worker-update.spec.ts:54-72`). 11 영역의 FOLLOW-UP과 같은 항목이다 | 06, 11 |
|
||||
| [1101/06-03](06-adapters-service-worker-push.md) | §16.6에 없음 | 남음 | PAGE_HELLO·UPDATE_READY·reload guard가 흔적만 남았다(`service-worker-protocol.ts:16`, `:18`) | 06 |
|
||||
| [1101/06-05](06-adapters-service-worker-push.md) | §16.6에 없음 | 남음 | 릴리스마다 사전 캐시 전체를 `no-store`로 다시 받는다(`service-worker-static-assets.ts:279-284`) | 06 |
|
||||
| [1101 R1](06-adapters-service-worker-push.md) | §16.6에 없음 | 남음 | `retainedPreviousCaches`를 `void`로만 참조한다(`service-worker-lifecycle.ts:169`) | 06 |
|
||||
| [1101 R2](06-adapters-service-worker-push.md) | §16.6에 없음 | 남음 | `validateActiveFence` 두 벌(`push-event-adapter.ts:196`, `notification-click-adapter.ts:356`) | 06 |
|
||||
| [1101 R3](06-adapters-service-worker-push.md) | §16.6에 없음 | 남음 | `SYNC_WAKE_OBSERVED`만 프로토콜 버전을 숫자로 쓴다(`service-worker-entry.ts:170`) | 06 |
|
||||
| [1101 R4](06-adapters-service-worker-push.md) | §16.6에 없음 | 고쳐짐 | `ce191be`(1101/10-07)가 가짜 시계로 바꿔 8 ms다. 실효 상한을 넓힌 것은 새 06-02 | 06 |
|
||||
| [0929/08-01](08-presentation.md) | §16.6에 없음 | 남음 | 제품이 지원 locale을 선언할 곳이 없다(`message-contract.ts:8-13`) | 08 |
|
||||
| [0929/08-08](08-presentation.md) | §16.6에 없음 | 남음 | 로그인 복귀 주소가 라우터 기준 경로다(`session-provider.tsx:99`) | 08 |
|
||||
| [0925 FOLLOW-UP 09-07](09-app-core.md) | §16.6에 없음 | 일부 | 샘플 제거 드릴이 브라우저 테스트를 돌지 않는다(`test-sample-removal.ts:443-448`). 예제 제거 드릴은 게이트 밖 | 09 |
|
||||
| [0925 FOLLOW-UP 09-08](09-app-core.md) | §16.6에 없음 | 남음(허용한 대안) | local-draft ABA를 주석으로 닫았다(`local-draft.ts:2-11`) | 09 |
|
||||
| [0929/11-02](11-tests-browser-release-scale.md) | §16.6에 없음 | 남음 | 운영 drill이 어떤 입력으로도 PASS가 될 수 없다(`drill-runbook.ts:245`) | 11 |
|
||||
| [0929/11-05](11-tests-browser-release-scale.md) | §16.6에 없음 | 남음(미검증) | 규모 기준선이 2026-11-01 `373b27b` 측정이다(`feature-shape-growth.json:3`) | 11 |
|
||||
| [0929/11-07](11-tests-browser-release-scale.md) | §16.6에 없음 | 남음 | 빌드 helper 두 벌(`fixture-builds.ts:55`, `service-worker-builds.ts:177`) | 11 |
|
||||
| [1101/13-03](13-build-release-supply-chain.md) | §16.6에 없음 | 남음 | provider job에 namespace 요구 주석·점검이 없다(`quality-gates.yml:228`, `:274`). 이 desktop에서 provider 18건이 bwrap 원문으로 끝났다 | 13 |
|
||||
| [0929/13-02](13-build-release-supply-chain.md) | §16.6에 없음 | 남음 | `.env*` 빌드 변수를 번들과 스크립트가 다르게 읽는다(`vite.config.ts:19`, `:193-194`) | 13 |
|
||||
| [0929/13-03](13-build-release-supply-chain.md) | §16.6에 없음 | 남음 | 청크 이름이 선언 없이 계약처럼 쓰인다(`generate-build-manifest.ts:70-78`, fail-closed) | 13 |
|
||||
| [0929/13-04](13-build-release-supply-chain.md) (= R-3) | §16.6에 없음 | 남음 | CSP가 6벌이고 내용 검사가 없다(`security-headers.json:4` 등) | 13 |
|
||||
| [0929/13-05](13-build-release-supply-chain.md) | §16.6에 없음 | 남음 | SBOM이 `deduped` 노드를 따라가지 않는다(`dependency-baseline.json:5778-5781`) | 13 |
|
||||
| [0929/13-06](13-build-release-supply-chain.md) | §16.6에 없음 | 일부 | live probe가 루트가 아닌 URL을 거절한다(`hosting-probe.ts:453-456`) | 13 |
|
||||
| [0929/13-10](13-build-release-supply-chain.md) | §16.6에 없음 | 남음 | "unmodified checkout" 문구 그대로(`README.md:421-426`) | 13 |
|
||||
| [R-2](13-build-release-supply-chain.md) (13) | §16.6에 없음 | 남음 | 빌드 입력 기본값이 다섯 곳이다(`env.ts:54-55`, `:204-205`, `generate-runtime-config.ts:77-78` 등) | 13 |
|
||||
|
||||
### 13.5 ID 없는 이월 (10건, 모두 남음)
|
||||
|
||||
| 항목 | 영역 | 지금 상태 | 근거 |
|
||||
|---|---|---|---|
|
||||
| FOLLOW-UP: `maxPartCount` 바이트 검사가 transport에 넘길 때만 | 01 | 남음 | `fetch-json-transport.ts:157-167` |
|
||||
| FOLLOW-UP: 업로드 PUT에 idle 제한 없음 | 01 | 남음(문서화된 선택) | 바뀌지 않았다 |
|
||||
| FOLLOW-UP: probe 재사용 테스트가 공개 이미지만 씀 | 01 | 남음 | `image-cdn-runtime.test.ts:196`, `:311`, `:383` |
|
||||
| 1103/01-02와 함께 볼 것: object store CORS의 `Retry-After` expose | 01 | 남음 | `server-file-capability-infrastructure.md:1666-1673` |
|
||||
| FOLLOW-UP: Firefox SW quarantine | 11 | 남음(만료 2027-03-31) | 빠지는 test가 3 → 4개(`service-worker-update.spec.ts:306`) |
|
||||
| `test:platform`만 `--no-file-parallelism`, 이유 없음 | 10 | 남음 | `package.json:141` |
|
||||
| `--passWithNoTests` 3곳 | 10 | 남음 | `package.json:50`, `:58`, `:81` |
|
||||
| (지난 R1) 전역 setup이 DOM 없는 unit에도 RTL을 읽음 | 10 | 남음 | `tests/setup.ts:1-2`, setup 누적 50.73 s |
|
||||
| (지난 R6) `typescript-tooling-smoke` 두 파일 | 10 | 남음 | `tests/unit/typescript-tooling-smoke.test.ts`, `tests/component/typescript-tooling-smoke.test.tsx` |
|
||||
| `tsc-diagnostics-parser.test.ts` 제외 사유 | 10(12 몫) | 남음 | `config/ci/ungated-tests.json:25` |
|
||||
|
||||
## 14. 오케스트레이터 확인
|
||||
|
||||
### 1105/12-04 완료 드릴(`bbde570`)
|
||||
|
||||
- 실행: `R5-01-1204-drill`, 2026-11-06 04:06~04:10, 234초. 한 checkout에서 run ID가 다른 e2e 둘을 동시에 돌렸다.
|
||||
- 부분 spec 둘(`compact-smoke`, `preload-use`): 두 실행 모두 rc=0, 19 passed.
|
||||
- 전체 e2e: 두 실행 모두 rc=0, 222 passed·4 skipped.
|
||||
- 두 실행 모두 "already used" 0줄, 자기 `dist/`·build manifest·`results.xml`·report를 가졌고, 포트가 달랐다(41159/46739, 33661/35167).
|
||||
- 판정: **일부.** 메인 세션이 정한 완료 기준(한 checkout에서 e2e 두 실행이 함께 돌고 둘 다 통과)은 충족한다. 지난 리뷰의 완료 기준(FE-GATE-008 둘, 또는 FE-GATE-008과 FE-GATE-005를 함께 돌려 둘 다 통과하고 증거 파일이 섞이지 않는다)은 충족하지 않는다. 두 `ci:gate` 실행은 아직 저장소 루트의 `dist`·`artifacts/`를 함께 쓰고, 그 제한은 문서로만 적혀 있다(`README.md:362-363`, 12 영역). 12-04 수정이 12-02를 만들었다.
|
||||
|
||||
## 15. 새 발견 색인 (25건)
|
||||
|
||||
심각도·우선순위 순이고, 같은 칸 안에서는 영역 번호 순이다. 영역 문서 3절에 36.3 양식이 있다.
|
||||
|
||||
- 영역 문서가 적은 새 발견은 27건이다. 같은 결함 둘을 합쳐 25건으로 센다.
|
||||
- 10-02는 12-01과 같은 결함이다. 제거 fixture의 문서 테스트 목록이 테스트 파일을 통째로 뺀다.
|
||||
- 16-02는 07-01과 같은 결함이다. 계약 문서 4.1절의 bulk 줄 "`responseEnvelope`를 빼고"다. 16 영역도 07-01로 한 번 센다고 적었다.
|
||||
- 심각도: High 이상 0 · Medium 1 · Low 24. 우선순위: P1 이상 0 · P2 2 · P3 23.
|
||||
- 성격: 확인된 결함 13 · 구조적 위험 9 · 개선 제안 3 · 미검증 0.
|
||||
- 지난 조치가 만들거나 남긴 것(영역 문서 근거 칸 기준):
|
||||
- 만든 것: 01-01(1105/01-01), 03-01의 길 일부와 03-02(1105/03-02 `c6c37f3`), 03-03(0929/03-03 `683ccfb`), 04-01(1105/04-02 `05330e3`), 04-02(1103/04-01 `27e3dec`가 권한 `input.operation` 경로), 06-02(1101/10-07 `ce191be`), 08-01(1105/08-04 뒤 다시 마운트 경로), 08-03(1105/15-05 `e02f252`), 09-01(1103/16-05 `48c1ab7`), 10-01·12-01(§16.3 통합 수정), 11-01(1103/11-01 `757d1c7`의 분류에 지키는 test가 없음), 12-02(1105/12-04 `f4d5761`), 13-01(1105/13-01이 새로 쓴 문장), 14-01(PR B CHANGELOG 새 절), 14-02·15-01(D7 `287dc6f`), 16-01(1105/16-04 `b45d6a0`).
|
||||
- 남긴 것: 07-01(1103/16-01 BREAKING `56272e8`이 같은 절의 이 줄을 고치지 않음), 05-01(`dc7c95b`가 행을 더하고 문서는 고치지 않음).
|
||||
- 지난 라운드들이 보고하지 않은 기존 경로: 02-01, 06-01, 07-02, 08-02.
|
||||
|
||||
판정이 갈린 것(합치지 않고 적어 둔다):
|
||||
|
||||
- 10-01: 12 영역 2.2절은 같은 두 변경(`playwright-run-isolation.test.ts`의 `HAS_CAPABILITIES`, `vite-build-inputs.test.ts`의 `existsSync`)을 "약화 아님"으로 봤다. 15 영역 1105/15-03 행도 `vite-build-inputs` 쪽을 "약해진 검사가 아니다"로 봤다. 10 영역은 템플릿에서 이름이 바뀔 때의 검출 공백으로 셌다.
|
||||
- 12-01: 07 영역 4절 27번은 같은 제외를 "드릴에 필요한 검사를 빼지 않았다. 개선 여지(세지 않음)"로 봤다. 10·12 영역은 구조적 위험으로 셌다. 셋 다 지금 놓친 결함은 없다고 적는다.
|
||||
|
||||
| ID | 심각도·우선순위 | 성격 | 내용 | 관련 관점 | 위치 | 합친 것 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| [03-01](03-adapters-http-state.md) | Medium·P2 | 확인된 결함 | KEYED 결과 불명의 같은 키 재전송이 429·503 `RATE_LIMIT_*`·보내기 전 실패로 끝나면 훅이 결과 불명과 키를 버린다. 생성 폼의 "다시 시도"가 새 키로 보낸다(03-R1 `keys=["key-1","key-1","key-2"]`) | 6, 12, 28, 17, 10, 5 | `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` | |
|
||||
| [14-01](14-template-product-docs.md) | Low·P2 | 확인된 결함 | 새 미출시 절 BREAKING 1~3단계의 설명 셋이 코드·다운스트림과 다르다. 3단계 "부팅이 멈춘다"(실제는 기능 라우트 첫 진입), 1단계가 TechLog를 "감싸지 않는 백엔드"로 적음, 2단계가 `requiresIdempotencyKey` 재계산을 말하지 않음 | 17, 23, 24, 20 (30.4) | `CHANGELOG.md:24-26`; `src/features/installed-contract-contributions.ts:93-111`; `src/contracts/server-state.ts:303-311`; tech-log `studio-management-server-state.ts:209` | |
|
||||
| [01-01](01-adapters-browser-transfer.md) | Low·P3 | 개선 제안 | 202 `REJECTED` 실패(`FILE_REJECTED`)에 성공 Envelope의 `traceId`가 없고, 백엔드 답에는 거절 이유가 없어 서버 기록과 잇지 못한다 | 8, 7, 23, 17, 26 | `src/adapters/http/fileserver-upload.ts:681-689`, `:787-800`; `src/adapters/http/backend-envelope.ts:97-117`; 백엔드 `UploadedFileResponse.java:11-29` | |
|
||||
| [02-01](02-adapters-browser-files-cache.md) | Low·P3 | 구조적 위험 | active pointer 본문이 계속 읽히지 않으면 activation·cleanup·inspect·조회가 모두 멈추고, adapter API 안에서는 돌아올 길이 없다(02-R1 X3) | 28, 6, 18, 24, 11 | `src/adapters/cache-storage/public-response-cache-adapter.ts:714-730`, `:813-819`, `:885-893`, `:246-254`, `:1041-1064` | |
|
||||
| [03-02](03-adapters-http-state.md) | Low·P3 | 확인된 결함 | 계약 6.1절은 rate-limit 503에 "자동 재전송은 없다"고 적지만 IDEMPOTENT 쓰기는 `retryBudget` 안에서 다시 보낸다. 그 경로의 테스트가 없다 | 17, 23, 10, 5 | `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](03-adapters-http-state.md) | Low·P3 | 개선 제안 | 0929/03-03의 두 가드가 키 유무로만 갈라서, IDEMPOTENT 쓰기도 결과 불명 뒤 재전송과 같은 입력 재제출이 막힌다 | 28, 23, 22, 24, 12 | `src/presentation/adapters/query/application-query.ts:574-583`, `:853-867`; `src/contracts/server-state.ts:309-312` | |
|
||||
| [04-01](04-adapters-realtime.md) | Low·P3 | 구조적 위험 | reconnect coordinator는 던지는 `attempt`·`waitClosed`를 서버 장애로 재시도한다. `05330e3` 뒤 poll은 같은 던짐을 `PROTOCOL_MISMATCH`로 끝내고, 규칙은 어디에도 적혀 있지 않다. endpoint 설정 오류가 fetch 0회로 3번 재시도되고 `PROVIDER_UNAVAILABLE`(EXHAUSTED)로 끝난다(04-R2) | 23, 8, 24, 5, 6 | `src/adapters/realtime/reconnect-coordinator.ts:766-774`, `:954-961`; `tests/unit/realtime/realtime-reconnect-coordinator.test.ts:1764-1770` | |
|
||||
| [04-02](04-adapters-realtime.md) | Low·P3 | 개선 제안 | 권하는 `input.operation`은 `InstalledHttpContract<unknown, unknown, unknown>`이라 실행기 호출의 입력·출력 타입이 사라진다. V3 결과 9종 → poll 결과 대응표가 없고, 유일한 예는 SUCCESS 외 전부를 retryable `PROVIDER_UNAVAILABLE`로 바꾼다 | 20, 22, 17, 3 | `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` | |
|
||||
| [05-01](05-adapters-storage-kernel.md) | Low·P3 | 확인된 결함 | 저장소 설계 문서가 registry 행 8개 중 4개만 "현재 등록되어 있다"고 적는다 | 9, 4, 15, 23, 5 | `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` | |
|
||||
| [06-01](06-adapters-service-worker-push.md) | Low·P3 | 구조적 위험 | live probe가 `/service-worker.js`의 같은 origin redirect를 통과시킨다. 브라우저는 워커 스크립트 redirect를 거절해 등록·업데이트·`REMOVE_REGISTRATION`이 실패할 수 있다 | 18, 21, 28, 5 | `scripts/lib/hosting-probe.ts:135`, `:142-157`; `docs/operations/release-cache-rollback.md:66-67` | |
|
||||
| [06-02](06-adapters-service-worker-push.md) | Low·P3 | 확인된 결함(약해진 검사) | 1101/10-07 수정이 marker 읽기 시간 상한 test의 실효 상한을 10초에서 20초로 넓혔다. 상한을 15초로 올린 변이에서 64건이 모두 통과했다(06-R3) | 10, 21 | `tests/unit/service-worker-runtime.test.ts:2029-2034`; `src/adapters/service-worker/service-worker-lifecycle.ts:558` | |
|
||||
| [07-01](07-contracts.md) | Low·P3 | 확인된 결함 | 계약 문서 4.1절이 bulk 엔드포인트에 "`responseEnvelope`를 빼라"고 적는다. 빼면 `check:types`가, 같은 기여에 `"NONE"`을 적으면 조립이 실패한다(1103/16-01 BREAKING 뒤 남은 줄) | 20, 9, 23, 17, 4 | `docs/architecture/backend-api-and-server-state-contract.md:205-207`; `src/contracts/external-contract-runtime.ts:239`, `:709-720` | 16-02(같은 줄, 영역 16) |
|
||||
| [07-02](07-contracts.md) | Low·P3 | 구조적 위험 | 스키마 메타 행이 `direction`·`unknownFieldPolicy`를 적지 않으면 정책 테스트가 건너뛰어, 응답 DTO를 strict로 바꿔도 `check:registries`·`test:unit` 어느 쪽도 보지 않는다 | 17, 21, 10, 20 | `tests/unit/schema-metadata-policy.test.ts:130`, `:157`; `config/contracts/registry-governance.json:263`; `src/contracts/schema-registry.ts:17-18` | |
|
||||
| [08-01](08-presentation.md) | Low·P3 | 확인된 결함 | 다시 마운트한 참조 폼이 자기가 시작하지 않은 저장의 끝을 보이지 않는다. "변경됨으로 확인" 뒤 결과 문구가 없고 포커스가 `body`다(08-R1) | 28, 24, 1, 6, 10, 22 | `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](08-presentation.md) | Low·P3 | 확인된 결함 | 생성 기능 작성 폼이 저장 중에 떠난 사용자를 저장이 끝나면 상세 화면으로 옮긴다(08-R7) | 1, 23, 28, 10, 20 | `scripts/create-feature-write-slice.ts:636-655` | |
|
||||
| [08-03](08-presentation.md) | Low·P3 | 확인된 결함 | `scrollbar-gutter: stable`의 15 px 띠를 drawer·모달 가림막과 header가 칠하지 않는다. 새 골든이 이 띠를 고정했다(08-R2) | 1, 23, 10, 5 | `src/presentation/styles/theme/base.css:6-11`; `src/presentation/styles/theme/primitives.css:416-419`; `src/presentation/styles/theme/shell.css:45-57` | |
|
||||
| [09-01](09-app-core.md) | Low·P3 | 확인된 결함 | 1103/16-05 이행 안내가 HTTP descriptor 없는 뮤테이션(Fileserver 업로드 등)과 테스트 fixture의 길을 말하지 않고, 매뉴얼 01이 손 ID의 실패 시점을 두 가지로 적는다 | 20, 17, 4, 9, 5 (30.4) | `CHANGELOG.md:25`; `docs/manual/01-add-a-feature.md:476`, `:499-500`; `src/contracts/server-state.ts:294-313`; `tests/helpers/mutation-operation-id.ts:11-15` | |
|
||||
| [10-01](10-tests-fast-layers.md) | Low·P3 | 구조적 위험 | 통합 수정이 새 테스트 둘의 검사를 "대상 파일이 있으면"으로 정했다. 드릴 사본에서 8개가 말없이 사라지고, 템플릿에서 이름을 바꿔도 같다. skip 차단은 이를 보지 못하고 주석의 근거 ID도 틀렸다 | 10, 21, 27, 23, 5, 24 | `tests/unit/playwright-run-isolation.test.ts:27-44`, `:243-252`; `tests/unit/vite-build-inputs.test.ts:19-22`, `:49-56` | |
|
||||
| [11-01](11-tests-browser-release-scale.md) | Low·P3 | 구조적 위험 | `a11y.json`의 `notChecked` 분류를 지키는 test가 없고 기록 없는 라우트를 "검사함"으로 센다. spec의 기록 호출 한 줄을 바꾸면 상세 라우트가 다시 passed로 세지고 rc=0이다(11-R2) | 10, 21, 5 | `tests/e2e/accessibility.spec.ts:77-84`; `scripts/lib/a11y-data-state.ts:50`, `:61`; `scripts/contracts/release-artifacts.ts:853-868` | |
|
||||
| [12-01](12-guardrails-ci.md) | Low·P3 | 구조적 위험 | 제거 fixture가 문서를 읽는 테스트를 파일째 뺀다. 그래서 capability 드릴 사본 셋에서 `backend-contract-pin.test.ts`의 문서 무관 14건과 `feature-tracked-files.test.ts`의 1건이 돌지 않는다. 목록 검사는 주석 한 줄로 통과한다 | 10, 21, 27, 24, 17, 5 | `scripts/lib/removal-fixture.ts:70-81`; `tests/unit/backend-contract-pin.test.ts:150-253`, `:259`; `tests/unit/removal-fixture.test.ts:161` | 10-02(같은 결함, 영역 10) |
|
||||
| [12-02](12-guardrails-ci.md) | Low·P3 | 확인된 결함 | 셸에 `RUN_OUTPUT_ROOT`가 있으면 빌드는 `.tmp/` 아래에 쓰고 `check:bundle`은 루트의 이전 빌드로 판정한다. 예산을 3,504 B 넘는 빌드가 PASS했다(12-R2) | 21, 19, 5, 23, 20 | `scripts/build-frontend.ts:51`; `scripts/generate-supply-chain.ts:144`, `:156`; `scripts/check-bundle.ts:24-29`; `scripts/run-ci-gate.ts:189-206` | |
|
||||
| [13-01](13-build-release-supply-chain.md) | Low·P3 | 확인된 결함 | FE-GATE-027의 공개 대상 승인이 거절되면 advisory 검사가 돌지 않아, 그 run의 증거에 advisory 기록이 없다. 문서는 결과와 상관없이 올린다고 적는다(13-R1 C) | 5, 8, 23, 16 | `config/ci/gates.json:2212-2213`; `scripts/run-ci-gate.ts:176-190`; `docs/operations/ci-quality-gates.md:169-173`, `:540-544` | |
|
||||
| [14-02](14-template-product-docs.md) | Low·P3 | 확인된 결함 | D7 커밋 `287dc6f` 본문이 `bbde570` 이력에 없는 다시 쓰기 전 해시 `ab0d4a1`·`7ce9bf1`을 가리킨다. CHANGELOG·커밋 본문의 해시를 대조하는 장치가 없다 | 9, 24, 21 (30.4) | `git show 287dc6f`; `scripts/verify-documentation-readiness.ts:165` | |
|
||||
| [15-01](15-performance.md) | Low·P3 | 구조적 위험 | 초기 JS 예산 상향(D7)이 드릴 초과분 665 B의 세 배(2,048 B)를 올렸다. 폭의 근거와 다시 내릴 조건이 없어, 다음 1,383 B는 어느 merge 게이트도 멈추지 않는다 | 21, 14, 13, 5, 10 | `config/performance/budgets.json:4`; `docs/operations/performance-evidence.md:44-53`; `tests/unit/performance-budgets.test.ts:106-136` | |
|
||||
| [16-01](16-structure-patterns.md) | Low·P3 | 구조적 위험 | 제품 기능 제거 드릴이 `tests` 잔여를 파일 이름·import로 좁혔다. 안전망으로 든 `test:all`은 Playwright spec을 돌지 않아, spec 본문의 기능 ID를 아무 검사도 잡지 않는다. 매뉴얼·주석은 "`test:all`이 잡는다"고 적는다 | 21, 10, 27, 8 | `scripts/lib/feature-residue.ts:18-20`, `:57-60`; `docs/manual/01-add-a-feature.md:662`; `vitest.config.ts:45`; `package.json:85` | |
|
||||
|
||||
## 16. 조치 (2026-11-06)
|
||||
|
||||
메인 세션이 지시한 마지막 수정 라운드다. 새 발견 25건과 1103/15-02 재발(초기 파일 수 문장)을 고쳤다. 그 밖의 이월(결정 대기, 백엔드로 넘김, 러너 대기)은 고치지 않았다. 상태는 13.4절 표 그대로다. 이 세션이 수정·통합·문서를 맡았고, push·merge 게이트 14개·PR은 메인 세션이 맡는다.
|
||||
|
||||
### 16.1 방법
|
||||
|
||||
- 브랜치: `fix/maturity-review-2026-11-06`. 기준은 이 리뷰 커밋 `302d3a5`(PR B `bbde570` 위)다.
|
||||
- 수정 에이전트 9개가 각자 worktree의 `fix/r1106-<영역>` 브랜치에서 고쳤다. 모두 `302d3a5`에서 갈라졌다. 오케스트레이터가 그 브랜치를 `--no-ff`로 합쳤다.
|
||||
- 공통 지시:
|
||||
- RED 먼저, 발견 하나에 커밋 하나.
|
||||
- 검사 범위를 좁히거나 단언을 느슨하게 하지 않는다. 예외·skip·조건부 테스트도 더하지 않는다.
|
||||
- 커밋 규칙(`design-docs/conventions/commit-and-pr.md`)을 따르고 AI 꼬리말을 넣지 않는다.
|
||||
- 에이전트는 노트북에서 아무것도 실행하지 않는다. 검증은 요청 파일에 적고 오케스트레이터가 desktop에서 돌린다.
|
||||
- 실행 방법은 1105 README 16.1절과 같다.
|
||||
- desktop 한 checkout에서 공유 잠금(`/tmp/claude-gates/heavy.lock`)을 잡고 항목을 하나씩 돌렸다. 복제본은 만들지 않았다.
|
||||
- 항목마다 그 ref를 detached로 checkout하고, 끝나면 원래 브랜치로 되돌렸다(`restore=clean`).
|
||||
- RED는 그 커밋의 테스트 파일을 부모의 비테스트 파일 위에 올려 돌린 것이다. 변이는 항목마다 patch·script로 적용했다.
|
||||
- 결과: 배치 항목 70개(`desktop:/tmp/claude-gates/r6/batch/`), 모두 `restore=clean`이다.
|
||||
- RED 15개는 모두 요청이 이름 댄 테스트에서 말한 이유로 실패했다.
|
||||
- GREEN은 모두 통과했다. 예외는 08-03의 첫 수정 하나다(16.3절).
|
||||
- 변이와 실험(06-02 상한 15000·5001, 07-02, 10-01 M1·M2, 11-01 R2·기록 삭제, 12-02 12-R2, 16-01 spec 본문, 03-R1, 13-R1 C)은 모두 고친 커밋에서 잡혔다. 10-01 M1·M2는 부모 커밋에서는 통과해, 고치기 전에는 못 잡던 것을 보였다.
|
||||
- `R6-DOCS-HEAD` 첫 실행은 오케스트레이터가 명령을 잘못 이어 붙여(`;;`) 문법 오류로 끝났다. 스크립트로 바꿔 다시 돌렸다.
|
||||
|
||||
### 16.2 결정
|
||||
|
||||
| 번호 | 고른 것 | 이유 | 버린 대안 | 재검토 조건 |
|
||||
|---|---|---|---|---|
|
||||
| D1~D3, D11 | 결정 대기로 남긴다(1103/13-03, 09-04, 03-07, 1105/16-03) | 메인 세션 지시 | — | 7절과 같다 |
|
||||
| D8 | **결정 대기.** 사용자 답을 기다린다 | FE-GATE-013을 멈춤 기준에서 어떻게 셀지는 사용자가 정한다 | — | 사용자가 답할 때 |
|
||||
| D9 | 초기 JS 예산 206,848 B를 그대로 둔다(1105 D7). 메인 세션 결정, 2026-11-06. 사용자가 뒤집을 수 있다 | 폭의 근거: `bbde570`에서 생성 기능 둘을 더한 드릴(FE-GATE-020)의 실측 205,465 B(CI env, 15 영역)에 기능 하나 상한 1 KiB를 더해 KiB 단위로 올리면 202 KiB = 206,848 B다. 근거와 되돌림 규칙은 `docs/operations/performance-evidence.md`에 적었다(`1eaa6447`) | 필요한 폭으로 다시 내리기. 리뷰 15 영역의 대안 (c) 예산 규칙을 테스트로 고정하기 | D7의 재검토 조건마다 드릴을 다시 잰다. 드릴 실측이 204,800 B 이하면 같은 규칙으로 예산을 내린다 |
|
||||
| D10 | (a) 결과 불명 상태를 훅에서 지킨다(`25685871`). 메인 세션 결정, 2026-11-06. 사용자가 뒤집을 수 있다 | 같은 키 재전송이 쓰기 전 거절(`NOT_APPLIED`·`NOT_STARTED`)로 끝나도 훅이 결과 불명과 키를 버리지 않는다. 폼 쪽은 (i)를 골랐다. `resendUnknown`이 `unknownSubmissionRef`를 지우지 않고, 새 문구 하나(`form.resendLater`, ko·en)로 "나중에 다시 보내라"고 알린다. 다음 "다시 시도"도 같은 키다. 03-R1 X1~X3·X5의 키가 모두 `key-1`이다(16.5절) | rate-limit 503을 다시 `MAYBE_APPLIED`로 읽기(1105/03-02를 되돌림). 생성 페이지만 고치기(참조 폼과 직접 훅 호출이 그대로 남음) | KEYED를 템플릿 기본으로 바꾸거나 rate limit을 기본으로 켤 때(10절) |
|
||||
| D10 보완 | 같은 키 재전송의 결과가 첫 요청의 결과를 증명할 때만 결과 불명을 푼다(`80e7f1d6`). 입력 검증 kind로 푸는 부분은 D10 보완 2가 지웠다. 메인 세션 결정, 2026-11-06(diff 리뷰 DR-01 뒤). 사용자가 뒤집을 수 있다 | 푸는 경우: 성공·APPLIED(저장된 답의 재생), 같은 요청이라 첫 요청도 받았을 거절(입력 검증 `VALIDATION_REJECTED`, 400 `VALIDATION_FAILED`, 400 `IDEMPOTENCY_KEY_INVALID`). 남기는 경우: 멱등성 판정보다 앞에서 오거나 시간에 따라 바뀌는 거절(429, 401, 403, 503 `RATE_LIMIT_*`, 보내기 전 `NOT_STARTED`), 422 `IDEMPOTENT_REQUEST_MISMATCH`(키가 이미 서버에 닿아야 나온다), 기능이 선언한 code. 어느 쪽인지 애매하면 남긴다. 남겨도 결과 불명 화면의 확인으로 빠져나갈 수 있고, 테스트가 그것을 고정한다. 판정은 `src/contracts/errors.ts` `isRefusedOnEveryAttempt` 하나를 훅과 폼이 함께 부른다 | 일시 거절(`NOT_STARTED`·retryable·rate limit)만 남기기(diff 리뷰 안. 401·403·422 mismatch·기능 code를 풀어 버린다) | 백엔드 거절 표(`backend-envelope.ts`)에 행이 생길 때. 단위 테스트가 새 행에서 실패해 분류를 정하게 한다 |
|
||||
| D10 보완 2 | 재전송의 거절이 결과 불명을 푸는 것은 짝 백엔드 표의 code뿐이다(`b41990cd`). 지금은 400 `VALIDATION_FAILED`와 400 `IDEMPOTENCY_KEY_INVALID` 둘이다. 기능 `mapProblem`이 붙인 kind는 믿지 않는다. 메인 세션 결정, 2026-11-06(마지막 리뷰 FR-01 뒤). 사용자가 뒤집을 수 있다 | 기능 code는 상태 규칙일 수 있다. 생성 scaffold는 자기 선언 code를, 참조 기능은 모든 422를 `VALIDATION_REJECTED`로 바꾼다. 그래서 kind로 풀면 기능 선언 code와 422 `IDEMPOTENT_REQUEST_MISMATCH`도 풀렸다. 참조 기능의 422는 이제 남고, 확인 버튼으로 빠져나간다(테스트로 고정). 계약 문서 6.1절에 "`VALIDATION_FAILED`는 요청 내용만 보는 검증이어야 하고, 시간이나 DB를 읽는 규칙은 기능 선언 code로 내보낸다"를 더했다(`6142cc8e`, FR-02) | 기능이 "매번 같은 거절"을 descriptor에 따로 선언하게 하기(계약 타입을 바꾼다) | 짝 백엔드가 `VALIDATION_FAILED`를 내는 검증에 시간·DB를 읽는 규칙을 더할 때 |
|
||||
| 14-02 | 올린 이력은 고쳐 쓰지 않는다. `287dc6f`는 amend·rebase하지 않는다. 맞는 해시는 1105 README 16.2절 D7 행에 적었다(`ddc6353d`) | 메인 세션 지시 | `287dc6f` 본문 고치기(이미 push한 이력) | — |
|
||||
|
||||
해시 대조 도구는 더하지 않았다. 문서 에이전트가 본 비용(`ddc6353d` 본문):
|
||||
|
||||
- 이력이 없는 사본과 얕은 checkout에서는 건너뛰어야 한다. 이 repo는 skip이 있는 실행을 실패로 본다(1101/10-04).
|
||||
- 이미 올린 `287dc6f`에 영구 예외가 필요하다.
|
||||
|
||||
그래서 대조는 사람이 하는 단계로 두었다. CHANGELOG 머리말에 `git merge-base --is-ancestor` 단계를 적었고, 이번 결과는 16.6절에 있다.
|
||||
|
||||
### 16.3 통합에서 생긴 것
|
||||
|
||||
| 위치 | 내용 |
|
||||
|---|---|
|
||||
| `7625dc45`(08-03) | 첫 수정은 완료 기준을 채우지 못했다. drawer를 열어도 gutter 자리는 rgb(248 250 252)로 남았고, 바로 옆 가림막은 rgb(122 128 136)이었다. compact 골든도 바뀌지 않았다. 에이전트에 되돌려 보냈다. `amend!` fixup이 규칙을 `:root:has(.ui-dialog[open])`의 불투명 배경색(`--dialog-backdrop-on-surface`, `--dialog-backdrop-weight` 55%)으로 바꿨다. 그 뒤 GREEN이 통과했고, 골든은 compact 한 장만 바뀌었다(x 375~390 띠). 오케스트레이터가 diff를 눈으로 보고 그 골든을 `amend!`로 같은 커밋에 넣었다. fixup은 사본 브랜치 `fix/r1106-presentation-sq`에서 접었다 |
|
||||
| `5cfc3a65` | 모두 합친 빌드에서 `tests/unit/feature-shape-growth.test.ts`가 기록이 낡았다고 실패했다. context 하나가 더하는 초기 JS가 기록 218 B, 빌드 245 B로 10% 허용치를 넘었다. 브랜치마다는 기록과 맞았다. 합친 끝에서 `--initial-baseline --write`로 다시 적었다. 합계 204,111 → 204,193 B, 기능 하나 768 → 751 B, 초기 파일 27개 그대로다 |
|
||||
|
||||
### 16.4 새 발견 상태 (25건)과 1103/15-02
|
||||
|
||||
- 고침: 완료 기준까지 확인했다.
|
||||
- 일부: 남은 부분을 적었다.
|
||||
- 백엔드로 넘김: 이 repo 안에서 고칠 수 없다. 백엔드에 할 요청을 적었다.
|
||||
- 해시는 브랜치 `fix/maturity-review-2026-11-06`에서 닿는 커밋이다.
|
||||
|
||||
| ID | 상태 | 커밋 | 남은 것 |
|
||||
|---|---|---|---|
|
||||
| 03-01 | 고침(D10, 보완, 보완 2) | `25685871`, `80e7f1d6`(diff 리뷰 DR-01), `b41990cd`(마지막 리뷰 FR-01) | 재전송이 rate limit에 막힌 동안 결과 불명 화면이 남는다. 폼 밖에서 `submit`을 부른 같은 입력 재저장이 `NOT_APPLIED`로 끝나면 훅은 키를 지키지만 폼은 retry-later를 보인다 |
|
||||
| 14-01 | 고침 | `2f0f2bba` | `as` 단언이 빠진 `responseEnvelope`를 잡지 않는다는 것과 tech-log 관리 쓰기의 지금 거절은 코드로 읽은 추론이다. 문서에도 그렇게 적었다 |
|
||||
| 01-01 | 일부 · 백엔드로 넘김 | `7395c78c` | `FILE_REJECTED`에 응답 `meta.traceId`가 실린다. 거절 이유는 프론트로 고칠 수 없다. 요청: Fileserver가 REJECT를 422 실패 Envelope(`error.code` = 판정 code)로 답하거나, 202 `REJECTED` 응답에 판정 code 칸을 더한다. 앞의 것이면 `FILE_REJECTED` 분기는 지운다 |
|
||||
| 02-01 | 고침 | `4cef2a27` | `activateRelease`의 선택 옵션 `replaceUnreadablePointer`다. 켜면 rollback 목록을 잃어 기본값은 꺼짐이다. 1105/02-02의 남은 부분(읽히지 않는 release marker를 stage가 다시 쓰지 않음)은 그대로다 |
|
||||
| 03-02 | 고침 | `8156d85f` | 동작은 바꾸지 않았다. 문서를 고치고 IDEMPOTENT PUT 통합 테스트를 더했다 |
|
||||
| 03-03 | 고침 | `815ea58e` | `commandMutationIdentity`가 `resendSafe`(KEYED 또는 IDEMPOTENT)를 돌려준다. `BoundMutation.resendSafe?`는 선택 칸이다. 템플릿 안에는 IDEMPOTENT 쓰기 소비자가 없다 |
|
||||
| 04-01 | 고침 | `0438c3f2` | 리뷰 선택지 (c)다. 동작은 그대로 두고 규칙을 타입 주석과 설계 13.1에 적었다. bridge 예는 만들 때 endpoint를 검사한다(fetch 0회로 `TypeError`). `attempt` 안에서 연결을 만드는 조합 코드는 여전히 설정 오류가 서버 장애로 보인다 |
|
||||
| 04-02 | 고침 | `6f06e770` | 대응표(설계 9.2절)는 조합 코드가 따를 규칙이고 강제 수단은 없다 |
|
||||
| 05-01 | 고침 | `02a761f0` | 두 문서는 목표 설계라 `verify:documentation`이 읽지 않는다. 이 문장을 보는 검사는 없다 |
|
||||
| 06-01 | 고침 | `2a78169c` | redirect하는 호스트로 실제 등록을 돌려 보지 않았다(8절 미검증 그대로) |
|
||||
| 06-02 | 고침 | `1f4b929f` | 상한을 줄이는 변경은 잡지 않는다(수정 전 test도 잡지 않았다) |
|
||||
| 07-01 | 고침 | `c6c86dc3` | bulk 지원 여부는 결정 대기(1103/03-02) 그대로다 |
|
||||
| 07-02 | 고침 | `e7b1b018`, `efe11f15`(DR-04) | 두 칸 없는 HTTP 행을 가진 다운스트림은 동기화 뒤 `test:unit`이 실패한다 |
|
||||
| 08-01 | 고침 | `fbaaaee4`, `145be2df`(DR-03) | 참조 폼만 해당한다. 생성 작성 폼은 저장이 끝나면 목록으로 옮기므로 (B) 안내가 없다. 브라우저 3엔진 e2e는 더하지 않았다 |
|
||||
| 08-02 | 고침 | `116cbf3d` | 이미 생성한 기능에는 반영되지 않는다 |
|
||||
| 08-03 | 고침 | `7625dc45` | 완료 기준(drawer를 연 compact 골든과 스크롤바를 보이게 띄운 Chromium에서 가림막이 390 px까지)을 채웠다. header 띠는 디자인으로 받아들여 `docs/styling/design-system-platform.md` 8.2절에 적었다. `:has()`를 모르는 브라우저는 전처럼 띠가 남는다. Firefox·WebKit은 보지 않았다 |
|
||||
| 09-01 | 고침 | `06357e9c` | descriptor 없는 쓰기의 ID 오타는 여전히 아무 검사도 잡지 않는다(문서에 적음) |
|
||||
| 10-01 | 고침 | `a135fa8a` | capability 테스트를 `tests/unit/playwright-capabilities-run-isolation.test.ts`로 옮겼다. 드릴이 그 파일을 이름으로 지운다. 측정 스크립트의 조건은 여전히 소유 기능의 파일 존재다 |
|
||||
| 11-01 | 고침 | `9c4cddc2`, `95141f1d`(DR-05) | paramsSchema가 GET 입력과 다른 손 작성 상세 페이지는 규칙이 찾지 못해 기록으로만 정해진다(전과 같다) |
|
||||
| 12-01 | 고침 | `b8535f8c` | 목록 검사는 파일 단위다. 파일 안의 모든 테스트가 문서를 읽는지는 기계로 보지 않는다 |
|
||||
| 12-02 | 고침 | `68fde027` | FE-GATE-012는 변수 이름을 적고 실패한다(12-R2 `stale-bundle-rc=1`). 같은 모양일 수 있는 `check:app-build-input:bundle`, `check:optional-recipes --require-dist`, release candidate 조립은 보지 않았다 |
|
||||
| 13-01 | 고침 | `c5ab7a39` | 리뷰 선택지 (b)다. 승인이 거절된 run에도 advisory 기록이 생긴다(13-R1 C). gate 모양 기준선 digest를 다시 적었다. FE-GATE-015가 실패한 run에는 여전히 기록이 없다. 실제 runner의 upload는 미확인이다 |
|
||||
| 14-02 | 고침 | `ddc6353d` | 완료 기준 "다음 통합 기록에 그 대조 결과가 있다"는 16.6절이다. 새 clone에서 `git show 287dc6f` 본문의 두 해시는 여전히 열리지 않는다 |
|
||||
| 15-01 | 고침(D9) | `1eaa6447` | 규칙은 문서에만 있다. 예산 값을 규칙 밖으로 바꿔도 실패하는 테스트는 없다 |
|
||||
| 16-01 | 고침 | `af3344b3`, `eb03dabd`(DR-02) | spec 본문은 `-`가 든 이름만 찾는다(16.7절). 한 단어 ID만 적은 spec과 route ID·URL만 적은 spec은 못 잡는다. 1105/16-04의 남은 부분(`product-feature` 거짓 양성 20파일, dist 잔여 검사)은 그대로다 |
|
||||
| 1103/15-02 | 고침 | `43ed03d1` | 초기 파일 수 문장이 기록 `config/scale/feature-shape-ceilings.json`의 `initialJavascript.files`를 가리킨다. 상한 32는 예산 값이라 그대로 적었다 |
|
||||
|
||||
D10의 폼 쪽, 04-02의 표시, CHANGELOG 위치는 이렇게 정했다.
|
||||
|
||||
- 03-01 폼 쪽은 (i)다. 폼은 이미 `unknownSubmissionRef`로 새 저장을 막는다. 그 ref를 지우지 않으면 결과 불명 화면(확인·같은 키로 다시 보내기)이 남고, 다음 행동이 재전송이 된다. 더한 것은 문구 하나(`form.resendLater`)다. 버린 (ii)는 `useAppForm`이 코디네이터 상태를 받는 새 옵션이다. 폼과 훅을 새로 묶는 설계 변경이라 이 라운드에 넣지 않았다(`25685871` 본문).
|
||||
- 04-02 커밋(`6f06e770`)은 `!` 없이 들어갔다. 타입 인자 없이 부르는 호출이 이제 descriptor 타입을 추론해, 입력이 맞지 않으면 `check:types`가 실패할 수 있다. 그래서 CHANGELOG는 이 행을 BREAKING으로 적었다. 두 다운스트림은 이 함수를 부르지 않는다(문서 에이전트가 2026-11-06에 grep).
|
||||
- CHANGELOG는 새 미출시 절(`bbde570` → `fix/maturity-review-2026-11-06`)이다(`39aab7e3`). 1105 절은 범위 끝 `bbde570`의 상태라 고치지 않았다. 예외는 처음부터 틀린 문장(14-01, 09-01)이다.
|
||||
|
||||
### 16.5 확인
|
||||
|
||||
desktop 배치(`desktop:/tmp/claude-gates/r6/batch/`)에서 돌렸다. 항목마다 잠금을 잡고 그 커밋을 detached로 checkout했고, 모두 `restore=clean`이다. CI env는 `CI=true`와 빌드 식별 변수(`VITE_COMMIT_SHA` 등)를 준 것이다.
|
||||
|
||||
| 시점 | 실행 | 결과 |
|
||||
|---|---|---|
|
||||
| `5cfc3a65`(초기 JS 재기록) | FE-GATE-020(CI env) | PASS. 합치기 전 실패하던 `feature-shape-growth` 대조가 통과한다 |
|
||||
| `f1734913`(CHANGELOG 절과 16절 첫 커밋) | FE-GATE-020(CI env, 1,245초) | PASS |
|
||||
| | FE-GATE-012(CI env) | PASS |
|
||||
| | 빠른 검사 10개(`check:types`, `lint`, `check:architecture`, `check:ci`, `check:registries`, `check:diagnostics`, `check:adapter-inventory`, `check:design-system`, `check:i18n`, `check:test-evidence`) | 모두 rc=0 |
|
||||
| | `test:unit` 3,077 · `test:component` 284 · `test:integration` 214 · `test:contract` 24 · `test:runtime-schema` 60 · `test:visual` 7 | 모두 통과 |
|
||||
| | `verify:documentation`(옆 백엔드 checkout 있음·없음), 문서 단위 테스트 4개 30건 | PASS_SCOPED 둘, 30 통과 |
|
||||
| DR 수정(16.7절) | RED: DR-01 14건, DR-02 2건, DR-03 1건 실패. 기대한 테스트에서 기대한 이유로 실패했다. GREEN: 각 145·9·68건과 DR-04 6건, DR-05 10건 통과 | 기대대로 |
|
||||
| | 변이: DR-04의 `UNREACHED` 건너뛰기 제거 → 새 테스트 1건 실패. 지난 07-02 변이(참조 응답 행의 두 칸 삭제) → 2건 실패. 16-01 spec 본문 변이(`invoice-feature`) → 잔여 `tests/e2e/checkout.spec.ts`를 그대로 잡음 | 모두 잡힘 |
|
||||
| | 03-R1 실험(DR-01 커밋) | X1~X3 키 `["key-1","key-1","key-1"]`, X5 키 `["key-1","key-1"]`, 다시 저장 뒤 요청 2번 그대로 |
|
||||
| | 검사 브랜치 끝: 타입·lint·아키텍처, `test:unit` 3,082, 문서 검사. 폼 브랜치 끝: 타입·lint·아키텍처·i18n과 관련 단위 테스트 17건 | 모두 통과 |
|
||||
| `59b2ccb5`(DR 합친 끝) | 빠른 검사 10개 | 모두 rc=0 |
|
||||
| | `test:unit` 3,090 · `test:component` 294 · `test:integration` 214 · `test:contract` 24 · `test:runtime-schema` 60 · `tests/features` 126 · `test:visual` 7 | 모두 통과. 초기 JS 기록 대조도 `test:unit` 안에서 통과(허용치 안) |
|
||||
| | `test:coverage`(CI env) | 4,143 통과, risk coverage 418/418 |
|
||||
| | FE-GATE-012(CI env), 문서 검사 | PASS, PASS_SCOPED |
|
||||
| FR-01 수정(16.8절) | RED 4건 실패(scaffold 모양 failure, 422 mismatch, 참조 페이지 422, 다시 마운트한 폼의 422 mismatch). GREEN 149건 통과 | 기대대로 |
|
||||
| | 03-R1 실험(FR-01 커밋) | DR-01 때와 같다 |
|
||||
| `57ffcc96`(= `8b8b6c54` 트리) | 타입·lint·아키텍처, `test:unit` 3,090 · `test:component` 296 · `tests/features` 127, `test:coverage` 4,146(risk 418/418), 문서 검사 | 모두 통과 |
|
||||
|
||||
돌리지 않은 것:
|
||||
|
||||
- DR·FR 수정 뒤의 FE-GATE-020. 메인 세션 지시로 `f1734913`에서만 돌렸다. DR-02가 바꾼 제거 드릴의 잔여 판정은 단위 테스트와 16-01 변이로만 봤다.
|
||||
- Playwright e2e(FE-GATE-008)와 세 엔진. 폼 동작을 바꿨지만 컴포넌트·기능 테스트로만 봤다.
|
||||
- merge 게이트 14개. 최종 head에서 메인 세션이 돈다.
|
||||
- 이 README 커밋 자체. 문서 검사만 돌린다. 결과는 이 문서에 적을 수 없어서 메인 세션 보고에 적는다.
|
||||
|
||||
|
||||
### 16.6 해시 대조 (1106/14-02 완료 기준)
|
||||
|
||||
CHANGELOG 머리말의 단계대로 `git merge-base --is-ancestor <해시> 8b8b6c54`(코드 쪽 마지막 커밋, 이 README 커밋의 부모)를 하나씩 돌렸다. 2026-11-06, 노트북 worktree. 처음에는 CHANGELOG 절을 합친 `9b19f753`에서 돌렸고, DR·FR 수정을 합친 뒤 다시 돌렸다. 아래는 다시 돌린 결과다.
|
||||
|
||||
| 대상 | 해시 | 결과 |
|
||||
|---|---|---|
|
||||
| CHANGELOG 새 절 | 36개 | 모두 조상이다. 35개는 기준점 `bbde570` 뒤 범위 안이다(리뷰 기록 `302d3a5` 포함). 나머지 1개는 기준점 `bbde570`이다 |
|
||||
| 범위 커밋 본문(`302d3a5..8b8b6c54`, merge 포함) | 7~12자리 16진 문자열 29개 | 이 repo 커밋 26개는 모두 조상이다(DR·FR 수정이 인용한 `80e7f1d`, `145be2d`, `eb03dab`, `efe11f1`, `95141f1`, `b41990c`, `6142cc8`, `9b19f753` 등 포함). 셋은 이 repo 커밋이 아니다: `45d2a478`(백엔드 pin), `d3810a0`(memento-frontend), `7bebafe6`(바꾸기 전 CI 기준선 digest 앞자리) |
|
||||
| 1105 README 16.2절 D7 행 | `5c0b37e`, `f849d78` | 둘 다 조상이다 |
|
||||
| 이 README 16절 | 59개 | 54개는 조상이다. 다섯은 닿지 않는 것이 맞다: 위 셋, 그리고 아래 `287dc6f` 본문의 두 해시 |
|
||||
|
||||
`287dc6f` 본문의 두 해시(`ab0d4a1`, `7ce9bf1`)는 여전히 닿지 않는다. 올린 이력이라 고치지 않는다(16.2절).
|
||||
|
||||
### 16.7 diff 리뷰 (`302d3a5..f1734913`)
|
||||
|
||||
메인 세션 지시대로 맥락 없는 서브에이전트 하나가 이 라운드의 diff만 읽고 리뷰했다. 코드는 실행하지 않았다(E1). 새 High·P1 후보는 없다. Medium 2건은 이 라운드 수정이 만든 회귀다. 오케스트레이터가 코드에서 다시 확인했다. 메인 세션이 그 둘은 고치고, Low는 작으면 고치라고 정했다.
|
||||
|
||||
| ID | 심각도·우선순위 | 내용 | 처리 |
|
||||
|---|---|---|---|
|
||||
| DR-01 | Medium·P2 | 03-01·03-03이 같은 키 재전송의 모든 `NOT_APPLIED`를 결과 불명으로 잡아 둔다. 결정적 거절(400 `VALIDATION_FAILED` 등)이면 저장이 꺼지고, 다시 보내도 같은 400이 온다. 출구는 사실이 아닌 "변경됨으로 확인"이나 새로고침뿐이다 | 고침 `80e7f1d6`. 16.2절 D10 보완. 400으로 끝나는 재전송은 필드 오류를 보이고, 고친 값은 새 키로 다시 받는다. 남기는 경우에도 확인 버튼이 화면에 있다(테스트로 고정). 기능이 선언한 결정적 거절(생성 기능의 400 `<FEATURE>_INVALID`)은 어느 쪽인지 알 수 없어 남기고, 출구는 확인이다(CHANGELOG 알려진 제한). 이 커밋에서는 그 code가 kind 때문에 풀렸다. 실제로 남게 된 것은 16.8절 FR-01 수정 뒤다 |
|
||||
| DR-02 | Medium·P2 | 16-01의 spec 본문 검색이 대소문자를 무시하고 `_`를 경계로 본다. `messages`·`status` 같은 흔한 ID를 지우면 템플릿 자신의 spec이 잔여로 잡혀 드릴이 실패한다 | 고침 `eb03dabd`. 메인 세션 기준대로 적힌 그대로(대소문자 구분) 찾고, 경계는 `[A-Za-z0-9_-]`다. **기준에 하나를 더했다.** 그 둘만으로는 `status`·`reports`가 0건이 되지 않는다. 템플릿 spec이 `status: 200`, `getByRole("status")`, 테스트 제목의 "reports"를 쓴다. 그래서 spec 본문은 `-`가 든 이름만 찾는다. 이 기준은 오케스트레이터가 수정 에이전트에 `status`·`reports`도 0건이어야 한다고 지시해서 생겼다. 대가로 한 단어 ID만 본문에 적은 spec은 못 잡는다. 1106/16-01 전(`bbde570`, spec 본문을 보지 않음)보다 좁지는 않다. 메인 세션이 뒤집을 수 있다. 뒤집으면 `scripts/lib/feature-residue.ts`의 `-` 필터 한 줄을 지우고, 흔한 한 단어 ID의 거짓 양성을 알려진 제한으로 둔다 |
|
||||
| DR-03 | Low·P3 | 08-01 뒤 다시 마운트한 폼에서 "변경됨으로 확인"을 누르면, 보낸 적 없는 지금 입력을 저장됨으로 두고 지운다 | 고침 `145be2df`. 제출한 값이 없으면 결과 표시와 포커스 이동만 한다. 08-01 완료 기준 테스트는 그대로 통과해야 한다 |
|
||||
| DR-04 | Low·P3 | 07-02 뒤 탐침이 닿지 않는 스키마(`UNREACHED`, 객체가 아닌 페이로드)는 행을 어떻게 적어도 정책 검사를 통과할 수 없다(추론, 다운스트림 쪽) | 고침 `efe11f15`. `UNREACHED`면 정책 비교만 빼고 `direction`은 계속 요구한다. 07-02 전에는 이 경우를 통째로 건너뛰었으므로 약화가 아니다. 탐침은 이 스키마를 판정할 수 없다. 남은 것: `strictObject \| null` 같은 합집합도 `UNREACHED`가 되어 정책 비교에서 빠질 수 있다(커밋 본문, 추론) |
|
||||
| DR-05 | Low·P3 | 11-01 규칙은 `paramsSchema`만 보고 기록을 기대한다. 같은 스키마를 쓰지만 그 GET을 부르지 않는 라우트는 FE-GATE-009가 거짓 실패하고, `errors.md`의 고칠 곳 안내가 틀린다(추론) | 고침 `95141f1d`(문서). `errors.md`·매뉴얼 01·report 실패 문장에 "그 GET을 부르지 않는 라우트는 자기 `paramsSchema`를 둔다"를 더했다. report 판정은 그대로다 |
|
||||
| DR-06 | Low·P3 | 04-02 커밋(`6f06e770`)에 `!`·`BREAKING CHANGE:`가 없는데 CHANGELOG는 BREAKING으로 적는다 | **남김.** 커밋 메시지를 고치려면 이미 합친 merge들을 다시 쌓아야 한다. BREAKING은 CHANGELOG 새 절과 16.4절 끝 목록에 적혀 있다. PR 본문에도 같은 줄을 둔다(메인 세션 몫) |
|
||||
|
||||
수정은 `f1734913` 위의 두 브랜치(`fix/r1106-dr-forms`, `fix/r1106-dr-checks`)에서 했고 `591dd31a`·`3abe28e5`로 합쳤다. 두 브랜치가 CHANGELOG 같은 줄 근처를 고쳐 둘째 merge에서 충돌했다. 충돌한 9쌍은 모두 한쪽만 바뀐 줄이라, 바뀐 쪽을 골랐다. 합친 결과는 두 브랜치가 CHANGELOG에서 바꾼 줄(5줄, 6줄)을 모두 담는다(11줄). 검사 브랜치가 비워 둔 CHANGELOG 커밋 칸 셋은 `59b2ccb5`가 채웠다.
|
||||
|
||||
### 16.8 마지막 리뷰 (`f1734913..59b2ccb5`)
|
||||
|
||||
DR 수정 커밋만 맥락 없는 서브에이전트 하나가 다시 읽었다. 코드는 실행하지 않았다(E1). 메인 세션 지시는 둘이었다. High·P1이 나오면 고치기 전에 알린다. Medium·Low는 고치지 않고 여기 적는다.
|
||||
|
||||
| ID | 리뷰어 등급 → 최종 | 내용 | 처리 |
|
||||
|---|---|---|---|
|
||||
| FR-01 | High·P1 → **Medium·P2** | DR-01 수정(`80e7f1d6`)의 `isRefusedOnEveryAttempt`가 `kind === "VALIDATION_REJECTED"`면 code를 보지 않고 결과 불명을 푼다. 이 kind는 기능 `mapProblem`이 붙인다. 생성 scaffold는 선언 code `<FEATURE>_INVALID`를, 참조 기능은 모든 422를 이 kind로 바꾼다. 그래서 함수 주석·CHANGELOG·런북이 남긴다고 적은 기능 선언 code와 422 `IDEMPOTENT_REQUEST_MISMATCH`가 풀렸다. 테스트는 `mapProblem`을 거치지 않은 failure로만 검사했다 | **고침** `b41990cd`(16.2절 D10 보완 2). 오케스트레이터가 고치기 전에 메인 세션에 알렸고, 메인 세션이 `errors.ts:273`을 직접 확인했다. 등급: 같은 길인 03-01과 같이 Medium·P2다. 규칙 위반은 코드로 확인했다(E1). 중복 쓰기 피해가 나려면 다운스트림의 상태 규칙(이름 중복 등)이 멱등성 재생보다 먼저 돌아야 한다(추론). 리뷰어는 가이드 35.2의 "결과 불명 작업의 무방비 재실행"으로 High를 줬다. 테스트: scaffold 모양 failure와 422 mismatch는 남긴다. 참조 페이지의 422 재전송은 남기고 확인 버튼을 보인다. 다시 마운트한 폼에서 다른 값으로 보이는 재전송이 422 mismatch를 받아도 남긴다(FR-03과 이어지는 길) |
|
||||
| FR-02 | Medium·P2 | 400 `VALIDATION_FAILED`를 "매 시도가 받는 거절"로 보는 전제가, 시간이나 DB를 읽는 검증에서 깨진다(추론) | 코드는 고치지 않았다. 계약 문서 6.1절에 규칙 한 문장을 더했다(`6142cc8e`). 짝 백엔드 pin `45d2a478`을 grep했다. `VALIDATION_FAILED`는 `GlobalExceptionHandler`의 Bean Validation 세 갈래, 읽을 수 없는 본문, 페이지 파라미터에서만 나온다. main 소스와 생성기 템플릿에 `@Future`·`@Past`나 직접 만든 `ConstraintValidator`가 없다. 백엔드로 넘길 것은 없다. 다운스트림이 그런 검증을 더하면 전제가 깨진다(계약 문서 규칙) |
|
||||
| FR-03 | Medium·P2 | 다시 마운트한 폼에서 "같은 요청으로 다시 보내기"는 보내지 않은 화면 값을 제출한 값으로 쓴다(`use-app-form.ts:425`). 실제로 다시 보내는 것은 코디네이터가 보관한 원래 입력이다. 서버 데이터는 바뀌지 않지만, 입력이 지워지거나 이탈 확인이 꺼질 수 있다 | **남김.** 메인 세션 지시. 이 길에서 422가 결과 불명을 풀던 것은 FR-01 수정이 막았다 |
|
||||
| FR-04 | Low·P3 | DR-02가 한 단어 ID를 spec 본문 검색에서 뺐지만, `src` 부분 문자열 검색(1105/16-04 남은 부분) 때문에 그런 ID의 드릴은 여전히 실패할 수 있다. 탐지만 줄었다 | **남김.** 1105/16-04의 남은 부분과 같은 원인이다 |
|
||||
| FR-05 | Low·P3 | DR-04의 `UNREACHED` 제외가 루트 union(`strictObject \| null` 등)까지 덮는다. 문서는 "객체가 아닌 본문"만 적는다. 그런 행에 적은 정책 값은 아무도 검사하지 않는다 | **남김.** 템플릿 안에는 해당 스키마가 없다 |
|
||||
|
||||
FR-01 수정 뒤에는 diff 리뷰를 다시 하지 않았다(메인 세션 지시). 이 수정은 결과 불명을 푸는 경우를 줄이기만 한다. 빠져나가는 길(확인 버튼)은 테스트가 고정한다.
|
||||
@@ -213,6 +213,7 @@ primitive token -> semantic token -> component token
|
||||
- `button-primary-background`
|
||||
- `field-border-invalid`
|
||||
- `dialog-elevation`
|
||||
- `dialog-backdrop`, `dialog-backdrop-on-surface`, `dialog-backdrop-weight`
|
||||
- `navigation-active-background`
|
||||
|
||||
컴포넌트 토큰은 제품별 variant를 만들기 위한 우회 경로가 아니다. 두 개 이상의
|
||||
@@ -537,6 +538,31 @@ Radix는 overlay와 primitive composition을 중심으로 평가할 수 있다.
|
||||
- Escape와 명시적 닫기 action을 제공한다.
|
||||
- 닫은 뒤 trigger 또는 안전한 대체 위치로 focus를 복원한다.
|
||||
- nested overlay와 route transition 중 orphan portal을 남기지 않는다.
|
||||
- modal 가림막은 창 끝까지 덮는다. 스크롤바 자리도 덮는다(아래).
|
||||
|
||||
**스크롤바 자리(1106/08-03).** `:root`의 `scrollbar-gutter: stable`
|
||||
(`src/presentation/styles/theme/base.css`, 1105/15-05)은 일반(overlay가 아닌)
|
||||
스크롤바를 쓰는 브라우저에서 문서가 스크롤되지 않아도 오른쪽에 스크롤바 폭
|
||||
(Chromium 15 px)을 비워 둔다. 그 자리에는 root의 배경색이 보인다. 페이지 내용,
|
||||
header, 고정 위치 요소, modal의 `::backdrop`은 모두 그 자리 앞에서 끝난다.
|
||||
|
||||
- modal이 열린 동안(`.ui-dialog[open]`) root 배경색을, 가림막을 페이지 바탕 위에
|
||||
겹친 불투명한 색(`--dialog-backdrop-on-surface`)으로 바꾼다
|
||||
(`src/presentation/styles/theme/primitives.css`). 가림막 색 `--dialog-backdrop`과
|
||||
이 색은 같은 비율(`--dialog-backdrop-weight`)을 읽는다. 첫 시도(`:modal`로 고른
|
||||
gradient 한 겹)는 Chromium에서 그 자리를 바꾸지 못했다. 페이지 바탕은 `body`가
|
||||
같은 색으로 칠하므로 root 배경은 그 자리에만 보인다. 문서가 스크롤되면 그
|
||||
자리에 스크롤바가 그려지고, 가림막은 스크롤바를 덮지 않는다(브라우저 동작).
|
||||
검사는 `tests/visual/scrollbar-gutter.visual.spec.ts`다. 스크롤바를 보이게
|
||||
띄운 Chromium에서 그 자리와 바로 옆 가림막의 픽셀 색을 비교한다.
|
||||
- header 띠는 그 자리 앞에서 끝나고, 그 자리는 페이지 바탕색으로 남는다.
|
||||
받아들인 모습이다. 스크롤되지 않는 화면에서만 보이고 기능 영향이 없다. header
|
||||
색으로 칠하려면 root 배경이 셸의 header 높이(4.5rem)와 색을 알아야 하고, 셸이
|
||||
없는 화면(부팅 화면, 오류 화면)에서는 그 띠를 빼야 한다. 제품이 header를 창
|
||||
끝까지 그리려면 그 결합을 감수하고 root 배경에 header 높이만큼의 띠를 더한다.
|
||||
- 오른쪽에 붙는 drawer(`placement="end"`)를 열면 drawer와 창 끝 사이에 가림막
|
||||
색 띠가 남는다. 템플릿은 이 배치를 쓰지 않고, 화면에서 확인하지 않았다.
|
||||
RTL에서 스크롤바가 어느 쪽에 그려지는지도 확인하지 않았다.
|
||||
|
||||
### 8.3 Form 기준
|
||||
|
||||
|
||||
@@ -953,6 +953,13 @@ Playwright `toHaveScreenshot()`을 사용한다.
|
||||
`check-test-evidence`는 기준선 PNG가 4장 이상인지만 본다. 위 목록의 각
|
||||
화면이 있는지는 검사하지 않는다.
|
||||
|
||||
골든과 달리 기준 이미지가 없는 시각 검사 1건이 같은 설정에서 돈다
|
||||
(1106/08-03). `tests/visual/scrollbar-gutter.visual.spec.ts`는 Chromium을
|
||||
`--hide-scrollbars` 없이 띄운다. 스크롤되지 않는 화면(`/not-found`, 390×844)에서
|
||||
drawer를 열고, 오른쪽 스크롤바 자리의 픽셀 색이 바로 옆 가림막과 같은지 본다.
|
||||
골든은 스크롤바를 숨긴 채 찍으므로 그 자리에 스크롤바가 그려지는 경우를 보지
|
||||
않는다.
|
||||
|
||||
아직 기준선이 없고, 제품이 화면을 늘릴 때 추가할 후보:
|
||||
|
||||
- 각 page template
|
||||
@@ -1026,7 +1033,7 @@ TEST_RUN_ID=a playwright test
|
||||
| 변수 | 누가 읽나 | 없을 때 |
|
||||
|---|---|---|
|
||||
| `TEST_RUN_ID` | 다섯 Playwright 설정, `tests/e2e/preload-use.spec.ts` | `dist`, `artifacts/tests/<이름>/` |
|
||||
| `RUN_OUTPUT_ROOT` | 빌드 단계 전부(`scripts/build-frontend.ts`가 부르는 것), `vite.config.ts`. 설정이 web server에만 넘긴다 | `.` |
|
||||
| `RUN_OUTPUT_ROOT` | 빌드 단계 전부(`scripts/build-frontend.ts`가 부르는 것), `vite.config.ts`. 설정이 web server에만 넘긴다. 빌드 뒤 검사(`scripts/generate-supply-chain.ts`, `scripts/check-bundle.ts`)는 `.`이 아니면 멈춘다 | `.` |
|
||||
| `TEST_E2E_PORT`, `TEST_VISUAL_PORT`, `TEST_CAPABILITIES_PORT`, `TEST_STORYBOOK_PORT`, `TEST_DEV_PORT` | 각 설정 | 빈 포트 |
|
||||
|
||||
- run ID는 글자·숫자·`.`·`_`·`-` 64자 이하이고 글자나 숫자로 시작한다.
|
||||
@@ -1035,6 +1042,9 @@ TEST_RUN_ID=a playwright test
|
||||
- `RUN_OUTPUT_ROOT`는 직접 export하지 않는다. 설정이 run ID에서 만든다. 빌드
|
||||
코드는 `TEST_RUN_ID`를 읽지 않는다. e2e가 저장소 복사본을 빌드할 때 그
|
||||
빌드는 복사본 자기 `dist`에 써야 하기 때문이다.
|
||||
- 빌드 뒤 검사는 checkout의 `dist`와 `artifacts/`만 읽는다. 그래서
|
||||
`RUN_OUTPUT_ROOT`가 셸에 있으면 `check:bundle`은 변수 이름을 적고 실패한다.
|
||||
빌드는 `.tmp/` 아래에 쓰고 검사는 이전 빌드를 재서 통과했기 때문이다(1106/12-02).
|
||||
- 규칙은 `scripts/lib/run-isolation.ts` 한 곳에 있다.
|
||||
|
||||
두 e2e 실행을 동시에 돌리는 예:
|
||||
|
||||
@@ -9,6 +9,7 @@ import {
|
||||
bundlePerformanceArtifactSchema,
|
||||
} from "./contracts/release-artifacts.ts";
|
||||
import { classifyViteJavascript } from "./lib/classify-vite-bundle.ts";
|
||||
import { checkoutBuildReadFailure } from "./lib/run-isolation.ts";
|
||||
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
|
||||
|
||||
type ViteManifest = Record<
|
||||
@@ -21,6 +22,16 @@ type BundleBudgets = {
|
||||
lazyChunkGzipBytes: number;
|
||||
};
|
||||
|
||||
// 1106/12-02. This reads dist/.vite/manifest.json and the inventory
|
||||
// scripts/generate-supply-chain.ts made of dist. Under RUN_OUTPUT_ROOT the
|
||||
// build wrote elsewhere, and this passed a build over budget on the earlier
|
||||
// one the checkout still held.
|
||||
const outputRootFailure = checkoutBuildReadFailure("scripts/check-bundle.ts");
|
||||
if (outputRootFailure !== undefined) {
|
||||
process.stderr.write(`${outputRootFailure}\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const report = bundleOutputInventoryArtifactSchema.parse(
|
||||
JSON.parse(await readFile("artifacts/performance/bundle.json", "utf8")) as unknown,
|
||||
);
|
||||
|
||||
@@ -589,7 +589,7 @@ export default function ${pascal}DetailPage() {
|
||||
|
||||
export function renderCreatePage({ names, routeId, write }: SliceShape): string {
|
||||
const { base, camel, pascal, upper } = names;
|
||||
return `import { useCallback } from "react";
|
||||
return `import { useCallback, useEffect, useRef } from "react";
|
||||
import { Link, useNavigate } from "react-router-dom";
|
||||
|
||||
import type { Result } from "../../../contracts/result.ts";
|
||||
@@ -619,7 +619,8 @@ import { ${camel}RouteUrl } from "./${base}-routes.ts";
|
||||
import { use${pascal}Create } from "./use-${base}-create.ts";
|
||||
|
||||
/**
|
||||
* The create form. A saved item opens its detail page. The backend's refusal
|
||||
* The create form. A saved item opens its detail page, unless the user left
|
||||
* this page while it saved. The backend's refusal
|
||||
* of the name (400 ${write.invalidCode}, refused before the write) shows on
|
||||
* the field and the form saves again. A save whose result is unknown (the
|
||||
* response was lost) keeps the form: the user checks, or, for a KEYED
|
||||
@@ -633,9 +634,18 @@ export default function ${pascal}CreatePage() {
|
||||
name: message("${camel}.form.name"),
|
||||
} satisfies Record<keyof ${pascal}FormValues, string>;
|
||||
const mutation = use${pascal}Create();
|
||||
// A save outlives this page when the user leaves while it runs. Ending
|
||||
// then, it does not take them to its item or the list (1106/08-02).
|
||||
const mounted = useRef(false);
|
||||
useEffect(() => {
|
||||
mounted.current = true;
|
||||
return () => {
|
||||
mounted.current = false;
|
||||
};
|
||||
}, []);
|
||||
const openSaved = useCallback(
|
||||
(outcome: Result<${pascal}ItemView> | null) => {
|
||||
if (outcome?.ok) {
|
||||
if (outcome?.ok && mounted.current) {
|
||||
void navigate(
|
||||
${camel}RouteUrl("${write.detail.routeId}", {
|
||||
params: { ${write.idParam}: outcome.value.itemId },
|
||||
@@ -726,7 +736,7 @@ export default function ${pascal}CreatePage() {
|
||||
onReconcileUnknownEffect={(resolution) => {
|
||||
void mutation.reconcileUnknownEffect(resolution).then(() => {
|
||||
form.settleApplied();
|
||||
void navigate(${camel}RouteUrl("${routeId}"));
|
||||
if (mounted.current) void navigate(${camel}RouteUrl("${routeId}"));
|
||||
});
|
||||
}}
|
||||
// Drawn only for a request with a key (a KEYED command).
|
||||
@@ -788,7 +798,7 @@ export function renderCreatePageTest({ names, apiPath, write }: SliceShape): str
|
||||
});`;
|
||||
return `// @vitest-environment jsdom
|
||||
|
||||
import { screen } from "@testing-library/react";
|
||||
import { screen, waitFor, within } from "@testing-library/react";
|
||||
import { http, HttpResponse, type JsonBodyType } from "msw";
|
||||
import { setupServer } from "msw/node";
|
||||
import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
|
||||
@@ -931,6 +941,59 @@ ${unknownTest}
|
||||
expect(await screen.findByText("First item")).toBeVisible();
|
||||
expect(posts).toHaveLength(1);
|
||||
});
|
||||
|
||||
// 1106/08-02. The user leaves for the list while the save runs. The save
|
||||
// that ends then does not take them to the item: they stay on the list.
|
||||
it("stays on the list the user went to while the create was saving", async () => {
|
||||
let answerPost: ((response: Response) => void) | undefined;
|
||||
api.use(
|
||||
http.post(
|
||||
\`\${API}${apiPath}\`,
|
||||
() =>
|
||||
new Promise<Response>((resolve) => {
|
||||
answerPost = resolve;
|
||||
}),
|
||||
),
|
||||
);
|
||||
let lists = 0;
|
||||
api.use(
|
||||
http.get(\`\${API}${apiPath}\`, () => {
|
||||
lists += 1;
|
||||
return HttpResponse.json({
|
||||
success: true,
|
||||
data: lists === 1 ? [] : [{ id: ITEM_ID, name: "First item" }],
|
||||
meta: META,
|
||||
});
|
||||
}),
|
||||
);
|
||||
answerItem();
|
||||
const user = await openForm();
|
||||
await user.type(await nameField(), "First item");
|
||||
await user.click(saveButton());
|
||||
await waitFor(() => expect(answerPost).toBeDefined());
|
||||
|
||||
await user.click(
|
||||
within(screen.getByRole("navigation", { name: KO_MESSAGES["template.breadcrumb"] })).getByRole(
|
||||
"link",
|
||||
{ name: MESSAGES["${camel}.list.title"] },
|
||||
),
|
||||
);
|
||||
expect(
|
||||
await screen.findByRole("heading", { level: 1, name: MESSAGES["${camel}.list.title"] }),
|
||||
).toBeVisible();
|
||||
answerPost?.(created());
|
||||
|
||||
// The create invalidates the list: the item there means the save ended.
|
||||
// Opening the item would show its name as the heading within a second
|
||||
// (earlier tests here loaded the detail page); it never comes.
|
||||
expect(await screen.findByRole("link", { name: "First item" })).toBeVisible();
|
||||
await expect(
|
||||
screen.findByRole("heading", { level: 1, name: "First item" }, { timeout: 1_000 }),
|
||||
).rejects.toThrow();
|
||||
expect(
|
||||
screen.getByRole("heading", { level: 1, name: MESSAGES["${camel}.list.title"] }),
|
||||
).toBeVisible();
|
||||
});
|
||||
});
|
||||
`;
|
||||
}
|
||||
|
||||
@@ -39,8 +39,18 @@ import {
|
||||
parseRepositoryFileInventoryPolicy,
|
||||
} from "./lib/repository-file-inventory.ts";
|
||||
import { collectDistOutputs, distSha256 } from "./lib/release-candidate.ts";
|
||||
import { checkoutBuildReadFailure } from "./lib/run-isolation.ts";
|
||||
import { deterministicSupplyChainGeneratedAt } from "./lib/supply-chain-time.ts";
|
||||
|
||||
// 1106/12-02. This reads artifacts/release/build-manifest.json and dist where
|
||||
// the checkout keeps them. Under RUN_OUTPUT_ROOT the build wrote elsewhere,
|
||||
// and this recorded the earlier build the checkout still held.
|
||||
const outputRootFailure = checkoutBuildReadFailure("scripts/generate-supply-chain.ts");
|
||||
if (outputRootFailure !== undefined) {
|
||||
process.stderr.write(`${outputRootFailure}\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
type Document = Record<string, unknown>;
|
||||
|
||||
function isRecord(value: unknown): value is Document {
|
||||
|
||||
@@ -14,6 +14,12 @@ import path from "node:path";
|
||||
* only the failure state, no record otherwise. A route's latest run therefore
|
||||
* decides. `scripts/write-a11y-report.ts` reads the records and reports those
|
||||
* routes under `notChecked` instead of in the passed `scope`.
|
||||
*
|
||||
* 1106/11-01. No record used to mean "checked", and nothing but the spec said
|
||||
* which routes needed one: a record call changed to `null` (review 11-R2) put
|
||||
* the detail page back in `scope` and every check passed. The report now
|
||||
* works the same routes out from the installed descriptors
|
||||
* (`oneResourceReadRoutes`) and fails when one has no record.
|
||||
*/
|
||||
export const A11Y_DATA_STATE_DIRECTORY = "artifacts/tests/a11y-data-state";
|
||||
|
||||
@@ -74,6 +80,88 @@ export async function readA11yNotCheckedRoutes(
|
||||
return Object.freeze(notChecked);
|
||||
}
|
||||
|
||||
export type OneResourceRoute = Readonly<{
|
||||
routeId: string;
|
||||
operationIds: readonly string[];
|
||||
}>;
|
||||
|
||||
type RouteFacts = Readonly<{
|
||||
routeId: string;
|
||||
access: string;
|
||||
paramsSchema: string | null;
|
||||
}>;
|
||||
|
||||
type ReadFacts = Readonly<{
|
||||
contract: Readonly<{
|
||||
operationId: string;
|
||||
method: string;
|
||||
pathTemplate: string;
|
||||
inputValidator: Readonly<{ schemaId: string }>;
|
||||
outputValidator: Readonly<{
|
||||
safeParse(value: unknown): Readonly<{ success: boolean }>;
|
||||
}>;
|
||||
}>;
|
||||
}>;
|
||||
|
||||
/**
|
||||
* 1106/11-01. The installed routes the spec can scan only on their failure
|
||||
* state, from the descriptors alone: a protected route whose `paramsSchema` is
|
||||
* the input of a GET that reads one resource. A GET reads one resource by the
|
||||
* rule `tests/e2e/support/installed-api-answers.ts` answers with: it has a
|
||||
* path parameter and its output rejects an empty list, so no generic body
|
||||
* answers it. The spec signs in only on protected routes, so a public route is
|
||||
* not listed.
|
||||
*
|
||||
* This finds the detail pages that take their params schema from their read
|
||||
* (the reference sample and every `create:feature --with-create` slice). A
|
||||
* detail page whose params schema differs is not found, and its record alone
|
||||
* decides, as before.
|
||||
*/
|
||||
export function oneResourceReadRoutes(
|
||||
routes: Iterable<RouteFacts>,
|
||||
operations: Iterable<ReadFacts>,
|
||||
): readonly OneResourceRoute[] {
|
||||
const readsByInput = new Map<string, string[]>();
|
||||
for (const { contract } of operations) {
|
||||
if (contract.method !== "GET" || !contract.pathTemplate.includes("{")) continue;
|
||||
if (contract.outputValidator.safeParse([]).success) continue;
|
||||
const reads = readsByInput.get(contract.inputValidator.schemaId) ?? [];
|
||||
reads.push(contract.operationId);
|
||||
readsByInput.set(contract.inputValidator.schemaId, reads);
|
||||
}
|
||||
const found: OneResourceRoute[] = [];
|
||||
for (const route of routes) {
|
||||
if (route.access !== "session-required" || route.paramsSchema === null) continue;
|
||||
const reads = readsByInput.get(route.paramsSchema);
|
||||
if (reads === undefined) continue;
|
||||
found.push(
|
||||
Object.freeze({ routeId: route.routeId, operationIds: Object.freeze([...reads]) }),
|
||||
);
|
||||
}
|
||||
return Object.freeze(found);
|
||||
}
|
||||
|
||||
/**
|
||||
* 1106/11-01. One line for each route in `expected` that `notChecked` leaves
|
||||
* out, which `a11y.json` would count as passed. Empty when every route that
|
||||
* reads one resource has its failure-state record. A record for a route not in
|
||||
* `expected` claims less and is not refused.
|
||||
*/
|
||||
export function oneResourceRoutesCountedAsChecked(
|
||||
expected: readonly OneResourceRoute[],
|
||||
notChecked: readonly A11yNotCheckedRoute[],
|
||||
): readonly string[] {
|
||||
const recorded = new Set(notChecked.map(({ routeId }) => routeId));
|
||||
return Object.freeze(
|
||||
expected
|
||||
.filter(({ routeId }) => !recorded.has(routeId))
|
||||
.map(
|
||||
({ routeId, operationIds }) =>
|
||||
`${routeId} reads one resource (${operationIds.join(", ")}) but has no failure-state record in ${A11Y_DATA_STATE_DIRECTORY}; tests/e2e/accessibility.spec.ts must record why it scanned the route on its failure state only, or, when the route's page does not call that read, the route needs a params schema of its own`,
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* The `artifacts/tests/a11y.json` value. `automatedStatus: "passed"` speaks
|
||||
* for `scope` only: the installed routes axe scanned in their own state.
|
||||
|
||||
@@ -11,13 +11,28 @@ import path from "node:path";
|
||||
* there is a reference the type checker cannot see (a catalog key, a
|
||||
* runtime override, a link).
|
||||
* - `tests/`: a file named after the feature, or one that imports from the
|
||||
* feature's `src/features/<dir>/` or `tests/features/<dir>/`. The test
|
||||
* text is not searched for the bare name: the template's own tests use
|
||||
* example IDs as data (`tests/unit/create-feature.test.ts` writes
|
||||
* feature's `src/features/<dir>/` or `tests/features/<dir>/`. A vitest
|
||||
* test's text is not searched for the bare name: the template's own tests
|
||||
* use example IDs as data (`tests/unit/create-feature.test.ts` writes
|
||||
* `invoice-feature`, the manual's example, 51 times), and the drill flagged
|
||||
* them as residue of a product feature that took that name. A test that
|
||||
* still depends on the removed feature fails `test:all`, which the drill
|
||||
* runs.
|
||||
* them as residue of a product feature that took that name. A vitest test
|
||||
* that still depends on the removed feature fails `test:all`, which the
|
||||
* drill runs.
|
||||
* - 1106/16-01. `test:all` runs vitest only (the `*.test.ts(x)` files under
|
||||
* `tests/`, vitest.config.ts), and no step of the drill runs a Playwright
|
||||
* spec. So a spec (`*.spec.ts`) that names the feature only in its text,
|
||||
* such as `test.describe("invoice-feature", ...)`, is residue: its text is
|
||||
* searched for the ID or folder name as written, case-sensitive, with no
|
||||
* identifier character (`[A-Za-z0-9_-]`) on either side. A longer name
|
||||
* that contains it (`generate-product-feature-index.ts` for
|
||||
* `product-feature`, `KO_MESSAGES` for `messages`) does not count. A spec
|
||||
* that names only the feature's routes or URLs is not found; 03's hand list
|
||||
* removes the feature's specs.
|
||||
* Diff review DR-02: only a name with a hyphen is searched. A one-word ID
|
||||
* or folder (`status`, `reports`, `messages`) is an ordinary word in the
|
||||
* template's own specs (`status: 200`, `getByRole("status")`, "reports" in
|
||||
* a test title), and no text rule tells that from a reference, so a spec
|
||||
* that names only a one-word ID is not found either.
|
||||
*
|
||||
* The reference sample keeps its own, wider pattern in
|
||||
* scripts/test-sample-removal.ts: the template owns all of its files.
|
||||
@@ -48,6 +63,14 @@ export async function productFeatureResidue(
|
||||
String.raw`(?:\bfrom\s*|\bimport\s*\(\s*|\bimport\s+|\bmock\s*\(\s*)["'][^"'\n]*/features/(?:${names})/`,
|
||||
"u",
|
||||
);
|
||||
const specNames = [...new Set([featureId, directory])]
|
||||
.filter((name) => name.includes("-"))
|
||||
.map(escapeRegExp);
|
||||
const wholeName =
|
||||
specNames.length === 0
|
||||
? null
|
||||
: new RegExp(`(?<![A-Za-z0-9_-])(?:${specNames.join("|")})(?![A-Za-z0-9_-])`, "u");
|
||||
const playwrightSpec = /\.spec\.[cm]?[jt]sx?$/u;
|
||||
const residue: string[] = [];
|
||||
const relative = (file: string) => path.relative(root, file).split(path.sep).join("/");
|
||||
for (const file of await filesUnder(path.join(root, "src"))) {
|
||||
@@ -56,7 +79,14 @@ export async function productFeatureResidue(
|
||||
}
|
||||
for (const file of await filesUnder(path.join(root, "tests"))) {
|
||||
const name = relative(file);
|
||||
if (named.test(name) || imported.test(await readFile(file, "utf8"))) residue.push(name);
|
||||
const text = await readFile(file, "utf8");
|
||||
if (
|
||||
named.test(name) ||
|
||||
imported.test(text) ||
|
||||
(wholeName !== null && playwrightSpec.test(name) && wholeName.test(text))
|
||||
) {
|
||||
residue.push(name);
|
||||
}
|
||||
}
|
||||
return residue.sort();
|
||||
}
|
||||
|
||||
@@ -125,6 +125,12 @@ export function releaseIdentity(manifest: string | null): ReleaseIdentity | null
|
||||
*
|
||||
* 1103/13-02. The host must negotiate a declared protocol (HTTP/2): the
|
||||
* template splits its initial chunks on that premise.
|
||||
*
|
||||
* 1106/06-01. The worker script alone must also answer without any redirect.
|
||||
* Browsers fetch it with redirect mode "error" (the Service Worker Update
|
||||
* algorithm), so a same-origin redirect breaks registration, every update
|
||||
* check and the REMOVE_REGISTRATION kill switch, although the followed answer
|
||||
* is a 200 with the right headers. Pages may still follow a redirect.
|
||||
*/
|
||||
export async function probeLiveRelease(
|
||||
base: URL,
|
||||
@@ -156,6 +162,17 @@ export async function probeLiveRelease(
|
||||
passed: finalOrigin === base.origin,
|
||||
},
|
||||
);
|
||||
if (surface === "serviceWorker") {
|
||||
const redirected = response.redirected || response.type === "opaqueredirect";
|
||||
results.push({
|
||||
surface,
|
||||
header: "redirect",
|
||||
expected: false,
|
||||
observed: redirected,
|
||||
...(redirected ? { reason: "browsers refuse a redirected worker script" } : {}),
|
||||
passed: !redirected,
|
||||
});
|
||||
}
|
||||
responses[surface] = Object.fromEntries(
|
||||
[...response.headers.entries()].map(([name, value]) => [name.toLowerCase(), value]),
|
||||
);
|
||||
|
||||
@@ -66,13 +66,19 @@ export const REMOVAL_FIXTURE_DOCUMENT_TARGETS = Object.freeze([
|
||||
* CHANGELOG.md, whatever the removal did. prepareRemovalFixture deletes them
|
||||
* from such a fixture, and the repository's own test:unit keeps running them.
|
||||
* This is the only list; the sample drill used to keep the exclusion to itself.
|
||||
*
|
||||
* 1106/12-01. The unit is a file, so every test in a listed file reads the
|
||||
* documents. A test that reads none goes in another file: listing a file for
|
||||
* one document test took the file's other tests out of those drills too.
|
||||
*/
|
||||
export const REMOVAL_FIXTURE_DOCUMENT_TESTS = Object.freeze([
|
||||
"tests/unit/changelog-review-ids.test.ts",
|
||||
"tests/unit/documentation-readiness.test.ts",
|
||||
// 1105/03-01. Reads the 6.1 table of the frontend contract document.
|
||||
"tests/unit/backend-contract-pin.test.ts",
|
||||
// 1105/16-01. Reads the 03 manual and docs/architecture/starter-experience.md.
|
||||
// 1105/03-01. Reads the 6.1 table of the frontend contract document; the
|
||||
// pin checks that read none are in backend-contract-pin.test.ts.
|
||||
"tests/unit/backend-contract-pin-document.test.ts",
|
||||
// 1105/16-01. Reads the 03 manual and docs/architecture/starter-experience.md;
|
||||
// the generator's list is checked in feature-tracked-file-rewrites.test.ts.
|
||||
"tests/unit/feature-tracked-files.test.ts",
|
||||
// 1105/14-01
|
||||
"tests/unit/template-feature-removal-documents.test.ts",
|
||||
|
||||
@@ -82,6 +82,34 @@ export function runOutputPath(
|
||||
return path.posix.join(runOutputRoot(environment), relativePath);
|
||||
}
|
||||
|
||||
/**
|
||||
* 1106/12-02. Why `step`, which reads the build where the checkout keeps it
|
||||
* (`dist/`, the build manifest and the evidence under `artifacts/`), must not
|
||||
* run in this environment; `undefined` when it may. With RUN_OUTPUT_ROOT set
|
||||
* the build writes under that folder, so such a step would judge whatever
|
||||
* build the checkout still holds: check:bundle passed an over-budget build
|
||||
* that way, on the earlier one. `.` is the checkout itself, which is what a
|
||||
* Playwright config hands its web server without a run ID.
|
||||
*/
|
||||
export function checkoutBuildReadFailure(
|
||||
step: string,
|
||||
environment: Environment = process.env,
|
||||
): string | undefined {
|
||||
let root: string;
|
||||
try {
|
||||
root = runOutputRoot(environment);
|
||||
} catch (error) {
|
||||
return `${step}: ${error instanceof Error ? error.message : String(error)}`;
|
||||
}
|
||||
if (root === ".") return undefined;
|
||||
return (
|
||||
`${step} reads the build at this checkout's paths (dist/, artifacts/), but ` +
|
||||
`${RUN_OUTPUT_ROOT_VARIABLE}=${root} makes the build write under ${root}/, so it ` +
|
||||
`would judge an earlier build. Unset ${RUN_OUTPUT_ROOT_VARIABLE}, build again and ` +
|
||||
`run ${step} again.`
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* The port variable of each Playwright config's web server. Unset, the config
|
||||
* picks a free port; set, it uses that one (to pin a port while debugging).
|
||||
|
||||
@@ -9,7 +9,8 @@ import {
|
||||
|
||||
/**
|
||||
* 1103/13-03. Release-stage signal for known dependency advisories
|
||||
* (FE-GATE-027, next to the release admission of the candidate). It runs
|
||||
* (FE-GATE-027, before the release admission of the candidate, so a refused
|
||||
* candidate still leaves the record: 1106/13-01). It runs
|
||||
* `pnpm audit --json` over the lockfile and applies
|
||||
* config/security/vulnerability-policy.json with its exceptions, the policy the
|
||||
* production promotion provider is held to. The result is a line in the gate
|
||||
|
||||
@@ -131,9 +131,16 @@ try {
|
||||
}
|
||||
await writeFile(catalogPath, `${JSON.stringify(catalog, null, 2)}\n`);
|
||||
|
||||
await rm(path.join(fixtureRoot, "playwright.capabilities.config.ts"), {
|
||||
force: true,
|
||||
});
|
||||
// 1106/10-01. The capabilities config goes with this runtime, and so do its
|
||||
// run-isolation checks, by name: the template's test:unit runs them, this
|
||||
// copy has nothing for them to check. Without `force`, so a renamed file
|
||||
// stops the drill here instead of failing its typecheck later.
|
||||
for (const capabilityConfigFile of [
|
||||
"playwright.capabilities.config.ts",
|
||||
"tests/unit/playwright-capabilities-run-isolation.test.ts",
|
||||
]) {
|
||||
await rm(path.join(fixtureRoot, capabilityConfigFile));
|
||||
}
|
||||
await rm(
|
||||
path.join(fixtureRoot, "scripts/check-browser-file-storage-boundaries.ts"),
|
||||
{ force: true },
|
||||
|
||||
@@ -1,8 +1,12 @@
|
||||
import { mkdir } from "node:fs/promises";
|
||||
|
||||
import { ROUTE_REGISTRY } from "../src/features/installed-feature-contracts.ts";
|
||||
import { COMPOSED_CONTRACT_CONTRIBUTIONS } from "../src/features/loaded-feature-runtimes.ts";
|
||||
import { automatedA11yArtifactSchema } from "./contracts/release-artifacts.ts";
|
||||
import {
|
||||
automatedA11yReport,
|
||||
oneResourceReadRoutes,
|
||||
oneResourceRoutesCountedAsChecked,
|
||||
readA11yNotCheckedRoutes,
|
||||
} from "./lib/a11y-data-state.ts";
|
||||
import { MANUAL_A11Y_ROUTE_IDS } from "./lib/manual-a11y-evidence.ts";
|
||||
@@ -12,6 +16,22 @@ await mkdir("artifacts/tests", { recursive: true });
|
||||
// 1103/11-01. Routes the spec scanned only on their failure state are not
|
||||
// reported as passed.
|
||||
const notChecked = await readA11yNotCheckedRoutes(MANUAL_A11Y_ROUTE_IDS);
|
||||
// 1106/11-01. The records come from the spec alone. The descriptors say which
|
||||
// routes need one, so a record call the spec lost fails here instead of
|
||||
// counting a detail page as passed.
|
||||
const countedAsChecked = oneResourceRoutesCountedAsChecked(
|
||||
oneResourceReadRoutes(
|
||||
Object.values(ROUTE_REGISTRY),
|
||||
COMPOSED_CONTRACT_CONTRIBUTIONS.httpByOperationId.values(),
|
||||
),
|
||||
notChecked,
|
||||
);
|
||||
if (countedAsChecked.length > 0) {
|
||||
process.stderr.write(
|
||||
`a11y.json not written:\n${countedAsChecked.map((line) => `a11y: ${line}`).join("\n")}\n`,
|
||||
);
|
||||
process.exit(1);
|
||||
}
|
||||
await writeValidatedJsonArtifact({
|
||||
path: "artifacts/tests/a11y.json",
|
||||
schema: automatedA11yArtifactSchema,
|
||||
|
||||
@@ -719,9 +719,12 @@ export function createPublicResponseCacheAdapter(
|
||||
// under this policy) is replaced by this verified candidate with
|
||||
// an empty rollback list, rather than blocking every later
|
||||
// deployment. A transient read failure still stops activation.
|
||||
// 1106/02-01. Unless the caller asks to replace it: a body that
|
||||
// stays unreadable fails the same way, and only this writes it.
|
||||
if (
|
||||
!previousPointer.ok &&
|
||||
previousPointer.error.code !== "CORRUPT_DATA"
|
||||
previousPointer.error.code !== "CORRUPT_DATA" &&
|
||||
options.replaceUnreadablePointer !== true
|
||||
) {
|
||||
return rebaseFailure(
|
||||
previousPointer.error,
|
||||
|
||||
@@ -93,13 +93,23 @@ const ENVELOPE_INVALID: EnvelopeRead<never> = Object.freeze({ ok: false });
|
||||
/**
|
||||
* The success `data`. A missing key is the null the backend dropped.
|
||||
* 1103/03-02. A page list's `meta.page` comes with it.
|
||||
* 1106/01-01. And the backend's `meta.traceId`, when it sent one, as
|
||||
* `readFailureEnvelope` gives it, for a client that turns a well-formed
|
||||
* answer into a failure (Fileserver's 202 `REJECTED`).
|
||||
*/
|
||||
export function readSuccessEnvelope(
|
||||
value: unknown,
|
||||
): Readonly<{ ok: true; value: unknown; page?: EnvelopePage }> | Readonly<{ ok: false }> {
|
||||
):
|
||||
| Readonly<{
|
||||
ok: true;
|
||||
value: unknown;
|
||||
page?: EnvelopePage;
|
||||
traceId?: string;
|
||||
}>
|
||||
| Readonly<{ ok: false }> {
|
||||
const parsed = successEnvelopeSchema.safeParse(value);
|
||||
if (!parsed.success) return ENVELOPE_INVALID;
|
||||
const page = parsed.data.meta.page;
|
||||
const { page, traceId } = parsed.data.meta;
|
||||
return Object.freeze({
|
||||
ok: true as const,
|
||||
value: parsed.data.data,
|
||||
@@ -113,6 +123,7 @@ export function readSuccessEnvelope(
|
||||
...(typeof page.sort === "string" ? { sort: page.sort } : {}),
|
||||
}),
|
||||
}),
|
||||
...(traceId === undefined ? {} : { traceId }),
|
||||
});
|
||||
}
|
||||
|
||||
|
||||
@@ -682,9 +682,15 @@ async function readAnswer(
|
||||
// 1105/01-01. The file is the user's to replace, as with a 413, 415 or
|
||||
// 422 refusal. The backend keeps the record unpublished and schedules
|
||||
// its bytes for removal, so nothing usable was stored.
|
||||
// 1106/01-01. The server answered, so the failure carries its
|
||||
// `meta.traceId` as an Envelope failure does (1105/01-03). The answer
|
||||
// names no reason: the backend keeps the verifier's code on its record.
|
||||
return failure("VALIDATION_REJECTED", "FILE_REJECTED", {
|
||||
httpStatus: status,
|
||||
effect: "NOT_APPLIED",
|
||||
...(envelope.traceId === undefined
|
||||
? {}
|
||||
: { traceId: envelope.traceId }),
|
||||
});
|
||||
}
|
||||
return Object.freeze({
|
||||
@@ -790,6 +796,7 @@ function failure(
|
||||
details: Readonly<{
|
||||
effect: FailureEffectCertainty;
|
||||
httpStatus?: number;
|
||||
traceId?: string;
|
||||
}>,
|
||||
): Result<never, AppFailure> {
|
||||
return Object.freeze({
|
||||
|
||||
@@ -94,19 +94,30 @@ export type BoundedPollObservation = Readonly<{
|
||||
outcome?: "VALUE" | "UNCHANGED" | "TERMINAL" | RealtimeFailureKind;
|
||||
}>;
|
||||
|
||||
export type BoundedPollCoordinatorDependencies<Value> = Readonly<{
|
||||
/**
|
||||
* 1106/04-02. `Operation` is the descriptor's own type, so the executor call
|
||||
* in `execute` checks the feature's input and output types. It is inferred
|
||||
* from `operation`; a caller that writes `Value` writes both
|
||||
* (`createBoundedPollCoordinator<Value, typeof operation>`), or `Operation`
|
||||
* falls back to `BoundedPollOperation` and the executor sees `unknown`.
|
||||
*/
|
||||
export type BoundedPollCoordinatorDependencies<
|
||||
Value,
|
||||
Operation extends BoundedPollOperation = BoundedPollOperation,
|
||||
> = Readonly<{
|
||||
policy: PollLeasePolicy;
|
||||
/**
|
||||
* The V3 descriptor `execute` runs (`BoundedPollOperation`). Creation
|
||||
* refuses one whose `frontend.retryBudget` is not 0, and every `execute`
|
||||
* call receives this same object as `input.operation`.
|
||||
*/
|
||||
operation: BoundedPollOperation;
|
||||
operation: Operation;
|
||||
/**
|
||||
* Returns every outcome as a result, server and network failures included
|
||||
* (the V3 executor returns a rejected fetch as NETWORK_FAILURE). A throw,
|
||||
* like a result of the wrong shape, ends the lease with PROTOCOL_MISMATCH
|
||||
* and is not retried: it is a composition defect, not a server outage.
|
||||
* Design 9.2 maps each V3 executor outcome to a result.
|
||||
*/
|
||||
execute(input: Readonly<{
|
||||
operationId: string;
|
||||
@@ -116,7 +127,7 @@ export type BoundedPollCoordinatorDependencies<Value> = Readonly<{
|
||||
* for the same path: a descriptor with `retryBudget: 2` sends up to three
|
||||
* requests per attempt.
|
||||
*/
|
||||
operation: BoundedPollOperation;
|
||||
operation: Operation;
|
||||
attempt: number;
|
||||
/**
|
||||
* Hard response-body ceiling that must be enforced before decoding.
|
||||
@@ -142,8 +153,11 @@ const POLL_RETRY_AFTER_FAILURE_KINDS = Object.freeze([
|
||||
"PROVIDER_UNAVAILABLE",
|
||||
] as const satisfies readonly RealtimeFailureKind[]);
|
||||
|
||||
export function createBoundedPollCoordinator<Value>(
|
||||
dependencies: BoundedPollCoordinatorDependencies<Value>,
|
||||
export function createBoundedPollCoordinator<
|
||||
Value,
|
||||
Operation extends BoundedPollOperation = BoundedPollOperation,
|
||||
>(
|
||||
dependencies: BoundedPollCoordinatorDependencies<Value, Operation>,
|
||||
): BoundedPollCoordinator<Value> {
|
||||
const policy = definePollLeasePolicy(dependencies.policy);
|
||||
const operation = dependencies.operation;
|
||||
|
||||
@@ -99,9 +99,14 @@ export type RealtimeReconnectCloseClassification =
|
||||
export type RealtimeReconnectSession<
|
||||
ClosedReceipt = RealtimeReconnectOutcome<void>,
|
||||
> = Readonly<{
|
||||
/**
|
||||
* 1106/04-01. A throw or rejection reads like a lost connection:
|
||||
* PROVIDER_UNAVAILABLE on RECEIVE, `retryable: true`, retried with backoff.
|
||||
*/
|
||||
waitClosed():
|
||||
| ClosedReceipt
|
||||
| Promise<ClosedReceipt>;
|
||||
/** A throw ends the run with PROTOCOL_MISMATCH and no retry. */
|
||||
classifyClosed(
|
||||
receipt: ClosedReceipt,
|
||||
): RealtimeReconnectCloseClassification;
|
||||
@@ -164,6 +169,18 @@ export type RealtimeReconnectCoordinatorDependencies<
|
||||
> = Readonly<{
|
||||
policy: ReconnectPolicy;
|
||||
environment: RealtimeReconnectEnvironment;
|
||||
/**
|
||||
* 1106/04-01. Return every connect failure as a result. A throw or
|
||||
* rejection is read as a transport failure, not a defect: the attempt ends
|
||||
* PROVIDER_UNAVAILABLE on CONNECT, `retryable: true`, and is retried with
|
||||
* backoff, so a transport around a library that throws on a failed connect
|
||||
* still recovers. The poll coordinator reads a throwing `execute` the other
|
||||
* way (PROTOCOL_MISMATCH, no retry): the V3 executor it wraps never throws.
|
||||
* Check the transport's settings outside `attempt`, when composition builds
|
||||
* it. `createFetchSseConnection` and `createWebSocketConnection` throw a
|
||||
* TypeError on a wrong endpoint; inside `attempt` that TypeError would be
|
||||
* retried until the budget ends and look like a server outage.
|
||||
*/
|
||||
attempt(
|
||||
context: RealtimeReconnectAttemptContext,
|
||||
):
|
||||
@@ -175,7 +192,10 @@ export type RealtimeReconnectCoordinatorDependencies<
|
||||
RealtimeReconnectAttemptSuccess<ClosedReceipt>
|
||||
>
|
||||
>;
|
||||
/** Build the result with `realtimeSuccess`/`realtimeFailure`. */
|
||||
/**
|
||||
* Build the result with `realtimeSuccess`/`realtimeFailure`. A throw ends
|
||||
* the run with PROTOCOL_MISMATCH on RECOVER and no retry.
|
||||
*/
|
||||
confirmTransportBarrier(
|
||||
recovery: RealtimeCommittedRecovery,
|
||||
): RealtimeResult<void>;
|
||||
|
||||
@@ -36,7 +36,8 @@ export type PollLeasePolicy = Readonly<{
|
||||
* pass it to the executor (`createContractHttpExecutor().execute`). The
|
||||
* executor reads its retry ceiling from `frontend.retryBudget`, so a budget of
|
||||
* 0 is what makes one poll attempt one physical request; the poll coordinator
|
||||
* owns every retry between attempts.
|
||||
* owns every retry between attempts. This type is the bound: the coordinator
|
||||
* keeps the descriptor's own input and output types (1106/04-02).
|
||||
*/
|
||||
export type BoundedPollOperation = InstalledHttpContract<
|
||||
unknown,
|
||||
|
||||
@@ -45,7 +45,9 @@ export type PublicCacheInspection = Readonly<{
|
||||
* no longer accepts: lookup and cleanup stop on it and the next verified
|
||||
* activation replaces it with an empty rollback list. The candidates are
|
||||
* still listed so the operator can see what that activation and the
|
||||
* cleanup after it will keep. A transient pointer read is a failure.
|
||||
* cleanup after it will keep. A transient pointer read is a failure. One
|
||||
* that keeps failing is the case for `replaceUnreadablePointer` on
|
||||
* `activateRelease` (1106/02-01).
|
||||
*/
|
||||
activePointer: "NONE" | "READABLE" | "UNREADABLE";
|
||||
/** `null` unless `activePointer` is `READABLE`. */
|
||||
@@ -94,10 +96,23 @@ export interface PublicResponseCacheAdminPort {
|
||||
manifest: PublicCacheReleaseManifest,
|
||||
options?: Readonly<{ signal?: AbortSignal }>,
|
||||
): Promise<BrowserDataResult<PublicCacheReleaseSummary>>;
|
||||
/**
|
||||
* 1106/02-01. A pointer read that fails other than as damage stops the
|
||||
* activation, so one bad read does not lose the rollback list. A pointer
|
||||
* body that stays unreadable fails the same way every time, and lookup,
|
||||
* cleanup and inspect stop on it too; only an activation writes the
|
||||
* pointer. `replaceUnreadablePointer: true` is the caller's way back: this
|
||||
* activation then replaces a pointer it cannot read, as it always replaces
|
||||
* a damaged one, with an empty rollback list, and the next cleanup deletes
|
||||
* every other release cache.
|
||||
*/
|
||||
activateRelease(
|
||||
releaseRegistryId: string,
|
||||
manifestDigestHex: string,
|
||||
options?: Readonly<{ signal?: AbortSignal }>,
|
||||
options?: Readonly<{
|
||||
signal?: AbortSignal;
|
||||
replaceUnreadablePointer?: boolean;
|
||||
}>,
|
||||
): Promise<BrowserDataResult<PublicCacheReleaseSummary>>;
|
||||
cleanupOwned(
|
||||
request?: Readonly<{
|
||||
|
||||
@@ -71,7 +71,8 @@ export type AsyncSignals = Readonly<{
|
||||
hasMutationEffectUnknown?: boolean;
|
||||
/**
|
||||
* 0929/03-03. Whether the unknown-effect request can be sent again as the
|
||||
* same request: it carries an idempotency key.
|
||||
* same request: it carries an idempotency key, or (1106/03-03) its
|
||||
* command is IDEMPOTENT.
|
||||
*/
|
||||
isUnknownEffectResendable?: boolean;
|
||||
hasMutationConflict?: boolean;
|
||||
|
||||
@@ -242,6 +242,42 @@ export function withFailureEffect(
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* 1106/03-01 (D10 supplement). The paired backend's pre-write refusals that
|
||||
* every attempt of one request gets, code and status: binding and
|
||||
* validation of the request (400 VALIDATION_FAILED, whatever its details)
|
||||
* and a key its rule rejects (400 IDEMPOTENCY_KEY_INVALID). Both are rows of
|
||||
* the refusal table in `src/adapters/http/backend-envelope.ts`
|
||||
* (tests/unit/backend-envelope.test.ts holds them to it). Its other rows are
|
||||
* not: 422 IDEMPOTENT_REQUEST_MISMATCH comes only once the key reached the
|
||||
* server, and the 503 RATE_LIMIT_* answers come before the idempotency
|
||||
* check and change over time.
|
||||
*/
|
||||
export const REFUSALS_OF_EVERY_ATTEMPT: Readonly<Record<string, number>> =
|
||||
Object.freeze({
|
||||
VALIDATION_FAILED: 400,
|
||||
IDEMPOTENCY_KEY_INVALID: 400,
|
||||
});
|
||||
|
||||
/**
|
||||
* 1106/03-01 (D10 supplement and its second fix). A `NOT_APPLIED` refusal
|
||||
* the same request gets on every attempt: a row above, code and status
|
||||
* together. A resend of an unknown request that meets one shows the first
|
||||
* attempt was refused too, so the request is settled. Not one: a refusal
|
||||
* before the idempotency check or one that changes over time (429, 401,
|
||||
* 403, 503 RATE_LIMIT_*), a code a feature declared refused before its
|
||||
* write (it may be a rule on changing state), any other code, and
|
||||
* `NOT_STARTED`. The kind is not read: a feature's `mapProblem` sets it, and
|
||||
* it maps its own codes, or every 422, to `VALIDATION_REJECTED`.
|
||||
*/
|
||||
export function isRefusedOnEveryAttempt(failure: AppFailure): boolean {
|
||||
if (failure.effect !== "NOT_APPLIED") return false;
|
||||
return (
|
||||
Object.hasOwn(REFUSALS_OF_EVERY_ATTEMPT, failure.code) &&
|
||||
REFUSALS_OF_EVERY_ATTEMPT[failure.code] === failure.httpStatus
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Projects an untrusted validation details payload into the only validation
|
||||
* metadata allowed to cross the HTTP boundary. Backend copy and additional
|
||||
|
||||
@@ -633,7 +633,8 @@ const IDEMPOTENCY_CODE = /^IDEMPOTEN(?:T|CY)_/;
|
||||
* fileserver module. Their stage is the template's knowledge, not the
|
||||
* feature's, so no operation may declare them as refused before its write.
|
||||
* Business codes stay the feature author's to declare.
|
||||
* tests/unit/backend-contract-pin.test.ts holds this list to the 6.1 table.
|
||||
* tests/unit/backend-contract-pin-document.test.ts holds this list to the 6.1
|
||||
* table.
|
||||
*/
|
||||
export const PLATFORM_CODES_POSSIBLY_AFTER_WRITE: readonly string[] =
|
||||
Object.freeze([
|
||||
|
||||
@@ -283,7 +283,10 @@ export type MutationOperationId = string & {
|
||||
* second time: the operation id its intent names (the executor refuses an
|
||||
* intent whose id is not its descriptor's, before sending, reported as a
|
||||
* missing idempotency key) and whether the intent carries a key (a KEYED
|
||||
* command only). Spread it into the policy:
|
||||
* command only). 1106/03-03. Also whether the same request may be sent
|
||||
* again after an unknown result (`resendSafe`): KEYED (the key lets the
|
||||
* server recognise it) or IDEMPOTENT (applying it twice gives the same
|
||||
* result). Spread it into the policy:
|
||||
*
|
||||
* ...commandMutationIdentity(INVOICE_CREATE_CONTRACT),
|
||||
*
|
||||
@@ -299,7 +302,11 @@ export function commandMutationIdentity(
|
||||
retrySemantics: RetrySemantics;
|
||||
}>;
|
||||
}>,
|
||||
): Readonly<{ operationId: MutationOperationId; requiresIdempotencyKey: boolean }> {
|
||||
): Readonly<{
|
||||
operationId: MutationOperationId;
|
||||
requiresIdempotencyKey: boolean;
|
||||
resendSafe: boolean;
|
||||
}> {
|
||||
const { operationId, method, retrySemantics } = command.contract;
|
||||
if (method === "GET" || method === "HEAD") {
|
||||
throw new TypeError(
|
||||
@@ -309,6 +316,7 @@ export function commandMutationIdentity(
|
||||
return Object.freeze({
|
||||
operationId: operationId as MutationOperationId,
|
||||
requiresIdempotencyKey: retrySemantics === "KEYED",
|
||||
resendSafe: retrySemantics === "KEYED" || retrySemantics === "IDEMPOTENT",
|
||||
});
|
||||
}
|
||||
|
||||
@@ -318,6 +326,13 @@ export type BoundMutation<Input, Value> = Readonly<{
|
||||
/** 1103/16-05. From `commandMutationIdentity(<OPERATION>_CONTRACT)`. */
|
||||
operationId: MutationOperationId;
|
||||
requiresIdempotencyKey: boolean;
|
||||
/**
|
||||
* 1106/03-03. From `commandMutationIdentity`: the request may be sent
|
||||
* again after an unknown result (resend, or saving the same input), as a
|
||||
* KEYED or IDEMPOTENT command may. Left out, only a request whose intent
|
||||
* carries a key may (a NEVER command never).
|
||||
*/
|
||||
resendSafe?: boolean;
|
||||
/**
|
||||
* @deprecated 1103/16-06. The mutation coordinator never reads it. Leave
|
||||
* it out; it is removed in a later release.
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
import { useCallback } from "react";
|
||||
import { useCallback, useState } from "react";
|
||||
import { Link, useNavigate } from "react-router-dom";
|
||||
|
||||
import {
|
||||
@@ -59,7 +59,30 @@ export default function ReferenceResourceFormPage() {
|
||||
// feedback says a save is running, instead of a click that does nothing.
|
||||
const otherSaveRunning =
|
||||
mutation.state.indicator === "mutation-pending" && !form.pending;
|
||||
// 1106/08-01. The result of that save belongs to the form that started
|
||||
// it, not to this one. Once it ends, the feedback points to the list,
|
||||
// which shows whether the item is there, until this form saves itself.
|
||||
const [otherSaveSeen, setOtherSaveSeen] = useState(false);
|
||||
if (!otherSaveSeen && otherSaveRunning && form.result === "idle") {
|
||||
setOtherSaveSeen(true);
|
||||
} else if (otherSaveSeen && (form.pending || form.result !== "idle")) {
|
||||
setOtherSaveSeen(false);
|
||||
}
|
||||
const guard = useDirtyNavigationGuard(form.dirty && !form.pending);
|
||||
const reloadList = (
|
||||
<p>
|
||||
<Link
|
||||
to={referenceRouteUrl("REFERENCE_RESOURCE_LIST")}
|
||||
onClick={() => {
|
||||
void invalidation
|
||||
?.invalidate([REFERENCE_RESOURCE_INVALIDATION_TOPIC])
|
||||
.catch(() => {});
|
||||
}}
|
||||
>
|
||||
{message("reference.form.reloadList")}
|
||||
</Link>
|
||||
</p>
|
||||
);
|
||||
|
||||
return (
|
||||
<Form
|
||||
@@ -168,18 +191,7 @@ export default function ReferenceResourceFormPage() {
|
||||
void form.resendUnknown(mutation.resendUnknownEffect);
|
||||
}}
|
||||
/>
|
||||
<p>
|
||||
<Link
|
||||
to={referenceRouteUrl("REFERENCE_RESOURCE_LIST")}
|
||||
onClick={() => {
|
||||
void invalidation
|
||||
?.invalidate([REFERENCE_RESOURCE_INVALIDATION_TOPIC])
|
||||
.catch(() => {});
|
||||
}}
|
||||
>
|
||||
{message("reference.form.reloadList")}
|
||||
</Link>
|
||||
</p>
|
||||
{reloadList}
|
||||
</>
|
||||
) : form.result === "success" ? (
|
||||
<p role="status">{message("reference.form.saved")}</p>
|
||||
@@ -189,6 +201,8 @@ export default function ReferenceResourceFormPage() {
|
||||
// 1105/08-04. While this form's own unknown result is being
|
||||
// checked, the result that follows is shown instead.
|
||||
<AsyncSurface state={mutation.state} />
|
||||
) : otherSaveSeen ? (
|
||||
reloadList
|
||||
) : null
|
||||
}
|
||||
aside={
|
||||
|
||||
@@ -20,6 +20,7 @@ import {
|
||||
import type { Result } from "../../../contracts/result.ts";
|
||||
import {
|
||||
createFailure,
|
||||
isRefusedOnEveryAttempt,
|
||||
normalizeUnknownFailure,
|
||||
withFailureEffect,
|
||||
type AppFailure,
|
||||
@@ -249,6 +250,7 @@ type ApplicationMutationController<Input, Value> = Readonly<{
|
||||
* key. 0929/03-03. Without a key it is not sent: the result is a
|
||||
* `NOT_STARTED` `DUPLICATE_IN_FLIGHT` failure with code
|
||||
* `UNKNOWN_EFFECT_PENDING` until the unknown request is reconciled.
|
||||
* 1106/03-03. A `resendSafe` (IDEMPOTENT) policy sends it without a key.
|
||||
*/
|
||||
submit(input: Input): Promise<ApplicationResult<Value>>;
|
||||
resolveConflict(): Promise<void>;
|
||||
@@ -264,12 +266,17 @@ type ApplicationMutationController<Input, Value> = Readonly<{
|
||||
* intent, so a keyed command carries the same `Idempotency-Key`. Resolves
|
||||
* to `null` when nothing is waiting to be resent, and (0929/03-03) when
|
||||
* that request has no key: the server could not tell a second one from a
|
||||
* new request, so it could apply twice.
|
||||
* new request, so it could apply twice. An IDEMPOTENT command
|
||||
* (`resendSafe`) is sent without one (1106/03-03). 1106/03-01. A resend
|
||||
* that ends `NOT_APPLIED` or `NOT_STARTED` resolves to that failure and
|
||||
* leaves the request unknown with its key. Success, `APPLIED_CONFIRMED`
|
||||
* and a refusal every attempt gets (`isRefusedOnEveryAttempt`) settle it.
|
||||
*/
|
||||
resendUnknownEffect(): Promise<ApplicationResult<Value> | null>;
|
||||
/**
|
||||
* 0929/03-03. `resendUnknownEffect` would send: the oldest request is
|
||||
* unknown, carries an idempotency key and is not being reconciled.
|
||||
* unknown, carries an idempotency key or comes from a `resendSafe`
|
||||
* policy (1106/03-03), and is not being reconciled.
|
||||
* `state.unknownEffectResendable` carries the same answer to `AsyncSurface`.
|
||||
*/
|
||||
canResendUnknownEffect: boolean;
|
||||
@@ -284,6 +291,11 @@ type MutationAdmission = {
|
||||
state: "ACTIVE" | "UNKNOWN" | "RECONCILING" | "SETTLED";
|
||||
readonly input: unknown;
|
||||
intent: MutationIntent | null;
|
||||
/**
|
||||
* 1106/03-03. Sending this request again cannot apply it twice: its intent
|
||||
* carries a key (KEYED) or the policy is `resendSafe` (IDEMPOTENT).
|
||||
*/
|
||||
resendable: boolean;
|
||||
/** Held while UNKNOWN so the same input keeps the same identity token. */
|
||||
identityLease: Readonly<{ release(): void }> | null;
|
||||
/** `performance.now()` before which a resend waits (see RESEND_WAIT_CEILING_MS). */
|
||||
@@ -368,6 +380,7 @@ export function useApplicationMutation<Input, Value>(
|
||||
"requiresIdempotencyKey" in options
|
||||
? options.requiresIdempotencyKey
|
||||
: false;
|
||||
const resendSafe = "resendSafe" in options && options.resendSafe === true;
|
||||
const unknownEffectChannelKey = scope
|
||||
? `bound:${scope.generation}:${scope.fingerprint}:${definitionId}:${definitionVersion}`
|
||||
: `legacy:${definitionId}:${
|
||||
@@ -570,8 +583,9 @@ export function useApplicationMutation<Input, Value>(
|
||||
// request from this one, so saving the same input again could apply it
|
||||
// twice. The unknown request is settled first (reconcileUnknownEffect),
|
||||
// never repeated; a page that calls submit outside the form meets this
|
||||
// too.
|
||||
if (replayed && replayed.intent?.idempotencyKey === undefined) {
|
||||
// too. 1106/03-03. An IDEMPOTENT command has no key but applying it
|
||||
// twice gives the same result, so it is sent (`resendable`).
|
||||
if (replayed && !replayed.resendable) {
|
||||
identityLease?.release();
|
||||
return Promise.resolve({
|
||||
ok: false,
|
||||
@@ -586,6 +600,7 @@ export function useApplicationMutation<Input, Value>(
|
||||
state: "ACTIVE",
|
||||
input,
|
||||
intent: null,
|
||||
resendable: false,
|
||||
identityLease: null,
|
||||
resendNotBefore: 0,
|
||||
scope: scope ?? null,
|
||||
@@ -605,6 +620,30 @@ export function useApplicationMutation<Input, Value>(
|
||||
notifyUnknownEffectChannel(unknownEffectChannel);
|
||||
setConflict(null);
|
||||
mutation.reset();
|
||||
const holdUnknown = (retryAfterMs: number | undefined): void => {
|
||||
admission.state = "UNKNOWN";
|
||||
admission.resendNotBefore =
|
||||
performance.now() +
|
||||
Math.min(retryAfterMs ?? 0, RESEND_WAIT_CEILING_MS);
|
||||
if (identityLease) {
|
||||
identityLease.acquire();
|
||||
admission.identityLease = identityLease;
|
||||
}
|
||||
notifyUnknownEffectChannel(unknownEffectChannel);
|
||||
};
|
||||
// 1106/03-01. A resend of an unknown request that is refused before
|
||||
// the write (429, the edge's 503 RATE_LIMIT_*) or never sent shows only
|
||||
// that this attempt did not apply; the first may have. The request
|
||||
// stays unknown with its intent, so the next save or resend carries
|
||||
// the same key, never a new one (backend http-contract.md §2). A
|
||||
// refusal every attempt of the request gets (the paired backend's 400
|
||||
// VALIDATION_FAILED and IDEMPOTENCY_KEY_INVALID) shows the first was
|
||||
// refused too, so the request is settled and the form can take a
|
||||
// corrected save (isRefusedOnEveryAttempt, D10 supplement).
|
||||
const resendLeavesUnknown = (failure: AppFailure): boolean =>
|
||||
replayed !== undefined &&
|
||||
(!scope || scope.isCurrent()) &&
|
||||
!isRefusedOnEveryAttempt(failure);
|
||||
|
||||
let runtimeExecution: RuntimeMutationExecution<Value> | undefined;
|
||||
const pending = (async (): Promise<ApplicationResult<Value>> => {
|
||||
@@ -618,6 +657,8 @@ export function useApplicationMutation<Input, Value>(
|
||||
requiresIdempotencyKey,
|
||||
});
|
||||
admission.intent = intent;
|
||||
admission.resendable =
|
||||
intent.idempotencyKey !== undefined || resendSafe;
|
||||
execution = Object.freeze({ kind: "BOUND", input, intent });
|
||||
} else {
|
||||
execution = Object.freeze({ kind: "LEGACY", input });
|
||||
@@ -666,6 +707,11 @@ export function useApplicationMutation<Input, Value>(
|
||||
switch (failure.effect) {
|
||||
case "NOT_STARTED":
|
||||
case "NOT_APPLIED":
|
||||
if (resendLeavesUnknown(failure)) {
|
||||
optimisticLayer?.markUncertain();
|
||||
holdUnknown(failure.retryAfterMs);
|
||||
break;
|
||||
}
|
||||
optimisticLayer?.rollback();
|
||||
if (failure.kind === "CONFLICT") setConflict(failure);
|
||||
settleMutationAdmission(unknownEffectChannel, admission);
|
||||
@@ -684,15 +730,7 @@ export function useApplicationMutation<Input, Value>(
|
||||
case "MAYBE_APPLIED":
|
||||
optimisticLayer?.markUncertain();
|
||||
if (!scope || scope.isCurrent()) {
|
||||
admission.state = "UNKNOWN";
|
||||
admission.resendNotBefore =
|
||||
performance.now() +
|
||||
Math.min(failure.retryAfterMs ?? 0, RESEND_WAIT_CEILING_MS);
|
||||
if (identityLease) {
|
||||
identityLease.acquire();
|
||||
admission.identityLease = identityLease;
|
||||
}
|
||||
notifyUnknownEffectChannel(unknownEffectChannel);
|
||||
holdUnknown(failure.retryAfterMs);
|
||||
} else {
|
||||
settleMutationAdmission(unknownEffectChannel, admission);
|
||||
}
|
||||
@@ -724,6 +762,11 @@ export function useApplicationMutation<Input, Value>(
|
||||
}),
|
||||
"NOT_STARTED",
|
||||
);
|
||||
if (resendLeavesUnknown(failure)) {
|
||||
admission.optimisticLayer?.markUncertain();
|
||||
holdUnknown(undefined);
|
||||
return { ok: false as const, error: failure };
|
||||
}
|
||||
settleMutationAdmission(unknownEffectChannel, admission);
|
||||
if (failure.kind === "CONFLICT") setConflict(failure);
|
||||
return { ok: false as const, error: failure };
|
||||
@@ -754,6 +797,7 @@ export function useApplicationMutation<Input, Value>(
|
||||
mutationIntentFactory,
|
||||
mutationOperationId,
|
||||
requiresIdempotencyKey,
|
||||
resendSafe,
|
||||
scope,
|
||||
unknownEffectChannel,
|
||||
],
|
||||
@@ -853,7 +897,9 @@ export function useApplicationMutation<Input, Value>(
|
||||
/**
|
||||
* D-1 / 0929/03-03. A resend repeats the unknown request with its original
|
||||
* intent. Without an idempotency key (a `NEVER` command) nothing lets the
|
||||
* server recognise the repeat, so it is not offered.
|
||||
* server recognise the repeat, so it is not offered. 1106/03-03. An
|
||||
* IDEMPOTENT command (`resendSafe`) is: applying it twice gives the same
|
||||
* result.
|
||||
*/
|
||||
function canResend(
|
||||
channel: UnknownEffectChannel,
|
||||
@@ -861,7 +907,7 @@ function canResend(
|
||||
): boolean {
|
||||
return (
|
||||
head.state === "UNKNOWN" &&
|
||||
head.intent?.idempotencyKey !== undefined &&
|
||||
head.resendable &&
|
||||
!channel.reconciliationInFlight
|
||||
);
|
||||
}
|
||||
|
||||
@@ -5,6 +5,23 @@
|
||||
--field-border: var(--color-border-strong);
|
||||
--field-border-invalid: var(--color-danger);
|
||||
--dialog-elevation: var(--elevation-dialog);
|
||||
/* 1106/08-03. The modal scrim: the content colour at this weight.
|
||||
`--dialog-backdrop` is the translucent scrim `::backdrop` paints.
|
||||
`--dialog-backdrop-on-surface` is that scrim already laid over the page
|
||||
surface, an opaque colour, for the root background under the scrollbar
|
||||
gutter while a modal is open (primitives.css). The two agree because a
|
||||
browser blends a translucent colour over another in sRGB. */
|
||||
--dialog-backdrop-weight: 55%;
|
||||
--dialog-backdrop: color-mix(
|
||||
in oklab,
|
||||
var(--color-content) var(--dialog-backdrop-weight),
|
||||
transparent
|
||||
);
|
||||
--dialog-backdrop-on-surface: color-mix(
|
||||
in srgb,
|
||||
var(--color-content) var(--dialog-backdrop-weight),
|
||||
var(--color-surface)
|
||||
);
|
||||
--navigation-active-background: color-mix(
|
||||
in oklab,
|
||||
var(--color-action) 14%,
|
||||
|
||||
@@ -10,7 +10,10 @@ import {
|
||||
} from "react";
|
||||
import { flushSync } from "react-dom";
|
||||
import type { ZodIssue, ZodType } from "../../contracts/zod.ts";
|
||||
import type { AppFailure } from "../../contracts/errors.ts";
|
||||
import {
|
||||
isRefusedOnEveryAttempt,
|
||||
type AppFailure,
|
||||
} from "../../contracts/errors.ts";
|
||||
import {
|
||||
useLocale,
|
||||
type ParameterlessMessageKey,
|
||||
@@ -230,7 +233,18 @@ export function useAppForm<
|
||||
|
||||
const settleApplied = useCallback(() => {
|
||||
const submittedValues = unknownSubmissionRef.current;
|
||||
if (!submittedValues) return;
|
||||
if (!submittedValues) {
|
||||
// 1106/08-01. After a remount the form no longer holds the submitted
|
||||
// values. The confirmed save is shown, and focus, lost with the
|
||||
// confirm button, goes to the feedback area that shows it. The values
|
||||
// on screen were never sent, so they and the dirty state stay as they
|
||||
// are (diff review of 1106/08-01).
|
||||
focusFeedbackRef.current = focusIsLost();
|
||||
setFieldErrors({} as FieldErrors<Values>);
|
||||
setFormErrors([]);
|
||||
setResult("success");
|
||||
return;
|
||||
}
|
||||
settleSuccessfulValues(submittedValues);
|
||||
}, [settleSuccessfulValues]);
|
||||
|
||||
@@ -397,7 +411,10 @@ export function useAppForm<
|
||||
* D-1. Runs a resend of the unknown submission (for example
|
||||
* `mutation.resendUnknownEffect`) through the same outcome handling as a
|
||||
* submit. The form never builds a new command here: the caller resends the
|
||||
* original request with its original key.
|
||||
* original request with its original key. 1106/03-01. A resend refused
|
||||
* before the write (429, 503 `RATE_LIMIT_*`) or never sent leaves the
|
||||
* result unknown: the form keeps the submission, so a save does not go
|
||||
* out as a new request, and asks for the same request again later.
|
||||
*/
|
||||
const resendUnknown = useCallback(
|
||||
(
|
||||
@@ -410,7 +427,15 @@ export function useAppForm<
|
||||
setPending(true);
|
||||
try {
|
||||
const outcome = await send();
|
||||
if (outcome) applyOutcome(outcome, submittedValues);
|
||||
if (outcome && resendLeftUnknown(outcome)) {
|
||||
focusFeedbackRef.current = true;
|
||||
unknownSubmissionRef.current = submittedValues;
|
||||
setFieldErrors({} as FieldErrors<Values>);
|
||||
setFormErrors(["form.resendLater"]);
|
||||
setResult("effect-unknown");
|
||||
} else if (outcome) {
|
||||
applyOutcome(outcome, submittedValues);
|
||||
}
|
||||
return outcome;
|
||||
} finally {
|
||||
setPending(false);
|
||||
@@ -486,6 +511,24 @@ function refusalFor<Values extends FormValues>(
|
||||
: undefined;
|
||||
}
|
||||
|
||||
/**
|
||||
* 1106/03-01. The resend did not reach the write: the request it repeats is
|
||||
* still unknown, and the mutation coordinator keeps its key. Signing in again
|
||||
* still comes first (D-2). A refusal every attempt gets
|
||||
* (`isRefusedOnEveryAttempt`, the coordinator's own test) settles the request
|
||||
* instead, and the form shows it as for a first save (field errors, a save
|
||||
* it takes again).
|
||||
*/
|
||||
function resendLeftUnknown(outcome: FormResult<unknown>): boolean {
|
||||
return (
|
||||
!outcome.ok &&
|
||||
(outcome.error.effect === "NOT_APPLIED" ||
|
||||
outcome.error.effect === "NOT_STARTED") &&
|
||||
outcome.error.action !== "reauth" &&
|
||||
!isRefusedOnEveryAttempt(outcome.error)
|
||||
);
|
||||
}
|
||||
|
||||
/** 1105/08-01. Nothing has focus: the focused element left the document. */
|
||||
function focusIsLost(): boolean {
|
||||
const active = document.activeElement;
|
||||
|
||||
@@ -152,6 +152,8 @@ const PLATFORM_KO_MESSAGES = {
|
||||
"form.validation.configuration": "입력 구성을 다시 확인해 주세요.",
|
||||
"form.conflict":
|
||||
"다른 변경과 충돌했습니다. 입력은 유지되었으니 최신 상태를 확인해 주세요.",
|
||||
"form.resendLater":
|
||||
"다시 보낸 요청이 처리되지 않았습니다. 잠시 뒤 같은 요청으로 다시 보내 주세요.",
|
||||
"form.reauthLosesInput":
|
||||
"다시 로그인하면 이 화면에 입력한 내용은 사라집니다. 필요하면 먼저 복사해 두세요.",
|
||||
"form.remaining": "{count}자 남음",
|
||||
@@ -356,6 +358,8 @@ const PLATFORM_EN_MESSAGES = {
|
||||
"form.validation.configuration": "Review the input configuration.",
|
||||
"form.conflict":
|
||||
"Another update conflicts with this change. Your input has been preserved.",
|
||||
"form.resendLater":
|
||||
"The request sent again was not processed. Send the same request again shortly.",
|
||||
"form.reauthLosesInput":
|
||||
"Signing in again clears what you entered on this page. Copy it first if you need it.",
|
||||
"form.remaining": "{count} characters remaining",
|
||||
|
||||
@@ -15,6 +15,10 @@
|
||||
margin: 0;
|
||||
min-width: 20rem;
|
||||
min-height: 100vh;
|
||||
/* 1106/08-03. The same colour as the root background. The page covers
|
||||
the window except the scrollbar gutter, so the root background shows
|
||||
only there, where primitives.css darkens it under an open modal. */
|
||||
background: var(--color-surface);
|
||||
}
|
||||
|
||||
/* 08-06. Korean breaks between words, not between syllables. A word too
|
||||
|
||||
@@ -414,10 +414,27 @@
|
||||
}
|
||||
|
||||
.ui-dialog::backdrop {
|
||||
background: color-mix(in oklab, var(--color-content) 55%, transparent);
|
||||
background: var(--dialog-backdrop);
|
||||
backdrop-filter: blur(2px);
|
||||
}
|
||||
|
||||
/* 1106/08-03. `scrollbar-gutter: stable` (base.css) keeps a classic
|
||||
scrollbar's strip on the right even when the page does not scroll.
|
||||
The strip shows the root's background colour: `::backdrop`, like every
|
||||
fixed box, ends at its left edge. While a modal is open the root
|
||||
background colour is the scrim over the page surface, so the scrim
|
||||
reaches the window edge. The page paints its own surface (`body`,
|
||||
base.css), so this shows only in the strip. A page that scrolls has
|
||||
its scrollbar there instead, as before.
|
||||
The first attempt (a gradient layer over the surface, matched with
|
||||
`:modal`) left the strip the surface colour in Chromium; this changes
|
||||
the colour itself and matches on `[open]`, the attribute showModal()
|
||||
sets. The Dialog primitive always opens with showModal(), so an open
|
||||
`.ui-dialog` in a browser is modal. */
|
||||
:root:has(.ui-dialog[open]) {
|
||||
background-color: var(--dialog-backdrop-on-surface);
|
||||
}
|
||||
|
||||
.ui-drawer {
|
||||
width: var(--drawer-width);
|
||||
max-width: none;
|
||||
|
||||
@@ -407,7 +407,15 @@ describe("application mutation intent admission", () => {
|
||||
|
||||
function renderKeyedCreate(
|
||||
outcomes: ApplicationResult<string>[],
|
||||
options: Readonly<{ maxIdentities?: number; keyed?: boolean }> = {},
|
||||
options: Readonly<{
|
||||
maxIdentities?: number;
|
||||
keyed?: boolean;
|
||||
resendSafe?: boolean;
|
||||
optimistic?: Readonly<{
|
||||
queryKey: readonly unknown[];
|
||||
update(previous: unknown, input: string): unknown;
|
||||
}>;
|
||||
}> = {},
|
||||
) {
|
||||
const client = queryClient();
|
||||
const intents: MutationIntent[] = [];
|
||||
@@ -435,6 +443,12 @@ describe("application mutation intent admission", () => {
|
||||
scope,
|
||||
execute,
|
||||
invalidate: [],
|
||||
...(options.resendSafe === undefined
|
||||
? {}
|
||||
: { resendSafe: options.resendSafe }),
|
||||
...(options.optimistic === undefined
|
||||
? {}
|
||||
: { optimistic: options.optimistic }),
|
||||
}),
|
||||
{ wrapper: wrapper(client) },
|
||||
);
|
||||
@@ -602,6 +616,41 @@ describe("application mutation intent admission", () => {
|
||||
expect(hook.result.current.state.unknownEffectResendable).toBe(true);
|
||||
});
|
||||
|
||||
// 1106/03-03. An IDEMPOTENT command has no key, but applying it twice
|
||||
// gives the same result: after an unknown result it is offered for
|
||||
// resend and the same input is sent again, unlike NEVER (above).
|
||||
it("resends an unknown IDEMPOTENT request and sends the same input again", async () => {
|
||||
const { hook, intents, execute } = renderKeyedCreate([unknown, unknown], {
|
||||
keyed: false,
|
||||
resendSafe: true,
|
||||
});
|
||||
await act(() => hook.result.current.submit("idempotent-input"));
|
||||
expect(hook.result.current.state.indicator).toBe("mutation-effect-unknown");
|
||||
|
||||
expect(hook.result.current.canResendUnknownEffect).toBe(true);
|
||||
expect(hook.result.current.state.unknownEffectResendable).toBe(true);
|
||||
let resent: ApplicationResult<string> | null | undefined;
|
||||
await act(async () => {
|
||||
resent = await hook.result.current.resendUnknownEffect();
|
||||
});
|
||||
expect(resent).toMatchObject({ ok: false, error: { effect: "MAYBE_APPLIED" } });
|
||||
|
||||
let again: ApplicationResult<string> | undefined;
|
||||
await act(async () => {
|
||||
again = await hook.result.current.submit("idempotent-input");
|
||||
});
|
||||
|
||||
expect(again).toEqual({ ok: true, value: "idempotent-input" });
|
||||
expect(execute).toHaveBeenCalledTimes(3);
|
||||
expect(intents[1]).toBe(intents[0]);
|
||||
expect(intents[2]).toBe(intents[0]);
|
||||
expect(intents.map((intent) => intent.idempotencyKey)).toEqual([
|
||||
undefined,
|
||||
undefined,
|
||||
undefined,
|
||||
]);
|
||||
});
|
||||
|
||||
// 백엔드 1101/02-01. The paired backend answers a same-key request while
|
||||
// the first still runs with 409 IDEMPOTENT_IN_FLIGHT and Retry-After.
|
||||
it("holds a resend until the Retry-After of the unknown answer", async () => {
|
||||
@@ -647,5 +696,249 @@ describe("application mutation intent admission", () => {
|
||||
vi.useRealTimers();
|
||||
}
|
||||
});
|
||||
|
||||
// 1106/03-01. A same-key resend refused before the write (429, the
|
||||
// edge's 503 RATE_LIMIT_*) or never sent says nothing about the first
|
||||
// request, which may have applied. It stays unknown, and the next save
|
||||
// carries its key, not a new one (review experiment 03-R1 X1-X3: keys
|
||||
// key-1, key-1, key-2).
|
||||
it.each([
|
||||
[
|
||||
"refused by the edge's 503 RATE_LIMIT_UNAVAILABLE",
|
||||
createFailure("SERVER_FAILURE", "CREATE_REPLAYED", 0, {
|
||||
code: "RATE_LIMIT_UNAVAILABLE",
|
||||
httpStatus: 503,
|
||||
effect: "NOT_APPLIED",
|
||||
}),
|
||||
],
|
||||
[
|
||||
"refused with 429",
|
||||
createFailure("RATE_LIMITED", "CREATE_REPLAYED", 0, {
|
||||
code: "RATE_LIMIT_EXCEEDED",
|
||||
httpStatus: 429,
|
||||
effect: "NOT_APPLIED",
|
||||
}),
|
||||
],
|
||||
[
|
||||
"not sent",
|
||||
createFailure("NETWORK_UNREACHABLE", "CREATE_REPLAYED", 0, {
|
||||
effect: "NOT_STARTED",
|
||||
}),
|
||||
],
|
||||
// D10 supplement: these come before the idempotency check, change
|
||||
// over time, or need the key to have reached the server already.
|
||||
[
|
||||
"refused with 401",
|
||||
createFailure("AUTH_REQUIRED", "CREATE_REPLAYED", 0, {
|
||||
httpStatus: 401,
|
||||
effect: "NOT_APPLIED",
|
||||
}),
|
||||
],
|
||||
[
|
||||
"refused with 403",
|
||||
createFailure("FORBIDDEN", "CREATE_REPLAYED", 0, {
|
||||
httpStatus: 403,
|
||||
effect: "NOT_APPLIED",
|
||||
}),
|
||||
],
|
||||
[
|
||||
"refused with 422 IDEMPOTENT_REQUEST_MISMATCH",
|
||||
createFailure("UNKNOWN_CLIENT_FAILURE", "CREATE_REPLAYED", 0, {
|
||||
code: "IDEMPOTENT_REQUEST_MISMATCH",
|
||||
httpStatus: 422,
|
||||
effect: "NOT_APPLIED",
|
||||
}),
|
||||
],
|
||||
// A code the feature declared refused before its write may be a rule
|
||||
// on changing state (a name already taken).
|
||||
[
|
||||
"refused with a code the feature declared",
|
||||
createFailure("UNKNOWN_CLIENT_FAILURE", "CREATE_REPLAYED", 0, {
|
||||
code: "WORKLOG_INVALID",
|
||||
httpStatus: 400,
|
||||
effect: "NOT_APPLIED",
|
||||
}),
|
||||
],
|
||||
// Final review FR-01. The kind is the feature's mapProblem: the
|
||||
// scaffold maps its declared code to a field error, and the reference
|
||||
// gateway maps every 422 to one, whatever the code.
|
||||
[
|
||||
"refused with a declared code the feature maps to a field error",
|
||||
createFailure("VALIDATION_REJECTED", "CREATE_REPLAYED", 0, {
|
||||
code: "WORKLOG_INVALID",
|
||||
httpStatus: 400,
|
||||
effect: "NOT_APPLIED",
|
||||
validationIssues: [{ path: "name", code: "INVALID" }],
|
||||
}),
|
||||
],
|
||||
[
|
||||
"refused with 422 IDEMPOTENT_REQUEST_MISMATCH read as a field error",
|
||||
createFailure("VALIDATION_REJECTED", "CREATE_REPLAYED", 0, {
|
||||
code: "IDEMPOTENT_REQUEST_MISMATCH",
|
||||
httpStatus: 422,
|
||||
effect: "NOT_APPLIED",
|
||||
}),
|
||||
],
|
||||
])("keeps the request unknown with its key when the resend is %s", async (_label, refusal) => {
|
||||
const { hook, intents } = renderKeyedCreate([
|
||||
unknown,
|
||||
{ ok: false, error: refusal },
|
||||
]);
|
||||
await act(() => hook.result.current.submit("same-input"));
|
||||
|
||||
let resent: ApplicationResult<string> | null | undefined;
|
||||
await act(async () => {
|
||||
resent = await hook.result.current.resendUnknownEffect();
|
||||
});
|
||||
|
||||
expect(resent).toMatchObject({
|
||||
ok: false,
|
||||
error: { kind: refusal.kind, effect: refusal.effect },
|
||||
});
|
||||
expect(hook.result.current.state.indicator).toBe(
|
||||
"mutation-effect-unknown",
|
||||
);
|
||||
expect(hook.result.current.canResendUnknownEffect).toBe(true);
|
||||
|
||||
await act(() => hook.result.current.submit("same-input"));
|
||||
|
||||
expect(intents.map((intent) => intent.idempotencyKey)).toEqual([
|
||||
"key-1",
|
||||
"key-1",
|
||||
"key-1",
|
||||
]);
|
||||
});
|
||||
|
||||
// 1106/03-01 (D10 supplement). A refusal every attempt of the request
|
||||
// gets shows the first attempt was refused too: input validation, or a
|
||||
// key the server's rule rejects. The request is settled, so the form can
|
||||
// take a corrected save, which goes out as a new request.
|
||||
it.each([
|
||||
[
|
||||
"400 VALIDATION_FAILED with its field list",
|
||||
createFailure("VALIDATION_REJECTED", "CREATE_REPLAYED", 0, {
|
||||
code: "VALIDATION_FAILED",
|
||||
httpStatus: 400,
|
||||
effect: "NOT_APPLIED",
|
||||
}),
|
||||
],
|
||||
[
|
||||
"400 VALIDATION_FAILED whose body did not parse",
|
||||
createFailure("UNKNOWN_CLIENT_FAILURE", "CREATE_REPLAYED", 0, {
|
||||
code: "VALIDATION_FAILED",
|
||||
httpStatus: 400,
|
||||
effect: "NOT_APPLIED",
|
||||
}),
|
||||
],
|
||||
[
|
||||
"400 IDEMPOTENCY_KEY_INVALID",
|
||||
createFailure("UNKNOWN_CLIENT_FAILURE", "CREATE_REPLAYED", 0, {
|
||||
code: "IDEMPOTENCY_KEY_INVALID",
|
||||
httpStatus: 400,
|
||||
effect: "NOT_APPLIED",
|
||||
}),
|
||||
],
|
||||
])("settles the request when the resend is refused with %s", async (_label, refusal) => {
|
||||
const { hook, intents } = renderKeyedCreate([
|
||||
unknown,
|
||||
{ ok: false, error: refusal },
|
||||
]);
|
||||
await act(() => hook.result.current.submit("same-input"));
|
||||
|
||||
let resent: ApplicationResult<string> | null | undefined;
|
||||
await act(async () => {
|
||||
resent = await hook.result.current.resendUnknownEffect();
|
||||
});
|
||||
|
||||
expect(resent).toMatchObject({
|
||||
ok: false,
|
||||
error: { code: refusal.code, effect: "NOT_APPLIED" },
|
||||
});
|
||||
expect(hook.result.current.state.indicator).toBeNull();
|
||||
expect(hook.result.current.canResendUnknownEffect).toBe(false);
|
||||
|
||||
await act(() => hook.result.current.submit("corrected-input"));
|
||||
|
||||
expect(intents.map((intent) => intent.idempotencyKey)).toEqual([
|
||||
"key-1",
|
||||
"key-1",
|
||||
"key-2",
|
||||
]);
|
||||
});
|
||||
|
||||
// 1106/03-01 (D10 supplement) on the IDEMPOTENT path (1106/03-03). A 404
|
||||
// the operation reads as not applied is a common answer once the first
|
||||
// attempt applied, so the request stays unknown; input validation
|
||||
// settles it.
|
||||
it.each([
|
||||
[
|
||||
"refused with 404",
|
||||
createFailure("NOT_FOUND", "CREATE_REPLAYED", 0, {
|
||||
httpStatus: 404,
|
||||
effect: "NOT_APPLIED",
|
||||
}),
|
||||
"mutation-effect-unknown",
|
||||
],
|
||||
[
|
||||
"refused with 400 VALIDATION_FAILED",
|
||||
createFailure("VALIDATION_REJECTED", "CREATE_REPLAYED", 0, {
|
||||
code: "VALIDATION_FAILED",
|
||||
httpStatus: 400,
|
||||
effect: "NOT_APPLIED",
|
||||
}),
|
||||
null,
|
||||
],
|
||||
] as const)("decides an unknown IDEMPOTENT request by its resend %s", async (_label, refusal, indicator) => {
|
||||
const { hook, execute } = renderKeyedCreate(
|
||||
[unknown, { ok: false, error: refusal }],
|
||||
{ keyed: false, resendSafe: true },
|
||||
);
|
||||
await act(() => hook.result.current.submit("idempotent-input"));
|
||||
|
||||
await act(async () => {
|
||||
await hook.result.current.resendUnknownEffect();
|
||||
});
|
||||
|
||||
expect(execute).toHaveBeenCalledTimes(2);
|
||||
expect(hook.result.current.state.indicator).toBe(indicator);
|
||||
});
|
||||
|
||||
// 1106/03-01. The same when the resend fails in the coordinator itself
|
||||
// before anything is sent (here the page's optimistic update throws).
|
||||
it("keeps the request unknown with its key when the resend fails before sending", async () => {
|
||||
let projectionBroken = false;
|
||||
const { hook, intents } = renderKeyedCreate([unknown], {
|
||||
optimistic: {
|
||||
queryKey: ["resource", "replayed-projection"],
|
||||
update: (_previous, input) => {
|
||||
if (projectionBroken) throw new Error("projection defect");
|
||||
return [input];
|
||||
},
|
||||
},
|
||||
});
|
||||
await act(() => hook.result.current.submit("same-input"));
|
||||
|
||||
projectionBroken = true;
|
||||
let resent: ApplicationResult<string> | null | undefined;
|
||||
await act(async () => {
|
||||
resent = await hook.result.current.resendUnknownEffect();
|
||||
});
|
||||
|
||||
expect(resent).toMatchObject({
|
||||
ok: false,
|
||||
error: { effect: "NOT_STARTED" },
|
||||
});
|
||||
expect(hook.result.current.state.indicator).toBe(
|
||||
"mutation-effect-unknown",
|
||||
);
|
||||
|
||||
projectionBroken = false;
|
||||
await act(() => hook.result.current.submit("same-input"));
|
||||
|
||||
expect(intents.map((intent) => intent.idempotencyKey)).toEqual([
|
||||
"key-1",
|
||||
"key-1",
|
||||
]);
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
// @vitest-environment jsdom
|
||||
|
||||
import { render, screen, waitFor } from "@testing-library/react";
|
||||
import { fireEvent, render, screen, waitFor } from "@testing-library/react";
|
||||
import userEvent from "@testing-library/user-event";
|
||||
import { useState } from "react";
|
||||
import { createMemoryRouter, RouterProvider, useNavigate } from "react-router-dom";
|
||||
@@ -889,7 +889,12 @@ describe("correcting a field after a server validation refusal", () => {
|
||||
<Button type="submit" disabled={form.pending || blocked}>
|
||||
Submit
|
||||
</Button>
|
||||
<Button onClick={() => void form.resendUnknown(mutation.resendUnknownEffect)}>
|
||||
Resend
|
||||
</Button>
|
||||
<output data-testid="result">{form.result}</output>
|
||||
<output data-testid="indicator">{mutation.state.indicator ?? "none"}</output>
|
||||
<output data-testid="form-errors">{form.formErrors.join(" ")}</output>
|
||||
</Form>
|
||||
);
|
||||
}
|
||||
@@ -1141,4 +1146,130 @@ describe("correcting a field after a server validation refusal", () => {
|
||||
expect(screen.getByRole("button", { name: "Submit" })).toBeDisabled();
|
||||
expect(fetcher).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
// 1106/03-01. The answer is lost, and the same-key resend meets the edge
|
||||
// rate limiter's 503 RATE_LIMIT_UNAVAILABLE, refused before the write. The
|
||||
// first request may still have applied: the result stays unknown, a save
|
||||
// sends nothing new, and the next resend carries the same key (review
|
||||
// experiment 03-R1 X5: keys key-1, key-1, key-2).
|
||||
it("keeps a lost create unknown when its resend is refused before the write", async () => {
|
||||
const user = userEvent.setup();
|
||||
const fetcher = vi
|
||||
.fn<typeof fetch>()
|
||||
.mockRejectedValueOnce(new TypeError("Failed to fetch"))
|
||||
.mockResolvedValueOnce(
|
||||
Response.json(
|
||||
{
|
||||
success: false,
|
||||
error: {
|
||||
code: "RATE_LIMIT_UNAVAILABLE",
|
||||
category: "TRANSIENT_DEPENDENCY",
|
||||
retryable: true,
|
||||
},
|
||||
meta,
|
||||
},
|
||||
{ status: 503 },
|
||||
),
|
||||
)
|
||||
.mockImplementation(async () =>
|
||||
Response.json({
|
||||
success: true,
|
||||
data: { id: "entity-1", name: "Saved" },
|
||||
meta,
|
||||
}),
|
||||
);
|
||||
const { container } = render(<CoordinatedForm fetcher={fetcher} />, {
|
||||
wrapper: wrapper(queryClient()),
|
||||
});
|
||||
|
||||
await user.type(screen.getByRole("textbox", { name: /Name/ }), "Saved");
|
||||
await user.click(screen.getByRole("button", { name: "Submit" }));
|
||||
await waitFor(() =>
|
||||
expect(screen.getByTestId("result")).toHaveTextContent("effect-unknown"),
|
||||
);
|
||||
await user.click(screen.getByRole("button", { name: "Resend" }));
|
||||
await waitFor(() => expect(fetcher).toHaveBeenCalledTimes(2));
|
||||
|
||||
await waitFor(() =>
|
||||
expect(screen.getByTestId("form-errors")).toHaveTextContent(
|
||||
formatMessage("ko-KR", "form.resendLater"),
|
||||
),
|
||||
);
|
||||
expect(screen.getByTestId("result")).toHaveTextContent("effect-unknown");
|
||||
expect(screen.getByTestId("indicator")).toHaveTextContent(
|
||||
"mutation-effect-unknown",
|
||||
);
|
||||
expect(screen.getByRole("button", { name: "Submit" })).toBeDisabled();
|
||||
// A save that reaches the form anyway (Enter in the field) sends nothing.
|
||||
const form = container.querySelector("form");
|
||||
if (!form) throw new Error("expected the form");
|
||||
fireEvent.submit(form);
|
||||
expect(fetcher).toHaveBeenCalledTimes(2);
|
||||
|
||||
await user.click(screen.getByRole("button", { name: "Resend" }));
|
||||
|
||||
await waitFor(() =>
|
||||
expect(screen.getByTestId("result")).toHaveTextContent("success"),
|
||||
);
|
||||
expect(sentKeys(fetcher)).toEqual(["key-1", "key-1", "key-1"]);
|
||||
});
|
||||
|
||||
// 1106/03-01 (D10 supplement). The same-key resend meets the backend's 400
|
||||
// VALIDATION_FAILED, which every attempt of that request gets: the first
|
||||
// was refused too. The form is not held: it shows the field error, and the
|
||||
// corrected value goes out as a new request. Before, the save stayed off
|
||||
// and the only ways out were a false "confirm applied" or a reload.
|
||||
it("takes a corrected save after a resend refused with 400 VALIDATION_FAILED", async () => {
|
||||
const user = userEvent.setup();
|
||||
const fetcher = vi
|
||||
.fn<typeof fetch>()
|
||||
.mockRejectedValueOnce(new TypeError("Failed to fetch"))
|
||||
.mockResolvedValueOnce(
|
||||
Response.json(
|
||||
{
|
||||
success: false,
|
||||
error: {
|
||||
code: "VALIDATION_FAILED",
|
||||
details: [{ field: "name", code: "NOT_BLANK", message: "필수 값이 없습니다." }],
|
||||
},
|
||||
meta,
|
||||
},
|
||||
{ status: 400 },
|
||||
),
|
||||
)
|
||||
.mockImplementation(async () =>
|
||||
Response.json({
|
||||
success: true,
|
||||
data: { id: "entity-1", name: "Fixed" },
|
||||
meta,
|
||||
}),
|
||||
);
|
||||
render(<CoordinatedForm fetcher={fetcher} />, {
|
||||
wrapper: wrapper(queryClient()),
|
||||
});
|
||||
const name = screen.getByRole("textbox", { name: /Name/ });
|
||||
|
||||
await user.type(name, "Rejected");
|
||||
await user.click(screen.getByRole("button", { name: "Submit" }));
|
||||
await waitFor(() =>
|
||||
expect(screen.getByTestId("result")).toHaveTextContent("effect-unknown"),
|
||||
);
|
||||
await user.click(screen.getByRole("button", { name: "Resend" }));
|
||||
|
||||
await waitFor(() =>
|
||||
expect(screen.getByTestId("result")).toHaveTextContent("validation-error"),
|
||||
);
|
||||
expect(name).toHaveAttribute("aria-invalid", "true");
|
||||
expect(screen.getByTestId("indicator")).toHaveTextContent("none");
|
||||
expect(screen.getByRole("button", { name: "Submit" })).toBeEnabled();
|
||||
|
||||
await user.clear(name);
|
||||
await user.type(name, "Fixed");
|
||||
await user.click(screen.getByRole("button", { name: "Submit" }));
|
||||
|
||||
await waitFor(() =>
|
||||
expect(screen.getByTestId("result")).toHaveTextContent("success"),
|
||||
);
|
||||
expect(sentKeys(fetcher)).toEqual(["key-1", "key-1", "key-2"]);
|
||||
});
|
||||
});
|
||||
|
||||
@@ -40,6 +40,10 @@ for (const definition of ROUTES) {
|
||||
test(`@a11y ${route} has no critical or serious axe violations`, async ({
|
||||
page,
|
||||
}) => {
|
||||
// 1106/11-01. An earlier run's record never outlives this run, even when
|
||||
// no record call below is reached. scripts/write-a11y-report.ts then
|
||||
// fails on a route the descriptors say reads one resource.
|
||||
await recordA11yDataState(definition.routeId, null);
|
||||
const heading = page.getByRole("heading", { level: 1 });
|
||||
if (definition.access === "session-required") {
|
||||
// 1103/11-01. Feature data is not this spec's subject: a list read gets
|
||||
|
||||
@@ -23,6 +23,7 @@ import { REFERENCE_FEATURE_ROUTE_CODECS } from "../../../src/features/reference-
|
||||
import type { ReferenceFeatureInput } from "../../../src/features/reference-feature/application/reference-feature-api.ts";
|
||||
import { createTestApplication } from "../../helpers/create-test-application.ts";
|
||||
import { createReferenceFeatureInstalledInput } from "../../../src/features/reference-feature/adapters/create-reference-feature-input.ts";
|
||||
import { oneResourceReadRoutes } from "../../../scripts/lib/a11y-data-state.ts";
|
||||
|
||||
describe("reference feature boundary contracts", () => {
|
||||
it("propagates uncertain command effect certainty into the application failure", async () => {
|
||||
@@ -138,6 +139,23 @@ describe("reference feature boundary contracts", () => {
|
||||
);
|
||||
});
|
||||
|
||||
// 1106/11-01. scripts/write-a11y-report.ts fails when a11y.json would count
|
||||
// these routes as passed: the accessibility spec has no generic answer for a
|
||||
// read of one resource and scans the page on its failure state only.
|
||||
it("has one detail page the a11y report expects under notChecked", () => {
|
||||
expect(
|
||||
oneResourceReadRoutes(
|
||||
Object.values(REFERENCE_FEATURE_CONTRACT.routes),
|
||||
REFERENCE_FEATURE_TEMPLATE_CONTRIBUTION.http,
|
||||
),
|
||||
).toEqual([
|
||||
{
|
||||
routeId: "REFERENCE_RESOURCE_DETAIL",
|
||||
operationIds: ["GET_REFERENCE_RESOURCE"],
|
||||
},
|
||||
]);
|
||||
});
|
||||
|
||||
it("contributes an identity-based invalidation graph and an explicit wire version", () => {
|
||||
expect(REFERENCE_FEATURE_CONTRACT.invalidation).toEqual({
|
||||
topics: [REFERENCE_RESOURCE_INVALIDATION_TOPIC],
|
||||
|
||||
@@ -412,6 +412,84 @@ describe("reference feature page states", () => {
|
||||
expect(name).toHaveValue("");
|
||||
});
|
||||
|
||||
/**
|
||||
* 1106/03-01 (D10 supplement). The form is never held for good after a
|
||||
* same-key resend. A refusal that may change (429) keeps the result
|
||||
* unknown and the confirm and resend actions on screen. So does a 422
|
||||
* (final review FR-01): this feature's gateway reads every 422 as a field
|
||||
* error whatever its code, and only the paired backend's own table codes
|
||||
* settle a resent request.
|
||||
*/
|
||||
async function resendAnUnknownCreate(resendAnswer: ReferenceResult<ReferenceResourceView>) {
|
||||
const user = userEvent.setup();
|
||||
const createResource = vi
|
||||
.fn<ReferenceFeatureInput["createResource"]>()
|
||||
.mockResolvedValueOnce({
|
||||
ok: false,
|
||||
error: createFailure("SERVER_FAILURE", "CREATE_REFERENCE_RESOURCE", 0, {
|
||||
effect: "MAYBE_APPLIED",
|
||||
}),
|
||||
})
|
||||
.mockResolvedValueOnce(resendAnswer)
|
||||
.mockResolvedValue({
|
||||
ok: true,
|
||||
value: { resourceId: "created", title: "Resent", createdAt: null },
|
||||
});
|
||||
renderReference(
|
||||
inputWith({ createResource }),
|
||||
"/examples/reference-resources/new",
|
||||
);
|
||||
const name = await screen.findByRole("textbox", { name: /새 항목 이름/ });
|
||||
await user.type(name, "Resent");
|
||||
await user.click(screen.getByRole("button", { name: "저장" }));
|
||||
await user.click(
|
||||
await screen.findByRole("button", { name: "같은 요청으로 다시 보내기" }),
|
||||
);
|
||||
await waitFor(() => expect(createResource).toHaveBeenCalledTimes(2));
|
||||
return { user, name, createResource };
|
||||
}
|
||||
|
||||
it("keeps the confirm on screen when the resend is refused for now", async () => {
|
||||
const { user } = await resendAnUnknownCreate({
|
||||
ok: false,
|
||||
error: createFailure("RATE_LIMITED", "CREATE_REFERENCE_RESOURCE", 0, {
|
||||
effect: "NOT_APPLIED",
|
||||
httpStatus: 429,
|
||||
}),
|
||||
});
|
||||
|
||||
expect(
|
||||
await screen.findByText(KO_MESSAGES["form.resendLater"]),
|
||||
).toBeVisible();
|
||||
expect(screen.getByText("변경 결과를 확인할 수 없습니다.")).toBeVisible();
|
||||
expect(screen.getByRole("button", { name: "같은 요청으로 다시 보내기" })).toBeVisible();
|
||||
await user.click(screen.getByRole("button", { name: "변경됨으로 확인" }));
|
||||
|
||||
expect(await screen.findByText("저장했습니다.")).toBeVisible();
|
||||
});
|
||||
|
||||
it("keeps the confirm on screen when the resend is refused with a 422", async () => {
|
||||
const { user, name } = await resendAnUnknownCreate({
|
||||
ok: false,
|
||||
error: createFailure("VALIDATION_REJECTED", "CREATE_REFERENCE_RESOURCE", 0, {
|
||||
code: "REFERENCE_RESOURCE_REJECTED",
|
||||
effect: "NOT_APPLIED",
|
||||
httpStatus: 422,
|
||||
validationIssues: [{ path: "name", code: "REQUIRED" }],
|
||||
}),
|
||||
});
|
||||
|
||||
expect(
|
||||
await screen.findByText(KO_MESSAGES["form.resendLater"]),
|
||||
).toBeVisible();
|
||||
expect(screen.getByText("변경 결과를 확인할 수 없습니다.")).toBeVisible();
|
||||
expect(name).not.toHaveAttribute("aria-invalid");
|
||||
expect(screen.getByRole("button", { name: "저장" })).toBeDisabled();
|
||||
await user.click(screen.getByRole("button", { name: "변경됨으로 확인" }));
|
||||
|
||||
expect(await screen.findByText("저장했습니다.")).toBeVisible();
|
||||
});
|
||||
|
||||
it.each([
|
||||
["AUTH_REQUIRED", "계속하려면 로그인이 필요합니다.", "로그인"],
|
||||
["FORBIDDEN", "이 작업을 수행할 권한이 없습니다.", "안전한 화면으로 이동"],
|
||||
@@ -644,6 +722,162 @@ describe("reference feature page states", () => {
|
||||
expect(createResource).toHaveBeenCalledTimes(2);
|
||||
});
|
||||
|
||||
/**
|
||||
* 1106/08-01. The form the user came back to did not start the save
|
||||
* still running, and holds none of its result (review probe 08-R1).
|
||||
*/
|
||||
async function leaveDuringSaveAndComeBack(
|
||||
...laterAnswers: readonly ReferenceResult<ReferenceResourceView>[]
|
||||
) {
|
||||
const user = userEvent.setup();
|
||||
let release:
|
||||
| ((result: ReferenceResult<ReferenceResourceView>) => void)
|
||||
| undefined;
|
||||
const createResource = vi
|
||||
.fn<ReferenceFeatureInput["createResource"]>()
|
||||
.mockImplementationOnce(
|
||||
() =>
|
||||
new Promise<ReferenceResult<ReferenceResourceView>>((resolve) => {
|
||||
release = resolve;
|
||||
}),
|
||||
);
|
||||
for (const answer of laterAnswers) createResource.mockResolvedValueOnce(answer);
|
||||
renderReference(
|
||||
inputWith({ createResource }),
|
||||
"/examples/reference-resources/new",
|
||||
);
|
||||
await user.type(
|
||||
await screen.findByRole("textbox", { name: /새 항목 이름/ }),
|
||||
"First item",
|
||||
);
|
||||
await user.click(screen.getByRole("button", { name: "저장" }));
|
||||
await waitFor(() => expect(createResource).toHaveBeenCalledOnce());
|
||||
await user.click(screen.getByRole("button", { name: "목록으로 돌아가기" }));
|
||||
await waitFor(() =>
|
||||
expect(window.location.pathname).toBe("/examples/reference-resources"),
|
||||
);
|
||||
window.history.pushState({}, "", "/examples/reference-resources/new");
|
||||
window.dispatchEvent(new PopStateEvent("popstate"));
|
||||
expect(await screen.findByText("변경 사항을 저장하고 있습니다.")).toBeVisible();
|
||||
return {
|
||||
user,
|
||||
createResource,
|
||||
release(result: ReferenceResult<ReferenceResourceView>) {
|
||||
release?.(result);
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
// 1106/03-01 (final review FR-01). The remounted form shows other values
|
||||
// than the save it did not start; its resend sends that save, with its
|
||||
// key. A 422 IDEMPOTENT_REQUEST_MISMATCH there says the key already
|
||||
// reached the server, so the first request may have applied: it stays
|
||||
// unknown and the confirm stays on screen.
|
||||
it("keeps a resent request unknown on a remounted form when the server answers 422 IDEMPOTENT_REQUEST_MISMATCH", async () => {
|
||||
const { user, createResource, release } = await leaveDuringSaveAndComeBack({
|
||||
ok: false,
|
||||
error: createFailure("VALIDATION_REJECTED", "CREATE_REFERENCE_RESOURCE", 0, {
|
||||
code: "IDEMPOTENT_REQUEST_MISMATCH",
|
||||
effect: "NOT_APPLIED",
|
||||
httpStatus: 422,
|
||||
}),
|
||||
});
|
||||
release({
|
||||
ok: false,
|
||||
error: createFailure("SERVER_FAILURE", "CREATE_REFERENCE_RESOURCE", 0, {
|
||||
effect: "MAYBE_APPLIED",
|
||||
}),
|
||||
});
|
||||
await screen.findByRole("button", { name: "같은 요청으로 다시 보내기" });
|
||||
await user.type(
|
||||
screen.getByRole("textbox", { name: /새 항목 이름/ }),
|
||||
"Second item",
|
||||
);
|
||||
|
||||
await user.click(
|
||||
screen.getByRole("button", { name: "같은 요청으로 다시 보내기" }),
|
||||
);
|
||||
await waitFor(() => expect(createResource).toHaveBeenCalledTimes(2));
|
||||
|
||||
expect(
|
||||
await screen.findByText(KO_MESSAGES["form.resendLater"]),
|
||||
).toBeVisible();
|
||||
expect(screen.getByText("변경 결과를 확인할 수 없습니다.")).toBeVisible();
|
||||
expect(screen.getByRole("button", { name: "변경됨으로 확인" })).toBeVisible();
|
||||
const [first, second] = createResource.mock.calls;
|
||||
expect(second?.[0]).toEqual(first?.[0]);
|
||||
expect(second?.[1]?.intent?.idempotencyKey).toBe(
|
||||
first?.[1]?.intent?.idempotencyKey,
|
||||
);
|
||||
});
|
||||
|
||||
// 1106/08-01 (A). Confirming that save from the remounted form used to
|
||||
// show nothing and drop focus to the body: the form had no submitted
|
||||
// values to settle.
|
||||
it("shows the save confirmed on a remounted form and keeps focus in its feedback", async () => {
|
||||
const { user, release } = await leaveDuringSaveAndComeBack();
|
||||
release({
|
||||
ok: false,
|
||||
error: createFailure("SERVER_FAILURE", "CREATE_REFERENCE_RESOURCE", 0, {
|
||||
effect: "MAYBE_APPLIED",
|
||||
}),
|
||||
});
|
||||
const confirm = await screen.findByRole("button", { name: "변경됨으로 확인" });
|
||||
confirm.focus();
|
||||
|
||||
await user.keyboard("{Enter}");
|
||||
|
||||
const saved = await screen.findByText("저장했습니다.");
|
||||
await waitFor(() =>
|
||||
expect(saved.closest(".page-template__feedback")).toHaveFocus(),
|
||||
);
|
||||
});
|
||||
|
||||
// 1106/08-01, diff review. What the user typed on the remounted form was
|
||||
// never sent. Confirming the earlier save shows that save and leaves the
|
||||
// new input, and its leave guard, in place.
|
||||
it("keeps what the user typed on a remounted form when confirming the earlier save", async () => {
|
||||
const { user, release } = await leaveDuringSaveAndComeBack();
|
||||
release({
|
||||
ok: false,
|
||||
error: createFailure("SERVER_FAILURE", "CREATE_REFERENCE_RESOURCE", 0, {
|
||||
effect: "MAYBE_APPLIED",
|
||||
}),
|
||||
});
|
||||
await screen.findByRole("button", { name: "변경됨으로 확인" });
|
||||
const name = screen.getByRole("textbox", { name: /새 항목 이름/ });
|
||||
await user.type(name, "Second item");
|
||||
screen.getByRole("button", { name: "변경됨으로 확인" }).focus();
|
||||
|
||||
await user.keyboard("{Enter}");
|
||||
|
||||
const saved = await screen.findByText("저장했습니다.");
|
||||
await waitFor(() =>
|
||||
expect(saved.closest(".page-template__feedback")).toHaveFocus(),
|
||||
);
|
||||
expect(name).toHaveValue("Second item");
|
||||
await user.click(screen.getByRole("button", { name: "목록으로 돌아가기" }));
|
||||
expect(
|
||||
await screen.findByRole("button", { name: "변경 버리고 이동" }),
|
||||
).toBeVisible();
|
||||
});
|
||||
|
||||
// 1106/08-01 (B). That save succeeding left the remounted form saying
|
||||
// nothing. The form cannot know its result, so it points to the list.
|
||||
it("points to the list once a save the remounted form did not start ends", async () => {
|
||||
const { release } = await leaveDuringSaveAndComeBack();
|
||||
release({
|
||||
ok: true,
|
||||
value: { resourceId: "created-1", title: "First item", createdAt: null },
|
||||
});
|
||||
|
||||
expect(
|
||||
await screen.findByRole("link", { name: "목록을 새로 불러와 확인" }),
|
||||
).toBeVisible();
|
||||
expect(screen.queryByText("변경 사항을 저장하고 있습니다.")).not.toBeInTheDocument();
|
||||
expect(screen.getByRole("button", { name: "저장" })).toBeEnabled();
|
||||
});
|
||||
|
||||
// 0929/08-04. The ids a user quotes to support reach the screens that
|
||||
// need them, and the sample status page shows no made-up reference.
|
||||
it("shows the request id of an unknown create next to its result", async () => {
|
||||
|
||||
@@ -0,0 +1,197 @@
|
||||
import { createServer, type Server } from "node:net";
|
||||
import path from "node:path";
|
||||
|
||||
import type { PlaywrightTestConfig } from "@playwright/test";
|
||||
import { describe, expect, it, vi } from "vitest";
|
||||
|
||||
/**
|
||||
* 1105/12-04. The run-isolation checks every Playwright config shares, for
|
||||
* tests/unit/playwright-run-isolation.test.ts (the four configs every project
|
||||
* has) and tests/unit/playwright-capabilities-run-isolation.test.ts (the
|
||||
* capabilities config, which goes with the browser file/storage runtime).
|
||||
*
|
||||
* 1106/10-01. Each file imports its configs by name and passes them here, so
|
||||
* no check depends on which config files a checkout happens to have.
|
||||
*/
|
||||
export type ConfigName = "e2e" | "visual" | "capabilities" | "storybook" | "dev";
|
||||
export type ConfigLoaders = Readonly<
|
||||
Partial<Record<ConfigName, () => Promise<{ default: PlaywrightTestConfig }>>>
|
||||
>;
|
||||
|
||||
const PORT_VARIABLES: Readonly<Record<ConfigName, string>> = {
|
||||
e2e: "TEST_E2E_PORT",
|
||||
visual: "TEST_VISUAL_PORT",
|
||||
capabilities: "TEST_CAPABILITIES_PORT",
|
||||
storybook: "TEST_STORYBOOK_PORT",
|
||||
dev: "TEST_DEV_PORT",
|
||||
};
|
||||
const RUN_VARIABLES = ["TEST_RUN_ID", "RUN_OUTPUT_ROOT", ...Object.values(PORT_VARIABLES)];
|
||||
const held: Server[] = [];
|
||||
|
||||
/** For afterEach: forgets the loaded configs and frees the ports `hold` took. */
|
||||
export async function releaseRuns(): Promise<void> {
|
||||
vi.resetModules();
|
||||
await Promise.all(
|
||||
held.splice(0).map((server) => new Promise<void>((resolve) => server.close(() => resolve()))),
|
||||
);
|
||||
}
|
||||
|
||||
type ConfigProcess = Readonly<{
|
||||
config: PlaywrightTestConfig;
|
||||
after: Readonly<Record<string, string | undefined>>;
|
||||
}>;
|
||||
|
||||
export type ConfigRuns = Readonly<{
|
||||
/** The config as one process sees it, and what it left in that environment. */
|
||||
loadProcess(
|
||||
name: ConfigName,
|
||||
environment?: Readonly<Record<string, string>>,
|
||||
): Promise<ConfigProcess>;
|
||||
load(name: ConfigName, environment?: Readonly<Record<string, string>>): Promise<PlaywrightTestConfig>;
|
||||
}>;
|
||||
|
||||
/** Each load evaluates the config again with the environment of one process. */
|
||||
export function configRuns(loaders: ConfigLoaders): ConfigRuns {
|
||||
async function loadProcess(
|
||||
name: ConfigName,
|
||||
environment: Readonly<Record<string, string>> = {},
|
||||
): Promise<ConfigProcess> {
|
||||
const loader = loaders[name];
|
||||
if (loader === undefined) throw new TypeError(`no loader for the ${name} config`);
|
||||
const saved = RUN_VARIABLES.map((variable) => [variable, process.env[variable]] as const);
|
||||
for (const variable of RUN_VARIABLES) delete process.env[variable];
|
||||
Object.assign(process.env, environment);
|
||||
vi.resetModules();
|
||||
try {
|
||||
const config = (await loader()).default;
|
||||
return {
|
||||
config,
|
||||
after: Object.fromEntries(RUN_VARIABLES.map((variable) => [variable, process.env[variable]])),
|
||||
};
|
||||
} finally {
|
||||
for (const [variable, value] of saved) {
|
||||
if (value === undefined) delete process.env[variable];
|
||||
else process.env[variable] = value;
|
||||
}
|
||||
}
|
||||
}
|
||||
return {
|
||||
loadProcess,
|
||||
load: async (name, environment = {}) => (await loadProcess(name, environment)).config,
|
||||
};
|
||||
}
|
||||
|
||||
export function portOf(config: PlaywrightTestConfig): number {
|
||||
return Number(new URL(String(config.use?.baseURL)).port);
|
||||
}
|
||||
|
||||
/** Listens on `port` the way the first run's server does. */
|
||||
export async function hold(port: number): Promise<void> {
|
||||
const server = createServer();
|
||||
held.push(server);
|
||||
await new Promise<void>((resolve, reject) => {
|
||||
server.once("error", reject);
|
||||
server.listen(port, "127.0.0.1", () => resolve());
|
||||
});
|
||||
}
|
||||
|
||||
function reporterOption(config: PlaywrightTestConfig, reporter: string, option: string): string {
|
||||
const reporters: readonly unknown[] = Array.isArray(config.reporter) ? config.reporter : [];
|
||||
const entry = reporters.find(
|
||||
(candidate) => Array.isArray(candidate) && candidate[0] === reporter,
|
||||
) as readonly [string, Record<string, unknown>] | undefined;
|
||||
return String(entry?.[1][option]);
|
||||
}
|
||||
|
||||
function outputs(config: PlaywrightTestConfig) {
|
||||
return {
|
||||
results: path.resolve(String(config.outputDir)),
|
||||
report: path.resolve(reporterOption(config, "html", "outputFolder")),
|
||||
junit: path.resolve(reporterOption(config, "junit", "outputFile")),
|
||||
};
|
||||
}
|
||||
|
||||
export function webServer(config: PlaywrightTestConfig) {
|
||||
const server = config.webServer;
|
||||
if (!server || Array.isArray(server)) throw new TypeError("expected one web server");
|
||||
return server;
|
||||
}
|
||||
|
||||
/** Each config's results, report and JUnit file, by its folder under artifacts/tests. */
|
||||
export function describeResultFolders(
|
||||
runs: ConfigRuns,
|
||||
folders: readonly (readonly [ConfigName, string])[],
|
||||
): void {
|
||||
describe.each(folders)("the %s config", (name, folder) => {
|
||||
const expected = (root: string) => ({
|
||||
results: path.resolve(root, `artifacts/tests/${folder}/results`),
|
||||
report: path.resolve(root, `artifacts/tests/${folder}/report`),
|
||||
junit: path.resolve(root, `artifacts/tests/${folder}/results.xml`),
|
||||
});
|
||||
|
||||
it("writes where the gates read without a run ID", async () => {
|
||||
expect(outputs(await runs.load(name as ConfigName))).toEqual(expected("."));
|
||||
});
|
||||
|
||||
it("gives each run ID its own results, report and JUnit file", async () => {
|
||||
const a = outputs(await runs.load(name as ConfigName, { TEST_RUN_ID: "a" }));
|
||||
const b = outputs(await runs.load(name as ConfigName, { TEST_RUN_ID: "b" }));
|
||||
|
||||
expect(a).toEqual(expected(".tmp/runs/a"));
|
||||
expect(b).toEqual(expected(".tmp/runs/b"));
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
/** Inside "the build a run serves": the dev servers' Vite cache. */
|
||||
export function itKeepsTheViteCacheInTheRun(runs: ConfigRuns, names: readonly ConfigName[]): void {
|
||||
it.each(names)("keeps the dev server's Vite cache in the run's folder (%s)", async (name) => {
|
||||
expect(webServer(await runs.load(name)).env?.["RUN_OUTPUT_ROOT"]).toBe(".");
|
||||
expect(webServer(await runs.load(name, { TEST_RUN_ID: "a" })).env?.["RUN_OUTPUT_ROOT"]).toBe(
|
||||
".tmp/runs/a",
|
||||
);
|
||||
});
|
||||
}
|
||||
|
||||
export function describeServerPorts(runs: ConfigRuns, names: readonly ConfigName[]): void {
|
||||
describe.each(names)("the %s server port", (name) => {
|
||||
it("is a free port the runner hands to its workers", async () => {
|
||||
const runner = await runs.loadProcess(name);
|
||||
const port = portOf(runner.config);
|
||||
const server = webServer(runner.config);
|
||||
|
||||
// Playwright evaluates the config again in each worker, which inherits
|
||||
// the runner's environment: the port is there, so baseURL agrees.
|
||||
expect(runner.after[PORT_VARIABLES[name]]).toBe(String(port));
|
||||
expect(portOf(await runs.load(name, { [PORT_VARIABLES[name]]: String(port) }))).toBe(port);
|
||||
expect(server.url).toBe(`http://127.0.0.1:${port}`);
|
||||
expect(server.command).toMatch(new RegExp(` (?:--port )?${port}(?: |$)`, "u"));
|
||||
expect(server.reuseExistingServer).toBe(false);
|
||||
});
|
||||
|
||||
it("moves for a second run while the first run's server holds its port", async () => {
|
||||
const first = portOf(await runs.load(name));
|
||||
await hold(first);
|
||||
|
||||
expect(portOf(await runs.load(name))).not.toBe(first);
|
||||
});
|
||||
|
||||
it("is the one its variable pins", async () => {
|
||||
const pinned = await runs.load(name, { [PORT_VARIABLES[name]]: "40123" });
|
||||
expect(portOf(pinned)).toBe(40123);
|
||||
expect(webServer(pinned).url).toBe("http://127.0.0.1:40123");
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
/** Inside "vite servers": the configs whose server is vite. */
|
||||
export function itExitsWhenItsPortIsTaken(runs: ConfigRuns, names: readonly ConfigName[]): void {
|
||||
it.each(names)(
|
||||
"exit instead of moving to the next port when theirs is taken (%s)",
|
||||
async (name) => {
|
||||
// Without --strictPort vite moved on, and Playwright, waiting on the
|
||||
// configured URL, tested whatever already listened there.
|
||||
expect(webServer(await runs.load(name)).command).toMatch(/ --port \d+ --strictPort(?: |$)/u);
|
||||
},
|
||||
);
|
||||
}
|
||||
@@ -214,6 +214,8 @@ describe("Fileserver multipart upload — success", () => {
|
||||
|
||||
it("reads 202 REJECTED as a refused file, not as a broken answer", async () => {
|
||||
// 1105/01-01. A verifier refused the file for a reason other than malware.
|
||||
// 1106/01-01. The server answered, so its `meta.traceId` comes with the
|
||||
// failure for support to find the upload in the server logs.
|
||||
answer({
|
||||
status: 202,
|
||||
body: successEnvelope(
|
||||
@@ -233,6 +235,7 @@ describe("Fileserver multipart upload — success", () => {
|
||||
retryable: false,
|
||||
action: "none",
|
||||
operationId: "FILESERVER_UPLOAD",
|
||||
traceId: "trace-1",
|
||||
}),
|
||||
});
|
||||
});
|
||||
|
||||
@@ -983,6 +983,64 @@ describe("KEYED resend on the backend's pre-execution refusal", () => {
|
||||
});
|
||||
});
|
||||
|
||||
// 1106/03-02. The edge rate limiter's 503 is refused before the write, so
|
||||
// an IDEMPOTENT write, which the executor may send again after dispatch, is
|
||||
// resent within its retryBudget after Retry-After (contract 6.1). The status
|
||||
// decides, so the INCOMPATIBLE answer the backend marks not retryable is
|
||||
// resent too. KEYED and NEVER are not (above).
|
||||
describe("IDEMPOTENT write on the edge's rate-limit 503", () => {
|
||||
const RENAME_CONTRACT = Object.freeze({
|
||||
contract: Object.freeze({
|
||||
...CREATE_CONTRACT.contract,
|
||||
operationId: "ENVELOPE_RENAME_ITEM",
|
||||
method: "PUT" as const,
|
||||
pathTemplate: "/api/envelope-items/item-1",
|
||||
acceptedStatuses: Object.freeze([200]),
|
||||
retrySemantics: "IDEMPOTENT" as const,
|
||||
commandRecovery: null,
|
||||
}),
|
||||
frontend: Object.freeze({
|
||||
...CREATE_CONTRACT.frontend,
|
||||
policyId: "ENVELOPE_RENAME_V1",
|
||||
retryBudget: 1 as const,
|
||||
diagnosticsOperation: "envelope.rename",
|
||||
}),
|
||||
});
|
||||
|
||||
it.each([
|
||||
["RATE_LIMIT_UNAVAILABLE", "TRANSIENT_DEPENDENCY", true],
|
||||
["RATE_LIMIT_INCOMPATIBLE", "INTERNAL", false],
|
||||
] as const)("sends the write again after 503 %s", async (code, category, retryable) => {
|
||||
const keys: (string | null)[] = [];
|
||||
server.use(
|
||||
http.put(`${BASE_URL}/api/envelope-items/item-1`, ({ request }) => {
|
||||
keys.push(request.headers.get("idempotency-key"));
|
||||
return keys.length === 1
|
||||
? HttpResponse.json(failure(code, category, retryable), {
|
||||
status: 503,
|
||||
headers: { "Retry-After": "1" },
|
||||
})
|
||||
: HttpResponse.json(success({ id: "item-1", name: "Renamed" }));
|
||||
}),
|
||||
);
|
||||
const executor = createContractHttpExecutor({
|
||||
baseUrl: BASE_URL,
|
||||
maxRetryAttempts: 2,
|
||||
attachCredentials: () => ({ kind: "READY" as const, headers: {} }),
|
||||
sleep: async () => {},
|
||||
random: () => 0,
|
||||
});
|
||||
|
||||
const outcome = await executor.execute(RENAME_CONTRACT, Object.freeze({}), {
|
||||
routeId: "ENVELOPE_ROUTE",
|
||||
scope: scope(),
|
||||
});
|
||||
|
||||
expect(outcome).toMatchObject({ kind: "SUCCESS", effect: "APPLIED_CONFIRMED" });
|
||||
expect(keys).toEqual([null, null]);
|
||||
});
|
||||
});
|
||||
|
||||
// 1103/10-02. A failure Envelope is read under the operation's own response
|
||||
// limit and media type, not only the problem ceiling. Native Responses: MSW
|
||||
// never settles a cancel() on a body it is still streaming.
|
||||
|
||||
@@ -19,13 +19,14 @@ describe("paired backend Envelope boundary", () => {
|
||||
});
|
||||
|
||||
it("reads data, and a dropped data key as null", () => {
|
||||
// 1106/01-01. With `meta.traceId`, as the failure reader gives it.
|
||||
expect(
|
||||
readSuccessEnvelope({
|
||||
success: true,
|
||||
data: [],
|
||||
meta: { requestId: "request-1", traceId: "trace-1" },
|
||||
}),
|
||||
).toEqual({ ok: true, value: [] });
|
||||
).toEqual({ ok: true, value: [], traceId: "trace-1" });
|
||||
expect(readSuccessEnvelope({ success: true, meta: {} })).toEqual({
|
||||
ok: true,
|
||||
value: null,
|
||||
|
||||
@@ -6,6 +6,7 @@ import path from "node:path";
|
||||
import { afterEach, describe, expect, it } from "vitest";
|
||||
|
||||
import { loadCiGateContract } from "../../../scripts/contracts/ci-gates.ts";
|
||||
import { DEPENDENCY_ADVISORIES_RECORD_PATH } from "../../../scripts/lib/dependency-advisories.ts";
|
||||
import { FIXTURE_PNPM_ENVIRONMENT } from "../../../scripts/lib/fixture-node-modules.ts";
|
||||
|
||||
// F-12. The temp roots have a package.json but no node_modules or lockfile.
|
||||
@@ -184,3 +185,65 @@ describe("CI-runner gate output budget", () => {
|
||||
);
|
||||
}, 20_000);
|
||||
});
|
||||
|
||||
// 1106/13-01. ci:gate stops at the first command that fails. FE-GATE-027 ran
|
||||
// the admission first, so a refused candidate left no advisory record, and the
|
||||
// release evidence the operations guide points to had none. The two package
|
||||
// scripts are stand-ins: the admission refuses, the scan writes its record.
|
||||
describe("CI-runner FE-GATE-027 advisory record", () => {
|
||||
it("writes the advisory record when the release admission refuses the candidate", async () => {
|
||||
const root = await mkdtemp(path.join(tmpdir(), "ci-gate-refused-admission-"));
|
||||
temporaryRoots.push(root);
|
||||
await mkdir(path.join(root, "config/ci"), { recursive: true });
|
||||
await mkdir(path.join(root, path.dirname(DEPENDENCY_ADVISORIES_RECORD_PATH)), {
|
||||
recursive: true,
|
||||
});
|
||||
const contract = JSON.parse(
|
||||
JSON.stringify(await loadCiGateContract(process.cwd())),
|
||||
) as Record<string, any>;
|
||||
const gate = contract.gates.find(
|
||||
(entry: Record<string, any>) => entry.id === "FE-GATE-027",
|
||||
);
|
||||
const logArtifact = contract.artifacts.find(
|
||||
(entry: Record<string, any>) => entry.id === gate.logArtifactId,
|
||||
);
|
||||
const packageDocument = JSON.parse(
|
||||
await readFile("package.json", "utf8"),
|
||||
) as { scripts: Record<string, string> };
|
||||
packageDocument.scripts["check:release-admission"] =
|
||||
`node -e "process.stderr.write('release admission refused for production: fixture'),process.exit(1)"`;
|
||||
packageDocument.scripts["scan:dependency-advisories"] =
|
||||
`node -e 'require("node:fs").writeFileSync(${JSON.stringify(DEPENDENCY_ADVISORIES_RECORD_PATH)}, "fixture record")'`;
|
||||
await writeFile(
|
||||
path.join(root, "config/ci/gates.json"),
|
||||
`${JSON.stringify(contract)}\n`,
|
||||
);
|
||||
await writeFile(
|
||||
path.join(root, "config/ci/contract-baseline.json"),
|
||||
await readFile("config/ci/contract-baseline.json"),
|
||||
);
|
||||
await writeFile(
|
||||
path.join(root, "package.json"),
|
||||
`${JSON.stringify(packageDocument)}\n`,
|
||||
);
|
||||
|
||||
const result = spawnSync(
|
||||
process.execPath,
|
||||
[path.resolve("scripts/run-ci-gate.ts"), "FE-GATE-027"],
|
||||
{
|
||||
cwd: root,
|
||||
encoding: "utf8",
|
||||
env: { ...process.env, ...FIXTURE_PNPM_ENVIRONMENT, CI: "false" },
|
||||
timeout: 15_000,
|
||||
},
|
||||
);
|
||||
|
||||
expect(result.status, result.stderr).toBe(1);
|
||||
expect(
|
||||
await readFile(path.join(root, logArtifact.path), "utf8"),
|
||||
).toContain("release admission refused for production: fixture");
|
||||
expect(
|
||||
await readFile(path.join(root, DEPENDENCY_ADVISORIES_RECORD_PATH), "utf8"),
|
||||
).toBe("fixture record");
|
||||
}, 20_000);
|
||||
});
|
||||
|
||||
@@ -50,7 +50,12 @@ describe("accessibility e2e API answers", () => {
|
||||
expect(answer.kind).toBe("empty-list");
|
||||
if (answer.kind !== "empty-list") return;
|
||||
// What the executor reads out of the frame is what the operation accepts.
|
||||
expect(readSuccessEnvelope(answer.body)).toEqual({ ok: true, value: [] });
|
||||
// 1106/01-01. The reader also gives the scenario meta's `traceId`.
|
||||
expect(readSuccessEnvelope(answer.body)).toEqual({
|
||||
ok: true,
|
||||
value: [],
|
||||
traceId: "0af7651916cd43dd8448eb211c80319c",
|
||||
});
|
||||
expect(LIST!.contract.outputValidator.safeParse([]).success).toBe(true);
|
||||
});
|
||||
|
||||
|
||||
@@ -7,6 +7,8 @@ import { afterEach, describe, expect, it } from "vitest";
|
||||
import { automatedA11yArtifactSchema } from "../../scripts/contracts/release-artifacts.ts";
|
||||
import {
|
||||
automatedA11yReport,
|
||||
oneResourceReadRoutes,
|
||||
oneResourceRoutesCountedAsChecked,
|
||||
readA11yNotCheckedRoutes,
|
||||
recordA11yDataState,
|
||||
} from "../../scripts/lib/a11y-data-state.ts";
|
||||
@@ -99,3 +101,97 @@ describe("automated accessibility report", () => {
|
||||
).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
/**
|
||||
* 1106/11-01. Which routes need a failure-state record comes from the
|
||||
* descriptors, not from the spec that writes the records. Review 11-R2 passed
|
||||
* `null` for the detail page's record and every check passed.
|
||||
*/
|
||||
describe("routes the accessibility spec can scan only on their failure state", () => {
|
||||
const read = (
|
||||
operationId: string,
|
||||
method: string,
|
||||
pathTemplate: string,
|
||||
inputSchemaId: string,
|
||||
acceptsEmptyList: boolean,
|
||||
) => ({
|
||||
contract: {
|
||||
operationId,
|
||||
method,
|
||||
pathTemplate,
|
||||
inputValidator: { schemaId: inputSchemaId },
|
||||
outputValidator: {
|
||||
safeParse: (value: unknown) => ({
|
||||
success: acceptsEmptyList && Array.isArray(value),
|
||||
}),
|
||||
},
|
||||
},
|
||||
});
|
||||
const route = (
|
||||
routeId: string,
|
||||
access: string,
|
||||
paramsSchema: string | null,
|
||||
) => ({ routeId, access, paramsSchema });
|
||||
|
||||
it("finds a protected route whose params are the input of a read of one resource", () => {
|
||||
expect(
|
||||
oneResourceReadRoutes(
|
||||
[
|
||||
route("THING_LIST", "session-required", null),
|
||||
route("THING_DETAIL", "session-required", "ThingParams"),
|
||||
route("THING_PARTS", "session-required", "ThingPartsParams"),
|
||||
route("THING_EDIT", "session-required", "ThingEditParams"),
|
||||
route("PUBLIC_THING", "public", "ThingParams"),
|
||||
],
|
||||
[
|
||||
read("LIST_THINGS", "GET", "/api/things", "ThingListQuery", true),
|
||||
read("GET_THING", "GET", "/api/things/{thingId}", "ThingParams", false),
|
||||
// A list under a path parameter gets the empty list.
|
||||
read("LIST_THING_PARTS", "GET", "/api/things/{thingId}/parts", "ThingPartsParams", true),
|
||||
// Not a read.
|
||||
read("DELETE_THING", "DELETE", "/api/things/{thingId}", "ThingEditParams", false),
|
||||
],
|
||||
),
|
||||
).toEqual([{ routeId: "THING_DETAIL", operationIds: ["GET_THING"] }]);
|
||||
});
|
||||
|
||||
it("refuses records that count such a route as checked", async () => {
|
||||
const directory = await recordDirectory();
|
||||
const expected = [
|
||||
{ routeId: FAILURE_STATE_ROUTE, operationIds: ["TEST_GET_ENTITY"] },
|
||||
];
|
||||
|
||||
// 11-R2: the spec recorded the route as scanned in its own state.
|
||||
await recordA11yDataState(FAILURE_STATE_ROUTE, null, directory);
|
||||
expect(
|
||||
oneResourceRoutesCountedAsChecked(
|
||||
expected,
|
||||
await readA11yNotCheckedRoutes(ROUTES, directory),
|
||||
),
|
||||
).toEqual([
|
||||
expect.stringContaining(
|
||||
`${FAILURE_STATE_ROUTE} reads one resource (TEST_GET_ENTITY) but has no failure-state record`,
|
||||
),
|
||||
]);
|
||||
|
||||
await recordA11yDataState(FAILURE_STATE_ROUTE, REASON, directory);
|
||||
expect(
|
||||
oneResourceRoutesCountedAsChecked(
|
||||
expected,
|
||||
await readA11yNotCheckedRoutes(ROUTES, directory),
|
||||
),
|
||||
).toEqual([]);
|
||||
});
|
||||
|
||||
it("does not refuse a record for a route the descriptors do not name", async () => {
|
||||
const directory = await recordDirectory();
|
||||
await recordA11yDataState(FAILURE_STATE_ROUTE, REASON, directory);
|
||||
|
||||
expect(
|
||||
oneResourceRoutesCountedAsChecked(
|
||||
[],
|
||||
await readA11yNotCheckedRoutes(ROUTES, directory),
|
||||
),
|
||||
).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
@@ -0,0 +1,67 @@
|
||||
import { readFileSync } from "node:fs";
|
||||
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { z } from "zod";
|
||||
|
||||
import { PLATFORM_CODES_POSSIBLY_AFTER_WRITE } from "../../src/contracts/external-contract-runtime.ts";
|
||||
|
||||
/**
|
||||
* 1106/12-01. The one paired-backend pin check that reads a document. It has
|
||||
* its own file because the removal drills that copy no documents leave whole
|
||||
* files out (REMOVAL_FIXTURE_DOCUMENT_TESTS in scripts/lib/removal-fixture.ts):
|
||||
* in tests/unit/backend-contract-pin.test.ts it took that file's fourteen
|
||||
* checks of config and code out of those drills with it. The pin names the
|
||||
* document; it is a repository document (`docs/`), which is why this file is
|
||||
* on that list.
|
||||
*/
|
||||
const pin = z
|
||||
.object({
|
||||
frontend: z.object({ contractDocument: z.string().startsWith("docs/") }),
|
||||
})
|
||||
.parse(JSON.parse(readFileSync("config/contracts/backend-contract-pin.json", "utf8")));
|
||||
|
||||
/**
|
||||
* 1105/03-01. The codes of the contract 6.1 table rows whose stage is "쓰기 뒤
|
||||
* 가능" (possibly after the write), read from the document the pin names.
|
||||
*/
|
||||
function codesPossiblyAfterWrite(): ReadonlySet<string> {
|
||||
const text = readFileSync(pin.frontend.contractDocument, "utf8");
|
||||
const section = text.split("### 6.1 ")[1]?.split(/\n#{2,3} /u)[0] ?? "";
|
||||
const codes = new Set<string>();
|
||||
for (const line of section.split("\n")) {
|
||||
const cells = line.split("|").map((cell) => cell.trim());
|
||||
if (!line.startsWith("|") || cells[3] !== "쓰기 뒤 가능") continue;
|
||||
for (const [, code = ""] of (cells[1] ?? "").matchAll(/`([A-Z0-9_]+)`/gu)) {
|
||||
codes.add(code);
|
||||
}
|
||||
}
|
||||
return codes;
|
||||
}
|
||||
|
||||
/**
|
||||
* Rows of that table whose stage the endpoint decides: the reference domain's
|
||||
* codes and web-advanced's patch codes ("부르는 코드가 단계를 정한다"). A
|
||||
* feature author who checked the endpoint may declare them.
|
||||
*/
|
||||
const FEATURE_DECIDED_CODES: readonly string[] = [
|
||||
"WORKLOG_INVALID",
|
||||
"POSTER_INVALID_STATE",
|
||||
"POSTER_IMAGE_REQUIRED",
|
||||
"WORKLOG_CONFLICT",
|
||||
"POSTER_ALREADY_EXISTS",
|
||||
"POSTER_IMAGE_ALREADY_PUBLISHED",
|
||||
"PATCH_REJECTED",
|
||||
"PATCH_TEST_FAILED",
|
||||
];
|
||||
|
||||
describe("platform codes no operation may declare as refused before its write", () => {
|
||||
it("are the 6.1 table's possibly-after-write codes outside the feature-decided rows", () => {
|
||||
const table61 = codesPossiblyAfterWrite();
|
||||
for (const code of FEATURE_DECIDED_CODES) {
|
||||
expect(table61.has(code), code).toBe(true);
|
||||
}
|
||||
expect([...PLATFORM_CODES_POSSIBLY_AFTER_WRITE].sort()).toEqual(
|
||||
[...table61].filter((code) => !FEATURE_DECIDED_CODES.includes(code)).sort(),
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -13,7 +13,6 @@ import {
|
||||
maybeAppliedAnswerRows,
|
||||
refusedBeforeWriteRows,
|
||||
} from "../../src/adapters/http/backend-envelope.ts";
|
||||
import { PLATFORM_CODES_POSSIBLY_AFTER_WRITE } from "../../src/contracts/external-contract-runtime.ts";
|
||||
|
||||
/**
|
||||
* 1103/12-06. The paired backend's contract is pinned in a file a machine
|
||||
@@ -27,6 +26,10 @@ import { PLATFORM_CODES_POSSIBLY_AFTER_WRITE } from "../../src/contracts/externa
|
||||
* copied word for word at the pin (`tables.backendExcerpt`), so a mistyped
|
||||
* status or a row left out fails here without a backend checkout.
|
||||
* `check:backend-contract-drift` holds that copy to the backend document.
|
||||
*
|
||||
* 1106/12-01. This file reads config and code only, so every removal drill
|
||||
* runs it. The check of the contract 6.1 table reads a document and is in
|
||||
* tests/unit/backend-contract-pin-document.test.ts.
|
||||
*/
|
||||
const COMMIT = /^[0-9a-f]{40}$/u;
|
||||
|
||||
@@ -252,52 +255,3 @@ describe("paired backend contract pin", () => {
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
/**
|
||||
* 1105/03-01. The codes of the contract 6.1 table rows whose stage is "쓰기 뒤
|
||||
* 가능" (possibly after the write), read from the document the pin names
|
||||
* (docs/architecture/backend-api-and-server-state-contract.md). Because this
|
||||
* file reads that document, the removal drills that copy no documents leave
|
||||
* it out (REMOVAL_FIXTURE_DOCUMENT_TESTS in scripts/lib/removal-fixture.ts).
|
||||
*/
|
||||
function codesPossiblyAfterWrite(): ReadonlySet<string> {
|
||||
const text = readFileSync(pin.frontend.contractDocument, "utf8");
|
||||
const section = text.split("### 6.1 ")[1]?.split(/\n#{2,3} /u)[0] ?? "";
|
||||
const codes = new Set<string>();
|
||||
for (const line of section.split("\n")) {
|
||||
const cells = line.split("|").map((cell) => cell.trim());
|
||||
if (!line.startsWith("|") || cells[3] !== "쓰기 뒤 가능") continue;
|
||||
for (const [, code = ""] of (cells[1] ?? "").matchAll(/`([A-Z0-9_]+)`/gu)) {
|
||||
codes.add(code);
|
||||
}
|
||||
}
|
||||
return codes;
|
||||
}
|
||||
|
||||
/**
|
||||
* Rows of that table whose stage the endpoint decides: the reference domain's
|
||||
* codes and web-advanced's patch codes ("부르는 코드가 단계를 정한다"). A
|
||||
* feature author who checked the endpoint may declare them.
|
||||
*/
|
||||
const FEATURE_DECIDED_CODES: readonly string[] = [
|
||||
"WORKLOG_INVALID",
|
||||
"POSTER_INVALID_STATE",
|
||||
"POSTER_IMAGE_REQUIRED",
|
||||
"WORKLOG_CONFLICT",
|
||||
"POSTER_ALREADY_EXISTS",
|
||||
"POSTER_IMAGE_ALREADY_PUBLISHED",
|
||||
"PATCH_REJECTED",
|
||||
"PATCH_TEST_FAILED",
|
||||
];
|
||||
|
||||
describe("platform codes no operation may declare as refused before its write", () => {
|
||||
it("are the 6.1 table's possibly-after-write codes outside the feature-decided rows", () => {
|
||||
const table61 = codesPossiblyAfterWrite();
|
||||
for (const code of FEATURE_DECIDED_CODES) {
|
||||
expect(table61.has(code), code).toBe(true);
|
||||
}
|
||||
expect([...PLATFORM_CODES_POSSIBLY_AFTER_WRITE].sort()).toEqual(
|
||||
[...table61].filter((code) => !FEATURE_DECIDED_CODES.includes(code)).sort(),
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
@@ -5,7 +5,13 @@ import {
|
||||
envelopeFailureReading,
|
||||
idempotencyRefusalReason,
|
||||
invitesKeyedResend,
|
||||
refusedBeforeWriteRows,
|
||||
} from "../../src/adapters/http/backend-envelope.ts";
|
||||
import {
|
||||
createFailure,
|
||||
isRefusedOnEveryAttempt,
|
||||
REFUSALS_OF_EVERY_ATTEMPT,
|
||||
} from "../../src/contracts/errors.ts";
|
||||
|
||||
/**
|
||||
* 1103/10-02. The backend's refusal table, read status by status. The
|
||||
@@ -175,3 +181,52 @@ describe("backend Envelope failure table", () => {
|
||||
},
|
||||
);
|
||||
});
|
||||
|
||||
/**
|
||||
* 1106/03-01 (D10 supplement). The refusals every attempt of one request
|
||||
* gets (`REFUSALS_OF_EVERY_ATTEMPT`, which the mutation coordinator and the
|
||||
* form read) are rows of this table. Every other row is sorted to the other
|
||||
* side here, so a new row fails this test until someone decides it.
|
||||
*/
|
||||
describe("refusals every attempt of a request gets", () => {
|
||||
it("are rows of the refusal table, code and status", () => {
|
||||
for (const [code, status] of Object.entries(REFUSALS_OF_EVERY_ATTEMPT)) {
|
||||
expect(refusedBeforeWriteRows()).toContainEqual({ code, status });
|
||||
}
|
||||
});
|
||||
|
||||
it("leave the table's other rows to keep a resent request unknown", () => {
|
||||
expect(
|
||||
refusedBeforeWriteRows()
|
||||
.filter(({ code }) => !Object.hasOwn(REFUSALS_OF_EVERY_ATTEMPT, code))
|
||||
.map(({ code }) => code),
|
||||
).toEqual([
|
||||
"IDEMPOTENT_REQUEST_MISMATCH",
|
||||
"RATE_LIMIT_UNAVAILABLE",
|
||||
"RATE_LIMIT_INCOMPATIBLE",
|
||||
]);
|
||||
});
|
||||
|
||||
// The failure the binding builds from each answer: kind from
|
||||
// envelopeFailureReading, effect from envelopeFailureEffect.
|
||||
it.each([
|
||||
["400 VALIDATION_FAILED with a field list", 400, "VALIDATION_FAILED", [{ field: "name", code: "NOT_BLANK" }], undefined, true],
|
||||
["400 VALIDATION_FAILED whose body did not parse", 400, "VALIDATION_FAILED", { cause: "JsonParseException" }, undefined, true],
|
||||
["400 IDEMPOTENCY_KEY_INVALID", 400, "IDEMPOTENCY_KEY_INVALID", undefined, undefined, true],
|
||||
["422 IDEMPOTENT_REQUEST_MISMATCH", 422, "IDEMPOTENT_REQUEST_MISMATCH", undefined, undefined, false],
|
||||
["503 RATE_LIMIT_UNAVAILABLE", 503, "RATE_LIMIT_UNAVAILABLE", undefined, undefined, false],
|
||||
["a code the operation declared", 400, "WORKLOG_INVALID", undefined, ["WORKLOG_INVALID"], false],
|
||||
] as const)("decides whether %s is refused on every attempt", (_label, status, code, details, declared, expected) => {
|
||||
const error = { code, ...(details === undefined ? {} : { details }) };
|
||||
const effect = envelopeFailureEffect(status, error, declared);
|
||||
expect(effect).toBe("NOT_APPLIED");
|
||||
const failure = createFailure(
|
||||
envelopeFailureReading(status, error).kind,
|
||||
"ENVELOPE_OPERATION",
|
||||
0,
|
||||
{ code, httpStatus: status, effect: "NOT_APPLIED" },
|
||||
);
|
||||
|
||||
expect(isRefusedOnEveryAttempt(failure)).toBe(expected);
|
||||
});
|
||||
});
|
||||
|
||||
@@ -24,6 +24,8 @@ async function checkBundle(
|
||||
outputs: readonly Output[];
|
||||
manifest: Record<string, unknown>;
|
||||
budgets: Record<string, number>;
|
||||
/** RUN_OUTPUT_ROOT for the run, and the build written under it. */
|
||||
runOutput?: Readonly<{ root: string; outputs: readonly Output[] }>;
|
||||
}>,
|
||||
) {
|
||||
const root = await mkdtemp(path.join(tmpdir(), "check-bundle-output-"));
|
||||
@@ -32,22 +34,28 @@ async function checkBundle(
|
||||
await mkdir(path.dirname(path.join(root, file)), { recursive: true });
|
||||
await writeFile(path.join(root, file), `${JSON.stringify(value, null, 2)}\n`);
|
||||
};
|
||||
const writeBuild = async (buildRoot: string, outputs: readonly Output[]) => {
|
||||
await write(path.posix.join(buildRoot, "dist/.vite/manifest.json"), options.manifest);
|
||||
await write(path.posix.join(buildRoot, "artifacts/performance/bundle.json"), {
|
||||
schemaVersion: 1,
|
||||
generatedAt: "2026-11-04T00:00:00.000Z",
|
||||
context: { nodeVersion: "v24.14.0", packageManager: "pnpm@11.17.0", runnerImage: "fixture" },
|
||||
outputs: outputs.map((output) => ({
|
||||
path: `dist/${output.path}`,
|
||||
bytes: output.gzipBytes * 3,
|
||||
gzipBytes: output.gzipBytes,
|
||||
sha256: "a".repeat(64),
|
||||
})),
|
||||
});
|
||||
};
|
||||
await write("config/performance/budgets.json", { schemaVersion: 1, bundle: options.budgets });
|
||||
await write("dist/.vite/manifest.json", options.manifest);
|
||||
await write("artifacts/performance/bundle.json", {
|
||||
schemaVersion: 1,
|
||||
generatedAt: "2026-11-04T00:00:00.000Z",
|
||||
context: { nodeVersion: "v24.14.0", packageManager: "pnpm@11.17.0", runnerImage: "fixture" },
|
||||
outputs: options.outputs.map((output) => ({
|
||||
path: `dist/${output.path}`,
|
||||
bytes: output.gzipBytes * 3,
|
||||
gzipBytes: output.gzipBytes,
|
||||
sha256: "a".repeat(64),
|
||||
})),
|
||||
});
|
||||
await writeBuild(".", options.outputs);
|
||||
if (options.runOutput) await writeBuild(options.runOutput.root, options.runOutput.outputs);
|
||||
const result = spawnSync(process.execPath, [path.resolve("scripts/check-bundle.ts")], {
|
||||
cwd: root,
|
||||
encoding: "utf8",
|
||||
// Empty is unset (scripts/lib/run-isolation.ts), whatever the runner has.
|
||||
env: { ...process.env, RUN_OUTPUT_ROOT: options.runOutput?.root ?? "" },
|
||||
});
|
||||
return { status: result.status, stdout: result.stdout, stderr: result.stderr };
|
||||
}
|
||||
@@ -126,3 +134,54 @@ describe("check:bundle failure output (1103/15-03)", () => {
|
||||
expect(result.stderr).not.toContain("Bundle budget failed");
|
||||
});
|
||||
});
|
||||
|
||||
/**
|
||||
* 1106/12-02. Under RUN_OUTPUT_ROOT scripts/build-frontend.ts writes the build
|
||||
* below that folder, and check:bundle (scripts/generate-supply-chain.ts, then
|
||||
* scripts/check-bundle.ts) read the checkout's dist/ and artifacts/ anyway: a
|
||||
* build over budget under .tmp/ passed on the checkout's earlier build
|
||||
* (review run 12-R2). Both stop and name the variable instead.
|
||||
*/
|
||||
describe("check:bundle with RUN_OUTPUT_ROOT (1106/12-02)", () => {
|
||||
it("does not pass the checkout's earlier build while the build writes elsewhere", async () => {
|
||||
const result = await checkBundle({
|
||||
outputs: OUTPUTS,
|
||||
manifest: MANIFEST,
|
||||
budgets: BUDGETS,
|
||||
runOutput: {
|
||||
root: ".tmp/runs/other",
|
||||
outputs: OUTPUTS.map((output) => ({ ...output, gzipBytes: output.gzipBytes * 4 })),
|
||||
},
|
||||
});
|
||||
expect(result.stdout).not.toContain("Bundle budget: PASS");
|
||||
expect(result.status).toBe(1);
|
||||
expect(result.stderr).toContain("RUN_OUTPUT_ROOT=.tmp/runs/other");
|
||||
});
|
||||
|
||||
it("measures the checkout's build when the output root is the checkout", async () => {
|
||||
const result = await checkBundle({
|
||||
outputs: OUTPUTS,
|
||||
manifest: MANIFEST,
|
||||
budgets: BUDGETS,
|
||||
runOutput: { root: ".", outputs: OUTPUTS },
|
||||
});
|
||||
expect(result.stderr).toBe("");
|
||||
expect(result.status).toBe(0);
|
||||
expect(result.stdout).toContain("initial JS 900 / 1000 gzip bytes");
|
||||
});
|
||||
|
||||
it("stops scripts/generate-supply-chain.ts before it reads the checkout's build", async () => {
|
||||
const root = await mkdtemp(path.join(tmpdir(), "generate-supply-chain-output-root-"));
|
||||
roots.push(root);
|
||||
const result = spawnSync(process.execPath, [path.resolve("scripts/generate-supply-chain.ts")], {
|
||||
cwd: root,
|
||||
encoding: "utf8",
|
||||
env: { ...process.env, RUN_OUTPUT_ROOT: ".tmp/runs/other" },
|
||||
});
|
||||
expect(result.status).toBe(1);
|
||||
expect(result.stderr).toContain(
|
||||
"scripts/generate-supply-chain.ts reads the build at this checkout's paths",
|
||||
);
|
||||
expect(result.stderr).toContain("RUN_OUTPUT_ROOT=.tmp/runs/other");
|
||||
});
|
||||
});
|
||||
|
||||
@@ -21,17 +21,28 @@ describe("commandMutationIdentity", () => {
|
||||
expect(commandMutationIdentity(TEST_CREATE_HTTP_CONTRACT)).toEqual({
|
||||
operationId: "TEST_CREATE_ENTITY",
|
||||
requiresIdempotencyKey: true,
|
||||
resendSafe: true,
|
||||
});
|
||||
});
|
||||
|
||||
it.each(["NEVER", "IDEMPOTENT"] as const)(
|
||||
"sends no key for a %s command",
|
||||
(retrySemantics) => {
|
||||
// 1106/03-03. An IDEMPOTENT command carries no key, but sending it again
|
||||
// gives the same result, so the coordinator may resend it after an
|
||||
// unknown result. A NEVER command may not.
|
||||
it.each([
|
||||
["NEVER", false],
|
||||
["IDEMPOTENT", true],
|
||||
] as const)(
|
||||
"sends no key for a %s command, resend safe: %s",
|
||||
(retrySemantics, resendSafe) => {
|
||||
expect(
|
||||
commandMutationIdentity({
|
||||
contract: { ...TEST_CREATE_HTTP_CONTRACT.contract, retrySemantics },
|
||||
}),
|
||||
).toEqual({ operationId: "TEST_CREATE_ENTITY", requiresIdempotencyKey: false });
|
||||
).toEqual({
|
||||
operationId: "TEST_CREATE_ENTITY",
|
||||
requiresIdempotencyKey: false,
|
||||
resendSafe,
|
||||
});
|
||||
},
|
||||
);
|
||||
|
||||
|
||||
@@ -299,6 +299,26 @@ describe("create:feature --with-create", () => {
|
||||
},
|
||||
);
|
||||
|
||||
// 1106/08-02. A save that ended after the user left the form took them to
|
||||
// the item anyway. The page opens the item or the list only while it is
|
||||
// still mounted, and the generated page test walks that path.
|
||||
it.each(["NEVER", "KEYED"] as const)(
|
||||
"does not open the item when the user left during a %s create",
|
||||
(write) => {
|
||||
const { files } = plan({ id: "invoice-feature", write });
|
||||
const page =
|
||||
files.get("src/features/invoice-feature/presentation/invoice-create-page.tsx") ?? "";
|
||||
|
||||
expect(page).toContain("if (outcome?.ok && mounted.current) {");
|
||||
expect(page).toContain(
|
||||
'if (mounted.current) void navigate(invoiceRouteUrl("INVOICE_LIST"));',
|
||||
);
|
||||
expect(
|
||||
files.get("tests/features/invoice-feature/invoice-create-page.test.tsx"),
|
||||
).toContain('it("stays on the list the user went to while the create was saving"');
|
||||
},
|
||||
);
|
||||
|
||||
// 1103/16-07. A backend create made KEYED (IdempotencyExecutor) takes these.
|
||||
it("writes the KEYED values for a backend create made KEYED", () => {
|
||||
const { files } = plan({ id: "invoice-feature", write: "KEYED" });
|
||||
|
||||
@@ -96,7 +96,11 @@ describe("dependency advisory summary (1103/13-03)", () => {
|
||||
}
|
||||
});
|
||||
|
||||
it("runs at release admission (FE-GATE-027) and never fails the gate by itself", async () => {
|
||||
// 1106/13-01. ci:gate stops at the first command that fails. With the scan
|
||||
// after the admission, a refused run had no advisory record, while the
|
||||
// operations guide says the release evidence carries it. The scan never
|
||||
// fails, so running it first leaves the admission verdict as it was.
|
||||
it("runs before the release admission (FE-GATE-027) and never fails the gate by itself", async () => {
|
||||
const contract = JSON.parse(await readFile("config/ci/gates.json", "utf8")) as {
|
||||
gates: { id: string; commandIds: string[] }[];
|
||||
commands: { id: string; script: string }[];
|
||||
@@ -104,7 +108,7 @@ describe("dependency advisory summary (1103/13-03)", () => {
|
||||
const scripts = (contract.gates.find(({ id }) => id === "FE-GATE-027")?.commandIds ?? []).map(
|
||||
(commandId) => contract.commands.find(({ id }) => id === commandId)?.script,
|
||||
);
|
||||
expect(scripts).toEqual(["check:release-admission", "scan:dependency-advisories"]);
|
||||
expect(scripts).toEqual(["scan:dependency-advisories", "check:release-admission"]);
|
||||
const source = await readFile("scripts/scan-dependency-advisories.ts", "utf8");
|
||||
expect(source).not.toMatch(/process\.exit(?:Code)?\s*(?:=|\()\s*[1-9]/u);
|
||||
});
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
|
||||
import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import path from "node:path";
|
||||
|
||||
@@ -59,6 +59,80 @@ describe("product feature residue (1105/16-04)", () => {
|
||||
]);
|
||||
});
|
||||
|
||||
// 1106/16-01. test:all is vitest only and the drill runs no Playwright
|
||||
// spec, so a spec that names the removed feature in its text and nowhere
|
||||
// else was caught by no step.
|
||||
it("counts a Playwright spec that names the feature only in its text", async () => {
|
||||
const spec = [
|
||||
`test.describe("${ID}", () => {`,
|
||||
' test("opens", async ({ page }) => {',
|
||||
' await page.goto("/invoice");',
|
||||
" });",
|
||||
"});",
|
||||
"",
|
||||
].join("\n");
|
||||
const root = await fixture({
|
||||
"tests/e2e/checkout.spec.ts": spec,
|
||||
"tests/visual/billing.visual.spec.ts": `const FEATURE = '${ID}';\n`,
|
||||
// The same text in a vitest test is data (1105/16-04).
|
||||
"tests/unit/checkout.test.ts": spec,
|
||||
"tests/e2e/route-only.spec.ts": 'test("opens", ({ page }) => page.goto("/invoice"));\n',
|
||||
});
|
||||
|
||||
expect(await productFeatureResidue(root, ID, ID)).toEqual([
|
||||
"tests/e2e/checkout.spec.ts",
|
||||
"tests/visual/billing.visual.spec.ts",
|
||||
]);
|
||||
});
|
||||
|
||||
it("does not count a spec whose longer names only contain the ID", async () => {
|
||||
const root = await fixture({
|
||||
"tests/e2e/builds.spec.ts": [
|
||||
'run("scripts/generate-product-feature-index.ts");',
|
||||
'const attribute = "data-product-feature";',
|
||||
'const registry = "product-features";',
|
||||
"",
|
||||
].join("\n"),
|
||||
});
|
||||
|
||||
expect(
|
||||
await productFeatureResidue(root, "product-feature", "product-feature"),
|
||||
).toEqual([]);
|
||||
});
|
||||
|
||||
// 1106/16-01 (diff review DR-02). The spec search ignored case and took
|
||||
// `_` as a boundary, so removing a feature named `messages` counted the
|
||||
// template's accessibility spec (`KO_MESSAGES`), and `status` or `reports`
|
||||
// counted a dozen template specs that use the word.
|
||||
it("does not count the template's own specs for common feature IDs", async () => {
|
||||
const specs: Record<string, string> = {};
|
||||
for (const entry of await readdir("tests", { recursive: true })) {
|
||||
const file = path.join("tests", entry).split(path.sep).join("/");
|
||||
if (/\.spec\.[cm]?[jt]sx?$/u.test(file)) specs[file] = await readFile(file, "utf8");
|
||||
}
|
||||
expect(Object.keys(specs)).toContain("tests/e2e/accessibility.spec.ts");
|
||||
// A copy of the specs alone: `src` is searched by substring (1105/16-04).
|
||||
const root = await fixture(specs);
|
||||
|
||||
for (const id of ["product-feature", "messages", "status", "reports"]) {
|
||||
expect(await productFeatureResidue(root, id, id), id).toEqual([]);
|
||||
}
|
||||
});
|
||||
|
||||
it("finds the name in a spec as written, and the folder name by the same rule", async () => {
|
||||
const root = await fixture({
|
||||
"tests/e2e/checkout.spec.ts": `test.describe("${ID}", () => {});\n`,
|
||||
"tests/e2e/documents.spec.ts": 'const FOLDER = "invoice-docs";\n',
|
||||
"tests/e2e/title-case.spec.ts": 'test.describe("Invoice-Feature", () => {});\n',
|
||||
"tests/e2e/longer-key.spec.ts": `const KEY = "${ID}_v2";\n`,
|
||||
});
|
||||
|
||||
expect(await productFeatureResidue(root, ID, "invoice-docs")).toEqual([
|
||||
"tests/e2e/checkout.spec.ts",
|
||||
"tests/e2e/documents.spec.ts",
|
||||
]);
|
||||
});
|
||||
|
||||
it("matches the folder name as well as the ID", async () => {
|
||||
const root = await fixture({
|
||||
"src/contracts/leftover.ts": 'export const DIRECTORY = "invoices";\n',
|
||||
|
||||
@@ -0,0 +1,22 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { FEATURE_TRACKED_FILE_REWRITES } from "../../scripts/create-feature.ts";
|
||||
|
||||
/**
|
||||
* 1105/16-01. The tracked template files every added feature changes, each
|
||||
* with the command that rewrites it. tests/unit/feature-tracked-files.test.ts
|
||||
* holds the documents to this list.
|
||||
*
|
||||
* 1106/12-01. This check reads no document, so it is not in that file: the
|
||||
* removal drills that copy no documents leave that file out
|
||||
* (REMOVAL_FIXTURE_DOCUMENT_TESTS in scripts/lib/removal-fixture.ts) and run
|
||||
* this one.
|
||||
*/
|
||||
describe("tracked files a feature changes (1105/16-01)", () => {
|
||||
it("lists the generator's tracked rewrites", () => {
|
||||
expect(FEATURE_TRACKED_FILE_REWRITES.map((file) => file.path)).toEqual([
|
||||
"public/release-manifest.json",
|
||||
"config/scale/feature-shape-ceilings.json",
|
||||
]);
|
||||
});
|
||||
});
|
||||
@@ -13,6 +13,11 @@ import { FEATURE_TRACKED_FILE_REWRITES } from "../../scripts/create-feature.ts";
|
||||
* had neither, and nothing said what to do when two feature branches change
|
||||
* the same `setDigest` line. The documents name each file with the command
|
||||
* that rewrites it, which is also how a merge conflict on it is resolved.
|
||||
*
|
||||
* 1106/12-01. Every test here reads a document, so the removal drills that
|
||||
* copy no documents leave this file out (REMOVAL_FIXTURE_DOCUMENT_TESTS in
|
||||
* scripts/lib/removal-fixture.ts). The generator's own list is checked in
|
||||
* tests/unit/feature-tracked-file-rewrites.test.ts, which every drill runs.
|
||||
*/
|
||||
function between(text: string, start: string, end: string): string {
|
||||
const from = text.indexOf(start);
|
||||
@@ -22,13 +27,6 @@ function between(text: string, start: string, end: string): string {
|
||||
}
|
||||
|
||||
describe("tracked files a feature changes (1105/16-01)", () => {
|
||||
it("lists the generator's tracked rewrites", () => {
|
||||
expect(FEATURE_TRACKED_FILE_REWRITES.map((file) => file.path)).toEqual([
|
||||
"public/release-manifest.json",
|
||||
"config/scale/feature-shape-ceilings.json",
|
||||
]);
|
||||
});
|
||||
|
||||
it("names each file and its rewrite command in the 03 manual's section A", async () => {
|
||||
const section = between(
|
||||
await readFile("docs/manual/03-outside-feature-folder.md", "utf8"),
|
||||
|
||||
@@ -448,6 +448,55 @@ describe("live hosting probe (1105/06-02)", () => {
|
||||
expect.objectContaining({ surface: "releaseManifest", header: "build-id", passed: true }),
|
||||
);
|
||||
});
|
||||
|
||||
// 1106/06-01. Browsers fetch the worker script with redirect mode "error",
|
||||
// so a same-origin redirect breaks registration, every update check and the
|
||||
// REMOVE_REGISTRATION kill switch, while the followed answer is a 200 with
|
||||
// the right headers. A page may still follow such a redirect.
|
||||
it("fails a worker script the host answers only after a same-origin redirect", async () => {
|
||||
const served: Record<string, readonly [string, string]> = {
|
||||
"/": [INDEX, "text/html"],
|
||||
"/release-manifest.json": [JSON.stringify(IDENTITY), "application/json"],
|
||||
"/service-worker.js": ["", "text/javascript"],
|
||||
"/assets/index-A1.js": ["", "text/javascript"],
|
||||
"/assets/index-C3.css": ["", "text/css"],
|
||||
};
|
||||
// Each path in `redirected` is answered after a redirect to `/v2/...` on the same origin.
|
||||
const failing = async (redirected: readonly string[]) => {
|
||||
const { results } = await probeLiveHosting(
|
||||
base,
|
||||
{ ...PATHS, serviceWorker: "/service-worker.js" },
|
||||
CANDIDATE,
|
||||
DIST_FILES,
|
||||
{
|
||||
fetcher: async (url) => {
|
||||
const entry = served[url.pathname];
|
||||
const response = new Response(entry?.[0] ?? "Not Found", {
|
||||
status: entry ? 200 : 404,
|
||||
headers: entry ? { "content-type": entry[1] } : {},
|
||||
});
|
||||
const moved = redirected.includes(url.pathname);
|
||||
Object.defineProperty(response, "url", {
|
||||
value: moved ? new URL(`/v2${url.pathname}`, url).href : url.href,
|
||||
});
|
||||
Object.defineProperty(response, "redirected", { value: moved });
|
||||
return response;
|
||||
},
|
||||
},
|
||||
);
|
||||
return results.filter((result) => !result.passed);
|
||||
};
|
||||
|
||||
expect(await failing([])).toEqual([]);
|
||||
expect(await failing(["/", "/service-worker.js"])).toEqual([
|
||||
expect.objectContaining({
|
||||
surface: "serviceWorker",
|
||||
header: "redirect",
|
||||
observed: true,
|
||||
reason: expect.stringContaining("redirect"),
|
||||
}),
|
||||
]);
|
||||
});
|
||||
});
|
||||
|
||||
// 1101/13-01. FE-GATE-019 checks the promoted candidate it downloaded, not a
|
||||
|
||||
@@ -0,0 +1,51 @@
|
||||
import { afterEach, describe, expect, it } from "vitest";
|
||||
|
||||
import {
|
||||
configRuns,
|
||||
describeResultFolders,
|
||||
describeServerPorts,
|
||||
hold,
|
||||
itExitsWhenItsPortIsTaken,
|
||||
itKeepsTheViteCacheInTheRun,
|
||||
portOf,
|
||||
releaseRuns,
|
||||
} from "../helpers/playwright-run-isolation.ts";
|
||||
|
||||
/**
|
||||
* 1105/12-04 for the capabilities config; why each check exists is in
|
||||
* tests/unit/playwright-run-isolation.test.ts.
|
||||
*
|
||||
* 1106/10-01. This config goes with the browser file/storage runtime:
|
||||
* test:browser-file-storage-removal deletes it, and deletes this file by
|
||||
* name with it. Its eight checks used to sit with the other configs and were
|
||||
* defined only while `existsSync` found the config. test:unit fails on a
|
||||
* skipped test (1101/10-04), but a test that is never defined is not
|
||||
* reported: the checks left that drill's copy unnoticed, and a renamed config
|
||||
* would have taken them out of the template the same way. Imported by name, a
|
||||
* renamed config fails check:types and this file instead.
|
||||
*/
|
||||
const runs = configRuns({
|
||||
capabilities: () => import("../../playwright.capabilities.config.ts"),
|
||||
visual: () => import("../../playwright.visual.config.ts"),
|
||||
});
|
||||
|
||||
afterEach(releaseRuns);
|
||||
|
||||
describeResultFolders(runs, [["capabilities", "browser-capabilities"]]);
|
||||
|
||||
describe("the build a run serves", () => {
|
||||
itKeepsTheViteCacheInTheRun(runs, ["capabilities"]);
|
||||
});
|
||||
|
||||
describeServerPorts(runs, ["capabilities"]);
|
||||
|
||||
describe("vite servers", () => {
|
||||
itExitsWhenItsPortIsTaken(runs, ["capabilities"]);
|
||||
|
||||
it("no longer share one port between the visual preview and the capability dev server", async () => {
|
||||
const visual = portOf(await runs.load("visual"));
|
||||
await hold(visual);
|
||||
|
||||
expect(portOf(await runs.load("capabilities"))).not.toBe(visual);
|
||||
});
|
||||
});
|
||||
@@ -1,9 +1,16 @@
|
||||
import { existsSync, readFileSync } from "node:fs";
|
||||
import { createServer, type Server } from "node:net";
|
||||
import path from "node:path";
|
||||
import { readFileSync } from "node:fs";
|
||||
|
||||
import type { PlaywrightTestConfig } from "@playwright/test";
|
||||
import { afterEach, describe, expect, it, vi } from "vitest";
|
||||
import { afterEach, describe, expect, it } from "vitest";
|
||||
|
||||
import {
|
||||
configRuns,
|
||||
describeResultFolders,
|
||||
describeServerPorts,
|
||||
itExitsWhenItsPortIsTaken,
|
||||
itKeepsTheViteCacheInTheRun,
|
||||
releaseRuns,
|
||||
webServer,
|
||||
} from "../helpers/playwright-run-isolation.ts";
|
||||
|
||||
/**
|
||||
* 1105/12-04. Every Playwright config wrote its results, report and JUnit
|
||||
@@ -20,151 +27,36 @@ import { afterEach, describe, expect, it, vi } from "vitest";
|
||||
*
|
||||
* Each load evaluates the config again with the environment of one process.
|
||||
*
|
||||
* test:browser-file-storage-removal deletes the capabilities config with the
|
||||
* capability it runs, so a project without it checks the other four. Its path
|
||||
* is a variable so that typecheck does not need the file.
|
||||
* 1106/10-01. The capabilities config is checked in
|
||||
* tests/unit/playwright-capabilities-run-isolation.test.ts: it goes with the
|
||||
* browser file/storage runtime, and test:browser-file-storage-removal deletes
|
||||
* the config and that file by name. This file has the four configs every
|
||||
* project has.
|
||||
*/
|
||||
const CAPABILITIES_CONFIG = "playwright.capabilities.config.ts";
|
||||
const HAS_CAPABILITIES = existsSync(CAPABILITIES_CONFIG);
|
||||
const LOADERS = {
|
||||
const runs = configRuns({
|
||||
e2e: () => import("../../playwright.config.ts"),
|
||||
visual: () => import("../../playwright.visual.config.ts"),
|
||||
capabilities: () =>
|
||||
import(/* @vite-ignore */ `../../${CAPABILITIES_CONFIG}`) as Promise<{
|
||||
default: PlaywrightTestConfig;
|
||||
}>,
|
||||
storybook: () => import("../../playwright.storybook.config.ts"),
|
||||
dev: () => import("../../playwright.dev.config.ts"),
|
||||
} as const;
|
||||
type ConfigName = keyof typeof LOADERS;
|
||||
/** The names among `names` whose config file this checkout has. */
|
||||
function installed<T extends ConfigName>(names: readonly T[]): T[] {
|
||||
return names.filter((name) => name !== "capabilities" || HAS_CAPABILITIES);
|
||||
}
|
||||
const CONFIG_NAMES = installed(Object.keys(LOADERS) as ConfigName[]);
|
||||
const PORT_VARIABLES: Readonly<Record<ConfigName, string>> = {
|
||||
e2e: "TEST_E2E_PORT",
|
||||
visual: "TEST_VISUAL_PORT",
|
||||
capabilities: "TEST_CAPABILITIES_PORT",
|
||||
storybook: "TEST_STORYBOOK_PORT",
|
||||
dev: "TEST_DEV_PORT",
|
||||
};
|
||||
const RUN_VARIABLES = ["TEST_RUN_ID", "RUN_OUTPUT_ROOT", ...Object.values(PORT_VARIABLES)];
|
||||
const held: Server[] = [];
|
||||
|
||||
afterEach(async () => {
|
||||
vi.resetModules();
|
||||
await Promise.all(
|
||||
held.splice(0).map((server) => new Promise<void>((resolve) => server.close(() => resolve()))),
|
||||
);
|
||||
});
|
||||
|
||||
/** The config as one process sees it, and what it left in that environment. */
|
||||
async function loadProcess(
|
||||
name: ConfigName,
|
||||
environment: Readonly<Record<string, string>> = {},
|
||||
): Promise<{ config: PlaywrightTestConfig; after: Readonly<Record<string, string | undefined>> }> {
|
||||
const saved = RUN_VARIABLES.map((variable) => [variable, process.env[variable]] as const);
|
||||
for (const variable of RUN_VARIABLES) delete process.env[variable];
|
||||
Object.assign(process.env, environment);
|
||||
vi.resetModules();
|
||||
try {
|
||||
const config = (await LOADERS[name]()).default;
|
||||
return {
|
||||
config,
|
||||
after: Object.fromEntries(RUN_VARIABLES.map((variable) => [variable, process.env[variable]])),
|
||||
};
|
||||
} finally {
|
||||
for (const [variable, value] of saved) {
|
||||
if (value === undefined) delete process.env[variable];
|
||||
else process.env[variable] = value;
|
||||
}
|
||||
}
|
||||
}
|
||||
afterEach(releaseRuns);
|
||||
|
||||
async function load(
|
||||
name: ConfigName,
|
||||
environment: Readonly<Record<string, string>> = {},
|
||||
): Promise<PlaywrightTestConfig> {
|
||||
return (await loadProcess(name, environment)).config;
|
||||
}
|
||||
|
||||
function portOf(config: PlaywrightTestConfig): number {
|
||||
return Number(new URL(String(config.use?.baseURL)).port);
|
||||
}
|
||||
|
||||
/** Listens on `port` the way the first run's server does. */
|
||||
async function hold(port: number): Promise<void> {
|
||||
const server = createServer();
|
||||
held.push(server);
|
||||
await new Promise<void>((resolve, reject) => {
|
||||
server.once("error", reject);
|
||||
server.listen(port, "127.0.0.1", () => resolve());
|
||||
});
|
||||
}
|
||||
|
||||
function reporterOption(config: PlaywrightTestConfig, reporter: string, option: string): string {
|
||||
const reporters: readonly unknown[] = Array.isArray(config.reporter) ? config.reporter : [];
|
||||
const entry = reporters.find(
|
||||
(candidate) => Array.isArray(candidate) && candidate[0] === reporter,
|
||||
) as readonly [string, Record<string, unknown>] | undefined;
|
||||
return String(entry?.[1][option]);
|
||||
}
|
||||
|
||||
function outputs(config: PlaywrightTestConfig) {
|
||||
return {
|
||||
results: path.resolve(String(config.outputDir)),
|
||||
report: path.resolve(reporterOption(config, "html", "outputFolder")),
|
||||
junit: path.resolve(reporterOption(config, "junit", "outputFile")),
|
||||
};
|
||||
}
|
||||
|
||||
function webServer(config: PlaywrightTestConfig) {
|
||||
const server = config.webServer;
|
||||
if (!server || Array.isArray(server)) throw new TypeError("expected one web server");
|
||||
return server;
|
||||
}
|
||||
|
||||
const RESULT_FOLDERS: Readonly<Record<Exclude<ConfigName, "dev">, string>> = {
|
||||
e2e: "e2e",
|
||||
visual: "visual",
|
||||
capabilities: "browser-capabilities",
|
||||
storybook: "storybook",
|
||||
};
|
||||
|
||||
const INSTALLED_RESULT_FOLDERS = installed(
|
||||
Object.keys(RESULT_FOLDERS) as Exclude<ConfigName, "dev">[],
|
||||
).map((name) => [name, RESULT_FOLDERS[name]] as const);
|
||||
|
||||
describe.each(INSTALLED_RESULT_FOLDERS)("the %s config", (name, folder) => {
|
||||
const expected = (root: string) => ({
|
||||
results: path.resolve(root, `artifacts/tests/${folder}/results`),
|
||||
report: path.resolve(root, `artifacts/tests/${folder}/report`),
|
||||
junit: path.resolve(root, `artifacts/tests/${folder}/results.xml`),
|
||||
});
|
||||
|
||||
it("writes where the gates read without a run ID", async () => {
|
||||
expect(outputs(await load(name as ConfigName))).toEqual(expected("."));
|
||||
});
|
||||
|
||||
it("gives each run ID its own results, report and JUnit file", async () => {
|
||||
const a = outputs(await load(name as ConfigName, { TEST_RUN_ID: "a" }));
|
||||
const b = outputs(await load(name as ConfigName, { TEST_RUN_ID: "b" }));
|
||||
|
||||
expect(a).toEqual(expected(".tmp/runs/a"));
|
||||
expect(b).toEqual(expected(".tmp/runs/b"));
|
||||
});
|
||||
});
|
||||
describeResultFolders(runs, [
|
||||
["e2e", "e2e"],
|
||||
["visual", "visual"],
|
||||
["storybook", "storybook"],
|
||||
]);
|
||||
|
||||
describe("the build a run serves", () => {
|
||||
it.each(["e2e", "visual"] as const)(
|
||||
"is the checkout's dist without a run ID, and the run's own with one (%s)",
|
||||
async (name) => {
|
||||
const checkout = webServer(await load(name));
|
||||
const checkout = webServer(await runs.load(name));
|
||||
expect(checkout.env?.["RUN_OUTPUT_ROOT"]).toBe(".");
|
||||
expect(checkout.command).toMatch(/ --outDir dist(?: |$)/u);
|
||||
|
||||
const run = webServer(await load(name, { TEST_RUN_ID: "a" }));
|
||||
const run = webServer(await runs.load(name, { TEST_RUN_ID: "a" }));
|
||||
// The build writes under RUN_OUTPUT_ROOT and the preview serves it.
|
||||
expect(run.env?.["RUN_OUTPUT_ROOT"]).toBe(".tmp/runs/a");
|
||||
expect(run.command).toMatch(/^corepack pnpm build && corepack pnpm preview /u);
|
||||
@@ -172,23 +64,15 @@ describe("the build a run serves", () => {
|
||||
},
|
||||
);
|
||||
|
||||
it.each(installed(["capabilities", "dev"] as const))(
|
||||
"keeps the dev server's Vite cache in the run's folder (%s)",
|
||||
async (name) => {
|
||||
expect(webServer(await load(name)).env?.["RUN_OUTPUT_ROOT"]).toBe(".");
|
||||
expect(webServer(await load(name, { TEST_RUN_ID: "a" })).env?.["RUN_OUTPUT_ROOT"]).toBe(
|
||||
".tmp/runs/a",
|
||||
);
|
||||
},
|
||||
);
|
||||
itKeepsTheViteCacheInTheRun(runs, ["dev"]);
|
||||
|
||||
it("builds the workshop into the run's folder the way build:storybook does", async () => {
|
||||
const checkout = webServer(await load("storybook")).command;
|
||||
const checkout = webServer(await runs.load("storybook")).command;
|
||||
expect(checkout).toMatch(
|
||||
/^corepack pnpm build:storybook && node scripts\/serve-static\.ts artifacts\/storybook\/static /u,
|
||||
);
|
||||
|
||||
const run = webServer(await load("storybook", { TEST_RUN_ID: "a" })).command;
|
||||
const run = webServer(await runs.load("storybook", { TEST_RUN_ID: "a" })).command;
|
||||
const script = (
|
||||
JSON.parse(readFileSync("package.json", "utf8")) as { scripts: Record<string, string> }
|
||||
).scripts["build:storybook"]!;
|
||||
@@ -201,53 +85,8 @@ describe("the build a run serves", () => {
|
||||
});
|
||||
});
|
||||
|
||||
describe.each(CONFIG_NAMES)("the %s server port", (name) => {
|
||||
it("is a free port the runner hands to its workers", async () => {
|
||||
const runner = await loadProcess(name);
|
||||
const port = portOf(runner.config);
|
||||
const server = webServer(runner.config);
|
||||
|
||||
// Playwright evaluates the config again in each worker, which inherits
|
||||
// the runner's environment: the port is there, so baseURL agrees.
|
||||
expect(runner.after[PORT_VARIABLES[name]]).toBe(String(port));
|
||||
expect(portOf(await load(name, { [PORT_VARIABLES[name]]: String(port) }))).toBe(port);
|
||||
expect(server.url).toBe(`http://127.0.0.1:${port}`);
|
||||
expect(server.command).toMatch(new RegExp(` (?:--port )?${port}(?: |$)`, "u"));
|
||||
expect(server.reuseExistingServer).toBe(false);
|
||||
});
|
||||
|
||||
it("moves for a second run while the first run's server holds its port", async () => {
|
||||
const first = portOf(await load(name));
|
||||
await hold(first);
|
||||
|
||||
expect(portOf(await load(name))).not.toBe(first);
|
||||
});
|
||||
|
||||
it("is the one its variable pins", async () => {
|
||||
const pinned = await load(name, { [PORT_VARIABLES[name]]: "40123" });
|
||||
expect(portOf(pinned)).toBe(40123);
|
||||
expect(webServer(pinned).url).toBe("http://127.0.0.1:40123");
|
||||
});
|
||||
});
|
||||
describeServerPorts(runs, ["e2e", "visual", "storybook", "dev"]);
|
||||
|
||||
describe("vite servers", () => {
|
||||
it.each(installed(["e2e", "visual", "capabilities", "dev"] as const))(
|
||||
"exit instead of moving to the next port when theirs is taken (%s)",
|
||||
async (name) => {
|
||||
// Without --strictPort vite moved on, and Playwright, waiting on the
|
||||
// configured URL, tested whatever already listened there.
|
||||
expect(webServer(await load(name)).command).toMatch(/ --port \d+ --strictPort(?: |$)/u);
|
||||
},
|
||||
);
|
||||
|
||||
// Defined only where the capabilities config exists, not skipped:
|
||||
// test:unit fails on a skipped test (0929/10-04).
|
||||
if (HAS_CAPABILITIES) {
|
||||
it("no longer share one port between the visual preview and the capability dev server", async () => {
|
||||
const visual = portOf(await load("visual"));
|
||||
await hold(visual);
|
||||
|
||||
expect(portOf(await load("capabilities"))).not.toBe(visual);
|
||||
});
|
||||
}
|
||||
itExitsWhenItsPortIsTaken(runs, ["e2e", "visual", "dev"]);
|
||||
});
|
||||
|
||||
@@ -970,4 +970,91 @@ describe("public cache pointer after a policy change or damage (0929/02-01)", ()
|
||||
await adapter.responses.matchActiveExact({ absoluteUrl: assetUrl("r1") }),
|
||||
).toMatchObject({ ok: true, value: expect.anything() });
|
||||
});
|
||||
|
||||
// 1106/02-01 (review experiment 02-R1 X3). The pointer entry is there, but
|
||||
// its stored body fails to read until something writes it again (a lost
|
||||
// blob). Without the option that looks like the transient failure above and
|
||||
// everything stops; only an activation writes the pointer.
|
||||
it("replaces a pointer whose body stays unreadable when the activation asks to (1106/02-01)", async () => {
|
||||
const cacheStorage = new MemoryCacheStorage();
|
||||
const policy = policyRetaining(1);
|
||||
const adapter = adapterFor(cacheStorage, policy);
|
||||
expect(await deploy(adapter, "r1", policy)).toMatchObject({ ok: true });
|
||||
const control = cacheStorage.caches.get(controlCacheName(policy))!;
|
||||
const pointerUrl = activePointerRequest(policy).url;
|
||||
const pointer = { unreadable: true, rewrites: 0 };
|
||||
const realMatch = control.match.bind(control);
|
||||
const realPut = control.put.bind(control);
|
||||
const urlOf = (request: RequestInfo | URL) =>
|
||||
request instanceof Request ? request.url : new URL(String(request)).href;
|
||||
control.put = async (request, response) => {
|
||||
if (urlOf(request) === pointerUrl) {
|
||||
pointer.unreadable = false;
|
||||
pointer.rewrites += 1;
|
||||
}
|
||||
await realPut(request, response);
|
||||
};
|
||||
control.match = async (request) => {
|
||||
const stored = await realMatch(request);
|
||||
if (!stored || urlOf(request) !== pointerUrl || !pointer.unreadable) {
|
||||
return stored;
|
||||
}
|
||||
return new Response(
|
||||
new ReadableStream<Uint8Array>({
|
||||
pull(controller) {
|
||||
controller.error(new TypeError("blob missing"));
|
||||
},
|
||||
}),
|
||||
{ headers: stored.headers },
|
||||
);
|
||||
};
|
||||
const next = await manifestOf("r2", policy);
|
||||
const activateNext = (
|
||||
options?: Readonly<{ replaceUnreadablePointer?: boolean }>,
|
||||
) =>
|
||||
adapter.admin.activateRelease(
|
||||
next.releaseRegistryId,
|
||||
next.manifestDigestHex,
|
||||
options,
|
||||
);
|
||||
const unavailable = (operation: string) => ({
|
||||
ok: false,
|
||||
error: { code: "UNAVAILABLE", operation, recovery: "RETRY" },
|
||||
});
|
||||
|
||||
// Staging does not read the pointer; everything else stops on it.
|
||||
expect(await adapter.admin.stageRelease(next)).toMatchObject({ ok: true });
|
||||
expect(
|
||||
await adapter.responses.matchActiveExact({ absoluteUrl: assetUrl("r1") }),
|
||||
).toMatchObject(unavailable("CACHE_LOOKUP"));
|
||||
expect(await activateNext()).toMatchObject(unavailable("CACHE_ACTIVATE"));
|
||||
expect(await adapter.admin.cleanupOwned()).toMatchObject(
|
||||
unavailable("CACHE_DELETE"),
|
||||
);
|
||||
expect(await adapter.admin.inspect()).toMatchObject(
|
||||
unavailable("CACHE_LOOKUP"),
|
||||
);
|
||||
expect(await activateNext()).toMatchObject(unavailable("CACHE_ACTIVATE"));
|
||||
expect(pointer).toEqual({ unreadable: true, rewrites: 0 });
|
||||
|
||||
// The way back: this activation replaces the pointer it cannot read.
|
||||
expect(
|
||||
await activateNext({ replaceUnreadablePointer: true }),
|
||||
).toMatchObject({ ok: true, value: { releaseRegistryId: "r2" } });
|
||||
expect(pointer).toEqual({ unreadable: false, rewrites: 1 });
|
||||
expect(
|
||||
await adapter.responses.matchActiveExact({ absoluteUrl: assetUrl("r2") }),
|
||||
).toMatchObject({ ok: true, value: expect.anything() });
|
||||
expect(await adapter.admin.inspect()).toMatchObject({
|
||||
ok: true,
|
||||
value: { activePointer: "READABLE", activeReleaseRegistryId: "r2" },
|
||||
});
|
||||
// The rollback list went with the old pointer, so cleanup drops r1.
|
||||
expect(await adapter.admin.cleanupOwned()).toMatchObject({
|
||||
ok: true,
|
||||
value: { deletedOwnedCaches: 1, retainedOwnedCaches: 2 },
|
||||
});
|
||||
// A later activation without the option works as before.
|
||||
expect(await deploy(adapter, "r3", policy)).toMatchObject({ ok: true });
|
||||
});
|
||||
});
|
||||
|
||||
@@ -1,11 +1,15 @@
|
||||
import { describe, expect, it, vi } from "vitest";
|
||||
|
||||
import type { ClockPort } from "../../../src/application/ports/clock-port.ts";
|
||||
import type { RealtimeFailureKind } from "../../../src/application/ports/realtime/shared.ts";
|
||||
import {
|
||||
definePollLeasePolicy,
|
||||
type BoundedPollOperation,
|
||||
} from "../../../src/application/policies/bounded-polling.ts";
|
||||
import { createContractHttpExecutor } from "../../../src/adapters/http/index.ts";
|
||||
import {
|
||||
createContractHttpExecutor,
|
||||
type HttpExecutionOutcome,
|
||||
} from "../../../src/adapters/http/index.ts";
|
||||
import {
|
||||
createBoundedPollCoordinator,
|
||||
type BoundedPollAttemptResult,
|
||||
@@ -1090,6 +1094,71 @@ describe("bounded poll coordinator", () => {
|
||||
});
|
||||
});
|
||||
|
||||
/**
|
||||
* Design 9.2's table (1106/04-02): every V3 executor outcome as a poll attempt
|
||||
* result. `retryAfterMs` is present only with a value; an empty key is a
|
||||
* malformed result.
|
||||
*/
|
||||
function pollAttemptResult<Value>(
|
||||
outcome: HttpExecutionOutcome<Value, unknown>,
|
||||
): BoundedPollAttemptResult<Value> {
|
||||
const failed = (
|
||||
kind: RealtimeFailureKind,
|
||||
retryable: boolean,
|
||||
retryAfterMs?: number,
|
||||
): BoundedPollAttemptResult<Value> => ({
|
||||
ok: false,
|
||||
error: {
|
||||
kind,
|
||||
operation: "POLL",
|
||||
retryable,
|
||||
...(retryAfterMs === undefined ? {} : { retryAfterMs }),
|
||||
},
|
||||
});
|
||||
const outage = (status: number | undefined) =>
|
||||
status !== undefined &&
|
||||
(status >= 500 || status === 408 || status === 425);
|
||||
switch (outcome.kind) {
|
||||
case "SUCCESS":
|
||||
return {
|
||||
ok: true,
|
||||
value: { kind: "VALUE", value: outcome.value, responseBytes: 0 },
|
||||
};
|
||||
case "PROBLEM":
|
||||
case "CONTRACT_VIOLATION":
|
||||
return outage(outcome.metadata?.status)
|
||||
? failed(
|
||||
"PROVIDER_UNAVAILABLE",
|
||||
true,
|
||||
outcome.metadata?.retryAfterMs,
|
||||
)
|
||||
: failed("PROTOCOL_MISMATCH", false);
|
||||
case "UNAUTHENTICATED":
|
||||
return failed("AUTH_REQUIRED", false);
|
||||
case "FORBIDDEN":
|
||||
return failed("FORBIDDEN", false);
|
||||
case "RATE_LIMITED":
|
||||
return failed("RATE_LIMITED", true, outcome.retryAfterMs);
|
||||
case "TRANSPORT_FAILURE":
|
||||
if (outcome.failure.kind === "TIMEOUT") {
|
||||
return failed("CONNECT_TIMEOUT", true);
|
||||
}
|
||||
if (outcome.failure.kind === "ABORTED_BY_CALLER") {
|
||||
return failed("ABORTED", false);
|
||||
}
|
||||
if (outcome.failure.kind === "ABORTED_BY_SCOPE") {
|
||||
return failed("SCOPE_FENCED", false);
|
||||
}
|
||||
return failed("PROVIDER_UNAVAILABLE", true);
|
||||
case "CANCELLED":
|
||||
return failed("ABORTED", false);
|
||||
case "AUTH_INTEGRATION_FAILURE":
|
||||
return outcome.reason === "CREDENTIAL_OWNER_UNAVAILABLE"
|
||||
? failed("PROVIDER_UNAVAILABLE", true)
|
||||
: failed("PROTOCOL_MISMATCH", false);
|
||||
}
|
||||
}
|
||||
|
||||
// 1103/04-01. The natural composition: `execute` runs the poll's descriptor on
|
||||
// the app's V3 executor. The executor's own retries would turn one poll attempt
|
||||
// into up to three requests, hidden from the poll's budget and observations.
|
||||
@@ -1115,7 +1184,27 @@ describe("a poll attempt on the V3 executor", () => {
|
||||
isCurrent: () => true,
|
||||
});
|
||||
|
||||
function pollOn(descriptor: BoundedPollOperation, clock: ManualClock) {
|
||||
// 1106/04-02. Typed by the feature's own descriptor, with no cast.
|
||||
const typedPollOnly = Object.freeze({
|
||||
...TEST_LIST_HTTP_CONTRACT,
|
||||
frontend: Object.freeze({
|
||||
...TEST_LIST_HTTP_CONTRACT.frontend,
|
||||
retryBudget: 0 as const,
|
||||
}),
|
||||
});
|
||||
|
||||
function pollOn(
|
||||
descriptor: BoundedPollOperation,
|
||||
clock: ManualClock,
|
||||
respond: () => Response = () =>
|
||||
new Response(
|
||||
JSON.stringify({ type: "about:blank", title: "down", status: 503 }),
|
||||
{
|
||||
status: 503,
|
||||
headers: { "content-type": "application/problem+json" },
|
||||
},
|
||||
),
|
||||
) {
|
||||
const requests: string[] = [];
|
||||
const executor = createContractHttpExecutor({
|
||||
baseUrl: "https://api.example/",
|
||||
@@ -1124,13 +1213,7 @@ describe("a poll attempt on the V3 executor", () => {
|
||||
attachCredentials: () => ({ kind: "READY", headers: {} }),
|
||||
fetcher: async (request) => {
|
||||
requests.push(String(request));
|
||||
return new Response(
|
||||
JSON.stringify({ type: "about:blank", title: "down", status: 503 }),
|
||||
{
|
||||
status: 503,
|
||||
headers: { "content-type": "application/problem+json" },
|
||||
},
|
||||
);
|
||||
return respond();
|
||||
},
|
||||
sleep: async () => undefined,
|
||||
random: () => 0.5,
|
||||
@@ -1143,31 +1226,77 @@ describe("a poll attempt on the V3 executor", () => {
|
||||
clock,
|
||||
random: () => 0.5,
|
||||
// 1103/04-01. Runs the descriptor the coordinator hands back, never a
|
||||
// closed-over one.
|
||||
// closed-over one, and maps its outcome by the 9.2 table (1106/04-02).
|
||||
execute: async ({ operation: polled, signal }) => {
|
||||
const outcome = await executor.execute(
|
||||
polled,
|
||||
{ limit: 20 },
|
||||
{ routeId: "TEST_ROUTE", scope, signal },
|
||||
);
|
||||
return outcome.kind === "SUCCESS"
|
||||
? {
|
||||
ok: true,
|
||||
value: { kind: "VALUE", value: outcome.value, responseBytes: 1 },
|
||||
}
|
||||
: {
|
||||
ok: false,
|
||||
error: {
|
||||
kind: "PROVIDER_UNAVAILABLE",
|
||||
operation: "POLL",
|
||||
retryable: true,
|
||||
},
|
||||
};
|
||||
return pollAttemptResult(outcome);
|
||||
},
|
||||
});
|
||||
return { coordinator, requests };
|
||||
}
|
||||
|
||||
// 1106/04-02. `input.operation` keeps the descriptor's own type, so the
|
||||
// executor call in `execute` is checked against the feature's input and
|
||||
// output types. check:types is the assertion; the body never runs.
|
||||
it("types the executor call in execute by the poll descriptor", () => {
|
||||
const executor = createContractHttpExecutor({
|
||||
baseUrl: "https://api.example/",
|
||||
maxRetryAttempts: 2,
|
||||
attachCredentials: () => ({ kind: "READY", headers: {} }),
|
||||
fetcher: async () => new Response(null, { status: 503 }),
|
||||
});
|
||||
const coordinator = createBoundedPollCoordinator({
|
||||
policy: pollPolicy,
|
||||
operation: typedPollOnly,
|
||||
environment: new MutableEnvironment(),
|
||||
execute: async ({ operation: polled, signal }) => {
|
||||
const context = { routeId: "TEST_ROUTE", scope, signal };
|
||||
// @ts-expect-error 1106/04-02: the list descriptor takes `limit`, not `size`.
|
||||
await executor.execute(polled, { size: 20 }, context);
|
||||
const outcome = await executor.execute(polled, { limit: 20 }, context);
|
||||
return pollAttemptResult<readonly Readonly<{ id: string; name: string }>[]>(outcome);
|
||||
},
|
||||
});
|
||||
|
||||
expect(coordinator.getState()).toBe("IDLE");
|
||||
});
|
||||
|
||||
// 1106/04-02. The 9.2 table ends the lease on an auth answer. The old
|
||||
// example here retried every non-SUCCESS outcome as a server outage.
|
||||
it.each([
|
||||
[401, "AUTH_REQUIRED"],
|
||||
[403, "FORBIDDEN"],
|
||||
] as const)(
|
||||
"ends the lease on the first %i through the 9.2 table",
|
||||
async (status, kind) => {
|
||||
const clock = new ManualClock();
|
||||
const { coordinator, requests } = pollOn(
|
||||
typedPollOnly,
|
||||
clock,
|
||||
() => new Response(null, { status }),
|
||||
);
|
||||
|
||||
let result: unknown = null;
|
||||
void coordinator.run().then((value) => {
|
||||
result = value;
|
||||
});
|
||||
for (let turn = 0; turn < 400 && result === null; turn += 1) {
|
||||
clock.advance(1_000);
|
||||
await flush();
|
||||
}
|
||||
|
||||
expect(result).toEqual({
|
||||
ok: false,
|
||||
error: { kind, operation: "POLL", retryable: false },
|
||||
});
|
||||
expect(requests).toHaveLength(1);
|
||||
},
|
||||
);
|
||||
|
||||
it("refuses the default read descriptor, whose executor retries", () => {
|
||||
expect(TEST_LIST_HTTP_CONTRACT.frontend.retryBudget).toBe(2);
|
||||
expect(() =>
|
||||
|
||||
@@ -1758,16 +1758,29 @@ class FakeWebSocket implements WebSocketFacade {
|
||||
/**
|
||||
* The smallest SSE bridge design 6.3 leaves to composition: the attempt ends
|
||||
* at `onOpen` and the rest of the read is the session.
|
||||
*
|
||||
* 1106/04-01. The coordinator retries a throwing attempt as
|
||||
* PROVIDER_UNAVAILABLE, so the bridge checks its connection settings here,
|
||||
* when it is built: a wrong endpoint throws before any run. Each attempt
|
||||
* still makes its own connection, because the session's `close` ends that
|
||||
* connection for good.
|
||||
*/
|
||||
function sseAttempt(fetcher: typeof fetch, clock: ManualClock) {
|
||||
function sseAttempt(
|
||||
fetcher: typeof fetch,
|
||||
clock: ManualClock,
|
||||
endpoint = "https://app.example.test/events",
|
||||
) {
|
||||
const settings = Object.freeze({
|
||||
endpoint,
|
||||
applicationOrigin: "https://app.example.test",
|
||||
recoveryMode: "CURSOR" as const,
|
||||
fetcher,
|
||||
clock,
|
||||
});
|
||||
// Creating a connection checks the settings and sends nothing.
|
||||
createFetchSseConnection(settings).close();
|
||||
return async (context: RealtimeReconnectAttemptContext) => {
|
||||
const connection = createFetchSseConnection({
|
||||
endpoint: "https://app.example.test/events",
|
||||
applicationOrigin: "https://app.example.test",
|
||||
recoveryMode: "CURSOR",
|
||||
fetcher,
|
||||
clock,
|
||||
});
|
||||
const connection = createFetchSseConnection(settings);
|
||||
const open = deferred<"OPEN">();
|
||||
const reading = readSseForReconnect(connection, {
|
||||
resumeCursor: null,
|
||||
@@ -2435,4 +2448,106 @@ describe("results that composition code hands the reconnect coordinator", () =>
|
||||
);
|
||||
expect(clock.sleepCalls).toEqual([]);
|
||||
});
|
||||
|
||||
// 1106/04-01. The rule the attempt and session types state. A throwing
|
||||
// attempt or waitClosed is a transport failure and is retried; poll reads a
|
||||
// throwing execute the other way (1105/04-02).
|
||||
it.each([
|
||||
["attempt", "CONNECT"],
|
||||
["waitClosed", "RECEIVE"],
|
||||
] as const)(
|
||||
"retries a throwing %s as PROVIDER_UNAVAILABLE on %s",
|
||||
async (thrower, operation) => {
|
||||
const clock = new ManualClock();
|
||||
const observed: string[] = [];
|
||||
let attempts = 0;
|
||||
const coordinator = createRealtimeReconnectCoordinator({
|
||||
policy: policy(),
|
||||
environment: new MutableOnlineEnvironment(true),
|
||||
clock,
|
||||
random: () => 0.5,
|
||||
confirmTransportBarrier: confirmationSucceeded,
|
||||
attempt: () => {
|
||||
attempts += 1;
|
||||
if (thrower === "attempt") throw new TypeError("composer defect");
|
||||
return opened<RealtimeReconnectOutcome<void>>(
|
||||
Object.freeze({
|
||||
classifyClosed: (
|
||||
receipt: RealtimeReconnectOutcome<void>,
|
||||
) => receipt,
|
||||
close: vi.fn(),
|
||||
waitClosed: () => {
|
||||
throw new TypeError("composer defect");
|
||||
},
|
||||
}),
|
||||
);
|
||||
},
|
||||
observe: (observation) => observed.push(observationLabel(observation)),
|
||||
});
|
||||
|
||||
let result: RealtimeResult<void> | null = null;
|
||||
void coordinator.run().then((value) => {
|
||||
result = value;
|
||||
});
|
||||
await advanceUntil(clock, () => result !== null);
|
||||
|
||||
expect(attempts).toBe(3);
|
||||
expect(clock.sleepCalls).toEqual([50, 100]);
|
||||
expect(result).toEqual({
|
||||
ok: false,
|
||||
error: { kind: "PROVIDER_UNAVAILABLE", operation, retryable: true },
|
||||
});
|
||||
expect(
|
||||
observed.filter((label) => label.startsWith("RETRY_SCHEDULED")),
|
||||
).toEqual([
|
||||
"RETRY_SCHEDULED:PROVIDER_UNAVAILABLE",
|
||||
"RETRY_SCHEDULED:PROVIDER_UNAVAILABLE",
|
||||
]);
|
||||
expect(observed.at(-1)).toBe(
|
||||
"RUN_ENDED:PROVIDER_UNAVAILABLE:EXHAUSTED",
|
||||
);
|
||||
},
|
||||
);
|
||||
|
||||
it("ends the run without a retry when classifyClosed throws", async () => {
|
||||
const clock = new ManualClock();
|
||||
let attempts = 0;
|
||||
const coordinator = createRealtimeReconnectCoordinator({
|
||||
policy: policy(),
|
||||
environment: new MutableOnlineEnvironment(true),
|
||||
clock,
|
||||
confirmTransportBarrier: confirmationSucceeded,
|
||||
attempt: () => {
|
||||
attempts += 1;
|
||||
return opened<RealtimeReconnectOutcome<void>>(
|
||||
Object.freeze({
|
||||
classifyClosed: () => {
|
||||
throw new TypeError("composer defect");
|
||||
},
|
||||
close: vi.fn(),
|
||||
waitClosed: closedSuccessfully,
|
||||
}),
|
||||
);
|
||||
},
|
||||
});
|
||||
|
||||
await expect(coordinator.run()).resolves.toEqual(
|
||||
realtimeFailure("PROTOCOL_MISMATCH", "CONNECT", false),
|
||||
);
|
||||
expect(attempts).toBe(1);
|
||||
expect(clock.sleepCalls).toEqual([]);
|
||||
});
|
||||
|
||||
// Review 04-R2 built this endpoint's connection inside the attempt: no
|
||||
// request, three attempts, then PROVIDER_UNAVAILABLE (EXHAUSTED). The bridge
|
||||
// now checks its settings when it is built, so the run never starts.
|
||||
it("refuses a wrong SSE endpoint when the bridge is built", () => {
|
||||
const fetcher = vi.fn<typeof fetch>();
|
||||
const build = () =>
|
||||
sseAttempt(fetcher, new ManualClock(), "http://app.example.test/events");
|
||||
|
||||
expect(build).toThrow(TypeError);
|
||||
expect(build).toThrow("SSE endpoint must be fixed same-origin HTTPS.");
|
||||
expect(fetcher).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
@@ -3,6 +3,7 @@ import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from "node:fs/promis
|
||||
import { tmpdir } from "node:os";
|
||||
import path from "node:path";
|
||||
|
||||
import { parseAsync } from "@babel/core";
|
||||
import { afterEach, describe, expect, it } from "vitest";
|
||||
|
||||
import { loadCiGateContract } from "../../scripts/contracts/ci-gates.ts";
|
||||
@@ -137,6 +138,50 @@ it("rejects pruning that leaves a reduced gate without commands", async () => {
|
||||
})).rejects.toThrow(/commandIds|too small|at least 1/i);
|
||||
});
|
||||
|
||||
type BabelOptions = NonNullable<Parameters<typeof parseAsync>[1]>;
|
||||
type BabelParserPlugin = NonNullable<NonNullable<BabelOptions["parserOpts"]>["plugins"]>[number];
|
||||
type SyntaxNode = { type: string } & Record<string, unknown>;
|
||||
|
||||
/**
|
||||
* 1106/12-01. The document paths the code of `source` spells out: string and
|
||||
* template literal parts that are a document target (README.md, CHANGELOG.md,
|
||||
* docs) or a path under one. Comments are not code.
|
||||
*/
|
||||
async function documentsNamedInCode(file: string, source: string): Promise<string[]> {
|
||||
const plugins: BabelParserPlugin[] = [["typescript", { dts: false }]];
|
||||
const tree = (await parseAsync(source, {
|
||||
filename: file,
|
||||
babelrc: false,
|
||||
configFile: false,
|
||||
sourceType: "module",
|
||||
parserOpts: { plugins },
|
||||
})) as unknown as SyntaxNode | null;
|
||||
if (!tree) throw new Error(`cannot parse ${file}`);
|
||||
const strings: string[] = [];
|
||||
const visit = (node: SyntaxNode): void => {
|
||||
const literal = node["value"];
|
||||
if (node.type === "StringLiteral" && typeof literal === "string") strings.push(literal);
|
||||
if (node.type === "TemplateElement") {
|
||||
const cooked = (literal as { cooked?: unknown } | undefined)?.cooked;
|
||||
if (typeof cooked === "string") strings.push(cooked);
|
||||
}
|
||||
for (const [key, value] of Object.entries(node)) {
|
||||
if (key === "comments" || key.endsWith("Comments")) continue;
|
||||
for (const child of Array.isArray(value) ? value : [value]) {
|
||||
if (child && typeof child === "object" && typeof (child as SyntaxNode).type === "string") {
|
||||
visit(child as SyntaxNode);
|
||||
}
|
||||
}
|
||||
}
|
||||
};
|
||||
visit(tree);
|
||||
return strings.filter((value) =>
|
||||
REMOVAL_FIXTURE_DOCUMENT_TARGETS.some(
|
||||
(target) => value === target || value.startsWith(`${target}/`),
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
// 1103/02-06. Three FE-GATE-020 drills copied the repository without its
|
||||
// documents and still ran the tests that read them, so each failed its `test`
|
||||
// check on ENOENT whatever it removed. Only the sample drill excluded them.
|
||||
@@ -157,12 +202,38 @@ describe("document tests in a removal fixture", () => {
|
||||
for (const test of REMOVAL_FIXTURE_DOCUMENT_TESTS) {
|
||||
expect(existsSync(test), test).toBe(documentsPresent);
|
||||
if (documentsPresent) {
|
||||
// 1105/14-02. docs/ is one of the document targets too.
|
||||
await expect(readFile(test, "utf8")).resolves.toMatch(/README\.md|CHANGELOG\.md|docs\//u);
|
||||
// 1106/12-01. Named in its code, not in a comment. A comment naming
|
||||
// the contract document let backend-contract-pin.test.ts on the list,
|
||||
// and its fourteen checks of config and code left those drills with
|
||||
// the one that read the document.
|
||||
expect(await documentsNamedInCode(test, await readFile(test, "utf8")), test).not.toEqual([]);
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
it("counts a document named in code, not one named in a comment", async () => {
|
||||
const commentOnly = [
|
||||
"// Reads docs/architecture/a.md (README.md, CHANGELOG.md).",
|
||||
"/** docs/manual/b.md */",
|
||||
'const pin = JSON.parse(readFileSync("config/pin.json", "utf8"));',
|
||||
"readFileSync(pin.document);",
|
||||
].join("\n");
|
||||
expect(await documentsNamedInCode("comment-only.test.ts", commentOnly)).toEqual([]);
|
||||
|
||||
const reads = [
|
||||
'readFileSync("CHANGELOG.md", "utf8");',
|
||||
"const name: string = 'a';",
|
||||
"readFileSync(`docs/manual/${name}.md`, 'utf8');",
|
||||
'z.string().startsWith("docs/");',
|
||||
'const notADocument = "src/docs/x.ts";',
|
||||
].join("\n");
|
||||
expect((await documentsNamedInCode("reads.test.ts", reads)).sort()).toEqual([
|
||||
"CHANGELOG.md",
|
||||
"docs/",
|
||||
"docs/manual/",
|
||||
]);
|
||||
});
|
||||
|
||||
it("is the only exclusion list: every drill prepares its fixture through it", async () => {
|
||||
const drills: string[] = [];
|
||||
for (const name of await readdir("scripts")) {
|
||||
|
||||
@@ -3,6 +3,7 @@ import { createServer, type Server } from "node:net";
|
||||
import { afterEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
import {
|
||||
checkoutBuildReadFailure,
|
||||
findFreePort,
|
||||
moduleSpecifier,
|
||||
reservePort,
|
||||
@@ -91,6 +92,24 @@ describe("build output root (RUN_OUTPUT_ROOT)", () => {
|
||||
expect(() => runOutputRoot({ RUN_OUTPUT_ROOT: root }), root).toThrow(/RUN_OUTPUT_ROOT/u);
|
||||
}
|
||||
});
|
||||
|
||||
// 1106/12-02. The steps after the build read the checkout's dist/ and
|
||||
// artifacts/; under another root they judged an earlier build.
|
||||
it("lets a step that reads the checkout's build run only when the build writes there", () => {
|
||||
for (const environment of [{}, { RUN_OUTPUT_ROOT: "" }, { RUN_OUTPUT_ROOT: "." }, { RUN_OUTPUT_ROOT: "./" }]) {
|
||||
expect(checkoutBuildReadFailure("check-bundle", environment), JSON.stringify(environment))
|
||||
.toBeUndefined();
|
||||
}
|
||||
expect(checkoutBuildReadFailure("check-bundle", { RUN_OUTPUT_ROOT: "./.tmp/runs/a/" })).toBe(
|
||||
"check-bundle reads the build at this checkout's paths (dist/, artifacts/), but " +
|
||||
"RUN_OUTPUT_ROOT=.tmp/runs/a makes the build write under .tmp/runs/a/, so it would " +
|
||||
"judge an earlier build. Unset RUN_OUTPUT_ROOT, build again and run check-bundle again.",
|
||||
);
|
||||
// A root the build itself refuses is no reason to read the checkout's.
|
||||
expect(checkoutBuildReadFailure("check-bundle", { RUN_OUTPUT_ROOT: "dist" })).toMatch(
|
||||
/^check-bundle: RUN_OUTPUT_ROOT must be/u,
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe("server ports", () => {
|
||||
|
||||
@@ -21,6 +21,14 @@ import {
|
||||
* `unrecognized_keys` rejects unknown fields; one that reaches the object
|
||||
* without that issue tolerates them. A nested object below that level is not
|
||||
* probed.
|
||||
*
|
||||
* 1106/07-02. Both fields are optional in the row type, and a row that left
|
||||
* them out used to be skipped here. 1105/07-02 grades a response row whose
|
||||
* policy turns `REJECT_UNKNOWN` as breaking, but a row with no policy does not
|
||||
* change when its DTO turns `.strict()`, so nothing saw it. A schema an HTTP
|
||||
* operation uses now fails here without them; the policy only where the probe
|
||||
* reaches an object (`policyProblems`). Route-only rows (`NotFoundSplat`) are
|
||||
* not in `slots` and still need neither.
|
||||
*/
|
||||
const PROBE_KEY = "__unknownFieldProbe";
|
||||
|
||||
@@ -77,6 +85,44 @@ const slots = COMPOSED_CONTRACT_CONTRIBUTIONS.contributions.flatMap(
|
||||
]),
|
||||
);
|
||||
|
||||
type Slot = Readonly<{
|
||||
operationId: string;
|
||||
direction: "REQUEST" | "RESPONSE";
|
||||
validator: RuntimeValidator<unknown>;
|
||||
}>;
|
||||
type Rows = Readonly<Record<string, SchemaDefinition | undefined>>;
|
||||
|
||||
function directionProblems(used: readonly Slot[], rows: Rows): string[] {
|
||||
return used.flatMap(({ operationId, direction, validator }) => {
|
||||
const declared = rows[validator.schemaId]?.direction;
|
||||
return declared === direction
|
||||
? []
|
||||
: [
|
||||
`${operationId} ${validator.schemaId}: row ${declared ?? "states no direction"}, used as ${direction}`,
|
||||
];
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* 1106/07-02 (diff review DR-04). A validator the probe cannot reach, one
|
||||
* that refuses both probes at the root (`z.undefined()` for a
|
||||
* `responseBody: "NONE"` output, a string or null payload), has no object
|
||||
* level to judge, and no row value equals `UNREACHED`. Its policy is not
|
||||
* compared; `directionProblems` still requires its `direction`.
|
||||
*/
|
||||
function policyProblems(used: readonly Slot[], rows: Rows): string[] {
|
||||
return used.flatMap(({ operationId, validator }) => {
|
||||
const probed = probeUnknownFieldPolicy(validator);
|
||||
if (probed === "UNREACHED") return [];
|
||||
const declared = rows[validator.schemaId]?.unknownFieldPolicy;
|
||||
return probed === declared
|
||||
? []
|
||||
: [
|
||||
`${operationId} ${validator.schemaId}: row ${declared ?? "states no unknownFieldPolicy"}, validator ${probed}`,
|
||||
];
|
||||
});
|
||||
}
|
||||
|
||||
type Boundary = SchemaDefinition["boundary"];
|
||||
|
||||
/**
|
||||
@@ -125,14 +171,7 @@ function boundaryFor(uses: ReadonlySet<string>): Boundary | undefined {
|
||||
// probe, and both cases pass empty.
|
||||
describe("FE-REG-SCHEMA policy of the installed HTTP schemas (1103/07-03)", () => {
|
||||
it("declares the direction each schema is used in", () => {
|
||||
const wrong = slots.flatMap(({ operationId, direction, validator }) => {
|
||||
const declared = SCHEMA_REGISTRY[validator.schemaId]?.direction;
|
||||
return declared === undefined || declared === direction
|
||||
? []
|
||||
: [`${operationId} ${validator.schemaId}: row ${declared}, used as ${direction}`];
|
||||
});
|
||||
|
||||
expect(wrong).toEqual([]);
|
||||
expect(directionProblems(slots, SCHEMA_REGISTRY)).toEqual([]);
|
||||
});
|
||||
|
||||
it("gives every schema an operation or route uses a row at the boundary it is used", () => {
|
||||
@@ -152,15 +191,53 @@ describe("FE-REG-SCHEMA policy of the installed HTTP schemas (1103/07-03)", () =
|
||||
});
|
||||
|
||||
it("declares the unknown-field policy its validator applies", () => {
|
||||
const wrong = slots.flatMap(({ operationId, validator }) => {
|
||||
const declared = SCHEMA_REGISTRY[validator.schemaId]?.unknownFieldPolicy;
|
||||
if (declared === undefined) return [];
|
||||
const probed = probeUnknownFieldPolicy(validator);
|
||||
return probed === declared
|
||||
? []
|
||||
: [`${operationId} ${validator.schemaId}: row ${declared}, validator ${probed}`];
|
||||
});
|
||||
|
||||
expect(wrong).toEqual([]);
|
||||
expect(policyProblems(slots, SCHEMA_REGISTRY)).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
// 1106/07-02 (diff review DR-04). No row value passed for such a schema: the
|
||||
// policy check asked for a field and then compared it with `UNREACHED`.
|
||||
describe("FE-REG-SCHEMA policy of a schema the probe cannot reach (1106/07-02)", () => {
|
||||
const noContent: RuntimeValidator<unknown> = {
|
||||
schemaId: "NoContent",
|
||||
safeParse: (value) =>
|
||||
value === undefined
|
||||
? { success: true, data: value }
|
||||
: { success: false, issues: [{ path: [], code: "invalid_type" }] },
|
||||
};
|
||||
const used: readonly Slot[] = [
|
||||
{ operationId: "DELETE_THING", direction: "RESPONSE", validator: noContent },
|
||||
];
|
||||
const rows = (
|
||||
fields: Pick<SchemaDefinition, "direction" | "unknownFieldPolicy">,
|
||||
): Rows => ({
|
||||
NoContent: {
|
||||
schemaId: "NoContent",
|
||||
boundary: "api-response",
|
||||
owner: "test",
|
||||
runtime: "zod",
|
||||
...fields,
|
||||
},
|
||||
});
|
||||
|
||||
it("is a schema the probe cannot reach", () => {
|
||||
expect(probeUnknownFieldPolicy(noContent)).toBe("UNREACHED");
|
||||
});
|
||||
|
||||
it("still needs its direction", () => {
|
||||
expect(directionProblems(used, rows({}))).toEqual([
|
||||
"DELETE_THING NoContent: row states no direction, used as RESPONSE",
|
||||
]);
|
||||
expect(directionProblems(used, rows({ direction: "RESPONSE" }))).toEqual([]);
|
||||
});
|
||||
|
||||
it("is not held to an unknown-field policy", () => {
|
||||
expect(policyProblems(used, rows({ direction: "RESPONSE" }))).toEqual([]);
|
||||
expect(
|
||||
policyProblems(
|
||||
used,
|
||||
rows({ direction: "RESPONSE", unknownFieldPolicy: "STRIP_UNKNOWN" }),
|
||||
),
|
||||
).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user