fix: 2026-11-05 리뷰를 기록하고 P1 3건을 고친다 #5
@@ -34,6 +34,8 @@ jobs:
|
||||
merge_gate:
|
||||
name: "${{ matrix.gate }} / ${{ matrix.name }}"
|
||||
if: ${{ gitea.event_name != 'workflow_dispatch' || inputs.stage != 'documentation' }}
|
||||
# FE-GATE-013 runner requirement: Linux with executable /usr/bin/bwrap (with --size), /usr/bin/prlimit, /usr/bin/systemd-run, /usr/bin/systemctl and /usr/bin/tar, an active systemd user manager 254 or newer, and unified cgroup v2 with delegated memory, pids and cpu controllers
|
||||
# FE-GATE-013 runner requirement: unprivileged user and network namespaces for bwrap (the provider sandbox runs bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net); Ubuntu 23.10 and later refuse them while kernel.apparmor_restrict_unprivileged_userns=1 unless /usr/bin/bwrap has an AppArmor profile that allows userns; scripts/check-system-test-prerequisites.ts probes this before test:system runs
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 45
|
||||
strategy:
|
||||
@@ -205,6 +207,20 @@ jobs:
|
||||
name: "release-candidate-${{ gitea.run_id }}-${{ gitea.run_attempt }}"
|
||||
path: ".release/release-candidate-${{ gitea.run_id }}-${{ gitea.run_attempt }}.tar.gz"
|
||||
if-no-files-found: error
|
||||
- name: Upload immutable gate evidence
|
||||
if: always()
|
||||
uses: https://github.com/ChristopherHX/gitea-upload-artifact@81f940d004763f986ba3582c007fd842dd5cb0d7
|
||||
with:
|
||||
name: "immutable-gate-evidence-${{ gitea.run_id }}-${{ gitea.run_attempt }}"
|
||||
path: |
|
||||
artifacts/quality/gates/FE-GATE-015.txt
|
||||
artifacts/release/release-candidate.json
|
||||
artifacts/release/verification.json
|
||||
artifacts/security/supply-chain-coherence.json
|
||||
artifacts/quality/gates/FE-GATE-027.txt
|
||||
artifacts/release/deployment-admission.json
|
||||
artifacts/security/dependency-advisories.json
|
||||
if-no-files-found: error
|
||||
|
||||
vulnerability_provider:
|
||||
name: external-vulnerability-provider
|
||||
|
||||
+16
-1
@@ -11,7 +11,22 @@
|
||||
- 괄호 안 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다. `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'`).
|
||||
|
||||
## 미출시 — `752a61f` → 브랜치 `fix/maturity-review-2026-11-03`
|
||||
## 미출시 — `409d72e` → 브랜치 `fix/maturity-review-2026-11-05`
|
||||
|
||||
2026-11-05 성숙도 리뷰(`docs/reviews/2026-11-05-maturity-review/`) 조치다. 범위는 `main` `409d72e`(아래 절의 묶음을 합친 커밋)부터 이 브랜치의 끝까지다. 아래 절을 아직 받지 않은 프로젝트는 아래 절부터 받는다.
|
||||
|
||||
### 보안·계약 변경
|
||||
|
||||
| 표시 | 변경 | 영향 경로 | 커밋 |
|
||||
|---|---|---|---|
|
||||
| [계약] | FE-GATE-013(`test:system`) 러너는 비특권 user namespace와 network namespace를 허용해야 한다(provider 샌드박스의 `bwrap --unshare-net`). 사전 점검이 bwrap을 실제로 띄워 보고, 허용하지 않는 호스트에서는 provider 테스트를 돌리기 전에 이유·호스트 설정·고치는 방법을 적고 멈춘다. 요구는 러너 요구 목록, gate 정의의 `hostRequirements`, workflow 주석에 있다 (1105/12-01) | `scripts/check-system-test-prerequisites.ts`, `scripts/lib/provider-sandbox-namespaces.ts`, `config/ci/gates.json`, `docs/operations/ci-quality-gates.md` | `9655958` |
|
||||
| [계약] | release job `immutable_build`가 FE-GATE-015·027의 gate 로그·evidence와 의존성 advisory 기록을 결과와 상관없이 `immutable-gate-evidence-<run>-<attempt>`로 올린다. 후보 archive와 그 upload는 그대로다 (1105/13-01) | `scripts/generate-ci-workflow.ts`, `scripts/contracts/ci-gates.ts`, `.gitea/workflows/quality-gates.yml` | `629c713` |
|
||||
|
||||
### 그 밖의 수정
|
||||
|
||||
- 테스트: 제품 확장 타입 검사 탐침이 복사본의 `product-contracts.ts`·`product-composition.ts`를 덮어쓰지 않고 덧붙인다. 기능이 제품 capability를 쓰는 다운스트림에서도 FE-GATE-005가 통과한다 (1105/09-01, `397664e`)
|
||||
|
||||
## 미출시(`main` `409d72e`에 합침) — `752a61f` → 브랜치 `fix/maturity-review-2026-11-03`
|
||||
|
||||
한 번의 동기화로 받는 변경의 순 요약이다. 범위는 `main` `752a61f`부터 브랜치 `fix/maturity-review-2026-11-03`의 끝까지다. 이 절을 쓸 때 끝은 `f887817`이었다(병합 커밋을 빼고 310개). 그 뒤 깨끗한 clone 검증(merge 단계 14개)에서 찾은 수정과 pin 갱신을 더했다. 버전 번호와 태그는 아직 정하지 않았다.
|
||||
|
||||
|
||||
@@ -328,7 +328,10 @@ tags. The Git host of this repository may not have Actions enabled, so a pull
|
||||
request can show no gate status at all; no status is not a pass. Until the
|
||||
host runs the workflow and marks the merge gates as required checks, run the 14
|
||||
merge gates locally before merging (FE-GATE-008 and 009 need Playwright
|
||||
browsers; FE-GATE-012 builds the app first). Product checks listed in
|
||||
browsers; FE-GATE-012 builds the app first; FE-GATE-013 needs a Linux host where
|
||||
bubblewrap may create unprivileged user and network namespaces, which Ubuntu
|
||||
23.10 and later refuse by default — its first step says so, and
|
||||
`docs/operations/ci-quality-gates.md` lists the fixes). Product checks listed in
|
||||
`config/ci/product-gates.json` (`PRODUCT-GATE-NNN`) run in the workflow's own
|
||||
`product_merge_gate` job:
|
||||
|
||||
|
||||
+20
-1
@@ -2036,7 +2036,11 @@
|
||||
"artifact-artifacts-security-supply-chain-fixtures-json",
|
||||
"artifact-artifacts-security-supply-chain-provider-fixtures-json"
|
||||
],
|
||||
"retentionClassId": "release-coherence"
|
||||
"retentionClassId": "release-coherence",
|
||||
"hostRequirements": [
|
||||
"Linux with executable /usr/bin/bwrap (with --size), /usr/bin/prlimit, /usr/bin/systemd-run, /usr/bin/systemctl and /usr/bin/tar, an active systemd user manager 254 or newer, and unified cgroup v2 with delegated memory, pids and cpu controllers",
|
||||
"unprivileged user and network namespaces for bwrap (the provider sandbox runs bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net); Ubuntu 23.10 and later refuse them while kernel.apparmor_restrict_unprivileged_userns=1 unless /usr/bin/bwrap has an AppArmor profile that allows userns; scripts/check-system-test-prerequisites.ts probes this before test:system runs"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "FE-GATE-014",
|
||||
@@ -2504,6 +2508,21 @@
|
||||
"paths": [
|
||||
".release/release-candidate-${{ gitea.run_id }}-${{ gitea.run_attempt }}.tar.gz"
|
||||
]
|
||||
},
|
||||
{
|
||||
"kind": "upload",
|
||||
"transferId": "immutable-gate-evidence",
|
||||
"name": "immutable-gate-evidence-${{ gitea.run_id }}-${{ gitea.run_attempt }}",
|
||||
"paths": [
|
||||
"artifacts/quality/gates/FE-GATE-015.txt",
|
||||
"artifacts/release/release-candidate.json",
|
||||
"artifacts/release/verification.json",
|
||||
"artifacts/security/supply-chain-coherence.json",
|
||||
"artifacts/quality/gates/FE-GATE-027.txt",
|
||||
"artifacts/release/deployment-admission.json",
|
||||
"artifacts/security/dependency-advisories.json"
|
||||
],
|
||||
"always": true
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
@@ -163,7 +163,12 @@ Release tier의 `immutable_build`는 `dist`의 hidden `.vite` entries, raw
|
||||
번 생성해 run ID/attempt로 구분된 archive로 게시한다. Raw lock bytes의 SHA-256은
|
||||
dependency inventory와 candidate manifest 양쪽의 `lockfileSha256`과 같아야 한다.
|
||||
Producer는 게시 전에 manifest가 선언한 exact member set과 각 byte digest를
|
||||
검증하고 archive SHA-256을 job output으로 고정한다. Vulnerability/provenance
|
||||
검증하고 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에만 쓰고 콘솔에는 한 줄만
|
||||
남기므로, release 단계의 실패 이유는 이 산출물에서 읽는다. 후보 archive의 member
|
||||
set은 그대로다. Vulnerability/provenance
|
||||
provider job은 같은 archive를 각각 내려받아 output SHA-256과 exact member set을
|
||||
확인한 뒤 checkout과 분리된 root에만 추출하고, `CANDIDATE_LOCKFILE_PATH`와
|
||||
`CANDIDATE_DIST_SHA256`를 외부 command에 전달한다. Provider command 실행 후에는
|
||||
@@ -188,6 +193,46 @@ trust/archive/path 같은 host-side preflight 실패는 raw report 생성 전에
|
||||
만든 뒤 scope 안에서만 확정할 수 있으며, 이 단계의 실패는 해당 inode를
|
||||
identity-bound cleanup하고 fail closed한다.
|
||||
|
||||
**비특권 user namespace (1105/12-01).** runner는 비특권 process가 bubblewrap으로
|
||||
user namespace와 network namespace를 만들 수 있게 허용해야 한다. provider
|
||||
sandbox는 `bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net`으로
|
||||
뜬다(`scripts/lib/provider-sandbox-namespaces.ts`). bubblewrap은 setuid가 아니므로
|
||||
이 옵션마다 비특권 user namespace가 필요하다. 이 조건은 provider job과 merge
|
||||
게이트 FE-GATE-013(`test:system`의 provider 테스트) 둘 다에 걸린다.
|
||||
`config/ci/gates.json`의 FE-GATE-013 `hostRequirements`에 같은 조건이 있고,
|
||||
생성 workflow는 그것을 merge job의 `runs-on` 옆 주석으로 보여 준다.
|
||||
|
||||
- Ubuntu 23.10부터는 `kernel.apparmor_restrict_unprivileged_userns=1`이
|
||||
기본이다(24.04도 같다). `/usr/bin/bwrap`에 `userns`를 허용하는 AppArmor
|
||||
profile이 없으면 bwrap이
|
||||
`bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`로 끝난다.
|
||||
- `test:system`은 먼저 `scripts/check-system-test-prerequisites.ts`를 돈다. 이
|
||||
검사는 provider와 같은 namespace 옵션으로 bwrap에서 `/bin/true`를 한 번
|
||||
띄운다. 실패하면 "this host does not allow unprivileged user and network
|
||||
namespaces"와 bwrap의 stderr, 위 sysctl 값, 고치는 방법을 적고 exit 1로
|
||||
멈춘다. 전에는 이 검사가 PASS를 낸 뒤 provider 테스트가 bwrap 원문 오류로
|
||||
실패했다(2026-11-05 desktop에서 114건 중 18건).
|
||||
- 고치는 방법은 셋 중 하나다. 호스트의 보안 설정을 바꾸는 일이므로 호스트
|
||||
소유자가 고른다.
|
||||
1. `/usr/bin/bwrap`에 `userns`를 허용하는 AppArmor profile을 둔다. Ubuntu
|
||||
문서가 안내하는 형태는 아래와 같다. `/etc/apparmor.d/bwrap`에 두고
|
||||
`sudo apparmor_parser -r /etc/apparmor.d/bwrap`으로 읽게 한다.
|
||||
2. 직접 관리하는 호스트라면 sysctl
|
||||
`kernel.apparmor_restrict_unprivileged_userns=0`으로 제한을 끈다. 이 설정이
|
||||
없는 커널에서는 `kernel.unprivileged_userns_clone=1`이 같은 역할이다.
|
||||
3. 비특권 user namespace를 허용하는 다른 runner에서 FE-GATE-013과 provider
|
||||
job을 돌린다.
|
||||
|
||||
```text
|
||||
abi <abi/4.0>,
|
||||
include <tunables/global>
|
||||
|
||||
profile bwrap /usr/bin/bwrap flags=(unconfined) {
|
||||
userns,
|
||||
include if exists <local/bwrap>
|
||||
}
|
||||
```
|
||||
|
||||
각 provider는 고유한 collected user scope에서 실행된다. Supervisor는 실행 전에
|
||||
실제 cgroup membership과 `memory.max=1073741824`, `memory.swap.max=0`,
|
||||
`pids.max=64`, `cpu.max="100000 100000"`을 확인한다. 내부 process에는 core 0,
|
||||
@@ -485,6 +530,11 @@ Repository variables required by higher tiers:
|
||||
findings) or `UNVERIFIED` (no registry). It never fails the gate, because an
|
||||
advisory database that changes under unchanged code would break releases;
|
||||
the signed verdict of the vulnerability provider still decides promotion.
|
||||
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,
|
||||
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
|
||||
(`update:dependency-baseline`).
|
||||
|
||||
@@ -0,0 +1,281 @@
|
||||
# 영역 01 — adapters: browser-transfer
|
||||
|
||||
> 검토일 2026-11-05 · 기준 `8a44226`(`8a4422624e81e5d13a3809e212e826ff75aac62b`, 브랜치 `fix/maturity-review-2026-11-03`) · 가이드 `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`(1103/01-01 수정, 지난 README 14.2 D1)
|
||||
> 짝 백엔드: `clean-architecture-backend-template` `45d2a478`(읽기만. `config/contracts/backend-contract-pin.json:5`의 pin)
|
||||
> 깊게 본 관점: 6, 10, 17, 20, 21, 23, 28
|
||||
> 영역 판정(35.8): presigned 실행기·vault는 **지정 범위에서 사용 가능**. resumable upload runtime은 **조건부 사용 가능**(제품 backend가 `PRESIGNED_MULTIPART_V1` BFF를 직접 만들 때). 짝 백엔드와 함께 파일 업로드를 출시하는 용도는 **조건부 사용 가능**(Fileserver client. 조건: 재개 없음, 파일 전체를 메모리에 읽음, 202 `REJECTED`를 읽지 못함(01-01), 504 `TRANSFER_TIMEOUT`을 자동 재전송하지 않음(01-02), `MAYBE_APPLIED` 뒤 재전송은 파일이 둘 생길 수 있음(백엔드가 키를 읽지 않음), 실제 짝 백엔드로 올려 본 적 없음). image CDN runtime은 **지정 범위에서 사용 가능**(reference runtime 범위).
|
||||
|
||||
ID 표기: 이번 라운드 새 발견은 `01-01`부터 쓴다. 라운드 밖에서는 `1105/01-01`이다. 지난 라운드는 `1103/01-01`(2026-11-03), 그 전은 `1101/…`, `0929/…`다.
|
||||
|
||||
## 0. 결론
|
||||
|
||||
- **1103/01-01(High·P1)은 일부 고쳐졌다.** 프론트에 짝 백엔드 Fileserver `POST /v1/files` client가 생겼다(`src/adapters/http/fileserver-upload.ts`). 요청 모양, 파트 이름, Envelope 성공·실패 본문, 크기 상한, `Retry-After`, 멱등 키 처리를 백엔드 `45d2a478` 코드와 대조했고 주된 경로는 맞다(2.1절). 프론트 문서 넷은 "presigned 레시피는 짝이 아니다"와 이 client를 가리킨다. 남은 것: 실제 짝 백엔드로 올려 본 증거가 없다(테스트는 MSW뿐), 백엔드 매뉴얼에는 안내가 없다(백엔드 repo 몫), 백엔드가 멱등 키를 읽지 않는다(백엔드 결정). 지난 README 14.4의 "고침"은 완료 기준("두 매뉴얼이 그 경로를 가리킨다")에 못 미친다.
|
||||
- **새 Medium 01-01.** 백엔드는 동기 검증에서 거절된 파일을 202 `state: "REJECTED"`로 답한다. 기본 검증기 사슬에서는 0바이트 파일 하나로 닿는다. client의 schema에는 `REJECTED`가 없어 `SCHEMA_MISMATCH`(지원 문의 문구)로 끝난다(XB). 매뉴얼은 202를 "아직 검사 중"으로 적는다. 실제 202의 대부분은 `QUARANTINED`다.
|
||||
- **새 Medium 01-02.** client는 504 `TRANSFER_TIMEOUT`을 `NOT_APPLIED`·`retryable:true`·`retryAfterMs:5000`으로 준다(XF). 매뉴얼대로면 기능이 5초 뒤 다시 올린다. 백엔드는 이 code를 작업 단계와 상관없이 대기 스레드에서 낸다. 작업 스레드가 게시·커밋 중이면 늦게 끝날 수 있다. client 주석의 "게시 전에 나는 code"라는 근거가 이 줄에는 맞지 않는다. 같은 client의 효과 표는 V3 표·계약 문서 6.1과도 갈라졌다(`IDEMPOTENCY_UNAVAILABLE`, Fileserver 4xx). pin 대조 밖이다.
|
||||
- **새 Low 2건.** client가 실패 Envelope의 `traceId`를 버린다(01-03, V3는 1103/03-06에서 싣게 됐다). client 규칙 셋을 테스트가 고정하지 않는다: 바이트 비례 deadline, 읽기 전 크기 거절, 5xx `NOT_APPLIED` code 둘(01-04, 변이 FS4·FS5·FS8 생존).
|
||||
- **지난 발견 재판정.** 고쳐짐 5건(1103/01-02, 1103/01-03, 1101/01-02, 0929/01-02, resumable spec 포트 고정). 일부 1건(1103/01-01). 남음 4건(1101/01-03, 0929/01-03, 0929/01-04, 0929/01-05)과 FOLLOW-UP 4건. 1103/01-03의 생존 변이 N2·N10·N17은 이번에 모두 잡혔다. N10은 네 라운드 만에 처음 잡혔다.
|
||||
- **이 영역 수정이 검사를 약하게 만든 곳은 없다.** 테스트 diff는 단언 추가뿐이다. 바뀐 기대값 하나(422 `IDEMPOTENT_REQUEST_MISMATCH`)는 08-05에 맞춘 재정의다(2.2절).
|
||||
- 실행: desktop 1회(`01-mutations`). 기준 실행 17파일 330건 통과. 변이 14건 중 11건 검출. 복원 `restored: clean at 8a442262`.
|
||||
|
||||
## 1. 범위 (36.1)
|
||||
|
||||
| 항목 | 기록 |
|
||||
| --- | --- |
|
||||
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`. `src/adapters/browser-transfer/` 27파일 12,919줄. 포트 `src/application/ports/browser-transfer/` 5파일 821줄. 새 client `src/adapters/http/fileserver-upload.ts` 735줄과 배럴 export(`src/adapters/http/index.ts:44-56`). 단위 테스트 15파일 + fixture 3파일 11,865줄, 통합 테스트 `tests/integration/fileserver-upload.test.ts` 557줄 |
|
||||
| 커밋·작업 상태·확인 시점 | `8a44226`. 노트북 worktree에서 읽기만 했다. 실행은 desktop checkout(같은 커밋)에서 helper로 했다. `e40684b..8a44226`의 이 영역 커밋: `3af2c8ea`(1103/01-03 테스트), `c695898a`(1103/01-02), `af4ebacb`(1103/01-01 문서), `274ae690`(1101/01-02), `af7d0b18`(0929/01-02), `f8005493`(Fileserver client), `ed499736`(spec 포트), `20a5b084`(422 재분류), `3d3d6527`(client 입력 타입). 영역·포트·client 4파일 +792/−16 |
|
||||
| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. file-transfer 레시피는 `productionComposition: false`(`config/recipes/frontend-capability-recipes.json:155-200`). Fileserver client는 레시피가 아니라 http adapter 배럴 export이고, 제품이 capability로 넘겨 기능 adapter가 만든다(`docs/manual/02-decision-tables.md:326-389`) |
|
||||
| 필수 요구와 규모·운영 목표 | 사용자 목표: 짝 백엔드 템플릿과 함께 서비스를 빨리 출시한다. 업로드 크기·실패율 목표는 없다. 백엔드 기본 상한(`max-file-size 100MB`, `fileserver.yml:12-13`)과 프론트 기본 정책값(`runtime-policy.ts:60-81`)을 사실상의 목표로 보았다 |
|
||||
| 읽은 코드·구성 범위 | 전부: `fileserver-upload.ts`, 그 통합 테스트, `e40684b..8a44226` 영역 diff 전부, 매뉴얼 02 7절(`:273-396`). 필요한 부분: `resumable-upload-runtime.ts`(`stripProviderFailure`와 호출 9곳, 재조정, 스트림 해시), `presigned/http-common.ts:154-212`, `fetch-json-transport.ts:155-170`, `:560-592`, `backend-envelope.ts:118-135`, `:246-290`, `http-execution-v3.ts:1708-1725`, 계약 문서 `backend-api-and-server-state-contract.md:202`, `:308`. **짝 백엔드**(`45d2a478`): `docs/fileserver/http-contract.md` 전체, `docs/web/http-contract.md` 1·2절, `docs/storage-capability-boundary.md`, `FileUploadController.java`, `MultipartUploadRequestMapper.java`, `UploadedFileResponse.java`, `UploadFileApplicationUseCase.java`, `FinalizeUploadApplicationUseCase.java:114-135`, `:296-343`, `:360-423`, `BlockingTransferExecutor.java`, `FileserverExceptionHandler.java`, `FileserverProblemHeaders.java`, `FileserverErrorCode.java`, `FileserverFailureContext.java`, `AmbiguousCompletionException.java`, 검증기 사슬(`FileserverVerificationConfiguration.java:44-57`, `LengthVerifier.java`, `MediaTypeVerifier.java`), `EnvelopeBodyAdvice.java`, `WebAdapterAutoConfiguration.java:53`, `GlobalExceptionHandler.java:281-290`, `CorsExposedHeaders.java`, `fileserver.yml`, `FileserverCompositionIntegrationTest.java` |
|
||||
| 읽은 문서(주장) | 지난 영역 문서와 README 12·13·14절, 커밋 본문 9개, `server-file-capability-infrastructure.md:1-19`, `presigned-transfer-and-image-cdn.md:14-23`, `:392-397`, `:759-764`, `docs/manual/02-decision-tables.md` 4·7절, CHANGELOG 미출시 절(`:190`, `:241`, `:249`) |
|
||||
| 수행한 테스트·실험 | **실행 환경 = desktop**(`/tmp/claude-gates/r4/exp.sh`, 공유 잠금). 실행 이름 `01-mutations` 1회: ① 기준 실행 — 영역 단위 15파일 + Fileserver 통합 1파일 + 실험 파일 1개, 17파일 330건 통과 ② 실험 XA~XF(`tests/integration/zz-area01-exp.test.ts`, 실행 안에서만 만들고 지움) ③ 변이 14건(6절). 이 실행은 19:46에 시작해 `restored: clean at 8a442262`로 끝났다. 19:55의 helper 종료·대기열 취소(BRIEF-2) 전이다. 그 뒤 따로 돌린 것은 없고 배치 요청도 없다. 오케스트레이터 결과(`desktop:/tmp/claude-gates/r4/`, 6절 끝): `check:architecture`·`check:types`·`lint`·`test:unit`·`test:integration` rc=0, merge FE-GATE-001~007·020 rc=0 |
|
||||
| 실험 조건 | node vitest + MSW. 출하 client를 그대로 만들고 백엔드 응답만 흉내 냈다. 응답 모양은 백엔드 `45d2a478` 코드에서 읽은 것이다(문서가 아니라 코드). 실제 백엔드·브라우저·네트워크는 쓰지 않았다 |
|
||||
| 확인하지 못한 범위·이유 | 짝 백엔드를 띄운 업로드(백엔드 repo는 읽기만, helper는 프론트 checkout용). 실제 배포에서 Fileserver 성공 본문이 Envelope로 감싸지는지(정적으로만 확인, 2.1절 3행). 0바이트 파일이 백엔드 append·finalize를 끝까지 지나는지(막는 검사가 코드에 없음을 읽었다). `TRANSFER_TIMEOUT` 뒤 작업이 늦게 끝나는 경쟁(재현 안 함). 실제 브라우저에서 Fileserver client(spec 없음). resumable 경로의 실패 뒤 재개·두 탭 경쟁(브라우저 spec은 정상 경로뿐, 이번에 돌리지 않음) |
|
||||
| 이전 리뷰와 비교 가능한 범위 | 지난 발견은 지금 코드와 이번 실행으로 다시 판정했다. 지난 라운드의 X1~X5, N1~N18, 265건, 번들 측정은 증거로 쓰지 않았다. 이번 N2·N10·N17은 지난 변이와 같은 자리를 같은 방식으로 바꿨다 |
|
||||
|
||||
## 2. 지난 발견 재확인
|
||||
|
||||
| 지난 ID | 내용 | 상태 | 근거 |
|
||||
| --- | --- | --- | --- |
|
||||
| 1103/01-01 (High·P1) | 두 템플릿을 짝으로 쓰면 파일 업로드가 연결되지 않는다 | **일부** | 고친 것: client `createFileserverUploadClient`(`src/adapters/http/fileserver-upload.ts:181-275`), 배럴 export(`src/adapters/http/index.ts:44-56`), 문서 넷(`server-file-capability-infrastructure.md:3-19`, `presigned-transfer-and-image-cdn.md:14-23`, 레시피 fallback `frontend-capability-recipes.json:199`, 매뉴얼 `02-decision-tables.md:273-396`). 백엔드 코드와 대조한 결과는 2.1절이다. 남은 것: ① 완료 기준의 "두 매뉴얼" 중 백엔드 매뉴얼에 안내가 없다(`docs/manual/`에 Fileserver·업로드 짝 언급 0건, 백엔드 repo 몫) ② 검증 방법 "짝 백엔드를 띄우고 업로드"를 하지 않았다. 테스트는 MSW이고, 그 MSW가 백엔드 문서에서 왔다(`tests/integration/fileserver-upload.test.ts:14-19`). 그래서 백엔드 코드의 202 `REJECTED`를 놓쳤다(새 01-01) ③ 백엔드 `POST /v1/files`가 멱등 키를 읽지 않는다(`UploadFileApplicationUseCase.java:38-41` `NOT_IDEMPOTENT`, 컨트롤러에 키 처리 없음). 프론트는 이를 적었다(`fileserver-upload.ts:93-99`, 매뉴얼 `:320-324`). 남은 부분은 High가 아니다. "연결되지 않는다"는 고쳐졌고, 남은 것은 연동 미검증과 새 발견 01-01·01-02다 |
|
||||
| 1103/01-02 (Medium·P2) | 상한을 넘는 `Retry-After`에 part 단계가 `retryable:true`를 준다 | **고쳐짐** | `stripProviderFailure`가 정책을 받아 상한 밖이면 `retryable:false`로 만든다(`resumable-upload-runtime.ts:1683-1705`). 호출 9곳이 모두 정책을 넘긴다(`:575`, `:676`, `:999`, `:1079`, `:1083-1086`, `:1136`, `:1251`, `:1316`). 테스트: part 두 단계 × 429·503(`resumable-upload-runtime-recovery.test.ts:332-389`), transport 상한 30초·60초 두 조합(`:397-462`). 완료 기준(X1a·X1b `false`, X1d·X1f 같은 답)을 테스트가 그대로 본다. 변이 M0102(수정 되돌림) 5건 실패 — 검출. 남은 차이: 헤더 없는 part 단계 429는 backoff 뒤 `retryable:true`, control plane은 `false`다. 커밋 `c695898a` 본문이 범위 밖으로 적었고 완료 기준에도 없다(관점 23에 남김) |
|
||||
| 1103/01-03 (Low·P3) | `Retry-After`·멱등 키 규칙 세 개를 테스트가 고정하지 않는다 | **고쳐짐** | 테스트 셋이 더해졌다: 503 행(`resumable-upload-runtime-recovery.test.ts:333-338`), abort 키 재사용(`:625-666`), transport 헤더 없는 429(`resumable-upload-fetch-transport.test.ts:322-347`). 완료 기준대로 다시 돌렸다: N2 4건, N10 1건, N17 1건 실패 — 모두 검출 |
|
||||
| 1101/01-02 (Low·P3) | `FILE_BYTE_SOURCE` 재개가 수락된 part까지 다시 해시한다 | **고쳐짐** | 수락 확인이 검증 앞으로 왔다(`resumable-upload-runtime.ts:881-883`). 테스트가 part 크기 digest 수 10을 본다(`resumable-upload-runtime-recovery.test.ts:1374-1459`). 변이 N11r(되돌림) 1건 실패 — 검출. 수락된 part는 보내지 않으므로 검증을 빼도 서버 객체는 manifest와 같다 |
|
||||
| 1101/01-03 (Low·P3) | 메모리 상한 식의 copyFactor가 설정값이다 | 남음 | `runtime-policy.ts:12`, `:68`, `:101-107`. 바뀌지 않았다 |
|
||||
| 0929/01-02 (Low·P3) | 재조정 경로에서 checkpoint 삭제가 실패하면 resourceId를 버린다 | **고쳐짐** | 삭제 결과와 상관없이 `{QUARANTINED, resourceId, replayed:true}`를 준다(`resumable-upload-runtime.ts:584-598`). 테스트가 남은 행과 다음 호출의 정리까지 본다(`resumable-upload-runtime-recovery.test.ts:757-802`). 문서도 고쳤다(`presigned-transfer-and-image-cdn.md:392-397`). 변이 N18(되돌림) 1건 실패 — 검출 |
|
||||
| 0929/01-03 (Low·P3) | 느린 업링크 설정이 runtime 정책과 실행기에 따로 있다 | 남음 | `resumable-upload-runtime.ts:1047`, `presigned-transfer-executor.ts:140-145`. Fileserver client도 같은 기본값을 글자로 복사했다(`fileserver-upload.ts:141-142`). 다른 경로라 이 발견의 범위를 넓히지는 않는다 |
|
||||
| 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:103-133`). 닫힌 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`는 `e40684b` 뒤 바뀌지 않았다(`:196`, `:311`, `:383`이 `publicAsset()`) |
|
||||
| FOLLOW-UP: `resumable-upload.spec.ts` `PAGE_ORIGIN` 포트 고정 | — | **고쳐짐** | 설정의 `baseURL`에서 읽는다(`tests/browser-capabilities/resumable-upload.spec.ts:5-10`, `ed499736`) |
|
||||
| 1103/01-02 함께 볼 것: object store CORS의 `Retry-After` expose가 handoff 문서에 없다 | — | 남음 | `server-file-capability-infrastructure.md:1668-1673`은 receipt 헤더만 적는다. 짝 백엔드는 자기 응답에 expose한다(`CorsExposedHeaders.java:27-36`) |
|
||||
| 1103 D3: `issuePartCapability` 포트 주석에 "`PERMISSION_DENIED`는 `NONE`" 한 줄 | — | 안 함 | `resumable-upload.ts:215`에 주석이 없다. 결정 권고였고 발견은 아니다 |
|
||||
|
||||
1103 라운드의 이 영역 발견은 README 12절의 3건(01-01·01-02·01-03)이다. 10.3절에 합친 항목과 13절 추가는 이 영역에 없다.
|
||||
|
||||
### 2.1 1103/01-01 수정을 짝 백엔드 `45d2a478` 코드와 대조
|
||||
|
||||
| 항목 | 짝 백엔드(코드) | 프론트 client | 판정 |
|
||||
| --- | --- | --- | --- |
|
||||
| 경로·요청 | `POST /v1/files`, `consumes multipart/form-data`, `produces application/json`(`FileUploadController.java:98-103`) | base 아래 `v1/files`(`fileserver-upload.ts:307-310`), `content-type: multipart/form-data; boundary=…`, `accept: application/json`(`:227-234`) | 맞다 |
|
||||
| 파트·파일 이름·타입 | `@RequestParam("file")`. 이름이 비면 `upload.bin`. part의 Content-Type은 주장이다(`MultipartUploadRequestMapper.java:18-33`). `application/octet-stream` 주장은 검증기가 받아들인다(`MediaTypeVerifier.java`의 `FALLBACK`) | 파트 `file`, 기본 이름 `upload.bin`, 기본 타입 `application/octet-stream`(`:139-147`, `:440-444`). 이름의 `"`·CR·LF는 escape(`:434-438`) | 맞다 |
|
||||
| 성공 본문 | 컨트롤러는 `UploadedFileResponse` 7필드를 돌려준다(`UploadedFileResponse.java:11-29`). 배포 구성에서는 `EnvelopeBodyAdvice`가 감싼다(`WebAdapterAutoConfiguration.java:53`, `EnvelopeBodyAdvice.java:76-93`) | `readSuccessEnvelope` 뒤 7필드 schema, 모르는 필드는 버림(`:191-202`, `:621-635`) | 정적으로 맞다. 백엔드 자신의 조립 테스트는 advice 없는 좁은 context에서 감싸지 않은 모양을 읽는다(`FileserverCompositionIntegrationTest.java:217`, `:486-505`). 실제 감싸짐을 본 테스트는 두 repo에 없다(미검증) |
|
||||
| 201·202 | `READY`면 201, 그 밖의 모든 state는 202(`FileUploadController.java:195-200`). 업로드는 동기 검증이다(`FinalizeUploadRequest(…, false)`, `:185`). 그래서 202는 `QUARANTINED`(이름·타입 불일치·스크립트), `REJECTED`(악성 아닌 거절), `VERIFYING`(검증기 RETRY)이다(`FinalizeUploadApplicationUseCase.java:300-343`). 문서는 "202 VERIFYING"만 적는다(`docs/fileserver/http-contract.md:10`) | enum `READY`·`UPLOADED`·`VERIFYING`·`QUARANTINED`(`:194`), 201⇔`READY` 검사(`:627`) | **어긋남** — 202 `REJECTED`를 읽지 못한다(새 01-01) |
|
||||
| 크기 상한 | servlet `max-file-size 100MB`·`max-request-size 110MB`가 Fileserver 정책과 같은 placeholder다(`fileserver.yml:12-13`, `:55-56`). servlet 상한은 413 `PAYLOAD_TOO_LARGE`(`GlobalExceptionHandler.java:281-290`), 선언 길이 정책은 413 `FILE_TOO_LARGE`(`CreateUploadApplicationUseCase.java:172-176`). 0바이트는 `LengthVerifier`가 REJECT(`LengthVerifier.java:35-36`) | `maxFileBytes` 필수, 기본값 없음(`:338`). 선언 크기가 크면 읽기 전에 `FILE_TOO_LARGE`(`:424-428`). 413·415·422(불일치 제외)는 `VALIDATION_REJECTED`(`:663-667`). 하한은 없다(XA: 0바이트도 보낸다) | 대체로 맞다. 서버 413 code는 둘인데 주석은 "server's code for the same refusal"(`:426`)이라 적는다(XD). 0바이트는 새 01-01 |
|
||||
| 멱등 키 | 업로드 use case는 `NOT_IDEMPOTENT`이고 executor를 거치지 않는다(`UploadFileApplicationUseCase.java:38-41`). 키 헤더는 무시된다 | 키가 있으면 `Idempotency-Key` 헤더로 보낸다(`:231-233`). 스스로 다시 보내지 않는다(`:53-54`). 백엔드가 읽지 않는다고 적었다(`:93-99`, 매뉴얼 `:320-324`) | 맞게 적었다. 재전송 중복 위험은 백엔드 결정으로 남는다 |
|
||||
| 실패 본문·효과 | Envelope + `details.ambiguous`·`reconciliationRequired`(`FileserverExceptionHandler.java:52-66`). 모호하지 않은 실패는 업로드를 취소한다(`UploadFileApplicationUseCase.java:77-82`). 게시 뒤 실패는 `AMBIGUOUS_COMPLETION`으로 바꾼다(`FinalizeUploadApplicationUseCase.java:405-420`, `AtomicMoveContentPublisher.java:89-95`, `:113-120`). 단, `TRANSFER_TIMEOUT`은 대기 스레드가 작업 단계와 상관없이 낸다(`BlockingTransferExecutor.java:64-79`) | `ambiguous` → `MAYBE_APPLIED`, 4xx → `NOT_APPLIED`, 정한 5xx 여섯 → `NOT_APPLIED`, 그 밖 → `MAYBE_APPLIED`(`:163-179`, `:691-704`) | 단일 업로드에서 대부분 맞다. `TRANSFER_TIMEOUT` 한 줄은 근거가 없다(새 01-02) |
|
||||
| `Retry-After` | 재시도 가능한 409·429·503·504에 code별 초(`FileserverProblemHeaders.java:30-37`, `:48-53`). CORS로 노출(`CorsExposedHeaders.java:27-36`) | 읽고, 상한 30초를 넘으면 버리고 `retryable:false`(`:650-680`) | 맞다. 1103/01-02와 같은 규칙이다 |
|
||||
| 인증·CORS | `file:upload` 권한(`fileserver.yml:23-27`), `access-policy: required`(`:80`), CORS 허용 헤더 `*`(`security.yml:51`) | 인증 프로필의 `credentials`, 프로필이 허락한 증명 헤더만(`:221-226`, `:536-560`) | 프론트 쪽은 맞다. 세션 owner는 09 영역 몫 |
|
||||
| 문서 | — | 상태 줄·안내 넷이 맞게 바뀌었다(위 1행). 남은 틀림: 매뉴얼 `:289`, `:311`이 202를 "`VERIFYING` 등, 아직 검사 중"으로 적는다. SHA 표기가 `bbe944bd`다(`fileserver-upload.ts:38`, `:95`, `:161`, 매뉴얼 `:320`, `:394`). pin은 `45d2a478`이다. 두 SHA 사이 Fileserver main 코드와 `docs/fileserver/http-contract.md`는 바뀌지 않았다(`git diff --stat bbe944bd..45d2a478` 0파일) | 표기만 낡았다. 202 안내는 새 01-01 |
|
||||
|
||||
### 2.2 수정이 검사를 약하게 만들었는가
|
||||
|
||||
`git diff e40684b..8a44226 -- tests/unit/resumable-upload-* tests/unit/presigned-transfer* tests/unit/image-cdn* tests/unit/upload-cancellation* tests/integration/fileserver-upload.test.ts tests/browser-capabilities/resumable-upload.spec.ts`를 읽었다.
|
||||
|
||||
- 지운 단언, 넓힌 허용 목록·정규식, 새 skip, 늘린 시간 제한·예산은 없다. 단위 테스트 2파일은 +309/−10이고, 지운 10줄은 같은 단언을 더 강하게 고친 자리다(`resumable-upload-runtime-recovery.test.ts:374-383`에 `retryable:false`, `recovery` 추가).
|
||||
- 바뀐 기대값 하나: `20a5b084`가 422 `IDEMPOTENT_REQUEST_MISMATCH`를 `VALIDATION_REJECTED`에서 `UNKNOWN_CLIENT_FAILURE`로 바꿨다(`fileserver-upload.test.ts:320`). 08-05(필드 목록 없는 422는 입력 오류가 아니다)에 맞춘 재정의다. 같은 커밋이 그 밖의 422를 파일 거절로 남겨 MALWARE 행(`:319`)은 그대로다. 약화가 아니다.
|
||||
- spec 변경(`ed499736`)은 같은 값을 설정에서 읽게 했을 뿐이다.
|
||||
|
||||
## 3. 이번 발견 (36.3)
|
||||
|
||||
새 발견 4건: Medium 2 · Low 2 / P2 2 · P3 2 / 확인된 결함 3 · 구조적 위험 1. High 이상 0, P1 0.
|
||||
|
||||
### 01-01 Fileserver client가 짝 백엔드의 202 `REJECTED`를 "서버 응답 모양 오류"로 읽는다 — 빈 파일 하나로 닿고, 매뉴얼은 202를 "아직 검사 중"으로 적는다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(두 템플릿 사이 응답 해석 불일치) |
|
||||
| 관련 관점 | 17, 6, 8, 20, 10, 24 |
|
||||
| 근거 | **백엔드.** 업로드는 동기 검증이다(`FileUploadController.java:185`, `FinalizeUploadRequest.java`의 `async=false`). 검증 결과가 REJECT이고 code가 `MALWARE_REJECTED`가 아니면 예외 없이 `REJECTED` `FileView`를 돌려준다(`FinalizeUploadApplicationUseCase.java:300-343`, 백엔드 테스트 `FinalizeUploadApplicationUseCaseTest.java:132-148`). 컨트롤러는 `READY`가 아니면 모두 202다(`FileUploadController.java:195-200`). 기본 검증기 사슬의 첫 검증기는 0바이트를 `REJECT("EMPTY_CONTENT")`로 본다(`LengthVerifier.java:35-36`, 사슬 `FileserverVerificationConfiguration.java:48-56`). REJECT는 다른 판정보다 우선한다(`VerificationVerdict` 주석 "REJECT > QUARANTINE > RETRY > ACCEPT"). 0바이트를 앞에서 막는 검사는 찾지 못했다(`CreateUploadApplicationUseCase.java:172-176`은 상한만 본다). 문서는 202를 `VERIFYING`으로만 적는다(`docs/fileserver/http-contract.md:10`). **프론트.** state enum에 `REJECTED`가 없다(`fileserver-upload.ts:60`, `:194`). schema를 통과하지 못하면 `SCHEMA_MISMATCH`·`APPLIED_CONFIRMED`다(`:624-631`). 0바이트 하한은 없다(`:424-428`). 테스트는 202 `VERIFYING`만 본다(`tests/integration/fileserver-upload.test.ts:183-189`). 그 MSW는 백엔드 문서대로라고 적는다(`:14-19`). 매뉴얼은 "그 밖(202 `VERIFYING` 등)은 서버가 아직 검사 중이다"라고 적는다(`docs/manual/02-decision-tables.md:289`, `:311`). **실험.** XA: 0바이트 파일도 요청 1회를 보낸다. XB: 202 + `state:"REJECTED"` → `{ok:false, kind:"SCHEMA_MISMATCH", code:"UPLOADED_FILE_INVALID", effect:"APPLIED_CONFIRMED", httpStatus:202, userMessageKey:"error.schema_mismatch", action:"none"}`. XC(대조군): 202 `QUARANTINED` → 성공 |
|
||||
| 발생 조건 | 사용자가 빈 파일을 고른다(기본 검증기 사슬). 또는 제품이 악성 아닌 이유로 REJECT하는 검증기를 더한다(예: 서명 검사). 그때마다 닿는다 |
|
||||
| 영향 | 기능은 "이 파일은 거절됐다"를 "서버 계약이 깨졌다"와 구별하지 못한다. 사용자는 파일을 바꾸라는 안내 대신 응답 형식 오류 문구를 본다. `fileId`도 잃는다. 서버에는 공개되지 않은 `REJECTED` 레코드가 남고 정리 작업이 예약된다(`FinalizeUploadApplicationUseCase.java:327-333`). 데이터 손상은 없다. 별도로, 매뉴얼을 따르면 기능은 `QUARANTINED`(동기 검증의 202 대부분)를 "검사 중"으로 보여 준다. 격리 파일은 관리자 결정 전까지 내려받을 수 없으므로 화면이 끝나지 않는 대기가 된다 |
|
||||
| 심각도·우선순위 | Medium · P2 — 지원 구성(짝 백엔드 기본 사슬)에서 닿고 사용자 결과가 틀린다. 범위는 거절되는 파일로 제한되고 데이터 피해는 없다. 1103/01-02(같은 범위의 잘못된 신호, Medium·P2)와 같은 급으로 맞췄다 |
|
||||
| 통제·증거 | 202 state 해석: M2(일부 state만 구현) · `REJECTED`: M0(이 경로를 확인했고 받는 코드가 없다) · E1(두 repo 코드) + E2(XB) |
|
||||
| 확실성과 남은 가정 | 백엔드가 202 `REJECTED`를 내는 경로는 코드와 백엔드 단위 테스트로 확정했다. 0바이트가 append·finalize를 실제로 끝까지 지나는지는 실행하지 않았다(막는 코드를 찾지 못했다). 실제 배포에서 성공 본문이 Envelope로 감싸진다는 전제는 정적 확인이다 |
|
||||
| 결정의 근거 | [확인한 사실] client는 백엔드 `FileState` 일부(`UPLOADED`, `QUARANTINED`)를 문서보다 넓게 받았다. `REJECTED`만 빠졌다. [리뷰어 추론] 202 목록을 백엔드 문서에서 시작해 코드로 일부만 넓힌 결과다. 고를 선택지가 있는 문제라 아래에서 비교한다 |
|
||||
| 이해 비용 | 기능 작성자는 매뉴얼 7절만 보고 202를 "검사 중"으로 처리한다. 실제 202의 뜻을 알려면 백엔드 컨트롤러·finalize·검증기 세 파일을 읽어야 한다 |
|
||||
| 최소 개선 방향 | ① schema가 `REJECTED`를 받고, 202 `REJECTED`를 `VALIDATION_REJECTED` 실패(code `FILE_REJECTED`, `NOT_APPLIED`, `fileId`는 실패에 싣지 않음)로 돌려준다. 422 `MALWARE_DETECTED`를 읽는 방식과 같다 ② 0바이트는 보내기 전에 거절한다(읽기 전 크기 거절과 같은 자리) ③ 매뉴얼 `:289`, `:311`을 "202는 `VERIFYING`(검사 중) 또는 `QUARANTINED`(격리, 내려받기 불가)"로 고친다 |
|
||||
| 대안 비교 | (가) 위 ①②③. (나) `REJECTED`를 성공 state로 그대로 넘긴다 — 타입 변경이 작지만 기능마다 성공 값에서 거절을 다시 찾아야 한다. (다) ②만 — 기본 사슬은 막지만 제품 검증기의 REJECT는 그대로다. (가)를 권한다. 거절을 실패로 주는 것이 413·415·422와 같은 규칙이다 |
|
||||
| 단순화의 보존 조건 | 201⇔`READY` 검사(`:627`), size 일치 검사, 모르는 필드 무시(`:202`)를 유지한다 |
|
||||
| 비용·부작용 | 수십 줄과 테스트 3행. `upload()` 결과가 바뀌므로 CHANGELOG [계약] 한 줄 |
|
||||
| 재검토 조건 | 백엔드가 REJECT를 422로 던지도록 바꾸거나, 202 state 목록을 계약 문서에 적을 때 |
|
||||
| 완료 기준 | 202 `REJECTED`와 0바이트가 `SCHEMA_MISMATCH`가 아니다. 테스트가 202 `QUARANTINED`·`REJECTED`·`VERIFYING`을 각각 본다. 매뉴얼이 `QUARANTINED`의 뜻을 적는다 |
|
||||
| 검증 방법 | 통합 테스트 행 추가. 가능하면 짝 백엔드를 띄워 빈 파일 하나를 올린다 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규(1103/01-01 수정이 만든 결함) |
|
||||
|
||||
### 01-02 Fileserver client가 504 `TRANSFER_TIMEOUT`을 "적용 안 됨, 5초 뒤 다시"로 준다 — 백엔드는 이 code를 작업 단계와 상관없이 대기 스레드에서 내고, 같은 client의 효과 표는 V3 표·계약 문서 6.1과도 갈라졌다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험(늦은 완료로 파일이 둘 생기는 인과 경로가 있고, 재현은 하지 않았다). 표가 갈라진 사실은 확인했다 |
|
||||
| 관련 관점 | 6, 28, 17, 23, 9, 21, 5 |
|
||||
| 근거 | **이 줄.** client는 `TRANSFER_TIMEOUT`을 `NOT_APPLIED_5XX_CODES`에 둔다(`fileserver-upload.ts:163-170`). 근거로 "the backend raises [these] before the file is published"라고 적는다(`:154-161`). 백엔드는 업로드 작업을 전송 풀에 넘기고, 대기 스레드가 `await-seconds`(기본 300초, `fileserver.yml:75`)가 지나면 `future.cancel(true)` 뒤 `TRANSFER_TIMEOUT`(retryable)을 던진다(`BlockingTransferExecutor.java:64-79`). 그 시점에 작업 스레드가 어느 단계인지는 보지 않는다. interrupt는 FileChannel 복사는 멈추지만, 게시(rename)와 READY 커밋(JDBC)은 멈추지 않는다(`FinalizeUploadApplicationUseCase.java:381-423`). 그래서 504 뒤에 파일이 `READY`가 될 수 있다. 백엔드는 이 code에 `Retry-After: 5`를 붙인다(`FileserverProblemHeaders.java:30-37`). **실험 XF**: 504 `TRANSFER_TIMEOUT` → `{kind:"SERVER_FAILURE", effect:"NOT_APPLIED", retryable:true, action:"retry"}`. 매뉴얼은 "`retryable: true`이고 `retryAfterMs`가 있으면 그만큼 기다린 뒤 기능이 다시 부른다"고 적는다(`02-decision-tables.md:318`). 4절 표는 `NOT_APPLIED`의 다음 전송을 "새 멱등 키"로 둔다(`:162-167`). 대조군 XE: 프록시가 준 HTML 504는 `MAYBE_APPLIED`다. **표가 갈라진 곳.** ① `IDEMPOTENCY_UNAVAILABLE`(503): client는 `NOT_APPLIED`(`:169`, 테스트 `fileserver-upload.test.ts:326`). V3 표는 `MAYBE_APPLIED`(`backend-envelope.ts:249-254`). 매뉴얼 4절은 굵은 글씨로 "`NOT_APPLIED`로 분류하지 않는다"(`02-decision-tables.md:187-206`) ② Fileserver 4xx: 계약 문서 6.1은 `MALWARE_DETECTED`·`INTEGRITY_MISMATCH`·`CONCURRENT_MODIFICATION` 등을 "쓰기 뒤 가능, `MAYBE_APPLIED`"로 적는다(`backend-api-and-server-state-contract.md:202`, `:308`). client는 4xx를 모두 `NOT_APPLIED`로 본다(`fileserver-upload.ts:702`, 테스트 `:319`). 두 문서 모두 다른 쪽을 언급하지 않는다 ③ pin 대조(`scripts/check-backend-contract-drift.ts`, `backend-contract-pin.json:5-12`)는 web 계약 §1·2·4와 `backend-envelope.ts`만 본다. Fileserver 계약과 이 표는 밖이다. 매뉴얼은 "백엔드 SHA가 바뀌면 같이 다시 본다"(`:394`)고 적었지만, pin이 `45d2a478`로 올라갈 때(`580be58`) 이 표의 SHA 표기는 `bbe944bd` 그대로다 |
|
||||
| 발생 조건 | 이 줄: 전송 풀이 밀리거나 저장소·DB가 느려 한 업로드의 대기가 300초 경계에 걸리고, 그때 작업 스레드가 게시·커밋 구간에 있다. 기능이 매뉴얼대로 5초 뒤 자동으로 다시 올린다. ①은 배포가 업로드를 멱등성 executor 뒤에 둘 때만 닿는다(client 주석 `:95-98`이 말하는 구성). ②는 누군가 한 표를 다른 표에 맞출 때 |
|
||||
| 영향 | 같은 파일이 두 번 `READY`가 된다. 기능은 두 번째 `fileId`만 안다. 첫 파일은 참조 없이 저장 공간과 quota를 쓴다. 업무 데이터 손상은 없다. ①②는 지금 짝 백엔드의 `POST /v1/files`에서는 결과가 달라지지 않는다. 대신 같은 백엔드 code의 효과가 템플릿 안에서 세 곳에 따로 적혀 있고 서로 다르다 |
|
||||
| 심각도·우선순위 | Medium · P2 — 가이드 35.2의 "결과 불명 작업의 재실행" 모양이지만 닿는 조건이 좁고(300초 경계의 경쟁), 피해가 중복 파일 하나로 제한된다. 백엔드 자신이 이 code를 retryable로 선언한다는 점도 반영했다. High로 올리지 않았다 |
|
||||
| 통제·증거 | 효과 판정의 단일 출처: M0(세 표가 따로 있고 대조 검사가 없다) · `TRANSFER_TIMEOUT` 행: M2(구현만, 테스트 없음 — 변이 FS4 생존) · E1(두 repo 코드) + E2(XF) |
|
||||
| 확실성과 남은 가정 | 대기 스레드가 단계와 상관없이 504를 낸다는 것과 커밋이 interrupt로 멈추지 않는다는 것은 코드로 확인했다. 실제로 늦게 끝나는 빈도는 재현하지 않았다. multipart 본문은 컨트롤러 전에 다 받으므로(Spring 기본 `resolve-lazily=false`) 풀 작업은 대개 짧다. 그래서 빈도는 낮다고 본다(추론) |
|
||||
| 결정의 근거 | [확인한 사실] client는 백엔드 `UploadFileApplicationUseCase`의 "모호하지 않은 실패는 취소한다"를 근거로 표를 만들었다. 그 근거는 작업 스레드 안의 실패에만 맞다. [기록된 의도] V3 표는 "같은 키로 다시 보낼 것"을 결과 불명으로만 표현할 수 있어 `IDEMPOTENCY_UNAVAILABLE`를 `MAYBE_APPLIED`로 두었다(`backend-envelope.ts:249-250`). client 커밋 `f8005493`은 "효과 판정 표는 백엔드 bbe944bd 기준이다. 어긋남을 알리는 검사는 없다"고 적었다. [리뷰어 추론] 단일 업로드에서 4xx를 `NOT_APPLIED`로 보는 client 쪽 판단은 맞다. 문제는 근거가 다른 세 표가 서로를 모르는 것과, 한 줄이 근거 밖이라는 것이다 |
|
||||
| 이해 비용 | Fileserver 실패의 효과를 알려면 client 표, `backend-envelope.ts` 표, 계약 문서 6.1, 백엔드 `BlockingTransferExecutor`를 함께 읽어야 한다 |
|
||||
| 최소 개선 방향 | ① `TRANSFER_TIMEOUT`을 `NOT_APPLIED_5XX_CODES`에서 빼 `MAYBE_APPLIED`로 둔다(한 줄 + 테스트 행). 백엔드에는 "대기 시간 초과는 작업이 시작됐으면 모호한 결과"를 넘긴다 ② `IDEMPOTENCY_*`는 client가 `backend-envelope.ts`의 판정을 그대로 쓴다 ③ 계약 문서 6.1 fileserver 행에 "`POST /v1/files` 단일 업로드는 use case가 취소하므로 4xx `NOT_APPLIED`(`fileserver-upload.ts`)"를 적는다 ④ client·매뉴얼의 SHA 표기를 pin에 맞추고, pin 대조 대상에 `docs/fileserver/http-contract.md`를 더한다 |
|
||||
| 대안 비교 | (가) ①~④. (나) ①만 — 위험한 줄은 없어지지만 세 표의 갈라짐은 남는다. (다) client 효과 판정을 V3 표로 통째로 바꾼다 — Fileserver 4xx가 모두 결과 불명이 되어 413·415·422 파일 거절의 화면이 나빠진다. (가)를 권한다 |
|
||||
| 단순화의 보존 조건 | `ambiguous` 우선(`:701`), 4xx 파일 거절의 `VALIDATION_REJECTED`(`:663-667`), 상한 밖 `Retry-After` 규칙(`:654-657`)을 유지한다 |
|
||||
| 비용·부작용 | 수 줄과 문서 몇 줄. ①은 504 뒤 화면이 "재시도"에서 "결과 불명"으로 바뀐다 |
|
||||
| 재검토 조건 | 백엔드가 `TRANSFER_TIMEOUT`을 작업 시작 전에만 내도록 고치거나 모호 표시를 붙일 때 ①을 되돌린다. 업로드가 멱등성 executor 뒤로 갈 때 ②를 다시 본다 |
|
||||
| 완료 기준 | 504 `TRANSFER_TIMEOUT`이 `NOT_APPLIED`가 아니다. 같은 백엔드 code의 효과가 client·V3·계약 문서에서 같거나, 다른 이유가 한 곳에 적혀 있다. 변이 FS4가 실패를 만든다 |
|
||||
| 검증 방법 | 통합 테스트 504 `TRANSFER_TIMEOUT` 행. drift 검사 대상 추가 뒤 `check-backend-contract-drift` 실행 |
|
||||
| 담당·기한·상태 | 미정(①의 백엔드 쪽은 백엔드 소유자) · 미정 · 신규(1103/01-01 수정이 만든 결함) |
|
||||
|
||||
### 01-03 Fileserver client가 실패 Envelope의 `traceId`를 버린다 — V3 실행기는 1103/03-06에서 싣게 됐다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(진단 정보 누락, 두 실행 경로 불일치) |
|
||||
| 관련 관점 | 8, 23, 7 |
|
||||
| 근거 | `readFailureEnvelope`는 `meta.traceId`를 함께 돌려준다(`src/adapters/http/backend-envelope.ts:118-135`, `631ce339` "실패 Envelope의 meta.traceId를 AppFailure.traceId로 싣는다"). V3는 그 값을 실패에 싣는다(`http-execution-v3.ts:1712-1721`). client는 `envelope.value`만 넘기고 `envelope.traceId`를 버린다(`fileserver-upload.ts:638-640`). `envelopeFailure`와 `createFailure` 호출에 trace 값이 없다(`:668-676`). XB·XD·XF 결과에도 `traceId`가 없다(MSW가 `meta.traceId: "trace-1"`을 보냈다) |
|
||||
| 발생 조건 | 업로드 실패 하나를 백엔드 로그와 맞춰 볼 때 |
|
||||
| 영향 | 지원 담당이 업로드 실패를 서버 요청과 잇지 못한다. 같은 백엔드의 다른 쓰기 실패는 이을 수 있다 |
|
||||
| 심각도·우선순위 | Low · P3 — 진단 편의. 동작 피해는 없다 |
|
||||
| 통제·증거 | M0(이 경로를 확인했고 싣는 코드가 없다) · E1 + E2(XB 등 결과에 없음) |
|
||||
| 확실성과 남은 가정 | 코드와 실험으로 확정했다 |
|
||||
| 결정의 근거 | 적용 제외 — 이미 정한 규칙(1103/03-06)을 이 경로에 적용하는 문제다 |
|
||||
| 이해 비용 | 적용 제외 — 지역 누락이다 |
|
||||
| 최소 개선 방향 | `envelopeFailure`에 `envelope.traceId`를 넘겨 `createFailure`의 `traceId`로 싣는다 |
|
||||
| 대안 비교 | 적용 제외 — 기대 계약이 정해져 있다 |
|
||||
| 단순화의 보존 조건 | 적용 제외 |
|
||||
| 비용·부작용 | 몇 줄과 테스트 단언 하나 |
|
||||
| 재검토 조건 | 적용 제외 |
|
||||
| 완료 기준 | Envelope 실패 결과에 `traceId`가 있다 |
|
||||
| 검증 방법 | 통합 테스트 실패 표에 `traceId` 단언 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
|
||||
### 01-04 Fileserver client 규칙 셋을 테스트가 고정하지 않는다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(테스트 빈틈. 규칙을 바꿔도 48건이 모두 통과한다) |
|
||||
| 관련 관점 | 10, 21, 6, 14 |
|
||||
| 근거 | 변이 세 건이 `tests/integration/fileserver-upload.test.ts` 48건을 모두 통과했다. **FS4**: `ATOMIC_PUBLISH_UNSUPPORTED`·`TRANSFER_TIMEOUT`을 `NOT_APPLIED_5XX_CODES`에서 뺌(`fileserver-upload.ts:163-170`). 테스트 표에 두 code 행이 없다(`:312-329`). **FS5**: deadline에서 바이트 비례 몫을 없앰(`:211-215`). 시간 초과 테스트는 작은 고정값만 본다(`:430-447`). 큰 파일이 느린 망에서 30초에 끊기는 회귀를 못 잡는다. **FS8**: 선언 크기가 `maxFileBytes`보다 큰 파일을 읽기 전에 거절하지 않게 함(`:424-428`). 읽는 중 상한 검사가 같은 code를 내서 테스트가 통과한다(`:498-510`). 그런데 이 검사가 없으면 선언 크기만큼 버퍼를 먼저 잡는다(`:448-451`) |
|
||||
| 발생 조건 | 이 근처를 고치는 리팩토링. 01-02를 고칠 때도 FS4 자리를 바꾼다 |
|
||||
| 영향 | 규칙이 조용히 깨질 수 있다. FS5가 깨지면 큰 파일 업로드가 기본 30초에 끊긴다. FS8이 깨지면 큰 선언 크기에 버퍼를 먼저 잡는다 |
|
||||
| 심각도·우선순위 | Low · P3 — 지금 코드는 의도대로다(FS4 자리는 01-02가 따로 다룬다) |
|
||||
| 통제·증거 | 세 규칙 M2(구현만, 검출 없음) · E2(변이 FS4·FS5·FS8, 6절) |
|
||||
| 확실성과 남은 가정 | 변이 실행으로 확정했다 |
|
||||
| 결정의 근거 | 적용 제외 — 정한 규칙을 테스트로 고정하는 문제다 |
|
||||
| 이해 비용 | 적용 제외 — 지역 빈틈이다 |
|
||||
| 최소 개선 방향 | ① 5xx 표에 `ATOMIC_PUBLISH_UNSUPPORTED` 행과 01-02에서 정한 `TRANSFER_TIMEOUT` 행 ② 주입한 `monotonicNow`·지연 fetch로 큰 파일이 기본 deadline을 넘겨도 끊기지 않음을 본다 ③ 선언 크기 초과에서 `stream()`이 한 번도 불리지 않음을 본다 |
|
||||
| 대안 비교 | 적용 제외 |
|
||||
| 단순화의 보존 조건 | 적용 제외 — 테스트 추가뿐이다 |
|
||||
| 비용·부작용 | 테스트 세 건 |
|
||||
| 재검토 조건 | 적용 제외 |
|
||||
| 완료 기준 | FS4·FS5·FS8이 각각 한 건 이상 실패를 만든다 |
|
||||
| 검증 방법 | `01-driver.mjs`의 FS4·FS5·FS8을 다시 돌린다(6절) |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
|
||||
## 4. 28개 관점 판정 (36.2)
|
||||
|
||||
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외. 굵은 번호가 깊게 본 관점이다.
|
||||
|
||||
| 번호 | 관점 | 판정 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 1 | 코드 성숙도 | O | M3 / M3 | E2(330건, 변이 11/14) | checkpoint 상태 전이·CAS는 그대로다. client는 입력 검사, 바이트 상한, deadline 하나, 고정된 결과 객체를 갖는다(`fileserver-upload.ts:368-505`). 효과 판정 변이 FS1·FS2·FS3·FS6·FS7이 잡혔다 |
|
||||
| 2 | 구조적 성숙도 | O | M4 | E1, 오케스트레이터 `check:architecture` rc=0 | client는 http adapter 안 파일과 kernel(`platform/abortable-operation.ts`, `platform/retry-after.ts`)만 import한다(`fileserver-upload.ts:1-33`). 새 adapter 사이 예외가 없다. browser-file-storage 포트도 import하지 않는다(`:62-73`, `3d3d6527`) |
|
||||
| 3 | 변경 용이성 | O | M3 | E2 | 1103/01-02를 한 함수(`stripProviderFailure`)에서 고쳐 두 단계·두 상한 조합이 같은 답을 낸다. 포트 타입은 바뀌지 않았다 |
|
||||
| 4 | 인지 부하 | P | M2 | E1 | 업로드 경로 둘의 비교표가 매뉴얼에 생겼다(`02-decision-tables.md:295-301`). 남은 것: 같은 백엔드 code의 효과가 세 곳에 따로 있다(01-02). `maxRetryAfterMs`가 factory 셋(transport, 정책, client)에 있다 |
|
||||
| **5** | 위험 가시성 | P | M2 / M2 | E1 | "짝 아님"이 문서 넷에 있다(1103/01-01 본체). 남은 것: 매뉴얼의 202 안내(01-01), client 주석의 "게시 전" 근거가 `TRANSFER_TIMEOUT`에 맞지 않음(01-02), SHA 표기 `bbe944bd` |
|
||||
| **6** | 실패 성숙도 | P | M3 / M2~M3 | E2 | resumable: 상한 안 대기·상한 밖 `retryable:false`가 두 단계에서 같다. client: `ambiguous`, 모호하지 않은 실패의 취소 규칙을 백엔드 코드대로 읽는다. 남은 것: 202 `REJECTED`(01-01), `TRANSFER_TIMEOUT`(01-02), 헤더 없는 part 단계 429의 `retryable:true`(control plane은 `false`) |
|
||||
| 7 | 운영 성숙도 | P | M2 | E1 | resumable은 part마다 관측 1건이다(`resumable-upload-runtime.ts:834-840`). client에는 관측 지점이 없다. 실패 값만 돌려준다. traceId도 버린다(01-03) |
|
||||
| 8 | 디버깅 가능성 | P | M2 | E2 | 실패에 code·httpStatus·effect가 있다. 남은 것: traceId 누락(01-03), `REJECTED`가 `UPLOADED_FILE_INVALID`로 보임(01-01), `abort()` recovery의 뜻(0929/01-05) |
|
||||
| 9 | 유지보수 성숙도 | P | M2 | E1 | 갈라진 사본: `isAbortSignal` 두 벌(`checkpoint-schema.ts:195`, `http-common.ts:231`), media type 정규식 세 벌(`checkpoint-schema.ts:26`, `presigned-capability-http-provider.ts:50`, `fileserver-upload.ts:151`), 업링크 기본값 글자 복사(`fileserver-upload.ts:141-142`), 효과 표(01-02) |
|
||||
| **10** | 테스트 성숙도 | P | M3 / M3(대부분) | E2(330건, 변이 11/14) | 1103/01-03의 N2·N10·N17이 잡혔다. 이번 수정 넷(M0102, N18, N11r, FS 표)도 테스트가 붙었다. 남은 것: FS4·FS5·FS8 생존(01-04), MSW가 백엔드 문서에서 와 202 `REJECTED`를 놓침(01-01), client의 브라우저 실행 없음 |
|
||||
| 11 | 데이터 성숙도 | O | M3 | E2 | 0929/01-02가 고쳐져 재조정에서 resourceId를 잃지 않는다(N18 검출). 계정 partition과 checkpoint allowlist는 그대로다 |
|
||||
| 12 | 동시성 성숙도 | P | M3 / M3(탭 하나) | E2 | 바뀌지 않았다. 두 탭 같은 uploadKey 경쟁은 단위 테스트(메모리 lock)뿐이다. client는 상태가 없다 |
|
||||
| 13 | 확장성 | P | M2 | E1 | 발급 요청 `2N+4`, `maxPartCount` 검사는 transport에 넘길 때만. client는 요청 하나에 파일 전체다 |
|
||||
| 14 | 성능 성숙도 | P | M3 / M2 | E2 | 1101/01-02 고쳐짐(N11r 검출). 남은 것: copyFactor 설정값(1101/01-03). client는 크기 선언이 없으면 조각 보관 뒤 한 번 복사해 파일의 약 2배를 쓴다(`fileserver-upload.ts:446-499`, 문서화됨). 바이트 비례 deadline을 테스트가 고정하지 않는다(01-04) |
|
||||
| 15 | 보안 성숙도 | O | M4 / M3 | E2 | resumable·presigned 경로는 바뀌지 않았다. client: `credentials`는 프로필이 정하고, 증명 헤더는 프로필에 맞춰 받고, `redirect:"error"`, `no-referrer`, `no-store`, 응답 상한, 이름 escape를 테스트가 본다(`fileserver-upload.test.ts:229-257`, `:534-548`). 이번에 이 부분 변이는 돌리지 않았다 |
|
||||
| 16 | 의존성 성숙도 | O | M2 | E1 | 새 패키지 없음. multipart 본문을 직접 만든다(`FormData`·`Blob` 없음) |
|
||||
| **17** | API / Contract 성숙도 | P | M3 / M2 | E1, E2 | 짝 계약이 생겼다(2.1절). 남은 것: 202 `REJECTED`(01-01), 효과 표 갈라짐과 pin 밖(01-02), `abort()` 표 없음(0929/01-05) |
|
||||
| 18 | 배포 성숙도 | O | M3 | E2 | 정책을 바꾼 빌드가 이전 checkpoint를 잇는 테스트가 기준 실행에서 통과했다. 바뀌지 않았다 |
|
||||
| 19 | 설정 성숙도 | P | M2 | E1 | resumable의 두 상한 조합은 이제 결과가 같다. 남은 것: 업링크 기본값 세 곳(0929/01-03 + client), copyFactor(1101/01-03). client `maxFileBytes`를 백엔드 `max-file-size`에 맞추라는 안내가 없다(매뉴얼 예시는 20 MiB) |
|
||||
| **20** | 개발자 경험 | P | M2 / M2 | E1 | 지난 X에서 올랐다. 매뉴얼 7절에 고르는 기준, 조립 예, 결과 읽기, 틀리면이 있다(`02-decision-tables.md:273-396`). 남은 것: 202 안내(01-01), tus client 없음(재개 필요 시 짝 경로 없음, 매뉴얼이 적음), 백엔드 매뉴얼에 안내 없음 |
|
||||
| **21** | Guardrail 성숙도 | P | M3 | E2 | 1103/01-03 고쳐짐. 남은 것: Fileserver 계약이 pin 대조 밖(01-02), FS 생존(01-04), 게이트가 이 영역 파일 이름을 고정(0929/01-04) |
|
||||
| 22 | 추상화 성숙도 | O | M3 | E1 | client는 의존성을 받는 factory이고 기능 adapter 기여에서 만든다. 새 포트를 만들지 않았다. 레시피 번들·제거 드릴과 떨어져 있다(오케스트레이터 FE-GATE-020 PASS) |
|
||||
| **23** | 일관성 | P | M2 | E1, E2 | 같은 code의 효과가 client와 V3에서 반대(01-02), traceId(01-03), 헤더 없는 429(part 단계 `true` / control plane `false`), 닫힌 runtime에서 `upload()` `NONE` / `abort()` `RESUME` |
|
||||
| 24 | 네이밍 / 의미 성숙도 | P | M2 | E1 | `REJECTED`가 `UPLOADED_FILE_INVALID`로 나온다(01-01). 같은 이름 `maxRetryAfterMs`가 셋이다. `abort()`의 `RESUME` 뜻이 정해져 있지 않다 |
|
||||
| 25 | 조직 확장성 | - | - | - | 적용 제외: 팀 1인 |
|
||||
| 26 | Ownership 성숙도 | P | M1 / M1 | E1 | 지난 X에서 올랐다. presigned 서버 주인은 "제품 backend"로 적혔다(`server-file-capability-infrastructure.md:3-5`). 짝 경로는 Fileserver다. 남은 것: Fileserver 계약 대조의 주인이 없다(pin은 web 계약만), 백엔드에 넘길 것(멱등 키, `TRANSFER_TIMEOUT`)이 지난 README 14.7 한 줄뿐이다 |
|
||||
| 27 | 삭제 가능성 | P | M3 / 레시피 단위 M0 | E1, 오케스트레이터 FE-GATE-020 PASS | client는 browser-file-storage·file-transfer 레시피 제거 드릴 뒤에도 남는다. 어댑터만 지우면 게이트가 실패한다(0929/01-04) |
|
||||
| **28** | 회복 가능성 | P | M3 / M3(주 경로) | E2 | resumable: 재조정 삭제 실패에도 resourceId를 준다(0929/01-02 고쳐짐), ABORT 키 재사용 고정(N10 검출). client: 재개 없음(문서화), `MAYBE_APPLIED` 뒤 재전송은 백엔드가 키를 읽지 않아 중복 가능(문서화), `TRANSFER_TIMEOUT` 자동 재전송(01-02) |
|
||||
|
||||
충족 O 8 · 부분 충족 P 19 · 미충족 X 0 · 미검증 ? 0 · 적용 제외 1. 지난 라운드의 X 둘(20, 26)은 1103/01-01 수정으로 P가 됐다.
|
||||
|
||||
## 5. 미검증
|
||||
|
||||
| 범위 | 이유 | 확인 방법 |
|
||||
| --- | --- | --- |
|
||||
| 짝 백엔드를 띄운 업로드(201, 202 `QUARANTINED`·`REJECTED`, 413 두 code, 실패 Envelope) | 백엔드는 읽기만 했다. helper는 프론트 checkout만 다룬다 | 백엔드 기본 구성 + 프론트 client로 파일 넷(정상, 빈 파일, 타입 불일치, 상한 초과)을 올린다 |
|
||||
| 배포 구성에서 Fileserver 성공 본문이 Envelope로 감싸지는지 | 정적 확인뿐. 백엔드 조립 테스트는 advice 없는 context다(`FileserverCompositionIntegrationTest.java:486-505`) | 위 실행에서 응답 원문을 본다 |
|
||||
| 0바이트 파일이 백엔드 append·finalize를 끝까지 지나는지 | 실행 안 함. 막는 코드를 찾지 못했다 | 위 실행 |
|
||||
| `TRANSFER_TIMEOUT` 뒤 작업이 늦게 `READY`가 되는 경쟁 | 재현 안 함 | 백엔드 `await-seconds`를 1초로, 검증기에 지연을 넣고 업로드 |
|
||||
| client를 실제 브라우저에서(Uint8Array 본문, 비ASCII 파일 이름, CORS preflight) | spec 없음 | capability spec 하나 |
|
||||
| resumable 경로의 실패 뒤 재개·두 탭 경쟁을 실제 브라우저에서 | 브라우저 spec은 정상 경로뿐. 이번에 영역 spec을 돌리지 않았다(오케스트레이터 FE-GATE-008이 돌린다) | 실패 주입 spec |
|
||||
| file-transfer 레시피 번들 크기 | 이번에 재지 않았다. 커밋 `af4ebacb` 본문의 56,084 / 57,800은 주장이다 | `check:optional-recipes:source` |
|
||||
|
||||
## 6. 실행 기록
|
||||
|
||||
| 이름 | 명령 | 변이 | rc | 결과 | 잠금 대기 | 시작 부하 |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| `01-mutations` | `ssh desktop '/tmp/claude-gates/r4/exp.sh 01-mutations - 900 "node /tmp/claude-gates/r4/mut/01-driver.mjs"'` | driver 안에서 하나씩 넣고 원문으로 되돌림(아래 표) | 0 (25초) | 기준 실행 17파일 330건 통과, 변이 14건 중 11건 검출, `restored: clean at 8a442262` | 733초 | 12.03 |
|
||||
|
||||
driver(`/tmp/claude-gates/r4/mut/01-driver.mjs`)는 실험 파일 `tests/integration/zz-area01-exp.test.ts`를 만들어 기준 실행에 넣고 지운 뒤, 변이마다 `node scripts/run-vitest.ts run <관련 테스트>`를 돌린다. 영역 변이는 영역 단위 15파일(276건), FS 변이는 `tests/integration/fileserver-upload.test.ts`(48건)를 돌렸다. 모든 변이의 바꿀 글자는 파일에서 정확히 한 번 나온다는 것을 확인한 뒤 넣었다. 끝난 뒤 helper가 checkout을 되돌렸다.
|
||||
|
||||
**기준 실행**: 17파일 330건 통과(영역 276 + Fileserver 48 + 실험 6), 2.0초.
|
||||
|
||||
**실험**(MSW, 출하 client):
|
||||
|
||||
| ID | 백엔드 응답(코드에서 읽은 모양) | 결과 | 쓰인 곳 |
|
||||
| --- | --- | --- | --- |
|
||||
| XA | 0바이트 파일, 201 `READY` | 요청 1회를 보낸다(보내기 전 하한 없음) | 01-01 |
|
||||
| XB | 202 `state:"REJECTED"`, size 0 | `{ok:false, kind:SCHEMA_MISMATCH, code:UPLOADED_FILE_INVALID, effect:APPLIED_CONFIRMED, httpStatus:202, userMessageKey:error.schema_mismatch, action:none}` | 01-01 |
|
||||
| XC | 202 `state:"QUARANTINED"` | 성공, `state:"QUARANTINED"`(대조군) | 01-01 |
|
||||
| XD | 413 `PAYLOAD_TOO_LARGE`(servlet 상한) / 선언 2,000 B > 상한 1,024 B | 서버: `VALIDATION_REJECTED`, code `PAYLOAD_TOO_LARGE`, `NOT_APPLIED`. 로컬: `VALIDATION_REJECTED`, code `FILE_TOO_LARGE`, `NOT_STARTED`. 같은 거절에 code가 둘이다 | 2.1절 |
|
||||
| XE | 프록시 HTML 504 | `SERVER_FAILURE`, code `CONTENT_TYPE_MISMATCH`, `MAYBE_APPLIED`(대조군) | 01-02 |
|
||||
| XF | 504 `TRANSFER_TIMEOUT` Envelope(`retryable:true`) | `SERVER_FAILURE`, `NOT_APPLIED`, `retryable:true`, `action:"retry"` | 01-02 |
|
||||
|
||||
모든 실험 결과에 `traceId`가 없다(MSW는 `meta.traceId`를 보냈다, 01-03).
|
||||
|
||||
**변이**(하나씩 넣고 되돌림):
|
||||
|
||||
| ID | 바꾼 것 | 결과 |
|
||||
| --- | --- | --- |
|
||||
| N2 | part 단계가 503의 `Retry-After`를 읽지 않음(`http-common.ts:173-176`) | 4 실패 — 검출(1103/01-03) |
|
||||
| N10 | abort 시도마다 멱등 키를 바꿈(`resumable-upload-runtime.ts:1222-1230`) | 1 실패 — 검출(1103/01-03, 네 라운드 만에 처음) |
|
||||
| N17 | control plane 헤더 없는 429를 `retryable:true`로(`fetch-json-transport.ts:588`) | 1 실패 — 검출(1103/01-03) |
|
||||
| M0102 | 1103/01-02 수정 되돌림(`stripProviderFailure`의 `waitRefused` 무시) | 5 실패 — 검출 |
|
||||
| N18 | 0929/01-02 수정 되돌림(재조정 `QUARANTINED`가 삭제 실패를 돌려줌) | 1 실패 — 검출 |
|
||||
| N11r | 1101/01-02 수정 되돌림(수락된 part도 해시) | 1 실패 — 검출 |
|
||||
| FS1 | 4xx를 모두 `MAYBE_APPLIED`로 | 10 실패 — 검출 |
|
||||
| FS2 | `details.ambiguous` 무시 | 1 실패 — 검출 |
|
||||
| FS3 | `Retry-After` 상한 무시 | 1 실패 — 검출 |
|
||||
| FS4 | `ATOMIC_PUBLISH_UNSUPPORTED`·`TRANSFER_TIMEOUT`을 `NOT_APPLIED` 5xx에서 뺌 | **48 통과 — 검출 못 함**(01-04. 뺀 쪽이 01-02의 권고 방향이다) |
|
||||
| FS5 | deadline의 바이트 비례 몫 제거 | **48 통과 — 검출 못 함**(01-04) |
|
||||
| FS6 | 201/202와 state 대조 제거 | 2 실패 — 검출 |
|
||||
| FS7 | Envelope `retryable:false`가 좁히지 않음 | 2 실패 — 검출 |
|
||||
| FS8 | 선언 크기 초과를 읽기 전에 거절하지 않음 | **48 통과 — 검출 못 함**(01-04) |
|
||||
|
||||
**오케스트레이터 결과**(이 문서를 쓸 때까지 나온 것, `desktop:/tmp/claude-gates/r4/`):
|
||||
|
||||
- `gates/summary.txt`(local env): `check:architecture`, `check:types`, `lint`, `test:unit`, `test:component`, `test:integration`, `test:contract`, `test:runtime-schema` 모두 rc=0. `gates/test_unit.log`: 194파일 2,883건 통과, 이 영역 15파일 모두 ✓(합 276건, 이번 기준 실행과 같다). `gates/test_integration.log`: 11파일 189건 통과, `tests/integration/fileserver-upload.test.ts` 48건 ✓.
|
||||
- `merge-48/summary.txt`(CI=true workflow env): FE-GATE-001~007·020 rc=0. FE-GATE-020 로그 `FE-GATE-020 removability: PASS (merge-cycle)`(browser-file-storage·optional-recipe 제거 드릴 포함, client가 남아도 통과).
|
||||
- 나머지 게이트와 snapshot(`r4/snap/`)은 이 문서를 쓸 때 없었다. 결론에 영향 없는 범위라 기다리지 않았다. file-transfer 번들 크기는 5절 미검증으로 남긴다.
|
||||
|
||||
## 7. 새 발견 요약
|
||||
|
||||
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 01-01 | Medium·P2 | 확인된 결함 | Fileserver client가 짝 백엔드의 202 `REJECTED`(빈 파일 하나로 닿음)를 `SCHEMA_MISMATCH`로 읽고, 매뉴얼은 202를 "아직 검사 중"으로 적는다 | `src/adapters/http/fileserver-upload.ts:194`, `:624-631`; `docs/manual/02-decision-tables.md:311`; 백엔드 `FileUploadController.java:195-200`, `FinalizeUploadApplicationUseCase.java:300-343` |
|
||||
| 01-02 | Medium·P2 | 구조적 위험 | 504 `TRANSFER_TIMEOUT`을 `NOT_APPLIED`·5초 뒤 재시도로 주지만 백엔드는 작업 단계와 상관없이 낸다. 효과 표가 V3 표·계약 문서 6.1과 갈라졌고 pin 밖이다 | `src/adapters/http/fileserver-upload.ts:154-170`, `:691-704`; `src/adapters/http/backend-envelope.ts:249-254`; 백엔드 `BlockingTransferExecutor.java:64-79` |
|
||||
| 01-03 | Low·P3 | 확인된 결함 | Fileserver client가 실패 Envelope의 `traceId`를 버린다 | `src/adapters/http/fileserver-upload.ts:638-640` |
|
||||
| 01-04 | Low·P3 | 확인된 결함 | Fileserver client 규칙 셋(5xx 두 code, 바이트 비례 deadline, 읽기 전 크기 거절)을 테스트가 고정하지 않는다 | `src/adapters/http/fileserver-upload.ts:163-170`, `:211-215`, `:424-428` |
|
||||
@@ -0,0 +1,297 @@
|
||||
# 영역 02 — adapters: browser-files · cache-storage · cross-context-invalidation
|
||||
|
||||
> 검토일 2026-11-05 · 기준 `8a44226` · 가이드 `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,file}.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`, 제거 fixture `scripts/lib/removal-fixture.ts`와 드릴 5개
|
||||
> 깊게 본 관점 1, 6, 8, 10, 15, 21, 27, 28
|
||||
> 이번 라운드 렌즈: 지난 라운드 수정이 완료 기준까지 갔는가. 수정이 검사를 약하게 하거나 새 결함을 만들었는가
|
||||
> 영역 판정(35.8): cross-context-invalidation **지정 범위에서 사용 가능** · cache-storage **조건부 사용 가능** · browser-files **조건부 사용 가능** · 이 영역 제거 드릴(FE-GATE-020) **통과**(0절)
|
||||
|
||||
ID 표기: 이번 라운드 새 발견은 `02-01`부터 쓴다. 지난 라운드(2026-11-03) 발견은 `1103/02-01`, 그 전 라운드는 `1101/…`, `0929/…`로 쓴다.
|
||||
|
||||
실행 증거의 출처: 이번 라운드는 리뷰어가 desktop에서 따로 돌리지 않았다(BRIEF-2). 변이 31개와 실험 4개는 요청 `02-R1` 하나로 오케스트레이터 배치에서 돌았다(rc=0, 59초, 앞뒤 checkout 깨끗). 게이트 결과는 오케스트레이터 실행(merge-48, 로컬 env 목록, snapshot)을 인용한다.
|
||||
|
||||
## 0. 결론
|
||||
|
||||
- **지난 라운드 6건은 모두 고쳐졌다.** 고친 커밋은 `60b721f`(02-04), `7e7614f`(02-05), `f19d4c6`(02-02), `1dfe86a`(02-03), `f485e51`(02-01), `f08c93a`·`a28b8a4`(02-06)다. 수정이 고쳤다고 한 규칙을 바꾼 변이 23개를 새 테스트가 모두 잡았다(6.2절). 오케스트레이터 `test:unit`(194파일 2,883건), `test:recipes`(77건), 이 영역 browser spec 21건(3 spec × 3엔진)이 이 커밋에서 통과했다.
|
||||
- **제거 드릴 고장(1103/02-06 = 06-05)은 고쳐졌다.** 오케스트레이터가 CI env로 돌린 FE-GATE-020이 rc=0(1,156초)이다. 드릴 5개 junit이 모두 `failures="0"`이다(browser-file-storage 7/7, realtime 7/7, optional-recipe 6/6, sample 31/31, feature-scaffold 77/77). 문서를 읽는 테스트 제외 목록은 `scripts/lib/removal-fixture.ts:70-82` 한 곳에만 있다.
|
||||
- **이월 7건 중 2건이 고쳐졌고 2건이 일부 고쳐졌다.** `0929/02-04`(설계 문서 줄 번호)와 `0929/02-05`(handoff 실패 lease, M10 검출)는 고쳐졌다. `1101/02-04`는 7개 중 6개가 검출되고 ②(host `storageArea` 비교, N38)만 살아남는다. `1101/02-02`는 위험 확장자를 막았고 media type 짝 검사는 남았다. `0929/02-02`(M05 생존)·`0929/02-03`·`0929/02-06`은 그대로다.
|
||||
- **수정이 새 결함 넷을 만들었다.** 넷 다 데이터를 새게 하지는 않는다.
|
||||
- **02-01(Medium·P2)**: 1103/02-01이 제품 closer를 scope reset에 넣었다. closer가 던지면 scope가 `FAILED`로 멈추고 진단 기록이 하나도 생기지 않는다. 실험 E-3에서 확인했다. 계약의 `ProductScopeParticipant.label`을 읽는 곳이 없다. 그동안 모든 서버 요청이 `SCOPE_FENCED`로 막힌다.
|
||||
- **02-02(Low·P3)**: 1103/02-02가 본문 읽기 실패를 "손상"에서 "모름"으로 옮겼다. 그래서 다시 쓰기 전까지 읽히지 않는 entry는 다시 stage해도 고쳐지지 않는다. 실험 E-1에서 확인했다. 안내는 `RETRY`인데 다시 해도 같다. rollback 대상 release는 cleanup도 지우지 않아 되돌릴 길이 없다. 수정 전 판정에서는 같은 상황이 다시 stage 한 번으로 풀린다.
|
||||
- **02-03(Low·P3)**: 세션 레시피 주석이 "`FeaturePlatformCapabilities`를 보강한다"고 적는다. 매뉴얼은 그 방식이 `check:types:node`에서 키를 잃는다고 막는다. 레시피 테스트는 capability를 기능에 넘기는 절반을 돌지 않는다(`capabilities: {}`).
|
||||
- **02-04(Low·P3)**: 1103/02-02가 만든 "손상 code 4개" 목록의 경계를 테스트가 고정하지 않는다. 목록에서 하나를 빼거나(4개 모두) `NOT_READABLE`을 더해도 테스트가 통과한다. 특히 `INTEGRITY_FAILED`를 빼면 바이트가 바뀐 후보를 다시 stage로 고치지 못하는데, 이것도 잡히지 않는다.
|
||||
- **검사를 약하게 한 수정은 찾지 못했다.** `git diff e40684b..8a44226`에서 이 영역 테스트의 단언 삭제는 0건이다. 지운 줄은 browser spec의 버튼 붙이는 위치 2곳뿐이다(11-10, 실제 클릭 경로는 그대로). 제거 fixture가 문서 테스트 2개를 빼는 것은 약화가 아니다. 그 테스트는 이전에도 fixture에서 한 번도 통과한 적이 없고, 본 저장소 `test:unit`은 계속 돈다.
|
||||
|
||||
| ID | 심각도·우선순위 | 한 줄 |
|
||||
| --- | --- | --- |
|
||||
| 02-01 | Medium · P2 | 제품 scope participant가 실패하면 scope가 진단 없이 `FAILED`로 멈춘다 |
|
||||
| 02-02 | Low · P3 | 계속 읽히지 않는 캐시 본문은 다시 stage해도 고쳐지지 않고 rollback 대상은 회복 길이 없다 |
|
||||
| 02-03 | Low · P3 | 세션 레시피 주석이 매뉴얼이 막는 보강 방식을 가리키고, capability 전달은 테스트 밖이다 |
|
||||
| 02-04 | Low · P3 | 1103/02-02의 손상 code 목록 경계를 테스트가 고정하지 않는다(변이 5개 생존) |
|
||||
|
||||
**영역 판정 (35.8)**
|
||||
|
||||
- cross-context-invalidation(기본 조립): **지정 범위에서 사용 가능.** `e40684b` 뒤 코드 변경이 없다(`git diff --stat` 0줄). 범위는 지난 라운드와 같다. 실제 BroadcastChannel·localStorage 경로가 3엔진에서 통과한다(오케스트레이터 FE-GATE-008). host `storageArea` 비교만 테스트가 없다(`1101/02-04` ②).
|
||||
- cache-storage(service-worker-pwa 레시피, 미조립): **조건부 사용 가능.** 조건은 둘이다. 정적 release 조합에만 쓴다. activate·stage가 같은 후보에서 `UNAVAILABLE`/`NOT_READABLE`을 계속 내면 `cleanupOwned()` 뒤 다시 stage하는 절차를 제품이 정한다(02-02). rollback 대상 release에는 이 절차도 듣지 않으므로 새 release를 배포한다.
|
||||
- browser-files(file-transfer 레시피, 미조립): **조건부 사용 가능.** 세션 수명 연결(1103/02-01)이 생겨 지난 라운드의 첫째 조건은 풀렸다. 로그아웃·계정 전환 모두 이전 runtime을 닫는다(E-2, 기존 테스트). 남은 조건은 둘이다. 제품이 추가하는 scope closer는 던지지 않게 쓴다(02-01). download 정책의 media type과 확장자 짝은 제품이 직접 검토한다(`1101/02-02` 남은 부분).
|
||||
- 템플릿 CI의 FE-GATE-020: **통과.** 지난 라운드 "사용 보류" 사유가 풀렸다. 실제 Gitea 러너에서는 돌리지 않았다(오케스트레이터 결과는 CI env를 준 로컬 실행이다).
|
||||
|
||||
## 1. 범위 (36.1)
|
||||
|
||||
| 항목 | 기록 |
|
||||
| --- | --- |
|
||||
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` 영역 02: `src/adapters/browser-files/` 10파일 4,840줄, `src/adapters/cache-storage/` 5파일 2,339줄, `src/adapters/cross-context-invalidation/` 3파일 1,062줄 |
|
||||
| 커밋·작업 상태·확인 시점 | `8a44226`(laptop worktree, HEAD = 기준). 2026-11-05 19:20~20:10. 지난 기준 `e40684b` 뒤 이 영역을 바꾼 커밋: 소스 `60b721f`·`7e7614f`·`f19d4c6`·`4f78890`, 테스트 `1dfe86a`·`0a74bd4`·`de2670c`·`3bfe6a8`, 조립 `f485e51`·`b9524cf`, 문서 `d9ca653`, 제거 fixture `f08c93a`·`a28b8a4`(`git log e40684b..8a44226 -- <경로>`) |
|
||||
| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker, SSR 없음. cross-context는 기본 조립이다. cache-storage는 service-worker-pwa, browser-files는 file-transfer 레시피의 `AVAILABLE_NOT_COMPOSED` runtime이다(`config/recipes/frontend-capability-recipes.json:155-200`). 공개 경계는 배럴 세 개다 |
|
||||
| 필수 요구와 규모·운영 목표 | 규모·운영 목표는 없다. 코드의 상한 값을 사실상의 목표로 본다(지난 라운드와 같다) |
|
||||
| 읽은 코드·구성 범위 | 세 폴더의 `e40684b..8a44226` 차이 전체, 바뀐 함수 전체(vault `inspect`·`resolveFile`·`resolveVerifiedFile`·`release`·`dispose`, preview `create`, cache `inspect`·`cleanupOwned`·stage 재사용·activate·`verifyReleaseCandidate`, `readAndValidateResponse`, `mapBrowserDataException`). 조립: `runtime-adapters.ts:380-425`·`:505-560`·`:660-690`, `server-state-scope-runtime.ts` 전체, `product-composition-contract.ts` 전체, 레시피와 그 테스트 2개, `scripts/lib/removal-fixture.ts` 전체, 드릴 5개의 fixture 준비 부분 |
|
||||
| 읽은 설정·문서(주장) | `docs/architecture/browser-file-and-origin-storage.md:350-385`·`:447-453`·`:955-1000`, `docs/architecture/client-cache-and-storage.md:80-105`, `docs/manual/03-outside-feature-folder.md:96-115`, `CHANGELOG.md:57-65`·`:179`·`:188-189`·`:240`·`:316`, 각 수정 커밋 본문, 지난 라운드 영역 문서와 README 10.3·12·14절 |
|
||||
| 수행한 테스트·실험 | ① 오케스트레이터 게이트 결과(6.1절): merge-48(CI env) 14개 중 13개 rc=0(FE-GATE-013은 `test:system`의 host bwrap 문제로 rc=1, 이 영역과 무관). 로컬 env 목록은 `verify:documentation` 밖 모두 rc=0. ② 배치 `02-R1`(desktop, 오케스트레이터 실행): 테스트 묶음 4개 대조 실행, 변이 31개(검출 23, 생존 8), 실험 E-1~E-3(6.2·6.3절) |
|
||||
| 확인하지 못한 범위·이유 | 레시피를 조립한 실제 화면(조립 코드 없음). 실제 브라우저에서 Cache Storage 본문 읽기 실패가 지속되는지(E-1은 메모리 fake에서 오류를 주입했다). 실제 Gitea 러너. 5절 |
|
||||
| 이전 리뷰와 비교 가능한 범위 | 변이 ID(L1·L4~L7·L11·N26·N26b·N27·N29·N30·N38·N39·M05·M10)는 지난 라운드와 같은 규칙을 같은 방식으로 바꾼다. 지난 라운드 실행 결과(E-1~E-7, 변이 30건)는 현재 증거로 쓰지 않았다 |
|
||||
|
||||
## 2. 지난 발견 재확인
|
||||
|
||||
| 지난 ID | 내용 | 상태 | 근거 |
|
||||
| --- | --- | --- | --- |
|
||||
| `1103/02-01` | browser-files runtime을 로그아웃·계정 전환에 맞춰 닫는 공식 연결점이 없다 | **고쳐짐** | `ProductComposition.scopeParticipants`가 생겼다(`src/bootstrap/product-composition-contract.ts:100-103`, `:127`). template이 order 10 participant 하나로 제품 closer를 차례로 부르고, 하나라도 실패하면 던진다(`src/bootstrap/runtime-adapters.ts:396`, `:409-423`). `composeProduct` 결과를 그 자리에 넣는다(`:681`). 레시피는 기능에 getter를 주고 closer가 runtime을 dispose한 뒤 다음 호출에서 새로 만든다(`recipes/frontend-capabilities/browser-file-session-capability.ts:38-57`). 설계 문서(`browser-file-and-origin-storage.md:370-384`)와 매뉴얼(`docs/manual/03-outside-feature-folder.md:108`)이 이 방법을 가리킨다. 완료 기준의 테스트가 있다(`tests/recipes/browser-file-session-capability.test.ts:226-284`, 오케스트레이터 `test:recipes` 통과). 로그아웃판(E-2)도 통과했다: 이전 runtime `readRange` `UNAVAILABLE`, download `ABORTED`, handoff 0회, 새 runtime 선택 성공. 변이 F0201a~e(등록 누락, 실패 삼킴, 첫 실패에서 멈춤, 레시피 dispose 누락, 레시피 runtime 유지) 5개 모두 검출. 이 수정이 만든 새 결함: 02-01, 02-03 |
|
||||
| `1103/02-02` | 활성화 재검증이 캐시 본문 읽기의 일시 오류를 무결성 실패로 보고한다 | **고쳐짐** | 저장된 바이트·헤더 판정 4개 code만 `REPAIRABLE`이고 나머지는 `UNKNOWN`이다(`src/adapters/cache-storage/public-response-cache-adapter.ts:1083-1088`, `:1139-1144`). 활성화는 `UNKNOWN`을 자기 operation으로 돌려준다(`:681-685`). 완료 기준 시나리오가 테스트에 있다(`tests/unit/public-response-cache-repair.test.ts:177-234`). 되돌리는 변이 F0202가 그 테스트에 걸린다. 이 수정이 만든 새 결함: 02-02(회복 공백), 02-04(목록 경계 테스트 공백) |
|
||||
| `1103/02-03` | 손상 데이터·로그아웃 경로의 보호 규칙 5개를 테스트가 잡지 못한다 | **고쳐짐** | L1·L4·L5·L6·L7 다섯 변이가 모두 새 테스트 하나씩에 걸린다. L4 `tests/unit/browser-file-content.test.ts:653`, L5 `:672`(리뷰가 제안한 `readRange` 대신 `openSource`로 고정했다. `readRange`는 slice 뒤 한 번 더 검사해 L5를 못 잡는다는 커밋 `1dfe86a` 설명이 코드와 맞다), L1 `:697`, L6 `tests/unit/public-response-cache-repair.test.ts:530`, L7 `:552` |
|
||||
| `1103/02-04` | `inspect()`와 `release()`가 겹치면 놓은 ref에 receipt가 발급되고 File이 남는다 | **고쳐짐** | `#disposed` 재확인 바로 뒤에 ref 재확인이 생겼다(`src/adapters/browser-files/browser-file-vault.ts:355-363`). 결과는 `NOT_FOUND`/`RESELECT`로 `resolveFile`의 없는 ref 결과와 같다(`:568-571`). 테스트 `tests/unit/browser-file-content.test.ts:617`이 변이 F0204를 잡는다. L11(`resolveVerifiedFile`의 `records.has`, `:614`)은 이제 동등 변이다. `release()`가 receipt를 먼저 지우고(`:627`) inspect가 놓은 ref에 receipt를 내지 않으므로, ref 없는 receipt가 남는 경로가 없다. 같은 ref를 두 정책으로 동시에 inspect하면 receipt가 둘 생긴다. 둘 다 자기 정책에 맞고 release·dispose가 지운다(커밋 `60b721f`가 범위 밖으로 적음). 결함으로 세지 않는다 |
|
||||
| `1103/02-05` | pointer가 손상되면 `inspect()`가 아무 상태도 보여 주지 않는다 | **고쳐짐** | `CORRUPT_DATA`면 후보 목록을 끝까지 채우고 `activePointer: "UNREADABLE"`을 준다(`public-response-cache-adapter.ts:872-875`, `:911-916`). 일시 오류는 그대로 실패다. 포트에 필수 칸이 생겼다(`src/application/ports/browser-file-storage/cache-storage-ports.ts:43-51`). [계약] CHANGELOG 행이 있다(`CHANGELOG.md:188`). 변이 F0205(되돌림), F0205b(일시 오류도 UNREADABLE), F0205c(`NONE`을 `READABLE`로) 모두 `public-response-cache-repair.test.ts:469`에 걸린다. 지난 영향 칸의 "오류 operation이 `CACHE_LOOKUP`이라 구분되지 않는다"는 남았다(`:923`). 완료 기준에 없던 부분이고 커밋 `7e7614f`가 공유 operation union 변경이라 미뤘다고 적었다 |
|
||||
| `1103/02-06` (= `06-05`, + `test:optional-recipe-removal`) | 제거 드릴이 문서 테스트 2파일 때문에 항상 실패한다 | **고쳐짐** | 제외 목록이 한 곳에 있다(`scripts/lib/removal-fixture.ts:56-82`). `prepareRemovalFixture`가 문서를 복사하지 않은 fixture에서만 두 테스트를 지운다(`:152-154`). sample·scaffold 드릴은 문서를 같이 복사하고 두 테스트를 돈다(`scripts/test-sample-removal.ts:211-214`, `scripts/test-feature-scaffold.ts:60-63`). 다섯 드릴이 같은 함수를 쓰는지 테스트가 고정한다(`tests/unit/removal-fixture.test.ts:143-178`). 완료 기준: 오케스트레이터 merge-48(CI env) FE-GATE-020 rc=0, 1,156초. junit(snapshot `artifacts/tests/`, 19:25~19:39): browser-file-storage-runtime-removal 7/7, realtime-runtime-removal 7/7, optional-recipe-removal 6/6, reference-feature-removal 31/31, feature-scaffold 77/77, 모두 `failures="0"`. 새 레시피 파일도 드릴이 같이 지운다(`scripts/test-browser-file-storage-runtime-removal.ts:41`) |
|
||||
| `1101/02-02` | download 정책 `safeExtension`이 금지 목록·media type을 보지 않는다 | **일부** | 금지 목록은 이제 본다. 금지 확장자이거나 그것으로 끝나면(`.tar.js`) 조립이 `TypeError`다(`src/adapters/browser-files/browser-file-policy-registry.ts:456`, `file-policy.ts:103-108`). 목록은 사용자 파일명과 같은 `DEFAULT_FORBIDDEN_EXTENSIONS` 하나다(`file-policy.ts:63-96`). 테스트 3건(`tests/unit/browser-file-policy-registry.test.ts:180-204`)이 F110102(검사 삭제)와 F110102b(`endsWith`를 일치 비교로)를 잡는다. 남은 것: media type과 확장자 짝은 여전히 보지 않는다. `application/pdf` + `.zip` 정책이 통과한다. 설계 문서가 한계로 적었다(`browser-file-and-origin-storage.md:450-453`) |
|
||||
| `1101/02-04` | 보호 규칙 7개가 변이에서 살아남는다 | **일부** | 6개가 이제 검출된다. ① N29 합계 바이트 상한(`tests/unit/browser-file-content.test.ts:985`), ③ N27 재검사 receipt 무효화(`:1008-1010`), ④ N26b `no-cache`와 ⑦ N26 `Set-Cookie`(`tests/unit/public-response-cache-codec.test.ts:160-166`), ⑤ N39 조회의 `keys()` 재확인(`tests/unit/public-response-cache-repair.test.ts:587-612`), ⑥ N30 fragment(`tests/unit/browser-file-download.test.ts:296`). 남은 것: ② N38 host `storageArea` 비교(`src/adapters/cross-context-invalidation/browser-cross-context-host.ts:291-295`)는 CX 묶음 46건을 모두 통과한다(생존). 커밋 `3bfe6a8`이 하네스가 필요해 미뤘다고 적었다 |
|
||||
| `0929/02-02` | `inspect()`의 비용·취소·판정 불가가 포트 계약에 없다 | **남음** | 포트에 signal이 없다(`cache-storage-ports.ts:93`). 호출부가 `undefined`를 넘긴다(`public-response-cache-adapter.ts:899`). 판정 불가(`UNKNOWN`)도 `verified:false`다(`:904`). M05(판정 불가를 `verified:true`로)가 CS 묶음 59건을 모두 통과한다. 1103/02-02 뒤 `UNKNOWN`이 본문 읽기 실패까지 넓어져 이 칸이 "손상"과 "읽지 못함"을 더 많이 합친다. E-1c에서 읽히지 않는 r1이 `r1:false`로 보인다 |
|
||||
| `0929/02-03` | CHANGELOG 0.2.0 browser-files [계약] 행의 경로·대상이 틀렸다 | **남음** | `CHANGELOG.md:316`의 영향 경로가 여전히 `src/adapters/browser-file-storage/`다. Cache Storage를 "browser-files recipe"로 적는다 |
|
||||
| `0929/02-04` | 설계 문서 줄 번호 참조가 밀렸다 | **고쳐짐** | 지난번 밀린 5곳이 고쳐졌다. `client-cache-and-storage.md:93-102`는 줄 번호 대신 심볼 이름을 쓴다(`crossContextCacheEpochForRelease`, `createServerStateGenerationStore` 콜백, `activateNextGeneration`, coordinator `dispose()`, 커밋 `d9ca653`). 남은 줄 번호 5곳을 대조했다. `storage-keys.ts:112`, `browser-cross-context-host.ts:36-37`·`:286-296`, `browser-cross-context-invalidation.ts:197-201`, `server-state-generation-store.ts:50-57` 모두 맞다. `browser-file-and-origin-storage.md`의 줄 번호(`create-browser-file-runtime.ts:93`·`:154`·`:163`·`:177-188`, `object-url-lease.ts:48-71`·`:143-151`, `download-delivery-adapter.ts:150`·`:390-396`)도 맞다. 문서 줄 번호를 보는 자동 검사는 여전히 없다. 심볼 이름으로 바꾼 것이 그 대신이다 |
|
||||
| `0929/02-05` | handoff 실패 lease 반환을 테스트가 고정하지 않는다 | **고쳐짐** | 테스트 "revokes the lease of a handoff that throws"(`tests/unit/browser-file-download.test.ts:774`)가 M10(`download-delivery-adapter.ts:858`의 `lease?.release()` 삭제)을 잡는다 |
|
||||
| `0929/02-06` | cross-context kernel 예외가 쓰임보다 넓다 | **남음** (결정 대기) | 예외가 `cross-context-invalidation/index.ts` 전체를 연다(`.dependency-cruiser.json:261`). adapter 쪽 사용은 여전히 query-cache의 `import type` 하나다(`src/adapters/query-cache/tanstack-cache-coordinator.ts:21`). repo `CLAUDE.md`가 이 예외를 kernel로 열거하고, 새 파일 단위 예외는 제안하지 않는다. 좁힐지는 소유자 결정이다 |
|
||||
|
||||
지난 라운드에 고쳐짐으로 닫은 `1101/02-01`·`1101/02-03`·`1101/02-05`·`0929/02-01`은 이번 diff에서 그 코드가 바뀌지 않았다(`object-url-lease.ts:192-208`, `public-response-cache-adapter.ts:497`, `browser-cross-context-invalidation.ts:318`·`:337`, `public-cache-codec.ts:456-461`). 재발 없음으로 본다. 그 변이(F1~F7)는 다시 걸지 않았다.
|
||||
|
||||
## 3. 이번 발견 (36.3)
|
||||
|
||||
새 발견 4건. 심각도 Medium 1 · Low 3. 우선순위 P2 1 · P3 3. 성격 확인된 결함 2 · 구조적 위험 2. 넷 다 지난 라운드 수정이 만들었다(02-01·02-03은 `f485e51`, 02-02·02-04는 `f19d4c6`).
|
||||
|
||||
### 02-01 제품 scope participant가 실패하면 scope가 진단 없이 `FAILED`로 멈춘다. 어느 participant인지도 남지 않는다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(진단 공백) |
|
||||
| 관련 관점 | 8, 7, 5, 17, 6 |
|
||||
| 근거 | ① 1103/02-01 수정이 제품 closer를 scope reset에 넣었다. template participant 하나가 제품 closer를 차례로 부르고, 하나라도 던지면 이유 없는 `Error("A product scope participant failed.")`를 던진다(`src/bootstrap/runtime-adapters.ts:409-423`). 어느 closer가 무엇을 던졌는지 버린다. ② scope runtime은 participant 실패를 `failed = true`로만 받는다(`src/adapters/query-cache/server-state-scope-runtime.ts:136-141`). 그 뒤 `FAILED`를 lifecycle로만 알린다(`:161-171`). 이 runtime이 `diagnostics`에 남기는 것은 subject 누락 하나뿐이다(`:114`, `:239-250`). ③ `src`에서 `subscribeLifecycle`을 듣는 곳이 없다(`git grep subscribeLifecycle -- src`가 계약과 runtime 정의만 찾는다). ④ 계약은 `label`을 필수로 받는다(`src/bootstrap/product-composition-contract.ts:100-103`). 그런데 `label`을 읽는 코드가 없다(`runtime-adapters.ts`, `server-state-scope-runtime.ts`에 `.label` 0건). ⑤ `FAILED` 동안 모든 서버 요청이 `SCOPE_FENCED`로 막힌다. 자격 증명 붙이기가 phase를 먼저 본다(`runtime-adapters.ts:513-514`). 익명 profile도 같다. ⑥ 수정 전에는 이 경로가 사실상 닿지 않았다. template participant는 `conditionalValidators.clear()` 하나였다(`runtime-adapters.ts:404-408`). 이제 제품 코드(비동기 포함)가 이 경로로 들어온다. ⑦ 실험 E-3(실제 `createRuntimeAdapters`, 6.3절): `label: "r4-broken-closer"` closer가 던지게 하고 계정을 바꿨다. phase `FAILED`, lifecycle `FENCED → FAILED`. 같은 identity 알림을 한 번 더 주자 다시 `FENCED → FAILED`. 진단 기록 수는 전후 1건 그대로다(부팅 때 남은 `cache.operation.failed` 하나). label·scope·participant를 담은 기록은 0건이다 |
|
||||
| 발생 조건 | 제품이 `scopeParticipants`에 closer를 넣는다. 그 closer가 로그아웃·계정 전환 때 던지거나 reject한다(예: IndexedDB close 실패, 소켓 정리 중 예외) |
|
||||
| 영향 | 그 탭의 서버 상태가 멈춘다. 모든 요청이 `SCOPE_FENCED`다. 다음 session 알림이 reset을 다시 시도한다(`server-state-scope-runtime.ts:103-110`). closer가 계속 던지면 다시 `FAILED`다(E-3). 알림이 없는 세션(쿠키 세션)이면 새로 고침까지 그대로다. 진단 기록이 0건이라 개발자와 운영자는 "로그아웃 뒤 앱이 아무 요청도 안 보낸다"만 본다. 원인 closer를 찾으려면 제품 closer를 하나씩 지워 봐야 한다. 데이터 노출은 없다. 닫히는 쪽으로 실패한다 |
|
||||
| 심각도·우선순위 | Medium · P2 — 가이드 35.2의 Medium 예시 "주요 진단 정보 부족"이다. 앱 전체 서버 상태가 멈추는데 흔적이 없다. 닫히는 쪽으로 실패하고 데이터가 새지 않아 High는 아니다. 레시피의 closer는 dispose 전에 `runtime = null`을 먼저 해 재시도에서 던지지 않는다(`browser-file-session-capability.ts:51-55`). 그래서 P1이 아니다. 매뉴얼이 제품에게 closer를 더하라고 안내하므로(`docs/manual/03-outside-feature-folder.md:108`) 제품 closer가 늘기 전에 고친다 |
|
||||
| 통제·증거 | 실패를 막는 규칙(READY로 가지 않음) M3(`runtime-adapters-product-scope-participants.test.ts:135-152`, F0201b·F0201c 검출) · 실패를 알리는 규칙 M0(관측 코드 없음) · E1, E2(E-3) |
|
||||
| 확실성과 남은 가정 | 진단 없음, `label` 미사용, 요청 차단은 코드와 E-3으로 확정했다. 화면이 `FAILED`를 어떻게 보이는지는 영역 08·09 몫이라 보지 않았다. scope runtime 자체의 무진단은 이번 수정 전부터 있었다(영역 03). 이 항목은 1103/02-01 수정이 그 경로를 제품 코드에 연 부분으로 센다. 영역 03·09가 같은 결함을 적었다면 오케스트레이터가 하나로 합친다 |
|
||||
| 결정의 근거 | 확인한 사실: 실패는 닫히는 쪽(READY 막음)으로 처리되고 관측은 없다. 기록된 의도: 계약 주석 "A close that throws or rejects keeps the scope from reaching READY"(`product-composition-contract.ts:93-99`). 관측 의도는 기록이 없다. 리뷰어 추론: `label`은 진단용으로 둔 칸인데 연결이 빠졌다 |
|
||||
| 이해 비용 | 제품 개발자가 로그아웃 뒤 멈춘 앱을 보면 scope runtime, template participant, 제품 closer 세 곳을 읽어야 "closer가 던졌다"를 안다 |
|
||||
| 최소 개선 방향 | scope runtime이 participant 실패와 `FAILED` 진입을 그 participant의 `label`과 함께 diagnostics에 한 번 남긴다. 제품 wrapper는 실패한 제품 closer의 `label`을 실어 던진다 |
|
||||
| 대안 비교 | (가) 현상 유지 + 문서에 "closer는 던지지 않게 쓴다": 0줄, 결함은 그대로. (나) 제품 wrapper만 label을 기록: 몇 줄, template participant 실패는 여전히 조용하다. (다) scope runtime이 participant마다 label과 함께 실패를 기록: template 것까지 한 곳에서 해결. (다)가 가장 작은 전체 해결이다. `label`은 제품이 고른 문자열이라 진단 projection이 받는 형식(닫힌 토큰)으로 제한해야 한다 |
|
||||
| 단순화의 보존 조건 | reset 실패는 READY를 막는다. 나머지 closer는 계속 부른다(`runtime-adapters-product-scope-participants.test.ts:135-152`). 진단은 사용자·세션 값을 싣지 않는다 |
|
||||
| 비용·부작용 | 수십 줄과 테스트 1~2개. 진단 eventId 레지스트리에 행 하나 |
|
||||
| 재검토 조건 | 화면이 `FAILED`를 사용자에게 보이고 재시도 버튼을 주게 되면, 진단과 화면 신호를 같은 lifecycle 구독으로 묶는다 |
|
||||
| 완료 기준 | 던지는 제품 closer 뒤 diagnostics에 그 `label`이 담긴 기록이 하나 있다. template participant 실패도 기록된다 |
|
||||
| 검증 방법 | E-3 시나리오(`scratchpad/r4-02/02-setup.mjs`가 만든 테스트)를 `tests/unit/runtime-adapters-product-scope-participants.test.ts`에 옮겨 `outputPorts.diagnostics.entries()`를 단언한다 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
|
||||
### 02-02 계속 읽히지 않는 캐시 본문은 다시 stage해도 고쳐지지 않는다. 안내는 `RETRY`인데 다시 해도 같고, rollback 대상은 회복 길이 없다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험(1103/02-02 수정이 만든 회복 공백) |
|
||||
| 관련 관점 | 28, 6, 24, 11, 18 |
|
||||
| 근거 | ① 1103/02-02 뒤 본문 읽기 실패(`UNAVAILABLE`·`NOT_READABLE`·`NOT_FOUND` 등)는 `UNKNOWN`이다(`src/adapters/cache-storage/public-response-cache-adapter.ts:1083-1088`, `:1139-1144`). 브라우저 오류 이름이 그 code로 바뀐다(`src/adapters/browser-file-storage/result.ts:49-104`: `TypeError` → `UNAVAILABLE`/`RETRY`, `NotReadableError` → `NOT_READABLE`/`REOPEN`). ② stage 재사용 경로는 `UNKNOWN`이면 실패를 돌려주고 다시 받지 않는다(`:492-497`). 테스트가 그렇게 고정한다: "neither reused nor fetched again over the network"(`tests/unit/public-response-cache-repair.test.ts:217-223`). ③ 수정 전에는 같은 상태가 `REPAIRABLE`이었다. 그때 stage는 모든 asset을 다시 받아 같은 캐시에 덮어썼다(`:505-548`). 덮어쓰기는 digest로 검증한 같은 바이트라 서비스 중인 release를 해치지 않는다. 실패하면 이미 바꾼 entry만 남긴다(`:573-578`). ④ cleanup은 pointer와 rollback 목록에 있는 캐시를 지우지 않는다(`:801-812`). ⑤ 설계 문서는 이 경우의 절차를 적지 않는다(`docs/architecture/browser-file-and-origin-storage.md:955-1000`). ⑥ 실험 E-1(6.3절): entry 하나가 다시 쓸 때까지 읽히지 않게 했다. 현재 코드: 후보 r2는 activate 2회 `UNAVAILABLE`/`RETRY`, 재stage 2회 같은 실패에 fetch 0회. cleanup이 r2를 지운 뒤에야 stage(fetch 2)와 activate가 성공했다. `NotReadableError`도 같다(`NOT_READABLE`/`REOPEN`). rollback 대상 r1: activate 2회, 재stage, cleanup(삭제 0, r1 보존), 다시 activate 모두 실패. 활성 r1: 조회 `UNAVAILABLE`, 재stage 실패, 조회 계속 실패. 수정 전 판정(F0202 되돌림)으로 같은 실험: activate는 `INTEGRITY_FAILED`/`REHYDRATE`, 재stage 한 번(fetch 2)으로 entry가 고쳐지고 activate·rollback·조회가 모두 성공했다 |
|
||||
| 발생 조건 | Cache Storage의 한 entry 본문이 다시 쓰기 전까지 계속 읽히지 않는다(디스크의 blob 손실 등). 그 후보를 활성화하거나 같은 manifest로 다시 stage한다. 또는 rollback으로 그 release를 다시 활성화한다 |
|
||||
| 영향 | 새 release 후보: 배포 흐름이 `RETRY`를 따르면 끝나지 않는다. 운영자가 cleanup을 돌린 뒤 다시 stage해야 풀린다. rollback 대상: 그 release로는 되돌릴 수 없다. 새 release를 배포해야 한다. 활성 release: 그 asset 조회가 계속 `UNAVAILABLE`이다. 제품 SW가 네트워크로 넘기면 사용자 피해는 오프라인에서 그 asset을 못 쓰는 것이다. 데이터를 지우지는 않는다 |
|
||||
| 심각도·우선순위 | Low · P3 — 데이터는 지켜진다. 새 후보는 cleanup으로, 나머지는 새 release로 회복된다. 지속되는 본문 읽기 실패가 실제 브라우저에서 얼마나 생기는지는 모른다. 레시피가 미조립이다 |
|
||||
| 통제·증거 | 지속 실패 회복 규칙 M0(다시 쓰는 길이 없음) · E1, E2(E-1, 메모리 fake에 오류 주입) |
|
||||
| 확실성과 남은 가정 | 코드 경로와 동작은 E-1로 확정이다. 실제 Chrome·Firefox·Safari에서 Cache Storage 본문 읽기 실패가 지속되는지, 어떤 오류 이름으로 오는지는 확인하지 못했다. 일시 오류만 있다면 이 항목은 결함이 아니다 |
|
||||
| 결정의 근거 | 확인한 사실: 수정은 일시 오류의 재다운로드 비용을 없애고 대신 지속 실패의 자가 회복을 잃었다. 기록된 의도: 커밋 `f19d4c6` "stage 재사용 경로는 본문을 읽지 못하면 이제 repair 대신 실패를 돌려준다. 손상이 아닌 것을 손상으로 고치지 않는다는 STO-RR-04와 같은 방향". 리뷰어 추론: STO-RR-04가 막으려던 것은 서비스 중인 release 삭제다(`:464-466` 주석). stage 덮어쓰기는 삭제가 아니라서 그 규칙이 막을 대상이 아니다. 지난 라운드 리뷰(1103/02-02 비용 칸)도 이 차이를 보지 않았다 |
|
||||
| 이해 비용 | 운영자는 `UNAVAILABLE`/`RETRY`만 보고 cleanup이 답이라는 것을 코드 없이 알 수 없다. rollback이 안 되는 이유는 inspect의 `verified:false`(판정 불가와 손상을 합침, `0929/02-02`)로도 구분되지 않는다 |
|
||||
| 최소 개선 방향 | stage 재사용 경로만 `UNKNOWN`(중단 제외)을 "덮어써 고침"으로 본다. 활성화는 지금처럼 본문 읽기 실패를 손상으로 보고하지 않는다. 다만 recovery를 "다시 stage"(`REHYDRATE`)로 안내한다. code는 그대로 둔다 |
|
||||
| 대안 비교 | (가) 현상 유지 + 문서에 "계속 실패하면 cleanup 뒤 다시 stage, rollback 대상은 새 release": 0줄, rollback 대상은 못 고친다. (나) 재사용 경로의 `UNKNOWN`만 덮어쓰기: 몇 줄, 일시 오류에서 재다운로드 비용이 돌아온다(수정 전과 같다). 서비스 중인 release는 지우지 않는다. (다) 실패한 entry만 다시 받아 덮어쓰기: 비용이 가장 작지만 stage 경로를 entry 단위로 나눠야 한다. (나)가 가장 작다 |
|
||||
| 단순화의 보존 조건 | 활성화는 검증된 후보만 올린다. 일시 읽기 실패로 캐시를 지우지 않는다(STO-RR-04). 바이트가 다르면 `INTEGRITY_FAILED`(`public-response-cache-repair.test.ts:236-263`). 조회는 지금처럼 `UNAVAILABLE`/`RETRY`다 |
|
||||
| 비용·부작용 | 몇 줄과 테스트 1~2개. `public-response-cache-repair.test.ts:217-223`의 "fetch 0회" 단언을 바꾼다. service-worker-pwa 번들 여유 342 B 안에서 끝나야 한다(오케스트레이터 FE-GATE-012: 9,758 / 10,100 gzip B) |
|
||||
| 재검토 조건 | 실제 브라우저에서 지속되는 본문 읽기 실패가 관찰되지 않으면 (가)로 닫는다. Service Worker drain 조합을 조립하면 rollback 대상 회복을 그 설계와 같이 본다 |
|
||||
| 완료 기준 | E-1a·E-1c 시나리오에서 같은 manifest stage가 후보를 고치고 다음 activate(rollback 포함)가 성공한다 |
|
||||
| 검증 방법 | E-1(`scratchpad/r4-02/zz-r4-02-e1.test.ts`)을 `public-response-cache-repair.test.ts`의 02-02 묶음에 옮긴다 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
|
||||
### 02-03 세션 레시피 주석이 매뉴얼이 막는 보강 방식을 가리키고, capability를 기능에 넘기는 절반은 테스트 밖이다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(문서 불일치 + 테스트 공백) |
|
||||
| 관련 관점 | 9, 20, 17, 10 |
|
||||
| 근거 | ① 레시피 주석은 "A product that installs a feature using it augments `FeaturePlatformCapabilities` with `files: SessionBrowserFiles`"라고 적는다(`recipes/frontend-capabilities/browser-file-session-capability.ts:21-24`). ② 매뉴얼은 그 타입을 `src/features/product-capabilities.ts`의 `ProductFeaturePlatformCapabilities`에 적으라고 한다. `product-composition.ts` 안에서 `FeaturePlatformCapabilities`를 보강(`declare module`)하면 `check:types:node`가 그 키를 보지 못한다고 막는다(`docs/manual/03-outside-feature-folder.md:105-106`). 제품 쪽 인터페이스는 `src/features/product-capabilities.ts:28`, 상속은 `src/features/feature-adapter-contribution.ts:57`이다. ③ 레시피 주석의 예는 `capabilities: { files: browserFiles.files }`다(`:30`). 레시피 테스트는 `capabilities: {}`로 조립한다(`tests/recipes/browser-file-session-capability.test.ts:142`). 테스트는 `files.current()`를 직접 부른다(`:228`, `:278`). 기능 contribution이 `files` capability를 받아 쓰는 길은 돌지 않는다 |
|
||||
| 발생 조건 | 제품 개발자가 레시피 주석만 보고 파일 기능을 붙인다 |
|
||||
| 영향 | 주석대로 `declare module`로 보강하면 앱 typecheck는 통과하고 `check:types:node`에서 키를 잃는다. 매뉴얼이 이미 적은 함정이다. capability 전달 절반이 테스트 밖이라 그 길이 깨져도 레시피 테스트는 통과한다 |
|
||||
| 심각도·우선순위 | Low · P3 — 실패가 typecheck에서 드러나고 매뉴얼이 정답을 적었다. 런타임 피해는 없다 |
|
||||
| 통제·증거 | 문서 M1(주석과 매뉴얼이 다름) · 전달 경로 검출 M0 · E1 |
|
||||
| 확실성과 남은 가정 | 주석 문장과 테스트 입력은 확정이다. "augments"를 `ProductFeaturePlatformCapabilities` 채우기로 읽는 사람도 있다. 그래도 어느 파일인지 적지 않아 매뉴얼과 다르게 읽힌다 |
|
||||
| 결정의 근거 | 적용 제외 — 같은 저장소 안 두 안내가 다른 단순 불일치다 |
|
||||
| 이해 비용 | 레시피에서 시작한 개발자는 매뉴얼 03 C절까지 와야 맞는 파일을 안다 |
|
||||
| 최소 개선 방향 | 주석을 "`src/features/product-capabilities.ts`의 `ProductFeaturePlatformCapabilities`에 `files: SessionBrowserFiles`를 적는다"로 고친다. 레시피 테스트에 `capabilities: { files }`를 넘기고 기능 contribution 하나가 `current()`로 받는지 단언을 더한다 |
|
||||
| 대안 비교 | 적용 제외 — 기대 계약(매뉴얼)이 이미 정해져 있다 |
|
||||
| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다 |
|
||||
| 비용·부작용 | 주석 몇 줄, 테스트 수십 줄 |
|
||||
| 재검토 조건 | 적용 제외 — 선택을 바꾸는 판단이 없다 |
|
||||
| 완료 기준 | 주석이 매뉴얼과 같은 파일을 가리킨다. 레시피 테스트가 capability를 기능까지 넘긴다 |
|
||||
| 검증 방법 | 주석 대조(정적). 레시피 테스트에서 `capabilities.files`를 빼면 실패하는지 변이로 본다 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
|
||||
### 02-04 1103/02-02의 손상 code 목록 경계를 테스트가 고정하지 않는다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험(테스트 공백) |
|
||||
| 관련 관점 | 10, 28, 6 |
|
||||
| 근거 | 1103/02-02 수정은 `REPAIRABLE_READ_CODES` 4개를 새 판정 표로 두었다(`src/adapters/cache-storage/public-response-cache-adapter.ts:1083-1088`). 배치 02-R1에서 이 표의 경계를 바꾼 변이 5개가 CS 묶음(4파일 59건)을 모두 통과했다(6.2절). F0202-int(`INTEGRITY_FAILED` 뺌), F0202-cor(`CORRUPT_DATA` 뺌), F0202-pol(`POLICY_REJECTED` 뺌), F0202-lim(`LIMIT_EXCEEDED` 뺌), F0202-notreadable(`NOT_READABLE` 더함). 앞의 넷이 살아남는 이유: 활성화는 `UNKNOWN`도 원래 code로 돌려준다(`:681-685`). 그래서 "바이트가 다르면 `INTEGRITY_FAILED`" 테스트(`tests/unit/public-response-cache-repair.test.ts:236-263`)는 두 판정을 구분하지 못한다. 차이는 stage 재사용 경로(`public-response-cache-adapter.ts:482-497`)에서만 난다. 그런데 그 경로의 repair 테스트는 entry가 없는 경우(`!cached`, `:1127`)만 본다("repairs an evicted asset in place", `:320`). 마지막 하나는 `NotReadableError`를 쓰는 테스트가 없어서다. 지금 테스트는 `TypeError` 하나로 본문 실패를 만든다(`:190-194`) |
|
||||
| 발생 조건 | 이 목록을 고치는 리팩터링이나 새 failure code 추가 |
|
||||
| 영향 | `INTEGRITY_FAILED`가 빠지면 바이트가 바뀐 후보를 다시 stage로 고치지 못한다. 활성화는 `REHYDRATE`를 안내하는데 다시 stage도 같은 `INTEGRITY_FAILED`로 실패한다. 손상 회복의 기본 길이 끊겨도 테스트는 통과한다. `NOT_READABLE`이 더해지면 1103/02-02가 `NotReadableError`에서만 되돌아간다 |
|
||||
| 심각도·우선순위 | Low · P3 — 지금 코드는 맞다. 회귀를 막는 장치만 없다. 지난 라운드 같은 모양(1103/02-03, 변이 생존)과 같은 등급이다 |
|
||||
| 통제·증거 | 판정 표 M2 구현 · 검출 M3 없음(경계 5개) · E2(변이 생존) |
|
||||
| 확실성과 남은 가정 | 변이 결과는 확정이다. CS 묶음 밖의 테스트(browser spec)는 이 경계를 돌지 않는다(`public-cache-storage.spec.ts`의 두 테스트는 실패 B stage와 Vary 조회만 본다) |
|
||||
| 결정의 근거 | 적용 제외 — 테스트를 더하는 문제다 |
|
||||
| 이해 비용 | 목록을 고치는 사람은 테스트가 통과해도 어느 손상이 다시 stage로 고쳐지는지 알 수 없다 |
|
||||
| 최소 개선 방향 | stage 재사용 경로에서 code마다 한 행씩 표 테스트를 둔다. 바이트 변경(`INTEGRITY_FAILED`), 정책 밖 헤더(`POLICY_REJECTED`), 길이 초과(`LIMIT_EXCEEDED`)는 다시 받아 고치고(fetch > 0, 다음 activate 성공), `TypeError`·`NotReadableError` 본문 실패는 fetch 0으로 실패한다. `CORRUPT_DATA`는 `DataError` 본문 오류로 만든다(`result.ts:67-69`) |
|
||||
| 대안 비교 | 적용 제외 |
|
||||
| 단순화의 보존 조건 | 적용 제외 |
|
||||
| 비용·부작용 | 표 테스트 1개(행 5~6개). 02-02를 고치면 본문 실패 행의 기대가 바뀐다 |
|
||||
| 재검토 조건 | 적용 제외 |
|
||||
| 완료 기준 | F0202-int·-cor·-pol·-lim·-notreadable이 모두 실패한다 |
|
||||
| 검증 방법 | `scratchpad/r4-02/02-runner.mjs`의 같은 변이를 다시 건다 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
|
||||
## 4. 28개 관점 판정 (36.2)
|
||||
|
||||
판정 기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 굵은 번호는 깊게 본 관점이다.
|
||||
|
||||
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| **1** | 코드 성숙도 | 적용 — "검증 뒤에만 성공", 같은 턴 경쟁 | M2 / M2 | E1, E2 | P — inspect·release 경쟁이 고쳐졌다(1103/02-04). 본문 읽기 실패 판정이 맞아졌다(1103/02-02). 대신 지속 실패의 자가 회복을 잃었다(02-02) |
|
||||
| 2 | 구조적 성숙도 | 적용 — 배럴 경계, kernel 예외 | M3 / M3 | E2(`check:architecture` rc=0, 오케스트레이터) | P — 새 레시피도 배럴만 import한다(`browser-file-session-capability.ts:1-2`). cross-context 예외가 배럴 전체를 연다(`0929/02-06`, 결정 대기) |
|
||||
| 3 | 변경 용이성 | 적용 — 수명 연결, 정책 추가 | M2 / M2 | E1, E2 | O — 제품 파일만 고쳐 file runtime을 세션에 묶는다(1103/02-01, 로그아웃·계정 전환 모두 확인). 정책·topic은 registry에 더하면 끝난다 |
|
||||
| 4 | 인지 부하 | 적용 — 1.1k~1.2k줄 파일 2개, 수명 규칙 | — / — | E1 | P — 큰 파일 둘(`public-response-cache-adapter.ts` 1,215줄, `download-delivery-adapter.ts` 1,161줄)은 지난 판단대로 둔다. 세션 연결은 레시피 하나를 읽으면 된다. 레시피 주석이 매뉴얼과 다르다(02-03) |
|
||||
| **5** | 위험 가시성 | 적용 — 실패 의미, 세션 수명 | M1~M2 / M1~M2 | E1, E2 | P — 손상 pointer를 inspect가 보인다(1103/02-05). 제품 closer 실패가 안 보인다(02-01) |
|
||||
| **6** | 실패 성숙도 | 적용 — 손상·일시·지속 실패 구분 | M2 / M2 | E1, E2(E-1) | P — 일시 오류와 손상이 갈렸다(1103/02-02). 지속되는 읽기 실패가 일시 오류로 분류돼 끝나지 않는다(02-02). 그 경계를 테스트가 고정하지 않는다(02-04). 제품 closer 실패는 닫히는 쪽으로 처리된다(02-01) |
|
||||
| 7 | 운영 성숙도 | 적용 — 관측 연결 | M2 / M1 | E1, E2(E-3) | P — cross-context 실패 관측은 그대로다. scope reset 실패가 관측에 없다(02-01). file·cache observer는 레시피 조립 몫이다 |
|
||||
| **8** | 디버깅 가능성 | 적용 — reason·operation·label | M2 / M1 | E1, E2(E-3) | P — inspect가 pointer 상태를 준다(고쳐짐). inspect 실패 operation이 여전히 `CACHE_LOOKUP`이다(`public-response-cache-adapter.ts:923`). participant `label`을 아무도 읽지 않는다(02-01) |
|
||||
| 9 | 유지보수 성숙도 | 적용 — 문서·CHANGELOG 정합 | M1 / M1 | E1 | P — 설계 문서 줄 번호가 맞다(고쳐짐). CHANGELOG 0.2.0 행이 그대로 틀렸다(`0929/02-03`). 레시피 주석과 매뉴얼이 다르다(02-03) |
|
||||
| **10** | 테스트 성숙도 | 적용 — 수정 테스트, 변이 | M3 / M3 | E2(영역 unit 12파일·recipe 2파일 통과, 오케스트레이터), E2(변이 31개: 검출 23, 생존 8) | P — 수정이 고쳤다고 한 규칙의 변이 23개를 모두 잡는다. 지난 생존 변이 15개 중 12개가 검출로 바뀌었다. 생존 8개: N38·M05(이월), L11(동등), 02-02 판정 표 경계 5개(02-04). 레시피 capability 전달이 테스트 밖이다(02-03) |
|
||||
| **11** | 데이터 성숙도 | 적용 — pointer·marker·캐시 entry | M2 / M2 | E1, E2 | P — 손상 marker는 다시 stage로 고친다(L7 검출). 지속적으로 읽히지 않는 entry는 고칠 길이 cleanup뿐이다(02-02) |
|
||||
| **12** | 동시성 성숙도 | 적용 — async 경쟁, 탭 간 순서 | M3 / M3 | E1, E2 | O — inspect·release 경쟁이 고쳐졌다(F0204 검출). 조회의 `keys()` 재확인을 잡는다(N39 검출). 같은 ref 두 정책 동시 inspect는 receipt 둘로 끝나고 둘 다 정리된다(결함 아님) |
|
||||
| 13 | 확장성 | 적용 — 상한 값 | M2 / M2 | E1, E2(N29 검출) | O — 상한 값 변경 없음. 합계 바이트 상한에 테스트가 생겼다. 부하 목표 없음 |
|
||||
| 14 | 성능 성숙도 | 적용 — 레시피 번들, 관리 연산 비용 | M2 / M2 | E2(FE-GATE-012 PASS, 오케스트레이터) | P — service-worker-pwa 9,758 / 10,100(여유 342 B), file-transfer 56,130 / 57,800 gzip B(여유 1,670 B). `inspect()`·`cleanupOwned()`에 cursor·deadline이 없다(`0929/02-02`) |
|
||||
| **15** | 보안 성숙도 | 적용 — 세션 경계, 위험 확장자, 익명 캐시 | M2~M3 / M2~M3 | E1, E2 | P — 로그아웃·계정 전환 때 file runtime이 닫힌다(1103/02-01, E-2). 위험 확장자 정책을 거절한다(F110102 검출). 익명 캐시의 `no-cache`·`Set-Cookie` 거절을 잡는다(N26b·N26 검출). media type 짝은 보지 않는다(`1101/02-02`). host `storageArea` 비교는 테스트 밖이다(N38 생존) |
|
||||
| 16 | 의존성 성숙도 | 적용 제외 — 세 폴더의 외부 패키지 import 0건(grep) | — | E1 | - |
|
||||
| **17** | API / Contract 성숙도 | 적용 — 포트·제품 확장 계약 | M2 / M2 | E1 | P — `activePointer`, `scopeParticipants`가 [계약] CHANGELOG 행과 함께 생겼다(`CHANGELOG.md:179`, `:188`). `ProductScopeParticipant.label`은 계약에만 있고 쓰이지 않는다(02-01). CHANGELOG 0.2.0 행(`0929/02-03`) |
|
||||
| 18 | 배포 성숙도 | 적용 — 배포·rollback, 게이트 | M2 / M2 | E2(FE-GATE-020 rc=0, E-1c) | P — release 단계가 기다리는 FE-GATE-020이 통과한다(고쳐짐). rollback 대상에 읽히지 않는 entry가 있으면 되돌릴 수 없다(02-02, E-1c). Service Worker drain 조합은 범위 밖이다 |
|
||||
| 19 | 설정 성숙도 | 적용 — 정책 조합 검증 | M3 / M3 | E1, E2 | P — 위험 `safeExtension`이 조립 때 `TypeError`다. media type 짝은 통과한다(`1101/02-02`) |
|
||||
| 20 | 개발자 경험 | > 영역 14 — 레시피 주석과 매뉴얼 불일치(02-03)는 이 영역에서 센다 | — | — | > |
|
||||
| **21** | Guardrail 성숙도 | 적용 — 제거 드릴, kernel 예외 | M3 / M3 | E2(FE-GATE-020, `check:architecture`) | P — 제거 드릴 5개가 통과한다(고쳐짐). 문서를 읽는 테스트 제외 목록은 손으로 관리한다(`removal-fixture.ts:70-73`). 새 문서 테스트를 빠뜨리면 capability 드릴이 ENOENT로 시끄럽게 실패한다. 조용히 통과하지는 않는다 |
|
||||
| 22 | 추상화 성숙도 | 적용 — lease registry, 세션 getter | — / — | E1 | P — getter capability가 "부팅 때 한 번"과 "세대마다 새 runtime"을 잇는다. registry에 닫힘 상태가 없는 것은 지난 결정대로다(지난 라운드 5.2). 소비자 쪽 재확인(L4·L5)에 이제 테스트가 있다 |
|
||||
| 23 | 일관성 | 적용 — 실패 분류 | — / — | E1, E2 | P — 같은 본문 읽기 오류가 조회·활성화·stage에서 같은 code다(고쳐짐). `QUOTA_EXCEEDED`의 recovery가 `READ_ONLY`와 `ONLINE_ONLY`로 갈린다(`result.ts:80-85`, `public-cache-codec.ts:597-603`, 지난 라운드와 같음) |
|
||||
| **24** | 네이밍 / 의미 성숙도 | 적용 — 실패 이름이 약속하는 것 | M2 / M2 | E1, E2(E-1) | P — `RETRY`·`REOPEN`이 지속 실패에서는 지켜지지 않는다(02-02). `verified:false`가 판정 불가를 합친다(`0929/02-02`, M05 생존) |
|
||||
| 25 | 조직 확장성 | 적용 제외 — 1인 관리 | — | — | - |
|
||||
| 26 | Ownership 성숙도 | > 영역 12 | — | — | > |
|
||||
| **27** | 삭제 가능성 | 적용 — 제거 드릴 | M3 / M3 | E2(FE-GATE-020 rc=0, junit 5개 failures 0) | O — browser-files·cache-storage·포트·새 레시피를 지운 fixture에서 7개 검사가 모두 통과한다. 지난 라운드 P(드릴 거짓 실패)에서 올라갔다. 실제 Gitea 러너는 미실행 |
|
||||
| **28** | 회복 가능성 | 적용 — 손상 pointer·marker·entry 회복 | M2 / M2 | E1, E2(E-1) | P — 손상 marker 회복(L7)과 손상 pointer 진단(F0205)이 고정됐다. 지속적으로 읽히지 않는 entry는 다시 stage로 회복하지 못한다(02-02). 바이트가 바뀐 후보의 stage 회복은 테스트가 고정하지 않는다(02-04) |
|
||||
|
||||
집계(이 영역에서 판정한 24개): O 4(3, 12, 13, 27) · P 20 · X 0 · ? 0. 적용 제외 2(16, 25) · 다른 영역 2(20, 26). 지난 라운드 대비: 27번 P → O(02-06 수정), 3번 P → O(1103/02-01 수정), 12번 P → O(1103/02-04 수정). 18번은 P 유지(원인이 02-06에서 02-02로 바뀜). 7번 확인 통제가 M2 → M1로 내려갔다(02-01).
|
||||
|
||||
## 5. 미검증
|
||||
|
||||
| 항목 | 왜 확인하지 못했나 | 확인하려면 |
|
||||
| --- | --- | --- |
|
||||
| 실제 브라우저에서 Cache Storage 본문 읽기 실패가 지속되는지, 어떤 오류 이름으로 오는지(02-02의 발생 가능성) | 실기에서 blob 손실을 만들지 않았다. E-1은 메모리 fake에 오류를 주입했다 | 브라우저별 프로필에서 cache entry의 blob 파일을 지운 뒤 `response.arrayBuffer()` 결과를 본다 |
|
||||
| 레시피를 조립한 실제 화면에서 로그아웃 뒤 파일·download가 닫히는지 | 조립 코드가 없다. E-2와 레시피 테스트는 jsdom이다 | file-transfer 레시피를 조립한 제품 E2E |
|
||||
| `FAILED` scope가 화면에서 어떻게 보이는지 | 영역 08·09 몫 | `FAILED` 주입 뒤 화면 상태 확인 |
|
||||
| FE-GATE-020이 실제 Gitea 러너에서 같은 결과인지 | 러너가 없다 | 러너의 merge job |
|
||||
| N38(host `storageArea`)을 실제 브라우저 spec이 잡는지 | `cross-context-invalidation.spec.ts`의 두 테스트에 sessionStorage 이벤트를 거절하는 경우가 없다(정적) | spec에 sessionStorage `storage` 이벤트 행 추가 |
|
||||
|
||||
## 6. 실행 기록
|
||||
|
||||
### 6.1 오케스트레이터 게이트 결과(인용)
|
||||
|
||||
| 출처 | 결과 |
|
||||
| --- | --- |
|
||||
| merge-48(CI env) FE-GATE-020 | rc=0, 1,156초. `removability: PASS`. junit 5개 failures 0(snapshot 시각 19:25~19:39) |
|
||||
| merge-48 FE-GATE-001~012 | 모두 rc=0. FE-GATE-007(`test:recipes`): `optional-recipes.xml` 77건 failures 0, 그중 `browser-file-session-capability.test.ts` 1, `browser-file-storage-contracts.test.ts` 13. FE-GATE-008: browser capability 66건 failures 0, 이 영역 spec 21건(`browser-files` 3, `cross-context-invalidation` 2, `public-cache-storage` 2 × chromium·firefox·webkit). FE-GATE-012: `Optional recipes: PASS`, file-transfer 56,130 / 57,800, service-worker-pwa 9,758 / 10,100 gzip B |
|
||||
| merge-48 FE-GATE-013 | rc=1. `test:system` 114건 중 18건 실패, 원인은 host bwrap(오케스트레이터 판정). 이 영역과 무관 |
|
||||
| 로컬 env 목록 | `check:architecture`·`check:types`·`lint`·`test:unit`·`test:component`·`test:integration`·`test:contract`·`test:runtime-schema`·`check:adapter-inventory`·`check:ci` rc=0. `test:unit` 194파일 2,883건, 이 영역 unit 12파일 통과. `verify:documentation`은 desktop의 짝 백엔드 checkout 옆에서 실패(오케스트레이터 몫) |
|
||||
|
||||
### 6.2 배치 02-R1(변이)
|
||||
|
||||
명령 `node /tmp/claude-gates/r4/mut/02-runner.mjs`, 변이 스크립트 `02-mut.sh`(임시 테스트 3개 생성), env local. 오케스트레이터 실행: 2026-11-05 20:01, 부하 1.48, rc=0, 59초, 앞뒤 checkout 깨끗(`8a44226`, git status 빈 상태). 스크립트 사본과 결과: `scratchpad/r4-02/`, `scratchpad/r4/results/02/`(`02-R1.log`, `02-mut-result.json`).
|
||||
|
||||
대조 실행(변이 없음): BF 8파일 93건, CS 4파일 59건, CX 3파일 46건, BOOT 4파일 38건 모두 rc=0. 각 변이는 파일 한 곳을 바꾸고 해당 묶음을 돌린 뒤 원본으로 되돌렸다.
|
||||
|
||||
| ID | 바꾼 규칙 | 결과 | 잡은 테스트 / 연결 |
|
||||
| --- | --- | --- | --- |
|
||||
| L1 | vault `dispose()`가 File 참조 Map을 비우지 않음 | 검출 | "lets go of every selected File on dispose" / 1103/02-03 |
|
||||
| L4 | preview가 resolve 뒤 `#disposed`를 다시 보지 않음 | 검출 | "creates no object URL for a preview whose runtime is disposed while it resolves" / 1103/02-03 |
|
||||
| L5 | vault `resolveFile`이 load 뒤 `#disposed`를 다시 보지 않음 | 검출 | "opens no byte source for a file whose vault is disposed while it loads" / 1103/02-03 |
|
||||
| L6 | `cleanupOwned()`가 손상 pointer를 "없음"으로 보고 정리 | 검출 | "does not clean up on a damaged pointer…" / 1103/02-03 |
|
||||
| L7 | stage가 손상 marker를 고치지 않고 실패 | 검출 | "repairs a damaged release marker by staging the same manifest again" / 1103/02-03 |
|
||||
| F0204 | inspect의 ref 재확인 삭제(1103/02-04 되돌림) | 검출 | "issues no receipt for a ref released while inspect() was reading it" |
|
||||
| L11 | `resolveVerifiedFile`이 ref 존재를 보지 않음 | 생존(동등) | release가 receipt를 먼저 지우고 inspect가 놓은 ref에 receipt를 내지 않는다(2절) |
|
||||
| N27 | 재검사 때 이전 receipt 무효화 삭제 | 검출 | "ends the previous receipt when the same file is inspected again" / 1101/02-04 ③ |
|
||||
| N29 | object URL 합계 바이트 상한 삭제 | 검출 | "caps retained files and aggregate object URL leases" / 1101/02-04 ① |
|
||||
| N30 | browser-managed handoff의 fragment 거절 삭제 | 검출 | "rejects cross-origin or query-bearing browser-managed targets" / 1101/02-04 ⑥ |
|
||||
| N26b | `Cache-Control: no-cache` 거절 삭제 | 검출 | "keeps response validation failure codes" / 1101/02-04 ④ |
|
||||
| N26 | `Set-Cookie` 응답 거절 삭제 | 검출 | 같은 테스트 / 1101/02-04 ⑦ |
|
||||
| N39 | 조회가 eviction 판정 전 `keys()`를 다시 읽지 않음 | 검출 | "lists caches again before it reports the active release evicted" / 1101/02-04 ⑤ |
|
||||
| N38 | host가 `storageArea`를 캡처한 localStorage와 비교하지 않음 | **생존** | 1101/02-04 ② |
|
||||
| M10 | bounded download catch의 `lease?.release()` 삭제 | 검출 | "revokes the lease of a handoff that throws" / 0929/02-05 |
|
||||
| M05 | `inspect()`의 판정 불가를 `verified:true`로 | **생존** | 0929/02-02 |
|
||||
| F110102 | download 정책의 위험 확장자 검사 삭제(1101/02-02 되돌림) | 검출 | "refuses a download policy whose safe extension is %s" 3건 |
|
||||
| F110102b | `endsWith`를 정확히 같은지로 | 검출 | 같은 테스트의 `.tar.js` 행 |
|
||||
| F0202 | 본문 읽기 실패를 다시 `REPAIRABLE`로(1103/02-02 되돌림) | 검출 | "reports a cached body that cannot be read during activation as retryable…" |
|
||||
| F0202-notreadable | 손상 목록에 `NOT_READABLE` 더함 | **생존** | 02-04 |
|
||||
| F0202-int | 손상 목록에서 `INTEGRITY_FAILED` 뺌 | **생존** | 02-04 |
|
||||
| F0202-cor | 손상 목록에서 `CORRUPT_DATA` 뺌 | **생존** | 02-04 |
|
||||
| F0202-pol | 손상 목록에서 `POLICY_REJECTED` 뺌 | **생존** | 02-04 |
|
||||
| F0202-lim | 손상 목록에서 `LIMIT_EXCEEDED` 뺌 | **생존** | 02-04 |
|
||||
| F0205 | inspect가 손상 pointer에서 다시 실패(1103/02-05 되돌림) | 검출 | "shows a damaged pointer and the candidates it leaves behind in inspect" |
|
||||
| F0205b | inspect가 일시 오류도 `UNREADABLE`로 | 검출 | 같은 테스트 |
|
||||
| F0205c | `activePointer` `NONE`을 `READABLE`로 | 검출 | 같은 테스트 |
|
||||
| F0201a | 제품 participant 등록 누락 | 검출 | 레시피 테스트와 participant 테스트 2건(3건 실패) |
|
||||
| F0201b | 제품 participant 실패를 삼킴 | 검출 | "keeps the scope from READY when one fails, and still closes the rest" |
|
||||
| F0201c | 첫 실패에서 나머지를 부르지 않음 | 검출 | 같은 테스트 |
|
||||
| F0201d | 레시피 closer가 dispose하지 않음 | 검출 | 레시피 테스트 |
|
||||
| F0201e | 레시피 closer가 runtime을 비우지 않음 | 검출 | 레시피 테스트 |
|
||||
|
||||
집계: 31건, 검출 23 · 생존 7 · 동등 1. 지난 라운드에 살아남았던 변이 15개(1103/02-03의 L1·L4·L5·L6·L7, 1103/02-04의 L11, 1101/02-04의 N26·N26b·N27·N29·N30·N38·N39, 0929/02-02의 M05, 0929/02-05의 M10)는 12개가 검출, 2개(N38·M05)가 생존, 1개(L11)가 동등으로 바뀌었다. 생존 7개 중 5개는 이번 수정이 만든 판정 표의 경계다(02-04).
|
||||
|
||||
### 6.3 배치 02-R1(실험)
|
||||
|
||||
| ID | 방법 | 결과 |
|
||||
| --- | --- | --- |
|
||||
| E-1a | 메모리 Cache Storage. r1 배포, r2 stage. r2의 entry 하나를 다시 쓸 때까지 `TypeError`로 읽히지 않게 함. activate 2회, 재stage 2회, activate, inspect, cleanup, 재stage, activate | 현재 코드: activate 2회 `UNAVAILABLE`/`retry`/`RETRY`, 재stage 2회 같은 실패·fetch 0, activate 실패, inspect `r2:false`, cleanup 삭제 1(r2), 재stage fetch 2 성공, activate 성공. 수정 전 판정(F0202): activate `INTEGRITY_FAILED`/`REHYDRATE`, 재stage 1회 fetch 2로 고쳐짐, activate 성공 |
|
||||
| E-1b | E-1a와 같고 오류가 `NotReadableError` | 현재 코드: activate·재stage 모두 `NOT_READABLE`/`REOPEN`, fetch 0, cleanup 뒤에만 회복. 수정 전 판정: 재stage로 고쳐짐 |
|
||||
| E-1c | r1·r2 배포(rollback 목록에 r1). r1 entry 손상. rollback activate 2회, 재stage, activate, cleanup, activate | 현재 코드: 모두 `UNAVAILABLE`/`RETRY`. cleanup 삭제 0(r1 보존). 끝까지 rollback 불가. 수정 전 판정: 재stage(fetch 2) 뒤 rollback 성공 |
|
||||
| E-1d | 활성 r1 entry 손상. 조회, 재stage, 조회 | 현재 코드: 손상 asset 조회 `UNAVAILABLE`, 다른 asset 조회 hit, 재stage 실패, 조회 계속 실패. 수정 전 판정: 재stage 뒤 조회 hit |
|
||||
| E-2 | `tests/recipes/browser-file-session-capability.test.ts`의 계정 전환을 로그아웃(`unauthenticated`, subject 없음)으로 바꾼 사본 | 통과. 이전 runtime `readRange` `UNAVAILABLE`, 진행 중 download `ABORTED`, handoff 0회, 다음 runtime 선택 `SELECTED` |
|
||||
| E-3 | `tests/unit/runtime-adapters-product-scope-participants.test.ts` 사본에 던지는 closer(`label: "r4-broken-closer"`) 테스트를 더함. 계정 전환, 같은 identity 알림 한 번 더 | phase `FAILED`, lifecycle `FENCED, FAILED, FENCED, FAILED`. diagnostics 기록 전 1건·후 1건(부팅 때의 `cache.operation.failed`). label·scope·participant 언급 0건. dropped 없음 |
|
||||
|
||||
임시 테스트 3개는 runner가 끝에 지웠고, 오케스트레이터가 checkout을 `8a44226`으로 되돌렸다(git status 빈 상태).
|
||||
|
||||
### 6.4 리뷰어의 desktop 시도(실행 안 됨)
|
||||
|
||||
| 이름 | 결과 |
|
||||
| --- | --- |
|
||||
| `02-mut` 1차(19:39 대기 시작) | 잠금 대기 중 19:55에 취소됐다(BRIEF-2). 실행되지 않았고 checkout을 건드리지 않았다 |
|
||||
| `02-mut` 2차(19:48, `nohup`) | rc=93 `CLOSED: exp.sh no longer runs experiments`. 같은 내용을 배치 02-R1로 넘겼다 |
|
||||
|
||||
## 7. 새 발견 요약
|
||||
|
||||
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 02-01 | Medium · P2 | 확인된 결함(진단 공백) | 제품 scope closer가 던지면 scope가 진단 없이 `FAILED`로 멈추고 `label`은 쓰이지 않는다 | `src/bootstrap/runtime-adapters.ts:409-423`, `src/adapters/query-cache/server-state-scope-runtime.ts:136-171`, `src/bootstrap/product-composition-contract.ts:100-103` |
|
||||
| 02-02 | Low · P3 | 구조적 위험 | 계속 읽히지 않는 캐시 본문은 다시 stage해도 고쳐지지 않고 rollback 대상은 회복 길이 없다 | `src/adapters/cache-storage/public-response-cache-adapter.ts:492-497`, `:1083-1088`, `:1139-1144` |
|
||||
| 02-03 | Low · P3 | 확인된 결함 | 세션 레시피 주석이 매뉴얼이 막는 보강 방식을 가리키고 capability 전달은 테스트 밖이다 | `recipes/frontend-capabilities/browser-file-session-capability.ts:21-30`, `tests/recipes/browser-file-session-capability.test.ts:142` |
|
||||
| 02-04 | Low · P3 | 구조적 위험(테스트 공백) | 1103/02-02의 손상 code 목록 경계 변이 5개가 살아남는다 | `src/adapters/cache-storage/public-response-cache-adapter.ts:1083-1088`, `tests/unit/public-response-cache-repair.test.ts:236-263`, `:320` |
|
||||
@@ -0,0 +1,205 @@
|
||||
# 영역 03 — HTTP·서버 상태·인증·진단
|
||||
|
||||
> 검토일 2026-11-05 · 기준 `8a44226`(`fix/maturity-review-2026-11-03`) · 가이드 `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/bootstrap/runtime-adapters.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`, `src/contracts/external-contract-runtime.ts`, 참조 기능, `scripts/create-feature.ts`·`scripts/create-feature-write-slice.ts`, `config/contracts/backend-contract-pin.json`·`backend-idempotency-answers.json`, 짝 백엔드 `45d2a478`의 `docs/web/http-contract.md`·생성기 템플릿·`RateLimitInterceptor.java`
|
||||
> 깊게 본 관점 5, 6, 10, 12, 17, 20, 21, 28
|
||||
> 렌즈: 지난 High 둘(1103/03-01 = 08-01, 0929/03-03)을 선언부터 화면까지 따라간다. 503 `IDEMPOTENCY_COMPLETION_UNKNOWN`(지난 README 10.6)과 1103/03-04. 나머지 1103/03-*와 이월 항목
|
||||
> **영역 판정(35.8): 조건부 사용 가능.** 짝 백엔드 쓰기 폼은 이제 쓸 수 있다. `create:feature --with-create`(NEVER, `--keyed`면 KEYED)가 만든 폼과 참조 폼 모양이 여기에 든다. 조건은 둘이다. (1) 폼 밖에서 `mutation.submit`을 부르는 쓰기 화면은 결과 불명 동안 같은 입력의 제출을 스스로 막는다. 키 없는 쓰기(NEVER)면 그 제출이 보호 없는 두 번째 요청이 된다(0929/03-03 남은 부분). (2) `refusedBeforeWrite`에는 백엔드 코드에서 쓰기 전에만 나온다고 확인한 업무 code만 적는다. 쓰기 뒤에도 나오는 플랫폼 code를 적어도 조립이 막지 않는다(03-01). bulk 응답은 지원하지 않는다(1103/03-02, 문서화).
|
||||
|
||||
ID 표기: `03-NN`은 이번(2026-11-05) 라운드 발견이다. 지난 라운드는 `1103/03-NN`, 그 전은 `1101/03-NN`, `0929/03-NN`이다.
|
||||
|
||||
**실행 상태.** 처음 넣은 desktop 실행(`03-mut`, `03-gen`)은 큐에서 취소됐다(BRIEF-2). 변이와 실험은 오케스트레이터 배치로 돌렸다(03-R01~03-R18, `scratchpad/r4/requests/03.md`). 18건 모두 매 항목 앞뒤로 checkout이 `8a44226`으로 깨끗하게 복원됐다(`scratchpad/r4/results/03/summary.txt`). 대조군(변이 없는 실행)은 게이트 로그로 갈음했다. `test:unit` 2,883건, `test:component` 270건, `test:integration` 189건이 `8a44226`에서 rc=0이다. 변이 대상 파일 9개도 모두 통과로 찍혀 있다(`desktop:/tmp/claude-gates/r4/gates/test_{unit,component,integration}.log`, 오케스트레이터 결과). 생성 기능 쪽 대조군은 03-R02 안에서 돌렸다.
|
||||
|
||||
## 0. 결론
|
||||
|
||||
- **1103/03-01(= 08-01, High·P1)은 완료 기준까지 고쳐졌다.** operation이 `commandEffect.refusedBeforeWrite`에 쓰기 전 업무 code를 적는다(`src/contracts/external-contract-runtime.ts:161-171`). 표 밖 400·409·422 중 적힌 code만 `NOT_APPLIED`다(`src/adapters/http/backend-envelope.ts:317-352`). 실행기가 설치된 목록을 넘긴다(`src/adapters/http/http-execution-v3.ts:1723-1727`). 조립은 Envelope 아닌 operation, 멱등성 code, 문법 위반, 중복을 거절한다(`external-contract-runtime.ts:616-646`). 폼 테스트가 끝까지 고정한다. 선언 code면 저장 버튼이 켜지고 fetch 2회, 키 `[key-1, key-2]`다. 선언하지 않은 code면 꺼진 채다(`tests/component/form-foundation.test.tsx:960-1008`). 생성기는 `<FEATURE>_INVALID`를 적고 필드 오류로 보인다(`scripts/create-feature-write-slice.ts:306`, `:397-404`). 규칙을 깨는 변이 6개가 모두 기대한 테스트에서 실패했다. 판정을 끈 변이, 실행기가 목록을 넘기지 않는 변이, 런타임과 조립의 멱등성 code 거절을 뺀 변이, 생성기 선언을 지운 변이, 생성한 기능에서 선언 줄을 지운 변이다(03-R02 G1, 03-R03~R06, 03-R18).
|
||||
- **0929/03-03(High·P1)은 화면 버튼 쪽만 고쳐졌다(일부).** 훅이 키 없는 intent에 재전송을 주지 않는다(`application-query.ts:800-804`, `:836-846`). 화면은 플래그가 `false`면 버튼을 그리지 않는다(`async-surface.tsx:225-231`). 두 가드를 깨는 변이는 템플릿 테스트와 생성 NEVER 페이지 테스트에서 모두 검출됐다(03-R07, R08, R02 M08·M09). 남은 길이 있다. 같은 입력을 다시 `submit`하면 훅은 키 없는 결과 불명 intent를 그대로 다시 보낸다(`application-query.ts:557-561`, `:590-596`). 실험 X1: 재전송은 `null`인데 같은 입력 `submit`이 두 번째 POST를 보냈다. 두 요청 모두 키가 없다(`keys=[null,null]`, 03-R01). 폼(`use-app-form.ts:325`)과 두 페이지가 막을 뿐 훅은 막지 않는다. 남은 부분은 Medium·P2로 본다.
|
||||
- **503 `IDEMPOTENCY_COMPLETION_UNKNOWN`과 1103/03-04는 고쳐졌다.** 백엔드가 정한 5xx 넷을 status와 code를 함께 맞춰 `MAYBE_APPLIED`로 고정한다(`backend-envelope.ts:246-280`). 분류기가 `NOT_APPLIED`라고 해도 바뀌지 않고 자동 재전송도 없다(`tests/integration/http-execution-v3-envelope.test.ts:634-697`, `:912-933`). 백엔드 답 표 사본과 양방향으로 대조하는 테스트가 생겼다(`tests/unit/backend-contract-pin.test.ts:105-142`). 사본 7행은 백엔드 `45d2a478` §2 두 표와 §4 `REQUEST_TIMEOUT`과 같다. `COMPLETION_UNKNOWN` 행을 지운 변이는 단위·pin·통합 테스트 6건이 잡았다(03-R09).
|
||||
- **나머지 1103/03-*:** 03-02 일부(bulk는 미지원으로 문서화), 03-03 고쳐짐, 03-05 고쳐짐, 03-06 고쳐짐(VD-23 부분은 14 영역), 03-07 일부(백엔드 목록 GET 결정 대기), 03-08(= 10-02) 03 부분 고쳐짐. 이월: 1101/03-03·1101/03-06·0929/03-06 고쳐짐, 1101/03-04·0929/03-02 남음.
|
||||
- **새 발견은 2건, 모두 Low·P3다.** 03-01: `refusedBeforeWrite`가 프론트 자신의 6.1절 표가 "쓰기 뒤 가능"으로 적은 플랫폼 code(`BAD_PARAMETER`, `MAPPING_FAILED`, `DB_*`, `LOCK_ACQUISITION_TIMEOUT`)도 받는다. 03-02: 백엔드 §4의 rate-limit 503 두 code가 답 표 밖이라, 생성 기능의 쓰기는 실행 전 거절을 결과 불명으로 보인다. 둘 다 실험으로 확인했다(X2, X4, 03-R01).
|
||||
- **변이 19개가 모두 검출됐다.** 템플릿 테스트 대상 16개(03-R03~R18)와 생성 기능 대상 3개(03-R02)다. 지난 라운드의 생존 변이 넷도 이제 잡힌다. M1 identity lease(03-R12), M3 반사 correlation 문법(03-R13), M6 표의 status 대조(03-R10), M7 처리 중 409 무재전송(03-R11)이다.
|
||||
- **고친 커밋이 이 영역의 검사를 약하게 만든 곳은 찾지 못했다.** 지워진 단언은 다른 발견(1103/08-02, 08-05)의 동작 변경에 맞춘 교체였다(2절 끝).
|
||||
|
||||
## 1. 범위 (36.1)
|
||||
|
||||
| 항목 | 기록 |
|
||||
|---|---|
|
||||
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`. 짝 백엔드 `clean-architecture-backend-template`은 읽기만 했다 |
|
||||
| 커밋·작업 상태·확인 시점 | 프론트 `8a44226`(laptop worktree, HEAD = 기준). 백엔드 HEAD `45d2a478` = `config/contracts/backend-contract-pin.json`의 commit. 2026-11-05 19~20시 |
|
||||
| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음. 사용자 목표는 두 템플릿을 짝으로 써서 빨리 출시하는 것 |
|
||||
| 필수 요구와 규모·운영 목표 | 짝 백엔드 `docs/web/http-contract.md` §1·§2·§4, 프론트 계약 `docs/architecture/backend-api-and-server-state-contract.md` 4.1·6·6.1, 매뉴얼 `docs/manual/02-decision-tables.md` 3·4절. 수치 운영 목표는 없다 |
|
||||
| 읽은 코드·구성 범위 | 줄 단위: `backend-envelope.ts` 전부, `http-execution-v3.ts` 450~520·1440~1510·1700~1810, `feature-http-binding.ts` 280~575, `external-contract-runtime.ts` 155~175·450~670·800~845, `api-operations.ts` 125~143, `application-query.ts` 340~400·520~850·860~940, `use-app-form.ts` 170~400, `async-state.ts` 60~140, `async-surface.tsx` 120~235, `runtime-adapters.ts` 180~260·560~660, `fileserver-upload.ts` 150~200·685~705, 참조 폼 페이지·계약 기여·`use-reference-feature.ts`, `create-feature-write-slice.ts` 1~320·380~420·600~1010, `create-feature.ts` 40~160·760~830·1740~1800, `test-feature-scaffold.ts`·`test-sample-removal.ts`의 생성 부분, 위 수정의 테스트 9개 파일. `git diff e40684b..8a44226`(영역·흐름 20파일, +2,129/−277). 백엔드: `http-contract.md` §1~§4, 생성기 템플릿(UseCase·ErrorCode·RejectedException·Controller·HttpRequest), `new-feature.sh` 이름 변환, `RateLimitInterceptor.java`, `CorsSettings.java`. `src/adapters/auth`는 주석만, `browser-rpc`·`query-cache`·`diagnostics`·`telemetry`는 `e40684b` 뒤 변경이 없다(`git diff --stat`) |
|
||||
| 수행한 테스트·실험 | 실행 환경 = desktop. 이 영역이 직접 돌린 `03-mut`, `03-gen`은 큐에서 취소됐다. 오케스트레이터 배치 03-R01(실험 X1~X4), 03-R02(생성 NEVER 슬라이스 + 변이 3), 03-R03~R18(변이 16)을 돌렸다(6절). 게이트는 오케스트레이터 결과를 인용한다. local env에서 `check:architecture`·`check:types`·`lint`·`test:unit`·`test:component`·`test:integration`·`test:contract`·`test:runtime-schema`·`check:adapter-inventory`·`check:ci`는 rc=0이다. `verify:documentation`은 rc=1이다(desktop에 짝 백엔드 형제 디렉터리가 없어 문서의 백엔드 경로를 못 찾음, 이 영역의 결함이 아니다). CI env에서 FE-GATE-001~012·020은 rc=0이고 FE-GATE-013은 rc=1이다(13 영역) |
|
||||
| 확인하지 못한 범위·이유 | 5절 |
|
||||
| 이전 리뷰와 비교 가능한 범위 | `e40684b..8a44226`의 영역 커밋 34개(`git log --oneline -- <경로>`). 지난 실행 결과는 증거로 쓰지 않았다 |
|
||||
|
||||
## 2. 지난 발견 재확인
|
||||
|
||||
지난 라운드 README 12절의 03 행 8개, 10.3절에서 합친 08-01·10-02, 지난 03 문서 2절이 "남음"으로 적은 이월 6개다. 13절 추가 발견 중 03 영역은 없다. README 14.4는 주장으로만 봤다.
|
||||
|
||||
| 지난 ID | 내용 | 상태 | 근거 |
|
||||
|---|---|---|---|
|
||||
| 1103/03-01 (= 1103/08-01) High·P1 | 짝 백엔드의 업무 규칙 거절(표 밖 400·409·422)이 모든 쓰기에서 결과 불명이 된다 | **고쳐짐** (변이 6개 검출: 03-R02 G1, 03-R03~R06, 03-R18) | 완료 기준 넷을 코드와 테스트로 확인했다. ① 선언한 code는 결과 불명이 아니고 저장 버튼이 켜진다. 고친 값의 두 번째 요청은 새 키다(`form-foundation.test.tsx:960-987`, 키 `["key-1","key-2"]`). ② 선언하지 않은 code는 결과 불명이다(`:989-1008`, `http-execution-v3-envelope.test.ts:749-765`). ③ 처리 중 409를 목록에 넣으면 조립이 실패한다(`tests/unit/external-contract-runtime.test.ts:274-284`, 거절 `external-contract-runtime.ts:637-641`). 실행기도 따로 무시한다(`backend-envelope.ts:323-324`). ④ 생성기와 매뉴얼: 생성 create가 `refusedBeforeWrite: ["<FEATURE>_INVALID"]`를 적고(`create-feature-write-slice.ts:306`) `mapProblem`이 이름 필드 오류로 바꾼다(`:397-404`). 생성 테스트가 "필드에 보이고 다시 저장"을 고정한다(`:864-886`). 이 테스트는 `test:sample-removal`(NEVER, `scripts/test-sample-removal.ts:496-503`)과 `test:feature-scaffold`(KEYED, `scripts/test-feature-scaffold.ts:64-69`)에서 돈다. FE-GATE-020 rc=0(오케스트레이터). 매뉴얼 `02-decision-tables.md:122`, `:179-185`, `01-add-a-feature.md:223`, `:359`. 백엔드 쪽 사실: `<FEATURE>_INVALID`를 던지는 곳은 `build()` 하나이고 트랜잭션 전이다(`Create__Feature__UseCase.java.tmpl:52-60`, `__Feature__RejectedException.java.tmpl:21-27`). 남은 것: 선언하지 않은 업무 code는 설계대로 결과 불명이다(완료 기준). 화면 쪽 막다른 길은 08 영역이 본다. 플랫폼 code 선언을 막지 않는 것은 새 03-01이다. 변이 결과: M01(판정 끔)은 단위 3·통합 3·폼 1건, M06(실행기가 목록을 안 넘김)은 통합 3·폼 1건, M02(런타임 멱등성 접두사 거절 제거)는 "never lets a declaration decide an idempotency answer or a table code", M04(조립 거절 제거)는 멱등성 code 5개 `it.each`, M22(생성기 선언 제거)는 `create-feature.test.ts` "matches the backend scaffold's NOT_IDEMPOTENT create with a NEVER command"가 잡았다. 생성한 `memo-feature`에서 선언 줄을 지우면(G1) 생성 테스트 "shows the backend's refusal of the name on the field and saves again"과 "reads 400 MEMO_INVALID as not applied, on the name field"가 실패한다. 변이 없는 생성 테스트는 4 files / 21 tests 통과(03-R02 BASELINE) |
|
||||
| 0929/03-03 High·P1 | 결과 불명 화면의 "같은 요청으로 다시 보내기"가 키 없는 쓰기에도 열려 있다 | **일부** (가드 변이 4개 검출: 03-R07, R08, R02 M08·M09. 남은 길 실험 03-R01) | 고쳐진 것: `canResend`가 intent의 키를 본다(`application-query.ts:836-846`). 없으면 `resendUnknownEffect`가 `null`이다(`:800-804`). 훅이 `canResendUnknownEffect`와 `state.unknownEffectResendable`을 낸다(`:806-828`, `async-state.ts:132-138`). 화면은 `false`면 버튼을 그리지 않는다(`async-surface.tsx:225-231`). 테스트: `application-mutation-admission.test.tsx:541-564`, `async-surface.test.tsx:105-136`, 생성 NEVER 페이지 테스트(`create-feature-write-slice.ts:754-770`). KEYED는 그대로 같은 키로 보낸다(`application-mutation-admission.test.tsx:503-539`). NEVER intent에 키를 넣는 길도 없다. 정책이 descriptor에서 키 여부를 받고(`src/contracts/server-state.ts:281-299`), 실행기가 NEVER intent의 키를 보내기 전에 거절한다(`http-execution-v3.ts:507-512`). **남은 것 ①** 같은 입력의 재제출. `submit`은 같은 canonical input의 결과 불명 admission을 찾아 그 intent를 그대로 쓴다(`application-query.ts:557-561`, `:590-596`). 키 없는 intent면 서버가 가려낼 수 없는 두 번째 요청이다. 훅은 이것을 막지 않는다. 막는 곳은 폼(`use-app-form.ts:325`, `unknownSubmissionRef`)과 두 페이지의 버튼·`onSubmit` 검사뿐이다(`reference-resource-form-page.tsx:52-66`, `create-feature-write-slice.ts:656-669`). 런북 6.3-4는 같은 입력 재저장을 "같은 `Idempotency-Key`로 보낸다"고만 적고 키 없는 경우를 적지 않는다(`docs/operations/api-contract-and-server-state-recovery.md:254-260`). 고친 커밋도 이 경로를 바꾸지 않았다고 적었다(`2017ef76` 본문 "위험·한계"). 실험 X1(03-R01): NEVER 쓰기의 첫 요청이 보낸 뒤 연결이 끊겼다. 결과 불명이 되고 `canResendUnknownEffect=false`, `resendUnknownEffect()`는 `null`, fetch는 1회 그대로였다. 그 뒤 같은 입력을 `submit`하자 fetch 2회, 키 `[null,null]`, 두 번째 응답 성공이다. 첫 요청이 실제로 적용됐다면 `NOT_IDEMPOTENT`인 짝 백엔드 create에는 같은 항목이 둘 생긴다(추론. 실험은 fetch mock이다). 같은 실험의 KEYED는 재전송이 같은 키(`key-1`, `key-1`)를 썼다. **남은 것 ②** 손으로 만든 AsyncState(플래그 없음)는 지금도 버튼을 그린다(`async-surface.tsx:227`의 `!== false`. 실험 X3(03-R01): `deriveAsyncState({ data, hasMutationEffectUnknown: true })`로 그리면 버튼이 있다). 콜백이 `resendUnknownEffect`면 `null`이라 보내지는 않는다. 남은 부분의 심각도는 Medium·P2로 본다. 템플릿의 폼 경로는 막혀 있고, 폼 밖에서 `submit`을 다시 부르는 손으로 만든 화면이어야 닿는다. 닿으면 피해는 중복 생성이다. 최소 개선: 훅의 `submit`이 키 없는 결과 불명 admission과 같은 입력이면 보내지 않고 `UNKNOWN_EFFECT_PENDING` 같은 `NOT_STARTED` 실패를 돌려준다. 런북 6.3-4에 키 없는 경우를 적는다 |
|
||||
| 1103/03-02 Medium·P2 | Envelope 읽기가 `meta.page`를 버리고 bulk `results`를 거절한다 | **일부** (bulk는 미지원으로 문서화. 변이 검출 03-R15) | `meta.page`를 백엔드 범위(정수, `size` 1~100)로 읽고 범위 밖이면 버린다(`backend-envelope.ts:21-28`, `:49`, `:96-116`). 실행 결과에 `page`가 실리고(`http-execution-v3.ts:1454-1468`, `:1509`) `mapSuccess(value, { page })`로 간다(`feature-http-binding.ts:419-428`). 생성 목록은 `page?.total ?? items.length`를 쓰고 화면이 그 수를 보인다(`create-feature.ts:694-697`, `:1203`). 테스트 `http-execution-v3-envelope.test.ts:347-387`. bulk: 계약 4.1이 "지원하지 않는다, `ENVELOPE_MISMATCH`"로 적었다(`backend-api-and-server-state-contract.md:188-190`). README 14.4와 같은 판정이다 |
|
||||
| 1103/03-03 Medium·P2 | 쓰기 operation을 `SAFE`로 설치할 수 있다 | **고쳐짐** (변이 검출 03-R14: "rejects SAFE retry semantics on a POST·PUT·PATCH·DELETE" 4건) | 조립이 쓰기의 `SAFE`를 거절한다(`external-contract-runtime.ts:564-571`). 읽기는 `SAFE`·`IDEMPOTENT`만 받는다(`:533-543`). 테스트 `external-contract-runtime.test.ts:181-200`. 생성 쓰기는 `NEVER`/`KEYED`다(`create-feature-write-slice.ts:227-236`) |
|
||||
| 1103/03-04 Low·P2 (+ 지난 README 10.6 503 `IDEMPOTENCY_COMPLETION_UNKNOWN`) | 백엔드의 다른 멱등성 실패와 503 `REQUEST_TIMEOUT`이 패키지 분류기에 달려 있다 | **고쳐짐** (변이 검출 03-R09: 단위 2·pin 1·통합 3건) | `MAYBE_APPLIED_ANSWERS` 네 행(503 `IDEMPOTENCY_UNAVAILABLE`, 503 `IDEMPOTENCY_COMPLETION_UNKNOWN`, 500 `IDEMPOTENCY_RECOVERY_REQUIRED`, 503 `REQUEST_TIMEOUT`)을 status와 함께 맞춘다(`backend-envelope.ts:246-280`). 표가 판정하면 분류기를 부르지 않는다(`http-execution-v3.ts:1764-1771`). 관대한 분류기에도 셋은 `MAYBE_APPLIED`이고(`http-execution-v3-envelope.test.ts:680-697`) 자동 재전송이 없다(`:912-933`). 다른 5xx에 붙은 같은 code는 표 밖이다(`tests/unit/backend-envelope.test.ts:112-122`). 백엔드 답 표를 `config/contracts/backend-idempotency-answers.json`에 옮기고 양방향 대조한다(`backend-contract-pin.test.ts:105-142`). 사본 7행을 백엔드 `45d2a478` `http-contract.md` §2 두 표, §4 첫 행과 한 줄씩 대조했다. 모두 같다. 지난 제안의 "`RECOVERY_REQUIRED`는 재전송 불가 표시"는 이제 필요 없다. 백엔드 §2가 "같은 키 재전송은 안전하다"로 바뀌었다. 남은 것: §4의 rate-limit 503 둘이 사본에 없다(새 03-02) |
|
||||
| 1103/03-05 Low·P3 | 결과 불명 쓰기의 진단·텔레메트리에 effect와 원인이 없다 | **고쳐짐** (변이 검출 03-R17: 진단 표 9행과 observability 1건) | 진단·텔레메트리가 닫힌 5값 `effect_certainty`를 싣는다(`runtime-adapters.ts:204-209`). 결과 불명의 원인이 닫힌 6값 `reason`으로 진단에 간다(`backend-envelope.ts:233-239`, `:298-308`, `http-execution-v3.ts:1728-1736`, `:1788-1792`). 테스트 `http-execution-v3-envelope.test.ts:801-830`. Envelope 아닌 operation의 결과 불명은 원인 없이 effect만 남는다(`39c1de2e` 본문 위험란) |
|
||||
| 1103/03-06 Low·P3 | `AppFailure.traceId`를 채우는 곳이 없다, VD-23 401 문장 | **고쳐짐** (traceId. 변이 검출 03-R16) | 실패 Envelope의 `meta.traceId`가 `traceReference`를 거쳐 `AppFailure.traceId`가 된다(`http-execution-v3.ts:1716-1721`, `feature-http-binding.ts:376-389`). 테스트 `http-execution-v3-envelope.test.ts:441-455`. VD-23 부분은 14-03으로 합쳤다(10.3절). 지금 VD-23은 "401 response 뒤 숨은 refresh-and-replay를 하지 않는다"를 적는다(`VD-23-api-transport-selection-and-rest-execution.md:435-437`). 마감 목록·테스트 목록의 "401 recovery" 낱말은 남았다(`:407`, `:413`, `:714`, `:729-730`). 14 영역에 넘긴다. 소비자 0인 `projectCertaintyToUi`도 남았다(`http-effect-certainty.ts:155-167`). 배럴 밖이라 확장 지점이 아니다. 결함으로 세지 않는다 |
|
||||
| 1103/03-07 Low·P3 | 두 생성기가 만드는 operation이 맞지 않는다 | **일부** (결정 대기: 백엔드) | 프론트 생성기가 백엔드 경로 규칙(`create-feature.ts:125-134`)과 create·read-by-id(`--with-create`, `create-feature-write-slice.ts:1-17`)를 맞췄다. NEVER가 기본이라 백엔드 `NOT_IDEMPOTENT`와 맞는다(`:12-15`). 백엔드 생성기에는 목록 GET이 아직 없다(`__Feature__Controller.java.tmpl:49-68`). 생성 목록이 405를 받는다고 주석이 적는다(`create-feature.ts:765-771`) |
|
||||
| 1103/03-08 (= 1103/10-02로 합침) Low·P3 | 표의 "상태와 code를 함께" 규칙과 처리 중 409 무재전송 규칙의 테스트가 없다 | **03 부분 고쳐짐** (지난 생존 변이 M6·M7 이제 검출: 03-R10 "reads a table code under another status" 5행 외, 03-R11 "does not resend a 409 IDEMPOTENT_IN_FLIGHT on its own"과 pin 1건) | M6: 표 code가 다른 status로 오면 `MAYBE_APPLIED`(`backend-envelope.test.ts:96-101`, 409 `VALIDATION_FAILED`). M7: 처리 중 409를 자동 재전송하지 않는다(`http-execution-v3-envelope.test.ts:896-910`). 10-02 전체는 10 영역이 판정한다 |
|
||||
| 1101/03-03 Low·P3 | mutation 정책이 `operationId`·`requiresIdempotencyKey`를 계약과 따로 적는다 | **고쳐짐** | `commandMutationIdentity(descriptor)`가 둘을 descriptor에서 받는다(`server-state.ts:281-299`). 참조(`use-reference-feature.ts:57-61`)와 생성기(`create-feature-write-slice.ts:505`)가 쓴다. 정책에 문자열을 직접 적는 길은 남고, 매뉴얼이 "못 잡음"으로 적는다(`f59a806` 본문) |
|
||||
| 1101/03-04 Low·P3 | 효과 판정과 화면 분류가 두 함수로 나뉜다 | **남음** (문서화) | kind는 `envelopeFailureReading`(`backend-envelope.ts:378-398`), effect는 `envelopeFailureEffect`(`:340-352`)가 따로 정한다. 필드 목록 있는 표 밖 422는 필드 오류와 저장 꺼짐이 함께 나온다. 테스트가 이것을 기대값으로 둔다(`form-foundation.test.tsx:1012-1030`). 선언 없이 `mapProblem`만 둔 업무 code도 같은 모양이고, 매뉴얼이 적는다(`02-decision-tables.md:185`). 짝 백엔드의 필드 검증은 400이라(백엔드 `http-contract.md` §4) 짝 사용에서는 드물다. Low 유지 |
|
||||
| 1101/03-06 Low·P3 | V3 시간 초과 분류와 반사 correlation 문법 검사의 테스트가 없다 | **고쳐짐** (지난 생존 변이 M3 이제 검출: 03-R13, 두 건 모두 실패) | 문법 검사(`http-execution-v3.ts:1798-1810`)를 테스트 두 건이 고정한다. 마크업이 든 값과 129자 값을 버리고 보낸 id를 쓴다(`tests/integration/http-execution-v3-observability.test.ts:213-247`). 시간 초과 절반은 지난 라운드에 고쳐졌다 |
|
||||
| 0929/03-02 Medium·P2 | `x-correlation-id` CORS 허용이 문서 통제뿐이다 | **남음** | 프론트 확인 수단은 계약 §5(`backend-api-and-server-state-contract.md:240-254`)와 런북 5.2-6(`api-contract-and-server-state-recovery.md:184-193`) 문장뿐이다. 짝 백엔드 기본은 모든 요청 헤더를 허용한다(백엔드 `CorsSettings.java:47-48`). `Idempotency-Key`도 같은 조건이다 |
|
||||
| 0929/03-06 Low·P3 | UNKNOWN 동안 identity lease를 잡는 코드의 테스트가 없다 | **고쳐짐** (지난 생존 변이 M1 이제 검출: 03-R12) | 코드 `application-query.ts:669-672`. 두 칸 레지스트리에서 다른 입력 둘이 들어온 뒤에도 같은 입력이 같은 키를 받는 테스트가 생겼다(`application-mutation-admission.test.tsx:483-500`) |
|
||||
|
||||
**고친 커밋이 검사를 약하게 만들었는가(관점 10·21).** `git diff e40684b..8a44226`의 영역·흐름 파일과 위 테스트 9개를 봤다. 지워진 단언은 셋이다. ① `form-foundation.test.tsx`의 `validationMessage("SOME_FUTURE_CODE")` 한 건은 5개 code로 늘어난 `it.each`로 바뀌었다(1103/08-03). ② 저장 중 버튼 `toBeDisabled()`는 `aria-busy`와 포커스 단언으로 바뀌었다. 두 번째 클릭 거절은 `dblClick` 뒤 `toHaveBeenCalledOnce()`가 그대로 본다(`tests/features/reference-feature/reference-page.test.tsx:332-339`, 1103/08-02). ③ Envelope 표 테스트의 422 기대 kind가 `VALIDATION_REJECTED`에서 `UNKNOWN_CLIENT_FAILURE`로 바뀌었다(1103/08-05의 의도된 동작 변경, effect 기대는 같다). `metaSchema`의 `page`에 붙은 `.catch(undefined)`(`backend-envelope.ts:49`)는 완화가 아니다. 그 전에는 `.strip()`이 `page`를 늘 버렸다. 새 skip·quarantine·시간 상한 상향은 없다. **약해진 검사는 찾지 못했다.**
|
||||
|
||||
## 3. 이번 발견 (36.3)
|
||||
|
||||
새 발견 2건: Low 2 · P3 2 · 구조적 위험 1, 개선 제안 1. High 이상과 P1은 없다. 0929/03-03의 남은 부분(Medium·P2 제안)은 2절에 이월로 적었다. 새 발견으로 세지 않는다.
|
||||
|
||||
| ID | 심각도 | 우선순위 | 성격 | 관련 관점 | 제목 |
|
||||
|---|---|---|---|---|---|
|
||||
| 03-01 | Low | P3 | 구조적 위험 | 21, 6, 17, 5 | `refusedBeforeWrite`가 6.1절 표의 "쓰기 뒤 가능" 플랫폼 code도 받아, 선언 하나로 결과 불명이어야 할 실패가 새 요청이 된다 |
|
||||
| 03-02 | Low | P3 | 개선 제안 | 17, 6, 28, 9 | 백엔드 §4의 rate-limit 503 두 code가 답 표 밖이라, 생성 기능의 쓰기는 실행 전 거절을 결과 불명으로 보인다 |
|
||||
|
||||
### 03-01 `refusedBeforeWrite`가 6.1절 표의 "쓰기 뒤 가능" 플랫폼 code도 받아, 선언 하나로 결과 불명이어야 할 실패가 새 요청이 된다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 구조적 위험 |
|
||||
| 관련 관점 | 21, 6, 17, 5 |
|
||||
| 근거 | 조립 검사는 code 문법, `IDEMPOTEN(T|CY)_` 접두사, 중복, Envelope 여부만 본다(`external-contract-runtime.ts:608-646`). 실행기의 fail-close도 멱등성 접두사와 `REFUSED_BEFORE_WRITE`의 세 code만 뺀다(`backend-envelope.ts:317-327`). 그런데 프론트 계약 6.1절 표는 플랫폼 code 다수를 "쓰기 뒤 가능 → `MAYBE_APPLIED`"로 적는다. `BAD_PARAMETER`(어느 층이든 `IllegalArgumentException`), `MAPPING_FAILED`(멱등성 응답 직렬화는 action 뒤), `DB_*` 8개, `LOCK_ACQUISITION_TIMEOUT`, fileserver code들이다(`backend-api-and-server-state-contract.md:302-308`). 이 code를 `refusedBeforeWrite`에 적으면 조립이 통과하고, 그 code로 온 400·409·422가 `NOT_APPLIED`가 된다(`backend-envelope.ts:346-349`). 다음 저장은 새 키다. 매뉴얼은 "쓰기 전임을 확인했을 때만 적는다"를 문장으로 요구한다(`02-decision-tables.md:183`). 실험 X2(03-R01): `BAD_PARAMETER`, `MAPPING_FAILED`, `DB_UNIQUE_VIOLATION`, `LOCK_ACQUISITION_TIMEOUT`을 선언한 NEVER 쓰기 계약이 `composeContractContributions`를 통과했다(`composeError=none`). 설치된 목록에 넷이 그대로 있고, 각 code의 400·409 답은 모두 `NOT_APPLIED`였다 |
|
||||
| 발생 조건 | 개발자가 폼을 막는 400 `BAD_PARAMETER`나 409 `DB_UNIQUE_VIOLATION`을 보고 "폼이 다시 저장되게" 그 code를 목록에 넣는다. 그리고 그 code가 실제로 쓰기 뒤에 난다 |
|
||||
| 영향 | 쓰기 뒤에 난 실패가 "적용 안 됨"으로 보인다. 사용자가 다시 저장하면 새 키(KEYED)나 키 없는 새 요청(NEVER)이 나가 같은 항목이 둘 생길 수 있다. 중복은 드문 조건 둘이 겹쳐야 한다 |
|
||||
| 심각도·우선순위 | Low · P3 — 매뉴얼을 어긴 선언이 먼저 있어야 한다. 그러나 프론트가 이미 6.1절 표로 그 code들을 "쓰기 뒤 가능"으로 알고 있어, 막는 비용이 몇 줄이다 |
|
||||
| 통제·증거 | 멱등성 code: M4(조립 거절) / 플랫폼 "쓰기 뒤 가능" code: M1(매뉴얼 문장) · E1(코드·문서 대조), E2(실험 X2, 03-R01) |
|
||||
| 확실성과 남은 가정 | 조립과 판정의 동작은 코드로 확정이다. 개발자가 실제로 그런 선언을 할지는 가정이다. `DB_UNIQUE_VIOLATION`처럼 커밋에서 롤백되는 code는 DB 효과만 보면 적용 안 됨일 수 있다. 6.1절이 "쓰기 뒤 가능"으로 둔 판정을 그대로 따랐다 |
|
||||
| 결정의 근거 | `[기록]` D2 ①은 "함수가 아니라 code 목록이라 리뷰할 수 있고, 상태 범위를 통째로 `NOT_APPLIED`로 만들 수 없다"를 골랐다(지난 README 14.2). 멱등성 code만 조립 거절 대상으로 정했다. `[사실]` 6.1절 표는 프론트가 백엔드 코드를 읽고 만든 판정이고 같은 repo에 있다. `[추론]` 업무 code는 기능 작성자만 알지만, 플랫폼 code의 단계는 템플릿이 이미 안다. 그 지식을 조립 검사가 쓰지 않는다 |
|
||||
| 이해 비용 | 폼이 막힌 개발자는 막는 code를 목록에 넣고 싶어진다. 그 code가 업무 code인지 플랫폼 code인지 가르려면 6.1절 표를 찾아 읽어야 한다 |
|
||||
| 최소 개선 방향 | 6.1절 표의 "쓰기 뒤 가능" 플랫폼 code를 `backend-envelope.ts`에 상수 목록으로 두고, 조립이 그 code의 선언을 거절한다. 거절 문구에 6.1절을 적는다. `backend-contract-pin.test.ts`처럼 그 목록과 6.1절 표를 대조하는 테스트를 하나 둔다 |
|
||||
| 대안 비교 | (a) 현상 유지: 매뉴얼 문장에 기댄다. (b) 플랫폼 code 거절(위): 몇 줄, 6.1절과 함께 갱신. (c) 업무 code 접두사 규칙(예: `<FEATURE>_`로 시작하는 code만 허용): 다운스트림 code 이름을 강제해 과하다. (b)가 가장 좁다 |
|
||||
| 단순화의 보존 조건 | 업무 code 선언은 지금처럼 된다. 멱등성 code 거절은 그대로다 |
|
||||
| 비용·부작용 | 상수 1개, 조립 검사 몇 줄, 테스트 1건. 이미 플랫폼 code를 적은 다운스트림은 부팅에서 실패한다(CHANGELOG [계약] 행) |
|
||||
| 재검토 조건 | 백엔드가 실패 Envelope에 단계 신호(D2 ②)를 내면 선언 목록 자체를 다시 본다 |
|
||||
| 완료 기준 | X2의 계약이 조립에서 "`BAD_PARAMETER`는 6.1절에서 쓰기 뒤 가능" 이유로 거절된다 |
|
||||
| 검증 방법 | `tests/unit/external-contract-runtime.test.ts`의 `refusedBeforeWrite` 묶음에 `it.each` 1건 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
|
||||
### 03-02 백엔드 §4의 rate-limit 503 두 code가 답 표 밖이라, 생성 기능의 쓰기는 실행 전 거절을 결과 불명으로 보인다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 개선 제안 |
|
||||
| 관련 관점 | 17, 6, 28, 9 |
|
||||
| 근거 | 백엔드 §4 표는 web 전용 code 넷을 적는다. `REQUEST_TIMEOUT`, `IDEMPOTENCY_KEY_INVALID`, `RATE_LIMIT_UNAVAILABLE`(503, retryable, `Retry-After` 있음), `RATE_LIMIT_INCOMPATIBLE`(503)이다(백엔드 `docs/web/http-contract.md` §4 표). 뒤의 둘은 `RateLimitInterceptor.preHandle`이 컨트롤러 전에 낸다(백엔드 `RateLimitInterceptor.java:30-63`). pin은 §4를 대조했다고 적는다(`backend-contract-pin.json`의 `sectionsCompared: ["1","2","4"]`). 그러나 답 표 사본에는 §4에서 `REQUEST_TIMEOUT` 한 행만 있다(`config/contracts/backend-idempotency-answers.json`의 7행). 프론트 표에도 없다(`backend-envelope.ts:152-172`, `:246-269`). 그래서 이 503은 기능 분류기가 정한다(`http-execution-v3.ts:1764-1771`). 생성 기능의 분류기는 늘 `MAYBE_APPLIED`다(`create-feature-write-slice.ts:298`). 같은 생성 기능이 429 `RATE_LIMIT_EXCEEDED`는 `classifyStatus`로 `NOT_APPLIED`로 본다(`:303`). 실험 X4(03-R01, 생성 기능과 같은 분류기): 429 `RATE_LIMIT_EXCEEDED` → `RATE_LIMITED/NOT_APPLIED`, 503 `RATE_LIMIT_UNAVAILABLE` → `SERVER_FAILURE/MAYBE_APPLIED`, 503 `RATE_LIMIT_INCOMPATIBLE` → `SERVER_FAILURE/MAYBE_APPLIED` |
|
||||
| 발생 조건 | rate-limit 저장소가 응답하지 않거나 제공자가 맞지 않는 동안 생성 기능으로 쓰기를 저장한다 |
|
||||
| 영향 | 아무 일도 일어나지 않은 저장이 결과 불명이 된다. NEVER 쓰기는 재전송 버튼이 없어(0929/03-03 수정) "변경됨으로 확인"을 눌러야 폼이 풀린다. 사실과 다른 확인이다. KEYED는 같은 키 재전송으로 빠져나온다. 데이터 피해는 없다(안전 쪽) |
|
||||
| 심각도·우선순위 | Low · P3 — 드문 장애 중에만 생기고 안전 쪽으로 실패한다 |
|
||||
| 통제·증거 | M0(이 code의 판정이 없다) · E1(백엔드 코드·문서, 프론트 표 대조), E2(실험 X4, 03-R01) |
|
||||
| 확실성과 남은 가정 | `preHandle`이 컨트롤러 전이라는 것은 코드로 확인했다. 다른 필터가 같은 code를 쓰기 뒤에 내는 곳은 찾지 못했다(백엔드 `src/**/main`에서 두 곳뿐) |
|
||||
| 결정의 근거 | 적용 제외 — 기존 표에 행을 채우는 문제다 |
|
||||
| 이해 비용 | 쓰기를 만드는 사람은 503이 표에 있는지 `backend-envelope.ts`를 읽어야 안다. 매뉴얼 4절은 표의 5xx 넷만 적는다(`02-decision-tables.md:176-178`) |
|
||||
| 최소 개선 방향 | 답 표 사본에 §4의 두 행을 `refusedBeforeWrite: true`, `sameKeyResend: false`로 옮긴다. 프론트 거절 표에 status와 함께 `NOT_APPLIED`로 더한다. 그러면 `backend-contract-pin.test.ts`가 둘을 함께 지킨다 |
|
||||
| 대안 비교 | 적용 제외 — 표의 범위 누락이다 |
|
||||
| 단순화의 보존 조건 | 503 `IDEMPOTENCY_UNAVAILABLE`의 `MAYBE_APPLIED`와 KEYED 자동 재전송은 그대로다 |
|
||||
| 비용·부작용 | JSON 2행, 표 2행, 6.1절·매뉴얼 4절 1줄 |
|
||||
| 재검토 조건 | 백엔드 §4 표가 바뀔 때(pin을 올리는 같은 변경) |
|
||||
| 완료 기준 | X4에서 503 `RATE_LIMIT_UNAVAILABLE`이 분류기와 상관없이 `NOT_APPLIED`/`retry-later`다 |
|
||||
| 검증 방법 | `backend-contract-pin.test.ts`가 새 행을 읽는다. `backend-envelope.test.ts`에 1건 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
|
||||
**다른 영역에 넘기는 관찰(세지 않음).** `fileserver-upload.ts`는 같은 백엔드 답을 자기 표로 따로 판정한다(`src/adapters/http/fileserver-upload.ts:158-180`, `:690-704`). 503 `IDEMPOTENCY_UNAVAILABLE`을 `backend-envelope.ts`는 `MAYBE_APPLIED`로, 업로드 client는 `NOT_APPLIED`로 본다. 4xx는 기본이 `NOT_APPLIED`다. 그래서 백엔드가 §2에 409 계열 code를 새로 더하면 `backend-contract-pin.test.ts`는 `backend-envelope.ts`만 알리고, 업로드 client는 그 code를 조용히 `NOT_APPLIED`로 읽는다. 갈라진 판정 복사본인지는 01 영역이 판단한다.
|
||||
|
||||
## 4. 28개 관점 판정 (36.2)
|
||||
|
||||
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역. 굵은 번호는 깊게 본 관점이다.
|
||||
|
||||
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | 코드 성숙도 | 적용 | M2 / M2 | E1 | P — 짝 백엔드 판정이 한 모듈에 모였고(`backend-envelope.ts`), 선언 목록은 조립 때 고정 사본이 된다(`external-contract-runtime.ts:813-842`). 바인딩의 `default` 가지가 새 위반 종류를 `ENVELOPE_MISMATCH`로 흡수한다(`feature-http-binding.ts:571-572`, 1101 R3). 업로드 client가 같은 답을 따로 판정한다(01 영역) |
|
||||
| 2 | 구조적 성숙도 | 다른 영역 | — | 게이트 | > 12·16 영역. `check:architecture` rc=0(오케스트레이터) |
|
||||
| 3 | 변경 용이성 | 적용 | M3 / M2 | E1 | P — 쓰기 하나에 맞출 곳이 descriptor 한 곳으로 줄었다(`commandMutationIdentity`, 1101/03-03 고쳐짐). 업무 code는 descriptor 한 줄로 선언한다 |
|
||||
| 4 | 인지 부하 | 적용 | M1 / M1 | E1 | P — 실패 판정 순서(401·403·429 → 표 → 선언 목록 → 분류기 → 폼 분기)를 알아야 한다. 매뉴얼 02 4절이 흐름도와 표로 설명한다(`02-decision-tables.md:150-185`) |
|
||||
| **5** | 위험 가시성 | 적용 | M3 / M2 | E1 | P — 선언 목록이 descriptor와 FE-REG-API 행에 보인다(`src/contracts/api-operations.ts:130-143`). 플랫폼 code를 적은 위험은 descriptor만 보고 알 수 없다(03-01) |
|
||||
| **6** | 실패 성숙도 | 적용 | M4 / M3 | E2(변이 19개 검출, 실험 X1·X4) | P — 업무 거절 뒤 다시 저장(1103/03-01), 5xx 넷 고정(1103/03-04), `SAFE` 쓰기 거절(1103/03-03), NEVER 재전송 버튼 제거가 들어왔다. 남은 것: 키 없는 같은 입력 재제출(0929/03-03 일부), 플랫폼 code 선언(03-01), rate-limit 503(03-02) |
|
||||
| 7 | 운영 성숙도 | 적용 | M2 / M2 | E2 | P — `effect_certainty`로 결과 불명 쓰기를 셀 수 있다(1103/03-05). 진단 sink는 메모리 버퍼뿐이다 |
|
||||
| **8** | 디버깅 가능성 | 적용 | M2 / M2 | E2 | O — 보낸 id fallback, `traceId`, 반사 id 문법, 전송 전 거절 `reason`, 결과 불명 `reason`이 모두 있다. Envelope 아닌 결과 불명은 원인이 없다(작은 잔여) |
|
||||
| 9 | 유지보수 성숙도 | 적용 | M3 / M3 | E2 | P — pin과 답 표 사본을 테스트가 양방향으로 대조한다(`backend-contract-pin.test.ts`). 사본이 §4를 일부만 옮겼다(03-02). 백엔드 문서 변경 감지는 게이트 밖이다(12 영역) |
|
||||
| **10** | 테스트 성숙도 | 적용 | M3 / M3 | E2 | O — 수정마다 테스트가 생겼고 게이트에서 통과한다(대상 9파일, 오케스트레이터). 규칙을 깨는 변이 19개가 모두 기대한 테스트에서 실패했다(03-R02 3개, 03-R03~R18 16개). 지난 생존 변이 M1·M3·M6·M7도 이제 잡힌다. 빈틈: 키 없는 같은 입력 재제출은 테스트가 없다(0929/03-03 일부, 실험 X1이 그 동작을 보였다) |
|
||||
| 11 | 데이터 성숙도 | 적용 제외 | — | — | - 영속 데이터를 쓰지 않는다. 메모리 캐시와 intent뿐이다 |
|
||||
| **12** | 동시성 성숙도 | 적용 | M3 / M2 | E2 | P — KEYED 같은 입력 재제출은 같은 키, identity lease는 테스트가 생겼다(0929/03-06). 키 없는 같은 입력 재제출은 훅이 막지 않는다(0929/03-03 일부) |
|
||||
| 13 | 확장성 | 다른 영역 | — | — | > 11·15 영역 |
|
||||
| 14 | 성능 성숙도 | 다른 영역 | — | — | > 15 영역. 이 영역 변경은 실행 경로에 상수·작은 검사만 더했다 |
|
||||
| 15 | 보안 성숙도 | 적용 | M4 / M3 | E2 | O — 쿠키 쓰기 CSRF 조립 검사(`external-contract-runtime.ts:587-599`), `redirect: "error"`·`no-referrer`·`no-store`(`http-execution-v3.ts:991-994`), 반사 correlation 문법 테스트(1101/03-06). 0929/03-02(CORS 헤더)는 19번 |
|
||||
| 16 | 의존성 성숙도 | 다른 영역 | — | — | > 13 영역 |
|
||||
| **17** | API / Contract | 적용 | M3 / M3 | E2 | P — §1 `meta.page`, §2 답 전부, §4 `REQUEST_TIMEOUT`을 읽는다. bulk는 미지원으로 문서화했다(1103/03-02 일부). §4 rate-limit 503 둘이 표 밖이다(03-02). 업무 code의 단계 신호는 계약에 없고 operation 선언으로 대신한다(D2 ② 백엔드 대기) |
|
||||
| 18 | 배포 성숙도 | 다른 영역 | — | — | > 13 영역 |
|
||||
| 19 | 설정 성숙도 | 적용 | M2 / M1 | E1 | P — 교차 origin `x-correlation-id`·`Idempotency-Key` 허용은 문서뿐이다(0929/03-02) |
|
||||
| **20** | 개발자 경험 | 적용 | M3 / M2 | E2 | P — `--with-create`가 짝 백엔드 create·read-by-id와 쓰기 전 거절 선언, NEVER/KEYED 값을 만든다. 백엔드 목록 GET이 없다(1103/03-07 일부). 전체 판정은 14·16 영역 |
|
||||
| **21** | Guardrail 성숙도 | 적용 | M4 / M4 | E2 | P — 조립이 쓰기 `SAFE`, 읽기 `KEYED`·`NEVER`, 목록 안의 멱등성 code, Envelope 없는 목록을 거절한다. "쓰기 뒤 가능" 플랫폼 code는 거절하지 않는다(03-01) |
|
||||
| 22 | 추상화 성숙도 | 적용 | M2 / M2 | E1 | P — `FeatureHttpBinding`은 좁다. kind와 effect가 두 함수에서 정해진다(1101/03-04 남음) |
|
||||
| 23 | 일관성 | 적용 | M2 / M2 | E1 | O — 401·403·429는 `classifyStatus`, 400·409·422는 `refusedBeforeWrite`로 operation이 "적용 안 됨"을 정할 수 있다. 지난 라운드의 불일치가 풀렸다 |
|
||||
| 24 | 네이밍 / 의미 | 적용 | M1 / M1 | E1 | P — NEVER 결과 불명 화면의 출구는 "변경됨으로 확인" 하나다. 사용자가 적용 안 됨을 확인했어도 이 버튼을 눌러야 폼이 풀린다(`async-surface.tsx:126-128`의 설계 결정) |
|
||||
| 25 | 조직 확장성 | 다른 영역 | — | — | > 14 영역 |
|
||||
| 26 | Ownership | 적용 | M2 / M2 | E1 | P — pin이 담당(`frontend-platform`)과 대조 날짜를 적는다. 백엔드가 code를 더할 때 프론트에 알리는 길은 게이트 밖 drift 검사다 |
|
||||
| 27 | 삭제 가능성 | 적용 | M3 / M2 | E1 | O — 소비자 0인 `projectCertaintyToUi`가 남았다(배럴 밖, 결함 아님) |
|
||||
| **28** | 회복 가능성 | 적용 | M3 / M2 | E2 | P — 선언한 업무 거절 뒤 고쳐서 저장한다. KEYED 결과 불명은 같은 키로 재전송한다. NEVER 결과 불명의 출구는 "변경됨으로 확인"이나 새로고침이다. rate-limit 503도 그 길로 간다(03-02) |
|
||||
|
||||
X(미충족)는 없다.
|
||||
|
||||
## 5. 미검증
|
||||
|
||||
| 무엇을 | 왜 확인하지 못했나 | 무엇이 있으면 확인할 수 있나 |
|
||||
|---|---|---|
|
||||
| 생성 KEYED 슬라이스에 같은 변이를 넣은 결과 | 03-R02는 NEVER 슬라이스만 생성했다. KEYED 슬라이스는 `test:feature-scaffold`(FE-GATE-020 rc=0)에서 변이 없이만 돈다 | `create:feature x --with-create --keyed` 뒤 같은 G1 |
|
||||
| 실험 X1~X4가 이 실험 파일 밖의 실제 화면에서도 같은가 | 실험은 jsdom에서 실제 실행기·바인딩·훅을 쓰고 fetch만 바꿨다 | 생성 기능 페이지에 폼 밖 버튼을 붙인 시나리오 |
|
||||
| 짝 백엔드와의 실제 통합 | 백엔드는 읽기만 했다. 생성기 템플릿과 문서로 확인했다 | 백엔드 생성 기능을 띄워 빈 이름 create, rate-limit 저장소 장애 주입 |
|
||||
| 실제 브라우저의 폼 흐름 | jsdom 테스트만 봤다 | Playwright 폼 시나리오 |
|
||||
| 다운스트림이 폼 밖에서 같은 입력을 다시 `submit`하는 NEVER 쓰기를 갖고 있는가 | tech-log·memento를 읽지 않았다 | 두 제품의 `useApplicationMutation` 호출과 `retrySemantics: "NEVER"` grep |
|
||||
| `src/adapters/browser-rpc`·`query-cache`·`diagnostics`·`telemetry`의 세부 동작 | `e40684b` 뒤 변경이 없다. 게이트 통과만 확인했다 | 지난 라운드 변이를 다시 돌리기 |
|
||||
|
||||
## 6. 실행 기록
|
||||
|
||||
| 이름 | 명령 | 변이 | rc | 결과 | 잠금 대기 | 부하 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| `03-mut` | `exp.sh 03-mut - 840 "bash /tmp/claude-gates/r4/mut/03-runner.sh"` | 스크립트 안의 21개 | — | **돌지 않았다.** 잠금 대기 중 19:55에 취소됐다(BRIEF-2). 로그 없음 | 취소 | — |
|
||||
| `03-gen` | `exp.sh 03-gen - 600 "bash /tmp/claude-gates/r4/mut/03-gen.sh"` | 스크립트 안의 G1·M08·M09 | — | **돌지 않았다.** 같은 이유 | 취소 | — |
|
||||
| 재시도 2건(19:48) | 같은 명령을 `nohup`으로 | — | 93 | `CLOSED: exp.sh no longer runs experiments` | — | — |
|
||||
| 오케스트레이터 게이트(인용, 대조군) | `check:architecture`·`check:types`·`lint`·`test:unit`·`test:component`·`test:integration`(local), FE-GATE-001~012·020(CI env) | — | 0 | unit 194 files / 2,883 tests, component 40 / 270, integration 11 / 189. 대상 9파일 통과(`backend-envelope` 30, `external-contract-runtime` 42, `create-feature` 43, `backend-contract-pin` 10, `form-foundation` 31, `async-surface` 34, `application-mutation-admission` 17, `http-execution-v3-observability` 11, `http-execution-v3-envelope` 57). `verify:documentation` rc=1과 FE-GATE-013 rc=1은 이 영역 밖이다(1절) | — | 3.2~8.3 |
|
||||
|
||||
배치 결과(오케스트레이터가 돌림, local env, 2026-11-05 20:02~20:03, 부하 2.2~3.3). 18건 모두 복원 깨끗(`restore=clean`). 로그는 `scratchpad/r4/results/03/03-Rnn.log`. 공통 명령: `ENV` = `node scripts/run-vitest.ts run` + `backend-envelope`·`backend-contract-pin`·`http-execution-v3-envelope`·`http-execution-v3-observability`·`form-foundation` 테스트 5파일(139 tests), `ECR` = `external-contract-runtime.test.ts`(42), `STATE` = `application-mutation-admission`·`async-surface`(51), `CF` = `create-feature.test.ts`(43). 변이 스크립트는 `node /tmp/claude-gates/r4/mut/03-files/mutate.mjs <ID>` 하나를 부른다. 바꿀 문자열이 정확히 한 번 나와야 바꾸고, 아니면 exit 3이다. 모든 로그에 `<ID>: applied to <file>`이 찍혔다. 대조군은 위 게이트 로그다(03-R02는 자기 안에서 돌렸다).
|
||||
|
||||
| 이름 | 명령 | 변이 | rc | 결과(실패한 테스트) |
|
||||
|---|---|---|---|---|
|
||||
| 03-R01 | `node scripts/run-vitest.ts run tests/component/r04-03-experiments.test.tsx` | 실험 파일 추가만 | 0 (2 s) | 5/5 통과. X1 NEVER `canResend=false resendReturned=null fetchAfterResend=1 fetchAfterSameInputSubmit=2 keys=[null,null] second=true`. X1 KEYED `canResend=true ... keys=["key-1","key-1","key-2"]`. X2 `composeError=none`, 넷 모두 `NOT_APPLIED`. X3 `resendButtonDrawn=true`. X4 429 `RATE_LIMITED/NOT_APPLIED`, 503 둘 `SERVER_FAILURE/MAYBE_APPLIED` |
|
||||
| 03-R02 | `bash /tmp/claude-gates/r4/mut/03-gen.sh` | 스크립트 안: G1, M08, M09 | 0 (15 s) | `create:feature memo-feature --with-create` rc=0, 생성 계약에 `refusedBeforeWrite: ["MEMO_INVALID"]`·`NEVER`·`retryBudget: 0`. BASELINE 4 files / 21 tests 통과. G1(선언 줄 삭제, 남은 줄 0) rc=1: "reads 400 MEMO_INVALID as not applied, on the name field", "shows the backend's refusal of the name on the field and saves again". M08 rc=1, M09 rc=1: 둘 다 "keeps a create whose response was lost unknown and offers no resend"만 실패 |
|
||||
| 03-R03 | `ENV` | M01 선언 판정 끔 | 1 (8 s) | 7건: 단위 "reads a declared 400/409/422 ... as not applied" 3, 통합 "reads a declared 400 WORKLOG_INVALID / 409 POSTER_ALREADY_EXISTS as not applied"·"applies the list the composition installed" 3, 폼 "saves the corrected value after a declared pre-write refusal, with a new key" 1 |
|
||||
| 03-R04 | `ENV` | M02 런타임 멱등성 접두사 거절 제거 | 1 (4 s) | 1건: "never lets a declaration decide an idempotency answer or a table code" |
|
||||
| 03-R05 | `ECR` | M04 조립의 멱등성 code 거절 제거 | 1 (1 s) | 5건: "refuses to declare the idempotency answer" × `IDEMPOTENT_IN_FLIGHT`·`IDEMPOTENT_REQUEST_MISMATCH`·`IDEMPOTENCY_UNAVAILABLE`·`IDEMPOTENCY_COMPLETION_UNKNOWN`·`IDEMPOTENCY_KEY_INVALID` |
|
||||
| 03-R06 | `ENV` | M06 실행기가 목록을 안 넘김 | 1 (8 s) | 4건: 통합 3("reads a declared ..." 2, "applies the list the composition installed"), 폼 1 |
|
||||
| 03-R07 | `STATE` | M08 훅이 키를 안 봄 | 1 (2 s) | 1건: "offers no resend for an unknown request that carries no key" |
|
||||
| 03-R08 | `STATE` | M09 화면이 플래그를 안 봄 | 1 (2 s) | 1건: "draws no resend for an unknown request that cannot be resent" |
|
||||
| 03-R09 | `ENV` | M11 `COMPLETION_UNKNOWN` 행 삭제 | 1 (4 s) | 6건: 단위 "reads 503 IDEMPOTENCY_COMPLETION_UNKNOWN as maybe applied"·"never lets a declaration decide ...", pin "reads the backend's 503 IDEMPOTENCY_COMPLETION_UNKNOWN as its table says", 통합 "keeps the key and does not resend 503 ..."·진단 "503 IDEMPOTENCY_COMPLETION_UNKNOWN"·"keeps 400, 409, 422 outside the table ..." |
|
||||
| 03-R10 | `ENV` | M13 거절 표가 status를 안 봄 | 1 (3 s) | 6건: "reads a table code under another status (...) as maybe applied" 5행, "never lets a declaration decide ..." |
|
||||
| 03-R11 | `ENV` | M14 처리 중 409도 자동 재전송 | 1 (4 s) | 2건: "does not resend a 409 IDEMPOTENT_IN_FLIGHT on its own", pin "reads the backend's 409 IDEMPOTENT_IN_FLIGHT as its table says" |
|
||||
| 03-R12 | `STATE` | M15 UNKNOWN 동안 identity lease 안 잡음 | 1 (2 s) | 1건: "keeps the unknown input's identity when the identity registry is full" |
|
||||
| 03-R13 | `ENV` | M16 반사 correlation 문법 검사 제거 | 1 (3 s) | 2건: "drops a reflected correlation id that is an overlong value / a value with spaces and markup" |
|
||||
| 03-R14 | `ECR` | M17 쓰기 `SAFE` 조립 거절 제거 | 1 (1 s) | 4건: "rejects SAFE retry semantics on a POST/PUT/PATCH/DELETE" |
|
||||
| 03-R15 | `ENV` | M18 `meta.page` 버림 | 1 (4 s) | 3건: "hands the backend's meta.page to mapSuccess", "reads an unsorted page", "reads a page without sort" |
|
||||
| 03-R16 | `ENV` | M19 실패 `traceId` 버림 | 1 (3 s) | 1건: "carries the failure Envelope's meta.traceId on the failure" |
|
||||
| 03-R17 | `ENV` | M20 `effect_certainty` 안 실음 | 1 (4 s) | 10건: 진단 표 9행("400 IDEMPOTENCY_KEY_INVALID" … "503 REQUEST_TIMEOUT"), "projects every V3 terminal outcome through the closed diagnostics allowlist" |
|
||||
| 03-R18 | `CF` | M22 생성기의 `refusedBeforeWrite` 줄 삭제 | 1 (1 s) | 1건: "matches the backend scaffold's NOT_IDEMPOTENT create with a NEVER command" |
|
||||
|
||||
변이 19개(03-R02의 3개 포함) 모두 검출됐다. 각 변이는 요청서에 적은 기대 테스트에서 실패했다. 기대 밖에서 함께 실패한 것(03-R09의 "never lets a declaration decide ...", 03-R15의 page 2건, 03-R17의 observability 1건)도 같은 규칙을 보는 테스트다.
|
||||
|
||||
## 7. 새 발견 요약
|
||||
|
||||
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|
||||
|---|---|---|---|---|
|
||||
| 03-01 | Low·P3 | 구조적 위험 | `refusedBeforeWrite`가 6.1절의 "쓰기 뒤 가능" 플랫폼 code(`BAD_PARAMETER`, `MAPPING_FAILED`, `DB_*`, `LOCK_ACQUISITION_TIMEOUT`)도 받는다 | `src/contracts/external-contract-runtime.ts:608-646`, `src/adapters/http/backend-envelope.ts:317-327` |
|
||||
| 03-02 | Low·P3 | 개선 제안 | 백엔드 §4의 503 `RATE_LIMIT_UNAVAILABLE`·`RATE_LIMIT_INCOMPATIBLE`이 답 표 밖이라 생성 쓰기에서 결과 불명이 된다 | `config/contracts/backend-idempotency-answers.json`, `src/adapters/http/backend-envelope.ts:246-269`, `scripts/create-feature-write-slice.ts:298` |
|
||||
|
||||
이월로 남은 것: 0929/03-03 일부(남은 부분 Medium·P2 제안), 1103/03-02 일부, 1103/03-07 일부, 1101/03-04 남음, 0929/03-02 남음.
|
||||
@@ -0,0 +1,232 @@
|
||||
# 04 realtime 어댑터 성숙도 리뷰
|
||||
|
||||
> 검토일: 2026-11-05 · 기준: `fix/maturity-review-2026-11-03` / `8a44226` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
|
||||
> 경로: `src/adapters/realtime/`, `src/contracts/realtime-streams.ts`, `src/application/policies/bounded-polling.ts`. 짝 백엔드 `clean-architecture-backend-template` `45d2a478`의 실시간 출구(읽기만)
|
||||
> 깊게 본 관점: 6, 10, 17, 21, 24, 28
|
||||
> 렌즈: ① 1103/04-01 수정 뒤 poll 한 번이 실제 요청 한 번인가(지난 실험 P 재실행) ② 이 영역의 수정이 검사를 약하게 만들지 않았는가 ③ 1103/04-02 대응표가 백엔드 `45d2a478`과 맞는가
|
||||
|
||||
ID 표기: 이번 라운드 발견은 `04-01`부터 쓴다. 라운드 밖에서는 `1105/04-NN`이다. 지난 라운드(2026-11-03)는 `1103/04-NN`, 그 전은 `1101/04-NN`, `0929/04-NN`이다.
|
||||
|
||||
**이 문서의 실행 증거.** 처음 건 영역 실행(`04-poll-mut`)은 lock 대기 중 19:55에 일괄 취소되어 돌지 않았다(6절). 그 뒤 실험·변이 네 건(04-R1~04-R4)을 배치로 요청했고, 오케스트레이터가 desktop에서 한 번씩 돌렸다(20:03, 부하 2.4~2.6, 매번 `8a44226`으로 되돌림 확인). 나머지 실행 증거는 오케스트레이터 게이트 로그와 snapshot이다.
|
||||
|
||||
**영역 판정 (35.8)**
|
||||
|
||||
| 범위 | 판정 | 이유 |
|
||||
| --- | --- | --- |
|
||||
| codec·stream coordinator·WebSocket 연결·live↔Poll handoff·reconnect coordinator | 지정 범위에서 사용 가능 | 지난 라운드의 남은 항목 1101/04-03(초당 event 상한 테스트)과 0929/04-04(heartbeat 주석)가 고쳐졌다. realtime 단위 테스트 14파일 267건이 게이트에서 통과했다 |
|
||||
| reconnect coordinator + SSE | 조건부 사용 가능 | 서버 끊김 이름이 세 transport에서 같아졌다(1103/04-04 고쳐짐). 조합 코드가 SSE session bridge와 EOF 분류를 직접 정해야 하는 것(0929/04-02)과 `retry:` 상한 규칙(0929/04-03)은 그대로다 |
|
||||
| bounded polling + V3 HTTP 실행기 | 조건부 사용 가능 | 조건이 하나로 줄었다. `execute` 안에서 coordinator에 넘긴 descriptor를 그대로 실행기에 넘겨야 한다. 그러면 실행기는 다시 보내지 않는다. 조립된 행으로 503·네트워크 실패·429 모두 poll 3회 = 요청 3회였다(04-R1 P2~P4). 다른 descriptor를 넘기면 막는 것이 없다. 그때는 poll 3회에 요청 9회다(04-R1 P5, 2절 1103/04-01 남은 틈) |
|
||||
| 짝 백엔드 템플릿과 realtime push를 그대로 연결 | 해당 용도의 사용 보류 | 지금 연결되는 push 조합이 없다. 이제 설계 0.1절이 이것과 세 길을 적는다(1103/04-02 문서 고쳐짐). 길 선택은 제품 결정이다. 짝 백엔드와 bounded polling 조합은 위 행대로 쓸 수 있다 |
|
||||
|
||||
## 0. 결론
|
||||
|
||||
- 지난 라운드 Medium 둘이 고쳐졌다. **1103/04-01**: poll은 이제 V3 descriptor를 받고 `frontend.retryBudget`이 0이 아니면 생성 때 거절한다(`bounded-polling.ts:115-139`). 실행기는 같은 칸에서 재시도 상한을 읽는다(`http-execution-v3.ts:557`, `:911-915`). 그래서 같은 descriptor를 실행기에 넘기면 poll 1회 = 요청 1회다. 실험 P를 조립된 행(`composeContractContributions`)으로 다시 돌렸다. 지난 라운드 9회이던 요청이 3회다(04-R1). 검사 줄을 지우는 변이(MP1)는 테스트 3건, 실행기가 `retryBudget`을 읽지 않게 하는 변이(MP2)는 1건에서 잡힌다(04-R2, 04-R3). **1103/04-02**: 설계 0.1절에 짝 백엔드 대응표가 생겼다. 표의 백엔드 사실을 `45d2a478`에서 다시 확인했고 맞다.
|
||||
- 지난 라운드 Low 넷(04-03~04-06)과 이월 둘(1101/04-03, 0929/04-04)도 완료 기준까지 고쳐졌다. 남은 이월은 0929/04-02(SSE bridge·EOF)와 0929/04-03(SSE `retry:` 범위, 결정 대기) 둘이다.
|
||||
- 1103/04-01에 남은 틈이 하나 있다. coordinator는 `execute`에 descriptor를 넘기지 않는다(`bounded-poll-coordinator.ts:104-113`, `:307-312`). 조합 코드가 검사받은 descriptor와 다른 descriptor로 실행기를 부르면 다시 요청이 3배가 된다(04-R1 P5: poll 3회, 요청 9회, 실행기 대기 6번). 커밋 `a65df74`가 위험으로 적었고 타입 주석이 "같은 객체"를 요구한다. 완료 기준은 충족해서 상태는 고쳐짐으로 둔다.
|
||||
- 수정이 검사를 약하게 만든 곳이 하나 있다(새 04-01). `af00067`이 SSE 거절을 `PROVIDER_UNAVAILABLE`로 바꾸면서, 0929/04-01(서버만 끊기면 run이 멈춤)을 막던 테스트 두 건이 더는 transport `OFFLINE` 경로를 지나지 않는다. 그 규칙은 타입 주석과 설계 5.3에 남아 있다. 지운 두 줄을 되살리는 변이(MR1)에서 realtime 14파일 267건이 모두 통과했다. 같은 변이에서 리뷰 대조 C1·C2는 run이 멈춰 실패했다(04-R4).
|
||||
- 같은 수정이 다른 결함 하나를 만들었다(새 04-02). poll `execute`가 던지면 이제 "서버에 닿지 않음"(`PROVIDER_UNAVAILABLE`)으로 보고 lease 안에서 재시도한다. V3 실행기는 네트워크 실패를 던지지 않고 결과로 돌려준다. 그래서 자연스러운 조합에서 던짐은 조합 코드 결함이고, 그 결함이 서버 장애와 예산 소진으로 보인다.
|
||||
- 설계 결정 VD-28은 아직 지운 V2 poll 예산(`maxAttempts=1`, `authRecoveryCount=0`, `maxCumulativeSleepMs=0`)으로 poll 규칙을 적는다(새 04-03, 문서).
|
||||
- 이번 발견 3건: **Low 3**, 모두 P3. High 이상·P1은 없다.
|
||||
|
||||
## 1. 범위 (36.1)
|
||||
|
||||
| 항목 | 기록 |
|
||||
| --- | --- |
|
||||
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`. 짝 백엔드 `clean-architecture-backend-template` `45d2a478`(프론트 pin `config/contracts/backend-contract-pin.json`)은 읽기만 했다 |
|
||||
| 커밋·작업 상태·확인 시점 | `8a44226`. laptop worktree(HEAD = 기준)에서 읽기만 했다. 2026-11-05 19:20~ |
|
||||
| 목적과 지원 실행 구성 | 템플릿. realtime은 `RECIPE_AVAILABLE`·`AVAILABLE_NOT_COMPOSED`다. 조합 코드(bridge, 환경 신호, poll `execute`)는 채택 프로젝트 몫이다. 브라우저 SPA, 탭마다 연결 1개 |
|
||||
| 필수 요구와 규모·운영 목표 | 합의된 SLO 없음. 설계 문서의 상한표(11절)와 실패 어휘(13.1절)를 기준으로 봤다 |
|
||||
| 읽은 코드·구성 범위 | `e40684b..8a44226`에서 영역을 바꾼 커밋 전부: `a65df74`(poll V3 descriptor), `af00067`(서버 끊김 kind), `a94006b`(snapshot 표 테스트), `3bc690d`(WS rate 테스트), `5d0f5ad`(heartbeat 주석), `5b2106d`(바인딩 출처 문서), `615da35`(짝 백엔드 대응표), `08ed0a0`의 `tests/unit/realtime/fixture.ts`. 전부 읽음: `bounded-polling.ts`, `bounded-poll-coordinator.ts`, 위 커밋의 diff와 테스트 변경. 필요한 부분: `http-execution-v3.ts`(재시도 상한, fetch 거절 처리), `external-contract-runtime.ts`(조립·동결·중복 검사), `reconnect-coordinator.ts`(online 대기, 재시도 분기), `fetch-sse-connection.ts`, `websocket-connection.ts`(heartbeat 훅, rate 상한), `realtime-streams.ts`(snapshot 바인딩), `sse-parser.ts`(`retry:`), `installed-feature-runtime-registries.ts`, `schema-registry.ts`, `boundary-mapper.ts` |
|
||||
| 읽은 문서(주장) | 설계 `realtime-events-web-push-and-bounded-polling.md` 0.1·3·5.3·6.3·9.2·11·13.1절, `VD-28` 상태·1·poll 절, `VD-23` 상태와 8절, `optional-adapter-recipes.md` Realtime 절, 매뉴얼 03 C절, `CHANGELOG.md` 미출시 절, 지난 라운드 `2026-11-03-maturity-review/04-adapters-realtime.md`와 README 10.3·12·14절. 짝 백엔드 `src/adapter/inbound/websocket/README.md`, `src/adapter/inbound/web-advanced/README.md`, `docs/web/repository-adaptation.md`, `ForbiddenApiArchitectureTest.java`, `WebOpenApi32Generator.java` |
|
||||
| 수행한 테스트·실험 | 배치 실험 04-R1(실험 P 재실행 + 대조 C), 변이 04-R2(MP1), 04-R3(MP2), 04-R4(MR1). desktop, 오케스트레이터 실행, local env(6절). 인용한 오케스트레이터 게이트 결과: `gates/summary.txt`의 check:architecture·check:types·lint·test:unit·test:component·test:integration·test:contract·test:runtime-schema·check:adapter-inventory·check:ci rc=0, `test_unit.log`의 realtime 14파일 267건 통과(194파일 2,883건 중). `merge-48/summary.txt`(CI=true env): FE-GATE-010 rc=0(realtime boundaries·fixture·optional recipes source 포함, snapshot `artifacts/quality/realtime-boundaries.json` violations 0, `optional-recipes.json` realtime 40,811 / 42,200 gzip B), FE-GATE-020 rc=0(1,156초, `artifacts/tests/realtime-runtime-removal.xml` 7 checks 0 failures) |
|
||||
| 확인하지 못한 범위·이유 | 실제 브라우저·SSE/WS 서버·프록시(환경 없음). 짝 백엔드 실행(읽기만 허용). 0929/04-03은 코드가 그대로라 실험을 요청하지 않았다. 1103/04-03·04-04·1101/04-03 수정을 되돌리는 변이는 정적 근거로 충분해 요청하지 않았다(최소 요청). `verify:documentation`은 rc=1이지만 실패 원인은 짝 백엔드 경로를 적은 다른 문서다(`gates/verify_documentation.log`: 매뉴얼 01·02·04·README, `backend-api-and-server-state-contract.md`). 이 영역 문서(설계 0.1절, 레시피 Realtime 절)는 실패 목록에 없다 |
|
||||
| 이전 리뷰와 비교 가능한 범위 | 지난 발견 6건, 합친 중복 2건(04-03 → 07-02, 04-05 → 14-01), 이월 남음 4건을 지금 코드로 다시 판정했다(2절). 지난 라운드의 실험·변이 결과는 증거로 쓰지 않았다. 실험 P는 같은 서버 조건(503만)에 조립된 행을 써서 다시 돌렸고(04-R1 P2), 네트워크 실패·429를 더했다 |
|
||||
|
||||
## 2. 지난 발견 재확인
|
||||
|
||||
| 지난 ID | 내용 | 상태 | 근거 |
|
||||
| --- | --- | --- | --- |
|
||||
| 1103/04-01 (Medium·P2) | bounded polling 계약이 지운 V2 행 어휘로 된 자기 선언이라 V3 실행기 재시도를 막지 못한다 | **고쳐짐** (남은 틈 1) | `a65df74`. `BoundedPollOperationContract`를 지우고 operation을 V3 descriptor로 받는다(`bounded-polling.ts:33-44`). 생성 검사는 operationId, method GET·HEAD, retrySemantics SAFE·IDEMPOTENT, **`frontend.retryBudget !== 0` 거절**, `responseByteLimit` 1..8 MiB다(`:115-139`). 실행기는 `policy = operation.frontend`(`http-execution-v3.ts:557`)에서 `retryCeiling = min(policy.retryBudget, maxRetryAttempts, 2)`를 만든다(`:911-915`). 네트워크 실패 재시도(`:1060-1063`)와 status 재시도(`:1115-1124`) 모두 이 상한 아래에 있다. 그래서 같은 descriptor면 실행기 옵션과 상관없이 재시도가 0이다(정적, E1). 응답 상한은 `min(policy.maxResponseBytes, frontend.responseByteLimit)`이다(`bounded-poll-coordinator.ts:136-139`). 테스트: 거절 8가지(`bounded-polling-policy.test.ts:60-115`), 실제 V3 실행기(`maxRetryAttempts: 2`)와 503 서버로 poll 3회 = 요청 3회, 기본 GET 거절(`bounded-poll-coordinator.test.ts:1054-1163`). 게이트에서 통과(`test_unit.log`: bounded-polling-policy 11건, bounded-poll-coordinator 21건). **실험 P 재실행(04-R1, 6.1절):** 한 기여에 같은 경로 GET 둘(기본 `retryBudget: 2`, poll 전용 0)을 넣어 `composeContractContributions`로 조립했다. 조립된 기본 행은 생성 때 `TypeError`로 거절됐다(P1). poll 전용 행 + 실행기 `maxRetryAttempts: 2`에서 503·네트워크 실패·429(Retry-After 1)가 모두 poll 3회 = 요청 3회, 실행기 대기 0번이었다(P2~P4). 지난 라운드 같은 조건은 요청 9회였다. **변이 MP1(04-R2, 검사 줄 `:128` 삭제):** 3건 실패. "refuses a descriptor with one/two transport retry"(`bounded-polling-policy.test.ts:120`), "refuses the default read descriptor"(`bounded-poll-coordinator.test.ts:1134`). **변이 MP2(04-R3, 실행기 `:912` `policy.retryBudget` 삭제):** 1건 실패. "sends one request per poll attempt with a poll descriptor"가 요청 9개를 받았다(`bounded-poll-coordinator.test.ts:1161`). 변이 없는 실행은 게이트 `test_unit.log`가 통과다. V2 리터럴 필드는 src·설계 9.2에서 모두 사라졌다(`git grep` 0건, VD 문서는 새 04-03). **남은 틈:** `execute` 입력에는 descriptor가 없다(`bounded-poll-coordinator.ts:104-113`, `:307-312`). 조합 코드가 검사받은 descriptor와 다른 것(예: 같은 경로의 기본 GET, `retryBudget: 2`)을 실행기에 넘기면 막는 것이 없다. 04-R1 P5: lease는 poll 전용 행, `execute`는 기본 행 → poll 3회, 요청 9회, 실행기 대기 6번(125·250 ms × 3). 실행기를 `maxRetryAttempts: 0`으로 만들면 3회다(P6). 타입 주석(`bounded-polling.ts:33-38`, `bounded-poll-coordinator.ts:99-103`)과 설계 9.2(`:1655-1671`)가 "같은 descriptor를 넘긴다"고 적는다. 완료 기준("`retryBudget > 0` descriptor는 거절, 같은 조합에서 poll 3회 = 요청 3회")은 충족한다 |
|
||||
| 1103/04-02 (Medium·P2) | 짝 백엔드 실시간 출구와 프론트 전송 규약이 맞지 않고 어디에도 적혀 있지 않다 | **고쳐짐** (문서). 전송 불일치 자체는 제품 결정으로 남음 | `615da35`. 설계 0.1절(`realtime-events-…md:81-118`)에 transport별 대응표, push가 필요할 때의 세 길, 재검토 조건이 있다. 레시피(`optional-adapter-recipes.md:225-229`)와 매뉴얼 03(`docs/manual/03-outside-feature-folder.md:110`)이 링크한다. **백엔드 `45d2a478`에서 다시 확인(정적):** STOMP-over-SockJS `/ws`·`/topic`·구독 1개·`Map<String, String>` 투영(`src/adapter/inbound/websocket/README.md:7-12`, `:17-42`), simple broker는 재전송·영속 없음(`:77-81`), raw handler는 `servlet/PlatformWebSocketHandler.java`, `NO_SSE_EMITTER` 규칙(`ForbiddenApiArchitectureTest.java:516`), MVC SSE writer 없음(`docs/web/repository-adaptation.md:255-259`), `StreamMediaType.SSE`는 OpenAPI 생성기만 씀(`WebOpenApi32Generator.java:33`), 스트리밍 writer는 NDJSON·JSON text sequence(`web-advanced/README.md:28-29`), websocket main 코드에 `realtime.v1`·subprotocol 협상 코드 없음(`git grep` 0건). 커밋이 읽은 백엔드 `70fb80bf`과 `45d2a478` 사이 websocket 변경은 실패 로그(`StompHandlerFailureLog`)뿐이라 표의 결론이 같다. 정확히 하면 Spring STOMP 처리기는 STOMP subprotocol(`v1x.stomp`)을 협상한다(리뷰어 지식, 이 repo 코드로 확인하지 않음). `realtime.v1`이 없으니 결론은 같다. 완료 기준("대응표 하나로 지금 연결되는 조합과 새로 쓸 것을 안다")은 충족한다. 남은 것: 표는 백엔드 drift 검사(`check:backend-contract-drift`) 대상이 아니다. 백엔드가 바뀌면 사람이 0.1절 재검토 조건을 봐야 한다. push 경로 선택은 사용자 결정이다 |
|
||||
| 1103/04-03 (Low·P3, README 10.3에서 07-02로 합침) | realtime snapshot 바인딩 검사를 막는 테스트가 없다 | **고쳐짐** | `a94006b`. `realtime-stream-registry.test.ts:219-316`이 6 method × 4 retrySemantics를 CURSOR·SNAPSHOT_ONLY 두 모드로 돈다. 행은 조립한 descriptor를 `projectApiOperationRows`로 뽑은 것이다(`:227-229`). 받는 조합은 GET×SAFE·GET×IDEMPOTENT뿐이고 나머지는 throw를 기대한다. 없는 id도 거절한다(`:311-315`). 검사 코드(`realtime-streams.ts:457-474`)에서 method 조건을 지우면 HEAD×SAFE가 받아져 표가 실패한다(정적 추론, E1). 게이트 통과 30건(`test_unit.log`). 변이 실행은 07-02 대표 영역 판정을 따른다 |
|
||||
| 1103/04-04 (Low·P3) | 서버만 끊긴 실패의 이름이 transport마다 다르고 13.1 표가 맞지 않는다 | **고쳐짐** (수정이 다른 결함 둘을 만듦: 새 04-01, 04-02) | `af00067`. SSE fetch 거절(`fetch-sse-connection.ts:217-225`)·reader 거절(`:402-407`)·poll execute 거절(`bounded-poll-coordinator.ts:322-328`)이 `PROVIDER_UNAVAILABLE`(retryable)이다. WS는 원래 그렇다. src/adapters/realtime에서 transport가 `OFFLINE`을 만드는 곳은 없다. 남은 `OFFLINE`은 환경 신호(`bounded-poll-coordinator.ts:177`, `:216-219`, `:597`, `reconnect-coordinator.ts:458`, `:720`, `:758`)뿐이다. 13.1 표가 두 행을 고쳤다(`realtime-events-…md:1955`, `:1961`). 5.3도 고쳤다(`:825-829`). 테스트 기대값 3곳이 새 kind를 고정한다(`realtime-reconnect-coordinator.test.ts:2122-2137`, `:2181-2198`, `bounded-poll-coordinator.test.ts:906-948`). 그 기대값은 정확한 kind를 비교하므로 옛 kind로 되돌리면 실패한다(정적). CHANGELOG [계약] 행(`CHANGELOG.md:197`) |
|
||||
| 1103/04-05 (Low·P3, README 10.3에서 14-01로 합침) | CHANGELOG에 handoff kind 변경 [계약] 행이 없고 알려진 제한이 틀렸다 | **고쳐짐** | `CHANGELOG.md:198`이 stream·handoff coordinator 둘과 `17fa8d1`을 적는다. 알려진 제한(`:256-277`)에 `IDLE_TIMEOUT` 줄이 없다(`grep IDLE_TIMEOUT CHANGELOG.md` → `:198` 하나) |
|
||||
| 1103/04-06 (Low·P3) | realtime 레지스트리의 codec·mapper 바인딩을 기능이 채울 자리가 없다 | **고쳐짐** (최소 방향: 문서) | `5b2106d`. 레시피(`optional-adapter-recipes.md:230-245`)가 세 바인딩의 출처와 맞아야 하는 id를 적는다. 적힌 이름이 모두 있다: `loadInstalledFeatureRuntimeRegistries`(`installed-feature-runtime-registries.ts:30`, 반환 `apiOperations` `:67-70`), `runtimeSchemaCodecFromValidator`(`schema-registry.ts:39`), `composeRuntimeSchemaCodecs`(`:59`), `BoundaryMapper`·`composeBoundaryMapperRegistry`(`boundary-mapper.ts:44`, `:56`). 주의 한 가지: 그 함수는 설치된 모든 기능의 실행부를 적재한다. 앱 부팅은 일부러 부르지 않는다(`installed-feature-runtime-registries.ts:17-29`). realtime 조합이 런타임에 부르면 모든 기능 청크를 받는다. 레시피는 `projectApiOperationRows`도 함께 적어 한 기능 기여만 뽑는 길이 있다. 코드 칸 추가는 04-02 경로 선택 뒤로 미뤘다(커밋 본문) |
|
||||
| 0929/04-02 (Medium·P2) | SSE↔reconnect 세션 bridge 부재, EOF 분류 미정 | **남음** | `readSseForReconnect`(`fetch-sse-connection.ts:498-513`)가 유일한 도구다. 테스트 안의 bridge는 EOF를 `PROTOCOL_MISMATCH`/`RECEIVE`/`retryable:false`로 끝낸다(`realtime-reconnect-coordinator.test.ts:1791-1798`). 설계 6.3 상태표는 `204`만 정하고 `200` 뒤 EOF는 정하지 않는다(`realtime-events-…md:1082-1092`). 영역 커밋 중 이것을 바꾼 것이 없다 |
|
||||
| 0929/04-03 (Low·P3) | SSE `retry:` 처리 규칙이 설계 5.3·6.3과 코드에서 다르다 | **남음** (결정 대기, 1103 README 14.4) | `sse-parser.ts:330-341` 그대로다(60초 넘는 값은 버림). 5.3은 "SSE `retry`도 not-before, 상한을 넘으면 종료"(`:801-805`), 6.3은 "ceiling을 통과한 경우 다음 delay hint로만"(`:1077-1078`)이라 여전히 다른 말을 한다. `git diff e40684b..8a44226 -- src/adapters/realtime/sse/sse-parser.ts src/adapters/realtime/reconnect-coordinator.ts` 0줄 |
|
||||
| 0929/04-04 (Low·P3) | hidden 탭에서 heartbeat를 멈춘 조용한 WS는 예산을 새로 받지 못한다 | **고쳐짐** | `5d0f5ad`. `heartbeatEligible` 옆 주석(`websocket-connection.ts:182-188`)과 설계 5.3(`:813-816`)이 결과와 대처(닫거나 visible 복귀 때 새 run)를 적는다. 완료 기준("주석만 보고 결과를 안다")을 충족한다. 동작은 바뀌지 않았다 |
|
||||
| 1101/04-03 (Low·P3) | WS 구독별 초당 event 상한 테스트·문서 없음 | **고쳐짐** | `3bc690d`. `websocket-connection.test.ts:652-707`이 상한 2로 2개 → 1초 뒤 2개(열림) → 1개 더(닫힘, `EVENT_RATE_EXCEEDED`)를 본다. 검사(`websocket-connection.ts:995-1015`)를 끄면 `onEvent` 5회·`OPEN`이라 테스트가 실패한다(정적). 설계 11절 상한표에 행이 생겼다(`:1840`). 게이트 통과(websocket-connection 24건) |
|
||||
| 0929/04-05 (Low·P3) | CHANGELOG [계약] 문장이 초기화 조건보다 넓다 | 지난 라운드에 닫음 | 1103 영역 문서 2절 "바뀜 — 닫아도 된다". 다시 보지 않았다 |
|
||||
|
||||
### 2.1 수정이 검사를 약하게 만들었는가 (`git diff e40684b..8a44226`)
|
||||
|
||||
| 커밋 | 테스트·검사 변경 | 판정 |
|
||||
| --- | --- | --- |
|
||||
| `a65df74` | 리터럴 선언 객체를 `TEST_LIST_HTTP_CONTRACT`를 펼친 descriptor로 바꿨다. 거절 사례가 2개에서 8개가 됐고 실제 V3 실행기 테스트가 생겼다 | 강해짐. 테스트 descriptor는 손으로 펼친 객체지만, 조립된 행으로도 같은 결과가 나왔다(04-R1 P1~P4). MP1·MP2 변이가 잡힌다(04-R2, 04-R3) |
|
||||
| `af00067` | 기대 kind 3곳을 `OFFLINE` → `PROVIDER_UNAVAILABLE`로 바꿨다. poll "던지는 executor는 `OFFLINE`으로 끝" 테스트를 "lease 안에서 재시도"로 바꿨다 | **약해짐 1건(새 04-01).** 0929/04-01 회귀를 막던 두 테스트(`realtime-reconnect-coordinator.test.ts:2095`, `:2140`)가 이제 `PROVIDER_UNAVAILABLE` 경로만 지난다. 환경은 online이고 transport가 `OFFLINE`을 내는 테스트는 남아 있지 않다(`OFFLINE`을 만드는 곳은 `:503` 하나이고 그 테스트는 환경 offline을 함께 보낸다). 변이 MR1이 realtime 테스트 전부를 통과했다(04-R4). poll 테스트 변경은 동작 변경을 따른 것이다(새 04-02) |
|
||||
| `a94006b`, `3bc690d` | 테스트만 더했다 | 강해짐 |
|
||||
| `08ed0a0` | `tests/unit/realtime/fixture.ts`의 snapshot 행에 새 투영 칸 10개를 더했다 | 바뀐 검사 없음 |
|
||||
| `5d0f5ad`, `5b2106d`, `615da35` | 문서·주석만 | 해당 없음 |
|
||||
|
||||
시간 상한·skip·허용 목록 확대는 영역 diff에 없다.
|
||||
|
||||
## 3. 이번 발견 (36.3)
|
||||
|
||||
이번 발견 3건: **Low 3** · **P3 3** · 구조적 위험 2, 확인된 결함 1.
|
||||
|
||||
### 04-01 서버 끊김 kind를 바꾼 뒤, 0929/04-01 회귀를 막던 테스트가 transport `OFFLINE` 경로를 지나지 않는다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험(수정이 만든 테스트 공백) |
|
||||
| 관련 관점 | 10, 21, 6, 28 |
|
||||
| 근거 | ① 규칙: 환경이 online이면 transport가 보고한 `OFFLINE`도 online 이벤트를 기다리지 않고 backoff로 재시도한다(`reconnect-coordinator.ts:111-117`, 설계 5.3 `:828-829` "조합 코드가 만든 transport가 `OFFLINE`을 보고해도"). `4d27b20`이 이 규칙을 위해 `requireOnline()` 두 줄을 지웠다. ② 그 수정을 막던 테스트는 SSE fetch·reader 거절이 `OFFLINE`이던 것을 이용했다. `af00067` 뒤 SSE는 `PROVIDER_UNAVAILABLE`을 낸다(`fetch-sse-connection.ts:221`, `:404`). 두 테스트(`realtime-reconnect-coordinator.test.ts:2095-2138`, `:2140-2198`)는 이제 `PROVIDER_UNAVAILABLE` 재시도만 본다. ③ transport가 `OFFLINE`을 내고 환경은 online인 테스트가 없다. 테스트 파일에서 `OFFLINE`을 만드는 곳은 `:503` 하나이고, 그 테스트는 환경 offline 이벤트를 같이 보낸다(`:522-526`). ④ 템플릿 transport는 이제 `OFFLINE`을 내지 않는다(13.1 `:1955`). 그래서 회귀가 생겨도 템플릿 SSE·WS 경로는 멈추지 않는다. 멈추는 것은 조합 코드가 만든 transport(예: 04-02 대응표 길 2의 STOMP transport)와 `classifyClosed`가 `OFFLINE`을 돌려주는 경우다. ⑤ **변이 MR1(04-R4, `4d27b20`이 지운 두 줄을 `reconnect-coordinator.ts:806`, `:1001` 뒤에 되살림): realtime 14파일 267건 모두 통과(생존).** 같은 실행에서 리뷰 대조 C1(attempt가 `OFFLINE`/`CONNECT`로 실패)·C2(세션이 `OFFLINE`/`RECEIVE`로 닫힘)는 실패했다. 둘 다 attempt 1회 뒤 run이 끝나지 않았다(`attempts 1`, `result null`, "expected 1 to be greater than 1"). 변이 없는 C1·C2는 attempt 3회 뒤 `OFFLINE` retryable로 끝난다(04-R1). 즉 규칙이 지금 동작에 실제로 걸려 있고, 저장소 테스트만 그것을 보지 못한다 |
|
||||
| 발생 조건 | 누군가 reconnect coordinator의 재시도 분기를 고치며 transport `OFFLINE`에 online 대기를 다시 걸 때 |
|
||||
| 영향 | CI가 통과한다. 그 뒤 transport가 `OFFLINE`을 내는 조합에서 서버만 끊기면 run이 재시도도 종료도 없이 멈춘다(0929/04-01과 같은 모양, 리뷰어 추론). 데이터 손상은 없다 |
|
||||
| 심각도·우선순위 | Low · P3. 지금 코드는 맞다. 템플릿 transport는 영향이 없다. 회귀 탐지 공백이다 |
|
||||
| 통제·증거 | 규칙 M1(주석·설계)·M2(구현) · 위반 검출 없음(MR1 생존) · E1 + E2(04-R1, 04-R4) |
|
||||
| 확실성과 남은 가정 | 테스트 공백과 변이 생존을 실행으로 확인했다. 멈춤의 영향(조합 transport에서 run이 끝나지 않음)은 리뷰 대조 테스트로 확인했다. 실제 조합 transport는 repo에 없다 |
|
||||
| 결정의 근거 | 적용 제외 — 기존 규칙에 테스트를 다시 붙이는 문제다 |
|
||||
| 이해 비용 | 이 분기를 고치는 사람이 테스트로 규칙을 확인할 수 없다. 규칙은 주석 한 문단에만 있다 |
|
||||
| 최소 개선 방향 | `realtime-reconnect-coordinator.test.ts`에 조합 transport 테스트 둘을 더한다. 환경 online, attempt가 `OFFLINE`/`CONNECT`로 실패 → 재시도 후 상한에서 끝남. 세션이 `OFFLINE`/`RECEIVE`로 닫힘 → 재시도. 리뷰 실험 파일의 C1·C2와 같다 |
|
||||
| 대안 비교 | 적용 제외 |
|
||||
| 단순화의 보존 조건 | 적용 제외 |
|
||||
| 비용·부작용 | 테스트 2건 |
|
||||
| 재검토 조건 | 적용 제외 |
|
||||
| 완료 기준 | 변이 MR1이 realtime 테스트에서 실패한다 |
|
||||
| 검증 방법 | 04-R4와 같은 패치(`scratchpad/r4/requests/04-R4-mr1.patch`의 src 부분)를 다시 넣고 realtime 테스트를 돌린다 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
|
||||
### 04-02 poll `execute`가 던지면 서버 장애로 보고 재시도해, V3 조합에서는 조합 코드 결함이 서버 장애와 예산 소진으로 보인다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험(`af00067`이 만든 진단 의미 불일치) |
|
||||
| 관련 관점 | 8, 24, 6, 7 |
|
||||
| 근거 | ① poll은 `execute`의 reject를 `PROVIDER_UNAVAILABLE`/`POLL`/`retryable:true`로 바꾼다(`bounded-poll-coordinator.ts:322-328`). 주석은 "No server answered"라고 적는다(`:323`). 이 kind는 재시도 대상이다(`:121-125`). 설계 13.1도 "poll `execute` 거절"을 "환경은 online인데 서버·프록시에 닿지 않은 것"이라 적는다(`realtime-events-…md:1961`). ② V3 실행기는 fetch 거절을 잡아 `NETWORK_FAILURE` 결과로 돌려준다(`http-execution-v3.ts:1036-1049`, `:1077-1080`). 설계 9.2가 권하는 조합(`execute` 안에서 V3 실행기 호출, `:1655-1671`)에서 네트워크 실패는 던짐이 아니라 결과다. 그 조합에서 `execute`가 던지는 경우는 결과 매핑·디코딩 같은 조합 코드 결함이다. ③ 테스트가 지금 동작을 고정한다. `TypeError`를 던지는 execute → `maxAttempts`번 다시 불림, 관측 `ATTEMPT_FINISHED: PROVIDER_UNAVAILABLE` × 3, 결과 `POLL_BUDGET_EXHAUSTED`(`bounded-poll-coordinator.test.ts:906-948`). ④ `execute` 타입 주석(`:104-113`)은 던졌을 때의 처리를 말하지 않는다. CHANGELOG는 "poll은 던지는 execute도 lease 안에서 다시 시도한다"고 적는다(`CHANGELOG.md:197`). 커밋 `af00067`도 "조합 코드의 버그 포함"을 위험으로 적었다 |
|
||||
| 발생 조건 | 조합 코드의 `execute`가 결과를 만들다 던질 때(스키마 매핑 오류, 잘못된 필드 접근 등) |
|
||||
| 영향 | 결함이 즉시 드러나지 않는다. lease가 backoff로 최대 `maxAttempts`(상한 120)번 요청하고 `POLL_BUDGET_EXHAUSTED`로 끝난다. 관측과 kind로 보는 화면은 "서비스 이용 불가"로 본다. 원인 예외는 어디에도 남지 않는다. 데이터 손상은 없다. 요청 수는 정상 poll과 같은 상한 안이다 |
|
||||
| 심각도·우선순위 | Low · P3. 진단을 늦추는 문제이고 상한이 있다 |
|
||||
| 통제·증거 | M1(동작은 CHANGELOG에만 있음) · E1 + E2(그 동작을 고정한 테스트가 게이트에서 통과) |
|
||||
| 확실성과 남은 가정 | 코드와 테스트로 확인했다. 조합 코드가 V3 실행기 대신 `fetch`를 직접 부르면 던짐이 네트워크 실패일 수 있다. 그 조합은 설계가 권하지 않는다 |
|
||||
| 결정의 근거 | 확인한 사실: 1103/04-04의 목적은 서버 끊김 이름을 transport마다 맞추는 것이었다. 기록된 의도: `af00067` 본문 "executor가 `PROVIDER_UNAVAILABLE`을 돌려준 경우와 같은 처리". 리뷰어 추론: poll의 "transport"는 `execute`이고, V3 조합에서 그 경계의 네트워크 실패는 이미 결과로 온다. 던짐까지 서버 장애로 묶을 이유가 약하다. 41절: (a) 현상 유지 (b) 던짐은 재시도하지 않고 `PROTOCOL_MISMATCH`(조합 결함)로 끝냄 (c) 동작은 두고 `execute` 주석과 13.1에 "던짐 = 조합 코드가 실패를 결과로 바꾸지 못함, 서버 장애로 재시도됨"을 적음 |
|
||||
| 이해 비용 | 조합자가 poll이 끝난 이유를 보려면 coordinator 코드를 읽어야 던짐이 섞였는지 안다 |
|
||||
| 최소 개선 방향 | (c) 주석 2줄 + 13.1 한 구절. 바꿀 거면 (b)이고 테스트 1건 기대값을 고친다 |
|
||||
| 대안 비교 | (a)는 비용 0이고 진단이 늦다. (b)는 결함이 첫 attempt에서 드러난다. fetch를 직접 쓰는 조합에서는 네트워크 실패가 재시도 없이 끝난다. (c)는 동작이 같고 읽는 사람만 안다 |
|
||||
| 단순화의 보존 조건 | lease 상한(시도·시간·바이트), abort 시 `ABORTED`, 환경 offline 시 `OFFLINE` |
|
||||
| 비용·부작용 | (b)는 공개 동작 변경([계약]) |
|
||||
| 재검토 조건 | 템플릿이 poll `execute` 기본 구현(V3 실행기 래퍼)을 제공하게 되면 (b)로 간다 |
|
||||
| 완료 기준 | 던지는 execute의 결과를 보고 조합 결함과 서버 장애를 구분할 수 있다(동작이나 문서로) |
|
||||
| 검증 방법 | (b)면 `bounded-poll-coordinator.test.ts:906-948` 기대값 변경. (c)면 문서 리뷰 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
|
||||
### 04-03 VD-28과 설계 3절이 지운 V2 poll 예산으로 poll 규칙을 적는다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(문서) |
|
||||
| 관련 관점 | 9, 24, 17 |
|
||||
| 근거 | `VD-28-realtime-events-web-push-and-bounded-polling.md:441-444`: "operation은 registered terminal·replay-safe REST `QUERY`", "Poll-bound VD-23 budget은 `maxAttempts=1`, `authRecoveryCount=0`, `maxCumulativeSleepMs=0`". `:117-118`: "VD-23의 terminal·replay-safe REST `QUERY` execution contract를 재사용". 설계 3절도 "REST `QUERY` operation"이라 적는다(`realtime-events-…md:363-370`). 이 칸들은 지운 V2 실행 예산이다. VD-23 상태 줄은 V2 실행 경로를 지웠다고 적는다(`VD-23-…md:10-13`). 지금 규칙은 descriptor `retryBudget: 0`(설계 9.2 `:1655-1671`)이고, V2 이름은 src에 없다(`git grep authRecoveryCount -- src` 0건). `a65df74`는 설계 9.2만 고쳤다(`git show --stat a65df74`) |
|
||||
| 발생 조건 | 채택자가 VD-28을 보고 poll을 조립할 때 |
|
||||
| 영향 | 없는 예산 칸을 찾는다. 지금 규칙(`retryBudget: 0`)은 VD-28에서 찾을 수 없다 |
|
||||
| 심각도·우선순위 | Low · P3. 상세 설계 9.2는 맞다. VD-28 머리말이 상세 설계를 가리킨다 |
|
||||
| 통제·증거 | M1(두 문서가 다른 말) · E1 |
|
||||
| 확실성과 남은 가정 | 확인한 사실이다 |
|
||||
| 결정의 근거 | 적용 제외 — 기록 누락이다. 1103 조치(14.3절)가 VD-23·VD-24의 V2 표시를 고친 것과 같은 종류다 |
|
||||
| 이해 비용 | 결정 문서와 상세 설계를 대조해야 한다 |
|
||||
| 최소 개선 방향 | VD-28 `:441-444`를 "poll operation은 GET·HEAD, SAFE·IDEMPOTENT인 V3 descriptor이고 `frontend.retryBudget` 0(상세 설계 9.2, 1103/04-01)"으로, `:117-118`과 설계 `:365-370`의 "REST `QUERY`"를 같은 말로 바꾼다 |
|
||||
| 대안 비교 | 적용 제외 |
|
||||
| 단순화의 보존 조건 | 적용 제외 |
|
||||
| 비용·부작용 | 문서 4줄 |
|
||||
| 재검토 조건 | 적용 제외 |
|
||||
| 완료 기준 | `git grep -n "authRecoveryCount\|maxCumulativeSleepMs" -- docs/architecture/decisions/VD-28*` 0건, VD-28이 `retryBudget` 0 규칙을 적는다 |
|
||||
| 검증 방법 | 문서 대조 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
|
||||
## 4. 28개 관점 판정 (36.2)
|
||||
|
||||
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역 판정을 따름
|
||||
|
||||
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 1 | 코드 성숙도 | 적용 | M2 / M2 | E2 realtime 14파일 267건 통과(게이트 `test_unit.log`) | O. 바뀐 코드는 작고(poll 검사, kind 3곳) 상태 기계·terminal close는 그대로다 |
|
||||
| 2 | 구조적 성숙도 | 적용 | M4 / M4 일부 | E2 `check:architecture` rc=0(게이트, 419 modules), FE-GATE-010 rc=0(snapshot `realtime-boundaries.json` violations 0) | O. `bounded-polling.ts`가 `external-contract-runtime.ts`를 type import로만 읽는다(`:1`). 제거 드릴이 통과했다(27번) |
|
||||
| 3 | 변경 용이성 | 적용 | M2 / M2 | E1 | P. poll 조립이 V3 descriptor 하나로 줄었다. poll 전용 operation을 따로 등록해야 한다(조립은 같은 경로 두 GET을 막지 않는다: `external-contract-runtime.ts:1024-1036`은 operationId 중복만 본다, 04-R1 P0가 확인). SSE bridge는 여전히 직접 작성(0929/04-02) |
|
||||
| 4 | 인지 부하 | 적용 | M1 / M1 | E1 | P. V2 리터럴 9칸이 사라져 poll 읽기가 쉬워졌다. `runLoop` 크기는 그대로다. VD-28은 아직 옛 칸을 적는다(04-03) |
|
||||
| 5 | 위험 가시성 | 적용 | M1 / M1 | E1 | P. poll 남은 틈(다른 descriptor로 실행)은 타입 주석과 설계 9.2에 적혀 있다. 던지는 execute 재시도는 CHANGELOG에만 있다(04-02) |
|
||||
| 6 | 실패 성숙도 | 적용(깊게) | M3 / M3 일부 | E1·E2(04-R1~R4) | P. poll 재시도 3배가 같은 descriptor 조건에서 막혔다(04-R1 P2~P4, MP1·MP2 검출). 서버 끊김 kind가 같아졌다. 회귀 테스트 공백(04-01), 던짐 분류(04-02), EOF 미정(0929/04-02), `retry:` 규칙(0929/04-03) |
|
||||
| 7 | 운영 성숙도 | 적용 | M2 / M2 | E1 | P. 서버 끊김이 transport와 상관없이 `PROVIDER_UNAVAILABLE`이다. poll 관측에서 조합 결함이 서버 장애로 보인다(04-02) |
|
||||
| 8 | 디버깅 가능성 | 적용 | M2 / M1 | E1·E2 | P. 04-02(던짐의 원인 예외가 남지 않음). 13.1 `OFFLINE` 행은 이제 실제와 맞다 |
|
||||
| 9 | 유지보수 성숙도 | 적용 | M1 / M1 | E1 | P. CHANGELOG 누락(1103/04-05)이 고쳐졌다. VD-28 옛 어휘(04-03). 설계 5.3의 줄 번호(`reconnect-coordinator.ts:556-568`)는 지금 코드(`:559-568`)와 거의 맞는다 |
|
||||
| 10 | 테스트 성숙도 | 적용(깊게) | M3 / M3 일부 | E2 게이트, 변이 3건(MP1·MP2 검출, MR1 생존) | P. 지난 생존 변이 자리(S·P·R7)에 테스트가 생겼다. poll 수정은 변이 두 개로 막힌다. 수정이 만든 공백 1(04-01, MR1 생존). poll 테스트 descriptor는 손으로 펼친 객체지만 조립 경로도 같은 결과다(04-R1) |
|
||||
| 11 | 데이터 성숙도 | 적용 | M2 / M2 | E1 | O. cursor는 effect 성공 뒤에만 전진한다. 이번 커밋들이 바꾸지 않았다 |
|
||||
| 12 | 동시성 성숙도 | 적용 | M3 / M3 | E2 | O. run 1개, DRAINING·generation fence 그대로. 영역 diff는 fence를 건드리지 않았다 |
|
||||
| 13 | 확장성 | 적용 | M3 / M3 | E1·E2(04-R1) | P. poll 요청 수가 시도 수와 같아졌다(조건: 같은 descriptor, P2~P4). 다른 descriptor면 3배다(P5). WS 초당 상한 테스트가 생겼다 |
|
||||
| 14 | 성능 성숙도 | 적용 | M2 / M2 | E2 FE-GATE-010 rc=0, snapshot `optional-recipes.json` realtime 40,811 / 42,200 gzip B(여유 1,389, 지난 라운드 40,857) | P. 레시피 번들 예산 안이다. production 번들에는 들어가지 않는다. 브라우저 실행 성능은 미측정 |
|
||||
| 15 | 보안 성숙도 | 적용 | M4 / M4 | E1 | O. 고정 same-origin endpoint, URL credential 없음. 이번에 바뀐 곳 없음 |
|
||||
| 16 | 의존성 성숙도 | 적용 | M3 / M3 | E1 | O. 외부 패키지 없음 |
|
||||
| 17 | API / Contract 성숙도 | 적용(깊게) | M3 / M3 일부 | E1·E2 | P. poll 계약이 V3 descriptor에 묶였다. snapshot 바인딩이 표로 고정됐다. `execute`가 descriptor를 받지 않는 틈(2절). VD-28 옛 계약(04-03) |
|
||||
| 18 | 배포 성숙도 | 적용 | M2 / M1 | E1 | P. 백엔드 배포의 SSE EOF를 재연결할지 미정(0929/04-02) |
|
||||
| 19 | 설정 성숙도 | 적용 | M2 / M2 | E1 | P. `MAX_RETRY_ATTEMPTS` 기본 2가 poll에 걸리지 않는다(descriptor 0이 우선, `http-execution-v3.ts:911-915`). 파서 `maxRetryMs`와 정책 `maxDelayMs`는 따로 논다(0929/04-03) |
|
||||
| 20 | 개발자 경험 | 적용 | M2 / M2 | E1 | P. 짝 백엔드 대응표와 바인딩 출처가 문서 한 곳에 있다. SSE bridge 예시는 테스트 안에만 있다. 바인딩 출처 함수가 모든 기능 청크를 적재한다는 주의가 레시피에 없다(2절 1103/04-06) |
|
||||
| 21 | Guardrail 성숙도 | 적용 | M3 / M3 일부 | E2 check:architecture, FE-GATE-010·020, 변이 MP1·MP2 검출 | P. poll 검사는 생성 때 거절한다(M4에 가까운 경계 검사). 0929/04-01 규칙 회귀 검출 공백(04-01, MR1 생존) |
|
||||
| 22 | 추상화 성숙도 | 적용 | M2 / M2 | E1 | P. poll 계약과 실행기가 같은 descriptor 칸으로 이어졌다. `execute`는 그 descriptor를 받지 않는다 |
|
||||
| 23 | 일관성 | 적용 | M2 / M2 | E1 | P. 서버 끊김이 세 transport에서 같은 kind다. `APPLY_FAILED`의 `retryable`이 handoff는 true, stream은 false인 것(1103 4절 23번)은 그대로다 |
|
||||
| 24 | 네이밍 / 의미 성숙도 | 적용 | M1 / M1 | E1 | P. `OFFLINE`이 환경 신호 하나의 뜻이 됐다. poll의 `PROVIDER_UNAVAILABLE`에 조합 결함이 섞인다(04-02). VD-28 V2 이름(04-03) |
|
||||
| 25 | 조직 확장성 | 적용 제외 — 작성자 1인 | - | - | - |
|
||||
| 26 | Ownership 성숙도 | 적용 제외 — 제품 조합 없음 | - | - | -. 짝 백엔드 push 경로 선택의 결정자는 사용자다(1103/04-02) |
|
||||
| 27 | 삭제 가능성 | 적용 | M3 / M3 | E2 FE-GATE-020 rc=0(CI=true, `realtime-runtime-removal.xml` 7 checks 0 failures: typecheck·lint·architecture·test·build·optional-catalog·ci-contract) | O. 세 라운드 만에 처음으로 실행 증거가 생겼다(오케스트레이터 실행) |
|
||||
| 28 | 회복 가능성 | 적용 | M3 / M3 일부 | E1·E2 | P. 서버 끊김 뒤 재연결로 회복한다. 그 규칙의 회귀 테스트가 템플릿 transport 경로만 본다(04-01). EOF 뒤 회복은 조합 코드 몫(0929/04-02) |
|
||||
|
||||
## 5. 미검증
|
||||
|
||||
| 항목 | 왜 확인하지 못했나 | 확인하려면 |
|
||||
| --- | --- | --- |
|
||||
| 1103/04-03·04-04·1101/04-03 수정을 되돌리는 변이 | 기대값이 정확한 비교임을 정적으로 확인해 요청하지 않았다(최소 요청). 1103/04-03은 07-02 대표 영역의 판정을 따른다 | 필요하면 다음 라운드에서 한 번씩 |
|
||||
| 실제 브라우저·SSE/WS 서버·프록시, 짝 백엔드 실행 | 환경 없음, 백엔드는 읽기만 | 설계 15.3의 로컬 서버 + 브라우저 실행 |
|
||||
| 0929/04-03의 현재 동작 | 코드가 그대로라 실험을 요청하지 않았다 | 0929 실험 E9를 다시 돌림 |
|
||||
| 브라우저에서의 realtime 실행 성능 | 측정 환경 없음. 번들 크기만 게이트에서 봤다 | lab 측정 |
|
||||
|
||||
## 6. 실행 기록
|
||||
|
||||
모든 배치 항목: desktop `/home/donghyeon/workspace/clean-architecture-frontend-template`, 오케스트레이터 실행, env local, 각 항목 전후로 `8a44226`으로 되돌림(restore clean). 로그: `scratchpad/r4/results/04/04-R1.log`~`04-R4.log`. 변이 없는 대조: realtime 14파일 267건은 게이트 `gates/test_unit.log`가 통과다. 04-R1은 실험 파일 자체라 04-R4의 대조다.
|
||||
|
||||
| 이름 | 명령 | 변이 | rc | 결과 | lock 대기 | 부하 |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| `04-poll-mut` | `bash /tmp/claude-gates/r4/mut/04-driver.sh` | 실험 파일 + 변이 스크립트 | 없음 | **돌지 않았다.** 처음 건 ssh가 끊긴 뒤 원격 대기가 남아 lock 획득 전에 직접 끊었다. 다시 건 실행은 19:55 일괄 취소로 끝났다(`exp/04-poll-mut.stdout` 빈 파일, log 없음). checkout에 손대지 않았다 | 취소 | - |
|
||||
| 04-R1 | `node scripts/run-vitest.ts run tests/unit/zz-review04/ --reporter=default` | 실험 파일 `tests/unit/zz-review04/zz-review04-1105.test.ts`만 추가(src 변경 없음) | 0 | 9건 통과. 6.1절 표 | 배치 | 2.59 |
|
||||
| 04-R2 (MP1) | `node scripts/run-vitest.ts run tests/unit/realtime/ --reporter=default` | `bounded-polling.ts:128` `frontend.retryBudget !== 0 \|\|` 삭제 | 1 | **검출.** 3건 실패 / 267: `bounded-polling-policy.test.ts` "refuses a descriptor with one transport retry"·"two transport retries"(`:120`, expected function to throw), `bounded-poll-coordinator.test.ts` "refuses the default read descriptor, whose executor retries"(`:1134`) | 배치 | 2.59 |
|
||||
| 04-R3 (MP2) | 같음 | `http-execution-v3.ts:912` `policy.retryBudget,` 삭제 | 1 | **검출.** 1건 실패 / 267: "sends one request per poll attempt with a poll descriptor"(`bounded-poll-coordinator.test.ts:1161`, expected length 3, got 9) | 배치 | 2.59 |
|
||||
| 04-R4 (MR1) | `node scripts/run-vitest.ts run tests/unit/realtime/ tests/unit/zz-review04/ --reporter=default` | `reconnect-coordinator.ts:806`, `:1001` 뒤에 `if (… .kind === "OFFLINE") requireOnline();` 두 줄 + 04-R1 실험 파일 | 1 | **realtime 14파일 267건 모두 통과(생존).** 실패는 리뷰 대조 C1·C2 둘뿐(15파일 중 1, 276건 중 2, "expected 1 to be greater than 1", `attempts 1`, `result null`). P0~P6은 04-R1과 같은 값 | 배치 | 2.38 |
|
||||
|
||||
### 6.1 실험 P와 대조 C (04-R1)
|
||||
|
||||
한 기여(`TEST_CONTRACT_CONTRIBUTION`을 펼친 것)에 같은 경로 GET 둘을 넣어 `composeContractContributions`로 조립했다. 기본 행 `TEST_LIST_ENTITIES`(`retryBudget: 2`)와 poll 전용 행 `TEST_POLL_ENTITIES`(`retryBudget: 0`)다. 둘 다 조립됐고 동결돼 있다(P0). poll `maxAttempts: 3`. `execute`는 `createContractHttpExecutor`(`maxRetryAttempts: 2`, 앱 기본값)를 부른다. 가짜 clock, 실행기 `sleep`은 즉시 끝나는 함수로 주입했다.
|
||||
|
||||
| 실험 | lease에 묶은 행 | 실행기에 넘긴 행 | 실행기 `maxRetryAttempts` | 서버 | poll 시도 | 실제 요청 | 실행기 대기 | 결과 |
|
||||
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
|
||||
| P1 | 기본(2) | — | 2 | — | — | — | — | 생성 때 `TypeError` |
|
||||
| P2 | poll(0) | poll(0) | 2 | 503 | 3 | **3** | 0 | `POLL_BUDGET_EXHAUSTED` |
|
||||
| P3 | poll(0) | poll(0) | 2 | fetch 거절 | 3 | **3** | 0 | `POLL_BUDGET_EXHAUSTED` |
|
||||
| P4 | poll(0) | poll(0) | 2 | 429 + `Retry-After: 1` | 3 | **3** | 0 | `POLL_BUDGET_EXHAUSTED` |
|
||||
| P5 | poll(0) | **기본(2)** | 2 | 503 | 3 | **9** | 6번(125·250 ms × 3) | `POLL_BUDGET_EXHAUSTED` |
|
||||
| P6 | poll(0) | 기본(2) | 0 | 503 | 3 | 3 | 0 | `POLL_BUDGET_EXHAUSTED` |
|
||||
|
||||
지난 라운드 실험 P(같은 503, 실행기 기본값)는 요청 9회였다. 같은 descriptor를 쓰면 지금은 3회다(P2). P5는 남은 틈이다(2절).
|
||||
|
||||
대조 C는 reconnect coordinator(`maxAttempts: 2`)에 조합 transport를 붙였다. 환경은 계속 online이다.
|
||||
|
||||
| 실험 | transport 동작 | 변이 없음(04-R1) | 변이 MR1(04-R4) |
|
||||
| --- | --- | --- | --- |
|
||||
| C1 | attempt가 `OFFLINE`/`CONNECT`/retryable로 실패 | attempt 3회, `OFFLINE` retryable로 끝남 | attempt 1회, run이 끝나지 않음(실패) |
|
||||
| C2 | 세션이 열린 뒤 `OFFLINE`/`RECEIVE`/retryable로 닫힘 | attempt 3회, `OFFLINE` retryable로 끝남 | attempt 1회, run이 끝나지 않음(실패) |
|
||||
|
||||
인용한 오케스트레이터 결과(직접 실행 아님): `gates/summary.txt` check:architecture rc=0(3초), check:types rc=0, lint rc=0, test:unit rc=0(25초, 194파일 2,883건), test:component·test:integration·test:contract·test:runtime-schema·check:adapter-inventory·check:ci rc=0, verify:documentation rc=1(이 영역 밖 문서의 짝 백엔드 경로). `merge-48/summary.txt`(CI=true env) FE-GATE-001~012·020 rc=0, FE-GATE-013 rc=1(이 영역 밖). snapshot `artifacts/quality/realtime-boundaries.json` violations 0, `artifacts/quality/optional-recipes.json` realtime 40,811 / 42,200 gzip B(여유 1,389), `artifacts/tests/realtime-runtime-removal.xml` 7 checks 0 failures.
|
||||
|
||||
## 7. 새 발견 요약
|
||||
|
||||
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 04-01 | Low·P3 | 구조적 위험 | 서버 끊김 kind 변경 뒤 0929/04-01 회귀 테스트가 transport `OFFLINE` 경로를 지나지 않는다. 지운 두 줄을 되살려도 realtime 테스트가 모두 통과한다(04-R4) | `tests/unit/realtime/realtime-reconnect-coordinator.test.ts:2095-2198`, `src/adapters/realtime/reconnect-coordinator.ts:111-117` |
|
||||
| 04-02 | Low·P3 | 구조적 위험 | poll `execute`의 던짐을 서버 장애로 보고 재시도해 조합 결함이 서버 장애·예산 소진으로 보인다 | `src/adapters/realtime/polling/bounded-poll-coordinator.ts:322-328`, `tests/unit/realtime/bounded-poll-coordinator.test.ts:906-948` |
|
||||
| 04-03 | Low·P3 | 확인된 결함 | VD-28·설계 3절이 지운 V2 poll 예산·`REST QUERY`로 poll 규칙을 적는다 | `docs/architecture/decisions/VD-28-realtime-events-web-push-and-bounded-polling.md:117-118`, `:441-444` |
|
||||
@@ -0,0 +1,242 @@
|
||||
# 영역 05 — 저장소·adapter kernel
|
||||
|
||||
> 검토일 2026-11-05 · 기준 `8a44226`(`8a4422624e81e5d13a3809e212e826ff75aac62b`, 브랜치 `fix/maturity-review-2026-11-03`. 노트북 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/application/ports/browser-file-storage/opfs-ports.ts`, `src/contracts/storage-keys.ts`, `src/bootstrap/runtime-adapters.ts`·`boot-release-recovery.ts`·`optional-runtime-host.ts`·`product-composition-contract.ts`, `recipes/frontend-capabilities/browser-file-storage-fakes.ts`(OPFS fake), `recipes/session-owners/oidc-pkce-session-owner.ts`(Web Storage 키 부분), `tests/unit/opfs-worker-runtime.test.ts`·`indexeddb-opfs-journal.test.ts`·`storage-registry.test.ts`, `tests/recipes/browser-file-storage-contracts.test.ts`, `tests/browser-capabilities/opfs-runtime.spec.ts`, `docs/operations/browser-file-storage-recovery.md` §0·§7, `docs/architecture/layers.md` kernel 절, `.dependency-cruiser.json` kernel 규칙
|
||||
> 깊게 본 관점: 1, 11, 12, 17, 22, 28
|
||||
> 이번 렌즈: 1103/05-01~05-04 수정이 주장한 범위를 지키는가, 수정이 검사를 약하게 만들었는가, kernel 경계에 새 예외가 생겼는가
|
||||
> 영역 판정(35.8): **조건부 사용 가능.** kernel과 Web Storage 어댑터는 기본 구성에서 쓸 수 있다. 기본 구성은 Web Storage에 개인 데이터를 두지 않는다. OPFS 런타임은 crash가 남긴 put(1103 X2·X2b·X3)을 이제 계정 삭제가 지운다. **그러나 다른 탭이 새 파일을 쓰는 중에 계정을 삭제하면, partition에 객체가 3개 이상일 때 매번 `COMPLETED`를 보고하고 그 파일이 남는다**(1103/05-01 잔여 ①. 메모리 런타임 20/20, 실제 Chromium 6/6. 객체 0~1개일 때만 지운다). **OPFS에 개인 파일을 두는 제품은 이 잔여를 고친 뒤 조합한다.** 그 전에는 계정 삭제 전에 모든 탭의 그 partition 쓰기를 멈추는 장치를 composition이 직접 만들어야 한다.
|
||||
|
||||
ID 표기: 이번 라운드 새 발견은 `05-NN`. 지난 라운드(2026-11-03)는 `1103/05-NN`, 그 전은 `1101/05-NN`, `0929/05-NN`이다. 배치 요청은 `05-R1`(변이 15개 + 실험 Y1a·Y1b·Y2, vitest), `05-R2`(Y1 브라우저판, Chromium)다(6.3절).
|
||||
|
||||
## 0. 결론
|
||||
|
||||
- **이 영역은 `e40684b..8a44226` 사이 커밋 8개로 바뀌었다.** 수정 7개(`d13a393` 1103/05-01, `7b55f0f` 05-02, `fd6b631` 05-03, `8da33a5`·`36ff633` 05-04, `f6b74ed` 0929/05-09, `3f72ae7` 0929/05-08)와 테스트 1개(`b5c7128` 1101/05-06)다. OPFS 런타임·port·fake는 5파일 +215/−31줄이다. kernel(`src/adapters/platform/`), `browser-file-storage/`, Web Storage 어댑터, IndexedDB 런타임, `storage-keys.ts`는 한 줄도 바뀌지 않았다(`git diff --shortstat` 출력 없음).
|
||||
- **지난 라운드 발견 13건 재판정: 고쳐짐 6, 일부 3, 남음 4.** 1103 4건 중 05-02·05-03·05-04는 고쳐졌다. **05-01은 일부다. README §14.4는 이 항목을 "고침"(그 밖의 81건)으로 적었다. 그 판정은 틀렸다.** 이월 9건 중 1101/05-04·0929/05-08·0929/05-09는 고쳐졌고, 0929/05-01(③ 손상 chunk reference 행)과 1101/05-06(W2·W5·W6)은 일부, 0929/05-05·05-06·05-07·05-10은 남았다.
|
||||
- **수정이 더한 테스트는 규칙을 잡는다.** 변이 15개 중 12개가 죽었다(05-R1). 1103 수정 쪽 10개(M1~M9, M8b)는 모두 죽었다. Web Storage 5개 중 W4·W8은 죽고 W2·W5·W6은 살아남았다(1101/05-06의 남은 공백 그대로).
|
||||
- **1103/05-01 수정은 journal을 세는 그 순간에 살아 있는 put만 잡는다(잔여 ①, Medium·P2 유지, OPFS 개인 파일 제품은 P1).** purge는 객체 목록을 읽고, 하나씩 지우고, 마지막에 journal 행을 센다(`opfs-byte-store-adapter.ts:821`, `:848`, `:899`). 다른 탭의 새 객체 put은 purge의 첫 remove가 origin lease를 기다리는 동안 앞서 끝나고, 지울 객체가 여럿이면 세기 전에 `complete`까지 마친다. 그러면 목록에도 행 수에도 없다. sweep은 그 객체의 chunk를 건너뛰고 `COMPLETED`를 돌려준다. 실험(손대지 않은 코드):
|
||||
- Y1b(메모리 런타임, hook 없음): 객체 1개 10/10 `partitionDeleted`. 객체 3개·8개 **20/20 `COMPLETED` + 그 파일이 `[5]`로 읽힘**, partition 아래 파일 2개.
|
||||
- 05-R2(실제 Chromium, OPFS·Web Locks·DedicatedWorker): 객체 0·1개 6/6 `partitionDeleted` + `NOT_FOUND`. 객체 3·8개 **6/6 `COMPLETED` + `OPENED`**.
|
||||
- 저장소의 X1 테스트는 객체 1개(`opfs-worker-runtime.test.ts:2313`), 브라우저 X1은 0개(`opfs-runtime.spec.ts:332`)로만 돈다. 그래서 수정이 통과했다.
|
||||
- **잔여 ②(드문 손상)도 재현됐다(05-R1 Y2).** FILES_READY에서 멈춘 put의 journal 행이 `logicalKey`를 잃으면 purge가 두 번 모두 `COMPLETED`다. staging receipt·chunk·manifest가 남는다. reconcile은 `corruptTransactions: 1, unattributedCorruptTransactions: 1`, 관측은 `SUCCEEDED`다. 05-03 수정 뒤 이 경우의 신호는 count 하나뿐이다.
|
||||
- **새 발견은 1건이다. Low 1. High 이상과 P1은 없다.** 05-01: OIDC PKCE recipe가 Web Storage 키를 registry 밖에서 글자 그대로 만든다(`oidc-pkce-session-owner.ts:44`). 제품이 `APP_NAMESPACE`를 바꾸면 이 키만 `ca-frontend:`로 남는다.
|
||||
- **kernel 경계는 그대로다.** kernel 예외 밖 adapter 간 import는 0건이다(6.1절 정적 스크립트, kernel 소비 79곳 외 위반 0). kernel 파일은 `contracts`·`application/ports` 타입과 kernel 안 파일만 import한다. 이번에 새로 생긴 kernel 소비는 `opfs-byte-store-adapter.ts:26` → `platform/abortable-operation.ts` 하나이고 허용된 것이다. `.dependency-cruiser.json`의 kernel 규칙은 주석만 바뀌었다(`:254`, `pathNot`은 같다). `check:architecture`·`check:adapter-inventory` rc=0, FE-GATE-010(boundaries 34건 거절 PASS) rc=0(오케스트레이터).
|
||||
- **수정이 검사를 약하게 만든 곳은 없다.** 1103 X1 동작을 기대값으로 고정하던 테스트는 반대 기대값으로 바뀌었다(`opfs-worker-runtime.test.ts:2313-2343`). 0929/05-02 테스트는 타이밍만 바꾸고 `CONFLICT` 단언을 지켰다(`:2428-2479`). recipe의 FILES_READY rollback 테스트는 PREPARING으로 바꾸고, FILES_READY는 runtime과 fake를 함께 돌리는 parity 테스트로 옮겼다(`tests/recipes/browser-file-storage-contracts.test.ts:601`, `:765-960`). 05-03 수정은 소속 없는 손상 행의 `DEGRADED`를 껐다. 이것은 지난 리뷰가 권한 의도된 변경이다. 다만 그 권고의 전제("이런 행은 bytes를 남기지 않는다")가 잔여 ②에서 깨진다. 그래서 따로 세지 않고 1103/05-01 잔여 ②로 센다. 테스트 폭의 문제(X1을 객체 0~1개로만 본다)는 잔여 ①의 한 부분으로 적는다.
|
||||
|
||||
## 1. 범위 (36.1)
|
||||
|
||||
| 항목 | 기록 |
|
||||
|---|---|
|
||||
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` 영역 05 |
|
||||
| 커밋·작업 상태·확인 시점 | `8a44226`, 2026-11-05 19:20~20:40. 노트북 worktree(HEAD = 기준)에서 읽기만 했다. 실행은 desktop(같은 커밋, 깨끗한 checkout)에서 오케스트레이터 배치로만 했다 |
|
||||
| 목적과 지원 실행 구성 | 템플릿(참고 구현). 브라우저 SPA + 정적 호스팅 + Service Worker. 여러 탭 동시 실행. SSR 없음 |
|
||||
| 조합 상태 | 기본 bootstrap이 조립하는 것은 Web Storage 어댑터 두 벌(`runtime-adapters.ts:427`, `boot-release-recovery.ts:57`)과 kernel의 `createBrowserMutationIntentFactory`(`runtime-adapters.ts:31`), lifecycle runtime(`optional-runtime-host.ts:4`)이다. IndexedDB·OPFS·StorageManager 런타임은 `AVAILABLE_NOT_COMPOSED` 레시피다(`config/recipes/frontend-capability-recipes.json:76-112`, 스냅샷 `artifacts/quality/optional-recipes.json`). 다운스트림이 켜는 확장 지점이다 |
|
||||
| 필수 요구와 규모·운영 목표 | 규모·운영 목표는 없다(13·14번 미검증). 데이터 요구: OPFS 정책 예시가 `classification: "PERSONAL"`, `accountDeletionAction: "PURGE_PARTITION"`이다. 그래서 port 주석(`opfs-ports.ts:154-160`)과 runbook(`browser-file-storage-recovery.md:460-462`)이 적은 "LOGOUT·ACCOUNT_DELETION이 `COMPLETED`나 `partitionDeleted`를 보고하면 그 partition의 bytes가 없다(purge가 journal을 센 뒤 시작한 put은 예외)"를 이 영역의 필수 계약으로 본다 |
|
||||
| 읽은 코드·구성 범위 | `e40684b..8a44226`의 영역 diff 전부(커밋 8개). `enforcePolicies` 전체(`opfs-byte-store-adapter.ts:730-987`), `withTransactionLock`·`withPartitionLock`(`:1130-1205`), put 흐름(`:177-360`), reconcile(`:564-728`), orphan sweep(`:1365-1440`). journal의 `listIncomplete`·`countPartitionTransactions`·`removePartition`·`hasPartitionKey`(`indexeddb-opfs-journal.ts:685-1000`). worker의 staging 보호(`opfs-worker-runtime.ts:999-1180`). fake의 put·reconcile·purge(`browser-file-storage-fakes.ts:1649-1945`). kernel 10개 파일의 import. 지난 발견이 가리킨 위치 전부 |
|
||||
| 주장으로만 읽은 것 | 커밋 본문 8개, runbook §0·§7, `docs/architecture/layers.md` kernel 절, `docs/contracts/compatibility.md:31`, `docs/manual/04-paired-backend-session.md:40-50`, 지난 리뷰 문서·README §14.4 |
|
||||
| 수행한 테스트·실험 | 노트북: 정적 읽기와 cross-adapter import 스크립트(6.1절, `grep`·`realpath`만 씀). desktop(오케스트레이터 배치, 둘 다 복원 clean): 05-R1 변이 15개(12 검출, 3 생존) + 실험 Y1a·Y1b(30회)·Y2, 05-R2 Chromium Y1(12회). 게이트 결과는 오케스트레이터 로그와 스냅샷을 인용한다(6.2절) |
|
||||
| 확인하지 못한 범위·이유 | reconcile과 partition 삭제의 겹침, N-1 탭과의 공존, WebKit·Firefox의 Y1, WebKit의 OPFS 런타임 동작은 실행하지 않았다(5절) |
|
||||
| 이전 리뷰와 비교 가능한 범위 | 지난 라운드 발견 13건(1103 4건 + 이월 9건)을 이 커밋의 코드와 이번 실행으로 다시 판정했다(2절). 지난 라운드의 실행 결과(314/314, 변이, X1~X5)는 증거로 쓰지 않았다 |
|
||||
|
||||
## 2. 지난 발견 재확인
|
||||
|
||||
상태: **고쳐짐**(완료 기준을 코드와 실행으로 확인) / **일부**(남은 것을 적음) / **남음** / **재발** / **틀린 발견**. 심각도는 지난 판정이다. 변이 ID는 6.3절 표다.
|
||||
|
||||
| 지난 ID | 내용 | 상태 | 근거 |
|
||||
|---|---|---|---|
|
||||
| 1103/05-01 | 손상 없는 LOGOUT·ACCOUNT_DELETION purge가 같은 partition의 끝나지 않은 put을 보지 않고 "다 지웠다"고 보고한다 (Medium·P2, OPFS 개인 파일 제품 P1) | **일부** · Medium·P2 유지(OPFS 개인 파일 제품 P1). **README §14.4의 "고침"은 틀렸다** | **고쳐진 것**: 객체를 다 돈 뒤 `countPartitionTransactions`로 그 partition 키의 journal 행을 센다(`opfs-byte-store-adapter.ts:897-906`). 하나라도 있으면 sweep을 하지 않고(`:915`) exclusive partition lock 아래 partition을 지운다(`:950-975`). 세는 범위는 `LOGICAL_KEY_INDEX`의 `${scopeKey}\|` 범위로, `removePartition`이 지우는 범위와 같다(`indexeddb-opfs-journal.ts:891-899`, `:934-938`). 읽을 수 없는 행도 센다(`:902-905`, 값을 보지 않음). crash가 남긴 행(X2·X2b·X3, `opfs-worker-runtime.test.ts:2349-2421`)과 세는 순간 살아 있는 put(X1, `:2313`)을 테스트가 고정한다. 변이 M1(6건 실패), M2(2건), M3(1건)이 모두 죽었다. 브라우저 X1(`opfs-runtime.spec.ts:332`)은 FE-GATE-008에서 Chromium·Firefox 통과. **남은 것**: ① 세기 전에 끝난 새 객체 put. 객체 3개 이상이면 늘 일어난다(메모리 20/20, Chromium 6/6, 2.1절). ② `logicalKey`를 잃은 멈춘 put 행(Y2, 2.1절) |
|
||||
| 1103/05-02 | partition lock을 기다리는 put·delete가 자기 abort signal을 무시하고 기다림에 상한이 없다 (Low·P3) | 고쳐짐 | put·remove가 `request.signal`을 `withTransactionLock`에 넘긴다(`opfs-byte-store-adapter.ts:222-226`, `:497-501`). `withPartitionLock`은 kernel `createAbortableOperation`으로 caller signal과 `mutationLockWaitTimeoutMs`를 묶어 lock을 요청한다(`:1175-1186`). caller abort는 `ABORTED`, 시간 초과는 retryable `BLOCKED`다(`:1191-1200`). lock을 얻으면 타이머를 지운다(`:1184-1187`). 테스트 "ends a queued put and a queued delete as soon as their caller aborts"(`opfs-worker-runtime.test.ts:2894`), "ends a partition lock wait at the policy bound as a retryable BLOCKED"(`:2942`). 변이 M4(signal 빼기)·M5(상한 ×1000)가 각각 그 테스트를 실패시켰다. 덧붙임: 같은 상한이 partition 삭제(exclusive)의 기다림에도 걸린다. 10분 넘는 다른 탭 put이 있으면 purge가 `BLOCKED`로 끝나고 호출자가 다시 부른다(커밋 본문, runbook `:504-507`). 전에는 끝없이 기다렸다 |
|
||||
| 1103/05-03 | partition 삭제가 `logicalKey`를 읽을 수 없는 손상 journal 행을 지우지 못해 `DEGRADED`가 영원히 남는다 (Low·P3) | 고쳐짐 (완료 기준 두 개 충족) | ① runbook 문장이 코드와 맞는다: "키(`logicalKey`)를 읽을 수 있는 row뿐"(`browser-file-storage-recovery.md:42-44`), "그 값까지 깨진 row는 남는다"(`:480-481`). ② 운영 출구: journal이 소속 없는 손상 행을 `unattributedRows`로 따로 센다(`indexeddb-opfs-journal.ts:717-726`, `hasPartitionKey` `:980-995`). reconcile report에 `unattributedCorruptTransactions`가 실리고(`opfs-byte-store-adapter.ts:720-726`), `DEGRADED`는 지울 수 있는 손상 행이 있을 때만 낸다(`:716`). runbook에 할 일이 적혔다(`:45-52`). 테스트 `opfs-worker-runtime.test.ts:2616`, `indexeddb-opfs-journal.test.ts:877`. 변이 M6(1건)·M7(3건)이 죽었다. **전제 하나가 틀렸다**: 지난 리뷰는 "파일 bytes는 남지 않는다"(X4)를 전제로 이 행을 경보에서 빼라고 권했다. 그 행이 멈춘 put이고 다른 손상이 없으면 bytes가 남는다(Y2). 이것은 1103/05-01 잔여 ②로 센다 |
|
||||
| 1103/05-04 | recipe fake의 reconcile이 FILES_READY에서 멈춘 put을 되돌리지만 런타임은 commit한다 (Low·P2) | 고쳐짐 | fake가 멈춘 단계를 기억한다. FILES_READY 행은 commit될 객체를 함께 둔다(`browser-file-storage-fakes.ts:1797-1808`). reconcile은 같은 generation 검사로 commit한다(`:1872-1886`). LOGOUT·ACCOUNT_DELETION은 멈춘 행을 지우고 `partitionDeleted`를 보고한다(`:1928-1941`). 완료 기준("같은 시나리오를 fake와 런타임에 돌린 결과가 같다"): parity 테스트가 두 단계 × 계정 삭제 여부 4경우를 메모리 OPFS·IndexedDB 위의 실제 런타임과 fake에 돌려 `toEqual`로 비교한다(`tests/recipes/browser-file-storage-contracts.test.ts:765-960`). FE-GATE-007 PASS. 변이 M8(fake가 FILES_READY를 다시 rollback)·M8b(fake purge가 멈춘 행 무시)가 parity 테스트를 실패시켰다. M1(런타임 쪽 되돌림)에도 parity 2건이 실패했다. 비교하지 않는 칸: `cleanedTransactions`, `removedObjects`. fake는 재검증 실패(digest 불일치)를 흉내 내지 않는다(커밋 본문). 결함으로 세지 않는다. 덧붙임: parity 테스트도 객체 0개 partition만 쓰므로 잔여 ①을 보지 않는다. fake에는 다른 탭이 없어 ①을 흉내 낼 수 없다 |
|
||||
| 1101/05-04 | kernel 폴더의 port 구현 2개가 공유 메커니즘이 아닌데 폴더 예외를 받는다 (Low·P3) | 고쳐짐 (완료 기준의 두 번째 조건) | 1101 완료 기준은 "각 파일이 기준을 만족한다. 또는 기준 밖 파일이 문서에 따로 적혀 있다"다. `layers.md:83-90`이 두 파일을 "Two bootstrap-only platform services … (no adapter imports them)"로 따로 적는다. `.dependency-cruiser.json:254` 주석도 같다. 쓰는 곳은 여전히 bootstrap 둘뿐이다(`runtime-adapters.ts:31`, `optional-runtime-host.ts:4`, `grep`). 남는 위험: 규칙은 adapter가 두 파일을 import하는 것을 막지 않는다(폴더 예외). 커밋 `3f72ae7` 본문은 이 항목을 "남음"이라 적었지만, 그것은 파일을 옮기지 않았다는 뜻이다. 4절 22번에 잔여 위험으로 남긴다 |
|
||||
| 1101/05-06 | Web Storage 어댑터·codec 분기 5개(W2·W4·W5·W6·W8)를 테스트가 잡지 못한다 (Low·P3) | **일부** | W4·W8에 테스트가 생겼고(`b5c7128`) 변이가 죽었다: W4 → "falls back to memory on Firefox's quota error name too"(`storage-registry.test.ts:287`) 실패, W8 → "reads a record expiring at 100 at time 100 as undefined"(`:420-450`) 실패. **W2(TTL 모양 검사, `browser-storage-adapter.ts:123`), W5(`__proto__` 등 키 거절, `browser-storage-codec.ts:204`), W6(accessor 거절, `:206`)는 살아남았다**(3파일 52건 통과). codec을 직접 부르는 테스트가 0개다(`grep browser-storage-codec tests`). 커밋 본문도 "codec을 직접 부르는 테스트는 여전히 없다"고 적는다 |
|
||||
| 0929/05-01 | journal·staging 손상 한 건이 계정 삭제 purge와 reconcile·GC를 멈춘다 (Medium·P2) | **일부** | 1103에서 남은 셋 중 ①(손상 journal 행이 partition 삭제 조건에 없음)은 1103/05-01 수정으로 키가 읽히는 행에 한해 고쳐졌다(M2 검출). ②(키 없는 행)는 지우지 않기로 정하고 따로 센다(1103/05-03). **③은 그대로다**: 손상 chunk reference 행은 `isChunkReferenced`가 `CORRUPT_DATA`로 실패하고(`indexeddb-opfs-journal.ts:855-862`), GC가 그 실패를 그대로 돌려준다(`opfs-byte-store-adapter.ts:1417-1423`). reconcile은 앞에서 처리한 결과를 버리고 실패한다(`:702`). purge 쪽만 partition 삭제로 빠져나간다 |
|
||||
| 0929/05-05 | IndexedDB 전체 삭제 경로가 롤백 중 계정 삭제에 쓰이지 않는다 (Low·P3) | 남음 | 전체 삭제 조건은 `POLICY_REJECTED`·`CORRUPT_DATA`뿐이다(`indexeddb-runtime.ts:2580-2586`). N-1 탭은 `VersionError`를 `INCOMPATIBLE`로 바꾼다(`:663-672`). 파일은 `e40684b` 뒤 바뀌지 않았다 |
|
||||
| 0929/05-06 | 두 런타임이 삭제 승인 계약을 다르게 요구 (Low·P3) | 남음 | proof 정규식 `{16,128}`(`indexeddb-runtime.ts:97`) 대 `{16,512}`(`opfs-byte-store-adapter.ts:1951`) |
|
||||
| 0929/05-07 | canonical JSON 3벌, `sameScope` 2벌 (Low·P3) | 남음 | `opfs-prepared-object.ts:138`, `cache-storage/public-cache-codec.ts:637`, `realtime/event-codec.ts:414`. `sameScope`는 `indexeddb-opfs-journal.ts:1428`, `opfs-worker-runtime.ts:1690`. 덧붙임: 05-03 수정의 `hasPartitionKey`(`indexeddb-opfs-journal.ts:980-995`)가 partition 키 문법(`\|`로 나눈 세 토큰 + 토큰 정규식)을 한 번 더 적는다. 정규식은 `opfs-policy.ts:58`과 같다 |
|
||||
| 0929/05-08 | kernel 범위 설명이 실제보다 좁다 (Low·P3) | 고쳐짐 | `layers.md:83-90`과 `.dependency-cruiser.json:254`가 실제 10개 파일(공유 메커니즘 7종 + bootstrap 전용 2종 + 배럴)을 적고, 편입 기준 위치(`indexeddb-connection.ts:21-26`)를 가리킨다. `ls src/adapters/platform`과 맞다 |
|
||||
| 0929/05-09 | `putIdleTimeoutMs < mutationLockWaitTimeoutMs`가 주석에만 있다 (Low·P3) | 고쳐짐 | `assertOpfsRuntimePolicy`가 `putIdleTimeoutMs >= mutationLockWaitTimeoutMs`를 거절한다(`opfs-policy.ts:111-112`). 테스트 "rejects an idle bound equal to / longer than the lock wait"(`opfs-worker-runtime.test.ts:3041-3059`). 변이 M9(`>=` → `>`)에 "equal to"가 실패했다 |
|
||||
| 0929/05-10 | OPFS journal DB 접두사를 바꿀 수 없다 (Low·P3) | 남음 | `indexeddb-opfs-journal.ts:131` `ca-frontend-opfs-metadata-v1:`, `indexeddb-governance.ts:83` `ca-idb-v1:` 고정 |
|
||||
|
||||
지난 라운드 앞에 이미 고쳐진 8건(1101/05-01·05-02·05-03·05-05·13.6, 0929/05-02·05-03·05-04)은 재발이 없는지만 봤다. pulse 행 `backend: "external"`(`storage-keys.ts:116`), 진단 `reason: cause`(`browser-storage-adapter.ts:382`), lifecycle 테스트 5건(test:unit ✓), 영역 코드의 `파일:줄` 참조 0건(`grep -oE '\.(ts|json|md):[0-9]+'`), 여러 페이지 purge 테스트(`opfs-worker-runtime.test.ts:2277`), recipe contracts의 src port import(`browser-file-storage-contracts.ts:1-14`)가 그대로다. offline-indexeddb 레시피는 이번 측정 **37,714 / 38,500 gzip B**(여유 786 B, FE-GATE-012 `check:optional-recipes`)다. 측정표(`optional-adapter-recipes.md:83`)의 37,327 B보다 +387 B로, 표의 3% 규칙(+1,120 B) 안이다.
|
||||
|
||||
### 2.1 1103/05-01 잔여 (36.3)
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| ID·제목 | 1103/05-01 (잔여) 승인된 LOGOUT·ACCOUNT_DELETION이 journal 행을 한 순간만 세서, 그 전에 끝난 새 객체 put과 키를 잃은 행의 bytes를 남긴 채 `COMPLETED`를 보고한다 |
|
||||
| 성격 | 확인된 결함 (재현 Y1a·Y1b·Y2, 실제 Chromium 05-R2) |
|
||||
| 관련 관점 | 11, 15, 12, 17, 10, 5, 28, 24 |
|
||||
| 근거 | **① 세기 전에 끝난 새 객체 put.** purge 순서는 (a) `listCommittedObjects`로 페이지를 읽고(`opfs-byte-store-adapter.ts:821`) (b) 객체마다 `objects.remove`(`:848`) (c) 마지막에 `countPartitionTransactions`(`:899`) (d) 0이면 sweep(`:913-940`)이다. 다른 탭 put의 journal 행은 `complete`가 지운다(`:335`). 그 앞의 `commitPut`(`:298`)이 객체 행을 만든다. 그래서 put이 (a) 뒤에 commit하고 (c) 앞에 `complete`하면, (a)의 목록에도 (c)의 수에도 없다. sweep은 committed 객체가 참조하는 chunk를 건너뛴다(`isChunkReferenced`, `:1417-1424`). 덮어쓰기라면 (b)의 remove가 `CONFLICT`가 되어 `moreObjectsAvailable: true`가 된다(`:853-861`). 새 객체에는 그런 장치가 없다.<br>**왜 객체 수에 달렸나.** (b)의 remove는 worker의 origin lease를 기다린다. 다른 탭 put은 BEGIN부터 FINISH까지 그 lease를 쥔다(`opfs-policy.ts:26-31`). 그래서 purge의 첫 remove가 put의 FINISH까지 멈추고, 그 뒤 put의 commit·finalize·complete와 purge의 남은 remove가 lease를 번갈아 쓴다. 지울 객체가 1개면 purge가 먼저 센다. 3개 이상이면 put이 먼저 `complete`한다.<br>**재현(손대지 않은 코드)**:<br>• Y1a(메모리, 저장소 0929/05-02 테스트와 같은 hook, `opfs-worker-runtime.test.ts:2440-2447`: 목록 읽기 직후 다른 탭 put을 끝냄) → report `{inspectedObjects:1, removedObjects:1, releasedBytes:3, moreObjectsAvailable:false, deadlineReached:false, chunkSweep:"COMPLETED"}`. 그 뒤 `object_late_0001`이 `{generation:1, bytes:[5]}`로 읽히고 chunk 1·manifest 1이 남는다.<br>• Y1b(메모리, hook 없음, 저장소 X1 테스트와 같은 순서에 객체 수만 바꿈, 각 10회): 객체 1개 → 10/10 `partitionDeleted`, 파일 0. 객체 3개 → 10/10 `chunkSweep:"COMPLETED"`, 파일 `[5]`로 읽힘, 파일 2. 객체 8개 → 10/10 같은 결과.<br>• 05-R2(실제 Chromium, 저장소 브라우저 X1 테스트에 객체 수만 더함, 각 3회): 객체 0·1개 → 6/6 `partitionDeleted` + `NOT_FOUND`. 객체 3·8개 → 6/6 `{removedObjects:3 또는 8, moreObjectsAvailable:false, chunkSweep:"COMPLETED"}` + `OPENED`.<br>**테스트가 놓친 이유.** 저장소의 X1 단위 테스트는 객체 1개(`opfs-worker-runtime.test.ts:2313-2343`), 브라우저 X1은 0개(`opfs-runtime.spec.ts:332`), parity 테스트도 0개다. 1103 완료 기준("X1·X2·X2b·X3 순서에서…")을 그 순서 그대로만 옮겼다.<br>**② `logicalKey`를 잃은 멈춘 put 행.** 세기는 `LOGICAL_KEY_INDEX`로 찾으므로(`indexeddb-opfs-journal.ts:893-899`) 키가 없는 행은 세지 못한다(커밋 `d13a393` 본문). 그 행의 staging receipt가 chunk를 sweep에서 지킨다(`opfs-worker-runtime.ts:1104-1110`, `:1136-1180`). reconcile은 그 행을 손상으로 건너뛰므로 staging도 정리하지 않는다. 05-03 수정 뒤 이 행은 `DEGRADED`도 내지 않는다(`opfs-byte-store-adapter.ts:716`). 재현 Y2(메모리): FILES_READY에서 멈춘 put의 행에서 `logicalKey`만 지움 → 첫 purge `{removedObjects:1, chunkSweep:"COMPLETED"}`, 남은 파일 `staging/transaction_w_1/receipt.json`, chunk 1, `object_dead_0001` manifest 1. reconcile `{inspectedTransactions:0, corruptTransactions:1, unattributedCorruptTransactions:1}`, 관측 `SUCCEEDED`. 두 번째 purge도 `COMPLETED`, 파일 3개 그대로. runbook은 "같은 수로 남아 있으면 할 일이 없다"고 적는다(`browser-file-storage-recovery.md:48-49`).<br>**계약 문장.** port: "For those two reasons the partition's bytes are gone exactly when this is `COMPLETED` or `partitionDeleted` is set; a put that begins after the purge reached its journal check is kept"(`opfs-ports.ts:154-160`). runbook: "이 두 reason에서는 report의 `chunkSweep`이 `COMPLETED`이거나 `partitionDeleted`가 있을 때 그 partition의 bytes가 지워진 것이다"(`:460-462`), "purge가 journal row를 센 뒤에 시작한 put … 의 데이터는 남는다(point-in-time)"(`:507-509`). ①의 put은 purge 시작 전에 시작했다. ②의 행은 purge보다 먼저 있었다 |
|
||||
| 발생 조건 | ① OPFS 런타임을 조합한 제품에서, 승인된 LOGOUT·ACCOUNT_DELETION을 부를 때 같은 사용자의 다른 탭이 **새 파일**을 저장하고 있고, partition에 객체가 3개 이상일 때. 실험에서는 그 조건이면 매번 일어났다. runbook은 "purge 전에 그 partition의 쓰기를 멈추는 것이 composition의 몫"이라고 적는다(`:508-509`). 그러나 다른 탭의 진행 중 put을 멈추거나 기다릴 공개 API는 없다. ② journal 행의 `logicalKey`가 깨지고, 그 행이 멈춘 put(staging 있음)이고, 같은 partition에 다른 손상이 없을 때. 드물다 |
|
||||
| 영향 | 계정 삭제·로그아웃 뒤 그 사용자 파일(①)이나 staging bytes(②)가 기기에 남는다. ①의 파일은 같은 partition으로 열면 읽힌다(Chromium에서 `OPENED`). 호출자는 port 계약대로 "다 지웠다"를 받으므로 다시 부르지 않는다. 공유 기기에서는 이전 사용자 데이터가 origin 저장소에 남는다. ②는 스스로 풀리지 않고 신호도 count 하나뿐이다 |
|
||||
| 심각도·우선순위 | Medium · P2 유지. **OPFS에 개인 파일을 두는 제품은 P1**(출시 전 차단). 피해의 모양은 지난 판정과 같다(개인 데이터 잔존 + 거짓 완료). 지난 라운드 X1과 같은 순서가 보통 크기 partition에서는 고쳐지지 않았다. 지속되는 crash 경우(X2·X2b·X3)는 고쳐졌다. OPFS 런타임은 기본 구성에 없어(`AVAILABLE_NOT_COMPOSED`) 지난 라운드와 같은 등급으로 둔다 |
|
||||
| 통제·증거 | "승인된 계정 삭제가 완료를 보고하면 bytes 0" 규칙: 세는 순간 살아 있거나 crash가 남긴 행은 M3(테스트 4건 + 변이 M1·M2·M3 검출), 세기 전에 끝난 새 객체 put과 키 없는 행은 **M0 확인**(그 경우를 보는 코드가 없음) · E2(Y1a·Y1b·Y2), E3(05-R2 Chromium 6/6) |
|
||||
| 확실성과 남은 가정 | 메모리 런타임(실제 adapter·journal·worker 코드)과 실제 Chromium에서 같은 결과다. Firefox·WebKit에서는 돌리지 않았다. Firefox도 OPFS·Web Locks 순서가 같으므로 같을 것으로 보지만 확인하지 않았다. 객체 2개일 때는 돌리지 않았다 |
|
||||
| 결정의 근거 | [기록] `d13a393`은 리뷰 5.1절 (c)(끝나지 않은 행이 있으면 partition 삭제)를 골랐고 (d)(항상 partition 삭제)를 "예산 단위 진행과 `removedObjects`·`releasedBytes` 보고를 잃는다"며 버렸다. [사실] (c)의 판단은 세는 한 순간의 journal 상태에 기댄다. 그 순간 전에 끝난 put은 journal에서 사라지고, 목록은 그보다 더 앞의 상태다. 지난 리뷰의 (c) 권고도 이 틈을 보지 못했다. [추론] 두 관찰 사이에 끝난 일을 보려면 세기 뒤에 목록을 다시 보거나, 관찰과 삭제를 한 lock 안에 넣어야 한다 |
|
||||
| 이해 비용 | port 주석만 보고는 "세는 순간"이 언제인지 알 수 없다. 호출자가 이 틈을 알려면 adapter의 순서와 origin lease 동작을 읽어야 한다 |
|
||||
| 최소 개선 방향 | (d') 승인된 LOGOUT·ACCOUNT_DELETION은 객체 순회를 하되, sweep 대신 늘 partition 삭제로 끝낸다. exclusive partition lock이 그때 진행 중인 put·delete를 모두 기다린 뒤 디렉터리 전체(staging 포함)와 그 partition 행을 지우므로 ①·② 모두 막는다. 순회는 `removedObjects`·`releasedBytes` 보고를 위해 남길 수 있다 |
|
||||
| 대안 비교 | (a) 세기를 sweep 뒤로 한 번 더 하고, 그때 committed 객체도 한 페이지(limit 1) 다시 본다. 하나라도 있으면 partition 삭제: ①을 막는다. ②는 남는다. journal 읽기가 둘 는다. (b) sweep이 staging receipt 때문에 건너뛴 chunk가 있으면 partition 삭제: ②를 막는다. worker 응답에 칸이 하나 는다. ①은 남는다. (c) (a)+(b): 둘 다 막지만 판단 조건이 일곱 개가 된다(`unfinished`, `corruptObjects`, `damaged`, `moreObjectsAvailable`, `deadlineReached`, 재확인, staging). (d') 늘 partition 삭제: 조건이 줄고 ①·②를 함께 막는다. 잃는 것은 예산 단위 진행이다. partition 삭제는 지금도 예산에 묶이지 않고(`opfs-byte-store-adapter.ts:941-949` 주석), 다른 탭이 쓰는 중이면 이미 이 길로 가야 맞다. [추론] (d')를 권한다. 예산 단위 진행이 꼭 필요하면 (c) |
|
||||
| 단순화의 보존 조건 | 승인 없이 partition을 지우지 않는다(`authorizePolicyMaintenance` 뒤에만). 다른 partition의 행·파일을 건드리지 않는다. 진행 중 put을 지우는 것은 exclusive partition lock 안에서만 한다. TTL·SESSION_END·UNTIL_SYNCED·PRESSURE는 바꾸지 않는다. purge의 abort와 `mutationLockWaitTimeoutMs` 상한(1103/05-02)은 그대로 둔다 |
|
||||
| 비용·부작용 | (d'): 판단 조건이 줄어 코드가 준다. 모든 승인 purge가 다른 탭의 put을 기다린다(지금은 끝나지 않은 행이 있을 때만). recipe fake의 purge도 늘 `partitionDeleted`가 된다. 기존 테스트 기대값 `chunkSweep: "COMPLETED"`(`opfs-worker-runtime.test.ts:2247-2272`, `:2277-2307`, `:2428-2479`)를 바꿔야 한다 |
|
||||
| 재검토 조건 | 한 partition에 서로 다른 LOGOUT 정책의 객체가 섞여야 할 때((d') 불가). partition이 커서 예산 없는 삭제가 화면을 오래 막을 때 |
|
||||
| 완료 기준 | Y1a, Y1b(객체 1·3·8개 각 10회), Y2, 05-R2(Chromium 객체 0·1·3·8개)에서 승인된 ACCOUNT_DELETION이 `COMPLETED`나 `partitionDeleted`를 보고하면, 그 직후 partition 아래 파일이 0개이고 그 객체가 `NOT_FOUND`다 |
|
||||
| 검증 방법 | Y1a·Y1b·Y2(`scratchpad/r4-05/05-exp-block.ts`)를 `tests/unit/opfs-worker-runtime.test.ts`의 05-04 describe로 옮긴다. 05-R2의 브라우저판(`05-browser-block.ts`)을 `opfs-runtime.spec.ts`로 옮긴다. X1 테스트의 객체 수를 3개 이상으로 바꾸는 것만으로도 ①을 잡는다(Y1b) |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 일부 고쳐짐 |
|
||||
| 재검증 결과 | `8a44226`: X2·X2b·X3과 객체 0~1개 X1은 지운다(테스트 + 변이). ①은 메모리 20/20, Chromium 6/6에서 남음. ②는 메모리에서 남음 |
|
||||
|
||||
## 3. 이번 발견 (36.3)
|
||||
|
||||
새 발견 1건: Low 1 · P3 1 · 확인된 결함 1. Critical·High·Medium 0, P0·P1·P2 0. 구조적 위험·미검증·개선 제안은 새로 세지 않았다(미검증은 5절).
|
||||
|
||||
| ID | 심각도 | 우선 | 성격 | 관련 관점 | 제목 |
|
||||
|---|---|---|---|---|---|
|
||||
| 05-01 | Low | P3 | 확인된 결함 | 23, 17, 15, 9, 21 | OIDC PKCE session owner recipe가 Web Storage 키를 registry 밖에서 글자 그대로 만들어, 제품이 `APP_NAMESPACE`를 바꾸면 이 키만 갈라진다 |
|
||||
|
||||
### 05-01 OIDC PKCE session owner recipe가 Web Storage 키를 registry 밖에서 글자 그대로 만들어, 제품이 `APP_NAMESPACE`를 바꾸면 이 키만 갈라진다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함 (계약 문서와 코드 불일치, 정적 확인). 영역 09(세션 owner)와 겹칠 수 있다. 같은 결함이면 하나로 합친다 |
|
||||
| 관련 관점 | 23, 17, 15, 9, 21 |
|
||||
| 근거 | ① recipe가 sessionStorage 키를 상수 문자열로 적는다: `export const OIDC_PKCE_TRANSACTION_KEY = "ca-frontend:auth:v1:oidc-pkce-transaction"`. 주석은 "`buildPhysicalKey("auth", 1, "oidc-pkce-transaction")`; never a token"이다(`recipes/session-owners/oidc-pkce-session-owner.ts:43-44`). 함수를 부르지 않는다. 쓰기·읽기·지우기가 이 상수로 주입된 Storage에 직접 간다(`:183`, `:466`, `:543`, `:563`).<br>② 템플릿의 키 규칙: 물리 키는 `buildPhysicalKey`가 `${APP_NAMESPACE}:${scope}:v${n}:${name}`로 만든다(`src/contracts/storage-keys.ts:1`, `:179-185`). 계약 표는 "Persisted client storage … `defineStorageKey` in `src/contracts/storage-keys.ts`"라고 적는다(`docs/contracts/compatibility.md:31`). 다른 어댑터가 직접 쓰는 키도 registry에 `backend: "external"` 행으로 둔다(pulse 키, `storage-keys.ts:107-123`, 1101/05-01의 수정). 이 키는 registry 7행 어디에도 없다(`grep oidc src/contracts`).<br>③ 제품이 `APP_NAMESPACE`를 바꾸는 것은 예정된 일이다. memento 설계 문서가 `ca-frontend` → `memento`로 바꾼다고 적는다(`docs/superpowers/specs/2026-09-20-memento-frontend-template-bootstrap-design.md:186`). 매뉴얼은 이 recipe를 `src/bootstrap/`로 복사하라고 한다(`docs/manual/04-paired-backend-session.md:48-50`).<br>④ Web Storage 접근을 registry로 모으는 검사는 lint의 `localStorage`·`sessionStorage` 속성 금지다(`eslint.config.ts:82-83`, `:127-128`). recipe는 bootstrap이 넘긴 Storage 객체를 쓰고(`runtime-adapters.ts:300`, `hostValue(host, "sessionStorage")`), 그래서 이 검사에 걸리지 않는다. 키가 registry에 있는지 보는 검사는 없다.<br>⑤ 커밋 `05958bb`(`e40684b` 뒤)에서 생겼다 |
|
||||
| 발생 조건 | 제품이 OIDC PKCE recipe를 복사해 쓰고, `APP_NAMESPACE`를 바꿀 때. 또는 제품이 registry를 보고 로그아웃·계정 삭제 때 지울 Web Storage 키를 정할 때 |
|
||||
| 영향 | 이 키만 `ca-frontend:` 접두사로 남는다. 같은 origin에 템플릿에서 나온 앱이 둘이면 서로의 sign-in transaction을 덮어쓴다(드묾). registry가 "앱이 쓰는 Web Storage 키 목록"이 아니게 된다. registry로 지울 키를 정하는 제품은 버려진 sign-in의 PKCE verifier·`state`·`nonce`·돌아갈 경로를 지우지 못한다. 다만 sessionStorage라 탭을 닫으면 사라지고, callback이 먼저 지우며, 10분 뒤에는 쓰이지 않는다(`oidc-pkce-session-owner.ts:25-27`). 토큰은 두지 않는다 |
|
||||
| 심각도·우선순위 | Low · P3. 기본 구성에는 없고(recipe), 값의 수명이 짧다. 피해는 키 이름이 갈라지는 것과 목록이 불완전한 것이다 |
|
||||
| 통제·증거 | "앱의 Web Storage 키는 registry가 만든다" 규칙: 템플릿 src 안은 M3(lint + registry 테스트), recipe 키는 **M0 확인**(문자열 상수, 검사 없음) · E1 |
|
||||
| 확실성과 남은 가정 | 키 문자열, 계약 문장, memento의 namespace 변경 계획은 파일로 확인했다. memento가 실제로 이 recipe를 쓰는지는 모른다 |
|
||||
| 결정의 근거 | 적용 제외 — 이미 있는 키 규칙(`buildPhysicalKey`, `external` 행)을 recipe에도 적용하는 단순 수정이다 |
|
||||
| 이해 비용 | recipe를 복사하는 사람은 주석의 `buildPhysicalKey(...)`를 보고 키가 registry를 따른다고 읽는다. namespace를 바꿀 때 이 상수도 바꿔야 한다는 것은 어디에도 없다 |
|
||||
| 최소 개선 방향 | recipe가 `buildPhysicalKey("auth", 1, "oidc-pkce-transaction")`를 부르게 한다. 그리고 registry에 `AUTH_REDIRECT_TRANSACTION` 행을 `backend: "external"`로 둔다(pulse 키와 같은 모양, StoragePort는 거절). registry 분류(`public-preference`·`opaque-cache`·`sensitive-forbidden`)에 맞는 것이 없으면 그 행의 분류를 정한다 |
|
||||
| 대안 비교 | 적용 제외 — 기존 규칙을 따르는 수정이다 |
|
||||
| 단순화의 보존 조건 | 적용 제외 |
|
||||
| 비용·부작용 | recipe 한 줄, registry 행 하나, registry 테스트 한 줄. 이미 recipe를 복사한 제품은 키 이름이 바뀌어 진행 중인 sign-in 하나를 잃는다(로그인 다시 시작) |
|
||||
| 재검토 조건 | 적용 제외 |
|
||||
| 완료 기준 | recipe의 키가 `buildPhysicalKey`로 만들어지고 registry에 `external` 행이 있다. `APP_NAMESPACE`를 바꾸면 이 키도 같이 바뀐다 |
|
||||
| 검증 방법 | `tests/recipes/oidc-pkce-session-owner.test.ts`에서 키가 `STORAGE_REGISTRY.<행>.physicalKey`와 같은지 본다 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
| 재검증 결과 | 적용 제외 — 신규 |
|
||||
|
||||
## 4. 28개 관점 판정 (36.2)
|
||||
|
||||
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가
|
||||
|
||||
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|
||||
|---|---|---|---|---|---|
|
||||
| **1** | 코드 성숙도 | 적용 | M3 / M2 | E2(게이트 test:unit 2,883건, 05-R1) | P — purge가 끝나지 않은 행을 본다(1103/05-01 고쳐진 부분). 판단이 세는 한 순간에 기대어 그 전에 끝난 새 객체 put과 키 없는 행을 놓친다(1103/05-01 잔여, Y1b 20/20) |
|
||||
| 2 | 구조적 성숙도 | 적용 | M3 / M3 | E1(6.1절 스크립트), E2(`check:architecture`·`check:adapter-inventory` rc=0, FE-GATE-010 rc=0) | O — kernel 예외 밖 adapter 간 import 0건. kernel 파일은 `contracts`·`application/ports` 타입만 import한다. kernel 규칙 `pathNot` 그대로(`.dependency-cruiser.json:258-263`) |
|
||||
| 3 | 변경 용이성 | 적용 | M2 / M2 | E1, E2(FE-GATE-012) | P — journal port에 필수 메서드가 또 하나 늘었다(`countPartitionTransactions`, `opfs-ports.ts:398-405`). 직접 구현한 쪽은 깨진다(커밋 본문에 [계약]). offline-indexeddb 예산 여유 786 B(37,714 / 38,500) |
|
||||
| 4 | 인지 부하 | 적용 | — | E1 | P — 큰 파일 넷(1,880~2,641줄) 그대로. purge 완료 판단이 플래그 여섯 개(`unfinished` 추가)에 흩어져 있다(`opfs-byte-store-adapter.ts:803-953`) |
|
||||
| 5 | 위험 가시성 | 적용 | M1 / M1 | E2(Y1·Y2), E3(05-R2) | P — port·runbook이 "exactly when … `COMPLETED`"라고 적지만 세기 전에 끝난 put과 키 없는 행은 예외다(1103/05-01 잔여). runbook은 키 없는 행에 "할 일이 없다"고 적는다(`:48-49`). README §14.4가 1103/05-01을 "고침"으로 적었다 |
|
||||
| 6 | 실패 성숙도 | 적용 | M3 / M3 | E2(M4·M5 검출) | P — lock 기다림이 취소되고 상한이 있다(1103/05-02 고쳐짐). 손상 chunk reference 행은 여전히 reconcile을 실패로 끝낸다(0929/05-01 ③) |
|
||||
| 7 | 운영 성숙도 | 적용 | M1 / M1 | E2(Y2) | P — 소속 없는 손상 행이 늘 켜진 경보를 만들지 않는다(1103/05-03 고쳐짐). 그 행이 bytes를 쥔 경우의 신호는 count 하나다(Y2에서 관측 `SUCCEEDED`, 1103/05-01 잔여 ②). 선택형 런타임은 조합이 없어 경보 경로가 없다 |
|
||||
| 8 | 디버깅 가능성 | 적용 | M2 / M1 | E1 | P — purge report에 sweep이 건너뛴 staged·참조 chunk 수가 없다. Y1에서 `COMPLETED` report만으로는 남은 파일 2개를 알 수 없다. `unattributedCorruptTransactions`는 생겼다 |
|
||||
| 9 | 유지보수 성숙도 | 적용 | M2 / M1 | E1 | P — canonical JSON 3벌·`sameScope` 2벌(0929/05-07), `hasPartitionKey`가 키 문법을 한 번 더 적는다, recipe 키 상수(05-01) |
|
||||
| 10 | 테스트 성숙도 | 적용 | M3 / M2 | E2(05-R1 변이 15개 중 12개 검출) | P — 1103 수정 변이 10개는 모두 죽었다. parity 테스트가 fake와 런타임을 같이 돈다. 그러나 X1 테스트가 객체 0~1개로만 돌아, 객체 수만 3개로 바꾸면 실패하는 수정을 통과시켰다(1103/05-01 잔여). Web Storage W2·W5·W6이 살아남았다(1101/05-06) |
|
||||
| **11** | 데이터 성숙도 | 적용 | M3 / M2 | E2, E3(05-R2) | P — **"승인된 계정 삭제가 완료를 보고하면 partition bytes 0" 세부 규칙은 미충족**(1103/05-01 잔여, Chromium 6/6). crash가 남긴 행과 손상 object 행 경로는 충족한다. IndexedDB 롤백 중 계정 삭제는 실패로 끝난다(0929/05-05) |
|
||||
| **12** | 동시성 성숙도 | 적용 | M3 / M2 | E2(Y1b), E3(05-R2 Chromium, FE-GATE-008) | P — 세는 순간 살아 있는 다른 탭 put은 partition 삭제가 기다렸다 지운다. 객체 3개 이상이면 그 put이 세기 전에 끝나 남는다(잔여 ①). lock 기다림 취소·상한(1103/05-02 고쳐짐). reconcile 대 partition 삭제, N-1 탭 공존은 미검증 |
|
||||
| 13 | 확장성 | 적용 | — | E1 | ? — 규모 목표가 없다. partition 삭제는 예산이 없다 |
|
||||
| 14 | 성능 성숙도 | 적용 | — | E2(FE-GATE-012) | ? — 목표가 없다. offline-indexeddb 레시피 37,714 gzip B(지난 라운드 37,423 B, +291 B). put·delete마다 타이머 하나가 는다(`opfs-byte-store-adapter.ts:1175`) |
|
||||
| 15 | 보안 성숙도 | 적용 | M2 / M2 | E2, E3 | P — 기본 구성은 Web Storage에 개인 데이터를 두지 않는다(`storage-keys.ts` 7행). OPFS 계정 삭제 뒤 개인 파일이 남는다(1103/05-01 잔여, Chromium에서 `OPENED`). recipe 키가 registry 밖이다(05-01). 승인 정규식 두 벌(0929/05-06) |
|
||||
| 16 | 의존성 성숙도 | 적용 제외 | — | — | - — 외부 패키지 없이 브라우저 API만 쓴다 |
|
||||
| 17 | API / Contract 성숙도 | 적용 | M2 / M1 | E2, E3 | P — port의 `COMPLETED` 문장이 실제 보장보다 넓다(1103/05-01 잔여). fake와 런타임의 reconcile 의미가 같아졌다(1103/05-04 고쳐짐, M8·M8b 검출). 계약 표의 키 규칙을 recipe가 따르지 않는다(05-01) |
|
||||
| 18 | 배포 성숙도 | 적용 | M2 / M1 | E1 | P — `e5b7b3e`·`d13a393` 이전 release 탭은 partition lock을 쥐지 않고 journal도 세지 않는다. 롤아웃 중 섞이면 막은 경합이 다시 열린다(미검증). IndexedDB N-1 계정 삭제 실패(0929/05-05) |
|
||||
| 19 | 설정 성숙도 | 적용 | M3 / M3 | E2(M9 검출) | P — timeout 관계를 정책 검사가 거절한다(0929/05-09 고쳐짐). partition lock 기다림도 같은 값에 묶였다. 접두사 고정(0929/05-10) |
|
||||
| 20 | 개발자 경험 | 다른 영역 | — | — | > — 영역 14 |
|
||||
| 21 | Guardrail 성숙도 | 적용 | M3 / M2 | E2(FE-GATE-005·007·008·010·012·020 rc=0) | P — 아키텍처·inventory·boundaries(34건 거절)·레시피 예산·제거 드릴 게이트가 돈다. Web Storage 키가 registry에 있는지 보는 검사는 없다(05-01). lifecycle 리스너 규칙은 검사가 없다고 주석이 밝힌다 |
|
||||
| **22** | 추상화 성숙도 | 적용 | M2 / M2 | E1, E2 | P — kernel 문서가 실제 내용과 맞다(0929/05-08, 1101/05-04 고쳐짐). 남은 위험: 폴더 예외라 adapter가 bootstrap 전용 두 파일을 import해도 규칙이 막지 않는다. fake가 런타임과 같은 의미를 갖는다(1103/05-04). 중복 helper(0929/05-07) |
|
||||
| 23 | 일관성 | 적용 | M1 / M1 | E1 | P — 승인 정규식 두 벌(0929/05-06). recipe 키가 namespace 규칙과 따로 논다(05-01) |
|
||||
| 24 | 네이밍 / 의미 성숙도 | 적용 | M1 / M1 | E2, E3 | P — `chunkSweep: "COMPLETED"`는 "세는 순간 끝나지 않은 행이 없었고 참조 없는 chunk를 다 훑었다"다. port 문장은 "partition이 비었다"로 읽힌다. Y1에서 이 값과 함께 파일 2개가 남았다(1103/05-01 잔여) |
|
||||
| 25 | 조직 확장성 | 적용 | — | E0 | ? — 팀이 하나다 |
|
||||
| 26 | Ownership 성숙도 | 적용 | — | E0 | ? — 선택형 런타임 조합이 없어 runbook 담당을 확인할 대상이 없다 |
|
||||
| **27** | 삭제 가능성 | 적용 | M3 / M3 | E2(FE-GATE-020 rc=0) | P — 번들 제거 드릴이 통과한다. 새 parity 테스트가 src OPFS를 import하지만 드릴이 그 파일을 함께 지운다(`scripts/test-browser-file-storage-runtime-removal.ts:47`). 기기 데이터 삭제는 OPFS 정상 경로에 틈이 남았다(1103/05-01 잔여) |
|
||||
| **28** | 회복 가능성 | 적용 | M2 / M2 | E2(Y2) | P — 키가 읽히는 손상 journal 행은 승인된 purge가 partition째 지운다(M2 검출). 키 없는 행은 출구가 정해졌으나 bytes를 쥐면 풀리지 않는다(Y2). 손상 chunk reference는 reconcile을 막는다(0929/05-01 ③) |
|
||||
|
||||
적용 항목 26개(16 제외, 20은 영역 14): 충족 1(2번), 부분 충족 21, 미충족 0, 미검증 4(13, 14, 25, 26). 11번의 "계정 삭제 뒤 bytes 0" 세부 규칙은 미충족이다.
|
||||
|
||||
## 5. 미검증
|
||||
|
||||
| 항목 | 이유 | 확인에 필요한 것 |
|
||||
|---|---|---|
|
||||
| 1103/05-01 잔여 ①의 Firefox·WebKit 재현 | 05-R2는 Chromium만 돌렸다(요청 최소화). WebKit은 기본 정책에서 OPFS 지원 판정이 거절해 spec이 일찍 끝난다 | `05-browser.sh`를 `--project=firefox`로 한 번 |
|
||||
| 객체 2개 partition에서의 ① | 1·3·8개만 돌렸다 | Y1b의 `[1, 3, 8]`에 2를 더함 |
|
||||
| reconcile과 partition 삭제의 겹침 | 코드로만 판단(지난 라운드 5.2절 ①과 같음. 코드 변화 없음) | 삭제 두 단계 사이에 다른 탭 reconcile을 넣는 단위 테스트 |
|
||||
| N-1 탭(partition lock·journal 세기 없음)과의 공존 | 실행하지 않음 | 이전 커밋 adapter와 현재 adapter를 같은 메모리 루트로 묶은 테스트 |
|
||||
| WebKit의 OPFS 런타임 동작 | 기본 정책에서 지원 판정이 거절해 spec이 일찍 끝난다(`opfs-runtime.spec.ts` `installOpfsTab`이 `false`면 `return`) | 정책을 바꾼 WebKit 실행 또는 지원 범위 문서화 |
|
||||
| 0929/05-05·05-06·05-07·05-10 | 파일이 바뀌지 않아 정적 확인만 함 | 지난 라운드 재현을 테스트로 옮김 |
|
||||
|
||||
## 6. 실행 기록
|
||||
|
||||
### 6.1 노트북 정적 확인
|
||||
|
||||
| 명령 | 결과 |
|
||||
|---|---|
|
||||
| cross-adapter import 스크립트(오케스트레이터 scratchpad `xadapter.sh`: `src/adapters` 아래 상대 import를 `grep`으로 모으고 `realpath`로 대상 그룹을 풀어 같은 그룹·kernel 예외를 뺀다) | kernel 소비 79곳(`browser-file-storage/result.ts` 30, `platform/abortable-operation.ts` 23, `indexeddb-transaction` 5, `indexeddb-connection` 4, `system-clock` 5, `retry-after` 5, `json-member-scanner` 3, `bounded-capacity` 3, `cross-context-invalidation/index.ts` 1). **위반 0건** |
|
||||
| `grep` kernel 10파일의 import | `contracts/result.ts`, `contracts/mutation-intent.ts`, `application/ports/*` 타입, kernel 안 파일뿐 |
|
||||
| `git diff --shortstat e40684b..8a44226 -- src/adapters/platform src/adapters/browser-file-storage src/adapters/storage/indexeddb src/adapters/storage/browser-storage-*.ts src/contracts/storage-keys.ts` | 출력 없음(변경 0) |
|
||||
| `git show 8da33a5`의 옮긴 블록과 `tests/helpers/memory-opfs.ts` 비교 | 주석·`export` 빼면 같다(동작 변경 없음) |
|
||||
|
||||
### 6.2 오케스트레이터 게이트(같은 커밋, desktop, 인용)
|
||||
|
||||
| 출처 | 결과 |
|
||||
|---|---|
|
||||
| `gates/summary.txt`(로컬 env) | `check:architecture`·`check:types`·`lint`·`check:adapter-inventory`·`check:ci` rc=0. `test:unit` rc=0(194파일 2,883건. 이 영역 파일: opfs-worker-runtime 84, indexeddb-opfs-journal 18, opfs-byte-store 24, storage-registry 26, browser-storage-policy 8, runtime-adapters 18, browser-lifecycle 5, indexeddb-runtime 31, indexeddb-connection 33, indexeddb-transaction 28, indexeddb-maintenance 22, abortable-operation 22 모두 ✓). `test:component`·`test:integration`·`test:contract`·`test:runtime-schema` rc=0. `verify:documentation` rc=1(짝 백엔드 경로 문제, 이 영역과 무관) |
|
||||
| `merge-48/summary.txt`(CI=true env) | FE-GATE-001~012, 020 rc=0. FE-GATE-013 rc=1(`tests/system/ci-runner/ci-artifact-contract.test.ts`, 이 영역과 무관, 오케스트레이터 몫) |
|
||||
| 스냅샷 `artifacts/quality/gates/FE-GATE-008.txt`, `tests/browser-capabilities/results.xml` | capability 66건 통과. `opfs-runtime.spec.ts`의 05-01 X1·reconcile 2탭 테스트가 Chromium·Firefox에서 통과(WebKit은 지원 판정에서 끝남) |
|
||||
| 스냅샷 `FE-GATE-010.txt` | `Browser file/storage boundaries: PASS (owned adapter allowed, 34 direct or misplaced native access cases rejected)` |
|
||||
| 스냅샷 `FE-GATE-012.txt` | `budgets=file-transfer:56130/57800, offline-indexeddb:37714/38500, realtime:40811/42200, service-worker-pwa:9758/10100 gzip bytes` PASS |
|
||||
|
||||
### 6.3 desktop 실행
|
||||
|
||||
이 영역이 직접 걸었던 run 두 개(`05-batch`, `05-browser`)는 lock 대기 중 19:55에 취소돼 실행되지 않았다(BRIEF-2). 같은 내용을 오케스트레이터 배치로 다시 돌렸다. 스크립트와 변이 표는 desktop `/tmp/claude-gates/r4/mut/05/`와 노트북 `scratchpad/r4-05/`에 같은 내용으로 있다(md5 대조). 결과는 노트북 `scratchpad/r4/results/05/`.
|
||||
|
||||
| 이름 | 명령 | 변이 | rc | 결과 | 시간·부하 | 복원 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| 05-R1 | `bash /tmp/claude-gates/r4/mut/05/05-batch.sh` (local env) | `05-mutate.mjs` M1~M9·M8b·W2~W8을 하나씩 걸고 사본으로 되돌림 + `05-exp-block.ts` | 0 | 변이 15개 중 12 검출. 실험 89/89 통과(원래 84 + 실험 5) | 92초, 부하 1.0~2.5 | clean |
|
||||
| 05-R2 | `bash /tmp/claude-gates/r4/mut/05/05-browser.sh` (local env, Chromium) | 없음(임시 spec 복사본) | 0 | 4건 통과(복사본의 기존 3건 + Y1). `R4OUT` 12줄 | 13초, 부하 1.4 | clean |
|
||||
|
||||
대조 실행은 하지 않았다. 변이 없는 같은 파일이 `8a44226`에서 통과한 기록이 `gates/test_unit.log`와 FE-GATE-007(test:recipes)에 있다.
|
||||
|
||||
**변이 (05-R1).** 돌린 파일: OPFS 4파일 139건(`opfs-worker-runtime`, `indexeddb-opfs-journal`, `opfs-byte-store`, `tests/recipes/browser-file-storage-contracts`), Web Storage 3파일 52건(`storage-registry`, `browser-storage-policy`, `runtime-adapters`).
|
||||
|
||||
| ID | 바꾼 것 | 결과 | 실패한 테스트(요지) |
|
||||
|---|---|---|---|
|
||||
| M1 | 끝나지 않은 행이 partition 삭제를 부르지 않음(`opfs-byte-store-adapter.ts:915`, `:952`) | 검출(6) | X1 "waits for a put…", X2·X2b·X3 3건, parity의 purge 2건 |
|
||||
| M2 | 세기가 읽을 수 있는 행만 셈(`indexeddb-opfs-journal.ts:902-905`) | 검출(2) | "counts the unfinished rows…, a damaged one included", "…whose journal row is damaged" |
|
||||
| M3 | 세는 범위를 authority 전체로(`:897-899`) | 검출(1) | 같은 journal 테스트 |
|
||||
| M4 | put·delete의 partition lock 요청에 signal을 넘기지 않음(`opfs-byte-store-adapter.ts:1148`) | 검출(5) | "ends a queued put and a queued delete as soon as their caller aborts"(215 ms). 나머지 4건은 그 테스트가 lock을 놓지 못해 뒤 테스트가 10초 timeout(변이와 무관한 연쇄) |
|
||||
| M5 | 대기 상한 ×1000(`:1177`) | 검출(4) | "ends a partition lock wait at the policy bound as a retryable BLOCKED"(10초 timeout). 나머지 3건은 같은 연쇄 |
|
||||
| M6 | 소속 없는 행도 `DEGRADED`(`:716`) | 검출(1) | "reports a damaged journal row no partition owns…" |
|
||||
| M7 | 키 없는 행을 소속 있음으로(`indexeddb-opfs-journal.ts:985`) | 검출(3) | journal 2건, adapter 1건 |
|
||||
| M8 | fake가 FILES_READY를 다시 rollback(`browser-file-storage-fakes.ts:1880`) | 검출(1) | parity "FILES_READY (… false)" |
|
||||
| M8b | fake purge가 멈춘 행 무시(`:1930`) | 검출(2) | parity purge 2건 |
|
||||
| M9 | 정책 검사 `>=` → `>`(`opfs-policy.ts:112`) | 검출(1) | "rejects an idle bound equal to the lock wait" |
|
||||
| W2 | TTL 모양 검사 제거(`browser-storage-adapter.ts:123`) | **생존**(52/52) | — |
|
||||
| W4 | Firefox quota 이름 제거(`:324`) | 검출(1) | "falls back to memory on Firefox's quota error name too" |
|
||||
| W5 | `__proto__` 등 키 거절 제거(`browser-storage-codec.ts:204`) | **생존**(52/52) | — |
|
||||
| W6 | accessor 거절 제거(`:206`) | **생존**(52/52) | — |
|
||||
| W8 | 만료 비교 `<=` → `<`(`browser-storage-adapter.ts:138`) | 검출(1) | "reads a record expiring at 100 at time 100 as undefined" |
|
||||
|
||||
**실험 (05-R1, 메모리 OPFS·IndexedDB·Node Web Locks, 실제 adapter·journal·worker 코드).**
|
||||
|
||||
| ID | 시나리오 | 결과 |
|
||||
|---|---|---|
|
||||
| Y1a | 객체 1개. 탭 W가 새 객체 put(source 대기) 중 탭 P가 ACCOUNT_DELETION. P의 목록 읽기 직후 W의 put을 끝냄(저장소 0929/05-02 테스트와 같은 hook) | put `ok`. report `{inspectedObjects:1, removedObjects:1, releasedBytes:3, moreObjectsAvailable:false, deadlineReached:false, chunkSweep:"COMPLETED"}`. `object_late_0001`이 `{generation:1, bytes:[5]}`로 읽힘. 남은 파일: chunk 1, manifest 1 |
|
||||
| Y1b | hook 없음. 객체 N개, W의 새 객체 put이 source 대기 중 P가 ACCOUNT_DELETION, 20 ms 뒤 source 풀기. N마다 10회 | N=1: 10/10 `partitionDeleted`, `NOT_FOUND`, 파일 0. N=3: 10/10 `chunkSweep:"COMPLETED"`, `[5]` 읽힘, 파일 2. N=8: 10/10 같음 |
|
||||
| Y2 | W의 `commitPut` 실패로 FILES_READY 행이 남은 뒤 그 행의 `logicalKey`만 지움. P가 ACCOUNT_DELETION → reconcile → ACCOUNT_DELETION | 두 purge 모두 `chunkSweep:"COMPLETED"`, `partitionDeleted` 없음. 남은 파일 `staging/transaction_w_1/receipt.json`, chunk 1, `object_dead_0001` manifest. reconcile `{inspectedTransactions:0, corruptTransactions:1, unattributedCorruptTransactions:1}`, 관측 `SUCCEEDED:`. 행은 남음 |
|
||||
|
||||
**실험 (05-R2, Chromium, 실제 OPFS·Web Locks·DedicatedWorker).** 저장소 브라우저 X1 테스트(`opfs-runtime.spec.ts:332`)에 객체 수만 더했다. 탭 B(승인)가 객체 N개를 둔 뒤, 탭 A가 새 객체 put(source 대기), 탭 B가 ACCOUNT_DELETION, 250 ms 뒤 source 풀기.
|
||||
|
||||
| N | 회수 | report | 그 객체 |
|
||||
|---|---|---|---|
|
||||
| 0 | 3 | `partitionDeleted: true` | `NOT_FOUND` 3/3 |
|
||||
| 1 | 3 | `removedObjects:1, partitionDeleted: true` | `NOT_FOUND` 3/3 |
|
||||
| 3 | 3 | `removedObjects:3, moreObjectsAvailable:false, chunkSweep:"COMPLETED"` | **`OPENED` 3/3** |
|
||||
| 8 | 3 | `removedObjects:8, moreObjectsAvailable:false, chunkSweep:"COMPLETED"` | **`OPENED` 3/3** |
|
||||
|
||||
## 7. 새 발견 요약
|
||||
|
||||
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|
||||
|---|---|---|---|---|
|
||||
| 05-01 | Low · P3 | 확인된 결함 | OIDC PKCE recipe가 Web Storage 키를 registry 밖에서 글자 그대로 만들어 `APP_NAMESPACE`를 바꾸면 갈라진다 | `recipes/session-owners/oidc-pkce-session-owner.ts:43-44`, `src/contracts/storage-keys.ts:179-185`, `docs/contracts/compatibility.md:31` |
|
||||
|
||||
이월 중 열린 것: **1103/05-01 일부(Medium·P2, OPFS 개인 파일 제품 P1. README §14.4의 "고침"은 틀림, 2.1절)**, 0929/05-01 일부(③), 1101/05-06 일부(W2·W5·W6 생존), 0929/05-05·05-06·05-07·05-10 남음.
|
||||
@@ -0,0 +1,229 @@
|
||||
# 영역 06 — adapters: service worker, push
|
||||
|
||||
> 검토일 2026-11-05 · 기준 `8a44226` (`fix/maturity-review-2026-11-03`) · 가이드 `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`
|
||||
> 깊게 본 관점: 10, 18, 21, 28 (그다음 15, 19)
|
||||
> 렌즈: 지난 라운드 수정이 완료 기준을 채우는가 / 수정이 검사를 약하게 만들지 않았는가 / SW 제어 아래 preload 허용(11-09)이 워커 결함을 가리는가 / Firefox 격리가 아직 필요한가
|
||||
> 영역 판정(35.8): 기본 구성(SW `null`) **지정 범위에서 사용 가능** · SW `ACTIVE` **조건부 사용 가능** · Web Push **조건부 사용 가능** (0절)
|
||||
|
||||
ID 표기: 이번 라운드의 새 발견은 `06-01`부터 쓴다. 라운드 밖에서는 `1105/06-NN`이다. 지난 라운드(2026-11-03)는 `1103/06-NN`, 그 전은 `1101/06-NN`, `0929/06-NN`, `0925/06-NN`이다.
|
||||
|
||||
실행 방식: 이 리뷰가 desktop lock에 넣은 실험 3건은 19:55에 취소됐다(실행 안 됨, checkout 무변경). 대신 오케스트레이터가 배치로 `06-R1`~`06-R11`을 돌렸다(20:05~20:07, 11건 모두 restore clean). 요청은 `scratchpad/r4/requests/06.md`, 패치는 같은 폴더의 `06-Rk.diff`, 로그는 `scratchpad/r4/results/06/06-Rnn.log`다. 판정은 이 커밋의 코드, 오케스트레이터 게이트 결과, 이 배치 결과로 했다.
|
||||
|
||||
## 0. 결론
|
||||
|
||||
| 구성 | 결정 | 조건·이유 |
|
||||
| --- | --- | --- |
|
||||
| 기본(SW `null`, Web Push 미선택) | 지정 범위에서 사용 가능 | 이 영역 런타임이 돌지 않는다. 선택은 제품 소유 파일 `src/features/product-capabilities.ts:34`의 `null`이다 |
|
||||
| SW `ACTIVE` | 조건부 사용 가능 | 지난 라운드와 같은 조건이다. 업데이트 실패 관측·활성화 UI는 제품이 붙인다(`0925/06-05`). 호스팅은 이제 확장자별 MIME을 probe가 본다(`1103/06-03` 고쳐짐). 새 조건: `public/`에 PWA 아이콘을 두는 제품은 06-01을 먼저 고친다. 하위 경로 호스팅 게이트는 13 영역 `0929/13-06`이다 |
|
||||
| Web Push | 조건부 사용 가능 | registry `path`의 dot segment 구멍이 고쳐졌다(`1103/06-02`, 변이 06-R4 검출). 서버의 짧은 TTL·send-time 인가 조건은 그대로다 |
|
||||
|
||||
- **지난 라운드 이 영역 발견 5건은 모두 고쳐졌다.** `1103/06-02`·`06-03`의 테스트는 되돌리는 변이를 잡는다(06-R4 5건, 06-R3 2건 실패). `1103/06-01`·`06-04`는 문서로 완료 기준을 채웠다. `1103/06-05`(= 02-06)는 FE-GATE-020 rc=0이고 realtime 제거 드릴 junit 7 check가 모두 통과다. `1103/06-03`의 live 호출 줄은 테스트가 없다(변이 06-R2 생존). 이것은 새 06-02로 셌다.
|
||||
- **이월 항목**: `0929/06-03`·`0929/06-05`·`0929/06-06`·`1101/06-04`가 고쳐졌다. `1101/06-04`의 변이 4건은 모두 잡힌다(06-R5~R8). 그중 M3은 단언이 아니라 10초 test 시간 초과로 잡힌다. `0929/06-06`은 문서 선택지로 닫혔고 동작은 그대로다. 남음 6건: `0925/06-05`, `0925/06-08`, `0925` P3(route chunk export), `1101/06-03`, `1101/06-05`, `1101` R1~R4.
|
||||
- **새 발견 3건, 모두 Low·P3. High·P1은 없다.**
|
||||
- 06-01: 사전 캐시 수집이 `assets/` 밖 public 파일(`apple-touch-icon.png` 등)을 해시 자산으로 넣는다(06-R1 실행 확인).
|
||||
- 06-02: 확장자별 MIME probe가 redirect 뒤 200을 통과시키고, 워커 없는 빌드에도 돈다. live 호출 줄을 지우는 변이는 44건 통과로 생존한다(06-R1, 06-R2).
|
||||
- 06-03: SW 제어 아래에서 route chunk를 import하는 test가 없다. 제어 아래 preload 검사는 허용 때문에 모두 꺼진다.
|
||||
- **preload 허용(`service-worker-update.spec.ts:45-52`)은 워커 결함을 가리지 않는다. 다만 제어 아래 preload 검사는 사실상 꺼진다.**
|
||||
- 06-R9: 제어 아래 test 6건(엔진 2개 × 3건)에서 preload 26~27개가 모두 `ALLOWED`였다(158줄). 허용 밖 줄은 0이다. 제어 전 첫 load의 preload 26개는 모두 실행 표시가 있어 줄이 없다.
|
||||
- 06-R10: 워커가 직전 캐시로 답하지 않게 바꾸자 두 test가 실패했다. 실패 줄은 허용 밖에 있었다: console 404, `requestfailed`, "Failed to fetch dynamically imported module".
|
||||
- 덧붙여: 그 변이에서 추가 test의 화면 단언은 통과했다. chunk 복구가 페이지를 reload해 B의 화면을 그렸기 때문이다. 화면 단언만으로는 이 결함을 못 잡는다(06-03 최소 개선 방향에 반영).
|
||||
- **Firefox 격리(`expires=2027-03-31`)는 아직 필요하다.** 06-R11에서 skip을 지우자, 격리 대상 3 test가 주석대로 실패했다. 실패는 `requestActivation()` → `NO_WAITING_WORKER` 2건과 `blocked` 대신 `loaded` 1건이다. 나머지 3 test는 통과했다. recovery spec은 strict fixture(`page.route`)를 쓰지 않으므로, 원인은 fixture가 아니라 Playwright Firefox의 워커 제어다. Playwright를 올릴 때 다시 본다(`package.json:170` `1.62.0`).
|
||||
- **약해진 검사**: 이 영역 경로에서 단언 삭제, 정규식 완화, timeout·상한 상향, skip 추가는 찾지 못했다(`git diff e40684b..8a44226`). 넓어진 허용 목록은 위 preload 허용 하나다. 판단은 06-03에 적었다.
|
||||
|
||||
## 1. 범위 (36.1)
|
||||
|
||||
| 항목 | 기록 |
|
||||
| --- | --- |
|
||||
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` (템플릿, reference implementation) |
|
||||
| 커밋·작업 상태·확인 시점 | `8a44226`, laptop worktree(HEAD = 기준, 추적 파일 변경 없음), 2026-11-05 19~20시. `git log e40684b..8a44226 -- <영역 경로>` 19커밋. 이 영역 코드에서 바뀐 곳은 `notification-registry.ts`(1103/06-02), `hosting-probe.ts`·`verify-hosting-headers.ts`(1103/06-03, 13-01, 13-02), `vite.service-worker.config.ts`(`rolldownOptions` 이름), 운영 문서 2개, 테스트·e2e 도우미다. `src/adapters/service-worker/` 7파일은 바뀌지 않았다 |
|
||||
| 목적과 지원 실행 구성 | 브라우저 SPA + 정적 호스팅 + Service Worker. SW 선택 기본값 `null`. 선택은 이제 제품 소유 `src/features/product-capabilities.ts:34`에 있고 템플릿 `installed-runtime-capabilities.ts:37-48`이 투영만 한다(1103/09-05). Web Push는 `NOT_SELECTED`이고 빌드가 `WEB_PUSH` handler를 거절한다(`scripts/lib/service-worker-build-input.ts:61-65`) |
|
||||
| 필수 요구와 규모·운영 목표 | 합의된 SLO·업데이트 전파 목표는 없다. 사전 캐시 상한 256개·5 MiB(`src/contracts/service-worker.ts:13-16`) |
|
||||
| 읽은 코드·구성 범위 | 경로 머리의 파일 전부. 연결: `src/contracts/{service-worker,service-worker-static-manifest,web-push}.ts`, `src/features/{product-capabilities,installed-runtime-capabilities}.ts`, `src/bootstrap/{create-runtime-composition,optional-runtime-host}.ts`, `src/adapters/web-push/inbound/*`, `tests/e2e/service-worker-{update,recovery}.spec.ts`, `tests/e2e/support/service-worker-builds.ts`, `tests/support/browser/{strict-browser-test,preload-use}.ts`, `tests/unit/{service-worker-*,web-push-*,hosting-probe}.test.ts` |
|
||||
| 읽은 문서(주장) | `docs/operations/browser-file-storage-recovery.md` 8절(`:533-647`), `docs/operations/release-cache-rollback.md`(`:41-99`, `:199-239`), `docs/architecture/optional-adapter-recipes.md`(`:112`, `:128-168`), `config/recipes/frontend-capability-recipes.json` `service-worker-pwa`(`:118-151`), `docs/architecture/realtime-events-web-push-and-bounded-polling.md:1594-1599`, 지난 라운드 README §12·§13·§14, 수정 커밋 본문. 모두 주장으로 읽었다 |
|
||||
| 게이트(오케스트레이터, 같은 커밋) | local env(`gates/summary.txt`): `check:architecture`·`check:types`(`check:types:service-worker` 포함, `package.json:29`)·`lint`·`test:unit`·`test:component`·`test:integration`·`test:contract`·`test:runtime-schema`·`check:adapter-inventory`·`check:ci` rc=0. `test:unit`은 194파일 2,883건이고 이 영역 `service-worker-runtime` 64·`web-push-worker-runtime` 26·`hosting-probe` 37·`service-worker-build-output` 7이 통과했다. `verify:documentation` rc=1(두 번 모두)의 실패 줄은 짝 백엔드 경로뿐이고 이 영역 문서는 없다. CI env(`merge-48/summary.txt`): FE-GATE-001~012·020 rc=0, 013 rc=1(이 영역 밖). FE-GATE-008의 첫 명령은 `test:e2e`다(`config/ci/gates.json:252-254`, 기본 config의 모든 spec, 3 엔진). 그래서 SW spec 2개가 CI env에서 통과했다는 뜻이다. FE-GATE-020이 쓴 `artifacts/tests/realtime-runtime-removal.xml`은 tests=7 failures=0이다. FE-GATE-019는 release 단계라 이번 실행에 없다(`config/ci/gates.json:2259-2279`). snapshot의 `hosting-headers.json`은 2026-07-27자라 현재 증거로 쓰지 않았다 |
|
||||
| 수행한 테스트·실험 | 오케스트레이터 배치 11건(6절): 단위 probe 1, 단위 변이 7, e2e 3(추가 test·줄 출력, 워커 변이, Firefox skip 해제) |
|
||||
| 확인하지 못한 범위·이유 | 5절. 실제 CDN·푸시 서비스, live 모드 probe, 하위 경로 브라우저 재확인 |
|
||||
| 이전 리뷰와 비교 가능한 범위 | 지난 라운드 문서(`docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md`)의 발견 5건과 2절 이월 항목 전부를 다시 봤다. 지난 실행 결과(변이 13건, L1~L3)는 현재 증거로 쓰지 않았다 |
|
||||
|
||||
## 2. 지난 발견 재확인
|
||||
|
||||
상태: **고쳐짐** = 완료 기준을 이 커밋에서 확인 · **일부** = 남은 것을 적음 · **남음** = 코드 그대로 · **재발** · **틀린 발견**.
|
||||
|
||||
| 지난 ID | 내용 | 상태 | 근거 (`8a44226`) |
|
||||
| --- | --- | --- | --- |
|
||||
| 1103/06-01 | 운영 문서가 "`verify:hosting-headers`는 워커 헤더를 보지 않는다"고 적음 | **고쳐짐** | 새 문장은 이렇다. 워커를 싣는 빌드에서 live 모드가 `/service-worker.js`를 요청해 `no-cache`를 확인하고, 다르면 FAIL이다. fixture 모드는 `UNVERIFIED`다. 하위 경로는 손으로 확인한다(`browser-file-storage-recovery.md:605-612`). 다른 문서와 같다(`release-cache-rollback.md:72-73`). 코드와도 맞다(`verify-hosting-headers.ts:86-89`, `cache-policy.json:41-47`, `hosting-probe.ts:411-418`). 완료 기준 "두 운영 문서가 같은 검사 범위를 적는다" 충족 |
|
||||
| 1103/06-02 | Web Push registry `path`의 `..`·`%2e%2e`가 base path 밖을 엶 | **고쳐짐** | `safePath`가 정규화한 `pathname + search`가 입력과 같을 때만 받는다(`notification-registry.ts:117-125`). 테스트(`tests/unit/web-push-worker-runtime.test.ts:421-453`)는 06-R4 변이(비교 삭제)에서 5건 모두 실패했다: `/../admin`, `/%2e%2e/admin`, `/%2E%2E/admin`, `/./inbox`, `/inbox/..`. 문서도 규칙을 적는다(`realtime-events-web-push-and-bounded-polling.md:1596-1599`). 완료 기준 충족. 부수 동작(06-R1 실행): `/공지`, `/inbox?q=a b`, `/inbox?filter=it's`, `/inbox?`도 같은 일반 메시지 "registry is invalid"(`:53`)로 거절된다. 문서가 "parser가 바꾸지 않는 경로만"이라고 적으므로 결함으로 세지 않는다. 메시지가 이유를 말하지 않는 점은 8번 관점에 적었다 |
|
||||
| 1103/06-03 | install은 7개 확장자 MIME을 정확히 요구하지만 probe는 JS만 봄 | **고쳐짐** | `probeAssetContentTypes`는 후보 dist의 `assets/`에서 확장자마다 첫 파일을 요청한다. 그리고 워커 표(`CACHEABLE_ASSET_CONTENT_TYPES`)와 비교한다(`hosting-probe.ts:255-315`). live 모드에서 부른다(`verify-hosting-headers.ts:119-120`). 테스트(`hosting-probe.test.ts:329-380`)는 06-R3 변이(`passed: true`)에서 2건 실패했다("fails a host that serves CSS as text/plain", "fails a font served as octet-stream …"). 완료 기준 "live probe가 CSS `text/plain` 호스트를 FAIL" 충족(함수 수준). 남은 관찰은 수정이 만든 새 모양이라 **06-02**로 셌다. live 호출 줄 무검사(06-R2 생존), redirect 통과(06-R1), 워커 없는 빌드다 |
|
||||
| 1103/06-04 | waiting 워커가 바뀔 때마다 밀려난 후보 캐시가 쌓임 | **고쳐짐**(문서 선택지 (a)) | 완료 기준 (a) "문서가 waiting 기간 캐시 수를 적는다" 충족. 문서가 적는 것: 쌓이는 규칙, 예(A·B·C 3개 → C·A 2개), 5 MiB 상한, 쿼터 결과, 줄이는 방법(`requestActivation()` 화면), install이 지우지 않는 이유(`browser-file-storage-recovery.md:620-632`, `release-cache-rollback.md:211-215`). 동작은 그대로다(`service-worker-lifecycle.ts` `onActivate`만 지움). 재검토 조건(사전 캐시 1 MiB 초과 + 잦은 릴리스)은 남는다 |
|
||||
| 1103/06-05 (= 02-06) | `test:realtime-removal`(FE-GATE-020)이 문서 테스트 15건으로 실패 | **고쳐짐** | 오케스트레이터 `merge-48/FE-GATE-020.log`: `FE-GATE-020 removability: PASS (merge-cycle)`, rc=0, 1,156초(CI env). `artifacts/tests/realtime-runtime-removal.xml`은 tests=7 failures=0이다. check는 typecheck·lint·architecture·test·build·optional-catalog·ci-contract다. 원인 수정은 02 영역 몫이다(문서를 읽는 테스트 제외 목록 공유, `scripts/lib/removal-fixture.ts:56-81`) |
|
||||
| 0929/06-03 | 레시피가 오프라인 셸을 SW 설치 조건으로 적지만 계약은 금지 | **고쳐짐** | catalog `trigger`가 "navigation network-only, offline shell 없음"이다(`frontend-capability-recipes.json:140`). `failureKinds`는 `offline-navigation-network-error`다(`:145`). 레시피 표는 "오프라인 셸은 지원하지 않는다"고 적고(`optional-adapter-recipes.md:112`) 졸업 절차를 둔다(`:158-168`). 완료 기준 "catalog·레시피·설계의 주장이 같고 졸업 절차가 있다" 충족. 같은 절의 "사전 캐시는 해시 이름의 `assets/`뿐"(`:160-161`)은 코드와 다르다(**06-01**) |
|
||||
| 0929/06-05 | `service-worker.js` `no-cache`가 호스팅 정책·probe에 없음 | **고쳐짐**(이 영역 몫) | 루트 base 검사는 지난 라운드에 고쳐졌다. 남았던 문서 문장은 1103/06-01로 고쳐졌다. 하위 경로 base를 probe가 거절하는 부분(`hosting-probe.ts:411-418`)은 13 영역 `0929/13-06`에서 센다 |
|
||||
| 0929/06-06 | 제거 2·3단계가 `service-worker.js`를 내보내지 않음 | **고쳐짐**(문서 선택지) | 완료 기준 첫째 "운영 문서에 유지 기간 조건이 있다" 충족. 문서가 적는 것: `REMOVE_REGISTRATION` release는 최대 미방문 기간 이상 유지하고, 남은 사용자가 보이면 다시 배포한다(`browser-file-storage-recovery.md:640-647`, `release-cache-rollback.md:233-239`). 동작은 그대로다. 자기 해제 워커는 `REMOVE_REGISTRATION`에서만 나온다(`scripts/build-frontend.ts`, 변경 없음) |
|
||||
| 0925/06-05 | 업데이트 설치 실패·`observe`·`health()` 미연결 | **남음**(문서화됨) | `watchForUpdates`는 `installed`만 알린다(`service-worker-page-controller.ts:328-349`). composition은 `telemetry`만 넘긴다(`create-runtime-composition.ts:50-54`). `src`에서 `requestActivation`·`onUpdateWaiting`·`onReloadRequired`·`health()`를 읽는 곳은 어댑터·계약·host 밖에 없다(`git grep`). 레시피가 다운스트림 몫으로 적는다(`optional-adapter-recipes.md:134-150`) |
|
||||
| 0925/06-08 | 이전 빌드 fallback이 `assets/`를 하드코딩 | **남음** | `service-worker-static-assets.ts:66`, `cache-policy.json:26` `pathPattern "/assets/*"`. 06-01과 같은 상수 문제로 이어진다(06-01 최소 개선 방향) |
|
||||
| 0925 P3 | route chunk 변경용 export 덧붙이기를 도우미 옵션으로 | **남음** | `service-worker-update.spec.ts:54-71` 그대로 |
|
||||
| 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`)를 읽는 곳이 없다. `retainedPreviousCaches`는 `void`로만 참조된다(`service-worker-lifecycle.ts:169`) |
|
||||
| 1101/06-04 | SW 보호 장치 변이 M1·M3·M9·N8이 살아남음 | **고쳐짐** | 테스트 3건이 생겼다: M1 `service-worker-runtime.test.ts:1084`, M3·M9 `:773`, N8 `:1418`. 배치 결과: M1(06-R5)은 `expected { cache: 'no-store', …(1) } to match object { …(2) }`로 실패했다. M9(06-R7)는 `expected true to be false`, N8(06-R8)은 `vi.fn() … called 1 times`로 실패했다. 모두 단언 실패다. M3(06-R6)은 `Test timed out in 10000ms`(10,001 ms)로 실패했다. 이유: nonce를 다시 받으면 두 번째 요청이 30초 drain(`src/contracts/service-worker.ts:19` `clientDrainMs`)을 기다리는데, test 상한이 10초다(`vitest.config.ts:43`). drain 상한을 10초 아래로 줄이면 drain 시간 초과도 `REJECTED`라서 M3은 다시 생존한다. 지금은 잡히므로 고쳐짐으로 본다 |
|
||||
| 1101/06-05 | 릴리스마다 사전 캐시 전체를 `no-store`로 다시 받음 | **남음** | `service-worker-static-assets.ts:280-285`. 이전 캐시 재사용 없음(`:221-267`) |
|
||||
| 1101 R1~R4 | 리팩터링 후보 | **남음** | R1 `service-worker-lifecycle.ts:169`. R2 `validateActiveFence` 두 벌(`web-push/inbound/push-event-adapter.ts:196`, `notification-click-adapter.ts:356`). R3 `SYNC_WAKE_OBSERVED`가 버전을 숫자로 씀(`service-worker-entry.ts:170`). R4 `bounds a stream that never produces a chunk`(`service-worker-runtime.test.ts:2006`). 파일 64건이 5,221 ms(`gates/test_unit.log`) |
|
||||
|
||||
## 3. 이번 발견 (36.3)
|
||||
|
||||
새 발견 3건. 심각도: Critical 0 · High 0 · Medium 0 · Low 3. 우선순위: P0 0 · P1 0 · P2 0 · P3 3. 성격: 확인된 결함 1 · 구조적 위험 1 · 미검증 0 · 개선 제안 1.
|
||||
|
||||
### 06-01 사전 캐시 수집이 `assets/` 밖 public 파일도 "해시 이름"으로 보고 immutable 자산으로 넣는다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 18, 23, 5, 21 |
|
||||
| 근거 | 해시 판정 정규식은 `/-[A-Za-z0-9_-]{8,}\.[a-z0-9]+$/`이다(`src/contracts/service-worker.ts:116`). 수집기는 dist 전체를 돌고 파일 이름만 이 정규식으로 본다. 디렉터리 제한이 없다(`scripts/generate-service-worker-assets.ts:57-64`). 같은 파일의 주석은 "Vite emits content-hashed names; only those may be treated as immutable"이다(`:44`). Vite가 내용 해시를 붙이는 곳은 `assets/`이고, `public/` 파일은 이름 그대로 dist 루트에 복사된다. **06-R1**(실제 `collectStaticAssets`, 임시 dist): 결과 manifest에 `/android-chrome-192x192.png`, `/apple-touch-icon.png`, `/safari-pinned-tab.svg`가 `assets/` 두 파일과 함께 들어갔다. `favicon.svg`는 빠졌다. 나머지 셋은 `assets/`만 가정한다. 이전 릴리스 fallback(`service-worker-static-assets.ts:66-74`), immutable 호스팅 surface `/assets/*`(`config/hosting/cache-policy.json:25-31`), 새 MIME probe(`scripts/lib/hosting-probe.ts:284-290`)다. 06-R1에서 probe는 같은 dist의 `assets/` 두 파일만 요청했다. 레시피 문서는 "사전 캐시는 해시 이름의 `assets/`뿐"이라고 적는다(`docs/architecture/optional-adapter-recipes.md:160-161`). 템플릿 `public/`에는 `config.json`·`release-manifest.json`뿐이라 지금 빌드에는 영향이 없다 |
|
||||
| 발생 조건 | SW `ACTIVE` 제품이 PWA 아이콘을 `public/`에 둔다(이 레시피 id가 `service-worker-pwa`다). 같은 이름으로 내용을 바꾼다. CDN이 그 파일을 TTL 동안 옛 내용으로 준다(호스팅 정책에 그 파일의 캐시 규칙이 없다) |
|
||||
| 영향 | 새 릴리스 install이 그 파일에서 `INTEGRITY_MISMATCH`로 전체 거절된다(`service-worker-static-assets.ts:333`). 사용자는 CDN TTL이 지날 때까지 옛 워커에 머문다. 첫 방문은 SW 없이 돌고 `service-worker.start.failed`가 남는다. 업데이트 실패는 신호가 없다(`0925/06-05`). 호스팅이 그 파일을 틀린 MIME으로 주면 probe는 보지 않고 install만 실패한다. 데이터 손상은 없다 |
|
||||
| 심각도·우선순위 | Low · P3. 여러 조건이 겹쳐야 하고 결과는 업데이트 지연이다 |
|
||||
| 통제·증거 | "immutable로 다룰 파일은 Vite가 해시한 `assets/` 파일뿐" 규칙: 수집기 M0(디렉터리 제한 없음), fallback·호스팅 M2 · E1 + E2(06-R1) |
|
||||
| 확실성과 남은 가정 | 수집 결과는 실행으로 확인했다. CDN이 옛 내용을 준다는 것은 일반적인 CDN 기본 동작에 기댄 추론이다. 실제 브라우저 install 실패는 돌리지 않았다 |
|
||||
| 결정의 근거 | 적용 제외 — 규칙("해시한 `assets/`만")이 주석·문서·fallback·호스팅 정책에 이미 있고 수집기만 어긋난다 |
|
||||
| 이해 비용 | 제품 개발자는 문서대로 `assets/`만 사전 캐시된다고 믿는다. 루트 파일이 들어가는지는 정규식과 수집 루프를 같이 읽어야 안다 |
|
||||
| 최소 개선 방향 | 수집기가 `assets/` 아래 파일만 받는다. 그 디렉터리 이름을 계약 모듈의 상수 하나로 둔다. fallback(`service-worker-static-assets.ts:66`)·probe(`hosting-probe.ts:285`)·수집기가 그 상수를 같이 쓴다. 그러면 `0925/06-08`(`assetsDir` 하드코딩)을 고칠 때 한 곳만 바꾸면 된다 |
|
||||
| 대안 비교 | (a) 디렉터리 제한: 이름과 무관하게 맞다. (b) 정규식을 Vite 해시 형식(8자 고정)으로 좁힘: 우연히 맞는 이름이 남는다. (c) 문서만 고침: 아이콘 문제는 그대로다. (a)가 가장 작고 맞다 |
|
||||
| 단순화의 보존 조건 | `assets/` 아래 해시 파일은 그대로 사전 캐시한다. `index.html`·`service-worker.js`·설정·manifest 제외 목록(`generate-service-worker-assets.ts:36-42`)을 유지한다 |
|
||||
| 비용·부작용 | 수 줄. 루트에 해시 이름 파일을 일부러 두는 제품은 사전 캐시에서 빠진다(그런 파일은 Vite가 만들지 않는다) |
|
||||
| 재검토 조건 | 제품이 `assetsDir`를 바꾸면 상수를 그 값에서 읽는다 |
|
||||
| 완료 기준 | `collectStaticAssets`가 dist 루트의 `apple-touch-icon.png`를 manifest에 넣지 않고, `assets/` 아래 해시 파일은 넣는다 |
|
||||
| 검증 방법 | 수집기 단위 테스트에 루트 아이콘 사례 1개(06-R1 첫 test와 같은 입력) |
|
||||
| 담당·기한·상태 | 템플릿 소유자 · SW를 켜는 제품 전 · 열림 |
|
||||
| 재검증 결과 | 해당 없음(이번 라운드 발견) |
|
||||
|
||||
### 06-02 확장자별 MIME probe(1103/06-03 수정)가 install 조건 일부만 옮겼고, live 모드의 호출 줄은 테스트가 지키지 않는다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험 |
|
||||
| 관련 관점 | 21, 18, 10 |
|
||||
| 근거 | ① redirect: install fetch는 `redirect: "error"`라서 redirect가 하나라도 있으면 `FETCH_FAILED`다(`service-worker-static-assets.ts:283`, `:296-297`). probe는 `redirect: "follow"`로 받고(`hosting-probe.ts:279`) 최종 status와 MIME만 본다(`:299-311`). 다른 surface는 `final-origin`을 보지만(`:148-154`) 이 함수는 보지 않는다. **06-R1**: `redirected: true`이고 최종 URL이 다른 200 응답을 `hashedAsset.js` `passed: true`로 냈다. ② 워커 없는 빌드: probe는 `workerShipped`와 무관하게 live 모드에서 늘 돈다(`verify-hosting-headers.ts:119-120`). `:86`의 조건은 `serviceWorker` surface에만 쓴다. 주석과 문서는 이유를 워커로만 적는다(`hosting-probe.ts:269-275`, `release-cache-rollback.md:74-79`). 워커가 없으면 글꼴·이미지의 정확한 MIME은 페이지에 필요하지 않다(`nosniff`는 script·style에 적용된다. 일반 지식, 이 저장소에서 확인하지 않음). ③ 호출 줄: live 분기의 `probeAssetContentTypes` 호출(`verify-hosting-headers.ts:120`)을 지키는 테스트가 없다. **06-R2**: 그 호출을 `void probeAssetContentTypes;`로 바꿔도 `hosting-probe`·`service-worker-build-output` 44건이 모두 통과했다(생존). live 모드는 루프백·http를 거절한다(`hosting-probe.ts:381-410`). 그래서 저장소 안 테스트는 이 분기에 들어갈 수 없다 |
|
||||
| 발생 조건 | ① 호스트가 해시 자산을 같은 origin 안에서 redirect한다(정규 경로 규칙, object storage 웹사이트 규칙). ② SW `null` 제품이 글꼴을 `application/octet-stream`으로 주는 호스트를 쓴다(오래된 MIME 표). ③ 누군가 live 분기를 고치다 호출을 빠뜨린다 |
|
||||
| 영향 | ① FE-GATE-019 PASS인데 워커 install이 매번 실패한다. ② 페이지에 피해가 없는 MIME으로 FE-GATE-019가 FAIL한다. 운영자가 원인을 워커 문서에서 찾는다. ③ `1103/06-03`의 검사가 조용히 사라지고 게이트는 계속 PASS다 |
|
||||
| 심각도·우선순위 | Low · P3. ①은 드문 호스팅 구성이다. ②는 막는 쪽(안전한 쪽) 오판이다. ③은 미래 회귀 위험이다 |
|
||||
| 통제·증거 | "probe PASS면 호스팅 때문에 install이 실패하지 않는다" 규칙: MIME은 M3(함수 테스트, 06-R3 검출), redirect는 M0, live 호출은 M2(코드에만 있음, 06-R2 생존) · E1 + E2 |
|
||||
| 확실성과 남은 가정 | ①③은 실행으로 확인했다. ②는 코드로 확정된다 |
|
||||
| 결정의 근거 | 수정 커밋(`0f58abbd`) 본문은 세 가지를 위험으로 적었다: "확장자마다 파일 하나만 본다", "cache-control은 다시 보지 않는다", "live 모드를 실제 호스트로 돌리지 않았다". redirect와 워커 없는 빌드는 적지 않았다. 리뷰어의 추론: install 조건(상태·MIME·redirect·워커 유무)을 probe가 한 함수로 따라가면 셋 모두 닫힌다 |
|
||||
| 이해 비용 | 운영자는 FE-GATE-019 PASS를 "워커 install도 된다"로 읽는다. 실제 범위는 install의 fetch 옵션과 probe의 fetcher를 같이 읽어야 안다 |
|
||||
| 최소 개선 방향 | (1) 자산 probe의 fetcher를 `redirect: "manual"`로 바꾸고 3xx·`opaqueredirect`를 FAIL로 본다. (2) 비JS 확장자는 `shipsServiceWorker`일 때만 요구한다. 의도라면 대신 "워커 없이도 정확한 MIME을 요구한다"고 주석·문서에 적는다. (3) live 분기를 fetcher를 받는 함수로 빼서, 테스트가 호출을 확인한다 |
|
||||
| 대안 비교 | (a) 위 세 가지 (b) 문서에 한계만 적음(①③이 그대로) (c) 현상 유지. (a)의 (1)(3)은 수 줄이고 (2)는 정책 결정이다 |
|
||||
| 단순화의 보존 조건 | 확장자별 MIME 검사와 `.js`의 `application/javascript` 허용(`hosting-probe.ts:261-267`, `hosting-probe.test.ts:374-380`)을 유지한다 |
|
||||
| 비용·부작용 | 수십 줄과 테스트. 호스팅 검사는 13 영역과 같이 고친다 |
|
||||
| 재검토 조건 | probe가 실제 사전 캐시 목록(워커에 들어간 manifest)을 읽게 되면 ②와 06-01의 probe 쪽 공백이 함께 닫힌다 |
|
||||
| 완료 기준 | 같은 origin redirect 뒤 200을 주는 fetcher 대역에서 `hashedAsset.js`가 FAIL이다. 06-R2와 같은 변이가 테스트 1건을 실패시킨다 |
|
||||
| 검증 방법 | `hosting-probe.test.ts`에 redirect 사례 추가, live 분기 함수 테스트, 06-R2 재실행 |
|
||||
| 담당·기한·상태 | 템플릿 소유자(13 영역과 공동) · 미정 · 열림 |
|
||||
| 재검증 결과 | 해당 없음 |
|
||||
|
||||
### 06-03 SW 제어 아래에서 route chunk를 import하는 browser 검사가 없다. 11-09 허용 때문에 그 아래 preload 검사도 모두 꺼진다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 개선 제안 (현재 결함은 없음, 06-R9에서 실제 경로가 동작함을 확인) |
|
||||
| 관련 관점 | 10, 28, 21 |
|
||||
| 근거 | 허용은 `allowedBrowserFailure: /^preloadunverifiable:service-worker:\/assets\/[\w-]+\.js$/u`다(`tests/e2e/service-worker-update.spec.ts:45-52`). fixture는 링크가 붙는 순간 워커가 제어 중이면 그 preload를 `service-worker`로 적는다(`tests/support/browser/preload-use.ts:72-74`, `:94-101`). 실행 표시가 없으면 `preloadunverifiable:service-worker:`로 낸다(`:198-199`). 워커는 해시 `/assets/*.js`를 모두 가로챈다(`service-worker-lifecycle.ts:272-278`, `service-worker-entry.ts:106-107`). 그래서 제어 아래 build script는 표시를 붙이는 route(`preload-use.ts:211`)를 거치지 않는다. WebKit의 3초 추정 경고도 이제 모든 spec에서 무시한다(`strict-browser-test.ts:16-24`). **06-R9**(줄 출력 패치): 제어 아래 test 6건(chromium·webkit 각 3건)에서 preload 26~27개 전부가 `ALLOWED`였다(158줄, 허용 밖 0줄). 제어 아래에서는 검사가 하나도 판정하지 못한다. 제어 전 첫 load(install test 4건)에서는 같은 26개가 모두 실행 표시를 받아 줄이 없다. 한편 spec 자체는 제어 아래에서 route를 import하지 않는다. 옛 탭 회복은 페이지의 `fetch(removedChunk)`로만 본다(`service-worker-update.spec.ts:267-276`) |
|
||||
| 허용이 가리는가(오케스트레이터 질문) | **가리지 않는다. 06-R10이 확인했다.** 워커가 직전 캐시로 답하지 않게 바꿨다(`service-worker-lifecycle.ts:296`을 `return null`로). 기존 test "serves A's removed chunk …"는 `status 404 ≠ 200` 단언과 `console:error:Failed to load resource … 404`로 실패했다. 추가 test는 허용 밖 세 줄로 실패했다: console 404, `requestfailed:GET:/assets/not-found-page-…js:net::ERR_ABORTED`, `console:error:TypeError: Failed to fetch dynamically imported module`. 같은 run의 허용 줄 52개는 실패를 덮지 않았다. 코드로 본 이유: 허용이 숨기는 것은 "제어 아래 preload됐고 실행 표시가 없는 `/assets/*.js`"뿐이다. 무엇을 preload할지는 Vite 빌드가 정하고 워커가 정하지 않는다. `/assets/` 이름은 내용 해시라 워커가 옛 바이트를 줄 수 없다. 06-01의 루트 파일은 허용 패턴 밖이다. 워커가 청크 실행을 깨면 console·`requestfailed`·page error·`start:` 단언으로 드러난다 |
|
||||
| 06-R9가 보인 실제 경로 | B가 제어하는 A 탭에서 client navigation으로 지워진 route를 열었다. 두 엔진 모두 not-found 화면이 그려졌다. `/assets/not-found-page-Dkdu-YsI.js`는 서버 요청 없이 응답됐고(navigation 뒤 서버 요청 `[]`), chromium `responseStatus` 200이다. entry는 A의 `index-DHUP7IEW.js` 그대로였다(reload 없음) |
|
||||
| 06-R10이 보인 함정 | 워커 변이에서 추가 test의 화면 단언은 **통과**했다. 실패는 fixture 줄에서만 나왔다. chunk 복구가 페이지를 reload해 B를 부팅하고 B의 화면을 그렸기 때문이다. navigation 뒤 서버 요청은 `/review06-missing-route`, `/config.json`, `/release-manifest.json`이었다. entry도 B의 `index-HHScv93_.js`로 바뀌었다. 화면 단언만 두는 test는 이 결함을 못 잡는다 |
|
||||
| 발생 조건 | 앞으로 워커의 fallback이나 route 쪽 변경이 `fetch()` 경로는 살리고 "옛 탭이 지워진 route를 연다"는 실제 경로만 깨는 경우. 지금 코드에서는 `classifyFetch`가 요청 종류(destination)를 보지 않는다(`service-worker-static-assets.ts:45-59`). 그래서 두 경로가 같은 분기를 탄다 |
|
||||
| 영향 | 옛 탭 회복(지난 라운드의 확인된 강점)을 spec은 바이트 단위로만 확인한다. 깨지면 사용자는 reload를 겪고 탭의 화면 상태를 잃는다(06-R10에서 본 동작) |
|
||||
| 심각도·우선순위 | Low · P3. 지금 결함은 없고 test 공백이다 |
|
||||
| 통제·증거 | "옛 탭은 새 워커 아래에서 지워진 route를 reload 없이 연다" 규칙: 목표 M3 / 확인 M2(fallback 코드)+`fetch()` 단언 · E3(06-R9, 06-R10, 두 엔진/한 엔진) |
|
||||
| 확실성과 남은 가정 | 실제 경로 동작과 허용의 효과는 실행으로 확인했다. 06-R10은 chromium 한 엔진, 워커 변이 한 종류다 |
|
||||
| 결정의 근거 | 11-09 조치는 제어 아래 script에 표시를 포기했다. 표시를 붙이면 워커가 sha256으로 검사하는 바이트가 바뀌기 때문이다(`preload-use.ts:25-28`). 그 선택은 맞다. 리뷰어의 추론: 표시 대신 "reload 없이 route가 그려진다"를 단언하면 같은 목적을 이룬다 |
|
||||
| 이해 비용 | spec을 읽는 사람은 `fetch()` 단언을 "옛 탭이 route를 연다"로 읽기 쉽다. 실제로는 바이트만 본다 |
|
||||
| 최소 개선 방향 | update spec에 test 1건을 더한다. B가 제어하는 A 탭에서 client navigation으로 지워진 route를 연다. 단언은 세 가지다: 화면이 그려진다, entry script가 A의 것 그대로다(reload 없음), 허용 밖 실패 줄이 없다(strict fixture). 06-R9의 추가 test에 entry 단언 한 줄을 더해 옮기면 된다 |
|
||||
| 대안 비교 | (a) 위 test 추가 (b) fixture가 워커 쪽 응답을 추적(Playwright의 워커 network 이벤트는 Chromium 전용) (c) 현상 유지. (a)가 엔진에 무관하고 작다 |
|
||||
| 단순화의 보존 조건 | 허용 패턴은 `/assets/*.js`와 `service-worker` 종류만 받는다. 제어 전 preload 검사는 유지한다 |
|
||||
| 비용·부작용 | test 1건, 엔진마다 약 7초(06-R9: 6.5~6.8초) |
|
||||
| 재검토 조건 | fixture가 워커 제어 아래 실행을 볼 수 있게 되면(예: 엔진 공통 워커 network 이벤트) 허용을 지운다 |
|
||||
| 완료 기준 | update spec이 제어 아래 route import를 reload 없이 단언한다. 06-R10과 같은 워커 변이에서 그 test가 실패한다 |
|
||||
| 검증 방법 | 06-R9·06-R10과 같은 실행 |
|
||||
| 담당·기한·상태 | 템플릿 소유자(11 영역 fixture와 공동) · 미정 · 열림 |
|
||||
| 재검증 결과 | 해당 없음 |
|
||||
|
||||
**Firefox 격리 판단(발견 아님).** 격리는 3곳이다(`service-worker-update.spec.ts:181`, `:223`, `:244`, `service-worker-recovery.spec.ts:84-88`). 근거는 "Playwright Firefox는 워커가 페이지를 제어하지 못한다"다. **06-R11**은 세 skip을 지우고 firefox로 두 spec을 돌렸다. 3건 통과, 3건 실패다. 실패는 모두 제어가 없을 때의 모양이다. "announces …"와 "serves A's removed chunk …"는 `requestActivation()`이 `NO_WAITING_WORKER`였다. B가 waiting 없이 스스로 활성화됐다는 뜻이고, 주석(`:174-180`)이 적은 그대로다. recovery는 `blocked` 대신 `loaded`였다. 망가진 워커 A가 페이지를 제어하지 않았다는 뜻이다. recovery spec은 strict fixture의 `page.route`를 쓰지 않으므로(`service-worker-recovery.spec.ts:91-94`), 원인은 fixture가 아니다. 격리는 아직 필요하다. install 2 test는 Firefox에서도 돈다. 만료일(2027-03-31)은 Playwright 버전(`package.json:170` `1.62.0`)을 올릴 때 다시 볼 날짜로 적당하다.
|
||||
|
||||
## 4. 28개 관점 판정 (36.2)
|
||||
|
||||
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 통제는 "목표 / 확인"이다.
|
||||
|
||||
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 1 | 코드 성숙도 | 적용 | M2 / M2 | E1·E2 | P. registry 경로 정규화 구멍이 고쳐졌다(1103/06-02). 사전 캐시 수집이 루트 파일을 해시로 오인한다(06-01) |
|
||||
| 2 | 구조적 성숙도 | 적용 | M3 / M3 | E1·E2 | O. worker·page realm을 tsconfig로 나눈다. `check:types:service-worker`가 통과한다(오케스트레이터 `check:types` 0). 엔트리는 web-push를 import하지 않는다(`service-worker-entry.ts:144-158`) |
|
||||
| 3 | 변경 용이성 | 적용 | M1 / M1 | E1 | P. SW 켜기는 제품 소유 파일 한 줄이 됐다(`product-capabilities.ts:34`). 활성화 UI·observe 연결은 템플릿 composition을 고쳐야 한다(0925/06-05) |
|
||||
| 4 | 인지 부하 | 적용 | - | E1 | P. 쓰지 않는 kind·상수가 남았다(1101/06-03). lifecycle 736줄, page controller 642줄, subscription adapter 1,203줄 |
|
||||
| 5 | 위험 가시성 | 적용 | M1 / M1 | E1 | P. 운영 문서가 검사 범위·waiting 캐시 누적·제거 유지 기간을 맞게 적는다(1103/06-01, 06-04, 0929/06-06). 레시피 문서의 "사전 캐시는 `assets/`뿐"이 코드와 다르다(06-01) |
|
||||
| 6 | 실패 성숙도 | 적용 | M2 / M2 | E1·E2 | P. install 거절 11종을 구분한다. 거절 이유는 페이지에 오지 않는다 |
|
||||
| 7 | 운영 성숙도 | 적용 | M2 / M1~M2 | E1 | P. 시작 실패만 `service-worker.start.failed`로 남는다. 업데이트 실패·`health()` 미연결(0925/06-05). probe PASS가 install 성공을 다 뜻하지는 않는다(06-02 ①) |
|
||||
| 8 | 디버깅 가능성 | 적용 | M2 / M1 | E1·E2 | P. `observe` hook과 reason 코드가 조립되지 않는다. registry 거절 메시지가 어느 정의·이유인지 말하지 않는다(`notification-registry.ts:53`, 06-R1) |
|
||||
| 9 | 유지보수 성숙도 | 적용 | M1 / M1 | E1 | P. 읽히지 않는 상수·kind(1101/06-03), `validateActiveFence` 두 벌(R2). 폐기 예정 옵션 `inlineDynamicImports`가 남았다(`vite.service-worker.config.ts:83`) |
|
||||
| 10 | 테스트 성숙도 **(깊게)** | 적용 | M3 / M3(일부) | E2·E3 | P. 영역 단위 테스트(test:unit)와 SW e2e(FE-GATE-008 `test:e2e`, CI env)가 이 커밋에서 통과한다. 지난 수정의 변이 7건 중 6건을 단언이 잡고 1건(M3)은 시간 초과로 잡는다(06-R3~R8). live 호출 줄 변이는 생존한다(06-R2, 06-02). 제어 아래 route import test가 없다(06-03) |
|
||||
| 11 | 데이터 성숙도 | 적용 | M2 / M2 | E1·E2 | O. 캐시는 `credentials: "omit"`으로 받은 해시 공개 자산만 담는다. 이를 테스트가 단언한다(`service-worker-runtime.test.ts:1084`, 06-R5 검출). 소유 캐시 이름은 exact 비교다. push fence에 계정 ID·endpoint가 없다 |
|
||||
| 12 | 동시성 성숙도 | 적용 | M3 / M3 | E2 | O. nonce 재사용과 요청받지 않은 drain 응답을 테스트가 잡는다(06-R6, 06-R7). 잔여: M3 검출이 drain 상한(30초) > test 상한(10초)에 기댄다 |
|
||||
| 13 | 확장성 | 적용 | M2 / M2 | E1 | P. 256개·5 MiB 상한을 빌드가 막는다. waiting 기간 캐시 누적은 문서화만 했다(1103/06-04) |
|
||||
| 14 | 성능 성숙도 | 적용 | M2 / M2 | E1 | P. 릴리스마다 사전 캐시 전체를 다시 받는다(1101/06-05) |
|
||||
| 15 | 보안 성숙도 | 적용 | M3 / M3 | E2 | O. registry 경로가 앱 루트를 벗어나지 않고 되돌리면 테스트가 잡는다(06-R4). install fetch의 `credentials`·`redirect` 설정도 같다(06-R5). payload는 route intent만 고르고 클릭 URL은 same-origin이다 |
|
||||
| 16 | 의존성 성숙도 | 적용 | - | E1 | P. 런타임 외부 패키지 없음. `rollupOptions`는 `rolldownOptions`로 바뀌었다. 안의 `inlineDynamicImports`는 폐기 예정 옵션 그대로다(`vite.service-worker.config.ts:79-85`) |
|
||||
| 17 | API / Contract 성숙도 | 적용 | M2 / M2 | E1·E2 | P. registry `path` 계약을 이제 검사가 지킨다. 처리하지 않는 kind 3개를 받는다(1101/06-03). catalog의 오프라인 셸 약속이 없어졌다(0929/06-03) |
|
||||
| 18 | 배포 성숙도 **(깊게)** | 적용 | M3 / M2~M3 | E1·E2·E3 | P. probe가 확장자별 MIME을 본다(1103/06-03). 옛 탭이 새 워커 아래에서 지워진 route를 연다(06-R9). 남은 것: 루트 파일 오인(06-01), redirect·워커 없는 빌드(06-02), 하위 경로 호스팅 게이트(13 영역 0929/13-06), `assets/` 하드코딩(0925/06-08). FE-GATE-019(release 단계)는 이번에 돌지 않았다 |
|
||||
| 19 | 설정 성숙도 | 적용 | M3 / M3 | E1·E2 | P. 선택이 제품 소유 파일로 옮겨졌다. 빌드·호스팅 검사·e2e 도우미가 같은 투영을 읽는다(`installed-runtime-capabilities.ts:37-48`, `tests/e2e/support/service-worker-builds.ts:76`). 자산 디렉터리는 설정이 아니라 상수다(0925/06-08) |
|
||||
| 20 | 개발자 경험 | 적용 | M1 / M1 | E1 | P. SW 켜기 체크리스트가 새 파일 위치를 적는다(`optional-adapter-recipes.md:128-153`). 활성화 UI·observe는 composition을 직접 고친다 |
|
||||
| 21 | Guardrail 성숙도 **(깊게)** | 적용 | M3 / M3(일부) | E2·E3 | P. FE-GATE-020이 통과하고 realtime 제거 드릴 7 check가 모두 통과한다(오케스트레이터). 새 MIME probe가 있다. live 호출 줄 무검사·redirect 미검사(06-02). preload 허용은 워커 결함을 가리지 않는다(06-R10). 대신 제어 아래 preload 검사는 전부 꺼진다(06-R9, 06-03) |
|
||||
| 22 | 추상화 성숙도 | 적용 | M2 / M2 | E1·E3 | O. 구조적 facade로 워커 없이 테스트한다. 실제 브라우저 결과(06-R9·R10·R11)와 단위 테스트 가정이 어긋난 곳을 찾지 못했다 |
|
||||
| 23 | 일관성 | 적용 | - | E1·E2 | P. "사전 캐시 = `assets/`" 규칙이 fallback·호스팅·probe·문서 네 곳에 있고 수집기만 다르다(06-01). `SYNC_WAKE_OBSERVED`만 버전을 숫자로 쓴다(R3) |
|
||||
| 24 | 네이밍 / 의미 | 적용 | - | E1 | P. `retainedPreviousCaches`는 읽히지 않는다(R1). `HASHED_STATIC_ASSET_NAME`은 내용 해시를 뜻하는 이름인데 `apple-touch-icon.png`에 맞는다(06-01과 같은 결함, 따로 세지 않음) |
|
||||
| 25 | 조직 확장성 | 적용 제외 | - | - | -. 1인 관리 전제(0.1) |
|
||||
| 26 | Ownership 성숙도 | 적용 | M1 / M1 | E1 | P. 운영 문서가 코드 경로·검사 범위·유지 기간을 맞게 적는다. 레시피 문서 한 문장이 틀렸다(06-01) |
|
||||
| 27 | 삭제 가능성 | 적용 | M3 / M3 | E3 | O. web-push·realtime을 지운 fixture에서 7 check가 모두 통과한다: typecheck·lint·architecture·test·build·optional-catalog·ci-contract(`realtime-runtime-removal.xml` 7/7, 오케스트레이터 FE-GATE-020, CI env). 지난 라운드 P(드릴 깨짐)에서 올라왔다 |
|
||||
| 28 | 회복 가능성 **(깊게)** | 적용 | M3 / M2~M3 | E2·E3 | P. kill switch와 자기 해제 워커가 있다. 제거 단계 유지 기간이 문서에 있다(0929/06-06). 옛 탭은 새 워커 아래에서 지워진 route를 reload 없이 연다(06-R9). 그러나 이를 지키는 spec이 없다(06-03). `null` 릴리스 뒤 옛 워커를 걷어내는 장치는 여전히 없고 문서로 운영한다 |
|
||||
|
||||
집계: 적용 27개 중 O 6(2, 11, 12, 15, 22, 27) · P 21 · X 0 · ? 0, 적용 제외 1. 지난 라운드 대비 12·15·27번이 P에서 O로 올라왔다.
|
||||
|
||||
## 5. 미검증
|
||||
|
||||
| 항목 | 이유 | 확인하려면 |
|
||||
| --- | --- | --- |
|
||||
| 06-01 루트 아이콘의 실제 install 실패(CDN이 옛 내용을 줄 때) | 수집 결과만 실행으로 확인했다 | e2e 도우미 서버가 루트 아이콘을 다른 바이트로 주게 하고 첫 install 결과 확인 |
|
||||
| live 모드 probe 전체(FE-GATE-019) | release 단계 게이트라 이번 실행에 없다. live 모드는 저장소 안에서 돌 수 없다. snapshot의 `hosting-headers.json`은 2026-07-27자다 | staging 호스트로 `HOSTING_BASE_URL` live probe |
|
||||
| SW spec의 test별 CI env 결과 | FE-GATE-008 로그는 PASS 한 줄뿐이다. 06-R9는 local env다 | FE-GATE-008의 Playwright junit을 따로 보관 |
|
||||
| 06-R10의 webkit 결과, 다른 워커 결함 종류 | 배치는 chromium 한 엔진, 변이 한 종류다 | 같은 변이를 webkit으로, MIME이 틀린 캐시 응답 변이 |
|
||||
| Web Push end-to-end(실제 푸시 서비스, VAPID) | 푸시 서버 없음. `WEB_PUSH`는 빌드에서 거절된다 | 로컬 web-push 서버와 제품 조립 브랜치 |
|
||||
| 하위 경로(`/app/`) 브라우저 설치 재확인 | 지난 라운드 L1 이후 이 영역 SW 코드는 바뀌지 않았다. 이번에 다시 돌리지 않았다 | 지난 L1과 같은 실험 |
|
||||
| 얼어 있는 탭이 Web Lock을 쥔 경우, A 워커 아래 B 부팅 지연 | 재현 환경 없음 | `Page.setWebLifecycleState(frozen)`, resource timing 비교 |
|
||||
|
||||
## 6. 실행 기록
|
||||
|
||||
이 리뷰가 desktop lock에 넣은 `06-unit`, `06-e2e-sw`, `06-firefox-sw`는 19:55에 취소됐다. 실행되지 않았고 checkout을 건드리지 않았다(BRIEF-2).
|
||||
|
||||
인용한 오케스트레이터 게이트(같은 커밋 `8a44226`): 1절 게이트 행.
|
||||
|
||||
오케스트레이터 배치(2026-11-05 20:05~20:07, 부하 1.14~1.49, 항목마다 `8a44226`로 reset 후 실행, 11건 모두 restore clean). 요청 `scratchpad/r4/requests/06.md`, 패치 `06-R1.diff`~`06-R11.diff`(모두 `git apply --check` 통과), 로그 `scratchpad/r4/results/06/06-Rnn.log`. 변이를 넣은 실행의 무변이 대조는 게이트가 대신한다. 단위는 `gates/test_unit.log`, e2e는 `merge-48/FE-GATE-008.log`다.
|
||||
|
||||
| ID | 명령 | 변이 | rc · 시간 | 결과 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 06-R1 | `node scripts/run-vitest.ts run tests/unit/review06-r4-probe.test.ts` | 임시 test 파일 추가 | 0 · 0초 | 7건 통과. 루트 아이콘 3개 사전 캐시, probe는 `assets/` 2개만 요청, redirect 응답 `passed: true`, registry `/inbox`만 수락 |
|
||||
| 06-R2 | `hosting-probe`·`service-worker-build-output` 단위 | live 호출 줄을 `void`로 | 0 · 4초 | 44건 통과 → **생존**(06-02) |
|
||||
| 06-R3 | `hosting-probe` 단위 | `passed: true` | 1 · 1초 | 기대대로 2건 실패(CSS `text/plain`, 글꼴·404) |
|
||||
| 06-R4 | `web-push-worker-runtime` 단위 | 정규화 비교 삭제 | 1 · 1초 | 기대대로 5건 실패(dot segment 5경로) |
|
||||
| 06-R5 | `service-worker-runtime` 단위 | M1 | 1 · 6초 | 기대대로 1건 실패(fetch init 단언) |
|
||||
| 06-R6 | 같음 | M3 | 1 · 16초 | 기대대로 1건 실패, `Test timed out in 10000ms` |
|
||||
| 06-R7 | 같음 | M9 | 1 · 6초 | 기대대로 1건 실패(`expected true to be false`) |
|
||||
| 06-R8 | 같음 | N8 | 1 · 6초 | 기대대로 1건 실패(`onUpdateWaiting` 1회 호출) |
|
||||
| 06-R9 | `playwright test -c playwright.review06.config.ts --project=chromium --project=webkit tests/e2e/service-worker-update.spec.ts` | 임시 config, 옛 탭 test 추가, fixture 줄 출력 | 0 · 54초 | 12건 통과(52.7초). `ALLOWED` 158줄, `FAIL` 0줄. 옛 탭 test는 두 엔진 모두 reload 없이 not-found 화면 |
|
||||
| 06-R10 | 같은 config, chromium, `--grep "removed chunk\|removed route chunk"` | R9 + 직전 캐시 응답 끊기(S1) | 1 · 24초 | 기대대로 2건 실패. 허용 밖 줄(console 404, `requestfailed`, dynamic import 실패)과 `status 404` 단언. 추가 test의 화면 단언은 reload 복구로 통과 |
|
||||
| 06-R11 | 같은 config, firefox, update·recovery spec | Firefox skip 3개 제거 | 1 · 30초 | 3건 통과(install 2, build 1), 3건 실패(`NO_WAITING_WORKER` 2, `loaded` 1) → 격리 유지 |
|
||||
|
||||
## 7. 새 발견 요약
|
||||
|
||||
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 06-01 | Low · P3 | 확인된 결함 | 사전 캐시 수집이 `assets/` 밖 public 파일(`apple-touch-icon.png` 등)도 해시 자산으로 넣는다 | `scripts/generate-service-worker-assets.ts:57-64`, `src/contracts/service-worker.ts:116` |
|
||||
| 06-02 | Low · P3 | 구조적 위험 | 확장자별 MIME probe가 redirect 뒤 200을 통과시키고, 워커 없는 빌드에도 돈다. live 호출 줄을 지워도 테스트가 통과한다 | `scripts/lib/hosting-probe.ts:276-315`, `scripts/verify-hosting-headers.ts:119-120` |
|
||||
| 06-03 | Low · P3 | 개선 제안 | SW 제어 아래 route import를 지키는 test가 없다. 11-09 허용으로 그 아래 preload 검사도 모두 꺼진다(허용이 워커 결함을 가리지는 않음) | `tests/e2e/service-worker-update.spec.ts:45-52`, `:267-276` |
|
||||
@@ -0,0 +1,213 @@
|
||||
# 영역 07 — contracts (공유 어휘·외부 계약)
|
||||
|
||||
> 검토일 2026-11-05 · 기준 `8a44226` (`fix/maturity-review-2026-11-03`) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
|
||||
> 경로: `src/contracts/`(44파일, 9,183줄), `schemas/`, `config/contracts/`(6파일. 새 파일 `backend-contract-pin.json`, `backend-idempotency-answers.json`)
|
||||
> 깊게 본 관점: 17, 21, 10, 15, 19
|
||||
> 렌즈: 1103/07-01(FE-REG-API가 wire 칸을 보는가), 07-02(CSRF·realtime snapshot 변이), 07-03, 07-04 남은 부분, 결정 D6(pin과 답 표가 백엔드 변경을 잡는가)
|
||||
> 영역 판정(35.8): **조건부 사용 가능.** 외부 계약 조립기, FE-REG-API 투영, 쿠키 쓰기 CSRF 조립 검사, FE-REG-ENV 대조, 스키마 정책 대조는 그대로 써도 된다. 조건은 둘이다. (1) 짝 백엔드 checkout을 frontend 옆에 두고, 백엔드를 받을 때마다 `check:backend-contract-drift`를 돌린다. 게이트는 백엔드 변경을 보지 못한다(07-01). (2) 응답 스키마를 `.strict()`로 바꾸는 PR은 사람이 본다. 레지스트리가 behavior-change로만 적는다(07-02).
|
||||
|
||||
ID 표기: 이 문서의 `07-NN`은 2026-11-05 라운드 ID다. 지난 라운드(2026-11-03)는 `1103/07-NN`, 그 전은 `1101/07-NN`, 2026-09-29 라운드는 `P-07-NN`(= `0929/07-NN`)이다.
|
||||
|
||||
## 0. 결론
|
||||
|
||||
- **지난 라운드 영역 07 발견 10건 중 9건이 고쳐졌다.** 1103/07-01·02·03·05, 1101/07-05·07, P-07-05·06·07이다. 07-02에 합친 10-03·04-03도 같이 닫혔다. 남은 것은 1103/07-04의 한 부분(부팅 오류에 키 이름이 없다)뿐이다. Low다.
|
||||
- **1103/07-01이 닫혔다.** FE-REG-API 행이 status 목록·상한·마감·재시도 예산·traffic·command 칸·검증 생략을 담는다(`src/contracts/api-operations.ts:52-61, 88-112`). 지난 라운드 X2(생성 API `[200, 201]`→`[201]`)가 이제 `acceptedStatuses:allowed-value-removed` breaking으로 실패한다. X4·X5·R1도 실패한다. X3·X6은 behavior-change로 스냅샷에 남는다(6절 07-a). 완료 기준을 모두 채웠다.
|
||||
- **1103/07-02가 닫혔다.** 지난 라운드에 살아남은 변이 M2·M3·M9·M9b와, 이번에 더한 H19(`x-csrf-token` 허용 삭제)·S2(retry 조건 삭제)가 모두 죽는다(6절 07-b).
|
||||
- **D6(pin + 답 표)은 답 표와 프론트 판정의 어긋남은 잡는다. 백엔드 변경은 게이트가 잡지 못한다(07-01, Low).** 답 표 한 칸을 뒤집거나(D6a), 행을 더하거나 빼거나(D6d·D6e2), 프론트 표 행을 지우면(D6e) `backend-contract-pin.test.ts`가 실패한다. 그러나 이 테스트는 프론트 파일만 읽는다. 백엔드 문서의 §2 행을 바꾼 가짜 백엔드에서 drift 스크립트는 rc=1로 알렸지만, 같은 상태에서 테스트는 통과했다(D6g). 답 표 JSON이 pin한 백엔드 문서와 같은지는 아무 검사도 보지 않는다. drift 스크립트는 desktop(게이트를 도는 곳)에서 rc=2 "비교 불가"이고(D6f), worktree에서는 "skipped"로 rc=0이다. 매뉴얼에 이 스크립트가 없다.
|
||||
- **응답 스키마를 strict로 바꾸는 변경은 behavior-change다(07-02, Low, 개선 제안).** 1103/07-03 수정으로 행과 검증기는 묶였다. 그러나 둘을 같이 바꾸면 FE-REG-SCHEMA의 `unknownFieldPolicy`는 breaking 칸이 아니라 통과한다(`config/contracts/registry-governance.json:288`). 배치 07-R1: `check:registries` PASS `compatibility=behavior-change`, 관련 vitest 25파일 180건 통과.
|
||||
- **이번 수정들이 검사를 약하게 만든 곳은 찾지 못했다.** `git diff e40684b..8a44226`의 영역 테스트에서 지운 단언은 없고, 바뀐 것은 공용 함수로 옮긴 리팩터링이다. governance의 `defaultValue` 타입에 `object`가 더해진 것은 스키마 기본값을 그대로 적기 위해서다.
|
||||
- High 이상 발견은 없다. 이번 라운드 새 발견 2건(Low 2). P1도 없다.
|
||||
|
||||
## 1. 범위 (36.1)
|
||||
|
||||
| 항목 | 기록 |
|
||||
|---|---|
|
||||
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`, 영역 07 |
|
||||
| 커밋·작업 상태·확인 시점 | `8a44226`. 노트북 worktree는 읽기만 했다. 실행은 desktop checkout(`~/workspace/clean-architecture-frontend-template`, 같은 커밋)에서 helper로 2회(07-a, 07-b). 둘 다 `restored: clean at 8a442262`. 2026-11-05 19:46~19:47, 잠금 대기 약 745초, load 8.5~10.6 |
|
||||
| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음. 짝 백엔드 템플릿과 함께 빨리 출시하는 것이 목표 |
|
||||
| 필수 요구와 규모·운영 목표 | 합의된 규모·운영 목표 없음. 짝 백엔드 응답은 백엔드 `45d2a478`의 `docs/web/http-contract.md`(노트북 checkout, 읽기만)를 기준으로 했다 |
|
||||
| 읽은 코드·구성 범위 | 줄 단위: `api-operations.ts` 전체, `external-contract-runtime.ts:450-670, 800-845, 1020-1035`, `env.ts` 전체, `product-contracts.ts`, `schema-registry.ts:1-60`, `realtime-streams.ts:455-475`, `errors.ts:115-145`, `unvalidated-payload.ts`, `config/contracts/*` 6파일, `scripts/lib/registry-compatibility.ts` 전체, `scripts/check-registries.ts:680-773`, `scripts/check-backend-contract-drift.ts` 전체. `git diff e40684b..8a44226 -- src/contracts config/contracts schemas` 전체. 함께 읽은 곳: `src/adapters/http/backend-envelope.ts:120-360`, `src/bootstrap/load-runtime-config.ts:100-135`, 참조 기능 `contracts/` 3파일, `scripts/create-feature-write-slice.ts:290-300`, 테스트 `api-operation-rows`, `rest-profile-contract`, `realtime-stream-registry:220-330`, `external-contract-runtime:110-360`, `schema-metadata-policy`, `env-registry-coverage`, `backend-contract-pin`, `second-api-feature-registries`의 diff |
|
||||
| 읽은 문서(주장) | `docs/manual/01-add-a-feature.md:530-560`, `docs/manual/03-outside-feature-folder.md:106-115`, `docs/architecture/backend-api-and-server-state-contract.md:160-180`, `docs/architecture/starter-experience.md:160-175`, `docs/contracts/compatibility.md:1-60`, `config/ci/ungated-scripts.json:4-7`, 커밋 `08ed0a08`·`a94006b9`·`5bee9abe`·`3b40f736`·`9800bc89`·`e4caafda`·`ba2b4f4c` 본문, 지난 라운드 07 문서와 README 12~14절. 백엔드 `45d2a478:docs/web/http-contract.md` §2(81-135줄)·§4(184-200줄) |
|
||||
| 수행한 테스트·실험 | 6절. 07-a: `check:registries` 변이 7종 + `check:architecture` 변이 1종(각각 변이 없는 대조 포함). 07-b: vitest 변이 17종(대조 1회, 6파일 106건 통과)과 drift 스크립트 2회. 게이트는 다시 돌리지 않았다. 오케스트레이터 결과(local env, `desktop:/tmp/claude-gates/r4/gates/summary.txt`): `check:architecture`·`check:types`·`lint`·`test:unit`(194파일 2,883건)·`test:component`·`test:integration`·`test:contract`·`test:runtime-schema`·`check:adapter-inventory` rc=0, `verify:documentation` rc=1(desktop 옆 백엔드 checkout에 문서가 없다, 07-01 근거에 인용). merge-48(CI env): FE-GATE-001~009, 020 rc=0. `check-registries`를 품은 FE-GATE-010은 이 문서를 쓸 때 돌고 있었다 |
|
||||
| 확인하지 못한 범위·이유 | 07-c(응답 스키마와 행을 같이 strict로)는 잠금 대기 중 취소됐다. 오케스트레이터 배치 07-R1로 돌렸다(20:11, restore clean). `browser-rpc.ts`, `service-worker*.ts`, `web-push.ts`, `query-keys.ts`, `deployment-admission.ts`는 이번 diff가 없어 읽지 않았다. 실제 짝 백엔드를 띄워 답을 받아 보지는 않았다. FE-GATE-010·012·013의 결과는 아직 없었다 |
|
||||
| 이전 리뷰와 비교 가능한 범위 | 지난 라운드 07 문서의 실험 X2·X2b·X3·X4·X5·X6·X8·R1·Z1·E-4와 변이 M2·M3·M9·M9b를 같은 이름으로 이 커밋에서 다시 돌렸다. 지난 실행 결과는 증거로 쓰지 않았다 |
|
||||
|
||||
## 2. 지난 발견 재확인
|
||||
|
||||
| 지난 ID | 내용 | 상태 | 근거 (`8a44226`) |
|
||||
|---|---|---|---|
|
||||
| 1103/07-01 | V2 행 삭제 뒤 FE-REG-API가 status 목록·상한·마감·재시도 예산·`commandEffect`를 보지 않고, `problemSchema`는 반만 잠겼다 | **고쳐짐** | 투영이 함수 밖 descriptor 값을 모두 담는다(`src/contracts/api-operations.ts:52-61, 88-112`). governance가 새 칸을 필수 칸으로 두고(`registry-governance.json:150-163`), `problemSchema`·`unvalidated`를 breaking 칸에 넣고(`:242-255`), `problemSchema`가 FE-REG-SCHEMA를 참조한다(`:232-236`). 읽기는 `SAFE`·`IDEMPOTENT`만 조립된다(`external-contract-runtime.ts:533-543`). 실험(6절 07-a): X2·X2b `breaking change missing evidence: FE-REG-API:CREATE_REFERENCE_RESOURCE:acceptedStatuses:allowed-value-removed`로 실패. X3+X6 PASS `compatibility=behavior-change`, `responseByteLimit 32768 -> 8388608`, `totalDeadlineMs 10000 -> 60000` 기록. X4 `problemSchema references unknown FE-REG-SCHEMA.schemaId=WhateverProblem` 3건 + breaking 3건으로 실패. X5 `unvalidated:field-changed` breaking으로 실패. R1·R1b `GET is a read; its retrySemantics is SAFE or IDEMPOTENT, not KEYED/NEVER`로 실패. 매뉴얼이 breaking과 behavior-change를 나눠 적고, 행에 없는 함수(`classifyProblem`·`classifyStatus`·`projectRequest`)를 "못 잡음"에 적는다(`docs/manual/01-add-a-feature.md:539-541, 555`). 완료 기준(X2·X4·R1 실패, X3·X6 기록, X5 breaking)을 모두 채웠다 |
|
||||
| 1103/07-02 (= 10-03, 04-03) | CSRF·realtime snapshot 검사가 한 사례씩만 테스트된다 | **고쳐짐** | CSRF는 POST·PUT·PATCH·DELETE마다 CSRF 없는 프로필과 `x-tenant-context`만 요구하는 프로필을 거절하고, 두 CSRF 헤더를 각각 받는지 본다(`tests/unit/rest-profile-contract.test.ts:110-138`). realtime은 6 method × 4 retrySemantics 표를 두 복구 모드로 돈다(`tests/unit/realtime/realtime-stream-registry.test.ts:226-320`). 변이(6절 07-b): M2 3건 실패, M3 4건, H19 4건, M9 10건, M9b 22건, S2 2건. 모두 죽었다. 검사 코드는 그대로다(`external-contract-runtime.ts:585-598`, `realtime-streams.ts:457-474`) |
|
||||
| 1103/07-03 | FE-REG-SCHEMA의 `unknownFieldPolicy`·`direction`이 검증기와 묶이지 않은 손 사본이다 | **고쳐짐** | 설치된 HTTP descriptor의 입력·응답·실패 검증기를 행과 대조한다. 방향, 쓰인 자리의 boundary, 모르는 키 탐침으로 본 정책을 비교한다(`tests/unit/schema-metadata-policy.test.ts:127-165`). X8(응답 DTO `.strip()`→`.strict()`, 행은 그대로): `row STRIP_UNKNOWN, validator REJECT_UNKNOWN` 3건으로 실패(07-b). 완료 기준을 채웠다. 남은 것: 탐침은 첫 객체 단계만 본다(테스트 주석 `:19-23`, 커밋 `5bee9abe`이 한계로 적음). 행과 검증기를 같이 바꾸는 경우는 새 발견 07-02로 적었다 |
|
||||
| 1103/07-04 | 제품 설정 키의 금지 이름 검사가 부팅 때만 돈다 | **일부** · Low · P3 | `test:unit`이 스키마 키와 FE-REG-ENV runtime 키 전부를 `assertSafeConfigNames`로 검사한다(`tests/unit/env-registry-coverage.test.ts:70-83`). E4(제품 키 `PRODUCT_COOKIE_NOTICE`)가 `Forbidden client configuration key: PRODUCT_COOKIE_NOTICE`로 실패한다(07-b). 매뉴얼에 규칙이 있다(`docs/manual/03-outside-feature-folder.md:113`). **남은 것:** 부팅 오류 `CONFIG_SECRET_NAME_REJECTED`는 여전히 `buildId`만 싣고 키 이름을 버린다(`src/bootstrap/load-runtime-config.ts:118-124`). 같은 파일의 스키마 실패는 키 이름을 싣는다(`:134-135` 주석 "Key names tell an operator what to fix"). 기본값에 없고 값으로만 생기는 중첩 키는 여전히 부팅에서만 걸린다(커밋 `9800bc89` 한계) |
|
||||
| 1103/07-05 (→ 09-10) | `starter-experience.md`가 지워진 V2 모양으로 `FeatureRuntime`을 설명한다 | **고쳐짐** | 문장이 `schemas`·adapter 기여·contract 기여로 바뀌었다(`docs/architecture/starter-experience.md:166-171`). 실제 타입과 같다(`src/features/feature-module.ts:52-66`). `runtime schemas, mappers` grep 0건. 대표 발견은 영역 09의 09-10이다 |
|
||||
| 1101/07-05 | 오류 어휘 둘과 두 "retry"의 관계가 타입 옆에 없다 | **고쳐짐** | `AppFailure` 위에 `AppError`와의 관계와 재시도 규칙이 있고, `retryable` 칸에 "src에서 읽는 곳 없음"과 `action: "retry"`와의 차이가 있다(`src/contracts/errors.ts:121-145`). `src`의 `.retryable` 읽기는 upload·realtime·파일 결과 타입의 것뿐이다(git grep). `AppFailure.retryable`을 읽는 곳은 찾지 못했다 |
|
||||
| 1101/07-07 | `commandRecovery`를 실행기가 읽지 않고 수습 책임이 타입 옆에 없다 | **고쳐짐** | 타입 위 주석이 "실행기는 읽지 않는다, 기능 gateway가 정한다"고 적는다(`external-contract-runtime.ts:130-138`). FE-REG-API 행이 이 값을 기록한다(`api-operations.ts:109-112`) |
|
||||
| P-07-05 | FE-REG-ENV runtime 행이 zod 스키마와 다르다 | **고쳐짐** | 행 값 5곳이 스키마와 같아졌다(`src/contracts/env.ts:59-80`). 테스트가 두 방향(스키마→행, 행→스키마)과 `required`·`defaultValue`를 대조한다(`tests/unit/env-registry-coverage.test.ts:33-63`). 오케스트레이터 `test:unit` rc=0에서 4건 통과(`gates/test_unit.log`) |
|
||||
| P-07-06 | zod facade 규칙이 `"zod"`만 막는다 | **고쳐짐** | 규칙 경로가 `^zod(/|$)`다(`.dependency-cruiser.json:60-68`). Z1: 변이 없이 `check:architecture` rc=0, 참조 스키마의 import를 `"zod/v4"`로 바꾸면 `Architecture violation [zod-is-reached-through-contracts-zod]` rc=1(07-a) |
|
||||
| P-07-07 | CHANGELOG [계약] 행이 레지스트리 분류기를 잘못 가리킨다 | **고쳐짐** | 행이 "설정 스키마 호환성 분류기(`classifyObjectSchemaChange`)"라 적고 레지스트리 분류기와 다르다고 적는다(`CHANGELOG.md:310`). README 14.4가 적었듯 지난 판정은 이름과 둘째 경로만 맞았다 |
|
||||
|
||||
틀린 발견으로 판정한 것은 없다.
|
||||
|
||||
## 3. 이번 발견 (36.3)
|
||||
|
||||
새 발견 2건. 심각도 Low 2. 우선순위 P3 2. 성격 구조적 위험 1, 개선 제안 1. High 이상과 P1은 없다. 남은 지난 발견(1103/07-04 일부, Low·P3)은 2절에 있다.
|
||||
|
||||
### 07-01 짝 백엔드 답 표 JSON이 pin한 백엔드 문서와 같은지 아무 검사도 보지 않고, 백엔드 변경은 게이트 밖 스크립트만 알린다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 구조적 위험 (검출 경로를 실행으로 확인. 실제 백엔드 변경으로 생긴 피해는 미확인) |
|
||||
| 관련 관점 | 17, 21, 10, 20, 26 |
|
||||
| 근거 | D6은 세 조각이다. **(1) pin**(`config/contracts/backend-contract-pin.json:1-19`): 백엔드 커밋 `45d2a478`, 대조한 절 `["1", "2", "4"]`(`:7`). **(2) 답 표 테스트**: `tests/unit/backend-contract-pin.test.ts`는 pin과 답 표 JSON 두 파일만 읽는다(`:76, 79`). 두 파일의 커밋이 같은지(`:91-98`), 답마다 프론트 판정이 표와 같은지(`:108-121`), 프론트 표의 행이 답 표에 있는지(`:123-140`)를 본다. **(3) drift 스크립트**: `scripts/check-backend-contract-drift.ts`는 게이트 밖이다(`config/ci/ungated-scripts.json:5-6`). 옆 디렉터리 `../clean-architecture-backend-template`(`:30`)에서 pin 커밋과 HEAD 사이에 `http-contract.md` 글자가 바뀌었는지만 본다(`:60`). **실행(6절 07-b):** 답 표의 한 칸 뒤집기(D6a), pin 커밋만 바꾸기(D6b), 답 표에 새 답 더하기(D6d), 프론트 표 행 지우기(D6e), 답 표 행 지우기(D6e2)는 모두 테스트가 실패한다. pin과 답 표의 커밋을 함께 `c508b1ba`로 바꾸면 통과한다(D6c). 가짜 백엔드 repo에서 §2의 `IDEMPOTENCY_COMPLETION_UNKNOWN` status를 503→500으로 바꾼 커밋을 HEAD로 두자, drift 스크립트는 바뀐 표 줄을 찍고 rc=1이었다. 같은 pin 상태에서 테스트는 10건 모두 통과했다(D6g). **빈 곳 셋.** (a) 답 표 JSON이 pin한 커밋의 백엔드 문서와 같은지는 테스트도 스크립트도 보지 않는다. 테스트는 사본만, 스크립트는 문서끼리만 비교한다. 지금 사본은 §2 표 6행과 §4 `REQUEST_TIMEOUT`이 백엔드 `45d2a478:docs/web/http-contract.md:89-91, 111-113, 190`과 같다(리뷰어가 대조). §4의 `RATE_LIMIT_UNAVAILABLE`·`RATE_LIMIT_INCOMPATIBLE`(`:192-193`)은 옮기지 않았다. 프론트 계약 문서는 "§2 표와 §4 `REQUEST_TIMEOUT`"만 옮겼다고 적는다(`docs/architecture/backend-api-and-server-state-contract.md:170`). pin의 `sectionsCompared`는 §4 전체처럼 읽힌다. (b) drift 스크립트가 실제로 돌 수 있는 곳이 좁다. desktop(게이트를 도는 곳)의 옆 백엔드 checkout은 `ef947e5`(2026-09-16)라 pin 커밋이 없어 rc=2 "cannot compare"다(D6f). 같은 원인으로 오케스트레이터의 local `verify:documentation`도 rc=1이다(`gates/verify_documentation.log`, 영역 14·12 몫이라 여기서 세지 않음). 기본 경로가 cwd 기준이라 `.claude/worktrees/<이름>`에서 돌리면 옆 디렉터리가 없어 "skipped"로 rc=0이다(`:40-45`). (c) `docs/manual/`에 이 스크립트가 없다(git grep 0건). 실행 시점은 `ungated-scripts.json`의 "Run this before moving the pin"과 아키텍처 문서(`:175-177`)에만 있다. 백엔드가 움직이고 pin은 그대로인 경우를 누가 언제 보는지는 적혀 있지 않다 |
|
||||
| 발생 조건 | 짝 백엔드가 §2·§4의 답(status, 쓰기 전 거절 여부, 같은 키 재전송)을 바꾸고, 프론트는 그 백엔드를 받았지만 drift 스크립트를 돌리지 않았을 때. 또는 pin을 올리면서 답 표를 잘못 옮겼을 때 |
|
||||
| 영향 | 프론트 Envelope 판정이 실제 백엔드와 달라진다. 위험한 방향은 지금 `NOT_APPLIED`인 code(`src/adapters/http/backend-envelope.ts:152-172`)가 백엔드에서 "적용됐을 수 있음"으로 바뀌는 경우다. 그러면 다음 저장이 새 키를 써 같은 작업이 두 번 적용될 수 있다(추론, 실행 안 함). D6g 같은 status 변경은 표의 status+code 짝이 안 맞아 기능 분류기로 넘어간다(`backend-envelope.ts:340-351`). 생성 뼈대 분류기는 늘 `MAYBE_APPLIED`라(`scripts/create-feature-write-slice.ts:298`) 지금 템플릿에서는 결과 불명으로 끝난다. 이 설정은 모든 다운스트림에 복제된다 |
|
||||
| 심각도·우선순위 | Low · P3 — 지금 사본은 맞고, 모르는 답은 템플릿 분류기에서 결과 불명으로 끝난다. 피해는 백엔드 변경과 사람 절차 누락이 겹칠 때만 난다. 다만 지난 라운드 중 백엔드가 세 번 움직였고(README 14.3), 이 경로가 게이트에서 보이지 않으니 P3 안에서 먼저 한다 |
|
||||
| 통제·증거 | 목표 M3(pin한 백엔드 문서와 사본의 어긋남, pin 뒤 백엔드 변경을 기계가 알림) / 확인: 사본↔프론트 표 M3, 사본↔pin 문서 M0, pin 뒤 백엔드 변경 M1(게이트 밖 스크립트, 돌 때만 M3) · E2(D6a~D6g) |
|
||||
| 확실성과 남은 가정 | 실행으로 확인했다. D6g는 진짜 백엔드가 아니라 백엔드 문서 한 파일로 만든 가짜 repo다. 다운스트림 두 repo가 백엔드 checkout을 어디에 두는지는 보지 않았다 |
|
||||
| 결정의 근거 | 기록된 결정: D6 "(1) pin 파일 + (2) 답 표 JSON 대조 테스트 + 로컬 drift 검사"(README 14.2). 이유는 CI가 frontend만 checkout한다는 것이다(`ungated-scripts.json:6`). 리뷰어 판단: 게이트 밖에 두는 이유는 타당하다. 빠진 것은 사본과 pin 문서를 잇는 고리 하나와, 스크립트가 "비교 못 함"을 통과처럼 끝내는 경우다 |
|
||||
| 이해 비용 | 백엔드를 올리는 사람은 아키텍처 문서 4.1절을 찾아 읽어야 스크립트와 세 파일을 함께 고쳐야 한다는 것을 안다 |
|
||||
| 최소 개선 방향 | (1) drift 스크립트가 pin 커밋의 백엔드 문서에서 §2·§4 표 행(code·status)을 읽어 답 표 JSON과 비교한다. 옮기지 않는 행(`RATE_LIMIT_*`)은 pin에 이유와 함께 적는다. (2) 옆 checkout이 없으면 "skipped"를 rc=0이 아닌 다른 값으로 끝내거나, `--backend`를 필수로 한다. (3) 매뉴얼 04(짝 백엔드)나 01의 Envelope 단계에 "백엔드를 받으면 `check:backend-contract-drift --backend <dir>`"를 한 줄 적는다 |
|
||||
| 대안 비교 | (A) 현 상태: 비용 0. 사본 오타와 백엔드 이동을 사람이 본다. (B) 위 (1)~(3): 표 파서 수십 줄, 문서 한 줄. 게이트 밖이라 CI 비용은 없다. (C) 백엔드 문서 사본(또는 다이제스트)을 프론트에 두고 테스트가 사본에서 표를 읽음: 게이트 안에서 사본↔JSON을 본다. 대신 백엔드 문서를 프론트에 복사하는 사본이 하나 더 생긴다. (D) 계약 패키지(`@org-contracts/*`)에 답 표를 넣어 두 repo가 같은 파일을 읽음: 가장 단단하지만 패키지 배포 경로가 아직 없다 |
|
||||
| 단순화의 보존 조건 | 답 표 테스트의 양방향 대조(D6a·D6d·D6e·D6e2 실패)는 그대로 둔다. CI는 frontend만 checkout한다는 전제를 바꾸지 않는다 |
|
||||
| 비용·부작용 | (B) 백엔드 문서 표 형식이 바뀌면 파서도 고친다. 백엔드 §5("바꿀 때")에 프론트 파서를 적어야 할 수 있다 |
|
||||
| 재검토 조건 | 계약 패키지가 생기면 (D)로 옮기고 pin과 drift 스크립트를 지운다. 백엔드 표가 기계 형식(YAML 등)으로 따로 나오면 (1)은 그 파일을 읽는다 |
|
||||
| 완료 기준 | D6g처럼 pin과 다른 행을 가진 답 표, 또는 pin 문서에만 있는 행을 drift 스크립트가 rc≠0으로 알린다. 옆 checkout이 없을 때 rc=0으로 끝나지 않는다. 매뉴얼에서 스크립트를 찾을 수 있다 |
|
||||
| 검증 방법 | D6g 재실행과, 답 표 JSON의 status 하나를 pin 문서와 다르게 바꾼 경우 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 (D6 이후 생긴 경로. 영역 12의 12-06 후속과 겹치면 하나로 센다) |
|
||||
| 재검증 결과 | 미실시 |
|
||||
|
||||
### 07-02 응답 스키마를 strict로 좁히는 변경이 FE-REG-SCHEMA에서 behavior-change로 통과한다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 개선 제안 (배치 07-R1로 실행 확인) |
|
||||
| 관련 관점 | 17, 21, 23 |
|
||||
| 근거 | FE-REG-SCHEMA의 breaking 칸은 `schemaId`·`boundary`·`runtime`뿐이다(`config/contracts/registry-governance.json:288`). `unknownFieldPolicy`·`direction`은 governance에 이름도 없다. 분류기는 breaking 칸이 아닌 값 변경을 `behavior-change`로 본다(`scripts/lib/registry-compatibility.ts:346-351`). 기준선에 응답 행의 `STRIP_UNKNOWN`이 있다(`config/contracts/registry-baseline.json:618, 627`). 1103/07-03 수정 테스트는 행과 검증기가 같은지만 본다(`tests/unit/schema-metadata-policy.test.ts:154-165`). 그래서 응답 DTO를 `.strict()`로 바꾸고 행을 `REJECT_UNKNOWN`으로 같이 고치면 모든 검사가 통과한다. **07-R1(배치):** 그 패치에서 `check:registries`가 `11 registries PASS; compatibility=behavior-change`로 통과했다. 변경은 `FE-REG-SCHEMA:ReferenceResourceListPayload:unknownFieldPolicy:field-changed behavior-change`와 `ReferenceResourcePayload`의 같은 줄 2건이다. `tests/unit/schema-metadata-policy.test.ts`, `tests/features/reference-feature`, `tests/contract`, `tests/runtime-schema` 25파일 180건이 모두 통과했다. 응답에 모르는 필드를 싣는 테스트가 없어 아무 테스트도 잡지 않았다. 같은 경계에서 FE-REG-API는 `acceptedStatuses` 축소를 breaking으로 본다(1103/07-01 수정). 호환 문서는 REJECT_UNKNOWN 경계에서 필드 추가가 breaking이라 적고(`docs/contracts/compatibility.md:18-19`), 참조 응답 DTO를 additive라 적는다(`:28`). 경계를 strict로 바꾸면 이 표의 칸이 바뀌지만 그 변경을 잡는 검사는 없다 |
|
||||
| 발생 조건 | 기능 작성자가 응답 DTO를 `.strict()`로 바꾸고, 정책 테스트가 실패하자 메타데이터 행도 `REJECT_UNKNOWN`으로 고칠 때 |
|
||||
| 영향 | 백엔드가 응답에 필드 하나를 더할 때마다 그 API가 `SCHEMA_MISMATCH`로 실패한다. 리뷰어는 스냅샷 diff에서 behavior-change 한 줄로만 본다. 런타임 피해는 백엔드가 필드를 더한 뒤에 생긴다 |
|
||||
| 심각도·우선순위 | Low · P3 — 지금 템플릿 코드는 맞다. 바뀌는 경우도 스냅샷에 기록은 남는다. 등급만 FE-REG-API와 맞지 않는다 |
|
||||
| 통제·증거 | 목표 M3(응답 경계를 좁히는 변경은 breaking) / 확인 M2(기록만, behavior-change) · E2(07-R1) |
|
||||
| 확실성과 남은 가정 | 실행으로 확인했다. test:component·integration·e2e는 이 패치로 돌리지 않았다. MSW 응답이 DTO 키만 보내면 그쪽도 통과할 것이다(추론) |
|
||||
| 결정의 근거 | 기록된 결정: `5bee9abe`·`3b40f736`은 행과 검증기를 묶었고 등급은 바꾸지 않았다. 리뷰어 판단: 응답 방향의 `STRIP_UNKNOWN`→`REJECT_UNKNOWN`만 breaking이면 충분하다. 요청 방향이나 반대 방향(REJECT→STRIP)은 읽는 쪽을 넓히는 변경이라 behavior-change가 맞다 |
|
||||
| 이해 비용 | 적음. 기능 작성자는 FE-REG-API와 FE-REG-SCHEMA의 등급 규칙이 다르다는 것을 governance JSON을 읽어야 안다 |
|
||||
| 최소 개선 방향 | (1) governance FE-REG-SCHEMA에 `unknownFieldPolicy`·`direction`을 `fieldTypes`로 선언한다. (2) 분류기에 "RESPONSE 행의 `STRIP_UNKNOWN`→`REJECT_UNKNOWN`은 breaking" 규칙 하나를 더하거나, 더 단순하게 `unknownFieldPolicy`를 breaking 칸에 넣는다(완화 쪽도 증거가 필요해지지만 드문 변경이다) |
|
||||
| 대안 비교 | (A) 현 상태: 기록만. (B) `unknownFieldPolicy`를 breaking 칸에: governance 한 줄과 기준선 재승인 1회. 완화도 증거를 요구한다. (C) 방향 규칙을 분류기에: 정확하지만 레지스트리별 특수 규칙이 생긴다 |
|
||||
| 단순화의 보존 조건 | 적용 제외 — 등급 규칙 추가다 |
|
||||
| 비용·부작용 | governance 계약 변경이라 `contract-field-changed` breaking으로 기준선 재승인 1회. 다운스트림은 동기화 때 1회 |
|
||||
| 재검토 조건 | 응답 검증기가 정책을 스스로 보고하게 되면(생성 검증기 등) 행 칸 대신 검증기 정보를 레지스트리에 싣는다 |
|
||||
| 완료 기준 | 07-R1 변이에서 `check:registries`가 `FE-REG-SCHEMA:...:unknownFieldPolicy` breaking 증거 누락으로 실패한다 |
|
||||
| 검증 방법 | 07-R1 재실행 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 (1103/07-03 수정 뒤 남은 범위) |
|
||||
| 재검증 결과 | 미실시 |
|
||||
|
||||
## 4. 28개 관점 판정 (36.2)
|
||||
|
||||
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가
|
||||
|
||||
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|
||||
|---|---|---|---|---|---|
|
||||
| **1** | 코드 성숙도 | 적용. 조립기가 계약 규칙의 유일한 입구다 | M4 / M4 | E2(07-b MR1·MW1·MF1, 07-a R1) | O — 읽기 `SAFE`·`IDEMPOTENT`, 쓰기 `SAFE` 금지, 쓰기 전 거절 목록, 기여당 wire 틀 하나가 조립에서 막히고 변이가 모두 죽는다. 함수(`classifyProblem` 등)의 내용은 조립이 보지 않는다(매뉴얼에 적힘) |
|
||||
| 2 | 구조적 성숙도 | 적용 | M3 / M3 | E2(`check:architecture` rc=0, 오케스트레이터) | O — 계약은 application·presentation·bootstrap을 import하지 않는다. 이번 diff의 새 import는 `platform/traffic` 타입 하나다(`api-operations.ts:11`) |
|
||||
| **3** | 변경 용이성 | 적용. API 하나 추가·변경 | M3 / M3 | E2(07-a X2~X6) | O — wire 칸 변경이 스냅샷에 보이고 축소는 breaking이다. 함수가 보내는 값(`projectRequest`)은 PR에서 본다(매뉴얼 "못 잡음") |
|
||||
| 4 | 인지 부하 | 적용 | M1 / M1 | E1 | O — 오류 어휘 둘의 관계가 타입 옆에 있다. 폐기 별칭 `MappingResult`는 제거 조건과 lint로 남아 있다(`boundary-mapper.ts:1-28`) |
|
||||
| 5 | 위험 가시성 | 적용 | M2 / M3 | E2(07-a X5) | O — 검증 생략이 행(`unvalidated`)과 breaking 등급으로 드러난다. `commandRecovery`를 누가 읽는지 타입 옆에 있다 |
|
||||
| 6 | 실패 성숙도 | 적용 | M3 / M3 | E2 | O — 조립 실패가 operation·method·원인을 메시지에 싣는다(`external-contract-runtime.ts:291-293`). `check:registries`가 그 원인을 찍는다(07-a R1) |
|
||||
| 7 | 운영 성숙도 | 다른 영역 | - | - | > 영역 03·13 |
|
||||
| 8 | 디버깅 가능성 | 적용 | M2 / M2 | E2(07-b E4, D6g) | P — 테스트와 drift 스크립트는 고칠 곳을 말한다. 부팅 `CONFIG_SECRET_NAME_REJECTED`는 키 이름을 버린다(1103/07-04 남음) |
|
||||
| 9 | 유지보수 성숙도 | 적용 | M2 / M2 | E1 | O — 낡은 문서 줄(1103/07-05)과 CHANGELOG 행(P-07-07)이 고쳐졌다 |
|
||||
| **10** | 테스트 성숙도 | 적용 | M3 / M3 | E2(변이 26종) | P — 07-a·07-b의 변이 26종이 모두 기대한 대로 죽거나(실패) 기록됐다. 답 표 사본과 pin 문서를 잇는 테스트는 없다(07-01). 행과 검증기를 같이 strict로 바꾸면 테스트 25파일이 모두 통과한다(07-R1, 07-02) |
|
||||
| 11 | 데이터 성숙도 | 다른 영역 | - | - | > 영역 05 |
|
||||
| 12 | 동시성 성숙도 | 적용 제외. 계약은 순수 선언과 검사다 | - | - | - |
|
||||
| 13 | 확장성 | 적용 | M2 / M2 | E2(`second-api-feature-registries`, test:unit 통과) | O — 새 operation은 additive이고 governance를 고치지 않는다 |
|
||||
| 14 | 성능 성숙도 | 다른 영역 | - | - | > 영역 15. 이번 diff는 투영 칸을 늘렸지만 투영은 레지스트리 검사와 개요 화면에서만 돈다 |
|
||||
| **15** | 보안 성숙도 | 적용 | M4 / M4 | E2(07-b M2·M3·H19, 07-a Z1, 07-b E4) | O — 쿠키 쓰기 CSRF 조립 검사가 method·헤더 이름별로 잠겼다. zod 하위 경로도 facade를 거친다. 금지 설정 키가 `test:unit`에서 막힌다. descriptor 밖 쿠키 POST(upload 제어)는 영역 01 |
|
||||
| 16 | 의존성 성숙도 | 다른 영역 | - | - | > 영역 13 |
|
||||
| **17** | API / Contract 성숙도 | 적용 | M3 / M3(부분) | E2(07-a, 07-b D6a~D6g, 07-R1) | P — FE-REG-API가 실행되는 wire 값을 모두 기록한다(큰 개선). 짝 백엔드 답 표는 사본↔프론트만 잠겼고 사본↔백엔드는 게이트 밖이다(07-01). 응답 경계를 좁히는 변경은 기록만 된다(07-02) |
|
||||
| 18 | 배포 성숙도 | 다른 영역 | - | - | > 영역 13 |
|
||||
| **19** | 설정 성숙도 | 적용 | M3 / M3 | E2(07-b E4, test:unit) | P — FE-REG-ENV 행이 두 방향과 값까지 스키마와 같다(P-07-05 고쳐짐). 금지 이름이 test:unit에서 잡힌다. 부팅 오류에 키 이름이 없다(1103/07-04 남음) |
|
||||
| 20 | 개발자 경험 | 적용 | M2 / M1 | E1 | P — 매뉴얼이 breaking과 behavior-change, 못 잡는 것을 맞게 적는다. drift 스크립트는 매뉴얼에 없고, worktree에서는 "skipped" rc=0이다(07-01) |
|
||||
| **21** | Guardrail 성숙도 | 적용 | M3 / M3(부분) | E2 | P — breaking 칸 12개, 참조 3개, 조립 규칙이 동작한다. 백엔드 변경 검출은 게이트 밖이고 desktop에서 비교 불가다(07-01) |
|
||||
| 22 | 추상화 성숙도 | 적용 | M2 / M2 | E1 | O — 투영이 descriptor 하나에서 행을 뽑아 사본이 없다. 스키마 메타 행은 남았지만 테스트가 쓰임과 대조한다 |
|
||||
| 23 | 일관성 | 적용 | M2 / M1 | E1 | P — FE-REG-API는 경계 축소를 breaking으로, FE-REG-SCHEMA는 behavior-change로 본다(07-02). Browser RPC는 여전히 `KEYED_COMMAND`·`NON_REPLAYABLE`이다(`src/contracts/browser-rpc.ts:51-52`) |
|
||||
| 24 | 네이밍 / 의미 성숙도 | 적용 | M2 / M2 | E1 | P — `unknownFieldPolicy`가 이제 검증기와 대조돼 이름에 효과가 생겼다. `SAME_ORIGIN_COOKIE` 전송이 `credentials: "include"`도 받아 이름보다 넓다(`src/contracts/rest-profiles.ts:177-183`, 지난 라운드와 같음, 발견으로 세지 않음). pin의 `sectionsCompared: ["4"]`가 실제로 옮긴 범위(§4 한 행)보다 넓게 읽힌다(07-01) |
|
||||
| 25 | 조직 확장성 | 적용 | M2 / M2 | E2(second-api 테스트) | O — 기능 팀이 governance나 기준선을 고치지 않고 API를 더한다 |
|
||||
| 26 | Ownership 성숙도 | 적용 | M2 / M2 | E1 | P — pin에 `owner`·`comparedOn`이 있다. 백엔드가 움직였을 때 누가 drift를 돌리는지는 정해져 있지 않다(07-01) |
|
||||
| 27 | 삭제 가능성 | 적용 | M3 / M3 | E2(FE-GATE-020 rc=0, 오케스트레이터) | O — 참조 기능 제거 드릴이 통과한다. 정책 테스트는 설치된 기능이 없으면 빈 채로 통과한다(`schema-metadata-policy.test.ts:124-125`) |
|
||||
| 28 | 회복 가능성 | 적용 제외. 계약은 복구 절차를 소유하지 않는다 | - | - | - |
|
||||
|
||||
X(미충족)인 관점은 없다.
|
||||
|
||||
## 5. 미검증
|
||||
|
||||
- 07-R1 패치로는 `check:registries`와 vitest 25파일만 돌렸다. test:component·integration·e2e는 돌리지 않았다.
|
||||
- 실제 짝 백엔드를 띄워 §2·§4 답을 받아 프론트 판정을 본 적은 없다. D6g는 문서 한 파일로 만든 가짜 repo다.
|
||||
- FE-GATE-010(`check-registries` 포함)·012·013의 merge-48 결과는 이 문서를 쓸 때 아직 없었다. `check:registries` 변이 없는 결과는 07-a의 A0(`11 registries PASS; compatibility=none`)를 썼다.
|
||||
- 다운스트림 두 repo가 백엔드 checkout을 어디에 두고 drift 스크립트를 돌리는지는 보지 않았다.
|
||||
- `browser-rpc.ts`, `service-worker*.ts`, `web-push.ts`, `query-keys.ts`, `deployment-admission.ts`는 이번 diff가 없어 다시 읽지 않았다.
|
||||
|
||||
## 6. 실행 기록
|
||||
|
||||
모든 실행은 desktop helper(`/tmp/claude-gates/r4/exp.sh`)로 했다. 변이 스크립트는 사례마다 `perl -0pi`로 한 파일을 바꾸고, 바뀌지 않으면 그 사례를 건너뛰고, 명령 뒤 `git checkout -- .`로 되돌렸다. 스크립트는 `desktop:/tmp/claude-gates/r4/mut/07-lib.sh`, `07-loop-a.sh`, `07-loop-b.sh`, 사례별 출력은 `desktop:/tmp/claude-gates/r4/exp/07-cases/`다. 처음 띄운 두 실행은 ssh 수명 문제로 잠금을 얻기 전에 직접 멈췄다(로그 없음, checkout에 닿지 않음). 07-c는 19:55 helper 종료로 취소돼 배치 요청 07-R1이 됐다.
|
||||
|
||||
| 실행 | 명령 | 잠금 대기·load | rc | 복구 |
|
||||
|---|---|---|---|---|
|
||||
| 07-a | `bash /tmp/claude-gates/r4/mut/07-loop-a.sh` (env local) | 740초 · 10.57 · 19:46:44 | 0 (11초) | `restored: clean at 8a442262` |
|
||||
| 07-b | `bash /tmp/claude-gates/r4/mut/07-loop-b.sh` (env local) | 749초 · 8.45 · 19:46:55 | 0 (16초) | `restored: clean at 8a442262` |
|
||||
| 07-c | `bash /tmp/claude-gates/r4/mut/07-loop-c.sh` | — | 실행 안 됨 | 취소(checkout에 닿지 않음) → 07-R1 |
|
||||
| 07-R1(오케스트레이터 배치) | 패치 `requests/07-R1-strict-response.diff` 적용 뒤 `corepack pnpm -s check:registries`, 변경 출력, `node scripts/run-vitest.ts run tests/unit/schema-metadata-policy.test.ts tests/features/reference-feature tests/contract tests/runtime-schema` (env local) | 배치 · 1.01 · 20:11:41 | registries-rc=0, vitest-rc=0 (8초) | restore clean(앞뒤로 `8a44226`) |
|
||||
|
||||
### 6.1 07-a: FE-REG-API와 zod facade (`corepack pnpm -s check:registries`, Z1은 `check:architecture`)
|
||||
|
||||
| 사례 | 변이 | rc | 결과 |
|
||||
|---|---|---|---|
|
||||
| A0 | 없음 | 0 | `11 registries PASS; compatibility=none` |
|
||||
| X2 | 생성 API `acceptedStatuses` `[200, 201]`→`[201]` | 1 | **잡힘.** `breaking change missing evidence: FE-REG-API:CREATE_REFERENCE_RESOURCE:acceptedStatuses:allowed-value-removed` |
|
||||
| X2b | 같은 칸 → `[200]` | 1 | **잡힘.** 같은 메시지 |
|
||||
| X3+X6 | GET 상세 `responseByteLimit` 32,768→8,388,608, `totalDeadlineMs` 10,000→60,000 | 0 | PASS `compatibility=behavior-change`. `responseByteLimit:field-changed behavior-change 32768 -> 8388608`, `totalDeadlineMs:field-changed behavior-change 10000 -> 60000` |
|
||||
| X4 | problem 검증기 id `ReferenceProblem`→`WhateverProblem` | 1 | **잡힘.** `problemSchema references unknown FE-REG-SCHEMA.schemaId=WhateverProblem` 3건, `problemSchema:field-changed` breaking 3건 |
|
||||
| X5 | GET 상세 출력 검증기 → `unvalidatedPayload` | 1 | **잡힘.** `breaking change missing evidence: FE-REG-API:GET_REFERENCE_RESOURCE:unvalidated:field-changed` |
|
||||
| R1 | GET 상세 `retrySemantics` `SAFE`→`KEYED` | 1 | **잡힘.** `GET is a read; its retrySemantics is SAFE or IDEMPOTENT, not KEYED` |
|
||||
| R1b | 같은 칸 → `NEVER` | 1 | **잡힘.** `... not NEVER` |
|
||||
| Z1-base | 없음 (`check:architecture`) | 0 | `Architecture graph fixtures: 29 regression checks PASS` |
|
||||
| Z1 | 참조 스키마 import를 `"zod/v4"`로 | 1 | **잡힘.** `Architecture violation [zod-is-reached-through-contracts-zod]: ... -> zod/v4` |
|
||||
|
||||
### 6.2 07-b: 조립 규칙·정책·설정·D6 (`node scripts/run-vitest.ts run <파일>`)
|
||||
|
||||
| 사례 | 변이 | 테스트 파일 | rc | 결과 |
|
||||
|---|---|---|---|---|
|
||||
| B0 | 없음 | 아래 6파일 전부 | 0 | 6파일 106건 통과 |
|
||||
| M2 | CSRF 검사 `!isRead`→`method === "POST"` | rest-profile-contract, realtime-stream-registry | 1 | **죽음.** PUT·PATCH·DELETE 거절 3건 실패 |
|
||||
| M3 | CSRF 헤더 이름 검사 → "필수 헤더가 0개면" | 같음 | 1 | **죽음.** POST·PUT·PATCH·DELETE 4건 |
|
||||
| H19 | `x-csrf-token` 허용 삭제 | 같음 | 1 | **죽음.** "accepts a %s that requires x-csrf-token" 4건 |
|
||||
| M9 | snapshot의 `method === "GET"` 조건 삭제 | 같음 | 1 | **죽음.** HEAD·POST·PUT·PATCH·DELETE × SAFE·IDEMPOTENT 10건 |
|
||||
| M9b | method·retrySemantics 조건 모두 삭제 | 같음 | 1 | **죽음.** 22건 |
|
||||
| S2 | retrySemantics 조건만 삭제 | 같음 | 1 | **죽음.** GET × KEYED·NEVER 2건 |
|
||||
| MR1 | 읽기 `SAFE`·`IDEMPOTENT` 규칙 끔 | external-contract-runtime | 1 | **죽음.** GET·HEAD × KEYED·NEVER 4건 |
|
||||
| MW1 | 쓰기 `SAFE` 거절 끔 | 같음 | 1 | **죽음.** POST·PUT·PATCH·DELETE 4건 |
|
||||
| MF1 | `assertSameWireFrame` 호출 삭제 | 같음 | 1 | **죽음.** "refuses an operation that forgot the Envelope" 1건 |
|
||||
| X8 | 응답 DTO `.strip()`→`.strict()`(행 그대로) | schema-metadata-policy | 1 | **죽음.** `row STRIP_UNKNOWN, validator REJECT_UNKNOWN` 3건 |
|
||||
| E4 | 제품 키 `PRODUCT_COOKIE_NOTICE`(zod 필드 + FE-REG-ENV 행) | env-registry-coverage | 1 | **죽음.** `Forbidden client configuration key: PRODUCT_COOKIE_NOTICE` |
|
||||
| D6a | 답 표 `IDEMPOTENT_REQUEST_MISMATCH.refusedBeforeWrite` true→false | backend-contract-pin | 1 | **잡힘.** `expected 'NOT_APPLIED' to be 'MAYBE_APPLIED'` 외 1건 |
|
||||
| D6b | pin 커밋만 `c508b1ba`로 | 같음 | 1 | **잡힘.** "names one backend commit" |
|
||||
| D6c | pin과 답 표 커밋을 함께 `c508b1ba`로 | 같음 | 0 | **통과.** 10건. 테스트는 백엔드를 읽지 않는다 |
|
||||
| D6d | 답 표에 새 답(409, 쓰기 전 거절, 같은 키 아님) | 같음 | 1 | **잡힘.** `expected 'MAYBE_APPLIED' to be 'NOT_APPLIED'` |
|
||||
| D6e | 프론트 표에서 `REQUEST_TIMEOUT` 행 삭제 | 같음 | 1 | **잡힘.** `expected undefined to be 'MAYBE_APPLIED'` |
|
||||
| D6e2 | 답 표에서 `REQUEST_TIMEOUT` 행 삭제 | 같음 | 1 | **잡힘.** `503 REQUEST_TIMEOUT: expected false to be true` |
|
||||
| D6f | 없음. `node scripts/check-backend-contract-drift.ts` | — | 스크립트 rc 2 | `cannot compare /home/donghyeon/workspace/clean-architecture-backend-template with the pinned 45d2a478b800`. desktop 옆 checkout은 `ef947e5`(2026-09-16)라 pin 커밋이 없다 |
|
||||
| D6g | 가짜 백엔드 repo(커밋1 = `45d2a478` 문서, 커밋2 = `IDEMPOTENCY_COMPLETION_UNKNOWN` 503→500). pin·답 표 커밋을 커밋1로 | drift 스크립트 `--backend <가짜>`, backend-contract-pin | 스크립트 rc 1, 테스트 rc 0 | drift가 바뀐 표 줄 두 개(`-| ... | 503 |`, `+| ... | 500 |`)와 "Recheck ..."를 찍었다. 같은 상태에서 테스트는 10건 통과 |
|
||||
|
||||
변이 26종(07-a 8종, 07-b 18종) 중 통과를 예상한 X3+X6·D6c와 D6g의 테스트 쪽을 빼면 모두 기대한 메시지로 실패했다. 변이 없는 대조(A0, Z1-base, B0)는 모두 통과했다.
|
||||
|
||||
### 6.3 배치 요청
|
||||
|
||||
| 요청 | 내용 | 상태 |
|
||||
|---|---|---|
|
||||
| 07-R1 | 응답 DTO `.strict()` + 두 응답 행 `REJECT_UNKNOWN` 패치로 `check:registries`와 정책·참조 기능·contract·runtime-schema vitest | 완료. `11 registries PASS; compatibility=behavior-change`. `FE-REG-SCHEMA:ReferenceResource(List)Payload:unknownFieldPolicy:field-changed behavior-change "STRIP_UNKNOWN" -> "REJECT_UNKNOWN"` 2건. vitest 25파일 180건 통과. 변이 없는 대조는 07-a A0와 `gates/test_unit.log`·`test_contract.log`·`test_runtime-schema.log`, FE-GATE-005다. 결과 로그는 `scratchpad/r4/results/07/07-R1.log` |
|
||||
|
||||
## 7. 새 발견 요약
|
||||
|
||||
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|
||||
|---|---|---|---|---|
|
||||
| 07-01 | Low · P3 | 구조적 위험 | 짝 백엔드 답 표 JSON이 pin한 백엔드 문서와 같은지 아무 검사도 보지 않고, 백엔드 변경은 게이트 밖 drift 스크립트만 알린다(desktop에서 비교 불가, worktree에서 skipped rc=0, 매뉴얼에 없음) | `tests/unit/backend-contract-pin.test.ts:76-79`, `scripts/check-backend-contract-drift.ts:30, 40-45, 60`, `config/contracts/backend-contract-pin.json:7` |
|
||||
| 07-02 | Low · P3 | 개선 제안 | 응답 스키마를 행과 함께 strict로 좁히는 변경이 FE-REG-SCHEMA에서 behavior-change로 통과하고 관련 테스트 25파일이 모두 통과한다(07-R1) | `config/contracts/registry-governance.json:288`, `scripts/lib/registry-compatibility.ts:346-351`, `tests/unit/schema-metadata-policy.test.ts:154-165` |
|
||||
@@ -0,0 +1,255 @@
|
||||
# 영역 08 — presentation
|
||||
|
||||
> 검토일 2026-11-05 · 기준 `8a44226`(`fix/maturity-review-2026-11-03`) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
|
||||
> 경로 `src/presentation/`. 연결 확인: 참조 기능 폼 페이지(`src/features/reference-feature/presentation/`), 생성기 쓰기 슬라이스 템플릿(`scripts/create-feature-write-slice.ts`), 라우트 충돌 검사(`src/apps/deployable-app-module.ts`), Envelope 판정 일부(`src/adapters/http/backend-envelope.ts`)
|
||||
> 깊게 본 관점 4, 5, 8, 14, 15, 23, 24
|
||||
> 렌즈: 선언한 업무 거절 뒤의 폼(이유·포커스·다시 저장), 결과 불명 화면의 재전송 버튼(키 없음/KEYED), 1103/08-02~08-05 수정, 15-01 수정의 플랫폼 구성 화면
|
||||
> **영역 판정(35.8): 조건부 사용 가능.** 셸, 디자인 시스템, 읽기 화면, 필드 검증 400을 받는 폼, `refusedBeforeWrite`를 선언한 짝 백엔드 쓰기 폼은 쓸 수 있다. 조건: 기능이 업무 거절 code를 모두 선언한다. 선언하지 않은 code는 지금도 막다른 길이다(2절 1103/08-01). 거절 이유를 사용자 말로 보이려면 페이지가 따로 만들어야 한다.
|
||||
|
||||
## 0. 결론
|
||||
|
||||
- **지난 라운드 08 발견 중 4건(1103/08-02~08-05)은 고쳐졌다.** 각 수정에 테스트가 붙었고, 수정을 되돌리는 변이를 넣으면 그 테스트가 기대한 이유로 실패한다(08-R3, 08-R5~08-R7, 6절).
|
||||
- **1103/08-01(= 03-01) 폼 쪽은 일부만 고쳐졌다.** `refusedBeforeWrite`에 적은 code는 이제 결과 불명이 아니다. 값을 고치면 저장 버튼이 켜져 있고 새 키로 저장된다(08-R1 A1~A4: 두 번째 요청 키 `key-2`). 생성 기능은 이름 거절을 필드 옆에 보인다. 남은 것은 둘이다. (1) 거절 이유가 사용자 말로 안 보인다. 선언한 400은 "요청을 처리할 수 없습니다." + "지원 정보 확인", 409는 "다른 변경과 충돌했습니다."다. 기능이 자기 거절 문구를 붙일 자리가 없다. (2) 선언하지 않은 code는 지난 라운드와 같은 막다른 길이다. KEYED면 `500 IDEMPOTENCY_RECOVERY_REQUIRED` 뒤에도 재전송 버튼이 남아 같은 키로 끝없이 다시 보낸다(08-R1 A5: 3회).
|
||||
- **0929/03-03 화면 쪽은 고쳐졌다.** 결과 불명 화면은 키 없는 쓰기에 "같은 요청으로 다시 보내기"를 그리지 않는다. KEYED에는 그대로 그리고, 3엔진에서 같은 키로 다시 보낸다(08-R2 B2). 코디네이터와 화면이 같은 판정(`canResend`)을 쓴다. 키 조건을 지우면 테스트가 실패한다(03-R07 = 08-R4).
|
||||
- **15-01 수정(플랫폼 구성 화면) 쪽 화면 결함은 없다.** 제목과 선언 정보가 먼저 그려지고, 실행부 표만 `Suspense` 뒤에서 기다린다. 로딩 자리는 이름 있는 `aria-busy` 영역이다. 청크 실패는 그 라우트의 청크 복구 경계로 간다.
|
||||
- **새 발견 4건, 모두 Low·P3.** 복구 버튼을 키보드로 누른 뒤 포커스가 `body`로 떨어진다(08-01, 3엔진 확인). 생성 기능 폼은 "변경됨으로 확인" 뒤 아무것도 보이지 않고 입력을 비운다(08-02). 홈 시작 링크가 런타임에 꺼진 기능을 가리킨다(08-03, `b96d61d8`이 만듦, 확인). 저장 버튼이 다른 저장이 진행 중일 때 켜져 있지만 눌러도 반응이 없다(08-04, `2d5d41f8`이 만듦, 확인).
|
||||
- **약해진 검사는 없다**(2.1절). Critical·High·Medium 없음.
|
||||
|
||||
## 1. 범위 (36.1)
|
||||
|
||||
| 항목 | 기록 |
|
||||
|---|---|
|
||||
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` |
|
||||
| 커밋·작업 상태·확인 시점 | `8a44226`(`fix/maturity-review-2026-11-03`, 같은 커밋이 `fix/ui-design-audit-2026-11-01`·PR #4). 노트북 worktree `happy-easley-233d07`에서 읽기만 했다. 미추적 `AGENTS.md`는 무시했다. 2026-11-05 |
|
||||
| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음. 짝 백엔드 `clean-architecture-backend-template` `45d2a478`(`config/contracts/backend-contract-pin.json`의 pin) |
|
||||
| 필수 요구와 규모·운영 목표 | `PRODUCT.md`: WCAG 2.2 AA, 한국어 기본 + 영어. 짝 백엔드 Envelope 계약(계약 문서 6.1절). 화면 규모 목표 없음 |
|
||||
| 읽은 코드·구성 범위 | `src/presentation/forms/` 전부, `components/async-surface.tsx`·`state-surfaces.tsx`, `templates/page-templates.tsx`, `adapters/query/application-query.ts`(250-280, 330-380, 560-850행), `examples/platform-overview-page.tsx` 전부, `pages/home-page.tsx`, `layouts/app-shell.tsx`(190-215행), `routes/app-router.tsx`(340-420, 500-625행)·`route-runtime.tsx`, `boundaries/chunk-recovery-boundary.tsx`, `providers/session-provider.tsx`, `i18n/catalog.ts`·`message-contract.ts` 일부, `design-system/primitives/button.tsx`. 연결: `reference-resource-form-page.tsx`, `use-reference-failure-action.ts`, `create-feature-write-slice.ts`(280-330, 385-410, 585-990행), `deployable-app-module.ts`(50-140행), `backend-envelope.ts`(90-400행), `http-execution-v3.ts`(1690-1790행), `contracts/errors.ts`(1-260행), `mutation-intent.ts`, `browser-mutation-intent-factory.ts`, 매뉴얼 01·02 해당 절, VD-04. `git diff e40684b..8a44226 -- src/presentation tests/component tests/features tests/e2e/reference-save.spec.ts tests/architecture/context-route-roots.test.ts` |
|
||||
| 수행한 테스트·실험 | 직접 실행 0건. 오케스트레이터 배치 7건(6절): 08-R1 폼·홈 probe(jsdom), 08-R2 포커스 probe(Playwright 3엔진), 08-R3·08-R5~08-R7 변이 4종, 08-R4는 같은 변이인 03-R07로 대신했다. 모든 항목의 restore가 clean이었다. 게이트는 오케스트레이터 결과를 읽었다(아래) |
|
||||
| 확인하지 못한 범위·이유 | 5절 |
|
||||
| 이전 리뷰와 비교 가능한 범위 | `2026-11-03-maturity-review/08-presentation.md`의 08-01~08-05와 그 문서 2절의 "남음" 이월 항목, README §12·§13·§14.4. README §14.4는 주장으로만 읽었다. 지난 실행 결과는 증거로 쓰지 않았다 |
|
||||
|
||||
게이트(오케스트레이터, `8a44226`). 로컬 env(`desktop:/tmp/claude-gates/r4/gates/summary.txt`): `check:architecture`·`check:types`·`lint`·`test:contract`·`test:runtime-schema`·`check:adapter-inventory`·`check:ci` rc=0, `test:unit` 194 files / 2,883 tests, `test:component` 40 / 270, `test:integration` 11 / 189 통과. `verify:documentation`은 rc=1이다(짝 백엔드 문서 경로 3개, 영역 14 소관). merge 단계(CI=true, `merge-48/summary.txt`): FE-GATE-001~012·020 rc=0, FE-GATE-013 rc=1(security, 영역 13 소관). 이 영역 근거로 쓴 것: `test_component.log`에서 `form-foundation` 31, `async-surface` 34, `application-mutation-admission` 17, `starter-platform-overview-page` 10, `starter-platform-overview-route` 1, `layout-landmarks` 4 모두 ✓. snapshot `artifacts/tests/coverage.xml`(FE-GATE-005)에서 `reference-page.test`·`context-route-roots` 48건 실패 0. FE-GATE-008 로그에서 `reference-save.spec.ts` 5건 × 3엔진 통과(포커스 2건 포함). FE-GATE-012: 초기 JS 202,973 / 204,800 gzip B, 26 / 32 파일, PASS.
|
||||
|
||||
## 2. 지난 발견 재확인
|
||||
|
||||
줄 번호는 `8a44226` 기준이다. 08-Rk는 6절의 배치 실험 ID다.
|
||||
|
||||
| 지난 ID | 내용 | 상태 | 근거 |
|
||||
|---|---|---|---|
|
||||
| 1103/08-01 (= 03-01, 폼 쪽) | 짝 백엔드의 업무 규칙 거절이 결과 불명이 되어, 거절 이유가 안 보이고 값을 고쳐 다시 저장할 수 없다 | **일부** | **고쳐진 것.** operation이 `commandEffect.refusedBeforeWrite`에 적은 code의 400·409·422는 `NOT_APPLIED`다(`backend-envelope.ts:317-327`, `:340-351`, `http-execution-v3.ts:1722-1737`). 폼은 결과 불명으로 붙들지 않는다. 값을 고치면 저장 버튼이 켜져 있고 새 키로 저장된다(`form-foundation.test.tsx` "saves the corrected value after a declared pre-write refusal, with a new key", 08-R1 A1~A4: 두 요청의 키 `key-1` → `key-2`, 결과 "저장했습니다."). 생성기는 `<BASE>_INVALID`를 선언하고(`create-feature-write-slice.ts:306`) `mapProblem`으로 name 필드 오류로 바꾼다(`:397-404`). 그래서 생성 기능 폼은 "올바른 값을 입력해 주세요."를 필드 옆에 보이고 첫 오류 필드로 포커스를 옮긴다(08-R1 A4: 오류 요약 "새 항목 이름: 올바른 값을 입력해 주세요.", 포커스는 이름 입력란). **남은 것 (1) 이유 문구.** 선언한 409는 kind `CONFLICT`라 "다른 변경과 충돌했습니다. 입력은 유지되었으니 최신 상태를 확인해 주세요."다(`use-app-form.ts:244-248`, `catalog.ts:153-154`). 선언한 400은 `UNKNOWN_CLIENT_FAILURE`·`action: "contact-support"`라 "요청을 처리할 수 없습니다." + "지원 정보 확인"이다(`backend-envelope.ts:386-392`, `errors.ts:79-83`, `use-app-form.ts:260-267`). 고칠 수 있는 입력인데 지원 문의로 보낸다. `mapProblem`으로 필드 오류를 만들어도 문구는 플랫폼 표(`form-contracts.ts:33-64`)에서 issue code로만 고른다. 표에 없는 `DUPLICATE`는 "입력값을 확인해 주세요."다(08-R1 A3). 기능이 `*_ALREADY_EXISTS` 같은 자기 거절 문구를 붙일 자리가 없다. `conflict` 결과에서는 `form.failure`가 `null`이라(`use-app-form.ts:385`, `:411-416`) 페이지가 code를 읽어 따로 그릴 수도 없다. 매뉴얼은 "거절 이유를 필드 옆에 보이려면 `mapProblem`"이라고만 적는다(`docs/manual/02-decision-tables.md:185`). VD-04 결정 5는 "409 conflict는 validation으로 바꾸지 않는다"(`VD-04-native-form-facade.md:26`)여서 409 업무 거절을 어느 쪽으로 보일지 문서끼리 갈린다. **(2) 선언하지 않은 code.** 지난 라운드와 같다. 결과 불명, 저장 꺼짐, "변경됨으로 확인"이 저장되지 않은 요청을 "저장했습니다."로 바꾼다. KEYED면 재전송이 `500 IDEMPOTENCY_RECOVERY_REQUIRED`를 받아도 결과 불명이 이어지고 재전송 버튼이 계속 남는다(08-R1 A5: 키 `key-1` 3회, 세 번 모두 같은 화면). `canResend`는 응답 원인을 보지 않는다(`application-query.ts:836-845`). 백엔드 표 주석은 이 응답을 "스스로 다시 보내지 않는다, 사용자가 데이터를 확인한다"로 적는다(`backend-envelope.ts:261-266`). 남은 부분의 심각도는 Medium·P2로 본다. 저장이 막히는 High 조건은 선언한 code에서 풀렸다. 판정 규칙은 영역 03 소관이다 |
|
||||
| 1103/08-02 | 키보드로 저장했다가 필드 오류가 아닌 실패를 받으면 포커스가 `body`로 떨어진다 | 고쳐짐 | 폼이 렌더 뒤 feedback 자리로 포커스를 옮긴다(`use-app-form.ts:91-101`). 표시는 필드 오류·성공이 아닌 분기 5곳이다(`:230`, `:236`, `:245`, `:253`, `:262`). 템플릿이 그 자리를 `id` + `tabIndex=-1`로 만든다(`page-templates.tsx:73-82`). 참조 폼은 `feedbackId`를 넘기고 저장 중에 `disabled` 대신 `pending`을 쓴다(`reference-resource-form-page.tsx:71`, `:124-131`). 생성기 템플릿도 같다(`create-feature-write-slice.ts:674`, `:693-698`). 테스트: `reference-page.test.tsx:470-517`(결과 불명, 429), `reference-save.spec.ts:120-132`, `:166-173`. 변이(포커스 제거)는 이 두 행으로 실패한다(08-R3). FE-GATE-008에서 `reference-save.spec.ts` 포커스 2건이 3엔진 통과. 완료 기준(저장 뒤 포커스가 실패 상태 안, Tab 한 번에 복구 버튼)을 충족한다. 복구 버튼을 누른 **뒤**의 포커스는 새 발견 08-01이다 |
|
||||
| 1103/08-03 | 폼 문구 표가 `Object.prototype` 이름까지 찾는다 | 고쳐짐 | `form-contracts.ts:74-80` `Object.hasOwn`. `form-foundation.test.tsx:677-685`가 `constructor`·`toString`·`__proto__`·`hasOwnProperty`를 본다. 변이(`!== undefined`)는 내장 이름 4행으로 실패한다(08-R5, "요청한 문구를 표시할 수 없습니다.") |
|
||||
| 1103/08-04 | 대소문자·끝 슬래시만 다른 기능 라우트를 놓친다 | 고쳐짐 | `deployable-app-module.ts:115-121` 모양 키를 소문자로 바꾸고 끝 슬래시를 지운다. `context-route-roots.test.ts:226-251` 두 행. 변이(`.toLowerCase()` 제거)는 대소문자 행으로 실패한다(08-R6). `/a/new`·`/a/:id` 허용 행은 그대로 통과한다 |
|
||||
| 1103/08-05 | 422 `IDEMPOTENT_REQUEST_MISMATCH`를 입력 오류로 보인다 | 고쳐짐 | 422는 필드 목록이 있을 때만 필드 검증이다(`backend-envelope.ts:216-225`). 없으면 `UNKNOWN_CLIENT_FAILURE`다(`:386-392`). 폼은 `unavailable` + 지원 참조다. `form-foundation.test.tsx:346-` "shows a paired backend 422 IDEMPOTENT_REQUEST_MISMATCH as a status". 변이(422 → 항상 필드)는 이 행으로 실패한다(08-R7) |
|
||||
| 0929/03-03 (화면 쪽, 판정은 영역 03) | 결과 불명 화면의 재전송이 키 없는 쓰기에도 열린다 | 고쳐짐 | `canResend`가 결과 불명·키 있음·조정 중 아님을 함께 본다(`application-query.ts:836-845`). `resendUnknownEffect`도 같은 함수를 쓴다(`:800-804`). 같은 답을 `state.unknownEffectResendable`로 넘기고(`:807-820`) 화면은 `false`면 버튼을 그리지 않는다(`async-surface.tsx:225-231`). 키는 `requiresIdempotencyKey`일 때만 생기고(`browser-mutation-intent-factory.ts:38-45`) 없는 키는 칸째 빠진다(`mutation-intent.ts:82-84`). 그래서 `idempotencyKey !== undefined` 판정이 맞다. KEYED는 그대로 보인다(`application-mutation-admission.test.tsx` "offers the same-key resend…", 08-R2 B2: 3엔진 모두 같은 키로 재전송). 키 없는 생성 기능의 테스트가 "재전송 버튼 없음"을 본다(`create-feature-write-slice.ts:752-769`). 키 조건을 지우면 "offers no resend for an unknown request that carries no key"가 실패한다(03-R07, 08-R4와 같은 변이) |
|
||||
| 0929/08-01 | 제품이 지원 locale을 선언할 곳이 없다 | 남음 | `message-contract.ts:8-13` 고정 목록, `app-shell.tsx:86-89` 선택지에 `en-XA`·`ar-EG`. 1103 README §14.4가 "큰 것은 남겼다"고 적은 항목이다 |
|
||||
| 0929/08-08 | 로그인 복귀 주소가 라우터 기준 경로다 | 남음 | `session-provider.tsx:88`, `:99` `beginSignIn(pathname + search + hash)`. `useLocation()`은 basename을 뺀 값이다(basename은 `runtime-application.tsx:52`). `use-reference-failure-action.ts:26`도 같다. `beginSignIn(returnTo?)`(`auth-session-port.ts:38`)은 어느 기준인지 적지 않는다 |
|
||||
| 0929/08-06, 0929/08-07 | 라우트 제목 세 곳, 제품 폰트 자리 | 판정 안 함 | 지난 라운드와 같이 렌즈 밖이다. 08-06은 1103/16-06(라우트 계약 `title`을 화면이 읽지 않음, §14.4 일부)과 겹친다 |
|
||||
| 1103 3.6절 관찰 셋 | 지원 참조가 재전송마다 바뀜, `role="status"` 안의 버튼, 레이아웃 `<main tabIndex>` 미검사 | 그대로(발견 아님) | `use-app-form.ts:392-395`, `async-surface.tsx:197-239`, `layout-landmarks.test.tsx`에 `tabIndex` 단언 0건 |
|
||||
|
||||
### 2.1 수정이 검사를 약하게 했는가
|
||||
|
||||
`git diff e40684b..8a44226`로 이 영역 수정 9커밋(`4282a541`, `2d5d41f8`, `2017ef76`, `d7c6cb4f`, `d549ceb3`, `b96d61d8`, 병합 3)과 대상 테스트를 봤다. **약해진 검사는 없다.**
|
||||
|
||||
| 바뀐 검사 | 판단 |
|
||||
|---|---|
|
||||
| `reference-page.test.tsx:334-339` "deduplicates create": `toBeDisabled()` → `aria-busy="true"` + 포커스 유지 | 약해지지 않았다. `toHaveBeenCalledOnce()`는 그대로다. 버튼이 꺼지지 않으므로 두 번째 클릭이 실제로 폼까지 가고, 폼의 중복 차단(`use-app-form.ts:324`)을 직접 검사하게 됐다 |
|
||||
| `starter-pages.test.tsx`에서 예제 화면 테스트 2건 삭제 | 옮겨졌다. `tests/features/platform-examples-feature/example-pages.test.tsx:51-79`에 같은 단언이 있다(`b96d61d8`) |
|
||||
| `starter-platform-overview-page.test.tsx` 전부 `await act` + `Promise.resolve(...)` | 단언은 같다. 대기 중 경로는 새 `starter-platform-overview-route.test.tsx`가 본다. load 실패 경로는 전에도 지금도 테스트가 없다(5절) |
|
||||
| `form-foundation.test.tsx` "keeps the default copy" 1건 → `it.each` 5건 | 넓어졌다(`:677-685`) |
|
||||
| `application-mutation-admission.test.tsx`, `async-surface.test.tsx`, `context-route-roots.test.ts` | 더하기만 했다 |
|
||||
|
||||
## 3. 이번 발견 (36.3)
|
||||
|
||||
**새 발견 4건.** 심각도: Low 4(Critical·High·Medium 0). 우선순위: P3 4. 성격: 확인된 결함 4(코드 + 실행으로 확인 3건, 코드로만 확인 1건(08-02)).
|
||||
|
||||
### 3.0 짝 백엔드 Envelope 쓰기가 거절될 때 폼이 보이는 것
|
||||
|
||||
코드 읽기와 08-R1(A1~A5, 참조 폼 실제 페이지·코디네이터, gateway 결과만 주입)로 채웠다. 생성기 행은 코드 읽기만이다. 참조 폼 페이지의 배선(`reference-resource-form-page.tsx:51-183`)과 생성기 템플릿(`create-feature-write-slice.ts:584-721`)을 기준으로 했다.
|
||||
|
||||
| 서버 답 | 판정 | 폼 결과 | 사용자가 보는 것 | 포커스 | 다시 저장 |
|
||||
|---|---|---|---|---|---|
|
||||
| 선언한 409 업무 code(예: `POSTER_ALREADY_EXISTS`) | `NOT_APPLIED`, kind `CONFLICT`(`errors.ts:284-293`) | `conflict`(`use-app-form.ts:244-248`) | 오류 요약 "다른 변경과 충돌했습니다. 입력은 유지되었으니 최신 상태를 확인해 주세요.", feedback "충돌을 해결한 뒤 다시 제출할 수 있습니다." | feedback 자리 | 됨, 새 키 |
|
||||
| 선언한 400 업무 code(예: `WORKLOG_INVALID`), `mapProblem` 없음 | `NOT_APPLIED`, `UNKNOWN_CLIENT_FAILURE`·`contact-support` | `unavailable`(`:260-267`) | "요청을 처리할 수 없습니다." + "지원 정보 확인"(참조 폼은 지원 상태 화면으로 이동, `use-reference-failure-action.ts:36-41`) + 지원 참조 | feedback 자리 | 됨, 새 키(`form-foundation.test.tsx` "saves the corrected value after a declared pre-write refusal") |
|
||||
| 선언한 code + `mapProblem`이 필드 목록, issue code가 표 밖(예: `DUPLICATE`) | `NOT_APPLIED`, `VALIDATION_REJECTED` | `validation-error` | 필드 옆 "입력값을 확인해 주세요." | 첫 오류 필드 | 됨 |
|
||||
| 생성기 기본(`<BASE>_INVALID` → issue `INVALID`) | 같음 | `validation-error` | 필드 옆 "올바른 값을 입력해 주세요." | 첫 오류 필드 | 됨 |
|
||||
| 선언하지 않은 400·409·422 | `MAYBE_APPLIED` | `effect-unknown` | "변경 결과를 확인할 수 없습니다." + "변경됨으로 확인"(+ KEYED면 "같은 요청으로 다시 보내기") + 지원 참조 | feedback 자리 | 안 됨(1103/08-01 남은 부분) |
|
||||
| 위 KEYED 재전송에 `500 IDEMPOTENCY_RECOVERY_REQUIRED` | `MAYBE_APPLIED` | `effect-unknown` | 같은 화면, 재전송 버튼 그대로 | feedback 자리 | 안 됨 |
|
||||
|
||||
공통: 담당·기한·상태는 `미정 · 미정 · 신규`, 재검증 결과는 `없음(신규)`이다.
|
||||
|
||||
### 08-01 실패 상태의 복구 버튼(변경됨으로 확인, 같은 요청으로 다시 보내기, 다시 시도)을 키보드로 누르면, 일이 끝난 뒤 그 버튼이 사라지면서 포커스가 `body`로 떨어진다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 1, 6, 10, 28 |
|
||||
| 근거 | 폼은 결과가 필드 오류도 성공도 아닌 실패일 때만 렌더 뒤 feedback 자리로 포커스를 옮긴다(`use-app-form.ts:91-101`, 표시는 `:230`, `:236`, `:245`, `:253`, `:262`). 성공 쪽 `settleSuccessfulValues`(`:176-195`)는 표시하지 않는다. 그 길을 타는 것이 "변경됨으로 확인"(`settleApplied`, `:197-201`), 재전송 성공(`resendUnknown` → `applyOutcome` → `:213-215`), "다시 시도" 성공(`submitForm`)이다. **참조 폼, 확인.** 누르면 코디네이터가 그 시도를 `RECONCILING`으로 바꾸고(`application-query.ts:761`) 화면 표시가 `mutation-pending`이 된다(`:815-819`). 그 사이 feedback은 `null`이다. `form.failure`는 상태 결과에만 있고(`use-app-form.ts:385`) `form.result`는 아직 `effect-unknown`이라 어느 가지에도 들지 않는다(`reference-resource-form-page.tsx:141-183`). feedback 자리(`page-templates.tsx:73-82`)가 통째로 빠지고 포커스가 있던 버튼도 빠진다. 끝나면 "저장했습니다."가 새 `<p role="status">`로 그려진다(`:178-179`). **재전송·다시 시도.** 성공하면 그 버튼을 그리던 `AsyncSurface`·`FormFailureStatus`가 `<p role="status">`로 바뀐다. **생성 폼.** 재전송 성공은 상세로 이동해 라우터가 제목으로 포커스를 옮긴다(`create-feature-write-slice.ts:629-647`, `:718`). 확인 뒤에는 feedback이 `null`이다(`:704-721`, 08-02). 브라우저는 포커스된 요소가 문서에서 빠지면 포커스를 `body`로 돌린다. 1103/08-02 테스트는 저장 **직후**의 포커스만 본다(`reference-page.test.tsx:470-517`, `reference-save.spec.ts:120-132`, `:166-173`). **실행.** 08-R2(빌드 preview, 3엔진): 키보드로 저장 → feedback 포커스 → Tab → 복구 버튼 → Enter → "저장했습니다." 뒤 `document.activeElement`가 chromium·firefox·webkit × 확인·재전송·다시 시도 9건 모두 `body`. 다음 Tab은 9건 모두 이름 입력란이었다. 08-R1(jsdom) B1~B3도 `BODY` |
|
||||
| 발생 조건 | 키보드·스크린 리더 사용자가 실패 상태 안의 복구 버튼을 쓰고, 그 결과가 성공 또는 확인일 때. 1103/08-02 수정 뒤에는 저장 직후 Tab 한 번에 이 버튼에 닿으므로 이 경로를 더 자주 탄다 |
|
||||
| 영향 | 저장이 끝난 뒤 보이는 포커스가 사라진다. 다음 Tab은 세 엔진 모두 이름 입력란으로 가서(08-R2) 키보드 이동은 이어진다. 1103/08-02 때(다음 Tab이 문서 맨 앞)보다 피해가 작다. 스크린 리더가 `body` 포커스에서 읽는 위치는 미확인이다. "저장했습니다."는 `role="status"`라 발표될 수는 있다 |
|
||||
| 심각도·우선순위 | Low · P3 — 기능과 키보드 이동은 남는다. 모든 폼이 참조 폼·생성기 배선을 복사하고 `PRODUCT.md`가 WCAG 2.2 AA를 요구하지만, 다음 Tab이 제자리 근처로 가서 1103/08-02(Low·P2)보다 한 단계 낮게 둔다 |
|
||||
| 확실성과 남은 가정 | 3엔진 실행으로 확인(E3). 실제 스크린 리더 발표는 미확인 |
|
||||
| 결정의 근거 | 적용 제외 — 이미 있는 feedback 포커스 장치를 복구 뒤 전이에도 쓰지 않은 누락이다 |
|
||||
| 이해 비용 | 필요한 범위만 |
|
||||
| 최소 개선 방향 | (1) 직전 결과가 상태 결과나 `effect-unknown`이었다가 성공·확인으로 바뀌면 `focusFeedbackRef`를 세운다(`useAppForm` 안, 페이지마다 복사하지 않음). (2) 참조 폼은 확인 중(`mutation-pending`)에도 feedback 자리를 비우지 않는다(예: `async.mutationPending` 문구). 08-04와 함께 고칠 수 있다 |
|
||||
| 대안 비교 | 적용 제외 |
|
||||
| 단순화의 보존 조건 | 처음 저장이 그냥 성공할 때는 포커스를 옮기지 않는다. 1103/08-02의 실패 뒤 포커스와 Tab 한 번 규칙 |
|
||||
| 비용·부작용 | `use-app-form.ts` 몇 줄, 참조 페이지 한 가지, e2e 3건 |
|
||||
| 재검토 조건 | 적용 제외 |
|
||||
| 완료 기준 | 08-R2의 세 경우에서 일이 끝난 뒤 포커스가 feedback 자리 안에 있다 |
|
||||
| 검증 방법 | `tests/e2e/reference-save.spec.ts`에 08-R2 probe의 세 test를 넣는다 |
|
||||
|
||||
### 08-02 생성 기능 폼은 "변경됨으로 확인" 뒤 아무것도 보이지 않은 채 입력을 비운다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함 (생성기 템플릿 코드로 확정. 생성한 기능으로 실행하지 않았다) |
|
||||
| 관련 관점 | 24, 23, 20, 28 |
|
||||
| 근거 | 생성기 템플릿의 feedback은 `form.failure`와 결과 불명 두 가지뿐이다(`create-feature-write-slice.ts:703-721`). 저장 성공은 상세 화면으로 이동해서 알린다(`:629-647`). "변경됨으로 확인"은 `reconcileUnknownEffect(...).then(form.settleApplied)`이고 이동하지 않는다(`:714`). `settleApplied` → `settleSuccessfulValues`가 결과를 `success`로 바꾸고 기본값 `resetOnSuccess: true`로 입력을 비운다(`use-app-form.ts:54`, `:176-195`). 그래서 결과 불명 화면이 사라진 뒤 빈 폼만 남는다. 참조 폼은 같은 경우 "저장했습니다."를 보인다(`reference-resource-form-page.tsx:178-179`). 생성 기능 테스트는 결과 불명에서 재전송 버튼이 없다는 것까지만 본다(`create-feature-write-slice.ts:752-769`) |
|
||||
| 발생 조건 | 생성 기능(짝 백엔드 기본은 `NEVER`)의 저장 응답을 잃어 결과 불명 → 사용자가 "변경됨으로 확인". `NEVER`에서는 이것이 화면 안의 유일한 행동이다(재전송 없음, 0929/03-03 수정) |
|
||||
| 영향 | 사용자는 확인이 받아들여졌는지, 항목이 저장됐는지 화면에서 알 수 없다. 입력이 지워졌으므로 다시 입력해 저장하면 키 없는 생성이 한 번 더 나간다(실제로 저장됐던 경우 중복). 포커스도 `body`로 간다(08-01) |
|
||||
| 심각도·우선순위 | Low · P3 — 응답을 잃는 드문 경로다. 중복은 사용자가 다시 입력할 때만 생기고 목록에서 보인다 |
|
||||
| 확실성과 남은 가정 | 템플릿 문자열을 읽었다. 생성 결과 파일과 실행은 확인하지 않았다. 파일은 `scripts/`라 영역 16과 겹칠 수 있다. 합칠 때 하나로 센다 |
|
||||
| 결정의 근거 | 적용 제외 — 참조 폼에 있는 가지가 생성기 템플릿에 빠진 누락이다 |
|
||||
| 이해 비용 | 필요한 범위만 |
|
||||
| 최소 개선 방향 | 확인 뒤 목록으로 이동한다(목록 쿼리는 `reconcileUnknownEffect`가 이미 무효화한다). 또는 참조 폼처럼 `form.result === "success"` 가지에 확인 문구를 둔다 |
|
||||
| 대안 비교 | 적용 제외 |
|
||||
| 단순화의 보존 조건 | 저장 성공 뒤 상세 이동, 키 없는 결과 불명에 재전송 없음 |
|
||||
| 비용·부작용 | 템플릿 몇 줄, 생성 기능 테스트 한 행 |
|
||||
| 재검토 조건 | 적용 제외 |
|
||||
| 완료 기준 | 생성 기능 테스트에서 결과 불명 → "변경됨으로 확인" 뒤 확인 문구가 보이거나 목록 화면이다 |
|
||||
| 검증 방법 | `renderCreatePageTest`(`create-feature-write-slice.ts:731-`)에 한 행. `test:feature-scaffold`가 생성 결과로 돈다 |
|
||||
|
||||
### 08-03 홈 화면의 시작 링크가 런타임 설정으로 꺼진 기능의 라우트를 가리킨다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 23, 1, 10 |
|
||||
| 근거 | `home-page.tsx:21-23`의 `STARTER_ROUTES`는 모듈을 불러올 때 `NAVIGATION_ROUTES`에서 `APP_HOME`을 빼고 앞 3개를 고른다. 기능이 켜져 있는지는 보지 않는다. 셸 탐색은 같은 목록을 `runtime.isFeatureActive(owner)`로 거른다(`app-shell.tsx:196-202`, 주석 "A feature the runtime document disabled does not advertise itself"). 라우터는 꺼진 기능의 라우트에 사용 중지 화면을 그린다(`app-router.tsx:361-364`). 템플릿에서 시작 링크는 `EXAMPLES_PLATFORM`(순서 15, `contracts/routes.ts:44`), `EXAMPLES_UI`(20), `EXAMPLES_STATES`(30)이다(`platform-examples-contract.ts:16-39`). 뒤의 둘이 `platform-examples-feature`의 라우트다. 1103/09-04 수정(`b96d61d8`)이 예제 화면 셋을 끌 수 있는 기능으로 옮기면서 생겼다. 기능 끄기 테스트(`product-feature-switch.test.tsx`)는 셸 탐색과 직접 링크만 본다. **실행(08-R1 C, 실제 `AppRouter`).** `platform-examples-feature`를 `DISABLED_BY_CONFIG`로 두면 셸 탐색은 `/`, `/examples/platform`, `/examples/reference-resources`만 남는다. 홈 시작 링크는 켜져 있을 때와 같이 "플랫폼 구성 보기 → /examples/platform", "UI 구성요소 보기 → /examples/ui", "화면 상태 보기 → /examples/states"다. 둘째 링크를 누르면 `data-disabled-feature="platform-examples-feature"`, 제목 "현재 사용할 수 없는 기능입니다."다 |
|
||||
| 발생 조건 | 운영자가 런타임 설정으로 `platform-examples-feature`를 끈다. 또는 제품이 탐색 순서 앞쪽 기능을 런타임에 끈다. 빌드에서 뺀 기능은 해당 없다 |
|
||||
| 영향 | 홈의 주요 버튼 셋 중 둘이 사용 중지 화면으로 간다. 켜진 다른 기능은 그 자리에 오지 않는다 |
|
||||
| 심각도·우선순위 | Low · P3 — 화면에서 바로 보이고 데이터 영향이 없다. 홈은 제품이 바꾸는 시작 화면이다 |
|
||||
| 확실성과 남은 가정 | jsdom 실행으로 확인(E2). 브라우저에서는 돌리지 않았다 |
|
||||
| 결정의 근거 | 적용 제외 — 셸과 같은 조건을 홈이 빠뜨린 누락이다 |
|
||||
| 이해 비용 | 필요한 범위만 |
|
||||
| 최소 개선 방향 | 렌더 때 셸과 같은 조건으로 거른 뒤 앞 3개를 고른다. 셸과 홈이 같은 함수(예: "켜진 탐색 라우트")를 쓴다 |
|
||||
| 대안 비교 | 적용 제외 |
|
||||
| 단순화의 보존 조건 | 홈은 기능 라우트를 이름으로 부르지 않는다(`home-page.tsx:15-20` 주석, 1103/09-04) |
|
||||
| 비용·부작용 | 몇 줄, 테스트 한 행 |
|
||||
| 재검토 조건 | 적용 제외 |
|
||||
| 완료 기준 | 08-R1 C(disabled)에서 시작 링크에 꺼진 기능의 라우트가 없다 |
|
||||
| 검증 방법 | `product-feature-switch.test.tsx`에 홈 시작 링크 단언 한 행 |
|
||||
|
||||
### 08-04 다른 저장이 진행 중일 때 저장 버튼이 켜져 있지만, 눌러도 아무 일도 없고 아무것도 보이지 않는다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 1, 24, 6 |
|
||||
| 근거 | 1103/08-02 수정(`2d5d41f8`) 전에는 저장 버튼이 `disabled={form.pending || mutationBlocked}`였다. 지금은 `disabled={mutationEffectUnknown}`만이다(`reference-resource-form-page.tsx:124-131`. 생성기 템플릿도 같다, `create-feature-write-slice.ts:693-698`). `mutationBlocked`는 코디네이터의 `mutation-pending`도 포함하고(`reference-resource-form-page.tsx:52-55`) `onSubmit`은 그때 아무것도 하지 않고 돌아간다(`:62-68`). `mutation-pending`은 이 폼이 저장 중이 아닐 때도 생긴다. (1) 저장 중에 화면을 떠났다가 같은 세션에서 돌아온 경우. 저장 중에는 이탈 확인이 꺼지고(`:56`), 코디네이터 채널은 진행 중 시도가 있는 동안 남는다(`application-query.ts:914-918`). (2) "변경됨으로 확인"을 처리하는 동안(`RECONCILING`이 pending으로 표시, `:815-819`). 그동안 feedback에는 진행 표시가 없다(`reference-resource-form-page.tsx:141-183`). 같은 조건에서 취소·초기화 버튼은 꺼진다(`:117`, `:135`). **실행(08-R1 D).** 저장을 걸어 둔 채 "목록으로 돌아가기" → 다시 `/examples/reference-resources/new` → 새 이름 입력: 저장 버튼 켜짐(`disabled=false`, `aria-busy` 없음), 취소 꺼짐, feedback 없음. 저장을 누르면 요청 수는 1 그대로이고 화면 변화가 없다. 첫 저장이 끝난 뒤에도 그 클릭은 실행되지 않았고 아무것도 보이지 않았다 |
|
||||
| 발생 조건 | 위 (1)·(2). (1)은 저장이 끝나기 전(operation `totalDeadlineMs` 안)에 돌아와야 한다 |
|
||||
| 영향 | 사용자가 저장을 눌러도 반응이 없다. 진행 중 시도가 끝나면 다시 누를 수 있지만 눌렀던 저장은 실행되지 않는다(08-R1 D). 중복 제출은 여전히 막히므로 데이터 피해는 없다 |
|
||||
| 심각도·우선순위 | Low · P3 — 짧은 창에서만 생기고 스스로 풀린다 |
|
||||
| 확실성과 남은 가정 | (1)은 jsdom 실행으로 확인(E2). (2)는 코드 읽기다 |
|
||||
| 결정의 근거 | 적용 제외 — 1103/08-02 수정이 `disabled`를 `pending`으로 바꾸면서 다른 인스턴스의 진행 중 상태를 알리는 수단을 같이 지웠다 |
|
||||
| 이해 비용 | 필요한 범위만 |
|
||||
| 최소 개선 방향 | `mutation-pending`이고 이 폼이 저장 중이 아니면 feedback에 `async.mutationPending`("변경 사항을 저장하고 있습니다.")를 보인다. 또는 그때만 버튼을 끈다(`disabled={mutationEffectUnknown \|\| (mutationBlocked && !form.pending)}`). 포커스를 잃지 않게 하려면 앞쪽이다 |
|
||||
| 대안 비교 | 적용 제외 |
|
||||
| 단순화의 보존 조건 | 저장 중 포커스 유지(1103/08-02), 중복 제출 차단(`use-app-form.ts:324-325`) |
|
||||
| 비용·부작용 | 페이지·템플릿 몇 줄, 테스트 한 행 |
|
||||
| 재검토 조건 | 적용 제외 |
|
||||
| 완료 기준 | 08-R1 D에서 다시 마운트한 폼이 진행 중 문구를 보이거나 저장 버튼이 꺼져 있다 |
|
||||
| 검증 방법 | `reference-page.test.tsx`에 08-R1 D 행 |
|
||||
|
||||
### 3.5 발견으로 올리지 않은 관찰
|
||||
|
||||
- **15-01 수정의 플랫폼 구성 화면(화면 쪽).** 결함은 찾지 못했다. 제목·릴리스·라우트 표는 곧바로 그린다. 실행부가 필요한 두 곳만 `Suspense` 뒤에 있다(`platform-overview-page.tsx:468-480`, `:526-528`). 요약 칸은 대기 중 "확인 중"을 보이고 칸 수가 같아 자리가 바뀌지 않는다(`:470-478`). 표 자리는 이름 있는 `aria-busy` + `aria-live` 영역이다(`async-surface.tsx:15-37`). 제목 h1이 바로 있어 라우터의 제목 포커스가 그대로다(`starter-platform-overview-route.test.tsx`). 실행부 load는 렌더 중의 dynamic import지만 `ChunkRecoveryBoundary` 안이라 청크 실패는 reload-once 복구로, 그 밖의 실패(기능 사이 중복)는 라우트 경계로 간다(`app-router.tsx:379-397`, `chunk-recovery-boundary.tsx:56-88`). 실패한 load는 캐시에서 지워 다음 방문에 다시 시도한다(`platform-overview-page.tsx:646-658`). load 실패 경로를 보는 테스트는 없다(전에도 없었다). 요약 칸 묶음에는 릴리스 칸(`:422`)과 달리 `aria-live`가 없어 값이 바뀌어도 발표되지 않는다. 정적 화면이라 결함으로 보지 않았다.
|
||||
- **포커스를 받는 feedback 자리에 역할·이름이 없다**(`page-templates.tsx:73-82`). 안의 `role="status"`·`role="alert"`와 포커스 이동이 겹쳐 두 번 읽힐 수 있다. `2d5d41f8` 본문도 스크린 리더 확인을 하지 않았다고 적었다. 미검증(5절).
|
||||
- **라우트 모양 키**(1103/08-04 수정)는 끝 슬래시만 지운다. 가운데 `//`(`/shop//items`)는 React Router가 합치지만 키는 그대로다. 오타 두 번이 겹쳐야 생겨 올리지 않았다.
|
||||
- **지원 참조가 재전송마다 바뀐다**(`use-app-form.ts:392-395`). 지난 라운드 관찰 그대로다.
|
||||
- **반복 원인.** 이번 새 발견 4건 중 3건(08-01, 08-02, 08-04)은 같은 자리다. 폼 결과(`useAppForm`)와 코디네이터 상태(`useApplicationMutation`)를 페이지가 손으로 합치고, 참조 폼과 생성기 템플릿이 그 합치기를 따로 복사한다. 지난 라운드 5.3절의 (B)(`useAppForm`이 코디네이터 상태를 받아 결과를 하나로 낸다)가 이 셋과 1103/08-01 남은 부분 일부를 함께 줄인다.
|
||||
|
||||
## 4. 28개 관점 판정 (36.2)
|
||||
|
||||
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역. 굵은 번호가 깊게 본 관점이다.
|
||||
|
||||
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | 코드 성숙도 | 적용 | M3 / M3 | E3 | P — 1103/08-02~08-05 고쳐짐(변이 4종 + 03-R07 모두 잡힘). 복구 버튼 뒤 포커스 유실(08-01, 3엔진), 생성 폼 확인 뒤 무안내(08-02), 홈 시작 링크가 꺼진 기능을 가리킴(08-03), 다른 저장 진행 중 저장 버튼 무반응(08-04) |
|
||||
| 2 | 구조적 성숙도 | 적용 | M3 / M3 | E2 | O — `check:architecture` 통과(오케스트레이터). presentation이 HTTP를 직접 모른다. 포커스 이동이 페이지가 아니라 `useAppForm`·`FormPage`에 있다 |
|
||||
| 3 | 변경 용이성 | 적용 | M3 / M1 | E1 | P — locale 목록이 셸에 박혀 있다(0929/08-01 남음) |
|
||||
| **4** | 인지 부하 | 적용 | — | E2 | P — "선언한 거절 뒤 화면에 무엇이 보이나"를 알려면 계약 칸(`refusedBeforeWrite`) → status별 kind(`backend-envelope.ts:386-392`) → kind별 action(`errors.ts`) → 폼 분기 순서(`use-app-form.ts:217-267`) → 플랫폼 문구 표(`form-contracts.ts:33-64`) → 페이지 feedback 분기를 읽어야 한다. 매뉴얼은 저장이 풀린다는 것만 적고 무엇이 보이는지는 적지 않는다(1103/08-01 남은 부분) |
|
||||
| **5** | 위험 가시성 | 적용 | M2 / M2 | E2 | P — 선언 목록이 틀리면 중복 위험이 생긴다는 것은 매뉴얼과 조립 검사에 있다(`02-decision-tables.md:183`). 화면은 선언한 400을 "지원 정보 확인"으로 보내 사용자가 거절 이유를 알 수 없다(1103/08-01 남은 부분) |
|
||||
| 6 | 실패 성숙도 | 적용 | M3 / M3 | E2 | P — 선언한 거절은 다시 저장된다(08-R1 A1~A4). 선언하지 않은 code와 `RECOVERY_REQUIRED` 뒤 재전송은 막다른 길이다(1103/08-01 남은 부분, 08-R1 A5) |
|
||||
| 7 | 운영 성숙도 | > | — | — | 영역 09·13 |
|
||||
| **8** | 디버깅 가능성 | 적용 | M3 / M3 | E2 | P — 상태 실패와 결과 불명에 지원 참조가 있다. 422 불일치가 상태와 참조로 보인다(1103/08-05 고쳐짐, `form-foundation.test.tsx:346-`). `conflict` 결과에는 참조가 없다(`use-app-form.ts:392-395`). 참조가 재전송마다 바뀐다(관찰, 그대로) |
|
||||
| 9 | 유지보수 성숙도 | 적용 | — | E1 | P — `application-query.ts` 1,004줄(지난 981줄). harness용 LEGACY 분기가 그대로다 |
|
||||
| 10 | 테스트 성숙도 | 적용 | M3 / M3 | E2 | P — 이번 수정 다섯 개는 모두 테스트에 잡힌다(08-R3, 08-R5~08-R7, 03-R07). 복구 버튼 뒤 포커스(08-01), 홈 시작 링크와 기능 끄기(08-03), 생성 폼 확인 경로(08-02), 다시 마운트한 폼(08-04)을 보는 테스트가 없다. 플랫폼 구성 화면의 load 실패 경로도 테스트가 없다 |
|
||||
| 11 | 데이터 성숙도 | - | — | — | presentation은 저장을 소유하지 않는다 |
|
||||
| 12 | 동시성 성숙도 | 적용 | M3 / M3 | E2 | P — 중복 제출은 폼(`use-app-form.ts:324-325`)과 `REJECT_WHILE_ACTIVE`가 막는다. 결과 불명 재전송은 같은 키, 키 없는 쓰기는 재전송 없음(0929/03-03 고쳐짐). 다른 인스턴스의 저장이 진행 중일 때 저장 버튼이 켜진 채 조용히 거절한다(08-04) |
|
||||
| 13 | 확장성 | > | — | — | 영역 09·15·16 |
|
||||
| **14** | 성능 성숙도 | 적용 | M3 / M3 | E2 | O — FE-GATE-012 PASS, 초기 JS 202,973 / 204,800 gzip B, 26 / 32 파일(오케스트레이터). 여유 1,827 B. 이 영역 수정은 작다(`useEffect` 하나, 홈 링크 계산). 플랫폼 구성 화면은 제목·선언 정보를 먼저 그리고 실행부 표만 기다린다(`platform-overview-page.tsx:468-480`, `:526-528`, `:646-663`). 측정(FE-GATE-026)은 영역 15 |
|
||||
| **15** | 보안 성숙도 | 적용 | M3 / M3 | E2 | P — 백엔드 message를 그리지 않는다(`form-foundation.test.tsx` "raw backend copy", 422 행). 이번 수정에 새 입력 경로는 없다. 로그인 복귀 주소(0929/08-08) 남음 |
|
||||
| 16 | 의존성 성숙도 | > | — | — | 영역 13 |
|
||||
| 17 | API / Contract 성숙도 | 적용 | M3 / M3 | E2 | P — 선언한 code는 VD-04 결정 5(입력 보존·재제출)가 짝 백엔드에서 성립한다. 409 업무 거절을 필드 오류로 보이라는 매뉴얼(`02-decision-tables.md:185`)과 "409는 validation으로 바꾸지 않는다"(VD-04 결정 5)가 갈린다 |
|
||||
| 18 | 배포 성숙도 | 적용 | M3 / M2 | E1 | O — 플랫폼 구성 화면이 렌더 중에 부르는 dynamic import도 `ChunkRecoveryBoundary` 안에 있어 청크 실패는 reload-once 복구로 간다(`app-router.tsx:379-397`, `chunk-recovery-boundary.tsx:56-88`). 실행 확인은 안 했다 |
|
||||
| 19 | 설정 성숙도 | 적용 | M2 / M1 | E1 | P — 0929/08-01 남음 |
|
||||
| 20 | 개발자 경험 | 적용 | — | E2 | P — 기능이 업무 거절 문구를 자기 catalog로 붙일 자리가 없다(1103/08-01 남은 부분). 생성 폼의 확인 경로가 아무것도 보이지 않는다(08-02) |
|
||||
| 21 | Guardrail 성숙도 | 적용 | M3 / M3 | E2 | O — 라우트 모양 키가 라우터 규칙(대소문자, 끝 슬래시)과 맞다(1103/08-04). 키 없는 재전송을 코디네이터와 화면이 둘 다 막는다(0929/03-03). 두 수정 모두 변이에 잡힌다(03-R07, 08-R6) |
|
||||
| 22 | 추상화 성숙도 | 적용 | — | E2 | P — 폼 결과와 코디네이터 상태를 페이지가 합친다(지난 5.3절 그대로). `form.failure`가 상태 결과에만 있어 `conflict`의 code를 페이지가 못 읽는다. 그 합치기를 참조 폼과 생성기가 따로 복사해 08-01·08-02·08-04가 같은 자리에서 났다(3.5절) |
|
||||
| **23** | 일관성 | 적용 | — | E2 | P — 셸 탐색은 꺼진 기능을 빼는데 홈 시작 링크는 빼지 않는다(08-03). 참조 폼은 확인 뒤 "저장했습니다."를 보이는데 생성 폼은 아무것도 보이지 않는다(08-02) |
|
||||
| **24** | 네이밍 / 의미 성숙도 | 적용 | — | E2 | P — 선언한 400 업무 거절에 "요청을 처리할 수 없습니다." + "지원 정보 확인"(1103/08-01 남은 부분). "변경됨으로 확인"이 선언하지 않은 거절을 "저장했습니다."로 바꾼다(같은 항목) |
|
||||
| 25 | 조직 확장성 | 적용 | — | E1 | P — 필드 거절 문구 표(`form-contracts.ts:33-64`)와 locale 목록이 템플릿 파일에 있어 제품이 템플릿 파일을 고친다 |
|
||||
| 26 | Ownership 성숙도 | 적용 | — | E1 | ? — 수동 접근성 기록 10건이 모두 `pending-manual-review`다(`artifacts/tests/a11y-manual/*.md`) |
|
||||
| 27 | 삭제 가능성 | > | — | — | 영역 09·16. 홈 화면은 예제 기능을 지운 빌드에서 그 라우트를 이름으로 부르지 않는다(`home-page.tsx:15-23`) |
|
||||
| 28 | 회복 가능성 | 적용 | M3 / M2 | E3 | P — 선언한 거절 뒤 화면 안에서 고쳐 다시 저장된다(08-R1 A1~A4). 선언하지 않은 거절은 여전히 거짓 성공 버튼과 끝나지 않는 재전송만 남는다(08-R1 A5). 복구 버튼 뒤 포커스가 `body`다(08-01) |
|
||||
|
||||
## 5. 미검증
|
||||
|
||||
- **브라우저에서 돌리지 않은 것.** 08-03(홈 링크)과 08-04(다시 마운트)는 jsdom에서만 확인했다. 08-01만 3엔진에서 확인했다.
|
||||
- **실제 스크린 리더.** 포커스된 feedback 자리(역할·이름 없음)를 어떻게 읽는지, 그 안의 `role="status"`·`role="alert"`와 겹쳐 두 번 읽히는지 확인하지 않았다. 수동 접근성 기록 10건은 모두 `pending-manual-review`다(`artifacts/tests/a11y-manual/*.md`).
|
||||
- **생성기로 만든 기능 폼.** 생성 명령을 돌려 결과 파일을 보거나 실행하지 않았다(08-02, 3.0절 생성기 행). 템플릿 문자열만 읽었다.
|
||||
- **짝 백엔드.** 실제로 띄우지 않았다. 도메인 거절 뒤 같은 키 재전송이 `500 IDEMPOTENCY_RECOVERY_REQUIRED`가 된다는 것은 지난 라운드의 백엔드 코드 읽기이고, 이번에 다시 읽지 않았다(백엔드 HEAD `45d2a478`). 08-R1 A5는 그 응답을 흉내 냈다.
|
||||
- **플랫폼 구성 화면의 load 실패 경로**(기능 사이 중복, 실행부 청크 실패). 코드만 읽었다. 측정(FE-GATE-026)은 영역 15다.
|
||||
- **영역 밖 게이트 실패.** `verify:documentation` rc=1(짝 백엔드 문서 경로), FE-GATE-013 rc=1(security). 이 영역 판정에 쓰지 않았다.
|
||||
|
||||
## 6. 실행 기록
|
||||
|
||||
리뷰어가 직접 돌린 desktop 실행은 0건이다. 처음 넣은 `08-vt`·`08-pw`는 잠금을 기다리는 동안 ssh가 끊겨(rc 255) 시작하지 못했고, 19:55에 별도 실행이 닫혔다(`BRIEF-2.md`). 노트북에서는 읽기와 `git apply --check`(상태를 바꾸지 않음)만 했다. 아래는 오케스트레이터가 한 배치로 돌린 결과다(`scratchpad/r4/results/08/`, 20:02~20:08, 부하 2.0~4.5). 매 항목 전후로 checkout을 `8a44226`으로 되돌렸고 모두 `restore=clean`이다. 요청과 패치는 `scratchpad/r4/requests/08.md`, `scratchpad/r4-08/patch/`.
|
||||
|
||||
| ID | 명령 | 변이 | rc·시간 | 결과 |
|
||||
|---|---|---|---|---|
|
||||
| 08-R1 | `node scripts/run-vitest.ts run tests/features/reference-feature/probe-08-r4.test.tsx` | probe 파일 추가 | 0 · 8초 | 11 passed. 관찰은 아래 표 |
|
||||
| 08-R2 | `corepack pnpm exec playwright test tests/e2e/probe-08-r4-focus.spec.ts --project=chromium --project=firefox --project=webkit --reporter=list` | spec 추가 | 0 · 13초 | 9 passed. 9건 모두 `after=BODY tab=이름 입력란`, 재전송 3건 `keysSame=true` |
|
||||
| 08-R3 | `… run tests/features/reference-feature/reference-page.test.tsx` | M1 `use-app-form.ts:100` 포커스 제거 | 1 · 16초 | 기대대로. 2 failed / 21 passed: "moves focus to the failure status after a keyboard save ('unknown')", "('rate-limited')" — `toHaveFocus` 실패 |
|
||||
| 08-R4 → 03-R07 | `… run tests/component/application-mutation-admission.test.tsx tests/component/async-surface.test.tsx` | 영역 03 M08(= 이 영역 M3, `application-query.ts:842` 키 조건 제거) | 1 | 기대대로. 1 failed / 50 passed: "offers no resend for an unknown request that carries no key" — `expected true to be false`. `async-surface.test.tsx`는 상태를 직접 만들어 통과(화면 쪽 조건은 그 파일의 "draws no resend …"가 본다) |
|
||||
| 08-R5 | `… run tests/component/form-foundation.test.tsx` | M5 `form-contracts.ts:77` `hasOwn` → `!== undefined` | 1 · 3초 | 기대대로. 4 failed / 27 passed: `constructor`·`toString`·`__proto__`·`hasOwnProperty` 행, "요청한 문구를 표시할 수 없습니다." ≠ "입력값을 확인해 주세요." |
|
||||
| 08-R6 | `… run tests/architecture/context-route-roots.test.ts` | M6 `deployable-app-module.ts:120` `.toLowerCase()` 제거 | 1 · 1초 | 기대대로. 1 failed / 24 passed: "rejects two feature routes whose paths differ 'only by letter case'" — throw 없음 |
|
||||
| 08-R7 | `… run tests/component/form-foundation.test.tsx` | M8 `backend-envelope.ts:221` 422 → 항상 필드 | 1 · 4초 | 기대대로. 1 failed / 30 passed: "shows a paired backend 422 IDEMPOTENT_REQUEST_MISMATCH as a status, not an input error" |
|
||||
|
||||
변이 없는 대조는 게이트 출력이다: `tests/component`는 `gates/test_component.log`(40 / 270 통과), `tests/features`·`tests/architecture`는 snapshot `artifacts/tests/coverage.xml`(FE-GATE-005, 3,869건 실패 0, 그중 `reference-page.test`·`context-route-roots` 48건). 변이 넷과 03-R07 모두 변이 없는 실행은 통과, 변이 실행은 기대한 테스트가 기대한 이유로 실패했다.
|
||||
|
||||
08-R1 관찰(참조 폼, 실제 `AppRouter`·코디네이터, gateway 결과만 주입):
|
||||
|
||||
| 경우 | 거절 직후 | 값 고친 뒤 다시 저장 |
|
||||
|---|---|---|
|
||||
| A1 선언한 409 `POSTER_ALREADY_EXISTS`(`CONFLICT`, `NOT_APPLIED`) | 요약 "입력 내용을 확인해 주세요. 다른 변경과 충돌했습니다. 입력은 유지되었으니 최신 상태를 확인해 주세요.", feedback "충돌을 해결한 뒤 다시 제출할 수 있습니다.", 저장 켜짐, 포커스 feedback | 키 `key-1` → `key-2`, "저장했습니다." |
|
||||
| A2 선언한 400 `WORKLOG_INVALID`(`UNKNOWN_CLIENT_FAILURE`) | feedback "요청을 처리할 수 없습니다. / 지원 정보 확인 / 지원 참조: corr-a2", 저장 켜짐, 포커스 feedback | `key-2`로 저장 |
|
||||
| A3 선언 + `mapProblem` 필드 `DUPLICATE` | 요약 "새 항목 이름: 입력값을 확인해 주세요.", `aria-invalid="true"`, 포커스 이름 입력란 | `key-2`로 저장 |
|
||||
| A4 생성기 모양 필드 `INVALID` | 요약 "새 항목 이름: 올바른 값을 입력해 주세요.", 포커스 이름 입력란 | `key-2`로 저장 |
|
||||
| A5 선언하지 않은 409(`MAYBE_APPLIED`) → 재전송 2회 `500 IDEMPOTENCY_RECOVERY_REQUIRED` | "변경 결과를 확인할 수 없습니다." + "변경됨으로 확인" + "같은 요청으로 다시 보내기", 저장 꺼짐 | 재전송 키 `key-1` 3회, 세 번 모두 같은 화면과 같은 버튼 |
|
||||
| B1·B2·B3 확인 / 재전송 성공 / 429 뒤 다시 시도 성공 | 복구 버튼에 포커스 | 끝난 뒤 `document.activeElement` = `BODY`(셋 모두) |
|
||||
| C 기능 켜짐 / 꺼짐 | 시작 링크 셋 같음. 꺼짐이면 셸 탐색에서 `/examples/ui`·`/examples/states`·`/examples/auth`가 빠짐 | 꺼짐에서 둘째 링크 → 사용 중지 화면 |
|
||||
| D 저장 중 이탈 → 복귀 | 저장 켜짐, 취소 꺼짐, feedback 없음 | 클릭해도 요청 1 그대로, 화면 변화 없음 |
|
||||
|
||||
## 7. 새 발견 요약
|
||||
|
||||
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|
||||
|---|---|---|---|---|
|
||||
| 08-01 | Low · P3 | 확인된 결함 | 실패 상태의 복구 버튼을 키보드로 누르면 일이 끝난 뒤 버튼이 사라지며 포커스가 `body`로 떨어진다 | `src/presentation/forms/use-app-form.ts:91-101`, `:176-195`; `src/features/reference-feature/presentation/reference-resource-form-page.tsx:141-183` |
|
||||
| 08-02 | Low · P3 | 확인된 결함 | 생성 기능 폼이 "변경됨으로 확인" 뒤 아무것도 보이지 않고 입력을 비운다 | `scripts/create-feature-write-slice.ts:703-721`, `:714` |
|
||||
| 08-03 | Low · P3 | 확인된 결함 | 홈 시작 링크가 런타임에 꺼진 기능의 라우트를 가리킨다(`b96d61d8`) | `src/presentation/pages/home-page.tsx:21-23` vs `src/presentation/layouts/app-shell.tsx:196-202` |
|
||||
| 08-04 | Low · P3 | 확인된 결함 | 다른 저장이 진행 중일 때 저장 버튼이 켜져 있지만 눌러도 반응이 없다(`2d5d41f8`) | `src/features/reference-feature/presentation/reference-resource-form-page.tsx:52-68`, `:124-131` |
|
||||
|
||||
이월(새로 세지 않음): 1103/08-01(= 03-01) 일부, 0929/08-01 남음, 0929/08-08 남음.
|
||||
@@ -0,0 +1,206 @@
|
||||
# 영역 09 — 애플리케이션 코어·기능·조립
|
||||
|
||||
> 검토일 2026-11-05 · 기준 `8a44226`(`fix/maturity-review-2026-11-03`) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
|
||||
> 경로: `src/application/`, `src/features/`, `src/bootstrap/`, `src/platform/`, `src/apps/`, `src/contexts/`. 09-03 판정에 필요한 만큼 `recipes/session-owners/`, `docs/manual/04-paired-backend-session.md`, `tests/unit/product-extension-typecheck.test.ts`도 읽었다.
|
||||
> 깊게 본 관점: 3, 6, 10, 15, 20, 21, 22, 25
|
||||
> 렌즈: 지난 라운드 09-01~09-11 수정이 완료 기준까지 갔는가, 그 수정이 검사를 약하게 하거나 다른 결함을 만들었는가, 다운스트림(제품 소유 파일을 채운 상태)에서도 템플릿 테스트가 통과하는가, 부팅 경로가 예전에 거절하던 것을 받게 됐는가
|
||||
> 영역 판정(35.8): **조건부 사용 가능.** 지난 11건 중 8건은 코드와 테스트로 닫혔다. 조건은 넷이다. (1) 기능에 제품 capability를 주는 다운스트림은 이 커밋을 받으면 `test:unit`(FE-GATE-005)이 템플릿 테스트 하나로 실패한다(09-01). (2) 짝 백엔드 Redis session 모드는 recipe와 매뉴얼대로 이으면 서버 401이 세션에 닿지 않는다. `onCredentialRejected`를 제품이 직접 잇는다(09-02). (3) 짝 백엔드 실제 연동은 아무도 확인하지 않았다. realm public client와 Redis 모드 로그인 엔드포인트는 제품 몫이다(1103/09-03 일부). (4) 플랫폼 구성 화면은 끌 수 없고, 예제 기능을 빼면 브라우저 spec 8개를 고친다(1103/09-04 일부). SW `blockers`·`observe` 연결은 템플릿 파일을 고친다(1103/09-05 일부).
|
||||
|
||||
## 0. 결론
|
||||
|
||||
- 지난 라운드 이 영역 발견 11건: 고쳐짐 8(09-01, 09-02, 09-06~09-11), 일부 3(09-03, 09-04, 09-05). 이월 둘은 일부 1(0925 FOLLOW-UP 09-07), 남음 1(0925 FOLLOW-UP 09-08, 허용한 대안). 틀린 발견은 없다.
|
||||
- 09-01·09-08 수정은 변이로 지켜진다. 수정 전 동작으로 되돌리면 테스트 4건이 실패한다(09-mut). 수정 전후의 테스트 diff에 느슨해진 단언·skip·상한 증가는 없다(3절 머리).
|
||||
- 부팅 쪽 검사는 약해지지 않았다. `load-release-manifest.ts`, `contract-set.ts`, `load-runtime-config.ts`, `release-artifacts.ts`, `runtime-config-schema.ts`는 `e40684b`와 같다. 16-09 수정은 커밋된 dev manifest를 다시 쓰는 쪽만 바꿨다. 부팅이 새로 받게 된 것은 "제품 provider가 낸 자격증명의 401은 세션을 로그아웃시키지 않는다" 하나다(1103/09-01 수정, 의도된 변경). 이것이 09-02를 만들었다.
|
||||
- 새 발견 09-01: 09-02 수정이 더한 타입 검사 탐침이 복사본의 `product-composition.ts`·`product-contracts.ts`를 탐침 내용으로 덮어쓴다. 그래서 제품 capability를 기능에 주는 다운스트림에서는 그 capability가 사라져 app 타입 검사가 실패한다(09-probe-downstream). 두 다운스트림 모두 제품 capability를 쓴다(`CHANGELOG.md:57`).
|
||||
- 새 발견 09-02: 1103/09-01 수정(401을 자격증명을 낸 쪽에만 알림)과 1103/09-03 recipe(쿠키 세션 owner)가 다른 브랜치에서 들어와 맞지 않는다. 쿠키 모드의 모든 operation은 제품 provider 프로필이라, 서버 401이 세션 owner에 가지 않는다. recipe와 매뉴얼은 "서버 401 → unauthenticated"라고 적는다(09-cookie401).
|
||||
- 새 발견 09-03: 1103/09-07 수정과 1103/14-06 수정이 둘 다 원인을 붙여, `check:registries` 출력에 같은 원인이 두 번 나온다(Low).
|
||||
- 401과 계정 전환이 겹치는 경쟁(지난 1.2 미확인)은 코드로는 실행기가 막는다. 응답 admission(401 본문 cancel 포함)이 scope fence와 경쟁하고, fence가 이기면 결과가 `SCOPE_FENCED` 위반(`CONTRACT_VIOLATION`)이라 조립 루트가 401을 알리지 않는다(`src/adapters/http/http-execution-v3.ts:1088-1114`). 09-R1(배치)에서 `R4-09 race: switched=true outcome=CONTRACT_VIOLATION previousScopeCurrent=false subject=user-b notify=0`. 발견 없음.
|
||||
- 새 발견: Medium 2 · Low 1. P1 1 · P2 1 · P3 1. 확인된 결함 3.
|
||||
|
||||
## 1. 범위 (36.1)
|
||||
|
||||
| 항목 | 기록 |
|
||||
|---|---|
|
||||
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` |
|
||||
| 커밋·작업 상태·확인 시점 | `8a4422624e81e5d13a3809e212e826ff75aac62b`. 노트북 worktree(HEAD = 기준, 추적 파일 변경 없음, untracked `AGENTS.md`는 무시)에서 읽었다. 실행은 desktop checkout에서 공유 잠금 helper(`/tmp/claude-gates/r4/exp.sh`)로 19:43에 4개를 돌렸다. 그 뒤 helper가 닫혀(BRIEF-2) 남은 1개는 오케스트레이터 배치(09-R1, 20:08)로 돌렸다. 2026-11-05 19~20시 |
|
||||
| 목적과 지원 실행 구성 | 프론트엔드 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음. 짝 백엔드 `clean-architecture-backend-template` `45d2a478`(읽기만) |
|
||||
| 필수 요구와 규모·운영 목표 | 두 템플릿을 짝으로 빨리 출시. 다운스트림(tech-log, memento)이 템플릿을 동기화한다. 정량 운영 목표 없음 |
|
||||
| 읽은 코드·구성 범위 | `src/bootstrap/` 전체(`runtime-adapters.ts` 280~720행, `product-composition{,-contract}.ts`, `product-session-owner-context.ts`, `session-owner-fetch.ts`, `optional-runtime-host.ts`, `load-release-manifest.ts` 계약 집합 부분), `src/features/` 최상위 파일 전부와 `platform-examples-feature/`, `local-draft-feature/`, `src/apps/`, `src/contexts/`, `src/application/ports/auth-session-port.ts`·`view-models/async-state.ts`·`result.ts`. 연결 확인: `src/adapters/auth/external-session-adapter.ts`, `src/adapters/http/http-execution-v3.ts`(401·scope·admission 부분), `src/adapters/http/feature-http-binding.ts:464-467`, `src/presentation/providers/session-provider.tsx`, `src/contracts/{routes,env,product-contracts,external-contract-runtime,contract-set}.ts`, `recipes/session-owners/*.ts`, `scripts/{generate-product-feature-index,write-dev-release-manifest,test-sample-removal,test-feature-scaffold,check-registries,create-feature-write-slice}.ts`, `tests/unit/{product-extension-typecheck,dev-release-manifest,runtime-adapters*}.test.ts`, `tests/recipes/session-owners-runtime.test.ts`, `docs/manual/{02,03,04}*.md`, `docs/architecture/{starter-experience,optional-adapter-recipes}.md`, `config/ci/gates.json`(FE-GATE-005·007). `git diff e40684b..8a44226 -- <영역 경로>` 32파일 전부와 영역 커밋 31개의 본문 |
|
||||
| 수행한 테스트·실험 | 6절. desktop 실행 4개: `09-ctrl`(변이 없음), `09-mut`, `09-cookie401`, `09-probe-downstream`. `09-race401`은 잠금 대기 중 취소돼 오케스트레이터 배치 09-R1로 돌렸다. 전체 게이트는 다시 돌리지 않고 오케스트레이터 결과를 인용했다(6절 끝) |
|
||||
| 확인하지 못한 범위·이유 | 5절 |
|
||||
| 이전 리뷰와 비교 가능한 범위 | `docs/reviews/2026-11-03-maturity-review/09-app-core.md` 09-01~09-11과 2절의 이월 항목, README 10.3(07-05 → 09-10), 14.4·14.6. README 14.4는 주장으로만 읽었다. 각 항목을 현재 코드와 이번 실행으로 다시 판정했다(2절) |
|
||||
|
||||
오케스트레이터 게이트 결과(`desktop:/tmp/claude-gates/r4/merge-48/`, `gates/`)는 이 문서를 쓰는 동안 채워지는 중이었다. 6절 끝에 그 내용을 적었다. snapshot(`r4/snap/`)은 읽지 않았다(이 영역 판단에 필요한 출력이 게이트 로그에 있었다).
|
||||
|
||||
## 2. 지난 발견 재확인
|
||||
|
||||
| 지난 ID | 내용 | 상태 | 근거 |
|
||||
|---|---|---|---|
|
||||
| 1103/09-01 | 자격증명을 싣지 않은 요청의 401도 세션을 로그아웃시킨다 | **고쳐짐** (이 수정이 새 결함 09-02를 만들었다) | `reportServerUnauthenticated`가 `attachCredentials`와 같은 순서로 401의 주인을 가른다(`src/bootstrap/runtime-adapters.ts:577-593`, 호출 `:647-652`). ANONYMOUS면 아무에게도, 제품 provider 프로필이면 `onCredentialRejected`에, 나머지는 세션에 알린다. 완료 기준(ANONYMOUS 두 경우 세션 유지·알림 0회·scope 유지, bearer 대조군 1회)을 `tests/unit/runtime-adapters-auth-profile.test.ts:371-441`이 그대로 본다. provider 경로는 `runtime-adapters-credential-order.test.ts:357-420`. **09-mut**: 함수 첫 줄을 수정 전 동작(`authSession.onUnauthenticated()` 후 return)으로 바꾸면 3건 실패. 지난 1.2의 "401과 계정 전환 경쟁"은 코드로는 실행기가 막는다(`http-execution-v3.ts:1088-1114`). 09-R1에서 이전 scope의 401이 새 사용자에게 닿지 않음을 확인했다(6절) |
|
||||
| 1103/09-02 | 제품 확장 지점의 타입 검사 경로가 막힌다 | **고쳐짐** (템플릿 상태). 수정이 더한 탐침이 다운스트림에서 실패한다(새 09-01) | capability 타입은 제품 소유 `src/features/product-capabilities.ts:28`에 두고 `FeaturePlatformCapabilities`가 extends한다(`src/features/feature-adapter-contribution.ts:9`, `:56-62`). 그래서 node 프로그램에도 보인다. 템플릿 테스트는 `testRuntimeConfig`로 제품 기본값을 실제 스키마에서 채운다(`tests/helpers/runtime-config.ts:31-58`). 완료 기준(문서 위치 보강 + `.default()` 키로 tsc 3종 통과)을 `tests/unit/product-extension-typecheck.test.ts:164-212`가 실제 파일로 확인한다. **09-ctrl**에서 통과 |
|
||||
| 1103/09-03 | 짝 백엔드 인증 방식에 맞는 세션 owner가 없다 | **일부** | 생긴 것: OIDC PKCE owner(`recipes/session-owners/oidc-pkce-session-owner.ts`, 651행)와 쿠키 owner + CSRF provider(`cookie-session-owner.ts`, 199행), owner context의 시간 제한 fetch·page·redirectStorage(`src/bootstrap/product-session-owner-context.ts:80-102`, `session-owner-fetch.ts:128-194`), 매뉴얼 04, 조립 루트를 지나는 테스트(`tests/recipes/session-owners-runtime.test.ts`, 09-ctrl 통과). 남은 것: ① 완료 기준인 실제 Keycloak 로그인·Redis 쓰기 1회는 아무도 하지 않았다(README 14.4 "실제 Keycloak·Redis 연동 미확인"). ② 백엔드 realm에는 confidential client `ca-skeleton-api` 하나뿐이다(백엔드 `45d2a478` `infra/keycloak/realms/ca-skeleton-realm.json:59-65`). Redis 모드 로그인·세션 조회 엔드포인트도 없다. 둘 다 제품 몫으로 적었다(`docs/manual/04-paired-backend-session.md:192-200`). ③ 쿠키 모드에서 서버 401이 owner에 닿지 않는다. 이것은 1103/09-01 수정과 맞물린 다른 결함이라 새 09-02로 센다 |
|
||||
| 1103/09-04 | 플랫폼 예제 화면 4개를 끌 자리가 없다 | **일부** (결정 대기) | 셋은 기능으로 옮겼다(`src/features/platform-examples-feature/`, `src/contexts/platform-examples-context/context-module.ts:9-12`). 남은 것: ① `EXAMPLES_PLATFORM`은 플랫폼 레지스트리에 고정이다(`src/contracts/routes.ts:33-45`). FE-GATE-028 서명 대상이고 기록은 `pending-manual-review`다(`artifacts/tests/a11y-manual/EXAMPLES_PLATFORM.md:3`). 옮기면 lab이 443 ms로 FAIL이라 남겼다(`b96d61d8` 본문). ② 예제 기능을 빼면 예제 화면을 자기 페이지로 쓰는 브라우저 spec 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`)를 제품이 고치거나 지운다(`docs/architecture/starter-experience.md:122-125`). 완료 기준 "템플릿 파일 diff 0"에 못 미친다 |
|
||||
| 1103/09-05 | SW 등 선택 런타임을 켜는 일이 제품 확장 지점 밖에 있다 (흡수: 1101/09-05) | **일부** | 선택 상수 넷은 제품 소유 파일로 옮겼다(`src/features/product-capabilities.ts:30-43`). 템플릿 파일은 검사·투영만 한다(`src/features/installed-runtime-capabilities.ts:36-46`). 매뉴얼 03 "SW 켜기"가 생겼다(`docs/manual/03-outside-feature-folder.md:128-154`). 남은 것: `blockers`·`observe` 연결은 여전히 템플릿 소유 `src/bootstrap/create-runtime-composition.ts`를 고친다(같은 매뉴얼 `:154`, `docs/architecture/optional-adapter-recipes.md:134-146`). realtime·worker·offline은 여전히 "Connect a runtime in src/bootstrap/optional-runtime-host.ts"로 거절된다(`src/bootstrap/optional-runtime-host.ts:60-64`) |
|
||||
| 1103/09-06 | 참조 기능이 짝 백엔드 응답 모양이 아니다 | **고쳐짐** (대안 B) | README 14.6의 결정은 생성 명령 확장으로 났다. `create:feature --with-create [--keyed]`가 짝 백엔드 생성기와 같은 Envelope 쓰기 slice를 만든다(`scripts/create-feature-write-slice.ts`). 생성 테스트가 KEYED 생성·503 재전송·409 `IDEMPOTENT_IN_FLIGHT`·400 필드 오류를 본다(`:898-921`, `:971`). 생성 드릴이 이 slice를 만들고 게이트를 돈다(`scripts/test-feature-scaffold.ts:41`, `:62-70`). 참조 기능은 problem details 예제로 남는다(`src/features`의 `responseEnvelope` 0건). 드릴 실행 결과는 오케스트레이터 FE-GATE-020에 있다(6절) |
|
||||
| 1103/09-07 | 제품 인증 프로필 id 오타 시 원인 없는 메시지, 문서가 사라진 메시지를 약속 | **고쳐짐** (부작용: 새 09-03) | message에 reason을 싣는다(`src/contracts/external-contract-runtime.ts:290-297`). 테스트가 operation·프로필 id를 본다(`tests/unit/second-api-feature-registries.test.ts:279-293`). 문서 문구가 실제 출력과 같다(`docs/manual/02-decision-tables.md:245`, `docs/architecture/starter-experience.md:224`). 옛 문구 grep 0건(docs/manual·docs/architecture·src·scripts) |
|
||||
| 1103/09-08 | `needs` 좁히기가 타입에서만 (이월: 1101/09-08) | **고쳐짐** | `invokeContribution`이 `needs`의 키만 골라 frozen 객체로 넘긴다(`src/features/feature-adapter-contribution.ts:154-161`). 주석 두 곳(`runtime-adapters.ts:682`, `scripts/create-feature.ts:1027`)이 이제 맞다. 테스트 `tests/contract/reusable-capability/feature-adapter-composition.test.ts:166`. **09-mut**: 전체 context를 넘기도록 되돌리면 그 1건 실패 |
|
||||
| 1103/09-09 | `NOT_INSTALLED` 다의, 표시와 선언이 함께 있어도 설치 (이월: 1101/09-04) | **고쳐짐** | 표시 이름 `NOT_A_FEATURE`(`scripts/generate-product-feature-index.ts:284`), 함께 있으면 실패(`:316-320`), 옛 이름 거절. 테스트 `tests/scripts/generate-product-feature-index.test.ts:167-192`(09-ctrl 통과). 런타임 상태 `NOT_INSTALLED`는 그대로다(`README.md:124`) |
|
||||
| 1103/09-10 (+ 07-05) | V2 삭제 뒤 기능 실행부 모양 설명 네 곳 | **고쳐짐** | `git grep -nE "V2 API registr\|runtime schemas, mappers\|runtime schemas and mappers" -- src docs/architecture` 0건. `src/features/feature-module.ts:12-14`, `installed-feature-contracts.ts:12-14`가 지금 모양을 적는다 |
|
||||
| 1103/09-11 | 세션 복구 버튼이 `recover()` 결과를 버린다 | **고쳐짐** | `"no-session"`이면 owner가 다음에 알릴 때까지 화면이 `unauthenticated`로 본다(`src/presentation/providers/session-provider.tsx:36-62`). 계약에 전이 표를 적었다(`src/application/ports/auth-session-port.ts:1-16`, `:46-55`, `src/adapters/auth/external-session-adapter.ts:25-36`). `tests/component/session-recovery.test.tsx` 4건(09-ctrl 통과) |
|
||||
| 0925 FOLLOW-UP 09-07 | 샘플 제거 드릴이 lint·`check:i18n`·e2e를 건너뜀 | **일부** | lint, `verify:documentation`, `check:i18n`, `check:design-system`이 더해졌다(`scripts/test-sample-removal.ts:434-441`). e2e·시각 테스트는 여전히 돌리지 않는다(`b96d61d8` 본문 "제거 드릴은 브라우저 테스트를 돌리지 않아 이것을 보지 않는다"). 위 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` 표시로 기능이 아니다 |
|
||||
| README 14.6 결정 (참조 기능 Envelope 이행) | 결정 기록 없음 | **고쳐짐** | 1103/09-06과 같다. 생성 명령 확장(B)으로 결정됐다(README 14.4 "그 밖의 81건 고침", 커밋 `2ec9d560`) |
|
||||
| (영역 16) 1103/16-09 — 부팅 쪽만 | dev server의 고정 contract set | **부팅 검사 약화 없음** | 수정 `799ab7f`은 `scripts/write-dev-release-manifest.ts:17-25`, `scripts/create-feature.ts`, `scripts/test-sample-removal.ts`, `tests/unit/dev-release-manifest.test.ts`, `vite.config.ts`만 바꿨다. 부팅 검사(`src/bootstrap/load-release-manifest.ts:296-305`, `src/contracts/contract-set.ts:64-110`)는 `e40684b`와 같다(`git diff --stat` 0). 테스트는 커밋된 `contractSet` 전체(digest 포함)를 설치된 기능의 값과 비교한다(`dev-release-manifest.test.ts:17-26`). 09-ctrl 통과 |
|
||||
|
||||
## 3. 이번 발견 (36.3)
|
||||
|
||||
요약: Medium 2 · Low 1. P1 1(09-01) · P2 1(09-02) · P3 1(09-03). 확인된 결함 3.
|
||||
|
||||
검사 약화 점검(브리프 4절): `git diff e40684b..8a44226`의 영역 테스트에서 지운 단언은 셋이다. `context-route-roots.test.ts:193-210`은 예로 쓴 라우트를 `EXAMPLES_UI`에서 아직 플랫폼인 `EXAMPLES_PLATFORM`으로 바꿨다(같은 단언). `second-api-feature-registries.test.ts`의 생성 단언은 helper로 옮겼다. `reference-page.test.tsx`의 "저장 중 버튼 disabled"는 aria-busy·focus 단언으로 바뀌었고 호출 1회 단언은 남았다(08 영역 08-02). `runtime-adapters.test.ts:58-70`의 `API_FEATURE_IDS`는 API 없는 예제 기능을 빼지만, 기준 커밋에서도 API 있는 기능은 참조 기능 하나였다. skip·quarantine·timeout·상한 증가는 영역 경로에 없다. 약화로 센 것은 없다.
|
||||
|
||||
### 09-01 제품 확장 타입 검사 탐침이 제품 소유 파일 둘을 탐침 내용으로 덮어써, 기능이 제품 capability를 쓰는 다운스트림에서는 `test:unit`이 실패한다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 10, 21, 25, 3, 20, 13(제품 수 축) (30.3, 30.4) |
|
||||
| 근거 | 탐침은 저장소 복사본에서 `src/contracts/product-contracts.ts`와 `src/bootstrap/product-composition.ts`를 통째로 탐침 내용으로 쓴다(`tests/unit/product-extension-typecheck.test.ts:41-83`, `:181-193`). capability 타입만 제품 선언 끝에 덧붙인다(`:35-39`, `:180-182`). 탐침의 `composeProduct`는 `typecheckProbeSettings` 하나만 돌려준다(`:74-82`). 조립 루트는 `composeProduct`의 capability를 기능 로더에 넘긴다(`src/bootstrap/runtime-adapters.ts:689-697`). 로더의 context 타입은 설치된 기능들이 `needs`에 적은 키를 모두 요구한다(`src/features/installed-feature-adapters.ts:21-27`, `:48-49`, `feature-adapter-contribution.ts:124-129`). 그래서 제품이 문서대로 capability를 타입에 적고(`docs/manual/03-outside-feature-folder.md:105`) `product-composition.ts`에서 돌려주고 자기 기능의 `needs`에 적으면, 복사본에서는 값이 사라져 app 프로그램이 실패한다. **09-probe-downstream**: 제품 소유 파일 두 개(`product-capabilities.ts`에 `r4NoticeSettings` 타입, `product-composition.ts`가 그 값을 돌려줌)와 제품 기능·context 폴더(`needs: ["r4NoticeSettings"]`)만 더했다. 그 상태의 저장소는 `check:types:app`·`:node`·`:test`가 모두 rc=0이다. 탐침은 실패한다: `tsconfig.app.json: … /tmp/product-extension-typecheck-T7Vx60/src/bootstrap/runtime-adapters.ts(695,5): error TS2741: Property 'r4NoticeSettings' is missing in type 'Readonly<{ typecheckProbeSettings: …; http…`. 변이 없는 09-ctrl에서는 탐침이 통과한다 |
|
||||
| 발생 조건 | 다운스트림이 이 커밋 이후로 동기화하고, 제품 capability를 하나 이상 기능에 준다. CHANGELOG가 두 다운스트림의 capability를 적는다: memento `offsetUpload`·`runtime`, tech-log Studio 소스·HTTP(`CHANGELOG.md:57`) |
|
||||
| 영향 | merge 게이트 FE-GATE-005(`test-unit`, `config/ci/gates.json:1840-1848`)가 코드와 무관하게 항상 실패한다. 통과시키려면 템플릿 테스트를 고치거나 지운다. 동기화마다 충돌 자리가 된다. 1103/09-02 수정의 목적("제품 소유 파일만 고치고 템플릿 게이트 통과")이 첫 제품 capability에서 다시 깨진다. 실패 메시지는 복사본 경로의 TS 오류라 원인(탐침이 파일을 덮어씀)을 말하지 않는다 |
|
||||
| 심각도·우선순위 | Medium · P1 — 사용자 피해 없는 "merge 게이트 항상 실패"(지난 라운드 02-06·12-01과 같은 눈금). 동기화 직후 두 다운스트림 모두에 해당한다 |
|
||||
| 통제·증거 | 목표 M3(탐침이 제품 파일을 보존한 채 실행) / 확인 M0(다운스트림 상태를 보는 검사 없음) · E3(09-probe-downstream, 실제 tsc) |
|
||||
| 확실성과 남은 가정 | 다운스트림 상태를 desktop 복사본에서 만들어 재현했다. 실제 tech-log·memento에 이 커밋을 넣어 보지는 않았다. 제품 capability를 기능에 주지 않는 제품은 통과한다. 같은 모양의 다른 경우(추론, 실행 안 함): 탐침 context가 소유 앱을 `template-app`으로 고정한다(`tests/unit/product-extension-typecheck.test.ts:152-156`). 앱 id를 바꾼 제품에서는 생성기가 "Context typecheck-probe-context belongs to undeclared app template-app"으로 멈출 것이다(`scripts/generate-product-feature-index.ts:357-358`) |
|
||||
| 결정의 근거 | 확인한 사실: 위 근거. 기록된 의도: `235143c` 본문이 "product-contracts.ts·product-composition.ts는 여전히 탐침 내용으로 바꿔 쓴다. 제품 기능이 이 두 파일의 이름 있는 export를 import하면 … 타입 오류가 날 수 있다"를 위험으로 적었다. CHANGELOG는 "제품의 capability 선언을 덮어쓰지 않는다"고 적는다(`CHANGELOG.md:249`). 리뷰어 추론: 선언(타입)은 지켰지만 값(`composeProduct`)을 덮어써, 선언한 capability를 실제로 쓰는 제품이 막힌다. X2 #1이 고치려던 바로 그 제품이다 |
|
||||
| 이해 비용 | 제품 개발자는 실패한 tsc 출력이 임시 복사본(`/tmp/product-extension-typecheck-*`)의 `runtime-adapters.ts`를 가리키는 이유를 탐침 소스를 읽어야 안다 |
|
||||
| 최소 개선 방향 | 탐침이 제품 파일 내용을 버리지 않는다. (가) 복사본 안에서 원래 `product-composition.ts`를 다른 이름으로 옮기고, 새 파일이 원래 `composeProduct` 결과를 펼친 뒤 탐침 capability를 더한다. `product-contracts.ts`도 원래 필드를 펼친 뒤 탐침 키·행을 더한다. 또는 (나) 제품 파일이 출하 상태(빈 값)가 아니면 탐침을 건너뛴다. 그 상태의 타입 경로는 제품 자신의 `check:types`가 본다 |
|
||||
| 대안 비교 | (A) 현 상태: 템플릿에서는 통과, 다운스트림 실패. (B) (가): 다운스트림에서도 같은 검사를 한다. 제품 파일의 export 이름(`composeProduct`, `PRODUCT_*`)에 기댄다. 그 이름은 계약이라 바뀌지 않는다. (C) (나): 더 단순하다. 탐침의 목적(템플릿 테스트와 node 프로그램이 제품 키·capability를 받아들임)은 출하 상태에서 이미 확인된다. 다운스트림 상태의 확인은 잃는다. (D) 다운스트림이 동기화 때 탐침을 지우게 문서화: 충돌 자리가 남는다 |
|
||||
| 단순화의 보존 조건 | 템플릿 출하 상태에서 tsc 3종을 실제 파일로 돈다. `.default()` 제품 키와 node 프로그램에 보이는 capability 타입을 계속 본다. 예약 이름 `typecheck-probe-*` 충돌 검사(`:171`)는 남긴다 |
|
||||
| 비용·부작용 | 테스트 파일 하나 수십 줄 |
|
||||
| 재검토 조건 | 제품 소유 파일이 늘거나, 다운스트림이 템플릿 테스트를 따로 고르는 방식으로 바뀌면 |
|
||||
| 완료 기준 | 09-probe-downstream 상태(제품 capability + 그것을 쓰는 제품 기능)에서 탐침 통과. 템플릿 출하 상태에서도 통과 |
|
||||
| 검증 방법 | 09-probe-downstream 변이를 테스트 안 픽스처로 옮긴다 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
| 재검증 결과 | 해당 없음(신규) |
|
||||
|
||||
### 09-02 짝 백엔드 Redis session 모드를 recipe와 매뉴얼대로 이으면 서버 401이 세션 owner에 닿지 않는다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 6, 28, 15, 17, 22, 4, 5, 10, 9 (32 세션 만료, 30.5) |
|
||||
| 근거 | 1103/09-01 수정 뒤 조립 루트는 제품 provider 프로필의 401을 세션에 알리지 않고 선택 hook `onCredentialRejected`만 부른다(`src/bootstrap/runtime-adapters.ts:583-591`, 계약 `src/bootstrap/product-composition-contract.ts:111-120`). 쿠키 recipe에서는 모든 operation이 provider 프로필이다. owner의 `attachCredential`은 항상 throw하고 `SESSION_COOKIE_*` 프로필을 쓰라고 한다(`recipes/session-owners/cookie-session-owner.ts:163-167`, provider `:181-199`). 매뉴얼의 연결 예시는 `credentialProviders`만 돌려주고 `onCredentialRejected`가 없다(`docs/manual/04-paired-backend-session.md:238-246`). recipe와 매뉴얼은 반대를 적는다: "a server 401 signs out"(`cookie-session-owner.ts:33`), "its 401 reaches the owner"(`:179`), "서버 401 → [unauthenticated]"(매뉴얼 `:186`), "서버의 401은 owner에게 간다"(`:249`). hook을 이으려 해도 `ProductCompositionContext`에 세션이나 owner가 없다(`product-composition-contract.ts:81-91`). owner는 다른 함수 `composeProductSessionOwner`에서 만들어지므로 제품은 모듈 변수로 둘을 이어야 한다. 이 방법은 어디에도 없다(`git grep onCredentialRejected` → CHANGELOG·매뉴얼 02·계약·테스트뿐). 두 변경은 다른 브랜치에서 만들어져 `c17b3a05`·`b029dcc0`로 합쳐졌다. 조립 루트를 지나는 recipe 테스트는 쿠키 모드의 401을 보지 않는다(`tests/recipes/session-owners-runtime.test.ts:342-396`). owner 단위 테스트는 `notifyUnauthenticated`를 직접 불러, 조립 루트가 그것을 부른다고 가정한다(`tests/recipes/cookie-session-owner.test.ts:121-133`). **09-cookie401**: 같은 테스트 파일의 조립 루트와 매뉴얼 4.3 연결 그대로, 세션 조회는 200(`user-1`), API는 401로 답하게 했다. 읽기(`SESSION_COOKIE_READ`)·쓰기(`SESSION_COOKIE_WRITE`) 모두 `outcome=UNAUTHENTICATED sent=true credentials=include state=authenticated scopeCurrent=true`. 매뉴얼이 적은 `unauthenticated`를 단언한 두 테스트가 `expected 'authenticated' to be 'unauthenticated'`로 실패했다. 같은 파일의 기존 4건은 통과했다 |
|
||||
| 발생 조건 | 짝 백엔드 `APP_SECURITY_AUTH_MODE=redis-session`에서 서버 세션이 끝난다(Redis TTL 만료, 다른 탭·서버에서 로그아웃, 세션 삭제). 그 뒤 화면이 요청을 보낸다 |
|
||||
| 영향 | 세션 상태가 `authenticated`로 남는다. scope fence가 일어나지 않아 끝난 세션의 서버 상태 캐시가 화면에 남는다. 셸은 로그인한 사용자로 보인다. 요청마다 `AUTH_REQUIRED` 실패 화면이 뜬다(`src/adapters/http/feature-http-binding.ts:464-467`). 실패 화면의 로그인으로 다시 들어가면 풀린다. 다른 사용자가 로그인하면 owner가 세션을 다시 묻고 subject가 바뀌어 fence가 일어나므로(`cookie-session-owner.ts:106-133`, `auth-session-port.ts:14-15`), 다른 사용자 데이터 노출은 없다 |
|
||||
| 심각도·우선순위 | Medium · P2 — 지원하는 짝 모드 하나에서 세션 만료 판정(R-3.2)이 빠진다. 사용자는 실패 화면에서 회복할 수 있고 정보 노출은 없다. 지난 라운드의 반대 방향 결함(1103/09-01, 과잉 로그아웃)과 같은 눈금이다 |
|
||||
| 통제·증거 | 목표 M3(조립 루트를 지나는 recipe 테스트가 쿠키 모드 401을 본다) / 확인 M0 · E2(09-cookie401) |
|
||||
| 확실성과 남은 가정 | 조립 루트 테스트에서 재현했다. 실제 Redis 백엔드에는 붙이지 않았다. 다운스트림 memento·tech-log가 이미 hook을 이었는지는 보지 않았다(CHANGELOG `:58`는 "여기서 owner에 알린다"고 안내한다) |
|
||||
| 결정의 근거 | 확인한 사실: 위 근거. 기록된 의도: `0aada28b` 본문 "제품 provider가 템플릿 세션과 같은 세션의 자격 증명을 내는 경우, 제품이 hook을 쓰지 않으면 그 401은 세션을 바꾸지 않는다. 계약 주석과 매뉴얼 02 5절에 적었다". `05958bbd`(recipe)는 그 전 동작(provider 401도 세션에 감)을 전제로 썼다. 리뷰어 추론: 1103/09-01의 판단(자격증명을 낸 쪽이 판정)은 맞다. 다만 템플릿이 직접 내놓은 provider 예시가 그 판단의 첫 소비자인데 이어지지 않았다 |
|
||||
| 이해 비용 | 쿠키 모드 제품 개발자는 recipe, 매뉴얼 04, 매뉴얼 02 5절, 계약 주석, CHANGELOG가 서로 다른 말을 하는 것을 맞춰야 한다 |
|
||||
| 최소 개선 방향 | recipe가 owner와 provider를 한 번에 만드는 함수를 내고, 그 결과에 `onCredentialRejected: () => owner.notifyUnauthenticated()`를 담는다. 또는 `ProductCompositionContext`에 세션 알림(`notifySessionUnauthenticated`)을 준다. 매뉴얼 04 4.3 예시와 recipe 주석을 고치고, `session-owners-runtime.test.ts`에 쿠키 모드 401 케이스를 더한다 |
|
||||
| 대안 비교 | (A) 현 상태 + 문서만 고침: 모듈 변수 연결을 제품마다 쓴다. (B) recipe가 hook까지 만든다: recipe 몇 줄, 계약 그대로. (C) context에 세션 알림 함수: 계약 칸 하나, 모든 BFF 제품이 같은 한 줄을 쓴다. (D) provider 선언에 "이 provider는 템플릿 세션의 자격증명을 낸다" 표시를 두고 조립 루트가 세션에 알림: 판정이 선언 하나로 모인다. 계약 칸이 하나 는다 |
|
||||
| 단순화의 보존 조건 | ANONYMOUS 401은 아무에게도 알리지 않는다. 세션과 무관한 provider(외부 API 토큰)의 401은 세션을 로그아웃시키지 않는다(1103/09-01 완료 기준). hook의 throw는 결과를 바꾸지 않는다 |
|
||||
| 비용·부작용 | (B) recipe·매뉴얼 수십 줄, 테스트 1~2개 |
|
||||
| 재검토 조건 | 짝 백엔드 Redis 모드가 세션 조회·로그인 엔드포인트를 템플릿에 들이면 owner와 provider를 다시 맞춘다 |
|
||||
| 완료 기준 | 매뉴얼 04 4.3대로 이은 조립 루트에서 쿠키 읽기·쓰기 operation이 401을 받으면 세션이 `unauthenticated`이고 이전 scope는 current가 아니다 |
|
||||
| 검증 방법 | 09-cookie401 테스트를 `tests/recipes/session-owners-runtime.test.ts`에 옮기고 수정 전 실패를 본다 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
| 재검증 결과 | 해당 없음(신규) |
|
||||
|
||||
### 09-03 계약 조립 오류의 원인이 `check:registries` 출력에 두 번 나온다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함(작은 출력 중복) |
|
||||
| 관련 관점 | 8, 20, 23 |
|
||||
| 근거 | 1103/09-07 수정은 오류 message 끝에 reason을 붙인다(`src/contracts/external-contract-runtime.ts:293`). 1103/14-06 수정은 `check:registries`가 message 첫 줄 뒤에 `(reason: …)`를 또 붙인다(`scripts/check-registries.ts:158-163`). 두 수정이 다른 브랜치에서 들어왔다(`f98d0c36`, `84d6e526`). 그래서 출력은 "…not composable: X/OP: unknown authProfileId Y (reason: X/OP: unknown authProfileId Y)"가 된다(정적 확인). `tests/unit/registry-governance.test.ts:637-645`는 reason이 message에 없는 가짜 오류로 시험해 중복을 보지 않는다 |
|
||||
| 발생 조건 | 계약 조립 실패(프로필 id 오타 등)로 `check:registries`가 레지스트리를 읽지 못한다 |
|
||||
| 영향 | 같은 원인이 두 번 보여 읽기 어렵다. 동작 피해는 없다 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 통제·증거 | 목표 M3 / 확인 M0(실제 오류로 출력을 보는 테스트 없음) · E1 |
|
||||
| 확실성과 남은 가정 | 코드로 확인했다. 실행하지 않았다 |
|
||||
| 결정의 근거 | 적용 제외 — 두 수정이 같은 일을 겹쳐 한 단순 중복이다 |
|
||||
| 이해 비용 | 작다 |
|
||||
| 최소 개선 방향 | `loadErrorText`가 message에 reason이 이미 있으면 붙이지 않는다. 또는 테스트가 실제 `ContractContributionError`를 던진다 |
|
||||
| 대안 비교 | 적용 제외 |
|
||||
| 단순화의 보존 조건 | 적용 제외 |
|
||||
| 비용·부작용 | 몇 줄 |
|
||||
| 재검토 조건 | 적용 제외 |
|
||||
| 완료 기준 | 프로필 id 오타 하나로 `check:registries` 출력에 원인이 한 번 나온다 |
|
||||
| 검증 방법 | `registry-governance.test.ts`의 케이스를 실제 오류 클래스로 바꾼다 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
| 재검증 결과 | 해당 없음(신규) |
|
||||
|
||||
## 4. 28개 관점 판정 (36.2)
|
||||
|
||||
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가
|
||||
|
||||
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | 코드 성숙도 | 적용 | 조립 불변식 M3 / M3 | E2(09-ctrl, 09-mut) | P — 라우트 루트·핸들·경로 중복(대소문자·끝 슬래시 포함)·needs·자격증명 순서를 throw·테스트로 지킨다. 쿠키 모드 401이 세션에 닿지 않는다(09-02) |
|
||||
| 2 | 구조적 성숙도 | 적용 | 공개 경계 M3 / M3 | E1, 오케스트레이터 `check:architecture` | P — 제품 소유 파일이 셋으로 정리됐다(`product-composition.ts`, `product-contracts.ts`, `product-capabilities.ts`). SW 연결·플랫폼 구성 화면은 템플릿 파일이다(1103/09-04·09-05 일부) |
|
||||
| 3 | 변경 용이성 | 적용 | 제품 변경 = 제품 파일만 M2 / M1 | E3(09-probe-downstream) | P — 기능·capability·설정 키·SW 선택은 제품 파일만 고친다. 그런데 제품 capability를 쓰면 템플릿 테스트가 실패한다(09-01). 예제 기능을 빼면 브라우저 spec 8개를 고친다(1103/09-04 ②) |
|
||||
| 4 | 인지 부하 | 적용 | 확장 위치 한 표 M1 / M1 | E1 | P — `starter-experience.md:224` 표와 매뉴얼 03이 맞다. 쿠키 모드 401은 recipe·매뉴얼 04·매뉴얼 02·CHANGELOG가 서로 다르게 말한다(09-02) |
|
||||
| 5 | 위험 가시성 | 적용 | 판단 규칙이 호출부에서 보임 M2 / M2 | E1 | P — 401 판정 규칙이 함수 하나와 계약 주석에 모였다(`runtime-adapters.ts:571-593`). 탐침이 제품 파일을 덮어쓰는 위험은 커밋 본문에만 있다(09-01) |
|
||||
| 6 | 실패 성숙도 | 적용 | 안전한 기본 M2 / M2 | E2(09-ctrl, 09-cookie401, 09-R1) | P — 401 판정이 자격증명 출처를 본다. 계정 전환 중 401은 실행기가 막는다(09-R1). owner fetch는 시간·크기 제한·redirect 거절(`session-owner-fetch.ts:128-194`). 쿠키 모드 만료를 놓친다(09-02) |
|
||||
| 7 | 운영 성숙도 | 적용 | 경계 실패 진단 M2 / M2 | E1 | P — 결과 불명 쓰기의 effect가 진단에 실린다(`runtime-adapters.ts:209`). 제품 hook이 없을 때 provider 401이 조용히 버려지는 것은 진단에 남지 않는다(09-02) |
|
||||
| 8 | 디버깅 가능성 | 적용 | 조립 오류가 원인을 말함 M3 / M3 | E2(`second-api-feature-registries.test.ts`) | P — 프로필 오타가 operation·프로필 id를 말한다(1103/09-07 고쳐짐). 원인이 두 번 찍힌다(09-03). 탐침 실패는 임시 복사본 경로를 가리킨다(09-01) |
|
||||
| 9 | 유지보수 성숙도 | 적용 | 낡은 설명 정리 M1 / M1 | E1 | P — V2 설명 4곳 정리(1103/09-10). recipe 주석이 401 동작 변경을 따라가지 않았다(09-02). `src/application/result.ts` deprecated 재수출은 그대로(소비자 0, 제거 조건 없음) |
|
||||
| 10 | 테스트 성숙도 | 적용 | 핵심 판단 M3 / M3(템플릿 상태) | E2(09-ctrl, 09-mut, 오케스트레이터 `test:unit` 194 files / 2,883 tests) | P — 지난 수정마다 RED 테스트가 있고 변이를 잡는다. 테스트는 템플릿 출하 상태만 본다. 다운스트림 상태에서 템플릿 테스트가 실패하고(09-01), 쿠키 모드 401 테스트가 없다(09-02) |
|
||||
| 11 | 데이터 성숙도 | 적용(샘플 범위) | — / M1 | E1 | P — local-draft ABA는 주석으로만(0925 FOLLOW-UP 09-08, 허용한 대안). 이 영역에 데이터 손상 경로는 없다 |
|
||||
| 12 | 동시성 성숙도 | 적용(401·계정 전환) | 이전 scope의 401은 새 세션에 닿지 않음 M3 / M2 | E2(09-R1, 리뷰 탐침) | P — 실행기의 admission 경쟁 처리(`http-execution-v3.ts:1088-1114`)가 막는다. 09-R1에서 `notify=0`. 다만 이 경쟁을 만드는 테스트는 저장소에 없다(탐침은 리뷰용). 조립 루트의 `reportServerUnauthenticated`는 scope를 다시 보지 않는다(실행기 반환과 알림 사이 한 microtask, 5절). 나머지 동시성은 > 03 영역 |
|
||||
| 13 | 확장성 | 적용 | 기능·제품 수 축 M3 / M2 | E3(09-probe-downstream) | P — context 루트 충돌·예산 검사는 그대로다. 제품 수 축에서 09-01이 생겼다 |
|
||||
| 14 | 성능 성숙도 | > 15 영역 | — | — | > — 플랫폼 구성 화면을 기능으로 옮기면 lab FAIL(`b96d61d8` 본문)이라 남긴 판단은 15 영역 |
|
||||
| 15 | 보안 성숙도 | 적용 | fail-closed M3 / M3 | E2(09-ctrl) | P — ANONYMOUS는 세션을 묻지 않는다. provider 뒤 fence 재확인. OIDC recipe는 토큰 메모리 보관(`recipes/session-owners/oidc-pkce-session-owner.ts:23`), HTTPS·loopback 엔드포인트만(`:131-143`), return path 검사(`:166-177`), state·issuer 대조(`:474-477`), PKCE S256(`:553`), bearer origin 제한(`:581`)을 지킨다. ID token 서명은 보지 않는다(문서화, OIDC Core 3.1.3.7(6)). 쿠키 모드 만료 미감지(09-02)는 노출이 아니라 상태 오판이다 |
|
||||
| 16 | 의존성 성숙도 | 적용 제외 — recipe가 OIDC 라이브러리를 쓰지 않는다. 영역 고유 의존성 없음 | — | — | - |
|
||||
| 17 | API / Contract 성숙도 | 적용 | 401 의미가 계약과 같음 M3 / M2 | E2 | P — `ProductComposition.onCredentialRejected` 계약은 짧고 맞다. 계약을 쓰는 템플릿 예시가 계약을 따르지 않는다(09-02) |
|
||||
| 18 | 배포 성숙도 | > 13 영역 | — | — | > — 플랫폼 구성 화면의 FE-GATE-028 서명 요구는 1103/09-04 일부 |
|
||||
| 19 | 설정 성숙도 | 적용 | 제품 키 strict 검증 M3 / M3 | E2(09-ctrl 탐침) | O — 기본값 제품 키가 템플릿 테스트를 깨지 않는다. 기본값 없는 필수 키는 helper가 원인을 말하며 throw한다(`tests/helpers/runtime-config.ts:31-39`) |
|
||||
| 20 | 개발자 경험 | 적용 | 생성·제품 파일 → 게이트 통과 M3 / M2 | E3(09-probe-downstream) | P — 생성 명령의 쓰기 slice(1103/09-06), dev manifest 재작성(16-09). 제품 capability를 쓰면 게이트가 원인 없이 실패하고(09-01), 쿠키 모드 연결 예시가 틀렸다(09-02) |
|
||||
| 21 | Guardrail 성숙도 | 적용 | 조립 실수 차단 M3 / M3 | E2(09-mut) | P — 표시+선언 동시 존재, 경로 대소문자 중복, needs 밖 capability를 막는다. 템플릿 자신의 guardrail 테스트가 다운스트림 상태에서 오탐한다(09-01) |
|
||||
| 22 | 추상화 성숙도 | 적용 | 계약이 짧고 정확 M2 / M2 | E1 | P — owner context가 fetch·page·redirectStorage를 준다(1103/09-03). `composeProduct`가 owner에 닿을 길이 없어 hook을 잇기 어렵다(09-02) |
|
||||
| 23 | 일관성 | 적용 | 같은 선택은 같은 장치 M2 / M2 | E1 | P — 예제 화면 셋은 기능 선택으로 뺀다. 플랫폼 구성 화면만 예외다(1103/09-04 ①). 401 알림 경로가 bearer recipe(세션)와 쿠키 recipe(provider)에서 다르다(09-02) |
|
||||
| 24 | 네이밍 / 의미 성숙도 | 적용 | — / M2 | E2 | P — `NOT_A_FEATURE`로 나눴다(1103/09-09). `TEMPLATE_APP_MODULE`이 선택된 아무 앱을 가리키는 것은 그대로(`src/apps/template-app.ts:10`) |
|
||||
| 25 | 조직 확장성 | 적용 | 동기화 충돌 자리 분리 M2 / M1 | E3(09-probe-downstream) | P — 제품 소유 파일 셋을 테스트가 고정한다(`product-composition-fixture.test.ts:605-628`, `product-runtime-capability-selection.test.ts:43-51`). 템플릿 테스트 하나가 다운스트림에서 실패해 충돌 자리가 된다(09-01) |
|
||||
| 26 | Ownership 성숙도 | > 14 영역 | — | E2 | > — "Product-owned." 표시 세 파일 |
|
||||
| 27 | 삭제 가능성 | 적용 | 기능·예제 제거 M3 / M2 | E1, `b96d61d8` 드릴 기록 | P — 예제 셋은 제거 드릴로 빠진다. 플랫폼 구성 화면은 빠지지 않고, 브라우저 spec 8개는 제거 드릴이 보지 않는다(0925 FOLLOW-UP 09-07 일부) |
|
||||
| 28 | 회복 가능성 | 적용 | 세션·부트 회복 M2 / M2 | E2(`session-recovery.test.tsx`) | P — `no-session` 뒤 로그인 버튼(1103/09-11 고쳐짐). 쿠키 모드 만료 뒤 셸이 로그인 상태로 남는다(09-02) |
|
||||
|
||||
집계(판정한 24개): 충족 1(19) · 부분 충족 23 · 미충족 0 · 미검증 0. 적용 제외 1(16), 다른 영역 3(14, 18, 26). 지난 라운드와 달리 12는 401·계정 전환 경쟁을 이 영역에서 판정했다(코드 + 09-R1).
|
||||
|
||||
## 5. 미검증
|
||||
|
||||
| 항목 | 이유 | 확인하려면 |
|
||||
|---|---|---|
|
||||
| 짝 백엔드에 실제로 붙인 로그인·401 | Keycloak·Redis·백엔드를 띄우지 않았다. realm에 public client가 없다 | 백엔드 local + Keycloak에 public client를 더하고 OIDC recipe로 `EXTERNAL_BEARER` 1회. Redis 모드에 세션 엔드포인트를 더하고 쿠키 owner로 쓰기 1회, 세션 삭제 뒤 401 1회 |
|
||||
| 다운스트림(tech-log, memento)에 이 커밋을 넣은 결과 | 두 제품 코드를 읽지 않았다 | 동기화 브랜치에서 `test:unit`(09-01), 쿠키 provider의 `onCredentialRejected` 연결 여부 grep(09-02) |
|
||||
| 실행기 반환과 `reportServerUnauthenticated` 사이의 경쟁 | 09-R1은 admission 중 전환만 본다. 반환 뒤 한 microtask 안의 전환은 재현 장치를 만들지 않았다 | `contractHttp.execute`를 감싼 테스트에서 resolve 직전 subject를 바꾼다 |
|
||||
| 예제 기능을 뺀 제품의 브라우저 게이트 | 무거운 실행이다(FE-GATE-008). 정적으로 spec 8개를 셌다 | `VITE_PRODUCT_FEATURES`에서 예제 기능을 빼고 `test:e2e`·`test:visual` |
|
||||
| OIDC recipe의 실제 IdP 응답 모양(Keycloak refresh 응답의 `id_token`·`nonce`) | IdP를 띄우지 않았다. recipe 테스트는 가짜 응답이다 | Keycloak local로 refresh 2회 |
|
||||
|
||||
## 6. 실행 기록
|
||||
|
||||
모두 desktop helper(`/tmp/claude-gates/r4/exp.sh`, 기준 `8a442262`, 공유 잠금)로 돌렸다. 노트북에서는 아무것도 실행하지 않았다. 변이 스크립트는 `desktop:/tmp/claude-gates/r4/mut/09-*.sh`, 전체 로그는 `desktop:/tmp/claude-gates/r4/exp/09-*.log`다.
|
||||
|
||||
| 이름 | 명령 | 변이 | rc | 결과 | 잠금 대기 · 부하 |
|
||||
|---|---|---|---|---|---|
|
||||
| 09-ctrl | `node scripts/run-vitest.ts run` 11파일: `tests/unit/{runtime-adapters-auth-profile,runtime-adapters-credential-order,product-extension-typecheck,product-session-owner-context,dev-release-manifest,product-runtime-capability-selection,product-composition-fixture}.test.ts`, `tests/contract/reusable-capability/feature-adapter-composition.test.ts`, `tests/recipes/session-owners-runtime.test.ts`, `tests/component/session-recovery.test.tsx`, `tests/scripts/generate-product-feature-index.test.ts` | 없음 | 0 | 11 files / 87 tests 통과, 5.58s. 아래 변이·탐침의 대조군 | 606s · 1.49 |
|
||||
| 09-mut | `run-vitest.ts run` `runtime-adapters-auth-profile`, `runtime-adapters-credential-order`, `feature-adapter-composition` | 두 수정을 수정 전 동작으로: ① `reportServerUnauthenticated` 첫 줄에 `authSession.onUnauthenticated(); return;`(`runtime-adapters.ts:581`) ② `invokeContribution`이 `context` 전체를 넘김(`feature-adapter-contribution.ts:161`) | 1 | 4 failed / 27 passed. ①로 "keeps a demo session signed in when an ANONYMOUS request gets 401", "does not tell the external owner about an ANONYMOUS request's 401", "leaves the session alone and tells the product"(`credential-order.test.ts:380` notify 호출됨). ②로 "hands a contribution only the capabilities it names in needs"(`expected [['http','telemetry']] to deeply equal [['telemetry']]`). 대조군 09-ctrl은 같은 파일 모두 통과 → 두 수정은 테스트로 지켜진다 | 623s · 1.52 |
|
||||
| 09-R1 (배치, 원래 09-race401) | `node scripts/run-vitest.ts run tests/unit/runtime-adapters-auth-profile.test.ts --reporter=default` · local | 같은 파일 끝에 탐침 1건 추가(`scratchpad/r4/requests/09-R1-race401.diff`): external owner(user-a) bearer 요청이 401을 받고, 실행기가 401 본문을 cancel하는 순간 owner가 user-b로 바뀐다. 단언: 이전 scope는 current가 아니고 `notifyUnauthenticated` 0회 | 0 | 17 tests 통과(기존 16 + 탐침 1). `R4-09 race: switched=true outcome=CONTRACT_VIOLATION previousScopeCurrent=false subject=user-b notify=0`. 계정 전환이 admission 도중에 일어났고(`switched=true`), 결과는 `UNAUTHENTICATED`가 아니며 새 사용자에게 알림이 가지 않았다. 대조군(변이 없는 16건)은 09-ctrl과 `gates/test_unit.log`. 발견 없음 | 오케스트레이터 배치 20:08 · 3.42 |
|
||||
| 09-cookie401 | `run-vitest.ts run tests/recipes/session-owners-runtime.test.ts` | 같은 파일 끝에 탐침 2건 추가(읽기·쓰기): 매뉴얼 04 4.3 연결, 세션 조회 200, API 401. 단언: 세션 `unauthenticated`(매뉴얼 `:186`) | 1 | 2 failed / 4 passed. 두 건 모두 `outcome=UNAUTHENTICATED sent=true credentials=include state=authenticated scopeCurrent=true`, `expected 'authenticated' to be 'unauthenticated'`. 기존 4건 통과(09-ctrl에서도 통과) → 09-02 | 612s · 1.45 |
|
||||
| 09-probe-downstream | `corepack pnpm -s check:types:app; …:node; …:test; run-vitest.ts run tests/unit/product-extension-typecheck.test.ts` | 다운스트림 흉내: `product-capabilities.ts`에 `r4NoticeSettings` 타입, `product-composition.ts`가 그 값을 돌려줌, 새 `src/contexts/r4-notice-context/`와 `src/features/r4-notice-feature/`(`needs: ["r4NoticeSettings"]`), 생성기 실행. 템플릿 파일은 고치지 않음(`git status`: M 2 + ?? 2) | 0(명령 묶음) | `APP_RC=0`, `NODE_RC=0`, `TEST_RC=0`. 탐침 `PROBE_RC=1`: `runtime-adapters.ts(695,5): error TS2741: Property 'r4NoticeSettings' is missing in type 'Readonly<{ typecheckProbeSettings: …`. 대조군 09-ctrl에서 탐침 통과 → 09-01 | 614s · 1.45 |
|
||||
|
||||
직접 돌린 4개 모두 helper가 `restored: clean at 8a442262`를 출력했다. `REFUSED`·`RESTORE FAILED`는 없었다. 09-R1은 오케스트레이터가 `8a44226`으로 되돌린 checkout에서 돌렸고 restore=clean이다(`scratchpad/r4/results/09/09-R1.log`).
|
||||
|
||||
오케스트레이터 결과(인용, 이 영역이 기대는 것만, 20시 전후 확인):
|
||||
|
||||
- `gates/`(local env): `check:architecture`·`check:types`·`lint`·`test:unit`·`test:component`·`test:integration`·`test:contract`·`test:runtime-schema` rc=0. `test:unit`은 194 files / 2,883 tests 통과이고, 이 영역의 `product-extension-typecheck.test.ts`(1 test), `runtime-adapters-auth-profile.test.ts`(16), `runtime-adapters-credential-order.test.ts`(10)가 들어 있다. `verify:documentation` rc=1: 짝 백엔드 sibling 경로가 없어서다(`docs/manual/04-paired-backend-session.md`가 `../clean-architecture-backend-template/docs/manual/07-authorization.md`를 가리킴 등). 오케스트레이터가 따로 다루는 환경 조건이라 이 영역 발견으로 세지 않았다.
|
||||
- `merge-48/`(CI=true): FE-GATE-001~012·020 rc=0, FE-GATE-013 rc=1(원인은 오케스트레이터가 다룬다. 이 영역의 테스트를 돌리는 게이트가 아니다). FE-GATE-005(`test-unit`, 탐침 포함), FE-GATE-007(`test-recipes`, 세션 owner recipe 포함), FE-GATE-020(생성 드릴의 `--with-create --keyed` slice 포함, 1,156s).
|
||||
- 이 결과는 모두 템플릿 출하 상태다. 09-01·09-02는 출하 상태에서 드러나지 않는다(09-probe-downstream, 09-cookie401).
|
||||
|
||||
## 7. 새 발견 요약
|
||||
|
||||
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|
||||
|---|---|---|---|---|
|
||||
| 09-01 | Medium·P1 | 확인된 결함 | 제품 확장 타입 검사 탐침이 제품 소유 파일 둘을 덮어써, 기능이 제품 capability를 쓰는 다운스트림에서 FE-GATE-005가 실패한다 | `tests/unit/product-extension-typecheck.test.ts:41-83`, `:181-193`; `src/bootstrap/runtime-adapters.ts:689-697` |
|
||||
| 09-02 | Medium·P2 | 확인된 결함 | Redis session 모드를 recipe·매뉴얼대로 이으면 서버 401이 세션 owner에 닿지 않는다(1103/09-01 수정과 1103/09-03 recipe 불일치) | `src/bootstrap/runtime-adapters.ts:583-591`; `recipes/session-owners/cookie-session-owner.ts:33`, `:179`; `docs/manual/04-paired-backend-session.md:186`, `:238-249` |
|
||||
| 09-03 | Low·P3 | 확인된 결함 | 계약 조립 오류의 원인이 `check:registries` 출력에 두 번 나온다 | `src/contracts/external-contract-runtime.ts:293`; `scripts/check-registries.ts:158-163` |
|
||||
@@ -0,0 +1,229 @@
|
||||
# 영역 10 — 테스트: 빠른 계층
|
||||
|
||||
> 검토일 2026-11-05 · 기준 `8a44226`(`fix/maturity-review-2026-11-03`, PR #4와 같은 커밋)
|
||||
> 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` · 지난 문서: `docs/reviews/2026-11-03-maturity-review/10-tests-fast-layers.md`(기준 `e40684b`)
|
||||
> 경로: `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 영역)
|
||||
> 깊게 본 관점: 10 테스트, 12 동시성, 20 개발자 경험, 21 Guardrail
|
||||
> 렌즈: (1) 지난 라운드 생존 변이가 지금 잡히는가. (2) 1103/10-01이 한도만 올려 고친 것인가. (3) `e40684b..8a44226`의 테스트 변경이 검사를 약하게 했는가.
|
||||
> 영역 판정(35.8): **지정 범위에서 사용 가능** — 템플릿 상태의 머지 게이트로 쓴다. 지난 조건 둘(10-02 Envelope 경계, 10-01 부하 실패)이 모두 풀렸다. 샘플을 지운 제품은 새 10-01의 두 규칙을 제품 테스트로 다시 고정해야 같은 검출력이 남는다.
|
||||
|
||||
## 0. 결론
|
||||
|
||||
- **지난 라운드에 살아남은 변이 15종 중 14종이 이제 잡힌다.** Envelope 경계 6종(H14·H45·H15·H23·H10b·M7), CSRF 3종(H18·H19·07-02 M3), V3 동작 4종(H53·H56·H57·H21), 세션 복구 분기(L02)다. 남은 하나는 §10.8 마지막 검사(L01, 0929/10-04)다. 네 라운드째 아무 테스트도 고정하지 않는다(107파일 995개 통과).
|
||||
- **수정 뒤에 생긴 규칙도 대부분 고정됐다.** 5xx 결과 불명 답의 status 대조(E7), 선언 목록이 멱등 code와 표의 code를 바꾸지 못하는 규칙(E8·E9)을 넣은 변이가 모두 새 테스트에서 실패했다.
|
||||
- **1103/10-01은 한도만 올린 수정이 아니다.** 테스트가 준비 신호(fd 3의 1바이트)를 받은 뒤에 stdin을 닫는다(`tests/unit/task3-selective-integration.test.ts:247-273`, `:174`). 기동은 따로 5초 watchdog으로 잰다(`:272`). desktop에서 한 코어에 바쁜 이웃 6개를 둔 조건(지난 F5)이 5/5 통과했고, 이웃 14개도 3/3 통과했다. EOF 처리를 지운 변이(P1)는 잡혔다.
|
||||
- **약하게 만든 검사는 찾지 못했다.** skip·todo·only가 새로 들어오지 않았다. 늘어난 시간 한도는 새 테스트의 것이거나 일이 늘어난 테스트의 것이다. 바뀐 기대값은 수정이 동작을 바꾼 자리다(3.0절 표). 다만 `6407904c`가 세션 복구 단언을 "보호 라우트가 있으면 본다"로 바꿔, 샘플을 지운 상태에서는 대상이 없다(새 10-01).
|
||||
- **새 발견 2건, 모두 Low·P3다.** 10-01: 수정이 더한 플랫폼 규칙 테스트 둘(`MAX_RETRY_ATTEMPTS` 전달, 복구 중 세션 대기)이 참조 샘플에 기대어, 샘플을 지우면 테스트가 함께 사라진다. 10-02: 호출자·scope signal listener 정리는 고정됐지만, 같은 자리의 interaction signal listener 정리는 지워도 107파일 995개가 통과한다.
|
||||
- **비용 쪽 이월 항목은 커졌다.** `tests/unit` 194파일 중 `scripts`만 보는 파일과 import 없는 파일이 테스트 시간 합의 72%(94.2s / 130.9s)를 쓴다(지난 66%). 한 머지에서 `tests/unit`이 13번 돈다(1101/10-06, 2절).
|
||||
- **오케스트레이터 게이트(로컬 env):** `test:unit` 194파일 2,883개, `test:component` 40파일 270개, `test:integration` 11파일 189개, `test:contract` 3파일 24개, `test:runtime-schema` 3파일 56개 모두 통과. merge 48회차(CI=true)에서 FE-GATE-004·005·006·020 PASS(인용, 1.1절).
|
||||
|
||||
## 1. 범위 (36.1)
|
||||
|
||||
| 항목 | 기록 |
|
||||
|---|---|
|
||||
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`. 테스트 파일 수(`git ls-files`, `e40684b` 대비): unit 194(+18), component 40(+1), integration 11(+1), contract 3, runtime-schema 3, features 23(+2), platform 29, recipes 7(+4). 지원 코드: helpers 11, mocks 6, `tests/support`는 모두 `browser/` 아래(11 영역). 설정: `vitest.config.ts`, `tests/setup.ts`, `scripts/run-vitest.ts`, `scripts/lib/no-skipped-tests-reporter.ts` |
|
||||
| 커밋·작업 상태·확인 시점 | `8a4422624e81e5d13a3809e212e826ff75aac62b`. 노트북 worktree(HEAD = 기준)에서 읽기만 했다. 실행은 desktop 공유 checkout에서 `exp.sh`로 했고 매번 `restored: clean at 8a442262`를 확인했다. 확인 2026-11-05 19:25~20:10 |
|
||||
| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. Vitest 4.1.12, Node 24.14.0, jsdom 29.1.1, MSW 2.15.0 |
|
||||
| 필수 요구와 규모·운영 목표 | 빠른 계층은 머지 게이트다: FE-GATE-004(runtime-schema), 005(unit·contract·coverage·scale pr, `config/ci/gates.json:1840-1848`), 006(component), 007(integration·HTTP 시나리오·reference-feature·recipes, `:1873-1880`), 020(제거·생성 드릴 안에서 다시, `:2112-2120`). 러너 사양과 허용 실패율은 정해져 있지 않다(U-1) |
|
||||
| 읽은 코드·구성 범위 | 위 설정 전체. `git log`/`git diff e40684b..8a44226`의 영역 경로 114커밋, 94파일(+9,541 / −455). 지난 발견의 수정 커밋 `12395662`, `5d0f8454`, `a94006b9`, `a6b85e87`, `fb206994`, `6407904c`, `1b1d972a`. 변이 대상 코드: `src/adapters/http/backend-envelope.ts`, `http-execution-v3.ts`, `src/bootstrap/runtime-adapters.ts:502`, `src/contracts/external-contract-runtime.ts:525-597`, `realtime-streams.ts:462-473`, `src/presentation/routes/navigation-policy.ts`, `scripts/lib/provider-scope-wrapper.ts`. 드릴: `scripts/test-sample-removal.ts`, `test-feature-scaffold.ts`, `lib/feature-scaffold-drill.ts`, 제거 드릴 셋 |
|
||||
| 읽은 문서(주장으로만) | 지난 영역 문서, 지난 README 10.3·12·13·14절, 수정 커밋 본문 |
|
||||
| 수행한 테스트·실험 | desktop: `10-mut-A`(Envelope 변이 9종), `10-mut-B`(V3·CSRF·이월·EOF 변이 11종), `10-eofload`(1103/10-01 부하 재실행). 세 실행 모두 restore clean. `10-mut-C`(지난 라운드에 잡힌 변이 대조군 4종 + H20)와 `10-eofload-old`(옛 테스트로 같은 부하 대조)는 19:55 실행 규칙 변경(BRIEF-2)으로 취소돼 돌지 않았다. 오케스트레이터 로그에서 unit 파일별 시간을 분류했다(J1) |
|
||||
| 확인하지 못한 범위·이유 | 실제 Gitea 러너(U-1). 옛 EOF 테스트가 desktop의 같은 부하에서 떨어지는지(10-eofload-old 취소, 5절). 테스트별 시간(오케스트레이터 snapshot의 junit이 아직 없다. 파일별 시간만 로그에서 셌다). 브라우저 계층(11 영역) |
|
||||
| 이전 리뷰와 비교 가능한 범위 | 지난 실행 결과는 증거로 쓰지 않았다. 지난 생존 변이는 `8a44226`의 같은 규칙 자리에 다시 넣었다(줄은 바뀌었다, 6절). 파일 분류(J1)는 지난 J1과 같은 기준(import 대상)이다 |
|
||||
|
||||
### 1.1 게이트 결과 (오케스트레이터, `8a44226`, 인용)
|
||||
|
||||
로컬 env(`desktop:/tmp/claude-gates/r4/gates/summary.txt`): `check:architecture`, `check:types`, `lint` rc=0. `test:unit` rc=0(194파일 2,883개, Duration 22.61s, setup 누적 43.97s, tests 130.90s). `test:component` rc=0(40파일 270개, 9.10s). `test:integration` rc=0(11파일 189개, 10.37s). `test:contract` rc=0(3파일 24개). `test:runtime-schema` rc=0(3파일 56개). merge 48회차(CI=true, `merge-48/summary.txt`): FE-GATE-004·005·006 PASS, FE-GATE-020 PASS(1,156s). 이 영역에서는 다시 돌리지 않았다.
|
||||
|
||||
## 2. 지난 발견 재확인
|
||||
|
||||
| 지난 ID | 내용 | 상태 | 근거 |
|
||||
|---|---|---|---|
|
||||
| 1103/10-01 | 자식 프로세스 EOF 테스트가 자식 기동까지 1초 안에 넣는다 | **고쳐짐** | `12395662`. 테스트는 loader로 래퍼를 띄우고(`task3-selective-integration.test.ts:247-265`), loader가 래퍼 import를 끝낸 뒤 fd 3에 1바이트를 쓴다(`:258-259`). 테스트는 그 신호를 받은 뒤 75ms를 기다리고 stdin을 닫는다(`:173-179`). 래퍼에는 top-level await가 없어 import가 끝나면 EOF 처리기가 붙어 있다(`scripts/lib/provider-scope-wrapper.ts:27-51`). 래퍼는 `argv.slice(2)`만 읽어 loader 자리에서도 같다(`:9`). 한도 5초는 멈춤만 본다(`:20-25`, `:180`). 기동은 별도 5초로 재고 "start-up"이라는 이름으로 실패한다(`:267-273`). 그래서 **한도만 올린 수정이 아니다**. 10-eofload: 이웃 0개 156~169ms 5/5, 이웃 6개(지난 F5 조건) 596~610ms 5/5, 이웃 14개 1,172~1,322ms 3/3 통과. P1(EOF 처리기 `:50` 제거): "uses early liveness EOF …" 실패. 완료 기준 둘을 모두 충족했다 |
|
||||
| 1103/10-02 (= 03-08) | Envelope 실패 판정의 경계 다섯 곳 미고정, 처리 중 409 무재전송 미고정 | **고쳐짐** | `5d0f8454`. `tests/unit/backend-envelope.test.ts:29-49`(표 code를 다른 status로, 표 밖 422), `:143-150`(게이트웨이 408·425), envelope 통합 `:898`(409 IN_FLIGHT 한 번만), `:956`(응답 한도 초과 실패 Envelope), `:977`(JSON 아닌 실패 본문). 변이 E1(H14)·E2(H45)·E3(H15)·E4(H23)·E5(H10b)·E6(M7) 모두 잡힘(6절) |
|
||||
| 1103/10-03 (→ 07-02) | 쿠키 쓰기 CSRF 조립 검사를 POST와 `x-xsrf-token` 하나로만 고정 | **고쳐짐** | `a94006b9`. `tests/unit/rest-profile-contract.test.ts:111-137`이 POST·PUT·PATCH·DELETE × (CSRF 없음, `x-tenant-context`만, `x-csrf-token`, `x-xsrf-token`)과 GET·HEAD를 돈다. C1(H18, POST만)·C2(H19, `x-csrf-token` 허용 삭제)·C3(07-02 M3, "아무 필수 헤더") 모두 잡힘 |
|
||||
| 1103/10-04 | V2 삭제로 V3 동작 셋이 머지 게이트 보호를 잃음 | **고쳐짐(템플릿 상태)** | `a6b85e87`, `a94006b9`. ① `tests/features/reference-feature/reference-runtime-composition.test.ts:163-204`(FE-GATE-007의 `test-reference-feature`) — R1(H53) 잡힘. ② `tests/unit/http-execution-v3.test.ts:764-805` — R2(H56)·R3(H57) 잡힘. 이제 nightly 테스트가 아니라 머지 게이트 테스트가 잡는다. ③ `tests/unit/realtime/realtime-stream-registry.test.ts:226-316` — R4(H21) 잡힘. 남은 것 둘은 새 발견으로 적었다: ①이 샘플에 기댄다(새 10-01), 같은 자리의 interaction signal 정리는 고정되지 않았다(새 10-02) |
|
||||
| 1101/10-03 | 보호 라우트의 세션 복구 대기 분기 미고정 | **고쳐짐(템플릿 상태)** | `fb206994` 뒤 `6407904c`. `tests/unit/navigation-policy.test.ts:40-56`이 보호 라우트마다 `recovery-pending → wait-for-session`을 단언한다. L02 잡힘("treats every non-public route as explicitly session-required"). 샘플을 지우면 보호 라우트가 0개라 단언 대상이 없다(새 10-01) |
|
||||
| 1101/10-05 | `tests/unit`에 도구 테스트가 섞여 시간 대부분을 씀 | **남음 — 커짐** | J1: 194파일 중 `src`만 116파일 23.3s(18%), `scripts`만 51파일 72.6s(55%), 둘 다 12파일 12.4s(9%), import 없음(자식 실행) 15파일 22.6s(17%). 합 130.9s. 지난 라운드는 `scripts`만 44파일 51% + import 없음 11파일 15% = 66%였다. 가장 긴 파일 셋은 모두 도구 테스트다: `documentation-readiness.test.ts` 17.0s, `product-extension-typecheck.test.ts` 11.0s(새 파일), `ci-workflow-generation.test.ts` 7.5s. `tests/scripts`는 여전히 2파일이고 `test:coverage`에서만 돈다(`package.json:83`) |
|
||||
| 1101/10-06 | 머지 단계가 빠른 계층을 여러 번 돌림 | **남음 — 커짐** | 다시 셌다. FE-GATE-005: `test:unit`, `test:coverage`(2번, `gates.json:1843-1845`). FE-GATE-020: `test:sample-removal`이 샘플 제거 뒤와 생성 기능을 더한 뒤 두 단계에서 `test:all`·`test:coverage`(4번, `scripts/test-sample-removal.ts:445-446`, `:503`). `test:feature-scaffold`가 merge 명령 전체에서 `test:unit`·`test:coverage`(2번, `scripts/test-feature-scaffold.ts:100-102`), 그 안의 생성 기능 제거 드릴에서 다시 2번(`:104`, 16-02 수정으로 생김). 제거 드릴 셋의 `test:all`(3번, `test-optional-recipe-removal.ts:73`, `test-realtime-runtime-removal.ts:128`, `test-browser-file-storage-runtime-removal.ts:179`). **한 머지에 `tests/unit`이 13번 돈다.** 같은 방법으로 `e40684b`를 세면 11번이다. 지난 문서의 "최대 5번"은 드릴 셋과 sample-removal 두 단계를 세지 않은 값이다. FE-GATE-020은 merge 48회차에서 1,156초 걸렸다 |
|
||||
| 1101/10-07 | 프로덕션 시간 상수를 실제 시계로 기다림 | **남음** | `tests/unit/service-worker-runtime.test.ts:2006-2022`("bounds a stream that never produces a chunk")는 가짜 타이머 없이 `ACTIVATION_MARKER_READ_DEADLINE_MS = 5_000`(`src/adapters/service-worker/service-worker-lifecycle.ts:558`)을 기다린다. 파일 시간 5,221ms. `browser-rpc-remediation.test.ts` 파일 시간 4,451ms. 테스트별 시간은 snapshot junit을 보지 못해 세지 않았다 |
|
||||
| 1101/10-08 | `scopeSnapshot` 갈라진 복사본 | **남음** | 공유 도우미 두 곳(`tests/helpers/traffic-test-kit.ts:13`, `tests/component/application-query-fixture.tsx:20`) 밖에 4개 파일이 각자 정의한다(`reference-diagnostics.test.ts:7`, `http-execution-v3-auth-profile.test.ts:41`, `-live-authority.test.ts:23`, `-observability.test.ts:24`). `identities: Object.freeze({}) as never`는 10곳(그중 `tests/scale` 1곳). `deferred()` 7벌 그대로 |
|
||||
| 0929/10-01 | 실행 속도에 기대는 테스트 | **고쳐짐** | 지난 라운드에 남은 한 곳(task3 EOF)이 1103/10-01로 고쳐졌다 |
|
||||
| 0929/10-04 | §10.8 마지막 검사(오래된 scope의 성공 응답 버림) 미고정 | **남음 — 네 라운드째** | L01: `src/adapters/http/http-execution-v3.ts:1493-1499`의 조건을 `false`로 바꿔도 대상 2파일 80개, 관련 107파일 995개가 통과했다. 지금 scope fence 테스트(`tests/unit/http-execution-v3.test.ts:532-627`)는 signal도 함께 abort해 앞 단계 검사가 먼저 잡는다 |
|
||||
| 0929/10-05 | `test:all`이 CI 빠른 테스트 일부를 빠뜨림 | **남음 — 범위 넓어짐** | `package.json:85`는 `tests/features` 중 `test:reference-feature`만 돈다. 새 `tests/features/platform-examples-feature`(2파일, `b96d61d8`)와 `tests/scripts`는 `test:coverage`(`:83`)에서만 돈다 |
|
||||
| (지난 2절) `boot-unexpected-failure.test.tsx`의 `vi.stubGlobal` 미복원 | | **고쳐짐** | `1b1d972a`. `tests/component/boot-unexpected-failure.test.tsx:19-23` `afterEach(vi.unstubAllGlobals)`. `vi.stubGlobal`을 쓰는 나머지 두 파일도 unstub이 있다 |
|
||||
| (지난 2절) `test:platform`만 `--no-file-parallelism`, 이유 없음 | | **남음** | `package.json:141` |
|
||||
| (지난 2절) `test:runtime-schema`의 `--passWithNoTests` | | **남음** | `package.json:50`. `test:recipes`(`:58`), `test:reference-feature`(`:81`)도 같다 |
|
||||
| (지난 R1) 전역 setup이 DOM 없는 unit에도 RTL을 읽음 | | **남음** | `tests/setup.ts:1-3`. unit setup 누적 43.97s(1.1절) |
|
||||
| (지난 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-26` |
|
||||
|
||||
틀린 발견으로 판정한 지난 항목은 없다. 지난 문서 1101/10-06 행의 "최대 5번"은 셈이 모자랐다(위 행).
|
||||
|
||||
## 3. 이번 발견 (36.3)
|
||||
|
||||
새 발견 2건 — 심각도 Low 2 · 우선순위 P3 2 · 성격 구조적 위험 2. High 이상과 P1은 없다.
|
||||
|
||||
### 3.0 검사를 약하게 했는지 (`git diff e40684b 8a44226 -- <영역 경로>`)
|
||||
|
||||
지운 테스트 파일은 없다(이름 바꿈 1: `starter-ui-gallery-page.test.tsx` → `tests/features/platform-examples-feature/ui-gallery-page.test.tsx`). 새 `it.skip`·`todo`·`only`·`skipIf`·`context.skip()`는 없다(`git grep`, 0건). `vitest.config.ts:38` `allowOnly: false`와 `scripts/run-vitest.ts:66-72`의 skip reporter는 그대로다. 지운 `expect`가 있는 자리는 모두 아래 표에 있다.
|
||||
|
||||
| 커밋 | 바뀐 것 | 판정 |
|
||||
|---|---|---|
|
||||
| `12395662` | EOF 대기 1,000ms → 5,000ms, 테스트 제한 기본 10s → 15s(`task3-selective-integration.test.ts:180`, `:184`) | 약화 아님. 기동을 준비 신호로 한도 밖에 뺐다. 래퍼에는 EOF 마감 같은 프로토콜 요구가 없다. P1이 잡혀 검출력이 남은 것을 확인했다 |
|
||||
| `6407904c` | 세션 복구 단언을 "보호 라우트 하나를 찾고 없으면 실패"에서 "보호 라우트 반복 안"으로(`navigation-policy.test.ts:40-56`) | 템플릿 상태에서는 같다(L02 잡힘). 샘플을 지운 상태에서는 대상이 없다. 바꾼 이유는 제거 드릴이 그 테스트로 떨어졌기 때문이다(커밋 본문). → 새 10-01 |
|
||||
| `c9e7bab2` | 기능당 초기 JS 상한: 첫 복사본(기능+새 context) ≤ 1,024 B → 같은 context의 기능 ≤ 1,024 B, 새 context ≤ 512 B, 기록과 ±10% 대조(`feature-shape-growth.test.ts:150-166`). 테스트 제한 120s → 180s | 약화로 세지 않음. 1103/15-04 권고대로 기준을 나눴다. 새 context의 첫 기능 합계 상한은 1,024 → 1,536 B로 넓어졌다. 대신 기록 대조(`scripts/scale/measure-feature-shape-growth.ts:234-247`)가 새로 생겨, 비용이 10% 넘게 움직이면 기록을 다시 써야 통과한다. 시간 제한은 빌드가 2번에서 3번으로 는 만큼이다(`:214-225`). 기준 숫자의 적절성은 15 영역 몫이다 |
|
||||
| `b96d61d8` | FEATURE_OVERRIDES 테스트 반복 대상을 설치 기능 전체에서 API를 기여하는 기능으로(`runtime-adapters.test.ts:64-70`, `:380`, `:420`) | 약화 아님. 새 예제 기능은 application API가 없어 "API를 주지 않는다"는 규칙의 대상이 아니다 |
|
||||
| `d13a3936` | purge와 겹친 put의 기대: "늦은 put이 읽힌다" → `NOT_FOUND`, partition 삭제 | 약화 아님. 05-01 수정이 동작을 바꿨고 단언이 늘었다(`opfs-worker-runtime.test.ts`) |
|
||||
| `af000673` | 실패 kind 기대 `OFFLINE` → `PROVIDER_UNAVAILABLE` | 약화 아님. 04-04 동작 변경 |
|
||||
| `2d5d41f8` | 저장 중 버튼 `toBeDisabled()` → `aria-busy`·포커스 단언 | 약화 아님. 08-02 동작 변경. 두 번 눌러도 한 번만 보낸다는 단언은 남았다(`reference-page.test.tsx:334`) |
|
||||
| `b6bfc9b7` 등 | 문서 검사 테스트의 route ID 정규식을 `REFERENCE_RESOURCE_*` → `[A-Z]+_RESOURCE_*`(`documentation-readiness.test.ts:88`) | 약화 아님. 지운 뒤에도 문서 검사가 통과하는지 보는 테스트라, 지우는 범위를 넓힌 것이다 |
|
||||
| 새 테스트의 시간 제한 | 30s ×2(`architecture-lint-fixtures`), 60s(`second-api-feature-registries`), 120s(`product-extension-typecheck`) | 새 테스트의 것이다. 기존 한도를 올린 것이 아니다 |
|
||||
|
||||
### 10-01 수정이 더한 플랫폼 규칙 테스트 둘이 참조 샘플에 기대어, 샘플을 지우면 함께 사라진다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 구조적 위험(검출 공백, 샘플 제거 상태) |
|
||||
| 관련 관점 | 10, 27, 21, 3, 19 |
|
||||
| 근거 | ① `MAX_RETRY_ATTEMPTS` 전달(1103/10-04 ①의 수정). 유일한 테스트가 `tests/features/reference-feature/reference-runtime-composition.test.ts:163-204`에 있다. 샘플 제거는 `tests/features/<샘플>`을 지운다(`scripts/test-sample-removal.ts:130`, `:159-161`). 남는 플랫폼 테스트 `tests/unit/runtime-adapters.test.ts`(`:140`의 공통 목록)에는 이 단언이 없다. 커밋 `a6b85e87` 본문도 "샘플을 지운 제품에서는 이 테스트도 같이 빠진다"고 적는다. 같은 자리의 `REQUEST_TIMEOUT_MS`(`src/bootstrap/runtime-adapters.ts:507`)도 지난 라운드부터 `reference-production-vertical.test.tsx`만 잡는 같은 모양이다. ② 복구 중 세션 대기(1101/10-03의 수정). `tests/unit/navigation-policy.test.ts:40-56`은 설치된 보호 라우트를 돌며 단언한다. 보호 라우트는 참조 기능에만 있다(`src/features/reference-feature/contracts/reference-feature-contract.ts:27`, `:41`, `:54`, `:67`). 샘플을 지우면 반복이 0번이라 `navigation-policy.ts:20-22`를 지켜도 지우지 않아도 통과한다. ③ 제거 드릴은 이 손실을 알리지 않는다. 드릴의 공통 테스트 검사는 파일이 남았는지만 본다(`test-sample-removal.ts:132-150`). 그 주석은 "플랫폼 자신의 커버리지를 기능과 함께 조용히 지워 통과하는 것"을 막는다고 적는다 |
|
||||
| 발생 조건 | 제품이 템플릿 안내대로 참조 샘플을 지운 뒤, 플랫폼 파일(`runtime-adapters.ts`, `navigation-policy.ts`)을 고치거나 템플릿 동기화에서 충돌을 손으로 풀 때 |
|
||||
| 영향 | 제품 CI에서 운영자의 재시도 끄기 손잡이(`MAX_RETRY_ATTEMPTS: 0`)나 요청 마감 상한이 조용히 무시돼도 통과한다. 세션 복구 중인 사용자가 보호 화면에서 로그인 화면으로 튕겨도 통과한다. 템플릿 CI(샘플 있음)는 계속 잡는다 |
|
||||
| 심각도·우선순위 | Low · P3 — 지금 코드는 맞고 템플릿 CI가 지킨다. 플랫폼 파일은 제품이 고치지 않는 것이 원칙이라 닿는 경로가 좁다. 그러나 0929/10-02에서 고친 원칙("샘플을 지워도 플랫폼 검사가 남는다")을 새 수정 둘이 다시 어겼다 |
|
||||
| 확실성과 남은 가정 | 테스트 위치와 제거 범위, 보호 라우트 분포는 코드로 확인했다(E1). 샘플을 지운 복사본에 변이를 넣어 돌리지는 않았다(5절) |
|
||||
| 결정의 근거 | [확인한 사실] `createRuntimeAdapters`는 설치된 기능의 HTTP가 있어야 조립 루트를 탄다(`a6b85e87` 본문). `decideRouteAccess`는 설치된 라우트 레지스트리(`getRoute`)를 읽는다(`navigation-policy.ts:15`). 그래서 테스트 전용 기능을 주입할 자리가 없다. [추론] 두 테스트가 샘플에 기댄 것은 테스트 작성자의 실수보다 조립 입력을 바꿀 수 없는 구조 탓이다 |
|
||||
| 이해 비용 | 제품 작성자는 어느 플랫폼 규칙이 샘플 테스트에만 고정돼 있는지 알 수 없다. 알려면 제거 드릴 목록과 테스트를 맞춰 봐야 한다 |
|
||||
| 최소 개선 방향 | ⓐ 두 규칙을 샘플 밖에서 고정한다. `MAX_RETRY_ATTEMPTS`는 `createContractHttpExecutor`를 `runtime-adapters.ts`와 같은 방식으로 조립하는 작은 함수로 빼고 그 함수를 `tests/unit`에서 시험한다. 라우트 결정은 `decideRouteAccess`가 라우트 정의를 인자로 받는 순수 함수를 하나 두고 `tests/helpers/fixture-feature.tsx`의 보호 라우트로 시험한다. ⓑ 지금 테스트를 두고, 제거 드릴이 샘플 제거 뒤 "보호 라우트 반복 0번"처럼 대상이 빈 단언을 알리게 한다. ⓒ 현 상태를 유지하고 매뉴얼에 "샘플을 지우면 이 두 규칙을 제품 테스트로 다시 고정한다"고 적는다 |
|
||||
| 대안 비교 | ⓐ 테스트 대상이 샘플과 무관해져 원인을 없앤다. 운영 코드에 함수 경계가 하나씩 는다. ⓑ 실패를 알리지만 제품이 결국 테스트를 새로 써야 한다. ⓒ 가장 싸지만 사람이 기억해야 한다. [추론] ⓐ를 고른다. 0929/10-02를 고칠 때 쓴 방식(테스트 전용 기능)과 같은 방향이다 |
|
||||
| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다 |
|
||||
| 비용·부작용 | 함수 경계 둘, 테스트 수십 줄 |
|
||||
| 재검토 조건 | 조립 루트가 테스트 전용 contract 기여를 받게 되면 ⓐ의 함수 분리 없이 `runtime-adapters.test.ts`로 옮긴다 |
|
||||
| 완료 기준 | 샘플을 지운 복사본에서 H53(`runtime-adapters.ts:502` 상수 2)과 L02(`navigation-policy.ts:21` → `show-sign-in`)가 각각 `test:all`에서 실패한다 |
|
||||
| 검증 방법 | `test:sample-removal` 복사본에 두 변이를 넣고 `test:all` |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규(1103 수정 `a6b85e87`, `6407904c`에서 생김) |
|
||||
|
||||
### 10-02 interaction signal에 단 abort listener 정리는 지워도 모든 테스트가 통과한다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 구조적 위험(검출 공백) |
|
||||
| 관련 관점 | 10, 12, 14, 21 |
|
||||
| 근거 | 실행기는 호출자·interaction·scope 세 signal에 abort listener를 단다(`src/adapters/http/http-execution-v3.ts:634-652`). 끝날 때 셋을 모두 지운다(`:662-664`). 1103/10-04 ②의 새 테스트(`tests/unit/http-execution-v3.test.ts:764-805`)는 호출자와 scope signal만 감시한다. 변이 R2b(`:663` interaction 쪽 제거)가 대상 1파일 69개와 관련 107파일 995개를 통과했다(`10-mut-B`). 같은 자리의 R2(호출자)·R3(scope)는 잡혔다 |
|
||||
| 발생 조건 | 이 정리 줄을 리팩터링할 때. 기능이 `ExecutionContext`(`src/platform/execution/execution-context.ts:31-60`)를 넘겨 한 interaction 안에서 요청을 여러 번 보낼 때 드러난다(`reference-feature-api.ts:20`이 받는 자리다) |
|
||||
| 영향 | 요청마다 listener 하나(그 요청의 lifetime controller를 잡은 closure)가 interaction signal에 남는다. interaction은 마감이 있어(`MAX_INTERACTION_DEADLINE_MS`, `http-execution-v3.ts:565-576`) 남는 기간은 그 마감까지다. 그래서 피해는 1103/10-04 ②(세션 scope, 오래 산다)보다 작다 |
|
||||
| 심각도·우선순위 | Low · P3 — 지금 코드는 맞다. 남는 기간이 짧다. 고치는 비용은 기존 테스트에 signal 하나를 더하는 정도다 |
|
||||
| 확실성과 남은 가정 | 변이 생존은 확인했다(E2). 실제 누수량은 재지 않았다 |
|
||||
| 결정의 근거 | 적용 제외 — 테스트 경우 누락이다 |
|
||||
| 이해 비용 | 작다. 테스트 이름("caller and scope signals")이 감시 범위를 말한다 |
|
||||
| 최소 개선 방향 | 같은 테스트에서 `execution: createExecutionContext(...)`을 넘기고 그 `cancellation.signal`도 감시 목록에 넣는다 |
|
||||
| 대안 비교 | 적용 제외 |
|
||||
| 단순화의 보존 조건 | 적용 제외 |
|
||||
| 비용·부작용 | 테스트 몇 줄 |
|
||||
| 재검토 조건 | 적용 제외 |
|
||||
| 완료 기준 | R2b가 `http-execution-v3.test.ts`에서 실패한다 |
|
||||
| 검증 방법 | 6절 R2b 재실행 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규(1103/10-04 ② 수정의 남은 자리, 03 영역 코드) |
|
||||
|
||||
## 4. 28개 관점 판정 (36.2)
|
||||
|
||||
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역. 굵은 번호가 깊게 본 관점이다.
|
||||
|
||||
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | 코드 성숙도 | > 03·07 | — | — | 변이는 모두 테스트 검출력을 본 것이다. 새 코드 결함은 찾지 않았다 |
|
||||
| 2 | 구조적 성숙도 | > 16 | — | — | — |
|
||||
| 3 | 변경 용이성 | 적용 | M2 / M2 | E1 | **P** — 테스트 전용 fixture(`tests/helpers/external-contract-fixture.ts`, `runtime-config.ts`, `memory-opfs.ts`)로 새 테스트를 쉽게 만든다. 조립 루트와 라우트 결정은 테스트 입력을 바꿀 자리가 없어 샘플에 기댄다(10-01) |
|
||||
| 4 | 인지 부하 | 적용 | M2 / M2 | E1 | **P** — 한 unit 파일이 한 머지에서 몇 번 도는지 알려면 `gates.json`과 드릴 스크립트 다섯 개를 맞춰야 한다(13번, 1101/10-06) |
|
||||
| 5 | 위험 가시성 | 적용 | M2 / M2 | E1·E2 | **P** — 제거 드릴 주석은 플랫폼 커버리지 보존을 약속하지만 파일 존재만 본다(10-01). EOF 테스트는 기동 실패를 "start-up"으로 따로 알린다(1103/10-01 고쳐짐) |
|
||||
| 6 | 실패 성숙도 | 적용 | M3 / M3 | E2 | **P** — Envelope 실패 경계 9종이 모두 잡힌다. 오래된 scope의 성공 응답 버림(L01)은 아무도 고정하지 않는다 |
|
||||
| 7 | 운영 성숙도 | - | 테스트 계층 밖 | — | — |
|
||||
| 8 | 디버깅 가능성 | 적용 | M2 / M3 | E2·E3 | **O** — EOF 테스트가 기동과 EOF를 다른 이름으로 실패한다(`task3-selective-integration.test.ts:180`, `:272`). skip reporter가 이유와 다음 행동을 출력한다. 변이 실패 이름이 바꾼 규칙을 그대로 말한다(6절) |
|
||||
| 9 | 유지보수 성숙도 | 적용 | M2 / M1 | E1 | **P** — `scopeSnapshot` 4벌, `as never` scope 10곳, `deferred()` 7벌(1101/10-08). `test:platform`의 `--no-file-parallelism` 이유 없음 |
|
||||
| **10** | **테스트 성숙도** | 적용 | 목표 M3 / 확인 M3 | E2(변이 20종), E3(부하) | **P** — 지난 생존 변이 15종 중 14종이 잡힌다. 새 규칙 변이 3종(E7~E9)과 EOF 변이가 잡힌다. 남은 생존 2종: L01(네 라운드째), R2b(10-02). 샘플 제거 상태의 검출 공백(10-01) |
|
||||
| 11 | 데이터 성숙도 | > 05 | — | — | Envelope 판정 경계가 고정돼 짝 백엔드 쓰기 중복 위험(지난 10-02)이 테스트로 막힌다 |
|
||||
| **12** | **동시성 성숙도** | 적용(테스트 격리·CPU 경쟁) | M3 / M3 | E3 | **O** — 테스트 사이 상태 격리(`vitest.config.ts:40-42`, `tests/setup.ts:15-20`), 전역 stub 복원(`boot-unexpected-failure.test.tsx:19-23`). 한 코어에 이웃 14개를 둬도 자식 프로세스 테스트가 통과한다(10-eofload). 실제 러너 사양은 미확인(U-1) |
|
||||
| 13 | 확장성 | > 11·15 | — | — | — |
|
||||
| 14 | 성능 성숙도 | 적용(테스트 실행 비용) | M2 / M1 | E2 | **P** — unit 테스트 시간 합 130.9s 중 도구·자식 실행 테스트가 72%(1101/10-05 커짐). 한 머지에 `tests/unit` 13번(1101/10-06 커짐). 실제 시계 5초 대기 남음(1101/10-07). setup 누적 44.0s(R1) |
|
||||
| 15 | 보안 성숙도 | 적용(보안 규칙의 테스트) | M3 / M3 | E2 | **O** — 쿠키 쓰기 CSRF 조립 검사가 method 4종 × 헤더 4종으로 고정됐다(C1~C3 잡힘) |
|
||||
| 16 | 의존성 성숙도 | > 13 | — | — | — |
|
||||
| 17 | API / Contract 성숙도 | 적용(계약 테스트) | M3 / M3 | E2 | **P** — Envelope 판정 표, 5xx 결과 불명 표, 선언 목록 규칙, realtime snapshot 바인딩(6 method × 4 retry)이 고정됐다. FE-REG-API `authProfileId`(H20)는 fixture가 모두 `ANONYMOUS`라 빠른 계층이 여전히 못 본다(`check:registries` 몫, 정적 판단, 5절) |
|
||||
| 18 | 배포 성숙도 | > 13 | — | — | — |
|
||||
| 19 | 설정 성숙도 | 적용(러너·런타임 설정) | M3 / M2 | E2 | **P** — `MAX_RETRY_ATTEMPTS` 전달이 머지 게이트에서 고정됐지만 샘플에 기댄다(10-01). `--passWithNoTests` 3곳 남음 |
|
||||
| **20** | **개발자 경험** | 적용 | M2 / M2 | E2·E3 | **P** — 부하 거짓 실패의 원인이 사라졌다. `test:all`이 CI 빠른 테스트 일부(예제 기능 2파일, `tests/scripts`)를 빠뜨린다(0929/10-05). FE-GATE-020이 1,156초다 |
|
||||
| **21** | **Guardrail 성숙도** | 적용 | M3 / M3 | E2 | **P** — skip·todo·only 차단 유지. 이번 diff에 약화된 검사 없음(3.0절). 플랫폼 규칙의 유일한 테스트가 샘플과 함께 지워지는 것을 드릴이 알리지 않는다(10-01) |
|
||||
| 22 | 추상화 성숙도 | 적용(테스트 도우미) | M2 / M2 | E1 | **P** — 새 공유 도우미 셋(`runtime-config.ts`, `memory-opfs.ts`, `external-contract-fixture.ts` 확장). scope fixture 복사본은 그대로 |
|
||||
| 23 | 일관성 | 적용 | M2 / M2 | E1 | **P** — 자식 프로세스 대기 방식이 준비 신호 하나로 맞춰졌다(guardian, task3). `deferred()` 7벌 |
|
||||
| 24 | 네이밍 / 의미 성숙도 | 적용 | M2 / M2 | E2 | **O** — 지난 라운드에 범위보다 넓게 읽히던 두 테스트 이름이 이제 맞다("refuses a %s whose cookie profile…", Envelope 표 테스트). 새 listener 테스트 이름은 감시 범위(caller and scope)를 정확히 말한다 |
|
||||
| 25 | 조직 확장성 | - | 작성자 1인 | — | — |
|
||||
| 26 | Ownership 성숙도 | 부분 적용 | M2 / M1 | E1 | **P** — `ungated-tests.json` 항목에 담당·재검토 시점이 없다(12 영역) |
|
||||
| 27 | 삭제 가능성 | 적용 | M3 / M2 | E1 | **P** — V2 삭제가 남긴 보호 공백 세 곳이 메워졌다. 대신 샘플 삭제가 플랫폼 규칙 테스트 둘을 함께 지운다(10-01) |
|
||||
| 28 | 회복 가능성 | - | 테스트 계층 밖 | — | — |
|
||||
|
||||
집계(적용 19개, `>`·`-` 제외): 충족 4(8, 12, 15, 24) · 부분 충족 15 · 미충족 0 · 미검증 0. 지난 라운드는 충족 0 · 부분 충족 18이었다. 8·12·15·24가 오른 근거는 각 행의 실행 증거다. 10번은 남은 생존 변이 2종과 샘플 제거 공백 때문에 P로 둔다.
|
||||
|
||||
## 5. 미검증
|
||||
|
||||
| 항목 | 이유 | 확인하려면 |
|
||||
|---|---|---|
|
||||
| 옛 EOF 테스트가 desktop의 같은 부하(이웃 6·14개)에서 떨어지는지 | `10-eofload-old`가 19:55 규칙 변경으로 취소됐다. 지금 판단은 추론이다: 이웃 14개에서 새 테스트 전체가 1.17~1.32s라, 기동+EOF를 1,075ms 안에 넣던 옛 모양은 넘었을 것이다. 1103/10-01의 완료 기준(F5 5/5 통과, EOF 처리 제거 시 실패)은 이것 없이 충족됐다 | 옛 테스트 파일(`git show e40684b:tests/unit/task3-selective-integration.test.ts`)로 같은 부하 3회 |
|
||||
| 지난 라운드에 잡힌 변이 대조군(H02·H05·H12·H27)과 H20 | `10-mut-C`가 취소됐다. H20은 정적으로 판단했다: 빠른 계층 fixture의 `authProfileId`가 모두 `ANONYMOUS`라(`tests/helpers/external-contract-fixture.ts:36`, `:167`, `tests/unit/api-operation-rows.test.ts:44`) 상수 `ANONYMOUS` 변이는 여전히 빠른 계층을 통과하고 `check:registries`가 잡는다. 지난 라운드와 같아 발견으로 세지 않았다 | 다음 라운드 변이 묶음에 넣는다 |
|
||||
| 샘플을 지운 복사본에서 H53·L02가 통과하는지(10-01) | 정적 근거로 판단했다(E1). 제거 드릴 복사본에 변이를 넣는 실행은 비싸다 | 10-01 완료 기준의 실행 |
|
||||
| 테스트별 시간(1101/10-07의 실제 대기 합) | snapshot junit을 보지 못했다. 파일별 시간만 로그에서 셌다 | `desktop:/tmp/claude-gates/r4/snap/artifacts/tests/unit.xml` |
|
||||
| 실제 CI 러너의 실패율 | CI 꺼짐(U-1) | U-1 뒤 FE-GATE-005·020을 20회 |
|
||||
| 10-02의 실제 누수량 | 재지 않았다 | 한 interaction 안에서 요청 N번 뒤 listener 수 |
|
||||
|
||||
## 6. 실행 기록
|
||||
|
||||
모든 실행은 desktop `exp.sh`(공유 잠금, 기준 `8a44226` 확인 후 실행, 끝나면 `reset --hard` + `clean`)로 했다. 변이 드라이버(`desktop:/tmp/claude-gates/r4/mut/10-driver.mjs`, 원본 scratchpad `r4/10/10-driver.mjs`)는 변이마다 정확한 문자열 하나를 바꾸고(1회 등장 확인), 대상 테스트를 `node scripts/run-vitest.ts run <파일>`로 돈다. 실패한 테스트가 없으면 `related <소스> --run`을 더 돈다. 매번 원본으로 되돌리고, 끝에 `git status`가 비었는지 출력한다. "잡힘"은 실패한 테스트 이름이 바꾼 규칙과 맞는 경우만 적었다.
|
||||
|
||||
| 이름 | 명령 | 변이 | rc · 시간 | 결과 | 잠금 대기 · 부하 | restore |
|
||||
|---|---|---|---|---|---|---|
|
||||
| 10-mut-A | `node /tmp/claude-gates/r4/mut/10-driver.mjs A` | 아래 E1~E9 | 0 · 15s | 무변이 기준: 3파일 156개 통과. 9종 모두 잡힘 | 595s · 1.52 | clean |
|
||||
| 10-mut-B | `node /tmp/claude-gates/r4/mut/10-driver.mjs B` | 아래 R1~P1 | 0 · 63s | 무변이 기준: 9파일 167개 통과. 9종 잡힘, 2종 생존(R2b, L01) | 583s · 1.56 | clean |
|
||||
| 10-eofload | `bash /tmp/claude-gates/r4/mut/10-eofload.sh`: `taskset -c 11`로 테스트 파일 전체 실행, 같은 코어에 `node -e 'for(;;){}'` 이웃 N개 | 없음 | 0 · 98s | 이웃 0: 5/5, EOF 테스트 156~169ms. 이웃 6: 5/5, 596~610ms. 이웃 14: 3/3, 1,172~1,322ms. 파일 7개 모두 통과 | 646s · 7.22 | clean |
|
||||
| 10-mut-C | 대조군 K1~K5 | — | 돌지 않음 | 19:55 취소(BRIEF-2) | — | 해당 없음 |
|
||||
| 10-eofload-old | 옛 테스트로 같은 부하 | — | 돌지 않음 | 19:55 취소(BRIEF-2) | — | 해당 없음 |
|
||||
|
||||
### 6.1 변이
|
||||
|
||||
| ID | 지키는 규칙(지난 ID) | 바꾼 곳(`8a44226`) | 결과 | 잡은 테스트 |
|
||||
|---|---|---|---|---|
|
||||
| E1 | 쓰기 전 거절 = code와 status 둘 다(H14 = 03-08 M6) | `backend-envelope.ts:194` status 대조 제거 | 잡힘(6) | `backend-envelope.test.ts` "reads a table code under another status …" 5, "never lets a declaration decide …" 1 |
|
||||
| E2 | 표 밖 422는 결과 불명(H45) | `:346` `|| status === 422` 제거 | 잡힘(5) | `backend-envelope.test.ts` 4, envelope 통합 "keeps 400, 409, 422 outside the table …" 1 |
|
||||
| E3 | 게이트웨이 408·425는 SERVER_FAILURE(H15) | `:372` 408·425 제거 | 잡힘(2) | `backend-envelope.test.ts` "reads a gateway 408/425 as a server failure" |
|
||||
| E6 | 처리 중 409는 자동 재전송하지 않는다(03-08 M7) | `:364` 409 `IDEMPOTENT_IN_FLIGHT`도 참 | 잡힘(1) | envelope 통합 "does not resend a 409 IDEMPOTENT_IN_FLIGHT on its own" |
|
||||
| E7 | 5xx 결과 불명 답도 status와 code를 함께 본다(새 규칙, `37615072`) | `:275` status 대조 제거 | 잡힘(1) | `backend-envelope.test.ts` "leaves a status the table does not speak for to the package" |
|
||||
| E8 | 선언 목록이 멱등 code를 바꾸지 못한다(새 규칙, `1e8b3d04`) | `:324` 정규식 조건 제거 | 잡힘(1) | "never lets a declaration decide an idempotency answer or a table code" |
|
||||
| E9 | 선언 목록이 표의 code를 바꾸지 못한다(새 규칙) | `:323` 표 조건 제거 | 잡힘(1) | 같음 |
|
||||
| E4 | 실패 Envelope 한도 = min(64 KiB, 응답 한도)(H23) | `http-execution-v3.ts:1636` 항상 64 KiB | 잡힘(1) | envelope 통합 "refuses a failure Envelope above the operation's response limit" |
|
||||
| E5 | 실패 응답 media type 검사(H10b) | `:1657` 조건 `false` | 잡힘(1) | envelope 통합 "refuses a failure Envelope that is not sent as JSON" |
|
||||
| R1 | `MAX_RETRY_ATTEMPTS`가 실행기에 닿는다(H53) | `runtime-adapters.ts:502` 상수 2 | 잡힘(2) | `reference-runtime-composition.test.ts` "honours MAX_RETRY_ATTEMPTS 0/1" |
|
||||
| R2 | 호출자 signal listener 정리(H56) | `http-execution-v3.ts:662` 제거 | 잡힘(2) | `http-execution-v3.test.ts` "removes the listeners … after an answer / a caller abort" |
|
||||
| R3 | scope signal listener 정리(H57) | `:664` 제거 | 잡힘(2) | 같음. 지난 라운드는 nightly `long-session` 하나만 잡았다 |
|
||||
| R2b | interaction signal listener 정리(새로 확인) | `:663` 제거 | **생존**(대상 69개, 관련 107파일 995개) | 없음 → 10-02 |
|
||||
| R4 | realtime snapshot은 GET만(H21 = 04-03) | `realtime-streams.ts:470` → `operation !== undefined` | 잡힘(10) | `realtime-stream-registry.test.ts` HEAD·POST·PUT 등 행 |
|
||||
| C1 | 쿠키 쓰기 CSRF — 모든 쓰기 method(H18 = 07-02 M2) | `external-contract-runtime.ts:589` `!isRead` → `method === "POST"` | 잡힘(3) | `rest-profile-contract.test.ts` "refuses a PUT/PATCH/DELETE …" |
|
||||
| C2 | `x-csrf-token`도 허용(H19) | `:592` `x-csrf-token` 제거 | 잡힘(4) | "accepts a POST/PUT/PATCH/DELETE that requires x-csrf-token or x-xsrf-token" |
|
||||
| C3 | CSRF 헤더 이름만 증명이다(07-02 M3) | `:591-593` → 필수 헤더 수 > 0 | 잡힘(4) | "refuses a %s whose cookie profile requires no CSRF header" |
|
||||
| L01 | §10.8 오래된 scope의 성공 응답 버림(0929/10-04) | `http-execution-v3.ts:1494` 조건 `false` | **생존**(대상 80개, 관련 107파일 995개) | 없음 → 0929/10-04 남음 |
|
||||
| L02 | 복구 중 세션은 보호 라우트에서 기다린다(1101/10-03) | `navigation-policy.ts:21` → `show-sign-in` | 잡힘(1) | `navigation-policy.test.ts` "treats every non-public route as explicitly session-required" |
|
||||
| P1 | EOF를 받으면 명령 프레임 없이 끝난다(1103/10-01 완료 기준) | `provider-scope-wrapper.ts:50` 제거 | 잡힘(1) | `task3-selective-integration.test.ts` "uses early liveness EOF …" (154ms에 code 불일치) |
|
||||
|
||||
집계: 20종 중 18종이 잡혔고 2종이 살아남았다. 지난 라운드 생존 변이를 같은 규칙 자리에 다시 넣은 15종(E1~E6, R1~R4, C1~C3, L01, L02) 중 14종이 잡혔다. 수정 뒤 새 규칙 3종(E7~E9)과 EOF 변이(P1)는 잡혔고, 새로 확인한 R2b는 살아남았다. 관련 실행(`related`)은 생존 변이에만 돌았다.
|
||||
|
||||
### 6.2 그 밖의 분석
|
||||
|
||||
| ID | 방법 | 결과 |
|
||||
|---|---|---|
|
||||
| J1 | 오케스트레이터 `test_unit.log`의 파일별 시간(194줄)을 파일의 import 대상(`src`/`scripts`/둘 다/없음)으로 분류해 합산(노트북, 로그 사본) | 합 130.9s. `src`만 116파일 18%, `scripts`만 51파일 55%, 둘 다 12파일 9%, 없음 15파일 17% |
|
||||
| D1 | `git diff e40684b 8a44226 -- <영역 경로>`에서 지운 `expect`·`it` 줄, 새 skip·시간 한도·정규식·matcher를 파일별로 대조 | 3.0절 표 |
|
||||
| D2 | 한 머지의 `tests/unit` 실행 횟수를 `gates.json` merge stage와 드릴 스크립트에서 셈 | 13번(`e40684b` 11번) |
|
||||
|
||||
## 7. 새 발견 요약
|
||||
|
||||
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|
||||
|---|---|---|---|---|
|
||||
| 10-01 | Low · P3 | 구조적 위험 | 1103 수정이 더한 플랫폼 규칙 테스트 둘(`MAX_RETRY_ATTEMPTS` 전달, 복구 중 세션 대기)이 참조 샘플에 기대어, 샘플을 지우면 함께 사라지고 제거 드릴은 알리지 않는다 | `tests/features/reference-feature/reference-runtime-composition.test.ts:163-204`, `tests/unit/navigation-policy.test.ts:40-56`, `scripts/test-sample-removal.ts:130-161` |
|
||||
| 10-02 | Low · P3 | 구조적 위험 | 실행기가 interaction signal에 단 abort listener 정리는 지워도 모든 테스트가 통과한다(호출자·scope 쪽만 고정) | `src/adapters/http/http-execution-v3.ts:663`, `tests/unit/http-execution-v3.test.ts:764-805` |
|
||||
|
||||
이월(새 발견으로 세지 않음): 0929/10-04(§10.8, L01 생존, 네 라운드째), 1101/10-05·10-06(커짐), 1101/10-07, 1101/10-08, 0929/10-05, `--no-file-parallelism`, `--passWithNoTests`, R1, R6, `tsc-diagnostics-parser` 제외(12 영역). 모두 Low.
|
||||
@@ -0,0 +1,263 @@
|
||||
# 영역 11 — 테스트: 브라우저·릴리스·규모
|
||||
|
||||
> 검토일 2026-11-05 · 기준 `8a44226`(`8a4422624e81e5d13a3809e212e826ff75aac62b`, 브랜치 `fix/maturity-review-2026-11-03`) · 가이드 `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/check-system-test-prerequisites.ts`, `scripts/run-and-validate-provider.ts:240-300`, `scripts/write-a11y-report.ts`, `scripts/create-feature.ts`(목록 페이지 틀 `:1160-1222`), `scripts/drill-runbook.ts`, `tests/unit/runbook-drill.test.ts`, `tests/unit/indexeddb-runtime.test.ts:450-485`, `scripts/generate-ci-workflow.ts`·`.gitea/workflows/quality-gates.yml`(글꼴 단계), `scripts/lib/visual-test-fonts.ts`, `scripts/lib/build-environment.ts`, `config/hosting/security-headers.json`, `config/ci/gates.json`(FE-GATE-008·009·013)
|
||||
> 깊게 본 관점: 10, 21, 8, 20, 18
|
||||
> 이번 라운드 렌즈(오케스트레이터 필수 4건): (1) 1103/11-09 수정 `aad005cb`의 preload 사용 검사가 실패해야 할 때 실패하는가. (2) 1103/11-10 수정 `ee37dd86`의 고정 층이 RED를 없애는가, 무엇을 건너뛰는가. (3) FE-GATE-013 `test:system` 실패 18건 분류. (4) 1103/11-01~11-10과 0929/11-* 이월 항목 상태
|
||||
> 영역 판정(35.8): **조건부 사용 가능.** 오케스트레이터 merge-48(CI env)에서 FE-GATE-008이 통과했다(e2e 202 통과·3 quarantine skip, capability 66, storybook 1, visual 6, 재시도 0). 브라우저 검사의 두 수정(11-09, 11-10)은 변이로 실패 방향까지 확인했다(배치 11-R1~R7). FE-GATE-013은 `test:system` 18건 때문에 실패했고, 18건 모두 호스트 원인이다(11-R10: 이 호스트의 bwrap은 repo 없이도 user namespace를 못 쓴다). 다음은 그대로 믿지 않는다. (a) strict fixture가 preload 결과를 버려도 커밋된 test는 아무것도 실패하지 않는다(새 11-01, 11-R3에서 확인). (b) `test:system`은 bwrap이 user namespace를 못 쓰는 호스트(desktop)에서 사전 점검 PASS 뒤 18건이 샌드박스 회귀처럼 실패한다(새 11-02, 영역 12의 12-01과 같은 결함). (c) 생성 기능의 상세 라우트는 접근성 e2e에서 실패 화면으로 검사되고 `a11y.json`은 "passed"라고 적는다(1103/11-01 남은 것). (d) CI 러너 위 실행은 여전히 없다(U-1)
|
||||
|
||||
ID 표기: 이번 라운드 새 발견은 `11-01`부터 쓴다. 라운드 밖에서는 `1105/11-01`이다. 지난 라운드는 `1103/11-NN`(2026-11-03), 그 전은 `1101/…`, `0929/…`다. `11-Rk`는 `scratchpad/r4/requests/11.md`의 배치 실험이고, 결과 로그는 `scratchpad/r4/results/11/11-Rk.log`다(6절).
|
||||
|
||||
## 0. 결론
|
||||
|
||||
- **1103/11-09(preload 검사)는 고쳐졌다.** strict fixture는 WebKit의 3초 추정 경고 한 문구만 정확한 정규식으로 무시한다(`tests/support/browser/strict-browser-test.ts:16-25`). 대신 세 엔진에서 같은 방법으로 "preload한 build script가 끝까지 실행됐는가"를 본다(`tests/support/browser/preload-use.ts:117-141`, `:173-231`). 변이 결과: check가 실패를 안 내면 변이 test가 세 엔진에서 실패했다(11-R1). 평가 표시를 빼면 9건 모두 실패했다(11-R2). strict test 안의 진짜 안 쓴 preload는 세 엔진에서 실패했다(11-R4 P1). WebKit 문구 그대로는 무시되고, Chromium 문구·뒤에 글자를 붙인 문구·같은 문구의 `console.error`·다른 warning은 세 엔진 모두 실패했다(11-R4 P2~P6). 허용 규칙을 가진 spec 셋(boot·old-tab·production-csp) 안에 허용 밖 안 쓴 preload를 넣으면 셋 다 그 한 줄로 실패했다(11-R5). 앞에 붙인 한 문장은 CSP 검사를 바꾸지 않는다. CSP가 `script-src 'self'`이고 해시·SRI가 없다(`config/hosting/security-headers.json:4`).
|
||||
- **새 11-01(Low·P2): 증명 spec이 실패 방향 절반을 고정하지 않는다.** `preload-use.spec.ts`의 변이 test는 fixture가 아니라 tracker를 직접 부른다(`tests/e2e/preload-use.spec.ts:46`). strict fixture를 쓰는 test는 "통과해야 한다" 방향 하나뿐이다(`:105-144`). fixture가 `check()` 결과를 버리는 변이(11-R3)에서 `preload-use.spec.ts` 9건이 모두 통과했고, 안 쓴 preload를 넣은 probe P1도 세 엔진에서 통과했다. 같은 probe는 변이가 없으면 세 엔진에서 실패한다(11-R4). 3번 test는 지연시킬 청크를 못 찾으면 조용히 평범한 방문이 된다(`:126`). 지금은 찾는다(11-R1 끝 줄: `reference-feature-contract-contribution` 청크).
|
||||
- **1103/11-10(고정 층)은 고쳐졌다.** 두 test가 붙이는 control은 `position: fixed` 층에 있다(`tests/browser-capabilities/browser-files.spec.ts:11-12`, `:34-37`, `:245-248`). mousedown 때 앱 root를 400 px 늘리는 재현에서 수정이 있으면 3건 모두 통과했다(11-R6). 수정을 되돌리면 두 test가 `filechooser`·`download` 대기 30 s 시간 초과로 실패했다(11-R7, firefox). 클릭은 여전히 Playwright의 신뢰된 클릭이고, 단언은 그대로다. 건너뛰는 검사는 없다.
|
||||
- **FE-GATE-013의 `test:system` 18건은 모두 호스트 원인이다.** merge-48 실행(114건 중 18 failed, snapshot `artifacts/tests/system.xml`도 `failures="18"`)과 같은 커밋 메인 세션 실행(10:31)의 실패 18건이 이름까지 같다. 12건은 provider가 `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`로 시작도 못 했다. 6건은 같은 provider가 시작하지 못해 기다리던 파일이 생기지 않았다. repo 없이 이 호스트에서 bwrap을 돌려도 `--unshare-net`은 같은 RTM_NEWADDR로, 네트워크 없는 `--unshare-pid --unshare-ipc --unshare-uts`도 `setting up uid map: Permission denied`로 실패한다(11-R10). 코드 결함으로 볼 실패는 없다. FE-GATE-013의 나머지 명령 7개는 모두 rc=0이다(`r4/013-rest`). 이 실패를 사전 점검이 PASS로 넘긴다(새 11-02, Low·P3, 영역 12의 12-01과 같은 결함).
|
||||
- **지난 영역 11 발견 10건 재판정(2절).** 고쳐짐 6건(11-05·06·07·08·09·10), 일부 4건(11-01은 상세 라우트가 남음, 11-02·03·04는 코드가 들어왔고 완료 기준 실행이 남음). 11-01의 목록 라우트 쪽 완료 기준은 배치로 확인했다(11-R8b: 빈 상태에만 넣은 이름 없는 button을 세 엔진 axe가 잡음, 11-R8c: 응답 모양이 틀리면 경고 상자 단언에서 실패). 이월: 0929/11-08·11-09와 resumable 포트는 고쳐짐. 0929/11-02·11-04·11-05 잔여·11-07과 FOLLOW-UP 2건은 남음.
|
||||
- **검사를 약하게 만든 수정:** 새 결함으로 셀 것은 11-01 하나다. 나머지 축소는 기록된 결정이나 지난 리뷰가 고른 방향이다. 시각 골든에서 기능 링크·4개 절을 뺀 것(D3, `tests/visual/platform.visual.spec.ts:17-54`), provider 테스트 상한 30초(지난 11-03의 개선 방향), IndexedDB 전이 상태 폴링 삭제(단위 테스트가 고정), storybook a11y 애드온 자동 실행 끔(spec이 axe를 직접 돈다). 3.3절 표.
|
||||
- 실행: 이 영역이 직접 돌린 desktop 실행은 없다. 처음 넣은 세 실행(`11-preload`, `11-allow-files`, `11-a11y`)은 19:55에 줄에서 취소됐다(한 번도 돌지 않았다). 실험 10건은 오케스트레이터 배치로 돌았고 모두 복원이 깨끗했다(6절). 10건 모두 기대와 같은 결과였다.
|
||||
|
||||
## 1. 범위 (36.1)
|
||||
|
||||
| 항목 | 기록 |
|
||||
| --- | --- |
|
||||
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` 영역 11. `e40684b..8a44226`에서 이 영역 경로 29파일이 바뀌었다(+1,113/−128, `git diff --stat`). 새 파일: `tests/support/browser/preload-use.ts`(233줄), `tests/e2e/preload-use.spec.ts`(144줄), `tests/e2e/support/installed-api-answers.ts`(63줄). 골든 3장 교체 |
|
||||
| 커밋·작업 상태·확인 시점 | `8a44226`. 노트북 worktree에서 읽기만 했다. 이 영역 수정 커밋: `aad005cb`(11-09), `ee37dd86`(11-10), `b0195e3d`(11-02), `90440082`(11-03), `0edc3fc9`(11-04), `8d328c9c`(11-05), `b3ce7322`(11-06), `af312dee`(11-07), `b6936001`(11-08), `7f633106`(11-01), `ed499736`(resumable 포트), `0a6ff6e5`(12-01 시각 골든), `f92cfd9a`(storybook), `9bddfa52`(시각 빌드 식별값). 영역 밖이 이 경로를 건드린 것: `d13a3936`(05-01 OPFS test), `2d5d41f8`(08-02 키보드 포커스 e2e), `851fdedb`(08-04 라우트 테스트), `9edc8307`(09-09), `2963c6f4`(09-05 SW 선택 파일), `b96d61d8`(09-04 예제 화면). 영역 밖 `529615dc`(로그 추적 끊기), `8cd60bfb`(drill 검사) |
|
||||
| 목적과 지원 실행 구성 | 템플릿(참고 구현). 브라우저 SPA + 정적 호스팅 + 선택형 Service Worker. SSR 없음. 브라우저 테스트는 FE-GATE-008(e2e·capability·storybook·visual)과 FE-GATE-009(`test:a11y`), 샌드박스 경계는 FE-GATE-013(`test:system`)이 merge 단계에서 돈다(`config/ci/gates.json:1893-1903`, `:2011-2022`) |
|
||||
| 필수 요구와 규모·운영 목표 | 사용자 목표: 두 템플릿을 짝으로 써서 서비스를 빨리 출시한다. merge 게이트는 1회 판정이므로 코드와 무관한 실패가 없어야 한다(지난 라운드 심각도 기준). 규모·성능 목표는 영역 15 |
|
||||
| 실행 환경 | 이 영역의 실행 없음(BRIEF-2: 별도 desktop 실행 금지, 배치 1회). 근거로 쓴 출력: 오케스트레이터 `desktop:/tmp/claude-gates/r4/merge-48/summary.txt`(CI env, 19:20 시작, load 0.42): FE-GATE-001~012·020 rc=0, 013 rc=1. `r4/gates/summary.txt`(local env): `check:ci` 등 rc=0, `verify:documentation` rc=1(영역 14). `r4/013-rest`: FE-GATE-013 나머지 명령 7개 rc=0. FE-GATE-008·013의 상세는 merge-48이 쓴 게이트 로그 파일(desktop checkout `artifacts/quality/gates/FE-GATE-008.txt` 19:56, `FE-GATE-013.txt` 20:00)을 snapshot 전에 복사해 읽었다(사본 `scratchpad/r4/a11/FE-GATE-008.m48.txt`, `FE-GATE-013.m48.txt`). 두 사본은 snapshot(`desktop:/tmp/claude-gates/r4/snap/artifacts/quality/gates/`)의 같은 파일과 sha256이 같다(`fba324b9…`, `7fd37e75…`). 같은 커밋 메인 세션 실행(FE-GATE-013 10:31)은 대조에만 썼다. 배치 실험은 오케스트레이터가 같은 desktop checkout(`8a44226`)에서 local env로 돌렸다(20:11~20:16, load 1.7~6.5) |
|
||||
| 읽은 코드·구성 범위 | 전부: 위 수정 커밋의 영역 diff, `preload-use.ts`, `strict-browser-test.ts`, `preload-use.spec.ts`, 허용 규칙을 가진 spec 4개(`boot-module-failure`, `old-tab-chunk-recovery`, `service-worker-update`, `production-csp`), `browser-files.spec.ts`, `accessibility.spec.ts`, `installed-api-answers.ts`, `check-system-test-prerequisites.ts`. 필요한 부분: `ci-artifact-contract.test.ts`의 provider 묶음(`:453-1204`), `service-worker-builds.ts:262-330`, `fixture-builds.ts:15-66`, `opfs-runtime.spec.ts` 새 test, `platform.visual.spec.ts`, `workshop.spec.ts` |
|
||||
| 수행한 테스트·실험 | 배치 10건(11-R1~R8c, R10, 6절). 패치 9개는 노트북에서 `git apply --check`로 `8a44226`에 붙는 것을 먼저 확인했다 |
|
||||
| 확인하지 못한 범위·이유 | `test:system` provider 묶음은 desktop에서 돌 수 없다(11-02). 그래서 1103/11-03·11-04의 완료 기준을 이 호스트에서 확인할 길이 없다. 실제 Gitea 러너(U-1). 글꼴이 없는 깨끗한 Ubuntu에서 FE-GATE-008 |
|
||||
| 이전 리뷰와 비교 가능한 범위 | 지난 README 12절의 영역 11 행 5건(11-01~05), 13절 추가 5건(11-06~10), 10.3절에서 11-01에 합친 12-03·16-03 뒷부분, 지난 영역 문서 2절의 "남음" 이월(0929/11-02·04·05·07·08·09, FOLLOW-UP 3건). 지난 실행 결과는 증거로 쓰지 않았다. README 14.4의 "고침"은 주장으로 보고 코드와 오늘 게이트 출력으로 다시 봤다 |
|
||||
|
||||
## 2. 지난 발견 재확인
|
||||
|
||||
상태: 고쳐짐(완료 기준 확인) / 일부(남은 것) / 남음 / 재발 / 틀린 발견. "일부(검증 남음)"은 코드 변경은 들어왔고 완료 기준 실행만 남은 경우다.
|
||||
|
||||
| 지난 ID | 내용 | 상태 | 근거 |
|
||||
|---|---|---|---|
|
||||
| 1103/11-01 (+12-03, 16-03 뒷부분) | 생성 기능 라우트를 접근성 e2e가 Envelope 불일치 오류 화면으로 검사하고 `a11y.json`은 "passed" | **일부** | 고쳐진 것: spec이 설치된 descriptor로 GET을 찾아 빈 목록을 그 모양으로 답한다(`tests/e2e/support/installed-api-answers.ts:33-62`, Envelope면 `successEnvelope([])` `:42-45`). 목록 라우트는 "경고 상자가 없다"를 단언한 뒤 axe를 돈다(`tests/e2e/accessibility.spec.ts:72-74`). 답하지 못한 요청은 501로 답하고 test가 실패한다(`:55-56`, `:65-68`). 매뉴얼 문장이 동작과 맞다(`docs/manual/reference/create-feature.md:97`). **남은 것:** 하나의 자원을 읽는 라우트(생성기 `--with-create`의 상세 페이지, `scripts/create-feature.ts:360`)는 빈 목록으로 답할 수 없어 실패 화면으로 검사되고 annotation만 남는다(`accessibility.spec.ts:75-81`). `scripts/write-a11y-report.ts:11-17`은 그대로 모든 라우트 ID를 `scope`에 넣고 `automatedStatus: "passed"`를 쓴다. 지난 README 14.4도 16-03 쪽 남은 것으로 적었다. **완료 기준 실행(목록 라우트):** `create:feature sample-feature --with-create`(라우트 `/sample`, `/sample/items/:sampleId`, `/sample/new`) 뒤 생성 목록 페이지의 빈 상태에만 이름 없는 button을 넣자 `@a11y /sample`이 세 엔진 모두 `accessibility.spec.ts:88`의 axe `button-name`(`.zz-review-unnamed`)으로 실패했다. 상세·작성 라우트는 세 엔진 통과했고, 상세 라우트의 `a11y-data-state` annotation이 JSON 결과에 남았다(11-R8b). 답이 Envelope를 무시하게 바꾸자 `@a11y /sample`이 axe 전에 `accessibility.spec.ts:74`의 경고 상자 단언(받은 값 1)으로 실패했다(11-R8c). 같은 실행에서 상세 라우트는 실패 화면 그대로 통과했다. 그래서 목록 쪽 완료 기준은 충족, 상세 라우트와 `a11y.json` 쪽이 남는다 |
|
||||
| 1103/11-02 | CI merge job이 시각 테스트 글꼴을 설치하지 않음 | **일부(검증 남음)** | 생성기와 workflow의 브라우저 단계 두 곳이 패키지 4개를 설치한다(`.gitea/workflows/quality-gates.yml:72`, `:111`). 목록은 한 곳에서 읽는다(`scripts/lib/visual-test-fonts.ts:9-16`, `tests/visual/fonts.setup.ts:6`, `:22-23`). 남은 것: 완료 기준 3번 "글꼴 없는 깨끗한 Ubuntu 24.04에서 그 단계 뒤 `test:visual` 6/6"은 커밋 본문도 실행하지 않았다고 적는다(`b0195e3d`). 러너가 root가 아니고 sudo도 없으면 `apt-get`이 실패한다(`$(command -v sudo || true)`). 생성기와 workflow가 맞는지는 `check:ci` rc=0(`r4/gates`). 글꼴이 있는 desktop에서는 merge-48 FE-GATE-008의 `test:visual` 6/6 통과 |
|
||||
| 1103/11-03 | provider 테스트 10개가 10초 상한, 하나만 고르면 첫 테스트가 기반 fixture 빌드를 떠안음 | **일부(검증 남음)** | describe 옵션으로 묶음 전체가 30초다(`tests/system/ci-runner/ci-artifact-contract.test.ts:461`). 기반 fixture는 `beforeAll`에서 180초 상한으로 만든다(`:65-69`, `:462-464`). 묶음 안에 남은 개별 상한은 tar 폭탄 test의 40초 하나다(`:539`). 남은 것: 완료 기준(`-t 'kills descendants'` 단독 통과, loadavg 20+에서 5회)은 desktop에서 돌 수 없다. provider test가 호스트 원인으로 시작하지 못한다(11-02) |
|
||||
| 1103/11-04 | worktree의 `.git` 파일 때문에 provider test 16개 실패, 사전 점검은 PASS | **일부(검증 남음)** | `.git`이 디렉터리면 tmpfs, 아니면 `/dev/null`을 `--ro-bind`로 겹친다(`scripts/run-and-validate-provider.ts:277-292`). 기반 fixture 복사가 `.claude`·`.worktrees`·`.tmp`·`graphify-out`을 뺀다(`ci-artifact-contract.test.ts:2235-2244`, `:2256`). 새 test가 두 모양을 본다(`:771-802`). 남은 것: 그 새 test 둘도 desktop에서는 호스트 원인으로 실패한다(4절 FE-GATE-013 분류). 가림을 지우는 변이는 커밋 본문도 "결론을 내지 못했다"고 적는다(`0edc3fc9`). 지금 증거는 E1뿐이다. 사전 점검이 worktree를 따로 보는 일은 없다(바꾸지 않았다) |
|
||||
| 1103/11-05 | IndexedDB 차단 업그레이드 test가 500 ms 전이 상태를 폴링 | **고쳐짐** | 폴링을 지웠다(`tests/browser-capabilities/indexeddb-runtime.spec.ts:1023-1027` 주석, `:1028`). 남은 단언이 차단 결과(`code: "BLOCKED"`, `recovery: "RELOAD_OTHER_CONTEXTS"`)와 닫힌 상태를 본다(`:1029-1042`). 전이 상태는 제어된 시계로 단위 테스트가 고정한다(`tests/unit/indexeddb-runtime.test.ts:470-474`). 경쟁이 구조로 없어졌다. merge-48 FE-GATE-008에서 이 test가 세 엔진 모두 통과했다(1회). 지난 완료 기준의 5회 반복은 하지 않았다. 원인이 코드에서 사라졌으므로 고쳐짐으로 본다 |
|
||||
| 1103/11-06 | compact smoke가 build id를 `local-build`로 고정 | **고쳐짐** | 기대값을 빌드와 같은 `VITE_BUILD_ID`에서 읽는다(`tests/e2e/compact-smoke.spec.ts:10`, `:27`). merge-48(`VITE_BUILD_ID=gitea-48-1`) FE-GATE-008에서 `[chromium-compact] compact-smoke.spec.ts:12` 통과. 기본값(`local-build`) 쪽 실행은 이번 라운드에 없다(코드상 `||` 대체값) |
|
||||
| 1103/11-07 | CI 빌드 식별값이 vitest·dev server로 새어 merge 게이트 다섯 개 실패 | **고쳐짐** | dev·capability·visual web server가 로컬 식별값으로 뜬다(`playwright.capabilities.config.ts:35`, `playwright.dev.config.ts:17`, `playwright.visual.config.ts:57`). 완료 기준 "CI env로 merge 단계 14개 통과": merge-48에서 FE-GATE-005·006·007·008·020 rc=0. 14개 중 013만 실패이고 원인은 호스트다(3.2 (3)). capability 66건에 "Execution context was destroyed"가 없다 |
|
||||
| 1103/11-08 | `CI=true`가 테스트 안 로컬 빌드까지 release 빌드로 검사 | **고쳐짐** | fixture 빌드 두 helper가 `localBuildEnvironment()`로 `CI`와 CI 식별값을 지운다(`tests/e2e/support/fixture-builds.ts:65`, `tests/e2e/support/service-worker-builds.ts:179`, `scripts/lib/build-environment.ts:61-66`). merge-48(`CI=true`, `CI_RUNNER_IMAGE` 포함): FE-GATE-005·008·020 rc=0. fixture 빌드를 쓰는 e2e(boot·old-tab·SW update/recovery)가 모두 돌았다 |
|
||||
| 1103/11-09 | WebKit 3초 preload 추정에 기대어 FE-GATE-008이 가끔 실패하고, 정말 안 쓴 preload는 놓침 | **고쳐짐** | 3.2절 (1). 변이 없는 실행: merge-48 FE-GATE-008에서 `preload-use.spec.ts` 3건과 허용 spec 4개(boot·old-tab·production-csp·SW update)가 세 엔진 모두 통과(firefox SW 2건은 quarantine skip). 지난 13절의 두 증상: 곧 쓰일 preload(3.5 s 늦은 부모 청크)는 strict test에서 세 엔진 통과(11-R4의 `preload-use.spec.ts:105`), 정말 안 쓴 preload는 strict test에서 세 엔진 실패(11-R4 P1). 실패 방향 변이 셋(11-R1, R2, R5)도 모두 잡혔다. 증명 spec이 fixture 쪽 실패를 고정하지 않는 빈틈은 새 11-01 |
|
||||
| 1103/11-10 | capability 파일·다운로드 test 버튼이 클릭 도중 움직여 firefox 시간 초과 | **고쳐짐** | 3.2절 (2). 변이 없는 실행: merge-48 FE-GATE-008에서 `browser-files.spec.ts:14`, `:225`가 세 엔진 모두 통과(1회). 400 px 재현: 수정 있음 3/3 통과(11-R6), 수정 되돌림 2/3 실패(두 test 모두 30 s 시간 초과, 11-R7). 지난 커밋 본문의 RED/GREEN과 같다 |
|
||||
| 0929/11-02 | 운영 drill이 어떤 입력으로도 PASS가 될 수 없음 | 남음 | `scripts/drill-runbook.ts:245`, `:350`, `:392`, `:433`의 `providerVerificationRequired: true` 상수 그대로. `main()`은 runbook ID와 `--release-root`만 받는다(`:518-525`). 거짓 PASS는 내지 않는다(`:549`) |
|
||||
| 0929/11-04 | lab 성능 게이트 판정이 같은 빌드에서 뒤집힘 | 남음(코드 기준, 영역 15) | `scripts/test-performance.ts`는 `d99301b` 뒤로 바뀌지 않았다(`git log`). `performance-budgets.ts`의 `46dfe23f`는 bundle 예산 변경이다. 실측은 영역 15 |
|
||||
| 0929/11-05 남은 것 | 규모 기준선이 지금 코드를 대표하는지 | 남음(미검증, 영역 15) | `config/scale/feature-shape-growth.json:3`, `:16` — 2026-11-01 측정, 커밋 `373b27b`. 그 뒤로 기준선 파일은 바뀌지 않았다 |
|
||||
| 0929/11-07 | 빌드 helper 두 벌 | 남음 | 제외 목록이 다르다(`.tmp`는 `fixture-builds.ts:24`에만). `run`(`fixture-builds.ts:55`, `service-worker-builds.ts:174`)과 한 번 치환(`editOnce` `fixture-builds.ts:43`, `replaceOnce` `service-worker-builds.ts:108`)이 두 벌이다. 일반 서버 `startBuildServer`(`service-worker-builds.ts:270`)를 SW와 무관한 spec 둘이 쓴다(`old-tab-chunk-recovery.spec.ts:15`, `boot-module-failure.spec.ts:11`). 지난 판단대로 결함으로 올리지 않는다(리팩토링 후보) |
|
||||
| 0929/11-08 | drill "상수 판정 금지" 검사가 옛 모양만 찾음 | 고쳐짐 | `tests/unit/runbook-drill.test.ts:128-132`가 문자열 모양 셋을 더 찾는다(`8cd60bfb`). 지난 변이(`scripts/drill-runbook.ts:235-239`의 `verdict(await builtAssetsPresent(...))`를 `"PASS"`로)는 `assertion(…, "PASS",\n )` 꼴이 된다. `:130`의 `[^;]*`는 줄바꿈을 넘고 `,?\s*\)`가 끝 쉼표를 받으므로 이 모양을 잡는다(정적 대조). 변이 실행은 하지 않았다(커밋 본문이 실행했다고 적는다). 변이 없는 실행: `r4/gates/test_unit.log`에서 `runbook-drill.test.ts` 9건 통과. 변수에 담아 넘기는 우회는 여전히 못 본다(커밋 본문의 한계, 동작 test가 본다) |
|
||||
| 0929/11-09 | 규모 tier 실행 로그가 커밋됨 | 고쳐짐 | `.gitignore:17` `artifacts/**/*.log`. `git ls-files 'artifacts/**/*.log'` 0개(`529615dc`). 로그를 읽는 코드는 없다(`git grep`) |
|
||||
| FOLLOW-UP | `resumable-upload.spec.ts` 포트 하드코딩 | 고쳐짐 | 설정의 `baseURL`에서 origin을 읽는다(`tests/browser-capabilities/resumable-upload.spec.ts:5`, `:10`, `ed499736`) |
|
||||
| FOLLOW-UP | SW update spec의 route chunk 변경을 helper 옵션으로 | 남음(문서화된 전제) | 아직 spec의 `beforeBuild`에서 덧붙인다(`tests/e2e/service-worker-update.spec.ts:58-73`). 전제는 주석에 있다 |
|
||||
| FOLLOW-UP | Firefox SW quarantine | 남음(만료 2027-03-31) | `service-worker-update.spec.ts:181`, `service-worker-recovery.spec.ts:84` |
|
||||
|
||||
## 3. 이번 발견 (36.3)
|
||||
|
||||
심각도 분포: Critical 0 · High 0 · Medium 0 · Low 2. 우선순위: P2 1 · P3 1. 성격: 구조적 위험 1 · 확인된 결함 1.
|
||||
|
||||
### 3.1 발견
|
||||
|
||||
#### 11-01 strict fixture의 preload 검사를 증명하는 spec이 실패 방향 절반을 고정하지 않아, fixture가 그 결과를 버려도 커밋된 test는 아무것도 실패하지 않는다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 구조적 위험 |
|
||||
| 관련 관점 | 10, 21, 5 |
|
||||
| 근거 | **증명 spec:** `tests/e2e/preload-use.spec.ts` 머리 주석은 "These tests prove that check on a real build"라고 적는다(`:15`). 그런데 안 쓴 preload를 넣는 변이 test는 `@playwright/test`의 맨 `test`에서 tracker를 직접 부른다(`:5`, `:45-46`). strict fixture를 쓰는 test는 3번 하나이고, "fixture가 통과해야 한다" 방향만 본다(`:105-144`). **fixture 연결:** strict fixture가 tracker 결과를 실패 목록에 넣는 곳은 한 줄이다(`tests/support/browser/strict-browser-test.ts:62`). 이 줄을 지우거나, 무시 정규식(`:16-17`)을 넓혀도 실패할 test가 없다. 다른 spec은 `allowedBrowserFailure`로 실패를 허용만 하고, 실패가 나야 한다고 단언하는 곳은 없다(`git grep allowedBrowserFailure`). 커밋 본문의 "새 fixture: 3/3 실패"는 커밋하지 않은 probe였다(`aad005cb` 본문 "변이를 fixture에 직접 넣은 probe(커밋 안 함)"). **조용한 퇴화:** 3번 test는 "boot가 아직 안 받은 청크를 import하는 기능 실행부의 정적 import"를 manifest에서 찾는다(`:116-123`). 못 찾으면 `if (parent !== undefined)`(`:126`)에서 지연을 걸지 않고 평범한 화면 방문으로 통과한다. 지금은 찾는다. 같은 계산을 빌드한 manifest에 돌리면 `_reference-feature-contract-contribution-XD-KpqsD.js`가 나온다(11-R1 끝 줄). 기능 실행부 모양이 바뀌면 이 test는 경고 없이 아무것도 재현하지 않게 된다. **변이 실행(11-R3, local env, 세 엔진):** `strict-browser-test.ts:62`를 `await preloads.check();`로 바꾸고, strict fixture로 안 쓴 modulepreload(`/assets/async-state-Cxfod8c-.js`)를 넣는 probe P1을 더했다. 결과: `preload-use.spec.ts` 9건 모두 통과, P1도 세 엔진 모두 통과(놓침). **대조(11-R4, 같은 명령, fixture 변이 없음):** P1이 세 엔진 모두 `preloadunused:/assets/async-state-Cxfod8c-.js`로 실패, `preload-use.spec.ts` 9건 통과. 그래서 그 한 줄이 사라져도 커밋된 test가 알아채지 못한다는 것이 실행으로 확인됐다 |
|
||||
| 발생 조건 | strict fixture(`strict-browser-test.ts`)를 고치는 변경. 또는 Vite·기능 실행부 구조가 바뀌어 3번 test의 `parent`가 사라질 때 |
|
||||
| 영향 | 1103/11-09가 새로 만든 검사(세 엔진의 안 쓴 preload 검출)가 조용히 사라질 수 있다. 사라져도 FE-GATE-008은 초록이다. 사용자 피해는 없다. 낭비된 다운로드 회귀를 다시 놓치게 된다. 템플릿을 받은 제품도 같은 fixture를 받는다 |
|
||||
| 심각도·우선순위 | Low · P2 — 피해는 테스트 장치의 신뢰도에 한정된다. 고치는 비용이 몇 줄이다. 지난 라운드 1103/11-05와 같은 기준 |
|
||||
| 통제·증거 | 목표 M3(fixture의 실패 방향을 test가 고정) / 확인 M2(검사는 구현됐고 동작하지만, fixture 쪽 실패를 고정하는 test 없음) · E3(11-R3·R4 변이와 대조) |
|
||||
| 확실성과 남은 가정 | 연결 한 줄과 test 목록은 코드로 확정이다. `preload-use.spec.ts`가 그 변이를 놓친다는 것은 실행으로 확정이다. 전체 e2e도 놓친다는 것은 추론이다(초록 suite에는 진짜 안 쓴 preload가 없으므로 다른 spec도 실패할 이유가 없다). 무시 정규식을 넓히는 변이는 돌리지 않았다. 그 방향을 보는 커밋된 test가 없다는 것은 코드로 확인했다(11-R4의 P3~P6은 리뷰 probe다) |
|
||||
| 결정의 근거 | 적용 제외 — 이미 정한 검사를 증명하는 test 보강이다 |
|
||||
| 이해 비용 | fixture를 고치는 사람은 `preload-use.spec.ts`가 통과하면 검사가 살아 있다고 믿기 쉽다. 실제로는 tracker만 증명된다 |
|
||||
| 최소 개선 방향 | (1) `preload-use.spec.ts`에 strict fixture로 안 쓴 preload를 넣는 test를 하나 둔다(이번 probe P1과 같다). 그 test는 `test.fail()`로 "fixture가 실패시켜야 한다"를 고정하거나, fixture의 실패 목록을 test가 읽을 수 있게 내보낸다. 같은 방식으로 WebKit 문구와 다른 warning 하나(이번 P3·P6)가 실패하는지도 고정한다. (2) 3번 test가 `expect(parent).toBeDefined()`로 시작한다 |
|
||||
| 대안 비교 | 적용 제외 — test 추가 외에 고를 길이 없다. `test.fail()`과 실패 목록 노출은 같은 효과다 |
|
||||
| 단순화의 보존 조건 | 적용 제외 |
|
||||
| 비용·부작용 | test 1~3개, 엔진마다 수 초 |
|
||||
| 재검토 조건 | fixture 검사가 별도 단위 테스트 가능한 모듈로 빠지면 그 모듈의 단위 test로 옮긴다 |
|
||||
| 완료 기준 | 11-R3 변이(fixture가 결과를 버림)를 넣으면 `preload-use.spec.ts`가 세 엔진에서 실패한다. 무시 정규식을 `/.*/`로 넓혀도 실패한다. `parent`가 없으면 3번 test가 실패한다 |
|
||||
| 검증 방법 | 11-R3과 같은 변이 + 정규식 변이로 `playwright test tests/e2e/preload-use.spec.ts` 세 엔진 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
|
||||
#### 11-02 `test:system` 사전 점검이 provider 샌드박스(bwrap namespace)를 한 번도 실행해 보지 않아, bwrap이 user namespace를 못 쓰는 호스트에서는 PASS 뒤 provider test 18건이 샌드박스 회귀처럼 실패한다
|
||||
|
||||
> 영역 12가 같은 결함을 12-01(Medium·P1, 러너 전제를 적지 않음 + 사전 점검 PASS 뒤 bwrap 원문 실패)로 적었다. 오케스트레이터가 README에서 둘을 합친다. 여기서는 영역 11이 본 근거와 등급을 그대로 적는다.
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 8, 20, 26, 10, 21 |
|
||||
| 근거 | **사전 점검:** `scripts/check-system-test-prerequisites.ts:15-38`은 `bwrap`·`systemctl`·`tar` 실행 파일, cgroup v2 controller, systemd bus만 본다. bwrap을 한 번도 실행하지 않는다. 실패 안내는 "compatible Linux CI-runner host"라고만 적는다(`:46-48`). **provider:** `scripts/run-and-validate-provider.ts:255-256`은 bwrap에 `--unshare-net`을 준다. bwrap은 새 네트워크 namespace에서 loopback을 올린다. **실행(merge-48 FE-GATE-013, CI env; 같은 커밋 메인 세션 10:31도 같다):** "System test prerequisites: PASS" 뒤 114건 중 18건 실패. 12건은 `sandboxed external provider failed: exit=1 … sandbox reported: bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`. 6건은 그 provider가 시작하지 못해 기다리던 파일이 안 생겼다는 메시지뿐이다(`provider output did not reach expected content` 4건, `expected path did not appear` 2건, `ci-artifact-contract.test.ts:1782`, `:1812`). 이 6건은 bwrap 원인을 보여 주지 않는다. 4절 FE-GATE-013 분류 표. **같은 bwrap을 쓰는 노트북**(Ubuntu 24.04.5, `kernel.apparmor_restrict_unprivileged_userns=1`, bwrap setuid 아님)에서는 지난 라운드에 provider 묶음이 돌았다(지난 영역 문서 6.2절 6번). 그래서 desktop만의 조건으로 본다. **호스트 확인(11-R10, repo 코드 없음):** desktop은 kernel `7.0.0-38-generic`, `kernel.apparmor_restrict_unprivileged_userns = 1`, bwrap 0.9.0(setuid 아님)이다. `bwrap --ro-bind / / --unshare-net /bin/true`는 같은 `loopback: Failed RTM_NEWADDR: Operation not permitted`로 rc=1이다. 네트워크를 빼고 `--unshare-pid --unshare-ipc --unshare-uts`만 줘도 `setting up uid map: Permission denied`로 rc=1이다. `systemd-run --user --scope` 아래에서도 같다. 즉 이 호스트의 bwrap은 비특권 user namespace를 쓸 수 없다. FE-GATE-013의 다른 명령 7개는 이 호스트에서 모두 통과한다(`r4/013-rest`) |
|
||||
| 발생 조건 | bwrap이 비특권 user namespace를 만들거나 그 안에서 loopback을 설정하지 못하는 Linux 호스트(desktop: AppArmor 비특권 userns 제한, bwrap setuid 아님). 노트북도 같은 sysctl 값인데 지난 라운드에는 돌았다. 그래서 그 sysctl 하나로 갈리지는 않는다(원인 미상). 어떤 러너 이미지가 여기에 해당하는지는 미확인(U-1) |
|
||||
| 영향 | FE-GATE-013이 코드와 무관하게 실패한다. 실패가 "sandboxed external provider failed"와 파일 대기 시간 초과로 나와 샌드박스 회귀처럼 보인다. 6건은 원인 문구도 없다. 사전 점검은 PASS라서 어디가 문제인지 알려 주지 않는다. 1103/11-04(worktree)와 같은 모양이다. 그때는 worktree를 지원하는 쪽으로 고쳤고 사전 점검은 그대로다 |
|
||||
| 심각도·우선순위 | Low · P3 — 지금 확인된 범위는 개발·검증 호스트의 편의다. 러너가 같은 조건이면 merge 게이트가 항상 실패하는 Medium·P1이 된다(재검토 조건) |
|
||||
| 통제·증거 | 목표 M3(사전 점검이 provider가 쓰는 샌드박스 옵션을 직접 시험하고 이유를 말함) / 확인 M1(필요 도구 목록만 확인) · E3(merge-48 게이트 로그 + 11-R10 호스트 확인) + E1 |
|
||||
| 확실성과 남은 가정 | 사전 점검이 bwrap을 실행하지 않는다는 것, 18건의 메시지, 이 호스트의 bwrap이 repo 없이도 실패한다는 것은 확정이다. 6건이 같은 원인이라는 것은 같은 provider 시작 경로를 쓰고 같은 실행에서 났다는 데서 온 추론이다. 노트북과 desktop이 왜 갈리는지는 확인하지 않았다(환경은 고치지 않는다) |
|
||||
| 결정의 근거 | 적용 제외 — 사전 점검에 provider와 같은 bwrap 호출 한 번을 더하는 보강이다 |
|
||||
| 이해 비용 | 실패를 본 사람은 provider 샌드박스 코드(`run-and-validate-provider.ts`)와 18개 test를 읽고 나서야 호스트 문제라는 것을 안다. 메인 세션도 desktop 환경 문제로 따로 처리했다(지난 README 14.5 9·11회차) |
|
||||
| 최소 개선 방향 | 사전 점검이 provider와 같은 bwrap 옵션 묶음(`scripts/run-and-validate-provider.ts:255-256`의 `--unshare-pid --unshare-ipc --unshare-uts --unshare-net`)으로 `/bin/true`를 한 번 돌린다. 옵션 묶음은 provider와 한 상수에서 읽는다. 11-R10처럼 네트워크를 빼도 실패하는 호스트가 있으므로 옵션 일부만 시험하면 안 된다. 실패하면 bwrap의 stderr와 "이 호스트의 bwrap은 비특권 user namespace를 쓸 수 없다"를 적고 멈춘다. 파일을 기다리는 test는 시간 초과 때 provider stderr를 메시지에 붙인다. 러너 전제는 영역 12의 12-01 방향대로 문서에 적는다 |
|
||||
| 대안 비교 | 적용 제외 — `--unshare-net`을 빼는 것은 provider의 네트워크 차단 경계를 없애므로 대안이 아니다 |
|
||||
| 단순화의 보존 조건 | 적용 제외 |
|
||||
| 비용·부작용 | 사전 점검에 bwrap 실행 1회(수 ms) |
|
||||
| 재검토 조건 | 실제 러너에서 같은 RTM_NEWADDR이 나면 Medium·P1로 올리고, 러너 요구(비특권 userns + 네트워크 namespace)를 CI 문서와 러너 점검에 적는다 |
|
||||
| 완료 기준 | desktop에서 `corepack pnpm test:system`이 사전 점검 단계에서 bwrap 원인과 함께 멈춘다. 지원 호스트에서는 그대로 PASS 뒤 114건이 돈다 |
|
||||
| 검증 방법 | desktop과 지원 호스트에서 `corepack pnpm test:system` |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규(README에서 1105/12-01과 합칠 예정) |
|
||||
|
||||
### 3.2 오케스트레이터 필수 확인
|
||||
|
||||
**(1) 1103/11-09 preload 검사 (`aad005cb`)**
|
||||
|
||||
검사가 하는 일(코드): 문서마다 첫 바이트 전에 MutationObserver로 `<link rel=modulepreload|preload>`를 적는다(`preload-use.ts:61-87`). page.route로 `/assets/*.js`에 "이 URL이 평가됐다" 한 문장을 앞에 붙인다(`:38`, `:117-141`, `:152-171`, `:211`). test 끝에 preload됐는데 평가 기록이 없는 script를 `preloadunused:`로 센다(`:190-203`). script가 아닌 preload, worker 제어 중 preload, 표시 못 한 script는 `preloadunverifiable:`로 실패한다(`:192-200`). 끝까지 읽지 못한 문서는 `preloadcheck:unreadable-document`로 실패한다(`:221-227`).
|
||||
|
||||
| 질문 | 판단 | 근거·상태 |
|
||||
|---|---|---|
|
||||
| (a) 진짜 안 쓴 modulepreload가 세 엔진에서 실패하는가 | 그렇다 | tracker 직접 호출: `preload-use.spec.ts:45-79`가 세 엔진에서 본다(FE-GATE-008 통과). strict test 안: 리뷰 probe P1이 홈 화면에서 안 받은 청크 `/assets/async-state-Cxfod8c-.js`를 modulepreload만 하고 실행하지 않자 세 엔진 모두 `unexpected browser console/page errors`에 `preloadunused:/assets/async-state-Cxfod8c-.js` 한 줄로 실패했다(11-R4). 커밋된 test에는 이 방향이 없다(11-01) |
|
||||
| (a) fixture 변이를 무엇이 잡는가 | check가 실패를 안 내면 1번 test, 평가 표시를 빼면 세 test 모두, fixture가 결과를 버리면 아무것도 | 11-R1(`preload-use.ts:220` 실패 목록 비움): `reports a modulepreload the page never runs`만 세 엔진 실패(Expected `["preloadunused:/assets/async-state-Cxfod8c-.js"]`, Received `[]`), 나머지 6건 통과. 11-R2(`:139` 평가 표시 없음): 9건 모두 실패, 홈 화면만으로도 `preloadunused:` 26줄(boot·react·i18n 등). 11-R3(`strict-browser-test.ts:62` 결과 버림): 9건 통과 + probe P1 세 엔진 통과(놓침, 11-01) |
|
||||
| (b) WebKit 무시가 정확한 문구인가 | 그렇다 | `strict-browser-test.ts:16-17`은 `^…$`로 묶인 WebKit 문구 하나이고 URL 자리만 `\S+`다. `:21`이 `warning` 타입만 본다. 엔진을 가리지 않고 문구로만 거른다. 11-R4(세 엔진): P2(WebKit 문구 그대로, `console.warn`) 통과. P3(Chromium 문구 "…has an appropriate \`as\` value…") 실패. P4(WebKit 문구 뒤에 " (and more)") 실패. P5(같은 문구를 `console.error`로) 실패. P6(다른 warning) 실패. 실패는 모두 `console:warning:`/`console:error:` 한 줄이다. 리뷰 probe라 커밋된 test는 아니다(11-01) |
|
||||
| (c) 허용 규칙 아래에서 진짜 안 쓴 preload가 통과하는가 | 허용 목록에 없는 청크는 실패한다. worker 제어 중 preload는 통과한다(설계 한계) | **11-R5(chromium):** 네 spec의 주 단언 뒤에 허용 규칙이 이름 붙이지 않은, 아직 안 받은 청크 하나를 modulepreload하고 실행하지 않았다. boot-module-failure(`dist-broken`에서 `async-state-Cxfod8c-.js`), old-tab(`dist-a`에서 같은 청크), production-csp(`dist`에서 `badge-D6w1dKS_.js`)는 셋 다 `preloadunused:<그 청크>` 한 줄로 실패했다. service-worker-update "removed chunk" test는 `service worker controls: true` 상태에서 넣어 통과했다(아래 설계 한계 확인). **코드:** boot-module-failure: 깨진 빌드의 `boot.tsx` 정적 closure만(`boot-module-failure.spec.ts:46-64`). 끝 문서는 그 깨진 boot 문서 하나라 범위가 원인과 같다. old-tab: 없어진 페이지 이름 꼴 `MISSING_PAGE`(`old-tab-chunk-recovery.spec.ts:119`, `:168`)와 A 플랫폼 페이지·B UI routes의 정적 closure(`:155-169`). 끝에 남는 것은 B 탭 문서뿐이라 A 쪽 closure는 이제 B 탭 허용을 넓히기만 한다(A·B가 공유하는 청크). `context-routes-*`는 어느 context든 허용한다. 좁힐 여지는 있지만 실제 가림은 추론으로도 작다(B 탭은 그 청크들을 플랫폼 화면에서 이미 실행했다). service-worker-update: worker가 제어하는 문서의 preload 전부(`service-worker-update.spec.ts:50-52`). page.route가 worker 응답을 못 보므로 쓰였는지 알 길이 없다. 이 spec 안에서는 안 쓴 preload도 통과한다. 주석과 커밋 본문이 적은 한계다. production-csp: 허용 없음, `fulfillBuildScript`로 표시 유지(변이 없는 FE-GATE-008 통과가 쓰인 청크의 표시가 살아 있다는 증거다. 표시가 없으면 11-R2처럼 쓰인 청크도 전부 실패한다) |
|
||||
| (d) 앞에 붙인 문장이 production-csp 등이 보는 것을 바꾸는가 | 바꾸지 않는다 | CSP는 `script-src 'self'`이고 해시 출처가 없다(`config/hosting/security-headers.json:4`). 붙인 문장은 같은 출처 외부 script 안이라 같은 규칙으로 허용된다. HTML 문서 응답에는 보안 헤더가 그대로 붙는다(`production-csp.spec.ts:36-39`, `preload-use.ts:124-130` 비-script 경로). 앱 HTML에 `integrity` 속성이 없다(`index.html`). 브라우저 쪽 크기 단언(`transferSize` 등)을 하는 browser spec이 없다(`git grep`). SW spec의 바이트 비교(`service-worker-update.spec.ts` "removed chunk" test의 `readFile` 대조, SW의 sha256 대조)는 worker가 직접 받은 바이트다. page.route는 worker 요청을 보지 않는다. `server.served`는 서버 쪽 기록이라 경로가 그대로다. `fulfillBuildScript`는 본문이 바뀌므로 `content-length`·`content-encoding`을 지운다(`:131-133`). 그래서 gzip 응답도 페이지에는 풀린 본문으로 간다. gzip 헤더 검사는 worker 쪽 test가 하므로 영향이 없다 |
|
||||
| 부수 효과 | 기록 | page.route를 걸면 Playwright는 그 페이지의 HTTP cache를 끈다(Playwright 문서의 page.route 주의 문구, E0). 그래서 이제 strict fixture를 쓰는 모든 browser test가 HTTP cache 없이 돈다. 지금 HTTP cache 동작을 단언하는 browser test는 없다(테스트 서버는 `no-cache`를 보낸다, `service-worker-builds.ts:314`). 커밋 본문의 한계 목록에는 이 점이 없다. 결함으로 세지 않고 5절에 적는다 |
|
||||
|
||||
**(2) 1103/11-10 고정 층 (`ee37dd86`)**
|
||||
|
||||
| 질문 | 판단 | 근거·상태 |
|
||||
|---|---|---|
|
||||
| (a) 수정을 되돌리고 mousedown 때 앱 root를 400 px 늘리면 RED, 수정이 있으면 GREEN인가 | 그렇다 | 재현: 두 test의 click 직전에 capture 단계 mousedown listener가 `#root`에 `padding-block-start: 400px`를 주고 layout을 다시 계산한다. 11-R6(수정 있음, firefox): 3 passed(6.0 s). 11-R7(`ee37dd86`의 spec 변경을 되돌림, firefox, 줄 번호는 되돌린 파일 기준): `browser-files.spec.ts:3`이 `page.waitForEvent("filechooser")`, `:224`가 `page.waitForEvent("download")` 대기 중 30 s test 시간 초과로 실패, 세 번째 test(`showOpenFilePicker`)는 통과. 변이 없는 실행: merge-48 FE-GATE-008에서 두 test 세 엔진 통과 |
|
||||
| (b) 고정 층 때문에 건너뛰는 검사가 있는가 | 없다 | 층은 control 셋(label·input·button)을 감쌀 뿐이다(`browser-files.spec.ts:34-37`, `:245-248`). 클릭은 그대로 `getByRole("button").click()`이라 신뢰된 입력이고, Playwright의 보임·안정·이벤트 수신 확인을 거친다(`:186`, `:324-326`). 파일 선택기·다운로드 이벤트 대기와 결과 단언(`:185`, `:201-224`, `:323`, `:340-`)은 바뀌지 않았다. 다운로드 anchor는 runtime이 `document.body`에 따로 붙인다(`src/adapters/browser-files/download-delivery-adapter.ts:66`). 층이 앱 header 왼쪽 위를 덮지만 두 test는 앱 UI를 누르지 않는다 |
|
||||
| 남은 위험 | 기록 | 원인(앱이 첫 그리기 뒤 약 12 px 자람)은 그대로다. 두 test만 앱 흐름 밖으로 뺐다. 그리는 중인 앱 안의 요소를 바로 누르는 다른 browser test가 같은 이동을 만날 가능성은 남는다. 관찰된 사례는 없다(5절) |
|
||||
|
||||
**(3) FE-GATE-013 `test:system` 실패 분류**
|
||||
|
||||
출처: merge-48 FE-GATE-013(CI env, rc=1, 84 s)의 게이트 로그(`FE-GATE-013.m48.txt`). "System test prerequisites: PASS", 3파일 114건 중 18 failed / 96 passed. 실패는 모두 `tests/system/ci-runner/ci-artifact-contract.test.ts`의 `candidate archive and provider upload boundaries` 묶음이다. 같은 커밋 메인 세션 실행(10:31)의 실패 18건과 이름이 모두 같다. vitest가 같은 오류를 묶어 보여서 RTM_NEWADDR 블록은 8개이고, 그 블록이 아래 12건을 덮는다.
|
||||
|
||||
| # | test | 실패 메시지 | 분류 |
|
||||
|---|---|---|---|
|
||||
| 1–3 | leaves no stale raw report after invalid trust / invalid archive / provider failure and permits a clean retry | `sandbox reported: bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted` | 호스트 |
|
||||
| 4 | drains and kills provider background processes before sealing evidence | 같음 | 호스트 |
|
||||
| 5 | does not expose or mutate a host path outside the sandboxed workspace | 같음 | 호스트 |
|
||||
| 6–7 | hides repository metadata from the provider when .git is a directory / file (1103/11-04의 새 test) | 같음 | 호스트 |
|
||||
| 8 | applies effective aggregate cgroup limits without exposing command or credentials | 같음 | 호스트 |
|
||||
| 9 | observes EMFILE at the provider FD limit and still emits valid evidence | 같음 | 호스트 |
|
||||
| 10 | enforces CPU RLIMIT before the independent wall-clock timeout | 기대 `exit=(?:137\|152)\|signal=SIGXCPU…`, 받은 값이 같은 bwrap 오류 | 호스트 |
|
||||
| 11–12 | runs the vulnerability / provenance adapter offline and collects its unit | 같은 bwrap 오류 | 호스트 |
|
||||
| 13–14 | kills and collects an active provider when its guardian dies / collects the whole provider scope when its supervisor dies | `provider output did not reach expected content` | 호스트(추론: provider가 시작하지 못해 출력 없음) |
|
||||
| 15–16 | fails closed when the guardian dies after scope collection and before commit / cleans published evidence when the supervisor dies and permits same-workspace retry | `expected path did not appear` | 호스트(추론, 같음) |
|
||||
| 17–18 | kills descendants and collects the scope on provider output / timeout termination | `provider output did not reach expected content` | 호스트(추론, 같음) |
|
||||
|
||||
코드 결함으로 분류한 것은 0건이다. 통과한 96건에는 provider를 샌드박스에서 띄우지 않는 test가 모두 들어간다. 이 18건 때문에 1103/11-03·11-04의 완료 기준과 11-04의 가림 변이를 desktop에서 확인할 수 없다. 남는 코드 쪽 문제는 사전 점검과 진단 문구다(11-02). FE-GATE-013은 `test:system`에서 멈춘다. 나머지 명령 7개(`verify:reproducible-build`, `build:release-candidate`, `verify:local-evidence`, `check:supply-chain:fixtures`, `check:supply-chain:provider-fixtures`, `check:security:fixtures`, `check:browser-security`)는 오케스트레이터가 `r4/013-rest`로 따로 돌려 모두 rc=0이다. 그래서 이 호스트에서 FE-GATE-013을 막는 것은 이 18건뿐이다. snapshot의 `artifacts/tests/system.xml`도 `tests="114" failures="18"`이다. 호스트 확인(11-R10, repo 코드 없음): bwrap 자체가 `--unshare-net`에서 RTM_NEWADDR, 네트워크 없이도 `setting up uid map: Permission denied`로 실패한다(11-02 근거). 이 결과로 분류를 "호스트"로 확정한다. 추론으로 둔 13~18번도 provider 시작 전에 bwrap이 실패하는 호스트라서 같은 원인으로 본다.
|
||||
|
||||
**(4) 1103/11-*과 0929/11-* 이월 상태:** 2절 표.
|
||||
|
||||
### 3.3 수정이 검사를 약하게 했는가 (`git diff e40684b..8a44226 -- <영역 경로>`)
|
||||
|
||||
| 변경 | 약해진 것 | 판단 |
|
||||
|---|---|---|
|
||||
| strict fixture가 WebKit 경고 문구를 무시(`aad005cb`) | 끝에 열려 있지 않은 문서(이동·reload 전 문서)의 안 쓴 preload를 WebKit이 3초 뒤 잡던 경우가 사라졌다 | 대신 세 엔진에서 끝 문서를 검사한다. 커밋 본문 한계에 적혀 있다. 결함 아님. 증명 spec의 빈틈은 11-01 |
|
||||
| old-tab 허용이 WebKit 전용 경고 → 모든 엔진의 `preloadunused:` | 허용이 엔진 전체로 넓어졌다 | 전에는 chromium·firefox에 preload 검사 자체가 없었다. 허용 청크 목록은 같은 계산이다. 결함 아님(3.2 (c)) |
|
||||
| SW update spec에 `preloadunverifiable:service-worker:` 허용 | worker 제어 중 preload는 쓰였는지 안 본다 | 볼 수 없는 것이고 이름 붙인 허용이다. 결함 아님 |
|
||||
| IndexedDB 전이 상태 폴링 삭제(`8d328c9c`) | 실제 브라우저에서 `BLOCKED` 전이 상태 단언 | 차단 결과 단언은 남았고 전이 상태는 단위 test가 고정한다. 지난 리뷰의 개선 방향 그대로. 결함 아님 |
|
||||
| provider test 상한 10→30초(`90440082`) | 느려진 provider test가 늦게 실패한다 | 파일이 이미 정한 예산이고 지난 리뷰의 개선 방향이다. 결함 아님 |
|
||||
| 시각 골든에서 기능 링크와 플랫폼 화면 4개 절을 숨김(`0a6ff6e5`) | 기능 링크 목록·설치 요약·라우트·계약·기능 절의 모양 회귀 | 기록된 결정(지난 README 14.2 D3). DataTable 하나·능력 카드·릴리스 신원·셸 CSS는 남고, 커밋 본문은 셸 링크 padding 변이를 두 장이 잡았다고 적는다(이번 미실행). 결함 아님 |
|
||||
| storybook a11y 애드온 자동 실행 끔(`f92cfd9a`) | 애드온의 자동 axe | spec이 AxeBuilder로 위반 0을 단언한다(`tests/storybook/workshop.spec.ts:24-25`). 결함 아님 |
|
||||
| capability·dev·visual web server가 로컬 식별값(`af312dee`, `9bddfa52`, `b6936001`) | 그 서버들은 CI 식별값으로 뜨지 않는다 | CI 식별값 빌드는 release e2e(`playwright.config.ts` webServer)와 compact smoke가 본다. 결함 아님 |
|
||||
| compact smoke 기대값을 env에서 읽음(`b3ce7322`) | 고정 기대값 | 빌드가 같은 env를 읽으므로 빌드가 식별값을 무시하면 CI env에서 여전히 실패한다. 결함 아님 |
|
||||
|
||||
## 4. 28개 관점 판정 (36.2)
|
||||
|
||||
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가.
|
||||
|
||||
| 번호 | 관점 | 판정 | 목표·확인 통제 | 증거 | 이유·잔여 위험 |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | 코드 성숙도 | > | — | — | src는 영역 01~09 |
|
||||
| 2 | 구조적 성숙도 | > | — | — | 12·16 |
|
||||
| 3 | 변경 용이성 | P | M3 / M2 | E1 | 기능을 더해도 접근성 spec은 descriptor로 응답 모양을 정한다(1103/11-01 고쳐진 쪽). 시각 골든은 기능 수와 무관하다(D3). 상세 라우트는 실패 화면으로 검사된다(1103/11-01 남은 것) |
|
||||
| 4 | 인지 부하 | P | M2 / M2 | E1 | preload 검사는 머리 주석이 한계까지 적는다(`preload-use.ts:3-36`). 빌드 helper 두 벌(0929/11-07) |
|
||||
| 5 | 위험 가시성 | P | M3 / M2 | E1 | 볼 수 없는 preload를 이름 붙여 실패시킨다. 상세 라우트를 실패 화면으로 검사해도 `a11y.json`은 "passed"다(1103/11-01). 증명 spec이 tracker만 증명한다(11-01) |
|
||||
| 6 | 실패 성숙도 | O | M3 / M3 | E3(merge-48 1회) | 부트 오류 화면, 구 탭 1회 reload, 429 재시도·불명 결과 저장, 깨진 SW 해제, 이전 캐시 응답이 FE-GATE-008에서 통과했다(SW 둘은 chromium·webkit, firefox quarantine) |
|
||||
| 7 | 운영 성숙도 | P | M3 / M1 | E1 | drill은 거짓 PASS를 내지 않지만 PASS 경로가 없다(0929/11-02) |
|
||||
| 8 | 디버깅 가능성 (깊게) | P | M3 / M2 | E3·E1 | preload 실패는 경로와 이유 이름을 찍는다(`preloadunused:<path>`, `preloadunverifiable:<reason>:<path>`, 11-R5의 실패 메시지가 주입한 청크 한 줄이었다). `test:system`은 사전 점검 PASS 뒤 bwrap 원인을 12건만 보여 주고 6건은 파일 대기 시간 초과로만 보인다(11-02) |
|
||||
| 9 | 유지보수 성숙도 | P | M2 / M2 | E1 | 커밋 로그 추적을 끊었다(0929/11-09 고쳐짐). helper 두 벌(0929/11-07). 규모 기준선 재측정은 영역 15 |
|
||||
| 10 | 테스트 성숙도 (깊게) | P | M3 / M3(검사 동작), M2(검사의 보호) | E3(merge-48 + 배치 변이 10건) | 강점: 세 엔진 같은 방법의 preload 사용 검사가 진짜 안 쓴 preload·표시 누락·허용 밖 청크를 잡는다(11-R1·R2·R4·R5). 고정 층은 400 px 이동 재현에서 RED→GREEN(11-R6·R7). 생성 기능 목록 라우트가 빈 상태로 검사되고 모양 오류는 경고 상자 단언에서 실패한다(11-R8b·R8c). 전이 상태 폴링 제거, provider 묶음 상한 통일. 약점: fixture 실패 방향을 test가 고정하지 않는다(11-01, 11-R3 놓침), 상세 라우트 실패 화면 검사(1103/11-01), provider 묶음은 지원 안 되는 호스트에서 원인 없이 실패(11-02) |
|
||||
| 11 | 데이터 성숙도 | - | — | — | 이 영역에 데이터 이관 경로가 없다 |
|
||||
| 12 | 동시성 성숙도 | P | M3 / M2 | E1 | 차단 업그레이드 test의 경쟁을 없앴다(1103/11-05). 05-01 OPFS 새 test는 `waitForTimeout(250)`이 경쟁 경로를 탈지 정한다(`opfs-runtime.spec.ts`, 영역 05 몫, 5절) |
|
||||
| 13 | 확장성 | P | M3 / M2 | E1 | 접근성 spec·시각 골든이 기능 추가에 따라 손대지 않고 돈다. 규모 tier 재측정은 영역 15 |
|
||||
| 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`의 호스트 요구가 적혀 있지 않다(11-02) |
|
||||
| 17 | API / Contract | > | — | — | 07. 접근성 e2e 응답이 operation의 Envelope 선언을 따른다(1103/11-01 고쳐진 쪽) |
|
||||
| 18 | 배포 성숙도 (깊게) | P | M3 / M3(브라우저), M1(drill) | E3(merge-48 1회) | 구 탭 청크 복구(세 엔진), SW A→B 업데이트(chromium·webkit), CI 식별값 빌드의 compact smoke가 CI env로 통과했다. drill로 provider 전환을 기록할 수 없다(0929/11-02). 실제 러너 미실행(U-1) |
|
||||
| 19 | 설정 성숙도 | P | M3 / M2 | E1 | 로컬 식별값과 CI 식별값을 web server별로 나눈다(`LOCAL_BUILD_IDENTITY`). resumable spec 포트를 설정에서 읽는다 |
|
||||
| 20 | 개발자 경험 (깊게) | P | M3 / M2 | E3·E1 | worktree에서 provider test가 돌 수 있게 됐다(코드). 지원 안 되는 호스트에서 사전 점검이 PASS다(11-02) |
|
||||
| 21 | Guardrail 성숙도 (깊게) | P | M3 / M2 | E3(merge-48, 배치 변이) | merge-48(CI env)에서 FE-GATE-001~012·020 통과. 지난 라운드 CI env에서만 나던 실패 넷(11-06·07·08, 11-10의 firefox 시간 초과)이 이번 1회 실행에 없다. `forbidOnly`·quarantine 만료·mask 규칙 fixture가 기대대로 실패한다(FE-GATE-008 `check:test-evidence:fixture`). strict fixture 검사는 넓어졌지만 그 검사를 지켜 주는 test가 없다(11-01). FE-GATE-013은 이 호스트에서 코드와 무관하게 실패한다(11-02) |
|
||||
| 22 | 추상화 성숙도 | P | M2 / M2 | E1 | preload 검사 하나가 fixture 하나에 들어갔고 `fulfillBuildScript` 한 함수로 직접 응답 spec과 맞춘다. helper 두 벌(0929/11-07) |
|
||||
| 23 | 일관성 | P | M2 / M2 | E1 | 모든 browser spec이 같은 strict fixture를 쓴다(`chunk-load-error.spec.ts` 하나만 맨 test). 허용 규칙 셋의 모양이 spec마다 다르다(함수 fixture 둘, 정규식 하나) |
|
||||
| 24 | 네이밍 / 의미 | P | M2 / M2 | E1 | 실패 이름(`preloadunused`·`preloadunverifiable:<reason>`)이 뜻과 맞다. 증명 spec 주석 "These tests prove that check"는 fixture까지 증명하지 않는다(11-01) |
|
||||
| 25 | 조직 확장성 | > | — | — | 14 |
|
||||
| 26 | Ownership 성숙도 | P | M2 / M1 | E1 | quarantine에 owner·만료가 있다. `test:system`을 어떤 호스트에서 돌려야 하는지 적힌 곳이 없다(11-02) |
|
||||
| 27 | 삭제 가능성 | P | M2 / M2 | E1 | 커밋 로그가 없어졌다(0929/11-09). 시각 골든이 기능 링크를 빼서 기능을 지워도 골든이 안 바뀐다 |
|
||||
| 28 | 회복 가능성 | P | M3 / M3(브라우저), M1(drill) | E3(merge-48 1회) | 깨진 SW 해제(`service-worker-recovery.spec.ts:79`, chromium·webkit)와 구 탭 청크 복구(세 엔진)가 통과했다. provider 전환 뒤 smoke를 drill 증거로 넣을 방법이 없다(0929/11-02) |
|
||||
|
||||
집계(적용 21개): 충족 1(6) · 부분 충족 20 · 미충족 0 · 미검증 0 · 적용 제외 1(11) · 다른 영역 6(1, 2, 14, 15, 17, 25).
|
||||
지난 라운드와 달라진 곳: 14는 이번에 실행 비용을 재지 않아 >(영역 15)로 넘겼다. 8은 새 11-02 때문에 근거가 바뀌었다(판정은 P 그대로). 21은 P 그대로지만 CI env의 merge 게이트 실패가 사라졌다.
|
||||
|
||||
## 5. 미검증
|
||||
|
||||
| 무엇 | 왜 확인하지 못했나 | 무엇이 있으면 확인할 수 있나 |
|
||||
|---|---|---|
|
||||
| strict fixture의 무시 정규식을 넓히는 변이 | 배치는 결과를 버리는 변이(11-R3)만 돌렸다. 넓히는 쪽을 커밋된 test가 보지 않는다는 것은 코드로만 확인했다 | 정규식을 `/.*/`로 바꾸고 `preload-use.spec.ts` 세 엔진 |
|
||||
| 1103/11-03·11-04의 완료 기준, `.git` 가림 변이 | provider 묶음이 desktop에서 시작하지 못한다(11-02, 11-R10) | bwrap이 비특권 user namespace를 쓸 수 있는 호스트(지난 라운드의 노트북)에서 `test:system`과 가림 삭제 변이 |
|
||||
| 노트북과 desktop의 bwrap 동작이 왜 갈리는지 | 같은 `apparmor_restrict_unprivileged_userns=1`인데 노트북은 지난 라운드에 돌았다. 환경은 고치지 않는다(지시) | 두 호스트의 AppArmor 프로필·커널 차이 비교(영역 12·오케스트레이터) |
|
||||
| 1103/11-02 깨끗한 러너의 글꼴 단계 | U-1 | 글꼴 없는 Ubuntu 24.04 컨테이너나 러너 1대 |
|
||||
| page.route가 끄는 HTTP cache의 영향 | 근거가 Playwright 문서뿐이다. 지금 HTTP cache 동작을 단언하는 test는 없다 | cache 동작을 보는 test를 만들 때 fixture 밖에서 돌거나 fixture에 적는다 |
|
||||
| 앱이 첫 그리기 뒤 자라는 12 px이 다른 browser test에 주는 영향 | 1103/11-10은 두 test만 뺐다. 다른 test의 사례는 없다 | 레이아웃 이동(CLS) 측정(영역 15)이나 같은 400 px 재현을 다른 클릭 spec에 |
|
||||
| 05-01 OPFS 새 test가 경쟁 경로를 실제로 타는지 | `page.waitForTimeout(250)` 뒤에 put을 풀어 준다. purge가 그 안에 대기 지점에 닿지 않으면 경쟁 없이 같은 결과로 통과할 수 있다(추론). 영역 05의 수정 test다 | 영역 05의 수정 되돌림 변이 |
|
||||
| `opfs-runtime.spec.ts`의 OPFS 미지원 엔진 조용한 통과(`:346`, `:438` `return`) | 지난 라운드부터 있던 모양. merge-48에서는 세 엔진 모두 2.5~4.7초 걸려 실제로 돈 것으로 보인다(추론). capability 증거 검사는 "22 cases x 3 engines, zero skipped"지만 `return`은 skip으로 세지 않는다 | test가 지원 여부를 단언하거나 `test.skip`으로 이름을 남김 |
|
||||
| CI 러너 위 FE-GATE-008·013 | U-1 | 러너 1대와 PR 1건 |
|
||||
|
||||
## 6. 실행 기록
|
||||
|
||||
이 영역이 직접 돌린 실행은 없다. 처음 낸 desktop 실행 셋(`11-preload`, `11-allow-files`, `11-a11y`)은 공용 잠금 줄에서 기다리다 19:55에 취소됐다(BRIEF-2). 셋 다 `restored: clean`을 찍기 전이고, checkout을 건드리지 않았다.
|
||||
|
||||
배치 실험(요청 `scratchpad/r4/requests/11.md`, 패치 `scratchpad/r4/requests/11-Rk.diff`, 결과 로그 `scratchpad/r4/results/11/11-Rk.log`). 오케스트레이터가 desktop checkout(`8a44226`)에서 local env로 하나씩 돌렸다. 항목마다 전후로 checkout을 `8a44226`으로 되돌렸고, 10건 모두 `restore=clean`이다. 대조 실행은 merge-48 FE-GATE-008(변이 없는 같은 spec 통과)과 11-R4(probe의 대조)다.
|
||||
|
||||
| ID | 명령(요약) | 변이 | rc · 시간 · load | 결과 |
|
||||
|---|---|---|---|---|
|
||||
| 11-R1 | `playwright test tests/e2e/preload-use.spec.ts` 세 엔진 + `11-parent.mjs` | `preload-use.ts:220` 실패 목록을 비움 | 1 · 16 s · 1.67 | 기대대로. `:45` test 세 엔진 실패(Expected `["preloadunused:/assets/async-state-Cxfod8c-.js"]`, Received `[]`), 6건 통과. parent = `_reference-feature-contract-contribution-XD-KpqsD.js` |
|
||||
| 11-R2 | 같음(parent 없이) | `preload-use.ts:139` 평가 표시 없음 | 1 · 30 s · 1.89 | 기대대로. 9건 모두 실패. 실패마다 쓰인 청크가 `preloadunused:`로 수십 줄 나온다(1번 test는 홈 화면만으로 26줄 더) |
|
||||
| 11-R3 | `preload-use.spec.ts` + probe 세 엔진 | `strict-browser-test.ts:62` 결과 버림 + probe | 1 · 27 s · 2.75 | 기대대로(놓침). `preload-use.spec.ts` 9건과 P1·P2 통과, P3~P6 12건 실패(콘솔 검사는 변이와 무관). P1이 통과한 것이 11-01의 근거 |
|
||||
| 11-R4 | 같음 | probe만 | 1 · 31 s · 4.78 | 기대대로. `preload-use.spec.ts` 9건·P2 3건 통과. P1 3건 `preloadunused:/assets/async-state-Cxfod8c-.js`, P3~P6 12건 `console:warning:`/`console:error:` 한 줄로 실패(15 failed). rc=1은 probe가 일부러 실패한 것이다 |
|
||||
| 11-R5 | 허용 spec 4개 chromium | 각 spec 끝에 허용 밖 안 쓴 preload 주입 | 1 · 17 s · 5.79 | 기대대로. boot(`async-state-…`)·old-tab(`async-state-…`)·csp(`badge-D6w1dKS_.js`) 세 test가 그 한 줄로 실패. SW "removed chunk" test는 `service worker controls: true`로 통과 |
|
||||
| 11-R6 | `browser-files.spec.ts` firefox | 400 px 재현 | 0 · 7 s · 6.52 | 기대대로. 3 passed(6.0 s) |
|
||||
| 11-R7 | 같음 | `ee37dd86` 되돌림 + 재현 | 1 · 71 s · 6.16 | 기대대로. 두 test가 `filechooser`·`download` 대기 30 s 시간 초과, `showOpenFilePicker` test 통과 |
|
||||
| 11-R8b | `create:feature sample-feature --with-create` 뒤 `@a11y /sample` 세 엔진 | 생성 목록 빈 상태에 이름 없는 button(생성기 틀 `scripts/create-feature.ts:1214`) | 1 · 16 s · 2.29 | 기대대로. 생성 명령 성공(파일 33개, 라우트 3개). `@a11y /sample`만 세 엔진 axe `button-name`(`.zz-review-unnamed`, `accessibility.spec.ts:88`)으로 실패. `/sample/items/a11y-1`·`/sample/new` 세 엔진 통과. JSON 결과에 `a11y-data-state` 6곳(상세 라우트 3엔진) |
|
||||
| 11-R8c | 같음 chromium | 답이 Envelope를 무시(`installed-api-answers.ts:43`) | 1 · 17 s · 2.70 | 기대대로. 생성 명령 성공. `@a11y /sample`이 `accessibility.spec.ts:74` `getByRole('alert')` 기대 0·받은 값 1로 실패. 상세·작성 라우트 통과 |
|
||||
| 11-R10 | repo 없이 bwrap 옵션별 `/bin/true` | 없음 | 0 · 0 s · 3.26 | `--unshare-net` rc=1(RTM_NEWADDR), 네트워크 없이 rc=1(`setting up uid map: Permission denied`), `systemd-run --user --scope` 아래 rc=1(RTM_NEWADDR). kernel `7.0.0-38-generic`, `apparmor_restrict_unprivileged_userns = 1`, bwrap 0.9.0. 기대("네트워크 없이는 통과")와 한 곳이 달랐다. 그래서 호스트의 bwrap이 user namespace 자체를 못 쓰는 것으로 정정했다 |
|
||||
|
||||
오케스트레이터가 짧다고 짚은 R08b·R08c(16~17 s)는 로그를 끝까지 읽었다. 둘 다 `create:feature`가 성공했고 webServer 빌드 뒤 test가 돌았다(14.7 s). rc=1은 변이가 일으킨 실패다.
|
||||
|
||||
인용한 오케스트레이터 출력(이 영역이 돌린 것 아님):
|
||||
|
||||
| 출력 | 결과 |
|
||||
|---|---|
|
||||
| `merge-48/summary.txt`(CI env, 19:20 시작, load 0.42) | FE-GATE-020 rc=0 1,156 s · 001 rc=0 579 s · 002 35 s · 003 53 s · 004 13 s · 005 133 s · 006 14 s · 007 29 s · **008 rc=0 181 s** · 009 54 s · 010 66 s · 011 9 s · 012 13 s · **013 rc=1 84 s** |
|
||||
| FE-GATE-008 게이트 로그(`FE-GATE-008.m48.txt`, snapshot과 sha256 같음) | e2e 205건: 202 passed, 3 skipped(firefox SW quarantine, `service-worker-recovery.spec.ts:79`, `service-worker-update.spec.ts:219`, `:240`), 1.8 m, 6 workers. capability 66 passed(42.3 s), "Browser capability evidence: PASS (22 cases x 3 engines, zero skipped)". storybook 1 passed. visual 6 passed. "Test evidence: PASS (416 files, 5 baselines …)". 금지 fixture 4종은 기대대로 실패(EXPECTED_FAILURE). 재시도·flaky 표시 없음. "Execution context was destroyed" 0건 |
|
||||
| FE-GATE-013 게이트 로그(`FE-GATE-013.m48.txt`, snapshot과 sha256 같음) | 사전 점검 PASS, `test:system` 114건 중 18 failed / 96 passed(`ci-artifact-contract.test.ts` 110건 중 18건, 75 s). snapshot `artifacts/tests/system.xml` `failures="18"`. 3.2 (3) 표 |
|
||||
| `r4/013-rest/summary.txt`(CI env) | FE-GATE-013 나머지 7개 명령 모두 rc=0 |
|
||||
| `r4/gates/summary.txt`(local env) | `check:architecture`·`check:types`·`lint`·`test:unit`(194파일 2,883건, `runbook-drill.test.ts` 9건 포함)·`test:component`·`test:integration`·`test:contract`·`test:runtime-schema`·`check:adapter-inventory`·`check:ci` rc=0. `verify:documentation` rc=1(영역 14) |
|
||||
| 메인 세션 FE-GATE-013(같은 커밋, 10:31) | 18 failed / 96 passed, 실패 이름이 merge-48과 같다(대조만) |
|
||||
|
||||
## 7. 새 발견 요약
|
||||
|
||||
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|
||||
|---|---|---|---|---|
|
||||
| 11-01 | Low·P2 | 구조적 위험 | preload 검사 증명 spec이 tracker만 증명해서, strict fixture가 그 결과를 버려도(11-R3, 9건 통과·안 쓴 preload probe 통과) 커밋된 test가 실패하지 않는다. 3번 test는 지연시킬 청크가 없으면 조용히 평범한 방문이 된다 | `tests/support/browser/strict-browser-test.ts:62`, `tests/e2e/preload-use.spec.ts:45-46`, `:105-126` |
|
||||
| 11-02 | Low·P3 | 확인된 결함 | `test:system` 사전 점검이 provider의 bwrap 호출을 한 번도 시험하지 않아, bwrap이 user namespace를 못 쓰는 desktop(11-R10)에서 PASS 뒤 18건이 샌드박스 회귀처럼 실패한다(6건은 원인 문구도 없음). 영역 12의 12-01(Medium·P1)과 같은 결함, README에서 합침 | `scripts/check-system-test-prerequisites.ts:15-38`, `scripts/run-and-validate-provider.ts:255-256`, `tests/system/ci-runner/ci-artifact-contract.test.ts:1782`, `:1812` |
|
||||
@@ -0,0 +1,223 @@
|
||||
# 영역 12 — 가드레일·CI
|
||||
|
||||
> 검토일 2026-11-05 · 기준 `8a44226` (`fix/maturity-review-2026-11-03`) · 가이드 `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`. 함께 본 것: `config/performance/budgets.json`, `config/scale/feature-shape-ceilings.json`, `config/contracts/backend-*.json`, `CLAUDE.md` 2단계 게이트 목록, `README.md` merge 게이트 절
|
||||
> 깊게 본 관점: 5, 19, 20, 21, 23
|
||||
> 렌즈: FE-GATE-013의 호스트 전제(비특권 user namespace)가 어디에 적혀 있고 사전 점검이 알아내는가 · 1103/12-* 9건의 완료 기준 · `e40684b` 이후 약해진 검사 · merge stage와 리뷰 게이트 목록의 차이
|
||||
> 영역 판정(35.8): **조건부 사용 가능.** 지난 라운드 12번 9건 중 7건은 고쳐졌고(12-01은 기능 2개를 더한 상태에서 시각 게이트 통과를 확인했다), 1건은 일부 남았다. 고친 검사들은 스스로 변이를 품은 단위 테스트로 지켜지고, 약해진 검사는 찾지 못했다. 조건은 셋이다. (1) **FE-GATE-013은 bwrap이 user namespace 안에서 네트워크를 만들 수 있는 호스트에서만 통과한다.** 이 desktop(Ubuntu 24.04, AppArmor 제한 켜짐)에서는 항상 실패한다. 사전 점검은 PASS라고 하고, runner 요구 목록 세 곳 어디에도 이 조건이 없다(12-01). (2) 리뷰·머지 확인은 `CLAUDE.md` 목록이 아니라 merge stage 14게이트를 `ci:gate`로 돈다. `CLAUDE.md` 목록은 merge 명령 87개 중 10개만 돌고 7개 게이트를 건드리지 않는다(12-03). (3) `verify:documentation`은 짝 백엔드 checkout이 없거나 pin 커밋에 있는 곳에서 돈다. 옆 checkout의 작업 트리를 읽어서, 이 desktop에서는 문서와 무관하게 실패한다(12-02).
|
||||
|
||||
ID 표기: 이 문서의 `12-NN`은 2026-11-05 라운드 ID다. 2026-11-03 라운드 발견은 `1103/12-NN`, 그 전은 `1101/…`, `0929/…`로 적는다.
|
||||
|
||||
## 0. 결론
|
||||
|
||||
- **지난 라운드 12번 발견 9건: 고쳐짐 7, 일부 1, 대표로 합쳐진 1.** 1103/12-02(드릴이 merge stage에서 명령을 뽑음), 12-04(금지 fixture를 운영 ESLint 설정으로 검사), 12-06(짝 백엔드 pin과 답 표), 12-07(제품 소유 overlay), 12-08(로그 추적 해제), 12-09(`branchesTrue`)는 코드와 게이트 로그로 확인했다. 12-01(시각 골든에서 설치 기능 부분을 숨김)은 `create:feature`로 기능 2개(새 context 둘, 라우트 4개)를 더한 상태에서 `test:visual` 6건이 골든 변경 없이 통과했다(12-R1). 완료 기준 둘째 절("셸 CSS를 바꾸면 여전히 실패")은 확인하지 못했다. 내 변이(12-R2)가 화면을 바꾸지 않는 변이였다. 12-05는 명령 안 경로와 짝 저장소 링크를 고쳤고, 1절 밖 문서는 남았다. 12-03은 11-01로 합쳐졌다(영역 11).
|
||||
- **고친 검사가 실제로 잡는지 스스로 시험한다.** 운영 presentation 규칙을 끄면 금지 fixture 3개가 실패한다(`tests/unit/architecture-lint-fixtures.test.ts:30-47`). merge stage에 명령을 더하면 드릴이 그것을 돈다(`tests/unit/feature-scaffold-drill.test.ts:45`). 오케스트레이터 `test:unit` 2,883건 통과(`gates/test_unit.log`).
|
||||
- **약해진 검사는 찾지 못했다(2.2절).** 초기 JS 파일 상한 25 → 26 → 32는 이유가 커밋 본문과 `docs/operations/performance-evidence.md:169-178`에 있다. 템플릿 자신의 파일 수는 기록 대조(허용 오차 0, `scripts/scale/measure-feature-shape-growth.ts:238-243`)가 따로 잡는다. 새 skip·`eslint-disable`·`@ts-ignore`는 0건이다.
|
||||
- **FE-GATE-013의 호스트 전제가 기록에도 검사에도 없다(12-01, Medium·P1).** provider sandbox는 `bwrap --unshare-net`을 쓴다. 이 desktop에서는 `kernel.apparmor_restrict_unprivileged_userns = 1`이라 bwrap이 loopback을 못 올린다. 사전 점검은 "System test prerequisites: PASS"를 찍고, 이어서 provider 테스트 18건이 `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`로 실패한다(메인 세션 `8a44226` 실행, 오케스트레이터 merge-48도 같다). 이 조건은 한 호스트에서 본 일회성 기록(원장)과 코드 주석에만 있고, runner 요구로 적힌 곳은 없다.
|
||||
- **문서 검사가 pin이 아니라 옆 checkout의 작업 트리를 본다(12-02, Low·P2).** 1103/12-05 수정이 만든 결함이다. 이 desktop의 짝 백엔드는 `ef947e5`(9월)라 `verify:documentation`이 rc=1로 실패했다(`gates/verify_documentation.log`). 같은 커밋을 짝이 없는 임시 worktree에서 돌리면 PASS_SCOPED에 "17 reference(s) … not verified"다(`results/00/00-R2-docs-nosibling.log`). pin(`45d2a478`)에는 그 파일들이 있다.
|
||||
- **`CLAUDE.md`의 리뷰 게이트 목록이 merge stage와 다르다(12-03, Medium·P2).** 지난 라운드는 이 목록을 따르다 11-06·12-09를 놓쳤다(1103 README 10.5절). 목록은 그 뒤에도 바뀌지 않았다. 이번 라운드의 FE-GATE-013 실패도 이 목록으로는 보이지 않는다.
|
||||
- **이월 항목은 그대로다.** 0929/12-01·12-04·12-05·12-06·12-07, 1101/12-03은 코드가 바뀌지 않아 남음. 0929/12-03도 남음이다. feature 안 `support/` 폴더를 거쳐 presentation이 http adapter 배럴에 닿아도 `check:architecture`와 ESLint가 둘 다 통과했다(12-R3).
|
||||
|
||||
## 1. 범위 (36.1)
|
||||
|
||||
| 항목 | 기록 |
|
||||
|---|---|
|
||||
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`, 영역 12 |
|
||||
| 커밋·작업 상태·확인 시점 | `8a44226`. 노트북 worktree `happy-easley-233d07`(HEAD = 기준, 미추적 `AGENTS.md`만)에서 읽었다. 2026-11-05 19:20~ |
|
||||
| 목적과 지원 실행 구성 | 템플릿. 브라우저 SPA + 정적 호스팅 + Service Worker. CI는 `config/ci/gates.json`에서 생성하는 Gitea Actions workflow. merge job은 `runs-on: ubuntu-latest` |
|
||||
| 필수 요구와 규모·운영 목표 | 짝 백엔드 템플릿과 함께 빨리 출시한다. CI 시간·실패율 목표는 없다 |
|
||||
| 읽은 코드·구성 범위 | `git diff e40684b..8a44226`의 영역 파일 31개(+1,168/−187) 전부. 전체: `check-system-test-prerequisites.ts`, `lib/architecture-lint-fixtures.ts`, `lib/feature-scaffold-drill.ts`, `check-backend-contract-drift.ts`, `contracts/product-ci-overlay.ts`, `lib/coverage-summary-metrics.ts`, `lib/build-environment.ts`, `lib/performance-budgets.ts`, `check-bundle.ts`. 부분: `verify-documentation-readiness.ts:160-445`, `generate-ci-workflow.ts`(diff), `contracts/ci-gates.ts:580-660`, `run-and-validate-provider.ts:105-130`·`:250-280`·`:390-420`, `check-architecture.ts:100-220`·`:1040-1090`, `check-registries.ts`(diff), `lib/removal-fixture.ts`(diff), `eslint.config.ts:455-500`·`:676-760`·`:900-945`, `gates.json` stage·job·FE-GATE-013, workflow 머리·merge job, 단위 테스트 7파일, `tests/visual/platform.visual.spec.ts`, `tests/e2e/accessibility.spec.ts:1-85` |
|
||||
| 읽은 문서(주장) | `CLAUDE.md:23`, `README.md:262-270`·`:322-350`, `docs/README.md:17-52`, `docs/operations/ci-quality-gates.md:1-60`·`:100-140`·`:175-215`·`:335-395`, `docs/security/supply-chain.md:55-80`·`:175-215`, `docs/testing/taxonomy.md:10-30`, `docs/operations/adapter-remediation-ledger.md:495-560`, `docs/operations/performance-evidence.md:112-180`, `docs/manual/reference/create-feature.md:1-30`, 지난 라운드 12번 문서와 README 6·10·12~14절 |
|
||||
| 게이트 결과 | 오케스트레이터 `desktop:/tmp/claude-gates/r4/gates/`(로컬 env): `check:architecture`·`check:types`·`lint`·`test:unit`(2,883)·`test:component`·`test:integration`·`test:contract`·`test:runtime-schema`·`check:adapter-inventory`·`check:ci` rc=0, 모두 `dirty=0`. `verify:documentation` **rc=1**(12-02). `merge-48/`(CI env): FE-GATE-001~012·020 rc=0(020 1,156초, 008 181초), **FE-GATE-013 rc=1**(84초). FE-GATE-013은 snapshot `desktop:/tmp/claude-gates/r4/snap/artifacts/quality/gates/FE-GATE-013.txt`에서 "System test prerequisites: PASS" 뒤 114건 중 18건 실패(12-01). 짝 없는 임시 worktree의 `verify:documentation`: PASS_SCOPED, 17개 참조 미확인(`results/00/00-R2-docs-nosibling.log`). 메인 세션의 같은 커밋 실행 `desktop:/tmp/claude-gates/8a44226-ci/`(2026-11-05 10:02~10:31): 13게이트 rc=0, **FE-GATE-013 rc=1** |
|
||||
| 수행한 테스트·실험 | **실행 환경 = desktop.** 내가 직접 띄운 실험 4개(`12-prereq`, `12-arch`, `12-misc`, `12-visual`)는 잠금 대기 중 취소되어 돌지 않았다(BRIEF-2). 대신 오케스트레이터 배치로 3개를 돌렸다: `12-R1`(기능 2개 상태의 `test:visual`), `12-R2`(같은 상태 + 셸 헤더 padding 변이), `12-R3`(0929/12-03 변이). 셋 다 restore 깨끗함. ssh로 읽기만 한 것: 호스트 `sysctl`·`/etc/os-release`·`/etc/apparmor.d` 목록·bwrap 버전, 짝 백엔드 checkout의 HEAD와 파일 존재, 게이트 로그 |
|
||||
| 확인하지 못한 범위·이유 | 실제 Gitea runner(Actions 꺼짐, 1101 U-1). user namespace를 허용하는 호스트에서의 `test:system`. 1103/12-01 완료 기준 둘째 절(셸 CSS 회귀가 여전히 실패): 12-R2 변이가 화면을 바꾸지 않아 증거가 되지 못했다(6절) |
|
||||
| 이전 리뷰와 비교 가능한 범위 | `e40684b..8a44226` 영역 커밋 34개. 지난 실험 결과는 증거로 다시 쓰지 않았다. 지난 라운드 변이 M2·M3·M4는 이번에 다시 돌리지 못했다. M2는 단위 테스트가 같은 변이를 매번 돈다 |
|
||||
|
||||
## 2. 지난 발견 재확인
|
||||
|
||||
### 2.1 상태
|
||||
|
||||
| 지난 ID | 내용 | 상태 | 근거 |
|
||||
|---|---|---|---|
|
||||
| 1103/12-01 | `create:feature` 하나로 merge 게이트 `test:visual`이 실패(Medium·P1로 조정) | **고쳐짐(보존 조건 하나는 미검증)** | **실행(12-R1):** `create:feature probe-feature`와 `probe-write-feature --with-create --keyed`(새 context 둘, 라우트 4개)를 더한 상태에서 `test:visual` 6 passed, 골든 변경 없음(`results/12/12-R1.log`). 지난 라운드에는 기능 1개로 3건이 실패했다. **코드:** 셸 두 장은 설치 기능 라우트의 링크와 `li`를 `display: none`으로 빼고 찍는다(`tests/visual/platform.visual.spec.ts:33-42`, `:60`, `:73`). 플랫폼 구성 화면은 설치 기능을 세거나 나열하는 절 4개와 계약 집합 다이제스트를 숨긴다(`:43-54`, `:115`). 목록은 `ROUTE_FEATURE_OWNER`에서 뽑으므로 기능 수와 무관하다(`:33-35`). 골든 3장을 다시 찍었다(플랫폼 구성 456,747 → 187,585 B). 깨끗한 템플릿의 통과는 `merge-48/FE-GATE-008` rc=0. **확인 못 한 것:** "셸 CSS를 바꾸면 여전히 실패"는 증거가 없다. 12-R2에서 헤더 위아래 padding을 `0.75rem` → `1rem`으로 바꿨는데 6건이 그대로 통과했다(`results/12/12-R2.log`). 이 변이는 화면을 바꾸지 않는다. 헤더 높이는 grid 행 `4.5rem`이 정하고(`src/presentation/styles/theme/shell.css:38`) 내용은 가운데 정렬이다(`:51`). 변이를 잘못 고른 리뷰어 실수다. 정적으로는 숨김 규칙이 기능 라우트의 `a`·`li`와 플랫폼 화면 절 4개만 고른다(`platform.visual.spec.ts:36-54`). 나머지 셸(헤더, 사이드바 틀, 플랫폼 라우트 `APP_HOME`·`EXAMPLES_PLATFORM` 링크, `src/contracts/routes.ts:21`, `:34`)은 계속 스크린샷 안에 있다(E1). 남은 것: 숨긴 절 4개의 모양은 이제 시각 계약 밖이다. 결정 D3 (a)로 정했고 spec 주석(`:23-32`)에 적혀 있다 |
|
||||
| 1103/12-02 | 드릴이 merge 명령 88개 중 15개만 돎 | **고쳐짐** | 드릴이 사본의 `gates.json` merge stage를 순서대로 돈다(`scripts/lib/feature-scaffold-drill.ts:58-104`, `scripts/test-feature-scaffold.ts:101-102`). 제외 15개는 이유와 함께 한 목록이다(`feature-scaffold-drill.ts:26-46`). merge 밖으로 옮긴 명령의 제외는 거부한다(`:91-102`). 단위 테스트 6건(`tests/unit/feature-scaffold-drill.test.ts:14-82`)이 `gates/test_unit.log`에서 통과. 문구도 맞췄다(`docs/manual/reference/create-feature.md:3-4`, `scripts/create-feature.ts:1750`). 드릴은 이제 `verify:documentation`(FE-GATE-017, merge 밖)을 돌지 않는다. 대신 사본의 `test:unit`이 문서를 넣은 사본에서 같은 검사를 돈다(`tests/unit/documentation-readiness.test.ts:58-61`, 제외 조건 `scripts/lib/removal-fixture.ts:76-82`). 약화가 아니다 |
|
||||
| 1103/12-03 (= 11-01) | a11y 게이트가 생성 기능 경로에서 오류 화면을 검사 | **대표 11-01, 영역 11이 판정** | 정적 확인만: spec이 descriptor 모양의 빈 목록으로 답하고(`tests/e2e/accessibility.spec.ts:44-58`) 목록 라우트에서 `alert` 0개를 단언한다(`:72-74`). 단건 조회 라우트는 실패 상태로 검사하고 annotation을 남긴다(`:75-80`) |
|
||||
| 1103/12-04 | 금지 fixture가 fixture 전용 ESLint 규칙을 시험 | **고쳐짐** | fixture마다 그 계층의 운영 경로로 lint하고(`lintAs`), 거부는 지정한 규칙 id로만 센다(`scripts/lib/architecture-lint-fixtures.ts:39-82`, `:141-171`). fixture 전용 블록은 지워졌다(`eslint.config.ts` diff). 목록에 없는 fixture는 실패한다(`:128-130`). 지난 변이 M2와 같은 것(운영 `src/presentation/**`의 `no-restricted-globals`·`no-restricted-imports` 끔)을 단위 테스트가 매번 돌고 3개 fixture 실패를 단언한다(`tests/unit/architecture-lint-fixtures.test.ts:30-47`). 통과: `gates/test_unit.log`. 실제 게이트 출력: "3 allowed PASS, 9 forbidden rejected by the production rule for their layer"(`gates/check_architecture.log`) |
|
||||
| 1103/12-05 | 문서 검사가 명령 안 경로·저장소 밖 링크·지운 심볼·1절 밖 문서를 안 봄 | **일부** | 고친 것: backtick 명령과 셸 블록 안 경로 인자(`scripts/verify-documentation-readiness.ts:243-266`), 짝 저장소 경로·링크(`:214-226`, `:305-316`). 테스트 `tests/unit/documentation-readiness.test.ts:150-209` 통과. 원장 N-06~N-08 행은 백틱 명령을 지우고 "V2와 함께 삭제"로 고쳤다(`docs/operations/adapter-remediation-ledger.md:91-93`). `ungated-scripts.json`의 시점 문장도 지웠다. 남은 것: 지운 심볼, 1절 밖 문서. 예: `docs/testing/frontend-platform-testing-strategy.md:769`가 아직 지운 `tests/integration/auth-recovery.test.ts`를 적는다. 고친 부분이 새 결함을 만들었다(12-02) |
|
||||
| 1103/12-06 | 짝 백엔드 계약 기준이 문서 문장뿐 | **고쳐짐(D6 범위)** | pin 파일(`config/contracts/backend-contract-pin.json`, `45d2a478`)과 백엔드 답 표 사본(`config/contracts/backend-idempotency-answers.json`, 7행, `IDEMPOTENCY_COMPLETION_UNKNOWN` 포함). 단위 테스트가 두 방향으로 대조한다(`tests/unit/backend-contract-pin.test.ts:100-142`, 10건 통과). 표에 `refusedBeforeWrite: true`인 새 409 code를 더하면 기대값은 `NOT_APPLIED`이고 프론트는 `MAYBE_APPLIED`를 낸다(`src/adapters/http/backend-envelope.ts:345-349`). 그래서 그 테스트가 실패한다(코드 추적, E1). 남은 것: 백엔드가 움직인 것을 아는 장치는 게이트 밖 로컬 스크립트뿐이다(`scripts/check-backend-contract-drift.ts`, 이유 `config/ci/ungated-scripts.json:4-7`). 그 스크립트도 커밋된 이력만 본다(`:60`). 노트북 짝 백엔드는 pin에 있고 깨끗하다 |
|
||||
| 1103/12-07 | 배포 슬롯·제품 게이트가 템플릿 `gates.json` 안에 | **고쳐짐** | 제품 소유 `config/ci/product-gates.json`(템플릿은 비워 둠). 로더가 슬롯을 채운 뒤 템플릿 규칙으로 다시 검사하고(`scripts/contracts/ci-gates.ts:590-597`), 기준선은 템플릿 몫만 센다(`:658`). 제품 게이트는 `PRODUCT-GATE-NNN`만, 별도 job(`scripts/generate-ci-workflow.ts` `renderProductGateJob`). 단위 테스트 11건 통과(`tests/unit/product-ci-overlay.test.ts`): 슬롯 채우기, 이중 채움 거부, 없는 script 거부, 템플릿 ID 거부, 템플릿 부분 workflow 바이트 불변. 남은 것: 생성 YAML은 여전히 템플릿이 추적하는 파일이고 제품 job이 끝에 붙는다. 동기화 때 YAML 충돌은 다시 생성해 푼다. 문서는 "a template sync does not meet it"라고만 적는다(`docs/operations/ci-quality-gates.md:365-368`) |
|
||||
| 1103/12-08 | `check:scale:pr`이 커밋된 로그를 다시 씀 | **고쳐짐** | `.gitignore:15-17`이 `artifacts/**/*.log`를 무시하고, `529615dc`가 추적을 끊었다. `git ls-files artifacts`의 `.log` 0개. 그래서 어떤 실행도 추적 로그를 바꿀 수 없다. 오케스트레이터 로그의 모든 명령이 `dirty=0`(`gates/summary.txt`) |
|
||||
| 1103/12-09 | coverage 증거 검사가 `branchesTrue`를 거절 | **고쳐짐** | 키 목록을 한 상수로 두고 두 검사기가 같이 쓴다(`scripts/lib/coverage-summary-metrics.ts`, `scripts/lib/ci-artifact-validator.ts:86-96`, `scripts/lib/risk-coverage.ts:640-656`). `merge-48/FE-GATE-005` rc=0(CI env, 133초) |
|
||||
| 1101/12-03 | 디자인 규칙이 정해진 파일·형식만 봄 | **남음** | `check-design-system.ts`, `lib/design-system-rules.ts`가 `e40684b` 이후 커밋 0개. 그라디언트, TSX 인라인, `base.css` 재정의, feature 폴더 CSS는 그대로 범위 밖(E1) |
|
||||
| 1101 FOLLOW-UP | `noUnusedParameters`, `no-deprecated` 없음 | **바뀜(그대로)** | `tsconfig.base.json:14`는 `noUnusedLocals`뿐. 손 목록 2개(`eslint.config.ts:53-68`). 사용처 판정은 영역 09·16 |
|
||||
| 1101 FOLLOW-UP U-1 | Actions 꺼짐 | **미확인** | Gitea API를 부르지 않았다. README가 이제 "no status is not a pass"와 로컬 실행을 적는다(`README.md:327-330`) |
|
||||
| 0929/12-01 | `check:request-fanout`이 반복 횟수·요청 의존을 안 봄 | **남음** | 파일 커밋 0개. receiver 이름 정규식(`scripts/check-request-fanout.ts:23`), 같은 줄 `fanout-reviewed:`만 인정(`:108`) |
|
||||
| 0929/12-03 | feature 안 layer 밖 폴더에 경계 규칙 없음 | **남음** | **변이(12-R3):** `src/features/reference-feature/support/direct-http.ts`(http adapter 배럴에서 `createContractHttpExecutor` import)와 그것을 import하는 `src/features/reference-feature/presentation/r12-probe-leak.ts`를 더했다. `check:architecture` arch-rc=0(그래프가 421 modules로 두 파일을 읽었다, 무변이 419), ESLint eslint-rc=0(`results/12/12-R3.log`). 무변이 대조: `gates/check_architecture.log` rc=0. 해당 규칙(`.dependency-cruiser.json:140` `concrete-adapters-compose-only-in-bootstrap`, `:302` `feature-and-app-roots-do-not-reach-adapters`)의 diff는 주석뿐이다. 그래프 회귀 fixture 29개에 이 경우가 없다 |
|
||||
| 0929/12-04 | CI 계약 크기가 기준선과 테스트 상수 두 곳 | **남음** | `26ca2fdb`가 `config/ci/contract-baseline.json`(100/104)과 `tests/unit/ci-workflow-generation.test.ts:199-203`(100, 104)을 같이 고쳤다. 절차 문서에 테스트 갱신 단계가 없다(`docs/operations/ci-quality-gates.md:19-27`) |
|
||||
| 0929/12-05 | 실행하지 않는 `dependency-cruiser` 의존성 | **남음** | `package.json:182` `"dependency-cruiser": "18.1.0"`. 검사기는 자기 그래프뿐(`scripts/check-architecture.ts:103-105`) |
|
||||
| 0929/12-06 | Vitest 폴더의 `*.spec.ts`를 게이트 안으로 셈 | **남음** | 파일 커밋 0개. `scripts/lib/ungated-tests.ts:18`(`test|spec`), `:94-95`(폴더 접두어로 판정). Vitest는 `*.test.*`만 돈다(`vitest.config.ts:45`) |
|
||||
| 0929/12-07 | 예외 목록에 담당·재검토 시점 없음 | **남음** | 스키마가 `path|script`와 `reason`뿐(`scripts/lib/ungated-tests.ts:20-34`, `scripts/lib/ungated-scripts.ts:17-31`). 이번에 `check:backend-contract-drift` 항목이 늘었다 |
|
||||
|
||||
요약: 1103 12번 9건 중 고쳐짐 7(12-01은 보존 조건 하나 미검증), 일부 1(12-05), 다른 영역 대표 1(12-03 → 11-01). 이월 10건 중 남음 8, 바뀜 1, 미확인 1. 틀리게 고쳐졌다고 본 항목은 없다. 다만 12-05의 수정이 새 결함 12-02를 만들었다.
|
||||
|
||||
### 2.2 `e40684b` 이후 바뀐 검사의 약화 여부
|
||||
|
||||
| 바뀐 것 | 판정 | 근거 |
|
||||
|---|---|---|
|
||||
| 초기 JS 파일 상한 신설 25 → 26 → 32 (`config/performance/budgets.json:5`) | **정당, 기록됨. 약화 아님** | 상한은 `46dfe23f`가 새로 만든 검사다. 26은 두 수정 브랜치 통합으로 생긴 198 B 파일 하나(`1b8cb126` 본문), 32는 기능 하나가 공유 청크 하나를 떨어뜨리는 경우의 여유(`2fef27d5` 본문, 1103 X2 #4)다. 이유와 "넘으면 먼저 청크 그룹을 본다"가 `docs/operations/performance-evidence.md:169-178`에 있다. 템플릿 자신이 파일을 하나라도 늘리면 기록 대조가 실패한다: `config/scale/feature-shape-ceilings.json`의 `initialJavascript.files: 26`을 빌드와 허용 오차 0으로 비교한다(`scripts/scale/measure-feature-shape-growth.ts:238-243`, `tests/unit/feature-shape-growth.test.ts:150-165`, `gates/test_unit.log` 통과). 상한 초과 자체는 `check:bundle`의 자가 fixture(`scripts/check-bundle.ts:86-97`)와 `tests/unit/check-bundle-output.test.ts`(5건 통과)가 지킨다. 합계 바이트 예산 204,800 B는 그대로 |
|
||||
| 화면 문구 i18n 규칙 예외에 `src/features/platform-examples-feature/presentation/**` 추가(`eslint.config.ts:915-921`) | **범위 동일** | 예제 화면이 `src/presentation/examples`(원래 `screenTextDirectories` 밖)에서 기능 폴더로 옮겨졌다(1103/09-04). 같은 코드에 같은 예외를 유지한다. 이 블록이 빠져도 일반 `no-restricted-syntax`(보안 선택자)는 그 파일에 그대로 걸린다 |
|
||||
| 아키텍처 금지 fixture 전용 ESLint 블록 삭제 | **강화** | 1103/12-04. 운영 규칙으로 검사한다 |
|
||||
| 제거 fixture가 문서 없는 사본에서 문서 테스트 2파일을 지움(`scripts/lib/removal-fixture.ts:62-82`, `:152-154`) | **이유 있음, 약화 아님** | 문서를 복사하지 않는 capability 드릴에서만이다. 원본의 `test:unit`은 그 두 파일을 계속 돈다 |
|
||||
| `check:registries`가 읽지 못한 레지스트리를 참조·기준선 비교에서 뺌(`scripts/check-registries.ts:119-125`, `:408-413`) | **약화 아님** | 읽기 실패는 먼저 `failures`에 들어가 게이트가 실패한다. 같은 원인을 "삭제됨"으로 다시 세지 않을 뿐이다 |
|
||||
| `check:architecture`가 pnpm 경유 요구를 없애고 ESLint API를 씀 | **약화 아님** | 같은 `eslint.config.ts`를 읽는다(`scripts/check-architecture.ts:202-218`) |
|
||||
| CI 계약 기준선 owner `frontend-platform` → `DongHyeonka` | **검사 영향 없음** | 문서는 `CI_CONTRACT_BASELINE_OWNER=<팀>`을 예로 든다(`docs/operations/ci-quality-gates.md:24`). 관점 26에만 적는다 |
|
||||
| 새 `skip`·`fixme`·`eslint-disable`·`@ts-ignore` | **0건** | `git diff e40684b..8a44226 -- src scripts tests eslint.config.ts`의 추가 줄 검색 |
|
||||
|
||||
## 3. 이번 발견 (36.3)
|
||||
|
||||
새 발견 3건: Medium 2 · Low 1 / P1 1 · P2 2 / 확인된 결함 3. High 이상 없음.
|
||||
|
||||
### 3.1 발견 목록
|
||||
|
||||
| ID | 심각도·우선순위 | 성격 | 관련 관점 | 한 줄 |
|
||||
|---|---|---|---|---|
|
||||
| 12-01 | Medium · P1 | 확인된 결함 | 21, 19, 20, 8, 5 | FE-GATE-013의 호스트 전제(bwrap이 user namespace 안에서 네트워크를 만듦)가 runner 요구 목록과 사전 점검 어디에도 없어, 이 desktop에서는 사전 점검 PASS 뒤 `test:system` 18건이 bwrap 원문 오류로 실패한다 |
|
||||
| 12-02 | Low · P2 | 확인된 결함 | 21, 17, 20, 23, 8 | `verify:documentation`이 짝 백엔드 참조를 pin 커밋이 아니라 옆 checkout의 작업 트리에서 찾아, 같은 커밋이 기계마다 다른 결과를 낸다 |
|
||||
| 12-03 | Medium · P2 | 확인된 결함 | 21, 5, 26, 23, 10 | `CLAUDE.md`의 리뷰 게이트 목록이 merge stage와 달라, 따르면 merge 명령 87개 중 10개만 돌고 7개 게이트와 `ci:gate`의 증거 검사가 빠진다 |
|
||||
|
||||
### 12-01 FE-GATE-013의 호스트 전제가 runner 요구 목록과 사전 점검 어디에도 없어, 이 desktop에서는 사전 점검 PASS 뒤 `test:system` 18건이 bwrap 원문 오류로 실패한다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 21, 19, 20, 8, 5 |
|
||||
| 근거 | **전제:** provider sandbox는 `bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net`으로 provider를 띄운다(`scripts/run-and-validate-provider.ts:254-256`). `test:system`은 merge 게이트 FE-GATE-013의 첫 명령이다(`config/ci/gates.json:2011-2041`, merge stage `:2236-2256`). **사전 점검:** `scripts/check-system-test-prerequisites.ts`는 실행 파일 3개(`:15-19`), cgroup controller 파일(`:21-28`), `systemctl show-environment`(`:30-38`)만 본다. namespace를 만들어 보지 않는다. **실행(메인 세션, 같은 커밋 `8a44226`, desktop, 2026-11-05 10:29):** 게이트 로그 첫 줄이 "System test prerequisites: PASS"다. 이어서 "Tests 18 failed \| 96 passed (114)". 18건 모두 provider 테스트이고 오류는 "sandboxed external provider failed: exit=1, signal=none; sandbox reported: bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted"다(`desktop:…/artifacts/quality/gates/FE-GATE-013.txt`, `artifacts/tests/system.xml`에 23회). FE-GATE-013 rc=1(`/tmp/claude-gates/8a44226-ci/summary.txt`). 오케스트레이터 merge-48(CI env)도 같다: snapshot `desktop:/tmp/claude-gates/r4/snap/artifacts/quality/gates/FE-GATE-013.txt`에서 "System test prerequisites: PASS" 뒤 114건 중 18건 실패. **호스트(ssh 읽기):** Ubuntu 24.04.4 LTS, `kernel.apparmor_restrict_unprivileged_userns = 1`, `/etc/apparmor.d/unprivileged_userns` 있음, bwrap 전용 profile 없음, bubblewrap 0.9.0(setuid 아님). **기록:** runner 요구 목록 세 곳이 bwrap·prlimit·systemd·cgroup v2만 적는다(`docs/operations/ci-quality-gates.md:181-185`, `docs/security/supply-chain.md:182-186`, `docs/testing/taxonomy.md:15`). `gates.json`과 workflow에도 호스트 조건 칸이 없다. merge job 14게이트가 같은 `runs-on: ubuntu-latest`다(`.gitea/workflows/quality-gates.yml:37`, `:55`). README는 merge 게이트 14개를 로컬에서 돌리라고 하면서 008·009(브라우저)와 012(빌드)의 조건만 적는다(`README.md:326-338`). 이 조건을 아는 곳은 둘뿐이다. 하나는 원장의 "Host restriction discovered during this pass" 절이다(`docs/operations/adapter-remediation-ledger.md:531-546`). 한 호스트에서 `bwrap --unshare-net`이 `apparmor_restrict_unprivileged_userns = 1`로 실패했다는 일회성 기록이고, runner 요구로 적지 않았다. 다른 하나는 코드 주석이다(`scripts/run-and-validate-provider.ts:394-405`). 둘 다 runner를 준비하는 사람이 읽는 요구 목록이 아니다. 1103 README 14.5절 9·11회차는 "013은 desktop 환경 문제(사용자 결정 대기)"로 적었다 |
|
||||
| 발생 조건 | 비특권 user namespace가 제한된 호스트에서 FE-GATE-013을 돌릴 때마다. 이 desktop이 그렇다. Ubuntu는 23.10부터 이 제한을 두었고 24.04에서 기본으로 켰다(외부 사실. 이 리뷰가 확인한 호스트는 desktop 한 대다). user namespace를 막은 컨테이너도 같다(추론) |
|
||||
| 영향 | merge stage가 이 호스트에서 한 번도 초록이 될 수 없다. provider sandbox의 격리·cgroup·guardian 테스트 18건이 돌지 못한다. 운영자는 PASS 뒤 커널 netlink 문장을 보고 원인을 이력 문서에서 찾아야 한다. 템플릿을 받은 제품도 같은 호스트에서 같은 일을 겪는다 |
|
||||
| 심각도·우선순위 | Medium · P1 — 사용자 피해는 없다. 적힌 요구를 모두 만족하는 호스트에서 merge 게이트가 항상 실패한다. 1103/11-02(runner에 글꼴 패키지가 없어 FE-GATE-008 실패, Medium·P1)와 같은 기준이다. 고치는 비용이 작다 |
|
||||
| 통제·증거 | 목표 M3(사전 점검이 호스트 조건을 알아내고 이름을 댄다) / 확인: namespace 조건 M0(원장의 일회성 기록은 요구가 아니라 M1에도 못 미친다), 나머지 runner 조건 M1(문서)·M3(실행 파일·cgroup·bus 점검) · E3(메인 세션과 오케스트레이터 merge-48 게이트 실행, 같은 커밋) + 호스트 읽기 + E1 |
|
||||
| 확실성과 남은 가정 | 실패 원인, PASS 출력, 문서 누락은 확정. AppArmor가 `unprivileged_userns` profile로 capability를 빼서 loopback 설정이 막힌다는 기전은 외부 사실이다. user namespace를 허용하는 호스트에서 18건이 통과하는지는 이번에 보지 않았다(원장은 그런 호스트에서 107/108이었다고 적는다, `adapter-remediation-ledger.md:545-547`, 주장) |
|
||||
| 결정의 근거 | 확인한 사실: OPS-23이 bwrap의 원문 줄을 살려 원인을 보이게 했다(`run-and-validate-provider.ts:394-415`). 원장은 제한이 "세션 도중에 켜졌다"고 적고(`adapter-remediation-ledger.md:542-544`), 그 호스트의 기록으로 남겼다. 사전 점검과 요구 목록에 넣은 기록은 없다. 추론: 일시적인 호스트 상태로 보고 계약으로 올리지 않았다. 그러나 같은 desktop에서 이번에도 두 번(10:29, merge-48) 같은 실패가 났으므로 일시적 상태가 아니다 |
|
||||
| 이해 비용 | runner를 준비하는 사람은 문서의 조건을 다 맞춘 뒤에도 실패를 보고, sysctl과 AppArmor를 스스로 찾아야 한다 |
|
||||
| 최소 개선 방향 | (1) 사전 점검이 provider와 같은 플래그로 `bwrap --unshare-net … /bin/true`를 한 번 돌린다. 실패하면 sysctl 값과 함께 "unprivileged user namespaces are restricted: allow bwrap with an AppArmor profile or use a host that permits them"처럼 이유와 할 일을 적고 exit 1. (2) runner 요구 목록 세 곳에 이 조건 한 줄. (3) README merge 게이트 절에 013의 호스트 조건 한 줄 |
|
||||
| 대안 비교 | (a) 현 상태: 비용 0, 매 실행 원인 추적. (b) 위 (1)~(3): 수십 줄, 실패가 사전 점검에서 이름과 함께 난다. (c) FE-GATE-013을 release stage로 옮김: PR마다 sandbox 검사를 잃는다. 보안 검사 약화라 버린다. (d) namespace가 없으면 provider 테스트를 skip: 거짓 초록이라 버린다. (b)가 가장 작다 |
|
||||
| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다. sandbox 플래그와 provider 테스트 114건은 그대로 둔다 |
|
||||
| 비용·부작용 | 스크립트 10~20줄, 문서 3줄. probe 1회는 수 ms |
|
||||
| 재검토 조건 | provider sandbox가 network namespace 말고 다른 격리로 바뀌면 probe를 바꾼다 |
|
||||
| 완료 기준 | 이 desktop에서 `node scripts/check-system-test-prerequisites.ts`가 exit 1로 끝나고 user namespace 제한을 이름으로 적는다. 제한이 없는 호스트에서는 PASS. 요구 목록 세 곳에 조건이 있다 |
|
||||
| 검증 방법 | desktop에서 사전 점검 실행. 허용 호스트(또는 bwrap AppArmor profile을 넣은 뒤)에서 `test:system` |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규. 호스트를 고칠지는 사용자 결정 대기이고, 조건을 적고 알리는 것은 템플릿 몫이다. 1101/13-03(영역 13, provider job의 runner 전제)과 원인이 겹친다. 이 항목은 merge 게이트의 사전 점검과 요구 목록만 센다. 영역 11의 같은 결함(1105/11-02)은 오케스트레이터가 README에서 이 항목으로 합친다 |
|
||||
|
||||
### 12-02 `verify:documentation`이 짝 백엔드 참조를 pin 커밋이 아니라 옆 checkout의 작업 트리에서 찾아, 같은 커밋이 기계마다 다른 결과를 낸다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함(1103/12-05 수정 `b4e4f98c`가 만들었다) |
|
||||
| 관련 관점 | 21, 17, 20, 23, 8 |
|
||||
| 근거 | **코드:** 짝 저장소 위치는 `cwd`의 부모다(`scripts/verify-documentation-readiness.ts:214-215`). 짝 경로는 그 작업 트리에서 찾는다. checkout이 없으면 `unverifiedLinks`로 넘기고 통과한다(`:312-313`, `:438-445`). checkout이 있는데 파일이 없으면 `missingPaths`로 실패한다(`:314-315`). pin(`config/contracts/backend-contract-pin.json:5`, `45d2a478`)은 읽지 않는다. `../`로 나가는 링크의 첫 폴더가 없으면 짝 저장소 이름이 틀려도 같은 "unverified" 가지로 간다(`:308-313`). **실행:** 오케스트레이터 `gates/verify_documentation.log`(desktop checkout, 로컬 env)가 rc=1이다. 5개 문서가 `../clean-architecture-backend-template/docs/web/http-contract.md`, `…/docs/manual/07-authorization.md`, `…/src/adapter/inbound/web-advanced/README.md`, `…/src/application-fileserver`를 "names paths that do not exist"로 적고 "FAIL_UNVERIFIED (failed: document references)". **원인(ssh 읽기):** desktop의 옆 checkout은 `ef947e5`(2026-09-16)이고 미커밋 변경이 있다. 그 트리에 위 4개 경로가 없다. 같은 커밋을 짝이 없는 임시 worktree에서 돌리면 PASS_SCOPED이고 "17 reference(s) into paired repositories not verified"를 찍는다(오케스트레이터 `results/00/00-R2-docs-nosibling.log`). 노트북 원본 checkout의 짝 백엔드는 pin에 있고, 이 리뷰 worktree는 부모가 `.claude/worktrees`라 짝이 없다. 같은 커밋이 놓인 곳에 따라 FAIL·PASS·PASS(17개 미확인)가 된다. **테스트도 이 의존을 피해 간다:** "Only this document is under test: other documents name paired-backend paths the stub checkout does not have"(`tests/unit/documentation-readiness.test.ts:179-180`). **주장:** `docs/README.md:44-47`은 "그 checkout이 옆에 있을 때만 확인"이라고 적고 어느 커밋인지는 적지 않는다 |
|
||||
| 발생 조건 | 짝 백엔드를 pin과 다른 커밋으로 옆에 둔 checkout에서 `verify:documentation`(`CLAUDE.md` 목록, FE-GATE-017)을 돌릴 때 |
|
||||
| 영향 | 사용자가 테스트용으로 정한 desktop에서 리뷰 게이트가 문서와 무관하게 실패한다. 옆 checkout이 pin보다 새로우면 pin에 없는 파일을 적어도 통과한다. 저장소 이름 오타는 "확인 못 함"으로 통과한다. CI는 영향이 없다(짝 checkout이 없어 unverified). merge 때의 문서 검사(`test:unit`의 `documentation-readiness.test.ts:58-61`)는 `/tmp` 사본에서 돌아 영향이 없다 |
|
||||
| 심각도·우선순위 | Low · P2 — merge 게이트에는 영향이 없다. 리뷰와 개발 루프의 결과를 기계마다 다르게 만들고, 고치는 비용이 작다 |
|
||||
| 통제·증거 | 목표 M3(pin 커밋의 트리를 확인) / 확인: 옆 checkout이 pin에 있을 때 M3, 다른 커밋일 때 M0(그 트리를 그대로 믿음) · E3(오케스트레이터 게이트 로그) + E1 |
|
||||
| 확실성과 남은 가정 | 확정. 짝이 pin보다 새로운 경우(거짓 통과)는 실행하지 않았고 코드 추적이다(`:314-316`) |
|
||||
| 결정의 근거 | 확인한 사실: 1103/12-05는 "옆에 있으면 확인, 없으면 unverified"를 골랐다(1103 12번 문서 5.2절 (b)). pin 파일은 다른 수정 브랜치(`ba2b4f4c`, 1103/12-06)에서 들어왔고 두 수정이 이어지지 않았다. 추론: 두 브랜치를 따로 만든 뒤 합쳤다 |
|
||||
| 이해 비용 | 실패를 본 사람은 문서를 고치려다 옆 저장소의 커밋이 원인임을 찾아야 한다 |
|
||||
| 최소 개선 방향 | (1) 옆 checkout에 pin 커밋이 있으면 `git -C <짝> cat-file -e <pin>:<경로>`로 pin 트리에서 찾는다. (2) pin 커밋이 없으면 실패 대신 "unverified (짝 HEAD `<sha>`, pin `<sha>`)"로 적는다. (3) 첫 폴더가 알려진 짝 저장소가 아닌 `../` 링크는 실패로 센다 |
|
||||
| 대안 비교 | (a) 현 상태. (b) 위 (1)~(3): 수십 줄, 결과가 기계와 무관해진다. (c) 짝 HEAD가 pin과 다르면 전부 unverified: 더 단순하지만 다른 커밋에서는 아무것도 확인하지 못한다. (d) 짝 문서를 이 repo로 복사: 사본 동기화가 하나 더 생긴다. (b)를 권한다 |
|
||||
| 단순화의 보존 조건 | 짝이 없을 때 PASS + unverified, 명령 안 경로 검사, 1103/12-05 테스트 4건은 그대로 |
|
||||
| 비용·부작용 | 스크립트 수십 줄, stub 짝 저장소에 커밋 2개를 만드는 단위 테스트 |
|
||||
| 재검토 조건 | 짝 문서를 패키지나 서브모듈로 가져오게 되면 그 판을 기준으로 바꾼다 |
|
||||
| 완료 기준 | 짝이 `ef947e5`(pin 없음)인 desktop에서 PASS + unverified. 짝 HEAD가 pin 뒤에 있을 때 결과가 pin 트리와 같다. 저장소 이름 오타 링크는 실패한다 |
|
||||
| 검증 방법 | 위 세 경우를 stub git 저장소로 만드는 단위 테스트. desktop에서 `verify:documentation` |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
|
||||
### 12-03 `CLAUDE.md`의 리뷰 게이트 목록이 merge stage와 달라, 따르면 merge 명령 87개 중 10개만 돌고 7개 게이트와 `ci:gate`의 증거 검사가 빠진다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함(리뷰 절차와 게이트 계약이 다르다) |
|
||||
| 관련 관점 | 21, 5, 26, 23, 10 |
|
||||
| 근거 | **목록:** `CLAUDE.md:23`이 명령 11개를 적는다. **계약:** merge stage는 14게이트, 명령 참조 88개(서로 다른 명령 87개, `build`가 011·012에 겹침)다(`config/ci/gates.json:2236-2256`). 목록은 그중 10개를 돈다. 하나도 돌지 않는 게이트가 7개다: FE-GATE-001(lockfile), 008(e2e·capability·storybook·시각), 009(a11y), 011(build·storybook), 012(bundle), 013(security, 12-01), 020(제거·생성 드릴). 003은 25개 중 1개, 010은 21개 중 3개다. 나머지 하나 `verify:documentation`은 merge 밖 FE-GATE-017이다. 이 게이트는 `workflow_dispatch`에 `stage=documentation`일 때만 돈다(`.gitea/workflows/quality-gates.yml:466`). **빠지는 단계:** 명령을 직접 돌리면 `ci:gate`가 하는 로그·증거 산출물 검증(`scripts/run-ci-gate.ts:217`), 음성 fixture 30개의 기대 실패 판정, workflow env(`README.md:340-349`)가 빠진다. 1103/12-09는 증거 검증에서만, 11-07·11-08은 CI env에서만 실패했다. **이력:** 1103 README 10.5절이 이 목록만 따르다 11-06·12-09(둘 다 Medium·P1)를 놓쳤다고 적었다. `CLAUDE.md`는 그 뒤에도 바뀌지 않았다(`git log e40684b..8a44226 -- CLAUDE.md` 0건, 마지막 `412b3d1f`). 이번 라운드는 오케스트레이터가 따로 merge stage를 돌려 메웠다(BRIEF §2). **두 번째 사본:** `README.md:336`도 14개 ID를 손으로 적는다(지금은 맞다) |
|
||||
| 발생 조건 | 누군가 `CLAUDE.md`의 리뷰 절차를 그대로 따를 때. Actions가 꺼져 있어(`README.md:327-330`) 리뷰 실행이 유일한 게이트 실행일 때 특히 |
|
||||
| 영향 | "게이트 통과"라고 적힌 리뷰에서 merge 게이트 7개는 아무도 돌리지 않았다. 지금 이 목록으로는 FE-GATE-013의 실패(12-01)가 보이지 않는다. 지난 라운드에는 항상 실패하는 merge 게이트 두 개가 리뷰를 통과했다 |
|
||||
| 심각도·우선순위 | Medium · P2 — 런타임 피해는 없다. 항상 실패하는 merge 게이트를 리뷰마다 숨길 수 있고 실제로 숨겼다. 고치는 비용은 문서 몇 줄이다 |
|
||||
| 통제·증거 | 목표 M3(리뷰 절차가 게이트 계약에서 목록을 얻는다) / 확인 M1(손 목록) · E1 + 지난 라운드 기록 + 이번 게이트 결과 대조 |
|
||||
| 확실성과 남은 가정 | 확정 |
|
||||
| 결정의 근거 | 확인한 사실: 목록은 2026-09 가이드 커밋 때 적은 것이다. 그 뒤 merge stage에 FE-GATE-020 등 게이트와 명령이 늘었다. 추론: 목록을 계약에서 뽑지 않아 따라가지 못했다 |
|
||||
| 이해 비용 | 리뷰어는 목록과 `gates.json`을 직접 대조해야 빠진 게이트를 안다 |
|
||||
| 최소 개선 방향 | (1) `CLAUDE.md` 2단계를 "merge stage `gateIds`를 workflow env로 `ci:gate` 하나씩, 그리고 `verify:documentation`"으로 바꾼다. (2) 더 낫게는 merge stage를 `gates.json`에서 읽어 도는 명령 하나(예: `ci:gate:stage merge`)를 두고 `CLAUDE.md`와 README가 그것을 가리킨다 |
|
||||
| 대안 비교 | (a) 현 상태. (b) 문서만 고침: 다시 손 목록이 된다. (c) stage 실행 명령: 목록 사본이 0이 되고 계약이 바뀌면 따라간다. (d) `check:ci`가 README·`CLAUDE.md`의 목록을 계약과 대조: 문서 파싱이 늘어난다. (c)를 권한다 |
|
||||
| 단순화의 보존 조건 | `ci:gate`의 첫 실패에서 멈추는 동작과 게이트별 로그 산출물은 그대로 |
|
||||
| 비용·부작용 | 스크립트 수십 줄 또는 문서 두 곳. merge stage 전체는 이 desktop에서 게이트 시간 합 2,419초(약 40분, FE-GATE-020 1,156초 포함, `merge-48/summary.txt`) |
|
||||
| 재검토 조건 | merge stage가 둘 이상의 job으로 나뉘거나, 리뷰가 실제 runner 결과를 읽게 되면 |
|
||||
| 완료 기준 | `CLAUDE.md`와 README가 merge stage를 손으로 나열하지 않는다. 리뷰 절차를 따르면 merge stage 14게이트가 `ci:gate`로 돈다 |
|
||||
| 검증 방법 | merge stage에 게이트 하나를 더한 사본에서 절차의 명령이 그것을 도는지 본다 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
|
||||
## 4. 28개 관점 판정 (36.2)
|
||||
|
||||
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 굵은 번호가 이번에 깊게 본 관점이다.
|
||||
|
||||
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | 코드 성숙도 | 적용 제외 — 이 영역에 도메인 규칙이 없다 | — | — | - |
|
||||
| 2 | 구조적 성숙도 | 적용 — 경계 강제 장치 | M3 / import 방향 M3(그래프 29 fixture), 운영 ESLint 계층 규칙 M3(1103/12-04), feature 안 layer 밖 폴더 M0 | E3 | P · 0929/12-03 남음(12-R3: 변이가 그래프·ESLint 모두 통과) |
|
||||
| 3 | 변경 용이성 | 적용 | M3 / P | E3 | P · 기능 2개를 더해도 템플릿 골든을 다시 찍지 않는다(1103/12-01, 12-R1). 배포·제품 게이트는 overlay로 갔다(1103/12-07). 게이트 하나 변경은 여전히 기준선·테스트 상수를 같이 고친다(0929/12-04) |
|
||||
| 4 | 인지 부하 | 적용 | — | E1 | P · `gates.json` 2,990줄, workflow 488줄. overlay는 5줄 파일이라 제품 쪽 부담은 줄었다 |
|
||||
| **5** | 위험 가시성 | 적용 | M3 / P | E3 | P · FE-GATE-013 사전 점검이 PASS라고 한다(12-01). 리뷰 목록이 merge 게이트 7개를 빼고 "통과"라고 한다(12-03). 금지 fixture 출력은 이제 운영 규칙을 시험한 것이 맞다 |
|
||||
| 6 | 실패 성숙도 | 적용 제외 — 런타임 실패 처리가 없는 영역 | — | — | - |
|
||||
| 7 | 운영 성숙도 | 다른 영역 | — | — | > 영역 13 |
|
||||
| 8 | 디버깅 가능성 | 적용 | M3 / P | E3 | P · 번들 실패가 넘은 한도와 초과량을 적는다(`check-bundle.ts:120-145`). 아키텍처 fixture 실패가 규칙과 경로를 적는다. bwrap 실패는 원문 netlink 문장뿐이다(12-01). 문서 검사 실패가 원인(옆 checkout 커밋)을 적지 않는다(12-02). fanout 메시지 그대로(0929/12-01) |
|
||||
| 9 | 유지보수 성숙도 | 적용 | — | E1 | P · 로그 churn은 사라졌다(1103/12-08). 미사용 `dependency-cruiser`(0929/12-05). merge 게이트 목록 손 사본 두 곳(12-03) |
|
||||
| 10 | 테스트 성숙도 | 적용 | M3 / P | E2 | P · 고친 검사마다 변이를 품은 단위 테스트가 있다(2.1절). 고아 `*.spec.ts`(0929/12-06). 리뷰 절차가 merge 명령 대부분을 돌지 않는다(12-03) |
|
||||
| 11 | 데이터 성숙도 | 적용 제외 | — | — | - |
|
||||
| 12 | 동시성 성숙도 | 적용 제외 | — | — | - |
|
||||
| 13 | 확장성 | 일부 적용 | — | E2 | > 영역 09·15. 이 영역 몫: 초기 파일 상한 32(현재 26), 바이트 여유는 영역 15 |
|
||||
| 14 | 성능 성숙도 | 적용 | — | 로컬만 | ? · runner가 없다. desktop에서 FE-GATE-020 1,156초(job 상한 45분의 43%, `merge-48`), 001은 이번 실행에서 579초(메인 세션 실행 3초, 원인 미확인) |
|
||||
| 15 | 보안 성숙도 | 적용(workflow 범위) | M4 / M4 | E1 | O · `permissions: contents: read`, action 33개 모두 40자 SHA, `persist-credentials: false` 9곳, `pull_request_target` 0. 배포 secrets는 deploy 단계에만 렌더한다(`generate-ci-workflow.ts` `isStepScopedSecret`). provider sandbox 검증이 이 호스트에서 돌지 못한다(12-01) |
|
||||
| 16 | 의존성 성숙도 | 적용 | M3 / P | E2 | P · 짝 백엔드 pin이 기계가 읽는 파일이 됐다(1103/12-06). 문서 검사는 그 pin을 쓰지 않는다(12-02). 미사용 `dependency-cruiser@18.1.0`(0929/12-05) |
|
||||
| 17 | API / Contract | 적용 | M3 / P | E2 | P · 답 표와 Envelope 표를 두 방향으로 대조한다. 백엔드가 움직인 것은 게이트 밖 로컬 스크립트만 안다(1103/12-06 남은 것) |
|
||||
| 18 | 배포 성숙도 | 다른 영역 | — | — | > 영역 13. 이 영역 몫: 배포 슬롯이 제품 overlay로 갔다(1103/12-07) |
|
||||
| **19** | 설정 성숙도 | 적용 | M3 / P | E3 | P · runner 호스트 조건이 계약·문서에 다 적혀 있지 않다(12-01). 제품 CI 설정은 템플릿 파일 밖으로 나왔다(1103/12-07) |
|
||||
| **20** | 개발자 경험 | 적용 | — | E3 | P · 사용자가 정한 테스트 호스트에서 `verify:documentation`과 FE-GATE-013이 변경과 무관하게 실패한다(12-02, 12-01). 로컬 게이트가 트리를 더럽히지 않는다(`dirty=0`) |
|
||||
| **21** | Guardrail 성숙도 | 적용 | M3 / 로컬 P, 머지 시점 미확인 | E3 | P(로컬) · ?(머지 시점) · 지난 라운드 X의 원인(02-06 드릴 항상 실패, 11-06·12-09)은 이번 merge-48에서 FE-GATE-001~012·020 통과로 사라졌다. 13게이트가 통과하고 013만 이 호스트에서 실패한다. 남은 틈: 12-01(013은 이 호스트에서 항상 실패), 12-02, 12-03, 0929/12-03·12-06 |
|
||||
| 22 | 추상화 성숙도 | 적용 | — | E1 | O · overlay는 허용 칸 셋(deploy script, bindings, 제품 게이트)으로 좁고 스키마로 막았다. 드릴 제외 목록은 이유를 값으로 든다 |
|
||||
| **23** | 일관성 | 적용 | — | E1 | P · merge 게이트 목록이 계약·README·`CLAUDE.md` 세 곳이다(12-03). 문서 검사와 pin 테스트가 짝 백엔드 기준을 다르게 잡는다(12-02). coverage 키 목록은 한 상수가 됐다(1103/12-09) |
|
||||
| 24 | 네이밍 / 의미 | 적용 | — | E3 | P · "System test prerequisites: PASS"가 sandbox를 띄울 수 없는 호스트에서도 나온다(12-01). "PASS_SCOPED"는 unverified를 같이 적어 정직하다 |
|
||||
| 25 | 조직 확장성 | 적용(팀 하나라 구조만) | — | E2 | P · 기능 추가(12-R1로 시각 게이트까지 확인)·배포·제품 게이트가 템플릿 파일을 고치지 않는다(1103/12-01·12-07). 생성 YAML은 동기화 때 다시 생성해야 한다 |
|
||||
| 26 | Ownership | 적용 | M1 / P | E1 | P · 예외 목록에 담당·재검토가 없다(0929/12-07). CI 기준선 owner가 팀이 아니라 개인 이름이다(`config/ci/contract-baseline.json:3`). 리뷰 절차 문서의 담당이 없다(12-03) |
|
||||
| 27 | 삭제 가능성 | 적용 | M3 / P | E2 | P · 제거 드릴 셋이 문서 테스트 제외를 같은 상수로 쓴다. 1절 밖 문서에 지운 테스트 경로가 남았다(1103/12-05 남은 것) |
|
||||
| 28 | 회복 가능성 | 적용 제외 — 이 영역에 복구 경로가 없다 | — | — | - |
|
||||
|
||||
## 5. 미검증
|
||||
|
||||
| 항목 | 이유 | 확인하려면 |
|
||||
|---|---|---|
|
||||
| 셸 CSS 회귀가 기능 부분을 숨긴 시각 게이트에서 여전히 실패하는가(1103/12-01 완료 기준 둘째 절) | 12-R2 변이(헤더 위아래 padding)가 화면을 바꾸지 않았다. grid 행 높이 고정 + 가운데 정렬이라 렌더가 같다 | 배경색이나 사이드바 너비처럼 보이는 셸 속성 하나를 바꾸고 기능 1개 상태에서 `test:visual` |
|
||||
| 짝 백엔드가 pin보다 새로울 때의 거짓 통과(12-02) | 그런 checkout이 없다 | stub git 저장소 단위 테스트 |
|
||||
| user namespace를 허용하는 호스트의 `test:system` | 그런 호스트가 없다 | AppArmor bwrap profile을 넣은 호스트나 다른 runner에서 1회 |
|
||||
| 실제 Gitea runner와 머지 시점 강제 | Actions 꺼짐(1101 U-1) | runner 1대와 PR 1건 |
|
||||
| FE-GATE-001이 이번에 579초 걸린 이유 | 영역 밖(lockfile 설치), 로그만 봄 | 영역 13 또는 오케스트레이터 |
|
||||
|
||||
## 6. 실행 기록
|
||||
|
||||
| 이름 | 명령 | 변이 | rc | 결과 | 잠금 대기 | load |
|
||||
|---|---|---|---|---|---|---|
|
||||
| `12-prereq` | `bash /tmp/claude-gates/r4/mut/12-prereq-cmd.sh`(호스트 probe, 사전 점검, provider 테스트 1건) | 없음 | — | **돌지 않음.** 잠금 대기 중 ssh가 끊기고(255), 이어 실험 실행이 닫혔다(BRIEF-2). restore 대상 없음 | — | — |
|
||||
| `12-arch` | `bash …/12-arch-cmd.sh`(`check:architecture` 무변이·M2·M4·M5) | 명령 안에서 | — | **돌지 않음** | — | — |
|
||||
| `12-misc` | `bash …/12-misc-cmd.sh`(문서 검사 probe, pin 변이, `check:scale:pr`, 고아 spec, overlay) | 명령 안에서 | — | **돌지 않음** | — | — |
|
||||
| `12-visual` | `bash …/12-visual-cmd.sh` | `12-visual-mut.sh` | — | **돌지 않음** | — | — |
|
||||
| 배치 `12-R1` (20:08:26) | `corepack pnpm -s test:visual` | `12-R1-two-features.sh`(`create:feature probe-feature`, `probe-write-feature --with-create --keyed`, `git add -N .`, 54파일) | visual-rc=0 | **6 passed**(11.3초), 골든 변경 없음. 기대대로 | 배치 | 3.42 |
|
||||
| 배치 `12-R2` (20:08:40) | 같음 | `12-R2-two-features-shell-css.sh`(12-R1 + `.app-shell__header` padding `0.75rem 1.25rem` → `1rem 1.25rem`) | visual-rc=0 | **6 passed.** 기대(실패)와 다르다. 원인은 변이 쪽이다: 헤더 높이를 grid 행 `4.5rem`이 정하고(`shell.css:38`) 내용이 가운데 정렬이라(`:51`) 위아래 padding을 늘려도 렌더가 같다. 이 실행은 셸 회귀 검출의 증거가 아니다(리뷰어 실수) | 배치 | 2.87 |
|
||||
| 배치 `12-R3` (20:08:54) | `check:architecture` + ESLint 2파일 | `12-R3-feature-support-leak.diff` | arch-rc=0, eslint-rc=0 | 둘 다 통과. 그래프가 421 modules(무변이 419)로 두 파일을 읽었다. 0929/12-03 남음 확인. 무변이 대조 `gates/check_architecture.log` | 배치 | 2.58 |
|
||||
| ssh 읽기 | `sysctl …userns…`, `/etc/os-release`, `ls /etc/apparmor.d`, `ls -l /usr/bin/bwrap`, `dpkg -s bubblewrap`, 짝 백엔드 `git log -1`·파일 존재 | 없음 | 0 | 12-01·12-02 근거 | 없음 | 4~7 |
|
||||
|
||||
끊긴 실험 4개는 desktop checkout을 건드리기 전에 끝났다(`/tmp/claude-gates/r4/exp/`에 `12-*.log` 없음). 배치 3개는 오케스트레이터가 돌렸고 각 실행 앞뒤로 checkout을 `8a44226`으로 되돌렸다(`results/12/summary.txt`: 셋 다 `restore=clean`, 마지막 `status=empty head=8a44226`). 배치 rc는 마지막 echo의 것이라 판정은 로그 안의 `visual-rc`·`arch-rc`·`eslint-rc`로 했다. 증거로 쓴 다른 실행: 오케스트레이터 `gates/`(로컬 env), `merge-48/`(CI env)와 그 snapshot, 짝 없는 `verify:documentation`(`results/00/00-R2-docs-nosibling.log`), 메인 세션 `/tmp/claude-gates/8a44226-ci/`(같은 커밋, 2026-11-05 10:02~10:31). 요청서는 `scratchpad/r4/requests/12.md`, 로그는 `scratchpad/r4/results/12/`.
|
||||
|
||||
## 7. 새 발견 요약
|
||||
|
||||
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|
||||
|---|---|---|---|---|
|
||||
| 12-01 | Medium · P1 | 확인된 결함 | FE-GATE-013의 user namespace 전제가 요구 목록·사전 점검에 없어, 이 desktop에서 사전 점검 PASS 뒤 provider 테스트 18건이 bwrap 원문 오류로 실패한다 | `scripts/check-system-test-prerequisites.ts:15-38`, `scripts/run-and-validate-provider.ts:254-256`, `docs/operations/ci-quality-gates.md:181-185` |
|
||||
| 12-02 | Low · P2 | 확인된 결함 | `verify:documentation`이 짝 백엔드 참조를 pin이 아니라 옆 checkout 작업 트리에서 찾아 기계마다 결과가 다르다(desktop rc=1) | `scripts/verify-documentation-readiness.ts:214-215`, `:308-316` |
|
||||
| 12-03 | Medium · P2 | 확인된 결함 | `CLAUDE.md` 리뷰 게이트 목록이 merge stage와 달라 merge 명령 87개 중 10개만 돌고 7개 게이트와 증거 검사가 빠진다 | `CLAUDE.md:23`, `config/ci/gates.json:2236-2256` |
|
||||
@@ -0,0 +1,218 @@
|
||||
# 영역 13 — 빌드·릴리스·설정·공급망
|
||||
|
||||
> 검토일 2026-11-05 · 기준 `8a44226`(`fix/maturity-review-2026-11-03`) · 가이드 `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/contracts/{ci-gates,product-ci-overlay}.ts`(배포 슬롯 부분), `scripts/generate-ci-workflow.ts`(배포 슬롯·제품 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`(배포 job), `.gitea/workflows/quality-gates.yml`(env, `immutable_build`~`production_gate`), `src/contracts/{env,deployment-admission}.ts`
|
||||
> 깊게 본 관점: 15, 16, 18, 19, 21
|
||||
> 렌즈: 1103/11-08 수정(`b693600`)이 release 빌드 검사를 약하게 했는가 · 1103/13-01~05 수정 결과 · FE-GATE-013의 test:system 뒤 명령
|
||||
> 영역 판정(35.8): **조건부 사용 가능.** "빌드 → 공개 대상 승인 → 손으로 배포"는 그대로 써도 된다. 지난 라운드 P1 결함 1103/13-01은 고쳐졌다. 템플릿 자신의 nginx 예시를 실제 TLS로 띄워 확인했다(배치 13-R02). 같은 run에서 로컬 프로필로 다시 빌드한 release는 이제 FE-GATE-019가 FAIL한다. HTTP/1.1만 되거나 압축하지 않는 호스트도 FAIL한다. 예시 그대로의 호스트는 PASS한다. **배포 슬롯을 채워 CD로 쓰기 전에 두 가지를 알아야 한다.** release 단계 job(`immutable_build`)은 gate 로그를 올리지 않는다. 그래서 FE-GATE-015·027이 왜 실패했는지와 13-03 수정이 만든 advisory 경고가 실제 workflow에서 사라진다(13-01). 제품 merge 검사(`PRODUCT-GATE-*`)는 실패해도 같은 run의 release·배포를 막지 않는다(13-02). 운영 의존성 high advisory 2건은 결정 대기로 남았다(1103/13-03). provider 없이는 슬롯까지 가지 못하는 1101/13-03도 남았다. desktop에서는 provider sandbox가 아예 뜨지 않는다(merge-48 FE-GATE-013).
|
||||
|
||||
ID 표기: 이 문서의 `13-NN`은 2026-11-05 라운드 ID다(라운드 밖에서는 `1105/13-NN`). 지난 라운드는 `1103/13-NN`, 그 전은 `1101/…`, `0929/…`다.
|
||||
|
||||
## 0. 결론
|
||||
|
||||
- **11-08 수정(`b693600`)은 release 빌드 검사를 약하게 하지 않았다.** 검사 함수 `ciBuildEnvironmentFailures`는 그대로다(`scripts/lib/build-environment.ts:9-41`). workflow env(CI=true)에서 커밋 ID·`SOURCE_DATE_EPOCH`·`CI_RUNNER_IMAGE`가 없거나 틀리면 음성 실행 14개가 모두 실패했다. 빌드 자체, `build:release-candidate`, `verify:reproducible-build`, `ci:gate FE-GATE-015·013`이 포함된다(13-R01). "로컬" 표시(`CI !== "true"`)를 release job env나 생성 workflow에 넣으면 `check:ci`가 실패했다(13-R03·R04). 수정을 되돌리면 CI=true의 fixture 빌드가 `missing … VITE_COMMIT_SHA`로 멈췄다(13-R05). 수정된 상태는 CI=true merge 게이트에서 통과한다(merge-48 FE-GATE-005·008·020).
|
||||
- **1103/13-01·13-02·13-04·13-05는 고쳐졌다(E3).** 실제 nginx 1.27.5에 예시 설정을 그대로 올렸다. 결과는 다음과 같다. 후보는 `PASS (live)`(55개 항목). 같은 run 로컬 재빌드는 `runtimeConfig build-fields` FAIL(`API_BASE_URL`, `APP_ENV`, `AUTH_MODE`, `TELEMETRY_*`). 비상 스위치만 바꾸면 PASS. `http2 on;`을 빼면 `alpn` FAIL(`http/1.1`). `gzip on;`을 빼면 `content-encoding` FAIL(13-R02). 고친 규칙을 하나씩 끄면 단위 테스트가 6개 모두 잡았다(13-R07~R12).
|
||||
- **1103/13-03은 일부다.** dev advisory는 사라졌고 FE-GATE-027이 판정한다. 2026-11-05 20:09 기준 결과는 `POLICY_VIOLATION`이다. 운영 high 2건(`react-router@7.18.1` GHSA-qwww, `zod@4.4.3` GHSA-mrhx), 개발 moderate 2건이 나왔다(13-R01). 운영 2건은 결정 대기다.
|
||||
- **새 발견 13-01(Medium·P1): `immutable_build`가 gate 로그를 올리지 않는다.** `ci:gate`는 명령 출력을 로그 파일에만 쓴다. 콘솔에는 한 줄만 남는다. 13-R01에서 FE-GATE-027 콘솔은 2줄이었다(`FE-GATE-027 release-admission: PASS`). advisory 경고 4줄은 로그 파일에만 있었다. FE-GATE-015가 실패할 때도 콘솔은 `FAIL` 한 줄이었다. 이유는 로그 파일에만 있었다. `immutable_build`는 그 파일을 올리지 않는다(`.gitea/workflows/quality-gates.yml:122-207`).
|
||||
- **새 발견 13-02(Medium·P2): 제품 merge 검사가 release·배포를 막지 않는다.** `product_merge_gate` job에는 `needs` 관계가 없다(`scripts/generate-ci-workflow.ts:129-157`). job 그래프는 계약이 고정한다(`scripts/contracts/ci-gates.ts:926-933`). 그래서 제품이 그 연결을 더할 방법도 없다.
|
||||
- **FE-GATE-013의 test:system 뒤 명령 7개는 CI env에서 모두 통과했다**(오케스트레이터 `013-rest`). FE-GATE-013 자체는 merge-48에서 rc=1이다. 원인은 `tests/system`의 provider sandbox다(`bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`). desktop의 `kernel.apparmor_restrict_unprivileged_userns = 1` 때문이다. 이 영역 코드의 결함은 아니다. 다만 1101/13-03의 호스트 전제를 사용자의 배포 기계가 지금 만족하지 않는다는 사실을 보여 준다.
|
||||
- **지난 이월 항목 중 0929/13-07·13-08·13-09는 고쳐졌다.** 0929/13-02·13-03·13-04·13-05·13-06·13-10, 1101/13-03, R-2는 남았다.
|
||||
|
||||
## 1. 범위 (36.1)
|
||||
|
||||
| 항목 | 기록 |
|
||||
|---|---|
|
||||
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`, 영역 13 — 빌드·릴리스·설정·공급망 |
|
||||
| 커밋·작업 상태·확인 시점 | `8a44226`. 노트북 worktree `happy-easley-233d07`(HEAD = 기준, 추적 파일 변경 없음)에서 읽기만 했다. 실행은 오케스트레이터가 desktop checkout(`8a44226`)에서 배치로 돌렸다. 매 항목 앞뒤로 기준 커밋으로 되돌렸고 12개 모두 `restore=clean`이다. 2026-11-05 19:20~20:40 |
|
||||
| 목적과 지원 실행 구성 | 템플릿. 브라우저 SPA + 정적 호스팅 + Service Worker(기본 `null`). 사용자 목표: 짝 백엔드 템플릿과 빨리 출시하고 desktop 서버로 배포한다 |
|
||||
| 필수 요구와 규모·운영 목표 | 수치 목표는 초기 JS 204,800 gzip B와 파일 32개(`config/performance/budgets.json:4-5`). 서빙 전제는 h2와 압축(`config/hosting/cache-policy.json:3-5`, `:29`) |
|
||||
| 읽은 코드·구성 범위 | 머리의 경로 전체. 그 밖에 `vitest.config.ts:17-23`, `playwright.{visual,capabilities,dev}.config.ts`의 webServer env, `scripts/check-supply-chain-provider-fixtures.ts:55-90`. 주장 자료: `README.md:330-352`, `docs/operations/{ci-quality-gates,release-cache-rollback}.md`, `docs/architecture/static-delivery.md:30-62`, 커밋 본문 `b693600`, `cd7e784`, `4bce8bf3`, `2e12d2f0`, `4c4248aa`, `26ca2fdb`, `eeb6f92f`, `a144b575`, `1497e64c`, `7af8e366`, `e440ece9` |
|
||||
| 수행한 테스트·실험 | 배치 13-R01~R12(요청 `scratchpad/r4/requests/13.md`, 결과 `scratchpad/r4/results/13/`). R01: CI env 음성 실행 14개와 FE-GATE-027 콘솔 확인. R02: 실제 nginx·실제 TLS로 live probe 6회. R03·R04: `check:ci` 변이 2개. R05·R06: 11-08 수정 되돌림 변이 2개. R07~R12: 이 영역 수정 규칙 변이 6개. 대조군은 오케스트레이터 게이트 로그다. 6절 |
|
||||
| 확인하지 못한 범위·이유 | 실제 Gitea runner(콘솔·작업 디렉터리 정리·`needs` 처리), 채운 배포 슬롯, provider 실행, 실제 운영 호스트(인증서·CDN), advisory 도달 가능성. 5절 |
|
||||
| 이전 리뷰와 비교 가능한 범위 | `docs/reviews/2026-11-03-maturity-review/13-build-release-supply-chain.md`의 새 발견 5건과 그 문서가 남음·일부로 둔 이월 11건. README §12의 13-행, §10.3에서 13-02에 합친 15-05 뒷부분, §13의 11-08(이 영역 경로의 수정)도 본다. `git log e40684b..8a44226 -- <경로>` 19커밋. 지난 실험 결과는 증거로 쓰지 않았다 |
|
||||
|
||||
### 1.1 오케스트레이터 게이트 결과 중 이 영역에 해당하는 것 (`8a44226`)
|
||||
|
||||
| 게이트 | 결과 | 이 영역에 주는 의미 |
|
||||
|---|---|---|
|
||||
| `test:unit`(local env, `gates/test_unit.log`) | rc=0, 194파일 2,883건 | 통과한 파일: `hosting-probe` 37, `ci-workflow-generation` 426, `product-ci-overlay` 11, `env-registry-coverage` 4, `dependency-advisories` 5, `local-build-environment` 3, `build-environment` 4, `pnpm-install-policy` 2, `service-worker-build-output` 7, `deployment-admission` 25. 배치 변이 R05~R12의 대조군이다 |
|
||||
| `check:ci`(local) | rc=0 | R03·R04의 대조군 |
|
||||
| FE-GATE-005·008·020(CI=true, merge-48) | rc=0(133초·181초·1,156초) | 테스트가 띄우는 로컬 빌드가 CI=true에서 통과한다. 008 안의 결과: e2e 202, capability 66, storybook 1, visual 6 |
|
||||
| FE-GATE-010(CI=true) | rc=0 | `check:ci` 포함 |
|
||||
| FE-GATE-011·013(CI=true) | 로그 첫 줄 `derived SOURCE_DATE_EPOCH=1793840484 from HEAD` | merge-48은 `SOURCE_DATE_EPOCH`를 주지 않았다. `ci:gate`가 HEAD 시각으로 채웠다(2.3절 (a)) |
|
||||
| FE-GATE-012(CI=true) | rc=0, `initial JS 202973 / 204800 gzip bytes, 26 / 32 files` | 여유 1,827 B |
|
||||
| FE-GATE-013(CI=true) | **rc=1**, test:system 114건 중 18건 실패 | 실패 원인은 `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`(provider sandbox, `tests/system/ci-runner/ci-artifact-contract.test.ts`)다. desktop은 `kernel.apparmor_restrict_unprivileged_userns = 1`이다. 영역 11·12 몫이다. 이 영역에서는 1101/13-03 근거로만 쓴다 |
|
||||
| FE-GATE-013의 test:system 뒤 명령(CI env, `013-rest/`) | 7개 모두 rc=0 | `verify:reproducible-build`: `PASS (fca93d18…)`. `build:release-candidate`: `Supply chain: LOCAL PASS (562 dependencies); promotion=FAIL_UNVERIFIED`, secret scan PASS(1,613파일), 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 검출 |
|
||||
|
||||
## 2. 지난 발견 재확인
|
||||
|
||||
### 2.1 2026-11-03 라운드(이 영역) 발견과 이 영역 경로의 수정
|
||||
|
||||
| 지난 ID | 내용 | 상태 | 근거 |
|
||||
|---|---|---|---|
|
||||
| 1103/13-01 | FE-GATE-019가 run 이름만 대조하고 `config.json` 내용과 슬롯의 후보 사용을 보지 않는다 | **고쳐짐** | **코드.** probe가 받은 `/config.json`을 후보 `dist/config.json`과 비교한다. 비상 스위치 두 개 밖의 필드가 다르거나 읽을 수 없으면 FAIL이다(`scripts/lib/hosting-probe.ts:216-232`). 규칙은 `scripts/lib/runtime-config-switches.ts:11-27`에 있고 `check-release-admission.ts:112`도 같은 함수를 쓴다. 받은 entry script를 후보의 것과 비교한다(`hosting-probe.ts:208-215`). 후보는 `--release-root`에서 읽는다(`scripts/verify-hosting-headers.ts:107-116`). 슬롯에 deploy script가 있으면 세 가지가 있어야 한다: `promoted-release` download, extract, `CANDIDATE_ARCHIVE_SHA256`(`scripts/contracts/ci-gates.ts:1268-1299`). 제품 overlay는 이 단계를 템플릿이 채운다(`scripts/contracts/product-ci-overlay.ts:116-146`). **완료 기준 확인(13-R02).** 지난 라운드 E-2c를 실제 nginx로 재현했다. 같은 run 이름(`gitea-77-1`)의 로컬 프로필 재빌드는 후보와 `config.json` 하나만 달랐다. 그 재빌드를 올린 호스트는 FAIL했다(`runtimeConfig build-fields` 관측 `["API_BASE_URL","APP_ENV","AUTH_MODE","TELEMETRY_ENABLED","TELEMETRY_ENDPOINT"]`, rc=1). 후보는 PASS, 비상 스위치(`CAPABILITY_OVERRIDES.REALTIME`)만 바꾸면 PASS였다. **변이.** 비교를 끄면(13-R07) "fails a host whose config.json is not the candidate's"와 "…unreadable" 2건이 실패한다. 슬롯 입력 규칙을 끄면(13-R10) "rejects a slot that deploys without the promoted candidate"와 "…extracts the candidate without its digest" 2건이 실패한다. 남은 한계는 커밋 본문이 적은 대로다. deploy script가 받은 파일을 실제로 올리는지는 계약이 못 본다. 결과는 FE-GATE-019가 본다 |
|
||||
| 1103/13-02 | HTTP/2·압축 전제가 호스팅 계약·probe에 없고 nginx 예시가 둘 다 켜지 않는다 | **고쳐짐** | **코드.** `transport.alpnProtocols: ["h2"]`, `hashedAsset.contentEncodings`(`config/hosting/cache-policy.json:3-5`, `:29`). probe가 TLS handshake에서 고른 프로토콜을 본다(`hosting-probe.ts:64-81`, `:233-251`). entry script의 `Content-Encoding`도 본다(`verify-hosting-headers.ts:163-175`). nginx 예시에 `http2 on;`, `gzip on;`, `gzip_types`가 있다(`docs/operations/release-cache-rollback.md:123-137`). **완료 기준 확인(13-R02).** 예시 그대로(포트·인증서 경로만 바꿈) 띄웠다. 결과: curl `/` HTTP/2, entry `content-encoding: gzip`, probe `alpn="h2"`, PASS. `http2 on;`만 빼면 `transport alpn` FAIL(관측 `http/1.1`). `gzip on;`만 빼면 `hashedAsset content-encoding` FAIL(관측 없음). **변이.** ALPN 판정을 끄면(13-R08) "fails a host that does not negotiate a declared protocol"이 실패한다. 압축 판정을 끄면(13-R09) "fails a hashed asset served without a declared content encoding"이 실패한다. **동작 변화.** HTTP/1.1 호스트는 이제 FAIL이고 문서에 적혀 있다(`release-cache-rollback.md:95-104`, `docs/architecture/static-delivery.md:57-62`). 선언을 HTTP/1.1로 바꿀 때 초기 청크를 묶었는지 보는 검사는 없다(M1, 4절 14번) |
|
||||
| 15-05 뒷부분(→ 1103/13-02에 합침) | HTTP/2 서빙 전제를 확인하는 장치가 없다 | **고쳐짐** | 위 13-02와 같다. 앞부분(초기 파일 수 상한)은 영역 15 몫이다. 상한은 26 → 32로 올랐고(`config/performance/budgets.json:5`, `2fef27d5`) 그 근거로 이 전제를 든다 |
|
||||
| 1103/13-03 | 취약점 판정이 운영 승격 provider에만 있고, lockfile이 자체 정책을 어기는데 merge·release에서 모른다 | **일부** | **고쳐진 것.** dev 의존성을 갱신했다(`package.json:171-192`, `eeb6f92f`). 기준선을 다시 승인했다(`config/security/dependency-baseline.approval.json:3-6`). FE-GATE-027이 `scan:dependency-advisories`를 돈다(`config/ci/gates.json:2205-2210`). 판정은 승격과 같은 `validateVulnerabilityReport`다(`scripts/lib/dependency-advisories.ts:152-176`). 항상 exit 0이다(`scripts/scan-dependency-advisories.ts:15-18`). `renovate.json`이 생겼다. 13-R01 실측: `POLICY_VIOLATION`, 운영 high 2건(GHSA-qwww-vcr4-c8h2 `react-router@7.18.1`, GHSA-mrhx-c7xc-m3w5 `zod@4.4.3`), 개발 moderate 2건(GHSA-3g3m-2fjr-6pw4 `glob@13.0.6`, GHSA-g3hv-75wg-m249 `minimatch@10.2.5`). 운영·개발 구분은 맞게 나왔다. 지난 라운드 44건에서 4건으로 줄었다. **남은 것.** (1) 운영 high 2건 그대로다(`package.json:160-161`, `pnpm-lock.yaml:2376`, `:2816`). 결정 대기로 적혀 있다(owner와 다른 reviewer 필요, zod 4.6.x는 약 +7 KB로 예산 초과, 재확인 2026-12-04, `docs/operations/ci-quality-gates.md:499-508`). (2) 신호가 실제 workflow에서 보이지 않는다. 원인은 새 13-01이다. 완료 기준 "release 단계 산출물에 advisory 수가 남는다"를 채우지 못한다. (3) renovate는 runner가 없어 동작하지 않는다(`renovate.json:4`). (4) merge 단계 신호는 없다. 비차단으로 고른 설계라 받아들인다 |
|
||||
| 1103/13-04 | FE-REG-ENV 런타임 행의 `required`·`defaultValue`가 스키마와 다르다 | **고쳐짐** | 커버리지 테스트가 두 가지를 더 본다: 스키마가 읽지 않는 행, 행 값과 스키마의 대조(`tests/unit/env-registry-coverage.test.ts:44-64`). 5개 행을 맞췄다(`src/contracts/env.ts:62-69`). 변이(13-R12)로 `AUTH_MODE` 행 기본값을 지난 값 `"external"`로 되돌리면 실패한다. 메시지: `AUTH_MODE: row {"required":true,"defaultValue":"external"}, schema {"required":true,"defaultValue":null}` |
|
||||
| 1103/13-05 | 슬롯 `secrets.*`가 job 전체 env로 렌더링된다 | **고쳐짐** | 배포 job의 `secrets.*`는 job env에서 빠지고(`scripts/generate-ci-workflow.ts:193`) deploy 단계 `env:`에만 들어간다(`:331-345`, 판정 `:376-378`). 변이(13-R11)로 판정을 끄면 "accepts a deployment job the slot allows"가 `expected ' env:\n CANDIDATE_ARCHIVE_SHA…' not to contain 'secrets.'`로 실패한다. 제품 overlay 경로는 같은 렌더러를 쓴다. 다만 `product-ci-overlay.test.ts`는 이 변이에서 통과했다. 그 경로의 secret 위치는 따로 단언하지 않는다 |
|
||||
| 1103/11-08(영역 11 발견, 수정이 이 영역 경로) | CI=true가 테스트 안의 로컬 빌드까지 release 빌드로 검사한다 | **고쳐짐, 검사 약화 없음** | 아래 2.3절 |
|
||||
|
||||
### 2.2 지난 영역 문서가 남음·일부로 둔 이월 항목
|
||||
|
||||
| 지난 ID | 내용 | 상태 | 근거 |
|
||||
|---|---|---|---|
|
||||
| 1101/13-03 | provider job의 호스트 전제와 workflow의 컨테이너 전제가 어긋나고 provider 없는 배포 경로가 없다 | **남음** | provider job은 `runs-on: ubuntu-latest`다(`.gitea/workflows/quality-gates.yml:212`, `:258`). 배포 슬롯은 `promotion` 뒤에만 돈다(`scripts/contracts/ci-gates.ts:933`). provider 없이 배포하는 절은 없다(`docs/operations`·`README.md` grep). 새 사실: 사용자의 배포 대상 desktop에서 provider sandbox 시험이 뜨지 않는다. merge-48 FE-GATE-013의 test:system 18건이 `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`로 실패했다(`apparmor_restrict_unprivileged_userns = 1`). 이 기계에 runner를 붙이면 provider job도 같은 이유로 막힐 것으로 본다(추정, runner 미실행) |
|
||||
| 0929/13-02 | `.env*` 파일로 준 빌드 변수를 번들과 스크립트가 다르게 읽는다 | **남음** | `vite.config.ts:18`의 `loadEnv`는 미선언 변수를 거절할 때만 쓴다. asset base는 `:174`에서 `process.env`로 읽는다. `generate-runtime-config.ts:59`, `:70-74`, `generate-build-manifest.ts:36-39`, `vite.service-worker.config.ts:58-59`도 `process.env`다. `.env.example:14`는 여전히 "`.env.local`로 복사해 덮어쓰라"고 적는다 |
|
||||
| 0929/13-03 | 청크 이름이 선언 없이 계약처럼 쓰인다 | **남음**(Low, fail-closed) | route chunk를 `entry.name === runtime.moduleId`로 찾고 없으면 빌드가 멈춘다(`scripts/generate-build-manifest.ts:64-72`) |
|
||||
| 0929/13-04(= R-3) | CSP가 여러 벌이고 내용 검사가 없다 | **남음** | 같은 CSP 문자열이 6곳에 있다: `config/hosting/security-headers.json:4`, `response-headers.fixture.json:7`, `:17`, `:27`, `:42`, nginx 예시 `release-cache-rollback.md:115`. `scripts/check-browser-security.ts`에는 CSP 내용 검사가 없다(grep 0건). live probe는 받은 CSP를 `security-headers.json`과 비교한다(`verify-hosting-headers.ts:176-186`). 13-R02 P1이 PASS했으므로 지금 nginx 예시 사본은 정책과 같다. 이 비교는 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`). 실제로는 react-dom 청크에 이름으로 묶여 실린다(`vite.config.ts:226-238`) |
|
||||
| 0929/13-06 | 하위 경로 배포에서 base를 따르지 않는 소비자가 있다 | **일부(남음)** | live probe가 루트가 아닌 URL을 거절한다(`scripts/lib/hosting-probe.ts:411-418`) |
|
||||
| 0929/13-07(= R-5) | 청크 설정이 폐기 예정 `build.rollupOptions`에 있다 | **고쳐짐** | `vite.config.ts:192`, `vite.service-worker.config.ts:79`가 `rolldownOptions`를 쓴다(`e440ece9`). `rollupOptions`는 리뷰 문서·CHANGELOG 밖에서 0건이다 |
|
||||
| 0929/13-08 | pnpm 설치 정책을 지키는 검사가 없다 | **고쳐짐** | `tests/unit/pnpm-install-policy.test.ts:15-36`(`1497e64c`)가 세 가지를 본다. `engineStrict`·`saveExact`가 `true`인지, `minimumReleaseAge`가 1,440분 이상인지, 예외가 정확한 버전만인지다. 통과(E2). 변이는 돌리지 않았다 |
|
||||
| 0929/13-09 | README 변수 표에 staging·production의 `VITE_BUILD_ID` 필수 조건이 없다 | **고쳐짐** | `README.md:46`(`7af8e366`) |
|
||||
| 0929/13-10 | 선택 기능을 켜야 재현되는 템플릿 결함의 책임 | **남음** | `README.md:393-398`의 "unmodified checkout" 문구가 그대로다 |
|
||||
| R-2 | 빌드 입력 기본값을 한 곳에서 정한다 | **남음** | 기본값이 네 곳에 흩어져 있다: `generate-runtime-config.ts:73`(`\|\|`)·`:74`(`??`), `generate-build-manifest.ts:36-38`(`??`), `vite.service-worker.config.ts:58-59`(`??`), `src/contracts/env.ts:173-174`(`\|\|`) |
|
||||
|
||||
지난 라운드 판정이 틀렸다고 본 항목은 없다.
|
||||
|
||||
### 2.3 1103/11-08 수정(`b693600`, 안내 `cd7e784`)의 약화 확인
|
||||
|
||||
| 확인 | 판정 | 근거 |
|
||||
|---|---|---|
|
||||
| 검사 자체가 바뀌었는가 | 아니다 | `b693600`은 `scripts/lib/build-environment.ts`에 26줄을 더했을 뿐이다. `ciBuildEnvironmentFailures`(`:9-41`)와 `ciCheckoutIdentityFailures`(`:90-111`)는 그대로다. 단위 테스트가 "CI job 자체 release 빌드는 계속 검사된다"를 따로 단언한다(`tests/unit/local-build-environment.test.ts:37-41`) |
|
||||
| (a) CI=true에서 커밋 ID·`SOURCE_DATE_EPOCH`·`CI_RUNNER_IMAGE`가 없거나 틀린 release 빌드는 여전히 실패하는가 | **실패한다(E3, 13-R01)** | 같은 env의 대조군 빌드는 rc=0이었다. 음성 실행은 모두 rc=1이었다. **(1) 커밋 ID 없이 `build:release-candidate`:** 빌드 7단계에서 멈췄다(`missing required CI build environment: VITE_COMMIT_SHA`, `generate-build-manifest.ts:25`). **(2) 빌드 7단계에 값 하나씩 틀리게:** `VITE_COMMIT_SHA=local`, `SOURCE_DATE_EPOCH` 없음, `SOURCE_DATE_EPOCH=2026-11-05`, `CI_RUNNER_IMAGE` 없음·빈 값·`local/runner:latest`. 각각 "must be a full 40- or 64-character …", "missing … SOURCE_DATE_EPOCH", "must be non-negative epoch seconds", "missing … CI_RUNNER_IMAGE"(2회), "must end with an immutable @sha256 image digest"로 실패했다. **(3) 커밋 ID 없이 `verify:reproducible-build`:** "missing … VITE_COMMIT_SHA". **(4) `ci:gate FE-GATE-015`:** 커밋 ID 없음, epoch 형식 오류, 다른 epoch(`946684800`), 빈 이미지, 다른 커밋(40자리 0)이 각각 실패했다. 메시지는 순서대로 "missing …", "does not match … / must be non-negative", "does not match the checked-out commit timestamp", "missing … CI_RUNNER_IMAGE", "does not identify the checked-out commit"였다. **(5) `ci:gate FE-GATE-013`:** 커밋 ID 없이 실패했다. 예외 하나: `ci:gate`는 비어 있는 `SOURCE_DATE_EPOCH`를 HEAD 시각으로 채운다(`run-ci-gate.ts:82-85`). merge-48 로그 첫 줄 `derived SOURCE_DATE_EPOCH=1793840484 from HEAD`가 그 경우다. 이 동작은 `b693600` 전부터 있었다. 틀린 값은 채우지 않고 실패한다 |
|
||||
| (b) "로컬" 표시를 release 경로에서 실수나 의도로 켤 수 있는가 | **release job에서는 켤 수 없다(E3, 13-R03·R04)** | "로컬" 표시는 `CI !== "true"`다(`build-environment.ts:12`). **함수로 켜는 길:** `localBuildEnvironment`·`LOCAL_BUILD_IDENTITY`를 쓰는 곳은 다섯 곳뿐이다: `tests/e2e/support/fixture-builds.ts:65`, `tests/e2e/support/service-worker-builds.ts:179`, `playwright.{visual,capabilities,dev}.config.ts`. FE-GATE-013·015 명령은 이 함수를 부르지 않는다. **env로 켜는 길:** `immutable_build` env에 `CI` 바인딩을 더했더니 `check:ci`가 `job environment binding drift: immutable_build`로 실패했다(R03). 생성 workflow의 `immutable_build`에 `CI: "false"`를 손으로 넣었더니 `generated workflow drift at byte 5473, line 134`로 실패했다(R04). 대조군 `check:ci`는 rc=0이다. `check:ci`는 FE-GATE-010에 있고, release job은 merge job 뒤에만 돈다(`ci-gates.ts:927-929`). 제품이 `CI`를 바인딩할 수 있는 곳은 배포 job 하나다(`product-ci-overlay.ts:28-37`). 그 job은 후보가 만들어지고 승격된 뒤에 돈다. 재빌드를 올리면 FE-GATE-019의 `config.json` 비교가 잡는다(13-R02 P2). 그래서 발견으로 세지 않는다 |
|
||||
| (c) 테스트 쪽 로컬 빌드는 CI=true에서 통과하고, 수정이 그 이유인가 | **그렇다(E3, 13-R05·R06)** | 수정된 상태: merge-48(CI=true)에서 FE-GATE-005·008·020이 rc=0이다. 008의 visual 6건과 capability 66건은 `LOCAL_BUILD_IDENTITY` webServer로 돈다. 되돌린 상태: spawn 지점 둘을 `process.env`로 되돌리고 CI env로 돌렸다(R05). `service-worker-build-output`이 `scripts/build-frontend.ts failed for sw-profile-active` / `missing required CI build environment: VITE_COMMIT_SHA`로 멈췄다(7건 미실행). vitest가 `VITE_COMMIT_SHA`만 지우고 `CI`는 남기기 때문이다(`vitest.config.ts:22-23`). `localBuildEnvironment`가 `CI`를 남기게 바꾸면 "is not checked as a CI build …"가 CI 식별값 누락 5건을 보이며 실패한다(R06) |
|
||||
| 테스트가 실제 경로를 덜 보게 됐는가 | 아니다 | 수정 전에도 fixture 빌드와 시각 골든 빌드는 release 빌드 검사를 통과하는 경로가 아니었다. CI=true에서는 멈췄다. 지금 그 검사를 시험하는 테스트는 `build-environment.test.ts:22-55`와 `local-build-environment.test.ts:37-41`이고, 위 (a)의 실행이 실제 경로를 보였다 |
|
||||
|
||||
남는 작은 위험이 하나 있다. spawn 지점을 다시 `process.env`로 되돌리면 그것을 잡는 것은 CI=true로 도는 merge 게이트뿐이다. 개발자가 CI env 없이 돌리면 통과한다. README가 workflow env로 돌리라고 적었다(`README.md:340-352`). 발견으로 세지 않는다.
|
||||
|
||||
## 3. 이번 발견 (36.3)
|
||||
|
||||
새 발견은 2건이다. Medium 2. P1 1, P2 1. 확인된 결함 1, 구조적 위험 1. High 이상은 없다.
|
||||
|
||||
### 13-01 `immutable_build`가 FE-GATE-015·027의 gate 로그와 기록을 올리지 않아, release 단계의 실패 이유와 advisory 경고가 실제 workflow에서 사라진다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| ID·제목 | 13-01(라운드 밖: `1105/13-01`) — 위 제목 |
|
||||
| 성격 | 확인된 결함. 지난 라운드 전부터 있던 구성이다. 보고된 적은 없다. 1103/13-03 수정이 이 구성 위에 신호를 두면서 영향이 커졌다 |
|
||||
| 관련 관점 | 8, 5, 7, 16, 18 |
|
||||
| 근거 | **로그 경로.** `ci:gate`는 각 명령의 stdout·stderr를 모아(`scripts/run-ci-gate.ts:148-150`) 로그 파일 `artifacts/quality/gates/<gate>.txt`에만 쓴다(`:209-213`). 콘솔에는 한 줄만 쓴다: `FE-GATE-NNN name: PASS (…)` 또는 `FAIL`(`:243-249`). **실측(13-R01, CI env).** FE-GATE-027 콘솔은 2줄이었다: `$ node … run-ci-gate.ts FE-GATE-027`, `FE-GATE-027 release-admission: PASS (release-coherence)`. 같은 실행의 로그 파일에는 줄이 더 있었다: `Dependency advisories: POLICY_VIOLATION (production: … high 2 …)`(8행), `WARNING: the vulnerability policy (block at high) would refuse this lockfile at production promotion:`(11행), 해당 advisory 2줄(12·13행). FE-GATE-015를 커밋 ID 없이 돌렸을 때도 같았다. 콘솔은 `FE-GATE-015 release-coherence: FAIL` 한 줄이었다. 이유 `missing required CI build environment: VITE_COMMIT_SHA`는 로그 파일에만 있었다. **올리는 곳.** `merge_gate`·`release_gate`는 `artifacts/`를 `if: always()`로 올린다(`.gitea/workflows/quality-gates.yml:75-80`, `:114-119`). `immutable_build`의 단계는 checkout → setup-node → install → `ci:gate FE-GATE-015` → `ci:gate FE-GATE-027` → archive → 후보 upload다(`:122-207`). 계약도 이 단계 목록을 고정한다(`scripts/contracts/ci-gates.ts:947`). archive 멤버에 `artifacts/quality/gates/*`와 `artifacts/security/dependency-advisories.json`은 없다(`:150-200`). **주장과 차이.** 커밋 `26ca2fdb` 본문은 "gate 로그가 이미 release 단계 산출물이다"라고 적었다. 문서는 결과가 "gate log와 `artifacts/security/dependency-advisories.json`에 남는다"고 적는다(`docs/operations/ci-quality-gates.md:479-487`). 둘 다 업로드되지 않는다 |
|
||||
| 발생 조건 | release 단계를 돌 때마다 생긴다(tag push 또는 dispatch `stage=release` 이상). advisory 경고는 항상 사라진다. 실패 이유는 FE-GATE-015(후보 빌드·로컬 증거)나 FE-GATE-027(공개 대상 승인)이 실패할 때 사라진다 |
|
||||
| 영향 | 운영자는 "FE-GATE-027 release-admission: FAIL"만 본다. 거절 이유(`release admission refused: …`, `scripts/check-release-admission.ts:39-42`)는 보이지 않는다. 원인을 알려면 같은 커밋을 손으로 다시 돌려야 한다. advisory 경고는 아무도 보지 못한다. 1103/13-03(P1)을 고치려던 신호가 실제 workflow에서는 효과가 없다. provider를 붙인 프로젝트는 지난 라운드처럼 첫 승격에서야 안다 |
|
||||
| 심각도·우선순위 | Medium · P1. 주요 진단 정보가 빠진 경우다(35.2의 Medium 예). 사용자 피해는 없다. P1로 둔 이유는 둘이다. 지난 라운드 P1(1103/13-03)의 수정이 이것 때문에 실제로 작동하지 않는다. 사용자 로드맵의 CD 경로(release → 승격 → 배포 슬롯)에서 첫 실패를 진단할 수 없다. 고치는 비용은 단계 하나다 |
|
||||
| 통제·증거 | 로그 생성 M2 / release job 로그 보존 M0 · E3(13-R01: 같은 `ci:gate`의 콘솔과 로그 파일 비교) + E1(workflow 단계 목록) |
|
||||
| 확실성과 남은 가정 | Gitea act_runner는 job 콘솔만 남기고 작업 디렉터리를 job 뒤에 지운다고 본다. 일반 동작이고 실제 runner에서 확인하지는 않았다. 작업 디렉터리를 남기는 runner 구성이면 파일이 남을 수 있다. 그래도 다음 job이 덮어쓴다 |
|
||||
| 결정의 근거 | 확인한 사실: 다른 gate job은 모두 `artifacts/` upload 단계가 있다. `immutable_build`만 없다. 기록된 의도: `immutable_build`는 "정확한 후보 파일 집합"만 내보낸다(`:149` 단계 이름 `Archive and validate the exact candidate file set`). 리뷰어 추론: 후보 archive를 정확한 집합으로 두려는 의도와 gate 로그를 따로 올리는 일은 충돌하지 않는다. 이름이 다른 upload라면 후보 집합은 그대로다 |
|
||||
| 이해 비용 | release 단계 실패를 조사하는 사람은 "로그는 `artifacts/quality/gates/`에 있다"는 문서를 보고 찾는다. 그 job의 산출물에는 없다 |
|
||||
| 최소 개선 방향 | `immutable_build`에 `if: always()` upload 단계를 더한다. 대상은 `artifacts/quality/gates/FE-GATE-015.txt`, `FE-GATE-027.txt`, `artifacts/release/deployment-admission.json`, `artifacts/security/dependency-advisories.json`이다. 계약의 단계 목록(`ci-gates.ts:947`)과 전송 ID를 함께 고친다. 예: `immutable-gate-evidence`. 후보 archive 멤버는 바꾸지 않는다. 덧붙여 advisory `POLICY_VIOLATION` 한 줄을 `ci:gate` 콘솔에도 내보낸다 |
|
||||
| 대안 비교 | (a) 현상 유지 — 13-03 신호가 계속 보이지 않는다. (b) upload 단계만 더한다 — 가장 작다. 사람이 산출물을 열어야 본다. (c) `ci:gate`가 실패한 명령의 마지막 N줄을 콘솔에도 쓴다 — 모든 job의 진단이 나아진다. 대신 로그 크기 상한과 secret 노출(`run-ci-gate.ts`는 provider 출력도 다룬다)을 다시 따져야 한다. (d) (b)에 advisory 한 줄을 콘솔에 더한다. 리뷰어 추천은 (d) |
|
||||
| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다. 후보 archive 멤버 집합과 `verify-ci-candidate-archive.ts` 검사는 그대로 둔다 |
|
||||
| 비용·부작용 | workflow 단계 하나, 계약 단계 목록 한 줄, `ci-workflow-generation` 테스트 갱신, 계약 기준선 재기록 |
|
||||
| 재검토 조건 | `ci:gate`가 콘솔 요약을 쓰게 바뀌거나, release job이 후보 archive와 같은 upload에 증거를 싣게 되면 다시 본다 |
|
||||
| 완료 기준 | release 단계 run의 산출물에 FE-GATE-015·027 로그와 advisory 기록이 있다. FE-GATE-027이 실패한 run에서 그 산출물로 거절 이유를 읽을 수 있다 |
|
||||
| 검증 방법 | `ci-workflow-generation.test.ts`에 "`immutable_build`는 gate 로그를 always upload한다"를 더한다. 실제 runner에서 `stage=release`를 1회 돌린다 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
| 재검증 결과 | 해당 없음(신규) |
|
||||
|
||||
### 13-02 제품 merge 검사(`PRODUCT-GATE-*`)가 실패해도 같은 run의 release·승격·배포가 진행되고, 제품이 그것을 막을 방법이 계약에 없다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| ID·제목 | 13-02(`1105/13-02`) — 위 제목 |
|
||||
| 성격 | 구조적 위험. job 그래프는 코드로 확인했다. 실제 피해는 제품이 넣는 검사에 달려 있다 |
|
||||
| 관련 관점 | 18, 21, 26, 3, 24 |
|
||||
| 근거 | 제품 overlay의 `mergeGates`는 `product_merge_gate` job으로 렌더링된다. 이 job에는 `needs`가 없다. 다른 job도 이 job을 기다리지 않는다(`scripts/generate-ci-workflow.ts:129-157`). job 그래프는 계약이 고정한다. `release_gate`는 `merge_gate`만 기다린다. `immutable_build`는 `release_gate`만, `deployment`는 `immutable_build`·`promotion`만 기다린다(`scripts/contracts/ci-gates.ts:926-933`). 생성 workflow도 같다(`.gitea/workflows/quality-gates.yml:85`, `:124`, `:375`). 문서는 "Make that job a required check of the branch where it has to block a merge"라고만 적는다(`docs/operations/ci-quality-gates.md:377-378`). 브랜치 필수 검사는 PR merge를 막는다. dispatch run의 release·배포는 막지 않는다. 문서가 드는 예가 짝 백엔드 계약 검사다(`:371-372`). 커밋 `4c4248aa` 본문도 "제품 gate는 … readiness 공식 밖이다"라고 적는다 |
|
||||
| 발생 조건 | 세 조건이 겹칠 때 생긴다. 제품이 `mergeGates`와 `deployment`를 둘 다 채운다. 제품 검사가 실패한다. 그 커밋으로 `workflow_dispatch stage=production`을 돌린다(tag push라면 release까지 간다). 템플릿 자신은 `mergeGates: []`라 해당하지 않는다(`config/ci/product-gates.json`) |
|
||||
| 영향 | 제품 검사가 지키려던 것(예: 짝 백엔드 계약 일치)이 깨진 release가 운영 호스트에 올라간다. FE-GATE-019는 호스팅만 본다. 그래서 PASS한다. 사용자는 API 응답 해석 오류를 볼 수 있다(검사 종류에 따라 다르다). 템플릿 merge 게이트가 실패하면 release가 멈춘다. 제품 검사는 그렇지 않다. 이 비대칭 때문에 제품 개발자가 같은 보호를 기대하기 쉽다 |
|
||||
| 심각도·우선순위 | Medium · P2. 지원 구성(제품 overlay)에서 배포 차단이 빠진다. 다만 제품이 두 칸을 채우고 빨간 run을 직접 dispatch해야 생긴다. 템플릿 자체에는 피해가 없다. 고치는 비용은 작다 |
|
||||
| 통제·증거 | 템플릿 merge 게이트 → release 차단 M4(job 그래프) / 제품 merge 게이트 → release 차단 M0 · E1 |
|
||||
| 확실성과 남은 가정 | Gitea가 `needs`를 GitHub Actions처럼 처리한다고 본다(실제 runner 미확인). 이 항목은 영역 12(1103/12-07 수정 `4c4248aa`)와 겹칠 수 있다. 같은 결함이면 오케스트레이터가 한 항목으로 합친다 |
|
||||
| 결정의 근거 | 확인한 사실: overlay는 템플릿 gate ID·readiness를 건드리지 못하도록 따로 둔 job이다(`product-ci-overlay.ts:16-21`). 기록된 의도: 제품 gate를 계약 기준선과 readiness 밖에 둬 템플릿 동기화 충돌을 없앤다. 리뷰어 추론: readiness 밖에 두는 것과 release job이 그 결과를 기다리는 것은 별개다. `needs` 한 줄은 계약 기준선(gate 수·명령 수)을 바꾸지 않는다 |
|
||||
| 이해 비용 | 제품 개발자는 "merge 검사"라는 이름을 보고 release도 막힌다고 가정한다. 막히지 않는다는 사실은 job 그래프를 읽어야 안다 |
|
||||
| 최소 개선 방향 | `mergeGates`가 비어 있지 않으면 `release_gate`(또는 `immutable_build`)의 `needs`에 `product_merge_gate`를 더해 렌더링한다. overlay가 있을 때만 계약 그래프 검사(`ci-gates.ts:926-933`)가 그 연결 하나를 허용한다. 문서에 "제품 merge 검사가 실패하면 release 단계는 돌지 않는다"를 적는다 |
|
||||
| 대안 비교 | (a) 현상 유지하고 문서에 "release를 막지 않는다"고 적는다 — 가장 싸다. 그래도 그래프가 고정이라 제품이 스스로 막을 방법이 없다. (b) `needs` 연결을 더한다 — 템플릿 게이트와 같은 보호다. 제품 gate가 불안정하면 release도 멈춘다. (c) overlay의 gate마다 `blocksRelease: true\|false`를 둔다 — 선택권을 주지만 칸이 하나 는다. 리뷰어 추천은 (b)다. 불안정한 검사가 생기면 (c)로 간다 |
|
||||
| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다. `mergeGates`가 비어 있을 때 생성 workflow 바이트는 지금과 같아야 한다 |
|
||||
| 비용·부작용 | 생성기 분기 하나, 계약 그래프 검사의 예외 하나, `product-ci-overlay.test.ts` 케이스 하나 |
|
||||
| 재검토 조건 | 제품 gate를 readiness 공식에 넣는 방식으로 바꾸면 그쪽에서 다시 본다 |
|
||||
| 완료 기준 | overlay에 gate 하나를 넣고 생성하면 release 쪽 job이 `product_merge_gate`를 기다린다. overlay를 비우면 workflow 바이트가 지금과 같다 |
|
||||
| 검증 방법 | `product-ci-overlay.test.ts`에 "mergeGates가 있으면 release_gate가 product_merge_gate를 기다린다"를 더한다 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
| 재검증 결과 | 해당 없음(신규) |
|
||||
|
||||
## 4. 28개 관점 판정 (36.2)
|
||||
|
||||
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역. **굵은 번호**는 이 영역이 깊게 본 관점이다.
|
||||
|
||||
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | 코드 성숙도 | > 영역 09·12 | — | — | > — 빌드 단계 주석이 실제 순서와 맞다(`build-frontend.ts:10-39`) |
|
||||
| 2 | 구조적 성숙도 | > 영역 12 | — | — | > |
|
||||
| 3 | 변경 용이성 | 적용 | 목표 M2 / 확인 M2 | E1·E2 | P — 제품이 템플릿 파일을 고치지 않고 배포 job을 채운다(`product-ci-overlay.ts`). 제품 검사로 release를 막을 수는 없다(13-02) |
|
||||
| 4 | 인지 부하 | 적용 | M1 | E1 | P — FE-GATE-019가 보는 것(이름·config·entry·ALPN·압축·Content-Type)이 문서 한 절에 모였다(`release-cache-rollback.md:82-104`). release job 실패 원인을 어디서 보는지는 알기 어렵다(13-01) |
|
||||
| 5 | 위험 가시성 | 적용 | M3 / 일부 M0 | E3 | P — 빈 슬롯은 `UNVERIFIED`가 되고 advisory `POLICY_VIOLATION` 판정이 생겼다. 그 판정이 실제 workflow 콘솔과 산출물에 없다(13-01, 13-R01) |
|
||||
| 6 | 실패 성숙도 | 적용 | M3 | E3 | O — 빌드 단계가 실패하면 즉시 멈추고 승인은 fail-closed다. CI 식별값 누락·형식 오류 14가지가 모두 실패한다(13-R01) |
|
||||
| 7 | 운영 성숙도 | 적용(일부) | M1 | E1·E3 | P — 비상 스위치 절차와 probe가 같은 규칙을 쓰고, 스위치만 바꾼 호스트는 PASS한다(13-R02 P3). provider 없는 배포 경로가 없고 desktop에서 provider sandbox가 뜨지 않는다(1101/13-03). release 실패를 진단할 수 없다(13-01) |
|
||||
| **8** | 디버깅 가능성 | 적용 | M2 / release job M0 | E3 | P — probe 실패는 표면·헤더·기대·관측으로 남는다(13-R02 출력). release job은 그 로그를 올리지 않는다(13-01). TLS·전송 실패는 `error.name`(`"Error"`, `"TypeError"`)만 남아 원인 코드가 없다(`hosting-probe.ts:165`, `:239`) |
|
||||
| 9 | 유지보수 성숙도 | 적용 | M2 | E1 | P — `rolldownOptions` 이전이 끝났다(0929/13-07). CSP 6벌(0929/13-04)과 기본값 4곳(R-2)이 남았다 |
|
||||
| 10 | 테스트 성숙도 | 적용 | M3 | E3 | P — 이 영역 수정의 규칙 6개를 하나씩 끄면 모두 단위 테스트가 실패한다(13-R07~R12). 11-08 수정 되돌림도 잡는다(R05·R06, R05는 CI env에서만). 실제 TLS·nginx를 쓰는 자동 테스트는 없다(13-R02는 일회성 실험이다). 제품 overlay 경로의 secret 위치는 따로 단언하지 않는다 |
|
||||
| 11 | 데이터 성숙도 | > 저장소 영역 | — | — | > |
|
||||
| 12 | 동시성 성숙도 | > 탭·저장소 영역 | — | — | > |
|
||||
| 13 | 확장성 | > 영역 11·15 | — | — | > |
|
||||
| 14 | 성능 성숙도 | 적용 | 예산 M3 / 서빙 전제 M3 | E3 | P(지난 P) — h2와 압축을 probe가 실제 nginx에서 확인한다(13-R02). 초기 JS는 202,973 / 204,800 B, 26 / 32파일(FE-GATE-012)이다. 선언을 HTTP/1.1로 바꿀 때 청크를 묶었는지는 문서로만 지킨다(M1). 파일 상한 32는 영역 15 |
|
||||
| **15** | 보안 성숙도 | 적용 | M3 / 일부 M0 | E3 | P — 승인받지 않은 `config.json`을 내주면 FE-GATE-019가 FAIL한다(13-R02 P2). 슬롯 secret은 deploy 단계에만 간다(13-R11). 운영 high advisory 2건은 결정 대기다(1103/13-03) |
|
||||
| **16** | 의존성 성숙도 | 적용 | 판정 M3(승격) / 신호 M2 / 갱신 M1 | E3 | P — advisory가 44건에서 4건으로 줄었다(13-R01). release 단계에서 advisory를 판정하고 pnpm 정책을 테스트한다(0929/13-08). 남은 것: 운영 2건, runner 안에 갇힌 신호(13-01), 동작하지 않는 renovate, SBOM `scheduler` 분류(0929/13-05) |
|
||||
| 17 | API / Contract 성숙도 | 적용(설정 계약) | M3 | E3 | O — FE-REG-ENV 행과 스키마를 양방향으로 대조한다(1103/13-04, 13-R12) |
|
||||
| **18** | 배포 성숙도 | 적용 | M3 / 일부 M0 | E3 | P(지난 P) — 슬롯은 후보만 받고, probe는 실제 호스트에서 후보 내용과 전송 전제를 본다(13-R02). 남은 것: 제품 검사가 배포를 막지 않는다(13-02), release 실패를 진단할 수 없다(13-01), provider 없이 슬롯에 갈 수 없다(1101/13-03), 하위 경로 배포는 PASS할 수 없다(0929/13-06) |
|
||||
| **19** | 설정 성숙도 | 적용 | M3 | E3 | P — 호스트 `config.json`과 레지스트리 값을 대조한다. `.env*` 입력 갈림(0929/13-02)과 기본값 갈림(R-2)은 남았다 |
|
||||
| 20 | 개발자 경험 | 적용 | M1 | E3 | P — nginx 예시를 그대로 쓰면 FE-GATE-019를 통과한다(13-R02 P1, 55개 항목). README가 workflow env로 merge 게이트를 돌리는 법을 적는다(`README.md:340-352`) |
|
||||
| **21** | Guardrail 성숙도 | 적용 | M3·M4 | E3 | P — release job env와 workflow 바이트를 merge 게이트가 막는다(13-R03·R04). 제품 gate에서 release로 가는 연결은 없다(13-02) |
|
||||
| 22 | 추상화 성숙도 | > 영역 09·12 | — | — | > |
|
||||
| 23 | 일관성 | 적용 | M1 | E1 | P — 승인과 probe가 같은 비상 스위치 규칙을 쓴다. 빌드 변수 출처(0929/13-02)와 기본값(R-2) 갈림이 남았다 |
|
||||
| 24 | 네이밍 / 의미 성숙도 | 적용 | M1 | E1 | P — `product_merge_gate`와 "merge 검사"라는 이름이 release 보호까지 뜻하는 것처럼 읽힌다(13-02) |
|
||||
| 25 | 조직 확장성 | - 1인 관리 전제 | — | — | - |
|
||||
| **26** | Ownership 성숙도 | 적용 | M1 | E1 | P — advisory 2건의 결정 조건과 재확인 날짜가 적혀 있다(`ci-quality-gates.md:499-508`). 그 결정을 내릴 reviewer(owner와 다른 사람)가 1인 운영에는 없다. 선택 기능 결함 분류(0929/13-10)는 남았다 |
|
||||
| 27 | 삭제 가능성 | > 영역 14 | — | — | > |
|
||||
| 28 | 회복 가능성 | 적용 | M2 | E3 | P — 비상 스위치만 바꾼 호스트는 probe를 통과한다(13-R02 P3). 슬롯 배포 뒤 FE-GATE-019가 실패해도 자동으로 되돌리지 않는다(문서상 프로젝트 몫) |
|
||||
|
||||
## 5. 미검증
|
||||
|
||||
| 항목 | 이유 | 확인하려면 |
|
||||
|---|---|---|
|
||||
| 실제 Gitea runner: `immutable_build` 콘솔과 작업 디렉터리 정리, `needs` 처리, 채운 슬롯 | runner 없음 | `stage=release`·`production` dispatch 1회 |
|
||||
| desktop에 runner를 붙였을 때 provider job이 같은 sandbox 오류로 막히는가 | runner 미실행. 같은 오류는 test:system에서만 봤다 | host-mode runner에서 provider job 1회 |
|
||||
| 실제 운영 호스트(공인 인증서, CDN·프록시 뒤)에서 ALPN·압축 판정 | 실험은 LAN IP와 일회용 CA로 했다 | 운영 호스트로 FE-GATE-019 1회 |
|
||||
| `zod`·`react-router` advisory가 이 앱에서 실제로 닿는가 | 코드 경로를 끝까지 따라가지 않았다(지난 라운드와 같은 추정) | advisory 조건과 사용 지점 대조 |
|
||||
| `.env*` 입력 갈림(0929/13-02) 재현 | 정적 확인만 | `.env.production.local`에 `VITE_BUILD_ID`만 두고 빌드 |
|
||||
| `pnpm-install-policy` 변이 검출(0929/13-08) | 요청하지 않았다(작은 정적 테스트) | `pnpm-workspace.yaml`에서 `saveExact`를 지우고 테스트 |
|
||||
|
||||
## 6. 실행 기록
|
||||
|
||||
이 영역이 직접 실행한 것은 없다. 배치는 오케스트레이터가 desktop checkout에서 돌렸다. 매 항목 앞뒤로 `8a44226`으로 되돌렸고 12개 모두 `restore=clean`이다. 마지막 상태는 `status=empty branch=fix/maturity-review-2026-11-03 head=8a44226`이었다. 잠금 대기는 배치라 따로 없다.
|
||||
|
||||
| 이름 | 명령 · env | 변이 | rc | 결과 | 부하 |
|
||||
|---|---|---|---|---|---|
|
||||
| (취소) 13-ciid, 13-probe-live, 13-mut, 13-localtests | `exp.sh …` | 스크립트 안 | — / 93 | 1차는 잠금 대기 중 취소됐다(19:48). 2차는 `CLOSED`였다. 잠금을 잡지 못해 checkout을 건드리지 않았다 | 3~7 |
|
||||
| 13-R01 | `bash /tmp/claude-gates/r4/mut/13-ciid-run.sh` · CIENV | - | 0(스크립트), 14초 | 대조군 빌드 rc=0. FE-GATE-027 콘솔 2줄, 로그에 `POLICY_VIOLATION`과 경고 4줄. 음성 실행 14개 모두 rc=1이고 이유가 기대와 같다(2.3절 (a)) | 2.46 |
|
||||
| 13-R02 | `bash /tmp/claude-gates/r4/mut/13-probe-run.sh` · local | - | 0(스크립트), 12초 | nginx 1.27.5(docker `nginx:1.27-alpine`), TLS `IP:192.168.0.107`. 후보 빌드 rc=0, production ADMITTED. P1 PASS(55개), P2 FAIL `runtimeConfig build-fields`, P3 PASS, P4 FAIL `transport alpn`(`http/1.1`), P5 FAIL `hashedAsset content-encoding`, P6 PASS. 컨테이너는 지웠다 | 3.49 |
|
||||
| 13-R03 | `corepack pnpm -s check:ci` · local | `13-b1-ci-binding-immutable-build.diff` | 1, 2초 | `root: job environment binding drift: immutable_build`(빈 값이라 `value: Too small`도 함께 나왔다). 대조군 `gates/check_ci.log` rc=0 | 3.11 |
|
||||
| 13-R04 | 같음 · local | `13-b2-hand-edit-workflow.diff` | 1, 1초 | `CI contract failed: generated workflow drift at byte 5473, line 134` | 2.94 |
|
||||
| 13-R05 | `node scripts/run-vitest.ts run tests/unit/service-worker-build-output.test.ts` · CIENV | `13-c1-spawn-sites-process-env.diff` | 1, 3초 | `scripts/build-frontend.ts failed for sw-profile-active` / `missing required CI build environment: VITE_COMMIT_SHA`. 7건 미실행. 대조군 merge-48 FE-GATE-005 rc=0 | 2.94 |
|
||||
| 13-R06 | `node scripts/run-vitest.ts run tests/unit/local-build-environment.test.ts` · local | `13-c2-local-env-keeps-ci.diff` | 1, 1초 | "is not checked as a CI build, whatever CI identity the job has" 실패(누락 5건). 다른 2건 통과 | 2.94 |
|
||||
| 13-R07 | `node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts` · local | `13-m1-config-compare-off.diff` | 1, 1초 | 2 failed / 37: "…config.json is not the candidate's", "…is unreadable" | 2.78 |
|
||||
| 13-R08 | 같음 | `13-m3-alpn-off.diff` | 1, 1초 | 1 failed / 37: "fails a host that does not negotiate a declared protocol" | 2.78 |
|
||||
| 13-R09 | 같음 | `13-m4-encoding-off.diff` | 1, 1초 | 1 failed / 37: "fails a hashed asset served without a declared content encoding" | 2.78 |
|
||||
| 13-R10 | `node scripts/run-vitest.ts run tests/unit/ci-workflow-generation.test.ts tests/unit/product-ci-overlay.test.ts` · local | `13-m5-slot-input-rule-off.diff` | 1, 4초 | 2 failed / 437: "rejects a slot that deploys without the promoted candidate", "rejects a slot that extracts the candidate without its digest". `product-ci-overlay`는 통과 | 2.78 |
|
||||
| 13-R11 | 같음 | `13-m6-secret-step-scope-off.diff` | 1, 3초 | 1 failed / 437: "accepts a deployment job the slot allows"(`not to contain 'secrets.'`). `product-ci-overlay`는 통과 | 2.64 |
|
||||
| 13-R12 | `node scripts/run-vitest.ts run tests/unit/env-registry-coverage.test.ts` · local | `13-m7-env-row-drift.diff` | 1, 1초 | 1 failed / 4: `AUTH_MODE: row {…"external"}, schema {…null}` | 2.91 |
|
||||
|
||||
요청·패치·결과 파일은 `scratchpad/r4/requests/13.md`, `scratchpad/r4/13/patches/`, `scratchpad/r4/results/13/`에 있다. 변이 9개(R03~R12)는 모두 대조군이 통과하고 변이 실행이 기대한 이유로 실패했다.
|
||||
|
||||
## 7. 새 발견 요약
|
||||
|
||||
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|
||||
|---|---|---|---|---|
|
||||
| 13-01 | Medium·P1 | 확인된 결함 | `immutable_build`가 FE-GATE-015·027의 gate 로그와 advisory 기록을 올리지 않는다. 그래서 release 실패 이유와 13-03 신호가 실제 workflow에서 사라진다 | `.gitea/workflows/quality-gates.yml:122-207`, `scripts/run-ci-gate.ts:148-150`, `:209-213`, `:243-249`, `scripts/contracts/ci-gates.ts:947` |
|
||||
| 13-02 | Medium·P2 | 구조적 위험 | 제품 merge 검사가 실패해도 같은 run의 release·승격·배포가 진행된다. job 그래프가 고정이라 제품이 막을 수도 없다 | `scripts/generate-ci-workflow.ts:129-157`, `scripts/contracts/ci-gates.ts:926-933`, `docs/operations/ci-quality-gates.md:377-378` |
|
||||
@@ -0,0 +1,252 @@
|
||||
# 영역 14 — 템플릿 제품성·문서·DX·업데이트 전파
|
||||
|
||||
> 검토일 2026-11-05 · 기준 `8a44226` (브랜치 `fix/maturity-review-2026-11-03`) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
|
||||
>
|
||||
> 경로: `README.md`, `CHANGELOG.md`, `PRODUCT.md`, `docs/`(특히 `docs/manual/`, `docs/architecture/`, `docs/testing/`), `recipes/`의 문서 주장, `scripts/test-sample-removal.ts`, `scripts/lib/removal-fixture.ts`, 루트 추적 파일. `docs/reviews/`는 이력이라 판정하지 않았다. 2026-11-03 README §13·§14는 코드와 대조할 주장으로만 읽었다.
|
||||
>
|
||||
> 깊게 본 관점: 9 유지보수, 17 API/Contract, 20 개발자 경험, 26 Ownership, 27 삭제 가능성, 30절 전체
|
||||
>
|
||||
> 렌즈: ① 결정 D5(동기화 단위 순 요약)대로 `CHANGELOG.md` 미출시 절이 `e40684b..8a44226`과 맞는가. ② BREAKING 이행 안내가 두 다운스트림(tech-log `7a4e201a`, memento `d3810a0`)의 실제 모양과 맞는가. ③ 수정으로 새로 쓴 매뉴얼(01~04, reference)의 명령·경로·파일 이름·게이트 주장이 `8a44226`에서 참인가. ④ 이 영역의 수정이 검사를 약하게 만들지 않았는가.
|
||||
>
|
||||
> 영역 판정(35.8): **새 프로젝트를 복사해 시작하는 용도는 조건부 사용 가능**(04 문서 예시 하나를 고쳐 쓴다, 14-02). **이 미출시 묶음을 다운스트림에 전파하는 용도는 조건부 사용 가능**으로 올렸다. 지난 라운드의 막는 항목 둘(1103/14-01, 14-02)은 해시·[계약] 행·memento-web 숫자까지 맞게 고쳐졌다. 남은 조건은 셋이다. 예제 기능을 지운 제품은 문서 검사가 실패한다(14-01). "옮기기 전" 2단계의 템플릿 파일 목록이 두 제품이 실제로 고친 파일의 일부다(1103/14-02 잔여). 초기 파일 상한 숫자가 절 안에서 둘이다(1103/14-01 잔여).
|
||||
>
|
||||
> ID 표기: 이 문서의 새 발견은 `14-01`부터다. 라운드 밖에서는 `1105/14-NN`이다. 지난 라운드는 `1103/14-NN`, 그 전은 `1101/14-NN`, `0929/14-NN`이다.
|
||||
|
||||
## 0. 결론
|
||||
|
||||
핵심은 둘이다. 지난 라운드에 "전파 보류"였던 CHANGELOG는 이제 범위와 맞는다. 새로 생긴 결함은 모두 서로 다른 브랜치에서 온 수정이 문서에서 만나지 못한 곳이다.
|
||||
|
||||
```text
|
||||
CHANGELOG 미출시 절 (752a61f → 8a44226, 비병합 348커밋)
|
||||
해시 148개 모두 범위 안 / 지난번 빠진 8커밋 모두 행 있음 / ! 커밋 13개 모두 BREAKING 행
|
||||
: 초기 파일 상한이 :107·:216은 26, :249와 budgets.json은 32 (1103/14-01 잔여)
|
||||
: 알려진 제한은 f887817 기준, FE-GATE-017을 merge 게이트로 적음 (1103/14-01 잔여)
|
||||
|
||||
BREAKING 이행 안내
|
||||
memento-web 숫자(descriptor 29, schemaId 42+1, isRecord)는 실제와 같다 (1103/14-02 일부 고쳐짐)
|
||||
: "옮기기 전 2" 목록 = memento 고친 템플릿 src 26개 중 7개, tech-log 38개 중 11개 (1103/14-02 잔여)
|
||||
: CHANGELOG 6단계대로 예제 기능을 지우면 문서 검사가 실패한다 (14-01, 새)
|
||||
|
||||
매뉴얼
|
||||
01·02·03·reference의 오류 문구 70여 개를 코드와 대조: 모두 있다
|
||||
: 04 §3.2 설정 키 예시를 그대로 옮기면 check:types·test:unit 실패 (14-02, 새)
|
||||
: 참조 기능 경로 26줄이 백틱에서 빠져 문서 검사 밖으로 나갔다 (14-03, 새, 검사 약화)
|
||||
```
|
||||
|
||||
- 새 발견 3건: Medium 1(14-01), Low 2(14-02, 14-03). High·P1은 없다.
|
||||
- 지난 라운드 영역 14 발견 6건 중 4건 고쳐짐(14-03, 14-04, 14-05, 14-06), 2건 일부(14-01, 14-02). 합친 04-05와 03-06(VD-23 부분)은 고쳐짐.
|
||||
- 이월 항목 7건은 여전히 열려 있다(일부 4, 남음 3). 0929/14-01은 실행 로그 63개가 추적에서 빠져 일부로 바뀌었다.
|
||||
- 지난 라운드 1103/14-04는 결함 판단은 맞았지만 게이트 이름이 틀렸다. FE-GATE-017은 merge 게이트가 아니다(`config/ci/gates.json:2298` documentation 단계, `.gitea/workflows/quality-gates.yml:466` 수동 실행). merge에서 같은 검사를 하는 것은 FE-GATE-005의 `tests/unit/documentation-readiness.test.ts:58`이다.
|
||||
|
||||
지금 이해하면 되는 것:
|
||||
|
||||
1. 이 미출시 묶음은 다운스트림에 옮겨도 된다. 다만 tech-log는 예제 기능 폴더를 지우기 전에 14-01을 먼저 고쳐야 merge 게이트가 통과한다.
|
||||
2. "옮기기 전" 2단계 목록에 없는 파일(memento의 HTTP 실행기 `if-match` 수정, tech-log의 `AppFailure.detail` 등)은 동기화 때 충돌이나 조용한 유지로 남는다. 제품 소유 자리가 없는 것도 있다.
|
||||
3. 매뉴얼 04 §3.2 예시는 `defaultValue: null`을 더해 쓴다.
|
||||
|
||||
## 1. 범위 (36.1)
|
||||
|
||||
| 항목 | 기록 |
|
||||
|---|---|
|
||||
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`. 읽기만 한 저장소: `clean-architecture-backend-template`(`45d2a478`, pin과 같음), `tech-log-frontend`(`7a4e201a`), `memento-frontend`(`d3810a0`). 두 다운스트림 HEAD는 지난 라운드와 같다 |
|
||||
| 커밋·작업 상태·확인 시점 | `8a44226`, 노트북 worktree(읽기만), desktop checkout(실험만, helper가 실행 뒤 되돌림), 2026-11-05 |
|
||||
| 목적과 지원 실행 구성 | 복사해서 시작하고 Git으로 원본 수정을 받아 가는 프론트엔드 템플릿. 짝 백엔드 템플릿과 함께 쓴다. 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음 |
|
||||
| 필수 요구와 규모·운영 목표 | 두 템플릿으로 서비스를 빨리 출시한다. 두 다운스트림이 이 템플릿을 복사해 쓰고 범위 단위로 동기화한다(memento merge, tech-log 3-way). 문서 규모 목표는 없다 |
|
||||
| 지난 리뷰 뒤 바뀐 것 | `e40684b..8a44226` 비병합 172커밋, 병합 12커밋. 이 영역 경로를 고친 커밋 109개. 문서 195개 93,445줄(지난 177개 86,108줄), 그중 `docs/reviews/` 37,162줄. 매뉴얼 2,206줄(지난 1,620줄). 새 문서 `docs/manual/04-paired-backend-session.md`(298줄), 새 recipe `recipes/session-owners/` 2개 |
|
||||
| 읽은 코드·구성 범위 | `CHANGELOG.md` 미출시 절 전체(`:14-276`), `README.md` 업데이트·CI·지울 파일 절, `PRODUCT.md`, `docs/README.md`, `docs/manual/` 전체, `starter-experience.md` 기능 추가·예제 절, VD-23 머리·배경, `api-contract-schema-mapper-and-server-state.md`·`backend-api-and-server-state-contract.md`의 상태 표와 6·6.1절. `scripts/verify-documentation-readiness.ts` 150~345행, `scripts/test-sample-removal.ts` 30~135·200~220·410~500행, `scripts/lib/removal-fixture.ts` 46~85행, `scripts/check-registries.ts`(84d6e52 diff), `src/contracts/env.ts`, `src/contracts/product-contracts.ts`, `tests/unit/env-registry-coverage.test.ts`, `tests/unit/documentation-readiness.test.ts` 1~60행, `config/ci/gates.json` 단계, `config/performance/budgets.json`. 두 다운스트림은 `git diff af3d8e6 HEAD`(읽기)와 memento-web 계약 파일 |
|
||||
| 수행한 테스트·실험 | 정적: CHANGELOG 해시 위치·인용 대조(E-1, E-2), 매뉴얼 오류 문구 대조(E-3), 두 다운스트림 파일 목록(E-4), memento-web 모양 집계(E-5), 백틱 밖 경로 존재 확인(E-6). desktop 개별 실행 `14-docs`·`14-examples-drill`은 대기 중 취소돼 돌지 않았다(BRIEF-2). 배치 요청 14-R1·14-R3·14-R4·14-R5(`scratchpad/r4/requests/14.md`). 오케스트레이터 결과: `merge-48/FE-GATE-020`(CI env) |
|
||||
| 게이트 결과(오케스트레이터, 같은 커밋) | `desktop:/tmp/claude-gates/r4/merge-48/summary.txt`: FE-GATE-020 rc=0 1,156초(CI env). 그 안의 `sample-removal.xml`은 31건 모두 통과이고 `documentation`·`lint`·`i18n`·`design-system`·`scaffold-documentation`이 들어 있다. `gates/summary.txt`(local env): `check:architecture`·`check:types`·`lint`·`test:unit`·`test:component`·`test:integration` rc=0. `test:unit`은 2,883건 통과이고 `documentation-readiness.test.ts` 19건, `registry-governance.test.ts` 11건, `env-registry-coverage.test.ts` 4건을 포함한다(`gates/test_unit.log`). `verify:documentation`은 로컬 rc=1이다. 실패 줄은 모두 짝 백엔드 경로이고 그때 백엔드 checkout이 pin이 아닌 `ef947e5`였다(4절 21번). 짝 저장소 없는 임시 worktree에서는 `PASS_SCOPED`, 17개 `not verified`다(`results/00/00-R2-docs-nosibling.log`) |
|
||||
| 확인하지 못한 범위·이유 | 두 다운스트림에서 실제 병합 뒤 게이트(제품 repo는 읽기만), 다음 동기화 충돌 수 재측정(merge-tree가 쓰기 작업이라 하지 않았다), 깨끗한 환경 `install → dev`, 매뉴얼만 보는 기능 추가 재실험(X2), 목표 설계 문서 본문 전체, 04 §3.3·§4.3 코드 예시의 컴파일 |
|
||||
| 이전 리뷰와 비교 가능한 범위 | 지난 라운드 영역 14 발견 6건, 합친 2건(04-05, 03-06 일부), 이월 7건과 FOLLOW-UP 1건을 이 커밋에서 다시 판정했다(2절). 지난 실행 결과는 증거로 쓰지 않았다 |
|
||||
|
||||
## 2. 지난 발견 재확인
|
||||
|
||||
| 지난 ID | 내용 | 상태 | 근거 (`8a44226`) |
|
||||
|---|---|---|---|
|
||||
| 1103/14-01 (+04-05) | CHANGELOG 미출시 절이 기준 커밋과 맞지 않는다 | **일부** | 고쳐진 것: ① 미출시 절 해시 148개가 모두 `752a61f..8a44226`에 있다. 범위 밖은 머리가 기준점이라고 적은 `752a61f`·`af3d8e6` 둘뿐이다(`CHANGELOG.md:27`, E-1). ② 지난 라운드가 빠졌다고 한 8커밋이 모두 행을 가진다: `ece944d`(`:130`), `d0414c8`(`:131`), `8469554`·`7d85589`(`:134`), `7c8cb19`(`:169`), `17fa8d1`(`:198`), `27f4523`(`:133`), `8a09c90`(`:237`), `e5b7b3e`(`:185`). ③ `752a61f..8a44226`의 `!` 커밋 13개가 모두 BREAKING 행에 있다(E-2). `e40684b..8a44226` 비병합 172커밋 중 해시로 인용된 것은 65개다. 나머지 107개는 리뷰 ID로 행에 들어갔거나 테스트·리뷰 기록뿐이다. ④ 알려진 제한에서 지난번 낡았던 9줄이 빠졌다. 남은 것: (a) 초기 파일 상한이 BREAKING 7단계(`:107`)와 [계약] 행(`:216`)은 "26개", 같은 절 `:249`는 "32"다. 코드는 32다(`config/performance/budgets.json:5`, `2fef27d`). 머리 규칙 "최종 상태만 적는다"(`:7`, `:26`)를 어긴다. `:216`이 인용한 `1b8cb12`(26으로 올림)는 범위 안에서 `2fef27d`가 다시 바꾼 중간 상태다. (b) 알려진 제한 머리가 "이 절을 쓴 끝 커밋(`f887817`)에서 사실인 것만"이다(`:258`). 범위 끝은 `8a44226`이다. `:270`의 여유 1,873 B는 기록 값이고, 지난 라운드 14.5절 10회차 빌드(202,975 B)로는 1,825 B다. (c) "옮긴 뒤 확인"이 "로컬 merge 게이트 14개" 아래에 `verify:documentation`(FE-GATE-017)을 둔다(`:112-118`). FE-GATE-017은 merge 단계가 아니다(`config/ci/gates.json:2298`). 남은 것은 모두 사람이 숫자를 읽으면 `check:bundle`이 바로 알려 준다. 새 발견으로 세지 않는다 |
|
||||
| 1103/04-05 (→14-01) | handoff 결과 kind 변경(`17fa8d1`)의 [계약] 행 없음 | **고쳐짐** | `CHANGELOG.md:198`이 `1196b86`, `17fa8d1`을 함께 적는다. 알려진 제한에 `IDLE_TIMEOUT` 줄이 없다(`:256-276`) |
|
||||
| 1103/14-02 | BREAKING 이행 안내가 두 다운스트림의 실제 모양과 다르다 | **일부** | 고쳐진 것: memento-web의 모양이 실제와 같다(E-5). `*-api-contract.ts`가 없다는 것, V2 칸 위치(`contracts/memento-feature-contract.ts:28-30`, `:295`), descriptor 29개, schemaId 42개와 `MementoProblem`, `isRecord` 검증기, `responseEnvelope` 0개, 쓰기의 `KEYED`·`IDEMPOTENT`·`NEVER`(`CHANGELOG.md:41`, `:72`, `:95`, `:97`). `ownsShell` → `CONTEXT_LAYOUT`(`:76`). tech-log 직접 조립 길(`:80`)과 그 한계(`:261`). 남은 것: (a) "옮기기 전" 2단계(`:37-39`)는 "제품이 고친 템플릿 파일을 뽑는다"며 memento 7개, tech-log 11개를 적는다. 실제로 `af3d8e6` 뒤 고친 템플릿 `src` 파일은 memento 23개(+템플릿 폴더 안 새 파일 3개), tech-log 38개다(E-4). 빠진 것 중 제품 소유 자리가 없는 것이 있다. memento: `src/adapters/http/http-contract-bridge.ts`·`http-execution-v3.ts`에 descriptor 헤더 `if-match`를 더했다(낙관적 동시성, `memento-http-contract-contribution.ts:390`, `:448`). 템플릿 bridge는 지금도 `headerEntries`가 있는 projection을 거절한다(`src/adapters/http/http-contract-bridge.ts:275`). 템플릿 HTTP 폴더 안의 `offset-upload.ts`와 배럴 export, `storage-keys.ts`의 `APP_NAMESPACE`, OPFS 이름 두 곳. tech-log: `AppFailure.detail`(`src/contracts/errors.ts`), `BoundMutation.identity`(`src/contracts/server-state.ts`), `deriveAsyncState`가 `null`을 빈 상태로 보는 것(`src/application/view-models/async-state.ts`), 라우팅 파일 7개. (b) 완료 기준(안내를 memento 모양에 그대로 적용하면 `check:registries` 통과)은 실행되지 않았다. CHANGELOG가 스스로 적는다(`:32`, `:260`). 영향은 동기화 때 충돌이나 제품 fork 유지로 드러나고 조용한 데이터 피해는 없다. 남은 것은 이 ID로 둔다 |
|
||||
| 1103/14-03 (+03-06 VD-23 부분) | 목표 설계 문서의 상태 값과 401 규칙이 V2 삭제를 반영하지 않는다 | **고쳐짐**, 작은 잔여 | 완료 기준 셋을 확인했다. VD-23 머리가 `REMOVED (2026-11-03, 048f490·12f3bb7)`이고 V3 실행기를 `COMPOSED`로 적는다(`docs/architecture/decisions/VD-23-api-transport-selection-and-rest-execution.md:10-14`). 401 문장은 "401은 끝이다. 숨은 refresh-and-replay는 하지 않는다(정본 8.4, FRT-D016)"다(`:35-37`). 원장도 V2 행이 `REMOVED`다(`api-contract-schema-mapper-and-server-state.md:85`, `:101`). 6.1절은 `docs/README.md:35`이 현재 계약으로 링크한다. 검사기는 1절 링크 문서를 모두 읽으므로(`scripts/verify-documentation-readiness.ts:269-275`) 6.1절의 repo 경로도 검사된다. 없는 경로를 잡는 동작은 `tests/unit/documentation-readiness.test.ts:119`가 고정한다(E1·E2, 실행 요청 없음). 잔여: 같은 원장 본문 `:306-310`("동시 401 recovery는 … replay-safe operation만 … 한 번 재실행한다"), `:366`, `:863`("REST v2 local baseline은 … 연결됐다")이 V2 시절 서술로 남았다. 이 문서는 머리 `:3-8`에 정본 우선 안내가 있다. 코드는 정본대로다(`src/adapters/http/http-execution-v3.ts:794`). 새 발견으로 세지 않는다 |
|
||||
| 1103/14-04 (+FOLLOW-UP 09-07) | 참조 기능을 지우면 매뉴얼·입구 문서가 문서 검사를 실패시키고 드릴은 그것을 보지 않는다 | **고쳐짐** | 드릴이 문서를 복사하고(`scripts/test-sample-removal.ts:209-214`, `scripts/lib/removal-fixture.ts:56-60`) `lint`·`verify:documentation`·`check:i18n`·`check:design-system`을 돈다(`:439-442`). 문서 검사 테스트를 fixture에서 지우던 두 줄이 없어졌다. 오케스트레이터 FE-GATE-020(CI env) `sample-removal.xml` 31건 통과, `documentation`과 `scaffold-documentation` 포함. 지난 라운드 실험 E-6의 재실행은 드릴 안의 `documentation` 검사가 대신한다. 지난 제목의 "merge 게이트 FE-GATE-017"은 틀린 이름이다(0절). 결함 판단은 그대로다. 같은 종류의 결함이 예제 기능에서 새로 생겼다(14-01). 고친 방법이 검사를 좁혔다(14-03) |
|
||||
| 1103/14-05 | 정본 표와 결정표가 지운 메시지와 틀린 게이트 기대를 적는다 | **고쳐짐** | `git grep 'REST security profiles are incoherent\|cannot use the ANONYMOUS profile\|nothing requires the row' -- docs/manual docs/architecture README.md` 0건. `starter-experience.md:224`가 `tests/unit/env-registry-coverage.test.ts`를 적는다. `02-decision-tables.md:244-246`의 메시지가 코드(`src/contracts/external-contract-runtime.ts:410`, `src/contracts/rest-profiles.ts:210`)와 같다 |
|
||||
| 1103/14-06 | `check:registries`가 조립 실패의 `reason`을 버리고 `removed` 증거를 연쇄로 요구한다 | **고쳐짐** | `84d6e52`: `loadErrorText`가 `(reason: …)`를 붙이고, 읽지 못한 레지스트리는 참조·기준선 비교를 건너뛴다(`scripts/check-registries.ts:125`, `:158-164`, `:410`). `tests/unit/registry-governance.test.ts:544-650`이 출력 두 줄(원인 포함, 연쇄 없음)을 그대로 단언한다. 오케스트레이터 `test:unit`에서 통과했다(E2). 이 테스트는 손으로 던진 오류를 쓴다. 실제 계약 조립 실패(14-R5, 참조 기능 `LIST_REFERENCE_RESOURCES`의 `authProfileId`를 `NOTICE_NOPE`로)에서 출력은 `missing registry source src/features/loaded-feature-runtimes.ts: Installed contract contribution is not composable: reference-feature/LIST_REFERENCE_RESOURCES: unknown authProfileId NOTICE_NOPE (reason: …같은 문구…)` 두 줄뿐이고 rc=1이다. `removed` 줄과 `is not an object registry` 줄은 없다. 완료 기준을 채웠다(E3). 남은 군더더기: 같은 줄이 두 번(FE-REG-API·FE-REG-SCHEMA가 같은 source) 나오고, 원인이 한 줄 안에 두 번 나온다(`f98d0c3`이 메시지에 원인을 넣은 뒤 `loadErrorText`가 `(reason: …)`를 또 붙인다). 진단 정확성에는 영향이 없다 |
|
||||
| 1101/14-02 잔여 | 리뷰 ID 꼴이 섞인다 | **남음**(작은 잔여) | `CHANGELOG.md:148`, `:169` `(1101 README 14.3)`, `:149` `(1101 README 14.4, …)`, `:247` `1103 07 영역 P-07-06`. `tests/unit/changelog-review-ids.test.ts`의 정규식은 `NN-MM`·`F-N`만 본다 |
|
||||
| 1101/14-07 | 문서 위치가 상태를 드러내지 않는다 | **남음**(일부 개선) | `docs/README.md:67`이 로드맵·capability-review를 여전히 "목표 설계"에 둔다. 6.1절은 "목표 설계" 문서 안의 절을 현재 계약으로 링크하는 방식으로 올렸다(`docs/README.md:35`, `backend-api-and-server-state-contract.md:11`). 한 문서 안에 현재 계약 절과 목표 설계 절이 섞인 구조는 그대로다 |
|
||||
| 0929/14-01 | 실행 로그·작업 기록이 복사 대상에 섞인다 | **일부** | 추적 중인 `.log` 0개(지난 63개, `.gitignore:17`, `529615d`). `SPEC.md`·`tasks/`는 루트에 있고 이유가 "이 라운드가 쓰는 중"이다(`docs/README.md:85`). 2026-09-25 라운드는 끝났다 |
|
||||
| 0929/14-02 | README 업데이트 절차가 범위 반영을 다루지 않는다 | **일부** | `README.md:363-366`이 "미출시 절은 한 동기화 범위다. 범위 전체를 받고 BREAKING 단계를 먼저 한다"고 적는다. 그러나 명령은 커밋 하나 `cherry-pick`(`:379`)과 `git diff`뿐이다. 두 제품이 실제로 쓰는 범위 merge·3-way 이식 명령은 없다. 두 기준점 형식(`.template-origin`, `template.lock.json`)은 CHANGELOG `:36`에만 있다 |
|
||||
| 0929/14-03 | 제품이 고치는 템플릿 파일 목록이 없다 | **일부** | 제품 소유 자리가 넓어졌다(`src/contracts/product-contracts.ts`, `src/bootstrap/product-composition.ts`, `src/features/product-capabilities.ts`, `config/ci/product-gates.json`, 매뉴얼 03 C절). 남은 것의 근거는 1103/14-02 잔여 (a)와 같다. 거기서 센다 |
|
||||
| 0929/14-05 | `FEATURE_OVERRIDES` 남은 키를 "조용히 무시"로 적는다 | **남음** | `docs/operations/ci-quality-gates.md:69` 그대로. 코드는 `release admission warning: FEATURE_OVERRIDES.<id> … the override does nothing`를 낸다(`scripts/check-release-admission.ts:131-141`) |
|
||||
| 0929/14-06 | 제품이 찾은 템플릿 결함 후보가 돌아오지 않는다 | **남음** | `README.md:393-398`의 분류 문단뿐이다. 다운스트림이 보낸 기록은 repo에 없다. 이번 라운드도 템플릿 리뷰가 다운스트림 코드를 직접 읽었다(1103/14-02 잔여) |
|
||||
| FOLLOW-UP(09-25) 09-07 (→1103/14-04) | 제거 검사가 lint·`check:i18n`·문서를 건너뛴다 | **고쳐짐** | `scripts/test-sample-removal.ts:439-442`. e2e·visual은 설계상 드릴 밖이고 문서에 적혀 있다(`docs/manual/reference/create-feature.md:164`) |
|
||||
|
||||
1101/14-01·03·04·05·06은 지난 라운드에 고쳐졌고 이번에 되돌아간 것이 없다.
|
||||
|
||||
## 3. 이번 발견 (36.3)
|
||||
|
||||
수: Critical 0 · High 0 · Medium 1 · Low 2. P1 0 · P2 2 · P3 1. 확인된 결함 2 · 구조적 위험 1.
|
||||
|
||||
### 14-01 예제 기능을 지우라는 안내와 문서가 맞지 않는다 — `starter-experience.md`의 백틱 경로 세 개 때문에 지운 제품은 문서 검사(merge 게이트 FE-GATE-005 포함)가 실패하고, 안내한 드릴도 실패한다. `PRODUCT.md`는 반대로 지울 수 없다고 적는다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 27, 30.5, 30.4, 9, 20, 10 |
|
||||
| 근거 | **안내.** `b96d61d`(1103/09-04 조치)가 예제 화면 3개를 끌 수 있는 기능 `platform-examples-feature`로 옮겼다. `CHANGELOG.md:103`은 "예제를 지운 제품(tech-log)은 이 기능 폴더와 `src/contexts/platform-examples-context/`를 지운다"고 적는다. `docs/architecture/starter-experience.md:104-111`은 지우는 법과 드릴 명령(`:108`, `test:sample-removal -- --feature=platform-examples-feature`)을 적고, 세 경로를 백틱 경로로 적는다(`:105`, `:106`, `:111`). **검사.** `verify:documentation`은 `docs/README.md` 1절 문서의 백틱 경로가 있는지 본다(`scripts/verify-documentation-readiness.ts:294`, `:319-325`). 예외는 아직 없는 web worker 폴더 하나와 README의 지울 이력 목록뿐이다(`:161-165`, `:202-208`). merge 단계에서는 FE-GATE-005의 `tests/unit/documentation-readiness.test.ts:58`("passes the documents as they are")이 같은 스크립트를 이 repo의 코드에 대고 돈다. **실험 14-R1(E3).** 세 폴더를 지우고 돌렸다. `verify:documentation`: `docs/architecture/starter-experience.md names paths that do not exist: src/contexts/platform-examples-context, src/features/platform-examples-feature, tests/features/platform-examples-feature`, `FAIL_UNVERIFIED (failed: document references)`, rc=1. 같은 출력에 짝 백엔드 경로 줄도 있는데, 이것은 desktop의 백엔드 checkout이 pin이 아닌 `ef947e5`라서 생긴 환경 실패다(4절 21번). merge 게이트 쪽: `documentation-readiness.test.ts` "passes the documents as they are"가 위 세 경로만으로 실패했다(짝 저장소 없는 임시 사본, rc=1). 지우지 않은 `8a44226`에서는 같은 테스트가 통과한다(오케스트레이터 `gates/test_unit.log`, 19건). **드릴.** 안내한 드릴은 문서를 복사하고(`scripts/test-sample-removal.ts:209-214`) `verify:documentation`을 돈다(`:440`). 또 `src`·`tests`에서 기능 ID를 찾는다(`:417-426`). `tests/unit/hosting-probe.test.ts:248`이 `FEATURE_OVERRIDES: { "platform-examples-feature": false }`를 예시로 쓴다. 그래서 드릴은 `documentation`과 `fixture-id-residue` 두 검사에서 실패한다(E1 추론, 드릴은 시간이 커서 요청하지 않았다). 어느 게이트도 이 드릴을 돌리지 않는다(FE-GATE-020 명령은 `test:sample-removal` 기본값인 참조 기능뿐, `config/ci/gates.json` FE-GATE-020). **반대 주장.** `PRODUCT.md:33`은 "예제 라우트 4개(`/examples/platform`, `ui`, `states`, `auth`)와 홈은 기본 구성이고 제거 드릴이 없습니다"다. `b96d61d` 뒤 셋은 지울 수 있는 기능이다. `PRODUCT.md`는 1절 밖이라 검사되지 않는다 |
|
||||
| 발생 조건 | 제품이 CHANGELOG 6단계나 `starter-experience.md`대로 예제 기능 폴더를 지울 때. 그 안내의 드릴로 지울 수 있는지 확인할 때. tech-log가 이 묶음을 동기화할 때(CHANGELOG가 tech-log를 이름으로 가리킨다) |
|
||||
| 영향 | tech-log는 동기화 직후 FE-GATE-005(`test:unit`)가 실패한다. 통과하려면 템플릿 소유 문서 `starter-experience.md`를 고치거나 예제 폴더를 남겨야 한다. 고치면 다음 동기화마다 그 줄이 충돌한다(0929/14-03과 같은 원리). "지울 수 있다"의 증거로 안내한 드릴이 실패해 사람이 원인을 다시 찾는다. 디자인 도구가 읽는 `PRODUCT.md`는 지울 수 없다고 말한다. 데이터·보안 피해는 없다 |
|
||||
| 심각도·우선순위 | Medium · P2 — 1103/14-04와 같은 기준이다. 게이트가 실패를 드러내므로 조용한 피해는 없다. 그러나 CHANGELOG가 직접 시킨 일이 merge 게이트를 깨고, "지울 수 있는 기능" 약속과 문서 유지가 부딪친다 |
|
||||
| 통제·증거 | 목표 M3(문서가 지울 수 있다고 한 기능마다 그 제거 드릴이 게이트에서 돈다). 확인: 참조 기능 M3(FE-GATE-020), 예제 기능 M0(드릴을 도는 게이트 없음) · 문서 검사 실패 E3(14-R1). 드릴 실패 E1(추론). `PRODUCT.md` E1 |
|
||||
| 확실성과 남은 가정 | 문서 검사와 merge 게이트 테스트의 실패는 실험으로 확인했다(14-R1). 드릴의 실패(`documentation`, `fixture-id-residue`)는 드릴 코드를 읽은 추론이다. tech-log가 실제로 폴더를 지울지는 tech-log의 결정이다. CHANGELOG가 그렇게 하라고 적었다. 드릴의 다른 실패(e2e·visual spec이 예제 화면을 연다)는 알려진 제한에 적혀 있고(`CHANGELOG.md:268`) 드릴 밖이다 |
|
||||
| 결정의 근거 | 기록된 사실: 1103/14-04 조치(`c4d5870`, 게이트·드릴 브랜치 병합 `fbd8f7d`)는 참조 기능 경로만 백틱에서 뺐다. 예제 기능 이동(`b96d61d`)은 다른 수정 브랜치(예제 화면·시각·접근성, 병합 `83f4dd5`)에서 왔다. 리뷰어의 추론: 두 브랜치가 서로의 규칙을 보지 못했다. 선택 비교는 아래 대안 |
|
||||
| 이해 비용 | 제품 개발자는 CHANGELOG → `starter-experience.md` → 문서 검사 출력 → `verify-documentation-readiness.ts` 예외 목록 순으로 읽어야 원인을 안다 |
|
||||
| 최소 개선 방향 | ① `starter-experience.md:105`, `:106`, `:111`의 경로를 참조 기능과 같은 규칙(`CHANGELOG.md:225`)으로 백틱 없이 적거나 기능 ID로 적는다. ② `tests/unit/hosting-probe.test.ts:248`의 키를 고정 fixture ID로 바꾼다. ③ `PRODUCT.md:33`을 고친다. ④ 같은 일이 다음 기능에서 반복되지 않게 아래 (c)를 한다 |
|
||||
| 대안 비교 | (a) 현 상태: 지운 제품마다 템플릿 문서를 고친다. (b) ①~③만: 싸다. 그러나 경로 검사가 또 좁아진다(14-03). (c) 검사기가 "설치된 기능의 폴더(`src/features/<dir>/`, `tests/features/<dir>/`, 그 context 폴더) 아래 경로는 그 폴더가 있을 때만 본다"를 규칙으로 갖는다: 있을 때는 지금처럼 잡고, 지운 뒤에는 통과한다. 14-03도 함께 풀린다. 지난 라운드 5.2절 (c)는 "지운 뒤에 독자가 끊긴 링크를 만난다"고 버렸지만, 지운 제품에서 그 예시는 어차피 쓸 수 없다. (d) FE-GATE-020에 `--feature=platform-examples-feature`를 더한다: 확실하지만 job 시간이 약 5분 는다(지금 1,156초). (c) + ②③ 권장, (d)는 기능이 셋 이상 지울 수 있게 되면 |
|
||||
| 단순화의 보존 조건 | 플랫폼 경로(`src/presentation/…`, `src/contracts/…`)의 검사는 좁히지 않는다. 참조 기능을 지운 사본에서 문서 검사가 통과하는 지금 성질(1103/14-04)은 유지한다 |
|
||||
| 비용·부작용 | ①~③ 문서 3곳·테스트 1줄. (c) 검사기 수십 줄과 테스트 |
|
||||
| 재검토 조건 | 예제 화면을 다시 지울 수 없는 플랫폼 구성으로 되돌리면 이 발견은 `starter-experience.md`·CHANGELOG 문장 정정으로 바뀐다 |
|
||||
| 완료 기준 | 세 폴더를 지운 사본에서 `verify:documentation`과 `documentation-readiness.test.ts`가 통과한다. `test:sample-removal -- --feature=platform-examples-feature`가 통과한다. `PRODUCT.md:33`이 코드와 같다 |
|
||||
| 검증 방법 | 14-R1 재실행, `corepack pnpm test:sample-removal -- --feature=platform-examples-feature` |
|
||||
| 담당·기한·상태 | 미정 · tech-log 동기화 전 · 신규 |
|
||||
| 재검증 결과 | 미실시 |
|
||||
|
||||
### 14-02 매뉴얼 04 §3.2의 제품 설정 키 예시에 `defaultValue`가 없어, 그대로 옮기면 `check:types`(FE-GATE-003)와 `test:unit`(FE-GATE-005)이 실패한다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 20, 19, 9 |
|
||||
| 근거 | `docs/manual/04-paired-backend-session.md:127-130`의 `PRODUCT_ENV_REGISTRY` 두 행은 `{ phase: "runtime", classification: "public", required: false }`이고 `defaultValue`가 없다. 행 타입은 `defaultValue: unknown`을 필수 칸으로 가진다(`src/contracts/env.ts:37-42`). `env.ts:94-95`가 제품 행을 그 타입에 넣는다. `tests/unit/env-registry-coverage.test.ts:52-63`은 행의 `{ required, defaultValue }`를 스키마가 키 없을 때 내는 값(`.optional()`이면 `{ required: false, defaultValue: null }`)과 `isDeepStrictEqual`로 비교한다. 같은 매뉴얼 03 C절은 "기본값이 없으면 `defaultValue: null`"이라고 적는다(`03-outside-feature-folder.md:114`). `product-contracts.ts:9-13` 주석도 `defaultValue`를 쓴 예를 든다. 04는 `f3fd10f`(1103/09-03 조치)에서 썼고, 그때 타입에도 `defaultValue`가 이미 필수였다(`git show f3fd10f:src/contracts/env.ts`). **실험 14-R3·14-R4(E3).** 04 §3.2를 그대로 `product-contracts.ts`에 넣으면 `check:types:app`이 `src/contracts/env.ts(94,9): error TS2322 … Property 'defaultValue' is missing …`로, `env-registry-coverage`가 `OIDC_ISSUER: row {"required":false}, schema {"required":false,"defaultValue":null}`(`OIDC_CLIENT_ID`도 같다)로 실패했다(둘 다 rc=1). 대조로 두 행에 `defaultValue: null`만 더하면 둘 다 rc=0이다. 원인은 그 칸 하나다 |
|
||||
| 발생 조건 | 짝 백엔드 `jwt` 모드로 처음 붙이는 제품이 04 §3.2를 복사할 때 |
|
||||
| 영향 | 첫 시도에서 타입 검사와 unit 게이트가 실패한다. 실패 메시지가 칸 이름을 말하므로 고치기는 쉽다. 데이터·보안 영향은 없다 |
|
||||
| 심각도·우선순위 | Low · P2 — 1103/14-05와 같은 기준이다. 매뉴얼 몇 줄의 어긋남이고 게이트가 잡는다. 다만 04는 짝 백엔드에 처음 붙이는 사람이 그대로 따라 하는 문서다 |
|
||||
| 통제·증거 | 목표 M3(매뉴얼 코드 예시가 지금 타입·테스트를 통과한다). 확인: M0. `verify:documentation`은 설명·코드 블록을 검사하지 않는다(`docs/README.md:49`). recipe 테스트(`tests/recipes/session-owners-runtime.test.ts:48`)는 빈 제품 행으로 돈다 · E3(14-R3, 14-R4) |
|
||||
| 확실성과 남은 가정 | 04의 다른 코드 예시(§3.3, §4.3)는 recipe 옵션 이름(`recipes/session-owners/oidc-pkce-session-owner.ts:46-66`, `cookie-session-owner.ts:70-82`)과 정적으로만 대조했다. 이름은 맞았다. 컴파일은 하지 않았다 |
|
||||
| 결정의 근거 | 적용 제외 — 문서를 코드에 맞추는 일이다 |
|
||||
| 이해 비용 | 작다. 실패 메시지를 보고 03 문서나 `product-contracts.ts` 주석을 찾는다 |
|
||||
| 최소 개선 방향 | ① 04 §3.2의 두 행에 `defaultValue: null`을 더한다. ② (선택) recipe 파일이 예시 행을 export하고 recipe 테스트가 그 행으로 조립한다. 매뉴얼은 그 export를 가리킨다. 예시가 한 곳에만 있게 된다 |
|
||||
| 대안 비교 | ① 문장만: 싸다. 다음 타입 변경에서 다시 어긋날 수 있다. ② 예시를 코드로: 테스트가 예시를 지킨다. recipe에 예시 상수가 하나 는다. ①을 지금, ②는 04를 다시 고칠 때 |
|
||||
| 단순화의 보존 조건 | 적용 제외 |
|
||||
| 비용·부작용 | ① 두 줄. ② 수십 줄 |
|
||||
| 재검토 조건 | 적용 제외 |
|
||||
| 완료 기준 | 04 §3.2를 그대로 옮긴 사본에서 `check:types:app`과 `env-registry-coverage`가 통과한다 |
|
||||
| 검증 방법 | 14-R3 재실행 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
| 재검증 결과 | 미실시 |
|
||||
|
||||
### 14-03 참조 기능 경로 26줄을 백틱에서 빼서, 문서 검사가 그 경로를 더 보지 않는다 — 지금은 모두 있지만 참조 기능 파일 이름이 바뀌면 매뉴얼이 조용히 낡는다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 구조적 위험(이 영역 수정이 만든 검사 약화) |
|
||||
| 관련 관점 | 21, 10, 9, 20 |
|
||||
| 근거 | 1103/14-04 조치(`c4d5870`, `2f2426a`, `fd11d08`, `2c2d459`, `b6bfc9b`)가 참조 기능·참조 context 경로와 그 전용 script를 백틱 없이 다시 적었다. `git diff e40684b..8a44226 -- docs README.md`에서 백틱 안의 `reference-feature`·`reference-context`를 지운 줄이 26개다. 예: `docs/manual/01-add-a-feature.md:8`, `:151`, `:237`, `:374`, `:418`, `:419`, `:483`, `:514`, `:610`, `02-decision-tables.md`의 `CREATE_EFFECT` 줄, `backend-api-and-server-state-contract.md:269-270`. 검사기는 백틱 안·명령 안·링크의 경로만 본다(`scripts/verify-documentation-readiness.ts:294-300`). 규칙은 `CHANGELOG.md:225`에 적혀 있다. **지금 상태(E1, E-6).** 1절 문서에서 백틱 밖에 적힌 참조 기능 경로 14개와 샘플 전용 파일 11개는 `8a44226`에서 모두 있다. 그래서 지금은 피해가 없다. 지난 라운드 1103/14-04가 권한 방법 (b)의 비용이다 |
|
||||
| 발생 조건 | 참조 기능 파일 이름이나 위치가 바뀔 때(예: `reference-routes.ts`를 옮김). 매뉴얼은 그 경로를 예제로 가리키지만 어느 게이트도 실패하지 않는다 |
|
||||
| 영향 | 매뉴얼 독자가 없는 예제 경로를 따라간다. 매뉴얼이 약속한 "이 폴더 문서의 경로·명령·게이트 ID는 검사된다"(`docs/manual/README.md:85`)가 예제 경로에서는 성립하지 않는데, 그 사실이 독자에게 보이지 않는다 |
|
||||
| 심각도·우선순위 | Low · P3 — 지금 낡은 경로는 없다. 생기면 문서 독자의 시간만 든다 |
|
||||
| 통제·증거 | 목표 M3(참조 기능이 있을 때는 그 경로도 검사된다). 확인: 이 26줄은 M3 → M0 · E1 |
|
||||
| 확실성과 남은 가정 | 26줄은 diff에서 센 값이다. 같은 줄에 경로가 둘 이상이면 경로 수는 더 많다 |
|
||||
| 결정의 근거 | 기록된 판단: 지난 라운드 5.2절이 (b)를 고르고 (c)(검사기 예외)를 "독자가 끊긴 링크를 만난다"로 버렸다. 리뷰어의 추론: (c)를 "폴더가 있을 때만 본다"로 좁히면 그 반대 이유가 지운 제품에만 해당한다. 비교는 14-01 대안 (c) |
|
||||
| 이해 비용 | 참조 기능을 고치는 사람이 매뉴얼을 `git grep`으로 직접 찾아 고쳐야 한다 |
|
||||
| 최소 개선 방향 | 14-01 대안 (c)를 하고 26줄을 다시 백틱으로 적는다. (c)를 하지 않으면, 참조 기능 폴더가 있을 때 1절 문서의 `src/features/reference-feature/…` 꼴 문자열이 모두 있는지 보는 단위 테스트 하나 |
|
||||
| 대안 비교 | 14-01과 같다 |
|
||||
| 단순화의 보존 조건 | 참조 기능을 지운 사본에서 문서 검사가 통과하는 성질은 유지한다 |
|
||||
| 비용·부작용 | (c)와 같다. 단위 테스트만이면 수십 줄 |
|
||||
| 재검토 조건 | 참조 기능을 템플릿에서 빼거나 지울 수 없는 기본 구성으로 바꾸면 이 위험은 없어진다 |
|
||||
| 완료 기준 | 참조 기능 파일 하나의 이름을 바꾸는 변이에서 그 경로를 적은 매뉴얼 줄 때문에 게이트가 실패한다. 참조 기능을 지운 사본에서는 통과한다 |
|
||||
| 검증 방법 | 위 두 변이 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
| 재검증 결과 | 미실시 |
|
||||
|
||||
## 4. 28개 관점 판정 (36.2)
|
||||
|
||||
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역.
|
||||
|
||||
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | 코드 성숙도 | > 01~13 영역 | - | - | 이 영역은 문서·드릴 스크립트만 본다 |
|
||||
| 2 | 구조적 성숙도 | > 09·12 영역 | M3 / M3 | E1 | 입구 문서의 폴더·규칙 설명은 지난 라운드처럼 검사된다(`verify-documentation-readiness.ts:102-150`) |
|
||||
| 3 | 변경 용이성 | 적용 | M2 / M1 | E1 | P — 제품 소유 자리가 4파일 + `product-gates.json`으로 늘었다. 두 제품이 고친 템플릿 `src` 파일 26/38개 중 안내가 다루는 것은 7/11개다(1103/14-02 잔여) |
|
||||
| 4 | 인지 부하 | 적용 | M1 / M1 | E1 | P — 문서 195개 93,445줄. 매뉴얼은 2,206줄로 늘었지만 한 경로(README → 01 → 02·03·04 → reference)다. 원장 본문에 V2 서술이 남아 정본 안내를 함께 읽어야 한다(1103/14-03 잔여) |
|
||||
| 5 | 위험 가시성 | 적용 | M2 / M2 | E1 | P — 알려진 제한 17줄은 대부분 지금 사실이다. 머리가 `f887817` 기준이다. 다운스트림에 적용해 보지 않았다는 사실을 스스로 적는다(`CHANGELOG.md:32`, `:260`) |
|
||||
| 6 | 실패 성숙도 | > 다른 영역 | - | - | - |
|
||||
| 7 | 운영 성숙도 | > 11·13 영역 | - | - | - |
|
||||
| 8 | 디버깅 가능성 | 적용 | M3 / M3 | E2(단위 테스트)·E3(14-R5) | O — `check:registries`가 조립 실패 원인을 적는다(1103/14-06). 문서 검사 실패가 문서·경로를 적는다 |
|
||||
| 9 | 유지보수 성숙도 | **깊게 봄** | M3 / M1~M3 | E1 | P — 지운 V2 상태 값을 함께 고쳤다(1103/14-03). 다른 브랜치에서 온 수정이 문서에서 만나지 못했다(14-01, 1103/14-01 잔여 (a)) |
|
||||
| 10 | 테스트 성숙도 | 적용 | M3 / M3(참조 기능) | E2(오케스트레이터 FE-GATE-020) | P — 참조 기능 제거 드릴이 문서·lint·i18n·디자인 게이트를 돈다. 예제 기능의 제거 드릴을 도는 게이트는 없다(14-01) |
|
||||
| 11 | 데이터 성숙도 | - 이 영역에 데이터 경계가 없다 | - | - | - |
|
||||
| 12 | 동시성 성숙도 | - 이 영역에 동시 실행 경로가 없다 | - | - | - |
|
||||
| 13 | 확장성 | > 11·15 영역 | - | - | - |
|
||||
| 14 | 성능 성숙도 | > 15 영역 | - | - | 문서 규모만 4번에 적었다 |
|
||||
| 15 | 보안 성숙도 | > 다른 영역 | - | E1 | 04 문서의 보안 주장(토큰을 storage에 두지 않음, ID token 서명 미검사, 쿠키 host 제약)은 recipe 주석·코드와 같은 말을 한다. 동작은 09 영역 |
|
||||
| 16 | 의존성 성숙도 | 적용(제품에게 템플릿은 의존성) | M2 / M1 | E1 | P — 태그 `v0.2.0` 뒤 348커밋이 태그 없이 쌓였다. 두 제품의 기준점 형식이 다르다(0929/14-02) |
|
||||
| 17 | API / Contract 성숙도 | **깊게 봄** | M3 / M2 | E1 | P — BREAKING 행과 이행 순서가 범위와 맞는다(1103/14-01 고쳐진 부분). 초기 파일 상한 [계약] 숫자가 틀리다(잔여 (a)). 목록에 없는 제품 수정 중 제품 소유 자리가 없는 계약 변경이 있다(1103/14-02 잔여) |
|
||||
| 18 | 배포 성숙도 | > 13 영역 | - | - | - |
|
||||
| 19 | 설정 성숙도 | 적용 | M3 / M3 | E3(14-R3) | P — 제품 설정 키의 FE-REG-ENV 행은 테스트가 요구한다. 04 예시가 그 규칙을 어긴다(14-02). `FEATURE_OVERRIDES` "조용히 무시"(0929/14-05) |
|
||||
| 20 | 개발자 경험 | **깊게 봄** | M3 / M2 | E1 | P — 매뉴얼 01·02·03·reference의 오류 문구 70여 개가 코드에 있다(E-3). 04 예시 하나가 게이트를 깬다(14-02). 생성 명령 출력 `Next:` 1~3과 매뉴얼이 같은 말을 한다(`scripts/create-feature.ts:1746-1756`). 매뉴얼만 보는 재실험은 이번에도 미실시 |
|
||||
| 21 | Guardrail 성숙도 | 적용 | M3 / M0~M3 | E1 | P — 문서 경로 검사가 명령 안 경로·짝 저장소 참조까지 넓어졌다. 반대로 참조 기능 경로 26줄이 검사 밖으로 나갔다(14-03). 짝 저장소 참조는 CI에서 `not verified`다(`CHANGELOG.md:273`). 짝 저장소가 옆에 있으면 pin(`config/contracts/backend-contract-pin.json`, `45d2a478`)이 아니라 그 작업 트리를 본다(`scripts/verify-documentation-readiness.ts:305-317`). 그래서 결과가 개발자의 백엔드 checkout에 따라 바뀐다: 오케스트레이터 로컬 실행은 백엔드가 `ef947e5`였을 때 rc=1(`docs/web/http-contract.md`, `docs/manual/07-authorization.md`, `src/application-fileserver` 등이 없다고 적는다. `ef947e5`에는 실제로 없다), 짝 저장소 없는 임시 worktree는 `PASS_SCOPED`, 17개 `not verified`다(`results/00/00-R2-docs-nosibling.log`). 검사기는 12 영역 소관이라 여기서 발견으로 세지 않는다 |
|
||||
| 22 | 추상화 성숙도 | > 09 영역 | - | - | - |
|
||||
| 23 | 일관성 | 적용 | M1 / M1 | E1 | P — 리뷰 ID 꼴 넷이 섞였다(1101/14-02 잔여). 같은 문서 안 숫자 26/32(1103/14-01 잔여). `PRODUCT.md`와 `starter-experience.md`가 예제 제거를 반대로 적는다(14-01) |
|
||||
| 24 | 네이밍 / 의미 성숙도 | 적용 | M1 / M1 | E1 | P — "merge 게이트 14개"에 FE-GATE-017을 넣는다(1103/14-01 잔여 (c)). 04 머리의 "백엔드 `bbe944bd` 기준"(`04-paired-backend-session.md:10`)은 pin `45d2a478`과 다르다. 두 커밋 사이 인증 설정 파일 변경은 없다(`git diff --stat bbe944bd 45d2a478 -- …/auth security.yml application-local.yml infra/keycloak` 0줄) |
|
||||
| 25 | 조직 확장성 | 적용 | M2 / M1 | E1 | P — 두 제품의 모양을 템플릿 리뷰가 직접 읽어 안내를 맞춘다. 다운스트림 모양 fixture로 안내를 검증하는 장치는 없다(1103/14-02 대안 (B) 미실시) |
|
||||
| 26 | Ownership 성숙도 | **깊게 봄** | M1 / M1 | E1 | P — 제품 소유 파일과 "고치지 않는다" 목록이 매뉴얼 03 C·D절에 있다. 다운스트림 결함 보고 경로는 기록이 없다(0929/14-06) |
|
||||
| 27 | 삭제 가능성 | **깊게 봄** | M3 / M0~M3 | E2(오케스트레이터), E1 | P — 참조 기능 삭제는 드릴과 문서 검사를 함께 통과한다(1103/14-04, 오케스트레이터 FE-GATE-020). 예제 기능 삭제는 문서 검사와 그 드릴이 실패한다(14-01). 이력 삭제는 지난 라운드 실험 뒤 바뀐 것이 없다 |
|
||||
| 28 | 회복 가능성 | > 다른 영역 | - | - | 동기화 되돌림(`git revert`, `README.md:391`)은 실행하지 않았다 |
|
||||
|
||||
### 4.1 30절 템플릿 기준
|
||||
|
||||
| 절 | 판정 | 근거 |
|
||||
|---|---|---|
|
||||
| 30.1 최소 구성과 안전한 기본값 | P | 자리표시자 계약 신원은 staging·production 승인이 거절한다(`src/contracts/deployment-admission.ts:133`). 깨끗한 환경 실행은 이번에도 확인하지 못했다 |
|
||||
| 30.2 옵션 조합의 수와 검증 책임 | P | 지울 수 있는 기능이 둘(참조, 예제)이 됐는데 드릴은 하나만 게이트에 있다(14-01) |
|
||||
| 30.3 생성·복사 후 수정 권한 | P | 제품 소유 파일이 늘었다. 두 제품이 고친 템플릿 파일 중 일부는 옮길 자리가 없다(1103/14-02 잔여). 예제를 지운 제품은 템플릿 문서를 고쳐야 한다(14-01) |
|
||||
| 30.4 버전과 업데이트 전파 | P | 미출시 절이 범위와 맞고 다운스트림 모양을 적는다. 남은 것: 숫자 하나, 기준 커밋 표기, 목록의 빈칸, 적용 실험 없음(2절) |
|
||||
| 30.5 샘플 코드의 대표성 | P | 매뉴얼은 생성 명령으로 시작하고 참조 기능을 "있으면 더 볼 곳"으로 둔다. 그 경로는 검사 밖이다(14-03) |
|
||||
| 30.6 도입·유지 비용 | P | 문서 195개 93,445줄, 이번 동기화 범위 348커밋. FE-GATE-020 한 번 1,156초(오케스트레이터) |
|
||||
| 30.7 템플릿에서 졸업할 수 있는가 | P | `runtime: "zod"` 같은 닫힌 값과, 제품 자리가 없는 실행기 수정(`if-match`)이 제품을 템플릿 파일에 묶는다 |
|
||||
| 30.8 배포 판단에 필요한 최소 증거 | P | "기능 추가": 오류 문구 대조 E1, 생성 드릴 E2(오케스트레이터). "선택 기능 분리": 참조 기능 E2, 예제 기능 E3(문서 검사 실패, 14-R1). "패치 전달": 안내와 실제 파일 대조 E1, 적용 실험 없음 |
|
||||
|
||||
## 5. 미검증
|
||||
|
||||
| 항목 | 이유 | 확인하려면 |
|
||||
|---|---|---|
|
||||
| 두 다운스트림의 실제 병합 뒤 게이트 | 제품 repo는 읽기만 했다 | 제품 sync 브랜치에서 병합하고 CHANGELOG만 보고 `check:types`·`check:registries`·`test:unit`까지 진행 |
|
||||
| 다음 동기화 충돌 수(`8a44226` 기준) | `git merge-tree --write-tree`는 객체를 쓰는 작업이라 하지 않았다. 지난 라운드 값(memento 25, tech-log 76경로)은 `e40684b` 기준이다 | scratch clone에서 지난 라운드 E-5 재실행 |
|
||||
| memento의 `if-match` 실행기 수정이 병합 뒤 남는지 | 템플릿은 `http-contract-bridge.ts`를 주석 2줄만 고쳤다. 자동 병합으로 memento 수정이 남을 것으로 추론했다 | memento clone에서 병합 |
|
||||
| 예제 기능 제거 드릴(`test:sample-removal -- --feature=platform-examples-feature`) | 개별 실행이 취소됐고 시간이 커서 배치에 넣지 않았다. 실패는 문서 검사(14-R1)와 잔여 검사(`tests/unit/hosting-probe.test.ts:248`)로 추론했다 | 14-01을 고친 뒤 완료 기준으로 1회 |
|
||||
| 매뉴얼만 보는 기능 추가(X2) | 지난 라운드 14.6절도 고친 뒤 다시 돌리지 않았다 | 깨끗한 clone에서 매뉴얼만 보는 에이전트 1회 |
|
||||
| 04 §3.3·§4.3 코드 예시 컴파일 | recipe 옵션 이름만 대조했다 | recipe를 `src/bootstrap/`에 복사하고 예시를 붙여 `check:types:app` |
|
||||
| 깨끗한 환경 `install --frozen-lockfile` → `dev` | 공유 `node_modules` | 새 clone이나 컨테이너에서 README 명령만 |
|
||||
| 목표 설계 문서 본문 전체 | 약 3만 줄. 상태 줄과 검색 결과만 봤다 | `git grep -i -E 'v2|replay|mapper registry'` 후보를 코드와 대조 |
|
||||
| 짝 백엔드가 pin에 있을 때의 `verify:documentation` | desktop 백엔드 checkout이 실행 시점에 `ef947e5`였다. 그때는 짝 백엔드 경로 여러 개가 없다고 실패했다. 짝 저장소 없는 실행은 통과했다 | 백엔드를 `45d2a478`에 두고 1회. 4절 21번(12 영역과 함께) |
|
||||
|
||||
## 6. 실행 기록
|
||||
|
||||
정적 확인(노트북, 읽기만):
|
||||
|
||||
| ID | 무엇을 | 어떻게 | 결과 |
|
||||
|---|---|---|---|
|
||||
| E-1 | CHANGELOG 해시 위치 | 미출시 절(`:14-277`) 백틱 해시 153개를 `git rev-parse`·`git merge-base --is-ancestor`로 `8a44226`, `752a61f`, `e40684b`와 대조 | 이 repo 해시 150개. 148개가 `752a61f..8a44226` 범위. 범위 밖 2개는 기준점 `752a61f`·`af3d8e6`. 나머지 3개는 다른 repo(`45d2a478`, `7a4e201a`, `d3810a0`) |
|
||||
| E-2 | 범위 커밋과 행 대조 | `git log --no-merges e40684b..8a44226`(172개)와 인용 해시 비교, 커밋마다 `Refs:` 꼬리말 확인. `752a61f..8a44226`의 `type(scope)!:` 커밋과 본문에 `BREAKING`이 있는 커밋 | 해시 인용 65개. 인용 없는 107개는 리뷰 ID로 행에 있거나 테스트·리뷰 기록. `!` 커밋 13개 모두 BREAKING 행. 숫자 불일치 1건(26/32) |
|
||||
| E-3 | 매뉴얼 오류 문구 | 01·02·03·reference의 백틱 메시지 고정 부분을 `src`·`scripts`·`eslint.config.ts`·`tests/unit`·`tests/e2e`·`.dependency-cruiser.json`에서 `git grep -F` | 약 70개 모두 있다(템플릿 문자열은 고정 부분으로) |
|
||||
| E-4 | 두 다운스트림이 고친 템플릿 파일 | 각 repo에서 `git diff --name-status af3d8e6 HEAD -- src`(제품 기능·context 폴더 제외) | memento 수정 23, 템플릿 폴더 안 추가 3. tech-log 수정 38. CHANGELOG 목록 7, 11 |
|
||||
| E-5 | memento-web 모양 | `memento-http-contract-contribution.ts`, `memento-feature-contract.ts` 집계 | descriptor 29(GET 16, 쓰기 13), 검증기 schemaId 42(+`MementoProblem`), `responseEnvelope` 0, `headerEntries` 2 operation(`if-match`) |
|
||||
| E-6 | 백틱 밖 경로 | 1절 문서에서 백틱 없이 적은 참조 기능·예제 기능·샘플 전용 경로를 모아 존재 확인 | 참조 기능 14개, 샘플 전용 11개 모두 있다 |
|
||||
|
||||
desktop 실행: 개별 실행 `14-docs`(S0~S6)와 `14-examples-drill`은 잠금 대기 중 19:55에 취소돼 돌지 않았다(BRIEF-2). desktop checkout에는 손대지 않았다. 필요한 것만 배치로 요청했다(`scratchpad/r4/requests/14.md`). 오케스트레이터가 2026-11-05 20:09에 차례로 돌렸다(부하 2.9~3.0, 각 1~2초). 각 실행 앞뒤로 checkout을 `8a44226`으로 되돌렸고 복구는 모두 clean이다. 로그: `scratchpad/r4/results/14/`. 표의 rc는 마지막 `echo`의 것이고, 명령별 rc는 로그의 `*-rc=` 줄이다.
|
||||
|
||||
| 요청 | 명령 | 변이 | 발견 | 결과 |
|
||||
|---|---|---|---|---|
|
||||
| 14-R1 | `verify:documentation`, `run-vitest … documentation-readiness.test.ts -t "passes the documents as they are"` | `mut/14-R1-rm-examples.sh`(예제 기능·context·기능 테스트 삭제) | 14-01 | rc 0(마지막 echo). `verify-rc=1`: `starter-experience.md`의 세 경로 + 환경 탓 짝 백엔드 경로. `doc-test-rc=1`: "passes the documents as they are"가 세 경로로 실패. 복구 clean |
|
||||
| 14-R3 | `check:types:app`, `run-vitest … env-registry-coverage.test.ts` | `requests/14-R3.diff`(04 §3.2 그대로) | 14-02 | `types-app-rc=1`(TS2322, `defaultValue` 없음, `src/contracts/env.ts:94`), `env-coverage-rc=1`(두 키 `row {"required":false}`). 복구 clean |
|
||||
| 14-R4 | 같음 | `requests/14-R4.diff`(`defaultValue: null` 추가, 대조) | 14-02 | `types-app-rc=0`, `env-coverage-rc=0`(4건 통과). 복구 clean |
|
||||
| 14-R5 | `check:registries` | `requests/14-R5.diff`(참조 기능 `authProfileId` → `NOTICE_NOPE`) | 1103/14-06 | `registries-rc=1`. 원인(`unknown authProfileId NOTICE_NOPE`)이 든 load 실패 두 줄뿐, `removed` 줄 없음. 복구 clean |
|
||||
|
||||
요청하지 않은 것과 이유: 1103/14-03 검증(6.1절 경로 변이)은 검사기 코드와 `documentation-readiness.test.ts:119`로 충분하다. 1103/14-04 재실행은 오케스트레이터 FE-GATE-020의 `sample-removal.xml` `documentation` 항목이 대신한다. 예제 기능 제거 드릴은 약 5~10분이라 14-R1로 대신했다. 대조 실행은 오케스트레이터 게이트 로그(`gates/verify_documentation*.log`, `gates/test_unit.log`, `merge-48/FE-GATE-010.log`)를 쓴다.
|
||||
|
||||
## 7. 새 발견 요약
|
||||
|
||||
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|
||||
|---|---|---|---|---|
|
||||
| 14-01 | Medium·P2 | 확인된 결함 | CHANGELOG 6단계대로 예제 기능을 지우면 문서 검사(FE-GATE-005 포함)와 안내한 드릴이 실패하고, `PRODUCT.md`는 지울 수 없다고 적는다 | `docs/architecture/starter-experience.md:105-111`, `CHANGELOG.md:103`, `tests/unit/hosting-probe.test.ts:248`, `PRODUCT.md:33` |
|
||||
| 14-02 | Low·P2 | 확인된 결함 | 매뉴얼 04 §3.2의 제품 설정 키 예시에 `defaultValue`가 없어 `check:types`·`test:unit`이 실패한다 | `docs/manual/04-paired-backend-session.md:127-130`, `src/contracts/env.ts:37-42` |
|
||||
| 14-03 | Low·P3 | 구조적 위험 | 참조 기능 경로 26줄을 백틱에서 빼 문서 검사 밖으로 냈다 | `scripts/verify-documentation-readiness.ts:294-300`, `CHANGELOG.md:225`, `docs/manual/01-add-a-feature.md:8` |
|
||||
@@ -0,0 +1,299 @@
|
||||
# 영역 15 — 성능 실측·최적화
|
||||
|
||||
> 검토일 2026-11-05 · 기준 `8a44226`(`fix/maturity-review-2026-11-03`) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
|
||||
> 경로: `vite.config.ts`, `config/performance/budgets.json`, `config/scale/feature-shape-{ceilings,growth}.json`, `scripts/check-bundle.ts`, `scripts/lib/{performance-budgets,classify-vite-bundle,lab-performance}.ts`, `scripts/scale/measure-feature-shape-growth.ts`, `scripts/test-performance.ts`, `tests/unit/feature-shape-growth.test.ts`, 빌드 산출물과 `artifacts/performance/{bundle,lab}.json`(desktop에서만 빌드). 12 px 조사에 필요한 만큼 `index.html`, `src/bootstrap/main.tsx`, `src/presentation/{pages/home-page.tsx,layouts/app-shell.tsx,routes/app-router.tsx,examples/platform-overview-page.tsx}`, `src/presentation/styles/theme/{base,shell,pages}.css`, `tests/browser-capabilities/browser-files.spec.ts`도 읽었다.
|
||||
> 깊게 본 관점: 14, 10, 21, 13
|
||||
> 렌즈: 지난 라운드 15-01~15-07 수정이 완료 기준까지 갔는가, 수정이 예산·상한·허용 오차를 느슨하게 했는가, 기능 하나를 더하면 예산이 얼마나 남는가, 1103/11-10의 12 px 늦은 성장이 제품의 layout shift인가, lab이 그 순간을 재는가
|
||||
> 영역 판정(35.8): **조건부 사용 가능.** 번들 게이트(FE-GATE-012)와 lab 게이트(FE-GATE-026)가 이 커밋에서 통과한다. 지난 라운드의 "release 단계 사용 보류"(1103/15-01)는 풀린다. 조건은 둘이다. (1) 초기 JS 여유가 1,873 B라 `--with-create` 기능 하나(976 B)를 넣으면 897 B가 남는다. 둘째 기능 전에 다운스트림이 예산을 정해야 한다. (2) lab은 플랫폼 화면 하나의 클릭 진입만 잰다. 기능 라우트 첫 진입은 같은 lab 조건에서 406 ms로 대상 화면(148 ms)의 2.7배인데 어느 게이트도 재지 않는다(15-04). lab CLS는 `/` 첫 화면만 보고, 스크롤바를 숨긴 채 잰다(15-01, 15-05).
|
||||
|
||||
## 0. 결론
|
||||
|
||||
- **지난 발견 7건: 고쳐짐 6(15-01, 15-03~15-07), 일부 1(15-02).** 15-02는 `CHANGELOG.md:107`·`:216`이 초기 파일 예산을 26개로 적어 남았다(실제 32). 이월은 1101/15-01(여유가 작다)·1101/15-03(CSS·라우트 합 예산)·1101/15-04(테스트 시간)·0929/11-04(lab 부하 가드)가 남음이다. 틀린 발견은 없다.
|
||||
- **lab 게이트가 통과한다.** `test:performance -- --runs=5`(15-lab): 상호작용 중앙값 146 ms(표본 155·146·143·148·146), LCP 2,032 ms, CLS 0. 부하 6.06 → 5.01, i5-10400F. 플랫폼 구성 화면의 제목은 실행부 표보다 300 ms(lab 조건), 1.2초(Fast 3G) 먼저 나온다(15-platform-shift). 기능 하나를 더해도 154 ms로 통과한다(15-feature).
|
||||
- **번들: 202,927 / 204,800 B(99.1%), 초기 파일 26 / 32개.** 기록(`feature-shape-ceilings.json:42-43`)과 바이트까지 같다. `create:feature --with-create --keyed` 기능 하나(새 context)가 +976 B를 쓰고 897 B가 남는다. 파일 수는 26 그대로다. 파일 상한 25 → 26 → 32는 근거가 있고, 템플릿 자신의 파일 수는 기록의 `files`가 정확히 막으므로 약해진 검사가 아니다(2.1절). 이 영역 diff에서 느슨해진 단언·skip·상한은 찾지 못했다. 단 기록 대조의 허용 오차 1%(2,029 B)가 남은 여유보다 크다(15-02).
|
||||
- **12 px 늦은 성장은 라우트 로딩 화면(280 px)이 홈 화면(660 px)으로 바뀌는 순간이다.** 앱 셸의 최소 높이(본문 행 648 px)를 홈 내용이 12 px 넘는다. dev server만이 아니라 `vite preview` 제품 빌드에서도, chromium·firefox·webkit 모두에서 같은 값으로 난다. **스크롤바를 숨긴 조건(게이트와 같은 조건)에서는 layout shift가 아니다.** 화면에 있던 요소는 움직이지 않고, Chromium `layout-shift`는 preview 8회 모두 0건이다. lab은 이 순간(lab 조건 약 2.0초)을 networkidle(약 2.25초) 전에 관찰 구간 안에서 본다. **다만 실제 스크롤바를 켜면 작은 shift가 된다.** 창이 홈 내용(732 px)보다 낮으면(1280×720, 1366×657) 이 순간 세로 스크롤바가 생겨 너비가 15 px 줄고, header 오른쪽 세션 영역이 15 px 왼쪽으로 밀린다. CLS 0.00022~0.00023, 12회 모두. 1920×960은 0이다(15-R2). 게이트의 Playwright는 모두 스크롤바를 숨겨 이것을 못 본다. 새 발견 15-05(2.2절).
|
||||
- **dev server만의 shift가 하나 있다.** dev chromium에서 부팅 셸이 스타일 없이 그려졌다가 CSS가 들어오며 0.00625 shift가 난다(JS가 `theme.css`를 넣음). 제품 빌드는 0이다.
|
||||
- **새 15-01(Low·P3).** lab 대상 화면은 제목을 그린 뒤 약 30~100 ms에 릴리스 신원 칸이 1칸 → 4칸이 되며 아래 내용을 21 px 민다(shift 0.00461). lab은 클릭 뒤 500 ms 안이라 CLS에서 빼고 0을 낸다. deep link 8회와 Fast 3G 클릭 3회에서는 CLS에 들어간다. lab은 `/`만 직접 열므로 다른 라우트의 CLS는 어느 게이트도 보지 않는다.
|
||||
- **새 15-04(Low·P2).** lab은 플랫폼 화면 하나만 잰다. 같은 시계로 기능 라우트(`EXAMPLES_UI`)를 재면 중앙값 406 ms(403~410)이고, 대상 화면은 148 ms(144~150)다(15-R1). 기능 라우트는 context 라우트 모듈을 받은 뒤 페이지 청크를 받는 두 번의 요청 묶음을 거친다. 1103/15-01이 플랫폼 화면에서 없앤 모양이 기능 라우트에는 남아 있고, 어느 게이트도 보지 않는다.
|
||||
- **새 15-02·15-03·15-05(Low·P3).** 기록 대조 허용 오차가 여유보다 크다(15-02). 측정용 빌드 입력 목록 두 벌(15-03, 지난 README 14.7의 남은 문제). 홈 첫 렌더의 스크롤바 shift를 lab이 못 본다(15-05).
|
||||
- 새 발견: Low 5. P2 1 · P3 4. 확인된 결함 2 · 구조적 위험 3.
|
||||
|
||||
## 1. 범위 (36.1)
|
||||
|
||||
| 항목 | 기록 |
|
||||
|---|---|
|
||||
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` 영역 15(성능 실측·최적화) |
|
||||
| 커밋·작업 상태·확인 시점 | `8a4422624e81e5d13a3809e212e826ff75aac62b`. 노트북 worktree(HEAD = 기준, 추적 파일 변경 없음, untracked `AGENTS.md`는 무시)에서 읽기만 했다. 실행은 desktop checkout에서 공유 잠금 helper(`/tmp/claude-gates/r4/exp.sh`)로만 했다. 측정 스크립트는 helper의 변이 단계에서 `scripts/r4-15-*.mjs`로 복사했고 helper가 끝에 지웠다(모든 실행 `restored: clean at 8a442262`). 2026-11-05 19:30~20:40. 19:48에 helper가 닫혀(BRIEF-2) 직접 실행은 4개만 돌았다. 나머지 둘은 배치 요청 15-R1·15-R2(`scratchpad/r4/requests/15.md`)로 넘겼고, 오케스트레이터가 20:09~20:11에 돌렸다(둘 다 rc 0, restore clean) |
|
||||
| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음. 운영 서빙은 HTTP/2 이상이 전제다(`config/hosting/cache-policy.json:4`, 13-02) |
|
||||
| 필수 요구와 규모·운영 목표 | `config/performance/budgets.json:3-12`: 초기 JS 204,800 gzip B, 초기 JS 파일 32개, lazy 청크 파일당 122,880 B, lab LCP 2,500 ms·CLS 0.1·이름 붙은 상호작용 200 ms. 기능 하나 +1 KiB·context 하나 +512 B(`tests/unit/feature-shape-growth.test.ts:157-160`). field p75는 표본 기준이 미정이라 설계대로 `FAIL_UNVERIFIED` |
|
||||
| 실행 환경 | desktop: Intel Core i5-10400F(논리 CPU 12), Node v24.14.0, Playwright 1.62.0, Chromium 151.0.7922.34, Playwright 번들 Firefox·WebKit. 부하(1분 loadavg)는 6절에 실행마다 적었다(1.5~6.5). desktop 실행: `15-lab`, `15-growth`, `15-feature`, `15-platform-shift`(직접), `15-R1`(기능 라우트 진입), `15-R2`(실제 스크롤바)(오케스트레이터 배치) |
|
||||
| 읽은 코드·구성 범위 | 머리말 경로. `git diff e40684b..8a44226`로 이 영역 커밋 16개(`d549ceb`, `46dfe23`, `af6d0a9`, `9f9e459`, `c9e7bab`, `1b8cb12`, `f887817`, `2fef27d`, `7f9a515`, `799ab7f`, `e440ece`, `c15345c`, `2c2d459`과 합친 커밋)를 읽었다. `config/ci/gates.json`의 FE-GATE-005·012·026과 stage, `tests/unit/{check-bundle-output,build-environment-bundle,product-feature-selection-build}.test.ts`, `docs/operations/performance-evidence.md`, `docs/architecture/static-delivery.md:43-58`, `CHANGELOG.md` 미출시 절의 예산 문장 |
|
||||
| 수행한 테스트·실험 | 6절. 요약: 기준 빌드 + `check:bundle` + `test:performance -- --runs=5`(15-lab). `create:feature bulletin-feature --with-create --keyed` 뒤 같은 세 단계(15-feature). 홈 첫 화면의 높이·크기 변화와 layout shift를 dev server와 `vite preview`, 세 엔진에서 추적(15-growth). lab 대상 화면이 제목 뒤에 채워질 때의 layout shift(15-platform-shift). lab과 같은 시계로 기능 라우트 첫 진입(15-R1). 실제 스크롤바를 켠 Chromium에서 첫 화면 shift(15-R2). 오케스트레이터 게이트 로그(`desktop:/tmp/claude-gates/r4/gates/test_unit.log`)에서 이 영역 테스트 결과와 시간을 읽었다 |
|
||||
| 확인하지 못한 범위·이유 | 5절 |
|
||||
| 이전 리뷰와 비교 가능한 범위 | `docs/reviews/2026-11-03-maturity-review/15-performance.md`(기준 `e40684b`)와 그 README 12·13·14절. 지난 수치는 비교에만 썼다. 바이트는 결정적이라 비교한다. 시간은 호스트가 다르다(지난 라운드 영역 측정은 Core Ultra 7 155H, 이번은 i5-10400F). 그래서 lab 시간은 지난 값과 직접 비교하지 않는다 |
|
||||
|
||||
## 2. 지난 발견 재확인
|
||||
|
||||
README 14.4는 15-02~15-07을 "고침"으로 적는다. 주장으로만 읽고 현재 코드와 이번 실행으로 다시 판정했다.
|
||||
|
||||
| 지난 ID | 내용 | 상태 | 근거 |
|
||||
|---|---|---|---|
|
||||
| 1103/15-01 | lab 게이트 FE-GATE-026이 실패한다. 측정 화면의 route module이 모든 기능 실행부를 기다린 뒤 그린다 | **고쳐짐** | route module이 페이지를 바로 돌려준다(`src/presentation/examples/platform-overview-page.tsx:662-664`). 실행부가 있어야 아는 칸만 Suspense 두 곳 뒤에서 채운다(`:468-480`, `:526-528`). 조립 모듈도 dynamic import다(`:641-659`). 15-lab: **PASS**, 상호작용 중앙값 146 ms(표본 155·146·143·148·146), LCP 2,032 ms, CLS 0(부하 6.06 → 5.01). 기능 하나를 더한 15-feature도 PASS 154 ms(147~158). 제목이 실행부를 기다리지 않는다(완료 기준 둘째): 15-platform-shift에서 클릭 → 제목 145~150 ms, 클릭 → 오퍼레이션 표 446~451 ms(lab 조건). Fast 3G에서는 674~684 ms와 1,873~1,885 ms다. 남은 것: FE-GATE-026은 여전히 release stage에만 있다(`config/ci/gates.json:2267`). 이번 라운드에서 `d99301b` 대조 A/B는 하지 않았다(수정 커밋 `d549ceb` 본문의 A/B: `d99301b` 107·106 ms, 수정 136·134 ms) |
|
||||
| 1103/15-02 | 성능 기준선 숫자가 현재 빌드와 다르고 같은 파일 안에서도 다르다 | **일부** | 기록은 `config/scale/feature-shape-ceilings.json:41-46` 한 곳이다. 15-lab 빌드는 202,927 B·26개로 기록과 바이트까지 같다. `feature-shape-growth.test.ts:161-165`가 빌드와 대조하고, `performance-evidence.md:22-38`·`static-delivery.md:43-46`은 숫자 대신 그 칸을 가리킨다. **남은 것:** `CHANGELOG.md:107`(BREAKING 이행 7번)과 `:216`이 "예산은 gzip 204,800 B와 초기 파일 26개"라고 적는다. 상한은 32다(`budgets.json:5`, `2fef27d`가 올리며 CHANGELOG를 고치지 않았다). `performance-evidence.md:170-171`도 "템플릿 그대로의 수(26)"를 손으로 적는다(지금은 맞다). 완료 기준 "문서·JSON에 서로 다른 기준선이 없다"를 채우지 못한다. 기록 대조의 허용 오차는 새 발견 15-02 |
|
||||
| 1103/15-03 | 예산을 넘으면 `check:bundle`이 무엇이 얼마나 넘었는지 말하지 않는다 | **고쳐짐** | 예산 실패와 manifest 무결성 실패를 다른 문장으로 쓴다(`scripts/check-bundle.ts:120-143`). 넘은 한도마다 측정값·한도·초과량을 한 줄로 쓴다(`scripts/lib/performance-budgets.ts:44-63`). `tests/unit/check-bundle-output.test.ts:80-126`이 초기 바이트·lazy·파일 수·무결성 네 경우의 stderr를 본다. 이번에 넘는 빌드를 직접 만들지는 않았다(E1 + 테스트 존재) |
|
||||
| 1103/15-04 | 기능당 1 KiB 상한 여유가 40 B이고 context 비용이 섞였다 | **고쳐짐** | 복사본 0·1·2개를 재서 기능 하나와 context 하나를 나눈다(`scripts/scale/measure-feature-shape-growth.ts:214-225`). 기능 1 KiB·context 512 B로 따로 막고 실패 메시지에 잰 값을 넣는다(`feature-shape-growth.test.ts:157-160`). 기록 768 B·233 B라 여유는 256 B·279 B다. 테스트 시간 상한 120 → 180초(`:166`)는 빌드가 2번에서 3번이 된 만큼이다. 약해진 검사로 보지 않는다 |
|
||||
| 1103/15-05 | 초기 JS 파일 수 상한이 없고 HTTP/2 전제를 확인하지 않는다 | **고쳐짐** | `budgets.json:5` `initialJsFiles` 32. `check-bundle.ts:52`가 세고 자가 검사 fixture가 있다(`:86-97`). HTTP/2 부분은 13-02로 합쳐졌고 production probe가 ALPN을 본다(`scripts/lib/hosting-probe.ts:233-249`, 영역 13 판정). 상한 변경의 근거는 2.1절 |
|
||||
| 1103/15-06 | build id만 바뀌어도 초기 JS의 49.4%가 캐시에서 버려진다 | **고쳐짐** | react-dom·scheduler 그룹(`vite.config.ts:235-239`). 15-lab 빌드에서 `react-dom-CQa5bBdz.js` 56,515 B가 따로 있다. 코드가 바뀐 15-feature 빌드에서도 같은 이름이다. `tests/unit/build-environment-bundle.test.ts:84-91`이 build id만 다른 두 빌드에서 이름이 같은지 본다. 커밋이 적은 "바뀌는 초기 JS 44,297 B(22.0%)"는 다시 재지 않았다(두 build id 비교를 하지 않음) |
|
||||
| 1103/15-07 | react-router 개발 빌드가 운영 번들에 들어간다 | **고쳐짐** | build일 때만 `react-router`·`react-router/dom`을 같은 패키지의 `dist/production`으로 보낸다. 파일이 없으면 빌드를 멈춘다(`vite.config.ts:155-170`, `:180`). `build-environment-bundle.test.ts:96-100`이 개발 경고 문구가 없는지 본다. 라우터 청크 30,767 → 30,157 B(15-lab `chunk-3WDNQUW5`). dev server와 capability e2e는 개발 빌드를 그대로 쓴다(의도, `:179`) |
|
||||
| 13-02 (15-05 뒷부분이 합쳐짐) | HTTP/2·압축 전제가 호스팅 계약과 probe에 없다 | 영역 13 | 위 15-05 행. 이 영역은 상한 32의 근거로만 썼다 |
|
||||
| 1101/15-01 (지난 문서 "남음: 여유가 작다") | 초기 JS 여유가 작다 | **남음** | 여유 1,873 B(15-lab). 지난 라운드 2,952 B보다 1,079 B 줄었다. 그사이 1103/15-06·15-07 수정은 바이트를 줄였고(−305 B, −613 B, `af6d0a9`·`9f9e459` 본문), 1103 조치 브랜치 열 개가 합쳐지며 늘었다(`f887817` 본문). `--with-create` 기능 하나를 더하면 897 B가 남는다(2.1절) |
|
||||
| 1101/15-03 | 예산이 CSS를 빼고, lazy는 파일 단위만 본다 | **남음** | `check-bundle.ts:37-45`는 JS만 센다. `performance-evidence.md:68`이 그렇게 적는다. CSS 1개 8,791 B gzip(15-lab, 지난 8,766 B). README 14.4 마지막 단락도 남겼다고 적는다. 라우트 진입 하나가 받는 lazy 합계를 보는 검사도 없다. lazy는 기능 하나로 27 → 39파일, 38,880 → 46,552 B가 됐다(15-feature). 라우트 하나의 요청(15-R1, lab 조건): 플랫폼 구성 화면은 제목 전 4파일 7,037 B, 제목 뒤 6파일. 기능 라우트 `EXAMPLES_UI`는 제목 전 6파일 8,199 B다. 이 합을 보는 예산은 없다 |
|
||||
| 1101/15-04 (+1101 T1·T2·T4) | 빠른 테스트 계층의 시간을 프로세스 생성과 실제 대기가 정한다 | **남음** | `tests/setup.ts:1-2`는 여전히 모든 파일에 jest-dom·RTL을 싣는다. `tests/unit/service-worker-runtime.test.ts:2006-2022`는 여전히 진짜 시간으로 기다린다(상한 10초). FE-GATE-005는 여전히 `test-unit`과 `test-coverage`를 둘 다 돈다(`config/ci/gates.json` FE-GATE-005 `commandIds`). 시간은 오케스트레이터 `test:unit`(로컬 env, 부하 3.24) 로그로만 봤다: 194파일 2,883건 22.6초, 파일마다 도는 setup의 합 44초, 가장 느린 파일 `documentation-readiness` 17.0초·`product-extension-typecheck` 11.0초(6절). 자식 프로세스를 띄우는 파일의 비율은 다시 재지 않았다 |
|
||||
| 0929/11-04 | lab 판정이 호스트 부하로 뒤집힌다 | **코드 남음** | `scripts/test-performance.ts:175`, `:188-191`은 부하를 기록만 한다. 이번 두 lab 실행은 부하 2~6에서 표본 범위가 12 ms 안이었다. 판정이 흔들릴 조건은 재지 않았다 |
|
||||
| 0929/11-05 | 기능 규모 기준선에 소스 커밋이 없다 | **고쳐짐**(필드) | `config/scale/feature-shape-growth.json:16`. 그 값(203,816 B)은 그 커밋의 측정 기록이고, 지금 기준선은 15-02 수정으로 `feature-shape-ceilings.json`의 `initialJavascript`가 맡는다 |
|
||||
| README 14.7 "`BUILD_INPUTS` 두 벌" | 초기 JS 측정용 빌드 입력 목록이 두 파일에 있다 | **남음** → 새 발견 15-03 | `scripts/scale/measure-feature-shape-growth.ts:40-49`와 `tests/unit/product-feature-selection-build.test.ts:22-31`이 같은 8줄이다. 지난 라운드에는 발견 ID가 없었다 |
|
||||
|
||||
### 2.1 예산 변경의 근거와 남은 여유
|
||||
|
||||
| 시점 | 초기 JS gzip B | 초기 파일 / 상한 | 근거 |
|
||||
|---|---:|---|---|
|
||||
| `e40684b`(지난 라운드) | 201,848 | 25 / 없음 | 지난 문서 6절 |
|
||||
| `46dfe23` | — | 25 / **25** | 15-05. 상한을 그 브랜치의 수로 뒀다 |
|
||||
| `1b8cb12` | — | 26 / **26** | 15-01 수정이 조립 모듈을 dynamic import로 바꾸자, 그 모듈과 초기 그래프가 함께 쓰는 `installed-product-manifest`가 따로 떨어졌다. 15-lab 빌드에도 `installed-product-manifest-*.js` 199 B가 초기 파일로 있다. 근거가 맞다 |
|
||||
| `2fef27d` | — | 26 / **32** | 매뉴얼 검색 폼 예제를 따른 기능 하나가 공유 청크 하나를 떨어뜨려 27 > 26이 됐다(README 14.6 X2 #4) |
|
||||
| `8a44226`(15-lab) | **202,927** / 204,800 | **26** / 32 | 여유 1,873 B |
|
||||
| + `create:feature bulletin-feature --with-create --keyed`(15-feature, 새 context) | **203,903** / 204,800 | **26** / 32 | +976 B, 여유 **897 B**. lazy 27 → 39파일, 38,880 → 46,552 B |
|
||||
|
||||
- **26 → 32는 약해진 검사가 아니다.** 템플릿 자신의 파일 수는 기록의 `files`가 정확히(허용 오차 0) 막는다(`measure-feature-shape-growth.ts:238-243`). 템플릿 변경이 초기 파일을 하나라도 늘리면 `test:unit`이 실패하고, 기록을 다시 쓴 diff에 남는다. 32의 여유 6은 다운스트림 기능이 공유 청크를 떨어뜨릴 때만 쓰인다. HTTP/2가 production probe로 강제되므로(13-02) 파일 하나의 비용은 작다(지난 라운드 측정). 바이트 예산 204,800 B는 그대로다.
|
||||
- **기능 하나를 더하면 거의 다 쓴다.** `--with-create` 기능 하나(새 context)가 976 B를 쓴다. 기록의 기능 768 B + context 233 B = 1,001 B와 비슷하다. 남은 897 B로는 같은 context에 기능 하나(768 B 안팎)가 더 들어갈 수도 있고, 새 context면 넘는다(둘째 기능은 재지 않았다). CHANGELOG의 운영 의존성 advisory 항목은 zod를 고치는 버전이 초기 JS를 약 7 KB 늘린다고 적는다(`CHANGELOG.md:271`, 이번에 재지 않음). 그 갱신은 지금 예산으로는 들어가지 않는다(13-03 결정 대기).
|
||||
- 기능을 더해도 초기 파일 수는 26 그대로다. 생성 기능의 지연 페이지는 공유 청크를 떨어뜨리지 않았다. lab도 PASS(154 ms)다.
|
||||
|
||||
### 2.2 12 px 늦은 성장(1103/11-10) — 무엇이 자라는가
|
||||
|
||||
**결론: 홈 화면이 라우트 로딩 화면을 대신 그리는 순간이다. 제품 빌드에서도, 세 엔진 모두에서 같은 12 px로 난다. 스크롤바를 숨긴 조건에서는 layout shift가 아니다(Chromium CLS 0). 실제 스크롤바가 있으면 그 순간 스크롤바가 생겨 header가 15 px 밀리는 작은 shift(CLS 0.0002)가 된다(15-05).** dev server만의 현상이 아니다. 다만 dev에서는 load 이벤트와 그 순간의 간격이 엔진마다 달라 firefox에서 클릭과 겹쳤다.
|
||||
|
||||
흐름은 이렇다(15-growth, 1280×720, 세 엔진 같은 값).
|
||||
|
||||
```
|
||||
index.html 부팅 셸 "불러오는 중"(#root 안 192 px)
|
||||
→ load 이벤트 (entry가 앱 그래프를 dynamic import하므로 앱을 기다리지 않는다, src/bootstrap/main.tsx:14)
|
||||
→ AppShell + RouteLoadingSurface(div.ui-page.route-loading, 280 px) 문서 720 px
|
||||
→ HomePage(section.ui-page, 660 px)가 로딩 화면을 대신한다 문서 732 px
|
||||
```
|
||||
|
||||
- 왜 12 px인가. `.app-shell`은 `min-height: 100vh`이고 header 4.5rem, 본문 행은 sidebar 높이 `calc(100vh - 4.5rem)`으로 648 px다(`src/presentation/styles/theme/shell.css:35-43`, `:157-161`). 로딩 화면(280 px)은 그 안에 들어간다. 홈 내용은 660 px라 행이 648 → 660이 되고, 문서가 720 → 732가 된다. 내용은 380 px 늘었지만 문서 밖으로 보이는 것은 12 px다.
|
||||
- 바뀐 요소는 매번 같은 프레임의 9개뿐이다: `html`·`body`·`#root`·`.app-shell` 720 → 732, `main#main-content` 648 → 660, 로딩 화면과 그 자식 4개가 0이 됨. 그 뒤로는 높이가 바뀌는 요소가 없다. 글꼴 교체는 없다(웹 글꼴 없음, `--font-sans`는 시스템 글꼴, `src/presentation/design-system/tokens/semantic.css:33`). 런타임 요약 줄은 "확인하고 있습니다" → "빌드 … · 릴리스 …"로 바뀌지만 한 줄 그대로다. i18n 문구는 부팅 때 이미 있다.
|
||||
- 시각(navigation 시작부터 `performance.now()`, 첫 dev 실행인 warm-up은 뺐다):
|
||||
|
||||
| 실행 | 횟수 | load 이벤트 | 로딩 화면 | 홈 화면(+12 px) |
|
||||
|---|---:|---:|---:|---:|
|
||||
| preview chromium | 5 | 16~22 ms | 95~163 ms | 394~421 ms |
|
||||
| preview firefox | 3 | 38~209 ms | 112~395 ms | 417~704 ms |
|
||||
| preview webkit | 3 | 17~28 ms | 455~473 ms | 697~708 ms |
|
||||
| preview chromium, lab 조건(CPU 4×, 40 ms, 200 KB/s) | 3 | 206~209 ms | 1,721~1,740 ms | 1,995~2,018 ms(networkidle 2,238~2,258 ms) |
|
||||
| dev chromium | 5 | 22~36 ms | 400~414 ms | 691~734 ms |
|
||||
| dev firefox | 3 | **390~411 ms** | 431~453 ms | **732~760 ms** |
|
||||
| dev webkit | 3 | 75~78 ms | 728~741 ms | 965~979 ms |
|
||||
|
||||
- 11-10과 맞춰 보면: capability test는 `goto("/")`(load까지) 뒤에 dev 모듈을 import하고 버튼을 붙여 누른다. dev firefox에서는 load가 400 ms 근처라, 그 뒤 수백 ms 안에 홈이 그려진다. 클릭이 그 창에 걸렸다. chromium dev는 load가 30 ms 근처라 클릭이 홈보다 훨씬 먼저 끝난다. 이것이 firefox에서만 떨어진 이유로 보인다(추론, 클릭 시각은 재지 않았다). body 744 → 756은 문서 720 → 732에 test가 붙인 한 줄(24 px)을 더한 값이다.
|
||||
- **layout shift인가.** 스크롤바를 숨긴 조건(게이트와 같은 조건)에서는 아니다. 화면에 있던 요소가 움직이지 않는다. header·sidebar는 그대로이고, 로딩 화면은 지워지고 홈 내용은 새로 나타난다. Chromium `layout-shift` entry(buffered)는 preview 5회 + lab 조건 3회 모두 0건이다. 문서 아래에 붙인 요소(test의 버튼)만 밀린다. firefox·webkit은 `layout-shift`가 없어 ResizeObserver 추적으로 같은 변화를 확인했다.
|
||||
- dev server에만 있는 것이 하나 있다. dev chromium에서는 실행마다 layout shift 1건(0.00625)이 t = 26~37 ms(warm-up은 224 ms)에 난다. source는 `body`가 (8, 8, 1264×24) → (0, 0, 1280×720)이다. 부팅 셸이 24 px → 192 px가 되는 순간이다(세 엔진 dev 모두). dev는 `theme.css`를 JS 모듈이 넣으므로(`src/bootstrap/main.tsx:1`) 부팅 셸이 스타일 없이 한 번 그려진다. preview는 처음부터 192 px이고 shift가 0건이다. 제품 영향은 없다.
|
||||
- **lab이 이 순간을 재는가.** 잰다. lab은 `networkidle`까지 기다린 뒤 클릭한다(`scripts/test-performance.ts:148-152`). lab 조건에서 홈이 그려지는 시각(약 2.0초)은 networkidle(약 2.25초)보다 앞이다. 그래서 첫 화면의 shift는 lab CLS 관찰 구간 안에 있다. lab CLS 0은 이 순간을 놓친 값이 아니라 shift가 없다는 값이다. 다만 lab이 보지 못하는 것이 셋 있다. (1) headless Chromium은 스크롤바를 숨긴다. 홈이 그려질 때 세로 스크롤바가 생기면 실제 브라우저(일반 스크롤바)에서는 너비가 줄어 header 오른쪽 요소가 가로로 밀릴 수 있다. 15-R2(Chromium, `--hide-scrollbars`를 뺌, 창 셋 × 지연 없음·lab 조건 × 3회)가 확인했다. 1280×720과 1366×657에서는 홈이 그려지는 프레임에 `clientWidth`가 1280 → 1265, 1366 → 1351로 줄고 `div.app-shell__session`이 x 802 → 787(888 → 873)로 밀린다. layout shift 1건, CLS 0.00023·0.00022, 12회 모두 같다. 1920×960은 홈(732 px)이 창 안에 들어가 6회 모두 0이다. lab과 모든 게이트의 Playwright Chromium은 스크롤바를 숨기므로 이것을 못 본다(새 발견 15-05). (2) firefox·webkit에는 lab이 없다. (3) 클릭 뒤 500 ms 안의 shift는 정의상 CLS에서 빠진다(`hadRecentInput`, `:114`). 이 영향은 3절 15-01에서 본다.
|
||||
- **어떤 test·게이트가 첫 화면의 늦은 성장을 잡는가.** CLS가 되는 성장은 lab(release 단계, Chromium, 스크롤바 숨김)만 잡는다. 성장 자체는 사용자에게 해가 없다. 사용자에게 보이는 부분은 스크롤바가 생기며 header가 밀리는 15 px이고, 그것은 어느 게이트도 잡지 않는다(15-05). 해가 된 곳은 앱 흐름 뒤에 요소를 붙인 test였고, 11-10 수정(`browser-files.spec.ts:3-17`, 고정 층)이 그 두 test를 고쳤다. `goto` 뒤 load를 "앱이 그려졌다"로 쓰면 안 된다는 점은 남는다. load는 앱 그래프를 기다리지 않는다(`main.tsx:14`). 첫 화면이 그려졌다는 신호로는 라우트 heading(`h1[data-route-heading]`, 시각 테스트의 `expectRouteHeading`, `tests/visual/platform.visual.spec.ts:13-15`)이 있다. 다른 capability spec이 body에 요소를 붙이지 않는다는 것은 11-10 수정 커밋 본문의 grep 주장이다(이번에 다시 보지 않았다, 영역 11).
|
||||
|
||||
## 3. 이번 발견 (36.3)
|
||||
|
||||
새 발견 5건: Low 5. P2 1 · P3 4. 확인된 결함 2 · 구조적 위험 3. High 이상과 P1은 없다.
|
||||
|
||||
### 15-01 lab 대상 화면이 그린 뒤 릴리스 신원 칸을 늘려 아래 내용을 21 px 민다. lab은 그 shift를 클릭 입력 창 안이라 빼고, `/` 밖의 라우트 CLS는 어느 게이트도 보지 않는다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 14, 21, 10, 5 |
|
||||
| 근거 | 15-platform-shift(preview, Chromium, 1280×720, 16회). 매번 layout shift 1건, 값 0.00461. source는 `section[aria-labelledby=platform-summary-title]`(y 495 → 516)과 `section[platform-release-title] > dl.platform-metric-grid > div.platform-metric > dd`다. 원인: 릴리스 신원 칸은 `getReleaseSummary()`가 effect에서 끝날 때까지 "상태: 런타임 정보를 확인하고 있습니다." 한 칸만 그린다. 끝나면 빌드·릴리스·설정 스키마·다이제스트 네 칸을 hint 줄과 함께 그린다(`src/presentation/examples/platform-overview-page.tsx:378-393`, `:422-454`). hint 한 줄만큼 grid 행이 커지고 그 아래 모든 section이 내려간다. 시각(클릭 기준): 지연 없음 제목 20~26 ms·shift 51~53 ms, lab 조건 제목 145~150 ms·shift 218~223 ms, Fast 3G 제목 674~684 ms·shift 748~754 ms. lab은 클릭 뒤 500 ms 안의 shift를 `hadRecentInput`으로 뺀다(`scripts/test-performance.ts:111-118`). 그래서 lab 조건에서는 CLS 0이다. Fast 3G 클릭(3회)과 deep link(8회, 지연 없음·lab·Fast 3G)는 입력 창 밖이라 CLS 0.00461로 셌다. lab은 `/`를 열고 클릭으로만 들어간다(`:148-152`). 그래서 대상 화면의 CLS는 구조적으로 잴 수 없다. 이 칸은 `c6da0336`(2026-08-01)부터 같다. 15-01 수정(`d549ceb`)이 더한 Suspense 두 곳은 shift를 더하지 않았다(16회 모두 shift 1건뿐, 오퍼레이션 표는 제목 뒤 약 300 ms) |
|
||||
| 발생 조건 | 플랫폼 구성 화면을 직접 열거나 새로 고칠 때. 느린 회선에서 클릭으로 들어갈 때(제목이 클릭 뒤 500 ms보다 늦을 때) |
|
||||
| 영향 | 제목이 보인 뒤 약 30~100 ms에 아래 내용이 21 px 내려간다(지연 없음 약 30 ms, Fast 3G 약 75 ms, lab 조건 약 70~100 ms). CLS 0.0046은 예산 0.1의 4.6%다. 더 큰 영향은 측정 쪽이다. 다운스트림의 화면이 그린 뒤 채워지며 밀어도, 그 화면이 `/`가 아니면 lab CLS는 0을 낸다 |
|
||||
| 심각도·우선순위 | Low · P3 — 값이 작고 예제 화면이다. lab CLS가 `/`만 본다는 점은 기록해 둔다 |
|
||||
| 통제·증거 | 목표 M3(lab이 대상 화면의 CLS를 검출) / 확인 M3(`/` 첫 화면만), 대상 화면 M0 · E3(16회) + E1 |
|
||||
| 확실성과 남은 가정 | Chromium만 쟀다(다른 엔진에는 API가 없다). 실제 스크롤바와 다른 창 크기에서는 재지 않았다. 사용자가 21 px 이동을 알아채는지는 판단하지 않았다 |
|
||||
| 결정의 근거 | 적용 제외 — 칸 수를 미리 맞추는 표시 결함이다. lab 측정 범위는 아래 대안 비교에 적었다 |
|
||||
| 이해 비용 | lab이 CLS 0을 내니 화면을 고친 사람은 shift가 없다고 믿는다. 클릭 뒤 500 ms 규칙을 알아야 0의 뜻을 안다 |
|
||||
| 최소 개선 방향 | (1) 릴리스 신원 칸이 처음부터 네 칸 모양(같은 label·hint 줄, 값만 "확인 중")을 그린다. (2) lab이 대상 라우트를 한 번 직접 열어 그 CLS도 `lab.json`에 남긴다 |
|
||||
| 대안 비교 | (a) 현상 유지: 값이 작다. 다음 회귀도 lab이 0으로 본다. (b) 네 칸 자리 표시(권장, 화면 한 파일). (c) 릴리스 요약을 동기로 읽음: 부팅 때 이미 가진 값이지만 `getReleaseSummary()`가 비동기 포트 계약이라 포트를 바꿔야 한다. (d) lab deep link 표본 추가: run마다 navigation 하나(lab 조건 약 2초)가 늘고, 같은 종류의 회귀를 잡는다 |
|
||||
| 단순화의 보존 조건 | lab 상호작용 시계(클릭 → 대상 heading)와 중앙값 판정. 릴리스 칸의 `aria-live="polite"`(`:422`) |
|
||||
| 비용·부작용 | (b)는 몇 줄. (d)는 FE-GATE-026 시간 +10~20초 |
|
||||
| 재검토 조건 | field CLS 데이터가 생기면 lab deep link 표본의 필요를 다시 본다 |
|
||||
| 완료 기준 | `/examples/platform`을 직접 열면 layout shift가 0건이다. `lab.json`에 대상 라우트를 직접 연 CLS가 있다 |
|
||||
| 검증 방법 | 15-platform-shift와 같은 방법(`scratchpad/r4/a15/r4-15-platform-shift.mjs`) |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
|
||||
### 15-02 초기 JS 기록 대조의 허용 오차(1%, 2,029 B)가 남은 여유(1,873 B)보다 크다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 구조적 위험 |
|
||||
| 관련 관점 | 9, 21, 5, 13 |
|
||||
| 근거 | `initialJavascriptRecordDrift`는 합계를 1%까지 같다고 본다(`scripts/scale/measure-feature-shape-growth.ts:238-246`). 주석은 그 이유로 "build id로 합계가 수십 바이트 움직인다"를 든다(`:227-233`). 1%는 202,927 B의 2,029 B다. 여유는 1,873 B다(15-lab). 단위 테스트는 기록 201,500 B와 빌드 200,000 B(1,500 B 차이)를 "같음"으로 고정한다(`tests/unit/feature-shape-growth.test.ts:176-178`, `toEqual([])`). build id 차이는 수십 B 규모다. README 14.5 10회차는 `8a3b16a`와 `37c63e8`의 차이를 6 B(커밋 ID)로 적었고, 그 desktop 게이트의 202,975 B와 15-lab의 202,927 B도 48 B 차이다. 문서는 여유를 그 기록으로 계산하라고 한다(`docs/operations/performance-evidence.md:37-38`). `CHANGELOG.md:107`·`:270`은 "여유는 1,873 B"를 적는다 |
|
||||
| 발생 조건 | 템플릿 변경이 초기 JS를 2 KB 안에서 늘리거나 줄이고 기록을 다시 쓰지 않을 때. 이 영역의 기능 하나(+976 B, 0.48%)도 합계 칸만으로는 걸리지 않는다 |
|
||||
| 영향 | 기록과 그것을 인용한 문서가 "여유 1,873 B"라고 말하는 동안 실제 여유는 0일 수 있다. 실제 초과는 FE-GATE-012가 막으므로 배포 피해는 없다. 계획 숫자만 틀린다 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 통제·증거 | 목표 M3(기록이 여유보다 작은 오차로 맞음) / 확인 M3(2,029 B 단위) · E1 + E3(15-lab 바이트) |
|
||||
| 확실성과 남은 가정 | 기능 하나를 더했을 때 `files`·기능·context 칸의 10% 오차로 테스트가 실패하는지는 재지 않았다(이 경우 생성 명령 `Next:` 3번이 기록을 다시 쓰라고 한다). 템플릿 변경이 실제로 2 KB 안에서 기록을 낡게 둔 사례는 아직 없다(지금은 0 B 차이) |
|
||||
| 결정의 근거 | 15-02 수정 커밋 `c9e7bab`이 지난 리뷰의 완료 기준(1%)을 그대로 썼다. 지난 리뷰는 여유가 2,952 B일 때 그 숫자를 정했다. 리뷰어 추론: 여유가 줄면서 1%가 여유보다 커졌다 |
|
||||
| 이해 비용 | 기록을 믿는 사람은 기능 두 개가 더 들어간다고 계산한다 |
|
||||
| 최소 개선 방향 | 합계 허용 오차를 바이트로 둔다. build id 차이(수십 B)를 넘고 기능 하나(약 768 B)보다 작은 값, 예: 256 B |
|
||||
| 대안 비교 | (a) 현상 유지. (b) 바이트 상한(권장, 한 줄). (c) 여유 자체를 기록하고 대조: 예산이 바뀔 때마다 같이 바뀌어 더 낡기 쉽다 |
|
||||
| 단순화의 보존 조건 | CI와 로컬 build id 차이로 테스트가 흔들리지 않는다 |
|
||||
| 비용·부작용 | 초기 JS를 수백 바이트 움직이는 템플릿 변경마다 기록을 다시 써야 한다. 그게 목적이다 |
|
||||
| 재검토 조건 | 예산이나 기준선이 크게 바뀌어 여유가 10 KB 이상이 되면 비율로 돌아가도 된다 |
|
||||
| 완료 기준 | 초기 JS를 300 B 늘린 템플릿 변경에서 기록을 다시 쓰기 전까지 `test:unit`이 실패한다 |
|
||||
| 검증 방법 | 셸 문구 하나를 늘리는 변이로 `feature-shape-growth.test.ts`를 돌린다 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
|
||||
### 15-03 초기 JS 측정용 빌드 입력 목록(`BUILD_INPUTS`)이 두 파일에 같은 내용으로 있다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 구조적 위험 |
|
||||
| 관련 관점 | 9, 23, 3, 10 |
|
||||
| 근거 | `scripts/scale/measure-feature-shape-growth.ts:40-49`와 `tests/unit/product-feature-selection-build.test.ts:22-31`이 같은 8개 경로를 따로 적는다. 둘 다 그 목록을 임시 폴더에 복사하고 vite build를 돈다. `c15345c`가 `vite.config.ts`에 새 import를 더하자 두 목록 모두 낡아 `test:unit` 두 파일과 제거 드릴 셋이 "Could not resolve"로 실패했다. `7f9a515`가 두 곳을 같이 고쳤고, `799ab7f`가 다시 두 곳에서 지웠다. 그 커밋 본문이 합치는 것을 "남은 문제"로 적었고 README 14.7에도 있다. 지난 라운드에는 발견 ID가 없었다 |
|
||||
| 발생 조건 | `vite.config.ts`나 빌드가 읽는 루트 파일이 새 로컬 파일을 import할 때 |
|
||||
| 영향 | 조용히 틀리지는 않는다. 빌드가 실패해 바로 보인다. 다만 고칠 곳이 둘이고, 오류 메시지는 한 곳만 가리킨다. 다운스트림이 vite 설정을 나눌 때 같은 실패를 만난다 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 통제·증거 | 목표 M2(한 곳에 정의) / 확인 M1(커밋 본문의 남은 문제) · E1(두 파일) + 커밋 기록 |
|
||||
| 확실성과 남은 가정 | 지금 두 목록은 같다(갈라진 사본은 아니다). `scripts/lib/removal-fixture.ts:25-39`의 목록은 제거 드릴용 전체 사본이라 목적이 달라 세지 않았다 |
|
||||
| 결정의 근거 | 적용 제외 — 같은 상수를 한 모듈에서 내보내면 되는 중복이다 |
|
||||
| 이해 비용 | vite 설정을 바꾸는 사람이 두 테스트 파일을 찾아야 한다 |
|
||||
| 최소 개선 방향 | `scripts/lib/`에 목록 하나를 두고 두 파일이 import한다 |
|
||||
| 대안 비교 | 적용 제외 |
|
||||
| 단순화의 보존 조건 | 두 테스트가 같은 입력으로 빌드한다. 측정 스크립트가 테스트 파일을 import하지 않는다 |
|
||||
| 비용·부작용 | 파일 하나 |
|
||||
| 재검토 조건 | 적용 제외 |
|
||||
| 완료 기준 | `git grep -n "const BUILD_INPUTS"`가 한 곳이다 |
|
||||
| 검증 방법 | `vite.config.ts`에 로컬 import 하나를 더하는 변이로 한 곳만 고치면 두 테스트가 통과하는지 본다 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규(README 14.7 남은 문제) |
|
||||
|
||||
### 15-04 lab은 플랫폼 화면 하나만 잰다. 기능 라우트 첫 진입(lab 조건 406 ms, 요청 두 묶음)은 어느 게이트도 재지 않는다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 구조적 위험 |
|
||||
| 관련 관점 | 14, 21, 13, 10 |
|
||||
| 근거 | lab 대상은 `ROUTE_REGISTRY.EXAMPLES_PLATFORM` 하나다(`scripts/test-performance.ts:46`). 플랫폼 라우트이고 기능 라우트가 아니다(`src/contracts/routes.ts:33-45`). 15-01 수정 뒤 이 화면은 기능 실행부를 기다리지 않고 그린다(`platform-overview-page.tsx:662-664`). 그래서 lab 수치는 기능이 늘어도 거의 그대로다(15-lab 146 ms → 기능 하나 더한 15-feature 154 ms). 기능 라우트는 처음 들어갈 때 그 기능의 실행부와 페이지 청크를 받는다(`src/features/installed-feature-runtime-registries.ts:23-24` 주석). `CHANGELOG.md:269`(알려진 제한)는 "기능 라우트 첫 진입(실행부 청크, 약 430 ms)은 어느 게이트도 재지 않는다"고 적는다. 15-R1(lab과 같은 시계와 throttle, `vite preview`, 번갈아 5회): 기능 라우트 `EXAMPLES_UI`(`platform-examples-feature`) 중앙값 **406 ms**(403·405·406·406·410), lab 대상 `EXAMPLES_PLATFORM` 148 ms(144·146·148·150·150). 기능 라우트의 요청은 두 묶음이다. 클릭 뒤 39~95 ms에 context 라우트 모듈(`context-routes`, 830 B)과 기능 실행부(177 B), 그 뒤 98~204 ms에 페이지 청크(`ui-gallery-page`, 5,893 B)와 공유 청크 셋(1,299 B)이다. 제목 전 6파일 8,199 B. 첫 묶음이 끝나야 둘째 묶음의 이름을 안다: `ContextRouteGateway`가 effect에서 `routeModule.loadRoutes()`를 기다린 뒤 라우트를 그리고(`src/presentation/routes/app-router.tsx:510-538`), 그때 페이지 lazy 청크를 받는다. 기능 실행부는 첫 묶음에 같이 받도록 이미 맞춰져 있다(`:522-530`). 나머지 약 200 ms는 CPU 4× 조건의 렌더로 보인다(나누어 재지 않음) |
|
||||
| 발생 조건 | 다운스트림의 화면은 모두 기능 라우트다. 템플릿 안에서는 `platform-examples-feature`의 예제 화면과 참조 기능 화면이다 |
|
||||
| 영향 | 템플릿의 유일한 상호작용 예산(200 ms)이 제품 화면을 보지 않는다. 지금 기능 라우트 진입은 그 값의 2배다. 1103/15-01이 플랫폼 화면에서 없앤 "요청 묶음 하나 더"가 기능 라우트에는 구조로 남아 있다. 기능 실행부·페이지가 커지거나 왕복이 더 늘어도 모든 게이트가 통과한다 |
|
||||
| 심각도·우선순위 | Low · P2 — 기능 결함은 아니다. 406 ms는 lab 조건(CPU 4×, 200 KB/s) 값이고, 예산은 이름 붙은 라우트 하나에만 적용되므로 계약 위반도 아니다. CHANGELOG에 알려진 제한으로 적혀 있다(M1). 그러나 제품을 만드는 경로의 성능을 템플릿 게이트가 보지 않으므로 P2다 |
|
||||
| 통제·증거 | 목표 M3(제품 화면 하나 이상을 lab이 잰다) / 확인 M1(CHANGELOG 제한 문장), 게이트 M0 · E3(15-R1, 5회 번갈아) + E1 |
|
||||
| 확실성과 남은 가정 | 기능 라우트 하나(예제 화면)만 쟀다. 생성 기능 목록 라우트는 세션과 백엔드 응답이 필요해 재지 않았다. 406 ms를 왕복·다운로드·렌더로 나누지 않았다. CHANGELOG의 430 ms와 가깝다 |
|
||||
| 결정의 근거 | 기록된 의도: 1103/15-01의 대안 비교는 "lab 대상 라우트 변경"을 회귀를 숨긴다는 이유로 버렸다. 대상을 바꾸지 않고 하나를 더하는 선택은 비교되지 않았다(리뷰어 확인). 리뷰 기록 README 14.7은 이것을 "새 관찰"로만 적었다 |
|
||||
| 이해 비용 | 다운스트림 담당자는 lab PASS를 제품 화면 진입이 200 ms 안이라는 뜻으로 읽기 쉽다 |
|
||||
| 최소 개선 방향 | lab이 이름 붙은 상호작용을 하나 더 잰다. 내비게이션에 있는 첫 기능 라우트(`ROUTE_FEATURE_OWNER`가 있는 것)를 같은 시계로 재고 `lab.json`에 따로 남긴다. 처음에는 기록만 하고, 예산은 값을 본 뒤 정한다. 두 묶음을 하나로 줄이는 것(context 라우트 모듈을 받을 때 그 라우트의 페이지 청크도 같이 받기)은 그다음 별도 결정이다 |
|
||||
| 대안 비교 | (a) 현상 유지 + CHANGELOG의 제한 문장. (b) 기능 라우트 표본 추가(권장): run마다 navigation 하나, FE-GATE-026 +10~15초. (c) 진입한 URL의 페이지 청크를 context 라우트 모듈과 같은 묶음에서 받기: 둘째 묶음(약 100 ms)을 없앨 것으로 보이나 측정 없이는 판단하지 않는다. 라우트 표와 페이지 청크의 대응을 gateway가 알아야 한다. (d) hover·idle 프리페치: 키보드·직접 진입에는 효과가 작다(1103/15-01 대안 비교와 같다). (e) `budgets.json`에 라우트별 예산: 표가 늘고 다운스트림이 채워야 한다 |
|
||||
| 단순화의 보존 조건 | 기존 대상 라우트의 측정과 예산을 그대로 둔다(회귀 비교가 이어진다) |
|
||||
| 비용·부작용 | (b)는 스크립트 수십 줄과 lab 시간 |
|
||||
| 재검토 조건 | field INP·라우트 전환 데이터가 생기면 lab 표본의 필요를 다시 본다 |
|
||||
| 완료 기준 | `lab.json`에 기능 라우트 하나의 클릭 → heading 시간이 표본과 함께 있다 |
|
||||
| 검증 방법 | 15-R1과 같은 방법(`scratchpad/r4/a15/r4-15-route-entry.mjs`). 기능 실행부에 지연 import 하나를 더하는 변이로 lab의 새 값이 느는지 본다 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
|
||||
### 15-05 홈 첫 렌더가 세로 스크롤바를 만들어 header를 15 px 민다. 게이트는 스크롤바를 숨긴 Chromium으로만 재서 보지 못한다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 14, 10, 21 |
|
||||
| 근거 | 2.2절의 12 px 성장(로딩 화면 → 홈, 문서 720 → 732 px)이 원인이다. 15-R2(Chromium 151, `ignoreDefaultArgs: ["--hide-scrollbars"]`, preview, 창 셋 × 지연 없음·lab 조건 × 3회): 1280×720에서 `clientWidth` 1280 → 1265, `div.app-shell__session` x 802 → 787, layout shift 1건 0.00023(6/6). 1366×657에서 1366 → 1351, x 888 → 873, 0.00022(6/6). 1920×960은 홈이 창 안이라 0(6/6). shift 시각은 홈이 그려지는 프레임(지연 없음 400~414 ms, lab 조건 1,997~2,031 ms)과 같다. `html`·`body`에 `scrollbar-gutter`나 `overflow-y` 지정이 없다(`src/presentation/styles/theme/base.css:1-71`). lab은 Playwright 기본 실행이라 스크롤바를 숨긴다(`scripts/test-performance.ts:186`, `chromium.launch()`). 게이트의 다른 Playwright 설정도 같다 |
|
||||
| 발생 조건 | 일반(overlay가 아닌) 스크롤바를 쓰는 브라우저에서 창 높이가 홈 내용(732 px)보다 낮을 때 첫 화면. Windows와 많은 Linux 데스크톱의 기본값이다. 다른 화면도 로딩 화면이 창 안에 들고 내용이 창보다 길면 같다(재지 않음) |
|
||||
| 영향 | 첫 화면이 그려지는 순간 header 오른쪽(테마·언어 선택, 세션 상태, 로그인 버튼)이 15 px 왼쪽으로 움직인다. CLS 0.0002는 예산의 0.2%다. 게이트가 이 종류의 shift를 볼 방법이 없다 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 통제·증거 | 목표 M3(첫 화면 shift를 실제 브라우저 조건으로 검출) / 확인 M0(스크롤바 조건) · E3(18회) |
|
||||
| 확실성과 남은 가정 | Chromium Linux의 15 px 스크롤바만 쟀다. Windows 스크롤바 폭(약 17 px)과 Firefox는 재지 않았다. macOS 기본 overlay 스크롤바에서는 나지 않을 것으로 본다(추론) |
|
||||
| 결정의 근거 | 적용 제외 — 스크롤바 자리를 미리 잡는 CSS 한 줄로 끝나는 표시 결함이다 |
|
||||
| 이해 비용 | 낮다 |
|
||||
| 최소 개선 방향 | `html { scrollbar-gutter: stable; }`(base.css). lab은 스크롤바를 켠 실행(`--hide-scrollbars` 제외)으로 바꾸거나 한 표본을 더한다 |
|
||||
| 대안 비교 | 적용 제외 — 대안(`overflow-y: scroll`)은 항상 스크롤바를 그려 짧은 화면에서도 보인다. 차이가 작아 비교하지 않는다 |
|
||||
| 단순화의 보존 조건 | 적용 제외 |
|
||||
| 비용·부작용 | 스크롤바 폭만큼 오른쪽 여백이 늘 생긴다(내용이 짧아도). 시각 골든(`tests/visual/`)은 스크롤바를 숨긴 실행이라 바뀌지 않을 것으로 본다(미확인) |
|
||||
| 재검토 조건 | 적용 제외 |
|
||||
| 완료 기준 | 15-R2와 같은 실행에서 1280×720·1366×657의 layout shift가 0건이다 |
|
||||
| 검증 방법 | `scratchpad/r4/a15/r4-15-scrollbar.mjs` |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
|
||||
## 4. 28개 관점 판정 (36.2)
|
||||
|
||||
표기: O 충족 / P 부분 충족 / X 미충족 / ? 미검증 / - 적용 제외 / > 다른 영역.
|
||||
|
||||
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | 코드 성숙도 | 일부 적용(성능 스크립트) | M2 / M2 | E1, E2(게이트 로그) | **O** — 판정기(`performance-budgets.ts`)와 CLI가 나뉘고, 실패 출력이 넘은 한도를 말한다. 측정 스크립트들의 이 영역 테스트 6개가 통과한다(`gates/test_unit.log`) |
|
||||
| 2 | 구조적 성숙도 | 일부 적용(청크 구성) | M3 / M3 | E3 | **O** — react-dom 그룹, `feature-declarations`·`feature-platform` 그룹. 생성 기능 하나를 더해도 초기 파일 26개 그대로(15-feature) |
|
||||
| 3 | 변경 용이성 | 적용 | — / — | E3 | **P** — 생성 기능 하나는 예산 수정 없이 들어간다. 둘째는 예산 결정이 필요하다(2.1절). 빌드 입력 목록 두 벌(15-03) |
|
||||
| 4 | 인지 부하 | 적용 | M1 / M1 | E1 | **P** — 기준선이 한 곳(`initialJavascript`)이 됐다. CHANGELOG의 파일 예산 26은 틀렸다(1103/15-02 일부). lab CLS 0의 뜻을 알려면 500 ms 입력 규칙을 알아야 한다(15-01) |
|
||||
| 5 | 위험 가시성 | 적용 | M3 / M2 | E3 | **P** — lab 실패는 고쳐졌지만 여전히 release 단계에서만 돈다. lab CLS가 `/` 밖을 보지 않는다(15-01). 기록 오차가 여유보다 크다(15-02) |
|
||||
| 6 | 실패 성숙도 | 다른 영역(06·09) | — | — | **>** 부트 실패 화면 청크는 react-dom과 분리된 뒤에도 앱 그래프 없이 그려진다는 주장(`af6d0a9` 본문)은 영역 09·13 |
|
||||
| 7 | 운영 성숙도 | 일부 적용 | M2 / M2 | E3 | **P** — `lab.json`에 CPU·부하·표본·클릭 이벤트 길이가 남는다. field는 설계대로 `FAIL_UNVERIFIED` |
|
||||
| 8 | 디버깅 가능성 | 적용 | M2 / M2 | E1, E2 | **O** — `check:bundle`이 측정값·한도·초과량을 쓴다(1103/15-03 고쳐짐). 기능당 비용 실패가 잰 값을 말한다 |
|
||||
| 9 | 유지보수 성숙도 | 적용 | M3 / M2 | E1 | **P** — 기록과 빌드를 대조하지만 오차가 크고(15-02), CHANGELOG 숫자는 손으로 적혀 이미 틀렸다(1103/15-02). 목록 두 벌(15-03) |
|
||||
| 10 | 테스트 성숙도 (깊게) | 적용 | M3 / M3 | E2, E3 | **P** — 이 영역 테스트는 merge에서 돌고 통과한다(feature-shape-growth 7건 5.3초, check-bundle-output 5건, build-environment-bundle 2건). lab은 대상 화면의 CLS를 볼 수 없고(15-01), 기능 라우트를 재지 않으며(15-04), 스크롤바를 숨긴 조건만 잰다(15-05). 빠른 계층 시간은 그대로다: unit 194파일 2,883건 22.6초, 파일 setup 합 44초(1101/15-04 남음) |
|
||||
| 11 | 데이터 성숙도 | 적용 제외 | — | — | **-** 이 영역에 저장 데이터가 없다 |
|
||||
| 12 | 동시성 성숙도 | 다른 영역(03·05) | — | — | **>** |
|
||||
| 13 | 확장성 (깊게) | 적용 | M3 / M3(초기 JS) | E3 | **P** — 생성 기능 하나 +976 B, 파일 증가 0, lazy +12파일. lab 대상 화면은 기능 수와 거의 무관하다(146 → 154 ms). 여유로는 기능 하나 남짓이다 |
|
||||
| 14 | 성능 성숙도 (깊게) | 적용 | M3 / 번들 M3(merge), lab M3(release, `/`와 대상 화면 하나) | E3 | **P** — 초기 JS 99.1%, lab PASS(146 ms, LCP 2,032, CLS 0). 12 px 성장은 shift가 아니다(2.2절). 대상 화면 deep link CLS 0.0046(15-01). 기능 라우트 진입 406 ms, 게이트 없음(15-04). 실제 스크롤바에서 홈 첫 렌더 CLS 0.0002(15-05). CSS 예산 없음(1101/15-03). field 미검증 |
|
||||
| 15 | 보안 성숙도 | 다른 영역(13) | — | — | **>** zod advisory를 고치는 버전이 초기 JS 약 +7 KB라 예산을 넘는다는 주장(`CHANGELOG.md:271`)은 13-03 결정 대기. 이 영역은 재지 않았다 |
|
||||
| 16 | 의존성 성숙도 | 일부 적용 | M2 / M3 | E2, E3 | **O** — react-router 운영 빌드(1103/15-07). 업그레이드로 경로가 바뀌면 빌드가 멈춘다(`vite.config.ts:163-168`) |
|
||||
| 17 | API / Contract 성숙도 | 다른 영역(07) | — | — | **>** |
|
||||
| 18 | 배포 성숙도 | 적용 | M3 / M3 | E3 | **O** — release 단계 lab 게이트가 통과한다. build id만 바뀐 release에서 react-dom 청크 이름이 유지된다(테스트 존재, 바이트 비교는 미검증). HTTP/2 전제는 production probe(13-02, 영역 13) |
|
||||
| 19 | 설정 성숙도 | 적용 | M2 / M2 | E1 | **O** — 예산은 `budgets.json` 한 곳, 기준선은 `feature-shape-ceilings.json` 한 곳 |
|
||||
| 20 | 개발자 경험 (깊게) | 적용 | M2 / M2 | E3 | **P** — 생성 명령이 기록 재작성을 안내한다(`Next:` 3번). 예산 실패 메시지가 원인을 말한다. CHANGELOG 이행 7번의 파일 예산 숫자가 틀렸다 |
|
||||
| 21 | Guardrail 성숙도 | 적용 | M3 / M3(번들 merge), lab은 release만 | E3 | **P** — 상한 25 → 26 → 32는 근거가 있고 템플릿 쪽은 기록의 `files`가 정확히 막는다(2.1절). 기록 오차 1%(15-02), lab의 CLS·라우트·스크롤바 범위(15-01, 15-04, 15-05) |
|
||||
| 22 | 추상화 성숙도 | 다른 영역(16) | — | — | **>** |
|
||||
| 23 | 일관성 | 일부 적용 | — | E1 | **P** — 같은 목록 두 벌(15-03). dev와 build가 다른 라우터 빌드를 쓰는 것은 의도이고 주석이 있다(`vite.config.ts:179`) |
|
||||
| 24 | 네이밍 / 의미 성숙도 | 일부 적용 | — | E3 | **P** — react-router 청크는 여전히 자동 이름(`chunk-3WDNQUW5`)이다. 문서는 "청크 이름으로 판단하지 않는다"고 적는다(`performance-evidence.md:42`) |
|
||||
| 25 | 조직 확장성 | 다른 영역(12) | — | — | **>** |
|
||||
| 26 | Ownership 성숙도 | 다른 영역(14) | — | — | **>** 예산 결정은 다운스트림 몫이라고 문서에 있다(`performance-evidence.md:17-20`) |
|
||||
| 27 | 삭제 가능성 | 다른 영역(14) | — | — | **>** lab 대상이 끌 수 없는 플랫폼 라우트다(09-04 결정 대기) |
|
||||
| 28 | 회복 가능성 | 다른 영역(06) | — | — | **>** |
|
||||
|
||||
## 5. 미검증
|
||||
|
||||
| 범위 | 이유 | 확인 방법 |
|
||||
|---|---|---|
|
||||
| 기능 라우트 진입 406 ms의 구성(왕복·다운로드·렌더) | 15-R1은 합계와 요청 시각만 남긴다 | CDP trace 또는 CPU throttle 없이 다시 잼 |
|
||||
| 생성 기능 라우트의 첫 진입 | 세션과 백엔드 응답이 필요하다 | MSW나 짝 백엔드를 붙인 lab |
|
||||
| 스크롤바 shift의 Firefox·Windows 조건 | 15-R2는 Linux Chromium만이다 | — |
|
||||
| `d99301b`와의 lab A/B | 이번 brief는 lab 1회만 요구한다. 수정 커밋 `d549ceb` 본문의 A/B만 있다 | 지난 라운드 6절 방법 |
|
||||
| build id만 다른 두 빌드의 바뀐 초기 JS(44,297 B 주장) | 두 build id 빌드를 비교하지 않았다. 이름 유지는 테스트가 본다 | `VITE_BUILD_ID`만 다른 두 빌드 |
|
||||
| 예산을 넘는 실제 빌드의 `check:bundle` 출력 | 넘는 빌드를 만들지 않았다. fixture 테스트는 게이트 로그에서 통과 | 기능 둘을 더한 빌드 |
|
||||
| 기능 둘째의 비용과 남는 여유 | 하나만 더했다 | 같은 context·새 context로 하나씩 |
|
||||
| CI env(`CI=true`, CI build id)에서의 lab | 로컬 env로만 돌렸다. merge-48에는 FE-GATE-026이 없다(release 단계) | `CIENV=1` lab 1회 |
|
||||
| firefox·webkit의 lab 수치 | lab은 Chromium만이다. 두 엔진에는 `layout-shift` API도 없다 | — |
|
||||
| 11-10 실패 run의 클릭 시각 | 재현 run을 다시 돌리지 않았다. firefox에서만 겹친 이유는 시각표로 한 추론이다 | 진단 branch의 event 기록에 `performance.now()` 추가 |
|
||||
| 다른 capability spec이 body에 요소를 붙이지 않는다는 주장 | 11-10 수정 커밋 본문의 grep 주장이다. 영역 11 | `git grep "document.body.append" tests/` |
|
||||
| field CLS·INP | 입력이 없다(설계대로 `FAIL_UNVERIFIED`) | — |
|
||||
| 오케스트레이터 merge-48의 FE-GATE-012 결과 | 이 문서를 쓸 때 001~004·020만 끝나 있었다 | `merge-48/FE-GATE-012.log` |
|
||||
|
||||
## 6. 실행 기록
|
||||
|
||||
모든 실행은 desktop에서 helper로 했다. 바이트는 `check:bundle`과 같은 계산이다(`classifyViteJavascript` + Node `gzipSync` 기본 수준). 부하는 1분 loadavg다. 측정 스크립트(`r4-15-*.mjs`)는 리뷰어 scratchpad `r4/a15/`에 있다(커밋하지 않음).
|
||||
|
||||
| 이름 | 명령 | 변이 | rc | 결과 | 잠금 대기 | 부하 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| `15-lab` | `pnpm build` → `pnpm check:bundle` → `r4-15-summary.mjs bundle` → `pnpm test:performance -- --runs=5` → `r4-15-summary.mjs lab` | 측정 스크립트 복사만 | 0(19초) | `Bundle budget: PASS (initial JS 202927 / 204800 gzip bytes, 26 / 32 files)`. lazy 27파일 38,880 B(최대 8,566), CSS 8,791 B. 초기 파일: react-dom 56,515, feature-platform 39,297, boot 39,067, react-router(`chunk-3WDNQUW5`) 30,157, i18n 7,957, server-state-scope-provider 6,171, render-boot-failure 4,280, feature-declarations 3,256, react 3,157, 그 밖 17개 13,070. `Lab performance: PASS, median of 5 (LCP 2032ms, CLS 0, interaction 146ms [143-155])`, 표본 155·146·143·148·146, LCP 2,036·2,032·2,032·2,028·2,020, 클릭 event 16~24 ms. `restored: clean at 8a442262` | 435초 | 시작 6.51, lab 전후 6.06 → 5.01 |
|
||||
| `15-growth` | `pnpm build` → `r4-15-growth-probe.mjs preview 3` → `r4-15-growth-probe.mjs dev 3` | 측정 스크립트 복사만 | 0(111초) | 2.2절. preview: chromium 5회(ResizeObserver 3·무계측 2) + lab 조건 3회, firefox 3회, webkit 3회. dev: 세 엔진 warm-up 1회 + 3회, chromium 무계측 2회. 모든 run에서 문서 720 → 732, 홈이 로딩 화면을 대신하는 프레임 하나. Chromium shift: preview 0건(8회), dev 매번 1건 0.00625(부팅 셸 스타일). 상세 `desktop:/tmp/claude-gates/r4/exp/15-growth-{preview,dev}.json`. `restored: clean at 8a442262` | 453초 | 5.01 → 2.96(preview), 2.75(dev 끝) |
|
||||
| `15-feature` | `pnpm create:feature bulletin-feature --with-create --keyed` → `pnpm build` → `pnpm check:bundle` → 요약 → `pnpm test:performance -- --runs=5` → 요약 | 생성 명령(`git status --short` 9줄) | 0(20초) | `initial JS 203903 / 204800 gzip bytes, 26 / 32 files`(+976 B, 여유 897 B). lazy 39파일 46,552 B. `Lab performance: PASS ... (LCP 2020ms, CLS 0, interaction 154ms [147-158])`. `restored: clean at 8a442262` | 559초 | 2.75, lab 전후 2.69 → 2.16 |
|
||||
| `15-platform-shift` | `pnpm build` → `r4-15-platform-shift.mjs 3` | 측정 스크립트 복사만 | 0(94초) | 15-01 근거. 지연 없음·lab·Fast 3G × 클릭·deep link, 16회 모두 shift 1건 0.00461. 셈에 들어간 것: deep link 8/8, Fast 3G 클릭 3/3, 나머지 클릭 0/5(입력 창). `restored: clean at 8a442262` | 722초 | 6.80 → 2.58 |
|
||||
| `15-R1`(배치, 오케스트레이터) | `pnpm build` → `r4-15-route-entry.mjs 5` | 측정 스크립트 복사만 | 0(43초) | lab 조건, 번갈아 5회. `SUMMARY EXAMPLES_PLATFORM median 148 samples 144,146,148,150,150`, `SUMMARY EXAMPLES_UI median 406 samples 403,405,406,406,410`. 플랫폼: 제목 전 4파일 7,037 B, 제목 뒤 6파일(`installed-feature-runtime-registries` 130 ms~, `feature-runtime`·`reference-*` 233 ms~). 기능 라우트: 39~95 ms `context-routes` 830 B·`feature-runtime` 177 B, 98~204 ms `ui-gallery-page` 5,893 B·공유 셋 1,299 B. restore clean. 처음 요청한 `15-route-entry`는 helper가 닫히며 시작 전에 취소됐다 | 배치 | 3.00 → 2.14 |
|
||||
| `15-R2`(배치, 오케스트레이터) | `r4-15-scrollbar.mjs 3`(15-R1이 만든 `dist/` 재사용, 로그에 `reuse-dist-from-15-R1`) | 측정 스크립트 복사만 | 0(54초) | 15-05 근거. 1280×720 6/6 shift 0.00023, 1366×657 6/6 0.00022, 1920×960 6/6 0. restore clean. 처음 요청한 `15-scrollbar`는 시작 전에 취소됐다 | 배치 | 2.14 → 1.30 |
|
||||
|
||||
오케스트레이터 게이트 결과(인용, 이 문서를 쓸 때 채워지는 중): `gates/summary.txt`에서 `test:unit rc=0 25s load 3.24`. 그 로그의 끝은 194파일 2,883건 통과, Duration 22.61초(setup 합 43.97초, tests 합 130.90초)다. 이 영역 파일: `feature-shape-growth` 7건 5,317 ms, `build-environment-bundle` 2건 3,791 ms, `check-bundle-output` 5건 3,183 ms, `product-feature-selection-build` 1건 1,494 ms, `lab-performance` 5건 977 ms, `performance-budgets` 3건 9 ms. 가장 느린 unit 파일은 `documentation-readiness` 17.0초, `product-extension-typecheck` 11.0초, `ci-workflow-generation` 7.5초, `security-promotion-staging` 6.7초, `service-worker-build-output` 6.3초, `risk-coverage` 6.1초다. `merge-48/summary.txt`는 FE-GATE-020 rc=0 1,156초, 001 rc=0 579초, 002·003 rc=0이었다. FE-GATE-012는 아직 없었다.
|
||||
|
||||
## 7. 새 발견 요약
|
||||
|
||||
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|
||||
|---|---|---|---|---|
|
||||
| 15-01 | Low·P3 | 확인된 결함 | lab 대상 화면이 그린 뒤 릴리스 칸을 늘려 21 px 민다(shift 0.0046). lab은 클릭 입력 창이라 0을 내고 `/` 밖의 CLS는 아무도 보지 않는다 | `src/presentation/examples/platform-overview-page.tsx:422-454`, `scripts/test-performance.ts:111-118`, `:148-152` |
|
||||
| 15-02 | Low·P3 | 구조적 위험 | 초기 JS 기록 대조 허용 오차 1%(2,029 B)가 남은 여유(1,873 B)보다 크다 | `scripts/scale/measure-feature-shape-growth.ts:227-246` |
|
||||
| 15-03 | Low·P3 | 구조적 위험 | 측정용 빌드 입력 목록이 두 파일에 같은 내용으로 있다 | `scripts/scale/measure-feature-shape-growth.ts:40-49`, `tests/unit/product-feature-selection-build.test.ts:22-31` |
|
||||
| 15-04 | Low·P2 | 구조적 위험 | lab은 플랫폼 화면 하나만 잰다. 기능 라우트 첫 진입은 lab 조건 406 ms(요청 두 묶음)인데 어느 게이트도 재지 않는다 | `scripts/test-performance.ts:46`, `src/presentation/routes/app-router.tsx:510-538`, `CHANGELOG.md:269` |
|
||||
| 15-05 | Low·P3 | 확인된 결함 | 홈 첫 렌더가 세로 스크롤바를 만들어 header를 15 px 민다(CLS 0.0002). 게이트는 스크롤바를 숨긴 Chromium이라 못 본다 | `src/presentation/styles/theme/base.css:1-71`, `scripts/test-performance.ts:186` |
|
||||
@@ -0,0 +1,276 @@
|
||||
# 영역 16 — 폴더 구조·리팩토링·기능 개발 패턴
|
||||
|
||||
> 검토일 2026-11-05 · 기준 `8a44226`(`fix/maturity-review-2026-11-03`) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
|
||||
> 경로: repo 구조 전체, `src/features/reference-feature/`, `scripts/create-feature.ts`, `scripts/create-feature-write-slice.ts`, `docs/manual/`, `docs/architecture/`
|
||||
> 깊게 본 관점: 2, 3, 4, 9, 22, 23, 24, 27
|
||||
> 렌즈: 템플릿의 핵심 약속 — 생성 명령과 매뉴얼로 기능을 더하고, 템플릿 소유 파일을 고치지 않고, merge 게이트를 통과한다. 매뉴얼의 예시 이름 그대로 `create:feature invoice-feature --with-create --keyed`(새 context)를 만들었다. 한 번은 지난 라운드 변이를 다시 넣었고(`16-mut`), 한 번은 CI가 생성 기능으로 돌지 않는 단계(브라우저 게이트, 11단계 제거 드릴, 둘째 기능의 예산)를 돌렸다(배치 16-R1).
|
||||
> 영역 판정(35.8): **조건부 사용 가능.** 생성 명령 하나로 만든 쓰기 기능이 손 수정 없이 merge 명령을 통과한다. 비브라우저 명령은 오케스트레이터 merge-48 FE-GATE-020(`feature scaffold: PASS (77 checks)`), 브라우저 게이트는 16-R1(FE-GATE-008·009 rc=0, workflow env)에서 봤다. 지난 라운드 16 발견 9건 중 6건이 고쳐졌고 3건이 일부 남았다. 조건은 다섯이다. (1) 생성 명령이 다시 쓴 `public/release-manifest.json`과(참조 기능이 있는 동안) 초기 JS 기록을 기능과 함께 커밋한다. 병렬 기능 브랜치는 이 줄에서 충돌한다(16-01). (2) 매뉴얼 예시 이름(`invoice-feature`, `notice-feature`)이나 템플릿 테스트에 나오는 이름(`orders-feature`, `shop-feature` 등)으로 기능을 만들지 않는다. 11단계 제거 드릴이 템플릿 테스트의 글자를 잔여로 잡아 실패한다(16-04). (3) 쓰기 기능 셋째부터는 예산 결정이 먼저다. 둘을 더하면 초기 JS 여유가 277 B다(16-R1, 1101/15-01). (4) 템플릿 변경이 생성 기능의 브라우저 경로를 깨도 CI는 모른다(16-03). (5) 뮤테이션 정책 ID는 `commandMutationIdentity`로 받고, 읽기만 있는 계약 기여에서는 생성된 gateway 테스트를 지우지 않는다(1103/16-05·16-01 일부).
|
||||
|
||||
## 0. 결론
|
||||
|
||||
- **지난 16 발견 9건: 고쳐짐 6, 일부 3.** 고쳐짐: 16-02(제품 기능 제거 드릴), 16-03 앞부분(접근성 spec 기능별 수정), 16-04(스키마 메타 설명 칸), 16-07(KEYED 쓰기 값), 16-08(낡은 문장 다섯), 16-09(dev server 부팅). 일부: 16-01(Envelope 누락), 16-05(뮤테이션 ID), 16-06(읽지 않는 칸). 틀린 발견은 없다. 1101·0929 이월 셋(16-05, 16-06, 12-03)은 그대로 남았다.
|
||||
- **변이로 확인한 것(`16-mut`, restored clean).** 생성 기능에서 `responseEnvelope` 줄 하나를 지우자 계약 조립이 operation 이름과 고칠 방법을 말하며 거절했다. `check:registries` rc=1, 기능 테스트 4파일 실패. 세 줄을 다 지워도 쓰기의 `refusedBeforeWrite`가 Envelope를 요구해 조립이 거절했다. `check:types`는 rc=0이었다. 스키마 메타 세 변이(`direction`, `boundary`, `unknownFieldPolicy`)는 각각 `tests/unit/schema-metadata-policy.test.ts`가 잡았다. 셋 다 `check:registries`는 통과했다.
|
||||
- **매뉴얼을 글자 그대로 따르면 마지막 단계에서 막힌다(16-04, Low·P2).** `create:feature invoice-feature`(01:94) 뒤 11단계 `test:sample-removal -- --feature=invoice-feature`(01:626)가 rc=1로 끝났다(16-R1, 198초). 타입·테스트·커버리지·CI 계약·빌드 검사는 모두 통과했다. 실패는 잔여 검사 하나였다: `fixture-id-residue: residue: tests/unit/create-feature.test.ts`. 그 템플릿 테스트가 예시 ID `invoice-feature`를 53번 쓴다. 잔여 검사는 기능 ID를 `src`·`tests` 전체에서 대소문자 무시 부분 문자열로 찾는다(`scripts/test-sample-removal.ts:113-120`, `:417-425`). 오류 안내는 "그 파일을 고친다"다(`docs/manual/reference/errors.md:197`). 그 파일은 템플릿 소유다. 지난 X2 #1(예시 이름 `notice-feature`와 타입 검사 탐침 충돌)과 같은 종류다. `notice-feature`도 지금 템플릿 테스트에 있다(`tests/unit/registry-governance.test.ts:637`).
|
||||
- **템플릿 소유 파일을 손으로 고칠 곳은 없다(제거 드릴 실패 제외).** 다만 생성 명령이 추적 파일 `public/release-manifest.json`을 다시 쓴다(`setDigest`와 `packages` 줄). 참조 기능이 있는 동안은 `config/scale/feature-shape-ceilings.json`도 명령으로 다시 써야 한다. 03 문서와 정본 표는 이 둘을 말하지 않는다. 둘째 기능은 같은 `setDigest` 줄을 또 바꿨다(16-R1). 기능 브랜치 둘은 이 줄에서 충돌한다(16-01, Low·P2).
|
||||
- **생성 기능을 설치하고 브라우저 게이트를 돌렸다(16-R1, workflow env).** FE-GATE-008 rc=0(e2e 211 통과·3 skip, capability 66, storybook 1, visual 6). dev server를 쓰는 capability e2e가 그대로 부팅했다(1103/16-09 고쳐짐). FE-GATE-009 rc=0(69 통과). 생성 라우트 셋이 세 엔진에서 spec 수정 없이 axe를 통과했다(1103/16-03 고쳐짐). 다만 CI는 이 상태를 돌지 않는다(16-03, Low·P2).
|
||||
- **생성기의 쓰기 slice가 짝 백엔드의 기본 경로 예시가 됐다.** 지난 라운드 5.3절 권고 (c)가 들어왔다(`2ec9d56`). 대신 백엔드 생성기 템플릿의 사실 넷(경로 복수형, 이름 상한 100, 오류 code, 검사 순서)을 프론트 문자열로 옮겼다. 지금은 같다. 짝 계약 pin과 drift 검사는 `http-contract.md` 하나만 본다(16-02, Low·P3).
|
||||
- **약해진 검사는 찾지 못했다.** 참조 라우팅 테스트를 참조 기능 라우트로 좁힌 것(`e8c4197`)은 테스트 대상이 같다. 초기 파일 상한 26 → 32(`2fef27d`, X2 #4)는 15 영역이 근거와 함께 판정했다.
|
||||
- **이번 발견.** Low 4 · P2 3 · P3 1 · 구조적 위험 3 · 확인된 결함 1. 다른 영역과 같은 결함은 2.4절에 증거만 붙였다(15-03 `BUILD_INPUTS` 두 벌, 1101/15-01 초기 JS 여유, 11-01).
|
||||
|
||||
## 1. 범위 (36.1)
|
||||
|
||||
| 항목 | 기록 |
|
||||
|---|---|
|
||||
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` |
|
||||
| 커밋·작업 상태·확인 시점 | `8a44226`. 코드 읽기는 노트북 worktree(HEAD = 기준, 읽기만). 실행은 desktop checkout(같은 커밋)에서 두 번: helper로 `16-mut`(19:41), 오케스트레이터 배치로 16-R1(20:15). 둘 다 restore clean. 2026-11-05 19:20~20:40 |
|
||||
| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음 |
|
||||
| 필수 요구와 규모·운영 목표 | 짝 백엔드(`clean-architecture-backend-template` `45d2a478`, 읽기만)와 짝으로 쓴다. 생성 명령과 매뉴얼로 기능을 더하고, 템플릿 소유 파일을 고치지 않고, merge 게이트를 통과한다. 기능 수 증가 외 정량 목표 없음 |
|
||||
| 읽은 코드·구성 범위 | `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/removal-fixture.ts`, `scripts/write-dev-release-manifest.ts`, `scripts/scale/measure-feature-shape-growth.ts`, `scripts/check-backend-contract-drift.ts`, `tests/unit/{dev-release-manifest,feature-shape-growth,schema-metadata-policy,product-feature-selection-build,a11y-api-answers,product-extension-typecheck}.test.ts`, `tests/e2e/accessibility.spec.ts`, `tests/e2e/support/installed-api-answers.ts`, `src/contracts/external-contract-runtime.ts`(응답 모양 조립 검사), `src/contracts/server-state.ts`, `src/adapters/http/http-execution-v3.ts`(intent 검증), `src/adapters/http/http-effect-certainty.ts`, `docs/manual/` 전체, `docs/architecture/starter-experience.md` "Adding a feature", `docs/architecture/layers.md`, `public/release-manifest.json`, `config/scale/feature-shape-ceilings.json`, `config/contracts/backend-contract-pin.json`, `config/ci/gates.json`, `CHANGELOG.md` 미출시 절의 남은 것. 백엔드 `scripts/new-feature.sh`와 `scripts/feature-scaffold/templates/`의 create use case·controller·aggregate 템플릿. `git diff e40684b..8a44226`의 이 영역 경로 |
|
||||
| 수행한 테스트·실험 | `16-mut`: 생성 1번, 변이 5개(6절). 16-R1(workflow env, 450초): 생성 1번 → `ci:gate FE-GATE-008`, `ci:gate FE-GATE-009` → 11단계 `test:sample-removal -- --feature=invoice-feature` → 둘째 기능 `order-feature` 생성, manifest diff, `build`, `check:bundle`. 오케스트레이터 결과 인용: `merge-48/`(CI=true, FE-GATE-020·001~009 rc=0), `gates/`(로컬 env). 다른 영역 실행 인용: `15-lab`, `15-feature`, `11-R8b`, `12-R3`(같은 커밋, restore clean) |
|
||||
| 확인하지 못한 범위·이유 | FE-GATE-013, 실제 Gitea 러너, 실제 짝 백엔드 연결, 두 브랜치의 실제 `git merge`, 매뉴얼만 보는 사람·에이전트의 재실험(X2 방식)은 하지 않았다(5절). 생성 기능 설치 상태의 FE-GATE-001~007·010~012는 다시 돌리지 않고 merge-48 FE-GATE-020의 생성 드릴(같은 명령, `--with-create --keyed` 기능)을 인용했다 |
|
||||
| 이전 리뷰와 비교 가능한 범위 | `docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md`의 16-01~16-08, README §13의 16-09, §10.3에서 11-01로 합친 16-03 뒷부분, 지난 영역 문서 2절의 "남음" 이월, README §14.6 X2 막힘 7건, §14.7 남은 문제. 지난 실행 결과는 증거로 쓰지 않았다 |
|
||||
| 실행 중 부하 | 리뷰어 15명과 게이트 실행이 잠금 하나를 나눠 썼다. `16-mut`은 잠금을 579초 기다렸고 시작 부하 2.16이었다. 16-R1은 시작 부하 3.26, FE-GATE-008 중 14.09였다. 이 영역 결론은 실행 시간에 기대지 않는다 |
|
||||
|
||||
## 2. 지난 발견 재확인
|
||||
|
||||
README §14.4의 상태는 주장으로 보고, 이번 커밋의 코드와 `16-mut`·16-R1로 다시 판정했다.
|
||||
|
||||
### 2.1 1103 영역 16 발견 (README §12·§13, §10.3 합친 것 포함)
|
||||
|
||||
| 지난 ID | 내용 | 상태 | 근거 (`8a44226`) |
|
||||
|---|---|---|---|
|
||||
| 1103/16-01 | Envelope를 operation마다 선언하고, 빠뜨려도 게이트와 MSW 시나리오 테스트가 통과한다 | **일부** | 고친 것: 계약 조립이 한 기여 안에서 응답 모양이 다른 operation을 거절한다(`src/contracts/external-contract-runtime.ts:655-669`, 호출 `:1031`). 쓰기의 `refusedBeforeWrite`는 Envelope를 요구한다(`:627-629`). 생성기는 모든 operation에 줄을 쓴다(`scripts/create-feature-write-slice.ts:269`, `:323`). `16-mut` M1(줄 하나 삭제): `check:registries` rc=1, `invoice-feature/INVOICE_GET_ITEM: responseEnvelope NONE, but INVOICE_LIST_ITEMS in the same contribution reads ENVELOPE_V1; ...`, 기능 테스트 4파일 실패. M2(세 줄 모두 삭제): `check:types` rc=0, `check:registries` rc=1(`INVOICE_CREATE_ITEM: refusedBeforeWrite needs responseEnvelope ENVELOPE_V1`), gateway 테스트 11건이 `SCHEMA_MISMATCH`로 실패. 남은 것: 읽기만 있는 기여(기본 생성 판)나 `refusedBeforeWrite` 없는 쓰기에서 줄을 모두 빼면 조립은 통과하고 손글씨 gateway 테스트만 잡는다(코드 추론, 실행 안 함). 매뉴얼이 "못 잡음"으로 적는다(`docs/manual/01-add-a-feature.md:213`). 지난 완료 기준("줄을 지우면 `check:types` 실패")은 충족하지 않았다. 지난 대안 (d)를 고른 이유는 커밋 본문에 있다(`3f7e10c`) |
|
||||
| 1103/16-02 | 제품 기능 제거 드릴이 시작 3초 만에 CI 기준선 오류로 끝난다 | **고쳐짐** | 빈 목록 사유(`scripts/lib/removal-fixture.ts:468-476`). 이 길을 merge 게이트가 돈다: `test:feature-scaffold`가 생성 기능을 `--feature`로 지운다(`scripts/test-feature-scaffold.ts:104`). 오케스트레이터 merge-48 FE-GATE-020 rc=0(1,156초, CI=true): `scaffold-feature removal: PASS (17 checks, no fixture IDs)`. 16-R1의 `invoice-feature`(`--with-create --keyed`) 제거는 기준선·타입·테스트·커버리지(`Risk coverage: PASS`)·CI 계약 검사를 모두 통과하고 잔여 검사에서만 실패했다. 원인은 다른 결함이다(새 16-04: 잔여 검사가 템플릿 테스트의 예시 이름을 잡는다). 이 발견의 원인(빈 사유)은 다시 나오지 않았다 |
|
||||
| 1103/16-03 | 공유 접근성 spec이 기능마다 수정을 요구하고, Envelope 기능에는 오류 화면만 검사한다 | **고쳐짐(앞부분)**. 뒷부분은 11-01로 합침 | 경로 파라미터를 이름과 상관없이 `a11y-1`로 바꾼다(`tests/e2e/accessibility.spec.ts:30-38`). API 답은 설치된 descriptor에서 만든다(`tests/e2e/support/installed-api-answers.ts:35-63`). 그래서 기능을 더해도 spec을 고치지 않는다. 상세 라우트는 실패 상태로 검사하고 annotation을 남긴다(`accessibility.spec.ts:72-82`, 매뉴얼 01:426). 16-R1: 생성 기능을 설치하고 spec을 고치지 않은 채 FE-GATE-009 rc=0. `/invoice`, `/invoice/items/a11y-1`, `/invoice/new`가 chromium·firefox·webkit에서 통과했고, `review:a11y-manual -- --format-only`는 `13 routes` PASS였다. 11-R8b(11 영역): 생성 목록 페이지의 빈 상태에만 이름 없는 button을 넣자 `/sample`만 세 엔진에서 실패했다. 목록 라우트가 빈 상태로 axe 검사된다는 뜻이다 |
|
||||
| 1103/16-04 | 스키마 메타 행을 손으로 다시 적고, 틀려도 아무 검사가 잡지 않는다 | **고쳐짐** | `tests/unit/schema-metadata-policy.test.ts:126-171`이 `boundary`·`direction`·`unknownFieldPolicy`를 설치된 descriptor·라우트·zod 검증기와 대조한다(`test:unit`, FE-GATE-005). 완료 기준("E-4 세 변이가 각각 실패")을 생성 기능으로 다시 했다(`16-mut` M3a~c): 셋 다 `check:registries` rc=0, 그 테스트가 각각 `InvoiceItemListPayload: row REQUEST, used as RESPONSE`, `row api-request, used as api-response`, `row STRIP_UNKNOWN, validator REJECT_UNKNOWN`으로 실패. 변이 전 같은 명령은 rc=0. 행은 여전히 손으로 쓴다(지난 대안 (c) 대조를 골랐다) |
|
||||
| 1103/16-05 | 뮤테이션 정책 `operationId`가 자유 문자열이다 | **일부** | 고친 것: `commandMutationIdentity(<OPERATION>_CONTRACT)`(`src/contracts/server-state.ts:281-300`)를 쓰기 slice(`scripts/create-feature-write-slice.ts:505`)와 참조 기능(`src/features/reference-feature/presentation/use-reference-feature.ts:60`)이 쓴다. 상수 이름 오타는 tsc가 잡는다. 남은 것: `BoundMutation.operationId`가 여전히 `string`이다(`server-state.ts:305`). 손으로 쓴 문자열의 오타는 통과한다(매뉴얼 01:492 "못 잡음"). 위반 이름도 그대로다. ID가 다르면 KEYED는 `MISSING_IDEMPOTENCY_KEY`, 키 없는 쓰기는 `UNEXPECTED_IDEMPOTENCY_KEY`다(`src/adapters/http/http-execution-v3.ts:491-498`) |
|
||||
| 1103/16-06 | 반드시 채우는 칸 중 아무도 읽지 않는 칸이 있다 | **일부** | 쿼리 `owner`·`operationId`, 뮤테이션 `owner`는 `@deprecated` 선택 칸이 됐다(`server-state.ts:178-184`, `:308-311`). 생성기는 쿼리에 이 칸을 쓰지 않는다. 남은 것: 라우트 계약 `title`·`navigationLabel`은 화면이 읽지 않는데 생성기가 채운다(`scripts/create-feature.ts:582-583`, `scripts/create-feature-write-slice.ts:128-129`). 매뉴얼이 "화면이 읽지 않는다"고 적는다(01:402) — M1 |
|
||||
| 1103/16-07 | 짝 백엔드 KEYED 쓰기 값 넷을 매뉴얼이 정하지 않는다 | **고쳐짐** | 02 결정표 3절이 NEVER·KEYED 두 경우의 값과 이유를 준다(`docs/manual/02-decision-tables.md:99-127`). `--keyed`가 같은 값을 쓴다(`scripts/create-feature-write-slice.ts:225-250`, `:291-307`). 호출 문맥 `intent`는 생성된 `<Base>CommandContext`가 필수로 받는다(01:326). 하네스 재시도 상한은 앱 기본값 2다(`scripts/create-feature.ts:1491-1497`). `classifyStatus`의 근거(401·403·429가 use case 전)는 백엔드 템플릿과 맞다(`Create__Feature__UseCase.java.tmpl`의 `@RequiresPermission`, 검사 뒤 `tx.inWrite`). `operationIdentityField`를 실행기가 읽지 않는 것은 1101/07-07(07 영역) 그대로다 |
|
||||
| 1103/16-08 | 기능 추가 문서의 낡은 문장 다섯 | **고쳐짐** | ① 테스트 셋(01:35) ② 400 `VALIDATION_FAILED`(01:508) ③ `context-route-roots.test.ts`는 fixture만(01:78) ④ 인증 프로필 오타에 통과하는 게이트(01:296) ⑤ `<Pascal>NoRequest`(`docs/architecture/starter-experience.md:244-245`). 이 수정 뒤에 생긴 다른 낡은 문장은 새 16-01에 적었다 |
|
||||
| 1103/16-09 | dev server가 고정된 contract set을 내주어 기능 추가 직후 `pnpm dev`가 부팅하지 못한다 | **고쳐짐**(방식이 새 16-01을 만듦) | `create:feature`가 생성 뒤 `scripts/write-dev-release-manifest.ts`를 돌린다(`scripts/create-feature.ts:1787-1796`). `16-mut`에서 `public/release-manifest.json`의 `packages`에 `@org-contracts/invoice`가 들어갔다. 낡으면 `tests/unit/dev-release-manifest.test.ts:17-27`이 다시 쓰는 명령을 말하며 실패한다(M3). 16-R1: 생성 기능을 설치한 채 FE-GATE-008 rc=0. dev server를 쓰는 capability e2e 66건이 세 엔진에서 통과했고 `Browser capability evidence: PASS (22 cases x 3 engines, zero skipped)`였다. 지난 라운드의 38건 실패가 사라졌다 |
|
||||
|
||||
### 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`, `src/application/ports/telemetry-port.ts:5`. 매뉴얼은 "쓰지 않는다"로만 막는다(01:334, `docs/manual/reference/patterns.md:128`) ③ `adapters` 두 뜻 ④ 폐기 재수출 `src/application/result.ts:9`. 넷 다 그대로다 |
|
||||
| 1101/16-06 (R-8) | 기능 `contracts/`가 와이어 계약·문구·뷰 타입을 함께 담는다 | **남음** | 생성기가 `contracts/<base>-message-catalog.ts`, `contracts/<base>-mapper.ts`를 쓴다(`docs/manual/reference/create-feature.md:50-53`, `16-mut` 생성 목록) |
|
||||
| 0929/12-03 | 기능 안 다섯 폴더 밖 폴더와 `contracts/`를 거친 어댑터 import에 규칙이 없다 | **남음** | `docs/architecture/layers.md`의 규칙 표에 기능 `contracts/`나 다른 폴더를 막는 행이 없다. 매뉴얼이 "못 잡음"으로 적는다(01:387) — M1. 12 영역 12-R3: 기능 안 `support/direct-http.ts`가 http 어댑터 barrel을 import하고 presentation이 그 파일을 import해도 `check:architecture` rc=0, eslint rc=0 |
|
||||
| 0929/08-06 → 1103/16-06 | 라우트 이름이 계약과 catalog 두 곳 | **일부** | 위 1103/16-06 행 |
|
||||
| README §14.7 | `BUILD_INPUTS` 두 벌 | **남음** | 15 영역이 새 1105/15-03으로 셌다. 이 영역은 세지 않는다(2.4절) |
|
||||
|
||||
### 2.3 지난 라운드 X2 막힘 7건 (README §14.6)
|
||||
|
||||
| # | 지난 막힘 | §14.6 주장 | 이번 확인 |
|
||||
|---|---|---|---|
|
||||
| 1 | 타입 검사 탐침이 매뉴얼 예시 이름(`notice-feature`)과 겹쳐 FE-GATE-005 실패 | 고침 `235143c` | 탐침 이름이 `typecheck-probe-*`다(`tests/unit/product-extension-typecheck.test.ts:85-86`). 생성 기능(`scaffold-*`)이 든 드릴의 FE-GATE-005 명령 통과(merge-48 FE-GATE-020). 그 탐침은 고쳐졌다. 같은 종류(매뉴얼 예시 이름이 템플릿 테스트와 겹침)가 제거 드릴에서 다시 나왔다: 새 16-04 |
|
||||
| 2 | 초기 JS 기록을 다시 쓰면 제거 드릴이 실패, 안 쓰면 FE-GATE-005 실패 | 고침 `72c6e9d` | 드릴이 지운 뒤 기록을 다시 쓴다(`scripts/test-sample-removal.ts:399-413`). 생성 드릴도 다시 쓴다(`scripts/test-feature-scaffold.ts:72-91`). 둘 다 merge-48 FE-GATE-020에서 통과. 남은 것: 다운스트림이 이 추적 파일을 기능마다 커밋한다(16-01) |
|
||||
| 3 | 기능 생성 직후 dev server가 `CONTRACT_SET_PACKAGE_MISSING` | 고침 `799ab7f`(16-09) | 생성 명령이 manifest를 다시 쓴다(`16-mut`, 16-R1 diff). 설치 상태에서 dev server capability e2e 66건 통과(16-R1 FE-GATE-008). 남은 것: 추적 파일 공유(16-01) |
|
||||
| 4 | 검색 폼 예제가 초기 파일 상한 26을 넘김 | 고침 `2fef27d`(상한 32) | 상한을 올린 변경이다. 15 영역이 약해진 검사가 아니라고 판정했다(템플릿 자신의 파일 수는 기록이 정확히 막는다) |
|
||||
| 5 | 매뉴얼이 "드릴은 `check:bundle`을 돌리지 않는다" | 고침 `72b8ab1` | 01:667, `docs/manual/reference/create-feature.md:164`가 "돈다"로 맞다 |
|
||||
| 6 | 로컬 FE-GATE-013에 `VITE_COMMIT_SHA` 안내 없음 | 고침 `72b8ab1` | 01:669, 생성 출력(`scripts/create-feature.ts:1752`). 실행하지 않았다 |
|
||||
| 7 | 깨끗한 base에서 FE-GATE-020 드릴 셋 실패 | 고침 | merge-48 FE-GATE-020 rc=0: optional-recipe·browser-file-storage·realtime 제거 PASS |
|
||||
|
||||
이번 실행(`16-mut`, 16-R1)을 지난 X2와 같은 기준으로 세면 이렇다.
|
||||
|
||||
| 셈 | 결과 |
|
||||
|---|---|
|
||||
| 손으로 고친 템플릿 파일 | 0개 |
|
||||
| 생성 명령이 바꾼 추적 파일 | 1개(`public/release-manifest.json`). `Next:` 3번을 따르면 1개가 더 바뀐다(`config/scale/feature-shape-ceilings.json`, 16-R1은 이 단계를 생성 드릴에 맡기고 생략) |
|
||||
| 원인을 모르는 실패 | 0건 |
|
||||
| 매뉴얼대로 했는데 실패한 단계 | 1건: 11단계 제거 드릴(16-04). 문구는 원인 파일을 말한다. 고치라는 곳이 템플릿 소유 테스트라 매뉴얼로는 풀 수 없다. 다른 이름을 고르면 피한다 |
|
||||
| merge 게이트 | 브라우저 둘(FE-GATE-008·009)은 16-R1에서 rc=0. 나머지는 merge-48 FE-GATE-020의 생성 드릴로 갈음 |
|
||||
|
||||
지난 X2(막힘 7건, 91분 중 약 45분이 원인 추적)와 비교하면 생성 뒤 단계에서 막힌 곳은 1건이다. 다만 이번에는 3~8단계의 손 작업을 하지 않았으므로 같은 셈이 아니다(5절).
|
||||
|
||||
### 2.4 다른 영역 발견에 이 영역이 더한 증거
|
||||
|
||||
같은 결함을 다시 세지 않는다.
|
||||
|
||||
| 발견 | 이 영역이 더한 증거 |
|
||||
|---|---|
|
||||
| 1105/15-03 `BUILD_INPUTS` 두 벌 | 두 목록은 이번 라운드에 두 번 함께 고쳐졌다. `7f9a515`가 두 목록에 같은 줄을 더했고(본문: "두 목록이 같은 내용의 사본이다. 하나로 합치는 것은 범위 밖"), `799ab7f`가 두 목록에서 그 줄을 뺐다. 한쪽만 고쳤을 때의 증상은 생성 명령 `Next:` 3번(초기 JS 기록)이 원인을 말하지 않는 `Could not resolve`로 실패하는 것이다(`7f9a515` 본문) |
|
||||
| 1101/15-01 초기 JS 여유가 작다(15 영역 "남음") | 생성 명령의 약속 쪽에서 본 영향이다. 템플릿 202,927 B(`15-lab`). 쓰기 기능 하나(새 context) 203,903 B, 여유 897 B(`15-feature`, 로컬 env). 16-R1(workflow env): 쓰기 기능 둘(각각 새 context) 204,523 / 204,800 B, `Bundle budget: PASS`, 여유 **277 B**, 파일 26 / 32. 문서 작성 중 "둘째에서 넘는다"고 추론했으나 틀렸다. 둘째 기능은 약 620 B를 더했다(두 측정의 env와 기능 이름이 달라 대략이다). 셋째는 넘는다(추론: 둘째의 증가분이 남은 여유보다 크다). 넘으면 고를 길은 템플릿 소유 `config/performance/budgets.json` 수정, 참조 기능·예제 기능 제거, 기존 context에 넣기다. 매뉴얼은 "넘으면 예산을 올리기 전에 팀이 정한다"만 적는다(01:666). 03 문서는 `budgets.json`을 A~D 어디에도 두지 않는다 |
|
||||
| 1103/16-03 뒷부분 → 11-01 | 16-R1 FE-GATE-009: 생성 목록 라우트 `/invoice`가 세 엔진에서 경고 상자 없이 axe를 통과했다(`accessibility.spec.ts:72-74`의 단언). 11-R8b가 빈 상태에 넣은 결함을 axe가 잡는 것을 보였다 |
|
||||
|
||||
## 3. 이번 발견 (36.3)
|
||||
|
||||
집계: Low 4 · P2 3 · P3 1 · 구조적 위험 3 · 확인된 결함 1. High 이상과 P1은 없다.
|
||||
|
||||
| ID | 제목 | 성격 | 심각도·우선순위 | 관련 관점 |
|
||||
|---|---|---|---|---|
|
||||
| 16-01 | 기능 하나를 더하면 템플릿 추적 파일 두 개가 바뀌고, 문서는 이를 말하지 않으며, 기능 브랜치 둘이 같은 줄에서 충돌한다 | 구조적 위험 | Low · P2 | 25, 3, 9, 20, 23, 27 |
|
||||
| 16-02 | 쓰기 slice가 짝 백엔드 생성기 템플릿의 사실을 손으로 옮겼는데, 짝 계약 pin은 `http-contract.md`만 대조한다 | 구조적 위험 | Low · P3 | 17, 9, 21, 23 |
|
||||
| 16-03 | 생성 기능을 설치한 상태로 브라우저 merge 게이트를 도는 장치가 없다 | 구조적 위험 | Low · P2 | 10, 21, 20, 5 |
|
||||
| 16-04 | 제품 기능 제거 드릴의 잔여 검사가 템플릿 테스트에 나오는 이름을 잔여로 잡아, 매뉴얼 예시 이름(`invoice-feature`)으로 만든 기능은 11단계가 실패한다 | 확인된 결함 | Low · P2 | 27, 20, 21, 24, 8 |
|
||||
|
||||
### 16-01 기능 하나를 더하면 템플릿 추적 파일 두 개가 바뀐다 — 정본 표와 03 문서가 이를 말하지 않고, 기능 브랜치 둘이 같은 줄을 바꿔 충돌한다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 구조적 위험 (문서 불일치 포함) |
|
||||
| 관련 관점 | 25, 3, 9, 20, 23, 27 |
|
||||
| 근거 | ① dev manifest: `create:feature`가 생성 뒤 `scripts/write-dev-release-manifest.ts`를 돌려 추적 파일 `public/release-manifest.json`의 `contractSet`을 다시 쓴다(`scripts/create-feature.ts:1787-1796`, `scripts/write-dev-release-manifest.ts:17-21`). 출력이 "commit it with the feature"라고 한다(`create-feature.ts:1754`). 1103/16-09를 고친 `799ab7f`의 방식이다. ② 초기 JS 기록: 참조 기능이 설치돼 있는 동안 `config/scale/feature-shape-ceilings.json`의 `initialJavascript`를 명령으로 다시 써서 같은 커밋에 넣어야 한다(`create-feature.ts:1753`, 매뉴얼 01:668). 안 쓰면 `tests/unit/feature-shape-growth.test.ts:160-165`가 실패한다. ③ 실행 `16-mut`: 생성 직후 폴더 밖 변경은 새 파일 4개(context 선언, a11y 기록 3)와 수정 1개 `M public/release-manifest.json`이다. diff는 `setDigest` 한 줄(`sha256:ad6a…` → `sha256:d9af…`)과 `packages: []` → `@org-contracts/invoice` 항목이다. ④ 문서: 03 문서 A절은 "생성 명령이 쓰는 폴더 밖 파일은 둘이다"(context 선언, a11y 기록)라고 적는다(`docs/manual/03-outside-feature-folder.md:22-30`). 03이 정본으로 가리키는 표(`docs/architecture/starter-experience.md:215-226`)에도 두 파일이 없다. 매뉴얼 01 1단계의 "명령이 하는 일"(01:99-107)은 manifest 재작성을 말하지 않는다. 03의 "기능을 지울 때"는 dev manifest만 말하고 초기 JS 기록은 말하지 않는다(03:185). ⑤ 충돌: `setDigest`는 설치된 패키지 집합 전체의 해시 한 줄이고 `packages`는 배열 하나다. 기능을 하나씩 더한 두 브랜치는 둘 다 이 줄을 다른 값으로 바꾼다. 초기 JS 기록의 `gzipBytes`도 그렇다. 16-R1에서 둘째 기능(`order-feature`)을 더하자 같은 `setDigest` 줄이 다시 바뀌었고(`sha256:d9af…` → `sha256:4a87…`), `packages` 배열 끝에 항목이 붙었다. ⑥ 다시 쓰기가 실패하면 명령은 만든 기능 파일을 지우지 않고 멈춘다(`create-feature.ts:1793-1796`). 생성기 거절 때는 지운다(`:1781-1785`) |
|
||||
| 발생 조건 | 기능 브랜치 둘을 병렬로 만들어 합칠 때. 참조 기능이 남은 다운스트림이 초기 JS를 바꾸는 템플릿 변경을 받을 때(기록은 템플릿 변경마다 다시 찍힌다: `1b8cb12`, `f887817`). 03 문서나 정본 표만 보고 커밋할 파일을 고를 때 |
|
||||
| 영향 | 병렬 기능 브랜치의 둘째 merge가 텍스트 충돌로 멈춘다. 손으로 합친 값이 틀리면 `test:unit`이 다시 쓰는 명령을 말하며 실패한다(`tests/unit/dev-release-manifest.test.ts:23-26`). 사용자 피해와 데이터 위험은 없다. 지난 라운드 강점 "기능 하나가 템플릿 소유 파일을 건드리지 않는다"(1103 6.5절)가 이제 "손으로는 건드리지 않는다"로 줄었다 |
|
||||
| 심각도·우선순위 | Low · P2 — 피해가 없고 낡은 값은 검사가 잡는다. 다만 기능이 늘 때마다, 브랜치가 둘 이상일 때마다 반복되는 비용이고 문서가 그 처리를 말하지 않는다 |
|
||||
| 통제·증거 | 목표 M3(낡은 값 검출) + 기능마다 바뀌는 공유 줄 없음. 확인 M3(두 test:unit 검사) · 문서 M0(03 A절·정본 표에 없음) · E3(`16-mut`, 16-R1 둘째 기능 diff) |
|
||||
| 확실성과 남은 가정 | 파일이 바뀌는 것은 실행으로 봤다. 두 브랜치 merge 충돌은 실제 `git merge`로 재현하지 않았다. 같은 JSON 줄을 두 브랜치가 다른 값으로 바꾸는 구조에서 판단했다(추론, 확실성 높음) |
|
||||
| 결정의 근거 | 확인한 사실: dev 전용 미들웨어(서빙 중에 설치된 기능으로 manifest를 냄)는 capability e2e를 불안정하게 만들어 지웠다(`799ab7f` 본문, 1103 README §14.5 7회차). 커밋은 "레지스트리 기준선과 같은 방식"이라고 적는다. 리뷰어 추론: 레지스트리 기준선은 더하기만 하는 기능에서는 바뀌지 않게 설계됐다(03:122). dev manifest와 초기 JS 기록은 기능마다 바뀐다. 같은 방식이 아니다 |
|
||||
| 이해 비용 | 기능 작성자가 출력 `Next:` 3번과 마지막 줄을 읽어야 두 파일을 안다. 03 문서·정본 표만 보는 사람은 모른다. 충돌하면 어느 명령으로 다시 만드는지는 test:unit 실패 문구에만 있다 |
|
||||
| 최소 개선 방향 | (1) 03 A절, 정본 표, 01 1단계 흐름에 두 파일을 적는다: 누가 쓰나, 언제 커밋하나, 충돌하면 어느 명령으로 다시 만드나. (2) 충돌 자체를 없애려면 아래 (b)·(d) |
|
||||
| 대안 비교 | (a) 현상 유지 + 문서: 가장 싸다. 충돌은 남는다. (b) dev manifest를 생성 파일로 두고(`.gitignore`) `dev` 스크립트와 dev server를 쓰는 Playwright 설정 앞에서 만든다(`generate:feature-index`처럼): 커밋 줄이 사라진다. 서빙 중이 아니라 시작 전에 쓰므로 미들웨어의 불안정과 다르다. (c) dev 부팅에서 contract set 검사를 끈다: `799ab7f`가 버린 대안이다(검사 조건이 dev만 달라진다). (d) 초기 JS 기록은 템플릿 자신의 값만 담고, 대조할 때 설치된 제품 기능을 빼고 잰다: 다운스트림이 다시 찍지 않는다. (b)+(d) 권장. 빠르게는 (a) 먼저 |
|
||||
| 단순화의 보존 조건 | dev server와 build가 같은 contract set 검사를 한다(`src/bootstrap/load-release-manifest.ts`). build의 manifest는 지금처럼 `scripts/generate-build-manifest.ts`에서 온다. 초기 JS 예산 검사(FE-GATE-012)와 기능당 1 KiB 상한은 그대로다 |
|
||||
| 비용·부작용 | (b)는 `dev`와 Playwright webServer 명령 앞에 단계 하나, `tests/unit/dev-release-manifest.test.ts` 변경. (d)는 측정 스크립트 수정 |
|
||||
| 재검토 조건 | dev server가 서빙 중에 contract set을 안정적으로 낼 수 있게 되면 (b) 대신 그쪽을 다시 본다 |
|
||||
| 완료 기준 | 기능 하나를 더한 커밋에 템플릿 추적 파일이 없다. 또는 03 A절·정본 표가 두 파일과 충돌 처리 명령을 적는다 |
|
||||
| 검증 방법 | `create:feature` 뒤 `git status --short`에서 폴더 밖 수정 파일을 센다. 기능을 하나씩 더한 두 브랜치를 합친다 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
| 재검증 결과 | 해당 없음 |
|
||||
|
||||
### 16-02 쓰기 slice가 짝 백엔드 생성기 템플릿의 사실을 손으로 옮겼는데, 짝 계약 pin은 `http-contract.md`만 대조한다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 구조적 위험 (다른 repo의 사본, 지금은 같다) |
|
||||
| 관련 관점 | 17, 9, 21, 23 |
|
||||
| 근거 | `--with-create`(`2ec9d56`)가 백엔드 `scripts/new-feature.sh`와 `scripts/feature-scaffold/templates/`의 사실을 문자열로 옮겼다. ① 경로 복수형 규칙: 프론트 `scripts/create-feature.ts:126-134`, 백엔드 `scripts/new-feature.sh:58-63`. ② 이름 상한 100: 프론트 `scripts/create-feature-write-slice.ts:58-59`, 백엔드 `__Feature__.java.tmpl:17`. ③ code `<FEATURE>_INVALID`·`<FEATURE>_NOT_FOUND`: 프론트 `create-feature-write-slice.ts:83-84`, 백엔드 `__Feature__ControllerTest.java.tmpl:68, 91`, `__Feature__ErrorCode.java.tmpl:12`. ④ 201과 `refusedBeforeWrite`·`classifyStatus`의 근거(검사 순서): 프론트 `create-feature-write-slice.ts:291-307`, 백엔드 `__Feature__Controller.java.tmpl:58`, `Create__Feature__UseCase.java.tmpl`의 `handle`. 백엔드 `45d2a478`과 지금 모두 같다. 그러나 pin은 `docs/web/http-contract.md` 하나를 본다(`config/contracts/backend-contract-pin.json:6-7`). drift 검사도 그 파일의 diff만 본다(`scripts/check-backend-contract-drift.ts:40`, `:60`). 그 검사는 게이트 밖이다(`CHANGELOG.md:265`) |
|
||||
| 발생 조건 | 백엔드가 생성기 템플릿(이름 규칙, 오류 code, 상한, use case 순서)을 바꿀 때 |
|
||||
| 영향 | 생성 기능이 백엔드 생성 기능과 다른 경로·상한·code를 쓴다. 경로가 다르면 404다. code가 다르면 쓰기 전 거절이 결과 불명으로 간다(`refusedBeforeWrite`에 없는 code). 정확성은 결과 불명 쪽으로 안전하게 기운다 |
|
||||
| 심각도·우선순위 | Low · P3 — 지금 갈라지지 않았고, 틀리면 안전한 쪽이다 |
|
||||
| 통제·증거 | 목표 M3(백엔드 템플릿 변경 신호). 확인 M1(주석이 백엔드 파일을 가리킨다) · E1(두 repo 정적 대조) |
|
||||
| 확실성과 남은 가정 | 네 사실이 같은 것은 두 repo를 읽어 확인했다. 백엔드가 이 템플릿을 얼마나 자주 바꾸는지는 보지 않았다 |
|
||||
| 결정의 근거 | 확인한 사실: D6(1103 README §14.2)은 짝 계약 기준점을 "pin 파일 + 답 표 대조 + 로컬 drift 검사"로 정했고 범위는 `http-contract.md`였다. 쓰기 slice는 그 뒤에 들어왔다. 리뷰어 추론: pin의 `document`를 목록으로 넓히면 같은 장치로 덮인다 |
|
||||
| 이해 비용 | 백엔드 생성기를 바꾸는 사람이 프론트 생성기의 네 곳을 알아야 한다 |
|
||||
| 최소 개선 방향 | pin에 백엔드 생성기 템플릿 파일 넷을 비교 대상으로 더한다. drift 검사가 pin 뒤에 그 파일이 바뀌면 알린다 |
|
||||
| 대안 비교 | (a) 현상 유지(주석만). (b) pin 대상 확대: 기존 장치 재사용, 파일 목록만 는다. (c) 백엔드가 생성기 사실을 JSON으로 내고 프론트가 읽는다: 두 repo 변경. (b) 권장 |
|
||||
| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다 |
|
||||
| 비용·부작용 | pin 몇 줄과 drift 검사의 파일 목록 처리 |
|
||||
| 재검토 조건 | 백엔드 생성기가 계약 패키지(`@org-contracts/*`)를 내게 되면 그 패키지가 정본이 되고 이 사본은 사라진다 |
|
||||
| 완료 기준 | 백엔드 생성기 템플릿의 네 사실 중 하나가 바뀌면 프론트 drift 검사가 알린다 |
|
||||
| 검증 방법 | 백엔드 사본에서 `NAME_MAX_LENGTH`를 바꾸고 drift 검사를 돌린다 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
| 재검증 결과 | 해당 없음 |
|
||||
|
||||
### 16-03 생성 기능을 설치한 상태로 브라우저 merge 게이트를 도는 장치가 없다 — 지난 라운드 16-09도 이 틈에서 사람이 찾았다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 구조적 위험 (검사 공백) |
|
||||
| 관련 관점 | 10, 21, 20, 5 |
|
||||
| 근거 | ① 생성 드릴(FE-GATE-020)은 merge 명령을 `config/ci/gates.json`에서 뽑아 돌지만, 브라우저 명령(`test:e2e`, `test:browser-capabilities`, `test:storybook`, `test:visual`, `test:a11y`, 그 증거 검사)은 뺀다(`scripts/lib/feature-scaffold-drill.ts:18-37`). 이유는 "FE-GATE-020 job에 브라우저가 없다"이고, 생성 라우트는 "1103/12-01과 12-03으로 리뷰했다"고 적는다(`:18-21`). ② 그래서 CI의 FE-GATE-008·009(merge-48 rc=0)는 템플릿 원래 상태만 본다. 매뉴얼 README도 "브라우저 게이트는 드릴 밖"이라고 적는다(`docs/manual/README.md:5`). ③ 이 틈의 실제 사례: 1103/16-09(기능 생성 직후 dev server 부팅 실패, dev server를 쓰는 capability e2e 38건 실패)는 게이트가 아니라 매뉴얼 재실험(X2 #3)이 찾았다(1103 README §13). 고친 뒤 `tests/unit/dev-release-manifest.test.ts`가 그 원인 하나를 test:unit으로 막는다. 같은 종류(브라우저에서만 드러나는 생성 기능 결함)는 여전히 CI가 보지 않는다. 예: a11y spec의 descriptor 답(`tests/e2e/support/installed-api-answers.ts`), 시각 골든의 기능 링크 가리기(12-01) ④ 지금은 통과한다. 16-R1(workflow env)에서 생성 기능을 설치하고 FE-GATE-008 rc=0(e2e 211 통과·3 skip, capability 66, storybook 1, visual 6), FE-GATE-009 rc=0(69 통과, 생성 라우트 3 × 엔진 3)이었다. 통과를 지키는 장치가 CI에 없다는 것이 이 발견이다 |
|
||||
| 발생 조건 | 템플릿 변경이 생성 기능의 화면·접근성·dev server 경로만 깨뜨릴 때 |
|
||||
| 영향 | 그 변경은 merge 게이트를 통과하고, 다운스트림이 기능을 더한 뒤 처음 드러난다. 사용자 피해는 없다(다운스트림의 자기 게이트가 잡는다) |
|
||||
| 심각도·우선순위 | Low · P2 — 피해는 없고 다운스트림 게이트가 결국 잡는다. 다만 생성 명령의 약속("모든 merge 게이트를 통과")을 템플릿이 스스로 지키는 장치가 이 두 게이트에 없다 |
|
||||
| 통제·증거 | 목표 M3(생성 기능 설치 상태의 브라우저 게이트를 CI가 돈다). 확인 M1(제외 이유와 문서) · E1(드릴 코드), 지금 통과는 E3(16-R1) |
|
||||
| 확실성과 남은 가정 | 제외 목록과 CI matrix는 코드로 확인했다. 12 영역(게이트·CI)과 겹칠 수 있다. 합칠 때는 12 영역을 대표로 한다 |
|
||||
| 결정의 근거 | 확인한 사실: 1103/12-02 수정이 드릴을 merge 단계 전체로 넓혔고, 브라우저만 이유와 함께 뺐다. FE-GATE-020 job은 `browser: false`다(`.gitea/workflows/quality-gates.yml:56`). 리뷰어 추론: FE-GATE-008 job은 브라우저가 있으므로 그 job에서 생성 기능 하나를 설치한 복사본으로 a11y·capability 일부를 돌릴 수 있다 |
|
||||
| 이해 비용 | 템플릿 변경자가 생성 기능을 손으로 만들어 브라우저 게이트를 돌려야 그 경로를 본다 |
|
||||
| 최소 개선 방향 | FE-GATE-008 또는 009에 "생성 기능 하나 설치 + `test:a11y -g <생성 라우트>` + dev server capability 한 spec" 단계를 더한다. 또는 FE-GATE-020 job에 브라우저를 주고 드릴의 브라우저 제외를 줄인다 |
|
||||
| 대안 비교 | (a) 현상 유지 + 문서. (b) FE-GATE-009에 생성 기능 라우트만 도는 짧은 단계: 시간이 적다. (c) FE-GATE-020 job에 브라우저: 드릴 시간(지금 1,156초)이 더 는다(job 상한 45분, `CHANGELOG.md:273`). (b) 권장 |
|
||||
| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다 |
|
||||
| 비용·부작용 | (b)는 생성 1회 + 라우트 3개 a11y + spec 하나. 분 단위 |
|
||||
| 재검토 조건 | merge job의 브라우저 구성이 바뀌거나, 생성 판이 화면을 더 만들 때 |
|
||||
| 완료 기준 | 생성 기능을 설치한 상태의 a11y·dev server 경로를 merge 게이트 하나가 돈다 |
|
||||
| 검증 방법 | a11y spec의 descriptor 답을 일부러 틀리게 바꾼 템플릿 변경이 merge 게이트에서 실패한다 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
| 재검증 결과 | 해당 없음 |
|
||||
|
||||
### 16-04 제품 기능 제거 드릴의 잔여 검사가 템플릿 테스트에 나오는 이름을 잔여로 잡는다 — 매뉴얼 예시 이름 `invoice-feature`로 만든 기능은 11단계가 실패하고, 안내는 템플릿 파일 수정이다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함 (검사의 거짓 양성) |
|
||||
| 관련 관점 | 27, 20, 21, 24, 8 |
|
||||
| 근거 | ① 매뉴얼은 예시 ID로 `invoice-feature`를 쓴다(1단계 `corepack pnpm create:feature invoice-feature`, 01:94. 11단계 `corepack pnpm test:sample-removal -- --feature=invoice-feature`, 01:626). ② 실행 16-R1(workflow env): 그 이름으로 만든 `--with-create --keyed` 기능의 11단계가 rc=1, 198초. 기준선 재작성, 타입, 테스트, 커버리지(`Risk coverage: PASS (418/418 production modules, 72 thresholds)`), CI 계약(`27 gates ... PASS`)은 통과했다. 실패는 `invoice-feature removal failed: fixture-id-residue: residue: tests/unit/create-feature.test.ts` 하나다. ③ 원인: 제품 기능의 잔여 패턴은 기능 ID와 폴더 이름의 대소문자 무시 부분 문자열이고(`scripts/test-sample-removal.ts:113-120`), 복사본의 `src`·`tests` 모든 파일의 경로와 내용에 건다(`:415-425`). 템플릿 소유 `tests/unit/create-feature.test.ts`가 `invoice-feature`를 53번 쓴다(생성 명령 단위 테스트의 예시 ID). ④ 같은 충돌이 나는 이름: 매뉴얼의 다른 예시 `notice-feature`(`tests/unit/registry-governance.test.ts:637`), `orders-feature`·`drafts-feature`(`tests/unit/create-feature.test.ts:27`), `shop-feature`·`home-feature`(`tests/architecture/context-route-roots.test.ts:59, 98`). 경계 없는 부분 문자열이라 `-feature`를 붙이지 않은 짧은 ID(예: `items`, `shop`)는 더 많은 파일에 걸린다(코드 추론). ⑤ 오류 안내는 "그 파일을 기능 폴더 안으로 옮기거나, 기능 ID를 담지 않게 한다"다(`docs/manual/reference/errors.md:197`). 그 파일은 템플릿 소유라, 따르면 템플릿 파일을 고치게 된다. ⑥ 생성 명령은 이 이름을 거절하지 않는다. 생성 드릴의 이름(`scaffold-feature`)은 템플릿 테스트에 없어 FE-GATE-020은 통과한다 |
|
||||
| 발생 조건 | 매뉴얼 예시 이름이나 템플릿 테스트·fixture에 나오는 이름으로 기능을 만들고 11단계를 돌릴 때 |
|
||||
| 영향 | 문서화된 제거 확인이 기능과 무관한 이유로 실패한다. 다른 검사는 다 통과했으므로 실제 잔여는 없다. 사용자는 이름을 바꾸거나(0단계는 "나중에 바꾸기 어렵다"고 적는다, 01:66) 템플릿 테스트를 고친다. 사용자 피해는 없고 merge 게이트도 막지 않는다 |
|
||||
| 심각도·우선순위 | Low · P2 — 제품 기능의 제거 드릴은 merge 게이트가 아니고, 실패 문구가 원인 파일을 말한다. 다만 매뉴얼 예시를 그대로 따른 사람이 마지막 단계에서 막히고, 같은 종류가 지난 X2 #1(예시 이름과 타입 검사 탐침 충돌)에 이어 두 번째다 |
|
||||
| 통제·증거 | 목표 M3(잔여 검사가 실제 잔여만 잡는다). 확인 M2(검사는 돌지만 템플릿 파일을 잔여로 셈) · E3(16-R1) |
|
||||
| 확실성과 남은 가정 | `invoice-feature`는 실행으로 확인했다. 다른 이름은 `git grep`과 잔여 패턴 코드로 판단했다 |
|
||||
| 결정의 근거 | 적용 제외 — 검사 범위를 좁히는 단순 수정이다. 고를 것은 범위뿐이다(아래) |
|
||||
| 이해 비용 | 실패를 본 사람이 잔여 패턴이 부분 문자열이고 템플릿 테스트도 훑는다는 것을 코드에서 알아야 한다 |
|
||||
| 최소 개선 방향 | 제품 기능의 잔여 검사를 "제거 전에 그 기능 ID를 담지 않던 파일"으로 좁힌다. 예: 드릴이 지우기 전에 같은 패턴으로 한 번 훑어 이미 걸리는 템플릿 파일을 제외 목록으로 잡는다. 함께 템플릿 테스트의 예시 ID를 예약 접두어(`typecheck-probe-*`처럼)로 바꾸고, 매뉴얼 예시는 그 접두어와 겹치지 않게 둔다. 생성 명령이 템플릿 테스트에 나오는 ID를 경고할 수도 있다 |
|
||||
| 대안 비교 | 적용 제외 — 단순 결함 수정 |
|
||||
| 단순화의 보존 조건 | 적용 제외 |
|
||||
| 비용·부작용 | 드릴 수십 줄, 테스트 예시 ID 교체 |
|
||||
| 재검토 조건 | 적용 제외 |
|
||||
| 완료 기준 | `create:feature invoice-feature --with-create --keyed` 뒤 `test:sample-removal -- --feature=invoice-feature`가 rc=0이다. 기능 ID를 담은 파일 하나를 `src/contracts/`에 남긴 변이에서는 여전히 실패한다 |
|
||||
| 검증 방법 | 16-R1을 다시 돌린다. 잔여 하나를 일부러 남긴 변이를 더한다 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
| 재검증 결과 | 해당 없음 |
|
||||
|
||||
## 4. 28개 관점 판정 (36.2)
|
||||
|
||||
판정: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역.
|
||||
|
||||
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | 코드 성숙도 | > 07·09. 생성 기능은 도메인 규칙이 없어 `domain/`을 만들지 않는다 | — | E1 | > |
|
||||
| **2** | **구조적 성숙도** | 적용(깊게) | M4 / M3 | E2 | **P** — 기능 경계 규칙이 생성 기능에도 돈다(드릴의 `check:architecture`, merge-48 FE-GATE-020). 기능 `contracts/`와 다섯 폴더 밖 폴더를 거친 어댑터 접근은 규칙이 없다(0929/12-03, 1101/16-06 남음). 오류 경계·`TelemetryPort` 두 벌(1101/16-05 남음) |
|
||||
| **3** | **변경 용이성** | 적용(깊게) | M3 / M3 | E3 | **P** — 손으로 다시 적는 칸 넷 중 둘이 검사를 얻었다(Envelope 섞임 거절, 스키마 메타 대조, `16-mut`). 뮤테이션 정책은 helper가 생겼다. 대신 기능마다 다시 쓰는 추적 파일 둘이 생겼다(16-01) |
|
||||
| **4** | **인지 부하** | 적용(깊게) | M1 / M1 | E1 | **P** — KEYED 쓰기 값 넷이 02 결정표와 `--keyed`로 정해졌다(1103/16-07). 생성 뒤 할 일(a11y 서명, merge 게이트, 초기 JS 기록, manifest 커밋)이 출력 `Next:`에만 모여 있고 03 문서와 다르다(16-01) |
|
||||
| 5 | 위험 가시성 | 적용 | M3 / M3 | E3 | P — Envelope 줄 하나 누락과 쓰기의 전부 누락은 조립이 거절한다(`16-mut` M1·M2). 읽기만 있는 기여의 전부 누락은 생성 gateway 테스트만 잡는다(1103/16-01 일부) |
|
||||
| 6 | 실패 성숙도 | > 03·07 | — | E1 | > — 생성 KEYED 작성의 409·503·400 경로 테스트가 생성된다(`scripts/create-feature-write-slice.ts:864-994`) |
|
||||
| 7 | 운영 성숙도 | - 이 영역 밖 | — | — | - |
|
||||
| 8 | 디버깅 가능성 | 적용 | M2 / M2 | E3 | P — 조립 거절이 두 operation과 고칠 방법을 말하고 `check:registries`가 그 이유를 싣는다(`16-mut`). 제거 드릴의 잔여 실패는 파일을 말하지만, 안내가 템플릿 파일 수정을 가리킨다(16-04). 뮤테이션 ID 불일치는 여전히 `MISSING_IDEMPOTENCY_KEY`·`UNEXPECTED_IDEMPOTENCY_KEY`다(1103/16-05 일부) |
|
||||
| **9** | **유지보수 성숙도** | 적용(깊게) | M1 / M1 | E1 | **P** — 같은 내용 사본: 백엔드 생성기 사실의 프론트 사본(16-02), `BUILD_INPUTS` 두 벌(15-03). 1101/16-05의 두 벌 넷 그대로. 기능 모양의 원본이 셋이다(`create-feature.ts` 1,813줄 + `create-feature-write-slice.ts` 1,044줄, 참조 기능). FE-GATE-020이 생성 결과를 merge 명령으로 돌려 컴파일·테스트 drift를 잡는다 |
|
||||
| 10 | 테스트 성숙도 | 적용 | M3 / M3(부분) | E3 | P — 생성 쓰기 기능이 비브라우저 merge 명령과 기능 제거를 FE-GATE-020에서 돈다. 설치 상태의 브라우저 게이트는 지금 통과하지만(16-R1) CI가 돌지 않는다(16-03). 제품 기능 제거의 잔여 검사가 거짓 양성을 낸다(16-04) |
|
||||
| 11 | 데이터 성숙도 | > 05 | — | — | > |
|
||||
| 12 | 동시성 성숙도 | > 03 | — | — | > — 생성 뮤테이션 정책은 `REJECT_WHILE_ACTIVE` |
|
||||
| 13 | 확장성 | 적용(기능 수 축) | M3 / M3 | E3 | P — 기능당 초기 JS를 기록과 상한으로 막는다. 쓰기 기능 둘(각각 새 context)이 204,523 / 204,800 B로 들어가고 여유 277 B가 남는다(16-R1). 셋째부터 예산 결정이 필요하다(추론, 1101/15-01, 15 영역) |
|
||||
| 14 | 성능 성숙도 | > 15 | — | E3 | > — 번들 게이트는 15 영역 |
|
||||
| 15 | 보안 성숙도 | > 03·13 | — | — | > |
|
||||
| 16 | 의존성 성숙도 | > 12·13 | — | — | > |
|
||||
| 17 | API / Contract | 적용 | M4 / M3 | E3 | P — operation은 descriptor 한 곳, FE-REG-API는 투영, 한 기여 안 응답 모양 섞임은 조립이 거절한다. 스키마 메타 설명 칸은 test:unit이 대조한다(`16-mut` M3). 백엔드 생성기 사실의 사본은 기계 대조가 없다(16-02) |
|
||||
| 18 | 배포 성숙도 | > 13 | — | — | > |
|
||||
| 19 | 설정 성숙도 | 적용(일부) | M1 / M1 | E1 | O — 앱 `MAX_RETRY_ATTEMPTS`가 `retryBudget`을 덮는다는 사실과 하네스 값이 02 결정표에 있다(`02-decision-tables.md:121-127`) |
|
||||
| 20 | 개발자 경험 | 적용 | M3 / M2 | E3 | P — 생성 명령 하나로 쓰기 기능이 손 수정 없이 merge 명령(브라우저 둘 포함, 16-R1)을 통과한다. 매뉴얼 예시 이름을 그대로 쓰면 11단계가 실패한다(16-04). 생성 뒤 커밋할 추적 파일과 충돌 처리가 문서에 없다(16-01) |
|
||||
| 21 | Guardrail 성숙도 | 적용 | M3 / M3(부분) | E3 | P — 새로 잡는 것: Envelope 섞임과 쓰기의 Envelope 누락, 스키마 메타 설명 칸, 낡은 dev manifest·초기 JS 기록, 제품 기능 제거. 아직 통과하는 것: 읽기만 있는 기여의 Envelope 전부 누락, 손으로 쓴 뮤테이션 ID, 기능 안 폴더 우회(0929/12-03, 12-R3 rc=0), 생성 기능의 브라우저 경로(16-03). 거짓 양성: 제거 드릴 잔여 검사(16-04) |
|
||||
| **22** | **추상화 성숙도** | 적용(깊게) | M3 / M3 | E3 | **P** — `commandMutationIdentity`는 descriptor에서 두 값을 받는 작고 맞는 helper다. 스키마 메타는 투영 대신 대조를 골라 칸이 남았다. 읽지 않는 라우트 `title`·`navigationLabel` 칸이 남았다(1103/16-06 일부) |
|
||||
| **23** | **일관성** | 적용(깊게) | M1 / M1 | E1 | **P** — 쓰기 slice가 Envelope 모양의 완성 예시가 됐다(지난 5.3 권고 (c)). 참조 기능은 problem details 모양으로 남았다(의도, 01:229-237). 03 문서·정본 표가 생성 명령이 바꾸는 파일을 다르게 말한다(16-01) |
|
||||
| **24** | **네이밍 / 의미** | 적용(깊게) | M1 / M1 | E1 | **P** — 뮤테이션 ID 불일치의 위반 이름(1103/16-05 일부). `typecheck-probe-*`는 주석으로만 예약됐다(`tests/unit/product-extension-typecheck.test.ts:28-29`). 매뉴얼 예시 이름이 템플릿 테스트의 이름과 겹친다(16-04). 1101/16-05의 같은 이름 두 타입 그대로 |
|
||||
| 25 | 조직 확장성 | 적용(구조 준비, 팀 1개) | M3 / M2 | E3 | P — 손으로 고치는 템플릿 파일은 없다. 지난 라운드 예외(접근성 spec 수정)는 사라졌다. 대신 기능마다 다시 쓰는 추적 파일 둘이 병렬 브랜치의 충돌 자리다(16-01) |
|
||||
| 26 | Ownership | > 14 | — | — | > |
|
||||
| **27** | **삭제 가능성** | 적용(깊게) | M3 / M2 | E3 | **P** — 제품 기능 제거 드릴이 동작하고 merge 게이트가 돈다(merge-48 FE-GATE-020 `scaffold-feature removal: PASS (17 checks)`, 지난 X 해소). 매뉴얼 예시 이름의 쓰기 기능은 다른 검사를 다 통과하고 잔여 검사의 거짓 양성으로 실패했다(16-R1, 16-04). 폴더 밖 잔여(a11y 기록, 기능 전용 e2e spec)는 드릴이 잡지 않고 03 손 목록에 있다(03:176-185). 그 목록은 초기 JS 기록을 말하지 않는다(16-01) |
|
||||
| 28 | 회복 가능성 | > 06·02 | — | — | > |
|
||||
|
||||
집계(이 영역): O 1 · P 16 · X 0 · ? 0 · > 10 · - 1. 지난 라운드 X 1개(27)는 P가 됐다.
|
||||
|
||||
## 5. 미검증
|
||||
|
||||
| 항목 | 이유 | 확인 방법 |
|
||||
|---|---|---|
|
||||
| 읽기만 있는 기여에서 Envelope 줄을 모두 지운 경우(1103/16-01 남은 부분) | 코드로 판단했다(`external-contract-runtime.ts:627-669`의 두 검사 모두 걸리지 않는다). 요청하지 않았다 | 기본 생성 판(GET 하나)에서 그 줄을 지우고 `check:registries`와 기능 테스트 |
|
||||
| FE-GATE-013(생성 기능 설치 상태) | `test:system`은 오케스트레이터가 따로 다룬다. 생성 기능과 무관한 전제(bubblewrap, cgroup)다 | 실제 CI 러너에서 생성 기능 브랜치로 FE-GATE-013 |
|
||||
| 실제 Gitea 러너의 merge job | desktop에서 workflow env를 준 것뿐이다 | 러너에서 생성 기능 PR 하나 |
|
||||
| 두 기능 브랜치의 실제 `git merge` 충돌(16-01) | git 상태를 바꾸는 실행을 하지 않았다. diff 구조로 판단했다 | 임시 clone에서 기능을 하나씩 더한 두 브랜치를 합친다 |
|
||||
| 매뉴얼만 보는 사람·에이전트의 재실험(X2 방식) | 이번 실행은 리뷰어가 생성 뒤 단계를 돈 것이다. 3~8단계 손 작업(계약을 실제 백엔드에 맞추기)은 하지 않았다. 1103 README §14.6도 "막힘 0"을 같은 방법으로 다시 재지 않았다 | 매뉴얼만 보는 에이전트가 생성 기능을 실제 계약으로 바꾸고 막힘을 센다 |
|
||||
| 실제 짝 백엔드 연결 | 백엔드를 띄우지 않았다. 생성 테스트의 손글씨 Envelope 본문과 백엔드 템플릿 코드를 대조했다 | 백엔드 `new-feature.sh Invoice`와 프론트 생성 기능을 같이 띄운다 |
|
||||
|
||||
## 6. 실행 기록
|
||||
|
||||
| 이름 | 명령 | 변이 | rc | 결과 | 잠금 대기 | 부하 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| `16-mut` | `bash /tmp/claude-gates/r4/mut/16-mut-cmd.sh`(상태마다 `corepack pnpm -s check:registries`, `node scripts/run-vitest.ts run tests/features/invoice-feature tests/unit/schema-metadata-policy.test.ts`, M2에서 `check:types`) · env: local | `16-gen-norecord.sh`: `create:feature invoice-feature --with-create --keyed`, `git add -A` | 0(73초) | 변이 전: registries rc=0(`11 registries PASS; compatibility=additive`), vitest 5파일 통과. M1 줄 하나 삭제: registries rc=1 `responseEnvelope NONE, but INVOICE_LIST_ITEMS ...`, vitest 4파일 실패. M2 세 줄 삭제: `check:types` rc=0, registries rc=1 `refusedBeforeWrite needs responseEnvelope ENVELOPE_V1`, gateway 11건·페이지 7건 실패(`SCHEMA_MISMATCH` 4, `SUCCESS_SCHEMA_INVALID` 2). M3a `direction`: registries rc=0, `InvoiceItemListPayload: row REQUEST, used as RESPONSE`. M3b `boundary`: registries rc=0, `row api-request, used as api-response`. M3c `unknownFieldPolicy`: registries rc=0, `row STRIP_UNKNOWN, validator REJECT_UNKNOWN`. **restored: clean at 8a442262** | 579초 | 시작 2.16 |
|
||||
| (취소) 첫 묶음 4개 | `16-feat-fast` 외 | — | — | 19:31에 잠금 대기 중 내가 멈췄다. 잠금을 잡지 않아 checkout을 건드리지 않았다 | — | — |
|
||||
| (취소) `16-feat-fast`, `16-feat-browser`, `16-feat-build`, `16-two-features` | merge 게이트 `ci:gate`, 제거 드릴, 둘째 기능 예산 | `16-gen.sh` | — | 잠금 대기 중 `Killed`, 뒤 호출은 `CLOSED`(exp.sh 닫힘). 잡은 적 없다. 배치 요청 16-R1로 바꿨다 | — | — |
|
||||
| 16-R1 (오케스트레이터 배치) | `bash /tmp/claude-gates/r4/mut/16-R1.sh` · env: CIENV. 안의 단계: `RECORD=0 bash 16-gen.sh`(`create:feature invoice-feature --with-create --keyed`, `git add -A`) → `corepack pnpm -s ci:gate FE-GATE-008` → `ci:gate FE-GATE-009` → `corepack pnpm -s test:sample-removal -- --feature=invoice-feature` → `create:feature order-feature --with-create --keyed`, `git diff -- public/release-manifest.json`, `corepack pnpm -s build`, `corepack pnpm -s check:bundle` | — (생성이 첫 단계) | 0(450초) | 생성: 폴더 밖 새 파일 4, 수정 `M public/release-manifest.json`. FE-GATE-008 rc=0 186초(e2e 211 통과·3 skip, capability 66, `Browser capability evidence: PASS (22 cases x 3 engines, zero skipped)`, storybook 1, visual 6). FE-GATE-009 rc=0 60초(69 통과, `/invoice`·`/invoice/items/a11y-1`·`/invoice/new` × 3 엔진, `Manual accessibility record format: PASS (13 routes ...)`). 제거 드릴 rc=1 198초: `fixture-id-residue: residue: tests/unit/create-feature.test.ts`(다른 검사는 통과). 둘째 기능: `setDigest` 줄 다시 바뀜, `packages`에 `@org-contracts/order`. build rc=0, `Bundle budget: PASS (initial JS 204523 / 204800 gzip bytes, 26 / 32 files)`. **restore clean**(8a44226) | 배치 | 시작 3.26, FE-GATE-008 중 14.09 |
|
||||
|
||||
인용한 다른 실행(같은 커밋):
|
||||
|
||||
| 출처 | 내용 |
|
||||
|---|---|
|
||||
| 오케스트레이터 `merge-48`(CI=true) | FE-GATE-020 rc=0 1,156초: `reference-feature removal: PASS (31 checks)`, `scaffold-feature removal: PASS (17 checks)`, `feature scaffold: PASS (77 checks)`, optional-recipe·browser-file-storage·realtime 제거 PASS. FE-GATE-001~012 rc=0. FE-GATE-013 rc=1(오케스트레이터가 판정. 이 영역 경로와 무관) |
|
||||
| 오케스트레이터 `gates/`(로컬 env) | `check:architecture`·`check:types`·`lint`·`test:unit`·`test:component`·`test:integration`·`test:contract`·`test:runtime-schema`·`check:adapter-inventory` rc=0. `verify:documentation` rc=1: desktop의 짝 백엔드 사본이 `ef947e5`라 `../clean-architecture-backend-template/docs/web/http-contract.md`가 없다(`docs/manual/01·02·04·README`가 이름을 든다). 이 영역 결함이 아니다(1103/12-05 소관, 오케스트레이터가 판정) |
|
||||
| 영역 15 `15-lab`, `15-feature` | 템플릿 202,927 / 204,800 B, 26 / 32 파일. `create:feature bulletin-feature --with-create --keyed`(새 context) 뒤 203,903 B(+976 B, 여유 897 B), 26 파일. 둘 다 restored clean |
|
||||
| 영역 12 `12-R3`, 영역 11 `11-R8b` | 12-R3: 기능 안 `support/` 폴더를 거친 어댑터 import에 `check:architecture` rc=0, eslint rc=0(0929/12-03 남음). 11-R8b: 생성 목록 빈 상태에만 이름 없는 button을 넣자 `/sample`만 세 엔진 실패, 상세·작성 통과(목록이 빈 상태로 검사됨). 둘 다 restore clean |
|
||||
|
||||
## 7. 새 발견 요약
|
||||
|
||||
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|
||||
|---|---|---|---|---|
|
||||
| 16-01 | Low · P2 | 구조적 위험 | 기능 하나를 더하면 추적 파일 `public/release-manifest.json`(자동)과 초기 JS 기록(명령)이 바뀌고, 03 문서·정본 표는 이를 말하지 않으며, 기능 브랜치 둘이 같은 줄에서 충돌한다 | `scripts/create-feature.ts:1753-1754, 1787-1796`, `docs/manual/03-outside-feature-folder.md:22`, `docs/architecture/starter-experience.md:215-226` |
|
||||
| 16-02 | Low · P3 | 구조적 위험 | 쓰기 slice가 백엔드 생성기 템플릿의 사실 넷을 손으로 옮겼고, pin·drift 검사는 `http-contract.md`만 본다 | `scripts/create-feature-write-slice.ts:58-59, 83-84`, `config/contracts/backend-contract-pin.json:6-7`, `scripts/check-backend-contract-drift.ts:60` |
|
||||
| 16-03 | Low · P2 | 구조적 위험 | 생성 기능을 설치한 상태로 브라우저 merge 게이트(FE-GATE-008·009)를 도는 장치가 없다 | `scripts/lib/feature-scaffold-drill.ts:18-37` |
|
||||
| 16-04 | Low · P2 | 확인된 결함 | 제품 기능 제거 드릴의 잔여 검사가 템플릿 테스트의 글자를 잔여로 잡아, 매뉴얼 예시 이름 `invoice-feature`로 만든 기능의 11단계가 실패한다. 안내는 템플릿 파일 수정이다 | `scripts/test-sample-removal.ts:113-120, 415-425`, `tests/unit/create-feature.test.ts:53`, `docs/manual/01-add-a-feature.md:94, 626`, `docs/manual/reference/errors.md:197` |
|
||||
@@ -0,0 +1,507 @@
|
||||
# 성숙도 리뷰 — 2026-11-05 (4라운드)
|
||||
|
||||
> 기준: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`. 대상: `8a44226`(= main `409d72e` 트리. 메인 세션이 `git diff --quiet`로 같은 트리임을 확인했다). 이 커밋은 2026-11-03 리뷰의 조치(README 14절)를 모두 담는다. 영역은 2026-11-03 리뷰의 16개를 그대로 썼다. 영역 에이전트는 노트북 worktree에서 코드를 읽었다. 실행은 모두 desktop checkout 하나에서 했다(10.4절). 이 문서는 오케스트레이터가 결과를 모은 것이다. 새 P1 세 건은 오케스트레이터가 코드를 직접 다시 읽었다. 리뷰 중 코드는 고치지 않았다.
|
||||
>
|
||||
> 메인 세션이 따로 물은 네 가지(§14.4 건수, 11-10의 12 px 늘어남, 11-08·11-09·11-10 수정이 검사를 약하게 했는지, FE-GATE-013의 user namespace 전제)의 답은 3절에 있다.
|
||||
|
||||
## 0. 평가 전제 (가이드 0.1)
|
||||
|
||||
| 전제 | 기록 | 판정에 미치는 영향 |
|
||||
|---|---|---|
|
||||
| 사용 목적 | 프론트엔드 템플릿(reference implementation). 짝 백엔드 템플릿과 함께 써서 desktop 서버에 서비스를 빨리 출시하는 시작점(`PRODUCT.md`) | 다운스트림이 그대로 복제하는 기본값과 문서가 판정 대상이다 |
|
||||
| 사용자와 팀 | 작성자 1명 + AI 세션. 다운스트림 2개(tech-log, memento) | 템플릿 파일을 고쳐야 하는 지점은 동기화 비용이 된다 |
|
||||
| 지원 실행 형태 | 브라우저 SPA + 정적 호스팅 + 선택형 Service Worker. SSR 없음 | 서버 메모리 상태·다중 인스턴스 경쟁은 적용 제외. 탭 사이 경쟁은 적용 |
|
||||
| 데이터와 권한 | 세션(짝 백엔드 인증), 선택형 OPFS 개인 파일, 공개 캐시. 관리자·테넌트 기능 없음 | 로그아웃·계정 삭제 뒤 남는 데이터가 주된 피해 경로다 |
|
||||
| 규모 목표 | 기능 수 증가 축만 있다. 초기 JS 204,800 B(gzip), 초기 파일 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 등). 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)에서 항상 실패하고, 사전 점검은 PASS를 낸다(12-01) |
|
||||
| `create:feature`로 기능을 더하고 템플릿 CI로 머지 | 조건부 사용 가능 | 쓰기 기능 하나를 더해도 FE-GATE-008·009가 수정 없이 통과했다(16-R1). 다만 기능에 제품 capability를 주면 FE-GATE-005가 항상 실패한다(09-01, 두 다운스트림 모두 해당). 매뉴얼 예시 이름(`invoice-feature`)으로 만든 기능은 제거 드릴이 실패한다(16-04) |
|
||||
| 다운스트림(tech-log·memento)에 이 묶음 전파 | 조건부 사용 가능 | CHANGELOG 6단계대로 예제 기능을 지우면 문서 검사가 실패한다(14-01). 이행 안내가 실제 변경의 일부만 다룬다(1103/14-02 일부) |
|
||||
| 짝 백엔드에 붙는 쓰기 폼 | 조건부 사용 가능 | 선언한 업무 거절은 다시 저장할 수 있다(1103/03-01). 거절 이유가 안 보이고, 회복 필요 응답 뒤 재전송 버튼이 남는다(1103/03-01 일부, Medium·P2). hook을 직접 쓰면 키 없는 쓰기를 같은 입력으로 다시 보낸다(0929/03-03 일부, Medium·P2) |
|
||||
| 짝 백엔드와 파일 업로드 | 조건부 사용 가능 | 빈 파일 거절(202 `REJECTED`)을 스키마 불일치로 읽는다(01-01). 504 `TRANSFER_TIMEOUT` 뒤 재시도가 파일을 둘 만들 수 있다(01-02). 실제 짝 백엔드로 올려 본 적이 없다 |
|
||||
| 짝 백엔드 인증에 세션 붙이기 | 조건부 사용 가능 | Redis session 모드를 recipe·매뉴얼대로 이으면 서버 401이 세션 owner에 닿지 않는다(09-02). 실제 Keycloak·Redis 연동 미확인(1103/09-03 일부) |
|
||||
| OPFS에 개인 파일 저장 | **사용 보류** | 계정 삭제 purge가 다른 탭이 저장 중인 파일을 놓치고 "다 지웠다"고 보고한다(1103/05-01 일부, 개인 파일 제품에 P1). 지난 §14.4의 "고침"은 틀렸다 |
|
||||
| release 단계(`RELEASE_READY`)까지 | 조건부 사용 가능 | lab 게이트 통과(146 ms). release job이 gate 로그를 올리지 않아 실패 이유와 의존성 advisory 신호가 실제 run에서 사라진다(13-01). advisory 2건은 결정 대기(1103/13-03) |
|
||||
| 배포 슬롯을 채워 자동 배포 | 조건부 사용 가능 | 제품 merge 검사가 실패해도 같은 run의 release·배포가 진행된다(13-02). 13-01·13-03 |
|
||||
| 빌드 → 공개 대상 승인 → 손으로 배포 | 사용 가능 | 실제 nginx 1.27.5에 템플릿 예시 그대로 FE-GATE-019가 후보를 통과시키고, 같은 run 재빌드·`http2`·`gzip` 누락을 거절한다(13-R02) |
|
||||
| 짝 백엔드 Envelope 조회 화면 | 사용 가능 | `meta.page`를 넘긴다(1103/03-02 일부: bulk만 미지원) |
|
||||
| opt-in realtime(SSE·WS)·bounded polling | 조건부 사용 가능 | poll 1회 = 요청 1회(04-R1). 결정 대기 0929/04-03, SSE EOF 0929/04-02 |
|
||||
| SW `ACTIVE`·Web Push | 조건부 사용 가능 | Firefox quarantine 아직 필요(06-R11). 06 영역 Low 3건 |
|
||||
| 셸·디자인 시스템·읽기 화면 | 사용 가능 | 08 영역 Low 4건 |
|
||||
|
||||
## 2. 차단 항목 (36.5-3)
|
||||
|
||||
### 2.1 새 High — 없음
|
||||
|
||||
### 2.2 새 P1 (3건, 모두 Medium)
|
||||
|
||||
| ID | 내용 | 위치 | 재확인 |
|
||||
|---|---|---|---|
|
||||
| [09-01](09-app-core.md) | 1103/09-02 수정이 더한 제품 확장 타입 검사 탐침이 복사본의 `product-contracts.ts`·`product-composition.ts`를 탐침 내용으로 통째로 덮어쓴다. 기능에 제품 capability를 주는 다운스트림에서는 FE-GATE-005가 항상 실패한다 | `tests/unit/product-extension-typecheck.test.ts:41-83`, `:181-193`; `src/bootstrap/runtime-adapters.ts:689-697` | **오케스트레이터 확인.** `product-capabilities.ts`는 덧붙이지만(`:185`) 나머지 둘은 `PRODUCT_CONTRACTS`·`PRODUCT_COMPOSITION` 상수로 바꾼다(`:186-187`). `composeProduct`가 `typecheckProbeSettings`만 돌려주므로 제품 capability가 빠진다. 에이전트 실험 09-probe-downstream: 같은 상태에서 tsc app·node·test는 rc=0, 탐침만 TS2741(`runtime-adapters.ts(695,5)`) |
|
||||
| [12-01](12-guardrails-ci.md) (+ [11-02](11-tests-browser-release-scale.md)) | FE-GATE-013이 비특권 user namespace(bwrap `--unshare-net`)를 전제하는데 러너 요구 목록·gate 정의·사전 점검 어디에도 없다. 이 desktop에서 사전 점검은 PASS를 내고 provider test 18건이 bwrap 원문 오류로 실패한다 | `scripts/check-system-test-prerequisites.ts:15-38`, `scripts/run-and-validate-provider.ts:254-256`, `docs/operations/ci-quality-gates.md:181-185` | **오케스트레이터 확인 + 실행.** 사전 점검은 실행 파일·cgroup·systemd bus만 보고 bwrap을 한 번도 실행하지 않는다. 요구 목록(`ci-quality-gates.md:181-185`)은 bwrap·`--size` 지원·cgroup을 적지만 user namespace·네트워크 namespace는 없다. 유일한 기록은 2026-08-15 운영 원장의 한 번 관찰 메모다(`docs/operations/adapter-remediation-ledger.md:531-546`). merge-48 FE-GATE-013: 18 failed / 96 passed (114), 12건 `bwrap: loopback: Failed RTM_NEWADDR`, 6건은 그 provider를 기다린 시간 초과. desktop `kernel.apparmor_restrict_unprivileged_userns = 1`. 11-R10: repo 없이도 `bwrap --unshare-net /bin/true`가 같은 오류 |
|
||||
| [13-01](13-build-release-supply-chain.md) | release 단계 job `immutable_build`가 FE-GATE-015·027의 gate 로그와 advisory 기록을 올리지 않는다. `ci:gate`는 명령 출력을 로그 파일에만 쓰므로 실제 run에서는 release 실패 이유와 1103/13-03의 advisory 신호가 사라진다 | `.gitea/workflows/quality-gates.yml:122-207`, `scripts/run-ci-gate.ts:148-150`, `:209-213`, `:243-249` | **오케스트레이터 확인 + 배치 실행.** 다른 gate job은 `if: always()`로 `artifacts/`를 올린다(`quality-gates.yml:114-120`). `immutable_build`의 upload는 후보 tar 하나뿐이고 성공 경로에만 있다(`:202-207`). 13-R01: FE-GATE-027 console은 2줄(PASS), `POLICY_VIOLATION`과 경고 4줄은 로그 파일에만 있었다 |
|
||||
|
||||
세 건 모두 "사용자 피해 없이 merge·release 게이트가 틀린 답을 내거나 이유를 숨긴다"는 지난 라운드 기준(1103 README 2.3절, 02-06)으로 Medium·P1이다.
|
||||
|
||||
### 2.3 이월 항목 중 남은 큰 것
|
||||
|
||||
| ID | 지난 등급 | 지금 | 남은 부분의 등급 |
|
||||
|---|---|---|---|
|
||||
| 1103/05-01 | Medium·P2 (OPFS 개인 파일 제품 P1) | 일부. 지난 §14.4 "고침"은 틀렸다 | Medium·P2, OPFS 개인 파일 제품 P1 |
|
||||
| 1103/03-01 (= 08-01) | High·P1 | 일부. 완료 기준 넷은 충족 | Medium·P2 (거절 이유 표시, 회복 필요 응답 뒤 재전송 버튼) |
|
||||
| 0929/03-03 | High·P1 | 일부. 버튼·hook 재전송은 막혔다 | Medium·P2 (같은 입력 재제출. 템플릿 폼은 막는다. 오케스트레이터가 `application-query.ts:557-561`, `:590-596`, `use-app-form.ts:325`를 읽어 확인) |
|
||||
| 1103/01-01 | High·P1 | 일부. client와 문서는 들어왔다 | 미검증(실제 짝 백엔드 업로드) + 새 01-01·01-02(Medium·P2) |
|
||||
| 1103/13-03 | Medium·P1 | 일부, 결정 대기 | Medium·P1 그대로 |
|
||||
| 1103/09-04, 1103/03-07 | Medium·P2, Low·P3 | 결정 대기 | 그대로 |
|
||||
|
||||
### 2.4 심각도 조정과 합침
|
||||
|
||||
| ID | 영역 제안 | 최종 | 이유 |
|
||||
|---|---|---|---|
|
||||
| 12-01 + 11-02 | 12: Medium·P1, 11: Low·P3 | 12-01 Medium·P1 하나 | 같은 사전 점검(`check-system-test-prerequisites.ts:15-38`)과 같은 실패. 11 영역은 "desktop만의 조건"으로 낮췄다. 하지만 이 desktop은 사용자 목표의 배포 서버이고, 러너 요구 목록에 이 조건이 없어 어떤 러너가 해당하는지 알 수 없다. 메인 세션의 정지 기준(merge 14개 통과)을 직접 막는다 |
|
||||
| 01-02 | Medium·P2 | 그대로 | 결과 불명 쓰기의 재실행(가이드 35.2 High 예시)과 모양이 같다. 그러나 백엔드가 `TRANSFER_TIMEOUT`을 `retryable=true`, `ambiguous=false`로 선언한다(`BlockingTransferExecutor.java:64-79`, `FileserverFailureContext.java:13-20`). client는 백엔드 선언을 따른다. 남는 위험의 주인은 두 repo 계약이다 |
|
||||
| 0929/03-03 남은 부분 | High·P1 → Medium·P2 (03 영역) | Medium·P2 | 템플릿이 그리는 경로(폼·페이지)는 모두 막는다. 남은 길은 제품이 hook을 직접 부를 때뿐이다 |
|
||||
|
||||
## 3. 메인 세션이 물은 네 가지
|
||||
|
||||
### 3.1 §14.4 "그 밖의 81건"
|
||||
|
||||
- 1103 색인은 95건이다. 2절 차단 항목에만 있는 0929/03-03을 더하면 96건이다. §14.4가 ID로 적은 것은 35건이다. 그래서 나머지는 81건이 아니라 **61건**이다. 81은 셈이 틀렸다.
|
||||
- 96건 전부를 ID별로 다시 판정했다(13절 표). **고쳐짐 74 · 일부 22 · 남음 0.**
|
||||
- §14.4가 "고침"이라 적었지만 지금 "일부"인 것이 **13건**이다. 01-01, 03-01, 0929/03-03, 05-01, 11-01, 11-02, 11-03, 11-04, 14-01, 14-02, 15-02, 16-01, 16-05.
|
||||
- 이 중 05-01·14-01·14-02·16-01·16-05·11-03·11-04 7건은 "그 밖의 61건"에 들어 있었다. 61건 중 54건은 고쳐졌다.
|
||||
- 11-02·11-03·11-04는 코드는 들어왔지만 완료 기준 실행이 없다. 가이드 35.6에 따라 "일부"로 둔다.
|
||||
- §14.4가 "일부"라고 한 9건은 지금도 일부다. 03-02, 03-07, 07-04, 09-03, 09-04, 09-05, 12-05, 13-03, 16-06.
|
||||
- 지난 판정이 틀렸던 것이 하나 더 있다. 1103/14-04는 FE-GATE-017을 merge 게이트라고 적었지만 문서 단계 게이트다. 결함 자체는 맞았다(14 영역).
|
||||
|
||||
### 3.2 11-10의 12 px 늘어남 — 첫 화면의 layout shift인가 (15 영역)
|
||||
|
||||
- **무엇이 늘어나나.** 라우트 로딩 화면(280 px)이 홈 화면(660 px)으로 바뀐다. 셸 내용 줄이 648 px라 문서 높이가 720 → 732 px가 된다. dev server와 production build(`vite preview`), 세 엔진 모두 같다.
|
||||
- **스크롤바를 숨긴 조건(모든 게이트의 Chromium)에서는 layout shift가 아니다.** preview 8회에서 `layout-shift` 항목 0건. Firefox·WebKit ResizeObserver 기록에서도 화면에 보이는 것이 움직이지 않는다. 늘어난 부분은 화면 아래다.
|
||||
- **실제 스크롤바가 있으면 작은 shift가 있다.** 홈 첫 렌더가 세로 스크롤바를 만들어 header가 15 px 밀린다. CLS 0.0002(1280×720, 1366×657). 1920×960에서는 0이다(15-R2). → **새 15-05(Low·P3).**
|
||||
- **관점 10·21: 어떤 게이트도 이것을 보지 못한다.** 게이트의 Chromium은 스크롤바를 숨긴다. lab은 `/`의 CLS만 재고, 클릭 뒤 500 ms 안의 shift를 뺀다. lab 대상 화면 자체도 제목 뒤 21 px를 민다(CLS 0.0046, 새 15-01 Low·P3). dev에서만 스타일 없는 부팅 셸이 0.00625 shift를 낸다(production에는 없다).
|
||||
- 결론: 사용자에게 보이는 첫 화면 문제는 작다(Low). 11-10 test 실패의 원인은 test가 그리는 중인 앱 뒤에 버튼을 붙인 것이었다. 지금 고정 층 수정으로 막혔다(3.3절).
|
||||
|
||||
### 3.3 11-03 뒤 수정이 검사를 약하게 했나 (변이로 확인)
|
||||
|
||||
| 수정 | 확인 | 결과 |
|
||||
|---|---|---|
|
||||
| 11-08 `b693600` 로컬 빌드 환경 | 13-R01: CI=true에서 `VITE_COMMIT_SHA`·`SOURCE_DATE_EPOCH`·`CI_RUNNER_IMAGE`를 빼거나 틀린 값으로 준 release 빌드·gate 14가지 | **약화 없음.** 14가지 모두 기대한 문구로 실패. release job에 `CI` 바인딩을 넣거나 생성 workflow를 손으로 고치면 `check:ci`가 거절(13-R03·R04). 수정을 되돌리면 CI=true 테스트가 실패(13-R05·R06). 로컬 빌드 표시는 test helper와 Playwright 설정만 쓴다 |
|
||||
| 11-09 `aad005c` preload 사용 검사 | 11-R1(검사가 실패를 돌려주지 않게), R2(평가 표시 제거), R4(대조 probe), R5(허용 spec 넷 안에 안 쓴 preload 하나) | **검사는 실패해야 할 때 실패한다.** R1·R2·R5 모두 실패, R4 대조는 세 엔진 모두 probe 실패. WebKit 무시는 정확한 문구 하나뿐이다. **약한 곳 둘:** strict fixture가 그 결과를 버려도 커밋된 test가 하나도 실패하지 않는다(11-R3, 새 11-01 Low·P2). SW가 페이지를 제어하면 허용 규칙이 preload 검사를 모두 끈다(06-R9에서 158줄 모두 ALLOWED, 새 06-03 Low·P3). 지금 워커 결함을 가리지는 않는다(06-R10) |
|
||||
| 11-10 `ee37dd8` 고정 층 | 11-R6(수정 + mousedown 때 앱 400 px 늘림), R7(수정 되돌림 + 같은 늘림) | **약화 없음.** R6 통과, R7 실패(RED가 돌아온다). 고정 층은 test가 붙이는 control에만 쓰이고 제품 화면 검사는 그대로다 |
|
||||
| 그 밖의 수정 | 영역별 `git diff e40684b..8a44226` | 약해진 검사 한 건: 1103/14-04 수정이 참조 기능 경로 26줄을 백틱에서 빼 문서 검사 밖으로 냈다(새 14-03 Low·P3). 초기 파일 상한 25 → 26 → 32는 이유가 기록됐고 템플릿 자신의 파일 수는 정확히 대조한다(12·15 영역) |
|
||||
|
||||
### 3.4 FE-GATE-013의 user namespace 전제는 위험으로 적혀 있나
|
||||
|
||||
**적혀 있지 않다.** 러너 요구 목록(`docs/operations/ci-quality-gates.md:181-185`), `config/ci/gates.json`의 FE-GATE-013 정의, 생성 workflow, 사전 점검(`scripts/check-system-test-prerequisites.ts:15-38`) 어디에도 없다. 운영 원장에 한 호스트에서 본 일로만 남아 있다(`docs/operations/adapter-remediation-ledger.md:531-546`, "16 of the 108 provider tests cannot run here"). 위험으로 올린 기록이 아니다. → 12-01(Medium·P1, 2.2절).
|
||||
|
||||
## 4. 새 발견 건수 — 지난 라운드와 비교
|
||||
|
||||
| 구분 | 이번(2026-11-05) 새 발견 | 2026-11-03 리뷰 당시 | 2026-11-03 최종 색인(리뷰 뒤 추가 7건 포함) |
|
||||
|---|---|---|---|
|
||||
| 합계 | **48** | 88 | 95 |
|
||||
| 심각도 | High 0 · **Medium 11** · Low 37 | High 2 · Medium 34 · Low 52 | High 2 · Medium 41 · Low 52 |
|
||||
| 우선순위 | **P1 3** · P2 15 · P3 30 | P1 12 · P2 38 · P3 38 | P1 19 · P2 38 · P3 38 |
|
||||
| 성격 | 확인된 결함 25 · 구조적 위험 19 · 개선 제안 4 | 확인된 결함 55 · 구조적 위험 23 · 개선 제안 10 | 확인된 결함 62 · 구조적 위험 23 · 개선 제안 10 |
|
||||
|
||||
- 2026-11-03은 이 밖에 이월 0929/03-03을 High·P1로 올렸다(색인 밖).
|
||||
- 이번 48건은 영역 문서 47건에서 같은 결함 1건(11-02 → 12-01)을 합치고, 오케스트레이터 발견 2건(12-04, 10-03, 14절)을 더한 수다.
|
||||
- 이번 새 발견 중 영역 문서가 원인을 지난 라운드 수정으로 짚은 것: 01-01~01-04(새 Fileserver client), 02-01~02-04, 03-01, 04-01·04-02, 07-01(D6 pin), 08-03·08-04, 09-01~09-03, 10-01, 11-01, 12-02, 14-03, 16-01.
|
||||
|
||||
## 5. 확인된 강점 (36.5-2)
|
||||
|
||||
- **merge 게이트 13/14가 CI env에서 통과했다**(desktop, run 48). FE-GATE-005: unit 2,883·coverage 3,869건. FE-GATE-008: e2e 202(3 skip)·capability 66·storybook 1·visual 6. FE-GATE-012: 초기 JS 202,973 / 204,800 B, 26 / 32 파일. FE-GATE-020: 제거·생성 드릴 모두 PASS. FE-GATE-013의 test:system 뒤 명령 7개도 모두 rc=0.
|
||||
- **지난 High 세 건의 핵심 경로가 변이로 지켜진다.** 03 영역 변이 19개 전부 검출(지난 라운드 생존 M1·M3·M6·M7 포함). 생성한 NEVER 쓰기 기능에서도 선언 누락·재전송 가드 변이가 잡힌다(03-R02).
|
||||
- **수정을 지키는 테스트가 실제로 잡는다.** 02 영역 수정 규칙 변이 23/23, 05 영역 10/10, 06 영역 7/7, 07 영역 26종, 08 영역 5종, 13 영역 음성 실행 14가지가 기대대로 실패했다.
|
||||
- **lab 게이트가 다시 통과한다.** 상호작용 중앙값 146 ms(지난 227 ms), LCP 2,032 ms, CLS 0(1103/15-01 고쳐짐).
|
||||
- **기능 추가 경로가 브라우저 게이트까지 닿는다.** `--with-create --keyed` 기능 하나를 넣고 FE-GATE-008·009가 수정 없이 통과했다. 쓰기 기능 둘도 초기 JS 예산 안에 든다(204,523 / 204,800 B, 16-R1).
|
||||
- **실제 nginx에서 호스팅 계약이 동작한다.** 템플릿 예시 그대로 FE-GATE-019가 후보를 통과시키고 같은 run 재빌드, `http2 on;`·`gzip on;` 누락을 각각 거절했다(13-R02).
|
||||
|
||||
## 6. 반복되는 원인 (36.5-4)
|
||||
|
||||
1. **수정을 템플릿 원래 상태나 작은 입력으로만 확인했다.** 1103/05-01 수정 테스트는 객체 0~1개만 쓴다. 3개 이상이면 놓친다. 09-01 탐침은 제품 파일이 비어 있는 템플릿에서만 맞다. 16-04는 템플릿 테스트의 글자가 제품 기능 이름과 부딪친다. 14-01은 예제 기능을 지운 상태를 아무 게이트도 돌지 않는다. 16-03은 기능을 설치한 상태로 브라우저 게이트를 도는 장치가 없다. 지난 라운드 원인 2가 모양을 바꿔 남았다.
|
||||
2. **두 템플릿 사이 사실을 손으로 옮긴다.** Fileserver client의 효과 표(01-02), 202 `REJECTED`(01-01), 답 표 JSON(07-01), 생성기의 백엔드 사실 넷(16-02), rate-limit 503(03-02). pin과 drift 검사는 `http-contract.md` 글자만 비교하고 게이트 밖이다.
|
||||
3. **게이트가 실행 환경을 말없이 가정한다.** user namespace(12-01), 옆 백엔드 checkout(12-02), 고정 출력 경로·포트(12-04), 숨긴 스크롤바(15-05). 가정이 깨지면 원인 없는 실패나 기계마다 다른 결과가 나온다.
|
||||
4. **실패 이유가 남지 않는다.** release job 로그(13-01), scope closer 던짐(02-01), poll `execute` 던짐(04-02), 사전 점검 PASS 뒤 원문 bwrap 오류(12-01).
|
||||
5. **수정이 새 결함을 만든다.** 4절 끝 목록. 수정 커밋마다 "이 변경이 무엇을 새로 가정하는가"를 묻는 단계가 없었다.
|
||||
|
||||
## 7. 결정이 필요한 것
|
||||
|
||||
| 번호 | 결정 | 선택지 | 관련 | 결정할 사람 |
|
||||
|---|---|---|---|---|
|
||||
| D1 | 운영 advisory 2건 | zod 4.6.x(+약 7 KB, 예산 초과) / react-router 갱신 / 위험 수용과 재검토일 | 1103/13-03, 13-01 | 프론트 소유자 + reviewer |
|
||||
| D2 | 플랫폼 구성 화면 | (가) 플랫폼 진단 화면으로 인정 (나) 기능으로 옮기고 라우트 청크 병렬화 뒤 재측정 | 1103/09-04 | 프론트 소유자 |
|
||||
| D3 | 백엔드 생성기 목록 GET | 백엔드에 추가 / 프론트 생성기에서 제외 | 1103/03-07 | 두 repo 소유자 |
|
||||
| D4 | FE-GATE-013 러너 전제 | (가) 러너 요구에 비특권 user namespace를 적고 사전 점검이 bwrap을 실제로 돌린다 (나) 샌드박스 방식을 바꾼다 | 12-01 | 프론트 소유자 |
|
||||
| D5 | 제품 merge 검사와 release의 관계 | 제품 gate를 release `needs`에 묶는 칸을 연다 / 문서로 제한 명시 | 13-02 | 프론트 소유자 |
|
||||
| D6 | 실행 격리 | 실행별 출력 디렉터리 + 빈 포트 / "한 checkout 한 실행"을 문서로 명시 | 12-04 | 프론트 소유자 |
|
||||
|
||||
## 8. 미검증 (36.5-5)
|
||||
|
||||
| 항목 | 이유 | 확인하려면 |
|
||||
|---|---|---|
|
||||
| 실제 Gitea 러너 결과 | Actions가 꺼져 있다(U-1). 이번 결과는 desktop에 workflow env를 준 것이다. `CI_RUNNER_IMAGE`는 형식만 맞춘 값이다 | runner 1대와 PR 1건 |
|
||||
| 실제 짝 백엔드 연동(업로드, 세션) | 백엔드는 읽기만 했다 | 백엔드를 띄워 업로드·로그인·401 한 번씩 |
|
||||
| 셸 CSS 변경을 시각 계약이 여전히 잡는가 | 12-R2 변이(header padding)가 grid 높이 고정 때문에 화면을 바꾸지 않았다 | 화면이 바뀌는 CSS 변이로 다시 |
|
||||
| `test:system` 완료 기준(1103/11-03·11-04) | desktop 호스트가 user namespace를 막는다(12-01) | user namespace를 허용하는 호스트에서 한 번 |
|
||||
| 빈 러너의 시각 글꼴(1103/11-02) | 러너가 없다 | runner 1대 |
|
||||
| 매뉴얼만 보는 기능 추가 재실험(X2) | 이번 범위 밖 | 매뉴얼만 받은 에이전트 1회 |
|
||||
| 10 영역 변이 C, 부하 중 EOF 대조 | 19:55에 줄에서 취소됐다 | 배치 1항목 |
|
||||
|
||||
## 9. 개선 순서 (36.5-6)
|
||||
|
||||
| 순서 | 항목 | 최소 변경 | 완료 기준 |
|
||||
|---|---|---|---|
|
||||
| 1 | 09-01 | 탐침이 제품 파일을 덮지 않고 복사본의 실제 내용에 덧붙이거나, 탐침 전용 경로로 조립한다 | 제품 capability를 쓰는 기능이 있는 복사본에서 FE-GATE-005 통과 |
|
||||
| 1 | 12-01 | 사전 점검이 provider와 같은 bwrap 옵션으로 `/bin/true`를 돌려 실패하면 원인과 함께 멈춘다. 러너 요구 목록에 user namespace를 적는다(D4) | desktop에서 사전 점검이 "user namespace" 문구로 실패한다. 허용 호스트에서 114/114 |
|
||||
| 1 | 13-01 | `immutable_build`에 `if: always()` gate 로그 upload를 더한다 | release gate 실패가 업로드된 로그에 남는다 |
|
||||
| 1 | 1103/05-01 남은 부분 | purge가 journal 집계와 객체 목록을 같은 잠금 아래에서 다시 대조하거나 끝난 뒤 한 번 더 센다. 객체 3개 이상 테스트 | 객체 3·8개 + 다른 탭 put에서 `COMPLETED`가 나오지 않는다 |
|
||||
| 2 | 12-04, 12-03 | 실행별 출력·포트 격리. CLAUDE.md 리뷰 게이트 목록을 merge stage `gateIds`로 바꾼다 | 한 checkout에서 두 게이트가 동시에 통과 |
|
||||
| 2 | 14-01, 16-04, 16-03 | 예제 기능 제거 상태와 기능 설치 상태를 드릴로 돈다 | CHANGELOG 6단계 뒤 문서 검사 통과, 매뉴얼 예시 이름으로 제거 드릴 통과 |
|
||||
| 2 | 01-01, 01-02, 09-02 | 짝 백엔드 실제 응답으로 client 판정을 맞춘다. 쿠키 recipe가 `onCredentialRejected`를 잇는다 | 백엔드를 띄운 업로드·401 시나리오 |
|
||||
| 2 | 1103/03-01·0929/03-03 남은 부분 | 거절 문구 자리, 회복 필요 응답 뒤 버튼 제거, hook 재제출 가드 | 08-R1 A5·03-R01 X1이 막힌다 |
|
||||
| 3 | 나머지 P2·P3 | 영역 문서 | 영역 문서 완료 기준 |
|
||||
|
||||
## 10. 재검토 조건 (36.5-7)
|
||||
|
||||
- Gitea Actions를 켤 때. 12-01의 러너 전제와 13-01의 로그를 실제로 본다.
|
||||
- 짝 백엔드가 Fileserver 응답·멱등 답 표·생성기를 바꿀 때(01-01, 01-02, 07-01, 16-02).
|
||||
- 다운스트림에 이 묶음을 동기화할 때(14-01, 1103/14-02, 09-01).
|
||||
- 제품이 OPFS에 개인 파일을 둘 때(1103/05-01).
|
||||
|
||||
## 11. 리뷰 범위 (36.1)
|
||||
|
||||
| 항목 | 기록 |
|
||||
|---|---|
|
||||
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`. 짝 백엔드 `clean-architecture-backend-template`은 노트북 `45d2a478`(pin과 같음)을 읽기만 했다 |
|
||||
| 커밋·작업 상태·확인 시점 | `8a44226`(= main `409d72e` 트리), 브랜치 `fix/maturity-review-2026-11-03`. 2026-11-05 19:20~21:00. 노트북 worktree는 이 커밋에서 깨끗했다(추적 안 된 `AGENTS.md` 하나는 리뷰와 무관). desktop checkout도 같은 커밋에서 시작해 끝에 `git status`가 비었다 |
|
||||
| 목적과 지원 실행 구성 | 0절 |
|
||||
| 필수 요구와 규모·운영 목표 | 0절 |
|
||||
| 읽은 코드·구성 범위 | `src/`, `tests/`, `scripts/`, `config/`, `.gitea/`, `docs/`, `recipes/`, 루트 설정(영역 표 11.2). 짝 백엔드의 Fileserver·HTTP 계약·멱등·생성기·인증 문서와 코드 일부 |
|
||||
| 수행한 테스트·실험 | 11.1절 게이트. 영역 에이전트의 개별 실행 15건(10.4절 전환 전), 배치 78항목. 3엔진 Playwright, 변이, 생성 명령으로 기능 추가, 실제 nginx(docker) probe, lab 측정 |
|
||||
| 확인하지 못한 범위·이유 | 8절 |
|
||||
| 이전 리뷰와 비교 가능한 범위 | 2026-11-03 리뷰의 96건 전부(13절)와 각 영역의 0929·1101 이월 항목. 이전 실행 결과는 증거로 쓰지 않았다. 메인 세션의 8a44226 실행도 다시 돌렸다(11.1절) |
|
||||
|
||||
실행 환경: 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 게이트 실행 결과 (오케스트레이터, `8a44226`, desktop)
|
||||
|
||||
merge stage 14개, workflow env(`CI=true`, `VITE_COMMIT_SHA`, `VITE_BUILD_ID=gitea-48-1`, `RELEASE_ID`, `CI_RUNNER_IMAGE` digest 형식). 시간은 잠금 대기를 포함한다.
|
||||
|
||||
| 게이트 | 결과 | 시간 |
|
||||
|---|---|---|
|
||||
| FE-GATE-020 | 통과(제거·생성 드릴 모두 PASS) | 1,156초 |
|
||||
| FE-GATE-001 | 통과 | 579초(대부분 잠금 대기) |
|
||||
| FE-GATE-002 | 통과 | 35초 |
|
||||
| FE-GATE-003 | 통과 | 53초 |
|
||||
| FE-GATE-004 | 통과 | 13초 |
|
||||
| FE-GATE-005 | 통과(unit 2,883, coverage 3,869) | 133초 |
|
||||
| FE-GATE-006 | 통과 | 14초 |
|
||||
| FE-GATE-007 | 통과 | 29초 |
|
||||
| FE-GATE-008 | 통과(e2e 202·3 skip, capability 66, storybook 1, visual 6) | 181초 |
|
||||
| FE-GATE-009 | 통과 | 54초 |
|
||||
| FE-GATE-010 | 통과 | 66초 |
|
||||
| FE-GATE-011 | 통과 | 9초 |
|
||||
| FE-GATE-012 | 통과(초기 JS 202,973 / 204,800 B, 26 / 32 파일) | 13초 |
|
||||
| FE-GATE-013 | **실패** — `test:system` 18 failed / 96 passed(114). 18건 모두 호스트 원인(12-01). 뒤 명령 7개(`verify:reproducible-build`, `build:release-candidate`, `verify:local-evidence`, 공급망 fixture 둘, 보안 fixture, `check:browser-security`)는 따로 돌려 모두 rc=0 | 84초 |
|
||||
|
||||
CLAUDE.md 목록, local env(CI 값 없음):
|
||||
|
||||
| 명령 | 결과 |
|
||||
|---|---|
|
||||
| `check:architecture`, `check:types`, `lint` | 통과 |
|
||||
| `test:unit` / `test:component` / `test:integration` / `test:contract` / `test:runtime-schema` | 통과 — 2,883 / 270 / 189 / 24 / 56 |
|
||||
| `verify:documentation` | **실패(환경 조건)** — desktop의 옆 백엔드 checkout이 `ef947e5`이고 커밋 안 한 변경이 있어 pin `45d2a478`과 다르다. 그 트리에 없는 경로 5개 문서. 옆 checkout이 없는 임시 worktree에서 node로 직접 돌리면 `PASS_SCOPED`(짝 repo 참조 17개 미검증). 기계마다 결과가 다른 것 자체는 12-02 |
|
||||
| `check:adapter-inventory`, `check:ci` | 통과 |
|
||||
|
||||
메인 세션이 같은 커밋에서 낸 결과(001~012·020 통과, 013의 test:system 18/114 실패, 나머지 7개 통과)와 같다. 그 결과를 가져다 쓰지 않고 다시 돌렸다.
|
||||
|
||||
### 11.2 영역 분할 (2026-11-03 README 10.2절 재사용)
|
||||
|
||||
| 번호 | 영역 | 문서 | 새 발견 |
|
||||
|---|---|---|---|
|
||||
| 01 | adapters: browser-transfer | [01-adapters-browser-transfer.md](01-adapters-browser-transfer.md) | 4 |
|
||||
| 02 | adapters: browser-files·cache·cross-context | [02-adapters-browser-files-cache.md](02-adapters-browser-files-cache.md) | 4 |
|
||||
| 03 | adapters: http·state | [03-adapters-http-state.md](03-adapters-http-state.md) | 2 |
|
||||
| 04 | adapters: realtime | [04-adapters-realtime.md](04-adapters-realtime.md) | 3 |
|
||||
| 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) | 3 |
|
||||
| 07 | contracts | [07-contracts.md](07-contracts.md) | 2 |
|
||||
| 08 | presentation | [08-presentation.md](08-presentation.md) | 4 |
|
||||
| 09 | app core·bootstrap·features | [09-app-core.md](09-app-core.md) | 3 |
|
||||
| 10 | tests: 빠른 계층 | [10-tests-fast-layers.md](10-tests-fast-layers.md) | 2 (+ 10-03 오케스트레이터) |
|
||||
| 11 | tests: 브라우저·릴리스·규모 | [11-tests-browser-release-scale.md](11-tests-browser-release-scale.md) | 2 (11-02는 12-01로 합침) |
|
||||
| 12 | guardrails·CI | [12-guardrails-ci.md](12-guardrails-ci.md) | 3 (+ 12-04 오케스트레이터) |
|
||||
| 13 | build·release·supply chain | [13-build-release-supply-chain.md](13-build-release-supply-chain.md) | 2 |
|
||||
| 14 | 템플릿·제품 문서 | [14-template-product-docs.md](14-template-product-docs.md) | 3 |
|
||||
| 15 | 성능 실측·최적화 | [15-performance.md](15-performance.md) | 5 |
|
||||
| 16 | 폴더 구조·리팩토링·기능 개발 패턴 | [16-structure-patterns.md](16-structure-patterns.md) | 4 |
|
||||
|
||||
### 11.3 합친 중복
|
||||
|
||||
| 대표 | 같은 결함 | 이유 |
|
||||
|---|---|---|
|
||||
| 12-01 | 11-02 | 같은 사전 점검과 같은 18건 실패. 11은 test 쪽, 12는 러너 요구 쪽을 봤다 |
|
||||
|
||||
관련은 있지만 따로 센 것: 07-01과 16-02(둘 다 pin이 `http-contract.md`만 본다. 07-01은 답 표 JSON, 16-02는 생성기가 옮긴 사실 넷으로 결함 위치가 다르다). 15-03은 지난 §14.7 "남은 문제"에 적혀 있었지만 색인에 없던 것이라 새 발견으로 셌다.
|
||||
|
||||
### 11.4 실행 방식과 안전 사항
|
||||
|
||||
- 처음에는 영역 에이전트가 desktop checkout 하나에서 공유 잠금 아래 각자 실행했다(helper `exp.sh`: 잠금, 시작 전 깨끗함 확인, 끝난 뒤 되돌림). 19:40에 30여 개 실행이 잠금 줄에 섰다. 메인 세션과 사용자의 결정("필요할 때만, 묶어서, 실행마다 환경을 되돌린다")에 따라 19:55에 줄에 선 32건을 취소하고 helper를 닫았다. 취소된 실행은 잠금을 얻지 못해 checkout을 건드리지 않았다. 그 전에 끝난 실행 15건은 모두 `restored: clean`을 찍었다.
|
||||
- 그 뒤 리뷰어는 코드와 게이트 출력(읽기 전용 snapshot `desktop:/tmp/claude-gates/r4/snap/`)만으로 판정하고, 더 필요한 실험을 목록으로 냈다. 오케스트레이터가 게이트가 끝난 뒤 78항목을 두 묶음으로 하나씩 돌렸다. 항목마다 앞뒤로 추적 파일을 기준 커밋으로 되돌리고 추적 안 된 파일을 지웠다(node_modules 유지). 78항목 모두 `restore=clean`, 끝에 `git status` 비어 있음, branch `fix/maturity-review-2026-11-03`, head `8a44226`.
|
||||
- 같은 변이는 한 번만 돌렸다. 08-R4는 03-R07과 같은 변이라 그 결과를 썼다. 15-R2는 바로 앞 15-R1이 만든 `dist/`를 썼다.
|
||||
- 이 방식이 필요했던 이유가 템플릿 결함이다(12-04).
|
||||
|
||||
### 11.5 오케스트레이터 자신의 실수
|
||||
|
||||
| 실수 | 결과 | 원인 |
|
||||
|---|---|---|
|
||||
| 처음에 영역 에이전트 16개가 각자 desktop에서 실행하게 했다 | 잠금 줄 30여 건, 같은 빌드·테스트 중복. 32건 취소 | 실행 비용을 영역마다 따로 셈했다. 공용 출력 경로 때문에 병렬이 불가능하다는 것을 먼저 보지 않았다 |
|
||||
| `verify:documentation`을 옆 checkout 없는 임시 worktree에서 `pnpm`으로 돌렸다 | pnpm이 node_modules 재설치를 시도하다 TTY 없음으로 멈춰 결과가 무효. 배치에서 node로 직접 다시 돌렸다(00-R2) | 연결한 node_modules를 pnpm이 자기 것으로 보지 않았다 |
|
||||
| 취소 통지에서 16 영역의 `16-mut`도 취소됐다고 적었다 | 실제로는 19:41에 돌아 `restored: clean`이었다(16 영역이 정정) | 취소 목록을 프로세스 이름으로만 셌다 |
|
||||
| 배치 진행 감시(Monitor)가 30분 동안 아무것도 알리지 않았다 | 진행은 직접 조회로 확인했다 | awk 입력 버퍼링 |
|
||||
|
||||
## 12. 28개 관점 판정 (36.2)
|
||||
|
||||
판정 기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 영역 순서는 01부터 16까지다. 종합 판정은 평균하지 않는다. 한 영역이라도 X면 X다(35.7절). 이번에는 X를 준 영역이 없다. 21번만 오케스트레이터가 X로 판정했다. 각 영역의 목표·확인 통제와 증거는 영역 문서 4절에 있다.
|
||||
|
||||
| 번호 | 관점 | 영역 01~16 | 종합 | 종합 판정의 근거·잔여 위험 |
|
||||
|---|---|---|---|---|
|
||||
| 1 | 코드 성숙도 | `OPPOPPOPP>>->>O>` | P | 판정 규칙이 한 모듈과 선언 목록으로 모였다(03). 1103/05-01 purge 집계 시점, 08-04 저장 버튼 |
|
||||
| 2 | 구조적 성숙도 | `OP>OOOOOP>>P>>OP` | P | `check:architecture` 통과. 0929/12-03(층 밖 폴더로 adapter에 닿음)은 12-R3에서 여전히 통과한다 |
|
||||
| 3 | 변경 용이성 | `OOPPPPOPPPPPPPPP` | P | 09-01 제품 확장 지점 탐침, 16-01 기능마다 추적 파일 둘 변경, 13-02 제품 gate를 release에 묶을 자리 없음 |
|
||||
| 4 | 인지 부하 | `PPPPPPOPPPPPPPPP` | P | 짝 백엔드 사실이 여러 손 사본에 흩어졌다(6절 원인 2) |
|
||||
| 5 | 위험 가시성 | `PPPPPPOPPPPPPPPP` | P | 13-01 release 실패 이유가 사라진다. 12-01 전제가 적혀 있지 않다. 15-04 기능 라우트 첫 진입을 아무도 재지 않는다 |
|
||||
| 6 | 실패 성숙도 | `PPPPPPOPPPO-O>>>` | P | 1103/03-01 고쳐짐. 01-01 202 `REJECTED` 오판, 04-02 던짐을 서버 장애로 봄 |
|
||||
| 7 | 운영 성숙도 | `PPPPPP>>P-P>P>P-` | P | 13-01, 02-01 진단 없음 |
|
||||
| 8 | 디버깅 가능성 | `PPOPPPPPPOPPPOOP` | P | 12-01 원인 없는 18건, 02-01, 01-03 `traceId` 버림, 09-03 원인 중복 |
|
||||
| 9 | 유지보수 성숙도 | `PPPPPPOPPPPPPPPP` | P | 14-01·1103/14-01 낡은 문장, 04-03 VD-28, 15-03 중복 목록 |
|
||||
| 10 | 테스트 성숙도 | `PPOPPPPPPPPPPPPP` | P | 변이 검출이 크게 늘었다(5절). 남은 틈: 11-01 fixture 결과 버림, 04-01, 10-02, 02-04, 1103/05-01 테스트가 객체 0~1개만 씀 |
|
||||
| 11 | 데이터 성숙도 | `OP-OPO>-P>-->-->` | P | 1103/05-01 계정 삭제 purge 누락(OPFS 개인 파일 제품에는 사용 보류) |
|
||||
| 12 | 동시성 성숙도 | `POPOPO-PPOP->->>` | P | 1103/05-01 다른 탭 put, 0929/03-03 같은 입력 재제출, 12-04 한 checkout 두 실행 |
|
||||
| 13 | 확장성 | `PO>P?PO>P>P>>>PP` | P | 쓰기 기능 둘이 예산 안(277 B 남음). 15-02 대조 허용치가 여유보다 크다 |
|
||||
| 14 | 성능 성숙도 | `PP>P?P>O>P>?P>P>` | P | lab 146 ms 통과. 15-04 기능 라우트 첫 진입 406 ms 미측정, 15-01·15-05 작은 shift |
|
||||
| 15 | 보안 성숙도 | `OPOOPOOPPO>OP>>>` | P | 1103/13-03 advisory 결정 대기, 05-01 저장 키, 09-02 401 미전달 |
|
||||
| 16 | 의존성 성숙도 | `O->O-P>>->PPPPO>` | P | 1103/13-03, 13-01로 advisory 신호가 안 보임 |
|
||||
| 17 | API / Contract 성숙도 | `PPPPPPPPPP>POP>P` | P | 01-01·01-02 Fileserver 판정, 07-01 답 표 미대조, 16-02, 03-01·03-02 |
|
||||
| 18 | 배포 성숙도 | `OP>PPP>O>>P>P>O>` | P | 실제 nginx probe 통과(13-R02). 13-02 제품 gate가 배포를 막지 못함 |
|
||||
| 19 | 설정 성숙도 | `PPPPPPPPOPPPPPOO` | P | 14-02 매뉴얼 설정 예시 실패, 1103/07-04 |
|
||||
| 20 | 개발자 경험 | `P>PP>PPPPPPPPPPP` | P | 기능 추가가 브라우저 게이트까지 통과(16-R1). 12-04 병렬 실행 불가, 16-04 예시 이름 충돌, 14-02 |
|
||||
| 21 | Guardrail 성숙도 | `PPPPPPPOPPPPPPPP` | **X** | **오케스트레이터 판정.** 영역은 모두 P다. 그러나 merge 게이트 둘이 지원 구성에서 코드와 무관하게 틀린 답을 낸다. FE-GATE-005는 제품 capability를 쓰는 다운스트림에서 항상 실패한다(09-01, 두 다운스트림 해당). FE-GATE-013은 사전 점검 PASS 뒤 호스트 원인으로 실패한다(12-01, 직접 재현). 지난 라운드에 같은 모양(02-06)으로 X를 줬다. 13-02(제품 gate가 release를 막지 못함), 11-01(fixture 결과 버림이 안 잡힘)도 이 관점이다 |
|
||||
| 22 | 추상화 성숙도 | `OPPPPOOPPPPO>>>P` | P | 04-02 poll `execute` 계약, 1103/04-01 남은 틈(descriptor 미전달) |
|
||||
| 23 | 일관성 | `PPOPPPPPPPPPPPPP` | P | 01-02 Fileserver 효과 표가 V3 표와 다르다 |
|
||||
| 24 | 네이밍 / 의미 성숙도 | `PPPPPPPPPOPPPPPP` | P | 08-02 "변경됨으로 확인" 뒤 무안내, 04-02 `PROVIDER_UNAVAILABLE` 뜻 |
|
||||
| 25 | 조직 확장성 | `-->-?-OPP->P-P>P` | P | 16-01 기능 브랜치끼리 같은 줄 충돌, 12-04 |
|
||||
| 26 | Ownership 성숙도 | `P>P-?PP?>PPPPP>>` | P | 1103/01-01 백엔드 매뉴얼 몫, 13-02 |
|
||||
| 27 | 삭제 가능성 | `POOOPOO>PPPP>P>P` | P | 14-01 예제 기능 제거 뒤 문서 검사 실패, 16-04 제거 드릴의 이름 충돌, 10-01 샘플과 함께 사라지는 플랫폼 테스트 |
|
||||
| 28 | 회복 가능성 | `PPPPPP-PP-P-P>>>` | P | 02-02 rollback 대상 회복 길 없음, 1103/03-01 회복 필요 응답 뒤 재전송 버튼 |
|
||||
|
||||
## 13. 지난 발견 상태 (96건, `8a44226`)
|
||||
|
||||
1103 색인 95건 + 차단 항목에만 있던 0929/03-03. "1103 §14.4"는 지난 README 14.4절의 판정이다("그 밖의 81건"은 고침으로 셌다). **(판정 정정)**은 §14.4가 고침이라 했지만 지금 일부인 것이다. 근거는 링크한 영역 문서 2절에 있다. 각 영역 문서 2절에는 1101·0929 이월 항목도 있다.
|
||||
|
||||
| ID | 지난 심각도·우선순위 | 1103 §14.4 | 지금 상태 | 남은 것·근거 |
|
||||
|---|---|---|---|---|
|
||||
| [1103/01-01](01-adapters-browser-transfer.md) | High·P1 | 고침 | 일부 **(판정 정정)** | Fileserver client와 문서는 들어왔다. 백엔드 매뉴얼에 안내가 없고, 실제 짝 백엔드로 올려 보지 않았다. MSW가 백엔드 문서에서 와서 202 `REJECTED`를 놓쳤다(새 01-01). 남은 결함은 새 01-01·01-02로 센다 |
|
||||
| [1103/03-01](03-adapters-http-state.md) | High·P1 | 고침 | 일부 **(판정 정정)** | 완료 기준 넷은 충족했다(영역 03 변이 19개 검출). 폼 쪽(08 영역): 선언한 거절의 이유가 화면에 안 보이고 기능이 문구를 더할 자리가 없다. KEYED 쓰기에서 500 `IDEMPOTENCY_RECOVERY_REQUIRED` 뒤 재전송 버튼이 남아 같은 키를 끝없이 보낸다. 남은 부분 Medium·P2 |
|
||||
| [1103/02-06](02-adapters-browser-files-cache.md) | Medium·P1 | 고침 | 고쳐짐 | FE-GATE-020 rc=0(merge-48). 06-05 포함 |
|
||||
| [1103/09-02](09-app-core.md) | Medium·P1 | 고침 | 고쳐짐 | 수정(탐침)이 새 09-01을 만들었다 |
|
||||
| [1103/09-03](09-app-core.md) | Medium·P1 | 일부 | 일부 | 실제 Keycloak·Redis 연동 미확인. 백엔드 realm에 public client가 없다. 쿠키 recipe로 이으면 401이 owner에 안 닿는다(새 09-02) |
|
||||
| [1103/11-02](11-tests-browser-release-scale.md) | Medium·P1 | 고침 | 일부 **(판정 정정)** | 코드는 들어왔다. 빈 러너에서 FE-GATE-008 완료 기준을 돌리지 않았다 |
|
||||
| [1103/11-06](11-tests-browser-release-scale.md) | Medium·P1 | 고침 | 고쳐짐 | |
|
||||
| [1103/11-07](11-tests-browser-release-scale.md) | Medium·P1 | 고침 | 고쳐짐 | |
|
||||
| [1103/11-08](11-tests-browser-release-scale.md) | Medium·P1 | 고침 | 고쳐짐 | 검사 약화 없음(13-R01·R03~R06, 3절) |
|
||||
| [1103/11-09](11-tests-browser-release-scale.md) | Medium·P1 | 고침 | 고쳐짐 | 변이 R1·R2·R4·R5 검출. 검사 약화 없음(3절) |
|
||||
| [1103/11-10](11-tests-browser-release-scale.md) | Medium·P1 | 고침 | 고쳐짐 | 400 px 재현: 수정 있음 통과(R6), 되돌림 실패(R7) |
|
||||
| [1103/16-09](16-structure-patterns.md) | Medium·P1 | 고침 | 고쳐짐 | 수정 방식이 새 16-01을 만들었다 |
|
||||
| [1103/12-01](12-guardrails-ci.md) | Medium·P1 | 고침 | 고쳐짐 | 기능 2개로 `test:visual` 6/6(12-R1). 셸 CSS 변경이 여전히 실패하는지는 미검증(12-R2 변이가 화면을 안 바꿈) |
|
||||
| [1103/12-09](12-guardrails-ci.md) | Medium·P1 | 고침 | 고쳐짐 | FE-GATE-005 rc=0(merge-48) |
|
||||
| [1103/13-01](13-build-release-supply-chain.md) | Medium·P1 | 고침 | 고쳐짐 | |
|
||||
| [1103/13-03](13-build-release-supply-chain.md) | Medium·P1 | 일부 | 일부 | 결정 대기: 운영 high 2건(zod GHSA-mrhx, react-router GHSA-qwww). 그 신호가 실제 run에서 안 보인다(새 13-01) |
|
||||
| [1103/14-01](14-template-product-docs.md) | Medium·P1 | 고침 | 일부 **(판정 정정)** | 초기 파일 상한이 `CHANGELOG.md:107`·`:216`은 26, 예산 파일은 32. 알려진 제한이 `f887817` 기준. FE-GATE-017을 merge 게이트로 적는다 |
|
||||
| [1103/14-02](14-template-product-docs.md) | Medium·P1 | 고침 | 일부 **(판정 정정)** | "옮기기 전" 목록이 memento 템플릿 src 변경 26개 중 7개, tech-log 38개 중 11개만 다룬다. 제품 소유 자리가 없는 변경(memento `if-match`)이 있다 |
|
||||
| [1103/15-01](15-performance.md) | Medium·P1 | 고침 | 고쳐짐 | lab 146 ms(지난 227 ms) |
|
||||
| [1103/01-02](01-adapters-browser-transfer.md) | Medium·P2 | 고침 | 고쳐짐 | |
|
||||
| [1103/02-01](02-adapters-browser-files-cache.md) | Medium·P2 | 고침 | 고쳐짐 | |
|
||||
| [1103/03-02](03-adapters-http-state.md) | Medium·P2 | 일부 | 일부 | bulk `results`는 지원하지 않는다(문서화) |
|
||||
| [1103/03-03](03-adapters-http-state.md) | Medium·P2 | 고침 | 고쳐짐 | |
|
||||
| [1103/04-01](04-adapters-realtime.md) | Medium·P2 | 고침 | 고쳐짐 | |
|
||||
| [1103/04-02](04-adapters-realtime.md) | Medium·P2 | 고침 | 고쳐짐 | |
|
||||
| [1103/05-01](05-adapters-storage-kernel.md) | Medium·P2 | 고침 | 일부 **(판정 정정)** | 다른 탭의 새 파일 put이 purge의 목록과 journal 집계(`opfs-byte-store-adapter.ts:821`→`:899`) 사이에 끝나면 놓치고 `COMPLETED`를 낸다. 객체 3·8개에서 메모리 20/20, Chromium 6/6. 테스트는 객체 0~1개만 쓴다. Medium·P2(OPFS에 개인 파일을 두는 제품은 P1) |
|
||||
| [1103/07-01](07-contracts.md) | Medium·P2 | 고침 | 고쳐짐 | |
|
||||
| [1103/09-01](09-app-core.md) | Medium·P2 | 고침 | 고쳐짐 | 수정이 새 09-02를 만들었다 |
|
||||
| [1103/09-04](09-app-core.md) | Medium·P2 | 일부 | 일부 | 결정 대기(`EXAMPLES_PLATFORM`). 예제 기능을 빼면 브라우저 spec 8개 수정 |
|
||||
| [1103/09-05](09-app-core.md) | Medium·P2 | 일부 | 일부 | SW `blockers`·`observe` 연결이 템플릿 파일에 남았다 |
|
||||
| [1103/09-06](09-app-core.md) | Medium·P2 | 고침 | 고쳐짐 | |
|
||||
| [1103/10-01](10-tests-fast-layers.md) | Medium·P2 | 고침 | 고쳐짐 | |
|
||||
| [1103/10-02](10-tests-fast-layers.md) | Medium·P2 | 고침 | 고쳐짐 | |
|
||||
| [1103/11-01](11-tests-browser-release-scale.md) | Medium·P2 | 고침 | 일부 **(판정 정정)** | 목록 라우트는 완료 기준 충족(11-R8b·R8c). 상세 라우트는 실패 화면으로 검사되는데 `a11y.json`은 passed |
|
||||
| [1103/12-02](12-guardrails-ci.md) | Medium·P2 | 고침 | 고쳐짐 | |
|
||||
| [1103/12-06](12-guardrails-ci.md) | Medium·P2 | 고침 | 고쳐짐 | |
|
||||
| [1103/12-07](12-guardrails-ci.md) | Medium·P2 | 고침 | 고쳐짐 | |
|
||||
| [1103/13-02](13-build-release-supply-chain.md) | Medium·P2 | 고침 | 고쳐짐 | |
|
||||
| [1103/14-03](14-template-product-docs.md) | Medium·P2 | 고침 | 고쳐짐 | |
|
||||
| [1103/14-04](14-template-product-docs.md) | Medium·P2 | 고침 | 고쳐짐 | 지난 판정 정정: FE-GATE-017은 merge가 아니라 문서 단계다. 결함 자체는 맞았다 |
|
||||
| [1103/16-01](16-structure-patterns.md) | Medium·P2 | 고침 | 일부 **(판정 정정)** | 읽기만 있는 기여나 `refusedBeforeWrite` 없는 쓰기에서 Envelope 줄을 모두 빼면 조립이 통과한다(코드 추론). 지난 완료 기준("줄을 지우면 `check:types` 실패")은 충족하지 않았다 |
|
||||
| [1103/16-02](16-structure-patterns.md) | Medium·P2 | 고침 | 고쳐짐 | |
|
||||
| [1103/16-03](16-structure-patterns.md) | Medium·P2 | 고침 | 고쳐짐 | |
|
||||
| [1103/03-04](03-adapters-http-state.md) | Low·P2 | 고침 | 고쳐짐 | |
|
||||
| [1103/05-04](05-adapters-storage-kernel.md) | Low·P2 | 고침 | 고쳐짐 | |
|
||||
| [1103/08-02](08-presentation.md) | Low·P2 | 고침 | 고쳐짐 | |
|
||||
| [1103/09-07](09-app-core.md) | Low·P2 | 고침 | 고쳐짐 | 수정이 새 09-03을 만들었다 |
|
||||
| [1103/10-04](10-tests-fast-layers.md) | Low·P2 | 고침 | 고쳐짐 | |
|
||||
| [1103/11-03](11-tests-browser-release-scale.md) | Low·P2 | 고침 | 일부 **(판정 정정)** | 코드는 들어왔다. desktop에서는 호스트 원인(12-01)으로 `test:system` 완료 기준을 돌릴 수 없다 |
|
||||
| [1103/11-05](11-tests-browser-release-scale.md) | Low·P2 | 고침 | 고쳐짐 | |
|
||||
| [1103/12-04](12-guardrails-ci.md) | Low·P2 | 고침 | 고쳐짐 | |
|
||||
| [1103/14-05](14-template-product-docs.md) | Low·P2 | 고침 | 고쳐짐 | |
|
||||
| [1103/15-02](15-performance.md) | Low·P2 | 고침 | 일부 **(판정 정정)** | `CHANGELOG.md:107`·`:216`이 파일 상한을 26으로 적는다(14-01과 같은 줄) |
|
||||
| [1103/15-03](15-performance.md) | Low·P2 | 고침 | 고쳐짐 | |
|
||||
| [1103/16-04](16-structure-patterns.md) | Low·P2 | 고침 | 고쳐짐 | |
|
||||
| [1103/16-05](16-structure-patterns.md) | Low·P2 | 고침 | 일부 **(판정 정정)** | `BoundMutation.operationId`가 아직 `string`이다(`server-state.ts:305`) |
|
||||
| [1103/16-07](16-structure-patterns.md) | Low·P2 | 고침 | 고쳐짐 | |
|
||||
| [1103/01-03](01-adapters-browser-transfer.md) | Low·P3 | 고침 | 고쳐짐 | |
|
||||
| [1103/02-02](02-adapters-browser-files-cache.md) | Low·P3 | 고침 | 고쳐짐 | |
|
||||
| [1103/02-03](02-adapters-browser-files-cache.md) | Low·P3 | 고침 | 고쳐짐 | |
|
||||
| [1103/02-04](02-adapters-browser-files-cache.md) | Low·P3 | 고침 | 고쳐짐 | |
|
||||
| [1103/02-05](02-adapters-browser-files-cache.md) | Low·P3 | 고침 | 고쳐짐 | |
|
||||
| [1103/03-05](03-adapters-http-state.md) | Low·P3 | 고침 | 고쳐짐 | |
|
||||
| [1103/03-06](03-adapters-http-state.md) | Low·P3 | 고침 | 고쳐짐 | |
|
||||
| [1103/03-07](03-adapters-http-state.md) | Low·P3 | 일부 | 일부 | 결정 대기(백엔드 목록 GET) |
|
||||
| [1103/04-04](04-adapters-realtime.md) | Low·P3 | 고침 | 고쳐짐 | 수정이 새 04-01·04-02를 만들었다 |
|
||||
| [1103/04-06](04-adapters-realtime.md) | Low·P3 | 고침 | 고쳐짐 | |
|
||||
| [1103/05-02](05-adapters-storage-kernel.md) | Low·P3 | 고침 | 고쳐짐 | |
|
||||
| [1103/05-03](05-adapters-storage-kernel.md) | Low·P3 | 고침 | 고쳐짐 | |
|
||||
| [1103/06-01](06-adapters-service-worker-push.md) | Low·P3 | 고침 | 고쳐짐 | |
|
||||
| [1103/06-02](06-adapters-service-worker-push.md) | Low·P3 | 고침 | 고쳐짐 | |
|
||||
| [1103/06-03](06-adapters-service-worker-push.md) | Low·P3 | 고침 | 고쳐짐 | |
|
||||
| [1103/06-04](06-adapters-service-worker-push.md) | Low·P3 | 고침 | 고쳐짐 | |
|
||||
| [1103/07-02](07-contracts.md) | Low·P3 | 고침 | 고쳐짐 | |
|
||||
| [1103/07-03](07-contracts.md) | Low·P3 | 고침 | 고쳐짐 | |
|
||||
| [1103/07-04](07-contracts.md) | Low·P3 | 일부 | 일부 | 부팅 오류 `CONFIG_SECRET_NAME_REJECTED`에 키 이름이 없다 |
|
||||
| [1103/08-03](08-presentation.md) | Low·P3 | 고침 | 고쳐짐 | |
|
||||
| [1103/08-04](08-presentation.md) | Low·P3 | 고침 | 고쳐짐 | |
|
||||
| [1103/08-05](08-presentation.md) | Low·P3 | 고침 | 고쳐짐 | |
|
||||
| [1103/09-08](09-app-core.md) | Low·P3 | 고침 | 고쳐짐 | |
|
||||
| [1103/09-09](09-app-core.md) | Low·P3 | 고침 | 고쳐짐 | |
|
||||
| [1103/09-10](09-app-core.md) | Low·P3 | 고침 | 고쳐짐 | |
|
||||
| [1103/09-11](09-app-core.md) | Low·P3 | 고침 | 고쳐짐 | |
|
||||
| [1103/11-04](11-tests-browser-release-scale.md) | Low·P3 | 고침 | 일부 **(판정 정정)** | 11-03과 같다 |
|
||||
| [1103/12-05](12-guardrails-ci.md) | Low·P3 | 일부 | 일부 | 지운 심볼 이름과 docs/README.md 1절 밖 문서는 검사하지 않는다 |
|
||||
| [1103/12-08](12-guardrails-ci.md) | Low·P3 | 고침 | 고쳐짐 | |
|
||||
| [1103/13-04](13-build-release-supply-chain.md) | Low·P3 | 고침 | 고쳐짐 | |
|
||||
| [1103/13-05](13-build-release-supply-chain.md) | Low·P3 | 고침 | 고쳐짐 | |
|
||||
| [1103/14-06](14-template-product-docs.md) | Low·P3 | 고침 | 고쳐짐 | |
|
||||
| [1103/15-04](15-performance.md) | Low·P3 | 고침 | 고쳐짐 | |
|
||||
| [1103/15-05](15-performance.md) | Low·P3 | 고침 | 고쳐짐 | |
|
||||
| [1103/15-06](15-performance.md) | Low·P3 | 고침 | 고쳐짐 | |
|
||||
| [1103/15-07](15-performance.md) | Low·P3 | 고침 | 고쳐짐 | |
|
||||
| [1103/16-06](16-structure-patterns.md) | Low·P3 | 일부 | 일부 | 라우트 계약 `title`·`navigationLabel`을 화면이 읽지 않는다 |
|
||||
| [1103/16-08](16-structure-patterns.md) | Low·P3 | 고침 | 고쳐짐 | |
|
||||
| [0929/03-03](03-adapters-http-state.md) | High·P1 | 고침 | 일부 **(판정 정정)** | 재전송 버튼과 hook은 키 없는 intent를 거절한다. 남은 것: 같은 입력을 다시 제출하면 hook이 키 없는 결과 불명 intent를 키 없이 다시 보낸다(`application-query.ts:557-561`, `:590-596`, 실험 X1 `keys=[null,null]`). 템플릿 폼(`use-app-form.ts:325`)과 페이지만 막는다. 손으로 만든 `AsyncState`는 버튼을 그린다(X3). 남은 부분 Medium·P2 |
|
||||
|
||||
합계: 고쳐짐 74 · 일부 22 · 남음 0. 판정 정정 13건.
|
||||
|
||||
## 14. 오케스트레이터 발견
|
||||
|
||||
메인 세션이 기록하라고 정한 두 가지다(2026-11-05 지시). 영역 문서가 없으므로 36.3 양식을 여기에 적는다.
|
||||
|
||||
### 12-04 빌드·게이트가 고정 출력 경로와 고정 포트를 써서, 한 checkout에서 두 실행이 부딪힌다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 20, 25, 12, 10, 21 |
|
||||
| 근거 | **포트:** e2e preview 4173(`playwright.config.ts:13`, `:19-21`), visual preview 4174(`playwright.visual.config.ts:34`, `:59-61`), capability dev server도 4174(`playwright.capabilities.config.ts:26`, `:37-39`), storybook 6006(`playwright.storybook.config.ts`), dev 5173. 넷 모두 `reuseExistingServer: false`라 두 번째 실행은 시작하지 못한다. dev 설정만 `reuseExistingServer: true`라 5173에 다른 서버가 떠 있으면 조용히 그 서버를 검사한다(`playwright.dev.config.ts:19-20`). **출력:** 빌드는 `dist/`를 비우고 다시 쓴다(`scripts/build-frontend.ts:18`, emptyOutDir). Playwright 결과는 `artifacts/tests/*/results`(`playwright.config.ts:6` 등), gate 로그는 `artifacts/quality/gates/FE-GATE-<NNN>.txt`(`scripts/create-feature.ts:1752`)에 고정이다. `scripts/` 54개 파일이 `artifacts/` 고정 경로를 쓴다. 일부 테스트는 이미 임시 출력 경로를 쓴다(`tests/unit/build-environment-bundle.test.ts:33`). **실행(00-R1):** 다른 preview가 4173을 잡은 상태에서 e2e를 시작하자 `http://127.0.0.1:4173 is already used`로 rc=1. **리뷰 중 실제로 일어남:** 이 리뷰는 한 checkout에서 실행을 하나씩만 돌려야 해서 공유 잠금을 썼고, 19:40에 30여 건이 줄을 섰다(11.4절) |
|
||||
| 발생 조건 | 한 checkout에서 두 실행이 겹칠 때. IDE 테스트와 터미널 게이트, 두 에이전트, 같은 기계의 두 worktree(포트만 충돌) |
|
||||
| 영향 | 두 번째 실행이 포트 충돌로 실패한다. 겹친 빌드가 앞 실행의 `dist/`를 지워 앞 실행이 다른 빌드를 검사하거나, 증거 파일이 섞인다. CI 러너는 job마다 따로라 영향이 없다. 다운스트림의 로컬 개발과 에이전트 병렬 작업이 직렬이 된다 |
|
||||
| 심각도·우선순위 | Medium · P2 — 사용자 피해는 없다. 변경·검증 비용을 반복해서 올린다(35.2 Medium). 출시를 막지는 않는다 |
|
||||
| 통제·증거 | 목표 M2 / 확인 M0(실행 격리 장치 없음) · E3(00-R1) + E1 |
|
||||
| 확실성과 남은 가정 | 포트 충돌은 실행으로 확인했다. 겹친 빌드가 앞 실행의 결과를 바꾸는 경우는 코드로만 확인했다 |
|
||||
| 결정의 근거 | 고정 경로는 문서·게이트·증거 검사가 같은 파일을 찾게 한다. 그 대가로 실행 하나만 허용한다. 이 선택은 어디에도 적혀 있지 않다 |
|
||||
| 최소 개선 방향 | 실행마다 출력·artifact 디렉터리를 따로 쓴다(임시 폴더 또는 run ID). 서버는 빈 포트를 고르고 Playwright `baseURL`에 env로 넘긴다. dev 설정의 `reuseExistingServer`를 끈다 |
|
||||
| 대안 비교 | (a) 현상 유지 + "한 checkout에 한 실행"을 매뉴얼·README에 적는다: 비용 0, 병렬 불가는 그대로. (b) 포트만 빈 포트로: 충돌은 사라지지만 `dist/`·`artifacts/` 덮어쓰기가 남는다. (c) 출력·포트 모두 격리: 증거 경로를 읽는 검사(`ci:gate`, `check:test-evidence` 등)를 함께 바꿔야 한다 |
|
||||
| 비용·부작용 | (c)는 증거 경로를 쓰는 스크립트 54개 파일과 workflow upload 경로를 손봐야 한다 |
|
||||
| 재검토 조건 | 다운스트림이 병렬 에이전트나 IDE 테스트를 쓰기 시작할 때 |
|
||||
| 완료 기준 | 한 checkout에서 FE-GATE-008과 FE-GATE-005(또는 FE-GATE-008 둘)를 동시에 돌려 둘 다 통과하고, 각자의 증거 파일이 섞이지 않는다 |
|
||||
| 검증 방법 | 동시 실행 드릴 1회 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규 |
|
||||
|
||||
### 10-03 판정 규칙의 변이 실험을 리뷰어가 손으로 만들고 checkout 전체를 잠가 돌린다
|
||||
|
||||
| 필드 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 개선 제안 |
|
||||
| 관련 관점 | 10, 21, 20 |
|
||||
| 근거 | 이번 라운드 변이는 모두 리뷰어가 sed·패치·스크립트로 만들었다. 02 영역 31개, 03 영역 19개, 07 영역 26종, 10 영역 20종, 13 영역 10개 등. 실행마다 checkout 전체를 잠그고 되돌렸다(11.4절, 12-04 때문). 같은 규칙의 변이를 라운드마다 다시 쓴다. 0929/10-04의 §10.8 검사 변이 L01은 네 라운드째 살아남는다(10 영역). 변이 결과는 리뷰 문서에만 남고 회귀를 지키지 않는다 |
|
||||
| 발생 조건 | 리뷰나 수정 때 판정 규칙의 테스트 강도를 확인할 때마다 |
|
||||
| 영향 | 리뷰 시간의 큰 몫이 변이 준비와 잠금 대기다. 결과를 라운드 사이에 비교할 수 없다 |
|
||||
| 심각도·우선순위 | Low · P3 — 계약 위반은 아니다. 효과와 비용을 비교해 고를 개선이다 |
|
||||
| 통제·증거 | 목표 M3 / 확인 M1(손 실험) · E3 |
|
||||
| 최소 개선 방향 | 실행마다 sandbox 사본을 만드는 변이 도구(예: Stryker, vitest runner)를 판정 규칙 모듈에 한정해 들인다. 예: `backend-envelope.ts`, `http-execution-v3.ts` 판정부, `application-query.ts` 재전송, `public-response-cache-adapter.ts` 판정. 처음에는 merge 게이트가 아닌 수동·nightly로 돈다 |
|
||||
| 대안 비교 | (a) 현상 유지: 리뷰마다 손 변이. (b) 변이 목록을 스크립트로 커밋해 다시 쓴다: 도구 없이 재현은 되지만 격리는 없다. (c) 변이 도구: 격리·재현·점수가 생기고, dev 의존성과 실행 시간이 든다 |
|
||||
| 비용·부작용 | dev 의존성 추가(공급망 증거, `dependency-change-evidence.json`), 실행 시간, 생존 변이 관리. 구조 변경이라 이번 라운드에는 고치지 않는다 |
|
||||
| 재검토 조건 | 다음 리뷰가 같은 변이를 다시 쓸 때 |
|
||||
| 완료 기준 | 판정 규칙 모듈 하나에서 도구가 돌고, 생존 변이 목록이 리뷰 문서 대신 도구 출력으로 나온다 |
|
||||
| 담당·기한·상태 | 미정 · 미정 · 신규(이번 라운드 조치 안 함) |
|
||||
|
||||
## 15. 새 발견 색인 (48건)
|
||||
|
||||
심각도·우선순위 순. 영역 문서에 36.3 양식이 있다(12-04·10-03은 14절).
|
||||
|
||||
| ID | 심각도·우선순위 | 성격 | 내용 | 관련 관점 | 위치 | 합친 것 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| [09-01](09-app-core.md) | Medium·P1 | 확인된 결함 | 제품 확장 타입 검사 탐침이 제품 소유 파일 둘을 덮어써, 기능이 제품 capability를 쓰는 다운스트림에서 FE-GATE-005가 실패한다 | 10, 21, 25, 3, 20, 13(제품 수 축) (30.3, 30.4) | `tests/unit/product-extension-typecheck.test.ts:41-83`, `:181-193`; `src/bootstrap/runtime-adapters.ts:689-697` | |
|
||||
| [12-01](12-guardrails-ci.md) | Medium·P1 | 확인된 결함 | FE-GATE-013의 user namespace 전제가 요구 목록·사전 점검에 없어, 이 desktop에서 사전 점검 PASS 뒤 provider 테스트 18건이 bwrap 원문 오류로 실패한다 | 21, 19, 20, 8, 5 | `scripts/check-system-test-prerequisites.ts:15-38`, `scripts/run-and-validate-provider.ts:254-256`, `docs/operations/ci-quality-gates.md:181-185` | 11-02(같은 결함, 영역 11) |
|
||||
| [13-01](13-build-release-supply-chain.md) | Medium·P1 | 확인된 결함 | `immutable_build`가 FE-GATE-015·027의 gate 로그와 advisory 기록을 올리지 않는다. 그래서 release 실패 이유와 13-03 신호가 실제 workflow에서 사라진다 | 8, 5, 7, 16, 18 | `.gitea/workflows/quality-gates.yml:122-207`, `scripts/run-ci-gate.ts:148-150`, `:209-213`, `:243-249`, `scripts/contracts/ci-gates.ts:947` | |
|
||||
| [01-01](01-adapters-browser-transfer.md) | Medium·P2 | 확인된 결함 | Fileserver client가 짝 백엔드의 202 `REJECTED`(빈 파일 하나로 닿음)를 `SCHEMA_MISMATCH`로 읽고, 매뉴얼은 202를 "아직 검사 중"으로 적는다 | 17, 6, 8, 20, 10, 24 | `src/adapters/http/fileserver-upload.ts:194`, `:624-631`; `docs/manual/02-decision-tables.md:311`; 백엔드 `FileUploadController.java:195-200`, `FinalizeUploadApplicationUseCase.java:300-343` | |
|
||||
| [01-02](01-adapters-browser-transfer.md) | Medium·P2 | 구조적 위험 | 504 `TRANSFER_TIMEOUT`을 `NOT_APPLIED`·5초 뒤 재시도로 주지만 백엔드는 작업 단계와 상관없이 낸다. 효과 표가 V3 표·계약 문서 6.1과 갈라졌고 pin 밖이다 | 6, 28, 17, 23, 9, 21, 5 | `src/adapters/http/fileserver-upload.ts:154-170`, `:691-704`; `src/adapters/http/backend-envelope.ts:249-254`; 백엔드 `BlockingTransferExecutor.java:64-79` | |
|
||||
| [02-01](02-adapters-browser-files-cache.md) | Medium·P2 | 확인된 결함 | 제품 scope closer가 던지면 scope가 진단 없이 `FAILED`로 멈추고 `label`은 쓰이지 않는다 | 8, 7, 5, 17, 6 | `src/bootstrap/runtime-adapters.ts:409-423`, `src/adapters/query-cache/server-state-scope-runtime.ts:136-171`, `src/bootstrap/product-composition-contract.ts:100-103` | |
|
||||
| [09-02](09-app-core.md) | Medium·P2 | 확인된 결함 | Redis session 모드를 recipe·매뉴얼대로 이으면 서버 401이 세션 owner에 닿지 않는다(1103/09-01 수정과 1103/09-03 recipe 불일치) | 6, 28, 15, 17, 22, 4, 5, 10, 9 (32 세션 만료, 30.5) | `src/bootstrap/runtime-adapters.ts:583-591`; `recipes/session-owners/cookie-session-owner.ts:33`, `:179`; `docs/manual/04-paired-backend-session.md:186`, `:238-249` | |
|
||||
| [12-03](12-guardrails-ci.md) | Medium·P2 | 확인된 결함 | `CLAUDE.md` 리뷰 게이트 목록이 merge stage와 달라 merge 명령 87개 중 10개만 돌고 7개 게이트와 증거 검사가 빠진다 | 21, 5, 26, 23, 10 | `CLAUDE.md:23`, `config/ci/gates.json:2236-2256` | |
|
||||
| [12-04](#14-오케스트레이터-발견) | Medium·P2 | 확인된 결함 | 빌드·게이트가 고정 출력 경로(`dist/`, `artifacts/`)와 고정 포트(4173·4174·5173·6006)를 써서, 한 checkout에서 두 실행이 부딪힌다 | 20, 25, 12, 10, 21 | `playwright.config.ts:6`, `:13`, `:19-21`; `playwright.visual.config.ts:34`, `:59-61`; `playwright.capabilities.config.ts:26`, `:37-39`; `playwright.dev.config.ts:19-20`; `scripts/build-frontend.ts:18` | |
|
||||
| [13-02](13-build-release-supply-chain.md) | Medium·P2 | 구조적 위험 | 제품 merge 검사가 실패해도 같은 run의 release·승격·배포가 진행된다. job 그래프가 고정이라 제품이 막을 수도 없다 | 18, 21, 26, 3, 24 | `scripts/generate-ci-workflow.ts:129-157`, `scripts/contracts/ci-gates.ts:926-933`, `docs/operations/ci-quality-gates.md:377-378` | |
|
||||
| [14-01](14-template-product-docs.md) | Medium·P2 | 확인된 결함 | CHANGELOG 6단계대로 예제 기능을 지우면 문서 검사(FE-GATE-005 포함)와 안내한 드릴이 실패하고, `PRODUCT.md`는 지울 수 없다고 적는다 | 27, 30.5, 30.4, 9, 20, 10 | `docs/architecture/starter-experience.md:105-111`, `CHANGELOG.md:103`, `tests/unit/hosting-probe.test.ts:248`, `PRODUCT.md:33` | |
|
||||
| [11-01](11-tests-browser-release-scale.md) | Low·P2 | 구조적 위험 | preload 검사 증명 spec이 tracker만 증명해서, strict fixture가 그 결과를 버려도(11-R3, 9건 통과·안 쓴 preload probe 통과) 커밋된 test가 실패하지 않는다. 3번 test는 지연시킬 청크가 없으면 조용히 평범한 방문이 된다 | 10, 21, 5 | `tests/support/browser/strict-browser-test.ts:62`, `tests/e2e/preload-use.spec.ts:45-46`, `:105-126` | |
|
||||
| [12-02](12-guardrails-ci.md) | Low·P2 | 확인된 결함 | `verify:documentation`이 짝 백엔드 참조를 pin이 아니라 옆 checkout 작업 트리에서 찾아 기계마다 결과가 다르다(desktop rc=1) | 21, 17, 20, 23, 8 | `scripts/verify-documentation-readiness.ts:214-215`, `:308-316` | |
|
||||
| [14-02](14-template-product-docs.md) | Low·P2 | 확인된 결함 | 매뉴얼 04 §3.2의 제품 설정 키 예시에 `defaultValue`가 없어 `check:types`·`test:unit`이 실패한다 | 20, 19, 9 | `docs/manual/04-paired-backend-session.md:127-130`, `src/contracts/env.ts:37-42` | |
|
||||
| [15-04](15-performance.md) | Low·P2 | 구조적 위험 | lab은 플랫폼 화면 하나만 잰다. 기능 라우트 첫 진입은 lab 조건 406 ms(요청 두 묶음)인데 어느 게이트도 재지 않는다 | 14, 21, 13, 10 | `scripts/test-performance.ts:46`, `src/presentation/routes/app-router.tsx:510-538`, `CHANGELOG.md:269` | |
|
||||
| [16-01](16-structure-patterns.md) | Low·P2 | 구조적 위험 | 기능 하나를 더하면 추적 파일 `public/release-manifest.json`(자동)과 초기 JS 기록(명령)이 바뀌고, 03 문서·정본 표는 이를 말하지 않으며, 기능 브랜치 둘이 같은 줄에서 충돌한다 | 25, 3, 9, 20, 23, 27 | `scripts/create-feature.ts:1753-1754, 1787-1796`, `docs/manual/03-outside-feature-folder.md:22`, `docs/architecture/starter-experience.md:215-226` | |
|
||||
| [16-03](16-structure-patterns.md) | Low·P2 | 구조적 위험 | 생성 기능을 설치한 상태로 브라우저 merge 게이트(FE-GATE-008·009)를 도는 장치가 없다 | 10, 21, 20, 5 | `scripts/lib/feature-scaffold-drill.ts:18-37` | |
|
||||
| [16-04](16-structure-patterns.md) | Low·P2 | 확인된 결함 | 제품 기능 제거 드릴의 잔여 검사가 템플릿 테스트의 글자를 잔여로 잡아, 매뉴얼 예시 이름 `invoice-feature`로 만든 기능의 11단계가 실패한다. 안내는 템플릿 파일 수정이다 | 27, 20, 21, 24, 8 | `scripts/test-sample-removal.ts:113-120, 415-425`, `tests/unit/create-feature.test.ts:53`, `docs/manual/01-add-a-feature.md:94, 626`, `docs/manual/reference/errors.md:197` | |
|
||||
| [01-03](01-adapters-browser-transfer.md) | Low·P3 | 확인된 결함 | Fileserver client가 실패 Envelope의 `traceId`를 버린다 | 8, 23, 7 | `src/adapters/http/fileserver-upload.ts:638-640` | |
|
||||
| [01-04](01-adapters-browser-transfer.md) | Low·P3 | 확인된 결함 | Fileserver client 규칙 셋(5xx 두 code, 바이트 비례 deadline, 읽기 전 크기 거절)을 테스트가 고정하지 않는다 | 10, 21, 6, 14 | `src/adapters/http/fileserver-upload.ts:163-170`, `:211-215`, `:424-428` | |
|
||||
| [02-02](02-adapters-browser-files-cache.md) | Low·P3 | 구조적 위험 | 계속 읽히지 않는 캐시 본문은 다시 stage해도 고쳐지지 않고 rollback 대상은 회복 길이 없다 | 28, 6, 24, 11, 18 | `src/adapters/cache-storage/public-response-cache-adapter.ts:492-497`, `:1083-1088`, `:1139-1144` | |
|
||||
| [02-03](02-adapters-browser-files-cache.md) | Low·P3 | 확인된 결함 | 세션 레시피 주석이 매뉴얼이 막는 보강 방식을 가리키고 capability 전달은 테스트 밖이다 | 9, 20, 17, 10 | `recipes/frontend-capabilities/browser-file-session-capability.ts:21-30`, `tests/recipes/browser-file-session-capability.test.ts:142` | |
|
||||
| [02-04](02-adapters-browser-files-cache.md) | Low·P3 | 구조적 위험 | 1103/02-02의 손상 code 목록 경계 변이 5개가 살아남는다 | 10, 28, 6 | `src/adapters/cache-storage/public-response-cache-adapter.ts:1083-1088`, `tests/unit/public-response-cache-repair.test.ts:236-263`, `:320` | |
|
||||
| [03-01](03-adapters-http-state.md) | Low·P3 | 구조적 위험 | `refusedBeforeWrite`가 6.1절의 "쓰기 뒤 가능" 플랫폼 code(`BAD_PARAMETER`, `MAPPING_FAILED`, `DB_*`, `LOCK_ACQUISITION_TIMEOUT`)도 받는다 | 21, 6, 17, 5 | `src/contracts/external-contract-runtime.ts:608-646`, `src/adapters/http/backend-envelope.ts:317-327` | |
|
||||
| [03-02](03-adapters-http-state.md) | Low·P3 | 개선 제안 | 백엔드 §4의 503 `RATE_LIMIT_UNAVAILABLE`·`RATE_LIMIT_INCOMPATIBLE`이 답 표 밖이라 생성 쓰기에서 결과 불명이 된다 | 17, 6, 28, 9 | `config/contracts/backend-idempotency-answers.json`, `src/adapters/http/backend-envelope.ts:246-269`, `scripts/create-feature-write-slice.ts:298` | |
|
||||
| [04-01](04-adapters-realtime.md) | Low·P3 | 구조적 위험 | 서버 끊김 kind 변경 뒤 0929/04-01 회귀 테스트가 transport `OFFLINE` 경로를 지나지 않는다. 지운 두 줄을 되살려도 realtime 테스트가 모두 통과한다(04-R4) | 10, 21, 6, 28 | `tests/unit/realtime/realtime-reconnect-coordinator.test.ts:2095-2198`, `src/adapters/realtime/reconnect-coordinator.ts:111-117` | |
|
||||
| [04-02](04-adapters-realtime.md) | Low·P3 | 구조적 위험 | poll `execute`의 던짐을 서버 장애로 보고 재시도해 조합 결함이 서버 장애·예산 소진으로 보인다 | 8, 24, 6, 7 | `src/adapters/realtime/polling/bounded-poll-coordinator.ts:322-328`, `tests/unit/realtime/bounded-poll-coordinator.test.ts:906-948` | |
|
||||
| [04-03](04-adapters-realtime.md) | Low·P3 | 확인된 결함 | VD-28·설계 3절이 지운 V2 poll 예산·`REST QUERY`로 poll 규칙을 적는다 | 9, 24, 17 | `docs/architecture/decisions/VD-28-realtime-events-web-push-and-bounded-polling.md:117-118`, `:441-444` | |
|
||||
| [05-01](05-adapters-storage-kernel.md) | Low·P3 | 확인된 결함 | OIDC PKCE recipe가 Web Storage 키를 registry 밖에서 글자 그대로 만들어 `APP_NAMESPACE`를 바꾸면 갈라진다 | 23, 17, 15, 9, 21 | `recipes/session-owners/oidc-pkce-session-owner.ts:43-44`, `src/contracts/storage-keys.ts:179-185`, `docs/contracts/compatibility.md:31` | |
|
||||
| [06-01](06-adapters-service-worker-push.md) | Low·P3 | 확인된 결함 | 사전 캐시 수집이 `assets/` 밖 public 파일(`apple-touch-icon.png` 등)도 해시 자산으로 넣는다 | 18, 23, 5, 21 | `scripts/generate-service-worker-assets.ts:57-64`, `src/contracts/service-worker.ts:116` | |
|
||||
| [06-02](06-adapters-service-worker-push.md) | Low·P3 | 구조적 위험 | 확장자별 MIME probe가 redirect 뒤 200을 통과시키고, 워커 없는 빌드에도 돈다. live 호출 줄을 지워도 테스트가 통과한다 | 21, 18, 10 | `scripts/lib/hosting-probe.ts:276-315`, `scripts/verify-hosting-headers.ts:119-120` | |
|
||||
| [06-03](06-adapters-service-worker-push.md) | Low·P3 | 개선 제안 | SW 제어 아래 route import를 지키는 test가 없다. 11-09 허용으로 그 아래 preload 검사도 모두 꺼진다(허용이 워커 결함을 가리지는 않음) | 10, 28, 21 | `tests/e2e/service-worker-update.spec.ts:45-52`, `:267-276` | |
|
||||
| [07-01](07-contracts.md) | Low·P3 | 구조적 위험 | 짝 백엔드 답 표 JSON이 pin한 백엔드 문서와 같은지 아무 검사도 보지 않고, 백엔드 변경은 게이트 밖 drift 스크립트만 알린다(desktop에서 비교 불가, worktree에서 skipped rc=0, 매뉴얼에 없음) | 17, 21, 10, 20, 26 | `tests/unit/backend-contract-pin.test.ts:76-79`, `scripts/check-backend-contract-drift.ts:30, 40-45, 60`, `config/contracts/backend-contract-pin.json:7` | |
|
||||
| [07-02](07-contracts.md) | Low·P3 | 개선 제안 | 응답 스키마를 행과 함께 strict로 좁히는 변경이 FE-REG-SCHEMA에서 behavior-change로 통과하고 관련 테스트 25파일이 모두 통과한다(07-R1) | 17, 21, 23 | `config/contracts/registry-governance.json:288`, `scripts/lib/registry-compatibility.ts:346-351`, `tests/unit/schema-metadata-policy.test.ts:154-165` | |
|
||||
| [08-01](08-presentation.md) | Low·P3 | 확인된 결함 | 실패 상태의 복구 버튼을 키보드로 누르면 일이 끝난 뒤 버튼이 사라지며 포커스가 `body`로 떨어진다 | 1, 6, 10, 28 | `src/presentation/forms/use-app-form.ts:91-101`, `:176-195`; `src/features/reference-feature/presentation/reference-resource-form-page.tsx:141-183` | |
|
||||
| [08-02](08-presentation.md) | Low·P3 | 확인된 결함 | 생성 기능 폼이 "변경됨으로 확인" 뒤 아무것도 보이지 않고 입력을 비운다 | 24, 23, 20, 28 | `scripts/create-feature-write-slice.ts:703-721`, `:714` | |
|
||||
| [08-03](08-presentation.md) | Low·P3 | 확인된 결함 | 홈 시작 링크가 런타임에 꺼진 기능의 라우트를 가리킨다(`b96d61d8`) | 23, 1, 10 | `src/presentation/pages/home-page.tsx:21-23` vs `src/presentation/layouts/app-shell.tsx:196-202` | |
|
||||
| [08-04](08-presentation.md) | Low·P3 | 확인된 결함 | 다른 저장이 진행 중일 때 저장 버튼이 켜져 있지만 눌러도 반응이 없다(`2d5d41f8`) | 1, 24, 6 | `src/features/reference-feature/presentation/reference-resource-form-page.tsx:52-68`, `:124-131` | |
|
||||
| [09-03](09-app-core.md) | Low·P3 | 확인된 결함 | 계약 조립 오류의 원인이 `check:registries` 출력에 두 번 나온다 | 8, 20, 23 | `src/contracts/external-contract-runtime.ts:293`; `scripts/check-registries.ts:158-163` | |
|
||||
| [10-01](10-tests-fast-layers.md) | Low·P3 | 구조적 위험 | 1103 수정이 더한 플랫폼 규칙 테스트 둘(`MAX_RETRY_ATTEMPTS` 전달, 복구 중 세션 대기)이 참조 샘플에 기대어, 샘플을 지우면 함께 사라지고 제거 드릴은 알리지 않는다 | 10, 27, 21, 3, 19 | `tests/features/reference-feature/reference-runtime-composition.test.ts:163-204`, `tests/unit/navigation-policy.test.ts:40-56`, `scripts/test-sample-removal.ts:130-161` | |
|
||||
| [10-02](10-tests-fast-layers.md) | Low·P3 | 구조적 위험 | 실행기가 interaction signal에 단 abort listener 정리는 지워도 모든 테스트가 통과한다(호출자·scope 쪽만 고정) | 10, 12, 14, 21 | `src/adapters/http/http-execution-v3.ts:663`, `tests/unit/http-execution-v3.test.ts:764-805` | |
|
||||
| [10-03](#14-오케스트레이터-발견) | Low·P3 | 개선 제안 | 판정 규칙의 변이 실험을 리뷰어가 손으로 만들고 checkout 전체를 잠가 돌린다. 실행마다 사본을 따로 쓰는 변이 도구(예: Stryker)로 옮길 수 있다 | 10, 21, 20 | 이번 라운드 6.3절, `docs/reviews/2026-11-05-maturity-review/*.md` 6절 | |
|
||||
| [14-03](14-template-product-docs.md) | Low·P3 | 구조적 위험 | 참조 기능 경로 26줄을 백틱에서 빼 문서 검사 밖으로 냈다 | 21, 10, 9, 20 | `scripts/verify-documentation-readiness.ts:294-300`, `CHANGELOG.md:225`, `docs/manual/01-add-a-feature.md:8` | |
|
||||
| [15-01](15-performance.md) | Low·P3 | 확인된 결함 | lab 대상 화면이 그린 뒤 릴리스 칸을 늘려 21 px 민다(shift 0.0046). lab은 클릭 입력 창이라 0을 내고 `/` 밖의 CLS는 아무도 보지 않는다 | 14, 21, 10, 5 | `src/presentation/examples/platform-overview-page.tsx:422-454`, `scripts/test-performance.ts:111-118`, `:148-152` | |
|
||||
| [15-02](15-performance.md) | Low·P3 | 구조적 위험 | 초기 JS 기록 대조 허용 오차 1%(2,029 B)가 남은 여유(1,873 B)보다 크다 | 9, 21, 5, 13 | `scripts/scale/measure-feature-shape-growth.ts:227-246` | |
|
||||
| [15-03](15-performance.md) | Low·P3 | 구조적 위험 | 측정용 빌드 입력 목록이 두 파일에 같은 내용으로 있다 | 9, 23, 3, 10 | `scripts/scale/measure-feature-shape-growth.ts:40-49`, `tests/unit/product-feature-selection-build.test.ts:22-31` | |
|
||||
| [15-05](15-performance.md) | Low·P3 | 확인된 결함 | 홈 첫 렌더가 세로 스크롤바를 만들어 header를 15 px 민다(CLS 0.0002). 게이트는 스크롤바를 숨긴 Chromium이라 못 본다 | 14, 10, 21 | `src/presentation/styles/theme/base.css:1-71`, `scripts/test-performance.ts:186` | |
|
||||
| [16-02](16-structure-patterns.md) | Low·P3 | 구조적 위험 | 쓰기 slice가 백엔드 생성기 템플릿의 사실 넷을 손으로 옮겼고, pin·drift 검사는 `http-contract.md`만 본다 | 17, 9, 21, 23 | `scripts/create-feature-write-slice.ts:58-59, 83-84`, `config/contracts/backend-contract-pin.json:6-7`, `scripts/check-backend-contract-drift.ts:60` | |
|
||||
@@ -183,7 +183,15 @@ External provider supervision is fail-closed and requires a Linux runner with
|
||||
executable `/usr/bin/bwrap`, `/usr/bin/prlimit`, `/usr/bin/systemd-run`, and
|
||||
`/usr/bin/systemctl`, bubblewrap support for `--size`, an active user bus, a
|
||||
systemd user manager version 254 or newer, unified cgroup v2, and delegated
|
||||
memory, pids, and CPU controllers. Executable access, user-manager/version,
|
||||
memory, pids, and CPU controllers. The runner must also let an unprivileged
|
||||
process create user and network namespaces with bubblewrap: the sandbox runs
|
||||
`bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net`, and Ubuntu
|
||||
23.10 and later refuse that while
|
||||
`kernel.apparmor_restrict_unprivileged_userns=1` unless `/usr/bin/bwrap` has
|
||||
an AppArmor profile that allows `userns` (1105/12-01). The same holds for
|
||||
FE-GATE-013, whose `test:system` probes it first
|
||||
(`scripts/check-system-test-prerequisites.ts`); the fixes are in
|
||||
`docs/operations/ci-quality-gates.md`. Executable access, user-manager/version,
|
||||
trust, archive, and path failures are rejected before raw creation. Bubblewrap
|
||||
`--size` acceptance and effective delegated controller values can only be
|
||||
verified after the owned raw inode exists inside a new scope; failures there
|
||||
|
||||
@@ -12,7 +12,7 @@ Each gate is blocking in its declared scope. Failures are not downgraded with
|
||||
| capability contract | `pnpm test:contract` | reusable capability consumer contracts | `artifacts/tests/contract.xml` |
|
||||
| component | `pnpm test:component` | React/hook/UI behavior | `artifacts/tests/component.xml` |
|
||||
| integration | `pnpm test:integration` | HTTP/MSW, IndexedDB, composed browser-runtime boundaries, child-process/filesystem/IPC integration | `artifacts/tests/integration.xml` |
|
||||
| system / CI runner | `pnpm test:system` | compatible Linux host with systemd, bubblewrap, cgroup v2 and CI-provider process controls | `artifacts/tests/system.xml` |
|
||||
| system / CI runner | `pnpm test:system` | compatible Linux host with systemd, bubblewrap, cgroup v2 and CI-provider process controls, where bubblewrap may create unprivileged user and network namespaces | `artifacts/tests/system.xml` |
|
||||
| end-to-end | `pnpm test:e2e` | pinned browser engines | `artifacts/tests/e2e/` |
|
||||
| accessibility | `pnpm test:a11y` | pinned browser engines | `artifacts/tests/a11y.json` |
|
||||
|
||||
@@ -60,6 +60,11 @@ start the CI-runner suite.
|
||||
The system suite additionally runs
|
||||
`scripts/check-system-test-prerequisites.ts` and fails with one prerequisite
|
||||
report when the CI-runner host does not provide its required Linux facilities.
|
||||
Besides the executables, cgroup v2 and the systemd bus, it runs bubblewrap once
|
||||
with the provider sandbox's namespace options on `/bin/true`, so a host that
|
||||
refuses unprivileged user namespaces (Ubuntu 23.10 and later with
|
||||
`kernel.apparmor_restrict_unprivileged_userns=1`) fails there by name instead of
|
||||
in the provider tests (1105/12-01, `docs/operations/ci-quality-gates.md`).
|
||||
|
||||
## Development paths
|
||||
|
||||
|
||||
@@ -1,55 +1,154 @@
|
||||
import { constants } from "node:fs";
|
||||
import { access, readFile } from "node:fs/promises";
|
||||
import { spawnSync } from "node:child_process";
|
||||
import path from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
|
||||
const failures: string[] = [];
|
||||
import { PROVIDER_SANDBOX_NAMESPACE_ARGUMENTS } from "./lib/provider-sandbox-namespaces.ts";
|
||||
|
||||
async function requireExecutable(path: string, label: string): Promise<void> {
|
||||
try {
|
||||
await access(path, constants.X_OK);
|
||||
} catch {
|
||||
failures.push(`${label} is required at ${path}`);
|
||||
}
|
||||
}
|
||||
/** What the check reads from the host; a test passes a fake. */
|
||||
export type SystemTestHost = Readonly<{
|
||||
/** Resolves when `target` is executable, rejects otherwise. */
|
||||
access(target: string): Promise<void>;
|
||||
readFile(target: string): Promise<string>;
|
||||
spawn(
|
||||
command: string,
|
||||
args: readonly string[],
|
||||
timeoutMs: number,
|
||||
): Readonly<{ status: number | null; stderr: string; error?: Error | undefined }>;
|
||||
}>;
|
||||
|
||||
await Promise.all([
|
||||
requireExecutable("/usr/bin/bwrap", "bubblewrap"),
|
||||
requireExecutable("/usr/bin/systemctl", "systemctl"),
|
||||
requireExecutable("/usr/bin/tar", "tar"),
|
||||
export const nodeSystemTestHost: SystemTestHost = Object.freeze({
|
||||
access: async (target: string) => access(target, constants.X_OK),
|
||||
readFile: async (target: string) => readFile(target, "utf8"),
|
||||
spawn: (command: string, args: readonly string[], timeoutMs: number) => {
|
||||
const result = spawnSync(command, [...args], { encoding: "utf8", timeout: timeoutMs });
|
||||
return { status: result.status, stderr: result.stderr ?? "", error: result.error };
|
||||
},
|
||||
});
|
||||
|
||||
const BWRAP = "/usr/bin/bwrap";
|
||||
const SYSTEMCTL = "/usr/bin/systemctl";
|
||||
|
||||
/**
|
||||
* 1105/12-01. The provider sandbox's own namespace options on /bin/true. The
|
||||
* check used to see only that /usr/bin/bwrap was executable, so a host that
|
||||
* refuses unprivileged user namespaces passed it and then failed 18 provider
|
||||
* tests with `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`.
|
||||
*/
|
||||
export const NAMESPACE_PROBE_ARGUMENTS: readonly string[] = Object.freeze([
|
||||
...PROVIDER_SANDBOX_NAMESPACE_ARGUMENTS,
|
||||
"--ro-bind", "/", "/",
|
||||
"--", "/bin/true",
|
||||
]);
|
||||
|
||||
try {
|
||||
const controllers = await readFile("/sys/fs/cgroup/cgroup.controllers", "utf8");
|
||||
if (controllers.trim().length === 0) {
|
||||
failures.push("cgroup v2 controllers are unavailable");
|
||||
/** Host settings that decide whether an unprivileged process may create user namespaces. */
|
||||
const USER_NAMESPACE_SETTINGS = Object.freeze([
|
||||
["kernel.apparmor_restrict_unprivileged_userns", "/proc/sys/kernel/apparmor_restrict_unprivileged_userns"],
|
||||
["kernel.unprivileged_userns_clone", "/proc/sys/kernel/unprivileged_userns_clone"],
|
||||
["user.max_user_namespaces", "/proc/sys/user/max_user_namespaces"],
|
||||
] as const);
|
||||
|
||||
const PROBE_TIMEOUT_MS = 5_000;
|
||||
const MAX_REPORTED_STDERR_LINES = 4;
|
||||
|
||||
export async function findSystemTestPrerequisiteFailures(
|
||||
host: SystemTestHost = nodeSystemTestHost,
|
||||
): Promise<string[]> {
|
||||
const failures: string[] = [];
|
||||
const executable = new Map<string, boolean>();
|
||||
for (const [target, label] of [
|
||||
[BWRAP, "bubblewrap"],
|
||||
[SYSTEMCTL, "systemctl"],
|
||||
["/usr/bin/tar", "tar"],
|
||||
] as const) {
|
||||
try {
|
||||
await host.access(target);
|
||||
executable.set(target, true);
|
||||
} catch {
|
||||
executable.set(target, false);
|
||||
failures.push(`${label} is required at ${target}`);
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
failures.push("cgroup v2 is required at /sys/fs/cgroup/cgroup.controllers");
|
||||
}
|
||||
|
||||
if (!failures.some((failure) => failure.includes("systemctl"))) {
|
||||
const probe = spawnSync("/usr/bin/systemctl", ["show-environment"], {
|
||||
encoding: "utf8",
|
||||
timeout: 3_000,
|
||||
});
|
||||
if (probe.error || probe.status !== 0) {
|
||||
failures.push("a reachable systemd manager bus is required");
|
||||
try {
|
||||
const controllers = await host.readFile("/sys/fs/cgroup/cgroup.controllers");
|
||||
if (controllers.trim().length === 0) {
|
||||
failures.push("cgroup v2 controllers are unavailable");
|
||||
}
|
||||
} catch {
|
||||
failures.push("cgroup v2 is required at /sys/fs/cgroup/cgroup.controllers");
|
||||
}
|
||||
|
||||
if (executable.get(SYSTEMCTL)) {
|
||||
const probe = host.spawn(SYSTEMCTL, ["show-environment"], 3_000);
|
||||
if (probe.error || probe.status !== 0) {
|
||||
failures.push("a reachable systemd manager bus is required");
|
||||
}
|
||||
}
|
||||
|
||||
if (executable.get(BWRAP)) {
|
||||
const probe = host.spawn(BWRAP, NAMESPACE_PROBE_ARGUMENTS, PROBE_TIMEOUT_MS);
|
||||
if (probe.error || probe.status !== 0) {
|
||||
failures.push(await namespaceFailure(host, probe));
|
||||
}
|
||||
}
|
||||
return failures;
|
||||
}
|
||||
|
||||
if (failures.length > 0) {
|
||||
process.stderr.write(
|
||||
[
|
||||
"System/CI-runner test prerequisites are unavailable:",
|
||||
...failures.map((failure) => ` - ${failure}`),
|
||||
"",
|
||||
"Run test:unit/test:contract/test:component/test:integration for the",
|
||||
"developer loop. test:system is intentionally reserved for a compatible",
|
||||
"Linux CI-runner host.",
|
||||
"",
|
||||
].join("\n"),
|
||||
);
|
||||
process.exit(1);
|
||||
async function namespaceFailure(
|
||||
host: SystemTestHost,
|
||||
probe: ReturnType<SystemTestHost["spawn"]>,
|
||||
): Promise<string> {
|
||||
const settings: string[] = [];
|
||||
for (const [name, file] of USER_NAMESPACE_SETTINGS) {
|
||||
try {
|
||||
settings.push(`${name} = ${(await host.readFile(file)).trim()}`);
|
||||
} catch {
|
||||
// Absent on this kernel; the others still say what the host allows.
|
||||
}
|
||||
}
|
||||
const stderr = probe.stderr
|
||||
.split("\n")
|
||||
.map((line) => line.trim())
|
||||
.filter((line) => line.length > 0)
|
||||
.slice(0, MAX_REPORTED_STDERR_LINES);
|
||||
const outcome = probe.error
|
||||
? `did not finish: ${probe.error.message}`
|
||||
: `exited ${String(probe.status)}`;
|
||||
return [
|
||||
"this host does not allow unprivileged user and network namespaces, which the provider " +
|
||||
`sandbox needs (bwrap ${PROVIDER_SANDBOX_NAMESPACE_ARGUMENTS.join(" ")}).`,
|
||||
` probe: ${BWRAP} ${NAMESPACE_PROBE_ARGUMENTS.join(" ")} ${outcome}`,
|
||||
...(stderr.length > 0 ? stderr.map((line) => ` bwrap stderr: ${line}`) : [" bwrap stderr: (empty)"]),
|
||||
...(settings.length > 0 ? [` host settings: ${settings.join(", ")}`] : []),
|
||||
" To fix, do one of these:",
|
||||
" - give /usr/bin/bwrap an AppArmor profile that allows `userns` (Ubuntu 23.10 and later),",
|
||||
" - on a host you own, set sysctl kernel.apparmor_restrict_unprivileged_userns=0",
|
||||
" (or kernel.unprivileged_userns_clone=1 where that setting exists),",
|
||||
" - run FE-GATE-013 on another runner that allows them.",
|
||||
" Runner requirements: docs/operations/ci-quality-gates.md.",
|
||||
].join("\n");
|
||||
}
|
||||
|
||||
process.stdout.write("System test prerequisites: PASS\n");
|
||||
export function formatSystemTestPrerequisiteReport(failures: readonly string[]): string {
|
||||
return [
|
||||
"System/CI-runner test prerequisites are unavailable:",
|
||||
...failures.map((failure) => ` - ${failure}`),
|
||||
"",
|
||||
"Run test:unit/test:contract/test:component/test:integration for the",
|
||||
"developer loop. test:system is intentionally reserved for a compatible",
|
||||
"Linux CI-runner host.",
|
||||
"",
|
||||
].join("\n");
|
||||
}
|
||||
|
||||
const isCli = process.argv[1] !== undefined && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
|
||||
if (isCli) {
|
||||
const failures = await findSystemTestPrerequisiteFailures();
|
||||
if (failures.length > 0) {
|
||||
process.stderr.write(formatSystemTestPrerequisiteReport(failures));
|
||||
process.exit(1);
|
||||
}
|
||||
process.stdout.write("System test prerequisites: PASS\n");
|
||||
}
|
||||
|
||||
@@ -4,6 +4,7 @@ import path from "node:path";
|
||||
|
||||
import { z } from "zod";
|
||||
|
||||
import { DEPENDENCY_ADVISORIES_RECORD_PATH } from "../lib/dependency-advisories.ts";
|
||||
import { PROMOTION_FORMULA } from "../lib/promotion-readiness.ts";
|
||||
import {
|
||||
RELEASE_CANDIDATE_EVIDENCE_PATHS,
|
||||
@@ -290,6 +291,14 @@ const gateSchema = z
|
||||
evidenceArtifactIds: z.array(id).min(1).max(128),
|
||||
retentionClassId: id,
|
||||
requiresEnvironment: z.array(z.string().max(128).regex(/^[A-Z][A-Z0-9_]*$/u)).max(32).optional(),
|
||||
/**
|
||||
* 1105/12-01. What the runner host must provide for the gate to pass, one
|
||||
* line each. The workflow shows them as comments beside the job's
|
||||
* `runs-on`; a line cannot hold a line break, so it cannot leave the
|
||||
* comment. They describe the runner, not the gate's commands or evidence,
|
||||
* so the reviewed gate shape (canonicalGateShapeSha256) leaves them out.
|
||||
*/
|
||||
hostRequirements: z.array(nonEmpty.max(512)).min(1).max(8).optional(),
|
||||
})
|
||||
.strict();
|
||||
|
||||
@@ -944,7 +953,7 @@ function validateContractSemantics(
|
||||
const expectedStepKinds: Readonly<Record<string, readonly CiWorkflowStep["kind"][]>> = {
|
||||
merge_gate: ["checkout", "setup-node", "frozen-install", "browser-install", "run-gate", "upload"],
|
||||
release_gate: ["checkout", "setup-node", "frozen-install", "browser-install", "run-gate", "upload"],
|
||||
immutable_build: ["checkout", "setup-node", "frozen-install", "run-gate", "archive-candidate", "upload"],
|
||||
immutable_build: ["checkout", "setup-node", "frozen-install", "run-gate", "archive-candidate", "upload", "upload"],
|
||||
vulnerability_provider: ["checkout", "setup-node", "frozen-install", "download", "run-provider", "validate-provider-evidence", "upload"],
|
||||
provenance_provider: ["checkout", "setup-node", "frozen-install", "download", "run-provider", "validate-provider-evidence", "upload"],
|
||||
promotion: ["checkout", "setup-node", "frozen-install", "download", "download", "download", "verify-promotion", "upload", "cleanup-promotion"],
|
||||
@@ -1142,6 +1151,29 @@ function validateContractSemantics(
|
||||
validateCanonicalStepFields(contract, issue);
|
||||
}
|
||||
|
||||
const IMMUTABLE_GATE_EVIDENCE_TRANSFER_ID = "immutable-gate-evidence";
|
||||
|
||||
/**
|
||||
* 1105/13-01. What immutable_build uploads besides the candidate: the log and
|
||||
* evidence artifacts of each gate it runs, in gate order, then the advisory
|
||||
* record of scan:dependency-advisories (FE-GATE-027), which is not a gate
|
||||
* evidence artifact because it never blocks.
|
||||
*/
|
||||
function immutableGateEvidencePaths(
|
||||
contract: Pick<z.infer<typeof ciGateContractBaseSchema>, "artifacts" | "gates">,
|
||||
immutable: Pick<z.infer<typeof jobSchema>, "gateIds">,
|
||||
): string[] {
|
||||
const paths = immutable.gateIds.flatMap((gateId) => {
|
||||
const gate = contract.gates.find(({ id }) => id === gateId);
|
||||
return gate
|
||||
? [gate.logArtifactId, ...gate.evidenceArtifactIds].flatMap((artifactId) =>
|
||||
contract.artifacts.filter(({ id }) => id === artifactId).map(({ path: artifactPath }) => artifactPath),
|
||||
)
|
||||
: [];
|
||||
});
|
||||
return [...new Set([...paths, DEPENDENCY_ADVISORIES_RECORD_PATH])];
|
||||
}
|
||||
|
||||
function validateCanonicalStepFields(
|
||||
contract: z.infer<typeof ciGateContractBaseSchema>,
|
||||
issue: (message: string, path?: PropertyKey[]) => void,
|
||||
@@ -1160,6 +1192,26 @@ function validateCanonicalStepFields(
|
||||
) {
|
||||
issue("immutable archive and upload fields must remain linked");
|
||||
}
|
||||
// 1105/13-01. ci:gate writes command output only to the gate log and prints
|
||||
// one PASS/FAIL line, and this job uploaded only the candidate, on success.
|
||||
// Why FE-GATE-015 or FE-GATE-027 failed, and the advisory record FE-GATE-027
|
||||
// writes, went with the runner's workspace. A separate transfer, always and
|
||||
// last, carries them; the candidate archive's member set stays as it is.
|
||||
const gateEvidence = immutable?.steps.find(
|
||||
(step) => step.kind === "upload" && step.transferId === IMMUTABLE_GATE_EVIDENCE_TRANSFER_ID,
|
||||
);
|
||||
if (
|
||||
!immutable ||
|
||||
gateEvidence?.kind !== "upload" ||
|
||||
gateEvidence.always !== true ||
|
||||
immutable.steps.at(-1) !== gateEvidence ||
|
||||
JSON.stringify(gateEvidence.paths) !== JSON.stringify(immutableGateEvidencePaths(contract, immutable))
|
||||
) {
|
||||
issue(
|
||||
"immutable_build must upload its gates' logs and evidence and the dependency advisory record " +
|
||||
`as ${IMMUTABLE_GATE_EVIDENCE_TRANSFER_ID}, with always, as its last step`,
|
||||
);
|
||||
}
|
||||
|
||||
const providerExpectations = {
|
||||
vulnerability_provider: {
|
||||
|
||||
@@ -167,7 +167,11 @@ function renderJob(
|
||||
if (job.needs.length > 1) lines.push(` needs: [${job.needs.map(yamlKey).join(", ")}]`);
|
||||
const condition = renderCondition(job.condition);
|
||||
if (condition) lines.push(` if: ${condition}`);
|
||||
lines.push(" runs-on: ubuntu-latest", ` timeout-minutes: ${job.timeoutMinutes}`);
|
||||
lines.push(
|
||||
...renderHostRequirements(job, index),
|
||||
" runs-on: ubuntu-latest",
|
||||
` timeout-minutes: ${job.timeoutMinutes}`,
|
||||
);
|
||||
if (job.kind === "immutable") {
|
||||
const archive = job.steps.find((step) => step.kind === "archive-candidate");
|
||||
if (!archive || archive.kind !== "archive-candidate") throw new TypeError("immutable job lacks archive step");
|
||||
@@ -214,6 +218,24 @@ function renderJob(
|
||||
return lines;
|
||||
}
|
||||
|
||||
/**
|
||||
* 1105/12-01. A gate's host requirements (`hostRequirements` in
|
||||
* config/ci/gates.json) sit as comments beside the runner label of the job
|
||||
* that runs the gate, where whoever picks the runner reads them. FE-GATE-013
|
||||
* needs unprivileged user namespaces, and that was written nowhere a runner
|
||||
* is chosen. The contract keeps line breaks out of each requirement.
|
||||
*/
|
||||
function renderHostRequirements(
|
||||
job: CiWorkflowJob,
|
||||
index: ReturnType<typeof indexCiGateContract>,
|
||||
): string[] {
|
||||
return job.gateIds.flatMap((gateId) =>
|
||||
(index.gates.get(gateId)?.hostRequirements ?? []).map(
|
||||
(requirement) => ` # ${gateId} runner requirement: ${requirement}`,
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
function renderStep(
|
||||
job: CiWorkflowJob,
|
||||
step: CiWorkflowStep,
|
||||
|
||||
@@ -1,5 +1,11 @@
|
||||
import { validateVulnerabilityReport } from "./supply-chain.ts";
|
||||
|
||||
/**
|
||||
* Where scan:dependency-advisories writes its record. 1105/13-01: the
|
||||
* immutable_build job uploads it on every outcome (scripts/contracts/ci-gates.ts).
|
||||
*/
|
||||
export const DEPENDENCY_ADVISORIES_RECORD_PATH = "artifacts/security/dependency-advisories.json";
|
||||
|
||||
/**
|
||||
* 1103/13-03. The vulnerability verdict belongs to the external provider of
|
||||
* the production promotion (signed, independent of the build). Without a
|
||||
|
||||
@@ -0,0 +1,18 @@
|
||||
/**
|
||||
* 1105/12-01. The namespaces the provider sandbox asks bubblewrap for
|
||||
* (scripts/run-and-validate-provider.ts). bubblewrap is not setuid, so each of
|
||||
* them is an unprivileged user namespace plus the namespace named, and
|
||||
* `--unshare-net` also brings up loopback inside it.
|
||||
*
|
||||
* scripts/check-system-test-prerequisites.ts probes the host with this same
|
||||
* list. A host that refuses them (Ubuntu 24.04 with
|
||||
* kernel.apparmor_restrict_unprivileged_userns=1 and no AppArmor profile for
|
||||
* bwrap) then fails the prerequisite check by name, instead of passing it and
|
||||
* failing the provider tests with a raw netlink error.
|
||||
*/
|
||||
export const PROVIDER_SANDBOX_NAMESPACE_ARGUMENTS: readonly string[] = Object.freeze([
|
||||
"--unshare-pid",
|
||||
"--unshare-ipc",
|
||||
"--unshare-uts",
|
||||
"--unshare-net",
|
||||
]);
|
||||
@@ -30,6 +30,7 @@ import {
|
||||
type ProviderGuardianLease,
|
||||
} from "./lib/provider-guardian-client.ts";
|
||||
import { createProviderOutputLimiter } from "./lib/provider-output-limiter.ts";
|
||||
import { PROVIDER_SANDBOX_NAMESPACE_ARGUMENTS } from "./lib/provider-sandbox-namespaces.ts";
|
||||
import {
|
||||
providerProcessTraceEnvironment,
|
||||
traceOwnProviderProcess,
|
||||
@@ -253,7 +254,7 @@ async function runProviderInSandbox(
|
||||
const cpuSeconds = providerCpuSeconds();
|
||||
const bwrapArguments = [
|
||||
"--die-with-parent", "--new-session", "--as-pid-1",
|
||||
"--unshare-pid", "--unshare-ipc", "--unshare-uts", "--unshare-net",
|
||||
...PROVIDER_SANDBOX_NAMESPACE_ARGUMENTS,
|
||||
"--dev", "/dev", "--remount-ro", "/dev",
|
||||
"--proc", "/proc", "--remount-ro", "/proc",
|
||||
"--size", String(PROVIDER_TMP_BYTES), "--tmpfs", "/tmp",
|
||||
|
||||
@@ -2,7 +2,10 @@ import { spawnSync } from "node:child_process";
|
||||
import { createHash } from "node:crypto";
|
||||
import { mkdir, readFile, writeFile } from "node:fs/promises";
|
||||
|
||||
import { summarizeDependencyAdvisories } from "./lib/dependency-advisories.ts";
|
||||
import {
|
||||
DEPENDENCY_ADVISORIES_RECORD_PATH,
|
||||
summarizeDependencyAdvisories,
|
||||
} from "./lib/dependency-advisories.ts";
|
||||
|
||||
/**
|
||||
* 1103/13-03. Release-stage signal for known dependency advisories
|
||||
@@ -17,7 +20,7 @@ import { summarizeDependencyAdvisories } from "./lib/dependency-advisories.ts";
|
||||
* result is UNVERIFIED, not PASS. The signed verdict of the vulnerability
|
||||
* provider stays the only one that decides a promotion.
|
||||
*/
|
||||
const RECORD_PATH = "artifacts/security/dependency-advisories.json";
|
||||
const RECORD_PATH = DEPENDENCY_ADVISORIES_RECORD_PATH;
|
||||
|
||||
const [policy, exceptions, lockfile] = await Promise.all([
|
||||
readFile("config/security/vulnerability-policy.json", "utf8").then((text) => JSON.parse(text) as Record<string, unknown>),
|
||||
|
||||
@@ -37,6 +37,8 @@ jobs:
|
||||
merge_gate:
|
||||
name: "\${{ matrix.gate }} / \${{ matrix.name }}"
|
||||
if: \${{ gitea.event_name != 'workflow_dispatch' || inputs.stage != 'documentation' }}
|
||||
# FE-GATE-013 runner requirement: Linux with executable /usr/bin/bwrap (with --size), /usr/bin/prlimit, /usr/bin/systemd-run, /usr/bin/systemctl and /usr/bin/tar, an active systemd user manager 254 or newer, and unified cgroup v2 with delegated memory, pids and cpu controllers
|
||||
# FE-GATE-013 runner requirement: unprivileged user and network namespaces for bwrap (the provider sandbox runs bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net); Ubuntu 23.10 and later refuse them while kernel.apparmor_restrict_unprivileged_userns=1 unless /usr/bin/bwrap has an AppArmor profile that allows userns; scripts/check-system-test-prerequisites.ts probes this before test:system runs
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 45
|
||||
strategy:
|
||||
@@ -208,6 +210,20 @@ jobs:
|
||||
name: "release-candidate-\${{ gitea.run_id }}-\${{ gitea.run_attempt }}"
|
||||
path: ".release/release-candidate-\${{ gitea.run_id }}-\${{ gitea.run_attempt }}.tar.gz"
|
||||
if-no-files-found: error
|
||||
- name: Upload immutable gate evidence
|
||||
if: always()
|
||||
uses: https://github.com/ChristopherHX/gitea-upload-artifact@81f940d004763f986ba3582c007fd842dd5cb0d7
|
||||
with:
|
||||
name: "immutable-gate-evidence-\${{ gitea.run_id }}-\${{ gitea.run_attempt }}"
|
||||
path: |
|
||||
artifacts/quality/gates/FE-GATE-015.txt
|
||||
artifacts/release/release-candidate.json
|
||||
artifacts/release/verification.json
|
||||
artifacts/security/supply-chain-coherence.json
|
||||
artifacts/quality/gates/FE-GATE-027.txt
|
||||
artifacts/release/deployment-admission.json
|
||||
artifacts/security/dependency-advisories.json
|
||||
if-no-files-found: error
|
||||
|
||||
vulnerability_provider:
|
||||
name: external-vulnerability-provider
|
||||
|
||||
@@ -1654,7 +1654,7 @@ describe("CI workflow generation", () => {
|
||||
'if [ -n "$PROMOTION_STAGING_ROOT" ] && [ -n "$PROMOTION_CLEANUP_TOKEN" ] && [ -n "$PROMOTION_RUNNER_TEMP_DEV" ] && [ -n "$PROMOTION_RUNNER_TEMP_INO" ] && [ -n "$PROMOTION_STAGING_DEV" ] && [ -n "$PROMOTION_STAGING_INO" ]; then',
|
||||
);
|
||||
const actionUses = [...first.matchAll(/^\s+-?\s*uses: (.+)$/gmu)].map((match) => match[1]);
|
||||
expect(actionUses).toHaveLength(33);
|
||||
expect(actionUses).toHaveLength(34);
|
||||
expect(new Set(actionUses)).toEqual(
|
||||
new Set([
|
||||
"https://github.com/actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5",
|
||||
@@ -1698,6 +1698,36 @@ describe("CI workflow generation", () => {
|
||||
expect(workflow).toMatch(/^on:\n {2}push:\n {4}branches: \[main, develop\]$/mu);
|
||||
});
|
||||
|
||||
// 1105/12-01. The provider sandbox in FE-GATE-013 needs unprivileged user
|
||||
// and network namespaces. No runner requirement said so, and a host that
|
||||
// refuses them failed 18 provider tests after the prerequisite check passed.
|
||||
it("states FE-GATE-013's runner requirements beside the runner label of the job that runs it", async () => {
|
||||
const contract = await loadCiGateContract(process.cwd());
|
||||
const requirements = indexCiGateContract(contract).gates.get("FE-GATE-013")?.hostRequirements ?? [];
|
||||
expect(requirements.join("\n")).toMatch(/unprivileged user and network namespaces/u);
|
||||
expect(requirements.join("\n")).toContain("--unshare-net");
|
||||
expect(requirements.join("\n")).toContain("kernel.apparmor_restrict_unprivileged_userns");
|
||||
expect(requirements.join("\n")).toContain("scripts/check-system-test-prerequisites.ts");
|
||||
|
||||
const workflow = renderCiWorkflow(contract);
|
||||
const merge = workflow.slice(workflow.indexOf(" merge_gate:\n"), workflow.indexOf(" release_gate:\n"));
|
||||
const header = merge.slice(0, merge.indexOf(" runs-on: ubuntu-latest\n"));
|
||||
expect(header.split("\n").filter((line) => line.startsWith(" # "))).toEqual(
|
||||
requirements.map((requirement) => ` # FE-GATE-013 runner requirement: ${requirement}`),
|
||||
);
|
||||
expect(workflow.match(/ runner requirement: /gu)).toHaveLength(requirements.length);
|
||||
});
|
||||
|
||||
it("rejects a runner requirement that would leave its workflow comment (1105/12-01)", async () => {
|
||||
const contract = JSON.parse(
|
||||
JSON.stringify(await loadCiGateContract(process.cwd())),
|
||||
) as Record<string, any>;
|
||||
contract.gates.find((gate: Record<string, any>) => gate.id === "FE-GATE-013").hostRequirements = [
|
||||
"namespaces\n runs-on: self-hosted",
|
||||
];
|
||||
expect(() => parseCiGateContract(contract)).toThrow(/line-break characters are forbidden/u);
|
||||
});
|
||||
|
||||
// 12-02 / 13-01: immutable_build owns FE-GATE-015 and FE-GATE-027, but only
|
||||
// the first gate of a non-matrix job was ever rendered, so release admission
|
||||
// never ran in CI.
|
||||
@@ -1713,6 +1743,105 @@ describe("CI workflow generation", () => {
|
||||
expect(workflowGateExecutionFailures(contract, workflow)).toEqual([]);
|
||||
});
|
||||
|
||||
// 1105/13-01. ci:gate writes each command's output only to the gate log and
|
||||
// prints one PASS/FAIL line. immutable_build uploaded only the candidate, on
|
||||
// success, so why FE-GATE-015 or FE-GATE-027 failed, and the advisory record
|
||||
// FE-GATE-027 writes (1103/13-03), went with the runner's workspace.
|
||||
const IMMUTABLE_GATE_EVIDENCE_PATHS = [
|
||||
"artifacts/quality/gates/FE-GATE-015.txt",
|
||||
"artifacts/release/release-candidate.json",
|
||||
"artifacts/release/verification.json",
|
||||
"artifacts/security/supply-chain-coherence.json",
|
||||
"artifacts/quality/gates/FE-GATE-027.txt",
|
||||
"artifacts/release/deployment-admission.json",
|
||||
"artifacts/security/dependency-advisories.json",
|
||||
];
|
||||
|
||||
it("uploads immutable_build's gate logs, evidence and advisory record on every outcome (1105/13-01)", async () => {
|
||||
const contract = await loadCiGateContract(process.cwd());
|
||||
const index = indexCiGateContract(contract);
|
||||
const gatePaths = ["FE-GATE-015", "FE-GATE-027"].flatMap((gateId) => {
|
||||
const gate = index.gates.get(gateId)!;
|
||||
return [gate.logArtifactId, ...gate.evidenceArtifactIds].map((artifactId) => index.artifacts.get(artifactId)!.path);
|
||||
});
|
||||
expect(IMMUTABLE_GATE_EVIDENCE_PATHS).toEqual([...gatePaths, "artifacts/security/dependency-advisories.json"]);
|
||||
|
||||
const workflow = renderCiWorkflow(contract);
|
||||
const immutable = workflow.slice(
|
||||
workflow.indexOf(" immutable_build:\n"),
|
||||
workflow.indexOf(" vulnerability_provider:\n"),
|
||||
);
|
||||
const candidateUpload = immutable.indexOf(" - name: Upload release candidate\n");
|
||||
const evidenceUpload = immutable.indexOf(" - name: Upload immutable gate evidence\n");
|
||||
expect(candidateUpload).toBeGreaterThan(immutable.indexOf("ci:gate -- FE-GATE-027"));
|
||||
expect(evidenceUpload).toBeGreaterThan(candidateUpload);
|
||||
expect(immutable.slice(evidenceUpload)).toBe(
|
||||
[
|
||||
" - name: Upload immutable gate evidence",
|
||||
" if: always()",
|
||||
` uses: ${resolveCiActionUses("uploadArtifact")}`,
|
||||
" with:",
|
||||
' name: "immutable-gate-evidence-${{ gitea.run_id }}-${{ gitea.run_attempt }}"',
|
||||
" path: |",
|
||||
...IMMUTABLE_GATE_EVIDENCE_PATHS.map((target) => ` ${target}`),
|
||||
" if-no-files-found: error",
|
||||
"",
|
||||
"",
|
||||
].join("\n"),
|
||||
);
|
||||
// The candidate still goes up only after its archive was validated, and
|
||||
// the archive's member set is not widened by the evidence.
|
||||
expect(immutable.slice(candidateUpload, evidenceUpload)).not.toContain("if: always()");
|
||||
const archive = contract.jobs
|
||||
.find(({ id }) => id === "immutable_build")
|
||||
?.steps.find((step) => step.kind === "archive-candidate");
|
||||
expect(archive?.kind === "archive-candidate" ? archive.members : []).not.toContain(
|
||||
"artifacts/quality/gates/FE-GATE-027.txt",
|
||||
);
|
||||
});
|
||||
|
||||
it.each([
|
||||
[
|
||||
"is missing",
|
||||
(steps: Record<string, any>[]) => steps.splice(steps.findIndex((step) => step.transferId === "immutable-gate-evidence"), 1),
|
||||
],
|
||||
[
|
||||
"runs only on success",
|
||||
(steps: Record<string, any>[]) => delete steps.find((step) => step.transferId === "immutable-gate-evidence")!.always,
|
||||
],
|
||||
[
|
||||
"leaves out the advisory record",
|
||||
(steps: Record<string, any>[]) => {
|
||||
const upload = steps.find((step) => step.transferId === "immutable-gate-evidence")!;
|
||||
upload.paths = upload.paths.filter((target: string) => target !== "artifacts/security/dependency-advisories.json");
|
||||
},
|
||||
],
|
||||
[
|
||||
"leaves out the FE-GATE-027 log",
|
||||
(steps: Record<string, any>[]) => {
|
||||
const upload = steps.find((step) => step.transferId === "immutable-gate-evidence")!;
|
||||
upload.paths = upload.paths.filter((target: string) => target !== "artifacts/quality/gates/FE-GATE-027.txt");
|
||||
},
|
||||
],
|
||||
[
|
||||
"comes before the candidate upload",
|
||||
(steps: Record<string, any>[]) => {
|
||||
const evidence = steps.splice(steps.findIndex((step) => step.transferId === "immutable-gate-evidence"), 1)[0]!;
|
||||
steps.splice(steps.findIndex((step) => step.transferId === "release-candidate"), 0, evidence);
|
||||
},
|
||||
],
|
||||
])("rejects an immutable_build whose gate evidence upload %s (1105/13-01)", async (_name, mutate) => {
|
||||
const contract = JSON.parse(
|
||||
JSON.stringify(await loadCiGateContract(process.cwd())),
|
||||
) as Record<string, any>;
|
||||
const steps = contract.jobs.find((job: Record<string, any>) => job.id === "immutable_build").steps;
|
||||
expect(steps.filter((step: Record<string, any>) => step.transferId === "immutable-gate-evidence")).toHaveLength(1);
|
||||
mutate(steps);
|
||||
expect(() => parseCiGateContract(contract)).toThrow(
|
||||
/immutable_build must upload its gates' logs and evidence and the dependency advisory record/u,
|
||||
);
|
||||
});
|
||||
|
||||
it.each([
|
||||
["a non-matrix gate step", " run: corepack pnpm ci:gate -- FE-GATE-027\n", "FE-GATE-027"],
|
||||
["a matrix entry", " - { gate: FE-GATE-020, name: removability, browser: false }\n", "FE-GATE-020"],
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
import { spawnSync } from "node:child_process";
|
||||
import { existsSync } from "node:fs";
|
||||
import { cp, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
|
||||
import { cp, mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import path from "node:path";
|
||||
|
||||
@@ -23,72 +23,131 @@ import { REMOVAL_FIXTURE_COPY_TARGETS } from "../../scripts/lib/removal-fixture.
|
||||
* - a product runtime-config key with a `.default()`, which the template's
|
||||
* own tests must not have to spell out.
|
||||
*
|
||||
* Only product-owned files and the feature's own directory are written.
|
||||
* Only product-owned files, the product files kept next to them and the
|
||||
* probe's own feature and context directories are written.
|
||||
*
|
||||
* The probe's names (`typecheck-probe-*`) are reserved for it: they are not
|
||||
* the manual's example names, which a product may well use (1103 X2 #1). The
|
||||
* capability type is appended to the product's own declaration, which a
|
||||
* TypeScript interface merges, so a product that already declares
|
||||
* capabilities keeps them.
|
||||
* the manual's example names, which a product may well use (1103 X2 #1).
|
||||
*
|
||||
* 1105/09-01. The probe adds to the product's files and keeps everything they
|
||||
* already declare and build. The capability type is appended to the
|
||||
* product's own declaration, which a TypeScript interface merges. The
|
||||
* product's `product-contracts.ts` and `product-composition.ts` move to
|
||||
* `<name>-product-*.ts` beside themselves; the probe's files re-export them
|
||||
* and add only the probe's key, env row and capability on top. Writing those
|
||||
* two files from scratch dropped the capabilities a product builds for its
|
||||
* own features, so in such a product the app program failed with TS2741 in
|
||||
* `src/bootstrap/runtime-adapters.ts`.
|
||||
*/
|
||||
const PRODUCT_CAPABILITIES_FILE = "src/features/product-capabilities.ts";
|
||||
const PRODUCT_CONTRACTS_FILE = "src/contracts/product-contracts.ts";
|
||||
const PRODUCT_COMPOSITION_FILE = "src/bootstrap/product-composition.ts";
|
||||
|
||||
/** Every name one extension adds, derived from one reserved name. */
|
||||
function productExtension(name: string, camelName: string, constantName: string) {
|
||||
return Object.freeze({
|
||||
featureId: `${name}-feature`,
|
||||
contextId: `${name}-context`,
|
||||
routePath: `${name}/*`,
|
||||
messageKey: `${camelName}.title`,
|
||||
capability: `${camelName}Settings`,
|
||||
configKey: `${constantName}_PAGE_SIZE`,
|
||||
keptContracts: `src/contracts/${name}-product-contracts.ts`,
|
||||
keptComposition: `src/bootstrap/${name}-product-composition.ts`,
|
||||
});
|
||||
}
|
||||
|
||||
type ProductExtension = ReturnType<typeof productExtension>;
|
||||
|
||||
/** The probe itself. */
|
||||
const PROBE = productExtension("typecheck-probe", "typecheckProbe", "TYPECHECK_PROBE");
|
||||
|
||||
/**
|
||||
* 1105/09-01. Stands in for a downstream's own capability and the feature that
|
||||
* needs it. It is added the same way, so in a downstream it lands on top of
|
||||
* the downstream's real product files too.
|
||||
*/
|
||||
const DOWNSTREAM = productExtension(
|
||||
"typecheck-probe-downstream",
|
||||
"typecheckProbeDownstream",
|
||||
"TYPECHECK_PROBE_DOWNSTREAM",
|
||||
);
|
||||
|
||||
/** Appended to the product's own `product-capabilities.ts`. */
|
||||
const PRODUCT_CAPABILITY_TYPES = `
|
||||
function capabilityType(extension: ProductExtension): string {
|
||||
return `
|
||||
export interface ProductFeaturePlatformCapabilities {
|
||||
readonly typecheckProbeSettings: Readonly<{ pageSize(): number }>;
|
||||
readonly ${extension.capability}: Readonly<{ pageSize(): number }>;
|
||||
}
|
||||
`;
|
||||
}
|
||||
|
||||
const PRODUCT_CONTRACTS = `import { z } from "./zod.ts";
|
||||
/** Replaces `product-contracts.ts`; the product's own is kept beside it. */
|
||||
function productContracts(extension: ProductExtension): string {
|
||||
const kept = `./${path.posix.basename(extension.keptContracts)}`;
|
||||
return `import {
|
||||
PRODUCT_ENV_REGISTRY as KEPT_PRODUCT_ENV_REGISTRY,
|
||||
PRODUCT_RUNTIME_CONFIG_FIELDS as KEPT_PRODUCT_RUNTIME_CONFIG_FIELDS,
|
||||
} from "${kept}";
|
||||
import { z } from "./zod.ts";
|
||||
|
||||
/**
|
||||
* Product-owned. Filled by the 1103/09-02 typecheck fixture on top of the
|
||||
* product's own file, kept as ${kept} (1105/09-01).
|
||||
*/
|
||||
export * from "${kept}";
|
||||
|
||||
/** Product-owned. Filled by the 1103/09-02 typecheck fixture. */
|
||||
export const PRODUCT_RUNTIME_CONFIG_FIELDS = Object.freeze({
|
||||
TYPECHECK_PROBE_PAGE_SIZE: z.int().min(1).max(100).default(20),
|
||||
...KEPT_PRODUCT_RUNTIME_CONFIG_FIELDS,
|
||||
${extension.configKey}: z.int().min(1).max(100).default(20),
|
||||
});
|
||||
|
||||
export const PRODUCT_ENV_REGISTRY = Object.freeze({
|
||||
TYPECHECK_PROBE_PAGE_SIZE: {
|
||||
...KEPT_PRODUCT_ENV_REGISTRY,
|
||||
${extension.configKey}: {
|
||||
phase: "runtime",
|
||||
classification: "public",
|
||||
required: false,
|
||||
defaultValue: "20",
|
||||
},
|
||||
} as const);
|
||||
|
||||
export const PRODUCT_REST_AUTH_PROFILES = Object.freeze({});
|
||||
`;
|
||||
|
||||
const PRODUCT_COMPOSITION = `import type {
|
||||
ProductComposition,
|
||||
ProductCompositionContext,
|
||||
ProductSessionOwner,
|
||||
ProductSessionOwnerContext,
|
||||
} from "./product-composition-contract.ts";
|
||||
|
||||
/** Product-owned. Filled by the 1103/09-02 typecheck fixture. */
|
||||
export function composeProductSessionOwner(
|
||||
context: ProductSessionOwnerContext,
|
||||
): ProductSessionOwner {
|
||||
return null;
|
||||
}
|
||||
|
||||
/** Replaces `product-composition.ts`; the product's own is kept beside it. */
|
||||
function productComposition(extension: ProductExtension): string {
|
||||
const kept = `./${path.posix.basename(extension.keptComposition)}`;
|
||||
return `import type {
|
||||
ProductComposition,
|
||||
ProductCompositionContext,
|
||||
} from "./product-composition-contract.ts";
|
||||
import { composeProduct as composeKeptProduct } from "${kept}";
|
||||
|
||||
/**
|
||||
* Product-owned. Filled by the 1103/09-02 typecheck fixture on top of the
|
||||
* product's own file, kept as ${kept} (1105/09-01).
|
||||
*/
|
||||
export * from "${kept}";
|
||||
|
||||
export function composeProduct(context: ProductCompositionContext) {
|
||||
const pageSize = context.config.TYPECHECK_PROBE_PAGE_SIZE;
|
||||
const product = composeKeptProduct(context);
|
||||
const pageSize = context.config.${extension.configKey};
|
||||
return {
|
||||
...product,
|
||||
capabilities: {
|
||||
typecheckProbeSettings: Object.freeze({ pageSize: () => pageSize }),
|
||||
...product.capabilities,
|
||||
${extension.capability}: Object.freeze({ pageSize: () => pageSize }),
|
||||
},
|
||||
credentialProviders: {},
|
||||
} satisfies ProductComposition;
|
||||
}
|
||||
`;
|
||||
}
|
||||
|
||||
const FEATURE_ID = "typecheck-probe-feature";
|
||||
const CONTEXT_ID = "typecheck-probe-context";
|
||||
function featureModule(extension: ProductExtension): string {
|
||||
return `import { defineFeatureModule } from "../feature-module.ts";
|
||||
|
||||
const FEATURE_MODULE = `import { defineFeatureModule } from "../feature-module.ts";
|
||||
|
||||
export const FEATURE_MODULE_ID = "${FEATURE_ID}";
|
||||
export const FEATURE_CONTEXT_ID = "${CONTEXT_ID}";
|
||||
export const FEATURE_MODULE_ID = "${extension.featureId}";
|
||||
export const FEATURE_CONTEXT_ID = "${extension.contextId}";
|
||||
|
||||
export const FEATURE_MODULE = defineFeatureModule({
|
||||
id: FEATURE_MODULE_ID,
|
||||
@@ -106,54 +165,59 @@ export const FEATURE_MODULE = defineFeatureModule({
|
||||
},
|
||||
routes: {},
|
||||
// Both locales: with the sample features removed (test:sample-removal)
|
||||
// this is the only catalog the message key types come from.
|
||||
// the probe's catalogs are the only ones the message key types come from.
|
||||
messages: {
|
||||
"ko-KR": { "typecheckProbe.title": "타입 검사 탐침" },
|
||||
"en-US": { "typecheckProbe.title": "Typecheck probe" },
|
||||
"ko-KR": { "${extension.messageKey}": "타입 검사 탐침" },
|
||||
"en-US": { "${extension.messageKey}": "Typecheck probe" },
|
||||
},
|
||||
loadRuntime: async () => (await import("./feature-runtime.ts")).FEATURE_RUNTIME,
|
||||
} as const);
|
||||
`;
|
||||
}
|
||||
|
||||
const FEATURE_RUNTIME = `import { defineFeatureAdapterContribution } from "../feature-adapter-contribution.ts";
|
||||
function featureRuntime(extension: ProductExtension): string {
|
||||
return `import { defineFeatureAdapterContribution } from "../feature-adapter-contribution.ts";
|
||||
import { defineFeatureRuntime } from "../feature-module.ts";
|
||||
|
||||
type TypecheckProbeInput = Readonly<{ pageSize(): number }>;
|
||||
|
||||
declare module "../../application/ports/in/application-api.ts" {
|
||||
interface ApplicationFeatureInputs {
|
||||
"${FEATURE_ID}": TypecheckProbeInput;
|
||||
"${extension.featureId}": TypecheckProbeInput;
|
||||
}
|
||||
}
|
||||
|
||||
export const FEATURE_RUNTIME = defineFeatureRuntime({
|
||||
featureId: "${FEATURE_ID}",
|
||||
featureId: "${extension.featureId}",
|
||||
schemas: {},
|
||||
adapters: [
|
||||
defineFeatureAdapterContribution({
|
||||
featureId: "${FEATURE_ID}",
|
||||
needs: ["typecheckProbeSettings"] as const,
|
||||
createInput: ({ typecheckProbeSettings }) =>
|
||||
featureId: "${extension.featureId}",
|
||||
needs: ["${extension.capability}"] as const,
|
||||
createInput: ({ ${extension.capability} }) =>
|
||||
Object.freeze({
|
||||
featureId: "${FEATURE_ID}",
|
||||
input: Object.freeze({ pageSize: () => typecheckProbeSettings.pageSize() }),
|
||||
featureId: "${extension.featureId}",
|
||||
input: Object.freeze({ pageSize: () => ${extension.capability}.pageSize() }),
|
||||
}),
|
||||
}),
|
||||
],
|
||||
contractContributions: [],
|
||||
} as const);
|
||||
`;
|
||||
}
|
||||
|
||||
const CONTEXT_ROUTES = `import type { RouteObject } from "react-router-dom";
|
||||
|
||||
export const FEATURE_CONTEXT_ROUTES: readonly RouteObject[] = Object.freeze([]);
|
||||
`;
|
||||
|
||||
const CONTEXT_MODULE = `export const CONTEXT_MODULE_ID = "${CONTEXT_ID}";
|
||||
function contextModule(extension: ProductExtension): string {
|
||||
return `export const CONTEXT_MODULE_ID = "${extension.contextId}";
|
||||
export const CONTEXT_APP_ID = "template-app";
|
||||
export const CONTEXT_ROUTE_PATH = "typecheck-probe/*";
|
||||
export const CONTEXT_ROUTE_PATH = "${extension.routePath}";
|
||||
export const CONTEXT_MAX_FEATURES = 1;
|
||||
`;
|
||||
}
|
||||
|
||||
const roots: string[] = [];
|
||||
|
||||
@@ -161,53 +225,99 @@ afterAll(async () => {
|
||||
await Promise.all(roots.map((root) => rm(root, { recursive: true, force: true })));
|
||||
});
|
||||
|
||||
describe("1103/09-02 a product filled through its own files typechecks", () => {
|
||||
it("passes the app, node and test programs", async () => {
|
||||
const root = await mkdtemp(path.join(tmpdir(), "product-extension-typecheck-"));
|
||||
roots.push(root);
|
||||
// The repository's one copy-target list for a fixture copy. A removal
|
||||
// drill runs this test in a copy that has already lost some of them
|
||||
// (test:optional-recipe-removal deletes recipes/).
|
||||
expect(existsSync(path.resolve("src/features", FEATURE_ID)), FEATURE_ID).toBe(false);
|
||||
for (const entry of REMOVAL_FIXTURE_COPY_TARGETS) {
|
||||
if (!existsSync(path.resolve(entry))) continue;
|
||||
await cp(path.resolve(entry), path.join(root, entry), {
|
||||
recursive: true,
|
||||
filter: (source) => !source.includes(`${path.sep}.generated`),
|
||||
});
|
||||
}
|
||||
await linkFixtureNodeModules(root);
|
||||
const shipped = await readFile(path.resolve("src/features/product-capabilities.ts"), "utf8");
|
||||
const files: Readonly<Record<string, string>> = {
|
||||
"src/features/product-capabilities.ts": `${shipped}${PRODUCT_CAPABILITY_TYPES}`,
|
||||
"src/contracts/product-contracts.ts": PRODUCT_CONTRACTS,
|
||||
"src/bootstrap/product-composition.ts": PRODUCT_COMPOSITION,
|
||||
[`src/contexts/${CONTEXT_ID}/context-module.ts`]: CONTEXT_MODULE,
|
||||
[`src/features/${FEATURE_ID}/feature-module.ts`]: FEATURE_MODULE,
|
||||
[`src/features/${FEATURE_ID}/feature-runtime.ts`]: FEATURE_RUNTIME,
|
||||
[`src/features/${FEATURE_ID}/context-routes.ts`]: CONTEXT_ROUTES,
|
||||
};
|
||||
for (const [file, content] of Object.entries(files)) {
|
||||
await mkdir(path.dirname(path.join(root, file)), { recursive: true });
|
||||
await writeFile(path.join(root, file), content);
|
||||
}
|
||||
async function copyRepository(): Promise<string> {
|
||||
const root = await mkdtemp(path.join(tmpdir(), "product-extension-typecheck-"));
|
||||
roots.push(root);
|
||||
// The repository's one copy-target list for a fixture copy. A removal
|
||||
// drill runs this test in a copy that has already lost some of them
|
||||
// (test:optional-recipe-removal deletes recipes/).
|
||||
for (const entry of REMOVAL_FIXTURE_COPY_TARGETS) {
|
||||
if (!existsSync(path.resolve(entry))) continue;
|
||||
await cp(path.resolve(entry), path.join(root, entry), {
|
||||
recursive: true,
|
||||
filter: (source) => !source.includes(`${path.sep}.generated`),
|
||||
});
|
||||
}
|
||||
await linkFixtureNodeModules(root);
|
||||
return root;
|
||||
}
|
||||
|
||||
const generated = spawnSync(
|
||||
process.execPath,
|
||||
[path.resolve("scripts/generate-product-feature-index.ts"), `--root=${root}`],
|
||||
async function writeFiles(root: string, files: Readonly<Record<string, string>>): Promise<void> {
|
||||
for (const [file, content] of Object.entries(files)) {
|
||||
await mkdir(path.dirname(path.join(root, file)), { recursive: true });
|
||||
await writeFile(path.join(root, file), content);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Adds one capability, its runtime-config key and a feature that needs it to
|
||||
* the copy, keeping whatever the copy's product files already hold.
|
||||
*/
|
||||
async function addProductExtension(root: string, extension: ProductExtension): Promise<void> {
|
||||
// The extension's names are reserved for this file: a product that took one
|
||||
// fails here, by name, instead of with a TS error in the copy.
|
||||
for (const owned of [
|
||||
`src/features/${extension.featureId}`,
|
||||
`src/contexts/${extension.contextId}`,
|
||||
extension.keptContracts,
|
||||
extension.keptComposition,
|
||||
]) {
|
||||
expect(existsSync(path.join(root, owned)), owned).toBe(false);
|
||||
}
|
||||
await rename(path.join(root, PRODUCT_CONTRACTS_FILE), path.join(root, extension.keptContracts));
|
||||
await rename(
|
||||
path.join(root, PRODUCT_COMPOSITION_FILE),
|
||||
path.join(root, extension.keptComposition),
|
||||
);
|
||||
const capabilities = await readFile(path.join(root, PRODUCT_CAPABILITIES_FILE), "utf8");
|
||||
await writeFiles(root, {
|
||||
[PRODUCT_CAPABILITIES_FILE]: `${capabilities}${capabilityType(extension)}`,
|
||||
[PRODUCT_CONTRACTS_FILE]: productContracts(extension),
|
||||
[PRODUCT_COMPOSITION_FILE]: productComposition(extension),
|
||||
[`src/contexts/${extension.contextId}/context-module.ts`]: contextModule(extension),
|
||||
[`src/features/${extension.featureId}/feature-module.ts`]: featureModule(extension),
|
||||
[`src/features/${extension.featureId}/feature-runtime.ts`]: featureRuntime(extension),
|
||||
[`src/features/${extension.featureId}/context-routes.ts`]: CONTEXT_ROUTES,
|
||||
});
|
||||
}
|
||||
|
||||
/** Generates the copy's indexes and runs the three programs of `check:types`. */
|
||||
function expectTypecheckPasses(root: string): void {
|
||||
const generated = spawnSync(
|
||||
process.execPath,
|
||||
[path.resolve("scripts/generate-product-feature-index.ts"), `--root=${root}`],
|
||||
{ encoding: "utf8" },
|
||||
);
|
||||
expect(generated.stderr).toBe("");
|
||||
expect(generated.status).toBe(0);
|
||||
|
||||
for (const project of ["tsconfig.app.json", "tsconfig.node.json", "tsconfig.test.json"]) {
|
||||
const typecheck = spawnSync(
|
||||
path.resolve("node_modules/.bin/tsc"),
|
||||
["--project", path.join(root, project)],
|
||||
{ encoding: "utf8" },
|
||||
);
|
||||
expect(generated.stderr).toBe("");
|
||||
expect(generated.status).toBe(0);
|
||||
expect(typecheck.stdout + typecheck.stderr, project).toBe("");
|
||||
expect(typecheck.status, project).toBe(0);
|
||||
}
|
||||
}
|
||||
|
||||
for (const project of ["tsconfig.app.json", "tsconfig.node.json", "tsconfig.test.json"]) {
|
||||
const typecheck = spawnSync(
|
||||
path.resolve("node_modules/.bin/tsc"),
|
||||
["--project", path.join(root, project)],
|
||||
{ encoding: "utf8" },
|
||||
);
|
||||
expect(typecheck.stdout + typecheck.stderr, project).toBe("");
|
||||
expect(typecheck.status, project).toBe(0);
|
||||
}
|
||||
describe("1103/09-02 a product filled through its own files typechecks", () => {
|
||||
it("passes the app, node and test programs", async () => {
|
||||
const root = await copyRepository();
|
||||
await addProductExtension(root, PROBE);
|
||||
expectTypecheckPasses(root);
|
||||
}, 120_000);
|
||||
});
|
||||
|
||||
describe("1105/09-01 the probe keeps what the product's own files build", () => {
|
||||
// The copy first becomes a downstream whose own product-composition.ts
|
||||
// builds a capability for its own feature, as memento and tech-log do
|
||||
// (CHANGELOG.md, `composeProduct(context)`). The probe must not take it away.
|
||||
it("passes when a product feature needs a product capability", async () => {
|
||||
const root = await copyRepository();
|
||||
await addProductExtension(root, DOWNSTREAM);
|
||||
await addProductExtension(root, PROBE);
|
||||
expectTypecheckPasses(root);
|
||||
}, 120_000);
|
||||
});
|
||||
|
||||
@@ -0,0 +1,125 @@
|
||||
import { readFile } from "node:fs/promises";
|
||||
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import {
|
||||
findSystemTestPrerequisiteFailures,
|
||||
formatSystemTestPrerequisiteReport,
|
||||
NAMESPACE_PROBE_ARGUMENTS,
|
||||
type SystemTestHost,
|
||||
} from "../../scripts/check-system-test-prerequisites.ts";
|
||||
import { PROVIDER_SANDBOX_NAMESPACE_ARGUMENTS } from "../../scripts/lib/provider-sandbox-namespaces.ts";
|
||||
|
||||
type SpawnCall = Readonly<{ command: string; args: readonly string[] }>;
|
||||
type SpawnResult = ReturnType<SystemTestHost["spawn"]>;
|
||||
|
||||
const RTM_NEWADDR = "bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted";
|
||||
|
||||
/** A host that has every prerequisite, except what `bwrap` and `files` say. */
|
||||
function fakeHost(
|
||||
bwrap: SpawnResult,
|
||||
files: Readonly<Record<string, string>> = {},
|
||||
): { host: SystemTestHost; calls: SpawnCall[] } {
|
||||
const calls: SpawnCall[] = [];
|
||||
const host: SystemTestHost = {
|
||||
access: async () => undefined,
|
||||
readFile: async (target) => {
|
||||
if (target === "/sys/fs/cgroup/cgroup.controllers") return "cpuset cpu io memory pids\n";
|
||||
const content = files[target];
|
||||
if (content === undefined) throw new Error(`ENOENT: ${target}`);
|
||||
return content;
|
||||
},
|
||||
spawn: (command, args) => {
|
||||
calls.push({ command, args });
|
||||
if (command === "/usr/bin/systemctl") return { status: 0, stderr: "" };
|
||||
if (command === "/usr/bin/bwrap") return bwrap;
|
||||
throw new Error(`unexpected spawn: ${command}`);
|
||||
},
|
||||
};
|
||||
return { host, calls };
|
||||
}
|
||||
|
||||
// 1105/12-01. The check looked only for the bwrap executable, so a host that
|
||||
// refuses unprivileged user namespaces printed PASS and then failed 18
|
||||
// provider tests with bwrap's raw netlink error.
|
||||
describe("system test prerequisites (1105/12-01)", () => {
|
||||
it("passes when bubblewrap creates the provider sandbox's namespaces", async () => {
|
||||
const { host, calls } = fakeHost({ status: 0, stderr: "" });
|
||||
|
||||
expect(await findSystemTestPrerequisiteFailures(host)).toEqual([]);
|
||||
|
||||
const probes = calls.filter(({ command }) => command === "/usr/bin/bwrap");
|
||||
expect(probes).toHaveLength(1);
|
||||
expect(probes[0]?.args).toEqual(NAMESPACE_PROBE_ARGUMENTS);
|
||||
expect(probes[0]?.args.at(-1)).toBe("/bin/true");
|
||||
});
|
||||
|
||||
it("probes with exactly the namespace options the provider sandbox uses", async () => {
|
||||
expect(PROVIDER_SANDBOX_NAMESPACE_ARGUMENTS).toEqual([
|
||||
"--unshare-pid",
|
||||
"--unshare-ipc",
|
||||
"--unshare-uts",
|
||||
"--unshare-net",
|
||||
]);
|
||||
expect(NAMESPACE_PROBE_ARGUMENTS.slice(0, PROVIDER_SANDBOX_NAMESPACE_ARGUMENTS.length)).toEqual(
|
||||
PROVIDER_SANDBOX_NAMESPACE_ARGUMENTS,
|
||||
);
|
||||
// The provider takes the list from the same module instead of its own copy.
|
||||
const provider = await readFile("scripts/run-and-validate-provider.ts", "utf8");
|
||||
expect(provider).toContain("...PROVIDER_SANDBOX_NAMESPACE_ARGUMENTS,");
|
||||
expect(provider).not.toMatch(/"--unshare-/u);
|
||||
});
|
||||
|
||||
it("fails with the namespace restriction, bwrap's stderr and what to do when bwrap cannot set up loopback", async () => {
|
||||
const { host } = fakeHost(
|
||||
{ status: 1, stderr: `${RTM_NEWADDR}\n` },
|
||||
{ "/proc/sys/kernel/apparmor_restrict_unprivileged_userns": "1\n" },
|
||||
);
|
||||
|
||||
const failures = await findSystemTestPrerequisiteFailures(host);
|
||||
|
||||
expect(failures).toHaveLength(1);
|
||||
const failure = failures[0] ?? "";
|
||||
expect(failure).toMatch(/^this host does not allow unprivileged user and network namespaces/u);
|
||||
expect(failure).toContain("--unshare-net");
|
||||
expect(failure).toContain(`bwrap stderr: ${RTM_NEWADDR}`);
|
||||
expect(failure).toContain("kernel.apparmor_restrict_unprivileged_userns = 1");
|
||||
expect(failure).toMatch(/AppArmor profile/u);
|
||||
expect(failure).toMatch(/sysctl kernel\.apparmor_restrict_unprivileged_userns=0/u);
|
||||
expect(failure).toMatch(/another runner/u);
|
||||
expect(formatSystemTestPrerequisiteReport(failures)).toContain(
|
||||
" - this host does not allow unprivileged user and network namespaces",
|
||||
);
|
||||
});
|
||||
|
||||
it("fails the same way when the probe cannot run to the end", async () => {
|
||||
const { host } = fakeHost({ status: null, stderr: "", error: new Error("spawnSync /usr/bin/bwrap ETIMEDOUT") });
|
||||
|
||||
const failures = await findSystemTestPrerequisiteFailures(host);
|
||||
|
||||
expect(failures).toHaveLength(1);
|
||||
expect(failures[0]).toMatch(/^this host does not allow unprivileged user and network namespaces/u);
|
||||
expect(failures[0]).toContain("did not finish: spawnSync /usr/bin/bwrap ETIMEDOUT");
|
||||
});
|
||||
|
||||
it("keeps the executable, cgroup v2 and systemd bus checks, and probes bwrap only when it is there", async () => {
|
||||
const calls: SpawnCall[] = [];
|
||||
const host: SystemTestHost = {
|
||||
access: async (target) => {
|
||||
if (target === "/usr/bin/bwrap") throw new Error(`EACCES: ${target}`);
|
||||
},
|
||||
readFile: async () => "\n",
|
||||
spawn: (command, args) => {
|
||||
calls.push({ command, args });
|
||||
return { status: 1, stderr: "Failed to connect to bus" };
|
||||
},
|
||||
};
|
||||
|
||||
expect(await findSystemTestPrerequisiteFailures(host)).toEqual([
|
||||
"bubblewrap is required at /usr/bin/bwrap",
|
||||
"cgroup v2 controllers are unavailable",
|
||||
"a reachable systemd manager bus is required",
|
||||
]);
|
||||
expect(calls.map(({ command }) => command)).toEqual(["/usr/bin/systemctl"]);
|
||||
});
|
||||
});
|
||||
Reference in New Issue
Block a user