Files
clean-architecture-frontend…/docs/reviews/2026-11-round9-01-react.md
DongHyeonka e1986be659
frontend-quality-gates / merge / static checks (pull_request) Successful in 3m30s
frontend-quality-gates / merge / tests (pull_request) Failing after 14m48s
frontend-quality-gates / merge / browser tests (pull_request) Successful in 9m28s
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Skipped
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Skipped
frontend-quality-gates / external-vulnerability-provider (pull_request) Skipped
frontend-quality-gates / external-provenance-provider (pull_request) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Skipped
frontend-quality-gates / deploy-promoted-release (pull_request) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Skipped
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
frontend-quality-gates / main / checker self-tests (pull_request) Skipped
docs(reviews): round9 확인 리뷰 결과를 적는다
main 5250ff95 전체를 분야 렌즈 아홉(React, 구조·공통 계약, 시험·QA,
UX·디자인 시스템, 접근성, 성능·빌드, 보안, 가드레일·문서, 나머지
adapter)과 지난 발견 재판정 둘로 나눠 리뷰했다. 새 발견은 반박 검증을
거쳐 80건이다(High 0, P1 1: 1112/08-02 템플릿 시험의 고정 기능 ID).
지난 리뷰가 연 118행은 고쳐짐 33, 일부 35, 남음 46, 재발 2다.

리뷰 README 하나와 영역 기록 열다섯을 docs/reviews/2026-11-round9-*.md
파일 묶음으로 둔다. 영역 기록은 서브에이전트가 쓴 원문이고, 작업 폴더
절대 경로만 줄였다. 리뷰 중 코드는 고치지 않았다.

위험·한계: 실행 증거는 desktop에 CI env를 준 실행이다(실제 runner
미검증). 실험 X-GD02·X-GD02b와 수정 라운드는 README 16절에 이어 적는다.
결정이 필요한 12건(R9-D1~D12)은 권하는 안과 함께 7절에 있다.

검증: scripts/verify.sh docs(노트북) 통과. 게이트 실행 결과는 README
11.1절(merge 13/14 rc=0, FE-GATE-013은 호스트 제약 조건 충족,
documentation rc=0).

Refs: round9 확인 리뷰
2026-11-12 22:35:54 +09:00

34 KiB

round9 L1 — fe-react 렌즈 + SRP (전체 리뷰)

round9 리뷰(2026-11-12, 대상 main 5250ff95)의 영역 기록이다. 서브에이전트가 쓴 원문을 그대로 옮겼다. 바꾼 것은 이 인용 블록과, 작업 폴더 절대 경로를 (작업 폴더)로 줄인 것뿐이다. 발견 ID는 이 파일의 이름표(R-01 등)이고, 라운드 ID(1112/NN-MM)와의 대응은 README 15절이다.

대상: 5250ff95(tree 75cc3752). 읽기만 했다. repo 파일을 고치지 않았다. 실행은 하지 않았다(실험 요청 4절).

0. 결론

  • 판정: 고칠 것 있음. 새 High 0, 새 P1 0.
  • 발견 6건: Medium·P2 1(구조적 위험, SRP), Low·P3 5(확인된 결함 4, 구조적 위험 1).
  • 결과 불명 쓰기의 재전송 입구(재전송 버튼, 같은 입력 재저장, 실행기 재시도, poll, 업로드)는 이번에 새로 열린 곳을 찾지 못했다. NEVER는 같은 입력을 UNKNOWN_EFFECT_PENDING으로 막고, KEYED는 같은 키를 쓰고, 1106/03-01 수정(재전송의 쓰기 전 거절은 결과 불명 유지)도 코드에 있다.
  • 가장 큰 것은 R-01이다. 결과 불명 상태를 코디네이터와 폼이 따로 갖고, 둘을 맞추는 판정은 생성된 작성 페이지 사본에 있다. 플랫폼에서 고친 것(1105/08-02, 1105/08-04, 1106/08-02)이 이미 생성한 기능으로 전파되지 않는다. R-02는 그 구조에서 나온 증상이다.

1. 범위

읽은 경로

  • 바뀐 곳 먼저(git diff --stat bbde570 5250ff95): 참조 샘플 기능 3개 삭제(reference-feature, platform-examples-feature, local-draft-feature). 이제 기능 React 코드는 생성 명령 템플릿이 전부다. application-query.ts(1106/03-01·03-03 수정), use-app-form.ts(1106/03-01·08-01), errors.ts(isRefusedOnEveryAttempt), backend-envelope.ts·fileserver-upload.ts(traceId).
  • src/presentation/adapters/query/ 전 파일(7).
  • src/presentation/forms/ 전 파일(5), src/presentation/pages/ 2.
  • src/adapters/query-cache/: server-state-scope-runtime.ts, tanstack-cache-coordinator.ts, tanstack-query-cache.ts 전체, 나머지는 훑음(소비자 없는 확장 지점).
  • src/adapters/http/: backend-envelope.ts·feature-http-binding.ts·platform-error-mapping.ts 전체, http-execution-v3.ts는 실행 루프·재시도 판정·결과 helper(517-1180, 1854-1934), fileserver-upload.ts는 재시도·effect 부분.
  • src/contracts/errors.ts 전체, server-state.ts(bind·mutation 정책), query-keys.ts(identity registry), diagnostics.ts(safeErrorKind).
  • src/application/: view-models/async-state.ts, policies/bounded-polling.ts, create-application.ts(일부).
  • 경계: src/presentation/components/async-surface.tsx, boundaries/render-error-boundary.tsx, chunk-recovery-boundary.tsx, routes/app-router.tsx(경계 연결부), routes/route-input.tsx.
  • 생성 템플릿: scripts/create-feature.ts(feature API, gateway, routes, use-<base>-items, 목록 페이지, 입력 테스트), scripts/create-feature-write-slice.ts(descriptor, gateway 조각, use-<base>-item, use-<base>-create, 폼, 상세·작성 페이지, 작성 페이지 테스트).
  • 계약 문서: docs/architecture/backend-api-and-server-state-contract.md 4·4.1·4.2·6·6.1절, docs/manual/02-decision-tables.md 3·4절, docs/manual/01-add-a-feature.md 7·8단계, src/{application,features,presentation,adapters,contracts}/AGENTS.md, docs/work/reference/{review-criteria,decisions,defect-patterns}.md, 테스트 전략 설계 7.1·7.2절, CHANGELOG 196·287행.
  • 짝 백엔드: scripts/new-feature.sh 이름 변환(앞 60행)만. 프론트 namesOf와 code 이름 규칙이 같음을 확인했다.

쓴 스킬과 그 기준으로 본 것

  • fe-react 함정 1(재전송 입구 다섯), 2(status+code 판정), 3(commandMutationIdentity), 4(서버 상태 위치), 5(TanStack 직접 import), 6(라우트 codec), 7(effect), 8(REJECT_WHILE_ACTIVE), 9(409·필드 문구), 10(오류 경계 reset), 12(브라우저 저장소). 체크리스트 「상태」(파생 값), 「데이터」(abort를 telemetry 실패로 세지 않음, 무효화 범위, rollback), 「렌더」(key, 정리).
  • SRP: 한 모듈·hook·컴포넌트가 바뀌는 이유가 둘 이상인 곳, 같은 판정이 여러 곳에 있는 곳. R-01, R-06이 여기서 나왔다.

확인 못 한 것

  • 실행 없음. 모든 발견은 E1이다. 4절 실험으로 E2를 만든다.
  • 게이트: desktop /tmp/claude-gates/r9fe-base/summary.txt를 읽었다. tree 75cc3752(= 5250ff95의 tree, 스냅샷 커밋 b693d36f)에서 FE-GATE-001~012 rc=0, FE-GATE-013 rc=1(결정 D8 대상인지 로그는 안 봤다), FE-GATE-020은 읽을 때 진행 중이었다. 이 결과는 발견들을 반박하지 않는다(발견마다 그 경로를 보는 테스트가 없음을 확인했다).
  • 화면으로만 아는 것: R-02·R-05의 실제 화면 흐름. verify-app으로 열 곳은 --with-create --keyed로 만든 기능의 작성 라우트(저장 중 목록으로 갔다 돌아옴 → 이름 입력 → 「같은 요청으로 다시 보내기」), 목록 라우트(배경 재조회 실패 → 「다시 시도」 중 표시).
  • http-execution-v3.ts의 admitResponse·admitProblem(1248-1800)은 지난 라운드들이 깊게 본 곳이라 훑기만 했다.

2. 발견

R-01 결과 불명 화면의 판정이 코디네이터·폼·생성 페이지 사본 세 곳에 나뉘어 있다

칸 내용
성격 구조적 위험 (SRP)
관련 관점 3, 4, 5, 22, 23, 25
심각도·우선순위 Medium·P2. 지금 템플릿 출력은 맞게 동작한다. 그러나 이 판정의 결함은 지난 두 라운드에 세 번 났고(1105/08-02, 1105/08-04, 1106/08-02), 고칠 때마다 이미 생성한 기능은 옛 판정을 그대로 갖는다. --with-create로 만든 모든 기능이 복제한다
통제 M1 — CHANGELOG가 "이미 생성한 기능은 바뀌지 않는다. … mounted ref를 손으로 옮긴다"고 적는다(CHANGELOG.md:196). 옮겼는지 보는 검사는 없다. 생성 기능을 새 판정으로 올리는 절차 문서도 없다(docs/manual, docs/work, docs/operations에서 0건)
증거 E1
근거 (1) 코디네이터가 결과 불명을 소유한다: 채널의 UNKNOWN admission(src/presentation/adapters/query/application-query.ts:310-321, :623-633). (2) 폼이 결과 불명을 따로 갖는다: unknownSubmissionRef와 result: "effect-unknown"(src/presentation/forms/use-app-form.ts:114, :304-310). 재전송 결과도 폼이 다시 판정한다: resendLeftUnknown(use-app-form.ts:522-530)은 코디네이터의 resendLeavesUnknown(application-query.ts:643-646)을 결과에서 거꾸로 추론한 사본이다. 둘은 이미 다르다: 폼은 action === "reauth"를 빼고(:527), 코디네이터는 replayed와 scope를 본다(:644-645). 401 재전송 뒤 코디네이터는 UNKNOWN을 쥐는데 폼은 unknownSubmissionRef를 비운다(use-app-form.ts:297-303). (3) 둘을 맞추는 규칙은 생성된 페이지 사본에 있다: effectUnknown·blocked·otherSaveRunning(scripts/create-feature-write-slice.ts:674-679), 저장 중 이탈 가드를 !form.pending으로 끔(:680), 마운트된 동안만 이동(:639-656), 확인 → settleApplied → 목록(:736-741), 재전송 → openSaved가 applyOutcome보다 먼저 이동(:744), feedback 고르기(:724-750). 폼이 진짜 상태를 모르니 페이지가 mutation.state.indicator로 막는다. src/application/AGENTS.md는 "결과 불명 쓰기의 재전송 판정은 한 곳에 둔다"고 적는다
발생 조건 플랫폼이 이 판정을 다시 고친다(지난 세 번처럼). 또는 제품이 생성 페이지를 손보면서 세 조각 중 하나를 빠뜨린다
영향 다운스트림 기능은 고쳐진 결함(예: 1106/08-02 저장이 떠난 사용자를 상세로 끌고 감)을 조용히 갖고 있다. 기능 수만큼 손 이식 비용이 든다. 폼과 코디네이터가 엇갈리는 상태(재마운트, 재인증)는 페이지가 매번 따로 맞춘다. R-02가 그 엇갈림에서 나온 결함이다
최소 개선 방향 결과 불명 상태의 소유자를 코디네이터 하나로 둔다. 폼은 코디네이터 상태를 읽는다(useAppForm에 mutation controller를 넘기거나, src/presentation/forms/에 useMutationForm(mutation, formOptions) 같은 platform hook을 둔다). 그 hook이 막기·피드백 고르기·마운트된 동안만 이동·확인·재전송 뒤 정리를 가진다. 생성 페이지는 그 hook과 필드·문구만 갖는다. 이미 생성한 기능의 이행 안내를 CHANGELOG [계약]에 한 번 적는다
완료 기준 생성된 <base>-create-page.tsx에 mutation.state.indicator 비교, useRef(false) 마운트 표시, form.resendUnknown·settleApplied 직접 호출이 없다. use-app-form.ts에 resendLeftUnknown 같은 재전송 결과 재판정이 없다. 지난 세 결함(1105/08-02·08-04, 1106/08-02)의 시험이 platform hook 시험(tests/component/)으로 옮겨져 통과한다
RED 시험 아이디어 platform 시험: 같은 mutation 정의를 쓰는 폼 두 개(기능 둘)를 그리고, 하나에서 결과 불명을 만든 뒤 내렸다 다시 그린다. 두 폼이 같은 hook으로 같은 막기·피드백을 보이는지 본다. 지금은 hook이 없어 쓸 수 없고, 생성 페이지 사본을 grep하는 정적 시험(mutation.state.indicator가 생성 출력에 있으면 실패)이 지금 실패한다
결정의 근거·대안 대안 A: 지금처럼 사본을 두고 CHANGELOG로 이식 안내(비용: 기능 수 × 수정 수). 대안 B: 위 platform hook(비용: 폼 API 추가, 생성 출력 변경. 생성 기능 이행 한 번). 대안 C: 폼에 코디네이터 상태만 주입하고 페이지 판정은 남김(절반). B를 권한다. 소유자 결정이 필요하면 결정 대기로 둔다(공개 API 추가)

R-02 재마운트한 폼에서 재전송하면 보낸 적 없는 화면 값을 제출 값으로 쓴다

칸 내용
성격 확인된 결함
관련 관점 1, 23, 28
심각도·우선순위 Low·P3. 쓰기는 맞다(원래 요청을 같은 키로 보낸다). 잃는 것은 사용자가 재마운트 뒤 입력한, 보낸 적 없는 값이다. 템플릿이 그리는 경로(KEYED 작성 페이지)에서 닿는다
통제 M1 — 같은 상황의 다른 출구(settleApplied)에는 규칙이 구현돼 있다(use-app-form.ts:236-246). 재전송 출구에는 없다. 이 경로의 시험 없음(tests/component/form-foundation.test.tsx의 재전송 시험은 재마운트를 다루지 않는다)
증거 E1
근거 resendUnknown이 const submittedValues = unknownSubmissionRef.current ?? values;(src/presentation/forms/use-app-form.ts:425, 주석 :424 "After a remount the form no longer holds the submitted values"). 성공이면 applyOutcome(outcome, submittedValues) → settleSuccessfulValues(화면 값)(:437, :261-263) → 기본 resetOnSuccess면 값과 기준값을 기본값으로 되돌리고, 아니면 화면 값을 기준값으로 삼아 dirty를 끈다(:218-229). 재전송이 결과 불명으로 남으면 unknownSubmissionRef.current = submittedValues(화면 값)(:430-435). 그 뒤 「변경됨으로 확인」은 settleApplied가 그 값을 제출 값으로 보고 같은 정리를 한다(:235, :248). 반대로 settleApplied의 재마운트 분기는 "The values on screen were never sent, so they and the dirty state stay as they are"(:237-241). CHANGELOG도 "화면의 값과 기준값은 그대로 둔다. 그 값은 보낸 적이 없어서, 입력이 남아 있으면 이탈 확인도 남는다"고 약속한다(CHANGELOG.md:196)
발생 조건 KEYED 작성 페이지에서 저장 중 떠났다 돌아온다(채널이 UNKNOWN을 유지, application-query.ts:982-995). 폼은 새로 마운트되어 unknownSubmissionRef가 비어 있다. 사용자가 필드에 입력한 뒤 「같은 요청으로 다시 보내기」를 누른다. 또는 재전송이 429·503 RATE_LIMIT_*로 결과 불명에 남은 뒤 「변경됨으로 확인」을 누른다
영향 보낸 적 없는 입력이 지워지거나 깨끗한 값으로 표시되고, 이탈 확인 없이 사라진다. 생성 페이지는 재전송 성공 때 pending 중에 상세로 이동하므로(scripts/create-feature-write-slice.ts:680, :744) 가드도 없다
최소 개선 방향 재전송 경로도 unknownSubmissionRef.current가 없으면 화면 값을 제출 값으로 쓰지 않는다. 성공이면 settleApplied의 재마운트 분기와 같은 처리(결과만 success, 값·기준값 유지). 결과 불명에 남으면 unknownSubmissionRef에 화면 값을 넣지 않고 "제출 값 모름" 표시를 따로 둔다. R-01을 고치면 이 분기는 hook 하나로 모인다
완료 기준 재마운트 뒤 재전송 성공·재전송 결과 불명→확인 두 경우 모두 화면 값과 dirty가 그대로다. 아래 RED 시험 통과
RED 시험 아이디어 실험 X-L1-01(4절). 새 폼(unknownSubmissionRef 없음)에 값을 입력하고 resendUnknown(async () => ({ ok: true, value }))를 부른다. 지금은 값이 ""로 되고 dirty=false다. 고친 뒤 값 유지, dirty=true
선택 비교 칸 적용 제외 — 이미 정한 규칙(settleApplied 재마운트 분기)을 다른 출구에 맞추는 일이다

R-03 생성 기능의 입력이 scope fence로 끊긴 요청을 실패 telemetry로 보낸다

칸 내용
성격 확인된 결함
관련 관점 6, 8, 24
심각도·우선순위 Low·P3. 사용자 피해 없음. 생성 기능 전부가 복제하는 기본값이다
통제 M2 — 호출자 abort(REQUEST_ABORTED)만 빼는 코드와 시험이 있다. fence abort는 없다
증거 E1
근거 생성된 create<Base>FeatureInput의 reported가 result.error.kind !== "REQUEST_ABORTED"일 때 <base>.list.failed 등을 warning으로 보낸다(scripts/create-feature.ts:940-948). scope fence로 끊긴 요청은 REQUEST_ABORTED가 아니라 SCOPE_GENERATION_CHANGED다: 전송 중 fence → TRANSPORT_FAILURE ABORTED_BY_SCOPE(src/adapters/http/http-execution-v3.ts:720-732), 응답 뒤 fence → CONTRACT_VIOLATION SCOPE_FENCED(:1854-1858). 바인딩이 둘 다 SCOPE_GENERATION_CHANGED로 바꾼다(src/adapters/http/feature-http-binding.ts:509-516, :557-558). 생성 입력 시험은 호출자 abort만 본다(scripts/create-feature.ts:1271-1281). 테스트 전략은 "aborted request는 terminal error나 telemetry failure로 오분류되지 않는다"(docs/design/2026-07-26-frontend-platform-testing-strategy-design.md 7.1절), 렌즈 체크리스트도 같다
발생 조건 목록·상세 GET이나 작성이 진행 중일 때 로그아웃·계정 전환·subject 없는 재알림으로 scope가 fence된다(src/adapters/query-cache/server-state-scope-runtime.ts:120-147)
영향 로그아웃마다 진행 중 요청 수만큼 <base>.*.failed warning이 쌓여 실패율 지표가 부풀고, 진짜 실패와 섞인다
최소 개선 방향 abort 판정을 한 곳에 둔다: src/contracts/errors.ts에 isAbortFailure(failure)(REQUEST_ABORTED, SCOPE_GENERATION_CHANGED)를 두고 템플릿의 reported가 그것을 쓴다(템플릿마다 kind를 손으로 적지 않는다). 생성 입력 시험에 fence 경우를 더한다. 이미 생성한 기능 이행은 R-01과 같은 문제다
완료 기준 생성 입력 시험에 SCOPE_GENERATION_CHANGED 실패가 emit을 부르지 않는 경우가 있고 통과한다
RED 시험 아이디어 실험 X-L1-02. 생성 입력 시험 템플릿에 fence 경우를 더해 생성·실행하면 지금 실패한다
선택 비교 칸 적용 제외 — 계약 문서의 abort 규칙을 생성 코드에 맞추는 일이다

R-04 query·mutation 실패 진단이 원인을 버린다

칸 내용
성격 확인된 결함
관련 관점 8, 24, 6
심각도·우선순위 Low·P3. 진단 품질
통제 미확인(이 동작을 보는 시험을 찾지 못함. tests/unit/query-cache.test.ts는 createQueryCacheAdapter만 본다)
증거 E1
근거 (1) 운영 QueryClient(src/bootstrap/runtime-adapters.ts:388)의 QueryCache·MutationCache onError가 모든 실패를 cache.operation.failed(warn)로 남긴다(src/adapters/query-cache/tanstack-query-cache.ts:39-44, :24-35). useApplicationQuery·useApplicationMutation은 실패한 결과마다 ApplicationQueryError를 던진다(src/presentation/adapters/query/application-query.ts:167, :478). 이 오류는 kind가 없고(failure.kind만 있다, :54-62) safeErrorKind는 kind 다음 name을 읽으므로(src/contracts/diagnostics.ts:241-266) 모든 기록이 error_kind: APPLICATION_QUERY_ERROR다. 404, 필드 거절, 결과 불명, scope fence로 끊긴 mutation(REQUEST_ABORTED·SCOPE_GENERATION_CHANGED)이 모두 "cache 작업 실패" 한 가지로 남는다. (2) 예상 밖 throw를 정규화할 때 정의 이름을 버린다: operationId: "APPLICATION_QUERY"(application-query.ts:173-177, 같은 함수가 :127·:137에서는 queryDefinitionId를 씀), "APPLICATION_MUTATION"(:702-705, :759-763, 같은 함수가 :510-513에서는 definitionId를 씀)
발생 조건 실패한 query·mutation 전부(1). execute·낙관적 update·무효화 설치 누락이 던질 때(2)
영향 진단에서 실패 종류를 가를 수 없고, 사용자 입력 거절과 abort가 warn "cache operation failed"로 세어진다(결함 패턴 C6). 예상 밖 throw는 어느 정의에서 났는지 모른다
최소 개선 방향 (1) onError는 ApplicationQueryError(서버·실행기 답)를 cache 실패로 세지 않거나, 센다면 failure.kind를 싣고 abort kind는 뺀다. (2) 두 리터럴을 queryDefinitionId·definitionId로 바꾼다
완료 기준 필드 거절·abort로 끝난 mutation 뒤 cache.operation.failed 기록이 없다(또는 kind가 실린다). 예상 밖 throw 실패의 operationId가 정의 ID다
RED 시험 아이디어 실험 X-L1-03
선택 비교 칸 적용 제외 — 진단 누락 수정

R-05 useApplicationQuery가 파생 값(stale 실패)을 effect로 state에 복사하고, 다시 시도의 초기화가 바로 덮인다

칸 내용
성격 확인된 결함(렌즈 위반은 코드로 확인, 화면 깜빡임은 미검증)
관련 관점 1, 5
심각도·우선순위 Low·P3
통제 미확인 — 최종 상태만 보는 시험이 있다(tests/component/application-query-bridge.test.tsx:15-49). 다시 시도 중 표시는 시험이 없다
증거 E1
근거 staleFailure를 useState로 두고 effect에서 query.isError && hasData면 true, 성공이면 false로 쓴다(src/presentation/adapters/query/application-query.ts:103, :185-191). TanStack v5는 data가 있으면 재조회 중에도 status: "error"를 유지하므로 이 값은 렌더 중 계산과 같다. retry가 setStaleFailure(false) 뒤 refetch하지만(:193-196) refetch가 isFetching을 바꾸면 effect가 다시 돌아 true로 되돌린다(:186-187). deriveAsyncState는 stale-degraded를 refreshing보다 먼저 고른다(src/application/view-models/async-state.ts:118-129). 렌즈: "파생할 수 있는 값을 state에 복사하지 않고 렌더 중에 계산한다", "effect는 외부 시스템 동기화에만"
발생 조건 데이터가 있는 query의 배경 재조회 실패 → 「다시 시도」
영향 매 전이마다 렌더가 한 번 더 돈다. 다시 시도 중에 "갱신 중"이 아니라 "오래된 데이터 + 다시 시도" 버튼이 다시 보인다(추론). retry의 초기화는 사실상 죽은 코드다
최소 개선 방향 const staleFailure = query.isError && hasData로 렌더 중에 계산하고 effect·state를 지운다. 다시 시도 중에 refreshing을 보이려면 isStale: staleFailure && !query.isFetching처럼 같은 줄에서 정한다(보일 상태는 fe-ux가 정한다)
완료 기준 이 hook에 setStaleFailure·그 effect가 없다. 다시 시도 중 indicator를 단언하는 시험이 통과한다
RED 시험 아이디어 실험 X-L1-04
선택 비교 칸 적용 제외 — 렌즈 기준 위반 정리

R-06 "모든 시도가 받는 거절" 판정이 기능 mapProblem이 바꿀 수 있는 failure.code를 읽는다

칸 내용
성격 구조적 위험
관련 관점 6, 17, 22, 23
심각도·우선순위 Low·P3. 기능 작성자가 mapProblem에서 code를 바꿔야 닿는다. 템플릿과 매뉴얼 예시는 code를 그대로 넘긴다
통제 M2 — 판정은 한 함수다(src/contracts/errors.ts:273-279). 입력이 백엔드 code라는 보장은 없다
증거 E1
근거 isRefusedOnEveryAttempt는 failure.code와 failure.httpStatus로 짝 백엔드 표(400 VALIDATION_FAILED, 400 IDEMPOTENCY_KEY_INVALID)를 본다(errors.ts:256-279). 그런데 PROBLEM 실패의 code는 기능 mapProblem이 준 값이 먼저다(src/adapters/http/feature-http-binding.ts:340-341, :447-450). effect는 실행기가 백엔드 code로 정한다(src/adapters/http/backend-envelope.ts:363-374). 주석은 kind를 읽지 않는 이유를 "a feature's mapProblem sets it"이라고 적지만(errors.ts:270-271) code도 같은 곳에서 정해진다. Envelope 없는 백엔드(매뉴얼 02 4절 예)의 code에도 짝 백엔드 표가 그대로 적용된다
발생 조건 (a) 기능이 선언한 쓰기 전 거절 code(예: WORKLOG_INVALID)를 mapProblem에서 code: "VALIDATION_FAILED"로 바꾼다 → 결과 불명 요청의 재전송이 그 답을 받으면 요청을 정리한다. 결정 D10 보완은 "기능이 선언한 code는 결과 불명을 풀지 않는다"(docs/architecture/backend-api-and-server-state-contract.md 6.1절). (b) 반대로 백엔드 400 VALIDATION_FAILED를 기능 code로 바꾸면 재전송 거절이 결과 불명을 풀지 못해 폼이 "나중에 다시 보내기"에 머문다
영향 (a) 정리된 뒤 다음 저장이 새 키로 나간다. 첫 시도가 적용됐다면 중복이 생길 수 있다(결함 패턴 C2와 같은 모양, 조건이 좁다). (b) 사용자가 고칠 수 있는 입력 오류에서 막힌다
최소 개선 방향 판정 입력을 백엔드 답에서 고정한다. 바인딩이 Envelope operation의 outcome.problem.code와 status로 "모든 시도가 받는 거절" 여부를 계산해 AppFailure에 따로 싣고(예: refusal: "EVERY_ATTEMPT"), isRefusedOnEveryAttempt는 그 칸만 읽는다. Envelope 없는 operation은 싣지 않는다(안전한 쪽)
완료 기준 mapProblem이 code를 바꿔도 (a)·(b) 모두 결정 D10 보완대로 동작한다
RED 시험 아이디어 통합 시험(tests/integration/): 실제 실행기 + 바인딩 + useApplicationMutation. KEYED Envelope create에 refusedBeforeWrite: ["WORKLOG_INVALID"], mapProblem이 그 code를 { kind: "VALIDATION_REJECTED", code: "VALIDATION_FAILED" }로 바꾼다. 첫 요청 응답 유실 → 재전송이 400 WORKLOG_INVALID → 지금은 indicator === null(정리됨), 고친 뒤 mutation-effect-unknown. (실험으로는 요청하지 않는다. 시험 작성이 필요하다)
선택 비교 칸 대안: 바인딩이 mapProblem의 code가 플랫폼 표의 code와 겹치면 거절하는 조립 검사(더 단순, 그러나 (b)는 못 막는다). 위 안을 권한다

3. 넘길 것

  • → fe-ux: R-05에서 다시 시도 중에 보일 상태(refreshing인지 stale-degraded 유지인지)를 정한다. R-01 hook을 만들 때 재인증 실패 뒤(코디네이터는 결과 불명, 폼은 reauth-required) 생성 작성 페이지가 sign-in 버튼 없는 상태만 보이고 결과 불명 버튼은 필드를 고쳐야 다시 나오는 흐름을 볼 것(scripts/create-feature-write-slice.ts:724-730, use-app-form.ts:297-303). 매뉴얼 8단계가 "onRetry만 넘긴다"고 적어 둔 범위라 이 렌즈의 결함으로 올리지 않았다.
  • → fe-testing: 생성 작성 페이지 시험이 1초 고정 대기로 "상세로 가지 않음"을 단언한다(scripts/create-feature-write-slice.ts:984-990). 부정 단언이라 대기가 필요하지만 시간 가정 시험(결함 패턴 T3)인지 판정이 필요하다.
  • → fe-structure: src/presentation/pages/home-page.tsx:31-47과 src/presentation/examples/platform-overview-page.tsx:396-412의 릴리스 요약 effect가 같은 사본이다(아직 갈라지지 않음). 한 hook으로 모을지.
  • → 총괄: desktop 게이트 summary는 FE-GATE-020이 진행 중이었고 013 rc=1이다. D8 조건(parts 뒤 명령 rc=0)은 확인하지 않았다.

4. 실험 요청

모두 desktop, 작업 폴더 되돌림 필요. env 없음(기본), 시간 상한 각 5분.

X-L1-01 (R-02) 재마운트 뒤 재전송이 화면 값을 지우는지

  • 명령: scripts/verify.sh exec -- node scripts/run-vitest.ts run tests/component/r9-l1-form-resend-remount.test.tsx
  • 기대: 지금 실패(값 "", dirty=false). 실패가 R-02의 증거(E2)다.
  • 패치(새 파일):
--- /dev/null
+++ b/tests/component/r9-l1-form-resend-remount.test.tsx
@@ -0,0 +1,27 @@
+// @vitest-environment jsdom
+
+import { act, renderHook } from "@testing-library/react";
+import { z } from "zod";
+import { describe, expect, it } from "vitest";
+
+import { useAppForm } from "../../src/presentation/forms/index.ts";
+
+describe("r9 L1 probe", () => {
+  it("keeps values a remounted form never sent when its resend succeeds", async () => {
+    const hook = renderHook(() =>
+      useAppForm({
+        schema: z.object({ name: z.string() }).strict(),
+        defaultValues: { name: "" },
+        allowedServerFields: ["name"],
+        mapToCommand: (values: { name: string }) => values,
+        submit: async () => ({ ok: true as const, value: "unused" }),
+      }),
+    );
+    act(() => hook.result.current.setValue("name", "typed after remount"));
+    await act(() =>
+      hook.result.current.resendUnknown(async () => ({ ok: true as const, value: "saved" })),
+    );
+    expect(hook.result.current.values.name).toBe("typed after remount");
+    expect(hook.result.current.dirty).toBe(true);
+  });
+});

X-L1-02 (R-03) 생성 입력이 fence abort를 telemetry로 보내는지

  • 명령: scripts/verify.sh exec -- sh -c 'corepack pnpm create:feature typecheck-probe-fence && node scripts/run-vitest.ts run tests/features/typecheck-probe-fence/typecheck-probe-fence-feature-input.test.ts'
  • 기대: 새 경우 1건 실패(emit 1회 호출). 나머지 통과.
  • 패치(템플릿에 경우 추가):
--- a/scripts/create-feature.ts
+++ b/scripts/create-feature.ts
@@ -1280,5 +1280,17 @@ function renderInputTest({ names, operationId }: Shape): string {
     await expect(input.listItems()).resolves.toEqual({ ok: false, error: failure });
     expect(emit).not.toHaveBeenCalled();
   });
+
+  it("does not report a load the session fence aborted", async () => {
+    const failure = createFailure("SCOPE_GENERATION_CHANGED", "${operationId}", 0, { code: "ABORTED_BY_SCOPE" });
+    const emit = vi.fn<TelemetryPort["emit"]>();
+    const input = create${pascal}FeatureInput(
+      gatewayListing(async () => ({ ok: false, error: failure })),
+      { telemetry: { emit } },
+    );
+
+    await expect(input.listItems()).resolves.toEqual({ ok: false, error: failure });
+    expect(emit).not.toHaveBeenCalled();
+  });
 });
 `;
 }

X-L1-03 (R-04) 실패한 mutation이 cache.operation.failed를 남기는지

  • 명령: scripts/verify.sh exec -- node scripts/run-vitest.ts run tests/unit/r9-l1-query-cache-diagnostics.test.ts
  • 기대: 지금 실패(기록 1건, error_kind: APPLICATION_QUERY_ERROR). 기록 내용이 R-04 증거다.
  • 패치(새 파일):
--- /dev/null
+++ b/tests/unit/r9-l1-query-cache-diagnostics.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+
+import { createQueryClient } from "../../src/adapters/query-cache/index.ts";
+
+describe("r9 L1 probe", () => {
+  it("does not count a refused save as a cache operation failure", async () => {
+    const records: unknown[] = [];
+    const client = createQueryClient({
+      diagnostics: { record: (event: unknown) => void records.push(event) } as never,
+    });
+    const answer = Object.assign(new Error("VALIDATION_REJECTED"), {
+      name: "ApplicationQueryError",
+      failure: { kind: "VALIDATION_REJECTED", effect: "NOT_APPLIED" },
+    });
+    await client
+      .getMutationCache()
+      .build(client, { mutationFn: async () => { throw answer; } })
+      .execute(undefined)
+      .catch(() => undefined);
+    console.log(JSON.stringify(records));
+    expect(records).toEqual([]);
+  });
+});

(createQueryClient가 배럴에 없으면 ../../src/adapters/query-cache/tanstack-query-cache.ts에서 가져온다.)

X-L1-04 (R-05) 다시 시도 중 indicator

  • 명령: scripts/verify.sh exec -- node scripts/run-vitest.ts run tests/component/application-query-bridge.test.tsx
  • 기대: 새 경우가 지금 실패(다시 시도 중 stale-degraded). 통과하면 R-05의 화면 영향 부분을 지우고 렌즈 위반(파생 state)만 남긴다.
  • 패치:
--- a/tests/component/application-query-bridge.test.tsx
+++ b/tests/component/application-query-bridge.test.tsx
@@ -49,6 +49,40 @@ describe("application query inbound bridge", () => {
     expect(execute).toHaveBeenCalledTimes(3);
   });
 
+  it("r9 L1 probe: does not show the stale failure again while its retry runs", async () => {
+    const client = queryClient();
+    let release: ((value: ApplicationResult<string[]>) => void) | undefined;
+    let calls = 0;
+    const execute = vi.fn(() => {
+      calls += 1;
+      if (calls === 1) return Promise.resolve({ ok: true as const, value: ["first"] });
+      if (calls === 2) {
+        return Promise.resolve({
+          ok: false as const,
+          error: createFailure("SERVER_FAILURE", "LIST", 0),
+        });
+      }
+      return new Promise<ApplicationResult<string[]>>((resolve) => {
+        release = resolve;
+      });
+    });
+    const hook = renderHook(
+      () => useApplicationQuery({ queryKey: ["resource", "r9-retry"], execute }),
+      { wrapper: wrapper(client) },
+    );
+    await waitFor(() => expect(hook.result.current.data).toEqual(["first"]));
+    await act(() => hook.result.current.retry());
+    await waitFor(() => expect(hook.result.current.state.indicator).toBe("stale-degraded"));
+    act(() => {
+      void hook.result.current.retry();
+    });
+    await waitFor(() => expect(execute).toHaveBeenCalledTimes(3));
+    await act(async () => {
+      await Promise.resolve();
+    });
+    expect(hook.result.current.state.indicator).not.toBe("stale-degraded");
+    act(() => release?.({ ok: true, value: ["recovered"] }));
+    await waitFor(() => expect(hook.result.current.state.indicator).toBeNull());
+  });
+
   it("coalesces repeated manual retries while stale data is refetching", async () => {

5. 결함 아님으로 판정한 의심

  • 생성 목록·상세 페이지가 onAction을 넘기지 않아 401·403·404에 버튼이 없다 — 매뉴얼 8단계가 그렇게 정하고 use-<base>-failure-action 조각을 준다(docs/manual/01-add-a-feature.md:588-619).
  • scope fence가 결과 불명 admission을 버려 재로그인 뒤 새 키가 된다(application-query.ts:964-978) — 런북 6.3-7에 적힌 한계(docs/operations/api-contract-and-server-state-recovery.md:280)이고 지난 라운드들이 판정했다.
  • useApplicationMutation의 LEGACY 실행 분기 — 1101 결정 08-03(테스트 4건 때문에 유지)이다.
  • KEYED 재전송이 기능 선언 code(<FEATURE>_INVALID)로 거절되면 "나중에 다시 보내기"에 머문다 — 결정 D10 보완("기능이 선언한 code는 결과 불명을 풀지 않는다")대로다.
  • bindQuery가 렌더마다 identity binding을 새로 만들어 useApplicationQuery의 lease effect가 렌더마다 돈다(application-query.ts:104-107) — 외부 자원 lease 동기화라 effect 용도가 맞고, 정리 순서상 row가 0으로 내려간 채 다른 intern을 만나지 않는다(query-keys.ts:247-299).
  • 첫 렌더에 결과 불명 채널이 아직 없어 submit이 UNKNOWN_EFFECT_CHANNEL_LIMIT_EXCEEDED를 낼 수 있다(application-query.ts:391-411, :556-574) — 채널은 마운트 effect에서 잡히고, 클릭은 그 뒤에 처리된다. 실제로 닿는 순서를 보이지 못했다.
  • 결과 불명 재전송 대기 setTimeout이 unmount에 취소되지 않는다(application-query.ts:689-695) — 사용자가 시작한 재전송이고, 대기 뒤 mutationFn이 scope를 다시 본다(:439-448). mutation은 취소가 안전할 때만 취소한다는 렌즈 기준에 맞다.
  • RenderErrorBoundary의 custom fallback 함수가 reset을 받지 않는다(src/presentation/boundaries/render-error-boundary.tsx:62-66) — 라우터의 fallback은 RENDER_FAILURE의 registry action(reload-once)대로 사용자 reload를 주고, resetKey(경로+검색값)가 라우트 이동 때 reset한다(src/presentation/routes/app-router.tsx:409-418). 사용자 버튼이라 "제한 없는 reload" 금지에도 해당하지 않는다.
  • OVERLOADED_BEFORE_SEND(클라이언트 트래픽 예산)가 kind NETWORK_UNREACHABLE로 보인다(feature-http-binding.ts:509-516) — code가 OVERLOADED_BEFORE_SEND로 남고 effect NOT_STARTED, action retry가 맞다. 문구 차이는 fe-ux 몫이다.
  • HomePage가 릴리스 요약을 effect + setState로 읽는다(home-page.tsx:34-47) — 백엔드 서버 상태가 아니라 부팅 때 읽은 릴리스 manifest이고 정리(active 플래그)가 있다.
  • 짝 백엔드 code 이름 규칙(<FEATURE>_INVALID) — 백엔드 new-feature.sh:56의 upper snake와 프론트 namesOf(scripts/create-feature.ts:142-157)가 같은 결과를 낸다(PascalCase ↔ kebab).
  • REFUSALS_OF_EVERY_ATTEMPT가 REFUSED_BEFORE_WRITE의 손 사본이다 — tests/unit/backend-envelope.test.ts:186-230가 부분집합 관계를 대조한다(구조적 위험은 통제됨).
  • 생성 목록 measureItems의 itemCount와 LIST_STANDARD.maxResultItems: 200 — 백엔드 page size 상한 100 안이다.