문제
0929/03-03은 화면 버튼 쪽만 고쳐졌다. 남은 길이 둘이다.
- useApplicationMutation의 submit은 같은 canonical input의 결과 불명
admission을 찾아 그 intent를 그대로 다시 보낸다. 키 없는 intent(NEVER)면
서버가 가려낼 수 없는 두 번째 요청이다. 막는 곳은 폼(unknownSubmissionRef)과
두 페이지의 버튼·onSubmit 검사뿐이라, 폼 밖에서 submit을 부르는 화면은 같은
항목을 둘 만들 수 있다(리뷰 실험 X1: 재전송은 null인데 같은 입력 submit이
두 번째 POST를 보냈고 keys=[null,null]).
- AsyncSurface는 state.unknownEffectResendable !== false일 때 재전송 버튼을
그린다. 코디네이터 없이 손으로 만든 AsyncState(플래그 없음)는 지금도 버튼을
그린다(실험 X3).
고른 방법
- submit이 같은 입력의 결과 불명 admission을 찾았는데 그 intent에 키가 없으면
보내지 않고 NOT_STARTED DUPLICATE_IN_FLIGHT(code UNKNOWN_EFFECT_PENDING)를
돌려준다. admission을 만들기 전이라 결과 불명 상태와 identity lease는 그대로다.
KEYED의 같은 키 재전송, 입력이 바뀐 새 요청은 바뀌지 않는다. LEGACY(테스트
하네스) 경로는 intent가 없어 replay 자체가 없으므로 영향이 없다.
- AsyncSurface는 unknownEffectResendable === true일 때만 재전송 버튼을 그린다.
코디네이터의 state는 늘 이 값을 싣는다(canResendUnknownEffect).
- 기존 async-surface 테스트 "renders unknown mutation effects with
confirm-applied and resend only"는 플래그 없는 상태로 버튼을 기대했다. 이
수정의 의도대로 isUnknownEffectResendable: true를 입력에 적었다. 단언은 그대로다.
- 런북 6.3-4와 매뉴얼 01에 키 없는 재제출과 손으로 만든 상태를 적었다.
버린 대안
FailureKind에 새 kind를 더한다: 닫힌 레지스트리를 넓히는 계약 변경이다.
"같은 논리 요청이 아직 끝나지 않았다"는 DUPLICATE_IN_FLIGHT(action none)로
충분하다.
위험·한계
- 다운스트림이 AsyncSurface에 손으로 만든 결과 불명 상태와 onResendUnknownEffect를
넘기던 화면은 재전송 버튼이 사라진다. 코디네이터의 state를 넘기면 그대로다.
- 결과 불명 admission은 메모리에만 있다. 새로고침 뒤 같은 입력은 막지 못한다
(런북 6.3-7의 한계 그대로).
검증
desktop batch에서 확인:
node scripts/run-vitest.ts run tests/component/application-mutation-admission.test.tsx
tests/component/async-surface.test.tsx tests/component/application-query.test.tsx
Refs: 0929/03-03
문제
resendUnknownEffect는 가장 오래된 admission이 UNKNOWN이고 intent가 있는지만
본다. 키 없는 명령(NEVER)도 intent는 있다. 그래서 응답을 잃은 NEVER 쓰기의
결과 불명 화면에서 "같은 요청으로 다시 보내기"를 누르면 키 없이 다시 나가고,
서버가 두 요청을 가려낼 수 없어 같은 항목이 두 번 생길 수 있다(리뷰 실험
X-D: fetch 2회, 키 [null, null]). 짝 백엔드 생성 기능의 create가
NOT_IDEMPOTENT이고 매뉴얼이 "모르면 NEVER"를 권하므로 이것이 짝 사용의
기본 경로다. 화면(AsyncSurface)은 콜백이 있으면 버튼을 그린다. 훅에도 화면에도
이 버튼을 숨기는 장치가 없다.
고른 방법
- application-query.ts canResend: head가 UNKNOWN이고 intent에
idempotencyKey가 있고 reconciliation 중이 아닐 때만 참. resendUnknownEffect는
거짓이면 null을 돌려준다. 컨트롤러가 canResendUnknownEffect로 같은 값을 낸다.
- AsyncState에 선택 칸 unknownEffectResendable(결과 불명일 때만)을 두고,
훅이 deriveAsyncState 신호로 채운다. AsyncSurface는 이 값이 false면
onResendUnknownEffect가 있어도 재전송 버튼을 그리지 않는다. 그래서 기존
페이지 배선(참조 폼)은 바꾸지 않아도 키 없는 명령에서 버튼이 사라진다.
- KEYED는 지금처럼 같은 키로 재전송한다.
버린 대안
- 페이지가 canResendUnknownEffect를 보고 콜백을 넘기지 않게만 하기: 기존
배선을 복사한 다운스트림 페이지에 버튼이 남는다(누르면 아무 일도 없다).
- AsyncSurface에 별도 prop: 같은 사실을 페이지가 한 번 더 옮겨야 한다.
위험·한계
- 키 없는 결과 불명 화면에는 "변경됨으로 확인"과 목록 새로고침만 남는다.
"적용 안 됨"으로 닫는 길은 없다(근거 없는 확정을 주지 않는 기존 결정).
- 같은 입력으로 submit을 다시 부르는 경로(D-1 replay)는 바꾸지 않았다. 폼은
결과 불명 동안 제출을 막는다.
- hand-built AsyncState(칸 없음)는 지금처럼 버튼을 그린다.
검증
- RED: application-mutation-admission 2건(NEVER: canResend false·resend null·
execute 1회, KEYED: canResend true), async-surface 2건 실패.
- GREEN: tests/unit·integration·component·features·contract 250파일
3,147건 통과. 변이(훅이 키를 보지 않음, 화면이 칸을 보지 않음) 모두 검출.
- check:types, lint, check:architecture, verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 0929/03-03
Refs: docs/reviews/2026-11-03-maturity-review/README.md 2.1
문제
primitive가 종류별 파일 5개(core·forms·overlays·navigation·feedback)에
모여 있다. 번들러는 export가 아니라 모듈 단위로 청크를
나눈다. 그래서 셸이 쓰는 Button·Drawer·Select와 같은 파일에 있는
Tooltip·Menu·Card 같은 갤러리 전용 primitive도 셸과 같은 청크로 간다.
다음 커밋(side effect 없음 선언)이 효과를 내려면 먼저 파일이 나뉘어야
한다.
고른 방법
- primitives/ 아래를 컴포넌트마다 파일 하나로 나눈다(32개). 본문은 원래
줄을 그대로 옮기고 import만 새로 쓴다. ToastProvider·useToast는 한
파일, 내부 타입 FieldCopy는 field.tsx에서 내보낸다.
- PaginationLandmarkContext는 pagination-landmark.ts로 따로 둔다.
page-templates.tsx(StatusPage, 초기 청크)가 이것만 읽는데, Pagination과
같은 파일이면 Pagination 코드가 초기 청크로 간다.
- design-system/index.ts의 export 이름은 그대로다(값 71개, 타입 36개를
전후 비교). components/ui/*.ts 재수출, page-templates.tsx,
common-patterns.tsx는 새 경로를 가리킨다. .dependency-cruiser.json의
page-templates 예외는 출발 파일 기준이라 그대로 맞다.
버린 대안
- 셸이 쓰는 것과 나머지 두 파일로 나누기: 제품 셸이 Tooltip 하나를
쓰면 나머지가 다시 초기 청크로 간다.
위험·한계
- 이 커밋만으로는 번들이 바뀌지 않는다. 배럴이 다시 내보내는 모듈은
side effect가 있다고 보고 모두 초기 청크에 남는다(초기 JS 16개 청크,
203,818 → 203,824 B). 다음 커밋이 같이 있어야 효과가 난다.
- primitives/ 안의 파일 경로를 직접 import하던 다운스트림 코드는 경로를
바꿔야 한다. 공개 경계(index.ts)는 그대로다.
검증
- 원래 5개 파일의 import 아래 본문 줄이 새 파일에 빠짐없이 한 번씩
있다(줄 다중집합 비교).
- tsc(app·node·test) 통과, 바꾼 파일 eslint 통과.
- node scripts/run-vitest.ts run tests/component: 35파일 228/228 통과.
- 빌드(flock): 초기 JS 16개 청크 203,824 B, ui-tooltip 등 갤러리 클래스는
여전히 초기 청크에 있다(예상대로).
Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-08
문제: 조회 실패는 failure.requestId를 "지원 참조"로 보이는데, 폼의
FormFailureStatus는 넘기지 않았다. 결과 불명 저장은 AsyncSurface의
indicator 분기라 실패 객체가 없고, 폼도 MAYBE_APPLIED 실패를 버렸다.
사용자가 가장 문의하고 싶은 경우에 줄 식별자가 없었다. 샘플의
contact-support 이동은 식별자를 버리고, 상태 페이지는 식별자처럼 보이는
고정 문자열 "REFERENCE-STATUS-DEMO"를 보였다.
고른 방법: 리뷰의 최소 개선 방향(기대 계약 고정)대로 했다.
- FormFailureStatus가 supportReference={failure.requestId}를 넘긴다.
- useAppForm이 MAYBE_APPLIED 실패도 보관하고 supportReference(현재
보이는 상태 실패 또는 결과 불명 저장의 requestId)를 돌려준다. failure는
여전히 상태 결과에만 값이 있어 FormFailureStatus가 결과 불명을 두 번
그리지 않는다.
- AsyncSurface가 supportReference prop을 받아 결과 불명 indicator에서만
보인다. 샘플 폼 페이지가 form.supportReference를 넘긴다.
- 샘플 contact-support 이동은 식별자를 history state로 넘기고(URL에
넣지 않음), 상태 페이지는 받은 문자열만 보이고 없으면 줄을 숨긴다.
공개 API는 추가만 했다(useAppForm 반환 필드, AsyncSurface prop).
버린 대안: 결과 불명 식별자를 mutation 채널(application-query.ts)에
두기 — 재마운트 뒤에도 남지만 925줄 파일의 채널 구조를 바꾸고 08-03
(raw 경로 정리)과 겹친다.
위험·한계: 폼이 재마운트되면 결과 불명 배너는 mutation 채널에서
남지만 식별자는 사라진다(제출 값과 같은 수명). 서버가
x-correlation-id를 노출하지 않으면 식별자가 없다(0929 FOLLOW-UP 03-03).
결과 불명 화면에 줄 하나가 생긴다. 초기 JS는 이번 브랜치 전체 기준
202,520 → 202,631 B(예산 204,800 B).
검증:
- RED: 새 테스트 6건이 수정 전 실패(form-foundation 2, async-surface 1,
reference-page 3. 예: "Unable to find an element with the text: 지원
참조: corr-save-500"). 새 e2e가 이전 빌드에서 실패(getByText('지원 참조:
corr-save-500') not found).
- GREEN: 관련 3파일 70/70, tests/component·features·architecture
59 files 336 tests 통과. e2e reference-save·reference-form·
reference-route chromium·firefox·webkit 42/42. tsc app·test, eslint,
check-i18n, check-design-system 통과.
Refs: docs/reviews/2026-09-29-maturity-review/08-presentation.md 08-04
문제: EmptySurface, TerminalErrorSurface, 접근 상태 화면, ErrorSummary의
제목이 h2로 고정돼 있다. Card(h3)나 상세 구획(h2) 안에 넣으면 그 안의
상태 문구가 카드 제목보다 상위 제목이 된다. /examples/states에서
h3 카드 안에 h2가 있었고, 섹션 h2 아래 접근 상태 화면도 h2였다.
상태 화면 제목을 <p>로 바꾸는 변이(M5)를 잡는 테스트도 없었다.
고른 방법: Card에 이미 있는 계약을 그대로 옮겼다. 위 네 컴포넌트에
headingLevel?: 2 | 3 | 4(기본 2)를 더하고, 이들을 그리는 AsyncSurface와
AccessSurface가 같은 prop을 넘긴다(그러지 않으면 가장 흔한 진입점에서
뒤집힘이 남는다). 타입은 state-surfaces.tsx의 HeadingLevel 하나에 둔다.
갤러리는 카드 안 상태에 4, 섹션 바로 아래 접근 상태에 3을 준다.
상태·오류 요약 CSS 선택자는 :is(h2, h3, h4)로 넓혔다. 공개 prop은 추가만
했고 기본값이 그대로라 기존 화면은 바뀌지 않는다. 버린 대안: 제목
수준 context(R7) — 모든 컨테이너가 제공자를 둬야 하고 Card의 prop
계약과 갈린다. Card의 인라인 2 | 3 | 4와 HeadingLevel을 합치는 것은
VD-05 재수출 경로를 건드려 이번 범위에서 뺐다.
위험·한계: 갤러리 화면이 바뀐다(카드 안 상태 제목 h4 16px, 접근 상태
h3 20px). 시각 골든은 오케스트레이터가 갱신한다. 실제 스크린 리더
제목 목록은 확인하지 않았다(접근성 트리 대신 component 단언).
검증:
- RED: async-surface.test.tsx 새 테스트 7건이 수정 전 실패(예: "expected
[ <h2></h2> ] to have a length of +0 but got 1").
- GREEN: async-surface.test.tsx 31/31, tests/component 220/220(4회 반복
통과, 부하 32에서 첫 실행 1건 실패 뒤 재현 안 됨). tsc app·test 통과,
eslint 통과. e2e accessibility·typography·reference-form·reference-save
chromium 27/27.
Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-05
AsyncSurface drew auth-required, forbidden and not-found query failures with
its own copy while the gallery used AccessSurface. Both now use one set, and
a state surface without a handler shows no dead button.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A direct link to /page#target stayed at the top: the target renders with the
lazy page, after the router scrolled up. PageHeader now scrolls to it below
the sticky header, focus never scrolls, and POP no longer scrolls to top.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Route render, unrecovered chunk and query failure screens now show the id
a user quotes to support, and the render diagnostic records the same id as
correlation_id. The route failure page also offers a reload.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Every non-input save failure became "unavailable" under the "review the entered
information" summary, with no sign-in button. useAppForm now reports
reauth-required, forbidden and retry-later with the failure, and
FormFailureStatus shows each one's copy and action outside ErrorSummary.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A save whose response was lost minted a new key on the next submit, and the
screen let the user declare "not applied" without evidence. The same canonical
input now reuses the unknown admission's intent; the screen offers "send the
same request again" and a list refresh link instead.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A disabled query (no data, no error, not fetching) fell through
deriveAsyncState to "empty", so AsyncSurface rendered the
"no items" copy before the query had even started.
- AsyncState.base gains "idle" for "not started / waiting on a
precondition". A completed empty result (`[]`, `""`, `null`) stays
"empty"; a real first load stays "initial-loading".
- AsyncSurface renders an optional `idle` slot for idle, else nothing
(no skeleton, no aria-busy, no empty copy, no children).
Consumer-facing: AsyncState["base"] union adds "idle" (additive);
AsyncSurface gains an optional `idle` prop. No in-repo exhaustive
switch over base needed changes.
RED (before the fix, node scripts/run-vitest.ts on the two files):
application-query-bridge > disabled query: expected 'empty' to be 'idle'
async-surface > derives base state 4 ({}): expected 'empty' to be 'idle'
async-surface > idle renders neither loading nor empty:
toBeEmptyDOMElement() received the empty-copy section
Tests 3 failed | 25 passed (pins for first load, [] and null empty passed)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Route-level loading (Suspense fallback, context gateway, chunk check) now
renders LoadingSurface, which gains optional visible copy; route-level
auth-required, integration-required, invalid-address, disabled-feature,
failure and 404 screens render StatusPage, which gains an optional
`surface` marker and children slot. Visible copy, h1 headings, data-surface
markers and alerts are unchanged; the 404 home link is a router link.
The unlabelled context gateway loading now has an accessible name.
Session buttons in the shell, the auth-required screen and the auth example
share useSessionAction: one pending/failed state and sign-in returns to the
current URL including its hash (the auth example dropped the hash).
PageActionBar keys actions by position so a pending label does not remount
the pressed button.
The home and platform overview release loaders now handle a rejected
summary instead of showing "checking" forever.
Pinned first with tests/component/route-status-surfaces.test.tsx (RED: auth
example hash and both loaders; loading, auth-required, shell session and
404 link characterized before the change), plus the lane gates.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>