f2b8ba75d3eaa8d3509da9e9a02d1052ab9efcff
80
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
5c0b37e39e |
fix(contracts)!: 쓰기 뒤에도 나오는 플랫폼 code를 쓰기 전 거절로 적지 못하게 한다
문제 commandEffect.refusedBeforeWrite의 조립 검사는 code 문법, 멱등성 접두사, 중복, Envelope 여부만 본다. 계약 문서 6.1절은 BAD_PARAMETER(어느 층이든 IllegalArgumentException), MAPPING_FAILED(멱등성 응답 직렬화는 action 뒤), DB_* 8개, LOCK_ACQUISITION_TIMEOUT, fileserver code를 "쓰기 뒤 가능"으로 적는다. 이 code를 목록에 적어도 조립이 통과하고, 그 code로 온 400·409·422가 NOT_APPLIED가 된다. 쓰기 뒤에 난 실패를 사용자가 다시 저장하면 새 키나 키 없는 새 요청이 나가 같은 항목이 둘 생길 수 있다(리뷰 실험 X2: 네 code가 조립을 통과하고 모두 NOT_APPLIED). 고른 방법 6.1절의 "쓰기 뒤 가능" 플랫폼 code를 src/contracts/external-contract-runtime.ts에 PLATFORM_CODES_POSSIBLY_AFTER_WRITE로 두고, assertRefusedBeforeWrite가 그 code의 선언을 6.1절을 이유로 거절한다. 실행기의 fail-close(조립 없이 부른 경우)도 같은 목록을 무시한다. 목록을 adapters가 아니라 contracts에 둔 것은 조립 검사가 adapters를 import할 수 없기 때문이다(리뷰 문서의 최소 개선은 backend-envelope.ts에 두라고 했다). backend-contract-pin.test.ts가 계약 문서 6.1절 표의 "쓰기 뒤 가능" 행을 읽어 목록과 양방향으로 대조한다. 참조 도메인 code와 web-advanced patch code는 엔드포인트가 단계를 정하므로 테스트의 예외 목록에 적고 선언할 수 있게 둔다. 버린 대안 - 매뉴얼 문장만 둔다(현상 유지): 폼을 막는 code를 넣고 싶어지는 바로 그 자리에 통제가 없다. - 업무 code 접두사 규칙(<FEATURE>_로 시작하는 code만 허용): 다운스트림 code 이름을 강제해 과하다. 위험·한계 - 이미 이 code를 적은 다운스트림 계약은 부팅에서 조립이 실패한다. 의도한 실패다. - 6.1절 표에 플랫폼 code가 더해지면 목록도 같이 고쳐야 한다. 대조 테스트가 알린다. 백엔드가 code를 더한 것은 pin을 올릴 때 6.1절을 다시 읽어야 안다. - 업무 code를 잘못 선언하는 것은 여전히 막지 못한다(기능 작성자의 판단). - 대조 테스트는 계약 문서를 읽으므로, 문서를 복사하지 않는 기능 제거 드릴(FE-GATE-020의 optional-recipe·browser-file-storage·realtime)에서는 돌지 않는다. `scripts/lib/removal-fixture.ts`의 문서 테스트 목록에 `tests/unit/backend-contract-pin.test.ts`를 더했다. 저장소 자신의 test:unit은 그대로 돌린다. 검증 desktop batch에서 확인: node scripts/run-vitest.ts run tests/unit/external-contract-runtime.test.ts tests/unit/backend-envelope.test.ts tests/unit/backend-contract-pin.test.ts corepack pnpm test:optional-recipe-removal BREAKING CHANGE: refusedBeforeWrite에 계약 문서 6.1절이 "쓰기 뒤 가능"으로 둔 플랫폼 code(PLATFORM_CODES_POSSIBLY_AFTER_WRITE)를 적으면 composeContractContributions가 거절한다. 그 code를 목록에서 지운다. 그 code의 실패는 결과 불명으로 남는다. Refs: 1105/03-01 |
||
|
|
41f8801d64 |
chore(review): 1103 기능 생성기·기능 패턴 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 03-07 09-06 16-01 16-04~16-07 # Conflicts: # docs/manual/01-add-a-feature.md # docs/manual/reference/create-feature.md # docs/manual/reference/patterns.md # scripts/create-feature.ts # scripts/test-feature-scaffold.ts |
||
|
|
3b40f73638 |
fix(contracts)!: 스키마 메타의 boundary를 쓰임과 대조하고 실패 본문 행을 둔다
문제
<base>-schema-metadata.ts의 boundary는 손으로 적고, check:registries는 값이
목록 안인지만 본다. 응답 스키마에 boundary "api-request"를 적어도 타입·
레지스트리·기능 테스트가 모두 통과한다(리뷰 E-4 세 번째 변이). direction과
unknownFieldPolicy는 07-03 수정(
|
||
|
|
83f4dd5f8e |
chore(review): 1103 예제 화면·시각·접근성 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 09-04 15-01 12-01 11-01 16-03 11-02 # Conflicts: # docs/architecture/frontend-application-foundation.md # docs/architecture/starter-experience.md # docs/manual/03-outside-feature-folder.md # tests/unit/runtime-adapters.test.ts |
||
|
|
68f94f5e93 |
refactor(server-state): 아무도 읽지 않는 쿼리·뮤테이션 정의 칸을 선택 칸으로 둔다
문제 QueryDefinition의 owner·operationId와 BoundMutation의 owner는 필수 칸이다. bindQuery가 돌려주는 객체에는 둘 다 없고, src 어디서도 읽지 않는다. 기능 작성자는 효과 없는 값을 매번 채우고, 매뉴얼은 그 오타를 "못 잡는 위험"으로 적어 오히려 신경 쓰게 한다(리뷰 16-06 ①②). 고른 방법 세 칸을 @deprecated 선택 칸으로 바꾼다. 참조 기능과 생성 뼈대는 더는 채우지 않는다. 요청 기록의 operation ID는 지금처럼 descriptor에서 온다. 매뉴얼 6·7단계와 patterns.md에 "적지 않는다"와, 라우트 계약 title· navigationLabel을 무엇이 읽는지(FE-REG-ROUTE, lab 측정)를 적었다. 버린 대안 - 칸을 바로 지우기: 객체 리터럴의 초과 속성 검사로 테스트 3파일과 다운스트림 정의가 컴파일 오류가 난다. 선택 칸으로 한 릴리스 두고 지운다. - 쿼리 operationId를 진단 이름표로 잇기: HTTP 실행 기록이 이미 descriptor의 operation ID를 싣는다. 같은 값을 두 번 싣는다. 위험·한계 - 라우트 계약의 title·navigationLabel(16-06 ③)은 그대로 둔다. 지우려면 FE-REG-ROUTE 기준선 행을 catalog에서 만들고, 플랫폼 라우트와 test-performance.ts를 함께 바꿔야 한다. 다른 작업(예제 화면 이동)과 같은 파일이라 이번에는 문서로만 적었다. 검증 - RED: application-query-scope-fence 새 테스트가 tsconfig.test에서 owner· operationId 누락으로 타입 오류. 선택 칸으로 바꾼 뒤 통과. - tests/features/reference-feature, tests/unit/create-feature.test.ts, scope-fence 129건 통과. check:types(app·node·test), lint 통과. Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-06 |
||
|
|
f59a806429 |
feat(server-state): 뮤테이션 정책이 operation ID와 키 여부를 descriptor에서 받는다
문제 BoundMutation의 operationId와 requiresIdempotencyKey는 기능이 손으로 다시 적는 자유 값이다. operationId에 오타가 있어도 check:types와 check:registries가 통과하고, 실행기는 intent의 operation ID가 descriptor와 다르다며 보내기 전에 거부한다(MISSING_IDEMPOTENCY_KEY 위반). 화면은 "요청을 처리할 수 없습니다"로 멈추고 원인을 말하지 않는다(리뷰 E-2). 1101/03-03이 같은 재기술을 적었다. 고른 방법 src/contracts/server-state.ts에 commandMutationIdentity(descriptor)를 둔다. descriptor의 operationId와 retrySemantics === "KEYED"를 돌려주고, 정책은 이것을 펼쳐 쓴다. 상수 이름 오타는 tsc가 잡는다. GET·HEAD descriptor를 넘기면 바인딩 때 throw한다. 참조 기능의 생성 정책이 이것을 쓴다. 버린 대안 - BoundMutation.operationId를 brand 타입으로: 자유 문자열도 막지만 테스트 약 27곳과 다운스트림 정책을 깨는 공개 타입 변경이다. - 실행기 위반 이름을 INTENT_OPERATION_MISMATCH로 나누기: http 어댑터의 닫힌 위반 어휘와 화면 매핑을 바꾼다. 값을 descriptor에서 받으면 그 경로에 닿지 않으므로 미뤘다. - 타입에서 method를 쓰기 method로 좁히기: InstalledHttpContract로 주석한 descriptor(method: HttpMethod)가 모두 타입 오류가 나서 실행 때 검사만 둔다. 위험·한계 - 정책에 operationId 문자열을 직접 적는 길은 남는다. 매뉴얼 7단계 "못 잡음"에 적었다. - 참조 기능 presentation이 계약 기여 파일을 import한다. 두 파일 모두 지연 청크라 초기 JS는 바뀌지 않는다(check:bundle은 다음 커밋들과 함께 잰다). 검증 - RED: tests/unit/command-mutation-identity.test.ts 4건이 함수 없음으로 실패. GREEN 뒤 통과. - tests/features/reference-feature, tests/component/application-query.test.tsx 125건 통과. - check:types, check:architecture, lint, verify:documentation 통과. Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-05 |
||
|
|
b96d61d8f7 |
feat(examples)!: 예제 화면 3개를 끌 수 있는 기능으로 옮긴다
문제
/examples/ui, /examples/states, /examples/auth(와 /examples/platform)는
플랫폼 라우트 레지스트리에 고정이었다. VITE_PRODUCT_FEATURES와
FEATURE_OVERRIDES는 기능만 빼므로 제품은 이 화면을 끌 수 없었다.
릴리스 게이트 FE-GATE-028은 ROUTE_REGISTRY의 모든 라우트에 서명된
수동 접근성 기록을 요구해서, 제품은 템플릿 갤러리를 운영 메뉴에 두고
서명하거나 템플릿 파일 5개와 src/presentation/examples/를 지워야 했다.
고른 방법
- UI 갤러리·화면 상태·인증 연동을 platform-examples-feature로 옮겼다.
자기 context platform-examples-context(루트 examples/*)에 산다.
reference-context의 examples/reference-resources/*와 플랫폼 라우트
/examples/platform이 더 구체적이라 그 URL은 그대로 간다.
- 라우트 ID·경로·청크 ID·표면은 바꾸지 않았다. 시각·e2e 테스트와 a11y
기록(artifacts/tests/a11y-manual/EXAMPLES_*.md)이 그대로 이 이름을
쓴다. 기능을 빼면 a11y 목록은 ROUTE_REGISTRY에서 오므로 같이 빠진다.
- 실행부는 비어 있다(스키마·adapter·계약 기여 없음). 페이지는 context
routes에서 페이지마다 lazy로 받는다.
- 플랫폼 구성 화면(EXAMPLES_PLATFORM)은 플랫폼 라우트로 남겼다. 처음에는
같이 옮겼다. 같은 호스트·같은 부하(15~19)에서 d99301b와 번갈아 잰
lab이 기능 라우트로는 443·432 ms FAIL이었다(d99301b 133·183 ms
PASS). 기능 라우트의 첫 진입은 context routes 모듈을 받은 뒤에 페이지
청크를 받는다(요청 추적: 939 B + 177 B 다음에 5,183 B + 3개). 페이지를
routes 모듈에 정적으로 넣으면 릴리스 매니페스트의 routeChunks 계약
(페이지마다 dynamic entry)이 깨진다. 15-01의 "예산을 올리지 않는다"를
지키려고 이 한 화면은 남겼다.
- 홈 화면은 예제 라우트 ID를 적지 않는다. 내비게이션의 처음 세 화면을
"{title} 보기"로 보여 준다. 템플릿에서는 예전과 같은 세 링크(플랫폼
구성·UI 구성요소·화면 상태)가 나오고, 예제를 뺀 제품에서는 그 제품의
화면이 나온다. home.starter.platform·ui·states 키를 home.starter.open
하나로 바꿨다. VITE_PRODUCT_FEATURES=none 빌드 검사
(product-feature-selection-build)가 홈 청크의 예제 라우트 ID를 잡았다.
- 예제 화면 component 테스트는 tests/features/platform-examples-feature/로
옮겼다. 제거 드릴이 같이 지운다. runtime-adapters 테스트는 API가 있는
기능만 센다(예제 기능은 API가 없다). context-route-roots 테스트의
"플랫폼 라우트와 같은 경로" 예는 /examples/platform으로 바꿨다.
- old-tab-chunk-recovery e2e는 페이지 소스를 빌드 A의 Vite manifest에서
찾는다(기능 폴더 이름을 적지 않음). UI 갤러리가 기능 라우트라 B 탭이
잃는 청크는 그 context routes 모듈이다. 허용 패턴에 넣었다.
- 예제 화면 문구는 08-07대로 한국어 고정이다. 화면 문구 ESLint 규칙의
예외에 새 폴더를 넣었다.
- 버린 대안: 빌드 변수로 숨김(선택 장치가 하나 더 생김), 예제 화면만
제품이 지우게 둠(동기화 충돌 자리가 남음).
위험·한계
- 공개 경로가 바뀌었다. src/presentation/examples/{ui-gallery,
state-gallery,auth-example}-page.tsx, PLATFORM_ROUTE_REGISTRY·
PLATFORM_ROUTE_RUNTIME(_CONTRACT)의 EXAMPLES_UI·STATES·AUTH,
home.starter.platform/ui/states 키를 쓰던 다운스트림은 깨진다.
- 플랫폼 구성 화면은 여전히 끌 수 없고 FE-GATE-028 서명 대상이다.
- tests/e2e와 tests/visual의 여러 spec이 예제 화면을 자기 페이지로 쓴다.
예제를 뺀 제품은 그 spec을 자기 화면으로 바꾸거나 지워야 한다
(starter-experience.md에 적음). 제거 드릴은 브라우저 테스트를 돌리지
않아 이것을 보지 않는다.
- 예제 기능 제거 드릴은 16-02(빈 ciScripts로 CI 기준선 사유가 공백)
때문에 그대로는 시작하자마자 실패한다. 아래 드릴 결과는 그 한 줄을
임시로 고친 상태에서 낸 것이다(커밋하지 않음).
- 기능 라우트 첫 진입이 이 lab 조건에서 약 430 ms라는 것은 어느 게이트도
재지 않는다.
검증
- product-feature-selection-build(VITE_PRODUCT_FEATURES=none 빌드):
홈 청크의 예제 라우트 ID 3건으로 실패한 것을 확인하고 홈 화면을 고친
뒤 통과.
- test:sample-removal -- --feature=platform-examples-feature(heavy lock,
16-02 한 줄 임시 패치): PASS, 13 checks(typecheck, architecture,
registries, test:all, coverage, test-evidence, ci, home-smoke, build,
route-absent, 잔여 ID 0). 첫 시도에서는 lab-performance 단위 테스트가
측정 라우트 조회가 포트 검사보다 먼저여서 실패했다(그 뒤 이 변경에서
측정 라우트를 플랫폼에 남겨 조회 변경 자체를 뺐다).
- test:unit 2,587, test:component 253, tests/features·platform·
architecture 383 통과. check:types, lint, check:architecture,
check:i18n, check:registries(additive), verify:documentation 통과.
- test:e2e 세 엔진 187 passed, 3 skipped(Firefox SW quarantine).
old-tab-chunk-recovery 포함. test:a11y 60 passed.
- build + check:bundle: 초기 JS 201,940 / 204,800 B(+92 B).
- lab(측정 라우트를 기능으로 옮긴 시도): 443·432 ms FAIL, 같은 묶음
d99301b 133·183 ms PASS(부하 15~19). 남긴 뒤 136·134 ms PASS.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-04
BREAKING CHANGE: 예제 라우트 EXAMPLES_UI·EXAMPLES_STATES·EXAMPLES_AUTH가
플랫폼 레지스트리에서 platform-examples-feature로 옮겨졌다. 페이지 파일은
src/features/platform-examples-feature/presentation/으로 갔고,
PLATFORM_ROUTE_REGISTRY·PLATFORM_ROUTE_RUNTIME_CONTRACT·
PLATFORM_ROUTE_RUNTIME에 이 키들이 없다. 홈 문구 키
home.starter.platform·ui·states는 home.starter.open({title})로 바뀌었다.
예제를 지운 다운스트림은 이 기능 폴더와 context를 지우면 된다.
|
||
|
|
3f7e10c91a |
fix(contracts): 한 계약 기여 안에서 응답 모양이 다른 operation을 거절한다
문제 responseEnvelope는 operation마다 적는 선택 칸이다. 생성 뼈대에 operation을 손으로 더하면서 이 줄을 빠뜨려도 check:types, check:registries, 라우터를 거치는 페이지 테스트가 모두 통과한다. MSW 시나리오 핸들러가 descriptor의 선언대로 답하기 때문이다. 짝 백엔드에 붙이면 그 화면만 SCHEMA_MISMATCH로 깨진다(리뷰 E-1). 고른 방법 계약 조립이 기여 하나 안의 operation이 같은 응답 모양을 읽는지 본다. 값이 없는 것과 "NONE"은 같은 모양이다. 기여 하나는 백엔드 하나의 패키지라서 그 안의 operation은 한 모양이다. 두 백엔드를 쓰는 기능은 기여를 나눈다. 거절 reason은 두 operation과 고칠 방법을 말한다. 앱을 조립하는 모든 테스트와 check:registries가 실패한다. 버린 대안 - responseEnvelope를 필수 칸으로: tsc가 잡는 가장 강한 통제지만 descriptor 약 25곳(참조, tests, 다운스트림 손 descriptor, 계약 패키지)을 깨는 공개 타입 변경이다. 같은 실수(일부만 빠뜨림)를 이 규칙이 잡으므로 작은 쪽을 골랐다. - 기여 단위 기본값: "기본값이 어디서 오나"라는 규칙이 하나 는다. 위험·한계 - 기여 안의 operation 모두에서 줄을 빼면 잡지 못한다. 생성된 gateway 테스트 (백엔드 본문을 손으로 적음)만 잡는다. 매뉴얼에 적었다. - 한 기여에 두 모양을 섞던 다운스트림 기여는 조립이 거부한다. 레포 안에서는 테스트 fixture 하나(api-operation-rows)가 그랬고 고쳤다. 검증 - RED: 새 테스트 3건 중 섞인 기여 거절 1건 실패. GREEN 뒤 통과. - tests/unit·integration·contract·component·features·runtime-schema·platform· architecture 297파일 3,718건: 섞인 fixture 1건만 실패 → 고친 뒤 통과. - check:types, lint 통과. Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-01 |
||
|
|
3fba68bebc |
refactor(contracts): FE-REG-API 행이 refusedBeforeWrite를 타입으로 읽는다
문제 fix/r1103-contracts는 fix/r1103-http가 아직 없을 때 CommandEffectDescriptor에 없는 refusedBeforeWrite를 구조 캐스트로 읽었다. 두 브랜치를 합치자 그 칸이 타입에 생겼다. 또 행 투영 테스트가 Envelope가 아닌 operation에 refusedBeforeWrite를 적는데, http 쪽 조립 검사(1103/03-01)는 그것을 거절해 테스트가 ContractContributionError로 실패한다. 고른 방법 - api-operations.ts는 effect.refusedBeforeWrite를 타입으로 읽는다. - 테스트의 create descriptor에 responseEnvelope ENVELOPE_V1을 주고, code를 업무 거절 모양(TEST_ENTITY_INVALID 등)으로 바꾼다. 위험·한계 - 행 모양은 그대로다. 기준선 영향 없음. 검증 - tests/unit/api-operation-rows.test.ts 12건, test:unit 2,790건, check:types, lint 통과. Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-01 |
||
|
|
6088f6e533 |
chore(review): 1103 HTTP 쓰기 경로 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 03-01~03-06 0929/03-03 08-05 10-02 10-04 12-06 # Conflicts: # docs/manual/02-decision-tables.md |
||
|
|
d5e3bf2e2c |
chore(review): 1103 계약·레지스트리 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 07-01~07-04 13-04 14-06 |
||
|
|
39c1de2e5e |
feat(diagnostics): 결과 불명 쓰기의 effect와 원인을 진단에 싣는다
문제 실행 관측(HttpExecutionObservation)에는 effect가 있지만 조립 루트 projector는 진단에도 텔레메트리에도 싣지 않는다. 진단 허용 키에 effect가 없고 status는 묶음(4xx)만 남는다. 그래서 진단 버퍼에서 결과 불명과 적용 안 됨, 처리 중 409와 업무 409, 503 IDEMPOTENCY_UNAVAILABLE 재전송 소진이 같은 줄이 된다. 텔레메트리로는 결과 불명 쓰기의 비율을 셀 수 없다. 03-01이 고쳐져도 업무 거절은 선언 전까지 결과 불명이라 이 구분이 필요하다. 고른 방법 - effect_certainty 키: 진단·텔레메트리(api.request.failed 선택 속성) 모두 HttpEffectCertainty 다섯 값만 받는 닫힌 value policy(isEffectCertainty)를 쓴다. cardinality는 bounded. projector가 두 sink에 싣는다. - 결과 불명 원인: Envelope 명령에서 표가 MAYBE_APPLIED를 줄 때 닫힌 UnknownEffectReason을 진단 reason으로 싣는다. IN_FLIGHT(409 처리 중), IDEMPOTENCY_UNAVAILABLE, COMPLETION_UNKNOWN, RECOVERY_REQUIRED, SERVER_TIMEOUT(503 REQUEST_TIMEOUT), STAGE_UNKNOWN(단계를 모르는 400·409· 422). 텔레메트리에는 싣지 않는다(VD-07: reason은 진단 전용). - VD-07 5-1의 projector 키 목록과 reason 값 목록을 고쳤다. 남아 있던 "effect_certainty는 필요해지면 더한다" 문장은 지웠다. 버린 대안 - 백엔드 error.code 원문을 진단에 싣기: cardinality 결정(1101 README 14.6)이 먼저다. 닫힌 원인 집합이면 그 결정과 무관하다. - 원인도 텔레메트리에: 텔레메트리 reason은 전달 실패용 닫힌 집합이라 뜻이 섞인다. 비율은 effect_certainty로 센다. 위험·한계 - Envelope가 아닌 operation의 MAYBE_APPLIED는 원인 없이 effect만 남는다. 응답을 잃은 경우는 outcome(TRANSPORT_FAILURE)이 원인을 보인다. - 텔레메트리 수집기가 속성 목록을 고정해 두었다면 새 선택 속성을 받도록 맞춰야 한다. 검증 - RED: envelope 진단 9행(effect·reason), observability 1건, cardinality 8건 실패. - GREEN: 처리 중 409는 reason IN_FLIGHT, 업무 409는 STAGE_UNKNOWN, 둘 다 effect_certainty MAYBE_APPLIED. 진단 투영이 모두 통과한다. tests/unit·integration·component·features·contract·runtime-schema·platform 282파일 중 281파일 통과. 남은 1건은 provider-guardian-transaction의 inotify 한도(ENOSPC)로 이 변경과 무관하다. - check:diagnostics, check:types, lint, verify:documentation 통과. Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-05 |
||
|
|
c99b7a7f63 |
docs(contracts): 두 오류 어휘와 commandRecovery를 누가 읽는지 타입 옆에 적는다
문제 - AppFailure(닫힌 kind, retryable, action)와 AppError(열린 owner.reason kind, retryability)의 관계가 타입 옆에 없다. AppFailure.retryable과 action "retry"는 뜻이 다른데(CONFLICT는 retryable false, action retry) 설명이 없어 모순으로 읽고 "고치는" 변경이 나올 수 있다(1101/07-05). - CommandRecoveryDescriptor는 KEYED 쓰기에 필수지만 HTTP 실행기는 읽지 않는다. 결과 불명 쓰기를 기능 gateway가 수습한다는 것은 설계서 4.4절에만 있다(1101/07-07). - 07-01(c)에서 더한 읽기 retrySemantics 거절 문구가 errors.md reason 표에 없다. 고른 방법 주석만 더한다. AppFailure 위에 어느 경계에서 어느 어휘를 쓰는지와, 둘 다 재시도 동작을 바꾸지 않는다는 것. retryable 칸에 "src에서 읽는 곳이 없고, 화면 버튼은 action"이라는 것. CommandRecoveryDescriptor 위에 실행기가 읽지 않고 기능 gateway가 재전송·조회를 정한다는 것. errors.md reason 표에 한 행. 버린 대안 - retryable을 autoRetryable 같은 이름으로 바꾸기: 다운스트림 import를 깨는 비용에 비해 얻는 것이 작다. 위험·한계 - 동작은 바뀌지 않는다. "src에서 읽는 곳이 없다"는 grep으로 확인한 지금 상태다. 검증 - grep: src/presentation·bootstrap·features·application에서 AppFailure.retryable을 읽는 곳 0. commandRecovery를 읽는 곳은 플랫폼 개요 화면뿐. - eslint, verify:documentation 통과. Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 1101/07-05, 1101/07-07 |
||
|
|
1e8b3d049f |
feat(http): operation이 쓰기 전 업무 거절 code를 선언한다
문제 Envelope operation의 400·409·422는 백엔드 표의 세 code만 NOT_APPLIED이고 나머지는 모두 MAYBE_APPLIED다. 기능의 classifyProblem은 이를 바꿀 수 없다. 짝 백엔드 생성 기능의 create는 이름 규칙을 트랜잭션 전에 검사하고 400 <FEATURE>_INVALID를 준다. 그런데 폼은 "변경 결과를 확인할 수 없습니다"를 띄우고 저장 버튼을 끈다. 입력을 고쳐도 다시 저장할 수 없다(리뷰 실험 X-A·X-B). 401·403·429는 classifyStatus로 operation이 정할 수 있는데 400·409·422는 정할 자리가 없다. 고른 방법 (결정 D2 ①) - CommandEffectDescriptor에 선택 칸 refusedBeforeWrite?: readonly string[]. 표 밖 400·409·422가 이 목록의 code면 NOT_APPLIED다. 함수가 아니라 code 목록이라 리뷰할 수 있고, status 범위를 통째로 NOT_APPLIED로 만들 수 없다. - 조립 검사(assertRefusedBeforeWrite): 목록은 Envelope operation에만, code는 백엔드 문법, 중복 금지. IDEMPOTENT_*·IDEMPOTENCY_*는 거절한다 (409 IDEMPOTENT_IN_FLIGHT의 앞선 요청은 적용될 수 있다). - 실행기도 같은 code와 표의 code(VALIDATION_FAILED 등)를 무시한다. 조립 없이 실행기를 부르는 경로의 fail-close다. - 조립이 목록을 얼려 복사한다(LIVE-03). classifier는 지금처럼 참조로 두고, 설치본이 원본을 prototype으로 물려받아 classifier의 this가 그대로다. - 매뉴얼 02 4절과 계약 문서 6.1절에 언제 적고 언제 적지 않는지, <FEATURE>_INVALID 예와 거부 문구를 적었다. 버린 대안 - 표 밖 400 전체를 NOT_APPLIED: BAD_PARAMETER·MAPPING_FAILED는 쓰기 뒤에도 나온다. - 분류기 판정 복원: 3261208이 버린 길. 400 전체를 NOT_APPLIED로 보는 분류기가 키 보호를 푼다. - 결과 불명 화면에 "적용되지 않음" 버튼: 사용자가 모르고 누르면 새 키로 중복이 생긴다. - 백엔드 단계 신호(error.applied): 두 repo 계약 변경이다(D2 ②). 위험·한계 - 쓰기 뒤에도 나오는 code를 잘못 적으면 결과 불명 요청이 새 키로 나가 중복이 생길 수 있다. 책임은 선언한 기능 작성자에게 간다. 매뉴얼이 백엔드 코드에서 던지는 곳을 확인한 code만 적으라고 한다. - 생성기(scripts/create-feature.ts)는 이 칸을 아직 쓰지 않는다. 다른 작업이 이어 받는다. - 결과 불명 화면이 거절 code의 문구를 보이는 것(08-01 (가))은 하지 않았다. 검증 - RED: 새 테스트 17건이 이 변경 전 소스에서 실패(조립 규칙 10, 판정 3, envelope 통합 3, form-foundation 1). - GREEN: tests/unit·integration·component·features·contract·runtime-schema 253파일 3,199건 통과. 폼: WORKLOG_INVALID를 선언하면 결과 unavailable, 저장 켜짐, 고친 값 저장 fetch 2회, 키 key-1 → key-2. 선언하지 않으면 effect-unknown, 저장 꺼짐, fetch 1회. - 변이: 실행기의 멱등성·표 code 무시 제거, 조립의 멱등성 규칙 제거, 목록 복사 제거, 실행기가 목록을 넘기지 않음 모두 검출. 보존 조건 M5·M10·M24도 계속 검출. - check:types, lint, check:registries, check:architecture, verify:documentation 통과. Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-01 Refs: docs/reviews/2026-11-03-maturity-review/08-presentation.md 08-01 |
||
|
|
37615072e9 |
fix(http): 백엔드가 정한 5xx 결과 불명 답을 분류기와 상관없이 고정한다
문제 Envelope 판정 표가 정하는 5xx는 503 IDEMPOTENCY_UNAVAILABLE 하나다. 짝 백엔드 http-contract.md가 직접 정한 다른 답 셋은 기능의 classifyProblem이 정한다. - §2 500 IDEMPOTENCY_RECOVERY_REQUIRED: 이전 시도의 효과를 증명할 수 없다. - §2 503 IDEMPOTENCY_COMPLETION_UNKNOWN(백엔드 bbe944bd): 작업은 돌았고 결과 기록이 실패했다. 같은 키로 나중에, 새 키 금지. - §4 503 REQUEST_TIMEOUT: 비동기 요청이 시간을 넘겼고 처리가 계속될 수 있다. 분류기가 5xx를 NOT_APPLIED로 보면 셋 다 SERVER_FAILURE/NOT_APPLIED가 되고, retryBudget이 있으면 실행기가 다시 보낸다. 폼은 "다시 시도"를 새 키로 연다(리뷰 실험 X-F). 백엔드가 "새 키 금지"라고 한 요청이다. 고른 방법 backend-envelope.ts에 MAYBE_APPLIED_ANSWERS(code → status)를 두고 IU와 같은 줄에 셋을 더했다. status와 code가 함께 맞을 때만 MAYBE_APPLIED다. MAYBE_APPLIED는 retryHint를 끄므로 자동 재전송이 없고, 코디네이터가 키를 붙들어 결과 불명 화면의 재전송이 같은 키로 나간다. 자동 같은 키 재전송은 지금처럼 KEYED의 503 IU뿐이다. 버린 대안 RECOVERY_REQUIRED에 "재전송 불가" 표시를 실어 화면 버튼을 숨기기(리뷰 최소 개선의 뒷부분): 완료 기준 밖이고 바인딩·코디네이터·화면을 함께 바꾼다. 같은 키 재전송은 백엔드가 다시 실행하지 않고 같은 500이나 재생으로 답한다. 남은 문제로 보고한다. 위험·한계 500 DB_COMPLETION_UNKNOWN(백엔드 error-codes.yaml, http-contract.md 밖)은 넣지 않았다. 계속 분류기가 정한다. 검증 - RED: backend-envelope 단위 3건, envelope 통합 4건(LENIENT 분류기 세 code의 effect, retryBudget 2에서 fetch 1회·같은 키) 실패. - GREEN: tests/unit·integration·component·features·contract 250파일 3,121건 통과. check:types:app·test, eslint, verify:documentation 통과. - 매뉴얼 02 4절, 계약 문서 6.1절, descriptor 주석에 네 답을 적었다. Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-04 Refs: docs/reviews/2026-11-03-maturity-review/README.md 10.6 |
||
|
|
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 |
||
|
|
a144b575e5 |
fix(contracts): FE-REG-ENV 런타임 행의 필수 여부·기본값을 스키마와 맞춘다
문제
FE-REG-ENV 런타임 행 13개 중 5개의 required·defaultValue가 실제 V2
runtime config 스키마(runtimeConfigV2ArtifactSchema)와 다르다.
- TELEMETRY_ENABLED: 행 기본값 false / 스키마 필수, 기본값 없음
- AUTH_MODE: 행 기본값 "external" / 스키마 기본값 없음
- RELEASE_MANIFEST_URL: 행 required true / 스키마 선택(기본값 있음)
- CAPABILITY_OVERRIDES: 행 기본값 null / 스키마 기본값 네 항목 DEFAULT
- FEATURE_OVERRIDES: 행 기본값 null / 스키마 기본값 {}
d0414c8의 테스트는 스키마 키마다 행이 있는지만 본다. 스키마에 없는 런타임
행도, 값이 다른 행도 통과한다. 이 레지스트리는 기준선 호환 검사 대상이라
틀린 값이 계약으로 굳는다. AUTH_MODE를 빼도 external이 된다고 읽으면
부팅이 스키마 오류로 멈춘다.
고른 방법
- env-registry-coverage에 두 방향을 더한다. 스키마가 읽지 않는 런타임 행은
실패한다. 각 행의 required·defaultValue는 스키마 필드에 undefined를 넣은
결과(실패 = 필수·기본값 없음, 성공 = 선택·그 값)와 같아야 한다. 차이는
키·행 값·스키마 값을 한 줄로 보인다. 제품 키(PRODUCT_*)도 같은 검사를
받는다.
- 5개 행을 스키마에 맞춘다. 두 override 기본값은 객체라 governance의
defaultValue 타입에 object를 더했다.
- ENV_REGISTRY 주석에 두 칸의 뜻(null = 스키마가 기본값을 주지 않음)을
적었다.
버린 대안
- 행의 required·defaultValue를 스키마에서 계산해 채우기: 손으로 맞출 일이
사라지지만 env.ts가 zod 스키마를 import해야 한다. env.ts는 부팅 경로
(getBuildConfig)에 있어 초기 청크에 zod 스키마가 끌려 들어간다.
위험·한계
- RELEASE_MANIFEST_URL required true→false는 breaking 칸 변경이고
governance fieldTypes도 바뀌어 기준선을 다시 승인했다.
- 스키마 superRefine의 조건부 필수(TELEMETRY_ENABLED면 TELEMETRY_ENDPOINT)는
행에 표현하지 않는다.
검증
- RED: 새 대조 테스트가 위 5개 행을 정확히 보고하며 실패했다.
- GREEN: env-registry-coverage 3건 통과. 변이: 스키마 REQUEST_TIMEOUT_MS
기본값만 20,000으로 바꾸면 실패, 스키마 필드 없는 제품 행을 더하면 실패.
- check:registries(재승인 뒤 compatibility=none), run-vitest related
(env.ts, governance) 18파일 154건, registry-governance·product-composition
23건, check:types, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/13-build-release-supply-chain.md 13-04
Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md P-07-05
|
||
|
|
61f70cb9b8 |
fix(contracts)!: 쓰기 operation의 SAFE 재시도 의미를 조립에서 거절한다
문제 설계 정본 8.3은 SAFE를 "GET/HEAD; 보낸 뒤 network 실패에도 재시도 허용" 으로 정한다. 실행기는 그 규칙대로 SAFE면 보낸 뒤 응답을 잃어도 다시 보낸다(http-retry-lifecycle.ts canRetryTransport). 그런데 조립 검사는 쓰기가 SAFE인지 보지 않는다. 생성된 뼈대 descriptor가 GET·SAFE· retryBudget 2이고, 매뉴얼은 쓰기를 더할 때 이 파일을 고쳐 쓰라고 한다. retrySemantics를 바꾸지 않으면 POST가 조립을 통과하고, 응답을 잃은 생성 요청이 최대 두 번 더 나간다(리뷰 실험 X-E: fetch 2회, 결과 SUCCESS). V2에도 이 규칙은 없었다. 고른 방법 assertHttpContract의 쓰기 가지(GET·HEAD 밖)에서 retrySemantics가 SAFE면 operation·method와 고를 값(IDEMPOTENT·KEYED·NEVER), 매뉴얼 절을 담아 거절한다. 매뉴얼 02 3절 "틀리면"에 같은 문장을 더했다. 버린 대안 실행기에서 쓰기의 SAFE를 NEVER처럼 다루기: 잘못 적은 계약이 조용히 다른 뜻으로 돈다. 조립 때 알리는 쪽이 고칠 곳을 바로 보여 준다. 위험·한계 쓰기를 SAFE로 적은 다운스트림은 부팅에서 실패한다. 의도한 실패다. 실행기를 조립 없이 직접 부르는 테스트 경로는 이 검사를 거치지 않는다. 검증 - RED: tests/unit/external-contract-runtime.test.ts의 POST·PUT·PATCH·DELETE × SAFE 4건 실패(조립 통과). - GREEN: 같은 파일 23건 통과. GET·SAFE와 PUT·IDEMPOTENT는 그대로 조립된다. - tests/unit·integration·contract·features·runtime-schema 214파일 2,904건 통과. check:types:app·test, eslint, verify:documentation 통과. BREAKING CHANGE: POST·PUT·PATCH·DELETE operation에 retrySemantics "SAFE"를 쓰면 composeContractContributions가 거절한다. 서버 보장에 맞춰 IDEMPOTENT, KEYED(commandRecovery 필요) 또는 NEVER(retryBudget 0)로 바꾼다. Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-03 |
||
|
|
08ed0a088d |
fix(contracts)!: FE-REG-API 행에 status 목록·상한·재시도 예산·검증 생략을 담는다
문제 V2 행과 V2/V3 parity 테스트를 지운 뒤 FE-REG-API 행은 descriptor에서 12칸만 뽑는다. acceptedStatuses, emptyBodyStatuses, 바이트 상한, 마감, retryBudget, traffic, commandEffect, commandRecovery, 검증 생략 표시는 행에 없다. 그래서 생성 API의 acceptedStatuses를 [200, 201]에서 [201]로 줄여도 check:registries가 통과한다(실험 X2). 이전 커밋 d99301b에서는 같은 변경이 breaking 증거 누락으로 실패했다. 응답 상한·마감 변경은 기록에서 사라졌고 (X3·X6), problemSchema는 breaking 칸이 아니어서 problem 검증기 id를 바꿔도 behavior-change로 통과했다(X4). 짝 백엔드는 생성에 201, 본문 없는 응답에 204를 쓴다. 이 status를 빼면 배포 뒤 그 API가 모두 실패한다. 고른 방법 - projectApiOperationRows가 함수 밖의 descriptor 값을 모두 뽑는다: acceptedStatuses, emptyBodyStatuses, unvalidated(검증을 건너뛰는 검증기 칸 이름: input·output·problem), requestByteLimit, responseByteLimit, totalDeadlineMs, retryBudget, traffic, commandEffect, commandRecovery. - commandEffect는 함수를 빼고 데이터만 남긴다: classifyStatus가 있는지 (classifiesStatus)와, descriptor가 이름을 붙였을 때만 refusedBeforeWrite 목록. refusedBeforeWrite는 다른 작업에서 더해지는 선택 칸이라 구조로 읽고, 없으면 행에도 없다. - governance: problemSchema와 unvalidated를 breakingFields에 넣는다. status 배열은 breakingFields에 넣지 않는다. 분류기가 배열에서 값이 빠지면 이미 allowed-value-removed breaking으로 본다. breakingFields에 넣으면 status를 더하는 것(전에 받던 응답을 모두 계속 받는 변경)까지 증거를 요구한다. 숫자 칸·traffic·command 칸은 behavior-change로 기록한다. - 매뉴얼 01 9단계에 무엇이 breaking이고 무엇이 behavior-change인지, descriptor 함수는 행에 없다는 것을 적었다. 버린 대안 - descriptor 전체(함수 제외)를 투영: policyId·diagnosticsOperation까지 기준선이 흔들려 리뷰 잡음만 는다. 둘은 wire 값이 아니다. - V2/V3 parity 테스트 부활: 사본이 다시 둘이 된다. - 숫자 칸 감소를 breaking으로: 분류기에 방향 규칙이 없고, 상한·마감 조정은 자주 하는 운영 값이다. 기록만 하고 PR에서 본다. 위험·한계 - governance 계약(requiredFields·fieldTypes·breakingFields)이 바뀌어 기준선을 다시 승인했다. 다운스트림은 동기화 때 재승인 1회가 필요하다. - FE-REG-SCHEMA에 problem 스키마 행이 없어 problemSchema는 참조 검사 대상이 아니다. breaking 칸으로만 잠근다. - classifyProblem이 무엇을 NOT_APPLIED로 보는지는 함수라 기록되지 않는다. 검증 - 기준선 재승인 뒤 실험 재실행(check:registries): X2 [200,201]->[201] 실패(acceptedStatuses:allowed-value-removed 증거 누락), X4 problem 검증기 id 변경 실패(problemSchema:field-changed 3건), X5 GET 출력 검증기 생략 실패(unvalidated:field-changed), X3 응답 상한·X6 마감 변경은 behavior-change로 통과하고 스냅샷에 남는다. - tests/unit/api-operation-rows.test.ts: 새 칸 고정, refusedBeforeWrite 있음·없음, governance JSON으로 분류한 8가지 변경. - run-vitest related(api-operations.ts, governance) 21파일 156건, registry 테스트 4파일 63건, check:registries:compatibility-fixtures, check:types, eslint, verify:documentation 통과. BREAKING CHANGE: FE-REG-API governance 계약이 바뀌어 다운스트림의 check:registries가 FE-REG-API:$contract:* contract-field-changed로 실패한다. 동기화 뒤 REGISTRY_BASELINE_OWNER·REGISTRY_BASELINE_REASON을 주고 update:registry-baseline을 한 번 돌린다. Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-01 Refs: docs/reviews/2026-11-03-maturity-review/README.md 3절 |
||
|
|
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
|
||
|
|
e4caafda30 |
fix(contracts)!: 읽기 operation은 SAFE·IDEMPOTENT일 때만 조립한다
문제 GET에 `retrySemantics: "KEYED"`(commandRecovery 없음)나 `"NEVER"`를 적어도 계약 조립이 통과하고 FE-REG-API 행에 그 값이 남는다. KEYED 복구 descriptor 검사가 쓰기 분기 안에만 있기 때문이다. 실행기는 이 GET을 쓰기로 보지 않아 재시도 없는 읽기로 돌린다. 매뉴얼은 "읽기(GET)는 늘 SAFE"라 적는다. V2 `defineRestOperation`은 조회에 SAFE·IDEMPOTENT만 허용했는데 V2 삭제 때 이 규칙이 V3로 옮겨지지 않았다(실험 R1). 고른 방법 assertHttpContract의 읽기 분기에서 GET·HEAD의 retrySemantics가 SAFE나 IDEMPOTENT가 아니면 method와 값을 담아 거절한다. realtime snapshot 바인딩이 요구하는 짝(GET + SAFE·IDEMPOTENT)과 같은 어휘다. 매뉴얼 02 3절 "틀리면"에 거절 문구를 더했다. 버린 대안 - 레지스트리 governance의 allowedValues로 막기: method별 허용값을 표현할 칸이 없고, 조립(부팅 경로)이 아니라 check:registries에서만 걸린다. 위험·한계 - GET·HEAD를 KEYED나 NEVER로 적은 다운스트림 descriptor는 부팅에서 계약 조립 실패가 된다. 템플릿 안에는 그런 descriptor가 없다(grep). - 쓰기의 SAFE 금지(03-03)는 이 커밋 범위가 아니다. 검증 - RED: tests/unit/external-contract-runtime.test.ts의 GET·HEAD × KEYED·NEVER 4건이 실패(조립 통과)했다. - GREEN: `run-vitest related src/contracts/external-contract-runtime.ts` 105파일 950건 통과. check:types, eslint, check:registries, verify:documentation 통과. BREAKING CHANGE: GET·HEAD operation의 retrySemantics가 KEYED나 NEVER이면 계약 조립이 CONTRACT_CONTRIBUTION_INVALID로 실패한다. SAFE(재시도 허용)나 IDEMPOTENT로 바꾼다. 재시도를 막으려면 frontend.retryBudget을 0으로 둔다. Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-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절)에 적는다. |
||
|
|
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에 넘긴다. |
||
|
|
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.
|
||
|
|
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(
|
||
|
|
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. |
||
|
|
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(
|
||
|
|
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 |
||
|
|
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
|
||
|
|
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 통과.
|
||
|
|
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로 쟀다.
|
||
|
|
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 통과.
- 회귀(
|
||
|
|
e98a980dff |
fix(storage): pulse 키를 외부 소유로 적어 StoragePort가 거절한다 (05-01)
문제: registry의 CACHE_INVALIDATION_PULSE 행은 backend localStorage,
valueCodec opaque-string-v1이다. 실제로 이 키에 쓰는 쪽은 cross-context
어댑터이고 envelope 없는 wire JSON을 setItem으로 바로 쓴다. 그래서
StoragePort로 read하면 Web Storage 어댑터가 값을 손상 envelope로 보고
물리 키를 지우고, write하면 envelope 문자열로 덮어써 수신 탭이 버린다.
고른 방법: StorageBackend에 "external"을 더하고 pulse 행을
backend external, valueCodec none으로 바꾼다. getStorageDefinition이
external 키를 던지므로 어댑터의 read/write/remove는 물리 키를 건드리지
않고 *_UNAVAILABLE 실패를 돌려준다. defineStorageKey는 external 키에
codec이 붙으면 거절해 같은 거짓 행이 다시 생기지 않게 한다. 물리 키
문자열 ca-frontend:cache-invalidation:v1:pulse와 wire 형식은 그대로다.
registry-governance의 backend 허용값에 external을 더하고, breaking
필드 변경 두 건은 registry-change-evidence에 근거를 남긴다(baseline
재승인 대신 기존 08-13·F-6과 같은 evidence 방식).
버린 대안:
- 행 위 주석만: 가장 싸지만 StoragePort 호출을 막지 못한다.
- cross-context 어댑터가 StoragePort로 쓰게 함: storage 이벤트의
newValue 형식이 바뀌어 이미 배포된 탭과 서로 못 읽는다.
위험·한계: StoragePort 공개 시그니처는 그대로다. StorageBackend
유니온에 값이 하나 늘어(추가만) exhaustive switch를 쓰는 다운스트림은
분기를 더해야 한다. check:registries 결과는 compatibility=breaking
(evidence로 통과)다. 기본 구성에는 이 키를 StoragePort로 쓰는 호출이
없어 실제 동작 변화는 없다.
검증:
- RED: storage-registry "refuses the externally owned pulse key..."가
"expected { ok: true, value: undefined } to match object { ok: false }"
로 실패(손상 discard 경로), codec 거절 테스트는 "expected [Function]
to throw an error"로 실패.
- GREEN: 같은 파일 23/23 통과.
- 회귀: storage-registry, registry-governance, cross-tab-invalidation,
contract-registry-lookup, browser-security, runtime-adapters,
release-mismatch-recovery 7파일 87/87 통과. tsc app·test 통과,
eslint 통과, check-registries PASS, verify-documentation-readiness
PASS_SCOPED. check:architecture는 pnpm 실행을 요구해 미실행.
Refs: docs/reviews/2026-11-01-maturity-review/05-adapters-storage-kernel.md
|
||
|
|
340acc55e9 |
Merge lane/G: contracts (07-02~07-07, 13-10, F-3, F-6, F-7)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
96cf513485 |
Merge lane/F: service worker / web push (06-01~06-10, F-8)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
9dc95ca066 |
fix(contracts): set zod jitless before any schema is built so the production csp sees no eval (F-7, 13-08)
zod probed Function("") on its first object schema, which the production CSP
(no unsafe-eval) reported on every boot. Schema code now imports z from
src/contracts/zod.ts, enforced by a dependency-cruiser rule, and the CSP smoke
drops its init-script workaround.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
||
|
|
f2e14af0a8 |
fix(service-worker): report a drain timeout as CLIENT_DRAIN_TIMEOUT (06-07)
The worker sent ACTIVATE_REJECTED for a client refusal, a drain timeout and a failed skipWaiting() alike, so the page blamed a dirty tab. Two worker reply kinds now carry the timeout and the commit failure. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
063375ed04 |
fix(contracts): fail public builds without VITE_BUILD_ID and record the local default (F-6, 13-15)
ENV_REGISTRY called VITE_BUILD_ID required with no default while every reader fell back to local-build. Staging and production builds now fail without it; local builds keep the placeholder, and the registry records that default. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> |