From 02a761f06406d543af47b802d0f16e51008ddad4 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 6 Nov 2026 05:17:33 +0900 Subject: [PATCH 1/6] =?UTF-8?q?docs(storage):=20=EC=A0=80=EC=9E=A5?= =?UTF-8?q?=EC=86=8C=20=EB=AC=B8=EC=84=9C=EA=B0=80=20registry=20=ED=82=A4?= =?UTF-8?q?=20=EB=AA=A9=EB=A1=9D=20=EB=8C=80=EC=8B=A0=20=EC=A0=95=EB=B3=B8?= =?UTF-8?q?=EC=9D=84=20=EA=B0=80=EB=A6=AC=ED=82=A4=EA=B2=8C=20=ED=95=9C?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 저장소 설계 문서와 VD-13이 Web Storage registry 행을 "현재" 목록으로 적는다. 설계 문서 50-52행은 8행 중 4행(`COLOR_SCHEME`, `CHUNK_RELOAD_GUARD`, `AUTH_TOKEN`, `QUERY_PERSISTENCE`)만, 0절 표와 16.2절 기본 조립 표와 VD-13 2.1절 표·7.1절 문단은 `COLOR_SCHEME`, `CHUNK_RELOAD_GUARD` 둘만("두 key") 적는다. registry에는 기본 조립이 쓰는 `LOCALE`·`RELEASE_MISMATCH_RECOVERY`와 외부 소유 행 `CACHE_INVALIDATION_PULSE`·`AUTH_REDIRECT_TRANSACTION`도 있다 (`src/contracts/storage-keys.ts`, `create-application.ts`, `boot-release-recovery.ts`). 행을 더한 커밋들이 이 문장을 따라 고치지 않았다. 고른 방법: 목록 문장을 지우고 `STORAGE_REGISTRY`를 정본으로 가리킨다. StoragePort가 거절하는 행의 규칙(`sensitive-forbidden` 분류와 `backend: "external"`, `getStorageDefinition`)만 문장으로 남긴다. 표 두 행은 "StoragePort 행" 한 행으로 합친다. 8행을 모두 적는 대안은 버렸다. 다음에 행이 늘면 같은 식으로 낡는다. 위험·한계: 이 문장을 보는 검사는 없다. 두 문서는 docs/README.md 2절(목표 설계)이라 verify:documentation이 읽지 않는다. 다시 목록을 적으면 리뷰가 손으로 찾아야 한다. 검증: 문서만 바꿨다. 검사 없음(위). `git grep -n 'COLOR_SCHEME' -- docs/architecture`에 목록 문장이 남지 않았다(starter-experience.md의 테마 설명 한 줄만 남는다). Refs: 1106/05-01 --- docs/architecture/client-cache-and-storage.md | 13 +++++++------ .../VD-13-client-cache-scope-and-persistence.md | 8 +++++--- 2 files changed, 12 insertions(+), 9 deletions(-) diff --git a/docs/architecture/client-cache-and-storage.md b/docs/architecture/client-cache-and-storage.md index 8e7143d6..95922e0e 100644 --- a/docs/architecture/client-cache-and-storage.md +++ b/docs/architecture/client-cache-and-storage.md @@ -47,9 +47,11 @@ generation마다 `QueryClient`를 만들고, query retry를 끄며, 30초 `stale `src/bootstrap/runtime-application.tsx`가 이 client를 실제 provider tree에 조립한다. -현재 `src/contracts/storage-keys.ts`에는 `COLOR_SCHEME`, -`CHUNK_RELOAD_GUARD`, 금지된 `AUTH_TOKEN`과 비활성 -`QUERY_PERSISTENCE`가 등록되어 있다. +등록된 Web Storage 키의 정본은 `src/contracts/storage-keys.ts`의 +`STORAGE_REGISTRY`다. 이 문서는 행 목록을 옮겨 적지 않는다. 옮겨 적은 목록은 +행이 늘 때 따라오지 않았다(1106/05-01). StoragePort(`getStorageDefinition`)는 +`classification: "sensitive-forbidden"` 행과 `backend: "external"` 행을 거절하고 +나머지 행만 읽고 쓴다. `src/adapters/storage/browser-storage-codec.ts`와 `browser-storage-adapter.ts`는 closed JSON codec, 기본 16,384-byte 상한, schema envelope, TTL과 동일 envelope를 쓰는 memory fallback을 제공한다. @@ -132,7 +134,7 @@ blocked/versionchange를 다루는 reference runtime이 있다. 이 설계는 | --- | --- | --- | --- | --- | | memory QueryClient | `COMPOSED` | server-state generation별 생성(session identity 변경 시 FENCED 뒤 새 client), global stale/gc/retry default | per-query policy | `DESIGNED_NOT_IMPLEMENTED` | | application query bridge | `COMPOSED` | AbortSignal, stale error, optimistic rollback/conflict surface | old-generation query/mutation callback 폐기 | `DESIGNED_NOT_IMPLEMENTED` | -| Web Storage | `COMPOSED` | 두 key, strict v1 envelope/codec, lazy TTL, global 16 KiB cap | per-key cap, HIT/MISS, durability, v2 scope, migration, sweep/logout | `DESIGNED_NOT_IMPLEMENTED` | +| Web Storage | `COMPOSED` | `STORAGE_REGISTRY`의 StoragePort 행, strict v1 envelope/codec, lazy TTL, global 16 KiB cap | per-key cap, HIT/MISS, durability, v2 scope, migration, sweep/logout | `DESIGNED_NOT_IMPLEMENTED` | | cross-tab invalidation | `COMPOSED` | release epoch(FNV-1a digest), versioned hint, duplicate/gap, BC→localStorage, registry pulse key, storageArea 동일성 검사, generation별 transport | composite scope epoch, durable ledger hook | `DESIGNED_NOT_IMPLEMENTED` | | generic IndexedDB | `AVAILABLE_NOT_COMPOSED` | reusable repository/maintenance runtime | product dataset schema/codec/query/policy composition | product selection `NOT_SELECTED` | | query persistence facade | `DESIGNED_NOT_IMPLEMENTED` | 없음, registry가 disabled 강제 | stable per-query record, bounded restore, namespace epoch/CAS | `DESIGNED_NOT_IMPLEMENTED` | @@ -1403,8 +1405,7 @@ invalidate-only runtime은 installed query contract가 실제로 소비하므로 | capability | 기본 | | --- | --- | | TanStack memory QueryClient | `COMPOSED` | -| 등록된 COLOR_SCHEME localStorage | `COMPOSED` | -| 등록된 CHUNK_RELOAD_GUARD sessionStorage | `COMPOSED` | +| `STORAGE_REGISTRY`의 StoragePort 행(`localStorage`·`sessionStorage`) | `COMPOSED` | | generic IndexedDB repository/maintenance reference | `AVAILABLE_NOT_COMPOSED` | | IndexedDB query persistence facade | `DESIGNED_NOT_IMPLEMENTED` | | product query persistence | `NOT_SELECTED` | diff --git a/docs/architecture/decisions/VD-13-client-cache-scope-and-persistence.md b/docs/architecture/decisions/VD-13-client-cache-scope-and-persistence.md index 571fbd94..b7c79db4 100644 --- a/docs/architecture/decisions/VD-13-client-cache-scope-and-persistence.md +++ b/docs/architecture/decisions/VD-13-client-cache-scope-and-persistence.md @@ -63,7 +63,7 @@ runtime의 구현 상태고, 후자는 제품 capability 선택 상태다. 하 | capability | 현재 상태 | 현재 보장 | | --- | --- | --- | | TanStack Query memory runtime | `COMPOSED` | runtime별 QueryClient, finite inactive GC, retry owner, query AbortSignal | -| registered Web Storage | `COMPOSED` | `COLOR_SCHEME`, `CHUNK_RELOAD_GUARD`만 strict codec/envelope로 사용 | +| registered Web Storage | `COMPOSED` | `STORAGE_REGISTRY`의 StoragePort 행만 strict codec/envelope로 사용. 행 목록은 `src/contracts/storage-keys.ts`가 정본이다 | | invalidate-only cross-tab runtime | `COMPOSED` | versioned topic, BroadcastChannel 우선, localStorage pulse fallback | | generic IndexedDB repository/maintenance runtime | `AVAILABLE_NOT_COMPOSED` | CAS, idempotency, transaction complete, policy binding, bounded lifecycle/migration | | session/account-scoped QueryClient lifecycle | `DESIGNED_NOT_IMPLEMENTED` | 없음; 현재 cache epoch는 release ID만 포함 | @@ -392,8 +392,10 @@ type WebStorageDefinition = Readonly<{ | 한 sweep에서 검사할 key | 16 | | 한 read에서 migration step | 2 | -현재 두 key는 각각 더 좁은 codec을 유지한다. `COLOR_SCHEME`은 public -origin-shared preference이고 `CHUNK_RELOAD_GUARD`는 tab session control이다. +현재 StoragePort 행은 행마다 더 좁은 `valueCodec`(`color-scheme-v1`, +`opaque-string-v1`)을 유지한다. `localStorage` 행은 public origin-shared +preference이고 `sessionStorage` 행은 tab session control이다. 행 목록은 +`src/contracts/storage-keys.ts`의 `STORAGE_REGISTRY`가 정본이다. server response, credential, signed URL, File/Blob, large draft와 queue를 Web Storage에 넣지 않는다. From 06357e9c0b29af15a74712323692ed1db8c5b4d1 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 6 Nov 2026 05:19:10 +0900 Subject: [PATCH 2/6] =?UTF-8?q?docs(manual):=20descriptor=20=EC=97=86?= =?UTF-8?q?=EB=8A=94=20=EB=AE=A4=ED=85=8C=EC=9D=B4=EC=85=98=EA=B3=BC=20?= =?UTF-8?q?=ED=85=8C=EC=8A=A4=ED=8A=B8=EC=9D=98=20operation=20ID=20?= =?UTF-8?q?=EA=B8=B8=EC=9D=84=20=EC=A0=81=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 1103/16-05로 `BoundMutation.operationId`가 brand 타입이 됐고, 그 값은 `commandMutationIdentity`만 만든다. 이 함수는 descriptor 모양 `{ contract: { operationId, method, retrySemantics } }`만 받는다. CHANGELOG "먼저 할 일" 2단계와 매뉴얼 01 7단계는 descriptor 상수 길만 적는다. V3 descriptor가 없는 쓰기(Fileserver 업로드 client는 `upload(request)`만 있다)와 테스트 fixture는 길이 없어, 따라 하면 `check:types`에서 막힌다. 템플릿은 자기 테스트에 `tests/helpers/mutation-operation-id.ts`를 두었지만 어느 문서도 그 helper를 말하지 않는다. 매뉴얼 01 안에서도 "손으로 적은 ID에 오타가 있으면 저장이 항상 실패한다"(BREAKING 전 동작)와 "문자열로 직접 적으면 `check:types`가 실패한다"가 서로 다르다. 고른 방법: 문서만 고친다(리뷰의 대안 A). descriptor 없는 쓰기는 descriptor 모양 객체를 넘기고, 키가 필요하면 `KEYED`, 아니면 `NEVER`를 적는다고 쓴다. 대조할 descriptor가 없어 그 ID는 intent 이름일 뿐이고 오타를 잡는 검사가 없다는 것도 적는다. 테스트는 `testMutationOperationId`를 쓰고 `requiresIdempotencyKey`는 따로 적는다. 매뉴얼 01의 "저장 때 실패" 문장은 손 객체를 넘긴 경우로 좁히고, "못 잡음" 항목을 descriptor가 있는 쓰기와 없는 쓰기로 나눈다. 버린 대안: 이름 있는 함수(B)나 Fileserver 업로드 descriptor 상수(C)를 공개하기. 공개 API가 늘고 코드 변경이라 이 문서 브랜치의 범위 밖이다. 리뷰도 A를 가장 작은 길로 적었다. 위험·한계: 손 객체가 공식 길이 된다. descriptor 없는 쓰기의 ID 오타는 여전히 아무 검사도 잡지 않는다(문서에 그렇게 적었다). 두 다운스트림의 손 ID 정책 중 몇 개가 이 길로 가야 하는지는 세지 않았다. 검증: 문서만 바꿨다. desktop batch에서 확인. corepack pnpm verify:documentation (매뉴얼 01이 새로 적은 경로 `tests/helpers/mutation-operation-id.ts`와 script `check:types:test`가 있는지) node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts tests/unit/documentation-readiness.test.ts Refs: 1106/09-01 --- CHANGELOG.md | 2 +- docs/manual/01-add-a-feature.md | 6 ++++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 75646dad..da8d37b2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,7 +22,7 @@ #### 옮기는 법 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`가 실패한다 (1103/16-05) +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) 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) diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index 17121c2a..a0522cdb 100644 --- a/docs/manual/01-add-a-feature.md +++ b/docs/manual/01-add-a-feature.md @@ -473,8 +473,10 @@ projectRequest: (input) => Object.freeze({ - 형식: `qinv.` + 소문자·숫자 26자. `scripts/create-feature.ts`의 `randomTopicSuffix`가 쓰는 방식이다. - `measureResult`에서 `JSON.stringify`를 쓰지 않는다. 문자열 바이트와 항목당 고정 크기로 어림한다(생성된 `measureItems` 참고). - 뮤테이션 정책의 operation ID와 `requiresIdempotencyKey`는 `commandMutationIdentity(_CONTRACT)`(`src/contracts/server-state.ts`)로 descriptor에서 받는다. 손으로 적지 않는다. - - 실행기는 intent의 operation ID가 descriptor와 다르면 보내기 전에 거부한다. 손으로 적은 ID에 오타가 있으면 저장이 항상 실패하고, 화면은 "요청을 처리할 수 없습니다"다. + - 실행기는 intent의 operation ID가 descriptor와 다르면 보내기 전에 거부한다. 문자열 ID는 그보다 먼저 `check:types`가 막는다(③). 그래서 저장 때 거부되는 것은 `commandMutationIdentity`에 손으로 만든 객체를 넘긴 오타뿐이다. 그때는 저장이 항상 실패하고, 화면은 "요청을 처리할 수 없습니다"다. - `requiresIdempotencyKey`는 `retrySemantics`가 `KEYED`일 때만 참이다. + - V3 HTTP descriptor가 없는 쓰기(Fileserver 업로드처럼 `execute`가 HTTP 실행기를 거치지 않는 것)는 descriptor 모양 객체를 넘긴다: `...commandMutationIdentity({ contract: { operationId: "", method: "POST", retrySemantics: "KEYED" } })`. intent가 멱등 키를 실어야 하면(Fileserver 업로드에 `idempotencyKey`를 넘길 때) `retrySemantics`는 `"KEYED"`, 아니면 `"NEVER"`다. 이 ID를 대조할 descriptor가 없으므로 ID는 intent의 이름일 뿐이고, 오타는 어느 검사도 잡지 않는다(③). + - 테스트에서 descriptor 없이 정책을 만들 때는 `tests/helpers/mutation-operation-id.ts`의 `testMutationOperationId("")`를 쓴다. 이 helper는 operation ID만 돌려주므로 `requiresIdempotencyKey`는 따로 적는다. 문자열을 그대로 적으면 `check:types:test`가 실패한다. - 쓰기 정책은 `duplicatePolicy: "REJECT_WHILE_ACTIVE"`, `invalidate: [topic]`을 쓴다. ```ts @@ -497,7 +499,7 @@ projectRequest: (input) => Object.freeze({ - topic·namespace·edge를 더하기만 하면 레지스트리 기준선은 바뀌지 않는다(additive). 9단계에서 할 일이 없다. - 뮤테이션 정책의 operation ID를 `commandMutationIdentity`로 받으면 descriptor 상수 이름의 오타는 `check:types`가 막는다. 쓰기 descriptor 대신 GET descriptor를 넘기면 바인딩 때 `commandMutationIdentity: is a GET; a mutation binds a write operation`으로 throw한다. - 뮤테이션 정책에 operation ID를 문자열로 직접 적으면 `check:types`가 실패한다. `BoundMutation.operationId`는 `MutationOperationId`이고, 이 값은 `commandMutationIdentity`만 만든다. 오류는 그 문자열을 `MutationOperationId`에 넣을 수 없다고 말한다. -- **못 잡음**: `commandMutationIdentity`에 descriptor 상수 대신 손으로 만든 객체(`{ contract: { operationId: "…", … } }`)를 넘기는 것. 그 오타는 저장할 때 실행기가 보내기 전에 거부한다(`MISSING_IDEMPOTENCY_KEY` 위반). +- **못 잡음**: `commandMutationIdentity`에 descriptor 상수 대신 손으로 만든 객체(`{ contract: { operationId: "…", … } }`)를 넘기는 것. descriptor가 있는 쓰기면 그 오타는 저장할 때 실행기가 보내기 전에 거부한다(`MISSING_IDEMPOTENCY_KEY` 위반). descriptor가 없는 쓰기(②의 Fileserver 업로드 등)는 대조할 곳이 없어 오타가 그대로 intent 이름이 된다. - `bindQuery`의 `owner`·`operationId`, 뮤테이션 정책의 `owner`는 적지 않는다. 읽는 곳이 없어 `@deprecated` 선택 칸이 됐고, 다음 릴리스에서 지운다. 요청 기록의 operation ID는 descriptor의 것이다. - **못 잡음**: `definitionId` 중복. 유일성 검사가 없다. From 2f0f2bba176891d8192b434973ef1967e450d153 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 6 Nov 2026 05:20:15 +0900 Subject: [PATCH 3/6] =?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이다. From ddc6353d81eb61f57b90e1051e483e73399dba1f Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 6 Nov 2026 05:21:14 +0900 Subject: [PATCH 4/6] =?UTF-8?q?docs(review):=20D7=20=EC=BB=A4=EB=B0=8B=20?= =?UTF-8?q?=EB=B3=B8=EB=AC=B8=EC=9D=98=20=EB=8B=A4=EC=8B=9C=20=EC=A7=93?= =?UTF-8?q?=EA=B8=B0=20=EC=A0=84=20=ED=95=B4=EC=8B=9C=EB=A5=BC=20=EB=A7=9E?= =?UTF-8?q?=EB=8A=94=20=ED=95=B4=EC=8B=9C=EB=A1=9C=20=EC=A0=81=EB=8A=94?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: D7 커밋 `287dc6f` 본문의 "늘어난 곳"이 1105/03-01과 1105/08-03에 적은 해시 둘은 통합에서 다시 짓기 전 해시라 `bbde570`에서 닿지 않는다 (`git merge-base --is-ancestor` rc=1). 같은 변경은 이 이력에서 `5c0b37e`, `f849d78`이다(`git log --format='%h %s' 409d72e..bbde570`, rc=0). 원격 clone에는 두 객체가 없다. 통합 절차에 CHANGELOG·커밋 본문의 해시를 범위와 대조하는 단계가 없다. 고른 방법: 올린 이력은 고쳐 쓰지 않는다(`287dc6f`을 amend·rebase하지 않음). 1105 README 16.2절 D7 행에 본문의 두 해시가 다시 짓기 전 것이라는 것과 이 이력의 해시를 적는다(지시대로 그 행만). 닿지 않는 해시는 새로 적지 않는다. 적으면 아래 대조에 다시 걸린다. CHANGELOG 머리말의 "그 절의 해시는 모두 그 범위에 있다" 뒤에, 해시를 다시 쓴 뒤 절과 범위 커밋 본문의 해시를 `git merge-base --is-ancestor`로 대조하고 결과를 리뷰 README 조치 절에 적는 한 단계를 둔다(리뷰의 대안 b). 버린 대안: 해시를 대조하는 단위 테스트(대안 c). 싸지 않다. - 복사한 프로젝트에는 템플릿 이력이 없거나(tech-log는 이력 없이 3-way로 옮긴다) CI checkout이 얕을 수 있어, 테스트가 그때 건너뛰어야 한다. 조건부로 도는 테스트는 이번 라운드 지시가 막는다. - 커밋 본문은 작업 트리가 아니라 `git log` 범위를 읽어야 하고, 이미 올린 `287dc6f`이 영구히 걸리므로 예외가 필요하다. 예외 추가도 지시가 막는다. - CHANGELOG에는 다른 repo 해시(`d3810a0` 등)가 섞여 있어 repo 표시 규칙부터 정해야 한다. 위험·한계: 대조는 사람이 하는 단계다. 빼먹으면 같은 일이 다시 난다. 완료 기준 "다음 통합 기록에 그 대조 결과가 있다"는 이번 라운드를 합칠 오케스트레이터가 채운다. 새 clone에서 `git show 287dc6f` 본문의 두 해시는 여전히 열리지 않는다. 검증: 문서만 바꿨다. desktop batch에서 확인. node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts (새 괄호 `(1106/14-02, 1105 README 16.2)`가 참조 꼴을 지킨다) git merge-base --is-ancestor 5c0b37e bbde570 && git merge-base --is-ancestor f849d78 bbde570 Refs: 1106/14-02 --- CHANGELOG.md | 2 +- docs/reviews/2026-11-05-maturity-review/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 35e8406a..7fbaae4d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,7 @@ - **[계약]** 백엔드, 배포 설정, CI, 또는 기능 코드가 함께 바뀌어야 하는 변경이다(헤더, 변수, 게이트, 공개 포트). - 표시가 없으면 템플릿 안에서 끝나는 수정이다. - 괄호 안 ID는 리뷰 발견 ID다. `MMDD/NN-MM`으로 적는다. `MMDD`는 리뷰 폴더 `docs/reviews/YYYY-MM-DD-maturity-review/`의 월일이고, 근거와 재현 조건은 그 폴더의 영역 문서에 있다. 복사한 프로젝트가 README대로 `docs/reviews/`를 지웠다면 이 폴더와 `PRODUCT.md`는 원본 템플릿 repo에서 찾는다. 라운드마다 `NN-MM`을 새로 매기므로 같은 `14-02`라도 라운드가 다르면 다른 결함이다. `F-N`은 그 라운드 `FOLLOW-UP.md`의 ID다. 리뷰 README의 절은 `MMDD README N.N`으로 적고 다시 돌린 항목은 그 뒤에 `X2`처럼 번호를 붙인다. 영역 문서가 따로 매긴 ID는 `MMDD NN 영역 P-NN-NN`, 짝 백엔드 리뷰의 ID는 `백엔드 리뷰 MMDD/NN-MM`으로 적는다. `tests/unit/changelog-review-ids.test.ts`가 라운드 없는 ID와 이 꼴을 벗어난 참조를 막는다. -- 0.2.0의 커밋 해시는 브랜치 `fix/maturity-review-2026-09-25`에서 만들었고, `main`에서도 같은 해시로 찾을 수 있다(2026-11-03에 52개 모두 확인). 그 뒤 절은 절 머리에 범위(기준 커밋과 브랜치)를 적고, 그 절의 해시는 모두 그 범위에 있다. 0.2.0의 커밋 제목은 라운드 없이 ID만 적었다(`git log --grep '03-03'`). +- 0.2.0의 커밋 해시는 브랜치 `fix/maturity-review-2026-09-25`에서 만들었고, `main`에서도 같은 해시로 찾을 수 있다(2026-11-03에 52개 모두 확인). 그 뒤 절은 절 머리에 범위(기준 커밋과 브랜치)를 적고, 그 절의 해시는 모두 그 범위에 있다. 통합에서 해시를 다시 쓴 뒤(fixup 접기, rebase)에는 절의 해시와 범위 커밋 본문의 해시를 `git merge-base --is-ancestor <해시> <브랜치 끝>`으로 하나씩 대조하고, 결과를 그 라운드 리뷰 README의 조치 절에 적는다. 1105 통합은 이 대조를 하지 않아, 올린 커밋 `287dc6f`의 본문이 다시 짓기 전 해시 둘을 가리킨다. 맞는 해시는 그 라운드 리뷰 README의 D7 행에 있다 (1106/14-02, 1105 README 16.2). 0.2.0의 커밋 제목은 라운드 없이 ID만 적었다(`git log --grep '03-03'`). ## 미출시 — `409d72e` → 브랜치 `fix/maturity-review-2026-11-05-b` diff --git a/docs/reviews/2026-11-05-maturity-review/README.md b/docs/reviews/2026-11-05-maturity-review/README.md index bf17e563..ed3ef994 100644 --- a/docs/reviews/2026-11-05-maturity-review/README.md +++ b/docs/reviews/2026-11-05-maturity-review/README.md @@ -537,7 +537,7 @@ CLAUDE.md 목록, local env(CI 값 없음): | D4 | (가) 러너 요구에 비특권 user namespace를 적고, 사전 점검이 `bwrap --unshare-net`을 실제로 돌린다(PR A `9655958`, 기준선 `67082cc`) | 메인 세션 지시. 러너 요구는 요구 목록·gate 정의·workflow 주석 셋에 적는다 | (나) 샌드박스 방식 변경 | 러너가 namespace를 허용하지 않게 바뀔 때 | | D5 | 제품 gate를 release `needs`에 묶는다(`92d5019`) | 제품 merge 검사가 실패한 run에서 release를 멈춘다 | 문서로 제한 명시 | — | | D6 | 실행별 출력 디렉터리 + 빈 포트(`ddbda4d`, `f4d5761`, `0e72c0c`, `510e2bb`) | 메인 세션 지시와 완료 기준(한 checkout 두 e2e 동시 실행) | "한 checkout 한 실행"을 문서로 명시 | 게이트·증거 검사도 run ID를 읽게 할 때 | -| D7 | 초기 JS 예산 `initialJsGzipBytes`를 204,800 → 206,848 B(202 KiB)로 올린다(`287dc6f`). 메인 세션 결정, 2026-11-06 | 아래 「D7 근거」 | 줄이기. 리뷰 라운드 중간의 설계 변경이라 다음 라운드 숫자를 흐린다. 청크를 합치는 것만으로는 663 B를 채우지 못한다 | 예산을 다시 넘을 때, 또는 1103/13-03(zod 갱신, 약 7 KB)을 정할 때. 그때 03-01·02-01의 런타임 검사를 빌드 시점으로 옮기는 것부터 본다. 이 상향은 13-03을 정하지 않는다 | +| D7 | 초기 JS 예산 `initialJsGzipBytes`를 204,800 → 206,848 B(202 KiB)로 올린다(`287dc6f`). 메인 세션 결정, 2026-11-06. `287dc6f` 본문의 "늘어난 곳"이 03-01·08-03에 적은 해시 둘은 통합에서 다시 짓기 전 해시라 PR B 이력(`bbde570`)에서 닿지 않는다. 이 이력의 해시는 03-01 `5c0b37e`, 08-03 `f849d78`이다(아래 「D7 근거」와 같다). 올린 이력이라 본문은 고치지 않는다(1106/14-02) | 아래 「D7 근거」 | 줄이기. 리뷰 라운드 중간의 설계 변경이라 다음 라운드 숫자를 흐린다. 청크를 합치는 것만으로는 663 B를 채우지 못한다 | 예산을 다시 넘을 때, 또는 1103/13-03(zod 갱신, 약 7 KB)을 정할 때. 그때 03-01·02-01의 런타임 검사를 빌드 시점으로 옮기는 것부터 본다. 이 상향은 13-03을 정하지 않는다 | D7 근거: From 1eaa6447dc980023085fca1d50056f1f97ee8127 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 6 Nov 2026 05:22:31 +0900 Subject: [PATCH 5/6] =?UTF-8?q?docs(perf):=20=EC=B4=88=EA=B8=B0=20JS=20?= =?UTF-8?q?=EC=98=88=EC=82=B0=20=ED=8F=AD=EC=9D=98=20=EA=B7=BC=EA=B1=B0?= =?UTF-8?q?=EC=99=80=20=EB=90=98=EB=8F=8C=EB=A6=BC=20=EA=B7=9C=EC=B9=99?= =?UTF-8?q?=EC=9D=84=20=EC=A0=81=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: D7이 초기 JS 예산을 204,800 → 206,848 B로 올렸다(`287dc6f`). 드릴 (FE-GATE-020, 생성 기능 둘)이 넘은 양은 665 B(CI env)인데 2,048 B를 올렸다. 문서는 올린 뒤 여유만 적고 왜 그 폭인지, 언제 다시 내리는지를 적지 않는다. 재검토 조건 "예산을 또 넘을 때"는 이번 상향의 조건과 같아서, 내릴 조건이 없다. 다음 담당자는 예산을 넘었을 때 올릴지 줄일지 문서에서 알 수 없다. 고른 방법: 메인 세션 결정 D9를 따른다. 206,848 B를 그대로 두고 `docs/operations/performance-evidence.md`의 예산 항목에 세 가지를 적는다. - 폭의 근거: 드릴 측정값 205,465 B(CI env, `bbde570`) + 기능 하나의 상한 1 KiB = 206,489 B를 KiB 단위로 올림해 202 KiB = 206,848 B. 드릴 위 여유 1,383 B가 기능 하나와 올림 359 B로 나뉜다. 템플릿 자신의 몫은 이 규칙에 없다. - 되돌림 규칙: D7의 재검토 조건마다 드릴을 다시 재고, 204,800 B 이하이면 같은 규칙으로 내린다. - 사용자가 이 결정을 뒤집을 수 있다. 버린 대안(리뷰 15-01의 대안): 예산을 드릴 + 256 B로 되돌리기(다음 템플릿 변경마다 넘는다), 테스트로 예산 값을 여유 규칙에 묶기(D9가 고르지 않았다). 위험·한계: 규칙은 문서에만 있다. 예산 값을 규칙 밖으로 바꿔도 실패하는 테스트는 없다(리뷰 대안 c는 고르지 않았다). 205,465 B는 2026-11-06의 한 번 측정이고, 다음 측정은 "다시 볼 때"에 한다. 결정 기록 자체는 오케스트레이터가 2026-11-06 리뷰 README에 적는다. 이 문서는 그 파일을 가리킨다. 검증: 문서만 바꿨다. desktop batch에서 확인. corepack pnpm verify:documentation (새로 적은 경로 `docs/reviews/2026-11-06-maturity-review/README.md`와 FE-GATE-020을 본다) node scripts/run-vitest.ts run tests/unit/documentation-readiness.test.ts tests/unit/template-feature-removal-documents.test.ts Refs: 1106/15-01 --- docs/operations/performance-evidence.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/operations/performance-evidence.md b/docs/operations/performance-evidence.md index 081b6f40..fe5b48f1 100644 --- a/docs/operations/performance-evidence.md +++ b/docs/operations/performance-evidence.md @@ -51,6 +51,17 @@ Performance evidence is deliberately split by measurement context: 넘을 때, 또는 1103/13-03(zod 갱신, 약 7 KB)을 정할 때. 그때 03-01·02-01의 런타임 검사를 빌드 시점으로 옮기는 것부터 본다. 이 상향은 13-03을 정하지 않는다. 결정 기록은 `docs/reviews/2026-11-05-maturity-review/README.md` 16절이다. + - 폭의 근거(1106/15-01, 결정 D9): 예산은 드릴 측정값에 기능 하나의 상한 + (`perFeatureGzipBytes` 상한 1 KiB)을 더해 KiB 단위로 올림한 값이다. 드릴은 + CI env에서 205,465 B였다(2026-11-06, `bbde570`, FE-GATE-020). 205,465 + + 1,024 = 206,489 B를 올림하면 202 KiB = 206,848 B다. 그래서 드릴 위의 여유 + 1,383 B는 기능 하나(1,024 B)와 올림(359 B)이다. 이 규칙에 템플릿 자신이 더 + 쓸 몫은 없다. 템플릿 변경이 이 여유를 쓰면 그만큼 기능 몫이 준다. + - 되돌림 규칙: 위 "다시 볼 때"마다 드릴을 다시 잰다. 드릴 측정값이 204,800 B + 이하이면 같은 규칙(드릴 + 1 KiB를 KiB 단위로 올림)으로 예산을 내린다. 그때 + 규칙의 값은 201 KiB 이하다. + - D9(206,848 B를 그대로 둔다)는 메인 세션이 2026-11-06에 정했다. 사용자가 뒤집을 + 수 있다. 결정 기록은 `docs/reviews/2026-11-06-maturity-review/README.md`다. - 기능 실행부(`feature-runtime.ts`)는 라우트에 들어갈 때 받는 lazy chunk다. lazy chunk 예산은 파일마다 120 KiB(`lazyChunkGzipBytes`)다. From 43ed03d14fc4e42612441cd6d762eb4c9a07dc2a Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 6 Nov 2026 05:23:03 +0900 Subject: [PATCH 6/6] =?UTF-8?q?docs(perf):=20=EC=B4=88=EA=B8=B0=20?= =?UTF-8?q?=ED=8C=8C=EC=9D=BC=20=EC=83=81=ED=95=9C=20=EB=AC=B8=EC=9E=A5?= =?UTF-8?q?=EC=9D=B4=20=ED=85=9C=ED=94=8C=EB=A6=BF=20=ED=8C=8C=EC=9D=BC=20?= =?UTF-8?q?=EC=88=98=EB=A5=BC=20=EA=B8=B0=EB=A1=9D=EC=97=90=EC=84=9C=20?= =?UTF-8?q?=EC=9D=BD=EA=B2=8C=20=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: `docs/operations/performance-evidence.md`의 초기 파일 상한 문장이 "상한은 템플릿 그대로의 수(26)에 6을 더한 32다"라고 적는다. 지금 기록은 27개다(`config/scale/feature-shape-ceilings.json`의 `initialJavascript.files`, FE-GATE-012 `27 / 32 files`). 기록을 27로 다시 쓴 `0fee3fe`이 이 문장을 고치지 않았다. 1103/15-02의 완료 기준 "문서·JSON에 서로 다른 기준선이 없다"를 다시 어긴다. 같은 문서의 바이트 쪽은 이미 숫자를 적지 않고 기록을 가리킨다. 고른 방법: 지금 수를 지우고, 상한 32가 정할 때 6칸을 더한 값이라는 것만 남긴다. 지금 템플릿 수는 그 기록이 정본이고 남은 칸은 32에서 그 값을 뺀 것이라고 적는다. 바이트 절의 "기준선 숫자는 이 문서에 적지 않는다"와 같은 방식이다. 숫자를 27로 고치는 대안은 버렸다. 다음에 파일이 하나 늘면 같은 식으로 낡는다. 위험·한계: 상한 값 32는 예산 값이라 그대로 적었다. `budgets.json`을 바꾸면 이 문장도 고쳐야 하고, 그것을 보는 검사는 없다. 기록 파일은 참조 기능과 함께 지워질 수 있고, 그때 문서 검사는 이 경로를 요구하지 않는다 (`scripts/lib/removable-template-features.ts`). 검증: 문서만 바꿨다. desktop batch에서 확인. corepack pnpm verify:documentation node scripts/run-vitest.ts run tests/unit/documentation-readiness.test.ts tests/unit/template-feature-removal-documents.test.ts Refs: 1103/15-02 --- docs/operations/performance-evidence.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/operations/performance-evidence.md b/docs/operations/performance-evidence.md index fe5b48f1..30de5b39 100644 --- a/docs/operations/performance-evidence.md +++ b/docs/operations/performance-evidence.md @@ -217,8 +217,10 @@ the example can never serve as production evidence. - HTTP/2에서는 (나)도 Fast 3G 85 ms, Fast 4G 22 ms 차이다(위 둘째 표). 그래서 템플릿은 HTTP/2 이상으로 서빙한다고 본다. 초기 파일 수는 -`config/performance/budgets.json`의 `initialJsFiles`가 막는다(1103/15-05). 상한은 -템플릿 그대로의 수(26)에 6을 더한 32다. 기능의 지연 페이지가 셸과 같은 구성요소 +`config/performance/budgets.json`의 `initialJsFiles`가 막는다(1103/15-05). 상한 32는 +정할 때 템플릿 그대로의 수에 6칸을 더한 값이다. 지금 템플릿 그대로의 수는 이 문서에 +적지 않는다. 위 기록 `config/scale/feature-shape-ceilings.json`의 +`initialJavascript.files`가 정본이고, 남은 칸은 32에서 그 값을 뺀 것이다. 기능의 지연 페이지가 셸과 같은 구성요소 (`Button`, `SearchField` 등)를 쓰면 그 구성요소가 별도 공유 청크로 떨어져 초기 파일이 하나 는다(1103 X2 #4). 상한을 현재 수와 같게 두면 그런 기능 하나로 게이트가 실패한다. HTTP/2에서 파일 하나는 거의 비용이 없다(위 표). 32를 넘으면 상한을 올리기