chore(review): 1106 문서·CHANGELOG 조치 브랜치를 합친다
This commit is contained in:
@@ -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` |
|
||||
|
||||
@@ -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<Value> = 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에 넣지 않는다.
|
||||
|
||||
|
||||
@@ -475,8 +475,10 @@ projectRequest: (input) => Object.freeze({
|
||||
- 형식: `qinv.` + 소문자·숫자 26자. `scripts/create-feature.ts`의 `randomTopicSuffix`가 쓰는 방식이다.
|
||||
- `measureResult`에서 `JSON.stringify`를 쓰지 않는다. 문자열 바이트와 항목당 고정 크기로 어림한다(생성된 `measureItems` 참고).
|
||||
- 뮤테이션 정책의 operation ID와 `requiresIdempotencyKey`는 `commandMutationIdentity(<OPERATION>_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: "<ID>", method: "POST", retrySemantics: "KEYED" } })`. intent가 멱등 키를 실어야 하면(Fileserver 업로드에 `idempotencyKey`를 넘길 때) `retrySemantics`는 `"KEYED"`, 아니면 `"NEVER"`다. 이 ID를 대조할 descriptor가 없으므로 ID는 intent의 이름일 뿐이고, 오타는 어느 검사도 잡지 않는다(③).
|
||||
- 테스트에서 descriptor 없이 정책을 만들 때는 `tests/helpers/mutation-operation-id.ts`의 `testMutationOperationId("<ID>")`를 쓴다. 이 helper는 operation ID만 돌려주므로 `requiresIdempotencyKey`는 따로 적는다. 문자열을 그대로 적으면 `check:types:test`가 실패한다.
|
||||
- 쓰기 정책은 `duplicatePolicy: "REJECT_WHILE_ACTIVE"`, `invalidate: [topic]`을 쓴다.
|
||||
|
||||
```ts
|
||||
@@ -499,7 +501,7 @@ projectRequest: (input) => Object.freeze({
|
||||
- topic·namespace·edge를 더하기만 하면 레지스트리 기준선은 바뀌지 않는다(additive). 9단계에서 할 일이 없다.
|
||||
- 뮤테이션 정책의 operation ID를 `commandMutationIdentity`로 받으면 descriptor 상수 이름의 오타는 `check:types`가 막는다. 쓰기 descriptor 대신 GET descriptor를 넘기면 바인딩 때 `commandMutationIdentity: <operationId> 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` 중복. 유일성 검사가 없다.
|
||||
|
||||
|
||||
@@ -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`)다.
|
||||
|
||||
@@ -206,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를 넘으면 상한을 올리기
|
||||
|
||||
@@ -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 근거:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user