docs: 번역하며 찾은 낡은 서술을 코드·설정에 맞춘다

문제: 살아 있는 문서를 옮길 때 뜻을 바꾸지 않는다는 규칙 때문에 남겨
둔 낡은 서술이 있다.
- contract-ownership: 계약 파일 「39개」. 지금 src/contracts의 .ts는 44개다.
- capability-consumer-experience: Local Draft를 「두 번째 구체 소비자」,
  「두 feature」라고 부른다. 지금은 제품 feature가 아니라 테스트 fixture
  (tests/fixtures/indexeddb-consumer)다.
- static-delivery: initialJavascript.files가 「예시 feature 기준」이라고
  한다. feature-shape-ceilings.json은 feature가 없는 지금 템플릿 빌드라고
  적는다.
- .dependency-cruiser.json:254 주석이 번호 없는 layers.md의 「§4」를 가리킨다.
- runbook 문서 제목 셋이 runbooks.json title과 다르다. FE-RB-002는 영어
  원문부터 manifest가 빠져 있었고, 001·003은 번역에서 갈라졌다.
- ci-quality-gates: zod 행의 고친 버전은 4.6.6인데 이유 칸은 4.6.7을 말한다.
  4.6.7은 올렸을 때 잰 버전이다(26ca2fdb 원문 "4.6.7 also adds").
- 같은 문서 FE-GATE-016 문단 끝 두 문장은 원래 runbook record 고정 경로
  문단의 것이다(6c52cdb9 원문). 폐기 문장 뒤로 밀려 뜻이 끊겼다.

고른 방법: 숫자는 옮겨 적지 않고 정본(src/contracts/)을 가리킨다.
Local Draft는 fixture라고 쓰고, 편의 프로필을 들일 조건을 「IndexedDB를
쓰는 제품 feature」로 좁힌다. 절 번호는 절 이름으로, 문서 제목은 등록부
title로 맞춘다. zod는 「고친 버전 이상으로 올리면」으로 쓰고 잰 버전과
날짜를 괄호에 둔다. 두 문장은 원래 문단으로 옮긴다.

위험: zod 7 KB는 다시 재지 않았다(2026-11-04 측정값 그대로).
cruiser 주석은 check:architecture 위반 메시지의 why 줄에 나온다. 이 주석을
비교하는 시험은 없다.

검증: 각 사실을 git ls-files, feature-shape-ceilings.json, runbooks.json,
layers.md 절 제목, 원문 커밋으로 확인했다. 문서 검사와 관련 시험은
desktop에서 돌린다.
This commit is contained in:
DongHyeonka
2026-11-12 09:40:51 +09:00
parent 8acf07c2f6
commit 374af98640
8 changed files with 16 additions and 15 deletions
+1 -1
View File
@@ -251,7 +251,7 @@
},
{
"name": "adapters-do-not-know-other-concrete-adapters",
"comment": "docs/architecture/layers.md §4: a concrete adapter never depends on another concrete adapter. The adapter kernel is shared on purpose and any adapter may import it: src/adapters/platform/** (shared mechanisms only: clock, abort primitive, capacity guard, IndexedDB connection and transaction, Retry-After, JSON member scanner; plus two bootstrap-only services, see layers.md), src/adapters/browser-file-storage/result.ts (browser-data result helpers) and src/adapters/cross-context-invalidation/index.ts (the cross-context invalidation transport and its types). Owner: frontend-platform. No new file-level exception is added here; a new shared primitive goes into src/adapters/platform/.",
"comment": "docs/architecture/layers.md, section \"adapter kernel\": a concrete adapter never depends on another concrete adapter. The adapter kernel is shared on purpose and any adapter may import it: src/adapters/platform/** (shared mechanisms only: clock, abort primitive, capacity guard, IndexedDB connection and transaction, Retry-After, JSON member scanner; plus two bootstrap-only services, see layers.md), src/adapters/browser-file-storage/result.ts (browser-data result helpers) and src/adapters/cross-context-invalidation/index.ts (the cross-context invalidation transport and its types). Owner: frontend-platform. No new file-level exception is added here; a new shared primitive goes into src/adapters/platform/.",
"severity": "error",
"from": {
"path": "^src/adapters/([^/]+)/"
@@ -111,14 +111,15 @@ Local Draft 소비자가 아직 `src/features/` 아래 있을 때 잰 값(09-12)
- 내구성, 스케줄링, 관측
이 복잡함은 feature가 아니라 조립·플랫폼 경계에 둔다.
Local Draft 세로 slice는 이제 두 번째 구체 소비자다.
Local Draft 세로 slice는 이 repository port를 feature 모양으로 쓰는 구체 소비자다.
다만 제품 feature가 아니라 테스트 fixture(`tests/fixtures/indexeddb-consumer`)다.
이 소비자는 안정된 연결 지점(seam)이 타입이 있는 repository provider와,
feature가 소유한 repository 식별자라는 것을 확인한다.
dataset 범위, 보존, 마이그레이션, codec, 수명 주기 권한 설정을 만능
`create...Repository<T>` factory 하나로 안전하게 합칠 수 있다는 것은 보여 주지 **않는다**.
그래서 편의 프로필은 IndexedDB를 쓰는 다른 제품 feature가 같은 인프라 정책을 되풀이한 뒤에만 들인다.
두 feature가 같은 repository port를 쓴다는 이유만으로 들이지 않는다.
그래서 편의 프로필은 IndexedDB를 쓰는 제품 feature가 생기고, 그 feature들이 같은 인프라 정책을 되풀이한 뒤에만 들인다.
여러 소비자가 같은 repository port를 쓴다는 이유만으로 들이지 않는다.
## 소비자 품질 검토 체크리스트
+2 -2
View File
@@ -39,7 +39,7 @@ bootstrap, presentation, application 모듈을 import하지 못하게 막는다.
## 감사 결과
2026년 9월 아키텍처 리뷰를 계기로 계약 파일 39개 전체의 import 그래프를 감사했다.
2026년 9월 아키텍처 리뷰를 계기로 그때 `src/contracts`에 있던 계약 파일 전체의 import 그래프를 감사했다. 지금 파일 목록은 `src/contracts/`가 정본이다.
### capability 소유 계약을 옮김
@@ -112,4 +112,4 @@ runtime에 설치됐다는 사실을 message 소유로 보지 않는다.
- 같은 정의가 필요한 빌드·release·runtime wire 기준이 없다.
- 정의를 그 owner로 옮겨도 안쪽 방향 의존성 규칙을 어기지 않는다.
39라는 숫자를 줄이려고 계약을 옮기지 않는다. 목표는 디렉터리를 작게 하는 것이 아니라 소유를 분명히 하는 것이다.
계약 파일 수를 줄이려고 계약을 옮기지 않는다. 목표는 디렉터리를 작게 하는 것이 아니라 소유를 분명히 하는 것이다.
+1 -1
View File
@@ -44,7 +44,7 @@ rollback은 이전 불변 release의 HTML·asset·config·API·manifest 묶음
미리 불러온다(preload). 몇 개까지 허용할지는 `config/performance/budgets.json`의
`initialJsFiles`가 정한다. 지금 개수는
`config/scale/feature-shape-ceilings.json`의 `initialJavascript.files`이고, 이
값은 예시 feature를 기준으로 한다. HTTP/1.1에서는 host마다 연결이 여섯 개라
값은 feature가 없는 지금 템플릿 빌드에서 잰 것이다. HTTP/1.1에서는 host마다 연결이 여섯 개라
파일이 줄을 선다. 그래서 Fast 3G에서 첫 화면이 초기 chunk를 묶었을 때보다 약
1초 늦게 떴다(2026-11-03). HTTP/2에서는 차이가 100 ms 미만이었다. 그래서
템플릿은 chunk를 나눈 채로 둔다. HTTP/1.1로만 서빙할 수 있는 제품은
+5 -5
View File
@@ -333,7 +333,9 @@ release 증거는 다음 release 승격까지, drill 증거는 다음 production
증거는 집계까지 보관한다.
runbook job은 고정 경로 `artifacts/runbooks/<runbook-id>/record.json`에 쓴다. 바뀌는
release identity는 record 안에 저장한다.
release identity는 record 안에 저장한다. 그래서 게이트 증거를 찾는 일이 `RELEASE_ID`의
slash나 그 밖의 provider별 문자에 영향을 받지 않는다. 그러면서도 workflow 산출물은 각자
자기 run 범위에 남는다.
runbook drill(`drill:runbook`, FE-GATE-021..025)은 판정마다 `PASS`, `FAIL`,
`UNVERIFIED` 중 하나로 기록한다(`scripts/drill-runbook.ts`, record schema는
@@ -411,9 +413,7 @@ drill은 `FAIL`(exit 1)이다. 그렇지 않고 `UNVERIFIED`가 하나라도 있
production 단계는 닫히지 않는다. 의도한 결과다. 로컬 drill은 승격한 release를 rollback할
수 있다는 것을 보여 줄 수 없다. FE-GATE-016(`rollback-drill`)은 FE-GATE-025와 같은
FE-RB-005 drill을 돌렸으므로 폐기했다(`scripts/contracts/ci-gates.ts`의
`RETIRED_GATE_IDS`). 이렇게 하면 게이트 증거를 찾는 일이 `RELEASE_ID`의 slash나 그 밖의
provider별 문자에 영향을 받지 않는다. 그러면서도 workflow 산출물은 각자 자기 run 범위에
남는다.
`RETIRED_GATE_IDS`).
브라우저를 쓰는 merge 게이트는 버전을 고정한 Chromium, Firefox, WebKit 엔진을 설치해
실행한다. 그래서 route 동작, reflow, 기본 dialog 동작, theme 유지, 자동 접근성 검사는
@@ -522,7 +522,7 @@ nanoid, source-map-js)은 선언한 범위 안에서 업데이트해서 없어
| Advisory | 패키지 | 고친 버전 | 아직 업데이트하지 않은 이유 |
|---|---|---|---|
| GHSA-mrhx-c7xc-m3w5 (high) | `zod`(production. 지금 버전은 `package.json`) | 4.6.6 | production 직접 의존성을 올리려면 `config/security/dependency-change-evidence.json` 항목이 필요하고, 그 항목의 reviewer는 owner가 아니어야 한다. 4.6.7은 초기 JavaScript를 gzip으로 약 7 KB 늘려 번들 예산을 넘는다. 그래서 업데이트에는 예산 결정도 필요하다. 앱은 HTTP 본문을 바이트 상한을 두고 읽는다. 그래서 이 advisory가 필요로 하는 큰 collection 입력이 좁아진다(리뷰 추정) |
| GHSA-mrhx-c7xc-m3w5 (high) | `zod`(production. 지금 버전은 `package.json`) | 4.6.6 | production 직접 의존성을 올리려면 `config/security/dependency-change-evidence.json` 항목이 필요하고, 그 항목의 reviewer는 owner가 아니어야 한다. 고친 버전 이상으로 올리면 초기 JavaScript가 gzip으로 약 7 KB 늘어 번들 예산을 넘는다(2026-11-04에 4.6.7로 잰 값). 그래서 업데이트에는 예산 결정도 필요하다. 앱은 HTTP 본문을 바이트 상한을 두고 읽는다. 그래서 이 advisory가 필요로 하는 큰 collection 입력이 좁아진다(리뷰 추정) |
| GHSA-qwww-vcr4-c8h2 (high) | `react-router`, `react-router-dom`을 거쳐 들어옴(production. 지금 버전은 `pnpm-lock.yaml`) | 7.18.2 | 같은 evidence 규칙을 따른다. 이 advisory는 RSC 모드에 관한 것이다. browser router를 쓰는 이 SPA는 RSC 모드를 쓰지 않는다(리뷰 추정, 확인하지 않음). 7.18.5는 초기 JavaScript를 약 470 B 늘린다 |
두 provider role은 서로 다른 key ID뿐 아니라 canonical DER-SPKI public-key bytes도
+1 -1
View File
@@ -1,4 +1,4 @@
# FE-RB-001 — 부트 설정 실패
# FE-RB-001 — boot 설정 실패
`BOOT_CONFIG_FAILURE`가 나고, 한 번만 허용된 재요청(refetch)도 실패하면 이
runbook을 시작한다. 제품 route를 mount하지 않고 안전한 지원 화면(support
+1 -1
View File
@@ -1,4 +1,4 @@
# FE-RB-002 — chunk 또는 배포 불일치
# FE-RB-002 — chunk·manifest·배포 불일치
`CHUNK_LOAD_FAILURE`, `RELEASE_MANIFEST_FAILURE`, `DEPLOY_MISMATCH` 중 하나가
나면 시작한다. 저장하지 않은 상태(dirty state)를 잃을 수 있으면 경고한다.
+1 -1
View File
@@ -1,4 +1,4 @@
# FE-RB-003 — 백엔드 API 품질 저하
# FE-RB-003 — 백엔드 API 저하
다음 중 하나면 시작한다. 더 재시도하지 않는(terminal) 네트워크·시간 초과·5xx
실패가 최근 5분 이동 구간(rolling)의 기준치를 넘는다. 또는 `SCHEMA_MISMATCH`가