a135fa8a09f9b88b7ada4dcb2ab65efe096ca314
222
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
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 |
||
|
|
f485e51e21 |
feat(bootstrap): 제품이 세션과 함께 닫을 것을 scopeParticipants로 넘긴다
문제: browser-files runtime은 세션을 모르고, 닫는 수단은 runtime.dispose() 하나다. 설계 문서는 로그아웃·계정 전환에 "server-state scope reset participant로 dispose()를 등록하라"며 템플릿 소유 파일 runtime-adapters.ts를 가리키는데, 매뉴얼은 제품이 그 파일을 고치지 않는다고 한다(09-02). 제품 확장 지점 composeProduct는 부팅 때 한 번 불리고, context에 participant 등록도 lifecycle 구독도 없다. 그래서 연결하지 않으면 이전 사용자가 고른 File, preview blob URL, 진행 중 download가 다음 세션까지 남는다(공유 기기에서 이전 사용자 파일이 메모리와 다운로드 폴더에 남을 수 있다). 고른 방법(리뷰 5.3절 (다) + 레시피 예제): - ProductComposition에 선택 칸 scopeParticipants(ProductScopeParticipant: label, close)를 둔다. 템플릿은 scope reset의 §10.6 10단계(offline lease 해제) 자리에 "product" participant 하나를 두고, composeProduct가 돌려준 것을 순서대로 부른다. 하나가 실패해도 나머지를 부르고, 실패가 있으면 template participant와 같이 READY로 가지 않는다(FAILED). composeProduct는 scope가 생긴 뒤 불리므로(context가 fence를 쓴다) 이 자리를 미리 만들고 나중에 채운다. - recipes/frontend-capabilities/browser-file-session-capability.ts: 기능에는 runtime 대신 current() getter를 주고, participant가 dispose한 뒤 다음 호출에서 새 runtime을 만든다. indexeddb 레시피와 같은 자리다. - 설계 문서와 매뉴얼 03 C절이 이 방법을 가리킨다. 제거 드릴이 새 레시피 파일도 같이 지운다. 버린 대안: (가) 문서만 고침 — feature presentation은 adapter를 만들 수 없어 제품마다 factory를 다시 설계한다. (나) context에 lifecycle 구독 위임 — FENCED → participant → READY 순서와 "실패는 READY를 막는다"를 제품이 직접 지켜야 한다. (라) runtime이 세대 AbortSignal을 받음 — adapter가 세대를 알게 되고 다른 opt-in runtime도 따로 받아야 한다. 위험·한계: - 제품 계약 표면이 하나 는다(선택 칸이라 기존 제품 파일은 그대로 컴파일된다, [계약]). - 기능은 current()를 작업마다 불러야 한다. 이전 세대에서 받은 runtime을 들고 있으면 UNAVAILABLE을 받는다. FENCED 동안 current()를 부르면 다음 세대 runtime이 미리 만들어진다(빈 runtime이라 이전 사용자 데이터는 없다). - app dispose(infrastructure.dispose)는 제품 participant를 부르지 않는다. - 실제 브라우저 2탭 로그아웃 E2E는 없다(조립된 화면이 없다). - scripts/test-browser-file-storage-runtime-removal.ts는 02-06 담당 작업도 고칠 수 있는 파일이다. runtimePaths에 한 줄만 더했다. 검증: - RED: tests/recipes/browser-file-session-capability.test.ts가 계정 전환 뒤에도 이전 runtime의 readRange가 ok로 실패. - GREEN: 같은 테스트에서 계정 전환 뒤 ① 이전 runtime readRange UNAVAILABLE ② 진행 중 bounded download ABORTED, handoff 0회 ③ 새 세대 runtime의 파일 선택 SELECTED. tests/unit/runtime-adapters-product-scope- participants.test.ts 2건(순서, 실패 시 FAILED와 나머지 실행). - 변이 4개(등록 누락, 실패 삼킴, 첫 실패에서 멈춤, 레시피 dispose 누락) 모두 새 테스트가 잡았다. - runtime-adapters 관련 unit 3파일 + tests/recipes 47건 통과. check:types, 바꾼 파일 eslint, check:architecture, verify:documentation 통과. Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 02-01 |
||
|
|
f3fd10f17c |
docs(manual): 짝 백엔드에 처음 붙이기 절을 더한다
문제: 제품이 짝 백엔드에 처음 붙을 때 볼 문서가 없다. owner 작성자는 SessionGateway 주석, subject·scope fence 규칙, R-3.2, recover 규약을 여러 파일에서 모아야 하고, 백엔드가 무엇을 주고 무엇을 안 주는지(realm의 브라우저 client, 로그인·로그아웃·세션 엔드포인트)는 백엔드 코드를 읽어야 안다. 고른 방법: docs/manual/04-paired-backend-session.md를 새로 둔다. - 두 모드 비교표와 근거 위치(백엔드 bbe944bd의 SecurityConfig, security.yml, application-local.yml, realm JSON). - 공통 준비: AUTH_MODE external, 백엔드 local CORS 출처 http://localhost:3000에 맞춘 dev 포트, owner context 필드, recipe는 복사(import 금지). - jwt: 흐름도, realm에 더할 public client JSON(audience mapper 포함), 제품 설정 키 OIDC_ISSUER·OIDC_CLIENT_ID, product-composition 예시, 하지 않는 것(새로고침 로그아웃, ID token 서명, id_token_hint). - redis-session: 흐름도, 제품이 더할 엔드포인트 셋과 CSRF 토큰 읽기, 프로필을 product-contracts.ts에 옮겨 적는 이유, 예시, 같은 host 조건. - 상태 전이 표, 확인 방법(실제 백엔드 e2e는 아직 없음), 증상별 원인. 매뉴얼 README·02 §5, starter-experience·foundation·optional-adapter- recipes에는 위치만 가리키는 줄을 더했다. 백엔드 표는 복사하지 않고 위치만 적었다(매뉴얼 README 규칙). 위험·한계: 백엔드 설정이 바뀌면 이 문서가 낡는다. 기준 커밋을 문서 첫머리에 적었다. Keycloak client JSON은 실제 Keycloak에 넣어 보지 않았다. 검증: verify:documentation PASS_SCOPED(새 문서와 고친 문서 모두 경로· 명령·게이트 ID 누락 0). Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-03 |
||
|
|
631ce339b9 |
fix(http): 실패 Envelope의 meta.traceId를 AppFailure.traceId로 싣는다
문제
AppFailure와 createFailure는 traceId를 받는다. 이를 채우던 곳은 V2
client.ts의 Envelope meta.traceId였고, 048f490이 V2를 지운 뒤 src에서
traceId를 넘기는 곳이 없다. 빈 칸을 믿고 만든 화면·진단 코드는 늘
undefined를 받는다. 짝 백엔드는 모든 실패 Envelope의 meta에 W3C trace id를
싣는다(http-contract.md §1).
고른 방법
- readFailureEnvelope가 error와 함께 meta.traceId를 돌려준다. 값은 이미
meta 스키마의 id 문법([A-Za-z0-9._:-]{1,128})을 통과한 것이다.
- 실행기가 그 값을 PROBLEM 결과의 SafeResponseMetadata.traceReference에
싣고, 바인딩이 AppFailure.traceId로 옮긴다. requestId 경로(반사 헤더 →
보낸 id)는 그대로다.
- 계약 문서 5절의 correlation 문단에 한 줄 더했다.
버린 대안
traceId를 타입에서 지우기(리뷰의 다른 선택지): 다운스트림이 쓰는지 확인이
필요하고, 백엔드가 이미 주는 지원용 id를 버린다.
위험·한계
- Envelope operation의 실패 응답만 채운다. 성공 뒤 매핑 실패, 전송 실패,
Envelope 없는 operation은 traceId가 없다.
- 텔레메트리에는 싣지 않는다(요청 단위 값).
- 같은 발견의 VD-23 401 문장은 다른 작업 몫이라 건드리지 않았다.
검증
- RED: envelope 통합 1건 실패(404 실패의 traceId 없음).
- GREEN: meta.traceId가 있으면 그 값, 없으면 칸 없음. tests/unit·
integration·component·features·contract·runtime-schema 253파일 중 252파일
통과. 남은 1건(provider-guardian-transaction "cleans a linked raw inode")은
이 기계의 inotify 한도(ENOSPC watch)로 단독 실행에서도 실패하며 이 변경과
무관하다.
- check:types, lint, verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-06
|
||
|
|
49a09868ad |
feat(http): Envelope 목록의 meta.page를 mapSuccess에 넘긴다
문제
짝 백엔드는 페이지 목록의 전체 수·페이지 번호를 meta.page(number·size·
total·sort)에 싣는다(http-contract.md §1). 프론트 Envelope 읽기는 meta에서
id 셋만 남기고 data만 꺼낸다. 그래서 목록 기능은 첫 페이지(기본 20개)만 받고
전체 수를 모른다. 생성된 목록 화면의 "총 N개 항목"은 배열 길이라 페이지
크기를 전체 수처럼 보인다(리뷰 실험 X-G). 우회하려면 responseEnvelope를 빼야
하고, 그러면 Envelope 실패 판정을 함께 잃는다.
고른 방법
- backend-envelope.ts: meta에 page 스키마(정수, number·total 0 이상,
size 1~100, sort 문자열 또는 null). 범위 밖이면 page만 버리고 응답은 읽는다.
readSuccessEnvelope가 data와 함께 page를 돌려준다.
- 실행기의 SUCCESS 결과에 선택 칸 page. outputValidator는 지금처럼 data만
본다.
- 바인딩: mapSuccess(value, context)의 두 번째 인자 FeatureHttpSuccessContext
{ page? }. 한 인자짜리 기존 mapSuccess는 그대로 맞는다.
- 배럴에서 EnvelopePage·FeatureHttpSuccessContext 타입을 낸다.
- 계약 문서 4.1절에 meta.page 경로와 "bulk results는 지원하지 않는다", 7절에
"짝 백엔드는 offset meta.page"를 적었다.
버린 대안
- outputValidator에 { data, page }를 넘기기: 기존 기능 스키마가 모두 깨진다.
- 기능 스키마가 Envelope 전체를 읽기: 실패 판정을 잃는다.
- page가 범위 밖이면 응답 전체를 거절: meta의 모르는 키는 무시한다는 백엔드
§1 규칙과 어긋난다.
위험·한계
- 생성기(create-feature.ts)의 목록 화면은 아직 배열 길이를 보인다. 생성기
담당 작업이 page.total을 쓰도록 이어 받는다.
- bulk는 지원하지 않고 문서로만 알린다.
검증
- RED: envelope 통합 3건 실패(mapSuccess가 page를 받지 못함, 정렬 없는
page 2건).
- GREEN: 같은 파일 51건 통과. 범위 밖 page 3건(size 500, number -1, total
1.5)은 page 없이 SUCCESS. tests/unit·integration·component·features·
contract·runtime-schema 253파일 3,209건 통과.
- check:types, lint, check:architecture, verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-02
|
||
|
|
af4ebacb68 |
docs(browser-transfer): presigned 업로드 레시피가 짝 백엔드와 맞지 않음을 적는다
문제: 프론트 업로드 레시피(PRESIGNED_MULTIPART_V1, 브라우저가 object store에 직접 PUT)를 받는 서버가 짝 백엔드 템플릿에 없다. 짝 백엔드는 2026-09-25에 presigned·direct multipart 코드를 지웠고, 파일은 자기 Fileserver가 직접 받는다(POST /v1/files, POST /v1/files:raw, tus). 그런데 서버 handoff 문서는 아직 "서버 구현 대기", "이후 서버 template에서 구현" 이라고 적고, docs/manual에는 업로드 언급이 없다. 팀은 조립 단계에서야 짝이 아님을 안다. 고친 방법(리뷰 D1 (다)): - server-file-capability-infrastructure.md 상태 줄을 "짝 백엔드 템플릿은 구현하지 않음(2026-09-25 제거)"으로, 대상을 "제품 backend가 직접 구현" 으로 고치고 짝 아님 안내를 머리에 둔다. - presigned-transfer-and-image-cdn.md 머리에 같은 안내를 둔다. presigned 다운로드와 private Image CDN descriptor 발급 서버도 짝 백엔드에 없다. - 레시피 카탈로그 file-transfer의 fallback에 짝 백엔드 경로(Fileserver POST /v1/files)를 적는다. - docs/manual/02-decision-tables.md에 7절 "파일 업로드"를 더한다. 두 경로 비교와 고르는 기준이다. 매뉴얼 README의 목차 줄도 고친다. 위험·한계: 문서만 바꾼다. 짝 백엔드로 파일을 올리는 프론트 client는 이 커밋에 없다(다음 커밋, D1 (나-1)). 백엔드 매뉴얼에 같은 안내를 적는 일은 백엔드 repo 몫이라 하지 않았다. 검증: - verify:documentation PASS_SCOPED - check:optional-recipes:source PASS (file-transfer 56,084/57,800) Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 01-01 |
||
|
|
4bce8bf379 |
fix(hosting): FE-GATE-019가 후보의 설정·entry와 HTTP/2·압축 전제를 대조한다
문제: (1) live probe는 배포된 release-manifest.json의 buildId·releaseId만 후보와 비교했다. 두 값은 CI run 번호로 만든 이름이라, 같은 run에서 로컬 프로필로 다시 빌드한 release(APP_ENV=local, AUTH_MODE=demo, loopback API)를 올려도 PASS(live)였다(리뷰 실험 E-2c). 공개 대상 승인 (FE-GATE-027)을 받은 것은 후보의 config.json인데, 호스트가 내주는 config.json은 헤더만 보았다. entry script도 호스트의 두 응답끼리만 비교했다. (2) 템플릿은 HTTP/2와 압축을 전제로 초기 청크를 나누고 gzip 바이트로 예산을 재는데, 그 전제가 호스팅 계약에 없고 probe도 보지 않았다. 템플릿 nginx 예시는 http2도 gzip도 켜지 않았다. 고른 방법: - 받은 /config.json을 후보 dist/config.json과 비교한다. 비상 스위치 두 개(CAPABILITY_OVERRIDES, FEATURE_OVERRIDES) 밖의 필드가 다르거나 읽을 수 없으면 FAIL. 규칙은 check-release-admission과 같은 함수 (scripts/lib/runtime-config-switches.ts)로 옮겨 같이 쓴다. - 받은 index.html의 entry script를 후보 index.html의 것과 비교한다. - cache-policy.json에 transport.alpnProtocols(["h2"])와 hashedAsset.contentEncodings(br, gzip, zstd)를 선언한다. probe는 TLS handshake의 ALPN(node:tls, h2와 http/1.1을 제안)과 entry script 응답의 Content-Encoding을 본다. Node fetch는 h2를 지원하는 서버에도 HTTP/1.1로 붙어서 프로토콜은 따로 확인해야 한다. - nginx 예시에 http2 on과 gzip·gzip_types를 넣고, static-delivery.md와 release-cache-rollback.md에 두 전제와 실패 조건을 적었다. 두 수정은 같은 probe 함수와 테스트를 고쳐 한 커밋에 넣었다. 버린 대안: archive SHA를 호스트에 올려 대조하기(호스트에 새 파일 규약이 생기고 일부 파일만 다른 배포는 못 잡는다). HTTP/2를 기록만 하기 (아무도 읽지 않는 경고는 청크를 묶는 결정을 부르지 못한다. 선언을 바꾸면 제품이 끌 수 있다). 위험·한계: HTTP/1.1만 되는 호스트는 이제 FE-GATE-019에서 FAIL한다. 그 제품은 cache-policy.json 선언을 바꾸고 초기 청크를 묶는다. 실제 nginx와 Gitea runner에서는 돌리지 않았다. 슬롯이 후보를 받도록 강제하는 계약 규칙은 다음 커밋(제품 overlay)에 있다. 검증: hosting-probe.test.ts에 같은 이름·다른 config.json → FAIL, 비상 스위치만 다름 → PASS, 읽을 수 없는 config.json → FAIL, 다른 entry → FAIL, ALPN http/1.1·없음 → FAIL, 압축 없는 entry → FAIL, 정책 선언 확인을 더했다(고치기 전 실패). 33건 통과. 로컬 자체 서명 TLS 서버 실험: http2.createSecureServer → "h2", https.createServer → "http/1.1", 인증서 이름 불일치 → ERR_TLS_CERT_ALTNAME_INVALID. verify:hosting-headers(fixture) UNVERIFIED exit 3, deployment-admission 통과. Refs: docs/reviews/2026-11-03-maturity-review/13-build-release-supply-chain.md 13-01, 13-02 |
||
|
|
64f19ac665 |
fix(architecture): zod 하위 경로 import도 src/contracts/zod.ts를 거치게 한다
문제 zod-is-reached-through-contracts-zod 규칙의 to.path가 ^zod$다. src 파일이 "zod/v4"를 import하면 check:architecture가 rc=0으로 통과한다(실험 Z1). 그 모듈은 src/contracts/zod.ts의 jitless 설정보다 먼저 스키마를 만들 수 있고, 그러면 운영 CSP가 zod의 Function 탐침을 부팅마다 보고한다(F-7). 고른 방법 to.path를 ^zod(/|$)로 넓힌다. 그래프 fixture에 "zod/v4"를 import하는 파일과 그것이 거절되는지 보는 회귀 검사를 더했다. layers.md 규칙 표도 고쳤다. 버린 대안 - eslint no-restricted-imports에 zod 패턴 추가: 같은 규칙을 두 도구에 둔다. 경계 규칙은 dependency-cruiser가 정본이다. 위험·한계 - src 안에 zod 하위 경로 import는 지금 없다(grep). 다운스트림이 쓰고 있으면 check:architecture가 실패한다. src/contracts/zod.ts의 z로 바꾼다. 검증 - 수정 뒤: 참조 기능 스키마 파일 import를 "zod/v4"로 바꾸면 "Architecture violation [zod-is-reached-through-contracts-zod]: ... -> zod/v4"로 실패, "zod"도 실패. - 규칙을 ^zod$로 되돌리면 새 회귀 검사 "zod subpath import outside src/contracts/zod.ts is rejected"가 실패한다. - check:architecture(29 regression checks PASS), check:types, eslint, verify:documentation 통과. Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md P-07-06 |
||
|
|
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 |
||
|
|
c3aa5eba35 |
docs(recipes): Service Worker 레시피가 오프라인 셸을 약속하지 않게 한다
문제 catalog의 service-worker-pwa trigger는 "a measured offline-shell requirement"를 설치 조건으로 적고 failureKinds에 offline-fallback이 있다. 레시피 표도 "install/offline shell"이다. 그러나 reference 워커는 navigation을 NETWORK_ONLY로 두고, 사전 캐시에 index.html을 넣지 않으며, 설계는 cached index.html fallback을 금지한다(closed deep design 18.8). catalog를 보고 온 제품은 템플릿 파일을 고쳐야 한다는 것을 뒤늦게 알고, 이후 동기화마다 같은 파일에서 충돌한다(0929 리뷰의 memento 사례). 고른 방법 - 0929/06-03 최소 방향대로 주장을 설계에 맞춘다. trigger에서 오프라인 셸을 빼고 "navigation network-only, offline shell 없음, 별도 제품 capability"를 적는다. failureKinds의 offline-fallback을 offline-navigation-network-error로 바꾼다. - 레시피 3절 표를 고치고, 같은 절에 졸업 경로(넘겨받는 파일 넷, 다시 증명할 e2e 단언과 성질, 동기화 충돌)를 적는다. - 버린 대안: 선택 handler로 오프라인 셸 확장 지점을 만들기. 설계가 금지한 동작이고 재검토 조건(제품 요구)이 아직 없다. 위험·한계 - catalog 문구만 바뀐다. 오프라인 셸을 켜는 확장 지점은 여전히 없다. 검증 - json-schema 테스트 6건 통과, check:remediation-ledger· check:optional-recipe-fixtures PASS, verify:documentation PASS_SCOPED. Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 2절 0929/06-03 |
||
|
|
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 |
||
|
|
c9e7bab2d7 |
test(scale): 기능·context 비용을 따로 재고 초기 JS 기준선을 빌드와 대조한다
문제: (1) 기능당 1 KiB 상한 테스트는 복사본 0개와 1개만 쟀다. 첫 복사본은 새 context(shape-context-0)도 만들어서, 잰 값에 context 비용이 섞였고 상한까지 40 B만 남았다. 넘으면 기능이 커졌는지 context가 비싸졌는지 알 수 없었다. (2) 성능 기준선 숫자는 performance-evidence.md, static-delivery.md, feature-shape-ceilings.json에 손으로 적혀 있었고 현재 빌드와도, 같은 파일 안에서도 서로 달랐다(1101/15-02 재발). (3) 이 테스트는 vitest 안에서 돌아 NODE_ENV=test를 물려받았다. 그래서 픽스처 vite build가 React 개발 빌드를 묶었고, 잰 합계가 운영 빌드 (약 201 KB)가 아니라 약 264 KB였다. 고른 방법: 복사본 0·1·2개를 잰다. 둘째 복사본은 같은 context에 들어가 기능 하나의 비용이고, 첫 복사본에서 그것을 뺀 나머지가 context 하나의 비용이다. 기능은 1 KiB, context는 512 B로 따로 막고 실패 메시지에 잰 값을 넣는다. 기준선은 feature-shape-ceilings.json의 initialJavascript 한 곳에 기계가 읽는 칸으로 두고, 같은 테스트가 빌드와 대조한다(합계 1%, 파일 수 정확히, 기능·context 비용 10%). 기록은 `measure-feature-shape-growth.ts --initial-baseline --write`로 다시 쓴다. 문서는 숫자 대신 그 칸을 가리킨다. 픽스처 명령은 NODE_ENV를 지우고 돈다. 버린 대안: 문서 숫자를 다시 손으로 고치기(두 번 낡았다), 문서에서 숫자를 지우고 bundle.json만 가리키기(예산을 정할 숫자를 보려면 빌드가 필요하다). 위험·한계: unit에 빌드가 하나 늘었다(약 3초). 초기 JS를 움직이는 변경은 기록도 다시 써야 test:unit이 통과한다. 그것이 목적이다. `298201f` 출처별 크기 표와 `ec7435c` HTTP/1.1 측정 표는 날짜가 붙은 측정 기록으로 남겼다. 검증: 기록을 쓰기 전 새 테스트가 실패했다. 기록 gzipBytes를 2% 바꾸면 실패하고 되돌리면 통과한다. 지금 기록: 200,939 B, 파일 25개, 기능 +765 B, context +214 B. feature-shape-growth 7건 통과, verify:documentation PASS_SCOPED. Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-02, 15-04 |
||
|
|
3bc690d3fb |
test(realtime): WebSocket 구독별 초당 event 상한을 테스트로 고정한다
문제 WebSocket 연결은 구독마다 1초 창에 maxEventsPerSecond(256, server가 알린 값과 작은 쪽)를 넘는 event가 오면 EVENT_RATE_EXCEEDED recovery를 요청하고 QUEUE_OVERFLOW로 닫는다. 이를 확인하는 테스트가 없어 검사를 꺼도 모든 테스트가 통과한다(리뷰 변이 R7, 두 라운드째). 설계 11절 상한표에도 행이 없다. 고른 방법 - 상한을 2로 낮춘 연결에서 2개 → 1초 뒤 2개(열림 유지) → 1개 더(닫힘, EVENT_RATE_EXCEEDED)를 보내는 테스트 1건을 더한다. 창 초기화와 상한 값 출처까지 한 테스트가 본다. - 설계 11절 상한표에 행 하나를 더한다. 위험·한계 - 동작은 바꾸지 않았다. 실제 서버 부하로는 확인하지 않았다. 검증 - 새 테스트 통과(websocket-connection 24건). - 변이 3건 모두 검출: 상한 검사 끄기(R7), 1초 창 초기화 삭제, 협상된 상한 대신 256 고정. - 바꾼 파일 eslint 통과. Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 2절 1101/04-03 |
||
|
|
5d0f5ad7f8 |
docs(realtime): heartbeat를 멈춘 WebSocket이 예산을 새로 받지 못함을 적는다
문제 heartbeatEligible()이 false면 WebSocket 연결은 HEARTBEAT를 보내지 않는다. 그러면 HEARTBEAT_ACK가 없고, 이벤트도 없는 조용한 stream은 유효 신호가 없어 reconnect 예산이 초기화되지 않는다(0929 실험 E7). 훅에 주석이 없어 채택자가 이 결과를 코드 두 곳(heartbeat 송신, isReconnectAttemptResetEligible)을 같이 읽어야 안다. 고른 방법 - 0929/04-04의 최소 방향대로 훅 옆에 주석을 달고 설계 5.3 예산 문단에 같은 문장을 더한다. hidden 연결은 닫거나 visible 복귀 때 새 run을 만들라고 적는다. 동작은 바꾸지 않는다. 위험·한계 - 동작 변경이 없다. 주석이 코드와 어긋나면 잡는 검사는 없다. 검증 - 바꾼 파일 eslint 통과. 주석만 바꿨다. Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 2절 0929/04-04 |
||
|
|
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 |
||
|
|
5b2106df25 |
docs(realtime): realtime 레지스트리 세 바인딩의 출처를 레시피에 적는다
문제
realtime 레지스트리는 schemaCodecs·mappers·apiOperations 세 바인딩을
받아 event type과 checkpoint를 대조한다. V2 삭제(
|
||
|
|
615da352b9 |
docs(realtime): 짝 백엔드 실시간 출구와 프론트 transport 대응표를 적는다
문제 짝 백엔드의 실시간 출구는 STOMP-over-SockJS 채널(/ws, /topic 구독 1개, Map<String,String> 투영, 재전송 없음)과 raw WebSocket 라이브러리 API, NDJSON·JSON text sequence writer다. 프론트 SSE 어댑터는 text/event-stream과 REALTIME_EVENT_V1 envelope을, WebSocket 어댑터는 subprotocol "realtime.v1"을 요구한다. 어느 repo에도 이 불일치와 지금 되는 경로가 적혀 있지 않아, 채택자가 두 repo를 다 읽어야 안다. 고른 방법 - 리뷰의 최소 방향을 프론트 repo 안에서 따른다. 설계 문서에 0.1절을 두고 transport별 대응표(지금 연결되나·이유), push가 필요할 때의 세 길, 재검토 조건을 적는다. 레시피 Realtime 절과 매뉴얼 03 C절에서 한 줄로 링크한다. - 다시 확인한 백엔드 사실(읽기만): 아키텍처 테스트가 MVC SseEmitter를 금지한다(ForbiddenApiArchitectureTest NO_SSE_EMITTER, 결정 D3). StreamMediaType.SSE는 OpenAPI 생성기만 쓴다. subprotocol 협상 코드는 없다. 그래서 첫째 길을 SSE가 아니라 realtime.v1 WebSocket handler로 적었다. - 지금 되는 경로(bounded polling)는 사실로 적고, push 경로는 고르지 않았다. 제품 결정이다. - 버린 대안: desktop-server-git/design-docs/에 쓰기. 이 브랜치 밖이라 함께 합쳐지지 않는다. 필요하면 그쪽에서 이 절을 링크한다. 위험·한계 - 백엔드 사실은 지금 백엔드 HEAD(70fb80bf)를 읽은 것이다. 백엔드가 바뀌면 표가 낡는다. 재검토 조건에 적었다. - 실제 연결은 실행하지 않았다(리뷰와 같음). 검증 - verify:documentation PASS_SCOPED. documentation-readiness· changelog-review-ids 테스트 15건 통과. Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 04-02 |
||
|
|
613c1cfd0c |
fix(http): 필드 목록이 없는 422를 입력 오류로 읽지 않는다
문제
Envelope 실패 해석이 422를 모두 필드 검증으로 본다
(isFieldValidationFailure). 짝 백엔드의 422 IDEMPOTENT_REQUEST_MISMATCH는
"같은 키를 다른 본문으로 보냈다"는 뜻이고 필드 목록이 없다. 그런데 kind가
VALIDATION_REJECTED가 되어 폼이 "입력값을 다시 확인해 주세요."를 띄운다.
사용자는 고칠 것이 없는 입력을 고치라는 말을 듣고, validation-error 상태는
지원 참조도 보이지 않는다. fileserver의 422(INTEGRITY_MISMATCH 등)도 같다.
고른 방법
422는 details에서 필드 목록(safeValidationIssues가 읽는 모양)이 나올 때만
필드 검증으로 본다. 필드 목록이 없는 422의 kind는 UNKNOWN_CLIENT_FAILURE다.
400 IDEMPOTENCY_KEY_INVALID와 같은 읽기다. 폼은 unavailable 상태와 지원
참조를 보인다. effect 판정(표)은 바꾸지 않았다. 422 MISMATCH는 그대로
NOT_APPLIED, 표 밖 422는 그대로 MAYBE_APPLIED다.
버린 대안
IDEMPOTENT_REQUEST_MISMATCH 한 code만 빼기: fileserver 422처럼 필드 목록
없는 다른 422가 계속 입력 오류로 보인다.
위험·한계
422로 필드 오류를 보내면서 details에 목록을 싣지 않는 백엔드는 이제 필드
오류 대신 실패 상태를 보인다. 짝 백엔드는 필드 검증을 400으로 보낸다.
검증
- RED: backend-envelope 단위 1건, envelope 통합 2건(422 MISMATCH·
INTEGRITY_MISMATCH의 kind), form-foundation 1건(결과 unavailable, 문구
없음) 실패.
- GREEN: tests/unit·integration·component·features·contract 250파일
3,114건 통과. details.issues가 있는 422는 그대로 필드 오류다
("keeps the save off after a 422 the backend may have applied").
- check:types:app·test, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/08-presentation.md 08-05
|
||
|
|
a145f30b48 |
fix(web-push): dot segment가 든 registry path를 생성 때 거절한다
문제
registry path는 router base path를 뺀 앱 경로이고, 정상 클릭은
`${appBasePath}${path}`를 URL로 풀어 연다. registry 검사는 `/` 시작,
`//`·`\`·`#` 금지, 같은 origin만 본다. URL parser는 `..`와 `%2e%2e`를
dot segment로 풀기 때문에 scope `/app/`에서 `/../admin`과
`/%2e%2e/admin`이 모두 `https://app.example.test/admin`을 연다(리뷰
실험 ⑤). 검사를 통과한 경로가 앱 밖을 연다.
고른 방법
- safePath가 `new URL(path, base)`의 pathname + search가 입력과 같을 때만
받는다. `..`·`.`·`%2e%2e`(대소문자 무관)는 parser가 바꾸므로 거절된다.
query는 그대로 남는다.
- 버린 대안: 클릭 때 target.pathname이 앱 루트 아래인지 보기. 잘못된
registry가 클릭할 때에야 드러난다. registry는 제품 코드라 생성 시점에
throw하는 쪽이 이르고 작다(리뷰 5.3 (a)).
위험·한계
- 정규화되지 않은 경로(인코딩 안 된 비ASCII 문자, 빈 query `?`)도
거절된다. registry를 쓰는 제품 코드는 아직 없다.
- registry가 서버가 내려주는 런타임 데이터가 되면 클릭 때 검사도 함께
둬야 한다(리뷰 재검토 조건).
검증
- 새 테스트를 옛 코드에 돌림: 5건 실패(RED). 새 코드: web-push 단위
6파일 76건 통과.
- 바꾼 파일 eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 06-02
|
||
|
|
af000673ef |
fix(realtime)!: 서버에 닿지 않은 SSE·poll 실패를 PROVIDER_UNAVAILABLE로 낸다
문제 브라우저는 online인데 서버·프록시만 닿지 않을 때 실패 이름이 transport마다 다르다. SSE는 fetch·reader 거절을 OFFLINE, poll은 execute 거절을 OFFLINE, WebSocket은 error를 PROVIDER_UNAVAILABLE로 낸다. reconnect coordinator는 transport OFFLINE을 backoff로 재시도하고 예산을 다 쓰면 online인데도 OFFLINE으로 끝낸다. 설계 13.1의 OFFLINE 행은 "online hint 뒤 bounded check"라 5.3과 다른 말을 한다. kind로 화면 문구나 조합 판단을 고르면 같은 서버 장애가 SSE에서는 "오프라인", WS에서는 "서비스 이용 불가"가 되고, "OFFLINE이면 online 이벤트를 기다린다"는 조합 코드는 다시 멈춘다(0929/04-01의 모양). 고른 방법 - 리뷰 5.3절 판단대로 어휘를 맞춘다. SSE fetch 거절(CONNECT)과 reader 거절(RECEIVE), poll execute 거절을 PROVIDER_UNAVAILABLE(retryable)로 바꾼다. 이제 OFFLINE은 환경 신호에서만 나온다. - poll은 PROVIDER_UNAVAILABLE을 lease 안에서 재시도하므로, 던지는 execute는 바로 끝나지 않고 backoff로 maxAttempts까지 다시 시도한다. executor가 PROVIDER_UNAVAILABLE을 돌려준 경우와 같은 처리다. - 설계 13.1의 OFFLINE·PROVIDER_UNAVAILABLE 행과 5.3 문단을 고친다. - 버린 대안: 13.1에 OFFLINE의 두 뜻을 적기만 하기. 비용은 1행이지만 조합자가 navigator.onLine을 따로 봐야 원인을 안다. 운영 중인 제품이 없는 지금 어휘를 바꾸는 비용이 가장 작다(리뷰 5.3). 위험·한계 - 배럴로 공개된 SSE 연결·poll coordinator의 결과 kind가 바뀐다. repo 안 소비자는 테스트뿐이다. - 던지는 execute(조합 코드의 버그 포함)는 이제 lease 예산만큼 다시 불린다. 상한은 maxAttempts·maxElapsed 그대로다. - 환경 신호가 늦게 offline이 되는 경우 첫 실패는 PROVIDER_UNAVAILABLE로 보인다. offline 대기는 kind가 아니라 환경 신호로 걸리므로 멈춤은 없다 (before/after 테스트 그대로 통과). 검증 - 바꾼 기대값 3건을 옛 코드에 돌림: 3건 실패(RED). 새 코드: realtime 단위 241건 통과. - check:types 통과, 바꾼 파일 eslint 통과. BREAKING CHANGE: SSE 연결의 fetch·reader 거절과 bounded poll의 execute 거절이 OFFLINE 대신 PROVIDER_UNAVAILABLE(retryable)로 끝난다. poll은 던지는 execute를 lease 안에서 재시도한다. OFFLINE을 서버 장애로 읽던 조합 코드는 PROVIDER_UNAVAILABLE을 함께 본다. Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 04-04 |
||
|
|
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
|
||
|
|
c695898aee |
fix(browser-transfer): 상한보다 긴 Retry-After는 앱에도 retryable:false로 준다
문제: part 단계(BFF 발급, object store PUT)가 상한(maxRetryAfterMs, 기본 30초)보다 긴 Retry-After로 429·503을 받으면 runtime은 기다리지 않고 멈춘다. 그런데 앱에 주는 실패는 retryable:true다. 포트 표대로면 "자동 재시도해도 된다"는 뜻이라, 서버가 45초 기다리라고 한 요청을 앱이 바로 다시 보낸다. 같은 429에 control plane 전송은 retryable:false를 준다. control plane도 전송 상한이 정책 상한보다 크면 retryable:true가 된다. 고친 방법: provider 실패를 앱 실패로 바꾸는 한 곳(stripProviderFailure)이 정책 상한을 받아, 지우는 retryAfterMs가 상한을 넘었으면 retryable을 false로 만든다. control plane 전송이 이미 쓰는 규칙이다. 한 곳에서 하므로 두 단계와 두 factory 상한 조합이 모두 같은 답을 낸다. 포트 주석과 설계 문서(presigned-transfer-and-image-cdn.md 7절)에 같은 규칙을 적었다. 버린 대안: 현상 유지 + 포트 주의 한 줄은 앱이 기다릴 값을 모르므로 지킬 수 없다. 앱 실패에 retryAfterMs를 싣는 안은 공유 타입 BrowserDataFailure를 바꿔 다른 포트까지 퍼진다. 상한 밖 값도 기다리는 안은 한 호출이 끝없이 늘어지지 않는다는 상한의 목적을 깬다(리뷰 5절 D2). 위험·한계: upload()·abort()의 실패 값이 바뀐다. 상한 밖 Retry-After는 RESUME에 retryable:false가 되어, 자동 재시도하던 다운스트림은 사람이 누르는 재시도로 넘어간다. 상한 안 대기, PUT 403 재발급, 발급 401/403 NONE은 바뀌지 않는다(기존 테스트 그대로 통과). 헤더 없는 part 단계 429가 backoff로 재시도하는 차이는 이 변경 범위 밖이다. 검증: - 고치기 전: 새 단언 5건 실패(part 단계 4건, 전송 상한 60초 조합 1건) - 고친 뒤: 영역 단위 테스트 15파일 274건 통과 - check:types, eslint(바꾼 파일) 통과 Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 01-02 |
||
|
|
a65df74046 |
fix(realtime)!: bounded poll을 V3 descriptor에 묶어 실행기 재시도를 막는다
문제 BoundedPollOperationContract는 지운 V2 행의 어휘(contractVersion: 2, protocol, semantics, replayPolicy, retry, transportMaxAttempts, authRecoveryCount, maxCumulativeSleepMs, serverStream)로 된 자기 선언이다. assertBoundedPollOperation은 리터럴만 보고 실제로 실행할 descriptor와 대조하지 않는다. 조합 코드가 execute를 V3 실행기와 기본 GET descriptor(retryBudget 2)로 만들면 503마다 실행기가 두 번 더 보낸다. poll 3회가 요청 9회가 되고, poll 관측에는 1건씩만 보인다(리뷰 실험 P). 고른 방법 - coordinator의 operation을 V3 descriptor(InstalledHttpContract)로 바꾼다. 실행기는 재시도 상한을 그 descriptor의 frontend.retryBudget에서 읽는다 (http-execution-v3.ts retryCeiling). 그래서 생성 때 retryBudget === 0을 요구하면 실행기 옵션 없이 poll 한 attempt가 요청 한 번이 된다. 실행기(src/adapters/http)는 고치지 않았다. - 검사: operationId 일치, method GET·HEAD, retrySemantics SAFE·IDEMPOTENT, retryBudget 0, responseByteLimit 1..8 MiB. execute에 넘기는 maxResponseBytes는 min(policy.maxResponseBytes, responseByteLimit)이다. - V2 리터럴 필드는 모두 지운다. command descriptor·요청 본문은 조립 (composeContractContributions)이 GET·HEAD에서 이미 거절한다. - 버린 대안: (a) ApiOperationRow + HttpExecutionPolicy 두 인자. 행에는 retryBudget이 없고, 실행기가 실제로 받는 것은 descriptor 하나라 같은 객체를 넘기는 쪽이 어긋날 틈이 작다. (b) 실행기에 호출별 재시도 끄기 옵션 추가. 다른 에이전트가 고치는 http 영역을 건드리고, descriptor가 재시도를 허용한다는 사실은 그대로 남는다. (c) 문서에만 적기. 검출이 없다. 위험·한계 - 공개 타입이 바뀐다. repo 안 소비자는 테스트뿐이다. - 조합 코드가 coordinator에 넘긴 descriptor와 다른 객체를 실행기에 넘기면 막지 못한다. 타입 주석과 설계 9.2에 "같은 객체를 넘긴다"고 적었다. 조립된 행은 동결돼 있어 검사 뒤 값이 바뀌지 않는다. - 기능의 기본 GET(retryBudget 2)은 poll에 쓸 수 없다. poll 전용 operation을 따로 등록해야 한다. 검증 - 새 테스트를 옛 코드에 돌림: 21건 실패(RED). 새 코드: 32건 통과. - 실험 P를 테스트로 옮김: 기본 descriptor는 생성 때 TypeError, retryBudget 0 descriptor + maxRetryAttempts 2 실행기 + 503 서버에서 poll 3회 = 요청 3회. - 변이 5건(retryBudget·method·retrySemantics·operationId·응답 상한 검사 삭제) 모두 검출. - check:types 통과, 바꾼 파일 eslint 통과. BREAKING CHANGE: BoundedPollOperationContract를 지운다. createBoundedPollCoordinator의 operation과 assertBoundedPollOperation의 둘째 인자는 V3 descriptor(BoundedPollOperation = InstalledHttpContract)다. 조립된 행(composeContractContributions(...).httpByOperationId.get(id))을 넘기고, frontend.retryBudget을 0으로 둔 poll 전용 operation을 등록한다. execute 안에서는 같은 descriptor를 실행기에 넘긴다. Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 04-01 |
||
|
|
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 |
||
|
|
7e7614fd48 |
fix(cache-storage): 손상 pointer에서도 inspect가 상태와 후보를 보여 준다
문제: inspect()는 active pointer 읽기가 실패하면 그 실패를 그대로
돌려준다. 손상 pointer(CORRUPT_DATA)는 조회·cleanup을 막고 다음
activation이 rollback 없이 덮어쓰는 상태인데, 그 상태를 진단할 유일한
관리 API도 같이 멈춘다. 운영자는 어떤 후보가 남았는지, 다음 activation이
무엇을 덮어쓰고 그 뒤 cleanup이 무엇을 지울지 모른 채 배포한다.
PublicCacheInspection에는 pointer 상태를 담을 칸이 없다.
고른 방법: PublicCacheInspection에 activePointer("NONE" | "READABLE" |
"UNREADABLE")를 둔다. pointer 읽기가 CORRUPT_DATA면 UNREADABLE로 적고
activeReleaseRegistryId는 null로 둔 채 후보 목록을 끝까지 채운다. 일시
오류(UNAVAILABLE 등)는 지금처럼 실패로 돌려준다. activation이 이미 쓰는
"CORRUPT_DATA만 손상으로 본다" 규칙과 같다. recipe fake도 같은 칸을
채운다. 리뷰가 함께 적은 inspect 전용 operation 이름은 공유 operation
union을 바꾸는 일이라 이번에 하지 않았다.
위험·한계: 공개 포트 타입에 필수 칸이 하나 는다. 결과를 읽는 쪽은
그대로지만 이 포트를 직접 구현한 쪽은 칸을 채워야 한다([계약]).
repo 안 소비자는 없다. inspect의 signal·판정 불가(0929/02-02)는
그대로다. service-worker-pwa 번들 9,733 → 9,758 / 10,100 gzip B.
검증:
- RED: public-response-cache-repair.test.ts 새 테스트가 activePointer
없음으로 실패.
- GREEN: 같은 파일 11건 통과(손상 중 inspect ok, UNREADABLE, 후보
r1·r2 verified, 일시 오류는 UNAVAILABLE). cache 단위 3파일 +
tests/recipes 63건 통과. check:types, 바꾼 파일 eslint,
check:optional-recipes:source PASS, verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 02-05
|
||
|
|
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 |
||
|
|
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으로 실행한다.
|
||
|
|
bf86fe5cd0 |
docs(contract): 4.2절의 400·422 행을 짝 백엔드 거절 표에 맞춘다
문제
계약 문서 4.2절은 422를 "field validation"으로 적는다.
|
||
|
|
8c39e77376 |
docs(delivery): 정적 배포 문서에 HTTP/2 서빙 전제를 적는다 (1101/14.4)
문제: 3f9c087은 초기 청크를 묶지 않는 근거로 "템플릿은 HTTP/2 이상으로 서빙한다"를 정했다. 그런데 이 전제는 작업 기록인 performance-evidence.md 에만 있다. 호스팅을 정하는 사람이 읽는 현재 계약 문서(static-delivery.md) 에는 서빙 프로토콜 이야기가 없다. 고른 방법: static-delivery.md 끝에 한 단락을 더한다. HTTP/2 이상으로 서빙한다는 것, HTTP/1.1에서 늦어지는 정도(Fast 3G 약 1초), HTTP/2에서의 차이(100 ms 미만), HTTP/1.1만 되는 제품이 할 일을 적고 측정 기록으로 링크한다. 버린 대안: README의 배포 절에 적기. README는 배포 변수와 명령을 다루고, 호스트 동작은 static-delivery.md가 다룬다. 위험·한계: 수치는 2026-11-03 한 번의 측정이다. 셸이 바뀌면 달라진다. 검증: node scripts/verify-documentation-readiness.ts PASS_SCOPED |
||
|
|
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로 선언한 `/`는 플랫폼 홈이 받는다(
|
||
|
|
27f45233f9 |
test(layouts): 모든 레이아웃의 skip link와 main 하나를 실행으로 검사한다 (1101/14.4)
문제: 라우터는 경로가 바뀔 때마다 `#main-content`로 focus를 옮긴다.
그래서 라우터가 붙이는 모든 레이아웃은 skip link와 `<main id="main-content">`
하나를 그려야 한다. ca16187이 context 레이아웃을 열면서 이 규칙을 타입 주석과
starter-experience.md, fixture로만 지켰다. 레이아웃에서 `<main>`을 빼도
실패하는 테스트가 없다(리뷰 README 14.4 09-03 첫 줄).
고른 방법: 등록된 레이아웃을 읽어 도는 component 테스트
`tests/component/layout-landmarks.test.tsx`.
- 대상: `AppShell`, 설치된 제품(`TEMPLATE_APP_MODULE.contexts`)의 각
`loadLayout`, fixture 제품(`LAYOUT_PRODUCT_CONTEXT_MODULES`)의 각
`loadLayout`. 제품이 `context-layout.tsx`를 추가하면 이 파일을 고치지 않아도
검사 대상이 된다.
- 각 레이아웃을 메모리 라우터에 붙이고 자식 페이지(probe h1)를 그린다.
확인: `main`/`role="main"`이 정확히 하나, 그 id가 `main-content`, 자식
페이지가 그 안에 있음, `href="#main-content"` 링크가 있음.
- fixture의 offline 레이아웃은 청크가 오지 않도록 만든 것이라 id로 뺐다.
버린 대안:
- context-layouts.test.tsx에 넣기: 그 파일은 생성 인덱스를 fixture로 mock한다.
설치된 제품의 레이아웃은 그 안에서 읽을 수 없고, 읽더라도 fixture 레지스트리
아래라 제품 라우트를 가리키는 레이아웃(`routePath`)이 다른 이유로 깨진다.
- `AppRouter`로 레이아웃마다 URL을 열기: 레이아웃마다 파라미터 없는 경로를
골라야 하고 설치된 제품과 fixture를 한 파일에서 돌릴 수 없다.
위험·한계:
- 레이아웃 단독 렌더라 페이지가 자기 `<main>`을 하나 더 그리는 경우는 이
테스트가 못 잡는다. 라우터를 거친 확인은 context-layouts.test.tsx가 fixture로
한다.
- skip link가 첫 focus 대상인지는 보지 않는다.
- 템플릿 자체에는 레이아웃을 선언한 context가 없어, 설치된 제품 쪽은 지금
`AppShell`만 돈다.
검증:
- RED(변이): fixture 레이아웃의 `<main>`을 `<div>`로 바꾸면 4건 중 3건 실패
("expected to have a length of 1 but got +0"). AppShell skip link href를
`#content`로 바꾸면 1건 실패("expected null not to be null"). 둘 다 되돌렸다.
- GREEN: 4건 통과(AppShell, context site, topics, studio).
- tsc test 통과. 새 파일 eslint 통과. verify-documentation-readiness
PASS_SCOPED.
|
||
|
|
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 |
||
|
|
ed0e4b1923 |
docs(contract): 거절 code별 적용 여부를 백엔드 코드로 정한다 (1101/14.4)
문제
"검증 거절은 적용 안 됨" 판정(
|
||
|
|
f3b87b3f02 |
docs: 생성한 기능이 짝 백엔드 Envelope를 읽는다는 결정과 결과를 적는다
문제 매뉴얼 01 3단계, CHANGELOG 미출시 절, 리뷰 README 14.3은 "생성한 기능은 짝 백엔드 응답을 그대로 읽지 못한다, 해결 방법은 정하지 않았다"를 알려진 제한으로 적는다. 7db32e1로 V3가 responseEnvelope: "ENVELOPE_V1" operation의 Envelope를 읽게 되어 이 문장들이 틀렸다. 매뉴얼 02 4절의 503 흐름도와 계약 문서 4.1절도 "V3는 Envelope 없이 DTO를 검증"으로 적는다. 고른 방법 - 리뷰 README 14.6: 선택지 넷(V3 operation 단위 / provider 단위 / 백엔드 problem+json 모드 / 기능 스키마가 감쌈)의 판정과 이유, V2와 같은 판정 표, 의도한 차이 세 가지, RED→GREEN·게이트 결과, 남은 것. 14.3 행의 처리 칸은 14.6을 가리킨다. - 매뉴얼 01 3단계: "응답 모양"을 짝 백엔드 Envelope 기준으로 다시 쓰고, Envelope가 아닌 백엔드에 붙이는 순서(responseEnvelope 줄 삭제, problem details 스키마)를 따로 적었다. 알려진 제한 문단은 지웠다. - 매뉴얼 02 4절: 실행기가 먼저 정하는 판정 목록과 바뀐 503 흐름. - CHANGELOG: [계약] 행 하나, 알려진 제한을 남은 차이(참조 기능 미선언, V2와의 차이 셋, e2e 접근성 스펙의 [] 본문)로 바꿨다. - 14.4와 CHANGELOG의 "V3 진단에 problem code가 없다"에 bd83b49가 싣는 범위(멱등성 거절 reason 두 값)와 싣지 않는 것, 그 이유를 적었다. - 계약 문서 4.1절·compatibility.md: Envelope를 읽는 곳을 backend-envelope.ts로 고쳤다. 버린 대안 - 백엔드에 요청 문서 쓰기: (나)를 고르지 않아 요청할 것이 없다. 위험·한계 - 문서의 게이트 결과는 이 커밋 직전 트리( |
||
|
|
0a7fbedca9 |
docs(architecture): 규모 설계서를 현재 계약 문서로 옮긴다 (1101/14-01)
문제: src/platform·src/apps·src/contexts의 구조·소유·예산·실행· 텔레메트리 규칙과 코드 주석 "Spec §N"의 근거가 2026-09-23 설계서 하나에만 있다. 그 설계서는 docs/reviews/ 안의 계획 묶음에 들어 있어 README가 복사 뒤 지워도 된다고 한 범위 안이다. 현재 계약 목록 (docs/README.md §1)에는 src/platform을 다루는 문서가 없다. 고른 방법: 설계서를 docs/architecture/scale-architecture.md로 복사한다 (git mv가 아니라 복사라 이력 묶음은 그대로 남는다). 본문 §1~§55는 영어 원문 그대로 두고 절 번호를 바꾸지 않는다. 맨 위에 상태 머리말을 붙인다: 현재 계약인 범위, 출처(커밋 6f6c48e와 원래 경로, git show로 보는 법), 코드와 달라진 곳을 절 끝 "> 2026-11-03 현재:"로 적는 규칙. 절 상태 표는 현재 계약(코드 참조) 41, 현재 계약 10, 기록만 4 (§40·§51·§53·§54), 미확인 0이다. 코드와 다른 18개 절에 차이를 한두 줄로 적었다(예: §4 최상위 domain/ 없음, §11 TrafficBudget에 deadline 없음, §40 부팅 게이트 없음, §47 CI는 pr 단계만). docs/README.md §1의 세부 규칙 목록에 새 문서를 더한다. 버린 대안: 필요한 절만 새로 쓰기. 68곳 넘는 주석의 절 번호 대응표가 필요해지고 원문과 갈라진다. 이력을 지우지 말라고 정책을 바꾸기 (리뷰 5.1절 (c)). 동기화 비용과 문서 섞임이 그대로 남는다. 위험·한계: 절 대조는 각 절을 가리키는 모듈의 타입·머리 주석·테스트 이름을 읽는 수준이다. 동작을 실행해 확인하지 않았다. 원문의 "Status: Design approved…"와 예정 경로 줄은 머리말로 바꿨다. 예정 경로가 없는 파일을 가리켜 verify:documentation의 경로 검사에 걸리기 때문이다. 이 커밋만으로는 코드 주석이 아직 이름 없는 "Spec §N"이다. 다음 커밋이 바꾼다. 검증: - 본문 비교: 원문 §1 이후와 새 문서 §1 이후의 diff에서 지운 줄 0, "> 2026-11-03 현재" 메모 외에 더한 줄 0 - node scripts/verify-documentation-readiness.ts: PASS_SCOPED (처음 "src/domain"을 백틱으로 적어 FAIL, 문구를 고쳐 PASS) - node scripts/run-vitest.ts run tests/unit/documentation-readiness.test.ts tests/unit/deletable-history-documents.test.ts: 15 passed |
||
|
|
313f9bac3e |
chore(recipes): 레시피 예산을 측정값 + 3%로 정하고 규칙을 적는다 (0929/05-04)
문제: 레시피 번들 예산을 수정마다 100 B씩 올려 왔다. 한도가 늘 직전 측정값이라 예산 초과가 "왜 커졌나"를 묻는 신호가 되지 못했다. 이번 수정 묶음 뒤 offline-indexeddb(37,327 > 36,900)와 realtime(40,902 > 40,900)이 넘었고, file-transfer는 여유가 47 B였다. remediation ledger는 예전 값 56,100을 적지 않아 check:remediation-ledger가 실패하고 있었다. 방법: 리뷰 결정(README 14절 0929/05-04)대로, 측정값 + 3%를 100 B 단위로 올린 값으로 한 번 정한다. 그 뒤 3% 안의 증가는 예산을 고치지 않고, 넘는 증가는 커밋 본문에 이유를 쓰고 같은 규칙으로 다시 정한다. - file-transfer 56,053 → 57,800, offline-indexeddb 37,327 → 38,500, realtime 40,902 → 42,200, service-worker-pwa 9,716 → 10,100 - 규칙·이유·측정 표는 optional-adapter-recipes.md의 예산 절에 둔다. JSON은 주석을 받지 않아서다. - realtime 문서 두 곳은 숫자 대신 정본 위치를 가리킨다. VD-10은 결정 기록이라 그대로 둔다. 버린 대안: 수정마다 100 B 인상(지금 방식), 레시피 예산에서 kernel 제외 (kernel 증가를 놓친다). 위험: 3% 여유 안에서는 회귀가 조용히 쌓인다. 예산 값을 표와 JSON 두 곳에 적으므로, 다음 인상 때 표도 같이 고쳐야 한다(ledger는 check:remediation-ledger가 file-transfer 값을 대조한다). 검증: check:optional-recipes:source PASS(4 budgets), verify:documentation PASS_SCOPED, check:remediation-ledger의 예산 실패 사라짐(TR-02~04 기존 3건은 그대로, 게이트 밖). |
||
|
|
3b7d73ab37 |
docs(contract): 계약 4.1·6절이 백엔드 http-contract.md를 가리킨다 (백엔드 1101/02-01)
문제 docs/architecture/backend-api-and-server-state-contract.md 4.1절(JSON envelope)과 6절(Command와 idempotency)이 백엔드 계약을 직접 다시 적었다. 짝 백엔드가 바뀐 뒤 둘이 어긋난다. - 4.1절 예시는 meta id를 늘 싣고 null 생략 규칙이 없다. - 6절은 같은 키·다른 본문을 409 IDEMPOTENCY_KEY_REUSED로 적는다. 백엔드는 422 IDEMPOTENT_REQUEST_MISMATCH다. 처리 중 409의 retryable·Retry-After, 400 IDEMPOTENCY_KEY_INVALID도 없다. - 4.2절 409 행이 "idempotency fingerprint" 충돌을 409로 적는다. 백엔드 http-contract.md 5절은 이 두 절이 자기 문서를 가리켜야 한다고 적는다. 고른 방법 - 4.1절·6절의 표와 예시를 지우고 백엔드 문서 링크(1절, 2절·4절)와 기준 버전(백엔드 리뷰 2026-11-01 15절 결정, 2026-11-03)만 적는다. 백엔드 변경은 아직 커밋이 없어 SHA 대신 결정 날짜를 적고, 커밋이 생기면 SHA로 바꾸라고 적었다. - 프론트가 그 계약을 읽는 코드 위치만 남긴다. 표를 복사하지 않는다. - 4.2절 409 행에서 멱등성 충돌을 빼고 6절을 가리킨다. 버린 대안 - 프론트 문서의 표를 백엔드 값으로 고쳐 두기: 다음 백엔드 변경에서 다시 어긋난다. 위험·한계 - 링크는 두 repo가 같은 상위 폴더에 나란히 있을 때만 열린다 (../../../clean-architecture-backend-template/...). verify:documentation은 repo 밖 링크를 검사하지 않는다. - 6절에서 지운 권장 IdempotencyRecord와 불변조건은 짝 백엔드가 구현과 문서로 소유한다. 다른 백엔드를 붙이는 제품은 백엔드 문서를 기준으로 삼는다. - 4.2절의 422 행(field validation)은 그대로다. 짝 백엔드는 필드 검증 실패를 400 VALIDATION_FAILED로 보낸다(백엔드 http-contract.md 4절). 이 차이는 이 변경 범위 밖이다. 검증 - node scripts/verify-documentation-readiness.ts: PASS_SCOPED. Refs: clean-architecture-backend-template docs/web/http-contract.md 5절, docs/reviews/2026-11-01-maturity-review/README.md 14.3 |
||
|
|
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
둘)로 나눠야 한다.
- 플랫폼 라우트와 기능 라우트의 같은 경로는 여전히 검사하지 않는다(
|
||
|
|
7450e1f2b3 |
test(features): 기능 추가 테스트에 무효화 topic을 넣고 폴더 밖 수정 표를 고친다 (1101/16-01)
문제
- starter-experience.md "Adding a feature"의 폴더 밖 수정 표가 실제와 다르다.
라우트마다 필요한 수동 a11y 기록이 없고, 어느 검사가 실패하는지도 적지
않는다.
- 이 주장을 지키는 second-api-feature-registries 테스트는 무효화 topic이
없는 기능만 넣는다. 그래서 topic 추가가 기준선 재승인을 요구하던 결함을
보지 못했다.
- http-operation-v2-v3-parity 테스트는 스키마 ID "NoRequest"를 "입력 없음"
표시로 고정해 쓴다. 스키마 ID는 전역이라 두 번째 기능은 다른 이름(예:
OrderNoRequest)을 써야 한다. 그러면 이 테스트가 그 기능의 path·request
스키마를 둘 다 입력으로 세어 실패한다(16-02 작업자 발견).
고른 방법
- 표를 지금 코드 기준으로 다시 썼다. 열은 파일 / 언제 / 없으면 무엇이
실패하나. 리뷰 실험 E의 ①~⑨ 중 이번 라운드 앞 커밋이 없앤 것은 뺐다:
governance allowlist(0929/07-03), 기준선 재승인(앞 커밋, 결정 1), README·
체크리스트 route ID 목록(14-05), 인증 프로필 이름(16-03, EXTERNAL_BEARER
재사용), MSW 카탈로그와 무관한 테스트 3개(16-02). runtime-adapters.ts는
product-composition.ts로 바뀌었다(09-02).
- 남은 것: context 선언, 라우트별 a11y 기록, 경로 파라미터가
:resourceId가 아니거나 빈 배열 응답으로 그려지지 않는 페이지의 e2e a11y
spec, 제품 capability·인증 프로필·설정 키(제품 소유 파일 2개), 선택인
FEATURE_OVERRIDES, 계약 패키지를 npm 의존성으로 들일 때의 의존성 검토
증거. 계약 출처(EXTERNAL_PACKAGE)는 기능 계약의 contractPackages에
선언하므로 폴더 밖 수정이 아니다.
- 표 아래에 레지스트리 추가는 기준선을 바꾸지 않는다는 것, 전역 ID에 기능
접두어를 붙인다는 것, 기능의 MSW 시나리오는 createHttpScenarioHandler로
만든다는 것을 적었다.
- second-api 기능에 무효화 topic·namespace·edge·topicVersion을 더하고,
무효화 그래프 변경 3건이 additive인지 단언한다. 라우트는 0929/07-03이
이미 넣었으므로(SECOND_ITEM_LIST) 더하지 않았다.
- second-api의 통과 codec은 검증을 생략하므로 1101/07-03의
unvalidatedPayload로 만든다.
- parity 테스트는 V2 행에서 입력이 있는 쪽을 읽는다. path 스키마는
pathParameterNames가 있을 때, request 스키마는 requestSource가 "none"이
아닐 때 입력이다. 둘 다 없으면 행의 requestSchema(그 기능의 빈 입력
스키마)를 기대한다.
버린 대안
- 표만 고치기(리뷰 대안 a): 테스트가 계속 좁은 모양만 증명한다.
- 참조 기능의 NoRequest를 ReferenceNoRequest로 바꾸기: FE-REG-API 행의
requestSchema·pathSchema가 바뀌어 기준선 재승인이 필요하고 범위 밖이다.
- parity 테스트에서 이름 끝이 NoRequest인 스키마를 빈 입력으로 보기: 이름
관례에 기대는 규칙이라 다른 이름을 쓰면 다시 깨진다.
- second-api 기능에 V3 기여를 넣어 parity를 그 사본에서 돌리기:
1101/07-02(
|
||
|
|
e1a458081d |
refactor(recipes)!: runtime이 있는 port는 src port를 다시 내보낸다 (0929/05-03)
문제: `recipes/frontend-capabilities/`가 `src/application/ports/`와
같은 이름의 타입 34개를 따로 정의한다(`DurableObjectStorePort`,
`FilePickerPort`, `StorageDurabilityPort`, `TransferProgress`,
`PublicCacheInspection` 등). 7월 이후 runtime port가 바뀌어도(0929
05-01~05-14) recipe 복사본은 한 번도 따라오지 않았다. catalog는 이
복사본을 구현한 fake를 runtime의 fake로 안내해서, 그 fake로 쓴 테스트는
runtime에 없는 resume·quarantine을 전제했다.
고른 방법 (리뷰의 (c)):
- runtime이 있는 port와 그 표면의 타입은 recipe 정의를 지우고
`src/application/ports`의 것을 같은 이름으로 다시 내보낸다. 옛 recipe
port에만 쓰이던 `DurableObjectDataClass`, `DurableObjectIntegrity`,
`DurableObjectRead`, `ObjectStoreRecoverySummary`도 지운다. src에 없는
`DurableObjectId`·`ObjectGeneration` 브랜드와 `as*` 헬퍼는 남긴다(src
port가 그대로 받는다).
- fake는 src port를 `implements`한다.
- 파일 picker·content·preview·download fake와 storage durability fake:
결과를 `BrowserDataResult`(`error`, 닫힌 코드, operation)로 바꿨다.
`PROVIDER_UNAVAILABLE`은 src 코드 `UNAVAILABLE`이 된다.
- `MemoryDurableObjectStore`: src OPFS port에 맞춰 다시 썼다. 생성자는
scope·storagePolicy·maxObjectBytes를 받는다. 멈춘 put의 행은
reconcile이 rollback만 한다(resume·quarantine 없음, runtime과 같다).
LOGOUT·ACCOUNT_DELETION만 지원하고 나머지 reason은 `UNSUPPORTED`다.
- 고칠 수 없는 fake: `MemoryStructuredOfflineStore`는
`IndexedDbRepositoryPort`와 설계가 달라(배치 commit·idempotency 대
CAS·lifecycle batch) catalog offline-indexeddb 행의 fake 칸에서 뺐다.
recipe 전용 `StructuredOfflineStore`의 fake로는 남는다.
- recipe 전용 port 두 곳:
- `PublicResponseCacheAdmin.inspect`는 runtime의 `PublicCacheInspection`
모양으로 보고한다. `MemoryPublicResponseCache`가 그 모양을 만든다.
- `FileTransferPort`(runtime 없음)의 progress는 `FileTransferProgress`로
나눴다. `TransferProgress`라는 이름은 recipe barrel에서 src 타입으로
계속 나간다. 일반 recipe인 `contracts.ts`가 선택형 runtime port를
import하지 않게 하려는 것이다.
- 다시 갈라지지 않게 `optional-capability-contracts.test.ts`에 검사를
더했다. recipes/가 src/application/ports/에 있는 이름으로 타입을
정의하면 실패한다(다시 내보내기는 허용).
- runtime 제거 fixture(`test-browser-file-storage-runtime-removal.ts`)는
이 runtime의 port를 다시 내보내는 recipe 두 파일과 그 테스트를 함께
지우고, recipe barrel에서 두 export 줄을 먼저 뺀다.
버린 대안: 현상 유지(변경 누락 계속), 이름만 바꿔 `*Sketch`로 표시(중복
유지비가 남음), 두 벌을 비교하는 타입 테스트(두 벌을 계속 유지).
위험·한계:
- recipe에서 위 타입·fake를 쓰던 다운스트림은 컴파일 오류로 드러난다
(조용히 깨지지 않는다). 같은 이름 타입의 모양, `MemoryDurableObjectStore`
생성자·메서드, 파일 fake의 실패 결과(`failure` → `error`), 지운 타입
4개가 바뀌었다. 두 제품 repo의 사용 여부는 확인하지 않았다.
- `MemoryDurableObjectStore`의 integrity digest는 runtime의 tree digest가
아니다(주석에 적음). worker·Web Lock·authority·GC는 흉내내지 않는다.
- `test:browser-file-storage-removal`은 pnpm이 필요해 돌리지 못했다.
barrel 줄 제거와 경로 추가는 코드로만 확인했다.
검증:
- RED: 새 검사를 수정 전 recipe 소스로 돌리면 실패한다.
`expected [ 'LocalFileRef', …(33) ] to deeply equal []` (34개).
- GREEN: `node scripts/run-vitest.ts run tests/unit tests/recipes
tests/contract` 180 files 2,548건 통과. `tsc` app·recipes·test·node
통과, 바꾼 파일 eslint 통과, `check-registries` PASS(재승인 불필요),
`verify-documentation-readiness` PASS_SCOPED.
`check-optional-recipes`(source)는 0929/05-01의 offline-indexeddb 예산
초과(37,327 > 36,900)만 실패하고 catalog·source 검사는 통과했다.
이 커밋은 그 번들 크기를 바꾸지 않는다(recipes/는 sourceRoots 밖).
BREAKING CHANGE: recipes/frontend-capabilities의 browser-file·OPFS·
storage durability·public cache 타입 중 src/application/ports와 이름이
같은 것은 이제 그 src 타입이다. file·durability·OPFS fake는 src port를
구현하고 BrowserDataResult를 돌려준다(`result.failure.code` →
`result.error.code`). `MemoryDurableObjectStore`는 `{ scope, storagePolicy,
maxObjectBytes }`로 만든다. `FileTransferPort`의 progress 타입은
`FileTransferProgress`다. `DurableObjectDataClass`·`DurableObjectIntegrity`
·`DurableObjectRead`·`ObjectStoreRecoverySummary`는 없어졌다.
Refs: docs/reviews/2026-09-29-maturity-review/05-adapters-storage-kernel.md 05-03
|
||
|
|
ca74caa2a8 |
test(component): 플랫폼 화면 테스트를 테스트 전용 페이지로 옮긴다 (0929/10-02)
문제: 라우터·chunk 복구·render 경계·앱 셸·런타임 트리 테스트가 스타터
화면(`/`의 h1, 홈의 "플랫폼 구성 보기" 링크, /examples/ui·states)을
대상으로 쓴다. 문서는 스타터 화면을 "페이지 단위로 교체 가능"하다고 하는데,
제품이 화면을 바꾸면 스타터와 무관한 플랫폼 테스트가 깨지고 동기화 때마다
같은 파일이 충돌한다(두 제품 기록).
방법: tests/helpers/fixture-feature.tsx에 테스트 전용 public 페이지 4개를
더했다. 메뉴에 나오는 지연 로드 페이지 2개(제목 h1, 런타임 릴리스 표시),
chunk 로드 실패 페이지, render 결함 페이지다. 플랫폼 테스트는 이미 쓰던
방식대로 생성 인덱스를 mock해 이 기능을 설치하고 그 페이지를 쓴다.
스타터 화면 자체를 검사하던 것(홈 시작 링크, 홈·플랫폼 구성의 릴리스 로딩
실패, 인증 예제의 복귀 URL, 상태 갤러리 제목 구조, 플랫폼 구성 화면)은
starter-pages.test.tsx와 starter-platform-overview-page.test.tsx로
모았다. 제품은 스타터 화면과 함께 starter-* 파일을 지우면 된다.
fixture는 design-system 배럴 대신 page-header.tsx를 직접 import한다.
배럴이 설치 카탈로그를 거쳐 mock된 생성 인덱스를 다시 불러 mock 팩토리가
자기 자신을 기다린다.
버린 대안: README에 "함께 사라지는 검사" 목록만 적는다. 비용은 0이지만
화면을 바꾸면 검사는 여전히 깨지거나 사라진다.
위험: 플랫폼 경로(createRegisteredRoutes의 platformChildren)를 지나는
화면 이동 테스트가 줄고 context 라우트 경로로 옮겨 갔다. `/`와 not-found는
여전히 플랫폼 경로로 돈다. ui-gallery-page는 이제 component 테스트에서
렌더되지 않는다(e2e·visual이 본다). sibling chunk 초기화 테스트는
key={definition.routeId}를 지우면 여전히 실패한다(변이 확인).
검증: RED는 템플릿 복사본에서 home-page.tsx와 examples/*를 다른 화면으로
바꾸고 test:component를 돌렸다. 7파일 20개 실패(router 5, route-status 4,
platform-overview 7, app-shell·async-surface·chunk-recovery·
runtime-application 각 1). GREEN은 같은 조작에서 starter-* 2파일 12개만
실패하고, starter-*를 지우면 34파일 216개 전부 통과. worktree에서
tests/component 36파일 228개 통과, tsc -p tsconfig.test.json 통과, 바꾼
파일 eslint 통과.
|
||
|
|
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과 같다.
|
||
|
|
de379ea78d |
ci(release): FE-GATE-019가 승격 후보를 배포된 release와 대조한다 (1101/13-01)
문제
production_gate는 promotion 직후 같은 run에서 시작하고 그 사이에 배포 job이
없다. CI 계약이 job 9개·그래프·env를 정확히 고정해 배포 job을 넣을 자리도
없다. live probe는 헤더만 보고 배포된 release가 승격 후보인지 확인하지
않는다. FE-GATE-019의 명령은 [build, verify-hosting-headers]라서 local
프로필로 다시 빌드한 dist를 검사한다. 그래서 FE-GATE-019 PASS는 "지금 떠
있는 release(대개 이전 것)의 헤더가 맞다"는 거짓 PASS다.
고른 방법 (리뷰 대안 (c), (1)~(3))
(1) live probe가 배포된 release-manifest.json의 buildId·releaseId를 후보와
비교한다. 다르거나 읽을 수 없으면 FAIL(releaseManifest build-id·
release-id). 후보는 검사하는 dist의 release-manifest.json이다.
(2) FE-GATE-019에서 build를 뺀다. verify-hosting-headers가
`--release-root .release/promoted-release`를 받아 후보 dist를 본다.
계약의 13-03 규칙(drill만 --release-root 필수)을 production_gate의 모든
게이트 명령으로 넓혔다. 플래그 없이 돌리면 local dist를 본다.
(3) promotion과 production_gate 사이에 `deployment` job(kind deployment)을
선언한다. 기본은 빈 슬롯이다: deploy 단계 하나가 deployed=false를 job
output으로 낸다. production_gate는 RELEASE_DEPLOYED로 받고, 비어 있으면
FE-GATE-019가 호스트를 probe하지 않고 UNVERIFIED(exit 3)로 끝난다.
프로젝트는 gates.json의 deployment job을 채운다. 계약이 허용하는 것:
checkout·setup-node·frozen-install·download·extract와 마지막 deploy 하나
(`script`는 package 스크립트, 존재·스크립트 그래프 검사를 gate 명령과
같이 받는다). env는 immutable_build의 CANDIDATE_ARCHIVE_SHA256과
vars.*·secrets.*만. 게이트를 소유하지 않아 채워도 계약 기준선이 안
바뀐다.
- ci-contract 보고서 jobCount 9→10, 계약 기준선 commandReferences
103→102(update-ci-contract-baseline, owner frontend-platform).
- verify-hosting-headers가 live가 아닌 모드에서 baseUrl을 null로 적는다.
스키마가 live에만 baseUrl을 허용해서, 비어 있는 슬롯과 기존 invalid-live
(예: http:// URL)는 산출물 쓰기에서 ZodError로 죽었다. 이제 기록을 남기고
각각 UNVERIFIED·FAIL로 끝난다.
버린 대안
- (b) (1)(2)만: 거짓 PASS는 사라지지만 배포 자리가 없어 운영 단계가 항상
FAIL이 된다.
- (d) production_gate를 별도 workflow로 분리: Gitea에서 run 사이 artifact
전달이 검증되지 않았다.
- 슬롯이 비었는지를 HOSTING_BASE_URL 유무로 판단: 변수만 있고 배포가 없으면
이전 release를 probe해 FAIL이 된다. 슬롯이 직접 보고하게 했다.
위험·한계
- Gitea runner가 꺼져 있어 workflow를 실제로 돌리지 않았다. job outputs와
`$GITHUB_OUTPUT`는 immutable_build가 이미 쓰는 방식과 같다.
- 실제 HTTPS 호스트에 이전 release를 띄워 probe하지 않았다. 불일치 판정은
fetcher를 주입한 단위 테스트로만 확인했다.
- 채운 슬롯의 secrets는 그 job의 모든 단계(checkout, download action 포함)
env에 보인다. 프로젝트가 고르는 값이다.
- FE-GATE-019를 수동으로 돌리는 운영자(provider 없는 최소 구성)는 후보
archive를 .release/promoted-release에 풀어야 한다. drill과 같은 전제다.
검증
- RED: node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts
7 failed / 19 passed(후보 인자 없음, verify가 dist ENOENT로 산출물 없음).
tests/unit/ci-workflow-generation.test.ts 8 failed / 415 passed
("expected [ 'build', 'verify:hosting-headers' ] to deeply equal ...",
"expected -1 to be 6", deployment job 없음)
- GREEN: hosting-probe 26 passed, ci-workflow-generation 423 passed
(스냅샷 1개 갱신)
- check:ci 하위 명령 직접 실행: generate-artifact-schemas --check PASS,
check-ci-contract.ts PASS, generate-ci-workflow --check PASS
- 슬롯을 채운 실험(체크아웃→다운로드→extract→deploy:release, vars·secrets
env, package 스크립트 추가) 뒤 같은 세 명령 PASS. package 스크립트를 빼면
"CI gate contract missing package scripts: deploy:release"로 실패. 실험
뒤 원복
- 관련 테스트 16파일 596 passed(ci-workflow-generation, hosting-probe,
service-worker-build-output, deployment-admission, ungated-*,
supply-chain, removal-fixture, task3-selective-integration,
documentation-readiness, tests/release, tests/platform/release)
- tsc(node, test, app) 0, eslint 바뀐 파일 0,
verify-documentation-readiness PASS_SCOPED
- 미실행: tests/system/ci-runner(pnpm 실행), check:architecture(pnpm)
Refs: docs/reviews/2026-11-01-maturity-review/13-build-release-supply-chain.md 13-01
|
||
|
|
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
|