2d5d41f85dd5ad1bf90ff856590538173a0f6dfa
323
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
2d5d41f85d |
fix(forms): 필드 오류가 아닌 저장 실패 뒤 키보드 포커스를 실패 상태로 옮긴다 (1103/08-02)
문제 참조 폼 페이지는 저장 중과 결과 불명 동안 저장 버튼에 disabled를 준다. 포커스가 있던 버튼이 꺼지면 브라우저가 포커스를 body로 내려놓는다. 폼은 필드 오류일 때만 포커스를 옮겼으므로, 키보드로 저장했다가 결과 불명(500)이나 429를 받으면 세 엔진 모두 포커스가 body로 떨어졌다. 복구 버튼은 폼 위 feedback 자리에 있어 셸 머리말부터 다시 지나야 닿았다. 고른 방법 - useAppForm이 feedbackId를 내고, 필드 오류·성공이 아닌 결과(결과 불명, 재인증, 권한 없음, 다시 시도, 사용 불가, 충돌)로 끝나면 렌더 뒤 그 요소에 포커스를 준다. FormPage(StandardPage)는 feedbackId를 받으면 feedback 자리를 id + tabIndex=-1인 포커스 대상으로 만든다. 페이지마다 포커스 코드를 복사하지 않게 하려고 hook과 템플릿에 두었다. - 참조 폼의 저장 버튼은 저장 중에 disabled 대신 Button의 pending(aria-busy)을 쓴다. 중복 제출은 지금처럼 폼(submitForm)과 onSubmit 가드가 막는다. 결과 불명 동안에는 여전히 꺼진다(08-01 범위). 그때는 위의 포커스 이동이 받는다. - 첫 행동 버튼 대신 feedback 자리 전체를 포커스한 이유: 실패 종류마다 버튼 구성이 다르고, Tab 한 번에 첫 복구 버튼에 닿는다. 매뉴얼 02 6절 FormPage에 feedbackId와 pending을 적었다. 위험·한계 - 스크린 리더가 포커스된 feedback 자리를 어떻게 읽는지는 확인하지 않았다. - 파생 폼 페이지는 feedbackId를 넘겨야 이 동작을 얻는다. - "deduplicates create" 테스트의 저장 중 단언을 disabled에서 aria-busy와 포커스 유지로 바꿨다. 한 번만 호출되는 단언은 그대로다. 검증 - RED: reference-page.test.tsx 새 2행(결과 불명, 429)이 수정 전 실패. e2e reference-save.spec.ts 새 2건이 수정 전 소스에서 chromium·firefox·webkit 6건 모두 실패(feedback 자리 focused 아님). - 수정 후 reference-save·reference-form e2e 3엔진 45건 통과(heavy lock, CHOKIDAR_USEPOLLING=1). tests/component·tests/features 60 files / 368 tests 통과. check:types, eslint, check:design-system, check:i18n, verify:documentation 통과. Refs: docs/reviews/2026-11-03-maturity-review/08-presentation.md 08-02 |
||
|
|
2963c6f42c |
fix(features): 선택 런타임(SW 등) 선택을 제품 소유 파일로 옮긴다 (1103/09-05)
문제 Service Worker를 켜는 유일한 방법은 src/features/installed-runtime-capabilities.ts의 SERVICE_WORKER 상수를 바꾸는 것이었다. 그 파일에는 "Product-owned." 표시가 없고, 매뉴얼 03 D절은 src/features/installed-*.ts를 고치지 말라고 한다. 매뉴얼대로 하면 SW를 켤 수 없고, 켜면 동기화마다 템플릿 파일을 손으로 병합한다. 템플릿 상태 설명과 제품 선택 상수가 한 블록에 섞여 있었다(1101/09-05). 고른 방법 리뷰의 최소 방향을 따른다. - 선택 상수 넷(REALTIME, WEB_WORKERS, SERVICE_WORKER, OFFLINE_COMMANDS)을 제품 소유 src/features/product-capabilities.ts의 PRODUCT_RUNTIME_CAPABILITY_SELECTION으로 옮긴다. 09-02에서 만든 같은 새 제품 소유 파일이다. product-contracts.ts에 넣지 않은 이유: 계약 층(src/contracts)이 아니라 기능 카탈로그 옆의 선택이고, 템플릿은 복사 뒤 기존 제품 소유 파일에 칸을 더하지 않는다. - installed-runtime-capabilities.ts는 템플릿 소유로 남고 그 선택을 검사 (validateRealtimeContributions, validateWebWorkerContributions)하고 투영만 한다. §3.5 설명과 템플릿 상태 설명은 여기에 남는다. - 매뉴얼 03 C절에 "SW 켜기"를 넣었다. 조립 거절 메시지, e2e SW 빌드 도우미의 편집 대상(premise 1), 레시피·운영 문서, dependency-cruiser 주석의 경로를 새 파일로 바꿨다. - 09-02 typecheck 테스트는 이제 출하된 product-capabilities.ts에 타입만 채우고 (선택은 유지), 복사 목록은 REMOVAL_FIXTURE_COPY_TARGETS 하나를 쓴다. 위험·한계 - 리뷰가 함께 제안한 composeProduct의 SW 연결 칸(blockers, observe)은 만들지 않았다. 그 연결은 여전히 템플릿 파일 create-runtime-composition.ts를 고쳐야 한다. 매뉴얼 "SW 켜기"에 적었다. - 템플릿 안의 선택을 이미 바꾼 다운스트림은 값을 새 파일로 옮겨야 한다. 검증 - RED: tests/unit/product-runtime-capability-selection.test.ts 3건(선택이 제품 소유 파일에만 있음, 제품 SW 선택 투영, 잘못된 선택은 여전히 검사)이 수정 전 실패. - 그 테스트, service-worker-build-output, optional-runtime-host, runtime-composition-service-worker-telemetry, product-features, product-extension-typecheck, runtime-adapters 통과. - check:types, check:architecture, eslint, verify:documentation PASS_SCOPED. Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-05 |
||
|
|
245f428123 |
fix(features): 제품 capability 타입과 기본값 설정 키가 타입 검사 3종을 통과한다 (1103/09-02)
문제 제품 확장 지점이 실행 경로에서는 동작했지만 타입 검사 경로에서 막혔다. (a) 문서대로 product-composition.ts에서 FeaturePlatformCapabilities를 보강하면 check:types:node가 실패했다. scripts 프로그램은 기능 코드를 끌어오지만 product-composition.ts는 끌어오지 않아 보강이 보이지 않았고, 오류는 기능 파일을 가리켰다. (b) 기본값 있는 제품 설정 키(.default()) 하나가 RuntimeConfig를 리터럴로 쓰는 템플릿 테스트 7개 파일의 타입을 깼다. 픽스처는 vi.mock이라 이 경로를 지나지 않았다. 고른 방법 - 제품 소유 빈 파일 src/features/product-capabilities.ts를 두고 FeaturePlatformCapabilities가 그 ProductFeaturePlatformCapabilities를 extends한다. feature-adapter-contribution.ts가 import하므로 기능을 보는 모든 프로그램에 들어간다. 문서만 "기능 파일 안에서 보강"으로 고치는 최소안은 capability 하나를 여러 기능이 쓸 때 보강 위치가 갈려 버렸다. 기존 제품 소유 파일에 칸을 더하지 않고 새 파일로 둔 이유: 템플릿은 복사 뒤 제품 소유 파일을 고치지 않으므로, 새 파일이어야 동기화 때 충돌 없이 들어간다. - tests/helpers/runtime-config.ts의 testRuntimeConfig: 템플릿 키는 테스트가 쓰고, 제품 키는 실제 스키마(validateRuntimeConfig)로 기본값을 채운다. 템플릿 테스트 6개 파일이 이것을 쓰고, release-coherence는 문서 타입을 z.input으로 바꿨다. 제품 키를 모두 Partial로 하는 대안은 기본값 키에도 undefined 처리를 강요해 버렸다. - tests/unit/product-extension-typecheck.test.ts: 복사본에 제품 소유 파일 세 개와 기능 하나를 실제 파일로 채우고 tsc app·node·test를 돈다. - 문서: starter-experience 표, 매뉴얼 01·03·patterns·create-feature, frontend-application-foundation, 계약 주석. 위험·한계 - 기본값 없는 필수 제품 키는 여전히 템플릿 테스트에서 실패한다(이제 타입이 아니라 helper가 이유를 적고 throw). 문서에 ".default() 또는 .optional()"을 적었다. - product-composition.ts 안에서 이미 보강한 다운스트림은 보강을 새 파일로 옮겨야 node 검사가 통과한다. 검증 - RED: 새 typecheck 테스트가 수정 전 app·node(보강 미연결)와 test(템플릿 테스트 8건, E-PROD와 같은 위치)에서 실패. - 수정 후 그 테스트와 영향받는 9개 테스트 파일 → 10 files / 83 tests 통과. - check:types(tsc app·node·test), check:architecture, eslint, verify:documentation PASS_SCOPED. Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-02 |
||
|
|
e7d63586b6 |
fix(features): 기능 어댑터 기여에 needs에 적은 capability만 넘긴다 (1103/09-08)
문제 조립 루트 주석과 생성 뼈대 주석은 "기능은 needs에 적은 capability만 받는다"고 했지만, invokeContribution은 context 전체를 넘겼다. needs: ["telemetry"] 기여가 ["telemetry","http"]를 받았다(E6). 제품 capability도 모든 기능에 갔다. 타입이 막고 있어 cast가 있어야 생기지만, 그러면 needs가 실제 의존을 다 말하지 않는다. 고른 방법 invokeContribution이 needs의 키만 골라 새 frozen 객체로 넘긴다. 주석을 "타입만 그렇다"로 고치는 대안은 생성 뼈대 주석(scripts/create-feature.ts)까지 모든 기능에 퍼진 설명을 바꿔야 해서 버렸다. 이제 두 주석이 실행과 맞는다. 위험·한계 needs에 적지 않은 capability를 cast로 쓰던 다운스트림 기능은 그 값이 undefined가 된다. repo 안에는 그런 기능이 없다. 검증 - RED: feature-adapter-composition.test.ts에 E6 행(받은 키가 ["telemetry"])을 더했고 수정 전 실패. - tests/contract/reusable-capability, tests/features, runtime-adapters 계열, product-composition-fixture → 27 files / 178 tests 통과. - check:types, eslint 통과. Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-08 |
||
|
|
f98d0c3663 |
fix(contracts): 계약 조립 오류 메시지에 원인을 싣는다 (1103/09-07)
문제
ContractContributionError의 message는 "Installed contract contribution is not
composable" 하나였고 원인은 reason 속성에만 있었다. check:registries는
message 첫 줄만 적으므로, 제품 인증 프로필 id를 잘못 적으면 게이트 출력에
operation id도 프로필 id도 없었다("missing registry source …: Installed
contract contribution is not composable"). 매뉴얼 02 5절과 starter-experience
정본 표는 V2 해석기와 함께 지워진 "REST security profiles are incoherent …"
메시지를 약속했다.
고른 방법
message에 reason을 붙인다: "Installed contract contribution is not composable:
<reason>". 메시지를 읽는 모든 곳(check:registries, vitest, 부팅 오류)이 원인을
보게 된다. check-registries.ts만 reason을 적게 하는 대안은 다른 출력 경로를
그대로 두어 버렸다. reason은 기능·operation·프로필 id 같은 개발자 식별자뿐이다.
문서 세 곳(매뉴얼 02 5절, errors.md, starter-experience 표)을 실제 출력으로
고쳤고, V3 descriptor에 없는 auth 칸 조합 문장을 지웠다.
위험·한계
- check:registries가 같은 실패 뒤에 적는 연쇄 줄(FE-REG-API is not an object
registry, breaking change missing evidence … removed)은 그대로다(14-06 범위).
- message 문자열 전체를 비교하는 다운스트림 테스트가 있으면 바뀐다.
검증
- RED: second-api-feature-registries.test.ts에 authProfileId를 SECOND_UNKNOWN
으로 바꾼 행을 더했고, 수정 전 stderr에 원인이 없어 실패.
- 같은 파일, external-contract-runtime, http-execution-v3-auth-profile,
reference-fixture-provenance, tests/platform → 33 files / 255 tests 통과.
- eslint, tsc(test), verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-07
|
||
|
|
bf9df9a5c2 |
docs(features): 기능 실행부 설명 네 곳을 V2 삭제 뒤 모양으로 고친다 (1103/09-10)
문제
FeatureRuntime은 featureId·schemas·adapters·contractContributions인데, 네 곳이
지워진 V2 모양을 적었다. feature-module.ts 머리 주석("API contracts with their
runtime schemas and mappers"), installed-feature-contracts.ts("The V2 API
registries"), frontend-application-foundation.md("composes the V2 API
registries"), starter-experience.md 기능 추가 2단계("the API contract
(operations, schema metadata, runtime schemas, mappers)"). 기능 작성자가 없는
칸을 찾게 된다. 07-05(starter-experience 같은 문장)를 함께 닫는다.
고른 방법
네 문장을 지금 모양으로 고친다: schemas는 FE-REG-SCHEMA 행, 어댑터 기여는
application input, 계약 기여는 HTTP operation이고 FE-REG-API 행은 거기서
투영한다(installed-feature-runtime-registries.ts와 같다).
위험·한계
verify:documentation은 문장 내용을 보지 않으므로 다시 낡아도 게이트가 모른다.
검증
- git grep "V2 API registr|runtime schemas, mappers|runtime schemas and
mappers" -- src docs/architecture → 0건.
- verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-10
Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-05
|
||
|
|
9edc8307b0 |
fix(features)!: 기능이 아닌 폴더 표시를 NOT_A_FEATURE로 바꾸고 선언과 함께 두면 실패한다 (1103/09-09)
문제 src/features/<dir>/NOT_INSTALLED 표시는 "기능이 아닌 샘플 폴더"라는 뜻인데, 같은 단어가 런타임 상태 "선언됐지만 빌드·FEATURE_OVERRIDES가 뺀 기능"으로도 쓰였다(product-features.ts). 생성기는 feature-module.ts를 못 읽을 때만 표시를 찾았으므로, 샘플을 졸업시키며 표시를 지우지 않으면 표시가 "설치 안 됨"이라고 말하는 채로 조용히 설치됐다. 고른 방법 - 표시 이름을 NOT_A_FEATURE로 바꾼다(local-draft-feature 파일 이름 변경). 런타임 상태 NOT_INSTALLED는 그대로 둔다. - 생성기가 표시와 feature-module.ts가 함께 있으면 둘 중 무엇을 지울지 적고 실패한다. - 옛 이름 표시는 받지 않는다. 받으면 같은 다의가 남는다. 옛 표시만 있는 폴더는 "has no feature-module.ts; … mark the directory with NOT_A_FEATURE"로 실패해 새 이름을 알려 준다. README 상태 표, starter-experience, 매뉴얼 errors·patterns 표를 맞췄다. 위험·한계 다운스트림이 자기 폴더에 NOT_INSTALLED 표시를 두었다면 생성 단계가 실패한다. 파일 이름만 바꾸면 된다. 검증 - RED: 생성기 테스트 3건(새 이름 허용, 옛 이름 거절, 동시 존재 거절)이 수정 전 실패. - generate-product-feature-index.test.ts 17건 통과. generate:feature-index 통과. verify:documentation PASS_SCOPED. eslint, tsc(node·test) 통과. BREAKING CHANGE: src/features/<dir>/NOT_INSTALLED 표시 파일은 더 이상 인식되지 않는다. 같은 자리에 NOT_A_FEATURE라는 이름으로 옮긴다. Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-09 |
||
|
|
851fdedbcd |
fix(apps): 대소문자·끝 슬래시만 다른 기능 라우트도 같은 경로로 거절한다 (1103/08-04)
문제 같은 모양 검사가 파라미터 이름만 지운 문자열로 비교했다. React Router는 대소문자를 무시하고 끝 슬래시를 같은 경로로 본다. 그래서 /shop/items/:itemId와 /shop/Items/:id, /shop/items와 /shop/items/가 조립을 통과했고 라우터는 그중 하나만 그렸다. 메뉴·레지스트리에는 둘 다 나왔다. 고른 방법 모양 키를 만들 때 소문자로 바꾸고 끝 슬래시를 지운다. 라우트 경로 문법을 소문자·끝 슬래시 없음으로 제한하는 검사는 기존 라우트에 새 규칙을 거는 것이라 버렸다. 위험·한계 라우터가 caseSensitive를 켜면 이 검사가 과하게 거절한다. src에 caseSensitive 사용은 없다. 검증 - RED: context-route-roots.test.ts의 새 두 행이 수정 전 실패. - tests/architecture, router, context-layouts → 9 files / 64 tests 통과. /a/new와 /a/:id 허용 행은 그대로 통과. eslint 통과. Refs: docs/reviews/2026-11-03-maturity-review/08-presentation.md 08-04 |
||
|
|
4282a541d0 |
fix(forms): 필드 code 문구를 표의 자기 키로만 찾는다 (1103/08-03)
문제
validationMessage가 VALIDATION_COPY[code]로 찾았다. Object.freeze({...})는
Object.prototype을 물려받으므로 constructor·toString·hasOwnProperty·
__proto__는 undefined가 아니라 함수·객체가 되고 ?? 대체가 걸리지 않았다.
그 값이 문구 키로 넘어가 "요청한 문구를 표시할 수 없습니다."가 나왔다.
고른 방법
같은 영역의 다른 표(route-codecs.ts, backend-envelope.ts)처럼
Object.hasOwn으로 자기 키만 본다. 표를 Object.create(null)로 바꾸는 대안은
타입 선언과 다른 표의 관용이 갈려 버렸다.
위험·한계
짝 백엔드는 대문자 code만 보내므로 짝 구성의 화면 결과는 바뀌지 않는다.
검증
- RED: 내장 이름 4개 행이 수정 전 실패, SOME_FUTURE_CODE 행은 통과.
- form-foundation.test.tsx 28건 통과. eslint, tsc(app) 통과.
Refs: docs/reviews/2026-11-03-maturity-review/08-presentation.md 08-03
|
||
|
|
0aada28b91 |
fix(bootstrap): 401을 그 요청의 자격 증명을 낸 쪽에만 알린다 (1103/09-01)
문제
조립 루트는 응답이 있는 UNAUTHENTICATED면 프로필을 보지 않고
authSession.onUnauthenticated()를 불렀다. ANONYMOUS 요청은 세션을 묻지 않고
헤더 없이 나가는데도, 그 401이 로그인한 사용자를 로그아웃시키고 scope fence가
서버 상태 캐시를 모두 비웠다. 제품 credentialProviders가 자격 증명을 낸
요청의 401도 템플릿 세션을 로그아웃시켰다.
고른 방법
attachCredentials와 같은 순서로 401의 주인을 가른다(reportServerUnauthenticated).
- ANONYMOUS 프로필: 아무에게도 알리지 않는다.
- 제품 provider 프로필: 세션은 그대로 두고, ProductComposition의 선택 hook
onCredentialRejected({operationId, authProfileId})를 부른다. BFF 제품은
거기서 자기 owner에게 알린다. hook의 throw는 결과를 바꾸지 않는다.
- 나머지(템플릿 세션이 낸 자격 증명): 지금처럼 onUnauthenticated().
버린 대안: ANONYMOUS만 빼기(2줄)는 provider 경로의 과잉 로그아웃이 남는다.
owner가 401을 직접 판단하게 하면 owner 계약이 바뀌고 모든 owner가 판단
로직을 쓴다.
위험·한계
- 제품 provider가 템플릿 세션과 같은 세션의 자격 증명을 내는 경우, 제품이
hook을 쓰지 않으면 그 401은 세션을 바꾸지 않는다. 계약 주석과 매뉴얼 02
5절에 적었다.
- 401 도착과 계정 전환이 겹치는 경쟁은 여전히 확인하지 않았다.
검증
- RED: 새 테스트 3건(ANONYMOUS 401 demo·external, provider 401)이 수정 전
실패했다. bearer 대조군은 수정 전후 모두 통과.
- node scripts/run-vitest.ts run runtime-adapters-{auth-profile,credential-order},
runtime-adapters, product-composition-fixture, reference-runtime-composition
→ 5 files / 62 tests 통과. check:types 통과. eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-01
|
||
|
|
e40684b4e1 |
chore(review): 리뷰 기준으로 두 작업 브랜치를 합친다
문제 2026-11-03 전체 리뷰는 출시될 코드 전체를 봐야 한다. 오늘 고친 것이 두 브랜치에 나뉘어 있다. claude/happy-easley-233d07(Envelope, V2 삭제, 거절 표, CSRF·KEYED 재전송)과 fix/ui-design-audit-2026-11-01(남은 위험 16커밋)이다. 사용자가 두 브랜치를 합친 상태를 리뷰 기준으로 골랐다. 고른 방법 새 브랜치 review/2026-11-03-merged에서 두 브랜치를 합쳤다. 원래 두 브랜치는 건드리지 않았다. 충돌은 계약 문서 4.1·6절 두 곳이었다. - 4.1: 백엔드 기준 SHA(5786126c) 문장은 fix 쪽을, Envelope를 읽는 곳은 V2가 없어진 이쪽을 택했다. - 6절: 거절 판정 위치는 backend-envelope.ts 표다. - 6.1 "프론트 판정과 표가 다른 곳"에서 3261208이 고친 두 항목을 지웠다. 위험·한계 - 이 합치기는 리뷰 기준을 고정하려는 것이다. 어느 브랜치를 main에 합칠지는 사용자가 정한다. 검증 - check:types 통과. 나머지 게이트는 리뷰 기록(9절)에 적는다. |
||
|
|
c05f41a63e |
fix(http): KEYED 명령이 백엔드의 실행 전 거절에 같은 키로 다시 보낸다
문제 V2 클라이언트는 보낸 KEYED 요청이 503·408·425·502·504·network·timeout으로 끝나면 같은 키로 자동 재시도했다. 048f490으로 그 동작이 없어졌다. 설계 정본 (2026-07-30 closed deep design 8.3)은 KEYED 자동 재시도를 "known response status가 retry 가능하다고 package가 명시한 경우만" 허용하고, 응답 없는 network·timeout 뒤에는 금지한다. V2는 응답 없는 실패 뒤에도 보내 정본과 어긋났고, V3는 응답이 재시도를 허락해도 보내지 않아 정본보다 좁았다. 짝 백엔드는 503 IDEMPOTENCY_UNAVAILABLE을 "작업 실행 전에 거부됐다. 같은 키로 나중에 다시 보낸다"로 정한다(http-contract.md §2). 고른 방법 - backend-envelope.ts의 invitesKeyedResend: 503 + IDEMPOTENCY_UNAVAILABLE. - Envelope operation의 실패 해석에서 KEYED 명령이 그 답을 받으면 AdmissionOutcome에 keyedResend를 싣는다. 재시도 루프는 그때 retryBudget· MAX_RETRY_ATTEMPTS·상한 2 안에서 같은 frozen 요청(같은 Idempotency-Key)을 다시 보낸다. certainty는 MAYBE_APPLIED로 두어, 다 쓰면 결과 불명으로 끝나고 키를 지킨다. 버린 대안 - V2처럼 KEYED의 모든 재시도 가능 status·network 실패에서 재시도: 정본 8.3이 응답 없는 실패 뒤 재시도를 금지한다. - 409 IDEMPOTENT_IN_FLIGHT도 자동 재시도: 처리 중 요청은 47fec5c의 사용자 재전송(Retry-After 대기)이 이미 같은 키로 다룬다. V2도 409는 자동으로 다시 보내지 않았다. 위험·한계 - retryBudget이 0인 명령(참조 기능 CREATE)은 그대로 다시 보내지 않는다. - Envelope가 아닌 operation은 백엔드 code를 몰라 이 재전송이 없다. 검증 - RED: tests/integration/http-execution-v3-envelope.test.ts "KEYED resend on the backend's pre-execution refusal" 3건 중 2건 실패(한 번만 보내고 PROBLEM). 다른 503(REQUEST_TIMEOUT)을 다시 보내지 않는 행은 처음부터 통과. - GREEN: 같은 파일 35건 통과. 두 번 보낸 키가 같다. - check:types, lint, check:architecture, test:unit 2,568, test:integration 117, test:component 245, tests/features 99 통과. Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.7 |
||
|
|
365d8c3c02 |
fix(contracts): 쿠키 인증 쓰기는 CSRF 헤더를 요구하는 프로필만 조립한다
문제 브라우저는 쿠키를 어느 사이트의 요청에든 붙이므로, 쿠키로 인증하는 쓰기 요청은 페이지만 넣을 수 있는 헤더(CSRF 토큰)가 있어야 서버가 진짜 요청을 가른다. V2 클라이언트는 resolveRestSecurityProfiles로 "쿠키 프로필 + GET·HEAD 밖 method면 HEADER CSRF 프로필"을 강제했다. 048f490·12f3bb7이 V2를 지운 뒤 V3에는 이 검사가 없다. V3 프로필 설치 규칙은 SAME_ORIGIN_COOKIE에 쿠키 전송과 bearer 금지만 요구한다. 그래서 제품이 CSRF 헤더 없는 쿠키 프로필을 POST에 붙여도 조립이 통과한다. 고른 방법 assertHttpContract가 operation의 auth profile을 설치된 레지스트리에서 찾아, 쓰기(GET·HEAD 밖)인데 SAME_ORIGIN_COOKIE이고 requiredCredentialHeaders에 x-csrf-token·x-xsrf-token이 없으면 operation·method·프로필 이름을 담아 거절한다. 읽기 쿠키 프로필은 CSRF 없이 그대로 된다(tech-log·memento 예시와 같다). 버린 대안 - 프로필 설치 때 모든 쿠키 프로필에 CSRF 요구: 읽기 전용 쿠키 프로필 (MEMENTO_BFF_READ 등)까지 막는다. method는 operation에만 있다. - 요청 때(attachCredentials) 검사: 조립 때 잡을 수 있는 설정 실수를 사용자 요청 시점까지 미룬다. 위험·한계 - 이미 CSRF 없는 쿠키 쓰기 프로필을 쓰는 제품은 조립이 실패한다. 의도한 실패다(CHANGELOG [보안]). - 헤더 값이 올바른 CSRF 토큰인지는 서버만 안다. 프론트는 헤더가 반드시 실리는지만 보장한다(requiredCredentialHeaders가 없으면 fetch 0회). 검증 - RED: tests/unit/rest-profile-contract.test.ts "refuses a write whose cookie profile requires no CSRF header" 실패(조립이 통과). - GREEN: 같은 파일 7건 통과. CSRF를 요구하는 쓰기와 CSRF 없는 쿠키 읽기는 조립된다. - check:types, lint, check:architecture, check:registries, test:unit 2,568, test:integration 117, test:component 245 통과. Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.7 |
||
|
|
12f3bb7862 |
refactor(contracts)!: V2 API 행을 지우고 FE-REG-API를 HTTP descriptor에서 뽑는다
문제 기능 하나가 같은 HTTP API를 두 번 적는다. *-api-contract.ts의 V2 행 (defineRestOperation)은 check:registries(FE-REG-API)가 검사하는 선언이고, contract contribution의 V3 descriptor가 실제로 실행된다. 둘이 어긋나지 않게 http-operation-v2-v3-parity 테스트를 따로 둔다. 048f490으로 V2 클라이언트가 없어져 V2 행을 읽는 실행 코드는 없고, 검사만 남은 두 번째 사본이다. V2 행을 위한 기능별 runtimeSchemas·mappers 레지스트리와 V2 보안 프로필 해석 (resolveRestSecurityProfiles)도 같이 남아 있다. 사용자 지시: 최신 경로 하나만 남기고, 레지스트리 기준선 재승인을 승인했다. 고른 방법 - src/contracts/api-operations.ts를 projectApiOperationRows 하나로 바꿨다. 조립된 contribution의 descriptor마다 operationId, featureId, method, path, authProfileId, retrySemantics, requestBody, responseBody, responseEnvelope, request/response/problemSchema(검증기 schemaId) 행을 만든다. FE-REG-API는 같은 export(API_OPERATIONS)를 읽고, governance 정의를 이 필드로 바꿨다. requestSchema·responseSchema는 그대로 FE-REG-SCHEMA를 참조한다. - FeatureRuntime은 apiContract 대신 schemas(FE-REG-SCHEMA 행)만 받는다. installed-feature-runtime-registries는 schemas로 스키마 레지스트리를 만들고 FE-REG-API 행을 descriptor에서 뽑는다. RUNTIME_SCHEMA_CODECS, MAPPER_REGISTRY, REST_PROFILE_BINDINGS_VALID, API_RUNTIME_BINDINGS_VALID를 지웠다. - realtime snapshot 바인딩은 ApiOperationRow를 받고 method GET과 retrySemantics SAFE·IDEMPOTENT를 본다(V2의 contractVersion·semantics· replayPolicy 대신). - rest-profiles.ts에서 V2 행용 provider·CSRF 프로필 해석을 지웠다. V3는 조립 때 auth profile을 검사하고 자격증명 헤더를 프로필로 거른다. - 참조 기능: reference-api-contract.ts를 reference-schema-metadata.ts로 바꾸고(스키마 행만), V2 runtime codec·operation mapper·레지스트리 mapper를 지웠다. V3 descriptor가 쓰지 않는 NoRequest 스키마 행도 지웠다. - create:feature: <base>-api-contract.ts 대신 <base>-schema-metadata.ts를 만든다. codec·mapper 레지스트리 행과 그 테스트를 만들지 않는다. - 레지스트리 기준선을 update:registry-baseline으로 다시 만들고 승인했다 (digest 16f72742…, 승인자 DongHyeonka, 이유에 사용자 승인을 적음). - 매뉴얼 01·02·reference, starter-experience, 계약 문서의 V2 설명을 지웠다. 버린 대안 - V2 행을 남기고 V3에서 생성하기: 생성 단계와 생성물이 하나 더 생긴다. 행은 실행되지 않으므로 메모리에서 뽑아 검사하면 충분하다. - 스키마 메타데이터(FE-REG-SCHEMA 행)도 검증기에서 뽑기: boundary· unknownFieldPolicy·owner는 검증기에 없고, 라우트 스키마도 같은 레지스트리를 쓴다. 이 행은 V2가 아니라 스키마 레지스트리라 남겼다. 위험·한계 - BREAKING: FeatureRuntime 모양, contracts·rest-profiles·loaded-feature-runtimes 의 이름이 바뀌거나 없어졌다. memento-frontend의 memento-web이 V2 행을 쓴다. 옮기는 법은 CHANGELOG에 적는다. - V2 보안 프로필 일관성 검사(auth "none"과 ANONYMOUS, 쿠키 프로필의 CSRF 모드)가 사라졌다. V3 descriptor에는 그 칸이 없다. - BoundedPollOperationContract(realtime polling recipe)는 contractVersion: 2 필드를 갖지만 자체 계약이라 바꾸지 않았다. 검증 - check:types, lint, check:architecture, check:registries(11 registries PASS, compatibility=none), check:ci, check:diagnostics, check:adapter-inventory, verify:documentation 통과. - test:unit 2,566(새 tests/unit/api-operation-rows.test.ts 3건 포함), test:integration 114, test:component 245, test:contract 23, test:runtime-schema 56, tests/features 99 통과. - tests/unit/second-api-feature-registries.test.ts: V3 descriptor만 가진 두 번째 기능을 복사본에 넣으면 기준선을 고치지 않고 check:registries가 통과한다. - check:bundle 통과. 초기 JS 201,598 → 200,911 B. - test:feature-scaffold 16개, test:sample-removal 23개 검사 통과. BREAKING CHANGE: FeatureRuntime이 apiContract 대신 schemas를 받는다. defineRestOperation, ApiOperation, RestOperationV2, composeApiOperations, validateApiRuntimeBindings, getApiOperation, contracts의 API_OPERATIONS, createRestProviderProfile, RestProviderProfile, resolveRestSecurityProfiles, validateRestProfileBindings, REST_CSRF_PROFILES, RestCsrfProfile, loaded-feature-runtimes의 RUNTIME_SCHEMA_CODECS, MAPPER_REGISTRY, REST_PROFILE_BINDINGS_VALID, API_RUNTIME_BINDINGS_VALID가 없어졌다. 기능은 operation을 contract contribution에만 적고, schemas 행을 feature-runtime에 넘긴다. |
||
|
|
048f490ada |
refactor(http)!: V2 HTTP 클라이언트를 지우고 V3 실행기 하나만 남긴다
문제
HTTP 실행 경로가 둘이다. V3 실행기(createContractHttpExecutor)가 모든 기능을
실행하고, V2 클라이언트(createHttpClient)는 bootstrap의
createRuntimeHttpClient에서만 만들어지는데 그 함수를 앱 안에서 부르는 곳이
없다(테스트만 부른다). tech-log·memento도 같다. 그런데도 V2는 초기 청크에
들어가고, 짝 백엔드 해석(7db32e1~3261208)과 테스트를 두 벌로 유지하게 했다.
사용자 지시: 레거시를 두지 말고 최신 경로 하나만 남긴다.
고른 방법
- src/adapters/http/의 client.ts, bounded-json.ts, request-builder.ts,
resource-mapper.ts, retry-policy.ts, schema-registry.ts를 지웠다. Envelope
스키마는 backend-envelope.ts로 옮겼다. V3가 retry-policy.ts에서 쓰던
parseRetryAfter는 그것이 감싸던 platform/retry-after.ts의
parseRetryAfterDelay를 직접 부른다.
- 배럴의 V2 export와 bootstrap의 createRuntimeHttpClient·RuntimeHttpContract를
지웠다.
- V2 전용 테스트(http-client, http-diagnostics, auth-recovery,
legacy-http-credential-authority, bounded-json-compatibility,
request-builder, retry-policy)와 tests/helpers/http-contract-fixture.ts를
지웠다. 섞인 파일(http-execution-contract, runtime-adapters,
boundary-mapper)은 V2 블록만 지웠다.
- V2로 돌던 폼 테스트(form-foundation)는 Envelope을 읽는 V3 keyed create
계약으로 옮겼다. 400 VALIDATION_FAILED 필드 오류, {cause} 뒤 다시 저장,
422 뒤 저장 꺼짐을 그대로 검사한다. http-execution-v3-envelope 테스트는 V2와
비교하던 행을 기대 판정을 직접 적는 행으로 바꿨다.
- drill:runbook FE-RB-003은 V2 shouldRetry 대신 V3 실행기를 실제로 돌려
보낸 요청 수를 센다(NEVER 503: 1회, SAFE 503: 재시도, SAFE 스키마 불일치:
1회).
- check:diagnostics의 http 이벤트 생산자, registry-governance의 오류 표 소비자,
risk-coverage 고위험 경로, 아키텍처 금지 fixture, adapter INVENTORY, 문서의
경로를 V3 파일로 바꿨다.
버린 대안
- V2를 @deprecated로 한 릴리스 남기기: 템플릿과 두 다운스트림 모두 부르는
곳이 없어 옮겨 갈 사용자가 없다. 남기면 초기 JS와 두 벌 유지 비용만 남는다.
위험·한계
- BREAKING: 배럴과 bootstrap의 V2 이름을 쓰던 제품 코드는 컴파일이 깨진다.
CHANGELOG에 옮기는 방법을 적었다.
- V2에만 있던 동작이 사라졌다: 401 뒤 세션 복구 후 한 번 재전송, KEYED 503
자동 재시도. V3는 401을 UNAUTHENTICATED로 넘기고 KEYED 요청은 보낸 뒤
재시도하지 않는다.
- 기능마다 적는 V2 API 행(*-api-contract.ts, check:registries가 읽음)은 이
커밋에서 지우지 않았다. 다음 커밋이 지운다.
검증
- check:types, lint, check:architecture(금지 fixture 9건 거절),
check:adapter-inventory(140 files), check:diagnostics, check:registries,
check:ci, verify:documentation 통과.
- test:unit 2,585, test:integration 114, test:component 245, test:contract 23,
test:runtime-schema 56, tests/features 101 통과.
- drill:runbook FE-RB-003: no local check failed.
- check:bundle 통과. 초기 JS 203,354 → 201,598 B(−1,756 B).
BREAKING CHANGE: src/adapters/http/index.ts가 createHttpClient, HttpClient,
HttpClientDependencies, HttpFailure, HttpResult, LegacyHttpInput, Scheduler,
OperationRequestInput를, src/bootstrap/runtime-adapters.ts가
createRuntimeHttpClient, RuntimeHttpContract를 내보내지 않는다. 그 operation의
V3 descriptor를 만들어 createFeatureHttpBinding으로 실행한다.
|
||
|
|
846955498d |
fix(apps): 두 기능 라우트가 같은 경로를 쓰면 조립 때 막는다 (1101/14.4)
문제: 7d85589는 플랫폼 라우트가 가리는 기능 라우트를 막지만, 기능 라우트 둘이 같은 경로를 쓰는 경우는 막지 않는다. 라우터는 순위가 같은 경로를 선언 순서로 고르므로 뒤의 라우트는 그려지지 않는다. 메뉴와 레지스트리에는 그 라우트가 나온다. 파라미터 이름(`:orderId`와 `:itemId`)은 순위를 바꾸지 않으므로 이름만 다른 경로도 같은 경로다. R-B가 남긴 것으로 보고했다. 고른 방법: 같은 함수(assertFeatureRoutesReachOwningContext)에서 플랫폼 검사를 통과한 라우트마다 파라미터 이름을 지운 경로 모양을 기록하고, 이미 있으면 두 라우트와 기능 이름을 담아 throw한다. 앱 모듈을 평가할 때 실패하므로 09-06·09-03 검사와 같이 fail-closed다. APP_HOME 대체는 이 함수의 앞쪽 continue로 빠지고, 두 기능이 같은 플랫폼 라우트를 가져가는 경우는 기존 검사(withoutTakenOverPlatformRoutes)가 막는다. 버린 대안: 레지스트리 검사(check:routes)에서 경로 중복 보기. 그 검사는 route ID 중복만 보고, 라우터가 실제로 어떤 순위로 고르는지는 모른다. 위험·한계: 일부만 겹치는 경로(`/a/new`와 `/a/:id`)는 라우터가 정적 경로를 먼저 고르므로 막지 않는다. 그 경우는 accepts 테스트로 고정했다. splat(`*`) 기능 라우트끼리의 겹침은 모양 비교로만 본다. 검증: - RED: 새 테스트 2건 중 "같은 경로 거절"이 실패(22/23 통과) - GREEN: tests/architecture와 라우트 component 테스트 75건 통과 - tests/unit·component·integration·features 253파일 3,153건 통과 - tsc app·test, eslint 통과 |
||
|
|
7c8cb19e94 |
fix(routes): 등록 라우트 없는 URL의 적재 실패를 UNREGISTERED_ROUTE로 적는다 (1101/14.3)
문제: context gateway가 라우트 적재 실패를 `ui.render.failed`로 남길 때
`route_id`를 URL에서 고른다. 고르는 곳이 세 군데이고 결과가 서로 다르다.
- 청크 누락이 아닌 실패: `registeredRouteIdAt(...) ?? routeModule.id`.
레지스트리의 NOT_FOUND splat이 모든 URL에 맞아서 등록 라우트가 없는 URL은
`NOT_FOUND`가 되고 대체값은 한 번도 쓰이지 않는다. 운영에서는 not-found
화면이 깨진 것처럼 읽혀 플랫폼 담당에게 간다. 실제로 실패한 것은 context의
라우트 모듈이다.
- 복구하지 못한 청크 실패: 늘 `routeModule.id`(context id). telemetry는
`route_id`를 `^[A-Z][A-Z0-9_]{0,63}$`로만 받는다. 그래서 이 이벤트는
`invalid-attribute-value`로 버려진다(`projectTelemetryEvent`로 확인).
- 레이아웃 청크 실패: `?? "NOT_FOUND"`. 레이아웃 아래 context는 등록 경로에만
붙어서 지금은 닿지 않는 값이다.
이 진단이 구분해야 하는 것은 둘이다. 어느 화면(그래서 어느 기능)이 실패했나,
그리고 not-found 화면 자체가 실패했나. 그 값은 telemetry까지 가야 한다.
고른 방법: 세 곳이 `failedRouteIdAt(pathname)` 하나를 쓴다. URL의 등록
라우트 id를 쓰고, 등록 라우트가 없으면(NOT_FOUND만 맞으면) 명시값
`UNREGISTERED_ROUTE`(`UNREGISTERED_ROUTE_ID`, src/contracts/routes.ts)를
쓴다. 등록 URL의 청크 실패는 context id 대신 그 라우트 id가 된다. 라우트
id로 소유 기능과 context를 찾을 수 있다. 청크 복구의 chunkId 선택은 바꾸지
않았다.
버린 대안:
- context id(`routeModule.id`, 원래 의도한 대체값): 실패한 모듈을 정확히
가리키지만 telemetry가 버린다. 받게 하려면 `route_id` 문법을 소문자
kebab까지 넓혀야 한다. 그러면 `api.request.failed` 등 모든 이벤트의
`route_id` 검사가 약해진다.
- context id를 대문자 snake로 바꿔 쓰기: 숨은 이름 규칙이 생기고 실제 라우트
id와 섞인다.
- `context_id` 속성 추가: 진단·telemetry 허용 목록과 레지스트리 기준선을
바꿔야 한다. 기준선 재승인은 이 작업 범위가 아니다.
위험·한계:
- 등록 라우트가 없는 URL의 실패는 어느 context인지 진단에 남지 않는다. 같은
결함은 그 context의 등록 URL에서도 나므로 그 보고로 찾는다.
- [계약] `ui.render.failed`의 `route_id`에 `UNREGISTERED_ROUTE` 값이 생긴다.
복구하지 못한 context 라우트 청크 실패는 context id 대신 라우트 id를 적는다.
`route_id` 이름과 허용 문법은 그대로다.
- 기능이 `UNREGISTERED_ROUTE`라는 route id를 선언하면 구분되지 않는다. 막지
않았다.
검증:
- RED: context-boundary-diagnostics "unregistered handle" 1건이
`"route_id": "NOT_FOUND"`로 실패. context-route-gateway 새 2건이
`"route_id": "context-offline"`로 실패(8건 중 3 실패).
- GREEN: 두 파일과 context-layouts 14건 통과. 각 보고는 telemetry 투영
(`projectTelemetryEvent`)도 통과한다.
- 회귀: tests/{architecture,unit,features,platform,component,contract,
runtime-schema,integration,scripts,scale}(pnpm을 띄우는 3개 제외) 306
files, 3,572건 통과.
- tsc app·test 통과. 바꾼 파일 eslint 통과. check-registries,
check-diagnostics 통과. verify-documentation-readiness PASS_SCOPED.
|
||
|
|
7d85589ec1 |
fix(apps): 플랫폼 라우트가 가리는 기능 라우트를 조립 때 막는다 (1101/14.4)
문제: 라우터는 `AppShell` 아래 플랫폼 라우트를 모든 context보다 먼저 붙인다.
그래서 기능 라우트를 플랫폼 라우트도 받으면 오류 없이 플랫폼 화면이 나온다.
React Router `matchRoutes`로 라우터와 같은 구조를 만들어 확인했다.
- 같은 경로: context `examples/*`의 `/examples/ui`는 `EXAMPLES_UI`가 받는다.
레이아웃 아래에서도 순위가 같으면 앞에 있는 `AppShell`이 이긴다.
- `APP_HOME`이 아닌 id로 선언한 `/`는 플랫폼 홈이 받는다(
|
||
|
|
326120867c |
fix(http): 거절의 적용 여부를 백엔드 기준 표 하나로 V2·V3가 판정한다
문제 계약 문서 6.1절( |
||
|
|
d0414c85f9 |
fix(contracts): 런타임 설정 키마다 FE-REG-ENV 행을 요구한다 (1101/09-02)
문제: config.json V2 스키마의 키 중 RELEASE_ID와 BUILD_ID에는 FE-REG-ENV(ENV_REGISTRY) 행이 없다. 이를 잡는 검사도 없다. 그래서 제품이 PRODUCT_RUNTIME_CONFIG_FIELDS에만 키를 더하고 PRODUCT_ENV_REGISTRY 행을 빠뜨려도 check:registries가 그 키를 보지 못한다. ece944d를 검토하다 찾았다. 고른 방법: - tests/unit/env-registry-coverage.test.ts를 더한다. runtimeConfigV2 ArtifactSchema의 모든 최상위 키에 phase "runtime" 행이 있어야 한다. 제품 필드는 withProductFields로 같은 shape에 들어가므로 같이 검사된다. - RELEASE_ID, BUILD_ID 행을 public-metadata, 선택, 기본값 null로 더한다. 빌드가 config.json에 쓰는 릴리스 신원이고, VITE_BUILD_ID와 같은 분류다. 버린 대안: check-registries.ts에서 검사하기. 그 검사기는 registry-governance.json에 적힌 레지스트리 export를 같은 규칙으로 읽는 일반 검사기다. 스키마와 레지스트리를 맞대는 규칙을 넣으면 FE-REG-ENV 하나만을 위한 분기가 생긴다. 테스트 하나로 같은 실패를 낸다. 위험·한계: V1 전용 키(API_CONTRACT_VERSION)는 검사하지 않는다. 그 행은 FE-REG-ENV 변경 증거로 지워졌고, V1 reader는 지울 예정이다. 행을 더한 것은 additive라 기준선을 고치지 않는다. 검증: - RED: 새 테스트가 ["RELEASE_ID", "BUILD_ID"]를 보고하며 실패 - GREEN: 통과. env 관련 unit 4파일 43건 통과 - node scripts/check-registries.ts: 11 registries PASS, additive - tsc app·test, eslint 통과 |
||
|
|
ece944d08b |
feat(bootstrap): 제품 세션 owner와 FE-REG-ENV 행을 제품 파일로 받는다 (1101/09-02)
문제
09-02(
|
||
|
|
17fa8d1f65 |
fix(realtime): live-poll handoff 마감 실패를 13.1의 kind로 보고한다 (04-02)
문제: 1196b86은 stream coordinator의 마감 실패만 13.1 어휘로 바꿨다. live↔Poll handoff coordinator는 아직 네 마감을 모두 `IDLE_TIMEOUT`으로 보고한다. 설계 13.1에서 `IDLE_TIMEOUT`은 전송 idle(heartbeat/byte deadline → close + bounded reconnect)이다. 그래서 관측에서 "서버가 조용함"과 "우리 effect·checkpoint가 멈춤"을 kind로 나눌 수 없다. - switchToPoll quiescence 마감: IDLE_TIMEOUT/RECOVER - activateProbe quiescence 마감: IDLE_TIMEOUT/RECOVER - checkpoint 마감: IDLE_TIMEOUT/RECOVER - close drain 마감: IDLE_TIMEOUT/CLOSE 고른 방법: 결정 (a)를 1196b86과 같은 방식으로 적용한다. kind만 바꾸고 operation, retryable(전과 같이 true), fail-close 동작은 그대로 둔다. - quiescence 마감 → APPLY_FAILED/RECOVER. 기다리는 것은 이전 writer의 apply effect tail이다. stream coordinator의 effect 마감과 같은 kind다. APPLY_FAILED의 기본 retryable은 false라 true를 명시했다. 두 곳의 같은 분기를 `quiescenceFailure` 하나로 합쳤다. - checkpoint 마감 → PROVIDER_UNAVAILABLE/RECOVER. checkpoint authority가 throw할 때와 같은 kind다. - close drain 마감 → PROVIDER_UNAVAILABLE/CLOSE. stream·reconnect coordinator의 drain 상한과 같다. 이전부터 timer 실패도 같은 값이라 두 분기를 하나로 합쳤다. - 13.1 표: IDLE_TIMEOUT 행에서 handoff를 빼고 "내부 task 마감에는 쓰지 않는다"로 적었다. APPLY_FAILED·PROVIDER_UNAVAILABLE 행에 handoff 마감과 retryable 값, 뒤 동작을 적었다. 남은 IDLE_TIMEOUT 생성 지점은 SSE·WS의 RECEIVE·SUBSCRIBE(전송 idle)뿐이다. 버린 대안: - retryable도 kind 기본값으로(quiescence가 false가 됨): 결정 범위는 어휘다. 재시도 판단 변경은 따로 정한다. - close 마감에 CLOSED: 1196b86과 같은 이유로 버렸다. 아직 writer가 settle하지 않았는데 "닫힘"으로 읽힌다. 위험·한계: - 배럴로 공개된 handoff coordinator 결과의 kind가 바뀐다. IDLE_TIMEOUT을 보던 조합 코드는 APPLY_FAILED·PROVIDER_UNAVAILABLE을 봐야 한다. repo 안에 소비자는 없다(AVAILABLE_NOT_COMPOSED). - handoff에는 observer가 없어 관측 reason은 바뀌는 것이 없다. - 같은 APPLY_FAILED라도 stream coordinator는 retryable:false, handoff는 true다. 13.1 표에 둘 다 적었다. - realtime 레시피 gzip 40,902 → 40,878 B(한도 42,200). 검증: - RED: 기대값을 먼저 바꾸고 activateProbe quiescence 마감 테스트를 새로 넣은 뒤 live-poll-handoff-coordinator.test.ts 실행 → 7 failed | 9 passed. 7건 모두 received kind IDLE_TIMEOUT(close 4건, switchToPoll quiescence, activateProbe quiescence, checkpoint). - GREEN: `node scripts/run-vitest.ts run tests/unit/realtime` 14 files, 231 passed. - tsc app·test·recipes 통과, 바꾼 두 파일 eslint 통과, `check-optional-recipes`(source) PASS, `verify-documentation-readiness` PASS_SCOPED, `check-adapter-inventory` PASS. - 미실행: `check:architecture`(pnpm 필요). Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.1 04-02, 14.4 |
||
|
|
e5b7b3e857 |
fix(storage): partition 삭제가 다른 탭의 진행 중인 put을 기다린다 (0929/05-01)
문제: 손상 때문에 끝나지 못한 LOGOUT·ACCOUNT_DELETION purge의 partition 삭제는 두 단계다. 디렉터리를 origin lease 안에서 지우고, 이어서 journal row를 lease 밖에서 지운다. origin lease는 put의 BEGIN~FINISH만 막는다. 그래서 다른 탭에서 journal `begin`을 끝낸 put이 두 단계 사이에 BEGIN을 하면 새 디렉터리에 파일을 쓰고, 두 번째 단계가 그 put의 row를 지운다. put은 다음 journal 단계에서 `CONFLICT`로 실패하지만 파일을 치울 주체가 없다. - markFilesReady 전에 row가 지워지면: 보상이 manifest·staging을 지우고 chunk가 남는다. - commitPut 전에 지워지면: 보상이 없어 manifest·FILES_READY staging receipt·chunk가 남는다. staging receipt가 chunk를 GC·sweep에서 지키고 row가 없어 reconcile도 보지 않으므로 영원히 남는다. 다음 LOGOUT purge는 `chunkSweep: COMPLETED`를 보고하면서 이 bytes를 남긴다. - commit 뒤 complete 전에 지워지면: put은 성공하지만 object는 없고 manifest·chunk가 남는다. 삭제 전체가 put의 FINISH~commit 사이에 들어가는 경우(72edb55가 가정한 경우)는 수정 전에도 put이 `CONFLICT`로 실패하고 bytes가 남지 않았다. 고른 방법: partition 단위 Web Lock (`<mutationLockName>:partition:<a>:<ns>:<p>`)을 둔다. 모든 put·delete는 `withTransactionLock` 안에서 journal `begin`부터 끝날 때까지 shared로 쥐고, partition 삭제는 디렉터리·journal 두 단계를 exclusive로 쥔 채 한다. mutation은 삭제 전체보다 앞이거나 뒤에만 놓인다. 진행 중이던 put은 끝난 뒤 삭제가 지우고, 삭제가 lock을 요청한 뒤 온 put은 삭제 뒤에 돈다. lock 순서는 partition lock → origin lease 하나뿐이라 교착이 없다 (per-transaction lock은 `ifAvailable`이라 기다리지 않는다). 기다리는 동안 purge `signal`을 abort하면 `ABORTED`를 반환한다. 버린 대안: - commitPut `CONFLICT`면 보상: commitPut 전 경우만 고치고 chunk와 commit 뒤 경우가 남는다. 또 port가 "CONFLICT = 아무것도 commit 안 됨"을 약속하지 않아 동봉 구현에 기대는 숨은 결합이 생긴다. - commit까지 origin lease 쥐기: lease는 worker 안에 있고 journal은 page 쪽이다. 두 번째 단계(row 삭제)가 lease를 쓰지 않아 commitPut 전 경우가 그대로다. - row를 먼저 지우고 디렉터리를 나중에: 그 사이 begin한 put이 디렉터리 단계 전에 FINISH하면 파일 없는 COMMITTED row가 생긴다. 중간 실패 뒤 재호출로 이어서 끝나는 성질도 잃는다. - 디렉터리 → row → 디렉터리: 같은 이유로 파일 없는 commit이 생긴다. 위험·한계: - 삭제는 진행 중인 put·delete를 기다린다. source가 멈춘 put은 put idle bound(05-07)까지 삭제를 붙잡는다. 수정 전에도 그 put은 origin lease를 쥐고 있어 디렉터리 단계가 같은 시간을 기다렸다. - reconcile은 partition lock을 쥐지 않는다. reconcile은 파일을 새로 쓰지 않으므로(검증·정리·finalize만) 삭제와 겹쳐도 bytes를 남기지 않는다고 보았고, 이 경우는 테스트하지 않았다. - put·delete마다 Web Lock 요청이 하나 늘어난다. - offline-indexeddb 레시피 gzip 37,327 → 37,423 B(한도 38,500). - 공개 타입·배럴 변경 없음. 검증: - RED(수정 전, put 결과 단언을 넣기 전): 새 it.each 5건 중 3건 실패. 디렉터리를 put BEGIN 전에 지운 경우만 실패했다. markFilesReady 앞: chunk 1개 남음. commitPut 앞: staging receipt·chunk· manifest 남음. complete 앞: chunk·manifest 남음. 삭제 전체가 FINISH~commit 사이인 2건은 통과(put CONFLICT, bytes 0). "put은 삭제 앞에 끝난다" 단언을 더한 뒤 수정 전 코드: 5건 모두 실패. - GREEN: 5건 + abort 테스트 1건 통과. 같은 5건 10회 반복 10/10. - `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 tests/recipes` 136건 통과. - tsc app·test·web-worker·recipes 통과. 바꾼 파일 eslint 통과. `check-adapter-inventory` PASS, `check-optional-recipes`(source) PASS, `verify-documentation-readiness` PASS_SCOPED. - 미실행: `check:browser-file-storage-boundaries`·`check:architecture` (pnpm 필요), Playwright OPFS spec(webServer가 pnpm). Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.4 |
||
|
|
8a09c90379 |
fix(forms): 짝 백엔드 필드 검증 code마다 문구를 보인다 (1101/14.4)
문제
짝 백엔드는 필드 검증 실패의 details[].code에 NOT_BLANK, SIZE 같은 자기
code를 싣는다(백엔드 5786126c ClientSafeValidationDetails.java RULES 18-42와
INVALID). 폼 문구 표(form-contracts.ts VALIDATION_COPY)에는 zod code와
REQUIRED만 있어서, 백엔드 code는 모두 form.validation.unknown("입력값을
확인해 주세요.")이 된다. 필드 위치는 맞지만 무엇이 틀렸는지 알 수 없다.
고른 방법
- VALIDATION_COPY에 백엔드 code 20개를 모두 넣었다. 뜻이 같은 것은 기존
키를 쓴다: NOT_NULL·NOT_BLANK·NOT_EMPTY → required, PATTERN →
invalidFormat, TYPE_MISMATCH → invalidType, ASSERT_TRUE·ASSERT_FALSE →
invalidValue.
- 나머지 13개는 새 키로 ko-KR·en-US 문구를 넣었다(size, min, max, positive,
positiveOrZero, negative, negativeOrZero, email, past, pastOrPresent,
future, futureOrPresent, invalid). ar-EG는 en-US 표를 그대로 쓴다.
- 모르는 code는 그대로 form.validation.unknown이다.
- 백엔드 code를 쓰는 곳은 V2 client가 이미 details[].code를 issue code로
넘기는 경로(errors.ts safeValidationIssues)라 표 한 곳만 바꿨다.
버린 대안
- SIZE를 tooSmall·tooBig에 맞추기: SIZE는 짧은지 긴지 말하지 않는다. 한쪽
문구를 고르면 틀린 말을 할 수 있다.
- 백엔드가 보낸 message를 보여 주기: 백엔드 문구를 화면에 그리지 않는 규칙
(check-i18n rawFailureRender, errors.ts)을 깬다. 한국어만 있다.
- 백엔드 소스에서 code 목록을 읽는 검사: 두 repo가 나란히 있어야 돈다.
목록은 테스트에 SHA와 함께 적었다.
위험·한계
- 백엔드가 code를 더하면 프론트는 알지 못하고 기본 문구가 나온다. 알아챌
방법은 백엔드가 code 목록을 문서나 레지스트리로 내주는 것이다(최종 보고에
제안).
- 페이지·정렬 파라미터 code(PAGE_NEGATIVE, SIZE_EXCEEDS_MAX 등)는 details가
배열이 아니라 폼 issue가 되지 않으므로 넣지 않았다.
- 초기 JS gzip 202,770 → 203,165 B(+395, 예산 204,800). i18n catalog가 초기
청크에 있다.
검증
- RED: tests/component/form-foundation.test.tsx 3행 실패. ko-KR·en-US 모두
백엔드 code 20개가 기본 문구였고, 400 VALIDATION_FAILED NOT_BLANK 행은
"Name: 입력값을 확인해 주세요."를 보였다.
- GREEN: 위 3행과 "keeps the default copy for a code it does not know" 통과.
tests/component·unit·features 237 files 2951 tests 통과.
- node scripts/generate-product-feature-index.ts && node scripts/check-i18n.ts:
237 keys across 4 locales PASS. node scripts/check-registries.ts: PASS,
compatibility=none.
- tsc app·test 통과, 바꾼 파일 eslint 통과.
- 초기 JS는 기준 트리와 이 트리를 각각 build-frontend.ts로 빌드하고
check-bundle.ts와 같은 방식(classifyViteJavascript initialFiles, gzipSync)으로
쟀다. check-bundle.ts는 pnpm이 만드는 bundle.json이 필요해 돌리지 않았다.
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.4
|
||
|
|
bd83b496cc |
fix(http): V3 Envelope 진단이 V2와 같은 멱등성 거절 reason을 싣는다
문제 V2 클라이언트는 짝 백엔드의 422 IDEMPOTENT_REQUEST_MISMATCH와 400 IDEMPOTENCY_KEY_INVALID를 진단(http.request.completed)의 reason으로 남긴다( |
||
|
|
7db32e1343 |
fix(http): V3 실행기가 짝 백엔드 Envelope를 operation 단위로 읽는다
문제
create:feature가 만든 기능과 참조 기능이 쓰는 V3 실행기
(http-execution-v3.ts, feature-http-binding.ts)는 성공 본문을 DTO로,
실패 본문을 problem details(최상위 code)로 바로 검증한다. 짝 백엔드는
모든 JSON 응답을 Envelope {success, data|error, meta}로 보내고 null 필드는
키째 뺀다(백엔드 docs/web/http-contract.md 1절). 그래서 생성한 기능은 짝
백엔드의 성공을 SCHEMA_MISMATCH로, 실패를 PROBLEM_SCHEMA_INVALID(쓰기는
결과 불명)로 읽는다. 백엔드 맞추기(969979d~64e98ee)는 V2 클라이언트에만
들어갔다.
고른 방법: (가) V3 실행기에 operation 단위 Envelope 읽기
- V3 descriptor에 선택 필드 responseEnvelope("NONE" | "ENVELOPE_V1")를
둔다. 조립은 이 키를 허용하고 모르는 값을 거부한다. 값이 없으면 지금과
같다.
- ENVELOPE_V1이면 실행기가 바이트 상한·구조 예산을 Envelope 전체에 건 뒤
프레임을 확인한다. outputValidator는 data(키가 없으면 null),
problemValidator는 error를 받는다. 성공 status에 Envelope가 아닌 본문은
새 위반 ENVELOPE_MISMATCH다. 실패 Envelope의 바이트 상한은
min(64 KiB, responseByteLimit)이다.
- V2 client.ts의 멱등성 거절 표·필드 검증 판정·gateway status 규칙을
backend-envelope.ts로 옮기고 V2, V3 실행기, feature binding이 함께
읽는다. 실행기는 그 표의 판정(422·400 거절, 필드 목록 400은 적용 안 됨,
409 IDEMPOTENT_IN_FLIGHT·503 IDEMPOTENCY_UNAVAILABLE은 결과 불명)을
classifyProblem보다 먼저 쓴다. binding은 mapProblem이 답하지 않으면 V2와
같은 kind·code·validationIssues로 읽는다. V2 출력은 바뀌지 않았다.
- create:feature 뼈대: contribution이 ENVELOPE_V1을 선언하고 problem
스키마가 Envelope error(code 필수)다. 백엔드 본문을 그대로 적은
<base>-http-gateway.test.ts를 생성한다.
- MSW createHttpScenarioHandler는 descriptor가 ENVELOPE_V1이면 Envelope로
답한다.
버린 대안
- provider 단위(실행기 전체): V3 실행기는 baseUrl 하나라 앱 전체가 바뀐다.
참조 기능·테스트 계약의 problem details fixture가 모두 깨지고 한 앱이 두
모양의 API를 쓸 수 없다.
- (나) 백엔드 problem+json·DTO 모드: 백엔드 소유자 결정 2(JSON은 모두
Envelope)와 반대이고 백엔드가 두 모양을 계속 유지해야 한다.
- (다) 기능 스키마가 Envelope를 감쌈: 기능마다 null 생략·success 판별·
멱등성 판정을 다시 쓰고, V2 행(data 스키마)과 V3 스키마 ID가 갈라진다.
위험·한계
- HttpContractViolationKind에 ENVELOPE_MISMATCH가 더해졌다. default 없는
exhaustive switch는 분기를 더해야 한다.
- 실행기가 ENVELOPE_V1 operation의 위 판정을 classifyProblem보다 먼저
정한다. 패키지가 409 IDEMPOTENT_IN_FLIGHT를 적용 안 됨이라 해도 결과
불명이다.
- V2와 남은 차이: 64 KiB를 넘는 실패 Envelope는 V3만 읽지 않는다. 보낸
KEYED 요청의 503은 V2만 같은 키로 자동 재시도한다(판정은 같다). 구조
예산은 V3에만 있다.
- 참조 기능은 그대로 DTO·problem details다. tests/e2e/accessibility.spec.ts는
모든 API에 []로 답하므로 생성한 기능 라우트는 오류 화면이 검사된다(e2e는
돌리지 않았다).
- 초기 JS 202,770 → 203,321 B(+551 B, 예산 204,800 B).
검증
- RED: tests/integration/http-execution-v3-envelope.test.ts 19건 중 17건
실패(성공 → SCHEMA_MISMATCH, 실패 → PROBLEM_SCHEMA_INVALID·MAYBE_APPLIED,
조립 → unexpected key: responseEnvelope). 크기 2건은 처음부터 통과(동작
고정).
- GREEN: 같은 파일 25건 통과. 같은 응답을 V2와 V3에 보내 kind·code·
httpStatus·effect·retryAfterMs·validationIssues가 같음을 7가지 응답으로
비교한다.
- check:types, lint, check:architecture, check:adapter-inventory,
check:registries, check:diagnostics, check:i18n, check:ci 통과.
test:unit 2,604, test:component 244, test:integration 200 통과.
tests/features·tests/contract 124건 통과.
test:feature-scaffold 16개 검사 통과(생성한 gateway 테스트 5건,
Envelope로 답하는 목록 화면 테스트 3건 포함).
test:sample-removal 23개 검사 통과.
check:bundle 통과(203,321 / 204,800 B).
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.3, 14.6
|
||
|
|
b26517e6f2 |
fix(docs): 설계 주석에 문서 이름을 붙이고 지운 뒤 끊기는 링크를 없앤다 (1101/14-01)
문제: 코드 주석 87곳(74파일, .dependency-cruiser.json 포함)이 "Spec §N" 처럼 문서 이름 없이 절 번호만 적는다(대문자 83, 소문자 "spec §" 4). 가리키는 설계서는 README가 복사 뒤 지워도 된다고 한 docs/reviews/ 안에 있었다. 지울 수 있는 기록 검사는 경로 문자열만 찾아 이 참조를 잡지 못했다. 현재 계약 문서도 지울 수 있는 파일로 링크한다: docs/reviews/adapters/INVENTORY.md 145행이 옆의 adapter 리뷰로, docs/operations/adapter-remediation-ledger.md가 adapter 리뷰와 docs/superpowers/plans의 계획으로. 고른 방법: - 주석의 "Spec §"/"spec §"를 "scale-architecture.md §"로 바꾼다(앞 커밋이 옮긴 docs/architecture/scale-architecture.md). 설명 문장과 절 번호는 그대로다. 절 번호가 없는 "Spec §"는 없었다. - tests/unit/deletable-history-documents.test.ts에 "spec" + 선택 공백 + "§"(대소문자 무시)를 거부하는 검사를 더하고, 검사 대상에 .dependency-cruiser.json을 넣는다. - README "Files you can delete after copying"에서 INVENTORY.md 한 파일 대신 docs/reviews/adapters/ 폴더를 남기게 하고 이유(INVENTORY 행과 ledger가 그 리뷰로 링크한다)를 적는다. docs/README.md §3도 같게 고친다. INVENTORY의 행 구조는 바꾸지 않는다. - 남긴 adapter 리뷰와 ledger가 docs/superpowers/plans로 거는 링크 5곳은 링크를 풀고 "작업 이력 계획, 복사본은 지울 수 있다"로 적는다. 버린 대안: INVENTORY 145칸의 링크를 그룹 이름으로 바꾸기. 템플릿에서도 상세 리뷰로 가는 길이 없어지고 수정이 145곳이다. 계획 3개도 지우기 목록에서 빼기. 지울 수 있는 폴더 안에 예외가 흩어지고, 계획이 다시 다른 이력을 가리키면 남길 목록이 계속 커진다. 위험·한계: 검사는 "HTML spec §4"처럼 다른 명세를 "spec §"로 부르는 주석도 거부한다. 그때는 "HTML Standard §4"처럼 이름을 쓴다. src/contracts/storage-keys.ts:79의 "release-coherence plan Task 6"처럼 이름 없는 계획 참조는 이 검사가 잡지 않는다. 복사한 프로젝트가 이미 docs/reviews/adapters/를 지웠다면 링크는 계속 끊겨 있다. CHANGELOG.md의 이력 언급 4곳(:15 두 경로, :75 PRODUCT.md, :93)은 고치지 않았다. check:remediation-ledger는 이 변경 전후 같은 4줄로 실패한다(이미 있던 실패, 게이트 밖). tests/unit/telemetry.test.ts의 describe 이름 하나가 바뀐다. 검증: - RED: 치환 전 새 검사가 87줄을 들어 실패(1 failed | 1 passed). - GREEN: 같은 테스트 2 passed. 변이 "// Spec §4. budgets live here"를 src/platform/errors/app-error.ts에 넣으면 그 한 줄로 실패, 되돌림. - 치환 diff: 바뀐 87줄 쌍이 토큰 외에 같음(스크립트 대조, 불일치 0). - 삭제 실험(작업 트리 복사본에서 README 목록대로 지움): 끊긴 링크 148→0, 끊긴 경로 언급 10→4(남은 4는 CHANGELOG.md), 이름 없는 설계 참조 87→0, scale-architecture.md §N 87곳 중 없는 절 0. 같은 복사본에서 verify-documentation-readiness PASS_SCOPED, 지울 수 있는 기록 테스트 2 passed. - node scripts/verify-documentation-readiness.ts: PASS_SCOPED - node scripts/check-adapter-inventory.ts: PASS - node scripts/run-vitest.ts run tests/unit/deletable-history-documents.test.ts tests/unit/documentation-readiness.test.ts tests/unit/telemetry.test.ts: 50 passed. tests/architecture: 39 passed. - npx tsc --noEmit (app·node·test): 모두 통과. 바꾼 TS 74파일 eslint 통과. .dependency-cruiser.json JSON 파싱 통과. - 미실행: check:architecture(pnpm 필요). |
||
|
|
1269992b1a |
fix(release): 공개 대상 승인이 자리표시자 계약 신원을 거절한다 (U7 결정 2)
문제 - 기능 생성 명령(U7)은 계약 패키지 인자가 없으면 자리표시자 신원으로 기능을 만든다. 이 신원은 형식 검사(external-contract-runtime.ts의 패키지 신원 검사)를 모두 통과한다. 계약 집합 검사도 같은 목록을 자기 자신과 비교한다. 그래서 자리표시자를 그대로 둔 빌드가 staging· production 승인까지 통과한다. 고른 방법 (오케스트레이터 결정 2) - 자리표시자를 src/contracts/deployment-admission.ts에 상수로 둔다. digest는 sha256: 뒤에 0 64개, version 0.0.0, revision 0000000이다. 생성 명령이 이 상수를 import해 쓰므로 코드에서 자리표시자임이 보인다. - findAdmissionViolations에 세 번째 인자로 빌드가 컴파일한 계약 패키지 목록을 받는다. 대상이 PUBLIC(staging, production)이면 digest가 자리표시자인 패키지마다 contractPackages.<packageId> 위반을 낸다. BUILD_ID·RELEASE_ID의 PLACEHOLDER_IDENTIFIERS 검사와 같은 꼴이다. - check-release-admission.ts는 EXPECTED_CONTRACT_SET_PACKAGES를 넘긴다. 이미 COMPILED_PRODUCT_FEATURE_IDS를 같은 방식으로 읽는다. - 배포된 config.json의 수정본 검사(--config, 1101/13-05)는 패키지를 보지 않는다. 수정본은 비상 스위치만 바꿀 수 있고, 패키지는 빌드 필드라 빌드 승인 때 이미 검사했다. - APP_PROFILE 테스트의 production 행은 컴파일된 계약 집합에 자리표시자가 있으면 거절(그 이유로만)을, 없으면 승인을 기대한다. 생성 명령으로 기능을 하나 만들면 저장소 자체 빌드가 production 승인을 받지 못하는 것이 의도한 동작이기 때문이다. - 버린 대안: 계약 형식 검사에서 거절하기. 그러면 생성한 기능이 로컬에서 부팅·테스트되지 않는다. dist/release-manifest.json을 읽어 비교하기. 릴리스 일관성 검사가 이미 manifest와 컴파일된 목록이 같은지 보므로 같은 값을 한 번 더 읽고, 이 스크립트를 실행하는 테스트마다 manifest를 써야 한다. 위험·한계 - digest만 본다. version이나 revision만 자리표시자이고 digest는 진짜인 신원은 거절하지 않는다. 결정이 digest 하나를 자리표시자로 정했다. - local·development 대상은 거절하지 않는다. 의도한 동작이다. - 새 코드는 앱 번들에 들어가지 않는다(빌드 후 dist에서 거절 문구와 상수 이름 grep 0건). 앱은 이 모듈에서 isLoopbackHostname만 쓴다. 검증 - RED: 상수만 넣고 거절 전 코드로 새 테스트를 돌리면 실패한다. "staging: expected [] to deeply equal [ Array(1) ]" - RED(수정본·APP_PROFILE): 생성 명령으로 기능 하나를 만든 상태에서 두 테스트가 "contractPackages.@org-contracts/order: pins the placeholder identity ..."로 실패했다. - GREEN: tests/unit/deployment-admission.test.ts 25/25, feature-override-diagnostics.test.ts(스크립트 실행) 통과. 생성한 기능이 있을 때와 없을 때 모두 통과. 생성한 기능이 있을 때 production 대상 스크립트 실행은 rc=1과 위 위반 한 줄을 낸다. - npx tsc app·node·test rc=0, 바꾼 3파일 eslint rc=0. |
||
|
|
64e98ee2fa |
fix(http): V2 검증 거절을 적용 안 됨으로 보고 고친 값을 다시 저장하게 한다 (백엔드 1101/02-01)
문제
V2 클라이언트(client.ts)는 필드 검증 거절(422, 짝 백엔드의 400
VALIDATION_FAILED + 필드 목록)에 effect를 붙이지 않는다. mutation
코디네이터(application-query.ts mutationFailureWithEffect)는 effect가 없으면
MAYBE_APPLIED로 보고 admission을 UNKNOWN으로 붙든다. 폼은 VALIDATION_
REJECTED를 필드 오류로 보여 주지만, 참조 폼 페이지는 코디네이터가 결과 불명을
들고 있으면 저장 버튼을 끈다(reference-resource-form-page.tsx
mutationBlocked). 사용자가 필드를 고쳐도 다시 저장할 수 없다. use-app-form
자체는 VALIDATION_REJECTED에서 unknownSubmissionRef를 비우므로 막지 않는다.
막는 것은 코디네이터 상태다.
V3 참조 기능은 재현되지 않는다. 생성 분류기가 400·422를 NOT_APPLIED로
본다(reference-feature-contract-contribution.ts classifyProblem).
고른 방법
V2에서 필드 검증 거절(fieldValidation: 422, 또는 400 VALIDATION_FAILED +
배열 details)에 effect NOT_APPLIED를 붙인다. 멱등성 거절(IDEMPOTENCY_
REFUSALS)과 같은 자리에서 붙이고, 진단 reason은 멱등성 거절에만 남긴다.
근거(백엔드 계약)
- docs/web/http-contract.md 4절과 web adapter README 예외 표가 VALIDATION_
FAILED의 출처를 적는다: 요청 본문 바인딩(MethodArgumentNotValid
Exception), 컨트롤러 파라미터 제약(HandlerMethodValidationException),
Bean Validation(ConstraintViolationException), 페이지 파라미터, 읽을 수
없는 본문. 모두 요청을 묶는 단계에서 컨트롤러·use case보다 먼저 거절한다.
- 4절에 "상태를 바꾸지 않는다"는 문장은 없다. 이 판정은 위 출처에서
끌어낸 것이다.
버린 대안
- 코디네이터가 effect 없는 VALIDATION_REJECTED를 모두 NOT_APPLIED로 보기:
거절을 판정하는 곳은 응답을 읽는 클라이언트다. 코디네이터의 "모르면
MAYBE_APPLIED" 규칙은 그대로 둔다.
- 폼 페이지가 VALIDATION_REJECTED 뒤 결과 불명을 무시하기: 키가 붙은 채
남아 같은 입력을 다시 저장하면 같은 키가 나간다.
위험·한계
- application 층에서 쓰기 뒤에 VALIDATION_FAILED를 던지는 백엔드 코드가
있다면 이 판정은 틀린다. 짝 백엔드 IdempotencyExecutor는 실행 중 예외를
EFFECT_UNKNOWN_ABANDONED로 기록한다. 이 경우 같은 키 재전송은 500
IDEMPOTENCY_RECOVERY_REQUIRED를 받는다. NOT_APPLIED면 다음 저장이 새 키를
쓰므로 그 경로를 타지 않는다.
- 필드 목록 없는 400 VALIDATION_FAILED({cause}, 본문 파싱 실패)와 그 밖의
400·409는 effect 없이 둔다(결과 불명으로 붙듦). 이번 범위 밖이다.
- 422 IDEMPOTENT_REQUEST_MISMATCH는 원래 NOT_APPLIED였고 그대로다.
검증
- RED: tests/component/form-foundation.test.tsx "saves the corrected value
after a $status field error" 2행(422, 400 VALIDATION_FAILED) 실패. 필드
오류 뒤 저장 버튼이 disabled다.
- V3: tests/features/reference-feature/reference-production-vertical.test.tsx
"saves the corrected value after a server 422 field error"는 수정 전에도
통과한다(재현 안 됨, 동작 고정).
- GREEN: 위 행 통과. tests/integration/http-diagnostics.test.ts의 "unrelated
422" 행은 effect가 없다고 기대하던 것을 NOT_APPLIED로 바꾸고, 409 행을
더해 다른 거절은 effect가 없음을 고정했다. tests/integration/http-client.
test.ts에 400 VALIDATION_FAILED effect 단언을 더했다.
tests/unit·contract·runtime-schema·integration·component·features·platform
3398 tests 통과, 1개 실패(tests/unit/second-api-feature-registries.test.ts,
기준 3b7d73a에서도 같은 메시지로 실패). tsc app·test, 바꾼 파일 eslint
통과.
Refs: clean-architecture-backend-template docs/web/http-contract.md 4절, src/adapter/inbound/web/README.md 예외 표
|
||
|
|
02e35d2b38 |
fix(http): 짝 백엔드의 400 VALIDATION_FAILED를 폼 필드 오류로 읽는다 (백엔드 1101/02-01)
문제
짝 백엔드는 필드 검증 실패를 400 VALIDATION_FAILED로 보낸다. details는
위반 하나마다 {field, code, message}인 배열이다(백엔드 docs/web/http-
contract.md 4절, ClientSafeValidationDetails). field는 점으로 이은 속성
이름이고 인덱스는 뺀다. 클래스 수준 오류는 "request"다.
프론트 V2 클라이언트(client.ts)는 422만 필드 검증으로 읽는다. 400은
UNKNOWN_CLIENT_FAILURE이고 validationIssues가 없어서, 폼(use-app-form.ts)이
필드 오류 대신 "unavailable" 상태를 보인다. safeValidationIssues도
{issues}·{fieldErrors} 객체만 읽어서 배열 details를 버린다.
고른 방법
- V2: 400 + code VALIDATION_FAILED + details가 배열이면 422와 같은 것으로
본다. kind VALIDATION_REJECTED와 validationIssues를 422 경로와 같은 식으로
만든다. 폼은 기존 mapValidationFailureToFields와 allowedServerFields를
그대로 쓴다. 새 폼 경로는 없다.
- safeValidationIssues: details가 배열이면 각 항목의 field를 path로 읽는다.
message는 버린다. 후보 수는 기존 상한(MAX_VALIDATION_ISSUE_CANDIDATES)으로
자른 뒤 projectValidationIssues에 넘긴다.
- 그 밖의 400은 그대로 둔다: details가 {cause}인 VALIDATION_FAILED(본문
파싱 실패), details 없는 VALIDATION_FAILED, BAD_PARAMETER,
IDEMPOTENCY_KEY_INVALID(NOT_APPLIED 판정 유지).
버린 대안
- 400 VALIDATION_FAILED 전체를 VALIDATION_REJECTED로: 파싱 실패 같은
클라이언트 버그가 "입력값을 다시 확인해 주세요."로 보인다. 필드 목록이
있을 때만 바꾼다.
- 공용 projectValidationIssues가 field를 path 별칭으로 받게: zod 이슈와
V3 경로까지 같은 규칙을 갖게 된다. 백엔드 wire 모양은 V2 전용
safeValidationIssues에서만 읽는다.
- V3 참조 기능 mapProblem도 바꾸기: 참조 fixture는 problem+json
(type·title·status·issues)이라 짝 백엔드 Envelope가 problem 검증을 통과하지
않는다. 짝 백엔드 wire를 읽는 곳은 V2다.
위험·한계
- 백엔드 code(NOT_BLANK, SIZE 등)는 폼 문구 표(VALIDATION_COPY)에 없어서
필드 문구가 "입력값을 확인해 주세요."(form.validation.unknown)다. 필드
위치는 맞게 표시된다. 코드별 문구는 이 변경 밖이다.
- 페이지·정렬 파라미터 검증(PageValidationException)은 details가 배열이
아닌 단일 {field, code}라 지금처럼 UNKNOWN_CLIENT_FAILURE로 남는다. 폼
입력이 아니라 목록 조회 파라미터다.
- V2 필드 검증 실패에는 effect가 없다(422와 같다). mutation 코디네이터는
이것을 MAYBE_APPLIED로 보고 admission을 붙든다. 422에도 있던 기존 동작이다.
검증
- RED: tests/component/form-foundation.test.tsx 새 행이 실패. V2
클라이언트가 400 VALIDATION_FAILED를 받으면 폼 결과가 "unavailable"이고
Name 필드에 aria-invalid가 없다. tests/integration/http-client.test.ts
"reads the field details as validation issues" 실패(kind
UNKNOWN_CLIENT_FAILURE, issues 없음). 다른 400 3행은 처음부터 통과(유지
동작 고정).
- GREEN: 위 행 모두 통과. tests/unit·contract·runtime-schema·integration·
component·features·platform 283 files 중 282 통과, 3394 tests 통과.
실패 1개(tests/unit/second-api-feature-registries.test.ts "passes
check-registries…")는 기준 3b7d73a에서도 같은 메시지로 실패한다.
tsc app·test·node 통과, 바꾼 파일 eslint 통과, check:registries PASS.
Refs: clean-architecture-backend-template docs/web/http-contract.md 4절
|
||
|
|
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
|