332bfee9b8bbc6172d1ea74f53d0f05698d3f1ce
371
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
332bfee9b8 |
fix(docs): 지운 템플릿 기능의 경로를 문서 검사가 요구하지 않는다
문제 CHANGELOG "먼저 할 일" 6단계는 예제를 지운 제품(tech-log)에게 예제 기능 폴더와 그 context를 지우라고 한다. 그런데 starter-experience.md가 그 세 폴더를 백틱 경로로 적어서, 지운 사본에서 verify:documentation과 FE-GATE-005의 documentation-readiness "passes the documents as they are"가 "starter-experience.md names paths that do not exist"로 실패한다(리뷰 14-R1). 그 문서가 안내한 드릴(test:sample-removal --feature=platform-examples-feature)도 같은 문서 검사와, 예제 기능 ID를 적은 tests/unit/hosting-probe.test.ts 때문에 잔여 검사에서 실패한다. PRODUCT.md는 예제 화면에 제거 드릴이 없다고 적는다. 지운 제품이 템플릿 문서를 고치면 동기화마다 그 줄이 충돌한다. 고른 방법 - 문서 검사는 scripts/lib/removable-template-features.ts의 기능마다, 그 기능이 설치돼 있으면(src/features/<id>/feature-module.ts가 있으면) 그 경로·script를 지금처럼 검사하고, 아니면 그 기능이 가진 경로(기능·테스트 폴더, context, 전용 파일)와 script를 없어도 되는 것으로 본다. 폴더가 아니라 feature-module.ts를 보는 것은 tech-log가 참조 기능 폴더를 계약 파일만 남긴 채 NOT_A_FEATURE로 두기 때문이다(CHANGELOG 옮기는 법 1). 목록에 없는 폴더(오타)는 그대로 실패한다. 지운 기능이 있으면 stdout에 그 ID를 적는다. - tests/unit/hosting-probe.test.ts의 FEATURE_OVERRIDES 키를 테스트 전용 기능 ID(fixture-feature)로 바꾼다. probe는 키 이름을 보지 않는다. - 새 테스트 tests/unit/template-feature-removal-documents.test.ts: 저장소 사본에서 기능마다 그 경로를 지우고 색인을 다시 만든 뒤 사본의 verify:documentation이 통과한다. 사본의 코드로 경로를 찾으므로 실제로 지운 상태다. 기능 ID는 목록에서 읽어 테스트에 적지 않는다(제거 드릴의 잔여 검사). 설치된 기능 아래의 없는 경로와 목록에 없는 폴더는 여전히 실패하는 것도 본다. 문서를 읽으므로 REMOVAL_FIXTURE_DOCUMENT_TESTS에 더했다. - PRODUCT.md, starter-experience.md(지우는 법과 문서 검사 규칙), docs/README.md 1절 검사 설명, CHANGELOG 6단계(테스트 폴더, generate:feature-index, 드릴, 두 절을 함께 받을 것)를 고쳤다. - 버린 대안: (a) 세 경로를 백틱 없이 적기(1103/14-04 방식). 검사가 또 좁아진다(1105/14-03). (b) 모든 src/features/<dir> 아래 경로를 폴더가 없으면 통과시키기. 기능 폴더 이름 오타가 조용히 지나간다. (c) FE-GATE-020에 예제 기능 드릴을 더하기. job이 약 5분 는다. 문서 쪽은 새 unit 테스트가 merge 단계에서 본다. 위험·한계 - 새 테스트는 저장소 사본을 두 번 만든다(기능마다 cp·색인·검사). test:unit 시간이 몇 초 는다. 드릴이 test:all에서 이 파일을 다시 돈다. - 예제 기능 드릴 전체(test:all, build 등)는 이 커밋에서 돌리지 않았다. 알려진 남은 실패는 e2e·visual spec이 예제 화면을 여는 것이고 드릴 밖이다. - RED에서 새 테스트는 앞 커밋의 목록 모듈을 import하므로 그대로 돈다. 검증 - desktop batch에서 확인: node scripts/run-vitest.ts run tests/unit/template-feature-removal-documents.test.ts tests/unit/hosting-probe.test.ts tests/unit/removal-fixture.test.ts tests/unit/documentation-readiness.test.ts, corepack pnpm verify:documentation, corepack pnpm test:sample-removal -- --feature=platform-examples-feature Refs: 1105/14-01 |
||
|
|
b8d53c9aae |
chore(review): 1105 성능·구조 조치 브랜치를 합친다
합치며 고친 것: 두 브랜치가 따로는 맞고 합치면 어긋나는 곳 둘. - 1105/12-04(실행 격리 브랜치)는 `vite.config.ts`가 `scripts/lib/run-isolation.ts`를 가져오게 해, 저장소를 임시 루트에 복사해 빌드하는 두 목록(`scripts/scale/measure-feature-shape-growth.ts`, `tests/unit/product-feature-selection-build.test.ts`)에 그 파일을 더했다. 1105/15-03(이 브랜치)은 두 목록을 `scripts/lib/vite-build-inputs.ts` 하나로 옮겼다. 두 파일의 충돌은 15-03 쪽으로 풀고, 옮긴 목록에 `scripts/lib/run-isolation.ts`를 더한다. 더하지 않으면 `tests/unit/vite-build-inputs.test.ts`가 그 파일 이름을 대며 실패하고, 임시 루트 빌드 두 곳이 "Could not resolve './scripts/lib/run-isolation.ts'"로 실패한다. - `scripts/lib/removal-fixture.ts`의 문서 테스트 목록에 03-01(HTTP 판정 브랜치)과 16-01(이 브랜치)이 각자 한 줄씩 더했다. 두 줄을 모두 둔다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/unit/vite-build-inputs.test.ts tests/unit/feature-shape-growth.test.ts tests/unit/product-feature-selection-build.test.ts Refs: 1105/12-04, 1105/15-03, 1105/03-01, 1105/16-01 |
||
|
|
703a33559f | chore(review): 1105 가드레일·CI 조치 브랜치를 합친다 | ||
|
|
1a29d4aa85 | chore(review): 1105 실행 격리 조치 브랜치를 합친다 | ||
|
|
d5a70b4267 | chore(review): 1105 테스트 조치 브랜치를 합친다 | ||
|
|
45c9c4dc48 |
chore(review): 1105 계약·앱 코어 조치 브랜치를 합친다
합치며 고친 것: 두 브랜치가 따로는 맞고 합치면 어긋나는 곳 하나. - 1105/03-02(HTTP 판정 브랜치)가 §4의 503 `RATE_LIMIT_UNAVAILABLE`· `RATE_LIMIT_INCOMPATIBLE`을 답 표(`backend-idempotency-answers.json`)에 옮겼다. 1105/07-01(이 브랜치)은 같은 두 code를 pin의 `notCopied`에 두었다. 합친 트리에서 `backend-contract-pin.test.ts`의 "copies the answers from the backend table rows at the pin"이 "is both copied and listed in notCopied"로 실패한다. - pin의 `notCopied`를 비우고, 계약 문서 4.1절의 "지금은 §4의 `RATE_LIMIT_*` 둘"과 "§4 행은 `REQUEST_TIMEOUT` 하나"를 답 표에 맞게 고친다. - `docs/manual/01-add-a-feature.md` 충돌은 앞 통합(1a4a220c)과 같게 푼다: "5xx 여섯" 줄과 pin·사본·drift 명령 세 줄을 함께 둔다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/unit/backend-contract-pin.test.ts tests/unit/backend-contract-drift.test.ts Refs: 1105/03-02, 1105/07-01 |
||
|
|
57c34ea626 | chore(review): 1105 realtime·Service Worker 조치 브랜치를 합친다 | ||
|
|
7af80859e5 | chore(review): 1105 브라우저 파일·캐시·저장소 조치 브랜치를 합친다 | ||
|
|
19d10538d6 | chore(review): 1105 HTTP 판정·폼 조치 브랜치를 합친다 | ||
|
|
510e2bbceb |
docs(testing): 한 checkout 두 실행의 run ID·포트 변수를 적는다
문제: 실행 격리(앞 두 커밋)의 변수(`TEST_RUN_ID`, `RUN_OUTPUT_ROOT`, `TEST_*_PORT`)와 "게이트는 한 checkout에서 하나씩"이라는 전제가 어디에도 적혀 있지 않다. 테스트 전략 13.1은 dev E2E가 떠 있는 서버를 재사용한다고 적고 있어 바뀐 동작과 다르다(1105/12-04 "결정의 근거"는 이 선택이 어디에도 적혀 있지 않다고 지적했다). 고른 방법: 테스트 전략에 13.6절을 더한다. 핵심, 흐름도, 변수 표, 두 실행 예, 한계(게이트·증거 검사는 기본 경로만 읽음, 같은 run ID, 선택이 다른 두 실행의 `src/.generated`, Storybook 캐시, `.tmp/runs` 정리)를 적는다. 13.1의 재사용 문구를 고친다. 매뉴얼 "merge 전에 돌릴 것"과 README 게이트 반복문 아래에 짧게 적고 13.6절을 가리킨다. 버린 대안: README에 표 전체를 두기. README는 게이트를 돌리는 법만 적고 상세는 테스트 전략 문서에 두는 지금 구조를 따른다. 위험·한계: 문서만 바꾼다. 경로·스크립트 이름·링크는 verify:documentation이 검사한다. 검증: desktop batch에서 확인. corepack pnpm verify:documentation Refs: 1105/12-04 |
||
|
|
90c489c31a |
fix(scaffold): 생성 폼이 "변경됨으로 확인" 뒤 목록을 연다
문제 create:feature --with-create가 만드는 작성 폼의 feedback은 form.failure와 결과 불명 두 가지뿐이다. 저장 성공은 상세로 이동해서 알리는데, "변경됨으로 확인"은 reconcileUnknownEffect(...).then(form.settleApplied)이고 이동하지 않는다. settleApplied가 결과를 success로 바꾸고 기본값 resetOnSuccess로 입력을 비우므로, 결과 불명 화면이 사라진 뒤 빈 폼만 남는다. 짝 백엔드 기본(NEVER)에서는 이것이 화면 안의 유일한 행동이다. 사용자는 확인이 받아들여졌는지 모르고, 다시 입력해 저장하면 키 없는 생성이 한 번 더 나간다(실제로 저장됐던 경우 중복). 참조 폼은 같은 경우 "저장했습니다."를 보인다. 고른 방법 확인 뒤 폼을 정리하고(settleApplied, flushSync라 이동 전에 dirty 가드가 풀린다) 목록으로 이동한다. 목록은 항목이 실제로 저장됐는지를 보여 주는 화면이고, reconcileUnknownEffect가 이미 목록 topic을 무효화한다. 라우터가 목록 제목으로 포커스를 옮기므로 08-01의 포커스 문제도 이 폼에서는 생기지 않는다. 생성 기능 테스트에 "응답을 잃은 생성 → 변경됨으로 확인 → 목록 제목과 항목"을 한 행 더했다 (NEVER·KEYED 공통). 매뉴얼 02의 생성 테스트 행에 적었다. 버린 대안 참조 폼처럼 success 가지에 확인 문구를 둔다: 생성 catalog에 키가 하나 늘고, 항목이 실제로 있는지는 여전히 보이지 않는다. 위험·한계 - 짝 백엔드 생성기에는 목록 GET이 아직 없다(1103/03-07 결정 대기). 실제 짝 백엔드에서는 이동한 목록이 405를 받는다(생성 목록 페이지가 지금 그렇다). 생성 테스트는 MSW로 목록을 답한다. - 생성 결과 파일은 단위 테스트가 문자열로만 보고, 동작은 test:feature-scaffold (KEYED, FE-GATE-020)와 test:sample-removal(NEVER)에서 생성한 테스트가 본다. 검증 desktop batch에서 확인: node scripts/run-vitest.ts run tests/unit/create-feature.test.ts corepack pnpm test:feature-scaffold corepack pnpm test:sample-removal Refs: 1105/08-02 |
||
|
|
12d97d7469 |
feat(forms): 기능이 백엔드 거절 code에 자기 문구를 붙인다
문제 refusedBeforeWrite로 선언한 업무 거절은 이제 결과 불명이 아니고 다시 저장된다. 그런데 거절 이유가 사용자 말로 보이지 않는다. 선언한 400은 kind UNKNOWN_CLIENT_FAILURE라 "요청을 처리할 수 없습니다." + "지원 정보 확인"이고, 409는 kind CONFLICT라 "다른 변경과 충돌했습니다."다. 고칠 수 있는 입력인데 지원 문의로 보낸다. mapProblem으로 필드 오류를 만들어도 문구는 플랫폼 표에서 issue code로만 고르므로(표에 없는 DUPLICATE는 "입력값을 확인해 주세요.") 기능이 *_ALREADY_EXISTS 같은 거절에 자기 문구를 붙일 자리가 없다(리뷰 08-R1 A1~A3). conflict 결과에서는 form.failure가 null이라 페이지가 code를 읽어 따로 그릴 수도 없다. 고른 방법 useAppForm에 refusalMessages 옵션을 더한다. 실패 code별로 기능 catalog의 메시지 키와(선택) 필드를 적는다. 적용 안 됨(effect NOT_APPLIED)으로 끝난 실패의 code가 있으면 그 문구를 필드 오류로(필드가 없거나 allowedServerFields 밖이면 오류 요약으로) 보이고 결과를 validation-error로 둔다. 필드면 그 필드로 포커스를 옮긴다. 키는 렌더 때 번역한다(다른 폼 오류와 같다). Object.hasOwn으로 자기 키만 읽는다(1103/08-03). 재로그인(action reauth)이 먼저다. 결과 불명은 code와 상관없이 결과 불명이다. 매뉴얼 02 4절에 적었다. 버린 대안 - 플랫폼 문구 표(form-contracts.ts)에 code를 더한다: 기능 code를 템플릿 파일에 적게 된다. - mapProblem이 문구까지 돌려주게 한다: 어댑터가 presentation 메시지 키를 알게 된다. - 지난 리뷰 5.3절 (B)(useAppForm이 코디네이터 상태를 받아 결과를 하나로 낸다): 더 넓은 구조 변경이라 이 커밋에서 하지 않았다. 위험·한계 - 1103/03-01 남은 부분 중 이 커밋은 "이유 문구와 기능 문구 자리"만 고친다. KEYED 결과 불명의 같은 키 재전송이 500 IDEMPOTENCY_RECOVERY_REQUIRED를 받아도 재전송 버튼이 남는 것(08-R1 A5)은 결정 대기로 남긴다. 백엔드 §2는 이 답에 "같은 키 재전송은 안전하다, 첫 시도가 늦게 끝났으면 그 결과를 재생한다"고 적고 답 표 사본도 sameKeyResend: true다. 버튼을 거두면 그 회복 길도 닫힌다. 고르는 사람: 프론트 템플릿 담당(frontend-platform). 선택지: (a) RECOVERY_REQUIRED 뒤 재전송을 거두고 "목록에서 확인" 안내를 둔다(AppFailure에 답의 원인을 싣는 계약 추가 필요), (b) 백엔드가 KEYED 작업 안의 업무 예외(트랜잭션 롤백)를 "효과 없음" 으로 기록해 같은 키 재전송이 다시 실행되게 한다(백엔드 변경), (c) 지금대로 둔다 (재전송은 안전하고, 참조 폼은 목록 새로 보기 링크가 있다). - 선언하지 않은 code는 지금처럼 결과 불명이고 "변경됨으로 확인"이 남는다(완료 기준의 설계). 참조 기능과 생성기는 이 옵션을 쓰지 않는다. 생성기는 이미 <FEATURE>_INVALID를 필드 오류로 보인다. 검증 desktop batch에서 확인: node scripts/run-vitest.ts run tests/component/form-foundation.test.tsx Refs: 1103/03-01 |
||
|
|
683ccfb56b |
fix(query): 키 없는 결과 불명 요청의 같은 입력 재제출을 훅이 막는다
문제 0929/03-03은 화면 버튼 쪽만 고쳐졌다. 남은 길이 둘이다. - useApplicationMutation의 submit은 같은 canonical input의 결과 불명 admission을 찾아 그 intent를 그대로 다시 보낸다. 키 없는 intent(NEVER)면 서버가 가려낼 수 없는 두 번째 요청이다. 막는 곳은 폼(unknownSubmissionRef)과 두 페이지의 버튼·onSubmit 검사뿐이라, 폼 밖에서 submit을 부르는 화면은 같은 항목을 둘 만들 수 있다(리뷰 실험 X1: 재전송은 null인데 같은 입력 submit이 두 번째 POST를 보냈고 keys=[null,null]). - AsyncSurface는 state.unknownEffectResendable !== false일 때 재전송 버튼을 그린다. 코디네이터 없이 손으로 만든 AsyncState(플래그 없음)는 지금도 버튼을 그린다(실험 X3). 고른 방법 - submit이 같은 입력의 결과 불명 admission을 찾았는데 그 intent에 키가 없으면 보내지 않고 NOT_STARTED DUPLICATE_IN_FLIGHT(code UNKNOWN_EFFECT_PENDING)를 돌려준다. admission을 만들기 전이라 결과 불명 상태와 identity lease는 그대로다. KEYED의 같은 키 재전송, 입력이 바뀐 새 요청은 바뀌지 않는다. LEGACY(테스트 하네스) 경로는 intent가 없어 replay 자체가 없으므로 영향이 없다. - AsyncSurface는 unknownEffectResendable === true일 때만 재전송 버튼을 그린다. 코디네이터의 state는 늘 이 값을 싣는다(canResendUnknownEffect). - 기존 async-surface 테스트 "renders unknown mutation effects with confirm-applied and resend only"는 플래그 없는 상태로 버튼을 기대했다. 이 수정의 의도대로 isUnknownEffectResendable: true를 입력에 적었다. 단언은 그대로다. - 런북 6.3-4와 매뉴얼 01에 키 없는 재제출과 손으로 만든 상태를 적었다. 버린 대안 FailureKind에 새 kind를 더한다: 닫힌 레지스트리를 넓히는 계약 변경이다. "같은 논리 요청이 아직 끝나지 않았다"는 DUPLICATE_IN_FLIGHT(action none)로 충분하다. 위험·한계 - 다운스트림이 AsyncSurface에 손으로 만든 결과 불명 상태와 onResendUnknownEffect를 넘기던 화면은 재전송 버튼이 사라진다. 코디네이터의 state를 넘기면 그대로다. - 결과 불명 admission은 메모리에만 있다. 새로고침 뒤 같은 입력은 막지 못한다 (런북 6.3-7의 한계 그대로). 검증 desktop batch에서 확인: node scripts/run-vitest.ts run tests/component/application-mutation-admission.test.tsx tests/component/async-surface.test.tsx tests/component/application-query.test.tsx Refs: 0929/03-03 |
||
|
|
c6c37f395b |
fix(http): 백엔드 rate-limit 503 두 code를 쓰기 전 거절로 읽는다
문제 짝 백엔드 http-contract.md §4는 web 전용 code 넷을 적는다. 그중 503 RATE_LIMIT_UNAVAILABLE(저장소 응답 없음, retryable, Retry-After 있음)과 503 RATE_LIMIT_INCOMPATIBLE(제공자 불일치)이 답 표 사본에도 프론트 판정 표에도 없다. 그래서 이 503은 기능 분류기가 정하고, create:feature가 만든 쓰기의 분류기는 늘 MAYBE_APPLIED다. 아무 일도 일어나지 않은 저장이 결과 불명이 되고, NEVER 쓰기는 사실과 다른 "변경됨으로 확인"을 눌러야 폼이 풀린다(리뷰 실험 X4: 429는 NOT_APPLIED, 503 둘은 SERVER_FAILURE/MAYBE_APPLIED). pin은 §4를 대조했다고 적었지만 사본에는 REQUEST_TIMEOUT 한 행만 있었다. 고른 방법 백엔드 45d2a478을 읽기만 해서 code마다 판정했다. 두 code는 RateLimitInterceptor.preHandle이 false를 돌려주며 쓰고(Unavailable· Indeterminate → RATE_LIMIT_UNAVAILABLE, Incompatible → RATE_LIMIT_INCOMPATIBLE), main 소스에서 두 code를 내는 곳은 그 두 줄뿐이다. preHandle이 false면 handler를 부르지 않으므로 둘 다 쓰기 전이다. 백엔드는 같은 키 재전송을 요구하지 않는다(멱등성 executor 전). 그래서 답 표 사본에 refusedBeforeWrite: true, sameKeyResend: false로 두 행을 더하고, 프론트 거절 표 REFUSED_BEFORE_WRITE에 status 503과 함께 더했다. pin 테스트의 "답 표대로 읽는다" 규칙이 그대로 NOT_APPLIED를 요구하고 양방향 대조가 두 표를 함께 지킨다. kind는 지금처럼 SERVER_FAILURE(action retry)이고, KEYED도 자동 재전송은 없다(같은 키를 요구하는 답은 503 IDEMPOTENCY_UNAVAILABLE 하나다). pin의 comparedOn을 §4를 다시 대조한 날짜로 올렸다. 계약 문서 4.1·6.1절과 매뉴얼 01·02의 5xx 행 수를 고쳤다. 버린 대안 생성기 분류기가 503을 code별로 보게 한다: 생성 기능에만 고쳐지고 손으로 쓴 Envelope operation은 그대로 남는다. 판정은 백엔드 답 표 한 곳이 정한다는 지금 규칙을 따랐다. 위험·한계 - 추론(실행 확인 안 함): Spring MVC는 비동기 처리(Callable·DeferredResult) 뒤 ASYNC 재디스패치에서도 interceptor의 preHandle을 다시 부르고, 이 interceptor는 dispatcher 종류를 보지 않는다. 비동기 쓰기 컨트롤러라면 이 503(그리고 429)이 쓰기 뒤에도 나올 수 있다. 45d2a478에는 Envelope을 돌려주는 비동기 쓰기 컨트롤러가 없다(web-advanced 스트리밍과 fileserver 전송뿐). 계약 6.1절에 적었다. 백엔드에 넘길 요청: RateLimitInterceptor가 DispatcherType.REQUEST에서만 평가하게 한다. - fileserver-upload.ts는 같은 백엔드 답을 자기 표로 따로 판정한다(01 영역). 여기서는 바꾸지 않았다. - NOT_APPLIED가 되면서 IDEMPOTENT 쓰기는 이 503에 retryBudget 안에서 자동으로 다시 보낼 수 있게 됐다(503은 재시도 status다). 쓰기 전 거절이라 중복은 없다. RATE_LIMIT_INCOMPATIBLE은 백엔드가 retryable false로 보내지만 실행기는 status로 판단하므로 같은 답을 한 번 더 받을 수 있다. KEYED·NEVER는 자동 재전송이 없다. 검증 desktop batch에서 확인: node scripts/run-vitest.ts run tests/unit/backend-envelope.test.ts tests/unit/backend-contract-pin.test.ts tests/integration/http-execution-v3-envelope.test.ts Refs: 1105/03-02 |
||
|
|
5c0b37e39e |
fix(contracts)!: 쓰기 뒤에도 나오는 플랫폼 code를 쓰기 전 거절로 적지 못하게 한다
문제 commandEffect.refusedBeforeWrite의 조립 검사는 code 문법, 멱등성 접두사, 중복, Envelope 여부만 본다. 계약 문서 6.1절은 BAD_PARAMETER(어느 층이든 IllegalArgumentException), MAPPING_FAILED(멱등성 응답 직렬화는 action 뒤), DB_* 8개, LOCK_ACQUISITION_TIMEOUT, fileserver code를 "쓰기 뒤 가능"으로 적는다. 이 code를 목록에 적어도 조립이 통과하고, 그 code로 온 400·409·422가 NOT_APPLIED가 된다. 쓰기 뒤에 난 실패를 사용자가 다시 저장하면 새 키나 키 없는 새 요청이 나가 같은 항목이 둘 생길 수 있다(리뷰 실험 X2: 네 code가 조립을 통과하고 모두 NOT_APPLIED). 고른 방법 6.1절의 "쓰기 뒤 가능" 플랫폼 code를 src/contracts/external-contract-runtime.ts에 PLATFORM_CODES_POSSIBLY_AFTER_WRITE로 두고, assertRefusedBeforeWrite가 그 code의 선언을 6.1절을 이유로 거절한다. 실행기의 fail-close(조립 없이 부른 경우)도 같은 목록을 무시한다. 목록을 adapters가 아니라 contracts에 둔 것은 조립 검사가 adapters를 import할 수 없기 때문이다(리뷰 문서의 최소 개선은 backend-envelope.ts에 두라고 했다). backend-contract-pin.test.ts가 계약 문서 6.1절 표의 "쓰기 뒤 가능" 행을 읽어 목록과 양방향으로 대조한다. 참조 도메인 code와 web-advanced patch code는 엔드포인트가 단계를 정하므로 테스트의 예외 목록에 적고 선언할 수 있게 둔다. 버린 대안 - 매뉴얼 문장만 둔다(현상 유지): 폼을 막는 code를 넣고 싶어지는 바로 그 자리에 통제가 없다. - 업무 code 접두사 규칙(<FEATURE>_로 시작하는 code만 허용): 다운스트림 code 이름을 강제해 과하다. 위험·한계 - 이미 이 code를 적은 다운스트림 계약은 부팅에서 조립이 실패한다. 의도한 실패다. - 6.1절 표에 플랫폼 code가 더해지면 목록도 같이 고쳐야 한다. 대조 테스트가 알린다. 백엔드가 code를 더한 것은 pin을 올릴 때 6.1절을 다시 읽어야 안다. - 업무 code를 잘못 선언하는 것은 여전히 막지 못한다(기능 작성자의 판단). - 대조 테스트는 계약 문서를 읽으므로, 문서를 복사하지 않는 기능 제거 드릴(FE-GATE-020의 optional-recipe·browser-file-storage·realtime)에서는 돌지 않는다. `scripts/lib/removal-fixture.ts`의 문서 테스트 목록에 `tests/unit/backend-contract-pin.test.ts`를 더했다. 저장소 자신의 test:unit은 그대로 돌린다. 검증 desktop batch에서 확인: node scripts/run-vitest.ts run tests/unit/external-contract-runtime.test.ts tests/unit/backend-envelope.test.ts tests/unit/backend-contract-pin.test.ts corepack pnpm test:optional-recipe-removal BREAKING CHANGE: refusedBeforeWrite에 계약 문서 6.1절이 "쓰기 뒤 가능"으로 둔 플랫폼 code(PLATFORM_CODES_POSSIBLY_AFTER_WRITE)를 적으면 composeContractContributions가 거절한다. 그 code를 목록에서 지운다. 그 code의 실패는 결과 불명으로 남는다. Refs: 1105/03-01 |
||
|
|
56272e86d5 |
fix(contracts)!: HTTP descriptor의 responseEnvelope를 필수 칸으로 둔다
문제: responseEnvelope는 descriptor의 선택 칸이고 없으면 "NONE"이다.
1103/16-01 수정은 계약 조립이 한 기여 안에서 값이 섞이면 거부하고,
refusedBeforeWrite가 있는 쓰기에 Envelope를 요구하게 했다. 그러나 읽기만
있는 기여(기본 생성 판)나 refusedBeforeWrite 없는 쓰기에서 줄을 모두 빼면
조립은 통과하고(모두 같은 NONE), 짝 백엔드의 Envelope를 DTO로 읽어
SCHEMA_MISMATCH로 깨지는 것은 손글씨 gateway 테스트만 잡는다. 지난 완료
기준("줄을 지우면 check:types가 실패한다")을 채우지 못했다.
고른 방법(1103 대안 (b)): InstalledHttpContract의 contract.responseEnvelope를
필수로 바꾼다. 생성 기능·참조 기능·예제의 descriptor는 모두
`satisfies InstalledHttpContract<...>`라 줄을 지우면 tsc가 그 자리에서
실패한다. 줄이 없던 descriptor에 "NONE" as const를 적었다: 참조 기능 셋,
tests/helpers/external-contract-fixture.ts 셋,
tests/contract/reusable-capability/feature-http-binding.test.ts,
scripts/drill-runbook.ts. 값은 전과 같아 FE-REG-API 행과 레지스트리 기준선은
바뀌지 않는다. 조립(external-contract-runtime.ts)은 그대로 빠진 값을 NONE으로
읽는다: TypeScript 밖에서 만든 descriptor를 런타임에 거부하지 않는다.
생성기 주석의 "줄을 지운다" 안내를 "NONE을 적는다"로, 매뉴얼 01(3단계,
짝 백엔드가 아닌 백엔드), errors.md, 계약 문서 4.1절을 같은 뜻으로 고쳤다.
테스트: external-contract-runtime.test.ts에 줄을 뺀 descriptor 선언 위
@ts-expect-error를 두었다. 타입이 다시 선택 칸이 되면 그 지시문이 쓰이지
않아 check:types:test가 실패한다. 같은 테스트가 런타임 조립은 NONE으로
읽는지도 본다.
버린 대안: (c) 기여 단위 기본값 — 규칙이 하나 는다. (d)만으로 두기 — 모두
빠진 경우를 못 막는다. 조립에서 빠진 키를 거부 — JS로 만든 계약 패키지가
런타임에 깨지고, 빠진 값을 일부러 다루는 테스트를 모두 바꿔야 한다.
위험·한계: descriptor를 직접 쓰는 다운스트림 코드는 줄을 더할 때까지
check:types가 실패한다. 모든 operation에 같은 틀린 값을 적는 것(짝 백엔드인데
모두 "NONE")은 여전히 타입도 조립도 통과한다(매뉴얼 "못 잡음"). 이 노트북에서
tsc를 돌리지 못해, 놓친 descriptor가 있으면 desktop check:types가 알려 준다.
검증: desktop batch에서 확인.
corepack pnpm check:types
node scripts/run-vitest.ts run tests/unit/external-contract-runtime.test.ts
tests/features/reference-feature tests/unit/api-operation-rows.test.ts
corepack pnpm check:registries (compatibility 변화 없음 기대)
BREAKING CHANGE: src/contracts/external-contract-runtime.ts의
InstalledHttpContract에서 contract.responseEnvelope가 필수다. 이 줄이 없는
descriptor는 check:types에서 실패한다. 감싸지 않는 백엔드는
responseEnvelope: "NONE" as const, 짝 백엔드(Envelope)는 "ENVELOPE_V1" as const를
operation마다 적는다. 런타임 동작은 같다.
Refs: 1103/16-01
|
||
|
|
6d084cf6a2 |
docs(manual): 기능마다 바뀌는 추적 파일 둘과 충돌 처리 명령을 적는다
문제: 기능 하나를 더하면 템플릿 추적 파일 두 개가 바뀐다.
create:feature가 public/release-manifest.json(dev server manifest)의
setDigest·packages를 다시 쓰고, 참조 기능이 있는 동안은 초기 JS 기록
(config/scale/feature-shape-ceilings.json initialJavascript)을 명령으로 다시
써야 한다. 03 문서 A절은 "생성 명령이 쓰는 폴더 밖 파일은 둘"(context 선언,
a11y 기록)이라고만 적고, 정본 표(starter-experience.md "Adding a feature")에도
두 파일이 없다. 기능 브랜치 둘은 같은 setDigest 줄을 다른 값으로 바꿔
충돌하는데, 어떻게 푸는지는 test:unit 실패 문구에만 있다.
고른 방법(리뷰 대안 (a)): 문서와 생성 출력에 두 파일, 쓰는 주체, 다시 쓰는
명령, 충돌 처리("아무 쪽이나 고르고 명령을 다시 돌린다")를 적는다.
- scripts/create-feature.ts에 FEATURE_TRACKED_FILE_REWRITES(경로·명령)를
두고 생성 출력이 충돌 처리 줄에 쓴다.
- 03 A절에 표와 충돌 단락, "기능을 지울 때"에 초기 JS 기록 재작성, 정본 표에
두 행, 01 1단계 흐름에 manifest 재작성 줄을 더했다.
- 새 단위 테스트가 그 상수의 파일·명령이 03 A절과 정본 표에 있는지 본다.
초기 JS 기록과 그 측정 스크립트 경로는 참조 기능과 함께 지워지므로 문서에서
백틱 없이 적었다(performance-evidence.md와 같은 규칙, 제거 드릴의
verify:documentation).
버린 대안(이번에 하지 않음, 결정 대기):
- (b) dev manifest를 생성 파일로 두고(.gitignore) dev·Playwright 시작 전에
만들기: 커밋 줄이 사라지지만 dev 스크립트와 Playwright webServer 명령을
바꿔야 한다. Playwright 설정은 다른 작업(12-04)이 고치는 중이다.
- (d) 초기 JS 기록이 템플릿 자신의 값만 담게 측정에서 설치된 제품 기능을
빼기: 측정 스크립트가 어떤 기능이 템플릿 것인지 알아야 한다.
위험·한계: 충돌 자체는 남는다. 두 기능 브랜치를 합칠 때 사람이 명령을 다시
돌려야 한다. 완료 기준의 둘째 길("03 A절·정본 표가 두 파일과 충돌 처리
명령을 적는다")만 채운다. 실제 두 브랜치 git merge로 재현하지 않았다.
테스트는 문서를 읽으므로, 문서를 복사하지 않는 기능 제거 드릴에서는 돌지
않는다(`scripts/lib/removal-fixture.ts`의 문서 테스트 목록).
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/feature-tracked-files.test.ts
corepack pnpm verify:documentation
corepack pnpm test:realtime-removal
Refs: 1105/16-01
|
||
|
|
dc7c95b005 |
fix(recipes): OIDC PKCE 레시피가 sessionStorage 키를 registry에서 가져온다
문제: OIDC PKCE session owner 레시피가 sign-in transaction의 sessionStorage 키를 글자 그대로 적는다 (`"ca-frontend:auth:v1:oidc-pkce-transaction"`). 주석은 `buildPhysicalKey(...)`라고 하지만 함수를 부르지 않는다. 템플릿의 다른 Web Storage 키는 모두 `src/contracts/storage-keys.ts` registry가 `APP_NAMESPACE`로 만들고, 어댑터가 직접 쓰는 키도 `backend: "external"` 행으로 둔다. 그래서 제품이 `APP_NAMESPACE`를 바꾸면(memento 설계가 예정한 일) 이 키만 `ca-frontend:`로 남고, registry는 앱이 쓰는 Web Storage 키 목록이 아니게 된다. registry로 로그아웃 때 지울 키를 정하는 제품은 버려진 sign-in의 verifier·state·nonce·돌아갈 경로를 지우지 못한다. 고른 방법: - registry에 `AUTH_REDIRECT_TRANSACTION` 행을 둔다. `scope: "auth"`, `name: "oidc-pkce-transaction"`, `backend: "external"`(pulse 키와 같은 모양, StoragePort는 거절), `ttl: "session"`. 물리 키는 지금 글자와 같다 (`ca-frontend:auth:v1:oidc-pkce-transaction`)라서 진행 중인 sign-in을 잃지 않는다. - 레시피의 `OIDC_PKCE_TRANSACTION_KEY`는 그 행의 `physicalKey`다. 매뉴얼의 복사 규칙(`../../src/` → `../`)이 새 import에도 그대로 맞는다. - 분류는 `opaque-cache`다. `sensitive-forbidden`은 "저장하지 않는다"는 뜻이고 backend가 disabled·forbidden이어야 해서 맞지 않는다. 이 값은 리다이렉트 한 번 동안 저장하는 것이 설계다. - FE-REG-STORAGE의 `orphanExemptRows`에 이 행을 더한다 (`config/contracts/registry-governance.json`). 이 행을 쓰는 곳은 레시피 하나뿐이고, 레시피는 제품이 지울 수 있다(test:optional-recipe-removal). 행은 registry로 지울 키를 정하는 제품을 위해 남는다. `AUTH_TOKEN`처럼 사용처 없이 선언만 하는 행이다. 빼지 않으면 `src`만 복사해 check:registries를 돌리는 `tests/unit/second-api-feature-registries.test.ts`가 "has no executable consumer"로 실패한다. 버린 대안: consumer 폴더에 `recipes`를 더하기. 레시피를 지운 사본(FE-GATE-020) 에서 다시 사용처가 사라진다. 버린 대안: registry에 새 분류(예: `session-transaction`)를 더하기. 계약 타입의 union과 registry 기준선의 허용 값이 함께 바뀌는데, 분류가 코드 동작을 바꾸는 곳은 `sensitive-forbidden` 검사뿐이라 얻는 것이 없다. 위험·한계: - `src/contracts/storage-keys.ts`에 행 하나가 더해진다(FE-REG-STORAGE additive). CHANGELOG [계약] 행이 필요하다. - 이미 레시피를 복사한 제품은 자기 복사본을 같은 diff로 고쳐야 키가 namespace를 따른다. - orphan 검사가 이 행을 보지 않는다. 레시피가 키를 registry에서 가져오는지는 `tests/recipes/oidc-pkce-session-owner.test.ts`가 본다. 검증: desktop batch에서 확인 - node scripts/run-vitest.ts run tests/unit/storage-registry.test.ts tests/recipes/oidc-pkce-session-owner.test.ts - corepack pnpm check:registries (additive 행) - node scripts/run-vitest.ts run tests/unit/second-api-feature-registries.test.ts - corepack pnpm test:optional-recipe-removal Refs: 1105/05-01 |
||
|
|
f600e6b132 |
fix(contracts): 짝 백엔드 pin과 drift 검사가 생성기 템플릿 사실도 대조한다
문제: create:feature --with-create가 백엔드 생성기 템플릿의 사실 넷을 프론트 문자열로 옮겼다. 경로 복수형(scripts/new-feature.sh), 이름 상한 100 (__Feature__.java.tmpl NAME_MAX_LENGTH), 오류 code <FEATURE>_INVALID· _NOT_FOUND(__Feature__ErrorCode·ControllerTest 템플릿), 201과 검사 순서 (Controller·Create__Feature__UseCase 템플릿)다. 그러나 pin (config/contracts/backend-contract-pin.json)과 check:backend-contract-drift는 docs/web/http-contract.md(1105/07-01 뒤로는 그 문서의 표 사본과 답 표)만 본다. 백엔드가 템플릿을 바꾸면 생성 기능이 다른 경로·상한·code를 써도 아무 신호가 없다. 고른 방법: pin의 backend.scaffoldSources에 백엔드 템플릿 파일 여섯과 각 파일에서 옮긴 사실, 옮긴 프론트 위치(파일과 이름)를 적는다. drift 검사는 1105/07-01의 사본·답 표 대조와 종료 코드(0 일치, 1 어긋남, 2 비교 못 함)를 그대로 두고, pin 뒤 HEAD에서 이 파일들도 diff한다. 바뀐 파일마다 다시 볼 프론트 위치를 failures에 더해 exit 1한다. pin 단위 테스트는 각 항목의 프론트 이름이 실제로 그 파일에 있는지 본다. drift 단위 테스트는 07-01의 가짜 백엔드 fixture에 생성기 템플릿 파일 하나를 더하고, 그 파일이 바뀐 경우(exit 1, 프론트 위치 출력)와 pin이 이름 붙이지 않은 파일만 바뀐 경우(exit 0, "1 scaffold sources unchanged")를 더한다. 07-01의 경우들은 그대로다. 계약 문서 4.1절과 생성기 머리 주석에 같은 내용을 적었다. 버린 대안: 백엔드가 생성기 사실을 JSON으로 내고 프론트가 읽기 — 두 repo를 바꿔야 한다(백엔드는 이번에 읽기만 한다). 위험·한계: drift 검사는 여전히 게이트 밖이고 형제 checkout이 있을 때만 돈다. 파일 단위 diff라 템플릿의 무관한 줄이 바뀌어도 알린다(사람이 다시 본다). pin의 commit(45d2a478)은 그대로다. 네 사실이 그 커밋과 같다는 대조는 리뷰(1105/16 영역)가 했고 이번에는 이름 상한만 다시 읽었다. 07-01과 같은 파일을 고쳐서 fix/r1105-contracts-core-sq 위에 다시 쌓았다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/unit/backend-contract-drift.test.ts tests/unit/backend-contract-pin.test.ts corepack pnpm check:backend-contract-drift (desktop 형제 checkout 기준, 참고) Refs: 1105/16-02 |
||
|
|
b45d6a03db |
fix(removal): 제품 기능 제거 드릴이 템플릿 테스트의 예시 ID를 잔여로 세지 않는다
문제: 매뉴얼 1단계 예시 ID는 invoice-feature이고 11단계가 `test:sample-removal -- --feature=invoice-feature`로 그 기능을 지운다. 드릴은 제품 기능의 잔여를 src·tests 모든 파일에서 기능 ID의 대소문자 무시 부분 문자열로 찾았다. 템플릿 소유 tests/unit/create-feature.test.ts가 같은 예시 ID를 데이터로 51번 쓰므로, 다른 검사가 모두 통과해도 `fixture-id-residue: residue: tests/unit/create-feature.test.ts`로 rc=1이었다 (리뷰 16-R1). errors.md의 안내는 그 템플릿 파일을 고치라는 것이었다. notice-feature, orders-feature, shop-feature 같은 이름도 같은 충돌이 난다. 고른 방법: 제품 기능의 잔여 판정을 scripts/lib/feature-residue.ts의 productFeatureResidue로 옮기고 범위를 나눈다. - src: 지금처럼 경로나 내용에 기능 ID·폴더 이름이 있으면 잔여. 플랫폼 소스는 제품 기능을 이름으로 부르지 않으므로, 남은 이름은 타입 검사가 못 보는 참조(카탈로그 키, 런타임 오버라이드, 링크)다. - tests: 파일 이름에 기능 ID가 있거나, 기능의 src/features/<dir>/ 또는 tests/features/<dir>/에서 import(동적 import, vi.mock 포함)하는 파일만 잔여. 테스트 본문에 ID를 글자로 적은 것은 세지 않는다. 지운 기능에 기대는 테스트는 같은 드릴의 test:all이 잡는다. 참조 샘플(reference-feature)은 템플릿이 모든 파일을 가지므로 기존 넓은 패턴을 그대로 쓴다. 빌드 산출물(dist) 잔여 검사도 그대로다. 단위 테스트: 저장소 자체(create-feature.test.ts 포함)를 invoice-feature로 훑으면 잔여 0, src/contracts에 ID를 남긴 파일·이름에 ID가 있는 e2e spec·기능 폴더 import는 잔여, 테스트 본문의 예시 데이터는 잔여 아님. 매뉴얼 01 11단계와 errors.md의 판정 문장·안내(템플릿 파일이 나오면 고치지 말고 템플릿에 알린다)를 고쳤다. 버린 대안: - 제거 전에 한 번 훑어 이미 걸리던 파일을 제외: src/contracts에 남긴 잔여도 제거 전부터 ID를 담고 있으므로 같이 빠진다(완료 기준 둘째를 못 지킨다). - 템플릿 테스트의 예시 ID를 예약 접두어로 바꾸기: 부분 문자열 검색이면 접두어를 붙여도 걸리고, create-feature.test.ts의 파생 이름 기대값 수십 곳을 함께 바꿔야 한다. - 생성 명령이 템플릿 테스트에 나오는 ID를 거절: 목록이 따로 낡는다. 위험·한계: tests 안에서 기능 ID를 글자로만 담은 진짜 잔여(예: 기능을 import하지 않고 경로 문자열만 적은 테스트)는 이제 잔여로 나오지 않는다. 그런 테스트가 지운 기능에 기대면 test:all이 실패하고, 기대지 않으면 해가 없다. src 쪽 부분 문자열 검색은 그대로라 items 같은 짧은 ID는 플랫폼 소스의 글자에 여전히 걸릴 수 있다(이번 범위 밖). 실제 드릴 실행(198초)은 단위 테스트로 대신하지 못한다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/unit/feature-residue.test.ts 16-R1과 같은 순서: create:feature invoice-feature --with-create --keyed 뒤 corepack pnpm test:sample-removal -- --feature=invoice-feature (rc=0 기대), 그리고 src/contracts/invoice-leftover.ts에 "invoice-feature"를 남긴 변이에서 rc=1(fixture-id-residue) 기대 Refs: 1105/16-04 |
||
|
|
81701add7e |
feat(perf): lab이 기능 라우트 첫 진입을 재고 500 ms 예산으로 판정한다
문제: lab(FE-GATE-026)은 플랫폼 구성 화면(EXAMPLES_PLATFORM) 하나만 잰다.
이 화면은 기능 코드를 받지 않아 기능을 더해도 수치가 거의 그대로다
(146 → 154 ms). 기능 라우트는 처음 들어갈 때 context 라우트 모듈과 기능
실행부를 받고, 그다음 페이지 청크를 받는 두 번의 요청 묶음을 거친다.
lab 조건에서 EXAMPLES_UI 첫 진입은 중앙값 406 ms(403~410, 리뷰 15-R1)로
대상 화면의 2.7배인데 어느 게이트도 재지 않는다. 다운스트림의 화면은
모두 기능 라우트다.
고른 방법:
- labFeatureRoute(scripts/lib/lab-performance.ts): 설치된 기능이 가진,
세션 없이 열리는 첫 내비게이션 라우트. 템플릿에서는 EXAMPLES_UI다.
없으면 null이고 lab은 measured: false로 남기고 판정하지 않는다.
- lab은 run마다 `/`에서 그 라우트의 내비게이션 링크를 눌러 heading까지를
같은 페이지 시계로 잰다(새 cold context). metrics.featureRouteInteractionMs
(중앙값), context.sampling.featureRoute(표본, owner)에 남긴다. 기존 대상
라우트와 그 예산(200 ms)은 그대로라 회귀 비교가 이어진다.
- 예산 config/performance/budgets.json lab.featureRouteInteractionMs = 500 ms.
측정 406 ms(
|
||
|
|
138c195fcd |
fix(examples): 릴리스 신원 칸의 자리를 미리 잡고 lab이 대상 화면 직접 진입 CLS를 잰다
문제: 플랫폼 구성 화면(lab 대상)은 getReleaseSummary()가 끝날 때까지 릴리스 신원 칸을 "상태" 한 칸으로 그리고, 끝나면 hint 줄이 있는 네 칸으로 바꾼다. 제목이 보인 뒤 약 30~100 ms에 grid가 hint 한 줄만큼 커져 아래 section이 21 px 내려간다(layout shift 0.00461, 리뷰 15-platform-shift 16회). lab은 `/`에서 클릭으로만 들어가고, 클릭 뒤 500 ms 안의 shift는 hadRecentInput이라 CLS에서 빠지므로 0을 낸다. `/` 밖의 라우트 CLS는 어느 게이트도 보지 않는다. 고른 방법: - 화면: 요약 전·실패 때도 같은 네 칸(빌드·릴리스·설정 스키마·계약 집합 다이제스트)을 같은 hint 줄 구성으로 그린다. 값만 "확인하고 있습니다." / "확인하지 못했습니다." / "—"다. 상태 문장은 가장 좁은 칸(13rem)에서도 한 줄이 되게 짧게 했다. dl에 aria-busy를 둔다. 시각 테스트는 이미 `main [aria-busy='true']`가 0개가 될 때까지 기다리므로, dt만 보고 찍던 대기가 값이 채워진 뒤로 유지된다. - lab: run마다 대상 라우트를 새 context에서 직접 열고 heading 뒤 network idle까지의 CLS를 잰다(metrics.targetDeepLinkCls, 중앙값, context.sampling.targetDeepLink에 표본). evaluateLabBudget가 lab.cls 임계값으로 판정한다. 클릭 시계(상호작용 중앙값)와 대상 라우트는 그대로다. - 컴포넌트 테스트: 요약 전과 후의 칸 이름·hint 유무가 같다. 실패 테스트는 빌드 칸의 값으로 본다. 단위 테스트: 직접 진입 CLS가 임계값을 넘으면 lab 판정이 실패한다. 버린 대안: 릴리스 요약을 동기로 읽기 — getReleaseSummary()가 비동기 포트 계약이라 포트를 바꿔야 한다. 클릭 run에서 hadRecentInput을 무시 — CLS 정의와 달라져 field 값과 비교할 수 없다. 위험·한계: lab 시간이 run마다 cold navigation 하나(lab 조건 약 2~3초) 늘어 5회면 +10~15초다. 직접 진입 CLS 예산은 0.1이라 0.0046 같은 작은 shift는 실패시키지 않고 lab.json에 값으로만 남는다. layout shift 0건은 lab 값(0)과 15-platform-shift 방법으로 확인해야 한다. 상태 문구가 바뀌어 "런타임 정보를 확인하고 있습니다." 문장은 이 화면에서 사라졌다(홈 화면 문구는 그대로). lab.json 스키마 문서(config/schemas/lab-performance.schema.json)에 새 칸을 필수로 더했다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/component/starter-platform-overview-page.test.tsx tests/unit/performance-budgets.test.ts corepack pnpm build && corepack pnpm test:performance -- --runs=5 (lab.json metrics.targetDeepLinkCls가 0인지) Refs: 1105/15-01 |
||
|
|
e02f252d57 |
fix(theme): 스크롤바 자리를 첫 화면부터 잡고 lab을 스크롤바와 함께 잰다
문제: 라우트 로딩 화면(280 px)은 720 px 창에 들고 홈 화면(732 px 문서)은
넘친다. 일반(overlay가 아닌) 스크롤바를 쓰는 브라우저에서 홈이 그려지는
프레임에 세로 스크롤바가 생겨 너비가 15 px 줄고 header 오른쪽(세션 영역)이
15 px 밀린다(1280x720·1366x657에서 CLS 0.0002, 리뷰 15-R2 12회). lab과 모든
게이트의 Playwright Chromium은 --hide-scrollbars로 떠서 이 shift를 못 본다.
고른 방법:
- base.css의 :root에 scrollbar-gutter: stable을 둔다. 스크롤바 자리가
첫 프레임부터 있어 내용이 길어져도 너비가 바뀌지 않는다. overlay
스크롤바(macOS 기본)는 어느 쪽이든 자리를 쓰지 않는다.
- lab(scripts/test-performance.ts)은 labBrowserLaunchOptions()로
--hide-scrollbars를 빼고 띄운다. lab.json context.browser에
scrollbars: "visible"을 남긴다. 이제 lab의 `/` CLS가 같은 회귀를 본다.
- 단위 테스트: 실행 옵션이 --hide-scrollbars를 빼는지, :root에
scrollbar-gutter: stable이 있는지.
- 시각 골든 5장을 새 gutter에 맞춰 desktop에서 다시 찍는다
(test:visual:update).
버린 대안: html { overflow-y: scroll } — 짧은 화면에도 빈 스크롤바를
그린다.
위험·한계: 스크롤바 폭만큼 오른쪽 여백이 짧은 화면에서도 늘 생긴다.
--hide-scrollbars로 뜬 Chromium도 gutter 자리를 잡는다. 그래서 시각 골든
5장이 모두 바뀌었다. 바뀐 것은 내용 폭 15 px다(main 1040 → 1025 px).
compact(390 px) 골든은 줄바꿈이 늘어 1297 → 1377 px로 길어졌다. 실제
휴대폰은 overlay 스크롤바라 자리를 쓰지 않으므로, compact 골든은 휴대폰
화면보다 15 px 좁게 그린다. 열린 drawer의 가림막은 gutter를 덮지 않는다
(일반 스크롤바 브라우저에서는 그 자리에 스크롤바가 그려진다). lab의 CLS 예산
0.1은 그대로라 0.0002 shift가 다시 생겨도 lab은 통과한다(값만 남는다).
Firefox·Windows 스크롤바 폭은 재지 않았다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/lab-performance.test.ts
corepack pnpm test:visual (부모 d5b6aeba에서 6건 통과, 이 변경은 옛
골든과 5건이 달라 실패, 다시 찍은 골든에서 통과)
corepack pnpm build && corepack pnpm test:performance -- --runs=5
Refs: 1105/15-05
|
||
|
|
46359a1c79 |
fix(scale): 초기 JS 기록 대조의 합계 허용 오차를 256 B로 둔다
문제: initialJavascriptRecordDrift가 합계를 1%까지 같다고 본다. 202,927 B에서 1%는 2,029 B로, 남은 여유 1,873 B와 기능 하나(768 B)보다 크다. 템플릿 변경이 여유를 다 써도 기록을 다시 쓰지 않은 채 test:unit을 통과하고, 기록을 인용한 문서는 없는 여유를 말한다. 단위 테스트는 1,500 B 차이를 "같음"으로 고정했다. 고른 방법: 합계만 바이트 상한 256 B(INITIAL_JAVASCRIPT_RECORD_TOLERANCE_BYTES)로 바꾼다. build id 차이(기록된 실행 사이 6 B, 48 B)는 넘고 기능 하나보다는 작다. 기능·context 비용(10%)과 파일 수(정확)는 그대로다. 단위 테스트는 48 B·200 B 차이는 통과, 300 B 증가와 1,500 B 차이는 실패로 고정한다. performance-evidence.md의 "합계 1% 초과" 문장을 고쳤다. 버린 대안: 여유 자체를 기록해 대조 — 예산이 바뀔 때마다 같이 바뀌어 더 쉽게 낡는다. 위험·한계: 초기 JS를 수백 바이트 움직이는 템플릿 변경마다 기록을 다시 써야 한다(의도). CI와 로컬의 build id 차이가 256 B를 넘는 일이 생기면 test:unit이 흔들린다. 지금까지 본 차이는 50 B 안이다. 이 커밋은 기록 숫자를 바꾸지 않는다. 현재 기록과 빌드의 차이는 0 B였다(리뷰 15-lab). 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/unit/feature-shape-growth.test.ts Refs: 1105/15-02 |
||
|
|
7ead8d369a |
fix(test): test:all이 test:coverage가 도는 Vitest 경로를 모두 돌린다
문제 taxonomy는 test:all을 일상 개발 루프라고 적는다. 그런데 test:all은 tests/features 중 참조 샘플만(test:reference-feature) 돌리고, test:coverage(FE-GATE-005)가 도는 tests/features의 나머지(설치 표면, feature-module, 예제 기능 2파일), tests/scripts, tests/scale/browser-soak.contract.test.ts를 빠뜨린다. 로컬에서 초록이고 CI에서 빨강이 될 수 있다. 고른 방법과 버린 대안 - package.json test:all의 test:reference-feature 자리를 tests/features 전체 + tests/scripts + browser-soak 계약 테스트를 한 번에 도는 Vitest 실행으로 바꾼다. 참조 샘플 테스트도 tests/features 안이라 그대로 돈다. 샘플을 지우면 그 폴더만 빠진다. - tests/unit/test-all-paths.test.ts(새 파일): package script graph로 test:all과 test:coverage의 Vitest 경로를 모아, coverage 쪽 경로가 모두 test:all 경로 안에 있는지 본다. 다시 빠지면 이 테스트가 잡는다. - 새 package script(test:features)를 만드는 안은 버렸다. 그 이름이 tests/scripts까지 도는 것을 말하지 못하고, test:all만 쓰는 스크립트가 하나 늘 뿐이다. - taxonomy에 "CI와 같은 집합은 test:coverage"라고만 적는 안은 버렸다. 완료 기준(test:all ⊇ test:coverage의 Vitest 파일)을 못 채운다. - docs/testing/taxonomy.md의 test:all 설명을 바꾼다. 위험·한계 - 제거 드릴 셋(optional recipe, realtime, browser-file-storage)은 fixture 안에서 test:all만 돈다. 이제 이 파일들도 그 fixture에서 처음 돈다. import를 보면 제거 대상에 기대지 않지만 실행으로는 확인하지 못했다. 드릴 시간이 몇 초씩 는다(1101/10-06과 반대 방향). 검증 - desktop batch에서 확인: node scripts/run-vitest.ts run tests/unit/test-all-paths.test.ts corepack pnpm test:all, corepack pnpm check:ci, FE-GATE-020 - RED: 부모 커밋의 package.json에서 "runs every Vitest path test:coverage runs"가 tests/features·tests/scripts·browser-soak 경로를 빠졌다고 실패한다. Refs: 0929/10-05 |
||
|
|
757d1c736b |
fix(a11y)!: 실패 화면으로만 검사한 라우트를 a11y.json에서 통과로 세지 않는다
문제
접근성 e2e는 보호 라우트의 목록 조회에 빈 목록을 답한다. 자원 하나를
읽는 상세 라우트(참조 기능의 상세, 생성기 --with-create의 상세)는
일반 답이 없어 실패 화면에서 axe를 돌린다. 그런데
scripts/write-a11y-report.ts는 설치된 라우트 전체를 scope에 넣고
automatedStatus "passed"를 쓴다. 화면 내용은 한 번도 검사하지 않은
라우트가 통과로 보고된다. annotation은 test 결과에만 남는다.
고른 방법과 버린 대안
- scripts/lib/a11y-data-state.ts(새 파일): 라우트 test가 끝날 때
자기 상태를 artifacts/tests/a11y-data-state/<ROUTE_ID>.json에 남긴다.
실패 화면으로만 봤으면 이유를 쓰고, 아니면 지운다. 그래서 라우트마다
마지막 실행이 정한다. 세 엔진이 같은 파일을 쓰므로 임시 파일에 쓰고
rename한다.
- tests/e2e/accessibility.spec.ts: 위 기록을 남긴다(공개 라우트와
데이터 상태로 본 라우트는 지운다).
- a11y.json schemaVersion 2: scope에는 자기 상태로 검사한 라우트만,
notChecked에는 실패 화면으로만 본 라우트와 이유를 넣는다. 둘을
합치면 설치된 라우트 레지스트리와 같아야 한다(schema가 본다).
- 상세 라우트를 실제 데이터 상태로 검사하는 안은 버렸다. 출력
validator에서 유효한 값을 일반적으로 만들 수 없고, 기능마다 견본
응답을 받는 자리를 새로 열어야 한다.
- annotation을 Playwright JSON reporter로 읽는 안은 버렸다. test:a11y
스크립트의 reporter와 산출물 경로를 바꿔야 하고, 경로는 다른 작업
(12-04)이 바꾸는 중이다.
- 매뉴얼(docs/manual/reference/create-feature.md)에 상세 라우트가
notChecked로 적히고 수동 검토가 맡는다고 적는다.
위험·한계
- a11y.json 모양이 바뀐다(schemaVersion 1 → 2, scope 의미, 새 필드).
템플릿 안의 소비자는 ci-artifact-validator 하나이고 같이 바꿨다.
- 템플릿 상태에서도 참조 기능의 상세 라우트가 notChecked로 나온다.
지금까지 실제로 검사하지 않던 것이 드러나는 것이다.
- 기록 디렉터리는 artifacts/tests 아래 고정 경로다. 12-04가 산출물
경로를 실행마다 나누면 이 경로도 따라가야 한다.
- 라우트 test가 돌지 않은 실행에서는 그 라우트의 지난 기록이 남는다.
지난 기록이 "검사 안 함"이면 덜 주장하는 쪽이라 위험하지 않다.
검증
- desktop batch에서 확인:
node scripts/run-vitest.ts run tests/unit/a11y-report.test.ts
corepack pnpm test:a11y (세 엔진) 뒤 artifacts/tests/a11y.json의
notChecked에 REFERENCE_RESOURCE_DETAIL이 있고 scope에 없어야 한다.
- RED: 부모 커밋에는 scripts/lib/a11y-data-state.ts가 없어 새 unit
test 파일 전체가 실패한다.
Refs: 1103/11-01
BREAKING CHANGE: artifacts/tests/a11y.json이 schemaVersion 2가 된다. scope는 실패 화면으로만 본 라우트를 빼고, 그 라우트는 새 notChecked 배열에 { routeId, reason }으로 들어간다. scope를 설치된 라우트 전체로 읽던 도구는 scope와 notChecked를 합쳐 읽는다.
|
||
|
|
e02552998d |
test(e2e): strict fixture가 preload 기록으로 test를 실패시키는지 고정한다
문제
tests/e2e/preload-use.spec.ts는 preload tracker만 증명한다. 안 쓴
preload를 넣는 test는 맨 test에서 tracker를 직접 부르고, strict
fixture를 쓰는 test는 "통과해야 한다" 방향 하나뿐이다. 그래서
strict-browser-test.ts가 tracker 결과를 버려도(11-R3) 커밋된 test는
하나도 실패하지 않았고, WebKit 무시 정규식을 넓혀도 볼 test가 없다.
3번 test는 지연시킬 청크를 못 찾으면 조용히 평범한 방문이 된다.
고른 방법과 버린 대안
- strict fixture의 마지막 판정을 browserFailureVerdict fixture로
뺀다. 기본값은 지금과 같다(allowedBrowserFailure로 거르고 빈 목록
단언). page fixture는 기록을 그 판정에 넘긴다.
- spec은 그 판정을 "기록을 받아 두는" 판정으로 바꾼 recordedTest를
둔다. page fixture가 판정에 의존하므로 판정의 teardown은 page
teardown 뒤에 돈다. 거기서 fixture가 넘긴 줄이 fixtureReports와 정확히
같은지 본다.
- 안 쓴 modulepreload 하나 → `preloadunused:/assets/<청크>.js` 한 줄.
- WebKit 문구 그대로(무시), Chromium 문구, WebKit 문구 + 뒤 글자,
같은 문구의 console.error, 다른 warning → 뒤의 네 줄만, 순서대로.
- 기본 판정이 실제로 test를 실패시키는지는 strictTest.fail()로 console
error 한 줄을 내는 test 하나가 본다. 기록이 맞다는 것은 위 두 test가
따로 증명하므로, 이 test가 엉뚱한 이유로 실패해도 놓치는 것이 적다.
- 3번 test는 지연시킬 청크가 없으면 이유를 적고 실패한다.
- 모든 probe를 test.fail()로만 고정하는 안은 버렸다. 어떤 이유로든
실패하면 통과해서 fixture가 무엇을 기록했는지 보지 못한다.
- 커밋한 문서: docs/testing/frontend-platform-testing-strategy.md에
증명 위치와 판정을 바꾸는 곳이 그 spec 하나라는 것을 적는다.
위험·한계
- 모든 browser spec이 쓰는 fixture의 구조가 바뀐다. 판정 내용은 같다.
- 다른 spec도 browserFailureVerdict를 바꿔 strict 검사를 끌 수 있다.
allowedBrowserFailure를 /.*/로 주는 것과 같은 수준의 노출이고 막는
검사는 더하지 않았다.
- 샘플을 지운 제품에서 기능 실행부 모양이 바뀌면 3번 test가 실패한다.
그때는 test를 다른 청크로 옮기거나 이유를 적고 지워야 한다.
검증
- desktop batch에서 확인:
corepack pnpm exec playwright test tests/e2e/preload-use.spec.ts (세 엔진)
- 테스트 장치만 바꾼 커밋이라 RED는 변이로 본다.
- 11-R3(strict fixture가 check 결과를 버림): "records a modulepreload
the page never runs"가 세 엔진에서 실패해야 한다.
- WEBKIT_UNUSED_PRELOAD_GUESS를 /.*/로: "ignores WebKit's
unused-preload guess word for word and nothing else"가 실패해야 한다.
- browserFailureVerdict 기본값의 expect 제거: "fails a test whose page
writes a console error"가 "expected to fail" 위반으로 실패해야 한다.
Refs: 1105/11-01
|
||
|
|
a37ebba39c |
fix(architecture): 기능 안 계층 밖 폴더가 src/adapters에 닿으면 막는다
문제 feature-and-app-roots-do-not-reach-adapters는 기능 루트 파일 (src/features/*.ts, src/features/<id>/*.ts), src/contexts, src/apps만 본다. 그래프는 간선 하나씩 검사하므로, 기능 안에 계층이 아닌 폴더(support/ 등)를 만들어 그 파일이 http adapter 배럴을 import하고 기능 presentation이 그 파일을 import하면 presentation이 구체 adapter에 닿는다. 1105 리뷰 12-R3 변이에서 check:architecture와 ESLint가 둘 다 통과했다. 고른 방법 - 규칙의 from을 "src/features 아래 모든 파일, 기능의 adapters/ 폴더 밖"으로 바꾼다(`^src/(features/|contexts/|apps/)`, pathNot `^src/features/([^/]+/adapters/|feature-adapter-contribution\.ts$)`). 규칙 주석이 이미 "기능 안에서는 adapters/ 폴더만 src/adapters에 닿는다"고 적고 있었고, 그 문장을 경로로 옮긴 것이다. 파일 단위 예외는 기존 하나 (feature-adapter-contribution.ts, type only) 그대로고 새로 더하지 않았다. - domain·application·presentation은 자기 규칙이 이미 src/adapters를 막는다. 이제 그 파일들이 src/adapters를 import하면 이 규칙도 같이 걸린다(위반 두 줄). 더 엄격해질 뿐 허용이 바뀌지는 않는다. - 지금 src/features에서 src/adapters를 import하는 곳은 reference-feature의 adapters/ 두 파일과 feature-adapter-contribution.ts뿐이라 새 위반은 없다. create:feature가 만드는 adapter import도 adapters/ 안이다. - 그래프 회귀 fixture에 support/ 재수출(거절), 그것을 읽는 presentation, 기능 adapters/ import(허용)를 더하고 check:architecture에 두 단언을 더했다. 규칙 경로를 check:architecture와 같은 방식으로 읽는 vitest 테스트를 더했다. - layers.md 표와 매뉴얼 01의 설명을 고쳤다. - 버린 대안: 계층 밖 폴더 자체를 금지(폴더 이름 목록 검사). 제품이 contracts/ 같은 다른 이름을 쓰면 계속 목록을 고쳐야 한다. 규칙마다 support/ 패턴 추가: 다음 폴더 이름에서 같은 틈이 난다. 위험·한계 - 다운스트림이 기능 안 adapters/ 밖에서 src/adapters를 import하고 있었다면 이제 check:architecture가 실패한다. 그 파일을 adapters/로 옮기면 된다. - ESLint는 여전히 간선 하나만 보므로 이 경로를 잡지 않는다. 그래프가 잡는다. 검증 - desktop batch에서 확인: node scripts/run-vitest.ts run tests/architecture/feature-adapter-reach.test.ts, corepack pnpm check:architecture(그래프 fixture 단언 2개 추가 PASS, 저장소 위반 0 기대). - RED 기대: "rejects a concrete adapter import from a feature folder that is not a layer", "leaves a feature's adapters folder and the type-only contribution file to reach adapters"(support/adapters/ 경로 단언). Refs: 0929/12-03 |
||
|
|
e72fb6e290 |
docs(testing): 테스트 전략이 지운 auth-recovery 테스트 대신 V3의 401 판정을 가리킨다
문제
docs/testing/frontend-platform-testing-strategy.md 11.2절이 "401 뒤 인증 복구
흐름은 tests/integration/auth-recovery.test.ts가 다룬다"고 적는다. 그 파일은
V2 클라이언트를 지울 때(
|
||
|
|
92d5019c6d |
fix(ci): 제품 merge 게이트가 실패하면 같은 run의 release 단계를 멈춘다
문제 제품 overlay(config/ci/product-gates.json)의 mergeGates는 product_merge_gate job으로 렌더링되는데, 다른 job이 이 job을 기다리지 않는다. release_gate는 merge_gate만 기다린다. 그래서 제품 검사(예: 짝 백엔드 계약 검사)가 실패해도 같은 run의 release·immutable_build·promotion·deployment는 그대로 돈다. 브랜치 필수 검사는 PR merge만 막는다. job 그래프는 계약이 고정해서(ci-gates.ts의 expectedJobGraph) 제품이 연결을 더할 방법도 없다. 고른 방법 - overlay에 게이트가 있으면 release_gate의 needs에 product_merge_gate를 더해 렌더링한다(`needs: [merge_gate, product_merge_gate]`). release_gate는 release 단계의 첫 job이고 뒤의 job은 모두 그것을 거쳐 기다린다. 템플릿 게이트가 release를 막는 방식과 같다. - 연결은 렌더링에서만 더한다. gates.json과 계약 그래프 검사는 그대로라 템플릿 job 그래프와 check:ci의 엄격함은 바뀌지 않는다. 게이트가 없으면 workflow 바이트가 같다(.gitea/workflows/quality-gates.yml 변경 없음). - workflowGateExecutionFailures(check:ci가 부름)가 제품 게이트가 있는데 release_gate가 product_merge_gate를 기다리지 않는 workflow를 거절한다. "실행된다"와 "막는다"를 따로 본다. - 문서(ci-quality-gates.md, README)에 release 단계가 제품 job을 기다린다고 적었다. - 버린 대안: (a) 문서에만 "막지 않는다"고 적기. 제품이 막을 방법이 계속 없다. (c) 게이트마다 blocksRelease 칸. 선택권은 주지만 칸이 늘고, 불안정한 제품 검사가 생기기 전에는 필요가 없다. 계약 그래프 검사에 overlay 예외를 넣는 것: 템플릿 계약이 제품 overlay를 알아야 한다. 위험·한계 - 불안정한 제품 게이트는 이제 release도 멈춘다. 그때는 (c)로 간다. - Gitea가 needs와 기본 success() 조건을 GitHub Actions처럼 처리한다고 본다. 실제 runner에서는 확인하지 못했다(Actions 꺼짐). - 제품 게이트를 이미 쓰는 다운스트림은 generate:ci-workflow를 다시 돌려야 check:ci를 통과한다(생성 YAML의 release_gate needs 한 줄이 바뀐다). 검증 - desktop batch에서 확인: node scripts/run-vitest.ts run tests/unit/product-ci-overlay.test.ts tests/unit/ci-workflow-generation.test.ts, corepack pnpm check:ci. - RED 기대: "holds the release stage until the product merge gates pass", "runs product merge gates in a job of their own, apart from the template gates". Refs: 1105/13-02 |
||
|
|
aa5d8e6c12 | chore(review): 1105 업로드 client 조치 브랜치를 합친다 | ||
|
|
fc95672ad5 |
fix(docs): 문서 검사가 짝 백엔드 참조를 pin 커밋의 트리에서 찾는다
문제 verify:documentation(FE-GATE-017)은 짝 백엔드 경로·링크를 옆 checkout의 작업 트리에서 찾았다. 그래서 같은 커밋이 놓인 곳마다 결과가 달랐다. desktop은 옆 checkout이 ef947e5(9월)에 미커밋 변경까지 있어 문서와 무관하게 rc=1, 짝이 없는 worktree는 PASS(17개 미확인)였다. 옆 checkout이 pin보다 새로우면 pin에 없는 파일을 적어도 통과하고, 저장소 이름을 틀린 `../` 링크는 "확인 못 함"으로 통과했다. config/contracts/backend-contract-pin.json은 읽지 않았다. 고른 방법 - 짝 저장소 목록과 기준 커밋을 pin 파일에서 읽는다. pin은 문서와 같이 작업 디렉터리에서 읽는다(문서가 어느 커밋을 설명하는지 적은 파일이라서). - 옆 checkout에 pin 커밋이 있으면 `git ls-tree -r -t <pin>`으로 그 커밋의 트리(파일과 폴더)를 한 번 읽어 찾는다. 작업 트리와 HEAD는 보지 않는다. hook이 넘긴 GIT_DIR 같은 GIT_* 변수는 지우고 git을 부른다. - checkout이 없거나, pin 커밋이 없거나, git이 읽지 못하면 실패 대신 unverifiedLinks로 남기고, 출력에 이유(짝 HEAD, pin 앞 12자)를 적는다. - `../`로 나가는 링크의 첫 폴더가 pin에 없는 저장소면 missingPaths로 실패한다. 실패하면 "pin 커밋에서 찾았다"는 줄을 stderr에 하나 더 적는다. - 버린 대안: 짝 HEAD가 pin과 다르면 전부 unverified(리뷰 (c)). 더 단순하지만 pin 뒤로 앞서 있는 흔한 checkout에서 아무것도 확인하지 못한다. 경로마다 `git cat-file -e`: 같은 결과지만 참조 수만큼 프로세스를 띄운다. 위험·한계 - pin 커밋을 fetch하지 않은 checkout(desktop 지금 상태)에서는 짝 참조가 전부 "not verified"다. 실패하지 않는 대신 확인도 하지 않는다. - 짝 저장소는 여전히 하나(pin 파일의 backend)다. 둘째 짝이 생기면 pin 모양부터 바꿔야 한다. - pin 파일이 없으면 짝 저장소가 없는 것으로 보고 `../` 링크를 전부 실패로 센다. - 보고서 schema는 그대로다(unverifiedLinks 주석만 고침). 검증 - desktop batch에서 확인: node scripts/run-vitest.ts run tests/unit/documentation-readiness.test.ts, 그리고 corepack pnpm verify:documentation(옆 짝이 ef947e5인 desktop에서 PASS_SCOPED + not verified 기대). - RED 기대: "looks a reference up in the pinned commit, not in a later HEAD or the working tree", "reports the references as not verified when the checkout does not have the pinned commit", "fails a link out of the repository into a repository that is not paired". Refs: 1105/12-02 |
||
|
|
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 |
||
|
|
00076992f7 |
fix(recipes): 쿠키 세션 모드의 서버 401을 템플릿 세션에 잇는다
문제: 짝 백엔드 Redis session 모드를 쿠키 recipe와 매뉴얼 04 4.3대로 이으면 서버 401이 세션에 닿지 않는다. 1103/09-01 수정 뒤 조립 루트는 제품 provider 프로필의 401을 제품의 선택 hook `onCredentialRejected`에만 알린다. 쿠키 모드의 operation은 모두 제품 프로필(SESSION_COOKIE_*)인데 매뉴얼 예시는 그 hook을 잇지 않았고, recipe와 매뉴얼은 "서버 401 → unauthenticated"라고 적었다. 이으려 해도 ProductCompositionContext에 세션에 알릴 길이 없었다. 리뷰 09-cookie401에서 세션 만료 뒤에도 상태가 authenticated, 이전 scope가 current로 남았다. 고른 방법: 두 가지를 더했다. - ProductCompositionContext.notifySessionUnauthenticated(): 템플릿 세션의 자기 401과 같은 판정(authSession.onUnauthenticated)을 제품이 부를 수 있게 한다(리뷰 안 C). - recipe의 createSessionCookieRejectionHandler(context): SESSION_COOKIE_* 프로필의 401만 세션에 넘긴다. 다른 제품 프로필의 401은 넘기지 않으므로 1103/09-01의 완료 기준(세션과 무관한 provider의 401은 로그아웃시키지 않는다)은 그대로다. 매뉴얼 04 4.3 예시에 `onCredentialRejected` 한 줄을 넣고, recipe 주석, 매뉴얼 04 흐름도, 매뉴얼 02 5절과 7절 업로드 예시(BACKEND_SESSION 쿠키 세션)를 맞췄다. 버린 대안: recipe가 owner와 provider를 한 번에 만드는 함수(안 B). owner는 composeProductSessionOwner, provider는 composeProduct 에서 따로 만들어져 모듈 변수가 필요하다. provider 선언에 "세션 자격 증명" 표시를 두는 안(D)은 계약 칸이 늘고 판정이 선언과 hook 둘로 갈린다. 위험·한계: 제품이 이 한 줄을 빼면 여전히 세션 만료를 모른다. 이것을 막는 검사는 없다(매뉴얼과 recipe 주석이 적는다). 이미 recipe를 복사한 다운스트림은 handler를 복사본에 옮기고 composeProduct에 한 줄을 더해야 한다. ProductCompositionContext에 칸이 하나 늘었다. 이 context는 템플릿만 만들므로 제품 코드는 깨지지 않는다. 실제 Redis 백엔드에는 붙이지 않았다(1103/09-03 남은 부분). 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/recipes/session-owners-runtime.test.ts tests/recipes/cookie-session-owner.test.ts 조립 루트를 지나는 테스트가 매뉴얼 4.3 연결로 쿠키 읽기·쓰기 401 뒤 세션 unauthenticated, 이전 scope not current를 본다. Refs: 1105/09-02 |
||
|
|
8e9fb1fde6 |
fix(cache-storage): 다시 stage하면 계속 읽히지 않는 캐시 본문을 다시 쓴다
문제: 2026-11-03 02-02 수정 뒤 저장된 본문을 읽지 못하면(`UNAVAILABLE`· `NOT_READABLE`) 손상이 아니라 "모름"이다. stage 재사용 경로는 "모름"이면 실패를 돌려주고 다시 받지 않는다. 그래서 다시 쓰기 전까지 계속 읽히지 않는 entry(blob 손실 등)는 다시 stage해도 고쳐지지 않는다(리뷰 실험 E-1). - 새 후보: activate가 `RETRY`를 안내하는데 다시 해도 같다. cleanup으로 후보를 지운 뒤에야 풀린다. - rollback 대상: cleanup도 지우지 않아 되돌릴 길이 없다. - 서비스 중 release: 그 asset 조회가 계속 `UNAVAILABLE`이다. 수정 전 판정에서는 같은 상태가 다시 stage 한 번으로 풀렸다. 고른 방법(리뷰 대안 (나)): - 판정에 `UNREADABLE`(entry는 있는데 본문 읽기가 실패)을 따로 둔다. `UNKNOWN`은 중단(`ABORTED`)과 `cache.match` 자체의 실패만 뜻한다. - stage 재사용 경로는 `REPAIRABLE`처럼 `UNREADABLE`도 모든 asset을 다시 받아 같은 cache에 덮어쓴다. 덮어쓰는 것은 digest로 검증한 같은 바이트이고 cache를 지우지 않으므로 서비스 중인 release를 해치지 않는다 (STO-RR-04가 막는 것은 삭제다). - activation은 지금처럼 본문 읽기 실패를 손상으로 보고하지 않고 code를 그대로 둔다. recovery만 `REHYDRATE`(같은 manifest로 다시 stage)로 바꾼다. - 조회는 그대로 `UNAVAILABLE`/`RETRY`다. - `cache.match`가 던지는 경우는 리뷰가 제안한 "중단 제외 UNKNOWN 전부"에서 뺐다. Cache Storage 자체가 응답하지 않을 때 모든 asset을 다시 받는 것은 고치는 것이 없고, 2026-11-01 02-03 테스트가 그 경우의 실패 보고를 고정한다. 버린 대안: - (가) 문서에 "cleanup 뒤 다시 stage"만 적기: rollback 대상은 못 고친다. - (다) 실패한 entry만 다시 받기: 비용은 가장 작지만 stage 경로를 entry 단위로 나눠야 한다. 위험·한계: - 일시적인 본문 읽기 오류에도 다시 stage하면 모든 asset을 다시 받는다 (수정 전과 같은 비용). - 실제 브라우저에서 본문 읽기 실패가 지속되는지, 어떤 오류 이름으로 오는지는 확인하지 못했다. 테스트는 메모리 fake에 오류를 주입한다. - service-worker-pwa 번들 여유가 342 B다(FE-GATE-012). 늘어난 코드는 분기 둘이다. 검증: desktop batch에서 확인 - node scripts/run-vitest.ts run tests/unit/public-response-cache-repair.test.ts tests/unit/public-response-cache.test.ts tests/unit/public-response-cache-codec.test.ts tests/recipes/browser-file-storage-contracts.test.ts - corepack pnpm check:optional-recipes (번들 예산) Refs: 1105/02-02 |
||
|
|
fdc1db9471 |
feat(bootstrap): 제품이 SW blockers·observe를 composeProduct로 넘긴다
문제: SW를 켜는 선택은 제품 소유 `product-capabilities.ts`로 옮겼다
(1103/09-05 일부). 그런데 저장하지 않은 편집이 있는 탭의 활성화 거절
(`blockers`)과 page controller 관측(`observe`)은 템플릿 소유
`src/bootstrap/create-runtime-composition.ts`를 고쳐야 이어진다(매뉴얼 03
"SW 켜기", 레시피 "Service Worker를 켤 때 확인할 것" 2·3). 그 파일을 고친
제품은 템플릿 동기화마다 충돌한다.
고른 방법: 기존 제품 확장 지점에 선택 칸 하나를 더한다.
`ProductComposition.serviceWorker?: { blockers?, observe? }`
(`product-composition-contract.ts`). `createRuntimeAdapters`가 `composeProduct`
결과의 이 칸을 bundle에 `productServiceWorker`로 싣고, 템플릿 조립
(`create-runtime-composition.ts`)이 telemetry와 같은 방식으로 받아
`createOptionalRuntimeHost`에 넘긴다. blockers 목록은 한 번 복사한다. 던지는
blocker는 page controller가 이미 막는 쪽으로 본다. page controller는
`observe`의 throw를 잡지 않으므로, 제품 sink가 던져도 worker 흐름이 바뀌지
않게 조립에서 감쌌다. 매뉴얼 03과 레시피 2·3을 새 자리로 고쳤다.
버린 대안:
- `product-composition.ts`에 새 export(`composeProductServiceWorker`)를 요구.
이미 그 파일을 가진 다운스트림이 동기화하면 import가 깨진다. 선택 칸은
기존 `composeProduct`를 그대로 둔다.
- `composeProduct`를 조립에서 한 번 더 부르기. capability와 credential이 두
벌 생긴다.
위험·한계: 일부만 닫는다. 남은 것:
- 활성화 화면(`onUpdateWaiting`·`requestActivation()`)과 reload 안내를 이을
제품 소유 자리가 없다(레시피 4·5, 0925/06-05).
- realtime·Web Worker·오프라인 명령은 여전히 조립이 거절한다
(`optional-runtime-host.ts`, 그 런타임이 템플릿에 없다).
`product-composition.ts`(제품 소유, 출하 상태 빈 값)는 고치지 않았다. 칸이
선택이라 기존 제품 파일과 1105/09-01의 타입 검사 탐침 내용이 그대로
통과한다.
검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/component/runtime-composition-service-worker-product-wiring.test.ts tests/component/runtime-composition-service-worker-telemetry.test.ts
- RED: "passes the product's blockers and observer to the page controller"가
옛 조립에서 observe 기록이 비어 실패한다.
- 함께: check:types, lint, check:architecture, verify:documentation
Refs: 1103/09-05
|
||
|
|
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
|
||
|
|
f738348d9d |
fix(bootstrap): 실패한 scope closer를 label과 함께 진단에 남긴다
문제: 1103/02-01이 제품 closer를 scope reset에 넣었다. template participant 하나가 제품 closer를 차례로 부르고, 하나라도 던지면 이유 없는 Error를 던진다. scope runtime은 그 실패를 `failed = true`로만 받아 scope를 `FAILED`에 둔다. 그동안 모든 서버 요청이 `SCOPE_FENCED`로 막히는데 진단 기록은 0건이다(리뷰 실험 E-3). 계약의 `ProductScopeParticipant.label`을 읽는 코드도 없다. 개발자는 "로그아웃 뒤 앱이 요청을 안 보낸다"만 보고 원인 closer를 찾으려면 closer를 하나씩 지워 봐야 한다. 고른 방법(리뷰 대안 (다)): - scope runtime이 reset의 실패 단계마다 `cache.operation.failed`를 하나 남긴다. `operation: "SCOPE_RESET"`, `reason`은 `PARTICIPANT_FAILED`· `CACHE_RESET_FAILED`·`GENERATION_ACTIVATION_FAILED`(+ 목록 함수가 던질 때 `PARTICIPANTS_UNREADABLE`), `error_kind`, participant 실패면 `scope_participant: <label>`. template participant 실패도 같은 길로 남는다. - 진단 계약에 `scope_participant` 키를 더한다(cardinality `topology`, 값 정책 `isScopeParticipantLabel` = 소문자 kebab-case 48자 이하). label은 제품 코드가 고른 문자열이라 projection이 받는 닫힌 토큰으로 제한했다. - 제품 closer를 wrapper 하나로 감싸지 않고 각자 order 10 participant로 넘긴다. 그래서 `participants`가 reset마다 읽는 함수도 받는다 (`ServerStateScopeDependencies`, 배열은 그대로 받는다). 순서와 "하나가 실패해도 나머지를 부른다"는 그대로다. - 조립은 형식에 맞지 않는 제품 label을 `TypeError`로 거절한다. 부팅에서 바로 드러나야 진단에서 label이 빠지는 일이 없다. 버린 대안: - (가) 문서에 "closer는 던지지 않게 쓴다"만 적기: 결함이 그대로다. - (나) wrapper만 제품 label을 기록: template participant 실패는 계속 조용하고, 한 실패가 wrapper와 runtime에서 두 번 기록된다. - label을 `operation`이나 `reason` 값에 섞기: 계약 변경은 없지만 그 키의 뜻이 흐려진다. 위험·한계: - 진단 계약(`src/contracts/diagnostics.ts`)에 키 하나, 함수 하나가 더해진다. 더하기만 해서 호환은 깨지지 않는다. CHANGELOG [계약] 행이 필요하다. - 제품 label 형식이 좁아졌다. `Browser Files` 같은 label을 쓰던 제품은 부팅에서 `TypeError`가 난다. 저장소 안의 label(`browser-files`, 테스트의 label)은 모두 맞는다. - 화면이 `FAILED`를 어떻게 보이는지는 바꾸지 않았다(영역 08·09). 검증: desktop batch에서 확인 - node scripts/run-vitest.ts run tests/unit/server-state-scope-runtime.test.ts tests/unit/runtime-adapters-product-scope-participants.test.ts tests/unit/observability-cardinality.test.ts tests/unit/diagnostics.test.ts - corepack pnpm check:diagnostics - node scripts/run-vitest.ts run tests/recipes/browser-file-session-capability.test.ts Refs: 1105/02-01 |
||
|
|
629c713ce4 |
fix(ci): immutable_build가 gate 로그와 advisory 기록을 항상 올린다
문제: ci:gate는 명령 출력을 artifacts/quality/gates/FE-GATE-<NNN>.txt에만 쓰고 콘솔에는 PASS/FAIL 한 줄만 남긴다(scripts/run-ci-gate.ts). release 단계 job immutable_build는 후보 tar만, 그것도 성공했을 때만 올린다. 그래서 실제 run에서 FE-GATE-015·027이 왜 실패했는지와 FE-GATE-027이 쓰는 artifacts/security/dependency-advisories.json(1103/13-03의 신호)이 runner 작업 디렉터리와 함께 사라진다. 다른 gate job은 artifacts/를 if: always()로 올린다. 고른 방법: - config/ci/gates.json의 immutable_build 마지막에 upload 단계를 더한다. transfer ID는 immutable-gate-evidence, 이름은 immutable-gate-evidence-<run>-<attempt>, always: true. 대상은 FE-GATE-015·027의 log와 evidence 산출물(gate 순서)과 advisory 기록 7개다. FE-GATE-015의 verification.json 등은 후보가 만들어지지 않으면 후보 안에도 없으므로 같이 올린다. - 계약(scripts/contracts/ci-gates.ts)이 이 단계를 고정한다. immutable_build의 단계 목록에 upload 하나가 늘고, 이 upload가 always이고 마지막 단계이며 경로가 "job이 도는 gate의 log·evidence 경로 + advisory 기록"과 같아야 한다. 경로는 계약의 artifact 등록에서 계산하므로 log 경로가 바뀌면 함께 따라온다. advisory 기록은 gate evidence가 아니라(막지 않는 신호) 경로를 scripts/lib/dependency-advisories.ts의 상수로 옮기고 scan 스크립트도 그 상수를 쓴다. - 후보 archive의 member set, 후보 upload(always 없음), 하위 job의 download는 그대로다. 생성 workflow를 generator 출력과 같게 손으로 고쳤다. 버린 대안: - immutable_build도 artifacts/ 전체를 올림: 다른 job과 같지만 후보 증거가 두 이름으로 나가 어느 것이 승격 대상인지 흐려진다. 필요한 파일만 고정했다. - ci:gate가 실패한 명령의 마지막 N줄을 콘솔에 씀(리뷰 대안 c, d의 콘솔 한 줄 포함): 모든 job에 걸리고 provider 출력의 비밀 노출과 로그 상한을 다시 따져야 한다. 담당 지시 범위(업로드) 밖이라 이번에 하지 않았다. 위험·한계: - checkout·install 단계에서 실패하면 올릴 파일이 없어 이 단계도 if-no-files-found: error로 실패한다. job은 이미 실패한 뒤라 결과는 같다. merge·release job의 upload도 같은 동작이다. - 실제 Gitea runner에서 stage=release를 돌려 산출물이 남는지는 확인하지 못했다(runner 없음). 확인한 것은 계약·생성 workflow까지다. - 콘솔에는 여전히 한 줄만 나온다. 사람이 산출물을 열어야 이유를 본다. 검증: desktop batch에서 확인 - node scripts/run-vitest.ts run tests/unit/ci-workflow-generation.test.ts - corepack pnpm check:ci, check:types, lint, verify:documentation Refs: 1105/13-01, 1103/13-03 |
||
|
|
8b92f45f5e |
fix(http): Fileserver 업로드 실패에 Envelope의 traceId를 싣는다
문제: readFailureEnvelope는 실패 Envelope의 meta.traceId를 함께 돌려주고, V3 실행기는 그 값을 AppFailure.traceId로 싣는다(1103/03-06). Fileserver client는 envelope.value만 넘겨 traceId를 버린다. 지원 담당이 업로드 실패를 서버 로그의 요청과 잇지 못한다. 같은 백엔드의 다른 쓰기 실패는 이을 수 있다. 고른 방법: envelopeFailure가 읽은 Envelope 전체를 받아 traceId가 있으면 createFailure의 traceId로 싣는다. V3와 같은 규칙이다. 없으면 키를 두지 않는다. 매뉴얼 7절 결과 읽기에 한 줄 적었다. 위험·한계: Envelope 실패에만 싣는다. 성공 Envelope을 읽지 못한 실패 (SCHEMA_MISMATCH 등, 202 REJECTED 포함)는 readSuccessEnvelope가 meta를 돌려주지 않아 traceId가 없다. V3도 같다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts RED(이 커밋의 테스트 + 부모 src): Envelope failures 표 17행이 traceId "trace-1"이 없어 모두 실패한다. Refs: 1105/01-03 |
||
|
|
4d6f254438 |
fix(hosting): 자산 MIME probe가 redirect를 거절하고 live 분기를 테스트한다
문제: 확장자별 MIME probe(1103/06-03)는 install 조건 일부만 옮겼다. 1. install fetch는 `redirect: "error"`라 redirect가 하나라도 있으면 실패한다. probe는 `redirect: "follow"`로 받고 최종 status와 MIME만 본다. 같은 origin 안 redirect 뒤 200을 주는 호스트가 PASS다(리뷰 06-R1). FE-GATE-019가 PASS인데 워커 install은 매번 실패한다. 2. 워커 없는 빌드에서도 돈다. 주석과 문서는 이유를 워커로만 적는다. 3. live 분기의 호출 줄(`verify-hosting-headers.ts`)을 지키는 테스트가 없다. live 모드는 루프백·http를 거절해 저장소 테스트가 들어갈 수 없다. 호출을 지우는 변이가 44건 통과로 살아남았다(06-R2). 고른 방법: 1. 자산 probe 기본 fetcher를 `redirect: "manual"`로 바꾸고, `response.redirected`이거나 `opaqueredirect`이면 관측 "redirected", 이유 "install fetch가 redirect를 거절"로 FAIL이다. 3xx는 지금처럼 `HTTP 3xx`로 FAIL이다. fetcher가 redirect를 따라가도 `redirected`로 잡으므로 fetcher 방식과 무관하다. 2. 동작은 그대로 두고 의도를 주석과 운영 문서에 적었다. 워커가 없어도 `nosniff` 아래 script·style은 MIME이 틀리면 페이지가 깨지고, 나중에 워커를 켜는 릴리스가 호스팅을 다시 확인하지 않아도 된다. 글꼴·이미지는 페이지에 피해가 없는데 FAIL한다는 것도 적었다. 워커 없는 빌드에서 script·style만 보도록 좁히는 것은 검사를 약하게 하는 정책 결정이라 하지 않았다(결정 대기, 템플릿 소유자). 3. live 분기 전체를 `probeLiveHosting`(release surface + 자산 MIME)으로 빼고 스크립트는 그것만 부른다. 테스트가 fetcher 대역으로 이 함수를 돌려 CSS `text/plain`이 FAIL인지 본다. 자산 probe 호출을 빼면 이 테스트가 실패한다. 스크립트에서 `probeLiveHosting` 호출을 빼면 live 결과가 비어 cache-control 행이 모두 FAIL이라 스스로 드러난다. 버린 대안: 문서에 한계만 적기(리뷰 (b)). 1·3이 그대로다. 위험·한계: 정규 경로 규칙으로 자산을 redirect하는 호스트는 이제 FE-GATE-019에서 FAIL이다. 워커가 없는 제품도 마찬가지다(2의 판단). 실제 호스트로 live 모드를 돌리지는 않았다. 검증: desktop batch에서 확인. - node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts - RED: "fails an asset the host answers only after a redirect"(옛 probe는 redirect 뒤 200을 PASS), "checks every built asset type besides the release surfaces"(옛 코드에 `probeLiveHosting`이 없음)가 실패한다. - 변이(06-R2 대응): `probeLiveHosting`에서 `probeAssetContentTypes` 결과를 빼면 "checks every built asset type ..."가 실패해야 한다. Refs: 1105/06-02 |
||
|
|
471b001c40 |
fix(http): Fileserver 504 TRANSFER_TIMEOUT를 결과 불명으로 읽고 멱등 응답은 V3 표를 쓴다
문제: client는 504 TRANSFER_TIMEOUT을 NOT_APPLIED, retryable:true, retryAfterMs 5000으로 준다. 매뉴얼대로면 기능이 5초 뒤 자동으로 다시 올린다. 근거로 든 "백엔드가 게시 전에 낸다"는 이 code에 맞지 않는다. 백엔드(45d2a478)는 업로드 작업을 전송 풀에 넘기고, 대기 스레드가 await-seconds가 지나면 작업 단계와 상관없이 future.cancel(true) 뒤 TRANSFER_TIMEOUT을 던진다(BlockingTransferExecutor). interrupt는 파일 복사는 멈추지만 게시 rename과 READY 커밋은 멈추지 않는다. 그래서 504 뒤에 파일이 READY가 될 수 있고, 백엔드가 멱등 키를 읽지 않으므로 다시 보내면 같은 파일이 둘 생긴다. 같은 client의 효과 표는 V3 표와도 갈라졌다. 503 IDEMPOTENCY_UNAVAILABLE을 client는 NOT_APPLIED, V3 표(backend-envelope.ts)와 매뉴얼 4절은 MAYBE_APPLIED로 본다. 계약 문서 6.1의 fileserver 행은 4xx를 MAYBE_APPLIED로 적는데 client는 NOT_APPLIED로 보고, 어느 쪽도 다른 쪽을 말하지 않는다. pin 대조도 이 표를 보지 않는다. 고른 방법: - TRANSFER_TIMEOUT을 NOT_APPLIED_5XX_CODES에서 뺀다. 5xx 기본값대로 MAYBE_APPLIED이고, createFailure가 retryable:false, action contact-support로 만든다. 자동 재전송은 없다. 남은 NOT_APPLIED 5xx는 작업 스레드가 게시 전에 내는 넷(PARTIAL_WRITE, ATOMIC_PUBLISH_UNSUPPORTED, STORAGE_UNAVAILABLE, STORAGE_FULL)이다. - 멱등성 code(IDEMPOTENT_*, IDEMPOTENCY_* 접두)와 V3 표의 행(REFUSED_BEFORE_WRITE, MAYBE_APPLIED_ANSWERS의 status+code)은 client도 envelopeFailureEffect로 판정한다(sharedAnswerEffect). 같은 백엔드 code의 판정이 이 repo에 하나다. 503 IDEMPOTENCY_UNAVAILABLE은 MAYBE_APPLIED가 되고, 400 IDEMPOTENCY_KEY_INVALID·422 IDEMPOTENT_REQUEST_MISMATCH는 그대로 NOT_APPLIED, 409 IDEMPOTENT_IN_FLIGHT 등은 그대로 MAYBE_APPLIED다. 손으로 둔 MAYBE_APPLIED_CODES 목록은 AMBIGUOUS_COMPLETION 비교 하나로 줄었다. - pin 옆에 복사한 백엔드 답 표(config/contracts/backend-idempotency-answers.json)의 행마다 client 결과의 effect가 V3 표와 같은지 통합 테스트가 본다. 그 표는 tests/unit/backend-contract-pin.test.ts가 V3 표를 묶는 표와 같다. pin을 옮기면 두 reader가 함께 다시 대조된다. - Fileserver 4xx를 NOT_APPLIED로 보는 이유(업로드 use case가 취소)를 계약 문서 6.1에 한 곳으로 적고, client 주석과 매뉴얼은 그곳을 가리킨다. - client 주석·매뉴얼의 백엔드 SHA 표기를 bbe944bd에서 pin(45d2a478)으로 맞췄다. 두 SHA 사이 Fileserver main 코드는 바뀌지 않았다(리뷰 2.1절). 버린 대안: - client 효과 판정을 V3 표로 통째로 바꾼다: Fileserver 4xx가 모두 결과 불명이 되어 413·415·422 파일 거절과 202 REJECTED 화면이 나빠진다. 단일 업로드에서는 use case가 취소하므로 근거도 없다. - TRANSFER_TIMEOUT 한 줄만 고친다: 위험한 줄은 없어지지만 세 표의 갈라짐과 pin 밖 상태가 남는다. 위험·한계: - 504 TRANSFER_TIMEOUT 뒤 화면이 "재시도"에서 "결과 불명"으로 바뀐다. 503 IDEMPOTENCY_UNAVAILABLE도 같다. CHANGELOG [계약] 한 줄이 필요하다. - 백엔드로 넘김: 백엔드는 TRANSFER_TIMEOUT을 retryable=true, ambiguous 없이 보낸다(FileserverErrorCode, BlockingTransferExecutor). 요청 — (a) 작업이 시작된 뒤의 대기 초과는 details.ambiguous=true, reconciliationRequired=true, retryable=false로 보내거나, (b) 작업 스레드가 게시 rename과 READY 커밋 전에 interrupt를 확인해 504가 "READY 없음"을 보장하게 하고, 어느 쪽인지 docs/fileserver/http-contract.md에 적는다. 백엔드가 (b)를 고르면 이 줄을 되돌린다(재검토 조건). - 백엔드로 넘김: POST /v1/files가 Idempotency-Key를 읽지 않는다 (UploadFileApplicationUseCase NOT_IDEMPOTENT). 요청 — 업로드를 멱등성 executor 뒤에 두거나, 키를 무시한다고 Fileserver 계약 문서에 적는다. - 리뷰 최소 개선 방향 ④의 "drift 검사 대상에 docs/fileserver/http-contract.md 추가"는 하지 않았다. scripts/check-backend-contract-drift.ts와 pin 모양은 같은 라운드의 1105/07-01 수정이 다시 짠다. 같은 파일을 두 브랜치가 고치면 충돌한다. 07-01과 함께 넣는 편이 낫다. - Fileserver 자신의 code 표(NOT_APPLIED_5XX_CODES)는 여전히 손으로 읽은 것이고 pin 대조 밖이다. 늦게 READY가 되는 경쟁은 재현하지 않았다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts RED(이 커밋의 테스트 + 부모 src): Envelope failures 표의 "503 IDEMPOTENCY_UNAVAILABLE → SERVER_FAILURE, MAYBE_APPLIED, retryable false", "504 TRANSFER_TIMEOUT → SERVER_FAILURE, MAYBE_APPLIED, retryable false", "504 TRANSFER_TIMEOUT is an unknown result the client does not offer to retry", pinned backend answer table의 "reads 503 IDEMPOTENCY_UNAVAILABLE as the V3 Envelope table does"가 실패한다. Refs: 1105/01-02 |
||
|
|
3b62ccd5db |
fix(registry): 응답 스키마 행을 REJECT_UNKNOWN으로 좁히면 breaking으로 본다
문제: 응답 DTO를 `.strict()`로 바꾸고 FE-REG-SCHEMA 행의 `unknownFieldPolicy`를 STRIP_UNKNOWN에서 REJECT_UNKNOWN으로 같이 고치면 check:registries가 behavior-change로 통과한다(리뷰 배치 07-R1). 1103/07-03 수정은 행과 검증기를 묶었지만 등급은 그대로였다. 그 뒤 백엔드가 응답에 필드 하나를 더하면 그 API는 SCHEMA_MISMATCH로 실패한다. 같은 경계에서 FE-REG-API는 acceptedStatuses 축소를 breaking으로 본다. 고른 방법: 분류기에 규칙 하나를 더한다. `direction: "RESPONSE"` 행의 `unknownFieldPolicy`가 REJECT_UNKNOWN이 아니던 값에서 REJECT_UNKNOWN으로 바뀌면 kind `response-reader-narrowed`, breaking이다. 반대 방향 (REJECT→STRIP, 읽는 쪽을 넓힘)과 REQUEST 행(프론트가 스스로 채우는 값)은 그대로 behavior-change다. 버린 대안: governance의 FE-REG-SCHEMA breakingFields에 `unknownFieldPolicy`를 넣는 것(리뷰 안 B). 넓히는 변경까지 증거를 요구하게 되고, governance 계약이 바뀌어 템플릿과 다운스트림 모두 기준선을 다시 승인해야 한다. 이 규칙은 기준선과 governance를 바꾸지 않는다. 리뷰 안 (1)의 fieldTypes 선언도 같은 이유로 하지 않았다. 위험·한계: 규칙은 칸 이름(`unknownFieldPolicy`)과 값 어휘 (src/contracts/schema-registry.ts)에 묶여 있다. 어휘를 바꾸면 이 함수도 고친다. route-params·route-search(REQUEST 방향, URL을 읽는 쪽)를 REJECT_UNKNOWN으로 좁히는 변경은 여전히 behavior-change다. 지금 템플릿 스냅샷은 기준선과 같아 결과는 none 그대로다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/unit/registry-compatibility.test.ts 리뷰 07-R1 패치(응답 DTO `.strict()` + 응답 행 두 개 REJECT_UNKNOWN)를 다시 적용하면 check:registries가 `breaking change missing evidence: FE-REG-SCHEMA:ReferenceResource(List)Payload:unknownFieldPolicy: response-reader-narrowed`로 실패해야 한다. Refs: 1105/07-02 |
||
|
|
1c7c614b47 |
fix(service-worker): 사전 캐시를 Vite assets 폴더의 해시 파일로 제한한다
문제: 사전 캐시 수집기(`collectStaticAssets`)는 dist 전체를 돌고 파일 이름만 해시 정규식으로 본다. `public/` 파일은 이름 그대로 dist 루트에 복사되는데, `apple-touch-icon.png`, `android-chrome-192x192.png`, `safari-pinned-tab.svg`는 정규식에 걸려 immutable 자산으로 들어간다(리뷰 06-R1). 제품이 같은 이름으로 아이콘을 바꾸고 CDN이 옛 바이트를 주면 새 릴리스 install이 INTEGRITY_MISMATCH로 통째로 거절된다. 이전 릴리스 fallback, 호스팅 정책 `/assets/*`, MIME probe, 레시피 문서는 모두 `assets/`만 가정한다. 고른 방법: 리뷰 06-01의 (a). 계약 모듈에 `BUILD_ASSET_DIRECTORY = "assets/"` 하나를 두고, 수집기는 그 아래 파일만 받는다. 워커 fallback (`service-worker-static-assets.ts`)과 probe(`hosting-probe.ts`)도 같은 상수를 읽는다. `build.assetsDir`를 바꿀 때(0925/06-08) 이 상수 한 곳만 고치면 된다. 수집기의 `.vite/` 제외는 새 조건이 덮으므로 지웠다. 레시피 문서에 루트 파일이 빠진다는 문장을 더했다. 버린 대안: - 정규식을 Vite 해시 형식(8자 고정)으로 좁히기. 우연히 맞는 이름이 남는다. - 문서만 고치기. 아이콘 문제가 그대로다. 위험·한계: 루트에 해시 이름 파일을 일부러 두는 제품은 그 파일이 사전 캐시에서 빠진다. Vite는 그런 파일을 만들지 않는다. 상수는 vite 설정에서 읽지 않는다. `build.assetsDir`를 바꾸는 제품은 상수도 같이 바꿔야 한다 (0925/06-08은 그대로 남는다). 검증: desktop batch에서 확인. - node scripts/run-vitest.ts run tests/unit/service-worker-web-push-remediation.test.ts tests/unit/service-worker-runtime.test.ts tests/unit/hosting-probe.test.ts tests/unit/service-worker-build-output.test.ts - RED: "precaches only the assets directory, not public files at the dist root"가 옛 수집기에서 루트 아이콘 세 개를 받아 실패한다. Refs: 1105/06-01 |
||
|
|
2e1acb1f21 |
fix(bootstrap): 금지된 설정 키로 멈춘 부팅 오류에 그 키 이름을 싣는다
문제: 런타임 설정에 비밀처럼 보이는 키(`CLIENT_SECRET` 등)가 있으면 부팅이 CONFIG_SECRET_NAME_REJECTED로 멈추지만, 안전한 부팅 오류에는 buildId만 있고 어느 키인지가 없다. assertSafeConfigNames가 던진 오류의 message에는 키 이름이 있었지만 loadRuntimeConfig가 그 오류를 버렸다. 같은 파일의 스키마 실패는 키 이름을 invalidKeys로 싣는다. 고른 방법: assertSafeConfigNames가 UnsafeConfigNameError를 던지고 그 `key`에 거절한 키의 점 경로(`CAPABILITY_OVERRIDES.AUTH_TOKEN`, `FEATURE_OVERRIDES.<id>.CLIENT_SECRET`)를 싣는다. 로더는 그 경로를 스키마 실패와 같은 SAFE_KEY_PATTERN으로 거른 뒤 invalidKeys에 넣는다. 오류 화면은 이미 invalidKeys를 "잘못된 설정 키"로 보인다. 값은 어디에도 싣지 않는다. 버린 대안: message에서 키를 정규식으로 다시 읽는 것. message 문구가 바뀌면 조용히 빠진다. 위험·한계: 키 이름은 거절된 문서에서 온다. 그래서 길이·문자를 제한하고, 그 밖의 이름은 빼고 코드만 남긴다. 첫 번째로 걸린 키 하나만 싣는다 (검사가 첫 키에서 멈추는 동작은 그대로). assertSafeConfigNames의 시그니처와 message는 바꾸지 않았다. UnsafeConfigNameError는 src/contracts/env.ts에 새로 더한 export다(추가만). 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/runtime-schema/runtime-config.test.ts Refs: 1103/07-04 |
||
|
|
23662fb23a |
fix(storage): 객체를 끝까지 돈 계정 삭제 purge는 늘 partition을 지운다
문제: 승인된 LOGOUT·ACCOUNT_DELETION purge는 객체 목록을 읽고, 하나씩 지우고, 마지막에 journal 행을 한 번 센 뒤 0이면 chunk sweep으로 끝나 `chunkSweep: "COMPLETED"`를 돌려준다. 목록과 세기는 각각 한 순간만 본다. - 다른 탭이 새 객체를 put하는 중이면 purge의 remove가 그 put이 쥔 origin lease를 기다린다. partition에 객체가 3개 이상이면 그 put은 목록 뒤에 commit하고 세기 전에 complete까지 끝난다. 목록에도 행 수에도 없어 sweep이 그 chunk를 건너뛰고, 계정 삭제 뒤에도 파일이 읽힌다 (리뷰 실험 Y1b 메모리 20/20, Chromium 6/6). 저장소 테스트는 객체 0~1개로만 돌아서 이 틈을 놓쳤다. - FILES_READY에서 멈춘 put의 행이 `logicalKey`를 잃으면 세지 못한다. staging receipt가 chunk를 sweep에서 지켜 purge마다 COMPLETED인데 receipt·chunk·manifest가 남는다(Y2). 고른 방법: 마지막 객체까지 돈 purge는 sweep 대신 늘 partition 삭제로 끝낸다(리뷰 2.1절 (d')). exclusive partition lock이 그때 진행 중인 put·delete를 모두 기다린 뒤 디렉터리 전체(staging 포함)와 그 partition 행을 지우므로 두 경우를 함께 막는다. 객체 순회는 `removedObjects`· `releasedBytes` 보고와 예산 단위 진행을 위해 남긴다. 예산이나 다른 탭의 변경(CONFLICT) 때문에 끝까지 돌지 못한 호출은 지금처럼 `moreObjectsAvailable: true`를 돌려주고, 그때만 journal 행을 세서 끝나지 않은 행이 있으면 바로 partition을 지운다(2026-11-03 05-01 그대로). purge 성공 report는 이제 `partitionDeleted`와 `moreObjectsAvailable` 중 정확히 하나를 가진다(walk 뒤 abort도 more로 보고). 버린 대안: - (a) sweep 뒤에 다시 세고 committed 객체를 한 번 더 본다: ①만 막고 ②가 남는다. 다시 볼 때 정책상 남겨야 할 객체를 가려내려면 목록을 끝까지 다시 읽어야 한다. - (b)+(a): 둘 다 막지만 판단 조건이 일곱 개가 된다. - 세기를 아예 없애기: 예산에 걸린 호출의 crash 행 처리가 다음 호출로 밀린다. 지금 동작을 바꿀 이유가 없어 남겼다. 위험·한계: - 모든 승인 purge가 다른 탭의 진행 중 put을 기다린다(지금까지는 끝나지 않은 행이 있을 때만). 기다림 상한은 `mutationLockWaitTimeoutMs` (1103/05-02)이고 abort로 멈출 수 있다. - 같은 partition에 LOGOUT 때 남겨야 하는 객체가 섞이면 이 방법은 맞지 않는다. 지금 정책 검사는 OPAQUE_PARTITION이면 LOGOUT·ACCOUNT_DELETION 모두 purge만 허용해 그런 객체가 생기지 않는다. - port의 `chunkSweep`은 아무도 채우지 않는다. 읽는 코드가 깨지지 않게 타입은 남기고 `@deprecated`로 적었다. - recipe fake의 purge도 늘 `partitionDeleted`다. - `logicalKey`를 잃은 행 자체는 여전히 남는다(05-03 설계). 그 bytes는 이제 남지 않는다. - Firefox·WebKit에서 Y1은 돌리지 않았다. browser spec은 객체 0·3개 두 경우로 늘렸다. 검증: desktop batch에서 확인 - node scripts/run-vitest.ts run tests/unit/opfs-worker-runtime.test.ts tests/unit/opfs-byte-store.test.ts tests/unit/indexeddb-opfs-journal.test.ts - node scripts/run-vitest.ts run tests/recipes/browser-file-storage-contracts.test.ts - corepack pnpm test:browser-capabilities tests/browser-capabilities/opfs-runtime.spec.ts --project=chromium Refs: 1103/05-01 |
||
|
|
6608fef4ba |
fix(http): Fileserver 202 REJECTED를 파일 거절로 읽고 빈 파일은 보내지 않는다
문제: 짝 백엔드(45d2a478)는 POST /v1/files를 요청 안에서 동기로 검증하고 READY가 아닌 state를 모두 202로 답한다(FileUploadController#created). 악성 코드가 아닌 이유로 검증기가 거절하면 예외 없이 202 REJECTED다 (FinalizeUploadApplicationUseCase#applyNonAcceptVerdict). 기본 검증기 사슬의 첫 검증기(LengthVerifier)가 빈 파일을 그렇게 거절하므로, 0바이트 파일 하나로 닿는다. client schema에는 REJECTED가 없어 이 답이 SCHEMA_MISMATCH, APPLIED_CONFIRMED, "응답 형식 오류" 문구로 끝난다. 사용자는 파일을 바꾸라는 안내 대신 지원 문의를 보게 된다. 테스트의 MSW는 202 VERIFYING만 적은 백엔드 문서에서 왔고, 매뉴얼도 202를 "아직 검사 중"으로 적어 QUARANTINED(동기 검증 202의 대부분)를 끝나지 않는 대기로 보이게 한다. 고른 방법(리뷰 01-01 최소 개선 방향 (가)): - schema가 REJECTED를 받는다. 202 REJECTED는 성공이 아니라 실패 VALIDATION_REJECTED, code FILE_REJECTED, NOT_APPLIED, httpStatus 202다. 413·415·422 파일 거절과 같은 규칙이다. 백엔드는 그 레코드를 공개하지 않고 바이트 정리를 예약하므로 쓸 수 있는 파일이 남지 않는다. 공개 타입 FileserverFileState와 FileserverUploadedFile은 바꾸지 않았다(REJECTED는 성공 값으로 나오지 않는다). - 빈 파일은 읽기 전(선언 크기 0) 또는 읽은 뒤(선언 없음, 0바이트) 보내지 않고 FILE_EMPTY, NOT_STARTED로 끝낸다. 서버의 202 REJECTED에는 이유가 없어 기능이 "빈 파일"이라고 말할 수 없기 때문이다. - 201⇔READY 검사, size 일치 검사, 모르는 필드 무시는 그대로다. 201 REJECTED는 여전히 SCHEMA_MISMATCH다. - MSW 설명을 백엔드 코드(45d2a478) 기준으로 고치고 202 QUARANTINED· REJECTED 행을 더했다(1103/01-01의 "MSW가 문서에서 왔다" 부분). - 매뉴얼 7절이 202 state 셋의 뜻(VERIFYING 재검사 대기, QUARANTINED 관리자 결정 전 내려받기 불가, REJECTED는 실패)과 FILE_EMPTY를 적는다. 버린 대안: - REJECTED를 성공 state로 넘긴다: 타입 변경은 작지만 기능마다 성공 값에서 거절을 다시 찾아야 하고, 공개 타입 FileserverFileState가 넓어진다. - 빈 파일 거절만 한다: 기본 사슬은 막지만 제품이 더한 검증기의 REJECT는 그대로 SCHEMA_MISMATCH다. 위험·한계: - upload() 결과가 바뀐다. 202 REJECTED가 SCHEMA_MISMATCH에서 VALIDATION_REJECTED/FILE_REJECTED로, 빈 파일이 서버 요청에서 FILE_EMPTY로 바뀐다. CHANGELOG [계약] 한 줄이 필요하다. - 빈 파일 거절은 짝 백엔드 기본 검증기 사슬을 가정한다. 제품이 사슬에서 LengthVerifier를 빼 빈 파일을 받게 하면 client 규칙도 바꿔야 한다. - 실제 짝 백엔드를 띄워 빈 파일을 올려 보지 않았다(미검증). 응답 모양은 백엔드 코드(UploadedFileResponse, FileRecord#toDescriptor)를 읽은 것이다. - 1103/01-01의 남은 부분은 이 커밋 밖이다: 백엔드 매뉴얼의 짝 경로 안내와 docs/fileserver/http-contract.md의 202 state 목록(백엔드로 넘김), 실제 업로드 검증(미검증). 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts RED(이 커밋의 테스트 + 부모 src): "reads 202 REJECTED as a refused file, not as a broken answer"(SCHEMA_MISMATCH로 끝남), "an empty file", "an undeclared size that turns out empty"(fetch를 부름)가 실패한다. Refs: 1105/01-01, 1103/01-01 |
||
|
|
9655958bda |
fix(ci): test:system 사전 점검이 bwrap namespace를 실제로 만들어 본다
문제: FE-GATE-013의 provider sandbox는 bwrap을 --unshare-pid --unshare-ipc --unshare-uts --unshare-net으로 띄운다. bwrap이 setuid가 아니므로 비특권 user namespace가 있어야 한다. 사전 점검 (scripts/check-system-test-prerequisites.ts)은 실행 파일·cgroup·systemd bus만 보고 bwrap을 한 번도 실행하지 않는다. 그래서 이 제한이 있는 호스트 (Ubuntu 24.04, kernel.apparmor_restrict_unprivileged_userns=1)에서 PASS를 낸 뒤 provider 테스트 114건 중 18건이 "bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted" 또는 그 provider를 기다린 시간 초과로 실패한다. 이 조건은 runner 요구 목록, gate 정의, workflow 어디에도 없고 운영 원장의 일회성 메모에만 있다. 고른 방법: - 사전 점검이 provider와 같은 namespace 옵션으로 bwrap에서 /bin/true를 한 번 띄운다. 실패하면 "this host does not allow unprivileged user and network namespaces", bwrap stderr(최대 4줄), user namespace sysctl 값, 고치는 방법 셋(AppArmor profile, sysctl, 다른 runner)을 적고 exit 1. 기존 검사(실행 파일 3개, cgroup v2, systemd bus)는 그대로 둔다. - 옵션 목록을 scripts/lib/provider-sandbox-namespaces.ts로 옮기고 run-and-validate-provider.ts와 사전 점검이 같은 상수를 쓴다. 둘이 갈라지면 점검이 다른 것을 시험하게 된다. - 점검을 findSystemTestPrerequisiteFailures(host)로 내보내고 access· readFile·spawn을 주입받는다. CLI 동작(출력·exit 코드)은 같다. - config/ci/gates.json의 FE-GATE-013에 hostRequirements 두 줄을 둔다. gate schema에 선택 필드를 더하고, generator가 그 gate를 도는 job의 runs-on 바로 위에 "# FE-GATE-013 runner requirement: ..." 주석으로 그린다. runner를 고르는 사람이 보는 자리다. 줄바꿈은 기존 nonEmpty 규칙이 막으므로 주석 밖으로 나갈 수 없다. 이 필드는 gate의 명령·증거가 아니라 runner 설명이라 기준선 gate shape 해시에는 넣지 않았다(기준선 재기록 불필요). - 요구 목록 세 곳(docs/operations/ci-quality-gates.md, docs/security/supply-chain.md, docs/testing/taxonomy.md)과 README merge 게이트 절에 조건을 적었다. ci-quality-gates.md에 AppArmor profile 예시를 두었다. 버린 대안: - namespace가 없으면 provider 테스트를 skip: 거짓 초록이다. - FE-GATE-013을 release 단계로 옮김: PR마다 sandbox 검사를 잃는다. - probe를 systemd-run --user --scope 안에서 돌림: 리뷰 11-R10에서 scope 안과 밖의 결과가 같았다. 직접 실행이 더 단순하다. - workflow에 요구 사항을 runs-on label로 표현: runner label 체계가 아직 없다. 주석이 지금 가능한 가장 작은 표시다. 위험·한계: - probe는 bwrap에 --ro-bind / /만 준다. --size 같은 provider의 다른 옵션 지원은 여기서 보지 않는다(기존과 같다). probe가 다른 이유로 실패해도 namespace 문구가 나오지만 bwrap stderr를 같이 적는다. - 호스트를 고칠지는 호스트 소유자가 정한다. 이 커밋은 조건을 적고 알리기만 한다. 이 desktop에서 FE-GATE-013은 여전히 실패하고, 이제 첫 단계에서 이유와 함께 실패한다. - gate schema에 선택 필드 hostRequirements가 생겼다. 기존 gates.json과 제품 overlay는 그대로 통과한다. 검증: desktop batch에서 확인 - node scripts/run-vitest.ts run tests/unit/system-test-prerequisites.test.ts tests/unit/ci-workflow-generation.test.ts - corepack pnpm check:ci, check:types, lint, verify:documentation - desktop에서 node scripts/check-system-test-prerequisites.ts가 exit 1과 namespace 문구를 내는지, FE-GATE-013이 그 단계에서 멈추는지 Refs: 1105/12-01, 1105/11-02 |
||
|
|
05880d12fa |
docs(realtime): VD-28과 설계 3절의 poll 규칙을 V3 descriptor로 고친다
문제: VD-28은 poll 규칙을 지운 V2 실행 예산으로 적는다. "operation은 registered terminal·replay-safe REST `QUERY`", "Poll-bound VD-23 budget은 `maxAttempts=1`, `authRecoveryCount=0`, `maxCumulativeSleepMs=0`"이다. 설계 3절도 "REST `QUERY` operation"과 "REST operation registry"라고 적는다. V2 실행 경로는 2026-11-03에 지웠고(VD-23 상태 줄), 지금 규칙은 V3 descriptor의 `frontend.retryBudget: 0`이다(설계 9.2, 1103/04-01). a65df74가 9.2만 고쳤다. 고른 방법: VD-28 1절 끝 문장과 11절 목록, 설계 3절 두 항목을 지금 규칙으로 바꾼다. GET·HEAD, SAFE·IDEMPOTENT인 V3 descriptor, `retryBudget` 0이 아니면 생성 때 거절, 실행기가 그 칸에서 재시도 상한을 읽어 한 attempt가 요청 하나라는 것이다. 상세는 9.2를 가리킨다. 설계 3절의 "REST operation registry의 credential, conditional request, ... 재사용"은 주어를 V3 실행기로 바꾸면서 conditional request를 뺐다. V3 실행기에는 ETag 처리가 없고(`http-execution-v3.ts`에 If-None-Match 없음), VD-23 상태 줄이 conditional execution을 `DESIGNED_NOT_IMPLEMENTED`로 적는다. 위험·한계: 문서만 바꿨다. VD-28 11절의 "ETag/`If-None-Match` 또는 server cursor 사용" 목표 줄은 결정 내용이라 그대로 두었다. 검증: 문서 전용이라 RED 없음. desktop batch에서 확인. - pnpm verify:documentation - `git grep -n "authRecoveryCount\|maxCumulativeSleepMs" -- docs/architecture/decisions/VD-28*` 0건(로컬 확인) Refs: 1105/04-03 |
||
|
|
bfd9d50d2b |
fix(registries): 계약 조립 실패의 원인을 check:registries에 한 번만 찍는다
문제: 계약 조립이 실패하면 check:registries 출력에 같은 원인이 두 번 나온다. 1103/09-07 수정이 ContractContributionError의 message 끝에 reason을 붙였고, 1103/14-06 수정이 loadErrorText에서 message 뒤에 "(reason: ...)"를 또 붙였다. 두 수정이 다른 브랜치에서 들어왔다. 기존 테스트는 reason이 message에 없는 가짜 오류로만 시험해 중복을 보지 못했다. 고른 방법: loadErrorText가 message에 reason이 이미 들어 있으면 붙이지 않는다. reason을 message에 싣지 않는 오류(기존 테스트의 가짜 오류)는 지금처럼 "(reason: ...)"가 붙는다. 버린 대안: ContractContributionError message에서 reason을 다시 빼는 것. message만 찍는 다른 출구(부팅 오류, 테스트 출력)가 원인을 잃는다(1103/09-07이 고친 문제). 위험·한계: message 첫 줄만 보므로 여러 줄 reason은 다시 붙는다. 지금 reason은 한 줄이다. docs/manual/reference/errors.md의 출력 형식 줄을 실제 출력에 맞췄다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/unit/registry-governance.test.ts 새 테스트는 실제 ContractContributionError를 던지는 source로 check:registries를 돌려 원인이 한 번만 나오는지 본다. Refs: 1105/09-03 |