Commit Graph
200 Commits
Author SHA1 Message Date
DongHyeonka 48c1ab7ab6 fix(server-state)!: 손으로 적은 뮤테이션 operation ID를 타입 검사에서 막는다
문제: 1103/16-05 수정으로 commandMutationIdentity가 생겼지만
BoundMutation.operationId는 여전히 string이다. 정책에 operation ID를
문자열로 직접 적으면 오타가 check:types와 check:registries를 통과하고,
저장할 때마다 실행기가 보내기 전에 MISSING_IDEMPOTENCY_KEY 위반으로
거부한다. 매뉴얼 01은 이것을 "못 잡음"으로 적고 있었다.

고른 방법: BoundMutation.operationId를 brand 타입 MutationOperationId로
바꾼다. 이 값을 돌려주는 것은 commandMutationIdentity뿐이라, 문자열을
직접 적으면 check:types가 실패한다. 런타임 값은 descriptor의 문자열
그대로이고 실행기·intent factory는 바뀌지 않는다. 참조 기능과 쓰기 slice
생성기는 이미 commandMutationIdentity를 spread하므로 고칠 것이 없다.
템플릿 테스트의 손글씨 ID 20곳은 tests/helpers/mutation-operation-id.ts
(commandMutationIdentity를 거치는 test helper)나 그 파일의 descriptor로
바꿨다. 매뉴얼 01·patterns 표·state 설계 예시를 맞췄다.
버린 대안: (1) 위반 이름을 INTENT_OPERATION_MISMATCH로 나누는 것. 실행
때만 드러나는 것은 같고, 공개 위반 어휘에 값이 하나 늘어 다운스트림
분기가 바뀐다. (2) 설치된 operation ID의 union 타입. 기능마다 늦게
적재되는 계약 전체를 타입으로 모을 곳이 없다.

위험·한계: 공개 타입(src/contracts/server-state.ts)이 좁아진다. 정책에
operation ID를 문자열로 적은 다운스트림 코드는 동기화 뒤 check:types가
실패한다. commandMutationIdentity에 descriptor 상수 대신 손으로 만든
객체를 넘기면 여전히 오타가 통과한다(매뉴얼 "못 잡음"). HTTP가 아닌
뮤테이션은 descriptor 모양 객체를 넘겨야 한다. 이 repo에는 그런 소비자가
없다.

검증: desktop batch에서 확인.
corepack pnpm check:types:test
tests/unit/command-mutation-identity.test.ts의 @ts-expect-error가 부모
커밋에서는 쓰이지 않아(TS2578) 실패하고 이 커밋에서 통과한다.
node scripts/run-vitest.ts run tests/unit/command-mutation-identity.test.ts tests/component/application-mutation-admission.test.tsx tests/component/application-mutation-scope-fence.test.tsx tests/component/application-query.test.tsx tests/component/form-foundation.test.tsx

BREAKING CHANGE: BoundMutation.operationId는 string이 아니라
MutationOperationId다. 뮤테이션 정책의 `operationId: "<ID>"`와
`requiresIdempotencyKey`를 `...commandMutationIdentity(<OPERATION>_CONTRACT)`
로 바꾼다(src/contracts/server-state.ts). commandMutationIdentity의 반환
타입도 operationId가 MutationOperationId다.

Refs: 1103/16-05
2026-11-05 22:26:27 +09:00
DongHyeonka daf3474252 fix(contracts): 짝 백엔드 답 표를 pin한 백엔드 표의 사본과 대조한다
문제: 짝 백엔드 답 표 JSON(backend-idempotency-answers.json)이 pin한
백엔드 http-contract.md와 같은지 아무 검사도 보지 않는다.
backend-contract-pin.test.ts는 pin과 답 표 두 파일만 읽고, drift
스크립트는 pin과 HEAD 사이에 문서 글자가 바뀌었는지만 본다. 그래서
답 표 status 오타나 옮기지 않은 행(§4 RATE_LIMIT_*)은 어디서도 걸리지
않는다. drift 스크립트는 옆 checkout이 없으면 "skipped"로 rc=0이고
(worktree에서 늘 그렇다), 매뉴얼에는 스크립트가 없다.

고른 방법: 게이트가 백엔드 checkout 없이 볼 수 있게, 백엔드 §2·§4 표의
`|` 줄을 pin 커밋 그대로 config/contracts/backend-http-contract-excerpt.json
에 옮겼다. 읽는 함수는 scripts/lib/backend-contract-excerpt.ts 하나다.
- test:unit(backend-contract-pin.test.ts): 답 표의 행마다 사본의 같은 절에
  같은 code·status 행이 있는지, 사본의 행마다 답 표에 있거나 pin의
  `notCopied`에 이유와 함께 있는지 본다. `notCopied`에는 RATE_LIMIT_* 둘을
  적었다(리뷰가 지적한 sectionsCompared §4의 실제 범위).
- check:backend-contract-drift(게이트 밖): pin 커밋의 문서에서 같은 표를
  읽어 사본과 글자 단위로 비교하고, 답 표도 그 표와 비교하고, pin 뒤
  HEAD에서 바뀐 사본 표 행을 찍는다. checkout이 없거나 pin 커밋·문서가
  없으면 rc=2("not compared")로 끝난다. 기본 경로는 main checkout 옆이라
  linked worktree에서도 같은 백엔드를 찾는다. `--write-excerpt`는 pin을
  올릴 때 사본을 pin 커밋에서 다시 옮긴다.
- 매뉴얼 01 Envelope 단계와 계약 문서 4.1에 언제 무엇을 돌리는지 적었다.
버린 대안: 백엔드 문서의 digest만 pin에 두는 것. 게이트는 digest로 답
표를 확인할 수 없다. 계약 패키지(리뷰 안 D)는 배포 경로가 아직 없다.

위험·한계: 사본과 백엔드 문서의 일치는 여전히 백엔드 checkout이 있을
때만 drift 스크립트가 본다. 게이트는 답 표와 사본의 일치만 본다. 사본을
손으로 같이 고치면 게이트는 통과한다(drift 스크립트가 잡는다). 답 표의
refusedBeforeWrite·sameKeyResend는 백엔드 문장(클라이언트 행동)을 사람이
읽은 값이라 기계로 대조하지 않는다. 그 문장이 바뀌면 사본 diff와 drift
출력에 보인다. 백엔드 표 형식(머리글 `error.code`·`코드`·`status`)이
바뀌면 파서도 고친다. pin의 comparedOn을 사본을 옮긴 날로 올렸다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/backend-contract-pin.test.ts tests/unit/backend-contract-drift.test.ts
drift 테스트는 가짜 백엔드 git repo로 D6g(pin 뒤 status 변경), 답 표
status 오타, 사본 오타, 옮기지도 적지도 않은 행, checkout 없음,
--write-excerpt를 돈다.

Refs: 1105/07-01
2026-11-05 22:17:57 +09:00
DongHyeonka 580be5839d docs(contracts): 짝 백엔드 계약 기준점을 45d2a478로 올린다
문제
check:backend-contract-drift가 백엔드 HEAD 45d2a478에서 http-contract.md §2
두 행의 설명 변경을 알린다. IDEMPOTENT_IN_FLIGHT(PostgreSQL 저장소는 409
대신 첫 요청이 끝날 때까지 기다림)와 IDEMPOTENCY_UNAVAILABLE(processing
lease가 시작 전에 끝나 저장소가 시작을 거절함)이다. 같은 커밋이 6.1절이
인용하는 GlobalExceptionHandler와 IdempotencyExecutor도 고쳤다.

고른 방법
- 두 행의 code·status·retryable·재전송 규칙은 같다. 프론트 판정(처리 중
  MAYBE_APPLIED·같은 키, UNAVAILABLE 실행 안 됨·같은 키 자동 재전송)은
  바꾸지 않는다.
- 6.1절이 인용하는 블록 13개를 두 판에서 대조했다. 내용은 모두 같고
  GlobalExceptionHandler 4개, IdempotencyExecutor 1개의 줄 번호만 옮겼다.
  인용한 다른 백엔드 파일 15개는 바뀌지 않았다.
- pin, 답 표 JSON, 계약 문서 4.1·6·6.1절, CHANGELOG의 pin 행과 알려진
  제한을 같이 고친다.

위험·한계
- PostgreSQL 저장소의 기다림이 프론트 totalDeadline보다 길면 응답 없는
  끝(결과 불명, 키 유지)이 된다. 판정은 안전 쪽이다.
- Fileserver 계약(docs/fileserver/http-contract.md)은 bbe944bd 이후 바뀌지
  않았다.

검증
- check:backend-contract-drift --backend <백엔드 checkout>: pinned
  45d2a478.
- backend-contract-pin·changelog-review-ids 테스트 11건,
  verify:documentation PASS_SCOPED.

Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-06
2026-11-05 00:24:59 +09:00
DongHyeonka 01b9def556 chore(review): 1103 CHANGELOG·문서 정리 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14-01 14-02 16-08 P-07-07
2026-11-05 00:23:06 +09:00
DongHyeonka 65fa0a78e3 docs(manual): 기능 추가 문서의 낡은 문장 넷을 지금 검사·백엔드에 맞춘다
문제
리뷰 16-08이 적은 다섯 문장 중 넷이 f887817에서도 코드와 다르다.
- 01 3단계: 라우트 루트 검사를 tests/architecture/context-route-roots.test.ts가
  "실행한다"고 적는다. 그 테스트는 fixture만 쓰고 설치된 기능을 보지 않는다.
  실제로 막는 것은 앱 모듈을 적재하는 테스트와 부팅이다.
- 01 3단계·02 결정표: 인증 프로필이 틀리면 "operation을 적재하는 모든 게이트가
  실패한다". 변이로 확인하면 check:registries와 그 기능을 적재하는 테스트만
  실패하고 check:types·check:architecture·verify:documentation은 통과한다.
- 01 8단계: "서버 422 오류를 받을 필드". 짝 백엔드의 필드 검증은 400
  VALIDATION_FAILED + details다. 공유 MSW 시나리오의 validation-422는
  Envelope operation에서 결과 불명이다.
- starter-experience.md: "`NoRequest` already belongs to the sample". src에
  NoRequest가 없다. 생성 명령이 <Pascal>NoRequest를 쓴다.
다섯째("테스트 2개")는 생성기 브랜치가 이미 고쳤다(테스트 3개와 test-app).

고른 방법
문장만 고친다. 리뷰가 검토하라고 한 공유 시나리오 validation-400 추가는 하지
않았다. 문서 작업 범위 밖이고, 생성된 작성 폼 테스트가 400 본문을 이미 손으로
적는다. 매뉴얼에 그 테스트를 가리켰다.

위험·한계
- 문장의 게이트 목록은 참조 기능에 넣은 변이 한 번으로 확인했다. build는
  돌리지 않았다.

검증
- 인증 프로필 오타 변이: check:registries rc=1(reason 포함), check:types rc=0,
  check:architecture PASS, verify:documentation PASS_SCOPED. 되돌림.
- verify:documentation PASS_SCOPED, documentation-readiness 테스트 통과.

Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-08
2026-11-05 00:22:05 +09:00
DongHyeonka 2f2426a670 docs: 샘플과 함께 지워지는 경로를 백틱 없이 적는다
문제
ac52a93이 backend-api-and-server-state-contract.md를 docs/README.md 1절에서
링크해 이 문서도 경로 검사를 받는다. 이 문서는 참조 기능 파일 둘을 백틱
경로로 적는다. static-delivery.md는 config/scale/feature-shape-ceilings.json
(15-02, 샘플 제거 때 함께 지워짐)을 백틱 경로로 적는다. 그래서 참조 기능을
지운 제거 fixture에서 verify:documentation이 "names paths that do not exist"로
실패하고, 그 fixture의 documentation-readiness 테스트 36건이 떨어진다
(FE-GATE-020). 14-04가 정한 규칙(지울 수 있는 샘플 경로는 백틱 없이)을
어겼다.

고른 방법
- 세 경로를 백틱 없이 적고, static-delivery에는 샘플과 함께 지워진다고
  적는다.

검증
- verify:documentation PASS_SCOPED. 제거 fixture 확인은 X4 재실행에서 한다.

Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-04, 14-03
2026-11-05 00:13:49 +09:00
DongHyeonka 505a8b0fca chore(review): 1103 release·CI·성능 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 12-07 13-01~13-03 13-05 15-02~15-07

# Conflicts:
#	docs/manual/03-outside-feature-folder.md
#	docs/operations/performance-evidence.md
#	scripts/lib/hosting-probe.ts
2026-11-04 23:10:59 +09:00
DongHyeonka fbd8f7d148 chore(review): 1103 게이트·드릴 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 02-06 11-06 12-09 10-01 11-03~11-05 12-02 12-04 12-05 12-08 14-04 16-02

# Conflicts:
#	docs/manual/01-add-a-feature.md
#	docs/manual/02-decision-tables.md
#	docs/manual/reference/patterns.md
2026-11-04 23:08:05 +09:00
DongHyeonka 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
2026-11-04 23:04:17 +09:00
DongHyeonka 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를 지우면 된다.
2026-11-04 22:59:03 +09:00
DongHyeonka 7f633106bb test(a11y): 접근성 e2e가 기능 API를 descriptor 모양의 빈 목록으로 답한다
문제
tests/e2e/accessibility.spec.ts는 보호 라우트의 모든 API에 맨 배열
`[]`를 답했다. create:feature가 만드는 기능은 responseEnvelope:
"ENVELOPE_V1"이라 `[]`는 ENVELOPE_MISMATCH가 되고, 페이지는 경고 상자를
그린다. spec은 h1과 axe만 봐서 오류 화면을 검사하고도 통과했고, 증거는
그 라우트를 "passed"로 적었다. 경로 파라미터는 `:resourceId`만 바꿔서
다른 이름을 쓰는 기능은 이 템플릿 파일을 고쳐야 했다.

고른 방법 (결정 D4 (b))
- tests/e2e/support/installed-api-answers.ts가 요청을 설치된 GET
  descriptor에서 method와 pathTemplate으로 찾는다. 출력 스키마가 빈
  목록을 받으면 그 operation의 모양으로 답한다(Envelope면 MSW 시나리오와
  같은 successEnvelope, 아니면 맨 배열).
- 목록만 읽은 라우트는 로딩이 끝난 뒤 경고 상자(role="alert")가 없다고
  단언한다. 모양이 다시 어긋나면 axe 통과 대신 여기서 실패한다.
- 경로 파라미터는 이름과 상관없이 모두 a11y-1로 바꾼다. 기능을 더해도
  spec을 고치지 않는다(16-03 앞 절반).
- 설치된 GET이 아닌 요청, 빈 목록을 받지 않는 파라미터 없는 GET은
  501로 답하고 그 목록이 비어 있다고 단언한다.
- 매뉴얼 01·03, starter-experience, create-feature 참조, 수동 점검
  문서의 "모든 API에 []", ".replace를 잇는다" 문장을 동작에 맞췄다.
- 버린 대안: 전역 Envelope 응답(참조 기능 DTO가 거꾸로 깨짐), 기능마다
  접근성 spec 생성(파일·실행 시간 증가).

위험·한계
- 한 자원을 읽는 GET(상세 페이지)에는 빈 목록 말고 줄 본문이 없다.
  그 라우트는 지금처럼 실패 상태로 검사하고 a11y-data-state
  annotation만 남긴다. 경고 상자 단언은 그 라우트에서 건너뛴다.
- write-a11y-report.ts의 증거는 annotation을 읽지 않는다. 상세 라우트도
  "passed"로 적힌다.

검증
- 새 unit 테스트 6건: helper가 없을 때 실패, 추가 뒤 통과.
- 템플릿 상태 chromium test:a11y 대상 spec 14건 통과.
- create:feature sample-feature 상태에서 `@a11y /sample` 세 엔진 통과.
  변이 1(Envelope 대신 맨 배열): 세 엔진 모두 경고 상자 단언으로 실패.
  변이 2(빈·성공 상태에서만 보이는 이름 없는 버튼): 세 엔진 모두
  axe button-name으로 실패. 생성 파일은 지웠다.
- check:types:test, eslint, verify:documentation, check:ci 통과.

Refs: docs/reviews/2026-11-03-maturity-review/11-tests-browser-release-scale.md 11-01
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-03
2026-11-04 22:59:03 +09:00
DongHyeonka d549ceb330 perf(examples): 플랫폼 구성 화면이 제목을 먼저 그리고 실행부 표만 기다린다
문제
lab 게이트 FE-GATE-026은 내비게이션 클릭부터 플랫폼 구성 화면 제목이
보일 때까지를 잰다. 298201f 뒤로 이 route module은 그리기 전에
loadInstalledFeatureRuntimeRegistries()를 기다린다. 그 함수는 설치된
모든 기능의 실행부를 dynamic import한다. 그래서 클릭 뒤 요청 묶음이
두 번이 되고 상호작용 중앙값이 117 -> 227 ms가 됐다(예산 200 ms).

고른 방법 (영역 문서 최소 개선 방향 (c))
- route module은 페이지 컴포넌트를 바로 돌려준다(default export).
  제목·릴리스·라우트 표·서버 상태·능력·기능 상태처럼 선언과 런타임
  snapshot으로 아는 것은 바로 그린다.
- 실행부가 있어야 아는 것(HTTP 오퍼레이션 수, 픽스처 수, 오퍼레이션
  표, 검증 생략 표)만 Suspense 경계 두 곳 뒤에서 use()로 채운다.
- 실행부 조립 모듈도 dynamic import로 바꿔 제목이 기다리는 페이지
  청크에서 뺐다(첫 요청 묶음 8,095 -> 6,919 B).
- 기능 사이 중복은 여전히 이 화면에서 throw하고 route 경계로 간다.
  실패한 load는 캐시에서 지워 다음 방문 때 다시 시도한다.
- 버린 대안: 예산 300 ms(회귀를 숨김), lab 대상 라우트 변경(같은
  이유), hover 프리페치(키보드·직접 진입에 효과 작음).

위험·한계
- 화면 안에 "기능 실행부를 불러오고 있습니다." 로딩 상태가 생긴다.
- PlatformOverviewPage의 contracts prop이 Promise가 됐다. 이 컴포넌트를
  직접 쓰는 다운스트림 테스트는 Promise를 넘기고 act로 기다려야 한다.
- 첫 요청 묶음은 d99301b보다 여전히 크다(6,919 vs 5,019 B). 그 사이
  페이지가 커졌고 badge·card가 공유 청크로 갈라졌다. 그래서 d99301b보다
  약 30 ms 느리다.
- 실제 CI 러너에서는 재지 않았다.

검증
- 새 component 테스트(실행부 load가 끝나지 않아도 제목·라우트 표가
  보이고 오퍼레이션 표만 로딩): 수정 전 실패, 수정 뒤 통과.
- test:component 통과. check:types, check:architecture, 바뀐 파일
  eslint 통과.
- lab A/B(heavy lock, 같은 호스트, d99301b worktree와 번갈아,
  test:performance --runs=5, CHOKIDAR_USEPOLLING=1, 이 브랜치 끝 기준):
  부하 19 -> 11에서 d99301b 107·106 ms PASS, 이 변경 136·134 ms PASS.
  LCP 1,968·1,984 ms, CLS 0. (같은 날 다른 묶음 한 번은 두 쪽 모두
  홈 링크를 30초 안에 찾지 못해 측정 전에 끝났다. 포트를 바꿔 다시
  잰 것이 위 결과다.)
- 요청 추적: 클릭 뒤 제목은 첫 묶음(페이지 청크 4개) 뒤에 나오고,
  feature-runtime·reference-schemas는 제목 뒤에 받는다.

Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-01
2026-11-04 22:59:03 +09:00
DongHyeonka 0fb78ff1b4 docs(architecture): 제품 설정 키의 FE-REG-ENV 행을 요구하는 테스트를 정본 표에 적는다
문제
starter-experience.md의 제품 소유 파일 표는 제품 런타임 설정 키의
FE-REG-ENV 행에 대해 "nothing requires the row"라고 적는다.
tests/unit/env-registry-coverage.test.ts(d0414c8)는 키마다 행을 요구하고,
fix/r1103-contracts(13-04)는 그 행의 required·defaultValue까지 스키마와
대조하게 했다. 매뉴얼 03 C절은 이 표를 정본으로 가리킨다.

고른 방법
- 그 셀을 "check:registries가 칸을 보고, env-registry-coverage 테스트
  (test:unit)가 키마다 행과 required·defaultValue를 요구한다"로 바꾼다.
- 같은 표의 사라진 오류 문구(14-05 ①)는 fix/r1103-app(09-07)이 이미
  고쳤다.

위험·한계
- 없음. 문서 한 셀이다.

검증
- verify:documentation PASS_SCOPED.

Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-05
2026-11-04 22:39:52 +09:00
DongHyeonka ac52a93920 docs(architecture): 목표 설계 문서의 V2 상태와 401 문장을 지금 코드에 맞춘다
문제
docs/README.md는 목표 설계 문서의 기능이 지금 동작하는지 문서 안의
상태 값으로 확인하라고 한다. 그런데 2026-11-03에 지운 V2 구성요소가
여전히 COMPOSED다(VD-23 머리, VD-24 머리, api-contract-schema-mapper
원장 세 행). VD-23은 "401 recovery는 replay-safe operation만 한 번
수행한다"를 적는데, 정본 8.4(FRT-D016)와 코드는 숨은 refresh-and-replay를
하지 않는다. 코드 주석 다섯 곳이 이 VD-23을 근거로 가리킨다. 지금 실행
규칙인 6.1절(쓰기 전 거절 표)은 "backend implementation pending"인 목표
설계 문서에 있어 verify:documentation 검사 밖이다.

고른 방법
- VD-23: 정본 우선 안내를 붙이고, V2 baseline을 REMOVED(048f490·12f3bb7)로,
  V3 contract executor를 COMPOSED로 적는다. 401 문장을 정본 8.4 문장으로
  바꾸고, 2절 defineRestOperation 앞에 삭제 안내를 둔다.
- VD-24 머리와 api-contract-schema-mapper 원장의 V2 행을 REMOVED로, shared
  executor 행을 V3 실행기 설명으로 바꾼다.
- backend-api-and-server-state-contract.md 상태 줄에 4.1·6·6.1절은 지금
  실행 규칙이라고 적고, docs/README.md 1절에서 그 절을 링크한다. 그 결과
  이 문서도 경로 검사를 받으므로, 백엔드 repo 경로 7곳에
  clean-architecture-backend-template/ 접두어를 붙였다.
- 버린 대안: 6.1절을 docs/contracts/로 옮기기. 백엔드 pin·답 표 JSON·
  backend-envelope.ts 주석이 이 절을 가리켜 같이 고쳐야 할 곳이 늘어난다.

위험·한계
- 원장 행의 나머지 문장과 VD-23 본문에는 V2 시기 서술이 남아 있다.
  상태 값과 401 규칙만 맞췄고, 남은 서술은 "V2 기록"이라고 표시했다.

검증
- git grep "401 recovery는 auth-required" -- docs/architecture: 0건.
- verify:documentation PASS_SCOPED, documentation-readiness·
  changelog-review-ids 테스트 통과.

Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-03, 03-adapters-http-state.md 03-06
2026-11-04 22:39:52 +09:00
DongHyeonka 5379c805ba docs(contracts): 짝 백엔드 계약 기준점을 c508b1ba로 올린다
문제
fix/r1103-http는 짝 백엔드 계약 pin을 bbe944bd에 두었다. 그 뒤 백엔드에
70fb80bf(늦게 끝난 멱등 실행 기록)와 c508b1ba(회복 필요 응답 안내)가
들어왔다. 새 `check:backend-contract-drift`가 §2의 500
IDEMPOTENCY_RECOVERY_REQUIRED 행 변경을 알린다. 전에는 "재전송도
재실행도 안전하지 않다"였고, 지금은 "자동 재시도하지 않는다. 같은 키
재전송은 안전하다"다.

고른 방법
- pin과 답 표 JSON의 기준을 c508b1ba 전체 SHA로 옮기고,
  IDEMPOTENCY_RECOVERY_REQUIRED의 sameKeyResend를 true로 바꾼다.
- 프론트 판정은 바꾸지 않는다. 이 code는 이미 MAYBE_APPLIED이고 키를
  붙들며 자동 재전송하지 않는다. 결과 불명 화면의 같은 키 재전송은 새
  문장과 맞는다.
- 6.1절이 인용하는 IdempotencyExecutor를 c508b1ba에서 다시 읽었다.
  처리 중·불일치 판정은 그대로 action 전이고 줄 번호만 옮겼다
  (127-130, 166-169, 267).

위험·한계
- c508b1ba에서는 §1·§2·§4와 IdempotencyExecutor만 다시 대조했다.
  나머지 6.1절 파일은 bbe944bd 판독 그대로다(두 커밋 사이에 바뀌지
  않았다).

검증
- check:backend-contract-drift --backend <백엔드 checkout>: pin과 HEAD가
  같다.
- tests/unit/backend-contract-pin.test.ts 10건, verify:documentation
  PASS_SCOPED.

Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-06, README.md 10.6
2026-11-04 22:36:24 +09:00
DongHyeonka 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
2026-11-04 22:28:57 +09:00
DongHyeonka e20b5bfe3a chore(review): 1103 업로드·전송 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 01-01 01-02 01-03
2026-11-04 21:50:46 +09:00
DongHyeonka 55d0d48424 chore(review): 1103 저장소·파일 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 02-01~02-05 05-01~05-04

# Conflicts:
#	docs/manual/03-outside-feature-folder.md
#	src/bootstrap/product-composition-contract.ts
#	src/bootstrap/runtime-adapters.ts
2026-11-04 21:46:20 +09:00
DongHyeonka c17b3a05d6 chore(review): 1103 세션 owner 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 09-03 09-11

# Conflicts:
#	docs/manual/02-decision-tables.md
2026-11-04 21:40:51 +09:00
DongHyeonka d5e3bf2e2c chore(review): 1103 계약·레지스트리 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 07-01~07-04 13-04 14-06
2026-11-04 21:28:13 +09:00
DongHyeonka 4f78890576 fix(browser-files): 위험 확장자를 safe extension으로 쓰는 다운로드 정책을 거절한다
문제: download 정책 registry는 safeExtension의 형식만 본다. 파일명
금지 목록(.exe, .html, .js 등)은 사용자가 준 이름에만 쓴다
(1101/02-02). 그래서 mediaType application/pdf + safeExtension .exe
정책이 조립되고, invoice.pdf가 invoice.exe로 browser handoff된다
(리뷰 E-7).

고른 방법: snapshotDownload가 금지 목록에 있거나 그것으로 끝나는
(.tar.js) safeExtension을 다른 정책 오류와 같이 TypeError로 거절한다.
목록은 file-policy.ts의 DEFAULT_FORBIDDEN_EXTENSIONS 하나를 쓰고,
isForbiddenDownloadExtension으로 내보낸다. browser-managed capability는
정책과 같은 safeExtension이어야 하므로 그 경로도 함께 막힌다.
버린 대안: media type과 확장자 짝 표를 두는 것. 표를 누가 소유할지
정해야 하고 범위가 크다. 이번에는 하지 않았다.

위험·한계: 이 확장자를 쓰던 다운스트림 정책은 조립 때 실패한다(보안
강화 방향). media type과 확장자가 서로 맞는지는 여전히 보지 않는다
(설계 문서에 적었다). file-transfer 번들 56,068 → 56,100 / 57,800 gzip B.

검증:
- RED: browser-file-policy-registry.test.ts 새 3건(.exe, .HTML, .tar.js)이
  throw 없음으로 실패.
- GREEN: browser-files 단위 5파일 + tests/recipes 98건 통과.
  check:types, 바꾼 파일 eslint, check:optional-recipes:source PASS,
  verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 1101/02-02
2026-11-04 21:18:51 +09:00
DongHyeonka b029dcc00a chore(review): 1103 앱 코어·폼 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 09-01 09-02 09-05 09-07~09-10 08-02~08-04
2026-11-04 21:17:43 +09:00
DongHyeonka 3f72ae7df9 docs(architecture): adapter kernel 설명을 실제 platform 폴더 내용에 맞춘다
문제: layers.md와 .dependency-cruiser.json 규칙 주석은 kernel
(src/adapters/platform/**)을 "clock, abort primitive, capacity guard"로만
적는다(0929/05-08). 실제 폴더에는 IndexedDB 연결·트랜잭션, Retry-After,
JSON member scanner와 bootstrap만 쓰는 lifecycle runtime·mutation intent
factory까지 10개 파일이 있다. 편입 기준("must never own")은
indexeddb-connection.ts 머리 주석에만 있어, 폴더에 무엇을 넣어도 되는지
문서로는 알 수 없다.

고른 방법: 리뷰 5.3절 (b). 두 곳의 설명을 실제 목록으로 고치고, 공유
메커니즘과 bootstrap 전용 서비스를 나눠 적고, 기준이 있는 위치를
가리킨다. 파일을 옮기는 (c)·(d)는 하지 않았다(1101/05-04, 남음).

위험·한계: 문서와 규칙 주석만 바꾼다. 규칙 동작은 같다. 폴더에 무엇을
넣을지를 기계가 보지 않는 것은 그대로다.

검증: check:architecture, verify:documentation 통과. bootstrap 밖에서
lifecycle·mutation intent factory를 쓰는 곳이 없음을 grep으로 확인했다.

Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 0929/05-08
2026-11-04 21:17:39 +09:00
DongHyeonka f800549315 feat(http): 짝 백엔드 Fileserver의 multipart 한 번 업로드 client를 더한다
문제: 두 템플릿을 짝으로 쓰면 파일 업로드 경로가 없다. 프론트 업로드
레시피는 PRESIGNED_MULTIPART_V1 서버를 가정하는데 짝 백엔드는 그 코드를
지웠고, 짝 백엔드 Fileserver(POST /v1/files)를 부를 프론트 client는 없다.
src 전체에 multipart 요청을 만드는 코드가 없다.

고친 방법(리뷰 D1 (나-1)): src/adapters/http/fileserver-upload.ts에
createFileserverUploadClient를 둔다. 백엔드 bbe944bd 계약 그대로다.
- 입력은 FileContentPort.openSource가 주는 FileByteSource다. 바이트를 한
  번 읽어 multipart 본문(파트 이름 file, RFC 7578, 파일 이름은 HTML 폼
  인코더처럼 escape)을 직접 만든다. File·Blob은 이 adapter에 들어오지
  않는다(eslint browser-data 경계). 선언 크기가 maxFileBytes보다 크면 읽기
  전에 거절하고, 읽는 중에 넘어도 멈춘다. 선언 크기가 있으면 본문 버퍼
  하나에 바로 쓴다.
- 전송 규칙은 레시피와 V3 실행기와 같다. credentials는 인증 프로필이
  정하고, 자격 증명 헤더는 admitCredentialHeaders로 프로필에 맞춰 받는다.
  redirect "error", no-referrer, no-store, 응답 본문 상한, 바이트에 비례한
  deadline 하나, 호출자 abort(커널 createAbortableOperation).
- 성공: 201 READY / 202 그 밖의 state를 Envelope에서 읽는다. 201과 202의
  state가 맞지 않거나 size가 보낸 바이트와 다르면 SCHEMA_MISMATCH,
  APPLIED_CONFIRMED.
- 실패: backend-envelope.ts의 readFailureEnvelope와 envelopeFailureReading을
  그대로 쓴다. 효과 판정은 Fileserver 계약을 따른다. details.ambiguous,
  AMBIGUOUS_COMPLETION, IDEMPOTENT_IN_FLIGHT, IDEMPOTENCY_COMPLETION_UNKNOWN은
  MAYBE_APPLIED. 그 밖의 4xx는 NOT_APPLIED(백엔드 UploadFile use case가
  모호하지 않은 실패에서 업로드를 취소한다). 5xx는 이름 붙인 Fileserver
  code만 NOT_APPLIED이고 나머지는 MAYBE_APPLIED. 보낸 뒤 네트워크 실패·
  시간 초과·abort도 MAYBE_APPLIED. Envelope의 retryable:false와 상한(기본
  30초)을 넘는 Retry-After는 retryable을 false로 만든다(01-02와 같은 규칙).
- Idempotency-Key 헤더를 보낸다. client는 스스로 다시 보내지 않는다.

위치를 http adapter로 고른 이유: Envelope 해석(backend-envelope.ts), 자격
증명 admission(http-contract-bridge.ts), bounded reader를 adapter 안
import로 다시 쓴다. 새 adapter 사이 import 예외가 필요 없다. 바꾼 http
파일은 index.ts의 export 한 묶음뿐이다.
버린 대안:
- backend-envelope.ts를 커널(src/adapters/platform/)로 옮기고 client를
  browser-transfer에 둔다. 다른 작업이 지금 고치는 파일을 옮겨야 하고,
  커널은 제품 중립 primitive 자리인데 백엔드 짝 정책이 들어간다.
  file-transfer 레시피 예산 여유도 1.7KB뿐이고, 이 client는 presigned
  레시피와 무관한데 그 제거 드릴에 함께 지워진다.
- browser-transfer에 Envelope 파서를 하나 더 둔다. 갈라진 사본이다.
- V3 실행기에 multipart 본문을 더한다. 1,900줄짜리 실행기를 다른 작업과
  동시에 크게 고쳐야 한다.
- FormData와 Blob을 쓴다. http adapter는 File·Blob을 쓸 수 없고(eslint),
  기능은 Blob을 갖지 않는다.

조립: 제품이 product-composition.ts에서 client 재료
(FileserverUploadClientDependencies)를 capability로 넘기고, 기능 adapter가
createFileserverUploadClient를 부른다. 그래서 템플릿 boot 번들에는 들지
않는다. 매뉴얼 02 결정표 7절, patterns.md, 두 architecture 문서, 레시피
fallback이 이 경로를 가리킨다. adapter INVENTORY와 상세 리뷰 표에 행을
더했다(번호는 끝에 141로 붙였다).

위험·한계:
- 재개가 없다. 파일 전체를 메모리에 한 번 읽는다(maxFileBytes까지). tus
  client는 없다.
- 짝 백엔드 bbe944bd의 POST /v1/files는 멱등 키를 읽지 않는다
  (NOT_IDEMPOTENT). MAYBE_APPLIED 뒤 같은 키로 다시 보내도 파일이 두 개
  생길 수 있다. 매뉴얼에 적었다.
- 효과 판정 표(NOT_APPLIED_5XX_CODES, MAYBE_APPLIED_CODES)는 백엔드
  bbe944bd 기준이다. 어긋남을 알리는 검사는 없다(12-06과 같은 종류).
- 실제 짝 백엔드를 띄운 업로드는 하지 않았다. 테스트는 계약대로 답하는
  MSW다. 실제 브라우저(Playwright)에서도 돌리지 않았다.
- 템플릿 기본 product-composition.ts가 자격 증명 owner를 노출하지 않으므로,
  템플릿 세션(EXTERNAL_BEARER)으로 올리려면 제품이 자기 credential
  provider를 써야 한다.

검증:
- tests/integration/fileserver-upload.test.ts 48건 통과(201/202 본문,
  Envelope 실패 16종, 409 IDEMPOTENT_IN_FLIGHT + Retry-After 2, 상한 밖
  Retry-After, 보낸 뒤 네트워크 실패 뒤 같은 키 재전송, 시간 초과, abort,
  자격 증명 거절, 크기·입력 거절). multipart 본문은 undici FormData
  파서로 다시 읽어 확인했다.
- 변이 7건(4xx 판정, ambiguous 무시, 상한 무시, credentials 고정, 키 누락,
  201/202 state 검사 제거, Envelope retryable 무시) 모두 실패를 만들었다.
- check:types, lint(바꾼 파일), check:architecture, check:adapter-inventory,
  verify:documentation, check:registries, check:ci 통과
- check:bundle PASS: initial JS 201,921 / 204,800 gzip bytes. 빌드 산출물
  어디에도 client 코드가 없다(dist grep). check:optional-recipes:source PASS
  (file-transfer 56,082 / 57,800)

Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 01-01
2026-11-04 21:05:23 +09:00
DongHyeonka ba2b4f4c6d feat(contracts): 짝 백엔드 계약 기준점을 기계가 읽는 pin과 답 표로 둔다
문제
짝 백엔드 계약의 기준 커밋은 계약 문서의 문장(백엔드 5786126c)뿐이고, 이
SHA를 읽는 코드·설정·테스트가 없다. 쓰기 전 거절 표 REFUSED_BEFORE_WRITE와
5xx 판정은 백엔드 http-contract.md §2를 손으로 옮긴 것이다. 리뷰 중 백엔드에
bbe944bd가 들어와 503 IDEMPOTENCY_COMPLETION_UNKNOWN이 새로 생겼는데 프론트의
어떤 검사도 알리지 않았다(README 10.6).

고른 방법 (결정 D6 (1)+(2))
- config/contracts/backend-contract-pin.json: repo, 전체 SHA(bbe944bd), 대조한
  문서와 절(§1·§2·§4), 프론트 쪽 계약 절·판정 파일, 담당.
- config/contracts/backend-idempotency-answers.json: 백엔드 §2 표 여섯 행과
  §4 REQUEST_TIMEOUT을 code·status·쓰기 전 거절·같은 키 재전송 열로 옮겼다.
  백엔드가 문서에 적은 사실만 담는다.
- tests/unit/backend-contract-pin.test.ts: 두 JSON의 모양과 같은 SHA를
  확인하고, 답마다 프론트 판정이 그 두 열에서 나오는 값인지(쓰기 전 거절이면서
  같은 키 재전송이 아니면 NOT_APPLIED, 아니면 MAYBE_APPLIED, 자동 재전송은
  둘 다 참일 때만) 본다. 반대로 프론트 표의 행이 모두 이 답 표나 6.1절
  읽기(VALIDATION_FAILED)로 뒷받침되는지 본다. 그래서 백엔드 표에 행이
  늘거나 status가 바뀐 JSON을 넣으면 실패한다.
- scripts/check-backend-contract-drift.ts(check:backend-contract-drift):
  형제 디렉터리(또는 --backend)의 백엔드 checkout이 pin 뒤에 http-contract.md를
  바꿨는지 알리고 바뀐 표 행을 보인다. CI에는 백엔드가 없어 게이트 밖이다.
  ungated-scripts.json에 이유를 적었다.
- 계약 문서 4.1·6절의 기준 커밋을 bbe944bd와 pin 파일로 옮겼다. 6.1절 표는
  5786126c..bbe944bd 사이 바뀐 백엔드 파일 다섯을 다시 읽었다. 판정은 같고
  줄 번호만 옮겼다(IdempotencyExecutor, GlobalExceptionHandler →
  HttpStatusErrorCodes, FailureCategory, PersistenceExceptionTranslator).

버린 대안
- 백엔드 error-codes.yaml과 문서 다이제스트를 기록: 다이제스트는 바뀐 것만
  알리고 무엇을 고칠지 말하지 않는다.
- 백엔드가 계약 패키지를 발행: 백엔드 빌드에 JS 발행이 생긴다. 지금 규모에는
  pin과 표가 작다.

위험·한계
- 답 표 JSON은 사람이 백엔드 문서에서 옮긴다. 옮기는 실수는 drift 스크립트와
  리뷰가 잡는다. 백엔드 쪽이 같은 JSON을 자기 레지스트리와 대조하는 일은
  백엔드 저장소 몫이다.
- 백엔드 HEAD는 이미 pin 뒤로 갔다(지금 c508b1ba). http-contract.md §2의 500
  IDEMPOTENCY_RECOVERY_REQUIRED 행이 "같은 키 재전송은 안전하다"로 바뀌었다.
  프론트 판정(MAYBE_APPLIED, 자동 재전송 없음, 사용자 재전송은 같은 키)은 그
  문장과도 맞는다. pin은 지시대로 bbe944bd에 두었다.

검증
- 새 테스트 10건 통과. 변이 4종 검출: 답 표에 503 새 code 행 추가, 프론트
  표에서 COMPLETION_UNKNOWN 제거, 프론트 표에 근거 없는 400 BAD_PARAMETER
  추가, 답 표의 RECOVERY_REQUIRED status 변경.
- check:backend-contract-drift: worktree에서 skipped(exit 0), 실제 백엔드
  checkout으로 exit 1과 바뀐 RECOVERY_REQUIRED 행 출력.
- test:unit 178파일 2,645건, check:ci, check:types, eslint,
  verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-06
Refs: docs/reviews/2026-11-03-maturity-review/README.md 10.6
2026-11-04 21:03:40 +09:00
DongHyeonka d9ca6537d8 docs(architecture): 캐시 문서의 밀린 줄 번호 참조를 심볼 이름으로 바꾼다
문제: client-cache-and-storage.md의 cross-context 조립 설명이
runtime-adapters.ts·server-state-scope-runtime.ts·tanstack-cache-
coordinator.ts의 줄 번호를 가리키는데, 네 곳 모두 다른 코드로 밀렸다
(0929/02-04). 문서 줄 번호를 보는 검사는 없어서 다음 변경에도 또 밀린다.
browser-file-and-origin-storage.md의 participant 등록 예 줄 번호는 앞
커밋(02-01)이 이미 고쳤다.

고른 방법: 줄 번호 대신 함수·호출 이름을 적는다(1101/05-05와 같은
방식). 리뷰가 맞다고 확인한 다른 줄 번호는 그대로 둔다.

위험·한계: 문서만 바꾼다. 다른 문서의 줄 번호 참조는 건드리지 않았다.

검증: verify:documentation PASS_SCOPED.

Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 0929/02-04
2026-11-04 21:02:15 +09:00
DongHyeonka c4d587052e fix(removal): 참조 기능을 지워도 문서 게이트가 통과하고 드릴이 그것을 본다
문제
README는 참조 기능을 지울 수 있다고 적는다. 그러나 매뉴얼·입구 문서
10개가 참조 기능과 그 드릴 전용 파일의 경로를 백틱으로 적고,
verify:documentation(FE-GATE-017)은 백틱 경로의 존재를 검사한다. 그래서
참조 기능을 지운 복사본에서 문서 게이트가 경로 24개로 실패한다. 제거
드릴(test:sample-removal)은 문서를 복사하지 않고 그 게이트와 lint·
check:i18n·check:design-system을 돌리지 않아 이 충돌을 보지 못했다.

고른 방법
- 리뷰 5.2절 (b): 참조 기능이 가진 경로는 백틱 없이 "예제(참조 기능)"으로
  적는다. 기능 공통 모양은 생성 경로 꼴(`src/features/<id>/domain`)로
  적는다. 규칙은 docs/manual/reference/patterns.md 첫머리에 적었다.
- 드릴은 REMOVAL_FIXTURE_DOCUMENT_TARGETS(README·CHANGELOG·docs)까지
  복사하고, 지운 뒤와 생성 기능을 더한 뒤 두 번 모두 lint,
  verify:documentation, check:i18n, check:design-system을 돈다
  (FOLLOW-UP 09-07). 문서 테스트 두 개도 fixture에서 다시 돈다.
- 버린 대안: 검사기가 참조 기능 경로를 "없어도 되는 경로"로 보기(5.2
  (c)). 매뉴얼이 없는 파일을 가리키는 상태를 허용한다. 참조 기능을 지울
  수 없게 하기(5.2 (d)). README 약속과 드릴의 존재 이유가 바뀐다.

위험·한계
- 템플릿 자신에서도 참조 기능 경로의 존재를 문서 검사가 더는 보지
  않는다. 참조 기능 파일 이름을 바꾸면 그 문장은 사람이 고쳐야 한다.
- 드릴 시간이 lint·문서 검사 두 번만큼 는다.
- 드릴 실제 실행 결과는 이 커밋 메시지에 적지 않았다(공유 잠금 대기).

검증
- 참조 기능·참조 context·SAMPLE_EXTRAS를 지운 복사본(scratchpad
  sim-sample-docs.sh)에서 수정 전 FAIL_UNVERIFIED(문서 10개), 수정 뒤
  PASS_SCOPED.
- 저장소에서 verify:documentation PASS_SCOPED,
  documentation-readiness 14건 통과, eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-04
2026-11-04 21:02:14 +09:00
DongHyeonka af7d0b1824 fix(browser-transfer): 재조정에서 checkpoint 삭제가 실패해도 resourceId를 준다
문제: complete 응답을 잃은 뒤 다음 upload()가 재조정해 서버 status
QUARANTINED를 찾았을 때, 로컬 checkpoint 삭제가 한 번 실패하면 runtime이
그 실패를 그대로 돌려준다({UNAVAILABLE, UPLOAD_RECONCILE, retryable:true,
RESUME}). 서버에는 자원이 이미 있는데 이 호출은 resourceId를 잃는다. 같은
상황의 complete 경로는 삭제 실패를 무시하고 성공을 준다.

고친 방법: 재조정의 QUARANTINED 분기도 complete 경로와 같이 삭제 결과와
상관없이 {QUARANTINED, resourceId, replayed:true}를 준다. 남은 행은 다음
upload()나 abort()가 같은 자원으로 정리한다. 설계 문서 4.3절의 같은 규칙
줄에 재조정 경우를 더했다.

위험·한계: 삭제가 계속 실패하는 저장소에서는 행이 남는다. 다음 호출마다
status를 한 번 읽고 같은 resourceId를 replayed로 준다. complete 경로와 같은
한계다.

검증:
- 새 테스트: 고치기 전 {ok:false, UNAVAILABLE, UPLOAD_RECONCILE} (리뷰 X4와
  같다), 고친 뒤 {ok:true, QUARANTINED, resource_01, replayed:true}, 행 남음,
  다음 호출이 정리
- 영역 단위 테스트 15파일 276건 통과
- check:types(test), eslint(바꾼 파일) 통과

Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 0929/01-02
2026-11-04 20:59:31 +09:00
DongHyeonka 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
2026-11-04 20:54:24 +09:00
DongHyeonka 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
2026-11-04 20:54:20 +09:00
DongHyeonka 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
2026-11-04 20:51:51 +09:00
DongHyeonka 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
2026-11-04 20:49:30 +09:00
DongHyeonka 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
2026-11-04 20:46:38 +09:00
DongHyeonka 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
2026-11-04 20:42:36 +09:00
DongHyeonka 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
2026-11-04 20:40:37 +09:00
DongHyeonka 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
2026-11-04 20:38:14 +09:00
DongHyeonka 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
2026-11-04 20:38:12 +09:00
DongHyeonka 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
2026-11-04 20:35:38 +09:00
DongHyeonka 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
2026-11-04 20:35:11 +09:00
DongHyeonka 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
2026-11-04 20:34:39 +09:00
DongHyeonka 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
2026-11-04 20:34:12 +09:00
DongHyeonka 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
2026-11-04 20:31:51 +09:00
DongHyeonka 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
2026-11-04 20:31:08 +09:00
DongHyeonka 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
2026-11-04 20:30:47 +09:00
DongHyeonka 5b2106df25 docs(realtime): realtime 레지스트리 세 바인딩의 출처를 레시피에 적는다
문제
realtime 레지스트리는 schemaCodecs·mappers·apiOperations 세 바인딩을
받아 event type과 checkpoint를 대조한다. V2 삭제(12f3bb7)로 기능의
runtimeSchemas·mappers 칸이 사라져 지금 출처가 있는 것은
apiOperations뿐이다. 레시피는 "제품 feature는 이 runtime에
schema/codec/query … 주입"이라고만 적어 조합자가 codec·mapper를 어디서
만드는지 알 수 없다.

고른 방법
- 리뷰의 최소 방향대로 레시피 Realtime 절에 세 바인딩의 출처를 적는다.
  apiOperations는 loadInstalledFeatureRuntimeRegistries().apiOperations,
  schemaCodecs는 V3 events[].payloadValidator·checkpoint outputValidator를
  runtimeSchemaCodecFromValidator + composeRuntimeSchemaCodecs로,
  mappers는 조합 코드의 BoundaryMapper + composeBoundaryMapperRegistry다.
  등록 때 맞아야 하는 id(payloadSchemaId = validator schemaId =
  mapper inputSchemaId)도 적었다(realtime-streams.ts 등록 검사).
- 버린 대안: 지금 기능 모듈에 realtimeMappers 칸을 더하거나 V3 events에서
  event type을 뽑기. 공개 계약이 바뀌고, 04-02의 push 경로(STOMP hint면
  delta mapper가 필요 없을 수 있음)를 고른 뒤 정하는 것이 맞다.

위험·한계
- 코드 변경이 없다. 같은 이벤트를 V3 events와 realtime 등록 두 곳에
  적는 중복은 문서 규칙으로만 막는다.

검증
- verify:documentation PASS_SCOPED.

Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 04-06
2026-11-04 20:30:22 +09:00
DongHyeonka 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
2026-11-04 20:29:32 +09:00
DongHyeonka 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
2026-11-04 20:27:53 +09:00
DongHyeonka 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
2026-11-04 20:24:14 +09:00
DongHyeonka 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
2026-11-04 20:23:21 +09:00
DongHyeonka 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
2026-11-04 20:21:55 +09:00