chore(merge): 문서 체계 PR #15가 들어간 main을 받는다
This commit is contained in:
@@ -5,11 +5,11 @@ paths:
|
||||
|
||||
# 문서를 고칠 때
|
||||
|
||||
- 문서 위치·묶음·언어 규칙은 `docs/README.md`, 쓰는 절차는 `docs/work/docs-writing.md`다.
|
||||
- 기록 문서(`docs/reviews/`, `docs/history/`, `docs/superpowers/`, 결정 기록)는 머리 블록만 고친다. 리뷰 영역 문서를 리뷰 뒤에 고치지 않는다. 예외는 그 라운드를 맡은 총괄이 리뷰 README에 「조치」 절(과 그 아래 diff 리뷰 절)을 더하는 것이다.
|
||||
- 문서 위치·수명·언어 규칙은 `docs/README.md`, 쓰는 절차는 `docs/work/docs-writing.md`다. 살아 있는 문서는 본문까지 한국어로, 「~한다」체로 쓴다.
|
||||
- 기록 문서(`docs/reviews/`, `docs/history/`, `docs/design/`, 결정 기록 `docs/adr/`)는 머리 블록만 고친다. 리뷰 영역 문서를 리뷰 뒤에 고치지 않는다. 예외는 그 라운드를 맡은 총괄이 리뷰 README에 「조치」 절(과 그 아래 diff 리뷰 절)을 더하는 것이다.
|
||||
- 진입 문서(루트 `AGENTS.md`·`CLAUDE.md`, `docs/work/`, `.claude/` 아래 문서) 본문에는 지난 리뷰 ID·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 `docs/work/evidence.md`로 옮긴다. 편집 훅이 `scripts/check-work-docs.py`의 실패 줄을 먼저 알려 준다.
|
||||
- `docs/README.md` 1절이 링크한 문서(루트 `AGENTS.md`, `docs/work/` 포함)는 `verify:documentation`이 백틱 경로·명령 경로·마크다운 링크·package script·FE-GATE ID를 본다. 있는 것만 쓴다. 검사를 피하려고 백틱을 빼지 않는다. 기능 제거 드릴의 문서 사본은 `scripts/lib/removal-fixture.ts`의 목록만 복사하니, 그 목록 밖 루트 파일을 마크다운 링크로 가리키지 않는다.
|
||||
- 살아 있는 문서 전부(루트 `AGENTS.md`, `docs/work/`, `.claude/` 아래 문서 포함)를 `verify:documentation`이 본다: 언어·문체·숫자 복사와 백틱 경로·명령 경로·마크다운 링크·package script·FE-GATE ID. 있는 것만 쓴다. 검사를 피하려고 백틱을 빼지 않는다. 기능 제거 드릴의 문서 사본은 `scripts/lib/removal-fixture.ts`의 목록만 복사하니, 그 목록 밖 루트 파일을 마크다운 링크로 가리키지 않는다.
|
||||
- repo 밖 문서(design-docs 등)는 링크가 아니라 코드 표기로 쓴다.
|
||||
- 숫자(예산, 기준선, 테스트 수)를 옮겨 적지 않는다. 정본을 가리킨다.
|
||||
- 그 문서를 읽는 테스트를 `git grep -n '<파일 이름>' -- tests scripts`로 찾는다. 있으면 desktop에서 돌린다.
|
||||
- 고친 뒤: 작업 매뉴얼이면 `scripts/verify.sh docs`(노트북), 1절 묶음이면 desktop `scripts/verify.sh script verify:documentation`.
|
||||
- 고친 뒤: 작업 매뉴얼이면 `scripts/verify.sh docs`(노트북), 그리고 살아 있는 문서를 바꿨으면 desktop `scripts/verify.sh script verify:documentation`.
|
||||
|
||||
@@ -24,7 +24,7 @@
|
||||
},
|
||||
{
|
||||
"name": "presentation-does-not-know-adapters",
|
||||
"comment": "§4. Presentation talks to application ports, not concrete adapters, the composition root or the TanStack runtime. Exception: src/presentation/adapters/query is the TanStack Query binding, the one place @tanstack is imported (docs/architecture/frontend-ports-adapters-and-boundaries.md). It needs @tanstack only; concrete-adapters-compose-only-in-bootstrap still keeps it off src/adapters. Owner: frontend-platform. Revisit if the binding moves out of presentation.",
|
||||
"comment": "§4. Presentation talks to application ports, not concrete adapters, the composition root or the TanStack runtime. Exception: src/presentation/adapters/query is the TanStack Query binding, the one place @tanstack is imported (docs/design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md). It needs @tanstack only; concrete-adapters-compose-only-in-bootstrap still keeps it off src/adapters. Owner: frontend-platform. Revisit if the binding moves out of presentation.",
|
||||
"severity": "error",
|
||||
"from": {
|
||||
"path": "^src/presentation/(?!adapters/query)"
|
||||
|
||||
+1
-1
@@ -8,7 +8,7 @@
|
||||
# materialized into `dist/config.json` at build time. Only the emergency
|
||||
# switches (CAPABILITY_OVERRIDES, FEATURE_OVERRIDES) may be changed in a
|
||||
# deployed config.json without rebuilding, by the checked procedure in
|
||||
# docs/runbooks/FE-RB-001.md. See the "Runtime configuration" section of
|
||||
# docs/runbooks/FE-RB-001.md. See the 「런타임 설정과 배포 변수」 section of
|
||||
# README.md.
|
||||
#
|
||||
# Copy to `.env.local` (git-ignored) to override locally.
|
||||
|
||||
+17
-2
@@ -1,7 +1,7 @@
|
||||
# 변경 이력
|
||||
|
||||
이 템플릿을 복사해 쓰는 프로젝트가 원본의 수정을 골라 가져갈 때 보는 문서다.
|
||||
가져오는 방법은 `README.md`의 "Updating a copied project" 절에 있다.
|
||||
가져오는 방법은 `README.md`의 「원본 업데이트 반영」 절에 있다.
|
||||
|
||||
- 버전은 git 태그 `vX.Y.Z`로 식별한다. 태그 사이의 변경을 여기 적는다.
|
||||
- 미출시 절은 한 번의 동기화 단위(기준 커밋 → 브랜치 끝)에서 받는 변경의 순 요약이다. 최종 상태만 적고, 같은 범위 안에서 뒤 커밋이 바꾼 중간 상태는 지운다. 호환을 깨는 변경은 절 첫머리 "먼저 할 일"에 옮기기 전·옮기는 법·옮긴 뒤 확인 순서로 적는다.
|
||||
@@ -43,7 +43,7 @@
|
||||
|
||||
## 미출시 — `48c7695b` → 정리 단계
|
||||
|
||||
2026-11-07 소유자가 지시한 저장소 정리다(design-docs `repo-structure/04-frontend-layout.md` 9.2절, 결정은 `repo-structure/README.md` 3.4절). 범위는 `main` `48c7695b`(PR #9 병합) 다음부터다. 1단계(PR #11, `85f941c4`~`121e1125`, `main` `f33e4778`에 합침), 2단계(브랜치 `chore/layout-2-sample-removal`, `c7e80f2f`~`ad3a071f`), 3단계(합치기)와 4단계(배치 규칙 검사)(브랜치 `chore/layout-3-merge`, `bf485f44`~`c54c3813`), CI 재편(브랜치 `chore/ci-merge-jobs`, `0739f26b`부터 브랜치 끝까지)을 담는다. 기준점 `48c7695b`를 빼면 이 절의 해시는 모두 이 범위에 있다.
|
||||
2026-11-07 소유자가 지시한 저장소 정리다(design-docs `repo-structure/04-frontend-layout.md` 9.2절, 결정은 `repo-structure/README.md` 3.4절). 범위는 `main` `48c7695b`(PR #9 병합) 다음부터다. 1단계(PR #11, `85f941c4`~`121e1125`, `main` `f33e4778`에 합침), 2단계(브랜치 `chore/layout-2-sample-removal`, `c7e80f2f`~`ad3a071f`), 3단계(합치기)와 4단계(배치 규칙 검사)(브랜치 `chore/layout-3-merge`, `bf485f44`~`c54c3813`), CI 재편(브랜치 `chore/ci-merge-jobs`, `0739f26b`부터 브랜치 끝까지), 문서 체계 단계(브랜치 `claude/fe-b-docs-korean-645f55`, `99e76e87`부터 브랜치 끝까지. design-docs `conventions/docs-system.md`)를 담는다. 기준점 `48c7695b`를 빼면 이 절의 해시는 모두 이 범위에 있다.
|
||||
|
||||
### 먼저 할 일 (BREAKING)
|
||||
|
||||
@@ -52,6 +52,7 @@
|
||||
#### 옮기기 전
|
||||
|
||||
- 템플릿은 참조 기능(`src/features/reference-feature/`, context `src/contexts/reference-context/`)과 예제 화면(`src/features/platform-examples-feature/`, context `src/contexts/platform-examples-context/`)을 지웠다. 받으면 템플릿 쪽 파일의 삭제가 함께 온다.
|
||||
- 자기 문서가 템플릿 문서의 옛 경로(`docs/superpowers/`, `docs/architecture/decisions/`, `docs/architecture/`의 목표 설계, 루트 `SPEC.md`)를 가리키는지 본다: `git grep -n -E 'docs/superpowers|architecture/decisions|SPEC\.md' -- '*.md' src tests scripts`. 새 위치는 아래 표의 문서 이동 행에 있다.
|
||||
- 자기 프로젝트가 그 폴더를 고쳐 남겨 두었는지 본다: `git log --oneline <마지막 동기화 기준>..HEAD -- src/features/reference-feature tests/features/reference-feature src/features/platform-examples-feature`. 고친 파일은 병합에서 수정/삭제 충돌이 된다.
|
||||
|
||||
#### 옮기는 법
|
||||
@@ -71,6 +72,9 @@
|
||||
13. **CI 계약 기준선 파일이 없어졌다.** `config/ci/contract-baseline.json`, `scripts/update-ci-contract-baseline.ts`, `update:ci-contract-baseline` script를 지웠다(소유자 결정). 위 12단계와 이 절 4단계, 아래 절들의 "기준선을 다시 기록한다"는 이 절까지 받으면 할 일이 없다. 병합에서 자기 기준선 파일이 수정/삭제 충돌이 되면 삭제 쪽을 고른다. 자기 script나 문서가 `update:ci-contract-baseline`을 부르면 지운다 (`f6b2b96c`)
|
||||
14. **merge 단계 job 이름이 바뀌었다.** 게이트마다 하나이던 행렬 job(`FE-GATE-NNN / <이름>`)이 `merge / static checks`(`merge_static`), `merge / tests`(`merge_test`), `merge / browser tests`(`merge_browser`) 셋이 됐다. 게이트는 job 안의 단계 이름(`FE-GATE-NNN / <이름>`)으로 남는다. Gitea 브랜치 보호의 필수 검사를 옛 job 이름으로 걸었으면 새 job 셋으로 바꾼다. 증거 업로드 이름도 `FE-GATE-NNN-<run>`에서 `merge-static-<run>`·`merge-test-<run>`·`merge-browser-<run>`으로 바뀌었다 (`0739f26b`)
|
||||
|
||||
7. **자기 문서를 새 문서 검사에 맞춘다.** `verify:documentation`(FE-GATE-017)이 살아 있는 문서 전부(루트 `README.md`, `docs/` 아래 기록 밖 문서, 모듈 README)를 본다: 본문이 한국어인지, 「~한다」 체인지, 버전·개수를 복사하지 않았는지, 적은 경로·script·게이트 ID가 있는지. 루트 README는 `## 프로젝트 구조`부터 `## 규칙과 기여`까지 정해진 절을 순서대로 가져야 하고, `docs/README.md`는 `docs/` 아래 모든 폴더를 표 첫 칸 `폴더/`로 덮어야 한다. 자기 기록(`docs/design/`, `docs/history/`, `docs/adr/`)은 맨 위에 머리 블록을 단다(형식은 템플릿 `docs/README.md` 3절). 한 번에 다 고칠 수 없으면 걸린 줄을 `scripts/docs-system-exceptions.txt`에 기준선으로 적고 그 지문을 `scripts/lib/docs-system.ts`의 `FROZEN`에 넣는다. 그 목록은 줄기만 한다 (`7a9aefdf`)
|
||||
8. **README의 바뀐 절 이름을 따른다.** 「Files you can delete after copying」은 「복사한 뒤 지워도 되는 것」이다. `verify:documentation`이 이 제목 아래 표의 첫 칸으로 지워도 되는 경로를 읽는다. 자기 README를 템플릿 README로 받았으면 이 제목을 지킨다 (`7a9aefdf`)
|
||||
|
||||
#### 옮긴 뒤 확인
|
||||
|
||||
1. 로컬 merge 게이트 14개를 돈다. 이 절 때문에 먼저 볼 것: `check:registries`(3단계), `check:ci`(4·12단계), `test:unit`(5·9·11단계), `generate:feature-index`(6단계), `check:types`·`check:types:fixtures`(7·8단계), `verify:documentation`(지운 샘플 경로를 적은 자기 문서, 9단계, 매뉴얼 03 E절 R6·R7), `test:sample-removal`(인자 없이 돌면 목록이 빈 템플릿에서는 `SKIP`을 출력한다).
|
||||
@@ -94,6 +98,9 @@
|
||||
| [계약] | 저장소 배치 규칙 R1~R10을 매뉴얼 03 E절에 적고, 기계로 볼 수 있는 것을 게이트에 넣었다: R1·R2·R7(파일)·R9 `tests/unit/repository-layout.test.ts`, R3 `tests/unit/tracked-artifacts.test.ts`, R4·R5 `tests/unit/example-feature-rules.test.ts`(이상 FE-GATE-005), R6·R7(문서) `verify:documentation`(FE-GATE-017, 산출물에 `layoutRuleViolations`), R8 FE-GATE-003 | `docs/manual/03-outside-feature-folder.md`, `scripts/verify-documentation-readiness.ts`, `scripts/contracts/release-artifacts.ts` | `e902e657` |
|
||||
| [계약] **BREAKING** | merge 단계 job 14개(게이트마다 행렬 하나)를 셋으로 합쳤다. job마다 설치를 한 번 하고 게이트를 차례로 돈다. 앞 게이트가 실패해도 다음 게이트가 돈다(`if: ${{ !cancelled() }}`). release 단계는 세 job을 모두 기다린다. 위 "먼저 할 일" 14 | `config/ci/gates.json` `jobs`, `scripts/contracts/ci-gates.ts`, `scripts/generate-ci-workflow.ts`, `.gitea/workflows/quality-gates.yml` | `0739f26b` |
|
||||
| [계약] **BREAKING** | 새 단계 `main`(`MAIN_READY`, 승격을 막지 않음)과 게이트 FE-GATE-029 `checker-self-tests`. FE-GATE-001·005·008·010·013의 `*:fixture` 명령 15개와 그 증거, `check:ci`의 ungated 검사(`check:ci:gating`으로 뗌)를 옮겼다. merge 단계 명령 참조 64 → 49. 음성 타입 fixture(`check:types:fixtures`)는 src 타입 계약 시험이라 merge에 남겼다. CI 계약 기준선 파일은 지웠다. 위 "먼저 할 일" 13 | `config/ci/gates.json`, `scripts/check-ci-gating.ts`, `scripts/lib/promotion-readiness.ts` | `f6b2b96c` |
|
||||
| [계약] **BREAKING** | 문서 체계 검사가 생겼다. `verify:documentation`이 백엔드 `check-docs.py`와 같은 규칙 여섯(language, head, number, map, readme, style)을 `scripts/lib/docs-system.ts`로 돌리고, 참조 검사의 대상이 `docs/README.md` 1절이 링크한 문서에서 살아 있는 문서 전부로 넓어졌다. pull request에서는 FE-GATE-005의 `tests/unit/documentation-readiness.test.ts`가 이 repo로 `verify:documentation`을 돌리므로 문서가 걸리면 merge 단계가 실패한다. 예외 목록(`scripts/docs-system-exceptions.txt`)은 비어 있고 줄기만 한다. 위 "먼저 할 일" 7 | `scripts/lib/docs-system.ts`, `scripts/verify-documentation-readiness.ts`, `scripts/docs-system-exceptions.txt`, `docs/README.md` | `7a9aefdf` |
|
||||
| [계약] | 문서를 수명으로 나눠 옮겼다. 설계서는 `docs/design/`(옛 `docs/superpowers/specs/`와 `docs/architecture/`의 목표 설계 16개는 `<작성일>-<이름>-design.md`로), 계획서는 `docs/history/plans/`(옛 `docs/superpowers/plans/`, 루트 `SPEC.md`는 `docs/history/plans/2026-09-25-review-fix-round/`), 결정 기록 VD는 `docs/adr/`(번호 그대로)다. 기록 67개에 한국어 머리 블록(상태·작성일·요약·현재 정본)을 달았다. 코드 주석의 문서 경로도 고쳤다. 위 "먼저 할 일" 옮기기 전 | `docs/design/`, `docs/history/`, `docs/adr/`, `.dependency-cruiser.json`, `tests/component/router.test.tsx` | `99e76e87`, `e632b230`, `9540bf81`, `75fad73a`, `2b8a348c` |
|
||||
| [계약] | 루트 README를 한국어로 다시 썼다. 절은 프로젝트 구조 → 시작하기 → (런타임 설정과 배포 변수) → 기능 켜고 끄기 → 문서 지도 → 검증 → 새 서비스로 시작하기 → 규칙과 기여다. 옛 「Support scope」는 「기능 켜고 끄기」의 「지원 범위」, 「Updating a copied project」는 「새 서비스로 시작하기」의 「원본 업데이트 반영」, 「CI and evidence」는 「검증」의 「게이트와 CI」다. 위 "먼저 할 일" 8 | `README.md`, `tests/unit/documentation-readiness.test.ts` | `7a9aefdf` |
|
||||
|
||||
### 그 밖의 수정
|
||||
|
||||
@@ -105,6 +112,14 @@
|
||||
- 기능 스위치 시험(`tests/component/product-feature-switch.test.tsx`)과 홈 시작 링크의 스위치 시험은 시험 전용 fixture 기능으로 옮겼다 (`e3c8db48`).
|
||||
- 라우트 런타임 음성 fixture(`tests/fixtures/typecheck/invalid-route-runtime.ts`)는 라우트 하나만 뺀다. 빠진 라우트 수에 따라 TS2739와 TS2740으로 갈리던 진단이 TS2741 하나가 됐고 FE-GATE-003의 기대 진단도 바꿨다. 라우트가 3개로 줄자 옛 기대(TS2740)가 어긋났다 (`e47a0ab2`).
|
||||
|
||||
- 살아 있는 문서를 모두 한국어로 옮겼다(현재 계약, 운영, runbook, 보안, 스타일, 접근성, 테스트, 모듈 README). 뜻은 바꾸지 않았고 백틱 안, 링크 대상, 절 번호, 표 구조는 그대로다. 문서를 읽는 테스트의 기대 문자열(`tests/unit/feature-tracked-files.test.ts`)과 절 이름을 인용한 주석을 같이 고쳤다 (`af10cae9`, `45e8cb77`, `11530b1a`).
|
||||
- `check:remediation-ledger`는 옮긴 원장의 절 제목 `## 세 번째 재검토 (2026-08-14)`을 찾고, 「모두 닫혔다」를 한국어로도 잡는다 (`45e8cb77`).
|
||||
- 하네스 범위가 더한 작업 매뉴얼·규칙(`docs/work/`, `.claude/rules/docs.md`, `docs/problem-statement.md`)의 문서 체계 설명을 새 위치와 검사 범위(살아 있는 문서 전부)에 맞췄다. `docs/work/evidence.md`는 근거 기록이라 참조·숫자 검사에서 뺐다 (`5757742e`).
|
||||
- `verify:documentation`의 경로 검사가 줄임표 「…」를 `...`처럼 자리표시자로 본다(`node scripts/…`). 문서가 제거 드릴 사본에 없는 루트 파일을 링크하지 않게 `docs/README.md`를 고쳤다. 문서 검사를 띄우는 시험에 60초 한도를 줬다 (`743f6fcc`, `5f10f928`, `7b09c215`).
|
||||
- 문서 검사는 라우트별 수동 접근성 기록(`docs/accessibility/route-reviews/`)을 문서로 보지 않는다. 정해진 영어 키 형식의 게이트 입력이다 (`e9e98b8a`).
|
||||
- `SPEC.md`의 공통 완료 기준은 하네스 범위가 `docs/work/improve.md` 5절로 옮겼다. 이 범위가 먼저 만든 사본 `docs/manual/reference/done-criteria.md`는 지웠다(`ee5e19f4`에서 만들고 뒤 커밋에서 지움).
|
||||
- 설정 파일의 설명 칸(recipe 카탈로그, runbook 등록, 규모 상한, 짝 백엔드 pin의 `fact`, secret scan 허용 이유)을 한국어로 옮겼다. 키와 값의 모양은 그대로다 (`309631e4`).
|
||||
|
||||
### 알려진 제한
|
||||
|
||||
- 두 다운스트림에 시험 병합을 하지 않아 충돌 수를 모른다(S4 가정 F4).
|
||||
|
||||
+21
-21
@@ -8,49 +8,49 @@ web
|
||||
|
||||
## Users
|
||||
|
||||
- **템플릿을 가져다 쓰는 개발자**: 이 템플릿으로 새 서비스를 빠르게 시작하는 사람입니다. 기본 화면(홈, 플랫폼 구성)과 Storybook 갤러리(UI 구성요소, 화면 상태)는 이 사람이 실행 구조와 공통 동작을 확인하는 용도입니다.
|
||||
- **파생 서비스의 최종 사용자**: 디자인 시스템(토큰, 프리미티브, 패턴, 레이아웃, 페이지 템플릿)은 이 템플릿으로 만든 서비스를 실제로 쓰는 사람을 기준으로 합니다.
|
||||
- **템플릿을 가져다 쓰는 개발자**: 이 템플릿으로 새 서비스를 빠르게 시작하는 사람이다. 기본 화면(홈, 플랫폼 구성)과 Storybook 갤러리(UI 구성요소, 화면 상태)는 이 사람이 실행 구조와 공통 동작을 확인하는 용도다.
|
||||
- **파생 서비스의 최종 사용자**: 디자인 시스템(토큰, 프리미티브, 패턴, 레이아웃, 페이지 템플릿)은 이 템플릿으로 만든 서비스를 실제로 쓰는 사람을 기준으로 한다.
|
||||
|
||||
## Product Purpose
|
||||
|
||||
도메인·비즈니스·DB 로직을 뺀 공통 기능을 모두 갖춘 React/Vite 프론트엔드 출발점입니다. 아키텍처 경계, 연동 동작, 릴리스 정합성, 접근성, 성능, 운영을 관례가 아니라 실행되는 계약으로 둡니다. 성공 기준은 이 템플릿에서 도메인만 추가해 서비스를 빠르게 만들고, 운영 중인 desktop 서버에 바로 띄워 출시할 수 있는 것입니다.
|
||||
도메인·비즈니스·DB 로직을 뺀 공통 기능을 모두 갖춘 React/Vite 프론트엔드 출발점이다. 아키텍처 경계, 연동 동작, 릴리스 정합성, 접근성, 성능, 운영을 관례가 아니라 실행되는 계약으로 둔다. 성공 기준은 이 템플릿에서 도메인만 추가해 서비스를 빠르게 만들고, 운영 중인 desktop 서버에 바로 띄워 출시할 수 있는 것이다.
|
||||
|
||||
## Positioning
|
||||
|
||||
화면 품질 규칙(접근성, 상태 표현, 반응형, 토큰 사용)이 문서가 아니라 게이트로 강제됩니다. 시각 회귀 골든, 아키텍처 검사, 접근성 테스트가 그 게이트입니다. 그래서 파생 서비스가 템플릿을 고쳐도 기준이 조용히 낮아지지 않습니다.
|
||||
화면 품질 규칙(접근성, 상태 표현, 반응형, 토큰 사용)이 문서가 아니라 게이트로 강제한다. 시각 회귀 골든, 아키텍처 검사, 접근성 테스트가 그 게이트다. 그래서 파생 서비스가 템플릿을 고쳐도 기준이 조용히 낮아지지 않는다.
|
||||
|
||||
## Operating Context
|
||||
|
||||
- 실행 형태는 브라우저 SPA + 정적 호스팅 + Service Worker입니다. SSR은 없습니다.
|
||||
- 파생 서비스는 운영 중인 desktop 서버에 배포됩니다.
|
||||
- 예제 앱 셸에는 테마 전환(시스템/라이트/다크), 언어 전환(한국어/영어), 로그인 상태 표시가 있습니다.
|
||||
- 실행 형태는 브라우저 SPA + 정적 호스팅 + Service Worker다. SSR은 없다.
|
||||
- 파생 서비스는 운영 중인 desktop 서버에 배포된다.
|
||||
- 예제 앱 셸에는 테마 전환(시스템/라이트/다크), 언어 전환(한국어/영어), 로그인 상태 표시가 있다.
|
||||
|
||||
## Capabilities and Constraints
|
||||
|
||||
- 하나의 디자인 시스템으로 세 종류의 서비스를 받칩니다. 업무용·관리 도구(대시보드, 어드민, 설정), 일반 사용자용 웹 서비스, 소개·랜딩 페이지입니다.
|
||||
- 디자인 시스템 위치는 `src/presentation/design-system/`입니다. 토큰은 primitive → semantic → component 세 단계로 파생됩니다(`tokens/primitive.css`, `semantic.css`, `component.css`).
|
||||
- 시각 회귀 골든이 `tests/visual/__snapshots__/`에 있습니다. 화면을 바꾸면 골든도 의도적으로 갱신해야 합니다.
|
||||
- 템플릿에는 샘플 기능이 없습니다(참조 기능과 예제 화면은 2026-11-07에 지웠습니다). 기능은 `create:feature`로 만듭니다. 디자인 시스템 갤러리와 화면 상태 갤러리는 Storybook story(`src/presentation/design-system/galleries.stories.tsx`)이고 시각 회귀 골든의 대상입니다. 플랫폼 구성 화면(`/examples/platform`)과 홈은 기본 구성입니다. 그래서 갤러리와 홈, 플랫폼 구성 화면에 넣은 디자인은 파생 서비스에 남습니다.
|
||||
- 어떤 서비스가 먼저 만들어질지, 서비스별 우선순위는 아직 정하지 않았습니다.
|
||||
- 하나의 디자인 시스템으로 세 종류의 서비스를 받친다. 업무용·관리 도구(대시보드, 어드민, 설정), 일반 사용자용 웹 서비스, 소개·랜딩 페이지다.
|
||||
- 디자인 시스템 위치는 `src/presentation/design-system/`이다. 토큰은 primitive → semantic → component 세 단계로 파생된다(`tokens/primitive.css`, `semantic.css`, `component.css`).
|
||||
- 시각 회귀 골든이 `tests/visual/__snapshots__/`에 있다. 화면을 바꾸면 골든도 의도적으로 갱신해야 한다.
|
||||
- 템플릿에는 샘플 기능이 없다(참조 기능과 예제 화면은 2026-11-07에 지웠다). 기능은 `create:feature`로 만든다. 디자인 시스템 갤러리와 화면 상태 갤러리는 Storybook story(`src/presentation/design-system/galleries.stories.tsx`)이고 시각 회귀 골든의 대상이다. 플랫폼 구성 화면(`/examples/platform`)과 홈은 기본 구성이다. 그래서 갤러리와 홈, 플랫폼 구성 화면에 넣은 디자인은 파생 서비스에 남는다.
|
||||
- 어떤 서비스가 먼저 만들어질지, 서비스별 우선순위는 아직 정하지 않았다.
|
||||
|
||||
## Brand Commitments
|
||||
|
||||
브랜드는 중립으로 유지합니다. 템플릿에는 브랜드 이름·로고·고유 톤을 넣지 않고, 서비스마다 토큰을 바꿔 브랜드를 입힙니다. 현재 표시 이름 "Frontend Skeleton"은 자리표시자입니다.
|
||||
브랜드는 중립으로 유지한다. 템플릿에는 브랜드 이름·로고·고유 톤을 넣지 않고, 서비스마다 토큰을 바꿔 브랜드를 입힌다. 현재 표시 이름 "Frontend Skeleton"은 자리표시자다.
|
||||
|
||||
## Evidence on Hand
|
||||
|
||||
- 실제 고객, 사용 후기, 로고, 지표, 가격 정보는 없습니다. 지어내지 않습니다.
|
||||
- 예제 문구는 템플릿 기능 설명뿐입니다(`src/presentation/i18n/catalog.ts`).
|
||||
- 실제 고객, 사용 후기, 로고, 지표, 가격 정보는 없다. 지어내지 않는다.
|
||||
- 예제 문구는 템플릿 기능 설명뿐이다(`src/presentation/i18n/catalog.ts`).
|
||||
- 현재 화면 기록: `tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/`, Storybook(`src/presentation/design-system/design-system.stories.tsx`).
|
||||
|
||||
## Product Principles
|
||||
|
||||
1. 디자인 시스템은 최종 사용자를 위한 것이고, 예제 화면은 개발자를 위한 것입니다. 둘을 섞지 않습니다.
|
||||
2. 브랜드는 토큰으로만 바꿉니다. 컴포넌트에 브랜드 값을 직접 넣지 않습니다.
|
||||
3. 업무 도구, 일반 서비스, 랜딩을 모두 받쳐야 하므로 밀도와 표현 폭은 토큰과 페이지 템플릿에서 조절합니다. 컴포넌트를 서비스 종류별로 복제하지 않습니다.
|
||||
4. 접근성과 상태 표현(로딩, 빈 상태, 오류, 권한 없음)은 기능이 아니라 기본값입니다.
|
||||
5. 한국어가 기본이고 영어를 함께 지원합니다. 두 언어의 문구 길이 차이를 견디는 레이아웃이어야 합니다.
|
||||
1. 디자인 시스템은 최종 사용자를 위한 것이고, 예제 화면은 개발자를 위한 것이다. 둘을 섞지 않는다.
|
||||
2. 브랜드는 토큰으로만 바꾼다. 컴포넌트에 브랜드 값을 직접 넣지 않는다.
|
||||
3. 업무 도구, 일반 서비스, 랜딩을 모두 받쳐야 하므로 밀도와 표현 폭은 토큰과 페이지 템플릿에서 조절한다. 컴포넌트를 서비스 종류별로 복제하지 않는다.
|
||||
4. 접근성과 상태 표현(로딩, 빈 상태, 오류, 권한 없음)은 기능이 아니라 기본값이다.
|
||||
5. 한국어가 기본이고 영어를 함께 지원한다. 두 언어의 문구 길이 차이를 견디는 레이아웃이어야 한다.
|
||||
|
||||
## Accessibility & Inclusion
|
||||
|
||||
WCAG 2.2 AA를 기준으로 합니다. 키보드 탐색, 포커스 이동과 복원, 색에만 의존하지 않는 상태 표현, 라이트·다크 테마 모두에서 대비를 지킵니다. 릴리스 후보 하나로 라우트를 사람이 직접 접근성 검토하는 절차가 따로 있습니다(`docs/accessibility/manual-checklist.md`).
|
||||
WCAG 2.2 AA를 기준으로 한다. 키보드 탐색, 포커스 이동과 복원, 색에만 의존하지 않는 상태 표현, 라이트·다크 테마 모두에서 대비를 지킨다. 릴리스 후보 하나로 라우트를 사람이 직접 접근성 검토하는 절차가 따로 있다(`docs/accessibility/manual-checklist.md`).
|
||||
|
||||
@@ -1,69 +1,101 @@
|
||||
# Clean Architecture Frontend Template
|
||||
|
||||
A React/Vite reference implementation where architecture boundaries,
|
||||
integration behavior, release coherence, accessibility, performance, and
|
||||
operations are executable contracts rather than conventions.
|
||||
React와 Vite로 만든 프론트엔드 참조 구현(reference implementation)이다. 이 템플릿을 복사한 제품 팀이 도메인 기능을 채워 서비스를 만든다.
|
||||
아키텍처 경계, 연동 동작, 릴리스 정합성, 접근성, 성능, 운영을 관례가 아니라 실행되는 계약(게이트와 테스트)으로 지킨다.
|
||||
|
||||
## Start locally
|
||||
## 프로젝트 구조
|
||||
|
||||
Requirements: the exact Node.js version in `.nvmrc` (currently 24.14.0) and
|
||||
Corepack. The repository pins pnpm in `package.json`.
|
||||
최상위 폴더와 파일:
|
||||
|
||||
Product source, tests, build/quality scripts, and supported tool configuration
|
||||
are TypeScript/TSX. `allowJs` is disabled. Node-side `.ts` scripts run directly
|
||||
on the pinned Node 24 runtime and are checked with NodeNext resolution plus
|
||||
erasable-syntax enforcement. Project-owned executable source contains no
|
||||
JavaScript-family files; negative architecture, security, and type-compatibility
|
||||
fixtures are TypeScript/TSX as well.
|
||||
| 경로 | 하는 일 | 먼저 읽을 곳 |
|
||||
| --- | --- | --- |
|
||||
| `src/` | 앱 코드. 아래 표의 폴더로 나뉜다 | `docs/architecture/layers.md` |
|
||||
| `tests/` | 테스트. 계층별 폴더(`tests/unit/`, `tests/component/`, `tests/integration/`, `tests/e2e/` 등) | `docs/testing/taxonomy.md` |
|
||||
| `scripts/` | 빌드·검사·생성 명령의 TypeScript 스크립트. `package.json`의 script가 부른다 | `package.json` |
|
||||
| `config/` | 게이트 목록(`config/ci/`), 런타임 프로필(`config/runtime/`), recipe 카탈로그(`config/recipes/`), JSON Schema(`config/schemas/`), 보안·성능·규모 기준선, 최상위 항목 등록부(`config/repository-layout.json`) | `docs/operations/ci-quality-gates.md` |
|
||||
| `recipes/` | 선택 기능(recipe)의 원본 코드. 제품이 앱으로 복사해 쓴다. 기본 빌드에 들어가지 않는다 | `docs/architecture/optional-adapter-recipes.md` |
|
||||
| `docs/` | 문서. 지도는 `docs/README.md` | `docs/README.md` |
|
||||
| `artifacts/` | 게이트와 시험의 실행 출력. git은 무시하고 `.gitkeep`만 추적한다 | `docs/operations/ci-quality-gates.md` |
|
||||
| `public/`, `index.html` | 정적 자원과 앱 진입 HTML | `docs/architecture/static-delivery.md` |
|
||||
| `.gitea/` | CI workflow(`.gitea/workflows/quality-gates.yml`, 생성 파일) | `docs/operations/ci-quality-gates.md` |
|
||||
| `.storybook/` | Storybook 설정 | `docs/styling/design-tokens.md` |
|
||||
| `.dependency-cruiser.json` | import 규칙. `check:architecture`가 읽는다 | `docs/architecture/layers.md` |
|
||||
| `AGENTS.md` | 규칙의 정본과 지도: 꼭 지킬 것, 맡은 일마다 읽을 playbook, 검증 진입점 | `AGENTS.md` |
|
||||
| `CLAUDE.md`, `.claude/` | Claude Code용: `CLAUDE.md`는 `AGENTS.md`를 가져오고 Claude Code 전용 줄만 둔다. `.claude/`에 경로별 규칙·스킬·서브에이전트·권한·훅 | `CLAUDE.md` |
|
||||
| `PRODUCT.md` | 디자인 도구가 읽는 제품 맥락 | `PRODUCT.md` |
|
||||
| `CHANGELOG.md` | 템플릿 버전 사이의 변경과 복사한 프로젝트가 할 일 | `CHANGELOG.md` |
|
||||
|
||||
`src/` 폴더 (설명은 `docs/architecture/layers.md` 표와 같다. 그 문서가 import 규칙도 모두 적는다):
|
||||
|
||||
- `src/bootstrap` — 조립 루트: 런타임 설정, 구체 adapter 생성, React 마운트
|
||||
- `src/apps` — 배포 단위 앱: 각 `app-module.ts`가 앱과 그 context 예산을 선언한다. `template-app.ts`가 이 빌드가 만드는 앱이다
|
||||
- `src/contexts` — bounded context: 각 `context-module.ts`가 소속 앱, 라우트 루트, 기능 예산을 선언한다
|
||||
- `src/features` — 지울 수 있는 수직 slice(`src/features/<id>/{domain,application,contracts,adapters,presentation}`)와 설치된 기능 목록(`src/features/*.ts`)
|
||||
- `src/presentation` — 범용 UI와 inbound adapter: 라우트, 레이아웃, 디자인 시스템, 페이지, provider
|
||||
- `src/adapters` — application 포트를 구현하는 재사용 capability 런타임: HTTP, 인증, 저장소, query cache, telemetry, worker 등
|
||||
- `src/application` — 범용 use case, 포트, 정책, view-model
|
||||
- `src/contracts` — 여러 계층·worker·빌드와 릴리스 스크립트가 같이 읽는 공용 어휘와 registry
|
||||
- `src/platform` — 어느 폴더든 쓸 수 있는 제품 중립 기본 요소: 예산, 실행 context, 복원력, telemetry 파이프라인, 오류 envelope, 릴리스 정합성
|
||||
|
||||
의존은 안쪽으로 향한다. 어느 폴더든 `contracts`와 `platform`은 가져와도 된다:
|
||||
|
||||
```text
|
||||
presentation -> application -> contracts -> platform
|
||||
adapters -----^
|
||||
bootstrap composes concrete adapters
|
||||
apps -> contexts -> features (an app deploys contexts; a context owns features)
|
||||
feature use case -> feature port <- feature-owned capability binding
|
||||
```
|
||||
|
||||
- 도메인 코드는 각 기능 안에 있다. 최상위 domain 폴더는 없다.
|
||||
- 기능은 `src/features/<id>` 아래 수직 slice다. 도메인, application 입력, HTTP 연결, 계약, 라우트 런타임, 화면을 그 기능이 소유한다. 중앙 목록은 고른 기능의 기여를 모으기만 한다.
|
||||
- 템플릿은 기능을 하나도 싣지 않는다(참조 샘플과 예제 화면은 2026-11-07에 지웠다). `corepack pnpm create:feature <id>`가 기능을 만든다. 기능이 없어도 범용 스타터 라우트는 타입 검사·테스트·빌드를 통과한다.
|
||||
- 불변식: 규칙은 `.dependency-cruiser.json`이 정하고 `check:architecture`가 모든 import를 풀어 검사한다. 해석되지 않은 import, 파싱 실패, 금지된 계층 간선, 순환 의존은 모두 실패로 닫힌다(fail-closed).
|
||||
|
||||
플랫폼 계층의 역할과 경계는 `docs/architecture/frontend-application-foundation.md`, `docs/architecture/overview.md`, `docs/architecture/starter-experience.md`에 있다.
|
||||
|
||||
## 시작하기
|
||||
|
||||
전제: `.nvmrc`에 적힌 Node.js 버전과 Corepack. pnpm 버전은 `package.json`이 고정한다.
|
||||
|
||||
```bash
|
||||
corepack pnpm install --frozen-lockfile
|
||||
corepack pnpm dev
|
||||
```
|
||||
|
||||
## Runtime configuration
|
||||
- 성공하면 터미널에 Vite가 알려 준 로컬 주소에서 헤더와 사이드바가 있는 앱 셸이 뜬다.
|
||||
- 내리려면 그 터미널에서 Ctrl+C를 누른다.
|
||||
|
||||
Runtime-public settings are validated against one schema before the product
|
||||
tree mounts (`runtimeConfigV2ArtifactSchema` in
|
||||
`src/contracts/release-artifacts.ts`). Client secrets are forbidden.
|
||||
앱 코드, 테스트, 빌드·품질 스크립트, 도구 설정은 모두 TypeScript/TSX다. `allowJs`는 꺼져 있다. Node 쪽 `.ts` 스크립트는 고정한 Node 런타임에서 바로 돈다. NodeNext 해석과 지울 수 있는 문법(erasable syntax)만 쓰는지로 검사한다. 아키텍처·보안·타입 호환의 음성 fixture도 TypeScript/TSX다.
|
||||
|
||||
The source of truth is `config/runtime/<profile>.json`, one file per
|
||||
environment: `local`, `development`, `staging`, `production`. `corepack pnpm
|
||||
build` writes `dist/config.json` from the selected profile
|
||||
(`scripts/generate-runtime-config.ts`). `public/config.json` is only the local
|
||||
profile for `corepack pnpm dev`; the build replaces it, so settings put there
|
||||
never reach a deployment. Keep it equal to `config/runtime/local.json` plus
|
||||
`BUILD_ID: local-build` and `RELEASE_ID: local-release`;
|
||||
`tests/unit/deployment-admission.test.ts` fails when the two differ.
|
||||
## 런타임 설정과 배포 변수
|
||||
|
||||
Build and deploy variables, lowest precedence first:
|
||||
런타임에 공개되는 설정은 제품 트리를 마운트하기 전에 스키마 하나로 검증한다(`src/contracts/release-artifacts.ts`의 `runtimeConfigV2ArtifactSchema`). 클라이언트 비밀값은 금지다.
|
||||
|
||||
| Variable | Sets | Default |
|
||||
정본은 환경마다 하나인 `config/runtime/<profile>.json`이다: `local`, `development`, `staging`, `production`.
|
||||
|
||||
- `corepack pnpm build`는 고른 프로필로 `dist/config.json`을 쓴다(`scripts/generate-runtime-config.ts`).
|
||||
- `public/config.json`은 `corepack pnpm dev`용 로컬 프로필일 뿐이다. 빌드가 덮어쓰므로 거기 넣은 설정은 배포에 닿지 않는다.
|
||||
- `public/config.json`은 `config/runtime/local.json`에 `BUILD_ID: local-build`, `RELEASE_ID: local-release`를 더한 것과 같아야 한다. 다르면 `tests/unit/deployment-admission.test.ts`가 실패한다.
|
||||
|
||||
빌드·배포 변수 (위가 우선순위가 가장 낮다):
|
||||
|
||||
| 변수 | 정하는 것 | 기본값 |
|
||||
| --- | --- | --- |
|
||||
| `APP_PROFILE` | which `config/runtime/<profile>.json` is used | `local`; an empty value fails the build |
|
||||
| `RUNTIME_API_BASE_URL` | `API_BASE_URL`, overriding the profile; the CI workflow cannot pass it (see below) | the profile value |
|
||||
| `RUNTIME_TELEMETRY_ENDPOINT` | `TELEMETRY_ENDPOINT`, overriding the profile; the CI workflow cannot pass it (see below) | the profile value |
|
||||
| `VITE_BUILD_ID` | `BUILD_ID` in the runtime config and the release manifest | `local-build` for `local` and `development`; a `staging` or `production` build fails without it |
|
||||
| `RELEASE_ID` | `RELEASE_ID` in the runtime config and the release manifest | `local-release` |
|
||||
| `RELEASE_TARGET` | the environment FE-GATE-027 admits the build to; must equal `APP_PROFILE` | none; admission refuses without it |
|
||||
| `APP_PROFILE` | 어느 `config/runtime/<profile>.json`을 쓰나 | `local`. 빈 값이면 빌드가 실패한다 |
|
||||
| `RUNTIME_API_BASE_URL` | 프로필을 덮어쓰는 `API_BASE_URL`. CI workflow는 넘길 수 없다(아래) | 프로필 값 |
|
||||
| `RUNTIME_TELEMETRY_ENDPOINT` | 프로필을 덮어쓰는 `TELEMETRY_ENDPOINT`. CI workflow는 넘길 수 없다(아래) | 프로필 값 |
|
||||
| `VITE_BUILD_ID` | 런타임 설정과 릴리스 manifest의 `BUILD_ID` | `local`·`development`는 `local-build`. `staging`·`production` 빌드는 없으면 실패한다 |
|
||||
| `RELEASE_ID` | 런타임 설정과 릴리스 manifest의 `RELEASE_ID` | `local-release` |
|
||||
| `RELEASE_TARGET` | FE-GATE-027이 빌드를 받아들일 환경. `APP_PROFILE`과 같아야 한다 | 없음. 없으면 승인(admission)이 거절한다 |
|
||||
|
||||
`verify:documentation` fails if this table stops naming a variable the build or
|
||||
admission reads (`scripts/verify-documentation-readiness.ts`).
|
||||
빌드나 승인이 읽는 변수를 이 표가 빠뜨리면 `verify:documentation`이 실패한다(`scripts/verify-documentation-readiness.ts`).
|
||||
|
||||
Only the two `RUNTIME_*` values can differ from the reviewed profile. Anything
|
||||
else changes by editing the profile file. Staging and production reject demo
|
||||
auth, non-HTTPS endpoints and the names reserved for examples and tests
|
||||
(`example.com`, `example.net`, `example.org` and their subdomains, `.example`,
|
||||
`.invalid`, `.test`). The shipped `staging` and `production` profiles use
|
||||
`*.example.com`, so admission refuses them until a project sets its own
|
||||
endpoints.
|
||||
- 검토한 프로필과 달라질 수 있는 값은 두 `RUNTIME_*`뿐이다. 나머지는 프로필 파일을 고쳐서 바꾼다.
|
||||
- staging과 production은 demo 인증, HTTPS가 아닌 endpoint, 예시·시험용으로 예약된 이름(`example.com`, `example.net`, `example.org`와 그 하위 도메인, `.example`, `.invalid`, `.test`)을 거절한다. 템플릿의 `staging`·`production` 프로필은 `*.example.com`을 쓰므로 프로젝트가 자기 endpoint를 넣기 전까지 승인이 거절한다.
|
||||
- CI에서 endpoint를 정하는 길은 `config/runtime/<profile>.json`에 커밋하는 것뿐이다. CI 계약은 build job에 `APP_PROFILE`과 `RELEASE_TARGET`만 넘긴다(`scripts/contracts/ci-gates.ts`). 그래서 `RUNTIME_*` repository 변수는 빌드에 닿지 않는다.
|
||||
|
||||
In CI the only way to set the endpoints is to commit them to
|
||||
`config/runtime/<profile>.json`. The CI contract binds just `APP_PROFILE` and
|
||||
`RELEASE_TARGET` to the build job (`scripts/contracts/ci-gates.ts`), so a
|
||||
`RUNTIME_*` repository variable never reaches the build.
|
||||
|
||||
A local production build and its admission check:
|
||||
로컬 production 빌드와 그 승인 검사:
|
||||
|
||||
```bash
|
||||
APP_PROFILE=production \
|
||||
@@ -74,321 +106,159 @@ corepack pnpm build
|
||||
APP_PROFILE=production RELEASE_TARGET=production corepack pnpm check:release-admission
|
||||
```
|
||||
|
||||
With `CI=true` the gate runner (`corepack pnpm ci:gate`) also requires
|
||||
`VITE_COMMIT_SHA`, `SOURCE_DATE_EPOCH` and `CI_RUNNER_IMAGE` before it runs a
|
||||
gate (`scripts/lib/build-environment.ts`, `scripts/run-ci-gate.ts`). The CI variable
|
||||
list is in [`docs/operations/ci-quality-gates.md`](docs/operations/ci-quality-gates.md).
|
||||
`CI=true`이면 게이트 실행기(`corepack pnpm ci:gate`)가 게이트를 돌리기 전에 `VITE_COMMIT_SHA`, `SOURCE_DATE_EPOCH`, `CI_RUNNER_IMAGE`도 요구한다(`scripts/lib/build-environment.ts`, `scripts/run-ci-gate.ts`). CI 변수 목록은 [`docs/operations/ci-quality-gates.md`](docs/operations/ci-quality-gates.md)에 있다.
|
||||
|
||||
## Included starter experience
|
||||
## 기능 켜고 끄기
|
||||
|
||||
The default build mounts a domain-neutral application shell with a header,
|
||||
responsive sidebar, route focus management, session integration status, a
|
||||
persistent `system` / `light` / `dark` theme selector, and a language selector.
|
||||
- **제품 기능**은 `corepack pnpm create:feature <id>`로 만들고 지운다. 절차는 [`docs/manual/`](docs/manual/README.md)에 있다. 기능 폴더만 지우면 테스트·정책 항목·CI 스크립트가 남아 게이트가 실패한다. 지우는 법은 아래 「새 서비스로 시작하기」에 있다.
|
||||
- **선택 capability**(recipe)는 기본 빌드에 없다. 프로젝트가 `config/recipes/frontend-capability-recipes.json`의 recipe 하나를 복사하고 좁혀서 넣는다. 원칙과 절차는 [`docs/architecture/optional-adapter-recipes.md`](docs/architecture/optional-adapter-recipes.md)에 있다.
|
||||
- **인증**: `AUTH_MODE=demo`는 자격 증명이 없고 local·development에서만 받는다. 배포는 `AUTH_MODE=external`을 쓰고 [`docs/architecture/starter-experience.md`](docs/architecture/starter-experience.md)가 설명하는 불투명 인증 owner를 준다. 클라이언트 라우트 정책은 사용자 경험일 뿐이다. 권한의 정본은 서버다.
|
||||
|
||||
The route list is `ROUTE_REGISTRY` (`src/features/installed-feature-contracts.ts`):
|
||||
the platform routes of `src/contracts/routes.ts` plus the routes of every
|
||||
installed feature. The template installs none: `corepack pnpm create:feature`
|
||||
adds one (`docs/manual/`). The platform overview page (`/examples/platform`) shows the composed list at runtime, so
|
||||
this README keeps no copy of it and adding a feature does not edit it.
|
||||
### 기본 화면
|
||||
|
||||
`AUTH_MODE=demo` is credential-free and accepted only in local/development
|
||||
environments. Deployments use `AUTH_MODE=external` and provide the opaque auth
|
||||
owner described in
|
||||
[`docs/architecture/starter-experience.md`](docs/architecture/starter-experience.md).
|
||||
The client route policy is user experience only; server authorization remains
|
||||
authoritative.
|
||||
기본 빌드는 도메인 중립 앱 셸을 마운트한다. 헤더, 반응형 사이드바, 라우트 포커스 관리, 세션 연동 상태, 저장되는 `system` / `light` / `dark` 테마 선택, 언어 선택이 있다.
|
||||
|
||||
## Support scope
|
||||
라우트 목록은 `ROUTE_REGISTRY`(`src/features/installed-feature-contracts.ts`)다. `src/contracts/routes.ts`의 플랫폼 라우트와 설치된 모든 기능의 라우트를 합친다. 템플릿은 기능을 설치하지 않는다. 플랫폼 개요 화면(`/examples/platform`)이 런타임에 합친 목록을 보여 준다. 그래서 이 README는 목록 사본을 두지 않고, 기능을 더해도 고치지 않는다.
|
||||
|
||||
Four tiers. The status words on the right are the ones the catalogs and
|
||||
design documents use; the next table maps them.
|
||||
### 지원 범위
|
||||
|
||||
| Tier | What it covers | Status words |
|
||||
네 단계다. 오른쪽 상태 값은 카탈로그와 설계 문서가 쓰는 말이다. 뜻은 다음 표에 있다.
|
||||
|
||||
| 단계 | 무엇이 들어가나 | 상태 값 |
|
||||
| --- | --- | --- |
|
||||
| Default | In the default build and covered by the merge gates: the application shell and example routes, the REST HTTP executor, TanStack Query server state, Local/Session Storage registries, cross-tab invalidation, runtime config profiles and the release manifest check, `AUTH_MODE=external` (`demo` only in local/development), the typed message catalog, and `create:feature`, which writes a feature that passes the merge gates. `dist/` is served by a static host ([`docs/architecture/static-delivery.md`](docs/architecture/static-delivery.md)) | `COMPOSED` |
|
||||
| Optional (recipe) | Not installed. A project copies one of the recipes in `config/recipes/frontend-capability-recipes.json` and narrows it ([`docs/architecture/optional-adapter-recipes.md`](docs/architecture/optional-adapter-recipes.md)). `realtime`, `offline-indexeddb`, `service-worker-pwa` and `file-transfer` also ship a tested reference runtime that the default build leaves out | `RECIPE_AVAILABLE`, `NOT_INSTALLED`, `AVAILABLE_NOT_COMPOSED` |
|
||||
| Experimental | Designed and decided, but the runtime is missing or unfinished; finish it before building on it. GraphQL, gRPC-Web, Connect-Web and Protobuf adapters, Range resumable download, IndexedDB query persistence, the local preview decode-safety probe | `DESIGNED_NOT_IMPLEMENTED` |
|
||||
| Not supported | Deliberately not selected, or browsers cannot guarantee it: SSR, app-managed background upload and download, directory selection, persistent file handles, product query persistence, exactly-once delivery between tabs | `NOT_SELECTED`, `PLATFORM_LIMITED` |
|
||||
| 기본 | 기본 빌드에 들어가고 merge 게이트가 덮는다: 앱 셸과 예제 라우트, REST HTTP 실행기, TanStack Query 서버 상태, Local/Session Storage registry, 탭 간 무효화, 런타임 설정 프로필과 릴리스 manifest 검사, `AUTH_MODE=external`(`demo`는 local·development만), 타입이 있는 문구 카탈로그, merge 게이트를 통과하는 기능을 만드는 `create:feature`. `dist/`는 정적 호스트가 서빙한다([`docs/architecture/static-delivery.md`](docs/architecture/static-delivery.md)) | `COMPOSED` |
|
||||
| 선택(recipe) | 설치되지 않는다. 프로젝트가 `config/recipes/frontend-capability-recipes.json`의 recipe를 복사하고 좁힌다([`docs/architecture/optional-adapter-recipes.md`](docs/architecture/optional-adapter-recipes.md)). `realtime`, `offline-indexeddb`, `service-worker-pwa`, `file-transfer`는 시험한 참조 런타임도 싣지만 기본 빌드는 뺀다 | `RECIPE_AVAILABLE`, `NOT_INSTALLED`, `AVAILABLE_NOT_COMPOSED` |
|
||||
| 실험 | 설계와 결정은 했지만 런타임이 없거나 덜 됐다. 그 위에 짓기 전에 마저 만든다. GraphQL, gRPC-Web, Connect-Web, Protobuf adapter, Range 이어받기 다운로드, IndexedDB query 영속화, 로컬 미리보기 디코드 안전 탐침 | `DESIGNED_NOT_IMPLEMENTED` |
|
||||
| 지원 안 함 | 일부러 고르지 않았거나 브라우저가 보장하지 못한다: SSR, 앱이 관리하는 백그라운드 업로드·다운로드, 디렉터리 선택, 영속 파일 핸들, 제품 query 영속화, 탭 사이의 정확히 한 번 전달 | `NOT_SELECTED`, `PLATFORM_LIMITED` |
|
||||
|
||||
The rows come from
|
||||
[`docs/architecture/browser-data-capability-completion-ledger.md`](docs/architecture/browser-data-capability-completion-ledger.md),
|
||||
[`docs/architecture/client-cache-and-storage.md`](docs/architecture/client-cache-and-storage.md)
|
||||
and
|
||||
[`docs/architecture/api-contract-schema-mapper-and-server-state.md`](docs/architecture/api-contract-schema-mapper-and-server-state.md).
|
||||
행의 출처는 설계서 [`docs/design/2026-07-30-browser-data-capability-completion-ledger-design.md`](docs/design/2026-07-30-browser-data-capability-completion-ledger-design.md), [`docs/design/2026-07-28-client-cache-and-storage-design.md`](docs/design/2026-07-28-client-cache-and-storage-design.md), [`docs/design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md`](docs/design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md)다.
|
||||
|
||||
| Status word | Where it appears | Meaning | Tier |
|
||||
| 상태 값 | 나오는 곳 | 뜻 | 단계 |
|
||||
| --- | --- | --- | --- |
|
||||
| `COMPOSED` | capability ledger, design documents | wired into the default production path | Default |
|
||||
| `INSTALLED` | a project's own recipe catalog (step 10 of the recipe procedure) | the project added the recipe | Default, for that project |
|
||||
| `RECIPE_AVAILABLE` | recipe catalog `status` | a recipe exists to copy; nothing is installed | Optional |
|
||||
| `NOT_INSTALLED` | recipe catalog `defaultStatus`; a declared feature the build or `FEATURE_OVERRIDES` left out | not part of the build | Optional (recipe) or Experimental (feature) |
|
||||
| `AVAILABLE_NOT_COMPOSED` | capability ledger; recipe `referenceRuntime.status` | code and tests exist; the default build leaves it out | Optional |
|
||||
| `DESIGNED_NOT_IMPLEMENTED` | capability ledger, design documents | design approved, runtime missing | Experimental |
|
||||
| `NOT_SELECTED` | capability ledger, design documents | deliberately not chosen | Not supported |
|
||||
| `PLATFORM_LIMITED` | capability ledger | browsers cannot guarantee it; offered only behind a probe and a fallback, if at all | Not supported as a guarantee |
|
||||
| `COMPOSED` | capability 원장, 설계 문서 | 기본 production 경로에 조립됐다 | 기본 |
|
||||
| `INSTALLED` | 프로젝트 자신의 recipe 카탈로그(recipe 절차 10단계) | 프로젝트가 recipe를 더했다 | 그 프로젝트에서 기본 |
|
||||
| `RECIPE_AVAILABLE` | recipe 카탈로그 `status` | 복사할 recipe가 있다. 설치된 것은 없다 | 선택 |
|
||||
| `NOT_INSTALLED` | recipe 카탈로그 `defaultStatus`. 빌드나 `FEATURE_OVERRIDES`가 뺀 선언된 기능 | 빌드에 없다 | 선택(recipe) 또는 실험(기능) |
|
||||
| `AVAILABLE_NOT_COMPOSED` | capability 원장, recipe `referenceRuntime.status` | 코드와 테스트가 있지만 기본 빌드가 뺀다 | 선택 |
|
||||
| `DESIGNED_NOT_IMPLEMENTED` | capability 원장, 설계 문서 | 설계는 승인됐고 런타임이 없다 | 실험 |
|
||||
| `NOT_SELECTED` | capability 원장, 설계 문서 | 일부러 고르지 않았다 | 지원 안 함 |
|
||||
| `PLATFORM_LIMITED` | capability 원장 | 브라우저가 보장하지 못한다. 준다면 탐침과 대체 경로 뒤에서만 준다 | 보장으로는 지원 안 함 |
|
||||
|
||||
Gate results (`PASS`, `PASS_SCOPED`, `UNVERIFIED`, `FAIL_UNVERIFIED`) are
|
||||
verdicts on evidence, not support tiers.
|
||||
게이트 결과(`PASS`, `PASS_SCOPED`, `UNVERIFIED`, `FAIL_UNVERIFIED`)는 증거에 대한 판정이지 지원 단계가 아니다.
|
||||
|
||||
Browsers: the build targets Chrome and Edge 111, Firefox 128, and Safari and
|
||||
iOS 16.4. That is the higher of Vite 8's default JavaScript target
|
||||
(`baseline-widely-available`; `vite.config.ts` sets no `build.target`) and
|
||||
the CSS targets of Tailwind CSS 4. There is no browserslist. The end-to-end
|
||||
suite runs on the desktop Chromium, Firefox and WebKit builds that Playwright
|
||||
1.62 pins, plus one Chromium phone-size smoke (`playwright.config.ts`). Older
|
||||
versions inside the target range and real mobile browsers are not tested.
|
||||
브라우저: 빌드 대상은 Chrome·Edge 111, Firefox 128, Safari·iOS 16.4다.
|
||||
|
||||
## Architecture
|
||||
- Vite 기본 JavaScript 대상(`baseline-widely-available`. `vite.config.ts`는 `build.target`을 정하지 않는다)과 Tailwind CSS의 CSS 대상 중 높은 쪽이다. browserslist는 없다.
|
||||
- end-to-end 시험은 Playwright가 고정한(`package.json`의 `@playwright/test`) 데스크톱 Chromium·Firefox·WebKit과, Chromium 휴대폰 크기 smoke 하나로 돈다(`playwright.config.ts`).
|
||||
- 대상 범위 안의 더 오래된 버전과 실제 모바일 브라우저는 시험하지 않는다.
|
||||
|
||||
This repository is a **Frontend Application Foundation**: a starter/composition
|
||||
skeleton plus a reusable capability platform. Platform capabilities stay
|
||||
horizontal while product business features use vertical slices.
|
||||
## 문서 지도
|
||||
|
||||
`src/` has nine top-level folders. The descriptions match the table in
|
||||
`docs/architecture/layers.md`, which also names every import rule:
|
||||
모든 문서 폴더의 지도는 [`docs/README.md`](docs/README.md)다. 거기에 문서의 수명(살아 있는 문서·결정 기록·기록)과 언어 규칙, 기록 문서의 머리 블록 형식도 있다.
|
||||
|
||||
- `src/bootstrap` — the composition root: runtime configuration, concrete adapter construction and the React mount
|
||||
- `src/apps` — deployable apps: each `app-module.ts` declares an app and its context budget; `template-app.ts` is the app this build produces
|
||||
- `src/contexts` — bounded contexts: each `context-module.ts` declares its app, route root and feature budget
|
||||
- `src/features` — removable vertical slices (`src/features/<id>/{domain,application,contracts,adapters,presentation}`) and the installed-feature catalogs (`src/features/*.ts`)
|
||||
- `src/presentation` — generic UI and the inbound adapter: routes, layouts, the design system, pages and providers
|
||||
- `src/adapters` — reusable capability runtimes that implement application ports: HTTP, auth, storage, query cache, telemetry, workers and more
|
||||
- `src/application` — generic use cases, ports, policies and view-models
|
||||
- `src/contracts` — shared vocabulary and registries read by several layers, the workers and the build and release scripts
|
||||
- `src/platform` — product-neutral primitives any folder may use: budgets, execution context, resilience, the telemetry pipeline, error envelopes and release coherence
|
||||
|
||||
Dependencies point inward. Every folder may also import `contracts` and
|
||||
`platform`:
|
||||
|
||||
```text
|
||||
presentation -> application -> contracts -> platform
|
||||
adapters -----^
|
||||
bootstrap composes concrete adapters
|
||||
apps -> contexts -> features (an app deploys contexts; a context owns features)
|
||||
feature use case -> feature port <- feature-owned capability binding
|
||||
```
|
||||
|
||||
Domain code lives inside each feature; there is no top-level domain folder.
|
||||
|
||||
See
|
||||
`docs/architecture/frontend-application-foundation.md`,
|
||||
`docs/architecture/overview.md`, `docs/architecture/layers.md`, and
|
||||
`docs/architecture/starter-experience.md`. A feature is a vertical slice under
|
||||
`src/features/<id>`; its domain, application input, HTTP binding, contracts,
|
||||
route runtime, and presentation own their contributions. The central installed
|
||||
catalogs only aggregate selected contributions. The template ships no feature
|
||||
(its reference sample and example screens were deleted on 2026-11-07):
|
||||
`corepack pnpm create:feature <id>` writes one, and the generic starter routes
|
||||
typecheck, test, and build without any.
|
||||
|
||||
### Platform capability review
|
||||
|
||||
The starter shell is implemented, but the repository review also records the
|
||||
remaining work required before feature teams can use every declared contract
|
||||
through one end-to-end application path:
|
||||
|
||||
- [platform capability review](docs/architecture/frontend-platform-capability-review.md)
|
||||
- [ports, adapters, and feature boundaries](docs/architecture/frontend-ports-adapters-and-boundaries.md)
|
||||
- [REST, GraphQL, Connect/gRPC-Web, Schema, Mapper, and Server State](docs/architecture/api-contract-schema-mapper-and-server-state.md)
|
||||
- [Protobuf browser transports and REST Gateway](docs/architecture/protobuf-browser-transport-and-rest-gateway.md)
|
||||
- [backend API and Server State handoff contract](docs/architecture/backend-api-and-server-state-contract.md)
|
||||
- [TypeScript, state ownership, and data flow](docs/architecture/typescript-state-and-data-flow.md)
|
||||
- [routing, page templates, and reusable patterns](docs/architecture/routing-pages-and-patterns.md)
|
||||
- [browser data capability completion ledger](docs/architecture/browser-data-capability-completion-ledger.md)
|
||||
- [browser file and origin-storage platform](docs/architecture/browser-file-and-origin-storage.md)
|
||||
- [client cache and storage](docs/architecture/client-cache-and-storage.md)
|
||||
- [realtime events, Web Push, and bounded polling](docs/architecture/realtime-events-web-push-and-bounded-polling.md)
|
||||
- [presigned transfer, resumable upload, streaming download, and Image CDN](docs/architecture/presigned-transfer-and-image-cdn.md)
|
||||
- [server file capability infrastructure](docs/architecture/server-file-capability-infrastructure.md)
|
||||
- [design-system platform](docs/styling/design-system-platform.md)
|
||||
- [frontend platform testing strategy](docs/testing/frontend-platform-testing-strategy.md)
|
||||
- [implementation roadmap](docs/architecture/frontend-platform-implementation-roadmap.md)
|
||||
|
||||
These documents distinguish repository defaults from opt-in adapters and
|
||||
project-owned integrations. They are target designs and review findings; a
|
||||
capability is not treated as implemented until its branch acceptance criteria
|
||||
and executable gates pass.
|
||||
|
||||
## Documentation
|
||||
|
||||
[`docs/README.md`](docs/README.md) sorts the documents into current contracts,
|
||||
target designs and work history.
|
||||
[`docs/manual/`](docs/manual/README.md) is the step-by-step guide (Korean) for
|
||||
adding a feature, starting from `corepack pnpm create:feature <id>`.
|
||||
[`AGENTS.md`](AGENTS.md) is the rule book and map that people and coding agents
|
||||
start from, and [`docs/work/`](docs/work/README.md) is the work manual: one
|
||||
playbook per kind of task (Korean). Both are part of the template a copy keeps.
|
||||
|
||||
### Files you can delete after copying
|
||||
|
||||
These record how the template was built. Nothing in the build or the gates
|
||||
reads them, except the one file noted below
|
||||
(`tests/unit/deletable-history-documents.test.ts` checks this).
|
||||
|
||||
| Path | Contents |
|
||||
| 무엇 | 어디 |
|
||||
| --- | --- |
|
||||
| `docs/superpowers/` | past plans and specs |
|
||||
| `docs/reviews/` | reviews and the review guide. Keep `docs/reviews/adapters/`: `check:adapter-inventory` (FE-GATE-010) reads its `INVENTORY.md`, whose rows link to the adapter reviews beside it, and `docs/operations/adapter-remediation-ledger.md` cites those reviews |
|
||||
| `SPEC.md`, `docs/history/` | requirements of the 2026-09-25 review fix round (`SPEC.md`), and the plans and evidence of finished work, that round's task list included |
|
||||
| `docs/ledger/estimates.jsonl` | the template's own task estimates and measurements; empty it and add your project's lines (`docs/ledger/README.md`) |
|
||||
| `PRODUCT.md` | product context of the template itself (users, purpose, principles) for design tools; replace it with your product's |
|
||||
| 규칙과 지도(사람과 코딩 에이전트가 먼저 읽는다) | [`AGENTS.md`](AGENTS.md), `src/` 계층 폴더마다의 `AGENTS.md` |
|
||||
| 작업 매뉴얼: 새 기능, 리뷰·수정, 조사·설계, 문서, 운영, 일 나누기의 playbook과 기준. 완료 기준은 `docs/work/improve.md` 5절 | [`docs/work/`](docs/work/README.md) |
|
||||
| 개발 매뉴얼: 새 기능을 더하는 순서와 판단 기준, `create:feature` | [`docs/manual/`](docs/manual/README.md) |
|
||||
| 비전과 문제 정의(소유자가 채우는 양식), 작업 예측·실측 장부 | [`docs/vision.md`](docs/vision.md), [`docs/problem-statement.md`](docs/problem-statement.md), [`docs/ledger/`](docs/ledger/README.md) |
|
||||
| 현재 계약: 계층과 import 규칙, 스타터, recipe, 정적 배포, 규모 설계, 짝 백엔드 계약 | [`docs/architecture/`](docs/architecture/), [`docs/contracts/`](docs/contracts/), [`docs/security/`](docs/security/), [`docs/styling/`](docs/styling/), [`docs/accessibility/`](docs/accessibility/), [`docs/testing/`](docs/testing/) |
|
||||
| 운영과 복구: 게이트, 복구 절차, 성능 증거, 오류 code별 runbook | [`docs/operations/`](docs/operations/), [`docs/runbooks/`](docs/runbooks/) |
|
||||
| 결정 기록(VD) | [`docs/adr/`](docs/adr/) |
|
||||
| 설계서(쓴 때의 목표 설계) | [`docs/design/`](docs/design/) |
|
||||
| 기록: 계획서·증거, 리뷰 | [`docs/history/`](docs/history/), [`docs/reviews/`](docs/reviews/) |
|
||||
| 버전별 변경 | [`CHANGELOG.md`](CHANGELOG.md) |
|
||||
|
||||
A feature is not in this list: deleting its directory alone leaves tests,
|
||||
policy entries and CI scripts behind that fail the gates.
|
||||
`corepack pnpm test:sample-removal -- --feature=<id>` removes it from a copy of
|
||||
the repository and lists everything that has to go with it (the header comment
|
||||
of `scripts/test-sample-removal.ts`); do the same in your project and run the
|
||||
gates. A sample your project keeps for a while can be listed in
|
||||
`scripts/lib/removable-template-features.ts`: the drill then removes it without
|
||||
`--feature`, and the documentation check accepts its paths once its
|
||||
`feature-module.ts` is gone.
|
||||
설계서와 기록은 쓴 때의 글이다. 지금 동작은 각 문서 맨 위 머리 블록의 「현재 정본」을 읽는다.
|
||||
|
||||
## Verification
|
||||
## 검증
|
||||
|
||||
Common local checks:
|
||||
일상 명령:
|
||||
|
||||
```bash
|
||||
corepack pnpm lint
|
||||
corepack pnpm check:types
|
||||
corepack pnpm check:types:app
|
||||
corepack pnpm check:types:node
|
||||
corepack pnpm check:types:test
|
||||
corepack pnpm check:architecture
|
||||
corepack pnpm test:all
|
||||
corepack pnpm test:contract
|
||||
corepack pnpm test:e2e
|
||||
corepack pnpm test:a11y
|
||||
corepack pnpm build
|
||||
corepack pnpm check:bundle
|
||||
corepack pnpm test:performance
|
||||
corepack pnpm verify:compatibility
|
||||
corepack pnpm verify:release
|
||||
corepack pnpm check:registries
|
||||
corepack pnpm drill:runbooks
|
||||
corepack pnpm check:ci
|
||||
```
|
||||
|
||||
`drill:runbooks` stops at the first drill that is not `PASS`. Without provider
|
||||
evidence every drill ends `UNVERIFIED` (exit 3), because a drill never reports
|
||||
a check it could not run locally as `PASS`; see "Runbook jobs" in
|
||||
[`docs/operations/ci-quality-gates.md`](docs/operations/ci-quality-gates.md).
|
||||
- `check:types`는 앱 코드, Node 스크립트·설정, 테스트를 따로 나눈 TypeScript project로 모두 검사한다(`check:types:app`, `check:types:node`, `check:types:test`). 타입·아키텍처·보안·registry의 잘못된 fixture는 `config/ci/gates.json`에서 "실패해야 통과"하는 음성 게이트로 돈다. 도구 호환 결정은 [VD-01](docs/adr/VD-01-typescript-lint-tooling.md)에 있다.
|
||||
- `test:all`은 평소 제품 개발 루프이고 호스트 수준의 CI runner 검증은 일부러 뺀다. `corepack pnpm test:system`은 [`docs/testing/taxonomy.md`](docs/testing/taxonomy.md)가 말하는 호환 Linux 검증 호스트에서만 돌린다.
|
||||
- 브라우저 시험 전에 고정한 Playwright 브라우저 엔진을 설치한다: `corepack pnpm exec playwright install --with-deps chromium firefox webkit`.
|
||||
- 그 밖의 검사(`test:contract`, `test:e2e`, `test:a11y`, `check:bundle`, `test:performance`, `verify:compatibility`, `verify:release`, `check:registries`, `drill:runbooks`, `check:ci`)는 `package.json`과 [`docs/operations/ci-quality-gates.md`](docs/operations/ci-quality-gates.md)에 있다. `drill:runbooks`는 `PASS`가 아닌 첫 드릴에서 멈춘다. provider 증거가 없으면 모든 드릴이 `UNVERIFIED`(exit 3)로 끝난다. 로컬에서 돌리지 못한 검사를 `PASS`로 적지 않기 때문이다.
|
||||
|
||||
`test:all` is the ordinary product-development loop and intentionally excludes
|
||||
host-level CI-runner assurance. Run `corepack pnpm test:system` only on the
|
||||
compatible Linux assurance host described in
|
||||
[`docs/testing/taxonomy.md`](docs/testing/taxonomy.md).
|
||||
### 게이트와 CI
|
||||
|
||||
`check:types`는 source, Node scripts/config와 tests를 분리된 TypeScript
|
||||
project로 모두 검사한다. type/architecture/security/registry의 invalid
|
||||
fixture는 `config/ci/gates.json`에서 “실패해야 통과”하는 negative gate로
|
||||
실행된다. 도구 호환성 결정은
|
||||
[VD-01](docs/architecture/decisions/VD-01-typescript-lint-tooling.md)에 기록돼
|
||||
있다.
|
||||
|
||||
Application feature input은 module augmentation으로 닫힌 ID와 정확한 input
|
||||
shape를 제공하며, 공통 `Result<Value, Failure = AppFailure>`는 error registry의
|
||||
failure kind만 application/presentation 경계를 통과시킨다. Architecture gate는
|
||||
TypeScript/TSX의 static, dynamic, type import를 별도 정적 그래프로 분석하고
|
||||
runtime/source 영역의 JavaScript 재유입도 거절한다. 해석되지 않은 import,
|
||||
parse failure, 금지 계층 edge와 순환 의존은 모두 fail-closed이며 전용
|
||||
TypeScript/TSX negative fixture로도 검증된다.
|
||||
|
||||
Install the pinned Playwright browser engines before the first cross-browser
|
||||
run:
|
||||
|
||||
```bash
|
||||
corepack pnpm exec playwright install --with-deps chromium firefox webkit
|
||||
```
|
||||
|
||||
Two gates intentionally need external evidence:
|
||||
|
||||
- `review:a11y-manual` (release gate FE-GATE-028) needs a signed human
|
||||
keyboard/focus/screen-reader review of every registered route, one record
|
||||
per route at `docs/accessibility/route-reviews/<ROUTE_ID>.md`. The routes are
|
||||
`ROUTE_REGISTRY`; `verify:documentation` fails, naming the route ID, when a
|
||||
registered route has no record. The merge gate FE-GATE-009 runs only
|
||||
`review:a11y-manual -- --format-only`, which checks that every route record
|
||||
keeps the template's fields, reviewed or still pending.
|
||||
- `collect:web-vitals-evidence` stays `FAIL_UNVERIFIED` until a reviewed minimum
|
||||
eligible-sample threshold and 28 days of production data exist.
|
||||
|
||||
Live hosting verification (FE-GATE-019, production stage) requires
|
||||
`HOSTING_BASE_URL` and the promoted release deployed by the workflow's
|
||||
`deployment` job. That job is an empty slot until the project fills it in
|
||||
`config/ci/product-gates.json`
|
||||
([`docs/operations/ci-quality-gates.md`](docs/operations/ci-quality-gates.md));
|
||||
until then the result is `UNVERIFIED`, not `PASS`. A host serving another
|
||||
release fails, and so does one without HTTP/2 or entry compression.
|
||||
|
||||
## CI and evidence
|
||||
|
||||
The gate registry is `config/ci/gates.json`; the Gitea workflow is
|
||||
`.gitea/workflows/quality-gates.yml`. It follows:
|
||||
게이트 목록은 `config/ci/gates.json`이고 Gitea workflow는 `.gitea/workflows/quality-gates.yml`이다. 단계 순서:
|
||||
|
||||
```text
|
||||
MERGE_READY -> RELEASE_READY -> PROD_PROMOTION_READY -> FIELD_SLO_READY
|
||||
```
|
||||
|
||||
`DOCUMENTATION_READY` is independent. No gate is downgraded to a warning.
|
||||
`DOCUMENTATION_READY`는 따로 선다. 경고로 낮춘 게이트는 없다.
|
||||
|
||||
The workflow runs on pull requests, pushes to `main` and `develop`, and `v*`
|
||||
tags. The Git host of this repository may not have Actions enabled, so a pull
|
||||
request can show no gate status at all; no status is not a pass. Until the
|
||||
host runs the workflow and marks the merge gates as required checks, run the 14
|
||||
merge gates locally before merging (FE-GATE-008 and 009 need Playwright
|
||||
browsers; FE-GATE-012 builds the app first; FE-GATE-013 needs a Linux host where
|
||||
bubblewrap may create unprivileged user and network namespaces, which Ubuntu
|
||||
23.10 and later refuse by default — its first step says so, and
|
||||
`docs/operations/ci-quality-gates.md` lists the fixes). Product checks listed in
|
||||
`config/ci/product-gates.json` (`PRODUCT-GATE-NNN`) run in the workflow's own
|
||||
`product_merge_gate` job, which the release stage waits for:
|
||||
workflow는 pull request, `main`·`develop` push, `v*` 태그에서 돈다. 이 repo의 Git 호스트는 Actions가 꺼져 있을 수 있다. 그러면 pull request에 게이트 상태가 아예 안 보인다. 상태가 없는 것은 통과가 아니다. 호스트가 workflow를 돌리고 merge 게이트를 필수 검사로 지정하기 전까지는 병합 전에 merge 단계 게이트를 로컬에서 모두 돌린다:
|
||||
|
||||
```bash
|
||||
for gate in 001 002 003 004 005 006 007 008 009 010 011 012 013 020; do
|
||||
corepack pnpm ci:gate -- "FE-GATE-$gate" || break
|
||||
for gate in $(node -p 'require("./config/ci/gates.json").stages.find((s) => s.id === "merge").gateIds.join(" ")'); do
|
||||
corepack pnpm ci:gate -- "$gate" || break
|
||||
done
|
||||
```
|
||||
|
||||
To run them as the workflow does, give the workflow's environment first.
|
||||
`CI=true` makes the runner and the release build require the CI build
|
||||
identity; builds a test makes of a copy (fixture builds, the visual goldens'
|
||||
build, the dev servers of the browser tests) run as local builds whatever this
|
||||
says (`localBuildEnvironment` in `scripts/lib/build-environment.ts`). Run it in
|
||||
a clean clone: `ci:gate` stops a gate at its first failing command.
|
||||
- FE-GATE-008과 FE-GATE-009는 Playwright 브라우저가 필요하다. FE-GATE-012는 먼저 앱을 빌드한다.
|
||||
- FE-GATE-013은 bubblewrap이 비특권 user·network namespace를 만들 수 있는 Linux 호스트가 필요하다. Ubuntu 23.10 이후는 기본으로 거절한다. 첫 단계가 그렇게 알려 주고, 고치는 법은 `docs/operations/ci-quality-gates.md`에 있다.
|
||||
- `config/ci/product-gates.json`에 적은 제품 검사(`PRODUCT-GATE-NNN`)는 workflow의 `product_merge_gate` job에서 돌고, release 단계가 그 job을 기다린다.
|
||||
|
||||
workflow처럼 돌리려면 workflow의 환경을 먼저 준다. `CI=true`이면 실행기와 release 빌드가 CI 빌드 식별값을 요구한다. 테스트가 사본으로 만드는 빌드(fixture 빌드, 시각 골든 빌드, 브라우저 시험의 dev 서버)는 이 값과 상관없이 로컬 빌드로 돈다(`scripts/lib/build-environment.ts`의 `localBuildEnvironment`). 깨끗한 clone에서 돌린다. `ci:gate`는 게이트의 첫 실패 명령에서 멈춘다.
|
||||
|
||||
```bash
|
||||
export CI=true VITE_COMMIT_SHA="$(git rev-parse HEAD)" VITE_BUILD_ID=local-ci-1 \
|
||||
RELEASE_ID=local-ci-1 CI_RUNNER_IMAGE="local/runner@sha256:$(printf 'a%.0s' $(seq 64))"
|
||||
```
|
||||
Machine-readable evidence is written below `artifacts/`; generated evidence is
|
||||
ignored by Git while `.gitkeep` files preserve the taxonomy.
|
||||
|
||||
Run the gates one at a time in a checkout: they and the evidence checks read
|
||||
the fixed `dist/` and `artifacts/` paths. Two Playwright runs can share a
|
||||
checkout when each has its own `TEST_RUN_ID`; its build, results and report go
|
||||
below `.tmp/runs/<id>/`. The test servers always pick a free port. The
|
||||
variables are listed in `docs/testing/frontend-platform-testing-strategy.md`
|
||||
(13.6).
|
||||
- 기계가 읽는 증거는 `artifacts/` 아래에 쓴다. 생성된 증거는 git이 무시하고, `.gitkeep` 파일이 폴더 구조를 지킨다.
|
||||
- 한 checkout에서는 게이트를 하나씩 돌린다. 게이트와 증거 검사가 고정된 `dist/`·`artifacts/` 경로를 읽는다. Playwright 실행 둘은 각자 `TEST_RUN_ID`를 주면 한 checkout을 같이 쓸 수 있다. 그 빌드·결과·보고서는 `.tmp/runs/<id>/` 아래로 간다. 시험 서버는 늘 빈 포트를 고른다. 변수 목록은 설계서 `docs/design/2026-07-26-frontend-platform-testing-strategy-design.md` 13.6절에 있다.
|
||||
|
||||
Operational details are in `docs/operations/`, with incident procedures in
|
||||
`docs/runbooks/`.
|
||||
외부 증거가 필요한 게이트:
|
||||
|
||||
## Updating a copied project
|
||||
- `review:a11y-manual`(release 게이트 FE-GATE-028)은 등록된 모든 라우트에 대해 사람이 서명한 키보드·포커스·스크린 리더 검토가 필요하다. 라우트마다 기록 하나를 `docs/accessibility/route-reviews/<ROUTE_ID>.md`에 둔다. 라우트는 `ROUTE_REGISTRY`다. 등록된 라우트에 기록이 없으면 `verify:documentation`이 라우트 ID를 적고 실패한다. merge 게이트 FE-GATE-009는 `review:a11y-manual -- --format-only`만 돌린다. 모든 라우트 기록이 템플릿의 칸을 지키는지(검토했든 아직이든) 본다.
|
||||
- `collect:web-vitals-evidence`는 검토한 최소 표본 기준과 28일치 production 데이터가 있기 전까지 `FAIL_UNVERIFIED`다.
|
||||
- 운영 호스팅 확인(FE-GATE-019, production 단계)은 `HOSTING_BASE_URL`과 workflow의 `deployment` job이 배포한 승격 릴리스가 필요하다. 그 job은 프로젝트가 `config/ci/product-gates.json`에서 채우기 전까지 빈 자리다([`docs/operations/ci-quality-gates.md`](docs/operations/ci-quality-gates.md)). 그때까지 결과는 `PASS`가 아니라 `UNVERIFIED`다. 다른 릴리스를 서빙하는 호스트, HTTP/2나 진입 압축이 없는 호스트는 실패한다.
|
||||
|
||||
Template versions are Git tags `vX.Y.Z`. [`CHANGELOG.md`](CHANGELOG.md) lists
|
||||
the changes between tags, marks security fixes **[보안]** and contract changes
|
||||
**[계약]** (backend, deployment, CI or feature code must change too), and names
|
||||
the affected paths. Its unreleased section summarizes one sync range (the
|
||||
section head names the base commit and the branch); take that range as a whole
|
||||
and do its "먼저 할 일" (BREAKING) steps in order before running the gates.
|
||||
운영 세부는 `docs/operations/`, 장애 절차는 `docs/runbooks/`에 있다.
|
||||
|
||||
Record where you started. Right after copying, commit a one-line
|
||||
`.template-origin` file at the root of your project with the template tag (or
|
||||
commit) you copied and the date, for example `v0.2.0 2026-09-26`.
|
||||
## 새 서비스로 시작하기
|
||||
|
||||
Take a template fix with Git. `cherry-pick` works even when your repository
|
||||
does not share the template's history, because it merges against the picked
|
||||
commit's parent:
|
||||
1. 복사한 바로 뒤에 프로젝트 루트에 한 줄짜리 `.template-origin` 파일을 커밋한다. 복사한 템플릿 태그(또는 커밋)와 날짜를 적는다. 예: `v0.2.0 2026-09-26`.
|
||||
2. `package.json`의 `name`과 `PRODUCT.md`를 제품 것으로 바꾸고, `docs/vision.md`·`docs/problem-statement.md`를 채운다. `AGENTS.md`·`CLAUDE.md`·`.claude/`·`docs/work/`는 템플릿 계약이라 그대로 받는다. 자기 환경에 맞출 곳은 `docs/work/operate.md` 4.1절과 `docs/work/delegate.md` 4.3절이다.
|
||||
3. 첫 기능은 `corepack pnpm create:feature <id>`로 만든다([`docs/manual/`](docs/manual/README.md)).
|
||||
4. 아래 표의 파일을 지웠으면 merge 게이트를 돌린다(「검증」 절).
|
||||
|
||||
### 복사한 뒤 지워도 되는 것
|
||||
|
||||
템플릿을 만든 과정의 기록이다. 빌드와 게이트는 아래에 적은 파일 하나 말고는 이것들을 읽지 않는다(`tests/unit/deletable-history-documents.test.ts`가 확인한다).
|
||||
|
||||
| 경로 | 내용 |
|
||||
| --- | --- |
|
||||
| `docs/history/` | 끝난 작업의 계획서와 증거. 2026-09-25 리뷰 수정 라운드의 요구사항과 작업 목록도 여기 있다 |
|
||||
| `docs/reviews/` | 리뷰와 리뷰 가이드 포인터. `docs/reviews/adapters/`는 남긴다: `check:adapter-inventory`(FE-GATE-010)가 그 안의 `INVENTORY.md`를 읽고, 그 행이 옆의 adapter 리뷰로 링크하며, `docs/operations/adapter-remediation-ledger.md`가 그 리뷰를 인용한다 |
|
||||
| `docs/ledger/estimates.jsonl` | 템플릿 자신의 작업 예측·실측. 줄을 비우고 자기 프로젝트 줄을 쌓는다(`docs/ledger/README.md`) |
|
||||
| `PRODUCT.md` | 디자인 도구가 읽는 템플릿 자체의 제품 맥락(사용자, 목적, 원칙). 제품 것으로 바꾼다 |
|
||||
|
||||
기능은 이 목록에 없다. 기능 폴더만 지우면 테스트, 정책 항목, CI 스크립트가 남아 게이트가 실패한다.
|
||||
|
||||
- `corepack pnpm test:sample-removal -- --feature=<id>`가 repo 사본에서 그 기능을 지우고, 같이 지워야 하는 것을 모두 적는다(`scripts/test-sample-removal.ts` 머리 주석). 프로젝트에서 같은 것을 지우고 게이트를 돌린다.
|
||||
- 프로젝트가 한동안 두는 샘플은 `scripts/lib/removable-template-features.ts`에 적을 수 있다. 그러면 드릴이 `--feature` 없이 지우고, 문서 검사는 그 기능의 `feature-module.ts`가 없어진 뒤 그 경로를 받아들인다.
|
||||
|
||||
### 원본 업데이트 반영
|
||||
|
||||
템플릿 버전은 Git 태그 `vX.Y.Z`다. [`CHANGELOG.md`](CHANGELOG.md)가 태그 사이의 변경을 적는다.
|
||||
|
||||
- 보안 수정은 **[보안]**, 계약 변경(백엔드·배포·CI·기능 코드도 바꿔야 함)은 **[계약]**으로 표시하고, 영향받는 경로를 적는다.
|
||||
- 미출시 절은 동기화 범위 하나를 요약한다(절 머리에 기준 커밋과 브랜치가 있다). 그 범위를 통째로 받고, 게이트를 돌리기 전에 그 절의 "먼저 할 일"(BREAKING) 단계를 순서대로 한다.
|
||||
|
||||
템플릿 수정 하나는 Git으로 받는다. `cherry-pick`은 고른 커밋의 부모와 병합하므로 템플릿과 이력을 공유하지 않는 repo에서도 된다:
|
||||
|
||||
```bash
|
||||
git remote add template <template repository URL>
|
||||
@@ -397,34 +267,21 @@ git log --oneline <your origin>..template/main # what changed since you copied
|
||||
git cherry-pick -x <commit> # one fix; -x records its origin
|
||||
```
|
||||
|
||||
Take an unreleased range as a whole. A repository that shares the template's
|
||||
history merges the range's branch. One that does not (it started from a copy
|
||||
of the files) merges three-way against the range base, which leaves the files
|
||||
both sides changed as conflicts; resolve them and commit:
|
||||
미출시 범위는 통째로 받는다. 템플릿과 이력을 공유하는 repo는 그 범위의 브랜치를 병합한다. 공유하지 않는 repo(파일 사본에서 시작함)는 범위 기준점과 3-way 병합한다. 양쪽이 바꾼 파일은 충돌로 남으니 풀고 커밋한다:
|
||||
|
||||
```bash
|
||||
git merge --no-ff template/<range branch> # shared history
|
||||
git merge-recursive <range base> -- HEAD template/<range branch> # no shared history
|
||||
```
|
||||
|
||||
Keep the base you synced from where your project records it: `.template-origin`
|
||||
(below), or your own lock file (tech-log keeps it as `sourceRevision` in
|
||||
`template.lock.json`). Move it to the range end once the range is in.
|
||||
- 동기화한 기준점은 프로젝트가 적어 두는 곳에 둔다: `.template-origin`, 또는 자기 잠금 파일(tech-log는 `template.lock.json`의 `sourceRevision`). 범위를 다 받으면 그 끝으로 옮긴다.
|
||||
- 파일이 너무 옮겨졌거나 갈라져서 깨끗하게 고를 수 없으면 diff로 읽고 손으로 적용한다: `git diff <commit>^ <commit> -- <paths from CHANGELOG>`.
|
||||
- 받은 뒤 「검증」 절의 로컬 merge 게이트를 돌리고, **[계약]** 행이 말하는 백엔드·배포 변경을 하고, 태그까지 따라잡았으면 `.template-origin`을 고친다. 받은 수정은 `git revert`로 되돌린다.
|
||||
|
||||
When the files have moved or diverged too far for a clean pick, read the
|
||||
change as a diff and apply it by hand:
|
||||
결함: 바꾸지 않은 `.template-origin` 커밋 checkout에서 재현되면 템플릿 결함이다. 그 커밋과 재현 방법을 템플릿 repo에 알린다. 템플릿 관리자가 분류하고 CHANGELOG 항목과 함께 수정을 낸다. 프로젝트의 변경이 있어야 재현되는 문제는 프로젝트의 몫이고, 템플릿 수정을 자기 사본에 적용하는 것도 프로젝트의 일이다.
|
||||
|
||||
```bash
|
||||
git diff <commit>^ <commit> -- <paths from CHANGELOG>
|
||||
```
|
||||
## 규칙과 기여
|
||||
|
||||
Afterwards run the local merge gates from "CI and evidence", apply the
|
||||
backend or deployment change a **[계약]** row names, and update
|
||||
`.template-origin` once you have caught up to a tag. `git revert` undoes a pick.
|
||||
|
||||
Defects: if a problem reproduces on an unmodified checkout of your
|
||||
`.template-origin` commit, it is a template defect. Report it on the template
|
||||
repository with that commit and the reproduction; the template maintainer
|
||||
classifies it and ships the fix with a CHANGELOG entry. A problem that needs
|
||||
your changes to reproduce belongs to your project, and applying a template fix
|
||||
to your copy is your project's job.
|
||||
- 규칙의 정본은 `AGENTS.md`다. `CLAUDE.md`는 `@AGENTS.md`로 가져오고 Claude Code 전용 줄만 둔다. 리뷰 기준은 `docs/work/reference/review-criteria.md`다.
|
||||
- 커밋 메시지와 PR 본문은 design-docs 저장소의 `conventions/commit-and-pr.md`를 따른다. 문서 규칙의 정본은 같은 저장소의 `conventions/docs-system.md`이고, 이 repo의 적용은 [`docs/README.md`](docs/README.md)에 있다.
|
||||
- 코드나 규칙을 바꾸는 변경은 그것을 설명하는 살아 있는 문서를 같은 변경에서 고친다. 공개 계약을 바꾸면 `CHANGELOG.md`의 미출시 절에 적는다.
|
||||
|
||||
@@ -8,7 +8,7 @@
|
||||
"scaffoldSources": [
|
||||
{
|
||||
"path": "scripts/new-feature.sh",
|
||||
"fact": "path segment: camel-case name plus es, ies or s",
|
||||
"fact": "경로 segment: camel-case 이름 뒤에 es, ies 또는 s를 붙인다",
|
||||
"copiedTo": { "file": "scripts/create-feature.ts", "symbol": "backendPathSegment" }
|
||||
},
|
||||
{
|
||||
@@ -18,22 +18,22 @@
|
||||
},
|
||||
{
|
||||
"path": "scripts/feature-scaffold/templates/src/application-core/src/main/java/dev/caskeleton/application/__feature__/__Feature__ErrorCode.java.tmpl",
|
||||
"fact": "error codes <FEATURE>_INVALID and <FEATURE>_NOT_FOUND",
|
||||
"fact": "오류 코드 <FEATURE>_INVALID와 <FEATURE>_NOT_FOUND",
|
||||
"copiedTo": { "file": "scripts/create-feature-write-slice.ts", "symbol": "invalidCode" }
|
||||
},
|
||||
{
|
||||
"path": "scripts/feature-scaffold/templates/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/__feature__/__Feature__ControllerTest.java.tmpl",
|
||||
"fact": "400 <FEATURE>_INVALID and 404 <FEATURE>_NOT_FOUND bodies",
|
||||
"fact": "400 <FEATURE>_INVALID와 404 <FEATURE>_NOT_FOUND 응답 본문",
|
||||
"copiedTo": { "file": "scripts/create-feature-write-slice.ts", "symbol": "notFoundCode" }
|
||||
},
|
||||
{
|
||||
"path": "scripts/feature-scaffold/templates/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/__feature__/__Feature__Controller.java.tmpl",
|
||||
"fact": "POST /<plural> answers 201, GET /<plural>/{id} reads one",
|
||||
"fact": "POST /<plural>은 201로 답하고, GET /<plural>/{id}는 하나를 읽는다",
|
||||
"copiedTo": { "file": "scripts/create-feature-write-slice.ts", "symbol": "renderWriteDescriptors" }
|
||||
},
|
||||
{
|
||||
"path": "scripts/feature-scaffold/templates/src/application-core/src/main/java/dev/caskeleton/application/__feature__/Create__Feature__UseCase.java.tmpl",
|
||||
"fact": "permission, then name check, then the write: refused before the write",
|
||||
"fact": "권한, 이름 검사, 쓰기 순서다. 거절은 쓰기 전에 일어난다",
|
||||
"copiedTo": { "file": "scripts/create-feature-write-slice.ts", "symbol": "refusedBeforeWrite" }
|
||||
}
|
||||
]
|
||||
|
||||
@@ -31,13 +31,13 @@
|
||||
"referenceRuntime": {
|
||||
"status": "AVAILABLE_NOT_COMPOSED",
|
||||
"coveredCapabilities": [
|
||||
"transport-independent event authority and recovery",
|
||||
"bounded reconnect ownership",
|
||||
"fetch-stream SSE",
|
||||
"bounded polling",
|
||||
"single-writer live and polling handoff",
|
||||
"WebSocket closed protocol",
|
||||
"Web Push window and Service Worker control"
|
||||
"transport에 묶이지 않는 event authority와 복구",
|
||||
"상한이 있는 재연결 소유권",
|
||||
"fetch 스트림 기반 SSE",
|
||||
"상한이 있는 폴링(polling)",
|
||||
"한 번에 하나만 쓰는(single-writer) live·폴링 전환",
|
||||
"WebSocket 닫힌(closed) 프로토콜",
|
||||
"Web Push window와 Service Worker 제어"
|
||||
],
|
||||
"sourceRoots": [
|
||||
"src/application/ports/realtime",
|
||||
@@ -58,18 +58,18 @@
|
||||
],
|
||||
"productionComposition": false
|
||||
},
|
||||
"trigger": "The backend exposes ordered push events with a documented resume and authorization protocol.",
|
||||
"forbiddenWhen": ["Polling satisfies the measured freshness requirement.", "Event ordering and reconnect ownership are undefined."],
|
||||
"boundary": "transport-independent event authority plus separately owned SSE, WebSocket, bounded polling and Web Push adapters",
|
||||
"port": "RealtimeEventAuthority / WebPushControlPort / transport-specific connection and polling factories",
|
||||
"fake": "Deterministic event authority, transport facade, clock, repository and Service Worker test doubles",
|
||||
"trigger": "백엔드가 순서가 보장된 push 이벤트를 내보내고, 이어 받기(resume)와 인가 프로토콜이 문서로 정해져 있다.",
|
||||
"forbiddenWhen": ["측정한 최신성 요구를 폴링으로 채울 수 있다.", "이벤트 순서와 재연결 소유권이 정해지지 않았다."],
|
||||
"boundary": "transport에 묶이지 않는 event authority, 그리고 owner가 따로 있는 SSE·WebSocket·상한 있는 폴링·Web Push adapter",
|
||||
"port": "RealtimeEventAuthority / WebPushControlPort / transport별 연결·폴링 factory",
|
||||
"fake": "결정적으로 동작하는 event authority·transport facade·clock·repository·Service Worker 테스트 대역(test double)",
|
||||
"failureKinds": ["abort", "disconnect-or-timeout", "protocol-or-mapping-mismatch", "duplicate-or-stale", "sequence-gap-or-cursor-expiry", "queue-overflow", "scope-fenced", "poll-budget-exhausted", "push-permission-or-subscription-failure"],
|
||||
"lifecycleMethods": ["close-or-dispose", "unsubscribe", "cancel-via-AbortSignal", "bounded-poll-lease", "revoke-push-association"],
|
||||
"owner": "project-owner-required",
|
||||
"securityPrivacy": ["Validate every event envelope and closed transport frame before application effects.", "Bind stream state to the current opaque scope generation and advance checkpoints only after committed effects or authoritative recovery.", "Use fixed same-origin endpoints and an exact WebSocket subprotocol; never place credentials, cursors, subscription material or scope bindings in URLs or telemetry.", "Treat Web Push as a notification hint, fence registration and revocation with one durable compare-and-swap control record, and allow only registry-owned notification and route intents.", "Keep every queue, parser, reconnect, poll, notification and storage operation bounded and abortable."],
|
||||
"securityPrivacy": ["application effect 전에 모든 이벤트 envelope와 닫힌(closed) transport frame을 검증한다.", "stream 상태를 현재 opaque scope 세대(generation)에 묶는다. checkpoint는 effect가 커밋되었거나 권위 있는 복구가 끝난 뒤에만 전진시킨다.", "고정된 same-origin endpoint와 정확한 WebSocket subprotocol을 쓴다. credential, cursor, 구독 정보, scope binding을 URL이나 telemetry에 절대 넣지 않는다.", "Web Push는 알림 힌트로만 다룬다. 등록과 철회는 지속되는 compare-and-swap 제어 레코드 하나로 막는다(fence). registry가 소유한 알림·route intent만 허용한다.", "모든 queue, parser, 재연결, poll, 알림, 저장 작업에 상한을 두고 중단할 수 있게 한다."],
|
||||
"bundleBudgetGzipBytes": 42200,
|
||||
"fallback": "Bounded polling or explicitly stale UI.",
|
||||
"removal": ["Disable admission and close active readers, sockets, poll leases and worker handlers.", "Revoke and purge only the owned Web Push association and notification state.", "Remove composition, registries, adapters and any selected vendor dependency.", "Run realtime boundary, runtime-removal and production-bundle gates."],
|
||||
"fallback": "상한이 있는 폴링, 또는 데이터가 오래되었음을 드러낸 UI.",
|
||||
"removal": ["새 연결 수락(admission)을 끄고, 열린 reader·socket·poll lease·worker handler를 닫는다.", "소유한 Web Push 연결 정보(association)와 알림 상태만 철회하고 지운다.", "composition, registry, adapter, 선택한 vendor 의존성을 지운다.", "realtime 경계, runtime 제거, production 번들 gate를 돌린다."],
|
||||
"serverStatePolicy": "query-cache-owned"
|
||||
},
|
||||
{
|
||||
@@ -80,7 +80,7 @@
|
||||
"coveredCapabilities": [
|
||||
"IndexedDB",
|
||||
"OPFS",
|
||||
"StorageManager estimate/persistence"
|
||||
"StorageManager 용량 추정(estimate)/영속 저장(persistence)"
|
||||
],
|
||||
"sourceRoots": [
|
||||
"src/application/ports/browser-file-storage/indexeddb-port.ts",
|
||||
@@ -100,18 +100,18 @@
|
||||
],
|
||||
"productionComposition": false
|
||||
},
|
||||
"trigger": "A product requirement needs indexed offline records, an unsynced command queue, or a large local binary sidecar beyond small public preferences.",
|
||||
"forbiddenWhen": ["The data contains credentials.", "The browser would connect directly to a server database or object store.", "A normal HTTP cache is sufficient.", "Partition, retention, quota and recovery ownership are undefined."],
|
||||
"boundary": "feature-specific async repository with registry-issued opaque dataset scope and immutable full-policy binding, plus an OPFS large-object sidecar whose logical commit authority and bidirectional scope binding are owned by an IndexedDB journal",
|
||||
"trigger": "제품 요구사항에 작은 공개 설정값 이상의 저장이 필요하다. 색인된 오프라인 레코드, 아직 동기화하지 않은 명령 queue, 큰 로컬 바이너리 sidecar 같은 것이다.",
|
||||
"forbiddenWhen": ["데이터에 credential이 들어 있다.", "브라우저가 서버 데이터베이스나 object store에 직접 연결하게 된다.", "일반 HTTP 캐시로 충분하다.", "partition, 보존 기간, quota, 복구의 owner가 정해지지 않았다."],
|
||||
"boundary": "feature 전용 비동기 repository. registry가 발급한 opaque dataset scope와, 바뀌지 않는 전체 정책 binding을 가진다. 여기에 OPFS 큰 객체 sidecar가 붙는다. 이 sidecar의 논리 커밋 권한과 양방향 scope binding은 IndexedDB journal이 소유한다",
|
||||
"port": "IndexedDbRepositoryPort / IndexedDbMaintenancePort / DurableObjectStorePort / DurableObjectMaintenancePort / StorageDurabilityPort",
|
||||
"fake": "MemoryDurableObjectStore / MemoryStorageDurabilityAdapter (no recipe fake implements IndexedDbRepositoryPort; run the reference runtime on tests/helpers/memory-indexeddb.ts)",
|
||||
"fake": "MemoryDurableObjectStore / MemoryStorageDurabilityAdapter (IndexedDbRepositoryPort를 구현한 recipe fake는 없다. 참조 runtime을 tests/helpers/memory-indexeddb.ts 위에서 돌린다)",
|
||||
"failureKinds": ["open-blocked", "versionchange", "quota", "corruption", "migration-rollback", "revision-conflict", "storage-eviction", "partial-object-write", "dataset-binding-mismatch", "dataset-budget-exceeded", "lifecycle-authorization-denied", "expired-resource"],
|
||||
"lifecycleMethods": ["close", "cancel-via-AbortSignal", "enforce-bounded-lifecycle-batch", "prune-expired-receipts", "reconcile", "enforcePolicies-with-composition-authority"],
|
||||
"owner": "project-owner-required",
|
||||
"securityPrivacy": ["Classify every persisted field and binary namespace.", "Encrypting in the same client is not a credential protection boundary.", "Keep database schema and record codec versions separate.", "Derive the physical IndexedDB name only from registry-issued authority, namespace and partition tokens; readable namespace, business and account IDs are forbidden.", "Persist and revalidate an immutable scope plus full BrowserStoragePolicy binding during upgrade, post-open and maintenance; missing or mismatched existing bindings fail closed.", "Use the actual IndexedDB wire split: StoredRecord contains only key, codecVersion, revision and payload; writtenAtEpochMs, synchronization, measuredBytes and eligibleAtEpochMs belong to the retention sidecar, while idempotency receipts and governance binding/budget use separate stores.", "Include every store registered in lifecycleMetadataStores in bounded full-partition purge while retaining immutable governance identity.", "Measure conservative logical bytes through the codec and atomically enforce dataset usedBytes plus receiptCount with record, lifecycle and migration writes.", "Enforce TTL before sweep visibility, delete UNTIL_SYNCED only after explicit confirmation, and require a composition-authorized short-lived proof for every deleting IndexedDB lifecycle batch.", "Bound idempotency receipt retention to 31 days and configured count to the implementation ceiling of 1000000; bound migration to old-writer-drained batches no larger than 500 rows or 30000ms.", "Bind OPFS readable and physical scopes in both directions and use only /ca-frontend-opfs-v1/authorities/<authorityToken>/<namespaceToken>/<partitionToken>/ for physical dataset layout.", "For OPFS LOGOUT, UNTIL_SYNCED and ACCOUNT_DELETION maintenance, composition must provide both requestMaintenanceAuthority and consumeMaintenanceAuthority; issue a fresh proof bound to the exact frozen reason, scope and policy for at most five minutes, then atomically consume it to reject replay.", "Never expose an OPFS authority proof through the application request, persistence, diagnostics or telemetry.", "Never place user file names or identifiers in OPFS paths or diagnostics."],
|
||||
"securityPrivacy": ["저장하는 모든 필드와 바이너리 namespace를 분류한다.", "같은 클라이언트 안에서 암호화하는 것은 credential 보호 경계가 아니다.", "데이터베이스 스키마 버전과 레코드 codec 버전을 따로 둔다.", "물리 IndexedDB 이름은 registry가 발급한 authority·namespace·partition token으로만 만든다. 읽을 수 있는 namespace·업무·계정 ID는 금지한다.", "바뀌지 않는 scope와 BrowserStoragePolicy 전체 binding을 저장하고, upgrade·open 직후·maintenance 때 다시 검증한다. 기존 binding이 없거나 맞지 않으면 닫힌 쪽으로 실패한다(fail closed).", "실제 IndexedDB 저장 분할을 따른다. StoredRecord에는 key, codecVersion, revision, payload만 들어간다. writtenAtEpochMs, synchronization, measuredBytes, eligibleAtEpochMs는 보존(retention) sidecar에 둔다. 멱등성 receipt와 governance binding/budget은 별도 store를 쓴다.", "상한 있는 partition 전체 삭제(purge)에 lifecycleMetadataStores에 등록된 모든 store를 포함한다. 이때 바뀌지 않는 governance 식별 정보는 남긴다.", "논리 바이트 수를 codec으로 보수적으로(넉넉하게) 잰다. dataset의 usedBytes와 receiptCount 한도는 레코드·lifecycle·migration 쓰기와 함께 원자적으로 지킨다.", "TTL은 sweep에 보이기 전에 적용한다. UNTIL_SYNCED는 명시적 확인 뒤에만 지운다. 삭제하는 IndexedDB lifecycle batch마다 composition이 허가한 짧은 수명의 proof를 요구한다.", "멱등성 receipt 보존은 31일로, 설정 개수는 구현 상한인 1000000으로 제한한다. migration은 옛 writer가 모두 빠진 뒤의 batch로만 하고, batch 하나는 500행 또는 30000ms를 넘지 않는다.", "OPFS의 읽을 수 있는 scope와 물리 scope를 양방향으로 묶는다. 물리 dataset 배치에는 /ca-frontend-opfs-v1/authorities/<authorityToken>/<namespaceToken>/<partitionToken>/만 쓴다.", "OPFS LOGOUT·UNTIL_SYNCED·ACCOUNT_DELETION maintenance에는 composition이 requestMaintenanceAuthority와 consumeMaintenanceAuthority를 둘 다 제공해야 한다. 고정된 reason·scope·policy에 정확히 묶인 새 proof를 최대 5분 동안 유효하게 발급하고, 재사용(replay)을 막도록 원자적으로 소비한다.", "OPFS authority proof를 application 요청, 저장, 진단, telemetry로 절대 내보내지 않는다.", "사용자 파일 이름이나 식별자를 OPFS 경로나 진단 정보에 절대 넣지 않는다."],
|
||||
"bundleBudgetGzipBytes": 38500,
|
||||
"fallback": "Read-only or online-only query path; OPFS may degrade to a size-capped IndexedDB Blob only when the product policy approves it.",
|
||||
"removal": ["Stop writes and background migration.", "Reconcile or export unsynced data, then purge only governance-bound owned partitions and OPFS namespaces through authorized bounded lifecycle operations.", "Close all database, channel, worker and file handles.", "Remove repository composition and dependency."],
|
||||
"fallback": "읽기 전용 또는 온라인 전용 query 경로. OPFS는 제품 정책이 승인할 때만 크기 상한이 있는 IndexedDB Blob으로 낮출 수 있다.",
|
||||
"removal": ["쓰기와 백그라운드 migration을 멈춘다.", "동기화하지 않은 데이터를 맞추거나(reconcile) 내보낸다. 그다음 허가된 상한 있는 lifecycle 작업으로, governance에 묶인 소유 partition과 OPFS namespace만 지운다.", "모든 데이터베이스·channel·worker·파일 handle을 닫는다.", "repository composition과 의존성을 지운다."],
|
||||
"serverStatePolicy": "reference-or-command-only"
|
||||
},
|
||||
{
|
||||
@@ -120,7 +120,7 @@
|
||||
"referenceRuntime": {
|
||||
"status": "AVAILABLE_NOT_COMPOSED",
|
||||
"coveredCapabilities": [
|
||||
"Cache Storage public-response administration"
|
||||
"Cache Storage 공개 응답 관리"
|
||||
],
|
||||
"sourceRoots": [
|
||||
"src/application/ports/browser-file-storage/cache-storage-ports.ts",
|
||||
@@ -137,18 +137,18 @@
|
||||
],
|
||||
"productionComposition": false
|
||||
},
|
||||
"trigger": "Installability or an explicitly owned public HTTP representation cache is approved. The reference worker keeps navigation network-only and has no offline shell; an offline document is a separate product capability (closed deep design 18.8).",
|
||||
"forbiddenWhen": ["Hosting cache and worker cache ownership conflict.", "Update and rollback UX is undefined.", "Authenticated, private, opaque or personal responses would be cached.", "Cache freshness, byte and entry limits are undefined."],
|
||||
"boundary": "bootstrap update controller plus platform-local public Request/Response cache administration",
|
||||
"port": "ServiceWorkerUpdatePort / PublicResponseCacheAdmin recipe / PublicResponseCachePort / PublicResponseCacheAdminPort reference runtime",
|
||||
"trigger": "설치 가능성(installability), 또는 owner가 명시된 공개 HTTP 표현(representation) 캐시가 승인되었다. 참조 worker는 navigation을 network-only로 두고 오프라인 셸이 없다. 오프라인 문서는 별도 제품 capability다(closed deep design 18.8).",
|
||||
"forbiddenWhen": ["hosting 캐시와 worker 캐시의 소유권이 충돌한다.", "업데이트와 rollback UX가 정해지지 않았다.", "인증된 응답, private 응답, opaque 응답, 개인 응답이 캐시에 들어가게 된다.", "캐시 신선도·바이트·항목 수 한도가 정해지지 않았다."],
|
||||
"boundary": "bootstrap 업데이트 controller, 그리고 platform 안에서만 쓰는 공개 Request/Response 캐시 관리",
|
||||
"port": "ServiceWorkerUpdatePort / PublicResponseCacheAdmin recipe / PublicResponseCachePort / PublicResponseCacheAdminPort 참조 runtime",
|
||||
"fake": "FakeServiceWorkerUpdateAdapter / MemoryPublicResponseCache",
|
||||
"failureKinds": ["stale-worker", "update-loop", "offline-navigation-network-error", "incomplete-candidate", "integrity-mismatch", "cache-policy-rejection", "quota"],
|
||||
"lifecycleMethods": ["unregister", "rollback", "delete-owned-caches"],
|
||||
"owner": "project-owner-required",
|
||||
"securityPrivacy": ["Cache only explicit same-origin public GET representations.", "Never cache authenticated, cookie-dependent, private, no-store, opaque or personal responses.", "Bind candidate cache names to release identity and a canonical manifest digest that includes normalized expectedContentType, exact request identity, expected byte length and integrity digest.", "Reject a response whose normalized Content-Type differs from manifest expectedContentType even when body integrity matches.", "Derive cleanup retention only from the verified active pointer and composition retainedPreviousReleaseCount; cleanup callers cannot submit cache names, release registry IDs or any retain set.", "Read active-pointer and release-marker control JSON through a strict UTF-8 stream capped at exactly 2 MiB (2097152 bytes), cancel on overflow and fail closed before parsing oversized metadata.", "Keep exact query and Vary semantics; ignoreSearch and ignoreVary are forbidden.", "Fail closed on malformed update metadata or integrity mismatch."],
|
||||
"securityPrivacy": ["명시된 same-origin 공개 GET 표현만 캐시한다.", "인증된 응답, 쿠키에 따라 달라지는 응답, private·no-store·opaque 응답, 개인 응답은 절대 캐시하지 않는다.", "후보 캐시 이름을 release 식별자와 정규형(canonical) manifest digest에 묶는다. 이 digest에는 정규화한 expectedContentType, 정확한 요청 식별자, 예상 바이트 길이, integrity digest가 들어간다.", "정규화한 Content-Type이 manifest의 expectedContentType과 다르면, 본문 integrity가 맞아도 응답을 거절한다.", "정리 때 남길 대상은 검증된 active pointer와 composition의 retainedPreviousReleaseCount로만 정한다. 정리를 부르는 쪽은 캐시 이름, release registry ID, 남길 집합을 넘길 수 없다.", "active-pointer와 release-marker 제어 JSON은 정확히 2 MiB(2097152 bytes)로 상한을 둔 엄격한 UTF-8 stream으로 읽는다. 상한을 넘으면 취소하고, 너무 큰 metadata는 파싱하기 전에 닫힌 쪽으로 실패한다.", "query와 Vary의 의미를 정확히 지킨다. ignoreSearch와 ignoreVary는 금지한다.", "업데이트 metadata가 잘못되었거나 integrity가 맞지 않으면 닫힌 쪽으로 실패한다."],
|
||||
"bundleBudgetGzipBytes": 10100,
|
||||
"fallback": "Normal network application with hosting cache headers.",
|
||||
"removal": ["Deploy an unregister migration.", "Delete only parsed, owned cache namespaces after old controlled clients drain.", "Remove worker registration, cache metadata and manifest."],
|
||||
"fallback": "hosting 캐시 헤더를 쓰는 일반 네트워크 application.",
|
||||
"removal": ["등록 해제(unregister) migration을 배포한다.", "옛 worker가 제어하던 클라이언트가 모두 빠진 뒤, 파싱해 확인한 소유 캐시 namespace만 지운다.", "worker 등록, 캐시 metadata, manifest를 지운다."],
|
||||
"serverStatePolicy": "network-cache-policy-only"
|
||||
},
|
||||
{
|
||||
@@ -159,15 +159,15 @@
|
||||
"coveredCapabilities": [
|
||||
"File",
|
||||
"Blob",
|
||||
"native file input",
|
||||
"system file picker",
|
||||
"object URL preview",
|
||||
"download delivery",
|
||||
"native 파일 input",
|
||||
"시스템 파일 선택기",
|
||||
"object URL 미리보기",
|
||||
"다운로드 전달",
|
||||
"presigned URL capability",
|
||||
"bounded streaming download",
|
||||
"multipart/resumable upload",
|
||||
"durable non-secret upload checkpoint",
|
||||
"Image CDN responsive delivery"
|
||||
"상한이 있는 스트리밍 다운로드",
|
||||
"multipart/이어 올리기(resumable) 업로드",
|
||||
"지속되는, 비밀이 아닌 업로드 checkpoint",
|
||||
"Image CDN 반응형 전달"
|
||||
],
|
||||
"sourceRoots": [
|
||||
"src/application/ports/browser-file-storage/file.ts",
|
||||
@@ -186,154 +186,154 @@
|
||||
],
|
||||
"productionComposition": false
|
||||
},
|
||||
"trigger": "The product selects, inspects, previews, uploads, downloads or delivers image renditions with bounded memory, resumability, cancellation, expiry and integrity requirements.",
|
||||
"forbiddenWhen": ["Allowed count, byte, extension, MIME and content-signature policy is missing.", "The BFF does not own authorization, short-lived capability issuance, upload session reconciliation, quarantine and orphan cleanup.", "Long-lived credentials, presigned URLs or signed headers would enter persistence, application state or telemetry.", "Native File, Blob, object URL or file-system handles would cross into domain state or persistence.", "Large downloads would be returned as one in-memory byte array or Blob.", "Image callers could submit arbitrary CDN source URLs or transform parameters."],
|
||||
"boundary": "BFF-owned transfer control plane plus adapter-owned browser/object-storage data plane; presentation receives opaque file/image references, registered policies and bounded result streams only",
|
||||
"trigger": "제품이 파일을 고르고, 검사하고, 미리 보고, 올리고, 내려받거나, 이미지 rendition을 전달한다. 여기에 메모리 상한, 이어 하기, 취소, 만료, integrity 요구가 있다.",
|
||||
"forbiddenWhen": ["허용 개수·바이트·확장자·MIME·내용 서명(content-signature) 정책이 없다.", "BFF가 인가, 짧은 수명의 capability 발급, 업로드 세션 맞춤(reconciliation), 격리(quarantine), 고아 파일 정리를 맡지 않는다.", "오래 사는 credential, presigned URL, 서명된 header가 저장소, application 상태, telemetry에 들어가게 된다.", "native File·Blob·object URL·파일 시스템 handle이 domain 상태나 저장소로 넘어가게 된다.", "큰 다운로드를 메모리 안의 바이트 배열 하나나 Blob 하나로 돌려주게 된다.", "이미지를 부르는 쪽이 임의의 CDN 원본 URL이나 변환 파라미터를 넘길 수 있다."],
|
||||
"boundary": "BFF가 소유하는 전송 control plane, 그리고 adapter가 소유하는 브라우저/object-storage data plane. presentation은 opaque 파일/이미지 참조, 등록된 정책, 상한 있는 결과 stream만 받는다",
|
||||
"port": "FilePickerPort / FileContentPort / TransientPreviewPort / DownloadDeliveryPort / PresignedDownloadSourcePort / PresignedUploadPartPort / ResumableUploadPort / ImageCdnPresentationPort",
|
||||
"fake": "Memory file/preview/download adapters plus injected deterministic capability, upload-control-plane, part-executor and image-verifier test doubles",
|
||||
"fake": "메모리 파일/미리보기/다운로드 adapter, 그리고 주입하는 결정적 capability·upload-control-plane·part-executor·image-verifier 테스트 대역",
|
||||
"failureKinds": ["dismissed", "permission-denied", "count-or-size-rejection", "type-or-signature-rejection", "file-changed", "abort", "integrity-failure", "partial-save", "expired-or-revoked-capability", "part-or-session-conflict", "checkpoint-conflict", "quarantined", "image-policy-rejection"],
|
||||
"lifecycleMethods": ["release-file-ref", "release-or-dispose-preview-leases", "cancel-via-AbortSignal", "reconcile-or-explicitly-abort-upload", "close-checkpoint-store", "dispose-capability-and-image-runtime", "dispose-browser-file-runtime-on-logout-or-account-switch"],
|
||||
"owner": "project-owner-required",
|
||||
"securityPrivacy": ["Treat file name, extension, MIME and lastModified as untrusted metadata.", "Resolve only exact composition-issued file and image policy object identities; callers cannot raise byte, candidate, pixel, quality, format, lifetime or origin ceilings.", "Use opaque file references and verification receipts bound to an inspected immutable file snapshot and the exact registered profile; reject replay through another profile even when an inspection rule ID matches.", "Treat presigned URLs as bearer capabilities; bind exact method, resource or upload part, offset, length, media type, checksum, origin, path, query, headers and expiry in an in-memory identity vault.", "Use credentials omit, redirect error, no-referrer and no-store for direct data-plane fetch; never persist or observe URL, query, signed header, capability, file name or raw backend message, and never emit digest, raw ETag or receipt values to diagnostics or telemetry.", "A strict account-partitioned upload checkpoint may persist only the protocol-defined SHA-256 file fingerprint, per-part checksum and bounded opaque non-authorizing part receipt token required for server reconciliation; no bearer token or raw signed capability is allowed.", "Persist only strict non-authorizing upload checkpoints and reconcile them with server-authoritative status and re-hashed local parts before completion.", "Require a synchronous server-issued browser-managed download capability whose receipt exactly equals the caller's branded capability receipt and whose resource, media type, safe extension, maximum bytes, optional digest and expiry all match before handoff.", "Expose File, OPFS, Cache and transfer byte streams only as chunk-level closed Results; stop after the first failure, cancel native readers and never throw a raw native exception across the port.", "Accept Image CDN assets only through immutable allowlisted or signature-verified descriptors and registered preset identities; reject active formats, arbitrary transforms, pixel/decode-budget overflow and unsafe cache policy.", "Upload completion remains QUARANTINED until backend scan and promotion; client capability checks are not an authorization boundary.", "Active content preview requires isolation or download-only treatment."],
|
||||
"securityPrivacy": ["파일 이름, 확장자, MIME, lastModified는 믿을 수 없는 metadata로 다룬다.", "composition이 발급한 파일·이미지 정책 객체는 식별자가 정확히 같을 때만 쓴다. 부르는 쪽은 바이트·후보·픽셀·품질·형식·수명·origin 상한을 올릴 수 없다.", "opaque 파일 참조와 검증 receipt를 쓰고, 둘 다 검사를 마친 불변 파일 snapshot과 정확히 등록된 profile에 묶는다. 검사 규칙 ID가 같아도 다른 profile을 거친 재사용(replay)은 거절한다.", "presigned URL은 bearer capability로 다룬다. method, resource 또는 upload part, offset, length, media type, checksum, origin, path, query, header, 만료를 메모리 안 identity vault에 정확히 묶는다.", "data plane에 직접 fetch할 때는 credentials omit, redirect error, no-referrer, no-store를 쓴다. URL, query, 서명된 header, capability, 파일 이름, 원본 백엔드 메시지를 저장하거나 관찰하지 않는다. digest, 원본 ETag, receipt 값을 진단이나 telemetry로 내보내지 않는다.", "계정별로 나뉜 엄격한 업로드 checkpoint는 서버와 맞추는 데 필요한 것만 저장할 수 있다. 프로토콜이 정한 SHA-256 파일 fingerprint, part별 checksum, 길이 상한이 있고 권한을 주지 않는 opaque part receipt token이다. bearer token이나 서명된 capability 원본은 허용하지 않는다.", "권한을 주지 않는 엄격한 업로드 checkpoint만 저장한다. 완료 전에 그 checkpoint를, 서버가 권위를 가진 상태와 다시 해시한 로컬 part에 맞춘다.", "넘겨주기 전에, 서버가 동기로 발급하고 브라우저가 관리하는 다운로드 capability를 요구한다. 그 receipt는 부르는 쪽의 branded capability receipt와 정확히 같아야 하고, resource, media type, 안전한 확장자, 최대 바이트, 선택 digest, 만료가 모두 맞아야 한다.", "File, OPFS, Cache, 전송 byte stream은 chunk 단위의 닫힌(closed) Result로만 내보낸다. 첫 실패에서 멈추고, native reader를 취소하고, native 예외 원본을 port 너머로 던지지 않는다.", "Image CDN asset은 허용 목록(allowlist)에 있거나 서명이 검증된 불변 descriptor와, 등록된 preset 식별자로만 받는다. active 형식, 임의 변환, 픽셀/decode budget 초과, 안전하지 않은 캐시 정책은 거절한다.", "업로드 완료는 백엔드 검사와 promotion 전까지 QUARANTINED로 남는다. 클라이언트의 capability 검사는 인가 경계가 아니다.", "active content 미리보기는 격리하거나 다운로드 전용으로 다뤄야 한다."],
|
||||
"bundleBudgetGzipBytes": 57800,
|
||||
"fallback": "Accessible native file input, same-origin authorized server upload/download and a single bounded server-selected image rendition; generated artifacts above the buffer budget move to server-side generation. The paired backend template has no presigned or direct multipart server (removed 2026-09-25): with it, upload through its Fileserver (POST /v1/files) with createFileserverUploadClient from src/adapters/http.",
|
||||
"removal": ["Stop new capability and upload-session issuance, then cancel active reads and transfers.", "Reconcile or explicitly abort active multipart sessions and let backend TTL cleanup remove ambiguous orphans.", "Remove non-secret checkpoints according to account and retention policy.", "Release file references, revoke preview object-URL leases and dispose file, capability and image runtimes.", "Remove transfer/image feature facades and composition, then prove browser-transfer sources are absent from the production module inventory."],
|
||||
"fallback": "접근성을 갖춘 native 파일 input, 인가된 same-origin 서버 업로드/다운로드, 서버가 고른 상한 있는 이미지 rendition 하나. buffer budget을 넘는 생성 산출물은 서버에서 만든다. 짝 백엔드 템플릿에는 presigned나 직접 multipart 서버가 없다(2026-09-25에 지웠다). 짝 백엔드와 쓸 때는 src/adapters/http의 createFileserverUploadClient로 그 Fileserver(POST /v1/files)에 올린다.",
|
||||
"removal": ["새 capability와 업로드 세션 발급을 멈추고, 진행 중인 읽기와 전송을 취소한다.", "진행 중인 multipart 세션을 맞추거나 명시적으로 중단한다. 상태가 애매한 고아는 백엔드 TTL 정리가 지우게 둔다.", "비밀이 아닌 checkpoint를 계정·보존 정책에 따라 지운다.", "파일 참조를 놓아주고, 미리보기 object-URL lease를 철회하고, 파일·capability·이미지 runtime을 정리(dispose)한다.", "전송/이미지 feature facade와 composition을 지우고, browser-transfer 소스가 production 모듈 목록(inventory)에 없음을 증명한다."],
|
||||
"serverStatePolicy": "query-cache-metadata-only"
|
||||
},
|
||||
{
|
||||
"id": "generated-api",
|
||||
"status": "RECIPE_AVAILABLE",
|
||||
"trigger": "A versioned backend contract justifies generated transport code.",
|
||||
"forbiddenWhen": ["Generated DTOs would escape into domain or presentation.", "Contract drift cannot block CI."],
|
||||
"boundary": "generated client wrapped by a feature gateway facade and mapper",
|
||||
"trigger": "버전이 붙은 백엔드 계약이 있어, 생성된 transport 코드를 쓸 근거가 된다.",
|
||||
"forbiddenWhen": ["생성된 DTO가 domain이나 presentation으로 새어 나가게 된다.", "계약 drift가 CI를 막지 못한다."],
|
||||
"boundary": "feature gateway facade와 mapper로 감싼 생성 client",
|
||||
"port": "GeneratedApiFacade",
|
||||
"fake": "FakeGeneratedApiAdapter",
|
||||
"failureKinds": ["contract-drift", "unsupported-field"],
|
||||
"lifecycleMethods": ["cancel-via-AbortSignal"],
|
||||
"owner": "project-owner-required",
|
||||
"securityPrivacy": ["Generate from an authenticated source.", "Review generator execution and output.", "Do not log request bodies."],
|
||||
"securityPrivacy": ["인증된 출처에서 생성한다.", "생성기 실행과 출력을 검토한다.", "요청 본문을 로그에 남기지 않는다."],
|
||||
"bundleBudgetGzipBytes": 16000,
|
||||
"fallback": "Existing typed request builder and runtime response schema.",
|
||||
"removal": ["Restore handwritten gateway.", "Remove generated output and generator.", "Verify DTOs do not remain in public types."],
|
||||
"fallback": "기존의 타입 있는 요청 builder와 runtime 응답 스키마.",
|
||||
"removal": ["손으로 쓴 gateway로 되돌린다.", "생성된 출력과 생성기를 지운다.", "공개 타입에 DTO가 남지 않았는지 확인한다."],
|
||||
"serverStatePolicy": "query-cache-owned"
|
||||
},
|
||||
{
|
||||
"id": "feature-flag",
|
||||
"status": "RECIPE_AVAILABLE",
|
||||
"trigger": "A staged rollout or kill switch has a named owner, default and stale policy.",
|
||||
"forbiddenWhen": ["A flag is used as authorization.", "Unknown and unavailable behavior is undefined."],
|
||||
"boundary": "application feature policy output port",
|
||||
"trigger": "단계적 출시(staged rollout)나 kill switch에 이름이 정해진 owner, 기본값, 오래된 값(stale) 정책이 있다.",
|
||||
"forbiddenWhen": ["flag를 인가에 쓴다.", "알 수 없는(unknown) 경우와 쓸 수 없는(unavailable) 경우의 동작이 정해지지 않았다."],
|
||||
"boundary": "application feature 정책 출력 port",
|
||||
"port": "FeatureFlagPort",
|
||||
"fake": "FakeFeatureFlagAdapter",
|
||||
"failureKinds": ["provider-unavailable", "unknown-flag", "stale-value"],
|
||||
"lifecycleMethods": ["dispose-provider-if-installed"],
|
||||
"owner": "project-owner-required",
|
||||
"securityPrivacy": ["Flags are hints, never access control.", "Minimize targeting attributes.", "Apply consent rules to personal attributes."],
|
||||
"securityPrivacy": ["flag는 힌트일 뿐 접근 제어가 아니다.", "targeting 속성을 최소로 둔다.", "개인 속성에는 동의 규칙을 적용한다."],
|
||||
"bundleBudgetGzipBytes": 10000,
|
||||
"fallback": "Typed local default with an explicit stale decision.",
|
||||
"removal": ["Resolve the rollout permanently.", "Delete flag key and branches.", "Remove provider composition and dependency."],
|
||||
"fallback": "stale 판단을 명시한 타입 있는 로컬 기본값.",
|
||||
"removal": ["출시를 영구히 확정한다.", "flag 키와 분기를 지운다.", "provider composition과 의존성을 지운다."],
|
||||
"serverStatePolicy": "policy-cache-only"
|
||||
},
|
||||
{
|
||||
"id": "web-worker",
|
||||
"status": "RECIPE_AVAILABLE",
|
||||
"trigger": "Profiling shows CPU work blocking the main thread beyond the performance budget.",
|
||||
"forbiddenWhen": ["The task is primarily network I/O.", "Cancellation and stale-result ownership are undefined."],
|
||||
"boundary": "request/result/cancel output port with a validated message adapter",
|
||||
"trigger": "프로파일링 결과 CPU 작업이 성능 budget을 넘게 main thread를 막는다.",
|
||||
"forbiddenWhen": ["작업이 주로 네트워크 I/O다.", "취소와 오래된 결과(stale result)의 소유권이 정해지지 않았다."],
|
||||
"boundary": "검증하는 message adapter를 둔 request/result/cancel 출력 port",
|
||||
"port": "WorkerTaskPort",
|
||||
"fake": "FakeWorkerTaskAdapter",
|
||||
"failureKinds": ["crash", "stale-result", "transfer-failure"],
|
||||
"lifecycleMethods": ["cancel", "dispose"],
|
||||
"owner": "project-owner-required",
|
||||
"securityPrivacy": ["Validate worker messages.", "Do not send credentials.", "Bound transferred data and worker count."],
|
||||
"securityPrivacy": ["worker 메시지를 검증한다.", "credential을 보내지 않는다.", "넘기는 데이터와 worker 수에 상한을 둔다."],
|
||||
"bundleBudgetGzipBytes": 14000,
|
||||
"fallback": "Chunked or deferred main-thread execution within a measured limit.",
|
||||
"removal": ["Stop and dispose workers.", "Restore synchronous facade implementation.", "Remove worker entry and chunk."],
|
||||
"fallback": "측정한 한도 안에서 나누거나 미룬 main thread 실행.",
|
||||
"removal": ["worker를 멈추고 정리(dispose)한다.", "동기 facade 구현으로 되돌린다.", "worker entry와 chunk를 지운다."],
|
||||
"serverStatePolicy": "no-server-state"
|
||||
},
|
||||
{
|
||||
"id": "multi-tab",
|
||||
"status": "RECIPE_AVAILABLE",
|
||||
"trigger": "A documented workflow must synchronize non-sensitive events across tabs.",
|
||||
"forbiddenWhen": ["The server is the correct conflict authority.", "Event version and source identity are undefined."],
|
||||
"boundary": "versioned browser event output/input adapter",
|
||||
"trigger": "문서로 정한 workflow가 민감하지 않은 이벤트를 탭 사이에 맞춰야 한다.",
|
||||
"forbiddenWhen": ["충돌 판정은 서버가 하는 것이 맞다.", "이벤트 버전과 출처 식별자가 정해지지 않았다."],
|
||||
"boundary": "버전이 붙은 브라우저 이벤트 출력/입력 adapter",
|
||||
"port": "MultiTabPort",
|
||||
"fake": "FakeMultiTabAdapter",
|
||||
"failureKinds": ["self-echo", "duplicate", "conflict"],
|
||||
"lifecycleMethods": ["unsubscribe", "close"],
|
||||
"owner": "project-owner-required",
|
||||
"securityPrivacy": ["Broadcast no credentials or personal payload.", "Validate versions.", "Treat events as hints rather than authorization."],
|
||||
"securityPrivacy": ["credential이나 개인 payload를 broadcast하지 않는다.", "버전을 검증한다.", "이벤트는 인가가 아니라 힌트로 다룬다."],
|
||||
"bundleBudgetGzipBytes": 4000,
|
||||
"fallback": "Refresh from the authoritative server on focus.",
|
||||
"removal": ["Close channels.", "Remove event registry entries.", "Restore focus-based refresh."],
|
||||
"fallback": "focus를 받으면 권위 있는 서버에서 다시 읽는다.",
|
||||
"removal": ["channel을 닫는다.", "이벤트 registry 항목을 지운다.", "focus 기반 새로고침으로 되돌린다."],
|
||||
"serverStatePolicy": "invalidation-only"
|
||||
},
|
||||
{
|
||||
"id": "browser-permission",
|
||||
"status": "RECIPE_AVAILABLE",
|
||||
"trigger": "A user-initiated flow requires clipboard, notification or media access.",
|
||||
"forbiddenWhen": ["Permission would be requested at boot.", "Denied, dismissed and unsupported UX are not designed."],
|
||||
"boundary": "presentation input action through a browser capability output port",
|
||||
"trigger": "사용자가 시작한 흐름에 클립보드·알림·미디어 접근이 필요하다.",
|
||||
"forbiddenWhen": ["boot 때 권한을 요청하게 된다.", "거부·닫힘·미지원 UX를 설계하지 않았다."],
|
||||
"boundary": "브라우저 capability 출력 port를 거치는 presentation 입력 action",
|
||||
"port": "BrowserPermissionPort",
|
||||
"fake": "FakeBrowserPermissionAdapter",
|
||||
"failureKinds": ["denied", "dismissed", "unsupported"],
|
||||
"lifecycleMethods": ["stop-media-tracks-if-opened"],
|
||||
"owner": "project-owner-required",
|
||||
"securityPrivacy": ["Require an explicit user gesture.", "Minimize requested scope.", "Do not persist permission as authorization."],
|
||||
"securityPrivacy": ["명시적인 사용자 동작(user gesture)을 요구한다.", "요청 범위를 최소로 둔다.", "권한 허용을 인가로 저장하지 않는다."],
|
||||
"bundleBudgetGzipBytes": 3000,
|
||||
"fallback": "Manual input or copy/download instruction.",
|
||||
"removal": ["Stop acquired resources.", "Remove permission action and adapter.", "Retest denied-path accessibility."],
|
||||
"fallback": "직접 입력, 또는 복사/다운로드 안내.",
|
||||
"removal": ["얻은 자원을 멈춘다.", "권한 action과 adapter를 지운다.", "거부 경로의 접근성을 다시 시험한다."],
|
||||
"serverStatePolicy": "no-server-state"
|
||||
},
|
||||
{
|
||||
"id": "client-workflow",
|
||||
"status": "RECIPE_AVAILABLE",
|
||||
"trigger": "A measured cross-page client-only workflow cannot be represented by URL, local state, context or query cache.",
|
||||
"forbiddenWhen": ["The store would duplicate server response collections.", "A library is selected before state ownership is documented.", "Zustand and Redux Toolkit would both be installed."],
|
||||
"boundary": "workflow-specific local facade; vendor types remain in its adapter",
|
||||
"trigger": "측정해 보니 여러 페이지에 걸친 클라이언트 전용 workflow를 URL, 로컬 상태, context, query 캐시로 표현할 수 없다.",
|
||||
"forbiddenWhen": ["store가 서버 응답 컬렉션을 복제하게 된다.", "상태 소유권을 문서로 정하기 전에 라이브러리를 고른다.", "Zustand와 Redux Toolkit을 둘 다 설치하게 된다."],
|
||||
"boundary": "workflow 전용 로컬 facade. vendor 타입은 그 adapter 안에 남는다",
|
||||
"port": "ClientWorkflowPort",
|
||||
"fake": "FakeClientWorkflowAdapter",
|
||||
"failureKinds": ["reset", "version-mismatch", "server-state-duplication"],
|
||||
"lifecycleMethods": ["unsubscribe", "reset"],
|
||||
"owner": "project-owner-required",
|
||||
"securityPrivacy": ["Persist only explicitly classified workflow fields.", "Never persist credentials.", "Define logout and version reset."],
|
||||
"securityPrivacy": ["명시적으로 분류한 workflow 필드만 저장한다.", "credential을 절대 저장하지 않는다.", "logout과 버전 변경 때의 초기화를 정한다."],
|
||||
"bundleBudgetGzipBytes": 9000,
|
||||
"fallback": "URL, component state, context and TanStack Query ownership.",
|
||||
"removal": ["Move remaining state to its natural owner.", "Remove facade and one selected store dependency.", "Verify logout/reset."],
|
||||
"fallback": "URL·component 상태·context·TanStack Query가 나눠 소유한다.",
|
||||
"removal": ["남은 상태를 원래 맞는 owner로 옮긴다.", "facade와, 고른 store 의존성 하나를 지운다.", "logout/reset을 확인한다."],
|
||||
"serverStatePolicy": "reference-only"
|
||||
},
|
||||
{
|
||||
"id": "large-data-ui",
|
||||
"status": "RECIPE_AVAILABLE",
|
||||
"trigger": "Production-like profiling proves a list or grid exceeds interaction and rendering budgets.",
|
||||
"forbiddenWhen": ["Pagination solves the scale requirement.", "Keyboard and screen-reader focus behavior is undefined."],
|
||||
"boundary": "presentation facade around virtualizer or data-grid behavior",
|
||||
"trigger": "production과 비슷한 프로파일링에서 목록이나 grid가 상호작용·렌더링 budget을 넘는다는 것이 확인되었다.",
|
||||
"forbiddenWhen": ["페이지 나누기(pagination)로 규모 요구를 풀 수 있다.", "키보드와 화면 낭독기(screen reader)의 focus 동작이 정해지지 않았다."],
|
||||
"boundary": "virtualizer나 data-grid 동작을 감싼 presentation facade",
|
||||
"port": "LargeDataUiFacade",
|
||||
"fake": "FakeLargeDataUiAdapter",
|
||||
"failureKinds": ["focus-loss", "stale-row", "scale-limit"],
|
||||
"lifecycleMethods": ["dispose-observers-if-installed"],
|
||||
"owner": "project-owner-required",
|
||||
"securityPrivacy": ["Render only authorized rows.", "Do not expose hidden row data to telemetry.", "Preserve accessible row identity."],
|
||||
"securityPrivacy": ["인가된 행만 렌더링한다.", "숨긴 행 데이터를 telemetry에 내보내지 않는다.", "접근성용 행 식별자를 유지한다."],
|
||||
"bundleBudgetGzipBytes": 30000,
|
||||
"fallback": "Accessible pagination and bounded result sets.",
|
||||
"removal": ["Restore paginated primitive.", "Remove facade adapter and dependency.", "Run keyboard and performance evidence."],
|
||||
"fallback": "접근성을 갖춘 pagination과 상한 있는 결과 집합.",
|
||||
"removal": ["pagination 기본 요소로 되돌린다.", "facade adapter와 의존성을 지운다.", "키보드·성능 검증을 돌린다."],
|
||||
"serverStatePolicy": "query-cache-owned"
|
||||
},
|
||||
{
|
||||
"id": "analytics-error-sink",
|
||||
"status": "RECIPE_AVAILABLE",
|
||||
"trigger": "A production provider, consent policy, retention owner and event registry are approved.",
|
||||
"forbiddenWhen": ["Consent and essential diagnostics are not separated.", "Arbitrary message or attribute keys can bypass redaction."],
|
||||
"boundary": "closed diagnostics/analytics port with provider adapter",
|
||||
"trigger": "production provider, 동의 정책, 보존 owner, 이벤트 registry가 승인되었다.",
|
||||
"forbiddenWhen": ["동의가 필요한 수집과 필수 진단이 나뉘어 있지 않다.", "임의의 메시지나 속성 키가 가림(redaction)을 우회할 수 있다."],
|
||||
"boundary": "provider adapter를 둔 닫힌(closed) 진단/분석 port",
|
||||
"port": "AnalyticsErrorSink",
|
||||
"fake": "RecordingAnalyticsAdapter",
|
||||
"failureKinds": ["consent-denied", "queue-full", "provider-unavailable"],
|
||||
"lifecycleMethods": ["flush", "dispose"],
|
||||
"owner": "project-owner-required",
|
||||
"securityPrivacy": ["Allowlist events and attributes.", "Redact before queueing.", "Apply consent, sampling and retention policy."],
|
||||
"securityPrivacy": ["이벤트와 속성을 허용 목록(allowlist)으로 관리한다.", "queue에 넣기 전에 가린다.", "동의·sampling·보존 정책을 적용한다."],
|
||||
"bundleBudgetGzipBytes": 25000,
|
||||
"fallback": "Existing bounded local diagnostics and best-effort telemetry port.",
|
||||
"removal": ["Disable provider delivery.", "Flush or discard by policy.", "Remove adapter, runtime config and dependency."],
|
||||
"fallback": "기존의 상한 있는 로컬 진단과 best-effort telemetry port.",
|
||||
"removal": ["provider 전송을 끈다.", "정책에 따라 flush하거나 버린다.", "adapter, runtime config, 의존성을 지운다."],
|
||||
"serverStatePolicy": "no-server-state"
|
||||
}
|
||||
]
|
||||
|
||||
@@ -114,12 +114,6 @@
|
||||
"readBy": "verify:documentation (FE-GATE-017), 사람",
|
||||
"sets": ["fixture-documents"]
|
||||
},
|
||||
{
|
||||
"path": "SPEC.md",
|
||||
"kind": "history",
|
||||
"role": "2026-09-25 라운드 요구사항. 문서 체계 작업(fe-b)이 이력 폴더로 옮기고 이 항목을 뺀다",
|
||||
"readBy": "사람"
|
||||
},
|
||||
{
|
||||
"path": "artifacts",
|
||||
"kind": "output",
|
||||
|
||||
@@ -2,41 +2,41 @@
|
||||
"schemaVersion": 1,
|
||||
"runbooks": {
|
||||
"FE-RB-001": {
|
||||
"title": "Boot configuration failure",
|
||||
"title": "boot 설정 실패",
|
||||
"gateId": "FE-GATE-021",
|
||||
"triggerKinds": ["BOOT_CONFIG_FAILURE"],
|
||||
"containment": "stop product route mount, show the safe support shell, and refetch at most once",
|
||||
"window": "owner triage planned-default 5m",
|
||||
"containment": "제품 route mount를 멈추고, 안전한 지원 셸을 보여 주고, 다시 가져오기는 최대 한 번만 한다",
|
||||
"window": "owner 분류(triage) 계획 기본값(planned-default) 5m",
|
||||
"escalation": ["env-config owner", "release owner"],
|
||||
"recoveryEvidence": [
|
||||
"clean-session boot",
|
||||
"product root mount",
|
||||
"config validation",
|
||||
"no repeated boot error"
|
||||
"깨끗한 세션에서 boot",
|
||||
"제품 root mount",
|
||||
"config 검증",
|
||||
"boot 오류 반복 없음"
|
||||
],
|
||||
"negativeFixture": "a valid config followed by an injected mount failure must fail recovery"
|
||||
"negativeFixture": "올바른 config 뒤에 mount 실패를 주입하면 복구가 실패해야 한다"
|
||||
},
|
||||
"FE-RB-002": {
|
||||
"title": "Chunk, manifest, or deployment mismatch",
|
||||
"title": "chunk·manifest·배포 불일치",
|
||||
"gateId": "FE-GATE-022",
|
||||
"triggerKinds": [
|
||||
"CHUNK_LOAD_FAILURE",
|
||||
"RELEASE_MANIFEST_FAILURE",
|
||||
"DEPLOY_MISMATCH"
|
||||
],
|
||||
"containment": "warn for dirty state, fetch manifest no-store once, and allow one guarded reload",
|
||||
"window": "release owner triage planned-default 5m",
|
||||
"containment": "저장하지 않은 상태(dirty state)가 있으면 경고하고, manifest를 no-store로 한 번 가져오고, 보호된 reload를 한 번만 허용한다",
|
||||
"window": "release owner 분류(triage) 계획 기본값(planned-default) 5m",
|
||||
"escalation": ["release-cache owner", "hosting/CDN owner"],
|
||||
"recoveryEvidence": [
|
||||
"entry and lazy assets reachable",
|
||||
"release tuple coherent",
|
||||
"second reload blocked",
|
||||
"critical route smoke"
|
||||
"entry asset과 lazy asset에 접근 가능",
|
||||
"release tuple 일치",
|
||||
"두 번째 reload 차단",
|
||||
"핵심 route smoke 시험"
|
||||
],
|
||||
"negativeFixture": "a second failure for the same release pair must not reload"
|
||||
"negativeFixture": "같은 release 쌍에서 두 번째 실패가 나면 reload하지 않아야 한다"
|
||||
},
|
||||
"FE-RB-003": {
|
||||
"title": "Backend API degradation",
|
||||
"title": "백엔드 API 저하",
|
||||
"gateId": "FE-GATE-023",
|
||||
"triggerKinds": [
|
||||
"TERMINAL_NETWORK_RATE",
|
||||
@@ -44,50 +44,50 @@
|
||||
"SERVER_FAILURE_RATE",
|
||||
"SCHEMA_MISMATCH"
|
||||
],
|
||||
"containment": "do not expand retry caps, serve safe stale reads, and never retry an unkeyed mutation",
|
||||
"window": "rolling 5m trigger; first classification planned-default 10m",
|
||||
"containment": "재시도 상한을 늘리지 않고, 안전한 오래된(stale) 읽기를 보여 주고, 키 없는 mutation은 절대 재시도하지 않는다",
|
||||
"window": "이동 구간(rolling) 5m trigger. 첫 분류 계획 기본값(planned-default) 10m",
|
||||
"escalation": [
|
||||
"api-client owner",
|
||||
"backend operation owner",
|
||||
"release compatibility owner"
|
||||
"백엔드 operation owner",
|
||||
"release 호환성 owner"
|
||||
],
|
||||
"recoveryEvidence": [
|
||||
"terminal failure rate at baseline",
|
||||
"no retry amplification",
|
||||
"critical read/write smoke",
|
||||
"schema fixtures"
|
||||
"최종(terminal) 실패율이 기준선 수준",
|
||||
"재시도 증폭 없음",
|
||||
"핵심 읽기/쓰기 smoke 시험",
|
||||
"스키마 fixture"
|
||||
],
|
||||
"negativeFixture": "an unkeyed POST receiving 503 must not retry"
|
||||
"negativeFixture": "키 없는 POST가 503을 받으면 재시도하지 않아야 한다"
|
||||
},
|
||||
"FE-RB-004": {
|
||||
"title": "Telemetry sink failure",
|
||||
"title": "telemetry sink 실패",
|
||||
"gateId": "FE-GATE-024",
|
||||
"triggerKinds": ["TELEMETRY_FAILURE"],
|
||||
"containment": "keep product flow available, bound the queue, and never report recursively to the failing sink",
|
||||
"window": "platform triage planned-default 15m",
|
||||
"escalation": ["observability owner", "telemetry platform owner"],
|
||||
"containment": "제품 흐름을 계속 쓸 수 있게 두고, queue에 상한을 두고, 실패하는 sink에 재귀로 보고하지 않는다",
|
||||
"window": "platform 분류(triage) 계획 기본값(planned-default) 15m",
|
||||
"escalation": ["관측(observability) owner", "telemetry platform owner"],
|
||||
"recoveryEvidence": [
|
||||
"product flow unaffected",
|
||||
"delivery self-check",
|
||||
"queue drained within bound",
|
||||
"forbidden attributes absent"
|
||||
"제품 흐름 영향 없음",
|
||||
"전송 자체 점검",
|
||||
"queue가 상한 안에서 비워짐",
|
||||
"금지 속성 없음"
|
||||
],
|
||||
"negativeFixture": "raw URL and query data must be removed from telemetry"
|
||||
"negativeFixture": "원본 URL과 query 데이터는 telemetry에서 지워져야 한다"
|
||||
},
|
||||
"FE-RB-005": {
|
||||
"title": "Coherent release rollback",
|
||||
"title": "일관된 release rollback",
|
||||
"gateId": "FE-GATE-025",
|
||||
"triggerKinds": ["RELEASE_BLOCKING_DEFECT"],
|
||||
"containment": "select a prior immutable tuple, verify asset/config/API compatibility, atomically switch, and smoke",
|
||||
"window": "provider recovery target TBD",
|
||||
"escalation": ["release-cache owner", "release approver/hosting owner"],
|
||||
"containment": "이전의 불변 tuple을 고르고, asset/config/API 호환성을 확인하고, 원자적으로 바꾸고, smoke 시험을 한다",
|
||||
"window": "provider 복구 목표 미정(TBD)",
|
||||
"escalation": ["release-cache owner", "release 승인자/hosting owner"],
|
||||
"recoveryEvidence": [
|
||||
"compatibility gate",
|
||||
"release coherence gate",
|
||||
"critical smoke",
|
||||
"release ID in incident timeline"
|
||||
"호환성 gate",
|
||||
"release 일관성 gate",
|
||||
"핵심 smoke 시험",
|
||||
"장애 타임라인에 release ID 기록"
|
||||
],
|
||||
"negativeFixture": "HTML build A with asset manifest B must be rejected"
|
||||
"negativeFixture": "HTML build A와 asset manifest B 조합은 거절되어야 한다"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -5,37 +5,37 @@
|
||||
"contextMaxFeatures": 200,
|
||||
"appMaxContexts": 20
|
||||
},
|
||||
"summary": "The ceilings bound the count; they are not a verified capacity. The practical limit of one app is the initial JavaScript budget, then typecheck memory. 400 features were not measured (D-18 makes it optional).",
|
||||
"summary": "상한은 개수를 제한할 뿐, 검증된 수용량이 아니다. 앱 하나의 실제 한계는 먼저 초기 JavaScript budget이고, 그다음 typecheck 메모리다. 400개 feature는 재지 않았다(D-18이 선택 사항으로 둔다).",
|
||||
"axes": [
|
||||
{
|
||||
"axis": "Typecheck of one app",
|
||||
"verified": "Linear, about 101k instantiations and 31 MB of tsc memory per feature, up to 100 features",
|
||||
"condition": "Copies of the feature create:feature writes with --with-create --keyed (2026-11-07; reference-sample copies before), tsconfig.app.json, the host recorded in the baseline",
|
||||
"notVerified": "200 features (one full context) and beyond; 4,000 (20 x 200) would need on the order of 125 GB by the same slope"
|
||||
"verified": "100개 feature까지 선형이다. feature 하나에 instantiation 약 101k, tsc 메모리 31 MB",
|
||||
"condition": "create:feature가 --with-create --keyed로 만드는 feature의 사본(2026-11-07부터. 그 전에는 참조 샘플 사본), tsconfig.app.json, 기준선에 기록된 host",
|
||||
"notVerified": "200개 feature(context 하나를 꽉 채운 수)와 그 이상. 같은 기울기라면 4,000개(20 x 200)에는 125 GB 규모가 필요하다"
|
||||
},
|
||||
{
|
||||
"axis": "Production build",
|
||||
"verified": "Completes at 100 features in seconds",
|
||||
"condition": "Same",
|
||||
"notVerified": "Beyond 100"
|
||||
"verified": "100개 feature에서 몇 초 안에 끝난다",
|
||||
"condition": "위와 같음",
|
||||
"notVerified": "100개 초과"
|
||||
},
|
||||
{
|
||||
"axis": "Initial JavaScript",
|
||||
"verified": "15-01: only each feature's declaration (route table, messages, invalidation identities) loads at boot; its runtime half loads with its routes. initialJavascript below is the current template build, which has no feature; what the first feature adds once (firstFeatureGzipBytes: the code every feature shares joins the initial chunks); what one more feature in an existing context adds (perFeatureGzipBytes); and what a second context adds (perContextGzipBytes). tests/unit/feature-shape-growth.test.ts measures them on every unit run, bounds a feature at 1 KiB and a context at 512 B, and fails when the record no longer matches the build. The 25- and 100-copy runs are in the baseline at its source commit (before 15-01: +3,922 B per copy)",
|
||||
"condition": "Same; the feature-declarations and feature-platform chunk groups in vite.config.ts",
|
||||
"notVerified": "How many features fit: the initial budget (config/performance/budgets.json) minus initialJavascript.gzipBytes and firstFeatureGzipBytes, divided by perFeatureGzipBytes (plus perContextGzipBytes per new context). The platform itself takes most of the budget"
|
||||
"verified": "15-01: boot 때는 각 feature의 선언(route 표, 메시지, 무효화 식별자)만 로드된다. runtime 쪽 절반은 그 feature의 route와 함께 로드된다. 아래 initialJavascript에는 네 가지가 있다. feature가 없는 지금 템플릿 빌드, 첫 feature가 한 번 더하는 크기(firstFeatureGzipBytes: 모든 feature가 함께 쓰는 코드가 초기 chunk에 들어간다), 기존 context에 feature 하나를 더할 때 늘어나는 크기(perFeatureGzipBytes), 두 번째 context가 더하는 크기(perContextGzipBytes)다. tests/unit/feature-shape-growth.test.ts가 unit 실행마다 이것을 잰다. feature 하나는 1 KiB, context 하나는 512 B로 제한하고, 기록이 빌드와 맞지 않으면 실패한다. 25개·100개 사본 측정은 source commit 시점의 기준선에 있다(15-01 전: 사본 하나당 +3,922 B)",
|
||||
"condition": "위와 같음. 여기에 vite.config.ts의 feature-declarations·feature-platform chunk 그룹",
|
||||
"notVerified": "feature가 몇 개 들어가는지. 초기 budget(config/performance/budgets.json)에서 initialJavascript.gzipBytes와 firstFeatureGzipBytes를 빼고 perFeatureGzipBytes로 나눈 값이다(새 context마다 perContextGzipBytes를 더한다). platform 자체가 budget 대부분을 쓴다"
|
||||
},
|
||||
{
|
||||
"axis": "Lazy JavaScript",
|
||||
"verified": "About 6.7 KB gzip and nine files per feature, every file far below the 120 KiB lazy-chunk budget",
|
||||
"condition": "Same",
|
||||
"notVerified": "Download cost of many lazy files"
|
||||
"verified": "feature 하나에 gzip 약 6.7 KB, 파일 9개. 모든 파일이 lazy chunk budget 120 KiB보다 훨씬 작다",
|
||||
"condition": "위와 같음",
|
||||
"notVerified": "lazy 파일이 많을 때의 다운로드 비용"
|
||||
},
|
||||
{
|
||||
"axis": "Routes",
|
||||
"verified": "3 per feature (list, detail, create), composed without conflict",
|
||||
"condition": "Same",
|
||||
"notVerified": "Router matching cost at runtime"
|
||||
"verified": "feature 하나에 3개(list, detail, create). 충돌 없이 조합된다",
|
||||
"condition": "위와 같음",
|
||||
"notVerified": "runtime의 router 매칭 비용"
|
||||
}
|
||||
],
|
||||
"initialJavascript": {
|
||||
|
||||
@@ -42,7 +42,7 @@
|
||||
"path": "tests/fixtures/security/secret-detection/allowed/test-credentials.ts",
|
||||
"ruleId": "assigned-secret",
|
||||
"owner": "frontend-platform",
|
||||
"reason": "Synthetic credential verifies the scoped test-only allowlist.",
|
||||
"reason": "합성한 credential로 범위가 정해진 테스트 전용 허용 목록(allowlist)을 검증한다.",
|
||||
"expiresAt": "2027-07-26T00:00:00.000Z"
|
||||
}
|
||||
]
|
||||
|
||||
+150
-79
@@ -1,114 +1,185 @@
|
||||
# 문서 색인
|
||||
# docs
|
||||
|
||||
`docs/`의 문서를 세 묶음으로 나눈다.
|
||||
저장소의 문서는 이 폴더 아래에 있다(루트 `README.md`, `CHANGELOG.md` 등 몇 개는 밖에 있다). 이 README는 두 가지를 정한다.
|
||||
|
||||
```text
|
||||
1. 현재 계약 지금 코드가 지키는 규칙. 게이트가 검사한다
|
||||
2. 목표 설계 앞으로의 설계와 결정. 구현됐다는 뜻이 아니다
|
||||
3. 작업 이력 리뷰·계획·작업 추적. 복사한 프로젝트는 지워도 된다
|
||||
```
|
||||
- 어떤 문서가 어느 폴더에 있나: 1절 「문서 지도」. 지금 있는 모든 문서 폴더를 덮는다.
|
||||
- 문서의 수명에 따라 무엇을 어떤 언어로 어떻게 고치나: 2절부터.
|
||||
|
||||
문서와 코드가 다르면 코드가 맞다. 목표 설계 문서에 적힌 기능이 지금 동작하는지는
|
||||
문서 안의 상태 값(`COMPOSED`, `AVAILABLE_NOT_COMPOSED`, `DESIGNED_NOT_IMPLEMENTED` 등)으로
|
||||
확인한다. 상태 값의 뜻은 `README.md`의 "Support scope" 절에 있다.
|
||||
규칙의 정본은 design-docs 저장소의 `conventions/docs-system.md`다. 이 README는 그 규칙을 이 repo에 적용한 내용이고, 이 템플릿을 복사한 프로젝트도 이 README를 따른다.
|
||||
파일 목록과 개수는 여기에 적지 않는다. 적으면 다음 문서가 더해지는 순간 틀린 글이 된다. 파일은 폴더를 직접 읽는다.
|
||||
|
||||
README와 입구 문서는 영어, recipe·ledger·스타일 문서는 한국어다.
|
||||
문서와 코드가 다르면 코드가 맞다.
|
||||
|
||||
## 1. 현재 계약
|
||||
## 1. 문서 지도
|
||||
|
||||
처음 읽을 입구 문서 6개다.
|
||||
- 표의 첫 칸이 폴더다(`docs/` 기준 경로).
|
||||
- 새 문서 폴더를 만들면 같은 변경에서 이 지도에 행을 더한다. 폴더를 지우거나 옮기면 그 행도 고친다.
|
||||
- 문서 검사의 `map`이 지도에 없는 폴더와, 지도에 있지만 없는 폴더를 막는다(5절).
|
||||
|
||||
### 처음 읽을 문서
|
||||
|
||||
| 문서 | 정하는 것 |
|
||||
|---|---|
|
||||
| [`README.md`](../README.md) | 시작, 런타임 설정과 배포 변수, 검증 명령, CI, 지원 범위, 원본 업데이트 반영 |
|
||||
| --- | --- |
|
||||
| [`../AGENTS.md`](../AGENTS.md) | 규칙의 정본과 지도: 꼭 지킬 것, 맡은 일마다 읽을 playbook, 검증 진입점 `scripts/verify.sh` |
|
||||
| [`work/`](work/), [`work/reference/`](work/reference/) | 작업 매뉴얼: 맡은 일마다의 playbook과 기준(완료 기준은 `work/improve.md` 5절) |
|
||||
| [`README.md`](../README.md) | 프로젝트 구조, 시작하기, 런타임 설정과 배포 변수, 기능 켜고 끄기와 지원 범위, 검증과 CI, 새 서비스로 시작하기, 원본 업데이트 반영 |
|
||||
| [`architecture/frontend-application-foundation.md`](architecture/frontend-application-foundation.md) | 이 repo의 역할(스타터 + 재사용 capability)과 기본·선택의 경계 |
|
||||
| [`architecture/layers.md`](architecture/layers.md), [`architecture/overview.md`](architecture/overview.md) | 계층과 import 방향. `check:architecture`가 검사한다 |
|
||||
| [`architecture/starter-experience.md`](architecture/starter-experience.md) | 기본 라우트, 인증 모드, 기능 추가·제거 절차 |
|
||||
| [`architecture/optional-adapter-recipes.md`](architecture/optional-adapter-recipes.md) | 선택 기능(recipe)을 넣고 빼는 절차 |
|
||||
| [`manual/`](manual/README.md) | 새 기능을 더하는 순서와 판단 기준, `create:feature`([`manual/reference/`](manual/reference/)) |
|
||||
| [`operations/ci-quality-gates.md`](operations/ci-quality-gates.md), [`testing/taxonomy.md`](testing/taxonomy.md) | 게이트, 테스트 계층, 새 프로젝트가 초기화할 기준선 |
|
||||
|
||||
입구 문서가 가리키는 세부 규칙:
|
||||
### 매뉴얼
|
||||
|
||||
- 새 기능 추가 매뉴얼(작업 순서, 단계별 판단 기준, `create:feature`): [`manual/`](manual/), [`manual/reference/`](manual/reference/). 한국어다
|
||||
- 루트 지침과 작업 매뉴얼(꼭 지킬 것·지도·검증 진입점 `scripts/verify.sh`, 맡은 일마다의 playbook과 기준): [`../AGENTS.md`](../AGENTS.md), [`work/`](work/), [`work/reference/`](work/reference/). 한국어다
|
||||
- 규모 설계(구조·소유·실행·트래픽·오류·검증·텔레메트리·릴리스 일관성)와 코드 주석 `scale-architecture.md §N`의 근거: [`architecture/scale-architecture.md`](architecture/scale-architecture.md). 절마다 현재 계약인지 기록만인지 머리말 표에 적었다
|
||||
- 계약 소유와 호환성: [`architecture/contract-ownership.md`](architecture/contract-ownership.md), [`contracts/compatibility.md`](contracts/compatibility.md)
|
||||
- 짝 백엔드 Envelope 판정과 쓰기 전 거절 표(지금 실행 규칙, `src/adapters/http/backend-envelope.ts`의 근거): [`architecture/backend-api-and-server-state-contract.md`](architecture/backend-api-and-server-state-contract.md) 4.1·6·6.1절. 기준 커밋은 [`../config/contracts/backend-contract-pin.json`](../config/contracts/backend-contract-pin.json). 같은 문서의 나머지 절은 목표 설계다
|
||||
- 정적 배포와 런타임 설정: [`architecture/static-delivery.md`](architecture/static-delivery.md)
|
||||
- 기능 개발자가 알아야 하는 양: [`architecture/capability-consumer-experience.md`](architecture/capability-consumer-experience.md)
|
||||
- 운영·복구: [`operations/`](operations/), [`runbooks/`](runbooks/)
|
||||
- 보안과 공급망: [`security/browser-boundary.md`](security/browser-boundary.md), [`security/supply-chain.md`](security/supply-chain.md)
|
||||
- 디자인 토큰과 수동 접근성 검토: [`styling/design-tokens.md`](styling/design-tokens.md), [`accessibility/manual-checklist.md`](accessibility/manual-checklist.md)
|
||||
- 버전별 변경: [`../CHANGELOG.md`](../CHANGELOG.md)
|
||||
일하는 순서와 판단 지점이다. 사람과 AI 세션이 같이 쓴다.
|
||||
|
||||
`verify:documentation`은 이 파일과 이 절에서 링크한 문서(폴더 링크는 그 안의 `.md` 전부)에
|
||||
적힌 repo 경로·링크·package script·FE-GATE ID가 실제로 있는지 검사한다. 명령(인라인 코드와
|
||||
셸 코드 블록) 안의 경로 인자도 본다. 짝 백엔드 템플릿(`clean-architecture-backend-template`)의
|
||||
경로와 링크는 `config/contracts/backend-contract-pin.json`이 고정한 커밋의 트리에서 찾는다.
|
||||
이 checkout 옆에 있는 짝 checkout의 git 기록을 읽고, 그 작업 트리와 HEAD는 보지 않는다. 짝
|
||||
checkout이 없거나 그 커밋이 없으면 실패 대신 확인하지 못한 것으로 출력과
|
||||
`artifacts/quality/documentation-review.json`에 남긴다. repo 밖으로 나가는 링크가 짝 저장소를
|
||||
가리키지 않으면(저장소 이름 오타 포함) 실패한다. `CHANGELOG.md`는
|
||||
지난 상태를 적는 문서라 빼고, git이 무시하는 생성 산출물과 복사한 프로젝트가 지운 작업 이력은
|
||||
없어도 된다. 설명·수치가 코드와 맞는지는 검사하지 않는다. 규칙과 예외의 정본은
|
||||
`scripts/verify-documentation-readiness.ts`다.
|
||||
프로젝트가 지울 예정인 샘플 기능(목록은 `scripts/lib/removable-template-features.ts`, 템플릿은
|
||||
비어 있다)의 경로와 script는 그 기능이 설치돼 있을 때(`src/features/<id>/feature-module.ts`가
|
||||
있을 때) 검사하고, 지운 뒤에는 없어도 된다.
|
||||
| 폴더 | 무엇 |
|
||||
| --- | --- |
|
||||
| `work/` | 작업 매뉴얼: 새 기능, 리뷰·수정·리팩터링, 조사·설계, 문서, 운영, 일 나누기의 playbook. `work/reference/`에 게이트·구조·테스트·리뷰 기준과 결정 색인, `work/evidence.md`에 매뉴얼 규칙의 근거 기록 |
|
||||
| `manual/` | 개발 매뉴얼: 새 기능 하나를 더하는 0~11단계, 결정표, 기능 폴더 밖 파일, 짝 백엔드에 붙이기. `manual/reference/`에 명령 인자, 전역 ID, 패턴, 오류 메시지 |
|
||||
| `ledger/` | 작업 예측·실측 장부(`ledger/estimates.jsonl`, 형식은 `ledger/README.md`) |
|
||||
|
||||
게이트가 직접 읽는 파일이라 지우거나 옮기면 게이트가 실패한다.
|
||||
### 현재 계약
|
||||
|
||||
지금 코드가 지키는 규칙이다. 코드와 같은 변경에서 고친다.
|
||||
|
||||
| 폴더 | 무엇 |
|
||||
| --- | --- |
|
||||
| `architecture/` | 계층과 import 규칙(`architecture/layers.md`), 플랫폼의 역할, 스타터, recipe 절차, 정적 배포, 계약 소유, 규모 설계(`architecture/scale-architecture.md`, 코드 주석의 `scale-architecture.md §N`이 가리킨다), 짝 백엔드 계약(`architecture/backend-api-and-server-state-contract.md` 4.1·6·6.1절이 실행 규칙. 기준 커밋은 `config/contracts/backend-contract-pin.json`), 2026-07-18 도식 리뷰 기록의 사본(`architecture/review-evidence.md`, `architecture/review-ledger.json`) |
|
||||
| `contracts/` | 계약 호환 규칙(읽는 쪽을 먼저 배포한다) |
|
||||
| `security/` | 브라우저 보안 경계와 공급망 |
|
||||
| `styling/` | 디자인 토큰 |
|
||||
| `accessibility/` | 수동 접근성 검토 체크리스트와 라우트별 검토 기록(`accessibility/route-reviews/`) |
|
||||
| `testing/` | 테스트 계층(taxonomy)과 새 프로젝트가 초기화할 기준선 |
|
||||
|
||||
### 운영
|
||||
|
||||
| 폴더 | 무엇 |
|
||||
| --- | --- |
|
||||
| `operations/` | CI 품질 게이트, capability별 복구 절차, 릴리스·캐시 롤백, 성능 증거, 2026-08-14 adapter 재검토의 처리 원장(`operations/adapter-remediation-ledger.md`) |
|
||||
| `runbooks/` | 오류 code별 장애 대응 runbook(`FE-RB-00N`). 등록은 `config/runbooks/runbooks.json` |
|
||||
|
||||
### 결정 기록
|
||||
|
||||
| 폴더 | 무엇 |
|
||||
| --- | --- |
|
||||
| `adr/` | 결정 기록(VD). 번호는 옮기기 전과 같다(`VD-NN-<주제>.md`). 2026-11-08에 architecture 아래 decisions 폴더에서 옮겼다 |
|
||||
|
||||
### 설계와 기록
|
||||
|
||||
설계서와 기록은 쓴 때의 글이다. 지금 동작을 설명하지 않는다. 그래서 살아 있는 문서와 다른 폴더에 둔다.
|
||||
|
||||
| 폴더 | 무엇 |
|
||||
| --- | --- |
|
||||
| `design/` | 설계서. `YYYY-MM-DD-<주제>-design.md`. 2026-11-08에 옛 superpowers 폴더의 specs와 `architecture/`의 목표 설계를 옮겼다 |
|
||||
| `history/plans/` | 계획서. 2026-09-25 리뷰 수정 라운드의 요구사항(`SPEC.md`)과 작업 목록도 여기 있다 |
|
||||
| `history/evidence/` | 작업 단계의 증거·체크포인트 |
|
||||
| `reviews/` | 리뷰 결과. 라운드마다 폴더 하나(README가 결정과 남은 것을 적는다) 또는 리뷰 문서 하나. 리뷰 가이드와 실행 체크리스트는 design-docs 저장소로 옮겼고, 여기에는 정본 위치를 알려 주는 포인터 둘이 있다 |
|
||||
|
||||
- 계획서 본문에는 그때 계획한 경로와 명령이 그대로 남아 있다. 계획서를 나중에 고치지 않는 이유는, 고치면 계획의 기록이 아니라 결과를 계획처럼 보이게 만든 글이 되기 때문이다.
|
||||
- `history/`와 `reviews/`는 복사한 프로젝트가 지워도 된다(루트 `README.md` 「복사한 뒤 지워도 되는 것」). 예외는 `reviews/adapters/`다: `reviews/adapters/INVENTORY.md`는 `check:adapter-inventory`(FE-GATE-010)가 `src/adapters`와 대조하는 살아 있는 목록이다.
|
||||
- `design/`과 `adr/`은 코드 주석이 근거로 가리키므로 지우지 않는다.
|
||||
|
||||
### 폴더 밖 문서
|
||||
|
||||
| 문서 | 무엇 |
|
||||
| --- | --- |
|
||||
| [`../README.md`](../README.md) | 루트 README. 6절의 필수 절을 가진다 |
|
||||
| [`../CHANGELOG.md`](../CHANGELOG.md) | 템플릿 버전 사이의 변경. 지난 상태를 적는 문서라 문서 검사의 참조·숫자 검사는 보지 않는다 |
|
||||
| [`../AGENTS.md`](../AGENTS.md) | 규칙의 정본과 지도. `src/` 계층 폴더마다 지역 규칙 `AGENTS.md`가 있다 |
|
||||
| 루트 `CLAUDE.md` | `AGENTS.md`를 가져오고 Claude Code 전용 줄만 둔다. 경로별 규칙·스킬·서브에이전트는 `.claude/` |
|
||||
| [`vision.md`](vision.md), [`problem-statement.md`](problem-statement.md) | 비전과 문제 정의. 소유자가 채우는 양식이다 |
|
||||
| 루트 `PRODUCT.md` | 디자인 도구가 읽는 제품 맥락 |
|
||||
| [`../src/adapters/browser-transfer/image-cdn/README.md`](../src/adapters/browser-transfer/image-cdn/README.md) | Image CDN adapter의 모듈 README |
|
||||
|
||||
### 게이트가 읽는 파일
|
||||
|
||||
지우거나 옮기면 게이트가 실패한다.
|
||||
|
||||
| 파일 | 읽는 명령 |
|
||||
|---|---|
|
||||
| --- | --- |
|
||||
| 이 파일, `architecture/review-ledger.json`, `architecture/review-evidence.md` | `verify:documentation` (FE-GATE-017) |
|
||||
| `docs/accessibility/route-reviews/` 라우트별 기록 | `verify:documentation` (FE-GATE-017), `review:a11y-manual` (FE-GATE-009, FE-GATE-028) |
|
||||
| 라우트별 수동 접근성 기록(`accessibility/route-reviews/<ROUTE_ID>.md`) | `verify:documentation` (FE-GATE-017), `review:a11y-manual` (FE-GATE-009, FE-GATE-028) |
|
||||
| `reviews/adapters/INVENTORY.md` | `check:adapter-inventory` (FE-GATE-010) |
|
||||
| `operations/adapter-remediation-ledger.md`, `operations/adapter-remediation-dispositions.json` | `check:remediation-ledger` (게이트 밖. 이유는 `config/ci/ungated-scripts.json`) |
|
||||
| `architecture/backend-api-and-server-state-contract.md` 6.1절 표 | `tests/unit/backend-contract-pin-document.test.ts` (FE-GATE-005) |
|
||||
| `architecture/starter-experience.md`의 기능 폴더 밖 파일 표, `manual/03-outside-feature-folder.md` A절 | `tests/unit/feature-tracked-files.test.ts` (FE-GATE-005) |
|
||||
| `manual/`의 표시한 코드 블록과 `manual/04-paired-backend-session.md` 3.2절 | `tests/unit/manual-code-blocks.test.ts`, `tests/unit/manual-paired-backend-settings.test.ts` (FE-GATE-005) |
|
||||
|
||||
## 2. 목표 설계
|
||||
## 2. 문서 수명과 언어
|
||||
|
||||
설계와 결정 기록이다. 구현된 부분과 계획이 한 문서에 섞여 있다. 행마다 상태 값을 본다.
|
||||
| 수명 | 문서 | 위치 | 언어 | 고치는 법 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 살아 있음 | README, `AGENTS.md`(루트와 `src/` 계층 폴더), `CLAUDE.md`, `.claude/`의 규칙·스킬, 매뉴얼(`work/`, `manual/`), 장부(`ledger/`), `vision.md`·`problem-statement.md`, 현재 계약(`architecture/`, `contracts/`, `security/`, `styling/`, `accessibility/`, `testing/`), 운영(`operations/`, `runbooks/`), `reviews/adapters/INVENTORY.md`, 모듈 README, `CHANGELOG.md` | 제자리 | 한국어 | 코드와 같은 변경에서 고친다(4절) |
|
||||
| 결정 | 결정 기록(VD) | `adr/` | 한국어 | 본문은 고치지 않는다. 일부가 바뀌면 상태를 「채택(보완)」으로 하고 맨 아래에 날짜가 있는 「보완」 절을 덧붙인다. 크게 바뀌면 새 VD를 쓰고 옛 VD를 「대체됨」으로 한다 |
|
||||
| 기록 | 설계서, 계획서, 증거, 리뷰 | `design/`, `history/`, `reviews/` | 머리 블록은 한국어, 본문은 쓴 때의 원문 | 머리 블록의 칸만 고친다 |
|
||||
|
||||
- 런타임 capability 결정의 정본: [`architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md`](architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md)
|
||||
- 상태 원장: [`architecture/browser-data-capability-completion-ledger.md`](architecture/browser-data-capability-completion-ledger.md)
|
||||
- 전체 검토와 로드맵: [`architecture/frontend-platform-capability-review.md`](architecture/frontend-platform-capability-review.md), [`architecture/frontend-platform-implementation-roadmap.md`](architecture/frontend-platform-implementation-roadmap.md)
|
||||
- 포트·경계·데이터 흐름: [`architecture/frontend-ports-adapters-and-boundaries.md`](architecture/frontend-ports-adapters-and-boundaries.md), [`architecture/typescript-state-and-data-flow.md`](architecture/typescript-state-and-data-flow.md), [`architecture/routing-pages-and-patterns.md`](architecture/routing-pages-and-patterns.md)
|
||||
- API와 서버 상태: [`architecture/api-contract-schema-mapper-and-server-state.md`](architecture/api-contract-schema-mapper-and-server-state.md), [`architecture/backend-api-and-server-state-contract.md`](architecture/backend-api-and-server-state-contract.md), [`architecture/protobuf-browser-transport-and-rest-gateway.md`](architecture/protobuf-browser-transport-and-rest-gateway.md)
|
||||
- 브라우저 데이터: [`architecture/client-cache-and-storage.md`](architecture/client-cache-and-storage.md), [`architecture/browser-file-and-origin-storage.md`](architecture/browser-file-and-origin-storage.md), [`architecture/presigned-transfer-and-image-cdn.md`](architecture/presigned-transfer-and-image-cdn.md), [`architecture/server-file-capability-infrastructure.md`](architecture/server-file-capability-infrastructure.md)
|
||||
- 실시간: [`architecture/realtime-events-web-push-and-bounded-polling.md`](architecture/realtime-events-web-push-and-bounded-polling.md)
|
||||
- 디자인 시스템과 테스트 전략: [`styling/design-system-platform.md`](styling/design-system-platform.md), [`testing/frontend-platform-testing-strategy.md`](testing/frontend-platform-testing-strategy.md)
|
||||
- 결정 기록(ADR): [`architecture/decisions/`](architecture/decisions/) `VD-*.md`
|
||||
- 살아 있는 문서와 결정 기록의 본문은 한국어로 쓴다. 설정 파일의 사람이 읽는 설명 칸(recipe 카탈로그, runbook 등록)도 한국어다.
|
||||
- 원문으로 두는 것: 코드 식별자, 명령, 경로, 설정 키, 오류 코드, 로그·출력 인용, 외부 문서 인용, 제품 이름.
|
||||
- 용어는 자연스러운 한국어 → 한국어(영어) → 영어 그대로 순으로 고른다. 처음 나올 때 한 번 병기한다. 이 repo가 영어로 쓰는 말(adapter, port, capability, recipe, feature, context, slice, registry, gate 등)은 영어로 둔다.
|
||||
- 문체는 「~한다」다. 한 문서 안에서 「~합니다」와 섞지 않는다.
|
||||
- 2026-11-08에 살아 있는 문서를 모두 한국어로 옮겼다. 문서 검사의 예외 목록은 비어 있다(5절).
|
||||
- `accessibility/route-reviews/`의 라우트별 기록은 문서가 아니라 정해진 영어 키 형식의 게이트 입력이다(`scripts/lib/manual-a11y-evidence.ts`). 문서 검사가 보지 않는다.
|
||||
|
||||
## 3. 작업 이력·리뷰
|
||||
## 3. 기록 문서의 머리 블록
|
||||
|
||||
템플릿을 만들면서 쓴 계획, 리뷰, 작업 추적이다. 현재 계약이 아니다.
|
||||
복사한 프로젝트는 지워도 된다. 지울 때 남길 파일은 `README.md`의
|
||||
"Files you can delete after copying" 절에 있다.
|
||||
|
||||
| 경로 | 내용 |
|
||||
|---|---|
|
||||
| [`superpowers/`](superpowers/) | 과거 작업 계획과 스펙 |
|
||||
| [`reviews/`](reviews/) | 리뷰 결과. 리뷰 가이드와 실행 체크리스트는 2026-11-06에 design-docs 저장소로 옮겼고, 여기에는 정본 위치를 알려 주는 포인터 두 개만 있다. `reviews/adapters/INVENTORY.md`만 게이트가 읽는다. `reviews/adapters/`는 지우지 않는다: INVENTORY의 행과 `operations/adapter-remediation-ledger.md`가 그 안의 리뷰로 링크한다 |
|
||||
| [`history/`](history/) | 끝난 작업의 계획서(`history/plans/`)와 증거(`history/evidence/`). 파일마다 맨 위에 머리 블록이 있다(아래 4절). 2026-11-07에 루트에서 옮겼다: `tasks/` → `history/plans/2026-09-25-review-fix-round/`, `.superpowers/sdd/2026-08-01-runtime-correctness-remediation/` → `history/evidence/2026-08-01-runtime-correctness-remediation/`. 그때의 기록 문서(`superpowers/plans/`, `reviews/2026-09-25-maturity-review/`, 루트 `SPEC.md`)는 옛 경로로 가리킨다. 기록이라 고치지 않는다 |
|
||||
| [`../SPEC.md`](../SPEC.md) | 2026-09-25 리뷰 수정 라운드의 요구사항. 그 라운드는 0.2.0(`CHANGELOG.md`)으로 끝났다. 27~37줄 「공통 완료 기준」을 작업 매뉴얼로 옮긴 뒤 같은 라운드의 계획서 옆(`history/plans/2026-09-25-review-fix-round/`)으로 옮긴다 |
|
||||
|
||||
## 4. 기록 문서의 머리 블록
|
||||
|
||||
`history/` 아래 `.md` 파일은 맨 위에 이 블록을 둔다. 블록을 빼면 쓴 때의 원문이다. 본문은
|
||||
고치지 않고 블록의 칸만 고친다. 형식의 정본은 design-docs 저장소의
|
||||
`conventions/docs-system.md` 4절이다.
|
||||
`design/`, `history/`, `adr/`의 `.md` 파일은 맨 위에 이 블록을 둔다. 블록을 빼면 원문 그대로다(옮길 때 깨진 상대 링크의 대상만 고쳤다).
|
||||
|
||||
```text
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 계획서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 끝남
|
||||
- 작성일: 2026-09-25
|
||||
- 상태: 구현됨
|
||||
- 작성일: 2026-08-01
|
||||
- 요약: 한국어 한 문장
|
||||
- 현재 정본: 지금 동작을 설명하는 문서나 코드의 경로. 없으면 「없음 — 이유」
|
||||
- 현재 정본: `docs/architecture/layers.md`
|
||||
- 대체됨: `docs/design/<대체한 문서>.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
```
|
||||
|
||||
- 종류는 폴더가 정하고 둘째 줄에 굵게 적는다: `history/plans/` 계획서, `history/evidence/` 증거.
|
||||
- 상태: 계획서는 실행 중 · 끝남 · 중단 · 대체됨 · 확인 안 함, 증거는 보관.
|
||||
- 종류는 폴더가 정하고 둘째 줄에 굵게 적는다: `design/` 설계서, `history/plans/` 계획서, `history/evidence/` 증거. 결정 기록(`adr/`)의 둘째 줄은 `> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.`다. VD는 처음부터 한국어로 썼고 번역하지 않았다. 나중에 본문을 번역하면 「원문이다」 대신 「내용이다(번역은 뜻을 바꾸지 않았다)」로 쓴다.
|
||||
- 상태는 종류마다 고정 어휘다.
|
||||
|
||||
| 종류 | 상태 |
|
||||
| --- | --- |
|
||||
| 설계서 | 제안 · 채택 · 구현됨 · 보류 · 폐기 · 대체됨 · 확인 안 함 |
|
||||
| 결정 기록 | 제안 · 채택 · 채택(보완) · 폐기 · 대체됨 |
|
||||
| 계획서 | 실행 중 · 끝남 · 중단 · 대체됨 · 확인 안 함 |
|
||||
| 증거 | 보관 |
|
||||
|
||||
- 「현재 정본」은 지금 동작을 설명하는 살아 있는 문서나 코드의 경로다. 여럿이면 쉼표로 잇고, 없으면 「없음 — 이유」로 쓴다.
|
||||
- 「대체됨」은 상태가 대체됨일 때 대체한 문서의 경로다. 이 문서가 다른 문서를 대체했으면 「대체」 칸에 그 경로를 쓴다.
|
||||
- 상태는 그 결정을 바꾼 변경이 같이 바꾼다. 기능을 지우는 커밋이 그 기능의 설계서를 「폐기」나 「대체됨」으로 바꾼다. 새 설계서·결정 기록은 처음부터 블록을 달고 쓴다(보통 「제안」).
|
||||
- 2026-11-08에 처음 단 상태는 원래 상태 줄을 기계로 바꾼 값이다: Accepted·Approved·확정·승인·정본 → 채택, Superseded → 대체됨, Proposed → 제안, implemented → 구현됨, 날짜가 붙은 보완 메모가 본문에 있는 VD → 채택(보완). 상태 줄이 없던 설계서와 체크 상자가 모두 표시되지 않은 계획서는 「확인 안 함」이다.
|
||||
- `.md`가 아닌 파일(레인 준비 셸 스크립트)에는 달지 않는다. 같은 폴더 문서의 블록이 그 파일을 설명한다.
|
||||
- 리뷰(`reviews/`)는 아직 머리 블록을 요구하지 않는다.
|
||||
|
||||
## 4. 문서와 코드를 같은 변경에서 고친다
|
||||
|
||||
- 코드나 규칙을 바꾸는 변경이 그것을 설명하는 살아 있는 문서도 고친다. 찾는 법: `git grep -n '<바꾼 이름>' -- '*.md'`.
|
||||
- 살아 있는 문서는 지금 있는 것만 쓴다. 지운 타입·경로·명령은 `CHANGELOG.md`에 쓴다. 살아 있는 문서 안에서 꼭 써야 하면 `> 이력` 으로 시작하는 인용 블록 안에 쓴다. 문서 검사는 그 블록의 문체를 보지 않는다.
|
||||
- 숫자·버전을 복사하지 않는다. 프레임워크 버전은 `package.json`과 `.nvmrc`, 게이트 목록은 `config/ci/gates.json`, recipe 목록은 `config/recipes/frontend-capability-recipes.json`, adapter 파일 목록은 `reviews/adapters/INVENTORY.md`를 가리킨다.
|
||||
- 루트 README는 「프로젝트 구조」와 「문서 지도」 절을 반드시 둔다. 전체 절 목록과 순서의 정본은 design-docs `conventions/docs-system.md` 6.1절이고, 문서 검사의 `readme`가 그 목록(`scripts/lib/docs-system.ts`의 `README_SECTIONS`)을 본다.
|
||||
|
||||
## 5. 문서 검사
|
||||
|
||||
`verify:documentation`(FE-GATE-017)이 위 규칙 중 기계로 볼 수 있는 것을 본다. 하나라도 걸리면 실패한다. 경로 필터가 없다: 코드에서 파일이나 script를 지우는 변경이 그 변경과 상관없는 문서를 낡게 만든다.
|
||||
|
||||
- pull request에서 실패하게 하는 곳은 merge 단계 FE-GATE-005다. 그 안의 `tests/unit/documentation-readiness.test.ts`가 이 repo를 그대로 두고 `verify:documentation`을 한 번 돌린다. FE-GATE-017 job 자체는 documentation 단계를 고른 workflow_dispatch에서만 돈다(`config/ci/gates.json`의 `documentation_gate`).
|
||||
|
||||
| 검사 | 보는 것 |
|
||||
| --- | --- |
|
||||
| `language` | 살아 있는 문서와 결정 기록 본문이 한국어인가. 코드·명령·경로·링크·인용은 세지 않고, 영어 낱말 3개 이상이면서 한글 덩어리 비율 0.3 미만이면 영어다(보고 언어 훅 H11과 같은 판정) |
|
||||
| `head` | 기록과 결정 기록 맨 위의 머리 블록: 칸, 상태 어휘, 날짜, 한국어 요약, 현재 정본·대체됨 경로가 지금 있는지 |
|
||||
| `document references` | 살아 있는 문서의 인라인 코드·셸 코드 블록 안 repo 경로, 마크다운 링크 대상, package script 이름, FE-GATE ID가 지금 있는가. 짝 백엔드 경로는 `config/contracts/backend-contract-pin.json`이 고정한 커밋의 트리에서 찾는다 |
|
||||
| `number` | 살아 있는 문서가 프레임워크 버전이나 게이트·recipe·adapter 개수를 복사했는가. 결정 기록, 기록, `CHANGELOG.md`는 보지 않는다 |
|
||||
| `map` | 이 README의 1절 지도가 `docs/` 아래 모든 폴더를 덮는가(표 첫 칸의 `폴더/`). 파일 없이 폴더만 가진 묶음 폴더(`history/`)는 그 바로 아래 폴더가 대신한다. 지도에 있지만 없는 폴더도 실패다 |
|
||||
| `readme` | 루트 README가 첫 줄 제목, 그 아래 한 문단, 정해진 `##` 절을 정해진 순서로 가지는가 |
|
||||
| `style` | 살아 있는 문서와 결정 기록의 문장 끝이 높임(「~합니다」「~하세요」)이 아닌가. 코드, 따옴표·낫표 안 인용, `> 이력` 블록은 보지 않는다 |
|
||||
|
||||
- 그 밖에 같은 명령이 루트 README의 런타임 변수 표, 입구 문서의 `src/` 폴더 설명(`architecture/layers.md` 표와 글자가 같아야 한다), 수동 접근성 기록의 범위, 2026-07-18 도식 리뷰 사본 둘의 일치를 본다.
|
||||
- 규칙과 판정의 정본은 `scripts/lib/docs-system.ts`(검사 여섯)와 `scripts/verify-documentation-readiness.ts`(참조와 그 밖의 검사)다. 백엔드 템플릿의 문서 검사기(그 repo의 `check-docs.py`)를 같은 이름·문턱으로 옮긴 것이다.
|
||||
- 검사 자신의 시험: `tests/unit/docs-system.test.ts`, `tests/unit/documentation-readiness.test.ts`.
|
||||
- 예외 목록 `scripts/docs-system-exceptions.txt`는 비어 있고 줄기만 한다. 목록에 새 줄을 더하면 실패한다(줄마다 `scripts/lib/docs-system.ts`의 `FROZEN`에 지문이 있어야 하는데, `FROZEN`이 비어 있다). 기준선을 늘리는 것은 규칙을 바꾸는 일이라 소유자 결정이 필요하다.
|
||||
- 복사한 프로젝트가 지운 기록(`history/`, `reviews/`)과 지운 샘플 기능의 경로는 없어도 된다. git이 무시하는 생성 산출물도 없어도 된다.
|
||||
- 설명·수치가 코드와 맞는지는 검사하지 않는다. 리뷰가 표본으로 대조한다.
|
||||
|
||||
@@ -1,31 +1,31 @@
|
||||
# Manual accessibility review checklist
|
||||
# 수동 접근성 리뷰 체크리스트
|
||||
|
||||
Automated axe checks do not establish WCAG conformance. A human reviewer must
|
||||
review every route record in `docs/accessibility/route-reviews/` against one
|
||||
release candidate and sign them. The required scope is the route registry
|
||||
(`ROUTE_REGISTRY` in `src/features/installed-feature-contracts.ts`): one
|
||||
record per route, named `<ROUTE_ID>.md`. Copy the template fields exactly; the
|
||||
gate rejects blank identity/timestamp/signature fields, pending verdicts,
|
||||
mismatched release IDs, or missing routes.
|
||||
자동 axe 검사만으로는 WCAG 준수를 증명하지 못한다. 사람 리뷰어가
|
||||
`docs/accessibility/route-reviews/`의 route 기록을 모두 한 release 후보에 대해
|
||||
리뷰하고 서명해야 한다. 필요한 범위는 route
|
||||
registry(`src/features/installed-feature-contracts.ts`의 `ROUTE_REGISTRY`)다.
|
||||
route 하나에 기록 하나를 두고, 이름은 `<ROUTE_ID>.md`로 한다. template 필드를
|
||||
그대로 복사한다. gate는 다음을 거부한다: 비어 있는 신원·시각·서명 필드, 아직
|
||||
정하지 않은(pending) 판정, 맞지 않는 release ID, 빠진 route.
|
||||
|
||||
The signed review is the release gate FE-GATE-028 (`review:a11y-manual`), so
|
||||
it is required once per release candidate, not on every merge. The merge gate
|
||||
FE-GATE-009 runs `review:a11y-manual -- --format-only`: each record must keep
|
||||
the fields below with `pending`, `pass` or `not-applicable (<reason>)` verdicts,
|
||||
and a record marked `reviewed` must be complete.
|
||||
서명된 리뷰는 release gate FE-GATE-028(`review:a11y-manual`)이다. 그래서
|
||||
merge마다가 아니라 release 후보마다 한 번 필요하다. merge gate FE-GATE-009는
|
||||
`review:a11y-manual -- --format-only`를 돌린다. 각 기록은 아래 필드를 유지하고
|
||||
판정 값은 `pending`, `pass`, `not-applicable (<reason>)` 중 하나여야 한다.
|
||||
`reviewed`로 표시한 기록은 빠짐없이 채워져 있어야 한다.
|
||||
|
||||
This document keeps no route list. A list here once said six routes while ten
|
||||
were registered, and keeping it current made every new feature edit this file.
|
||||
Instead `verify:documentation` fails, naming the route ID, when a registered
|
||||
route has no record file. A new route starts from a copy of a pending record
|
||||
with its title and `Route ID` changed.
|
||||
이 문서에는 route 목록을 두지 않는다. 예전에 여기 목록이 route 6개라고 적었을 때
|
||||
실제로는 10개가 등록돼 있었다. 그리고 목록을 최신으로 유지하느라 새 feature마다
|
||||
이 파일을 고쳐야 했다. 대신 등록된 route에 기록 파일이 없으면
|
||||
`verify:documentation`이 그 route ID를 밝히며 실패한다. 새 route는 pending 기록
|
||||
하나를 복사하고 제목과 `Route ID`만 바꿔서 시작한다.
|
||||
|
||||
Allowed item verdicts:
|
||||
항목에 쓸 수 있는 판정:
|
||||
|
||||
- `pass`
|
||||
- `not-applicable (<specific reason>)`
|
||||
|
||||
Required record:
|
||||
필수 기록:
|
||||
|
||||
```text
|
||||
Status: reviewed
|
||||
@@ -46,39 +46,37 @@ Screen reader: pass
|
||||
Notes: <observations and linked defect IDs>
|
||||
```
|
||||
|
||||
The reviewer must verify:
|
||||
리뷰어가 확인해야 할 것:
|
||||
|
||||
- M1: every action works without a pointing device
|
||||
- M2: every focused element has a visible indicator
|
||||
- M3: route transitions move focus to a deterministic target
|
||||
- M4: modal focus is trapped and restored, when a modal exists
|
||||
- M5: errors are programmatically associated with their controls, when present
|
||||
- M6: state never relies on color alone
|
||||
- M7: non-essential motion is suppressed with reduced-motion preference
|
||||
- Screen reader: headings, live regions, errors, and actions are announced once
|
||||
- M1: 모든 동작이 포인팅 장치 없이 된다
|
||||
- M2: focus를 받은 모든 요소에 눈에 보이는 표시가 있다
|
||||
- M3: route가 바뀌면 focus가 정해진 대상으로 옮겨 간다
|
||||
- M4: modal이 있으면 focus가 modal 안에 갇히고, 닫으면 원래 자리로 돌아간다
|
||||
- M5: 오류가 있으면 해당 입력 요소와 프로그램으로 연결돼 있다
|
||||
- M6: 상태를 색으로만 나타내지 않는다
|
||||
- M7: 동작 줄이기(reduced-motion) 설정이 켜지면 꼭 필요하지 않은 움직임을 멈춘다
|
||||
- Screen reader: 제목, live region, 오류, 동작이 한 번씩 읽힌다
|
||||
|
||||
A route with a form or a dialog requires real M4 modal and M5 field-error
|
||||
review; those items must not be marked not-applicable on that route. Passing automated evidence means
|
||||
only that tested pages had no critical or serious axe findings under the
|
||||
recorded Chromium, Firefox, and WebKit runs.
|
||||
form이나 dialog가 있는 route는 M4 modal 리뷰와 M5 필드 오류 리뷰를 실제로 해야
|
||||
한다. 그런 route에서는 그 항목을 not-applicable로 표시하면 안 된다. 자동 증거가
|
||||
통과했다는 것은 이것만 뜻한다: 기록된 Chromium, Firefox, WebKit 실행에서
|
||||
테스트한 페이지에 critical이나 serious 등급의 axe 발견이 없었다.
|
||||
|
||||
What the automated run scans:
|
||||
자동 실행이 검사하는 것:
|
||||
|
||||
- Every registered route, after the route's own `h1` is on screen, so the scan
|
||||
never lands on the app shell's loading surface
|
||||
(`tests/e2e/accessibility.spec.ts`). A public route's `h1` must equal its
|
||||
catalog title.
|
||||
- Protected routes after the demo sign-in, never the sign-in prompt. A list
|
||||
read answers an empty list in the frame its descriptor declares (inside the
|
||||
Envelope for `responseEnvelope: "ENVELOPE_V1"`), and the scan runs only once
|
||||
no alert box is on screen, so a list page is scanned in its empty state. A
|
||||
read of one resource (a detail page) has no generic answer: that route is
|
||||
scanned in its failure state and the run records an `a11y-data-state`
|
||||
annotation. `a11y.json` lists it under `notChecked`. When a protected
|
||||
route's `paramsSchema` is the input of such a read, the report expects that
|
||||
record from the descriptors alone and fails without it
|
||||
(`scripts/write-a11y-report.ts`).
|
||||
- The list of the feature `create:feature` writes, in its success, empty and
|
||||
error states, its detail and its form with submit errors, each after that
|
||||
state is on screen (`tests/e2e/generated-feature.spec.ts`, on a build with
|
||||
that feature). A product's own features get the route scan above.
|
||||
- 등록된 모든 route. route 자신의 `h1`이 화면에 나온 뒤 검사한다. 그래서 앱 셸의
|
||||
로딩 화면을 검사하는 일이 없다(`tests/e2e/accessibility.spec.ts`). 공개
|
||||
route의 `h1`은 catalog 제목과 같아야 한다.
|
||||
- 보호된 route는 데모 로그인 뒤에 검사하고, 로그인 안내 화면은 검사하지 않는다.
|
||||
목록 읽기에는 빈 목록이 응답으로 온다. 그 응답은 descriptor가 선언한 frame에
|
||||
담긴다(`responseEnvelope: "ENVELOPE_V1"`이면 Envelope 안). 검사는 화면에
|
||||
alert 상자가 없을 때만 돈다. 그래서 목록 페이지는 빈 상태로 검사된다. 자원
|
||||
하나를 읽는 경우(상세 페이지)에는 범용 응답이 없다. 그런 route는 실패 상태로
|
||||
검사하고, 실행이 `a11y-data-state` annotation을 기록한다. `a11y.json`은 그
|
||||
route를 `notChecked` 아래에 적는다. 보호된 route의 `paramsSchema`가 그런
|
||||
읽기의 입력이면, 보고서는 descriptor만 보고 그 기록이 있어야 한다고 판단하고,
|
||||
없으면 실패한다(`scripts/write-a11y-report.ts`).
|
||||
- `create:feature`가 만드는 feature의 목록(성공·빈·오류 상태), 상세, 제출 오류가
|
||||
난 form. 각 상태가 화면에 나온 뒤
|
||||
검사한다(`tests/e2e/generated-feature.spec.ts`, 그 feature가 들어간 빌드에서).
|
||||
제품이 직접 만든 feature는 위의 route 검사를 받는다.
|
||||
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택(보완)
|
||||
- 작성일: 2026-07-26
|
||||
- 요약: TypeScript 7과 ESLint 10으로 옮길 때 컴파일러와 운영 소스를 한꺼번에 바꾸지 않고 JS·TS 파일이 같은 품질 게이트를 통과하게 하는 도구 구성을 정한 결정이다.
|
||||
- 현재 정본: `eslint.config.ts`, `tsconfig.json`, `scripts/check-architecture.ts`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# VD-01: TypeScript 7과 ESLint 10의 점진적 전환 도구
|
||||
|
||||
- 상태: Accepted
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-07-26
|
||||
- 요약: 라우터를 React Router Data Mode로 바꾸고 실행 route는 registry에서 만들며 서버 상태는 계속 application input과 TanStack Query가 소유한다는 결정이다.
|
||||
- 현재 정본: `src/presentation/routes/`, `src/contracts/routes.ts`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# VD-03: React Router Data Mode와 서버 상태 소유권
|
||||
|
||||
- 상태: Accepted
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택(보완)
|
||||
- 작성일: 2026-07-26
|
||||
- 요약: 폼은 외부 폼 라이브러리 대신 native form 이벤트를 쓰는 local `useAppForm` facade로 처리하고 검증 오류·충돌·저장 실패를 구분해 보여 준다는 결정이다.
|
||||
- 현재 정본: `src/presentation/forms/`, `src/presentation/templates/`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# VD-04: Native form controller와 local facade
|
||||
|
||||
- 상태: Accepted
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택(보완)
|
||||
- 작성일: 2026-07-26
|
||||
- 요약: 아이콘은 `lucide-react`를 한 파일 facade 뒤에 두고 의미 이름만 노출하며, 복합 control은 headless 라이브러리 없이 native 요소로 만든다는 결정이다.
|
||||
- 현재 정본: `src/presentation/design-system/`, `docs/styling/design-tokens.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# VD-05: Semantic icon facade와 native-first interaction
|
||||
|
||||
- 상태: Accepted
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택(보완)
|
||||
- 작성일: 2026-07-26
|
||||
- 요약: 다국어 문구는 표준 Intl과 한국어 기준 typed local catalog로 처리하고 i18n 라이브러리는 기본으로 넣지 않는다는 결정이다.
|
||||
- 현재 정본: `src/presentation/i18n/`, `scripts/check-i18n.ts`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# VD-06: Intl과 typed local message catalog
|
||||
|
||||
- 상태: Accepted
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택(보완)
|
||||
- 작성일: 2026-07-26
|
||||
- 요약: 운영 진단은 `DiagnosticsPort`, 의미 이벤트는 `TelemetryPort`로 나누고 닫힌 registry와 값 정책을 통과한 값만 보낸다는 결정이다.
|
||||
- 현재 정본: `src/adapters/diagnostics/`, `src/adapters/telemetry/`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# VD-07: Diagnostics와 telemetry exporter 경계
|
||||
|
||||
- 상태: Accepted
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-07-26
|
||||
- 요약: Storybook은 개발용 정적 산출물로만 쓰고, 시각 회귀는 운영 build를 고정된 Chromium으로 찍은 스크린샷과 비교한다는 결정이다.
|
||||
- 현재 정본: `.storybook/`, `docs/testing/taxonomy.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# VD-08: 개발용 Storybook과 로컬 시각 회귀 증적
|
||||
|
||||
- 상태: Accepted
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-07-26
|
||||
- 요약: lockfile 전체에서 의존성 목록·라이선스·SBOM·출처 증명을 만들고, 외부 취약점 보고와 서명된 증거가 없으면 승격(promotion)을 실패로 둔다는 결정이다.
|
||||
- 현재 정본: `docs/security/supply-chain.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# VD-09: 공급망 inventory, license, vulnerability, SBOM과 provenance
|
||||
|
||||
- 상태: Accepted
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택(보완)
|
||||
- 작성일: 2026-07-26
|
||||
- 요약: realtime·offline·PWA 같은 선택 기능 12개를 recipe catalog로 두고, 실제 제품 요구가 생기기 전에는 설치하지 않는다는 결정이다.
|
||||
- 현재 정본: `config/recipes/frontend-capability-recipes.json`, `docs/architecture/optional-adapter-recipes.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# VD-10: 선택형 frontend capability recipe
|
||||
|
||||
- 상태: Accepted
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-07-27
|
||||
- 요약: File·Blob·파일 선택기·IndexedDB·OPFS·Cache Storage를 기존 `StoragePort`와 섞지 않는 별도 경계로 두고, reference runtime은 제품에 조립하지 않은 채 둔다는 결정이다.
|
||||
- 현재 정본: `src/adapters/browser-files/`, `src/adapters/storage/`, `config/recipes/frontend-capability-recipes.json`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# VD-11: Browser file and origin-storage 경계
|
||||
|
||||
- 상태: Accepted — native reference runtime available, not composed
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-07-28
|
||||
- 요약: presigned 전송과 Image CDN에서 BFF 제어 경로와 저장소·CDN 데이터 경로를 나누고, 브라우저는 발급받은 정확한 capability만 쓴다는 결정이다.
|
||||
- 현재 정본: `src/adapters/browser-transfer/`, `docs/operations/browser-transfer-recovery.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# VD-12: Presigned transfer, resumable upload와 Image CDN 경계
|
||||
|
||||
- 상태: Accepted — reference runtime available, not composed
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-07-28
|
||||
- 요약: server state cache, Web Storage, IndexedDB 영속화, 탭 간 무효화를 한 추상으로 합치지 않고 scope와 영속화 경계를 따로 정한다는 결정이다.
|
||||
- 현재 정본: `src/adapters/query-cache/`, `src/adapters/cross-context-invalidation/`, `src/contracts/storage-keys.ts`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# VD-13: Client cache scope, persistence와 탭 간 일관성 경계
|
||||
|
||||
- 상태: Accepted — staged implementation required
|
||||
+13
-4
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-07-28
|
||||
- 요약: Range로 이어받는 다운로드와 백그라운드 다운로드를 일반 스트리밍 다운로드와 다른 capability로 두고, 재개 근거는 서버가 준 불변 세대와 강한 validator로 한다는 결정이다.
|
||||
- 현재 정본: `config/recipes/frontend-capability-recipes.json`, `docs/operations/browser-transfer-recovery.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# VD-14: Resumable download와 background download 경계
|
||||
|
||||
- 상태: Accepted — production design complete, implementation pending
|
||||
@@ -886,13 +895,13 @@ background download 구현 완료 증거로 사용하지 않는다.
|
||||
|
||||
## 20. 참고
|
||||
|
||||
- [Browser data capability completion ledger](../browser-data-capability-completion-ledger.md)
|
||||
- [Browser data capability completion ledger](../design/2026-07-30-browser-data-capability-completion-ledger-design.md)
|
||||
- [VD-16 Browser transfer composition과 Image delivery](./VD-16-browser-transfer-composition-and-image-delivery.md)
|
||||
- [Browser transfer recovery](../../operations/browser-transfer-recovery.md)
|
||||
- [Browser transfer recovery](../operations/browser-transfer-recovery.md)
|
||||
- [RFC 9110 HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110.html)
|
||||
- [Fetch Standard](https://fetch.spec.whatwg.org/)
|
||||
- [File System Standard](https://fs.spec.whatwg.org/)
|
||||
- [Service Workers](https://w3c.github.io/ServiceWorker/)
|
||||
- [Background Fetch draft](https://wicg.github.io/background-fetch/)
|
||||
- [기존 transfer 설계](../presigned-transfer-and-image-cdn.md)
|
||||
- [browser file/origin storage 설계](../browser-file-and-origin-storage.md)
|
||||
- [기존 transfer 설계](../design/2026-07-30-presigned-transfer-and-image-cdn-design.md)
|
||||
- [browser file/origin storage 설계](../design/2026-07-27-browser-file-and-origin-storage-design.md)
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-07-28
|
||||
- 요약: VD-11 reference runtime을 제품에 조립하기 전에 필요한 origin 저장소 수명 주기, migration, 선택형 파일 capability의 공통 계약을 정한 결정이다.
|
||||
- 현재 정본: `src/adapters/storage/`, `src/adapters/platform/`, `docs/operations/browser-file-storage-recovery.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# VD-15: Origin storage lifecycle, migration, and optional file capabilities
|
||||
|
||||
- 상태: Accepted design — implementation pending
|
||||
+13
-4
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-07-28
|
||||
- 요약: 파일·전송·이미지 capability를 계정 범위의 단일 composition owner가 정해진 순서로 만들고 Image delivery를 그 위에 붙인다는 결정이다.
|
||||
- 현재 정본: `src/adapters/browser-transfer/`, `config/recipes/frontend-capability-recipes.json`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# VD-16: Browser transfer composition과 Image delivery
|
||||
|
||||
- 상태: Accepted — design complete, implementation pending
|
||||
@@ -601,11 +610,11 @@ schema version을 내리거나 checkpoint를 무조건 삭제해 rollback하지
|
||||
|
||||
## 관련 문서
|
||||
|
||||
- [Browser data capability completion ledger](../browser-data-capability-completion-ledger.md)
|
||||
- [Presigned transfer and Image CDN](../presigned-transfer-and-image-cdn.md)
|
||||
- [Browser data capability completion ledger](../design/2026-07-30-browser-data-capability-completion-ledger-design.md)
|
||||
- [Presigned transfer and Image CDN](../design/2026-07-30-presigned-transfer-and-image-cdn-design.md)
|
||||
- [VD-14 Resumable download와 background download](./VD-14-resumable-download-and-background-transfer.md)
|
||||
- [Server file capability infrastructure](../server-file-capability-infrastructure.md)
|
||||
- [Browser transfer recovery](../../operations/browser-transfer-recovery.md)
|
||||
- [Server file capability infrastructure](../design/2026-07-28-server-file-capability-infrastructure-design.md)
|
||||
- [Browser transfer recovery](../operations/browser-transfer-recovery.md)
|
||||
|
||||
## 선택하지 않은 대안
|
||||
|
||||
+12
-3
@@ -1,10 +1,19 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택(보완)
|
||||
- 작성일: 2026-07-28
|
||||
- 요약: API transport는 operation registry가 고르고 feature port는 protocol을 모르게 하며, REST 실행 경로를 정한 결정이다.
|
||||
- 현재 정본: `src/adapters/http/`, `docs/architecture/backend-api-and-server-state-contract.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# VD-23: API transport selection과 REST execution
|
||||
|
||||
> **정본 안내 (non-authoritative for runtime capability decisions)**
|
||||
>
|
||||
> Runtime Config/boot, Fetch HTTP client, Router, Query/Mutation, realtime 공통 경계, Web Worker,
|
||||
> Service Worker, offline command와 Background Sync의 구현 결정은
|
||||
> [프론트엔드 런타임 Capability 저장소 정합형 구현 결정 폐쇄 상세 설계](../2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md)가 정본이다.
|
||||
> [프론트엔드 런타임 Capability 저장소 정합형 구현 결정 폐쇄 상세 설계](../design/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md)가 정본이다.
|
||||
> 본 결정의 해당 서술이 정본과 충돌하면 정본을 따른다.
|
||||
|
||||
- 상태: Accepted — REST v2 실행 경로는 2026-11-03에 지웠다(`048f490`·`12f3bb7`). 지금 REST 실행은 V3 contract executor다. advanced profiles pending
|
||||
@@ -17,9 +26,9 @@
|
||||
- GraphQL/Connect/gRPC-Web/REST Gateway product selection: `NOT_SELECTED`
|
||||
- 관련 결정: VD-13, VD-24, VD-25, VD-26, VD-27, VD-29, VD-30
|
||||
- 상세 설계:
|
||||
[API contract, Schema, Mapper와 Server State](../api-contract-schema-mapper-and-server-state.md)
|
||||
[API contract, Schema, Mapper와 Server State](../design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md)
|
||||
- browser Protobuf/gateway 설계:
|
||||
[Protobuf browser transport와 REST Gateway](../protobuf-browser-transport-and-rest-gateway.md)
|
||||
[Protobuf browser transport와 REST Gateway](../design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md)
|
||||
|
||||
## 배경
|
||||
|
||||
+10
-1
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택(보완)
|
||||
- 작성일: 2026-07-28
|
||||
- 요약: 입력·명령·전송·응답 검증 경계를 나누고 runtime schema와 boundary mapper가 각 경계에서 할 일을 정한 결정이다.
|
||||
- 현재 정본: `src/adapters/http/http-execution-v3.ts`, `src/contracts/boundary-mapper.ts`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# VD-24: Runtime Schema와 boundary Mapper
|
||||
|
||||
- 상태: Accepted — reference typed codec/mapper baseline은 2026-11-03에 지웠다(`12f3bb7`, `MAPPER_REGISTRY`·`RUNTIME_SCHEMA_CODECS` 삭제). 지금 schema는 V3 descriptor 검증기와 FE-REG-SCHEMA 행, mapping은 descriptor의 `mapSuccess`다. artifact governance pending
|
||||
@@ -8,7 +17,7 @@
|
||||
- generated API product selection: `NOT_SELECTED`
|
||||
- 관련 결정: VD-13, VD-23, VD-25, VD-26, VD-27, VD-29, VD-30
|
||||
- 상세 설계:
|
||||
[API contract, Schema, Mapper와 Server State](../api-contract-schema-mapper-and-server-state.md)
|
||||
[API contract, Schema, Mapper와 Server State](../design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md)
|
||||
|
||||
## 배경
|
||||
|
||||
+10
-1
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-07-28
|
||||
- 요약: TanStack Query를 유일한 기본 server state owner로 두고 bound query, 입력 기반 mutation 조정, 세션 세대에 따른 cache 수명 주기를 정한 결정이다.
|
||||
- 현재 정본: `src/presentation/adapters/query/`, `src/adapters/query-cache/`, `src/bootstrap/server-state-generation-store.ts`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# VD-25: Server State Cache lifecycle
|
||||
|
||||
- 상태: Accepted — reference bound-query/input-aware mutation baseline composed, lifecycle delta pending
|
||||
@@ -12,7 +21,7 @@
|
||||
- query persistence product selection: `NOT_SELECTED`
|
||||
- 관련 결정: VD-13, VD-23, VD-24, VD-26, VD-27, VD-29, VD-30
|
||||
- 상세 설계:
|
||||
[API contract, Schema, Mapper와 Server State](../api-contract-schema-mapper-and-server-state.md)
|
||||
[API contract, Schema, Mapper와 Server State](../design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md)
|
||||
|
||||
## 배경
|
||||
|
||||
+10
-1
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-07-28
|
||||
- 요약: 운영 GraphQL은 고정 endpoint와 persisted operation ID로만 보내고 임의 query 문자열은 허용하지 않는다는 결정이다.
|
||||
- 현재 정본: `docs/architecture/backend-api-and-server-state-contract.md`, `docs/operations/api-contract-and-server-state-recovery.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# VD-26: Persisted GraphQL operation
|
||||
|
||||
- 상태: Accepted design — reference runtime implementation pending
|
||||
@@ -9,7 +18,7 @@
|
||||
- normalized GraphQL cache: `NOT_SELECTED`
|
||||
- 관련 결정: VD-13, VD-23, VD-24, VD-25, VD-28
|
||||
- 상세 설계:
|
||||
[API contract, Schema, Mapper와 Server State](../api-contract-schema-mapper-and-server-state.md)
|
||||
[API contract, Schema, Mapper와 Server State](../design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md)
|
||||
|
||||
## 배경
|
||||
|
||||
+11
-2
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-07-28
|
||||
- 요약: gRPC-Web은 protocol profile을 섞지 않고 unary와 server stream만 지원하며 client·양방향 stream은 브라우저 한계로 보장하지 않는다는 결정이다.
|
||||
- 현재 정본: `src/adapters/browser-rpc/`, `src/contracts/browser-rpc.ts`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# VD-27: gRPC-Web unary와 server stream
|
||||
|
||||
- 상태: Accepted design — common coordinator available, wire adapter pending
|
||||
@@ -10,9 +19,9 @@
|
||||
- client-streaming/bidirectional-streaming guarantee: `PLATFORM_LIMITED`
|
||||
- 관련 결정: VD-13, VD-23, VD-24, VD-25, VD-28, VD-29, VD-30
|
||||
- 상세 설계:
|
||||
[Protobuf browser transport와 REST Gateway](../protobuf-browser-transport-and-rest-gateway.md)
|
||||
[Protobuf browser transport와 REST Gateway](../design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md)
|
||||
- 상위 API 설계:
|
||||
[API contract, Schema, Mapper와 Server State](../api-contract-schema-mapper-and-server-state.md)
|
||||
[API contract, Schema, Mapper와 Server State](../design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md)
|
||||
|
||||
## 배경
|
||||
|
||||
+14
-5
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택(보완)
|
||||
- 작성일: 2026-07-28
|
||||
- 요약: SSE·WebSocket·Web Push·제한된 Polling을 서로 다른 capability로 나누고 연결 복구와 자원 상한을 정한 결정이다.
|
||||
- 현재 정본: `src/adapters/realtime/`, `src/adapters/web-push/`, `docs/architecture/optional-adapter-recipes.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# VD-28: Realtime events, Web Push와 bounded polling
|
||||
|
||||
- 상태: Accepted — reference runtime available, product implementation pending
|
||||
@@ -649,16 +658,16 @@ common runtime status는 `AVAILABLE_NOT_COMPOSED`다. 위의 미완료 promotion
|
||||
|
||||
## 관련 자료
|
||||
|
||||
- [상세 설계](../realtime-events-web-push-and-bounded-polling.md)
|
||||
- [상세 설계](../design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md)
|
||||
- [VD-10 optional capability recipes](./VD-10-optional-capability-recipes.md)
|
||||
- [VD-13 client cache scope and persistence](./VD-13-client-cache-scope-and-persistence.md)
|
||||
- [VD-23 API transport selection and REST execution](./VD-23-api-transport-selection-and-rest-execution.md)
|
||||
- [VD-25 Server State Cache lifecycle](./VD-25-server-state-cache-lifecycle.md)
|
||||
- [VD-27 gRPC-Web unary and server stream](./VD-27-grpc-web-unary-and-server-stream.md)
|
||||
- [API contract, Schema, Mapper와 Server State](../api-contract-schema-mapper-and-server-state.md)
|
||||
- [Optional adapter recipes](../optional-adapter-recipes.md)
|
||||
- [Client cache and browser storage](../client-cache-and-storage.md)
|
||||
- [Frontend ports, adapters, and boundaries](../frontend-ports-adapters-and-boundaries.md)
|
||||
- [API contract, Schema, Mapper와 Server State](../design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md)
|
||||
- [Optional adapter recipes](../architecture/optional-adapter-recipes.md)
|
||||
- [Client cache and browser storage](../design/2026-07-28-client-cache-and-storage-design.md)
|
||||
- [Frontend ports, adapters, and boundaries](../design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md)
|
||||
- [WHATWG Server-sent events](https://html.spec.whatwg.org/multipage/server-sent-events.html)
|
||||
- [WHATWG WebSockets](https://websockets.spec.whatwg.org/)
|
||||
- [W3C Push API](https://www.w3.org/TR/push-api/)
|
||||
+11
-2
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-07-28
|
||||
- 요약: Connect-Web을 쓸 때 protocol, runtime, message encoding, framing을 따로 고르고 VD-27의 gRPC-Web 상태 기계와 섞지 않는다는 결정이다.
|
||||
- 현재 정본: `src/adapters/browser-rpc/`, `src/contracts/browser-rpc.ts`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# VD-29: Connect-Web과 browser Protobuf runtime
|
||||
|
||||
- 상태: Accepted design — common coordinator available, wire adapter pending
|
||||
@@ -10,9 +19,9 @@
|
||||
`PLATFORM_LIMITED`
|
||||
- 관련 결정: VD-13, VD-23, VD-24, VD-25, VD-27, VD-28, VD-30
|
||||
- 상세 설계:
|
||||
[Protobuf browser transport와 REST Gateway](../protobuf-browser-transport-and-rest-gateway.md)
|
||||
[Protobuf browser transport와 REST Gateway](../design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md)
|
||||
- 상위 API 설계:
|
||||
[API contract, Schema, Mapper와 Server State](../api-contract-schema-mapper-and-server-state.md)
|
||||
[API contract, Schema, Mapper와 Server State](../design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md)
|
||||
|
||||
## 배경
|
||||
|
||||
+12
-3
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-07-28
|
||||
- 요약: Protobuf schema와 codegen 관리 방식을 정하고, 기본 공개 adapter는 curated REST BFF로 두며 REST transcoding gateway와 섞지 않는다는 결정이다.
|
||||
- 현재 정본: `docs/architecture/backend-api-and-server-state-contract.md`, `src/contracts/browser-rpc.ts`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# VD-30: Protobuf contract와 REST transcoding gateway
|
||||
|
||||
- 상태: Accepted design — schema/codegen과 provider runtime implementation pending
|
||||
@@ -13,11 +22,11 @@
|
||||
`NOT_SELECTED`
|
||||
- 관련 결정: VD-12, VD-13, VD-14, VD-23, VD-24, VD-25, VD-27, VD-29
|
||||
- 상세 설계:
|
||||
[Protobuf browser transport와 REST Gateway](../protobuf-browser-transport-and-rest-gateway.md)
|
||||
[Protobuf browser transport와 REST Gateway](../design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md)
|
||||
- 상위 API 설계:
|
||||
[API contract, Schema, Mapper와 Server State](../api-contract-schema-mapper-and-server-state.md)
|
||||
[API contract, Schema, Mapper와 Server State](../design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md)
|
||||
- backend handoff:
|
||||
[Backend API와 Server State contract](../backend-api-and-server-state-contract.md)
|
||||
[Backend API와 Server State contract](../architecture/backend-api-and-server-state-contract.md)
|
||||
|
||||
## 배경
|
||||
|
||||
@@ -4,20 +4,20 @@
|
||||
>
|
||||
> Runtime Config/boot, Fetch HTTP client, Router, Query/Mutation, realtime 공통 경계, Web Worker,
|
||||
> Service Worker, offline command와 Background Sync의 구현 결정은
|
||||
> [프론트엔드 런타임 Capability 저장소 정합형 구현 결정 폐쇄 상세 설계](./2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md)가 정본이다.
|
||||
> [프론트엔드 런타임 Capability 저장소 정합형 구현 결정 폐쇄 상세 설계](../design/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md)가 정본이다.
|
||||
> 본 문서의 해당 서술이 정본과 충돌하면 정본을 따른다.
|
||||
|
||||
|
||||
- 상태: frontend handoff design accepted, backend implementation/evidence pending. 단 4.1·6·6.1절(Envelope 읽기, effect 판정, 쓰기 전 거절 표)은 지금 실행 규칙이다(`COMPOSED`, `src/adapters/http/backend-envelope.ts`)
|
||||
- 상태: frontend handoff 설계는 승인됨, backend 구현·증거는 대기 중. 단 4.1·6·6.1절(Envelope 읽기, effect 판정, 쓰기 전 거절 표)은 지금 실행 규칙이다(`COMPOSED`, `src/adapters/http/backend-envelope.ts`)
|
||||
- 기준일: 2026-07-28
|
||||
- 대상: Web API/BFF, application service, persistence, identity, GraphQL router,
|
||||
- 대상: Web API/BFF, 애플리케이션 서비스, 영속 계층(persistence), 신원(identity), GraphQL router,
|
||||
Connect/gRPC-Web gateway, Protobuf REST Gateway와 운영 owner
|
||||
- frontend 기준:
|
||||
[API contract, Schema, Mapper와 Server State](./api-contract-schema-mapper-and-server-state.md)
|
||||
[API contract, Schema, Mapper와 Server State](../design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md)
|
||||
- browser Protobuf/gateway 기준:
|
||||
[Protobuf browser transport와 REST Gateway](./protobuf-browser-transport-and-rest-gateway.md)
|
||||
[Protobuf browser transport와 REST Gateway](../design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md)
|
||||
- 파일 전송 backend 기준:
|
||||
[Server file capability infrastructure](./server-file-capability-infrastructure.md)
|
||||
[Server file capability infrastructure](../design/2026-07-28-server-file-capability-infrastructure-design.md)
|
||||
- 복구 절차:
|
||||
[API contract와 server-state recovery](../operations/api-contract-and-server-state-recovery.md)
|
||||
|
||||
@@ -28,14 +28,14 @@
|
||||
언어·framework·cloud 제품을 강제하지 않는다. Spring, Nest/Fastify, Go,
|
||||
.NET 또는 다른 stack을 사용해도 아래 불변조건은 동일하다.
|
||||
|
||||
이 repository에는 backend source, database migration, identity provider,
|
||||
이 repository에는 backend 소스 코드, 데이터베이스 migration, 신원 제공자(identity provider),
|
||||
GraphQL schema/router, protobuf descriptor, Connect/gRPC-Web runtime/proxy,
|
||||
REST transcoder와 실제 provider evidence가 없다. 따라서 이 문서는 backend 구현
|
||||
완료 증거가 아니다.
|
||||
|
||||
파일 업로드·다운로드, object storage, presigned URL, multipart와 Image CDN은
|
||||
별도 server file 문서가 소유한다. 이 문서는 ordinary REST/GraphQL/Connect/
|
||||
gRPC-Web application API, Protobuf REST Gateway와 frontend Server State 계약만
|
||||
gRPC-Web 애플리케이션 API, Protobuf REST Gateway와 frontend Server State 계약만
|
||||
소유한다.
|
||||
|
||||
## 2. 권장 논리 구조
|
||||
@@ -70,8 +70,8 @@ Browser-facing contract owner와 내부 service contract owner를 분리한다.
|
||||
body ceiling, status/media와 redaction을 소유한다.
|
||||
- Application service는 authorization 재검사, transaction, idempotency,
|
||||
conflict, revision과 domain invariant를 소유한다.
|
||||
- Persistence adapter는 SQL/NoSQL/Redis vendor type, row version과 cursor
|
||||
implementation을 외부 DTO에 노출하지 않는다.
|
||||
- 영속 계층(persistence) adapter는 SQL/NoSQL/Redis vendor 타입, row version과 cursor
|
||||
구현을 외부 DTO에 노출하지 않는다.
|
||||
- GraphQL router, Connect/gRPC-Web gateway와 REST transcoder는 선택 adapter다.
|
||||
다른 protocol로 임의 fallback하거나 frontend에 내부 service address를
|
||||
노출하지 않는다.
|
||||
@@ -193,8 +193,8 @@ Envelope의 모양과 키 존재 규칙은 짝 백엔드 템플릿 문서가 정
|
||||
`results` Envelope는 `ENVELOPE_MISMATCH`다. bulk 엔드포인트를 붙이려면 그
|
||||
operation을 `responseEnvelope: "NONE" as const`로 적고 별도 계약 기여에 둔다(한
|
||||
기여의 operation은 같은 값을 적는다. 기능 하나가 기여 둘을 낼 수 있다,
|
||||
`tests/unit/external-contract-runtime.test.ts` "lets one feature read two backends
|
||||
through two contributions"). 기능 스키마가 본문 전체를 읽고 `classifyProblem`이
|
||||
`tests/unit/external-contract-runtime.test.ts`
|
||||
"lets one feature read two backends through two contributions"). 기능 스키마가 본문 전체를 읽고 `classifyProblem`이
|
||||
적용 여부를 정한다.
|
||||
|
||||
### 4.2 Status와 error
|
||||
@@ -215,7 +215,7 @@ Envelope의 모양과 키 존재 규칙은 짝 백엔드 템플릿 문서가 정
|
||||
않았다. conditional mutation을 선택할 때 frontend failure vocabulary와
|
||||
transaction을 함께 승격해야 한다.
|
||||
|
||||
Backend `error.code`는 machine-readable stable code다. stack, SQL/vendor error,
|
||||
Backend `error.code`는 기계가 읽을 수 있는 안정된 code다. stack, SQL/vendor 오류,
|
||||
raw validation value, authorization reason과 내부 service address를 반환하지
|
||||
않는다.
|
||||
|
||||
@@ -243,7 +243,7 @@ revocation/session policy를 검증하고 operation별 authorization을 적용
|
||||
- unsafe method의 CSRF token/header와 Origin/Sec-Fetch-Site 검증
|
||||
- credentialed CORS에서 wildcard origin 금지
|
||||
- login/logout/session rotation과 cache generation 전환
|
||||
- session fixation, token rotation과 concurrent tab 동작
|
||||
- session 고정 공격(session fixation), token 교체(rotation)와 여러 탭을 동시에 쓸 때의 동작
|
||||
|
||||
Cross-origin bearer provider 최소 CORS:
|
||||
|
||||
@@ -255,7 +255,7 @@ Cross-origin bearer provider 최소 CORS:
|
||||
(`src/adapters/http/feature-http-binding.ts`). expose하지 않거나 응답이 없으면
|
||||
클라이언트가 보낸 값이 된다. Envelope operation의 실패 본문 `meta.traceId`는
|
||||
`AppFailure.traceId`가 된다(헤더가 아니라 본문이라 CORS expose와 상관없다)
|
||||
- redirect login page, HTML error body와 wildcard credential 금지
|
||||
- login 페이지로 redirect, HTML 오류 본문과 wildcard credential 금지
|
||||
|
||||
## 6. Command와 idempotency
|
||||
|
||||
@@ -436,7 +436,7 @@ CursorPage<T>
|
||||
- deleted/inserted row가 duplicate/gap을 만드는 의미를 snapshot 정책으로 결정
|
||||
- empty page인데 `hasMore=true`인 sparse page 허용 여부를 operation profile에 고정
|
||||
- cursor 최대 encoded byte, page size와 total scan/cost ceiling을 server도 강제
|
||||
- invalid, expired, wrong-principal, wrong-filter cursor의 safe error code를 고정
|
||||
- 잘못된 cursor, 만료된 cursor, 다른 principal의 cursor, 다른 filter의 cursor에 줄 안전한 오류 code를 고정
|
||||
|
||||
권장 query ordering 예:
|
||||
|
||||
@@ -486,7 +486,7 @@ GET with If-None-Match
|
||||
- `Vary`와 `Cache-Control` owner를 명확히 하고 browser HTTP cache와
|
||||
TanStack/application revalidation이 서로 다른 value owner가 되지 않게 함
|
||||
|
||||
Frontend는 validator와 mapped cache value의 scope, query identity,
|
||||
Frontend는 validator와 mapping된 cache 값의 scope, query identity,
|
||||
representation version과 cache revision이 모두 일치할 때만 304를 success로
|
||||
받는다. cache value가 없으면 unconditional refetch 또는 safe failure로 닫는다.
|
||||
|
||||
@@ -578,7 +578,7 @@ Backend handoff:
|
||||
- named operation source와 persisted ID/hash manifest
|
||||
- variables/result runtime fixtures
|
||||
- selected GraphQL-over-HTTP revision과 exact media/status profile
|
||||
- partial data policy와 safe error extension vocabulary
|
||||
- 부분 데이터(partial data) 정책과 안전한 error extension 어휘
|
||||
- field/row authorization, cost/depth/alias/list ceiling
|
||||
- N/N-1 router/frontend manifest rollout과 retirement
|
||||
|
||||
@@ -600,16 +600,16 @@ Browser
|
||||
|
||||
Backend handoff:
|
||||
|
||||
- authenticated proto source와 immutable descriptor digest
|
||||
- 인증된 proto source와 바뀌지 않는(immutable) descriptor digest
|
||||
- Buf/protoc lint/breaking 및 deterministic generation evidence
|
||||
- exact service/method/rpc-kind allowlist
|
||||
- selected gRPC-Web runtime kind, client API와 binary/JSON/text/wire revision;
|
||||
official XHR와 Connect-Web Fetch profile을 분리
|
||||
- proxy CORS, content-type, terminal status/trailer behavior
|
||||
- Envoy를 선택하면 exact version/config digest, filter order, upstream HTTP/2,
|
||||
- Envoy를 선택하면 정확한 version/config digest, filter 순서, upstream HTTP/2,
|
||||
route/idle/max-stream timeout, timeout offset와 buffering/flush
|
||||
- message/frame/count/queue/idle/total budget
|
||||
- server-stream sequence, gap, resume와 snapshot reset protocol
|
||||
- server-stream의 순번(sequence), 빈틈(gap), 재개(resume)와 snapshot 초기화 protocol
|
||||
- actual browser/proxy conformance
|
||||
|
||||
client streaming과 bidirectional streaming은 common gRPC-Web browser contract로
|
||||
@@ -636,7 +636,7 @@ Backend handoff:
|
||||
- protocol revision, JSON/binary encoding, POST 또는 approved GET
|
||||
- unary HTTP/error profile 또는 stream EndStream terminal profile
|
||||
- request/response/envelope/message/count/queue byte ceiling
|
||||
- unary/stream compression capability; stock browser stream은 identity-only
|
||||
- unary/stream 압축 capability. 기본(stock) 브라우저 stream은 identity 인코딩만 쓴다
|
||||
- total/idle timeout, browser abort→server context→downstream cancellation 전파
|
||||
- exact CORS allow/expose/preflight와 auth/CSRF profile
|
||||
- actual Chromium/Firefox/WebKit와 selected proxy/server conformance
|
||||
@@ -664,7 +664,7 @@ Direct gateway는 ProtoJSON/HttpRule/status/error 자체를 새 public contract
|
||||
- browser abort/deadline의 upstream gRPC/application work 전파
|
||||
- N/N-1 route/OpenAPI/runtime conformance와 coherent rollback
|
||||
|
||||
Gateway는 durable idempotency, pagination snapshot, ETag/HTTP conditional,
|
||||
Gateway는 지속되는(durable) 멱등성, pagination snapshot, ETag/HTTP 조건부 요청,
|
||||
product envelope, authorization와 file transfer semantics를 자동 구현하지 않는다.
|
||||
필요한 operation은 application service와 BFF가 계속 소유한다. generated
|
||||
REST streaming은 별도 framing/terminal/cache ADR 없이는 `NOT_SELECTED`다.
|
||||
@@ -678,8 +678,8 @@ Backend-driven invalidation/realtime을 선택하면:
|
||||
|
||||
- transactional outbox 또는 동등한 durable publication
|
||||
- principal/tenant authorization을 통과한 event projection
|
||||
- event type/version, aggregate revision, sequence와 dedupe identity
|
||||
- reconnect cursor, gap detection과 snapshot reset
|
||||
- event type/version, aggregate revision, 순번(sequence)과 중복 제거(dedupe) identity
|
||||
- 재연결 cursor, 빈틈 감지(gap detection)와 snapshot 초기화
|
||||
- retention, replay ceiling과 slow-consumer policy
|
||||
|
||||
를 제공해야 한다. event payload를 authoritative resource snapshot으로 쓸지
|
||||
@@ -745,13 +745,13 @@ Request ID와 trace ID는 browser에 반환할 수 있지만 credential 역할
|
||||
- operation availability와 latency
|
||||
- 401/403/409/412/422/429 및 5xx rate
|
||||
- schema/mapper/contract mismatch
|
||||
- idempotency in-progress age, collision과 unknown effect
|
||||
- 멱등 요청이 처리 중(in-progress)으로 머문 시간, 키 충돌(collision)과 결과 불명(unknown effect)
|
||||
- cursor invalid/expired/loop-equivalent server detection
|
||||
- conditional hit/miss와 invalid 304
|
||||
- GraphQL persisted miss/cost reject
|
||||
- Connect missing/duplicate EndStream, whole-body/queue overflow와 compression mismatch
|
||||
- gRPC-Web missing terminal status, frame/idle/queue overflow
|
||||
- REST Gateway route/OpenAPI/runtime rewrite drift와 cancel propagation loss
|
||||
- REST Gateway route/OpenAPI/runtime rewrite의 어긋남(drift)과 취소 전파 유실
|
||||
|
||||
## 18. 배포, compatibility와 rollback
|
||||
|
||||
@@ -779,7 +779,7 @@ Backend 완료 판정에는 unit test 외에 actual staging provider evidence가
|
||||
| --- | --- |
|
||||
| REST | exact path/query/body, media/status/envelope, max body, malformed/truncated JSON |
|
||||
| Auth | missing/expired credential, 401/403, rotation, cross-origin preflight |
|
||||
| Command | concurrent same-key replay, fingerprint mismatch, commit 뒤 response loss |
|
||||
| Command | 같은 키 동시 replay, fingerprint 불일치, commit 뒤 응답 유실 |
|
||||
| Cursor | filter/sort binding, expiry, snapshot stability, loop/gap/duplicate 방지 |
|
||||
| Conditional | 200→304, cache-missing 304 방지, representation change, 412 |
|
||||
| Schema | additive/breaking/null/enum/time/number fixtures와 N/N-1 |
|
||||
@@ -787,7 +787,7 @@ Backend 완료 판정에는 unit test 외에 actual staging provider evidence가
|
||||
| Connect | JSON/binary unary, GET restriction, EndStream, body/message cap, compression, cancel/deadline와 CORS |
|
||||
| gRPC-Web | proxy media/status/trailer, oversized frame, cancel, idle, gap/resume |
|
||||
| REST Gateway | HttpRule path/query/body, ProtoJSON, OpenAPI/status/error rewrite, abort propagation과 N/N-1 |
|
||||
| Operations | deadline/retry amplification, rate limit, kill switch, coherent rollback |
|
||||
| Operations | deadline/retry 증폭, 요청 한도(rate limit), 긴급 차단 스위치(kill switch), 일관된 rollback |
|
||||
|
||||
## 20. Backend handoff checklist
|
||||
|
||||
@@ -805,7 +805,7 @@ Backend 완료 판정에는 unit test 외에 actual staging provider evidence가
|
||||
- [ ] gRPC-Web을 선택했다면 descriptor/proxy/browser evidence가 있다.
|
||||
- [ ] REST Gateway를 선택했다면 kind/HttpRule/ProtoJSON/OpenAPI와 runtime
|
||||
conformance evidence가 있다.
|
||||
- [ ] staging conformance, fault injection, canary, kill switch와 rollback drill이
|
||||
- [ ] staging 적합성 검사(conformance), 장애 주입(fault injection), canary, kill switch와 rollback drill이
|
||||
통과했다.
|
||||
|
||||
## 21. Frontend 완료 경계
|
||||
@@ -815,17 +815,17 @@ Backend 구현과 별개로 현재 frontend 상태를 다음처럼 해석한다.
|
||||
| 범위 | 현재 상태 | 남은 owner |
|
||||
| --- | --- | --- |
|
||||
| REST path/provider/auth/deadline/bounded JSON | `COMPOSED` | actual provider conformance는 backend/operations |
|
||||
| runtime schema와 mapper registry | `COMPOSED` | artifact digest/source provenance는 backend contract source + frontend/platform |
|
||||
| session generation과 query identity | `COMPOSED` | account identity projection은 identity integration + frontend |
|
||||
| Cursor runtime | `AVAILABLE_NOT_COMPOSED` | CursorPage backend 계약 후 frontend query binding |
|
||||
| conditional validator store | `AVAILABLE_NOT_COMPOSED` | ETag/304/412 backend 계약 후 frontend HTTP/cache transaction |
|
||||
| ordered optimistic layer | `AVAILABLE_NOT_COMPOSED` | product membership/revision 승인 후 frontend mutation definition |
|
||||
| runtime schema와 mapper registry | `COMPOSED` | artifact digest/source provenance는 backend 계약 원천(contract source)과 frontend/platform |
|
||||
| session generation과 query identity | `COMPOSED` | 계정 identity projection은 identity 연동 담당과 frontend |
|
||||
| Cursor runtime | `AVAILABLE_NOT_COMPOSED` | CursorPage backend 계약 뒤 frontend query 연결(binding) |
|
||||
| conditional validator store | `AVAILABLE_NOT_COMPOSED` | ETag/304/412 backend 계약 뒤 frontend HTTP/cache 트랜잭션 |
|
||||
| ordered optimistic layer | `AVAILABLE_NOT_COMPOSED` | 제품의 membership/revision 승인 뒤 frontend mutation 정의 |
|
||||
| GraphQL adapter | `DESIGNED_NOT_IMPLEMENTED` | product/backend 선택 뒤 frontend adapter/codegen |
|
||||
| Browser RPC V3 공통 계약/coordinator | `AVAILABLE_NOT_COMPOSED` | selected descriptor/generated client와 protocol transport 확정 뒤 frontend provider adapter |
|
||||
| Protobuf schema/codegen | `DESIGNED_NOT_IMPLEMENTED` | authenticated backend contract source 선택 뒤 pinned frontend generation |
|
||||
| Protobuf schema/codegen | `DESIGNED_NOT_IMPLEMENTED` | 인증된 backend contract source 선택 뒤, 버전을 고정한 frontend 코드 생성 |
|
||||
| Connect-Web adapter | `DESIGNED_NOT_IMPLEMENTED` | product/backend/server 선택 뒤 frontend adapter/codegen |
|
||||
| gRPC-Web adapter | `DESIGNED_NOT_IMPLEMENTED` | product/backend/proxy 선택 뒤 frontend adapter/codegen |
|
||||
| Protobuf REST Gateway | `NOT_SELECTED` | gateway kind와 public HTTP contract 승인 뒤 REST adapter binding |
|
||||
| Protobuf REST Gateway | `NOT_SELECTED` | gateway 종류와 공개 HTTP contract 승인 뒤 REST adapter 연결(binding) |
|
||||
| persisted query/offline command | `NOT_SELECTED` | 별도 product ADR와 backend durability 계약 |
|
||||
|
||||
따라서 “backend만 구현하면 frontend가 아무 변경 없이 모든 capability를 자동
|
||||
|
||||
@@ -1,157 +1,146 @@
|
||||
# Capability consumer experience baseline
|
||||
# capability 소비자 경험 기준선
|
||||
|
||||
Correctness inside a reusable capability is not sufficient. The platform is
|
||||
also evaluated by how much of that correctness a normal feature developer must
|
||||
understand.
|
||||
재사용 capability 안이 올바르다는 것만으로는 부족하다.
|
||||
플랫폼은 그 올바름을 쓰려고 보통의 feature 개발자가 얼마나 많이 알아야 하는지로도 평가받는다.
|
||||
|
||||
These measurements are baselines, not score targets. A lower line count is not
|
||||
automatically better if it hides business semantics or creates a universal
|
||||
repository abstraction.
|
||||
이 측정값은 기준선이지 점수 목표가 아니다.
|
||||
줄 수가 적어도 업무 의미를 숨기거나 만능 repository 추상화를 만든다면, 저절로 더 좋은 것이 아니다.
|
||||
|
||||
## Scenario A — a REST feature
|
||||
## 시나리오 A — REST feature
|
||||
|
||||
The REST consumer is the feature `corepack pnpm create:feature <id> --with-create`
|
||||
writes (the template's reference sample had this role until 2026-11-07).
|
||||
REST 소비자는 `corepack pnpm create:feature <id> --with-create`가
|
||||
쓰는 feature다(2026-11-07까지는 템플릿의 참조 샘플이 이 역할을 했다).
|
||||
|
||||
It covers list/detail/create behavior, mapping, typed operation inputs and
|
||||
application ports.
|
||||
목록·상세·생성 동작, 매핑, 타입이 있는 operation 입력, application port를 다룬다.
|
||||
|
||||
The feature-owned boundary and application source is these four files:
|
||||
feature가 소유한 경계 코드와 application 코드는 다음 네 파일이다.
|
||||
|
||||
- `application/<base>-feature-api.ts`
|
||||
- `contracts/<base>-mapper.ts`
|
||||
- `adapters/<base>-http-gateway.ts`
|
||||
- `adapters/create-<base>-feature-input.ts`
|
||||
|
||||
This document does not keep their line counts; a hand-typed count drifted
|
||||
from the code (review 14-07). Measure them in a generated feature with
|
||||
`wc -l` on those four files.
|
||||
이 문서는 이 파일들의 줄 수를 적어 두지 않는다. 손으로 적은 줄 수가 코드와 어긋난 적이 있다(리뷰 14-07).
|
||||
생성한 feature에서 이 네 파일에 `wc -l`을 돌려 잰다.
|
||||
|
||||
The important boundary metric is not the raw total. It is what those files need
|
||||
to know about the platform.
|
||||
중요한 경계 지표는 단순 합계가 아니다. 이 파일들이 플랫폼에 대해 무엇을 알아야 하는지다.
|
||||
|
||||
Current result:
|
||||
지금 결과:
|
||||
|
||||
- HTTP platform imports in the feature adapter layer: 2 files,
|
||||
- canonical import path used by both:
|
||||
`src/adapters/http/index.ts`,
|
||||
- direct imports of `http-execution-v3.ts`, retry scheduler, response reader,
|
||||
auth admission or effect-certainty internals: 0,
|
||||
- feature gateway owns transport failure projection: 0,
|
||||
- feature gateway chooses operation ID, route ID, exact input/value type and
|
||||
mapper: yes,
|
||||
- central installed files own feature-specific adapter/runtime wiring: no;
|
||||
feature-owned contributions are aggregated centrally.
|
||||
- feature adapter 계층에서 HTTP 플랫폼을 import하는 파일: 2개
|
||||
- 두 파일이 쓰는 정식 import 경로:
|
||||
`src/adapters/http/index.ts`
|
||||
- `http-execution-v3.ts`, retry scheduler, 응답 reader, 인증 승인(auth admission),
|
||||
effect-certainty 내부 모듈을 직접 import하는 곳: 0
|
||||
- 전송 실패를 변환(projection)하는 일을 feature gateway가 맡는 곳: 0
|
||||
- feature gateway가 operation ID, route ID, 정확한 입력·값 타입, mapper를 고르는가: 예
|
||||
- 중앙 설치 파일이 feature 전용 adapter·runtime 연결을 소유하는가: 아니오.
|
||||
feature가 소유한 contribution을 중앙에서 모을 뿐이다.
|
||||
|
||||
The reusable HTTP capability now owns execution-outcome normalization through
|
||||
`createFeatureHttpBinding`. A feature may still implement a custom outbound
|
||||
adapter behind its application port when the reusable contract does not match
|
||||
its business requirement.
|
||||
실행 결과를 정규화하는 일은 이제 재사용 HTTP capability가
|
||||
`createFeatureHttpBinding`으로 맡는다.
|
||||
재사용 계약이 업무 요구에 맞지 않으면, feature는 여전히 자기 application port 뒤에 직접 만든 outbound adapter를 둘 수 있다.
|
||||
|
||||
## Scenario B — IndexedDB local draft
|
||||
## 시나리오 B — IndexedDB 로컬 초안
|
||||
|
||||
The executable consumer probe is:
|
||||
실행되는 소비자 탐침(probe)은 다음이다.
|
||||
|
||||
`tests/contract/consumer-experience/indexeddb-local-draft.test.ts`
|
||||
|
||||
It runs and reads the one Local Draft implementation, the test fixture
|
||||
`tests/fixtures/indexeddb-consumer` (the template's former local-draft sample
|
||||
under `src/features/`, moved there because it is no product feature). An
|
||||
earlier isolated copy had drifted from it and was removed (09-12).
|
||||
이 테스트는 Local Draft 구현 하나를 실행하고 읽는다. 그 구현은 테스트 fixture
|
||||
`tests/fixtures/indexeddb-consumer`다. 예전에 `src/features/` 아래 있던 템플릿의 local-draft 샘플인데,
|
||||
제품 feature가 아니라서 이리로 옮겼다.
|
||||
예전에 따로 떼어 둔 복사본은 이 구현과 어긋나서 지웠다(09-12).
|
||||
|
||||
The consumer owns the Local Draft domain/application API and declares the slice
|
||||
of the repository it calls (`LocalDraftRepository` in
|
||||
`tests/fixtures/indexeddb-consumer/adapters/local-draft-indexeddb-store.ts`). The
|
||||
host hands in an `IndexedDbRepositoryPort<LocalDraft, never>` through the
|
||||
`indexedDb` capability; the port satisfies that slice structurally. The
|
||||
cross-capability composition contract lives at:
|
||||
소비자는 Local Draft의 domain·application API를 소유한다.
|
||||
그리고 repository에서 자기가 부르는 부분(slice)을 선언한다
|
||||
(`tests/fixtures/indexeddb-consumer/adapters/local-draft-indexeddb-store.ts`의 `LocalDraftRepository`).
|
||||
host는 `indexedDb` capability로 `IndexedDbRepositoryPort<LocalDraft, never>`를 넘겨준다.
|
||||
이 port는 구조적 타입으로 그 slice를 만족한다.
|
||||
capability를 가로지르는 조립 계약은 다음에 있다.
|
||||
|
||||
`tests/contract/reusable-capability/feature-adapter-composition.test.ts`
|
||||
|
||||
That test composes one HTTP-only contribution and the IndexedDB-only Local Draft
|
||||
contribution through the same generic catalog path.
|
||||
이 테스트는 HTTP만 쓰는 contribution 하나와 IndexedDB만 쓰는 Local Draft contribution을
|
||||
같은 범용 카탈로그 경로로 조립한다.
|
||||
|
||||
The browser-level composition proof lives at:
|
||||
브라우저 수준의 조립 증명은 다음에 있다.
|
||||
|
||||
`tests/browser-capabilities/local-draft-composition.spec.ts`
|
||||
|
||||
It runs against native browser IndexedDB. The test creates the platform
|
||||
`createIndexedDbRuntime`, exposes that runtime through the typed
|
||||
`createIndexedDbRepositoryProvider`, composes
|
||||
`LOCAL_DRAFT_FEATURE_ADAPTER_CONTRIBUTION`, then executes Local Draft
|
||||
save/find/remove through the feature API. The Local Draft feature still does
|
||||
not import the IndexedDB runtime or native browser API.
|
||||
이 테스트는 브라우저의 실제 IndexedDB에서 돈다. 먼저 플랫폼의
|
||||
`createIndexedDbRuntime`을 만들고, 타입이 있는
|
||||
`createIndexedDbRepositoryProvider`로 그 runtime을 내놓는다. 그다음
|
||||
`LOCAL_DRAFT_FEATURE_ADAPTER_CONTRIBUTION`을 조립하고, feature API로 Local Draft의
|
||||
저장·조회·삭제를 실행한다. 그래도 Local Draft feature는 IndexedDB runtime이나 브라우저 기본 API를 import하지 않는다.
|
||||
|
||||
Measured on the Local Draft consumer, then under `src/features/` (09-12):
|
||||
Local Draft 소비자가 아직 `src/features/` 아래 있을 때 잰 값(09-12):
|
||||
|
||||
| Metric | Result |
|
||||
| 지표 | 결과 |
|
||||
| --- | ---: |
|
||||
| feature LOC (all `.ts` files) | 295 |
|
||||
| import statements leaving the feature (`contracts/errors`, `contracts/result`, `application-api`, `feature-adapter-contribution`) | 7 |
|
||||
| native IndexedDB API references | 0 |
|
||||
| `src/adapters/storage/indexeddb/**` imports | 0 |
|
||||
| `src/application/ports/browser-file-storage/**` imports | 0 |
|
||||
| feature LOC (모든 `.ts` 파일) | 295 |
|
||||
| feature 밖으로 나가는 import 문(`contracts/errors`, `contracts/result`, `application-api`, `feature-adapter-contribution`) | 7 |
|
||||
| 브라우저 기본 IndexedDB API 참조 | 0 |
|
||||
| `src/adapters/storage/indexeddb/**` import | 0 |
|
||||
| `src/application/ports/browser-file-storage/**` import | 0 |
|
||||
|
||||
The feature does not import the storage runtime or its port, so removing the
|
||||
browser file/storage runtime (`test:browser-file-storage-removal`) leaves it
|
||||
compiling.
|
||||
이 feature는 storage runtime도 그 port도 import하지 않는다.
|
||||
그래서 브라우저 file/storage runtime을 지워도(`test:browser-file-storage-removal`) 계속 컴파일된다.
|
||||
|
||||
The contract test rejects feature source that reaches for
|
||||
계약 테스트는 다음에 손대는 feature 코드를 거부한다.
|
||||
`globalThis.indexedDB`, `IDBFactory`, `IDBDatabase`, `IDBTransaction`,
|
||||
`IDBObjectStore`, the concrete IndexedDB adapter directory or the
|
||||
browser-file-storage port.
|
||||
`IDBObjectStore`, 구체 IndexedDB adapter 디렉터리, browser-file-storage port다.
|
||||
|
||||
## What this does and does not prove
|
||||
## 이것이 증명하는 것과 증명하지 않는 것
|
||||
|
||||
The contract probe confirms that **feature business code does not need native
|
||||
IndexedDB knowledge** once an `IndexedDbRepositoryPort` has been composed.
|
||||
The browser-capability proof additionally confirms that the same feature
|
||||
contribution works when that port is backed by the repository's real
|
||||
`createIndexedDbRuntime` and native IndexedDB implementation.
|
||||
계약 탐침은 `IndexedDbRepositoryPort`가 조립되고 나면
|
||||
**feature 업무 코드에 브라우저 기본 IndexedDB 지식이 필요 없다**는 것을 확인한다.
|
||||
브라우저 capability 증명은 하나를 더 확인한다.
|
||||
그 port 뒤에 이 repo의 실제 `createIndexedDbRuntime`과 브라우저 기본 IndexedDB 구현이 있어도,
|
||||
같은 feature contribution이 동작한다는 것이다.
|
||||
|
||||
It does not prove that composition of `createIndexedDbRuntime` is cheap.
|
||||
That constructor still owns substantial infrastructure policy:
|
||||
`createIndexedDbRuntime`을 조립하는 비용이 싸다는 것은 증명하지 않는다.
|
||||
이 생성 함수는 여전히 상당한 인프라 정책을 갖고 있다.
|
||||
|
||||
- dataset scope and storage policy,
|
||||
- physical store governance,
|
||||
- retention/idempotency stores,
|
||||
- schema migrations,
|
||||
- codec and query policy,
|
||||
- lifecycle authority,
|
||||
- durability, scheduling and observation.
|
||||
- dataset 범위와 저장 정책
|
||||
- 물리 store 관리
|
||||
- 보존·멱등성(idempotency) store
|
||||
- schema 마이그레이션
|
||||
- codec과 조회 정책
|
||||
- 수명 주기 권한(lifecycle authority)
|
||||
- 내구성, 스케줄링, 관측
|
||||
|
||||
That complexity belongs at the composition/platform boundary, not in the
|
||||
feature. The Local Draft vertical slice is now the second concrete consumer, and
|
||||
it confirms that the stable seam is the typed repository provider plus a
|
||||
feature-owned repository identity. It does **not** show that dataset scope,
|
||||
retention, migration, codec or lifecycle-authority configuration can be safely
|
||||
collapsed into one universal `create...Repository<T>` factory.
|
||||
이 복잡함은 feature가 아니라 조립·플랫폼 경계에 둔다.
|
||||
Local Draft 세로 slice는 이제 두 번째 구체 소비자다.
|
||||
이 소비자는 안정된 연결 지점(seam)이 타입이 있는 repository provider와,
|
||||
feature가 소유한 repository 식별자라는 것을 확인한다.
|
||||
dataset 범위, 보존, 마이그레이션, codec, 수명 주기 권한 설정을 만능
|
||||
`create...Repository<T>` factory 하나로 안전하게 합칠 수 있다는 것은 보여 주지 **않는다**.
|
||||
|
||||
A convenience profile should therefore be introduced only after another
|
||||
IndexedDB-backed product feature repeats the same infrastructure policy, not
|
||||
merely because two features consume the same repository port.
|
||||
그래서 편의 프로필은 IndexedDB를 쓰는 다른 제품 feature가 같은 인프라 정책을 되풀이한 뒤에만 들인다.
|
||||
두 feature가 같은 repository port를 쓴다는 이유만으로 들이지 않는다.
|
||||
|
||||
## Consumer-quality review checklist
|
||||
## 소비자 품질 검토 체크리스트
|
||||
|
||||
For each new product feature, record:
|
||||
새 제품 feature마다 다음을 기록한다.
|
||||
|
||||
- feature-owned adapter LOC,
|
||||
- platform glue LOC,
|
||||
- files changed,
|
||||
- central catalog edits,
|
||||
- direct imports from capability-internal modules,
|
||||
- native browser/network API references,
|
||||
- duplicated failure/retry/lifecycle policy.
|
||||
- feature가 소유한 adapter LOC
|
||||
- 플랫폼 연결 코드(glue) LOC
|
||||
- 바뀐 파일
|
||||
- 중앙 카탈로그 수정
|
||||
- capability 내부 모듈 직접 import
|
||||
- 브라우저·네트워크 기본 API 참조
|
||||
- 중복된 실패·retry·수명 주기 정책
|
||||
|
||||
A healthy feature path should look like:
|
||||
건강한 feature 경로는 다음 모양이다.
|
||||
|
||||
1. domain type and invariant,
|
||||
2. use case,
|
||||
3. business port,
|
||||
4. feature-owned mapper/codec and policy,
|
||||
5. capability-specific binding,
|
||||
6. presentation controller/page.
|
||||
1. domain 타입과 불변식
|
||||
2. use case
|
||||
3. 업무 port
|
||||
4. feature가 소유한 mapper·codec과 정책
|
||||
5. capability 전용 binding
|
||||
6. presentation controller·페이지
|
||||
|
||||
The feature should not need the retry scheduler, abort ownership,
|
||||
effect-certainty machinery, IndexedDB transaction lifecycle, OPFS journal,
|
||||
reconnect coordinator or provider process model.
|
||||
feature는 다음을 알 필요가 없어야 한다.
|
||||
retry scheduler, abort 소유, effect-certainty 장치, IndexedDB transaction 수명 주기,
|
||||
OPFS journal, 재연결 coordinator, provider 프로세스 모델이다.
|
||||
|
||||
@@ -1,124 +1,115 @@
|
||||
# Contract ownership
|
||||
# 계약 소유
|
||||
|
||||
`src/contracts` is not a default destination for every shared-looking type.
|
||||
A contract belongs there only when the change authority is genuinely shared
|
||||
across layers, capabilities, build tooling, or runtime composition.
|
||||
`src/contracts`는 공유되는 것처럼 보이는 타입을 모두 넣는 기본 자리가 아니다.
|
||||
계약을 바꿀 권한이 계층, capability, 빌드 도구, runtime 조립 사이에 정말로 나뉘어 있을 때만 계약이 거기 들어간다.
|
||||
|
||||
## Decision rule
|
||||
## 판단 규칙
|
||||
|
||||
For every proposed contract, ask:
|
||||
제안된 계약마다 묻는다.
|
||||
|
||||
1. Which requirement can cause this type or policy to change?
|
||||
2. Is there one clear capability or feature owner?
|
||||
3. Does another runtime/tooling boundary consume the same semantic contract?
|
||||
4. Is the contract a wire/artifact authority shared by browser runtime and
|
||||
build/release tooling?
|
||||
1. 어떤 요구 사항이 이 타입이나 정책을 바꾸게 할 수 있나?
|
||||
2. 분명한 capability owner나 feature owner가 하나 있나?
|
||||
3. 다른 runtime 경계나 도구 경계가 같은 의미의 계약을 쓰나?
|
||||
4. 이 계약이 브라우저 runtime과 빌드·release 도구가 함께 따르는
|
||||
wire 형식이나 산출물(artifact)의 기준인가?
|
||||
|
||||
The placement rule is:
|
||||
두는 자리는 다음 규칙으로 정한다.
|
||||
|
||||
- one feature owner -> keep it under that feature,
|
||||
- one reusable capability owner -> keep it under that adapter/capability and
|
||||
export it through the capability public entry point,
|
||||
- a product-neutral primitive any layer may call, with no product vocabulary
|
||||
in it (a budget, deadline, retry, execution context, telemetry pipeline step
|
||||
or error envelope) -> `src/platform`,
|
||||
- multiple independent capability/layer owners -> `src/contracts`,
|
||||
- browser/build/release wire or artifact authority -> `src/contracts` even
|
||||
when the browser source graph alone looks small.
|
||||
- feature owner가 하나 -> 그 feature 아래에 둔다.
|
||||
- 재사용 capability owner가 하나 -> 그 adapter·capability 아래에 둔다.
|
||||
그리고 capability의 공개 진입점으로 export한다.
|
||||
- 어느 계층이든 부를 수 있고 제품 어휘가 들어 있지 않은 제품 중립 primitive
|
||||
(budget, deadline, retry, 실행 context, telemetry pipeline 단계, 오류 envelope) -> `src/platform`
|
||||
- 서로 독립된 capability·계층 owner가 여럿 -> `src/contracts`
|
||||
- 브라우저·빌드·release가 함께 따르는 wire 형식이나 산출물의 기준 -> `src/contracts`.
|
||||
브라우저 소스 그래프만 보면 작아 보여도 그렇다.
|
||||
|
||||
Consumer count alone is not sufficient. Scripts, generated artifacts and
|
||||
release gates are semantic consumers too.
|
||||
소비자 수만으로는 판단할 수 없다. script, 생성된 산출물, release gate도 의미상의 소비자다.
|
||||
|
||||
`src/platform` and `src/contracts` differ in what they hold. `src/contracts`
|
||||
holds the product's shared vocabulary: registries, schemas and wire formats
|
||||
such as routes, API operations, storage keys and release artifacts.
|
||||
`src/platform` holds mechanisms that work without that vocabulary, plus the
|
||||
few error kinds no feature owns (network, deadline, cancellation, response
|
||||
bounds). Today `src/contracts` imports `src/platform` and not the other way
|
||||
round. `platform-kernel-is-product-neutral` stops `src/platform` from importing
|
||||
any feature, context, app, adapter, bootstrap, presentation or application
|
||||
module. A primitive that needs a route, an API operation or a feature's
|
||||
vocabulary is not product-neutral: put it in `src/contracts` or with its owner.
|
||||
`src/platform`과 `src/contracts`는 담는 것이 다르다.
|
||||
`src/contracts`는 제품의 공유 어휘를 담는다.
|
||||
라우트, API operation, storage key, release 산출물 같은 registry, schema, wire 형식이다.
|
||||
`src/platform`은 그 어휘 없이 동작하는 장치를 담는다.
|
||||
그리고 어느 feature도 소유하지 않는 몇 가지 오류 종류(network, deadline, 취소, 응답 한도)도 담는다.
|
||||
지금은 `src/contracts`가 `src/platform`을 import하고, 반대 방향은 없다.
|
||||
`platform-kernel-is-product-neutral`은 `src/platform`이 feature, context, app, adapter,
|
||||
bootstrap, presentation, application 모듈을 import하지 못하게 막는다.
|
||||
라우트, API operation, feature 어휘가 필요한 primitive는 제품 중립이 아니다.
|
||||
그런 것은 `src/contracts`에 두거나 그 owner 곁에 둔다.
|
||||
|
||||
## Audit result
|
||||
## 감사 결과
|
||||
|
||||
The September 2026 architecture review triggered an import-graph audit of all
|
||||
39 contract files.
|
||||
2026년 9월 아키텍처 리뷰를 계기로 계약 파일 39개 전체의 import 그래프를 감사했다.
|
||||
|
||||
### Capability-owned contract moved
|
||||
### capability 소유 계약을 옮김
|
||||
|
||||
`cursor-pagination.ts` had one production owner:
|
||||
`src/adapters/query-cache/cursor-pagination-runtime.ts`.
|
||||
`cursor-pagination.ts`를 운영 코드에서 소유한 곳은 하나였다.
|
||||
`src/adapters/query-cache/cursor-pagination-runtime.ts`다.
|
||||
|
||||
It moved to:
|
||||
이 파일은 다음으로 옮겼다.
|
||||
|
||||
`src/adapters/query-cache/cursor-pagination-contract.ts`
|
||||
|
||||
and is exported through:
|
||||
그리고 다음을 거쳐 export된다.
|
||||
|
||||
`src/adapters/query-cache/index.ts`
|
||||
|
||||
Tests use that public capability entry point. Pagination vocabulary no longer
|
||||
occupies the global contract bucket merely because it is reusable inside one
|
||||
adapter.
|
||||
테스트도 그 capability 공개 진입점을 쓴다.
|
||||
pagination 어휘는 이제 adapter 하나 안에서 재사용된다는 이유만으로 전역 계약 자리를 차지하지 않는다.
|
||||
|
||||
### Contracts intentionally kept global
|
||||
### 일부러 전역에 둔 계약
|
||||
|
||||
The following examples have multiple semantic owners and remain global:
|
||||
다음 예는 의미상의 owner가 여럿이라 전역에 남는다.
|
||||
|
||||
- `errors.ts` — application, presentation and several adapters,
|
||||
- `result.ts` — common success/failure carrier below application,
|
||||
- `boundary-mapper.ts` — HTTP, browser RPC, realtime and feature registries,
|
||||
- `mutation-intent.ts` — application, presentation, HTTP, platform and
|
||||
bootstrap,
|
||||
- `exact-snapshot.ts` — HTTP, query-cache and browser-transfer,
|
||||
- `rest-profiles.ts` — auth, HTTP, bootstrap and feature contract validation,
|
||||
- `errors.ts` — application, presentation, 여러 adapter
|
||||
- `result.ts` — application 아래에서 쓰는 공통 성공·실패 운반 타입
|
||||
- `boundary-mapper.ts` — HTTP, 브라우저 RPC, realtime, feature registry
|
||||
- `mutation-intent.ts` — application, presentation, HTTP, platform,
|
||||
bootstrap
|
||||
- `exact-snapshot.ts` — HTTP, query-cache, browser-transfer
|
||||
- `rest-profiles.ts` — auth, HTTP, bootstrap, feature 계약 검증
|
||||
- `query-invalidation.ts` / `query-keys.ts` — query-cache, presentation,
|
||||
bootstrap and features,
|
||||
- `cache-invalidation.ts` — cross-context wire protocol plus query
|
||||
invalidation policy,
|
||||
- `storage-keys.ts` — browser storage and cross-context invalidation,
|
||||
- `telemetry.ts` / `diagnostics.ts` — runtime adapters, application and
|
||||
bootstrap.
|
||||
bootstrap, feature
|
||||
- `cache-invalidation.ts` — cross-context wire 프로토콜과 query
|
||||
무효화 정책
|
||||
- `storage-keys.ts` — 브라우저 storage와 cross-context 무효화
|
||||
- `telemetry.ts` / `diagnostics.ts` — runtime adapter, application,
|
||||
bootstrap
|
||||
|
||||
Some contracts appear to have few browser-source consumers but are still shared
|
||||
authorities:
|
||||
어떤 계약은 브라우저 소스에서 쓰는 곳이 적어 보이지만, 여전히 여러 곳이 함께 따르는 기준이다.
|
||||
|
||||
- `env.ts` is consumed by bootstrap, runtime-schema/security tests and
|
||||
registry governance,
|
||||
- `deployment-admission.ts` is shared by runtime-config generation and release
|
||||
admission,
|
||||
- `release-tokens.ts` is shared by runtime coherence tooling and tests,
|
||||
- `service-worker-static-manifest.ts` is a runtime-neutral canonical format
|
||||
shared by build generation, validation and service-worker evidence.
|
||||
- `env.ts`는 bootstrap, runtime-schema·보안 테스트,
|
||||
registry governance가 쓴다.
|
||||
- `deployment-admission.ts`는 runtime-config 생성과 release
|
||||
승인(admission)이 함께 쓴다.
|
||||
- `release-tokens.ts`는 runtime 정합성 도구와 테스트가 함께 쓴다.
|
||||
- `service-worker-static-manifest.ts`는 runtime에 묶이지 않는 정식 형식이다.
|
||||
빌드 생성, 검증, Service Worker 증거가 함께 쓴다.
|
||||
|
||||
Moving those based only on `src/**` import counts would split one semantic
|
||||
authority across processes.
|
||||
`src/**`의 import 수만 보고 이것들을 옮기면, 의미상 하나인 기준이 여러 프로세스로 쪼개진다.
|
||||
|
||||
## Feature contracts
|
||||
## feature 계약
|
||||
|
||||
Feature-specific contracts stay inside the vertical slice:
|
||||
feature 전용 계약은 세로 slice 안에 둔다.
|
||||
|
||||
`features/<feature>/contracts`
|
||||
|
||||
A feature owns its routes, schemas, mapper definitions, message catalogs and
|
||||
contribution identities (`create:feature` writes them under its `contracts/`). Central installed files aggregate those
|
||||
contributions; they do not own their semantics.
|
||||
feature는 자기 라우트, schema, mapper 정의, message 카탈로그,
|
||||
contribution 식별자를 소유한다(`create:feature`가 이것들을 그 feature의 `contracts/` 아래에 쓴다).
|
||||
중앙 설치 파일은 이 contribution을 모을 뿐, 그 의미를 소유하지 않는다.
|
||||
|
||||
The message catalog is a deliberate special case: the compiled catalog remains
|
||||
total even when a feature is build-time disabled so the typed message lookup
|
||||
does not become partial. The central message file therefore aggregates compiled
|
||||
message keys rather than treating runtime installation as message ownership.
|
||||
message 카탈로그는 일부러 둔 예외다.
|
||||
빌드 때 feature를 꺼도 컴파일된 카탈로그는 모든 키를 그대로 갖는다.
|
||||
그래야 타입이 있는 message 조회가 일부 키에서 비지 않는다(partial이 되지 않는다).
|
||||
그래서 중앙 message 파일은 컴파일된 message 키를 모은다.
|
||||
runtime에 설치됐다는 사실을 message 소유로 보지 않는다.
|
||||
|
||||
## Review rule for future additions
|
||||
## 앞으로 더할 때의 리뷰 규칙
|
||||
|
||||
A new file under `src/contracts` should be rejected during review when all of
|
||||
the following are true:
|
||||
`src/contracts` 아래 새 파일은 다음이 모두 참이면 리뷰에서 거부한다.
|
||||
|
||||
- one feature or one capability is the only semantic owner,
|
||||
- no build/release/runtime wire authority needs the same definition,
|
||||
- moving the definition to that owner does not create an inward dependency
|
||||
violation.
|
||||
- 의미상의 owner가 feature 하나나 capability 하나뿐이다.
|
||||
- 같은 정의가 필요한 빌드·release·runtime wire 기준이 없다.
|
||||
- 정의를 그 owner로 옮겨도 안쪽 방향 의존성 규칙을 어기지 않는다.
|
||||
|
||||
Do not move a contract merely to reduce the number 39. The goal is explicit
|
||||
ownership, not a smaller directory.
|
||||
39라는 숫자를 줄이려고 계약을 옮기지 않는다. 목표는 디렉터리를 작게 하는 것이 아니라 소유를 분명히 하는 것이다.
|
||||
|
||||
@@ -1,42 +1,44 @@
|
||||
# Frontend Application Foundation
|
||||
# 프론트엔드 애플리케이션 기반(Frontend Application Foundation)
|
||||
|
||||
This repository is not treated as a minimal React project template and it is not
|
||||
an independent general-purpose SDK. Its architectural role is:
|
||||
이 repo를 최소한의 React 프로젝트 템플릿으로 보지 않는다. 독립된 범용 SDK도
|
||||
아니다.
|
||||
아키텍처에서 맡는 역할은 다음과 같다:
|
||||
|
||||
> Frontend Application Foundation = Starter / Composition Skeleton + Reusable Capability Platform
|
||||
> Frontend Application Foundation = 시작 골격(Starter / Composition Skeleton) + 재사용 capability 플랫폼(Reusable Capability Platform)
|
||||
|
||||
The starter side owns bootstrap, routing, providers, project conventions and
|
||||
the `create:feature` command that writes a feature; it ships no sample feature. The capability side owns reusable technical
|
||||
problems such as HTTP execution, Server State, authentication boundaries,
|
||||
IndexedDB/OPFS, Cache Storage, realtime, browser RPC, transfer and diagnostics.
|
||||
시작 골격 쪽은 bootstrap, 라우팅, provider, 프로젝트 규약, feature를 만들어
|
||||
주는 `create:feature` 명령을 맡는다. 예시 feature는 싣지 않는다. capability
|
||||
쪽은 재사용할 기술 문제를 맡는다. HTTP 실행, Server State, 인증 경계,
|
||||
IndexedDB/OPFS, Cache Storage, realtime, 브라우저 RPC, 전송(transfer), 진단
|
||||
같은 것이다.
|
||||
|
||||
The cost of a sophisticated capability is acceptable only when product features
|
||||
do not have to understand that internal sophistication.
|
||||
정교한 capability의 비용은 제품 feature가 그 내부의 정교함을 몰라도 될 때만
|
||||
받아들일 수 있다.
|
||||
|
||||
## Hybrid architecture
|
||||
## 하이브리드 아키텍처
|
||||
|
||||
`src/` has nine top-level folders. The descriptions match the table in
|
||||
[the layer contract](./layers.md), which also names every import rule.
|
||||
`src/`에는 최상위 폴더가 아홉 개 있다. 설명은 [계층 계약](./layers.md)의
|
||||
표와 같다. 그 문서는 모든 import 규칙도 적는다.
|
||||
|
||||
Platform code is horizontal:
|
||||
platform 코드는 가로(수평)로 놓인다:
|
||||
|
||||
- `src/bootstrap` — the composition root: runtime configuration, concrete adapter construction and the React mount
|
||||
- `src/presentation` — generic UI and the inbound adapter: routes, layouts, the design system, pages and providers
|
||||
- `src/adapters` — reusable capability runtimes that implement application ports: HTTP, auth, storage, query cache, telemetry, workers and more
|
||||
- `src/application` — generic use cases, ports, policies and view-models
|
||||
- `src/contracts` — shared vocabulary and registries read by several layers, the workers and the build and release scripts
|
||||
- `src/platform` — product-neutral primitives any folder may use: budgets, execution context, resilience, the telemetry pipeline, error envelopes and release coherence
|
||||
- `src/bootstrap` — 조립 루트: 런타임 설정, 구체 adapter 생성, React 마운트
|
||||
- `src/presentation` — 범용 UI와 inbound adapter: 라우트, 레이아웃, 디자인 시스템, 페이지, provider
|
||||
- `src/adapters` — application 포트를 구현하는 재사용 capability 런타임: HTTP, 인증, 저장소, query cache, telemetry, worker 등
|
||||
- `src/application` — 범용 use case, 포트, 정책, view-model
|
||||
- `src/contracts` — 여러 계층·worker·빌드와 릴리스 스크립트가 같이 읽는 공용 어휘와 registry
|
||||
- `src/platform` — 어느 폴더든 쓸 수 있는 제품 중립 기본 요소: 예산, 실행 context, 복원력, telemetry 파이프라인, 오류 envelope, 릴리스 정합성
|
||||
|
||||
Ownership declarations group features into deployable units:
|
||||
소유 선언이 feature를 배포 단위로 묶는다:
|
||||
|
||||
- `src/apps` — deployable apps: each `app-module.ts` declares an app and its context budget; `template-app.ts` is the app this build produces
|
||||
- `src/contexts` — bounded contexts: each `context-module.ts` declares its app, route root and feature budget
|
||||
- `src/apps` — 배포 단위 앱: 각 `app-module.ts`가 앱과 그 context 예산을 선언한다. `template-app.ts`가 이 빌드가 만드는 앱이다
|
||||
- `src/contexts` — bounded context: 각 `context-module.ts`가 소속 앱, 라우트 루트, 기능 예산을 선언한다
|
||||
|
||||
Product business code is vertical:
|
||||
제품 비즈니스 코드는 세로(수직)로 놓인다:
|
||||
|
||||
- `src/features` — removable vertical slices (`src/features/<id>/{domain,application,contracts,adapters,presentation}`) and the installed-feature catalogs (`src/features/*.ts`)
|
||||
- `src/features` — 지울 수 있는 수직 slice(`src/features/<id>/{domain,application,contracts,adapters,presentation}`)와 설치된 기능 목록(`src/features/*.ts`)
|
||||
|
||||
Inside one feature:
|
||||
feature 하나 안에는 다음이 있다:
|
||||
|
||||
- `features/<feature>/domain`
|
||||
- `features/<feature>/application`
|
||||
@@ -44,7 +46,7 @@ Inside one feature:
|
||||
- `features/<feature>/adapters`
|
||||
- `features/<feature>/presentation`
|
||||
|
||||
The dependency model is:
|
||||
의존성 모델은 다음과 같다:
|
||||
|
||||
Domain / Use case
|
||||
|
|
||||
@@ -63,143 +65,144 @@ The dependency model is:
|
||||
v
|
||||
Browser / network / native API
|
||||
|
||||
A use case never imports a platform adapter. Generic binding happens in the
|
||||
feature adapter/composition seam.
|
||||
use case는 platform adapter를 절대 import하지 않는다. 범용 바인딩은 feature의
|
||||
adapter·조립 이음매(seam)에서 일어난다.
|
||||
|
||||
## Capability-specific typed bindings
|
||||
## capability별 타입 바인딩
|
||||
|
||||
Do not introduce one universal `Repository<TKey, TValue>` abstraction for HTTP,
|
||||
storage, realtime and transfer. Their lifecycle and failure semantics differ.
|
||||
HTTP, storage, realtime, transfer를 하나의 범용 `Repository<TKey, TValue>`
|
||||
추상화로 묶지 않는다. 넷은 lifecycle과 실패의 의미가 서로 다르다.
|
||||
|
||||
A reusable capability boundary is composed from:
|
||||
재사용 capability 경계는 다음으로 조립한다:
|
||||
|
||||
- generic input/output types,
|
||||
- feature-owned mapper or codec,
|
||||
- feature-selected policy,
|
||||
- one capability-specific runtime.
|
||||
- 범용 입력·출력 타입,
|
||||
- feature가 소유한 mapper 또는 codec,
|
||||
- feature가 고른 정책,
|
||||
- capability 전용 runtime 하나.
|
||||
|
||||
The HTTP path is the first concrete example.
|
||||
`src/adapters/http/feature-http-binding.ts` owns transport/outcome
|
||||
normalization. A feature `create:feature` writes contributes only:
|
||||
HTTP 경로가 첫 구체 예다.
|
||||
`src/adapters/http/feature-http-binding.ts`가 전송과 결과의 정규화를 맡는다.
|
||||
`create:feature`가 만든 feature가 내놓는 것은 다음뿐이다:
|
||||
|
||||
- operation ID,
|
||||
- route ID,
|
||||
- exact request input type,
|
||||
- exact success value type,
|
||||
- wire-to-domain mapper.
|
||||
- 정확한 요청 입력 타입,
|
||||
- 정확한 성공 값 타입,
|
||||
- wire 형식을 domain으로 바꾸는 mapper.
|
||||
|
||||
The feature gateway therefore does not reimplement timeout, cancellation,
|
||||
transport failure, authentication failure or contract-violation projection.
|
||||
그래서 feature gateway는 timeout, 취소, 전송 실패, 인증 실패, contract 위반
|
||||
투영을 다시 구현하지 않는다.
|
||||
|
||||
Storage, realtime and transfer may gain their own typed binders only after
|
||||
actual feature repetition demonstrates the need. They must not be forced
|
||||
through the HTTP abstraction.
|
||||
storage, realtime, transfer는 실제 feature에서 반복이 생겨 필요가 드러난
|
||||
뒤에야 자기 타입 바인더를 가질 수 있다. 이 셋을 HTTP 추상화에 억지로
|
||||
끼우면 안 된다.
|
||||
|
||||
## Custom adapter escape hatch
|
||||
## 직접 만드는 adapter라는 탈출구
|
||||
|
||||
A product feature uses a reusable capability when the capability preserves the
|
||||
business requirement.
|
||||
제품 feature는 재사용 capability가 비즈니스 요구를 지켜 줄 때 그 capability를
|
||||
쓴다.
|
||||
|
||||
If a platform contract would require changing or weakening the business model,
|
||||
the feature implements a custom outbound adapter behind the same application
|
||||
port. The architecture boundary remains stable; platform reuse is optional.
|
||||
platform contract 때문에 비즈니스 모델을 바꾸거나 약하게 해야 한다면, feature는
|
||||
같은 application port 뒤에 직접 만든 outbound adapter를 구현한다. 아키텍처
|
||||
경계는 그대로다. platform 재사용은 선택이다.
|
||||
|
||||
## Feature installation
|
||||
## feature 설치
|
||||
|
||||
A feature owns its contract, runtime and adapter contributions.
|
||||
feature는 자기 contract, runtime, adapter contribution을 소유한다.
|
||||
|
||||
Central installed catalogs are aggregation points only:
|
||||
중앙의 설치 목록(catalog)은 모으는 지점일 뿐이다:
|
||||
|
||||
- `installed-product-manifest.ts`: which product features are compiled/selected
|
||||
- `installed-feature-contracts.ts`: boot-time contract aggregation (routes,
|
||||
route runtime contracts, invalidation) from the feature declarations
|
||||
- `installed-feature-adapters.ts`: application-input loaders, one per active
|
||||
feature, run when the router enters the feature's routes (15-01)
|
||||
- `installed-contract-contributions.ts`: declared contract packages and the
|
||||
registry the HTTP executor resolves against, filled as features load
|
||||
- `installed-feature-runtime-registries.ts`: loads every runtime half and
|
||||
composes the contract contributions, the FE-REG-API rows projected from
|
||||
them and the FE-REG-SCHEMA registry; the platform overview page calls it
|
||||
after it draws its title (1103/15-01), the boot never does
|
||||
- `loaded-feature-runtimes.ts`: the same registries as module constants (top-
|
||||
level await) for Node scripts, tests and registry governance; nothing under
|
||||
`src` may import it (`boot-does-not-load-every-feature-runtime`)
|
||||
- `installed-product-manifest.ts`: 어떤 제품 feature를 컴파일하고 고르는지
|
||||
- `installed-feature-contracts.ts`: feature 선언에서 boot 시점 contract(라우트,
|
||||
라우트 runtime contract, 무효화)를 모은다
|
||||
- `installed-feature-adapters.ts`: 활성 feature마다 하나씩 있는
|
||||
application-input loader. router가 그 feature의 라우트에 들어갈 때
|
||||
실행된다(15-01)
|
||||
- `installed-contract-contributions.ts`: 선언된 contract 패키지와, HTTP
|
||||
executor가 해석할 때 쓰는 registry. feature가 로드될 때 채워진다
|
||||
- `installed-feature-runtime-registries.ts`: 모든 runtime 쪽 절반을 불러와
|
||||
contract contribution, 거기서 투영한 FE-REG-API 행, FE-REG-SCHEMA registry를
|
||||
조립한다. platform 개요 페이지가 제목을 그린 뒤 이 파일을 부른다
|
||||
(1103/15-01). boot는 절대 부르지 않는다
|
||||
- `loaded-feature-runtimes.ts`: 같은 registry를 모듈 상수(top-level await)로
|
||||
둔 것. Node 스크립트, 테스트, registry 관리(governance)가 쓴다. `src` 아래
|
||||
어떤 코드도 이 파일을 import하면 안 된다
|
||||
(`boot-does-not-load-every-feature-runtime`)
|
||||
|
||||
Feature-specific composition belongs under the feature itself. Central
|
||||
catalogs must not grow feature-specific branching logic.
|
||||
feature 전용 조립은 그 feature 아래에 둔다. 중앙 목록에 feature별 분기 로직을
|
||||
늘리면 안 된다.
|
||||
|
||||
Adapter contributions declare the platform capabilities they consume through
|
||||
`needs`. The generic contribution seam in
|
||||
`src/features/feature-adapter-contribution.ts` derives the context from that
|
||||
list, so an HTTP-only feature cannot reach IndexedDB and an IndexedDB-only
|
||||
feature does not receive the HTTP executor. It also binds
|
||||
`featureId -> ApplicationFeatureInputs[featureId]` at the contribution
|
||||
definition site instead of recovering that relationship with a final catalog
|
||||
cast.
|
||||
adapter contribution은 자기가 쓰는 platform capability를 `needs`로 선언한다.
|
||||
`src/features/feature-adapter-contribution.ts`의 범용 contribution 이음매가 그
|
||||
목록에서 context를 만든다. 그래서 HTTP만 쓰는 feature는 IndexedDB에 닿지
|
||||
못한다. IndexedDB만 쓰는 feature는 HTTP executor를 받지 않는다. 이 이음매는
|
||||
`featureId -> ApplicationFeatureInputs[featureId]` 관계도 contribution을
|
||||
정의하는 자리에서 묶는다. 마지막에 목록을 타입 캐스트해서 그 관계를 되찾지
|
||||
않는다.
|
||||
|
||||
A contribution becomes composable only through
|
||||
`defineFeatureAdapterContribution()`. That factory adds the private
|
||||
contribution brand required by `composeFeatureAdapterInputs()`; a raw object
|
||||
with the same visible fields is rejected by TypeScript and checked again at
|
||||
runtime. The negative type fixture
|
||||
`invalid-direct-feature-composition.ts` is part of FE-GATE-003 so this
|
||||
authority cannot be bypassed by calling the composer directly.
|
||||
contribution은 `defineFeatureAdapterContribution()`을 거쳐야만 조립할 수
|
||||
있다. 이 factory는 `composeFeatureAdapterInputs()`가 요구하는 비공개
|
||||
contribution brand를 붙인다. 겉으로 보이는 필드가 같은 날 객체는 TypeScript가
|
||||
거부하고, runtime에서도 다시 검사한다. 음성 타입 fixture
|
||||
`invalid-direct-feature-composition.ts`가 FE-GATE-003에 들어 있다. 그래서
|
||||
composer를 직접 불러 이 권한을 우회할 수 없다.
|
||||
|
||||
For IndexedDB-backed features, `createIndexedDbRepositoryProvider()` is the
|
||||
composition helper that maps feature-owned repository identities to typed
|
||||
`IndexedDbRepositoryPort` instances. It does not create a universal storage
|
||||
repository or move dataset/migration/lifecycle policy into the feature.
|
||||
IndexedDB를 쓰는 feature에서는 `createIndexedDbRepositoryProvider()`가 조립
|
||||
헬퍼다. 이 헬퍼는 feature가 소유한 repository 식별자를 타입이 붙은
|
||||
`IndexedDbRepositoryPort` 인스턴스에 연결한다. 범용 storage repository를
|
||||
만들지 않는다. dataset·migration·lifecycle 정책을 feature로 옮기지도 않는다.
|
||||
|
||||
The repository now has two executable contribution shapes:
|
||||
지금 repo에는 실행 가능한 contribution 모양이 둘 있다:
|
||||
|
||||
- A feature `create:feature` writes: `needs: ["http", "telemetry"]`
|
||||
- The Local Draft consumer: `needs: ["indexedDb"]`
|
||||
- `create:feature`가 만드는 feature: `needs: ["http", "telemetry"]`
|
||||
- Local Draft consumer: `needs: ["indexedDb"]`
|
||||
|
||||
Local Draft is a test fixture (`tests/fixtures/indexeddb-consumer`) used to
|
||||
prove the second capability shape; it is not a feature of the product. Its
|
||||
browser-capability test composes the feature over the real
|
||||
`createIndexedDbRuntime` and native IndexedDB, proving that this seam is not
|
||||
limited to an in-memory contract fixture.
|
||||
Local Draft는 두 번째 capability 모양을 증명하는 테스트
|
||||
fixture(`tests/fixtures/indexeddb-consumer`)다. 제품의 feature가 아니다. 그
|
||||
browser-capability 테스트는 실제 `createIndexedDbRuntime`과 브라우저 자체
|
||||
IndexedDB 위에서 feature를 조립한다. 이 이음매가 메모리 안 contract fixture에만
|
||||
묶이지 않는다는 것을 이 테스트가 증명한다.
|
||||
|
||||
The bootstrap does not build `indexedDb`: IndexedDB is an opt-in reference
|
||||
runtime (`productionComposition: false` in
|
||||
`config/recipes/frontend-capability-recipes.json`). The composition example is
|
||||
`recipes/frontend-capabilities/indexeddb-feature-capability.ts`
|
||||
(`createLocalDraftIndexedDbCapability`, exercised by
|
||||
`tests/recipes/indexeddb-feature-capability.test.ts`). A product that installs a
|
||||
feature with `needs: ["indexedDb"]` copies it and returns `indexedDb` from the
|
||||
product-owned `src/bootstrap/product-composition.ts`. Until it does, the feature
|
||||
capabilities in `src/bootstrap/runtime-adapters.ts` fail the app typecheck, and
|
||||
`composeFeatureAdapterInputs()` rejects the composition with
|
||||
`feature <id> needs indexedDb, which the host did not provide`.
|
||||
bootstrap은 `indexedDb`를 만들지 않는다. IndexedDB는 골라야 켜지는(opt-in)
|
||||
참조 runtime이다(`config/recipes/frontend-capability-recipes.json`의
|
||||
`productionComposition: false`). 조립 예시는
|
||||
`recipes/frontend-capabilities/indexeddb-feature-capability.ts`다
|
||||
(`createLocalDraftIndexedDbCapability`. 이 함수는
|
||||
`tests/recipes/indexeddb-feature-capability.test.ts`가 실행해 본다).
|
||||
`needs: ["indexedDb"]`인 feature를 설치하는 제품은 이 예시를 복사한다. 그리고
|
||||
제품이 소유한 `src/bootstrap/product-composition.ts`에서 `indexedDb`를
|
||||
돌려준다. 그 전까지는 `src/bootstrap/runtime-adapters.ts`의 feature
|
||||
capability가 앱 타입체크에서 실패한다. 그리고 `composeFeatureAdapterInputs()`가
|
||||
`feature <id> needs indexedDb, which the host did not provide`로 조립을
|
||||
거부한다.
|
||||
|
||||
The same file is where a product adds any other capability and the
|
||||
credential provider for a product auth profile. The capability's type goes in
|
||||
the product-owned `src/features/product-capabilities.ts`
|
||||
(`ProductFeaturePlatformCapabilities`, which `FeaturePlatformCapabilities`
|
||||
extends), so every typecheck program that sees a feature sees it
|
||||
(`tests/unit/product-extension-typecheck.test.ts`). The composition root keeps the order: scope fence, `ANONYMOUS`
|
||||
profile, product provider, session, scope fence again
|
||||
(`tests/unit/runtime-adapters-credential-order.test.ts`). A product that owns
|
||||
the session itself (a BFF whose session is an httpOnly cookie) returns its
|
||||
session owner from `composeProductSessionOwner` in the same file. It is asked
|
||||
first, before `http` exists, only when `AUTH_MODE` is `external`, and it comes
|
||||
before the host's `__CA_FRONTEND_AUTH_OWNER__`; `null` leaves the session to
|
||||
that global. Its context (`src/bootstrap/product-session-owner-context.ts`)
|
||||
carries a `fetch` with one deadline over the whole exchange, the page for a
|
||||
sign-in redirect, the page's session storage for that redirect only, and
|
||||
`readCookie`. Product auth profiles, runtime-config keys and the keys'
|
||||
FE-REG-ENV rows go in `src/contracts/product-contracts.ts`; each joins the
|
||||
template's registry under the same checks
|
||||
제품이 다른 capability를 더하는 곳도 같은 파일이다. 제품 인증 profile의
|
||||
credential provider를 더하는 곳도 이 파일이다. capability의 타입은 제품이
|
||||
소유한 `src/features/product-capabilities.ts`에 둔다
|
||||
(`ProductFeaturePlatformCapabilities`. `FeaturePlatformCapabilities`가 이
|
||||
타입을 확장한다). 그래서 feature를 보는 모든 타입체크 프로그램이 이 타입도
|
||||
본다(`tests/unit/product-extension-typecheck.test.ts`). composition root는 다음
|
||||
순서를 지킨다: scope fence, `ANONYMOUS` profile, 제품 provider, session, 다시
|
||||
scope fence(`tests/unit/runtime-adapters-credential-order.test.ts`). session을
|
||||
직접 소유하는 제품(session이 httpOnly 쿠키인 BFF)은 같은 파일의
|
||||
`composeProductSessionOwner`에서 자기 session owner를 돌려준다. 이 함수는
|
||||
`AUTH_MODE`가 `external`일 때만 불린다. 불릴 때는 `http`가 생기기 전에 가장
|
||||
먼저 불리고, host의 `__CA_FRONTEND_AUTH_OWNER__`보다 앞선다. `null`을
|
||||
돌려주면 session을 그 전역 값에 맡긴다. 이 함수의 context
|
||||
(`src/bootstrap/product-session-owner-context.ts`)에는 다음이 들어 있다: 교환
|
||||
전체에 deadline 하나를 거는 `fetch`, 로그인 redirect에 쓸 페이지, 그
|
||||
redirect에만 쓰는 페이지의 session storage, `readCookie`. 제품 인증 profile,
|
||||
runtime-config 키, 그 키의 FE-REG-ENV 행은 `src/contracts/product-contracts.ts`에
|
||||
둔다. 각각 같은 검사를 거쳐 템플릿의 registry에 합류한다
|
||||
(`tests/unit/product-composition-fixture.test.ts`).
|
||||
|
||||
## Presentation consumer surface
|
||||
## presentation 소비 표면
|
||||
|
||||
`ApplicationProvider` remains the composition root for presentation, but new
|
||||
consumers should not navigate a root `ApplicationApi` service locator.
|
||||
`ApplicationProvider`는 계속 presentation의 composition root다. 하지만 새
|
||||
소비 코드는 루트 `ApplicationApi` service locator를 뒤져서 기능을 찾아가면
|
||||
안 된다.
|
||||
|
||||
Use the narrow hooks in
|
||||
`src/presentation/providers/application-provider.tsx`:
|
||||
`src/presentation/providers/application-provider.tsx`의 좁은 hook을 쓴다:
|
||||
|
||||
- `useApplicationSession`
|
||||
- `useApplicationPreferences`
|
||||
@@ -208,100 +211,96 @@ Use the narrow hooks in
|
||||
- `useApplicationRecovery`
|
||||
- `useApplicationFeature`
|
||||
|
||||
`useApplication` exists only as a deprecated compatibility escape hatch.
|
||||
`useApplication`은 deprecated된 호환용 탈출구로만 남아 있다.
|
||||
|
||||
## Canonical imports
|
||||
## 정식 import 경로
|
||||
|
||||
New feature code should use capability public entry points rather than deep
|
||||
runtime modules. For HTTP the canonical path is
|
||||
`src/adapters/http/index.ts`.
|
||||
새 feature 코드는 깊은 runtime 모듈 대신 capability의 공개 진입점을 쓴다.
|
||||
HTTP의 정식 경로는 `src/adapters/http/index.ts`다.
|
||||
|
||||
Compatibility re-exports may exist during a migration window, but they must be
|
||||
marked as compatibility/deprecated paths and should not expand into an
|
||||
unbounded public barrel.
|
||||
옮기는 기간에는 호환용 재수출이 있을 수 있다. 하지만 그 경로에는 호환용·
|
||||
deprecated 경로라는 표시를 해야 한다. 그리고 끝없이 커지는 공개 barrel로
|
||||
늘어나면 안 된다.
|
||||
|
||||
## Policy ownership
|
||||
## 정책 소유
|
||||
|
||||
Duplication is judged by ownership, not by syntax percentage.
|
||||
중복은 문법이 겹치는 비율이 아니라 소유로 판단한다.
|
||||
|
||||
Small local validators can remain duplicated when locality improves auditing.
|
||||
Business or concurrency policy must have one owner. For example the reference
|
||||
create mutation keeps definition ID, idempotency requirement, duplicate policy
|
||||
and invalidation policy in one feature-owned definition and binds only
|
||||
`scope` and `execute` per usage site.
|
||||
가까이 두는 편이 감사하기 쉬우면 작은 로컬 검증기는 중복으로 남겨도 된다.
|
||||
비즈니스 정책이나 동시성 정책은 owner가 하나여야 한다. 예를 들어 참조 create
|
||||
mutation은 정의 ID, 멱등성 요구, 중복 정책, 무효화 정책을 feature가 소유한
|
||||
정의 하나에 둔다. 사용하는 자리마다 묶는 것은 `scope`와 `execute`뿐이다.
|
||||
|
||||
## Runtime decomposition rule
|
||||
## runtime 분해 규칙
|
||||
|
||||
Large runtime files are not split by line count.
|
||||
큰 runtime 파일을 줄 수로 나누지 않는다.
|
||||
|
||||
Extract a boundary when it has its own state machine, lifecycle owner, failure
|
||||
model or compensation/recovery responsibility. Candidate seams include:
|
||||
경계에 자기만의 상태 기계, lifecycle owner, 실패 모델, 보상·복구 책임이
|
||||
있으면 그 경계를 떼어 낸다. 떼어 낼 후보 이음매는 다음과 같다:
|
||||
|
||||
- connection/open/upgrade lifecycle,
|
||||
- transaction ownership,
|
||||
- migration state machine,
|
||||
- reconnect/backoff and heartbeat,
|
||||
- subscription ownership,
|
||||
- retry/deadline/cancellation ownership,
|
||||
- settlement/reconciliation/cleanup.
|
||||
- 연결·열기·업그레이드 lifecycle,
|
||||
- 트랜잭션 소유,
|
||||
- migration 상태 기계,
|
||||
- 재연결·backoff와 heartbeat,
|
||||
- 구독 소유,
|
||||
- 재시도·deadline·취소 소유,
|
||||
- 정산(settlement)·조정(reconciliation)·정리(cleanup).
|
||||
|
||||
A cohesive 2,000-line state machine can remain together. A 300-line file with
|
||||
multiple lifecycle owners is a better extraction candidate.
|
||||
응집된 2,000줄짜리 상태 기계는 한데 둬도 된다. lifecycle owner가 여럿인
|
||||
300줄짜리 파일이 더 나은 분리 후보다.
|
||||
|
||||
### Current runtime boundary audit
|
||||
### 지금 runtime 경계 점검
|
||||
|
||||
The current large-runtime inventory was reviewed using that rule.
|
||||
지금 있는 큰 runtime 목록을 이 규칙으로 점검했다.
|
||||
|
||||
- IndexedDB remains large, but connection, transaction, migration, maintenance
|
||||
and failure translation already have separate owners/modules.
|
||||
- resumable upload already separates runtime policy, checkpoint persistence,
|
||||
HTTP control-plane transport, part execution, cancellation and mutation
|
||||
locking.
|
||||
- realtime already separates reconnect policy/coordinator, event codec/consumer
|
||||
and stream coordination.
|
||||
- OPFS is separated into browser runtime, journal, byte-store, policy and worker
|
||||
protocol/runtime responsibilities.
|
||||
- HTTP V3 still owned retry eligibility/backoff inside the execution state
|
||||
machine, so that responsibility moved to
|
||||
`src/adapters/http/http-retry-lifecycle.ts`.
|
||||
- IndexedDB는 여전히 크다. 하지만 연결, 트랜잭션, migration, 유지보수, 실패
|
||||
변환은 이미 owner·모듈이 따로 있다.
|
||||
- 이어 올리기(resumable upload)는 이미 runtime 정책, checkpoint 저장, HTTP
|
||||
제어 평면 전송, 조각(part) 실행, 취소, mutation 잠금을 나눠 두었다.
|
||||
- realtime은 이미 재연결 정책·조정자, 이벤트 codec·소비자, 스트림 조정을
|
||||
나눠 두었다.
|
||||
- OPFS는 브라우저 runtime, journal, byte-store, 정책, worker 프로토콜·runtime
|
||||
책임으로 나뉘어 있다.
|
||||
- HTTP V3는 재시도 가능 여부와 backoff를 실행 상태 기계 안에서 여전히 소유하고
|
||||
있었다. 그래서 그 책임을 `src/adapters/http/http-retry-lifecycle.ts`로
|
||||
옮겼다.
|
||||
|
||||
No other runtime is split merely because of its line count.
|
||||
다른 runtime은 줄 수만 보고 나누지 않았다.
|
||||
|
||||
## Consumer quality metrics
|
||||
## 소비 품질 지표
|
||||
|
||||
Before adding another abstraction, implement or model multiple real feature
|
||||
uses and measure:
|
||||
추상화를 하나 더 들이기 전에, 실제 feature 사용 사례 여럿을 구현하거나
|
||||
모델링하고 다음을 잰다:
|
||||
|
||||
- feature-owned adapter LOC,
|
||||
- repeated platform glue,
|
||||
- number of platform-internal types exposed to the feature,
|
||||
- central catalog edits,
|
||||
- files changed for one normal query/command,
|
||||
- whether native browser/network APIs leak into the feature.
|
||||
- feature가 소유한 adapter LOC,
|
||||
- 반복되는 platform 접착 코드(glue),
|
||||
- feature에 드러나는 platform 내부 타입 수,
|
||||
- 중앙 목록 수정 횟수,
|
||||
- 평범한 query/command 하나에 바뀌는 파일 수,
|
||||
- 브라우저·네트워크 기본 API가 feature로 새어 나오는지.
|
||||
|
||||
The target feature-development path is:
|
||||
목표로 하는 feature 개발 경로는 다음과 같다:
|
||||
|
||||
1. domain type and invariant,
|
||||
1. domain 타입과 불변식,
|
||||
2. use case,
|
||||
3. port,
|
||||
4. transport/storage schema plus mapper/codec,
|
||||
5. capability binding,
|
||||
4. 전송·저장 schema와 mapper/codec,
|
||||
5. capability 바인딩,
|
||||
6. presentation controller/page.
|
||||
|
||||
A product feature should not need to know the retry scheduler, abort ownership,
|
||||
effect-certainty machinery, transaction leases, reconnect coordinator, OPFS
|
||||
journal or provider lifecycle.
|
||||
제품 feature는 재시도 스케줄러, abort 소유, 효과 확실성(effect-certainty) 장치,
|
||||
트랜잭션 lease, 재연결 조정자, OPFS journal, provider lifecycle을 몰라도 돼야
|
||||
한다.
|
||||
|
||||
The executable REST and IndexedDB consumer baselines are recorded in
|
||||
[`capability-consumer-experience.md`](./capability-consumer-experience.md).
|
||||
Contract placement and the global-vs-owner-local audit are recorded in
|
||||
[`contract-ownership.md`](./contract-ownership.md).
|
||||
실행 가능한 REST·IndexedDB 소비 기준선은
|
||||
[`capability-consumer-experience.md`](./capability-consumer-experience.md)에
|
||||
적혀 있다. contract를 어디에 둘지와, 전역에 둘지 owner 가까이 둘지 점검한
|
||||
결과는 [`contract-ownership.md`](./contract-ownership.md)에 적혀 있다.
|
||||
|
||||
## Verification paths
|
||||
## 검증 경로
|
||||
|
||||
Product-development verification, capability verification and release assurance
|
||||
are intentionally separate. See
|
||||
[`docs/testing/taxonomy.md`](../testing/taxonomy.md).
|
||||
제품 개발 검증, capability 검증, release 보증은 일부러 나눠 두었다.
|
||||
[`docs/testing/taxonomy.md`](../testing/taxonomy.md)를 본다.
|
||||
|
||||
Host-level CI-runner tests belong to `tests/system`, not `tests/unit`.
|
||||
Reusable capability consumer contracts belong to `tests/contract`.
|
||||
host 수준 CI runner 테스트는 `tests/unit`이 아니라 `tests/system`에 둔다.
|
||||
재사용 capability의 소비 contract는 `tests/contract`에 둔다.
|
||||
|
||||
+112
-109
@@ -1,119 +1,120 @@
|
||||
# Clean Architecture layer contract
|
||||
# Clean Architecture 계층 계약
|
||||
|
||||
Dependencies point inward: `presentation -> application -> contracts ->
|
||||
platform`. Concrete adapters implement application-owned ports and are
|
||||
assembled only in `src/bootstrap`.
|
||||
의존성은 안쪽을 향한다: `presentation -> application -> contracts ->
|
||||
platform`. 구체 adapter는 application이 소유한 port를 구현한다. 구체
|
||||
adapter는 `src/bootstrap`에서만 조립된다.
|
||||
|
||||
## Top-level folders
|
||||
## 최상위 폴더
|
||||
|
||||
`src/` has these nine folders and no others:
|
||||
`src/`에는 아래 아홉 폴더만 있다:
|
||||
|
||||
| Folder | Owns |
|
||||
| 폴더 | 맡는 것 |
|
||||
| --- | --- |
|
||||
| `src/bootstrap` | the composition root: runtime configuration, concrete adapter construction and the React mount |
|
||||
| `src/apps` | deployable apps: each `app-module.ts` declares an app and its context budget; `template-app.ts` is the app this build produces |
|
||||
| `src/contexts` | bounded contexts: each `context-module.ts` declares its app, route root and feature budget |
|
||||
| `src/features` | removable vertical slices (`src/features/<id>/{domain,application,contracts,adapters,presentation}`) and the installed-feature catalogs (`src/features/*.ts`) |
|
||||
| `src/presentation` | generic UI and the inbound adapter: routes, layouts, the design system, pages and providers |
|
||||
| `src/adapters` | reusable capability runtimes that implement application ports: HTTP, auth, storage, query cache, telemetry, workers and more |
|
||||
| `src/application` | generic use cases, ports, policies and view-models |
|
||||
| `src/contracts` | shared vocabulary and registries read by several layers, the workers and the build and release scripts |
|
||||
| `src/platform` | product-neutral primitives any folder may use: budgets, execution context, resilience, the telemetry pipeline, error envelopes and release coherence |
|
||||
| `src/bootstrap` | 조립 루트: 런타임 설정, 구체 adapter 생성, React 마운트 |
|
||||
| `src/apps` | 배포 단위 앱: 각 `app-module.ts`가 앱과 그 context 예산을 선언한다. `template-app.ts`가 이 빌드가 만드는 앱이다 |
|
||||
| `src/contexts` | bounded context: 각 `context-module.ts`가 소속 앱, 라우트 루트, 기능 예산을 선언한다 |
|
||||
| `src/features` | 지울 수 있는 수직 slice(`src/features/<id>/{domain,application,contracts,adapters,presentation}`)와 설치된 기능 목록(`src/features/*.ts`) |
|
||||
| `src/presentation` | 범용 UI와 inbound adapter: 라우트, 레이아웃, 디자인 시스템, 페이지, provider |
|
||||
| `src/adapters` | application 포트를 구현하는 재사용 capability 런타임: HTTP, 인증, 저장소, query cache, telemetry, worker 등 |
|
||||
| `src/application` | 범용 use case, 포트, 정책, view-model |
|
||||
| `src/contracts` | 여러 계층·worker·빌드와 릴리스 스크립트가 같이 읽는 공용 어휘와 registry |
|
||||
| `src/platform` | 어느 폴더든 쓸 수 있는 제품 중립 기본 요소: 예산, 실행 context, 복원력, telemetry 파이프라인, 오류 envelope, 릴리스 정합성 |
|
||||
|
||||
Domain code lives inside a feature (`src/features/<id>/domain`). There is no
|
||||
top-level domain folder. If a project adds one, `domain-is-framework-neutral`
|
||||
and `concrete-adapters-compose-only-in-bootstrap` already cover it.
|
||||
domain 코드는 feature 안(`src/features/<id>/domain`)에 있다. 최상위 domain
|
||||
폴더는 없다. 프로젝트가 그런 폴더를 더해도 `domain-is-framework-neutral`과
|
||||
`concrete-adapters-compose-only-in-bootstrap`이 이미 그 폴더를 다룬다.
|
||||
|
||||
`src/adapters/platform` is the adapter kernel (below). It is not
|
||||
`src/platform`.
|
||||
`src/adapters/platform`은 adapter kernel(아래 절)이다. `src/platform`과는
|
||||
다른 폴더다.
|
||||
|
||||
Where a shared type or primitive goes is decided in
|
||||
[contract ownership](./contract-ownership.md).
|
||||
공용 타입이나 기본 요소를 어디에 둘지는
|
||||
[contract 소유권](./contract-ownership.md)에서 정한다.
|
||||
|
||||
## Rules
|
||||
## 규칙
|
||||
|
||||
Each row is one `forbidden` rule in `.dependency-cruiser.json`, by its `name`.
|
||||
"Forbids" lists what code under "Applies to" must not import.
|
||||
각 행은 `.dependency-cruiser.json`의 `forbidden` 규칙 하나이고, 그 규칙의
|
||||
`name`으로 적는다. 「금지」 칸은 「적용 대상」 칸의 코드가 import하면 안 되는
|
||||
것이다.
|
||||
|
||||
| Rule | Applies to | Forbids |
|
||||
| 규칙 | 적용 대상 | 금지 |
|
||||
| --- | --- | --- |
|
||||
| `domain-is-framework-neutral` | a top-level domain folder (none today) | application, presentation, adapters, bootstrap, React, TanStack |
|
||||
| `domain-is-framework-neutral` | 최상위 domain 폴더(지금은 없다) | application, presentation, adapters, bootstrap, React, TanStack |
|
||||
| `application-does-not-know-concrete-runtime` | `src/application` | presentation, adapters, bootstrap, React, TanStack |
|
||||
| `presentation-does-not-know-adapters` | `src/presentation`, except `adapters/query` | adapters, bootstrap, TanStack |
|
||||
| `page-templates-own-layout-only` | `src/presentation/templates` | application, adapters, bootstrap, the presentation query adapter, TanStack. Templates take data and actions as props |
|
||||
| `icon-vendor-is-facade-only` | all of `src`, except the lucide vendor facade | `lucide-react` |
|
||||
| `zod-is-reached-through-contracts-zod` | all of `src`, except `src/contracts/zod.ts` | `zod` and its subpaths (`zod/v4`) |
|
||||
| `design-system-is-reached-through-its-index` | code outside the design system and its named facades | design-system files other than its `index.ts` |
|
||||
| `presentation-does-not-know-adapters` | `src/presentation`. 단 `adapters/query`는 제외 | adapters, bootstrap, TanStack |
|
||||
| `page-templates-own-layout-only` | `src/presentation/templates` | application, adapters, bootstrap, presentation query adapter, TanStack. template은 데이터와 action을 props로 받는다 |
|
||||
| `icon-vendor-is-facade-only` | `src` 전체. 단 lucide vendor facade는 제외 | `lucide-react` |
|
||||
| `zod-is-reached-through-contracts-zod` | `src` 전체. 단 `src/contracts/zod.ts`는 제외 | `zod`와 그 하위 경로(`zod/v4`) |
|
||||
| `design-system-is-reached-through-its-index` | 디자인 시스템과 이름이 정해진 그 facade 밖의 코드 | 디자인 시스템의 `index.ts`가 아닌 디자인 시스템 파일 |
|
||||
| `adapters-do-not-know-presentation` | `src/adapters` | presentation, bootstrap |
|
||||
| `feature-domain-is-framework-neutral` | `src/features/<id>/domain` | application, presentation, adapters, bootstrap, any feature's application, adapters and presentation, React, TanStack |
|
||||
| `feature-application-does-not-know-runtime` | `src/features/<id>/application` | presentation, adapters, bootstrap, any feature's adapters and presentation, React, TanStack |
|
||||
| `feature-presentation-does-not-know-outbound-adapters` | `src/features/<id>/presentation` | adapters, bootstrap, any feature's adapters, TanStack |
|
||||
| `feature-adapters-do-not-know-presentation` | `src/features/<id>/adapters` | presentation, bootstrap, any feature's presentation |
|
||||
| `feature-domain-is-framework-neutral` | `src/features/<id>/domain` | application, presentation, adapters, bootstrap, 모든 feature의 application·adapters·presentation, React, TanStack |
|
||||
| `feature-application-does-not-know-runtime` | `src/features/<id>/application` | presentation, adapters, bootstrap, 모든 feature의 adapters·presentation, React, TanStack |
|
||||
| `feature-presentation-does-not-know-outbound-adapters` | `src/features/<id>/presentation` | adapters, bootstrap, 모든 feature의 adapters, TanStack |
|
||||
| `feature-adapters-do-not-know-presentation` | `src/features/<id>/adapters` | presentation, bootstrap, 모든 feature의 presentation |
|
||||
| `concrete-adapters-compose-only-in-bootstrap` | `src/application`, `src/presentation`, `src/contracts` | `src/adapters` |
|
||||
| `external-contract-package-single-import-path` | all of `src`, except `src/features/<id>/contracts/*-contract-contribution.ts` | the generated `@org-contracts/*` service packages |
|
||||
| `presentation-does-not-fetch-directly` | generic and feature presentation | the HTTP, realtime, service-worker, web-worker and storage adapters |
|
||||
| `unselected-realtime-runtime-is-not-composed` | `src/bootstrap`, `src/features/installed-feature-*` | the realtime and Web Push adapters, which the template does not select |
|
||||
| `generic-worker-has-no-network-or-credentials` | `src/adapters/web-worker` | the HTTP, realtime, auth and Web Push adapters |
|
||||
| `external-contract-package-single-import-path` | `src` 전체. 단 `src/features/<id>/contracts/*-contract-contribution.ts`는 제외 | 생성된 `@org-contracts/*` 서비스 패키지 |
|
||||
| `presentation-does-not-fetch-directly` | 범용 presentation과 feature presentation | HTTP, realtime, service-worker, web-worker, storage adapter |
|
||||
| `unselected-realtime-runtime-is-not-composed` | `src/bootstrap`, `src/features/installed-feature-*` | 템플릿이 고르지 않은 realtime adapter와 Web Push adapter |
|
||||
| `generic-worker-has-no-network-or-credentials` | `src/adapters/web-worker` | HTTP, realtime, auth, Web Push adapter |
|
||||
| `service-worker-entry-is-not-page-code` | `src/adapters/service-worker` | presentation, bootstrap, React, TanStack |
|
||||
| `contracts-do-not-know-application` | `src/contracts` | application, features. Contracts is the lower package and owns the vocabulary both read |
|
||||
| `contracts-do-not-know-application` | `src/contracts` | application, features. contracts가 아래쪽 패키지이고, 둘이 함께 읽는 어휘를 소유한다 |
|
||||
| `contracts-do-not-know-presentation-or-bootstrap` | `src/contracts` | presentation, bootstrap |
|
||||
| `generic-presentation-does-not-compose-the-product` | `src/presentation`, except the files the rule lists | the installed-feature registries. Which features exist is a product decision owned by `src/bootstrap` |
|
||||
| `boot-does-not-load-every-feature-runtime` | all of `src`, except the module itself | `src/features/loaded-feature-runtimes.ts` |
|
||||
| `adapters-do-not-know-other-concrete-adapters` | each adapter group | another adapter group, except the adapter kernel |
|
||||
| `adapter-groups-are-reached-through-their-barrel` | code outside `src/adapters` | adapter files other than a group's `index.ts` and the `storage/indexeddb` and `storage/opfs` sub-barrels |
|
||||
| `features-do-not-import-other-features` | each feature | another feature |
|
||||
| `contexts-do-not-import-other-contexts` | each context | another context |
|
||||
| `feature-and-app-roots-do-not-reach-adapters` | every file in `src/features` outside a feature's `adapters/` folder (the root files and any folder that is not a layer, such as `support/`), `src/contexts`, `src/apps`, except the type-only `src/features/feature-adapter-contribution.ts` | `src/adapters` |
|
||||
| `presentation-does-not-import-apps-or-contexts` | generic and feature presentation, except `src/presentation/routes/app-router.tsx`, which mounts the app's route tree | `src/apps`, `src/contexts` |
|
||||
| `observability-vendors-live-behind-adapters` | code outside `src/adapters` | vendor telemetry SDKs |
|
||||
| `platform-kernel-is-product-neutral` | `src/platform`, except `routing/`, which reads app descriptors by type | features, contexts, apps, adapters, bootstrap, presentation, application |
|
||||
| `no-circular-dependencies` | all of `src` | import cycles |
|
||||
| `generic-presentation-does-not-compose-the-product` | `src/presentation`. 단 규칙에 적힌 파일은 제외 | 설치된 feature registry. 어떤 feature가 있는지는 제품 결정이고 `src/bootstrap`이 소유한다 |
|
||||
| `boot-does-not-load-every-feature-runtime` | `src` 전체. 단 그 모듈 자신은 제외 | `src/features/loaded-feature-runtimes.ts` |
|
||||
| `adapters-do-not-know-other-concrete-adapters` | 각 adapter 그룹 | 다른 adapter 그룹. 단 adapter kernel은 제외 |
|
||||
| `adapter-groups-are-reached-through-their-barrel` | `src/adapters` 밖의 코드 | 그룹의 `index.ts`와 `storage/indexeddb`·`storage/opfs` 하위 barrel이 아닌 adapter 파일 |
|
||||
| `features-do-not-import-other-features` | 각 feature | 다른 feature |
|
||||
| `contexts-do-not-import-other-contexts` | 각 context | 다른 context |
|
||||
| `feature-and-app-roots-do-not-reach-adapters` | `src/features` 안에서 feature의 `adapters/` 폴더 밖에 있는 모든 파일(루트 파일과, `support/`처럼 계층이 아닌 모든 폴더), `src/contexts`, `src/apps`. 단 타입 전용인 `src/features/feature-adapter-contribution.ts`는 제외 | `src/adapters` |
|
||||
| `presentation-does-not-import-apps-or-contexts` | 범용 presentation과 feature presentation. 단 앱의 라우트 트리를 마운트하는 `src/presentation/routes/app-router.tsx`는 제외 | `src/apps`, `src/contexts` |
|
||||
| `observability-vendors-live-behind-adapters` | `src/adapters` 밖의 코드 | vendor telemetry SDK |
|
||||
| `platform-kernel-is-product-neutral` | `src/platform`. 단 app descriptor를 타입으로 읽는 `routing/`은 제외 | features, contexts, apps, adapters, bootstrap, presentation, application |
|
||||
| `no-circular-dependencies` | `src` 전체 | import 순환 |
|
||||
|
||||
`feature-and-app-roots-do-not-reach-adapters` exists because the graph checks
|
||||
one edge at a time. Presentation may import those files, so a re-export of an
|
||||
adapter there would carry the adapter into presentation with every other rule
|
||||
passing.
|
||||
`feature-and-app-roots-do-not-reach-adapters`가 있는 이유는 그래프가 간선을
|
||||
하나씩만 검사하기 때문이다. presentation은 그 파일들을 import할 수 있다.
|
||||
그래서 그 파일에서 adapter를 재수출하면, 다른 규칙이 모두 통과한 채로
|
||||
adapter가 presentation까지 들어온다.
|
||||
|
||||
## The adapter kernel
|
||||
## adapter kernel
|
||||
|
||||
`adapters-do-not-know-other-concrete-adapters` excludes the adapter kernel,
|
||||
which is shared on purpose and is the only adapter code an adapter may reach
|
||||
across a group for:
|
||||
`adapters-do-not-know-other-concrete-adapters`는 adapter kernel을 예외로
|
||||
둔다. kernel은 일부러 공유하는 코드다. adapter가 그룹을 넘어 가져다 쓸 수
|
||||
있는 adapter 코드는 kernel뿐이다:
|
||||
|
||||
- `src/adapters/platform/**` — mechanisms more than one adapter group shares:
|
||||
the system clock, the shared abort primitive, the bounded-capacity guard,
|
||||
the IndexedDB connection and transaction helpers, `Retry-After` parsing and
|
||||
the JSON member scanner. Two bootstrap-only platform services live there
|
||||
too: the browser lifecycle runtime and the mutation intent factory (no
|
||||
adapter imports them). A kernel file owns mechanics only, never names,
|
||||
schemas, failure codes or observation shapes; the full list of what it must
|
||||
never own is at the top of `indexeddb-connection.ts`
|
||||
- `src/adapters/browser-file-storage/result.ts` — the browser-data result and
|
||||
failure constructors
|
||||
- `src/adapters/cross-context-invalidation/index.ts` — the cross-context
|
||||
invalidation transport and its types. Any adapter may import it; today
|
||||
`query-cache` does
|
||||
- `src/adapters/platform/**` — 여러 adapter 그룹이 함께 쓰는 동작 장치:
|
||||
시스템 시계, 공용 abort 기본 요소, 용량 상한 가드, IndexedDB 연결·트랜잭션
|
||||
헬퍼, `Retry-After` 파싱, JSON 멤버 스캐너. bootstrap만 쓰는 platform
|
||||
서비스 두 개도 여기 있다: 브라우저 lifecycle runtime과 mutation intent
|
||||
factory다(adapter는 이 둘을 import하지 않는다). kernel 파일은 동작 방식만
|
||||
소유한다. 이름, schema, 실패 코드, 관측 모양은 절대 소유하지 않는다.
|
||||
kernel이 절대 소유하면 안 되는 것의 전체 목록은 `indexeddb-connection.ts`
|
||||
맨 위에 있다
|
||||
- `src/adapters/browser-file-storage/result.ts` — 브라우저 데이터의 결과 값과
|
||||
실패 값을 만드는 생성 함수
|
||||
- `src/adapters/cross-context-invalidation/index.ts` — context 사이 무효화
|
||||
(invalidation) 전송과 그 타입. 어떤 adapter든 import할 수 있다. 지금은
|
||||
`query-cache`가 import한다
|
||||
|
||||
`check:architecture` enforces every rule above, including the kernel carve-out.
|
||||
`verify:documentation` fails when a rule name or a top-level `src` folder is
|
||||
missing from this page, when `README.md`, `overview.md` or
|
||||
`frontend-application-foundation.md` describe a folder differently from the
|
||||
folder table, and when any of them names a top-level `src` folder that does not
|
||||
exist. Neither checks that a row describes its rule correctly.
|
||||
`check:architecture`는 위 규칙을 모두 강제한다. kernel 예외도 포함한다.
|
||||
`verify:documentation`은 다음 경우에 실패한다. 규칙 이름이나 최상위 `src`
|
||||
폴더가 이 문서에서 빠졌을 때다. `README.md`, `overview.md`,
|
||||
`frontend-application-foundation.md`가 폴더를 폴더 표와 다르게 설명할 때다.
|
||||
그리고 그중 어느 문서든 없는 최상위 `src` 폴더를 적을 때다. 두 검사 모두 각
|
||||
행이 규칙을 맞게 설명하는지는 보지 않는다.
|
||||
|
||||
Every exception is written in the rule itself (`.dependency-cruiser.json`): the
|
||||
exempted path in `pathNot`, and the reason, owner and revisit condition in
|
||||
`comment` (review 12-07). Besides the kernel, the exceptions are:
|
||||
모든 예외는 규칙 자체(`.dependency-cruiser.json`)에 적는다. 예외 경로는
|
||||
`pathNot`에, 이유·owner·다시 볼 조건은 `comment`에 적는다(리뷰 12-07).
|
||||
kernel 말고 예외는 다음과 같다:
|
||||
|
||||
- the generic presentation modules that read the installed registries today
|
||||
(`generic-presentation-does-not-compose-the-product`). The list names exact
|
||||
files, so a new module that reads a registry fails the gate
|
||||
- `src/presentation/adapters/query`, the TanStack Query binding
|
||||
- 지금 설치된 registry를 읽는 범용 presentation 모듈
|
||||
(`generic-presentation-does-not-compose-the-product`). 목록은 파일을 정확히
|
||||
적는다. 그래서 registry를 읽는 새 모듈은 gate에서 실패한다
|
||||
- TanStack Query 바인딩인 `src/presentation/adapters/query`
|
||||
(`presentation-does-not-know-adapters`)
|
||||
- `src/presentation/routes/app-router.tsx` importing the app
|
||||
- 앱을 import하는 `src/presentation/routes/app-router.tsx`
|
||||
(`presentation-does-not-import-apps-or-contexts`)
|
||||
- the design-system facades (`design-system-is-reached-through-its-index`)
|
||||
- `src/platform/routing` reading deployable-app types
|
||||
- 디자인 시스템 facade(`design-system-is-reached-through-its-index`)
|
||||
- 배포 단위 앱 타입을 읽는 `src/platform/routing`
|
||||
(`platform-kernel-is-product-neutral`)
|
||||
|
||||
## 어댑터 그룹의 공개 경계
|
||||
@@ -151,19 +152,20 @@ realm 파일만 빼는 구조라, 배럴이 그 파일을 다시 끌어들이면
|
||||
`document`를 찾지 못한다. 배럴의 타입 커버리지는 `tsconfig.app.json`이
|
||||
담당하고, 워커 진입점은 배럴을 쓰지 않는다.
|
||||
|
||||
`bootstrap` contains composition only. Business rules and page-specific
|
||||
orchestration belong to `src/application` or to a feature's domain and
|
||||
application.
|
||||
`bootstrap`에는 조립만 있다. 비즈니스 규칙과 페이지별 흐름 조정
|
||||
(orchestration)은 `src/application`이나 feature의 domain·application에 둔다.
|
||||
|
||||
The [ports, adapters, and feature-boundary contract](./frontend-ports-adapters-and-boundaries.md)
|
||||
explains how `presentation` acts as the inbound adapter and how feature
|
||||
application APIs augment the generic typed input registry. Concrete output
|
||||
ports are composed in bootstrap and stay hidden behind the application facade.
|
||||
Project-selected capabilities still implement the same output boundaries.
|
||||
[port, adapter, feature 경계 계약](../design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md)은
|
||||
두 가지를 설명한다. 하나는 `presentation`이 inbound adapter로 동작하는
|
||||
방식이다. 다른 하나는 feature application API가 타입이 붙은 범용 입력
|
||||
registry를 확장(augment)하는 방식이다. 구체 output port는 bootstrap에서
|
||||
조립되고 application facade 뒤에 숨는다. 프로젝트가 고른 capability도 같은
|
||||
output 경계를 구현한다.
|
||||
|
||||
`check:architecture` writes the TypeScript-aware graph below. It reads the rules
|
||||
from `.dependency-cruiser.json` but does not run dependency-cruiser, which cannot
|
||||
parse TypeScript 7 and checked zero modules (review 12-05):
|
||||
`check:architecture`는 TypeScript를 이해하는 아래 그래프를 출력한다. 규칙은
|
||||
`.dependency-cruiser.json`에서 읽지만 dependency-cruiser를 돌리지는 않는다.
|
||||
dependency-cruiser는 TypeScript 7을 파싱하지 못해 모듈을 하나도 검사하지
|
||||
못했다(리뷰 12-05):
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -181,11 +183,12 @@ parse TypeScript 7 and checked zero modules (review 12-05):
|
||||
}
|
||||
```
|
||||
|
||||
The graph scans TypeScript and TSX, including static, dynamic, type, CommonJS
|
||||
and JSDoc import references. `import.meta.glob` is a parse failure: it loads
|
||||
modules without naming one, so no edge rule could see them (review 12-06). It applies the path rules from
|
||||
`.dependency-cruiser.json`, requires explicit TypeScript extensions for local
|
||||
source imports, and fails closed on JavaScript-family source/specifiers,
|
||||
unsupported rule shapes, unresolved imports, parse failures, error-severity
|
||||
layer violations, or cycles. Regression fixtures prove the allowed resolver
|
||||
path and each rejection class.
|
||||
그래프는 TypeScript와 TSX를 읽는다. static, dynamic, type, CommonJS, JSDoc
|
||||
import 참조를 모두 포함한다. `import.meta.glob`은 파싱 실패로 처리한다.
|
||||
모듈 이름을 적지 않고 모듈을 불러오므로 어떤 간선 규칙도 그 모듈을 볼 수
|
||||
없기 때문이다(리뷰 12-06). 그래프는 `.dependency-cruiser.json`의 경로 규칙을
|
||||
적용한다. 로컬 소스 import에는 TypeScript 확장자를 명시하도록 요구한다. 다음
|
||||
중 하나라도 있으면 통과시키지 않고 실패한다(fail closed): JavaScript 계열
|
||||
소스·specifier, 지원하지 않는 규칙 모양, 해석되지 않은 import, 파싱 실패,
|
||||
error 심각도의 계층 위반, 순환. 회귀 fixture가 허용되는 resolver 경로와 거부
|
||||
종류 하나하나를 증명한다.
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Optional frontend adapter recipes
|
||||
# 선택형 frontend adapter recipe
|
||||
|
||||
이 문서는 도메인과 무관한 선택형 frontend capability를 실제 프로젝트에
|
||||
도입하는 실행 가이드다. 기본 스켈레톤에는 vendor runtime을 설치하지 않는다.
|
||||
@@ -23,15 +23,15 @@ production readiness를 뜻하지 않는다.
|
||||
| 심층 deterministic fake. file·storage durability·OPFS fake는 `src` port를 `implements`한다 | `recipes/frontend-capabilities/browser-file-storage-fakes.ts` | 아니오 |
|
||||
| 심층 contract test | `tests/recipes/browser-file-storage-contracts.test.ts` | 아니오 |
|
||||
| 짝 백엔드 세션 owner(JWT·Keycloak PKCE, Redis session 쿠키+CSRF). catalog 밖이고 복사해서 쓴다. src가 import하면 `PRODUCTION_IMPORTS_RECIPE` | `recipes/session-owners/`, 테스트 `tests/recipes/oidc-pkce-session-owner.test.ts`, `tests/recipes/cookie-session-owner.test.ts`, `tests/recipes/session-owners-runtime.test.ts`, 절차 `docs/manual/04-paired-backend-session.md` | 아니오 |
|
||||
| browser data current-status ledger | `docs/architecture/browser-data-capability-completion-ledger.md` | 문서만 |
|
||||
| 심층 설계/ADR | `docs/architecture/browser-file-and-origin-storage.md`, `decisions/VD-11-browser-file-and-origin-storage.md` | 문서만 |
|
||||
| client cache scope/persistence 설계 | `docs/architecture/client-cache-and-storage.md`, `decisions/VD-13-client-cache-scope-and-persistence.md` | 문서만 |
|
||||
| realtime/Web Push/Polling 설계와 reference runtime | `docs/architecture/realtime-events-web-push-and-bounded-polling.md`, `decisions/VD-28-realtime-events-web-push-and-bounded-polling.md`, `src/adapters/realtime`, `src/adapters/web-push` | composition 전에는 tree-shaken |
|
||||
| transfer/CDN 설계/ADR | `docs/architecture/presigned-transfer-and-image-cdn.md`, `decisions/VD-12-presigned-transfer-and-image-cdn.md` | 문서만 |
|
||||
| Range/background 결정 | `docs/architecture/decisions/VD-14-resumable-download-and-background-transfer.md` | 문서만 |
|
||||
| storage lifecycle/migration 결정 | `docs/architecture/decisions/VD-15-origin-storage-lifecycle-and-migration.md` | 문서만 |
|
||||
| transfer composition/Image provider 결정 | `docs/architecture/decisions/VD-16-browser-transfer-composition-and-image-delivery.md` | 문서만 |
|
||||
| REST/GraphQL/Connect/gRPC-Web·Protobuf/REST Gateway·Schema·Mapper·Server State 설계 | `docs/architecture/api-contract-schema-mapper-and-server-state.md`, `docs/architecture/protobuf-browser-transport-and-rest-gateway.md`, `decisions/VD-23-api-transport-selection-and-rest-execution.md`, `decisions/VD-24-runtime-schema-and-boundary-mapper.md`, `decisions/VD-25-server-state-cache-lifecycle.md`, `decisions/VD-26-persisted-graphql-operation.md`, `decisions/VD-27-grpc-web-unary-and-server-stream.md`, `decisions/VD-29-connect-web-and-browser-protobuf-runtime.md`, `decisions/VD-30-protobuf-contract-and-rest-gateway.md` | 문서만 |
|
||||
| browser data current-status ledger | `docs/design/2026-07-30-browser-data-capability-completion-ledger-design.md` | 문서만 |
|
||||
| 심층 설계/ADR | `docs/design/2026-07-27-browser-file-and-origin-storage-design.md`, `docs/adr/VD-11-browser-file-and-origin-storage.md` | 문서만 |
|
||||
| client cache scope/persistence 설계 | `docs/design/2026-07-28-client-cache-and-storage-design.md`, `docs/adr/VD-13-client-cache-scope-and-persistence.md` | 문서만 |
|
||||
| realtime/Web Push/Polling 설계와 reference runtime | `docs/design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md`, `docs/adr/VD-28-realtime-events-web-push-and-bounded-polling.md`, `src/adapters/realtime`, `src/adapters/web-push` | composition 전에는 tree-shaken |
|
||||
| transfer/CDN 설계/ADR | `docs/design/2026-07-30-presigned-transfer-and-image-cdn-design.md`, `docs/adr/VD-12-presigned-transfer-and-image-cdn.md` | 문서만 |
|
||||
| Range/background 결정 | `docs/adr/VD-14-resumable-download-and-background-transfer.md` | 문서만 |
|
||||
| storage lifecycle/migration 결정 | `docs/adr/VD-15-origin-storage-lifecycle-and-migration.md` | 문서만 |
|
||||
| transfer composition/Image provider 결정 | `docs/adr/VD-16-browser-transfer-composition-and-image-delivery.md` | 문서만 |
|
||||
| REST/GraphQL/Connect/gRPC-Web·Protobuf/REST Gateway·Schema·Mapper·Server State 설계 | `docs/design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md`, `docs/design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md`, `docs/adr/VD-23-api-transport-selection-and-rest-execution.md`, `docs/adr/VD-24-runtime-schema-and-boundary-mapper.md`, `docs/adr/VD-25-server-state-cache-lifecycle.md`, `docs/adr/VD-26-persisted-graphql-operation.md`, `docs/adr/VD-27-grpc-web-unary-and-server-stream.md`, `docs/adr/VD-29-connect-web-and-browser-protobuf-runtime.md`, `docs/adr/VD-30-protobuf-contract-and-rest-gateway.md` | 문서만 |
|
||||
| provider-neutral Browser RPC V3 계약/port/runtime | `src/contracts/browser-rpc.ts`, `src/application/ports/browser-rpc`, `src/adapters/browser-rpc`, `tests/unit/browser-rpc` | composition 전에는 tree-shaken |
|
||||
| API contract/server-state 복구 runbook | `docs/operations/api-contract-and-server-state-recovery.md` | 문서만 |
|
||||
| storage 복구 runbook template | `docs/operations/browser-file-storage-recovery.md` | 문서만 |
|
||||
@@ -43,7 +43,7 @@ production readiness를 뜻하지 않는다.
|
||||
| 완전 제거 gate | `scripts/test-optional-recipe-removal.ts` | 아니오 |
|
||||
| native reference runtime 제거 gate | `scripts/test-browser-file-storage-runtime-removal.ts` | 아니오 |
|
||||
|
||||
현재 `productionRuntimeDependencies`는 빈 배열이며 12개 recipe 모두 선택되지
|
||||
현재 `productionRuntimeDependencies`는 빈 배열이며 카탈로그의 recipe 모두 선택되지
|
||||
않았다. `recipes/`의 TypeScript example은 선택 시 복사하고 좁힐 출발점이고,
|
||||
`src/adapters`의 browser-native reference runtime은 공통 lifecycle·failure
|
||||
mechanism을 재사용할 수 있는 실제 구현이다. 제품 feature는 이 runtime에
|
||||
@@ -95,7 +95,7 @@ source가 예산을 넘으면 gate를 우회하지 않는다. output artifact와
|
||||
| --- | --- | --- | --- |
|
||||
| application이 외부 결과를 요청 | application | outbound | `src/adapters/<capability>` |
|
||||
| URL/browser event가 의도를 전달 | application input | inbound | `src/presentation/adapters` |
|
||||
| React rendering behavior만 교체 | presentation | local facade | `src/presentation/<capability>` |
|
||||
| React 렌더링 동작만 교체 | presentation | local facade | `src/presentation/<capability>` |
|
||||
| feature 전용 protocol | feature application | in/out 분리 | `src/features/<name>/adapters` |
|
||||
|
||||
WebSocket 연결 생성, reconnect와 credential attachment는 outbound다. 수신 JSON
|
||||
@@ -103,14 +103,14 @@ WebSocket 연결 생성, reconnect와 credential attachment는 outbound다. 수
|
||||
BroadcastChannel event도 같은 원칙을 적용한다. generated DTO와 vendor SDK
|
||||
type은 facade 밖으로 노출하지 않는다.
|
||||
|
||||
## 3. 12개 recipe 선택표
|
||||
## 3. recipe 선택표
|
||||
|
||||
| recipe | 설치하는 경우 | 설치하면 안 되는 경우 | 핵심 fallback |
|
||||
| --- | --- | --- | --- |
|
||||
| realtime | foreground ordered event 또는 duplex protocol이 확정됨 | focus refetch/manual refresh가 충분하거나 ordering·replay owner 없음 | bounded polling 또는 stale UI |
|
||||
| offline/IndexedDB/OPFS | structured offline data/queue 또는 large local binary가 제품 요구 | credential, partition/retention/recovery 미정, HTTP cache로 충분 | read-only/online-only 또는 승인된 bounded Blob |
|
||||
| Service Worker/Cache Storage | 설치형(installability) 또는 public HTTP representation cache owner 승인. 오프라인 셸은 지원하지 않는다(이 절 끝) | auth/private/opaque cache, update/rollback UX 없음 | hosting cache 기반 network app |
|
||||
| file/picker/download | selection/preview/upload/download와 bounded memory/integrity 요구 | backend 재검증 없음, whole-buffer large file, long-lived credential URL | native input + authorized direct download |
|
||||
| file/picker/download | selection/preview/upload/download와 크기 제한이 있는 memory/integrity 요구 | backend 재검증 없음, 큰 파일을 통째로 buffer에 올림, 오래 사는 credential URL | native input + 인가된 직접 download |
|
||||
| generated API | versioned source와 drift CI가 있음 | DTO가 domain/UI로 노출됨 | typed request builder + schema |
|
||||
| feature flag | rollout/kill switch owner와 default 있음 | authorization에 사용 | typed local default |
|
||||
| Web Worker | profiler가 main-thread 병목을 증명 | 단순 network I/O | chunked/deferred execution |
|
||||
@@ -179,8 +179,8 @@ release" 성질은 제품이 다시 증명한다. 넘겨받은 뒤에는 템플
|
||||
Web Push target은 현재 13번째 설치 recipe가 아니다. 기존 `realtime`,
|
||||
`service-worker-pwa`, `browser-permission`의 인접 경계를 조합해야 하는 별도
|
||||
`NOT_SELECTED` capability다. 실제 선택 전 VD-10 amendment와 machine-readable
|
||||
catalog에 permission, subscription/backend provider, worker handler, notification
|
||||
policy와 removal source를 명시하며, foreground realtime이 선택됐다는 이유로
|
||||
catalog에 권한(permission), subscription/backend provider, worker handler, 알림(notification)
|
||||
정책과 제거 source를 명시하며, foreground realtime이 선택됐다는 이유로
|
||||
Web Push를 함께 설치하지 않는다.
|
||||
|
||||
## 4. 공통 구현 순서
|
||||
@@ -196,9 +196,9 @@ Web Push를 함께 설치하지 않는다.
|
||||
import한다.
|
||||
7. composition root가 concrete adapter를 주입한다. page/use case가 constructor를
|
||||
직접 호출하지 않는다.
|
||||
8. fake, unavailable, timeout/cancel, cleanup, malformed input, redaction과
|
||||
8. fake, 사용 불가(unavailable), timeout/cancel, cleanup, 형식이 틀린 입력, redaction과
|
||||
integration test를 작성한다.
|
||||
9. runtime config schema, dependency inventory/approval, SBOM, bundle budget,
|
||||
9. runtime config schema, 의존성 inventory/승인, SBOM, bundle budget,
|
||||
browser support와 runbook을 갱신한다.
|
||||
운영 CSP(`config/hosting/security-headers.json`)도 여기서 넓힌다. 기본 CSP는
|
||||
아래 기능을 막는다(리뷰 13-08).
|
||||
@@ -230,12 +230,12 @@ Web Push를 함께 설치하지 않는다.
|
||||
- Web Push permission은 user action에서만 요청하고 subscription endpoint/key와
|
||||
payload를 storage, URL, telemetry나 application state에 노출하지 않는다.
|
||||
- detailed status, target contract와 구현 work package는
|
||||
[Realtime events, Web Push, and bounded polling](./realtime-events-web-push-and-bounded-polling.md)을
|
||||
[Realtime events, Web Push, and bounded polling](../design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md)을
|
||||
따른다. 현재 concrete runtime과 product selection은 없다.
|
||||
- 짝 백엔드 템플릿의 실시간 출구(STOMP-over-SockJS, NDJSON)와 이 repo의 SSE·
|
||||
`realtime.v1` WebSocket 어댑터는 그대로 연결되지 않는다. 지금 두 템플릿만으로
|
||||
되는 경로는 bounded polling이다. 대응표와 push를 고를 때의 세 길은 설계 문서
|
||||
[0.1절](./realtime-events-web-push-and-bounded-polling.md#01-짝-백엔드-템플릿과의-대응-110304-02)에
|
||||
[0.1절](../design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md#01-짝-백엔드-템플릿과의-대응-110304-02)에
|
||||
있다(1103/04-02).
|
||||
- realtime 레지스트리(`createRealtimePolicyRegistry`)가 받는 세 바인딩의 출처
|
||||
(1103/04-06). 기능 모듈에는 codec·mapper를 낼 칸이 없으므로 조합 코드가 모은다.
|
||||
@@ -266,14 +266,14 @@ Web Push를 함께 설치하지 않는다.
|
||||
자동 reload와 database 삭제를 금지한다.
|
||||
- OPFS는 immutable bytes만 소유하고 IndexedDB journal이
|
||||
`PREPARING -> FILES_READY -> COMMITTED -> CLEANED` commit authority를 가진다.
|
||||
- quota, corrupt row/manifest, migration checkpoint, worker crash, storage eviction,
|
||||
- quota, 깨진 row/manifest, migration checkpoint, worker 비정상 종료, storage 축출(eviction),
|
||||
N-1 rollback을 fixture와 실제 browser에서 검증한다.
|
||||
|
||||
### Cache Storage/Service Worker
|
||||
|
||||
- Cache Storage는 public HTTP representation 전용이며 application repository나
|
||||
query cache가 아니다.
|
||||
- auth, cookie-dependent, private, personal, no-store, opaque, redirect, 206을
|
||||
- 인증 필요, cookie 의존, private, 개인 정보, no-store, opaque, redirect, 206 응답을
|
||||
거절하고 query/Vary exact match를 보존한다.
|
||||
- candidate 전체의 type/size/integrity가 검증된 뒤에만 release를 활성화하고
|
||||
verified previous release를 rollback용으로 유지한다.
|
||||
@@ -324,7 +324,7 @@ Web Push를 함께 설치하지 않는다.
|
||||
- virtualization은 profiler와 production-like row count로 정당화하며 keyboard,
|
||||
focus restoration, screen reader와 stale row identity를 검증한다.
|
||||
- analytics는 essential diagnostics와 consent-required event를 분리하고 closed
|
||||
event/attribute registry, pre-queue redaction, sampling, bounded queue와
|
||||
event/attribute registry, queue에 넣기 전 redaction, sampling, 크기 제한 queue와
|
||||
retention을 적용한다.
|
||||
|
||||
## 6. 검증 명령
|
||||
@@ -340,7 +340,7 @@ corepack pnpm test:optional-recipe-removal
|
||||
corepack pnpm test:browser-file-storage-removal
|
||||
```
|
||||
|
||||
negative gate는 cleanup 누락, unselected dependency, local adapter 밖 vendor
|
||||
negative gate는 cleanup 누락, 선택하지 않은 의존성, local adapter 밖 vendor
|
||||
import, credential localStorage/URL/telemetry 경로, workflow store의 server-state
|
||||
복제, production source의 recipe import와 선택 전 reference runtime composition을
|
||||
거절한다. removal gate는 recipe와 recipe test를 삭제한 임시 사본에서 base
|
||||
@@ -352,7 +352,7 @@ build와 optional catalog 검사를 다시 실행한다.
|
||||
## 7. 제거 체크리스트
|
||||
|
||||
1. 신규 호출과 background 작업을 중지한다.
|
||||
2. subscription, worker, channel, media track, observer를 cleanup한다.
|
||||
2. subscription, worker, channel, media track, observer를 정리(cleanup)한다.
|
||||
3. persisted store/cache/event queue의 migrate 또는 purge 정책을 실행한다.
|
||||
4. composition registration과 runtime config를 제거한다.
|
||||
5. concrete adapter, facade/port와 vendor dependency를 제거한다.
|
||||
|
||||
@@ -1,24 +1,24 @@
|
||||
# Architecture overview
|
||||
# 아키텍처 개요
|
||||
|
||||
This Mermaid view is a repository-local implementation projection. The
|
||||
`PASS_SCOPED` reviewer evidence applies to the canonical draw.io diagram named
|
||||
in `review-ledger.json`, not automatically to edits in this file.
|
||||
이 Mermaid 그림은 repo 안에서 구현을 옮겨 그린 투영(projection)이다.
|
||||
`PASS_SCOPED` 리뷰 증거는 `review-ledger.json`이 가리키는 정본 draw.io
|
||||
도식에 적용된다. 이 파일을 고친 내용에 저절로 적용되지는 않는다.
|
||||
|
||||
`src/` has nine top-level folders. The descriptions match the table in
|
||||
[the layer contract](./layers.md), which also names every import rule:
|
||||
`src/`에는 최상위 폴더가 아홉 개 있다. 설명은 [계층 계약](./layers.md)의
|
||||
표와 같다. 그 문서는 모든 import 규칙도 적는다:
|
||||
|
||||
- `src/bootstrap` — the composition root: runtime configuration, concrete adapter construction and the React mount
|
||||
- `src/apps` — deployable apps: each `app-module.ts` declares an app and its context budget; `template-app.ts` is the app this build produces
|
||||
- `src/contexts` — bounded contexts: each `context-module.ts` declares its app, route root and feature budget
|
||||
- `src/features` — removable vertical slices (`src/features/<id>/{domain,application,contracts,adapters,presentation}`) and the installed-feature catalogs (`src/features/*.ts`)
|
||||
- `src/presentation` — generic UI and the inbound adapter: routes, layouts, the design system, pages and providers
|
||||
- `src/adapters` — reusable capability runtimes that implement application ports: HTTP, auth, storage, query cache, telemetry, workers and more
|
||||
- `src/application` — generic use cases, ports, policies and view-models
|
||||
- `src/contracts` — shared vocabulary and registries read by several layers, the workers and the build and release scripts
|
||||
- `src/platform` — product-neutral primitives any folder may use: budgets, execution context, resilience, the telemetry pipeline, error envelopes and release coherence
|
||||
- `src/bootstrap` — 조립 루트: 런타임 설정, 구체 adapter 생성, React 마운트
|
||||
- `src/apps` — 배포 단위 앱: 각 `app-module.ts`가 앱과 그 context 예산을 선언한다. `template-app.ts`가 이 빌드가 만드는 앱이다
|
||||
- `src/contexts` — bounded context: 각 `context-module.ts`가 소속 앱, 라우트 루트, 기능 예산을 선언한다
|
||||
- `src/features` — 지울 수 있는 수직 slice(`src/features/<id>/{domain,application,contracts,adapters,presentation}`)와 설치된 기능 목록(`src/features/*.ts`)
|
||||
- `src/presentation` — 범용 UI와 inbound adapter: 라우트, 레이아웃, 디자인 시스템, 페이지, provider
|
||||
- `src/adapters` — application 포트를 구현하는 재사용 capability 런타임: HTTP, 인증, 저장소, query cache, telemetry, worker 등
|
||||
- `src/application` — 범용 use case, 포트, 정책, view-model
|
||||
- `src/contracts` — 여러 계층·worker·빌드와 릴리스 스크립트가 같이 읽는 공용 어휘와 registry
|
||||
- `src/platform` — 어느 폴더든 쓸 수 있는 제품 중립 기본 요소: 예산, 실행 context, 복원력, telemetry 파이프라인, 오류 envelope, 릴리스 정합성
|
||||
|
||||
Arrows point from the importing folder to the imported one. Every folder may
|
||||
also import `contracts` and `platform`; only the main path is drawn.
|
||||
화살표는 import하는 폴더에서 import되는 폴더로 향한다. 모든 폴더는
|
||||
`contracts`와 `platform`도 import할 수 있다. 그림에는 주 경로만 그렸다.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
@@ -37,19 +37,18 @@ flowchart LR
|
||||
Contracts --> Platform[platform]
|
||||
```
|
||||
|
||||
The enforced dependency rule points inward: presentation calls application use
|
||||
cases, adapters implement application ports, and only the composition root
|
||||
selects concrete adapters. Domain code lives inside each feature. Contract
|
||||
registries are the named source for routes,
|
||||
API operations, environment values, storage keys, errors, queries, telemetry,
|
||||
and release tokens. Installed feature contributions extend those registries
|
||||
without making the generic application or router import a concrete feature
|
||||
implementation.
|
||||
강제되는 의존성 규칙은 안쪽을 향한다. presentation은 application use case를
|
||||
부른다. adapter는 application port를 구현한다. 구체 adapter는 composition
|
||||
root만 고른다. domain 코드는 각 feature 안에 있다. contract registry는
|
||||
라우트, API operation, 환경 값, 저장소 키, 오류, query, telemetry, release
|
||||
토큰의 이름을 정하는 출처다. 설치된 feature contribution이 이 registry를
|
||||
확장한다. 그래도 범용 application이나 router가 구체 feature 구현을
|
||||
import하게 되지는 않는다.
|
||||
|
||||
In ports-and-adapters terms, `presentation` is the current inbound adapter and
|
||||
`adapters` contains the current outbound implementations. The production
|
||||
composition exposes an application input API to React while keeping concrete
|
||||
output ports inside application closures:
|
||||
ports-and-adapters 용어로 말하면 `presentation`이 지금의 inbound adapter이고,
|
||||
`adapters`에 지금의 outbound 구현이 있다. 운영 조립(production composition)은
|
||||
React에 application input API를 내보인다. 구체 output port는 application
|
||||
closure 안에 둔다:
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
@@ -62,39 +61,37 @@ flowchart LR
|
||||
Bootstrap2 -. selects and injects .-> Outbound
|
||||
```
|
||||
|
||||
The executable route tree is mounted only after runtime configuration and
|
||||
release-manifest coherence pass. `ApplicationProvider` receives the composed
|
||||
application API; concrete session, storage, telemetry, diagnostics, and release
|
||||
ports are not returned to feature pages. TanStack Query is isolated behind the
|
||||
presentation query adapter, while its provider remains React infrastructure.
|
||||
The module-augmented feature registry gives each installed feature a closed ID
|
||||
and exact input type.
|
||||
실행할 라우트 트리는 runtime 설정 검사와 release manifest 정합성 검사가
|
||||
통과한 뒤에만 마운트된다. `ApplicationProvider`는 조립된 application API를
|
||||
받는다. 구체 session·storage·telemetry·진단·release port는 feature 페이지에
|
||||
돌려주지 않는다. TanStack Query는 presentation query adapter 뒤에 격리된다.
|
||||
다만 그 provider는 React 인프라로 남는다. module augmentation으로 확장한
|
||||
feature registry가 설치된 feature마다 닫힌 ID와 정확한 입력 타입을 준다.
|
||||
|
||||
Route contracts/codecs, the route-input provider, and lazy runtime modules are
|
||||
separate modules so feature pages do not import the router that loads them.
|
||||
Expected application failures use the shared `Result`/`AppFailure` contract.
|
||||
The architecture gate analyzes TS/TSX imports with its own graph (the rules
|
||||
live in `.dependency-cruiser.json`; dependency-cruiser itself cannot parse
|
||||
TypeScript 7 and does not run), rejects local JavaScript-family specifiers and executable
|
||||
JavaScript-family files, and fails on unresolved imports, parse failures,
|
||||
forbidden layer edges, or cycles. The remaining project-owned work includes
|
||||
selecting and verifying real hosting, identity, telemetry, vulnerability and
|
||||
signing providers, plus backend/provider/browser/operations evidence for each
|
||||
selected optional capability; the repository does not fabricate that evidence.
|
||||
Use the following
|
||||
documents for implementation details and project integration work:
|
||||
라우트 contract·codec, route-input provider, lazy runtime 모듈은 서로 다른
|
||||
모듈이다. 그래서 feature 페이지는 자신을 불러오는 router를 import하지 않는다.
|
||||
예상된 application 실패는 공용 `Result`/`AppFailure` contract를 쓴다.
|
||||
architecture gate는 자체 그래프로 TS/TSX import를 분석한다(규칙은
|
||||
`.dependency-cruiser.json`에 있다. dependency-cruiser 자체는 TypeScript 7을
|
||||
파싱하지 못해 돌리지 않는다). gate는 로컬 JavaScript 계열 specifier와 실행
|
||||
가능한 JavaScript 계열 파일을 거부한다. 해석되지 않은 import, 파싱 실패,
|
||||
금지된 계층 간선, 순환이 있으면 실패한다. 프로젝트가 맡을 일이 남아 있다.
|
||||
실제 hosting, identity, telemetry, 취약점 점검, 서명 provider를 고르고
|
||||
검증하는 일이다. 그리고 고른 선택 capability마다 백엔드·provider·브라우저·운영
|
||||
증거를 갖추는 일이다. 이 repo는 그 증거를 지어내지 않는다. 구현 세부와
|
||||
프로젝트 통합 작업은 아래 문서를 본다:
|
||||
|
||||
- [Frontend platform capability review](./frontend-platform-capability-review.md)
|
||||
- [Frontend ports, adapters, and boundaries](./frontend-ports-adapters-and-boundaries.md)
|
||||
- [API contract, Schema, Mapper, and Server State](./api-contract-schema-mapper-and-server-state.md)
|
||||
- [Protobuf browser transports and REST Gateway](./protobuf-browser-transport-and-rest-gateway.md)
|
||||
- [Backend API and Server State handoff contract](./backend-api-and-server-state-contract.md)
|
||||
- [TypeScript, state, and data flow](./typescript-state-and-data-flow.md)
|
||||
- [Routing, pages, and patterns](./routing-pages-and-patterns.md)
|
||||
- [Browser data capability completion ledger](./browser-data-capability-completion-ledger.md)
|
||||
- [Browser file and origin storage](./browser-file-and-origin-storage.md)
|
||||
- [Client cache and storage](./client-cache-and-storage.md)
|
||||
- [Realtime events, Web Push, and bounded polling](./realtime-events-web-push-and-bounded-polling.md)
|
||||
- [Presigned transfer and Image CDN](./presigned-transfer-and-image-cdn.md)
|
||||
- [Server file capability infrastructure](./server-file-capability-infrastructure.md)
|
||||
- [Frontend platform implementation roadmap](./frontend-platform-implementation-roadmap.md)
|
||||
- [프론트엔드 platform capability 리뷰](../design/2026-07-26-frontend-platform-capability-review-design.md)
|
||||
- [프론트엔드 port, adapter, 경계](../design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md)
|
||||
- [API contract, Schema, Mapper와 Server State](../design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md)
|
||||
- [Protobuf 브라우저 전송과 REST Gateway](../design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md)
|
||||
- [백엔드 API와 Server State 인계 계약](./backend-api-and-server-state-contract.md)
|
||||
- [TypeScript, 상태, 데이터 흐름](../design/2026-07-26-typescript-state-and-data-flow-design.md)
|
||||
- [라우팅, 페이지, 패턴](../design/2026-07-26-routing-pages-and-patterns-design.md)
|
||||
- [브라우저 데이터 capability 완료 장부(ledger)](../design/2026-07-30-browser-data-capability-completion-ledger-design.md)
|
||||
- [브라우저 파일과 origin 저장소](../design/2026-07-27-browser-file-and-origin-storage-design.md)
|
||||
- [클라이언트 캐시와 저장소](../design/2026-07-28-client-cache-and-storage-design.md)
|
||||
- [Realtime 이벤트, Web Push, 상한을 둔 polling](../design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md)
|
||||
- [Presigned 전송과 Image CDN](../design/2026-07-30-presigned-transfer-and-image-cdn-design.md)
|
||||
- [서버 파일 capability 인프라](../design/2026-07-28-server-file-capability-infrastructure-design.md)
|
||||
- [프론트엔드 platform 구현 로드맵](../design/2026-07-26-frontend-platform-implementation-roadmap-design.md)
|
||||
|
||||
@@ -1,22 +1,21 @@
|
||||
# Imported scoped diagram review evidence
|
||||
# 가져온 범위 한정 도식 리뷰 증거
|
||||
|
||||
This ledger entry consumes the canonical evidence already recorded by the
|
||||
`ca-skeleton-frontend-operational-contract` project note. It does not claim
|
||||
review of the repository-local Mermaid projections or of the complete
|
||||
production deployment topology.
|
||||
이 ledger 항목은 `ca-skeleton-frontend-operational-contract` 프로젝트 노트에
|
||||
이미 기록된 정본 증거를 가져다 쓴다. 이 repo 안의 Mermaid 투영 그림을
|
||||
리뷰했다고 주장하지 않는다. 운영 배포 토폴로지 전체를 리뷰했다고 주장하지도
|
||||
않는다.
|
||||
|
||||
- Reviewer: `wiki-diagram-reviewer`
|
||||
- Standard: `rules/diagram-standards.md` v2
|
||||
- Canonical report:
|
||||
- 리뷰어: `wiki-diagram-reviewer`
|
||||
- 기준: `rules/diagram-standards.md` v2
|
||||
- 정본 보고서:
|
||||
`docs/superpowers/specs/2026-07-18-ca-skeleton-frontend-operational-contract-review/diagram-review.md`
|
||||
- Canonical report SHA-256:
|
||||
- 정본 보고서 SHA-256:
|
||||
`b4d2a35e4f07e176717786408f98dab5cee1047f77f6ff61f5faeddfccd78a29`
|
||||
|
||||
| Canonical diagram | SHA-256 | Score | Verdict | Reviewed scope |
|
||||
| 정본 도식 | SHA-256 | 점수 | 판정 | 리뷰 범위 |
|
||||
| --- | --- | ---: | --- | --- |
|
||||
| `raw/diagrams/ca-skeleton-frontend/architecture-overview-2026-07-18.drawio` | `c0ae56c9c964c5c6e698ab7dcc91736b9b811b2b834381817905db81c4230ba0` | 100 | PASS | Clean Architecture compile-time dependency ownership |
|
||||
| `raw/diagrams/ca-skeleton-frontend/architecture-deployment-2026-07-18.drawio` | `9a654326fb840ddf24b832221ff7eec4b8fadd9f87ad84174fccfa3bfcd1a25b` | 100 | PASS | immutable static assets and mutable `/config.json` delivery |
|
||||
| `raw/diagrams/ca-skeleton-frontend/architecture-overview-2026-07-18.drawio` | `c0ae56c9c964c5c6e698ab7dcc91736b9b811b2b834381817905db81c4230ba0` | 100 | PASS | Clean Architecture 컴파일 시점 의존성 소유 |
|
||||
| `raw/diagrams/ca-skeleton-frontend/architecture-deployment-2026-07-18.drawio` | `9a654326fb840ddf24b832221ff7eec4b8fadd9f87ad84174fccfa3bfcd1a25b` | 100 | PASS | 불변 정적 asset과 변경 가능한 `/config.json` 전달 |
|
||||
|
||||
The canonical report explicitly limits this `PASS_SCOPED`: it does not verify
|
||||
the complete release/rollback topology, the implementation topology, or live
|
||||
hosting state.
|
||||
정본 보고서는 이 `PASS_SCOPED`의 범위를 분명히 제한한다. release·rollback
|
||||
토폴로지 전체, 구현 토폴로지, 실제 hosting 상태는 검증하지 않는다.
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,11 +1,10 @@
|
||||
# Starter experience contract
|
||||
# 스타터 경험 계약
|
||||
|
||||
The repository provides a runnable, domain-neutral application rather than
|
||||
only infrastructure contracts. The starter experience is intentionally
|
||||
replaceable at the page level while the shell, providers, boundaries,
|
||||
primitives, and state surfaces remain reusable.
|
||||
이 repo는 인프라 계약만 주지 않는다. 바로 실행되는 앱을 준다. 이 앱은 특정 도메인에 묶이지 않는다.
|
||||
스타터 경험(starter experience)은 일부러 페이지 단위로 갈아 끼울 수 있게 만들었다.
|
||||
셸, provider, 경계, UI primitive, 상태 화면(state surface)은 그대로 다시 쓴다.
|
||||
|
||||
## Runtime composition
|
||||
## runtime 조립
|
||||
|
||||
```text
|
||||
validated config + coherent release manifest
|
||||
@@ -19,281 +18,253 @@ validated config + coherent release manifest
|
||||
-> lazy route boundary
|
||||
```
|
||||
|
||||
Boot stops before product mount when configuration or release coherence fails.
|
||||
Each lazy page renders inside Suspense and a telemetry-aware route boundary.
|
||||
Route changes move focus to the new page heading; the skip link and landmarks
|
||||
remain stable in the shell.
|
||||
설정 검증이나 release 정합성 검사가 실패하면 부팅은 제품 화면을 마운트하기 전에 멈춘다.
|
||||
지연 로드(lazy) 페이지는 각각 Suspense와 telemetry를 남기는 라우트 경계 안에서 렌더링된다.
|
||||
라우트가 바뀌면 포커스가 새 페이지 제목으로 옮겨진다.
|
||||
건너뛰기 링크(skip link)와 랜드마크는 셸에 고정되어 바뀌지 않는다.
|
||||
|
||||
## Registered routes
|
||||
## 등록된 라우트
|
||||
|
||||
The route list is `ROUTE_REGISTRY` (`src/features/installed-feature-contracts.ts`):
|
||||
the platform routes of `src/contracts/routes.ts` plus the routes of every
|
||||
installed feature. The platform overview page (`/examples/platform`) shows the
|
||||
composed list at runtime, so this document does not keep a copy of it.
|
||||
라우트 목록은 `ROUTE_REGISTRY`(`src/features/installed-feature-contracts.ts`)다.
|
||||
`src/contracts/routes.ts`의 플랫폼 라우트에, 설치된 모든 feature의 라우트를 더한 것이다.
|
||||
플랫폼 개요 페이지(`/examples/platform`)가 조립된 목록을 실행 중에 보여 준다.
|
||||
그래서 이 문서는 목록을 따로 복사해 두지 않는다.
|
||||
|
||||
Navigation labels and order come from `ROUTE_REGISTRY`; the sidebar does not
|
||||
maintain a second route list. The client access decision never claims to be
|
||||
authorization.
|
||||
내비게이션의 이름과 순서는 `ROUTE_REGISTRY`에서 온다. 사이드바는 라우트 목록을 따로 두지 않는다.
|
||||
클라이언트가 내리는 접근 판단은 어디서도 인가(authorization)라고 내세우지 않는다.
|
||||
|
||||
## Authentication seam
|
||||
## 인증 연결 지점
|
||||
|
||||
The session port exposes state subscription, sign-in start, sign-out,
|
||||
credential attachment, recovery, and unauthenticated notification. Credentials
|
||||
remain opaque to the application and presentation layers.
|
||||
세션 port가 제공하는 것은 상태 구독, 로그인 시작, 로그아웃, 자격 증명(credential) 붙이기, 세션 복구, 미인증 알림이다.
|
||||
application 계층과 presentation 계층은 자격 증명의 내용을 들여다보지 않는다.
|
||||
|
||||
- `demo`: local/development-only state transition with no credentials
|
||||
- `external`: delegates to `globalThis.__CA_FRONTEND_AUTH_OWNER__`
|
||||
- missing/invalid external owner: fails closed as `integration-failed`
|
||||
- `demo`: 로컬·개발 환경에서만 쓰는 상태 전환이다. 자격 증명이 없다.
|
||||
- `external`: `globalThis.__CA_FRONTEND_AUTH_OWNER__`에 맡긴다.
|
||||
- 외부 owner가 없거나 잘못됐을 때: `integration-failed`로 막고 실패한다(fail closed).
|
||||
|
||||
An external owner implements `readState`, `readSubject`, `subscribe`,
|
||||
`beginSignIn`, `signOut`, `attachCredential`, `recoverSession`, and
|
||||
`notifyUnauthenticated`. It owns token acquisition and storage. An owner that
|
||||
lacks any of these methods is rejected, and the session fails closed as
|
||||
`integration-failed`.
|
||||
외부 owner는 `readState`, `readSubject`, `subscribe`,
|
||||
`beginSignIn`, `signOut`, `attachCredential`, `recoverSession`,
|
||||
`notifyUnauthenticated`를 구현한다. 토큰을 받아 오고 저장하는 일은 owner가 맡는다.
|
||||
이 메서드 중 하나라도 빠진 owner는 거부된다. 그러면 세션은 `integration-failed`로 막힌다(fail closed).
|
||||
|
||||
The state transitions an owner makes, and what `recover()` leaves behind for
|
||||
each answer, are written on `SessionState` and `SessionGateway.recover` in
|
||||
`src/application/ports/auth-session-port.ts`. For the paired backend's two
|
||||
authentication modes there are owners to copy, not to write:
|
||||
`recipes/session-owners/oidc-pkce-session-owner.ts` (JWT mode: Keycloak,
|
||||
authorization code with PKCE, `EXTERNAL_BEARER`) and
|
||||
`recipes/session-owners/cookie-session-owner.ts` (Redis session mode: the
|
||||
session cookie, plus `SESSION_COOKIE_*` profiles and the `X-XSRF-TOKEN`
|
||||
provider). `docs/manual/04-paired-backend-session.md` wires them and lists
|
||||
what the backend template does not ship (a browser client in its realm; the
|
||||
sign-in, sign-out and session endpoints).
|
||||
owner가 일으키는 상태 전환과, 응답마다 `recover()`가 남기는 상태는
|
||||
`src/application/ports/auth-session-port.ts`의 `SessionState`와 `SessionGateway.recover`에 적혀 있다.
|
||||
짝 백엔드(paired backend)의 두 인증 모드에는 새로 쓰지 않고 복사하면 되는 owner가 있다.
|
||||
JWT 모드는 `recipes/session-owners/oidc-pkce-session-owner.ts`다(Keycloak, PKCE를 쓰는 authorization code, `EXTERNAL_BEARER`).
|
||||
Redis 세션 모드는 `recipes/session-owners/cookie-session-owner.ts`다(세션 쿠키, 그리고 `SESSION_COOKIE_*` 프로필과 `X-XSRF-TOKEN` provider).
|
||||
`docs/manual/04-paired-backend-session.md`가 이 둘을 연결한다.
|
||||
백엔드 템플릿이 주지 않는 것도 이 문서에 적혀 있다. realm 안의 브라우저 클라이언트, 그리고 로그인·로그아웃·세션 endpoint다.
|
||||
|
||||
`readSubject()` is required. The server-state cache is cleared only when the
|
||||
session state or the subject changes, so a token refresh for the same user
|
||||
keeps cached data. `readSubject()` must return:
|
||||
`readSubject()`는 필수다. subject는 로그인한 사용자를 가리키는 식별자다.
|
||||
서버 상태 캐시는 세션 상태나 subject가 바뀔 때만 비운다.
|
||||
그래서 같은 사용자의 토큰을 갱신해도 캐시된 데이터는 남는다. `readSubject()`는 다음을 돌려줘야 한다.
|
||||
|
||||
- an opaque, non-empty string that stays the same for one user across token
|
||||
refreshes and differs between users: the OIDC `sub` claim, Supabase
|
||||
`session.user.id`, or Firebase `user.uid`
|
||||
- `null` when nobody is signed in
|
||||
- never an access token, refresh token, or any other credential
|
||||
- 내용을 해석하지 않는 빈 값이 아닌 문자열. 한 사용자는 토큰을 갱신해도 값이 같고,
|
||||
사용자끼리는 값이 달라야 한다. 예: OIDC `sub` claim, Supabase
|
||||
`session.user.id`, Firebase `user.uid`
|
||||
- 아무도 로그인하지 않았으면 `null`
|
||||
- access token, refresh token, 그 밖의 어떤 자격 증명도 돌려주지 않는다
|
||||
|
||||
If `readSubject()` returns `null` or `""` while the owner reports
|
||||
`authenticated`, the runtime cannot tell a refresh from an account switch. It
|
||||
fails closed: every such notification clears server state, and each one records
|
||||
the `cache.operation.failed` diagnostic with `operation: SCOPE_FENCE` and
|
||||
`reason: SUBJECT_MISSING`. Seeing that diagnostic means the owner is not
|
||||
reporting its subject. The `demo` adapter reports one fixed demo user as its
|
||||
subject.
|
||||
owner가 `authenticated`를 알리는데 `readSubject()`가 `null`이나 `""`를 돌려주면,
|
||||
runtime은 토큰 갱신과 계정 전환을 구별하지 못한다. 이때는 막힌 쪽으로 실패한다(fail closed).
|
||||
그런 알림이 올 때마다 서버 상태를 비운다. 그리고 매번
|
||||
`cache.operation.failed` 진단을 `operation: SCOPE_FENCE`, `reason: SUBJECT_MISSING`과 함께 남긴다.
|
||||
이 진단이 보이면 owner가 subject를 알려 주지 않는다는 뜻이다.
|
||||
`demo` adapter는 고정된 데모 사용자 하나를 subject로 알린다.
|
||||
|
||||
Migration: `readSubject()` used to be optional. An owner written for an earlier
|
||||
release must add it; without it the owner is rejected at startup (the session
|
||||
becomes `integration-failed`) and a TypeScript owner no longer compiles
|
||||
against `ExternalSessionOwner`. A code path that implements `AuthSessionPort`
|
||||
or `SessionGateway` directly must add `getSubject()` the same way.
|
||||
마이그레이션: 예전에는 `readSubject()`가 선택이었다. 이전 release에 맞춰 쓴 owner는 이 메서드를 더해야 한다.
|
||||
없으면 시작할 때 owner가 거부된다(세션이 `integration-failed`가 된다).
|
||||
TypeScript로 쓴 owner는 `ExternalSessionOwner`에 맞춰 더는 컴파일되지 않는다.
|
||||
`AuthSessionPort`나 `SessionGateway`를 직접 구현한 코드도 같은 식으로 `getSubject()`를 더해야 한다.
|
||||
|
||||
## Extending the starter
|
||||
## 스타터 확장
|
||||
|
||||
New platform work should follow
|
||||
[routing, page templates, and reusable patterns](./routing-pages-and-patterns.md)
|
||||
and the
|
||||
[TypeScript, state, and data-flow target](./typescript-state-and-data-flow.md)
|
||||
rather than adding another independent route or data-loading convention.
|
||||
새 플랫폼 작업은 따로 노는 라우트 규칙이나 데이터 로딩 규칙을 하나 더 만들지 않는다.
|
||||
대신 [라우팅, 페이지 템플릿, 재사용 패턴](../design/2026-07-26-routing-pages-and-patterns-design.md)과
|
||||
[TypeScript, 상태, 데이터 흐름 목표](../design/2026-07-26-typescript-state-and-data-flow-design.md)를 따른다.
|
||||
|
||||
### Replacing the starter screens
|
||||
### 스타터 화면 바꾸기
|
||||
|
||||
`/` (`src/presentation/pages/home-page.tsx`) is the platform's `APP_HOME`; a
|
||||
feature takes it over by declaring that route id (see "Product home and
|
||||
layouts"). Its starter links are the first three screens of the navigation.
|
||||
`/`(`src/presentation/pages/home-page.tsx`)는 플랫폼의 `APP_HOME`이다.
|
||||
feature가 그 route id를 선언하면 이 자리를 넘겨받는다("제품 홈과 레이아웃" 참고).
|
||||
홈에 있는 스타터 링크는 내비게이션의 처음 세 화면이다.
|
||||
|
||||
The template ships no example feature. Its example screens (`/examples/ui`,
|
||||
`/examples/states`, `/examples/auth`) and its reference sample were deleted on
|
||||
2026-11-07: the design-system and screen-state galleries are workshop stories
|
||||
(`src/presentation/design-system/galleries.stories.tsx`), and the manual
|
||||
(`docs/manual/`) with `create:feature` shows how a feature is built. A sample a
|
||||
product keeps for a while is listed in
|
||||
`scripts/lib/removable-template-features.ts`: `verify:documentation` checks its
|
||||
paths while it is installed and accepts them once its `feature-module.ts` is
|
||||
gone (1105/14-01), and `corepack pnpm test:sample-removal` removes it in a copy
|
||||
of the repository and runs the gates there.
|
||||
템플릿은 예제 feature를 주지 않는다. 예제 화면(`/examples/ui`,
|
||||
`/examples/states`, `/examples/auth`)과 참조 샘플은 2026-11-07에 지웠다.
|
||||
디자인 시스템 갤러리와 화면 상태 갤러리는 workshop story
|
||||
(`src/presentation/design-system/galleries.stories.tsx`)다.
|
||||
feature를 만드는 방법은 매뉴얼(`docs/manual/`)과 `create:feature`가 보여 준다.
|
||||
제품이 한동안 남겨 두는 샘플은 `scripts/lib/removable-template-features.ts`에 적는다.
|
||||
`verify:documentation`은 샘플이 설치돼 있는 동안 그 경로를 검사한다.
|
||||
샘플의 `feature-module.ts`가 없어지면 그 경로를 받아들인다(1105/14-01).
|
||||
`corepack pnpm test:sample-removal`은 repo 복사본에서 샘플을 지우고 그 복사본에서 gate를 돌린다.
|
||||
|
||||
The platform overview (`/examples/platform`,
|
||||
`src/presentation/examples/platform-overview-page.tsx`) stays a platform
|
||||
route. It describes the installed registries, and the lab gate (FE-GATE-026)
|
||||
times entering it: a feature route's first entry also loads its context's
|
||||
routes module before the page, a second request round the 200 ms budget does
|
||||
not fit. Its tests are the `tests/component/starter-*.test.tsx` files.
|
||||
플랫폼 개요(`/examples/platform`,
|
||||
`src/presentation/examples/platform-overview-page.tsx`)는 플랫폼 라우트로 남는다.
|
||||
이 페이지는 설치된 registry를 보여 준다. lab gate(FE-GATE-026)는 이 페이지에 들어가는 시간을 잰다.
|
||||
feature 라우트라면 처음 들어갈 때 페이지보다 먼저 그 context의 routes 모듈도 불러온다.
|
||||
이 두 번째 요청 왕복은 200 ms budget 안에 들어가지 않는다.
|
||||
이 페이지의 테스트는 `tests/component/starter-*.test.tsx` 파일들이다.
|
||||
|
||||
The platform's component tests (router, boundaries, shell, runtime tree) run
|
||||
on the pages of the test-only feature in `tests/helpers/fixture-feature.tsx`.
|
||||
The browser-level checks in `tests/e2e` and `tests/visual` use the home page,
|
||||
the platform overview and the gallery stories; what needs a feature
|
||||
(`tests/e2e/generated-feature.spec.ts`, the chunk recovery spec) builds a copy
|
||||
of the repository with the one `create:feature` writes
|
||||
(`scripts/lib/generated-feature.ts`).
|
||||
플랫폼의 component 테스트(router, 경계, 셸, runtime 트리)는
|
||||
`tests/helpers/fixture-feature.tsx`에 있는 테스트 전용 feature의 페이지에서 돈다.
|
||||
`tests/e2e`와 `tests/visual`의 브라우저 수준 검사는 홈 페이지, 플랫폼 개요, 갤러리 story를 쓴다.
|
||||
feature가 있어야 하는 검사(`tests/e2e/generated-feature.spec.ts`, chunk 복구 spec)는
|
||||
`create:feature`가 쓰는 feature를 넣은 repo 복사본을 만든다(`scripts/lib/generated-feature.ts`).
|
||||
|
||||
### Ownership declarations
|
||||
### 소유 선언
|
||||
|
||||
Features, contexts and apps are discovered by
|
||||
`scripts/generate-product-feature-index.ts`. Each boundary declares only its
|
||||
parent, as exported string or integer literals the generator reads:
|
||||
`scripts/generate-product-feature-index.ts`가 feature, context, app을 찾아낸다.
|
||||
각 경계는 자기 부모만 선언한다. 선언은 생성기가 읽는, export된 문자열 리터럴이나 정수 리터럴이다.
|
||||
|
||||
| File | Exports |
|
||||
| 파일 | export |
|
||||
| --- | --- |
|
||||
| `src/apps/<app>/app-module.ts` | `APP_MODULE_ID`, `APP_MAX_CONTEXTS` |
|
||||
| `src/contexts/<context>/context-module.ts` | `CONTEXT_MODULE_ID`, `CONTEXT_APP_ID`, `CONTEXT_ROUTE_PATH`, `CONTEXT_MAX_FEATURES` |
|
||||
| `src/features/<feature>/feature-module.ts` | `FEATURE_MODULE_ID`, `FEATURE_CONTEXT_ID`, `FEATURE_MODULE` |
|
||||
| `src/features/<feature>/feature-runtime.ts` | `FEATURE_RUNTIME` (imported only by `feature-module.ts`, dynamically) |
|
||||
| `src/features/<feature>/feature-runtime.ts` | `FEATURE_RUNTIME` (`feature-module.ts`만 동적으로 import한다) |
|
||||
| `src/features/<feature>/context-routes.ts` | `FEATURE_CONTEXT_ROUTES` |
|
||||
| `src/contexts/<context>/context-layout.tsx` (optional) | `CONTEXT_LAYOUT`, the context's own layout ("Product home and layouts") |
|
||||
| `src/contexts/<context>/context-layout.tsx` (선택) | `CONTEXT_LAYOUT`, 그 context 고유의 레이아웃("제품 홈과 레이아웃") |
|
||||
|
||||
The generator writes `src/.generated/` (git-ignored): the feature index the
|
||||
installed catalogs import, the context index the router loads lazily, and the
|
||||
selected app. Every build and check script runs it first; run it yourself with
|
||||
`corepack pnpm generate:feature-index`. It fails, naming the file, when:
|
||||
생성기는 `src/.generated/`(git이 무시한다)에 세 가지를 쓴다.
|
||||
설치 카탈로그가 import하는 feature 색인, router가 지연 로드하는 context 색인, 선택된 app이다.
|
||||
모든 빌드·검사 script가 생성기를 먼저 돌린다. 직접 돌리려면
|
||||
`corepack pnpm generate:feature-index`를 쓴다. 다음 경우에 생성기는 해당 파일 이름을 대며 실패한다.
|
||||
|
||||
- a directory under `src/features/` has no `feature-module.ts`. Code that
|
||||
is no feature (the IndexedDB consumer the tests compose,
|
||||
`tests/fixtures/indexeddb-consumer`) lives outside `src/features/`;
|
||||
- a feature names an undeclared context, or a context an undeclared app;
|
||||
- a context or app exceeds its declared budget;
|
||||
- `VITE_PRODUCT_FEATURES` names a feature the app does not declare. The
|
||||
variable narrows the installed set here, before anything is compiled.
|
||||
- `src/features/` 아래 디렉터리에 `feature-module.ts`가 없을 때. feature가 아닌 코드
|
||||
(테스트가 조립하는 IndexedDB 소비자,
|
||||
`tests/fixtures/indexeddb-consumer`)는 `src/features/` 밖에 둔다.
|
||||
- feature가 선언되지 않은 context를 가리키거나, context가 선언되지 않은 app을 가리킬 때.
|
||||
- context나 app이 선언한 budget을 넘을 때.
|
||||
- `VITE_PRODUCT_FEATURES`가 app이 선언하지 않은 feature를 가리킬 때.
|
||||
이 변수는 무엇이든 컴파일하기 전에, 여기서 설치할 feature 집합을 줄인다.
|
||||
|
||||
### Adding a feature
|
||||
### feature 추가
|
||||
|
||||
1. Create `src/features/<feature>/feature-module.ts`. Build `FEATURE_MODULE`
|
||||
with `defineFeatureModule` (`src/features/feature-module.ts`). This is the
|
||||
feature's declaration, and it is in the initial chunk, so it holds data
|
||||
only: the declaration contract (routes, route runtime contracts,
|
||||
invalidation, topic versions and the external `contractPackages` the
|
||||
release manifest is checked against at boot), its message catalogs, and
|
||||
`loadRuntime`, which imports `feature-runtime.ts` dynamically.
|
||||
`create:feature` writes a complete one.
|
||||
2. Create `src/features/<feature>/feature-runtime.ts` with
|
||||
`defineFeatureRuntime`: the `schemas` (FE-REG-SCHEMA rows for the
|
||||
feature's route and API schemas), the adapter contributions
|
||||
(`defineFeatureAdapterContribution`, with `needs` naming the platform
|
||||
capabilities it receives) and the contract contributions (the HTTP
|
||||
operations). The router loads
|
||||
it (`application.features.load`) when one of the feature's routes is
|
||||
entered. Do not import it statically from anywhere: each feature would add
|
||||
its whole executable code to the initial chunk again, about 3.9 KB gzip
|
||||
(`tests/unit/feature-shape-growth.test.ts` bounds one feature at 1 KiB).
|
||||
An HTTP API is written once, as its contract contribution descriptor: it
|
||||
executes, and `check:registries` governs the FE-REG-API row projected from
|
||||
it (`projectApiOperationRows` in `src/contracts/api-operations.ts`).
|
||||
A product feature's contract contribution uses an `EXTERNAL_PACKAGE`
|
||||
source. `TEMPLATE_FIXTURE` was the template's reference sample source; it
|
||||
never joins the release contract set, and the composer rejects it in any
|
||||
product feature.
|
||||
3. Create `src/features/<feature>/context-routes.ts` exporting
|
||||
`FEATURE_CONTEXT_ROUTES`. Page components are imported lazily here, and each
|
||||
route handle carries the route's params/search `codecs`; the owning context
|
||||
loads this file only when its route root is visited
|
||||
(a `create:feature <id> --with-create` feature's `context-routes.ts`). Each handle's
|
||||
`routeId` must be a route of a feature contract in the same context; the
|
||||
context refuses the routes when they load, naming the route, context and
|
||||
features (`src/contexts/bounded-context-module.ts`).
|
||||
4. Name the owning context in `FEATURE_CONTEXT_ID`. Use an existing context or
|
||||
add `src/contexts/<context>/context-module.ts` owned by the app.
|
||||
Every route path in the feature contract must sit at or under that
|
||||
context's `CONTEXT_ROUTE_PATH` and must not fall under another context's
|
||||
identical or more specific root: the router renders feature routes only
|
||||
inside the owning context. No platform route may answer it either: the
|
||||
router tries `AppShell`'s platform routes first, so the same path as a
|
||||
platform route, `/` under an id other than `APP_HOME`, or a `*` root
|
||||
without a layout (the not-found route takes every URL) never renders the
|
||||
feature. The app module refuses anything else when it loads, naming the
|
||||
route, feature and context (`src/apps/deployable-app-module.ts`). A route
|
||||
that takes over the platform home is the exception ("Product home and
|
||||
layouts").
|
||||
5. If the feature has application input, augment `ApplicationFeatureInputs`
|
||||
from the feature (the IndexedDB consumer fixture does it in
|
||||
`tests/fixtures/indexeddb-consumer/application/local-draft-api.ts`).
|
||||
6. Run `corepack pnpm check:architecture`, `corepack pnpm check:types`,
|
||||
`corepack pnpm check:registries` and the tests. `tests/unit/two-feature-install-typecheck.test.ts`
|
||||
keeps the installed catalogs compiling with more than one feature.
|
||||
7. Run `corepack pnpm test:sample-removal -- --feature=<feature id>` to prove
|
||||
the product still builds and passes its gates without the feature.
|
||||
1. `src/features/<feature>/feature-module.ts`를 만든다. `defineFeatureModule`
|
||||
(`src/features/feature-module.ts`)로 `FEATURE_MODULE`을 만든다. 이 파일은
|
||||
feature의 선언이고 초기 chunk에 들어간다. 그래서 데이터만 담는다.
|
||||
담는 것은 셋이다. 첫째, 선언 계약이다(라우트, 라우트 runtime 계약,
|
||||
무효화(invalidation), topic 버전, 부팅 때 release manifest와 맞춰 보는 외부 `contractPackages`).
|
||||
둘째, message 카탈로그다. 셋째, `feature-runtime.ts`를 동적으로 import하는
|
||||
`loadRuntime`이다. `create:feature`가 완성된 파일을 써 준다.
|
||||
2. `defineFeatureRuntime`으로 `src/features/<feature>/feature-runtime.ts`를 만든다.
|
||||
담는 것은 셋이다. `schemas`(feature의 라우트 schema와 API schema에 대한 FE-REG-SCHEMA 행),
|
||||
adapter contribution(`defineFeatureAdapterContribution`. `needs`에 받을 플랫폼 capability를 적는다),
|
||||
contract contribution(HTTP operation)이다.
|
||||
feature의 라우트 하나에 들어갈 때 router가 이 파일을 불러온다(`application.features.load`).
|
||||
어디에서도 이 파일을 정적으로 import하지 않는다. 그러면 feature마다 실행 코드 전체가
|
||||
다시 초기 chunk에 들어간다. 대략 gzip 3.9 KB다
|
||||
(`tests/unit/feature-shape-growth.test.ts`는 feature 하나의 상한을 1 KiB로 둔다).
|
||||
HTTP API는 contract contribution descriptor로 한 번만 쓴다. 이 descriptor가 실제로 실행된다.
|
||||
그리고 여기서 뽑아낸 FE-REG-API 행을 `check:registries`가 관리한다
|
||||
(`src/contracts/api-operations.ts`의 `projectApiOperationRows`).
|
||||
제품 feature의 contract contribution은 `EXTERNAL_PACKAGE` source를 쓴다.
|
||||
`TEMPLATE_FIXTURE`는 템플릿의 참조 샘플이 쓰던 source다. 이 source는 release 계약 집합에
|
||||
절대 들어가지 않는다. composer는 어느 제품 feature에서든 이 source를 거부한다.
|
||||
3. `FEATURE_CONTEXT_ROUTES`를 export하는 `src/features/<feature>/context-routes.ts`를 만든다.
|
||||
페이지 컴포넌트는 여기서 지연 import한다. 각 route handle은 그 라우트의 params/search `codecs`를 갖는다.
|
||||
소유 context는 자기 route root에 들어갈 때만 이 파일을 불러온다
|
||||
(예: `create:feature <id> --with-create`로 만든 feature의 `context-routes.ts`).
|
||||
각 handle의 `routeId`는 같은 context에 있는 feature 계약의 라우트여야 한다.
|
||||
아니면 context가 라우트를 불러올 때 거부하고, 라우트·context·feature 이름을 댄다
|
||||
(`src/contexts/bounded-context-module.ts`).
|
||||
4. `FEATURE_CONTEXT_ID`에 소유 context를 적는다. 있는 context를 쓰거나,
|
||||
app이 소유하는 `src/contexts/<context>/context-module.ts`를 더한다.
|
||||
feature 계약의 라우트 경로는 모두 그 context의 `CONTEXT_ROUTE_PATH`이거나 그 아래여야 한다.
|
||||
또 다른 context의 같은 root나 더 구체적인 root 아래에 들어가면 안 된다.
|
||||
router는 feature 라우트를 소유 context 안에서만 렌더링하기 때문이다.
|
||||
플랫폼 라우트가 그 경로에 응답해서도 안 된다. router는 `AppShell`의 플랫폼 라우트를 먼저 시도한다.
|
||||
그래서 다음 경로에서는 feature가 렌더링되지 않는다. 플랫폼 라우트와 같은 경로,
|
||||
`APP_HOME`이 아닌 id로 쓴 `/`, 레이아웃 없는 `*` root(찾을 수 없음 라우트가 모든 URL을 가져간다)다.
|
||||
이 규칙을 어긴 라우트는 app 모듈이 불러올 때 거부하고, 라우트·feature·context 이름을 댄다
|
||||
(`src/apps/deployable-app-module.ts`). 플랫폼 홈을 넘겨받는 라우트는 예외다
|
||||
("제품 홈과 레이아웃").
|
||||
5. feature에 application 입력이 있으면 feature 쪽에서 `ApplicationFeatureInputs`를
|
||||
확장(augment)한다(IndexedDB 소비자 fixture가
|
||||
`tests/fixtures/indexeddb-consumer/application/local-draft-api.ts`에서 이렇게 한다).
|
||||
6. `corepack pnpm check:architecture`, `corepack pnpm check:types`,
|
||||
`corepack pnpm check:registries`와 테스트를 돌린다. `tests/unit/two-feature-install-typecheck.test.ts`는
|
||||
feature가 둘 이상일 때도 설치 카탈로그가 컴파일되는지 지킨다.
|
||||
7. `corepack pnpm test:sample-removal -- --feature=<feature id>`를 돌린다.
|
||||
이 feature를 빼도 제품이 빌드되고 gate를 통과하는지 확인한다.
|
||||
|
||||
Files outside the feature directory. Everything else a feature needs is in
|
||||
`src/features/<feature>/` and `tests/features/<feature>/`.
|
||||
feature 디렉터리 밖 파일은 아래 표에 있다. feature에 필요한 나머지는 모두
|
||||
`src/features/<feature>/`와 `tests/features/<feature>/` 안에 있다.
|
||||
|
||||
| File | When | What fails without it |
|
||||
| 파일 | 언제 | 없으면 실패하는 것 |
|
||||
| --- | --- | --- |
|
||||
| `src/.generated/*` | never by hand: every build and check script regenerates it | — |
|
||||
| `public/release-manifest.json` (tracked, the dev server's manifest) | every added or removed feature: `create:feature` rewrites it (`node scripts/write-dev-release-manifest.ts`). Commit it with the feature. Two feature branches change its `setDigest` line; on a merge conflict take either side and run the command again (1105/16-01) | `test:unit` (`tests/unit/dev-release-manifest.test.ts`) names the command; the dev server does not boot (`CONTRACT_SET_PACKAGE_MISSING`) |
|
||||
| `config/scale/feature-shape-ceilings.json` `initialJavascript` (tracked) | every added or removed feature, and every template change that moves the initial JavaScript: `node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write`. Commit it with the change; on a merge conflict run the command again | `test:unit` (the feature-shape growth test compares it with a build) |
|
||||
| `src/contexts/<context>/context-module.ts` | the feature needs a new context | `generate:feature-index`: `Feature <id> belongs to undeclared context <context>` |
|
||||
| `src/contexts/<context>/context-layout.tsx` | the context needs its own frame instead of `AppShell` (see "Product home and layouts" below) | nothing: without it the context renders in `AppShell` |
|
||||
| `docs/accessibility/route-reviews/<ROUTE_ID>.md` | every route the feature adds. Copy a record and reset it to `Status: pending-manual-review` | `test:unit` (`tests/unit/manual-a11y-evidence.test.ts`), `verify:documentation` (names the route IDs) and FE-GATE-009 (`review:a11y-manual -- --format-only`). FE-GATE-028 requires the signed review at release |
|
||||
| `tests/e2e/accessibility.spec.ts` | never per feature (1103/16-03): it fills every path parameter with one value and answers each API request from the installed descriptor, a list read with an empty list in its `responseEnvelope` frame. Edit it only for a protected page that sends something other than an installed GET before it renders | `test:a11y` (FE-GATE-009): a request no installed GET declares fails the route; so does an alert box (`role="alert"`) on a page that read only lists |
|
||||
| `src/features/product-capabilities.ts` (product-owned) | `needs` names a capability the template does not build: type it in `ProductFeaturePlatformCapabilities`. `FeaturePlatformCapabilities` extends it, so the app, scripts and tests typecheck programs all see the key (an augmentation inside `product-composition.ts` is not seen by the scripts' program) | `check:types`: `Type '"<capability>"' is not assignable to type 'keyof FeaturePlatformCapabilities'` in the feature |
|
||||
| `src/bootstrap/product-composition.ts` (product-owned) | `needs` names a capability the template does not build: return the capability here, typed in `product-capabilities.ts`. `indexedDb` is built as in `recipes/frontend-capabilities/indexeddb-feature-capability.ts`. Credentials for a product auth profile are returned here too. A product that owns the session (a BFF's httpOnly cookie) returns its session owner from `composeProductSessionOwner` instead of installing it on the host global before boot | `check:types`; at runtime `feature <id> needs <capability>, which the host did not provide`. Without the session owner, `AUTH_MODE: "external"` boots with the session `integration-failed` |
|
||||
| `src/contracts/product-contracts.ts` (product-owned) | a product auth profile, or a product runtime-config key and its FE-REG-ENV row (`PRODUCT_ENV_REGISTRY`) | auth profile: every gate that loads the operation, with `Installed contract contribution is not composable: <featureId>/<operationId>: unknown authProfileId <id>`. Config key: `check:types` where it is read. Give the key a `.default()` or make it `.optional()`: template tests build their config with `tests/helpers/runtime-config.ts`, which fills the product's defaults, and a required key without a default fails them. FE-REG-ENV row: `check:registries` checks its fields, and `tests/unit/env-registry-coverage.test.ts` (`test:unit`) requires a row for every key, with the schema's `required` and `defaultValue` |
|
||||
| `config/runtime/<profile>.json` | optional: a `FEATURE_OVERRIDES` entry switches the feature off | nothing |
|
||||
| `package.json`, the lockfile, `config/security/dependency-change-evidence.json` | the contract contribution imports a generated `@org-contracts/*` package as a production dependency | `generate:supply-chain` (in `check:bundle`): `high-risk dependency missing review: add:<package>` |
|
||||
| `src/.generated/*` | 손으로 고치지 않는다. 모든 빌드·검사 script가 다시 만든다 | — |
|
||||
| `public/release-manifest.json` (추적 파일, dev server의 manifest) | feature를 더하거나 뺄 때마다. `create:feature`가 다시 쓴다(`node scripts/write-dev-release-manifest.ts`). feature와 같은 커밋에 넣는다. 두 feature 브랜치가 모두 이 파일의 `setDigest` 줄을 바꾼다. 병합 충돌이 나면 아무 쪽이나 고르고 명령을 다시 돌린다(1105/16-01) | `test:unit`(`tests/unit/dev-release-manifest.test.ts`)이 실패하며 이 명령을 알려 준다. dev server가 부팅하지 못한다(`CONTRACT_SET_PACKAGE_MISSING`) |
|
||||
| `config/scale/feature-shape-ceilings.json` `initialJavascript` (추적 파일) | feature를 더하거나 뺄 때마다, 그리고 초기 JavaScript를 바꾸는 템플릿 변경마다: `node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write`. 그 변경과 같은 커밋에 넣는다. 병합 충돌이 나면 명령을 다시 돌린다 | `test:unit`(feature-shape growth 테스트가 이 값을 빌드 결과와 비교한다) |
|
||||
| `src/contexts/<context>/context-module.ts` | feature에 새 context가 필요할 때 | `generate:feature-index`: `Feature <id> belongs to undeclared context <context>` |
|
||||
| `src/contexts/<context>/context-layout.tsx` | context에 `AppShell` 대신 자기 틀이 필요할 때(아래 "제품 홈과 레이아웃" 참고) | 없음. 파일이 없으면 context는 `AppShell` 안에서 렌더링된다 |
|
||||
| `docs/accessibility/route-reviews/<ROUTE_ID>.md` | feature가 더하는 라우트마다. 기록 하나를 복사해 `Status: pending-manual-review`로 되돌린다 | `test:unit`(`tests/unit/manual-a11y-evidence.test.ts`), `verify:documentation`(route ID를 댄다), FE-GATE-009(`review:a11y-manual -- --format-only`). release 때는 FE-GATE-028이 서명된 검토를 요구한다 |
|
||||
| `tests/e2e/accessibility.spec.ts` | feature마다 고치지 않는다(1103/16-03). 이 파일은 모든 경로 파라미터를 한 값으로 채우고, 각 API 요청에 설치된 descriptor로 응답한다. 목록 읽기에는 `responseEnvelope` 틀에 담은 빈 목록으로 응답한다. 보호된 페이지가 렌더링 전에 설치된 GET이 아닌 요청을 보낼 때만 고친다 | `test:a11y`(FE-GATE-009): 설치된 GET 어디에도 선언되지 않은 요청이 오면 그 라우트가 실패한다. 목록만 읽은 페이지에 경고 상자(`role="alert"`)가 떠도 실패한다 |
|
||||
| `src/features/product-capabilities.ts` (제품 소유) | `needs`가 템플릿이 만들지 않는 capability를 가리킬 때: `ProductFeaturePlatformCapabilities`에 그 타입을 적는다. `FeaturePlatformCapabilities`가 이를 확장하므로 app, scripts, tests의 타입 검사 프로그램이 모두 그 키를 본다(`product-composition.ts` 안에 둔 augmentation은 scripts의 프로그램이 보지 못한다) | `check:types`: feature에서 `Type '"<capability>"' is not assignable to type 'keyof FeaturePlatformCapabilities'` |
|
||||
| `src/bootstrap/product-composition.ts` (제품 소유) | `needs`가 템플릿이 만들지 않는 capability를 가리킬 때: 여기서 그 capability를 돌려준다. 타입은 `product-capabilities.ts`에 적는다. `indexedDb`는 `recipes/frontend-capabilities/indexeddb-feature-capability.ts`처럼 만든다. 제품 인증 프로필의 자격 증명도 여기서 돌려준다. 세션을 직접 소유하는 제품(BFF의 httpOnly 쿠키)은 부팅 전에 host 전역에 세션 owner를 설치하지 않는다. 대신 `composeProductSessionOwner`에서 돌려준다 | `check:types`. 실행 중에는 `feature <id> needs <capability>, which the host did not provide`. 세션 owner가 없으면 `AUTH_MODE: "external"`은 세션이 `integration-failed`인 채로 부팅한다 |
|
||||
| `src/contracts/product-contracts.ts` (제품 소유) | 제품 인증 프로필, 또는 제품 runtime 설정 키와 그 FE-REG-ENV 행(`PRODUCT_ENV_REGISTRY`) | 인증 프로필: 그 operation을 불러오는 모든 gate가 `Installed contract contribution is not composable: <featureId>/<operationId>: unknown authProfileId <id>`로 실패한다. 설정 키: 키를 읽는 곳에서 `check:types`가 실패한다. 키에는 `.default()`를 주거나 `.optional()`로 만든다. 템플릿 테스트는 `tests/helpers/runtime-config.ts`로 설정을 만들고, 이 helper는 제품의 기본값을 채운다. 그래서 기본값 없는 필수 키는 이 테스트를 실패시킨다. FE-REG-ENV 행: `check:registries`가 행의 필드를 검사한다. `tests/unit/env-registry-coverage.test.ts`(`test:unit`)는 키마다 행이 있고, 그 행에 schema의 `required`와 `defaultValue`가 적혀 있기를 요구한다 |
|
||||
| `config/runtime/<profile>.json` | 선택: `FEATURE_OVERRIDES` 항목으로 feature를 끈다 | 없음 |
|
||||
| `package.json`, lockfile, `config/security/dependency-change-evidence.json` | contract contribution이 생성된 `@org-contracts/*` 패키지를 운영 의존성(production dependency)으로 import할 때 | `generate:supply-chain`(`check:bundle` 안에서 돈다): `high-risk dependency missing review: add:<package>` |
|
||||
|
||||
The central catalogs (`src/features/installed-*.ts`) and the registry
|
||||
governance file do not change: consumer directories there are globs over every
|
||||
feature (`src/features/*/adapters`, `config/contracts/registry-governance.json`).
|
||||
A route's params/search schema ids are checked against the schemas the feature
|
||||
registers, and its `loadingSurface` only has to be a kebab-case name, so a
|
||||
route with its own schema and loading surface needs no governance edit either.
|
||||
The registry baseline does not change either. New routes, API operations,
|
||||
schemas and invalidation topics, namespaces and edges are additive registry
|
||||
changes; `update:registry-baseline` or breaking evidence is needed only to
|
||||
remove or change a row or graph item.
|
||||
`tests/unit/second-api-feature-registries.test.ts` adds such a feature (an API
|
||||
operation, a route with its own search schema and loading surface, and an
|
||||
invalidation topic) to a copy of the repository and runs `check:registries` on
|
||||
it.
|
||||
중앙 카탈로그(`src/features/installed-*.ts`)와 registry governance 파일은 바뀌지 않는다.
|
||||
거기 적힌 소비자 디렉터리는 모든 feature를 덮는 glob이다
|
||||
(`src/features/*/adapters`, `config/contracts/registry-governance.json`).
|
||||
라우트의 params/search schema id는 feature가 등록한 schema와 맞춰 본다.
|
||||
`loadingSurface`는 kebab-case 이름이기만 하면 된다.
|
||||
그래서 자기 schema와 loading surface를 가진 라우트도 governance를 고칠 필요가 없다.
|
||||
registry baseline도 바뀌지 않는다. 새 라우트, API operation,
|
||||
schema, 무효화 topic, namespace, edge는 registry에 더하기만 하는 변경이다.
|
||||
`update:registry-baseline`이나 breaking 증거는 행이나 그래프 항목을 지우거나 바꿀 때만 필요하다.
|
||||
`tests/unit/second-api-feature-registries.test.ts`는 이런 feature(API
|
||||
operation 하나, 자기 search schema와 loading surface를 가진 라우트 하나, 무효화 topic 하나)를
|
||||
repo 복사본에 더하고 `check:registries`를 돌린다.
|
||||
|
||||
Schema, operation, mapper, route and chunk ids and invalidation topics are
|
||||
global. Prefix them with the feature; `create:feature` writes
|
||||
`<Pascal>NoRequest`, so a bare `NoRequest` would collide between features. MSW scenarios for the feature's own operations come from
|
||||
`createHttpScenarioHandler` (`tests/mocks/handlers/http-scenarios.ts`) with
|
||||
the feature's installed contract; the shared scenario catalog does not change.
|
||||
schema, operation, mapper, 라우트, chunk의 id와 무효화 topic은 전역이다.
|
||||
앞에 feature 이름을 붙인다. `create:feature`는
|
||||
`<Pascal>NoRequest`를 쓴다. 맨 `NoRequest`를 쓰면 feature끼리 이름이 겹친다.
|
||||
feature 자기 operation의 MSW 시나리오는 feature의 설치된 계약을 넣은
|
||||
`createHttpScenarioHandler`(`tests/mocks/handlers/http-scenarios.ts`)로 만든다.
|
||||
공유 시나리오 카탈로그는 바뀌지 않는다.
|
||||
|
||||
### Product home and layouts
|
||||
### 제품 홈과 레이아웃
|
||||
|
||||
A product whose home is a feature screen, or whose screens use a frame other
|
||||
than `AppShell`, declares it. The router and the catalogs do not change.
|
||||
홈이 feature 화면인 제품이나, 화면이 `AppShell`이 아닌 다른 틀을 쓰는 제품은 그것을 선언한다.
|
||||
router와 카탈로그는 바뀌지 않는다.
|
||||
|
||||
- **Home.** A feature takes over the platform home by declaring a route with
|
||||
the id `APP_HOME` in its contract. The platform names the routes a feature
|
||||
may take over (`FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS` in
|
||||
`src/contracts/routes.ts`); any other platform route id is still a
|
||||
duplicate. Two features declaring `APP_HOME` fail when the catalogs load,
|
||||
naming both. The router mounts the route at its own path with the owning
|
||||
context, whatever that context's route root. Leaving the feature out of the
|
||||
build (`VITE_PRODUCT_FEATURES`) brings the platform home back; switching it
|
||||
off at runtime shows the disabled-feature page at its path.
|
||||
- **Layout.** A context with `src/contexts/<context>/context-layout.tsx`
|
||||
exporting `CONTEXT_LAYOUT` (a component) renders under that layout instead
|
||||
of `AppShell`. The generated index loads the file lazily, when one of the
|
||||
context's routes is entered. The router mounts the context at each
|
||||
registered path of its features under the layout, so an unknown URL still
|
||||
gets the not-found page in `AppShell`. Contexts whose layout files export the
|
||||
same component keep one layout instance when the user moves between them,
|
||||
so several route roots can share a layout.
|
||||
- **Accessibility.** The layout renders a skip link to `#main-content` and
|
||||
exactly one `<main id="main-content" tabIndex={-1}>` around `<Outlet />`.
|
||||
The router moves focus there on every route change. Layout routes are
|
||||
siblings of `AppShell`, never inside it.
|
||||
`tests/component/layout-landmarks.test.tsx` renders `AppShell` and the
|
||||
layout of every installed context and fails one without them.
|
||||
- **Failures.** A layout chunk a deploy removed gets the reload-once recovery
|
||||
of a route chunk. Route and feature boundaries work as they do in
|
||||
`AppShell`.
|
||||
- The route root rule of step 4 spans every layout: a root takes the URLs
|
||||
under it whichever layout either context has.
|
||||
- **홈.** feature는 계약에 id가 `APP_HOME`인 라우트를 선언해 플랫폼 홈을 넘겨받는다.
|
||||
feature가 넘겨받을 수 있는 라우트는 플랫폼이 정한다
|
||||
(`src/contracts/routes.ts`의 `FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS`).
|
||||
그 밖의 플랫폼 route id를 쓰면 여전히 중복이다.
|
||||
두 feature가 `APP_HOME`을 선언하면 카탈로그를 불러올 때 둘의 이름을 대며 실패한다.
|
||||
router는 소유 context의 route root가 무엇이든, 그 라우트를 소유 context와 함께 자기 경로에 마운트한다.
|
||||
빌드에서 feature를 빼면(`VITE_PRODUCT_FEATURES`) 플랫폼 홈이 돌아온다.
|
||||
실행 중에 feature를 끄면 그 경로에 비활성 feature 페이지가 뜬다.
|
||||
- **레이아웃.** `CONTEXT_LAYOUT`(컴포넌트)을 export하는 `src/contexts/<context>/context-layout.tsx`가
|
||||
있는 context는 `AppShell` 대신 그 레이아웃 아래에서 렌더링된다.
|
||||
생성된 색인은 그 context의 라우트 하나에 들어갈 때 이 파일을 지연 로드한다.
|
||||
router는 context를 그 feature들이 등록한 경로마다 레이아웃 아래에 마운트한다.
|
||||
그래서 모르는 URL은 여전히 `AppShell` 안의 찾을 수 없음 페이지로 간다.
|
||||
레이아웃 파일이 같은 컴포넌트를 export하는 context끼리는, 사용자가 그 사이를 옮겨 다녀도
|
||||
레이아웃 인스턴스 하나를 유지한다. 그래서 여러 route root가 레이아웃 하나를 함께 쓸 수 있다.
|
||||
- **접근성.** 레이아웃은 `#main-content`로 가는 건너뛰기 링크를 렌더링한다.
|
||||
그리고 `<Outlet />`을 감싸는 `<main id="main-content" tabIndex={-1}>`을 정확히 하나 렌더링한다.
|
||||
router는 라우트가 바뀔 때마다 포커스를 그곳으로 옮긴다.
|
||||
레이아웃 라우트는 `AppShell`의 형제이고, 절대 그 안에 들어가지 않는다.
|
||||
`tests/component/layout-landmarks.test.tsx`는 `AppShell`과 설치된 모든 context의
|
||||
레이아웃을 렌더링하고, 이 둘이 없는 레이아웃을 실패시킨다.
|
||||
- **실패.** 배포로 사라진 레이아웃 chunk도 라우트 chunk처럼 한 번 새로고침해 복구한다.
|
||||
라우트 경계와 feature 경계는 `AppShell`에서와 똑같이 동작한다.
|
||||
- 4단계의 route root 규칙은 모든 레이아웃에 걸쳐 적용된다.
|
||||
두 context가 어떤 레이아웃을 갖든, root는 그 아래 URL을 가져간다.
|
||||
|
||||
`tests/component/context-layouts.test.tsx` installs a product declared this
|
||||
way (`tests/helpers/fixture-layout-product.tsx`).
|
||||
`tests/component/context-layouts.test.tsx`는 이렇게 선언한 제품
|
||||
(`tests/helpers/fixture-layout-product.tsx`)을 설치해 본다.
|
||||
|
||||
### Before shipping
|
||||
### 출시 전에
|
||||
|
||||
- Use the semantic tokens, UI primitives, and state surfaces before adding a
|
||||
project-specific variant.
|
||||
- Add component behavior, all-engine E2E, automated axe, and signed manual
|
||||
route evidence.
|
||||
- 프로젝트 전용 변형을 더하기 전에 의미 토큰(semantic token), UI primitive, 상태 화면을 먼저 쓴다.
|
||||
- component 동작 테스트, 모든 브라우저 엔진 E2E, 자동 axe 검사, 서명된 수동 라우트 증거를 더한다.
|
||||
|
||||
Theme preference is the public `COLOR_SCHEME` storage contract. Authentication
|
||||
tokens and other secrets remain forbidden storage keys.
|
||||
테마 선택은 공개된 `COLOR_SCHEME` 저장소 계약이다.
|
||||
인증 토큰과 그 밖의 비밀 값은 계속 저장 금지 키다.
|
||||
|
||||
@@ -1,16 +1,16 @@
|
||||
# Static asset and runtime-config delivery
|
||||
# 정적 자산과 runtime 설정 전달
|
||||
|
||||
> **정본 안내 (non-authoritative for runtime capability decisions)**
|
||||
> **정본 안내 (runtime capability 결정의 정본이 아니다)**
|
||||
>
|
||||
> Runtime Config/boot, Fetch HTTP client, Router, Query/Mutation, realtime 공통 경계, Web Worker,
|
||||
> Service Worker, offline command와 Background Sync의 구현 결정은
|
||||
> [프론트엔드 런타임 Capability 저장소 정합형 구현 결정 폐쇄 상세 설계](./2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md)가 정본이다.
|
||||
> [프론트엔드 런타임 Capability 저장소 정합형 구현 결정 폐쇄 상세 설계](../design/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md)가 정본이다.
|
||||
> 본 문서의 해당 서술이 정본과 충돌하면 정본을 따른다.
|
||||
|
||||
|
||||
This Mermaid view is a repository-local implementation projection. The
|
||||
`PASS_SCOPED` reviewer evidence applies only to the canonical static-delivery
|
||||
draw.io scope recorded in `review-ledger.json`.
|
||||
이 Mermaid 그림은 repo 안에서 구현을 옮겨 그린 투영(projection)이다.
|
||||
`PASS_SCOPED` 리뷰 증거는 `review-ledger.json`에 적힌 정본 static-delivery
|
||||
draw.io 범위에만 적용된다.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
@@ -29,34 +29,34 @@ sequenceDiagram
|
||||
CI->>Browser: boot, route, API, and reload-loop smoke
|
||||
```
|
||||
|
||||
In this repository the workflow deploys nothing. The upload, pointer switch
|
||||
and smoke steps above belong to the project's provider adapter, which fills the
|
||||
`deployment` job between `promotion` and `production_gate`. After it has
|
||||
deployed the promoted release, FE-GATE-019 probes the live headers and checks
|
||||
that the host serves that release; while the slot is empty FE-GATE-019 is
|
||||
`UNVERIFIED` (reviews 13-05, 1101/13-01,
|
||||
이 repo에서 workflow는 아무것도 배포하지 않는다. 위의 업로드, pointer 전환,
|
||||
smoke 단계는 프로젝트의 provider adapter가 맡는다. 그 adapter가 `promotion`과
|
||||
`production_gate` 사이의 `deployment` job을 채운다. adapter가 promotion된
|
||||
release를 배포하고 나면, FE-GATE-019가 실제 응답 header를 검사하고 host가 그
|
||||
release를 서빙하는지 확인한다. 그 자리가 비어 있는 동안 FE-GATE-019는
|
||||
`UNVERIFIED`다(리뷰 13-05, 1101/13-01,
|
||||
[`release-cache-rollback.md`](../operations/release-cache-rollback.md)).
|
||||
|
||||
Rollback changes the active pointer only after confirming that the prior
|
||||
immutable release has a coherent HTML/assets/config/API/manifest tuple.
|
||||
rollback은 이전 불변 release의 HTML·asset·config·API·manifest 묶음이 서로
|
||||
맞는지 확인한 뒤에만 active pointer를 바꾼다.
|
||||
|
||||
Serve the app over HTTP/2 or later. The entry preloads every initial
|
||||
JavaScript file in parallel (`initialJsFiles` in
|
||||
`config/performance/budgets.json` bounds how many; the current count is
|
||||
`initialJavascript.files` in `config/scale/feature-shape-ceilings.json`, which goes with the sample feature). Over HTTP/1.1 they queue for six connections per
|
||||
host, and the first screen on Fast 3G came about one second later than with the
|
||||
initial chunks grouped (2026-11-03). Over HTTP/2 the difference was under
|
||||
100 ms, so the template keeps the chunks split. A product that can only serve
|
||||
HTTP/1.1 groups its initial chunks in `vite.config.ts` and measures again
|
||||
whenever the shell changes ("초기 청크 수와 HTTP/1.1" in
|
||||
[`performance-evidence.md`](../operations/performance-evidence.md), review
|
||||
1101/14.4).
|
||||
앱은 HTTP/2 이상으로 서빙한다. 진입점은 모든 초기 JavaScript 파일을 병렬로
|
||||
미리 불러온다(preload). 몇 개까지 허용할지는 `config/performance/budgets.json`의
|
||||
`initialJsFiles`가 정한다. 지금 개수는
|
||||
`config/scale/feature-shape-ceilings.json`의 `initialJavascript.files`이고, 이
|
||||
값은 예시 feature를 기준으로 한다. HTTP/1.1에서는 host마다 연결이 여섯 개라
|
||||
파일이 줄을 선다. 그래서 Fast 3G에서 첫 화면이 초기 chunk를 묶었을 때보다 약
|
||||
1초 늦게 떴다(2026-11-03). HTTP/2에서는 차이가 100 ms 미만이었다. 그래서
|
||||
템플릿은 chunk를 나눈 채로 둔다. HTTP/1.1로만 서빙할 수 있는 제품은
|
||||
`vite.config.ts`에서 초기 chunk를 묶는다. 그리고 shell이 바뀔 때마다 다시
|
||||
잰다([`performance-evidence.md`](../operations/performance-evidence.md)의
|
||||
「초기 청크 수와 HTTP/1.1」, 리뷰 1101/14.4).
|
||||
|
||||
Serve JavaScript compressed (gzip, brotli or zstd). The bundle budget counts
|
||||
gzip bytes; uncompressed, the initial JavaScript is about three times larger.
|
||||
Both premises are declared in `config/hosting/cache-policy.json`
|
||||
(`transport.alpnProtocols`, `hashedAsset.contentEncodings`), and the live probe
|
||||
of FE-GATE-019 fails a host that does not meet them (review 1103/13-02). Every
|
||||
condition the host has to meet, and what checks each one, is in 「운영 환경이
|
||||
지켜야 할 조건」 in
|
||||
[`release-cache-rollback.md`](../operations/release-cache-rollback.md#운영-환경이-지켜야-할-조건).
|
||||
JavaScript는 압축해서(gzip, brotli, zstd 중 하나) 서빙한다. 번들 budget은
|
||||
gzip 바이트를 센다. 압축하지 않으면 초기 JavaScript가 약 세 배 커진다. 두
|
||||
전제는 `config/hosting/cache-policy.json`에 선언되어 있다
|
||||
(`transport.alpnProtocols`, `hashedAsset.contentEncodings`). FE-GATE-019의
|
||||
실제 host 검사(live probe)는 이 전제를 지키지 않는 host를 실패시킨다(리뷰
|
||||
1103/13-02). host가 지켜야 할 조건 전부와 각 조건을 무엇이 검사하는지는
|
||||
[`release-cache-rollback.md`](../operations/release-cache-rollback.md#운영-환경이-지켜야-할-조건)의
|
||||
「운영 환경이 지켜야 할 조건」에 있다.
|
||||
|
||||
@@ -1,80 +1,82 @@
|
||||
# Contract compatibility and rollback rules
|
||||
# 계약 호환성과 rollback 규칙
|
||||
|
||||
The blocking tuple is `(buildId, configSchemaVersion, apiContractVersion,
|
||||
assetManifestHash, releaseId)`. Versions are parsed numerically.
|
||||
차단 기준이 되는 tuple은 `(buildId, configSchemaVersion, apiContractVersion,
|
||||
assetManifestHash, releaseId)`이다. version은 숫자로 파싱한다.
|
||||
|
||||
1. a change is additive only when it adds an optional field that every
|
||||
reader of the previous version tolerates; see the boundary table below
|
||||
2. breaking changes require a major version bump or a reader-first deployment
|
||||
3. persisted cache is discarded unless an explicit tested migration exists
|
||||
4. an incompatible config or API contract blocks product mount
|
||||
5. rollback restores HTML, assets, runtime config, API compatibility, and
|
||||
release manifest as one coherent set
|
||||
1. 변경이 추가(additive)로 인정되는 것은 이전 version의 모든 reader가 받아들이는
|
||||
선택 필드를 더할 때뿐이다. 아래 경계별 표를 본다
|
||||
2. 깨지는(breaking) 변경은 major version을 올리거나 reader를 먼저 배포해야 한다
|
||||
3. 저장된 cache는 테스트된 명시적 migration이 없으면 버린다
|
||||
4. 호환되지 않는 config나 API 계약은 제품 mount를 막는다
|
||||
5. rollback은 HTML, asset, runtime config, API 호환성, release manifest를 하나의
|
||||
일관된 묶음으로 되돌린다
|
||||
|
||||
## Per-boundary rules
|
||||
## 경계별 규칙
|
||||
|
||||
Whether "add a field" is safe depends on the reader, not on the writer. Old
|
||||
readers stay alive: several tabs, cached app shells and rollbacks are all
|
||||
supported. At a `REJECT_UNKNOWN` boundary an added field is breaking, so the
|
||||
reader that accepts it must ship before any writer sends it.
|
||||
"필드 추가"가 안전한지는 쓰는 쪽(writer)이 아니라 읽는 쪽(reader)에 달려 있다.
|
||||
옛 reader는 계속 살아 있다. 여러 탭, cache된 앱 셸, rollback을 모두 지원하기
|
||||
때문이다. `REJECT_UNKNOWN` 경계에서는 필드를 더하면 깨진다. 그래서 그 필드를
|
||||
받아들이는 reader를 먼저 배포해야 한다. 어떤 writer든 그 뒤에야 그 필드를 보낼
|
||||
수 있다.
|
||||
|
||||
| Boundary | Reader policy | Adding a field or value | Code |
|
||||
| 경계 | reader 정책 | 필드나 값 추가 | 코드 |
|
||||
|---|---|---|---|
|
||||
| Runtime config V2 (`/config.json`) | strict object; `CONFIG_SCHEMA_VERSION` is the literal `"2.0"` | breaking | `runtimeConfigV2ArtifactSchema` in `src/contracts/release-artifacts.ts` |
|
||||
| `CAPABILITY_OVERRIDES` | strict; unknown capability rejected | breaking | `capabilityOverrideArtifactSchema` in `src/contracts/release-artifacts.ts` |
|
||||
| `FEATURE_OVERRIDES` | record; unknown feature id ignored | additive | `featureOverrideArtifactSchema` in `src/contracts/release-artifacts.ts` |
|
||||
| Release manifest V2 | strict object | breaking | `releaseManifestV2ArtifactSchema` in `src/contracts/release-artifacts.ts` |
|
||||
| HTTP success/failure envelope (V3 with `responseEnvelope: "ENVELOPE_V1"`) | strict object (`meta` strips) | breaking | `successEnvelopeSchema`, `failureEnvelopeSchema` in `src/adapters/http/backend-envelope.ts` |
|
||||
| HTTP V3 response DTO (a feature's) | `.strip()` drops unknown fields | additive | `<camel>ItemDtoSchema` in `contracts/<base>-schemas.ts` of a feature `create:feature` writes |
|
||||
| Realtime envelope | exact key set; unknown `eventType` is `MALFORMED_EVENT` | breaking | `decodeUnsafe` in `src/adapters/realtime/event-codec.ts` |
|
||||
| Browser RPC transport error code | closed vocabulary; unknown code is a protocol violation | breaking | `decodeTransportFailure` in `src/adapters/browser-rpc/browser-rpc-runtime.ts` |
|
||||
| Persisted client storage | versioned key; incompatible value discarded | use a new key version | `defineStorageKey` in `src/contracts/storage-keys.ts` |
|
||||
| Runtime config V2 (`/config.json`) | 엄격한(strict) object. `CONFIG_SCHEMA_VERSION`은 리터럴 `"2.0"` | 깨짐 | `src/contracts/release-artifacts.ts`의 `runtimeConfigV2ArtifactSchema` |
|
||||
| `CAPABILITY_OVERRIDES` | 엄격함. 모르는 capability는 거부 | 깨짐 | `src/contracts/release-artifacts.ts`의 `capabilityOverrideArtifactSchema` |
|
||||
| `FEATURE_OVERRIDES` | record. 모르는 feature id는 무시 | 추가로 인정 | `src/contracts/release-artifacts.ts`의 `featureOverrideArtifactSchema` |
|
||||
| Release manifest V2 | 엄격한 object | 깨짐 | `src/contracts/release-artifacts.ts`의 `releaseManifestV2ArtifactSchema` |
|
||||
| HTTP 성공·실패 envelope (V3에서 `responseEnvelope: "ENVELOPE_V1"`) | 엄격한 object(`meta`는 걸러 냄) | 깨짐 | `src/adapters/http/backend-envelope.ts`의 `successEnvelopeSchema`, `failureEnvelopeSchema` |
|
||||
| HTTP V3 응답 DTO (feature의 것) | `.strip()`이 모르는 필드를 버림 | 추가로 인정 | `create:feature`가 만드는 feature의 `contracts/<base>-schemas.ts`에 있는 `<camel>ItemDtoSchema` |
|
||||
| Realtime envelope | 정확한 key 집합. 모르는 `eventType`은 `MALFORMED_EVENT` | 깨짐 | `src/adapters/realtime/event-codec.ts`의 `decodeUnsafe` |
|
||||
| Browser RPC 전송 오류 code | 닫힌 어휘. 모르는 code는 protocol 위반 | 깨짐 | `src/adapters/browser-rpc/browser-rpc-runtime.ts`의 `decodeTransportFailure` |
|
||||
| 저장된 클라이언트 storage | version이 붙은 key. 호환되지 않는 값은 버림 | 새 key version을 쓴다 | `src/contracts/storage-keys.ts`의 `defineStorageKey` |
|
||||
|
||||
Turning a response DTO strict changes its row in this table. `check:registries`
|
||||
grades it as breaking (`response-reader-narrowed`) when the FE-REG-SCHEMA row
|
||||
of a `RESPONSE` schema goes from `STRIP_UNKNOWN` to `REJECT_UNKNOWN`, so the
|
||||
change needs registry evidence (1105/07-02).
|
||||
응답 DTO를 엄격하게 바꾸면 이 표에서 그 행이 바뀐다. `RESPONSE` schema의
|
||||
FE-REG-SCHEMA 행이 `STRIP_UNKNOWN`에서 `REJECT_UNKNOWN`으로 바뀌면
|
||||
`check:registries`가 이를 깨지는 변경(`response-reader-narrowed`)으로 판정한다.
|
||||
그래서 그 변경에는 registry 증거가 필요하다(1105/07-02).
|
||||
|
||||
`CAPABILITY_OVERRIDES` and `FEATURE_OVERRIDES` differ on purpose. Feature ids
|
||||
vary per build because each downstream project installs its own features, and
|
||||
one shared config document may cover several builds. The capability set is
|
||||
fixed by the platform version, so an unknown capability means the config was
|
||||
written for a newer platform; it is treated like any other strict config
|
||||
addition.
|
||||
`CAPABILITY_OVERRIDES`와 `FEATURE_OVERRIDES`는 일부러 다르게 둔다. feature id는
|
||||
빌드마다 다르다. 다운스트림 프로젝트마다 자기 feature를 설치하기 때문이다.
|
||||
그리고 공유 config 문서 하나가 여러 빌드를 덮을 수 있다. capability 집합은
|
||||
platform version이 정한다. 그래서 모르는 capability가 있다는 것은 그 config가 더
|
||||
새 platform을 위해 쓰였다는 뜻이다. 이것은 다른 엄격한 config 추가와 똑같이
|
||||
다룬다.
|
||||
|
||||
## Schema change classifier and FE-GATE-014
|
||||
## Schema 변경 분류기와 FE-GATE-014
|
||||
|
||||
`classifyObjectSchemaChange` (`src/contracts/compatibility.ts`) answers
|
||||
for a reader built against `before`. It is fail-closed: only a new property
|
||||
under a reader without `additionalProperties: false` is `additive`. A removed
|
||||
or changed property (type, enum, nullable, format, ...), a different required
|
||||
set, or any other changed keyword is `breaking`. Nothing differs: `none`.
|
||||
`classifyObjectSchemaChange`(`src/contracts/compatibility.ts`)는 `before`를
|
||||
기준으로 만든 reader 입장에서 답한다. fail closed로 동작한다:
|
||||
`additionalProperties: false`가 없는 reader 아래에 새 property를 더한 경우만
|
||||
`additive`다. property를 지우거나 바꾸는 것(type, enum, nullable, format 등),
|
||||
required 집합이 달라지는 것, 그 밖의 keyword가 바뀌는 것은 모두 `breaking`이다.
|
||||
아무것도 다르지 않으면 `none`이다.
|
||||
|
||||
FE-GATE-014 (`config-compatibility`, `corepack pnpm verify:compatibility`)
|
||||
runs `scripts/check-compatibility.ts`. It does two things:
|
||||
FE-GATE-014(`config-compatibility`, `corepack pnpm verify:compatibility`)는
|
||||
`scripts/check-compatibility.ts`를 실행한다. 이 스크립트는 두 가지를 한다.
|
||||
|
||||
1. Classifies the hand-written cases in `config/compatibility/fixtures.json`
|
||||
and fails if any result differs from `expected`.
|
||||
2. Compares the committed baseline
|
||||
`config/compatibility/runtime-config.schema.baseline.json` with the current
|
||||
runtime config schema, which is the same `z.toJSONSchema` output the build
|
||||
writes to `dist/runtime-config.schema.json`
|
||||
(`scripts/generate-build-manifest.ts`). A `breaking` result fails the gate.
|
||||
1. `config/compatibility/fixtures.json`에 손으로 쓴 사례를 분류하고, 결과가
|
||||
하나라도 `expected`와 다르면 실패한다.
|
||||
2. commit된 기준선 `config/compatibility/runtime-config.schema.baseline.json`을
|
||||
지금 runtime config schema와 비교한다. 지금 schema는 빌드가
|
||||
`dist/runtime-config.schema.json`에 쓰는 것과 같은 `z.toJSONSchema`
|
||||
출력이다(`scripts/generate-build-manifest.ts`). 결과가 `breaking`이면 gate가
|
||||
실패한다.
|
||||
|
||||
The baseline stands for the schema that readers of the previous release
|
||||
accept. When a breaking config change is intended, deploy the reader first (or
|
||||
bump the config major version), then run
|
||||
`corepack pnpm verify:compatibility --update-baseline` and commit the new
|
||||
baseline with the change. The result is recorded in
|
||||
`artifacts/release/compatibility.json`.
|
||||
기준선은 이전 release의 reader가 받아들이는 schema를 나타낸다. 깨지는 config
|
||||
변경을 의도했다면 reader를 먼저 배포한다(또는 config major version을 올린다).
|
||||
그다음 `corepack pnpm verify:compatibility --update-baseline`을 실행하고, 새
|
||||
기준선을 변경과 함께 commit한다. 결과는 `artifacts/release/compatibility.json`에
|
||||
기록된다.
|
||||
|
||||
The current `apiContractVersion` check proves release/config coherence, not
|
||||
provider conformance by itself. The target multi-protocol contract set binds
|
||||
REST/OpenAPI artifacts, GraphQL schema and persisted-operation manifests,
|
||||
protobuf source/descriptors/codegen profiles, Connect/gRPC-Web provider profiles,
|
||||
ProtoJSON/HttpRule/generated OpenAPI/gateway artifacts, runtime schema/mapper
|
||||
registries, and server-state policy digests as defined in
|
||||
[API contract, Schema, Mapper, and Server State](../architecture/api-contract-schema-mapper-and-server-state.md).
|
||||
Browser Protobuf and REST Gateway compatibility is further split in
|
||||
[Protobuf browser transport and REST Gateway](../architecture/protobuf-browser-transport-and-rest-gateway.md);
|
||||
binary/JSON/HTTP-route compatibility gates are not interchangeable.
|
||||
지금의 `apiContractVersion` 검사는 release와 config가 서로 맞는다는 것을
|
||||
증명한다. 그것만으로 provider가 계약을 지킨다는 것까지 증명하지는 않는다. 목표로
|
||||
하는 다중 protocol 계약 묶음은
|
||||
[API contract, Schema, Mapper와 Server State](../design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md)에
|
||||
정의된 대로 다음을 묶는다: REST/OpenAPI artifact, GraphQL schema와
|
||||
persisted-operation manifest, protobuf source·descriptor·codegen profile,
|
||||
Connect/gRPC-Web provider profile, ProtoJSON·HttpRule·생성된 OpenAPI·gateway
|
||||
artifact, runtime schema·mapper registry, server-state 정책 digest.
|
||||
브라우저 Protobuf와 REST Gateway 호환성은
|
||||
[Protobuf browser transport와 REST Gateway](../design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md)에서
|
||||
더 나눈다. binary·JSON·HTTP route 호환성 gate는 서로 바꿔 쓸 수 없다.
|
||||
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-07-26
|
||||
- 요약: 기능 화면을 만들기 전에 템플릿이 줄 디자인 시스템의 소유권, 계층, 기본 구성요소, 외부 라이브러리 경계와 검증 방법을 정한 설계다.
|
||||
- 현재 정본: `src/presentation/design-system/`, `docs/styling/design-tokens.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# 디자인 시스템 플랫폼 계약
|
||||
|
||||
이 문서는 도메인 기능을 추가하기 전에 프론트엔드 스켈레톤이 제공해야 하는
|
||||
+22
-13
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-07-26
|
||||
- 요약: 새 프론트 제품의 출발점이 갖춰야 할 공통 역량을 실제 호출 경로와 게이트 기준으로 다시 평가하고 RP-01~RP-12 결과를 누적한 검토다.
|
||||
- 현재 정본: `docs/architecture/overview.md`, `config/recipes/frontend-capability-recipes.json`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# 프론트엔드 플랫폼 역량 재검토
|
||||
|
||||
> **정본 안내 (non-authoritative for runtime capability decisions)**
|
||||
@@ -93,13 +102,13 @@ P0/P1 acceptance와 P2 recipe 기본값은 `LOCAL_TEMPLATE_READY`다. 다만 실
|
||||
| 샘플 제거 | 준비됨 | feature/catalog/test 제거 후 type/architecture/registry/test/home/build 9단계 검증 | 새 contribution도 같은 제거 gate에 포함 |
|
||||
| registry·compatibility 집행 | 준비됨 | 10개 registry type/reference/consumer/orphan, 승인 digest와 actual semantic diff, breaking evidence | public 계약 변경 시 baseline review 유지 |
|
||||
| 공급망 검사 | 준비됨/프로젝트 선택 | 561개 transitive inventory/integrity/license, actual diff, CycloneDX, local provenance, secret/reproducible build gate | 실제 vulnerability scanner와 signed attestation 없이는 promotion `FAIL_UNVERIFIED` |
|
||||
| realtime delivery | 참조 런타임 준비됨/프로젝트 미선택 | RT-01~04 공통 event authority, fetch-stream SSE, closed WebSocket, bounded Polling, Web Push window/worker와 handoff/reconnect 조정자는 `AVAILABLE_NOT_COMPOSED`; backend/provider/browser evidence는 없음 | [Realtime events, Web Push, and bounded polling](./realtime-events-web-push-and-bounded-polling.md)의 RT-05 제품 조립·운영 증거를 capability별로 통과 |
|
||||
| offline·file·browser data | 부분 준비/프로젝트 선택 | opt-in recipe와 gate; capability별 구현·조합·미구현·미선택·platform 제한 상태가 서로 다름 | [Browser data capability completion ledger](./browser-data-capability-completion-ledger.md)의 상태와 work package를 통과한 capability만 설치 |
|
||||
| realtime delivery | 참조 런타임 준비됨/프로젝트 미선택 | RT-01~04 공통 event authority, fetch-stream SSE, closed WebSocket, bounded Polling, Web Push window/worker와 handoff/reconnect 조정자는 `AVAILABLE_NOT_COMPOSED`; backend/provider/browser evidence는 없음 | [Realtime events, Web Push, and bounded polling](./2026-07-30-realtime-events-web-push-and-bounded-polling-design.md)의 RT-05 제품 조립·운영 증거를 capability별로 통과 |
|
||||
| offline·file·browser data | 부분 준비/프로젝트 선택 | opt-in recipe와 gate; capability별 구현·조합·미구현·미선택·platform 제한 상태가 서로 다름 | [Browser data capability completion ledger](./2026-07-30-browser-data-capability-completion-ledger-design.md)의 상태와 work package를 통과한 capability만 설치 |
|
||||
|
||||
REST/GraphQL/Connect/gRPC-Web/REST Gateway, Schema/Mapper와 Server State의 상세 current/target 판정은
|
||||
[API contract, Schema, Mapper와 Server State](./api-contract-schema-mapper-and-server-state.md)를
|
||||
[API contract, Schema, Mapper와 Server State](./2026-07-28-api-contract-schema-mapper-and-server-state-design.md)를
|
||||
따른다. Browser Protobuf 축의 선택 기준은
|
||||
[Protobuf browser transport와 REST Gateway](./protobuf-browser-transport-and-rest-gateway.md)를
|
||||
[Protobuf browser transport와 REST Gateway](./2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md)를
|
||||
따른다. 현재 REST reference 경로의 `COMPOSED` 판정을 GraphQL/Connect/gRPC-Web/
|
||||
Gateway 또는 REST v2 hardening 완료 증거로 재사용하지 않는다.
|
||||
|
||||
@@ -334,7 +343,7 @@ Web Push provider selection은 여전히 `NOT_SELECTED`이며 production bootstr
|
||||
worker에는 조립하지 않는다.
|
||||
|
||||
이 capability들을 한꺼번에 "준비됨"으로 표시하지 않는다.
|
||||
[Browser data capability completion ledger](./browser-data-capability-completion-ledger.md)가
|
||||
[Browser data capability completion ledger](./2026-07-30-browser-data-capability-completion-ledger-design.md)가
|
||||
`COMPOSED`, `AVAILABLE_NOT_COMPOSED`, `DESIGNED_NOT_IMPLEMENTED`,
|
||||
`NOT_SELECTED`, `PLATFORM_LIMITED`를 구분하는 현재 상태의 기준이다. 특히
|
||||
session/account Query lifecycle, Range resumable download, cross-store quota
|
||||
@@ -522,11 +531,11 @@ data 같은 프로젝트별 외부 작업을 포함하지 않는다.
|
||||
|
||||
## 8. 관련 상세 문서
|
||||
|
||||
- [API contract, Schema, Mapper와 Server State](./api-contract-schema-mapper-and-server-state.md)
|
||||
- [Realtime events, Web Push, and bounded polling](./realtime-events-web-push-and-bounded-polling.md)
|
||||
- [프론트 포트·어댑터와 기능 경계](./frontend-ports-adapters-and-boundaries.md)
|
||||
- [TypeScript·상태·데이터 흐름](./typescript-state-and-data-flow.md)
|
||||
- [라우팅·페이지·재사용 패턴](./routing-pages-and-patterns.md)
|
||||
- [프론트 플랫폼 구현 로드맵](./frontend-platform-implementation-roadmap.md)
|
||||
- [디자인 시스템 플랫폼](../styling/design-system-platform.md)
|
||||
- [프론트 플랫폼 테스트 전략](../testing/frontend-platform-testing-strategy.md)
|
||||
- [API contract, Schema, Mapper와 Server State](./2026-07-28-api-contract-schema-mapper-and-server-state-design.md)
|
||||
- [Realtime events, Web Push, and bounded polling](./2026-07-30-realtime-events-web-push-and-bounded-polling-design.md)
|
||||
- [프론트 포트·어댑터와 기능 경계](./2026-07-26-frontend-ports-adapters-and-boundaries-design.md)
|
||||
- [TypeScript·상태·데이터 흐름](./2026-07-26-typescript-state-and-data-flow-design.md)
|
||||
- [라우팅·페이지·재사용 패턴](./2026-07-26-routing-pages-and-patterns-design.md)
|
||||
- [프론트 플랫폼 구현 로드맵](./2026-07-26-frontend-platform-implementation-roadmap-design.md)
|
||||
- [디자인 시스템 플랫폼](2026-07-26-design-system-platform-design.md)
|
||||
- [프론트 플랫폼 테스트 전략](2026-07-26-frontend-platform-testing-strategy-design.md)
|
||||
+15
-6
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-07-26
|
||||
- 요약: 선언된 프론트 계약을 실제 runtime과 자동 검증까지 잇는 P0·P1·P2 구현 순서와 브랜치 계획을 정한 설계다.
|
||||
- 현재 정본: `docs/architecture/overview.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# 프론트엔드 플랫폼 구현 로드맵
|
||||
|
||||
> **정본 안내 (non-authoritative for runtime capability decisions)**
|
||||
@@ -324,7 +333,7 @@ adapter로 연결한다.
|
||||
동작과 production wiring을 검증한다.
|
||||
- 상세 상태와 남은 session/account epoch, native multi-tab evidence 및 optional
|
||||
IndexedDB query persistence는
|
||||
[Client cache and browser storage platform](./client-cache-and-storage.md)에
|
||||
[Client cache and browser storage platform](./2026-07-28-client-cache-and-storage-design.md)에
|
||||
기록한다.
|
||||
|
||||
**Rollback**
|
||||
@@ -1086,7 +1095,7 @@ revert하고 RP-11을 유지한다. 여러 vendor를 되돌릴 수 없는 한 co
|
||||
query state/payload를 복제하지 않고 persistence는 계속 disabled다. 기존
|
||||
IndexedDB reference runtime은 이 선택 때문에 bootstrap에 조립되지 않는다.
|
||||
- 같은 날 VD-28과
|
||||
[Realtime events, Web Push, and bounded polling](./realtime-events-web-push-and-bounded-polling.md)을
|
||||
[Realtime events, Web Push, and bounded polling](./2026-07-30-realtime-events-web-push-and-bounded-polling-design.md)을
|
||||
추가했다. SSE, WebSocket, Web Push와 Polling을 별도 delivery capability로
|
||||
분리하고 공통 delivery guarantee 없음, duplicate-tolerant CURSOR 처리,
|
||||
gap/snapshot checkpoint, scope generation, bounded lifecycle과 promotion 계약을
|
||||
@@ -1107,7 +1116,7 @@ revert하고 RP-11을 유지한다. 여러 vendor를 되돌릴 수 없는 한 co
|
||||
|
||||
RP-12의 reference runtime 존재는 browser data platform 전체의 구현 완료를
|
||||
뜻하지 않는다. 현재 상태와 상세 exit criteria는
|
||||
[Browser data capability completion ledger](./browser-data-capability-completion-ledger.md)를
|
||||
[Browser data capability completion ledger](./2026-07-30-browser-data-capability-completion-ledger-design.md)를
|
||||
단일 기준으로 사용한다. 후속 구현은 다음 독립 package로 진행한다.
|
||||
|
||||
| 순서 | work package | 핵심 exit |
|
||||
@@ -1140,9 +1149,9 @@ transfer는 위 package에 암묵적으로 포함하지 않는다. 각각 `NOT_S
|
||||
|
||||
REST reference vertical의 `COMPOSED` 판정과 multi-protocol production hardening을
|
||||
구분한다. 현재/목표 상태, protocol 선택 기준과 완료 조건은
|
||||
[API contract, Schema, Mapper와 Server State](./api-contract-schema-mapper-and-server-state.md)가
|
||||
[API contract, Schema, Mapper와 Server State](./2026-07-28-api-contract-schema-mapper-and-server-state-design.md)가
|
||||
소유한다. Browser Protobuf runtime과 gateway branch의 세부 기준은
|
||||
[Protobuf browser transport와 REST Gateway](./protobuf-browser-transport-and-rest-gateway.md)를
|
||||
[Protobuf browser transport와 REST Gateway](./2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md)를
|
||||
따른다.
|
||||
|
||||
| 순서 | work package | 핵심 exit |
|
||||
@@ -1173,7 +1182,7 @@ config를 기본 bundle에 넣지 않는다. browser client/bidirectional stream
|
||||
copyable recipe의 교육용 `RealtimePort`와 fake는 production runtime 증거가
|
||||
아니다. 현재 상태,
|
||||
transport 선택, event authority와 완료 기준은
|
||||
[Realtime events, Web Push, and bounded polling](./realtime-events-web-push-and-bounded-polling.md)이
|
||||
[Realtime events, Web Push, and bounded polling](./2026-07-30-realtime-events-web-push-and-bounded-polling-design.md)이
|
||||
소유한다.
|
||||
|
||||
| 순서 | work package | 핵심 exit |
|
||||
+11
-2
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-07-26
|
||||
- 요약: 프론트 플랫폼의 위험을 unit·contract·MSW·브라우저·시각 회귀 중 어느 테스트 계층에서 막을지 정한 테스트 전략이다.
|
||||
- 현재 정본: `docs/testing/taxonomy.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# 프론트엔드 플랫폼 테스트 전략
|
||||
|
||||
이 문서는 도메인 기능을 추가하기 전과 추가한 후에 프론트엔드 플랫폼의 위험을
|
||||
@@ -621,14 +630,14 @@ client route guard는 UX이며 authorization이 아님을 test 이름과 문서
|
||||
공용 컴포넌트는 한 번의 결함이 모든 페이지로 전파되므로 위험도가 높다.
|
||||
|
||||
RP-07의 실행 경로는 `check:design-system`,
|
||||
`check:design-system:fixture`, `check:types:fixtures`(`invalid-icon-button.tsx`),
|
||||
`check:design-system:fixture`, `check:types:fixture:icon-button`,
|
||||
`tests/component/design-system-platform.test.tsx`와
|
||||
`tests/e2e/design-system-interactions.spec.ts`다. Story interaction/visual
|
||||
baseline은 VD-08/RP-10에서 추가하며 현재 runtime gallery를 isolated workshop
|
||||
완료 증거로 사용하지 않는다.
|
||||
|
||||
RP-08의 국제화 실행 경로는 `check:i18n`, `check:i18n:fixture`,
|
||||
`check:types:fixtures`(`invalid-message-key.ts`, `invalid-message-params.ts`),
|
||||
`check:types:fixture:i18n-key`, `check:types:fixture:i18n-params`,
|
||||
`tests/unit/i18n-contract.test.ts`, `tests/component/locale-platform.test.tsx`와
|
||||
`tests/e2e/i18n.spec.ts`다.
|
||||
|
||||
+11
-2
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-07-26
|
||||
- 요약: inbound·outbound 포트와 adapter의 방향, React·Router·Query·HTTP 같은 기술의 자리, 새 adapter와 feature를 더하는 순서를 정한 설계다.
|
||||
- 현재 정본: `docs/architecture/layers.md`, `docs/architecture/frontend-application-foundation.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# 프론트엔드 포트·어댑터와 경계 설계
|
||||
|
||||
> **정본 안내 (non-authoritative for runtime capability decisions)**
|
||||
@@ -170,7 +179,7 @@ RP-03 구현으로 HTTP와 server-state 경계도 다음처럼 연결됐다.
|
||||
invariant, auth unavailable fail-close, total deadline, bounded response decoder,
|
||||
typed Schema/Mapper proof, complete pagination과 mutation concurrency 같은
|
||||
production hardening delta는
|
||||
[API contract, Schema, Mapper와 Server State](./api-contract-schema-mapper-and-server-state.md)에
|
||||
[API contract, Schema, Mapper와 Server State](./2026-07-28-api-contract-schema-mapper-and-server-state-design.md)에
|
||||
별도 `DESIGNED_NOT_IMPLEMENTED`로 기록한다.
|
||||
|
||||
RP-04에서 route 실행 불일치는 닫혔다. route registry와 runtime map은
|
||||
@@ -944,7 +953,7 @@ capability의 기본 정책, port 또는 안전한 no-op 구현과 composition
|
||||
조건, 보안 영향, bundle 비용과 제거 방법이 확인된 경우에만 추가한다.
|
||||
SSE, WebSocket, Web Push와 bounded polling의 서로 다른 delivery 의미,
|
||||
inbound/outbound 분리, resume·gap·lifecycle과 현재 상태는
|
||||
[Realtime events, Web Push, and bounded polling](./realtime-events-web-push-and-bounded-polling.md)을
|
||||
[Realtime events, Web Push, and bounded polling](./2026-07-30-realtime-events-web-push-and-bounded-polling-design.md)을
|
||||
따른다.
|
||||
Web Push는 subscription/provider/worker delivery를, 별도 Notification 행은
|
||||
permission과 user-visible rendering facade를 뜻한다. bounded polling은 inbound
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-07-26
|
||||
- 요약: typed route, 접근 guard, lazy chunk 복구, 이동할 때의 focus·취소 처리, 공통 page template과 재사용 패턴의 기준을 정한 설계다.
|
||||
- 현재 정본: `src/presentation/routes/`, `src/presentation/templates/`, `docs/manual/reference/patterns.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# 라우팅, 페이지 템플릿, 재사용 패턴
|
||||
|
||||
> **정본 안내 (non-authoritative for runtime capability decisions)**
|
||||
+12
-3
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-07-26
|
||||
- 요약: TypeScript 전용 경계를 지키는 법과 local·URL·server·form·영속 상태를 둘 곳, HTTP·재시도·오류 책임을 나누는 법을 정한 설계다.
|
||||
- 현재 정본: `docs/manual/reference/patterns.md`, `src/presentation/adapters/query/`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# TypeScript, 상태 소유권, 데이터 흐름
|
||||
|
||||
> **정본 안내 (non-authoritative for runtime capability decisions)**
|
||||
@@ -20,9 +29,9 @@
|
||||
|
||||
이 문서는 현재 구현된 TypeScript 경계와 상태/데이터 흐름의 저장소 표준이다.
|
||||
세부 역량의 구현 상태는
|
||||
[프론트엔드 플랫폼 역량 재검토](./frontend-platform-capability-review.md)를
|
||||
[프론트엔드 플랫폼 역량 재검토](./2026-07-26-frontend-platform-capability-review-design.md)를
|
||||
따른다. memory query cache, Web Storage와 탭 간 invalidation의 세부 protocol은
|
||||
[Client cache and browser storage platform](./client-cache-and-storage.md)에
|
||||
[Client cache and browser storage platform](./2026-07-28-client-cache-and-storage-design.md)에
|
||||
기록한다.
|
||||
|
||||
## 2. TypeScript 전환 원칙
|
||||
@@ -94,7 +103,7 @@ Node가 직접 실행하는 script/config project는 추가로 `NodeNext`,
|
||||
사용하되 저장소 내부 상대 import에 실제 `.ts/.tsx` 확장자를 기록한다.
|
||||
|
||||
현재 저장소의 VD-01 결정은
|
||||
[TypeScript 7과 ESLint 10의 점진적 전환 도구](./decisions/VD-01-typescript-lint-tooling.md)에
|
||||
[TypeScript 7과 ESLint 10의 점진적 전환 도구](../adr/VD-01-typescript-lint-tooling.md)에
|
||||
기록돼 있다. app, Node scripts/config, tests는 각각 독립된 strict project로
|
||||
typecheck한다. TypeScript 7을 아직 지원하지 않는 parser plugin을 강제
|
||||
설치하지 않고 Babel parser는 lint syntax/import/security 검사, `tsc`는 type
|
||||
+10
-1
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-07-27
|
||||
- 요약: File·Blob·파일 선택기·다운로드·IndexedDB·OPFS·Cache Storage를 운영에 넣을 때의 경계, 프로토콜, 실패·복구 정책과 승격 증거를 정한 설계다.
|
||||
- 현재 정본: `src/adapters/browser-files/`, `src/adapters/storage/`, `docs/operations/browser-file-storage-recovery.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Browser file and origin-storage platform
|
||||
|
||||
이 문서는 File, Blob, 파일 선택기, 다운로드, IndexedDB, OPFS, Cache Storage를
|
||||
@@ -40,7 +49,7 @@ receipt retention/prune가 구현되어 있으며 bootstrap에서만 분리되
|
||||
## 0. 후속 lifecycle/migration 결정과 현재 delta
|
||||
|
||||
origin storage를 제품에 composition하기 전 남은 공통 lifecycle 설계는
|
||||
[VD-15: Origin storage lifecycle, migration, and optional file capabilities](./decisions/VD-15-origin-storage-lifecycle-and-migration.md)에
|
||||
[VD-15: Origin storage lifecycle, migration, and optional file capabilities](../adr/VD-15-origin-storage-lifecycle-and-migration.md)에
|
||||
고정한다. VD-15가 Accepted됐다는 사실은 해당 runtime이 구현 또는 조립됐다는
|
||||
뜻이 아니다.
|
||||
|
||||
+27
-18
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-07-28
|
||||
- 요약: REST·GraphQL·Connect·gRPC-Web·Protobuf gateway에 걸친 API 계약, runtime schema, boundary mapper와 TanStack Query 기반 server state의 현재·목표 상태를 정한 설계다.
|
||||
- 현재 정본: `docs/architecture/backend-api-and-server-state-contract.md`, `docs/operations/api-contract-and-server-state-recovery.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# API contract, Schema, Mapper와 Server State platform
|
||||
|
||||
> **정본 안내 (non-authoritative for runtime capability decisions)**
|
||||
@@ -14,17 +23,17 @@
|
||||
Protobuf/REST Gateway, runtime Schema, boundary Mapper, TanStack Query 기반
|
||||
Server State Cache
|
||||
- 관련 결정:
|
||||
- [VD-23 API transport selection과 REST execution](./decisions/VD-23-api-transport-selection-and-rest-execution.md)
|
||||
- [VD-24 Runtime schema와 boundary mapper](./decisions/VD-24-runtime-schema-and-boundary-mapper.md)
|
||||
- [VD-25 Server state cache lifecycle](./decisions/VD-25-server-state-cache-lifecycle.md)
|
||||
- [VD-26 Persisted GraphQL operation](./decisions/VD-26-persisted-graphql-operation.md)
|
||||
- [VD-27 gRPC-Web unary와 server stream](./decisions/VD-27-grpc-web-unary-and-server-stream.md)
|
||||
- [VD-29 Connect-Web와 browser Protobuf runtime](./decisions/VD-29-connect-web-and-browser-protobuf-runtime.md)
|
||||
- [VD-30 Protobuf contract와 REST Gateway](./decisions/VD-30-protobuf-contract-and-rest-gateway.md)
|
||||
- [VD-23 API transport selection과 REST execution](../adr/VD-23-api-transport-selection-and-rest-execution.md)
|
||||
- [VD-24 Runtime schema와 boundary mapper](../adr/VD-24-runtime-schema-and-boundary-mapper.md)
|
||||
- [VD-25 Server state cache lifecycle](../adr/VD-25-server-state-cache-lifecycle.md)
|
||||
- [VD-26 Persisted GraphQL operation](../adr/VD-26-persisted-graphql-operation.md)
|
||||
- [VD-27 gRPC-Web unary와 server stream](../adr/VD-27-grpc-web-unary-and-server-stream.md)
|
||||
- [VD-29 Connect-Web와 browser Protobuf runtime](../adr/VD-29-connect-web-and-browser-protobuf-runtime.md)
|
||||
- [VD-30 Protobuf contract와 REST Gateway](../adr/VD-30-protobuf-contract-and-rest-gateway.md)
|
||||
- browser Protobuf/gateway 상세 설계:
|
||||
[Protobuf browser transport와 REST Gateway](./protobuf-browser-transport-and-rest-gateway.md)
|
||||
[Protobuf browser transport와 REST Gateway](./2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md)
|
||||
- backend handoff:
|
||||
[Backend API와 Server State contract](./backend-api-and-server-state-contract.md)
|
||||
[Backend API와 Server State contract](../architecture/backend-api-and-server-state-contract.md)
|
||||
- 운영 절차:
|
||||
[API contract와 server-state recovery](../operations/api-contract-and-server-state-recovery.md)
|
||||
|
||||
@@ -415,7 +424,7 @@ GraphQL 상세 결정은 VD-26이 소유한다. reference target은
|
||||
## 10. Browser Protobuf RPC와 REST Gateway 설계 요약
|
||||
|
||||
축과 선택 기준의 상세 계약은
|
||||
[Protobuf browser transport와 REST Gateway](./protobuf-browser-transport-and-rest-gateway.md)가
|
||||
[Protobuf browser transport와 REST Gateway](./2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md)가
|
||||
소유한다. Protobuf는 IDL/serialization, Connect와 gRPC-Web은 browser wire
|
||||
protocol, Connect-Web/official grpc-web은 client runtime, REST Gateway는 HTTP
|
||||
노출 방식이다. 네 이름을 하나의 대안 목록이나 하나의 auto-negotiating
|
||||
@@ -752,7 +761,7 @@ opening replay와 이후 resume 규칙은 VD-27이 계속 소유한다.
|
||||
|
||||
구현 owner, 권장 topology, 현재 reference endpoint/envelope, idempotency store,
|
||||
Cursor/ETag/revision과 protocol별 handoff checklist는
|
||||
[Backend API와 Server State contract](./backend-api-and-server-state-contract.md)가
|
||||
[Backend API와 Server State contract](../architecture/backend-api-and-server-state-contract.md)가
|
||||
소유한다. 아래 표는 frontend 설계가 요구하는 경계 요약이다.
|
||||
|
||||
| 경계 | backend/provider가 제공할 계약 |
|
||||
@@ -964,11 +973,11 @@ gRPC-Web과 REST Gateway를 “미래 대비” 목적으로 모두 기본 bundl
|
||||
|
||||
## 25. 관련 문서
|
||||
|
||||
- [Frontend ports, adapters, and boundaries](./frontend-ports-adapters-and-boundaries.md)
|
||||
- [Client cache and browser storage](./client-cache-and-storage.md)
|
||||
- [VD-13 Client cache scope와 persistence](./decisions/VD-13-client-cache-scope-and-persistence.md)
|
||||
- [Protobuf browser transport와 REST Gateway](./protobuf-browser-transport-and-rest-gateway.md)
|
||||
- [VD-29 Connect-Web와 browser Protobuf runtime](./decisions/VD-29-connect-web-and-browser-protobuf-runtime.md)
|
||||
- [VD-30 Protobuf contract와 REST Gateway](./decisions/VD-30-protobuf-contract-and-rest-gateway.md)
|
||||
- [Frontend ports, adapters, and boundaries](./2026-07-26-frontend-ports-adapters-and-boundaries-design.md)
|
||||
- [Client cache and browser storage](./2026-07-28-client-cache-and-storage-design.md)
|
||||
- [VD-13 Client cache scope와 persistence](../adr/VD-13-client-cache-scope-and-persistence.md)
|
||||
- [Protobuf browser transport와 REST Gateway](./2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md)
|
||||
- [VD-29 Connect-Web와 browser Protobuf runtime](../adr/VD-29-connect-web-and-browser-protobuf-runtime.md)
|
||||
- [VD-30 Protobuf contract와 REST Gateway](../adr/VD-30-protobuf-contract-and-rest-gateway.md)
|
||||
- [Contract compatibility](../contracts/compatibility.md)
|
||||
- [Frontend platform testing strategy](../testing/frontend-platform-testing-strategy.md)
|
||||
- [Frontend platform testing strategy](2026-07-26-frontend-platform-testing-strategy-design.md)
|
||||
+19
-10
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-07-28
|
||||
- 요약: TanStack Query memory cache, Local·Session Storage, IndexedDB 영속화 경계, 탭 간 무효화의 소유권과 프로토콜, 복구 방법을 정한 설계다.
|
||||
- 현재 정본: `src/adapters/query-cache/`, `src/contracts/storage-keys.ts`, `docs/operations/client-cache-and-storage-recovery.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Client cache and browser storage platform
|
||||
|
||||
> **정본 안내 (non-authoritative for runtime capability decisions)**
|
||||
@@ -13,7 +22,7 @@
|
||||
- 범위: TanStack Query memory cache, Local/Session Storage, IndexedDB query
|
||||
persistence 경계, 탭 간 invalidation
|
||||
- 관련 결정:
|
||||
[VD-13 client cache scope와 persistence](./decisions/VD-13-client-cache-scope-and-persistence.md)
|
||||
[VD-13 client cache scope와 persistence](../adr/VD-13-client-cache-scope-and-persistence.md)
|
||||
- query persistence reference 상태: `DESIGNED_NOT_IMPLEMENTED`
|
||||
- query persistence product 상태: `NOT_SELECTED`
|
||||
|
||||
@@ -405,7 +414,7 @@ locking에 사용하지 않는다.
|
||||
|
||||
query key factory와 함께 immutable scope/persistence profile을 등록한다.
|
||||
freshness, GC, refetch, retry, result budget, pagination과 conditional policy는
|
||||
[VD-25](./decisions/VD-25-server-state-cache-lifecycle.md)의
|
||||
[VD-25](../adr/VD-25-server-state-cache-lifecycle.md)의
|
||||
`ServerStateProfile`이 유일하게 소유한다.
|
||||
|
||||
```ts
|
||||
@@ -1682,14 +1691,14 @@ gate를 자동 충족하지 않는다.
|
||||
|
||||
## 21. 관련 자료
|
||||
|
||||
- [API contract, Schema, Mapper와 Server State](./api-contract-schema-mapper-and-server-state.md)
|
||||
- [VD-25 Server State Cache lifecycle](./decisions/VD-25-server-state-cache-lifecycle.md)
|
||||
- [Browser data capability completion ledger](./browser-data-capability-completion-ledger.md)
|
||||
- [TypeScript, 상태 소유권, 데이터 흐름](./typescript-state-and-data-flow.md)
|
||||
- [Frontend ports, adapters and boundaries](./frontend-ports-adapters-and-boundaries.md)
|
||||
- [Browser file and origin-storage platform](./browser-file-and-origin-storage.md)
|
||||
- [VD-11 browser file and origin-storage 경계](./decisions/VD-11-browser-file-and-origin-storage.md)
|
||||
- [VD-13 client cache scope와 persistence](./decisions/VD-13-client-cache-scope-and-persistence.md)
|
||||
- [API contract, Schema, Mapper와 Server State](./2026-07-28-api-contract-schema-mapper-and-server-state-design.md)
|
||||
- [VD-25 Server State Cache lifecycle](../adr/VD-25-server-state-cache-lifecycle.md)
|
||||
- [Browser data capability completion ledger](./2026-07-30-browser-data-capability-completion-ledger-design.md)
|
||||
- [TypeScript, 상태 소유권, 데이터 흐름](./2026-07-26-typescript-state-and-data-flow-design.md)
|
||||
- [Frontend ports, adapters and boundaries](./2026-07-26-frontend-ports-adapters-and-boundaries-design.md)
|
||||
- [Browser file and origin-storage platform](./2026-07-27-browser-file-and-origin-storage-design.md)
|
||||
- [VD-11 browser file and origin-storage 경계](../adr/VD-11-browser-file-and-origin-storage.md)
|
||||
- [VD-13 client cache scope와 persistence](../adr/VD-13-client-cache-scope-and-persistence.md)
|
||||
- [Client cache and Web Storage recovery](../operations/client-cache-and-storage-recovery.md)
|
||||
- [TanStack Query important defaults](https://tanstack.com/query/latest/docs/framework/react/guides/important-defaults)
|
||||
- [TanStack Query persistence](https://tanstack.com/query/v5/docs/framework/react/plugins/persistQueryClient)
|
||||
+16
-7
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-07-28
|
||||
- 요약: gRPC-Web·Connect-Web·Protobuf 계약과 codegen·REST gateway의 브라우저 쪽 설계로, provider 중립 Browser RPC V3 공통 runtime까지만 두고 vendor 선택은 미룬 설계다.
|
||||
- 현재 정본: `src/adapters/browser-rpc/`, `src/contracts/browser-rpc.ts`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Protobuf browser transport와 REST Gateway
|
||||
|
||||
- 상태: production design accepted, product/provider selection pending
|
||||
@@ -8,14 +17,14 @@
|
||||
unary/server-stream lifecycle runtime은 `AVAILABLE_NOT_COMPOSED`;
|
||||
vendor runtime/dependency/proto/descriptor/proxy는 없음
|
||||
- 관련 결정:
|
||||
- [VD-23 API transport selection과 REST execution](./decisions/VD-23-api-transport-selection-and-rest-execution.md)
|
||||
- [VD-24 Runtime schema와 boundary mapper](./decisions/VD-24-runtime-schema-and-boundary-mapper.md)
|
||||
- [VD-25 Server state cache lifecycle](./decisions/VD-25-server-state-cache-lifecycle.md)
|
||||
- [VD-27 gRPC-Web unary와 server stream](./decisions/VD-27-grpc-web-unary-and-server-stream.md)
|
||||
- [VD-29 Connect-Web와 browser Protobuf runtime](./decisions/VD-29-connect-web-and-browser-protobuf-runtime.md)
|
||||
- [VD-30 Protobuf contract와 REST Gateway](./decisions/VD-30-protobuf-contract-and-rest-gateway.md)
|
||||
- [VD-23 API transport selection과 REST execution](../adr/VD-23-api-transport-selection-and-rest-execution.md)
|
||||
- [VD-24 Runtime schema와 boundary mapper](../adr/VD-24-runtime-schema-and-boundary-mapper.md)
|
||||
- [VD-25 Server state cache lifecycle](../adr/VD-25-server-state-cache-lifecycle.md)
|
||||
- [VD-27 gRPC-Web unary와 server stream](../adr/VD-27-grpc-web-unary-and-server-stream.md)
|
||||
- [VD-29 Connect-Web와 browser Protobuf runtime](../adr/VD-29-connect-web-and-browser-protobuf-runtime.md)
|
||||
- [VD-30 Protobuf contract와 REST Gateway](../adr/VD-30-protobuf-contract-and-rest-gateway.md)
|
||||
- backend handoff:
|
||||
[Backend API와 Server State contract](./backend-api-and-server-state-contract.md)
|
||||
[Backend API와 Server State contract](../architecture/backend-api-and-server-state-contract.md)
|
||||
- 운영 절차:
|
||||
[API contract와 server-state recovery](../operations/api-contract-and-server-state-recovery.md)
|
||||
|
||||
+10
-1
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-07-28
|
||||
- 요약: 프론트의 파일 capability에 맞춰 제품 backend가 만들 object storage·multipart·서명 capability 같은 서버 쪽 기반을 정한 인계 설계다.
|
||||
- 현재 정본: `docs/manual/02-decision-tables.md`, `src/adapters/http/fileserver-upload.ts`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Server file capability infrastructure handoff
|
||||
|
||||
- 상태: 설계 완료. 짝 백엔드 템플릿은 구현하지 않음(2026-09-25 제거)
|
||||
@@ -26,7 +35,7 @@ runtime composition을 설치하지 않는다.
|
||||
|
||||
브라우저 쪽 capability envelope, bounded fetch, resume checkpoint와 Image CDN
|
||||
descriptor 계약은
|
||||
[`presigned-transfer-and-image-cdn.md`](./presigned-transfer-and-image-cdn.md)와
|
||||
[`presigned-transfer-and-image-cdn.md`](./2026-07-30-presigned-transfer-and-image-cdn-design.md)와
|
||||
VD-12가 소유한다. Range resume/background 경계는 VD-14, top-level transfer
|
||||
composition과 Image descriptor provider는 VD-16이 소유한다. 이 문서의 server
|
||||
port를 그 frontend DTO에 직접 노출하지 않고, 제품 BFF/controller가 두 경계
|
||||
+19
-10
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-07-30
|
||||
- 요약: 파일·저장소·cache·전송·Image CDN 같은 브라우저 데이터 capability의 현재·목표 상태와 남은 일, 승격 조건을 한곳에 모은 상태 대장이다.
|
||||
- 현재 정본: `config/recipes/frontend-capability-recipes.json`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Browser data capability completion ledger
|
||||
|
||||
## 1. 목적
|
||||
@@ -370,16 +379,16 @@ seekable/staging 정책, WP-04와 WP-05의 lifecycle/config 계약은 설계 단
|
||||
|
||||
## 11. 상세 문서
|
||||
|
||||
- [Browser file and origin storage](./browser-file-and-origin-storage.md)
|
||||
- [Client cache and storage](./client-cache-and-storage.md)
|
||||
- [Presigned transfer and Image CDN](./presigned-transfer-and-image-cdn.md)
|
||||
- [Server file capability infrastructure](./server-file-capability-infrastructure.md)
|
||||
- [VD-11 Browser file and origin-storage](./decisions/VD-11-browser-file-and-origin-storage.md)
|
||||
- [VD-12 Presigned transfer and Image CDN](./decisions/VD-12-presigned-transfer-and-image-cdn.md)
|
||||
- [VD-13 Client cache scope and persistence](./decisions/VD-13-client-cache-scope-and-persistence.md)
|
||||
- [VD-14 Resumable download and background download](./decisions/VD-14-resumable-download-and-background-transfer.md)
|
||||
- [VD-15 Origin storage lifecycle and migration](./decisions/VD-15-origin-storage-lifecycle-and-migration.md)
|
||||
- [VD-16 Browser transfer composition and image delivery](./decisions/VD-16-browser-transfer-composition-and-image-delivery.md)
|
||||
- [Browser file and origin storage](./2026-07-27-browser-file-and-origin-storage-design.md)
|
||||
- [Client cache and storage](./2026-07-28-client-cache-and-storage-design.md)
|
||||
- [Presigned transfer and Image CDN](./2026-07-30-presigned-transfer-and-image-cdn-design.md)
|
||||
- [Server file capability infrastructure](./2026-07-28-server-file-capability-infrastructure-design.md)
|
||||
- [VD-11 Browser file and origin-storage](../adr/VD-11-browser-file-and-origin-storage.md)
|
||||
- [VD-12 Presigned transfer and Image CDN](../adr/VD-12-presigned-transfer-and-image-cdn.md)
|
||||
- [VD-13 Client cache scope and persistence](../adr/VD-13-client-cache-scope-and-persistence.md)
|
||||
- [VD-14 Resumable download and background download](../adr/VD-14-resumable-download-and-background-transfer.md)
|
||||
- [VD-15 Origin storage lifecycle and migration](../adr/VD-15-origin-storage-lifecycle-and-migration.md)
|
||||
- [VD-16 Browser transfer composition and image delivery](../adr/VD-16-browser-transfer-composition-and-image-delivery.md)
|
||||
- [Browser file/storage recovery](../operations/browser-file-storage-recovery.md)
|
||||
- [Client cache/storage recovery](../operations/client-cache-and-storage-recovery.md)
|
||||
- [Browser transfer recovery](../operations/browser-transfer-recovery.md)
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-07-30
|
||||
- 요약: Runtime Config·boot, HTTP client, Router, Query·Mutation, realtime, Worker, Service Worker, offline command의 구현 결정을 닫은 상세 설계로, 다른 설계서가 런타임 결정의 정본으로 가리키던 문서다.
|
||||
- 현재 정본: `docs/architecture/frontend-application-foundation.md`, `src/bootstrap/`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# 프론트엔드 런타임 Capability 저장소 정합형 구현 결정 폐쇄 상세 설계
|
||||
|
||||
- 작성일: 2026-07-30
|
||||
+16
-7
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-07-30
|
||||
- 요약: presigned URL, multipart·재개 업로드, 스트리밍 다운로드, Image CDN의 제어·데이터 경로 경계와 무결성·만료·복구 계약을 정한 설계다.
|
||||
- 현재 정본: `src/adapters/browser-transfer/`, `docs/operations/browser-transfer-recovery.md`, `docs/manual/02-decision-tables.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Presigned transfer, resumable upload, streaming download and Image CDN
|
||||
|
||||
이 문서는 presigned URL, multipart/resumable upload, streaming download와
|
||||
@@ -19,7 +28,7 @@ authorization owner는 아직 조합하지 않는다. 이 개별 runtime은
|
||||
> `src/adapters/http/fileserver-upload.ts`의 `createFileserverUploadClient`(`POST /v1/files`)이고,
|
||||
> 재개가 없다(`docs/manual/02-decision-tables.md` 「파일 업로드」). 이 문서의 경로는 제품
|
||||
> backend가 같은 BFF 계약을 직접 만들 때 쓴다
|
||||
> ([`server-file-capability-infrastructure.md`](./server-file-capability-infrastructure.md)).
|
||||
> ([`server-file-capability-infrastructure.md`](./2026-07-28-server-file-capability-infrastructure-design.md)).
|
||||
> presigned 다운로드와 private Image CDN descriptor 발급 서버도 같은 이유로 짝 백엔드에 없다.
|
||||
|
||||
## 0. 현재 구현과 목표 상태
|
||||
@@ -46,10 +55,10 @@ admission은 이 status와 별도 축이다.
|
||||
`남은 목표`가 구현됐다는 뜻은 아니다. 특히 foreground whole-object streaming
|
||||
증거를 Range resume나 app-managed background download 증거로 재사용하지 않는다.
|
||||
Range와 background download의 상세 상태 머신, destination, fallback, rollout과 완료 기준은
|
||||
[VD-14](./decisions/VD-14-resumable-download-and-background-transfer.md)가
|
||||
[VD-14](../adr/VD-14-resumable-download-and-background-transfer.md)가
|
||||
소유한다. top-level runtime composition, account teardown, Image descriptor
|
||||
provider/refresh와 safe presentation projection은
|
||||
[VD-16](./decisions/VD-16-browser-transfer-composition-and-image-delivery.md)이
|
||||
[VD-16](../adr/VD-16-browser-transfer-composition-and-image-delivery.md)이
|
||||
소유한다.
|
||||
|
||||
## 1. 경계와 topology
|
||||
@@ -526,7 +535,7 @@ partial bytes를 기존 파일 뒤에 append하지 않는다.
|
||||
- system picker 미지원 환경의 browser-managed handoff/server-generation fallback
|
||||
|
||||
상세 불변조건과 promotion gate는
|
||||
[VD-14](./decisions/VD-14-resumable-download-and-background-transfer.md)를 따른다.
|
||||
[VD-14](../adr/VD-14-resumable-download-and-background-transfer.md)를 따른다.
|
||||
Range의 primary current status는 `DESIGNED_NOT_IMPLEMENTED`다.
|
||||
|
||||
### 5.1 아직 구현되지 않은 strategy selector
|
||||
@@ -889,12 +898,12 @@ promotion을 막는다. fake나 emulator success를 actual provider evidence로
|
||||
|
||||
## 9. 표준·vendor 참고
|
||||
|
||||
- [Browser data capability completion ledger](./browser-data-capability-completion-ledger.md)
|
||||
- [Browser data capability completion ledger](./2026-07-30-browser-data-capability-completion-ledger-design.md)
|
||||
- [Fetch Standard](https://fetch.spec.whatwg.org/)
|
||||
- [RFC 9110 HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110.html)
|
||||
- [File System Standard](https://fs.spec.whatwg.org/)
|
||||
- [VD-14 resumable download와 background download](./decisions/VD-14-resumable-download-and-background-transfer.md)
|
||||
- [VD-16 browser transfer composition과 image delivery](./decisions/VD-16-browser-transfer-composition-and-image-delivery.md)
|
||||
- [VD-14 resumable download와 background download](../adr/VD-14-resumable-download-and-background-transfer.md)
|
||||
- [VD-16 browser transfer composition과 image delivery](../adr/VD-16-browser-transfer-composition-and-image-delivery.md)
|
||||
- [HTML responsive images](https://html.spec.whatwg.org/multipage/images.html)
|
||||
- [tus resumable upload protocol](https://tus.io/protocols/resumable-upload)
|
||||
- [Amazon S3 presigned URLs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html)
|
||||
+22
-13
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-07-30
|
||||
- 요약: SSE·WebSocket·Web Push·제한된 Polling을 도입할 때의 선택 기준, 포트 경계, 이벤트 계약, 재연결·복구와 승격 조건을 정한 설계다.
|
||||
- 현재 정본: `src/adapters/realtime/`, `src/adapters/web-push/`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Realtime events, Web Push, and bounded polling
|
||||
|
||||
> **정본 안내 (non-authoritative for runtime capability decisions)**
|
||||
@@ -26,12 +35,12 @@ composition은 선택하지 않았다. 따라서 reference source가 있다는
|
||||
capability가 설치됐거나 production-ready라는 뜻이 아니다.
|
||||
|
||||
상세 결정은
|
||||
[VD-28](./decisions/VD-28-realtime-events-web-push-and-bounded-polling.md)이
|
||||
[VD-28](../adr/VD-28-realtime-events-web-push-and-bounded-polling.md)이
|
||||
소유한다. 공통 cache와 account scope는
|
||||
[Client cache and browser storage platform](./client-cache-and-storage.md),
|
||||
[Client cache and browser storage platform](./2026-07-28-client-cache-and-storage-design.md),
|
||||
선택 capability의 설치·제거 절차는
|
||||
[Optional frontend adapter recipes](./optional-adapter-recipes.md), 계층 방향은
|
||||
[Frontend ports, adapters, and boundaries](./frontend-ports-adapters-and-boundaries.md)
|
||||
[Optional frontend adapter recipes](../architecture/optional-adapter-recipes.md), 계층 방향은
|
||||
[Frontend ports, adapters, and boundaries](./2026-07-26-frontend-ports-adapters-and-boundaries-design.md)
|
||||
를 따른다.
|
||||
|
||||
|
||||
@@ -339,7 +348,7 @@ measured freshness/interaction requirement
|
||||
|
||||
### 2.3 인접 server-stream protocol과의 경계
|
||||
|
||||
[API contract, Schema, Mapper와 Server State](./api-contract-schema-mapper-and-server-state.md)의
|
||||
[API contract, Schema, Mapper와 Server State](./2026-07-28-api-contract-schema-mapper-and-server-state-design.md)의
|
||||
Connect/gRPC-Web server stream과 향후 GraphQL subscription은 이 문서의 SSE/WebSocket과
|
||||
자동으로 같은 adapter가 아니다.
|
||||
|
||||
@@ -2551,14 +2560,14 @@ production traffic 승인.
|
||||
|
||||
저장소 내부:
|
||||
|
||||
- [VD-28](./decisions/VD-28-realtime-events-web-push-and-bounded-polling.md)
|
||||
- [VD-10 optional capability recipes](./decisions/VD-10-optional-capability-recipes.md)
|
||||
- [Frontend ports, adapters, and boundaries](./frontend-ports-adapters-and-boundaries.md)
|
||||
- [Optional frontend adapter recipes](./optional-adapter-recipes.md)
|
||||
- [Client cache and browser storage](./client-cache-and-storage.md)
|
||||
- [API contract, Schema, Mapper와 Server State](./api-contract-schema-mapper-and-server-state.md)
|
||||
- [Browser file and origin-storage platform](./browser-file-and-origin-storage.md)
|
||||
- [TypeScript, state, and data flow](./typescript-state-and-data-flow.md)
|
||||
- [VD-28](../adr/VD-28-realtime-events-web-push-and-bounded-polling.md)
|
||||
- [VD-10 optional capability recipes](../adr/VD-10-optional-capability-recipes.md)
|
||||
- [Frontend ports, adapters, and boundaries](./2026-07-26-frontend-ports-adapters-and-boundaries-design.md)
|
||||
- [Optional frontend adapter recipes](../architecture/optional-adapter-recipes.md)
|
||||
- [Client cache and browser storage](./2026-07-28-client-cache-and-storage-design.md)
|
||||
- [API contract, Schema, Mapper와 Server State](./2026-07-28-api-contract-schema-mapper-and-server-state-design.md)
|
||||
- [Browser file and origin-storage platform](./2026-07-27-browser-file-and-origin-storage-design.md)
|
||||
- [TypeScript, state, and data flow](./2026-07-26-typescript-state-and-data-flow-design.md)
|
||||
- [`RealtimePort` copyable recipe](../../recipes/frontend-capabilities/contracts.ts)
|
||||
- [Deterministic realtime fake](../../recipes/frontend-capabilities/fake-adapters.ts)
|
||||
- [Optional capability contract test](../../tests/recipes/optional-capability-contracts.test.ts)
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-07-31
|
||||
- 요약: 설치된 route·계약·런타임 능력을 레지스트리에서만 파생해 보여 주는 플랫폼 구성 화면(`/examples/platform`)을 더하는 설계다.
|
||||
- 현재 정본: `src/presentation/examples/platform-overview-page.tsx`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# 플랫폼 구성 화면 (`EXAMPLES_PLATFORM`) 설계
|
||||
|
||||
작성일: 2026-07-31
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-08-01
|
||||
- 요약: 런타임 정합성 작업을 마무리하고 저장소 전체 리뷰에서 나온 query 무효화·mutation intent·release 증거·게이트 결함을 단계별로 고치는 수정 설계다.
|
||||
- 현재 정본: `src/contracts/query-invalidation.ts`, `src/contracts/mutation-intent.ts`, `docs/security/supply-chain.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Refactoring Review Remediation Design
|
||||
|
||||
## Purpose
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-08-01
|
||||
- 요약: release 산출물과 boot 프로토콜에서 실패를 통과시키던 경로를 먼저 막고, 런타임 소유권을 드러낸 뒤 도구와 큰 adapter를 정리하는 단계별 리팩터링 설계다.
|
||||
- 현재 정본: `scripts/contracts/release-artifacts.ts`, `src/bootstrap/`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Runtime Integrity Refactor Design
|
||||
|
||||
## Purpose
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-08-02
|
||||
- 요약: 테스트 보증과 CI/CD 실행을 `test-assurance-platform`과 `cicd-platform`으로 옮기고 이 repo에는 제품 코드와 제품 테스트만 남기는 설계다.
|
||||
- 현재 정본: `docs/operations/ci-quality-gates.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Platform-owned Frontend Assurance and Delivery Design
|
||||
|
||||
## Purpose
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-08-02
|
||||
- 요약: provider 증거 파일의 생성부터 봉인·게시까지를 guardian 프로세스 하나가 맡아, 중간에 죽어도 정본 증거가 남지 않고 바로 다시 시도할 수 있게 하는 설계다.
|
||||
- 현재 정본: `scripts/lib/provider-raw-guardian.ts`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Provider Evidence Guardian Transaction Design
|
||||
|
||||
## Goal
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-08-02
|
||||
- 요약: risk-coverage 산출물 schema를 정책과 따로 version 3으로 올리고, 설치된 Vitest·V8이 내는 counter 유무 분류를 고정하는 계약 설계다.
|
||||
- 현재 정본: `scripts/check-v8-coverage-counter-semantics.ts`, `scripts/check-risk-coverage.ts`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# V8 Coverage Counter Contract Design
|
||||
|
||||
## Goal
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-09-16
|
||||
- 요약: 어댑터 그룹의 `index.ts` 배럴을 실제 공개 경계로 만들고 그룹 밖은 배럴만 import하게 게이트로 강제하는 설계다.
|
||||
- 현재 정본: `docs/architecture/layers.md`, `.dependency-cruiser.json`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# 어댑터 배럴(`index.ts`)을 공개 경계로 승격 — 설계서
|
||||
|
||||
- 대상 레포: `/home/donghyeon/workspace/desktop-server-git/clean-architecture-frontend-template`
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-09-16
|
||||
- 요약: 어댑터 4곳에 흩어진 IndexedDB 연결·트랜잭션 구현을 `src/adapters/platform/` 커널로 모으는 설계다.
|
||||
- 현재 정본: `src/adapters/platform/indexeddb-connection.ts`, `src/adapters/platform/indexeddb-transaction.ts`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# IndexedDB 커널 승격 — 구체 설계
|
||||
|
||||
> 대상 브랜치: `develop` (5434760)
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-09-20
|
||||
- 요약: `memento-frontend`를 이 템플릿에서 upstream 추적 방식으로 파생하는 절차와 그 전에 템플릿에서 고칠 것을 정한 설계다.
|
||||
- 현재 정본: `README.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# memento-frontend를 이 템플릿에서 파생시키기 — 설계서
|
||||
|
||||
- 작성일: 2026-09-20
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 계획서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-07-31
|
||||
- 요약: 플랫폼 구성 화면이 정적 선택뿐 아니라 런타임 해석 결과까지 보여 주고 진입 경로와 브라우저 회귀 시험을 갖추게 하는 구현 계획이다.
|
||||
- 현재 정본: `src/presentation/examples/platform-overview-page.tsx`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# 플랫폼 구성 화면 완성 구현 계획
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 계획서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-08-01
|
||||
- 요약: 중복된 HTTP 실행 경로를 없애고 Service Worker 활성화 상한과 신원 확인을 강화한 뒤 큰 브라우저 adapter를 나누는 구현 계획이다.
|
||||
- 현재 정본: `src/adapters/http/`, `src/adapters/service-worker/`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# HTTP Worker and Adapter Remediation Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 계획서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-08-01
|
||||
- 요약: coverage·시나리오·CI·아키텍처 게이트가 실제 운영 동작을 재고, 측정 대상이 비었거나 모자라면 실패하게 하는 구현 계획이다.
|
||||
- 현재 정본: `docs/operations/ci-quality-gates.md`, `scripts/check-architecture.ts`, `scripts/check-risk-coverage.ts`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Quality and Architecture Remediation Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 계획서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-08-01
|
||||
- 요약: 생성한 Release Manifest V2 산출물을 검증할 수 있게 하고, 브라우저가 V1/V1 또는 V2/V2 boot 프로토콜 짝만 받게 하는 구현 계획이다.
|
||||
- 현재 정본: `scripts/contracts/release-artifacts.ts`, `src/bootstrap/load-release-manifest.ts`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Release and Boot Integrity Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 계획서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-08-01
|
||||
- 요약: 불변 release bundle 하나를 만들고, 모든 산출물·provider 보고·schema·digest가 그 바이트를 가리킬 때만 승격을 통과시키는 구현 계획이다.
|
||||
- 현재 정본: `docs/security/supply-chain.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Release Evidence Remediation Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 계획서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-08-01
|
||||
- 요약: topic 무효화가 실제 bound query 전부에 닿게 하고, 논리적 mutation마다 고유한 intent와 결과를 반영한 낙관적 상태를 지키게 하는 구현 계획이다.
|
||||
- 현재 정본: `src/contracts/query-keys.ts`, `src/contracts/mutation-intent.ts`, `src/presentation/adapters/query/`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Runtime Correctness Remediation Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 계획서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-08-01
|
||||
- 요약: 인증 scope가 바뀐 뒤 이전 계정의 query와 낙관적 상태가 화면에 남거나 다시 쓰이지 않게 하는 구현 계획이다.
|
||||
- 현재 정본: `src/bootstrap/server-state-generation-store.ts`, `src/presentation/adapters/query/server-state-scope-provider.tsx`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Scope-Owned Server State Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 계획서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-08-02
|
||||
- 요약: `cicd-platform`이 프론트 workflow 조정, 후보 생성, 공급망 증거, 불변 게시와 정확한 후보 승격을 혼자 맡게 하는 그 repo의 구현 계획이다.
|
||||
- 현재 정본: `docs/operations/ci-quality-gates.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# CI/CD Frontend Assurance and Delivery Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 계획서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 끝남
|
||||
- 작성일: 2026-08-02
|
||||
- 요약: coverage 출처 이름과 정적 분류를 Vitest·V8이 실제로 내는 counter에 맞추는 구현 계획이다.
|
||||
- 현재 정본: `scripts/check-risk-coverage.ts`, `config/testing/risk-coverage.json`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Counter-bearing Coverage Provenance Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 계획서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-08-02
|
||||
- 요약: 이 템플릿을 `test-assurance-platform`과 `cicd-platform`의 얇은 소비자로 바꾸면서 제품 소스·테스트·fixture를 그대로 두는 이행 계획이다.
|
||||
- 현재 정본: `docs/operations/ci-quality-gates.md`, `docs/testing/taxonomy.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Frontend Thin Platform Consumer Migration Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. Use `superpowers:using-git-worktrees` before editing.
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 계획서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-08-02
|
||||
- 요약: 보안 리뷰에서 나온 증거·수명 주기·staging·출력·신선도·workflow 결함을 닫고, 캡처한 후보 archive와 다섯 파일 bundle 검증기만 승격 근거로 삼게 하는 수정 계획이다.
|
||||
- 현재 정본: `docs/security/supply-chain.md`, `scripts/lib/promotion-stager.ts`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Promotion Security Review Fixes Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 계획서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-08-02
|
||||
- 요약: guardian이 시작할 때 정리 권한을 spawn 전에 할당한 파일 신원에서만 얻게 하면서, 덮어쓰지 않는 게시와 즉시 재시도를 지키는 구현 계획이다.
|
||||
- 현재 정본: `scripts/lib/provider-raw-guardian.ts`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Provider Evidence Guardian Transaction Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 계획서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-08-02
|
||||
- 요약: 캡처한 불변 후보를 무작위 비공개 staging 폴더 하나에 다섯 파일과 v3 검증 기록으로 마무리하는 구현 계획이다.
|
||||
- 현재 정본: `scripts/lib/promotion-stager.ts`, `scripts/lib/stage-verified-promotion-cli.ts`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Security Finalizer Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 계획서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-08-02
|
||||
- 요약: `test-assurance-platform`이 프론트 제품 suite의 선택·계획·실행·정규화·증거·판정을 모두 맡도록 넓히는 그 repo의 구현 계획이다.
|
||||
- 현재 정본: `docs/testing/taxonomy.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Test Assurance Frontend Capability Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 계획서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 끝남
|
||||
- 작성일: 2026-08-02
|
||||
- 요약: risk-coverage 산출물 schema version 3을 내고, 설치된 Vitest·V8의 counter 분류를 격리된 자식 실행에서 계속 검증하게 하는 구현 계획이다.
|
||||
- 현재 정본: `scripts/check-v8-coverage-counter-semantics.ts`, `scripts/check-risk-coverage.ts`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# V8 Coverage Counter Contract Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 계획서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-08-13
|
||||
- 요약: 확인된 adapter 정확성·수명 주기 결함을 모두 닫고 version 호환을 지킨 뒤에야 상태 기계 분리나 선택 capability 승격을 하는 수정 계획이다.
|
||||
- 현재 정본: `docs/operations/adapter-remediation-ledger.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Adapter Correctness and Refactoring Remediation Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
+10
-1
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 계획서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 끝남
|
||||
- 작성일: 2026-09-16
|
||||
- 요약: 어댑터 16개 그룹 모두에 `index.ts` 공개 경계를 세우고 그룹 밖은 배럴만 import하게 게이트로 강제하는 구현 계획이다.
|
||||
- 현재 정본: `docs/architecture/layers.md`, `.dependency-cruiser.json`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# 어댑터 배럴 공개 경계 확립 Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
@@ -8,7 +17,7 @@
|
||||
|
||||
**Tech Stack:** TypeScript (NodeNext/Bundler), dependency-cruiser, 자체 TypeScript 인지 import 그래프(`scripts/check-architecture.ts`), Vite, Vitest
|
||||
|
||||
**Spec:** [`docs/superpowers/specs/2026-09-16-adapter-barrel-boundary-design.md`](../specs/2026-09-16-adapter-barrel-boundary-design.md)
|
||||
**Spec:** [`docs/superpowers/specs/2026-09-16-adapter-barrel-boundary-design.md`](../../design/2026-09-16-adapter-barrel-boundary-design.md)
|
||||
|
||||
## Global Constraints
|
||||
|
||||
+10
-1
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 계획서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 끝남
|
||||
- 작성일: 2026-09-16
|
||||
- 요약: 어댑터 4곳의 IndexedDB 연결·트랜잭션 구현을 `src/adapters/platform/` 커널 두 파일로 모아 서로 다르던 동작을 하나로 맞추는 구현 계획이다.
|
||||
- 현재 정본: `src/adapters/platform/indexeddb-connection.ts`, `src/adapters/platform/indexeddb-transaction.ts`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# IndexedDB 커널 승격 Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
@@ -8,7 +17,7 @@
|
||||
|
||||
**Tech Stack:** TypeScript, IndexedDB, Vitest, `tests/helpers/memory-indexeddb.ts`(가짜 IDB)
|
||||
|
||||
**Spec:** [`docs/superpowers/specs/2026-09-16-indexeddb-kernel-promotion-design.md`](../specs/2026-09-16-indexeddb-kernel-promotion-design.md)
|
||||
**Spec:** [`docs/superpowers/specs/2026-09-16-indexeddb-kernel-promotion-design.md`](../../design/2026-09-16-indexeddb-kernel-promotion-design.md)
|
||||
|
||||
## Global Constraints
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 계획서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 끝남
|
||||
- 작성일: 2026-09-25
|
||||
- 요약: 2026-09-25 성숙도 리뷰 발견 138건을 고칠 때의 공통 완료 기준, 방향이 갈린 항목의 결정, repo 밖 사용자 몫을 정한 명세이고, 라운드는 v0.2.0(2026-09-27)으로 끝났다.
|
||||
- 현재 정본: 없음 — 끝난 라운드의 계획이다. 이 라운드가 바꾼 것은 `CHANGELOG.md` 0.2.0 절에 있다
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# SPEC: 성숙도 리뷰(2026-09-25) 전 항목 반영
|
||||
|
||||
## 목적
|
||||
@@ -124,7 +124,7 @@ corepack pnpm create:feature invoice-feature
|
||||
② **기준**
|
||||
|
||||
- 패키지가 아직 없으면 자리표시자로 시작한다. 3단계에서 실제 신원으로 바꾼다([02 결정표 2절](02-decision-tables.md#2-계약-출처)).
|
||||
- 손으로 만드는 길도 있다. `docs/architecture/starter-experience.md`의 "Adding a feature" 절이 그 순서다. 다만 전역 ID 접두어, 무작위 topic, a11y 기록을 직접 챙겨야 한다.
|
||||
- 손으로 만드는 길도 있다. `docs/architecture/starter-experience.md`의 "feature 추가" 절이 그 순서다. 다만 전역 ID 접두어, 무작위 topic, a11y 기록을 직접 챙겨야 한다.
|
||||
- 인자·파일·출력 전체는 [reference/create-feature.md](reference/create-feature.md)에 있다.
|
||||
|
||||
③ **잡는 검사 / 못 잡는 것**
|
||||
@@ -496,7 +496,7 @@ export function useInvoiceListFilters(): InvoiceListSearch {
|
||||
- 그 GET을 부르지 않는 페이지의 라우트(예: 상세 아래의 하위 항목 작성 폼 `/things/:thingId/parts/new`)는 상세 GET의 입력 스키마를 `paramsSchema`로 쓰지 않는다. 같은 스키마를 쓰면 report가 기록을 기대하는데 spec은 한 자원 응답을 보지 못해 기록을 남기지 않으므로 실패한다. 그 라우트에 자기 `paramsSchema`(예: `ThingPartCreateParams`)를 따로 둔다.
|
||||
- 설치된 GET이 아닌 요청을 그리기 전에 보내면 spec이 실패한다(`requests no installed list or single-resource read answers`).
|
||||
- spec은 h1이 보일 때까지 기다린다. 그래서 상세 페이지는 데이터가 없을 때도 h1을 그린다. 예: `heading={{ title: notice?.title ?? message("notice.detail.titlePending") }}`처럼 데이터가 없으면 고정 제목("공지")을 쓴다.
|
||||
- 기능이 앱 홈(`/`)을 대신하려면 route ID `APP_HOME`을 쓴다. `docs/architecture/starter-experience.md`의 "Product home and layouts" 절을 본다.
|
||||
- 기능이 앱 홈(`/`)을 대신하려면 route ID `APP_HOME`을 쓴다. `docs/architecture/starter-experience.md`의 "제품 홈과 레이아웃" 절을 본다.
|
||||
|
||||
③ **잡는 검사 / 못 잡는 것**
|
||||
|
||||
@@ -814,4 +814,4 @@ corepack pnpm test:sample-removal -- --feature=invoice-feature
|
||||
- 브라우저 테스트(`playwright test`)를 한 checkout에서 둘 이상 동시에 돌릴 때는 실행마다 다른 `TEST_RUN_ID`를 준다. 예: `TEST_RUN_ID=a corepack pnpm exec playwright test`. 그 실행의 빌드·결과·report는 `.tmp/runs/<id>/` 아래에 생긴다.
|
||||
- 서버 포트는 run ID가 없어도 빈 포트를 고른다. 같은 기계의 두 worktree도 부딪히지 않는다. 고정하려면 `TEST_E2E_PORT` 같은 포트 변수를 준다.
|
||||
- `ci:gate`에는 `TEST_RUN_ID`를 주지 않는다. 주면 증거가 기본 경로에 생기지 않아 게이트가 `command-generated evidence was not freshly produced`로 실패한다.
|
||||
- 변수 표와 한계는 [테스트 전략 13.6절](../testing/frontend-platform-testing-strategy.md)에 있다(1105/12-04).
|
||||
- 변수 표와 한계는 [테스트 전략 13.6절](../design/2026-07-26-frontend-platform-testing-strategy-design.md)에 있다(1105/12-04).
|
||||
|
||||
@@ -425,7 +425,7 @@ export function mapInvoiceCreateProblem(
|
||||
|
||||
- 짝 백엔드를 그대로 쓰면 Fileserver 한 번 업로드를 쓴다.
|
||||
- 큰 파일을 끊긴 데서 이어 올려야 하면 지금 템플릿에는 짝 경로가 없다. 짝 백엔드의 tus(`/v1/uploads`)를 부르는 프론트 client는 아직 없다.
|
||||
- presigned 레시피는 제품 backend가 그 BFF 계약(`docs/architecture/server-file-capability-infrastructure.md`)을 직접 만들 때만 쓴다.
|
||||
- presigned 레시피는 제품 backend가 그 BFF 계약(`docs/design/2026-07-28-server-file-capability-infrastructure-design.md`)을 직접 만들 때만 쓴다.
|
||||
|
||||
**결과 읽기**: `upload()`는 `Result<FileserverUploadedFile, AppFailure>`를 돌려준다.
|
||||
|
||||
|
||||
@@ -11,9 +11,9 @@
|
||||
└─ D. 고치지 않는다 → 중앙 카탈로그, governance, 공유 mock 등
|
||||
```
|
||||
|
||||
**정본 표**: 파일마다 "언제 고치나"와 "안 고치면 무엇이 실패하나"는 `docs/architecture/starter-experience.md`의 "Adding a feature" 절 표(`File | When | What fails without it`)가 정본이다. 이 문서는 그 표를 복사하지 않는다. 그 표에 없는 것만 더한다. 누가 하는지, 왜 폴더 밖인지, 사람이 하는 절차.
|
||||
**정본 표**: 파일마다 "언제 고치나"와 "안 고치면 무엇이 실패하나"는 `docs/architecture/starter-experience.md`의 "feature 추가" 절 표(`파일 | 언제 | 없으면 실패하는 것`)가 정본이다. 이 문서는 그 표를 복사하지 않는다. 그 표에 없는 것만 더한다. 누가 하는지, 왜 폴더 밖인지, 사람이 하는 절차.
|
||||
|
||||
링크: [starter-experience.md "Adding a feature"](../architecture/starter-experience.md#adding-a-feature)
|
||||
링크: [starter-experience.md "feature 추가"](../architecture/starter-experience.md#feature-추가)
|
||||
|
||||
---
|
||||
|
||||
@@ -96,7 +96,7 @@ create:feature가 pending 기록을 만든다
|
||||
- `@org-contracts/*` import는 이 파일에서만 된다(`external-contract-package-single-import-path`).
|
||||
5. 공개 대상으로 승인 검사를 돌린다.
|
||||
- `APP_PROFILE=staging`으로 빌드한 뒤 `APP_PROFILE=staging RELEASE_TARGET=staging corepack pnpm check:release-admission`(FE-GATE-027)을 돌린다.
|
||||
- 검사는 빌드 결과 `dist/config.json`을 읽는다. 빌드 변수는 루트 `README.md`의 "Runtime configuration" 절에 있다.
|
||||
- 검사는 빌드 결과 `dist/config.json`을 읽는다. 빌드 변수는 루트 `README.md`의 「런타임 설정과 배포 변수」 절에 있다.
|
||||
|
||||
안 하면: FE-GATE-027이 거절한다.
|
||||
|
||||
@@ -122,7 +122,7 @@ release admission refused for staging:
|
||||
- `label`은 `browser-files` 같은 소문자 kebab-case 토큰으로 쓴다. 다른 형식이면 조립이 `TypeError`로 멈춘다.
|
||||
- `close`가 던지면 scope가 `FAILED`에 머물고 모든 서버 요청이 `SCOPE_FENCED`로 막힌다. 진단 `cache.operation.failed`에 `reason: PARTICIPANT_FAILED`와 `scope_participant: <label>`이 남으니 그 기록으로 원인 closer를 찾는다.
|
||||
- 템플릿 파일 `src/bootstrap/runtime-adapters.ts`는 고치지 않는다.
|
||||
- 실시간 갱신: 짝 백엔드의 실시간 출구(STOMP·NDJSON)와 프론트 realtime 어댑터(SSE·`realtime.v1` WebSocket)는 그대로 연결되지 않는다. 지금 되는 경로는 bounded polling이다. 대응표: [realtime 설계 0.1절](../architecture/realtime-events-web-push-and-bounded-polling.md#01-짝-백엔드-템플릿과의-대응-110304-02).
|
||||
- 실시간 갱신: 짝 백엔드의 실시간 출구(STOMP·NDJSON)와 프론트 realtime 어댑터(SSE·`realtime.v1` WebSocket)는 그대로 연결되지 않는다. 지금 되는 경로는 bounded polling이다. 대응표: [realtime 설계 0.1절](../design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md#01-짝-백엔드-템플릿과의-대응-110304-02).
|
||||
- `src/contracts/product-contracts.ts`: 제품 인증 프로필이나 제품 런타임 설정 키가 필요할 때.
|
||||
- 템플릿 파일 `src/contracts/rest-profiles.ts`는 고치지 않는다.
|
||||
- 설정 키 이름에 `TOKEN`·`COOKIE`·`SECRET`·`PASSWORD` 같은 조각(`src/contracts/env.ts`의 `FORBIDDEN_CONFIG_NAME_FRAGMENTS`, 대소문자 무관)을 넣지 않는다. 부팅이 `CONFIG_SECRET_NAME_REJECTED`로 멈추고, 오류 화면의 "잘못된 설정 키"에 그 키 이름(값은 아님. 중첩 키는 `CAPABILITY_OVERRIDES.AUTH_TOKEN`처럼 경로)이 나온다. `test:unit`의 `env-registry-coverage`가 먼저 `Forbidden client configuration key: <키>`로 실패한다.
|
||||
|
||||
@@ -12,7 +12,7 @@
|
||||
- 기능을 만드는 AI 에이전트. 단계마다 "쓸 스킬"을 적었다.
|
||||
- 스킬: Claude Code가 부르는 작업 지침의 이름이다. 사람이 읽을 때는 건너뛰어도 된다.
|
||||
|
||||
전제: 루트 `README.md`의 "Start locally"대로 로컬에서 앱이 뜬다.
|
||||
전제: 루트 `README.md`의 「시작하기」대로 로컬에서 앱이 뜬다.
|
||||
|
||||
## 읽는 순서
|
||||
|
||||
@@ -65,16 +65,16 @@ README (이 문서)
|
||||
- 게이트: `config/ci/gates.json`
|
||||
- 백엔드 오류 code와 멱등성 응답: 백엔드 템플릿의 `clean-architecture-backend-template/docs/web/http-contract.md`
|
||||
- **다른 repo의 계약 표.** 백엔드 멱등성 응답 표는 위 파일 §2가 정본이다. 위치만 적는다.
|
||||
- **작업 이력.** `docs/reviews/`와 `docs/superpowers/`는 복사한 프로젝트가 지울 수 있다. 이 매뉴얼은 그 문서에 기대지 않는다.
|
||||
- **작업 이력.** `docs/reviews/`와 `docs/history/`는 복사한 프로젝트가 지울 수 있다. 이 매뉴얼은 그 문서에 기대지 않는다.
|
||||
|
||||
지금 구조가 아닌 설명은 링크하지 않는다.
|
||||
|
||||
- `docs/architecture/frontend-ports-adapters-and-boundaries.md`의 "7. 권장 목표 디렉터리 구조".
|
||||
- `docs/design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md`의 "7. 권장 목표 디렉터리 구조".
|
||||
- 목표안이다. 지금 기능 폴더 구조와 다르다.
|
||||
- 지금 구조는 `docs/architecture/layers.md`가 정본이다.
|
||||
- `docs/architecture/starter-experience.md`의 예전 "폴더 밖 수정" 4행 표와 "governance는 바뀌지 않는다" 문장(2026-11-01 리뷰 시점 판).
|
||||
- 그 판은 실제로 고쳐야 하는 파일을 다 적지 않았다.
|
||||
- 지금 판의 "Adding a feature" 절 표가 정본이다. 03 문서가 이 표를 링크한다.
|
||||
- 지금 판의 "feature 추가" 절 표가 정본이다. 03 문서가 이 표를 링크한다.
|
||||
- 템플릿이 예전에 두던 참조 샘플 기능과 예제 화면을 가리키는 문서와 리뷰 기록.
|
||||
- 그 샘플은 지웠다. 이 매뉴얼의 예시는 생성 명령 출력과 매뉴얼 안 코드 조각이다(`tests/unit/manual-code-blocks.test.ts`가 시험한다).
|
||||
|
||||
@@ -82,8 +82,7 @@ README (이 문서)
|
||||
|
||||
코드가 맞다. 이 매뉴얼은 주장이고, 근거는 코드·설정·실행 결과다.
|
||||
|
||||
`docs/README.md` §1에서 이 폴더를 링크하면 `verify:documentation`(FE-GATE-017)이 이 폴더 문서에 적힌 경로·명령·게이트 ID가 있는지 검사한다.
|
||||
폴더 링크는 그 폴더 바로 아래 `.md`만 검사한다. `reference/`도 검사하려면 따로 링크한다.
|
||||
`verify:documentation`(FE-GATE-017)이 이 폴더(`reference/` 포함)의 모든 문서에 적힌 경로·명령·게이트 ID가 있는지 검사한다(`docs/README.md` 「5. 문서 검사」).
|
||||
설명이 코드와 맞는지는 검사하지 않는다.
|
||||
|
||||
플랫폼 규칙(예산·실행·검증·텔레메트리)의 근거는 `docs/architecture/`의 `scale-architecture.md`에 있다. 이 매뉴얼은 `scale-architecture.md` §24처럼 절 번호로 가리킨다.
|
||||
|
||||
@@ -14,7 +14,7 @@
|
||||
|---|---|---|---|
|
||||
| 기능 모듈 등록 | `src/features/feature-module.ts` (`defineFeatureModule`, `defineFeatureRuntime`), 생성기 | 생성 뼈대 `feature-module.ts`, `feature-runtime.ts` | 생성기, 기능 ID와 계약 `featureId` 일치 |
|
||||
| context 소속 선언 | `src/contexts/bounded-context-module.ts` | 생성 뼈대 `src/contexts/<base>-context/context-module.ts`(새 context를 만들 때) | 생성기(없는 context, 예산), 앱 모듈(루트 밖 라우트) |
|
||||
| context 전용 레이아웃 | `docs/architecture/starter-experience.md` "Product home and layouts" | `tests/helpers/fixture-layout-product.tsx` (테스트 fixture) | `tests/component/context-layouts.test.tsx` |
|
||||
| context 전용 레이아웃 | `docs/architecture/starter-experience.md` "제품 홈과 레이아웃" | `tests/helpers/fixture-layout-product.tsx` (테스트 fixture) | `tests/component/context-layouts.test.tsx` |
|
||||
| 앱 홈 대신하기 | `src/contracts/routes.ts`의 `FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS` | 없음 (기능 예제) | 조립 (두 기능이 `APP_HOME`을 선언하면 실패) |
|
||||
| 조립 기여(`needs`) | `src/features/feature-adapter-contribution.ts` | 생성 뼈대 `adapters/create-<base>-feature-input.ts` | 조립 (없는 capability, 다른 기능의 input) |
|
||||
| 제품 capability | `src/features/product-capabilities.ts`(타입), `src/bootstrap/product-composition.ts`(값), `src/bootstrap/product-composition-contract.ts` | `recipes/frontend-capabilities/indexeddb-feature-capability.ts` | `check:types` |
|
||||
|
||||
@@ -1,63 +1,54 @@
|
||||
# Adapter Remediation Ledger
|
||||
# Adapter 수정 원장
|
||||
|
||||
> Source of truth for the execution state of every confirmed finding in
|
||||
> [`docs/reviews/adapters/`](../reviews/adapters/README.md).
|
||||
> [`docs/reviews/adapters/`](../reviews/adapters/README.md)에서 확인된 모든 발견(finding)의 실행 상태를 적는 정본이다.
|
||||
>
|
||||
> Plan: 2026-08-13 adapter remediation, a work-history plan under docs/superpowers/plans
|
||||
> that a copied project may delete (README, "Files you can delete after copying").
|
||||
> Baseline revision: `develop` / `4dc033cf33a5b6173bbf960d5eb464a406dc4c92`.
|
||||
> 계획: 2026-08-13 adapter 수정 계획. docs/history/plans 아래의 작업 이력 계획이고, 복사한 프로젝트는 지워도 된다(README 「복사한 뒤 지워도 되는 것」).
|
||||
> 기준 리비전: `develop` / `4dc033cf33a5b6173bbf960d5eb464a406dc4c92`.
|
||||
>
|
||||
> Test paths are given at their current location. Two suites moved after
|
||||
> these runs: `ci-artifact-contract.test.ts` from `tests/unit/` to
|
||||
> `tests/system/ci-runner/`, and `provider-guardian-transaction.test.ts` from
|
||||
> `tests/unit/` to `tests/integration/`. Three suites were split on
|
||||
> 2026-09-18 (`5cc41467`, `ec7f20e2`) and the third re-review rows follow the
|
||||
> tests that moved: TR-02 to `presigned-transfer-delivery.test.ts`, TR-03's
|
||||
> image probe to `image-cdn-browser-probe.test.ts`, TR-04 to
|
||||
> `resumable-upload-runtime-teardown.test.ts` (all in `tests/unit/`). The run
|
||||
> commands in the earlier sections keep the file each run used.
|
||||
> 테스트 경로는 지금 위치로 적는다. 이 실행들 뒤에 테스트 파일 두 개가 옮겨졌다.
|
||||
> `ci-artifact-contract.test.ts`는 `tests/unit/`에서 `tests/system/ci-runner/`로, `provider-guardian-transaction.test.ts`는 `tests/unit/`에서 `tests/integration/`로 옮겼다.
|
||||
> 2026-09-18(`5cc41467`, `ec7f20e2`)에 테스트 파일 세 개를 나눴고, 세 번째 재검토의 행은 옮겨 간 테스트를 따른다.
|
||||
> TR-02는 `presigned-transfer-delivery.test.ts`로, TR-03의 image probe는 `image-cdn-browser-probe.test.ts`로, TR-04는 `resumable-upload-runtime-teardown.test.ts`로 갔다(모두 `tests/unit/` 안).
|
||||
> 앞 절들의 실행 명령은 그 실행이 쓴 파일을 그대로 적는다.
|
||||
|
||||
## Containment state (plan Task 1, Step 1)
|
||||
## 격리 상태 (계획 Task 1, Step 1)
|
||||
|
||||
Scan performed on the baseline revision:
|
||||
기준 리비전에서 돌린 검색:
|
||||
|
||||
```bash
|
||||
rg -n "createBrowserOpfsRuntime|createBrowserFileRuntime|createPublicResponseCache|createBrowserRpcRuntime|createWebPush|createServiceWorker|createResumableUpload|createImageCdn" src recipes tests
|
||||
rg -n "AVAILABLE_NOT_COMPOSED|DESIGNED_NOT_IMPLEMENTED|NOT_SELECTED" docs/architecture src/bootstrap
|
||||
```
|
||||
|
||||
Result:
|
||||
결과:
|
||||
|
||||
| Capability | Template default composition | Containment action |
|
||||
| Capability | 템플릿 기본 조립 여부 | 격리(containment) 조치 |
|
||||
| --- | --- | --- |
|
||||
| OPFS byte store (`createBrowserOpfsRuntime`) | Not composed. Only `recipes/frontend-capabilities/*` reference the `"OPFS"` backend literal in contract/fake code. | None required. No V1 writer is admitted, so no kill switch is invented. |
|
||||
| Browser files runtime | Not composed in `src/bootstrap/**`. | None. |
|
||||
| Public response cache | Not composed; only `tests/unit/public-response-cache.test.ts` constructs it. | None. |
|
||||
| Browser RPC runtime | Not composed; `AVAILABLE_NOT_COMPOSED`. | None. |
|
||||
| Web Push | Not composed; `NOT_SELECTED` / `AVAILABLE_NOT_COMPOSED`. | None. |
|
||||
| Resumable upload / image CDN | Not composed; test-only construction. | None. |
|
||||
| Service Worker runtime host | Composed conditionally through `src/bootstrap/optional-runtime-host.ts` → `createServiceWorkerRuntimeHost`, gated by `ResolvedRuntimeCapabilities`. | Stays as-is. Task 14 fixes truthfulness without changing selection. |
|
||||
| Realtime | `src/bootstrap/optional-runtime-host.ts:91` keeps realtime `NOT_SELECTED` with `realtime: null`. | None. |
|
||||
| OPFS 바이트 저장소 (`createBrowserOpfsRuntime`) | 조립하지 않는다. `recipes/frontend-capabilities/*`만 contract/fake 코드에서 `"OPFS"` backend 리터럴을 참조한다. | 필요 없다. V1 writer를 받아들이지 않으므로 kill switch를 새로 만들지 않는다. |
|
||||
| 브라우저 파일 runtime | `src/bootstrap/**`에서 조립하지 않는다. | 없음. |
|
||||
| 공개 응답 캐시 | 조립하지 않는다. `tests/unit/public-response-cache.test.ts`만 이것을 만든다. | 없음. |
|
||||
| Browser RPC runtime | 조립하지 않는다. `AVAILABLE_NOT_COMPOSED`. | 없음. |
|
||||
| Web Push | 조립하지 않는다. `NOT_SELECTED` / `AVAILABLE_NOT_COMPOSED`. | 없음. |
|
||||
| 재개 가능 업로드(resumable upload) / image CDN | 조립하지 않는다. 테스트에서만 만든다. | 없음. |
|
||||
| Service Worker runtime host | `src/bootstrap/optional-runtime-host.ts` → `createServiceWorkerRuntimeHost`로 조건부 조립한다. `ResolvedRuntimeCapabilities`가 켜고 끈다. | 그대로 둔다. Task 14가 선택은 바꾸지 않고, 보고 값이 사실과 맞도록 고친다. |
|
||||
| Realtime | `src/bootstrap/optional-runtime-host.ts:91`이 realtime을 `realtime: null`로 두고 `NOT_SELECTED`로 유지한다. | 없음. |
|
||||
|
||||
No product-specific composition root outside the template default exists in this repository, so
|
||||
there is no OPFS V1 write admission to close.
|
||||
이 저장소에는 템플릿 기본 말고 제품 전용 composition root가 없다. 그래서 막아야 할 OPFS V1 쓰기 허용 경로도 없다.
|
||||
|
||||
## Baseline gates (plan Task 1, Step 3)
|
||||
## 기준 게이트 (계획 Task 1, Step 3)
|
||||
|
||||
Captured on the baseline revision before any source change.
|
||||
소스를 바꾸기 전에 기준 리비전에서 기록했다.
|
||||
|
||||
| Command | Exit code | Result |
|
||||
| 명령 | 종료 코드 | 결과 |
|
||||
| --- | ---: | --- |
|
||||
| `corepack pnpm check:types` | 0 | app, node, test, recipes, web-worker, service-worker projects all pass. |
|
||||
| `corepack pnpm lint` | 0 | `--max-warnings=0` clean. |
|
||||
| `corepack pnpm check:architecture` | 0 | 286 modules, 854 dependencies, all imports resolved; 12 graph fixtures PASS; TS-only policy PASS; allowed PASS / 9 forbidden rejected. |
|
||||
| `corepack pnpm test:unit` | 1 | 110 passed / 1 failed test files; 1496 passed / 19 failed tests (1515 total), 150.92s. |
|
||||
| `corepack pnpm check:types` | 0 | app, node, test, recipes, web-worker, service-worker 프로젝트가 모두 통과한다. |
|
||||
| `corepack pnpm lint` | 0 | `--max-warnings=0`로 경고 없음. |
|
||||
| `corepack pnpm check:architecture` | 0 | 모듈 286개, 의존 854개, import 해석 실패 없음. graph fixture 12개 PASS. TS-only 정책 PASS. 허용 PASS / 금지 9개 거부. |
|
||||
| `corepack pnpm test:unit` | 1 | 테스트 파일 110개 통과 / 1개 실패. 테스트 1496개 통과 / 19개 실패(전체 1515개), 150.92s. |
|
||||
|
||||
### `test:unit` failure attribution
|
||||
### `test:unit` 실패 원인
|
||||
|
||||
The single failing file is `tests/system/ci-runner/ci-artifact-contract.test.ts`. All 19 failures come from
|
||||
child-process, cgroup, and filesystem-permission behavior of the sandboxed execution
|
||||
environment, not from adapter code. Verbatim causes recorded from the run log:
|
||||
실패하는 파일은 `tests/system/ci-runner/ci-artifact-contract.test.ts` 하나다. 실패 19건은 모두 sandbox 실행 환경의 자식 프로세스, cgroup, 파일 시스템 권한 동작에서 나왔다. adapter 코드 탓이 아니다. 실행 로그에서 기록한 원인 원문:
|
||||
|
||||
```
|
||||
Error: ENOENT: no such file or directory, open '/proc/1325422/task/1325422/children'
|
||||
@@ -69,468 +60,398 @@ AssertionError: expected 5714 to be less than 5000
|
||||
AssertionError: expected [] to deeply equal ArrayContaining{…}
|
||||
```
|
||||
|
||||
This matches the environment note already recorded in the review index. It is **not** converted
|
||||
to an adapter failure and it is **not** treated as green. Every adapter task below must keep the
|
||||
adapter-focused suites green and must not increase this file's failure count.
|
||||
리뷰 색인에 이미 적힌 환경 메모와 같다. adapter 실패로 바꾸지 **않고**, 통과(green)로도 보지 **않는다**. 아래의 모든 adapter 작업은 adapter 중심 테스트 파일을 통과 상태로 유지해야 하고, 이 파일의 실패 수를 늘리면 안 된다.
|
||||
|
||||
## Finding ledger
|
||||
## 발견 원장
|
||||
|
||||
`Activation` records whether the finding is reachable on the current template execution path.
|
||||
Rollout state starts at `NOT_STARTED`; documented-unimplemented items start at
|
||||
`PROMOTION_BLOCKED` and are never labelled `DEFECT`.
|
||||
`Activation` 열은 그 발견이 지금 템플릿 실행 경로에서 닿는지(활성화 여부)를 적는다. Rollout 상태는 `NOT_STARTED`에서 시작한다. 문서에 미구현으로 적힌 항목은 `PROMOTION_BLOCKED`에서 시작하고, `DEFECT`로 표시하지 않는다.
|
||||
|
||||
### Network and state (`docs/reviews/adapters/01-network-and-state.md`)
|
||||
### 네트워크와 상태 (`docs/reviews/adapters/01-network-and-state.md`)
|
||||
|
||||
| ID | Activation | Red test command | Fix commit/PR | Rollout state | Rollback trigger | Evidence |
|
||||
| ID | Activation | 실패 테스트(red test) 명령 | 수정 커밋/PR | Rollout 상태 | Rollback 기준 | 증거 |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| N-01 | Live V3 path | `corepack pnpm exec vitest run tests/integration/http-execution-v3-observability.test.ts` | `fix: restore V3 HTTP observability` | `FIXED_NOT_RELEASED` | diagnostics/telemetry producer gate regression | Red 5/5 failed → green 5/5; `check:diagnostics` PASS (8 diagnostics, 5 telemetry producers); `check:types` PASS; `check:architecture` PASS |
|
||||
| N-02 | Live V3 path | `corepack pnpm exec vitest run tests/integration/http-execution-v3-auth-profile.test.ts` | `fix: enforce installed HTTP auth profiles` | `FIXED_NOT_RELEASED` | authenticated request 4xx spike after profile enforcement | Red suite failed to load (`installRestAuthProfileRegistry` absent) → green 7/7; `check:types` PASS; `check:architecture` PASS; `lint` PASS; unit+integration+features 1560 passed with only the pre-existing environmental `ci-artifact-contract` failures |
|
||||
| N-03 | Live V3 path | `corepack pnpm exec vitest run tests/unit/http-execution-v3.test.ts -t "retry-time fence"` | `fix: preserve command effect certainty across retries` | `FIXED_NOT_RELEASED` | command effect verdict regression | Red reproduced `SCOPE_FENCED` with `NOT_STARTED` after one dispatched attempt → green `MAYBE_APPLIED`; lattice table 9/9; `check:types` PASS; `lint` PASS |
|
||||
| N-04 | Live composition teardown | `corepack pnpm exec vitest run tests/unit/telemetry.test.ts tests/unit/runtime-adapters.test.ts` | `fix: terminate telemetry work on disposal` | `FIXED_NOT_RELEASED` | telemetry delivery loss after teardown change | Red 10 failed (5 lifecycle + 5 capacity) → green 34/34; `check:diagnostics` PASS; `check:types` PASS; `check:architecture` PASS; `lint` PASS |
|
||||
| N-05 | Rollout blocker (sidecar not composed) | `corepack pnpm exec vitest run tests/unit/conditional-validator-store.test.ts` | `fix: harden bounded state sidecars` | `FIXED_NOT_RELEASED` | persisted validator key incompatibility | Red collision case (two valid bindings sharing one delimiter-joined key) → green; key is now a bounded validated tuple encoded with `JSON.stringify` |
|
||||
| N-06 | Legacy V2 rollback seam | The V2 client test tests/integration/http-client.test.ts (deleted with the V2 client on 2026-11-03) | `fix: harden the legacy HTTP rollback path` | `FIXED_NOT_RELEASED` | legacy keyed command rejection spike | Red 4 invalid-key cases → green; rejection happens before credentials and fetch (0 credential calls, 0 fetches) |
|
||||
| N-07 | Legacy V2 rollback seam | The V2 client tests tests/integration/http-client.test.ts and tests/integration/auth-recovery.test.ts (deleted with the V2 client on 2026-11-03) | `fix: harden the legacy HTTP rollback path` | `FIXED_NOT_RELEASED` | legacy credential timeout regression | Red never-settling owner → green; credential wait races the existing attempt controller so no extra timer is added; ownership maps to REQUEST_TIMEOUT / REQUEST_ABORTED / AUTH_INTEGRATION_FAILURE with zero fetches |
|
||||
| N-08 | Legacy V2 rollback seam | The V2 bounded JSON test tests/unit/bounded-json-compatibility.test.ts (deleted with the V2 client on 2026-11-03) | `fix: harden the legacy HTTP rollback path` | `FIXED_NOT_RELEASED` | legacy JSON failure-code drift | Green 7/7 including throwing cancel/releaseLock; `readBoundedJson` now delegates to `bounded-body-reader` with the legacy codes preserved |
|
||||
| N-09 | Live cross-context host | `corepack pnpm exec vitest run tests/unit/cross-tab-invalidation.test.ts` | `fix: harden bounded state sidecars` | `FIXED_NOT_RELEASED` | cross-tab invalidation drop | Red foreign-area pulse accepted → green 13/13; localStorage captured once and `StorageEvent.storageArea` compared by object identity; pulse key registered as `CACHE_INVALIDATION_PULSE`; `check:registries` PASS |
|
||||
| N-10 | Cursor runtime `AVAILABLE_NOT_COMPOSED` | `corepack pnpm exec vitest run tests/unit/cursor-pagination-runtime.test.ts` | `fix: harden bounded state sidecars` | `FIXED_NOT_RELEASED` | pagination abort semantics change | Red never-settling loader → green `PAGINATION_ABORTED` with the late page ignored |
|
||||
| N-11 | Live composition | `corepack pnpm exec vitest run tests/unit/telemetry.test.ts -t capacity` | `fix: terminate telemetry work on disposal` | `FIXED_NOT_RELEASED` | capacity rejection on valid composition | Red 5/5 capacity cases → green; ceilings documented in VD-07 §7-4 |
|
||||
| N-01 | 실행 중인 V3 경로 | `corepack pnpm exec vitest run tests/integration/http-execution-v3-observability.test.ts` | `fix: restore V3 HTTP observability` | `FIXED_NOT_RELEASED` | diagnostics/telemetry producer 게이트 회귀 | 실패 5/5 → 통과 5/5. `check:diagnostics` PASS(diagnostic 8개, telemetry producer 5개). `check:types` PASS. `check:architecture` PASS |
|
||||
| N-02 | 실행 중인 V3 경로 | `corepack pnpm exec vitest run tests/integration/http-execution-v3-auth-profile.test.ts` | `fix: enforce installed HTTP auth profiles` | `FIXED_NOT_RELEASED` | profile 강제 뒤 인증 요청 4xx 급증 | 실패: 테스트 파일이 로드되지 않음(`installRestAuthProfileRegistry` 없음) → 통과 7/7. `check:types` PASS. `check:architecture` PASS. `lint` PASS. unit+integration+features 1560개 통과, 실패는 원래 있던 환경 탓 `ci-artifact-contract` 실패뿐 |
|
||||
| N-03 | 실행 중인 V3 경로 | `corepack pnpm exec vitest run tests/unit/http-execution-v3.test.ts -t "retry-time fence"` | `fix: preserve command effect certainty across retries` | `FIXED_NOT_RELEASED` | command effect 판정 회귀 | 실패: 시도 한 번을 보낸 뒤 `NOT_STARTED`와 함께 `SCOPE_FENCED`가 재현됨 → 통과 `MAYBE_APPLIED`. lattice 표 9/9. `check:types` PASS. `lint` PASS |
|
||||
| N-04 | 실행 중인 조립의 정리(teardown) | `corepack pnpm exec vitest run tests/unit/telemetry.test.ts tests/unit/runtime-adapters.test.ts` | `fix: terminate telemetry work on disposal` | `FIXED_NOT_RELEASED` | teardown 변경 뒤 telemetry 전달 유실 | 실패 10개(lifecycle 5 + capacity 5) → 통과 34/34. `check:diagnostics` PASS. `check:types` PASS. `check:architecture` PASS. `lint` PASS |
|
||||
| N-05 | Rollout 차단 요인(sidecar 조립 안 됨) | `corepack pnpm exec vitest run tests/unit/conditional-validator-store.test.ts` | `fix: harden bounded state sidecars` | `FIXED_NOT_RELEASED` | 저장된 validator 키 비호환 | 실패: 충돌 사례(올바른 binding 두 개가 구분자로 이은 키 하나를 공유) → 통과. 키는 이제 크기가 제한되고 검증된 tuple이며 `JSON.stringify`로 인코딩한다 |
|
||||
| N-06 | 구 V2 rollback 경계(seam) | V2 client 테스트 tests/integration/http-client.test.ts(2026-11-03에 V2 client와 함께 지웠다) | `fix: harden the legacy HTTP rollback path` | `FIXED_NOT_RELEASED` | 구 keyed command 거부 급증 | 실패: 잘못된 키 사례 4개 → 통과. credential과 fetch 전에 거부한다(credential 호출 0회, fetch 0회) |
|
||||
| N-07 | 구 V2 rollback 경계(seam) | V2 client 테스트 tests/integration/http-client.test.ts와 tests/integration/auth-recovery.test.ts(2026-11-03에 V2 client와 함께 지웠다) | `fix: harden the legacy HTTP rollback path` | `FIXED_NOT_RELEASED` | 구 credential timeout 회귀 | 실패: 끝나지 않는 owner → 통과. credential 대기가 기존 attempt controller와 경주(race)하므로 타이머를 더 만들지 않는다. 소유권은 fetch 0회로 REQUEST_TIMEOUT / REQUEST_ABORTED / AUTH_INTEGRATION_FAILURE에 대응한다 |
|
||||
| N-08 | 구 V2 rollback 경계(seam) | V2 bounded JSON 테스트 tests/unit/bounded-json-compatibility.test.ts(2026-11-03에 V2 client와 함께 지웠다) | `fix: harden the legacy HTTP rollback path` | `FIXED_NOT_RELEASED` | 구 JSON 실패 코드 drift | 통과 7/7(예외를 던지는 cancel/releaseLock 포함). `readBoundedJson`은 이제 구 코드를 그대로 두고 `bounded-body-reader`에 맡긴다 |
|
||||
| N-09 | 실행 중인 cross-context host | `corepack pnpm exec vitest run tests/unit/cross-tab-invalidation.test.ts` | `fix: harden bounded state sidecars` | `FIXED_NOT_RELEASED` | cross-tab 무효화 유실 | 실패: 다른 영역의 pulse를 받아들임 → 통과 13/13. localStorage를 한 번만 잡고 `StorageEvent.storageArea`를 객체 동일성으로 비교한다. pulse 키는 `CACHE_INVALIDATION_PULSE`로 등록했다. `check:registries` PASS |
|
||||
| N-10 | Cursor runtime `AVAILABLE_NOT_COMPOSED` | `corepack pnpm exec vitest run tests/unit/cursor-pagination-runtime.test.ts` | `fix: harden bounded state sidecars` | `FIXED_NOT_RELEASED` | pagination abort 의미 변경 | 실패: 끝나지 않는 loader → 통과 `PAGINATION_ABORTED`, 늦게 온 page는 무시 |
|
||||
| N-11 | 실행 중인 조립 | `corepack pnpm exec vitest run tests/unit/telemetry.test.ts -t capacity` | `fix: terminate telemetry work on disposal` | `FIXED_NOT_RELEASED` | 올바른 조립에서 capacity 거부 | 실패: capacity 사례 5/5 → 통과. 상한은 VD-07 §7-4에 적었다 |
|
||||
|
||||
### Storage and browser files (`docs/reviews/adapters/03-storage-and-browser-files.md`)
|
||||
### 스토리지와 브라우저 파일 (`docs/reviews/adapters/03-storage-and-browser-files.md`)
|
||||
|
||||
| ID | Activation | Red test command | Fix commit/PR | Rollout state | Rollback trigger | Evidence |
|
||||
| ID | Activation | 실패 테스트 명령 | 수정 커밋/PR | Rollout 상태 | Rollback 기준 | 증거 |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| STO-01 | OPFS not composed in template; **Critical** for any product writer | `corepack pnpm exec vitest run tests/unit/opfs-byte-store.test.ts tests/unit/opfs-worker-runtime.test.ts tests/unit/indexeddb-opfs-journal.test.ts` | `fix: preserve OPFS recovery authority during cleanup` | `FIXED_NOT_RELEASED` | OPFS reconcile backlog or journal growth | Red 4 new saga cases → green 25/25 across the three OPFS suites; `check:types` PASS (incl. web-worker); `check:browser-file-storage-boundaries` PASS; `lint` PASS; `test:unit` 1511 passed with only the pre-existing environmental `ci-artifact-contract` failures |
|
||||
| STO-02 | Browser file runtime not composed | `corepack pnpm exec vitest run tests/unit/browser-file-download.test.ts` | `fix: execute canonical browser download targets` | `FIXED_NOT_RELEASED` | download navigation blocked by canonical target | Red 2 failed (raw relative href handed to host) → green 17/17 |
|
||||
| STO-03 | Public cache not composed | `corepack pnpm exec vitest run tests/unit/public-response-cache.test.ts` | `fix: make public cache staging repairable` | `FIXED_NOT_RELEASED` | composition rejection of an existing policy | Red 4 cases across STO-03..05 → green 21/21; `check:types` PASS; `check:browser-file-storage-boundaries` PASS; `lint` PASS |
|
||||
| STO-04 | Public cache not composed | `corepack pnpm exec vitest run tests/unit/public-response-cache.test.ts` | `fix: make public cache staging repairable` | `FIXED_NOT_RELEASED` | restage loop or bandwidth spike | — |
|
||||
| STO-05 | Public cache not composed | `corepack pnpm exec vitest run tests/unit/public-response-cache.test.ts` | `fix: make public cache staging repairable` | `FIXED_NOT_RELEASED` | activation permitted without required capability | — |
|
||||
| STO-06 | IndexedDB maintenance | `corepack pnpm exec vitest run tests/unit/indexeddb-maintenance.test.ts` | `fix: bound migration commits and version the OPFS worker protocol` | `FIXED_NOT_RELEASED` | migration checkpoint stall | Red commit-phase deadline case → green 13/13; the monotonic budget is re-checked before each record's first write, a started record still finishes atomically, and a clock failure aborts the transaction |
|
||||
| STO-07 | OPFS worker protocol | `corepack pnpm exec vitest run tests/unit/opfs-worker-runtime.test.ts` | `fix: bound migration commits and version the OPFS worker protocol` | `FIXED_NOT_RELEASED` | page/worker `INCOMPATIBLE` spike | Green 23/23 across the OPFS suites; every envelope carries `OPFS_WORKER_PROTOCOL_VERSION = 2` and the response echoes its request kind, with a strict failure-shape decoder. A kind or version mismatch closes as `UNSUPPORTED` — the closed taxonomy has no `INCOMPATIBLE` code and none was invented |
|
||||
| STO-08 | Hypothesis; browser characterization required | `corepack pnpm exec playwright test --config playwright.capabilities.config.ts tests/browser-capabilities/browser-files.spec.ts` | none (source unchanged) | `UNVERIFIED` | n/a until characterized | chromium 2/2 PASS; webkit could not launch (`libevent-2.1-7t64`, `libavif16` missing — environmental). The existing spec does not exercise `Window.showOpenFilePicker`/`showSaveFilePicker`, which need a user gesture and a native dialog, so the receiver-binding hypothesis is **neither reproduced nor refuted**. No `SystemPickerHost` was introduced: the plan forbids implementing an uncharacterized hypothesis as a defect. |
|
||||
| GAP-01 | Documented unimplemented (VD-15) | promotion evidence, not a red test | — | `PROMOTION_BLOCKED` | n/a | — |
|
||||
| GAP-02 | Documented unimplemented (VD-15) | promotion evidence, not a red test | — | `PROMOTION_BLOCKED` | n/a | — |
|
||||
| GAP-03 | Documented unimplemented (VD-15) | promotion evidence, not a red test | — | `PROMOTION_BLOCKED` | n/a | — |
|
||||
| STO-01 | 템플릿에서 OPFS 조립 안 됨. 제품 writer가 있으면 **Critical** | `corepack pnpm exec vitest run tests/unit/opfs-byte-store.test.ts tests/unit/opfs-worker-runtime.test.ts tests/unit/indexeddb-opfs-journal.test.ts` | `fix: preserve OPFS recovery authority during cleanup` | `FIXED_NOT_RELEASED` | OPFS reconcile 적체 또는 journal 증가 | 실패: 새 saga 사례 4개 → OPFS 테스트 파일 3개에서 통과 25/25. `check:types` PASS(web-worker 포함). `check:browser-file-storage-boundaries` PASS. `lint` PASS. `test:unit` 1511개 통과, 실패는 원래 있던 환경 탓 `ci-artifact-contract` 실패뿐 |
|
||||
| STO-02 | 브라우저 파일 runtime 조립 안 됨 | `corepack pnpm exec vitest run tests/unit/browser-file-download.test.ts` | `fix: execute canonical browser download targets` | `FIXED_NOT_RELEASED` | canonical target 때문에 다운로드 이동이 막힘 | 실패 2개(가공하지 않은 상대 href를 host에 넘김) → 통과 17/17 |
|
||||
| STO-03 | 공개 캐시 조립 안 됨 | `corepack pnpm exec vitest run tests/unit/public-response-cache.test.ts` | `fix: make public cache staging repairable` | `FIXED_NOT_RELEASED` | 기존 정책을 조립 단계에서 거부 | 실패: STO-03..05에 걸친 사례 4개 → 통과 21/21. `check:types` PASS. `check:browser-file-storage-boundaries` PASS. `lint` PASS |
|
||||
| STO-04 | 공개 캐시 조립 안 됨 | `corepack pnpm exec vitest run tests/unit/public-response-cache.test.ts` | `fix: make public cache staging repairable` | `FIXED_NOT_RELEASED` | restage 반복 또는 대역폭 급증 | — |
|
||||
| STO-05 | 공개 캐시 조립 안 됨 | `corepack pnpm exec vitest run tests/unit/public-response-cache.test.ts` | `fix: make public cache staging repairable` | `FIXED_NOT_RELEASED` | 필요한 capability 없이 활성화 허용 | — |
|
||||
| STO-06 | IndexedDB 유지보수 | `corepack pnpm exec vitest run tests/unit/indexeddb-maintenance.test.ts` | `fix: bound migration commits and version the OPFS worker protocol` | `FIXED_NOT_RELEASED` | migration checkpoint 멈춤 | 실패: commit 단계 deadline 사례 → 통과 13/13. 단조(monotonic) budget을 각 레코드의 첫 쓰기 전에 다시 확인한다. 이미 시작한 레코드는 원자적으로 끝낸다. clock이 실패하면 transaction을 중단한다 |
|
||||
| STO-07 | OPFS worker 프로토콜 | `corepack pnpm exec vitest run tests/unit/opfs-worker-runtime.test.ts` | `fix: bound migration commits and version the OPFS worker protocol` | `FIXED_NOT_RELEASED` | page/worker `INCOMPATIBLE` 급증 | OPFS 테스트 파일에서 통과 23/23. 모든 envelope가 `OPFS_WORKER_PROTOCOL_VERSION = 2`를 담고, 응답은 요청 kind를 그대로 돌려준다. 실패 모양은 엄격한 decoder로 읽는다. kind나 버전이 다르면 `UNSUPPORTED`로 닫는다. 닫힌 분류(closed taxonomy)에는 `INCOMPATIBLE` 코드가 없고, 새로 만들지도 않았다 |
|
||||
| STO-08 | 가설. 브라우저에서 동작 확인(characterization)이 필요 | `corepack pnpm exec playwright test --config playwright.capabilities.config.ts tests/browser-capabilities/browser-files.spec.ts` | 없음(소스 바꾸지 않음) | `UNVERIFIED` | 확인 전까지 해당 없음 | chromium 2/2 PASS. webkit은 실행되지 않았다(`libevent-2.1-7t64`, `libavif16` 없음, 환경 문제). 기존 spec은 `Window.showOpenFilePicker`/`showSaveFilePicker`를 실행하지 않는다. 이 둘은 사용자 동작과 네이티브 대화상자가 필요하다. 그래서 receiver-binding 가설은 **재현하지도 반박하지도 못했다**. `SystemPickerHost`는 만들지 않았다. 계획은 확인하지 않은 가설을 결함으로 보고 구현하는 것을 금한다. |
|
||||
| GAP-01 | 문서에 미구현으로 적힘(VD-15) | promotion 증거(실패 테스트가 아님) | — | `PROMOTION_BLOCKED` | 해당 없음 | — |
|
||||
| GAP-02 | 문서에 미구현으로 적힘(VD-15) | promotion 증거(실패 테스트가 아님) | — | `PROMOTION_BLOCKED` | 해당 없음 | — |
|
||||
| GAP-03 | 문서에 미구현으로 적힘(VD-15) | promotion 증거(실패 테스트가 아님) | — | `PROMOTION_BLOCKED` | 해당 없음 | — |
|
||||
|
||||
### Realtime and Browser RPC (`docs/reviews/adapters/02-realtime-and-browser-rpc.md`)
|
||||
### Realtime과 Browser RPC (`docs/reviews/adapters/02-realtime-and-browser-rpc.md`)
|
||||
|
||||
| ID | Activation | Red test command | Fix commit/PR | Rollout state | Rollback trigger | Evidence |
|
||||
| ID | Activation | 실패 테스트 명령 | 수정 커밋/PR | Rollout 상태 | Rollback 기준 | 증거 |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| R-01 | Browser RPC `AVAILABLE_NOT_COMPOSED` | `corepack pnpm exec vitest run tests/unit/browser-rpc/browser-rpc-runtime.test.ts` | `fix: install bounded Browser RPC stream leases` | `FIXED_NOT_RELEASED` | stream lease deadlock | Stream cleanup is bounded; the generator no longer waits indefinitely on a non-cooperative `iterator.return()` |
|
||||
| R-02 | Realtime `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/realtime/stream-coordinator.test.ts` | `fix: retain realtime work through draining` | `FIXED_NOT_RELEASED` | stream stuck in `DRAINING` | Red never-settling effect and recovery → green 27/27; `close()` returns `IDLE_TIMEOUT` while a task is retained and success only after actual settlement |
|
||||
| R-03 | Realtime `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/realtime/live-poll-handoff-coordinator.test.ts` | `fix: retain realtime work through draining` | `FIXED_NOT_RELEASED` | retired-writer set growth | Red overflow fail-close then `close()` → green 11/11; retired writers are waited on and only removed once actually quiesced |
|
||||
| R-04 | Browser RPC `AVAILABLE_NOT_COMPOSED` | `corepack pnpm exec vitest run tests/unit/browser-rpc/browser-rpc-contract.test.ts` | `fix: install bounded Browser RPC stream leases` | `FIXED_NOT_RELEASED` | binding install rejection | Red post-validation mutation, accessor and symbol cases → green 19/19; getters are never invoked |
|
||||
| R-05 | WebSocket protocol codec | `corepack pnpm exec vitest run tests/unit/realtime/websocket-protocol.test.ts` | `fix: install bounded Browser RPC stream leases` | `FIXED_NOT_RELEASED` | frame rejection regression | Red oversize frame allocated an encoder copy → green 8/8; byte counts match `TextEncoder` including lone surrogates |
|
||||
| R-06 | Browser RPC `AVAILABLE_NOT_COMPOSED` | `corepack pnpm exec vitest run tests/unit/browser-rpc/browser-rpc-runtime.test.ts` | `fix: install bounded Browser RPC stream leases` | `FIXED_NOT_RELEASED` | closed-failure taxonomy drift | Clock and fence reads are canonicalised into the closed Result taxonomy with single-exit cleanup |
|
||||
| R-07 | Promotion blocker | concrete transport conformance evidence | — | `PROMOTION_BLOCKED` | n/a | — |
|
||||
| R-01 | Browser RPC `AVAILABLE_NOT_COMPOSED` | `corepack pnpm exec vitest run tests/unit/browser-rpc/browser-rpc-runtime.test.ts` | `fix: install bounded Browser RPC stream leases` | `FIXED_NOT_RELEASED` | stream lease 교착 | stream 정리에 시간 제한이 있다. generator는 협조하지 않는 `iterator.return()`을 더는 끝없이 기다리지 않는다 |
|
||||
| R-02 | Realtime `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/realtime/stream-coordinator.test.ts` | `fix: retain realtime work through draining` | `FIXED_NOT_RELEASED` | stream이 `DRAINING`에 멈춤 | 실패: 끝나지 않는 effect와 recovery → 통과 27/27. 작업이 남아 있는 동안 `close()`는 `IDLE_TIMEOUT`을 돌려주고, 실제로 끝난 뒤에만 성공을 돌려준다 |
|
||||
| R-03 | Realtime `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/realtime/live-poll-handoff-coordinator.test.ts` | `fix: retain realtime work through draining` | `FIXED_NOT_RELEASED` | retired writer 집합 증가 | 실패: overflow로 fail-close한 뒤 `close()` → 통과 11/11. retired writer를 기다리고, 실제로 멈춘 뒤에만 지운다 |
|
||||
| R-04 | Browser RPC `AVAILABLE_NOT_COMPOSED` | `corepack pnpm exec vitest run tests/unit/browser-rpc/browser-rpc-contract.test.ts` | `fix: install bounded Browser RPC stream leases` | `FIXED_NOT_RELEASED` | binding 설치 거부 | 실패: 검증 뒤 변경, accessor, symbol 사례 → 통과 19/19. getter를 한 번도 부르지 않는다 |
|
||||
| R-05 | WebSocket 프로토콜 codec | `corepack pnpm exec vitest run tests/unit/realtime/websocket-protocol.test.ts` | `fix: install bounded Browser RPC stream leases` | `FIXED_NOT_RELEASED` | frame 거부 회귀 | 실패: 너무 큰 frame이 encoder 사본을 할당함 → 통과 8/8. 바이트 수가 짝 없는 surrogate까지 포함해 `TextEncoder`와 같다 |
|
||||
| R-06 | Browser RPC `AVAILABLE_NOT_COMPOSED` | `corepack pnpm exec vitest run tests/unit/browser-rpc/browser-rpc-runtime.test.ts` | `fix: install bounded Browser RPC stream leases` | `FIXED_NOT_RELEASED` | 닫힌 실패 분류 drift | clock과 fence 읽기 결과를 닫힌 Result 분류로 정규화하고, 정리는 출구 하나에서 한다 |
|
||||
| R-07 | Promotion 차단 요인 | 실제 transport 적합성 증거 | — | `PROMOTION_BLOCKED` | 해당 없음 | — |
|
||||
|
||||
### Browser transfer (`docs/reviews/adapters/04-browser-transfer.md`)
|
||||
### 브라우저 전송 (`docs/reviews/adapters/04-browser-transfer.md`)
|
||||
|
||||
| ID | Activation | Red test command | Fix commit/PR | Rollout state | Rollback trigger | Evidence |
|
||||
| ID | Activation | 실패 테스트 명령 | 수정 커밋/PR | Rollout 상태 | Rollback 기준 | 증거 |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| BT-PRE-01 | Presigned `AVAILABLE_NOT_COMPOSED` | `corepack pnpm exec vitest run tests/unit/presigned-transfer.test.ts` | `fix: lazy presigned download leases` | `FIXED_NOT_RELEASED` | download lease leak | Red lazy-lease cases → green 29/29; `open()` performs no network I/O and `close()` is idempotent |
|
||||
| BT-PRE-02 | Wire contract gap | `corepack pnpm exec vitest run tests/unit/presigned-transfer.test.ts` | `fix: complete presigned capability and upload transport contracts` | `FIXED_NOT_RELEASED` | provider `POLICY_REJECTED` spike | Red missing/V0/V2 protocol cases → green; request always declares `PRESIGNED_TRANSFER_V1` and a mismatched response is closed as `POLICY_REJECTED` before vault registration |
|
||||
| BT-PRE-03 | Presigned provider | `corepack pnpm exec vitest run tests/unit/presigned-transfer.test.ts` | `fix: complete presigned capability and upload transport contracts` | `FIXED_NOT_RELEASED` | timeout not bounding fetch | Red non-cooperative fetch → green; the scope races the task, the late response body is cancelled, and a throwing scheduler leaks no listener |
|
||||
| BT-PRE-04 | Presigned vault | `corepack pnpm exec vitest run tests/unit/presigned-transfer.test.ts` | `fix: complete presigned capability and upload transport contracts` | `FIXED_NOT_RELEASED` | issuer/consumer split break | Red 6-case issuer-seam table → green; the vault re-checks method, href/origin/path agreement, credentials, byte, digest and expiry invariants itself |
|
||||
| BT-PRE-05 | Provider path decoding | `corepack pnpm exec vitest run tests/unit/presigned-transfer.test.ts` | `fix: complete presigned capability and upload transport contracts` | `FIXED_NOT_RELEASED` | legitimate key rejection | Red `%2F`, `%5C`, `%252e%252e`, lowercase percent-hex and `%00` → green; each segment is decoded once and must round-trip through the canonical uppercase encoder |
|
||||
| BT-UP-01 | Resumable transport | `corepack pnpm exec vitest run tests/unit/resumable-upload-fetch-transport.test.ts` | `fix: harden resumable upload transport contracts` | `FIXED_NOT_RELEASED` | signal facade rejection | `isAbortSignal` now requires `removeEventListener` and release cleanup is isolated |
|
||||
| BT-UP-02 | Resumable transport | `corepack pnpm exec vitest run tests/unit/resumable-upload-fetch-transport.test.ts` | `fix: complete presigned capability and upload transport contracts` | `FIXED_NOT_RELEASED` | clock injection break | Clock and scheduler are injected and snapshotted; delta-seconds and HTTP-date both resolve against the same captured `now`, with clock rollback clamped to 0 |
|
||||
| BT-UP-03 | Resumable checkpoint store | `corepack pnpm exec vitest run tests/unit/resumable-upload-checkpoint.test.ts` | `fix: report unknown IndexedDB delete effects` | `FIXED_NOT_RELEASED` | pending-delete registry growth | Red blocked-deadline case → green `PENDING`/`UNKNOWN`; a realm-scoped registry blocks recreating the partition |
|
||||
| BT-UP-04 | Presigned part executor | `corepack pnpm exec vitest run tests/unit/resumable-upload-checkpoint.test.ts` | `fix: harden resumable upload transport contracts` | `FIXED_NOT_RELEASED` | expiry check rejection | Non-finite and negative clocks return `UNAVAILABLE`/`RESUME` instead of bypassing expiry |
|
||||
| BT-UP-05 | Refactor | `corepack pnpm exec vitest run tests/unit/resumable-upload-runtime.test.ts` | — | `NOT_PERFORMED` | characterization drift | **Attempted and reverted.** The five internal owners were extracted mechanically, but they require a shared-internals module for `RuntimeDependencies`, `ActiveResolution`, `ReconciliationResolution`, `FAILURE_CODES`, `RECOVERIES`, `reportProgress`, `observeTerminal` and ~40 further bindings to avoid an import cycle. Rather than risk the verified correctness work in this file, the extraction was reverted rather than half-landed. Behaviour and the public facade are unchanged; the file is still 2,239 lines. |
|
||||
| BT-UP-06 | Refactor | `corepack pnpm exec vitest run tests/unit/resumable-upload-runtime.test.ts` | `fix: drain resumable upload teardown` | `FIXED_NOT_RELEASED` | drain not quiescent | Red single-flight dispose case → green 18/18; `close()` closes admission and starts the same drain, `dispose()` aborts the active-operation registry and awaits real settlement before closing the checkpoint store |
|
||||
| BT-UP-07 | Documented gap (Web Locks matrix) | promotion evidence | — | `PROMOTION_BLOCKED` | n/a | — |
|
||||
| BT-IMG-01 | Type-contract change | `corepack pnpm check:types:test` fixture | `fix: complete presigned capability and upload transport contracts` | `FIXED_NOT_RELEASED` | caller compile break | `resolve()` now requires the lifetime signal; `tests/fixtures/typecheck/invalid-image-cdn-resolve-signal.ts` (then its own script, merged into `check:types:fixtures` on 2026-11-08) fail as designed (2 errors), and all callers pass a signal |
|
||||
| BT-IMG-02 | Image probe | `corepack pnpm exec vitest run tests/unit/image-cdn-runtime.test.ts` | `fix: parse Cache-Control with quote awareness` | `FIXED_NOT_RELEASED` | Cache-Control parse rejection | Red unmatched-quote cases → green 25/25 |
|
||||
| BT-IMG-03 | Refactor | `corepack pnpm exec vitest run tests/unit/image-cdn-runtime.test.ts` | — | `NOT_PERFORMED` | characterization drift | **Not performed.** Same reasoning as BT-UP-05: a pure cohesion refactor of `image-cdn-runtime.ts` (1,340 lines) with no finding closure. `image-header-metadata.ts` is deliberately left intact per the review. |
|
||||
| BT-IMG-04 | Documented gap (descriptor provider) | promotion evidence | — | `PROMOTION_BLOCKED` | n/a | — |
|
||||
| BT-X-01 | Shared abort mechanics | `corepack pnpm exec vitest run tests/unit/abortable-operation.test.ts` | `fix: share abort and deadline mechanics` | `FIXED_NOT_RELEASED` | late-result compensation regression | Golden suite 8/8: first terminal owner, idempotent close, throwing scheduler, observed late rejection, late-handle compensation |
|
||||
| BT-PRE-01 | Presigned `AVAILABLE_NOT_COMPOSED` | `corepack pnpm exec vitest run tests/unit/presigned-transfer.test.ts` | `fix: lazy presigned download leases` | `FIXED_NOT_RELEASED` | 다운로드 lease 누수 | 실패: lazy lease 사례 → 통과 29/29. `open()`은 네트워크 I/O를 하지 않고, `close()`는 여러 번 불러도 결과가 같다(idempotent) |
|
||||
| BT-PRE-02 | wire 계약 빈틈 | `corepack pnpm exec vitest run tests/unit/presigned-transfer.test.ts` | `fix: complete presigned capability and upload transport contracts` | `FIXED_NOT_RELEASED` | provider `POLICY_REJECTED` 급증 | 실패: protocol 없음/V0/V2 사례 → 통과. 요청은 늘 `PRESIGNED_TRANSFER_V1`을 선언하고, 맞지 않는 응답은 vault에 등록하기 전에 `POLICY_REJECTED`로 닫는다 |
|
||||
| BT-PRE-03 | Presigned provider | `corepack pnpm exec vitest run tests/unit/presigned-transfer.test.ts` | `fix: complete presigned capability and upload transport contracts` | `FIXED_NOT_RELEASED` | timeout이 fetch를 끊지 못함 | 실패: 협조하지 않는 fetch → 통과. scope가 작업과 경주하고, 늦게 온 응답 body는 취소하며, 예외를 던지는 scheduler도 listener를 남기지 않는다 |
|
||||
| BT-PRE-04 | Presigned vault | `corepack pnpm exec vitest run tests/unit/presigned-transfer.test.ts` | `fix: complete presigned capability and upload transport contracts` | `FIXED_NOT_RELEASED` | issuer/consumer 분리 깨짐 | 실패: issuer 경계 사례 6개 표 → 통과. vault가 method, href/origin/path 일치, credential, byte, digest, 만료 불변식을 직접 다시 확인한다 |
|
||||
| BT-PRE-05 | Provider 경로 디코딩 | `corepack pnpm exec vitest run tests/unit/presigned-transfer.test.ts` | `fix: complete presigned capability and upload transport contracts` | `FIXED_NOT_RELEASED` | 정상 키 거부 | 실패: `%2F`, `%5C`, `%252e%252e`, 소문자 percent-hex, `%00` → 통과. 각 segment는 한 번만 디코딩하고, canonical 대문자 encoder로 다시 인코딩했을 때 원래 값과 같아야 한다 |
|
||||
| BT-UP-01 | Resumable transport | `corepack pnpm exec vitest run tests/unit/resumable-upload-fetch-transport.test.ts` | `fix: harden resumable upload transport contracts` | `FIXED_NOT_RELEASED` | signal facade 거부 | `isAbortSignal`은 이제 `removeEventListener`를 요구하고, release 정리는 따로 격리했다 |
|
||||
| BT-UP-02 | Resumable transport | `corepack pnpm exec vitest run tests/unit/resumable-upload-fetch-transport.test.ts` | `fix: complete presigned capability and upload transport contracts` | `FIXED_NOT_RELEASED` | clock 주입 깨짐 | clock과 scheduler를 주입받아 snapshot한다. delta-seconds와 HTTP-date 둘 다 같은 시점에 잡은 `now`로 계산하고, clock이 뒤로 가면 0으로 맞춘다 |
|
||||
| BT-UP-03 | Resumable checkpoint store | `corepack pnpm exec vitest run tests/unit/resumable-upload-checkpoint.test.ts` | `fix: report unknown IndexedDB delete effects` | `FIXED_NOT_RELEASED` | pending-delete registry 증가 | 실패: deadline에 막힌 사례 → 통과 `PENDING`/`UNKNOWN`. realm 범위 registry가 partition을 다시 만들지 못하게 막는다 |
|
||||
| BT-UP-04 | Presigned part executor | `corepack pnpm exec vitest run tests/unit/resumable-upload-checkpoint.test.ts` | `fix: harden resumable upload transport contracts` | `FIXED_NOT_RELEASED` | 만료 검사 거부 | 유한하지 않거나 음수인 clock은 만료 검사를 건너뛰지 않고 `UNAVAILABLE`/`RESUME`을 돌려준다 |
|
||||
| BT-UP-05 | 리팩터링 | `corepack pnpm exec vitest run tests/unit/resumable-upload-runtime.test.ts` | — | `NOT_PERFORMED` | 동작 기록(characterization) drift | **시도했다가 되돌렸다.** 내부 owner 다섯 개는 기계적으로 뽑아냈다. 그러나 import 순환을 피하려면 `RuntimeDependencies`, `ActiveResolution`, `ReconciliationResolution`, `FAILURE_CODES`, `RECOVERIES`, `reportProgress`, `observeTerminal`과 바인딩 약 40개를 더 담은 공유 내부 모듈이 필요했다. 이 파일에서 검증한 정확성 작업을 위험에 빠뜨리지 않으려고, 반만 반영하지 않고 추출을 되돌렸다. 동작과 공개 facade는 그대로다. 파일은 여전히 2,239줄이다. |
|
||||
| BT-UP-06 | 리팩터링 | `corepack pnpm exec vitest run tests/unit/resumable-upload-runtime.test.ts` | `fix: drain resumable upload teardown` | `FIXED_NOT_RELEASED` | drain 뒤에도 작업이 남음 | 실패: single-flight dispose 사례 → 통과 18/18. `close()`는 새 작업 받기를 닫고 같은 drain을 시작한다. `dispose()`는 active-operation registry를 중단하고, 실제로 끝나기를 기다린 뒤 checkpoint store를 닫는다 |
|
||||
| BT-UP-07 | 문서에 적힌 빈틈(Web Locks 매트릭스) | promotion 증거 | — | `PROMOTION_BLOCKED` | 해당 없음 | — |
|
||||
| BT-IMG-01 | 타입 계약 변경 | `corepack pnpm check:types:test` fixture | `fix: complete presigned capability and upload transport contracts` | `FIXED_NOT_RELEASED` | 호출부 컴파일 깨짐 | `resolve()`는 이제 lifetime signal을 요구한다. `tests/fixtures/typecheck/invalid-image-cdn-resolve-signal.ts`(그때는 전용 script였고, 2026-11-08 `check:types:fixtures`로 합쳤다)는 설계대로 실패하고(오류 2개), 모든 호출부가 signal을 넘긴다 |
|
||||
| BT-IMG-02 | Image probe | `corepack pnpm exec vitest run tests/unit/image-cdn-runtime.test.ts` | `fix: parse Cache-Control with quote awareness` | `FIXED_NOT_RELEASED` | Cache-Control 파싱 거부 | 실패: 짝 없는 따옴표 사례 → 통과 25/25 |
|
||||
| BT-IMG-03 | 리팩터링 | `corepack pnpm exec vitest run tests/unit/image-cdn-runtime.test.ts` | — | `NOT_PERFORMED` | 동작 기록(characterization) drift | **하지 않았다.** BT-UP-05와 같은 이유다. `image-cdn-runtime.ts`(1,340줄)의 순수 응집도 리팩터링이고, 이것으로 닫히는 발견이 없다. `image-header-metadata.ts`는 리뷰에 따라 일부러 그대로 뒀다. |
|
||||
| BT-IMG-04 | 문서에 적힌 빈틈(descriptor provider) | promotion 증거 | — | `PROMOTION_BLOCKED` | 해당 없음 | — |
|
||||
| BT-X-01 | 공유 abort 메커니즘 | `corepack pnpm exec vitest run tests/unit/abortable-operation.test.ts` | `fix: share abort and deadline mechanics` | `FIXED_NOT_RELEASED` | 늦은 결과 보상 회귀 | 기준(golden) 테스트 8/8: 첫 terminal owner, idempotent close, 예외를 던지는 scheduler, 관찰된 늦은 rejection, 늦은 handle 보상 |
|
||||
|
||||
### Service Worker and Web Push (`docs/reviews/adapters/05-service-worker-and-web-push.md`)
|
||||
### Service Worker와 Web Push (`docs/reviews/adapters/05-service-worker-and-web-push.md`)
|
||||
|
||||
| ID | Activation | Red test command | Fix commit/PR | Rollout state | Rollback trigger | Evidence |
|
||||
| ID | Activation | 실패 테스트 명령 | 수정 커밋/PR | Rollout 상태 | Rollback 기준 | 증거 |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| SW-URL-01 | Composed when capability selected | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: make Service Worker cache and removal outcomes truthful` | `FIXED_NOT_RELEASED` | static asset cache miss rate | Red generator-shaped root-relative asset vs absolute Request URL → green; manifest URLs canonicalized once against the registration scope |
|
||||
| SW-01 | Composed when capability selected | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: make Service Worker cache and removal outcomes truthful` | `FIXED_NOT_RELEASED` | stale response served | Red previous-cache hit → green network fallback; only the current release cache is opened, matched and deleted from |
|
||||
| SW-02 | Composed when capability selected | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: make Service Worker cache and removal outcomes truthful` | `FIXED_NOT_RELEASED` | foreign cache deletion | Red prefix deletion of `ca-static-v1-not-owned` and longer suffixes → green exact `isOwnedStaticCacheName` only |
|
||||
| SW-03 | Composed when capability selected | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: make Service Worker cache and removal outcomes truthful` | `FIXED_NOT_RELEASED` | false removal success | Red `unregister() === false` reported as UNREGISTERED → green FAILED |
|
||||
| SW-04 | Composed when capability selected | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: make Service Worker cache and removal outcomes truthful` | `FIXED_NOT_RELEASED` | removal outcome misreport | Red removal modes always DISABLED → green outcome matrix (ABSENT/UNREGISTERED/PURGED→DISABLED, OWNERSHIP_MISMATCH→INCOMPATIBLE, FAILED→FAILED) |
|
||||
| SW-05 | Build gate | `corepack pnpm exec vitest run tests/unit/service-worker-build-input.test.ts` | `fix: make Service Worker cache and removal outcomes truthful` | `FIXED_NOT_RELEASED` | build admission rejection | Red tamper table (stale digest, byte length, cross-origin URL, dot segment, extension mismatch, unknown field, duplicate URL) → green; build gate decodes through the shared codec and recomputes the canonical digest |
|
||||
| SW-06 | Composed when capability selected | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: harden Service Worker activation and install lifecycle` | `FIXED_NOT_RELEASED` | activation handshake failure | Red foreign-source drain, source swap and 10 concurrent activations → green 24/24; replies correlate by source object identity against the captured waiting worker or controller, and activation/reset are single-flight |
|
||||
| SW-07 | Composed when capability selected | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: harden Service Worker activation and install lifecycle` | `FIXED_NOT_RELEASED` | activation blocked with zero clients | An empty in-scope client set is vacuously drained; `clients.matchAll()` failure still rejects |
|
||||
| SW-08 | Composed when capability selected | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: harden Service Worker activation and install lifecycle` | `FIXED_NOT_RELEASED` | per-client failure escalation | Per-client `postMessage` isolation; `skipWaiting()` is the commit point and its failure is REJECTED, with accepted/reload notifications sent only afterwards as best effort |
|
||||
| SW-09 | Composed when capability selected | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: harden Service Worker activation and install lifecycle` | `FIXED_NOT_RELEASED` | late install work observed | Red late-fetch case → green; a fenced worker starts no new candidate work, late response bodies are cancelled, digest throws map to a closed outcome, and a second exact-delete runs once the abandoned install settles without extending the public bound |
|
||||
| SW-10 | Protocol V2 migration | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | — | `DEFERRED_TO_MIGRATION` | V1/V2 mismatch fail-close | Not closed here. Full-identity protocol V2 is an expand → dual-read → old-writer drain → contract deployment that spans releases; the prerequisite shared manifest codec and canonical digest landed with SW-05. |
|
||||
| WP-01 | Web Push `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/web-push-fence-store.test.ts` | `fix: bind Web Push mutations to exact authority` | `FIXED_NOT_RELEASED` | CAS receipt rejection | Red stale/skipped/huge revision receipts → green; write and remove share one exact-next-revision validator |
|
||||
| WP-02 | Web Push `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/web-push-fence-store.test.ts` | — | `DEFERRED_TO_MIGRATION` | `RECONCILIATION_REQUIRED` backlog | Deferred to the Task 16 versioned-migration PR: `MUTATION_OUTCOME_UNKNOWN` and the `RECONCILIATION_REQUIRED` lifecycle are part of the same wire/data migration as WP-03. |
|
||||
| WP-03 | Web Push `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/web-push-subscription-adapter.test.ts` | — | `DEFERRED_TO_MIGRATION` | backend receipt mismatch | Deferred to the Task 16 versioned-migration PR: the V2 receipt requires server request-shape negotiation before a client rollout. |
|
||||
| WP-04 | Web Push `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/web-push-subscription-adapter.test.ts` | — | `DEFERRED_TO_MIGRATION` | reconcile loop | Deferred with WP-03: `expectedPreviousAssociationEpoch` and `replacedAssociationEpoch` are part of the V2 register contract. |
|
||||
| WP-05 | Web Push `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/web-push-subscription-adapter.test.ts` | `fix: bind Web Push mutations to exact authority` | `FIXED_NOT_RELEASED` | pre-abort observation drift | A pre-aborted command records the requested operation instead of always INSPECT |
|
||||
| WP-06 | Web Push `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/web-push-worker-runtime.test.ts` | `fix: bind Web Push mutations to exact authority` | `FIXED_NOT_RELEASED` | truncation reported degraded | Client handoff and notification cleanup report `countBucket` and `truncated`; an incomplete cleanup returns `{ complete: false }` and is DEGRADED |
|
||||
| WP-07 | Web Push `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/web-push-worker-runtime.test.ts` | `fix: bind Web Push mutations to exact authority` | `FIXED_NOT_RELEASED` | late native effect certainty | Native notification effect is tracked as NOT_APPLIED → MAYBE_APPLIED → CONFIRMED and observed as evidence only |
|
||||
| SW-URL-01 | capability를 고르면 조립됨 | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: make Service Worker cache and removal outcomes truthful` | `FIXED_NOT_RELEASED` | 정적 asset 캐시 miss 비율 | 실패: generator가 만든 root 기준 상대 asset과 절대 Request URL 비교 → 통과. manifest URL은 등록 scope 기준으로 한 번만 정규화한다 |
|
||||
| SW-01 | capability를 고르면 조립됨 | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: make Service Worker cache and removal outcomes truthful` | `FIXED_NOT_RELEASED` | 낡은 응답 제공 | 실패: 이전 캐시 hit → 통과: 네트워크 fallback. 지금 release 캐시만 열고, 찾고, 지운다 |
|
||||
| SW-02 | capability를 고르면 조립됨 | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: make Service Worker cache and removal outcomes truthful` | `FIXED_NOT_RELEASED` | 남의 캐시 삭제 | 실패: prefix로 `ca-static-v1-not-owned`와 더 긴 접미사까지 지움 → 통과: 정확한 `isOwnedStaticCacheName`만 |
|
||||
| SW-03 | capability를 고르면 조립됨 | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: make Service Worker cache and removal outcomes truthful` | `FIXED_NOT_RELEASED` | 거짓 제거 성공 | 실패: `unregister() === false`를 UNREGISTERED로 보고 → 통과: FAILED |
|
||||
| SW-04 | capability를 고르면 조립됨 | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: make Service Worker cache and removal outcomes truthful` | `FIXED_NOT_RELEASED` | 제거 결과 잘못 보고 | 실패: 제거 모드가 늘 DISABLED → 통과: 결과 매트릭스(ABSENT/UNREGISTERED/PURGED→DISABLED, OWNERSHIP_MISMATCH→INCOMPATIBLE, FAILED→FAILED) |
|
||||
| SW-05 | 빌드 게이트 | `corepack pnpm exec vitest run tests/unit/service-worker-build-input.test.ts` | `fix: make Service Worker cache and removal outcomes truthful` | `FIXED_NOT_RELEASED` | 빌드 허용 거부 | 실패: 변조 사례 표(낡은 digest, 바이트 길이, cross-origin URL, dot segment, 확장자 불일치, 모르는 필드, 중복 URL) → 통과. 빌드 게이트는 공유 codec으로 디코딩하고 canonical digest를 다시 계산한다 |
|
||||
| SW-06 | capability를 고르면 조립됨 | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: harden Service Worker activation and install lifecycle` | `FIXED_NOT_RELEASED` | activation handshake 실패 | 실패: 남의 source drain, source 바꿔치기, 동시 activation 10개 → 통과 24/24. 응답은 잡아 둔 waiting worker나 controller와 source 객체 동일성으로 맞춘다. activation/reset은 single-flight다 |
|
||||
| SW-07 | capability를 고르면 조립됨 | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: harden Service Worker activation and install lifecycle` | `FIXED_NOT_RELEASED` | client 0개에서 activation 막힘 | scope 안 client 집합이 비어 있으면 drain된 것으로 본다. `clients.matchAll()` 실패는 여전히 거부한다 |
|
||||
| SW-08 | capability를 고르면 조립됨 | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: harden Service Worker activation and install lifecycle` | `FIXED_NOT_RELEASED` | client별 실패가 전체로 번짐 | client별 `postMessage`를 격리한다. `skipWaiting()`이 commit 지점이고, 실패하면 REJECTED다. accepted/reload 알림은 그 뒤에만 best effort로 보낸다 |
|
||||
| SW-09 | capability를 고르면 조립됨 | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: harden Service Worker activation and install lifecycle` | `FIXED_NOT_RELEASED` | 늦은 install 작업 관찰됨 | 실패: 늦은 fetch 사례 → 통과. fence된 worker는 새 후보 작업을 시작하지 않는다. 늦은 응답 body는 취소한다. digest 예외는 닫힌 결과로 대응한다. 버린 install이 끝나면 두 번째 exact-delete를 돌리되, 공개된 시간 한도를 늘리지 않는다 |
|
||||
| SW-10 | 프로토콜 V2 migration | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | — | `DEFERRED_TO_MIGRATION` | V1/V2 불일치 fail-close | 여기서 닫지 않았다. full-identity 프로토콜 V2는 expand → dual-read → old-writer drain → contract 순서의 배포이고, 여러 release에 걸친다. 선행 조건인 공유 manifest codec과 canonical digest는 SW-05와 함께 반영했다. |
|
||||
| WP-01 | Web Push `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/web-push-fence-store.test.ts` | `fix: bind Web Push mutations to exact authority` | `FIXED_NOT_RELEASED` | CAS receipt 거부 | 실패: 낡은/건너뛴/아주 큰 revision receipt → 통과. write와 remove가 exact-next-revision validator 하나를 같이 쓴다 |
|
||||
| WP-02 | Web Push `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/web-push-fence-store.test.ts` | — | `DEFERRED_TO_MIGRATION` | `RECONCILIATION_REQUIRED` 적체 | Task 16 버전 migration PR로 미뤘다. `MUTATION_OUTCOME_UNKNOWN`과 `RECONCILIATION_REQUIRED` lifecycle은 WP-03과 같은 wire/data migration의 일부다. |
|
||||
| WP-03 | Web Push `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/web-push-subscription-adapter.test.ts` | — | `DEFERRED_TO_MIGRATION` | backend receipt 불일치 | Task 16 버전 migration PR로 미뤘다. V2 receipt는 client rollout 전에 서버와 요청 모양을 협상해야 한다. |
|
||||
| WP-04 | Web Push `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/web-push-subscription-adapter.test.ts` | — | `DEFERRED_TO_MIGRATION` | reconcile 반복 | WP-03과 함께 미뤘다. `expectedPreviousAssociationEpoch`와 `replacedAssociationEpoch`는 V2 register 계약의 일부다. |
|
||||
| WP-05 | Web Push `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/web-push-subscription-adapter.test.ts` | `fix: bind Web Push mutations to exact authority` | `FIXED_NOT_RELEASED` | 사전 abort 관찰 drift | 미리 abort된 command는 늘 INSPECT가 아니라 요청된 작업을 기록한다 |
|
||||
| WP-06 | Web Push `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/web-push-worker-runtime.test.ts` | `fix: bind Web Push mutations to exact authority` | `FIXED_NOT_RELEASED` | 잘림을 degraded로 보고 | client handoff와 알림 정리가 `countBucket`과 `truncated`를 보고한다. 끝나지 않은 정리는 `{ complete: false }`를 돌려주고 DEGRADED다 |
|
||||
| WP-07 | Web Push `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/web-push-worker-runtime.test.ts` | `fix: bind Web Push mutations to exact authority` | `FIXED_NOT_RELEASED` | 늦은 네이티브 effect의 확실성 | 네이티브 알림 effect를 NOT_APPLIED → MAYBE_APPLIED → CONFIRMED로 추적하고, 증거로만 관찰한다 |
|
||||
|
||||
## Final evidence (plan Task 18)
|
||||
## 최종 증거 (계획 Task 18)
|
||||
|
||||
Captured after every correctness task landed.
|
||||
정확성 작업이 다 반영된 뒤 기록했다.
|
||||
|
||||
### Focused subsystem suites (fresh processes)
|
||||
### 하위 시스템별 테스트 (새 프로세스)
|
||||
|
||||
| Suite | Exit | Result |
|
||||
| 테스트 | 종료 | 결과 |
|
||||
| --- | ---: | --- |
|
||||
| `tests/unit/browser-rpc` + `tests/unit/realtime` | 0 | 192 passed |
|
||||
| OPFS, IndexedDB, public cache, download | 0 | 80 passed |
|
||||
| abortable-operation, presigned, resumable, image CDN | 0 | 104 passed |
|
||||
| Service Worker + Web Push | 0 | 66 passed |
|
||||
| `tests/unit/browser-rpc` + `tests/unit/realtime` | 0 | 192개 통과 |
|
||||
| OPFS, IndexedDB, 공개 캐시, 다운로드 | 0 | 80개 통과 |
|
||||
| abortable-operation, presigned, 재개 가능 업로드, image CDN | 0 | 104개 통과 |
|
||||
| Service Worker + Web Push | 0 | 66개 통과 |
|
||||
|
||||
### Repository gates
|
||||
### 저장소 게이트
|
||||
|
||||
| Command | Exit | Result |
|
||||
| 명령 | 종료 | 결과 |
|
||||
| --- | ---: | --- |
|
||||
| `corepack pnpm check:types` | 0 | all six projects pass |
|
||||
| `corepack pnpm lint` | 0 | `--max-warnings=0` clean |
|
||||
| `corepack pnpm check:architecture` | 0 | 288 modules, 865 dependencies; 12 fixtures PASS; allowed PASS / 9 forbidden rejected |
|
||||
| `corepack pnpm check:diagnostics` | 0 | 8 diagnostics and 5 telemetry producers PASS |
|
||||
| `corepack pnpm check:browser-file-storage-boundaries` | 0 | PASS, 34 rejections |
|
||||
| `corepack pnpm check:types` | 0 | 여섯 프로젝트 모두 통과 |
|
||||
| `corepack pnpm lint` | 0 | `--max-warnings=0`로 경고 없음 |
|
||||
| `corepack pnpm check:architecture` | 0 | 모듈 288개, 의존 865개. fixture 12개 PASS. 허용 PASS / 금지 9개 거부 |
|
||||
| `corepack pnpm check:diagnostics` | 0 | diagnostic 8개와 telemetry producer 5개 PASS |
|
||||
| `corepack pnpm check:browser-file-storage-boundaries` | 0 | PASS, 거부 34건 |
|
||||
| `corepack pnpm check:realtime-boundaries` | 0 | PASS |
|
||||
| `git diff --check` | 0 | clean |
|
||||
| `corepack pnpm test:component` | 0 | 126 passed |
|
||||
| `corepack pnpm test:integration` | 0 | 52 passed |
|
||||
| 참조 샘플 기능 시험(그 script는 2026-11-07 샘플과 함께 지웠다) | 0 | 26 passed |
|
||||
| `corepack pnpm test:recipes` | 0 | 17 passed |
|
||||
| `corepack pnpm test:unit` | 1 | 1585 passed / 19 failed tests; the 19 are the unchanged pre-existing `ci-artifact-contract` sandbox failures |
|
||||
| `corepack pnpm check:registries` | 0 | 11 registries PASS |
|
||||
| `git diff --check` | 0 | 문제 없음 |
|
||||
| `corepack pnpm test:component` | 0 | 126개 통과 |
|
||||
| `corepack pnpm test:integration` | 0 | 52개 통과 |
|
||||
| 참조 샘플 기능 시험(그 script는 2026-11-07 샘플과 함께 지웠다) | 0 | 26개 통과 |
|
||||
| `corepack pnpm test:recipes` | 0 | 17개 통과 |
|
||||
| `corepack pnpm test:unit` | 1 | 테스트 1585개 통과 / 19개 실패. 19개는 원래 있던 그대로인 `ci-artifact-contract` sandbox 실패다 |
|
||||
| `corepack pnpm check:registries` | 0 | registry 11개 PASS |
|
||||
| `corepack pnpm verify:documentation` | 0 | PASS_SCOPED |
|
||||
| 음성 fixture `invalid-image-cdn-resolve-signal.ts` 단독 tsc(그 script는 2026-11-08 `check:types:fixtures`로 합쳤다) | 1 | **Expected non-zero.** Negative fixture proving `resolve()` now rejects a call without a lifetime signal (BT-IMG-01). |
|
||||
| 음성 fixture `invalid-image-cdn-resolve-signal.ts` 단독 tsc(그 script는 2026-11-08 `check:types:fixtures`로 합쳤다) | 1 | **0이 아닌 것이 정상이다.** `resolve()`가 이제 lifetime signal 없는 호출을 거부함을 보이는 음성 fixture다(BT-IMG-01). |
|
||||
|
||||
`test:all` stops at `test:unit`, so the later suites above were run directly.
|
||||
`test:all`은 `test:unit`에서 멈춘다. 그래서 위의 나머지 테스트는 직접 돌렸다.
|
||||
|
||||
### Final disposition of all 64 findings
|
||||
### 발견 64건 전체의 최종 처리
|
||||
|
||||
| State | Count |
|
||||
| 상태 | 수 |
|
||||
| --- | ---: |
|
||||
| `FIXED_NOT_RELEASED` | 51 |
|
||||
| `PROMOTION_BLOCKED` (unchanged by design) | 6 |
|
||||
| `PROMOTION_BLOCKED`(설계상 그대로) | 6 |
|
||||
| `DEFERRED_TO_MIGRATION` (`WP-02`, `WP-03`, `WP-04`, `SW-10`) | 4 |
|
||||
| `NOT_PERFORMED` (`BT-UP-05`, `BT-IMG-03` cohesion refactors) | 2 |
|
||||
| `UNVERIFIED` (`STO-08` browser hypothesis) | 1 |
|
||||
| `NOT_PERFORMED`(`BT-UP-05`, `BT-IMG-03` 응집도 리팩터링) | 2 |
|
||||
| `UNVERIFIED`(`STO-08` 브라우저 가설) | 1 |
|
||||
|
||||
No finding remains `NOT_STARTED`.
|
||||
`NOT_STARTED`로 남은 발견은 없다.
|
||||
|
||||
### Failures that are NOT claimed as green
|
||||
### 통과로 주장하지 않는 실패
|
||||
|
||||
| Gate | Status | Attribution |
|
||||
| 게이트 | 상태 | 원인 |
|
||||
| --- | --- | --- |
|
||||
| `tests/system/ci-runner/ci-artifact-contract.test.ts` | 19 failed | Identical to the baseline capture. Sandbox child-process, cgroup and `/tmp` permission behavior; unrelated to adapters. Count did not change across any task. |
|
||||
| `corepack pnpm test:browser-capabilities` (webkit) | 6 failed / 24 passed | WebKit cannot launch: missing `libevent-2.1-7t64` and `libavif16`. Chromium passes. **UNVERIFIED**, not PASS. |
|
||||
| `corepack pnpm test:browser-file-storage-removal` | exit 1 | The reduced-removal-fixture prunes the CI contract to 77/89/102 while `scripts/contracts/ci-gates.ts:481` demands exactly 81/93/105. That file, the CI contract and `scripts/lib/removal-fixture.ts` are **unchanged since the baseline revision** (`git diff --name-only 4dc033c..HEAD` outside `src/`, `tests/` and `docs/` lists only the two Service Worker build scripts), so this is pre-existing, not a regression from this work. |
|
||||
| `corepack pnpm test:realtime-removal` | exit 1 | Same pre-existing reduced-fixture arithmetic. |
|
||||
| Server/provider compatibility matrices (presigned V1, Web Push V1/V2, Service Worker V1/V2, OPFS V1/V2) | not run | No provider or multi-release infrastructure in this environment. **UNVERIFIED**. |
|
||||
| Staging rollback drill | not run | Requires a staging deployment. **UNVERIFIED**. |
|
||||
| `tests/system/ci-runner/ci-artifact-contract.test.ts` | 19개 실패 | 기준 기록과 같다. sandbox의 자식 프로세스, cgroup, `/tmp` 권한 동작이고 adapter와 관계없다. 어떤 작업에서도 수가 바뀌지 않았다. |
|
||||
| `corepack pnpm test:browser-capabilities` (webkit) | 6개 실패 / 24개 통과 | WebKit을 실행할 수 없다. `libevent-2.1-7t64`와 `libavif16`이 없다. Chromium은 통과한다. PASS가 아니라 **UNVERIFIED**다. |
|
||||
| `corepack pnpm test:browser-file-storage-removal` | exit 1 | 축소 제거 fixture(reduced-removal-fixture)는 CI 계약을 77/89/102로 줄이는데, `scripts/contracts/ci-gates.ts:481`은 정확히 81/93/105를 요구한다. 그 파일, CI 계약, `scripts/lib/removal-fixture.ts`는 **기준 리비전 뒤로 바뀌지 않았다**(`src/`, `tests/`, `docs/` 밖에서 `git diff --name-only 4dc033c..HEAD`는 Service Worker 빌드 스크립트 두 개만 보여 준다). 그래서 원래 있던 실패이고, 이 작업이 만든 회귀가 아니다. |
|
||||
| `corepack pnpm test:realtime-removal` | exit 1 | 같은, 원래 있던 축소 fixture 숫자 문제다. |
|
||||
| 서버/provider 호환성 매트릭스(presigned V1, Web Push V1/V2, Service Worker V1/V2, OPFS V1/V2) | 돌리지 않음 | 이 환경에는 provider도, 여러 release를 돌릴 인프라도 없다. **UNVERIFIED**. |
|
||||
| staging rollback drill | 돌리지 않음 | staging 배포가 필요하다. **UNVERIFIED**. |
|
||||
|
||||
### Work deliberately not performed
|
||||
### 일부러 하지 않은 작업
|
||||
|
||||
| Plan task | Status | Reason |
|
||||
| 계획 작업 | 상태 | 이유 |
|
||||
| --- | --- | --- |
|
||||
| Task 17 extraction (`BT-UP-05`, `BT-IMG-03`, OPFS/cache/download decomposition) | **NOT PERFORMED** | Pure cohesion refactor with no finding closure. `BT-UP-05` was attempted: the five internal owners extract cleanly, but they need a shared-internals module for ~40 types, constants and helpers to avoid an import cycle, so the attempt was reverted rather than half-landed. `BT-UP-06`, the one item in this group with behavioural content, **was** implemented. |
|
||||
| `SW-10`, OPFS physical/protocol V2 rollout, presigned and Web Push receipt V2 (`WP-02`, `WP-03`, `WP-04`) | **DEFERRED_TO_MIGRATION** | These are expand → dual-read/emit → old-writer drain → contract deployments requiring server request-shape negotiation and multi-release drain windows. The prerequisite in-repo pieces landed: the shared Service Worker manifest codec and canonical digest (`SW-05`), the OPFS worker protocol version and strict correlation (`STO-07`), and the OPFS physical generation token (`STO-01`). |
|
||||
| Promotion gaps `GAP-01`, `GAP-02`, `GAP-03`, `R-07`, `BT-UP-07`, `BT-IMG-04` | `PROMOTION_BLOCKED` | Unchanged by design. No availability state was raised and no optional capability was added to the default bootstrap. |
|
||||
| Task 17 추출(`BT-UP-05`, `BT-IMG-03`, OPFS/캐시/다운로드 분해) | **NOT PERFORMED** | 이것으로 닫히는 발견이 없는 순수 응집도 리팩터링이다. `BT-UP-05`는 시도했다. 내부 owner 다섯 개는 깔끔하게 뽑히지만, import 순환을 피하려면 타입·상수·helper 약 40개를 담은 공유 내부 모듈이 필요하다. 그래서 반만 반영하지 않고 되돌렸다. 이 묶음에서 동작이 바뀌는 유일한 항목인 `BT-UP-06`은 구현**했다**. |
|
||||
| `SW-10`, OPFS 물리/프로토콜 V2 rollout, presigned와 Web Push receipt V2(`WP-02`, `WP-03`, `WP-04`) | **DEFERRED_TO_MIGRATION** | 이것들은 expand → dual-read/emit → old-writer drain → contract 순서의 배포다. 서버와 요청 모양 협상, 여러 release에 걸친 drain 기간이 필요하다. 저장소 안에서 할 선행 작업은 반영했다. 공유 Service Worker manifest codec과 canonical digest(`SW-05`), OPFS worker 프로토콜 버전과 엄격한 대응(`STO-07`), OPFS 물리 generation token(`STO-01`)이다. |
|
||||
| Promotion 빈틈 `GAP-01`, `GAP-02`, `GAP-03`, `R-07`, `BT-UP-07`, `BT-IMG-04` | `PROMOTION_BLOCKED` | 설계상 그대로다. availability 상태를 올리지 않았고, 기본 bootstrap에 선택 capability를 더하지 않았다. |
|
||||
|
||||
## Re-review remediation (2026-08-14)
|
||||
## 재검토 후속 수정 (2026-08-14)
|
||||
|
||||
Source: [`docs/reviews/adapters/RE-REVIEW-2026-08-14.md`](../reviews/adapters/RE-REVIEW-2026-08-14.md),
|
||||
38 findings (High 19 / Medium 17 / Low 2) raised against `3b481eb`.
|
||||
출처: [`docs/reviews/adapters/RE-REVIEW-2026-08-14.md`](../reviews/adapters/RE-REVIEW-2026-08-14.md).
|
||||
`3b481eb`을 대상으로 낸 발견 38건(High 19 / Medium 17 / Low 2)이다.
|
||||
|
||||
**GOV-02.** That re-review found the previous section of this ledger closed a
|
||||
number of rows as `FIXED_NOT_RELEASED` that were in fact partial. The tables
|
||||
below are written the other way round: a row is `FIXED` only where a new
|
||||
adversarial test failed first on the pre-fix source and passes on the landed
|
||||
one.
|
||||
**GOV-02.** 그 재검토는 이 원장의 앞 절이 실제로는 부분 수정인 행 여럿을 `FIXED_NOT_RELEASED`로 닫았다는 것을 찾았다. 아래 표는 반대 방향으로 쓴다. 새 적대적(adversarial) 테스트가 수정 전 소스에서 먼저 실패하고 반영된 소스에서 통과할 때만 그 행을 `FIXED`로 적는다.
|
||||
|
||||
**All 38 second re-review findings are `FIXED` as scoped below.** The first pass
|
||||
closed 26; the second closed the remaining twelve, which each needed a lifecycle
|
||||
or contract change rather than a contained edit. A third re-review then found
|
||||
that twenty of those closures held only on the paths their tests exercised; that
|
||||
verdict and its remediation are recorded in the third re-review section further
|
||||
down, and this section is left as written so the two passes stay comparable.
|
||||
**두 번째 재검토의 발견 38건은 아래 범위에서 모두 `FIXED`다.** 1차 작업이 26건을 닫았다. 2차 작업이 나머지 12건을 닫았는데, 이들은 국소 수정이 아니라 lifecycle이나 계약 변경이 필요했다. 그 뒤 세 번째 재검토가, 이렇게 닫은 것 가운데 20건이 테스트가 거친 경로에서만 성립한다는 것을 찾았다. 그 판정과 수정은 아래 세 번째 재검토 절에 적었다. 두 작업을 비교할 수 있도록 이 절은 쓴 그대로 둔다.
|
||||
|
||||
### Landed
|
||||
### 반영한 것
|
||||
|
||||
| ID | Severity | Disposition | Commit | Red-then-green evidence |
|
||||
| ID | 심각도 | 처리 | 커밋 | 실패→통과 증거 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| LIVE-01 | High | `FIXED` | `f4bfdf0` | `tests/integration/http-execution-v3-live-authority.test.ts` — UNAVAILABLE, sync throw, async rejection and a malformed outcome each closed as `UNAUTHENTICATED` before the fix; all four now close as `AUTH_INTEGRATION_FAILURE` with zero fetches. |
|
||||
| LIVE-02 | High | `FIXED` | `f4bfdf0` | `tests/unit/contract-registry-immutability.test.ts` — a borrowed `Map.prototype.clear` emptied the installed profile registry before the fix. |
|
||||
| LIVE-03 | High | `FIXED` | `f4bfdf0` | Same suite — the composed HTTP registry was clearable and a post-composition mutation of a source policy changed `totalDeadlineMs` from 10000 to 999999. |
|
||||
| LIVE-04 | Medium | `FIXED` | `f4bfdf0` | Same integration suite — a non-cooperative fetch and reader held the port result open; a body that finished after the deadline was admitted as SUCCESS. |
|
||||
| LIVE-05 | High | `FIXED` | `f4bfdf0` | Same suite — a DEADLINE timeout emitted no `api.request.failed`. |
|
||||
| LEG-01 | High | `FIXED` | `ca210d3` | The V2 client's credential authority test (deleted with the V2 client on 2026-11-03) — a recovery that answered after the deadline called `onUnauthenticated` once; it now calls it zero times, and only an adopted no-session result notifies. |
|
||||
| LEG-02 | High | `FIXED` | `ca210d3` | Same suite — a bearer profile dispatched with no `Authorization` at all. |
|
||||
| OPT-NET-01 | Medium | `FIXED` | `ca210d3` | `tests/unit/legacy-and-optional-network-remediation.test.ts` — a loader rejection with a live signal became `PAGINATION_ABORTED`. |
|
||||
| OPT-NET-02 | Low | `FIXED` | `ca210d3` | Same suite — `defineMutationIntent` accepted control characters the executor rejected. |
|
||||
| STO-RR-01 | High | `FIXED` | `6a8281a` | `tests/unit/opfs-worker-runtime.test.ts` — a strict non-reentrant lease manager made `FINALIZE_PUT` hang forever; `tests/unit/opfs-byte-store.test.ts` pins that a failed finalization is no longer a plain success. |
|
||||
| STO-RR-02 | Medium | `FIXED` | `6a8281a` | Same suite — every failure answered with kind `CAPABILITIES`. |
|
||||
| STO-RR-03 | Medium | `FIXED` | `6a8281a` | Same suite — `{code:"EVIL"}` reached the caller; a non-boolean `retryable` and a throwing getter left the RPC to time out. |
|
||||
| STO-RR-04 | Medium | `FIXED` | `6a8281a` | `tests/unit/public-response-cache.test.ts` — a transient marker read failure deleted the active candidate. |
|
||||
| STO-RR-05 | Medium | `FIXED` | `6a8281a` | Same suite — one failed repair fetch destroyed every healthy asset in the release. |
|
||||
| RPC-RR-02 | Medium | `FIXED` | `bd90e0c` | `tests/unit/browser-rpc/browser-rpc-remediation.test.ts` — a throwing fence and a throwing `clock.sleep` escaped the Result contract. |
|
||||
| RPC-RR-03 | High | `FIXED` | `bd90e0c` | Same suite — a transport accessor ran during validation, and the installed binding registries exposed `set`/`delete`/`clear`. |
|
||||
| RPC-RR-04 | Medium | `FIXED` | `bd90e0c` | Same suite — extra, inherited, symbol-keyed and throwing-getter transport values passed. |
|
||||
| SW-RR-01 | High | `FIXED` | `efc577d` | Bounded marker reader with a read deadline, reader cancel and fatal UTF-8 decode replaces `response.text()`. |
|
||||
| SW-RR-02 | Medium | `FIXED` | `efc577d` | A `null` `event.source` no longer satisfies activation or reset completion. |
|
||||
| SW-RR-03 | Medium | `FIXED` | `efc577d` | `tests/unit/service-worker-web-push-remediation.test.ts` plus the `check:adapter-inventory` gate — generator and decoder now share one exported table. |
|
||||
| SW-RR-04 | Medium | `FIXED` | `efc577d` | `cache.match` rejection is closed as a miss so `respondWith` reaches its network fallback. |
|
||||
| WP-RR-01 | Medium | `FIXED` | `efc577d` | `focus`/`openWindow` carry NOT_APPLIED → MAYBE_APPLIED → CONFIRMED and a late effect is observed exactly once. |
|
||||
| TR-RR-08 | Medium | `FIXED` | `69cb7e3` | `tests/unit/resumable-upload-http-control-plane.test.ts` — a throwing getter escaped as `TypeError` out of `createSession`; symbol and non-enumerable extras passed the key check. |
|
||||
| TR-RR-09 | Medium | `FIXED` | `fb5b449` | `tests/unit/image-cdn-runtime.test.ts` — the suite pinned the contradictory `private, no-store` as success; the recorded fail-closed matrix now applies. |
|
||||
| GOV-01 | Low | `FIXED` | this commit | `scripts/check-adapter-inventory.ts` diffs `docs/reviews/adapters/INVENTORY.md` against `git ls-files src/adapters`. The missing `src/adapters/platform/abortable-operation.ts` row is restored and the total is 119/119. |
|
||||
| GOV-02 | Medium | `FIXED` | this commit | This section replaces the over-closed rows with evidence-linked dispositions and an explicit not-done list. |
|
||||
| LIVE-01 | High | `FIXED` | `f4bfdf0` | `tests/integration/http-execution-v3-live-authority.test.ts` — 수정 전에는 UNAVAILABLE, 동기 throw, 비동기 rejection, 잘못된 모양의 결과가 각각 `UNAUTHENTICATED`로 닫혔다. 이제 넷 다 fetch 0회로 `AUTH_INTEGRATION_FAILURE`로 닫힌다. |
|
||||
| LIVE-02 | High | `FIXED` | `f4bfdf0` | `tests/unit/contract-registry-immutability.test.ts` — 수정 전에는 빌려 온 `Map.prototype.clear`가 설치된 profile registry를 비웠다. |
|
||||
| LIVE-03 | High | `FIXED` | `f4bfdf0` | 같은 테스트 파일 — 조립된 HTTP registry를 비울 수 있었고, 조립 뒤 원본 정책을 바꾸면 `totalDeadlineMs`가 10000에서 999999로 바뀌었다. |
|
||||
| LIVE-04 | Medium | `FIXED` | `f4bfdf0` | 같은 integration 테스트 파일 — 협조하지 않는 fetch와 reader가 port 결과를 열린 채로 붙잡았다. deadline 뒤에 끝난 body를 SUCCESS로 받아들였다. |
|
||||
| LIVE-05 | High | `FIXED` | `f4bfdf0` | 같은 테스트 파일 — DEADLINE timeout이 `api.request.failed`를 내보내지 않았다. |
|
||||
| LEG-01 | High | `FIXED` | `ca210d3` | V2 client의 credential authority 테스트(2026-11-03에 V2 client와 함께 지웠다) — deadline 뒤에 답한 recovery가 `onUnauthenticated`를 한 번 불렀다. 이제는 0번 부르고, 채택된 no-session 결과만 알린다. |
|
||||
| LEG-02 | High | `FIXED` | `ca210d3` | 같은 테스트 파일 — bearer profile이 `Authorization` 없이 요청을 보냈다. |
|
||||
| OPT-NET-01 | Medium | `FIXED` | `ca210d3` | `tests/unit/legacy-and-optional-network-remediation.test.ts` — signal이 살아 있는데 loader rejection이 `PAGINATION_ABORTED`가 됐다. |
|
||||
| OPT-NET-02 | Low | `FIXED` | `ca210d3` | 같은 테스트 파일 — `defineMutationIntent`가 executor는 거부하는 제어 문자를 받아들였다. |
|
||||
| STO-RR-01 | High | `FIXED` | `6a8281a` | `tests/unit/opfs-worker-runtime.test.ts` — 엄격한 비재진입 lease manager 때문에 `FINALIZE_PUT`이 영원히 멈췄다. `tests/unit/opfs-byte-store.test.ts`는 실패한 finalization이 더는 단순 성공이 아님을 고정한다. |
|
||||
| STO-RR-02 | Medium | `FIXED` | `6a8281a` | 같은 테스트 파일 — 모든 실패가 kind `CAPABILITIES`로 답했다. |
|
||||
| STO-RR-03 | Medium | `FIXED` | `6a8281a` | 같은 테스트 파일 — `{code:"EVIL"}`이 호출자에게 닿았다. boolean이 아닌 `retryable`과 예외를 던지는 getter 때문에 RPC가 timeout까지 갔다. |
|
||||
| STO-RR-04 | Medium | `FIXED` | `6a8281a` | `tests/unit/public-response-cache.test.ts` — 일시적인 marker 읽기 실패가 활성 후보를 지웠다. |
|
||||
| STO-RR-05 | Medium | `FIXED` | `6a8281a` | 같은 테스트 파일 — repair fetch 하나가 실패하자 그 release의 정상 asset이 다 지워졌다. |
|
||||
| RPC-RR-02 | Medium | `FIXED` | `bd90e0c` | `tests/unit/browser-rpc/browser-rpc-remediation.test.ts` — 예외를 던지는 fence와 예외를 던지는 `clock.sleep`이 Result 계약을 빠져나갔다. |
|
||||
| RPC-RR-03 | High | `FIXED` | `bd90e0c` | 같은 테스트 파일 — 검증 중에 transport accessor가 실행됐고, 설치된 binding registry가 `set`/`delete`/`clear`를 드러냈다. |
|
||||
| RPC-RR-04 | Medium | `FIXED` | `bd90e0c` | 같은 테스트 파일 — 남는 필드, 상속된 필드, symbol 키, 예외를 던지는 getter가 있는 transport 값이 통과했다. |
|
||||
| SW-RR-01 | High | `FIXED` | `efc577d` | 읽기 deadline, reader 취소, fatal UTF-8 디코딩을 갖춘 크기 제한 marker reader가 `response.text()`를 대신한다. |
|
||||
| SW-RR-02 | Medium | `FIXED` | `efc577d` | `null`인 `event.source`는 더는 activation이나 reset 완료 조건을 채우지 않는다. |
|
||||
| SW-RR-03 | Medium | `FIXED` | `efc577d` | `tests/unit/service-worker-web-push-remediation.test.ts`와 `check:adapter-inventory` 게이트 — 이제 generator와 decoder가 export된 표 하나를 같이 쓴다. |
|
||||
| SW-RR-04 | Medium | `FIXED` | `efc577d` | `cache.match` rejection을 miss로 닫아서 `respondWith`가 네트워크 fallback까지 간다. |
|
||||
| WP-RR-01 | Medium | `FIXED` | `efc577d` | `focus`/`openWindow`가 NOT_APPLIED → MAYBE_APPLIED → CONFIRMED를 따르고, 늦은 effect는 정확히 한 번 관찰한다. |
|
||||
| TR-RR-08 | Medium | `FIXED` | `69cb7e3` | `tests/unit/resumable-upload-http-control-plane.test.ts` — 예외를 던지는 getter가 `TypeError`로 `createSession` 밖으로 새어 나갔다. symbol 키와 열거되지 않는 남는 필드가 키 검사를 통과했다. |
|
||||
| TR-RR-09 | Medium | `FIXED` | `fb5b449` | `tests/unit/image-cdn-runtime.test.ts` — 테스트가 서로 모순인 `private, no-store`를 성공으로 고정했었다. 이제 기록된 fail-closed 매트릭스를 적용한다. |
|
||||
| GOV-01 | Low | `FIXED` | 이 커밋 | `scripts/check-adapter-inventory.ts`가 `docs/reviews/adapters/INVENTORY.md`를 `git ls-files src/adapters`와 비교한다. 빠졌던 `src/adapters/platform/abortable-operation.ts` 행을 되살렸고, 합계는 119/119다. |
|
||||
| GOV-02 | Medium | `FIXED` | 이 커밋 | 이 절은 너무 일찍 닫은 행을, 증거가 연결된 처리 결과와 하지 않은 일을 명시한 목록으로 바꾼다. |
|
||||
|
||||
### Landed in the second pass
|
||||
### 2차 작업에서 반영한 것
|
||||
|
||||
The twelve findings the first pass did not reach are now closed on the same
|
||||
terms: a named adversarial test failed on the pre-fix source and passes on the
|
||||
landed one.
|
||||
1차 작업이 닿지 못한 발견 12건도 이제 같은 조건으로 닫았다. 이름을 밝힌 적대적 테스트가 수정 전 소스에서 실패하고, 반영된 소스에서 통과한다.
|
||||
|
||||
| ID | Severity | Commit | Red-then-green evidence |
|
||||
| ID | 심각도 | 커밋 | 실패→통과 증거 |
|
||||
| --- | --- | --- | --- |
|
||||
| RPC-RR-01 | High | `a7390e3` | `tests/unit/browser-rpc/browser-rpc-remediation.test.ts` — `openServerStream` returns a lease (`streamId`, `frames`, `cancel`, `waitClosed`) decoded from own data descriptors. A timed-out stream is cancelled exactly once, a second stream for the same operation is refused as `CONFLICT` / `RPC_STREAM_DRAINING` without reaching the transport, and admission resumes only after `waitClosed()` settles. |
|
||||
| RT-RR-01 | High | `c0f53d1` | `tests/unit/realtime/stream-coordinator.test.ts` — a `close()` during a running apply reported success before the fix; tasks are now registered at invocation, so it reports `IDLE_TIMEOUT` and `DRAINING`. |
|
||||
| RT-RR-02 | High | `c0f53d1` | Same suite — a queued event started running inside DRAINING, and a timed-out effect left its resume token in place. The queued event is now dropped as `CLOSED` at execution time and the token is discarded with `freshness: UNKNOWN`. |
|
||||
| RT-RR-03 | Medium | `c0f53d1` | `tests/unit/realtime/live-poll-handoff-coordinator.test.ts` — a second `close()` replayed the cached timeout forever; only an in-flight close is shared now, fenced writers are retained until their tails settle, and a later close converges to success. |
|
||||
| RT-RR-04 | High | `c0f53d1` | Same suite — `close()` reported quiescence while a checkpoint was still running; checkpoint work now joins the physical-task registry. |
|
||||
| TR-RR-05 | High | `46e067e` | `tests/unit/abortable-operation.test.ts` — a rejection was reported as `TERMINAL/CLOSED` while `terminal()` said no owner, and a throwing scheduler released the caller listener leaving no owner at all, so later aborts were invisible. The primitive now distinguishes `REJECTED`, agrees with `terminal()`, snapshots the scheduler, closes atomically on install failure and compensates a late value exactly once. Both presigned subsystems migrated onto it, replacing two hand-written copies. |
|
||||
| TR-RR-01 | High | `46e067e` | `tests/unit/presigned-transfer.test.ts` — `close()` released bookkeeping without aborting, and the consumer signal joined only after the fetch began. Both are fixed; the scheduler-failure test now pins fail-closed. |
|
||||
| TR-RR-02 | High | `46e067e` | The upload scope is created before the digest and the digest races the caller and deadline; the vault claim and network call follow an owner re-check. |
|
||||
| TR-RR-03 | High | `46e067e` | Same suite — the registration is a versioned exact union: unknown/missing protocol version, plaintext target, ambient credential and cookie headers, a non-2xx expected status and any extra own field are each refused at the issuer seam. |
|
||||
| TR-RR-04 | Medium | `5a76f95` | Same suite — the presigned source was never closed on success, writer failure or abort; a holder now closes it exactly once at the outermost boundary on all three. |
|
||||
| TR-RR-06 | High | `5a76f95` | `tests/unit/resumable-upload-runtime.test.ts` — a never-granting mutation lock made `dispose()` unbounded; it is now bounded by `cleanupDeadlineMs`, returns the drain result, and leaves the runtime `CLOSING` with the checkpoint store open when the drain is unproved. |
|
||||
| TR-RR-07 | High | `5a76f95` | `tests/unit/image-cdn-runtime.test.ts` — after an abort a new verification was admitted while the abandoned verifier still ran; the slot is now held until the raw verifier settles. |
|
||||
| RPC-RR-01 | High | `a7390e3` | `tests/unit/browser-rpc/browser-rpc-remediation.test.ts` — `openServerStream`이 자기 data descriptor에서 디코딩한 lease(`streamId`, `frames`, `cancel`, `waitClosed`)를 돌려준다. 시간이 다 된 stream은 정확히 한 번 취소한다. 같은 작업의 두 번째 stream은 transport에 닿기 전에 `CONFLICT` / `RPC_STREAM_DRAINING`으로 거부한다. 새 stream 받기는 `waitClosed()`가 끝난 뒤에만 다시 연다. |
|
||||
| RT-RR-01 | High | `c0f53d1` | `tests/unit/realtime/stream-coordinator.test.ts` — 수정 전에는 apply가 도는 중에 부른 `close()`가 성공을 보고했다. 이제 작업을 호출 시점에 등록하므로 `IDLE_TIMEOUT`과 `DRAINING`을 보고한다. |
|
||||
| RT-RR-02 | High | `c0f53d1` | 같은 테스트 파일 — 대기열의 event가 DRAINING 안에서 실행을 시작했고, 시간이 다 된 effect가 resume token을 그대로 남겼다. 이제 대기열의 event는 실행 시점에 `CLOSED`로 버리고, token은 `freshness: UNKNOWN`과 함께 폐기한다. |
|
||||
| RT-RR-03 | Medium | `c0f53d1` | `tests/unit/realtime/live-poll-handoff-coordinator.test.ts` — 두 번째 `close()`가 캐시된 timeout을 끝없이 되풀이했다. 이제 진행 중인 close만 공유한다. fence된 writer는 남은 작업이 끝날 때까지 붙잡아 두고, 나중의 close는 결국 성공으로 수렴한다. |
|
||||
| RT-RR-04 | High | `c0f53d1` | 같은 테스트 파일 — checkpoint가 아직 도는데 `close()`가 작업이 멈췄다(quiescence)고 보고했다. 이제 checkpoint 작업도 physical-task registry에 들어간다. |
|
||||
| TR-RR-05 | High | `46e067e` | `tests/unit/abortable-operation.test.ts` — `terminal()`은 owner가 없다고 하는데 rejection을 `TERMINAL/CLOSED`로 보고했다. 예외를 던지는 scheduler가 호출자 listener를 풀어 owner가 아예 없어졌고, 그래서 뒤이은 abort가 보이지 않았다. 이제 이 primitive는 `REJECTED`를 구분하고, `terminal()`과 일치하며, scheduler를 snapshot하고, 설치에 실패하면 원자적으로 닫고, 늦은 값을 정확히 한 번 보상한다. presigned 하위 시스템 둘이 다 이 primitive로 옮겨, 손으로 쓴 사본 두 개를 대신했다. |
|
||||
| TR-RR-01 | High | `46e067e` | `tests/unit/presigned-transfer.test.ts` — `close()`가 abort 없이 내부 기록만 풀었고, consumer signal은 fetch가 시작된 뒤에야 합류했다. 둘 다 고쳤다. scheduler 실패 테스트는 이제 fail-closed를 고정한다. |
|
||||
| TR-RR-02 | High | `46e067e` | upload scope를 digest 전에 만들고, digest는 호출자·deadline과 경주한다. vault claim과 네트워크 호출은 owner를 다시 확인한 뒤에 한다. |
|
||||
| TR-RR-03 | High | `46e067e` | 같은 테스트 파일 — 등록 값은 버전이 붙은 exact union이다. 모르는/없는 protocol 버전, 평문 target, ambient credential과 cookie 헤더, 2xx가 아닌 기대 status, 남는 own 필드는 각각 issuer 경계에서 거부한다. |
|
||||
| TR-RR-04 | Medium | `5a76f95` | 같은 테스트 파일 — presigned source를 성공, writer 실패, abort 어느 때도 닫지 않았다. 이제 holder가 세 경우 각각 가장 바깥 경계에서 정확히 한 번 닫는다. |
|
||||
| TR-RR-06 | High | `5a76f95` | `tests/unit/resumable-upload-runtime.test.ts` — 끝내 lock을 주지 않는 mutation lock 때문에 `dispose()`에 끝이 없었다. 이제 `cleanupDeadlineMs`로 제한하고, drain 결과를 돌려주며, drain이 증명되지 않으면 checkpoint store를 연 채로 runtime을 `CLOSING`에 둔다. |
|
||||
| TR-RR-07 | High | `5a76f95` | `tests/unit/image-cdn-runtime.test.ts` — abort 뒤에, 버린 verifier가 아직 도는데 새 검증을 받아들였다. 이제 원래 verifier가 끝날 때까지 자리를 붙잡아 둔다. |
|
||||
|
||||
**No second re-review row remains `NOT_STARTED`**, and the
|
||||
structural gate for the shared `abortable-operation` primitive is now active —
|
||||
it was withheld until the primitive actually had production importers, because a
|
||||
gate that fails CI for a documented but unfixed defect reports the wrong thing.
|
||||
**두 번째 재검토의 행 가운데 `NOT_STARTED`로 남은 것은 없다.** 공유 `abortable-operation` primitive의 구조 게이트도 이제 켜져 있다. primitive를 실제로 import하는 production 코드가 생길 때까지 이 게이트를 미뤘다. 문서에 적혔지만 아직 고치지 않은 결함으로 CI를 실패시키는 게이트는 잘못된 것을 보고하기 때문이다.
|
||||
|
||||
Contracts that changed shape, and are therefore breaking for an external
|
||||
implementor:
|
||||
모양이 바뀌어서 외부 구현자에게는 호환이 깨지는 계약:
|
||||
|
||||
| Contract | Change | Reason |
|
||||
| 계약 | 변경 | 이유 |
|
||||
| --- | --- | --- |
|
||||
| `BrowserRpcTransport.openServerStream` | returns `BrowserRpcServerStreamLease` instead of `AsyncIterable` | RPC-RR-01 needs cancellation and closure evidence |
|
||||
| `AuthSessionPort.recover` | accepts an optional `CredentialOperationContext` | LEG-01; optional for one release |
|
||||
| `PresignedCapabilityRegistration` | gains `protocol` | TR-RR-03 versioned exact union |
|
||||
| `ResumableUploadRuntime.dispose` | returns `BrowserDataResult<void>` | TR-RR-06 bounded drain result |
|
||||
| `ResumableUploadRuntimePolicy` | gains `cleanupDeadlineMs` | TR-RR-06 teardown bound |
|
||||
| `ImageCdnPresentationPort.resolve` | `signal` required | BT-IMG-01, landed earlier |
|
||||
| `BrowserRpcTransport.openServerStream` | `AsyncIterable` 대신 `BrowserRpcServerStreamLease`를 돌려준다 | RPC-RR-01에 취소와 닫힘 증거가 필요하다 |
|
||||
| `AuthSessionPort.recover` | 선택 인자 `CredentialOperationContext`를 받는다 | LEG-01. 한 release 동안은 선택이다 |
|
||||
| `PresignedCapabilityRegistration` | `protocol`이 생긴다 | TR-RR-03 버전 붙은 exact union |
|
||||
| `ResumableUploadRuntime.dispose` | `BrowserDataResult<void>`를 돌려준다 | TR-RR-06 제한된 drain 결과 |
|
||||
| `ResumableUploadRuntimePolicy` | `cleanupDeadlineMs`가 생긴다 | TR-RR-06 teardown 한도 |
|
||||
| `ImageCdnPresentationPort.resolve` | `signal` 필수 | BT-IMG-01, 먼저 반영 |
|
||||
|
||||
### Gates after this pass
|
||||
### 이 작업 뒤 게이트
|
||||
|
||||
Run on the landed tree. Only what actually passed is claimed as passing.
|
||||
반영된 트리에서 돌렸다. 실제로 통과한 것만 통과로 적는다.
|
||||
|
||||
| Command | Exit | Result |
|
||||
| 명령 | 종료 | 결과 |
|
||||
| --- | ---: | --- |
|
||||
| `corepack pnpm check:types` | 0 | all six projects |
|
||||
| `corepack pnpm lint` | 0 | `--max-warnings=0` clean |
|
||||
| `corepack pnpm check:architecture` | 0 | 289 modules, 868 dependencies; 12 fixtures PASS |
|
||||
| `corepack pnpm check:adapter-inventory` | 0 | 119 files, 7 shared asset extensions, fixture linking, primitive importers |
|
||||
| `corepack pnpm check:registries` | 0 | 11 registries PASS |
|
||||
| `corepack pnpm check:diagnostics` | 0 | 8 diagnostics / 5 telemetry producers |
|
||||
| `corepack pnpm check:browser-file-storage-boundaries` | 0 | PASS, 34 rejections |
|
||||
| `corepack pnpm check:types` | 0 | 여섯 프로젝트 모두 |
|
||||
| `corepack pnpm lint` | 0 | `--max-warnings=0`로 경고 없음 |
|
||||
| `corepack pnpm check:architecture` | 0 | 모듈 289개, 의존 868개. fixture 12개 PASS |
|
||||
| `corepack pnpm check:adapter-inventory` | 0 | 파일 119개, 공유 asset 확장자 7개, fixture 연결, primitive importer |
|
||||
| `corepack pnpm check:registries` | 0 | registry 11개 PASS |
|
||||
| `corepack pnpm check:diagnostics` | 0 | diagnostic 8개 / telemetry producer 5개 |
|
||||
| `corepack pnpm check:browser-file-storage-boundaries` | 0 | PASS, 거부 34건 |
|
||||
| `corepack pnpm check:realtime-boundaries` | 0 | PASS |
|
||||
| `corepack pnpm verify:documentation` | 0 | PASS_SCOPED |
|
||||
| `git diff --check` | 0 | clean |
|
||||
| `tests/unit` + `tests/integration`, no exclusions | — | 1643 passed / 1747; the 104 failures are the four environmental files below |
|
||||
| `corepack pnpm test:component` | 0 | 126 passed |
|
||||
| `corepack pnpm test:recipes` | 0 | 17 passed |
|
||||
| 참조 샘플 기능 시험(그 script는 2026-11-07 샘플과 함께 지웠다) | 0 | 26 passed |
|
||||
| `git diff --check` | 0 | 문제 없음 |
|
||||
| `tests/unit` + `tests/integration`, 제외 없음 | — | 1643개 통과 / 1747개. 실패 104개는 아래 환경 탓 파일 네 개에서 나온다 |
|
||||
| `corepack pnpm test:component` | 0 | 126개 통과 |
|
||||
| `corepack pnpm test:recipes` | 0 | 17개 통과 |
|
||||
| 참조 샘플 기능 시험(그 script는 2026-11-07 샘플과 함께 지웠다) | 0 | 26개 통과 |
|
||||
|
||||
### Environmental failures, not claimed as green
|
||||
### 통과로 주장하지 않는 환경 실패
|
||||
|
||||
| Gate | Status | Attribution |
|
||||
| 게이트 | 상태 | 원인 |
|
||||
| --- | --- | --- |
|
||||
| tests/unit/ci-workflow-generation.test.ts | 82 failed / 325 passed | Identical on the pre-change baseline (`git stash` comparison). The subprocess gates it spawns cannot run in this sandbox. |
|
||||
| `tests/system/ci-runner/ci-artifact-contract.test.ts` | fails | Unchanged pre-existing sandbox, cgroup and `/tmp` permission behaviour. |
|
||||
| `tests/unit/security-followup.test.ts`, `tests/integration/provider-guardian-transaction.test.ts`, `tests/unit/risk-coverage.test.ts` | flaky under full-suite load | Historical baseline result. All three passed in a fresh process (78 passed together). |
|
||||
| tests/unit/ci-workflow-generation.test.ts | 82개 실패 / 325개 통과 | 변경 전 기준에서도 같다(`git stash` 비교). 이 파일이 띄우는 하위 프로세스 게이트는 이 sandbox에서 돌 수 없다. |
|
||||
| `tests/system/ci-runner/ci-artifact-contract.test.ts` | 실패 | 원래 있던 그대로의 sandbox, cgroup, `/tmp` 권한 동작이다. |
|
||||
| `tests/unit/security-followup.test.ts`, `tests/integration/provider-guardian-transaction.test.ts`, `tests/unit/risk-coverage.test.ts` | 전체 실행 부하에서 불안정(flaky) | 과거 기준 결과다. 셋 다 새 프로세스에서 통과했다(함께 돌려 78개 통과). |
|
||||
|
||||
> Current classification update (2026-09-18): the provider guardian transaction
|
||||
> suite moved to `tests/integration/provider-guardian-transaction.test.ts`.
|
||||
> It spawns child processes and exercises filesystem/IPC/process lifecycle, so it
|
||||
> is not part of the pure unit pool. Its READY/PUBLISHED wait uses a dedicated
|
||||
> test watchdog rather than treating a 1-second scheduler delay as a production
|
||||
> protocol deadline.
|
||||
> 현재 분류 갱신(2026-09-18): provider guardian transaction 테스트 파일은 `tests/integration/provider-guardian-transaction.test.ts`로 옮겼다.
|
||||
> 이 파일은 자식 프로세스를 띄우고 파일 시스템/IPC/프로세스 lifecycle을 다룬다. 그래서 순수 unit 묶음에 넣지 않는다.
|
||||
> READY/PUBLISHED 대기에는 전용 테스트 watchdog을 쓴다. 1초 scheduler 지연을 production 프로토콜 deadline으로 보지 않는다.
|
||||
|
||||
### Destructive fixture hazard — fixed
|
||||
### 파괴적인 fixture 위험 — 고침
|
||||
|
||||
Outside the 38 findings, and found while running the suites for them.
|
||||
발견 38건 밖의 일이고, 그 발견을 위한 테스트를 돌리다가 찾았다.
|
||||
|
||||
Four sites linked the repository's installed dependencies into a throwaway
|
||||
fixture with a single directory symlink at `<fixture>/node_modules`:
|
||||
네 곳이 저장소에 설치된 의존성을 쓰고 버릴 fixture에 연결할 때, `<fixture>/node_modules`에 디렉터리 symlink 하나를 썼다:
|
||||
|
||||
- `scripts/lib/removal-fixture.ts`
|
||||
- `scripts/check-supply-chain-provider-fixtures.ts`
|
||||
- `tests/integration/security-followup-archive.test.ts`
|
||||
- `tests/system/ci-runner/ci-artifact-contract.test.ts`
|
||||
|
||||
Each fixture then runs `pnpm` inside itself. pnpm does not recognise the modules
|
||||
directory it finds there and purges it; with `CI=true` it does so without a
|
||||
prompt. The purge followed the symlink and deleted the **repository's own**
|
||||
`node_modules` mid-run — a test suite uninstalling the workspace it was running
|
||||
in. That is what produced the cascading, file-unrelated failures a full
|
||||
`test:unit` run reported, and it happened twice during this work.
|
||||
그다음 각 fixture는 자기 안에서 `pnpm`을 돌린다. pnpm은 거기서 찾은 modules 디렉터리를 알아보지 못하고 지운다. `CI=true`이면 묻지도 않고 지운다. 이 삭제가 symlink를 따라가 실행 도중 **저장소 자신의** `node_modules`를 지웠다. 테스트가 자기가 돌고 있는 workspace를 언인스톨한 셈이다. 전체 `test:unit` 실행이 보고한, 파일과 관계없이 줄줄이 이어진 실패가 여기서 나왔다. 이 작업 중에 두 번 일어났다.
|
||||
|
||||
`scripts/lib/fixture-node-modules.ts` replaces all four: `node_modules` is a
|
||||
real directory whose entries are individual symlinks, so a recursive delete
|
||||
unlinks the fixture's own links instead of walking through one link into the
|
||||
shared tree. `tests/unit/fixture-node-modules.test.ts` performs the exact
|
||||
recursive delete pnpm performs and asserts the source tree survives, and
|
||||
`corepack pnpm check:adapter-inventory` fails on any reintroduction of the
|
||||
directory-symlink form.
|
||||
`scripts/lib/fixture-node-modules.ts`가 네 곳을 다 대신한다. `node_modules`는 진짜 디렉터리이고, 그 안의 항목이 각각 symlink다. 그래서 재귀 삭제는 링크 하나를 타고 공유 트리로 들어가지 않고, fixture 자신의 링크만 끊는다. `tests/unit/fixture-node-modules.test.ts`는 pnpm이 하는 재귀 삭제를 그대로 해 보고 원본 트리가 살아남는지 확인한다. `corepack pnpm check:adapter-inventory`는 디렉터리 symlink 방식이 다시 들어오면 실패한다.
|
||||
|
||||
After the fix a full `tests/unit` + `tests/integration` run leaves the
|
||||
dependencies intact and its failures are confined to the two environmental
|
||||
files above plus the two flaky-under-load ones:
|
||||
고친 뒤에는 전체 `tests/unit` + `tests/integration` 실행이 의존성을 그대로 둔다. 실패는 위의 환경 탓 파일 두 개와, 부하에서 불안정한 파일 두 개로 좁혀진다:
|
||||
|
||||
| File | Failed | Attribution |
|
||||
| 파일 | 실패 | 원인 |
|
||||
| --- | ---: | --- |
|
||||
| tests/unit/ci-workflow-generation.test.ts | 82 | Identical on the pre-change baseline (`git stash` comparison). Its subprocess gates cannot run in this sandbox. |
|
||||
| `tests/system/ci-runner/ci-artifact-contract.test.ts` | 19 | Unchanged pre-existing sandbox, cgroup and `/tmp` permission behaviour. |
|
||||
| `tests/unit/security-followup.test.ts` | 2 | Passes in isolation. |
|
||||
| `tests/integration/provider-guardian-transaction.test.ts` | 1 | Historical baseline: passed in isolation; current suite is classified as process integration. |
|
||||
| tests/unit/ci-workflow-generation.test.ts | 82 | 변경 전 기준에서도 같다(`git stash` 비교). 이 파일의 하위 프로세스 게이트는 이 sandbox에서 돌 수 없다. |
|
||||
| `tests/system/ci-runner/ci-artifact-contract.test.ts` | 19 | 원래 있던 그대로의 sandbox, cgroup, `/tmp` 권한 동작이다. |
|
||||
| `tests/unit/security-followup.test.ts` | 2 | 따로 돌리면 통과한다. |
|
||||
| `tests/integration/provider-guardian-transaction.test.ts` | 1 | 과거 기준: 따로 돌리면 통과했다. 지금은 프로세스 integration 테스트로 분류한다. |
|
||||
|
||||
1619 passed / 1723 total, and tests/unit/removal-fixture.test.ts,
|
||||
`tests/unit/supply-chain.test.ts` and
|
||||
`tests/integration/security-followup-archive.test.ts` — the three that had to be
|
||||
excluded before — now pass in the full run.
|
||||
전체 1723개 중 1619개 통과다. 전에는 빼야 했던 세 파일 tests/unit/removal-fixture.test.ts,
|
||||
`tests/unit/supply-chain.test.ts`,
|
||||
`tests/integration/security-followup-archive.test.ts`도 이제 전체 실행에서 통과한다.
|
||||
|
||||
## Third re-review (2026-08-14)
|
||||
## 세 번째 재검토 (2026-08-14)
|
||||
|
||||
A third read-only re-review re-tested all 38 rows above against hostile,
|
||||
non-cooperative, late-completing and mutable inputs. It confirmed 18 as fixed
|
||||
and found 20 that held only on the paths their tests exercised, plus three new
|
||||
findings and three governance defects. The common shape was the same in almost
|
||||
every case: a value was **checked and then read again**, or a wrapper settled
|
||||
and was mistaken for the physical work it was bounding.
|
||||
읽기만 하는 세 번째 재검토가 위의 38행 전체를 적대적이고, 협조하지 않고, 늦게 끝나고, 값이 바뀌는 입력으로 다시 시험했다. 18건은 고쳐졌다고 확인했다. 20건은 테스트가 거친 경로에서만 성립했다. 새 발견 3건과 거버넌스(governance) 결함 3건도 찾았다. 거의 모든 경우에 모양이 같았다. 값을 **확인한 뒤 다시 읽었거나**, wrapper가 끝난 것을 그 wrapper가 제한하던 실제 작업이 끝난 것으로 착각했다.
|
||||
|
||||
`docs/operations/adapter-remediation-dispositions.json` is the machine-readable
|
||||
record; `corepack pnpm check:remediation-ledger` joins it against this document,
|
||||
verifies every named evidence path exists, and refuses a blanket closure
|
||||
sentence while any row is still open. **GOV-03.** The previous section claimed
|
||||
"All 38 are now FIXED" while six rows were reproducibly partial — a sentence is
|
||||
cheap and a reviewer reads it as evidence, so the claim is now derived rather
|
||||
than authored.
|
||||
`docs/operations/adapter-remediation-dispositions.json`이 기계가 읽는 기록이다. `corepack pnpm check:remediation-ledger`는 그 파일을 이 문서와 맞대어 보고, 적힌 증거 경로가 다 있는지 확인한다. 아직 열린 행이 하나라도 있으면 일괄 종료를 선언하는 문장을 거부한다. **GOV-03.** 앞 절은 여섯 행이 재현 가능하게 부분 수정이었는데도 "All 38 are now FIXED"라고 적었다. 문장은 쓰기 쉽고, 리뷰어는 그 문장을 증거로 읽는다. 그래서 이제 그 주장을 사람이 쓰지 않고 기록에서 끌어낸다.
|
||||
|
||||
### Landed
|
||||
### 반영한 것
|
||||
|
||||
| ID | Prior verdict | Disposition | Red-then-green evidence |
|
||||
| ID | 이전 판정 | 처리 | 실패→통과 증거 |
|
||||
| --- | --- | --- | --- |
|
||||
| NS-01 | `PARTIAL` | `FIXED` | `tests/integration/http-execution-v3-live-authority.test.ts` — a throwing `kind` getter escaped the auth boundary and an auth outage was reported as `NETWORK_FAILURE`; nine hostile credential shapes now close as `AUTH_INTEGRATION_FAILURE` with zero fetches, and each field is read exactly once. |
|
||||
| NS-02 | `PARTIAL` | `FIXED` | `tests/unit/contract-registry-immutability.test.ts` — a policy that answered `10_000` to validation and `999_999` to the copy installed the second value; composition now snapshots first, so the out-of-ceiling value is refused. |
|
||||
| NS-03 | `PARTIAL` | `FIXED` | `tests/integration/http-execution-v3-live-authority.test.ts` — a `NONE` probe left `body.locked === true` after a deadline; the reader is now cancelled once and its lock released. |
|
||||
| NS-04 | `PARTIAL` | `FIXED` | `tests/unit/opfs-byte-store.test.ts` — a failed `journal.complete` still returned plain success with `SUCCEEDED` telemetry; it now returns a `RECONCILE` failure and leaves the row `COMMITTED`, and an unfinished delete is observed `DEGRADED`. |
|
||||
| NS-05 | `PARTIAL` | `FIXED` | `tests/unit/opfs-worker-runtime.test.ts` — a bootstrap failure answered every request with kind `CAPABILITIES`, so the gateway replaced `BLOCKED` with `UNSUPPORTED`; all twelve kinds now round-trip their own correlation. |
|
||||
| NS-06 | `PARTIAL` | `FIXED` | Same suite — a throwing `requestId` getter produced an RPC timeout and a stateful trap left the public promise pending forever; replies are decoded before the pending row is released and an uncorrelatable reply fails the channel closed. |
|
||||
| NS-07 | `NEW` | `FIXED` | `tests/unit/cursor-pagination-runtime.test.ts` — raising `maxPages` after construction widened a validated cap from one page to three; caps and collaborators are captured once. |
|
||||
| NS-08 | `NEW` | `FIXED` | `tests/unit/public-response-cache.test.ts` — a non-cooperative fetch held the mutation lock forever, and a digest finishing after the abort still wrote the asset and the activation marker; one terminal owner now covers the whole staging body. |
|
||||
| RPC-01 | `PARTIAL` | `FIXED` | `tests/unit/browser-rpc/browser-rpc-remediation.test.ts` — a rejecting, throwing or non-promise `waitClosed()` was absorbed into success and a second physical stream opened; only a fulfilled contract-shaped receipt prunes the registration. |
|
||||
| RPC-02 | `PARTIAL` | `FIXED` | Same suite — a throwing iterator `return` accessor replaced the selected timeout with a native `TypeError`, and the exported lease decoder threw on a hostile `Symbol.asyncIterator`. |
|
||||
| RPC-03 | `PARTIAL` | `FIXED` | Same suite — a registry accessor ran twice during validation and rows hiding fields behind a prototype or a non-enumerable key installed; every registry is snapshotted before validation. |
|
||||
| RPC-04 | `PARTIAL` | `FIXED` | Same suite — own `{ok,message,encodedBytes}` plus a prototype `injected` was a success, and a missing `message` reached a permissive schema as `undefined`. |
|
||||
| RT-01 | `PARTIAL` | `FIXED` | `tests/unit/realtime/stream-coordinator.test.ts` — an authority that re-entered `close()` from inside its own invocation got `{ok:true}` while its effect was pending; the task is registered before the collaborator is called. |
|
||||
| RT-02 | `NEW` | `FIXED` | Same suite — a throwing `scheduleTimeout` started a recovery that overlapped the running apply and made `close()` reject with a native `TypeError`; an uninstallable deadline now fails closed inside the result contract. |
|
||||
| TR-01 | `PARTIAL` | `FIXED` | `tests/unit/presigned-transfer.test.ts` — a stateful issuer could show an allowed header set to the forbidden-header check and store `Authorization`; the registration and everything nested in it is snapshotted before validation. |
|
||||
| TR-02 | `PARTIAL` | `FIXED` | `tests/unit/presigned-transfer-delivery.test.ts` — a source lease that resolved after an abort was never closed; a compensator sharing the holder's close-once latch closes it exactly once. |
|
||||
| TR-03 | `PARTIAL` | `FIXED` | `tests/unit/abortable-operation.test.ts`, `tests/unit/image-cdn-browser-probe.test.ts`, `tests/unit/resumable-upload-fetch-transport.test.ts` — the outcome depended on a hard-coded four-microtask drain, and a throwing scheduler rejected `probe()`/`execute()` natively while leaking a caller listener. The primitive now settles once by observation order, and all four consumers use it with construction-time bound timer snapshots. |
|
||||
| TR-04 | `PARTIAL` | `FIXED` | `tests/unit/resumable-upload-runtime-teardown.test.ts` — a provider outliving its attempt deadline let `dispose()` report a drained runtime and close the checkpoint store; raw provider work is now its own registry and both must be quiescent. |
|
||||
| TR-05 | `PARTIAL` | `FIXED` | `tests/unit/resumable-upload-http-control-plane.test.ts` — a stateful `sessionId` passed the regex and returned `../../unsafe`; the decoder validates an owned snapshot read exactly once. |
|
||||
| SW-01 | `PARTIAL` | `FIXED` | `tests/unit/service-worker-runtime.test.ts` — a single 1 MiB chunk was retained before the 257-byte ceiling was compared, a declared oversize left the body open and the reader lock was never released. |
|
||||
| SW-02 | `PARTIAL` | `FIXED` | `tests/unit/service-worker-web-push-remediation.test.ts` — the generator emitted `/assets/bad@name-abcdefgh.js` and the decoder then refused the manifest it had just produced; both share one canonical path predicate and the generator self-validates its output. |
|
||||
| WP-01 | `PARTIAL` | `FIXED` | `tests/unit/web-push-worker-runtime.test.ts` — an ordinary click was counted twice, a late rejection downgraded `MAYBE_APPLIED` to `NOT_APPLIED`, and the late observation ran outside `waitUntil`. |
|
||||
| GOV-03 | `OPEN` | `FIXED` | `scripts/check-remediation-ledger.ts` — dispositions and evidence paths are machine-readable and a blanket closure sentence is blocked while any row is open. |
|
||||
| GOV-04 | `OPEN` | `FIXED` | `scripts/check-adapter-inventory.ts` — the gate passed on any single importer; it now requires the four named consumers to resolve their import to the shared primitive and prints the exact set. |
|
||||
| GOV-05 | `OPEN` | `FIXED` | `config/recipes/frontend-capability-recipes.json` — see the budget note below. |
|
||||
| NS-01 | `PARTIAL` | `FIXED` | `tests/integration/http-execution-v3-live-authority.test.ts` — 예외를 던지는 `kind` getter가 인증 경계를 빠져나갔고, 인증 장애를 `NETWORK_FAILURE`로 보고했다. 이제 적대적인 credential 모양 9가지가 fetch 0회로 `AUTH_INTEGRATION_FAILURE`로 닫히고, 각 필드는 정확히 한 번만 읽는다. |
|
||||
| NS-02 | `PARTIAL` | `FIXED` | `tests/unit/contract-registry-immutability.test.ts` — 검증에는 `10_000`, 복사에는 `999_999`를 답한 정책이 두 번째 값으로 설치됐다. 이제 조립 단계가 먼저 snapshot하므로 상한을 넘는 값은 거부한다. |
|
||||
| NS-03 | `PARTIAL` | `FIXED` | `tests/integration/http-execution-v3-live-authority.test.ts` — `NONE` probe가 deadline 뒤에 `body.locked === true`를 남겼다. 이제 reader를 한 번 취소하고 lock을 푼다. |
|
||||
| NS-04 | `PARTIAL` | `FIXED` | `tests/unit/opfs-byte-store.test.ts` — 실패한 `journal.complete`가 여전히 `SUCCEEDED` telemetry와 함께 단순 성공을 돌려줬다. 이제 `RECONCILE` 실패를 돌려주고 그 journal 행을 `COMMITTED`로 두며, 끝나지 않은 삭제는 `DEGRADED`로 관찰한다. |
|
||||
| NS-05 | `PARTIAL` | `FIXED` | `tests/unit/opfs-worker-runtime.test.ts` — bootstrap 실패가 모든 요청에 kind `CAPABILITIES`로 답해서, gateway가 `BLOCKED`를 `UNSUPPORTED`로 바꿨다. 이제 kind 12가지가 다 자기 요청과의 대응(correlation)을 그대로 주고받는다. |
|
||||
| NS-06 | `PARTIAL` | `FIXED` | 같은 테스트 파일 — 예외를 던지는 `requestId` getter가 RPC timeout을 냈고, 상태를 가진 trap이 공개 promise를 영원히 pending으로 남겼다. 이제 대기 행을 풀기 전에 응답을 디코딩하고, 대응시킬 수 없는 응답이 오면 channel을 닫힌 쪽으로 실패시킨다. |
|
||||
| NS-07 | `NEW` | `FIXED` | `tests/unit/cursor-pagination-runtime.test.ts` — 생성 뒤에 `maxPages`를 올리자 검증된 상한이 1 page에서 3 page로 넓어졌다. 이제 상한과 협력 객체는 한 번만 잡는다. |
|
||||
| NS-08 | `NEW` | `FIXED` | `tests/unit/public-response-cache.test.ts` — 협조하지 않는 fetch가 mutation lock을 영원히 붙잡았고, abort 뒤에 끝난 digest가 여전히 asset과 activation marker를 썼다. 이제 terminal owner 하나가 staging 본문 전체를 맡는다. |
|
||||
| RPC-01 | `PARTIAL` | `FIXED` | `tests/unit/browser-rpc/browser-rpc-remediation.test.ts` — reject하거나, 예외를 던지거나, promise가 아닌 `waitClosed()`를 성공으로 흡수했고, 두 번째 실제 stream이 열렸다. 이제 계약 모양에 맞는 receipt가 fulfilled일 때만 등록을 정리한다. |
|
||||
| RPC-02 | `PARTIAL` | `FIXED` | 같은 테스트 파일 — 예외를 던지는 iterator `return` accessor가 선택된 timeout을 네이티브 `TypeError`로 바꿨고, export된 lease decoder가 적대적인 `Symbol.asyncIterator`에서 예외를 던졌다. |
|
||||
| RPC-03 | `PARTIAL` | `FIXED` | 같은 테스트 파일 — 검증 중에 registry accessor가 두 번 실행됐고, prototype이나 열거되지 않는 키 뒤에 필드를 숨긴 행이 설치됐다. 이제 모든 registry를 검증 전에 snapshot한다. |
|
||||
| RPC-04 | `PARTIAL` | `FIXED` | 같은 테스트 파일 — 자기 필드 `{ok,message,encodedBytes}`에 prototype의 `injected`가 더해진 값이 성공이었고, 빠진 `message`가 `undefined`로 느슨한 schema에 닿았다. |
|
||||
| RT-01 | `PARTIAL` | `FIXED` | `tests/unit/realtime/stream-coordinator.test.ts` — 자기 호출 안에서 `close()`에 다시 들어간 authority가, effect가 아직 pending인데 `{ok:true}`를 받았다. 이제 협력 객체를 부르기 전에 작업을 등록한다. |
|
||||
| RT-02 | `NEW` | `FIXED` | 같은 테스트 파일 — 예외를 던지는 `scheduleTimeout`이 도는 중인 apply와 겹치는 recovery를 시작했고, `close()`가 네이티브 `TypeError`로 reject했다. 이제 설치할 수 없는 deadline은 result 계약 안에서 fail-closed로 실패한다. |
|
||||
| TR-01 | `PARTIAL` | `FIXED` | `tests/unit/presigned-transfer.test.ts` — 상태를 가진 issuer가 금지 헤더 검사에는 허용된 헤더 집합을 보여 주고 `Authorization`을 저장할 수 있었다. 이제 등록 값과 그 안에 든 모든 것을 검증 전에 snapshot한다. |
|
||||
| TR-02 | `PARTIAL` | `FIXED` | `tests/unit/presigned-transfer-delivery.test.ts` — abort 뒤에 resolve된 source lease를 한 번도 닫지 않았다. 이제 holder의 close-once latch를 같이 쓰는 compensator가 정확히 한 번 닫는다. |
|
||||
| TR-03 | `PARTIAL` | `FIXED` | `tests/unit/abortable-operation.test.ts`, `tests/unit/image-cdn-browser-probe.test.ts`, `tests/unit/resumable-upload-fetch-transport.test.ts` — 결과가 코드에 박힌 microtask 4개 drain에 달려 있었고, 예외를 던지는 scheduler가 호출자 listener를 남긴 채 `probe()`/`execute()`를 네이티브 예외로 reject했다. 이제 primitive는 관찰 순서대로 한 번만 끝나고, 소비자 네 곳이 다 생성 시점에 묶은 timer snapshot과 함께 이 primitive를 쓴다. |
|
||||
| TR-04 | `PARTIAL` | `FIXED` | `tests/unit/resumable-upload-runtime-teardown.test.ts` — attempt deadline보다 오래 산 provider 때문에 `dispose()`가 drain이 끝난 runtime을 보고하고 checkpoint store를 닫았다. 이제 가공하지 않은 provider 작업은 따로 registry를 두고, 두 registry가 다 멈춰야 한다. |
|
||||
| TR-05 | `PARTIAL` | `FIXED` | `tests/unit/resumable-upload-http-control-plane.test.ts` — 상태를 가진 `sessionId`가 정규식을 통과한 뒤 `../../unsafe`를 돌려줬다. 이제 decoder는 정확히 한 번 읽어 둔 자기 snapshot을 검증한다. |
|
||||
| SW-01 | `PARTIAL` | `FIXED` | `tests/unit/service-worker-runtime.test.ts` — 257바이트 상한과 비교하기 전에 1 MiB chunk 하나를 통째로 붙잡았고, 크기 초과가 선언돼도 body를 연 채로 두었으며, reader lock을 끝내 풀지 않았다. |
|
||||
| SW-02 | `PARTIAL` | `FIXED` | `tests/unit/service-worker-web-push-remediation.test.ts` — generator가 `/assets/bad@name-abcdefgh.js`를 내보냈고, decoder가 방금 만든 manifest를 거부했다. 이제 둘이 canonical 경로 판정 함수 하나를 같이 쓰고, generator가 자기 출력을 스스로 검증한다. |
|
||||
| WP-01 | `PARTIAL` | `FIXED` | `tests/unit/web-push-worker-runtime.test.ts` — 평범한 click을 두 번 셌고, 늦은 rejection이 `MAYBE_APPLIED`를 `NOT_APPLIED`로 낮췄으며, 늦은 관찰이 `waitUntil` 밖에서 돌았다. |
|
||||
| GOV-03 | `OPEN` | `FIXED` | `scripts/check-remediation-ledger.ts` — 처리 결과와 증거 경로를 기계가 읽을 수 있고, 열린 행이 하나라도 있으면 일괄 종료 문장을 막는다. |
|
||||
| GOV-04 | `OPEN` | `FIXED` | `scripts/check-adapter-inventory.ts` — 게이트가 importer 하나만 있어도 통과했다. 이제 이름을 밝힌 소비자 네 곳이 import를 공유 primitive로 해석해야 하고, 정확한 집합을 출력한다. |
|
||||
| GOV-05 | `OPEN` | `FIXED` | `config/recipes/frontend-capability-recipes.json` — 아래 budget 메모를 본다. |
|
||||
|
||||
### The file-transfer bundle budget
|
||||
### file-transfer 번들 budget
|
||||
|
||||
`check:optional-recipes:source` failed at the previous baseline too (52,078 >
|
||||
52,000 gzip bytes), so it was not green before this work either. Duplicate abort
|
||||
and deadline mechanics were consolidated first: the Image probe and the Resumable
|
||||
fetch transport now use the shared `abortable-operation` primitive instead of
|
||||
their own scopes, and four decoders share `src/contracts/exact-snapshot.ts`
|
||||
rather than each carrying its own descriptor walk. The remainder is the
|
||||
correctness code the third re-review asked for — exact decoders, late-value
|
||||
compensators and physical-work registries — so the budget is reset to **54,600**
|
||||
gzip bytes against a measured **53,810**, rather than the failure being carried
|
||||
forward as if it were green.
|
||||
`check:optional-recipes:source`는 이전 기준에서도 실패했다(52,078 > 52,000 gzip 바이트). 그러니 이 작업 전에도 통과 상태가 아니었다. 먼저 중복된 abort·deadline 메커니즘을 합쳤다. Image probe와 Resumable fetch transport는 이제 자기 scope 대신 공유 `abortable-operation` primitive를 쓴다. decoder 네 개는 각자 descriptor를 훑지 않고 `src/contracts/exact-snapshot.ts`를 같이 쓴다. 남은 크기는 세 번째 재검토가 요구한 정확성 코드다. exact decoder, 늦은 값 compensator, physical-work registry가 그것이다. 그래서 실패를 통과인 척 끌고 가지 않고, budget을 측정값 **53,810**에 맞춰 **54,600** gzip 바이트로 다시 정했다.
|
||||
|
||||
The budget has since moved with later fixes. On 2026-11-03 it was set to
|
||||
**57,800** gzip bytes against a measured **56,053** (measured + 3%, rounded up
|
||||
to 100 B). The rule and the current values are in
|
||||
`docs/architecture/optional-adapter-recipes.md`.
|
||||
그 뒤 수정이 이어지면서 budget도 바뀌었다. 2026-11-03에 측정값 **56,053**에 맞춰 **57,800** gzip 바이트로 정했다(측정값 + 3%, 100 B 단위로 올림). 규칙과 지금 값은 `docs/architecture/optional-adapter-recipes.md`에 있다.
|
||||
|
||||
### Regenerated evidence (this commit)
|
||||
### 다시 만든 증거 (이 커밋)
|
||||
|
||||
| Command | Exit | Result |
|
||||
| 명령 | 종료 | 결과 |
|
||||
| --- | ---: | --- |
|
||||
| `corepack pnpm check:types` | 0 | all six projects pass |
|
||||
| `corepack pnpm check:architecture` | 0 | 290 modules, 879 dependencies; 12 fixtures PASS; allowed PASS / 9 forbidden rejected |
|
||||
| `corepack pnpm check:adapter-inventory` | 0 | 119 files; 7 shared extensions; 5 shared-abort importers listed |
|
||||
| `corepack pnpm check:optional-recipes:source` | 0 | file-transfer 53,810 / 54,600 gzip bytes |
|
||||
| `corepack pnpm exec vitest run tests/unit/browser-rpc tests/unit/realtime` | 0 | 17 files / 234 passed |
|
||||
| abortable-operation, presigned, resumable, image CDN | 0 | 7 files / 176 passed |
|
||||
| OPFS, journal, public cache, cursor | 0 | 5 files / 100 passed |
|
||||
| Service Worker + Web Push | 0 | 6 files / 79 passed |
|
||||
| `corepack pnpm exec vitest run tests/integration` | 0 | 11 files / 82 passed |
|
||||
| `corepack pnpm check:types` | 0 | 여섯 프로젝트 모두 통과 |
|
||||
| `corepack pnpm check:architecture` | 0 | 모듈 290개, 의존 879개. fixture 12개 PASS. 허용 PASS / 금지 9개 거부 |
|
||||
| `corepack pnpm check:adapter-inventory` | 0 | 파일 119개. 공유 확장자 7개. shared-abort importer 5개 나열 |
|
||||
| `corepack pnpm check:optional-recipes:source` | 0 | file-transfer 53,810 / 54,600 gzip 바이트 |
|
||||
| `corepack pnpm exec vitest run tests/unit/browser-rpc tests/unit/realtime` | 0 | 파일 17개 / 234개 통과 |
|
||||
| abortable-operation, presigned, 재개 가능 업로드, image CDN | 0 | 파일 7개 / 176개 통과 |
|
||||
| OPFS, journal, 공개 캐시, cursor | 0 | 파일 5개 / 100개 통과 |
|
||||
| Service Worker + Web Push | 0 | 파일 6개 / 79개 통과 |
|
||||
| `corepack pnpm exec vitest run tests/integration` | 0 | 파일 11개 / 82개 통과 |
|
||||
|
||||
The full `tests/unit` + `tests/integration` run is **1,845 passed / 1,864**,
|
||||
128 of 129 files green. Every one of the 19 failures is in
|
||||
`tests/system/ci-runner/ci-artifact-contract.test.ts` and is the pre-existing sandbox,
|
||||
cgroup, RLIMIT and `/tmp` permission behaviour already recorded above — the same
|
||||
file failed identically before this work. No adapter test fails.
|
||||
전체 `tests/unit` + `tests/integration` 실행은 **1,845개 통과 / 1,864개**이고, 파일 129개 중 128개가 통과했다. 실패 19건은 전부 `tests/system/ci-runner/ci-artifact-contract.test.ts`에서 나온다. 위에 이미 적은, 원래 있던 sandbox, cgroup, RLIMIT, `/tmp` 권한 동작이다. 이 작업 전에도 같은 파일이 똑같이 실패했다. 실패하는 adapter 테스트는 없다.
|
||||
|
||||
## Operational contract review (2026-08-15)
|
||||
## 운영 계약 리뷰 (2026-08-15)
|
||||
|
||||
A fourth review looked past the adapter layer at the operational contract:
|
||||
feature on/off, environment separation, folder boundaries, and which gates were
|
||||
actually green. It found five red gates and three structural gaps. Every row
|
||||
below names the defect, not the symptom.
|
||||
네 번째 리뷰는 adapter 층을 넘어 운영 계약을 봤다. feature 켜고 끄기, 환경 분리, 폴더 경계, 그리고 실제로 통과한 게이트가 무엇인지다. 실패하는 게이트 다섯과 구조 빈틈 셋을 찾았다. 아래 각 행은 증상이 아니라 결함을 적는다.
|
||||
|
||||
| id | area | disposition | what was actually wrong |
|
||||
| id | 영역 | 처리 | 실제로 잘못된 것 |
|
||||
| --- | --- | --- | --- |
|
||||
| `OPS-01` | release | `FIXED` | `public/` is copied verbatim into `dist/`, so every build — production included — shipped the local runtime document. Runtime config now comes from `config/runtime/<profile>.json`. |
|
||||
| `OPS-02` | release | `FIXED` | Release coherence proved the artifacts agreed with each other, never that they belonged in production. `FE-GATE-027` refuses an artifact whose `APP_ENV`, auth mode, endpoints or build identity do not match a declared `RELEASE_TARGET`, and refuses an undeclared target outright. |
|
||||
| `OPS-03` | runtime | `FIXED` | `REQUEST_TIMEOUT_MS` was validated and then never passed to the V3 executor; every operation ran on its contract's own deadline. It is now a ceiling that may tighten a contract, never loosen one. |
|
||||
| `OPS-04` | build | `FIXED` | `VITE_ROUTER_BASE_PATH` drove the router and the Service Worker scope but not Vite's asset `base`, so a sub-path deployment emitted root-absolute assets. One value now feeds all three. |
|
||||
| `OPS-05` | provider | `FIXED` | bubblewrap 0.9.0 drops whatever follows the option stream inside an `--args` file, so the sandboxed command was never executed: bwrap printed usage and exited 1. Options stay hidden; the command travels on real argv. |
|
||||
| `OPS-06` | provider | `FIXED` | The scope wrapper read its liveness pipe through `fs`, a blocking `read(2)` on a pipe the supervisor never closes. `process.exit` deadlocked joining that thread, so a completed provider was reported as a timeout kill. |
|
||||
| `OPS-07` | release | `FIXED` | `mkdir`/`open` modes were left to the ambient umask, so a hardened runner produced directories it could not enter and handed `tar` a file it could not re-open. |
|
||||
| `OPS-08` | release | `FIXED` | Promotion cleanup deleted this promotion's exact five through a pinned descriptor and only then noticed the leaf had been substituted, leaving a half-emptied directory a retry could not distinguish from a completed one. |
|
||||
| `OPS-09` | removability | `FIXED` | The removal fixture was not a repository, had no `.gitignore`, and each removal script kept its own copy-target list that had drifted. Supply-chain generation therefore failed inside every fixture and took the whole provider suite down with it. |
|
||||
| `OPS-10` | removability | `FIXED` | A platform integration file asserted the reference feature's route ids, so removing the feature left it importing a deleted module. The assertion moved to the feature's own test tree. |
|
||||
| `OPS-11` | removability | `FIXED` | A removal fixture runs against a deliberately reduced CI contract; the canonical exact-count tests re-imposed the full authority on it and failed the fixture for the reduction it exists to prove. |
|
||||
| `OPS-12` | browser | `FIXED` | Four browser-capability specs answered capability requests without the `protocol` field the hardened envelope requires, so every capability was refused and the download and part-upload paths asserted against an empty transcript. |
|
||||
| `OPS-13` | browser | `FIXED` | A refused capability document answered `recovery: NONE`, contradicting both the design record and the vault, which already answers `REISSUE_CAPABILITY`. |
|
||||
| `OPS-14` | performance | `FIXED` | Playwright matches accessible names by substring, so the navigation entry matched the home page's call to action too; the run died on a strict-mode violation before the first measurement and produced no evidence at all. |
|
||||
| `OPS-15` | visual | `FIXED` | The platform overview baseline predated the reference routes moving from `integration-defined` to `session-required`, so the only visual gate covering that page failed for its own staleness. |
|
||||
| `OPS-16` | architecture | `FIXED` | `src/contracts` imported `src/application` for the shared `Result` and the compatibility predicate; neither package owned the shared vocabulary. Both moved down to contracts. |
|
||||
| `OPS-17` | architecture | `FIXED` | The documented "no adapter depends on another concrete adapter" rule had no executable form, and `diagnostics` imported a guard out of `telemetry`. The guard moved to the adapter kernel and the rule is now enforced with a same-directory backreference. |
|
||||
| `OPS-18` | architecture | `PARTIAL` | Generic presentation still reads the installed-feature registries. The rule freezes the exact set of modules doing so today; a new edge fails. Lifting the assembly into `bootstrap` is not done. |
|
||||
| `OPS-19` | documentation | `FIXED` | README and the manual accessibility checklist both claimed six routes while ten were registered, leaving four screens outside the declared manual review scope. The list is now derived from the route registry by `verify:documentation`. |
|
||||
| `OPS-01` | release | `FIXED` | `public/`은 `dist/`로 그대로 복사된다. 그래서 production을 포함한 모든 빌드가 local runtime 문서를 함께 내보냈다. 이제 runtime 설정은 `config/runtime/<profile>.json`에서 온다. |
|
||||
| `OPS-02` | release | `FIXED` | release 일관성 검사는 산출물끼리 맞는지만 증명했고, 그 산출물이 production에 맞는지는 증명하지 않았다. `FE-GATE-027`은 `APP_ENV`, 인증 모드, endpoint, 빌드 식별자가 선언된 `RELEASE_TARGET`과 맞지 않는 산출물을 거부하고, 선언되지 않은 target은 아예 거부한다. |
|
||||
| `OPS-03` | runtime | `FIXED` | `REQUEST_TIMEOUT_MS`는 검증만 하고 V3 executor에 넘기지 않았다. 그래서 모든 작업이 자기 계약의 deadline으로 돌았다. 이제 이 값은 상한이다. 계약을 조일 수는 있지만 풀 수는 없다. |
|
||||
| `OPS-04` | 빌드 | `FIXED` | `VITE_ROUTER_BASE_PATH`는 router와 Service Worker scope는 정했지만 Vite의 asset `base`는 정하지 않았다. 그래서 하위 경로 배포가 root 기준 절대 경로 asset을 내보냈다. 이제 값 하나가 셋 모두에 들어간다. |
|
||||
| `OPS-05` | provider | `FIXED` | bubblewrap 0.9.0은 `--args` 파일 안에서 option stream 뒤에 오는 것을 버린다. 그래서 sandbox 안 명령이 한 번도 실행되지 않았다. bwrap은 usage를 찍고 1로 끝났다. 이제 option은 그대로 숨기고, 명령은 진짜 argv로 넘긴다. |
|
||||
| `OPS-06` | provider | `FIXED` | scope wrapper가 liveness pipe를 `fs`로 읽었다. supervisor가 끝내 닫지 않는 pipe에 대한 blocking `read(2)`다. `process.exit`이 그 thread를 join하다 교착에 빠져서, 끝난 provider를 timeout kill로 보고했다. |
|
||||
| `OPS-07` | release | `FIXED` | `mkdir`/`open` mode를 주변 umask에 맡겼다. 그래서 강화된(hardened) runner가 자기가 들어갈 수 없는 디렉터리를 만들고, 다시 열 수 없는 파일을 `tar`에 넘겼다. |
|
||||
| `OPS-08` | release | `FIXED` | promotion 정리가 고정한 descriptor로 이번 promotion의 파일 정확히 다섯 개를 지운 뒤에야 leaf가 바꿔치기된 것을 알아챘다. 그래서 절반만 빈 디렉터리가 남았고, 재시도는 그것을 끝난 디렉터리와 구별하지 못했다. |
|
||||
| `OPS-09` | 제거 가능성 | `FIXED` | 제거 fixture는 저장소가 아니었고 `.gitignore`도 없었다. 제거 스크립트마다 따로 복사 대상 목록을 들고 있었고, 그 목록들이 서로 어긋났다. 그래서 supply-chain 생성이 모든 fixture 안에서 실패했고, provider 테스트 전체를 함께 무너뜨렸다. |
|
||||
| `OPS-10` | 제거 가능성 | `FIXED` | platform integration 파일이 참조 feature의 route id를 단언했다. 그래서 그 feature를 지우면 이 파일이 지운 모듈을 import하는 상태로 남았다. 단언은 feature 자신의 테스트 트리로 옮겼다. |
|
||||
| `OPS-11` | 제거 가능성 | `FIXED` | 제거 fixture는 일부러 줄인 CI 계약으로 돈다. 정본 exact-count 테스트가 그 fixture에 전체 기준을 다시 들이대서, fixture가 증명하려고 존재하는 바로 그 축소 때문에 fixture를 실패시켰다. |
|
||||
| `OPS-12` | 브라우저 | `FIXED` | browser-capability spec 네 개가 강화된 envelope가 요구하는 `protocol` 필드 없이 capability 요청에 답했다. 그래서 모든 capability가 거부됐고, download와 part-upload 경로는 빈 기록을 두고 단언했다. |
|
||||
| `OPS-13` | 브라우저 | `FIXED` | 거부된 capability 문서가 `recovery: NONE`으로 답했다. 이는 설계 기록과도, 이미 `REISSUE_CAPABILITY`로 답하는 vault와도 어긋난다. |
|
||||
| `OPS-14` | 성능 | `FIXED` | Playwright는 accessible name을 부분 문자열로 맞춘다. 그래서 navigation 항목이 home page의 call to action 버튼과도 맞았다. 실행은 첫 측정 전에 strict-mode 위반으로 죽었고, 증거를 하나도 남기지 않았다. |
|
||||
| `OPS-15` | 시각(visual) | `FIXED` | platform overview 기준 이미지는 참조 route가 `integration-defined`에서 `session-required`로 바뀌기 전에 만든 것이었다. 그래서 그 page를 다루는 유일한 visual 게이트가 자기 기준이 낡아서 실패했다. |
|
||||
| `OPS-16` | 아키텍처 | `FIXED` | `src/contracts`가 공유 `Result`와 호환성 판정 함수를 쓰려고 `src/application`을 import했다. 어느 쪽도 공유 어휘의 owner가 아니었다. 둘 다 contracts로 내렸다. |
|
||||
| `OPS-17` | 아키텍처 | `FIXED` | 문서에 적힌 "어떤 adapter도 다른 구체 adapter에 의존하지 않는다" 규칙은 실행 가능한 형태가 없었다. 그리고 `diagnostics`가 `telemetry`에서 guard를 import했다. guard는 adapter kernel로 옮겼고, 이제 같은 디렉터리 역참조(backreference)로 규칙을 강제한다. |
|
||||
| `OPS-18` | 아키텍처 | `PARTIAL` | 범용 presentation이 아직 installed-feature registry를 읽는다. 규칙은 지금 그렇게 하는 모듈 집합을 정확히 고정한다. 새 의존 edge는 실패한다. 조립을 `bootstrap`으로 올리는 일은 하지 않았다. |
|
||||
| `OPS-19` | 문서 | `FIXED` | README와 수동 접근성 체크리스트는 둘 다 route 6개라고 했지만, 등록된 것은 10개였다. 그래서 화면 4개가 선언된 수동 리뷰 범위 밖에 있었다. 이제 `verify:documentation`이 route registry에서 목록을 끌어낸다. |
|
||||
|
||||
### Product feature selection (2026-08-15, second pass)
|
||||
### 제품 feature 선택 (2026-08-15, 2차 작업)
|
||||
|
||||
| id | disposition | what changed |
|
||||
| id | 처리 | 바뀐 것 |
|
||||
| --- | --- | --- |
|
||||
| `OPS-20` | `FIXED` | Which features a build contains is now a declared manifest rather than five registries spreading a literal. `VITE_PRODUCT_FEATURES` narrows it at build time; a test fails if a new registry forgets to consult it. |
|
||||
| `OPS-21` | `FIXED` | `FEATURE_OVERRIDES` in the runtime document takes an installed feature out of service without a rebuild. The router refuses its routes, not just the navigation, so a typed deep link cannot still mount it. |
|
||||
| `OPS-22` | `FIXED` | Both inputs are subtractive by vocabulary: the override enum has no `ENABLED`, and a build-time selection naming a feature the source tree does not declare is refused rather than ignored. |
|
||||
| `OPS-23` | `FIXED` | A sandbox that fails to launch now reports why. The supervisor consumed the child's output only to enforce a byte cap and discarded it, so a host restriction surfaced as an unexplained `exit=1`. Lines the sandbox tooling itself emits are kept; provider output is still discarded. |
|
||||
| `OPS-20` | `FIXED` | 빌드에 어떤 feature가 들어가는지를, 이제 리터럴을 퍼뜨린 registry 다섯 개가 아니라 선언된 manifest가 정한다. `VITE_PRODUCT_FEATURES`가 빌드 때 그 범위를 좁힌다. 새 registry가 이 값을 확인하지 않으면 테스트가 실패한다. |
|
||||
| `OPS-21` | `FIXED` | runtime 문서의 `FEATURE_OVERRIDES`는 다시 빌드하지 않고 설치된 feature를 서비스에서 뺀다. router는 navigation만 숨기지 않고 그 feature의 route를 거부한다. 그래서 주소를 직접 쳐서 들어온 deep link도 그 feature를 띄울 수 없다. |
|
||||
| `OPS-22` | `FIXED` | 두 입력 다 어휘부터 빼기만 할 수 있다. override enum에는 `ENABLED`가 없다. 소스 트리가 선언하지 않은 feature를 적은 빌드 시점 선택은 무시하지 않고 거부한다. |
|
||||
| `OPS-23` | `FIXED` | 실행에 실패한 sandbox가 이제 이유를 보고한다. supervisor는 바이트 상한을 지키려고만 자식 출력을 읽고 버렸다. 그래서 host 제약이 설명 없는 `exit=1`로만 드러났다. sandbox 도구가 직접 내는 줄은 남긴다. provider 출력은 여전히 버린다. |
|
||||
|
||||
An env var does **not** shrink the bundle, and the code says so. A static import
|
||||
cannot be undone by a value, and making the import graph depend on a
|
||||
configuration string is what §3.5 exists to prevent. Measured: `none` changes
|
||||
the output by 58 bytes. Physical removal is FE-GATE-020's job.
|
||||
환경 변수는 번들을 줄이지 **않는다**. 코드도 그렇게 적는다. 정적 import는 값으로 되돌릴 수 없다. import graph가 설정 문자열에 따라 달라지게 하는 것은 §3.5가 막으려는 바로 그 일이다. 측정 결과 `none`은 출력을 58바이트 바꾼다. 물리적 제거는 FE-GATE-020이 맡는다.
|
||||
|
||||
### Host restriction discovered during this pass
|
||||
### 이 작업 중에 발견한 host 제약
|
||||
|
||||
`bwrap --unshare-net` no longer works on this machine:
|
||||
이 기계에서는 `bwrap --unshare-net`이 더는 동작하지 않는다:
|
||||
|
||||
```
|
||||
$ printf '%s\0' --unshare-net --ro-bind /usr /usr ... | bwrap --args 3 -- /bin/true
|
||||
@@ -539,52 +460,31 @@ $ sysctl kernel.apparmor_restrict_unprivileged_userns
|
||||
kernel.apparmor_restrict_unprivileged_userns = 1
|
||||
```
|
||||
|
||||
That reproduction contains none of this repository's code. Earlier in the same
|
||||
session the identical sandbox ran to completion, so the restriction became
|
||||
active partway through. While it holds, 16 of the 108 provider tests cannot run
|
||||
here — they need a sandbox the kernel will not grant. They are not counted as
|
||||
green and not counted as product defects; under a host that permits the
|
||||
namespace the same file was 107/108.
|
||||
이 재현에는 이 저장소의 코드가 하나도 없다. 같은 세션 앞부분에서는 똑같은 sandbox가 끝까지 돌았다. 그러니 제약은 도중에 켜졌다. 제약이 있는 동안 provider 테스트 108개 중 16개는 여기서 돌 수 없다. kernel이 허락하지 않는 sandbox가 필요하기 때문이다. 이 테스트는 통과로도, 제품 결함으로도 세지 않는다. namespace를 허락하는 host에서는 같은 파일이 107/108이었다.
|
||||
|
||||
### Still red after this pass
|
||||
### 이 작업 뒤에도 실패하는 것
|
||||
|
||||
*applies effective aggregate cgroup limits without exposing command or
|
||||
credentials* was rewritten. It used to read the live process tree with one
|
||||
`ps` per pid and assert mid-run, which lost a race against a sandbox that now
|
||||
completes in a few hundred milliseconds; it records the tree from `/proc` every
|
||||
5ms and asserts on the recording after the run. That restructuring is also what
|
||||
revealed the host restriction above — the supervisor had been failing to launch
|
||||
the sandbox and the test was dying on the observation first.
|
||||
*applies effective aggregate cgroup limits without exposing command or credentials* 테스트를 다시 썼다. 전에는 pid마다 `ps`를 한 번씩 돌려 살아 있는 프로세스 트리를 읽고, 실행 도중에 단언했다. 이 방식은 이제 몇백 밀리초 만에 끝나는 sandbox와의 경주에서 졌다. 지금은 `/proc`에서 5ms마다 트리를 기록하고, 실행이 끝난 뒤 그 기록으로 단언한다. 위의 host 제약도 이렇게 구조를 바꾸면서 드러났다. supervisor는 그동안 sandbox를 띄우는 데 실패하고 있었는데, 테스트가 관찰 단계에서 먼저 죽었던 것이다.
|
||||
|
||||
Tests that spawn processes, build archives and sign evidence were given a
|
||||
30s budget instead of the 10s default sized for pure-JS unit tests. The default
|
||||
was not raised: that would hide a genuinely hung test.
|
||||
프로세스를 띄우고, archive를 만들고, 증거에 서명하는 테스트에는 순수 JS unit 테스트에 맞춘 기본값 10s 대신 30s budget을 줬다. 기본값은 올리지 않았다. 올리면 정말로 멈춘 테스트를 숨기게 된다.
|
||||
|
||||
### FE-GATE-020 after this pass
|
||||
### 이 작업 뒤 FE-GATE-020
|
||||
|
||||
| fixture | before | after |
|
||||
| fixture | 전 | 후 |
|
||||
| --- | ---: | ---: |
|
||||
| reference feature | failed before its first assertion | 1,612 pass / 1 fail |
|
||||
| optional recipe | 39 failures | 1,386 pass / 2 fail |
|
||||
| browser file + storage | 40 failures | 1,006 pass / 3 fail |
|
||||
| realtime | not reached | 1,159 pass / 1 fail |
|
||||
| 참조 feature | 첫 단언 전에 실패 | 1,612개 통과 / 1개 실패 |
|
||||
| 선택 recipe | 실패 39개 | 1,386개 통과 / 2개 실패 |
|
||||
| 브라우저 파일 + 스토리지 | 실패 40개 | 1,006개 통과 / 3개 실패 |
|
||||
| realtime | 도달 못 함 | 1,159개 통과 / 1개 실패 |
|
||||
|
||||
Every remaining failure is one of the three environment-limited tests above.
|
||||
남은 실패는 하나하나가 위에서 말한 환경 제약 테스트 세 개 중 하나다.
|
||||
|
||||
Lab performance now produces evidence, and that evidence shows the
|
||||
named-interaction budget missed on this machine (367–724ms against 200ms). The
|
||||
metric measures a full lazy-route navigation while the budget is an
|
||||
INP-shaped 200ms, so the two do not describe the same thing. No budget was
|
||||
changed to make this green.
|
||||
Lab 성능 측정이 이제 증거를 낸다. 그 증거는 이 기계에서 named-interaction budget을 넘었음을 보여 준다(200ms 기준에 367–724ms). 이 지표는 lazy route 이동 전체를 재는데, budget은 INP 모양의 200ms다. 그래서 둘은 같은 것을 말하지 않는다. 이를 통과로 만들려고 budget을 바꾸지 않았다.
|
||||
|
||||
WebKit remains unavailable in this environment (`libevent-2.1-7t64`,
|
||||
`libavif16` are not installed), so 14 browser-capability specs and the WebKit
|
||||
E2E project are unverified here. Chromium and Firefox are 28/28 and visual is
|
||||
5/5.
|
||||
이 환경에서는 여전히 WebKit을 쓸 수 없다(`libevent-2.1-7t64`, `libavif16`이 설치되지 않았다). 그래서 browser-capability spec 14개와 WebKit E2E project는 여기서 확인하지 못했다. Chromium과 Firefox는 28/28, visual은 5/5다.
|
||||
|
||||
## Rules for updating this ledger
|
||||
## 이 원장을 고치는 규칙
|
||||
|
||||
- A row moves out of `NOT_STARTED` only with a linked red test, its green run, and the commit id.
|
||||
- `PROMOTION_BLOCKED` rows never become `DEFECT`; they close through an authorized product
|
||||
selection change with the browser/provider evidence named in the plan.
|
||||
- Environmental gate failures are copied verbatim and are never claimed as green.
|
||||
- 행은 연결된 실패 테스트, 그 테스트의 통과 실행, 커밋 id가 있을 때만 `NOT_STARTED`에서 벗어난다.
|
||||
- `PROMOTION_BLOCKED` 행은 `DEFECT`가 되지 않는다. 승인된 제품 선택 변경과, 계획이 정한 browser/provider 증거가 있을 때 닫힌다.
|
||||
- 환경 탓 게이트 실패는 원문 그대로 옮기고, 절대 통과로 주장하지 않는다.
|
||||
|
||||
@@ -6,13 +6,13 @@
|
||||
[Backend API와 Server State contract](../architecture/backend-api-and-server-state-contract.md)
|
||||
- 기준일: 2026-07-28, 1절·5.1·6.0·6.3은 2026-09-25 V3 코드 기준으로 갱신
|
||||
- 설계:
|
||||
[API contract, Schema, Mapper와 Server State](../architecture/api-contract-schema-mapper-and-server-state.md)
|
||||
[API contract, Schema, Mapper와 Server State](../design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md)
|
||||
- browser Protobuf/gateway 설계:
|
||||
[Protobuf browser transport와 REST Gateway](../architecture/protobuf-browser-transport-and-rest-gateway.md)
|
||||
[Protobuf browser transport와 REST Gateway](../design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md)
|
||||
|
||||
## 1. 적용 범위
|
||||
|
||||
현재 reference REST → Schema → Mapper → TanStack Query vertical은 V3 contract
|
||||
현재 참조 구현(reference)의 REST → Schema → Mapper → TanStack Query 수직 흐름(vertical)은 V3 contract
|
||||
executor(`src/adapters/http/http-execution-v3.ts`)로 `COMPOSED`다. 조합 위치는
|
||||
`src/bootstrap/runtime-adapters.ts`의 `createContractHttpExecutor`다. 이 문서의
|
||||
"current v1"은 V2 client 시절에 쓴 말이다. V2 client는 2026-11-03에 지웠다.
|
||||
@@ -54,10 +54,10 @@ PromotionEvidence
|
||||
| control | current v1 | target v2 |
|
||||
| --- | --- | --- |
|
||||
| operation traffic switch | 없음 | provider/family/operation별 `TrafficAdmission` |
|
||||
| frontend containment | promotion 중지와 known-good release rollback; feature composition 변경은 재배포 필요 | atomic admission disable |
|
||||
| frontend containment | 승격(promotion) 중지와 정상으로 확인된(known-good) release로 rollback. feature 조합을 바꾸려면 재배포가 필요 | admission을 원자적으로 끄기 |
|
||||
| provider containment | actual BFF/API owner의 route/kill switch가 있을 때만 사용 | registered provider kill switch와 probe |
|
||||
| query cleanup | composed QueryClient/coordinator의 cancel·invalidate·local clear | generation fence와 profile-scoped cleanup |
|
||||
| mutation recovery | backend 상태/idempotency owner와 수동 reconcile | effect certainty + runtime/scope coordinator |
|
||||
| query cleanup | 조립된 QueryClient/coordinator의 취소·무효화·로컬 삭제 | generation fence와 profile 범위 정리 |
|
||||
| mutation recovery | backend 상태/idempotency owner와 수동으로 맞추기(reconcile) | 효과 확실성(effect certainty)과 runtime/scope coordinator |
|
||||
|
||||
따라서 current v1 incident에서 존재하지 않는 switch를 내렸다고 기록하지 않는다.
|
||||
target v2가 composed된 operation만 `TrafficAdmission`을 먼저 내린다. 그 전에는
|
||||
@@ -78,7 +78,7 @@ current v1으로의 fallback은 (1) 해당 operation의 provider/security eviden
|
||||
- semantic operation/profile/provider ID
|
||||
- protocol/semantics
|
||||
- safe failure kind
|
||||
- HTTP status group, GraphQL safe category, gRPC status bucket
|
||||
- HTTP status 그룹, GraphQL의 안전한 category, gRPC status bucket
|
||||
- logical/physical attempt, auth recovery와 deadline bucket
|
||||
- provider가 측정한 encoded transfer bucket과 browser가 측정한
|
||||
decoded/result/message/frame/page/item byte/count bucket
|
||||
@@ -139,11 +139,11 @@ artifact에서 access-controlled하게 비교한다.
|
||||
|
||||
| 증상 | 우선 확인 |
|
||||
| --- | --- |
|
||||
| 특정 release에서 전 operation 실패 | runtime config, provider endpoint, auth owner, contract set |
|
||||
| schema/mapper mismatch 급증 | backend artifact rollout, unknown/null/enum/scalar 변화, wrong codec |
|
||||
| 특정 release에서 전 operation 실패 | runtime config, provider endpoint, 인증(auth) owner, contract 묶음 |
|
||||
| schema/mapper 불일치 급증 | backend 산출물 배포(rollout), unknown/null/enum/scalar 변화, 잘못된 codec |
|
||||
| retry/traffic 폭증 | retry owner 중복, 401 loop, Retry-After, total deadline |
|
||||
| stale/wrong account data | scope generation, late result, query key collision, invalidation |
|
||||
| command duplicate/rollback 이상 | idempotency tuple, input-aware concurrency, optimistic revision |
|
||||
| 낡거나 잘못된 account 데이터 | scope generation, 늦게 온 결과, query key 충돌, 무효화(invalidation) |
|
||||
| command 중복/rollback 이상 | idempotency tuple, 입력을 고려한(input-aware) 동시성 제어, 낙관적(optimistic) revision |
|
||||
| list가 반복/무한 증가 | cursor loop/snapshot/page/item/byte ceiling |
|
||||
| provider 200인데 client 실패 | status/media/envelope/schema/mapper/body cap |
|
||||
| 로그에서 payload/ID 발견 | redaction/allowlist bypass, diagnostics producer |
|
||||
@@ -235,8 +235,8 @@ diagnostics에만 남고 `api.request.failed`에는 세지 않는다(03-07). 그
|
||||
byte cap을 확인한다.
|
||||
3. actual encoded transfer/decompression ratio cap은 BFF/proxy/CDN evidence에서
|
||||
확인한다. browser reader가 encoded bytes를 셌다고 가정하지 않는다.
|
||||
4. standard JSON parse profile이면 decoded byte는 pre-parse guard,
|
||||
depth/node/key는 post-parse admission guard인지 확인한다.
|
||||
4. 표준 JSON parse profile이면 decoded byte는 parse 전(pre-parse) guard,
|
||||
depth/node/key는 parse 뒤(post-parse) admission guard인지 확인한다.
|
||||
5. truncated, content encoding/decompression overflow와 invalid UTF-8을 구분한다.
|
||||
6. success status/media/envelope profile이 operation registry와 일치하는지 확인한다.
|
||||
7. schema unknown-field policy와 actual codec fingerprint를 확인한다.
|
||||
@@ -369,8 +369,8 @@ terminal completeness 전 staging을 complete query cache로 commit하지 않는
|
||||
확인한다. official runtime이면 runtime-owned callback/status API와
|
||||
`ClientReadableStream.cancel()` 경로를 확인하며 raw `ReadableStream` parser가
|
||||
있다고 가정하지 않는다.
|
||||
4. body trailer frame 또는 zero-body trailers-only response header 중 terminal
|
||||
status source가 정확히 하나인지 확인한다.
|
||||
4. 최종 status를 알려 주는 곳(terminal status source)이 정확히 하나인지 확인한다. 후보는
|
||||
body trailer frame과, body가 없는 trailers-only 응답의 header다.
|
||||
5. `grpc-status`가 있으면 canonical decimal `0..16`으로 exactly once인지, body
|
||||
trailer name lowercase와 rich-details outer code가 맞는지 확인하며 그 status를
|
||||
authority로 사용한다.
|
||||
@@ -380,7 +380,7 @@ terminal completeness 전 staging을 complete query cache로 commit하지 않는
|
||||
이것을 wire header로 위조하지 않고 internal normalized failure로만 사용한다.
|
||||
7. HTTP success만으로 RPC success를 기록하지 않는다. duplicate/conflicting/
|
||||
malformed terminal source는 provider incompatibility로 traffic을 닫는다.
|
||||
8. Envoy의 upstream HTTP/2, filter order, route/idle/max-stream timeout과 buffering
|
||||
8. Envoy의 upstream HTTP/2, filter 순서, route/idle/max-stream timeout과 buffering
|
||||
profile을 확인한다. default route timeout으로 long stream이 잘렸는지 확인한다.
|
||||
9. raw grpc-message/status-details를 ticket에 복사하지 않는다.
|
||||
|
||||
@@ -400,8 +400,8 @@ terminal completeness 전 staging을 complete query cache로 commit하지 않는
|
||||
3. duplicate/order/gap/resume token protocol을 확인한다.
|
||||
4. event 전달 뒤 transport-only auto replay가 없었는지 확인한다.
|
||||
5. overflow/gap/truncation에서 current aggregate를 complete success로 쓰지 않는다.
|
||||
6. finite aggregate는 valid OK terminal status/completeness 뒤 atomic cache
|
||||
commit인지 확인한다.
|
||||
6. 끝이 있는(finite) aggregate는 올바른 OK 최종 status와 완결성(completeness)을 확인한 뒤
|
||||
cache에 원자적으로 commit하는지 확인한다.
|
||||
7. actual proxy buffering/flush와 affected browser cohort를 확인한다.
|
||||
|
||||
### 8.4 Proxy/CORS
|
||||
@@ -426,8 +426,8 @@ actual proxy를 복구한다. client decoder를 느슨하게 만들어 provider
|
||||
1. exact Connect-Web package/runtime, `CONNECT | GRPC_WEB`, JSON/binary,
|
||||
POST/GET와 rpc kind row를 확인한다. content type으로 다른 protocol을 자동
|
||||
선택하지 않는다.
|
||||
2. Connect unary는 HTTP status + bounded Connect error, stream은 HTTP admission +
|
||||
exactly-one final EndStream을 각각 authority로 사용한다.
|
||||
2. Connect unary는 HTTP status와 크기 상한이 있는 Connect error를, stream은 HTTP admission과
|
||||
정확히 하나인 마지막 EndStream을 각각 authority로 사용한다.
|
||||
3. missing/early/duplicate EndStream, terminal 뒤 data, malformed/oversize
|
||||
envelope와 compression mismatch에서 call을 cancel하고 cache write를 막는다.
|
||||
4. stock runtime이 whole unary body를 읽는 profile이면 edge encoded/decompressed
|
||||
@@ -436,7 +436,7 @@ actual proxy를 복구한다. client decoder를 느슨하게 만들어 provider
|
||||
5. remaining total deadline이 0 이하면 runtime `timeoutMs=0`을 호출하지 않고
|
||||
local deadline failure로 닫는다. abort 뒤 command는 backend receipt로
|
||||
reconcile한다.
|
||||
6. GET은 descriptor `NO_SIDE_EFFECTS`, input classification, URL cap, cache key,
|
||||
6. GET은 descriptor `NO_SIDE_EFFECTS`, 입력 분류, URL 상한(cap), cache key,
|
||||
`Vary`와 credential/preflight profile이 모두 일치하는지 확인한다.
|
||||
7. raw Connect message/metadata/detail/debug를 ticket에 복사하지 않는다.
|
||||
|
||||
@@ -492,7 +492,7 @@ fallback도 old generation을 cancel한 뒤 새 logical query로만 시작한다
|
||||
|
||||
### 11.0 Current v1 available checks
|
||||
|
||||
1. Query retry off, global stale/gc, AbortSignal과 affected query의
|
||||
1. Query retry가 꺼져 있는지, 전역 stale/gc, AbortSignal과 영향받은 query의
|
||||
cancel/invalidate/local clear를 확인한다.
|
||||
2. current arbitrary key/canonicalize와 hook-local pending Promise를 관측하고
|
||||
collision/incorrect join cohort cache를 clear한다.
|
||||
@@ -523,8 +523,8 @@ fallback도 old generation을 cancel한 뒤 새 logical query로만 시작한다
|
||||
|
||||
### 11.3 Mutation ordering/rollback — target v2
|
||||
|
||||
1. 전체 validated semantic input의 runtime-private exact equality + identity
|
||||
token이 아닌 hook instance로 join/reject를 판정했는지 확인한다.
|
||||
1. join/reject를 검증된 semantic input 전체의 runtime-private 정확한 동일성(exact equality)과
|
||||
identity token이 아니라 hook instance로 판정했는지 확인한다.
|
||||
2. `JOIN_IDENTICAL | REJECT_DUPLICATE | ALLOW_INDEPENDENT` 결과와 fetch/Promise
|
||||
횟수가 profile대로인지 확인한다.
|
||||
3. runtime/scope coordinator에서 same logical key의 two-hook/out-of-order
|
||||
@@ -600,7 +600,7 @@ revoke/rotate한다. 삭제/보존은 incident response 정책을 따른다.
|
||||
- idempotency concurrent replay/unknown effect
|
||||
- cursor loop/ETag 304/412
|
||||
- GraphQL persisted miss/partial/cost
|
||||
- gRPC missing/conflicting terminal status source, corrupt frame와 stream gap
|
||||
- gRPC 최종 status source 누락·충돌, 깨진 frame과 stream gap
|
||||
- query key collision/account late result
|
||||
- optimistic concurrent rollback
|
||||
- kill switch/coherent rollback
|
||||
@@ -623,11 +623,11 @@ raw payload, URL, document, protobuf와 identifier를 evidence record에 넣지
|
||||
|
||||
## 15. 관련 문서
|
||||
|
||||
- [VD-23 API transport selection과 REST execution](../architecture/decisions/VD-23-api-transport-selection-and-rest-execution.md)
|
||||
- [VD-24 Runtime Schema와 boundary Mapper](../architecture/decisions/VD-24-runtime-schema-and-boundary-mapper.md)
|
||||
- [VD-25 Server State Cache lifecycle](../architecture/decisions/VD-25-server-state-cache-lifecycle.md)
|
||||
- [VD-26 Persisted GraphQL operation](../architecture/decisions/VD-26-persisted-graphql-operation.md)
|
||||
- [VD-27 gRPC-Web unary와 server stream](../architecture/decisions/VD-27-grpc-web-unary-and-server-stream.md)
|
||||
- [VD-29 Connect-Web와 browser Protobuf runtime](../architecture/decisions/VD-29-connect-web-and-browser-protobuf-runtime.md)
|
||||
- [VD-30 Protobuf contract와 REST Gateway](../architecture/decisions/VD-30-protobuf-contract-and-rest-gateway.md)
|
||||
- [VD-13 Client cache scope와 persistence](../architecture/decisions/VD-13-client-cache-scope-and-persistence.md)
|
||||
- [VD-23 API transport selection과 REST execution](../adr/VD-23-api-transport-selection-and-rest-execution.md)
|
||||
- [VD-24 Runtime Schema와 boundary Mapper](../adr/VD-24-runtime-schema-and-boundary-mapper.md)
|
||||
- [VD-25 Server State Cache lifecycle](../adr/VD-25-server-state-cache-lifecycle.md)
|
||||
- [VD-26 Persisted GraphQL operation](../adr/VD-26-persisted-graphql-operation.md)
|
||||
- [VD-27 gRPC-Web unary와 server stream](../adr/VD-27-grpc-web-unary-and-server-stream.md)
|
||||
- [VD-29 Connect-Web와 browser Protobuf runtime](../adr/VD-29-connect-web-and-browser-protobuf-runtime.md)
|
||||
- [VD-30 Protobuf contract와 REST Gateway](../adr/VD-30-protobuf-contract-and-rest-gateway.md)
|
||||
- [VD-13 Client cache scope와 persistence](../adr/VD-13-client-cache-scope-and-persistence.md)
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user