4da046683f582caaaa9eeb163a44bfecf5be4e12
643
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
4da046683f |
fix(http): 전송 전 거절의 원인을 진단에 남기고 연결 실수를 구분한다 (03-02)
문제
전송 전 실패가 네 곳에서 원인 없는 위반 FINAL_REQUEST_INVARIANT_FAILED
하나로 바뀐다. 입력 검증 실패, 요청 조립 실패 10종(PATH_PLACEHOLDER_MISSING
등), 최종 불변식 실패 12종, 미설치 계약이다. 바인딩은 이 위반과
MISSING_IDEMPOTENCY_KEY·UNEXPECTED_IDEMPOTENCY_KEY를 모두 VALIDATION_REJECTED로
바꿔 "서버가 입력값을 받아들이지 않았습니다"를 띄운다. 그래서 경로
placeholder 오타나 mutation 정책과 계약의 불일치 같은 개발자 연결 실수가
사용자 입력 문제처럼 보이고, 진단에는 원인이 없다. 미설치 계약은 실행기를
거치지 않아 진단이 0건이다. 또 마감이 시도별 budget 읽기와 최종 불변식
검사 사이에 끝나면 DEADLINE_EXPIRED도 같은 위반이 되어, 시간 초과가 "입력
거절"로 보인다(P-03-05).
고른 방법
- HttpContractViolation에 선택 필드 reason(닫힌 집합
HttpRequestRejectionReason)을 더한다. 실행기의 세 거절 지점이
refusedRequest(reason)로 위반을 만들고, finish()가 그 reason을 관측의
diagnosticReason으로 옮긴다. projector는 03-05에서 만든 경로대로
diagnostics에만 reason을 싣는다. telemetry는 error_kind 그대로다.
- 최종 불변식의 DEADLINE_EXPIRED는 budget 읽기 분기와 똑같이
TRANSPORT_FAILURE/TIMEOUT으로 끝낸다(P-03-05).
- 바인딩은 사용자가 입력을 바꿔 고칠 수 있는 거절(INPUT_INVALID,
PATH_VALUE_INVALID, QUERY_TOO_LARGE, URL_TOO_LARGE, REQUEST_BODY_TOO_LARGE)과
reason 없는 거절만 VALIDATION_REJECTED로 둔다. 나머지 reason과 멱등 키
위반은 UNKNOWN_CLIENT_FAILURE(문의 행동, "요청을 처리할 수 없습니다.")로
낸다. V2 client가 미등록 operation을 같은 종류로 내는 것과 맞췄다.
- 미설치 계약 분기는 같은 projector로 관측 1건(reason
CONTRACT_NOT_INSTALLED)을 직접 남긴다.
버린 대안
- 새 FailureKind 추가: 오류 레지스트리·i18n 카탈로그·화면 분기를 다 바꿔야
한다. 이미 있는 UNKNOWN_CLIENT_FAILURE가 "클라이언트 결함, 문의"라는 같은
뜻이고 V2에서 같은 상황에 쓰고 있다.
- 리뷰 예시대로 MAPPING_CONTRACT_VIOLATION으로 내기: 문구가 "서버 응답을 화면
데이터로 바꾸지 못했습니다"라 응답이 없는 전송 전 실패와 맞지 않는다.
- 사용자 입력 쪽을 reason별 Record로 망라하기: 컴파일 시 분류를 강제하지만
20여 줄이 는다. 새 reason은 기본으로 클라이언트 결함이 되는 쪽이 안전하므로
입력 쪽 5개만 Set으로 적었다.
- terminalReason에 원인을 싣기(리뷰 문구): 03-05와 같은 이유로 버렸다.
위험·한계
- 동작 변경: 멱등 키 위반과 연결 실수가 VALIDATION_REJECTED에서
UNKNOWN_CLIENT_FAILURE로 바뀐다. 폼은 필드 오류 대신 "unavailable" 상태
안내를 띄운다. 기존 계약 테스트의 기대값을 이에 맞게 바꿨다.
- 입력 검증 실패(INPUT_INVALID)는 리뷰 문구("입력 크기 초과만")와 달리
VALIDATION_REJECTED로 남겼다. 입력 validator의 거절은 사용자 입력 문제다.
- reason 없는 FINAL_REQUEST_INVARIANT_FAILED(다른 실행기 구현)는 기존대로
VALIDATION_REJECTED다.
- AppFailure.code는 지금처럼 위반 종류다. 원인 코드는 진단에만 있다.
- 공개 타입은 추가만 했다(위반 선택 필드 1개, 진단 reason 집합 확장).
- validator가 throw하는 경우(VALIDATOR_RUNTIME_FAILURE → SCHEMA_MISMATCH,
"서버 응답 데이터가…" 문구)는 이번 범위가 아니라 그대로다.
- 미설치 계약 거절도 다른 CONTRACT_VIOLATION처럼 api.request.failed
telemetry 1건을 낸다(VD-07 규칙 5).
- 화면: 정상 상태는 그대로이고 위 실패에서만 문구가 바뀐다. 시각 골든은
다시 찍지 않았다.
검증
- RED(수정 전):
- http-execution-v3-observability "names a refused request's assembly
cause in diagnostics only (03-02)": violation.reason 없음.
- 같은 파일 "ends a deadline that expires at the final invariant check as
a timeout (P-03-05)": TRANSPORT_FAILURE 기대, 실제 CONTRACT_VIOLATION.
- feature-http-binding 계약 테스트 5건: PATH_PLACEHOLDER_MISSING,
CONTRACT_NOT_INSTALLED, HEADER_NOT_ALLOWED, MISSING_IDEMPOTENCY_KEY,
UNEXPECTED_IDEMPOTENCY_KEY가 VALIDATION_REJECTED로 나옴.
- runtime-adapters-auth-profile "is refused without a fetch and leaves one
diagnostic naming the cause": reason 없음, 진단 0건.
- GREEN: 세 파일 38/38 통과.
- 회귀: run-vitest tests/unit tests/integration tests/component
tests/features tests/contract tests/runtime-schema(pnpm을 언급하는 파일
13개 제외) 227 files 중 226 통과, 2354/2355. 실패 1건은
provider-guardian-transaction의 ENOSPC(inotify watcher 한도, 이 머신의
다른 실행 때문)로 HTTP와 무관하다. 제외했던 http-scenario-evidence는
pnpm을 띄우지 않아 따로 돌렸고 14/14 통과.
tsc app/test/node rc=0. 바꾼 파일 eslint rc=0.
check-adapter-inventory PASS. verify-documentation-readiness PASS_SCOPED.
- 미실행: check:architecture(pnpm 스크립트 필요), 번들 크기 측정.
Refs: docs/reviews/2026-11-01-maturity-review/03-adapters-http-state.md
|
||
|
|
f8a492a6ad |
fix(http): 문제 응답 분류기 실패를 진단 reason으로 남긴다 (03-05)
문제 기능 패키지의 classifyProblem이 throw하거나 집합 밖 값을 돌려주면 classifyProblemEffect는 MAYBE_APPLIED + contractRuntimeFailure: true를 돌려준다. 주석과 설계서(closed-deep-design.md:650)는 이것을 "contract runtime failure로 기록한다"고 적지만, 실행기는 .effect만 쓰고 플래그를 버린다. 그래서 분류기가 throw한 409와 분류기가 정말 MAYBE_APPLIED라고 답한 409의 관측 기록·진단이 요청 id 말고 똑같다. 또 이 안전 기본값을 NOT_APPLIED로 바꿔도(변이 M5) 영역 테스트가 하나도 실패하지 않는다. 고른 방법 - HttpExecutionObservation에 선택 필드 diagnosticReason을 더한다. 타입은 닫힌 집합 HttpDiagnosticReason이고 지금 값은 CLASSIFIER_FAILED 하나다. 문제 응답 admission이 명령의 contractRuntimeFailure를 이 값으로 바꾸고, finish()가 관측 기록에 싣는다. - 조립 지점의 projector는 이 값을 diagnostics에만 reason으로 더한다 (reason은 이미 허용 목록의 taxonomy 키). telemetry 속성은 그대로다. - 효과는 계속 MAYBE_APPLIED다. 재시도 판단에 쓰는 certainty는 건드리지 않았다. 버린 대안 - 리뷰 문서 문구대로 terminalReason을 CLASSIFIER_FAILED로 바꾸기: terminalReason은 "sink로 나가지 않는 내부 라벨"(VD-07 5-1)이고, 문제 응답에서는 certainty 값이 그대로 terminalReason이 되며 재시도 차단 조건(certainty !== "MAYBE_APPLIED")에도 쓰인다. 값을 바꾸면 그 이중 차단이 하나로 줄고, projector가 문자열을 걸러 내야 한다. 별도 닫힌 타입 필드가 의도가 더 잘 보인다. - 플래그와 주석 문장을 지우기(리뷰의 두 번째 안): 운영자가 "결과 불명"이 분류기 결함 때문인지 구분할 수단이 계속 없다. 위험·한계 - classifyStatus(401·403·429) 분류기의 throw는 지금처럼 MAYBE_APPLIED만 내고 reason을 남기지 않는다. 그 함수는 기록을 주장하지 않아 이번 범위에서 뺐다. - 공개 타입은 추가만 했다(관측 선택 필드 1개, 배럴 type export 1개). - VD-07 5-1에 reason 전달 규칙을 적었다. 검증 - RED(수정 전): tests/integration/http-execution-v3-observability.test.ts "keeps MAYBE_APPLIED and records a failed problem classifier in diagnostics only (03-05)" 실패. 기대 reason "CLASSIFIER_FAILED", 실제 undefined. - GREEN: 같은 파일 7/7 통과. 변이 M5(catch를 NOT_APPLIED로)를 다시 넣으면 이 테스트가 실패하는 것을 확인하고 원복했다. - 회귀: run-vitest tests/integration tests/features/reference-feature tests/unit/http-execution-v3.test.ts 30 files / 302 tests 통과. tsc app/test/node rc=0. 바꾼 파일 eslint rc=0. check-adapter-inventory PASS. - 미실행: check:architecture(pnpm 스크립트 필요). Refs: docs/reviews/2026-11-01-maturity-review/03-adapters-http-state.md |
||
|
|
5e6be9a92f |
fix(registry): breaking 증거를 그 증거가 설명하는 값에 묶는다 (0929/07-01)
문제
breaking 증거 조회 키는 registryId:row:field:kind뿐이고, 증거 검사는
5필드가 비었는지만 본다. 값은 diff에 있지만 증거와 비교하지 않는다. 그래서
한 번 증거를 쓴 row·field는 다음 변경도 새 증거 없이 통과한다. 실험 X3:
REFERENCE_RESOURCE_DETAIL.path를 08-13 증거가 설명하는
/examples/reference-resources/items/:resourceId가 아닌
.../entries/:resourceId로 바꿔도 check-registries가 "11 registries
PASS"였다. 공개 URL·API 경로·저장 키 같은 breaking 변경이 이행·롤백
계획 없이 지나간다.
고른 방법 (리뷰 최소 개선 (1))
- 값이 있는 breaking 변경(change.after가 있음)은 증거 행에 after가 있어야
하고, canonical JSON이 diff의 after와 같아야 한다. 없으면 "evidence
needs after", 다르면 "evidence explains after=..., the change is
after=..."로 실패한다. 키 순서·원시값 배열 순서는 기존 canonical 규칙
그대로라 차이로 보지 않는다.
- 삭제(row·registry·field 삭제)는 설명할 값이 없어 after를 요구하지 않는다.
- 현재 diff와 맞는 템플릿 증거 1건(REFERENCE_RESOURCE_DETAIL.path)에
after를 더했다. ci-quality-gates.md의 증거 안내에 after를 적었다.
- 완전한 증거를 만드는 테스트 두 곳(registry-compatibility,
registry-governance tamper 사례)에 after를 넣었다.
버린 대안
- after를 선택 필드로 두기: 없는 행은 지금처럼 모든 다음 변경을 통과시켜
X3이 그대로 남는다.
- 증거 키에 값 해시를 넣기(changeId 형식 변경): 기존 changeId 문법과
출력이 바뀌고 사람이 읽을 수 없다.
- 리뷰 (2) 현재 diff와 맞지 않는 증거 행 실패 또는 목록 출력, (3)
update:registry-baseline의 증거 정리: 실패로 할지 출력으로 할지, 오래된
14건을 지울지 이력 파일로 옮길지가 감사 기록을 다루는 결정이라 이번에
하지 않았다.
위험·한계
- 증거 파일 형식이 바뀐다. 다운스트림이 이 검사를 동기화하면 아직 diff에
남은 breaking 변경의 증거 행마다 after를 넣어야 게이트가 통과한다.
다음 릴리스 CHANGELOG [계약] 행이 필요하다(미출시 절이 없어 적지
않았다).
- 오래된 증거 행(현재 diff와 무관한 14건, 0929/07-02 수정으로 쓰이지 않게
된 VITE_BUILD_ID 포함)은 그대로 남는다. 위 (2)·(3)이 남은 일이다.
- 값이 큰 contract 필드(allowedValues 전체 등)의 증거는 그 값을 통째로
적어야 한다.
검증
- RED(수정 전): registry-compatibility.test.ts 새 사례 2건 실패
("rejects evidence written for another value", "requires the explained
value": expected [] to deeply equal [...]). X3 변이로 check-registries
"11 registries PASS".
- GREEN: 같은 X3 변이에서 check-registries 실패("evidence explains
after=\"/examples/reference-resources/items/:resourceId\", the change is
after=\"/examples/reference-resources/entries/:resourceId\""), 변이 없이
"11 registries PASS". registry-compatibility·registry-governance·
release-artifacts·second-api-feature-registries 53/53 통과.
compatibility fixtures 11 PASS. verify-documentation-readiness
PASS_SCOPED.
- 회귀: tsc node/test rc=0, 바꾼 파일 eslint rc=0.
- 미실행: check:architecture(pnpm), test:sample-removal(pnpm).
Refs: docs/reviews/2026-09-29-maturity-review/07-contracts.md
|
||
|
|
82c9e594ff |
fix(registry): 선언된 null 전환과 허용값 추가를 breaking으로 막지 않는다 (0929/07-02)
문제
레지스트리 호환성 분류기(scripts/lib/registry-compatibility.ts)는 값의 JS
타입이 다르면 breakingFields를 보기 전에 field-type-changed(breaking)로
판정한다. null과 문자열은 타입이 달라서, governance가 string|null로
선언하고 breaking 필드에서 뺀 필드(navigationLabel, navigationOrder, API
timeoutMs, 저장 ttl, ENV defaultValue)를 null <-> 값으로 바꾸기만 해도
breaking 증거를 요구한다. contract의 allowedValues에 값을 더하는 것도
어떤 변경이든 breaking이다. 그래서 증거 5필드에 쓸 내용이 없는 변경에
"마이그레이션·롤백"을 지어 쓰게 된다. 템플릿 자신도 VITE_BUILD_ID
defaultValue null -> "local-build"에 "the value itself did not change"라고
적은 breaking 증거를 남겼다.
고른 방법 (리뷰 최소 개선 B)
- 행 필드: 한쪽이 null이고 두 값이 모두 그 필드의 선언 타입
(contract.fieldTypes, 예 string|null)에 맞으면 타입 변경이 아니라
field-changed로 보고 breakingFields로 등급을 정한다. 선언이 없거나
선언 밖 값이면 지금처럼 field-type-changed(breaking)다.
- contract allowedValues: 필드 집합이 같고 필드마다 이전 허용값을 모두
포함하면 allowed-values-extended(additive)다. 값 하나라도 빠지거나,
새 필드를 제한하거나, 제한을 없애면 지금처럼 breaking이다. 나머지
contract 변경도 그대로 breaking이다.
- 선언 타입 판정은 check-registries.ts에 있던 runtimeType·
matchesDeclaredType을 lib로 옮겨 검사기와 분류기가 같은 함수를 쓴다.
- semantic-diff.json fixture에 nullable-field-cleared(behavior-change),
registry-contract-extension(additive)을 더하고 artifact id 목록에도
넣었다.
버린 대안
- 현 상태 + "이런 변경은 재승인하라"는 문서: 재승인이 증거를 대신하는
길을 더 넓힌다(0929/07-04).
- nullable 필드 판단 전체를 breakingFields로 옮기기(리뷰 C): 다른
레지스트리 영향을 다시 봐야 하는 넓은 변경이다.
- 제한 해제(allowedValues에서 필드 키 삭제)를 additive로 보기: 리뷰
기준("이전 값을 모두 포함")에 맞지 않고 판단이 하나 더 필요해 보수적으로
breaking에 남겼다.
위험·한계
- fail-closed 범위가 줄어든다. 선언 타입 안의 null 전환이 의미("기능
꺼짐")를 갖는 필드는 breakingFields에 넣어야 breaking으로 남는다.
paramsSchema·searchSchema는 이미 breakingFields라 그대로 breaking이다.
- 현재 기준선 diff에서 VITE_BUILD_ID defaultValue가 breaking에서
behavior-change로 바뀐다. registry-change-evidence.json의 해당 증거 행
(field-type-changed)은 이제 어떤 변경과도 맞지 않는다. 오래된 증거 정리는
0929/07-01 범위라 이번에는 지우지 않았다.
- 다운스트림의 같은 종류 증거 행도 쓰이지 않게 된다. 게이트 판정이
바뀌는 변경이라 다음 릴리스 CHANGELOG에 [계약] 행이 필요하다(이번
라운드는 CHANGELOG 미출시 절이 없어 적지 않았다).
- fieldTypes 키가 점 경로(a.b)인 필드는 행의 최상위 필드 이름과 맞지 않아
계속 breaking으로 남는다.
검증
- RED(분류기 수정 전): registry-compatibility.test.ts 새 사례 5건 실패
(null 전환 3건이 breaking/field-type-changed, nullable breaking 필드의
kind, allowlist 확장 breaking). check-registry-compatibility-fixtures:
nullable-field-cleared actual breaking, registry-contract-extension
actual breaking.
- GREEN: registry-compatibility·registry-governance·release-artifacts·
second-api-feature-registries 49/49 통과. compatibility fixtures 11 PASS.
check-registries "11 registries PASS"(남은 breaking은
REFERENCE_RESOURCE_DETAIL.path 하나, 증거 있음).
ci-artifact-contract "semantic validator" 사례 통과.
- 회귀: tsc node/test rc=0, 바꾼 파일 eslint rc=0.
- 미실행: check:architecture(pnpm). tests/system 나머지(provider guardian
exit=126 환경 문제로 이 변경과 무관하게 실패).
Refs: docs/reviews/2026-09-29-maturity-review/07-contracts.md
|
||
|
|
fc303d89bc |
refactor(contracts): 폐기 별칭 import를 새 이름으로 옮기고 lint로 막는다 (07-01)
문제
MappingResult라는 이름이 두 모양을 가리킨다. external-contract-runtime.ts의
MappingResult({ ok:false, error:{ kind, code } })는 주석이 "정본"이라고
부르지만 테스트 말고 쓰는 곳이 없다. boundary-mapper.ts는
{ ok:false, code } 모양을 BoundaryMappingResult로 이름 붙이고 같은 이름
MappingResult를 @deprecated 별칭으로 남겼는데, 실행 경로가 그 별칭을
요구한다(feature-http-binding mapSuccess, client.ts, resource-mapper,
참조 mapper, boundary-mapper 자신의 helper 반환 타입). 그래서 별칭의 제거
조건("이 파일에서 MappingResult를 import하는 모듈이 없을 때")이 충족될 수
없다. ApiFailure 별칭도 포트 2개와 참조 기능을 포함해 7개 파일이 쓴다.
eslint 설정에 폐기 검사가 없다.
고른 방법 (리뷰 최소 개선 (1)·(4)와 lint, 공개 이름은 그대로)
- boundary-mapper의 BoundaryMapper.map, mapWithBoundaryRegistry,
mappingSuccess, mappingFailure와 바인딩 mapSuccess가
BoundaryMappingResult를 반환한다. 참조 mapper·client·resource-mapper도
옮겼다. ApiFailure를 쓰던 파일은 AppFailure를 쓴다. 타입이 같아서
런타임과 공개 시그니처는 바뀌지 않는다.
- D-15 주석을 실제와 맞췄다. 기능 mapper와 HTTP 바인딩은
BoundaryMappingResult(닫힌 실패 코드)를 반환하고, 계약 패키지 쪽 결과가
필요하면 toContractMappingResult로 바꾼다. 참조 기능 README의 "ApiFailure는
같은 type의 alias" 문장도 고쳤다.
- 폐기 검사: 이 repo의 ESLint는 babel 파서라 타입 정보가 없어
@typescript-eslint/no-deprecated를 쓸 수 없다. 대신 core
no-restricted-imports의 patterns.importNames로 boundary-mapper의
MappingResult와 errors의 ApiFailure import를 src·tests 전체에서 막는다.
층별 no-restricted-imports 설정이 같은 규칙을 덮어쓰므로
restrictedImports()가 별칭 패턴을 항상 덧붙이고, 층 규칙이 없는 파일은
그 앞에 둔 공통 블록이 받는다.
버린 대안
- 별칭 export 삭제와 정본 이름을 ContractMappingResult로 바꾸기(리뷰 (2)
후반·(3)): 다운스트림 import를 깨는 공개 이름 변경이다. 이번 묶음 규칙상
공개 시그니처를 깨는 변경은 하지 않는다. 별칭 주석에 "repo 안 사용 0,
lint로 강제, 제거는 minor 릴리스 + CHANGELOG [계약] 행"을 적었다.
- typescript-eslint 도입 후 no-deprecated: 새 의존성과 type-aware lint
설정(속도·설정 범위)이 필요하다.
- 바인딩이 정본 모양을 받게 바꾸기(리뷰 C): 실패 코드가 닫힌 3종에서 자유
문자열로 넓어져 계약이 약해진다.
위험·한계
- 이름 MappingResult는 여전히 두 파일에서 export된다(한쪽은 폐기 별칭).
리뷰 완료 기준("MappingResult export 하나, grep 0건")은 별칭을 지워야
충족된다. 제거 시점은 릴리스 결정으로 남긴다.
- 다운스트림이 eslint.config.ts를 동기화하면 그쪽의 별칭 import가 lint
오류가 된다. 이름만 바꾸면 된다(tech-log는 mappingSuccess를 쓰는데,
반환 타입은 같은 모양이라 영향 없음).
- adapters/http의 client.ts·feature-http-binding.ts는 타입 이름만 바꿨다.
같은 파일을 고치는 다른 수정과 합칠 때 줄 단위 충돌이 날 수 있다.
검증
- RED: 규칙만 먼저 넣고 eslint src tests -> 9개 파일 11 errors
("'MappingResult' import from '../../contracts/boundary-mapper.ts' is
restricted ... deprecated alias: import BoundaryMappingResult", ApiFailure
같은 꼴).
- GREEN: lint 전체 범위(src scripts tests recipes .storybook 설정 파일)
--max-warnings=0 rc=0. src에서 별칭을 쓰는 곳은 정의 줄뿐(git grep).
- 회귀: tsc app/test/node rc=0. run-vitest tests/architecture tests/unit
tests/features tests/platform tests/component tests/contract
tests/runtime-schema tests/integration(pnpm·corepack을 띄우는 4파일 제외)
273 files / 3136 tests 중 3135 통과. 실패 1건은
provider-guardian-transaction(guardian exit=126, 단독 실행도 같음, 이
변경과 무관한 scripts/lib 프로세스 테스트).
check-registries PASS, verify-documentation-readiness PASS_SCOPED,
check-adapter-inventory PASS.
- 미실행: check:architecture(pnpm 필요). depcruise 직접 실행은 0 modules로
사실상 미검증.
Refs: docs/reviews/2026-11-01-maturity-review/07-contracts.md
|
||
|
|
32da8a40e9 |
test(contracts): 조립기·선언 검증의 쓰기 API 규칙 5개를 고정한다 (07-06)
문제 조립기와 선언 검증의 쓰기 API 규칙 5개는 지워도 관련 테스트가 모두 통과한다(리뷰 변이 MX1·MX2·MX5·MX6·MX9). - MX1 읽기 operation의 command descriptor 금지 (external-contract-runtime.ts). 실행기는 쓰기 여부를 메서드가 아니라 commandEffect !== null로 정하므로 GET이 쓰기로 처리되는 것을 막는 유일한 경계다. - MX9 KEYED 쓰기의 복구 descriptor 필수 - MX6 NEVER 재시도와 재시도 예산 1 이상의 모순 거부 - MX5 V2 KEYED_COMMAND의 idempotencyKeyPolicy REQUIRED 정합 (api-operations.ts) - MX2 mapper 레지스트리 키 = mapperId (boundary-mapper.ts) 조립기는 여러 번 다시 쓰인 파일이라 규칙 줄이 빠져도 CI가 모른다. 고른 방법 규칙마다 그 규칙만 어긴 행 하나로 실패 사례를 둔다. 오류 메시지는 기능 작성자가 쓰기 API 규칙을 배우는 통로라 reason 문자열을 그대로 단언한다. 정상 대조군은 기존 사례(TEST_CONTRACT_CONTRIBUTION 조립, command() 정의, 키가 맞는 mapper 등록)를 쓰거나 같은 테스트 안에 둔다. 코드 변경은 없다. 버린 대안 - 메시지 대신 ContractContributionError 종류만 단언: 다른 규칙이 먼저 실패해도 통과해서 변이를 놓칠 수 있다. 위험·한계 - 메시지 문구를 바꾸면 테스트도 바꿔야 한다. 의도한 결합이다. - MX6은 실행기(http-retry-lifecycle)가 한 번 더 막는다. 이 테스트는 조립 단계의 안내 메시지를 지킨다. 검증 - RED: 변이 5개를 하나씩 넣고 바꾼 3파일을 돌렸다. 이 커밋 전 테스트로는 5개 모두 살아남음(26/26 통과). 새 테스트로는 5개 모두 죽음, 각 변이마다 해당 사례 1건만 실패(30/31). - GREEN: 변이 없이 31/31 통과. - 회귀: tsc test rc=0, 바꾼 파일 eslint rc=0. Refs: docs/reviews/2026-11-01-maturity-review/07-contracts.md |
||
|
|
3c31576940 |
test(contracts): V2 행과 V3 descriptor를 양방향과 스키마 id까지 맞춰 본다 (07-02)
문제
HTTP API 하나를 V2 행(check:registries가 보는 선언)과 V3 descriptor(실제로
실행되는 사본)에 두 번 쓴다. 15-01 뒤에도 둘은 feature-runtime.ts의
apiContract와 contractContributions로 나뉘어 그대로 두 벌이다. 둘을 잇는
parity 테스트는 V2 행에서 V3를 찾는 한 방향이고 6필드만 비교한다. 그래서
V3 검증기의 schemaId를 바꾸거나(L1) V3에만 API를 추가해도(L6) 테스트가
통과한다. V3에만 있는 API는 공개 경로·메서드가 FE-REG-API 게이트 밖에서
실행된다. "V2는 게이트용, V3는 실행용"이라는 사실은 테스트 주석에만 있다.
고른 방법 (리뷰 5.1절의 B, 1단계)
- 두 사본의 operation id 집합이 같아야 한다(양방향). V3만 있는 API와
V2만 있는 API가 각각 실패한다.
- 비교 필드에 같은 사실의 사본 넷을 더했다: 쓰기 여부(V2 semantics ↔ V3
commandEffect 유무, 실행기가 쓰기를 메서드가 아니라 effect로 정하므로),
요청 본문(V2 requestSource body ↔ V3 requestBody JSON), 입력 스키마 id
(V2 pathSchema/requestSchema 중 NoRequest가 아닌 것 ↔ V3 inputValidator),
응답 스키마 id(V2 responseSchema ↔ V3 outputValidator).
- V2가 path와 request 스키마를 둘 다 가진 operation은 V3 입력 스키마 하나와
대응 규칙이 아직 없다. 조용히 넘기지 않고 테스트가 실패하며 규칙을
정하라고 알린다. 지금 설치된 operation에는 없다.
- RestOperationV2 위와 starter-experience.md "Adding a feature"에 V2는
게이트용 선언, V3는 실행 사본이고 둘 다 쓴다는 것을 적었다.
버린 대안
- V2 행을 V3에서 생성(5.1절 C)하거나 FE-REG-API 스냅샷을 V3에서 투영하고
V2 행을 없애기(D): 생성기·투영 함수와 기준선 재승인이 필요한 구조
변경이라 이번 범위를 넘는다. 15-01로 V2와 V3가 같은
defineFeatureRuntime 객체에 모였으므로 D로 갈 때 기능 단위 투영 지점은
생겼다.
- "V2 행이 1개 이상" 단언: test:sample-removal이 참조 기능을 지운 사본에서
이 파일을 돌리면 두 집합이 모두 비어 정상인데 실패한다. 양방향 집합
비교가 한쪽만 빈 경우를 잡는다.
- 두 번째 기능 테스트(second-api-feature-registries)에 V3 기여 넣기:
fixture 복사본에서 check:registries를 도는 테스트라 V3 기여를 넣어도 이
parity 검사가 그 사본에서 돌지 않는다. 비용 대비 효과가 작아 뺐다.
위험·한계
- 시간 제한(V2 timeoutMs null ↔ V3 totalDeadlineMs 10000, L3)은 비교하지
않는다. 맞추려면 V2 행 값을 바꿔야 하고 FE-REG-API 기준선이 바뀐다.
주석에 비교하지 않는다고 적었다.
- 응답 스키마 본문, unknownFieldPolicy ↔ zod strip/strict(L7), 손 guard ↔
zod DTO 차이는 여전히 대조하지 않는다.
- 설치된 기능에 대한 테스트다. CI 밖에서 V3만 추가한 다운스트림은 이
파일을 돌려야 걸린다.
검증
- RED: 기존 테스트와 새 테스트를 같은 변이에 돌렸다.
L1(V3 GET_REFERENCE_RESOURCE outputValidator schemaId를
ReferenceResourcePayloadV2로): 기존 통과, 새 테스트 실패
("responseSchema": "ReferenceResourcePayload" vs "...V2").
L6(V3에만 GET_REFERENCE_RESOURCE_V3_ONLY 추가): 기존 통과, 새 테스트
"cover the same operations" 실패(+ "GET_REFERENCE_RESOURCE_V3_ONLY").
- GREEN: 변이 없이 2/2 통과.
- 회귀: tsc test rc=0, 바꾼 파일 eslint rc=0. 전체 회귀는 다음 커밋들과
함께 마지막에 돌렸다(이 커밋의 src 변경은 주석뿐).
Refs: docs/reviews/2026-11-01-maturity-review/07-contracts.md
|
||
|
|
c06338956e |
fix(contracts): 참조 기능 밖의 TEMPLATE_FIXTURE 기여를 거부한다 (07-04)
문제
조립기(composeContractContributions)의 TEMPLATE_FIXTURE 분기는
fixtureId·revision·이벤트 0개만 보고 featureId를 보지 않는다. 참조 기여
파일을 복사한 제품 기능(order)이 fixture 출처 그대로 조립을 통과한다.
fixture 기여는 계약 집합(externalPackages)에 들어가지 않으므로 그 API는
실행되지만 부팅 때 릴리스 계약 정합 검사에서 경고 없이 빠진다. 설계서
§4.8은 "product feature는 반드시 EXTERNAL_PACKAGE", §24.5는 정적 검사가
product TEMPLATE_FIXTURE를 거부한다고 적지만 구현이 없다.
고른 방법
- 조립기 fixture 분기에서 featureId가 fixture의 주인과 다르면
ContractContributionError로 실패한다. 메시지가 EXTERNAL_PACKAGE를
쓰라고 안내한다.
- fixture 기여가 둘 이상이면 실패한다(설계서의 "유일한 예외").
- 15-01 뒤 조립은 기능 적재 때마다 전체를 다시 조립하므로 두 검사 모두
기능이 따로 적재돼도 걸린다. registry.install의 featureId 일치 검사가
있어 다른 기능이 참조 기능 id를 빌려 쓰는 길도 막혀 있다.
- 주인 featureId는 리터럴로 쓰지 않고 fixtureId에서 만든다
(REFERENCE_FEATURE_V1 -> 대문자 스네이크를 소문자 kebab으로, _V1 제거).
이유를 주석에 적었다.
- starter-experience.md "Adding a feature"에 제품 기여는
EXTERNAL_PACKAGE라는 문장을 넣었다.
- contract-snapshot-bypass의 "iterator에 숨긴 이벤트" 테스트는
featureId test-feature의 fixture를 썼다. 새 검사가 그 행을 먼저 막아
테스트가 아무것도 확인하지 못하게 되므로 EXTERNAL_PACKAGE 출처로
바꿨다. 패키지 출처는 이벤트를 받으므로 숨긴 이벤트를 읽으면 설치되어
단언이 실패한다. 예전 fixture 출처는 이벤트가 하나라도 있으면 던져서
읽었는지 아닌지를 구분하지 못했다.
버린 대안
- 리뷰 문서 그대로 featureId !== "reference-feature" 리터럴 비교:
test:sample-removal이 샘플 제거 뒤 src/·tests/ 전체에서
/REFERENCE_RESOURCE|reference-feature|reference-resource/i를 찾아
잔여물로 실패시킨다(scripts/test-sample-removal.ts:95). 플랫폼 코드와
남는 단위 테스트에 그 id를 쓰면 이 게이트가 깨진다.
- 조립기에 허용 featureId 인자를 추가하거나 feature module에 fixture 표시
필드를 추가: 공개 함수·타입 변경이라 이번 범위를 넘는다.
- 정적 검사(dependency-cruiser) 규칙: 출처 종류는 import가 아니라 값이라
depcruise로 볼 수 없다.
위험·한계
- 실패 시점은 15-01 구조에 따라 부팅이 아니라 그 기능의 런타임 적재
(라우트 진입) 때다. Node 쪽 loaded-feature-runtimes와 레지스트리
스크립트는 import 때 전부 조립하므로 CI에서는 바로 드러난다.
- scripts/scale/measure-feature-shape-growth.ts는 참조 기능을 이름만 바꿔
복사하고 REFERENCE_FEATURE_V1을 그대로 둔다. 그 복사본은 이제 조립에서
거부된다. 이 스크립트는 tsc와 vite build만 하고 기여를 조립하지 않아
측정에는 영향이 없다(실행하지 않음).
- 주인 id 유도는 fixtureId가 "<기능 id 대문자 스네이크>_V<revision>"
꼴이라는 이름 규칙에 기댄다. fixtureId는 닫힌 리터럴 하나라 지금은
참조 기능 id 하나로만 풀린다.
검증
- RED(수정 전 조립기): 새 테스트 2건 실패.
external-contract-runtime "rejects a fixture copied into a product
feature" -> "Expected contract composition to fail."
reference-fixture-provenance "rejects a second fixture contribution"
-> "expected undefined to be 'reference-feature: only one
TEMPLATE_FIXTURE contribution is allowed'".
- GREEN: 같은 3파일 22/22 통과.
- 회귀(
|
||
|
|
68e88b081d |
fix(opfs): 객체를 못 지운 purge가 완료와 chunk sweep을 보고하지 않는다 (0929/05-02)
문제: OPFS purge는 remove가 CONFLICT·NOT_FOUND면 그 객체를 건너뛴다.
chunk sweep 조건은 "남은 객체가 없다"가 아니라 !moreObjectsAvailable
&& !deadlineReached && !aborted라서, 다른 탭이 같은 객체를 덮어쓰는 동안
ACCOUNT_DELETION purge를 부르면 {removedObjects: 0,
moreObjectsAvailable: false, chunkSweep: "COMPLETED"}를 돌려준다. 객체와
chunk는 남아 있는데 보고는 완료로 읽힌다. port 주석은 sweep이 "once
every object is removed"라고 약속하고 runbook도 COMPLETED를 완료
조건으로 적는다.
고른 방법: 지난 리뷰의 첫 방향. 건너뛸 때 moreObjectsAvailable을 true로
두어 report가 미완료를 드러내고 sweep 조건이 sweep을 막게 한다
(chunkSweep 칸이 빠진다). port 계약은 바꾸지 않고 코드를 기존 주석에
맞춘다. 이 값을 뒤에서 false로 되돌리는 대입이 없다는 근거(다음
페이지로 넘어가는 대입은 그 페이지에 객체가 더 있을 때만 실행되고,
PRESSURE는 sweep하지 않는다)를 코드 주석에 적었다. port의
moreObjectsAvailable 주석과 runbook에 "다시 호출한다"를 더했다.
버린 대안:
- skippedObjects 칸을 report에 더하고 완료 조건을 "skippedObjects === 0
그리고 COMPLETED"로 고친다: port 추가와 문서 조건 변경이 필요하고
번들도 더 커진다. offline-indexeddb 예산 여유가 9 B뿐이다.
- 따로 skipped 플래그를 두고 끝에서 합친다: 같은 동작에 바이트가 더 든다.
위험·한계:
- offline-indexeddb 레시피 번들 36,891 -> 36,896 / 36,900 gzip B.
예산은 올리지 않았지만 여유가 4 B로 줄었다([0929] 05-04).
- 별도로 발견했고 고치지 않은 것: 여러 페이지에 걸친 purge는 마지막
페이지의 OR 대입이 앞 페이지에서 넘어올 때 넣은 true를 유지해, 다
지워도 moreObjectsAvailable true를 보고하고 sweep하지 않는다. 보수적
방향이라 다시 부르면 끝나지만 한 번에 끝나지 않는다. 코드로만
확인했고 실행하지 않았다. 동작 변경이라 범위 밖.
- 실제 브라우저(Playwright OPFS spec)에서는 돌리지 않았다.
검증:
- RED: opfs-worker-runtime "reports a purge that skipped a changing object
as unfinished"가 `- "moreObjectsAvailable": true`
`+ "moreObjectsAvailable": false`로 실패(removedObjects 0, 6번째 칸
chunkSweep 존재).
- GREEN: 같은 파일 64/64 통과. 두 번째 purge가 removedObjects 1,
chunkSweep COMPLETED, partition 파일 0개로 끝난다.
- 회귀: opfs-worker-runtime, opfs-byte-store, indexeddb-opfs-journal,
indexeddb-local-draft 4파일 104/104 통과. tsc app·test·web-worker·
recipes 통과, eslint 통과, verify-documentation-readiness PASS_SCOPED,
check-optional-recipes PASS.
Refs: docs/reviews/2026-09-29-maturity-review/05-adapters-storage-kernel.md
|
||
|
|
cc011bc740 |
docs(platform): kernel 주석의 줄 번호 참조를 심볼 이름으로 바꾼다 (05-05)
문제: kernel 주석이 근거를 다른 파일의 줄 번호로만 준다. 줄이 밀려 참조 20개 중 19개가 엉뚱한 코드를 가리킨다. 예를 들어 indexeddb-transaction.ts의 "runtime은 지운 행 수로 예산을 잰다"는 indexeddb-runtime.ts:2384를 가리키는데 그 줄은 cursor 삭제 onerror다. 네 벌의 transaction 상태 기계를 가리키는 참조 넷은 kernel 이전 코드라 이미 없다(네 어댑터 모두 지금은 runIndexedDbTransaction을 쓴다). 고른 방법: 리뷰 권고대로 줄 번호 대신 심볼 이름을 쓴다. - purgeEligibleRecords, scanBatch, monotonicClock, runCheckpointTransaction, bindScope, 체크포인트 store의 translate, BT-UP-03, restrictedBrowserDataProperties, browser-data-boundary 예외 목록, REQUIRED_ABORT_CONSUMERS. - 없어진 코드를 가리키던 역사 설명은 "IDB-X-02 이전에는 네 벌이 달랐다", "runtime의 kernel 이전 fail/requestFailed 의미"처럼 ID와 과거형으로 줄였다. "runtime이 지금 inline으로 한다"처럼 더는 사실이 아닌 문장은 지웠다. - 유일하게 맞던 abortable-operation.ts:11도 같은 규칙으로 줄 번호만 뺐다(심볼 AbortTerminalReason이 이미 문장에 있다). 버린 대안: 줄 번호를 지금 위치로 다시 맞추기. 다음 수정에서 또 밀린다. 위험·한계: 주석만 바뀐다. 코드·번들 크기(주석은 minify에서 빠짐)는 그대로다. 심볼 이름도 이름이 바뀌면 낡지만 grep으로 바로 찾을 수 있다. 검증: - RED(문서·코드 대조): platform/·browser-file-storage/의 `grep -rnE '\.(ts|json|md|mjs):[0-9]+'` 20건을 스크립트로 열어 대조. 19건이 다른 코드(예: check-adapter-inventory.ts:63-83은 INVENTORY 중복 행 검사, eslint.config.ts:519-530은 블록 끝 "},"), 1건만 맞음. - GREEN: 같은 grep 0건. 새로 적은 심볼은 모두 해당 파일에 있는 것을 확인했다. - 회귀: indexeddb-transaction, indexeddb-connection, browser-lifecycle 3파일 66/66 통과. tsc app 통과, eslint 통과, check-adapter-inventory 145 files PASS. Refs: docs/reviews/2026-11-01-maturity-review/05-adapters-storage-kernel.md |
||
|
|
49f7cde50e |
fix(platform): lifecycle 리스너 주인 규칙을 실제에 맞추고 테스트를 둔다 (05-03)
문제: browser-lifecycle.ts는 자신을 "창 lifecycle 리스너의 유일한
주인"이라 적고 어떤 capability도 visibilitychange·online·offline·focus·
pagehide·pageshow 리스너를 직접 달지 않는다고 약속한다.
optional-runtime-host.ts도 같은 말을 한다. 실제로는
- telemetry 수집기가 기본 구성에서 자기 pagehide 리스너를 단다
(telemetry-collector.ts onPageExit).
- 네이티브 파일 선택기가 선택 창이 열린 동안 window focus 리스너를
단다(browser-file-picker.ts, 리뷰가 세지 않은 두 번째 예외).
- lifecycle 런타임은 SW나 realtime이 있을 때만 만들어져 기본 구성에는
없다.
또 createBrowserLifecycleRuntime을 직접 부르는 테스트가 없어 bfcache
복원 때 generation 증가(K3), dispose 때 리스너 해제(K4) 변이가
살아남았다.
고른 방법: 리뷰 권고 (a). 주석을 "런타임이 있을 때 capability는 여기에
구독한다"로 좁히고, 런타임이 생기는 조건과 알려진 예외 둘을 적는다.
tests/unit/browser-lifecycle.test.ts를 추가해 리스너 수, generation,
visibility·connectivity, 구독자 격리, beforeunload 부착·해제·prompt,
dispose 뒤 0개를 확인한다.
버린 대안:
- (b) telemetry를 lifecycle 런타임에 연결하고 기본 구성에서도 런타임을
만든다: "기본 구성은 부작용 없는 생성" 원칙과 조립 순서를 함께 바꿔야
해 이번 범위를 넘는다.
- (c) lint로 이벤트 이름을 막고 예외 파일을 적는다: 예외 목록 관리 비용에
비해 지금 이득이 작다. 다운스트림이 lifecycle 런타임을 켤 때 다시 본다.
위험·한계: 규칙은 여전히 주석뿐이고 검사가 없다(주석에 그렇게 적었다).
src 동작은 바뀌지 않는다.
검증:
- RED(주석): 주석의 "single owner"와 telemetry-collector.ts의 pagehide,
browser-file-picker.ts의 focus 리스너를 대조해 불일치 확인.
- RED(테스트 공백): 새 테스트는 현재 코드에서 5/5 통과하고, 변이 4개를
모두 잡는다. K3(generation += 1 제거) → "expected {...} to match
object { generation: 2 }", K4(dispose의 pagehide·pageshow 해제 제거) →
"expected 2 to be +0", beforeunload 상시 부착 → "expected 1 to be +0",
dirty 검사 제거 → preventDefault "to not be called".
- 회귀: browser-lifecycle, optional-runtime-host, runtime-adapters
3파일 30/30 통과. tsc app·test 통과, eslint 통과,
check-adapter-inventory PASS.
Refs: docs/reviews/2026-11-01-maturity-review/05-adapters-storage-kernel.md
|
||
|
|
12c23feba9 |
fix(storage): 저장소 진단 이벤트에 실패 원인을 싣는다 (05-02)
문제: Web Storage 어댑터의 실패 원인은 QUOTA_EXCEEDED, SIZE_LIMIT_EXCEEDED, UNAVAILABLE, VALUE_REJECTED 넷이다. 진단 이벤트 storage.operation.failed는 error_kind에 quota면 STORAGE_QUOTA_EXCEEDED, 나머지는 모두 STORAGE_UNAVAILABLE을 넣고 원인을 버린다. 그래서 운영자는 "브라우저 저장소를 못 쓴다"와 "저장된 값이 깨져서 버렸다"를 같은 이벤트로 본다. 호출자에게 주는 실패 code에는 원인이 이미 들어 있다. 고른 방법: recordStorageFailure의 context에 reason: cause를 더한다. reason은 진단 계약의 허용 칸(taxonomy)이고 원인 값은 어댑터의 닫힌 유니온이라 cardinality가 늘지 않는다. projectDiagnosticRecord에 넣어 칸이 그대로 남는 것을 확인했다. 버린 대안: error_kind를 원인별로 나누는 것. error_kind는 createFailure의 error kind taxonomy와 맞춰져 있어, 값을 늘리면 그 taxonomy를 바꿔야 한다. 이미 있는 reason 칸에 싣는 쪽이 추가만으로 끝난다. 위험·한계: 진단 이벤트에 칸이 하나 는다(추가만). 수집기가 reason을 바깥으로 내보내는지는 영역 03 소관이라 보지 않았다. 검증: - RED: storage-registry의 quota, discard 3종(malformed, invalid envelope, oversized), oversize write 테스트 5개가 실패. 예: "expected vi.fn() to be called with arguments" 차이 `- "reason": "VALUE_REJECTED"`. - GREEN: 같은 파일 23/23 통과. - 회귀: storage-registry, runtime-adapters, diagnostics, release-mismatch-recovery 4파일 68/68 통과. tsc app·test 통과, eslint 통과. Refs: docs/reviews/2026-11-01-maturity-review/05-adapters-storage-kernel.md |
||
|
|
e98a980dff |
fix(storage): pulse 키를 외부 소유로 적어 StoragePort가 거절한다 (05-01)
문제: registry의 CACHE_INVALIDATION_PULSE 행은 backend localStorage,
valueCodec opaque-string-v1이다. 실제로 이 키에 쓰는 쪽은 cross-context
어댑터이고 envelope 없는 wire JSON을 setItem으로 바로 쓴다. 그래서
StoragePort로 read하면 Web Storage 어댑터가 값을 손상 envelope로 보고
물리 키를 지우고, write하면 envelope 문자열로 덮어써 수신 탭이 버린다.
고른 방법: StorageBackend에 "external"을 더하고 pulse 행을
backend external, valueCodec none으로 바꾼다. getStorageDefinition이
external 키를 던지므로 어댑터의 read/write/remove는 물리 키를 건드리지
않고 *_UNAVAILABLE 실패를 돌려준다. defineStorageKey는 external 키에
codec이 붙으면 거절해 같은 거짓 행이 다시 생기지 않게 한다. 물리 키
문자열 ca-frontend:cache-invalidation:v1:pulse와 wire 형식은 그대로다.
registry-governance의 backend 허용값에 external을 더하고, breaking
필드 변경 두 건은 registry-change-evidence에 근거를 남긴다(baseline
재승인 대신 기존 08-13·F-6과 같은 evidence 방식).
버린 대안:
- 행 위 주석만: 가장 싸지만 StoragePort 호출을 막지 못한다.
- cross-context 어댑터가 StoragePort로 쓰게 함: storage 이벤트의
newValue 형식이 바뀌어 이미 배포된 탭과 서로 못 읽는다.
위험·한계: StoragePort 공개 시그니처는 그대로다. StorageBackend
유니온에 값이 하나 늘어(추가만) exhaustive switch를 쓰는 다운스트림은
분기를 더해야 한다. check:registries 결과는 compatibility=breaking
(evidence로 통과)다. 기본 구성에는 이 키를 StoragePort로 쓰는 호출이
없어 실제 동작 변화는 없다.
검증:
- RED: storage-registry "refuses the externally owned pulse key..."가
"expected { ok: true, value: undefined } to match object { ok: false }"
로 실패(손상 discard 경로), codec 거절 테스트는 "expected [Function]
to throw an error"로 실패.
- GREEN: 같은 파일 23/23 통과.
- 회귀: storage-registry, registry-governance, cross-tab-invalidation,
contract-registry-lookup, browser-security, runtime-adapters,
release-mismatch-recovery 7파일 87/87 통과. tsc app·test 통과,
eslint 통과, check-registries PASS, verify-documentation-readiness
PASS_SCOPED. check:architecture는 pnpm 실행을 요구해 미실행.
Refs: docs/reviews/2026-11-01-maturity-review/05-adapters-storage-kernel.md
|
||
|
|
98b9682241 |
chore(scripts): 쓰지 않는 npm script 4개를 지우고 scan:도 게이트 검사한다 (12-05)
문제
package.json에 어디서도 부르지 않는 script 4개가 있다.
- scan:security:fixture: FE-GATE-013은 이것 대신 check:security:fixtures를
돈다. supply-chain.test.ts는 "게이트에 없어야 한다"고 단언하는데 script는
남아 있다. 게이트 밖 script 검사는 check|verify|test|drill|review만 봐서
scan:을 놓쳤다.
- build:profile: 이름과 달리 generate-runtime-config.ts만 돈다.
- generate:contract-set: 참조 0건.
- build:app-only: vite build와 매니페스트만 만든다. build-frontend.ts의
계약 세트·런타임 설정·Service Worker 단계가 빠진 dist가 나온다. 참조는
product-index-entrypoints 테스트의 진입점 목록 하나다.
참조 확인(새 기준
|
||
|
|
e714c0d770 |
fix(design-system): 디자인 검사가 deg 색상각과 시스템 글꼴 이름을 받는다 (12-04)
문제
디자인 규칙이 올바른 CSS를 거부한다. 포커스 대비 규칙의 parseOklch는
색상각 단위 deg와 음수 색상각을 읽지 못해 oklch(52% 0.15 230deg)를 실패로
센다(B13). 첫 글꼴 규칙은 -apple-system, BlinkMacSystemFont로 시작하는
시스템 글꼴 스택을 실패로 센다(B6). color-mix()·알파 표면(B10, B11)은
"--color-focus or X is not a plain oklch() value"로 실패해서 어느 토큰이
무슨 값인지, 무엇이면 되는지 알 수 없다. 네 규칙의 설명은 코드 주석에만
있다.
고른 방법
- parseOklch가 색상각에 deg와 음수를 받는다. 알파는 계속 받지 않는다.
- oklch-contrast.ts에 resolveValue(var() 사슬 끝 값)를 두고 resolveColor가
그것을 쓴다. 포커스 규칙은 계산할 수 없는 토큰마다 "<테마> <토큰> is
<값>; contrast needs an opaque oklch(L C H), hue in degrees with or
without deg"를 낸다. 포커스 색 자체를 못 읽으면 표면 8개 대신 한 줄이다.
- 첫 글꼴 허용 목록에 -apple-system, BlinkMacSystemFont를 더한다.
- docs/styling/design-system-platform.md 4.1절에 규칙 4개, 지원 형식,
검사 위치를 표 하나로 적는다.
버린 대안
- color-mix()·알파 표면을 배경 위에 섞어 계산: 무엇이 아래에 그려지는지
규칙이 모른다. 추측하지 않고 실패하는 기존 원칙을 유지하고 메시지로
해결 형식을 알린다(리뷰 대안 비교와 같다).
- 리뷰 개선 (4) token-contract.ts에 "제품이 싣는 글꼴" 목록: 공개 계약에
새 이름을 넣는 설계 선택이고 완료 기준에 없다. 문서 표에 "아직 선언할
곳이 없어 실패한다"로 적었다.
- rad·grad·turn 단위: 쓰는 곳이 없다. 넣지 않은 단위는 메시지가 알려 준다.
위험·한계
- 실패 메시지 문구가 바뀐다. 문구를 단언하는 곳은 이 테스트 파일뿐이다.
- 패키지·<link>로 싣는 글꼴, 12-03의 검사 위치 밖 CSS는 그대로다.
- 화면 변화 없음. CSS를 바꾸지 않았다.
검증
- RED(수정 전): design-system-rules·oklch-contrast 테스트 19개 중 4개
실패. "reads a hue written with deg" expected [ …(8) ] to deeply equal [],
"names the value it cannot compute …" 메시지 불일치, "-apple-system"
expected [ Array(1) ] to deeply equal [], parseOklch("…230deg") expected
null.
- GREEN: 같은 두 파일과 design-system-contract 21/21 통과. 실제 스크립트
probe: 포커스를 oklch(52% 0.15 230deg)로 → PASS(B13). surface-muted를
oklch(0.97 0 0 / 0.9)로 → "light --color-surface-muted is oklch(0.97 0 0
/ 0.9); contrast needs …"로 실패(B11). 저장소 CSS는 PASS.
- tsc(tsconfig.node, tsconfig.test), 바꾼 파일 eslint, verify-
documentation-readiness PASS_SCOPED.
Refs: docs/reviews/2026-11-01-maturity-review/12-guardrails-ci.md 12-04
|
||
|
|
c0451f9ad6 |
test(design-system): 검사 스크립트가 규칙 4개를 모두 부르는지 확인한다 (12-02)
문제 49d8675는 디자인 규칙 4개를 순수 함수로 옮기고 함수마다 단위 테스트를 붙였다. 규칙 함수의 판정을 깨면 규칙마다 테스트가 실패한다(이번에 다시 확인: 대비 < 0, 혼합 정규식 무력화, 토큰·글꼴 판정 무조건 통과 → 11개 중 7개 실패). 그러나 scripts/check-design-system.ts가 그 함수를 부르는 부분은 아무것도 지키지 않는다. 스크립트에서 규칙 호출을 지우고 포커스 색을 옛 값 oklch(0.72 0.16 225), 첫 글꼴을 Inter로 되돌려도 check-design-system은 PASS, 관련 단위 테스트 17개도 통과했다. 리뷰가 적은 "규칙을 모두 꺼도 모든 게이트가 통과한다"가 이 경로로 남아 있었다. 고른 방법 - 기존 규칙 테스트 파일에 테스트 하나를 더한다. 토큰 CSS와 styles/**를 임시 폴더에 복사하고 규칙마다 위반 하나를 넣는다(옛 포커스 색, Inter 첫 글꼴, var(--drawer-width) 제거, in oklch 혼합 probe.css). 그 폴더를 cwd로 실제 스크립트를 돌리고, 산출물 JSON의 failures에 네 규칙의 메시지가 모두 있고 다른 실패는 없는지 본다. - 스크립트·게이트·산출물 스키마는 바꾸지 않는다. 스크립트가 이미 cwd 기준 경로만 읽어서 임시 폴더로 충분하다. ci-workflow-generation 테스트가 check-ci-contract.ts를 같은 방식으로 돌린다. 버린 대안 - 리뷰가 제안한 --root 인자와 tests/fixtures/design-system/forbidden-css: 49d8675가 이미 버렸다. cwd 복사가 스크립트 변경 없이 같은 것을 증명한다. - --fixture 모드가 CSS fixture도 읽게 하기: gates.json 기대값과 CI 계약 기준선을 함께 바꿔야 한다. 위험·한계 - 실제 CSS 문자열(--color-focus 정의, --font-sans, var(--drawer-width))을 찾아 바꾼다. 찾지 못하면 어느 문자열인지 적고 실패한다(조용히 통과하지 않는다). - 성공 메시지와 산출물이 어떤 규칙이 돌았는지 적지 않는 점(12-02 근거의 산출물 부분)은 스키마 변경이라 그대로 둔다. - 테스트 하나가 node 프로세스를 띄운다(약 0.2초). 검증 - RED: 스크립트에서 hueMixFailures 호출과 규칙 4개 failures.push를 지우면 새 테스트가 "expected +0 to be 1"로 실패. firstFontFamilyFailures 한 줄만 지워도 '--font-sans starts with "Inter"' 메시지가 없어 실패. - GREEN: tests/unit/design-system-rules.test.ts 12/12, oklch-contrast· design-system-contract 포함 18/18 통과. node scripts/check-design-system.ts PASS. tsc -p tsconfig.test.json, 바꾼 파일 eslint 통과. Refs: docs/reviews/2026-11-01-maturity-review/12-guardrails-ci.md 12-02 |
||
|
|
3c175a5429 |
fix(provider): guardian이 실패하면 stdin을 기다리지 않고 끝난다 (G-1)
문제
guardian은 fd 0을 fs.createReadStream으로 읽는다. 이 스트림은 libuv
스레드 풀의 스레드 하나를 read(2)에 세워 둔다. process.exit()는 종료
전에 스레드 풀을 join하므로, 그 read가 돌아올 때까지(부모가 stdin을
닫을 때까지) 끝나지 않는다. 그래서 가드를 거부하거나 link가 실패하면
failClosed가 진단을 바로 쓰고도 프로세스는 남는다. 클라이언트는 stdin을
연 채 READY를 기다리므로 거부가 즉시 오지 않고 고정 5초 뒤 "READY timed
out"으로 끝난다. 같은 종류 guardian 두 개 테스트의 패자가 이 경로다.
탐침: 같은 종료 코드를 fs 스트림은 stdin을 닫은 2,008ms에, net 소켓은
228ms에 냈다(200ms 뒤 exit 호출).
고른 방법
- liveness 입력을 process.stdin으로 바꾼다. pipe면 Node가 이벤트 루프로
읽는 net.Socket을 만든다. 스레드 풀 read가 없어 exit가 바로 끝난다.
data/end/error 처리, removeAllListeners·destroy, closeSync(0)는 그대로다
(libuv는 fd 0~2를 destroy에서 닫지 않는다).
- 동시 guardian 테스트에 붙였던 PROCESS_HEAVY_TIMEOUT_MS와 그 주석을
뺀다. 패자가 link 실패 즉시 끝나 테스트가 5.14초에서 0.16~0.54초가 됐다.
버린 대안
- provider-scope-wrapper.ts처럼 new Socket({ fd: 0 }): fd 0이 pipe가
아니면 생성자가 throw한다. guardian은 그 시점에 이미 private alias를
묶었고 failClosed는 liveness가 있어야 돈다. process.stdin은 pipe에서는
같은 Socket이고, 그 밖의 fd에서는 throw 대신 end/error로 기존 실패
경로(125)를 탄다.
- 실패 때 SIGKILL로 자신을 죽이기: 종료 코드 124~126 계약이 사라진다.
위험·한계
- pipe인 fd 0에 O_NONBLOCK이 걸린다. 읽기 끝은 guardian만 가진다
(클라이언트는 stdio "pipe"로 띄운다).
- lease 마감 경로는 원래 SIGKILL을 쓰므로 바뀌지 않는다.
검증
- RED(수정 전): 새 테스트 "exits on a rejected guard while the parent
still holds its input open"이 "rejected-guard guardian exit timed out"
(5,122ms)으로 실패. 다른 nonce의 가드를 보내 시계와 무관하게 거부시킨다.
- GREEN: tests/integration/provider-guardian-transaction.test.ts 22/22
통과, 3회 반복 통과(새 테스트 65~333ms). tests/unit/task3-selective-
integration 7/7. tsc(tsconfig.node, tsconfig.test) 통과, 바꾼 파일
eslint 통과.
- 미실행: tests/system/ci-runner/ci-artifact-contract.test.ts의 provider
체인 테스트. fixture가 corepack pnpm으로 빌드해서 이 worktree에서는
돌리지 않았다.
Refs: commit
|
||
|
|
298201f3ee |
perf(features)!: 기능 실행부를 초기 청크에서 떼어 라우트 진입 때 적재한다 (15-01)
문제 초기 JS는 203,572 / 204,800 B(gzip)였다. 생성 인덱스가 각 기능의 feature-module.ts를 정적으로 import하고, 그 파일이 계약(zod 스키마·mapper 포함), HTTP 계약 contribution, application input 팩토리, route codec까지 모두 끌고 왔다. 참조 모양 기능 1개를 더하면 +3,922 B가 늘어 첫 기능에서 예산을 넘었다. 고른 방법 - 기능을 두 부분으로 나눈다. 선언(FeatureModule: route 표, route runtime 계약, invalidation, 문구, 부팅 때 release manifest와 맞춰 볼 contractPackages)은 초기 청크에 남는다. 실행부(FeatureRuntime: V2 API 계약, adapter contribution, contract contribution)는 feature-runtime.ts로 옮기고 loadRuntime이 동적 import한다. route codec은 context-routes.ts의 route handle에 실어 route와 함께 적재한다. - 적재 시점은 그 기능의 route에 들어갈 때다. ContextRouteGateway가 route 모듈과 함께 application.features.load(featureId)를 부르고, 끝난 뒤에 화면을 그린다(공개 포트에는 load만 추가). 들어온 URL의 기능은 route 모듈과 병렬로 적재해 왕복을 늘리지 않는다. 런타임 설정으로 꺼진 기능은 적재하지 않는다. - 조립부는 기능별 로더를 만든다(installed-feature-adapters.ts). contract registry는 기능이 적재될 때마다 전체를 다시 합쳐 검증한다 (installed-contract-contributions.ts). 선언하지 않은 contract package를 적재하면 거절한다. - 모든 실행부를 한꺼번에 읽는 registry(V2 API, contract contribution)는 installed-feature-runtime-registries.ts의 async 함수로, Node·테스트· registry 거버넌스용 상수는 top-level await 모듈 loaded-feature-runtimes.ts로 둔다. src에서 후자를 import하면 새 아키텍처 규칙 boot-does-not-load-every-feature-runtime이 막는다. 플랫폼 구성 화면은 route 로더에서 async 함수를 불러 결과를 prop으로 받는다. - vite.config.ts에 청크 그룹 2개를 둔다. rolldown은 부팅 그래프와 lazy 청크가 같이 쓰는 모듈을 importer 집합마다 따로 청크로 뗀다. 그대로 두면 기능마다 선언 청크가 하나씩 늘고(기능당 +1,471 B), 실행부와 공유하는 플랫폼 모듈(HTTP executor, contract runtime, zod)이 6개 청크로 쪼개져 템플릿 자체가 +438 B 커졌다. feature-declarations는 모든 기능의 선언을, feature-platform은 실행부가 같이 쓰는 부팅 모듈을 한 청크로 묶는다. render-boot-failure.tsx가 쓰는 모듈은 feature-platform에서 뺀다(09-03: 애플리케이션 그래프가 평가 중 던져도 실패 화면은 떠야 한다). 버린 대안 - 부팅 때 feature 청크를 미리 동적 import하고 기다린 뒤 렌더: 분류기는 lazy로 세지만 첫 렌더 경로의 바이트는 그대로다. 예산을 속이는 것이라 버렸다. - 실행부 일부만 지연(adapter와 contribution만): 모두 같은 zod 스키마를 공유해 줄지 않았다. 실측 +4,031 B로 오히려 늘었다. - 선언과 실행부를 같은 lazy 청크(context-routes)에 두기: 기능당 -60 B 수준이라 그룹 없이 목표에 못 미쳤다. - 페이지 문구까지 실행부로 옮기기: 기능당 약 300~450 B를 더 줄이지만 i18n catalog를 런타임 등록 구조로 바꿔야 해 이번 범위에서 뺐다. - boot.tsx를 별도 진입점으로 추가: 분류기가 boot의 동적 import를 모두 초기로 세어 218,303 B가 됐다. 위험·한계 - FeatureModule 모양이 바뀐다. 다운스트림 기능은 feature-runtime.ts로 실행부를 옮겨야 한다(BREAKING CHANGE). - 기능 계약 간 중복(operation, schema, contribution) 검사가 부팅이 아니라 그 기능의 적재 시점과 Node 검사(loaded-feature-runtimes를 읽는 스크립트· 테스트)로 옮겨 간다. - 기능 route에 처음 들어갈 때 실행부 청크(약 5 KB gzip)를 받는다. 플랫폼 구성 화면은 모든 기능의 실행부를 받은 뒤 그린다. lab 게이트(FE-GATE-026)가 재는 화면이라 LCP가 조금 늘 수 있다. 측정하지 않았다. - 청크 그룹은 rolldown 자동 분할을 일부 대신한다. feature-declarations가 비면 기능당 증가 상한 테스트가 실패한다. feature-platform이 비면 템플릿 총량(약 2 KB)만 늘고 번들 예산 검사가 잡는다. - config/contracts/registry-baseline.json의 FE-REG-API/SCHEMA source는 아직 installed-feature-contracts.ts다. 승인 digest가 걸려 있어 소유자 재승인 때 고친다. check-registries는 통과한다. - 예산 안에 들어가는 참조 모양 기능은 약 3개다. 플랫폼 자체가 예산의 98.8%다. 수치 (vite build, classifyViteJavascript + gzipSync 기본 수준) - 템플릿: 203,572 B(13파일) -> 202,361 B(16파일), -1,211 B - 참조 복사본 +1: 207,494 B(+3,922) -> 203,102 B(+741) - 참조 복사본 +2: 210,818 B(+3,324) -> 203,750 B(+648) - 참조 복사본 +5: 205,629 B - lazy JS: 23,516 B -> 28,204 B 검증 - RED: node scripts/run-vitest.ts run tests/unit/feature-shape-growth.test.ts "adds at most 1 KiB ... (15-01)" 실패: expected 3934 to be less than or equal to 1024 - GREEN: 같은 테스트 통과(+741 B) - node scripts/run-vitest.ts run tests/unit: 168파일 2,383 통과 - node scripts/run-vitest.ts run tests/component tests/features tests/integration tests/contract tests/runtime-schema tests/architecture tests/platform tests/recipes (security-followup-archive 제외, pnpm 호출): 109파일 787 통과 - npx tsc --noEmit: app, node, test, recipes, web-worker, service-worker 통과 - npx eslint 바뀐 파일 통과 - check-architecture.ts(pnpm exec 대신 eslint를 부르는 shim): PASS, 새 규칙이 boot.tsx의 import를 거절하는 것 확인 - check-adapter-inventory, check-registries, verify-documentation-readiness, check-ci-contract: PASS - e2e Chromium 전체(pnpm 없는 build-frontend + vite preview, 별도 포트): 55 통과 - storybook build 성공 - 미실행: Firefox·WebKit e2e, 시각 회귀, lab 성능(FE-GATE-026), pnpm 경로의 check:bundle, test:system BREAKING CHANGE: FeatureModule은 id, contracts(선언), routes, messages, loadRuntime만 가진다. adapters, contractContributions와 V2 API 계약 (apiOperations, schemas, runtimeSchemas, mappers)은 defineFeatureRuntime으로 만든 feature-runtime.ts로, route codec은 context-routes.ts의 route handle codecs로 옮긴다. contracts에는 contractPackages를 추가한다. Refs: docs/reviews/2026-11-01-maturity-review/15-performance.md 15-01, 16-structure-patterns.md 9절 |
||
|
|
f41e3d5e32 |
ci(gates): 번들 예산 검사를 merge 단계에서 돌린다 (15-01)
FE-GATE-012(build, check-bundle, check-app-build-input-bundle, check-optional-recipes)는 release 단계에만 있어 tag push나 수동 release 실행에서만 돈다. 초기 JS를 예산보다 크게 만드는 PR도 merge 게이트를 통과하고, 몇 PR 뒤 release가 실패한다. 어느 PR이 얼마나 늘렸는지는 그때 이력을 거꾸로 따라가 찾아야 한다. FE-GATE-012를 merge stage와 merge_gate job으로 옮긴다. release_gate는 merge_gate를 needs로 두므로 tag 실행에서도 그대로 돈다. promotion 공식 (MERGE_READY)과 CI 계약 검사의 job 소유 표를 같이 바꾸고, workflow는 생성기(node scripts/generate-ci-workflow.ts)로 다시 만든다. 버린 대안: - check-bundle만 FE-GATE-011(build)에 붙인다(리뷰의 최소안). 같은 검사가 두 게이트에 갈라지고, release에 남은 FE-GATE-012와 중복해서 돈다. - FE-GATE-012를 merge와 release 둘 다에 둔다. 계약이 게이트당 job 하나를 강제한다(multiply owned gate). - lab 게이트(FE-GATE-026)도 merge로 옮긴다. PR마다 브라우저 설치와 5회 측정이 붙고, 부하에 따라 판정이 뒤집힌 기록(0929/11-04)이 있다. release에 남긴다. 위험·한계: - merge 실행이 build 1회와 공급망 생성, 번들 계산만큼 길어진다. - 실제 CI 러너에서는 돌려 보지 않았다(Actions 꺼짐). 검증: - node scripts/check-ci-contract.ts: 27 gates PASS - node scripts/generate-ci-workflow.ts --check: PASS - node scripts/generate-artifact-schemas.ts --check: PASS - node scripts/run-vitest.ts run tests/unit/ci-workflow-generation.test.ts tests/unit/promotion-readiness.test.ts: 423 통과(workflow 스냅샷 1건 갱신) Refs: docs/reviews/2026-11-01-maturity-review/15-performance.md 15-01 |
||
|
|
c03bf020c9 |
test(setup): Testing Library 대기 기한을 전역 한 곳에서 정한다 (0929/10-01)
문제
lazy route 화면을 findBy*·waitFor 기본값(1초)으로 기다리는 테스트가 1코어
부하에서 코드와 무관하게 떨어진다. 수정 전 재현에서
runtime-application.test.tsx:65 "Unable to find role=heading name=Clean
Architecture Frontend"와 reference-production-vertical.test.tsx:103
"Unable to find role=button name=로그인 시작"이 났다. 두 DOM 모두
route-loading(aria-busy) 상태였다. 지난 리뷰는 router.test.tsx:244-250도
같은 이유로 실패했다고 적었다. React 19는 Suspense를 풀 때마다 실제 300ms
타이머(FALLBACK_THROTTLE_MS)를 기다린다. context route 표와 lazy 페이지를
거치는 화면은 렌더링 전에 1초 중 600ms를 쓴다. 이 사정을 아는 파일만
호출마다 { timeout: 5000 }을 붙이거나(7개 파일 13곳) 파일 단위로
configure를 바꿨다(reference-page). 새 테스트 작성자는 이 규칙을 알 방법이
없다.
고른 방법
tests/setup.ts에서 configure({ asyncUtilTimeout: 5_000 })를 한 번 정하고,
같은 값을 반복하던 호출·파일 단위 override를 지웠다. findBy*·waitFor는
DOM 변화가 오면 바로 끝나므로 기한은 멈춤을 알리는 용도뿐이다. 10초 테스트
제한의 절반이라 진짜 멈춤은 여전히 Testing Library의 DOM 덤프와 함께
실패한다. 기한을 늘리는 방식이라 고른 이유를 setup에 주석으로 남겼다.
버린 대안
- 가짜 시계: Testing Library는 Jest의 가짜 타이머만 알아본다
(jestFakeTimersAreEnabled가 jest 전역을 본다). Vitest 가짜 타이머에서
waitFor는 자기 타이머가 멈춰 끝나지 않는다. MSW와 user-event도 실제
시계로 돈다.
- route chunk를 테스트에서 미리 import하기: chunk를 받아도 React의 300ms
reveal 타이머와 렌더링 비용은 그대로 기한 안에 남는다. 테스트가 route
모듈 목록을 따로 알아야 한다.
- 실패한 파일에만 timeout 붙이기: 지금 상태와 같다. 다음 lazy 화면
테스트에서 같은 실패가 반복된다.
위험·한계
- 기다리다 실패하는 테스트는 실패까지 1초가 아니라 5초 걸린다. 부재를
findBy·waitFor의 실패로 확인하는 테스트는 없다(grep으로 확인).
- 가짜 타이머를 쓰는 테스트의 waitFor는 이 값과 무관하다(가짜 시간).
검증
- RED(수정 전, taskset -c 0 + 같은 코어의 바쁜 이웃 1개, --maxWorkers=4,
component·features·integration·platform/cardinality): 3회 중 1회 위 두
테스트 실패.
- GREEN(같은 조건): 대상 6개 파일 6회, 넓은 묶음 5회 모두 통과. 바쁜
이웃 2개로 3회 돌렸을 때도 이 커밋이 다루는 테스트는 모두 통과했다.
넓은 묶음 한 번의 시간은 RED 91~111s(실패가 몰린 209s 회차 제외)
-> GREEN 86~88s다.
- 기본 코어: tests/unit·component·integration 212파일 2,734개, features·
platform·architecture·contract·runtime-schema 60파일 403개 통과.
tsc -p tsconfig.test.json, 바꾼 파일 eslint 통과.
Refs: docs/reviews/2026-09-29-maturity-review/10-tests-fast-layers.md
|
||
|
|
582630062b |
test(scale): 극한 규모 테스트가 CPU와 무관한 비교만 단언한다 (0929/10-01)
문제 extreme-scale-registry.test.ts는 머지 게이트(FE-GATE-005 coverage, pr scale tier)에서 돈다. 그런데 절대 시간 예산(100만 조회 1,500ms, 100k 조합·멤버십 3,000ms)을 단언한다. 1코어에서는 코드와 무관하게 떨어진다 (수정 전 9회 중 5회, 1,509~1,826ms). run-scale-profile.ts와 ungated-tests.json은 pr tier를 "CPU와 무관하다"고 설명하는데 이 파일만 어긋났다. 같은 이유로 진짜 회귀를 잡는지도 기계 속도에 달려 있었다. 고른 방법 - 조합: 이미 있던 10k -> 100k 증가 비율(30 미만)만 남긴다. - 조회: 같은 100k 키로 만든 일반 객체 조회와 비교해 3배 미만인지 본다. 조회 횟수는 1,000,000 -> 200,000(양쪽 합 400,000). - 멤버십: 10k와 100k 선택·해석 비용을 repo의 assertLinearOrBetter(지수 1.5 이하)로 본다. - 측정: 비교하는 두 쪽을 번갈아 재고, 10k 쪽은 10번 반복해 일의 양을 맞추고, 각자 가장 빠른 회차를 쓴다. 공유 코어에서 10ms 측정은 한 scheduler slice 안에 끝나고 100ms 측정은 다른 프로세스 뒤에서 기다려 성장이 실제보다 가팔라 보인다(일의 양을 맞추기 전 조합 비율 61 관측). 가장 빠른 회차는 check:scale:baseline이 성장을 minMs로 읽는 것과 같다. 절대 시간은 기준 CPU에서만 비교하는 check:scale:baseline 몫으로 둔다. 버린 대안 - 예산을 올리기: 더 느린 러너에서 같은 문제가 다시 생긴다. - 절대 예산을 nightly 전용 파일로 떼기: tier 설정·ungated 목록·문서를 함께 고쳐야 하고, 머지 게이트 쪽에는 결국 이번 비교가 필요하다. - 조회를 10k/100k 성장으로 보기: 감싸기(proxy)처럼 크기와 무관한 느려짐을 못 잡는다. 선형 탐색은 어느 쪽이든 시간 초과로 드러난다. 위험·한계 - 비교도 실제 시계로 잰다. 바쁜 이웃 3개를 둔 1코어에서 관측한 최댓값은 조합 비율 17(한도 30), 조회 비율 1.04(한도 3), 멤버십 지수 1.21(한도 1.5)이다. 여유는 한도의 약 1.2~3배다. - 크기와 무관한 작은 상수 배 느려짐(get trap이 있는 proxy 정도)은 조회 비교가 잡지 못한다. 수정 전 절대 예산도 이 기계에서 잡지 못했다. 검증 - RED(수정 전, taskset -c 0): 대상 파일만 3회 중 1회, component·features· integration·platform/cardinality 3회 중 1회, 바쁜 이웃 1개를 더하면 3회 중 3회 "expected 1509.6… to be less than 1500" (extreme-scale-registry.test.ts:78). - 변이(기본 코어): 조합에 100번째마다 Object.keys -> "expected 145.5 to be less than 30". 조회에 20회 hasOwn get trap -> "expected 14.46 to be less than 3". 해석을 includes로 -> "super-linear growth: exponent 1.98". - GREEN(taskset -c 0 + 같은 코어의 바쁜 이웃, --maxWorkers=4): 대상 6개 파일 6회, component·features·integration·platform/cardinality 5회 모두 통과. 이 파일만 바쁜 이웃 3개 옆에서 6회, coverage를 켜고 3회 통과. - 실행 시간: 기본 코어에서 파일 1.76s -> 1.37s. - 기본 코어: tests/features·platform·architecture·contract·runtime-schema 60파일 403개 통과. tsc -p tsconfig.test.json, eslint 통과. Refs: docs/reviews/2026-09-29-maturity-review/10-tests-fast-layers.md |
||
|
|
c8620042ea |
test(guardian): 가드를 guardian이 읽을 준비가 된 뒤에 보낸다 (0929/10-01)
문제
guardian 테스트는 자식을 띄우자마자 절대 마감(Date.now() + 350)이 든
가드를 보낸다. 그래서 lease가 프로세스 기동 시간까지 낸다. 1코어에서
기동이 350ms를 넘으면 guardian이 가드를 마감 지남으로 거부하고, 테스트는
5초 뒤 "deadline guardian READY timed out"으로 실패한다(수정 전 1코어
재현 9회 중 4회). 같은 구조가 2~3초 lease를 쓰는 테스트 5곳에 있다. near-timeout
테스트는 READY 뒤 1초를 고정으로 자서, 기동이 길면 publish·commit에 남는
시간이 줄어든다. 자식 기동을 기다리는 poll 세 개(waitForFile,
waitForNewDirectChild, waitForStoppedProcess)는 1초 마감을 쓴다. 파일
머리의 watchdog 설명("1초 요구를 넣지 않는다")과 어긋난다.
고른 방법
- spawnGuardian이 실제 guardian을 import하는 래퍼로 띄운다. import가
끝나면(bootstrap과 stdin reader 등록까지 끝난 시점) 래퍼가 여분 pipe
(fd 7)에 1바이트를 쓰고 닫는다. 새 sendGuard는 이 신호를 받은 뒤에
마감을 계산해 가드를 보낸다. 가드를 보내는 6곳이 모두 sendGuard를 쓴다.
guardian 코드와 프로토콜, 350ms·2s·3s lease 값은 그대로다.
- near-timeout 테스트는 startProviderGuardian 호출 직전 시각에서 1초 뒤에
깬다. 클라이언트가 spawn 뒤에 마감을 찍으므로 마감은 그 시각 + 2초
이후다. 기동이 길어도 publish·commit에 1초가 남는다.
- 1초 poll 세 개는 같은 파일의 watchdog(5초)을 쓴다. 자식 기동에는 기다릴
이벤트가 없어 poll이 남는다.
- 같은 종류 guardian 두 개 테스트는 패자가 클라이언트의 고정 5초 READY
제한(RESPONSE_TIMEOUT_MS)으로만 거부된다. 테스트가 줄일 수 없는 고정
대기라 파일의 PROCESS_HEAVY_TIMEOUT_MS를 붙이고 이유를 주석에 적었다.
버린 대안
- lease를 늘리기: 기동 시간에 상한이 없어 같은 문제가 더 드물게 남는다.
350ms 테스트는 만료를 기다리는 시간도 길어진다.
- marker 파일 + poll로 준비 신호: 파일 시스템 poll에 다시 마감이 필요하다.
pipe는 이벤트로 끝나고 provider-evidence 목록 단언에 끼어들지 않는다.
- guardian 프로세스에 가짜 시계 주입: 자식 프로세스라 테스트용 훅을 운영
스크립트에 넣어야 한다.
위험·한계
- spawnGuardian 경로의 guardian은 main 모듈이 아니라 래퍼가 import한
모듈로 돈다. guardian은 argv·import.meta를 읽지 않는다. 래퍼는 신호를
보낸 뒤 fd 7을 닫으므로 가드를 받는 시점의 상속 fd(0~6)는 운영과 같다.
클라이언트 경로 테스트는 그대로 실제 스크립트를 직접 띄운다.
- 가드를 보내기 전 기동 대기는 watchdog 5초가 상한이다. 남은 실제 시계
구간은 가드 처리(decode, link, fsync, READY)뿐이다.
- 따로 남는 결함(이 커밋 범위 밖): guardian은 가드를 거부하거나 link가
실패하면 failClosed가 진단을 쓰지만, stdin 읽기가 걸려 있는 동안
종료하지 않는다. 탐침: 만료된 가드를 받고 1,008ms에 진단을 쓴 뒤 stdin을
닫은 4,014ms에야 126으로 끝났다. 그래서 클라이언트에서는 거부가 즉시
오지 않고 5초 뒤 "READY timed out"이 된다(leaseMs 1과 동시 guardian 탐침
5,018~5,053ms). 위 PROCESS_HEAVY_TIMEOUT_MS는 이 결함이 고쳐지면 뺄 수
있다.
검증
- RED(수정 전, taskset -c 0, --maxWorkers=4): component·features·
integration·platform/cardinality 3회 중 2회, 같은 묶음 + 바쁜 이웃 1개
3회 중 2회 "expires an uncommitted lease … deadline guardian READY timed
out"(5,035~5,052ms).
- GREEN(세 커밋을 합친 상태, taskset -c 0 + 같은 코어의 바쁜 이웃,
--maxWorkers=4): 대상 6개 파일 6회, 위 넓은 묶음 5회(이웃 1개) 모두
통과. 이웃 2개로 3회 돌렸을 때 이 파일은 모두 통과했다(실패 1건은
http-execution-v3-live-authority, 0929/10-03).
- 기본 코어: tests/unit·component·integration 212파일 2,734개 통과
(pnpm을 띄우는 security-followup-archive, fixture-node-modules,
lab-performance 제외). tsc -p tsconfig.test.json, 바꾼 파일 eslint
통과.
Refs: docs/reviews/2026-11-01-maturity-review/10-tests-fast-layers.md
|
||
|
|
08b5ccc86e |
test(visual): 시각 테스트 글꼴을 fonts.conf로 고정하고 먼저 검사한다 (11-02)
시각 골든은 작성자 PC가 고른 글꼴 4종(Noto Sans, Noto Sans CJK KR Regular·Black, Liberation Mono)으로 찍혀 있는데, 설정은 글꼴을 고정하지 않는다. 같은 dist에서 FONTCONFIG_FILE만 Playwright가 맨 Ubuntu에 까는 글꼴 구성으로 바꿔도 5장이 모두 실패한다. 실패는 화면 전체가 밀린 pixel diff라서 원인이 글꼴이라는 것을 알기 어렵다. CI 러너도 같은 처지다. 고른 방법 (리뷰 4.1절 c′, 사용자 결정): - tests/visual/fonts.conf가 Debian/Ubuntu 경로의 세 디렉터리 (truetype/noto, opentype/noto, truetype/liberation)만 보이게 한다. playwright.visual.config.ts가 use.launchOptions.env로 그 파일을 FONTCONFIG_FILE에 넣는다. 바깥 FONTCONFIG_FILE은 덮어쓴다. CI workflow는 바꾸지 않았다. - 같은 파일에서 래스터 설정(antialias, hintslight, rgb, lcddefault, autohint 끔)을 호스트 규칙 뒤에 고정한다. 글꼴 이름이 같아도 hint와 sub-pixel 기본값이 다른 호스트에서는 5장이 모두 실패했다(검증 참고). - visual-fonts setup 프로젝트(tests/visual/fonts.setup.ts)를 chromium-visual의 의존으로 둔다. 실제 앱 페이지에 탐침 요소를 넣고 CDP CSS.getPlatformFontsForNode로 실제로 그려진 글꼴을 비교한다. 다르면 설치할 패키지 이름과 함께 실패하고, 스크린샷 테스트는 돌지 않는다. 글꼴이 하나도 없으면 렌더러가 죽으므로 그 경우도 같은 안내로 감싼다. test:visual:update도 같은 검사를 먼저 거친다. 버린 대안: - fc-match 사전 검사: fontconfig CLI가 러너에 있다는 보장이 없고, Chromium이 실제로 고르는 글꼴과 다를 수 있다. 앱 페이지의 code는 Liberation Mono인데, lang 없는 빈 페이지에서는 Noto Mono가 잡혔다. 그래서 탐침도 앱 페이지 안에 넣는다. - document.fonts.check: 시스템 글꼴은 없어도 true를 돌려준다. - /etc/fonts/conf.d를 빼고 별칭 규칙을 직접 쓰기: system-ui와 Courier New(Chromium 기본 monospace) 해석을 다시 만들어야 한다. 리뷰 실험 D(호스트 규칙 포함, 5/5)에서 벗어난다. - 컨테이너 이미지, 글꼴 파일 커밋, 임계값 완화: 리뷰 4.1절에서 기각. 위험·한계: - 바이트가 아니라 패키지 이름을 고정한다. 배포판이 글꼴 버전을 바꾸면 이름 검사는 통과하고 pixel diff로 실패할 수 있다. - generic family 별칭(sans-serif → Noto Sans, Courier New → Liberation Mono)은 호스트의 /etc/fonts/conf.d를 따른다. 별칭이 다른 호스트 (예: Noto Sans를 우선하지 않는 fontconfig 2.14 미만)에서는 visual-fonts가 실패한다. 조용히 다른 글꼴로 바뀌지는 않는다. - 사용자 fontconfig(50-user.conf)가 디렉터리를 더하면 그 글꼴도 보인다. 탐침 4종이 바뀌면 검사가 잡는다. - Linux 전용이다. macOS와 Windows의 Chromium은 fontconfig를 읽지 않는다. - 실제 Gitea 러너에서는 돌려 보지 못했다(U-1). CI에 apt 설치 단계를 넣지 않았고, 필요한 패키지는 테스트 전략 문서 13.4절에 적었다. - 골든은 다시 찍지 않았다. 검증 (같은 dist, flock, `npx playwright test --config playwright.visual.config.ts`. pnpm을 부르지 않으려고 webServer만 vite preview로 바꾼 로컬 사본으로 실행): - 수정 전, 바깥 FONTCONFIG_FILE=A(Playwright Ubuntu 글꼴 + DejaVu): 5 failed, toHaveScreenshot diff(46,356 px, 4%) - 검사만 넣고 같은 A: 1 failed, 5 did not run. 설치 안내와 함께 latin=DejaVu Sans, korean=WenQuanYi Zen Hei - RED, fonts.conf가 빈 디렉터리만 볼 때: 1 failed, 5 did not run. 같은 설치 안내 + "The font probe page did not render" - GREEN, 호스트 환경: 6 passed. 바깥 A: 6 passed(기존 골든 5/5) - 러너 근사(호스트 conf.d에서 language-selector, ubuntulegacy, sub-pixel-rgb 제외): 6 passed - 다른 래스터 기본값(hinting-full, sub-pixel-none): 고정 블록 없이 5 failed(setup만 통과, diff 2%), 고정 블록 포함 6 passed - tsc(app·node·test), eslint, check-test-evidence --source-only PASS, verify-documentation-readiness PASS_SCOPED, vitest supply-chain과 tests/architecture 53 passed Refs: docs/reviews/2026-11-01-maturity-review/11-tests-browser-release-scale.md 11-02, 4.1절 |
||
|
|
a6560be93e |
test(system): cgroup 테스트가 /proc 표본 대신 실행 기록을 읽는다 (11-01)
문제: "applies effective aggregate cgroup limits ..." 테스트는 recordProviderProcessTree로 /proc을 5 ms마다 읽고 PID마다 처음 본 argv만 남긴다. systemd-run이 같은 PID에서 wrapper로 exec하고, 갓 fork된 자식이 exec 전까지 부모 argv를 보여서 "systemd-run 1개", "guardian 1개" 단언이 간헐적으로 실패한다(리뷰 README 13.1: 부하 약 3에서 10회 중 4회). 고른 방법: 표본을 지우고 앞 커밋의 실행 기록을 읽는다. 기록 파일은 workspace 밖 임시 폴더에 둔다. sandbox가 workspace를 ro-bind하므로 그 안에 두면 provider가 읽을 수 있다. 단언 대응: - 직접 자식 systemd-run 1회: systemd-run 기록 1개, ppid가 supervisor, argv[0]이 /usr/bin/systemd-run - guardian 1회: guardian 기록 1개, ppid가 supervisor - scope wrapper 1회: wrapper 기록 1개, pid가 systemd-run과 같고 cgroup이 `0::<ControlGroup>`과 정확히 같다 - sandbox 관찰: bwrap 기록 1개, ppid가 wrapper, argv에 /usr/bin/prlimit - 인프라 argv에 명령 없음: 모든 기록 argv에 command가 없다. 추가로 providerScript 경로도 없다 - provider 1회: bwrap 실행 1회 + provider가 자기 /proc/self/cgroup에 /ca-provider-vulnerability-가 없으면 exit 8(run 실패) - credential 없음: 기록 파일 원문과 모든 argv에 없다. stdout/stderr와 unit 메타데이터 단언은 그대로 - 종료 뒤 기록된 PID가 모두 없고 cgroup 디렉터리가 없다(그대로) 버린 대안: provider만 host 표본으로 계속 보는 혼합안. provider PID도 bwrap -> prlimit -> sh -> node로 바뀌어 같은 경쟁이 남는다. 위험·한계: - provider의 scope 소속은 host 관찰이 아니라 provider 자신의 확인(exit code)으로 본다. bwrap의 소속은 관찰된 wrapper cgroup에서 fork 상속으로 판단한다. - 기록에 남지 않은 spawn은 보이지 않는다(앞 커밋 한계와 같다). 검증: - 이 테스트는 createProviderFixture에서 corepack pnpm build:release-candidate를 부른다. 작업 규칙상 worktree에서 pnpm을 띄우지 않으므로 실제 테스트의 RED/GREEN은 실행하지 않았다. - 대신 pnpm 없는 하네스로 같은 실행 체인(운영 encoder, systemd-run -> sh -> wrapper -> bwrap -> prlimit -> provider, guardian 대역 포함)을 돌렸다. 옛 표본 판정: 10회 중 4회 실패(systemd-run=0, wrapper=2). 실행 기록 판정: 20회 중 20회 통과. provider 자기 확인은 scope 안에서 통과, host에서 exit 8. - tsc(tsconfig.test.json), eslint 통과. |
||
|
|
0536891c05 |
feat(provider): 실행 단계가 자기 PID와 argv를 실행 기록에 남긴다 (11-01)
문제: tests/system의 cgroup 테스트는 provider 실행 중 /proc을 5 ms마다 표본으로 읽어 어떤 프로세스가 어떤 argv로 돌았는지 판정한다. systemd-run --scope는 scope로 옮긴 뒤 같은 PID에서 sh 게이트와 scope wrapper로 exec하고, 갓 fork된 자식은 exec 전까지 부모 argv를 보인다. 표본은 PID마다 처음 본 argv만 남겨 이 짧은 단계를 자주 놓친다. 운영 코드에는 테스트가 결정적으로 읽을 실행 증거가 없다. 고른 방법: scripts/lib/provider-process-trace.ts를 추가한다. PROVIDER_PROCESS_TRACE_PATH가 있을 때만 각 단계가 JSON 한 줄을 덧붙인다. - 자기 기록: supervisor와 scope wrapper가 /proc/self/cmdline과 /proc/self/cgroup을 남긴다(커널이 본 값). - 자식 기록: supervisor가 systemd-run, guardian client가 guardian, wrapper가 bwrap을 spawn에 넘긴 argv 배열 그대로 남긴다. spawn과 기록이 같은 배열을 쓴다. - 필드는 role, pid, ppid, argv, (자기 기록만) cgroup. 환경변수는 담지 않는다. credential과 provider 명령이 지나가는 곳이기 때문이다. - systemd-run 환경은 허용 목록으로 다시 만들어지므로 providerProcessTraceEnvironment()로 기록 경로만 넘긴다. bwrap은 --clearenv라 sandbox 안의 provider는 경로를 받지 않는다. guardian은 빈 환경을 그대로 두고 client가 spawn 지점에서 기록한다. 테스트용 opt-in으로 두고 운영 감사 증거로 쓰지 않는다. 운영에서 켜면 argv가 두 번째로 남는 곳이 생긴다. 나중에 credential이나 provider 명령이 argv에 들어가는 회귀가 생기면, 지금은 /proc에 잠깐 보이는 값이 파일로 남아 CI 산출물이 될 수 있다. 감사 증거로 쓰려면 봉인 보고서와 같은 경로 안전·크기 상한·스키마·보존 정책이 필요하고 이번 범위가 아니다. CI 워크플로는 이 변수를 설정하지 않는다. 버린 대안: - /proc 표본 보강(부모와 같은 argv 무시, PID별 argv 이력 보존): 리뷰 README 13.1에서 시도하고 되돌렸다. 이력 보존은 prlimit -> sh로 바뀌는 PID 이력에 provider 명령이 섞여 "인프라 argv에 명령 없음" 단언의 뜻이 바뀐다. - spawn 직후 /proc/<pid>/cmdline 읽기: libuv는 exec 뒤에 반환하지만 systemd-run은 곧 wrapper로 다시 exec하므로 경쟁이 남는다. - guardian 자기 기록: guardian이 빈 환경으로 뜨는 것이 보장이라 기록 경로를 넘기지 않는다. 위험·한계: - 기록은 각 단계가 스스로 남긴다. 새 spawn 지점이 기록을 빠뜨리면 테스트에서 보이지 않는다. 모듈 주석에 적었다. - 기록 실패는 run 결과를 바꾸지 않고 stderr에 한 줄 남긴다. wrapper의 stderr는 provider 출력으로 버려지므로 빠진 줄은 기록을 읽는 쪽에서 드러난다. - 변수가 없으면 spawn 인자와 환경은 이전과 같다. 검증: - node scripts/run-vitest.ts run tests/unit/provider-process-trace.test.ts 2건 통과. 자식 기록에 env 필드를 넣는 변이를 넣으면 실패한다. - 관련 테스트 6파일 44건 통과(provider-process-trace, task3-selective- integration, provider-output-limiter, security-provider-evidence, provider-guardian-transaction, provider-process-group). - pnpm 없는 하네스(운영 encoder로 systemd-run -> sh -> wrapper -> bwrap -> prlimit -> provider 실행)에서 실행 기록 20회 중 20회 완전. - tsc(tsconfig.node.json, tsconfig.test.json), eslint 통과. |
||
|
|
d2a882fde6 |
fix(presentation): 좁은 화면에서 테마 선택과 세션 상태를 메뉴 서랍에 둔다 (08-01)
문제: 폭 48rem 미만(휴대폰, 1280px 창의 약 170% 이상 확대)에서
responsive.css가 머리글의 색상 테마 선택, 세션 상태, 브랜드를
display: none으로 숨긴다. 메뉴 서랍에는 주요 탐색만 있어서 이 기능과
정보를 쓸 곳이 없다. WCAG 2.2 1.4.10(Reflow)의 "기능·정보 손실 없이"
조건을 어긴다.
고른 방법: 머리글은 지금처럼 두고, 서랍에 브랜드 이름(탐색 위)과 색상
테마 선택·세션 상태(탐색 아래)를 넣는다.
- 테마 선택과 세션 상태를 app-shell.tsx 안의 ThemePreferenceSelect,
SessionStatus로 뽑아 머리글과 서랍이 같은 컴포넌트를 쓴다. 둘 다
기존 ThemeProvider·SessionProvider를 직접 읽어 따로 든 상태가 없다.
- 서랍 쪽 select id는 mobile-theme-preference로 달리 줘서 id가 겹치지
않는다. 머리글 #theme-preference는 그대로다(시각 테스트가 쓴다).
- 서랍 쪽은 라벨을 보이게 두고 theme-selector 클래스를 붙이지 않는다.
그래서 i18n.spec의 "머리글 선택 상자 2개" 검사가 그대로 맞는다.
- 브랜드는 화면을 보고 서랍 위쪽에 링크가 아닌 글자로 넣었다. 서랍에
"홈" 링크가 이미 있어 링크로 두면 같은 곳으로 가는 Tab 정지가 는다.
- 숨김 규칙(responsive.css)과 머리글(app-shell.tsx)에 서랍이 대신
보여 준다는 주석을 달았다.
버린 대안:
- 머리글에 테마 아이콘 메뉴 버튼(리뷰 5.3 (C)): 새 컴포넌트가 필요하고
320px 머리글 공간을 다툰다. 머리글은 단순하게 두기로 정했다.
- 서랍이 열릴 때만 서랍 쪽 컨트롤을 렌더: DOM 중복은 없어지지만 탐색은
항상, 나머지는 조건부로 그리는 이유가 코드에 드러나지 않는다. 탐색이
이미 사이드바와 서랍에 두 벌 있는 방식에 맞췄다.
- 서랍 제목을 앱 이름으로 바꾸기: 대화상자 이름 "메뉴"가 바뀌어 기존
접근성 이름과 테스트가 깨진다.
위험·한계:
- 세션 상태 문구와 테마 select가 DOM에 두 벌 있다. 접근성 트리에는
한 번만 나온다(좁은 폭은 머리글 쪽이 display: none, 넓은 폭은 닫힌
dialog). 다만 페이지 전체에서 getByText로 셸 문구를 찾는 테스트는
strict mode에 걸린다. reference-route.spec의 "인증됨"을 banner로
좁혔다. 다운스트림 테스트도 같은 수정이 필요할 수 있다.
- 640x400(200% 확대)에서는 테마 선택이 서랍 첫 화면 아래에 있어 서랍을
스크롤해야 보인다.
- 좁은 화면 서랍 화면이 바뀐다. 시각 골든
app-shell-compact-pseudo-drawer.png는 이 커밋에서 갱신하지 않았다.
- 초기 JS gzip 203,572 -> 203,648 B(+76 B, 예산 204,800 B). check:bundle은
pnpm을 불러 돌리지 않았고, 같은 분류(classifyViteJavascript)와
gzipSync로 직접 쟀다.
- 실제 기기 터치, 스크린 리더 발표는 확인하지 않았다.
검증:
- RED: tests/e2e/responsive.spec.ts 새 테스트(320·375·640px)가 수정 전
chromium·firefox·webkit 9/9 실패. getByRole('dialog', { name: '메뉴' })
.getByRole('combobox', { name: '색상 테마' }): element(s) not found.
- GREEN: 같은 테스트 9/9 통과. 마지막 탐색 링크에서 Tab으로 테마 선택에
닿고, dark·light 선택에 html[data-theme]이 바뀐다. 서랍에 "로그인 전"과
브랜드가 보인다.
- 회귀 e2e: responsive·i18n·theme·accessibility·app-shell·reference-route
(세 엔진) + compact-smoke(chromium-compact) 85/85 통과. app-shell.spec의
Esc 닫기·포커스 복원·서랍 링크 뒤 h1 포커스 포함. 수정 전에는
reference-route가 세 엔진에서 strict mode로 실패하는 것을 확인했다.
- 열린 서랍 axe(375px, light·dark, 세 엔진) 위반 0(일회성, 커밋 안 함).
- node scripts/run-vitest.ts run tests/component: 211/211 통과.
- tsc(app·test·node) 0, eslint(바꾼 tsx·spec) 0, check-design-system
PASS, check-architecture(pnpm 대신 exec 전용 shim) PASS.
- Playwright는 webServer만 `npx vite preview`로 바꾼 임시 설정으로
돌렸다(빌드는 node scripts/build-frontend.ts).
Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-01
|
||
|
|
4b646f687f |
docs(review): 개선 순서 1의 조치 현황과 남은 cgroup 경쟁을 기록한다
리뷰 README에 개선 순서 1을 어떻게 닫았는지가 없었다. 11-01은 고친 뒤 다른 단언에서 간헐 실패가 드러났다. 13절에 발견별 상태, 커밋, 막는 테스트를 적었다. 11-01은 부분 충족으로 두고, 되돌린 시도 세 가지와 다음 방향(표본 대신 실행 증거 파일)을 13.1절에 남겼다. 영역 문서는 리뷰 시점 기록이라 고치지 않았다. 위험: 문서만 바뀐다. 검증: verify:documentation PASS_SCOPED. cgroup 테스트 10회 중 6회 통과 (부하 약 3)를 직접 측정했다. |
||
|
|
4d27b2071e |
fix(realtime): 서버만 끊긴 OFFLINE 실패를 online 대기 없이 재시도한다 (0929/04-01)
문제: SSE 어댑터는 fetch 거절과 열린 스트림의 reader 거절을 모두 OFFLINE(retryable)으로 보고한다. reconnect coordinator는 transport가 OFFLINE을 보고하면 requireOnline()으로 "새 online 이벤트"를 요구했다. 서버만 내려가거나 프록시가 연결을 끊으면 브라우저 navigator.onLine은 true 그대로라 online 이벤트가 오지 않는다. run이 재시도도 종료도 없이 RUNNING으로 멈췄다(리뷰 재현: 20분 동안 fetch 1회, 결과 없음). 고른 방법: 수정안 b. coordinator의 attempt 실패 경로와 classifyClosed 경로에서 transport OFFLINE 뒤의 requireOnline() 두 줄을 지운다. 이제 transport OFFLINE은 다른 retryable 실패처럼 backoff로 재시도하고, 시도 상한이나 elapsed 상한에 닿으면 마지막 실패로 끝난다. online 대기는 환경 신호(observeOnline(false))가 offline을 알렸을 때만 한다. - 리뷰의 MU1은 "&& !online" 조건을 붙이는 방식이었다. 두 지점에 닿을 때 online은 항상 true다. 그 사이에 offline이 오면 wentOffline 분기가 먼저 받고, observeOnline(false)가 이미 requireOnline()을 부른다. 그래서 조건을 붙이는 것과 줄을 지우는 것은 동작이 같고, 지우는 쪽이 짧다. - 규칙은 RealtimeReconnectEnvironment 주석과 설계 5.3절에 적었다. 버린 대안: 수정안 c(SSE가 네트워크 거절을 PROVIDER_UNAVAILABLE로 보고). SSE 한 곳의 어휘만 바뀌고 coordinator의 함정은 남는다. 조합 코드가 classifyClosed에서 OFFLINE을 돌려주거나 다른 transport가 OFFLINE을 보고하면 같은 방식으로 멈춘다. OFFLINE을 보고 화면에 "오프라인"을 띄우는 소비자의 분류도 바뀐다. b는 모든 transport가 지나는 한 곳에서 고친다. (d) online 대기에 상한 시간을 두는 방식은 상수와 상태가 늘어서 버렸다. 위험·한계: - 환경 offline 이벤트보다 transport 실패를 먼저 보면, 첫 backoff 타이머가 잡힌다. offline 이벤트가 오면 그 sleep을 끊고 online을 기다린다(새 테스트 "after"가 고정). offline 이벤트가 타이머보다 늦게 오면 헛시도가 한두 번 생길 수 있다. 시도 상한 안이다. - lie-fi(브라우저는 online, 실제 네트워크 없음)에서는 이제 상한까지 재시도한 뒤 OFFLINE으로 끝난다. 설계 5.3의 "budget 소진 뒤 fallback"과 같다. - 0929/04-02(열린 SSE 세션 bridge 부재)는 그대로다. 테스트 안의 sseAttempt는 설계 6.3이 조합 코드에 맡긴 최소 bridge다. - 설계 문서의 reconnect-coordinator.ts 줄 번호를 새 위치로 고쳤다. - 레시피 번들(realtime): 40,886 -> 40,863 / 40,900 gzip B. 예산은 바꾸지 않았다. 검증: - RED(수정 전): `node scripts/run-vitest.ts run tests/unit/realtime/realtime-reconnect-coordinator.test.ts` -> X1·X2 2건 실패 "expected "vi.fn()" to be called 3 times, but got 1 times". 실제 offline 대기 테스트 2건(before/after)은 통과. - GREEN: `node scripts/run-vitest.ts run tests/unit/realtime/` -> 14파일 225건 통과(기존 221 + 새 4). - 변이: 수정 위에 MU2(SSE 거절 -> PROVIDER_UNAVAILABLE)를 넣으면 X1·X2 2건 실패. - `node scripts/run-vitest.ts run tests/unit` -> 165파일 2357건 통과. - `npx tsc --project tsconfig.app.json --noEmit`, `npx tsc --project tsconfig.test.json --noEmit` -> 오류 0. - `npx eslint <바꾼 ts 2개> --max-warnings=0` -> 통과. - `node scripts/check-realtime-boundaries.ts` -> PASS. - `node scripts/verify-documentation-readiness.ts` -> PASS_SCOPED. - `node scripts/check-optional-recipes.ts` -> PASS, realtime 40863/40900. - 미실행: check:architecture(pnpm을 띄운다). depcruise 직접 실행은 0 modules로 끝나 의미가 없다. import는 바꾸지 않았다. Refs: docs/reviews/2026-11-01-maturity-review/04-adapters-realtime.md 2절, 6.1절 |
||
|
|
112c870fe3 |
fix(reference): 처리 중 409를 결과 불명으로 보고 같은 키를 유지한다 (0929/03-01)
문제
참조 기능의 생성 분류기가 모든 409를 NOT_APPLIED로 판정한다
(reference-feature-contract-contribution.ts:42-44). 결과 불명 쓰기를 같은
멱등 키로 다시 보냈을 때 첫 요청이 아직 처리 중이면 짝 백엔드 템플릿은
409 IDEMPOTENT_IN_FLIGHT를 준다. 그러면 코디네이터가 intent를 정리하고
conflict를 세우고(application-query.ts:584-589), 폼은 결과 불명 기록을
지운다(use-app-form.ts:227-230). 화면이 "충돌"로 바뀌고 저장 버튼이 다시
열려 다음 저장이 새 키로 나간다. 첫 요청이 끝나면 같은 리소스가 두 번
생긴다(키 [K, K, K']).
고른 방법
분류기가 409를 problem code로 나눈다. fixture가 선언한 충돌 code
(CREATE_NOT_APPLIED_CONFLICT_CODES, 지금은 MSW fixture가 내는 "CONFLICT"
하나)만 NOT_APPLIED다. IDEMPOTENT_IN_FLIGHT, code 없는 409, 모르는 code의
409는 MAYBE_APPLIED다. 결과 불명이 유지되므로 코디네이터가 intent를 들고
있고 다음 전송이 같은 키를 쓴다. 400·422 판정은 바꾸지 않았다.
시나리오 카탈로그에 in-flight-409를 더해 "처리 중 409 -> 결과 불명"과
"충돌 409 -> 적용 안 됨"(기존 conflict-409)을 둘 다 고정했다.
버린 대안
- IDEMPOTENT_IN_FLIGHT 하나만 MAYBE_APPLIED로 빼기: 모르는 409가 계속
NOT_APPLIED다. 백엔드가 처리 중 code를 바꾸거나 다른 백엔드를 붙이면
같은 결함이 조용히 돌아온다. "모르는 409는 안전한 쪽" 결정과 어긋난다.
- 플랫폼 방어(같은 intent의 재전송이 NOT_APPLIED를 받아도
APPLIED_CONFIRMED 전까지 키 결합을 유지, 리뷰 03 5절 A의 (b)): 분류기가
틀려도 막지만 application-query의 admission 수명 규칙을 바꾸는 구조
변경이다. 이번 범위를 넘어 뺐다.
- 계약 문서의 409 IDEMPOTENCY_KEY_REUSED(같은 키·다른 지문)를 NOT_APPLIED
목록에 넣기: 프론트는 canonical 입력이 같을 때만 같은 키를 쓴다. 이
응답은 서버와 클라이언트의 지문 기준이 어긋났다는 뜻이고 같은 키의 앞선
요청은 적용됐을 수 있다. NOT_APPLIED로 풀면 다음 저장이 새 키로 중복을
만든다. 그래서 모르는 409와 같이 MAYBE_APPLIED로 둔다.
위험·한계
- 백엔드 계약(이 repo에서 끝낼 수 없음): backend-api-and-server-state-
contract.md §6은 같은 키 동시 재전송을 "bounded IN_PROGRESS 결과"라고만
적고 status·code를 정하지 않는다(:299-300). 409 + IDEMPOTENT_IN_FLIGHT로
고정하고, 진짜 충돌을 뜻하는 409 code 목록을 계약에 적어야 한다. 짝
백엔드 템플릿(01a8a2a, 읽기만 함)은 OperationalError.IDEMPOTENT_IN_FLIGHT
(CONFLICT, 409, retryable=false)를 쓴다. 승인자: 템플릿 소유자, 백엔드
템플릿 소유자.
- problem 형태: 짝 백엔드 web 어댑터는 실패를 problem+json이 아니라
Envelope {success:false, error:{code,...}}로 보낸다(ErrorResponseFactory).
참조 fixture는 최상위 code가 있는 problem 형태다. 그 Envelope가 오면
referenceProblemSchema 검증이 실패해 MAYBE_APPLIED가 되므로 안전 쪽이지만
code 분류는 닿지 않는다. 제품 계약 패키지가 code 위치를 정해야 한다.
- 화면 종류는 여전히 mapProblem이 409 전부를 CONFLICT로 만든다
(reference-http-gateway.ts:38). 폼이 effect를 먼저 보므로 결과 불명이
이기지만, 효과와 화면 종류가 두 함수에 나뉜 문제(03-04)는 그대로다.
"처리 중" 전용 문구는 없고 일반 결과 불명 문구를 보인다.
- 다운스트림 tech-log 분류기는 4xx 전체를 NOT_APPLIED로 쓴다(지난 라운드
확인). 동기화 때 같은 수정이 필요하다.
- 카탈로그 실행 수가 54 -> 57이 된다. 문서 세 곳의 "19개"와
run-http-scenario-evidence.ts 출력 문구를 맞췄다.
- 초기 JS gzip +37 B(203,507 -> 203,544, 예산 204,800). 같은 build-frontend로
두 번 빌드해 gzipSync로 쟀다. 예산은 바꾸지 않았다.
검증
- RED(수정 전): reference-production-vertical "keeps the key when the
resend meets the first attempt still in flight" 실패, 키 [K, K, K'].
분류 단위 테스트 3건 "expected 'NOT_APPLIED' to be 'MAYBE_APPLIED'"
(IDEMPOTENT_IN_FLIGHT, 모르는 code, code 없음).
카탈로그 CREATE_REFERENCE_RESOURCE::in-flight-409 불일치.
- GREEN: 같은 세 파일 23/23 통과.
- 회귀: run-vitest tests/features tests/component tests/contract
tests/integration tests/unit(pnpm을 띄우는 security-followup-archive
제외) 233 files / 2817 tests 통과. tests/runtime-schema 56 통과.
tsc app/test/node rc=0. 바꾼 파일 eslint rc=0. check-adapter-inventory
PASS. verify-documentation-readiness PASS_SCOPED.
- 미실행: check:architecture(pnpm 필요). depcruise 직접 실행은 TS 7을
읽지 못해 0 modules라 사실상 미검증. src 변경은 import를 더하지 않는다.
check:ci 미실행.
Refs: docs/reviews/2026-11-01-maturity-review/03-adapters-http-state.md
|
||
|
|
49d8675f97 |
fix(design-system): 컴포넌트 토큰 사용 검사가 이름 전체를 맞춰 본다 (12-01, 12-02)
문제: UI-03 규칙은 source.includes(`var(${token}`)로 독자를 찾는다.
"var(--field-border"가 var(--field-border-invalid) 안에도 있어서, 독자가
0곳이던 --field-border를 통과시켰다. 주석 안의 var(--x)도 독자로 셌다.
그리고 이번 브랜치의 디자인 규칙 4개(포커스 대비, oklab 혼합, 토큰
사용, 첫 글꼴)는 스크립트 본문에 바로 있어서, 규칙을 꺼도 잡는 테스트가
없었다(12-02).
고른 방법:
- 규칙 4개를 scripts/lib/design-system-rules.ts의 순수 함수로 옮긴다.
입력은 CSS 글자와 토큰 맵이고 출력은 실패 메시지다. 메시지 문구와
순서는 그대로다.
- 토큰 독자는 var(--name) 또는 var(--name, ...)처럼 이름 전체가 맞아야
한다. "var"는 대소문자를 무시하고, 사용자 정의 속성 이름은 CSS 규칙
대로 대소문자를 구분한다.
- 토큰 사용 규칙과 oklab 혼합 규칙은 CSS 주석을 지우고 본다(리뷰 probe
B5 우회, B12 오탐).
- oklab 혼합 규칙은 대소문자를 무시한다(B1 `in OKLCH` 우회). CSS
키워드는 대소문자를 구분하지 않는다.
- ui-design-audit.md의 UI-03 행에 다섯 번째 토큰을 적는다.
버린 대안: 12-02가 제안한 --root 인자와 CSS 음성 fixture 폴더. 규칙별
검출을 증명하려면 어차피 실패 메시지를 단언하는 테스트가 필요하고,
순수 함수 단위 테스트가 fixture 파일 없이 같은 것을 증명한다. 게이트의
--fixture 모드와 산출물 스키마는 바꾸지 않았다.
위험·한계:
- 주석 제거는 정규식이라 따옴표 문자열 안의 "/*"를 주석 시작으로
본다. 지금 CSS에는 없다.
- 12-03의 나머지 우회(그라디언트, TSX 인라인, base.css 재정의,
outline-offset 0, feature CSS)와 12-04의 오탐(-apple-system, deg,
알파, color-mix 표면)은 그대로다. 포커스·글꼴 규칙은 주석을 지우지
않는다.
- 게이트의 check:design-system:fixture는 여전히 TSX fixture 두 개만으로
"기대 실패"를 채운다. CSS 규칙 회귀는 test:unit이 잡는다.
검증:
- RED(규칙을 동작 그대로 옮긴 상태): tests/unit/design-system-rules.test.ts
11개 중 5개 실패. "does not count a longer token that starts with the
same name"이 "expected [] to deeply equal [ Array(1) ]"로 실패했다.
나머지 4개는 대문자 OKLCH, 주석 안 혼합, VAR( --x , ...) 형태, 주석
안 독자.
- 고친 검사를 앞 커밋 전 CSS(
|
||
|
|
3a0ac74d4e |
fix(design-system): 입력란 테두리가 --field-border 토큰을 읽게 한다 (12-01)
문제: .ui-field__input 테두리는 계약 토큰 --field-border 대신 color-mix(in oklab, var(--color-content-muted) 55%, var(--color-panel)) 를 직접 쓴다. 제품이 --field-border로 입력란 테두리를 바꿔도 화면이 그대로다. 이 식은 패널 대비 라이트 2.53:1, 다크 2.98:1이라 WCAG 1.4.11이 입력란 경계에 요구하는 3:1보다 낮다. check:design-system은 var(--field-border-invalid) 글자를 --field-border의 독자로 세어 이것을 놓쳤다(검사 수정은 다음 커밋). 고른 방법: 테두리가 var(--field-border)를 읽게 한다. 토큰값은 계약 그대로 --color-border-strong이다. 버린 대안: 토큰값을 지금 계산식으로 바꾸기. 화면은 안 바뀌지만 3:1 미달을 토큰에 굳히고, 다크 테마에서도 계약의 border-strong과 따로 노는 색이 남는다. 위험·한계: 입력란 테두리가 두 테마 모두 진해진다(화면 변경). 시각 골든은 이 커밋에서 갱신하지 않았다. 대비는 계산값이고 브라우저 실측은 하지 않았다. 검증: scripts/lib/oklch-contrast.ts로 --field-border 대비를 계산했다. - light: panel 6.52, surface 6.24, surface-muted 5.47, elevated 6.52 - dark: panel 4.19, surface 4.54, surface-muted 3.74, elevated 3.90 - 바꾸기 전 식(oklab로 직접 섞은 값): light 2.53, dark 2.98(panel 대비) node scripts/check-design-system.ts PASS. Refs: docs/reviews/2026-11-01-maturity-review/12-guardrails-ci.md 12-01 |
||
|
|
ddf411e4e2 |
fix(bootstrap): ANONYMOUS 프로필 요청을 세션 상태와 상관없이 보낸다 (09-01)
조립 루트의 attachCredentials가 operation의 인증 프로필을 보지 않고 세션 상태만 본다. 그래서 auth: "none" operation(ANONYMOUS 프로필)이 로그아웃이면 UNAUTHENTICATED, 로그인이면 세션 헤더가 붙어 CREDENTIAL_HEADER_NOT_ALLOWED로 거절되고, 외부 owner가 없으면 CREDENTIAL_OWNER_UNAVAILABLE로 끝난다. 어느 상태에서도 fetch가 0회다. scope 확인 바로 다음에 INSTALLED_REST_AUTH_PROFILES에서 operation.authProfileId의 transport를 읽고, ANONYMOUS면 세션을 보지 않고 빈 헤더로 READY를 돌려준다. executor에 넘기는 레지스트리와 같은 값을 같은 객체 안에서 읽는다. 그 밖의 프로필은 기존 경로 그대로다. 버린 대안: - executor(http-execution-v3.ts)가 ANONYMOUS면 attachCredentials를 부르지 않게 하기. adapter 공개 동작이 바뀐다. 지금 executor는 익명 프로필에도 협력자를 부르고 헤더를 내면 거절하며, 이 동작을 고정한 계약 테스트가 있다. 세션을 아는 쪽은 조립 루트라서 판단도 거기 둔다. - 리뷰 R1(attachCredentials를 createCredentialAttacher로 꺼내기). 구조 변경이라 이번 범위를 넘는다. 09-02에서 함께 다룬다. 새 테스트가 실제 createRuntimeAdapters를 거치므로 그때도 그대로 쓸 수 있다. - 새 케이스를 tests/unit/runtime-adapters.test.ts에 넣기. vi.mock은 파일 단위라 설치된 계약 묶음을 바꾸면 그 파일의 기존 테스트에도 번진다. 그래서 runtime-adapters-auth-profile.test.ts를 따로 만들었다. 위험·한계: - 로그인 상태의 익명 호출에 토큰이 붙지 않고 owner에게도 가지 않는다. ANONYMOUS 프로필이 자격증명 헤더를 하나도 허용하지 않으니 의도한 결과다. 인증 통합이 실패한 상태에서도 공개 읽기는 나간다. - scope fence는 익명 분기보다 먼저 본다. 모르는 프로필 id는 executor가 attachCredentials 전에 UNKNOWN_AUTH_PROFILE로 막는다. - 브라우저 화면은 보지 않았다. test:sample-removal도 돌리지 않았다. 새 테스트는 템플릿 소유 fixture와 src/contracts의 프로필만 쓴다. - tech-log 제품 쪽 우회는 다음 동기화 때 지운다. 검증: - RED(수정 전): 새 테스트 11건 중 5건 실패. ANONYMOUS 4개 상태가 expected 'UNAUTHENTICATED' to be 'SUCCESS'(demo 로그아웃), expected 'AUTH_INTEGRATION_FAILURE' to be 'SUCCESS'(demo 로그인, 외부 owner 로그인, owner 없음)로 실패. owner의 attachCredential이 1회 불림. 인증 필요 프로필의 UNAUTHENTICATED, CREDENTIAL_OWNER_ UNAVAILABLE 2건, fence 중 ABORTED_BY_SCOPE, 로그인 후 bearer 전송, 익명 요청의 SCOPE_FENCED 6건은 수정 전후 모두 통과. - GREEN: 새 테스트 11/11 통과. - 회귀: runtime-adapters, http-execution-v3(unit·integration), auth-recovery, legacy-http-credential-authority, tests/features, tests/component, 영역 R1 목록 71 files / 485 tests 통과. - tsc(tsconfig.app.json, tsconfig.test.json) 오류 0. 바꾼 두 파일 eslint 통과. check:architecture(pnpm 대신 exec 대행) 통과, 376 modules. Refs: docs/reviews/2026-11-01-maturity-review/09-app-core.md 09-01 |
||
|
|
c024182951 |
test(system): exact-five CLI의 current 모드 PASS 문구를 기대한다 (0929/11-01)
문제: 13-04( |
||
|
|
185a2aee68 |
test(system): supervisor argv를 실행 중 기록에서 확인한다 (11-01)
문제: cgroup 테스트("applies effective aggregate cgroup limits ...")는
`await execution.completion` 뒤에 `showProcessArguments(child.pid)`로
supervisor의 argv를 다시 조회한다. completion은 child의 `close`에서
풀리고, 그때 Node는 이미 child를 회수했다. `/proc/<pid>/cmdline`도
`ps -p`도 실패해서 이 테스트는 부하와 관계없이 항상
`ps failed: `로 끝난다. 바로 위 주석은 "아래는 실행 기록을 읽는다"고
적어서 코드와 반대로 말했다. 완료 전의 live 조회(`:793`)도 provider가
1.5초 뒤 끝나므로 부하가 있으면 같은 이유로 실패할 수 있다.
고른 방법: 이미 있는 샘플러 `recordProviderProcessTree`가 5ms마다
supervisor 자신의 argv도 읽어서, 서로 다른 값을 모두 기록한다.
완료 전 live 조회와 완료 후 조회를 이 기록으로 바꿨다. 단언은 줄이지
않았다.
- supervisor argv에 command와 credential이 없다(`:793`의 정규식 그대로).
- 기록에 `run-and-validate-provider.ts`가 있다. 기록이 비어서 위
단언이 공짜로 통과하는 경우를 막는다.
- 실행 중 `process.title`로 argv를 바꿔도 값마다 남기므로, 순간 한
번을 본 live 조회보다 넓게 본다.
버린 대안:
- 완료 후 조회 줄을 지운다: supervisor argv 검사가 사라진다.
- 완료 전 스냅샷을 한 번 더 찍는다: `:793`과 같은 방식이라 부하에서
provider 종료와 경쟁한다.
- `ps` 실패를 무시한다: 결함을 숨기고 검사가 공짜로 통과한다.
위험·한계: 샘플링 간격(5ms)보다 짧게 바뀌었다 돌아오는 argv는 놓칠 수
있다. 다른 프로세스 기록과 같은 한계다. 이 테스트는 base fixture가
`corepack pnpm build:release-candidate`를 부르므로 worktree에서
실행하지 않았다. `-t 'aggregate cgroup'` 반복 실행과 `test:system` 전체
통과는 메인 checkout에서 확인해야 한다.
검증:
- RED: 게이트 로그 test_system.log(d99301b, 메인 checkout 실행)에서 이
테스트가 `Error: ps failed: `로 `:810:7`에서 실패. 2 failed /
110 passed. d99301b..402e1db 사이 scripts·tests/system 변경 없음.
- 메커니즘: 테스트 파일에서 `readProcessArguments`·`showProcessArguments`·
`recordProviderProcessTree` 원문을 잘라 타입만 지우고, 수명이 짧은
child에 돌렸다(scratchpad/fix-11-01/recorder-check.mjs).
- 수정 전 20회: close 뒤 조회 실패 20, supervisor argv 기록 0,
실행 중 title 유출 기록 0
- 수정 후 20회(loadavg 1.6): 조회 실패 20, 기록 20, 유출 기록 20
- 수정 후 30회, busy loop 20개(loadavg 17.9): 기록 30, 유출 기록 30
- `npx tsc --project tsconfig.test.json --noEmit`, `tsconfig.node.json`
통과. `npx eslint tests/system/ci-runner/ci-artifact-contract.test.ts`
통과.
Fixes:
|
||
|
|
c7b9cb8818 |
fix(service-worker): SW 빌드가 public/을 다시 복사하지 않게 한다 (0929/06-01)
문제: SW를 ACTIVE로 켜면 build-frontend 6단계의 SW Vite 빌드가 Vite 기본값대로 public/을 dist에 다시 복사한다. 4단계가 프로필로 만든 dist/config.json이 public/config.json(local, demo 인증, http://localhost:8080/, 루트 release manifest)으로 덮어써진다. 빌드와 verify-release는 통과하고 release admission만 거절한다. 그래서 SW를 켠 제품은 local이 아닌 릴리스를 만들 수 없다. VITE_ROUTER_BASE_PATH를 쓰면 RELEASE_MANIFEST_URL도 base를 잃는다. 고른 방법: vite.service-worker.config.ts에 publicDir: false를 넣는다. dist에는 3단계 앱 빌드가 이미 public/을 복사해 두었고, 워커 번들은 public/ 파일을 쓰지 않는다. 같은 repo의 다른 두 번째 Vite 빌드 (scripts/lib/optional-recipe-bundle.ts)도 같은 설정이다. build-frontend.ts 6단계 주석에 이 조건을 한 줄 적었다. 버린 대안: - build.copyPublicDir: false. 복사만 끄고 public 디렉터리는 계속 설정에 남는다. 워커 빌드는 public/을 쓸 일이 없어 publicDir: false가 의도를 바로 말한다. - 앱 빌드 plugin의 closeBundle에서 워커를 만들기, 또는 Vite build()를 configFile: false로 부르는 스크립트. 둘 다 리뷰 5.2절의 대안이다. two-pass 구조를 바꾸거나 파일이 늘어 이 결함에 비해 범위가 크다. 테스트: tests/unit/service-worker-build-output.test.ts는 임시 복사본에서 SW ACTIVE + APP_PROFILE=production + VITE_ROUTER_BASE_PATH=/app/로 실제 build-frontend.ts를 돌린다. 그리고 dist/config.json이 generateRuntimeConfig("production", env) 결과와 같은지 본다(리뷰의 완료 기준). 설정 객체에서 publicDir === false를 보는 테스트는 수정을 다시 적을 뿐이고, 설정이 5단계 생성물 없이는 로드되지 않아 버렸다. 빌드 1회가 약 2초라 unit 계층에 둔다(build-environment-bundle.test.ts와 같은 방식, docs/testing/taxonomy.md의 짧은 child process 규칙). 복사와 빌드는 e2e 도우미 prepareFixtureBuilds를 재사용하고, 빌드별 env 옵션만 추가했다(기존 호출은 그대로). 이 테스트로 0925/06-10(SW Vite 설정의 dist/config.json 읽기 테스트 없음)도 닫힌다. 위험·한계: 하위 경로에서 사전 캐시 URL이 base를 잃는 문제(0929/06-02)와 워커의 runtime config URL 기본값은 그대로다. 이 테스트는 /app/ 빌드의 설정 문서만 보고 워커 설치는 보지 않는다. Vite 8.1.5 동작 기준이다. check:architecture는 pnpm 스크립트로만 돌아서 실행하지 않았다(src는 바꾸지 않았다). 검증: - RED(수정 전): 새 테스트 실패. APP_ENV local(기대 production), AUTH_MODE demo(기대 external), API_BASE_URL http://localhost:8080/, RELEASE_MANIFEST_URL /release-manifest.json(기대 /app/...) - GREEN: 새 테스트 통과(1.9초) - 수정 전후 production + /app/ 빌드 비교: dist 파일 34개로 같음. 수정 후 RELEASE_TARGET=production check-release-admission ADMITTED, 수정 전 rc 1 - node scripts/run-vitest.ts run tests/unit(pnpm을 띄우는 2파일 제외): 164파일 2343건 통과 - tsc tsconfig.test.json, tsconfig.node.json 통과. 바꾼 4파일 eslint 통과 Refs: docs/reviews/2026-11-01-maturity-review/06-adapters-service-worker-push.md 2절, 13-build-release-supply-chain.md 실험 E-B |
||
|
|
bdc32b6198 |
docs: PRODUCT.md의 예제 제거 주장을 드릴 범위에 맞춘다 (14-04)
PRODUCT.md가 "예제 기능과 라우트는 지울 수 있고, 예제 화면에만 있는 디자인은 남지 않는다"고 적었다. 실제 제거 드릴(test:sample-removal)은 참조 기능만 지운다. 예제 라우트 4개와 홈은 기본 구성이라 남는다. 이 주장을 믿고 예제 화면에 디자인을 넣으면 제품 빌드에 그대로 남는다. PRODUCT.md를 드릴 범위대로 고쳤다. 접근성 수동 검토의 근거를 지워도 되는 SPEC.md에서 docs/accessibility/manual-checklist.md로 바꿨다. README의 "복사 뒤 지워도 되는 파일" 표에 PRODUCT.md를 CLAUDE.md처럼 "제품 것으로 바꾼다"로 넣었다. 예제 화면을 지울 수 있게 만드는 일은 별도 선택이라 하지 않았다(0929/14-03). 위험: 문서만 바뀐다. 검증: deletable-history-documents 테스트 통과, verify:documentation PASS_SCOPED. |
||
|
|
402e1db592 |
docs(review): 2026-11-01 성숙도 리뷰 16개 영역 결과를 추가한다
지난 리뷰(09-29) 뒤로 무엇이 고쳐졌고 무엇이 남았는지, 그리고 이번에 사용자가 요구한 성능 실측·폴더 구조·리팩토링·기능 개발 패턴을 확인한 기록이 없었다. 지난 14개 영역에 15(성능 실측)와 16(폴더 구조·기능 개발 패턴)을 더해 영역 에이전트 16개가 병렬로 리뷰했다. README에는 사용 결정, 차단 항목, 28개 관점 판정, 결정이 필요한 것, 개선 순서, 발견 색인을 모았다. High 4건과 P1 일부(11-01)는 오케스트레이터가 코드에서 다시 확인했다. 위험: 문서만 추가한다. 영역 문서의 기준 커밋 d99301b는 메시지를 다시 쓴 c0c5d9c와 트리가 같다(README 9절). 검증: verify:documentation PASS_SCOPED. 발견 색인은 영역 문서에서 스크립트로 뽑았다(95건, 새 발견 90건). |
||
|
|
c0c5d9c7de |
test(visual): UI 감사 수정 뒤 시각 골든을 다시 찍는다 (UI-01~06)
예전 앱 셸 골든에는 잘린 선택 상자(UI-04)와 분홍 현재 메뉴(UI-02)가 들어 있었다. test:visual:update로 5장을 다시 찍고 눈으로 확인했다. 선택값이 다 보이고, 현재 메뉴가 파랗고, 예제 머리글의 반복 라벨이 없다. 위험: 이 Linux 호스트의 글꼴로 찍었다. 시각 테스트 실행 환경의 글꼴 고정은 UI-05의 남은 절반이다. 검증: test:visual 5건 통과. |
||
|
|
df66cc9e53 |
docs(review): UI 감사 발견별 조치 결과를 기록한다
감사 문서에 발견마다 어떻게 닫았는지가 없었다. 조치 결과 표를 추가했다. 넣은 검사, 커밋, UI-03 범위 확대(읽히지 않던 컴포넌트 토큰 4개), UI-05의 남은 절반(시각 테스트 글꼴 고정), UI-07 재판정(정상 구성과 데모 틀이라 조치 안 함)을 적었다. 위험: 문서만 바뀐다. 검증: 표의 커밋 ID와 검사 이름을 브랜치 기록과 대조했다. |
||
|
|
5008013db2 |
fix(design-system): 표 스크롤 영역에 표 제목으로 이름을 붙인다 (UI-08)
표를 감싼 스크롤 영역이 키보드 포커스(tabIndex 0)를 받지만 역할과 이름이 없었다. 스크린 리더가 이름 없는 정지점으로 읽었다. 영역에 role="region"을 주고 caption을 aria-labelledby로 연결했다. 위험: 없음. 시각 변화가 없다. 검증: 이름 있는 region을 요구하는 컴포넌트 테스트가 고치기 전 실패했고, 고친 뒤 통과했다(design-system-platform.test.tsx 10/10). |
||
|
|
9363fa84e3 |
refactor(examples): 예제 화면 머리글의 반복 "예제" 라벨을 지운다 (UI-06)
예제 화면 4곳이 제목 위에 같은 "예제" 라벨을 달았다. 이미 예제 메뉴 묶음 안에 있는 화면이라 정보가 없고, 예제를 복사하면 이 구성도 따라간다. 예제 화면의 eyebrow만 지웠다. PageHeader의 eyebrow 속성은 남겼다. 접근 상태 화면과 홈은 의미 있는 라벨을 쓴다. 검사는 넣지 않았다. 지울 수 있는 예제 화면의 문구라 검사 비용이 더 크다. 위험: 없음. 예제 화면은 i18n 검사 대상이 아니다. 검증: lint, check:types:app 통과. 시각 골든에 반영했다. |
||
|
|
8576ce16c7 |
fix(design-system): --font-sans가 실제로 그려지는 글꼴을 가리키게 한다 (UI-05)
토큰이 Inter로 시작했지만 Inter를 불러오는 코드가 없었다. Inter가 없는 기기는 자기 글꼴로 그렸고, Inter에는 한글이 없어 한국어는 처음부터 Inter로 그려지지 않았다. 토큰을 시스템 UI 글꼴과 플랫폼별 한국어 글꼴 목록으로 바꿨다(사용자 결정). 한글 웹폰트 배포는 버렸다. 전송량과 글꼴 파일 관리가 생기고, 중립 템플릿에서는 서비스가 브랜드 글꼴로 바꾸면 되기 때문이다. check:design-system이 첫 글꼴이 기본 키워드도 아니고 @font-face로 싣지도 않으면 실패한다. 위험: OS마다 글꼴 모양이 다르다. 시각 테스트 실행 환경의 글꼴 고정은 아직 남았다(UI-05 후반). 검증: 바꾸기 전 검사가 Inter를 보고했고, 바꾼 뒤 통과했다. |
||
|
|
f1b9d3c953 |
fix(shell): 테마·언어 선택 상자가 옵션 폭만큼 넓어지게 한다 (UI-04)
max-width 8.5rem과 7rem 때문에 모든 언어에서 선택값이 잘렸다
("Light then", "Englisl", "라이트 테ㅁ"). 커밋된 시각 골든에도 잘린
머리글이 들어 있어, 시각 테스트가 결함을 정답으로 지키고 있었다.
고정 폭을 지웠다. 좁은 화면은 기존 메뉴 서랍 배치가 그대로 맡는다.
새 i18n e2e 테스트가 ko-KR, en-US, en-XA에서 선택 상자 폭을 브라우저가
옵션에 필요한 폭과 비교한다.
위험: 중간 폭에서 머리글이 넓어진다. responsive·app-shell·theme·compact
테스트가 통과했다.
검증: 새 테스트가 고치기 전 실패했고, 고친 뒤 chromium·firefox·webkit
모두 통과했다.
|
||
|
|
165ed19968 |
fix(design-system): 컴포넌트 토큰을 복사하지 않고 읽게 한다 (UI-03)
계약에 있는 컴포넌트 토큰 4개를 읽는 스타일이 없었다. 기본 버튼은 bg-action을 직접 썼고, 현재 메뉴는 --navigation-active-background의 계산식을 다시 적었다. 그래서 서비스가 이 토큰으로 브랜드를 바꿔도 화면이 바뀌지 않았다. 기본 버튼과 현재 메뉴가 토큰을 읽게 했다. 변형 버튼은 뒤에 오는 같은 우선순위 규칙이라 그대로 덮어쓴다. check:design-system이 계약의 컴포넌트 토큰을 읽는 스타일이 하나도 없으면 실패한다. 위험: 기본 버튼 배경 지정 방식이 utility에서 토큰으로 바뀐다. 보이는 색은 같다. 검증: 바꾸기 전 검사가 토큰 4개를 보고했고, 바꾼 뒤 통과했다. |
||
|
|
bfa7dd9188 |
fix(design-system): 색 혼합을 oklab으로 해서 무채색이 색상각을 끌어오지 않게 한다 (UI-02)
라이트 테마에서 현재 메뉴 배경이 파랑이 아니라 분홍으로 그려졌다. color-mix(in oklch, action 14%, panel)에서 panel이 oklch(1 0 0)으로 색상각 0을 명시해, 보간된 색상각이 255에서 345로 끌려갔다. 15곳의 혼합을 모두 in oklab으로 바꿨다. oklab에는 보간할 색상각이 없다. 흰색을 oklch(1 0 none)으로 바꾸는 방법은 버렸다. 앞으로 생길 무채색 토큰마다 같은 규칙을 기억해야 하기 때문이다. check:design-system이 oklch·lch·hsl·hwb 혼합을 실패로 처리한다. 위험: 섞인 색이 미세하게 달라진다. 시각 골든을 갱신했다. 검증: 바꾸기 전 검사가 15곳을 보고했고, 바꾼 뒤 통과했다. |
||
|
|
35b183b64f |
fix(design-system): 라이트 포커스 링이 모든 표면에서 3:1을 넘게 한다 (UI-01)
라이트 --color-focus가 흰 패널에서 2.33:1, surface-muted에서 1.95:1로 WCAG 1.4.11 기준(3:1)에 못 미쳤다. 포커스 링은 컨트롤에서 3px 떨어져 그려지므로, 대비를 따질 인접색은 컨트롤 뒤의 표면이다. 라이트 포커스를 oklch(0.52 0.15 230)으로 바꿨다. 가장 낮은 대비가 4.24:1이다. 다크는 그대로다. check:design-system이 두 테마에서 포커스 토큰과 표면 토큰 8종의 대비를 계산하고, 3:1 미만이면 실패한다. 안팎 이중 링은 버렸다. 한 색으로 충분하고 링 모양이 바뀌지 않는다. 위험: 포커스 링 색이 진해져 시각 골든이 바뀐다(별도 커밋에서 갱신). 검증: 토큰을 바꾸기 전 검사가 라이트 표면 8종 모두에서 실패했고, 바꾼 뒤 통과했다. 계산식은 브라우저 실측값 2.33:1과 일치한다 (tests/unit/oklch-contrast.test.ts). |
||
|
|
b28715c783 |
docs: PRODUCT.md와 2026-11-01 UI 디자인 감사 문서를 추가한다
impeccable이 읽을 제품 정보(사용자, 목적, 제약, 원칙)가 없었다. 화면 품질을 실제 브라우저에서 잰 기록도 없었다. PRODUCT.md에는 사용자 답으로 확인한 제품 사실만 적었다. 감사 문서는 6개 화면을 라이트·다크, 1280·375·320 폭에서 잰 발견 8건(UI-01~08)을 가이드 36.3 양식으로 적었다. DESIGN.md는 만들지 않았다. 토큰 값을 문서 머리에 복사하는 형식이라 tokens/*.css와 갈라진 복사본이 생긴다. 위험: 문서만 추가한다. 동작 변경은 없다. 검증: verify:documentation PASS_SCOPED. |
||
|
|
752a61f28b | refactor: 리펙토링 문서 추가 | ||
|
|
af3d8e6ffe |
docs(review): record the calls deferred during the maturity review round
FOLLOW-UP.md lists, with priority and code locations, what this round left as it is although practice would not: raised bundle budgets and the near-full initial JS budget, the ungated remediation ledger check, the readSubject breaking change, load-flaky tests, gaps outside the completion criteria, and test-side workarounds. README section 11 links it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
f753669333 |
docs: record the WebKit run now that the host can launch it
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>v0.2.0 |