From 2f0f2bba176891d8192b434973ef1967e450d153 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 6 Nov 2026 05:20:15 +0900 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20BREAKING=201~3=EB=8B=A8?= =?UTF-8?q?=EA=B3=84=EC=9D=98=20=EB=8C=80=EC=83=81=C2=B7=EB=B0=94=EB=80=8C?= =?UTF-8?q?=EB=8A=94=20=EA=B0=92=C2=B7=EC=A6=9D=EC=83=81=EC=9D=84=20?= =?UTF-8?q?=EC=BD=94=EB=93=9C=EC=97=90=20=EB=A7=9E=EC=B6=98=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 미출시 절 "먼저 할 일"의 세 설명이 코드와 다운스트림 모양과 다르다. (1단계) TechLog를 "감싸지 않는 백엔드"라 적는다. TechLog 백엔드는 Envelope로 감싸고 출력 검증기 `envelopeData`가 직접 벗긴다(tech-log `tech-log-studio-contract-contribution.ts`). 같은 CHANGELOG 아래 절은 "출력은 Envelope 뼈대만 검사"로 적어 두 절이 다르다. "Envelope면 `ENVELOPE_V1`"을 따르면 실행기가 벗긴 `data`를 검증기가 다시 벗기려다 모든 응답이 실패한다. 빠뜨리면 `satisfies`에서 실패한다는 문장도 두 제품처럼 `as`로 단언한 descriptor에는 맞지 않는다. (2단계) `commandMutationIdentity`가 `requiresIdempotencyKey`를 `retrySemantics === "KEYED"`로 다시 계산한다는 말이 없다 (`src/contracts/server-state.ts`). tech-log 관리 정책은 `true`를 적었고 descriptor는 `NEVER`라 값이 `false`로 바뀌고, 키를 요구하는 제품 가드가 저장마다 던진다. `check:types`는 통과한다. (3단계) "계약 조립이 거절해 부팅이 멈춘다"고 적는다. 부팅은 빈 기여 목록만 조립하고(`installed-contract-contributions.ts`), 기능의 계약 기여는 그 기능 실행부를 적재할 때 `install`이 조립한다. 앱은 뜨고 그 기능 라우트에 처음 들어갈 때 실패한다. 고른 방법: 세 단계의 문장을 코드에 맞춘다. 1단계는 TechLog가 왜 `NONE`인지와 `ENVELOPE_V1`로 바꿀 때의 결과를 적고, `as` 단언에서는 타입 검사가 잡지 않는다고 덧붙인다. 2단계는 다시 계산하는 규칙, tech-log 관리 쓰기 예, 바꾸기 전에 값을 맞춰 보라는 한 줄을 붙인다. 3단계는 실패 시점과 CI에서 먼저 잡는 검사 (`test:unit`, `check:registries`)를 적고, "옮긴 뒤 확인" 1의 3단계 검사도 같이 고친다. 아래 절의 TechLog 문장은 이미 맞아 그대로 둔다. 위험·한계: `as` 단언이 빠진 `responseEnvelope`를 잡지 않는다는 것과 tech-log 관리 쓰기가 지금 실행기에서 `UNEXPECTED_IDEMPOTENCY_KEY`로 거절된다는 것은 코드를 읽은 추론이고, 문서에도 그렇게 적었다. tech-log sync 브랜치에서 2단계 뒤 관리 저장을 해 보지 않았다. 검증: 문서만 바꿨다. CHANGELOG는 verify:documentation 밖이다. desktop batch에서 확인. node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts Refs: 1106/14-01 --- CHANGELOG.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index da8d37b2..35e8406a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,9 +21,9 @@ #### 옮기는 법 -1. **HTTP descriptor마다 `responseEnvelope`를 적는다.** `InstalledHttpContract`의 필수 칸이 됐다. 감싸지 않는 백엔드(memento-web, TechLog)는 `"NONE" as const`, 짝 백엔드 Envelope는 `"ENVELOPE_V1" as const`다. 빠뜨리면 그 descriptor의 `satisfies InstalledHttpContract<...>`에서 `check:types`가 실패한다. 런타임 동작은 같다 (1103/16-01) -2. **뮤테이션 정책의 operation ID를 손으로 적지 않는다.** `BoundMutation.operationId`는 brand 타입 `MutationOperationId`다. `operationId: ""`와 `requiresIdempotencyKey`를 `...commandMutationIdentity()`로 바꾼다. 문자열로 적으면 `check:types`가 실패한다. V3 descriptor가 없는 쓰기(Fileserver 업로드처럼 `execute`가 HTTP 실행기를 거치지 않는 것)는 descriptor 모양 객체를 넘긴다: `...commandMutationIdentity({ contract: { operationId: "", method: "POST", retrySemantics: "KEYED" } })`. 멱등 키가 필요 없으면 `"NEVER"`다. 대조할 descriptor가 없으니 이 ID의 오타는 어느 검사도 잡지 않는다. 테스트 fixture는 `tests/helpers/mutation-operation-id.ts`의 `testMutationOperationId("")`를 쓴다. 문자열 ID는 `check:types:test`에서 실패한다. 매뉴얼 01 7단계 (1103/16-05) -3. **`refusedBeforeWrite`에서 플랫폼 code를 뺀다.** 계약 문서 6.1절이 "쓰기 뒤 가능"으로 둔 code(`PLATFORM_CODES_POSSIBLY_AFTER_WRITE`: `BAD_PARAMETER`, `MAPPING_FAILED`, `DB_*` 8개, `LOCK_ACQUISITION_TIMEOUT`, Fileserver code)를 적으면 계약 조립이 거절해 부팅이 멈춘다. 그 code의 실패는 결과 불명으로 남는다 (1105/03-01) +1. **HTTP descriptor마다 `responseEnvelope`를 적는다.** `InstalledHttpContract`의 필수 칸이 됐다. 감싸지 않는 백엔드(memento-web)는 `"NONE" as const`, 짝 백엔드 Envelope는 `"ENVELOPE_V1" as const`다. TechLog 백엔드는 Envelope로 감싸지만 출력 검증기(`envelopeData`)가 Envelope를 직접 벗기므로 `"NONE"`이다. `"ENVELOPE_V1"`로 바꾸면 실행기가 한 번 벗긴 `data`를 검증기가 다시 벗기려다 모든 응답이 실패한다. 빠뜨리면 그 descriptor의 `satisfies InstalledHttpContract<...>`에서 `check:types`가 실패한다. 두 제품의 descriptor helper처럼 `as`로 단언한 descriptor는 빠뜨려도 `check:types`가 잡지 않는다(타입 규칙으로 읽은 추론, 돌려 보지 않았다). 그런 descriptor는 직접 찾아 적는다. 빠진 값은 조립이 `NONE`으로 읽어 런타임 동작은 같다 (1103/16-01) +2. **뮤테이션 정책의 operation ID를 손으로 적지 않는다.** `BoundMutation.operationId`는 brand 타입 `MutationOperationId`다. `operationId: ""`와 `requiresIdempotencyKey`를 `...commandMutationIdentity()`로 바꾼다. 문자열로 적으면 `check:types`가 실패한다. 이 함수는 `requiresIdempotencyKey`를 descriptor의 `retrySemantics`가 `KEYED`일 때만 `true`로 다시 계산한다. 손으로 적은 값이 descriptor와 다른 정책은 동작이 바뀌고, `check:types`는 이것을 잡지 않는다. 예: tech-log 관리 쓰기는 정책이 `true`, descriptor가 `NEVER`라 `false`가 되고, 키가 없으면 던지는 자기 가드 때문에 저장마다 `TypeError`다(지금도 실행기가 키를 실은 `NEVER` 요청을 `UNEXPECTED_IDEMPOTENCY_KEY`로 거절하는 모양이다. 코드로 읽은 추론이다). 바꾸기 전에 정책마다 손으로 적은 값과 descriptor의 `retrySemantics`를 맞춰 본다. V3 descriptor가 없는 쓰기(Fileserver 업로드처럼 `execute`가 HTTP 실행기를 거치지 않는 것)는 descriptor 모양 객체를 넘긴다: `...commandMutationIdentity({ contract: { operationId: "", method: "POST", retrySemantics: "KEYED" } })`. 멱등 키가 필요 없으면 `"NEVER"`다. 대조할 descriptor가 없으니 이 ID의 오타는 어느 검사도 잡지 않는다. 테스트 fixture는 `tests/helpers/mutation-operation-id.ts`의 `testMutationOperationId("")`를 쓴다. 문자열 ID는 `check:types:test`에서 실패한다. 매뉴얼 01 7단계 (1103/16-05) +3. **`refusedBeforeWrite`에서 플랫폼 code를 뺀다.** 계약 문서 6.1절이 "쓰기 뒤 가능"으로 둔 code(`PLATFORM_CODES_POSSIBLY_AFTER_WRITE`: `BAD_PARAMETER`, `MAPPING_FAILED`, `DB_*` 8개, `LOCK_ACQUISITION_TIMEOUT`, Fileserver code)를 적으면 그 기능 실행부를 적재할 때 계약 조립이 거절한다. 부팅은 기능의 계약 기여를 조립하지 않으므로 앱은 뜨고, 그 기능 라우트에 처음 들어갈 때와 플랫폼 구성 화면에서 실패한다. CI에서는 모든 기능 실행부를 조립하는 `test:unit`과 `check:registries`가 먼저 잡는다. 그 code의 실패는 결과 불명으로 남는다 (1105/03-01) 4. **bounded poll의 `execute`는 실패를 던지지 않고 결과로 돌려준다.** 던지면(lease 자신의 abort 제외) 재시도 없이 `PROTOCOL_MISMATCH`(retryable 아님)로 lease가 끝난다. 네트워크 실패를 throw로 내던 `execute`는 retryable `PROVIDER_UNAVAILABLE` 결과로 바꾼다. 실행기에는 클로저의 descriptor 대신 `input.operation`(생성 때 검사한 descriptor)을 넘긴다 (1105/04-02, 1103/04-01) 5. **`artifacts/tests/a11y.json`을 읽는 도구는 schemaVersion 2를 읽는다.** `scope`는 실패 화면으로만 본 라우트를 빼고, 그 라우트는 새 `notChecked` 배열에 `{ routeId, reason }`으로 들어간다. 설치된 라우트 전체는 둘을 합친 것이다 (1103/11-01) 6. **제품 scope participant의 `label`은 소문자 kebab-case 48자 이하로 쓴다.** 아니면 조립이 `TypeError`로 멈춘다 (1105/02-01) @@ -34,7 +34,7 @@ #### 옮긴 뒤 확인 -1. 로컬 merge 게이트 14개를 돈다. 이 절 때문에 먼저 볼 것: `check:types`(1·2단계), 앱을 조립하는 `test:unit`·`test:component`(3·6단계), `check:ci`(9단계), `check:architecture`(10단계), `check:registries`(응답 스키마 행을 `REJECT_UNKNOWN`으로 좁힌 변경은 이제 breaking). +1. 로컬 merge 게이트 14개를 돈다. 이 절 때문에 먼저 볼 것: `check:types`(1·2단계), 모든 기능 실행부를 조립하는 `test:unit`·`check:registries`(3단계), 앱을 조립하는 `test:unit`·`test:component`(6단계), `check:ci`(9단계), `check:architecture`(10단계), `check:registries`(응답 스키마 행을 `REJECT_UNKNOWN`으로 좁힌 변경은 이제 breaking). 2. 한 checkout에서 브라우저 테스트 실행 두 개를 함께 돌리려면 실행마다 `TEST_RUN_ID`를 다르게 준다. 게이트(`ci:gate`)와 증거 검사는 기본 경로만 읽으므로 한 checkout에서 하나씩 돈다. 3. 배포가 있는 제품: 자산을 redirect로 주는 호스트는 FE-GATE-019가 FAIL이다.