루트 항목 하나를 옮기려면 코드 7곳의 루트 경로 목록을 같이 고쳐야 했다(복사 대상, 비밀값 검사 범위, 공급망 시험의 필수 입력, 이력 문서 검사, 규모 입력, vite 입력, TS 전용 규칙). 서로 다른 부분집합이고 한 곳에서 선언하지 않았다. 목록이 갈라져 공급망 생성이 깨진 적도 있다 (removal-fixture.ts 주석). 루트에는 JSON Schema 5개만 담은 `schemas/`가 `config/` 옆에 따로 있었다. `artifacts/`(출력 폴더)에는 사람이 쓴 수동 a11y 기록이, `config/hosting/`(호스트 계약)에는 시험 fixture가 섞였다. 고른 방법(design-docs repo-structure/04-frontend-layout.md 9.2절 3단계, 11절 R1·R2, 소유자 승인 2026-11-07): - `config/repository-layout.json`이 루트 항목마다 종류·역할·읽는 곳과 들어가는 목록(`sets`, 항목 안 경로는 `setPaths`)을 적는다. `scripts/lib/repository-layout.ts`가 읽고 검증한다. 6곳은 이름 붙은 집합을 고른다. JSON인 비밀값 검사 정책은 집합의 사본을 두고 시험이 같은지 본다(정책 파일은 릴리스 후보에 실려 형식을 바꾸지 않았다). 공급망 시험의 필수 입력 목록은 그 시험으로 대신한다. - `tests/unit/repository-layout.test.ts`: 등록부에 없는 루트 항목이 추적되면 실패(R1). 7곳이 등록부 모듈을 쓰고 루트 이름 둘 이상의 문자열 배열을 갖지 않는지(R2). - `schemas/artifacts/` → `config/schemas/artifacts/`, recipe 카탈로그 스키마 → `config/schemas/recipes/`. 정책 입력 순서(ASCII)에 맞춰 `config/schemas/`가 `config/security/` 앞에 온다. - 수동 a11y 기록 3개 → `docs/accessibility/route-reviews/`. `artifacts/`는 `.gitkeep`만 추적한다. 기록은 단위 시험이 읽어서 drill 사본에도 복사한다(`fixture-copy` 집합의 `docs/accessibility/route-reviews`). - `config/hosting/response-headers.fixture.json` → `tests/fixtures/hosting/response-headers.json`. 버린 것: 비밀값 검사 정책이 집합 이름을 참조하게 바꾸는 방법. 정책 파일은 릴리스 후보와 로컬 증거 평가가 읽는 형식이라 바꾸면 릴리스 증거 계약이 바뀐다. 루트 항목이 지워졌는데 등록부에 남는 경우는 시험하지 않았다. drill 사본은 일부만 복사해 그 방향을 볼 수 없다. 그런 항목은 그 집합을 쓰는 곳(복사, 비밀값 검사)에서 실패한다. 위험: 하네스 작업(fe-c)이 더할 `AGENTS.md`·`.claude/`를 미리 등록했다 (optional). 등록부가 이력 문서(`SPEC.md`)와 `CLAUDE.md` 이름을 적어서 이력 문서 검사에서 등록부 파일은 뺐다. 다운스트림은 자기 루트 항목을 등록부에 더해야 한다(CHANGELOG). CI 계약 기준선을 다시 받았다(a11y 기록 산출물 id·경로). 검증(desktop): 아래 4단계 커밋까지 쌓은 트리에서 test:unit, check:types, check:ci, lint, verify:documentation을 돌렸다(그 커밋에 적음). 이 커밋 단독으로 test:unit·check:ci·check:types를 돌렸다. Refs: design-docs repo-structure/04-frontend-layout.md 2.4·9.2·11절, README.md 3.4절
26 KiB
Optional frontend adapter recipes
이 문서는 도메인과 무관한 선택형 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/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 |
문서만 |
| 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는 빈 배열이며 12개 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 rendering behavior만 교체 | 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. 12개 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 |
| 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를
잇는 제품 소유 자리는 아직 없다.
- 제품 소유 파일
src/features/product-capabilities.ts의SERVICE_WORKER를ACTIVE로 바꾼다.scripts/build-frontend.ts가 worker 빌드를 추가로 돈다. 템플릿 파일src/features/installed-runtime-capabilities.ts는 그 선택을 검사하고 투영만 하므로 고치지 않는다. - 관측:
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안에서 읽는 코드가 없다. - 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가 확인한다. - 활성화 UI:
ServiceWorkerRuntimeHost.onUpdateWaiting을 구독하고, 사용자가 동의하면requestActivation()을 부른다(src/contracts/service-worker.ts). - reload 처리:
onReloadRequired를 구독해 reload를 안내한다. - 끄기·롤백·제거:
docs/operations/release-cache-rollback.md의 Service Worker 절차.service-worker.js는Cache-Control: no-cache로 서빙한다. - 실제 브라우저 검사:
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
policy와 removal source를 명시하며, foreground realtime이 선택됐다는 이유로
Web Push를 함께 설치하지 않는다.
4. 공통 구현 순서
- 문제를 vendor 이름이 아닌 capability와 측정값으로 기록한다.
- catalog의 trigger와 forbidden 조건을 모두 검토한다.
- project owner, security/privacy reviewer, gzip budget과 재검토 날짜를 VD-10 amendment에 기록한다.
- existing URL/local/context/query/application port로 해결되지 않는지 확인한다.
- 필요한 contract만
recipes에서 해당 application/presentation 경계로 복사해 실제 payload와 failure union으로 좁힌다. - concrete SDK는
src/adapters/...또는 local presentation facade adapter에서만 import한다. - composition root가 concrete adapter를 주입한다. page/use case가 constructor를 직접 호출하지 않는다.
- fake, unavailable, timeout/cancel, cleanup, malformed input, redaction과 integration test를 작성한다.
- runtime config schema, dependency inventory/approval, 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를 늘린다.
- 다른 origin의 realtime:
- 실제 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.v1WebSocket 어댑터는 그대로 연결되지 않는다. 지금 두 템플릿만으로 되는 경로는 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의 V3events[].payloadValidator(composedContractContributions.eventByType)와 checkpoint 응답의outputValidator를runtimeSchemaCodecFromValidator로 바꿔composeRuntimeSchemaCodecs로 합친다. event type의payloadSchemaId가 그 validator의schemaId와 같아야 등록된다. 같은 이벤트의 스키마를 V3events와 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 -> CLEANEDcommit authority를 가진다. - quota, corrupt row/manifest, migration checkpoint, worker crash, 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을 거절하고 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, pre-queue redaction, sampling, bounded 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 누락, unselected dependency, 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. 제거 체크리스트
- 신규 호출과 background 작업을 중지한다.
- subscription, worker, channel, media track, observer를 cleanup한다.
- persisted store/cache/event queue의 migrate 또는 purge 정책을 실행한다.
- composition registration과 runtime config를 제거한다.
- concrete adapter, facade/port와 vendor dependency를 제거한다.
- dependency baseline, SBOM과 bundle baseline을 갱신한다.
- typecheck/test/build, production bundle absence와 도메인 기능 fallback을 검증한다.
provider 장애 시 fake로 바꾸어 production을 PASS 처리하지 않는다. 문서화된
unavailable fallback만 사용하고 provider가 필수인 promotion은
FAIL_UNVERIFIED 또는 blocked 상태로 유지한다.