6ea9e4afa6393d55b7928aeae1ada79a78e2a65b
293
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
183a4a373d |
feat(contracts): 짝 백엔드 CSRF 헤더 x-xsrf-token을 자격증명 헤더에 더한다 (1101/09-02)
문제
짝 백엔드는 쿠키 세션의 CSRF를 Spring CookieCsrfTokenRepository로
검사하고, 기본 헤더 이름은 X-XSRF-TOKEN이다(백엔드 SecurityConfig.java,
docs/registries/env-keys.yaml APP_SESSION_CSRF_HEADER_NAME). 프론트의 닫힌
자격증명 헤더 목록(VD-23, rest-profiles.ts CREDENTIAL_HEADER_NAMES)에는
x-csrf-token만 있다. 제품 인증 프로필이 x-xsrf-token을 allowed·required에
적으면 프로필 레지스트리 설치가 모듈 로드 때 throw한다. 그래서 memento가
템플릿 파일을 고쳤고, 09-02(
|
||
|
|
47fec5c27c |
fix(query): 처리 중 409의 Retry-After 전 재전송은 그 시각까지 기다린다 (백엔드 1101/02-01)
문제
짝 백엔드는 같은 키의 첫 요청이 아직 실행 중이면 409
IDEMPOTENT_IN_FLIGHT, retryable=true, Retry-After: 2를 준다(백엔드
docs/web/http-contract.md §2). 클라이언트 행동은 "같은 키로 Retry-After 뒤
재전송"이다.
- 같은 키: 0929/03-01이 이 409를 MAYBE_APPLIED로 두어 코디네이터가 intent를
붙든다. 재전송은 같은 키를 쓴다(기존 vertical 테스트가 [K, K, K]를
고정). 이 부분은 이미 맞다.
- Retry-After: 지키지 않는다. V3는 응답 metadata에 retryAfterMs를 읽지만
feature binding이 PROBLEM을 AppFailure로 옮길 때 버린다. V2는 409의
Retry-After를 읽지 않는다. 그래서 결과 불명 화면의 "같은 요청으로 다시
보내기"(또는 같은 입력 다시 저장)를 바로 누르면 즉시 나가서 같은 409를
한 번 더 받는다.
고른 방법
재전송이 그 시각 전이면 기다렸다 보낸다.
- feature binding이 PROBLEM의 metadata.retryAfterMs를 AppFailure에 싣는다.
V2는 409의 Retry-After도 읽는다(409는 여전히 자동 재시도하지 않는다).
- mutation 코디네이터(application-query.ts)가 MAYBE_APPLIED로 남기는
admission에 resendNotBefore = 지금 + min(retryAfterMs, 5초)를 적는다.
같은 intent를 다시 쓰는 submit(재전송 버튼, 같은 입력 저장)이 그 시각까지
기다린 뒤 보낸다. 기다리는 동안 admission이 ACTIVE라 화면은 pending이다.
scope가 바뀌면 기존 mutationFn 검사가 NOT_STARTED로 막는다.
- 상한 5초는 V3 실행기의 Retry-After 상한(RETRY_AFTER_CEILING_MS)과 같다.
더 일찍 보내도 같은 키라 서버가 다시 409를 줄 뿐 두 번 적용하지 않으므로,
긴 Retry-After를 다 기다리게 하지 않는다.
버린 대안
- Retry-After 전에는 버튼을 막기: 화면과 시각 회귀 골든이 바뀌고, 다시
열어 줄 타이머와 문구가 더 든다. 기다렸다 보내는 쪽이 변경이 작다.
- V3 실행기가 키별 "이 시각 전 금지" 표를 들기: 실행기에 키를 기억하는
상태와 정리 규칙이 생긴다. 재전송을 만드는 곳은 코디네이터 하나다.
- 그대로 두기(이른 재전송은 409를 한 번 더 받을 뿐): 서버 문서가 허용하는
동작이지만 사용자는 같은 결과 불명 화면을 한 번 더 본다. 요구는
Retry-After를 지키는 것이다.
위험·한계
- AppFailure.retryAfterMs가 V3 PROBLEM에도 실린다(추가 필드). 이 값을 읽는
곳은 코디네이터뿐이다.
- 기다림은 MAYBE_APPLIED로 남은 admission을 다시 보낼 때만 생긴다. 다른
상태(NOT_APPLIED 등)는 그대로다.
- 시계는 performance.now(), 대기는 setTimeout이다. 탭이 백그라운드면
브라우저가 타이머를 늦출 수 있다(더 늦게 보낼 뿐이다).
검증
- RED: 4행 실패.
- tests/features/reference-feature/reference-production-vertical.test.tsx
처리 중 409(Retry-After: 1) 뒤 재전송 간격 39.7ms(기대 990ms 이상)
- tests/component/application-mutation-admission.test.tsx 재전송이
retryAfterMs 300을 기다리지 않음
- tests/features/reference-feature/reference-http-problem-mapping.test.ts
retryAfterMs 없음
- tests/integration/http-client.test.ts V2 409 retryAfterMs 없음
상한 행은 수정 전에도 통과하고, 상한을 뺀 변이에서 시간 초과로 실패하는
것을 확인했다.
- GREEN: 위 행 모두 통과. tests/component·features·contract/reusable-
capability, tests/integration/http-client·http-diagnostics, tests/unit/
http-execution-v3 62 files 491 tests 통과. tsc app·test 통과, 바꾼 파일
eslint 통과.
Refs: clean-architecture-backend-template docs/reviews/2026-11-01-maturity-review/README.md 14.3, 15
|
||
|
|
93782b0fce |
fix(http): 멱등성 거절 422·400을 적용 안 됨으로 보고 원인을 남긴다 (백엔드 1101/02-01)
문제
짝 백엔드는 KEYED 요청을 실행하기 전에 두 가지를 거절한다(백엔드
docs/web/http-contract.md §2).
- 422 IDEMPOTENT_REQUEST_MISMATCH: 같은 키에 다른 본문. 클라이언트 버그.
- 400 IDEMPOTENCY_KEY_INVALID(details.reason MISSING·MALFORMED): 키 누락·
형식 오류.
둘 다 이 요청은 적용되지 않았고, 그대로 다시 보내면 같은 답이 온다.
- V2(client.ts)는 이 실패에 effect를 붙이지 않는다. mutation 코디네이터는
effect가 없으면 MAYBE_APPLIED로 보고(application-query.ts
mutationFailureWithEffect) 키를 붙든다. 400은 결과 불명 화면으로 가고,
같은 입력을 다시 저장하면 같은 키로 같은 400·422를 계속 받는다. 진단
이벤트(http.request.completed)에는 원인이 없다.
- V3 참조 기능은 분류기가 400·422를 이미 NOT_APPLIED로 본다. 다만
mapProblem이 400을 다루지 않아 code가 CONTRACT_PROBLEM으로 바뀌고
서버의 IDEMPOTENCY_KEY_INVALID가 사라진다.
고른 방법
- V2: 문서에 적힌 status와 code가 둘 다 맞을 때만 effect NOT_APPLIED를
붙인다(IDEMPOTENCY_REFUSALS 표). 같은 표가 진단 reason을 준다.
- 422 → reason IDEMPOTENT_REQUEST_MISMATCH
- 400 → reason IDEMPOTENCY_KEY_RULE_MISMATCH. 프론트는 보내기 전에
isValidIdempotencyKey로 키를 검사한다. 서버의 400은 두 키 규칙이
어긋났다는 뜻이라 그 이름으로 남긴다. 보내기 전 거절(VALIDATION_
REJECTED, httpStatus 없음)은 표에 걸리지 않는다.
reason은 diagnostics에만 넣는다. telemetry 속성은 그대로다(VD-07).
- V3 참조 mapProblem: 400 + IDEMPOTENCY_KEY_INVALID만 UNKNOWN_CLIENT_
FAILURE와 서버 code로 둔다. 다른 400은 기존 fallback 그대로다.
- kind는 바꾸지 않았다(422 VALIDATION_REJECTED, 400 UNKNOWN_CLIENT_
FAILURE). 둘 다 retryable:false이고 V2 재시도 대상이 아니다.
- 키 문법은 백엔드 IdempotencyKeyHeader([\x21-\x7E]{1,256}, trim 없음)와
같다. 1자 키를 받는 행을 더해 경계를 고정했다.
버린 대안
- code만 보고 판정: 다른 status에 같은 code가 오면 NOT_APPLIED를 잘못
붙인다. NOT_APPLIED는 다음 저장이 새 키를 쓰게 하는 판정이라 문서의
짝(status+code)만 믿는다.
- 422 mismatch를 UNKNOWN_CLIENT_FAILURE로 바꾸기: 화면 문구가 바뀐다.
요구는 재전송 금지·결과 불명 화면 금지·원인 code 보존이라 kind는 두었다.
- 서버 code를 진단 reason에 그대로 넣기: 서버 code는 무제한이라 진단
cardinality 규칙(taxonomy)을 깬다. 표에 있는 두 값만 넣는다.
위험·한계
- 422 mismatch를 NOT_APPLIED로 보면 다음 저장이 새 키를 쓴다. 같은 키의
앞선 요청이 적용됐을 수 있지만, 프론트는 canonical 입력이 같을 때만 키를
재사용하므로 mismatch는 지문 규칙이 어긋난 버그다. 결정(15절)대로 이번
요청은 적용되지 않았다고 본다.
- 422 화면 문구는 "입력값을 다시 확인해 주세요."다. 사용자가 고칠 입력이
아니지만 다시 저장하면 새 키로 나간다.
- V3 실행기의 진단은 problem code를 모른다(Problem 타입은 계약 패키지
소유). V3에서 원인은 AppFailure.code·httpStatus로만 보인다.
검증
- RED: tests/integration/http-diagnostics.test.ts 새 2행 실패(effect
undefined, reason 없음). tests/features/reference-feature/reference-http-
problem-mapping.test.ts 400 IDEMPOTENCY_KEY_INVALID 행 실패(code
CONTRACT_PROBLEM). 422 mismatch 매핑, 분류기 2행, 1자 키 행은 처음부터
통과(이미 맞는 동작을 고정).
- GREEN: 위 파일과 tests/features/reference-feature, tests/integration/
http-client·http-execution-contract·auth-recovery·legacy-http-credential-
authority, tests/contract/reusable-capability/feature-http-binding 24 files
207 tests 통과. tests/unit/legacy-and-optional-network-remediation 6/6.
tsc app·test 통과, 바꾼 파일 eslint 통과.
Refs: clean-architecture-backend-template docs/reviews/2026-11-01-maturity-review/README.md 14.3, 15
|
||
|
|
969979d904 |
fix(http): 짝 백엔드가 생략한 Envelope 키를 null과 같이 읽는다 (백엔드 1101/02-02)
문제 짝 백엔드는 이제 값이 null인 필드를 키째 뺀다(백엔드 docs/web/http-contract.md §1). V2 Envelope 스키마 (src/adapters/http/schema-registry.ts)는 두 곳에서 "키 없음"을 null과 다르게 읽는다. - 성공 응답의 data: z.unknown()은 키가 없으면 거절한다(zod 4). 백엔드가 data:null을 빼고 보낸 성공이 ENVELOPE_MISMATCH 실패가 된다. data:null은 그대로 통과한다. - meta.requestId·traceId가 필수다. 백엔드는 요청 id 필터 앞에서 끊긴 응답(보안 entry point 등)에서 이 키를 뺄 수 있다고 적는다. 그러면 실패 Envelope 전체가 거절되어 백엔드 error.code가 HTTP_FAILURE로 바뀐다. error.details(키 없음 허용), meta.correlationId(선택), meta.page(strip)는 이미 키가 없어도 받는다. 고른 방법 - data를 z.unknown().default(null)로 둔다. 키가 없으면 스키마가 null을 채우므로 client.ts의 "data" in 검사와 payload 검증이 data:null과 같은 길을 탄다. 정규화가 wire 스키마 한 곳에 있다. - meta.requestId·traceId를 optional로 둔다. safeMeta()는 이미 키가 없는 경우를 처리한다. 버린 대안 - client.ts에서 "data" in 검사를 빼고 data ?? null로 읽기: 스키마와 클라이언트 두 곳이 같은 규칙을 나눠 갖는다. - 성공의 error:null, 실패의 data:null도 다시 받기: 백엔드가 더는 보내지 않는 모양이다. 최상위 strict는 그대로 둔다. 위험·한계 - meta id가 없는 Envelope도 이제 유효하다. 그런 응답의 HttpResult.meta와 AppFailure에는 requestId·traceId가 없다(이전에는 응답 전체가 거절됐다). - V3 실행기는 Envelope를 읽지 않는다(DTO 자체를 검증). 이 변경은 V2 경로만 바꾼다. bulk Envelope(results)는 프론트에 쓰는 곳이 없어 다루지 않았다. 검증 - RED: tests/integration/http-client.test.ts "envelope keys the paired backend omits" 5행 중 2행 실패. data 키 없는 성공이 ok:false, id 키 없는 403이 code HTTP_FAILURE. - GREEN: 같은 5행 통과. tests/integration/http-client·http-diagnostics· http-execution-contract·auth-recovery·legacy-http-credential-authority, tests/runtime-schema 8 files 150 tests 통과. tsc app·test 통과, 바꾼 파일 eslint 통과. Refs: clean-architecture-backend-template docs/reviews/2026-11-01-maturity-review/README.md 14.3, 15 |
||
|
|
8b7c6ebf6c |
perf(contracts): 검증 생략 목록을 부팅 경로 밖에서 만든다 (1101/07-03)
문제 - 93180f6(합친 커밋 |
||
|
|
ca161878f2 |
feat(routes): 기능이 홈을 대신하고 context가 자기 레이아웃을 선언한다 (1101/09-03)
문제: 라우터는 모든 context gateway를 `AppShell` 하나 아래에 붙이고 플랫폼
`/`를 index로 둔다. 기능이 `APP_HOME`을 선언하면 `composeUniqueRecord`가
throw한다. 그래서 제품 홈이 기능 화면이거나 화면이 `AppShell`이 아닌 자기
셸을 쓰면 제품이 템플릿 라우터와 조립 카탈로그를 고쳐야 한다. memento는
카탈로그 브리지(`APP_HOME` 허용 목록)와 라우터 브리지(`ownsShell`)를 넣고
동기화마다 병합한다. tech-log는 라우터를 PUBLIC/STUDIO 그룹 라우터로 통째로
바꿔 생성기 설치 경로(context gateway)를 쓰지 못한다.
고른 방법: 리뷰 4.3의 (B). 선언 두 개를 연다.
- 홈 대체: 플랫폼이 기능이 대신할 수 있는 라우트 id를 선언한다
(`FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS = ["APP_HOME"]`,
src/contracts/routes.ts). 그 id를 선언한 기능의 정의가 플랫폼 정의를
대신한다. 둘이 선언하면 카탈로그를 읽을 때 두 기능 id를 담아 throw한다
(`withoutTakenOverPlatformRoutes`). 다른 플랫폼 id는 지금처럼 중복 오류다.
라우터는 대체된 라우트를 소유 context와 함께 그 경로에 붙인다.
- context 레이아웃: `BoundedContextRouteModule.loadLayout`(선택). 생성기는
`src/contexts/<context>/context-layout.tsx`가 있으면 그 `CONTEXT_LAYOUT`을
지연 import로 싣는다. 라우터는 그 context를 `AppShell` 형제인 `/` 레이아웃
라우트 아래, 기능의 등록 경로마다 붙인다. 그래서 모르는 URL은 여전히
`AppShell`의 NOT_FOUND로 간다. 선언이 없으면 지금처럼 `AppShell` 아래 루트에
붙는다. 레이아웃 청크 실패는 라우트 청크와 같은 reload-once 복구를 받는다.
- 09-06 불변식을 레이아웃으로 넓힌다. 레이아웃 라우트는 모두 `/`의
형제라서 루트는 레이아웃과 상관없이 그 아래 URL을 가진다. 그래서 기존
루트 검사가 모든 레이아웃에 걸친다. 한 레이아웃 아래 루트 여럿(같은
컴포넌트를 싣는 context들)은 허용한다. 대체된 플랫폼 라우트는 라우터가
경로에 직접 붙이므로 루트 검사에서 뺀다(09-06 재검토 조건).
- tests/unit/product-features.test.ts의 "플랫폼 라우트는 소유자가 없다"
검사가 대체 가능한 id는 건너뛴다. memento가 고쳤던 템플릿 테스트다.
- `ContextRouteModule`에 `featureIds`가 생겨서, `TEMPLATE_APP_MODULE`을
손으로 mock하며 필수 필드 `features`를 빼먹은 두 테스트
(context-route-gateway, context-boundary-diagnostics)에 `features: []`를
넣었다.
버린 대안:
- (A) 현 상태: 제품마다 브리지를 넣고 동기화마다 병합한다.
- (C) `AppShell` 통째 교체: 레이아웃 그룹이 둘인 tech-log를 담지 못한다.
- 같은 레이아웃을 쓰는 context를 로더 함수로 묶어 레이아웃 라우트 하나에
모으기: 만들었다가 지웠다. React 19는 같은 컴포넌트로 풀린 lazy 타입을 같은
타입으로 맞춰 레이아웃 인스턴스를 그대로 둔다. 묶지 않은 변이로 테스트가
그대로 통과해서 쓸모없는 코드였다.
- `CONTEXT_LAYOUT_ID` 리터럴로 다른 context의 레이아웃을 가리키기: 같은
컴포넌트를 내보내는 파일 두 개로 같은 결과가 나와 선언을 하나 덜 둔다.
- 레이아웃 라우트를 `AppShell`보다 앞에 두기(memento 브리지 순서): 경로가
같으면 기능이 플랫폼 라우트를 조용히 가린다. `AppShell`을 앞에 두어
지금처럼 플랫폼이 이긴다.
위험·한계:
- 레이아웃이 skip link와 `<main id="main-content">` 하나를 그리는 것은
계약(타입 주석, starter-experience.md)과 테스트 fixture로만 지킨다. 실행 중
검사는 없다. 레이아웃 로딩·실패 화면에는 `<main>`이 없다(`AppShell`의
errorElement와 같다).
- 레이아웃 렌더 결함(청크 실패가 아닌 것)은 라우트 errorElement로 가고
진단을 남기지 않는다. `AppShell` 렌더 결함과 같다.
- 홈을 대신한 기능을 실행 중에 끄면 `/`는 비활성 기능 화면이 된다. 빌드에서
빼면(`VITE_PRODUCT_FEATURES`) 플랫폼 홈이 돌아온다.
- tech-log의 PUBLIC 셸 안 NOT_FOUND는 표현하지 않는다. 모르는 URL은
`AppShell`의 NOT_FOUND다. STUDIO의 `/studio/*` 라우트는 STUDIO 레이아웃
아래에서 동작한다. tech-log는 기능 하나를 레이아웃 그룹별 기능 둘(context
둘)로 나눠야 한다.
- 플랫폼 라우트와 기능 라우트의 같은 경로는 여전히 검사하지 않는다(
|
||
|
|
d3ddc8957f |
feat(contracts): zod 검증기 어댑터를 공유하고 검증 생략을 이름으로 드러낸다 (1101/07-03)
문제 - zod 스키마를 RuntimeValidator로 바꾸는 zodValidator가 참조 기능의 reference-schemas.ts 안에만 있다. 기능끼리 import가 금지라 새 기능은 복사하고, 복사본은 이미 갈라졌다(tests/helpers 복사본은 성공 값을 structuredClone하지 않는다). 참조 기능을 지우면 어댑터도 사라진다. - RuntimeValidator<T>는 schemaId와 safeParse만 요구한다. 아무것도 검증하지 않는 검증기도 조립을 통과하고, 검증을 생략했다는 사실이 타입·이름·조립 결과 어디에도 남지 않는다. 고른 방법 (C: 공유 어댑터 + 생략 표시) - zodValidator를 src/contracts/zod-validator.ts로 옮긴다. 참조 기능과 tests/helpers/external-contract-fixture.ts가 이것을 import한다. 동작은 참조 기능 쪽 원본 그대로다(성공 값 structuredClone, 경로 배열, code 문자열). tests/helpers도 이제 성공 값을 복사한다. - unvalidatedPayload(schemaId, reason)를 external-contract-runtime.ts에 둔다. 만든 검증기에는 validation: "NONE"과 unvalidatedReason이 붙는다. zod가 필요 없어서 검증기 프로토콜 옆에 뒀다. - composeContractContributions가 이 표시가 붙은 검증기를 unvalidatedPayloads(featureId, contractId, validator, schemaId, reason)로 내놓는다. HTTP의 input·output·problem과 이벤트의 envelope·payload를 모두 본다. 표시가 "NONE"이 아니거나 이유가 비어 있으면 조립을 거부한다. - 플랫폼 개요 화면(스타터 화면)의 계약 절에 "런타임 검증을 생략한 계약" 표를 둔다. 목록이 비면 그리지 않는다. 버린 대안 - (B) 공유 어댑터만: 검증 생략이 여전히 보이지 않는다. - (D) 브랜드 타입으로 zodValidator가 만든 검증기만 받기: 외부 패키지의 자체 검증기까지 막아 §4 설계와 충돌한다. 위험·한계 - 표시 없이 손으로 쓴 통과 검증기(리뷰 실험 L5)는 여전히 조립을 통과하고 목록에도 없다. 이 변경은 생략을 막지 않는다. 이름 있는 길을 만들어 그 길로 생략한 것만 드러낸다. - 공개 계약 추가: RuntimeValidator에 선택 필드 2개, ComposedContractContributions에 필드 1개, 새 export zodValidator· unvalidatedPayload·UnvalidatedPayloadEntry. 기존 호출자는 바뀌지 않는다. ComposedContractContributions를 손으로 만드는 코드는 새 필드를 채워야 한다(repo 안에는 없다). - 초기 JS gzip 204,586 → 204,745 B(+159). 예산 204,800까지 55 B 남는다. 플랫폼 개요 청크 4,625 → 4,750 B. - 참조 기능은 모든 검증기가 검증하므로 화면 모양은 그대로다. 시각 회귀는 돌리지 않았다. - tests/unit/second-api-feature-registries.test.ts의 V2 codec 통과 검증기는 그대로 둔다(16-01이 그 파일을 넓힌다). 검증 - RED(수정 전): zod-validator.test.ts "Cannot find module '../../src/contracts/zod-validator.ts'", external-contract-runtime.test.ts와 starter-platform-overview-page.test.tsx "unvalidatedPayload is not a function". 3파일 모두 실패. - GREEN: 같은 3파일 33건 통과. - 회귀: tests/unit·contract·component·runtime-schema·features·platform 268파일 3,189건, tests/integration 12파일 158건(pnpm을 띄우는 security-followup-archive 제외), tests/architecture 7파일 33건 통과. tsc app·node·test·recipes·web-worker·service-worker 오류 0. 바꾼 파일 eslint 0. check-registries PASS(compatibility=none), verify-documentation PASS_SCOPED, check-adapter-inventory PASS. 아키텍처 그래프 검사(pnpm 대신 exec stub) 383 모듈 PASS. - 참조 기능 삭제 모의: scripts/test-sample-removal.ts의 삭제 목록(기능 폴더, tests/features, reference-context, SAMPLE_EXTRAS)을 복사본에 적용. src/contracts/zod-validator.ts가 남고, tsc app·test 오류 0, 어댑터·조립· 플랫폼 개요·HTTP 시나리오 테스트 4파일 35건 통과. Refs: docs/reviews/2026-11-01-maturity-review/07-contracts.md 07-03, 5.3 |
||
|
|
ee81c448f0 |
fix(reference): 샘플 링크를 route ID로 만들고 route 입력 cast를 없앤다 (1101/16-04)
문제: 경로 정본은 계약의 `routes[*].path`인데, 샘플 페이지가 같은 경로를
문자열로 8곳에 다시 적는다(목록 2, 상세 1, 폼 3, 상태 1, 실패 행동 1).
route 입력은 `routeInput.search as ReferenceListFilters`와
`String(route.params.resourceId)`로 cast한다. 계약에서 경로만 바꾸면 tsc는
통과하고 링크는 NOT_FOUND로 간다. 문서(routing-pages-and-patterns 4.2절,
10절 4단계)는 codec 기반 builder와 cast 금지를 권하는데, 샘플이 반대
패턴을 보여 주고 복사되는 기능이 그 습관을 가져간다.
고른 방법: 이미 있는 URL builder를 쓴다.
- `buildRouteUrl(routeId, input, featureCodecs)`(`src/presentation/routes/
route-codecs.ts`)가 route ID로 계약 `path`를 찾고, 라우터가 parse에 쓰는
같은 codec으로 직렬화한다. canonical redirect도 이 함수를 쓴다.
`src/platform`에는 URL builder가 없다. 그래서 플랫폼에 새 공개 헬퍼를
더하지 않았다.
- 기능 쪽 helper는 `presentation/reference-routes.ts`에 둔다.
- `referenceRouteUrl(routeId, input)`: `buildRouteUrl`에 이 기능의
codec을 넘기는 한 줄 래퍼다. routeId는 이 기능 계약의 키로 좁힌다.
- `useReferenceListFilters()`, `useReferenceResourceId()`: 라우터가 이미
통과시킨 route 입력을 같은 codec으로 다시 parse해서 codec의 출력
타입을 얻는다. cast가 없다. 목록 필터는 `useMemo`로 묶어 route 입력이
그대로면 같은 객체를 준다.
- `REFERENCE_FEATURE_ROUTE_CODECS`를 `reference-feature-runtime.ts`에서
새 `presentation/reference-route-codecs.ts`로 옮겼다.
- runtime 파일이 페이지를 lazy import하므로, 페이지 쪽이 runtime 파일에서
codec을 가져오면 순환 의존이 된다.
- codec 표를 helper 파일에 같이 두지 않은 이유: 그러면
`context-routes.ts`가 router의 builder·hook까지 끌어와 초기 JS가
585 B 늘었다(204,809 B로 예산 204,800 B 초과). 분리하면 475 B다.
- `context-routes.ts`와 `reference-contract.test.ts`는 새 위치에서
가져온다.
- 페이지 8곳을 route ID 호출로 바꿨다. 기능 presentation에 `"/examples/`
문자열이 0건, route 입력 cast가 0건이다. 남은 `"/examples/` 4건은 계약의
`path`(정본)다.
- 기능 README에 helper 위치와 쓰는 법을 적었다.
버린 대안:
- 리뷰 (b)처럼 기능 안에 경로 치환·직렬화를 새로 쓰는 헬퍼: 라우터와 같은
일을 두 번 구현한다. 플랫폼 builder가 이미 route ID와 기능 codec을 받는다.
- 리뷰 (c)처럼 `buildRouteUrl`의 input 타입을 route ID별로 좁히기: 플랫폼은
기능 codec 타입을 모른다(15-01 이후 codec은 지연 적재). 라우터 API
변경이라 이 발견 범위를 넘는다.
- 플랫폼 `useRouteInput`을 제네릭으로 바꿔 타입 단언하기: 런타임 검사 없는
단언이라 cast를 다른 이름으로 옮길 뿐이다.
위험·한계:
- 목록 링크가 이제 정식 URL(`/examples/reference-resources?limit=20`)을
가리킨다. 전에는 `?limit` 없는 주소로 갔다가 라우터가 같은 URL로
replace했다. 도착 URL과 history 항목 수는 같다. 폼의 "목록을 새로
불러와 확인" 링크 href 기대값을 이 값으로 바꿨다.
- `buildRouteUrl`은 codec이 거절하는 입력에 예외를 던진다. 백엔드가
공백만 있는 id를 주면(DTO는 `min(1)`, route codec은 trim 후 `min(1)`)
목록 렌더가 기능 오류 경계로 간다. 전에는 링크가 잘못된 주소 화면으로
갔다. DTO와 route codec의 id 규칙 차이는 이 변경 전부터 있다.
- route 입력을 한 번 더 parse한다. 값이 작아 비용은 무시할 만하다.
- 초기 JS gzip이 204,224 B에서 204,699 B로 475 B 늘었다(예산 204,800 B,
여유 576 B → 101 B). 새 코드가 초기 청크에 들어간 것이 아니다.
`route-codecs.ts`는 원래 초기 청크에 있었다. 페이지가 이 모듈을 import하자
rolldown이 `boot` 청크에 있던 것을 공유 청크(`route-input`)로 옮기고,
`route-input`과 `server-state-scope-provider`를 두 청크로 나눴다. 늘어난
양은 청크 분리 비용이다. 예산 값은 바꾸지 않았다.
- 페이지 테스트의 진입 URL 문자열은 그대로 뒀다. 테스트가 경로를 적는
것은 이 발견의 완료 기준 밖이다.
- 상태 페이지의 `(state as ReferenceSupportState)`는 history state 처리라
route 입력 cast가 아니다. 그대로 뒀다.
검증:
- RED(수정 전): 새 `tests/features/reference-feature/
reference-route-links.test.tsx`는 계약의 네 경로를 모두 옮긴(vi.mock)
상태로 목록→상세→목록→폼→목록, 목록→지원 페이지→목록을 걷는다.
2개 모두 실패했다. 상세 링크가 `href=".../items/reference-1"`(기대
`.../entries/reference-1`), 지원 페이지 대신 NOT_FOUND가 나왔다.
- GREEN(수정 후): 같은 테스트 2개 통과. `tests/features/reference-feature`
18 files 89 tests 통과(href 기대값 1곳 변경 뒤).
- 회귀: tests/features, tests/component, tests/architecture, tests/scale,
관련 unit 3개, generator 테스트 81 files 464 tests 통과. 첫 실행에서는
부하(평균 23~35)로 타임아웃 2건(app-build-input,
global-local-independence)이 났고, 단독 재실행과 최종 재실행에서 통과했다.
- 초기 JS gzip(`scripts/build-frontend.ts` 후 check-bundle과 같은 분류로
측정): 수정 전 204,224 B, 수정 후 204,699 B.
- `tsc` app·test·node 통과. 바꾼 파일 `eslint --max-warnings=0` 통과.
- `check-architecture.ts`(pnpm 대신 exec 전용 shim): 381 modules,
순환·위반 없음, rc=0. `verify-documentation-readiness` PASS_SCOPED,
`check-i18n` PASS.
- 페이지 테스트 harness(`renderReference`, `inputWith`)는 새 테스트와
함께 쓰도록 `reference-page-harness.tsx`로 옮겼다. 내용은 그대로다.
Refs: docs/reviews/2026-11-01-maturity-review/16-structure-patterns.md 16-04
|
||
|
|
b4ccadab77 |
feat(design-system): 제품이 싣는 글꼴을 토큰 계약에 선언하게 한다 (1101/12-04)
문제 첫 글꼴 규칙(check:design-system)은 --font-sans의 첫 글꼴이 일반 키워드이거나 검사하는 CSS 안의 @font-face로 실릴 때만 통과시킨다. 글꼴 패키지 import, @import url(…), index.html의 <link>로 싣는 글꼴은 볼 수 없어 실패한다. memento 토큰이 이미 이 규칙에 걸린다. 선언할 곳이 없으니 제품은 템플릿 소유 스크립트를 고치게 된다. 고른 방법 - token-contract.ts에 PRODUCT_LOADED_FONT_FAMILIES(템플릿은 빈 목록)를 둔다. 제품은 토큰 계약 파일에서 자기가 싣는 글꼴 이름을 적는다. - firstFontFamilyFailures가 세 번째 인자로 이 목록을 받아 @font-face로 실은 글꼴과 같이 허용한다. check-design-system.ts가 목록을 넘긴다. - 실패 메시지에 목록 이름을 넣어 어디에 선언하는지 알린다. - docs/styling/design-system-platform.md 4.1절 표의 첫 글꼴 행을 고친다. - 12-04의 (1)~(3)과 (5)는 e714c0d가 했다(deg·음수 색상각, 지원 형식을 적는 포커스 메시지, -apple-system·BlinkMacSystemFont, 규칙 문서). 이 커밋은 (4)만 한다. 버린 대안 - 패키지 import·<link>를 찾아 실제로 싣는지 판정: 진입점·CDN·번들러 설정까지 봐야 해서 규칙이 커진다. - 목록을 design-system/index.ts로도 내보내기: 앱 코드가 쓰지 않는다. 위험·한계 - 검사는 목록을 믿는다. 글꼴이 실제로 실리는지 보지 않는다. 주석과 문서에 "모든 화면이 싣는 글꼴만 적는다"고 적었다. - 실패 메시지 문구가 바뀐다. 문구를 단언하는 곳은 tests/unit/design-system-rules.test.ts뿐이다. - 새 공개 이름 PRODUCT_LOADED_FONT_FAMILIES가 생긴다. 검증 - RED: 새 테스트 "passes a family the product declares it loads, and only that one"이 실패(expected [ Array(1) ] to deeply equal []). - GREEN: design-system-rules·oklch-contrast·design-system-contract 22/22 통과. - 실제 스크립트 probe: CSS 사본의 --font-sans를 "Pretendard Variable"로 시작하게 하고 node scripts/check-design-system.ts → 빈 목록이면 새 메시지로 실패(exit 1), 목록에 넣으면 PASS(exit 0). 저장소 CSS는 PASS. - tsc(app·node·test), 바꾼 파일 eslint, verify-documentation-readiness PASS_SCOPED. Refs: docs/reviews/2026-11-01-maturity-review/12-guardrails-ci.md 12-04 |
||
|
|
6dd4bc1c24 |
refactor(design-system): primitive를 컴포넌트마다 한 파일로 나눈다 (1101/08-08)
문제 primitive가 종류별 파일 5개(core·forms·overlays·navigation·feedback)에 모여 있다. 번들러는 export가 아니라 모듈 단위로 청크를 나눈다. 그래서 셸이 쓰는 Button·Drawer·Select와 같은 파일에 있는 Tooltip·Menu·Card 같은 갤러리 전용 primitive도 셸과 같은 청크로 간다. 다음 커밋(side effect 없음 선언)이 효과를 내려면 먼저 파일이 나뉘어야 한다. 고른 방법 - primitives/ 아래를 컴포넌트마다 파일 하나로 나눈다(32개). 본문은 원래 줄을 그대로 옮기고 import만 새로 쓴다. ToastProvider·useToast는 한 파일, 내부 타입 FieldCopy는 field.tsx에서 내보낸다. - PaginationLandmarkContext는 pagination-landmark.ts로 따로 둔다. page-templates.tsx(StatusPage, 초기 청크)가 이것만 읽는데, Pagination과 같은 파일이면 Pagination 코드가 초기 청크로 간다. - design-system/index.ts의 export 이름은 그대로다(값 71개, 타입 36개를 전후 비교). components/ui/*.ts 재수출, page-templates.tsx, common-patterns.tsx는 새 경로를 가리킨다. .dependency-cruiser.json의 page-templates 예외는 출발 파일 기준이라 그대로 맞다. 버린 대안 - 셸이 쓰는 것과 나머지 두 파일로 나누기: 제품 셸이 Tooltip 하나를 쓰면 나머지가 다시 초기 청크로 간다. 위험·한계 - 이 커밋만으로는 번들이 바뀌지 않는다. 배럴이 다시 내보내는 모듈은 side effect가 있다고 보고 모두 초기 청크에 남는다(초기 JS 16개 청크, 203,818 → 203,824 B). 다음 커밋이 같이 있어야 효과가 난다. - primitives/ 안의 파일 경로를 직접 import하던 다운스트림 코드는 경로를 바꿔야 한다. 공개 경계(index.ts)는 그대로다. 검증 - 원래 5개 파일의 import 아래 본문 줄이 새 파일에 빠짐없이 한 번씩 있다(줄 다중집합 비교). - tsc(app·node·test) 통과, 바꾼 파일 eslint 통과. - node scripts/run-vitest.ts run tests/component: 35파일 228/228 통과. - 빌드(flock): 초기 JS 16개 청크 203,824 B, ui-tooltip 등 갤러리 클래스는 여전히 초기 청크에 있다(예상대로). Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-08 |
||
|
|
72edb55475 |
fix(storage): 손상 행을 건너뛰고 끝나지 못한 삭제는 partition을 지운다 (0929/05-01)
문제: OPFS journal의 `listCommittedObjects`·`listIncomplete`는 손상 행
하나에 목록 전체를 `CORRUPT_DATA`로 실패시킨다. 그래서
- 승인된 LOGOUT·ACCOUNT_DELETION purge가 그 partition의 정상 객체까지
하나도 지우지 못하고, 개인 바이트가 기기에 계속 남는다.
- journal DB는 authority 단위라 손상 행 하나가 모든 partition의
reconcile과 orphan GC를 멈춘다.
스스로 풀리지 않고, runbook은 journal 수동 삭제를 금지해 출구가 없다.
고른 방법 (리뷰의 (c)):
1. 두 목록은 손상 행을 건너뛰고 `corruptRows`로 센다. 행은 지우지
않는다. 꽉 찬 페이지는 다음 행 앞에서 멈추므로 한 행은 그 행에 닿은
페이지에서 한 번만 센다. reconcile은 `corruptTransactions`로 보고하고,
0이 아니면 `OBJECT_RECONCILE` `DEGRADED` / `CORRUPT_DATA`로 관측한다.
2. LOGOUT·ACCOUNT_DELETION purge가 손상 때문에 끝날 수 없으면(건너뛴
object 행, 손상으로 `CORRUPT_DATA`가 된 remove나 chunk sweep,
`STAGING_STATE_UNREADABLE`) partition을 통째로 지운다.
- 승인: 기존 `maintenanceReasonAllowed` + authority proof 요청·소비를
통과한 뒤에만 이 지점에 온다. IndexedDB의 database 전체 삭제
(0929 05-03)와 같은 조건이다.
- 파일: 새 worker 요청 `REMOVE_PARTITION`이 origin mutation lease를
쥔 채 `authorities/<a>/<ns>/<p>`를 지운다.
- 행: 새 journal 메서드 `removePartition`이 그 partition 키로 시작하는
object·journal·chunk reference 행과 budget 행을 키로 찾아 지운다.
손상 행도 지워진다. scope binding 행은 남긴다.
- 보고: `partitionDeleted: true`, `corruptObjects`,
`moreObjectsAvailable: false`. 파일을 먼저, 행을 나중에 지워서 중간에
실패해도 다시 부르면 이어서 끝난다.
버린 대안:
- 현상 유지: 손상이 있으면 삭제가 영구히 실패한다.
- 1만: reconcile·GC와 정상 객체 purge는 돌지만 손상 행의 바이트가 남는다.
- journal DB 전체 삭제: 같은 authority의 다른 partition까지 지운다.
기존 테스트 주석("손상 행이 목록 전체를 실패시키는 것이 의도")과
runbook(`browser-file-storage-recovery.md`)을 새 동작에 맞게 고쳤다.
위험·한계:
- 공개 계약 변경. `OpfsJournalPort`에 `removePartition`, 두 page 타입에
`corruptRows`가 필수로 생겼다. journal이나 worker gateway를 직접 구현한
쪽은 추가해야 한다(adapter가 생성 시점에 TypeError로 알린다).
report에는 `corruptTransactions`(필수)와 `corruptObjects`·
`partitionDeleted`(선택)가 생겼다.
- lease는 put의 BEGIN~FINISH만 막는다. 그 밖에 있던 다른 tab의 같은
partition put은 journal 행이 지워져 다음 journal 단계에서 실패할
것으로 보지만, 이 경합은 실행으로 확인하지 않았다.
- partition 삭제는 IndexedDB 전체 삭제처럼 시간 예산에 묶이지 않는다.
- reconcile GC의 `isChunkReferenced` 손상(리뷰 근거 ③)과 reconcile 쪽
`STAGING_STATE_UNREADABLE`(④)은 이번 결정 범위 밖이다. purge에서만
partition 삭제로 빠져나간다.
- offline-indexeddb 레시피 gzip: 36,889 → 37,327 B (한도 36,900, 427 B
초과). 예산은 올리지 않았다.
- 실제 브라우저(Playwright OPFS spec)에서는 돌리지 않았다.
검증:
- RED (수정 전): journal 4건 실패 — `listIncomplete`·
`listCommittedObjects`가 `CORRUPT_DATA`, `removePartition is not a
function`. adapter·worker 4건 실패 — LOGOUT·ACCOUNT_DELETION purge가
`CORRUPT_DATA`, reconcile이 `CORRUPT_DATA`, `REMOVE_PARTITION` 뒤에도
디렉터리가 남음. 승인 거절 테스트는 수정 전후 모두 통과(가드).
- GREEN: `node scripts/run-vitest.ts run tests/unit tests/recipes`
177 files 2,523건 통과, `tests/contract` 41건 통과.
`tsc` app·test·node·web-worker·service-worker·recipes 통과, 바꾼 파일
eslint 통과, `check-adapter-inventory` 통과.
- 미실행: `check:browser-file-storage-boundaries`(pnpm 필요),
`check:architecture`(pnpm 필요), Playwright OPFS spec.
Refs: docs/reviews/2026-09-29-maturity-review/05-adapters-storage-kernel.md 05-01
|
||
|
|
c4052f0f8e |
fix(storage): 여러 페이지를 다 지운 purge를 끝났다고 보고한다 (1101/13.6)
문제: OPFS `enforcePolicies`의 LOGOUT·ACCOUNT_DELETION purge가 journal 목록을 두 페이지 이상 읽으면, 객체를 모두 지워도 `moreObjectsAvailable: true`를 보고하고 chunk sweep을 하지 않는다. 페이지를 넘길 때 `moreObjectsAvailable = page.value.moreAvailable`가 true를 넣고, 마지막 페이지의 `||=`가 그 값을 그대로 둔다. 호출자는 다시 불러야 끝나고, 그 사이 chunk 바이트가 기기에 남는다. 고른 방법: 페이지 넘김 대입을 지운다. 대신 "다음 페이지를 읽기 전에 멈췄다"(객체 한도나 시간 예산 소진)는 루프 머리에서 true로 적는다. `while` 조건을 루프 안 첫 검사로 옮긴 것이다. 0929/05-02(`85d8b59`)의 "건너뛴 객체가 있으면 true" 규칙은 그대로다. 그 값을 지우는 대입이 없다(마지막 페이지는 `||=`, PRESSURE 대입은 sweep하지 않는 purge). 버린 대안: 건너뜀 표시를 별도 변수로 나누기. 페이지 넘김 true가 남는 한 마지막 페이지에서 여전히 섞여 고쳐지지 않는다. 위험·한계: - 동봉 IndexedDB journal은 페이지 한도를 "남은 객체 한도"로 받아 꽉 찬 페이지를 돌려주므로, 한 번의 호출에서 두 번째 페이지가 생기지 않는다. 결함은 port가 허용하는 짧은 페이지를 돌려주는 journal에서 드러난다. 테스트도 그 journal(페이지 1개씩)로 재현했다. - 동작 차이 하나: 앞선 시간 검사를 통과한 직후 첫 페이지를 읽기 전에 시간이 다 되면, 전에는 `moreObjectsAvailable: false`로 sweep을 시도했고 이제는 true로 보고하고 sweep하지 않는다. 아무 객체도 읽지 않았으니 이쪽이 사실에 맞다. - offline-indexeddb 레시피 gzip: 36,896 → 36,889 B (한도 36,900). 검증: - RED: 새 테스트 "finishes a purge that walked more than one journal page"가 수정 전 `moreObjectsAvailable: true`, `chunkSweep` 없음으로 실패했다. - GREEN: `node scripts/run-vitest.ts run tests/unit/opfs-worker-runtime.test.ts tests/unit/opfs-byte-store.test.ts tests/unit/indexeddb-opfs-journal.test.ts` 103건 통과. `tsc` app·test·web-worker 통과, 바꾼 파일 eslint 통과. Refs: docs/reviews/2026-11-01-maturity-review/README.md 13.6절 |
||
|
|
da1e128999 |
feat(bootstrap): 제품 capability·자격증명·설정 키를 제품 소유 파일로 받는다 (1101/09-02)
문제
제품이 http·telemetry·indexedDb 밖의 capability, 세션 밖 자격증명(BFF
쿠키 XSRF, Studio CSRF), 제품 런타임 설정 키를 넣으려면
runtime-adapters.ts, feature-adapter-contribution.ts, rest-profiles.ts,
release-artifacts.ts, runtime-config-schema.ts를 직접 고쳐야 한다. 이
파일들은 템플릿이 보안·계약 수정을 자주 넣는 곳이라, 동기화 때마다
fail-closed 코드를 손으로 병합한다(memento +61줄, tech-log +118줄).
고른 방법 (리뷰 09 4.2의 (B))
- FeaturePlatformCapabilities를 interface로 바꾼다. 제품은 이 repo의
FeatureIndexedDbRepositories·ApplicationFeatureInputs와 같은
declaration merging으로 capability를 더한다.
- 제품 소유 파일 둘을 빈 구현으로 둔다.
- src/bootstrap/product-composition.ts: 추가 capability와 "인증 프로필
id → 자격증명 제공자" 표. 계약 타입은 템플릿 소유
product-composition-contract.ts에 둔다.
- src/contracts/product-contracts.ts: 제품 인증 프로필과 런타임 설정
zod 조각. 프로필 레지스트리와 strict 설정 스키마는 contracts 층에
있고 빌드 스크립트도 읽는다. contracts는 bootstrap을 import할 수
없어서 파일을 하나로 합치지 못했다.
- 판단 순서는 조립 루트가 쥔다: scope fence → ANONYMOUS 프로필 → 제품
제공자 → 세션 → 응답 뒤 fence 재확인. 제공자가 throw하면 executor가
CREDENTIAL_OWNER_FAILED로 닫는다. 나가는 헤더는 여전히 프로필 허용
목록이 정한다.
- 제공자 계약은 기존 attachCredentials 시그니처를 그대로 쓴다.
- 제품 composition은 http capability가 생긴 뒤에 부른다. tech-log가
두었던 전방 참조 stub이 필요 없다.
- 제품에 host 전체를 넘기지 않고 readCookie(name)만 넘긴다. host를 객체에
담으면 browser-data-boundary/no-capability-alias가 막는다.
- http·telemetry는 spread 뒤에 둬서 제품이 바꿀 수 없다(타입에서도 뺀다).
제품 프로필 id나 설정 키가 템플릿 이름과 겹치면 모듈 로드 때 throw한다.
버린 대안
- (A) 현 상태: 템플릿 비용은 0이지만 제품마다 동기화 비용이 반복된다.
- (C) 기능 계약 기여가 인증 프로필과 제공자를 함께 가져온다: 인증
정책이 기능마다 흩어져 보안 리뷰 범위가 넓어진다.
- 제공자에 응답 관찰 훅 추가: tech-log의 401/403 토큰 폐기는 제품
capability가 http를 감싸서 표현된다(픽스처). 제공자 계약을 작게 둔다.
위험·한계
- memento의 x-xsrf-token은 닫힌 자격증명 헤더 목록(VD-23,
CREDENTIAL_HEADER_NAMES)에 없다. 그 이름을 쓰려면 여전히
rest-profiles.ts를 고치거나 백엔드가 x-csrf-token을 받아야 한다.
픽스처는 x-csrf-token으로 표현했다.
- 제품 설정 키의 FE-REG-ENV 행(src/contracts/env.ts)은 이 변경 밖이다.
그 행을 요구하는 검사는 없다.
- tech-log가 부트 전에 BFF 세션 owner를 설치하는 코드
(create-runtime-composition.ts)는 이 확장 지점 밖이다.
- 제공자 응답 뒤 fence 재확인은 executor가 같은 fence로 먼저 전송을
끊어서 조립 루트 경유 테스트로는 따로 보이지 않는다. 세션 경로와 같은
이중 방어로 둔다.
- V1 설정 문서도 제품 키를 받는다(없으면 기본값). V1은 한 릴리스 동안만
쓰는 리더다.
- 초기 JS gzip 203,818 → 204,178 B(+360, 예산 204,800).
검증
- RED: tests/unit/runtime-adapters-credential-order.test.ts 7행 중 제품
제공자를 기대하는 4행 실패(세션이 먼저 답해 UNAUTHENTICATED, owner가
먼저 답해 SUCCESS). fence·ANONYMOUS·세션 3행은 통과.
- GREEN: 같은 파일 7/7. tests/unit/product-composition-fixture.test.ts
9/9(가짜 제품 파일 두 개로 offsetUpload, runtime, BFF 쿠키 XSRF 읽기·
쓰기, Studio CSRF 발급·403 폐기, 제품 설정 키, 이름 충돌 거절). 09-01
tests/unit/runtime-adapters-auth-profile.test.ts 12/12.
- 회귀: tests/unit·contract·runtime-schema 182 files 2590 tests 통과.
integration·component 47 files 386 tests 통과(pnpm을 띄우는
security-followup-archive 제외). tsc app·test·node·recipes·web-worker·
service-worker 통과. 바꾼 파일 eslint 통과. check:registries PASS
(compatibility=breaking은 기존 route·storage 행). verify:documentation
PASS_SCOPED. check:adapter-inventory PASS. check:architecture는 pnpm 대신
exec 전용 shim으로 그래프·fixture PASS. 템플릿 런타임 설정 JSON
schema는 baseline과 같다.
|
||
|
|
7b34756355 |
fix(release): 공개 대상 승인이 예시·테스트용 예약 이름을 거절한다 (1101/13-02)
문제 staging·production 프로필은 `https://api.example.com/`, `https://telemetry.example.com/v1/events`를 싣고 텔레메트리를 켠다. 공개 대상 승인(FE-GATE-027)은 https와 비공개 호스트만 보므로 프로필을 고치지 않은 production 빌드가 `production ADMITTED`로 통과한다. 모든 API 호출이 실패하고 이벤트는 프로젝트가 소유하지 않은 도메인으로 간다. CI 계약은 immutable_build의 env를 APP_PROFILE·RELEASE_TARGET로 고정해 RUNTIME_*를 넘길 수 없는데, README 변수 표는 이를 적지 않고 운영 예시는 `api.example.com`을 그대로 쓴다. 고른 방법 - publicEndpointViolations에 예약 이름 거절을 더한다. RFC 2606·6761의 `example.com`·`example.net`·`example.org`와 그 하위, `.example`, `.invalid`, `.test`. 비공개 호스트와 겹치면 비공개 사유 하나만 낸다. - README 운영 예시의 URL을 `<your-api-origin>/` 같은 빈칸으로 바꾼다. - README 변수 표와 본문에 CI에서 endpoint를 바꾸는 방법은 프로필 파일을 커밋하는 것 하나라고 적는다. - 테스트 fixture의 공개 endpoint를 예약되지 않은 이름으로 바꾸고, 프로필을 고치지 않은 빌드는 두 위반, endpoint를 준 빌드는 승인되는 것을 고정한다. 버린 대안 - 프로필 기본값을 비워 스키마가 빌드를 막게 하기: 더 확실하지만 프로필이 예시로 읽히지 않고 네 프로필을 같이 바꿔야 한다. 리뷰 대안 비교에서 승인 규칙 한 곳이 더 작다고 봤다. - 리뷰 13-02 (3)의 괄호("13-01 배포 슬롯에 RUNTIME_* 허용 목록")는 하지 않았다. RUNTIME_*는 빌드 때 쓰이는 값이고, 슬롯은 승격 뒤 배포 job이라 거기서 넘겨도 이미 만든 후보에 닿지 않는다. 위험·한계 - 템플릿을 그대로 쓰는 프로젝트(이 repo 포함)가 APP_PROFILE=production으로 immutable_build를 돌리면 FE-GATE-027이 새로 실패한다(의도). - `*.test` 같은 이름을 실제 운영 endpoint로 쓰는 프로젝트는 없다고 본다. 검증 - RED: node scripts/run-vitest.ts run tests/unit/deployment-admission.test.ts 2 failed / 22 passed. "refuses names reserved for examples and tests" (`expected [] to deeply equal [...]`), "refuses a public build from the unedited profile on both endpoints"(`staging: expected [] to deeply equal [ 'API_BASE_URL', 'TELEMETRY_ENDPOINT' ]`) - GREEN: 같은 파일 24 passed. feature-override-diagnostics, documentation-readiness 포함 29 passed - 실험 E-A 재실행: APP_PROFILE=production VITE_BUILD_ID=rel-prod-a RELEASE_ID=rel-a 빌드 뒤 RELEASE_TARGET=production 승인 rc=1, API_BASE_URL·TELEMETRY_ENDPOINT 두 위반으로 거절 - tsc(app, test) 0, eslint 바뀐 파일 0, verify-documentation-readiness PASS_SCOPED Refs: docs/reviews/2026-11-01-maturity-review/13-build-release-supply-chain.md 13-02 |
||
|
|
6c5818faec |
refactor(contracts): bearer 인증 프로필을 EXTERNAL_BEARER로 바꾼다 (1101/16-03)
문제
유일한 bearer 인증 프로필 이름이 샘플 이름 REFERENCE_EXTERNAL_BEARER다.
세션이 필요한 제품 기능은 지운 샘플의 이름을 계속 쓰거나 템플릿 소유
파일에 프로필을 더해야 한다. 샘플 제거 드릴의 잔여 검사 정규식도 이
이름을 잡지 않아 샘플을 지운 제품에 그대로 남는다. 리뷰 (2) 오류
메시지는 abf3ce5가 했고 (1) 이름 변경이 남았다.
고른 방법 (2026-11-03 결정)
- 프로필 이름을 EXTERNAL_BEARER로 바꿨다. 참조 기능의 V2 operation 3개와
V3 descriptor 3개, external-session-adapter 주석, 테스트, VD-23 문서를
새 이름으로 옮겼다.
- 옛 이름은 한 릴리스 동안 REST_AUTH_PROFILES에 별칭 한 줄로 남기고
JSDoc @deprecated를 붙였다. 레지스트리는 키와 authProfileId가 같아야
하므로 별칭은 EXTERNAL_BEARER를 펼치고 id만 옛 이름으로 둔 객체다.
그래서 옛 이름을 적은 다운스트림 operation도 같은 transport·헤더로
해석된다.
- scripts/scale의 PLATFORM_TOKENS에서 이 이름을 뺐다. 참조 기능에 더는
"REFERENCE"가 든 프로필 이름이 없어 이름 바꾸기에서 보호할 것이 없다.
- 새 테스트 두 개: 별칭이 id만 빼고 EXTERNAL_BEARER와 같게 설치되는지,
src에 옛 이름이 별칭 한 줄 외에 없는지(완료 기준).
버린 대안
- 별칭 없이 바로 바꾸기: 옛 이름을 쓰는 다운스트림 기능이 모듈 로드에서
바로 실패한다. 공개 이름을 깨는 변경은 BREAKING 결정이 있을 때만 한다.
- 조회 시점의 이름 매핑(alias 표): resolve·executor·composition 세 곳이
매핑을 알아야 한다. 프로필 항목 하나가 더 작다.
위험·한계
- 설치된 프로필이 셋이 된다. 같은 설정이 두 id로 있을 뿐 권한이 넓어지지
않는다. 별칭은 다음 minor에서 지우고 CHANGELOG [계약] 행을 남긴다.
그때 "src only on the alias line" 테스트의 기대값을 빈 목록으로 바꾼다.
- 다운스트림 문자열 id("REFERENCE_EXTERNAL_BEARER")에는 @deprecated 표시가
보이지 않는다. CHANGELOG로 알린다.
- FE-REG-API 행 3개의 authProfileId가 바뀐다. breakingFields가 아니라
behavior-change이므로 증거 없이 게이트를 통과한다. 기준선 재승인은 이번
작업 묶음 끝에서 한 번에 한다.
- 초기 JS gzip(초기 청크 파일별 gzip 합) 203,818 → 203,840 B(+22 B). 별칭
항목이 rest-profiles가 있는 초기 청크에 실린다. 참조 기능 계약은 lazy
청크라 초기 크기에 영향이 없다.
검증
- RED(수정 전): rest-profile-contract.test.ts 새 사례 2건 실패("expected
undefined to match object { transport: 'BEARER_HEADER', …(1) }",
"expected [ …(9) ] to deeply equal [ Array(1) ]").
- GREEN: 같은 파일 10/10 통과. check-registries "11 registries PASS"
(FE-REG-API authProfileId 3건 behavior-change).
- 회귀: tests/{unit,integration,features,contract,runtime-schema}
207 파일 2,366건 통과(pnpm·corepack을 띄우는 6개 제외:
http-scenario-evidence, ci-workflow-generation, lab-performance,
fixture-node-modules, deployment-admission, security-followup-archive).
tsc app·test·node rc=0, 바꾼 파일 eslint rc=0. vite build 성공.
- 미실행: check:architecture, test:sample-removal(pnpm 필요), e2e.
Refs: docs/reviews/2026-11-01-maturity-review/16-structure-patterns.md
|
||
|
|
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을 믿는 화면은 "다시 시도"를 띄우고, 다시 부르면 파일
전체를 재해시한 뒤 같은 거절을 받는다. 지난 수정(
|
||
|
|
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건을 고친 뒤 드릴 전체는 다시 돌리지 않았다. |
||
|
|
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
|
||
|
|
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 |
||
|
|
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"로 실패(수정 전,
|
||
|
|
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 |
||
|
|
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절 |
||
|
|
ffb6782b0c |
fix(query): 무효화 topic이 닿지 않는 조회 namespace를 진단으로 알린다 (03-01)
문제
QueryDefinition의 namespace는 아무 문자열, namespaceVersion은 아무
숫자다. bindQuery는 이 둘로 쿼리 키를 만들 뿐 무효화 registry에 있는지
보지 않는다. 저장 뒤 무효화는 topic -> 등록 namespace 접두사로만 가므로,
namespace 오타나 version만 올린 조회, registry에 빠진 namespace의 조회는
저장 뒤에도 갱신되지 않는다. 오류도 진단도 없다(E7). 문서는 "query
namespace는 registry reference"라고 적지만(client-cache-and-storage.md),
참조 기능도 registry 객체에서 두 필드를 꺼내 문자열로 다시 넘긴다.
고른 방법
- 런타임 검사(리뷰 ②): cache coordinator가 QueryCache의 "added"
이벤트를 구독한다. bindQuery 키 접두사(["query", 2, id, version])를
읽어 registry 인덱스(topicsForNamespace)에 없으면 namespace당 한 번
cache.operation.failed(operation: unregistered-query-namespace) 진단을
남긴다. registry와 TanStack 키의 연결은 원래 이 coordinator가 갖고
있으므로(무효화 접두사) 새 결합을 만들지 않는다. dispose 때 구독을 푼다.
- 정적 조회 예외: QueryDefinition에 선택 필드 invalidation: "NONE"을
더한다. bindQuery가 BoundQuery로 옮기고, useApplicationQuery가 공유 상수
QUERY_WITHOUT_INVALIDATION_META를 TanStack meta로 넣고, coordinator가 같은
상수로 읽는다. 상수는 query-keys.ts에 둔다. server-state.ts에 두면
coordinator(초기 청크)가 그 모듈 전체를 끌어와 초기 JS에 server-state
청크가 하나 생긴다(측정: +1,407 B gzip, 파일 16 -> 17).
- 타입(리뷰 ①, 추가만): QueryDefinition.namespace가 registry의
QueryNamespaceIdentity 객체를 그대로 받는다. 참조 기능의 두 조회는 등록
객체를 넘긴다. 문자열 id + namespaceVersion 쌍도 계속 받는다.
버린 대안
- 문자열 쌍을 없애고 객체만 받기(리뷰 ①의 원안): 공개 타입 시그니처를
깨서 다운스트림 조회 정의를 모두 고쳐야 한다. 이번 범위에서는 공개
포트를 추가만 한다. 문자열 쌍의 오타는 위 진단이 잡는다.
- useApplicationQuery에서 검사하고 QueryInvalidationCoordinator에 메서드
추가: 공개 인터페이스가 늘고, 다른 경로로 cache에 들어오는 bound 키는
못 본다.
- 개발 빌드에서 throw(리뷰 ②): QueryCache 구독 콜백에서 throw하면 TanStack
알림 경로가 깨진다. 진단 1건으로 완료 기준("타입 오류 또는 진단 1건")을
채운다.
- 진단에 namespace id 싣기: id는 80바이트까지 허용돼 진단 값 문법(64자)을
넘으면 기록 전체가 버려진다. id 없이 operation만 남겼다.
위험·한계
- 런타임 검사라 그 조회가 처음 cache에 들어갈 때(화면을 열 때) 드러난다.
- "등록은 했지만 edge가 없음"은 registry 인덱스가 시작 때 orphan
namespace로 거절하므로 여기까지 오지 않는다.
- 진단에서 어느 namespace인지는 알 수 없다. 개수만 보인다.
- useApplicationQuery -> meta 연결은 타입 검사로만 확인했다. 그 경로의
런타임 테스트는 없다.
- 공개 타입은 추가만 했다(QueryDefinition namespace 유니언, invalidation,
BoundQuery.invalidation, 상수 1개).
검증
- RED(수정 전): tests/unit/tanstack-cache-coordinator.test.ts "reports a
bound query whose namespace no registered topic reaches (03-01)" 실패.
"expected vi.fn() to be called 2 times, but got 0 times".
- GREEN: 같은 파일 10/10, tests/features/reference-feature 포함 17 files /
89 tests 통과. 변이 M20(참조 목록 조회 namespace를 문자열 오타 쌍으로)을
넣으면 reference-page.test.tsx가 실패하는 것을 확인하고 원복했다.
- 회귀: run-vitest tests/unit tests/integration tests/component
tests/features tests/contract tests/runtime-schema(pnpm을 언급하는 파일
12개 제외) 228 files 중 227 통과, 2369/2370. 실패 1건은
provider-guardian-transaction의 ENOSPC(inotify watcher 한도, 이 머신의
다른 실행 때문)로 이 변경과 무관하다.
tsc app/test/node rc=0. 바꾼 파일 eslint rc=0.
check-adapter-inventory PASS. verify-documentation-readiness PASS_SCOPED.
- 번들: build-frontend로 빌드해 check-bundle과 같은 분류로 초기 JS를
gzipSync로 쟀다.
|
||
|
|
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 |
||
|
|
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
|
||
|
|
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 |