문제
taxonomy는 test:all을 일상 개발 루프라고 적는다. 그런데 test:all은
tests/features 중 참조 샘플만(test:reference-feature) 돌리고,
test:coverage(FE-GATE-005)가 도는 tests/features의 나머지(설치 표면,
feature-module, 예제 기능 2파일), tests/scripts,
tests/scale/browser-soak.contract.test.ts를 빠뜨린다. 로컬에서 초록이고
CI에서 빨강이 될 수 있다.
고른 방법과 버린 대안
- package.json test:all의 test:reference-feature 자리를 tests/features
전체 + tests/scripts + browser-soak 계약 테스트를 한 번에 도는 Vitest
실행으로 바꾼다. 참조 샘플 테스트도 tests/features 안이라 그대로
돈다. 샘플을 지우면 그 폴더만 빠진다.
- tests/unit/test-all-paths.test.ts(새 파일): package script graph로
test:all과 test:coverage의 Vitest 경로를 모아, coverage 쪽 경로가
모두 test:all 경로 안에 있는지 본다. 다시 빠지면 이 테스트가 잡는다.
- 새 package script(test:features)를 만드는 안은 버렸다. 그 이름이
tests/scripts까지 도는 것을 말하지 못하고, test:all만 쓰는 스크립트가
하나 늘 뿐이다.
- taxonomy에 "CI와 같은 집합은 test:coverage"라고만 적는 안은 버렸다.
완료 기준(test:all ⊇ test:coverage의 Vitest 파일)을 못 채운다.
- docs/testing/taxonomy.md의 test:all 설명을 바꾼다.
위험·한계
- 제거 드릴 셋(optional recipe, realtime, browser-file-storage)은
fixture 안에서 test:all만 돈다. 이제 이 파일들도 그 fixture에서
처음 돈다. import를 보면 제거 대상에 기대지 않지만 실행으로는 확인하지
못했다. 드릴 시간이 몇 초씩 는다(1101/10-06과 반대 방향).
검증
- desktop batch에서 확인:
node scripts/run-vitest.ts run tests/unit/test-all-paths.test.ts
corepack pnpm test:all, corepack pnpm check:ci, FE-GATE-020
- RED: 부모 커밋의 package.json에서 "runs every Vitest path
test:coverage runs"가 tests/features·tests/scripts·browser-soak
경로를 빠졌다고 실패한다.
Refs: 0929/10-05
문제
접근성 e2e는 보호 라우트의 목록 조회에 빈 목록을 답한다. 자원 하나를
읽는 상세 라우트(참조 기능의 상세, 생성기 --with-create의 상세)는
일반 답이 없어 실패 화면에서 axe를 돌린다. 그런데
scripts/write-a11y-report.ts는 설치된 라우트 전체를 scope에 넣고
automatedStatus "passed"를 쓴다. 화면 내용은 한 번도 검사하지 않은
라우트가 통과로 보고된다. annotation은 test 결과에만 남는다.
고른 방법과 버린 대안
- scripts/lib/a11y-data-state.ts(새 파일): 라우트 test가 끝날 때
자기 상태를 artifacts/tests/a11y-data-state/<ROUTE_ID>.json에 남긴다.
실패 화면으로만 봤으면 이유를 쓰고, 아니면 지운다. 그래서 라우트마다
마지막 실행이 정한다. 세 엔진이 같은 파일을 쓰므로 임시 파일에 쓰고
rename한다.
- tests/e2e/accessibility.spec.ts: 위 기록을 남긴다(공개 라우트와
데이터 상태로 본 라우트는 지운다).
- a11y.json schemaVersion 2: scope에는 자기 상태로 검사한 라우트만,
notChecked에는 실패 화면으로만 본 라우트와 이유를 넣는다. 둘을
합치면 설치된 라우트 레지스트리와 같아야 한다(schema가 본다).
- 상세 라우트를 실제 데이터 상태로 검사하는 안은 버렸다. 출력
validator에서 유효한 값을 일반적으로 만들 수 없고, 기능마다 견본
응답을 받는 자리를 새로 열어야 한다.
- annotation을 Playwright JSON reporter로 읽는 안은 버렸다. test:a11y
스크립트의 reporter와 산출물 경로를 바꿔야 하고, 경로는 다른 작업
(12-04)이 바꾸는 중이다.
- 매뉴얼(docs/manual/reference/create-feature.md)에 상세 라우트가
notChecked로 적히고 수동 검토가 맡는다고 적는다.
위험·한계
- a11y.json 모양이 바뀐다(schemaVersion 1 → 2, scope 의미, 새 필드).
템플릿 안의 소비자는 ci-artifact-validator 하나이고 같이 바꿨다.
- 템플릿 상태에서도 참조 기능의 상세 라우트가 notChecked로 나온다.
지금까지 실제로 검사하지 않던 것이 드러나는 것이다.
- 기록 디렉터리는 artifacts/tests 아래 고정 경로다. 12-04가 산출물
경로를 실행마다 나누면 이 경로도 따라가야 한다.
- 라우트 test가 돌지 않은 실행에서는 그 라우트의 지난 기록이 남는다.
지난 기록이 "검사 안 함"이면 덜 주장하는 쪽이라 위험하지 않다.
검증
- desktop batch에서 확인:
node scripts/run-vitest.ts run tests/unit/a11y-report.test.ts
corepack pnpm test:a11y (세 엔진) 뒤 artifacts/tests/a11y.json의
notChecked에 REFERENCE_RESOURCE_DETAIL이 있고 scope에 없어야 한다.
- RED: 부모 커밋에는 scripts/lib/a11y-data-state.ts가 없어 새 unit
test 파일 전체가 실패한다.
Refs: 1103/11-01
BREAKING CHANGE: artifacts/tests/a11y.json이 schemaVersion 2가 된다. scope는 실패 화면으로만 본 라우트를 빼고, 그 라우트는 새 notChecked 배열에 { routeId, reason }으로 들어간다. scope를 설치된 라우트 전체로 읽던 도구는 scope와 notChecked를 합쳐 읽는다.
문제
tests/e2e/preload-use.spec.ts는 preload tracker만 증명한다. 안 쓴
preload를 넣는 test는 맨 test에서 tracker를 직접 부르고, strict
fixture를 쓰는 test는 "통과해야 한다" 방향 하나뿐이다. 그래서
strict-browser-test.ts가 tracker 결과를 버려도(11-R3) 커밋된 test는
하나도 실패하지 않았고, WebKit 무시 정규식을 넓혀도 볼 test가 없다.
3번 test는 지연시킬 청크를 못 찾으면 조용히 평범한 방문이 된다.
고른 방법과 버린 대안
- strict fixture의 마지막 판정을 browserFailureVerdict fixture로
뺀다. 기본값은 지금과 같다(allowedBrowserFailure로 거르고 빈 목록
단언). page fixture는 기록을 그 판정에 넘긴다.
- spec은 그 판정을 "기록을 받아 두는" 판정으로 바꾼 recordedTest를
둔다. page fixture가 판정에 의존하므로 판정의 teardown은 page
teardown 뒤에 돈다. 거기서 fixture가 넘긴 줄이 fixtureReports와 정확히
같은지 본다.
- 안 쓴 modulepreload 하나 → `preloadunused:/assets/<청크>.js` 한 줄.
- WebKit 문구 그대로(무시), Chromium 문구, WebKit 문구 + 뒤 글자,
같은 문구의 console.error, 다른 warning → 뒤의 네 줄만, 순서대로.
- 기본 판정이 실제로 test를 실패시키는지는 strictTest.fail()로 console
error 한 줄을 내는 test 하나가 본다. 기록이 맞다는 것은 위 두 test가
따로 증명하므로, 이 test가 엉뚱한 이유로 실패해도 놓치는 것이 적다.
- 3번 test는 지연시킬 청크가 없으면 이유를 적고 실패한다.
- 모든 probe를 test.fail()로만 고정하는 안은 버렸다. 어떤 이유로든
실패하면 통과해서 fixture가 무엇을 기록했는지 보지 못한다.
- 커밋한 문서: docs/testing/frontend-platform-testing-strategy.md에
증명 위치와 판정을 바꾸는 곳이 그 spec 하나라는 것을 적는다.
위험·한계
- 모든 browser spec이 쓰는 fixture의 구조가 바뀐다. 판정 내용은 같다.
- 다른 spec도 browserFailureVerdict를 바꿔 strict 검사를 끌 수 있다.
allowedBrowserFailure를 /.*/로 주는 것과 같은 수준의 노출이고 막는
검사는 더하지 않았다.
- 샘플을 지운 제품에서 기능 실행부 모양이 바뀌면 3번 test가 실패한다.
그때는 test를 다른 청크로 옮기거나 이유를 적고 지워야 한다.
검증
- desktop batch에서 확인:
corepack pnpm exec playwright test tests/e2e/preload-use.spec.ts (세 엔진)
- 테스트 장치만 바꾼 커밋이라 RED는 변이로 본다.
- 11-R3(strict fixture가 check 결과를 버림): "records a modulepreload
the page never runs"가 세 엔진에서 실패해야 한다.
- WEBKIT_UNUSED_PRELOAD_GUESS를 /.*/로: "ignores WebKit's
unused-preload guess word for word and nothing else"가 실패해야 한다.
- browserFailureVerdict 기본값의 expect 제거: "fails a test whose page
writes a console error"가 "expected to fail" 위반으로 실패해야 한다.
Refs: 1105/11-01
문제
feature-and-app-roots-do-not-reach-adapters는 기능 루트 파일
(src/features/*.ts, src/features/<id>/*.ts), src/contexts, src/apps만 본다.
그래프는 간선 하나씩 검사하므로, 기능 안에 계층이 아닌 폴더(support/ 등)를
만들어 그 파일이 http adapter 배럴을 import하고 기능 presentation이 그 파일을
import하면 presentation이 구체 adapter에 닿는다. 1105 리뷰 12-R3 변이에서
check:architecture와 ESLint가 둘 다 통과했다.
고른 방법
- 규칙의 from을 "src/features 아래 모든 파일, 기능의 adapters/ 폴더 밖"으로
바꾼다(`^src/(features/|contexts/|apps/)`, pathNot
`^src/features/([^/]+/adapters/|feature-adapter-contribution\.ts$)`). 규칙
주석이 이미 "기능 안에서는 adapters/ 폴더만 src/adapters에 닿는다"고 적고
있었고, 그 문장을 경로로 옮긴 것이다. 파일 단위 예외는 기존 하나
(feature-adapter-contribution.ts, type only) 그대로고 새로 더하지 않았다.
- domain·application·presentation은 자기 규칙이 이미 src/adapters를 막는다.
이제 그 파일들이 src/adapters를 import하면 이 규칙도 같이 걸린다(위반 두 줄).
더 엄격해질 뿐 허용이 바뀌지는 않는다.
- 지금 src/features에서 src/adapters를 import하는 곳은 reference-feature의
adapters/ 두 파일과 feature-adapter-contribution.ts뿐이라 새 위반은 없다.
create:feature가 만드는 adapter import도 adapters/ 안이다.
- 그래프 회귀 fixture에 support/ 재수출(거절), 그것을 읽는 presentation,
기능 adapters/ import(허용)를 더하고 check:architecture에 두 단언을 더했다.
규칙 경로를 check:architecture와 같은 방식으로 읽는 vitest 테스트를 더했다.
- layers.md 표와 매뉴얼 01의 설명을 고쳤다.
- 버린 대안: 계층 밖 폴더 자체를 금지(폴더 이름 목록 검사). 제품이 contracts/
같은 다른 이름을 쓰면 계속 목록을 고쳐야 한다. 규칙마다 support/ 패턴 추가:
다음 폴더 이름에서 같은 틈이 난다.
위험·한계
- 다운스트림이 기능 안 adapters/ 밖에서 src/adapters를 import하고 있었다면 이제
check:architecture가 실패한다. 그 파일을 adapters/로 옮기면 된다.
- ESLint는 여전히 간선 하나만 보므로 이 경로를 잡지 않는다. 그래프가 잡는다.
검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
tests/architecture/feature-adapter-reach.test.ts, corepack pnpm
check:architecture(그래프 fixture 단언 2개 추가 PASS, 저장소 위반 0 기대).
- RED 기대: "rejects a concrete adapter import from a feature folder that is not
a layer", "leaves a feature's adapters folder and the type-only contribution
file to reach adapters"(support/adapters/ 경로 단언).
Refs: 0929/12-03
문제
docs/testing/frontend-platform-testing-strategy.md 11.2절이 "401 뒤 인증 복구
흐름은 tests/integration/auth-recovery.test.ts가 다룬다"고 적는다. 그 파일은
V2 클라이언트를 지울 때(048f490a) 같이 지웠고, V3 실행기에는 401 뒤 복구·재전송
흐름이 없다. 문서를 따라가면 없는 테스트와 없는 동작을 찾게 된다. 이 문서는
docs/README.md 1절 밖(목표 설계)이라 verify:documentation이 보지 않는다.
고른 방법
- 문장을 지금 동작으로 고친다: V3는 401을 UNAUTHENTICATED로 끝내고 다시 보내지
않는다(http-execution-v3.ts), 판정은 tests/unit/http-execution-v3.test.ts가
검사한다. 지운 파일 이름은 backtick 경로로 남기지 않는다.
- 1103/12-05의 남은 둘(지운 심볼 이름 검사, 1절 밖 문서 검사)은 이 커밋에서
하지 않는다. 심볼 검사는 지난 리뷰가 버린 대안이다(지운 이름 목록을 따로
관리해야 하고 오탐이 많다). 1절 밖 문서는 목표 설계라 일부러 없는 경로를
적는다. 2절 문서의 backtick repo 경로 중 없는 것이 15개쯤이고 대부분
계획 경로다(src/domain, src/generated, V2 파일 등). 검사로 넓히려면 문서별
예외 방식부터 정해야 한다(결정 대기).
위험·한계
- 같은 종류의 옛 경로는 1절 밖 다른 문서에 남아 있다(2026-07-30 결정 정본의
V2 http 파일 등). 이 커밋은 리뷰가 든 한 곳만 고친다.
검증
- 문서만 바꿨다. 이 문서를 보는 자동 검사는 없다(1절 밖). desktop batch에서
corepack pnpm verify:documentation이 그대로 통과하는지만 본다.
Refs: 1103/12-05
문제
제품 overlay(config/ci/product-gates.json)의 mergeGates는 product_merge_gate
job으로 렌더링되는데, 다른 job이 이 job을 기다리지 않는다. release_gate는
merge_gate만 기다린다. 그래서 제품 검사(예: 짝 백엔드 계약 검사)가 실패해도
같은 run의 release·immutable_build·promotion·deployment는 그대로 돈다. 브랜치
필수 검사는 PR merge만 막는다. job 그래프는 계약이 고정해서(ci-gates.ts의
expectedJobGraph) 제품이 연결을 더할 방법도 없다.
고른 방법
- overlay에 게이트가 있으면 release_gate의 needs에 product_merge_gate를 더해
렌더링한다(`needs: [merge_gate, product_merge_gate]`). release_gate는 release
단계의 첫 job이고 뒤의 job은 모두 그것을 거쳐 기다린다. 템플릿 게이트가
release를 막는 방식과 같다.
- 연결은 렌더링에서만 더한다. gates.json과 계약 그래프 검사는 그대로라 템플릿
job 그래프와 check:ci의 엄격함은 바뀌지 않는다. 게이트가 없으면 workflow
바이트가 같다(.gitea/workflows/quality-gates.yml 변경 없음).
- workflowGateExecutionFailures(check:ci가 부름)가 제품 게이트가 있는데
release_gate가 product_merge_gate를 기다리지 않는 workflow를 거절한다.
"실행된다"와 "막는다"를 따로 본다.
- 문서(ci-quality-gates.md, README)에 release 단계가 제품 job을 기다린다고
적었다.
- 버린 대안: (a) 문서에만 "막지 않는다"고 적기. 제품이 막을 방법이 계속 없다.
(c) 게이트마다 blocksRelease 칸. 선택권은 주지만 칸이 늘고, 불안정한 제품
검사가 생기기 전에는 필요가 없다. 계약 그래프 검사에 overlay 예외를 넣는 것:
템플릿 계약이 제품 overlay를 알아야 한다.
위험·한계
- 불안정한 제품 게이트는 이제 release도 멈춘다. 그때는 (c)로 간다.
- Gitea가 needs와 기본 success() 조건을 GitHub Actions처럼 처리한다고 본다.
실제 runner에서는 확인하지 못했다(Actions 꺼짐).
- 제품 게이트를 이미 쓰는 다운스트림은 generate:ci-workflow를 다시 돌려야
check:ci를 통과한다(생성 YAML의 release_gate needs 한 줄이 바뀐다).
검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
tests/unit/product-ci-overlay.test.ts tests/unit/ci-workflow-generation.test.ts,
corepack pnpm check:ci.
- RED 기대: "holds the release stage until the product merge gates pass",
"runs product merge gates in a job of their own, apart from the template gates".
Refs: 1105/13-02
문제
verify:documentation(FE-GATE-017)은 짝 백엔드 경로·링크를 옆 checkout의
작업 트리에서 찾았다. 그래서 같은 커밋이 놓인 곳마다 결과가 달랐다. desktop은
옆 checkout이 ef947e5(9월)에 미커밋 변경까지 있어 문서와 무관하게 rc=1,
짝이 없는 worktree는 PASS(17개 미확인)였다. 옆 checkout이 pin보다 새로우면
pin에 없는 파일을 적어도 통과하고, 저장소 이름을 틀린 `../` 링크는
"확인 못 함"으로 통과했다. config/contracts/backend-contract-pin.json은 읽지
않았다.
고른 방법
- 짝 저장소 목록과 기준 커밋을 pin 파일에서 읽는다. pin은 문서와 같이
작업 디렉터리에서 읽는다(문서가 어느 커밋을 설명하는지 적은 파일이라서).
- 옆 checkout에 pin 커밋이 있으면 `git ls-tree -r -t <pin>`으로 그 커밋의
트리(파일과 폴더)를 한 번 읽어 찾는다. 작업 트리와 HEAD는 보지 않는다.
hook이 넘긴 GIT_DIR 같은 GIT_* 변수는 지우고 git을 부른다.
- checkout이 없거나, pin 커밋이 없거나, git이 읽지 못하면 실패 대신
unverifiedLinks로 남기고, 출력에 이유(짝 HEAD, pin 앞 12자)를 적는다.
- `../`로 나가는 링크의 첫 폴더가 pin에 없는 저장소면 missingPaths로 실패한다.
실패하면 "pin 커밋에서 찾았다"는 줄을 stderr에 하나 더 적는다.
- 버린 대안: 짝 HEAD가 pin과 다르면 전부 unverified(리뷰 (c)). 더 단순하지만
pin 뒤로 앞서 있는 흔한 checkout에서 아무것도 확인하지 못한다. 경로마다
`git cat-file -e`: 같은 결과지만 참조 수만큼 프로세스를 띄운다.
위험·한계
- pin 커밋을 fetch하지 않은 checkout(desktop 지금 상태)에서는 짝 참조가 전부
"not verified"다. 실패하지 않는 대신 확인도 하지 않는다.
- 짝 저장소는 여전히 하나(pin 파일의 backend)다. 둘째 짝이 생기면 pin 모양부터
바꿔야 한다.
- pin 파일이 없으면 짝 저장소가 없는 것으로 보고 `../` 링크를 전부 실패로 센다.
- 보고서 schema는 그대로다(unverifiedLinks 주석만 고침).
검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
tests/unit/documentation-readiness.test.ts, 그리고 corepack pnpm
verify:documentation(옆 짝이 ef947e5인 desktop에서 PASS_SCOPED +
not verified 기대).
- RED 기대: "looks a reference up in the pinned commit, not in a later HEAD or
the working tree", "reports the references as not verified when the
checkout does not have the pinned commit", "fails a link out of the
repository into a repository that is not paired".
Refs: 1105/12-02
문제: 1103/16-05 수정으로 commandMutationIdentity가 생겼지만
BoundMutation.operationId는 여전히 string이다. 정책에 operation ID를
문자열로 직접 적으면 오타가 check:types와 check:registries를 통과하고,
저장할 때마다 실행기가 보내기 전에 MISSING_IDEMPOTENCY_KEY 위반으로
거부한다. 매뉴얼 01은 이것을 "못 잡음"으로 적고 있었다.
고른 방법: BoundMutation.operationId를 brand 타입 MutationOperationId로
바꾼다. 이 값을 돌려주는 것은 commandMutationIdentity뿐이라, 문자열을
직접 적으면 check:types가 실패한다. 런타임 값은 descriptor의 문자열
그대로이고 실행기·intent factory는 바뀌지 않는다. 참조 기능과 쓰기 slice
생성기는 이미 commandMutationIdentity를 spread하므로 고칠 것이 없다.
템플릿 테스트의 손글씨 ID 20곳은 tests/helpers/mutation-operation-id.ts
(commandMutationIdentity를 거치는 test helper)나 그 파일의 descriptor로
바꿨다. 매뉴얼 01·patterns 표·state 설계 예시를 맞췄다.
버린 대안: (1) 위반 이름을 INTENT_OPERATION_MISMATCH로 나누는 것. 실행
때만 드러나는 것은 같고, 공개 위반 어휘에 값이 하나 늘어 다운스트림
분기가 바뀐다. (2) 설치된 operation ID의 union 타입. 기능마다 늦게
적재되는 계약 전체를 타입으로 모을 곳이 없다.
위험·한계: 공개 타입(src/contracts/server-state.ts)이 좁아진다. 정책에
operation ID를 문자열로 적은 다운스트림 코드는 동기화 뒤 check:types가
실패한다. commandMutationIdentity에 descriptor 상수 대신 손으로 만든
객체를 넘기면 여전히 오타가 통과한다(매뉴얼 "못 잡음"). HTTP가 아닌
뮤테이션은 descriptor 모양 객체를 넘겨야 한다. 이 repo에는 그런 소비자가
없다.
검증: desktop batch에서 확인.
corepack pnpm check:types:test
tests/unit/command-mutation-identity.test.ts의 @ts-expect-error가 부모
커밋에서는 쓰이지 않아(TS2578) 실패하고 이 커밋에서 통과한다.
node scripts/run-vitest.ts run tests/unit/command-mutation-identity.test.ts tests/component/application-mutation-admission.test.tsx tests/component/application-mutation-scope-fence.test.tsx tests/component/application-query.test.tsx tests/component/form-foundation.test.tsx
BREAKING CHANGE: BoundMutation.operationId는 string이 아니라
MutationOperationId다. 뮤테이션 정책의 `operationId: "<ID>"`와
`requiresIdempotencyKey`를 `...commandMutationIdentity(<OPERATION>_CONTRACT)`
로 바꾼다(src/contracts/server-state.ts). commandMutationIdentity의 반환
타입도 operationId가 MutationOperationId다.
Refs: 1103/16-05
문제: 짝 백엔드 Redis session 모드를 쿠키 recipe와 매뉴얼 04 4.3대로
이으면 서버 401이 세션에 닿지 않는다. 1103/09-01 수정 뒤 조립 루트는
제품 provider 프로필의 401을 제품의 선택 hook `onCredentialRejected`에만
알린다. 쿠키 모드의 operation은 모두 제품 프로필(SESSION_COOKIE_*)인데
매뉴얼 예시는 그 hook을 잇지 않았고, recipe와 매뉴얼은 "서버 401 →
unauthenticated"라고 적었다. 이으려 해도 ProductCompositionContext에
세션에 알릴 길이 없었다. 리뷰 09-cookie401에서 세션 만료 뒤에도 상태가
authenticated, 이전 scope가 current로 남았다.
고른 방법: 두 가지를 더했다.
- ProductCompositionContext.notifySessionUnauthenticated(): 템플릿 세션의
자기 401과 같은 판정(authSession.onUnauthenticated)을 제품이 부를 수
있게 한다(리뷰 안 C).
- recipe의 createSessionCookieRejectionHandler(context): SESSION_COOKIE_*
프로필의 401만 세션에 넘긴다. 다른 제품 프로필의 401은 넘기지 않으므로
1103/09-01의 완료 기준(세션과 무관한 provider의 401은 로그아웃시키지
않는다)은 그대로다.
매뉴얼 04 4.3 예시에 `onCredentialRejected` 한 줄을 넣고, recipe 주석,
매뉴얼 04 흐름도, 매뉴얼 02 5절과 7절 업로드 예시(BACKEND_SESSION 쿠키
세션)를 맞췄다. 버린 대안: recipe가 owner와 provider를 한 번에 만드는
함수(안 B). owner는 composeProductSessionOwner, provider는 composeProduct
에서 따로 만들어져 모듈 변수가 필요하다. provider 선언에 "세션 자격
증명" 표시를 두는 안(D)은 계약 칸이 늘고 판정이 선언과 hook 둘로 갈린다.
위험·한계: 제품이 이 한 줄을 빼면 여전히 세션 만료를 모른다. 이것을
막는 검사는 없다(매뉴얼과 recipe 주석이 적는다). 이미 recipe를 복사한
다운스트림은 handler를 복사본에 옮기고 composeProduct에 한 줄을 더해야
한다. ProductCompositionContext에 칸이 하나 늘었다. 이 context는 템플릿만
만들므로 제품 코드는 깨지지 않는다. 실제 Redis 백엔드에는 붙이지
않았다(1103/09-03 남은 부분).
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/recipes/session-owners-runtime.test.ts tests/recipes/cookie-session-owner.test.ts
조립 루트를 지나는 테스트가 매뉴얼 4.3 연결로 쿠키 읽기·쓰기 401 뒤
세션 unauthenticated, 이전 scope not current를 본다.
Refs: 1105/09-02
문제: 2026-11-03 02-02 수정 뒤 저장된 본문을 읽지 못하면(`UNAVAILABLE`·
`NOT_READABLE`) 손상이 아니라 "모름"이다. stage 재사용 경로는 "모름"이면
실패를 돌려주고 다시 받지 않는다. 그래서 다시 쓰기 전까지 계속 읽히지 않는
entry(blob 손실 등)는 다시 stage해도 고쳐지지 않는다(리뷰 실험 E-1).
- 새 후보: activate가 `RETRY`를 안내하는데 다시 해도 같다. cleanup으로
후보를 지운 뒤에야 풀린다.
- rollback 대상: cleanup도 지우지 않아 되돌릴 길이 없다.
- 서비스 중 release: 그 asset 조회가 계속 `UNAVAILABLE`이다.
수정 전 판정에서는 같은 상태가 다시 stage 한 번으로 풀렸다.
고른 방법(리뷰 대안 (나)):
- 판정에 `UNREADABLE`(entry는 있는데 본문 읽기가 실패)을 따로 둔다.
`UNKNOWN`은 중단(`ABORTED`)과 `cache.match` 자체의 실패만 뜻한다.
- stage 재사용 경로는 `REPAIRABLE`처럼 `UNREADABLE`도 모든 asset을 다시
받아 같은 cache에 덮어쓴다. 덮어쓰는 것은 digest로 검증한 같은
바이트이고 cache를 지우지 않으므로 서비스 중인 release를 해치지 않는다
(STO-RR-04가 막는 것은 삭제다).
- activation은 지금처럼 본문 읽기 실패를 손상으로 보고하지 않고 code를
그대로 둔다. recovery만 `REHYDRATE`(같은 manifest로 다시 stage)로 바꾼다.
- 조회는 그대로 `UNAVAILABLE`/`RETRY`다.
- `cache.match`가 던지는 경우는 리뷰가 제안한 "중단 제외 UNKNOWN 전부"에서
뺐다. Cache Storage 자체가 응답하지 않을 때 모든 asset을 다시 받는 것은
고치는 것이 없고, 2026-11-01 02-03 테스트가 그 경우의 실패 보고를 고정한다.
버린 대안:
- (가) 문서에 "cleanup 뒤 다시 stage"만 적기: rollback 대상은 못 고친다.
- (다) 실패한 entry만 다시 받기: 비용은 가장 작지만 stage 경로를 entry
단위로 나눠야 한다.
위험·한계:
- 일시적인 본문 읽기 오류에도 다시 stage하면 모든 asset을 다시 받는다
(수정 전과 같은 비용).
- 실제 브라우저에서 본문 읽기 실패가 지속되는지, 어떤 오류 이름으로
오는지는 확인하지 못했다. 테스트는 메모리 fake에 오류를 주입한다.
- service-worker-pwa 번들 여유가 342 B다(FE-GATE-012). 늘어난 코드는
분기 둘이다.
검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/public-response-cache-repair.test.ts
tests/unit/public-response-cache.test.ts tests/unit/public-response-cache-codec.test.ts
tests/recipes/browser-file-storage-contracts.test.ts
- corepack pnpm check:optional-recipes (번들 예산)
Refs: 1105/02-02
문제: SW를 켜는 선택은 제품 소유 `product-capabilities.ts`로 옮겼다
(1103/09-05 일부). 그런데 저장하지 않은 편집이 있는 탭의 활성화 거절
(`blockers`)과 page controller 관측(`observe`)은 템플릿 소유
`src/bootstrap/create-runtime-composition.ts`를 고쳐야 이어진다(매뉴얼 03
"SW 켜기", 레시피 "Service Worker를 켤 때 확인할 것" 2·3). 그 파일을 고친
제품은 템플릿 동기화마다 충돌한다.
고른 방법: 기존 제품 확장 지점에 선택 칸 하나를 더한다.
`ProductComposition.serviceWorker?: { blockers?, observe? }`
(`product-composition-contract.ts`). `createRuntimeAdapters`가 `composeProduct`
결과의 이 칸을 bundle에 `productServiceWorker`로 싣고, 템플릿 조립
(`create-runtime-composition.ts`)이 telemetry와 같은 방식으로 받아
`createOptionalRuntimeHost`에 넘긴다. blockers 목록은 한 번 복사한다. 던지는
blocker는 page controller가 이미 막는 쪽으로 본다. page controller는
`observe`의 throw를 잡지 않으므로, 제품 sink가 던져도 worker 흐름이 바뀌지
않게 조립에서 감쌌다. 매뉴얼 03과 레시피 2·3을 새 자리로 고쳤다.
버린 대안:
- `product-composition.ts`에 새 export(`composeProductServiceWorker`)를 요구.
이미 그 파일을 가진 다운스트림이 동기화하면 import가 깨진다. 선택 칸은
기존 `composeProduct`를 그대로 둔다.
- `composeProduct`를 조립에서 한 번 더 부르기. capability와 credential이 두
벌 생긴다.
위험·한계: 일부만 닫는다. 남은 것:
- 활성화 화면(`onUpdateWaiting`·`requestActivation()`)과 reload 안내를 이을
제품 소유 자리가 없다(레시피 4·5, 0925/06-05).
- realtime·Web Worker·오프라인 명령은 여전히 조립이 거절한다
(`optional-runtime-host.ts`, 그 런타임이 템플릿에 없다).
`product-composition.ts`(제품 소유, 출하 상태 빈 값)는 고치지 않았다. 칸이
선택이라 기존 제품 파일과 1105/09-01의 타입 검사 탐침 내용이 그대로
통과한다.
검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/component/runtime-composition-service-worker-product-wiring.test.ts tests/component/runtime-composition-service-worker-telemetry.test.ts
- RED: "passes the product's blockers and observer to the page controller"가
옛 조립에서 observe 기록이 비어 실패한다.
- 함께: check:types, lint, check:architecture, verify:documentation
Refs: 1103/09-05
문제: 짝 백엔드 답 표 JSON(backend-idempotency-answers.json)이 pin한
백엔드 http-contract.md와 같은지 아무 검사도 보지 않는다.
backend-contract-pin.test.ts는 pin과 답 표 두 파일만 읽고, drift
스크립트는 pin과 HEAD 사이에 문서 글자가 바뀌었는지만 본다. 그래서
답 표 status 오타나 옮기지 않은 행(§4 RATE_LIMIT_*)은 어디서도 걸리지
않는다. drift 스크립트는 옆 checkout이 없으면 "skipped"로 rc=0이고
(worktree에서 늘 그렇다), 매뉴얼에는 스크립트가 없다.
고른 방법: 게이트가 백엔드 checkout 없이 볼 수 있게, 백엔드 §2·§4 표의
`|` 줄을 pin 커밋 그대로 config/contracts/backend-http-contract-excerpt.json
에 옮겼다. 읽는 함수는 scripts/lib/backend-contract-excerpt.ts 하나다.
- test:unit(backend-contract-pin.test.ts): 답 표의 행마다 사본의 같은 절에
같은 code·status 행이 있는지, 사본의 행마다 답 표에 있거나 pin의
`notCopied`에 이유와 함께 있는지 본다. `notCopied`에는 RATE_LIMIT_* 둘을
적었다(리뷰가 지적한 sectionsCompared §4의 실제 범위).
- check:backend-contract-drift(게이트 밖): pin 커밋의 문서에서 같은 표를
읽어 사본과 글자 단위로 비교하고, 답 표도 그 표와 비교하고, pin 뒤
HEAD에서 바뀐 사본 표 행을 찍는다. checkout이 없거나 pin 커밋·문서가
없으면 rc=2("not compared")로 끝난다. 기본 경로는 main checkout 옆이라
linked worktree에서도 같은 백엔드를 찾는다. `--write-excerpt`는 pin을
올릴 때 사본을 pin 커밋에서 다시 옮긴다.
- 매뉴얼 01 Envelope 단계와 계약 문서 4.1에 언제 무엇을 돌리는지 적었다.
버린 대안: 백엔드 문서의 digest만 pin에 두는 것. 게이트는 digest로 답
표를 확인할 수 없다. 계약 패키지(리뷰 안 D)는 배포 경로가 아직 없다.
위험·한계: 사본과 백엔드 문서의 일치는 여전히 백엔드 checkout이 있을
때만 drift 스크립트가 본다. 게이트는 답 표와 사본의 일치만 본다. 사본을
손으로 같이 고치면 게이트는 통과한다(drift 스크립트가 잡는다). 답 표의
refusedBeforeWrite·sameKeyResend는 백엔드 문장(클라이언트 행동)을 사람이
읽은 값이라 기계로 대조하지 않는다. 그 문장이 바뀌면 사본 diff와 drift
출력에 보인다. 백엔드 표 형식(머리글 `error.code`·`코드`·`status`)이
바뀌면 파서도 고친다. pin의 comparedOn을 사본을 옮긴 날로 올렸다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/backend-contract-pin.test.ts tests/unit/backend-contract-drift.test.ts
drift 테스트는 가짜 백엔드 git repo로 D6g(pin 뒤 status 변경), 답 표
status 오타, 사본 오타, 옮기지도 적지도 않은 행, checkout 없음,
--write-excerpt를 돈다.
Refs: 1105/07-01
문제: 1103/02-01이 제품 closer를 scope reset에 넣었다. template
participant 하나가 제품 closer를 차례로 부르고, 하나라도 던지면 이유 없는
Error를 던진다. scope runtime은 그 실패를 `failed = true`로만 받아 scope를
`FAILED`에 둔다. 그동안 모든 서버 요청이 `SCOPE_FENCED`로 막히는데 진단
기록은 0건이다(리뷰 실험 E-3). 계약의 `ProductScopeParticipant.label`을
읽는 코드도 없다. 개발자는 "로그아웃 뒤 앱이 요청을 안 보낸다"만 보고 원인
closer를 찾으려면 closer를 하나씩 지워 봐야 한다.
고른 방법(리뷰 대안 (다)):
- scope runtime이 reset의 실패 단계마다 `cache.operation.failed`를 하나
남긴다. `operation: "SCOPE_RESET"`, `reason`은 `PARTICIPANT_FAILED`·
`CACHE_RESET_FAILED`·`GENERATION_ACTIVATION_FAILED`(+ 목록 함수가 던질
때 `PARTICIPANTS_UNREADABLE`), `error_kind`, participant 실패면
`scope_participant: <label>`. template participant 실패도 같은 길로
남는다.
- 진단 계약에 `scope_participant` 키를 더한다(cardinality `topology`,
값 정책 `isScopeParticipantLabel` = 소문자 kebab-case 48자 이하). label은
제품 코드가 고른 문자열이라 projection이 받는 닫힌 토큰으로 제한했다.
- 제품 closer를 wrapper 하나로 감싸지 않고 각자 order 10 participant로
넘긴다. 그래서 `participants`가 reset마다 읽는 함수도 받는다
(`ServerStateScopeDependencies`, 배열은 그대로 받는다). 순서와 "하나가
실패해도 나머지를 부른다"는 그대로다.
- 조립은 형식에 맞지 않는 제품 label을 `TypeError`로 거절한다. 부팅에서
바로 드러나야 진단에서 label이 빠지는 일이 없다.
버린 대안:
- (가) 문서에 "closer는 던지지 않게 쓴다"만 적기: 결함이 그대로다.
- (나) wrapper만 제품 label을 기록: template participant 실패는 계속
조용하고, 한 실패가 wrapper와 runtime에서 두 번 기록된다.
- label을 `operation`이나 `reason` 값에 섞기: 계약 변경은 없지만 그 키의
뜻이 흐려진다.
위험·한계:
- 진단 계약(`src/contracts/diagnostics.ts`)에 키 하나, 함수 하나가 더해진다.
더하기만 해서 호환은 깨지지 않는다. CHANGELOG [계약] 행이 필요하다.
- 제품 label 형식이 좁아졌다. `Browser Files` 같은 label을 쓰던 제품은
부팅에서 `TypeError`가 난다. 저장소 안의 label(`browser-files`, 테스트의
label)은 모두 맞는다.
- 화면이 `FAILED`를 어떻게 보이는지는 바꾸지 않았다(영역 08·09).
검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/server-state-scope-runtime.test.ts
tests/unit/runtime-adapters-product-scope-participants.test.ts
tests/unit/observability-cardinality.test.ts tests/unit/diagnostics.test.ts
- corepack pnpm check:diagnostics
- node scripts/run-vitest.ts run tests/recipes/browser-file-session-capability.test.ts
Refs: 1105/02-01
문제: ci:gate는 명령 출력을 artifacts/quality/gates/FE-GATE-<NNN>.txt에만
쓰고 콘솔에는 PASS/FAIL 한 줄만 남긴다(scripts/run-ci-gate.ts). release
단계 job immutable_build는 후보 tar만, 그것도 성공했을 때만 올린다. 그래서
실제 run에서 FE-GATE-015·027이 왜 실패했는지와 FE-GATE-027이 쓰는
artifacts/security/dependency-advisories.json(1103/13-03의 신호)이 runner
작업 디렉터리와 함께 사라진다. 다른 gate job은 artifacts/를 if: always()로
올린다.
고른 방법:
- config/ci/gates.json의 immutable_build 마지막에 upload 단계를 더한다.
transfer ID는 immutable-gate-evidence, 이름은
immutable-gate-evidence-<run>-<attempt>, always: true. 대상은
FE-GATE-015·027의 log와 evidence 산출물(gate 순서)과 advisory 기록 7개다.
FE-GATE-015의 verification.json 등은 후보가 만들어지지 않으면 후보 안에도
없으므로 같이 올린다.
- 계약(scripts/contracts/ci-gates.ts)이 이 단계를 고정한다. immutable_build의
단계 목록에 upload 하나가 늘고, 이 upload가 always이고 마지막 단계이며
경로가 "job이 도는 gate의 log·evidence 경로 + advisory 기록"과 같아야
한다. 경로는 계약의 artifact 등록에서 계산하므로 log 경로가 바뀌면 함께
따라온다. advisory 기록은 gate evidence가 아니라(막지 않는 신호) 경로를
scripts/lib/dependency-advisories.ts의 상수로 옮기고 scan 스크립트도 그
상수를 쓴다.
- 후보 archive의 member set, 후보 upload(always 없음), 하위 job의 download는
그대로다. 생성 workflow를 generator 출력과 같게 손으로 고쳤다.
버린 대안:
- immutable_build도 artifacts/ 전체를 올림: 다른 job과 같지만 후보 증거가
두 이름으로 나가 어느 것이 승격 대상인지 흐려진다. 필요한 파일만 고정했다.
- ci:gate가 실패한 명령의 마지막 N줄을 콘솔에 씀(리뷰 대안 c, d의 콘솔
한 줄 포함): 모든 job에 걸리고 provider 출력의 비밀 노출과 로그 상한을
다시 따져야 한다. 담당 지시 범위(업로드) 밖이라 이번에 하지 않았다.
위험·한계:
- checkout·install 단계에서 실패하면 올릴 파일이 없어 이 단계도
if-no-files-found: error로 실패한다. job은 이미 실패한 뒤라 결과는 같다.
merge·release job의 upload도 같은 동작이다.
- 실제 Gitea runner에서 stage=release를 돌려 산출물이 남는지는 확인하지
못했다(runner 없음). 확인한 것은 계약·생성 workflow까지다.
- 콘솔에는 여전히 한 줄만 나온다. 사람이 산출물을 열어야 이유를 본다.
검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/ci-workflow-generation.test.ts
- corepack pnpm check:ci, check:types, lint, verify:documentation
Refs: 1105/13-01, 1103/13-03
문제: readFailureEnvelope는 실패 Envelope의 meta.traceId를 함께 돌려주고,
V3 실행기는 그 값을 AppFailure.traceId로 싣는다(1103/03-06). Fileserver
client는 envelope.value만 넘겨 traceId를 버린다. 지원 담당이 업로드 실패를
서버 로그의 요청과 잇지 못한다. 같은 백엔드의 다른 쓰기 실패는 이을 수 있다.
고른 방법: envelopeFailure가 읽은 Envelope 전체를 받아 traceId가 있으면
createFailure의 traceId로 싣는다. V3와 같은 규칙이다. 없으면 키를 두지
않는다. 매뉴얼 7절 결과 읽기에 한 줄 적었다.
위험·한계: Envelope 실패에만 싣는다. 성공 Envelope을 읽지 못한 실패
(SCHEMA_MISMATCH 등, 202 REJECTED 포함)는 readSuccessEnvelope가 meta를
돌려주지 않아 traceId가 없다. V3도 같다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts
RED(이 커밋의 테스트 + 부모 src): Envelope failures 표 17행이 traceId
"trace-1"이 없어 모두 실패한다.
Refs: 1105/01-03
문제: 확장자별 MIME probe(1103/06-03)는 install 조건 일부만 옮겼다.
1. install fetch는 `redirect: "error"`라 redirect가 하나라도 있으면
실패한다. probe는 `redirect: "follow"`로 받고 최종 status와 MIME만
본다. 같은 origin 안 redirect 뒤 200을 주는 호스트가 PASS다(리뷰
06-R1). FE-GATE-019가 PASS인데 워커 install은 매번 실패한다.
2. 워커 없는 빌드에서도 돈다. 주석과 문서는 이유를 워커로만 적는다.
3. live 분기의 호출 줄(`verify-hosting-headers.ts`)을 지키는 테스트가
없다. live 모드는 루프백·http를 거절해 저장소 테스트가 들어갈 수
없다. 호출을 지우는 변이가 44건 통과로 살아남았다(06-R2).
고른 방법:
1. 자산 probe 기본 fetcher를 `redirect: "manual"`로 바꾸고,
`response.redirected`이거나 `opaqueredirect`이면 관측 "redirected",
이유 "install fetch가 redirect를 거절"로 FAIL이다. 3xx는 지금처럼
`HTTP 3xx`로 FAIL이다. fetcher가 redirect를 따라가도 `redirected`로
잡으므로 fetcher 방식과 무관하다.
2. 동작은 그대로 두고 의도를 주석과 운영 문서에 적었다. 워커가 없어도
`nosniff` 아래 script·style은 MIME이 틀리면 페이지가 깨지고, 나중에
워커를 켜는 릴리스가 호스팅을 다시 확인하지 않아도 된다. 글꼴·이미지는
페이지에 피해가 없는데 FAIL한다는 것도 적었다. 워커 없는 빌드에서
script·style만 보도록 좁히는 것은 검사를 약하게 하는 정책 결정이라
하지 않았다(결정 대기, 템플릿 소유자).
3. live 분기 전체를 `probeLiveHosting`(release surface +
자산 MIME)으로 빼고 스크립트는 그것만 부른다. 테스트가 fetcher
대역으로 이 함수를 돌려 CSS `text/plain`이 FAIL인지 본다. 자산 probe
호출을 빼면 이 테스트가 실패한다. 스크립트에서 `probeLiveHosting`
호출을 빼면 live 결과가 비어 cache-control 행이 모두 FAIL이라 스스로
드러난다.
버린 대안: 문서에 한계만 적기(리뷰 (b)). 1·3이 그대로다.
위험·한계: 정규 경로 규칙으로 자산을 redirect하는 호스트는 이제
FE-GATE-019에서 FAIL이다. 워커가 없는 제품도 마찬가지다(2의 판단).
실제 호스트로 live 모드를 돌리지는 않았다.
검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts
- RED: "fails an asset the host answers only after a redirect"(옛 probe는
redirect 뒤 200을 PASS), "checks every built asset type besides the
release surfaces"(옛 코드에 `probeLiveHosting`이 없음)가 실패한다.
- 변이(06-R2 대응): `probeLiveHosting`에서 `probeAssetContentTypes` 결과를
빼면 "checks every built asset type ..."가 실패해야 한다.
Refs: 1105/06-02
문제: client는 504 TRANSFER_TIMEOUT을 NOT_APPLIED, retryable:true,
retryAfterMs 5000으로 준다. 매뉴얼대로면 기능이 5초 뒤 자동으로 다시
올린다. 근거로 든 "백엔드가 게시 전에 낸다"는 이 code에 맞지 않는다.
백엔드(45d2a478)는 업로드 작업을 전송 풀에 넘기고, 대기 스레드가
await-seconds가 지나면 작업 단계와 상관없이 future.cancel(true) 뒤
TRANSFER_TIMEOUT을 던진다(BlockingTransferExecutor). interrupt는 파일
복사는 멈추지만 게시 rename과 READY 커밋은 멈추지 않는다. 그래서 504 뒤에
파일이 READY가 될 수 있고, 백엔드가 멱등 키를 읽지 않으므로 다시 보내면
같은 파일이 둘 생긴다. 같은 client의 효과 표는 V3 표와도 갈라졌다. 503
IDEMPOTENCY_UNAVAILABLE을 client는 NOT_APPLIED, V3 표(backend-envelope.ts)와
매뉴얼 4절은 MAYBE_APPLIED로 본다. 계약 문서 6.1의 fileserver 행은 4xx를
MAYBE_APPLIED로 적는데 client는 NOT_APPLIED로 보고, 어느 쪽도 다른 쪽을
말하지 않는다. pin 대조도 이 표를 보지 않는다.
고른 방법:
- TRANSFER_TIMEOUT을 NOT_APPLIED_5XX_CODES에서 뺀다. 5xx 기본값대로
MAYBE_APPLIED이고, createFailure가 retryable:false, action contact-support로
만든다. 자동 재전송은 없다. 남은 NOT_APPLIED 5xx는 작업 스레드가 게시 전에
내는 넷(PARTIAL_WRITE, ATOMIC_PUBLISH_UNSUPPORTED, STORAGE_UNAVAILABLE,
STORAGE_FULL)이다.
- 멱등성 code(IDEMPOTENT_*, IDEMPOTENCY_* 접두)와 V3 표의 행(REFUSED_BEFORE_WRITE,
MAYBE_APPLIED_ANSWERS의 status+code)은 client도 envelopeFailureEffect로
판정한다(sharedAnswerEffect). 같은 백엔드 code의 판정이 이 repo에 하나다.
503 IDEMPOTENCY_UNAVAILABLE은 MAYBE_APPLIED가 되고, 400
IDEMPOTENCY_KEY_INVALID·422 IDEMPOTENT_REQUEST_MISMATCH는 그대로
NOT_APPLIED, 409 IDEMPOTENT_IN_FLIGHT 등은 그대로 MAYBE_APPLIED다. 손으로 둔
MAYBE_APPLIED_CODES 목록은 AMBIGUOUS_COMPLETION 비교 하나로 줄었다.
- pin 옆에 복사한 백엔드 답 표(config/contracts/backend-idempotency-answers.json)의
행마다 client 결과의 effect가 V3 표와 같은지 통합 테스트가 본다. 그 표는
tests/unit/backend-contract-pin.test.ts가 V3 표를 묶는 표와 같다. pin을
옮기면 두 reader가 함께 다시 대조된다.
- Fileserver 4xx를 NOT_APPLIED로 보는 이유(업로드 use case가 취소)를 계약
문서 6.1에 한 곳으로 적고, client 주석과 매뉴얼은 그곳을 가리킨다.
- client 주석·매뉴얼의 백엔드 SHA 표기를 bbe944bd에서 pin(45d2a478)으로
맞췄다. 두 SHA 사이 Fileserver main 코드는 바뀌지 않았다(리뷰 2.1절).
버린 대안:
- client 효과 판정을 V3 표로 통째로 바꾼다: Fileserver 4xx가 모두 결과
불명이 되어 413·415·422 파일 거절과 202 REJECTED 화면이 나빠진다. 단일
업로드에서는 use case가 취소하므로 근거도 없다.
- TRANSFER_TIMEOUT 한 줄만 고친다: 위험한 줄은 없어지지만 세 표의 갈라짐과
pin 밖 상태가 남는다.
위험·한계:
- 504 TRANSFER_TIMEOUT 뒤 화면이 "재시도"에서 "결과 불명"으로 바뀐다. 503
IDEMPOTENCY_UNAVAILABLE도 같다. CHANGELOG [계약] 한 줄이 필요하다.
- 백엔드로 넘김: 백엔드는 TRANSFER_TIMEOUT을 retryable=true, ambiguous 없이
보낸다(FileserverErrorCode, BlockingTransferExecutor). 요청 — (a) 작업이
시작된 뒤의 대기 초과는 details.ambiguous=true, reconciliationRequired=true,
retryable=false로 보내거나, (b) 작업 스레드가 게시 rename과 READY 커밋 전에
interrupt를 확인해 504가 "READY 없음"을 보장하게 하고, 어느 쪽인지
docs/fileserver/http-contract.md에 적는다. 백엔드가 (b)를 고르면 이 줄을
되돌린다(재검토 조건).
- 백엔드로 넘김: POST /v1/files가 Idempotency-Key를 읽지 않는다
(UploadFileApplicationUseCase NOT_IDEMPOTENT). 요청 — 업로드를 멱등성
executor 뒤에 두거나, 키를 무시한다고 Fileserver 계약 문서에 적는다.
- 리뷰 최소 개선 방향 ④의 "drift 검사 대상에 docs/fileserver/http-contract.md
추가"는 하지 않았다. scripts/check-backend-contract-drift.ts와 pin 모양은
같은 라운드의 1105/07-01 수정이 다시 짠다. 같은 파일을 두 브랜치가 고치면
충돌한다. 07-01과 함께 넣는 편이 낫다.
- Fileserver 자신의 code 표(NOT_APPLIED_5XX_CODES)는 여전히 손으로 읽은
것이고 pin 대조 밖이다. 늦게 READY가 되는 경쟁은 재현하지 않았다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts
RED(이 커밋의 테스트 + 부모 src): Envelope failures 표의 "503
IDEMPOTENCY_UNAVAILABLE → SERVER_FAILURE, MAYBE_APPLIED, retryable false",
"504 TRANSFER_TIMEOUT → SERVER_FAILURE, MAYBE_APPLIED, retryable false",
"504 TRANSFER_TIMEOUT is an unknown result the client does not offer to
retry", pinned backend answer table의 "reads 503 IDEMPOTENCY_UNAVAILABLE as
the V3 Envelope table does"가 실패한다.
Refs: 1105/01-02
문제: 응답 DTO를 `.strict()`로 바꾸고 FE-REG-SCHEMA 행의
`unknownFieldPolicy`를 STRIP_UNKNOWN에서 REJECT_UNKNOWN으로 같이 고치면
check:registries가 behavior-change로 통과한다(리뷰 배치 07-R1). 1103/07-03
수정은 행과 검증기를 묶었지만 등급은 그대로였다. 그 뒤 백엔드가 응답에
필드 하나를 더하면 그 API는 SCHEMA_MISMATCH로 실패한다. 같은 경계에서
FE-REG-API는 acceptedStatuses 축소를 breaking으로 본다.
고른 방법: 분류기에 규칙 하나를 더한다. `direction: "RESPONSE"` 행의
`unknownFieldPolicy`가 REJECT_UNKNOWN이 아니던 값에서 REJECT_UNKNOWN으로
바뀌면 kind `response-reader-narrowed`, breaking이다. 반대 방향
(REJECT→STRIP, 읽는 쪽을 넓힘)과 REQUEST 행(프론트가 스스로 채우는 값)은
그대로 behavior-change다. 버린 대안: governance의 FE-REG-SCHEMA
breakingFields에 `unknownFieldPolicy`를 넣는 것(리뷰 안 B). 넓히는 변경까지
증거를 요구하게 되고, governance 계약이 바뀌어 템플릿과 다운스트림 모두
기준선을 다시 승인해야 한다. 이 규칙은 기준선과 governance를 바꾸지 않는다.
리뷰 안 (1)의 fieldTypes 선언도 같은 이유로 하지 않았다.
위험·한계: 규칙은 칸 이름(`unknownFieldPolicy`)과 값 어휘
(src/contracts/schema-registry.ts)에 묶여 있다. 어휘를 바꾸면 이 함수도
고친다. route-params·route-search(REQUEST 방향, URL을 읽는 쪽)를
REJECT_UNKNOWN으로 좁히는 변경은 여전히 behavior-change다. 지금 템플릿
스냅샷은 기준선과 같아 결과는 none 그대로다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/registry-compatibility.test.ts
리뷰 07-R1 패치(응답 DTO `.strict()` + 응답 행 두 개 REJECT_UNKNOWN)를
다시 적용하면 check:registries가 `breaking change missing evidence:
FE-REG-SCHEMA:ReferenceResource(List)Payload:unknownFieldPolicy:
response-reader-narrowed`로 실패해야 한다.
Refs: 1105/07-02
문제: 사전 캐시 수집기(`collectStaticAssets`)는 dist 전체를 돌고 파일
이름만 해시 정규식으로 본다. `public/` 파일은 이름 그대로 dist 루트에
복사되는데, `apple-touch-icon.png`, `android-chrome-192x192.png`,
`safari-pinned-tab.svg`는 정규식에 걸려 immutable 자산으로 들어간다(리뷰
06-R1). 제품이 같은 이름으로 아이콘을 바꾸고 CDN이 옛 바이트를 주면 새
릴리스 install이 INTEGRITY_MISMATCH로 통째로 거절된다. 이전 릴리스
fallback, 호스팅 정책 `/assets/*`, MIME probe, 레시피 문서는 모두
`assets/`만 가정한다.
고른 방법: 리뷰 06-01의 (a). 계약 모듈에 `BUILD_ASSET_DIRECTORY =
"assets/"` 하나를 두고, 수집기는 그 아래 파일만 받는다. 워커 fallback
(`service-worker-static-assets.ts`)과 probe(`hosting-probe.ts`)도 같은
상수를 읽는다. `build.assetsDir`를 바꿀 때(0925/06-08) 이 상수 한 곳만
고치면 된다. 수집기의 `.vite/` 제외는 새 조건이 덮으므로 지웠다. 레시피
문서에 루트 파일이 빠진다는 문장을 더했다.
버린 대안:
- 정규식을 Vite 해시 형식(8자 고정)으로 좁히기. 우연히 맞는 이름이 남는다.
- 문서만 고치기. 아이콘 문제가 그대로다.
위험·한계: 루트에 해시 이름 파일을 일부러 두는 제품은 그 파일이 사전
캐시에서 빠진다. Vite는 그런 파일을 만들지 않는다. 상수는 vite 설정에서
읽지 않는다. `build.assetsDir`를 바꾸는 제품은 상수도 같이 바꿔야 한다
(0925/06-08은 그대로 남는다).
검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/unit/service-worker-web-push-remediation.test.ts tests/unit/service-worker-runtime.test.ts tests/unit/hosting-probe.test.ts tests/unit/service-worker-build-output.test.ts
- RED: "precaches only the assets directory, not public files at the dist
root"가 옛 수집기에서 루트 아이콘 세 개를 받아 실패한다.
Refs: 1105/06-01
문제: 런타임 설정에 비밀처럼 보이는 키(`CLIENT_SECRET` 등)가 있으면
부팅이 CONFIG_SECRET_NAME_REJECTED로 멈추지만, 안전한 부팅 오류에는
buildId만 있고 어느 키인지가 없다. assertSafeConfigNames가 던진 오류의
message에는 키 이름이 있었지만 loadRuntimeConfig가 그 오류를 버렸다.
같은 파일의 스키마 실패는 키 이름을 invalidKeys로 싣는다.
고른 방법: assertSafeConfigNames가 UnsafeConfigNameError를 던지고 그
`key`에 거절한 키의 점 경로(`CAPABILITY_OVERRIDES.AUTH_TOKEN`,
`FEATURE_OVERRIDES.<id>.CLIENT_SECRET`)를 싣는다. 로더는 그 경로를
스키마 실패와 같은 SAFE_KEY_PATTERN으로 거른 뒤 invalidKeys에 넣는다.
오류 화면은 이미 invalidKeys를 "잘못된 설정 키"로 보인다. 값은 어디에도
싣지 않는다. 버린 대안: message에서 키를 정규식으로 다시 읽는 것.
message 문구가 바뀌면 조용히 빠진다.
위험·한계: 키 이름은 거절된 문서에서 온다. 그래서 길이·문자를 제한하고,
그 밖의 이름은 빼고 코드만 남긴다. 첫 번째로 걸린 키 하나만 싣는다
(검사가 첫 키에서 멈추는 동작은 그대로). assertSafeConfigNames의
시그니처와 message는 바꾸지 않았다. UnsafeConfigNameError는
src/contracts/env.ts에 새로 더한 export다(추가만).
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/runtime-schema/runtime-config.test.ts
Refs: 1103/07-04
문제: 승인된 LOGOUT·ACCOUNT_DELETION purge는 객체 목록을 읽고, 하나씩
지우고, 마지막에 journal 행을 한 번 센 뒤 0이면 chunk sweep으로 끝나
`chunkSweep: "COMPLETED"`를 돌려준다. 목록과 세기는 각각 한 순간만 본다.
- 다른 탭이 새 객체를 put하는 중이면 purge의 remove가 그 put이 쥔
origin lease를 기다린다. partition에 객체가 3개 이상이면 그 put은
목록 뒤에 commit하고 세기 전에 complete까지 끝난다. 목록에도 행 수에도
없어 sweep이 그 chunk를 건너뛰고, 계정 삭제 뒤에도 파일이 읽힌다
(리뷰 실험 Y1b 메모리 20/20, Chromium 6/6). 저장소 테스트는 객체
0~1개로만 돌아서 이 틈을 놓쳤다.
- FILES_READY에서 멈춘 put의 행이 `logicalKey`를 잃으면 세지 못한다.
staging receipt가 chunk를 sweep에서 지켜 purge마다 COMPLETED인데
receipt·chunk·manifest가 남는다(Y2).
고른 방법: 마지막 객체까지 돈 purge는 sweep 대신 늘 partition 삭제로
끝낸다(리뷰 2.1절 (d')). exclusive partition lock이 그때 진행 중인
put·delete를 모두 기다린 뒤 디렉터리 전체(staging 포함)와 그 partition
행을 지우므로 두 경우를 함께 막는다. 객체 순회는 `removedObjects`·
`releasedBytes` 보고와 예산 단위 진행을 위해 남긴다. 예산이나 다른 탭의
변경(CONFLICT) 때문에 끝까지 돌지 못한 호출은 지금처럼
`moreObjectsAvailable: true`를 돌려주고, 그때만 journal 행을 세서 끝나지
않은 행이 있으면 바로 partition을 지운다(2026-11-03 05-01 그대로).
purge 성공 report는 이제 `partitionDeleted`와 `moreObjectsAvailable`
중 정확히 하나를 가진다(walk 뒤 abort도 more로 보고).
버린 대안:
- (a) sweep 뒤에 다시 세고 committed 객체를 한 번 더 본다: ①만 막고
②가 남는다. 다시 볼 때 정책상 남겨야 할 객체를 가려내려면 목록을 끝까지
다시 읽어야 한다.
- (b)+(a): 둘 다 막지만 판단 조건이 일곱 개가 된다.
- 세기를 아예 없애기: 예산에 걸린 호출의 crash 행 처리가 다음 호출로
밀린다. 지금 동작을 바꿀 이유가 없어 남겼다.
위험·한계:
- 모든 승인 purge가 다른 탭의 진행 중 put을 기다린다(지금까지는 끝나지
않은 행이 있을 때만). 기다림 상한은 `mutationLockWaitTimeoutMs`
(1103/05-02)이고 abort로 멈출 수 있다.
- 같은 partition에 LOGOUT 때 남겨야 하는 객체가 섞이면 이 방법은 맞지
않는다. 지금 정책 검사는 OPAQUE_PARTITION이면 LOGOUT·ACCOUNT_DELETION
모두 purge만 허용해 그런 객체가 생기지 않는다.
- port의 `chunkSweep`은 아무도 채우지 않는다. 읽는 코드가 깨지지 않게
타입은 남기고 `@deprecated`로 적었다.
- recipe fake의 purge도 늘 `partitionDeleted`다.
- `logicalKey`를 잃은 행 자체는 여전히 남는다(05-03 설계). 그 bytes는
이제 남지 않는다.
- Firefox·WebKit에서 Y1은 돌리지 않았다. browser spec은 객체 0·3개
두 경우로 늘렸다.
검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/opfs-worker-runtime.test.ts
tests/unit/opfs-byte-store.test.ts tests/unit/indexeddb-opfs-journal.test.ts
- node scripts/run-vitest.ts run tests/recipes/browser-file-storage-contracts.test.ts
- corepack pnpm test:browser-capabilities tests/browser-capabilities/opfs-runtime.spec.ts --project=chromium
Refs: 1103/05-01
문제: 짝 백엔드(45d2a478)는 POST /v1/files를 요청 안에서 동기로 검증하고
READY가 아닌 state를 모두 202로 답한다(FileUploadController#created).
악성 코드가 아닌 이유로 검증기가 거절하면 예외 없이 202 REJECTED다
(FinalizeUploadApplicationUseCase#applyNonAcceptVerdict). 기본 검증기 사슬의
첫 검증기(LengthVerifier)가 빈 파일을 그렇게 거절하므로, 0바이트 파일
하나로 닿는다. client schema에는 REJECTED가 없어 이 답이 SCHEMA_MISMATCH,
APPLIED_CONFIRMED, "응답 형식 오류" 문구로 끝난다. 사용자는 파일을 바꾸라는
안내 대신 지원 문의를 보게 된다. 테스트의 MSW는 202 VERIFYING만 적은 백엔드
문서에서 왔고, 매뉴얼도 202를 "아직 검사 중"으로 적어 QUARANTINED(동기
검증 202의 대부분)를 끝나지 않는 대기로 보이게 한다.
고른 방법(리뷰 01-01 최소 개선 방향 (가)):
- schema가 REJECTED를 받는다. 202 REJECTED는 성공이 아니라 실패
VALIDATION_REJECTED, code FILE_REJECTED, NOT_APPLIED, httpStatus 202다.
413·415·422 파일 거절과 같은 규칙이다. 백엔드는 그 레코드를 공개하지
않고 바이트 정리를 예약하므로 쓸 수 있는 파일이 남지 않는다. 공개 타입
FileserverFileState와 FileserverUploadedFile은 바꾸지 않았다(REJECTED는
성공 값으로 나오지 않는다).
- 빈 파일은 읽기 전(선언 크기 0) 또는 읽은 뒤(선언 없음, 0바이트)
보내지 않고 FILE_EMPTY, NOT_STARTED로 끝낸다. 서버의 202 REJECTED에는
이유가 없어 기능이 "빈 파일"이라고 말할 수 없기 때문이다.
- 201⇔READY 검사, size 일치 검사, 모르는 필드 무시는 그대로다. 201
REJECTED는 여전히 SCHEMA_MISMATCH다.
- MSW 설명을 백엔드 코드(45d2a478) 기준으로 고치고 202 QUARANTINED·
REJECTED 행을 더했다(1103/01-01의 "MSW가 문서에서 왔다" 부분).
- 매뉴얼 7절이 202 state 셋의 뜻(VERIFYING 재검사 대기, QUARANTINED 관리자
결정 전 내려받기 불가, REJECTED는 실패)과 FILE_EMPTY를 적는다.
버린 대안:
- REJECTED를 성공 state로 넘긴다: 타입 변경은 작지만 기능마다 성공 값에서
거절을 다시 찾아야 하고, 공개 타입 FileserverFileState가 넓어진다.
- 빈 파일 거절만 한다: 기본 사슬은 막지만 제품이 더한 검증기의 REJECT는
그대로 SCHEMA_MISMATCH다.
위험·한계:
- upload() 결과가 바뀐다. 202 REJECTED가 SCHEMA_MISMATCH에서
VALIDATION_REJECTED/FILE_REJECTED로, 빈 파일이 서버 요청에서 FILE_EMPTY로
바뀐다. CHANGELOG [계약] 한 줄이 필요하다.
- 빈 파일 거절은 짝 백엔드 기본 검증기 사슬을 가정한다. 제품이 사슬에서
LengthVerifier를 빼 빈 파일을 받게 하면 client 규칙도 바꿔야 한다.
- 실제 짝 백엔드를 띄워 빈 파일을 올려 보지 않았다(미검증). 응답 모양은
백엔드 코드(UploadedFileResponse, FileRecord#toDescriptor)를 읽은 것이다.
- 1103/01-01의 남은 부분은 이 커밋 밖이다: 백엔드 매뉴얼의 짝 경로 안내와
docs/fileserver/http-contract.md의 202 state 목록(백엔드로 넘김), 실제
업로드 검증(미검증).
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts
RED(이 커밋의 테스트 + 부모 src): "reads 202 REJECTED as a refused file,
not as a broken answer"(SCHEMA_MISMATCH로 끝남), "an empty file", "an
undeclared size that turns out empty"(fetch를 부름)가 실패한다.
Refs: 1105/01-01, 1103/01-01
문제: FE-GATE-013의 provider sandbox는 bwrap을 --unshare-pid
--unshare-ipc --unshare-uts --unshare-net으로 띄운다. bwrap이 setuid가
아니므로 비특권 user namespace가 있어야 한다. 사전 점검
(scripts/check-system-test-prerequisites.ts)은 실행 파일·cgroup·systemd
bus만 보고 bwrap을 한 번도 실행하지 않는다. 그래서 이 제한이 있는 호스트
(Ubuntu 24.04, kernel.apparmor_restrict_unprivileged_userns=1)에서 PASS를
낸 뒤 provider 테스트 114건 중 18건이 "bwrap: loopback: Failed
RTM_NEWADDR: Operation not permitted" 또는 그 provider를 기다린 시간
초과로 실패한다. 이 조건은 runner 요구 목록, gate 정의, workflow 어디에도
없고 운영 원장의 일회성 메모에만 있다.
고른 방법:
- 사전 점검이 provider와 같은 namespace 옵션으로 bwrap에서 /bin/true를 한
번 띄운다. 실패하면 "this host does not allow unprivileged user and
network namespaces", bwrap stderr(최대 4줄), user namespace sysctl 값,
고치는 방법 셋(AppArmor profile, sysctl, 다른 runner)을 적고 exit 1.
기존 검사(실행 파일 3개, cgroup v2, systemd bus)는 그대로 둔다.
- 옵션 목록을 scripts/lib/provider-sandbox-namespaces.ts로 옮기고
run-and-validate-provider.ts와 사전 점검이 같은 상수를 쓴다. 둘이
갈라지면 점검이 다른 것을 시험하게 된다.
- 점검을 findSystemTestPrerequisiteFailures(host)로 내보내고 access·
readFile·spawn을 주입받는다. CLI 동작(출력·exit 코드)은 같다.
- config/ci/gates.json의 FE-GATE-013에 hostRequirements 두 줄을 둔다.
gate schema에 선택 필드를 더하고, generator가 그 gate를 도는 job의
runs-on 바로 위에 "# FE-GATE-013 runner requirement: ..." 주석으로
그린다. runner를 고르는 사람이 보는 자리다. 줄바꿈은 기존 nonEmpty
규칙이 막으므로 주석 밖으로 나갈 수 없다. 이 필드는 gate의 명령·증거가
아니라 runner 설명이라 기준선 gate shape 해시에는 넣지 않았다(기준선
재기록 불필요).
- 요구 목록 세 곳(docs/operations/ci-quality-gates.md,
docs/security/supply-chain.md, docs/testing/taxonomy.md)과 README merge
게이트 절에 조건을 적었다. ci-quality-gates.md에 AppArmor profile 예시를
두었다.
버린 대안:
- namespace가 없으면 provider 테스트를 skip: 거짓 초록이다.
- FE-GATE-013을 release 단계로 옮김: PR마다 sandbox 검사를 잃는다.
- probe를 systemd-run --user --scope 안에서 돌림: 리뷰 11-R10에서 scope
안과 밖의 결과가 같았다. 직접 실행이 더 단순하다.
- workflow에 요구 사항을 runs-on label로 표현: runner label 체계가 아직
없다. 주석이 지금 가능한 가장 작은 표시다.
위험·한계:
- probe는 bwrap에 --ro-bind / /만 준다. --size 같은 provider의 다른
옵션 지원은 여기서 보지 않는다(기존과 같다). probe가 다른 이유로
실패해도 namespace 문구가 나오지만 bwrap stderr를 같이 적는다.
- 호스트를 고칠지는 호스트 소유자가 정한다. 이 커밋은 조건을 적고 알리기만
한다. 이 desktop에서 FE-GATE-013은 여전히 실패하고, 이제 첫 단계에서
이유와 함께 실패한다.
- gate schema에 선택 필드 hostRequirements가 생겼다. 기존 gates.json과
제품 overlay는 그대로 통과한다.
검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/system-test-prerequisites.test.ts tests/unit/ci-workflow-generation.test.ts
- corepack pnpm check:ci, check:types, lint, verify:documentation
- desktop에서 node scripts/check-system-test-prerequisites.ts가 exit 1과
namespace 문구를 내는지, FE-GATE-013이 그 단계에서 멈추는지
Refs: 1105/12-01, 1105/11-02
문제: VD-28은 poll 규칙을 지운 V2 실행 예산으로 적는다. "operation은
registered terminal·replay-safe REST `QUERY`", "Poll-bound VD-23 budget은
`maxAttempts=1`, `authRecoveryCount=0`, `maxCumulativeSleepMs=0`"이다.
설계 3절도 "REST `QUERY` operation"과 "REST operation registry"라고 적는다.
V2 실행 경로는 2026-11-03에 지웠고(VD-23 상태 줄), 지금 규칙은 V3
descriptor의 `frontend.retryBudget: 0`이다(설계 9.2, 1103/04-01).
a65df74가 9.2만 고쳤다.
고른 방법: VD-28 1절 끝 문장과 11절 목록, 설계 3절 두 항목을 지금
규칙으로 바꾼다. GET·HEAD, SAFE·IDEMPOTENT인 V3 descriptor, `retryBudget`
0이 아니면 생성 때 거절, 실행기가 그 칸에서 재시도 상한을 읽어 한
attempt가 요청 하나라는 것이다. 상세는 9.2를 가리킨다.
설계 3절의 "REST operation registry의 credential, conditional request, ...
재사용"은 주어를 V3 실행기로 바꾸면서 conditional request를 뺐다. V3
실행기에는 ETag 처리가 없고(`http-execution-v3.ts`에 If-None-Match 없음),
VD-23 상태 줄이 conditional execution을 `DESIGNED_NOT_IMPLEMENTED`로 적는다.
위험·한계: 문서만 바꿨다. VD-28 11절의 "ETag/`If-None-Match` 또는 server
cursor 사용" 목표 줄은 결정 내용이라 그대로 두었다.
검증: 문서 전용이라 RED 없음. desktop batch에서 확인.
- pnpm verify:documentation
- `git grep -n "authRecoveryCount\|maxCumulativeSleepMs" --
docs/architecture/decisions/VD-28*` 0건(로컬 확인)
Refs: 1105/04-03
문제: 계약 조립이 실패하면 check:registries 출력에 같은 원인이 두 번
나온다. 1103/09-07 수정이 ContractContributionError의 message 끝에
reason을 붙였고, 1103/14-06 수정이 loadErrorText에서 message 뒤에
"(reason: ...)"를 또 붙였다. 두 수정이 다른 브랜치에서 들어왔다.
기존 테스트는 reason이 message에 없는 가짜 오류로만 시험해 중복을
보지 못했다.
고른 방법: loadErrorText가 message에 reason이 이미 들어 있으면 붙이지
않는다. reason을 message에 싣지 않는 오류(기존 테스트의 가짜 오류)는
지금처럼 "(reason: ...)"가 붙는다. 버린 대안: ContractContributionError
message에서 reason을 다시 빼는 것. message만 찍는 다른 출구(부팅 오류,
테스트 출력)가 원인을 잃는다(1103/09-07이 고친 문제).
위험·한계: message 첫 줄만 보므로 여러 줄 reason은 다시 붙는다. 지금
reason은 한 줄이다. docs/manual/reference/errors.md의 출력 형식 줄을
실제 출력에 맞췄다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/registry-governance.test.ts
새 테스트는 실제 ContractContributionError를 던지는 source로
check:registries를 돌려 원인이 한 번만 나오는지 본다.
Refs: 1105/09-03
문제: bounded poll은 생성 때 descriptor의 `retryBudget`이 0인지 본다
(1103/04-01). 그런데 `execute` 입력에는 descriptor가 없다. 조합 코드는
실행기에 넘길 descriptor를 스스로 골라야 하고, 같은 경로의 기본 GET
(`retryBudget: 2`)을 넘겨도 막는 것이 없다. 리뷰 04-R1 P5에서 poll 3회가
요청 9회, 실행기 대기 6번이었다. 타입 주석과 설계 9.2가 "같은 객체를
넘긴다"고 적을 뿐이다.
고른 방법: coordinator가 생성 때 검사한 그 객체를 모든 `execute` 호출에
`input.operation`으로 넘긴다. 생성 때 한 번 잡아 두므로 나중에
dependencies 객체가 바뀌어도 검사한 객체가 간다. 조합 코드는 클로저의
descriptor 대신 이것을 실행기에 넘기면 된다. 테스트의 V3 조합도 그렇게
바꿨다. 타입 주석(`bounded-polling.ts`, `bounded-poll-coordinator.ts`)과
설계 9.2를 고쳤다.
버린 대안: coordinator가 실행기를 직접 받아 부르기. 실행기 타입은
`adapters/http`에 있어 realtime 어댑터가 import할 수 없다(adapter 사이
import 금지, kernel 예외 아님). 구조 타입을 새로 두면 결과 매핑까지
coordinator가 정해야 해서 공개 모양이 크게 바뀐다.
위험·한계: 일부만 닫는다. 조합 코드가 `input.operation`을 무시하고 다른
descriptor를 실행기에 넘기면 여전히 attempt마다 요청이 최대 3번이다.
설계 9.2가 이 남은 틈을 적는다. 입력 칸을 더한 것이라 기존 `execute`는
그대로 돈다.
검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/unit/realtime/
- RED: "hands every execute call the descriptor it checked at creation"
(받은 값이 undefined), "sends one request per poll attempt with a poll
descriptor"(실행기에 undefined가 가서 요청 0개, PROTOCOL_MISMATCH)가
옛 코드에서 실패한다.
Refs: 1103/04-01
문제: bounded poll은 `execute`의 throw를 PROVIDER_UNAVAILABLE/retryable로
바꿔 lease 안에서 다시 부른다(af00067). 설계 9.2가 권하는 조합은
`execute` 안에서 V3 실행기를 부르는 것이고, 실행기는 fetch 거절을 던지지
않고 NETWORK_FAILURE 결과로 돌려준다. 그래서 그 조합에서 throw는 결과
매핑·디코딩 같은 조합 코드 결함이다. 지금은 그 결함이 maxAttempts번의
요청과 ATTEMPT_FINISHED: PROVIDER_UNAVAILABLE, 끝으로
POLL_BUDGET_EXHAUSTED가 되어 서버 장애로 보인다. 원인 예외는 남지 않는다.
고른 방법: 리뷰 04-02의 선택지 (b). throw를 모양이 틀린 결과와 같은
계약 위반으로 본다. coordinator는 이미 `parseAttemptResult`가 거절한
결과를 재시도 없이 PROTOCOL_MISMATCH로 끝낸다. throw도 그 길로 보낸다.
lease 자신의 abort로 생긴 throw는 지금처럼 abort의 이유(ABORTED,
OFFLINE, 예산 소진 등)로 끝난다. `execute` 타입 주석, 설계 9.2와 13.1의
PROVIDER_UNAVAILABLE·PROTOCOL_MISMATCH 행을 같이 고쳤다.
버린 대안:
- (c) 주석과 13.1에만 "throw는 서버 장애로 재시도된다"를 적기. 완료
기준은 "결과를 보고 조합 결함과 서버 장애를 구분한다"인데, (c)는 읽는
사람만 알고 결과는 그대로라 구분할 수 없다.
- 관측에 throw 표시 칸을 더하기. 닫힌 관측 어휘를 넓히고, 결과 kind는
여전히 서버 장애다.
위험·한계:
- 배럴로 공개된 bounded poll의 결과가 바뀐다. repo 안 소비자는 테스트뿐이다.
- `fetch`를 직접 부르는 조합은 네트워크 실패를 결과로 바꾸지 않으면 첫
거절에서 lease가 끝난다. 설계가 권하지 않는 조합이고, 타입 주석과
9.2가 "실패도 결과로 돌려준다"를 적는다.
- reconnect coordinator는 던지는 `attempt`를 계속 PROVIDER_UNAVAILABLE로
재시도한다. 그쪽 attempt는 브라우저 연결 API를 감싸는 자리라 이번
범위 밖이다.
- CHANGELOG.md 미출시 [계약] 행의 "poll은 던지는 execute도 lease 안에서
다시 시도한다"는 이 커밋과 맞지 않는다. CHANGELOG는 오케스트레이터가
고친다.
검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/unit/realtime/
- RED: "ends the lease with PROTOCOL_MISMATCH for an async execute that
rejects"·"... throws before returning"가 옛 코드에서 execute 3회,
POLL_BUDGET_EXHAUSTED로 실패한다. "keeps ABORTED ..."는 양쪽에서 통과한다
(보존 조건).
BREAKING CHANGE: createBoundedPollCoordinator의 `execute`가 던지면(abort로
생긴 것 제외) 재시도 없이 PROTOCOL_MISMATCH(retryable: false)로 lease가
끝난다. 전에는 PROVIDER_UNAVAILABLE로 maxAttempts까지 재시도했다.
네트워크 실패를 throw로 내던 `execute`는 그것을 retryable
PROVIDER_UNAVAILABLE 결과로 바꿔 돌려준다.
Refs: 1105/04-02
2026-11-03 리뷰의 조치가 main(409d72e)에 들어간 뒤 전체를 다시 봐야
한다. 지난 README 14.4절의 상태 판정("그 밖의 81건 고침")과, 조치가
검사를 약하게 했는지는 아무도 확인하지 않았다.
가이드 기준으로 16개 영역을 다시 리뷰했다. 기준은 8a44226(= main
409d72e 트리)이다. desktop에서 merge 단계 14개(workflow env)와
CLAUDE.md 게이트 목록을 직접 돌렸다. 실험은 게이트가 끝난 뒤 78항목을
한 묶음으로 하나씩 돌렸고, 항목마다 checkout을 기준 커밋으로 되돌렸다.
처음에는 영역마다 따로 실행했으나 공유 잠금에 30여 건이 줄을 서서
취소했다(README 11.4절).
결과: 새 발견 48건(High 0, Medium 11, Low 37 / P1 3, P2 15, P3 30).
P1은 09-01, 12-01, 13-01. 지난 96건은 고쳐짐 74, 일부 22이고,
14.4절이 고침이라 한 13건을 일부로 바로잡았다. merge 게이트는 13/14
통과, FE-GATE-013은 호스트 user namespace 제한으로 실패한다.
위험·한계: 실제 Gitea 러너와 짝 백엔드 연동은 확인하지 못했다(README
8절). 리뷰라 코드는 고치지 않았다. 영역 문서의 실행 기록 일부는
리뷰 세션 scratchpad 경로를 가리킨다.
검증: desktop에서 이 커밋으로 documentation-readiness,
deletable-history-documents, changelog-review-ids 테스트와
verify:documentation(옆 백엔드 checkout 없이)을 돌렸다.
Refs: docs/reviews/2026-11-05-maturity-review/README.md
문제: 메인 세션이 desktop(ee7e195, 부하 0.96)에서 FE-GATE-008의 firefox
capability 실패를 다시 찾았다. 14.7절은 같은 실패(browser-files 다운로드
test)를 부하 탓 flake로 적어 두었는데 틀렸다.
방법:
- 13절에 11-10(Medium·P1, 관점 10·21, 고침 ee37dd86)을 더했다. 근거는
진단 event 기록 6건(mouseup이 홈 화면 내용), 위치 기록 3건(scrollY
그대로, body·button 12 px 아래로), ×30 재현 3/60 두 번이다.
- 색인·발견 수(95건)·14.4 행을 맞췄다.
- 14.7절의 Firefox 줄을 지우고 정정을 적었다. "FE-GATE-008이 한 번에
통과하지 않을 수 있다"는 줄도 지웠다.
검증: desktop에서 changelog-review-ids test와 verify:documentation(scoped).
문제: 메인 세션이 desktop(부하 0.68)에서 8a3b16a의 FE-GATE-008 webkit
실패(i18n.spec.ts:60)를 찾았다. 14.7절은 같은 경고(production-csp.spec.ts:52)를
부하 탓 flake로 적어 두었는데 틀렸다.
방법:
- 13절에 11-09(Medium·P1, 관점 10·21, 고침 aad005cb)를 더했다. 근거는 실패
trace의 시각, 재현 3/10·0/10·2/2, 이전 fixture가 정말 안 쓴 preload를
놓친 probe다.
- 색인·발견 수(94건)·14.4 행을 맞췄다.
- 14.7절의 webkit flake 줄을 지우고 정정을 적었다. FE-GATE-008이 한 번에
통과하지 않을 수 있는 이유는 이제 Firefox 다운로드 건 하나다.
검증: desktop에서 changelog-review-ids test와 verify:documentation.
문제: FE-GATE-008이 webkit에서 가끔 "The resource … was preloaded using
link preload but not used within a few seconds from the window's load
event" 경고로 떨어졌다(desktop 부하 0.68, i18n.spec.ts:60, 반복 10회 중
3회). 부하 탓이 아니었다. WebKit은 load 3초 뒤 한 번, 아직 아무 요청도 쓰지
않은 preload를 경고한다. 플랫폼 구성 화면은 들어갈 때 기능 실행부를 모두
불러오고(15-01), Vite는 그 청크와 정적 의존 청크를 한꺼번에 modulepreload
한다. 화면을 load 뒤 2.5초쯤 열면 module graph가 가장 깊은
reference-schemas에 닿기 전에 WebKit 검사가 돈다. 그 청크는 곧 쓰인다(표가
그려지고 link로 한 번만 받는다). 반대로 정말 안 쓰는 preload는 Chromium·
Firefox에서 늘, WebKit에서도 test가 3초 전에 끝나면 아무도 잡지 않았다
(1103/11-09).
고른 방법:
- strict fixture가 WebKit의 그 문구 하나만 정확한 패턴으로 무시한다. 다른
console warning·error는 그대로 실패다.
- 대신 tests/support/browser/preload-use.ts가 세 엔진에서 같은 방법으로
"preload한 script가 실제로 실행됐는가"를 본다.
- 문서가 받은 `<link rel=modulepreload|preload>`를 첫 바이트 전부터
MutationObserver로 적고, 끝에 남은 link도 더한다.
- page.route로 build script(`/assets/*.js`)에 "이 URL이 평가됐다"를 적는
문장 하나를 앞에 붙인다.
- test 끝에 preload됐는데 평가되지 않은 script를 `preloadunused:`로
실패시킨다. 진행 중인 dynamic import는 5초까지 기다린다.
- "사용"을 평가로 판정하는 이유: preload는 받기만 하거나(WebKit·Firefox)
받아서 parse만 한다(Chromium). 어느 엔진도 평가하지 않는다. 그래서 그
문장은 module graph가 그 청크를 실제로 실행했을 때만 돈다. WebKit의
"참조됨"과 달리 시각에 기대지 않는다.
- 볼 수 없는 것은 따로 이름을 붙여 실패시킨다(fail closed).
- script가 아닌 preload는 `preloadunverifiable:<as>:`.
- Service Worker가 문서를 제어할 때 만든 preload는
`preloadunverifiable:service-worker:`. 그 요청은 worker가 답해서
page.route가 못 본다. context.route로 worker가 받는 것을 표시하면
release manifest의 sha256 대조가 깨진다.
- route.fetch가 세 번 실패해 표시 없이 넘어간 script는
`preloadunverifiable:unmarked:`. 처음 구현은 이때 조용히
route.continue()로 넘겨 쓰인 청크를 안 쓴 것으로 보고했다(webkit
reference-form 1건).
- 일부러 실패를 일으키는 spec은 그 실패가 남기는 preload만 허용한다.
- boot-module-failure: 깨진 build의 boot 정적 closure.
- old-tab-chunk-recovery: 없어진 청크와 함께 preload된 청크. 전에는 이
허용이 WebKit 경고 문구로만 있었다.
- service-worker-update: worker 제어 중 preload만.
- production-csp는 build script를 직접 fulfill하므로, 표시를 유지하는
fulfillBuildScript를 쓴다.
버린 대안:
- (A) lazy dynamic import의 JS 의존성 preload를 끈다. 경고는 원리상 없어지지만
test의 추정에 맞춰 제품을 바꾸는 것이다. lazy 라우트 첫 진입마다 1~2 RTT가
늘고, 그 화면은 lab이 재는 화면(FE-GATE-026)이다.
- 청크 단계를 줄인다. 창이 좁아질 뿐이다.
- 3초 뒤에 화면에 들어간다. 사용자가 보는 경고를 test에서 숨긴다.
위험·한계:
- 모든 strict fixture test가 build script를 page.route로 받는다.
- 끝에 열려 있는 문서만 검사한다. 이동해 버린 문서의 기록은 같이 사라진다.
- fixture가 검사하는 것은 fixture의 page 하나다(console 검사와 같다).
- worker가 제어하는 문서의 preload는 검사하지 못한다(이름을 붙여 실패,
service-worker-update만 허용).
검증 (desktop, CI=true와 workflow env):
- RED(검사 stub): 새 preload-use.spec 9건 중 7건 실패.
- 변이 test는 세 엔진 모두 Expected
["preloadunused:/assets/async-state-Cxfod8c-.js"], Received [].
- 부모 청크 3.5초 지연 scenario는 webkit만 "console:warning:The resource
…/reference-schemas-DICBcHlO.js was preloaded using link preload but not
used …"로 실패.
- GREEN: 9 passed.
- 변이를 fixture에 직접 넣은 probe(커밋 안 함), 안 쓰는 modulepreload 하나:
- 이전 fixture(8a3b16a): chromium·firefox·webkit 3/3 통과(놓침).
- 새 fixture: 3/3 실패,
"preloadunused:/assets/async-state-Cxfod8c-.js".
- 부모 청크 3.5초 지연 probe:
- 이전 fixture: webkit 실패.
- 새 fixture: 3/3 통과. webkit은 여전히 reference-schemas 경고를 냈다
(probe guesses ["reference-schemas-DICBcHlO.js was preloa…"]).
- 전체 e2e(playwright.config.ts): 202 passed, 3 skipped(기존 firefox SW skip).
- check:types:test, 바꾼 파일 eslint 통과.
문제: 14.5절 X4의 1~7회차와 799ab7f 결과는 CI=true와 CI_RUNNER_IMAGE
없이 돌린 것이라, 메인 세션이 c7c7887에서 workflow env로 찾은
FE-GATE-005·008·020 실패(11-08)를 놓쳤다. 리뷰 기록에 그 사실과 새 발견이
없었다.
방법:
- 13절에 11-08(Medium·P1, 고침 b693600, 안내 cd7e784)을 더하고 색인·
14.4 행·발견 수(93건)를 맞췄다.
- 14.5절에 앞 회차가 CI=true 없이 돌았다고 적고, 8회차(cd7e784, CI=true와
CI_RUNNER_IMAGE digest)와 최종 행을 더했다. 표 중간의 빈 줄로 7회차와
최종 행이 표 밖으로 빠져 있던 것도 고쳤다.
- 14.7절에 FE-GATE-008을 한 번에 통과시키지 못하게 하는 두 flake(Firefox
다운로드 시간 초과, webkit preload 경고)와 원인 조사 결과를 적었다.
Blob URL을 일찍 회수하는 경쟁을 의심해 A/B로 쟀으나 둘 다 60/60이라
테스트는 고치지 않았다.
위험·한계: 실제 Gitea 러너가 아니라 로컬에서 workflow env를 준 실행이고
CI_RUNNER_IMAGE는 가짜 digest다. 두 flake의 원인은 찾지 못했다.
검증: 깨끗한 clone(cd7e784)에서 14개 ci:gate. 001~007·009~013·020은 한
번에, 008은 세 번째 실행에서 통과. verify:documentation PASS_SCOPED.
문제
README의 로컬 merge 게이트 반복문과 매뉴얼 01, 생성 명령 출력은 CI=true와
CI 빌드 식별값 없이 돌리는 법만 적는다. 그렇게 통과해도 workflow(CI=true)에서
떨어지는 결함 두 건(1103/11-07, 11-08)이 이 차이로 숨었다.
고른 방법
- README 반복문 아래에 workflow와 같은 env 블록(CI=true, VITE_COMMIT_SHA,
VITE_BUILD_ID, RELEASE_ID, CI_RUNNER_IMAGE digest)과 깨끗한 clone에서 돌리라는
말을 더한다. 테스트가 만드는 로컬 빌드는 이 값과 무관하게 로컬 빌드로
돈다는 것도 적는다.
- 매뉴얼 01 "merge 전에 돌릴 것"과 생성 명령 Next 2번이 그 블록을
가리킨다.
검증
- verify:documentation PASS_SCOPED, tests/unit/create-feature.test.ts 43건.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 13절 11-08
문제
리뷰 README에 조치 결과가 없다. 사용자가 "나머지 전부 진행하세요"라고
했고, 이 세션이 발견 90건과 0929/03-03을 고치고 통합했다.
고른 방법
- 13절에 조치 중 찾은 발견 둘(11-07 CI 빌드 식별값 누출, 16-09 dev
manifest 고정 contract set)을 36.3 양식으로 더하고 색인을 92건으로 고친다.
- 14절을 새로 둔다: 방법(수정 브랜치 11개, wave 1~3), 결정 D1~D6, 통합에서
생긴 것, 발견별 상태(일부 9건과 결정 대기 3건), 깨끗한 clone의 merge 단계
14개 회차별 결과(X4), 매뉴얼 재실험 막힘 7건과 처리(X2), 남은 문제.
위험·한계
- X2(매뉴얼만 보는 재실험)는 고친 뒤 다시 돌리지 않았다. 고친 것은 생성
기능을 넣은 clone 확인과 X4로 확인했다.
- 실제 Gitea 러너, 짝 백엔드·nginx·Keycloak·Redis 연동은 확인하지 않았다.
검증
- 최종 커밋 799ab7f, 깨끗한 clone, CI env: FE-GATE-001~013·020 통과
(FE-GATE-008은 첫 실행 Firefox 다운로드 시간 초과 1건, 재실행 2회 통과).
- verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 13절 14절
문제
c15345c·db5728b·0eba082의 dev 전용 Vite 미들웨어(dev server가 설치된
기능의 contract set으로 manifest를 냄)를 넣은 뒤로, dev server를 쓰는
capability e2e가 "requestfailed:GET:/release-manifest.json:net::ERR_ABORTED"로
떨어졌다. 같은 호스트에서 번갈아 쟀다: 미들웨어 있음 5/30·2/30 실패, 없음
0/30·0/30(부하가 더 높았다). trace에서는 첫 manifest 요청이 200 헤더 뒤
끊기고 65 ms 뒤 두 번째 요청이 성공한다. 원인을 끝까지 좁히지는 못했다.
감시 이벤트(파일 쓰기)를 없애도 같았다.
고른 방법
- 미들웨어를 지운다. dev server는 커밋된 public/release-manifest.json을
그대로 낸다.
- 그 파일의 contractSet을 설치된 기능으로 다시 쓰는 일을 명시적 단계로
둔다: `create:feature`가 생성 뒤 scripts/write-dev-release-manifest.ts를
돌리고, 기능 제거 드릴이 지운 뒤 돌린다. 매뉴얼의 되돌리기·기능 지우기
절과 errors.md에 같은 명령을 적었다. 레지스트리 기준선과 같은 방식이다.
- tests/unit/dev-release-manifest.test.ts가 커밋된 파일이 설치된 기능의
contract set과 같은지 보고, 다르면 다시 쓰는 명령을 말한다.
- 함께: vite.config.ts가 artifacts/·dist/·.tmp/를 감시하지 않는다.
Playwright trace의 .html이 열린 페이지를 모두 다시 불러오게 했다(dev
server 로그의 page reload).
- 버린 대안: dev 부팅에서 contract set 검사 건너뛰기. 검사하는 테스트와
같은 조건을 dev만 따로 두게 된다.
위험·한계
- 기능을 손으로 지우고 명령을 잊으면 dev server가 부팅하지 못한다.
test:unit이 그 상태를 이름과 명령으로 알린다.
검증
- test:unit 2,880건, dev-release-manifest·create-feature 테스트 45건,
check:types, lint, verify:documentation 통과.
- 생성 기능을 넣은 clone의 dev capability e2e와 merge 단계 14개는 이 커밋
뒤 깨끗한 clone에서 돈다.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.5 14.6 X2 #3, 16-09
문제
매뉴얼만으로 기능을 더한 재실험(리뷰 조치 X2)에서 안내가 틀리거나 빠진
곳이 나왔다.
- 생성 명령 출력과 매뉴얼 01이 초기 JS 기록(config/scale/feature-shape-
ceilings.json)을 말하지 않는다. 출력은 "baseline does not change"만 적는다.
- 01·create-feature.md가 "드릴은 check:bundle을 돌리지 않는다"고 적는다.
12-02 뒤로 드릴은 merge 단계 명령으로 check:bundle을 돈다.
- 로컬에서 FE-GATE-013은 VITE_COMMIT_SHA가 40자리 커밋이어야 한다. 실패한
게이트의 로그 위치가 어디에도 없다.
- 01 6단계가 "생성된 판은 파라미터가 없다"고 적지만 --with-create 상세
라우트는 codec을 넘긴다. global-ids.md의 API 경로 예가 옛 생성 경로다.
고른 방법
- 생성 명령 Next에 3번(기록 다시 쓰기)과 로그 위치·FE-GATE-013 조건을
더한다. 매뉴얼 01 "merge 전에 돌릴 것"에 같은 내용과 파일 수 상한을
적는다. 나머지 문장을 지금 동작에 맞춘다.
검증
- tests/unit/create-feature.test.ts 43건, verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.6 X2 #2#5#6
문제
initialJsFiles 상한이 템플릿 그대로의 수(26)와 같다(1b8cb12). 기능의 지연
페이지가 셸과 같은 구성요소(Button, SearchField)를 쓰면 그 구성요소가 공유
청크로 떨어져 초기 파일이 하나 는다. 매뉴얼의 검색 폼 예제를 따른 기능
하나로 FE-GATE-012가 "27 > budget 26"으로 실패했다(리뷰 조치 X2 #4).
고른 방법
- 상한을 32(지금 26 + 6)로 둔다. 템플릿은 HTTP/2 서빙을 요구하고
(1103/13-02, FE-GATE-019), 그때 파일 하나의 비용은 거의 없다(15 영역
측정). 상한은 청크가 통째로 쪼개지는 회귀를 막는 용도다.
- performance-evidence.md에 이유와, 넘었을 때 먼저 청크 그룹을 볼 것을
적는다.
- 버린 대안: 상한을 지금 수로 두고 제품마다 올리기. 템플릿 소유 파일을
기능마다 고치게 된다.
위험·한계
- 합계 바이트 예산(204,800 B)은 그대로다. 여유는 1,873 B다.
검증
- performance-budgets·bundle-artifact-contract 테스트 14건,
verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-05, README.md 14.6 X2 #4
문제
fix/r1103-release(15-02)가 performance-evidence.md에 기준선 기록 파일
(config/scale/feature-shape-ceilings.json)과 측정 테스트
(tests/unit/feature-shape-growth.test.ts)를 백틱 경로로 적었다. 둘 다 참조
기능을 복사해 재므로 test:sample-removal이 함께 지운다. 그래서 제거
fixture에서 verify:documentation이 실패하고 documentation-readiness
테스트 36건이 떨어진다(깨끗한 clone FE-GATE-020). 14-04 규칙(지울 수 있는
샘플 경로는 백틱 없이)과 2f2426a와 같은 결함이다.
고른 방법
- 두 경로를 백틱 없이 적고, 샘플과 함께 지워진다고 적는다.
검증
- verify:documentation PASS_SCOPED. 제거 fixture는 X4 재실행에서 확인한다.
Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-04, 15-performance.md 15-02
문제
check:backend-contract-drift가 백엔드 HEAD 45d2a478에서 http-contract.md §2
두 행의 설명 변경을 알린다. IDEMPOTENT_IN_FLIGHT(PostgreSQL 저장소는 409
대신 첫 요청이 끝날 때까지 기다림)와 IDEMPOTENCY_UNAVAILABLE(processing
lease가 시작 전에 끝나 저장소가 시작을 거절함)이다. 같은 커밋이 6.1절이
인용하는 GlobalExceptionHandler와 IdempotencyExecutor도 고쳤다.
고른 방법
- 두 행의 code·status·retryable·재전송 규칙은 같다. 프론트 판정(처리 중
MAYBE_APPLIED·같은 키, UNAVAILABLE 실행 안 됨·같은 키 자동 재전송)은
바꾸지 않는다.
- 6.1절이 인용하는 블록 13개를 두 판에서 대조했다. 내용은 모두 같고
GlobalExceptionHandler 4개, IdempotencyExecutor 1개의 줄 번호만 옮겼다.
인용한 다른 백엔드 파일 15개는 바뀌지 않았다.
- pin, 답 표 JSON, 계약 문서 4.1·6·6.1절, CHANGELOG의 pin 행과 알려진
제한을 같이 고친다.
위험·한계
- PostgreSQL 저장소의 기다림이 프론트 totalDeadline보다 길면 응답 없는
끝(결과 불명, 키 유지)이 된다. 판정은 안전 쪽이다.
- Fileserver 계약(docs/fileserver/http-contract.md)은 bbe944bd 이후 바뀌지
않았다.
검증
- check:backend-contract-drift --backend <백엔드 checkout>: pinned
45d2a478.
- backend-contract-pin·changelog-review-ids 테스트 11건,
verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-06
문제
리뷰 16-08이 적은 다섯 문장 중 넷이 f887817에서도 코드와 다르다.
- 01 3단계: 라우트 루트 검사를 tests/architecture/context-route-roots.test.ts가
"실행한다"고 적는다. 그 테스트는 fixture만 쓰고 설치된 기능을 보지 않는다.
실제로 막는 것은 앱 모듈을 적재하는 테스트와 부팅이다.
- 01 3단계·02 결정표: 인증 프로필이 틀리면 "operation을 적재하는 모든 게이트가
실패한다". 변이로 확인하면 check:registries와 그 기능을 적재하는 테스트만
실패하고 check:types·check:architecture·verify:documentation은 통과한다.
- 01 8단계: "서버 422 오류를 받을 필드". 짝 백엔드의 필드 검증은 400
VALIDATION_FAILED + details다. 공유 MSW 시나리오의 validation-422는
Envelope operation에서 결과 불명이다.
- starter-experience.md: "`NoRequest` already belongs to the sample". src에
NoRequest가 없다. 생성 명령이 <Pascal>NoRequest를 쓴다.
다섯째("테스트 2개")는 생성기 브랜치가 이미 고쳤다(테스트 3개와 test-app).
고른 방법
문장만 고친다. 리뷰가 검토하라고 한 공유 시나리오 validation-400 추가는 하지
않았다. 문서 작업 범위 밖이고, 생성된 작성 폼 테스트가 400 본문을 이미 손으로
적는다. 매뉴얼에 그 테스트를 가리켰다.
위험·한계
- 문장의 게이트 목록은 참조 기능에 넣은 변이 한 번으로 확인했다. build는
돌리지 않았다.
검증
- 인증 프로필 오타 변이: check:registries rc=1(reason 포함), check:types rc=0,
check:architecture PASS, verify:documentation PASS_SCOPED. 되돌림.
- verify:documentation PASS_SCOPED, documentation-readiness 테스트 통과.
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-08
문제
ac52a93이 backend-api-and-server-state-contract.md를 docs/README.md 1절에서
링크해 이 문서도 경로 검사를 받는다. 이 문서는 참조 기능 파일 둘을 백틱
경로로 적는다. static-delivery.md는 config/scale/feature-shape-ceilings.json
(15-02, 샘플 제거 때 함께 지워짐)을 백틱 경로로 적는다. 그래서 참조 기능을
지운 제거 fixture에서 verify:documentation이 "names paths that do not exist"로
실패하고, 그 fixture의 documentation-readiness 테스트 36건이 떨어진다
(FE-GATE-020). 14-04가 정한 규칙(지울 수 있는 샘플 경로는 백틱 없이)을
어겼다.
고른 방법
- 세 경로를 백틱 없이 적고, static-delivery에는 샘플과 함께 지워진다고
적는다.
검증
- verify:documentation PASS_SCOPED. 제거 fixture 확인은 X4 재실행에서 한다.
Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-04, 14-03
문제
--with-create(NEVER)와 --with-create --keyed(KEYED)가 만드는 코드는 단위
테스트가 텍스트로만 본다. FE-GATE-020의 두 드릴(test:feature-scaffold,
test:sample-removal)은 기본 기능 하나만 만들어 게이트를 돈다. 그래서 쓰기
slice의 타입·lint·테스트·빌드가 머지 게이트에서 깨져도 모른다(16 5.3절의
"생성 결과를 매번 게이트로 돌린다"는 전제).
고른 방법
- scripts/test-feature-scaffold.ts: 기본 기능(scaffold-feature) 옆에
scaffold-write-feature를 --with-create --keyed로 하나 더 만들고, 둘 다
만들어졌을 때 같은 게이트를 한 번 돈다. 바꾼 것은 WRITE_FEATURE_ID 상수,
create-feature-write 검사 한 개, 게이트 조건(created && createdWrite), 머리
주석이다.
- scripts/test-sample-removal.ts: 참조 기능을 지운 복사본의 create:feature
인자에 --with-create 한 개를 더했다. 쓰기 slice도 샘플에 기대지 않는다는
증거다.
- 세 변형(기본, NEVER, KEYED)이 모두 드릴의 게이트를 지난다.
- reference/create-feature.md의 드릴 설명을 맞췄다.
버린 대안
- 드릴 기능 하나를 --with-create로 바꾸기: 기본 변형이 게이트에서 빠진다.
위험·한계
- test:feature-scaffold는 기능 하나만큼(create:feature 한 번과 그 기능의
테스트) 길어진다. 게이트는 한 번만 돈다.
- 다른 작업(게이트 담당)이 같은 두 파일의 명령 목록을 고칠 수 있다. 내 수정은
위 줄로 좁혔다.
검증
- flock 아래 CHOKIDAR_USEPOLLING=1 corepack pnpm test:feature-scaffold:
rc=0, "feature scaffold: PASS (17 checks)" (생성 2 + 게이트 15), 162초.
- 같은 조건 corepack pnpm test:sample-removal: rc=0, "reference-feature
removal: PASS (23 checks, no fixture IDs)". 참조 기능을 지운 복사본에서
--with-create 기능을 만든 뒤 scaffold-* 게이트 9개가 모두 통과했다. 첫
실행은 tests/unit/create-feature.test.ts에 샘플 ID 문자열이 있어
fixture-id-residue로 실패했고, 그 테스트를 앞 커밋에서 고친 뒤 통과했다.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-06
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-01
문제
짝 백엔드에 쓰기를 붙일 때 기능 작성자가 정하는 값 넷(호출 문맥 intent,
retryBudget, classifyStatus, operationIdentityField)을 매뉴얼이 정해 주지
않는다. 02 3절은 "retryBudget 안에서 같은 키로 재전송"과 "참조 기능은 0"을
함께 적어 부딪히고, 401·403·429를 짝 백엔드가 쓰기 전에 거절하는지는 어느
문서에도 없다. 실험에서 실행기 코드를 읽고 값을 정했다(리뷰 B1~B4). 또 백엔드
생성 create가 NOT_IDEMPOTENT라는 사실과 프론트 retrySemantics의 관계가 적혀
있지 않다(03-07).
고른 방법
- 02 3절에 "짝 백엔드의 생성 기능에 붙일 때" 표를 둔다. 백엔드 create를
그대로 두면 NEVER, IdempotencyExecutor 뒤로 옮기면 KEYED. 두 경우의
retrySemantics, retryBudget(0 / 1과 실제 상한 계산), commandRecovery와
operationIdentityField의 뜻(실행기는 읽지 않음), intent 전달,
classifyStatus(401 보안 필터, 403 @RequiresPermission 프록시, 429
rate-limit interceptor preHandle — 백엔드 코드에서 확인),
refusedBeforeWrite, acceptedStatuses, 결과 불명 화면, 생성 테스트를 적는다.
- 01 4단계에 쓰기 메서드의 호출 문맥(intent), 8단계에 NEVER는 다시 보내기
버튼이 없다는 것과 생성 예제 위치를 적는다.
- 표의 값은 create:feature --with-create(--keyed)가 만드는 값과 같다.
버린 대안
- classifyStatus를 "백엔드 확인 전에는 생략"으로 두기(리뷰 권고 (1)의 잠정안):
백엔드 코드를 확인해 생성 create에서는 셋 다 use case 전이라 NOT_APPLIED로
적었다. use case가 AuthorizationPort를 쓰기 뒤에 부르면 지우라고 조건을
붙였다.
위험·한계
- classifyStatus 판정은 백엔드 c508b1ba의 생성 템플릿과 web 어댑터 기준이다.
백엔드가 바뀌면 다시 본다.
검증
- verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-07
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-07
문제
`create:feature <id> --context reference-context`로 기능을 참조 context에
넣으면 tests/features/reference-feature/installed-context-routing.test.ts가
실패한다. 그 테스트가 참조 context가 적재하는 라우트 전체를 정확히 비교하기
때문이다. 매뉴얼은 이것을 "못 잡음"으로 두고 참조 context에 넣지 말라고만
적었다(메인 세션 X1).
고른 방법
비교 대상을 참조 기능 계약의 route ID로 거른다. 테스트의 의도(참조 기능
라우트가 공개 URL 그대로 지연 적재된다)는 그대로다. 매뉴얼 01 1단계와
reference/create-feature.md의 한계 문장을 고쳤다. 생성한 context 선언을
실행하는 테스트는 앞 커밋(tests/unit/create-feature.test.ts)에 있다.
버린 대안
- 생성 명령이 reference-context를 거부: 생성기가 샘플 이름을 알게 되고, 테스트
가정 하나를 지키려고 정상 입력을 막는다.
위험·한계
- 참조 context에 넣은 기능은 경로가 /examples/reference-resources/<base>다.
참조 기능을 지우면 context가 남아 제거 드릴 잔여 검사에 걸린다고 매뉴얼에
적었다. 이 경로의 드릴은 돌리지 않았다(추론).
검증
- RED: refx-feature --context reference-context --with-create를 만든 상태에서
이 테스트가 XONE/REFX 라우트를 받아 실패(앞 커밋 검증 기록). 고친 뒤 같은
상태에서 tests/features 124건 통과, tests/component·architecture와
create-feature·schema-metadata-policy 49파일 374건 통과. 생성 기능은 지웠다.
- lint, check:types(test), verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 1101/16-02
문제
- 프론트 create:feature는 GET /api/<base>-items 목록 하나를 만든다. 짝 백엔드
new-feature.sh는 POST /<plural>(201, NOT_IDEMPOTENT)과 GET /<plural>/{id}를
만든다. 경로 규칙도, operation 쌍도 맞지 않는다(03-07).
- 짝 백엔드 모양(Envelope)의 상세 GET·작성 POST·폼·결과 불명 화면 예제는
참조 기능뿐이고, 참조 기능은 problem details 모양이라 옮기면 짝 백엔드에서
쓰이지 않는 분기와 값(400·422 분류, retryBudget 0, Envelope 줄 없음)을
함께 옮긴다(09-06, 16 5.3절).
- 생성된 목록의 "총 N개"는 배열 길이다. 백엔드 meta.page.total을 쓰지
않는다(03-02 수정이 남긴 일).
고른 방법
- 경로: 백엔드 new-feature.sh와 같은 복수형 규칙(backendPathSegment)으로
API_PATH 상수 하나를 둔다. 백엔드 api-base-path는 API_BASE_URL에 붙인다.
- 목록: mapper가 { items, total }을 내고 total은 page?.total ?? 길이다. 빈
목록은 EmptySurface로 같은 빈 상태를 그린다.
- --with-create: 상세 GET, 작성 POST, 상세·작성 라우트와 페이지, 폼 스키마
(이름 100자 = 백엔드 NAME_MAX_LENGTH), 뮤테이션 정책(commandMutationIdentity),
작성 폼 테스트를 만든다. 작성은 백엔드 기본에 맞춰 NEVER(retryBudget 0, 키
없음)다. --keyed는 백엔드 create를 IdempotencyExecutor 뒤에 둔 경우의
KEYED 값(IDEMPOTENCY_REPLAY, retryBudget 1)을 쓴다.
- 작성 descriptor: acceptedStatuses [201], refusedBeforeWrite
["<BASE>_INVALID"], classifyStatus는 401·403·429를 NOT_APPLIED(백엔드
보안 필터·@RequiresPermission 프록시·rate-limit interceptor가 use case 전에
거절한다). mapProblem이 <BASE>_INVALID를 이름 칸 오류로 바꾼다.
- 생성 테스트: gateway 테스트가 세 operation의 백엔드 본문(201 Envelope,
404 <BASE>_NOT_FOUND, 400 <BASE>_INVALID → NOT_APPLIED, 응답 유실 →
MAYBE_APPLIED, NEVER는 키 없음·KEYED는 503 IDEMPOTENCY_UNAVAILABLE 뒤 같은 키
1회 재전송)을 손으로 적는다. 하네스 재시도 상한은 앱 기본값 2다(16-07 (3)).
작성 폼 테스트는 라우터를 거쳐 201 저장 뒤 상세 열기, 400 거절을 이름 칸에
보이고 저장 버튼이 켜진 채 다시 저장, 응답 유실 뒤 결과 불명(NEVER는 다시
보내기 없음, KEYED는 같은 Idempotency-Key로 다시 보내기)을 본다.
- 페이지 테스트의 앱 조립은 <base>-test-app.tsx 하나로 모은다.
- slice 템플릿은 scripts/create-feature-write-slice.ts에 둔다. 리뷰 5.3절
재검토 조건(템플릿 2,000줄)을 넘지 않게 하고, create-feature.ts의 수정을
필요한 자리로 좁힌다.
- X1: 생성한 context 선언을 임시 폴더에 써서 생성기 선언 읽기로 읽고, 그
모듈을 import해 앱 모듈 조립(라우트 루트 검사)이 기능 라우트를 받는지 보는
단위 테스트를 더한다.
버린 대안
- 작성을 기본 KEYED로: 백엔드 생성 create는 키를 읽지 않아, 같은 키 재전송이
새 항목을 만든다. 안전해 보이는 거짓 보장이다.
- 참조 기능을 Envelope로 옮기기(09-06 (2)): 참조 테스트와 MSW fixture를 다수
바꾸고 problem details 예제가 사라진다.
- 목록 값을 배열로 두고 total을 배열 속성으로 싣기: TanStack 구조 공유가 배열
속성을 버린다.
위험·한계
- 백엔드 생성기는 목록 엔드포인트를 만들지 않는다. 백엔드에 GET 페이지 목록을
더하기 전에는 생성 목록이 405를 받는다. descriptor 주석과 매뉴얼에 적었다.
- 생성 기능의 초기 JS: 기본 +647 B, --with-create +964 B(이 브랜치 기준선
203,702 B에서 잰 값, 기능당 1 KiB 안). 기준선의 남은 여유는 1,098 B라
--with-create 기능 하나를 넣으면 134 B가 남는다.
- 두 생성기를 실제로 띄워 붙여 보지는 않았다. 백엔드 템플릿의 응답 본문과
경로를 읽어 생성 테스트에 옮겼다.
검증
- RED: tests/unit/create-feature.test.ts 새 17건 실패 → GREEN 43건 통과.
- 기본·--with-create·--with-create --keyed·--context reference-context
--with-create 네 기능을 만든 상태에서: check:types(app·test·node), lint,
check:registries(additive), check:i18n, check:architecture,
check:design-system, check:diagnostics, verify:documentation 통과. 생성 기능
테스트 77건 통과. 빠른 계층 313파일 3,818건 중 참조 라우팅 테스트 1건만
실패(X1, 다음 커밋).
- 변이: refusedBeforeWrite 삭제 → gateway·폼 테스트 2건 실패. 상세 GET의
responseEnvelope 삭제 → 조립 거절로 테스트와 check:registries 실패. KEYED
retryBudget 0 → 503 재전송 테스트 실패. 정책의 descriptor 상수 오타 → tsc 실패.
- flock 아래 build, check:bundle: 기준 203,702, 기본 기능 204,349, --with-create
기능 204,666 / 204,800 B PASS.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-06
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-07
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-01