4ada84e1ec0a8219ea480276eb3eb715199889a5
698
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
4ada84e1ec |
fix(registry): 맞는 변경이 없는 breaking 증거 행을 실패로 막는다 (0929/07-01)
문제
check:registries는 증거 행이 지금 diff의 어느 breaking 변경을 설명하는지
보지 않는다. 증거 파일 17건 중 14건이 지금 diff의 어떤 changeId와도 맞지
않았다(예: FE-REG-ERROR:QUERY_CACHE_FAILURE:telemetryEvent:field-changed,
그 필드는 07-04 이후 없다). update:registry-baseline은 기준선을 새로 찍어도
증거 행을 그대로 두므로 오래된 행이 계속 쌓인다. 5e6be9a가 리뷰 개선
(1)(증거를 값에 묶기)만 했고 (2)·(3)이 남았다.
고른 방법 (2026-11-03 결정)
- (2) validateBreakingEvidence가 지금 diff의 breaking 변경과 changeId가
맞지 않는 증거 행마다 "stale breaking evidence <changeId>: ..."로
실패한다. 메시지에 지울 행과 update:registry-baseline이 지운다는 사실을
적는다. breaking이 아닌 변경(behavior-change 등)과 맞는 행도 오래된
행으로 본다. 증거는 breaking 변경에만 쓰기 때문이다.
- (3) update:registry-baseline이 승인 파일을 쓴 뒤 증거 행을 모두 지우고,
지운 changeId를 출력한다. 새 기준선은 지금 스냅샷이라 증거가 설명하던
변경을 모두 흡수한다. 남은 행은 어떤 변경과도 맞지 않아 (2)에서
실패한다. 이력 파일로 옮기지 않는다. git 이력이 이력이다.
증거 파일은 쓰기 전에 읽어서, 파일이 없으면 아무것도 바꾸지 않고 멈춘다.
- 이번 검사에 걸리는 오래된 14건을 지웠다. 지금 diff와 맞는 3건
(REFERENCE_RESOURCE_DETAIL.path, CACHE_INVALIDATION_PULSE backend·
valueCodec)은 남겼다.
- docs/operations/ci-quality-gates.md 증거 안내에 두 동작을 적었다.
이유: 목록을 출력만 하면 아무도 보지 않는다. 정리가 자동이라 실패해도
고치는 비용이 작다.
버린 대안
- 오래된 행을 목록으로 출력만 하기: 위 이유.
- 지운 행을 이력 파일로 옮기기: 파일이 하나 늘고, git 이력과 같은 사실의
사본이 된다.
위험·한계
- 다운스트림이 이 검사를 동기화하면 자기 증거 파일의 오래된 행 때문에
게이트가 실패한다. 실패 메시지가 행을 나열하므로 지우거나
update:registry-baseline을 한 번 돌리면 된다. CHANGELOG [계약] 행이
필요하다.
- 같은 changeId가 증거 파일에 두 번 있으면 지금처럼 뒤의 행만 쓰고,
앞의 행은 오래된 행으로 걸리지 않는다. 이번 범위 밖이다.
검증
- RED(수정 전): registry-compatibility.test.ts 새 사례 "fails on evidence
rows that explain no breaking change of the current diff"가
"expected [] to deeply equal [ …(2) ]"로 실패. registry-governance.test.ts
새 사례 "deletes the evidence rows the new baseline explains"가
"expected { schemaVersion: 1, changes: [ …(1) ] } to deeply equal
{ schemaVersion: 1, changes: [] }"로 실패.
- GREEN: 두 파일 25/25 통과. 오래된 행을 지우기 전 check-registries가
"stale breaking evidence ..." 14줄로 실패(rc=1), 지운 뒤 "11 registries
PASS"(rc=0).
- 회귀: registry-compatibility·registry-governance·second-api-feature-
registries·release-artifacts 55/55 통과. compatibility fixtures 11 PASS.
verify-documentation-readiness PASS_SCOPED. tsc node·test rc=0, 바꾼
파일 eslint rc=0.
- 미실행: check:architecture, test:sample-removal(pnpm 필요). 제거 드릴은
update:registry-baseline 뒤 check:registries를 돌리므로 (3)이 있어야
통과한다.
Refs: docs/reviews/2026-09-29-maturity-review/07-contracts.md
|
||
|
|
61baf96682 |
fix(docs): 입구 문서를 실제 src 폴더 9개와 규칙 이름에 맞추고 검사한다 (14-03)
문제: src/ 최상위 폴더는 adapters application apps bootstrap contexts
contracts features platform presentation 9개다. layers.md 표,
frontend-application-foundation.md 목록, overview.md 그림, README 구조
그림은 src/platform을 한 번도 적지 않았고 apps·contexts는 금지 간선
설명에만 나왔다. 대신 없는 최상위 domain을 계층으로 그렸다.
contract-ownership.md의 배치 규칙에는 src/platform 선택지가 없었다.
layers.md는 "표와 규칙이 어긋날 수 없다"고 적었지만
.dependency-cruiser.json 규칙 31개 중 25개의 이름이 없었다.
게이트는 금지 간선만 막으므로, 허용되지만 틀린 자리(최상위 domain 신설,
제품 중립 primitive를 contracts에 두기)를 문서로 막을 수 없었다.
고른 방법: 리뷰의 (B)안. 문서를 코드에 맞추고 verify:documentation에
대조 검사를 더한다.
- layers.md: 9개 폴더 표(폴더 | 소유)를 정본으로 두고, 금지 간선 글머리
목록을 규칙 31개 표(규칙 이름 | 적용 대상 | 금지)로 바꾼다. domain은
기능 안의 계층으로 옮기고 "최상위 domain 폴더는 지금 없고, 만들면
domain-is-framework-neutral이 이미 적용된다"고 적는다. 보증 문장은
실제로 검사하는 범위로 줄인다. kernel 절과 배럴 절은 그대로 둔다.
- README·overview·foundation: layers.md 표의 설명을 한 글자도 바꾸지
않고 "`src/<폴더>` — <설명>" 목록으로 싣는다. 그림은 실제 import
방향(presentation -> application -> contracts -> platform,
apps -> contexts -> features)으로 다시 그린다.
- contract-ownership.md: src/platform 선택지와 contracts와의 차이,
platform-kernel-is-product-neutral을 적는다.
- verify-documentation-readiness.ts: 폴더 목록은 src/를 읽고, 규칙 목록은
.dependency-cruiser.json을 읽는다. layers.md 표에 행이 없는 폴더,
나머지 세 문서에서 설명이 다른 폴더, 네 문서가 적은 없는 최상위
src 폴더, layers.md에 없는 규칙 이름이 있으면 실패한다. 결과는
documentation-review.json의 sourceStructure로 남긴다(스키마는 필드
하나를 더한다).
버린 대안: (A) 문서만 고치기 — 규칙이나 폴더가 늘면 다시 어긋난다.
(C) layers.md를 .dependency-cruiser.json에서 생성 — 사람이 읽는 설명을
넣기 어렵다. 네 문서 모두에 규칙 31개를 싣는 것 — 같은 목록이 네 벌이
되어 어긋날 곳만 늘어난다. 규칙 표는 layers.md 한 곳에 둔다.
위험·한계:
- 검사는 규칙 이름이 있는지만 본다. 행의 설명이 규칙과 맞는지는 보지
않는다(문서에도 그렇게 적었다).
- 없는 폴더 검사는 "src/<이름>" 꼴만 잡는다. "domain"처럼 src/ 없이
계층 이름만 쓰는 것은 잡지 못한다.
- README·overview·foundation에는 같은 9줄이 복사되어 있다. 설명을 바꾸면
네 곳을 함께 고쳐야 하고, 검사가 그것을 강제한다.
- .dependency-cruiser.json 주석의 "like src/domain"(feature-domain 규칙)은
코드 주석이라 이번 범위 밖이다.
- 문서 drift 전반(경로·줄 번호, 14-05)은 다루지 않는다.
검증:
- RED: 새 검사를 기준 커밋(
|
||
|
|
855d22ac1b |
fix(i18n): 화면 문구 literal 검사를 ESLint 선택자로 옮긴다 (0929/08-02)
문제: `check:i18n`은 화면 파일 전체에 `/[가-힣]/`를 돌린다. 한국어 주석
한 줄에 실패하고, 영어 JSX 문구와 영어 접근성 이름은 통과한다. 샘플
화면에도 영어 literal이 이미 있었다(목록 h1 "Reference feature",
`limit {n}`, 목록 aria-label, 상세 "DetailPage"·"Resource ID"·"Created",
폼·상태 eyebrow). ko-KR 사용자에게 영어 문구와 스크린리더 이름이 섞인다.
고른 방법: (B) 문구 literal 검사를 ESLint `no-restricted-syntax` 선택자로
옮긴다(`eslint.config.ts`의 `screenTextSelectors`).
- 대상: 글자(`\p{L}`)가 든 `JSXText`, 표시·접근성 속성(`aria-label`,
`aria-description`, `aria-roledescription`, `aria-valuetext`,
`aria-placeholder`, `title`, `placeholder`, `alt`, `label`)의 문자열
literal, 그리고 `{"..."}` 형태의 같은 literal. 주석은 AST에 없어 빠진다.
구두점·숫자만 있는 문구는 통과한다.
- 범위(4.3절 "화면 코드"): 지난 `check:i18n`과 같은 폴더다. 공통 UI
폴더와 `src/features/*/presentation`. 컴포넌트 갤러리
`src/presentation/examples`는 지금처럼 뺀다. stories(`*.stories.tsx`)는
workshop 코드라 뺀다. 테스트는 이 폴더 밖이라 대상이 아니다.
- 이 항목은 일반 `no-restricted-syntax` 목록을 대체하므로 FE-OC-019
선택자(raw HTML, script 생성)를 함께 싣는다.
- `check:i18n`에는 catalog parity와 raw backend 메시지 검사만 남긴다.
raw HTML은 원래 전역 FE-OC-019 ESLint 규칙이 거절한다.
- `check:i18n:fixture`는 ESLint Node API로 같은 규칙을 fixture 트리에도
돌린다. forbidden 파일은 하나하나 거절돼야 하고(아니면 종료 코드 2),
새 `tests/fixtures/i18n/allowed` 트리(한국어 주석, 구두점, catalog
문구)는 통과해야 한다(거절되면 종료 코드 2). 게이트 기대값(종료 1,
"I18n contract failed:")은 그대로다.
- fixture 추가: allowed `korean-comment.tsx`, forbidden
`english-jsx-text.tsx`, `english-accessible-name.tsx`.
- 샘플의 영어 literal 11곳을 catalog로 옮겼다. 새 키 10개
(`reference.list.title`·`filterLimit`·`filterTags`·`resources`,
`reference.detail.eyebrow`·`titlePending`·`resourceId`·`createdAt`,
`reference.form.eyebrow`, `reference.status.eyebrow`). en-US 값은
예전 영어 문구 그대로라 en-US 화면은 바뀌지 않는다. ko-KR 화면은 한국어가
된다.
버린 대안:
- (A) 현 상태: 두 제품이 각각 막히거나 스크립트를 고쳤다.
- (C) "행동·상태 문구"만 정규식으로 고르는 제품 정책: 한국어 문장 목록에
기대 영어를 못 잡고, 템플릿 기본값으로 쓰기에 제품 특화다.
ESLint 설정은 제품이 자기 규칙으로 덮어쓸 수 있는 자리다(한 locale 제품,
고유명사 허용).
위험·한계:
- 식 안에서 만든 문구는 보지 못한다. template literal, 삼항식, 객체
prop(`heading.title` 같은 것)이 그렇다. 샘플의 이런 문구는 손으로
옮겼고, `reference-page.test.tsx`가 ko-KR main 영역을 catalog·데이터
밖 라틴 문자로 검사해 그 빈 곳을 샘플에서만 막는다.
- 고유명사·브랜드 이름도 걸린다. 제품이 선택자를 덮어쓰거나 그 줄에
`eslint-disable-next-line`을 쓴다.
- ko-KR route 제목(`route.REFERENCE_RESOURCE_*`)은 catalog 안의 영어라
그대로 뒀다(라우트 제목 정리는 0929/08-06 몫).
- `tests/e2e/reference-form.spec.ts`의 ko-KR 목록 h1 기대값을 "참조
기능"으로 바꿨다. e2e는 이 worktree에서 돌리지 않았다(webServer가
pnpm build를 부른다).
- 시각 골든(`tests/visual`)은 /examples/ui·states·platform만 찍는다.
샘플 화면과 nav 문구는 바뀌지 않아 골든 영향이 없다고 본다(미실행).
검증:
- RED(수정 전):
- E1 한글 주석 변이: `node scripts/check-i18n.ts` -> "hardcoded common
user-facing locale literal in .../reference-resource-status-page.tsx",
exit 1
- E1b 영어 JSX 문구 변이: `check-i18n.ts` PASS exit 0, `eslint` exit 0
- `check-i18n.ts --fixture` -> "I18n fixture was not rejected:
english-accessible-name.tsx, english-jsx-text.tsx", exit 2
- 새 ko-KR main 테스트: "limit 5 · tags ..." 가 남아 실패
- GREEN(수정 후):
- E1 변이: `check-i18n.ts` PASS, `eslint` exit 0
- E1b 변이: `eslint` -> 42:13 no-restricted-syntax, exit 1
- `check-i18n.ts` PASS(224 keys), `--fixture` -> forbidden 7개 모두
거절, "I18n contract failed:", exit 1. allowed에 영어 문구를 넣으면
"I18n allowed fixture was rejected", exit 2
- ko-KR main 테스트 통과
- `npx eslint src scripts tests recipes .storybook ... --max-warnings=0`
통과, app·test·node 타입 검사 통과
- vitest: tests/unit + tests/component 209 files 2725 tests,
tests/features 등 25 files 141 tests 통과
- `check-registries.ts` PASS, `check-ci-contract.ts` PASS,
`verify-documentation-readiness.ts` PASS_SCOPED
Refs: docs/reviews/2026-09-29-maturity-review/08-presentation.md 08-02, 4.3
|
||
|
|
ff33d58e95 |
feat(i18n): 문구 보간 파라미터를 catalog의 {이름}에서 만든다 (0929/08-03)
문제: 보간 파라미터 타입이 플랫폼 파일의 닫힌 목록 `MessageParameters`에만
있다. 목록에 없는 기능 키는 `[parameters?: never]`가 된다. 그래서
`formatMessage("ko-KR", "reference.list.resultCount")`는 타입 검사를
통과하고 실행하면 대체 문구를 돌려주며, `{ count: 1 }`을 넣으면 TS2345로
거절된다. 샘플은 타입 없는 `resolveMessage`로 우회했고, tech-log는 템플릿
파일에 키 11개를 넣었다.
고른 방법: (B) catalog가 `as const`이므로 ko-KR 문자열 literal의
`{이름}`에서 `MessageArguments<Key>`를 만든다. 값 타입은
`string | number`다. 값 타입을 좁히고 싶은 키만 `MessageParameters`로
덮어쓴다. 덮어쓰기는 catalog 파라미터와 교집합이라 좁히기만 한다. 덮어쓴
항목이 catalog 문자열과 어긋나도 catalog의 자리표시자는 계속 필수다.
`ParameterlessMessageKey`도 "자리표시자가 없는 키"로 같은 규칙에서
만든다. 기존 덮어쓰기 8개는 값 타입을 좁히므로 그대로 둔다.
새 개념이 없고, 기능이 템플릿 파일을 고치지 않는다.
버린 대안: (C) 기능 모듈이 파라미터 타입을 따로 선언하고 설치 조립이
교집합을 만든다. 값 타입을 정확히 쓸 수 있지만 catalog와 선언을 따로
맞춰야 한다.
위험·한계:
- 값 타입이 `string | number`로 넓다. 좁히려면 `MessageParameters`에
덮어쓴다.
- 자리표시자는 ko-KR 문자열에서 읽는다. 다른 locale과의 일치는
`tests/unit/i18n-contract.test.ts`의 parity 검사가 지킨다.
- ICU 복수형·select처럼 `{이름}`으로 표현하지 못하는 문구는 다루지
않는다(VD-06 재검토 조건).
- 타입 검사 비용(`tsc -p tsconfig.app.json --extendedDiagnostics`):
Types 287,440 -> 289,911(+0.9%), Instantiations 721,217 -> 748,663
(+3.8%). 실행 시간은 load average 9~21에서 전·후 모두 1.0~2.6초로
흔들려 차이를 구분할 수 없었다.
- 기능 키 검사(`tests/features/reference-feature/feature-module.test.ts`)는
샘플과 함께 지워지도록 샘플 테스트 폴더에 두었다. 플랫폼 fixture는
샘플 키에 기대지 않는다.
검증:
- RED: `npx tsc -p tsconfig.test.json --noEmit`
feature-module.test.ts(23,5): error TS2578: Unused '@ts-expect-error'
feature-module.test.ts(26,60): error TS2345: Argument of type
'{ count: number; }' is not assignable to parameter of type 'undefined'.
- GREEN: 같은 명령 오류 0. app·node·recipes 타입 검사 통과.
- `check:types:fixture:i18n-params` fixture: 기존 3줄은 TS2554/TS2345로
계속 실패하고, 더한 덮어쓰기 좁힘 줄은 TS2322로 실패한다.
- vitest: tests/features/reference-feature, i18n-contract,
locale-platform 19 files 97 tests 통과.
- 샘플 목록 화면이 타입 있는 `message()`로 결과 수를 그린다.
Refs: docs/reviews/2026-09-29-maturity-review/08-presentation.md 08-03
|
||
|
|
d6e4e51688 |
fix(contexts): 계약에 없는 라우트 핸들을 라우트 적재 때 막는다 (09-06)
문제: context gateway는 적재한 라우트의 handle `routeId`가 가리키는
등록 라우트를 그린다. `context-routes.ts`가 기능 계약에 없는 route id를
handle에 실으면(오타, 계약에서 지운 라우트) 적재는 성공하고, 그 URL을
그릴 때 context 경계 실패 화면이 된다. 7139c7c가 리뷰의 (1)(2)를 했고
(3) "핸들의 route id가 레지스트리에 있는가"는 설계 선택으로 남겼다.
고른 방법: 적재 때 검사한다. `defineBoundedContextModule`이
`route.loadRoutes`를 감싸, 적재한 각 라우트의 handle `routeId`가 그
context 기능들의 계약 라우트 id에 없으면 TypeError로 실패한다. 메시지에
route id, context id, 기능 id를 담는다. handle에 `routeId`가 없어도
실패한다(gateway는 그 라우트를 NOT_FOUND로 그린다).
- 모든 context가 이 함수를 거치므로(생성된 product-context-index) 모든
context에 걸린다. 모든 context의 라우트를 적재하는 기존 단위 테스트
(tests/unit/route-runtime.test.ts)가 개발 단계에서 잡는다.
- 적재 실패는 09-09(
|
||
|
|
1196b86426 |
fix(realtime): stream 마감 실패를 13.1의 kind로 보고한다 (04-02)
문제: stream coordinator는 effect 마감 초과를 IDLE_TIMEOUT/APPLY로, recovery 마감 초과를 IDLE_TIMEOUT/RECOVER로, close drain 초과를 IDLE_TIMEOUT/CLOSE로 보고한다. 설계 13.1에서 IDLE_TIMEOUT은 전송 idle(heartbeat/byte deadline -> close + bounded reconnect)이다. reconnect 관측(RUN_ENDED failureKind)에는 operation이 없어서 운영에서 "서버가 조용해짐"과 "우리 effect가 멈춤"을 failureKind로 나눌 수 없다. 5b3f5b0은 13.1에 두 뜻을 적기만 했다(리뷰의 (b)). 고른 방법: 리뷰의 (a). kind만 바꾸고 retryable:false, DRAINING 유지, resume token 폐기는 그대로 둔다. - effect 마감: APPLY_FAILED/APPLY. 13.1의 "feature effect 실패"이고, WebSocket 연결도 자기 apply 마감을 APPLY_FAILED로 보고한다. - recovery 마감: PROVIDER_UNAVAILABLE/RECOVER. recovery source가 제때 답하지 않은 것이다. recovery가 throw한 경우와 같은 kind다. - close drain 마감: PROVIDER_UNAVAILABLE/CLOSE. reconnect coordinator가 drain 상한 초과를 PROVIDER_UNAVAILABLE로 보고하는 것과 맞춘다. - 관측 reason도 같은 kind로 바꾼다. - 13.1 표는 IDLE_TIMEOUT 행에서 stream coordinator 설명을 빼고, APPLY_FAILED·PROVIDER_UNAVAILABLE 행에 마감 경우를 적는다. VD-28의 같은 설명도 고친다. 이 템플릿으로 운영 중인 제품이 아직 없어서 관측 값을 바꾸는 비용이 지금 가장 작다. 버린 대안: (b) 문서만 고친다. 5b3f5b0이 한 것이고, 관측에서는 여전히 구분되지 않는다. close 마감에 CLOSED를 쓰는 것도 버렸다. 아직 DRAINING인데 "닫힘"으로 읽힌다. 위험·한계: - 공개로 관측되는 값이 바뀐다. stream coordinator 결과의 kind와 RealtimeObservation.reason에서 IDLE_TIMEOUT을 보던 조합 코드는 APPLY_FAILED/PROVIDER_UNAVAILABLE을 봐야 한다. repo 안에 그런 소비자는 없다. - live-poll handoff coordinator의 quiescence·checkpoint·close 마감은 여전히 IDLE_TIMEOUT이다. 결정 범위(stream coordinator)를 지켰다. 13.1 IDLE_TIMEOUT 행에 handoff 마감만 남겨 적었다. - realtime 레시피 번들 gzip이 40,897 B에서 40,902 B로 늘어 예산 40,900 B를 2 B 넘는다. "PROVIDER_UNAVAILABLE"이 "IDLE_TIMEOUT"보다 8자 길어 3곳에서 원본이 24 B 늘었다. 예산은 올리지 않았다. check-optional-recipes가 REFERENCE_RUNTIME_BUNDLE_BUDGET_EXCEEDED로 실패한다. 검증: - RED: 기대값을 먼저 바꾸고 stream-coordinator.test.ts 실행 -> 7 failed | 31 passed. 예: expected kind APPLY_FAILED, received IDLE_TIMEOUT. - GREEN: tests/unit/realtime 14 files, 230 passed. - tsc (tsconfig.app.json, tsconfig.test.json) 통과. 바꾼 두 파일 eslint 통과. verify-documentation-readiness PASS_SCOPED. - check-optional-recipes: realtime 40902 > 40900 실패(위험 참고). Refs: docs/reviews/2026-11-01-maturity-review/04-adapters-realtime.md 04-02 |
||
|
|
1fa5f3e237 |
fix(query)!: 제품 mutation 훅이 raw 입력을 받지 않게 한다 (1101/08-03)
문제: useApplicationMutation이 BoundMutation과 함께 raw
LegacyMutationOptions({ execute, definitionId })도 공개 overload로
받는다. raw 쓰기는 intent가 없어 Idempotency-Key 없이 나가고, scope
세대 확인과 측정 profile을 건너뛴다. 결과 불명 뒤 resendUnknownEffect()는
null이라 샘플 폼을 복사하면 "같은 요청으로 다시 보내기"를 눌러도 아무
일이 없고 새 제출도 막힌다. tsc·eslint·depcruise 어느 것도 기능 코드의
raw 사용을 막지 않는다.
고른 방법(결정대로):
- 공개 useApplicationMutation에서 raw overload를 뺀다. 남은 공개
시그니처는 BoundMutation 하나다. 런타임 LEGACY 분기는 그대로 둔다.
- raw로 쓰인 테스트 24곳(3파일)은 tests/helpers/legacy-application-
query-harness.ts의 useLegacyApplicationMutation으로 옮긴다. harness는
명시적 cast로만 그 분기에 닿는다. 단언은 한 줄도 바꾸지 않았다.
- 타입 fixture: application-mutation-admission 테스트에 제품 훅에 raw
입력을 넘기는 @ts-expect-error를 둔다. raw overload가 돌아오면
tsconfig.test.json 검사가 TS2578로 실패한다.
- raw query({ queryKey, execute })는 남긴다. 먼저 확인했다: raw query는
세션이 바뀐 뒤 이전 사용자의 결과를 보이지 않는다. FENCED에서
ServerStateScopeProvider가 하위 트리를 내리고, READY는 이전
QueryClient를 비우고 세대 key로 새 QueryClient를 붙인 뒤에 온다. 늦게
온 이전 응답은 버려진 client에 쓰인다. 이 동작을
server-state-generation-provider 테스트로 고정했고, 생성 저장소가 같은
client를 비우지 않고 다시 쓰게 바꾸면 이 테스트가 실패한다(변이 확인).
시그니처 JSDoc에 "scope·측정 profile 없이 도는 읽기 경로"와 provider
밖에서는 훅이 막지 않는다는 위험을 적었다.
- typescript-state-and-data-flow.md 4.3의 raw 예시를 bound 정의로 바꾼다.
버린 대안: raw query까지 제거 — 다운스트림 memento의 raw query 12곳이
깨지는데 읽기는 다시 보내도 부작용이 없어 얻는 안전이 작다. 현상 유지 —
쓰기 경로의 중복 생성과 동작하지 않는 재전송이 남는다. 런타임 LEGACY
분기 제거 — legacy 전용 테스트 4건의 단언이 바뀌어 "같은 단언 유지"를
못 지킨다. 별도 tests/fixtures/typecheck + CI 명령 — package.json,
gates.json, contract-baseline.json, 명령 수를 고정한 테스트까지 바꾸고
다른 수정과 baseline 해시가 충돌한다. 같은 tsc 검사를 기존
check:types:test 게이트가 돈다.
위험·한계: 공개 계약 변경(BREAKING). 런타임에는 raw 분기가 남아 cast로
여전히 닿는다(타입으로만 막음). LegacyMutationOptions 타입은 harness가
쓰도록 application-query.ts에서 export한다(배럴에는 없음). raw query는
ServerStateGenerationProvider 밖에서 쓰면 세션 보호가 없다.
검증:
- RED: 원래 훅(raw overload 있음)으로 tsc -p tsconfig.test.json →
"error TS2578: Unused '@ts-expect-error' directive."
- GREEN: tsc app·test·node 통과. tests/component 35 files 229 tests
통과(옮긴 테스트 포함). tests/unit·component·features·contract·
runtime-schema·architecture·scripts·integration(security-followup-
archive 제외, pnpm 사용) 256 files 중 3 files 4 tests가 부하(load
avg 32)에서 실패했고 세 파일을 3회 다시 돌려 모두 통과(78/78). eslint
(바꾼 파일) 통과.
- 다운스트림(읽기만): memento 10곳, tech-log 34곳 모두 bound. 깨지는
제품 호출 0곳. 두 repo의 tests/component 템플릿 소유 테스트 3파일은
raw 호출이 있어 harness와 함께 동기화해야 한다.
BREAKING CHANGE: useApplicationMutation이 raw { execute, definitionId }
입력을 받지 않는다. BoundMutation(definitionId, definitionVersion,
operationId, requiresIdempotencyKey, owner, duplicatePolicy, scope,
invalidate, execute(input, { signal, intent }))을 넘긴다. scope는
useServerStateScope()에서 얻는다.
Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-03
|
||
|
|
849d000342 |
fix(http): 결과 불명 쓰기에 보낸 요청 id를 지원 참조로 싣는다 (0929/03-04)
문제: 바인딩은 서버가 돌려준 x-correlation-id만 AppFailure.requestId로 싣는다. 마감 초과·연결 끊김(TRANSPORT_FAILURE)과 취소에는 응답이 없고, 헤더를 노출하지 않는 서버·게이트웨이의 504에도 반사값이 없다. 실행기는 보낸 id를 알지만 observation(기본 sink 없는 메모리 diagnostics)에만 넣었다. 그래서 e54fbf2(0929/08-04)가 결과 불명 화면에 더한 "지원 참조" 줄이 가장 흔한 결과 불명 경우(마감 초과)에 비어 있었다. 요청은 id를 싣고 서버 로그에 남는데도 지원 담당은 시각·사용자로 찾아야 했다. 고른 방법: 리뷰의 최소 개선 방향 ①을 한다. ②(화면)는 e54fbf2가 이미 했다. - V3 실행 결과(HttpExecutionOutcome)의 모든 가지에 선택 필드 sentRequestId를 더한다. finish()가 요청에 넣은 x-correlation-id를 싣는다. observation의 correlationId와 같은 값이다. - 바인딩은 반사값이 없으면 sentRequestId를 requestId로 쓴다. - 런북 5.2-6과 백엔드 계약 5절에 "반사값이 없으면 보낸 값" 한 줄씩. 버린 대안: metadata 없는 가지에만 필드 두기 — 반사 헤더 없는 504는 metadata가 있어 빠진다. 바인딩이 id를 만들어 실행기에 넘기기 — 실행기가 이미 id를 만들고 재시도에 공유하므로 생성 지점이 둘이 된다. 위험·한계: 공개 결과 타입에 선택 필드 하나가 붙는다(추가만). 요청을 조립하기 전에 끝난 실패(자격 증명 없음, 입력 거절)와 id 생성 실패(보안 컨텍스트 아님)에는 값이 없다. 서버가 id를 바꿔 쓰면 반사값을 우선하므로 두 값이 다를 수 있다. telemetry에는 넣지 않는다(VD-07). 초기 JS gzip은 이 커밋 단독으로 재지 않았다(두 커밋 뒤 함께 잼). 검증: - RED: reference-production-vertical에 새 테스트. REQUEST_TIMEOUT_MS 200, MSW가 abort까지 응답하지 않는다. 수정 전 "변경 결과를 확인할 수 없습니다."는 보이지만 "Unable to find an element with the text: 지원 참조: 29d7f444-…"로 실패. - GREEN: 같은 테스트 통과(화면 식별자 = 요청 헤더 x-correlation-id). tests/features·unit·integration·component 242 files 2975 tests, tests/contract·runtime-schema·architecture 13 files 109 tests 통과. tsc app·test, eslint(바꾼 파일), verify-documentation-readiness, check-adapter-inventory, check-registries 통과. Refs: docs/reviews/2026-09-29-maturity-review/03-adapters-http-state.md 03-04 |
||
|
|
c5f87aaef5 |
fix(browser-transfer): part 발급 401/403을 NONE으로 낸다 (0929/01-01)
문제: part 발급(BFF)이 401/403으로 거절하면 upload()가
{PERMISSION_DENIED, UPLOAD_PART, retryable:false, RESUME}을 돌려준다.
세션 만료나 권한 회수라서 재인증 전에는 다시 불러도 같은 거절이다.
그런데 RESUME을 믿는 화면은 "다시 시도"를 띄우고, 다시 부르면 파일
전체를 재해시한 뒤 같은 거절을 받는다. 지난 수정(
|
||
|
|
7a70cea631 |
docs(review): 결정 대기 항목의 결정과 이유를 적는다
문제: 13.5절의 건너뛴 20건과 5절의 확장 지점 범위가 결정을 기다리고 있었다. 결정이 없어서 0929/08-02·08-03, 13-01 같은 항목이 계속 미뤄졌다. 방법: 사용자가 결정을 오케스트레이터에게 맡겼다. 14절에 항목마다 결정, 이유, 버린 대안을 적었다. 레지스트리 기준선 재승인도 이 위임으로 한다는 것을 함께 적었다. 처리 결과는 구현을 합친 뒤 14.2절에 적는다. 위험: 08-03(raw mutation 제거)과 0929/05-03(recipe port 통합)은 다운스트림 코드를 깨는 공개 계약 변경이다. CHANGELOG에 이행 방법을 함께 적어야 한다. 검증: 문서만 바꿨다. 결정 근거는 각 영역 문서의 최소 개선 방향·대안 비교와 지난밤 에이전트 보고에서 가져왔다. |
||
|
|
d9366b73e3 |
docs(review): 개선 순서 2와 P2·P3 조치 현황, 건너뛴 것과 이유를 적는다
문제: 리뷰 README 13절은 개선 순서 1까지만 적혀 있었다. 밤사이 고친
ID와 커밋, 건너뛴 항목과 이유, 새로 찾은 결함, 예산 여유가 에이전트
보고에만 있었다. CHANGELOG 알려진 제한에는 이미 해결된 두 줄(규모
기준선이 15-01 전 측정, 좁은 화면 골든 미갱신)이 남아 있었고, 규모 근거
문장이 옛 수치를 적고 있었다.
방법: README 13.3~13.8에 개선 순서 2, 영역별 고친 ID와 커밋, 결정이
필요한 건너뛴 항목 20줄, 새 발견(여러 페이지 OPFS purge), 예산 여유,
마지막 게이트를 더했다. 영역 문서는 리뷰 시점 기록이라 고치지 않았다.
CHANGELOG는 해결된 두 줄을 지우고 OPFS purge 제한을 더했다.
feature-shape-ceilings.json의 Initial/Lazy JavaScript 수치를
|
||
|
|
e4ace51099 |
fix(features): 기능이 하나도 없을 때도 타입 검사와 커버리지가 통과하게 한다 (15-01)
문제: 샘플 제거 드릴(test:sample-removal)이 reference feature를 지우면 설치된 기능이 0개가 된다. 15-01 이후 그 상태에서 기능 기여 타입이 never가 되어 installed-feature-adapters.ts와 테스트 2개가 타입 검사에서 실패했다. features.load는 기능 테스트로만 검증되고 있어서, 기능 테스트가 같이 지워지면 create-application.ts 커버리지가 90% 아래로 떨어졌다. 드릴 사본에 README.md·CHANGELOG.md가 없어 문서 테스트 2개도 실패했다. 방법: never일 때도 통과하는 넓은 타입으로 받아서 읽는다(as 단언 없이 대입). features.load는 가짜 로더로 플랫폼 테스트를 추가했다(한 번만 적재, 남의 input 거부, 실패 후 재시도). 문서 테스트 2개는 드릴 제외 목록에 넣었다. 드릴 사본에 문서를 복사하는 안은 버렸다. 기능 제거와 무관한 파일이 사본 목록에 들어간다. 위험: 넓힌 타입은 기여 타입이 바뀌어도 featureId 검사 부분은 잡지 못한다. 그 검사는 실행 시 TypeError로 남아 있다. 검증: tsc -p tsconfig.test.json 통과, check:types 통과, 관련 단위 테스트 20/20 통과. 드릴은 고치기 전 실행에서 coverage PASS를 확인했고 타입 오류 2건이 남아 있었다. 그 2건을 고친 뒤 드릴 전체는 다시 돌리지 않았다. |
||
|
|
9333595ce5 |
fix(scale): 기능 복사본이 외부 패키지를 고정하고 선언하게 한다 (1101/07-04)
문제: 1101/07-04 이후 조립 단계는 reference feature 밖의 TEMPLATE_FIXTURE 기여를 거부한다. 규모 측정 생성기는 reference feature를 그대로 복사하므로 +25/+100 측정이 ContractContributionError로 멈췄고, 기준선 source가 작업 트리 SHA(2be973a)로 남아 있었다. 방법: renameReferenceFeature가 복사본의 source를 EXTERNAL_PACKAGE (@feature-shape/<id>)로 바꾸고, 같은 패키지를 contracts.contractPackages에도 선언한다. 제품 기능이 실제로 거치는 경로와 같다. 조립 검사에 측정용 예외를 두는 안은 버렸다. 측정이 제품과 다른 경로를 재게 된다. 위험: reference feature의 source 블록 형태가 바뀌면 정규식이 맞지 않는다. 그때는 조립이 같은 오류로 실패하므로 조용히 틀린 값을 기록하지 않는다. 검증: node scripts/scale/measure-feature-shape-growth.ts --sizes=0,25,100 --repeats=2 --write 성공(초기 JS +0: 203,816 B, +25: 219,508 B, +100: 264,841 B), tests/unit/feature-shape-growth.test.ts 6/6 통과. |
||
|
|
373b27b09c |
test(visual): 야간 수정 뒤 시각 골든 5장을 고정 글꼴로 다시 찍는다
입력란 테두리 토큰(12-01), 좁은 화면 서랍(08-01), 제목 단계 크기(08-04), 한국어 단어 단위 줄바꿈(08-06)이 화면을 바꿨다. 허용치를 절대 50 px로 줄인 뒤(11-03) 기존 골든 5장이 모두 달랐다. fonts.conf로 글꼴을 고정한 상태(11-02)에서 test:visual:update로 다시 찍고 눈으로 확인했다. 서랍에 브랜드·테마 선택·세션 상태가 보이고, 상태 화면 제목이 굵어지고, 한국어가 단어 사이에서만 줄바꿈된다. 위험: 이 호스트의 Noto·Noto CJK·Liberation 패키지 버전으로 찍었다. 검증: test:visual 6 passed(글꼴 검사 포함). |
||
|
|
8763ed6ec0 |
docs(changelog): 나중에 합친 수정과 커밋 해시를 미출시 절에 더한다
미출시 절은 13·14·15 묶음을 합칠 때 썼다. 그 뒤 합친 01·02·03·04·06·08· 09·10·11·16 영역 수정이 빠져 있었고, 13-04 행은 worktree 커밋 해시를 가리켰다. [계약] 행 9개(업로드 Retry-After와 recovery, realtime 배럴 함수, base path, 조립 거절 2종, 전송 전 거절 분류, CI의 skip·todo 실패, 시각 허용치 50 px, file-transfer 레시피 예산 인상)와 그 밖의 수정 5줄을 더했다. 13-04 해시를 브랜치 커밋으로 고쳤다. 위험: 문서만 바뀐다. file-transfer 예산 인상은 소유자 검토 대상으로 적었다. 검증: 표와 목록의 커밋 해시를 `git log`와 대조했다. |
||
|
|
65ea208b99 |
fix(registry): pulse 키 breaking 증거에 after 값을 적는다 (05-01, 0929/07-01)
두 수정이 따로 고쳐져 합쳐지면서 레지스트리 검사가 실패했다. 05-01은 CACHE_INVALIDATION_PULSE 행의 backend·valueCodec을 바꾸고 breaking 증거 2건을 넣었다. 0929/07-01은 증거가 설명하는 값(after)을 필수로 바꿨다. 그래서 05-01의 증거 2건에 after가 없어 check-registries와 second-api-feature-registries 테스트가 실패했다. 두 증거에 diff의 새 값(`external`, `none`)을 after로 적었다. 증거 내용과 05-01의 변경은 그대로다. 위험: 증거 파일만 바뀐다. 검증: check-registries "11 registries PASS", second-api-feature-registries 테스트 통과. |
||
|
|
e54fbf2014 |
feat(presentation): 폼 저장 실패와 결과 불명 화면에 지원 참조를 보인다 (0929/08-04)
문제: 조회 실패는 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
|
||
|
|
b9a8a1a6c2 |
test(presentation): 건너뛰기 링크·로딩 발표·사이드바 이름을 테스트로 지킨다 (08-09)
문제: 접근성 기본 장치 일부를 지키는 테스트가 없었다. 리뷰 변이 중 M3(건너뛰기 링크 대상을 #content로), M4(LoadingSurface의 aria-live 제거), M5(상태 화면 제목을 <p>로), M6(사이드바 aria-label 제거)가 component 211개를 모두 통과했다. e2e의 axe는 WCAG 태그만 돌려 best-practice인 skip-link 규칙이 빠지고, 건너뛰기 링크를 누르는 e2e도 없었다. 고른 방법: 리뷰의 최소 개선 방향 그대로 단언을 더했다. - app-shell.test.tsx: 건너뛰기 링크 href가 main의 id와 같고, 이름 있는 complementary 안에 주요 탐색이 있다. - async-surface.test.tsx: LoadingSurface가 aria-busy와 aria-live="polite"를 가진다. - accessibility.spec.ts: 건너뛰기 링크 Enter 뒤 포커스가 main 안에 있다. - M5는 08-05 커밋의 제목 수준 테스트가 이미 잡는다. 버린 대안: axe에 best-practice 태그를 켜기 — 이번 범위 밖의 위반까지 한꺼번에 게이트가 된다. 위험·한계: 사이드바 이름 "사이드바"는 위치를 말하는 이름이라 리뷰가 관찰로 남겼다. 테스트는 지금 이름을 고정하므로 이름을 바꾸면 테스트도 같이 바꾼다. M3 변이 빌드에서 e2e는 공용 실행 잠금이 길게 잡혀 돌리지 못했다(component 테스트가 M3를 잡는다). 검증(테스트만 추가라 RED는 변이로 확인): - M3: app-shell landmarks 테스트 실패(1 failed | 221 passed) - M4: loading surface 테스트 실패(1 failed | 221 passed) - M5(state-surfaces.tsx 제목을 <p>로): 08-05 테스트 2건 실패 - M6: app-shell landmarks 테스트 실패(1 failed | 221 passed) - 변이 없음: tests/component 222/222, 새 e2e chromium·firefox·webkit 3/3. tsc test 통과, eslint 통과. Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-09 |
||
|
|
ad73e56476 |
fix(presentation): 예제 화면이 자기 언어를 ko-KR로 밝힌다 (08-07)
문제: LocaleProvider가 <html lang>을 선택한 locale로 바꾸는데, 예제 화면 4개는 의도적으로 catalog 밖이라 본문이 한국어 literal이다. en-US로 바꾸면 /examples/platform main의 한글 1,013자가 lang="en-US" 아래에 있어 스크린 리더가 영어 규칙으로 읽는다(WCAG 3.1.2). 고른 방법: 리뷰 대안 (B). 예제 화면 루트 section에 lang="ko-KR"을 준다. 예제를 catalog 밖에 둔 결정(VD-06, check-i18n 예외)은 그대로다. 버린 대안: (C) 예제 문구 번역 — 문구 수백 개이고 지울 수 있는 예제다. 예제 안에 중첩 LocaleProvider(ko-KR) — <html lang>을 전역으로 바꾼다. 위험·한계: 예제 안에서 디자인 시스템 컴포넌트가 catalog로 그리는 문구(접근 상태 화면, 오류 문구, 닫기 같은 접근성 이름)는 en-US에서 영어인데 ko-KR 구역 안에 놓인다. 화면 상태 갤러리에 몇 줄 있다. 한국어 본문 전체가 영어 규칙으로 읽히던 것보다 범위가 훨씬 작아 받아들였다. 예제를 번역하기로 하면 (C)로 간다. 눈에 보이는 화면 변화는 없다. 검증: - RED: i18n.spec.ts 새 테스트가 수정 전 chromium에서 실패 (Platform composition: lang Expected "ko-KR", Received ""). - GREEN: i18n·accessibility·ui-gallery·platform-overview e2e chromium·firefox·webkit 69/69 통과. tests/component 220/220, check-i18n PASS, tsc app 통과, eslint 통과. Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-07 |
||
|
|
dda153b25e |
feat(presentation): 상태 화면과 오류 요약이 제목 수준을 받는다 (08-05)
문제: 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 |
||
|
|
8ed5beb8fd |
fix(design-system): 한국어 문구가 단어 사이에서만 줄바꿈되게 한다 (08-06)
문제: 스타일·토큰 어디에도 word-break가 없어 브라우저 기본값으로
한국어를 음절마다 끊는다. 골든에 "마운 / 트", "계 / 속할"이 있고, 텍스트
200%에서 로그인 버튼이 "로그 / 인"으로 쪼개졌다. PRODUCT.md의 한국어
기본 원칙과 맞지 않고 모든 파생 서비스가 받는다.
고른 방법: base.css에 :lang(ko) { word-break: keep-all; overflow-wrap:
break-word; }를 둔다. :lang(ko)라 en-US 문서 안의 lang="ko-KR" 구역에도
적용된다. 버린 대안: 리뷰 제안의 overflow-wrap: anywhere — min-content
계산에도 끊을 자리를 더해, 공간이 좁은 flex 항목(헤더 버튼)이 줄어들며
라벨을 다시 쪼갠다. break-word는 넘칠 때만 끊는다. 긴 영문·코드
토큰은 기존 pages.css의 anywhere 두 곳이 그대로 받는다.
위험·한계: 화면이 바뀐다. 좁은 칸에서 줄 수가 늘 수 있다. 시각 골든은
오케스트레이터가 갱신한다. 실제 브라우저 "글자만 확대" 설정에서의
줄바꿈은 눈으로 확인하지 않았다.
검증:
- RED: typography.spec.ts 새 테스트가 수정 전 chromium에서 실패
(wordBreak "normal", overflowWrap "normal").
- GREEN: typography.spec.ts chromium·firefox·webkit 6/6 통과.
accessibility·i18n(320px 가로 넘침 포함)·ui-gallery·app-shell·
responsive·theme·compact-smoke·platform-overview chromium/compact
34/34 통과. check-design-system PASS. 시각 회귀는 미실행.
Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-06
|
||
|
|
6fc77bb71f |
fix(design-system): h2·h3·h4에 제목 단계 크기와 굵기를 준다 (08-04)
문제: theme.css가 넣는 Tailwind preflight가 제목의 크기·굵기를 본문으로 되돌린다. base.css는 h1 크기와 h2 줄 간격만 정해, 6개 라우트 모두 h2·h3이 16px/400으로 본문과 같았다. 구획을 훑어볼 수 없고, 제품마다 제목 크기를 따로 만들게 된다. 고른 방법: 리뷰의 최소 개선 방향대로 primitive에 --font-size-xl(1.25rem) ·--font-size-2xl(1.5rem)을 더하고, semantic에 제목 단계 토큰 (--font-size-heading-2/3/4, --font-weight-heading = semibold)을 둔 뒤 base.css에서 h2·h3·h4에 적용했다. 컴포넌트 제목(카드 h3, 상태 화면 h2)은 자기 수준의 기본 스타일을 그대로 받는다. 제품은 semantic 토큰 값만 바꿔 단계를 조정한다. 값(24/20/16px, 650)은 1.2배 안팎의 단계로 골랐다. 버린 대안: 컴포넌트마다 크기를 주기 — 같은 값이 여러 곳에 흩어진다. token-contract 필수 목록에 추가 — 다운스트림 토큰 파일이 바로 실패하고, 결과는 아래 e2e가 지킨다. 위험·한계: 화면이 바뀐다. 시각 골든(app-shell, state-surfaces 등)은 오케스트레이터가 갱신한다. 상태 화면이 카드(h3) 안에서 h2로 더 크게 보이는 문제는 08-05가 다룬다. 값 자체는 디자인 결정이라 바꿀 수 있다. 검증: - RED: 새 tests/e2e/typography.spec.ts가 수정 전 chromium에서 실패 (h2 16px, h3 16px: "Expected: > 16, Received: 16"). - GREEN: 같은 spec chromium·firefox·webkit 3/3 통과. accessibility·i18n· ui-gallery·app-shell·responsive·theme·design-system-interactions· compact-smoke + typography chromium/chromium-compact 32/32 통과(별도 playwright 설정, vite preview, pnpm 없이 빌드). - check-design-system PASS(48 tokens). 시각 회귀는 미실행. Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-04 |
||
|
|
d0f3993b60 |
fix(presentation): 검색값만 바뀌면 포커스·스크롤·진단을 건드리지 않는다 (08-02)
문제: RouteLifecycle이 pathname·search·navigationType을 effect 의존값으로 썼다. 그래서 URL에 묶은 필터를 바꾸면 포커스가 컨트롤에서 <main>으로 튀고, POP이 아니면 맨 위로 스크롤하고, route.changed를 한 번 더 남겼다. 이미 보고 있는 화면의 링크를 눌러도(React Router가 REPLACE로 바꿈) navigationType만 바뀌어 같은 일이 났다. 템플릿은 필터를 URL에 두라고 권하므로 첫 목록 화면에서 바로 드러난다(WCAG 3.2.2). 고른 방법: 이동 판단을 route ID 또는 pathname 변경으로 좁혔다(리뷰 5.1 (B)). 포커스·스크롤·진단은 useEffectEvent로 옮겨 navigationType을 읽기만 하고 트리거로 쓰지 않는다. 검색값 변경에 맨 위가 필요한 화면(페이지 번호)은 그 화면이 직접 스크롤한다. routing 문서 6.3절에 규칙을 적었다. 버린 대안: (C) 라우트 계약에 searchChangeIsNavigation 선언 — 그런 라우트가 템플릿에 없고 생성기·문서까지 바뀐다. 필요해지면 (B) 위에 더할 수 있다. navigationType을 ref로 들고 있기 — 렌더 중 ref 쓰기라 React 19의 useEffectEvent보다 의도가 덜 드러난다. 위험·한계: 지금 검색값 변경을 이동으로 세던 대시보드가 있다면 수치가 준다. 실제 브라우저의 스크롤 유지는 jsdom이 스크롤을 건너뛰어 정적 확인만 했다. 테스트용 fixture 페이지에 URL에 묶은 select를 더했다. 검증: - RED: router.test.tsx 새 테스트 2건이 수정 전 실패. 포커스가 <main id="main-content">에 있었고 route.changed가 필터 테스트 1→3, 링크 테스트 1→2로 늘었다. - GREEN: router.test.tsx 11/11, tests/component 34 files 213 tests 통과. tsc(app, test) 통과, eslint(바꾼 파일) 통과, verify-documentation-readiness PASS_SCOPED. - check:architecture는 pnpm 실행을 요구해 이 worktree에서 미실행. Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-02 |
||
|
|
37e5f9d682 |
test(e2e): SW spec이 이미 켠 worker와 생성된 사전 캐시 목록을 쓴다 (0929/11-03)
SW e2e는 템플릿의 `= null;` 줄만 바꿔 worker를 켰다. 제품이 이미 ACTIVE로 켠 트리에서는 2건이 실패하고 4건이 실행되지 않았다. 사전 캐시 목록도 템플릿 기준으로 고정돼 있어 해시 파일을 더하면 2건이 실패했다. 선택을 지금 값과 상관없이 고치되, 이미 ACTIVE면 제품의 handler를 그대로 두는 `turnOnServiceWorker` 하나로 모았다. 빌드가 만든 사전 캐시 목록을 `precached`로 돌려주고 spec이 그 목록과 비교한다. 같은 문제를 고친 0929/06-04(`96a4f68`)의 `selectActiveServiceWorker`는 ACTIVE 선택을 템플릿 값으로 덮어써 제품 handler가 빠지므로 이 함수로 바꿨고, 실패한 준비 단계에서 임시 복사본을 지우는 처리는 유지했다(두 브랜치 병합 때 오케스트레이터가 충돌을 풀었다). 위험: 테스트 도우미만 바뀐다. 0929/06-04 단위 테스트의 기대값이 "ACTIVE 선택도 템플릿 값으로 덮어쓴다"에서 "ACTIVE 선택은 그대로 둔다"로 바뀐다. 검증: ACTIVE 선택과 해시 파일 추가 트리 모두 6 passed(에이전트). 병합 뒤 service-worker-build-output 단위 테스트 5/5, SW e2e chromium·webkit 12/12, tsc(test), eslint 통과. |
||
|
|
41e79627d0 |
test(scale): 기능 규모 기준선에 측정한 커밋을 남기고 다시 잰다 (0929/11-05)
문제: config/scale/feature-shape-growth.json에 측정 시각만 있고 어느
코드를 쟀는지가 없다. 기준선이 지금 코드와 맞는지, 다음 측정과 비교할 수
있는지 알 수 없다. 실제로 기준선은 2026-09-27 측정이고, 그 뒤 15-01이
초기 청크 구조를 바꿨다(ceilings.json도 "baseline predates 15-01"이라고
적고 있었다). 기준선 0개 초기 JS 200,001 B, 기능당 2,907 B는 지금 코드와
다르다.
고른 방법:
- 측정 스크립트가 시작할 때 `git rev-parse HEAD`와 추적 파일 변경 목록
(`git status --porcelain --untracked-files=no`)을 읽어 결과의
`source: { commit, modifiedPaths }`에 싣는다. 변경 목록이 비면 커밋만으로
재현된다는 뜻이다. 측정 중 트리가 바뀔 수 있어 시작할 때 읽는다.
- 기준선을 현재 코드로 다시 잰다(--sizes=0,25,100 --repeats=2 --write).
- ceilings.json의 수치를 새 기준선에 맞춘다. 초기 JS 여유는 리뷰 개선안대로
"예산 − 기준선 ÷ 기능당 증가"로 적는다(2,291 B ÷ 약 610 B ≈ 3개).
- 단위 테스트가 기준선에 40자 commit과 modifiedPaths 배열이 있는지 본다.
버린 대안:
- 기준선 커밋이 현재 이력의 조상인지 테스트로 확인: 이력 없이 3-way로
이식하는 다운스트림(tech-log)에서는 템플릿 커밋이 없어 항상 실패한다.
- dirty 트리면 --write를 거절: 이 커밋처럼 측정 스크립트와 기준선을 한
커밋에 넣을 수 없게 된다. 대신 변경 경로를 그대로 기록한다.
위험·한계:
- 기록된 커밋은 2be973a(이 브랜치의 직전 커밋)이고 modifiedPaths는 측정
스크립트와 그 테스트 2개다. 측정 대상(src, vite 설정)은 그 커밋과 같다.
이 브랜치를 rebase하면 기록된 SHA가 이력에서 사라진다. 그때는 다시 재야
한다.
- 시간 값은 호스트 부하(loadavg 27~29)에 따라 흔들린다. 바이트와
instantiation 수만 비교 대상이다.
- 15-01 커밋 본문의 202,361 B와 이번 0개 측정 202,509 B는 148 B 다르다.
원인은 확인하지 않았다. ceilings.json은 기준선 수치 하나로 통일했다.
검증:
- RED: node scripts/run-vitest.ts run tests/unit/feature-shape-growth.test.ts
-t 'commits a baseline' — "expected undefined to deeply equal { commit:
StringMatching…" 실패.
- 측정(flock): 0개 202,509 B·720,060 inst, 25개 218,010 B, 100개
263,119 B·12,399,171 inst, 반복 2회 바이트·inst 동일. 기능당 초기 JS
약 610 B, lazy 약 8.3 KB·8파일, inst 약 117k, tsc 메모리 약 36 MB,
route 4개.
- 재현: 같은 트리에서 --sizes=0,25 --repeats=1을 다시 돌려 0개 202,509 B,
25개 218,010 B로 같음.
- GREEN: feature-shape-growth.test.ts 5 passed(빌드 측정 테스트 포함).
- tsc(node·test), eslint(바꾼 2파일), verify-documentation-readiness
PASS_SCOPED.
Refs: docs/reviews/2026-09-29-maturity-review/11-tests-browser-release-scale.md 11-05
|
||
|
|
1604ef132e |
docs(testing): 시각 회귀 13.4절을 실제 기준선 5장에 맞춘다 (11-04)
문제: 테스트 전략 문서 13.4절은 "필수 baseline"으로 각 page template, 모든 primitive group, invalid form, 열린 dialog·drawer·menu, pseudo-locale·RTL 등을 적는다. 실제 기준선은 tests/visual/platform.visual.spec.ts의 5장이다. invalid form, 열린 dialog·menu, RTL, page template별 기준선은 없다. check-test-evidence는 기준선이 4장 이상인지만 본다. 다운스트림이 이 목록을 보고 보호되지 않는 화면을 보호된다고 믿을 수 있다. 고른 방법: 리뷰 최소 개선안대로 목록을 "현재 기준선 5장"과 "제품이 늘릴 후보"로 나눈다. 5장마다 경로, viewport·테마·locale, 덮는 상태를 적고, VD-08 5항의 최초 기준선 4장에 플랫폼 개요가 더해진 범위라고 밝힌다. 검사가 장 수만 본다는 것도 적는다. VD-08은 "최초 기준선은 … 포함한다"는 결정 기록이라 고치지 않았다(5장과 모순되지 않는다). 버린 대안: 기준선을 문서 목록만큼 늘리기. 골든이 늘고 11-03의 골든 재촬영과 겹친다. 리뷰도 기준선 확장은 11-02·11-03 뒤로 미뤘다. 위험·한계: check-test-evidence가 각 화면의 존재를 검사하게 바꾸지는 않았다. 문서만 고친다. 검증(문서와 코드 대조, RED 대신): - 수정 전: 13.4절 목록 8항목 중 invalid form, open dialog/menu, RTL, page template은 platform.visual.spec.ts의 5개 toHaveScreenshot과 __snapshots__ PNG 5장 어디에도 없다. - 수정 뒤: 문서의 5장 이름이 __snapshots__ 파일 이름(-chromium-visual-linux 앞부분)과 일치. state 기준선이 401·403·404를 담는 것은 src/presentation/examples/state-gallery-page.tsx의 AuthRequired· Forbidden·NotFound 표면으로 확인. - verify-documentation-readiness PASS_SCOPED. Refs: docs/reviews/2026-11-01-maturity-review/11-tests-browser-release-scale.md 11-04 |
||
|
|
ba98048b29 |
test(design-system): Popover 포커스 반환 테스트가 전제를 먼저 만든다 (10-02)
문제: "Escape 뒤 포커스가 trigger로 돌아온다" 단언은 trigger를 클릭한 채로 Escape를 누른다. Popover는 열 때 포커스를 내용으로 옮기지 않으므로 포커스는 처음부터 끝까지 trigger에 있다. overlays.tsx의 Escape 처리에서 `triggerRef.current?.focus()`를 지워도(M15) 관련 테스트가 모두 통과한다. 내용 안의 버튼으로 Tab한 뒤 Escape를 누르는 키보드 사용자는 포커스를 잃어도 아무 테스트가 모른다(WCAG 2.4.3). 고른 방법: 열고 나서 Tab으로 내용 안의 "내부 작업" 버튼에 포커스를 옮기고, 그 버튼에 포커스가 있는지 먼저 단언한다. 그 뒤 Escape와 trigger 포커스 단언은 그대로 둔다. 리뷰 최소 개선안 그대로다. 위험·한계: 바깥 클릭으로 닫을 때의 포커스 반환(closeOutside)은 이 테스트가 보지 않는다. 이번 발견 범위 밖이다. 검증: - RED(M15 적용): 변경 전 테스트 파일은 통과, 새 테스트는 "expect(element).toHaveFocus()" 실패(design-system-platform.test.tsx trigger 단언). - GREEN: 원본 overlays.tsx로 되돌리고 related overlays.tsx --run — 23파일 152 passed. - eslint(바꾼 파일), tsc -p tsconfig.test.json 통과. Refs: docs/reviews/2026-11-01-maturity-review/10-tests-fast-layers.md 10-02 |
||
|
|
5ce3db98ef |
test(visual): 시각 회귀 허용치를 절대 픽셀 50으로 바꾼다 (11-03)
문제: 시각 회귀 허용치가 maxDiffPixelRatio 0.002(이미지의 0.2%)라서 긴 화면일수록 허용 픽셀이 커진다. 넓은 셸 1440×900은 2,592 px를 허용한다. 그래서 UI-04 수정을 되돌린 회귀(선택 상자 값 잘림, 1,145 px)가 통과한다. 골든이 코드와 조금씩 달라져도 실패하지 않아 어느 골든이 낡았는지 알 수 없다. VD-08 8항은 작은 rasterization 차이만 허용한다고 적는다. 고른 방법: maxDiffPixels 50. 11-02로 글꼴과 래스터 설정을 고정한 뒤 같은 호스트에서 깨끗한 빌드를 다시 찍으면 0 px 차이다(아래 검증). 50은 흩어진 anti-aliasing만 덮고, 지금까지 잰 가장 작은 실제 변화(낡은 compact 골든 175 px)보다 작다. tests/unit/visual-regression-tolerance.test.ts가 비율 허용치가 다시 들어오거나 절대값이 175 이상이 되면 실패한다. 버린 대안: - 0 px: 이 호스트에서는 흔들리지 않았지만 다른 Linux 러너의 래스터는 재 보지 못했다(U-1). 50은 실제 회귀를 놓치지 않는 범위의 여유다. - 위험 영역만 따로 찍어 비율의 분모를 줄이기: 골든이 늘어난다. - 현상 유지: 회귀를 놓친다. 위험·한계: - 커밋된 골든 2장이 새 허용치에서 실패한다. 깨끗한 빌드 기준으로 넓은 셸 614 px, compact 6,955 px 다르다. compact는 이 변경 전 0.2%에서도 이미 실패한다(08-01의 서랍 변경). 골든은 다시 찍지 않았다. 오케스트레이터가 마지막에 한 번 찍는다. 나머지 3장은 0 px로 통과한다. - 다른 호스트의 래스터 차이는 재 보지 못했다. 수십 px 넘게 나오면 그 측정값으로 허용치를 정한다(리뷰 재검토 조건). 검증 (pnpm을 부르지 않으려고 build-frontend.ts로 빌드하고 webServer만 vite preview로 바꾼 로컬 설정 사본으로 실행, flock, 비교 대상은 깨끗한 빌드로 새로 찍은 scratch 골든. 저장소 골든은 건드리지 않았다): - 깨끗한 빌드 vs scratch 골든, 허용치 0, --repeat-each=3: 16 passed. - RED: UI-04 변이(f1b9d3c의 shell.css 변경을 git apply -R)를 넣은 빌드, 0.2% 비율: 6 passed. 허용치 0: 넓은 셸만 "1145 pixels are different". - GREEN: 같은 변이, maxDiffPixels 50: 넓은 셸 실패(1,145 px), 나머지 통과. 변이를 되돌리고 다시 빌드, --repeat-each=2: 11 passed. - 새 단위 테스트는 수정 전 "expected 0.002 to be undefined"로 실패, 수정 뒤 2 passed. supply-chain·deletable-history-documents· test-evidence-source-rules와 함께 37 passed. - tsc(node·test), eslint, check-test-evidence --source-only PASS, verify-documentation-readiness PASS_SCOPED. Refs: docs/reviews/2026-11-01-maturity-review/11-tests-browser-release-scale.md 11-03 |
||
|
|
95e7d1107c |
test(vitest): skip·todo·only가 남은 실행을 실패시킨다 (10-04)
문제: Vitest는 skip·todo 테스트를 통과로 센다. `it.skip`이나
`it.todo`가 든 파일은 CI=true에서도 종료 코드 0으로 끝난다.
`context.skip()`도 같다. `.only`는 Vitest 기본값 때문에 CI에서만 막히고,
로컬에서는 같은 파일의 나머지 테스트를 조용히 건너뛴다.
check:test-evidence의 소스 검사가 quarantine 주석 없는 `.skip(`·`.only(`
글자를 잡지만, `it.todo`, `context.skip()`, `skipIf`는 보지 못한다.
고른 방법:
- vitest.config.ts에 allowOnly: false를 둬 `.only`를 어디서나 막는다.
- scripts/lib/no-skipped-tests-reporter.ts reporter가 실행 끝에
state가 skipped인 테스트를 찾으면 이름을 출력하고 exitCode를 1로 둔다.
-t, 태그 필터, file:line처럼 호출자가 일부러 좁힌 실행은 예외다.
게이트는 실행을 좁히지 않는다.
- reporter는 scripts/run-vitest.ts가 붙인다. CLI --reporter는 config의
reporters를 대체하므로 config에 두면 package script에서 빠진다.
run-vitest.ts는 package script와 scale tier가 모두 거치는 입구다.
호출자가 reporter를 하나도 주지 않으면 default를 함께 붙인다.
버린 대안:
- 리뷰 최소 개선안의 junit `skipped > 0` 검사: Vitest junit은 mode가
skip·todo인 테스트만 <skipped/>로 적고 `context.skip()`은 통과처럼
적는다. junit을 쓰지 않는 실행(scale tier, http-scenario-catalog,
로컬 단일 파일)은 아예 보지 못한다.
- tests/setup.ts의 afterAll 검사: 모든 테스트가 skip인 파일은 hook이
돌지 않아 잡지 못한다.
- eslint-plugin-vitest no-disabled-tests: 새 의존성이 생기고
`context.skip()`을 못 잡는다.
위험·한계:
- run-vitest.ts를 거치지 않는 직접 `vitest` 실행에는 reporter가 붙지
않는다. allowOnly는 config라서 그때도 적용된다.
- 호출자가 reporter를 주지 않으면 default reporter를 고정해서 붙인다.
Vitest가 AI 에이전트 환경에서 고르는 agent reporter 대신 default가
나온다.
- 본문 없는 `describe.todo`처럼 테스트가 없는 묶음은 세지 않는다.
- check:test-evidence는 quarantine 주석이 있는 `.skip(`을 허용하지만
이 reporter는 Vitest에서 그것도 실패시킨다. 지금 quarantine은
Playwright spec에만 있어 충돌하는 테스트는 없다. 전략 문서 16.5절에
"quarantine은 Vitest 테스트를 통과시키지 않는다"고 적었다. Vitest에도
quarantine이 필요해지면 허용 목록을 따로 둬야 한다.
- 지금 저장소의 Vitest 테스트에는 skip·todo·only가 없다.
검증:
- RED(P-B 재현, run-vitest.ts로 skip+todo, only, context.skip() 파일을
CI 없음/CI=true로): 수정 전 6경우 중 5경우 exit 0("1 passed | 1
skipped | 1 todo"). only+CI=true만 exit 1.
- 새 tests/unit/no-skipped-tests-reporter.test.ts는 수정 전 "Cannot find
module ../../scripts/lib/no-skipped-tests-reporter.ts"로 실패.
- GREEN: 같은 6경우 모두 exit 1. skip·todo·context.skip()은 "N test(s)
did not run" 목록, only는 "Unexpected .only modifier". junit reporter를
준 실행도 exit 1. -t로 좁힌 실행과 file:line 실행은 exit 0. 새 테스트
11 passed.
- 빠른 계층 전체(unit·component·integration·contract·runtime-schema·
platform·architecture·features·release·scripts·recipes, pnpm 설치를
하는 fixture-node-modules.test.ts 제외, maxWorkers 4): 3,228 passed,
1 failed. 실패는 provider-guardian-transaction의 fs.watch ENOSPC(호스트
inotify 한도)이고 reporter 없이 vitest를 직접 돌려도 같다. skip 목록
출력은 없었다.
- tsc -p tsconfig.node.json, tsconfig.test.json, eslint(바꾼 4파일),
check-ci-contract, generate-ci-workflow --check,
verify-documentation-readiness(PASS_SCOPED) 통과.
Refs: docs/reviews/2026-11-01-maturity-review/10-tests-fast-layers.md 10-04
|
||
|
|
dddf6353e0 |
test(contracts): 이벤트 계약 검증을 실제 이벤트 행으로 고정한다 (10-01)
문제: "정확하지 않은 이벤트 계약을 거부한다" 테스트는 공용 fixture의
events가 빈 배열이라 첫 줄 `if (events.length === 0) return;`에서 끝난다.
단언이 하나도 실행되지 않는다. 그래서 composeContractContributions의
이벤트 snapshot(M17)이나 assertEventContract 호출(M18)을 빼도 관련
테스트가 모두 통과한다. 템플릿 안에는 이벤트를 기여하는 계약이 없어서
이 경로를 지키는 테스트가 따로 없다.
고른 방법:
- tests/helpers/external-contract-fixture.ts에 TEST_EVENT_CONTRACT를
추가한다. 공용 TEST_CONTRACT_CONTRIBUTION의 events는 그대로 비워 둔다.
이 fixture를 쓰는 다른 테스트 20여 파일의 전제를 바꾸지 않기 위해서다.
- 빈 배열이면 return하던 테스트를 지우고 "event contracts" 묶음을 둔다.
정상 행이 snapshot으로 설치되는지(같은 내용, 다른 객체, frozen) 먼저
확인해서 아래 거부 경우가 다른 이유로 throw하는 것이 아님을 보인다.
거부 경우는 HTTP 쪽 hostileRows처럼 모양(추가 필드, 다른 prototype,
accessor)과 내용(빈 eventType, 공백, C1 제어문자, 160바이트 초과,
validator 없음, 빈 schemaId), 중복 eventType이다.
ContractContributionError로 던지는지까지 본다.
버린 대안: tests/setup.ts에 전역 expect.hasAssertions()를 두는 방법.
같은 종류의 빈 테스트를 모두 막지만 모든 vitest 프로젝트의 테스트 계약을
바꾸고, 리뷰는 빠른 계층 8개 폴더에서만 확인했다. 이 발견의 범위를
넘는다.
위험·한계: 템플릿 안에서 eventByType을 읽는 코드는 여전히 없다. 이
테스트는 composition 단계의 검증만 고정한다.
검증:
- RED(변경 전 테스트 파일과 새 파일을 함께, 변이 적용):
M17(snapshotEventContract가 입력을 그대로 반환) — 옛 파일 16개 통과,
새 파일 4개 실패("installs a well-formed event contract as its own
snapshot", extra own field, custom prototype, accessor eventType).
M18(assertEventContract 호출 제거) — 옛 파일 16개 통과, 새 파일 6개
실패(빈·공백·제어문자·160바이트 초과 eventType, validator 2종).
- GREEN: node scripts/run-vitest.ts run
tests/unit/contract-registry-immutability.test.ts — 26 passed.
- related tests/helpers/external-contract-fixture.ts
src/contracts/external-contract-runtime.ts — 97파일 796 passed.
- tsc -p tsconfig.test.json, eslint(바꾼 2파일) 통과.
Refs: docs/reviews/2026-11-01-maturity-review/10-tests-fast-layers.md 10-01
|
||
|
|
9142390422 |
fix(browser-transfer): upload 실패 번역이 code도 보고 행동을 고른다 (0929/01-01)
문제: 포트는 upload() 실패의 recovery가 호출자 행동 하나를 가리킨다고
적는다. 번역은 toUploadAction 한 곳이 하는데 recovery 단어만 본다. 표
밖 값이면 REISSUE_CAPABILITY·RETRY만 RESUME, 나머지는 NONE으로 바꾸고
retryable은 그대로 둔다. 그래서 지난 리뷰 실험 X1의 경로들이 표와 다른
행동을 가리킨다.
- ① 고른 파일이 바뀜(NOT_READABLE/REOPEN): NONE에 retryable:true.
표대로면 RESELECT다.
- ② IndexedDB 일시 오류(UNAVAILABLE/REOPEN, retryable:true): NONE.
다시 부르면 성공한다.
- ③ part 발급 404(서버가 session을 모름): NONE. 다시 부르면 새
session으로 성공한다.
- ⑤ 닫힌 runtime: RESUME. 같은 runtime은 늘 같은 답이다.
- ⑥ session보다 긴 capability(POLICY_REJECTED/REISSUE_CAPABILITY):
RESUME. 서버가 같은 값을 다시 준다.
고른 방법(지난 리뷰 3절 D1의 (a), 번역 기준 보강): 번역은 계속 한 곳에
둔다. 몇 가지 code가 먼저 정한다. POLICY_REJECTED → NONE, file store의
NOT_READABLE/REOPEN → RESELECT, UPLOAD_PART의 NOT_FOUND → RECONCILE.
나머지는 지금처럼 표 안 값은 그대로 두고, 표 밖이면 retryable:true나
REISSUE_CAPABILITY·RETRY일 때 RESUME, 아니면 NONE이다. NONE과 RESELECT는
번역 끝에서 retryable:false로 맞춘다. 닫힌 runtime은 NONE을 돌려준다.
포트 표 주석과 설계 문서 표에 이 규칙을 적었다.
버린 대안:
- 리뷰 예시의 STALE_RESULT → RESELECT. 기존 STALE_RESULT/RECONCILE
경로(resumable-upload-runtime.ts의 재조정)를 깨뜨린다. 지금
STALE_RESULT는 모두 표 안 값을 갖고 있어 규칙이 필요 없다.
- 리뷰 예시의 NOT_READABLE → RESELECT(조건 없이). PUT 중 네트워크 읽기
실패도 NOT_READABLE(REISSUE_CAPABILITY)이라 파일 재선택으로 잘못
보낸다. 그래서 REOPEN(file store가 붙이는 값)일 때만 RESELECT다.
- 출처마다 포트 어휘를 만들게 하는 안(b), action 필드 추가(c). 지난
리뷰가 다른 포트를 틀어지게 하거나 공유 타입을 바꾼다고 기각했다.
위험·한계:
- ④ part 발급(BFF) 401/403은 고치지 않았다. 지금도 RESUME이다. object
store PUT 403(재발급으로 풀리고, 기존 01-05 표 테스트가 RESUME으로
고정)과 code·단계·recovery가 모두 같아 번역 한 곳에서 가를 수 없다.
리뷰 예시("PERMISSION_DENIED는 단계와 무관하게 NONE")와 보존 조건
("기존 7경로 기대값 유지")이 이 경로에서 서로 어긋난다. runtime
호출 지점에서 발급 거절만 따로 표시할지는 소유자 판단이 필요하다.
그래서 이 발견은 부분 충족이다.
- 몇 경로의 recovery 값이 바뀐다(위 ①②③⑤⑥). 기존 테스트 하나
(resumable-upload-runtime-contract.test.ts "rejects a part capability
that outlives its session")의 기대값을 RESUME → NONE으로 바꿨다.
다운스트림 화면이 이 값으로 분기하므로 CHANGELOG [계약] 한 줄이
필요하다. 이번 수정 묶음은 CHANGELOG를 한 번에 쓰므로 여기서는 쓰지
않았다.
- 실제 브라우저 오류 발생은 재현하지 않았다. 단위 harness에서 오류
값을 주입했다.
- file-transfer 레시피 번들이 55,937 → 56,031 gzip bytes가 되어 예산
56,000을 넘었다. 다음 백 단위 규칙대로 56,100으로 올렸다.
검증:
- RED(수정 전): resumable-upload-runtime-recovery.test.ts 새 5건 실패.
① recovery NONE·retryable true(기대 RESELECT·false), ② NONE(기대
RESUME), ③ NONE(기대 RECONCILE), ⑤ RESUME(기대 NONE), ⑥ RESUME(기대
NONE). 수정 전 번역 규칙으로 되돌리면 같은 5건이 실패한다.
- GREEN: 같은 파일 통과. 기존 7경로 표 테스트에 "NONE이면
retryable:false" 단언을 더했고 통과한다.
- 회귀: resumable-upload·presigned·upload-cancellation·browser-file·
image-cdn 단위 20파일 326건 통과. tsc app·test·recipes 통과. 바꾼
파일 eslint 통과. verify-documentation-readiness PASS_SCOPED.
check-architecture(exec 전용 shim) 통과. check-optional-recipes
(source) file-transfer 56031/56100.
Refs: docs/reviews/2026-09-29-maturity-review/01-adapters-browser-transfer.md
|
||
|
|
aedd32841f |
fix(cache-storage): 정책 변경과 손상 뒤에도 다음 배포가 pointer를 덮어쓴다 (0929/02-01)
문제: active pointer를 읽을 때 rollback 목록 길이를 현재
retainedPreviousReleaseCount와 비교한다. 3에서 1로 줄이는 정상 설정
변경이나 pointer JSON 손상 뒤에는 읽기가 CORRUPT_DATA가 되고, 조회·
활성화·정리·inspect가 모두 여기서 멈춘다. control cache를 지우는 API가
없어 사용자가 사이트 데이터를 지우기 전까지 오프라인 캐시가 꺼진 채로
남고, cleanup이 막혀 배포마다 release cache가 쌓인다. 이번 라운드에도
Node와 실제 Cache API 3엔진에서 재현됐다.
고른 방법(지난 리뷰 4.1절의 (나)+(다)):
- (다) isActivePointer는 목록 길이를 현재 값이 아니라 정책이 허용하는
최댓값(5, MAX_RETAINED_PREVIOUS_RELEASE_COUNT)과만 비교한다. 정책
검증과 같은 상수를 쓴다. 다음 activation이 이미 하던 slice로 목록을
현재 값으로 자른다.
- (나) activateRelease는 이전 pointer 읽기가 CORRUPT_DATA면 없는
것으로 보고, 전체 재검증을 통과한 후보로 rollback 목록 없이
덮어쓴다. 일시 오류(UNAVAILABLE 등)는 지금처럼 활성화를 멈춘다.
버린 대안:
- 현상 유지 + "사이트 데이터 삭제" 안내. 운영자가 원인을 알 수 없고
캐시가 계속 쌓인다.
- control을 지우는 admin API. 포트가 늘고 호출자가 언제 불러야 하는지
알아야 한다.
- (다)만 적용. 정책 변경은 풀리지만 JSON 손상은 풀리지 않는다.
위험·한계:
- 지키던 성질은 그대로다. 검증한 후보만 활성화하고(재검증은 pointer
읽기 전에 끝난다), 조회는 manifest digest가 맞는 바이트만 돌려준다.
읽을 수 있는 pointer가 가리키는 캐시는 cleanup이 지우지 않는다.
손상 pointer 상태의 조회와 cleanup은 다음 activation까지 여전히
CORRUPT_DATA다.
- 덮어쓰면 손상 pointer의 rollback 목록을 잃는다. 원래 읽을 수 없던
값이다. 덮어쓴 뒤 cleanup이 구버전 탭이 쓰던 캐시를 지울 수 있다.
그 탭의 조회는 네트워크로 떨어진다. Service Worker drain(VD-15)을
구현하면 이 규칙을 다시 본다(지난 리뷰 4.1절 7).
- 리뷰가 "가능하면"으로 적은 3엔진 browser spec(E-2)은 추가하지
않았다. 단위 테스트(MemoryCacheStorage)로만 확인했다.
- service-worker-pwa 레시피 번들 9,665 → 9,716 / 10,000 gzip bytes.
검증:
- RED(수정 전): public-response-cache-repair.test.ts 새 2건 실패.
retained 3 → 1 뒤 조회가 { ok: false }(기대 ok:true), 잘린 pointer
뒤 다음 배포의 activate가 { ok: false }.
- GREEN: 같은 파일 8건 통과. 일시 오류 가드 테스트 1건을 함께 넣었다.
activate가 모든 pointer 실패를 무시하도록 바꾼 변이를 이 테스트가
잡는다(1건 실패 확인 뒤 되돌림).
- 회귀: public-response-cache 단위 3파일 40건 통과. tsc app·test·
service-worker·recipes 통과. 바꾼 파일 eslint 통과.
verify-documentation-readiness PASS_SCOPED. check-optional-recipes
(source) PASS.
Refs: docs/reviews/2026-09-29-maturity-review/02-adapters-browser-files-cache.md
|
||
|
|
8ad11c0b64 |
fix(browser-files): preview와 download의 dispose가 자기 lease만 푼다 (02-01)
문제: runtime은 object URL lease registry 하나를 preview와 download에 같이 넘긴다. 두 쪽의 dispose()가 모두 registry 전체의 dispose()를 불러, 누가 만든 lease인지 구분하지 않고 전부 revoke한다. runtime.previews.dispose()를 부르면 30초 grace 중인 download blob URL까지 바로 revoke된다(E-9). 브라우저가 아직 blob을 읽기 전이면 그 download가 실패할 수 있다. 반대로 download의 dispose()는 다른 화면의 preview URL을 끊는다. registry 주석은 이 dispose를 "route teardown" 에서 쓰라고 읽혔다. 고른 방법(리뷰 5.2절의 (나)): 한도는 같이 쓰고 해제 권한만 나눈다. registry에 scope()를 두어 소비자마다 자기가 만든 lease 집합을 들고, scope의 dispose()는 그것만 release한다. preview와 download adapter는 각자 scope로 lease를 만든다. registry 전체 dispose()는 runtime.dispose()만 부른다. 포트 시그니처는 그대로이고, TransientPreviewPort.dispose()에 효과 범위를 주석으로 적었다. 설계 문서 3.5절에 해제 권한과 route 정리 방법을 적고, 바뀐 줄 번호를 맞췄다. 버린 대안: - 포트 주석만 고친다(가). 함정이 코드에 그대로 남는다. - 소비자마다 registry를 나눈다(다). 해제 범위는 맞지만 탭 전체의 합계 바이트 상한이 두 곳으로 갈라진다. - TransientPreviewPort에서 dispose()를 뺀다(라). 공개 포트 변경이라 이번 범위(포트는 추가만)를 넘는다. (나)와 함께 할 수 있어 남겨 둔다. 위험·한계: - previews.dispose() 뒤 그 runtime의 preview가 계속 UNAVAILABLE인 것(영향 ②)과, previews.dispose()가 다른 화면의 preview lease까지 푸는 것(영향 ①, 같은 소비자 안)은 그대로다. 문서에 route 정리는 lease마다 release()로 하라고 적었다. 완전히 막으려면 (라)가 필요하다. - scope가 들고 있는 release 함수 집합만큼 메모리가 조금 는다. lease release 때 집합에서 빠지므로 lease 수 상한(기본 16)을 넘지 않는다. - file-transfer 레시피 번들이 55,856 → 55,937 gzip bytes가 되어 예산 55,900을 넘었다. 다음 백 단위 규칙대로 56,000으로 올렸다. 검증: - RED(수정 전): browser-file-runtime.test.ts 새 1건 "expected [ 'blob:runtime-download' ] to deeply equal []"(previews.dispose()가 download URL을 revoke). browser-file-download.test.ts 새 1건 "expected [ 'blob:shared-1', 'blob:shared-2' ] to deeply equal [ 'blob:shared-2' ]"(download dispose()가 다른 소비자의 lease를 revoke). - GREEN: browser-file 단위 5파일 64건 통과. runtime dispose가 모든 lease를 즉시 revoke하는 기존 테스트도 통과. - 회귀: browser-file·presigned·json-schema 단위 10파일 168건 통과. tsc app·test·recipes 통과. 바꾼 파일 eslint 통과. check-architecture (exec 전용 shim) 통과, check-adapter-inventory 통과, verify-documentation-readiness PASS_SCOPED, check-optional-recipes(source) file-transfer 55937/56000. Refs: docs/reviews/2026-11-01-maturity-review/02-adapters-browser-files-cache.md |
||
|
|
5b96529c53 |
fix(cross-context-invalidation): publish 실패 원인을 관측 reason에 싣는다 (02-05)
문제: cross-context publish가 실패하면 원인과 상관없이 관측 reason이
INVALID_ENVELOPE다. createEventId가 던질 때(host에서는 secure random
실패)와 자기 envelope 검사 실패가 같은 invalidPublish()로 가고, 그
함수가 reason을 고정한다. bootstrap은 이 reason을 그대로
cache.operation.failed 진단에 싣는다. 난수 실패나 topic version
불일치가 "wire 형식 오류"로 보여 원인을 찾으려면 코드를 읽어야 한다.
고른 방법: invalidPublish가 reason을 인자로 받는다. event ID 실패는
이미 reason 목록에 있는 SECURE_RANDOM_UNAVAILABLE, envelope 검사
실패는 parse 결과의 reason(TOPIC_REJECTED 등)을 싣는다. 새 reason
값은 만들지 않는다. 호출자에게 돌려주는 결과
{ok:false, reason:"INVALID_EVENT"}는 그대로다.
위험·한계: 관측 reason 값이 바뀌므로 INVALID_ENVELOPE로 경보를 거는
대시보드가 있다면 새 값도 봐야 한다. 이 repo 안에는 그런 소비자가
없다. cross-context는 기본 조립이라 초기 JS에 들어간다. 바뀐 코드는
수십 바이트이고, 빌드 기반 번들 게이트(check:bundle)는 pnpm이 필요해
이 worktree에서 돌리지 않았다.
검증:
- RED(수정 전): cross-tab-invalidation.test.ts 새 1건이
"expected [ 'INVALID_ENVELOPE' ] to deeply equal
[ 'SECURE_RANDOM_UNAVAILABLE' ]"로 실패.
- GREEN: 같은 파일 통과.
- 회귀: cross-tab-invalidation·tanstack-cache-coordinator·
runtime-adapters 단위 3파일 46건 통과. tsc app·test 통과. 바꾼 파일
eslint 통과.
Refs: docs/reviews/2026-11-01-maturity-review/02-adapters-browser-files-cache.md
|
||
|
|
3bb1829cda |
fix(cache-storage): stage 재검증 실패를 CACHE_STAGE로 기록한다 (02-03)
문제: 이미 stage된 release를 다시 stage하면 후보를 재검증한다. 재검증 함수 verifyReleaseCandidate는 활성화와 같이 쓰는 함수라 실패 Result의 operation을 CACHE_ACTIVATE로 만든다. 활성화 경로는 rebaseFailure로 바꾸지만 stage의 재사용 경로는 그대로 돌려준다. Cache API가 재검증 중 일시 오류를 내면 stage 결과와 관측이 모두 CACHE_ACTIVATE가 된다. 운영자는 "활성화 실패"로 읽고, error.operation 으로 분기하는 호출자는 잘못된 경로를 탄다. 고른 방법: stage 재사용 경로도 활성화 경로처럼 rebaseFailure(..., "CACHE_STAGE")로 돌려준다. 한 줄이다. 버린 대안: verifyReleaseCandidate가 operation을 인자로 받게 하는 안. 호출부 세 곳(stage, activate, inspect)을 모두 바꾸고, inspect는 실패를 밖으로 내지 않아 이득이 없다. 리뷰가 함께 적은 readAndValidateResponse의 CACHE_STAGE 고정은 두 소비 경로가 이미 rebase하거나 결과를 내보내지 않아 겉으로 드러나는 결함이 없으므로 건드리지 않았다. 위험·한계: 동작(실패를 성공으로 바꾸지 않음, 후보를 지우지 않음)은 그대로다. 바뀌는 것은 실패의 operation 값뿐이다. service-worker-pwa 레시피 번들 9,662 → 9,665 / 10,000 gzip bytes. 검증: - RED(수정 전): public-response-cache-repair.test.ts 새 1건이 operation "CACHE_ACTIVATE"(기대 "CACHE_STAGE")로 실패. - GREEN: public-response-cache 단위 3파일 37건 통과. - 회귀: tsc app·test·service-worker 통과. 바꾼 파일 eslint 통과. check-optional-recipes(source) PASS. Refs: docs/reviews/2026-11-01-maturity-review/02-adapters-browser-files-cache.md |
||
|
|
6b7b53fe01 |
perf(image-cdn): 같은 이미지를 동시에 resolve하면 probe를 한 번만 돌린다 (01-04)
문제: resolve()는 통과한 probe 기록(passedProbes)을 slot을 기다리기 전에만 본다. 같은 asset·preset을 동시에 5번 resolve하면 probe가 5번 돈다. probe마다 preset의 encoded 예산까지 no-store로 내려받고 decode하며, 같은 이미지가 probe slot을 차지해 다른 이미지의 probe가 밀린다. 고른 방법: asset·preset별로 "진행 중인 probe 단계"(slot 대기, probe, 통과 기록)를 promise 하나로 둔다. 뒤에 온 호출은 그 단계가 끝나기를 자기 signal로 기다린 뒤 기록된 통과를 재사용한다. probe 자체를 공유하지 않으므로 호출마다 abort가 독립이다. 앞선 probe가 실패하면 기다린 호출이 직접 probe한다(실패는 재사용하지 않는다는 기존 규칙). X5(동시 5회, maxConcurrentProbes 2)에서 probe가 1회다. 버린 대안: - 리뷰가 제안한 slot 획득 뒤 재확인. 넣어 보니 X5에서 probe가 3회로 완료 기준(2회 이하)을 못 맞춘다. slot은 원시 probe가 끝날 때 넘겨지는데(TR-RR-07), 통과 기록은 그보다 몇 microtask 뒤에 남는다. 다음 대기자가 기록 전에 깨어난다. - 진행 중 probe의 결과를 공유(single-flight). 호출자마다 signal이 달라 참조 수를 세야 한다. - slot 해제를 통과 기록 뒤로 미룬다. 해제 지점이 원시 probe 정착과 wrapper 종료 두 곳으로 갈라진다. 위험·한계: - 대기 뒤 재사용할 때 만료를 따로 다시 보지 않는다. 통과를 기록한 호출이 기록 직전에 만료를 봤고, 대기자는 같은 task 안에서 이어서 실행된다. 시작할 때의 만료 검사(기존)는 그대로다. - 앞선 probe가 실패하면 기다리던 호출들이 각자 probe한다(slot 수로 묶임). 실패가 반복되는 이미지는 지금과 같은 수의 probe가 돈다. - probe 블록을 try/finally로 감싸면서 들여쓰기가 바뀌었다. 로직 변경은 `git show -w`로 보면 짧다. - file-transfer 레시피 번들이 55,725 → 55,856 gzip bytes가 되어 예산 55,800을 넘었다. 다음 백 단위로 올리는 기존 규칙대로 55,900으로 올렸다. 검증: - RED(수정 전 코드에 새 테스트): "probes once and lets the other calls reuse the pass"가 "expected vi.fn() to be called 1 times, but got 5 times"로 실패. 재확인 안(버린 대안)에서는 2회 기대에 3회로 실패. 나머지 새 테스트 2건(앞선 probe 실패 시 대기자가 직접 probe, 대기 중 abort가 진행 중 probe를 끊지 않음)은 새 분기를 고정한다. - GREEN: image-cdn 단위 3파일 37건 통과. - 회귀: browser-file·image-cdn·presigned·resumable-upload·json-schema 단위 20파일 323건 통과. tsc app·test·recipes 통과. 바꾼 파일 eslint 통과. check-optional-recipes(source) file-transfer 55856/55900. Refs: docs/reviews/2026-11-01-maturity-review/01-adapters-browser-transfer.md |
||
|
|
95e4445243 |
fix(browser-transfer): part 발급과 PUT이 서버의 Retry-After를 기다린다 (01-01)
문제: part 단계(BFF capability 발급, object store PUT)의 상태표
statusFailure는 상태 코드만 받아 429의 Retry-After를 버린다. 서버가
`429 Retry-After: 5`로 답해도 runtime은 지수 backoff(기본 250·500·
1000ms)로 다시 보내고, 1.75초 안에 요청 8개를 쓴 뒤 retryable 실패를
돌려준다. 설계 문서 두 곳(presigned-transfer-and-image-cdn.md,
server-file-capability-infrastructure.md)은 part 단계도 bounded
Retry-After를 따른다고 적는다. 헤더를 읽는 곳은 control plane
transport뿐이었다.
고른 방법: statusFailure가 Response와 현재 시각을 받아 429·503이면
kernel parseRetryAfterDelay로 retryAfterMs를 채운다. 상한
maxRetryAfterMs는 runtime의 canRetry·waitForRetry가 이미 적용하므로
presigned 계층은 값을 그대로 넘긴다. 상한을 넘으면 재시도하지 않는다
(control plane과 같은 규칙). PresignedUploadPartCapabilityProvider.
issueUploadPart와 PresignedUploadPartPort.put의 반환 타입을
UploadProviderResult로 넓혔다. 기존 구현은 그대로 대입되므로
추가형이다. HTTP control plane 어댑터의 발급 브리지가 실패를 다시
만들면서 retryAfterMs를 버리던 것도 넘기게 했다.
버린 대안:
- 문서를 "part 단계는 Retry-After를 읽지 않는다"로 고친다. 재시도
증폭이 그대로 남는다.
- BFF 응답 본문에 대기 시간을 넣는 별도 계약. 표준 헤더를 두고 서버와
클라이언트를 함께 바꿔야 한다.
- download 경로만 빼고 읽는다. 하나로 합친 상태표(Q-6.1-9)를 다시
둘로 가르게 된다. download 소비자(browser-files 전달 어댑터)는
실패를 다시 만들어 이 값을 읽지 않는다.
위험·한계:
- 다른 origin의 object store가 Access-Control-Expose-Headers에
Retry-After를 넣지 않으면 헤더가 없는 것으로 읽혀 지금처럼 backoff만
쓴다. statusFailure 주석에 적었다.
- part 단계에서 Retry-After가 없거나 형식이 틀린 429는 지금처럼
retryable backoff다. control plane은 이 경우 재시도하지 않는다. 이
차이는 이번에 바꾸지 않았다.
- issueDownload·open 실패에도 retryAfterMs가 실린다. 이 두 포트의
타입(BrowserDataResult)에는 드러나지 않는다.
- file-transfer 레시피 번들이 55,623 → 55,725 gzip bytes가 되어 예산
55,700을 넘었다. 측정값 위 약 100바이트로 반올림하는 기존 규칙
(
|
||
|
|
48a4074e3a |
fix(bootstrap): 시작할 런타임이 없는 선택 capability를 조립 때 거절한다 (09-07)
문제: 선택 파일은 "Adding an entry here is what installs a capability"라고
적지만 optional host가 실제로 시작하는 것은 Service Worker뿐이다.
realtime·webWorkers·offlineCommands에 항목을 넣으면 아무것도 시작되지
않고 health는 UNAVAILABLE로 남는데, 플랫폼 개요가 읽는 스냅샷은 그
선택을 active로 세어 "활성 (1)"을 보인다. 경고도 실패도 없다.
고른 방법:
- `createOptionalRuntimeHost`가 시작 수단이 없는 capability(realtime,
webWorkers, offlineCommands)가 선택돼 있으면 그 이름을 모두 담아
throw한다. 런타임 설정으로 끈 선택은 resolve 단계에서 빠지므로 막지
않는다. host는 부트 조립에서 만들어지므로 부트 실패 화면으로 드러난다.
- 선택 파일 주석을 "Service Worker만 여기서 설치된다. 나머지는
composition에 런타임을 먼저 연결해야 한다"로 고쳤다.
버린 대안: 주석만 고치기. 스냅샷이 계속 active로 세고, 선택한 제품은
여전히 아무 신호도 받지 못한다.
위험·한계:
- 런타임을 연결하는 제품은 host의 시작 순서와 이 검사를 함께 바꿔야
한다(09-02 확장 지점과 같은 자리). 검사 주석에 적었다.
- health 계산의 세 capability `UNAVAILABLE` 분기는 이제 닿지 않지만,
런타임을 연결할 때 쓸 자리라 남겼다.
- 리뷰 09-05(선택 파일에서 템플릿 상태 설명 분리)는 하지 않았다.
- 초기 JS +127 B gzip(202,995 → 203,122 B, 여유 1,678 B).
검증:
- RED: tests/unit/optional-runtime-host.test.ts의 새 테스트 3건(capability별
하나)이 "expected [Function] to throw an error"로 실패.
- GREEN: 같은 파일 9건 통과.
- 회귀: tests/unit(pnpm을 띄우는 5개 제외) 1,933건, tests/integration
(프로세스를 띄우는 3개 제외) 131건, tests/{component,platform,
architecture,features,contract} 570건 통과. 그중
app-build-input.test.ts 1건이 부하 25에서 10초 시간 초과로 실패했고,
heavy lock 아래 단독 재실행에서 4건 통과. tsc app·test 통과. 바꾼 파일
eslint 통과.
|
||
|
|
abf3ce521d |
fix(contracts): REST 보안 프로필 오류가 operation·프로필·깨진 조건을 말한다 (16-03)
문제: `resolveRestSecurityProfiles`는 프로필이 없거나 조합이 틀리면 일곱
조건을 한 번에 보고 "REST security profiles are incoherent."만 던진다.
참조 기능을 복사해 `REFERENCE_EXTERNAL_BEARER`를 바꾸면 이 한 문장으로
레지스트리를 읽는 게이트가 모두 멈추고, 개발자는 스택에서
rest-profiles.ts를 열어 조건을 하나씩 대조해야 한다.
고른 방법: 조건마다 깨졌을 때의 문장을 만들어 모은 뒤, operation id와
함께 한 오류로 던진다. 예: "REST security profiles are incoherent for
CREATE_SAMPLE_RESOURCE: unknown authProfileId ORDER_EXTERNAL_BEARER."
operation 인자 타입에 선택 필드 `operationId`를 더했다(추가만). 호출부
두 곳(`validateRestProfileBindings`, V2 client)은 이미 operation 전체를
넘기므로 고칠 곳이 없다. 기존 문장 앞부분은 그대로라 "incoherent"를 찾는
테스트·로그 검색은 계속 맞는다.
버린 대안: 첫 번째로 깨진 조건에서 바로 throw하기. 조건이 둘 이상
깨진 경우(예: 이름도 틀리고 CSRF도 틀림) 고칠 때마다 다음 오류를 다시
봐야 한다.
위험·한계:
- 리뷰 16-03의 (1) 프로필 이름을 `EXTERNAL_BEARER`로 바꾸고 옛 이름을
별칭으로 두는 부분은 하지 않았다. FE-REG-API 행이 바뀌어 레지스트리
기준선을 다시 써야 하고, `update-registry-baseline.ts`는 소유자와
사유(REGISTRY_BASELINE_OWNER/REASON)를 승인 파일에 남긴다. 그 승인은
사용자 몫이다. 제거 드릴 잔여 정규식이 이 이름을 못 잡는 문제도 그
작업에 남는다.
- 초기 JS +189 B gzip(202,806 → 202,995 B, 여유 1,805 B). rest-profiles가
초기 청크에 있어 오류 문장이 그대로 실린다.
검증:
- RED: tests/unit/rest-profile-contract.test.ts의 새 테스트가
"expected [Function] to throw error matching /incoherent.*
CREATE_SAMPLE_RESOURCE.*u…/ but got 'REST security profiles are
incoherent.'"로 실패.
- GREEN: 같은 파일 8건 통과(미등록 프로필, auth "none"+bearer 두 경우).
- 회귀: tests/unit(pnpm을 띄우는 5개 제외) 1,930건, tests/integration
(프로세스를 띄우는 3개 제외) 131건, tests/{contract,features,
runtime-schema,component,architecture,platform} 626건 통과. tsc app·test
통과. 바꾼 파일 eslint 통과.
|
||
|
|
de48db25d9 |
fix(router): context·feature 경계와 라우트 모듈 실패를 진단에 남긴다 (09-09)
문제: context gateway의 `ContextErrorBoundary`·`FeatureErrorBoundary`는
`onError`를 받지 않아 잡은 실패를 진단에 남기지 않고, 화면 지원 참조는
buildId뿐이다. 라우트 모듈이 청크 누락이 아닌 이유로 실패할 때(평가 중
throw, 15-01 뒤로는 기능 실행부 적재 실패)도 같은 화면만 그리고 기록이
없다. 안쪽 경계(`RenderErrorBoundary`) 밖에서 난 실패, 예를 들어 핸들의
route id가 레지스트리에 없거나 핸들에 라우트 codec이 없을 때는 사용자
신고로도 사건을 찾을 수 없다. 0929/08-05와 같은 결함이다.
고른 방법:
- `ScopedErrorBoundary`가 잡을 때 incident id를 만들어 `onError` 보고에
넣고, 함수형 fallback에 같은 id를 넘긴다. 둘 다 추가 변경이다(기존
ReactNode fallback과 `{scope, ownerId}`를 읽는 쪽은 그대로 동작).
- incident id 생성기를 `src/platform/errors/incident-id.ts`로 옮겨 두
경계 계열이 같은 함수를 쓴다(platform은 presentation을 import할 수 없다).
- gateway가 두 경계에 `reportRenderFailure` 호출과
`<buildId>:<incidentId>` 지원 참조를 넘긴다. context 경계는
`component_boundary`를 "route"로 보고한다. 진단·텔레메트리 계약에
context 값이 없고, 같은 gateway의 청크 복구 보고도 "route"를 쓴다.
- 비청크 적재 실패는 context 경계 안에서 다시 throw해 같은 보고 경로를
탄다. route id는 URL의 등록 라우트, 없으면 context id다.
버린 대안:
- 세 곳을 presentation `RouteBoundary`로 바꾸기(0929/08-05 제안): 경계
두 계열 통합(리팩토링 R4) 성격이고 context/feature 소유 범위 표시
(`data-boundary`, testid)가 바뀐다.
- gateway가 URL마다 incident id를 하나 만들어 두 경계에 나눠 주기:
두 경계가 같은 id를 공유해 사건 구분이 흐려진다.
- `component_boundary`에 "context" 추가: 진단·텔레메트리 계약과
레지스트리 기준선을 바꾸는 일이라 이번 범위 밖이다.
위험·한계:
- `APP_SHELL`의 `errorElement`(0929/08-05가 함께 적은 곳)는 그대로
buildId만 보이고 보고하지 않는다. React Router 오류 요소라 다른 방식
(useRouteError + 마운트 시 보고)이 필요해 남겼다.
- 실패한 context 안에서 URL을 바꾸면 경계가 리셋되고 다시 throw해 방문마다
한 번 보고한다.
- 화면 변화: context·feature 경계 실패 화면과 비청크 적재 실패 화면의
지원 참조가 `build:incident` 형식이 된다. 시각 골든에는 없는 화면이다.
- 초기 JS +58 B gzip(202,748 → 202,806 B, 여유 1,994 B).
검증:
- RED: tests/component/context-boundary-diagnostics.test.tsx 3건(context
경계: 미등록 핸들 id, feature 경계: codec 없는 핸들, 비청크 적재 실패)이
모두 `Unable to find an element with the text: /^지원 참조:
build-a:[0-9a-f]{8}$/`로 실패. 화면은 "지원 참조: build-a"였다.
- GREEN: 3건 통과. failure-boundary.test.tsx에 함수형 fallback이 보고한
incident id를 받는지 1건 추가, `onError` 보고 기대값에 incidentId 추가.
- 회귀: tests/{architecture,platform,component,features,scripts,contract}
95 files / 592 tests, tests/unit(pnpm을 띄우는 5개 제외) 164 files /
1,929 tests 통과. tsc app·test 통과. 바꾼 파일 eslint 통과.
check-architecture(shim), check-adapter-inventory, check-diagnostics,
check-registries 통과.
|
||
|
|
7139c7c61e |
fix(apps): 소유 context 루트가 닿지 않는 기능 라우트를 조립 때 막는다 (09-06)
문제: 라우터는 context마다 gateway 하나를 그 루트 경로에 붙이고 기능
라우트를 그 안에서만 렌더한다. 레지스트리와 탐색 메뉴는 경로와 상관없이
모든 기능 라우트를 싣는다. 그래서 루트 `shop/*` context의 `/catalog`
라우트는 메뉴 링크로 나오고 그 URL은 NOT_FOUND가 된다. 같은 루트를 쓰는
context가 둘이면 id가 늦은 쪽 전체가 닿지 않는다. 어떤 게이트도 경로와
루트를 비교하지 않았다.
고른 방법: `defineDeployableAppModule`이 context별 기능 계약 라우트를
React Router `matchRoutes`로 전체 context 루트에 맞춰 보고, 그 라우트를
받는 context가 소유 context가 아니면 라우트 id·경로·기능 id·context
id·루트를 담아 throw한다. 앱 모듈은 부트 정적 그래프에서 평가되므로
부트 실패 화면과 라우터를 거치는 모든 테스트에서 드러난다. 라우터와 같은
매칭 규칙을 쓰므로 루트 밖 경로, `/`, 루트 없는 context, 같은 루트, 더
구체적인 다른 루트에 먹히는 경로를 한 검사로 잡는다. 중첩 루트 자체는
허용한다(`tests/component/context-route-gateway.test.tsx`가 쓰는 모양).
starter-experience.md 기능 추가 4단계에 규칙을 적었다.
버린 대안:
- 생성기에서 검사: 생성기는 정규식으로 리터럴만 읽어 라우트 경로를 모른다.
- `defineBoundedContextModule`에서 검사: 다른 context의 루트를 모른다.
같은 루트·중첩 루트를 앱 단위에서 따로 또 봐야 해서 검사가 두 곳이 된다.
- 루트 문자열 접두어 비교: `:param`·splat 규칙을 다시 구현하게 된다.
위험·한계:
- 리뷰 09-06의 (3) "context 라우트 핸들의 route id가 레지스트리에 있는가"는
넣지 않았다. 핸들은 `context-routes.ts`를 읽어야 보이는데 이 파일은 늦게
읽어야 한다. 헬퍼 제공과 적재 시 검사 중 고르는 설계 선택이라 남긴다.
그 실패의 진단 누락은 09-09에서 다룬다.
- 플랫폼 라우트와 기능 라우트의 경로 충돌은 검사하지 않는다.
- 초기 JS +239 B gzip(202,509 → 202,748 B, 여유 2,291 → 2,052 B).
같은 worktree에서 `vite build` 두 번으로 쟀다.
검증:
- RED: tests/architecture/context-route-roots.test.ts 7건 중 거절 5건이
"expected [Function] to throw an error"로 실패(수정 전,
|
||
|
|
96a4f68016 |
test(service-worker): SW 픽스처가 현재 선택과 무관하게 워커를 켠다 (0929/06-04)
문제: SW e2e 도우미(prepareServiceWorkerBuilds)는 사본의 `const SERVICE_WORKER: InstalledServiceWorkerSelection | null = null;` 줄을 글자 그대로 찾아 ACTIVE로 바꿨다. 이미 SW를 켠 제품 트리에는 이 줄이 없어서 beforeAll이 throw하고 update·recovery spec이 모두 멈춘다. 이 spec이 실제로 필요한 곳이 바로 SW를 켠 제품이다. setup이 실패하면 spec이 root를 받지 못해 /tmp/ca-sw-builds-* 사본도 남았다. service-worker-build-output.test.ts도 같은 치환을 했다. 고른 방법: selectActiveServiceWorker(root)를 도우미에 두고, SERVICE_WORKER 선언 전체를 값과 무관하게(정규식, 정확히 1개) ACTIVE_SELECTION으로 바꾼다. 두 픽스처가 이 함수를 쓴다. recovery spec이 ACTIVE_SELECTION을 다시 찾는 방식은 그대로 동작한다. setup 실패 때는 fixture-builds.ts처럼 사본을 지우고 다시 throw한다. 버린 대안: 리뷰가 함께 적은 "install spec 기대값을 dist/assets 전체 대신 생성된 service-worker-assets.ts 목록과 비교". ACTIVE 트리에서도 두 값이 같아 이번 결함과 무관하다. 제품이 사전 캐시 대상을 바꿀 때(0929/06-03) 다시 본다. 위험·한계: - 선택 선언의 값에 `;`가 들어가면 정규식이 짧게 끊겨 "정확히 1개" 검사나 이후 타입 검사에서 실패한다(조용히 틀리지는 않는다). - e2e는 chromium만 돌렸다. webkit·firefox는 미실행. 검증: - RED: 작업 트리 선택을 ACTIVE로 바꾸고 SW e2e 2 spec(chromium, webServer 없는 임시 설정)을 돌림 -> `Expected exactly one "const SERVICE_WORKER: ... = null;"`로 2 failed, 4 did not run, 사본 2개 잔류. - GREEN: 같은 ACTIVE 트리에서 6 passed. 선택을 null로 되돌린 템플릿 트리에서도 6 passed. 잔류 사본 0. - 새 단위 테스트(null·ACTIVE·REMOVE_REGISTRATION 선택 -> ACTIVE) 포함 `node scripts/run-vitest.ts run tests/unit/service-worker-build-output.test.ts` -> 5 passed(ACTIVE 트리와 null 트리 모두). - `npx tsc --project tsconfig.test.json --noEmit` -> 오류 0. - `npx eslint <바꾼 파일 2개> --max-warnings=0` -> 통과. Refs: docs/reviews/2026-09-29-maturity-review/06-adapters-service-worker-push.md 06-04, docs/reviews/2026-11-01-maturity-review/06-adapters-service-worker-push.md 2.1절 |
||
|
|
85d55e0cd3 |
fix(service-worker): 사전 캐시와 설정 URL이 router base path를 따른다 (0929/06-02)
문제: SW 자산 생성기(scripts/generate-service-worker-assets.ts)가 사전
캐시 URL을 `/${relative}`로 만들어 VITE_ROUTER_BASE_PATH를 무시했다.
워커는 root-relative URL을 scope 기준으로 풀지만 base가 사라지므로
/app/ 배포에서 install이 /assets/...를 요청해 404를 받고, 워커가
설치되지 않았다. 같은 빌드의 SW 설정도 runtime config URL 기본값을
"/config.json"으로 고정해, 페이지가 쓰는 /app/config.json을 워커가
network-only로 알아보지 못했다. 앱 빌드·runtime config·06-08
fallback은 이미 base를 따르는데 이 두 곳만 빠져 있었다.
고른 방법: 리뷰가 적은 최소 방향. collectStaticAssets에 basePath
인자(기본 "/")를 더하고, 생성기 main과 SW Vite 설정이 페이지와 같은
getBuildConfig(src/contracts/env.ts)로 base와 runtime config URL을
계산한다. 결과 URL은 그대로 root-relative라 isCanonicalStaticAssetUrl
검사를 통과한다. base가 "/"이면 manifest와 digest가 전과 같다.
버린 대안: 워커가 manifest URL을 scope 상대로 풀게 바꾸기. 계약 차이는
없지만 워커 코드와 manifest 계약(root-relative)을 함께 바꿔야 해서
생성기 수정보다 크다.
위험·한계:
- base마다 manifest digest가 달라진다(의도된 결과).
- VITE_RUNTIME_CONFIG_URL이 빈 문자열이면 이제 base 기본값을 쓴다.
페이지(getBuildConfig)와 같은 규칙이다.
- 리뷰 완료 기준의 "e2e 도우미를 base 옵션으로 돌린 첫 설치가
RELOAD_TO_ENABLE"은 하지 않았다. e2e 도우미에 base 옵션과 /app/
서빙이 필요하고, 실제 브라우저 install은 이번에 확인하지 않았다.
검증:
- RED: collectStaticAssets 단위 테스트(basePath "/app/")가 수정 전
`/assets/index-abcdefgh.js`를 받아 실패(1 failed | 9 passed).
service-worker-build-output.test.ts의 새 테스트(SW ACTIVE·
production·/app/ 실제 빌드)가 생성기만 되돌리면 URL 목록에서,
SW 설정만 되돌리면 `Received: "/config.json"`으로 각각 실패.
- GREEN: 두 테스트 통과. `node scripts/run-vitest.ts run
tests/unit/service-worker tests/unit/sub-path-deployment.test.ts
tests/unit/hosting-probe.test.ts tests/unit/web-push` -> 12파일
171건 통과(빌드 테스트는 flock 안에서).
- `npx tsc` node·test·app·service-worker -> 오류 0.
- `npx eslint <바꾼 파일 4개> --max-warnings=0` -> 통과.
- `node scripts/check-adapter-inventory.ts` -> PASS.
- 미실행: SW e2e(Playwright).
Refs: docs/reviews/2026-09-29-maturity-review/06-adapters-service-worker-push.md 06-02, docs/reviews/2026-11-01-maturity-review/06-adapters-service-worker-push.md 2.1절
|
||
|
|
b28e290965 |
docs(operations): SW 활성화 조건에 탭을 모두 닫는 경로를 적는다 (06-02)
문제: 운영 문서(browser-file-storage-recovery.md 8절)는 "활성화는 페이지의 requestActivation()으로만 일어나므로 새 worker 활성화를 멈추려고 따로 할 일은 없다"고 적는다. 브라우저는 scope의 탭이 모두 닫히면 waiting 워커를 스스로 활성화한다. 운영자가 이 문장을 믿고 결함 있는 waiting 워커를 두면, 탭을 닫았다 연 사용자부터 그 워커를 쓰고 대응(REMOVE_REGISTRATION)이 늦어진다. RED(문서-코드 대조): install은 skipWaiting()을 부르지 않는다 (service-worker-entry.ts). requestActivation()은 src에서 정의 (service-worker-page-controller.ts, contracts/service-worker.ts)만 있고 부르는 곳이 없다. 저장소 e2e 주석(service-worker-update.spec.ts)과 리뷰 실험 8(chromium·webkit)은 탭을 모두 닫으면 B가 활성화되고 reload만으로는 waiting에 남는 것을 보였다. 같은 저장소의 release-cache-rollback.md는 이미 "every tab of the scope closes or a page calls requestActivation()"으로 맞게 적는다. 고른 방법: 문장을 두 활성화 경로(requestActivation 성공, scope의 탭이 모두 닫힘)와 reload만으로는 활성화되지 않는다는 점, 템플릿의 기본 경로, 결함 있는 waiting 워커에 대한 조치(다음 release로 교체 또는 REMOVE_REGISTRATION)로 고친다. 코드는 바꾸지 않는다. 버린 대안: 없음. 리뷰가 문서 정정 하나만 제시했다. 위험·한계: 이번에 브라우저 실험을 다시 하지 않았다. 근거는 표준 SW 수명주기, 저장소 e2e 주석, 리뷰 실험 8이다. firefox는 Playwright에서 페이지가 제어되지 않아 확인 범위 밖이다. 검증: - `node scripts/verify-documentation-readiness.ts` -> PASS_SCOPED. - `grep -rln requestActivation src tests` -> src는 정의 2파일뿐. Refs: docs/reviews/2026-11-01-maturity-review/06-adapters-service-worker-push.md 06-02, 7.2절 |
||
|
|
c67edd2557 |
fix(web-push): 정상 알림 클릭이 router base path 아래 경로를 연다 (06-01)
문제: Web Push 정상 클릭은 registry path를 origin 기준으로 풀었다 (`new URL(path, origin)`). 거절된 클릭은 이미 앱 루트(= registration.scope = router base path)를 쓴다(06-09). 그래서 VITE_ROUTER_BASE_PATH=/app/ 배포에서 열린 창이 없으면 정상 클릭이 https://host/inbox, 즉 앱 밖을 열었다. registry에 /app/inbox를 넣으면 openWindow는 맞지만 같은 값이 handoff path로 페이지에 가서 router basename과 겹친다. 어떤 registry 값으로도 두 경로를 함께 맞출 수 없었다. 고른 방법: registry path를 "base path를 뺀 앱 기준 경로"로 정하고, 클릭 어댑터가 앱 루트의 pathname(끝 / 제외)을 앞에 붙여 openWindow 대상을 만든다. handoff path는 registry 값 그대로 둔다. same-origin· userinfo·hash 검사(safeTarget)는 그대로 거친다. 규칙은 WebPushNotificationDefinition.path 주석, appRootUrl 주석, 설계 8.5절에 적었다. 앱 루트가 origin 루트(기본값)면 결과가 전과 같다. 버린 대안: 리뷰가 적은 `new URL(path.slice(1), appRootUrl)`. 앱 루트가 /로 끝나지 않으면(`https://host/app`) 마지막 segment가 사라지고, `/a:b` 같은 경로는 `a:b`가 scheme으로 읽혀 거절된다. pathname을 앞에 붙이면 두 경우 모두 의도대로 된다. 위험·한계: - realtime 레시피 번들(web-push 포함) 40,879 -> 40,897 / 40,900 gzip B(+18 B, 여유 3 B). 예산은 그대로다. 다음 realtime·web-push 변경은 예산 인상과 함께 와야 한다. - 페이지가 handoff path를 basename 기준으로 쓰는지는 제품 코드 몫이라 확인하지 않았다(템플릿에는 handoff 소비자가 없다). - 실제 브라우저·푸시 서비스에서는 실행하지 않았다. 검증: - RED: 새 테스트 "opens an accepted click's route under the base path"가 수정 전 openWindow 인자 `https://app.example.test/inbox` (기대 `https://app.example.test/app/inbox`)로 실패(1 failed | 19 passed). - GREEN: 같은 테스트가 통과하고, 열린 창에는 handoff path `/inbox`가 간다. `node scripts/run-vitest.ts run tests/unit/web-push tests/unit/sub-path-deployment.test.ts tests/unit/service-worker-web-push-remediation.test.ts` -> 8파일 82건 통과(web-push-worker-runtime 20건 포함). - `npx tsc` app·test·service-worker -> 오류 0. - `npx eslint <바꾼 ts 3개> --max-warnings=0` -> 통과. - `node scripts/check-realtime-boundaries.ts` -> PASS, `node scripts/check-optional-recipes.ts` -> PASS(realtime 40897/40900), `node scripts/verify-documentation-readiness.ts` -> PASS_SCOPED. Refs: docs/reviews/2026-11-01-maturity-review/06-adapters-service-worker-push.md 06-01 |
||
|
|
5b3f5b0eb3 |
docs(realtime): 13.1에 내부 task 마감의 IDLE_TIMEOUT 뜻을 적는다 (04-02)
문제: 설계 13.1은 IDLE_TIMEOUT을 "heartbeat/byte deadline 초과 -> close + bounded reconnect" 한 뜻으로만 적는다. 코드는 같은 kind를 내부 task 마감에도 쓴다. stream coordinator는 effect·recovery·close drain 마감을 IDLE_TIMEOUT/APPLY·RECOVER·CLOSE(retryable false)로, handoff coordinator는 quiescence·checkpoint·close 마감을 IDLE_TIMEOUT/RECOVER·CLOSE(기본값 retryable)로 보고한다. 13.1만 보고 조합 코드를 쓰면 내부 마감도 재연결 대상으로 읽는다. RED(문서-코드 대조): 13.1 행은 transport 뜻 하나. 코드에서 IDLE_TIMEOUT을 만드는 곳은 transport 3곳(SSE RECEIVE, WS RECEIVE· SUBSCRIBE)과 내부 task 7곳(stream-coordinator.ts 3곳, live-poll-handoff-coordinator.ts 4곳). stream coordinator close() 주석은 "IDLE_TIMEOUT이면 아직 DRAINING"을 공개 계약으로 적는다. 고른 방법: 리뷰의 (b). 13.1 IDLE_TIMEOUT 행을 코드에 맞춰 두 뜻, operation으로 구분하는 법, 각 경우의 recovery, 관측에서 구분되지 않는다는 한계를 적는다. 코드는 바꾸지 않는다. 버린 대안: (a) stream coordinator의 마감을 APPLY_FAILED· PROVIDER_UNAVAILABLE로 바꾸기. 리뷰는 코드 3곳으로 봤지만 같은 관례가 handoff coordinator 4곳에도 있고, stream coordinator close()의 IDLE_TIMEOUT은 주석에 적힌 공개 계약이다. 바꾸려면 두 coordinator의 마감 어휘를 함께 정해야 하므로 별도 결정으로 남긴다. 위험·한계: - 리뷰 완료 기준 중 "effect 마감과 전송 idle을 관측에서 구분"은 충족하지 못했다. reconnect 관측(RUN_ENDED)에 operation이 없다. (a) 또는 관측에 operation 추가가 필요하다. - handoff 마감 결과가 retryable true(kind 기본값)이고 stream coordinator는 false인 차이는 문서에 적기만 했다. 검증: - `node scripts/verify-documentation-readiness.ts` -> PASS_SCOPED. - 코드 변경 없음. 테스트 미실행(해당 없음). Refs: docs/reviews/2026-11-01-maturity-review/04-adapters-realtime.md 04-02, 6.3절 |
||
|
|
3fe28dec2e |
fix(realtime): 배럴에서 결과 생성 함수를 내보내고 동결 규칙을 적는다 (04-01)
문제: reconnect coordinator, live/poll handoff, SSE onOpen·onEvent, WS onSubscribed·onEvent는 받은 RealtimeResult를 2단계로 동결된 객체만 받는다. 타입은 Readonly일 뿐이라 같은 모양의 평범한 객체도 컴파일된다. 그런데 동결된 결과를 만드는 realtimeSuccess / realtimeFailure는 result.ts에만 있고 배럴에 없다. 조합 코드는 배럴만 import할 수 있으므로 결과를 손으로 만들게 되고, 그러면 첫 실패나 첫 종료에서 PROTOCOL_MISMATCH·MAPPING_CONTRACT_VIOLATION으로 재시도 없이 끝난다. 이 규칙은 주석에도 없었고, reconnect 경계의 동결 검사 3곳을 지워도(MU4) 테스트가 모두 통과했다. 고른 방법: 리뷰 6.2절의 (b). 배럴 src/adapters/realtime/index.ts에서 두 함수를 export하고(추가만, 기존 시그니처 변화 없음), 엄격한 경계의 타입 주석(RealtimeReconnectOutcome, RealtimeReconnectSession, confirmTransportBarrier, handoff apply·establishAuthoritativeCheckpoint, SSE onOpen·onEvent, WS onEvent·onSubscribed)과 생성 함수 주석에 규칙을 적었다. 동결 규칙 자체와 DEFAULT_RETRYABLE 기본값은 그대로다. 버린 대안: - (c) 엄격한 경계도 stream coordinator처럼 한 번 복사하기. 규칙이 하나가 되지만 "검증한 실패 객체를 그대로 돌려준다"(toBe) 계약을 깬다. - (d) 생성 함수를 application port(shared.ts)에 두기. feature 코드도 쓸 수 있게 되지만 application 계층에 런타임 헬퍼가 는다. handoff apply를 feature가 구현한다고 정해지면 그때 옮긴다. - 런타임 오류 이름을 따로 두기(예: RESULT_NOT_FROZEN). failure kind 어휘가 바뀌는 계약 변경이라 이번 범위 밖이다. 위험·한계: - 동결하지 않은 결과는 여전히 컴파일된다. 타입으로 막으려면 brand가 필요하고, 그건 공개 타입을 깨는 변경이다. 주석과 테스트로만 알린다. - realtime 레시피 번들 40,863 -> 40,879 / 40,900 gzip B(+16 B, 여유 21 B). 예산은 그대로다. 검증: - RED: 새 테스트 "retries a failure built with the barrel's realtimeFailure"가 수정 전 `TypeError: realtimeFailure is not a function`으로 실패(1 failed | 43 passed). - 새 테스트 4건(시도의 평범한 실패, 동결된 실패 안의 평범한 error, classifyClosed의 평범한 성공 -> PROTOCOL_MISMATCH, 재시도 없음)과 handoff apply의 평범한 성공 -> MAPPING_CONTRACT_VIOLATION 1건. - MU4(reconnect 동결 검사 3곳 제거)를 다시 넣으면 새 테스트 3건이 실패한다(수정 전에는 생존). - GREEN: `node scripts/run-vitest.ts run tests/unit/realtime/` -> 14파일 230건 통과. - `npx tsc --project tsconfig.app.json --noEmit`, `npx tsc --project tsconfig.test.json --noEmit` -> 오류 0. - `npx eslint <바꾼 파일 8개> --max-warnings=0` -> 통과. - `node scripts/check-realtime-boundaries.ts` -> PASS, `node scripts/check-adapter-inventory.ts` -> PASS, `node scripts/check-optional-recipes.ts` -> PASS(realtime 40879/40900). Refs: docs/reviews/2026-11-01-maturity-review/04-adapters-realtime.md 04-01, 6.2절 |
||
|
|
eaa5b63571 |
docs(changelog): 미출시 절에 이번 브랜치의 변경과 기능 이행 순서를 적는다
문제 fix/ui-design-audit-2026-11-01 브랜치에는 다운스트림(tech-log, memento)이 따라 고쳐야 하는 변경이 쌓였는데 CHANGELOG에 한 줄도 없다. 특히 298201f(15-01)는 FeatureModule 모양을 바꾸는 BREAKING 변경이라, 커밋 본문의 BREAKING CHANGE 꼬리말만으로는 기존 기능을 어떤 순서로 옮겨야 하는지 알 수 없다. 영역 14는 check:design-system 규칙 추가가 CHANGELOG에 없다고 지적했고, 영역 07 수정(증거 형식, 분류 판정, TEMPLATE_FIXTURE 거부, 폐기 별칭 lint)도 [계약] 행이 필요하다고 각 커밋이 적었다. 고른 방법 - 기존 형식(버전 절 → 보안·계약 표 → 그 밖의 수정 → 알려진 제한)을 따라 "미출시 — 브랜치 fix/ui-design-audit-2026-11-01" 절을 0.2.0 위에 둔다. 버전 번호는 정하지 않았다. 리뷰 ID는 1101/14-02 규칙대로 라운드를 붙였다. - 15-01은 "먼저 할 일" 절로 따로 뺐다. |
||
|
|
e0c2a91d47 |
test(setup): npx vitest가 npm scope 환경변수 없이 시작한다 (1101/15-05)
문제 `npx vitest run tests/unit/ci-workflow-generation.test.ts`는 79건이 "CI runner npm scope environment invalid"로 실패한다(415건 중). npx와 npm을 거친 IDE 실행기는 npm_config_prefix·_userconfig·_globalconfig를 넣는다. CI 게이트 preflight(withCiGatePreflight)는 실제 runner에서 이 변수들을 거절하는데(옳은 동작), 테스트가 그 preflight를 프로세스 안에서 부르거나 자식으로 띄우면서 실행기의 process.env를 그대로 물려받는다. scripts/run-vitest.ts만 그중 일부를 지워서 pnpm 경로만 통과한다. 원인은 timeout이 아니라 이 환경변수다. 고른 방법 - vitest.config.ts가 NODE_ENV를 고정하는 자리에서 npm scope 변수를 지운다. config는 worker를 띄우기 전에 메인 프로세스에서 평가되므로 worker와 그 자식 프로세스 모두 깨끗한 환경으로 시작한다. 어느 실행기로 돌리든, 어느 테스트 파일이든 한 곳에서 막는다. - 지울 이름은 preflight가 쓰는 것과 같은 판정 (package-script-graph.ts의 isNpmScopeEnvironmentName, 기존 private 함수를 export)으로 고른다. 목록이 둘로 갈라지지 않는다. - ci-workflow-generation.test.ts에 "테스트 프로세스에 npm scope 변수가 없다"는 테스트를 더했다. 버린 대안 - 해당 테스트 파일의 beforeEach/afterEach에서 지우고 되돌리기(리뷰의 최소 방향 1): 같은 preflight를 띄우는 다른 파일이 생기면 다시 깨진다. - 실행 함수가 환경을 인자로 받게 하기: 자식 프로세스는 여전히 process.env를 물려받아 실패한다. - run-vitest.ts의 하드코딩 목록 정리: 이번 수정으로 필요 없어지지만, product index 생성 자식에도 쓰이고 동작이 같아 건드리지 않았다. 위험·한계 - 실제 게이트 실행기의 npm scope 거절은 그대로다. 테스트 안에서 일부러 변수를 넣는 기존 테스트 3건도 그대로 통과한다. - tests/unit 밖(component, integration 등)은 npx로 돌려 보지 않았다. 검증 - RED: npx vitest run tests/unit/ci-workflow-generation.test.ts -t "npm-launched runner" 실패 "expected [ 'npm_config_userconfig', …(2) ] to deeply equal []". 수정 전 같은 파일 79 failed / 336 passed - GREEN: npx vitest run tests/unit/ci-workflow-generation.test.ts 416 passed - npx vitest run tests/unit: 171파일 2,401 passed - tsc(node, test), eslint 바뀐 파일 통과 Refs: docs/reviews/2026-11-01-maturity-review/15-performance.md 15-05 |
||
|
|
f13ed7bea7 |
fix(docs): verify:documentation이 실패한 검사와 고칠 파일을 적는다 (1101/14-06)
문제 verify-documentation-readiness.ts는 실패 원인과 상관없이 마지막에 "FAIL_UNVERIFIED (canonical scoped-review evidence is incomplete)"를 적는다. stderr에 따로 적는 것은 README 빌드 변수 누락뿐이다. 기능을 더해 route가 늘었는데 README나 접근성 체크리스트에 route ID를 안 적으면, 개발자는 diagram 리뷰 기록을 먼저 의심하고 산출물 JSON을 열어야 원인을 안다. 고른 방법 - 검사 네 개(route scope, runtime variables, review report digest, diagram reviews)의 실패를 failedChecks로 모으고 passed는 그것이 비었는지로 정한다. 판정 조건은 그대로다. - 실패하면 검사마다 고칠 곳을 stderr에 적는다. route scope는 문서별로 빠진 route ID, diagram review는 어느 diagram이 증거 문서에 PASS로 없는지. - 마지막 줄은 "FAIL_UNVERIFIED (failed: <검사 이름들>)"이다. 판정 토큰은 그대로 둬서 이 줄을 읽는 쪽이 바뀌지 않는다. 버린 대안 - route ID 누락만 따로 적기(리뷰의 최소 방향): 다음에 다른 검사가 실패해도 같은 엉뚱한 문구가 나온다. 검사 네 개 모두 같은 방식으로 적어도 몇 줄이다. 위험·한계 - diagram review 실패는 어느 하위 조건(경로·digest·점수)인지까지는 적지 않는다. 산출물 JSON의 results에 그대로 있다. 검증 - RED: node scripts/run-vitest.ts run tests/unit/documentation-readiness.test.ts 2 failed. README에서 `EXAMPLES_PLATFORM`을 지운 사본에서 stderr가 "Documentation readiness: FAIL_UNVERIF…"뿐이라 "README.md does not name route IDs: EXAMPLES_PLATFORM"이 없다. 두 검사 실패 때도 실패 이름이 없다 - GREEN: 같은 파일 3 passed(원본 사본 PASS, route 하나 누락, route+변수 누락) - 실제 repo에서 verify-documentation-readiness PASS_SCOPED - eslint, tsc(node, test), check-ci-contract PASS Refs: docs/reviews/2026-11-01-maturity-review/14-template-product-docs.md 14-06 |