Files
clean-architecture-frontend…/config/recipes/frontend-capability-recipes.json
T
DongHyeonka e9e98b8aa7 Merge branch 'main' into claude/fe-b-docs-korean-645f55
정리 3·4단계 PR #14와 CI 재편 PR #16(main 38c0dc7d)을 받는다. 충돌은 아홉
파일이다. 이 브랜치가 한국어로 다시 쓴 문서에 두 PR이 영어 판에서 바꾼
것을 한국어로 넣었다.
- a11y 기록 경로 `artifacts/tests/a11y-manual/` → `docs/accessibility/route-reviews/`:
  README, docs/README.md, manual-checklist, starter-experience,
  ci-quality-gates. 문서 검사의 `NOT_DOCUMENT`도 새 경로로 바꿨다(정해진 영어
  키 형식의 게이트 입력이라 문서로 보지 않는다)
- ci-quality-gates.md: merge 단계 job 셋, 지운 CI 계약 기준선, main 단계
  FE-GATE-029의 `check:ci:gating`
- adapter 재검토 원장: 합친 음성 fixture script
- README 프로젝트 구조: `schemas/`는 `config/schemas/`로, `artifacts/`는
  `.gitkeep`만 추적, 최상위 항목 등록부 `config/repository-layout.json`
- verify-documentation-readiness.ts: #14의 배치 규칙 검사(R6·R7)와 이 브랜치의
  문서 체계 검사를 둘 다 둔다. R7의 「현재 문서」는 #14의 폴더 목록(옛
  `docs/superpowers/` 포함) 대신 문서 검사의 `checkedForDrift`로 고른다
- deletable-history-documents 시험: #14의 등록부 기반 경로와 이 브랜치의
  검사기 예외를 같이 둔다
- CHANGELOG: 범위 문장과 표 행을 둘 다 둔다
- 루트 등록부에서 SPEC.md 항목을 뺀다(그 항목이 「문서 체계 작업이 이력 폴더로
  옮기고 이 항목을 뺀다」고 적었다)
- #14가 옛 `docs/testing/frontend-platform-testing-strategy.md`를 고친 것이
  이름 바뀜을 따라 기록(docs/design/…)에 들어와서, 기록은 옮길 때의 글로 되돌렸다
2026-11-12 04:53:06 +09:00

341 lines
30 KiB
JSON

{
"$schema": "../schemas/recipes/frontend-capability-recipes.schema.json",
"schemaVersion": 1,
"decisionId": "VD-10",
"defaultStatus": "NOT_INSTALLED",
"productionRuntimeDependencies": [],
"catalogOwner": "frontend-platform",
"reviewOn": "project-capability-selection",
"vendorPackagePatterns": [
"@launchdarkly/*",
"@sentry/*",
"@opentelemetry/*",
"@openapitools/openapi-generator-cli",
"@reduxjs/toolkit",
"@tanstack/react-virtual",
"@uppy/*",
"firebase",
"idb",
"react-window",
"redux",
"socket.io-client",
"tus-js-client",
"workbox-window",
"xstate",
"zustand"
],
"recipes": [
{
"id": "realtime",
"status": "RECIPE_AVAILABLE",
"referenceRuntime": {
"status": "AVAILABLE_NOT_COMPOSED",
"coveredCapabilities": [
"transport에 묶이지 않는 event authority와 복구",
"상한이 있는 재연결 소유권",
"fetch 스트림 기반 SSE",
"상한이 있는 폴링(polling)",
"한 번에 하나만 쓰는(single-writer) live·폴링 전환",
"WebSocket 닫힌(closed) 프로토콜",
"Web Push window와 Service Worker 제어"
],
"sourceRoots": [
"src/application/ports/realtime",
"src/application/ports/out/web-push-control.ts",
"src/application/policies/bounded-polling.ts",
"src/contracts/realtime-events.ts",
"src/contracts/realtime-streams.ts",
"src/contracts/web-push.ts",
"src/adapters/realtime",
"src/adapters/web-push"
],
"conformanceScripts": [
"test:unit",
"check:realtime-boundaries",
"check:realtime-boundaries:fixture",
"check:optional-recipes",
"test:realtime-removal"
],
"productionComposition": false
},
"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": ["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": "상한이 있는 폴링, 또는 데이터가 오래되었음을 드러낸 UI.",
"removal": ["새 연결 수락(admission)을 끄고, 열린 reader·socket·poll lease·worker handler를 닫는다.", "소유한 Web Push 연결 정보(association)와 알림 상태만 철회하고 지운다.", "composition, registry, adapter, 선택한 vendor 의존성을 지운다.", "realtime 경계, runtime 제거, production 번들 gate를 돌린다."],
"serverStatePolicy": "query-cache-owned"
},
{
"id": "offline-indexeddb",
"status": "RECIPE_AVAILABLE",
"referenceRuntime": {
"status": "AVAILABLE_NOT_COMPOSED",
"coveredCapabilities": [
"IndexedDB",
"OPFS",
"StorageManager 용량 추정(estimate)/영속 저장(persistence)"
],
"sourceRoots": [
"src/application/ports/browser-file-storage/indexeddb-port.ts",
"src/application/ports/browser-file-storage/opfs-ports.ts",
"src/application/ports/browser-file-storage/storage-durability-port.ts",
"src/adapters/browser-file-storage",
"src/adapters/storage/indexeddb",
"src/adapters/storage/opfs"
],
"conformanceScripts": [
"test:unit",
"test:browser-capabilities",
"verify:browser-capability-evidence",
"check:browser-file-storage-boundaries",
"check:optional-recipes",
"test:browser-file-storage-removal"
],
"productionComposition": false
},
"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 (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": ["저장하는 모든 필드와 바이너리 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": "읽기 전용 또는 온라인 전용 query 경로. OPFS는 제품 정책이 승인할 때만 크기 상한이 있는 IndexedDB Blob으로 낮출 수 있다.",
"removal": ["쓰기와 백그라운드 migration을 멈춘다.", "동기화하지 않은 데이터를 맞추거나(reconcile) 내보낸다. 그다음 허가된 상한 있는 lifecycle 작업으로, governance에 묶인 소유 partition과 OPFS namespace만 지운다.", "모든 데이터베이스·channel·worker·파일 handle을 닫는다.", "repository composition과 의존성을 지운다."],
"serverStatePolicy": "reference-or-command-only"
},
{
"id": "service-worker-pwa",
"status": "RECIPE_AVAILABLE",
"referenceRuntime": {
"status": "AVAILABLE_NOT_COMPOSED",
"coveredCapabilities": [
"Cache Storage 공개 응답 관리"
],
"sourceRoots": [
"src/application/ports/browser-file-storage/cache-storage-ports.ts",
"src/adapters/browser-file-storage",
"src/adapters/cache-storage"
],
"conformanceScripts": [
"test:unit",
"test:browser-capabilities",
"verify:browser-capability-evidence",
"check:browser-file-storage-boundaries",
"check:optional-recipes",
"test:browser-file-storage-removal"
],
"productionComposition": false
},
"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": ["명시된 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": "hosting 캐시 헤더를 쓰는 일반 네트워크 application.",
"removal": ["등록 해제(unregister) migration을 배포한다.", "옛 worker가 제어하던 클라이언트가 모두 빠진 뒤, 파싱해 확인한 소유 캐시 namespace만 지운다.", "worker 등록, 캐시 metadata, manifest를 지운다."],
"serverStatePolicy": "network-cache-policy-only"
},
{
"id": "file-transfer",
"status": "RECIPE_AVAILABLE",
"referenceRuntime": {
"status": "AVAILABLE_NOT_COMPOSED",
"coveredCapabilities": [
"File",
"Blob",
"native 파일 input",
"시스템 파일 선택기",
"object URL 미리보기",
"다운로드 전달",
"presigned URL capability",
"상한이 있는 스트리밍 다운로드",
"multipart/이어 올리기(resumable) 업로드",
"지속되는, 비밀이 아닌 업로드 checkpoint",
"Image CDN 반응형 전달"
],
"sourceRoots": [
"src/application/ports/browser-file-storage/file.ts",
"src/application/ports/browser-transfer",
"src/adapters/browser-file-storage",
"src/adapters/browser-files",
"src/adapters/browser-transfer"
],
"conformanceScripts": [
"test:unit",
"test:browser-capabilities",
"verify:browser-capability-evidence",
"check:browser-file-storage-boundaries",
"check:optional-recipes",
"test:browser-file-storage-removal"
],
"productionComposition": false
},
"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": "메모리 파일/미리보기/다운로드 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": ["파일 이름, 확장자, 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": "접근성을 갖춘 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": "버전이 붙은 백엔드 계약이 있어, 생성된 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": ["인증된 출처에서 생성한다.", "생성기 실행과 출력을 검토한다.", "요청 본문을 로그에 남기지 않는다."],
"bundleBudgetGzipBytes": 16000,
"fallback": "기존의 타입 있는 요청 builder와 runtime 응답 스키마.",
"removal": ["손으로 쓴 gateway로 되돌린다.", "생성된 출력과 생성기를 지운다.", "공개 타입에 DTO가 남지 않았는지 확인한다."],
"serverStatePolicy": "query-cache-owned"
},
{
"id": "feature-flag",
"status": "RECIPE_AVAILABLE",
"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": ["flag는 힌트일 뿐 접근 제어가 아니다.", "targeting 속성을 최소로 둔다.", "개인 속성에는 동의 규칙을 적용한다."],
"bundleBudgetGzipBytes": 10000,
"fallback": "stale 판단을 명시한 타입 있는 로컬 기본값.",
"removal": ["출시를 영구히 확정한다.", "flag 키와 분기를 지운다.", "provider composition과 의존성을 지운다."],
"serverStatePolicy": "policy-cache-only"
},
{
"id": "web-worker",
"status": "RECIPE_AVAILABLE",
"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": ["worker 메시지를 검증한다.", "credential을 보내지 않는다.", "넘기는 데이터와 worker 수에 상한을 둔다."],
"bundleBudgetGzipBytes": 14000,
"fallback": "측정한 한도 안에서 나누거나 미룬 main thread 실행.",
"removal": ["worker를 멈추고 정리(dispose)한다.", "동기 facade 구현으로 되돌린다.", "worker entry와 chunk를 지운다."],
"serverStatePolicy": "no-server-state"
},
{
"id": "multi-tab",
"status": "RECIPE_AVAILABLE",
"trigger": "문서로 정한 workflow가 민감하지 않은 이벤트를 탭 사이에 맞춰야 한다.",
"forbiddenWhen": ["충돌 판정은 서버가 하는 것이 맞다.", "이벤트 버전과 출처 식별자가 정해지지 않았다."],
"boundary": "버전이 붙은 브라우저 이벤트 출력/입력 adapter",
"port": "MultiTabPort",
"fake": "FakeMultiTabAdapter",
"failureKinds": ["self-echo", "duplicate", "conflict"],
"lifecycleMethods": ["unsubscribe", "close"],
"owner": "project-owner-required",
"securityPrivacy": ["credential이나 개인 payload를 broadcast하지 않는다.", "버전을 검증한다.", "이벤트는 인가가 아니라 힌트로 다룬다."],
"bundleBudgetGzipBytes": 4000,
"fallback": "focus를 받으면 권위 있는 서버에서 다시 읽는다.",
"removal": ["channel을 닫는다.", "이벤트 registry 항목을 지운다.", "focus 기반 새로고침으로 되돌린다."],
"serverStatePolicy": "invalidation-only"
},
{
"id": "browser-permission",
"status": "RECIPE_AVAILABLE",
"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": ["명시적인 사용자 동작(user gesture)을 요구한다.", "요청 범위를 최소로 둔다.", "권한 허용을 인가로 저장하지 않는다."],
"bundleBudgetGzipBytes": 3000,
"fallback": "직접 입력, 또는 복사/다운로드 안내.",
"removal": ["얻은 자원을 멈춘다.", "권한 action과 adapter를 지운다.", "거부 경로의 접근성을 다시 시험한다."],
"serverStatePolicy": "no-server-state"
},
{
"id": "client-workflow",
"status": "RECIPE_AVAILABLE",
"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": ["명시적으로 분류한 workflow 필드만 저장한다.", "credential을 절대 저장하지 않는다.", "logout과 버전 변경 때의 초기화를 정한다."],
"bundleBudgetGzipBytes": 9000,
"fallback": "URL·component 상태·context·TanStack Query가 나눠 소유한다.",
"removal": ["남은 상태를 원래 맞는 owner로 옮긴다.", "facade와, 고른 store 의존성 하나를 지운다.", "logout/reset을 확인한다."],
"serverStatePolicy": "reference-only"
},
{
"id": "large-data-ui",
"status": "RECIPE_AVAILABLE",
"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": ["인가된 행만 렌더링한다.", "숨긴 행 데이터를 telemetry에 내보내지 않는다.", "접근성용 행 식별자를 유지한다."],
"bundleBudgetGzipBytes": 30000,
"fallback": "접근성을 갖춘 pagination과 상한 있는 결과 집합.",
"removal": ["pagination 기본 요소로 되돌린다.", "facade adapter와 의존성을 지운다.", "키보드·성능 검증을 돌린다."],
"serverStatePolicy": "query-cache-owned"
},
{
"id": "analytics-error-sink",
"status": "RECIPE_AVAILABLE",
"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)으로 관리한다.", "queue에 넣기 전에 가린다.", "동의·sampling·보존 정책을 적용한다."],
"bundleBudgetGzipBytes": 25000,
"fallback": "기존의 상한 있는 로컬 진단과 best-effort telemetry port.",
"removal": ["provider 전송을 끈다.", "정책에 따라 flush하거나 버린다.", "adapter, runtime config, 의존성을 지운다."],
"serverStatePolicy": "no-server-state"
}
]
}