Files
clean-architecture-frontend…/docs/architecture/optional-adapter-recipes.md
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

26 KiB

선택형 frontend adapter recipe

이 문서는 도메인과 무관한 선택형 frontend capability를 실제 프로젝트에 도입하는 실행 가이드다. 기본 스켈레톤에는 vendor runtime을 설치하지 않는다. RECIPE_AVAILABLE은 catalog에 복사해 좁힐 recipe가 있다는 availability 표시다. runtime 구현이나 제품 선택·조립 상태가 아니다. 현재 catalog의 product selection과 production composition은 별도로 NOT_SELECTED/미설치다. 일부 browser-native capability에는 dependency 없는 referenceRuntime.status=AVAILABLE_NOT_COMPOSED 구현이 함께 있지만, 이것도 제품 dataset·owner·policy가 정해져 bootstrap에 연결되기 전에는 설치된 기능이나 production readiness를 뜻하지 않는다.

1. 현재 상태와 파일 지도

항목 경로 production 포함
선택/금지/예산 SSOT config/recipes/frontend-capability-recipes.json 정책만
catalog JSON schema config/schemas/recipes/frontend-capability-recipes.schema.json 아니오
TypeScript port recipes/frontend-capabilities/contracts.ts 아니오
fake/unavailable recipes/frontend-capabilities/fake-adapters.ts 아니오
contract test tests/recipes/optional-capability-contracts.test.ts 아니오
file/IndexedDB/OPFS/Cache 심층 계약. reference runtime이 있는 port는 복사하지 않고 src/application/ports의 port를 다시 내보낸다([0929] 05-03) recipes/frontend-capabilities/browser-file-storage-contracts.ts 아니오
심층 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/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 문서만
transfer/CDN 복구 runbook template docs/operations/browser-transfer-recovery.md 문서만
browser-native reference runtime src/adapters/browser-files, src/adapters/browser-transfer, src/adapters/storage/indexeddb, src/adapters/storage/opfs, src/adapters/cache-storage composition 전에는 tree-shaken
reference runtime browser evidence tests/browser-capabilities 아니오
정적/번들 gate scripts/check-optional-recipes.ts build 도구
negative fixture scripts/check-optional-recipe-fixtures.ts 아니오
완전 제거 gate scripts/test-optional-recipe-removal.ts 아니오
native reference runtime 제거 gate scripts/test-browser-file-storage-runtime-removal.ts 아니오

현재 productionRuntimeDependencies는 빈 배열이며 카탈로그의 recipe 모두 선택되지 않았다. recipes/의 TypeScript example은 선택 시 복사하고 좁힐 출발점이고, src/adapters의 browser-native reference runtime은 공통 lifecycle·failure mechanism을 재사용할 수 있는 실제 구현이다. 제품 feature는 이 runtime에 schema/codec/query와 dataset 정책을 주입하고 더 좁은 facade 뒤에서 조립한다.

Reference runtime bundle budget

referenceRuntime이 있는 recipe는 catalog의 sourceRoots를 실제 budget entry로 사용한다. gate는 중첩 root의 실행 가능한 source를 중복 제거하고 경로순으로 정렬한 뒤, 모든 module을 하나의 synthetic entry에 포함한다. 이 entry는 Vite production mode, ES2022/ES module, esbuild minify로 build하며 tree-shaking을 명시적으로 끈다. 따라서 synthetic consumer가 호출 여부를 알 수 없다는 이유로 validation, quota, integrity, cleanup 같은 fail-closed guard가 예산에서 빠지지 않는다. 생성된 모든 chunk/asset의 Node zlib gzip byte 합계를 catalog의 bundleBudgetGzipBytes와 비교하고 결과와 SHA-256을 artifacts/quality/optional-recipes.json에 기록한다.

이 synthetic build는 설치 크기 상한을 검증하기 위한 것이며 product bootstrap에 runtime을 compose하지 않는다. 별도의 production manifest/module-inventory 검사는 선택되지 않은 runtime source가 실제 dist에 없는지 계속 검증한다.

예산 값은 config/recipes/frontend-capability-recipes.json이 정본이다. 정하는 규칙은 아래와 같다(2026-11-03, 리뷰 결정 0929/05-04).

  • 예산 = 측정값 + 3%를 100 B 단위로 올린 값.
  • 측정값의 3% 안에서 늘면 예산을 고치지 않는다.
  • 3%를 넘게 늘면 예산을 올리는 커밋 본문에 늘어난 이유를 적는다. 그때 다시 이 규칙으로 정한다.
  • 이유: 전에는 수정마다 100 B씩 올렸다. 그러면 한도가 늘 직전 측정값이라, 예산 초과가 "왜 커졌나"를 묻는 신호가 되지 못하고 수정마다 인상 커밋만 남았다.
  • 버린 대안: 레시피 예산에서 kernel(src/adapters/platform/ 등 공유 source)을 빼는 것. kernel이 커지는 것을 놓친다.

2026-11-03 측정(check:optional-recipes:source, 기준 d166aa3)으로 정한 값:

recipe 측정 gzip B 예산 gzip B
file-transfer 56,053 57,800
offline-indexeddb 37,327 38,500
realtime 40,902 42,200
service-worker-pwa 9,716 10,100

source가 예산을 넘으면 gate를 우회하지 않는다. output artifact와 늘어난 이유를 검토한 뒤 위 규칙으로 올린다.

2. 어느 경계에 두는가

capability 성격 port 소유자 adapter 방향 concrete 위치 예
application이 외부 결과를 요청 application outbound src/adapters/<capability>
URL/browser event가 의도를 전달 application input inbound src/presentation/adapters
React 렌더링 동작만 교체 presentation local facade src/presentation/<capability>
feature 전용 protocol feature application in/out 분리 src/features/<name>/adapters

WebSocket 연결 생성, reconnect와 credential attachment는 outbound다. 수신 JSON 검증과 application input 호출은 inbound다. Service Worker update event, BroadcastChannel event도 같은 원칙을 적용한다. generated DTO와 vendor SDK type은 facade 밖으로 노출하지 않는다.

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와 크기 제한이 있는 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
multi-tab 비민감 event 동기화가 필요 server가 conflict authority focus 시 authoritative refresh
browser permission user gesture 기반 기능 필요 boot 요청, denied UX 없음 manual input/instruction
client workflow cross-page client-only state가 실재 query/server state 복제 URL/local/context/query
large data UI 실측 scale이 budget 초과 pagination으로 충분, a11y 미정 accessible pagination
analytics/error sink provider·consent·retention 승인 arbitrary payload/redaction 우회 bounded local diagnostics

정확한 failure matrix, security/privacy, gzip budget과 제거 순서는 JSON catalog가 SSOT다. 문서와 catalog가 다르면 gate가 검사하는 catalog를 우선 고치고 이 표도 같이 갱신한다.

Service Worker를 켤 때 확인할 것(06-05). 템플릿은 1·6·7, 2의 시작 실패 이벤트, 2의 observe와 3을 제품 소유 파일에서 잇는 자리를 갖고 있다. 4·5를 잇는 제품 소유 자리는 아직 없다.

  1. 제품 소유 파일 src/features/product-capabilities.ts의 SERVICE_WORKER를 ACTIVE로 바꾼다. scripts/build-frontend.ts가 worker 빌드를 추가로 돈다. 템플릿 파일 src/features/installed-runtime-capabilities.ts는 그 선택을 검사하고 투영만 하므로 고치지 않는다.
  2. 관측: createRuntimeComposition이 텔레메트리 포트를 optional host에 넘긴다 (src/bootstrap/create-runtime-composition.ts). 시작 결과가 FAILED나 INCOMPATIBLE이면 service-worker.start.failed가 1건 남는다 (src/bootstrap/optional-runtime-host.ts). 실제 composition에서 첫 설치가 실패하면 이벤트가 1건 나가는 것은 tests/component/runtime-composition-service-worker-telemetry.test.ts가 확인한다. 템플릿이 연결하지 않은 것은 셋이다. 업데이트 설치 실패 (watchForUpdates, src/adapters/service-worker/service-worker-page-controller.ts)는 이벤트를 남기지 않는다. page controller의 observe는 제품이 src/bootstrap/product-composition.ts의 composeProduct에서 serviceWorker.observe로 돌려준다(1103/09-05). 템플릿 조립이 그것을 optional host에 넘기고, 던지면 무시한다. OptionalRuntimeHost.health()는 src 안에서 읽는 코드가 없다.
  3. blockers: 저장하지 않은 편집이 있는 탭이 활성화를 거절하게 composeProduct가 serviceWorker.blockers를 돌려준다. 하나가 true를 돌려주거나 던지면 requestActivation()이 BLOCKED_DIRTY_CLIENT로 거절한다. 템플릿 파일 src/bootstrap/create-runtime-composition.ts는 고치지 않는다. 실제 조립에서 두 값이 page controller에 닿는 것은 tests/component/runtime-composition-service-worker-product-wiring.test.ts가 확인한다.
  4. 활성화 UI: ServiceWorkerRuntimeHost.onUpdateWaiting을 구독하고, 사용자가 동의하면 requestActivation()을 부른다(src/contracts/service-worker.ts).
  5. reload 처리: onReloadRequired를 구독해 reload를 안내한다.
  6. 끄기·롤백·제거: docs/operations/release-cache-rollback.md의 Service Worker 절차. service-worker.js는 Cache-Control: no-cache로 서빙한다.
  7. 실제 브라우저 검사: tests/e2e/service-worker-update.spec.ts와 service-worker-recovery.spec.ts를 제품 구성으로 돌린다. helper는 이미 ACTIVE인 선택을 그대로 쓰고, 캐시 단언은 빌드가 만든 사전 캐시 목록과 비교한다. 준비 단계에서 실패하면 helper(tests/e2e/support/service-worker-builds.ts) 머리 주석의 전제 목록과 두 spec 머리 주석에서 바뀐 곳을 찾는다.

오프라인 셸(0929/06-03): reference 워커는 navigation을 가로채지 않는다 (service-worker-static-assets.ts navigation NETWORK_ONLY, service-worker-lifecycle.ts intercepts). 사전 캐시는 해시 이름의 assets/(src/contracts/service-worker.ts BUILD_ASSET_DIRECTORY)뿐이고 index.html은 넣지 않는다(scripts/generate-service-worker-assets.ts). public/에서 dist 루트로 복사된 PWA 아이콘 같은 파일은 이름이 해시처럼 보여도 넣지 않는다(1105/06-01). 설계가 cached index.html fallback을 금지한다(closed deep design 18.8). 오프라인 셸이 필요한 제품은 템플릿 워커를 켜는 것으로 얻지 못한다. 별도 제품 capability로 설계하고, 그때 넘겨받는 파일은 위 세 파일과 vite.service-worker.config.ts다. tests/e2e/service-worker-update.spec.ts의 사전 캐시 단언과 "HTML과 자산은 같은 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) 정책과 제거 source를 명시하며, foreground realtime이 선택됐다는 이유로 Web Push를 함께 설치하지 않는다.

4. 공통 구현 순서

  1. 문제를 vendor 이름이 아닌 capability와 측정값으로 기록한다.
  2. catalog의 trigger와 forbidden 조건을 모두 검토한다.
  3. project owner, security/privacy reviewer, gzip budget과 재검토 날짜를 VD-10 amendment에 기록한다.
  4. existing URL/local/context/query/application port로 해결되지 않는지 확인한다.
  5. 필요한 contract만 recipes에서 해당 application/presentation 경계로 복사해 실제 payload와 failure union으로 좁힌다.
  6. concrete SDK는 src/adapters/... 또는 local presentation facade adapter에서만 import한다.
  7. composition root가 concrete adapter를 주입한다. page/use case가 constructor를 직접 호출하지 않는다.
  8. fake, 사용 불가(unavailable), timeout/cancel, cleanup, 형식이 틀린 입력, redaction과 integration test를 작성한다.
  9. runtime config schema, 의존성 inventory/승인, SBOM, bundle budget, browser support와 runbook을 갱신한다. 운영 CSP(config/hosting/security-headers.json)도 여기서 넓힌다. 기본 CSP는 아래 기능을 막는다(리뷰 13-08).
    • 다른 origin의 realtime: connect-src에 wss://<realtime origin>을 더한다. https:는 wss:를 허용하지 않는다(CSP3 scheme 비교).
    • 파일 preview(src/adapters/browser-files/object-url-lease.ts의 object URL): img-src에 blob:을 더한다.
    • 이미지 CDN: img-src에 CDN origin을 더한다. 바꾼 CSP 아래에서 tests/e2e/production-csp.spec.ts가 그 기능의 화면을 열도록 smoke를 늘린다.
  10. 실제 provider integration과 negative behavior가 통과한 뒤에만 catalog 상태를 별도 project catalog에서 INSTALLED로 바꾼다.

5. capability별 필수 검증

Realtime

  • runtime schema로 envelope/version/event ID/sequence/timestamp를 검증한다.
  • reconnect는 exponential backoff 상한, visibility/offline 상태, auth refresh와 resume token expiry를 정의한다.
  • duplicate/out-of-order는 domain use case에 전달하기 전에 정책화한다.
  • route unmount/logout에서 unsubscribe하고 heartbeat timer를 종료한다.
  • SSE는 active document의 one-way stream, WebSocket은 duplex protocol, Web Push는 Service Worker가 받는 background notification hint, Polling은 visible/finite HTTP scheduling policy로 분리한다.
  • 기본 event 효과는 query namespace invalidation과 authoritative refetch다. gap, cursor expiry와 queue overflow에서는 delta 적용을 중단하고 snapshot으로 복구한다.
  • 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을 따른다. 현재 concrete runtime과 product selection은 없다.
  • 짝 백엔드 템플릿의 실시간 출구(STOMP-over-SockJS, NDJSON)와 이 repo의 SSE· realtime.v1 WebSocket 어댑터는 그대로 연결되지 않는다. 지금 두 템플릿만으로 되는 경로는 bounded polling이다. 대응표와 push를 고를 때의 세 길은 설계 문서 0.1절에 있다(1103/04-02).
  • realtime 레지스트리(createRealtimePolicyRegistry)가 받는 세 바인딩의 출처 (1103/04-06). 기능 모듈에는 codec·mapper를 낼 칸이 없으므로 조합 코드가 모은다.
    • apiOperations: loadInstalledFeatureRuntimeRegistries().apiOperations (projectApiOperationRows). snapshot·checkpoint operation이 여기서 온다.
    • schemaCodecs: 기능 contract contribution의 V3 events[].payloadValidator (composedContractContributions.eventByType)와 checkpoint 응답의 outputValidator를 runtimeSchemaCodecFromValidator로 바꿔 composeRuntimeSchemaCodecs로 합친다. event type의 payloadSchemaId가 그 validator의 schemaId와 같아야 등록된다. 같은 이벤트의 스키마를 V3 events와 realtime 등록 두 곳에 따로 쓰지 않는다.
    • mappers: 조합 코드가 BoundaryMapper(src/contracts/boundary-mapper.ts)를 쓰고 composeBoundaryMapperRegistry로 합친다. mapper의 inputSchemaId는 event type의 payloadSchemaId와 같아야 한다. 템플릿이 만드는 출처는 없다.
    • 기능 모듈에 칸을 더하는 것(V3 events에서 event type을 뽑거나 realtimeMappers 칸)은 위 대응표에서 push 경로를 고른 뒤 정한다. STOMP hint 경로면 delta mapper가 필요 없을 수 있다.

IndexedDB/OPFS

  • 기존 동기식 preference StoragePort에 넣지 않고 feature-specific async repository와 large-object port를 사용한다.
  • raw database/transaction/store/index/schema version은 adapter 밖으로 노출하지 않는다. request success가 아니라 transaction complete 이후에만 성공이다.
  • DDL schema와 record codec version을 분리하고 schema upgrade는 additive, data migration은 resumable bounded batch로 실행한다.
  • versionchange/blocked/future schema를 read-only/online-only 상태로 드러내며 자동 reload와 database 삭제를 금지한다.
  • OPFS는 immutable bytes만 소유하고 IndexedDB journal이 PREPARING -> FILES_READY -> COMMITTED -> CLEANED commit authority를 가진다.
  • 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가 아니다.
  • 인증 필요, cookie 의존, private, 개인 정보, no-store, opaque, redirect, 206 응답을 거절하고 query/Vary exact match를 보존한다.
  • candidate 전체의 type/size/integrity가 검증된 뒤에만 release를 활성화하고 verified previous release를 rollback용으로 유지한다.
  • stale worker loop를 막고 unregister와 parsed owned-cache cleanup을 별도 lifecycle로 검증한다.

File/Blob/picker/download, presigned transfer와 generated API

  • native File/Blob/handle은 transient adapter vault 안에 두고 application에는 opaque ref, untrusted metadata와 bounded range/chunk만 전달한다.
  • native input을 baseline으로 두고 system picker는 user activation 안에서만 progressive enhancement한다. dismissal은 failure가 아니다.
  • upload는 client MIME을 신뢰하지 않고 count/size/signature/server rejection, resumable session, part checksum/idempotency, quarantine을 다룬다.
  • presigned URL은 application에 raw URL로 노출하지 않고 in-memory identity capability로 보관한다. method/resource 또는 session-part/offset/length/checksum, expiry, origin/path/query/header를 정확히 묶고 data-plane fetch는 credential, redirect, referrer와 cache를 fail-closed 정책으로 제한한다.
  • resume는 IndexedDB checkpoint만 신뢰하지 않고 server status와 다시 선택한 source의 part digest를 대조한다. checkpoint에는 URL/query/signed header/token을 저장하지 않으며 explicit abort가 불명확하면 reconcile 전까지 유지한다.
  • progress는 unknown total을 허용하며 navigation/unmount에서 AbortSignal로 취소한다. server upload session은 별도 abort/TTL cleanup이 필요하다.
  • 큰 download는 single Uint8Array/Blob이 아니라 browser handoff 또는 backpressure stream을 사용하고 handoff와 confirmed save를 구분한다.
  • Image CDN은 raw transform URL builder가 아니라 opaque asset과 composition-registered preset으로만 responsive descriptor를 만든다. immutable revision, format/width/pixel/decode/cache/expiry와 CDN origin을 검증한다.
  • object URL은 explicit lease로 만들고 replacement/unmount에서 revoke한다.
  • generated code는 facade 뒤 DTO이며 runtime response schema와 contract drift gate를 유지한다.

Flag/worker/multi-tab/browser

  • flag unknown/unavailable/stale에서 명시적 typed fallback을 사용하고 access control로 사용하지 않는다.
  • worker는 task ID/generation/cancel을 사용해 stale result를 폐기하고 crash를 normalized failure로 바꾼다.
  • multi-tab은 source/event/version으로 self-echo와 duplicate를 막고 payload를 비민감 invalidation hint로 제한한다.
  • browser permission은 user gesture에서만 요청하고 denied/dismissed/unsupported를 서로 다른 UX 결과로 처리한다.

Client workflow/large data/analytics

  • workflow store는 server entity/collection을 복제하지 않고 query key나 ID 참조만 보관한다. logout/reset/version mismatch 정책을 테스트한다.
  • virtualization은 profiler와 production-like row count로 정당화하며 keyboard, focus restoration, screen reader와 stale row identity를 검증한다.
  • analytics는 essential diagnostics와 consent-required event를 분리하고 closed event/attribute registry, queue에 넣기 전 redaction, sampling, 크기 제한 queue와 retention을 적용한다.

6. 검증 명령

corepack pnpm check:types:test
corepack pnpm test:recipes
corepack pnpm test:browser-capabilities
corepack pnpm build
corepack pnpm check:optional-recipes
corepack pnpm check:optional-recipe-fixtures
corepack pnpm test:optional-recipe-removal
corepack pnpm test:browser-file-storage-removal

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 typecheck, architecture, test와 build를 실행한다. 별도 native-runtime removal gate는 browser file/storage source와 전용 test, catalog metadata를 제거한 임시 사본에서 typecheck, architecture, 전체 base test, build와 optional catalog 검사를 다시 실행한다.

7. 제거 체크리스트

  1. 신규 호출과 background 작업을 중지한다.
  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를 제거한다.
  6. dependency baseline, SBOM과 bundle baseline을 갱신한다.
  7. typecheck/test/build, production bundle absence와 도메인 기능 fallback을 검증한다.

provider 장애 시 fake로 바꾸어 production을 PASS 처리하지 않는다. 문서화된 unavailable fallback만 사용하고 provider가 필수인 promotion은 FAIL_UNVERIFIED 또는 blocked 상태로 유지한다.